@bongos/core 1.18.0 → 1.18.3

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # GDS API reference
 
-> **Generated from the live route files** — the route file is authoritative. 223 endpoints across 36 route files.
+> **Generated from the live route files** — the route file is authoritative. 245 endpoints across 41 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`.
@@ -34,7 +34,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/audit-log` | `archon` | — | GET /api/gds/audit-log?limit=&offset=&builder_id=&method= Paginated, newest-first. |
 
-## `auth` (15)
+## `auth` (16)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -43,6 +43,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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/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. |
@@ -174,6 +175,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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. |
 
+## `github` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/github/repos` | `any-builder` | — | acts only on the caller's OWN GitHub identity (the token they granted). |
+| POST | `/api/bongos/github/repos` | `any-builder` | `name` | creates a repo in the caller's OWN account. |
+
 ## `goals` (24)
 
 | Method | Path | Rank | Body | Description |
@@ -213,7 +221,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
-| GET | `/api/bongos/healthz` | `public` | — | liveness probe; status.amazonprimea.com hits this anonymously. |
+| GET | `/api/bongos/healthz` | `public` | — | liveness probe; status.example.com hits this anonymously. |
 
 ## `inbox` (4)
 
@@ -303,6 +311,17 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/modules/:key/submit` | `metic+archon` | `signed_by` | POST /api/gds/modules/:key/submit — ADR 0107 §1 upstreaming submission. |
 | GET | `/api/bongos/modules/submissions` | `metic+archon` | — | GET /api/gds/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). |
 
+## `my-projects` (6)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/my-projects` | `any-builder` | — | the caller's OWN cross-project memberships (own data). |
+| POST | `/api/bongos/my-projects/:clientId/leave` | `any-builder` | — | leave a project from the caller's OWN membership list. |
+| GET | `/api/bongos/my-projects/invites` | `any-builder` | — | the caller's OWN pending invitations (ADR 0141 §5). |
+| POST | `/api/bongos/my-projects/invites/:clientId/accept` | `any-builder` | — | accept an invite (pending → builder) for the caller's OWN account. |
+| 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` | request to join a project. |
+
 ## `override-requests` (2)
 
 | Method | Path | Rank | Body | Description |
@@ -310,6 +329,16 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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… |
 
+## `projects` (5)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/projects` | `archon` | — | the full curation list (includes unfeatured + owner attribution). |
+| POST | `/api/bongos/projects` | `archon` | `origin`, `name`, `tagline`, `art_url` | create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration). |
+| PATCH | `/api/bongos/projects/:id/featured` | `archon` | `featured` | the feature / unfeature control (the ADR 0141 §5 curation gate). |
+| GET | `/api/bongos/projects/featured` | `public` | — | a curated public showcase; no auth by design. |
+| POST | `/api/bongos/projects/invite` | `archon` | `client_id`, `github_login` | invite a builder into a project (ADR 0141 §5, task #1002115). |
+
 ## `provisioning` (13)
 
 | Method | Path | Rank | Body | Description |
@@ -349,7 +378,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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.amazonprimea.com. |
+| GET | `/api/bongos/public/versions` | `public` | — | read-only surface for status.example.com. |
+
+## `scouting` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/scouting` | `archon` | — | the internal talent directory across every project. |
 
 ## `search` (2)
 
@@ -381,6 +416,18 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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). |
 
+## `sso` (7)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/sso/activity/rollup` | `public` | `client_id`, `client_secret`, `github_id`, `credits`, `tasks_shipped`, `karma`, `rank`, `disciplines` | POST /sso/activity/rollup — a federated instance reports a builder's activity snapshot (ADR 0141 §4). |
+| GET | `/api/bongos/sso/authorize` | `public` | — | GET /sso/authorize?client_id=&redirect_uri=&state= — the browser authorize leg. |
+| POST | `/api/bongos/sso/device/poll` | `public` | `device_code` | POST /sso/device/poll — poll the hub device flow. |
+| POST | `/api/bongos/sso/device/start` | `public` | `origin` | POST /sso/device/start — begin CLI federation. |
+| POST | `/api/bongos/sso/membership/check-in` | `public` | `client_id`, `client_secret`, `github_id`, `github_login`, `display_name`, `avatar_url`, `role` | POST /sso/membership/check-in — a federated instance reports, on every sign-in, that a builder builds on its project (ADR 0141 §3). |
+| GET | `/api/bongos/sso/pubkey` | `public` | — | GET /sso/pubkey — the hub's Ed25519 assertion-verification key (public). |
+| POST | `/api/bongos/sso/token` | `public` | `client_id`, `client_secret`, `code`, `redirect_uri` | POST /sso/token — server-to-server code redemption. |
+
 ## `tasks` (27)
 
 | Method | Path | Rank | Body | Description |
