@bongos/core 1.17.0

package/docs/adr/0116-api-error-envelope-and-code-taxonomy.md

@@ -0,0 +1,62 @@
+# ADR 0116 — API error envelope + code taxonomy
+
+**Date:** 2026-07-04
+**Status:** Accepted (contract; R01 of goal 36).
+**Context:** [task 1988](https://builders.example.com#/task/1988) (BONGOS-V1, goal 36 "Robust, versioned, easy-to-call public API", criterion `api-error-envelope`). This is the **contract** the rest of the criterion implements: the central middleware + `res.fail()` helper ([task 1989](https://builders.example.com#/task/1989), R02), the build check that holds the line ([task 1990](https://builders.example.com#/task/1990), R03), and the sweep of existing handlers onto it ([task 1991](https://builders.example.com#/task/1991), R04). Sibling contracts in the same goal: versioning (R05), the source-of-truth spike (R07), validation (C4), pagination (C5).
+
+## Problem
+
+An audit of the live API surface (`src/bongos/` + `modules/*/routes/`) found **352 distinct `error:'…'` string literals**, returned across HTTP statuses 400/401/403/404/409/413/422/429/500/502/503 in three or four different response *shapes* (`res.status(n).json({error})`, bare `res.json({error})`, `res.status(500).json({error, message})`, `res.sendStatus(n)`). A caller — the CLI, the Dev Box app, a web page, or an external self-hoster — cannot write **one** error-handling path against that: there is no guaranteed key to read, no stable status, and no way to tell a retriable failure from a permanent one. The codes are not the problem (a specific slug like `task_not_found` is useful); the *absence of a documented, uniform envelope and a classification* is.
+
+## Decision
+
+**One envelope, everywhere:**
+
+```json
+{ "error": { "code": "task_not_found", "message": "…", "details": … } }
+```
+
+- **`code`** — a stable machine-readable slug the caller may switch on. **The specific slug is preserved** — a caller keying on `task_not_found` keeps working. The taxonomy collapses codes by *category*; it does not discard them.
+- **`message`** — human-readable, safe to surface. Internals are never echoed unless a handler opts in.
+- **`details`** — optional structured payload (e.g. the validator's `[{field,reason}]`).
+
+**A registry, not 352 loose strings** — `src/bongos/api-errors.js` (kernel, core). It defines **~12 canonical categories**, each with a default HTTP status and a `retriable` flag:
+
+| category | status | retriable | meaning |
+|---|---|---|---|
+| `bad_request` | 400 | no | malformed/invalid input |
+| `validation_failed` | 400 | no | spec/schema validation failed; `details` lists field errors |
+| `unauthenticated` | 401 | no | no valid session/credential |
+| `forbidden` | 403 | no | rank/ownership insufficient |
+| `not_found` | 404 | no | resource missing |
+| `conflict` | 409 | no | clashes with current state (exists, cycle, active claim, stale tip) |
+| `payload_too_large` | 413 | no | body/element over the limit |
+| `unprocessable` | 422 | no | well-formed but semantically unacceptable |
+| `rate_limited` | 429 | **yes** | too many requests / quota |
+| `internal` | 500 | **yes** | unexpected error or a server-side op that failed |
+| `bad_gateway` | 502 | **yes** | upstream returned garbage |
+| `unavailable` | 503 | **yes** | dependency/feature not configured or down |
+
+Every one of the 352 codes classifies onto a category via **`classify(code)`** — an explicit `OVERRIDES` table for the exceptions the naming can't disambiguate (auth codes, preconditions read as conflicts, `*_too_large`), plus a **suffix/prefix heuristic** for the long tail that encodes the conventions the audit surfaced: `*_failed`/`*_error` → `internal`; `*_not_found` → `not_found`; `bad_*`/`invalid_*`/`*_required`/`*_mismatch` → `bad_request`; `already_*`/`*_taken`/`*_exists`/`*_conflict` → `conflict`; `*_unconfigured` → `unavailable`. `classify` is **pure + total**: an unrecognised (or future) code falls back to `internal` (500) — the safe default — never throwing.
+
+The module also ships the **`ApiError`** carrier (`throw new ApiError(code, {status?, message?, details?})` — status/category derived from the registry) and the pure **`envelope()`** formatter. `statusForCode(code, override)` lets a call site keep its current status where it differs from the category default (e.g. a route already returning 422) — so the R04 sweep changes *shape*, not *status*, and is safe.
+
+## Why this shape
+
+- **`{error:{…}}` (nested), not `{error:'code', message:'…'}` (flat).** A nested object gives one place to grow (`details`, later `retriable`/`docs_url`) without colliding with a payload field, and lets a caller test `resp.error` as the single failure discriminator. The flat shape is what today's mess already is.
+- **Preserve codes, collapse by category.** Discarding 352 codes down to 12 would break every caller that reads a specific code and lose real signal. Classification is additive: the code stays; the category + status become *derivable* and uniform.
+- **Heuristic + overrides, not a 352-row frozen table.** The naming conventions are real and regular; encoding them as rules keeps the registry small and auto-classifies future codes, while the override table pins the ~90 genuine exceptions. The classifier is authoritative — R02/R04 call it, they don't re-decide.
+- **Contract-only now, zero behaviour change.** Nothing imports `api-errors.js` yet, so this ADR + module + test ships without touching a single response. R02 wires the middleware; R04 sweeps the handlers behind the R03 build check.
+
+## Consequences
+
+- A caller can finally write one path: read `resp.error.code`, branch on `resp.error` presence, retry on the `retriable` categories (429/5xx).
+- The OpenAPI spec (R07/`gen-api-docs.js`) can advertise the envelope as the single error schema and the category set as an enum.
+- The sweep (R04) is mechanical: replace each `res.status(n).json({error:'x'})` with `res.fail('x')` (or `throw new ApiError('x')`), status preserved via the registry. The R03 build check fails any new hand-rolled flat error, so the line holds as the sweep progresses.
+
+## Rejected
+
+- **A flat `{error, message}`.** Already the de-facto shape; no room to grow, and `error` doubling as both discriminator and code is what callers can't rely on.
+- **Renumbering to numeric error codes (e.g. `BONGOS-1234`).** Opaque to humans, needs a lookup table, and throws away the self-describing slugs.
+- **Collapsing to ~12 codes only.** Loses per-operation signal and breaks specific-code callers.
+- **A per-module registry.** The whole point is *one* shape across core + every module; a shared kernel registry is the only thing that guarantees it.

package/docs/adr/0117-api-versioning-and-deprecation-policy.md

@@ -0,0 +1,50 @@
+# ADR 0117 — API versioning + deprecation policy
+
+**Date:** 2026-07-04
+**Status:** Accepted (policy; R05 of goal 36).
+**Context:** [task 1992](https://builders.example.com#/task/1992) (BONGOS-V1, goal 36 "Robust, versioned, easy-to-call public API", criterion `api-versioning`). This is the **policy**; the mount + aliasing that implements it is R06 ([task 1993](https://builders.example.com#/task/1993)). Builds on the API-prefix chokepoint ([`src/gds/api-prefix.js`](../../src/gds/api-prefix.js), task 1918/1919), the self-describing OpenAPI + hosted `/docs` ([ADR 0109](<redacted>.md)), and the docs-discovery contract ([ADR 0114](<redacted>.md)).
+
+## Problem
+
+The API (212 endpoints) is served at `/api/bongos` (canonical) with `/api/gds` as a permanent silent alias. Neither is a **version** — they are *prefix* names. There is no version marker in the path, no written definition of what a breaking change is, and no deprecation policy. So today any change — a removed field, a tightened validation, a changed status code — can silently break a self-hoster's integration, a shipped Dev Box binary, or the status dashboard, with no signalling and no migration window. Two things also get conflated: the **software version** (OpenAPI `info.version` = the core package semver, which moves every release) and the **API contract version** (which should move only on a breaking change). A caller must be able to pin to a contract that won't shift under it.
+
+## Decision
+
+**1. An explicit version segment in the path: `/api/bongos/v1/…`.** The version is a path marker (`v1`, `v2`, …) immediately after the prefix — coarse-grained (a whole-surface major), the shape almost every caller finds easiest to pin and reason about. It is the **contract** version, distinct from the package semver.
+
+**2. Today's unversioned paths are PERMANENT aliases pinned to v1.** `/api/bongos/<x>` and `/api/gds/<x>` keep working forever and resolve to **v1** semantics. This extends the existing permanent-`/api/gds`-alias decision (`api-prefix.js`): shipped Dev Box desktop binaries, live boxes, and the separately-hosted status-dashboard mirror all call unversioned `/api/gds/…` and **cannot be force-updated**, so their surface can never be removed.
+
+The load-bearing safety rule: **an unversioned path never silently jumps major versions.** When v2 ships, it mounts at `/api/bongos/v2/…`; the unversioned alias **stays pinned to v1**. An old caller keeps getting v1 behaviour; only a caller that explicitly asks for `/v2/` gets the new contract. Breaking changes therefore reach only opted-in callers.
+
+**3. What counts as a breaking change** (bumps the major → new `/vN`):
+
+- Removing or renaming an endpoint, a request/response field, or an error `code`.
+- Changing a field's type, or an endpoint's success status code.
+- Adding a newly-*required* request field, or tightening validation to reject input that was previously accepted.
+- Narrowing auth/rank so a call that used to succeed now 403s.
+- Changing a default that alters a response's shape/size (e.g. a pagination default).
+
+**Non-breaking** (ships within the current version, no bump):
+
+- Adding an endpoint, an *optional* request field, or a new response field.
+- Adding a new error `code` **within an existing category** (the ADR 0116 envelope means a caller already handles unknown codes by category, so this is safe).
+- Relaxing validation; adding an optional query param.
+
+**4. Deprecation window.** A version, once superseded, lives **≥ 180 days** past its successor's GA before it may be removed. While deprecated it returns RFC 8594 `Deprecation: true` + `Sunset: <date>` response headers and is marked deprecated in the OpenAPI spec + `/docs`. The **unversioned alias is exempt** — it is permanent (rule 2), never sunset. Only explicitly-versioned prefixes (`/v1`, `/v2`, …) are subject to the window. Removal of a sunset version is itself a tracked, announced task (build-broadcast to the team channel), never silent.
+
+**5. The version is discoverable.** The OpenAPI spec grows a `servers` entry for `…/v1` and an `x-api-version: "v1"` marker; `info.version` continues to track the **package** semver (unchanged — it is the software build, not the contract). The machine-discovery index (`GET <publicOrigin>/api/bongos`, ADR 0114) advertises the current + supported contract versions. `/docs` states the version. `api-prefix.js` grows the version constant so the whole surface reads it from one chokepoint (the R06 implementation).
+
+## Consequences
+
+- A self-hoster or external program pins `…/v1/…` and is guaranteed a stable contract for ≥ 180 days past any successor; unversioned/legacy callers never break at all.
+- Day one is a no-op for every existing consumer: R06 mounts the current surface at `/v1` and aliases the unversioned paths into it, so nothing changes behaviourally — the version just becomes *nameable*.
+- Shipping a breaking change is now a deliberate, expensive, announced act (a new `/vN` + a deprecation clock), not an accident — which is the whole point.
+- The contract/package split means routine releases (bug fixes, new endpoints) never churn the version a caller pinned.
+
+## Rejected
+
+- **Header-based versioning (`Accept: application/vnd.bongos.v1+json`).** Invisible in a URL, harder to `curl`, easy to forget → callers silently get the default. A path segment is self-evident and cache-friendly. (The AI-agent + self-hoster audience copies URLs, not header incantations.)
+- **Per-endpoint / semver-in-path versioning (`/v1.2.3/`).** Too fine-grained; callers would chase patch versions. Whole-surface majors match how the contract actually breaks.
+- **No version, "just don't break it."** The status quo — which is exactly the problem: no signal, no window, no way to pin.
+- **Sunsetting the unversioned alias too.** Would break un-updatable shipped binaries; the permanent-alias precedent (`api-prefix.js`) is deliberate and kept.
+- **Reusing `info.version` (package semver) as the API version.** Conflates software build with contract; every release would look like a version change.

package/docs/adr/0118-api-contract-source-of-truth-code-first.md

@@ -0,0 +1,47 @@
+# ADR 0118 — API contract source-of-truth: code-first, schema-as-data
+
+**Date:** 2026-07-04
+**Status:** Accepted (spike; R07 of goal 36).
+**Context:** [task 1994](https://builders.example.com#/task/1994) (BONGOS-V1, goal 36, criteria `api-client-sdk` + `api-validation`). The spike that shapes the SDK (R08–R10) and validation (R11–R12): does the OpenAPI spec become the **source** (schema-first — author schemas, generate routes + validation + client), or stay **generated from code** (code-first) with codegen layered on? Builds on the self-describing OpenAPI generator ([ADR 0109](<redacted>.md), `scripts/gds/gen-api-docs.js`) and the error envelope ([ADR 0116](<redacted>.md)).
+
+## What exists today
+
+`gen-api-docs.js` (ADR 0109) already generates the OpenAPI spec **from the route source**: it walks each `router.METHOD('/path', …)` in `src/gds/routes/` + `modules/*/routes/`, reads the `// rank:` comment for auth, and calls `extractBody()` — which finds the handler's `validateOrRespond(req, res, {schema})` / `validate(req.body, {schema})` call and pulls the schema's top-level **field names**. Measured on the live surface: **212 endpoints; 76 write ops carry a requestBody, 24 do not; `components.schemas` is empty.** So the spec is real and code-derived, but **shallow** — field names, not types/required/enums.
+
+The crucial observation: the per-route **`validate()` schema object is already structured data** (`_helpers.js` — each field rule carries `type`, `required`, `maxLength`, `minLength`, `min`/`max`, `enum`, `itemsType`, `maxItems`). It already drives runtime validation. It is *right there in the code*, richer than what the spec currently emits.
+
+## Decision
+
+**Stay code-first. The per-route `validate()` schema object is the single structured source of truth**; the spec, runtime validation, and the typed client are all *derived* from it — none is hand-authored.
+
+1. **Enrich the generator, don't invert the flow.** Extend `gen-api-docs.js` so `extractBody()` emits the FULL rule set (types, `required`, `enum`, length/range caps) from the `validate()` schema into typed OpenAPI request schemas (and named `components.schemas`), instead of only field names. This closes the 24 undocumented bodies and upgrades the 76 shallow ones to typed schemas — for free, from data that already exists.
+2. **One schema, three consumers.** That same `validate()` schema object:
+   - **generates** the OpenAPI request schema (this ADR's enrichment),
+   - **enforces** the request at runtime (it already does — R11 hardens it to reject unknown fields + cover query params),
+   - **types** the generated client (R08, emitted from the enriched spec).
+   So "single source of truth" is achieved *within* code-first — the code IS the schema, and everything downstream is generated. No drift, because there is only one authored artifact.
+3. **Generate the client from the spec (R08), don't hand-write it.** Once the spec carries typed schemas, a generator (a small in-house emitter, or `openapi-typescript`-class tooling kept to a dev-dependency — cheapest-viable, ADR §4 cost DNA) produces the typed client. The client is a build artifact, never edited by hand.
+
+## Why not schema-first
+
+Schema-first (author OpenAPI/JSON-Schema, generate the route layer + validators + client from it) would mean **rewriting the entire mature 212-endpoint route layer** to be schema-driven, replacing hand-written Express handlers with a schema-bound framework. That is an enormous, high-risk rewrite that throws away a working generator (ADR 0109) to buy a "single source" we can get far more cheaply by treating the existing in-code schema as the source. The AI-first build model (many small claimed tasks against a live API) strongly favours the incremental, low-blast-radius path.
+
+## Refinement of R08–R12 (the spike's sub-task output)
+
+- **R08 (typed client, [#1995](https://builders.example.com#/task/1995)):** (a) enrich `gen-api-docs.js` to emit typed request/response schemas + `components.schemas` from the `validate()` rules; (b) generate a typed client from the enriched spec; (c) publish as an internal package first.
+- **R09 (migrate callers, [#1996](https://builders.example.com#/task/1996)):** move the CLI (`cli-lib.apiCall`), the devbox app, and the web UIs onto the client; delete the duplicates. **This is also where the R04 fallout is repaired** — callers that read `data.error` as a string move to the client's typed envelope handling (`error.code`).
+- **R10 (external on-ramp, [#1997](https://builders.example.com#/task/1997)):** document token acquisition + a runnable hello-world against the published client.
+- **R11 (validation, [#1998](https://builders.example.com#/task/1998)):** harden `validate()` to reject unknown/typo'd fields and cover query params, driven by the same per-route schema the spec advertises; failures return the ADR-0116 envelope (`validation_failed` + `details`).
+- **R12 (build check, [#1999](https://builders.example.com#/task/1999)):** a fitness check failing the build when a write route has no spec-bound `validate()` schema (locks the 100% coverage).
+
+## Consequences
+
+- The SDK + validation work becomes incremental enrichment of an existing generator, not a rewrite.
+- The `validate()` schema gains a second payoff (it types the spec + client), which incentivises writing it — reinforcing R11/R12's coverage goal.
+- The spec stays honest by construction (generated at ship, ADR 0109), so the client + docs can never drift from the routes.
+
+## Rejected
+
+- **Schema-first** — full route-layer rewrite; disproportionate to the goal.
+- **Hand-maintained OpenAPI** — drifts from code (ADR 0109 already rejected this).
+- **Swapping to a schema-native framework (Fastify/JSON-Schema, tRPC)** — far too invasive for a live 212-endpoint surface; a framework migration, not an API-hardening task.

package/docs/adr/0119-api-pagination-contract.md

@@ -0,0 +1,34 @@
+# ADR 0119 — API pagination contract
+
+**Date:** 2026-07-04
+**Status:** Accepted (contract; R13 of goal 36).
+**Context:** [task 2000](https://builders.example.com#/task/2000) (BONGOS-V1, goal 36, criterion `api-pagination`). The contract; the sweep that adopts it across every list endpoint + caps the currently-unbounded public lists is R14 ([task 2001](https://builders.example.com#/task/2001)).
+
+## Problem
+
+Three pagination styles coexist across the API: `limit`-only, `limit`+`offset`, and none. Some public lists (leaderboard, blockers, versions) return **everything** — an unbounded result set that grows with the project and is a cost/DoS amplification target on the unauthenticated `/public/*` surface. A caller cannot page any two endpoints the same way, and cannot assume a list is bounded.
+
+## Decision
+
+**One convention: `?limit=&offset=` (limit/offset), served through one shared helper.**
+
+- **`limit`** — positive integer; default **50**, hard cap **200** (`PAGINATION.DEFAULT_LIMIT` / `MAX_LIMIT`). A value over the cap is clamped to the cap, so **no list can return an unbounded set**.
+- **`offset`** — non-negative integer; default **0**.
+- **Clamp, never reject.** A bad/absent/oversized value is coerced to a sane default (a list read stays forgiving — a typo'd `limit` returns the first page, not a 400). This is deliberately looser than write-body validation (R11), which rejects.
+- **Shared helper** — `parsePagination(req, { defaultLimit, maxLimit })` in `src/gds/routes/_helpers.js` returns `{ limit, offset }`. Per-endpoint caps are expressible via `maxLimit` (e.g. a heavy aggregate can cap lower).
+- **Response convention** — a paginated list returns `{ items: [...], page: { limit, offset, total? } }`; `pageMeta(limit, offset, total?)` builds the `page` block. `total` is optional (some lists can't cheaply count); when present a caller derives "more pages" via `offset + items.length < total`.
+
+**Why limit/offset, not cursor.** Limit/offset is the style already in use (the `?limit=`/`?offset=` reads today), needs no opaque-token or stable-sort infrastructure, and is trivial for an external caller or a `curl` to construct. Cursor pagination is stronger under high write-churn (no skipped/duplicated rows across pages), but this API's lists are modest and mostly append/status-updated; the cursor machinery is not worth its cost here. If a specific hot, churning list ever needs it, cursor can be added for that endpoint without changing this default.
+
+## Consequences
+
+- Adopting the helper (R14) makes every list page identically and caps the unbounded public lists (leaderboard/blockers/versions) — closing the cost/DoS surface.
+- **Opt-in + non-breaking today:** adding the helper + `pageMeta` changes no response until a route calls them. R14 does the adoption; the currently-unbounded lists gain a default page (a behaviour change scoped to R14, announced there).
+- The OpenAPI spec (R08 enrichment) advertises `limit`/`offset` query params + the `page` response block as the standard, so the generated client + docs teach one paging model.
+
+## Rejected
+
+- **Cursor/keyset pagination as the default** — more robust under churn but needs opaque cursors + a stable sort key per endpoint; disproportionate for these list sizes. Left as a per-endpoint escape hatch.
+- **Page-number pagination (`?page=&per_page=`)** — same expressiveness as offset but an extra mental step (page→offset) and awkward when the page size changes mid-scroll.
+- **Leaving lists unbounded** — the status quo; the exact cost/DoS problem the criterion exists to close.
+- **Rejecting a bad `limit` with a 400** — a list read should be forgiving; clamping is friendlier and keeps a typo from breaking a dashboard. (Write validation, R11, is the strict counterpart.)

package/docs/adr/0120-pay-on-land-and-builder-owned-rebase-gate.md

@@ -0,0 +1,108 @@
+# ADR 0120 — Pay drachmae on land (not on confirm) + a builder-owned rebase gate
+
+**Date:** 2026-07-04
+**Status:** Accepted
+**Discipline:** engineer (GDS / economy + lifecycle)
+**Task:** [#2035](https://example.com/builders#/task/2035) (BONGOS-V1)
+
+## Context — the problem
+
+The per-task drachmae reward is awarded in **`confirmTask`** (`modules/lifecycle/db.js`,
+`reward.insertMultipliedConfirmCredit`, `credit_log.reason = 'task.confirmed'`) — at the
+`completed → confirmed` transition. Confirmed means *verified + credited*, but the code is
+**not yet on `main`**: the merge to `main` + deploy is the later `confirmed → shipped`
+transition, run by the auto-lander / `publish-reconciler`.
+
+So a builder is paid the moment they declare done and pass verification — **before their
+code lands.** When the branch then can't merge (stale after a big codebase change, a real
+conflict, or never pushed at all), the task strands at `confirmed` indefinitely with **no
+consequence to the builder**: they already have the drachmae, and nothing stops them
+claiming new work while the stranded branch rots.
+
+This is not hypothetical. On 2026-07-04 the confirmed queue held ~17 tasks across three
+builders — several never pushed to the remote at all (the commits lived only on the
+builder's machine), one 154 commits behind `main` across the `src/gds → src/bongos`
+rename. Only the original builder can rebase their own stranded branch; but the incentive
+structure gave them no reason to, and no one else *can*. The reward was decoupled from the
+outcome we actually want (landed code).
+
+## Decision
+
+Re-couple reward and queue-access to **landed code**, in four parts.
+
+1. **Pay on land, not on confirm.** Move BOTH reward writes from the `confirmed`
+   transition to the `shipped` (merged-to-`main`) transition:
+   - the per-task credit (`insertMultipliedConfirmCredit` + the idea-promotion bonus), and
+   - the cost-plus session-token reward ([ADR 0054](<redacted>.md)).
+
+   The award becomes idempotent on ship (`credit_log.reason = 'task.shipped'`, guarded by a
+   uniqueness check per task, mirroring today's confirm-time guard). **The happy path barely
+   changes:** a clean PR auto-merges within a minute or two of confirm, so the credit lands
+   almost immediately. The teeth only bite when a task strands — no landed code, no drachmae.
+
+2. **A stalled land becomes the builder's own chore (`needs_rebase`).** The
+   `publish-reconciler` already detects why a confirmed task won't land — `merge_conflict`,
+   a failing required check against current `main`, or no pushed branch. After the normal
+   auto-land grace (the reconciler's existing retries + the [ADR 0082](<redacted>.md)
+   generated-file self-heal) is exhausted, it flags the task `needs_rebase = true`, attributed
+   to the **claim holder** (the builder who did the work — the same attribution rule as
+   `confirmTask`, task 661). This is a signal, not a status change: the task stays `confirmed`
+   (its work is done), it is simply marked as awaiting *its builder's* rebase.
+
+3. **A `needs_rebase` task blocks that builder's NEW claims — not their existing ones.**
+   `claimTask` / `POST /claims` gains a precondition: refuse a **new** claim
+   (`409 { error: 'REBASE_REQUIRED' }`, naming the offending task(s)) when the builder has
+   any `needs_rebase` task. Their already-active claims still resolve/ship normally — we
+   don't freeze in-flight work, we only stop them taking on *more* while a landing chore is
+   outstanding. Since the reward is now contingent on landing (part 1), the builder is
+   motivated to clear it; since it gates their queue, they can't walk away from it.
+
+4. **One-time clawback + re-gate for the existing confirmed backlog.** A migration reverses
+   the `task.confirmed` credit deltas for every task currently at `status = 'confirmed'`
+   (a compensating negative `credit_log` row per task, `reason = 'task.confirmed_reversal'`,
+   so the `builders.total_credits` trigger rolls it back; achievements already unlocked are
+   left intact — reversing gamification is punitive and messy) and sets `needs_rebase = true`
+   on those tasks. This applies the new incentive to the work that stranded under the old
+   rule, rather than grandfathering it. It hits every affected builder, the owner included.
+
+Together: **a builder's pay AND their ability to pick up new work both hinge on their code
+being on `main`** — and the rebase after a big codebase change falls on the one person who
+can do it.
+
+## Consequences
+
+- **Good behavior is unaffected.** Clean work still auto-lands in minutes and pays out then;
+  most builders never see `needs_rebase` or the gate.
+- **Stranding now has teeth.** No landed code → no drachmae, and a stalled land blocks new
+  claims until the builder rebases (or releases the task, forfeiting its reward).
+- **The credit ledger tells the truth.** `credit_log` credits now correspond to code that is
+  actually on `main`, not to verified-but-unlanded branches.
+- **Retroactive sting.** The clawback reverses already-shown drachmae for currently-stranded
+  tasks. This is intentional (it creates the pressure) and is applied uniformly, but it will
+  feel punitive to builders who were paid under the old rule. The reversal is fully re-earnable:
+  land the task and the `task.shipped` credit books.
+- **A genuinely un-rebaseable task must have an exit.** A builder blocked by a task they
+  truly cannot land can `release` it (freeing it, forfeiting the reward) to unblock their
+  queue — so no one is ever permanently stuck.
+- **New surfaces to keep honest.** `needs_rebase` is a new lifecycle signal the reconciler
+  writes and the claim gate + hall/CLI read; the reward-timing move touches the economy
+  `reward` port and the sessions reward path. All are covered by the seeded tasks' tests.
+
+## Alternatives considered
+
+- **Keep paying at confirm, add only the gate.** Rejected: the reward is the strongest lever;
+  leaving it at confirm means a stranded task still paid out, so the builder's only cost is a
+  queue block they can dodge by releasing — weak alignment.
+- **Soft gate (warn, don't block).** Rejected per the owner's call: a warning is ignorable and
+  stranded work kept accumulating exactly because nothing enforced it.
+- **Grandfather the existing confirmed backlog.** Rejected per the owner's call: it would leave
+  the current stranded tasks paid-and-unblocked, precisely the state this ADR exists to end.
+- **Only per-task credit waits for land; session reward stays at confirm.** Rejected per the
+  owner's call in favor of fullest alignment — nothing pays until the code is on `main`.
+
+## Implementation
+
+Seeded as tasks under this ADR (dependencies noted): pay-on-land (economy + lifecycle) →
+`needs_rebase` state + reconciler flag (lifecycle + migration) → claim gate (lifecycle/claims)
+→ clawback migration (depends on pay-on-land being live) → hall + `/builder-start` surfacing →
+tests. See the [#2035](https://example.com/builders#/task/2035) dependency graph.

package/docs/adr/0121-greenfield-vs-brownfield-onboarding-adopt-existing-repo.md

@@ -0,0 +1,97 @@
+# ADR 0121 — Greenfield vs. brownfield onboarding: scope `bongos init --adopt` (adopt an existing repo)
+
+- **Status:** Accepted (the split + the adopt-mode requirements are decided; the build is task-pending — see §Consequences for the seeded breakdown). **No adopt-mode code ships in this ADR — it is scope-only.**
+- **Date:** 2026-07-04
+- **Track:** internal (a portable Cloud Bongos platform capability)
+- **Task:** [#1986](https://example.com/builders#/task/1986) (BONGOS-V1, goal 35 — *Project creation flow*, the `adopt-existing-repo` criterion) — "SCOPE what an adopt mode must do; deliver an ADR + a task breakdown. Do NOT build adopt-mode here."
+- **Deciders:** Lars (Archon), Claude
+- **Builds on:** [ADR 0108](<redacted>.md) (configurable-root / core-as-npm-dep — the "layer, don't clone" substrate), [ADR 0111](<redacted>.md) (the `provisioning` module + the greenfield `bongos init` → provisioning-request wiring), [ADR 0062](<redacted>.md) (core↔host instance model), [ADR 0100](<redacted>.md) (two-repo instance model), [ADR 0105](<redacted>.md) (instance seeds out of core migrations), [ADR 0016](<redacted>.md) (server-enforced trust boundary), [ADR 0083](<redacted>.md) + [ADR 0108](<redacted>.md) §5 (module system + cross-repo migration namespacing).
+- **Raised while** abandoning task 1689 (2026-07-04): the standalone two-repo model is already proven by Emersonian Circles (task 1917), so the missing piece is not *"can core run standalone"* but *"how does an owner who **already has a repo** adopt it."*
+
+---
+
+## Context
+
+Goal 35 ("Project creation flow") has two done-when criteria:
+
+- **`project-creation-flow`** (greenfield) — a new owner goes zero-to-live on a fresh, empty project.
+- **`adopt-existing-repo`** (brownfield) — an owner with an *existing* repository (app code, git history, a backlog) brings Cloud Bongos onto it.
+
+**Today the flow is greenfield-only.** `scripts/gds/init.js`:
+
+- opens with *"Let's stand up a new Cloud Bongos instance."* (`init.js:325`) — the mental model is a blank slate;
+- **refuses to run where `config/branding.json` already exists** unless `--force`, and `--force` *overwrites* (`init.js:408–409`) — there is no "merge onto what's here" path;
+- **seeds a synthetic first version** — default id `V1`, name `"V1 — Prove the loop"` (`init.js:341–342`) + starter/kickoff tasks — rather than reflecting the repo's real current version, goal, or backlog;
+- **inspects nothing** about the existing tree: not its stack, not its layout, not its CI, not its migration numbering.
+
+So an owner with a real repo has only two bad options today: run `init` in a throwaway directory and hand-merge, or `--force` and clobber their config. Neither is a guided flow, and neither preserves their real state. That is the gap `adopt-existing-repo` names — and the reason this ADR complements the greenfield criterion rather than replacing it.
+
+---
+
+## Decision
+
+### 1. Two explicit onboarding modes over one canonical step sequence
+
+Goal 35's canonical runbook (task [#1981](https://example.com/builders#/task/1981)) is the source of truth for the *sequence*: name+address → init → scaffold → provision → OAuth app + verified secret + first sign-in → verify → brand. The runbook branches at **exactly one leg — scaffold** — into:
+
+- **greenfield** (`bongos init`, today's behavior): scaffold a fresh standalone repo + a synthetic first version.
+- **brownfield** (`bongos init --adopt`): **layer** onto the existing tree and reflect its real state.
+
+Every other leg (provision, OAuth, verify, brand) is **identical** across the two modes. `--adopt` is a mode of the *same* `init`, not a separate command — so the CLI form (task [#1982](https://example.com/builders#/task/1982)) and the hall wizard form (task [#1983](https://example.com/builders#/task/1983)) inherit it for free.
+
+### 2. LAYER, never scaffold or clobber (the core requirement)
+
+In `--adopt`, `init`:
+
+- adds the pinned `@cloudbongos/core` dependency + `config/` overrides + `.claude/` **additively** onto the existing tree;
+- for any file that already exists (an owner's `package.json`, a pre-existing `.claude/`, a CI workflow), it **merges or leaves-and-reports** — it **never overwrites**. The `--force`-overwrites code path is explicitly *not* reused;
+- writes only the *lean* `config/branding.json` overrides ADR 0108 defines (the rest resolves from `*.neutral.json`), so the owner's existing files stay theirs.
+
+### 3. Reflect REAL state, not a synthetic V1
+
+`--adopt`:
+
+- does **not** seed `"V1 — Prove the loop"`; it captures (by interview + detection) the repo's actual current version/milestone and open goal;
+- **imports the existing backlog** into GDS tasks — GitHub issues (via the GitHub auth the flow already establishes), a `TODO`/`ROADMAP`/`BACKLOG.md`, or an interview fallback — so the ledger starts truthful rather than empty.
+
+### 4. DETECT the existing stack + layout
+
+Before writing anything, `--adopt` inspects the tree — language/runtime, package manager, test + CI setup, directory layout — so the enabled modules, the generated repo-map, and the **core↔host fitness boundary** (ADR 0062 §1) fit what is already there instead of assuming the reference layout.
+
+### 5. A CONFLICT PRE-FLIGHT report — the owner sees the blast radius before committing
+
+`--adopt --dry-run` (the default first pass) produces a report covering at least:
+
+- **migration namespace** — do the repo's existing migration numbers collide with core's namespace (ADR 0108 §5)?
+- **the fitness boundary** — would adopting flag existing imports as core↔host violations (ADR 0062 §1)?
+- **protected-path / rank gates** — which incoming files land on protected paths (ADR 0043)?
+- **existing CI** — does core's expected `unit`/gate check collide with the repo's own workflows?
+
+**Nothing is written until the owner accepts the pre-flight.** This accept-gate is the safety the greenfield path does not need (a blank slate cannot be clobbered).
+
+### 6. What `--adopt` does NOT change
+
+The trust boundary (ADR 0016), the provisioning path (ADR 0111 — an adopted instance provisions exactly like a greenfield one), and the standalone composition model (ADR 0108) are all unchanged. Adopt is a *front door* onto the same substrate, not a new substrate.
+
+---
+
+## Alternatives considered
+
+- **Extend `--force` to "merge."** Rejected — `--force` means *overwrite*; overloading it to sometimes-merge is a footgun on exactly the repos where a mistake is expensive. A distinct `--adopt` mode with a dry-run pre-flight is legible.
+- **A separate `bongos adopt` command.** Rejected — it would duplicate the init/provision/verify legs and drift from them. Adopt is one branch of `init`'s *scaffold* leg; the CLI + hall forms then get it for free.
+- **Auto-import everything (issues + TODOs + CI) with no pre-flight.** Rejected — brownfield repos are exactly where silent clobbering hurts most; the pre-flight + accept step is mandatory, not optional.
+- **Build adopt-mode now.** Out of scope by the task's own charter — 1986 is scope-only. This ADR + the seeded breakdown *is* the deliverable.
+
+---
+
+## Consequences
+
+- **`adopt-existing-repo` gets a concrete, buildable shape** — the criterion is no longer a one-line aspiration; it has a governing decision and a dependency-wired task breakdown.
+- **The greenfield criterion is untouched** — today's `bongos init` *is* the greenfield mode; `--adopt` is purely additive to it.
+- **Sequencing:** the adopt build depends on goal 35's canonical runbook (task 1981) existing, because `--adopt` is a branch of it; the detection + pre-flight pieces are independent and can start first.
+- **Follow-up tasks seeded** under BONGOS-V1 / goal 35, linked to the `adopt-existing-repo` criterion (idempotent seeder `scripts/gds/seed-adopt-tasks.js`, `source_ref = BONGOS-V1-adopt-*`). Seeded as **`backlog`** — the owner schedules the adopt build deliberately; nothing auto-promotes:
+  1. [#2042](https://example.com/builders#/task/2042) **`bongos init --adopt` skeleton + config layering** — add the mode; layer the `@cloudbongos/core` dep + lean `config/` + `.claude/` additively; merge-or-report on every pre-existing file; never overwrite. *(deps: none — the substrate is shipped)*
+  2. [#2043](https://example.com/builders#/task/2043) **Stack + layout detection** — inspect runtime / package-manager / test / CI / layout; feed enabled modules + repo-map + the fitness boundary. *(deps: none)*
+  3. [#2044](https://example.com/builders#/task/2044) **Real-state capture + backlog import** — replace the synthetic V1 with the repo's actual version/goal; import GitHub issues / TODO / roadmap into GDS tasks. *(deps: [#2042](https://example.com/builders#/task/2042))*
+  4. [#2045](https://example.com/builders#/task/2045) **Conflict pre-flight report** — migration-namespace + fitness-boundary + protected-path + CI-collision report, `--dry-run` default, gated behind an accept step. *(deps: [#2042](https://example.com/builders#/task/2042), [#2043](https://example.com/builders#/task/2043))*
+  5. [#2046](https://example.com/builders#/task/2046) **Wire `--adopt` into the canonical runbook + both forms** — the /new-project skill, `bongos onboard`, and the hall wizard offer greenfield-vs-adopt at the scaffold leg. *(deps: [#2042](https://example.com/builders#/task/2042), [#2044](https://example.com/builders#/task/2044), [#2045](https://example.com/builders#/task/2045), and goal-35 runbook task [#1981](https://example.com/builders#/task/1981))*

package/docs/adr/0122-onboarding-diagram-renders-deploy-rendered-off-git.md

@@ -0,0 +1,43 @@
+# ADR 0122 — Onboarding diagram renders: untracked + rendered at deploy from a host-provisioned Chrome
+
+- **Status:** Accepted
+- **Date:** 2026-07-05
+- **Track:** internal
+- **Completes:** [ADR 0110](<redacted>.md) — the diagram half it explicitly **deferred** ("the diagrams need verified headless-Chromium handling"). This ADR records that verified handling and lands the untrack.
+- **Builds on:** [ADR 0094](<redacted>.md) (gitignored artifact rebuilt at deploy), [ADR 0063](<redacted>.md) / [ADR 0062](<redacted>.md) §8 (the nav-doc generators ADR 0110 already migrated)
+- **Task:** [#2027](https://example.com/builders#/task/2027) (consolidated the duplicate [#1928](https://example.com/builders#/task/1928))
+
+## Context
+
+ADR 0110 moved the whole-file generated **navigation docs** (`docs/repo-map.md`, `docs/session-log-index.md`) off the git graph — gitignored, regenerated server-side at deploy — to kill the multi-builder branch-collision class. It **deferred the onboarding diagrams** (`docs/onboarding/diagrams/*.svg` + `*.png`) for one reason: unlike the pure-Node nav generators, rendering a Mermaid `.mmd` needs a **headless Chromium**, and `mermaid-cli` (via puppeteer) **downloads its own Chromium on first run** — a multi-minute network fetch that stalls/no-ops the $14/mo, 2 GB prod droplet. So the renders stayed tracked and committed on every render-capable ship, and kept colliding on parallel branches (the exact cost ADR 0110 set out to remove).
+
+The blocker was never the untrack — it was proving a **reliable, non-downloading render on the actual deploy host**. That could not be verified from a credential-less dev box (puppeteer's browser download is blocked there too), so the work needed a deploy-host session.
+
+## Decision
+
+Apply the ADR 0110 model to the diagram **renders**, with a host-provisioned browser instead of an on-deploy download:
+
+1. **Provision Chrome once on the host.** Install Google Chrome stable (`google-chrome-stable`, `apt` resolves all shared-lib deps on Ubuntu 24.04) on the prod droplet. It is the single persistent browser the render step reuses — no per-deploy download.
+2. **`render-diagrams.sh` prefers an installed browser.** It auto-detects `google-chrome-stable`/`chromium`/… (or honors `PUPPETEER_EXECUTABLE_PATH`), and when it finds one exports `PUPPETEER_SKIP_DOWNLOAD=1` so puppeteer **never** attempts the droplet-stalling fetch. With nothing installed (a dev laptop) it falls back to puppeteer's own download, unchanged. It passes a committed `puppeteer-config.json` carrying `--no-sandbox` (required for headless Chrome as the non-root deploy user on Ubuntu 24.04, whose restricted unprivileged user namespaces break Chrome's own sandbox), and pins `mermaid-cli@11`.
+3. **Render at deploy + at box-fetch.** `scripts/deploy/deploy-prod.sh` runs `render-diagrams.sh` (timeout-guarded, **LOUD `::ERROR::` on failure**, best-effort — never fails a deploy) right beside the ADR 0110 nav-doc generators; `infra/box-source-fetch.sh` does the same **guarded on a browser being present** (a box without Chrome skips instantly rather than stalling on a download — a box does not serve the diagrams page).
+4. **Untrack only the renders.** `git rm --cached` + `.gitignore` for `docs/onboarding/diagrams/*.svg` + `*.png`. The **`.mmd` sources + `assertions.json` stay tracked** — `git reset --hard` restores them and the render regenerates the images from them.
+5. **Ship stops producing/committing renders.** `ship.js`'s diagram regen runs `gen-diagrams.js --no-render` (sources only); the gitignored images never enter its `git add`.
+
+## Why this is safe — and never worse than before
+
+- **No bot commits to `main`; the trust boundary is untouched** (ADR 0016/0043/0055). The renders are written as untracked files on the droplet after `git reset --hard`, exactly like the atlas and the ADR 0110 nav docs.
+- **The backstop is unaffected.** The nightly `diagram-drift` cron reads `assertions.json` (still tracked), not the images — so untracking the renders cannot blind it.
+- **Verified before landing.** Chrome + `mermaid-cli@11` was confirmed rendering all five `.mmd` (svg + png, incl. the ELK-layout `04-architecture`) on the prod droplet using the installed browser with no download — the verification ADR 0110 required.
+
+## Consequences
+
+- The diagram-render branch-collision class is eliminated at the source; render-capable ships drop a bookkeeping commit.
+- **Accepted staleness:** the served images are fresh only *after deploy* (or a box-fetch tick), not at merge — tolerant by nature for a human onboarding page; the LOUD `::ERROR::` is the alarm if a deploy render breaks, and the nightly drift cron is the belt-and-braces.
+- **Operational coupling:** the prod droplet must keep Google Chrome installed. `deploy-prod.sh` is the hand-maintained `~/deploy.sh` mirror ([ADR 0042](<redacted>.md)/[0043](<redacted>.md)), so landing this requires an operator to (a) install Chrome (done) and (b) reinstall the updated `deploy.sh`. If Chrome is ever removed, the render step fails LOUD and the drift cron flags staleness — the page keeps its last-deployed images (no `git reset` wipes an untracked file that was just re-rendered) until the next successful deploy.
+- **Fresh pristine checkout / core package:** a bare `git clone` that never deploys lacks the images (same accepted trade-off ADR 0110 notes for the nav docs). `docs/onboarding/diagrams/` is not in the core publish allowlist, so nothing changes for packaged core.
+
+## Alternatives considered
+
+- **On-deploy `npx mermaid-cli` with its own Chromium download** — rejected: the multi-minute first-run fetch stalls the 2 GB droplet (the original ADR 0110 deferral reason).
+- **Snap `chromium` on Ubuntu 24.04** — rejected: flaky/confined headless behavior on a server; the Chrome `.deb` gives a stable `/usr/bin` path with apt-resolved deps.
+- **Keep the renders tracked, strengthen the ADR 0082 conflict resolver only** — rejected for the same reason ADR 0110 rejected it for the nav docs: it hides the collision rather than removing it, and the cost grows with parallelism.

package/docs/adr/0123-box-idle-sweep-autosave-before-destroy.md

@@ -0,0 +1,36 @@
+# ADR 0123 — Idle-swept dev boxes lose uncommitted work: an on-box autosave-push, not a VM snapshot
+
+- **Status:** Accepted (the approach + rejected alternatives are decided; the cron script + operator credential wiring are task-pending — see §Consequences for the seeded follow-up). **No autosave code ships in this ADR — it is a SPIKE.**
+- **Date:** 2026-07-05
+- **Track:** internal (dev-box lifecycle)
+- **Task:** [#837](https://example.com/builders#/task/837) — "SPIKE: don't lose uncommitted work when a dev box is reclaimed (idle sweep deprovisions, no snapshot)."
+- **Builds on:** [ADR 0031](<redacted>.md) (cloud dev environments), [ADR 0071](<redacted>.md) (confirm-before-destroyed + drift reconcile — the closest prior art; hardens droplet *truthfulness*, not data preservation), [ADR 0043](<redacted>.md) (git/SSH trust boundary — relevant because the fix widens a box credential's scope).
+
+## Problem
+
+`scripts/gds/box.js` `cmdSweepIdle()` → `deprovisionOne()` deletes the droplet outright once `modules/dev-box/boxes.js` `selectIdleBoxes()` decides a box is idle (no heartbeat, no `claude_active`, past `BOX_IDLE_MINUTES`, default 10). **Nothing on this path looks at git status.** Park/snapshot was deliberately removed from the automated idle path (box.js:842-845 — snapshot storage cost with no benefit, since boxes are meant to be ephemeral). So today: idle sweep = hard droplet delete, and any uncommitted tracked work on `/workspace` is gone permanently, with no confirmation step and no way to recover it.
+
+The heartbeat (`infra/box-heartbeat.sh`) that feeds the idle clock is a pure presence signal (SSH/ttyd connection + CPU load) — it has no concept of a dirty working tree. A builder who steps away mid-edit with real uncommitted changes and no active connection gets swept exactly like a builder who is genuinely done.
+
+No existing ADR, blocker, or backlog entry addresses this — ADR 0071 explicitly treats the droplet as disposable and is scoped to infra-state correctness, not data preservation. `sweep-dormant` (parked boxes) is not the acute case: a parked box already has a snapshot from the manual `park` path, so its reclaim destroys a *backup copy*, not live work. The acute path is specifically **active → destroyed** via the idle sweep.
+
+## Decision
+
+**<redacted> from the box, not a VM/droplet snapshot.** Add an on-box cron (sibling to `box-heartbeat.sh`, similar ~5-minute cadence) that, when `/workspace`'s git tree is dirty, commits the tracked changes and pushes them to the box's own claim branch (the `claude/<name>` branch a claimed task already works in per ADR 0097). This bounds data loss to "since the last autosave tick" (~5 min) instead of "since session start," using infrastructure that already exists for a different purpose:
+
+- **Auth pattern is proven.** `infra/box-source-fetch.sh` already does one-shot-credentialed-push semantics for *fetch*: `git remote set-url origin "$AUTH_URL"` → git op → `git remote set-url origin "$REPO_URL"` (credential never persisted in `.git/config`). The autosave cron reuses the identical pattern for a *push*.
+- **Credential scope must widen.** `GET /box/source-access` (`modules/dev-box/routes/box.js:422`) mints a scope-appropriate token via `box-credential.js`, but the token today is only ever used to clone/fetch. Whether the operator-configured `BOX_SOURCE_FULL_TOKEN` already carries push scope is unknown from code — it's an operator-supplied env value (`box-credential.js:46-65`). **This is the one real open dependency**: either confirm the existing token already has push scope, or mint a second, push-scoped credential. Because this is a trust-boundary-relevant change (a box gains the ability to write to `origin`, not just read it), the follow-up task must treat it with the same care as ADR 0043 — scoped to the box's own `claude/<name>` branch only (never `main`), audited via the existing `source_grant`/new `autosave_push` event on `box_events`, and gated to the same rank floor that already gates source access.
+- **Explicit non-goals.** Gitignored/untracked local-only state (`.env.local`, other per-worktree secrets) is NOT covered — those are meant to be regenerated via `/builder-setup`/`/builder-key`, not preserved. This fix is scoped to tracked-file work loss only.
+
+## Alternatives considered
+
+- **Reintroduce snapshot-before-destroy on the idle path (bring back `park`'s snapshot).** Rejected: this is the exact cost (~$0.30/mo per idle box × fleet size, plus snapshot-restore latency on next wake) the team deliberately removed from the automated path. It also doesn't actually solve the problem faster than a commit — a snapshot still requires the operator (or the builder) to notice and restore it; a pushed branch is immediately visible and diffable from any machine.
+- **Control-plane git-status check before sweep (abort deprovision if `/workspace` is dirty).** Rejected: requires giving the control plane a NEW capability (SSH/exec into the box to read git state) that doesn't exist today, and a builder who simply forgets to commit for days would pin their box active-forever, defeating the idle sweep's entire cost-saving purpose. An autosave-push needs no new control-plane capability — it's entirely box-side, symmetric with the existing heartbeat/source-fetch crons.
+- **Rely on the manual `/builder-end` git-dirty check alone.** Rejected as the sole mitigation: it already exists (`builder-end` refuses to tear down a dirty worktree) but only fires when a builder explicitly signs off. It has zero relationship to the automatic idle sweep, which is precisely the unguarded path this spike is about.
+
+## Consequences
+
+- Bounds — doesn't eliminate — the loss window to the autosave interval; a crash or sweep in the seconds between an edit and the next tick can still lose that slice. Full elimination would need a snapshot (rejected above) or a live pre-sweep check (rejected above); this is the accepted trade-off.
+- Autosaved commits land on the SAME `claude/<name>` claim branch (not a separate `autosave/*` branch), so they show up as ordinary WIP commits a builder squashes/amends before shipping — no new branch-namespace or `/builder-ship` special-casing needed.
+- Needs an operator credential decision (push-scope token) before the cron can be built — flagged as the seeded follow-up task's first step, not assumed solved here.
+- No code ships from this ADR. Seeded follow-up: implement `infra/box-autosave.sh` (dirty-check + one-shot-credentialed commit+push, mirroring `box-source-fetch.sh`'s credential-scrub pattern) + the operator-side push-credential decision + wiring it into cloud-init alongside the existing heartbeat cron.

package/docs/adr/0124-typed-api-response-bodies.md

@@ -0,0 +1,37 @@
+# ADR 0124 — Typed API response bodies (infer the success shape from `res.json`)
+
+**Date:** 2026-07-05
+**Status:** Accepted (follow-up to [ADR 0118](<redacted>.md); goal 36 `api-client-sdk`).
+**Context:** [task 2061](https://builders.example.com#/task/2061) (BONGOS-V1), promoted from idea 519. [ADR 0118](<redacted>.md) / task 2050 typed every **request** body field-level from each route's `validate()` schema. Success **responses** stayed the `ApiResponse` (`= any`) alias: routes declare no response schema, so the generator had nothing to type them from — a caller got zero autocomplete or safety on what a call returns.
+
+## Problem
+
+The generated client (`clients/bongos-client`) is the one true way to call the API (goal 36). Its request bodies are typed, but every method returned `Promise<any>` (aliased `ApiResponse`). So `const { task } = await api.tasks.getTasks()` had no idea `task` was wrong (the field is `tasks`), and a paginated call's `page` block was untyped. The "typed client" was only half typed.
+
+## Decision
+
+**Infer the success shape statically from each route's inline `res.json({ … })` object literal** — do not add a parallel per-route response-schema declaration.
+
+- `gen-api-docs.js` scans a route's handler window for success (`2xx`) `res.json(…)` / `res.status(2xx).json(…)` calls (reusing the `captureBalanced` / `splitTopLevel` / `splitKeyValue` machinery the request extractor already uses — it **never executes** a route). The top-level keys of the object literal become a `<OperationId>Response` component in `components.schemas`, attached to the `200` response's `content`.
+- **Only keys are provable.** A property's value is usually a variable, so it types as `unknown` — the *shape* (which keys exist) is the win. Two values type with confidence: a **boolean literal** (`ok: true`), and the ADR-0119 `pageMeta(…)` `page` block → a shared **`PageInfo`** component.
+- `gen-api-client.js` types the method return as `Promise<<OperationId>Response>`; the component renders as a TS interface automatically (same path as request schemas). A route with no provable shape keeps `Promise<ApiResponse>`.
+
+**Degrade-gracefully contract — never emit a shape we cannot prove.** A route whose success body is a **bare value** (`res.json(row)`), contains a **top-level spread** (`{ …rest }`), an **empty** `{}`, or a **computed/quoted key** keeps the `ApiResponse` alias. We only ever *narrow* `any`; we never assert a wrong or partial-looking-complete shape. Branches within one handler are merged: a key present in every branch is required, others optional; a value schema is kept only where all branches agree.
+
+## Why not a per-route `responseSchema` export (idea 519 option a)
+
+ADR 0118 is **code-first**: the contract is read from what the route already does, not from a second declaration that can drift. The `res.json({ … })` literal *is* the response shape — adding a `responseSchema` export beside it would (a) duplicate that truth, (b) require touching 200+ route files for a one-time win, and (c) reintroduce exactly the drift the generator exists to kill. Reading the literal keeps a single source of truth and covers the whole surface for free.
+
+## Consequences
+
+- **162 of 221 endpoints** now return a concrete `<…>Response` interface; the remaining ~59 (bare values, spreads) safely stay `ApiResponse`. A representative, majority slice of the API is now typed end-to-end.
+- **No runtime change.** Only `docs/api/openapi.json` and `clients/bongos-client/index.d.ts` change — the client's runtime JS (`index.mjs/.cjs/.global.js`) is untouched (return types are a `.d.ts`-only concern), so the devbox-vendored CJS stays byte-identical.
+- Correctness is bounded: a value typed `unknown` forces a cast at the call site (honest — we don't know it); a missing route type is `any` (no worse than before). The generator can never over-claim a shape.
+- Enforced by both generators' `--check` gate + `tests/api_docs.mjs` (the pure extractors + spec facts) and `tests/api_client.mjs` (the emitted `.d.ts`).
+
+## Rejected
+
+- **Per-route `responseSchema` export / `res.json` hint comment** — drift + churn; see above.
+- **Executing routes / a running server to observe real responses** — breaks the generator's zero-execution, DB-free, deterministic contract (ADR 0118).
+- **Typing every value by tracing the variable** — would need real data-flow analysis; brittle and far past the static line/regex extractor's remit. Keys + the two safe value cases capture the value at a fraction of the risk.
+- **`additionalProperties: false` on response components** — omitted; since we degrade on spreads, the inferred shape is trusted, but leaving responses open avoids a false compile error if a handler branch we didn't parse adds a key.

package/docs/adr/0125-control-plane-scaffolds-standalone-instance-repo.md

@@ -0,0 +1,36 @@
+# ADR 0125 — The control plane scaffolds + pushes a standalone instance's repo
+
+**Date:** 2026-07-05
+**Status:** Accepted (implements goal 35's `project-creation-flow` criterion; builds on [ADR 0108](<redacted>.md) + [ADR 0111](<redacted>.md)).
+**Context:** [task 2055](https://builders.example.com#/task/2055) (BONGOS-V1) — greenfield onboarding gap 3/4, found in the 2026-07-05 end-to-end standup attempt (task 2052).
+
+## Problem
+
+The greenfield "one guided flow" (`bongos init` → provision → OAuth → verify) had a **manual dead-end** between init and provision. `scripts/gds/provision.js` assumed a standalone instance's repo was **already cloned** at `/srv/cloudbongos/<slug>` and **threw** ("standalone instance repo not found … clone … first") otherwise. So an owner who requested an instance (`POST /api/bongos/provisioning/instances`) had to SSH the control plane and hand-clone + hand-scaffold the repo — there was no automation to turn an *empty* GitHub repo into an *installable* Cloud Bongos instance.
+
+## Decision
+
+**The control-plane provisioning runner scaffolds the instance's own repo itself, then commits + pushes it** — replacing the throw with a `scaffoldStandaloneRepo()` leg that runs before the existing code-sync/db/service steps:
+
+1. **clone** the (empty) `target_ref` → `/srv/cloudbongos/<slug>`, forcing the initial branch to `main` (an empty clone has an unborn HEAD).
+2. **build** the installable `@cloudbongos/core` tarball from the control-plane checkout (`package-core.js`).
+3. **materialize** `config/` + `.claude/` + a `file:`-pinned `package.json` + `package-lock.json` via `bongos init --vendor-core` (the [task 2053](https://builders.example.com#/task/2053) primitive), `--no-seed` (the instance's own DB is seeded by `migrate`, not here).
+4. **commit + push** to the instance's `main` (with a `node_modules`-excluding `.gitignore`; the vendored tarball + lockfile stay tracked so `npm ci` resolves the pinned core).
+
+It is **idempotent** (skips once the repo carries a `package.json`) and **dry-run-safe** (every mutation goes through the injected `exec`/`writeFile`).
+
+**Git transport = the existing SSH deploy alias.** The clone/push use `git@<alias>:<owner>/<repo>.git` (default alias `github-deploy`, overridable via `PROVISION_GIT_SSH_ALIAS`) — the **same** transport the control-plane checkout already uses for the platform repo. No secret is interpolated into a command (SSH-key auth), so nothing leaks into journald.
+
+**Operational prerequisite (the one manual grant):** the control plane's deploy public key (`~/.ssh/github_deploy.pub`) must have **write** access to each instance repo. GitHub deploy keys are per-repo, so standing up a new instance requires the owner to add that key (write) to the new repo — a one-time browser step alongside "create the empty repo," mirroring how the platform repo's deploy key is registered.
+
+## Consequences
+
+- **`deploy-instance.sh` already existed** at `scripts/deploy/deploy-instance.sh` (added by [ADR 0108](<redacted>.md) §4 / task 1884 — the task-2055 description predated it). It is the *ongoing* consumer deploy (git pull → `npm ci` → three-root migrate → restart), installed as an instance's own `~/deploy.sh`; the provisioner does the *first-time* standup inline. No duplicate at `infra/` was created.
+- A fresh empty GitHub repo now goes from "requested" to "installable + bootable" with **no manual clone/scaffold** — closing the init→provision dead-end.
+- The control plane gains a new responsibility (pushing to owner repos). Bounded by the per-repo deploy-key grant above.
+
+## Rejected alternatives
+
+- **A control-plane GitHub PAT / App token over HTTPS.** More scalable than per-repo deploy keys, but (a) embedding a token in a `git` URL risks leaking it into journald / process args, requiring a credential-helper dance, and (b) it introduces a new broad-scoped secret class on the control plane. Deferred — the SSH-alias reuse ships zero new secret machinery. A **GitHub App** (per-repo installation tokens, no long-lived secret) is the scalable end-state and is the natural follow-up when instance count grows.
+- **Keep the "clone it yourself first" throw.** That *is* the manual dead-end this task exists to remove.
+- **Scaffold from a template repo (fork).** Adds a template-repo to maintain + a fork step; `bongos init --vendor-core` already produces the exact tree from the live core, single-source.