# AGENTS.md

Project context for AI coding agents (Codex, Antigravity, and any agent that reads `AGENTS.md`).

**The canonical instructions for this repo live in [`CLAUDE.md`](CLAUDE.md). Read it first** — this
file is a thin pointer plus the must-know essentials so nothing is missed if the reference isn't
chased. Global cross-project rules (identity, Obsidian vault as source of truth, Gitea-first) come
from your tool's user-level instructions (`~/.codex/AGENTS.md` / `~/.gemini/GEMINI.md`).

## Essentials (full detail in `CLAUDE.md`)

- **What this is:** deployment config for a live, single-host Docker homelab on a headless
  **EndeavourOS (Arch)** server reachable at `ssh ginnoir@valhalla` — `pacman`, not `apt`.
  ~50 containers in per-domain Portainer-managed stacks. This is **not** application code.
- **The repo is canonical.** Portainer polls `main` every 5 min and redeploys any app stack whose
  `stacks/<domain>/*` files changed. Editing here changes nothing until you `git push`.
- **Deployment channels:**
  - `stacks/<domain>/*` → git push to Gitea → Portainer polls every 5 min and redeploys that stack. GitHub is a temporary mirror only.
  - `Caddyfile` → git push → Gitea Actions (`.gitea/workflows/deploy-caddy.yml`) copies it + reloads Caddy. Fallback: `apply-compose.ps1 -Caddy`.
  - `portainer-compose.yml` / `vault.hcl` → `apply-compose.ps1 -Portainer` (Portainer can't manage itself).
- **Portainer app stacks must have empty UI environment variables.** All config comes from `stack.env` via `env_file: stack.env`. Run `scripts/check-portainer-stack-env.ps1` before pushing.
- **famapp images** build on Gitea Actions (`v*` tags) and push to `registry.ginnoir.com/ginnoir/famapp`.
- **Secrets are committed intentionally.** `.env` and `stacks/*/stack.env` are versioned in this
  PRIVATE repo. Do **not** scrub or gitignore them.
- **Line endings:** `.gitattributes` forces LF. Never push CRLF (especially `stack.env`) — stray
  `\r` breaks values on the Linux host.
- **Networks:** `edge` is the only reverse-proxy network (Caddy + anything it proxies); `<domain>`
  nets are per-stack private. Caddy upstreams use container name + container-internal port.
- **Live ops:** there is no `dc` alias — address services by container name with plain `docker`
  over SSH, or use the `portainer` MCP server.

See `CLAUDE.md` for the on-host topology, "adding a service" steps, Caddyfile/TLS details, and the
full list of known quirks.