@bongos/core 1.18.3 → 1.18.19

package/.claude/skills/planning-session/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: planning-session
-description: Run a structured planning session for an upcoming GDS version — set scope criteria, brainstorm tasks, rank them, and upload everything to the GDS in one atomic shot. Triggers when the user says "/planning-session", "open a planning session", "let's plan V[N]", "plan the next version", or "scope a new version". Metic+ rank only (Metic and Archon; not Xenos).
+description: Run a structured planning session for an upcoming GDS version — set scope criteria, draft a written spec, interview the owner in depth to resolve every non-obvious decision, then seed the ranked task list from that spec. Triggers when the user says "/planning-session", "open a planning session", "let's plan V[N]", "plan the next version", or "scope a new version". Metic+ rank only (Metic and Archon; not Xenos).
 ---
 
-You are running a planning session for the Game Development System (GDS). The goal is to leave the session with: (a) a clear set of done-when criteria for a version, (b) a ranked task list that lives in the GDS database, and (c) a durable record of the session for the audit trail.
+You are running a planning session for the Game Development System (GDS). The goal is to leave the session with: (a) a clear set of done-when criteria for a version, (b) a **written spec** (`docs/specs/<ver>-<goal-slug>.md`) that an in-depth interview refines until every non-obvious decision is resolved, (c) a ranked task list **seeded from that spec** that lives in the GDS database, and (d) a durable record of the session for the audit trail.
 
 The first planning session — V3 Planning Session #1, 2026-05-12 — is the template this skill encodes. See `docs/session-logs/<redacted>.md` for the precedent and `tasks/227` (V3.R00) for the meta-task pattern.
 
@@ -29,7 +29,7 @@ This mirrors GDS-V3 criterion C2 (`three-ranks-gate-everything`) and matches the
 
 1. Call `GET /api/gds/me` and read `builder.rank`. Compare case-insensitively (lowercase it before testing).
 2. **If `rank` is present and lowercases to `xenos`** → stop immediately. Tell the builder: *"Planning sessions set the scope-truth of a version — they're a Metic+ operation. You're currently Xenos. You can still **file** a criterion proposal or task idea via `POST /api/gds/inbox` (which lands in idea_inbox for an Archon to ratify at the next planning session); ask an Archon for promotion if you need to run sessions directly."* Do not pull state, do not present criteria, do not propose tasks.
