From 9f7cc45e86985cdf522af7f5609aae1129169619 Mon Sep 17 00:00:00 2001
From: Joachim Hummel <jh@unixweb.de>
Date: Fri, 26 Jun 2026 17:44:24 +0200
Subject: [PATCH] update README and add CLAUDE.md

Mark linux_apt-upgrade.yaml as work-in-progress in README, add dedicated section for it. Add CLAUDE.md with repo architecture guidance.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  9 ++++++++
 2 files changed, 72 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..86cb82e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+A collection of Kestra workflow flows (YAML) and helper scripts (Python) for homelab automation. The flows run inside Kestra and use this Git repository as the source for versioned logic.
+
+**Core separation of concerns:**
+- `*.yaml` — Kestra flows (orchestration, task sequencing, SSH commands)
+- `*.py` — Python scripts called at runtime by Kestra (data processing, transformation)
+- `.env` — Secrets and credentials, never committed (see `.env.example`)
+
+## Testing the Python script locally
+
+```bash
+export OPTIONS_B64_JSON='["WyJkb2NrZXIxOzE5Mi4xNjguMTAwLjEwO21laW51c2VyOy9ob21lL21laW51c2VyL2RvY2tlci9uZXh0Y2xvdWQiXQ=="]'
+python3 build_select_options.py
+cat select_options.json
+```
+
+The script reads `OPTIONS_B64_JSON` (a JSON array of base64-encoded per-host results) and writes `select_options.json`.
+
+## Architecture: how flows use Python scripts
+
+The `docker_stack_inventory_scan` flow does **not** bundle the Python script inline. Instead, it clones this Git repo at runtime via `io.kestra.plugin.git.Clone` inside a `WorkingDirectory` task, then finds and runs `build_select_options.py` dynamically using `find`. This means:
+- Changes to `.py` files take effect on the next flow run without redeploying the flow
+- The flow variable `git_repo_url` and `git_branch` control which repo/branch is used
+
+## Kestra secrets
+
+Secrets are referenced in flows as `{{ secret('SECRET_NAME') }}`. For Kestra OSS, secrets must be stored base64-encoded in `.env` with the `SECRET_` prefix:
+
+```bash
+# Encode a value
+echo -n "my-secret-value" | base64 -w 0
+
+# Encode an SSH private key
+base64 -w 0 ~/.ssh/id_ed25519
+```
+
+Then in `.env`:
+```env
+SECRET_SSH_PRIVATE_KEY=base64_encoded_value
+```
+
+## KV-Store data format
+
+The `docker_stack_inventory_scan` flow writes to the KV key `docker_stack_select_options`. Each entry is a semicolon-delimited string:
+
+```
+hostname;ip-address;ssh-user;/path/to/compose-dir
+```
+
+The `docker_hosts` variable in the flow uses the same `hostname;ip-address` format.
+
+## Flow namespaces
+
+All flows use the `homelab.docker` namespace.
+
+## Compose file discovery
+
+The SSH scan uses `find -maxdepth 2` under `base_dir`. Compose files must be named exactly `compose.yml`, `compose.yaml`, `docker-compose.yml`, or `docker-compose.yaml` and located at most 2 levels deep to be detected.
diff --git a/README.md b/README.md
index b02d16c..bf07eb6 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@ Aktuell enthalten:
 
 * `docker_stack_inventory_scan.yaml`
 * `build_select_options.py`
+* `linux_apt-upgrade.yaml` *(in Arbeit)*
 * `.env.example`
 
 Der erste Flow scannt mehrere Docker-Hosts per SSH, sucht nach Docker-Compose-Stacks und schreibt daraus eine Dropdown-Liste in den Kestra KV-Store.
@@ -71,6 +72,14 @@ Diese Datei wird anschließend vom Kestra-Flow in den KV-Store geschrieben.
 
 ---
 
+### `linux_apt-upgrade.yaml` *(in Arbeit)*
+
+Kestra-Flow zum Ausführen von `apt update && apt upgrade` auf einem Linux-Server per SSH.
+
+> **Hinweis:** Dieser Flow befindet sich noch in der Entwicklung und ist noch nicht vollständig implementiert.
+
+---
+
 ### `.env.example`
 
 Beispiel-Datei für benötigte Umgebungsvariablen und Secrets.