# AGENTS.md

Codex working notes for this repository. These instructions apply to the whole
repo unless a more specific `AGENTS.md` exists deeper in the tree.

Infrastructure-as-code for a self-hosted homelab on Proxmox VE 9.1: Docker Compose stacks, setup docs, automation scripts - not application code.

## Key Directories

- `compose/` - all Docker Compose stacks; also read `compose/CLAUDE.md` before editing there
- `docs/` - published MkDocs portfolio site; also read `docs/CLAUDE.md` before editing there
- `brand/` - the written brand: tokens, the Mark, and the only committed copy of the self-hosted fonts (`brand/BRAND.md`)
- `claude/output-styles/` - Claude Code output styles, symlinked into `~/.claude/output-styles/` (system-prompt-level behaviour rules; see `docs/other/claude-output-style.md`)
- `ansible/` - a K3s cluster config-rétegének IaC leírása (k3s-io/k3s-ansible collection; részletek `ansible/README.md`)
- `k8s/` - a K3s cluster **tartalmának** IaC leírása, Argo CD app-of-apps (részletek `k8s/README.md`). A k3s verziófrissítés is itt megy: `k8s/manifests/system-upgrade/plans.yaml`, két `version:` mező + push. **2026-08-28 óta fut rajta workload** (Forgejo, `k8s/manifests/forgejo/`; Umami analitika 2026-08-31 óta, `k8s/manifests/umami/`), tehát a clustert érintő műveletek már nem ingyenesek: van élő PVC és Longhorn kötet
- `scripts/restore-test.sh` - weekly restic restore verification, `scripts/k3s-backup.sh` - daily gpg-encrypted K3s control-plane backup, `scripts/longhorn-restore-test.sh` - on-demand Longhorn restore proof, `scripts/k3s-restore-test.sh` - on-demand control-plane restore proof into a throwaway k3s (see `scripts/README.md` for the full backup layout)
- `overrides/` - MkDocs Material theme override; exists only to carry the Umami `<script>` tag, which needs a `data-*` attribute no MkDocs config key can express
- `private/` - gitignored personal files (never commit); `private/todo.md` = planned tasks

## Infrastructure Overview

| Host | IP | Role |
|---|---|---|
| pve (Proxmox 9.1, HP EliteDesk 800 G4) | 192.168.0.109 | hypervisor |
| LXC 100 docker-host | 192.168.0.110 | 26 Compose stacks from this repo, plus the host-local `rails-lab` |
| VM 101 haos | 192.168.0.202 | Home Assistant OS |
| LXC 102 adguard | 192.168.0.111 | DNS |
| LXC 103 vaultwarden | 192.168.0.219 | passwords (Alpine, `pct exec` only) |
| LXC 105 komodo | 192.168.0.105 | GitOps deploy, port 9120 (Alpine) |
| LXC 106 karakeep / 107 n8n | .128 / .112 | apps |
| LXC 109 claude-mgmt | 192.168.0.204 | this machine, tmux persistent `claude` session, code-server (Tailscale-only, :8443) |
| LXC 110 caddy | 192.168.0.208 | Caddy reverse proxy (Alpine) |
| LXC 113 agentos | 192.168.0.71 | Hermes + Odysseus agentic OS |
| LXC 114 pocket-id | 192.168.0.114 | OIDC SSO, `pocketid.lan` (Alpine, `pct exec` only) |

Storage: MergerFS 8.1TB + SnapRAID (4 USB HDDs). Remote: Tailscale (private) + Pangolin on Hetzner VPS (public). Backups: Restic (local + NFS). K3s: 3x Dell OptiPlex (192.168.1.101-103, separate location, kubectl from this LXC).

## LXC Access

- Most LXCs: `ssh root@<ip>`; community-script containers (e.g. 103): `pct exec <id> -- bash` from pve, no SSH
- Always `cat /etc/os-release` first - Alpine uses `apk` + `rc-service`, not `apt` + `systemctl`

## Rules

- **Never `git push` unless explicitly asked.** Commit locally freely.
- Use Context7 MCP proactively for any library/framework/CLI question - `resolve-library-id` then `query-docs` before answering.
- Never rely solely on training knowledge for technical questions - search or inspect current docs first for versions, pricing, and third-party configs.
- Never use em dashes; use plain hyphens.
- Everything committed is English: commit messages (subject and body), code comments, YAML comments. The conversation language follows the user; the repo does not.
- `.env` and `private/` are gitignored - never commit them; keep `.env.example` updated.
- Docs/commits: redact API keys with placeholders; private LAN IPs (192.168.0.x) are NEVER redacted.
- A compose stack that builds its own image (`build:`) needs `pull_policy: build` on the service. Komodo deploys with `docker compose up -d`, which does not rebuild a service whose image already exists, so the stack pulls the new code and then recreates the container from the old image. Found on the first pedikur deploy: seventeen commits pulled, container running the image built at the first one.

## Codex Workflow

- Start by checking `git status --short` and avoid overwriting unrelated local changes.
- Prefer `rg` / `rg --files` for repo discovery.
- Use `apply_patch` for manual file edits when sandboxing permits it; otherwise use the smallest equivalent patch command.
- Keep changes scoped: this repo is infrastructure documentation and deployment config, not an application codebase.
- When changing compose stacks, validate YAML where possible and preserve existing deployment conventions.
- When changing docs, keep MkDocs navigation and `docs/README.md` in sync.
- Leaving a file out of `nav` does not keep it off the published site: MkDocs still builds it, lists it in `sitemap.xml` and indexes it for search. Internal material under `docs/` belongs in `exclude_docs` in `mkdocs.yml`.
- When adding or removing a compose stack, rebuild the `landing` stack on the VPS; its published stack count is baked in at build time.
- After editing `compose/proxmox-lxc-100/topology/nodes.yml`, the rebuilt `dist/index.html` must also be copied to `compose/vps/landing/src/topology/index.html`, and `topology.png` re-exported. Five steps total, listed in `compose/vps/landing/README.md`. Nothing enforces this; a missed copy publishes a stale map at homelabor.net/topology/.