@bongos/core 1.17.0

package/docs/file-map.md

@@ -0,0 +1,418 @@
+# File Map — Where Things Live
+
+> Split out of `CLAUDE.md` §11 in V3.R86 ([#305](https://example.com/builders#/task/305)) to keep the agent index lean. `CLAUDE.md` §11 now
+> carries a one-paragraph orientation and points here. Paths below are relative to the repo root — **today** one checkout. [ADR 0108](adr/<redacted>.md) (configurable-root) means that stops being universally true once a consumer installs the core as a `node_modules` dependency: `resolveCoreRoot()` and `resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) can diverge, and this single tree below splits into a **core-package tree** (everything `isPublishable()` selects — see [`docs/modules-contract.md`](modules-contract.md) and [ADR 0098](adr/<redacted>.md)) and an **instance tree** (`config/`, instance `modules/`, `migrations/instance/`, `.claude/` once materialized — ADR 0108 §3). Both resolvers return this repo's root today, so the tree below is still accurate for the live instance; this note is the marker for when that stops being true (ADR 0108 §6 lands the split on Mercury, R85, before Example).
+
+**Project root:**
+
+```
+/
+├── CLAUDE.md                    ← index + framing (descriptive; DB is source of truth for state)
+├── README.md                    ← public-facing one-paragraph summary
+├── .gitignore
+├── package.json / package-lock.json
+├── server.js                    ← game boot: Express + Colyseus + the shared internal surface (mountInternalSurfaces), binds 127.0.0.1:3000
+│
+├── .devcontainer/               ← the Example Dev Box, defined as code (ADR 0031 §3) — builds identically on a DO box + a laptop
+│   ├── devcontainer.json        ← box spec: features (Node 22, gh, Claude Code), NET_ADMIN caps, persisted volumes, lifecycle hooks
+│   ├── Dockerfile               ← Ubuntu 24.04 base + Python 3.12 venv + firewall/art system deps + build-time integrity assert
+│   ├── init-firewall.sh         ← postStart default-deny outbound firewall, tight allow-list (ADR 0031 §6)
+│   ├── post-create.sh           ← first-run: folds in setup-builder.sh --no-auth + art deps + full-stack verify
+│   ├── healthcheck.sh           ← image-level toolchain integrity check (the image half of doctor-as-health-check)
+│   └── README.md                ← box docs, ADR mapping, deliberate reconciliations, out-of-scope tasks
+│
+├── limitations/                 ← versioning-methodology artifacts
+│   ├── README.md
+│   ├── v1-shipped.md            ← V1 game archive (shipped 2026-05-12)
+│   ├── pms-v2-shipped.md        ← PMS-V2 archive (shipped 2026-05-12)
+│   ├── pms-v1-shipped.md        ← PMS-V1 archive (shipped 2026-05-09)
+│   └── backlog.md               ← FROZEN archive after one-time DB import (live tasks in GDS DB)
+├── generative-ideas.md          ← FROZEN archive after Phase 2c DB import (live ideas in GDS idea_inbox table)
+│                                  (chat-inbox.md removed 2026-06-05 — inbound is now Discord #ideas → idea_inbox, ADR 0033 F6)
+├── blockers/
+│   ├── README.md
+│   └── blockers.md              ← FROZEN archive after Phase 2a DB import (live blockers in GDS blockers table)
+│
+├── brand/                       ← repo-canonical design system (ADR 0081)
+│   └── cloud-bongos/            ← Cloud Bongos brand: README design guide + tokens.json + regen_*.py + assets/ (mascot, 9 animation states, Docker-homage sky-whale, coin logo + Baloo 2 wordmark, painted code-glyph charms). Built under task 1506 (mascot restyle 1529, code glyphs 1527); illustrations generated via Gemini (modules/art-pipeline/pipeline gen_api).
+│
+├── docs/
+│   ├── adr/                     ← Architecture Decision Records
+│   │   ├── README.md            ← full ADR index (authoritative)
+│   │   └── 0001…0120-*.md       ← 133 ADR files (a handful of numbers collide — see README.md's disambiguation note; README.md has the live list)
+│   ├── architecture.md          ← §10 detail: live infra, app stack, DB schema, GDS API (split out V3.R86)
+│   ├── canonical-permissions.md ← rank ladder + trust boundary reference (read-only mirror; DB enforces)
+│   ├── design/                  ← game design docs (V2 visual redesign cluster)
+│   │   ├── container-exterior.md ← (#641) container building exterior: two-storey stacked-container structure, glass facade, deck, rooftop
+│   │   └── container-interior.md ← (#645) container building interior: layered industrial shell + aqua wave floor + boutique display; palette reconciled to ADR 0044
+│   ├── file-map.md              ← this file (§11 detail, split out V3.R86); the `.claude/skills/` + `.claude/scheduled-tasks/` trees are GENERATED (gen-file-map.js, ADR 0066) — do not hand-edit those blocks
+│   ├── file-map.notes.json      ← ADR 0066 ([#1276](https://example.com/builders#/task/1276)): the sidecar of one-line notes for each skill/routine that gen-file-map.js renders into file-map.md; the ONE place to edit those notes — a new skill with no note here fails CI
+│   ├── handoff-template.md      ← session-end template + Definition of Done
+│   ├── google-chat-broadcast.md ← team-chat integration plan
+│   ├── pms-v1-deploy.md         ← step-by-step runbook to deploy PMS-V1 + status subdomain
+│   ├── recipes/                 ← long-form operational guides (formerly learnings/) — Postgres, Caddy, the pixel-art pipeline, etc.
+│   │   ├── README.md
+│   │   ├── ops-gotchas.md       ← Postgres, Caddy, SSH, Mac toolchain recipes
+│   │   ├── pixel-art-pipeline.md
+│   │   ├── overnight-builder.md ← (#358) operator runbook for the autonomous overnight session-runner
+│   │   ├── builder-box-lifecycle.md ← (#598/ADR 0031) operator runbook: provision/park/wake/deprovision dev boxes, the two sweeps, config env, going-live steps
+│   │   └── managed-settings-remote-control.md ← (#599/ADR 0031 §1, #760/ADR 0038) operator+builder guide: distribute the locked Claude Desktop SSH config; the browser web-terminal (ttyd + Cloudflare Tunnel) on-ramp
+│   ├── reviews/                 ← temporary audit/review docs (e.g. claude-md-audit-V3.R86.md)
+│   ├── session-logs/            ← one file per session, named YYYY-MM-DD-<slug>.md (CLAUDE.md §13 indexes them)
+│   └── session-log-archive.md   ← compressed older session-log prose
+│
+├── infra/
+│   ├── Caddyfile                ← reverse proxy + Cloudflare Origin Cert TLS
+│   ├── example.service     ← systemd unit
+│   ├── box-idle-suspend.{service,timer}    ← (#598) 15-min CONTROL-PLANE sweep: snapshot-and-park idle dev boxes
+│   ├── box-dormant-reclaim.{service,timer} ← (#598) daily CONTROL-PLANE sweep: deprovision long-parked dev boxes
+│   ├── box-intent-runner.{service,timer}   ← (#701) 1-min CONTROL-PLANE runner: drain box_intents (auto-provision + wake-on-connect) via `box.js run-intents --apply`
+│   ├── box-drift-reconcile.{service,timer}  ← (#1289/ADR 0071) hourly CONTROL-PLANE sweep: repair DO⇄DB drift via `box.js reconcile-drift --apply` (kill zombie droplets, mark ghost rows destroyed)
+│   ├── box-heartbeat.sh         ← (#598) runs ON THE BOX: pings /api/gds/box/heartbeat while in use, so the idle sweep measures activity not uptime
+│   ├── box-report-terminal.sh   ← (#760/ADR 0038) runs ON THE BOX: POSTs the box's web-terminal URL + basic-auth credential UP to /api/gds/box/terminal so a Chromebook builder reads them from the web
+│   ├── box-source-fetch.sh      ← (#600/#898/ADR 0052) runs ON THE BOX post-clone: scope-aware source fetch (sparse starter / full) + idempotently installs & enables the box units (box-game-preview, box-terminal, close-box) on every fetch so existing boxes self-heal; also self-tests (task 843) — every cycle it black-box-probes box-terminal/cloudflared/box-game-preview + the terminal credential and restarts whatever's unhealthy, not just what's absent
+│   ├── builder-box-cloud-init.yaml ← (#598/#599/#760) first-boot bootstrap: Docker + devcontainer up, Claude Code + ttyd + cloudflared on host, box-terminal.service + cloudflared.service + heartbeat cron wired (substituted by box.js)
+│   ├── managed-settings.template.json ← (#599) Claude Desktop sshConfigs template (locked to one approved box); filled per-builder by gen-managed-settings.sh
+│   ├── gen-managed-settings.sh  ← (#599) operator: emit per-builder Claude Desktop managed-settings.json (JSON-safe node substitution + input validation, #667)
+│   ├── box-terminal.service     ← (#760/ADR 0038) always-on ttyd web terminal (127.0.0.1:7681, per-box basic-auth) for thin-device (Chromebook/browser) builders
+│   ├── cloudflared.service      ← (#760/ADR 0038) outbound-only Cloudflare Tunnel exposing the box terminal (no inbound ports); runs cloudflared-run.sh
+│   └── cloudflared-run.sh       ← (#760/ADR 0038) runs ON THE BOX: named tunnel (BOX_TUNNEL_TOKEN) or tokenless quick tunnel; writes the public URL to /run/otb/terminal-url
+├── migrations/                 ← CORE (build-system / GDS) migrations — schema + platform-universal seeds, applied on EVERY instance (migrate.sh `migrations/*.sql`). Game-module migrations moved to modules/game/migrations/ (BV1.R49).
+│   ├── instance/                ← OTB/product SCOPE-TRUTH seeds (versions, goals, done_when_criteria). Applied only on the OWNING instance — `GDS_APPLY_INSTANCE_SEEDS=1`, default OFF — so a vanilla/branded self-host never inherits them (task 1704 / ADR 0105). Merge-sorted with core by basename, so global order is preserved.
+│   ├── game/                    ← LEGACY game-module migrations (moved to modules/game/migrations/ in BV1.R49 — stem-keyed, so they did NOT re-run on prod). Kept here as a frozen archive; migrate.sh still applies them for backward compat.
+│   │   ├── 001_initial.sql      ← schema_migrations + world_events (game)
+│   │   └── 002_players.sql      ← players — persistent identity (game)
+│   ├── 003_pms.sql              ← GDS schema: builders, versions, tasks, claims, costs, credits, sessions
+│   ├── 112_drop_track_check.sql ← task 1191: drop the product|internal track CHECK on versions (taxonomy → branding.tracks config); name-independent + idempotent
+│   ├── <redacted>.sql ← cost_log unique (source, source_ref) for idempotent backfill
+│   ├── 005_pms_smoke_filter.sql ← filter __smoke__ tasks from claimable_tasks + version_progress
+│   ├── 006_pms_v2.sql           ← PMS-V2: achievements, learnings, idea_inbox, done-when, task_kind, parent_task_id, pulses, builders.timezone
+│   ├── 007–013                  ← incremental PMS-V2: hierarchy trigger, migration-number allocator, blockers table, uptime, lifecycle breakdown, three-state lifecycle, claim session locking
+│   ├── <redacted>.sql ← tasks.discipline (creative|engineering|unclassified — renamed by mig 086); rebuilds claimable_tasks + tasks_session_fit so SELECT t.* re-expands
+│   ├── <redacted>.sql ← per-kind actual/est calibration multipliers; DROP+CREATE tasks_session_fit
+│   ├── 016_pms_task_grades.sql      ← task 197: task_grades table + task_grades_with_context view (PMS-V2 quality grader)
+│   ├── <redacted>.sql ← task 218: rebuild version_progress to exclude abandoned tasks from total_count / total_weight (mirrors the existing __smoke__ + parent filters)
+│   ├── <redacted>.sql ← V3.R00 planning seed: 9 done_when_criteria rows + versions.GDS-V3.done_when text + V3.R## prefix on existing 9 GDS-V3 tasks
+│   ├── 020–022                  ← V3: task dependencies + auto-promotion, V3 renumber/deps, dep-gated status reconcile
+│   ├── 023_pms_rank.sql         ← V3.R05 (#106): builders.rank enum (16-value ladder) + example-owner → archon
+│   ├── <redacted>.sql ← /builder-exit: deactivated builders drop to 'xenos'
+│   ├── <redacted>.sql ← builders.preferred_disciplines column (enum renamed by mig 086)
+│   ├── 029_rank_three_live.sql  ← #360/ADR 0018: rank default thetes→xenos + tasks.xenos_claimable (three-rank model live)
+│   ├── 067_builder_boxes.sql    ← #598/ADR 0031: builder_boxes (per-builder dev box lifecycle state) + box_events ledger
+│   └── <redacted>.sql ← task 615: rename disciplines engineering→engineer, creative→artist|ideator; swaps both CHECK constraints + backfills tasks.discipline & builders.preferred_disciplines
+├── modules/                    ← self-contained optional feature modules (ADR 0083 / docs/modules-contract.md). Each `modules/<key>/` is a full vertical slice — routes, migrations, skills, seam registrations — reached only through src/module-api.js. The loader discovers them at boot; no core file changes to add one.
+│   ├── dev-box/                ← per-builder cloud dev environments (DigitalOcean + Cloudflare tunnels, sandbox preview, branch publish). Template move (BV1.R43). CLAUDE.md, module.json, routes/box.js, boxes.js, box-access.js, box-onboard.js, do-api.js, cf-tunnel.js, http-api-client.js, box-credential.js.
+│   ├── game/                   ← the playable Example world — Phaser client, Colyseus rooms (WorldRoom/QueueRoom), world/terrain model, game DB tables, static assets. Moved BV1.R49 (task 1418). CLAUDE.md, module.json, routes/game.js, rooms/, world/, public/, migrations/.
+│   ├── discord/                ← outbound ship broadcast + inbound #ideas/#bugs bot + role-sync + channel management + account-link state. Mirror only, never authority (ADR 0033). CLAUDE.md, module.json, routes/discord.js, routes/bug-attachments.js, discord-bot.js, discord-lib.js.
+│   ├── art-pipeline/           ← self-improving pixel-art generation pipeline + the four otb-* art skills + the artist discipline. CLAUDE.md, module.json, routes/art-key.js, art/ (lives under art/ at repo root; module owns the route and discipline entry).
+│   ├── memory/                 ← CORE-DOMAIN carve (BV1.R72, default-on): per-builder session memory + the recall/search retrieval layer (ADR 0060) + learnings. CLAUDE.md, module.json, routes/{memory,search,learnings}.js, memory.js, search.js, search-chunker.js, learnings.js.
+│   ├── grading/                ← CORE-DOMAIN carve (BV1.R73, default-on): the grade-a-diff adversarial worker panel + deterministic pre-passes + rubric; registers the `grade` kernel port. CLAUDE.md, module.json, routes/grade.js, grader.js, grader-rubric.json.
+│   ├── economy/                ← CORE-DOMAIN carve (BV1.R77, default-on): credit allocation + cost ledger + streaks + achievements + leaderboard; registers the `reward` kernel port. CLAUDE.md, module.json, routes/{cost,leaderboard,reward}.js, credits.js, cost.js, cost-classify.js, cost-summary-shape.js, streak.js, achievements.js, reward.js.
+│   ├── ideas/                  ← CORE-DOMAIN carve (BV1.R78, default-on): the idea_inbox capture/triage/criterion-proposal flow + the blockers queue; registers the `ideas.capture` kernel port (retired the `captureIdea` doorway leak). CLAUDE.md, module.json, routes/{inbox,blockers}.js, inbox.js, blockers.js.
+│   ├── security/                ← CORE-DOMAIN carve (BV1.R79, default-on): red-team/vulnerability report intake + the env-aware bounty payout table (Metic+); registers the `security` kernel port the core /public/bounty-table resolves. <redacted> (permission-path-check, route-rank-check) stays kernel — this is <redacted>. CLAUDE.md, module.json, routes/reports.js, security.js, secret-scrub.js.
+│   ├── builder-settings/        ← CORE-DOMAIN carve (BV1.R80, default-on): per-builder prefs — wandering level, per-skill model ceilings, sound/render toggles — + builder-needs. `GET /me` resolves the `builder-settings` kernel port for these slices. CLAUDE.md, module.json, routes/settings.js, wandering-prefs.js, skill-prefs.js, sound-prefs.js, event-sound-prefs.js, render-prefs.js, model-alloc-prefs.js, interaction-prefs.js, display-name.js, builder-needs.js.
+│   ├── onboarding/              ← CORE-DOMAIN carve (BV1.R81, default-on): admission (access-request → Archon approval), the server-ticked onboarding state machine, the friction analyzer, and evergreen newcomer-chore restock; registers the `onboarding` kernel port. CLAUDE.md, module.json, routes/access-requests.js, onboarding.js, onboarding-state.js, newcomer-restock.js, approval-broadcast.js.
+│   ├── sessions/                ← CORE-DOMAIN carve (BV1.R82, default-on): the session_records corpus + data plane (upload, cross-builder search/deep-dive), the BFG read-the-room scorer, session-pulse/stale-claim helpers. Registers no port — reached via HTTP POST to its own /sessions route; resolves the economy `reward` port for the cost-plus token reward. CLAUDE.md, module.json, routes/sessions.js, bfg.js, pulse.js.
+│   ├── autonomy/                ← CORE-DOMAIN carve (BV1.R83, default-on): the MAS autonomy surfaces — the $0 deterministic autonomy gate (System 3, inert until armed), the conductor/architect CLIs, and the in-process routine timers (incl. the weekly peer-vote-tally poller). Registers no port; resolves the lifecycle `tallyPeerVotes` doorway. CLAUDE.md, module.json, routes/autonomy.js, autonomy.js.
+│   ├── status-ui/              ← CORE-DOMAIN WEB-SURFACE carve (BV1.R84, default-on): the public status dashboard at status.<apex>, moved from public-status/. NO routes/db/port — declares contributes.webSurfaces:[{host:"status.",dir:"public"}], served by the loader web-surface seam (moduleWebSurfaces → serve-internal). CLAUDE.md, module.json, public/{index.html,status.js,style.css,cursors/,snapshots/}.
+│   ├── hall-ui/                ← CORE-DOMAIN WEB-SURFACE carve (BV1.R85, default-on): the authenticated builders' hall at builders.<apex>, moved from public-builders/ (~13k LOC, the largest). NO routes/db/port — declares contributes.webSurfaces:[{host:"builders.",dir:"public"}] for discovery, but UNLIKE status-ui keeps its DEDICATED serving block in serve-internal (the /builders shim + canonical redirects + citizen/Archon page gates + asset-stamping + hall-widget injection), partitioned out of the generic web-surface loop and served from BUILDERS_DIR. CLAUDE.md, module.json, public/{index.html,builders.js,style.css,work,watch,harbor,gate,pair,settings,ranks,sessions,primer,diagrams,atlas,...}.{html,js},cursors/,chime.wav.
+│   ├── lifecycle/               ← CORE-DOMAIN carve (BV1.R86, default-on): the build state machine — tasks · claims · versions · done-when · goals · dependencies · claim→ship→grade→credit · github-push + merge-lock + conflict-resolve + publish-reconciler. The LAST, most-coupled carve; registers the `lifecycle` kernel port (createTask, classifyTaskKind, tallyPeerVotes, work-tracking reads). CLAUDE.md, module.json, routes/{tasks,claims,versions,done-when,goals,dependencies,gate-approvals,analytics}.js, lifecycle.js, github-push.js, merge-lock.js, conflict-resolve.js, publish-reconciler.js.
+│   ├── character-anim/          ← consistent-character generative animation (ADR 0088) — graded painterly frame sets + manifest, the otb-character-review skill. CLAUDE.md, module.json.
+│   ├── provisioning/            ← stands up + operates a Cloud Bongos instance's own infra (server/DB/domain/DNS/TLS) via the API (ADR 0111); web-tier request+state only, no cloud tokens — a separate control-plane runner drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute workloads. CLAUDE.md, module.json.
+│   └── demo/                    ← BV1.R52 acceptance-proof module: one rank-gated write route + one namespaced migration proving the loader mounts a scaffolded module with zero core edits. CLAUDE.md, module.json.
+│
+├── scripts/
+│   ├── migrate.sh               ← idempotent migration runner; applies core `migrations/*.sql` always + `modules/<key>/migrations/*.sql` only when the module is enabled (ADR 0083 §module-owned-migrations); stem-keyed so relocating a migration between dirs never re-runs it on prod
+│   ├── verify-gds-only-schema.sh ← task 1191: throwaway-DB proof that a GDS-only migration run yields the build-system schema with NO game tables (needs local Postgres; not the DB-free unit gate)
+│   ├── setup-builder.js         ← one-command new-builder bootstrap (toolchain + npm ci + .env.local + GDS auth); cross-platform node entry (#673)
+│   ├── setup-builder.sh         ← thin bash shim → setup-builder.js (Mac/Linux convenience + devcontainer/README refs)
+│   ├── deploy/                  ← deploy scripts that run ON the droplet
+│   │   ├── deploy-prod.sh       ← #1026/ADR 0056: version-controlled MIRROR of the droplet's hand-maintained ~/deploy.sh (byte-faithful). NOT auto-installed — the ci deploy key is forced-command-locked (ADR 0042/0043); reinstall by hand on change. Localhost /healthz retried 15×@1s so a slow bind no longer false-fails a deploy.
+│   │   ├── deploy-staging.sh    ← #261: staging analogue of ~/deploy.sh; scp'd to ~/deploy-staging.sh + run by deploy-staging.yml on push to `staging` (same healthz retry)
+│   │   └── provision-staging.sh ← #260: one-time staging-environment provisioner
+│   │                             (chat/ — Google Chat — REMOVED 2026-06-05; both directions are now Discord. Outbound → discord/ (#607); inbound → the in-process bot, ADR 0033 F6)
+│   ├── discord/                 ← outbound build broadcast → Discord #ship-news webhook (#607, ADR 0032); replaced chat/ outbound
+│   │   ├── README.md
+│   │   ├── lib.js               ← webhook poster (reads ~/.config/otb/discord-webhooks.json, mode 600)
+│   │   └── post.js              ← post a ship summary to a channel (default ship_news)
+│   └── gds/                     ← Game Development System CLI + bootstrap (renamed from `pms/` in V3.R01)
+│       ├── cli-lib.js           ← shared: session token, apiCall(), formatters
+│       ├── discord-channels.js  ← Archon CLI: plan/apply the Discord channel layout via the API (ADR 0036, #727)
+│       ├── setup.js             ← one-time GitHub Device Flow → ~/.config/otb/gds-session.json
+│       ├── start.js             ← list claimable tasks + active claims (`/builder-start`)
+│       ├── claim.js             ← atomic POST /api/gds/claims (`/builder-claim`); prints the claim-time context pack incl. next-free ADR/migration numbers (V4.R26); printDisciplineMode() reads discipline-modes.json to route a claimed task to its playbook skill
+│       ├── discipline-modes.json ← discipline→operating-playbook map read by claim.js: ideator→/ideate, artist→/paint, engineer→/dev; absence of an entry = the default build-and-ship loop, fail-open ([#1267](https://example.com/builders#/task/1267))
+│       ├── next-number.js       ← deterministic next-free ADR + migration number from origin/main ∪ local working tree; supersedes the drift-prone claim-time DB counter (V4.R26, [#964](https://example.com/builders#/task/964)). `node scripts/gds/next-number.js [--json]`
+│       ├── gen-repo-map.js      ← Path B (ADR 0063, [#1224](https://example.com/builders#/task/1224)): zero-dep, deterministic symbol-skeleton generator → docs/repo-map.md + the generated factual block in each nested CLAUDE.md; ranks exported symbols by reference frequency. `--check` = CI gate; regenerated on deploy by ship.js regenerateRepoMap()
+│       ├── gen-file-map.js      ← ADR 0066 ([#1276](https://example.com/builders#/task/1276)): generates the `.claude/skills/` + `.claude/scheduled-tasks/` sections of docs/file-map.md from disk; per-entry notes come from docs/file-map.notes.json; `--check` fails on drift OR a skill/routine with no note (CI gate via fitness.js); regenerated on deploy by ship.js regenerateFileMap()
+│       ├── fitness.js           ← Path C (ADR 0062 §9, [#1225](https://example.com/builders#/task/1225)): architecture fitness functions — core↔host import boundary (zero grandfathered exceptions as of R52/#1191), CLAUDE.md budget + nested-doc presence (ADR 0061), no route bypasses rank checks (reuses route-rank-check), repo-map freshness. Enforced in CI via tests/fitness.mjs (the `unit` gate). `node scripts/gds/fitness.js`
+│       ├── ship.js              ← resolve claim as shipped, award credits (`/builder-ship`); also uploads a secret-scrubbed session digest to the corpus (6D.1, ADR 0027); on a dev box runs the sandbox-first review gate before resolving (#927, ADR 0046)
+│       ├── package-core.js      ← package the core as a versioned, installable artifact + pin manifest (`bongos package-core`; R84, ADR 0100 §1, [#1688](https://example.com/builders#/task/1688)): isPublishable() selection + mirror redaction + fail-closed no-leak gate → dist/cloudbongos-core-<version>.{tgz,manifest.json}; version = src/module-api CORE_VERSION. Recipe: docs/recipes/packaging-the-core.md
+│       ├── sandbox-stage.js     ← stage the working tree on the live game preview (box OR local) for browser review before ship; resolvePreviewContext picks the context (`/builder-stage`; #927, ADR 0046; local: task 1056)
+│       ├── local-preview.js     ← builder CLI for the LOCAL sandbox: start/stop/status/restart/logs/url of the game-only preview at http://localhost:3100 (`npm run preview`; task 1056)
+│       ├── local-preview-lib.js ← core of the local sandbox launcher (detached `node src/preview-server.js`, pid/health/port mgmt); shared by local-preview.js + sandbox-stage.js (task 1056)
+│       ├── session-eval.js      ← BFG session-inefficiency analysis engine (6D.3): classify turns, compute ceremony-vs-work, detect footguns, file systemic findings (ADR 0027)
+│       ├── linkify-refs.js      ← rewrite bare `#NNN` task refs across ALL docs → status-dashboard permalinks (stops GitHub's PR/issue autolinker mis-linking them); conservative classifier, token-free id list via /public/ref-ids; --apply / --check (CI gate: .github/workflows/doc-ref-linkify.yml) / --dry-run default ([#604](https://example.com/builders#/task/604), [#653](https://example.com/builders#/task/653)).
+│       ├── release.js           ← resolve claim as abandoned (`/builder-release`)
+│       ├── cost.js              ← log a cost entry (`/builder-cost`)
+│       ├── me.js                ← current builder profile + leaderboard
+│       ├── seed-v3-tasks.js     ← V3 Planning Session #1: 80 net-new GDS-V3 tasks (V3.R01–V3.R89) + 10 idea_inbox promotions; idempotent on source_ref
+│       ├── backfill-cost.js     ← read art ledger → POST /api/gds/cost (idempotent)
+│       ├── smoke-write.sh       ← write-path smoke (create→claim→ship round-trip)
+│       ├── smoke-gds.js         ← public-surface + 401-check smoke test (asserts /api/pms/* now 404s — removed in V3.R01-followup #308)
+│       ├── box.js               ← (#598/ADR 0031) per-builder dev box lifecycle CLI: provision·park·wake·deprovision·sweep-idle·sweep-dormant·status (dry-run default, --apply to act; rank-gated)
+│       ├── smoke-box.sh         ← (#598) hermetic box-lifecycle smoke (no DB/DO/network): runs tests/boxes.mjs + tests/cf_tunnel.mjs (#771 named tunnel) + route-rank + module-load
+│       ├── recall.js            ← `/recall` CLI: two-call progressive-disclosure search (summary → `--expand <id>`) over the GDS retrieval layer (ADR 0060); `node scripts/gds/recall.js <query>`
+│       ├── capture.js           ← file an idea_inbox row from the CLI (the ideas.capture kernel port); backs the "capture a tangent" flow across skills
+│       ├── learning-capture.js  ← file a `learnings` row (DB-backed short-form rule capture, replacing hand-edited recipe files for a single gotcha)
+│       ├── docs-entropy.js      ← ([#…] docs-entropy) markdown-corpus linter: broken internal links + cross-file duplicate-prose detector across every tracked `.md`; `--verbose` / `--file-ideas`
+│       ├── gen-diagrams.js      ← generates the 5 onboarding diagrams (`.mmd`/`.svg`/`.png` + `assertions.json`) from templates in this file — never hand-edit a `.mmd`/assertions.json; runs on deploy
+│       ├── gen-api-docs.js      ← ADR 0109: generates `docs/api/openapi.json` + `docs/api-reference.md` from the live route files via `route-rank-check.js` introspection, so the API reference cannot drift from what the server actually mounts
+│       ├── architect-audit.js   ← MAS Phase 5 (ADR 0024): the Architect's bounded first-principles `--scope`/`--paths` audit CLI → `docs/audits/`
+│       ├── module.js            ← `bongos module new <key>` scaffolder + module CLI utilities (ADR 0083)
+│       ├── upgrade.js           ← `bongos upgrade` — bump the installed `@cloudbongos/core` package version with doorway/coreVersion pre-checks (ADR 0108)
+│       └── newcomer-floor.js    ← deterministic on-claim replenisher for the evergreen newcomer chores (engineer/artist/ideator floor); no cron, restocks when one is claimed (task 1168)
+│
+├── src/
+│   ├── db.js                    ← GAME db helper: logEvent + player identity; sources its pool from src/bongos/pool.js (R52 carve-out, task 1191 — one pool, host→core)
+│   ├── branding.js              ← the branding contract resolver (env → config/branding.json → branding.neutral.json); single source for instance-identity strings + the configurable track set + db.database (ADR 0062 §3)
+│   ├── modules.js              ← back-compat facade over src/module-loader/loader.js; stable exports: isModuleEnabled/enabledModules/enabledDisciplines/clientModules/resolveModules; vanilla=all off (ADR 0062 §4; ADR 0083; docs/modules-contract.md)
+│   ├── module-api.js           ← THE PUBLISHED, SEMVER'D DOORWAY (ADR 0083): the ONLY core file a module may `require`. Re-exports kernel capabilities (auth gates, pool, db helpers, branding, seams, logger, CORE_VERSION). MINOR bump = additive export; MAJOR = breaking change; `bongos upgrade` pre-checks. Current: 1.4.0.
+│   ├── module-seams.js         ← kernel seam registry (ADR 0083 / design 04§1): PORTS (registerProvider/resolve/resolveOptional — single-provider required capabilities) + EVENTS (emit/on — optional reactions, isolated errors). Modules cooperate through here, never by importing each other. Re-exported through module-api.js.
+│   ├── module-loader/          ← the loader that makes `modules/<key>/` discoverable (BV1.R38–R41)
+│   │   ├── loader.js           ← discover modules/*/module.json → validate manifest → coreVersion-check → enabled-filter → mount routes behind kernel auth → start pollers. <redacted> on empty modules/. Used by modules.js + routes.js.
+│   │   ├── manifest-schema.js  ← module.json schema + validator (key, title, description, coreVersion, default, contributes, provides, consumes, prerequisites). Unknown keys throw. Used by loader + bongos module new.
+│   │   └── semver.js           ← minimal semver `satisfies(version, range)` used by the loader (no npm dep).
+│   ├── platform-server.js       ← GDS-ONLY entrypoint (ADR 0062 R51, task 1190): boots Express + the shared internal surface (API + hall + status) with NO game in the process; the inverse of preview-server.js. `node src/platform-server.js`
+│   ├── preview-server.js        ← GAME-ONLY entrypoint for the per-box sandbox (ADR 0052): Phaser/Colyseus + tiles, NO /api/gds
+│   ├── seats.js                 ← in-process seat counter + EventEmitter
+│   ├── rooms/
+│   │   ├── WorldRoom.js         ← singleton room: move + interact + identity
+│   │   └── QueueRoom.js         ← FIFO queue; admits via seat-bus
+│   │   (the hall live channel is no longer a Colyseus room — R55/ADR 0069 moved it to the SSE endpoint src/bongos/routes/live.js)
+│   ├── bongos/                  ← the Bongos core kernel (mounted at /api/bongos; canonical path since the V4/BONGOS-V1 rename — /api/gds/* stays mounted forever as a permanent alias, /api/pms/* removed V3.R01-followup #308 — now 404). Own nested map: src/bongos/CLAUDE.md.
+│   │   ├── pool.js              ← the kernel-owned pg pool (R52 carve-out, task 1191/ADR 0062 §5): resolves DATABASE_URL → PG* → branding db.database (no hard-coded DB name); the core no longer imports the game's src/db.js
+│   │   ├── db.js / db-kernel.js ← the RESIDUE after the ADR 0091/0093 tranche 1+2 core-domain carve: builder identity/admission, rank/status management, auth sessions, the Discord/karma social twins, audit log, security_docs. The build state machine (tasks·claims·versions·done-when·ship) graduated to modules/lifecycle/db.js; grading/economy/ideas/security(feature)/builder-settings/onboarding/sessions/autonomy each graduated to their own `modules/<key>/` with a kernel PORT back-reference — see src/bongos/CLAUDE.md for the full carve map.
+│   │   ├── auth.js              ← GitHub Device Flow (CLI) + Authorization Code (web) + middleware (requireBuilder, requireRank, allowBoxScope)
+│   │   ├── routes.js            ← thin mounter — imports each routes/* sub-router + every enabled module's routes and stitches them behind kernel-composed auth
+│   │   ├── api-prefix.js        ← API_PREFIX ('/api/bongos') + LEGACY_API_PREFIXES ('/api/gds' permanent alias) + API_VERSION
+│   │   ├── api-path-404.js      ← recognize Bongos-API-shaped paths that missed the mount → JSON 404 + corrective hint (server.js catch-all; V4.R14, [#952](https://example.com/builders#/task/952))
+│   │   ├── serve-internal.js    ← (ADR 0062 R51, task 1190) the SHARED internal web surface: mountInternalSurfaces(app) wires /healthz + /version + /api/bongos + the Dev Box downloads + the status & builders hosts; called by BOTH server.js (game boot) and platform-server.js (Bongos-only) so the two never drift. Also injects clientBranding() as window.__BRANDING__ into the served hall/status HTML
+│   │   ├── routes/              ← one file per KERNEL feature so parallel branches stop colliding on routes.js — the domain routes (tasks/claims/versions/cost/leaderboard/memory/learnings/box/inbox/blockers/search/gate-approvals/discord/…) graduated with their domains into `modules/<key>/routes/`, reached only through the loader
+│   │   │   ├── _helpers.js      ← validateOrRespond, parseId, LIMITS, asyncHandler, publicOrigin, corsPublicGet, parseCookie
+│   │   │   ├── healthz.js, auth.js, me.js, builders.js, instance.js
+│   │   │   ├── modules.js       ← GET /modules — listModules() for the loader's live enablement roster
+│   │   │   ├── audit-log.js, backup.js, optimizer.js
+│   │   │   ├── llm-cache.js     ← POST /llm-cache/{lookup,store} — the ADR 0080 content-addressed cache API transport
+│   │   │   ├── live.js          ← GET /api/bongos/live — SSE stream of opaque hall nudges; subscribes to live-channel, mounts in both entrypoints so the hall is live on a game-less boot
+│   │   │   ├── security.js      ← the kernel-side slice: /security/adr threat-model reader + Archon-only /security/docs store (the red-team reports + bounty table graduated to modules/security/)
+│   │   │   └── public.js        ← /public/* — read-only surface for status.example.com; mounted LAST
+│   │   ├── live-channel.js      ← #569/ADR 0030: one persistent Postgres LISTEN('bongos_live') connection → fans NOTIFY nudges out to subscribers (the hall SSE endpoint routes/live.js); migration 066 fires the triggers
+│   │   ├── route-rank-check.js / permission-path-check.js ← the pure protected-path + route-rank matchers (SEC #863/ADR 0043), reused by the grading module + pre-push hook + `--fit` runner
+│   │   ├── llm-pricing.js       ← token→USD pricing shared by the cost-plus reward + the LLM cache savings ledger
+│   │   ├── secret-box.js / sensitive-surfaces.js ← at-rest secret encryption + the sensitive-file classifier
+│   │   ├── cascade-dispatch.js  ← (dormant System 3, ADR 0079) the model-tier escalation ladder for autonomous dispatch
+│   │   ├── goal-scope-check.js / hierarchy-config.js / module-scope-map.js ← goal-scope protected-path checks, the configurable work-hierarchy tiers, and the module→file-glob map
+│   │   ├── path-match.js / repo-info.js / metrics.js / uptime-poller.js / app-pair.js ← touches[] overlap matcher, git-remote parser, Prometheus metrics endpoint, uptime poller, Claude-Desktop pairing store
+│   └── world/
+│       ├── terrain.js           ← (Phase D + ADR 0012, CJS): TERRAIN + OBJECT enums + BLOCKING_TERRAINS + BLOCKING_OBJECTS (server twin of public/game/world/terrain.js)
+│       └── map.js               ← (Phase D + ADR 0012): two-grid INITIAL_MAP {ground, objects}; isBlocked checks both layers (mirrors public/game/world/{terrain,map}.js)
+│   (public-status/ moved to modules/status-ui/public/ in BV1.R84 — see the modules/ block above)
+│   (public-builders/ moved to modules/hall-ui/public/ in BV1.R85 — the authenticated builders' hall; see the modules/ block above. It keeps its DEDICATED serving block in src/bongos/serve-internal.js: the builders.<apex> + apex /builders/* shim, canonical redirects, the citizen/Archon page gates, asset-stamping, and the module hall-widget injection — partitioned out of the generic web-surface loop. index.html=the hall dashboard; work/board/roadmap/goals/watch/harbor/gate/pair/settings/ranks/sessions/primer/diagrams/atlas pages; profile.html/profile.js=the public, shareable builder profile page (/profile?id=N — rank, works, credits, karma, achievements; task 1467); task.html/task.js=the task-detail page (/task/:id, task 751 — replaced the old #/task/N overlay); builders.js=the controller; dom-utils.js/hall-widgets.js=the widget+settings-panel registries.)
+│
+├── devbox-app/                     ← OTB Dev Box — Electron menu-bar/tray switch for the builder's box (#904, ADR 0045; internal). SELF-CONTAINED: own package.json (never feeds the droplet's npm ci); built by .github/workflows/build-devbox-app.yml; published to the public releases repo per config/devbox-app.json; release recipe docs/recipes/devbox-app-release.md
+│   ├── src/                        ← main process: main.js (tray/window/IPC), brand.js (ADR 0004 — the ONE civ-name string), pairing.js, box-controller.js, gds-client.js, session-store.js (shares ~/.config/otb/gds-session.json with the CLI), ssh-setup.js (key 600 + known_hosts replace + managed-settings install w/ elevation), tray.js, preload.js
+│   ├── renderer/                   ← the panel UI (sandboxed; parchment theme)
+│   ├── assets/tray/ + build-resources/ ← generated icons (scripts/gen-icons.js; build-resources name dodges the global build/ gitignore)
+│   └── test/unit.mjs               ← hermetic unit tests (run by the CI workflow, not the root gate)
+│
+├── public/                         ← example.com — the game (product)
+│   ├── index.html
+│   ├── assets/
+│   │   └── tiles/                  ← deployed PNGs (built from art/generated/tiles/ + art/iterations/_autotile/ via build_tilesheet.py)
+│   │       ├── manifest.json       ← unified manifest: tiles + sprites + autotile_families (Phase D)
+│   │       ├── *.png               ← single tiles (legacy + family-published members like container_panel_*)
+│   │       └── autotile/<family>/<NN>.png  ← deployed autotile family tiles (47 PNGs for blob47, 16 for path16)
+│   └── game/
+│       ├── main.js                 ← Phaser game config + scene list
+│       ├── identity.js             ← persistent UUID via localStorage
+│       ├── net/NetClient.js        ← Colyseus client wrapper: try world → fall back to queue
+│       ├── npcs/{Vendor.js,vendorSprite.js}
+│       ├── player/{Player.js,playerSprite.js,movement.js}   ← movement.js: pure tap-to-turn input helpers (#1057)
+│       ├── scenes/WorldScene.js    ← world/queue mode, dialog, server sync; preloads tile manifest
+│       ├── ui/DialogBox.js
+│       └── world/
+│           ├── constants.js        ← TILE_SIZE, WORLD_COLS/ROWS only
+│           ├── terrain.js          ← (Phase D + ADR 0012): TERRAIN + OBJECT enums; TERRAIN_RENDER + OBJECT_RENDER registries; BLOCKING_TERRAINS + BLOCKING_OBJECTS; autotile dispatch helpers
+│           ├── map.js              ← (Phase D + ADR 0012): INITIAL_MAP exports {ground, objects} (mirrors src/world/{terrain,map}.js)
+│           ├── tilePalette.js      ← (Phase D + ADR 0012): pickGroundTextureKey + pickObjectTextureKey; loads autotile families from manifest; procedural fallbacks (transparent BG for objects, opaque for ground)
+│           └── autotile.js         ← runtime tile picker: selectBlob47/selectPath16; cross-verified mirror of art/pipeline/autotile_mapping.py (gated by tests/autotile_xverify.mjs)
+│
+└── art/                            ← pixel-art design system (see art/README.md)
+    ├── README.md                   ← operational reference
+    ├── references/pokemon-firered/ ← 24 reference map screenshots, never modified
+    ├── template/                   ← THE design system
+    │   ├── palette.json + palette.png      ← 64-color locked palette
+    │   ├── rubric.json                     ← 9-criterion scoring rules (per-tile pipeline)
+    │   ├── families.json                   ← family-pipeline schema: defaults + per-family threshold overrides + members + layout
+    │   ├── style_guide.md                  ← grows over time from Lars feedback (otb-feedback-capture)
+    │   ├── vocabulary.json                 ← 23 tile/sprite specs (per-tile pipeline; legacy as families migrate)
+    │   ├── cluster_overview.png            ← "what right looks like" image given to the reviewer
+    │   ├── ref_index.json                  ← slicer summary stats
+    │   └── (ref_tiles/, ref_clusters/ are gitignored — derived; regenerate via slice_references.py)
+    ├── pipeline/                   ← Python — runs everything
+    │   ├── slice_references.py     ← one-time: corpus → tiles, clusters, palette
+    │   ├── gen_api.py              ← Google AI Studio wrapper (Imagen 4 + Nano Banana)
+    │   ├── post_process.py         ← median-downsample + palette quantize → 32×32
+    │   ├── review.py               ← per-tile Gemini 2.5 Flash vision scoring (per-tile pipeline)
+    │   ├── procedural_fallback.py  ← Tier-5 hand-coded Python generators (safety net for per-tile ground)
+    │   ├── orchestrator.py         ← per-tile loop: generate → post → review → retry/escalate
+    │   ├── family_loader.py        ← load families.json with defaults inheritance
+    │   ├── family_generator.py     ← sheet prompt builder + single-call generation + slicer (family pipeline)
+    │   ├── family_checks.py        ← deterministic family-level checks: silhouette CV, palette Jaccard, dominant overlap, luminance EMD, self-seam, edge contracts
+    │   ├── family_review.py        ← Gemini family-coherence review (only fires when family_checks pass)
+    │   ├── family_orchestrator.py  ← family loop: gen → det checks → Gemini review → retry / anchor-refine; --publish atomic-swaps to art/generated/tiles/
+    │   ├── autotile_mapping.py     ← 47-blob + 16-path bitmask lookups (RPG Maker A2 / Cr31 standard); single source of truth for the tile picker
+    │   ├── autotile_compositor.py  ← procedural compositor: 47/16 tiles from primitives via per-quadrant masking; edges match by construction
+    │   ├── autotile_orchestrator.py ← gen primitives via AI + seamless-enforcement + compose + validate; one call per autotile family
+    │   ├── autotile_validate.py    ← Phase A foundation: placeholder primitives, test compositions (island/organic/winding/cross), edge-match scoring
+    │   ├── finalize.py             ← post-run pass: force-rerun any sub-9.0 tile (per-tile pipeline)
+    │   ├── build_tilesheet.py      ← copies finished tiles into public/assets/tiles/
+    │   ├── build_preview.py        ← self-contained HTML review sheet
+    │   ├── build_mosaic.py         ← 4×4 tileability check PNG
+    │   ├── refresh_all.py          ← one-shot: tilesheet + preview + mosaic + dashboard
+    │   ├── dashboard.py            ← per-tile score table
+    │   ├── smoke_test.sh           ← end-to-end server + asset URL check
+    │   └── cost_ledger.py          ← per-call USD ledger; hard stop at $80
+    ├── iterations/                 ← per-tile + per-family attempt history (gitignored)
+    │   ├── _families/<id>/         ← family pipeline artifacts: raw sheets, sliced cells, review JSON, log.jsonl, summary.json
+    │   └── _autotile/<id>/         ← autotile family artifacts: primitives/, tiles/ (47 or 16 PNGs), sheet.png, compositions/, summary.json
+    └── generated/
+        ├── tiles/<id>.png          ← THE accepted finals (both pipelines publish here)
+        ├── preview.html            ← self-contained per-tile review sheet
+        └── mosaic.png              ← 4×4-tiled view of every final, for tileability check
+```
+
+**Tests** at `tests/` (Node ESM, runnable directly + wired into `art/pipeline/smoke_test.sh`):
+
+```
+tests/
+├── autotile_xverify.mjs          ← (Phase D): imports public/game/world/autotile.js, rebuilds the 256/16 lookup tables, asserts byte-for-byte parity vs Python (art/pipeline/_autotile_tables.json from autotile_xverify.py).
+├── terrain_picker.mjs            ← (ADR 0012): picker dispatch shape + GROUND-ONLY invariant (objects must never affect tile selection).
+├── walkability.mjs               ← (ADR 0012): isBlocked over the actual INITIAL_MAP for sea / sand / grass / rock-on-grass / all 8 container cells / vendor cell / cell south of vendor / out-of-bounds. Loads server-side src/world/{map,terrain}.js directly so server logic is exercised.
+├── grader.mjs                    ← (task 197): pure scoring functions + weight blending + end-to-end grade() per kind. Run with `node tests/grader.mjs`.
+├── session_records.mjs           ← (6D.1, ADR 0027): scrubSecrets (ADR 0022 shapes + JWT/DSN/assignments) + buildSessionDigest + resolveTranscriptPath (worktree-session lookup, #551). Fixtures built at runtime so no literal secret hits the scanner.
+├── session_search.mjs            ← (6D.2): the session-search ORDER BY whitelist (injection guard) + LIMIT clamp.
+├── session_eval.mjs              ← (6D.3 + 6D.4): classifyTurn / computeOverhead / detectFootguns / summarizeSystemicFindings, incl. a #506-shaped fixture.
+├── session_506_regression.mjs    ← (6D.5): the #506 regression gate — runs the engine over tests/fixtures/session-506-digest.json, asserts the hand-labelled findings (→#513/#514/#468) reproduce.
+├── grade_attempts.mjs            ← (6D.6): logGradeAttempt swallow-safety + param coercion via an injected queryFn (no DB).
+├── linkify_refs.mjs              ← (#604): the doc-linkifier classifier — pins which `#NNN` rewrite (tasks) vs stay bare (heading anchors, link targets, idea/blocker/session/PR ids, code spans), incl. comma-list entity inheritance + idempotency.
+├── sandbox_stage.mjs             ← (#927, ADR 0046): sandbox-first review gate — box detection, BOX_PREVIEW_HOSTNAME parsing, previewable-surface matching, decideShipGate table, tree-stamp freshness (temp git repo), runShipGate composition with injected fs/exec/prompt.
+├── session_start_freshness.mjs   ← (#1277, ADR 0067): the SessionStart freshness decision (decideFreshness) — pull ONLY on a clean `main` full clone strictly behind origin/main; warn in every other behind case; skip when up to date.
+└── public_task_resolver.mjs      ← (#604): the public `/public/tasks/:id` projection — title/value_summary exposed only for shipped|confirmed; withheld for in-flight so unshipped/security task names can't leak.
+```
+
+**Project skills** at `.claude/skills/` (drive Claude Code from inside a session):
+
+<!-- BEGIN GENERATED FILE-MAP .claude/skills/ (scripts/gds/gen-file-map.js — do not hand-edit; notes live in docs/file-map.notes.json) -->
+```
+.claude/skills/
+├── blocker-review/SKILL.md        ← /blocker-review — daily review of open GDS blockers (resolve / escalate / note); Metic+
+├── blocker-solve/SKILL.md         ← /blocker-solve N — drive ONE blocker to done: do the doable parts, hand back owner-only steps, verify, auto-resolve (auto-promotes waiters); Metic+
+├── builder-backup/SKILL.md        ← /builder-backup — check DB backup status or trigger a fresh local dump before risky changes (migrations, destructive SQL); no SSH required
+├── builder-box/SKILL.md           ← /builder-box — show the builder their own dev box (state, IP/host, cost, SSH keys) and help them (re)connect
+├── builder-claim/SKILL.md         ← /builder-claim N — atomic claim; prints the claim-time context pack + discipline playbook routing
+├── builder-connect/SKILL.md       ← /builder-connect — one-command connect of the builder's Claude Desktop to their Example dev box (ADR 0031)
+├── builder-cost/SKILL.md          ← /builder-cost — log a cost-ledger entry (api|compute|infra|domain|art|other)
+├── builder-end/SKILL.md           ← /builder-end — safely close out a session: resolve the claim (ship/release) + clean-git verify + worktree teardown + (on a dev box) offer to close the box; the bookend to /builder-start, and the own-scoped session close-out that /builder-exit redirects non-Archons to
+├── builder-exit/SKILL.md          ← /builder-exit — gracefully offboard (or reactivate) a builder: release claims, seal session logs, drop rank to xenos
+├── builder-key/SKILL.md           ← /builder-key — list API-key status, render the visual 'key needed' callout for anything missing, drive the UI-first Settings add-flow + re-sync/confirm; never accepts a key pasted in chat (task 1391)
+├── builder-reauth/SKILL.md        ← /builder-reauth — refresh an expired GDS CLI session the UI-first way (no terminal Device Flow)
+├── builder-redteam/SKILL.md       ← /builder-redteam — file a red-team / vulnerability report (severity, target, repro) to /api/gds/security
+├── builder-release/SKILL.md       ← /builder-release — abandon a claim (task returns to ready, no credits)
+├── builder-setup/SKILL.md         ← /builder-setup — one-time GitHub Device Flow auth (GDS); multi-builder-on-one-device gate
+├── builder-ship/SKILL.md          ← /builder-ship — record + award credits (runs touches[] scanner; warns on drift; sandbox-first review gate on dev boxes, ADR 0046)
+├── builder-stage/SKILL.md         ← /builder-stage — stage work on the builder's sandbox (sandbox-<login>) for browser review before shipping (#927, ADR 0046)
+├── builder-start/SKILL.md         ← /builder-start — list claimable tasks (parallel-safe vs active claims)
+├── close-box/SKILL.md             ← /close-box — tear down the dev box you're working on, from inside the box terminal (POST /box/close)
+├── design-sync/SKILL.md           ← /design-sync — export repo design tokens + surfaces into Claude Design (token-preview bundle) and land generated UI code back as a GDS task (ADR 0081)
+├── dev/SKILL.md                   ← /dev — engineering-session playbook for engineer-discipline tasks; the default understand→scoped-change→verify→ship loop made explicit ([#1272](https://example.com/builders#/task/1272))
+├── feedback/SKILL.md              ← /feedback — pull the latest Bongos feedback bundle (prompt.md + screenshot file paths) into a Claude Code session; backed by scripts/gds/feedback-latest.js (BV1.R13, ADR 0087)
+├── figma-design-sync/SKILL.md     ← sync UI-surface tokens/surfaces with Figma (push a frame plan, land a designer's Code Connect / MCP snapshot edit back as code) — the ADR 0081 human escape hatch; distinct from otb-figma-sync's pixel-art tile review (task 2048)
+├── goal-review/SKILL.md           ← /goal-review — walk the criterion review queue: each auto-flagged 'met — pending review' criterion gets confirm / reject / defer; confirming a goal's last criterion auto-achieves it (ADR 0086 §6); Metic+
+├── idea-triage/SKILL.md           ← /idea-triage — daily walk through the GDS idea_inbox (promote / discard / merge); Metic+
+├── ideate/SKILL.md                ← /ideate — ideation-session playbook for ideator-discipline tasks; inverts the loop (human drives, Claude is the sounding board) ([#1267](https://example.com/builders#/task/1267))
+├── merge-mode/SKILL.md            ← /merge-mode — manual fallback for the auto-merge: land every confirmed task (merge + smoke + deploy)
+├── new-project/SKILL.md           ← /new-project — the canonical zero-to-live onboarding runbook for a new STANDALONE instance (name+address → init → scaffold → provision → OAuth+verified-secret+sign-in → verify → brand); the CLI + hall wizard are forms over it ([#1981](https://example.com/builders#/task/1981))
+├── otb-character-review/SKILL.md  ← /otb-character-review — score a painterly character ANIMATION (same character / anatomy / pose / smooth motion) — the animation sibling of otb-design-review (ADR 0088)
+├── otb-design-review/SKILL.md     ← /otb-design-review — score a tile against the Example rubric
+├── otb-feedback-capture/SKILL.md  ← /otb-feedback-capture — verbal design feedback → a durable style_guide.md rule
+├── otb-figma-sync/SKILL.md        ← /otb-figma-sync — push tiles into the Example Figma file as a review canvas
+├── otb-tile-generate/SKILL.md     ← /otb-tile-generate — run the pixel-art pipeline (generate world tiles/sprites)
+├── paint/SKILL.md                 ← /paint — art-session playbook for artist-discipline tasks; show-first/low-text, drives the otb-* pixel-art pipeline underneath ([#1269](https://example.com/builders#/task/1269))
+├── planning-session/SKILL.md      ← /planning-session — run a structured planning session for an upcoming version (set criteria, brainstorm, rank, seed GDS); Metic+
+├── priority-session/SKILL.md      ← /priority-session — a trusted builder answers plain-speech questions; the answers reweight the idea_inbox + suggest what to build next
+├── read-session-export/SKILL.md   ← /read-session-export — read a Claude Code /export zip fast (prompts + thinking + tool calls → stdout); reads the existing export, doesn't make one. Backed by scripts/gds/read-session-export.js
+├── recall/SKILL.md                ← /recall — one-call project-knowledge search across repo docs + DB prose (tasks, learnings, session logs)
+├── session-handoff/SKILL.md       ← /session-handoff — compose a clean, paste-ready next-steps prompt to START a fresh session with (keeps context light by curating what carries forward); read-only, distinct from /builder-ship's ledger notes and /builder-end's close-out
+└── status/SKILL.md                ← /status — what's the status of X / what's left for criterion Cn (read-only rollup)
+```
+<!-- END GENERATED FILE-MAP .claude/skills/ -->
+
+**Scheduled tasks** at `.claude/scheduled-tasks/` (autonomous routines that fire on a cron — user-level dir `~/.claude/scheduled-tasks/` is symlinked to this repo path so each routine is version-controlled and reviewable):
+
+<!-- BEGIN GENERATED FILE-MAP .claude/scheduled-tasks/ (scripts/gds/gen-file-map.js — do not hand-edit; notes live in docs/file-map.notes.json) -->
+```
+.claude/scheduled-tasks/
+├── bfg/SKILL.md                     ← (MAS Phase 6, ADR 0026) BFG hygiene + read-the-room + steward routine: doc-vs-reality checks, memory hygiene, cross-builder learning. Read-mostly.
+├── bfg-session-eval/SKILL.md        ← (6D.3, ADR 0027) BFG session-inefficiency evaluator: search the session corpus, deep-dive wasteful sessions (ceremony-vs-work + footguns), file systemic findings. Read-only.
+├── box-dormant-reclaim/SKILL.md     ← (#598/ADR 0031) daily: deprovision dev boxes parked past the dormant threshold (pings the builder). Drives `box.js sweep-dormant --apply`. Control-plane only.
+├── box-idle-suspend/SKILL.md        ← (#598/ADR 0031) every 15 min: snapshot-and-park dev boxes idle past the idle threshold. Drives `box.js sweep-idle --apply`. Control-plane only.
+├── dep-audit-nightly/SKILL.md       ← autonomous nightly dependency-vulnerability scan on the droplet (`scripts/security/dep-audit.js --report-mode=nightly`) across npm + the devbox app
+├── diagram-drift/SKILL.md           ← belt-and-braces backstop for the onboarding diagrams — all five auto-regenerate on deploy, so this only flags any residual staleness
+├── idea-triage-nightly/SKILL.md     ← nightly autonomous walk of the idea_inbox; promotes high-confidence bugs/cleanups, discards obvious noise, defers ambiguous ideas
+├── main-audit/SKILL.md              ← (SEC #863 / ADR 0043) nightly post-push audit of `main` — flags commits where a sub-Metic builder edited a permission-sensitive surface
+├── newcomer-floor/SKILL.md          ← deterministic on-claim replenisher for the three evergreen newcomer chores (engineer/artist/ideator) — no cron; restocks when one is claimed (task 1168)
+├── newcomer-generator/SKILL.md      ← keep the newcomer_friendly task queue populated (C1) — deterministic generator tops the queue back up to its floor
+├── overnight-builder/SKILL.md       ← (#358) autonomous overnight session-runner: claims the highest-priority autonomous-fit task, works it in a fresh sub-agent, ships, re-polls. Archon-only. Runbook: docs/recipes/overnight-builder.md
+├── overnight-code-review/SKILL.md   ← nightly read-only code review; routes each finding into the idea_inbox (one row per finding; title prefix `[review YYYY-MM-DD]`)
+├── peer-vote-tally/SKILL.md         ← (V3.R25 / #245, C2) weekly tally of builder-on-builder peer votes into karma; folds votes ≥7 days old into karma_log
+├── repo-simplify-sweep/SKILL.md     ← weekly autonomous repo-cleanliness janitor: runs repo-metrics, files dead-code findings to the idea_inbox, auto-fixes the narrow safe class (unused vars/imports)
+├── security-review-weekly/SKILL.md  ← (V3.R69 / #288) autonomous weekly security-state review — surfaces stale vulnerability_reports + other stale-security signals
+├── skill-usage-review/SKILL.md      ← nightly skill-usage feedback loop: aggregates 24h of skill invocations, detects friction (over-invocation, errors), files findings
+└── stale-claim-release/SKILL.md     ← auto-release GDS claims whose session_pulses heartbeat went silent ≥ GDS_STALE_CLAIM_HOURS (default 6h); runs every 15 min on the droplet
+```
+<!-- END GENERATED FILE-MAP .claude/scheduled-tasks/ -->
+
+To install on a new machine, symlink each routine's directory under `~/.claude/scheduled-tasks/`, e.g. `ln -s "<repo>/.claude/scheduled-tasks/overnight-code-review" ~/.claude/scheduled-tasks/overnight-code-review`.
+
+**Claude Code hooks** at `.claude/hooks/` (wired in `.claude/settings.json`; all invoked via `node` so they run on Windows/macOS/Linux alike — [#671](https://example.com/builders#/task/671)):
+
+```
+.claude/hooks/
+├── worktree-guard.js         ← PreToolUse (Edit|Write|MultiEdit|NotebookEdit): DENY a write that lands in the wrong git checkout (main/sibling worktree) when the session is in a worktree — hands back the corrected worktree path. Fail-open; opt-out OTB_ALLOW_CROSS_TREE=1 (V4.R13, [#951](https://example.com/builders#/task/951))
+├── session-start.js          ← SessionStart: <redacted> .env.local into a fresh worktree, then chains onboarding-ship + rank-change greeting + memory pull
+├── rank-change-greeting.js   ← promotion/demotion greeting (V3.R28 #249); spawned by session-start.js, also runnable standalone
+├── pull-memory.js            ← memory pull-on-session-start (V3.R56 #275); spawned by session-start.js (kill-switches: OTB_MEMORY_PULL_OFF / OTB_SUBAGENT)
+├── recall-hints.js           ← SessionStart: when the session opens holding a claim, surface the top project-knowledge hits for that task via POST /api/gds/search (#963/V4.R25, ADR 0060)
+├── conductor.js              ← UserPromptSubmit: MAS Conductor advisory + dispatch directive (#427/#439); self-gates on OTB_CONDUCTOR_OFF / OTB_SUBAGENT
+├── session-cards.js          ← UserPromptSubmit: deterministic delivery of READ-ONLY in-session cards (builder-start, status) — pre-renders the card + injects a one-step render directive (task 1288)
+├── lifecycle-card.js         ← PostToolUse: deterministic delivery of MUTATING lifecycle cards (claim/ship/release) — the write-side mirror of session-cards.js (task 1288)
+├── pre-compact.js            ← PreCompact: thin reader around eviction-policy.js — emits an eviction directive (blocks to drop + one-line recovery stubs) at the compaction seam (task 1349)
+├── eviction-policy.js        ← pure deterministic in-session compaction classifier (transcript turns → eviction set + replacement stubs); no I/O, unit-tested in tests/eviction_policy.mjs; consumed by pre-compact.js (task 1348)
+├── stop-sound.js             ← Stop: completion sound on macOS (afplay; Glass / Hero on /tmp/otb-celebrate); silent no-op on other OSes
+└── stop-refcheck.js          ← Stop: deterministic backstop that catches a bare `#NNN` GDS ref in live session text (autolinks to a 404 GitHub issue) and asks for the clickable form (follow-on to task 929)
+```
+
+(Before [#671](https://example.com/builders#/task/671) these ran via `bash` shims — `sync-env-local.sh`, `conductor.sh`, `onboarding-ship-logs.sh`, `rank-change-greeting.sh`, `pull-memory.sh` — which failed on Windows without Git Bash. The Node entries above replaced them.)
+
+**On the droplet (`REDACTED_IP`):**
+
+```
+/home/lars/example/                ← git checkout (mirrors local + node_modules)
+                                          remote: origin → git@github-deploy:example-owner/example.git
+/home/lars/deploy.sh                    ← git pull + npm ci (if lock changed) + migrate + restart + smoke (healthz retried 15×@1s). Hand-maintained; byte-faithful repo mirror = scripts/deploy/deploy-prod.sh (#1026/ADR 0056). Backup of pre-#1026 version: ~/deploy.sh.bak-task1026
+/etc/caddy/Caddyfile                    (deploy: scp to ~/staging + sudo mv + sudo systemctl reload caddy)
+/etc/systemd/system/example.service (deploy: scp to ~/staging + sudo mv + sudo systemctl daemon-reload)
+/etc/caddy/origin.crt + origin.key      (Cloudflare Origin Cert, valid through 2041-05-04)
+```

package/docs/handoff-template.md

@@ -0,0 +1,92 @@
+# Session-end handoff — template
+
+> **Use this at the end of every working session.** Write your entry as its own dated file `docs/session-logs/YYYY-MM-DD-<slug>.md`. Soft cap: ~400 words per entry. The next Claude session — or the next human — should be able to pick up cold from this. **You never touch an index by hand:** the CLAUDE.md §13 recent-sessions snippet and the full `docs/session-log-index.md` are generated from the files and regenerate at ship (`scripts/gds/gen-session-index.js`).
+
+---
+
+## Template (copy this block)
+
+```markdown
+### YYYY-MM-DD — {short title of what shipped or what was attempted}
+
+**What shipped (with confidence tags):**
+- [verified-prod] {thing that was tested end-to-end on the live site by a real human}
+- [verified-smoke] {thing that passed an automated smoke test but wasn't manually verified}
+- [implemented-not-verified] {thing that compiles and deploys but hasn't been touched yet}
+
+**What's broken or unverified:**
+- {anything that's known not to work, or known to be untested — be honest, don't paper over}
+
+**Manual checks the next session should run first:**
+- {one-line action} → {expected result}
+- {repeat for each check}
+
+**Next obvious work:**
+- {the thing the next session should pick up, with enough context to start without re-reading much}
+
+**New limitations / risks / blockers introduced this session:**
+- {new V1 architecture limitation → added to limitations/current-version.md}
+- {new ops gotcha → long-form recipe under docs/recipes/, OR short rule via `node scripts/gds/learning-capture.js`}
+- {new blocker for Lars → POST /api/gds/blockers (the markdown file is frozen archive only)}
+- {(or "none")}
+
+**Generative ideas captured this session:**
+- {captured via `node scripts/gds/capture.js` (B2 idea_inbox), or "none". The markdown file is frozen archive only.}
+
+**Decisions made (linked to ADRs):**
+- {NNNN — title} (or "none — no architectural decisions this session")
+```
+
+---
+
+## Confidence tag definitions
+
+These tags are required on every "shipped" claim. They prevent the session log from quietly conflating "the smoke test passed" with "a real person used the feature in a real browser."
+
+- `[verified-prod]` — A human (Lars or me, in a deployed-to-production context) opened the live site and exercised the feature end-to-end. The thing demonstrably works for a real visitor.
+- `[verified-smoke]` — An automated smoke test (one of the `/tmp/colyseus-*-smoketest.js` scripts, a `curl /healthz`, etc.) exercised the feature against production or a faithful local equivalent. The code path runs; the user-visible behavior may or may not match.
+- `[implemented-not-verified]` — The code is written, committed, deployed, and the service didn't crash on startup. Nothing has actually exercised the feature. Flag for next session to verify.
+
+If a claim doesn't fit any of these tags, it doesn't belong in the "shipped" list — put it in "unverified" or "next obvious work."
+
+---
+
+## Definition of Done (applies to every "shipped" claim)
+
+A feature is "shipped" when **all five** are true:
+
+1. **Smoke tests pass** (or there is no relevant smoke test, explicitly noted)
+2. **Deploy succeeded** — `ci` mode (current): the PR auto-merged → the `deploy-prod` Actions run went green → `curl /healthz` returns 200 (legacy `laptop` mode: `git push` → `~/deploy.sh` → `/healthz` 200)
+3. **Manually verified in a real browser** on the live site (this is what `[verified-prod]` means)
+4. **Limitations / risks / blockers updated** if this work introduced or resolved any
+5. **Session log written** as a dated file in `docs/session-logs/` with this template (the §13 snippet + `docs/session-log-index.md` regenerate at ship — don't hand-edit them)
+
+If even one of these is false, the claim is `[verified-smoke]` or `[implemented-not-verified]`, not `[verified-prod]`.
+
+### Diagram backstop (task [#357](https://example.com/builders#/task/357); conceptual diagrams auto-generated [#436](https://example.com/builders#/task/436))
+
+If your change touched anything the onboarding diagrams describe — the **rank enum or which ranks are wired** (`requireRank`, `builders.rank` default, exit/assign paths), the **task-status set**, the **versions** (id/track/status), or the **complete-architecture** (the ADR 0024 memory chain + the dev-box → production ship flow) **/ drachmae-karma** models (which now flip per the **shipped** status of their backing tasks) — then before shipping:
+
+- **All five diagrams are auto-generated** by `scripts/gds/gen-diagrams.js` — run it (`node scripts/gds/gen-diagrams.js`) and confirm the result looks right; **do not hand-edit any `.mmd`**. The mechanical three (`01-task-lifecycle`, `02-rank-ladder`, `05-versioning`) regenerate from migrations + the public version API. The conceptual two (`03-drachmae-karma`, `04-architecture`) regenerate from the **authenticated** `/tasks/:id` status of their backing tasks (and 03's seeded-achievement count); if no session is present the generator skips them cleanly. Rendering produces both `.svg` (the pannable viewer asset) and `.png` (fallback).
+- To change a diagram's **layout or wording**, edit the matching template function in `gen-diagrams.js` — not the `.mmd`. `assertions.json` is rebuilt by the generator in lockstep, so you don't hand-maintain it.
+
+The `diagram-drift` routine is a belt-and-braces backstop (it should find nothing once the generator has run), but the point is not to rely on it — running `gen-diagrams.js` is part of the change.
+
+---
+
+## Why this template exists
+
+Past sessions varied wildly in length and rigor. Some session-log entries were ~1000 words of prose; others were a sentence. Without a template, the log is hard to skim and hard to trust. (Context-budget growth is now handled structurally — the prose lives in per-session files and only a bounded, generated snippet loads in CLAUDE.md §13.)
+
+This template forces:
+
+- **Skimmability.** Same shape every entry — eyes know where to look.
+- **Honesty about completion.** Confidence tags make it impossible to silently overstate "shipped."
+- **Continuity.** Manual-checks and next-obvious-work let the next session start in 2 minutes instead of 20.
+- **Bounded growth.** Soft 400-word cap keeps each file lean; CLAUDE.md carries only a generated, bounded recent-sessions snippet, so the always-loaded cost can't balloon.
+
+---
+
+## Old entries
+
+There is **no per-session compaction chore** anymore. CLAUDE.md §13 shows only a generated, bounded recent-sessions snippet (older entries roll off it automatically) and the full history is the generated [`docs/session-log-index.md`](session-log-index.md) — neither is hand-maintained. Trimming very old prose from `docs/session-logs/` into `docs/session-log-archive.md` is optional on-disk housekeeping; it no longer affects the loaded-every-session context cost.