@bongos/core 1.23.21 → 1.24.1

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 587 endpoints across 98 route files.
+> **Generated from the live route files** — the route file is authoritative. 631 endpoints across 104 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/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -43,6 +43,23 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/agents/:name/enable` | `metic+archon` | — | POST /agents/:name/enable — THE OPERATOR ACT. |
 | POST | `/api/bongos/agents/:name/invoke` | `any-builder` | `input` | POST /agents/:name/invoke — fire an on-demand agent. |
 
+## `ai-studio` (12)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/ai-studio/balance` | `any-builder` | — |  |
+| GET | `/api/bongos/ai-studio/files/:id` | `any-builder` | — |  |
+| GET | `/api/bongos/ai-studio/keys` | `any-builder` | — |  |
+| PUT | `/api/bongos/ai-studio/keys/:provider` | `any-builder` | `key` |  |
+| DELETE | `/api/bongos/ai-studio/keys/:provider` | `any-builder` | — |  |
+| GET | `/api/bongos/ai-studio/requests` | `any-builder` | — |  |
+| POST | `/api/bongos/ai-studio/requests` | `any-builder` | `prompt`, `file_ids`, `pay_with` |  |
+| GET | `/api/bongos/ai-studio/requests/:id` | `any-builder` | — |  |
+| GET | `/api/bongos/ai-studio/status` | `any-builder` | — |  |
+| POST | `/api/bongos/ai-studio/topup` | `any-builder` | `amount_usd` | Top up the processor-held balance. |
+| GET | `/api/bongos/ai-studio/topup/quote` | `any-builder` | — | What a top-up of amount_usd would charge the card, before anything is paid (task 1004921): the Studio shows "your card is charged $20.91"… |
+| POST | `/api/bongos/ai-studio/uploads` | `any-builder` | `content_type`, `data`, `name` | One file per call, so a request body stays small; the global 64 KB parser skips this path (src/bongos/routes.js) and this parser takes it. |
+
 ## `analytics` (1)
 
 | Method | Path | Rank | Body | Description |
@@ -61,18 +78,22 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/audit-log` | `metic+archon` | — | GET /api/bongos/audit-log?limit=&offset=&builder_id=&method= Paginated, newest-first. |
 
-## `auth` (15)
+## `auth` (19)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | POST | `/api/bongos/auth/backchannel-logout` | `public` | `logout_token` | POST /auth/backchannel-logout — the INSTANCE side of federated single-logout (ADR 0144, task 1002238). |
 | POST | `/api/bongos/auth/cli-token/issue` | `any-builder` | — | POST /auth/cli-token/issue — V3.R91 / task 401. |
+| GET | `/api/bongos/auth/device` | `public` | — | shows a terminal's pending sign-in; approving it is the POST below. |
+| POST | `/api/bongos/auth/device/approve` | `any-builder` | `user_code`, `decision` | (own identity only) — mints a CLI session for the signed-in person themselves, from their browser cookie, never from a bearer (the /auth/… |
 | POST | `/api/bongos/auth/device/exchange` | `public` | `assertion` | POST /auth/device/exchange — CLI federation (ADR 0141 §1). |
 | 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. |
+| GET | `/api/bongos/auth/google/callback` | `public` | — | OAuth callback; the state cookie + code are the bearer. |
+| GET | `/api/bongos/auth/google/start` | `public` | — | entry into the Google OAuth handshake; identity establishment only. |
 | 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. |
@@ -122,7 +143,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/bug-attachments/:name` | `any-builder` | — | GET /api/bongos/bug-attachments/:name — stream one stored image. |
 
-## `builders` (13)
+## `builders` (14)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -131,6 +152,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/builders/:id/active-claims` | `metic+archon` | — | GET /builders/:id/active-claims — V3.R14 (task 238). |
 | GET | `/api/bongos/builders/:id/activity` | `any-builder` | — | GET /builders/:id/activity — the profile's PER-CRAFT activity log (task 1003281, goal 1000072, criterion legibility-activity-by-role). |
 | PATCH | `/api/bongos/builders/:id/budget` | `metic+archon` | `monthly_budget_usd` | PATCH /builders/:id/budget — set or clear a builder's monthly spend ceiling (V3.R84 task 302, criterion C3). |
