Bootstrap agent-ready docs and permissions (D-036)

Root AGENTS.md is now the single source of truth for coding agents;
CLAUDE.md, GEMINI.md and docs/CLAUDE.md are pointers. The product spec
moves from docs/CLAUDE.md to PRODUCT.md, DESIGN.md records the shipped
visual system, and docs/PERMISSIONS.md defines agent permission tiers
rendered to .claude/, .codex/ and .gemini/. Adds docs/specs/ and
docs/plans/, logs issues noticed (not fixed) in WorkBreakdown.md.

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

docs/PERMISSIONS.md

@@ -0,0 +1,56 @@
+# Agent permissions
+
+Source of truth for what AI coding agents may run here. Tool files are renderings of this page:
+`.claude/settings.json`, `.codex/config.toml` + `.codex/rules/project.rules`, `.gemini/settings.json`.
+Change this page and every tool file in the same commit. (No Cursor/Copilot files: no sign the team uses them.)
+
+## Verified commands
+
+Run on 2026-10-29 (Bun 1.3.14). Only `worked` rows may appear in a tier, a tool file, or `AGENTS.md` Commands.
+
+| Command | Result |
+|---|---|
+| `bun install --frozen-lockfile` | worked |
+| `bun test tests/export.test.ts` | worked — 28 pass |
+| `bun test tests/models.test.ts -t "dtype"` | worked — 5 pass, 14 filtered |
+| `bun test --path-ignore-patterns='tests/live-real-model.test.ts'` | worked — 239 pass, 1 skip, ~6 s |
+| `bun test` | ran — 242 pass, 1 skip, 1 fail in ~17 min. The fail is pre-existing: `tests/live-real-model.test.ts` › `en_alien` hits its 900 s timeout (reproduced in isolation). Allowed anyway: the command itself is the verified dev loop. |
+| `bun run build` | worked |
+| `bun run icons` | worked |
+| `bun dev` | worked — HTTP 200 on `/` |
+| `FW_INTEGRATION=1 bun test tests/transcribe.test.ts` | not run — faster-whisper not installed here |
+| `bun start` | not run — documented in README |
+| Typecheck / lint | not run — `typescript` not installed, no linter configured |
+| `docker build .` | not run — CI-only; in Ask tier |
+
+TODO(maintainer): confirm every row above that is not worked.
+
+## Tiers
+
+| Tier | Commands | Why |
+|---|---|---|
+| Allow | `git status`, `git diff`, `git log`, `git show`, `git branch --list`, `git rev-parse`, `git add`, `git commit`; `bun install --frozen-lockfile`, `bun test`, `bun run build`, `bun run icons`, `bun dev` | Inspection and the verified dev loop; no prompt needed. |
+| Ask | `git push`, `git merge`, `git rebase`, `git switch`, `git restore`, `git commit --amend`, `rm`; `bun add`/`remove`/`update`/`upgrade`/`patch`, `bunx`, `bun x`; `docker`; `pip install`, `python3 -m pip install` | Leaves the machine, rewrites work, changes dependencies or the transformers patch, or touches deployment — a human decides. |
+| Deny | `git push --force`/`-f`/`--force-with-lease`, `git reset --hard`, `git clean`, `git add -f`/`--force`, `git commit --no-verify`/`-n`, `rm -r`/`-R`/`-rf`/`-fr`/`-Rf`/`-fR`/`--recursive`, `sudo`; reading `.env`, `.env.*`, `data/**` (local SQLite users + sessions) | Destroys work, skips checks, or exposes secrets/user data. |
+
+## Known gaps
+- Allowlists save prompts; they are not a security boundary. Use the tool's sandbox for isolation.
+- Prefix rules are bypassable: `git -C dir push`, flags placed later (`git push origin main --force`),
+  `+refspec` pushes. Claude Code's `:*` matches at a word boundary, so each flag cluster must be
+  listed — which is why `git clean` is denied whole and `rm` always asks.
+- `bun install <pkg>` adds a dependency but cannot be put in Ask without also catching the allowed
+  `bun install --frozen-lockfile` (Ask beats Allow in Claude Code). Treat it as Ask by convention.
+- `bun run build` deletes and rewrites `dist/` itself (`scripts/build.ts`), outside the `rm` rules.
+- Allowed test, build, and dev commands run code from the repo; an agent that can edit
+  `package.json`, `scripts/`, or the tests can run anything through them. `bun test` also downloads
+  model weights from huggingface.co (`tests/live-real-model.test.ts`).
+- Denying reads of `.env` does not stop a script that opens it itself (Bun auto-loads `.env`), and
+  git can print staged or committed secrets. `git add -f` is denied so an agent cannot stage an
+  ignored secret; keep real secrets out of the working tree.
+- Codex: loaded only once the project is trusted; `approval_policy = "on-request"` here can loosen a
+  stricter user setting. No allow rules (Codex `allow` = run outside the sandbox). In
+  `workspace-write`, `.git/` is read-only, so `git add`/`commit` ask for escalation; `bun install`
+  needs network and asks too. `--force-with-lease=<ref>` and late flags only match the Ask rule.
+  Rules checked with `codex execpolicy check`.
+- Gemini: ignored until the folder is trusted; `tools.exclude` is the only project-level deny; no
+  Ask tier (anything not allowed already asks); cannot deny file reads.