chore: bootstrap agent-ready docs and rules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/DECISIONS.md

@@ -0,0 +1,50 @@
+# Decisions
+
+Append-only. Never edit or delete an entry — supersede it with a new one that links back.
+One entry per decision a future maintainer would otherwise have to reverse-engineer.
+No index: `grep -n '^## ' docs/DECISIONS.md` lists every entry (date, title, line number).
+
+## 2026-10-23 — Mockups are committed and served, not throwaway
+**Status:** accepted
+**Context:** The agent-repo playbook keeps mockups gitignored in `design/mockups/`, never wired into the app.
+Spec 001 asks for 7 design-direction mockups that run in the Docker image for the maintainer to compare.
+**Decision:** (maintainer decision) Mockups live in `src/mockups/NN-slug/`, are committed, served by the
+Bun server and covered by route smoke tests. Mockup agents edit only their own folder.
+**Alternatives:** Gitignored `design/mockups/` (can't ship in the image or be reviewed from the remote).
+**Consequences:** Mockup code is in the bundle and the history; when a direction is chosen, the unused
+mockups need an explicit removal decision (`docs/TODO.md`).
+
+## 2026-10-23 — Production bundle runs from `dist/`
+**Status:** accepted
+**Context:** With Bun 1.3.14, a `--production` bundle of HTML imports resolves its assets relative to the
+current working directory; `bun dist/server.js` from the repo root throws "Bundled file … not found".
+**Decision:** `bun run start` is `cd dist && bun server.js`; the Docker runtime stage uses `WORKDIR /app/dist`.
+**Alternatives:** Not recorded (e.g. `--asset-naming`/`naming` options were not explored).
+**Consequences:** Any new run script or deploy target must set the cwd to `dist/`.
+
+## 2026-10-23 — Bun only, self-contained assets
+**Status:** accepted
+**Context:** Spec 001 constraints.
+**Decision:** Bun's own server, bundler and test runner with HTML imports; no Vite/Next. Fonts and three.js
+bundled from npm, no CDN. YouTube as link cards, not embeds. three.js only in the 3D mockups (06, 07).
+**Alternatives:** Not recorded.
+**Consequences:** The image works offline apart from outbound links.
+
+## 2026-10-23 — Placeholder lyrics, unverified facts marked
+**Status:** accepted
+**Context:** Lyrics recalled from memory risk inaccuracy, and their copyright question is open.
+**Decision:** Sample data uses clearly marked placeholder lyric lines in the real data shape; any fact,
+story time or Odyssey reference not confirmed carries `// TODO(verify)`.
+**Alternatives:** Real lyrics (deferred by the maintainer).
+**Consequences:** Nothing in `src/data/sample.ts` may be presented as fact-checked.
+
+## 2026-10-23 — Adopt AGENTS.md as single source of truth
+**Status:** accepted
+**Context:** Agents had no durable project context and no consistent workflow between sessions.
+**Decision:** `AGENTS.md` is canonical; `CLAUDE.md`/`GEMINI.md` are pointers. Specs are permanent in
+`docs/specs/`. Plans live in `docs/plans/` only while work is in progress and are removed before the
+merge request. Both override the superpowers default paths.
+**Alternatives:** Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore
+the repo every session — measurably slower and more tokens).
+**Consequences:** Rule changes happen in one file; pointer files must stay thin. Plans are working
+artefacts: kept after merge they go stale and contradict the code, so the spec is the record.