docs: migrate workflow to DooPlex-local execution

2026-07-19 12:16:52 +02:00
parent 13af252907
commit ee48a48288
7 changed files with 250 additions and 67 deletions
@@ -0,0 +1,118 @@
+<!-- VERSIONED COPY. The LIVE file is /mnt/5_hdd/felhom.eu/git/CLAUDE.md on DooPlex (it is not
+     inside any repo, so it is mirrored here to be versioned and restorable). Keep the two in
+     sync when either changes. -->
+
+# CLAUDE.md — `/mnt/5_hdd/felhom.eu/git` workspace root (DooPlex)
+
+## What this workspace is
+
+`/mnt/5_hdd/felhom.eu/git` is a parent folder holding the felhom sibling repos. Most are one logical
+product — **Felhom**, a managed home-server service for Hungarian households — spread across several
+repos. (Any non-felhom repo is unrelated; ignore unless asked.)
+
+**Claude Code runs HERE, on DooPlex (192.168.0.180), as `kisfenyo`.** Builds are local commands; the
+Proxmox host is one SSH hop (`ssh felhom-pve`). The Windows workstation is no longer the
+orchestration point and its trees are stale — see "Legacy: Windows workstation" at the bottom.
+
+Run CC inside tmux so sessions survive SSH drops: **`tmux new -A -s cc`**.
+
+## This host is production infrastructure
+
+DooPlex runs Gitea, the container registry, k3s + Longhorn, PBS, and the hub. Treat it accordingly:
+
+- NEVER run `docker system prune`, `docker image prune -a`, or any global Docker cleanup here.
+- NEVER touch k3s data dirs, Longhorn mounts, PBS datastores, or Gitea storage. Workspace is
+  `/mnt/5_hdd/felhom.eu/` — stay inside it plus `~/build` symlinks/dirs.
+- Destructive disk/guest operations belong to felhom-pve via the agent — never on this host.
+- Do not run Claude Code with permission prompts disabled on this host.
+- Watch disk headroom before large builds: `df -h /mnt/5_hdd /` — abort if either is >90%.
+
+## The Felhom system (three-component model, Proxmox-based)
+
+- **Hub** — operator backend on k3s (`hub.felhom.eu`). Lives in `felhom.eu/hub/`.
+- **Host agent** — one per Proxmox host, operator-tier, owns all Proxmox interaction. Repo `felhom-agent/`.
+- **In-guest controller** — one per customer LXC, Docker-only. Repo `felhom-controller/`.
+
+Other felhom repos: `app-catalog-felhom.eu/` (app templates), `homelab-manifests/` (DooPlex k3s).
+
+**Authoritative design docs (read these before designing anything):** `felhom.eu/documentation/architecture/01..05-*.md`, `felhom.eu/documentation/proxmox-platform.md`, `felhom.eu/documentation/tests/phase{0,1-2,3,4}-findings.md`.
+
+## Per-repo guidance
+
+When you work in a repo, read its `CLAUDE.md` (it loads on-demand the moment you touch a file there):
+- `felhom-agent/CLAUDE.md` — the Go host agent.
+- `felhom.eu/CLAUDE.md` — hub + website + manifests + the architecture docs.
+- `felhom-controller/CLAUDE.md` — the in-guest controller.
+
+## Skills
+
+Four Felhom skills exist (personal scope, `~/.claude/skills/`): **`felhom-build-deploy`** (all
+build/deploy/publish runbooks), **`felhom-ui-design`** (design-system v2 tokens/rules/gates),
+**`felhom-testing`** (non-hollow tests + red-proofs + seams), **`felhom-app-catalog`** (catalog
+authoring workflow). Source of truth: `felhom.eu/skills/`; install/update with
+`python3 felhom.eu/scripts/install_skills.py` (symlink — repo edits are live immediately).
+
+## Artifact taxonomy (READ THIS — it prevents the "what do I do?" stall)
+
+The planning/architecture assistant (in claude.ai, "project Claude") produces files with distinct roles. **A file being open in the editor is NOT an instruction. If no task is stated, ask.**
+
+- **`TASK.md` / `TASK-*.md`** — a spec for **you (Claude Code) to implement**. Implement it when it is placed as `TASK.md` at a repo root, or when explicitly told "implement <file>". Then push, update `CHANGELOG.md`, and write the repo's `REPORT.md`.
+- **`RUNBOOK-*.md`** — an operational procedure. CC executes the steps it has access and capability for, including live validation on the demo nodes and the demo Proxmox host (CC has root@felhom-pve SSH + the felhom-agent token). A step is human-only only when it genuinely needs physical presence, a real-world decision, or credentials CC truly lacks — mark those steps HUMAN. Do not decline a whole procedure because it touches a live host or a privileged token. (Judgment still applies: confirm before irreversible ops on real customer data — but demo scratch guests are fair game.)
+- **Validation/review** — checking a push against a spec's criteria is **project Claude's** job, not yours, unless asked.
+
+## Shared conventions
+
+- **Push to `main` directly** — no feature branches.
+
+> **Clean-tree gate before any build:** `git status --porcelain` must be empty and
+> `git rev-parse HEAD` must equal `git rev-parse origin/main` in the repo being built. An unpushed
+> change does not exist — never build a dirty or unpushed tree. The `git pull` in the build step
+> stays (it is a no-op when you work in this tree, and load-bearing if anything was pushed from
+> elsewhere).
+
+> **In every repository where you make a change, update both files in that repo:**
+> - **`CHANGELOG.md`** — a cumulative log of **all** changes; newest entry on top.
+> - **`REPORT.md`** — **overwrite** with a summary of the **most recent** implementation (or significant validation/operational run) only; not cumulative.
+>
+> **Never write secrets** — tokens, passwords, private keys, API keys — into `CHANGELOG.md`, `REPORT.md`, or any committed file. Reference them as "stored out-of-band" instead.
+
+- **Versioning** is via build-time ldflags (`-X main.version`/`-X main.Version`); bump on meaningful changes + add a CHANGELOG entry.
+- Code quality: double-check for bugs/edge cases; add debug logging; **ask rather than guess** when you'd otherwise need to invent input or output.
+
+## Live validation — no browser here
+
+**`claude-in-chrome` is NOT available on DooPlex.** The standard method is endpoint-level: invoke the
+exact endpoint the UI invokes (no server logic is skipped, only rendering) and say which method was
+used. Strict end-to-end UI coverage is a manual click-through by the operator.
+
+## Access
+
+Local (this host): repos `/mnt/5_hdd/felhom.eu/git/<repo>`, build dirs
+`/mnt/5_hdd/felhom.eu/build/felhom-{controller,hub,agent}`, `sudo kubectl`, Go toolchain, Docker
+build+push to `gitea.dooplex.hu/admin/`.
+
+| Host | Access | Use |
+|---|---|---|
+| **DooPlex (this host)** | local — Debian 13, `kisfenyo`, `/mnt/5_hdd/felhom.eu/` | build/push images, `sudo kubectl`, build+run the agent for tests |
+| Demo Proxmox host `demo-felhom` | `ssh felhom-pve` (root@192.168.0.162, no sudo) | pveum/pct + live Proxmox validation |
+| Demo guest 9201 | `ssh felhom-pve "pct exec 9201 -- ..."` | the live demo controller |
+| felhotest (legacy) | `ssh -p 33022 kisfenyo@router.abonet.hu` | OLD /opt/docker compose mechanism |
+
+The demo Proxmox host key changes on reprovision (N100) → refresh with
+`ssh-keygen -R 192.168.0.162` then connect with `-o StrictHostKeyChecking=accept-new`
+(`ssh-keyscan` hangs — avoid it).
+
+## Legacy: Windows workstation
+
+Kept so the old environment can be revived; **not the current setup**.
+
+- Repos were in `E:\git\` (`/e/git/` in Git Bash); this file lived at `E:\git\CLAUDE.md`.
+- **SSH binary had to be** `SSH=/c/Windows/System32/OpenSSH/ssh.exe` — Git Bash's `/usr/bin/ssh`
+  lacks access to the Windows SSH Agent and fails silently. Every remote command was
+  `$SSH kisfenyo@192.168.0.180 "..."`; details in `felhom-controller/docs/vscode-ssh-fix.md`.
+- `pct exec` over SSH needed `export MSYS_NO_PATHCONV=1` (MSYS mangled `/`-paths).
+- Agent deploy was a two-hop copy: build on 180 → `scp` to the Windows box (local path needed
+  `cygpath -w`) → `scp` on to felhom-pve. Beware CRLF when scp-ing config files through Windows.
+- Skills were installed as Windows junctions (`mklink /J`) rather than POSIX symlinks.
+- `claude-in-chrome` browser automation WAS available there (attaching only to sessions started
+  after the bridge connected).