-3. **If `rank` lowercases to `metic`** → proceed in **Metic-mode**: run the five-phase structure below conversationally, but in Phase 5 write proposals to `idea_inbox` (kind=`criterion-proposal` for criteria, kind=`feature` for tasks) tagged with the target version. Archon ratifies at the next Archon-mode planning session. Do NOT write `done_when_criteria` rows or POST to `/tasks` directly — those are Archon writes.
+3. **If `rank` lowercases to `metic`** → proceed in **Metic-mode**: run the five-phase structure below conversationally, but in Phase 5 write proposals to `idea_inbox` (kind=`criterion-proposal` for criteria, kind=`feature` for tasks) tagged with the target version. Archon ratifies at the next Archon-mode planning session. Since [ADR 0090](../../../docs/adr/<redacted>.md) a Metic MAY `POST /tasks` directly, and since [ADR 0154](../../../docs/adr/<redacted>.md) a Metic MAY write a `done_when_criteria` row for a goal they own or manage. What still needs an Archon is a VERSION-level criterion (no `goal_id`), one in a goal you don't hold, and creating the version itself. The spec-draft (Phase 3) and the in-depth interview (Phase 4) run identically in Metic-mode — the only difference is the Phase-5 write (you file proposals, you don't seed tasks directly).
 
    **For each criterion proposal**, write `body_md` as a JSON object with this exact shape so the `POST /api/gds/inbox/:id/ratify` endpoint (V3.R31 / #252) can parse it cleanly:
 
@@ -107,6 +107,8 @@ Once criteria are agreed:
 
 ### Phase 2.5 — Goals (the module-scoped workspaces) — ADR 0086
 
+> **Planning a SINGLE goal, not a whole version? Use [`/goal-create`](../goal-create/SKILL.md)** — same decisions (reuse-vs-new, scope wall, criteria, seed tasks), one sitting, no spec file and no migration.
+
 A **goal** is the tier between version and criteria: a shared, joinable, **module-scoped** workspace that several builders work inside (ADR 0086). A version is "done" when all its goals are achieved. Defining goals is now part of planning — it's how the version's criteria get grouped into workspaces with a **scope wall** that bounds what each goal's members may author.
 
 For the version being planned, **group the agreed criteria into goals**. For each goal decide, with the user:
@@ -114,8 +116,7 @@ For the version being planned, **group the agreed criteria into goals**. For eac
 - **Title** — the outcome the goal owns (often 1–3 criteria's worth).
 - **`scope_modules`** — the module **keys** (NOT file paths) whose files this goal's members may touch. **This is the wall, and it is set here and only here — never self-granted.** Keep it tight: the modules the goal's work actually needs. Widening later goes through an explicit request a trusted rank approves (`POST /goals/:id/scope`; Archon for a `protected` module) — BV1.R64.
   > **The valid key list is the source of truth in [`src/bongos/module-scope-map.js`](../../../src/bongos/module-scope-map.js) — read it, don't trust this list.** It exports `moduleKeys()` (all keys), `protectedModules()` / `isProtectedModule(key)` (which are PROTECTED), and `scopeForModule(key)` (a key's globs + `protected` flag). Each key maps to path-globs; `protected` is **derived** (the key's globs overlap the trust/ship-pipeline/migration/authz core), and a goal scoped to any protected key is **Archon-only** to create. The current roster (run `node -e "const m=require('./src/bongos/module-scope-map');console.log(m.moduleKeys().map(k=>k+(m.isProtectedModule(k)?' 🔒':'')).join('\n'))"` to print it live):
-  >   - `kernel` 🔒 · `lifecycle` 🔒 · `economy` · `grading` 🔒 · `memory` · `onboarding` 🔒 · `ideas` · `builder-settings` 🔒 · `sessions` · `autonomy` 🔒 · `security` · `hall-ui` · `status-ui` · `game` · `art-pipeline` · `discord` · `dev-box` 🔒
-  >   - 🔒 = **protected** (Archon-only goal creation + Archon-mediated join). The list above is a convenience snapshot of a *derived* result — if it disagrees with `module-scope-map.js`, the file wins; re-run the one-liner.
+  >   - **No roster is written down here on purpose.** The previous snapshot went stale within a release (it still omitted a key that had been added), which is exactly the failure a "read it live" rule prevents. Run the one-liner above; `protected` is derived from glob overlap, so it changes when the globs change.
 - **No covering key? → file a module-map prep task FIRST.** Every `scope_modules` entry must be a real key from `moduleKeys()`. If a goal's planned work touches file paths that **no existing key covers** (e.g. a brand-new module dir, or code still fused under `src/bongos/` that isn't yet broken out as its own key), the scope wall cannot place that work. Do **not** invent a key. Instead, **add a prep task to this version** — `kind='refactor'`, scoped to `kernel` (the module that owns `module-scope-map.js`) — to extend `MODULE_GLOBS` so a key covers those paths, and make the dependent goal's tasks depend on it. Adding/editing a key is itself a `kernel`-scoped (Archon-gated) change, so flag it for Archon sign-off in this session.
 - **Join policy** — a normal-scope goal is **open-join** (any builder); a goal whose scope includes a **`protected`** module is **Archon-mediated** (a non-Archon can't self-join; an Archon admits Metic+ members). Creating a protected-scope goal is itself **Archon-only** — so flag those for Archon sign-off in this session.
 - **Optional seed tasks / lead** — any obvious first tasks, and who leads.
@@ -124,9 +125,9 @@ Present the goals as a short table (title · scope_modules · join policy · the
 
 > **Rescope is "previous or new" at the goal tier too.** If this version succeeds a prior one, you already decided in Phase 1 which prior goals carry forward — those become this version's goals (linked via `succeeded_by_goal_id`); the rest are net-new here.
 
-### Phase 3 — Brainstorm
+### Phase 3 — Draft the spec (the brainstorm, written to a file)
 
-For each criterion, list every task that could serve it. Be thorough — the user will narrow. Include:
+Do the full brainstorm below as thinking — but the **output is a written spec file**, not a numbered chat list for approval. For each criterion, list every task that could serve it. Be thorough — the Phase-4 interview will refine and prune. Include:
 
 - Existing tasks already queued for the version (you have them from Phase 1)
 - Open ideas tagged for the version that should be pulled in
@@ -147,13 +148,37 @@ Don't tunnel-vision. Surface lateral options the user might not have thought of:
 
 > **`touches[]` is an advisory hint, not a hard fence ([ADR 0049](../../../docs/adr/<redacted>.md)).** Parallel-safety is a *split contract*: for interactive single-human work, `git merge` is the authoritative collision detector and the claim-time overlap signal only warns; only the autonomous `--parallel` runner treats footprint overlap as a hard gate. So don't agonize over predicting every file at planning time — a rough blast-radius is enough, and a wrong prediction is no longer ship-blocking. (Step 7/8 — task [#882](https://example.com/builders#/task/882) — makes the per-task `touches` field optional and backfills it from the committed diff at ship.)
 
-Present the brainstorm **grouped by criterion, with every task numbered** (R## prefix or local numbering). Tags: `[E]` existing, `[I]` idea to pull, `[N]` net-new. Note totals per criterion and flag scope-tension points.
+**Write the brainstorm to a spec file — do NOT present a numbered chat list for e/r/a approval (that step is replaced by the Phase-4 interview).** Write `docs/specs/<ver>-<goal-slug>.md` (create `docs/specs/` if absent; slug = the goal's title kebab-cased). This file is the working document for the rest of the session and is committed in Phase 5. Give it these sections:
+
+- **Title + status line** — `# Spec — <goal title> (<ver>, goal <id>) · status: draft`.
+- **Summary** — 2–4 sentences: what we're building and why (the goal's outcome).
+- **Criteria (done-when)** — the goal's criteria verbatim by slug (C1, C2, …); every task links to one.
+- **Design decisions & assumptions** — what we're committing to and why; note grounding from the codebase (existing modules/tables/routes to reuse). Starts from your best defaults; the Phase-4 interview fills and revises this.
+- **Open questions (for the interview)** — the non-obvious decisions still unresolved, each with why-it-matters + the options you see. This is the raw material for Phase 4; empty it as answers land.
+- **Task outline** — grouped by criterion (and phase, if phased), one row per task: `R## · kind · title · one-line done-when · deps:[R##] · criterion_ids:[Cn]`, tagged `[E]`/`[I]`/`[N]`. Mark **spikes** (needs-exploration) and **proofs** (the live demo per criterion).
+- **Dependency graph & ranking** — filled in Phase 4 (topo order + priority tiers).
+- **Out of scope** — what this goal explicitly does NOT do, so the interview and tasks stay bounded.
+
+Tell the user the spec is written and where, then move straight to the interview — the spec is shaped THERE, not by chat edits here.
+
+### Phase 4 — Interview in depth, then finalize the spec
+
+**This is the heart of the new flow — it replaces asking for task-by-task approval.** Read the spec you just wrote, then interview the owner with the **AskUserQuestion tool** to resolve every non-obvious decision before a single task is seeded.
 
-Ask the user to **edit (e), remove (r), or add (a) tasks BY NUMBER** per criterion. Format the prompt to make this explicit: "Reply per criterion with e/r/a + the task number — e.g. 'C1: e R03, r R07, a [task description]'".
+**Run it as a loop, not a one-shot:**
 
-### Phase 4 — Rank + dependencies
+1. From the spec's *Open questions* (plus anything the task outline leaves genuinely undecided), assemble a round of up to **4 questions** and ask them with AskUserQuestion. Put a recommended option first when you have a view; always leave room for "Other."
+2. Fold the answers into the spec's *Design decisions* (and adjust the task outline if an answer reshapes the work).
+3. Re-assess: are there still non-obvious, decision-changing questions? If yes, ask another round. **Keep going until nothing material is left** — you should be able to seed every task without guessing. Then stop.
+4. The owner can end the interview early at any time ("that's enough / seed it"). Tell them this up front.
 
-Once the task list is approved, rank everything AND wire dependencies.
+**Ask only NON-OBVIOUS questions.** A question earns its place only if: the spec is genuinely underspecified on it, reasonable experts would disagree, AND the answer changes what gets built or how it's broken into tasks. Span dimensions across rounds — **data model & schema, API surface & contracts, UI/UX & information architecture, permissions/authz, privacy/consent, performance & scale, failure modes & edge cases, migration/rollout/backfill, naming the user will see, and scope boundaries.**
+
+**Do NOT ask** anything answerable by reading the codebase, anything the criteria already settle, yes/no rubber-stamps, or "do you want it to be good?" filler. If you catch yourself about to ask something with one obvious answer, decide it yourself and record it in *Design decisions* instead.
+
+> **This interview is the deliberate exception to the usual "decide implementation details yourself" default (see Tone, and CLAUDE.md §2).** The owner has explicitly asked to be consulted in depth here — so probe technical implementation, UX, tradeoffs, and concerns, not just outcomes.
+
+When the interview is complete, **rewrite the spec to the same file with `status: final`** — *Open questions* emptied into *Design decisions*, and the task outline updated. Then rank + wire dependencies and record them in the spec's *Dependency graph & ranking* section:
 
 **The system has two ordering signals — use both:**
 
@@ -184,7 +209,7 @@ Confirm what the `priority` column actually allows.
 
 The fine-grained N-deep rank lives in the title prefix: `V<ver>.R##` zero-padded so alphabetical sort returns ranking order within a priority bucket.
 
-Initial ranking: produce it yourself based on dependencies and what the user has stated as priority (e.g., "onboard builder #2 early"). Present in tiers. Ask the user to reorder, defer, or pull forward.
+Initial ranking: produce it yourself based on dependencies and what the user stated during the interview (e.g., "onboard builder #2 early"). Record the tiers in the spec's ranking section; the interview already surfaced the user's priority calls, so don't re-litigate — just reflect them.
 
 **Critical-path sequencing notes** to surface: which tasks gate which (architecture spikes gate the rest of their criterion; rename should be first; smoke tests should be last in their tier).
 
@@ -199,9 +224,9 @@ This is what the V3.R02 (task 309) dependency system encodes; Phase 5 writes bot
 
 ### Phase 5 — Land it
 
-Once ranking is agreed, do the writes in this exact order:
+Once the spec is finalized (Phase 4), **read `docs/specs/<ver>-<goal-slug>.md` as the source of truth** and do the writes in this exact order. (If the goal and its criteria already exist — e.g. this session planned tasks for a pre-existing goal — skip the goal/criteria creation in step 2 and seed the tasks under the existing goal, linking them via `criterion_ids` + `goal_id`.)
 
-1. **Create a meta planning-session task** (`source_ref='<ver>-planning-N'`) that backs all the writes — version='<ver>', kind='decision', status='ready', priority=5, the full session described in its body. Claim it.
+1. **Create a meta planning-session task** (`source_ref='<ver>-planning-N'`) that backs all the writes — version='<ver>', kind='decision', status='ready', priority=5, the full session described in its body. Claim it. (For a long session — a big spec + a multi-round interview — create and claim this meta task **early, at Phase 1**, so the spec-write and interview are themselves covered by a claim. A rebase-gated builder can't claim new work; as Archon, proceed and record the session in the meta task even if the claim is blocked, noting it.)
 
 2. **Create the version's goals, then write the criteria migration.** Goals come first (ADR 0086) so the criteria can be parented under them:
    - **Goals** (via API — `POST /goals`; Archon-only when the scope includes a `protected` module). One per goal from Phase 2.5; **capture each returned goal id**.
@@ -210,7 +235,7 @@ Once ranking is agreed, do the writes in this exact order:
      # carry-forward goal: add "succeeds_goal_id":<prior_goal_id>
      ```
    - **Criteria — the vector depends on whether the instance is LIVE ([ADR 0105](../../../docs/adr/<redacted>.md)):**
-     - **On a RUNNING instance (the normal case — planning a new goal/version on prod):** create each criterion via the **`POST /api/gds/versions/:id/done-when`** API (Archon), passing `criterion_id` (a stable slug), `criterion_md`, `goal_id` (the goal from above), and optional `sort_order`. This is the ONLY vector that actually lands a NEW criterion on a live DB — a `done_when_criteria` INSERT in a CORE migration **fails the `selfhost-boot` gate** (scope-truth pollution), and one in `migrations/instance/` **silently no-ops on a normal deploy** (ADR 0105 applies instance seeds only under the owner opt-in `GDS_APPLY_INSTANCE_SEEDS=1`, a DR step). A duplicate `criterion_id` returns 409 — treat as "already seeded."
+     - **On a RUNNING instance (the normal case — planning a new goal/version on prod):** create each criterion via the **`POST /api/gds/versions/:id/done-when`** API (**Metic+ for a goal you own or manage — [ADR 0154](../../../docs/adr/<redacted>.md); Archon for a version-level criterion, someone else's goal, or a shipped/frozen version**), passing `criterion_id` (a stable slug), `criterion_md`, `goal_id` (the goal from above), and optional `sort_order`. This is the ONLY vector that actually lands a NEW criterion on a live DB — a `done_when_criteria` INSERT in a CORE migration **fails the `selfhost-boot` gate** (scope-truth pollution), and one in `migrations/instance/` **silently no-ops on a normal deploy** (ADR 0105 applies instance seeds only under the owner opt-in `GDS_APPLY_INSTANCE_SEEDS=1`, a DR step). A duplicate `criterion_id` returns 409 — treat as "already seeded."
        ```
        node scripts/gds/api.js POST /api/gds/versions/<ver>/done-when --body '{"criterion_id":"<slug>","criterion_md":"...","goal_id":<gid>}'
        ```
@@ -224,6 +249,8 @@ Once ranking is agreed, do the writes in this exact order:
    - **Pass `goal_id: <gid>` on each task** so it lands under its goal (not the version's default catch-all). `POST /tasks` now honors `goal_id` (validated to belong to the version); to move an already-created task, `PATCH /tasks/:id` with `{goal_id}` (task 1763). `criterion_ids` accepts a **slug** (the `criterion_id` you set above), a `"Cn"` position, or a numeric id — the slug is position-independent and cleanest.
    - A main() that POSTs each task **with its `criterion_ids`** (idempotent on `source_ref`; the criterion links are inserted at create, idempotent on `(task_id, criterion_id)`), PATCHes `idea_inbox` for promotions, and after all tasks exist, POSTs `task_dependencies` via `POST /tasks/:id/dependencies` (resolving each R## to the just-created task ID). Idempotent on `(task_id, depends_on_task_id)`. (Need to re-attribute an already-seeded task? `POST /tasks/:id/criteria` with `{criterion_ids:['Cn',...]}`; `DELETE /tasks/:id/criteria/:criterionId` to detach — both Metic+ ([ADR 0090](../../../docs/adr/<redacted>.md)), mirroring the dependency endpoints.)
 
+> **Seeding contract — validated on goal 1000045 (2026-07-16):** proof-tasks use `kind='verify'` (a deliverable that IS a verification; can't be prematurely confirmed), spikes `kind='spike'`; `POST /tasks` accepts `criterion_ids` + `goal_id` inline and disciplines include `ui`; there is **no `promoted_idea_id`** field on `POST /tasks` — mark a promoted idea via `PATCH /inbox/:id`; **descoping a criterion has no API** (done-when is create/satisfy/unsatisfy only) — remove the row via a direct DB delete (`ssh … "sudo -u postgres psql -d <db> -c \"DELETE FROM done_when_criteria WHERE id=…\""`) under the meta-task claim, capturing the SQL in its notes; and a seed script **must throttle + honor `429` `retry_after`** (per-IP rate limit) — add a base delay between calls and back off on 429, or a large seed dies halfway. A completed reference seed: `scripts/gds/<redacted>.js`.
+
 4. **Apply the migration** (commit + push + deploy, or direct psql via SSH for hot-fix style).
 
 5. **Run the seed script.** Verify exit code 0; verify totals via `GET /api/gds/public/progress` and `GET /api/gds/versions/<ver>/done-when`.
@@ -262,7 +289,7 @@ Once ranking is agreed, do the writes in this exact order:
 
    If the query returns nothing, stay silent. Don't volunteer info about lower-priority spikes — the next planning session or `/idea-triage` walk will handle those at the right moment.
 
-8. **Commit + push** the migration + seed script + any new skill files + the session-log entry.
+8. **Commit + push** the spec file (`docs/specs/<ver>-<goal-slug>.md`) + the migration + seed script + any new skill files + the session-log entry.
 
 9. **Ship the meta task** via `/builder-ship` with a clean value-summary.
 
@@ -284,11 +311,11 @@ Phase 5 writes use the same `POST /tasks`, `PATCH /inbox/:id` shape as `idea-tri
 
 ## Tone for the user
 
-Lars is the prompter (see CLAUDE.md §2). Frame criteria and tasks in terms of outcomes and player/builder experience, not implementation. When asking him questions, ask about *what changes when this is true*, not *how would we build it*. Decide implementation details yourself and present them for confirmation.
+Lars is the prompter (see CLAUDE.md §2). Frame criteria and tasks in terms of outcomes and player/builder experience, not implementation. **Exception: the Phase-4 interview is deliberately in-depth** — there the owner has asked to be consulted on implementation, UX, tradeoffs, and concerns, so probe hard (non-obvious questions only). Outside that interview, keep the default: decide implementation details yourself and present them for confirmation.
 
 When the user pushes back ("criteria 4/5/6 are weak"), take it seriously and rewrite. Strong outcome criteria are the hard part — the rest of the session is downstream of them.
 
-When the user says "I am ready to rank" or "produce the initial ranking," do it in one shot. Don't bounce back with more clarification questions unless something genuinely ambiguous needs resolving.
+When the user ends the interview ("that's enough" / "seed it"), finalize the spec and seed in one shot — don't re-open settled questions or bounce back for more approval.
 
 ## After the session — improvements pass
 

package/.env.local.example

@@ -20,9 +20,10 @@
 GOOGLE_AI_STUDIO_KEY=
 
 # --- GDS CLI ------------------------------------------------------------------
-# Where the /builder-* CLI talks to. Defaults to production when unset; only
-# override if you're running the server locally.
-# GDS_API_BASE=http://localhost:3000
+# The /builder-* CLI base is NOT read from this file. It resolves (in order):
+#   1. the <PREFIX>_API_BASE env var on the command (e.g. CLOUDBONGOS_API_BASE=https://…)
+#   2. the signed-in session's api_base (set once by `bongos login <instance-url>`)
+#   3. the instance's own branding (config/branding.json → branding.neutral.json)
 
 # --- GitHub OAuth (server only) -----------------------------------------------
 # Needed only if you are running the GDS server yourself (server.js) and want

package/README.md

@@ -50,12 +50,14 @@ When it finishes, open Claude Code and run `/builder-start` to see what tasks ar
 
 We keep secrets (`.env` files, API keys, private keys) out of the repo with two layers. Both are **instance topology** — the git hook (`.husky/`) and CI (`.github/`) are provided when you stand up an instance and are not shipped in the portable core; the pattern below is the recommended posture:
 
-- **Pre-commit hook** (`.husky/pre-commit`) — scans your *staged* changes before each commit and aborts if it finds a secret. Activate it **once per clone**:
+- **Pre-commit hook** (`.husky/pre-commit`) — scans your *staged* changes before each commit and aborts if it finds a secret. On an instance that ships `.husky/`, activate it **once per clone**:
 
   ```sh
-  git config core.hooksPath .husky
+  node scripts/gds/install-git-hooks.js
   ```
 
+  Prefer that over setting `core.hooksPath` by hand: it no-ops cleanly on a checkout without a `.husky/` (the portable core), whereas pointing `core.hooksPath` at a directory that isn't there leaves git with a dangling hooks path and no gate. `node scripts/gds/doctor.js` reports which case you're in.
+
   It always runs a built-in guard (blocks `.env`, `*.pem`, credential files, obvious key patterns). If [TruffleHog](https://github.com/trufflesecurity/trufflehog) is installed (`brew install trufflehog` on macOS; `scoop install trufflehog` / `choco install trufflehog` or the GitHub release on Windows) it also runs a deep scan; if not, it warns and lets the commit through — CI is the real gate.
 
   > **Windows:** git runs the `.husky/pre-commit` hook through the Git-Bash `sh` bundled with Git for Windows, so the hook works if you installed Git for Windows (the usual case). If you don't have a `sh` available, the local hook silently no-ops — CI's full-history TruffleHog scan is then your only gate (and it always runs regardless of platform).

package/bin/bongos.js

@@ -86,6 +86,7 @@ const VERBS = {
   code:    { script: 'code.js',  group: 'account', summary: 'Open VS Code on your dev box over Remote-SSH  (--local for a local clone)' },
 
   init:    { script: 'init.js', group: 'instance', summary: 'Scaffold a new instance (config + first version + kickoff tasks)' },
+  dev:     { script: 'dev.js', group: 'instance', summary: 'Run THIS instance locally in one command (Postgres + migrate + server + sign-in)' },
   onboard: { script: 'onboard.js', group: 'instance', summary: 'Guided zero-to-live walkthrough: init → scaffold → provision → OAuth → verify → brand' },
   module:  { script: 'module.js', group: 'instance', summary: 'Scaffold a new module  (bongos module new <key>)' },
   upgrade: { script: 'upgrade.js', group: 'instance', summary: 'Pull the core to a new version (bump pin→install→migrate→materialize→restart); bare = module-compat pre-check' },

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 230 operations across 40 resource groups
+- 258 operations across 44 resource groups
 
 ## Install
 
@@ -19,7 +19,7 @@ npm install @bongos/client   # internal registry / workspace path
 import { createClient, ApiError } from '@bongos/client';
 
 const api = createClient({
-  baseUrl: 'https://example.com/api/bongos/v1', // or omit for same-origin (browser)
+  baseUrl: 'https://example.com/api/bongos/v1', // your instance origin — or omit for same-origin (browser)
   token: <redacted>,             // Authorization: Bearer <token>
 });
 

package/clients/bongos-client/bongos-client.global.js

@@ -115,8 +115,12 @@ function createClient(opts = {}) {
       postAuthAppPairPoll: (args) => request("POST", "/auth/app-pair/poll", { hasBody: true }, args),
       // POST /auth/app-pair/start — rank: public — POST /auth/app-pair/start
       postAuthAppPairStart: (args) => request("POST", "/auth/app-pair/start", { hasBody: true }, args),
+      // POST /auth/backchannel-logout — rank: public — POST /auth/backchannel-logout
+      postAuthBackchannelLogout: (args) => request("POST", "/auth/backchannel-logout", { hasBody: true }, args),
       // POST /auth/cli-token/issue — rank: any-builder — POST /auth/cli-token/issue
       postAuthCliTokenIssue: (args) => request("POST", "/auth/cli-token/issue", { hasBody: true }, args),
+      // POST /auth/device/exchange — rank: public — POST /auth/device/exchange
+      postAuthDeviceExchange: (args) => request("POST", "/auth/device/exchange", { hasBody: true }, args),
       // POST /auth/device/poll — rank: public — POST /auth/device/poll
       postAuthDevicePoll: (args) => request("POST", "/auth/device/poll", { hasBody: true }, args),
       // POST /auth/device/start — rank: public — POST /auth/device/start
@@ -133,6 +137,8 @@ function createClient(opts = {}) {
       postAuthRevoke: (args) => request("POST", "/auth/revoke", { hasBody: true }, args),
       // POST /auth/revoke-all — rank: archon — POST /auth/revoke-all
       postAuthRevokeAll: (args) => request("POST", "/auth/revoke-all", { hasBody: true }, args),
+      // GET /auth/web/admission-status — rank: public — GET /auth/web/admission-status
+      getAuthWebAdmissionStatus: (args) => request("GET", "/auth/web/admission-status", { hasBody: false }, args),
       // GET /auth/web/callback — rank: public — GET /auth/web/callback
       getAuthWebCallback: (args) => request("GET", "/auth/web/callback", { hasBody: false }, args),
       // GET /auth/web/start — rank: public — GET /auth/web/start
@@ -181,6 +187,8 @@ function createClient(opts = {}) {
       getBoxManagedSettings: (args) => request("GET", "/box/managed-settings", { hasBody: false }, args),
       // GET /box/me — rank: any-builder — GET /box/me
       getBoxMe: (args) => request("GET", "/box/me", { hasBody: false }, args),
+      // GET /box/scope — rank: any-builder — GET /box/scope
+      getBoxScope: (args) => request("GET", "/box/scope", { hasBody: false }, args),
       // GET /box/source-access — rank: any-builder — GET /box/source-access
       getBoxSourceAccess: (args) => request("GET", "/box/source-access", { hasBody: false }, args),
       // GET /box/ssh-key — rank: any-builder — GET /box/ssh-key
@@ -248,12 +256,6 @@ function createClient(opts = {}) {
       // POST /cost — rank: any-builder — POST /cost
       postCost: (args) => request("POST", "/cost", { hasBody: true }, args),
     },
-    "demo": {
-      // GET /demo/health — rank: public — GET /demo/health
-      getDemoHealth: (args) => request("GET", "/demo/health", { hasBody: false }, args),
-      // POST /demo/ping — rank: metic+archon — POST /demo/ping
-      postDemoPing: (args) => request("POST", "/demo/ping", { hasBody: true }, args),
-    },
     "dependencies": {
       // DELETE /dependencies — rank: archon — DELETE /dependencies
       deleteDependencies: (args) => request("DELETE", "/dependencies", { hasBody: false }, args),
@@ -280,6 +282,12 @@ function createClient(opts = {}) {
       // POST /gate-approvals/{pr}/approve — rank: archon — POST /gate-approvals/:pr/approve
       postGateApprovalsPrApprove: (args) => request("POST", "/gate-approvals/{pr}/approve", { hasBody: true }, args),
     },
+    "github": {
+      // GET /github/repos — rank: any-builder — GET /github/repos
+      getGithubRepos: (args) => request("GET", "/github/repos", { hasBody: false }, args),
+      // POST /github/repos — rank: any-builder — POST /github/repos
+      postGithubRepos: (args) => request("POST", "/github/repos", { hasBody: true }, args),
+    },
     "goals": {
       // GET /goals — rank: any-builder — GET /goals
       getGoals: (args) => request("GET", "/goals", { hasBody: false }, args),
@@ -347,6 +355,8 @@ function createClient(opts = {}) {
       getInboxId: (args) => request("GET", "/inbox/{id}", { hasBody: false }, args),
       // PATCH /inbox/{id} — rank: metic+archon — PATCH /inbox/:id
       patchInboxId: (args) => request("PATCH", "/inbox/{id}", { hasBody: true }, args),
+      // POST /inbox/{id}/ratify — rank: archon — POST /inbox/:id/ratify
+      postInboxIdRatify: (args) => request("POST", "/inbox/{id}/ratify", { hasBody: true }, args),
     },
     "instance": {
       // GET /instance — rank: public — GET /instance
@@ -379,16 +389,6 @@ function createClient(opts = {}) {
       getMeAchievements: (args) => request("GET", "/me/achievements", { hasBody: false }, args),
       // POST /me/anthropic-link — rank: any-builder — POST /me/anthropic-link
       postMeAnthropicLink: (args) => request("POST", "/me/anthropic-link", { hasBody: true }, args),
-      // GET /me/art-key — rank: any-builder — GET /me/art-key
-      getMeArtKey: (args) => request("GET", "/me/art-key", { hasBody: false }, args),
-      // DELETE /me/art-key/own — rank: any-builder — DELETE /me/art-key/own
-      deleteMeArtKeyOwn: (args) => request("DELETE", "/me/art-key/own", { hasBody: false }, args),
-      // GET /me/art-key/own — rank: any-builder — GET /me/art-key/own
-      getMeArtKeyOwn: (args) => request("GET", "/me/art-key/own", { hasBody: false }, args),
-      // PUT /me/art-key/own — rank: any-builder — PUT /me/art-key/own
-      putMeArtKeyOwn: (args) => request("PUT", "/me/art-key/own", { hasBody: true }, args),
-      // POST /me/art-key/storage-init — rank: archon — POST /me/art-key/storage-init
-      postMeArtKeyStorageInit: (args) => request("POST", "/me/art-key/storage-init", { hasBody: true }, args),
       // PATCH /me/disciplines — rank: any-builder — PATCH /me/disciplines
       patchMeDisciplines: (args) => request("PATCH", "/me/disciplines", { hasBody: true }, args),
       // GET /me/display-name — rank: any-builder — GET /me/display-name
@@ -433,6 +433,10 @@ function createClient(opts = {}) {
       getMemoryBfgBuildersBuilderIdFiles: (args) => request("GET", "/memory/bfg/builders/{builderId}/files", { hasBody: false }, args),
       // POST /memory/builders/{builderId}/bfg-write — rank: bfg-principal — POST /memory/builders/:builderId/bfg-write
       postMemoryBuildersBuilderIdBfgWrite: (args) => request("POST", "/memory/builders/{builderId}/bfg-write", { hasBody: true }, args),
+      // GET /memory/builders/{builderId}/file — rank: archon — GET /memory/builders/:builderId/file
+      getMemoryBuildersBuilderIdFile: (args) => request("GET", "/memory/builders/{builderId}/file", { hasBody: false }, args),
+      // GET /memory/builders/{builderId}/files — rank: archon — GET /memory/builders/:builderId/files
+      getMemoryBuildersBuilderIdFiles: (args) => request("GET", "/memory/builders/{builderId}/files", { hasBody: false }, args),
       // DELETE /memory/file — rank: any-builder — DELETE /memory/file
       deleteMemoryFile: (args) => request("DELETE", "/memory/file", { hasBody: true }, args),
       // GET /memory/file — rank: any-builder — GET /memory/file
@@ -452,12 +456,38 @@ function createClient(opts = {}) {
       // GET /modules/submissions — rank: metic+archon — GET /modules/submissions
       getModulesSubmissions: (args) => request("GET", "/modules/submissions", { hasBody: false }, args),
     },
+    "myProjects": {
+      // GET /my-projects — rank: any-builder — GET /my-projects
+      getMyProjects: (args) => request("GET", "/my-projects", { hasBody: false }, args),
+      // POST /my-projects/{clientId}/leave — rank: any-builder — POST /my-projects/:clientId/leave
+      postMyProjectsClientIdLeave: (args) => request("POST", "/my-projects/{clientId}/leave", { hasBody: true }, args),
+      // GET /my-projects/invites — rank: any-builder — GET /my-projects/invites
+      getMyProjectsInvites: (args) => request("GET", "/my-projects/invites", { hasBody: false }, args),
+      // POST /my-projects/invites/{clientId}/accept — rank: any-builder — POST /my-projects/invites/:clientId/accept
+      postMyProjectsInvitesClientIdAccept: (args) => request("POST", "/my-projects/invites/{clientId}/accept", { hasBody: true }, args),
+      // POST /my-projects/invites/{clientId}/decline — rank: any-builder — POST /my-projects/invites/:clientId/decline
+      postMyProjectsInvitesClientIdDecline: (args) => request("POST", "/my-projects/invites/{clientId}/decline", { hasBody: true }, args),
+      // POST /my-projects/join — rank: any-builder — POST /my-projects/join
+      postMyProjectsJoin: (args) => request("POST", "/my-projects/join", { hasBody: true }, args),
+    },
     "overrideRequests": {
       // GET /override-requests — rank: archon — GET /override-requests
       getOverrideRequests: (args) => request("GET", "/override-requests", { hasBody: false }, args),
       // POST /override-requests/{id}/decide — rank: archon — POST /override-requests/:id/decide
       postOverrideRequestsIdDecide: (args) => request("POST", "/override-requests/{id}/decide", { hasBody: true }, args),
     },
+    "projects": {
+      // GET /projects — rank: archon — GET /projects
+      getProjects: (args) => request("GET", "/projects", { hasBody: false }, args),
+      // POST /projects — rank: archon — POST /projects
+      postProjects: (args) => request("POST", "/projects", { hasBody: true }, args),
+      // PATCH /projects/{id}/featured — rank: archon — PATCH /projects/:id/featured
+      patchProjectsIdFeatured: (args) => request("PATCH", "/projects/{id}/featured", { hasBody: true }, args),
+      // GET /projects/featured — rank: public — GET /projects/featured
+      getProjectsFeatured: (args) => request("GET", "/projects/featured", { hasBody: false }, args),
+      // POST /projects/invite — rank: archon — POST /projects/invite
+      postProjectsInvite: (args) => request("POST", "/projects/invite", { hasBody: true }, args),
+    },
     "provisioning": {
       // GET /provisioning/fleet — rank: archon — GET /provisioning/fleet
       getProvisioningFleet: (args) => request("GET", "/provisioning/fleet", { hasBody: false }, args),
@@ -524,6 +554,10 @@ function createClient(opts = {}) {
       // GET /public/versions — rank: public — GET /public/versions
       getPublicVersions: (args) => request("GET", "/public/versions", { hasBody: false }, args),
     },
+    "scouting": {
+      // GET /scouting — rank: archon — GET /scouting
+      getScouting: (args) => request("GET", "/scouting", { hasBody: false }, args),
+    },
     "search": {
       // POST /search — rank: any-builder — POST /search
       postSearch: (args) => request("POST", "/search", { hasBody: true }, args),
@@ -531,12 +565,26 @@ function createClient(opts = {}) {
       postSearchMark: (args) => request("POST", "/search/mark", { hasBody: true }, args),
     },
     "security": {
+      // GET /security/adr — rank: metic+archon — GET /security/adr
+      getSecurityAdr: (args) => request("GET", "/security/adr", { hasBody: false }, args),
       // GET /security/docs — rank: archon — GET /security/docs
       getSecurityDocs: (args) => request("GET", "/security/docs", { hasBody: false }, args),
       // POST /security/docs — rank: archon — POST /security/docs
       postSecurityDocs: (args) => request("POST", "/security/docs", { hasBody: true }, args),
       // GET /security/docs/{slug} — rank: archon — GET /security/docs/:slug
       getSecurityDocsSlug: (args) => request("GET", "/security/docs/{slug}", { hasBody: false }, args),
+      // GET /security/reports — rank: archon — GET /security/reports
+      getSecurityReports: (args) => request("GET", "/security/reports", { hasBody: false }, args),
+      // POST /security/reports — rank: metic+archon — POST /security/reports
+      postSecurityReports: (args) => request("POST", "/security/reports", { hasBody: true }, args),
+      // POST /security/reports/{id}/confirm — rank: archon — POST /security/reports/:id/confirm
+      postSecurityReportsIdConfirm: (args) => request("POST", "/security/reports/{id}/confirm", { hasBody: true }, args),
+      // POST /security/reports/{id}/dispute — rank: archon — POST /security/reports/:id/dispute
+      postSecurityReportsIdDispute: (args) => request("POST", "/security/reports/{id}/dispute", { hasBody: true }, args),
+      // POST /security/reports/{id}/fix — rank: archon — POST /security/reports/:id/fix
+      postSecurityReportsIdFix: (args) => request("POST", "/security/reports/{id}/fix", { hasBody: true }, args),
+      // POST /security/reports/{id}/link-fix — rank: archon — POST /security/reports/:id/link-fix
+      postSecurityReportsIdLinkFix: (args) => request("POST", "/security/reports/{id}/link-fix", { hasBody: true }, args),
     },
     "session": {
       // POST /session/optimize — rank: any-builder — POST /session/optimize
@@ -552,6 +600,22 @@ function createClient(opts = {}) {
       // GET /sessions/search — rank: archon — GET /sessions/search
       getSessionsSearch: (args) => request("GET", "/sessions/search", { hasBody: false }, args),
     },
+    "sso": {
+      // POST /sso/activity/rollup — rank: public — POST /sso/activity/rollup
+      postSsoActivityRollup: (args) => request("POST", "/sso/activity/rollup", { hasBody: true }, args),
+      // GET /sso/authorize — rank: public — GET /sso/authorize
+      getSsoAuthorize: (args) => request("GET", "/sso/authorize", { hasBody: false }, args),
+      // POST /sso/device/poll — rank: public — POST /sso/device/poll
+      postSsoDevicePoll: (args) => request("POST", "/sso/device/poll", { hasBody: true }, args),
+      // POST /sso/device/start — rank: public — POST /sso/device/start
+      postSsoDeviceStart: (args) => request("POST", "/sso/device/start", { hasBody: true }, args),
+      // POST /sso/membership/check-in — rank: public — POST /sso/membership/check-in
+      postSsoMembershipCheckIn: (args) => request("POST", "/sso/membership/check-in", { hasBody: true }, args),
+      // GET /sso/pubkey — rank: public — GET /sso/pubkey
+      getSsoPubkey: (args) => request("GET", "/sso/pubkey", { hasBody: false }, args),
+      // POST /sso/token — rank: public — POST /sso/token
+      postSsoToken: (args) => request("POST", "/sso/token", { hasBody: true }, args),
+    },
     "tasks": {
       // GET /tasks — rank: any-builder — GET /tasks
       getTasks: (args) => request("GET", "/tasks", { hasBody: false }, args),
@@ -561,7 +625,7 @@ function createClient(opts = {}) {
       getTasksId: (args) => request("GET", "/tasks/{id}", { hasBody: false }, args),
       // PATCH /tasks/{id} — rank: metic+archon — PATCH /tasks/:id
       patchTasksId: (args) => request("PATCH", "/tasks/{id}", { hasBody: true }, args),
-      // POST /tasks/{id}/abandon — rank: archon — POST /tasks/:id/abandon
+      // POST /tasks/{id}/abandon — rank: metic+archon — POST /tasks/:id/abandon
       postTasksIdAbandon: (args) => request("POST", "/tasks/{id}/abandon", { hasBody: true }, args),
       // POST /tasks/{id}/attest-gate — rank: any-builder — POST /tasks/:id/attest-gate
       postTasksIdAttestGate: (args) => request("POST", "/tasks/{id}/attest-gate", { hasBody: true }, args),
@@ -615,7 +679,7 @@ function createClient(opts = {}) {
       postVersions: (args) => request("POST", "/versions", { hasBody: true }, args),
       // GET /versions/{id}/done-when — rank: public — GET /versions/:id/done-when
       getVersionsIdDoneWhen: (args) => request("GET", "/versions/{id}/done-when", { hasBody: false }, args),
-      // POST /versions/{id}/done-when — rank: archon — POST /versions/:id/done-when
+      // POST /versions/{id}/done-when — rank: metic+archon — POST /versions/:id/done-when
       postVersionsIdDoneWhen: (args) => request("POST", "/versions/{id}/done-when", { hasBody: true }, args),
       // GET /versions/{id}/progress — rank: public — GET /versions/:id/progress
       getVersionsIdProgress: (args) => request("GET", "/versions/{id}/progress", { hasBody: false }, args),