@bongos/core 1.19.562 → 1.19.563

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.562",
-  "core_contract": "1.19.562",
-  "source_commit": "8812128543b799aea8050fb1d51256bbdd0fc717",
+  "core_version": "1.19.563",
+  "core_contract": "1.19.563",
+  "source_commit": "c8dc8ef54a7fd97c2ba21c436f6c1faf0a125f0f",
   "source_ref": "HEAD",
-  "built_at": "2026-09-06T17:33:48.313Z",
+  "built_at": "2026-09-06T17:53:15.785Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 443,
+    "docs_redacted": 444,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2025,
+    "functional_verbatim": 2029,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2492,
-  "tree_sha256": "dc363435f4898d5c74509b25e810a61c1f3a4962b038c4f1c0c1527167e48217",
+  "file_count": 2497,
+  "tree_sha256": "d705f290c86bc4240b5cd119cb250092b6b2d7af6d8ffc8e870dd1f0ae6cdef3",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -372,12 +372,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "262491824b5d7b6005c69d8190d50f450320f02dc1333dc7ae029616aff9f018"
+      "sha256": "38988a49c2cdcc89db69602de1fe46cba0de430643c677352b9db36ed89c010c"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "fd5d716ec3ba7fbdb9fdaee076ef89048424248139ef7d4ea51c3983866dea90"
+      "sha256": "bd7d31e9cff0d758cc66c1d4adcf52eeaa99acc2ef48d459265425e2a4d2fd19"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -387,17 +387,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "17753bb744e592f7d7871d33399536d9938b1b7d6c6249959bcbb4355688b557"
+      "sha256": "33fbbbaf2a4a939b7351a7aa25264ddd609c1298d9ba809372a162983afe5038"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "24cbe2964b71993d9d6e55daaf0dc26c938f820c7c4f6c01579d9dd2508e89ba"
+      "sha256": "a0992ef72cffc0d200e62bd5315e64090eda7cbd3477a01ec041e2d08bb39b9e"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "779dc3d8970036513a0f8da8e4846bd6c0d2d4714de38390b14ede249e75a3f6"
+      "sha256": "e83e49178398441026fe6fd4822dd4eddae2c2316f5aa5006a090ef0d1a41b98"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1769,20 +1769,25 @@
       "mode": "0000644",
       "sha256": "da4549c19609d1f549e6f5a57b530c330765f1778f0a9b09a15a208f4575f986"
     },
