felhom.eu/documentation/runbooks/workspace-CLAUDE.md

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).

Memory

The accumulated project memory (119 files) migrated from the Windows workstation lives at /mnt/5_hdd/felhom.eu/git/.claude-memory/, surfaced to Claude Code via ~/.claude/projects/-mnt-5-hdd-felhom-eu-git/memory (symlink). MEMORY.md there is the index. Memories reflect what was true when written — verify a named file/flag still exists before acting on it.

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 ". 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).