stack/AGENTS.md

# Agent notes (arr-stack)

## Project specification (read first)

| File | Audience |
|------|----------|
| **`specification.json`** | Coding agents / tools — structured index of the whole stack |
| **`specification.html`** | Humans — same content, readable |

**Do not edit those two files by hand.** Update `scripts/generate-specification.py` (`SPEC` dict), then run:

```bash
./scripts/generate-specification.py
```

Commit **both** outputs together so they stay in lockstep. Prefer JSON over HTML for agent context.

## Git

- Remote: `origin` → `ssh://git@192.168.8.123:2222/tim/stack.git` (Forgejo `tim/stack`)
- After any meaningful change set: **commit and push** to `main` with a clear, complete-sentence message (what changed and why).
- Never commit secrets: `.env`, `wireguard/wg0.conf`, `config/`, GGUF models, `ansible/.secrets/`.
- Prefer SSH push (`GIT_SSH_COMMAND` with `~/.ssh/id_ed25519` if needed).
- Server checkout: `/opt/stack` is the same repo (`git pull` on ser5). Ansible uses `stack_deploy_method: git`.
- Prefer **`.env`** for config (see `.env.example`). Demo creds: `DEMO_USER=tim` `DEMO_PASS=asdfasdf`. Fresh host: `./scripts/bootstrap-stack.sh`.
- Secrets live in `secrets/.env` (gitignored). After edits: see **quickstart.md → After changing secrets** (Usenet → `configure-usenet.sh`; Cloudflare → `render-cloudflare-ddns-env.sh` + recreate container; NZBgeek → Prowlarr UI; WireGuard → `wg0.conf` + gluetun recreate/watch).
Document agent convention: commit and push to Forgejo after changes Keeps the stack repo on the home Forgejo instance in sync when the coding agent edits the project. 2026-07-22 06:32:54 -07:00			`# Agent notes (arr-stack)`

Add paired specification.json and specification.html generator Single SPEC source regenerates machine-readable JSON for agents and dark HTML for humans so architecture survives lost chat sessions. 2026-07-22 19:54:42 -07:00			`## Project specification (read first)`

			`\| File \| Audience \|`
			`\|------\|----------\|`
			\| `specification.json` \| Coding agents / tools — structured index of the whole stack \|
			\| `specification.html` \| Humans — same content, readable \|

			Do not edit those two files by hand. Update `scripts/generate-specification.py` (`SPEC` dict), then run:

			```bash
			`./scripts/generate-specification.py`
			```

			`Commit both outputs together so they stay in lockstep. Prefer JSON over HTML for agent context.`

Document agent convention: commit and push to Forgejo after changes Keeps the stack repo on the home Forgejo instance in sync when the coding agent edits the project. 2026-07-22 06:32:54 -07:00			`## Git`

			- Remote: `origin` → `ssh://git@192.168.8.123:2222/tim/stack.git` (Forgejo `tim/stack`)
			- After any meaningful change set: commit and push to `main` with a clear, complete-sentence message (what changed and why).
			- Never commit secrets: `.env`, `wireguard/wg0.conf`, `config/`, GGUF models, `ansible/.secrets/`.
			- Prefer SSH push (`GIT_SSH_COMMAND` with `~/.ssh/id_ed25519` if needed).
Make /opt/stack a Forgejo git checkout instead of rsync-only Prefer stack_deploy_method=git: init/fetch on the server, register an SSH deploy key with Forgejo, and leave local secrets untracked. Document git pull for day-to-day updates; keep rsync as an opt-in fallback. 2026-07-22 11:12:07 -07:00			- Server checkout: `/opt/stack` is the same repo (`git pull` on ser5). Ansible uses `stack_deploy_method: git`.
Centralize demo config in .env and add bootstrap-stack.sh Expand .env.example with ports, AI, Usenet, WireGuard, demo logins, and bootstrap flags. One script creates dirs, downloads the model, starts compose, heals gluetun, and configures SABnzbd from the same file. 2026-07-22 13:06:08 -07:00			- Prefer `.env` for config (see `.env.example`). Demo creds: `DEMO_USER=tim` `DEMO_PASS=asdfasdf`. Fresh host: `./scripts/bootstrap-stack.sh`.
Document all post-secret-change update procedures Add a single quickstart table covering Cloudflare DDNS, Usenet, NZBgeek, WireGuard, stack .env, and bootstrap; point secrets/.env.example and AGENTS.md at the same workflow. 2026-07-22 19:48:56 -07:00			- Secrets live in `secrets/.env` (gitignored). After edits: see quickstart.md → After changing secrets (Usenet → `configure-usenet.sh`; Cloudflare → `render-cloudflare-ddns-env.sh` + recreate container; NZBgeek → Prowlarr UI; WireGuard → `wg0.conf` + gluetun recreate/watch).