+    {
+      "path": "docs/adr/0251-a-suggestion-of-who-to-invite-is-a-recruiting-surface-and-owes-the-opt-out.md",
+      "mode": "0000644",
+      "sha256": "8ccfe21df7ab80ed872565bc879fb21a1b35ce81da55151035f2dc45cd40e749"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "f779c7dc040fd7096fa27e713c7045c44d69b1b7fa5fee107e6ae4d69ae11d6e"
+      "sha256": "6d7f0b67401ca836ed08f5cea31ea578c10987718de48fecc0ac663528e9403d"
     },
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "41a9d190c9df11d3adba109668508d147d8a148ae4222c2dc6aacf2ea811c7f3"
+      "sha256": "ae645afb5ce376b7e7b4ad0a5c00f63e48a2d0540fe79af29106d174a41ac3e8"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "1ad70f7f1cb7f53735f17fbd8e05287c9191a1d249493c928efb91692b491941"
+      "sha256": "a009aa37bc7698ac1469b45ac875b1b3884c0104b7f8a886e450082d503de45c"
     },
     {
       "path": "docs/architecture.md",
@@ -1807,12 +1812,12 @@
     {
       "path": "docs/copy-inventory.md",
       "mode": "0000644",
-      "sha256": "f031d9706b2afc0f579684ec7d451d38b9c8ffd88f7fdb29e3b720a306f80c2f"
+      "sha256": "375801be3c0c325da208e3f95fb6aa04e5a0136297673a562d143f61e4ca4c83"
     },
     {
       "path": "docs/copy-registry.json",
       "mode": "0000644",
-      "sha256": "aff8da11e90581e6ca7c9410d4524bf22d8bce6fe8f58bae9ebd6f1de744a2eb"
+      "sha256": "5a2ff67ac4a1cf8edf959b02db2a1c226de24c16a8b7b98762cfc1863d1a8f52"
     },
     {
       "path": "docs/design/apex-pass-2-direction.md",
@@ -2657,7 +2662,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "9c9e6c53ef623de12cdca7cd96dfc2221c19843f45d3a84a196862f4e195c908"
+      "sha256": "f13bd014e6a89aefd27dbfbaf639b7c3f3e8b90c3adb69cedfb6a0b11b0d3daf"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4057,7 +4062,7 @@
     {
       "path": "modules/dev-box/app/src/vendor/bongos-client.cjs",
       "mode": "0000644",
-      "sha256": "17753bb744e592f7d7871d33399536d9938b1b7d6c6249959bcbb4355688b557"
+      "sha256": "33fbbbaf2a4a939b7351a7aa25264ddd609c1298d9ba809372a162983afe5038"
     },
     {
       "path": "modules/dev-box/app/test/unit.mjs",
@@ -5467,12 +5472,12 @@
     {
       "path": "modules/lifecycle/db-versions.js",
       "mode": "0000644",
-      "sha256": "aa98bd22cf237579b065a9a85cb64dda30a0b6b9894ebc5d6ca0592bbb7a977f"
+      "sha256": "9f777643c44ebeef8b668a8120bf74d369564f904b2cb1aff54711bd5825c9c5"
     },
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "e7f65fbc43a0963ab6a7e6d25e0b52521f46b82f05115ffef80ea64d9e9fac81"
+      "sha256": "c6ab8ace534687d1989e4b192809a373294e539f7fb8624f512fda4ceea884ba"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5704,10 +5709,15 @@
       "mode": "0000644",
       "sha256": "366cb9c60952539ab8a946f8cf757754163b6cd6764a6430777b4529c86c6a75"
     },
+    {
+      "path": "modules/lifecycle/routes/version-route-authz.js",
+      "mode": "0000644",
+      "sha256": "5db4f94ca52f634f41cdb489572e43eb6785744220d2565a716cff47bfa72b30"
+    },
     {
       "path": "modules/lifecycle/routes/versions.js",
       "mode": "0000644",
-      "sha256": "77183a22af7bd1f506f2b3d2cba176e89af578ce5aa2da6abe0ee353e3ec8cbd"
+      "sha256": "a825191c1ef406ec4c0eb9455df5b65c5ecf25e23d2b9a9f78eeeae424fa2bf6"
     },
     {
       "path": "modules/lifecycle/routes/visuals.js",
@@ -5904,6 +5914,11 @@
       "mode": "0000644",
       "sha256": "2eb5577450d3bc1d67b7eab9a13256889aca945c6ac6a6a0ca919e195952b7a1"
     },
+    {
+      "path": "modules/platform-identity/invite-suggestions.js",
+      "mode": "0000644",
+      "sha256": "4fc8c9642e415b3dd0bc69968f6870fa9239f67f5cd5e93a301a9d8b53bd5c61"
+    },
     {
       "path": "modules/platform-identity/migrations/platform_identity_001_tables.sql",
       "mode": "0000644",
@@ -6072,7 +6087,7 @@
     {
       "path": "modules/platform-identity/routes/sso.js",
       "mode": "0000644",
-      "sha256": "6f89a384bfe46027ac330324b933255c2d55764b53df0c06571ecfbce6b98c23"
+      "sha256": "dbc8eeab6b1911b7fdc8b29e3d10871d355d2dead926a0742e9a816a72215dba"
     },
     {
       "path": "modules/platform-identity/scouting-authz.js",
@@ -6217,7 +6232,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "c6cfd3a1d0b4f39c4d23d65e1587ec50276aa4180ab48c520b4c22fdb6cf0a6c"
+      "sha256": "60c583e1ae977c85575709abf74af7d0dc5147788509f11d1b26cad459d7b4cf"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -6472,7 +6487,7 @@
     {
       "path": "modules/public-landing/public/assets/cosmos.css",
       "mode": "0000644",
-      "sha256": "0560e91405dabceb22a898ca73ef1830b28ad3e45b0da36ee4ffef770303c1f2"
+      "sha256": "51dc6eac59a85e24336597e554e84c7e76294e389b443cc40dd4e75b1684079d"
     },
     {
       "path": "modules/public-landing/public/assets/verro-medallion.png",
@@ -6732,7 +6747,7 @@
     {
       "path": "modules/public-landing/public/projects.html",
       "mode": "0000644",
-      "sha256": "1a7ba9243c257e767520aae6a164bf9730cd7834d6b1c9bc63c8202a2e711599"
+      "sha256": "edc38e4ae7859c1dfc5422a4a0351c10f31cf119cab878dae0e25461c6121578"
     },
     {
       "path": "modules/public-landing/public/projects.probes.json",
@@ -7477,12 +7492,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "c9fb4551642e3a6cdd1db0e7795805314e2a62b413eb96d2b6ee981146d666c3"
+      "sha256": "feb9b3919e27637f41f78010f3a31d662da752e2c3ea56555f919fae02758cff"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fe6556a8d666ce01124d6666fd07d7ad01920fe596ca3718398fb4bbcc885465"
+      "sha256": "29c0dd946891112260ed3da3ce17b036afa8019a9ca8a89defc4c291b7638d2e"
     },
     {
       "path": "public-docs/index.html",
@@ -9182,7 +9197,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "c08cf2ff080e74afdd1c88cb06f4960909b4984bc803f6eeddab57abe14fed79"
+      "sha256": "51c39233a591b55aa092d440634e57ef51840118b5e7d9d93784b9a6de502b29"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11304,6 +11319,11 @@
       "mode": "0000644",
       "sha256": "f4da7e663ab6d7b93bb02ecefd18178fa654a314da07108c4316317f50115ad0"
     },
+    {
+      "path": "tests/one_planning_version.mjs",
+      "mode": "0000644",
+      "sha256": "1f8c6924dac2c922a1f88c22693b4386ec16d5f0ae346609b3d1dc0003308a70"
+    },
     {
       "path": "tests/orphaned_claim_ship.mjs",
       "mode": "0000644",
@@ -11469,10 +11489,15 @@
       "mode": "0000644",
       "sha256": "743436b1191353bf687d8fb553d423a6003707a25a548367644928478569f171"
     },
+    {
+      "path": "tests/project_invite_suggestions.mjs",
+      "mode": "0000644",
+      "sha256": "df1c61d6db69675d979b2a053e8771a977064283280a5cc04acddb25c801def4"
+    },
     {
       "path": "tests/project_invite_ui.mjs",
       "mode": "0000644",
-      "sha256": "288ee2d4d736c8481d459a902e1d5ba02f823685ee4c42c8c22cce76dcf94918"
+      "sha256": "36a7ff3e5b8c4b9edd495d8a7e5b50dcecded8e608f148a62b4e37841c0eb36a"
     },
     {
       "path": "tests/project_join_door.mjs",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 356 operations across 55 resource groups
+- 357 operations across 55 resource groups
 
 ## Install
 

package/clients/bongos-client/bongos-client.global.js

@@ -677,6 +677,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
+      // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
+      getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
       // POST /provisioning/instances/{id}/restart — rank: any-builder — POST /provisioning/instances/:id/restart
       postProvisioningInstancesIdRestart: (args) => request("POST", "/provisioning/instances/{id}/restart", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/settings — rank: any-builder — GET /provisioning/instances/:id/settings

package/clients/bongos-client/index.cjs

@@ -676,6 +676,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
+      // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
+      getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
       // POST /provisioning/instances/{id}/restart — rank: any-builder — POST /provisioning/instances/:id/restart
       postProvisioningInstancesIdRestart: (args) => request("POST", "/provisioning/instances/{id}/restart", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/settings — rank: any-builder — GET /provisioning/instances/:id/settings

package/clients/bongos-client/index.d.ts

@@ -95,6 +95,7 @@ export interface GetProjectsResponse { projects: unknown }
 export interface GetProvisioningFleetResponse { instances: unknown }
 export interface GetProvisioningGithubAppStatusResponse { ok: boolean; status: unknown; ready: unknown; terminal: unknown; domain: unknown; instance_status: unknown; app_slug: unknown }
 export interface GetProvisioningHealthResponse { module: unknown; ok: boolean; coreVersion: unknown }
+export interface GetProvisioningInstancesIdInviteSuggestionsResponse { suggested: unknown; seeking: unknown; reason: unknown; unavailable?: unknown }
 export interface GetProvisioningInstancesIdResponse { instance: unknown; open_intent: unknown; github_app: unknown }
 export interface GetProvisioningInstancesIdSettingsResponse { ok: boolean; settings: unknown; planet: unknown; options: unknown }
 export interface GetProvisioningInstancesResponse { instances: unknown }
@@ -1000,6 +1001,8 @@ export interface BongosClient {
     postProvisioningInstancesIdForceTeardown(args?: RequestArgs): Promise<PostProvisioningInstancesIdForceTeardownResponse>;
     /** POST /provisioning/instances/{id}/github-app — rank: any-builder */
     postProvisioningInstancesIdGithubApp(args?: RequestArgs & { body?: PostProvisioningInstancesIdGithubAppRequest }): Promise<PostProvisioningInstancesIdGithubAppResponse>;
+    /** GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder */
+    getProvisioningInstancesIdInviteSuggestions(args?: RequestArgs): Promise<GetProvisioningInstancesIdInviteSuggestionsResponse>;
     /** POST /provisioning/instances/{id}/restart — rank: any-builder */
     postProvisioningInstancesIdRestart(args?: RequestArgs): Promise<PostProvisioningInstancesIdRestartResponse>;
     /** GET /provisioning/instances/{id}/settings — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -673,6 +673,8 @@ export function createClient(opts = {}) {
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
+      // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
+      getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
       // POST /provisioning/instances/{id}/restart — rank: any-builder — POST /provisioning/instances/:id/restart
       postProvisioningInstancesIdRestart: (args) => request("POST", "/provisioning/instances/{id}/restart", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/settings — rank: any-builder — GET /provisioning/instances/:id/settings

package/docs/adr/0251-a-suggestion-of-who-to-invite-is-a-recruiting-surface-and-owes-the-opt-out.md

@@ -0,0 +1,79 @@
+# ADR 0251 — A suggestion of who to invite is a recruiting surface, and owes the recruiting opt-out
+
+- **Status:** accepted
+- **Date:** 2026-09-06
+- **Task:** [task 1002347](https://cloudbongos.com/builders#/task/1002347) (BONGOS-V1, goal 1000046 — *Project creation*, criterion `proj-invite-builders` / C6), BV1.R28
+- **Deciders:** Claude, under the Archon's standing scope
+- **Depends on:** [ADR 0239](<redacted>.md) §6 (the seam this fills: the engine emits `invites.seeking` and names R28 as its reader) · [ADR 0249](<redacted>.md) (the widget these names arrive in, and its "only door in" rule) · [ADR 0083](<redacted>.md) (the one-way import rule that makes this a port)
+- **Related:** [ADR 0210](<redacted>.md) (the `/scouting` gate this route deliberately does **not** reuse) · [ADR 0248](<redacted>.md) (the ownership fact the invite route already admits on) · [ADR 0016](<redacted>.md) (a surface never re-derives a server rule)
+
+---
+
+## Context
+
+[ADR 0239](<redacted>.md) §6 left one recommendation deliberately unfinished. The creation wizard's rule engine emits, per team shape, a **seek** rather than a list:
+
+```
+solo        → seeking: null                              ("suggest nobody", a real answer)
+small-team  → seeking: { kind: 'top-builders', limit: 3 }
+community   → seeking: { kind: 'top-builders', limit: 5 }
+```
+
+`invites.suggested` is always `[]` there, and a test pins that emptiness as a decision rather than a gap. The engine is a pure file that may run no query; ranking builders is a directory read; and `provisioning` may not import a sibling module. So the engine states *what to look for* and R28 — this ADR — turns it into names.
+
+That leaves one genuinely open question, and it is not an architectural one: **which directory?**
+
+## The decision that matters: the recruiting directory, not the leaderboard
+
+Two readers could answer "who are the top builders", and they differ by exactly one SQL predicate:
+
+| reader | lives in | consent |
+|---|---|---|
+| `leaderboard()` | `economy` | joins `rollupVisibleSql` — **honours no recruiting opt-out**, on purpose |
+| `listScoutingRollup()` | `platform-identity` | joins `scoutingListableSql` — **the opt-out is inside the query** |
+
+The leaderboard is the cheaper answer in every mechanical sense: it is an explicitly public read route, it needs no port, and a browser could call it directly with no new server code at all.
+
+**We use the scouting rollup anyway, because the opt-out means this exact screen.** `account-visibility.js` states the split in its own words — `hide_stats` suppresses *numbers* everywhere, while the recruiting opt-out "removes an account from the RECRUITING SURFACE only", and the community spec's D3 says the opt-out "does not affect leaderboards; it governs the recruiting surface only". A list of people the platform is proposing you recruit into your project **is** the recruiting surface. Sourcing it from the leaderboard would not be a shortcut around some incidental gate; it would route around the one control that exists for precisely this case, and hand an owner the name of every builder who asked not to be recruited.
+
+The rule this fixes for later readers: **the cheapness of a public read is not an argument about who consented to appear in it.** `listScoutingRollup`'s own header already warns in the other direction ("a public LEADERBOARD must not reuse this reader"); this is the same boundary approached from the other side.
+
+## Where the lookup lives, and why it is a port
+
+`modules/platform-identity` gets a new function, `listInviteSuggestions`, exposed on the existing `platform-identity.hub` port. `modules/provisioning` reaches it with `resolveOptional` — the `catalog-bridge.js` precedent, and **not** declared in `consumes`: platform-identity is hub-only (`default: false`), so an instance running provisioning without it has no directory to ask and the honest answer is "no suggestions", never a 500.
+
+Two things are enforced inside the module rather than asked of callers:
+
+1. **`github_id` does not cross the port.** The projection is an explicit whitelist — login, display name, avatar, disciplines, and two counts. The invite route takes a *login*; the id names someone who has accepted nothing, and the surface already has a test forbidding it on screen. An explicit whitelist also means a new column on the rollup cannot leak by default.
+2. **The exclusion is applied inside.** A caller passes the ids to drop (in practice the owner's own) and gets back rows with no ids in them, so dropping yourself from your own list never requires holding one. The read is over-fetched by the exclusion count so filtering can never return short of the limit.
+
+## The gate is the one that already exists
+
+`GET /provisioning/instances/:id/invite-suggestions` is own-scoped by `instanceAccessDenied` — the same gate, and the same **404**, as the manage-page read beside it.
+
+It deliberately does **not** reuse `/scouting`'s gate (`project.curate` or a hub-witnessed `membership_kind='owner'`). A brand-new owner has no witnessed owner-membership row at the moment the done panel paints — that row is written later, by the child instance at SSO check-in — so the correct-looking gate would refuse the exact caller the feature exists for.
+
+Reaching this route **is** the ownership answer ([ADR 0249](<redacted>.md) §4), so the surface re-derives nothing and cannot become a weaker second copy of a server rule ([ADR 0016](<redacted>.md)). 404 rather than 403 keeps it leaking no more instance existence than its neighbour.
+
+## What the surface does with the answer
+
+The widget keeps its shape from [ADR 0249](<redacted>.md): it still answers neither "is anyone signed in" nor "is this their project", and gains a **second door in** (`setInviteSuggestions`) beside `setInviteSlug` rather than learning to fetch for itself.
+
+- **The reason is always said, including when the answer is nobody.** `seeking: null` returns its own sentence and never touches the directory. A solo owner is suggested nobody *on purpose*, and rendering that as an empty list would turn a stated answer into what looks like a failed lookup.
+- **A picked name takes the same write path as a typed one** — it fills the field and calls `doInvite`. One write path means the refusal vocabulary, the busy guard and the pending receipt cannot drift into a second copy.
+- **A filed invite stops being a suggestion.** The pending line is its receipt; offering the same person twice invites a refusal the owner cannot act on.
+- **Every failure is silent.** A suggestion is an extra, and a project that was just created successfully must never look broken because an optional directory read did not answer.
+
+## Consequences
+
+- A builder who opted out of recruiting is **absent from suggestions while still ranking on the leaderboard**. That is the opt-out working, not a bug — but it does mean the suggested names and the leaderboard's top names legitimately differ, and anyone comparing the two screens should expect that.
+- Suggestions are **hub-only**. An instance without `platform-identity` gets `unavailable: 'no_directory'` and an empty list; the step still works for typed logins.
+- `invites.suggested` stays `[]` in the pure engine forever. The filling happens one layer out, so ADR 0239's test still passes unchanged and the engine stays I/O-free.
+- Guilds are still out (task 1002348, blocked on goal 1000045). `seeking.kind` is already a discriminator, so a `guilds` kind is an added branch rather than a reshaping.
+
+## Rejected
+
+- **Read the economy leaderboard from the browser.** Cheapest by far and needs no server code — rejected on consent, above. This is the whole decision.
+- **Reuse `GET /scouting`.** The right data behind a gate that refuses the caller this feature is for.
+- **Fill `invites.suggested` inside `recommendationsForDetails`.** Would make a pure, synchronous, dependency-free file do I/O and import a sibling module — the two things ADR 0239 §6 and ADR 0083 respectively forbid.
+- **A `provisioning → economy` port for the leaderboard.** Architecturally legal and still the wrong directory; the boundary was never the objection.

package/docs/adr/README.md

@@ -338,6 +338,7 @@ This keeps the decision history honest and traceable.
 
 | 0249 | [**The invite step is the done panel’s first act, not a rail step — and the same widget is the way back** ([task 1002346](https://cloudbongos.com/builders#/task/1002346) · goal 1000046, criterion `proj-invite-builders` / C6). BV1.R27 asks for a skippable invite step *in creation*, but an invite cannot be one of the wizard’s numbered panels: `POST /projects/invite` takes `{ client_id, github_login }` where `client_id` **is the slug**, and per [ADR 0246](<redacted>.md) the catalog row that slug resolves is projected **at create** — so before the Create step there is nothing to invite anyone to, and a pre-Create panel could only queue names and replay them, inventing a second unaudited invite path whose failures land after the owner has left. **Decision: the step is the FIRST act of the DONE panel**, keyed on the created record (not `instanceId`, which `startProgress` sets only *after* `renderDone`), so it also returns on a resumed watch; the rail is NOT renumbered (a captured learning on this file: a renumbering couples in four places, and a step that can only run after the terminal step is not a step in the rail). The SAME widget is mounted again on the project’s own page beside *Its extras* — the [ADR 0245](<redacted>.md) argument, one implementation and two mounts, so the refusal vocabulary cannot drift. The widget answers neither “is anyone signed in” nor “is this their project”: each call site hands over a slug or nothing (the created record; the own-scoped manage read that 404s for everyone else), because a page that re-derived ownership would be a second, weaker copy of a server rule. **The 403 is quoted carefully and that is the point** — [ADR 0248](<redacted>.md) paid two equalised reads per request to make the refusal identical for a real, stealth, absent or malformed target ([ADR 0182](<redacted>.md) D2a), and “you lack permission on **this project**” would assert in copy the existence the route refuses to confirm, so the page says only “this account can’t invite people here” and a test pins that wording. `account_not_found` and `unknown_project` are said in the route’s own words (the latter as a moment, not a dead end — the row is projected at create); anything else falls through to the server’s own message. The pending line is drawn from the 201 row’s `membership_kind` and the typed login — **never the `github_id`** it carries, which names someone who has accepted nothing yet. Creation is never blocked: the project is filed before the step is shown, so every refusal leaves it created and the step re-tryable, and Skip sends nothing. Rejected: a rail step before or after Create; the manage page alone (R27 asks for it *in creation*); reading the real membership directory back (no own-scoped route exists, and the session receipt is honest about being one).](<redacted>.md) | provisioning / project creation |
 | 0250 | [**Strict versioning — the version boundary is the scope gate** ([task 1003589](https://cloudbongos.com/builders#/task/1003589) · goal 1000086). The work hierarchy ([ADR 0086](<redacted>.md)) has a bottom and no top: tasks close, criteria close, goals close, and a version never does. Measured live — **14 goals reading `achieved`/`archived` while holding 35 unfinished tasks**, 523 open tasks across 37 open goals, and **two versions `building` on one project**; every number was worse than the planning session had recorded two days earlier, which is the argument: the drift is the steady state, not a backlog. The cause is four mechanical gaps, not a social one — `POST /goals` fetches the version row and never reads its `status`; goal achievement is computed from criteria alone and never consults `tasks` (both the `db-goals.js` writer and the `done-when.js` cascade); `POST /goals/:id/archive` checks nothing at all; and no route ships a version, so version status has only ever moved as hand-run SQL on the droplet. **Decision, five rules:** the goal set closes when a version starts `building` (new goals go on the `planning` version — where the next version is scoped in advance) with a named 409 an agent can act on; a goal reaches `achieved` only when its criteria are satisfied **and** no task in it is non-terminal, where terminal is `shipped`|`abandoned` per [task 1003588](https://cloudbongos.com/builders#/task/1003588)'s one vocabulary and the mid-ship `completed`/`confirmed` hold it open; archiving a goal that holds open tasks refuses until the caller dispositions each (abandon with the reason, or move to a named surviving goal); `goal_id` becomes required and the per-version catch-all fallback is deleted; and exactly one version builds per project, auto-closing when its last non-maintenance goal achieves, with the single `planning` version promoting itself so the project is never without a live train. **The escape hatches are deliberate and visible**: an Archon may admit one *named* goal to a building version with a reason, and the overrides are counted on the version (the standard failure of a hard scope gate is a fake hotfix version cut to hold what did not fit — an untraced override is just a slower version of no rule); plus one auto-created maintenance goal per version, exempt from the auto-close count, so bugs never need an override to be filed. **Nothing here can refuse a ship, a claim, or a task** — every rule acts on a *closing* move. Rejected: counting `completed`/`confirmed` as finished (they can fail a grade or strand — the goals **board** buckets them as done, but that is a progress ring, and `task-status.js` keeps the two questions apart); a nightly reconciler that reopens wrongly-closed goals (detection is what you build when prevention is unavailable, and it is available here); a human review gate before a goal may close (the queue [ADR 0183](<redacted>.md) dismantled — the check is a fact the table already holds); concurrent building versions scoped by module (two live trains means every "what is in this version" question has two answers); retiring versions entirely (the version is the unit the owner sets scope in and `limitations/<version>-shipped.md` archives). **Amends [ADR 0157](<redacted>.md) for exactly one key:** `version.create` returns to the Archon floor. 0157's "authoring delegates, disposition does not" was right about what a version *was* — but once the boundary carries the scope gate, cutting a new version is no longer authoring, it is the way *around* the gate, so create joins close as a disposition over scope.](<redacted>.md) | lifecycle / versioning / scope |
+| 0251 | [**A suggestion of who to invite is a recruiting surface, and owes the recruiting opt-out** ([task 1002347](https://cloudbongos.com/builders#/task/1002347) · goal 1000046, criterion `proj-invite-builders` / C6). BV1.R28 fills the seam [ADR 0239](<redacted>.md) §6 left open: the wizard’s pure rule engine emits a **seek** (`solo` → `null`, `small-team` → 3, `community` → 5) and never a list, because ranking builders is a directory read a pure file may not run and `provisioning` may not import a sibling. Two readers could answer “who are the top builders” and they differ by **one SQL predicate**: `economy`’s `leaderboard()` joins `rollupVisibleSql` and deliberately honours **no** recruiting opt-out, while `platform-identity`’s `listScoutingRollup()` joins `scoutingListableSql`, which carries it. The leaderboard is cheaper in every mechanical sense — already a public route, no port, callable straight from the browser. **Decision: use the recruiting directory anyway**, because `account-visibility.js` says the split in its own words (`hide_stats` suppresses *numbers* everywhere; the recruiting opt-out “removes an account from the RECRUITING SURFACE only”, community spec D3), and a list of people the platform proposes you recruit **is** that surface — sourcing it from the leaderboard would route around the one control built for this exact case and name every builder who asked not to be recruited. The rule for later readers: **the cheapness of a public read is not an argument about who consented to appear in it.** The lookup ships as `listInviteSuggestions` on the existing `platform-identity.hub` port, reached with `resolveOptional` and NOT declared in `consumes` (the `catalog-bridge.js` precedent — platform-identity is hub-only, so its absence is “no suggestions”, never a 500); `github_id` **does not cross the port** (explicit whitelist — login, display name, avatar, disciplines, two counts — so a new rollup column cannot leak by default), and the owner-exclusion is applied inside, over-read by the exclusion count so filtering never returns short. The route `GET /provisioning/instances/:id/invite-suggestions` is own-scoped by the **existing** `instanceAccessDenied` (same 404 as the manage read) and deliberately does NOT reuse `/scouting`’s gate ([ADR 0210](<redacted>.md)): a brand-new owner has no hub-witnessed owner row at the moment the done panel paints, so the correct-looking gate would refuse the exact caller the feature exists for — and reaching the route IS the ownership answer ([ADR 0249](<redacted>.md) §4). On the surface: a **second door in** (`setInviteSuggestions`) beside `setInviteSlug`, so the widget still answers neither “signed in” nor “theirs”; the reason is **always** said including when the answer is nobody (`seeking: null` costs no query — rendering a stated answer as an empty list would make it look like a failed lookup); a picked name fills the field and takes the **same write path** as a typed one, so the refusal vocabulary cannot fork; a filed invite stops being a suggestion; and every failure is silent, because a suggestion is an extra and a just-created project must not look broken over one. Rejected: the browser reading the economy leaderboard (the whole decision — consent, not architecture); reusing `/scouting` (right data, gate that refuses this caller); filling `invites.suggested` inside the engine (I/O in a pure file + a sibling import); a `provisioning → economy` port (legal, still the wrong directory — the boundary was never the objection).](<redacted>.md) | provisioning / platform-identity / privacy |
 
 | 0246 | [**Catalog membership is a projection of the provisioning row, not a side effect of federation** ([task 1003576](https://cloudbongos.com/builders#/task/1003576) · goal 1000046, criterion `proj-detail-interview` / C3). The BV1.R18 proof ([task 1002337](https://cloudbongos.com/builders#/task/1002337)) demonstrated C3 against live and found its last clause — “then it publishes” — structurally false: the owner’s verdict reads `provisioning_instances` while the public map reads `platform_identity_projects`, and the ONLY bridge was `federateInstance → registerClient → upsertProject`, which `shouldFederate` refuses for anything but `co-tenant` (the wizard hard-codes `standalone`) and which runs ONCE, at provision time, through a COALESCE. So a wizard-made project was never catalogued at all and a co-tenant one that answered later never updated — `publishable: true`, `{"projects": []}`, forever. The same missing row is [task 1003580](https://cloudbongos.com/builders#/task/1003580)’s GAP 1: `POST /projects/invite` resolves against `platform_identity_sso_clients`, whose only writer is that same `registerClient`. Underneath is one conflation — federation mints CREDENTIALS and was incidentally the only thing that minted MEMBERSHIP, while [ADR 0182](<redacted>.md) D4 already fixed the map’s gate at IDENTITY, which has nothing to do with hosting topology. **Decision: the catalog row is a PROJECTION of the provisioning row, re-derived at every write that can change its inputs** — two halves, neither sufficient alone. (1) THE ROW SHAPE: every control-plane project gets both rows whatever its hosting shape, and the client row carries NO credential (`secret_hash = ''`, `redirect_uris = '{}'`), so **the shape is the enforcement** rather than a flag a caller could forget — `redirectUriAllowed` refuses `/sso/authorize`, `clientSecretValid` refuses `/sso/token`, `/sso/membership/check-in` and `/sso/activity/rollup`, and the one leg that checked NEITHER (`/sso/device/start`, which resolves a client from a user-typed origin) grew an explicit `clientIsCredentialed` guard. (2) THE TIMING: re-taken on create, on `PATCH …/detail`, on `PATCH …/settings` when the door changes, and on `POST …/domain` (which re-keys the row, retiring the abandoned origin — [ADR 0181](0181-teardown-state-gate-and-address-retention.md) §2’s leak, in the catalog instead of DNS). **NO MIGRATION** — `secret_hash` is `NOT NULL` and `''` satisfies it while hashing to nothing. `description` and `visibility` are ASSIGNED, not COALESCEd (clearing a description must UN-publish); `featured`/`tagline`/`art_url`/`template` are curation and stay untouched, so [ADR 0182](<redacted>.md) D3 holds. It grants nothing — the row is attribution per [ADR 0238](<redacted>.md), ownership stays `provisioning_instances.owner_builder_id` — and because it writes rows keyed on owner-supplied values (a slug, a BYO domain) each write carries its **claim rule in the ON CONFLICT action’s own WHERE**: the client is refreshed only `WHERE secret_hash = ''` (a real client’s origin, which binds the CLI mint audience, can never be rewritten) and the project only `WHERE owner_github_id = EXCLUDED.owner_github_id` (`NULL = anything` is not true, so the hand-seeded rows cannot be claimed). Writing `visibility` does not contradict [ADR 0182](<redacted>.md) D5: the hub authorizes nothing — the authority already ran on the provisioning plane ([ADR 0238](<redacted>.md)’s own-scoped, audited PATCH), and a project the control plane does NOT own has no provisioning row, so D5’s instance report (R08) stays the only channel for those. `tearing_down`/`torn_down` project `hidden`; a `no_address` instance is not catalogued at all. Travels on the kernel port `project.catalog`, the `project.publishGate` seam in the other direction ([ADR 0083](<redacted>.md) forbids the import). Rejected: extending `shouldFederate` to every shape (hands a real secret to instances whose web.env the platform does not write, and keeps the once-at-standup bug); bridging only at the publish moment (leaves the invite with nothing to resolve); registering only at standup (the bug itself); a `catalog_only` boolean column (needs a migration and is weaker than the shape); letting the bridge write `featured`; and backfilling the three existing catalog rows from code.](<redacted>.md) | provisioning / project creation |
 

package/docs/api/openapi.json

@@ -11785,6 +11785,58 @@
         ]
       }
     },
+    "/provisioning/instances/{id}/invite-suggestions": {
+      "get": {
+        "operationId": "get_provisioning_instances_id_invite_suggestions",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/instances/:id/invite-suggestions",
+        "description": "── Who is worth inviting (BV1.R28, task 1002347, goal 1000046 C6) ──────── GET /provisioning/instances/:id/invite-suggestions — turn the engine's `invites.seeking` into NAMES. ADR 0239 §6 left `invites.suggested` empty on purpose: ranking builders is a directory read the pure engine may not run. This is the resolution, and ADR 0251 is why it looks like this. rank: any authenticated builder, own resource — `instanceAccessDenied`, the same gate and the same 404 as the manage read above. That is deliberate and not a new authorization idea: REACHING this route IS the ownership answer (ADR 0249 §4), so the surface never re-derives \"is this theirs\" and can never become a weaker second copy of a server rule (ADR 0016). It also 404s rather than 403s, so it leaks no more instance existence than the read beside it. `seeking: null` COSTS NOTHING AND ASKS NOBODY. A solo owner is suggested nobody on purpose (ADR 0239 §6), which is a different statement from an empty list nobody filled — so that answer returns its own reason and never touches the directory at all.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.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/GetProvisioningInstancesIdInviteSuggestionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/instances/{id}/restart": {
       "post": {
         "operationId": "post_provisioning_instances_id_restart",
@@ -17447,6 +17499,20 @@
           "coreVersion"
         ]
       },
+      "GetProvisioningInstancesIdInviteSuggestionsResponse": {
+        "type": "object",
+        "properties": {
+          "suggested": {},
+          "seeking": {},
+          "reason": {},
+          "unavailable": {}
+        },
+        "required": [
+          "suggested",
+          "seeking",
+          "reason"
+        ]
+      },
       "GetProvisioningInstancesIdResponse": {
         "type": "object",
         "properties": {
@@ -22439,9 +22505,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 356,
-  "x-schema-count": 390,
+  "x-endpoint-count": 357,
+  "x-schema-count": 391,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 264,
+  "x-response-schemas": 265,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 356 endpoints across 58 route files.
+> **Generated from the live route files** — the route file is authoritative. 357 endpoints across 58 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`.
@@ -459,7 +459,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: invite a builder into a project (ADR 0141 §5, task #1002115), called by a `project.curate` holder OR the project'… |
 
-## `provisioning` (21)
+## `provisioning` (22)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -475,6 +475,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/provisioning/instances/:id/domain` | `any-builder` | `domain` | POST /provisioning/instances/:id/domain — give the caller's OWN instance its address (task 1002692, gap 5: no path existed to add a domai… |
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `metic+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… |
+| GET | `/api/bongos/provisioning/instances/:id/invite-suggestions` | `any-builder` | — | ── Who is worth inviting (BV1.R28, task 1002347, goal 1000046 C6) ──────── GET /provisioning/instances/:id/invite-suggestions — turn the … |
 | POST | `/api/bongos/provisioning/instances/:id/restart` | `any-builder` | — | POST /provisioning/instances/:id/restart — restart an ACTIVE project the heartbeat cannot reach (task 1003238). |
 | GET | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | — | GET /provisioning/instances/:id/settings — read a project's effective settings + the allowed values (so a form can render its choices). |
 | PATCH | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | validated | PATCH /provisioning/instances/:id/settings — change a project's settings. |