@bongos/core 1.25.16 → 1.25.17

package/docs/api/openapi.json

@@ -137,6 +137,10 @@
       "name": "feedback",
       "description": "Endpoints under `/api/bongos/feedback`."
     },
+    {
+      "name": "first-read",
+      "description": "Endpoints under `/api/bongos/first-read`."
+    },
     {
       "name": "founding",
       "description": "Endpoints under `/api/bongos/founding`."
@@ -7609,6 +7613,251 @@
         "security": []
       }
     },
+    "/first-read/maps": {
+      "post": {
+        "operationId": "post_first_read_maps",
+        "tags": [
+          "first-read"
+        ],
+        "summary": "POST /first-read/maps",
+        "description": ".create — a map is a planning proposal for this project. Stores it pending; files nothing. A malformed map is refused with every error named.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.create` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/first-read.js",
+        "x-permissions": [
+          "goal.create"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostFirstReadMapsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostFirstReadMapsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/first-read/maps/{id}": {
+      "get": {
+        "operationId": "get_first_read_maps_id",
+        "tags": [
+          "first-read"
+        ],
+        "summary": "GET /first-read/maps/:id",
+        "description": ".create — the review is for whoever may accept or reject it.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.create` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/first-read.js",
+        "x-permissions": [
+          "goal.create"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/first-read/maps/{id}/accept": {
+      "post": {
+        "operationId": "post_first_read_maps_id_accept",
+        "tags": [
+          "first-read"
+        ],
+        "summary": "POST /first-read/maps/:id/accept",
+        "description": ".create + act-alone planning — the owner's yes. Files the chosen items as draft goals (open) and tasks (backlog); an item already filed is skipped.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.create` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/first-read.js",
+        "x-permissions": [
+          "goal.create"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostFirstReadMapsIdAcceptRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/first-read/maps/{id}/reject": {
+      "post": {
+        "operationId": "post_first_read_maps_id_reject",
+        "tags": [
+          "first-read"
+        ],
+        "summary": "POST /first-read/maps/:id/reject",
+        "description": ".create — the owner's no. Files nothing.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.create` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/first-read.js",
+        "x-permissions": [
+          "goal.create"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/first-read/prompt": {
+      "get": {
+        "operationId": "get_first_read_prompt",
+        "tags": [
+          "first-read"
+        ],
+        "summary": "GET /first-read/prompt",
+        "description": "the prompt and the shape are instructions, not project data.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/first-read.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetFirstReadPromptResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/founding/alive": {
       "post": {
         "operationId": "post_founding_alive",
@@ -25358,6 +25607,69 @@
         ]
       }
     },
+    "/provisioning/instances/{id}/render/sandbox": {
+      "post": {
+        "operationId": "post_provisioning_instances_id_render_sandbox",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/instances/:id/render/sandbox",
+        "description": "POST /provisioning/instances/:id/render/sandbox — rank: any authenticated builder, and OWNER ONLY, like every Render route. An app already on Render adds its sandbox with one action (ADR 0406, task 1005289): the owner lends the key once, and the runner sets up a free app that follows main, beside the live one, which it does not touch. A project with no app on Render is told why it has none. The reply is a receipt.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/render-standup.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProvisioningInstancesIdRenderSandboxRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProvisioningInstancesIdRenderSandboxResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/instances/{id}/repo-private": {
       "post": {
         "operationId": "post_provisioning_instances_id_repo_private",
@@ -34352,6 +34664,23 @@
           "count"
         ]
       },
+      "GetFirstReadPromptResponse": {
+        "type": "object",
+        "properties": {
+          "schema": {},
+          "file": {},
+          "prompt": {},
+          "example": {},
+          "limits": {}
+        },
+        "required": [
+          "schema",
+          "file",
+          "prompt",
+          "example",
+          "limits"
+        ]
+      },
       "GetFrontDoorGuideMineResponse": {
         "type": "object",
         "properties": {
@@ -35528,6 +35857,7 @@
             "type": "boolean"
           },
           "app": {},
+          "sandbox": {},
           "env_vars": {},
           "values_held": {
             "type": "boolean"
@@ -35536,6 +35866,7 @@
         "required": [
           "ok",
           "app",
+          "sandbox",
           "env_vars",
           "values_held"
         ]
@@ -38845,6 +39176,49 @@
           "hub"
         ]
       },
+      "PostFirstReadMapsIdAcceptRequest": {
+        "type": "object",
+        "properties": {
+          "all": {
+            "type": "boolean"
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 500
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostFirstReadMapsRequest": {
+        "type": "object",
+        "properties": {
+          "map": {
+            "type": "object"
+          }
+        },
+        "required": [
+          "map"
+        ],
+        "additionalProperties": false
+      },
+      "PostFirstReadMapsResponse": {
+        "type": "object",
+        "properties": {
+          "map_id": {},
+          "status": {},
+          "items": {},
+          "next": {}
+        },
+        "required": [
+          "map_id",
+          "status",
+          "items",
+          "next"
+        ]
+      },
       "PostFoundingPlanRequest": {
         "type": "object",
         "properties": {
@@ -42310,6 +42684,42 @@
           "message"
         ]
       },
+      "PostProvisioningInstancesIdRenderSandboxRequest": {
+        "type": "object",
+        "properties": {
+          "key": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "additionalProperties": false
+      },
+      "PostProvisioningInstancesIdRenderSandboxResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "queued": {
+            "type": "boolean"
+          },
+          "action": {},
+          "sandbox": {
+            "type": "boolean"
+          },
+          "message": {}
+        },
+        "required": [
+          "ok",
+          "queued",
+          "action",
+          "sandbox",
+          "message"
+        ]
+      },
       "PostProvisioningInstancesIdRepoPrivateResponse": {
         "type": "object",
         "properties": {
@@ -42358,6 +42768,7 @@
           "action": {},
           "status": {},
           "superseded": {},
+          "sandbox_key_lent": {},
           "message": {}
         },
         "required": [
@@ -42366,6 +42777,7 @@
           "action",
           "status",
           "superseded",
+          "sandbox_key_lent",
           "message"
         ]
       },
@@ -44894,9 +45306,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 719,
-  "x-schema-count": 749,
+  "x-endpoint-count": 725,
+  "x-schema-count": 755,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 468,
+  "x-response-schemas": 471,
   "x-generated-by": "scripts/bongos/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. 719 endpoints across 121 route files.
+> **Generated from the live route files** — the route file is authoritative. 725 endpoints across 122 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`.
@@ -315,6 +315,16 @@ 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` (5)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| 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/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 +860,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 +896,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). |

package/docs/module-api-changelog.md

@@ -3470,5 +3470,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.25.13 with no explicit bump. run 43497325035. (task 1002620)
   1.25.16 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.25.14 with no explicit bump. run 43503871976. (task 1002620)
+  1.25.17 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.25.16 with no explicit bump. run 43506364199. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/page-readings.json

@@ -4138,7 +4138,7 @@
       "surface": "landing",
       "title": "{{productName}} — projects",
       "states_read": ["out-map","in-map","in-map-projects","in-map-profile","in-map-kbd","in-map-search","in-map-mine-on","in-table","in-table-by-builders","in-mine","in-manage","in-manage-address","in-manage-planet","in-manage-card","in-manage-look","in-manage-kind","in-manage-invite","in-manage-invite-handoff","in-manage-invite-guild","in-manage-app-live","in-manage-app-building","in-manage-app-failed","in-manage-app-retry","in-manage-app-offer","in-manage-app-connect","in-manage-snag","in-manage-gone","in-manage-missing","out-manage","in-new","in-new-named","in-new-ready","in-new-name-prefilled","in-new-demo","in-new-demo-used","in-new-checks-filled","in-new-checks-entity","in-new-row-code","in-new-row-address","in-new-row-team","in-new-row-extras","in-new-row-rewards","in-new-row-app","in-new-row-run","in-new-row-ship","in-new-look","in-new-look-custom","in-new-create-blocked","in-new-done","in-new-resume-offer","out-new","out-map-projects","card","card-noart","card-self","in-manage-demo","in-mine-dns-pending","in-manage-dns-pending","in-mine-empty","card-floor","card-backdrop","in-google","in-new-done-live","setup-just-created","setup-waiting-on-github","setup-installing","setup-stopped","setup-all-done","setup-cloud-hop-open"],
-      "files_hash": "0024fb5540541bf6",
+      "files_hash": "5534a50b3bece717",
       "reading_hash": "c22f44c534cabbdd",
       "counts": {"lines":687,"placed":239,"shared":23,"unplaced":425},
       "omitted": {"data":135},

package/modules/government/decision-rules.js

@@ -94,6 +94,7 @@ const AREAS = Object.freeze([
       'POST /goals/reorder',
       'POST /work-categories',
       'PUT /versions/focus',
+      'POST /first-read/maps/:id/accept', // task 1005280: accepting a repository map files goals
     ]) }),
   Object.freeze({ key: 'automation', name: 'Automation', gate: 'autonomy.fence.manage',
     today: 'whoever may switch unattended building on and off', acts: Object.freeze([