@bongos/core 1.19.1064 → 1.19.1066

package/docs/api/openapi.json

@@ -4979,6 +4979,37 @@
         ]
       }
     },
+    "/copy-desk/approvals": {
+      "get": {
+        "operationId": "get_copy_desk_approvals",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "GET /copy-desk/approvals",
+        "description": "GET /copy-desk/approvals — every round waiting for its artist, oldest applied first, with its position (\"1 of 2\"), the lines it rewrote (and the ones the applier refused), and where its renders are. Any signed-in builder; `can_decide` says whether the caller may approve or send back.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/copy-desk/flags": {
       "post": {
         "operationId": "post_copy_desk_flags",
@@ -5198,6 +5229,69 @@
         ]
       }
     },
+    "/copy-desk/pages/{pageId}/approve": {
+      "post": {
+        "operationId": "post_copy_desk_pages_pageId_approve",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "POST /copy-desk/pages/:pageId/approve",
+        "description": "------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/approve — the held pass goes on to land. Body: { task_id? } (the round the artist looked at). The port promotes completed -> confirmed with the rewards the hold skipped and nudges the merge; the reconciler lands it otherwise. The count goes up when it ships. 200 approved · 409 not_waiting · 409 round_moved · 403 not_an_artist -------------------------------------------------------------------------\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "parameters": [
+          {
+            "name": "pageId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `pageId`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostCopyDeskPagesPageIdApproveRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostCopyDeskPagesPageIdApproveResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/copy-desk/pages/{pageId}/asks": {
       "post": {
         "operationId": "post_copy_desk_pages_pageId_asks",
@@ -5525,6 +5619,69 @@
         ]
       }
     },
+    "/copy-desk/pages/{pageId}/send-back": {
+      "post": {
+        "operationId": "post_copy_desk_pages_pageId_send_back",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "POST /copy-desk/pages/:pageId/send-back",
+        "description": "------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/send-back — back to the /tweak queue with a note (ADR 0341 D7). Body: { note, task_id? }. The note is one line of at least 10 characters (pages.normalizeSentBackNote). The port appends a page-tweak-sent-back block { at, by, note }, releases any open claim, drops the round's grade row, returns the task to ready and closes the unmerged PR, so the round reads `submitted` again. 200 sent_back · 400 note_too_short / note_too_long · 409 not_waiting · 409 round_moved · 403 not_an_artist -------------------------------------------------------------------------\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "parameters": [
+          {
+            "name": "pageId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `pageId`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostCopyDeskPagesPageIdSendBackRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostCopyDeskPagesPageIdSendBackResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/copy-desk/pages/{pageId}/submit": {
       "post": {
         "operationId": "post_copy_desk_pages_pageId_submit",
@@ -25354,6 +25511,40 @@
           "flag"
         ]
       },
+      "PostCopyDeskPagesPageIdApproveRequest": {
+        "type": "object",
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 20
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostCopyDeskPagesPageIdApproveResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "outcome": {},
+          "page_id": {},
+          "round": {},
+          "status_after": {},
+          "land": {},
+          "next": {}
+        },
+        "required": [
+          "ok",
+          "outcome",
+          "page_id",
+          "round",
+          "status_after",
+          "land",
+          "next"
+        ]
+      },
       "PostCopyDeskPagesPageIdAsksRequest": {
         "type": "object",
         "properties": {
@@ -25390,6 +25581,47 @@
           "merge"
         ]
       },
+      "PostCopyDeskPagesPageIdSendBackRequest": {
+        "type": "object",
+        "properties": {
+          "note": {
+            "type": "string",
+            "minLength": 1
+          },
+          "task_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 20
+          }
+        },
+        "required": [
+          "note"
+        ],
+        "additionalProperties": false
+      },
+      "PostCopyDeskPagesPageIdSendBackResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "outcome": {},
+          "page_id": {},
+          "round": {},
+          "sent_back": {},
+          "pr": {},
+          "next": {}
+        },
+        "required": [
+          "ok",
+          "outcome",
+          "page_id",
+          "round",
+          "sent_back",
+          "pr",
+          "next"
+        ]
+      },
       "PostCopyDeskProposalsRequest": {
         "type": "object",
         "properties": {
@@ -25589,7 +25821,8 @@
           "status_set": {
             "type": "boolean"
           },
-          "recheck": {}
+          "recheck": {},
+          "held_for_artist": {}
         },
         "required": [
           "ok",
@@ -28973,9 +29206,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 457,
-  "x-schema-count": 491,
+  "x-endpoint-count": 460,
+  "x-schema-count": 495,
   "x-undocumented-bodies": 10,
-  "x-response-schemas": 336,
+  "x-response-schemas": 338,
   "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. 457 endpoints across 76 route files.
+> **Generated from the live route files** — the route file is authoritative. 460 endpoints across 76 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`.
@@ -210,21 +210,24 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/connections/requests` | `any-builder` | — | MY pending requests, both directions (own data). |
 | GET | `/api/bongos/connections/suggestions` | `any-builder` | — | "builders you may know" (R21, task 1002297; ADR 0202 D5). |
 
-## `copy-desk` (16)
+## `copy-desk` (19)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/copy-desk/approvals` | `any-builder` | — | GET /copy-desk/approvals — every round waiting for its artist, oldest applied first, with its position ("1 of 2"), the lines it rewrote (… |
 | POST | `/api/bongos/copy-desk/flags` | `any-builder` | `scope`, `surface`, `string_id`, `reason`, `kind` | ------------------------------------------------------------------------- POST /copy-desk/flags — file a flag. |
 | POST | `/api/bongos/copy-desk/flags/:id/close` | `any-builder` | `status`, `resolution_note`, `resolved_task_id` | ------------------------------------------------------------------------- POST /copy-desk/flags/:id/close — resolve or dismiss. |
 | GET | `/api/bongos/copy-desk/next` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/next — the Tweak/CopyWrite Flow's recommendation… |
 | GET | `/api/bongos/copy-desk/pages` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages — every page's status, count and drift, pl… |
 | GET | `/api/bongos/copy-desk/pages/:pageId` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages/:pageId — one page: status, changelog, the… |
+| POST | `/api/bongos/copy-desk/pages/:pageId/approve` | `any-builder` | `task_id` | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/approve — the held pass goes on t… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/asks` | `any-builder` | `reason` | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/asks — ask for a page (task 10043… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/claim` | `any-builder` | validated | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/claim — claim a page's tweak (tas… |
 | GET | `/api/bongos/copy-desk/pages/:pageId/draft` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages/:pageId/draft — what the tweak editor open… |
 | PUT | `/api/bongos/copy-desk/pages/:pageId/draft` | `any-builder` | `reading_hash`, `lines` | ------------------------------------------------------------------------- PUT /copy-desk/pages/:pageId/draft — autosave the artist's draf… |
 | GET | `/api/bongos/copy-desk/pages/:pageId/draft.docx` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages/:pageId/draft.docx — download the page's w… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/draft.docx` | `any-builder` | _undocumented_ | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/draft.docx — upload the Word file… |
+| POST | `/api/bongos/copy-desk/pages/:pageId/send-back` | `any-builder` | `note`, `task_id` | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/send-back — back to the /tweak qu… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/submit` | `any-builder` | validated | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/submit — freeze the draft and que… |
 | POST | `/api/bongos/copy-desk/proposals` | `any-builder` | `string_id`, `proposed_text`, `why`, `file`, `line`, `flag_id` | ------------------------------------------------------------------------- POST /copy-desk/proposals — an artist proposes new wording, and… |
 | GET | `/api/bongos/copy-desk/queue` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/queue — the artist's working list. |

package/docs/branding-contract.md

@@ -36,7 +36,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `repo` | `{ owner, name }` GitHub binding. |
 | `db.database` | DB name Bongos pool connects to when neither `DATABASE_URL` nor `PGHOST`/`PGDATABASE` is set (`src/bongos/pool.js`, ADR 0062 §5). `null` in the neutral starter = **fail loud** rather than silently target a host DB. |
 | `currency` | `{ label, symbol }` — the reward unit label (e.g. "example"). Display only. |
-| `reward` | `{ marginPct, usdPeg, mode }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/0054-session-token-reward-cost-plus.md) + ADR 0146, tasks 2009/1002270): the cost-plus margin percent (default `20`), the example-per-USD peg (default `1`), and `mode` — `"cost-plus-and-estimate"` (default; pay both the per-task author estimate AND the cost-plus session reward) or `"cost-plus-only"` (suppress the per-task estimate payout; the cost-plus session reward is the sole equity reward). A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg, pay both streams). |
+| `reward` | `{ marginPct, usdPeg, mode }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/0054-session-token-reward-cost-plus.md) + ADR 0146, tasks 2009/1002270): the cost-plus margin percent (default `20`), the example-per-USD peg (default `1`), and `mode` — `"cost-plus-and-estimate"` (default; pay both the per-task author estimate AND the cost-plus session reward) or `"cost-plus-only"` (suppress the per-task estimate payout; the cost-plus session reward is the sole equity reward). Two per-craft lanes sit beside `mode` and are not derived from it: `ideatorCredit` ([ADR 0172](adr/0172-per-craft-compensation-ideator-credit-lane.md)) and `artistCredit` ([ADR 0341](adr/0341-the-page-is-the-unit-of-tweak-mode.md) D10, an approved page tweak pays its artist), each default on and withheld only by an explicit `false`. A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg, pay both streams, both lanes on). |
 | `models` | `{ main, subagentDefault, subagentRoutine }` — the per-instance subagent model-allocation DEFAULT the builder-settings module reads (task 2011): the tier for the main session, subagent-default work, and routine plumbing (tiers: `haiku`/`sonnet`/`opus`/`fable`). A per-builder override resolves over this. Omit ⇒ code defaults (`opus`/`opus`/`haiku`). |
 | `tracks` | The configurable version-track set (replaces the hardcoded `product\|internal`). |
 | `theme` | `{ palette, mode, ui }` — palette file ref + theme mode, plus `ui`, the WEB look `themeMarkup()` splices into every served page as a plain `:root` after the page's stylesheet: `colors` (the thirteen contract tokens — **light-mode values**; each stylesheet derives its own dark tier from them at `:root[data-mode="dark"]` + its `prefers-color-scheme` twin, which outrank the pack), `fonts` (`display`, `body`, `links`), `favicon`, and `backdrop` — a `body{background:…}` rule that outranks every sheet in **both** modes, so a dual-mode world sets it to `var(--bg)` (the neutral pack does since [task 1003298](https://cloudbongos.com/builders#/task/1003298), ADR 0196) rather than a literal. The neutral values are the chrome world's; `config/design-tokens.neutral.json` must mirror `colors` + `fonts` key for key (`tests/design_tokens_sync.mjs`), and the world's derived recipes are recorded in `DESIGN.md`. The ui-design module's **style library** (`modules/ui-design/styles/`, [ADR 0219](adr/0219-a-look-is-a-branding-pack-the-style-library.md)) ships ready-made `theme.ui` blocks (looks) an instance copies into this field; every served sheet reads only these fifteen, so a look re-themes every surface with no page edit. |