+| PATCH | `/api/bongos/builders/:id/capabilities` | `archon` | `server` | PATCH /builders/:id/capabilities — the owner gives or takes a builder's server access (task 1004950, ADR 0395). |
 | 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. |
@@ -331,7 +353,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/goals/:id/requests/:reqId/withdraw` | `any-builder` | — | POST /goals/:id/requests/:reqId/withdraw — the requester cancels their OWN pending join-request (task 1953): the symmetric self-served mi… |
 | 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). |
 | GET | `/api/bongos/goals/:id/suggest-criteria` | `any-builder` | — | GET /goals/:id/suggest-criteria?title=&description=&limit= — task 2165. |
-| 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/tasks` | `any-builder` | `title`, `description`, `touches`, `est_minutes`, `priority`, `kind`, `discipline`, `value_summary`, `parent_task_id`, `needs` | 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` | — | PATCH /goals/:id/visibility — make a goal public\|private (task 1952 / ADR 0112). |
 | POST | `/api/bongos/goals/:id/water` | `any-builder` | — | POST /goals/:id/water — reset a rotting goal's clock. |
@@ -341,7 +363,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/goals/rollups` | `any-builder` | — | GET /goals/rollups?version= — one small row per goal: readiness counters, the last-activity timestamp, the craft set, and the next claima… |
 | GET | `/api/bongos/goals/suggestions` | `any-builder` | — | GET /goals/suggestions — "which goal should this draft live in?", answered before anything is created (task 1003062 / R07). |
 
-## `government` (36)
+## `government` (38)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -353,6 +375,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/government/assignments` | `archon` | — | government.manage — every builder↔rank assignment row. |
 | POST | `/api/bongos/government/assignments` | `archon` | `builder_id`, `rank_key` | government.manage — assign a CUSTOM rank to a builder. |
 | DELETE | `/api/bongos/government/assignments/:builderId/:rankKey` | `archon` | — | government.manage — remove a custom-rank assignment. |
