docs: documentation policy — every change lands in the Void wiki AND git

Standing rule: no work is done until it's documented in both the Void wiki
(page API) and git (code + spec/plan/CHANGELOG), pushed to Gitea. Verbose-first;
consolidate later.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
root
2026-06-08 21:53:23 +10:00
parent a042cbaaa5
commit 555a4c652c

24
AGENTS.md Normal file
View File

@@ -0,0 +1,24 @@
# Agent working agreement — Void / homelab
## Documentation policy (standing rule — do not skip)
**Every change, decision, fix, or incident must end up documented in BOTH places before the work is considered done:**
1. **The Void wiki** — the `wiki` space served by the Void. Update the relevant existing page, or create one. This is the human-facing source of truth and what `infra_audit` reads.
2. **Git** — the code plus an appropriate written artifact (a spec/plan under `docs/superpowers/`, a `CHANGELOG.md` entry, and/or a doc page), committed and **pushed** to Gitea.
Capture **verbose-first** — we consolidate/compress later. Losing information is the only failure mode; over-documenting is fine. Do this proactively as part of finishing a task, not only when asked.
### How — wiki
Owner token: `OWNER_TOKEN` in `/opt/void-server/.env` on CT 311 (`void-app`, `192.168.1.216`). API on the LAN at `http://192.168.1.216:3000`:
- Edit a page: `PATCH /api/pages/:id` with `{ "body_md": "…", "title": "…" }`
- Create a page: `POST /api/spaces/2201a3dd-2d40-425c-a4cf-7f18882a9146/pages` with `{ "slug", "title", "body_md", "parent_id" }`
- Per-LXC / per-service pages parent under **Hosts & Services** (`ab398d61-805a-46dd-b1ba-6f09374bd7aa`).
- **Do not** write a contiguous `IP:port` for a remote-site or inactive host — `infra_audit` probes those and will false-flag them.
### How — git
Commit code + docs together and push to the project's Gitea repo:
- `void-v2``Hynes/Void-Homelab`
- `farm-timelapse``Hynes/farm-timelapse`
Specs/plans live in `docs/superpowers/{specs,plans}/`; user-facing changes get a `CHANGELOG.md` entry.