@bongos/core 1.17.0 → 1.17.1

package/docs/api/openapi.json

@@ -4281,6 +4281,56 @@
       }
     },
     "/goals/{id}/requests": {
+      "get": {
+        "operationId": "get_goals_id_requests",
+        "tags": [
+          "goals"
+        ],
+        "summary": "GET /goals/:id/requests",
+        "description": "GET /goals/:id/requests — the goal's own pending invite/join-request queue (task 1953): every pending row on THIS goal, both kinds — outstanding invites the goal has sent (awaiting the invitee) and join-requests awaiting approval. db.listPendingRequestsForGoal was built for this route in task 1952's landing but never wired to HTTP; this is the goals-page manager view alongside the cross-goal GET /goals/inbox. rank: any-builder (requireBuilder) + the in-handler owner|manager|Archon gate (authorizeGoalManagement) — same wall as visibility/invite/request-respond.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/goals.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetGoalsIdRequestsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
       "post": {
         "operationId": "post_goals_id_requests",
         "tags": [
@@ -4415,6 +4465,67 @@
         ]
       }
     },
+    "/goals/{id}/requests/{reqId}/withdraw": {
+      "post": {
+        "operationId": "post_goals_id_requests_reqId_withdraw",
+        "tags": [
+          "goals"
+        ],
+        "summary": "POST /goals/:id/requests/:reqId/withdraw",
+        "description": "POST /goals/:id/requests/:reqId/withdraw — the requester cancels their OWN pending join-request (task 1953): the symmetric self-served mirror of a manager's deny. Sets status='cancelled' (kept as the audit trail, like a deny's 'rejected'); never touches an invitation row. rank: any-builder (requireBuilder) + the in-handler authorizeWithdrawJoinRequest.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/goals.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          },
+          {
+            "name": "reqId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `reqId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostGoalsIdRequestsReqIdWithdrawResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/goals/{id}/scope": {
       "post": {
         "operationId": "post_goals_id_scope",
@@ -6586,6 +6697,44 @@
         ]
       }
     },
+    "/modules/submissions": {
+      "get": {
+        "operationId": "get_modules_submissions",
+        "tags": [
+          "modules"
+        ],
+        "summary": "GET /modules/submissions",
+        "description": "GET /api/gds/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). Metadata only — no file contents (a future GET .../:id can add a with-files fetch if the review UI needs it). rank: metic+archon — the review queue, same rank as filing into it.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/modules.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetModulesSubmissionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/modules/{key}/enable": {
       "post": {
         "operationId": "post_modules_key_enable",
@@ -6656,7 +6805,7 @@
           "modules"
         ],
         "summary": "POST /modules/:key/submit",
-        "description": "the \"submit this module for review\" front door (501 until the submit pipeline, task 1770, ships).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /api/gds/modules/:key/submit — ADR 0107 §1 upstreaming submission. task 1770. Body: { signed_by?: \"Name <email>\" }. Re-runs the §4 AGPL/publish pre-check + requires a DCO-style sign-off against THIS box's OWN on-disk copy of modules/:key (the authoritative check — a local `bongos module check` pass on a builder's box is a courtesy, not proof, if the module's changes aren't committed + shipped + deployed here yet). signed_by records a NEW sign-off only if none is on file; an existing .upstream-signoff.json is reused as-is (not overwritten). rank: metic+archon — files into a shared review queue, not just a toggle for the caller.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/modules.js",
         "parameters": [
@@ -6670,12 +6819,30 @@
             "description": "Path parameter `key`."
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostModulesKeySubmitRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostModulesKeySubmitResponse"
+                }
+              }
+            }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -6878,6 +7045,34 @@
         "security": []
       }
     },
+    "/provisioning/github-app/status": {
+      "get": {
+        "operationId": "get_provisioning_github_app_status",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/github-app/status",
+        "description": "GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup is done + where to send the owner. Same public-by-state model as the callback: the unguessable, single-use `state` token is the only key, and the response reveals only the manifest lifecycle status + the instance's own (already-public) domain — never a secret. Per-IP rate-limited because the page polls it every ~3s. `ready` is true iff the manifest reached 'done' (creds placed + /healthz verified) — the page then auto-redirects to https://<domain>. rank: public — no session, no mutation, no secret; an unknown state is a 404 no-op.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningGithubAppStatusResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/provisioning/health": {
       "get": {
         "operationId": "get_provisioning_health",
@@ -7203,6 +7398,34 @@
         ]
       }
     },
+    "/provisioning/onboard-plan": {
+      "get": {
+        "operationId": "get_provisioning_onboard_plan",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/onboard-plan",
+        "description": "GET /provisioning/onboard-plan?mode=greenfield|adopt — the CANONICAL onboarding step sequence (task 2085; goal 35 / criterion 165: \"the canonical step sequence is the source of truth; skill/CLI/hall are forms over it\"). The branded /create page + the hall wizard fetch it so their human-steps checklist can't drift from the CLI's (scripts/gds/onboard.js reads the same modules/provisioning/onboard-plan.js). rank: public — the signed-out /create landing page reads it; it is the same public runbook the /new-project skill documents (no write, no secret).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningOnboardPlanResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/provisioning/tls-check": {
       "get": {
         "operationId": "get_provisioning_tls_check",
@@ -10250,6 +10473,15 @@
           "cross_goals_considered"
         ]
       },
+      "GetGoalsIdRequestsResponse": {
+        "type": "object",
+        "properties": {
+          "requests": {}
+        },
+        "required": [
+          "requests"
+        ]
+      },
       "GetGoalsIdResponse": {
         "type": "object",
         "properties": {
@@ -10530,6 +10762,15 @@
           "submit_pipeline_live"
         ]
       },
+      "GetModulesSubmissionsResponse": {
+        "type": "object",
+        "properties": {
+          "submissions": {}
+        },
+        "required": [
+          "submissions"
+        ]
+      },
       "GetOverrideRequestsResponse": {
         "type": "object",
         "properties": {
@@ -10548,6 +10789,27 @@
           "instances"
         ]
       },
+      "GetProvisioningGithubAppStatusResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "status": {},
+          "ready": {},
+          "terminal": {},
+          "domain": {},
+          "instance_status": {}
+        },
+        "required": [
+          "ok",
+          "status",
+          "ready",
+          "terminal",
+          "domain",
+          "instance_status"
+        ]
+      },
       "GetProvisioningHealthResponse": {
         "type": "object",
         "properties": {
@@ -10583,6 +10845,17 @@
           "instances"
         ]
       },
+      "GetProvisioningOnboardPlanResponse": {
+        "type": "object",
+        "properties": {
+          "mode": {},
+          "steps": {}
+        },
+        "required": [
+          "mode",
+          "steps"
+        ]
+      },
       "GetPublicBlockersIdResponse": {
         "type": "object",
         "properties": {
@@ -12305,6 +12578,19 @@
           "request"
         ]
       },
+      "PostGoalsIdRequestsReqIdWithdrawResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "request": {}
+        },
+        "required": [
+          "ok",
+          "request"
+        ]
+      },
       "PostGoalsIdRequestsRequest": {
         "type": "object",
         "properties": {
@@ -12807,6 +13093,29 @@
           "note"
         ]
       },
+      "PostModulesKeySubmitRequest": {
+        "type": "object",
+        "properties": {
+          "signed_by": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostModulesKeySubmitResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "submission": {}
+        },
+        "required": [
+          "ok",
+          "submission"
+        ]
+      },
       "PostOverrideRequestsIdDecideRequest": {
         "type": "object",
         "properties": {
@@ -13712,9 +14021,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 224,
-  "x-schema-count": 243,
+  "x-endpoint-count": 229,
+  "x-schema-count": 250,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 164,
+  "x-response-schemas": 170,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # GDS API reference
 
-> **Generated from the live route files** — the route file is authoritative. 224 endpoints across 38 route files.
+> **Generated from the live route files** — the route file is authoritative. 229 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`.
@@ -181,7 +181,7 @@ 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. |
 
-## `goals` (21)
+## `goals` (23)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -198,8 +198,10 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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). |
+| GET | `/api/bongos/goals/:id/requests` | `any-builder` | — | GET /goals/:id/requests — the goal's own pending invite/join-request queue (task 1953): every pending row on THIS goal, both kinds — outs… |
 | 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/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). |
 | 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). |
@@ -303,13 +305,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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)
+## `modules` (4)
 
 | 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). |
+| 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). |
 
 ## `override-requests` (2)
 
@@ -318,13 +321,14 @@ 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… |
 
-## `provisioning` (11)
+## `provisioning` (13)
 
 | 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/github-app/status` | `public` | — | GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup… |
 | 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. |
@@ -332,6 +336,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt — the CANONICAL onboarding step sequence (task 2085; goal 35 / criterion 165: "the c… |
 | 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)

package/docs/architecture.md

@@ -69,7 +69,7 @@ The product is organized as a small kernel (`src/`) + **19 modules** under `modu
 - **Post-merge branch cleanup (standard practice):** Every feature branch that lands on main via `--no-ff` merge gets deleted on origin once the deploy succeeds. The merge commit itself preserves the branch's history in main, so the named ref isn't carrying any signal — keeping it just clutters GitHub's branch list and tricks the UI into offering empty PRs against zero-diff branches. The auto-merge in [`scripts/gds/ship.js`](../scripts/gds/ship.js) does this automatically after `~/deploy.sh` returns 0; the manual [`/merge-mode`](../.claude/skills/merge-mode/SKILL.md) flow follows the same step 5b. Local refs and worktree directories stay — only the origin branch and the local tracking ref (cleaned on next `git fetch --prune`) go.
 - **Local dev machine:** Lars's MacBook Air (Apple Silicon, macOS Sequoia). Tooling installed via Homebrew at `/opt/homebrew/`. Node v26.0.0 locally; `package.json` declares `"engines": { "node": ">=22" }`. Single ed25519 SSH key (`~/.ssh/id_ed25519`) authenticates to GitHub and droplet.
 - **Smoke tests:** lightweight scripts in `/tmp/colyseus-*-smoketest.js` verify joinOrCreate, move protocol, interact, identity, queue. Run any after deploy with `node /tmp/colyseus-<name>-smoketest.js`.
-- **Repo topology today vs. the configurable-root future ([ADR 0108](adr/<redacted>.md)):** everything above describes the current **single checkout** — `git reset --hard` deploy, `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) both resolving to this same repo root. ADR 0108 lands (Mercury-first, then Example last) a model where Example instead installs a versioned `@cloudbongos/core` npm package and deploy becomes `git pull` (the instance repo) → `npm ci` (the pinned core) → migrate → restart — no more `git reset --hard` on a shared checkout. This section gets rewritten for the new topology once Example actually splits (ADR 0108 §6, task 1884/W4); until then it is unchanged and accurate.
+- **Repo topology today vs. the configurable-root future ([ADR 0108](adr/<redacted>.md)):** everything above describes the current **single checkout** — `git reset --hard` deploy, `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) both resolving to this same repo root. ADR 0108 lands (Mercury-first, then Example last) a model where Example instead installs a versioned `@bongos/core` npm package and deploy becomes `git pull` (the instance repo) → `npm ci` (the pinned core) → migrate → restart — no more `git reset --hard` on a shared checkout. This section gets rewritten for the new topology once Example actually splits (ADR 0108 §6, task 1884/W4); until then it is unchanged and accurate.
 
 **Database (`example` on Postgres 16, peer auth as `lars`):**
 

package/docs/file-map.md

@@ -147,7 +147,7 @@
 │       ├── gen-file-map.js      ← ADR 0066 ([#1276](https://example.com/builders#/task/1276)): generates the `.claude/skills/` + `.claude/scheduled-tasks/` sections of docs/file-map.md from disk; per-entry notes come from docs/file-map.notes.json; `--check` fails on drift OR a skill/routine with no note (CI gate via fitness.js); regenerated on deploy by ship.js regenerateFileMap()
 │       ├── fitness.js           ← Path C (ADR 0062 §9, [#1225](https://example.com/builders#/task/1225)): architecture fitness functions — core↔host import boundary (zero grandfathered exceptions as of R52/#1191), CLAUDE.md budget + nested-doc presence (ADR 0061), no route bypasses rank checks (reuses route-rank-check), repo-map freshness. Enforced in CI via tests/fitness.mjs (the `unit` gate). `node scripts/gds/fitness.js`
 │       ├── ship.js              ← resolve claim as shipped, award credits (`/builder-ship`); also uploads a secret-scrubbed session digest to the corpus (6D.1, ADR 0027); on a dev box runs the sandbox-first review gate before resolving (#927, ADR 0046)
-│       ├── package-core.js      ← package the core as a versioned, installable artifact + pin manifest (`bongos package-core`; R84, ADR 0100 §1, [#1688](https://example.com/builders#/task/1688)): isPublishable() selection + mirror redaction + fail-closed no-leak gate → dist/cloudbongos-core-<version>.{tgz,manifest.json}; version = src/module-api CORE_VERSION. Recipe: docs/recipes/packaging-the-core.md
+│       ├── package-core.js      ← package the core as a versioned, installable artifact + pin manifest (`bongos package-core`; R84, ADR 0100 §1, [#1688](https://example.com/builders#/task/1688)): isPublishable() selection + mirror redaction + fail-closed no-leak gate → dist/bongos-core-<version>.{tgz,manifest.json}; version = src/module-api CORE_VERSION. Recipe: docs/recipes/packaging-the-core.md
 │       ├── sandbox-stage.js     ← stage the working tree on the live game preview (box OR local) for browser review before ship; resolvePreviewContext picks the context (`/builder-stage`; #927, ADR 0046; local: task 1056)
 │       ├── local-preview.js     ← builder CLI for the LOCAL sandbox: start/stop/status/restart/logs/url of the game-only preview at http://localhost:3100 (`npm run preview`; task 1056)
 │       ├── local-preview-lib.js ← core of the local sandbox launcher (detached `node src/preview-server.js`, pid/health/port mgmt); shared by local-preview.js + sandbox-stage.js (task 1056)
@@ -170,7 +170,7 @@
 │       ├── gen-api-docs.js      ← ADR 0109: generates `docs/api/openapi.json` + `docs/api-reference.md` from the live route files via `route-rank-check.js` introspection, so the API reference cannot drift from what the server actually mounts
 │       ├── architect-audit.js   ← MAS Phase 5 (ADR 0024): the Architect's bounded first-principles `--scope`/`--paths` audit CLI → `docs/audits/`
 │       ├── module.js            ← `bongos module new <key>` scaffolder + module CLI utilities (ADR 0083)
-│       ├── upgrade.js           ← `bongos upgrade` — bump the installed `@cloudbongos/core` package version with doorway/coreVersion pre-checks (ADR 0108)
+│       ├── upgrade.js           ← `bongos upgrade` — bump the installed `@bongos/core` package version with doorway/coreVersion pre-checks (ADR 0108)
 │       └── newcomer-floor.js    ← deterministic on-claim replenisher for the evergreen newcomer chores (engineer/artist/ideator floor); no cron, restocks when one is claimed (task 1168)
 │
 ├── src/

package/docs/modules-contract.md

@@ -105,6 +105,8 @@ An unknown key throws at validate time — typos fail loud (top-level attributio
 
 **`bongos module check <key> [--sign-off "Name <email>"]`** ([ADR 0107](adr/<redacted>.md) §4) is the submit-time pre-check a module must clear before it can be upstreamed. It reuses (never re-types) the public-mirror publish denylist (`scripts/gds/publish-manifest.js`'s `matchesDeny`) to reject content that cannot ship under AGPL (game content, pixel art, copyrighted reference material) — deliberately the DENY half only, since a brand-new module is never on the publish ALLOWLIST until it's accepted into core (§6). It also requires `module.json`'s `license` to be AGPL-3.0 (inbound = outbound). On a pass, `--sign-off` records a lightweight DCO-style affirmation (own work, licensed AGPL-3.0 — never a copyright-assignment CLA) to `modules/<key>/.upstream-signoff.json`.
 
+**`bongos module submit <key> [--sign-off "Name <email>"]`** ([ADR 0107](adr/<redacted>.md) §1) re-runs the §4 pre-check + requires a sign-off, then packages the module (manifest + a full file snapshot + the sign-off) and files it into the rank-gated (metic+archon) upstreaming review queue via `POST /modules/:key/submit` — the same route the hall "Modules" tab's submit button calls. Refuses (exit 1) if the pre-check fails or no sign-off can be found/recorded. The queue currently lives in **this instance's own DB**, not a live call to the extracted core repo — see [ADR 0135](adr/<redacted>.md) for why, and `GET /modules/submissions` to read it back.
+
 ---
 
 ## The loader — `src/module-loader/loader.js`

package/docs/recipes/instance-deploy.md

@@ -1,12 +1,12 @@
 # Recipe — deploying a Cloud Bongos instance on a pinned core (`git reset` → `npm ci`)
 
-> ADR [0108](../adr/<redacted>.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@cloudbongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is [`scripts/deploy/deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh).
+> ADR [0108](../adr/<redacted>.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@bongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is [`scripts/deploy/deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh).
 
 ## The two models
 
 | | Pre-split (today, `example`) | Post-split (consumer instance) |
 |---|---|---|
-| Core code | in-tree (the monorepo) | `node_modules/@cloudbongos/core` (a pinned version) |
+| Core code | in-tree (the monorepo) | `node_modules/@bongos/core` (a pinned version) |
 | Deploy | [`deploy-prod.sh`](../../scripts/deploy/deploy-prod.sh): `git reset --hard origin/main` on a shared checkout | [`deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh): `git pull` the instance repo → `npm ci` → migrate → restart |
 | Upgrade the core | (n/a — one tree) | bump the pin in `package.json` → `npm ci` → migrate → restart (ADR 0108 §4; the R86 channel, task [#1690](https://example.com/builders#/task/1690)) |
 | `cloudbongos.com` | a 2nd service on the **same** checkout (why it ran stale) | its **own** consumer repo + its own `deploy-instance.sh` |
@@ -14,7 +14,7 @@
 ## The flow (`deploy-instance.sh`)
 
 1. **`git pull --ff-only origin main`** the *instance* repo — host content only: `config/`, `migrations/instance/`, and the pinned core version in `package.json`.
-2. **`npm ci --omit=dev`** — installs the pinned `@cloudbongos/core` + instance deps. This is what replaces `git reset --hard`: the core is a dependency, so an upgrade is a pin bump + `npm ci`, not a source merge.
+2. **`npm ci --omit=dev`** — installs the pinned `@bongos/core` + instance deps. This is what replaces `git reset --hard`: the core is a dependency, so an upgrade is a pin bump + `npm ci`, not a source merge.
 3. **`bash <core>/scripts/migrate.sh`** — the core's **three-root** migrate (W5 / ADR 0108 §5) merges `<core>/migrations` + `<instance>/migrations/instance` + each enabled module's migrations, keyed by namespaced filename stems (`core_NNN_`, `<key>_NNN_`, bare instance) so the two repos never collide. It resolves core-root vs instance-root via `src/instance-config.js`.
 4. **restart the platform** — a systemd unit runs `node <core>/src/platform-server.js` (GDS-only) with `WorkingDirectory` = the instance root (so `resolveInstanceRoot()` resolves to the instance) + `PORT`/`HOST` env; then poll `/healthz`.
 
@@ -32,6 +32,6 @@
 ## Wiring it on a consumer host (R85/R89)
 
 1. Install the script as the droplet's `~/deploy.sh` (the CI deploy key is forced-command-locked to `~/deploy.sh` — ADR 0043 — so it stays hand-installed, like `deploy-prod.sh`).
-2. Create a systemd unit for the instance: `ExecStart=/usr/bin/node <instanceRoot>/node_modules/@cloudbongos/core/src/platform-server.js`, `WorkingDirectory=<instanceRoot>`, `Environment=PORT=… HOST=127.0.0.1 <PREFIX>_INSTANCE_ROOT=<instanceRoot>`.
+2. Create a systemd unit for the instance: `ExecStart=/usr/bin/node <instanceRoot>/node_modules/@bongos/core/src/platform-server.js`, `WorkingDirectory=<instanceRoot>`, `Environment=PORT=… HOST=127.0.0.1 <PREFIX>_INSTANCE_ROOT=<instanceRoot>`.
 3. Set `INSTANCE_SERVICE=<unit>` + `PORT=<port>` in the deploy environment.
 4. Front it with TLS and point the origins at the real domain (see [self-host.md](self-host.md)).

package/docs/recipes/instance-first-run.md

@@ -0,0 +1,51 @@
+# First run: clone → working instance
+
+> The one-shot path from `git clone` of a **standalone Cloud Bongos instance repo**
+> (ADR 0108 — a repo that pins `@cloudbongos/core` as a dependency, e.g. `example-owner/demo`)
+> to a session that can actually claim + ship work. This is for a **builder joining an
+> existing instance**; standing up a *new* instance is `/new-project` (`bongos onboard`).
+
+## Why this recipe exists
+
+A cloned instance repo ships `config/` + `package.json` + a vendored core tarball, but
+**not** the installed engine. Until you install it there is no `bongos` binary and no
+`scripts/gds/…`, so every `/builder-*` skill fails. An agent that presses on in that
+state has no tools of its own and can fall back on whatever *other* Cloud Bongos instance
+the machine is signed in to — which is how a `demo` clone once offered to write a task
+into the wrong live backlog (2026-07-08). The session-start hook now prints these same
+steps when it detects an uninstalled instance (task 2105); the wrong-instance write it
+used to risk is refused outright (task 2102).
+
+## The steps
+
+From the repo root, in order:
+
+```bash
+# 1. Install the engine (the vendored core → node_modules + the `bongos` bin).
+#    No registry auth needed: the dependency is a local file: tarball.
+npm install
+
+# 2. Sign in to THIS instance (one browser click — no code to paste).
+#    Use the instance's own origin — the one in config/branding.json → domains.publicOrigin.
+npx bongos login https://<this-instance-origin>
+
+# 3. Confirm you're wired up: this lists what you can claim right now.
+npx bongos start
+```
+
+That's it — `bongos claim <id>` / `bongos ship` now work, scoped to this instance.
+
+## Notes
+
+- **Sign in to the RIGHT instance.** `bongos login <url>` writes a per-instance session
+  (`session.api_base`), and the CLI **refuses to act** if the session it would use belongs
+  to a different instance than this repo is configured for (task 2102). If you see that
+  refusal, re-run `bongos login` with *this* instance's origin.
+- **Which origin?** `config/branding.json` → `domains.publicOrigin`. `GET <origin>/api/bongos`
+  also re-advertises an instance's own hall/status/docs origins (the docs-discovery contract,
+  ADR 0114).
+- **Invite-only by default.** A brand-new GitHub account isn't admitted until an Archon
+  approves it; `bongos login` files the request and waits, then finishes sign-in.
+- **The engine lives in the package, not the repo.** `bongos` resolves the heavy CLI inside
+  `node_modules/@cloudbongos/core`; that's why step 1 must come first. On a machine with the
+  core installed globally you can drop the `npx`.