+| GET | `/api/bongos/government/blockers/for-me` | `any-builder` | — |  |
+| GET | `/api/bongos/government/blockers/people` | `any-builder` | — | board.vote.cast — the governor's DOCKET (task 1004523, goal 1000125): ONE read of every matter waiting on, or moving for, a governor, whi… |
 | POST | `/api/bongos/government/board/charter` | `metic+archon` | `form`, `franchise`, `council_rank`, `pass_rule`, `window_minutes`, `rationale_md`, `acknowledge_self_removal` | board.item.open — the genesis charter + legislation choice (task 1004427, spec D10): a form of government and/or its two live settings (f… |
 | POST | `/api/bongos/government/board/decision-rules` | `metic+archon` | `rules`, `rationale_md` | board.item.open — propose a change to WHO DECIDES WHAT (task 1004529): one or more buildings' rows of the decision-rules table, filed as … |
 | GET | `/api/bongos/government/board/genesis-stages` | `any-builder` | — | board.vote.cast — the founding band's read (task 1004429): each genesis stage's latest sitting, and who it is still waiting on under the … |
@@ -366,7 +390,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/government/buildouts` | `any-builder` | `building`, `capsule`, `name`, `line` | board.vote.cast — a Lead's BUILD-OUT (task 1004711, ADR 0378): a committee room, a new floor, an annex, or growing the building into a di… |
 | GET | `/api/bongos/government/constitution` | `any-builder` | — | board.vote.cast — the Constitution view (R18 of goal 1000069): the live board block plus the full amendment history, passed and returned … |
 | GET | `/api/bongos/government/counts` | `any-builder` | — | board.vote.cast — the government's COUNTS in one read (task 1004716): what is on the viewer ("to do"), what waits on others, what is to d… |
-| GET | `/api/bongos/government/docket` | `any-builder` | — | board.vote.cast — the governor's DOCKET (task 1004523, goal 1000125): ONE read of every matter waiting on, or moving for, a governor, whi… |
+| GET | `/api/bongos/government/docket` | `any-builder` | — |  |
 | GET | `/api/bongos/government/laws` | `any-builder` | — | board.vote.cast — the law book (task 1004706): every law in force, oldest first, each with who passed it (the government it was decided u… |
 | GET | `/api/bongos/government/leads` | `any-builder` | — | board.vote.cast — the Lead of each building (task 1004709): the nine buildings in street order, each with its Lead in office (who, their … |
 | GET | `/api/bongos/government/permissions` | `archon` | — | government.manage — the permission catalog + principals, straight from code (the catalog is CODE, not a table); no DB read. |
@@ -491,7 +515,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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` (49)
+## `me` (54)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -511,6 +535,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/me/filter-views` | `any-builder` | `page`, `name`, `values`, `is_default` | Save the current filters as a view. |
 | PATCH | `/api/bongos/me/filter-views/:id` | `any-builder` | `page`, `name`, `is_default` | Rename a view and/or make it (or stop it being) my default for that page. |
 | DELETE | `/api/bongos/me/filter-views/:id` | `any-builder` | — | own filter config. |
+| POST | `/api/bongos/me/guardian-cosigns` | `any-builder` | `approval_id`, `rule_id`, `run_key` | POST /api/bongos/me/guardian-cosigns — as a guardian, co-sign one payout to the 16-17 builder(s) I am guardian for. |
 | GET | `/api/bongos/me/guild-engagements` | `any-builder` | — | MY inbox of guild engagements (ADR 0365): "G is applying to P" and "P invited G", for guilds I belong to, inside 30 days, naming only pro… |
 | GET | `/api/bongos/me/guild-requests` | `any-builder` | — | MY queue: invites addressed to me, each carrying the card (the guild's current visibility, which an accept must echo back), the join requ… |
 | GET | `/api/bongos/me/guilds` | `any-builder` | — | MY guilds, each with my own two switches. |
@@ -528,6 +553,9 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/me/passkeys/register/verify` | `any-builder` | `response`, `nickname` | POST /api/bongos/me/passkeys/register/verify — finish adding a card. |
 | POST | `/api/bongos/me/passkeys/remove` | `any-builder` | `credential_id` | POST /api/bongos/me/passkeys/remove — Body: { credential_id }. |
 | POST | `/api/bongos/me/passkeys/rename` | `any-builder` | `credential_id`, `nickname` | POST /api/bongos/me/passkeys/rename — Body: { credential_id, nickname }. |
+| POST | `/api/bongos/me/payout-age` | `any-builder` | `tier` | POST /api/bongos/me/payout-age — declare my own age tier. |
+| POST | `/api/bongos/me/payout-freezes/:id/appeal` | `any-builder` | `statement` | POST /api/bongos/me/payout-freezes/:id/appeal — appeal a hold on my pay. |
+| GET | `/api/bongos/me/payouts` | `any-builder` | — | GET /api/bongos/me/payouts — my payout standing: whether I can be paid, every hold on my pay with its notice and what happened since, and… |
 | PATCH | `/api/bongos/me/profile` | `any-builder` | `display_name`, `bio`, `links` | the caller's OWN profile fields (P02, task 1002798; spec Decision 4): bio, typed links, account display name. |
 | GET | `/api/bongos/me/profile-nudge` | `any-builder` | — | The "Complete your profile" nudge dismissal (task 1002802 / P06). |
 | PATCH | `/api/bongos/me/profile-nudge` | `any-builder` | _undocumented_ | PATCH the dismissal. |
@@ -537,6 +565,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/me/sessions` | `any-builder` | — | GET /api/bongos/me/sessions — every live session on the CALLER's account. |
 | POST | `/api/bongos/me/sessions/revoke` | `any-builder` | `session_id` | POST /api/bongos/me/sessions/revoke — kill ONE of the caller's own sessions. |
 | POST | `/api/bongos/me/sessions/revoke-all` | `any-builder` | validated | POST /api/bongos/me/sessions/revoke-all — sign out everywhere. |
+| GET | `/api/bongos/me/sign-in-methods` | `any-builder` | — | the ways the caller's OWN account signs in (task 1004992, ADR 0393): GitHub, Google, or both, with the address each provider vouched for. |
 | 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). |
@@ -597,6 +626,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/my-projects/invites/:clientId/decline` | `any-builder` | — | decline an invite (delete the pending row) for the caller's OWN account. |
 | POST | `/api/bongos/my-projects/join` | `any-builder` | `origin`, `note`, `guild` | request to join a project. |
 
+## `notes` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/notes` | `any-builder` | — | notes are shared working information, readable by anyone signed in; a private goal's notes are narrowed to its members by notes.canSee. |
+| POST | `/api/bongos/notes` | `any-builder` | `body`, `kind`, `task_id`, `goal_id` | adding information is not a privileged act; the author is the caller and is never taken from the body. |
+| PATCH | `/api/bongos/notes/:id` | `any-builder` | `kind` | , narrowed in the handler — the author re-files their own note; a Metic or Archon may re-file anyone's (the grouping is a shared view). |
+| DELETE | `/api/bongos/notes/:id` | `any-builder` | — | , narrowed in the handler exactly as the re-file above. |
+
 ## `npm-release` (8)
 
 | Method | Path | Rank | Body | Description |
@@ -632,6 +670,27 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/page-notes/images/:id` | `any-builder` | — |  |
 | GET | `/api/bongos/page-notes/site` | `any-builder` | — | The public site's reviews (task 1004499), for the Studio's list. |
 
+## `payouts` (16)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/payouts/age-records` | `archon` | `builder_id`, `tier` | POST /api/bongos/payouts/age-records — record a builder's age tier, verified by a person. |
+| GET | `/api/bongos/payouts/approvals` | `archon` | — | GET /api/bongos/payouts/approvals — the log, newest first. |
+| POST | `/api/bongos/payouts/approve` | `archon` | `recipient_id`, `amount_cents`, `currency`, `note` | POST /api/bongos/payouts/approve — approve ONE payout. |
+| POST | `/api/bongos/payouts/contracts` | `archon` | — | POST /api/bongos/payouts/contracts — sign ONE contract. |
+| POST | `/api/bongos/payouts/freezes` | `archon` | `builder_id`, `notice_text`, `owed_cents` | POST /api/bongos/payouts/freezes — a person freezes a builder's payouts by hand. |
+| POST | `/api/bongos/payouts/freezes/:id/decide` | `archon` | `decision`, `statement` | POST /api/bongos/payouts/freezes/:id/decide — uphold or lift a freeze, with the reason the person will read. |
+| GET | `/api/bongos/payouts/gates/:builderId` | `archon` | — | GET /api/bongos/payouts/gates/:builderId — may this builder be paid now, and why not. |
+| POST | `/api/bongos/payouts/grants` | `archon` | — | POST /api/bongos/payouts/grants — sign ONE equity grant. |
+| POST | `/api/bongos/payouts/guardians` | `archon` | `builder_id`, `guardian_id`, `guardian_account`, `active` | POST /api/bongos/payouts/guardians — link (or unlink) a 16-17 builder's guardian and the account the guardian controls. |
+| GET | `/api/bongos/payouts/rules` | `archon` | — | GET /api/bongos/payouts/rules — every standing rule with its current terms. |
+| POST | `/api/bongos/payouts/rules` | `archon` | `terms`, `note` | POST /api/bongos/payouts/rules — sign a standing payout rule. |
+| POST | `/api/bongos/payouts/rules/:id/narrow` | `archon` | `terms`, `note` | POST /api/bongos/payouts/rules/:id/narrow — tighten a rule. |
+| POST | `/api/bongos/payouts/rules/:id/revoke` | `archon` | `note` | POST /api/bongos/payouts/rules/:id/revoke — end a rule. |
+| POST | `/api/bongos/payouts/rules/:id/runs` | `archon` | `run_key`, `payouts`, `note` | POST /api/bongos/payouts/rules/:id/runs — notice a run under a rule, opening its pause window. |
+| POST | `/api/bongos/payouts/rules/:id/runs/:runKey/hold` | `archon` | `note` | POST /api/bongos/payouts/rules/:id/runs/:runKey/hold — a person stops a run in its pause window. |
+| POST | `/api/bongos/payouts/screenings` | `archon` | `builder_id`, `result`, `reference`, `valid_days` | POST /api/bongos/payouts/screenings — record a sanctions screening a person ran. |
+
 ## `profiles` (1)
 
 | Method | Path | Rank | Body | Description |
@@ -915,9 +974,9 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/tasks` | `any-builder` | — |  |
-| 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 … |
+| 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`, `needs`, `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`, `needs_migration`, `description`, `title`, `priority`, `value_summary`, `status` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
+| 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`, `needs`, `needs_migration`, `description`, `title`, `priority`, `value_summary`, `status` | 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` | `any-builder` | — | 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` |  |

package/docs/architecture.md

@@ -103,11 +103,16 @@ builders(id, github_id UNIQUE, github_login, display_name, avatar_url, total_cre
   + skill_model_prefs jsonb (mig 037), preferred_disciplines text[] (mig 027), timezone (PMS-V2),
     main_discipline text NULL (core_268 — the builder chosen MAIN role; NULL = not chosen, inferred from credits),
     deactivated_at/reactivated_at/deactivated_reason (mig 025 — the /builder-exit flow; #307 guard)
+  + capability_grants text[] NOT NULL DEFAULT '{}' (core_285, task 1004950) -- what the OWNER has granted by hand: ⊆ {server};
+    'owner' is the seat itself and never stored. PATCH /builders/:id/capabilities (owner seat only).
 tasks ... + xenos_claimable boolean NOT NULL DEFAULT false (mig 029) -- Xenos may claim only these
 versions(id PK 'V1'|'PMS-V1'..., name, track, status, scope_doc_path, ...)  -- track is free text (the product|internal CHECK was dropped in mig 112, task 1191); the valid set is instance config (config/branding.json "tracks"), not a DB constraint
 tasks(id, version_id, title, description, status, touches text[], est_minutes, est_cost_usd,
       manual_degree, priority, automation_tag, credits_reward, source, source_ref,
       promoted_at, shipped_at, shipped_by, value_summary, created_at, updated_at)
+  + needs text[] NOT NULL DEFAULT '{}' (mig core_285, task 1004950 / ADR 0395) -- what the task needs beyond the build
+    loop: ⊆ {owner, server}. The recommend lists show it only to a viewer holding those capabilities;
+    a claim refuses only 'server' without the grant. Visibility elsewhere is unchanged.
   + parked_at, parked_by (mig core_274, task 1004592) -- a PERSON put this task in backlog (restore
     or /demote); the promotion sweep and the three promotion triggers skip it, and a trigger clears
     both whenever status leaves 'backlog'
@@ -262,6 +267,37 @@ passkey_challenges(challenge PK, purpose, builder_id NULL, created_at, expires_a
               -- single-use (DELETEd on consume), TTL swept; builder_id NULL for sign-in
 ```
 
+Payout approvals (migration `core_283`, task 1004913, [ADR 0385](adr/0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) D4 — the approval step every money-moving task must cite; holds no money; `src/bongos/payout-approvals.js`, routes `/payouts/*` gated `payout.approve` plus the person's own web session):
+
+```
+payout_approvals(id, kind rule_signed|rule_narrowed|rule_revoked|run_noticed|run_held|
+              payout_approved|grant_signed|contract_signed, rule_id FK self, run_key,
+              actor_id FK, actor_rank, session_id, session_source, recipient_id FK,
+              amount_cents, currency, terms jsonb, note, created_at)
+              -- APPEND-ONLY by trigger (UPDATE/DELETE/TRUNCATE refused). Every kind but
+              -- run_noticed needs session_source='web' and a human actor; a narrowing
+              -- that widens, and anything after a revocation, are refused by trigger.
+```
+
+Payout gates (migration `core_284`, task 1004914, [ADR 0385](adr/0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) D8 — who may be paid at all; `src/bongos/payout-gates.js` runs on every `/payouts/*` money route and inside `checkRun`/`checkApproval`; a refused owed payout files a hold the person sees on `GET /me/payouts` and in the `/me` needs list, and appeals at `POST /me/payout-freezes/:id/appeal`):
+
+```
+payout_age_records(id, builder_id, tier under_13|13_15|16_17|adult, basis, recorded_by, recorded_at)
+payout_guardians(id, builder_id, guardian_id, guardian_account, active, recorded_by, recorded_at)
+payout_screenings(id, builder_id, result clear|match|error, screened_by processor:*|person:*,
+              reference, valid_until, recorded_by, screened_at)
+              -- a processor:* row counts only once PROCESSOR_SCREENING_CONFIRMED names
+              -- what the chosen processor screens (task 1004906 decides the processor)
+payout_freezes(id, builder_id, reason, notice_text NOT NULL, appeal_route NOT NULL,
+              owed_cents, frozen_by, frozen_at)
+payout_freeze_events(id, freeze_id, kind appealed|upheld|lifted, actor_id, statement, created_at)
+payout_guardian_cosigns(id, builder_id, guardian_id, approval_id | rule_id+run_key,
+              session_id, session_source='web', created_at)
+              -- ALL APPEND-ONLY by trigger; latest row wins. Triggers also refuse an appeal
+              -- by anyone but the frozen person, a decision by them, anything after a lift,
+              -- and a co-signature by anyone but the current guardian.
+```
+
 Store sub-categories (migration `core_280`, task 1004355, [ADR 0342](adr/0342-module-categories-are-eight-parents-with-approved-sub-categories.md) D3 — an author proposes one at publish, a Metic+ person approves, renames or merges it; `src/bongos/module-subcategories.js`):
 
 ```
@@ -326,7 +362,7 @@ Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again
 - **Canonical path is `/api/bongos` (task 1919); `/api/gds` is a PERMANENT alias.** The router + the discovery index are dual-mounted at both by `serve-internal.js`, driven by the single `src/bongos/api-prefix.js` constant (`API_PREFIX` + `LEGACY_API_PREFIXES`). The legacy `/api/gds` alias never goes away — shipped older CLI binaries, the cached status mirror, and older instances call it. **Exception:** the GitHub OAuth callback stays pinned to `/api/gds/auth/web/callback` (registered on the OAuth app; `src/bongos/routes/auth.js`). Not yet flipped (still ride the permanent alias): `src/**` internal callers + the deeper internal names (folders, `GDS_*` env, `gds_session` cookie) — the deferred internal-rename pass.
 - **Self-describing (task 1918, [ADR 0109](adr/0109-self-describing-openapi-and-hosted-docs.md)).** The whole surface is documented in the standard **OpenAPI 3.1** format at `docs/api/openapi.json`, **generated from the live route files** by `scripts/bongos/gen-api-docs.js` (reusing the same `route-rank-check.js` introspection the ship-time rank gate uses — so it can't drift). Since task 1004866 the spec, the reference and the typed client are **gitignored**: `package-core.js` generates them into every core tarball (and refuses to build if that fails), `serve-internal.js` generates `/docs/openapi.json` and `/lib/bongos-client.js` in-process when the files are absent, and fitness proves generation succeeds. A rendered docs site (vendored Redoc) is served at **`/docs`** on the apex of every instance (`cloudbongos.com/docs` canonical); `GET /api/bongos` returns a machine-discovery index pointing at it. The generated `docs/api-reference.md` supersedes the old hand-maintained `routes-permissions.md`. The mount prefix is the single `src/bongos/api-prefix.js` constant.
 
-- Auth: `POST /auth/device/start`, `/poll` (CLI Device Flow); `GET /auth/web/start`, `/web/callback` (browser); `POST /auth/logout`.
+- Auth: `POST /auth/device/start`, `/poll` (CLI Device Flow); `GET /auth/web/start`, `/web/callback` (browser); `POST /auth/logout`. Where Google sign-in is configured (the hub only, ADR 0396): `GET /auth/web/start` shows a GitHub/Google chooser, `GET /auth/google/start` + `/google/callback` sign in with Google, and the CLI device flow is approved in the browser at `GET /auth/device` + `POST /auth/device/approve`.
 - Own-scoped session self-service ([ADR 0206](adr/0206-own-scoped-session-revocation-no-absolute-ceiling.md), task 1003341), in [`src/bongos/routes/my-sessions.js`](../src/bongos/routes/my-sessions.js): `GET /me/sessions` (every live session on the caller's own account — source, user agent, created/last-used/expires, a `current` flag; the token value is never selected), `POST /me/sessions/revoke` (`{session_id}` — one of your own; a miss answers `revoked: 0` so a stranger's id cannot be probed) and `POST /me/sessions/revoke-all` (sign out everywhere, the requesting session included). All three gate on `requireBuilder` alone and key every statement on `req.builder.id` — an account is never named in the query, body or path. They exist because a bearer refreshes to `now()+24h` on every call, so a leaked one never expires, and the cross-builder pair (`POST /auth/revoke`, `/auth/revoke-all`, both still gated on the admin `auth.session.revoke` atom) needed an Archon the victim might not have. Surfaced in the hall at Settings → Active sessions.
 - Authenticated CLI/web: `GET /me` (returns `rank`), `GET /versions[/progress]`, `GET /tasks[?version=&status=&kind=&discipline=]`, `GET /tasks/claimable[?version=&discipline=]`, `GET /tasks/:id`, `POST /tasks` (accepts `discipline` + `criterion_ids`; **metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)), `PATCH /tasks/:id` (supports `parent_task_id`, `kind`, `discipline`, `goal_id` — (re)assign the task's goal; must be a goal in the task's own version, task 1763; **metic+**), `POST /tasks/:id/promote` (**metic+**), `POST /claims`, `POST /claims/:id/resolve`, `POST /cost`.
 - Criterion rollup + task↔criterion links ([ADR 0025](adr/0025-structured-criterion-task-link.md), [#435](https://example.com/builders#/task/435)/[#438](https://example.com/builders#/task/438)): `GET /versions/:id/progress` rolls up each done-when criterion → its gating tasks (via `task_criteria`) → live status counts + the not-yet-shipped `remaining[]` + `unattributed_tasks` (the read behind the `/status` skill, in `src/bongos/done-when.js criterionProgress`). The link CRUD mirrors the dependency endpoints: `GET /tasks/:id/criteria`, `POST /tasks/:id/criteria` (**metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)) and `DELETE /tasks/:id/criteria/:criterionId` (**metic+**). A criterion ref is a numeric `done_when_criteria.id`, a positional `"Cn"` token, or a `criterion_id` slug, resolved against the task's version (`POST /tasks` links at create time so `/status` counts the task with no backfill).

package/docs/canonical-permissions.md

@@ -231,7 +231,7 @@ or missing ranks fail closed.
   `POST /security/reports/:id/{confirm,dispute,fix,link-fix}`, `/security/docs` CRUD);
   `GET /api/bongos/audit-log`; the **roster reads** (`GET /builders/roster`, `/grades/by-builder`,
   `/builders/:id/active-claims`); **cross-builder memory reads** (`GET /memory/builders/:id/file[s]`);
-  **project curation + scouting**; `PATCH /builders/:id/budget`; `POST /inbox/:id/ratify`;
+  **project curation + scouting**; `PATCH /builders/:id/budget`; `PATCH /builders/:id/capabilities` (server access; additionally the owner seat only, task 1004950); `POST /inbox/:id/ratify`;
   `GET /override-requests` + `POST .../:id/decide`; `POST /claims/:id/release-on-behalf`;
   `POST /done-when/:id/unsatisfy`; `POST /goals/reorder`; `POST /versions`;
   `POST /tasks/newcomer-restock`; `POST /tasks/peer-votes/tally`; `GET /discord/channels/plan` +