@@ -419,7 +466,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | 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.amazonprimea.com fetches this every 60s alongside other public/* surfaces. |
+| 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'. |

package/docs/file-map.md

@@ -322,7 +322,7 @@ tests/
 ├── builder-backup/SKILL.md        ← /builder-backup — check DB backup status or trigger a fresh local dump before risky changes (migrations, destructive SQL); no SSH required
 ├── builder-box/SKILL.md           ← /builder-box — show the builder their own dev box (state, IP/host, cost, SSH keys) and help them (re)connect
 ├── builder-claim/SKILL.md         ← /builder-claim N — atomic claim; prints the claim-time context pack + discipline playbook routing
-├── builder-connect/SKILL.md       ← /builder-connect — one-command connect of the builder's Claude Desktop to their Amazonprimea dev box (ADR 0031)
+├── builder-connect/SKILL.md       ← /builder-connect — one-command connect of the builder's Claude Desktop to their Example dev box (ADR 0031)
 ├── builder-cost/SKILL.md          ← /builder-cost — log a cost-ledger entry (api|compute|infra|domain|art|other)
 ├── builder-end/SKILL.md           ← /builder-end — safely close out a session: resolve the claim (ship/release) + clean-git verify + worktree teardown + (on a dev box) offer to close the box; the bookend to /builder-start, and the own-scoped session close-out that /builder-exit redirects non-Archons to
 ├── builder-exit/SKILL.md          ← /builder-exit — gracefully offboard (or reactivate) a builder: release claims, seal session logs, drop rank to xenos
@@ -336,20 +336,20 @@ tests/
 ├── builder-start/SKILL.md         ← /builder-start — list claimable tasks (parallel-safe vs active claims)
 ├── close-box/SKILL.md             ← /close-box — tear down the dev box you're working on, from inside the box terminal (POST /box/close)
 ├── design-sync/SKILL.md           ← /design-sync — export repo design tokens + surfaces into Claude Design (token-preview bundle) and land generated UI code back as a GDS task (ADR 0081)
-├── dev/SKILL.md                   ← /dev — engineering-session playbook for engineer-discipline tasks; the default understand→scoped-change→verify→ship loop made explicit ([#1272](https://amazonprimea.com/builders#/task/1272))
+├── dev/SKILL.md                   ← /dev — engineering-session playbook for engineer-discipline tasks; the default understand→scoped-change→verify→ship loop made explicit ([#1272](https://example.com/builders#/task/1272))
 ├── feedback/SKILL.md              ← /feedback — pull the latest Bongos feedback bundle (prompt.md + screenshot file paths) into a Claude Code session; backed by scripts/gds/feedback-latest.js (BV1.R13, ADR 0087)
 ├── figma-design-sync/SKILL.md     ← sync UI-surface tokens/surfaces with Figma (push a frame plan, land a designer's Code Connect / MCP snapshot edit back as code) — the ADR 0081 human escape hatch; distinct from otb-figma-sync's pixel-art tile review (task 2048)
 ├── goal-review/SKILL.md           ← /goal-review — walk the criterion review queue: each auto-flagged 'met — pending review' criterion gets confirm / reject / defer; confirming a goal's last criterion auto-achieves it (ADR 0086 §6); Metic+
 ├── idea-triage/SKILL.md           ← /idea-triage — daily walk through the GDS idea_inbox (promote / discard / merge); Metic+
-├── ideate/SKILL.md                ← /ideate — ideation-session playbook for ideator-discipline tasks; inverts the loop (human drives, Claude is the sounding board) ([#1267](https://amazonprimea.com/builders#/task/1267))
+├── ideate/SKILL.md                ← /ideate — ideation-session playbook for ideator-discipline tasks; inverts the loop (human drives, Claude is the sounding board) ([#1267](https://example.com/builders#/task/1267))
 ├── merge-mode/SKILL.md            ← /merge-mode — manual fallback for the auto-merge: land every confirmed task (merge + smoke + deploy)
-├── new-project/SKILL.md           ← /new-project — the canonical zero-to-live onboarding runbook for a new STANDALONE instance (name+address → init → scaffold → provision → OAuth+verified-secret+sign-in → verify → brand); the CLI + hall wizard are forms over it ([#1981](https://amazonprimea.com/builders#/task/1981))
+├── new-project/SKILL.md           ← /new-project — the canonical zero-to-live onboarding runbook for a new STANDALONE instance (name+address → init → scaffold → provision → OAuth+verified-secret+sign-in → verify → brand); the CLI + hall wizard are forms over it ([#1981](https://example.com/builders#/task/1981))
 ├── otb-character-review/SKILL.md  ← /otb-character-review — score a painterly character ANIMATION (same character / anatomy / pose / smooth motion) — the animation sibling of otb-design-review (ADR 0088)
-├── otb-design-review/SKILL.md     ← /otb-design-review — score a tile against the Amazonprimea rubric
+├── otb-design-review/SKILL.md     ← /otb-design-review — score a tile against the Example rubric
 ├── otb-feedback-capture/SKILL.md  ← /otb-feedback-capture — verbal design feedback → a durable style_guide.md rule
-├── otb-figma-sync/SKILL.md        ← /otb-figma-sync — push tiles into the Amazonprimea Figma file as a review canvas
+├── otb-figma-sync/SKILL.md        ← /otb-figma-sync — push tiles into the Example Figma file as a review canvas
 ├── otb-tile-generate/SKILL.md     ← /otb-tile-generate — run the pixel-art pipeline (generate world tiles/sprites)
-├── paint/SKILL.md                 ← /paint — art-session playbook for artist-discipline tasks; show-first/low-text, drives the otb-* pixel-art pipeline underneath ([#1269](https://amazonprimea.com/builders#/task/1269))
+├── paint/SKILL.md                 ← /paint — art-session playbook for artist-discipline tasks; show-first/low-text, drives the otb-* pixel-art pipeline underneath ([#1269](https://example.com/builders#/task/1269))
 ├── planning-session/SKILL.md      ← /planning-session — run a structured planning session for an upcoming version (set criteria, brainstorm, rank, seed GDS); Metic+
 ├── priority-session/SKILL.md      ← /priority-session — a trusted builder answers plain-speech questions; the answers reweight the idea_inbox + suggest what to build next
 ├── read-session-export/SKILL.md   ← /read-session-export — read a Claude Code /export zip fast (prompts + thinking + tool calls → stdout); reads the existing export, doesn't make one. Backed by scripts/gds/read-session-export.js

package/docs/recipes/packaging-the-core.md

@@ -26,12 +26,25 @@ Every file is **redacted** through the same fail-closed pipeline the public mirr
 bongos package-core                 # from HEAD, version = platform CORE_VERSION
 bongos package-core --ref origin/main --version 1.13.0
 node scripts/gds/package-core.js --droplet-ip <ip>   # add the prod IP as an exact gate literal
+bongos package-core --self-verify   # after building, prove the artifact reproduces its pin
+bongos package-core --self-verify --self-verify-boot   # ALSO npm-install the .tgz + boot /healthz
 ```
 
 `--ref` chooses the source commit (default `HEAD`), `--out-dir` the output dir (default `dist`), `--version` overrides the stamped version. `stdout` carries a one-line JSON pin (`{ core_version, source_commit, tree_sha256, tarball }`) for CI/scripts to capture; human detail goes to `stderr`.
 
+`--self-verify` (task [#1002218](https://example.com/builders#/task/1002218), audit H3) closes the produce-side of the integrity loop: after writing the artifact it **unpacks the built `.tgz` and recomputes `tree_sha256`, asserting it equals the manifest** (+ the on-disk `.tgz` bytes vs `tarball.sha256`) — proving the packager's own output reproduces its pin before it is trusted or published (a mismatch exits non-zero, ahead of the `--publish` leg). It is deterministic and network-free. Add `--self-verify-boot` to *also* `npm install` the tarball into a throwaway consumer and boot `/healthz` (reuses [`tests/consumer_layout_boot.mjs`](../../tests/consumer_layout_boot.mjs); needs npm/registry access — the deeper standing CI gate is task [#1002221](https://example.com/builders#/task/1002221)).
+
 If the no-leak gate fails, it names the file + the residual literal. Fix the redaction rules ([`scripts/gds/mirror-redact.js`](../../scripts/gds/mirror-redact.js)) or the manifest exclusions ([`scripts/gds/publish-manifest.js`](../../scripts/gds/publish-manifest.js)) and re-run — do not weaken the gate to force a pass.
 
+**The neutral floor** (task [#1002217](https://example.com/builders#/task/1002217), audit H4). Because the trunk carries no `config/branding.json`, the *branding-derived* redaction would strip nothing — so `package-core.js` always injects a fixed **`PRIOR_INSTANCE_FLOOR`** (prior-instance tokens/owners) into the doc-redaction + no-leak gate. Published **docs** are de-branded against it and the gate **fails closed** if a floor literal survives, even with no branding.json. **Functional** files still ship verbatim (the R88 fix) and are instead surfaced by the non-fatal `[leak-scan]` (task 1002220). To retire a new prior-instance token, add it to `PRIOR_INSTANCE_FLOOR` (kept in `package-core.js`, never in `mirror-redact.js` — that file's self-leak invariant forbids hardcoded literals).
+
+## Prove it boots (the standing PROVE-PUBLISH gates)
+
+Two standing gates keep "a published core boots clean from a bare install" honest (task [#1002221](https://example.com/builders#/task/1002221), audit H1/H2):
+
+- **`node scripts/gds/run-unit-tests.js --integration`** — the integration-smoke gate. Runs the heavier integration set (longer per-test budget), including [`tests/consumer_layout_boot.mjs`](../../tests/consumer_layout_boot.mjs), which packages the core, `npm install`s the `.tgz`, and boots `/healthz` from the real consumer layout. Run it per release / on a schedule in an env that provides the services (network, and — for the deeper DB leg tracked as a follow-up — Postgres). The default `run-unit-tests.js` (no flag) stays the fast DB-free unit gate and *excludes* this set.
+- **[`tests/pruned_lockfile_integrity.mjs`](../../tests/pruned_lockfile_integrity.mjs)** — a network-free unit guard (runs in the default gate every PR) that rebuilds the shipped pruned lockfile and asserts every registry package keeps a **well-formed, verbatim `integrity` hash**. This is the exact R88 regression (redaction once blanked those base64 hashes → `npm ci` could no longer verify) caught before a consumer's install ever fails.
+
 ## Consume + pin it (the R85 side)
 
 A downstream instance repo:

package/docs/recipes/upgrading-the-core.md

@@ -9,11 +9,12 @@
 1. **pre-flight** — module-compat vs the target core + a clean git tree (skip with `--force`).
 2. **bump the pin** — vendor the new `bongos-core-<version>.tgz` and rewrite the `"@bongos/core": "file:vendor/…"` dependency.
 3. **`npm install`** — `node_modules/@bongos/core` becomes the new version.
+3b. **verify the integrity pin** (task [#1002216](https://example.com/builders#/task/1002216)) — recompute `tree_sha256` over the installed core and check the vendored `.tgz` bytes against `tarball.sha256`, comparing to the trusted reference manifest (the committed `vendor/…manifest.json`; the installed inner manifest for `--registry`). Runs **before** migrate so a corrupted core never touches the DB. A **mismatch is fatal → rollback**; a missing reference warns (fatal with `--require-pin`); opt out with `--skip-pin-verify`.
 4. **`npm run migrate`** — the core's `migrate.sh` applies additive `core_*` migrations (merged three-root: core + instance + modules).
 5. **materialize `.claude/`** — refresh skills/settings/hooks from the new core (`materializeClaude`), rewriting invocations to the `bongos` bin.
 6. **restart** — `--service <unit>` or `--restart-cmd "<cmd>"`.
-7. **verify** — installed version == target (+ optional `--health-url`).
-8. **auto-rollback on failure** (task [#2149](https://example.com/builders#/task/2149), default ON) — if `npm install`/`migrate` fails or the step-7 health check fails, revert the pin → reinstall the previous core → restart → re-verify → write a `rolled_back:` ledger row. Opt out with `--no-rollback-on-failure`. See the section below.
+7. **verify** — installed version == target + the **mandatory post-restart health check** (task [#1002222](https://example.com/builders#/task/1002222)): a bump that restarts the service **requires `--health-url <url>`** (it can't report success without confirming the new core serves). Opt out explicitly with `--no-health-check`; a bump with no managed restart needs no URL (it reports the new core installed-but-unconfirmed). A still-failing health poll fails the bump (auto-rollback).
+8. **auto-rollback on failure** (task [#2149](https://example.com/builders#/task/2149), default ON) — if `npm install`/pin-verify/`migrate` fails or the step-7 health check fails, revert the pin → reinstall the previous core → restart → re-verify → write a `rolled_back:` ledger row. Opt out with `--no-rollback-on-failure`. See the section below.
 
 Run bare (`bongos upgrade`, no `--to`) it stays the module-compat **pre-check** only.
 
@@ -63,6 +64,8 @@ By default (`--rollback-on-failure`, ON unless `--no-rollback-on-failure`) the c
 
 **The DB is NOT rolled back — only the code pin.** Core migrations are additive + forward-safe (the core migration rule), so an already-applied migration is left in place; a *failed* migration is never recorded in `schema_migrations`, so a retry re-runs it cleanly. The reversal is recorded via the always-present `note` column (not a new `outcome` column) so it lands even in the failed-migrate path — where a newer column wouldn't yet exist on that instance.
 
+> **The forward-safe rule is now enforced, not just documented** (task [#1002223](https://example.com/builders#/task/1002223), audit H10). A core migration that DROPs/RENAMEs/retypes existing state (which would strand the rolled-back old code on the new schema) fails the [`tests/migrations_forward_safe.mjs`](../../tests/migrations_forward_safe.mjs) unit gate unless it carries an explicit `-- forward-unsafe: <reason>` acknowledgement pragma. `migrate.sh` also prints a non-fatal notice at apply time (via [`scripts/gds/lint-migrations.js`](../../scripts/gds/lint-migrations.js)). Additive migrations (the norm) need no annotation.
+
 **Proven live on demo.cloudbongos.com** (task [#2157](https://example.com/builders#/task/2157)): demo, on rollback-capable 1.17.3, was upgraded to a canary carrying a deliberately-failing migration. Migrate raised → the channel auto-reverted the pin to 1.17.3, reinstalled + restarted it, `/healthz` stayed 200 (**zero downtime** — the failure was at migrate, before the restart), and a `rolled_back` ledger row was written. This is the safety gate the unattended patch-only auto-upgrade subscription (task [#2150](https://example.com/builders#/task/2150)) depends on.
 
 ## Subscribing to updates — unattended patch-only auto-upgrade (task 2150 / ADR 0136)

package/migrations/039_newcomer_friendly_column.sql

@@ -1,6 +1,11 @@
 -- 039_newcomer_friendly_column.sql — V3.R15: tasks.newcomer_friendly column +
 -- view-level filter + Xenos claim-policy error code.
 --
+-- forward-unsafe: rename-column (RENAME tasks.xenos_claimable → newcomer_friendly). Historical
+--   (V3.R15, 2026), already applied on every instance long before `bongos upgrade`'s code-only
+--   rollback existed — no core version a current rollback could revert to reads the old column
+--   name. Acknowledged per audit H10 / task 1002223 (scripts/gds/lint-migrations.js).
+--
 -- Context: V3.R15 (#239) was planned as the row-level "newcomer-friendly task"
 -- gate for the Xenos rank. In parallel, #360 / ADR 0018 (migration 029) shipped
 -- the same idea under the name `xenos_claimable`. Now V3.R15 closes by:

package/migrations/102_remove_box_first_provision_approval.sql

@@ -1,6 +1,10 @@
 -- 102_remove_box_first_provision_approval.sql — ADR 0059 (task 1141): REMOVE the
 -- dev-box "first-box Archon approval" gate. Reverts migration 071.
 --
+-- forward-unsafe: drop-column (box_intents.approved_by / approved_at). Historical (ADR 0059, task
+--   1141); the code that read those columns was removed in the SAME change, and it predates
+--   `bongos upgrade`'s code-only rollback. Acknowledged per audit H10 / task 1002223.
+--
 -- Context
 -- -------
 -- Migration 071 (#717, ADR 0035 Decision 2) added a 'pending_approval' state to

package/migrations/core_192_github_oauth_tokens.sql

@@ -0,0 +1,33 @@
+-- core_192_github_oauth_tokens.sql — short-lived, encrypted GitHub repo tokens for
+-- the onboarding wizard (task 1002099, ADR 0143).
+--
+-- The wizard (public-landing/create.html) opts into `public_repo` at GitHub sign-in
+-- so it can LIST the signed-in user's repos (adopt) and CREATE an empty repo (fresh)
+-- — things `read:user` cannot do. That user-to-server GitHub token is held here
+-- BRIEFLY: one row per builder, the token encrypted with secret-box (master key in
+-- server env only — a DB dump alone decrypts nothing), with a short expires_at (one
+-- wizard sitting). It is read back by the repo picker/creator over the next few
+-- minutes and deleted on use; getGithubToken lazily sweeps an expired row so the
+-- table self-cleans without a cron. ON DELETE CASCADE ties a token to its builder.
+--
+-- This is the AUTH system's OWN handshake token (not a feature's third-party API
+-- key like the art module's Gemini key, ADR 0102), so it lives in core. When
+-- secret-box is unconfigured no row is ever written and the wizard falls back to
+-- manual repo entry (ADR 0143).
+--
+-- Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS github_oauth_tokens (
+  builder_id  bigint PRIMARY KEY REFERENCES builders(id) ON DELETE CASCADE,
+  token_enc   text NOT NULL,
+  scope       text,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  expires_at  timestamptz NOT NULL
+);
+
+-- The read/sweep hot path filters on expiry.
+CREATE INDEX IF NOT EXISTS idx_github_oauth_tokens_expires
+  ON github_oauth_tokens (expires_at);
+
+INSERT INTO schema_migrations (version) VALUES ('core_192_github_oauth_tokens')
+  ON CONFLICT (version) DO NOTHING;

package/modules/hall-ui/public/my-projects.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>My Projects</title>
+  <style>
+    :root {
+      --bg: #fff7ed; --card: #ffffff; --ink: #2a1f17; --ink-soft: #6b5d52;
+      --rule: #fed7aa; --accent: #ea580c; --accent-deep: #c2410c;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0; padding: 2.5rem 1.25rem 4rem; background: var(--bg); color: var(--ink);
+      font-family: "Quicksand", system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.5;
+    }
+    .wrap { max-width: 820px; margin: 0 auto; }
+    h1 { font-size: 1.9rem; margin: 0 0 .3rem; }
+    .sub { color: var(--ink-soft); margin: 0 0 2rem; }
+    h2 { font-size: 1.1rem; margin: 2rem 0 .75rem; border-bottom: 1px solid var(--rule); padding-bottom: .35rem; }
+    .row {
+      display: flex; align-items: center; gap: .75rem; background: var(--card);
+      border: 1px solid var(--rule); border-radius: 12px; padding: .8rem 1rem; margin-bottom: .6rem;
+    }
+    .row .meta { flex: 1; min-width: 0; }
+    .row .name { font-weight: 600; }
+    .row .origin { color: var(--accent); font-size: .82rem; word-break: break-all; }
+    .row .owner-pill { font-size: .72rem; background: var(--accent); color: #fff; border-radius: 999px; padding: .1rem .55rem; }
+    button {
+      font: inherit; cursor: pointer; border: 1px solid var(--rule); background: #fff; color: var(--ink);
+      border-radius: 9px; padding: .4rem .8rem;
+    }
+    button:hover { border-color: var(--accent); color: var(--accent-deep); }
+    .join { display: flex; gap: .5rem; margin-top: .75rem; }
+    .join input { flex: 1; font: inherit; padding: .5rem .7rem; border: 1px solid var(--rule); border-radius: 9px; }
+    .empty { color: var(--ink-soft); }
+    .note { margin-top: .5rem; color: var(--ink-soft); font-size: .9rem; min-height: 1.2em; }
+    a.home { color: var(--accent); text-decoration: none; font-size: .9rem; }
+    @media (prefers-color-scheme: dark) {
+      :root { --bg: #1a1410; --card: #241c16; --ink: #f5ece3; --ink-soft: #b9a998; --rule: #4a3728; }
+      button { background: #241c16; }
+      .join input { background: #241c16; color: inherit; }
+    }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <a class="home" href="/builders">← Back to the hall</a>
+    <h1>My Projects</h1>
+    <p class="sub">Every project you build on across the platform.</p>
+
+    <section>
+      <h2>Projects you own</h2>
+      <div id="owned"><p class="empty">—</p></div>
+    </section>
+
+    <section id="invites-section" hidden>
+      <h2>Invitations</h2>
+      <div id="invites"></div>
+    </section>
+
+    <section>
+      <h2>Projects you build on</h2>
+      <div id="building"><p class="empty">—</p></div>
+    </section>
+
+    <section>
+      <h2>Join a project</h2>
+      <div class="join">
+        <input id="join-origin" type="url" placeholder="https://project.cloudbongos.com" autocomplete="off">
+        <button id="join-btn" type="button">Request to join</button>
+      </div>
+      <p id="join-note" class="note"></p>
+    </section>
+  </div>
+  <script src="/my-projects.js"></script>
+</body>
+</html>

package/modules/hall-ui/public/my-projects.js

@@ -0,0 +1,142 @@
+// my-projects.js — the signed-in builder's cross-project view (ADR 0141 §3, task
+// #1002112). Fetches /api/gds/my-projects (session cookie, same-origin) and renders
+// owned + building-on lists with self-service leave, plus a join-by-origin form.
+// All network values are rendered via textContent — never innerHTML.
+(function () {
+  'use strict';
+  var ownedEl = document.getElementById('owned');
+  var buildingEl = document.getElementById('building');
+  var joinBtn = document.getElementById('join-btn');
+  var joinInput = document.getElementById('join-origin');
+  var joinNote = document.getElementById('join-note');
+
+  function el(tag, cls) { var e = document.createElement(tag); if (cls) e.className = cls; return e; }
+
+  function safeOriginHost(origin) {
+    try {
+      var u = new URL(String(origin));
+      return (u.protocol === 'https:' || u.protocol === 'http:') ? u.host : null;
+    } catch (_) { return null; }
+  }
+
+  function renderList(container, items, opts) {
+    container.textContent = '';
+    if (!items || items.length === 0) {
+      var p = el('p', 'empty');
+      p.textContent = opts.emptyText;
+      container.appendChild(p);
+      return;
+    }
+    items.forEach(function (m) {
+      var row = el('div', 'row');
+      var meta = el('div', 'meta');
+      var name = el('div', 'name');
+      name.textContent = m.name || m.client_id;
+      meta.appendChild(name);
+      var host = safeOriginHost(m.origin);
+      if (host) {
+        var o = el('div', 'origin');
+        o.textContent = host;
+        meta.appendChild(o);
+      }
+      row.appendChild(meta);
+      if (m.role === 'owner') {
+        var pill = el('span', 'owner-pill');
+        pill.textContent = 'owner';
+        row.appendChild(pill);
+      }
+      if (opts.leavable) {
+        var btn = el('button');
+        btn.type = 'button';
+        btn.textContent = 'Leave';
+        btn.addEventListener('click', function () { leave(m.client_id, row, btn); });
+        row.appendChild(btn);
+      }
+      container.appendChild(row);
+    });
+  }
+
+  function leave(clientId, row, btn) {
+    btn.disabled = true;
+    btn.textContent = 'Leaving…';
+    fetch('/api/gds/my-projects/' + encodeURIComponent(clientId) + '/leave', { method: 'POST' })
+      .then(function (r) { return r.ok ? r.json() : Promise.reject(); })
+      .then(function () { row.remove(); })
+      .catch(function () { btn.disabled = false; btn.textContent = 'Leave'; });
+  }
+
+  function resolveInvite(clientId, accept, row, btns) {
+    btns.forEach(function (b) { b.disabled = true; });
+    fetch('/api/gds/my-projects/invites/' + encodeURIComponent(clientId) + '/' + (accept ? 'accept' : 'decline'), { method: 'POST' })
+      .then(function (r) { return r.ok ? r.json() : Promise.reject(); })
+      .then(function () { row.remove(); if (accept) load(); loadInvites(); })
+      .catch(function () { btns.forEach(function (b) { b.disabled = false; }); });
+  }
+
+  function loadInvites() {
+    var section = document.getElementById('invites-section');
+    var container = document.getElementById('invites');
+    fetch('/api/gds/my-projects/invites', { headers: { Accept: 'application/json' } })
+      .then(function (r) { return r.ok ? r.json() : Promise.reject(); })
+      .then(function (data) {
+        var invites = (data && data.invites) || [];
+        if (invites.length === 0) { section.hidden = true; return; }
+        container.textContent = '';
+        invites.forEach(function (inv) {
+          var row = el('div', 'row');
+          var meta = el('div', 'meta');
+          var name = el('div', 'name');
+          name.textContent = inv.name || inv.client_id;
+          meta.appendChild(name);
+          var host = safeOriginHost(inv.origin);
+          if (host) { var o = el('div', 'origin'); o.textContent = host; meta.appendChild(o); }
+          row.appendChild(meta);
+          var accept = el('button'); accept.type = 'button'; accept.textContent = 'Accept';
+          var decline = el('button'); decline.type = 'button'; decline.textContent = 'Decline';
+          accept.addEventListener('click', function () { resolveInvite(inv.client_id, true, row, [accept, decline]); });
+          decline.addEventListener('click', function () { resolveInvite(inv.client_id, false, row, [accept, decline]); });
+          row.appendChild(accept); row.appendChild(decline);
+          container.appendChild(row);
+        });
+        section.hidden = false;
+      })
+      .catch(function () { section.hidden = true; });
+  }
+
+  function load() {
+    fetch('/api/gds/my-projects', { headers: { Accept: 'application/json' } })
+      .then(function (r) { return r.ok ? r.json() : Promise.reject(); })
+      .then(function (data) {
+        renderList(ownedEl, data.owned, { emptyText: 'You don’t own any projects yet.', leavable: false });
+        renderList(buildingEl, data.building, { emptyText: 'You’re not building on any other projects yet.', leavable: true });
+      })
+      .catch(function () {
+        ownedEl.textContent = ''; buildingEl.textContent = '';
+        var p = el('p', 'empty'); p.textContent = 'Couldn’t load your projects right now.';
+        buildingEl.appendChild(p);
+      });
+  }
+
+  joinBtn.addEventListener('click', function () {
+    var origin = (joinInput.value || '').trim();
+    if (!origin) { joinNote.textContent = 'Enter a project URL.'; return; }
+    joinBtn.disabled = true;
+    joinNote.textContent = 'Requesting…';
+    fetch('/api/gds/my-projects/join', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ origin: origin }),
+    })
+      .then(function (r) { return r.json().then(function (b) { return { ok: r.ok, body: b }; }); })
+      .then(function (res) {
+        joinBtn.disabled = false;
+        if (res.ok && res.body && res.body.message) { joinNote.textContent = res.body.message; joinInput.value = ''; load(); }
+        else if (res.body && res.body.error && res.body.error.code === 'unknown_project') { joinNote.textContent = 'That project isn’t on the platform.'; }
+        else { joinNote.textContent = 'Could not request access right now.'; }
+      })
+      .catch(function () { joinBtn.disabled = false; joinNote.textContent = 'Could not request access right now.'; });
+  });
+
+  load();
+  loadInvites();
+}());

package/modules/hall-ui/public/scouting.html

@@ -0,0 +1,45 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Scouting — cross-project builders</title>
+  <style>
+    :root {
+      --bg: #fff7ed; --card: #ffffff; --ink: #2a1f17; --ink-soft: #6b5d52;
+      --rule: #fed7aa; --accent: #ea580c;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0; padding: 2.5rem 1.25rem 4rem; background: var(--bg); color: var(--ink);
+      font-family: "Quicksand", system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.5;
+    }
+    .wrap { max-width: 960px; margin: 0 auto; }
+    a.home { color: var(--accent); text-decoration: none; font-size: .9rem; }
+    h1 { font-size: 1.9rem; margin: .4rem 0 .3rem; }
+    .sub { color: var(--ink-soft); margin: 0 0 1.75rem; }
+    .badge { display: inline-block; font-size: .7rem; text-transform: uppercase; letter-spacing: .06em;
+      background: var(--accent); color: #fff; border-radius: 999px; padding: .12rem .6rem; vertical-align: middle; }
+    table { width: 100%; border-collapse: collapse; background: var(--card); border: 1px solid var(--rule); border-radius: 12px; overflow: hidden; }
+    th, td { text-align: left; padding: .6rem .8rem; border-bottom: 1px solid var(--rule); font-size: .92rem; }
+    th { color: var(--ink-soft); font-weight: 600; }
+    td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+    tr:last-child td { border-bottom: none; }
+    .who { font-weight: 600; }
+    .note { color: var(--ink-soft); padding: 2.5rem 1rem; text-align: center; }
+    .scroll { overflow-x: auto; }
+    @media (prefers-color-scheme: dark) {
+      :root { --bg: #1a1410; --card: #241c16; --ink: #f5ece3; --ink-soft: #b9a998; --rule: #4a3728; }
+    }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <a class="home" href="/builders">← Back to the hall</a>
+    <h1>Scouting <span class="badge">Archon only</span></h1>
+    <p class="sub">Builders active across all hosted projects — an internal talent view. Descriptive only; it grants no authority anywhere.</p>
+    <div id="body" class="note">Loading…</div>
+  </div>
+  <script src="/scouting.js"></script>
+</body>
+</html>

package/modules/hall-ui/public/scouting.js

@@ -0,0 +1,73 @@
+// scouting.js — the internal Archon-only cross-project scouting view (ADR 0141 §4,
+// task #1002114). Fetches /api/gds/scouting (Archon-gated server-side) and renders a
+// ranked table. A non-Archon gets a 403 and sees the Archon-only notice — the data
+// endpoint's rank gate is the real protection ("NOT shown to builders"). All network
+// values are rendered via textContent — never innerHTML.
+(function () {
+  'use strict';
+  var body = document.getElementById('body');
+
+  function el(tag, cls) { var e = document.createElement(tag); if (cls) e.className = cls; return e; }
+  function td(text, cls) { var c = el('td', cls); c.textContent = text; return c; }
+
+  function fmtRecency(iso) {
+    if (!iso) return '—';
+    var t = Date.parse(iso);
+    if (isNaN(t)) return '—';
+    var days = Math.floor((Date.now() - t) / 86400000);
+    if (days <= 0) return 'today';
+    if (days === 1) return '1 day ago';
+    if (days < 30) return days + ' days ago';
+    return Math.floor(days / 30) + ' mo ago';
+  }
+
+  function render(builders) {
+    body.className = '';
+    body.textContent = '';
+    if (!builders || builders.length === 0) {
+      body.className = 'note';
+      body.textContent = 'No cross-project activity reported yet.';
+      return;
+    }
+    var scroll = el('div', 'scroll');
+    var table = el('table');
+    var thead = el('thead');
+    var hr = el('tr');
+    [['Builder', ''], ['Projects', 'num'], ['Credits', 'num'], ['Ships', 'num'], ['Karma', 'num'], ['Disciplines', ''], ['Last active', '']]
+      .forEach(function (h) { var th = el('th', h[1]); th.textContent = h[0]; hr.appendChild(th); });
+    thead.appendChild(hr); table.appendChild(thead);
+    var tbody = el('tbody');
+    builders.forEach(function (b) {
+      var tr = el('tr');
+      var who = el('td');
+      var name = el('span', 'who');
+      name.textContent = b.github_login || b.display_name || ('#' + b.github_id);
+      who.appendChild(name);
+      tr.appendChild(who);
+      tr.appendChild(td(String(b.project_count != null ? b.project_count : '—'), 'num'));
+      tr.appendChild(td(String(b.total_credits != null ? b.total_credits : 0), 'num'));
+      tr.appendChild(td(String(b.total_tasks_shipped != null ? b.total_tasks_shipped : 0), 'num'));
+      tr.appendChild(td(String(b.total_karma != null ? b.total_karma : 0), 'num'));
+      tr.appendChild(td(Array.isArray(b.disciplines) ? b.disciplines.join(', ') : '—'));
+      tr.appendChild(td(fmtRecency(b.last_active)));
+      tbody.appendChild(tr);
+    });
+    table.appendChild(tbody);
+    scroll.appendChild(table);
+    body.appendChild(scroll);
+  }
+
+  fetch('/api/gds/scouting', { headers: { Accept: 'application/json' } })
+    .then(function (r) {
+      if (r.status === 403 || r.status === 401) { throw { archon: true }; }
+      if (!r.ok) throw new Error('http ' + r.status);
+      return r.json();
+    })
+    .then(function (data) { render(data && data.builders); })
+    .catch(function (e) {
+      body.className = 'note';
+      body.textContent = (e && e.archon)
+        ? 'This view is Archon-only.'
+        : 'Couldn’t load the scouting view right now.';
+    });
+}());