# 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.

## 2026-10-30 — three.js allowed in mockup 13

**Decision:** mockup 13 (Curtain call) may use three.js, like 06 and 07. It mocks the frieze → 3D sea →
frieze → cave transition, which needs the 3D sea. three.js is already a dependency; nothing new is added.

## 2026-10-30 — three.js allowed in mockup 14

**Decision:** mockup 14 (Voyage with side panel) may use three.js; it converges 13's 3D flow with a
persistent side panel. No new dependency.

## 2026-10-30 — three.js allowed in mockup 15

**Decision:** mockup 15 (Voyage, look 2) may use three.js; it iterates on 14. No new dependency.