@bongos/core 1.25.16 → 1.25.18

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 719 endpoints across 121 route files.
+> **Generated from the live route files** — the route file is authoritative. 729 endpoints across 124 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -66,6 +66,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/analytics/builder/:id` | `any-builder` | — | a builder's historical AI dev curve. |
 
+## `app-host` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/app-host` | `any-builder` | — | GET /app-host — rank: any signed-in builder; owner-only parts gated on core.pin.move. |
+
 ## `artist-gate` (1)
 
 | Method | Path | Rank | Body | Description |
@@ -315,6 +321,18 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/feedback/receipt` | `any-builder` | `sha256`, `kind` | signed-in builder — a receipt only says "this builder sent this text"; it grants nothing here, and the hub files every report behind a nod. |
 | GET | `/api/bongos/feedback/receipt/:id` | `public` | — | the hub redeems a receipt with no session of its own. |
 
+## `first-read` (7)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/first-read/catalog` | `any-builder` | — | the modules this project can switch on, the only ones a map may recommend. |
+| POST | `/api/bongos/first-read/maps` | `metic+archon` | `map` | .create — a map is a planning proposal for this project. |
+| GET | `/api/bongos/first-read/maps/:id` | `metic+archon` | — | .create — the review is for whoever may accept or reject it. |
+| POST | `/api/bongos/first-read/maps/:id/accept` | `metic+archon` | `all`, `items` | .create + act-alone planning — the owner's yes. |
+| POST | `/api/bongos/first-read/maps/:id/dismiss` | `metic+archon` | `items` | .create — the owner's no to named items (a module recommendation, usually). |
+| POST | `/api/bongos/first-read/maps/:id/reject` | `metic+archon` | — | .create — the owner's no. |
+| GET | `/api/bongos/first-read/prompt` | `any-builder` | — | the prompt and the shape are instructions, not project data. |
+
 ## `founding` (18)
 
 | Method | Path | Rank | Body | Description |
@@ -850,7 +868,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 100… |
 | POST | `/api/bongos/projects/invite-guild` | `metic+archon` | `client_id`, `guild` | own-or-metic in effect, the SAME gate as POST /projects/invite above and for the same reasons (a non-inviter gets that route's unchanged … |
 
-## `provisioning` (47)
+## `provisioning` (48)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -886,6 +904,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/provisioning/instances/:id/look` | `any-builder` | `look`, `night_tint`, `accent` | PATCH — rank: any authenticated builder (own resource; archon may change any). |
 | GET | `/api/bongos/provisioning/instances/:id/render` | `any-builder` | — | GET /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER ONLY, like the POST (task 1004353). |
 | POST | `/api/bongos/provisioning/instances/:id/render` | `any-builder` | `key`, `owner_id`, `mode`, `service_id`, `web_plan`, `db_plan`, `region`, `runtime`, `build_command`, `start_command`, `database` | POST /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER ONLY: the key is the owner's and so is the account i… |
+| POST | `/api/bongos/provisioning/instances/:id/render/sandbox` | `any-builder` | `key` | POST /provisioning/instances/:id/render/sandbox — rank: any authenticated builder, and OWNER ONLY, like every Render route. |
 | POST | `/api/bongos/provisioning/instances/:id/repo-private` | `any-builder` | validated | POST /provisioning/instances/:id/repo-private — rank: any authenticated builder, and OWNER ONLY: no archon override, because the runner f… |
 | 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). |
@@ -1030,11 +1049,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/specialities/installed-skills` | `any-builder` | — | GET /specialities/installed-skills — every skill THIS instance has, each explained the way the adoption walkthrough explains it, so a spe… |
 | GET | `/api/bongos/specialities/offered` | `any-builder` | — | GET /specialities/offered — the suggestions for THIS builder. |
 
-## `sso` (12)
+## `sso` (13)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | POST | `/api/bongos/sso/activity/rollup` | `public` | `client_id`, `client_secret`, `github_id`, `credits`, `tasks_shipped`, `karma`, `rank`, `disciplines`, `recent_ships`, `crafts` | POST /sso/activity/rollup — a federated instance reports a builder's activity snapshot (ADR 0141 §4). |
+| POST | `/api/bongos/sso/app-status` | `public` | `client_id`, `client_secret` | authenticated by client_id + client_secret, not a builder rank. |
 | POST | `/api/bongos/sso/applicant-profile` | `public` | `client_id`, `client_secret`, `github_id` | POST /sso/applicant-profile — a federated instance resolves ONE applicant's profile view for its own reviewer queue, LIVE at render (priv… |
 | 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. |