@bongos/core 1.19.1081 → 1.20.1

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 440 endpoints across 76 route files.
+> **Generated from the live route files** — the route file is authoritative. 454 endpoints across 81 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`.
@@ -255,6 +255,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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. |
 
+## `goal-task-relevance` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/goal-task-relevance/:id/decide` | `metic+archon` | `decision`, `note` | task.promote — same atom as the read (task.promote's own gate). |
+| GET | `/api/bongos/goal-task-relevance/pending` | `metic+archon` | — | task.promote (metic+archon) — the reused review-queue atom. |
+
 ## `goals` (33)
 
 | Method | Path | Rank | Body | Description |
@@ -372,7 +379,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/inbox/:id/body` | `any-builder` | `body_md` | Metic+ (task 360 / ADR 0018): idea triage (promote/discard/merge) shapes the backlog. |
 | POST | `/api/bongos/inbox/:id/develop` | `any-builder` | `field_values`, `template_key`, `recommendation` | POST /inbox/:id/develop — DEVELOP A SPARK INTO A FULL IDEA (task 1002922 / BV1.R146, goal 1000062). |
 | POST | `/api/bongos/inbox/:id/ratify` | `metic+archon` | `notes_md` | V3.R31 (task 252) — Archon ratifies a criterion-proposal idea, atomically: - INSERT done_when_criteria row on the target version - UPDATE… |
-| POST | `/api/bongos/inbox/:id/ratify-goal` | `metic+archon` | `target_version`, `scope_modules`, `admit_reason`, `notes_md` | BV2.R17 (task 1004096, spec R23, goal 1000095) — ratify a FULL IDEA into a GOAL, atomically: - INSERT goals (title from the idea, descrip… |
+| POST | `/api/bongos/inbox/:id/ratify-goal` | `metic+archon` | `target_version`, `scope_modules`, `admit_reason`, `notes_md`, `success_criterion` | BV2.R17 (task 1004096, spec R23, goal 1000095) — ratify a FULL IDEA into a GOAL, atomically: - INSERT goals (title from the idea, descrip… |
 | POST | `/api/bongos/inbox/:id/resubmit` | `any-builder` | `field_values`, `template_key`, `recommendation` | RESUBMIT a Full Idea after a rejection (R13 of goal 1000069, criterion C2: an idea never dies and never stalls). |
 | POST | `/api/bongos/inbox/:id/spark` | `any-builder` | — | Mark a Quick Idea as a Big Idea Spark — "I have the spark but not the full picture, someone develop this". |
 | DELETE | `/api/bongos/inbox/:id/spark` | `any-builder` | — | Withdraw the Big Idea Spark mark — the reversibility half of R144. |
@@ -499,10 +506,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/my-projects/invites/:clientId/decline` | `any-builder` | — | decline an invite (delete the pending row) for the caller's OWN account. |
 | POST | `/api/bongos/my-projects/join` | `any-builder` | `origin`, `note` | request to join a project. |
 
-## `npm-release` (2)
+## `npm-release` (7)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/npm-release/preview` | `any-builder` | — |  |
+| POST | `/api/bongos/npm-release/preview` | `any-builder` | `version` |  |
+| DELETE | `/api/bongos/npm-release/preview` | `any-builder` | — |  |
+| GET | `/api/bongos/npm-release/preview/enter` | `any-builder` | — |  |
+| GET | `/api/bongos/npm-release/preview/exit` | `any-builder` | — |  |
 | GET | `/api/bongos/npm-release/task/:id` | `any-builder` | — |  |
 | GET | `/api/bongos/npm-release/work` | `archon` | — | Query: days (ledger window, default 14, max 60), before + limit (history paging). |
 
@@ -534,11 +546,11 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/projects` | `metic+archon` | `origin`, `name`, `tagline`, `description`, `art_url`, `type`, `template` | create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration). |
 | PATCH | `/api/bongos/projects/:id/featured` | `metic+archon` | `featured` | the feature / unfeature control (the ADR 0141 §5 curation gate), BOUNDED BY THE PUBLISH GATE (ADR 0182 D3, task 1002335). |
 | PATCH | `/api/bongos/projects/:id/status` | `metic+archon` | `status` | THE TAKEDOWN LEVER (R08, task 1002327; ADR 0252 §5.1). |
-| POST | `/api/bongos/projects/:projectId/specialities` | `any-builder` | `name`, `discipline`, `summary`, `contract_md`, `visibility`, `sellable` | POST /projects/:projectId/specialities — author one OWNED BY A PROJECT. |
+| POST | `/api/bongos/projects/:projectId/specialities` | `any-builder` | `name`, `discipline`, `summary`, `contract_md`, `visibility`, `sellable`, `skills` | POST /projects/:projectId/specialities — author one OWNED BY A PROJECT. |
 | 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's… |
 
-## `provisioning` (32)
+## `provisioning` (34)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -563,7 +575,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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/render` | `any-builder` | `key`, `owner_id`, `mode`, `service_id`, `web_plan`, `db_plan`, `region` | POST /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER ONLY: the key is the owner's and so is the account i… |
+| 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/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). |
@@ -571,6 +584,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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&domain=<host> — the CANONICAL onboarding step sequence (task 2085; goal 35 / criteri… |
 | GET | `/api/bongos/provisioning/recommendations` | `public` | — | GET /provisioning/recommendations?type=<project type>&team_shape=<interview answer> — the RULE-BASED recommendation for one set of creati… |
+| POST | `/api/bongos/provisioning/render/lookup` | `any-builder` | `key`, `owner_id` | POST /provisioning/render/lookup — rank: any authenticated builder. |
 | GET | `/api/bongos/provisioning/slug-available` | `any-builder` | — | GET /provisioning/slug-available?slug=<handle> — is this handle free to create under? rank: any authenticated builder (same gate as the c… |
 | GET | `/api/bongos/provisioning/starter-bundles` | `public` | — | GET /provisioning/starter-bundles — the curated module preset for each declared project type (BV1.R19, task 1002338; goal 1000046 criteri… |
 | 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). |
@@ -605,6 +619,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/removal-proposals` | `metic+archon` | — | GET /removal-proposals — the removal questions nobody has answered yet. |
 | POST | `/api/bongos/removal-proposals/:id/decide` | `metic+archon` | `verdict`, `note` | POST /removal-proposals/:id/decide — confirm or dismiss ONE proposal. |
 
+## `render-deploy` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/render-deploy/act` | `archon` | `action`, `deployId`, `confirm`, `expectLiveDeployId` |  |
+| GET | `/api/bongos/render-deploy/app` | `archon` | — |  |
+| PUT | `/api/bongos/render-deploy/app` | `archon` | `ownerId`, `serviceId` |  |
+| GET | `/api/bongos/render-deploy/history` | `archon` | — |  |
+
 ## `scouting` (2)
 
 | Method | Path | Rank | Body | Description |
@@ -665,20 +688,21 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/software-update` | `any-builder` | — | GET /software-update — Settings → Software update (task 1004296): this project's core, the newest release its channel allows, what the ve… |
 
-## `specialities` (12)
+## `specialities` (13)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/specialities` | `any-builder` | — | GET /specialities — the catalogue this builder may see. |
-| POST | `/api/bongos/specialities` | `any-builder` | `name`, `discipline`, `summary`, `contract_md`, `visibility`, `sellable` | POST /specialities — author one for YOURSELF. |
+| POST | `/api/bongos/specialities` | `any-builder` | `name`, `discipline`, `summary`, `contract_md`, `visibility`, `sellable`, `skills` | POST /specialities — author one for YOURSELF. |
 | GET | `/api/bongos/specialities/:id` | `any-builder` | — |  |
-| PATCH | `/api/bongos/specialities/:id` | `any-builder` | `name`, `summary`, `contract_md`, `visibility`, `sellable` | PATCH — owner only. |
+| PATCH | `/api/bongos/specialities/:id` | `any-builder` | `name`, `summary`, `contract_md`, `visibility`, `sellable`, `skills` | PATCH — owner only. |
 | POST | `/api/bongos/specialities/:id/abandon` | `any-builder` | — |  |
 | POST | `/api/bongos/specialities/:id/adopt` | `any-builder` | — | ── adoption ────────────────────────────────────────────────────────────── |
 | GET | `/api/bongos/specialities/:id/documents` | `any-builder` | — |  |
 | POST | `/api/bongos/specialities/:id/documents` | `any-builder` | `title`, `body_md`, `source` | ── training (a): the owner's own documents ─────────────────────────────── |
 | DELETE | `/api/bongos/specialities/:id/documents/:docId` | `any-builder` | — |  |
 | POST | `/api/bongos/specialities/:id/offer` | `metic+archon` | — | ── offering: a project puts its name behind a speciality ───────────────── OFFERING IS CURATION, NOT OWNERSHIP, so it is gated differentl… |
+| PUT | `/api/bongos/specialities/:id/skills` | `any-builder` | `enabled_skills` | PUT /specialities/:id/skills — the caller's ENABLED set for a speciality they hold (task 1004072, ADR 0310 §2). |
 | POST | `/api/bongos/specialities/:id/unoffer` | `metic+archon` | — |  |
 | GET | `/api/bongos/specialities/offered` | `any-builder` | — | GET /specialities/offered — the suggestions for THIS builder. |
 

package/docs/architecture.md

@@ -108,7 +108,8 @@ tasks(id, version_id, title, description, status, touches text[], est_minutes, e
       manual_degree, priority, automation_tag, credits_reward, source, source_ref,
       promoted_at, shipped_at, shipped_by, value_summary, created_at, updated_at)
   + visual_url, visual_alt (mig core_223, task 1003109) -- the OPTIONAL ship-time VISUAL: a
-    screenshot / before-after / diagram, stored on disk under var/task-visuals/ and served by
+    screenshot / before-after / diagram, stored on disk under <INSTANCE ROOT>/var/task-visuals/
+    (never inside the installed core package, which every upgrade replaces; task 1004381) and served by
     GET /api/bongos/task-visuals/:name. It is value_summary's claim in another medium, so it
     inherits that summary's audience (public only for shipped|confirmed, and never for a
     security_sensitive task); never required, and nothing on the ship path blocks on it.
@@ -186,7 +187,10 @@ session_pulses(claim_id PK, builder_id, last_pulse_at)  -- heartbeat for stale-c
 task_grades(id, task_id UNIQUE, score NUMERIC(3,1), passed bool, threshold NUMERIC(3,1),
             grader_kind 'auto'|'subagent'|'lars', grader_version, rubric_scores jsonb,
             signals jsonb, notes_md, graded_at)  -- mig 016, one row per task
-grade_attempts(id, task_id, builder_id?, passed bool, score NUMERIC(3,1), attempted_at)
+grade_attempts(id, task_id, builder_id?, passed bool, score NUMERIC(3,1), attempted_at,
+            worker_verdicts jsonb?)  -- worker_verdicts: core_261 (task 1004292), nullable: each round's
+            -- per-worker [{kind, verdict, error, severities[]}], NO prose; written best-effort by applyGrade,
+            -- read by the correlation audit (served as grade.attempts on GET /tasks/:id?include=grade)
             -- mig 064 (6D.6, ADR 0027): APPEND-ONLY, one row per grade run, so
             -- re-grade thrash is countable (task_grades keeps only the latest)
 session_records(id, session_id UNIQUE, builder_id, task_ids bigint[], example_earned,