@bongos/core 1.17.0

package/docs/api-reference.md

@@ -0,0 +1,437 @@
+<!-- GENERATED by scripts/gds/gen-api-docs.js — do not hand-edit. Run `node scripts/gds/gen-api-docs.js`. -->
+
+# GDS API reference
+
+> **Generated from the live route files** — the route file is authoritative. 224 endpoints across 38 route files.
+> Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
+
+Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
+
+## `access-requests` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/access-requests` | `archon` | — | GET /access-requests?status=pending — Archon queue. |
+| POST | `/api/bongos/access-requests` | `public` | `github_login`, `display_name`, `note` | POST /access-requests — PUBLIC. |
+| PATCH | `/api/bongos/access-requests/:id` | `archon` | `status` | PATCH /access-requests/:id — Archon resolves a request. |
+| GET | `/api/bongos/access-requests/status` | `public` | — | GET /access-requests/status?github_login=X — PUBLIC. |
+
+## `achievements` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/achievements` | `any-builder` | — | All seeded achievements — lets /builders render locked + unlocked side by side. |
+
+## `analytics` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/analytics/builder/:id` | `any-builder` | — | a builder's historical AI dev curve. |
+
+## `audit-log` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/audit-log` | `archon` | — | GET /api/gds/audit-log?limit=&offset=&builder_id=&method= Paginated, newest-first. |
+
+## `auth` (15)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/auth/app-pair/approve` | `any-builder` | `pair_code` | (own identity only) — approving signs the app in AS THE APPROVER. |
+| GET | `/api/bongos/auth/app-pair/info` | `any-builder` | — | read-only: what the approve page shows BEFORE the click (device name/platform for the given code). |
+| POST | `/api/bongos/auth/app-pair/poll` | `public` | `poll_token` | poll with the secret poll_token; the token IS the bearer (mirrors /auth/device/poll, where the device_code is the bearer). |
+| POST | `/api/bongos/auth/app-pair/start` | `public` | `device_name`, `platform` | starts a pairing; returns opaque codes only, no identity. |
+| POST | `/api/bongos/auth/cli-token/issue` | `any-builder` | — | POST /auth/cli-token/issue — V3.R91 / task 401. |
+| POST | `/api/bongos/auth/device/poll` | `public` | `device_code` | auth flow; the device code itself is the bearer. |
+| POST | `/api/bongos/auth/device/start` | `public` | — | /auth/device — CLI flow rank: public — auth flow itself; identity establishment, not authorization. |
+| GET | `/api/bongos/auth/discord/callback` | `any-builder` | — | completes the link to the caller's own identity. |
+| GET | `/api/bongos/auth/discord/start` | `any-builder` | — | /auth/discord — account-linking OAuth (Phase 3 F2, ADR 0033 §2). |
+| POST | `/api/bongos/auth/discord/unlink` | `any-builder` | — | unlink your OWN Discord. |
+| POST | `/api/bongos/auth/logout` | `any-builder` | — | own session, no rank gate (a Xenos can log themselves out). |
+| POST | `/api/bongos/auth/revoke` | `archon` | `session_id` | POST /auth/revoke — V3.R38 / task 259. |
+| POST | `/api/bongos/auth/revoke-all` | `archon` | `builder_id` | POST /auth/revoke-all — V3.R38 / task 259. |
+| GET | `/api/bongos/auth/web/callback` | `public` | — | OAuth callback; the state cookie + code are the bearer. |
+| GET | `/api/bongos/auth/web/start` | `public` | — | /auth/web — browser flow (used by the /builders page). |
+
+## `autonomy` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/autonomy/precheck` | `archon` | — |  |
+
+## `backup` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/backup/status` | `metic+archon` | — | any working builder may check or trigger a backup. |
+| POST | `/api/bongos/backup/trigger` | `metic+archon` | — |  |
+
+## `blockers` (5)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/blockers` | `public` | — | List currently-open blockers + the tasks each is blocking. |
+| POST | `/api/bongos/blockers` | `any-builder` | `title`, `body_md`, `source`, `source_ref` | FILE a blocker (contribution, not resolution). |
+| GET | `/api/bongos/blockers/:id` | `any-builder` | — | single blocker detail read. |
+| POST | `/api/bongos/blockers/:id/link` | `metic+archon` | `task_id` | Link an existing blocker to a task (puts the task in 'blocked' status if it's currently 'backlog' or 'ready'). |
+| POST | `/api/bongos/blockers/:id/resolve` | `metic+archon` | `resolution_note` | Resolve. |
+
+## `box` (17)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/box/authorized-keys` | `any-builder` | — | GET /box/authorized-keys — the box pulls its builder's authorized_keys. |
+| POST | `/api/bongos/box/close` | `any-builder` | — | POST /box/close — the builder manually requests their box be deprovisioned. |
+| GET | `/api/bongos/box/connect` | `public` | — | GET /box/connect — the human/Claude-readable connect walkthrough. |
+| GET | `/api/bongos/box/connect.ps1` | `public` | — | GET /box/connect.ps1 — the Windows (PowerShell) bootstrap script. |
+| GET | `/api/bongos/box/connect.sh` | `public` | — | GET /box/connect.sh — the macOS/Linux bootstrap script. |
+| POST | `/api/bongos/box/ensure` | `any-builder` | — | POST /box/ensure — "make my box ready". |
+| POST | `/api/bongos/box/heartbeat` | `any-builder` | `claude_active` | POST /box/heartbeat — the box reports it is alive, resetting the idle clock. |
+| POST | `/api/bongos/box/host-keys` | `any-builder` | `host_keys` | POST /box/host-keys — the box publishes its own PUBLIC SSH host keys (task 1187 / idea 235). |
+| GET | `/api/bongos/box/managed-settings` | `any-builder` | — | GET /box/managed-settings — the caller's Claude Desktop managed-settings.json. |
+| GET | `/api/bongos/box/me` | `any-builder` | — | GET /box/me — the caller's own box. |
+| GET | `/api/bongos/box/source-access` | `any-builder` | — | GET /box/source-access — the box fetches its rank-scoped clone spec + the credential to pull it (ADR 0031 §6, task 600). |
+| GET | `/api/bongos/box/ssh-key` | `any-builder` | — | GET /box/ssh-key — list the caller's registered keys. |
+| POST | `/api/bongos/box/ssh-key` | `any-builder` | `public_key`, `label` | POST /box/ssh-key — register the caller's own public SSH key. |
+| DELETE | `/api/bongos/box/ssh-key/:id` | `any-builder` | — | DELETE /box/ssh-key/:id — remove one of the caller's keys. |
+| GET | `/api/bongos/box/terminal` | `any-builder` | — | GET /box/terminal — the caller reads their box's web-terminal URL + credential (the Chromebook on-ramp, ADR 0038: ttyd behind a Cloudflar… |
+| POST | `/api/bongos/box/terminal` | `any-builder` | `url`, `credential` | POST /box/terminal — the box publishes its current web-terminal URL + the per-box basic-auth credential. |
+| POST | `/api/bongos/box/version` | `any-builder` | `sha`, `committed_at` | POST /box/version — the box reports its /workspace HEAD commit so the server can flag a stale box (idea 332 / task 1316, ADR 0072). |
+
+## `boxes` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/boxes` | `archon` | — | GET /boxes — full roster across all builders. |
+| PATCH | `/api/bongos/boxes/:builderId/block` | `archon` | `blocked`, `reason`, `close_current` | PATCH /boxes/:builderId/block — Archon bars (or un-bars) a builder from OPENING dev boxes (idea 257 / task 1163; migration 104). |
+| POST | `/api/bongos/boxes/:builderId/close` | `archon` | — | POST /boxes/:builderId/close — Archon force-closes ANY builder's box (idea 257 / task 1163). |
+| GET | `/api/bongos/boxes/cost-ledger` | `archon` | — | GET /boxes/cost-ledger — the full per-builder container-cost ledger + totals (task 602). |
+
+## `bug-attachments` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/bug-attachments/:name` | `any-builder` | — | GET /api/bongos/bug-attachments/:name — stream one stored image. |
+
+## `builders` (9)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/builders/:id/active-claims` | `archon` | — | GET /builders/:id/active-claims — V3.R14 (task 238). |
+| PATCH | `/api/bongos/builders/:id/budget` | `archon` | `monthly_budget_usd` | PATCH /builders/:id/budget — set or clear a builder's monthly spend ceiling (V3.R84 task 302, criterion C3). |
+| GET | `/api/bongos/builders/:id/onboarding` | `public` | — | GET /builders/:id/onboarding — V3.R75 (task 294) onboarding checklist read. |
+| GET | `/api/bongos/builders/:id/profile` | `public` | — | GET /builders/:id/profile — the viewable builder profile page's read (task 1467, goal 25 "bx-identity"). |
+| PATCH | `/api/bongos/builders/:id/rank` | `archon` | `rank` | sole chokepoint that mutates builders.rank; ADR 0016 §enforcement. |
+| PATCH | `/api/bongos/builders/:id/status` | `archon` | `status`, `reason` | PATCH /builders/:id/status — graceful exit + reactivation (V3.R88 task 307). |
+| GET | `/api/bongos/builders/directory` | `any-builder` | — | GET /builders/directory — the any-builder-readable picker roster (task 1877): every ACTIVE builder's identity, for a client-side invite d… |
+| GET | `/api/bongos/builders/me/pending-rank-change` | `any-builder` | — | GET /builders/me/pending-rank-change — V3.R28 / task 249 ceremony signal task 3. |
+| GET | `/api/bongos/builders/roster` | `archon` | — | GET /builders/roster — V3.R14 (task 238) onboarding observability. |
+
+## `claims` (6)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/claims` | `any-builder` | `task_id`, `worktree_name`, `head_sha`, `bind_session`, `enforce_touches` | own work (claim a ready task); Xenos additionally filtered to newcomer_friendly rows inside db.claimTask (returns rank_too_low_for_task 4… |
+| POST | `/api/bongos/claims/:id/release-on-behalf` | `archon` | `reason` | POST /claims/:id/release-on-behalf — V3.R14 (task 238). |
+| POST | `/api/bongos/claims/:id/resolve` | `any-builder` | `outcome`, `notes_md`, `value_summary`, `verification`, `force`, `committed_files`, `sandbox_review` | resolve own claim (ship/abandon); ownership checked in db.resolveClaim (NOT_YOUR_CLAIM). |
+| POST | `/api/bongos/claims/batch` | `any-builder` | `task_ids`, `worktree_name`, `bind_session` | Atomic multi-claim. |
+| POST | `/api/bongos/claims/batch/release` | `any-builder` | `claim_ids`, `force` | Bulk release (task 1758) — the batch twin of resolve(outcome='abandoned'). |
+| POST | `/api/bongos/claims/batch/validate` | `any-builder` | `task_ids` | Dry-run validate (task 1758) — read-only twin of claimTasksBatch's pre-flight checks. |
+
+## `cost` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/cost` | `any-builder` | `task_id`, `amount_usd`, `category`, `description`, `source`, `source_ref`, `recorded_at`, `fresh_input_usd`, `cache_read_usd`, `cache_write_usd`, `output_usd`, `builder_id`, `skill_name` | log cost on own claim (idempotent via source/source_ref). |
+
+## `demo` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/demo/health` | `public` | — | READ — liveness + the core version this module was mounted against. |
+| POST | `/api/bongos/demo/ping` | `metic+archon` | `note` | WRITE — EVERY module write route MUST be rank-gated (the BV1.R44 fitness check reds the build on an ungated module write route). |
+
+## `dependencies` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/dependencies` | `archon` | — | POST /dependencies — create an edge "from is blocked until to is done". |
+| DELETE | `/api/bongos/dependencies` | `archon` | — | DELETE /dependencies — remove an edge (body carries the 4-tuple). |
+
+## `discord` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/discord/channels/plan` | `archon` | — | GET /api/bongos/discord/channels/plan — dry run. |
+| POST | `/api/bongos/discord/channels/reconcile` | `archon` | — | POST /api/bongos/discord/channels/reconcile — apply the config to Discord now. |
+
+## `done-when` (3)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/done-when/:criterionId/satisfy` | `metic+archon` | `satisfied_by_task_id` | Auth (Metic+): confirm a criterion — flip it to satisfied. |
+| POST | `/api/bongos/done-when/:criterionId/unsatisfy` | `archon` | — | Auth: flip a criterion back to unsatisfied (rare; for corrections). |
+| GET | `/api/bongos/done-when/pending-review` | `metic+archon` | — | Auth (Metic+): the criterion review queue — every criterion auto-flagged "met — pending review" (≥1 linked task, all shipped, not yet con… |
+
+## `gate-approvals` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/gate-approvals` | `archon` | — | GET /gate-approvals — open PRs awaiting owner approval (gate-review red), with the verdict + per-file reasons + changed files + diff link. |
+| POST | `/api/bongos/gate-approvals/:pr/approve` | `archon` | — | POST /gate-approvals/:pr/approve — record owner approval for a stuck gate PR and re-run the gate-review check so it clears. |
+
+## `goals` (21)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/goals` | `any-builder` | — | GET /goals?version=&status= — list goals (read). |
+| POST | `/api/bongos/goals` | `metic+archon` | `version_id`, `title`, `description`, `scope_modules`, `succeeds_goal_id` | POST /goals — create a goal. |
+| GET | `/api/bongos/goals/:id` | `any-builder` | — | GET /goals/:id — one goal with its members + linked criteria (read). |
+| POST | `/api/bongos/goals/:id/archive` | `metic+archon` | — | POST /goals/:id/archive — retire a goal (open\|achieved → archived). |
+| GET | `/api/bongos/goals/:id/conflicts` | `any-builder` | — | GET /goals/:id/conflicts — the server-side task-conflict view (task 1736). |
+| POST | `/api/bongos/goals/:id/conflicts/resolve` | `any-builder` | `action`, `note`, `touches`, `first_task_id`, `then_task_id`, `task_id` | POST /goals/:id/conflicts/resolve — the owner/manager resolution actions for a detected conflict (task 1736; authority model ADR 0106): s… |
+| POST | `/api/bongos/goals/:id/invitations` | `any-builder` | `note`, `builder_id` | POST /goals/:id/invitations { builder_id, note? } — an owner\|manager\|Archon invites a builder (task 1952). |
+| POST | `/api/bongos/goals/:id/invitations/:reqId/respond` | `any-builder` | `action` | POST /goals/:id/invitations/:reqId/respond { action: accept\|decline } — ONLY the invited builder resolves their OWN pending invite (task … |
+| POST | `/api/bongos/goals/:id/join` | `any-builder` | — | POST /goals/:id/join — join an open goal. |
+| POST | `/api/bongos/goals/:id/leave` | `any-builder` | — | POST /goals/:id/leave — leave a goal you're in. |
+| POST | `/api/bongos/goals/:id/members` | `any-builder` | `role`, `builder_id` | POST /goals/:id/members — the goal's own authority (owner \| manager \| Archon) invites a builder to the goal (task 1762: widened from Arch… |
+| PATCH | `/api/bongos/goals/:id/members/:builderId` | `any-builder` | `role` | PATCH /goals/:id/members/:builderId — role management by the goal's own authority (task 1735): the owner, a manager, or an Archon promote… |
+| POST | `/api/bongos/goals/:id/reopen` | `metic+archon` | — | POST /goals/:id/reopen — bring an archived goal back to open (ADR 0086 §6 / BV1.R64). |
+| POST | `/api/bongos/goals/:id/requests` | `any-builder` | `note` | POST /goals/:id/requests — a builder asks to join a (private or protected) goal (task 1952 / ADR 0112). |
+| POST | `/api/bongos/goals/:id/requests/:reqId/respond` | `any-builder` | `action` | POST /goals/:id/requests/:reqId/respond { action: approve\|deny } — an owner\| manager\|Archon resolves a pending join-request (task 1952). |
+| POST | `/api/bongos/goals/:id/scope` | `metic+archon` | `add` | POST /goals/:id/scope — "ask to widen": add module(s) to a goal's scope_modules (ADR 0086 §4 / BV1.R64). |
+| POST | `/api/bongos/goals/:id/tasks` | `any-builder` | `title`, `description`, `touches`, `est_minutes`, `priority`, `kind`, `discipline`, `value_summary`, `parent_task_id` | POST /goals/:id/tasks — bounded task authoring within a goal's scope (BV1.R60 / ADR 0086 §3). |
+| POST | `/api/bongos/goals/:id/transfer` | `any-builder` | `builder_id` | POST /goals/:id/transfer — hand the goal to a new owner (task 1735). |
+| PATCH | `/api/bongos/goals/:id/visibility` | `any-builder` | `visibility` | PATCH /goals/:id/visibility — make a goal public\|private (task 1952 / ADR 0112). |
+| GET | `/api/bongos/goals/inbox` | `any-builder` | — | GET /goals/inbox — the caller's private-goals inbox (task 1952 / ADR 0112): { invitations: invites addressed to me (accept/decline); join… |
+| POST | `/api/bongos/goals/reorder` | `archon` | `version_id`, `ordered_ids` | POST /goals/reorder — Archon drag-to-reorder: set the priority order of every goal WITHIN one version (task 1760). |
+
+## `grades` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/grades/by-builder` | `archon` | — | GET /grades/by-builder?days=30 — per-builder grade breakdown (task 726). |
+
+## `healthz` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/healthz` | `public` | — | liveness probe; status.example.com hits this anonymously. |
+
+## `inbox` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/inbox` | `any-builder` | — | read open ideas; skill-friction rows filtered by viewer rank. |
+| POST | `/api/bongos/inbox` | `any-builder` | `title`, `body_md`, `kind`, `suggested_version`, `suggested_priority` | for ordinary ideas; metic+ for kind='criterion-proposal'. |
+| GET | `/api/bongos/inbox/:id` | `any-builder` | — | single idea read for the "#NNN" deep-link resolver (task 1047). |
+| PATCH | `/api/bongos/inbox/:id` | `metic+archon` | `status`, `kind`, `promoted_to_task_id`, `reviewed_at` | Metic+ (task 360 / ADR 0018): idea triage (promote/discard/merge) shapes the backlog. |
+
+## `instance` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/instance` | `public` | — | the instance descriptor; pre-auth by design (a stranger fetches it to learn how to sign in). |
+
+## `leaderboard` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/leaderboard` | `public` | — | leaderboard mirrors the public /public/leaderboard surface; preserved unauthenticated to match current production behavior. |
+
+## `learnings` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/learnings` | `any-builder` | — | read learnings (own + others'). |
+| POST | `/api/bongos/learnings` | `any-builder` | `title`, `body_md`, `tags`, `related_files`, `source`, `source_ref`, `task_id` | capture a learning (own contribution). |
+
+## `live` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/live` | `any-builder` | — | GET /api/gds/live — SSE stream of GDS state-change nudges for the hall. |
+
+## `llm-cache` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/llm-cache/lookup` | `metic+archon` | `cache_key`, `tokens_saved_est` | POST /llm-cache/lookup — hit/miss + atomic hit_count bump. |
+| POST | `/api/bongos/llm-cache/store` | `metic+archon` | `spec`, `result_stdout`, `result_cost_usd` | POST /llm-cache/store — upsert a freshly-produced result. |
+
+## `me` (26)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/me` | `any-builder` | — | PMS-V2 task 188: response now also carries `unlocked` (server-joined achievement metadata) + `locked_with_progress` (server-computed huma… |
+| GET | `/api/bongos/me/achievements` | `any-builder` | — | The builder's unlocked achievements (joined to achievement metadata). |
+| POST | `/api/bongos/me/anthropic-link` | `any-builder` | `anthropic_email`, `anthropic_user_id` | V3.R10 (task 235), criterion C3 — link the authed builder's Anthropic account. |
+| GET | `/api/bongos/me/art-key` | `any-builder` | — | Shared art key for newcomers (task 1281 / ADR 0068). |
+| GET | `/api/bongos/me/art-key/own` | `any-builder` | — | Masked metadata for the browser: { set, last4, set_at, storage_configured }. |
+| PUT | `/api/bongos/me/art-key/own` | `any-builder` | `key` | Set or replace the builder's own key. |
+| DELETE | `/api/bongos/me/art-key/own` | `any-builder` | — | Remove the builder's own key (back to "not set"). |
+| POST | `/api/bongos/me/art-key/storage-init` | `archon` | — | Archon-only: provision the server's secret-box master key so per-builder key storage can turn on (task 1398, blocker 41). |
+| PATCH | `/api/bongos/me/disciplines` | `any-builder` | `preferred_disciplines` | Self-service edit of the authenticated builder's preferred disciplines (migrations 027 + 086 / V3.R80). |
+| GET | `/api/bongos/me/display-name` | `any-builder` | — | Per-builder DISPLAY NAME (task 1669). |
+| PATCH | `/api/bongos/me/display-name` | `any-builder` | _undocumented_ | PATCH the display name. |
+| GET | `/api/bongos/me/event-sound-prefs` | `any-builder` | — | Per-builder per-event sound variant selection (task 582, migration 164). |
+| PATCH | `/api/bongos/me/event-sound-prefs` | `any-builder` | _undocumented_ | PATCH a partial set of event sound overrides. |
+| GET | `/api/bongos/me/interaction` | `any-builder` | — | Per-builder INTERACTION PROFILE (task 2010, shares the behavior_prefs jsonb / migration 119). |
+| PATCH | `/api/bongos/me/interaction` | `any-builder` | _undocumented_ | PATCH the interaction profile. |
+| GET | `/api/bongos/me/model-allocation` | `any-builder` | — |  |
+| PATCH | `/api/bongos/me/model-allocation` | `any-builder` | _undocumented_ | PATCH the model allocation. |
+| GET | `/api/bongos/me/recent-ships` | `any-builder` | — | Tasks this builder has shipped, most recent first. |
+| GET | `/api/bongos/me/render` | `any-builder` | — | Per-builder "render widgets" knob (task 1279, shares the behavior_prefs jsonb / migration 119). |
+| PATCH | `/api/bongos/me/render` | `any-builder` | _undocumented_ | PATCH the render knob. |
+| GET | `/api/bongos/me/skill-prefs` | `any-builder` | — | Per-builder skill model preferences (V3.R85 / task 304, migration 037). |
+| PATCH | `/api/bongos/me/skill-prefs` | `any-builder` | _undocumented_ | PATCH a partial set of skill overrides. |
+| GET | `/api/bongos/me/sound-prefs` | `any-builder` | — | Per-builder per-sound on/off preferences (V3.R91 / task 786, migration 075). |
+| PATCH | `/api/bongos/me/sound-prefs` | `any-builder` | _undocumented_ | PATCH a partial set of sound overrides. |
+| GET | `/api/bongos/me/wandering` | `any-builder` | — | Per-builder "wandering" level (task 1268, migration 119). |
+| PATCH | `/api/bongos/me/wandering` | `any-builder` | _undocumented_ | PATCH the wandering level. |
+
+## `memory` (7)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/memory/bfg/builders/:builderId/file` | `bfg-principal` | — |  |
+| GET | `/api/bongos/memory/bfg/builders/:builderId/files` | `bfg-principal` | — |  |
+| POST | `/api/bongos/memory/builders/:builderId/bfg-write` | `bfg-principal` | `kind`, `slug`, `title`, `body_md`, `rationale`, `karma_delta` | ----------------------------------------------------------------------- BFG CROSS-BUILDER WRITE (task 446 / ADR 0026 §6C) — the FIRST cro… |
+| GET | `/api/bongos/memory/file` | `any-builder` | — | GET /memory/file?path=... |
+| DELETE | `/api/bongos/memory/file` | `any-builder` | validated | DELETE /memory/file?path=... |
+| GET | `/api/bongos/memory/files` | `any-builder` | — | GET /memory/files — list the AUTHENTICATED builder's memory files (metadata only, no content). |
+| POST | `/api/bongos/memory/sync` | `any-builder` | `files` | POST /memory/sync — push a builder's local memory files to the server. |
+
+## `modules` (3)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/modules` | `any-builder` | — | list every on-disk module with attribution + provenance (same read gate as the atlas/primer pages). |
+| POST | `/api/bongos/modules/:key/enable` | `metic+archon` | `enabled` | toggling a module changes running behavior for the whole instance, not just the caller. |
+| POST | `/api/bongos/modules/:key/submit` | `metic+archon` | — | the "submit this module for review" front door (501 until the submit pipeline, task 1770, ships). |
+
+## `override-requests` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/override-requests` | `archon` | — | GET /override-requests?status=open — Archon queue. |
+| POST | `/api/bongos/override-requests/:id/decide` | `archon` | `decision`, `note` | POST /override-requests/:id/decide — body: { decision: 'approve'\|'deny', note? } On approve, atomically flips the task completed→confirme… |
+
+## `provisioning` (11)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/provisioning/fleet` | `archon` | — | GET /provisioning/fleet — the full instance roster across all owners. |
+| GET | `/api/bongos/provisioning/fleet/cost-ledger` | `archon` | — | GET /provisioning/fleet/cost-ledger — per-instance monthly estimate + total. |
+| GET | `/api/bongos/provisioning/github-app/callback` | `public` | — | GET /provisioning/github-app/callback?code=&state= — GitHub redirects the owner's BROWSER here after they approve the App Manifest (task … |
+| GET | `/api/bongos/provisioning/health` | `public` | — | GET /provisioning/health — liveness + the core version this module mounted against. |
+| GET | `/api/bongos/provisioning/instances` | `any-builder` | — | GET /provisioning/instances — the caller's own instances + each open intent. |
+| POST | `/api/bongos/provisioning/instances` | `any-builder` | `slug`, `target_ref`, `hosting_shape`, `domain`, `tier` | POST /provisioning/instances — request a new instance. |
+| GET | `/api/bongos/provisioning/instances/:id` | `any-builder` | — | GET /provisioning/instances/:id — read one of the caller's own instances. |
+| POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `archon` | — | POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. |
+| POST | `/api/bongos/provisioning/instances/:id/github-app` | `any-builder` | `account` | POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 01… |
+| POST | `/api/bongos/provisioning/instances/:id/teardown` | `any-builder` | — | POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. |
+| GET | `/api/bongos/provisioning/tls-check` | `public` | — | GET /provisioning/tls-check?domain=<host> — the Caddy on-demand-TLS ALLOW-LIST (ADR 0111 §4, task P4 task 1945). |
+
+## `public` (18)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/public/analytics/ecosystem` | `public` | — | ecosystem-wide dev-curve aggregate; individuals stripped. |
+| GET | `/api/bongos/public/blockers/:id` | `public` | — | Public blocker resolver (task 654) — same minimal-projection posture as the idea resolver. |
+| GET | `/api/bongos/public/bounty-table` | `public` | — | V3.R65 task 284: red-team bounty payout table by severity. |
+| GET | `/api/bongos/public/branding` | `public` | — | the client-safe branding projection (R56 task 1195, ADR 0062 §3). |
+| GET | `/api/bongos/public/cost-summary` | `public` | — | GDS task 118: `daily` + `daily_credits` are guaranteed gap-free (one row per day from the earliest event through CURRENT_DATE, server tim… |
+| GET | `/api/bongos/public/estimation-drift` | `public` | — | est-vs-actual aggregate. |
+| GET | `/api/bongos/public/grades` | `public` | — | PMS-V2 task 197: rolling 7d quality-grade tile + 30d trend for the dashboard. |
+| GET | `/api/bongos/public/ideas/:id` | `public` | — | Public idea resolver (task 654) — the open-web counterpart to the hall's authenticated /inbox/:id. |
+| GET | `/api/bongos/public/leaderboard` | `public` | — | PMS-V2 task 188: each row now carries an `achievements` string[] (top 5 unlocked IDs by sort_order) so the dashboard can render inline em… |
+| GET | `/api/bongos/public/modules` | `public` | — | the client-safe feature-module set (R54 task 1193, ADR 0062 §4). |
+| GET | `/api/bongos/public/progress` | `public` | — | version progress aggregate. |
+| GET | `/api/bongos/public/recent-shipped` | `public` | — | GDS task 191: `?days=7\|30\|90` restricts to that trailing window; `?days=all` or omitted with no query returns the historical 30-row "rece… |
+| GET | `/api/bongos/public/ref-ids` | `public` | — | The id allow-list the doc-ref linkifier (scripts/gds/linkify-refs.js) and its CI gate consult to decide which bare "#NNN" are real refere… |
+| GET | `/api/bongos/public/repo-health` | `public` | — | V3.R91 task 352: repo-health substrate. |
+| GET | `/api/bongos/public/repo-info` | `public` | — | GitHub URL bases for the deployed checkout (V3.R13-followup-2 task 411). |
+| GET | `/api/bongos/public/tasks/:id` | `public` | — | Single-task resolver for "#NNN" deep links. |
+| GET | `/api/bongos/public/uptime` | `public` | — | Uptime: current status + 90-day history bucketed by hour. |
+| GET | `/api/bongos/public/versions` | `public` | — | read-only surface for status.example.com. |
+
+## `search` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/search` | `any-builder` | `expand`, `q`, `source_kind`, `limit` | POST /search — two modes (ADR 0095 C1 / task 1658, progressive disclosure): 1. |
+| POST | `/api/bongos/search/mark` | `any-builder` | `chunk_id`, `useful` | POST /search/mark — the write half of the memory-usefulness feedback loop (ADR 0095 C3, task 1660). |
+
+## `security` (3)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/security/docs` | `archon` | — | GET /api/gds/security/docs — list doc METADATA (no content). |
+| POST | `/api/bongos/security/docs` | `archon` | `slug`, `title`, `content_md` | POST /api/gds/security/docs — upsert a doc by slug. |
+| GET | `/api/bongos/security/docs/:slug` | `archon` | — | GET /api/gds/security/docs/:slug — one doc WITH content, or 404. |
+
+## `session` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/session/optimize` | `any-builder` | `mode`, `time_budget_min`, `max_parallel` | pick own next work; the optimizer reads/recommends only. |
+
+## `sessions` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/sessions` | `any-builder` | `session_id`, `task_ids`, `total_tokens`, `duration_seconds`, `started_at`, `ended_at`, `detail`, `metrics`, `model_usage` | upload your OWN session digest. |
+| GET | `/api/bongos/sessions/:id` | `any-builder` | — | own session full detail (deep-dive); cross-builder fetch requires Archon + a fail-closed audit row (BFG-principal posture until 6C.1). |
+| GET | `/api/bongos/sessions/mine` | `any-builder` | — | your OWN sessions (self-serve; no audit needed). |
+| GET | `/api/bongos/sessions/search` | `archon` | — | cross-builder corpus search (BFG-principal posture until 6C.1). |
+
+## `tasks` (27)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/tasks` | `any-builder` | — | reads (filtered task list); preserved per CRITICAL §4. |
+| POST | `/api/bongos/tasks` | `metic+archon` | `version_id`, `title`, `description`, `status`, `touches`, `est_minutes`, `est_cost_usd`, `manual_degree`, `priority`, `automation_tag`, `credits_reward`, `source`, `source_ref`, `value_summary`, `kind`, `discipline`, `parallel_safe`, `newcomer_friendly`, `security_sensitive`, `requires_rank`, `auto_detect_touches`, `criterion_ids`, `module_key`, `goal_id` | Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090 (owner decision 2026-06-26): a Metic who can run idea-triage may … |
+| GET | `/api/bongos/tasks/:id` | `any-builder` | — | single-task read; preserved per CRITICAL §4 (supervisor hot path). |
+| PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
+| POST | `/api/bongos/tasks/:id/abandon` | `archon` | `reason` | POST /tasks/:id/abandon — terminal "retire this task" transition (task 987). |
+| POST | `/api/bongos/tasks/:id/attest-gate` | `any-builder` | `head_sha` | POST /tasks/:id/attest-gate — body: { head_sha }. |
+| POST | `/api/bongos/tasks/:id/confirm` | `any-builder` | `verified` |  |
+| GET | `/api/bongos/tasks/:id/criteria` | `any-builder` | — | GET /tasks/:id/criteria — the criteria this task gates (with live "Cn" + source). |
+| POST | `/api/bongos/tasks/:id/criteria` | `metic+archon` | `criterion_ids`, `criterion_id` | POST /tasks/:id/criteria — body: { criterion_ids: [ref, ...] } OR { criterion_id: ref }. |
+| DELETE | `/api/bongos/tasks/:id/criteria/:criterionId` | `metic+archon` | — | DELETE /tasks/:id/criteria/:criterionId — removes one link (criterionId is the numeric done_when_criteria.id, mirroring DELETE deps/:depId). |
+| POST | `/api/bongos/tasks/:id/demote` | `metic+archon` | — | POST /tasks/:id/demote — the strict inverse of /promote: flip a task ready→backlog and nothing else. |
+| GET | `/api/bongos/tasks/:id/dependencies` | `any-builder` | — | GET /tasks/:id/dependencies — same data, surfaced as its own resource. |
+| POST | `/api/bongos/tasks/:id/dependencies` | `metic+archon` | `depends_on_task_ids`, `depends_on_task_id` | POST /tasks/:id/dependencies — body: { depends_on_task_id } OR { depends_on_task_ids: [N, ...] } Returns 409 with code='cycle' if accepti… |
+| PUT | `/api/bongos/tasks/:id/dependencies` | `metic+archon` | `depends_on_task_ids` | PUT /tasks/:id/dependencies — replace the full dep set. |
+| DELETE | `/api/bongos/tasks/:id/dependencies/:depId` | `metic+archon` | — | DELETE /tasks/:id/dependencies/:depId — removes the edge. |
+| POST | `/api/bongos/tasks/:id/grade` | `any-builder` | `subagent_output`, `signals`, `committed_files`, `diff_hash` | GDS-V3 task V3.R18 (task 209). |
+| POST | `/api/bongos/tasks/:id/override-request` | `any-builder` | `rationale` | POST /tasks/:id/override-request — V3.R74 (task 293). |
+| POST | `/api/bongos/tasks/:id/promote` | `metic+archon` | — | backlog→ready promotion; scope mutation; ADR 0090 (was archon). |
+| POST | `/api/bongos/tasks/:id/publish-branch` | `any-builder` | `branch`, `head_sha`, `bundle_b64`, `value_summary` |  |
+| GET | `/api/bongos/tasks/:id/publish-status` | `any-builder` | — | GET /tasks/:id/publish-status?branch=<branch> — poll the PR + prod-deploy state for a server-mediated publish so ship.js can confirm the … |
+| POST | `/api/bongos/tasks/:id/ship` | `any-builder` | — | confirmed → shipped. |
+| POST | `/api/bongos/tasks/:id/vote` | `metic+archon` | `vote` | POST /tasks/:id/vote { vote: 1 \| -1 \| 0 } — cast/change/clear a peer vote on a confirmed/shipped task. |
+| GET | `/api/bongos/tasks/claimable` | `any-builder` | — | NOTE: /tasks/claimable must come BEFORE /tasks/:id or Express will route 'claimable' to the :id param. |
+| GET | `/api/bongos/tasks/newcomer-floor` | `any-builder` | — | GET /tasks/newcomer-floor — supply gauge for the newcomer queue (task 614). |
+| POST | `/api/bongos/tasks/newcomer-restock` | `archon` | — | POST /tasks/newcomer-restock (task 1168) — bring every evergreen newcomer chore's standing pool up to its configured floor. |
+| GET | `/api/bongos/tasks/peer-votes/feed` | `any-builder` | — | GET /tasks/peer-votes/feed — recent confirmed/shipped work by OTHER builders, each with its net vote total and the caller's own current v… |
+| POST | `/api/bongos/tasks/peer-votes/tally` | `archon` | — | POST /tasks/peer-votes/tally — fold matured votes (≥7 days old, not yet counted) into karma_log, one net row per shipping builder, then m… |
+
+## `versions` (7)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/versions` | `public` | — | read-only version list; mirrors /public/versions. |
+| POST | `/api/bongos/versions` | `archon` | `id`, `name`, `status`, `done_when`, `scope_doc_path`, `criteria` | POST /versions — create a version + its done-when criteria in one call. |
+| GET | `/api/bongos/versions/:id/done-when` | `public` | — | Public: status.example.com fetches this every 60s alongside other public/* surfaces. |
+| POST | `/api/bongos/versions/:id/done-when` | `archon` | `criterion_id`, `criterion_md`, `goal_id`, `sort_order` | Auth (Archon): create a done-when criterion at RUNTIME. |
+| GET | `/api/bongos/versions/:id/progress` | `public` | — | Per-criterion progress rollup: each done-when criterion → the tasks that gate it (task_criteria, migration 055) → live statuses → what re… |
+| GET | `/api/bongos/versions/close-suggestions` | `public` | — | Close-flow gate suggestions for every version still 'building'. |
+| GET | `/api/bongos/versions/progress` | `public` | — | read-only progress aggregate; mirrors /public/progress. |
+
+---
+
+> 8 write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a `validateOrRespond` schema (`src/bongos/routes/_helpers.js`) surfaces them here automatically.
+