@bongos/core 1.17.0

package/docs/adr/0108-instance-composition-configurable-root.md

@@ -0,0 +1,87 @@
+# ADR 0108 — Instance composition topology: configurable-root (the core is consumed as a versioned npm dependency)
+
+- **Status:** Accepted
+- **Date:** 2026-07-03
+- **Track:** internal
+- **Task:** [#1870](https://example.com/builders#/task/1870) (BV1.R115) — the decision this ADR records.
+- **Decides:** *how* a consumer instance physically composes with the extracted Cloud Bongos core — the composition **mechanism** that [ADR 0062](<redacted>.md) §10, [ADR 0100](<redacted>.md) §1, and [ADR 0103](<redacted>.md) §2 each left open. Those ADRs decided the repo *count* (two), the *order* (core-first), and per-repo GDS; they are deliberately mechanism-neutral ("installs a pinned core + layers its own content on top"), and [ADR 0103](<redacted>.md)'s R88 execution record explicitly deferred "the topology/instance paths the scaffold populates on `init`." This ADR resolves that deferral.
+- **Replaces:** the never-shipped clone-and-layer draft of this same ADR number. A 2026-07-03 owner review rejected clone-and-layer in favour of the scalable model below — optimising for upgrade economics + a real product boundary over near-term least-resistance. (No supersession machinery: the draft never merged.)
+- **Builds on:** [ADR 0062](<redacted>.md) §1 (core/host cut-line), [ADR 0098](<redacted>.md) (`isPublishable()` — now "the core *package* contents"), [ADR 0100](<redacted>.md) §§3–4 (per-repo GDS + conditional mirror, both retained), [ADR 0103](<redacted>.md) (core-first extraction; R88 shipped → `cloud-bongos`), [ADR 0105](<redacted>.md) (the `migrations/instance/` split), [ADR 0083](<redacted>.md)/[ADR 0061](<redacted>.md) (the module boundary + fitness functions), [ADR 0082](<redacted>.md).
+- **Informs:** [#1689](https://example.com/builders#/task/1689) (R85 — Mercury, the first real consumer + the contract's validator), [#1690](https://example.com/builders#/task/1690) (R86 — the `bongos upgrade` channel), [#1728](https://example.com/builders#/task/1728) (R89 — the Example split), plus the net-new workstreams enumerated in §Consequences.
+
+## Context
+
+[ADR 0103](<redacted>.md) extracted the Cloud Bongos core into its own repo (R88, [#1727](https://example.com/builders#/task/1727), shipped 2026-07-03) and committed Mercury (R85) and Example (R89) to becoming *consumer repos on a pinned core*. It left the composition **mechanism** open. Two shapes were possible:
+
+- **Clone-and-layer** — the consumer repo *is* the pinned core tree materialised at its **root**, host content layered on top; the core keeps sitting at repo-root, so its pervasive repo-root path assumptions keep working unchanged.
+- **Configurable-root** — the core is installed as a **versioned dependency** (`@cloudbongos/core` in `node_modules/`) and resolves host content through an **injected instance-root**, so it no longer assumes it lives at the repo root.
+
+A 2026-07-03 owner review chose **configurable-root**, explicitly weighting **scalability over least-resistance**. The decisive arguments: upgrades become an **O(1)-per-instance version bump** instead of an O(instances × drift) source merge; the core↔host boundary is enforced by the **packaging** (editing `node_modules` is obviously wrong and install-clobbered) rather than by convention + CI that *will* erode across many AI-agent builders and many instances; a dependency forces a **real public API/contract** on the core (the discipline that lets a platform serve many consumers without breaking them); instance repos stay **small and legible** (host content only); and "root is a parameter" is the precondition for any future **multi-instance / hosted** offering. Clone-and-layer dead-ends every one of those and would need this same refactor later anyway — under more pressure, on more instances, and on a live product.
+
+A five-surface sweep ([#1870](https://example.com/builders#/task/1870)) established the real blast radius, and it is **lopsided**: the runtime-library change is small and already half-scaffolded; the genuine work and risk live in *delivery and operations*. The evidence:
+
+- **The entrypoint seam already exists.** Three boot paths ship today — `server.js` (game + platform), `src/platform-server.js` (platform-only, zero game code), `src/preview-server.js` (game-only). The platform is exposed as `mountInternalSurfaces(app)` / `buildPlatformApp()` — ready-made core-package exports. The game is a seam-registered module, not wired into core boot.
+- **The core runtime is thin.** Core deps are `express` + `pg` (+ an `undici` pin). The five Colyseus/Phaser libs are game-only; `discord.js`/`sharp` are optional-module.
+- **The data/boundary partition is already single-sourced.** `publish-manifest.js`'s `isPublishable()` is the one authority; `package-core` consumes it (no second list); fitness Check 16 already hard-fails a core file that `require()`s an instance-excluded config (the R88 boot crash).
+- **The module loader is already two-roots-capable.** `discoverModules({roots})` iterates a roots array and errors on cross-root key collisions; only `DEFAULT_ROOTS` is hardcoded.
+- **Only ~8–11 files** resolve *instance* content off a `__dirname/../..` root and actually break under packaging (`branding.js`, `modules.js`, `hierarchy-config.js`, `pool.js`, the design adapter, `loader.js`, `serve-internal.js`, `migrate.sh`, `bin/bongos.js`, + a couple of scripts). The existing `src/instance-config.js` already solves the *sibling-identity* problem (config dir + env prefix) with a "OTB pins its values → zero change; vanilla → neutral" discipline — it is the template and the home for the fix.
+- **The runtime substrate for a vanilla boot already exists** — `docker-compose` + `platform-server.js` boot GDS-only via `PG*` env, and `selfhost-boot.yml` CI proves a fresh empty Postgres boots vanilla with zero instance-data leakage.
+
+The friction, instead, is concentrated in three places (detailed in §Consequences): the `.claude/` methodology surface cannot live in `node_modules`; deploy today is a `git reset --hard` on a shared checkout; and two independently-versioned repos will collide on migration numbering.
+
+## Decision
+
+### 1. The core is consumed as a versioned npm dependency; host content resolves through an injected instance-root.
+
+Introduce two resolvers in the existing `src/instance-config.js`, extending its established zero-risk pattern from `~/.config` to the in-repo roots:
+
+- **`resolveInstanceRoot()`** → where **host** content lives (`config/`, instance `modules/`, `migrations/instance/`, instance identity). Precedence: `<PREFIX>_INSTANCE_ROOT` env → a `bongos.config` pointer → `process.cwd()`.
+- **`resolveCoreRoot()`** → where the **core package's own** files live (core `modules/`, core `migrations/`, the `infra/` installers, the neutral config defaults). When packaged: the `node_modules` package dir; today: `path.resolve(__dirname, '..')`.
+
+The two directions are **opposite and both load-bearing**: config resolves from the *instance* root (with the `*.neutral.json` default in the *core* root); the `infra/bongos-install.{sh,ps1}` files that `serve-internal.js` serves resolve from the *core* root. A naive "use the instance-root everywhere" breaks the installers — this distinction is the crux of the `serve-internal` fix.
+
+**Today both resolvers return the current repo root** (because `process.cwd()` === `__dirname/../..` === repo root in the single checkout), so routing the ~8–11 sites through them is **byte-identical for the live instance** — verified by the existing suite + a vanilla boot. Packaging later flips `resolveCoreRoot()` to the `node_modules` dir; the split becomes real with **no further per-site edits**.
+
+### 2. `package-core` emits a real, installable npm package.
+
+`isPublishable()` stays the single definition of "the core" — now "the package contents." `package-core` additionally: synthesises a `package/`-rooted `package.json` (`name` `@cloudbongos/core`, `version` = `CORE_VERSION`, `main` → `platform-server.js`, `exports` for `mountInternalSurfaces`/`buildPlatformApp`/the module-API, `bin` → `bongos`), **prunes** the game/art deps (leaving `express`/`pg`/`undici`), and ships a pruned lockfile. Today it ships the repo's game-heavy `package.json` verbatim under a `cloudbongos-core/` tar root — neither is package-installable.
+
+### 3. The `.claude/` methodology surface is materialised into the instance, not resolved from `node_modules`.
+
+Claude Code discovers `.claude/settings.json`, `hooks/`, and `skills/` from the **project root**, never from a dependency — so `bongos init`/`upgrade` must **materialise `.claude/` into the instance repo**, and the ~30 skills + the `settings.json` hooks must be rewritten from `node scripts/gds/…` to the **`bongos` bin** (which already resolves the heavy CLI — `ship.js`, the grader, `src/bongos/*` — inside the package). This formalises a split the publish boundary already encodes (skills ship in the core; hooks + `settings.json` are "topology"). The materialisation step is **net-new** — `init` writes only `config/` today.
+
+### 4. `bongos upgrade` (R86) is a dependency version bump, not a snapshot-merge.
+
+Upgrading = bump the pin in `package.json`/lockfile → `npm ci` → migrate → restart. Deploy shifts from the droplet `git reset --hard origin/main` model to **`git pull` the instance repo → `npm ci` (installs the pinned core) → migrate core + instance → start `platform-server.js` with the instance-root**. The Docker/`platform-server`/`selfhost-boot` substrate already models this shape.
+
+### 5. Cross-repo migration numbering gets an explicit namespacing discipline.
+
+`migrate.sh`'s basename merge-sort already orders files from arbitrary directories correctly (and keys idempotency on basename), so feeding it **three roots** (core-package / instance / module) works mechanically. But two independently-versioned repos both adding `NNN_*.sql` **will collide** on the shared `schema_migrations` stem key. Core migrations therefore get a core-owned namespace/prefix distinct from instance migrations, plus a lineage/numbering-divergence check (reuse the public mirror's existing pattern). Fitness Check 11's "additive + namespaced" rule extends to cover this.
+
+### 6. Land incrementally and Mercury-first, so live prod is de-risked.
+
+- **Step 1 lands now, zero-behaviour-change:** the two resolvers (defaulting to repo-root) + routing the ~8–11 sites through them. Good hygiene even if no split ever happened; verified against the suite + a vanilla boot.
+- **Steps 2–3** (real package + `.claude/` materialisation) prove out on **greenfield Mercury (R85)** — the first consumer defines the contract.
+- **R86** makes `bongos upgrade` a real version-bump channel, driven by Mercury's first core bump.
+- **Example splits last (R89)** — and the trust-boundary-adjacent path sites (`route-rank-check.js`, `routes/backup.js`, `routes/builders.js`) plus the two-root awareness the guardrails need (see §Consequences) get a **security review** before they touch live prod.
+
+## Alternatives considered
+
+- **Clone-and-layer (the prior draft of this ADR).** Cheapest now, proven by the two proofs (cloudbongos.com reskin + the `package-core` tree snapshot), zero core-path changes. **Rejected as the destination:** merge-based upgrades don't scale across many instances × core versions; the boundary is convention + CI and rots under scale; there is no forcing function for a clean core API; and it dead-ends any multi-instance/hosted future — needing this exact refactor later regardless, under worse conditions. **Retained** only as the cheap single-checkout reskin shape (cloudbongos.com).
+- **Git submodule for the core.** Rejected — still lands the core at a subpath (so it still needs configurable-root; it doesn't avoid the refactor) and adds the submodule UX tax on an AI-agent-first builder base.
+- **One monorepo with an internal `core/` + `instances/` cut.** Already rejected in [ADR 0103](<redacted>.md) — the core never becomes a separately shippable product.
+
+## Consequences
+
+**More work now — the "pain" is real and concentrated in three net-new workstreams plus a cross-cutting guardrail fix:**
+
+1. **`.claude/` materialisation + invocation rewrite** (§3). `bongos init`/`upgrade` must copy `.claude/` into the instance and rewrite ~30 skills + the `settings.json` hooks to the `bongos` bin. This is what makes an installed instance actually usable by AI agents; it does not exist today.
+2. **Deploy conversion** (§4). `git reset --hard` → `npm ci`-of-the-pinned-core; `ship.js` (~151 KB, a monorepo-coupled deploy tool) needs rework; and the **shared-checkout dual-instance deploy** (example + cloudbongos.com on one tree — already the reason cloudbongos.com runs stale) must be cut *in tandem* with standing up the npm-install flow, or cloudbongos.com breaks.
+3. **Cross-repo migration numbering** (§5) — the deepest design risk; needs the namespacing + lineage discipline before two repos version independently.
+4. **The guardrails become two-root-aware.** `fitness.js`, `gen-repo-map.js`, and `gen-file-map.js` each hardcode `REPO_ROOT = __dirname/../..` and walk one tree; once the core is in `node_modules`, the core↔host boundary check, the CLAUDE.md-budget check, the nested-doc-presence check, and the two generators would inspect the wrong tree. They must learn the core-root/instance-root split — this is the mechanism [ADR 0062](<redacted>.md) §9 / [ADR 0061](<redacted>.md) rely on to keep the boundary from rotting, so it matters *more* under a real repo gap, not less.
+
+**But the runtime-library half is small and de-risked:** ~8–11 readers through the resolvers, and the entrypoint seam, the two-roots loader, the single-sourced `isPublishable()` partition, and the Docker/vanilla-boot substrate all already exist. Step 1 is byte-identical for prod, which lets the risky part land reversibly and early.
+
+**Docs to amend** (none *superseded* — this ADR resolves the mechanism they deferred, so they get cross-refs, not reversals): `docs/file-map.md` (present the tree as two — core-package vs instance), `docs/architecture.md` (repo + deploy), `docs/recipes/packaging-the-core.md` + `docs/recipes/self-host.md` (npm consumption + mount targets), [ADR 0105](<redacted>.md) (three-root migrations), `docs/modules-contract.md` (two-root discovery); cross-refs in [ADR 0062](<redacted>.md)/[0100](<redacted>.md)/[0103](<redacted>.md)/[0098](<redacted>.md), `docs/branding-contract.md`, and `CLAUDE.md` (whose nested-doc discovery model assumes core dirs sit at the instance root — they will live in the package). Keep within the CLAUDE.md 300-line / 42 KB fitness ceiling — relocate detail here, don't expand CLAUDE.md.
+
+**Commitments:** R85 is built as `npm install`-of-the-core + configurable-root (and becomes the contract's validator); R86 is a version-bump channel; R89 keeps the risky path/guardrail/trust-boundary changes behind a security review. **No migration, no new criterion** minted by this ADR; recorded against goal 26 (Cloud Bongos productization and self-host).

package/docs/adr/0109-self-describing-openapi-and-hosted-docs.md

@@ -0,0 +1,44 @@
+# ADR 0109 — The GDS API is self-describing: generated OpenAPI 3.1 + a hosted `/docs` site
+
+- **Status:** Accepted
+- **Date:** 2026-07-03
+- **Track:** internal
+- **Task:** [#1918](https://example.com/builders#/task/1918) (BONGOS-V1) — Part A of the API-docs + `/api/gds`→`/api/bongos` rename plan.
+- **Decides:** how the GDS API is documented so an AI agent (or any tool) can read it, and where that documentation is hosted.
+- **Builds on:** [ADR 0016](<redacted>.md) (server-enforced ranks — the gate each endpoint carries), [ADR 0063](<redacted>.md) (the "generate, don't hand-maintain, enforce with `--check`" pattern this copies), [ADR 0062](<redacted>.md) §3 (branding-injected served HTML), [ADR 0108](<redacted>.md) (two-root generator conventions).
+- **Informs:** the `/api/gds` → `/api/bongos` URL + naming rename (Part B), which flips the single `src/bongos/api-prefix.js` constant this ADR introduces.
+
+## Context
+
+The GDS API had **no machine-readable contract**. The only endpoint doc was `docs/routes-permissions.md` — a hand-maintained mirror that, by its own admission, drifted from the code (it claimed "154 registrations" against a live ~199). An AI agent hitting the API had nothing standard to consult, and every regeneration of the surface widened the gap. The prompter's ask: *"the GDS API needs to be better documented for AI to read"* and *"host this on cloudbongos.com/docs like others do."*
+
+Two things were already true and shaped the answer:
+
+1. **A route-introspection engine already exists and is CI-enforced.** `src/bongos/route-rank-check.js` (`discoverRouteFiles` + `classifyText` + `classifyRank`) already enumerates every endpoint — method, path, rank gate, source file — across core + every module, because the ship-time rank gate ([ADR 0016](<redacted>.md)) depends on it. It is the natural, non-drifting backbone for docs.
+2. **A generator pattern is established** ([ADR 0063](<redacted>.md)): a deterministic file-reader with a `--check` mode wired into `fitness.js` and auto-regenerated at ship. Docs generated the same way cannot rot.
+
+## Decision
+
+**1. Generate an OpenAPI 3.1 spec from the live routes.** A new `scripts/gds/gen-api-docs.js` reuses `route-rank-check.js` to emit `docs/api/openapi.json` (the industry-standard format every tool — Postman, Swagger, Redoc, LLM tool-callers — already reads), plus a generated `docs/api-reference.md`. Each operation carries its rank in an `x-rank` extension + a `security` reference, its path params, and — best-effort from the route's `validateOrRespond` schema — its request-body field names. Endpoints whose body has no validator are marked `x-body-undocumented` and **counted**, so the gap is visible rather than silently absent. The old `docs/routes-permissions.md` is replaced by a generated pointer stub.
+
+**2. Host a rendered docs site at `/docs`.** A vendored Redoc bundle (`public-docs/`, self-hosted — no CDN, matching the `/vendor/*` convention and staying CSP-safe) renders the spec. `serve-internal.js` serves `GET /docs` (branding-injected), `GET /docs/openapi.json` (CORS-open so external tools + AI can fetch it), and `GET /docs/redoc.standalone.js` — in the **shared** `mountInternalSurfaces`, so **every instance is self-documenting for free** and `cloudbongos.com/docs` is the advertised canonical URL. No Caddy change: the `cloudbongos.com` block already proxies non-gate paths to the platform process.
+
+**3. Make the API self-discoverable.** `GET /api/gds` (the base path) returns a small JSON index pointing at `/docs` + the spec, and the API-shaped 404 hint now names `/docs` — so an agent that hits the API bare finds the contract on its own.
+
+**4. Introduce a single prefix chokepoint.** `src/bongos/api-prefix.js` exports `API_PREFIX` (still `/api/gds`), consumed by the mount, the generator, the discovery route, and `context-pack.js`. This is deliberately the seam Part B flips to `/api/bongos` (adding `/api/gds` to `LEGACY_API_PREFIXES` for the permanent dual-mount) — turning a ~1,158-literal rename into a one-line change.
+
+**5. Enforce freshness.** `gen-api-docs.js --check` (which also structurally validates the spec is OpenAPI 3.1) is wired into `fitness.js` and regenerated at ship, exactly like the repo-map / session-index / file-map generators. `npm run docs:api:lint` runs the full standard `@redocly/cli` lint on demand (kept out of the critical path to avoid a heavy dependency; the spec validates clean, zero warnings).
+
+## Alternatives considered
+
+- **A hand-written/OpenAPI-by-annotation spec (JSDoc `@openapi`).** Rejected: it reintroduces exactly the drift that killed `routes-permissions.md`. Generating from the enforced route set is the only non-rotting option.
+- **Swagger UI instead of Redoc.** Either works over the same spec; Redoc is a single MIT bundle with a cleaner default read view. The renderer is a presentation choice — the *contract* (openapi.json) is the deliverable, and it is renderer-agnostic.
+- **A CDN-hosted renderer.** Rejected: the codebase self-hosts all assets (no CSP today, but one "may be added later") and a self-hosted instance may be air-gapped. Vendoring (~1 MB) is the convention-matching, portable choice.
+- **`@redocly/cli` as a hard CI dependency.** Rejected for the critical path: it is a large dependency tree in a deliberately lean, bootstrapped project. A dependency-free built-in structural validator runs in `fitness`; the full standard lint is available via `npm run docs:api:lint`.
+
+## Consequences
+
+- The API is now documented in a standard, tool-consumable format that cannot drift from the code, and is browsable by humans + AI at a stable URL on every instance.
+- `docs/routes-permissions.md` is retired to a stub; references were re-pointed at `docs/api-reference.md`.
+- Best-effort body extraction leaves 21 write endpoints with undocumented bodies (no validator schema) — a visible, counted backlog; adding a `validateOrRespond` schema surfaces them automatically.
+- Part B (the URL rename) is now a one-line flip of `src/bongos/api-prefix.js` + the dual-mount, with the docs regenerating to the new canonical prefix for free.

package/docs/adr/0110-untrack-whole-file-generated-nav-docs.md

@@ -0,0 +1,49 @@
+# ADR 0110 — Move whole-file generated navigation docs off the git graph; regenerate as deploy/box outputs
+
+- **Status:** Accepted
+- **Date:** 2026-07-03
+- **Track:** internal
+- **Builds on:** [ADR 0094](<redacted>.md) (the `gen-atlas.js` precedent — a gitignored artifact rebuilt on every deploy), [ADR 0063](<redacted>.md) (`gen-repo-map.js`), [ADR 0062](<redacted>.md) §8 (`gen-session-index.js`), [ADR 0082](<redacted>.md) (the reactive `otb-regen` heal — kept, not replaced), [ADR 0055](<redacted>.md) (server-mediated publish — untouched)
+- **Task:** [#1926](https://example.com/builders#/task/1926)
+- **Supersedes (in part):** the "regenerated + committed at ship" contract for `docs/repo-map.md` and `docs/session-log-index.md` (ADR 0063 / ADR 0062 §8). The nested-block half of that contract stands.
+
+## Context
+
+Every `/builder-ship` regenerated and **committed** up to four generated artifacts onto the shipping builder's feature branch — `docs/repo-map.md`, `docs/session-log-index.md`, the OpenAPI docs, and (render-capable ships) the diagrams — plus the file-map. Because these are rebuilt deterministically from the whole tree, two builders working in parallel produce *different* copies and their branches **collide on nearly every merge**. ADR 0082 built a reactive heal (the `otb-regen` merge driver + a server-side resolver) that untangles these collisions after the fact — but it treats the *symptom*. As the platform pushes toward multi-builder parallelism (BONGOS-V1), the healing cost grows with the number of concurrent branches, and a confirmed PR can still stall waiting on the ~5-minute reconciler.
+
+The owner asked to remove the **dependency at the source**, not keep patching the collision. A design workflow (2026-07-03, 11 agents, adversarially reviewed) mapped the artifacts and found they split cleanly into two kinds:
+
+- **Whole-file generated** — every byte is machine-owned (`docs/repo-map.md`, `docs/session-log-index.md`, the OpenAPI spec + reference, the diagram renders). A file like this need not live in git at all.
+- **Hybrid** — hand-written prose with a generator-owned block between markers (the three nested `CLAUDE.md` symbol blocks; the `CLAUDE.md` §13 "recent sessions" snippet; `docs/file-map.md`'s two sections). These **cannot** leave git without deleting the human prose.
+
+The `gen-atlas.js` precedent (ADR 0094) already proved the pattern for the whole-file kind: gitignore the artifact and regenerate it server-side on every deploy into the served directory — untracked, so `git reset --hard` never wipes it and no branch can ever diff it. The deploy-prod.sh atlas comment even names this as "the model the doc generators migrate onto."
+
+## Decision
+
+Apply the atlas pattern to the two **whole-file navigation** artifacts — `docs/repo-map.md` and `docs/session-log-index.md` — in this pass. (The OpenAPI spec and the diagram renders are deferred to follow-up tasks: the spec has external consumers and wants a bounded freshness bot; the diagrams need verified headless-Chromium handling. `docs/file-map.md` is hybrid and stays as-is.)
+
+1. **Untrack + gitignore** `docs/repo-map.md` and `docs/session-log-index.md` (`git rm --cached` + `.gitignore`). They can no longer appear in a branch diff, so the collision class is gone at the source.
+2. **Regenerate at deploy** — `scripts/deploy/deploy-prod.sh` runs both pure-JS generators beside `gen-atlas.js`, best-effort, and **LOUD on failure** (`::ERROR::` → journald) so a broken generator surfaces instead of silently serving a stale/absent map (this advances goal 24 / criterion `gcarry-pipe-loud`).
+3. **Regenerate at box-source-fetch** — `infra/box-source-fetch.sh` regenerates them after the credential scrub so a fresh dev-box clone has them for the `/dev` skill and the §13 links (additive, best-effort, never touches the security path).
+4. **Split the CI freshness gate.** Both generators are **dual-duty** — each also refreshes a *tracked* block (the nested `CLAUDE.md` symbol blocks; the `CLAUDE.md` §13 snippet). The old `--check` bundled the whole file and the block into one exit code, so naively relaxing it would silently drop the block gate too (the adversarial review's fatal flaw). Instead each generator now exposes `--check-block` (tracked block only) and `--check-whole` (the gitignored whole file); `fitness.js` gates the **block bucket HARD** via `--check-block`. The whole-file freshness moves from a merge-time invariant to a deploy-time one.
+5. **Ship-time regen keeps only the tracked blocks.** `ship.js`'s `regenerateRepoMap`/`regenerateSessionIndex` still run the generator (which writes the gitignored whole file harmlessly) but drop the gitignored paths from their `git add`/`git status` lists — an explicit `git add <ignored path>` **aborts the whole command** (exit 1), which would have dropped the nested-block commit.
+
+## Why this is safe — and never worse than today
+
+- **No bot ever commits to `main`; the trust boundary is untouched.** The whole files are written as untracked files on the droplet after `git reset --hard`, exactly like `atlas.json` — no push credential, no branch-protection bypass, zero change to ADR 0016/0043/0055. No `.github/workflows/` file is added (the server App token can't land those).
+- **The reactive heal is retained, not deleted.** `git-merge-regen.js`, its `REGENERABLE` set, the `.gitattributes` drivers, and the ADR 0082 server resolver are **unchanged**. Once the two files are gitignored they simply never appear in a diff, so the driver is a harmless never-triggered backstop for them — and it still actively heals the hybrid docs (`file-map.md`, nested `CLAUDE.md`) that remain tracked. During the transition it also still covers any in-flight branch that already committed the old files.
+- **The block gate stays hard.** A code change that didn't regenerate its nested block, or a session change that didn't regenerate the §13 snippet, still fails its PR via `--check-block`. Only *whole-file* drift is no longer gated (there's nothing committed to gate).
+
+## Consequences
+
+- The `repo-map.md` / `session-log-index.md` collision class — a recurring multi-builder merge cost (the PR #167 lineage) — is eliminated at the source. Ship drops up to two bookkeeping commits per session.
+- **Accepted staleness:** the *served/on-disk* whole files are fresh only *after deploy* (or a box-fetch tick), not at merge. For navigation indexes this is tolerant by nature — worst case an agent's symbol map is a few minutes stale. A generator that breaks at deploy leaves a stale/absent file with no *blocking* backstop; the LOUD `::ERROR::` line is the alarm (mandatory, not optional).
+- **Transition wrinkle:** a branch that already committed either file before this lands will hit a one-time modify/delete conflict on its next merge with `main` (resolve = keep deleted). New branches never touch the files.
+- **Fresh pristine checkout:** a bare `git clone` that never runs a generator lacks the two files, so a markdown link to them (e.g. the CLAUDE.md nav row, the §13 snippet's "full history" link) points at an absent path *there only*. Nothing hard-checks links in that state; every real environment (box, deploy) regenerates them. `docs-entropy` (a scheduled scanner, not a CI gate) runs where they exist.
+- The generated-artifact set is now defined per-bucket; adding a future gitignored generated file means: `.gitignore` + a deploy-prod.sh regen line + a box-source-fetch line + a `--check-block`/`--check-whole` split if it is dual-duty.
+
+## Alternatives considered
+
+- **Post-main regen bot / cron that re-commits the files** (the owner's two original ideas) — rejected as the *primary* mechanism: both keep the files in git, weaken the freshness gate for every content PR, burn CI on regen PRs, and (there is no GitHub webhook in this codebase) can only poll anyway. "Don't commit the file" is strictly simpler than "automate re-committing it." The bounded bot survives only for the API spec (a follow-up task), which has external consumers.
+- **Strengthen the reactive heal only** (ADR 0082++) — rejected: makes conflicts invisible, not absent; the per-branch bookkeeping commits and the heal latency remain, and the cost grows with parallelism.
+- **Trim `docs/repo-map.md` from `REGENERABLE`/`.gitattributes`** — deferred: it would force a rewrite of `tests/git_merge_regen.mjs` (which uses repo-map as its canonical whole-file heal fixture) for no real gain, since a gitignored file never reaches the driver anyway. Leaving the entries in place is the lower-risk transition posture.

package/docs/adr/0111-instance-hosting-provisioning-module.md

@@ -0,0 +1,135 @@
+# ADR 0111 — Instance hosting + domains as a Cloud Bongos module: the `provisioning` module boundary + the self-host / managed split
+
+- **Status:** Accepted (boundary + split decided with the owner; build is task-pending — see §Consequences for the seeded tasks)
+- **Date:** 2026-07-03
+- **Track:** internal (a portable Cloud Bongos platform capability)
+- **Task:** [#1485](https://example.com/builders#/task/1485) (BONGOS-V1, goal 26 — *Cloud Bongos productization and self-host*) — "spec the module boundary + the self-host vs managed split **before** tasking."
+- **Deciders:** Lars (Archon), Claude
+- **Consolidates:** idea [#345](https://example.com/builders#/idea/345) (owner — *"offer hosting + domain services directly as a module when people start a Cloud Bongos project… configured with the API"*) + idea [#303](https://example.com/builders#/idea/303) (owner, deferred from the 2026-06-17 planning — *optional managed-hosting layer: operate branded instances for owners, push updates centrally, same self-host artifact*).
+- **Decides:** (1) that "hosting + domains" ships as a **new `provisioning` module** (NOT the ADR 0092 `hosting` key — see disambiguation below), and its boundary; (2) how the web tier provisions real infra **without holding cloud credentials**; (3) what "provision an instance" composes; (4) domain + TLS handling; (5) the **self-host vs managed split** — both run the identical artifact, and what actually differs; (6) the cost posture; (7) sequencing.
+- **Builds on:** [ADR 0062](<redacted>.md) (core↔host instance model), [ADR 0108](<redacted>.md) (the core as a versioned npm dependency — "the same self-host artifact"), [ADR 0065](<redacted>.md) §2 (managed hosting is a service *on top of* the same AGPL artifact), [ADR 0031](<redacted>.md) (the dev-box lifecycle — the reusable provisioning substrate + trust-boundary pattern), [ADR 0083](<redacted>.md) (the module system this ships as), [ADR 0016](<redacted>.md) (server-enforced trust boundary the module must never weaken), [ADR 0100](<redacted>.md) §3 (per-repo GDS — locked; a managed fleet sits *above* it).
+- **Relationship to [ADR 0092](<redacted>.md) (name-collision, resolved):** ADR 0092's `hosting` module answers *"where do compute/storage **workloads** run"* (LLM inference, imagegen, embeddings, training, blob storage — brokered to a target such as the warehouse GPU box). **This ADR is a different layer:** *"stand up + operate a whole Cloud Bongos **instance's own infrastructure** — server, database, domain, DNS, TLS."* Same English word "hosting", two concerns. To avoid the "contribution seam" naming-collision lesson ([ADR 0107](<redacted>.md) §Context), this module takes the distinct key **`provisioning`**; ADR 0092 keeps `hosting`. This ADR does **not** re-open or supersede 0092.
+
+---
+
+## Context
+
+**What the ideas ask for.** Today, standing up a Cloud Bongos instance still leaves the owner with an irreducibly-manual infrastructure checklist. Idea 345 wants those steps offered *as a module, configured via the API*, so an owner doesn't manage infra by hand. Idea 303 wants an optional layer where Cloud Bongos *operates* branded instances for owners and pushes updates centrally — explicitly on the *same self-host artifact*.
+
+**What already exists (the reusable substrate).**
+
+- **The instance model is real and proven.** cloudbongos.com is a live second instance (shipped 2026-06-21): its own database, its own process/port, neutral branding, zero game code, **$0/mo extra** because it co-tenants the existing $14/mo droplet ([`docs/recipes/cloudbongos-standup.md`](../recipes/cloudbongos-standup.md)). An instance = a branding pack + enabled modules + owner/repo/OAuth binding + its own DB ([ADR 0062](<redacted>.md) §2).
+- **"The same self-host artifact" is defined.** [ADR 0108](<redacted>.md): the core is packaged as `@cloudbongos/core` (`scripts/gds/package-core.js`, `core_version 1.14.0`, pinned by `tree_sha256`) and consumed as a versioned npm dependency via `resolveCoreRoot()`/`resolveInstanceRoot()` in `src/instance-config.js`. Central updates = `bongos upgrade` (a version-pin bump → `npm ci` → migrate → restart) — **O(1) per instance, not an O(instances × drift) merge**. (`bongos upgrade` is a stub until R86; the channel is specified, not yet exercised.)
+- **`bongos init` scaffolds a project** (`scripts/gds/init.js`): an interview writes lean `config/branding.json` / `config/modules.json` / `config/hierarchy.json` overrides, materialises `.claude/`, seeds a first version + goal, and — critically — files the **irreducibly-manual owner steps as tracked kickoff tasks** rather than pretending launch is one command: register a GitHub OAuth app, first owner sign-in (seats the founding Archon), confirm the repo binding, and "production topology: TLS, real origins, managed Postgres." **That kickoff list is precisely the surface this module automates.**
+- **Programmatic infra provisioning already works — for dev boxes.** The dev-box lifecycle ([ADR 0031](<redacted>.md)) creates/parks/wakes/destroys DigitalOcean droplets (`modules/dev-box/do-api.js`, DO API v2, dry-run by default), manages Cloudflare DNS records (`infra/box-dns-cloudflare.sh` — UPSERT + a blackhole-on-retire that avoids NXDOMAIN caching), boots servers unattended via cloud-init, and prices resources from a `SIZE_CATALOG` cost ledger. **This is the exact machinery a hosting module needs**, one layer up (a whole instance instead of a builder's box).
+- **The trust-boundary + intent-queue pattern is established and non-negotiable.** Real-money / infra mutations **never** touch the internet-facing web process. The web route only **enqueues an intent** (`box_intents`); a separate **control-plane runner** (`scripts/gds/box.js`, driven by a systemd timer) is the *sole holder* of the cloud provider tokens, which live in a chmod-600 `/etc/<inst>/box.env` loaded via `EnvironmentFile=` — structurally out of reach of the web tier ([ADR 0016](<redacted>.md), [ADR 0031](<redacted>.md) §9.4).
+- **The module contract is settled** ([`docs/modules-contract.md`](../modules-contract.md), [ADR 0083](<redacted>.md)): `module.json` manifest, `default:false` optional modules, one-way import boundary (a module reaches core only through `src/module-api.js`; never another module), rank-gated write routes (fitness-enforced), and module-owned namespaced migrations.
+
+**The gaps (net-new work).** No single command turns the [`cloudbongos-standup.md`](../recipes/cloudbongos-standup.md) runbook into an automated provision. No **domain purchase/registration** capability exists (only DNS-*record* management on existing zones). Per-apex **TLS** is a manual Cloudflare Origin-Cert console step (the least-automated leg). There is no per-instance managed-DB provisioning at scale, no **billing/metering** (only a box *cost ledger*), and no **central fleet control plane** — per-repo GDS is locked ([ADR 0100](<redacted>.md) §3), so "instances Cloud Bongos operates" would be a new operator layer *above* the individual GDS DBs.
+
+**The budget DNA that constrains this.** $5K total for build + first year; cheapest-viable-by-default; any high fixed monthly cost needs an ADR + a cheaper fallback ([CLAUDE.md §4](../../CLAUDE.md)). The project has twice rejected always-on control planes on cost grounds — Coder and a container pool were both declined in [ADR 0031](<redacted>.md) in favour of snapshot-and-park with fixed cost ≈ $0. A hosting module inherits that DNA: **near-zero fixed cost when idle.**
+
+---
+
+## Decision
+
+### 1. Ship it as a new `provisioning` module — the boundary
+
+A new, portable, **`default:false`** module `modules/provisioning/` (`coreVersion: "^1.14.0"`), scaffolded with `bongos module new provisioning`. It **owns the web-tier request + state surface** for standing up and operating instance infrastructure, and nothing more.
+
+**It owns:**
+- **Tables** (namespaced `provisioning_*`, additive-only, in `modules/provisioning/migrations/provisioning_NNN_*.sql`):
+  - `provisioning_instances` — one row per instance the owner is provisioning/operating: owner, target ref, hosting shape (co-tenant | dedicated droplet), domain, DB name, allocated port, tier, lifecycle status, cost estimate.
+  - `provisioning_intents` — the enqueue queue (the `box_intents` analogue) the control-plane runner drains.
+  - `provisioning_events` — an append-only audit/log of provisioning actions.
+- **HTTP routes** (`contributes.routes`, mounted under `/api/bongos` + the `/api/gds` alias), each self-rank-gated:
+  - own-scoped: create a provisioning request, read own instance state/cost, request teardown;
+  - Archon-scoped: the fleet roster + cost ledger + force actions (the `/boxes` Archon precedent).
+- Optionally a hall **`uiSection`** (an "Instances" panel — own-scoped for owners, fleet view for Archon), reusing the dev-box UI pattern.
+- A **port it provides**, e.g. `provisioning.instanceState`, so other code can read instance status via `seams.resolveOptional` without importing this module.
+
+**It does NOT own** (hard boundary — the trust-boundary rule, §2): the cloud provider tokens, the code that calls DigitalOcean/Cloudflare/a registrar, or any privileged shell/SSH. Those live only on the control plane. It also does not own the *game*, *branding*, or *the instance's own GDS data* — an instance provisioned by this module is a normal Cloud Bongos instance with its own DB ([ADR 0100](<redacted>.md) §3).
+
+### 2. The web tier enqueues intents; a control-plane runner holds the tokens
+
+Mirror the dev-box split exactly. A provisioning API call **writes a `provisioning_intents` row and returns** — it never calls a cloud API. A new control-plane CLI **`scripts/gds/provision.js`** (a sibling of `box.js`, deliberately *outside* the module import boundary so it may reuse control-plane code directly) is the **sole token-holder**; a systemd timer runs `provision.js run-intents --apply` on the control plane. Tokens live in the existing chmod-600 `/etc/<inst>/box.env` (or a sibling), loaded via `EnvironmentFile=`, **never** in the web process. The runner is **idempotent + dry-run-by-default** (the `box.js` / `do-api.js` posture), with fleet tagging + drift reconciliation so a leaked droplet/DNS record is detectable.
+
+**Shared provider clients, no module→module import.** The DigitalOcean v2 client (`do-api.js`) and the Cloudflare DNS logic (`box-dns-cloudflare.sh`) that `provision.js` needs currently live inside `modules/dev-box/`. Because a module may not import another module, and both `box.js` and `provision.js` are control-plane CLIs (which *may* require code directly), the build extracts these into a **shared control-plane location** both CLIs use (a `scripts/gds/` or `infra/` client), rather than duplicating them. This is a small, mechanical refactor that leaves dev-box behaviour byte-identical.
+
+### 3. What "provision an instance" composes
+
+The runner automates the [`cloudbongos-standup.md`](../recipes/cloudbongos-standup.md) runbook into one idempotent flow. Each step is classified by how automatable it is:
+
+| Step | Automatable? | How |
+|---|---|---|
+| Server (co-tenant process **or** a dedicated droplet) | **Yes** | Co-tenant: allocate a port + DB on an existing box (the cloudbongos.com shape, $0 extra). Dedicated: `do-api.js` `createDroplet` + cloud-init (the box precedent). |
+| Database | **Yes** | `createdb <inst>` + GDS-only `migrate.sh` (`MEDUSA_GDS_ONLY=1`, instance seeds off — [ADR 0105](<redacted>.md)). |
+| App config + secrets | **Yes** | Write `config/branding.json`/`modules.json`/`hierarchy.json` (from the init spec) + a per-instance `/etc/<inst>/web.env` (chmod 600). |
+| Process/service | **Yes** | Install + enable a per-instance systemd unit (the `cloudbongos.service` template). |
+| DNS | **Yes** | Cloudflare A-record UPSERT via the shared client (§2/§4). |
+| TLS | **Yes** (new approach) | Caddy on-demand ACME for the new host (§4) — removes the manual Origin-Cert leg. |
+| Reverse proxy | **Yes** | Add the Caddy site block + reload. |
+| **GitHub OAuth app** | **Assisted** | GitHub has no clean API to *create* an OAuth app; the runner generates exact instructions + captures the client id/secret the owner pastes back. Stays a guided step. |
+| **First owner sign-in** | **Manual** | A human must sign in once to seat the founding Archon (config alone seats no one). Inherent. |
+| **Domain registration** | **Deferred** | See §4 — bring-your-own-domain first; registrar-API purchase is a later task. |
+
+### 4. Domains: bring-your-own first; TLS via on-demand ACME
+
+- **V1 = bring-your-own-domain.** The owner already owns a domain (or a delegated zone); the module manages **DNS records** on it via the shared Cloudflare client (the box precedent). **Domain *purchase/registration*** via a registrar API is genuinely net-new and is **deferred to its own later task** — it is not on the V1 critical path.
+- **TLS via Caddy on-demand ACME (Let's Encrypt) for provisioned hosts**, instead of per-apex Cloudflare Origin Certs. The existing example.com/cloudbongos.com apexes keep their Origin Certs unchanged; **newly provisioned** hosts get automatic certificates with no manual console step. This directly eliminates "the single least-automated leg" the standup runbook calls out. (On-demand TLS must be allow-listed to hostnames the module actually provisioned, so it can't be abused to mint certs for arbitrary names.)
+
+### 5. The self-host vs managed split
+
+**Both run the identical `@cloudbongos/core` artifact ([ADR 0108](<redacted>.md)).** Managed is not a fork, not open-core, not a proprietary layer — it is self-host + (a) the provisioning module pointed at Cloud Bongos's own infra, and (b) a central operator driving the *existing* `bongos upgrade` channel. This is exactly the posture [ADR 0065](<redacted>.md) §2 already recorded ("*a service offered on top of the same AGPL artifact — it does not change the artifact's license or the non-profit posture*").
+
+| Dimension | **Self-host** | **Managed** (idea 303) |
+|---|---|---|
+| Artifact | identical `@cloudbongos/core` (pinned npm dep) | identical |
+| Whose cloud account/tokens | the **owner's** (their DO/Cloudflare/registrar tokens, held on **their** control plane) | **Cloud Bongos's** tokens on Cloud Bongos infra |
+| Control plane | the owner's own (their box runs `provision.js`) | a **central fleet control plane** — greenfield; sits *above* per-instance GDS DBs ([ADR 0100](<redacted>.md) §3) |
+| The `provisioning` module | same module, enabled, configured with the owner's target | same module, target = Cloud Bongos infra |
+| Updates | owner runs `bongos upgrade` | operator drives `bongos upgrade` across the fleet (same channel) |
+| Billing | owner pays their own cloud bill directly | Cloud Bongos meters → invoices → collects (**deferred**, §6) |
+| Licensing | AGPL; owner owes source to *their* users only if they modify + serve | AGPL; operator owes source (satisfied by the public mirror) |
+| Buildable | **now**, on the shipped configurable-root substrate | **after** Mercury (R85) + a real `bongos upgrade` (R86) |
+
+**The one-sentence rule:** *self-host and managed run the same artifact and the same provisioning module; the only differences are **whose credentials** the control plane holds and **who operates** it.*
+
+### 6. Cost posture
+
+Inherit the budget DNA. **Default to the cheapest shape** — a co-tenant process + DB on an existing droplet ($0 new spend, the cloudbongos.com model) — and only graduate an instance to a dedicated droplet when justified. Idle dedicated instances follow the **snapshot-and-park** precedent (fixed cost ≈ $0). Reuse the `SIZE_CATALOG` per-size USD table for **cost visibility** in `provisioning_instances`. **Billing/metering/invoicing is out of scope for the module's first cut** and is a separate deferred track (it also depends on the V3 Stripe work); the managed layer needs it, self-host does not.
+
+### 7. Sequencing
+
+- **Self-host provisioning is buildable now** — the configurable-root substrate (ADR 0108 W1–W4) and the box lifecycle are shipped. The module + runner + DNS/TLS + `bongos init` wiring do not wait on anything.
+- **The managed layer is deferred** (idea 303 was always "post-C8, optional"). It is gated on **R85 (Mercury — the first real second-repo consumer on a pinned core; [#1689](https://example.com/builders#/task/1689))** proving the two-repo path end-to-end, and **R86 (a real `bongos upgrade` channel; [#1690](https://example.com/builders#/task/1690))**. The managed *fleet control plane* is itself a spec-first task, not a straight build.
+
+---
+
+## Alternatives considered
+
+- **Reuse the `hosting` key / fold into [ADR 0092](<redacted>.md).** Rejected — 0092 is compute/storage *workload* brokering; conflating "where my inference runs" with "where my instance runs" would muddy both boundaries (the [ADR 0107](<redacted>.md) naming-collision lesson). Distinct `provisioning` key.
+- **Provision directly from the web tier (let it hold DO/CF tokens).** Rejected — violates the [ADR 0016](<redacted>.md)/[ADR 0031](<redacted>.md) trust boundary. The intent-queue + control-plane runner is mandatory, not stylistic.
+- **A full standing control plane per the Coder model.** Rejected on cost — the exact trade [ADR 0031](<redacted>.md) already declined. Systemd-timer-drained intents keep idle fixed cost ≈ $0.
+- **Per-apex Cloudflare Origin Certs (automate the console step).** Rejected in favour of Caddy on-demand ACME — less bespoke, no Cloudflare-console dependency, and it removes the manual leg outright. Existing apexes keep their Origin Certs.
+- **Domain purchase in V1.** Deferred — bring-your-own-domain covers the common case; registrar-API integration is additive and shouldn't gate the module.
+- **Build managed first.** Rejected — it depends on unshipped Mercury + the upgrade channel, and idea 303 was always the optional later layer.
+
+---
+
+## Consequences
+
+- **Unblocks the self-host productization arm of goal 26** — the manual [`cloudbongos-standup.md`](../recipes/cloudbongos-standup.md) checklist becomes an owner-driven, API-configured flow (idea 345 delivered), with the two irreducibly-human steps (OAuth-app creation, first sign-in) clearly demarcated.
+- **The trust boundary is preserved** — the internet-facing process gains a provisioning surface but still holds no cloud credentials; all real infra mutation stays on the control plane.
+- **`bongos init` gains an infra arm** — its infra answers flow into a provisioning request instead of only filing manual kickoff tasks.
+- **Deferred / risks:** the **managed fleet control plane** is genuinely greenfield and sits above the locked per-repo GDS model — it needs its own spec once Mercury lands. **Billing/metering** is greenfield (no capability today). **Domain registration** is deferred. On-demand TLS must be hostname-allow-listed to what was actually provisioned. `bongos upgrade` is still a stub (R86).
+- **Licensing unchanged** — managed is a service on the same AGPL artifact ([ADR 0065](<redacted>.md) §2); no open-core, no relicensing.
+- **Follow-up tasks seeded** under BONGOS-V1 / goal 26 (idempotent seeder `scripts/gds/seed-provisioning-tasks.js`, `source_ref = <redacted>*`):
+  1. **Scaffold the `provisioning` module** — manifest + `provisioning_*` tables + the web-tier intent/state routes (own + Archon), no token handling. *(buildable now)*
+  2. **Extract the shared DO + Cloudflare control-plane clients** so `box.js` and `provision.js` reuse them without a module→module import (dev-box byte-identical). *(buildable now; enables 3)*
+  3. **`scripts/gds/provision.js` control-plane runner + systemd timer** — drains `provisioning_intents`; composes server→DB→migrate→env→service→Caddy→healthz; idempotent, dry-run-default, drift-reconciling. *(deps: 1, 2)*
+  4. **Automated DNS + Caddy on-demand ACME TLS** for a provisioned host. *(deps: 2, 3)*
+  5. **Wire provisioning into `bongos init`** — infra answers → a provisioning request; keep OAuth-app + first-sign-in as guided/manual. *(deps: 1, 3)*
+  6. **Hall UI "Instances" panel** — own-scoped for owners, Archon fleet view + cost. *(deps: 1)*
+  7. **Spec the managed fleet control plane** (idea 303) — the central operator above per-instance GDS that stands up branded instances on Cloud Bongos infra and drives `bongos upgrade` across the fleet. *(spec-first; gated on R85 [#1689](https://example.com/builders#/task/1689) + R86 [#1690](https://example.com/builders#/task/1690))*
+  8. **Managed billing/metering** — meter provisioned resources → invoice → payment. *(deferred; deps: 7)*

package/docs/adr/0112-private-goals-invitations-join-requests.md

@@ -0,0 +1,72 @@
+# 0112 — Private goals: a visibility flag + a two-sided membership-request queue (invitations + join-requests)
+
+- **Status:** Accepted
+- **Date:** 2026-07-03
+- **Deciders:** jaxri (Metic, owner request), Claude
+
+**Builds on / amends:** [ADR 0086](<redacted>.md) (goal-scoped work hierarchy — this ADR adds a privacy dimension + the self-service membership queue its §3 deferred), [ADR 0106](<redacted>.md) (goal owner/manager authority — the exact authority this ADR reuses for who may invite/approve), [ADR 0016](<redacted>.md) (server-enforced rank boundary — unchanged). Reuses the approval-queue shape of `access_requests` ([`modules/onboarding/routes/access-requests.js`](../../modules/onboarding/routes/access-requests.js)).
+
+**Track:** `internal` (GDS / methodology — a Cloud Bongos platform capability).
+
+---
+
+## Context
+
+Goals are shared, module-scoped workspaces ([ADR 0086](<redacted>.md)). Today a *normal* (non-protected-scope) goal is **open-join**: `POST /goals/:id/join` adds anyone who asks. Protected-scope goals are already Archon-mediated. There was no middle ground — no way for a goal's own owner/manager ([ADR 0106](<redacted>.md)) to say "this is a curated group; ask to join, or wait to be invited." ADR 0086 §3 explicitly deferred the self-service "request → approve" queue ("it co-evolves with that ADR"); this is that ADR for the normal-goal case.
+
+The owner request (2026-07-03): let a goal manager **make a goal private and invite builders**, let any builder **request to join**, gate approval to the goal's **owner/manager (or an Archon)**, and surface both sides in a **home-page inbox**.
+
+One product decision was made explicitly with the requester: **private means join-gated, not hidden.** A private goal still appears in the goals list with its title + progress; "private" controls who may *join*, not who may *see*. This keeps the change small and additive — no membership filter has to thread through the goals list, goal detail, roadmap, work board, and task queries (the "fully hidden" alternative, rejected below).
+
+## Decision
+
+**A goal gains a `visibility` of `public` (default) or `private`. On a private goal, non-members cannot self-join — they are INVITED (and accept) or they REQUEST to join (and an owner/manager/Archon approves). Both directions are rows in one new `goal_membership_requests` queue, and each builder's actionable slice of that queue is their home-page inbox.**
+
+### 1. Visibility (task 1951)
+
+- `goals.visibility text NOT NULL DEFAULT 'public' CHECK (visibility IN ('public','private'))` — a purely additive column (core migration `core_188_…`, because `goals` is a **core-owned** table; [ADR 0083](<redacted>.md) §Decision 5). Every existing goal defaults to `public` = today's behaviour, so nothing changes until a manager flips it.
+- `PATCH /goals/:id/visibility { visibility }` — the owner, a manager, or an Archon (the `authorizeGoalManagement` gate, [ADR 0106](<redacted>.md)). (task 1952)
+
+### 2. The membership-request queue (task 1951)
+
+One table, both directions, distinguished by `kind`:
+
+| `kind` | who opens it | who resolves it | on accept/approve |
+|---|---|---|---|
+| `invite` | owner \| manager \| Archon, targeting `builder_id` | **only the target** (`builder_id`) — accept / decline | membership added |
+| `request` | the builder themselves | owner \| manager \| Archon — approve / deny | membership added |
+
+`goal_membership_requests(id, goal_id, builder_id, kind, status, note, created_by, resolved_by, timestamps)`, `status ∈ {pending, accepted, rejected, cancelled}`. A **partial unique index on `(goal_id, builder_id) WHERE status='pending'`** means one open ask per person+goal (the `access_requests` precedent) — an invite and a request can't both be open, and neither piles up duplicates. Resolved rows stay as the audit trail and never block a later re-ask.
+
+**An invitation is consented, not a force-add.** It creates a *pending* row the invitee accepts from their inbox — distinct from the existing `POST /goals/:id/members` (kept byte-identical), which is the immediate owner/manager/Archon add. "Invite" is the new consented path; "add member" is the old direct one.
+
+### 3. Routes (task 1952) — every wall in-handler, pinned `any-builder`
+
+Following the [ADR 0106](<redacted>.md) precedent (the wall is the in-handler pure ordered gate, not a rank middleware; each route pinned in `route-rank-check` so an accidental `requireRank` re-gate or a gate removal is a red build):
+
+- `POST /goals/:id/join` — **changed**: on a `private` goal, a non-member who isn't owner/manager/Archon is refused `409 goal_private` ("request to join or wait for an invite") instead of being added. Public + protected-scope behaviour unchanged.
+- `POST /goals/:id/requests { note? }` — a builder asks to join (refused on a public non-protected goal — just join — and if already a member).
+- `POST /goals/:id/invitations { builder_id, note? }` — owner/manager/Archon opens a pending invite (protected-scope keeps the Archon-only + Metic+-target rule).
+- `POST /goals/:id/requests/:reqId/respond { action: approve|deny }` — owner/manager/Archon; approve → add member.
+- `POST /goals/:id/invitations/:reqId/respond { action: accept|decline }` — **only the target** may resolve their own invite; accept → add member.
+- `GET /goals/inbox` — the caller's `{ invitations, joinRequests, myPendingRequests }` (task 1954's home widget + task 1953's goals page read it). Mounted before `GET /goals/:id` so `inbox` isn't captured as an id (the `/goals/reorder` precedent).
+
+The membership add on accept/approve is atomic with the resolve: `resolveMembershipRequest` only moves a row **from `pending`**, so a re-submitted resolve can't double-add.
+
+### 4. The inbox scope (task 1954)
+
+`listInboxFor(builderId)` returns three buckets: invitations addressed to me, join-requests on goals I **own or manage** (`goals.created_by = me` OR a `goal_members 'lead'` row), and my own outstanding requests. Requests only ever exist on a private goal someone made private — so an owner/manager always exists and a request never lands in nobody's inbox. An Archon can still approve any request via the route; the inbox stays scoped to what a builder owns/manages so it doesn't drown an Archon in every goal's queue.
+
+## Consequences
+
+- **Additive + reversible.** Default `public` means zero behaviour change on every existing goal; the whole feature is dark until a manager flips a goal private. Each of the four build phases (schema, API, goals-page UI, home inbox) ships independently.
+- **Reuses the existing authority model wholesale** — no new notion of "who runs a goal"; invitations/approvals gate on the same owner/manager/Archon as role changes and conflict resolution ([ADR 0106](<redacted>.md)).
+- **Protected-scope goals are unchanged** — their stronger Archon-mediation ([ADR 0086](<redacted>.md) §3) still governs; `visibility` is orthogonal and additive on top.
+- **Private = join-gated, not hidden.** A non-member can still see a private goal's title + progress. If true concealment is ever wanted it needs its own ADR (a membership filter across list/detail/roadmap/board/tasks) — deliberately **not** built now.
+
+## Alternatives considered
+
+- **Fully hidden private goals (invisible to non-members) — rejected** (owner). Stronger privacy, but forces a membership filter through the goals list, goal detail, roadmap, work board, and every task query — a large surface for a feature whose ask is "control who joins." Join-gating delivers the intent with a purely additive change.
+- **Invite = immediate add (no accept step) — rejected.** The owner asked for an inbox that *accepts* invitations, so an invite is consented (pending until the invitee accepts). The immediate-add path already exists as `POST /goals/:id/members` and is kept.
+- **Two separate tables (invitations, join_requests) — rejected.** They share the same lifecycle (pending → accepted/rejected/cancelled), the same partial-unique "one open ask per person+goal" rule, and feed the same inbox. One table with a `kind` discriminator is less machinery and makes the mutual-exclusion index trivial.
+- **Requests allowed on public goals — rejected.** A public goal is open-join; a request there is redundant. Requests are the private-goal path; the route refuses a request on a public non-protected goal.

package/docs/adr/0113-sandbox-studio-descope-superseded-by-0044-0052.md

@@ -0,0 +1,41 @@
+# ADR 0113 — Per-builder art sandbox (task 885): descope to the Studio only, superseded by ADR 0044/0052
+
+**Date:** 2026-07-03
+**Context:** [task 885](https://example.com/builders#/task/885) ("Per-builder art sandbox + sprite studio"), goal 25 (builder experience). Companion to [ADR 0044](<redacted>.md) (per-box live game preview), [ADR 0052](<redacted>.md) (game-only preview entry, every rank), and [ADR 0083](<redacted>.md) (the game's carve into `modules/game/`).
+**Status:** Accepted.
+**Track:** `internal` (builder experience / dev box).
+
+## Problem
+
+Task 885 was filed 2026-06-09 with a full 8-part build plan: a walkable single-player preview reached by skipping the multiplayer connect, a static file server + systemd unit for `sandbox-<login>.example.com`, a `cf-tunnel.js` multi-ingress change, box-provisioning wiring, a "reset to main" script, and a sprite/animation studio — plus retiring the frozen `staging.example.com` environment as "Part C".
+
+By the time this session picked the task up (2026-07-03), the plan had gone stale on two independent axes:
+
+1. **Most of it already shipped, differently, one day later.** ADR 0044 (2026-06-10, task [#897](https://example.com/builders#/task/897)) already gives every full-clone box a live `sandbox-<login>.example.com` — not a static-file simplification, but the box's own real game server (`box-game-preview.service`, degraded-DB, real Colyseus rooms) over the same Cloudflare named tunnel the terminal already uses. ADR 0052 (2026-06-13, task [#1001](https://example.com/builders#/task/1001)/[#1002](https://example.com/builders#/task/1002)) then widened it to every rank via a dedicated game-only entry (`src/preview-server.js`) and put the game paths in the starter sparse clone. So task 885's Part A1 (walkable preview) and Part B (static server + systemd unit + `cf-tunnel.js` multi-ingress + provisioning wiring) describe infrastructure that exists already, under a different, better design (a real multiplayer world instead of an offline single-player mode) and a different hostname/tunnel mechanism than the one it proposed building.
+2. **The repo moved underneath it.** The game client the plan's touches\[\] pointed at (`public/game/scenes/WorldScene.js`, `public/game/player/Player.js`, `src/bongos/cf-tunnel.js`, `src/bongos/routes/box.js`, `src/bongos/boxes.js`) was carved into modules under ADR 0083/0093: the game now lives at `modules/game/public/game/...`, the tunnel CLI at `scripts/gds/cf-tunnel.js`, and the box routes/db at `modules/dev-box/{boxes.js,routes/box.js}`. None of the file paths in the original breakdown table resolve today.
+
+Separately, task 885's Part C ("retire the frozen staging env") directly contradicts a standing decision: `docs/recipes/staging-environment.md` records a deliberate **defer-not-delete** call from 2026-05-29 — staging was frozen (not torn down) specifically because re-provisioning it later costs real time, and the environment costs ~$0/mo idle. Task 885 re-proposing its removal, a week later, with no reference to that decision, is exactly the kind of drift this ADR exists to catch before code gets written against it.
+
+## Decision
+
+**Descope task 885 to the one part of its plan that is still real, unbuilt, and non-duplicative: the sprite/animation Studio.** Everything else in the original breakdown is either already shipped (Parts A1/B, under ADR 0044/0052) or conflicts with a standing decision (Part C, staging) and is dropped from this task's scope without re-litigating it here.
+
+The Studio — a sprite/animation reviewer at `/studio` (pick a sprite, play its walk cycle, flip direction, step frames, zoom, swap background) — has no existing equivalent. It gets built as a *viewer that imports the game's own code*, attached to the **existing** sandbox rather than a new one:
+
+- It layers onto `modules/game/public/` as a static page (`studio.html` + `game/studio/studio.js`), served automatically by the `express.static(GAME_PUBLIC, …)` mount both `server.js` and `src/preview-server.js` already have — no new server, tunnel, or systemd unit. The precedent is `/art` (task 1262's generated-art gallery), already living in `src/preview-server.js` as an explicit route; `/studio` needs no explicit route at all since it's a static page, not a per-request render.
+- It auto-discovers sprites from `/assets/tiles/manifest.json` (the same cache `tilePalette.js:preloadTilePalette` already loads) and uses the game's own key helpers (`PLAYER_DIRS`/`WALK_FRAMES`/`playerTextureKey`/`playerWalkTextureKey` in `modules/game/public/game/player/playerSprite.js`) so new sprites need zero studio edits.
+- The one shared extraction task 885 correctly identified is still needed: the right-facing mirror logic in `Player._applyIdleTexture`/`_applyWalkTexture` (`modules/game/public/game/player/Player.js:59-79`) becomes `modules/game/public/game/player/spriteFacing.js`, called by both `Player.js` and the studio — a behavior-preserving refactor, not new logic.
+
+This is filed as [a single new child task](https://example.com/builders#/task/885) under 885 rather than the original 8, since the remaining scope is small enough not to need a multi-task breakdown.
+
+## Consequences
+
+- No duplicate sandbox mechanism, no `cf-tunnel.js` change, no new systemd unit, no provisioning rewiring — the existing ADR 0044/0052 sandbox is left alone.
+- Staging stays frozen-not-deleted, unchanged from the 2026-05-29 decision; if retiring it is still wanted, that needs its own task that references (and explicitly overrides, with reasoning) that decision — not a drive-by line item in an unrelated epic.
+- The Studio ships as a small, self-contained addition: two new static files + one extraction + (if wanted) a prod-only gate so `/studio` doesn't show up as a public game page — left to the child task's judgment, since the `/art` precedent already runs unguarded on the sandbox and the studio is no more sensitive.
+- Future planning-session epics that embed a multi-task breakdown table should be re-validated against current `git log`/file layout before their child tasks are minted, not executed mechanically — this is the second time in this repo a stale breakdown table was caught only by checking the live repo first (companion precedent: the ADR 0088 dependency backfill session).
+
+## Alternatives considered
+
+- **Execute the original 8-task breakdown as written** — rejected: would build a second, weaker sandbox mechanism (static files, offline single-player) alongside the real one (live degraded-DB multiplayer) that already serves the same hostname, and would reopen the staging-retirement decision without cause.
+- **Silently drop task 885** — rejected: the Studio idea is genuinely good and still unbuilt; dropping the whole task would lose it.

package/docs/adr/0114-instance-docs-discovery-contract.md

@@ -0,0 +1,32 @@
+# ADR 0114 — Instance docs-discovery contract (how an agent finds its hall + docs from config alone)
+
+**Date:** 2026-07-04
+**Status:** Accepted.
+**Context:** [task 2005](https://builders.example.com#/task/2005) (BONGOS-V1, from the 2026-07-04 CLAUDE.md review, bullet 6). Companion to [ADR 0062](<redacted>.md) (core↔host split), [ADR 0109](<redacted>.md) (self-describing OpenAPI + hosted `/docs`), and [ADR 0029](<redacted>.md) (off-box status page).
+
+## Problem
+
+CLAUDE.md tells an agent to "read docs on your instance's builders' hall (`domains.buildersOrigin`)," but nothing *pins* how a fresh, self-hosted instance's agent reliably locates its doc surfaces. The pointer was one line of prose citing one config key — hand-waving, not a contract. A second instance standing up on its own domain needs to resolve "where are my hall, my rendered docs, my status page?" **from config alone, with no hard-coded `example` anywhere.** Today the pieces exist but were never named together as the discovery contract:
+
+- `config/branding.json` `domains.{publicOrigin,buildersOrigin,statusOrigin}` — the config source of truth.
+- `/docs` + `/docs/openapi.json` — the rendered API reference + machine spec ([ADR 0109](<redacted>.md)), served on the instance's own origin.
+- `GET <publicOrigin>/api/bongos` (and the permanent `/api/gds` alias) — the machine-discovery index (task 1918), CORS-open + unauthenticated, which answered with `docs`/`openapi` pointers but **not** the hall or status origins.
+
+## Decision
+
+Pin a three-layer docs-discovery contract. Every layer is derivable from config or from a single unauthenticated call — no host is ever hard-coded.
+
+1. **Config is the source of truth.** `config/branding.json` `domains` carries the surfaces:
+   - `domains.buildersOrigin` — the **builders' hall**: the canonical doc-reading surface (task/idea/blocker refs render as working links; the primer + generated diagrams + repo docs render there).
+   - `domains.publicOrigin` — the **instance origin**: `/docs` renders the API reference and `/docs/openapi.json` is the machine-readable OpenAPI 3.1 spec.
+   - `domains.statusOrigin` — the **status page**: the off-box fallback for project state when the hall is down ([ADR 0029](<redacted>.md)), though it does not render full docs.
+2. **The machine-discovery index is the zero-config entry point.** `GET <publicOrigin>/api/bongos` (and the permanent `/api/gds` alias) returns a small JSON map that now advertises the doc surfaces themselves — `hall`, `status`, and `public` origins alongside `docs`/`openapi`. An agent or client that knows only *one* origin (or reaches the API root by accident) can bootstrap every other doc surface from that single response, with no config file and no hard-coded host.
+3. **Resolution order for an agent.** (a) Read `config/branding.json` `domains` when the checkout is present; (b) otherwise `GET <origin>/api/bongos` and read `hall`/`status`/`docs`; (c) the hall is the canonical doc surface, the status page the outage fallback, `/docs` the API reference. `github.com` is the code host only — never the doc-reading surface (a bare `#NNN` mis-autolinks there).
+
+## Consequences
+
+- **The discovery index gains `hall`/`status`/`public`** (`src/bongos/serve-internal.js`). This is the concrete "resolve with no hard-coded example" guarantee: the values come from `branding().domains`, so a second instance's index advertises *its* origins automatically.
+- **`docs/branding-contract.md`** documents the docs-discovery contract so a fresh instance knows these `domains.*` fields are load-bearing, not decorative.
+- **CLAUDE.md's preamble references this ADR** instead of hand-waving a single config key.
+- **No new required config field** — the contract formalizes the existing `domains.{publicOrigin,buildersOrigin,statusOrigin}` keys. `buildersOrigin`/`statusOrigin` stay optional in the contract (an instance may ship without a hall/status surface); when absent the index returns `null` for that pointer and the agent falls back to `/docs` on `publicOrigin`.
+- **Portability, not behavior.** No endpoint semantics change; the index adds fields (back-compatible). The [ADR 0016](<redacted>.md) trust boundary is untouched — the index names only public locations and remains unauthenticated.

package/docs/adr/0115-scheduled-routines-portability.md

@@ -0,0 +1,31 @@
+# ADR 0115 — Scheduled-routines portability (self-host + multi-builder)
+
+**Date:** 2026-07-04
+**Status:** Accepted (contract; spike deliverable).
+**Context:** [task 2014](https://builders.example.com#/task/2014) (BONGOS-V1, from the 2026-07-04 CLAUDE.md review, bullet 241). The ~17 autonomous cron routines under [`.claude/scheduled-tasks/`](../../.claude/scheduled-tasks/) (`overnight-builder`, `idea-triage-nightly`, `overnight-code-review`, `bfg`, `security-review-weekly`, box lifecycle, audits, newcomer restock, …) were written for *this* instance. A self-hosted, multi-builder instance needs a defined model for which run instance-wide vs per-builder, how a fresh instance inherits/configures them, and what a builder gets by default. Companion to [ADR 0062](<redacted>.md) (core↔host split) and [ADR 0024](<redacted>.md) (the MAS the routines belong to).
+
+## Problem
+
+The routines are instance-agnostic in intent but were authored against OTB: their prose cites `example.com` API bases and `~/.config/otb` paths, and there was **no declared model** for how they scale to multiple builders or scaffold onto a fresh instance. Two questions were open: (1) in a multi-builder world, does a routine run once for the instance or once per builder? (2) how does a fresh instance inherit + configure the set, and what does an individual builder get by default?
+
+## Decision
+
+**Every scheduled routine is INSTANCE-WIDE — one scheduled run per instance, never one cron per builder.** A routine's *per-builder effect* (the BFG scores each builder; `newcomer-floor` restocks per discipline; `overnight-builder` may claim on any builder's behalf) comes from **iterating the builder set inside the routine body**, not from N per-builder schedules. This keeps scheduling O(1) in builders and the trust surface single (one control-plane scheduler, one autonomy gate), not O(builders).
+
+The contract is made concrete + configurable by a **manifest**, [`config/scheduled-routines.json`](../../config/scheduled-routines.json), declaring per routine:
+
+- `scope` — always `instance-wide` in v1 (the model above); `builderAware: true` marks the ones whose *body* iterates builders.
+- `enabled` — the default-on/off for a fresh instance. **Read-only hygiene/ops routines default ON** (box lifecycle, audits, drift checks, newcomer restock, peer-vote tally, dep/security audits). **Autonomous build routines default OFF** (`overnight-builder`, `overnight-code-review`, `idea-triage-nightly`) — they carry `requiresAutonomy: true` and are a no-op until the instance arms `<PREFIX>_AUTONOMY_ENABLED` (matching today's default-unset OTB behavior). The BFG's cross-builder WRITE (Part C) stays independently gated by `BFG_WRITE_ENABLED` + a provisioned principal token.
+- `cadence` — a scheduler hint (hourly/daily/nightly/weekly/on-merge); the actual cron lives in the operator's scheduler config.
+- `requiresAutonomy` — whether the routine is inert until the autonomy flag is armed.
+
+**Inheritance.** The routines ship in the core template (`.claude/scheduled-tasks/`); a fresh instance inherits the whole set + this manifest. The operator opts in/out and sets cadence **in the manifest**, without editing a routine. A vanilla instance therefore boots with the safe subset (read-only ops on, autonomous build off).
+
+**What a builder gets by default.** Builders do **not** schedule their own routines in v1 — these are instance/ops-level. A builder's *involvement* is governed by their per-builder settings (autonomy opt-in, `wandering`, model allocation), not by this manifest. Per-builder scheduling is explicitly out of scope for v1 (a future extension could let a builder opt a builder-aware routine in/out for themselves).
+
+## Consequences
+
+- **`config/scheduled-routines.json` is the portability surface** — the single place an operator configures the routine fleet; the scheduler + a future `bongos init` read it to decide what to arm.
+- **Portability debt flagged, not fully paid here (spike scope):** several routine `SKILL.md` files hardcode `example.com` / `~/.config/otb` in prose. The contract requires routines to resolve instance identity from config (`branding().domains`, the instance config dir) rather than hardcode it; genericizing all ~17 prose files is a **follow-up** (a mechanical sweep), captured as its own task — not part of this decision.
+- **No behavior change today.** OTB keeps running every routine exactly as before; the manifest simply records the model it already follows (instance-wide) and the safe defaults. The `requiresAutonomy` routines remain OFF (OTB has not armed autonomy).
+- **CLAUDE.md §12** references this contract + the manifest instead of just naming "~17 routines."