@bongos/core 1.25.14 → 1.25.16

package/docs/adr/0408-a-genesis-stage-is-three-doors-onto-one-record.md

@@ -0,0 +1,61 @@
+# ADR 0408 — A genesis stage is three doors onto one record
+
+- **Status:** accepted
+- **Date:** 2026-11-13
+- **Task:** [task 1005116](https://cloudbongos.com/builders#/task/1005116) (goal 1000106, Project creation)
+- **Owner ruling:** 2026-11-07 — one pattern, every stage, scope included
+
+## Context
+
+Each genesis stage (scope, strategize, charter, legalize, legislation) is a decision only
+the founder can make. Until now each had exactly one route through it: an AI session
+drafted the stage's answer and the founder read it, so the project's strategy was the
+model's. The owner's rule: **Bongos may structure the thinking and may help with the
+words, but the founder is the author.** The owner ruled the fix is one pattern shared by
+every stage, not a strategize feature that charter then copies.
+
+## Decision
+
+1. **Three doors, guided first.** Every stage offers *guided* (the stage's questions, one
+   at a time), *open* (a blank page, with the questions shown beside it as the shape of a
+   good answer) and *assisted* (the founder's own AI session works the same questions,
+   pushes back and records only what the founder accepts). Plus the existing way: link a
+   document the founder already has. Guided is the default because a blank page is how
+   toast's scope came back thin.
+2. **One record per stage, not one per door.** The door is only how the founder is
+   working right now (`onboarding_genesis_work.door`). The answers, the free page and the
+   link are kept whatever the door, so switching loses nothing.
+3. **An answer is a row, not prose.** `onboarding_genesis_answers` holds one row per
+   answered question with a STATE — `answered`, `not_sure` ("not sure yet", an answer,
+   not a gap) or `skipped` — and no row means never touched. Un-answering deletes the
+   row, back to empty. Each row carries its ORIGIN (`founder`, `assisted`,
+   `carried_over`), so answers brought in from before sign-up (task 1005274) read as
+   carried over until the founder makes them theirs. Every change is appended to
+   `onboarding_genesis_answer_history`.
+4. **The questions are code.** `QUESTIONS` in `modules/onboarding/genesis-work.js`; a
+   stage adopts the pattern by declaring its questions there. Strategize does now; scope's
+   guided door is its project interview (task 1005114); charter, legalize and legislation
+   adopt it when next touched. A stage with no questions still takes a page and a link.
+5. **The founder writes, everyone reads.** Writes are behind `project.settings.manage`,
+   like the rest of genesis; reads are any signed-in builder. `GET /founding/context`
+   (and `npx bongos genesis context`) is the read path a session planning a goal or task
+   uses.
+
+## Rejected
+
+- **Answers in `project_settings` JSON**, beside `founding.plan`. One blob per stage
+  cannot tell "not sure yet" from empty at the database, loses every earlier wording on
+  revision, and makes a carry-over that must never overwrite the founder a
+  read-modify-write race.
+- **The answers inside the stage task's description.** That is prose; nothing later can
+  read a single answer out of it, which is the problem the owner raised.
+- **A separate store per door.** Three copies of one artifact drift, and switching would
+  lose work — the opposite of the ruling.
+
+## Consequences
+
+- Presentation is left to the game frame (the founding of the government district) and
+  the hall version (task 1005285). Today a founder works a stage through their AI session
+  and `npx bongos genesis …`.
+- Task 1005115 renders each stage's record as an editable document from this store.
+- Scope adopted it with the project interview (task 1005114): six questions in three groups. `/goal-create` and `/planning-session` read the answers before planning, through `genesis.js context`.

package/docs/adr/README.md

@@ -521,5 +521,6 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0403 | [**In game mode the visor is the control and the scene is the view** ([task 1005203](https://cloudbongos.com/builders#/task/1005203), goal 1000142; owner 2026-11-11). Every main call to action you can see in game mode lives on the visor (the accent button, the key hints, the Actions sheet); the city, the sky and Home only show the project and can be moved through, never carry buttons of their own. A scene offers its actions to the visor through `OTBVisor.scene`. Found not yet keeping it: the city's decide button and door, the sky's top row and composer, Home's gallery links, the Artist's feedback tab.](0403-in-game-mode-the-visor-is-the-control-and-the-scene-is-the-view.md) | hall / game frame |
 | 0404 | [**A party is a room, and rooms register as kinds** ([task 1005220](https://cloudbongos.com/builders#/task/1005220), goal 1000148). Any group that talks together is a room: a free-form party (cap 8), a chain party (ADR 0400), a scoping session (cap 40, owned by `lifecycle`) or a decision room (cap 40, `government`). Each owner contributes its kind to the `room.kinds` contribution point (a port is single-provider, so four owners would fail the boot) with `members`/`isMember`/optional `invite`/`accept`, and fires `room.opened`/`room.member.joined`/`room.member.left`/`room.closed`; consumers never read an owner's tables and reconcile against `members()`. Free-form party: one per builder, leader handover to the longest-standing member, disband on last leave. A chain room follows an open `chain_party` row. Unlinked players get everything but voice. V3 polls (3 s, cursor + 304, paused when hidden, per-builder limiter) rather than pushing through `/live`. With discord off, no voice key or voice state; chat still works. A room is never authority. Rejected: one port, a port per kind, a rooms module reading other modules' tables, a second party roster, push via `/live`, speaking indicators.](0404-a-party-is-a-room-and-rooms-register-as-kinds.md) | game frame / modules / Discord |
 | 0405 | [**Each character has one colour, and the visor wears it** ([task 1005218](https://cloudbongos.com/builders#/task/1005218), goal 1000142; owner 2026-11-12). The Artisan is ember (the accent), the Artist violet, the Patron gold, each mixed from the hall’s tokens and none typed in. In game mode the visor’s lines, name, picture rim and accent are the held character’s colour, and your picture on the glass is your character wearing the visor. The characters are redrawn at 64 by 64 as two-animal aliens, drawn by a script.](0405-each-character-has-one-colour-and-the-visor-wears-it.md) | hall / game frame |
+| 0408 | [**A genesis stage is three doors onto one record** ([task 1005116](https://cloudbongos.com/builders#/task/1005116), goal 1000106; owner 2026-11-07). Every genesis stage offers guided (its questions, the default), open (a blank page with the questions beside it) and assisted (the founder's own AI session works the same questions and records only what the founder accepts), plus linking an existing document. The door is only how the founder is working now: answers, page and link are one record per stage, so switching loses nothing. An answer is a row with a state (answered · not sure yet · skipped; no row = empty) and an origin (founder · assisted · carried over), with append-only history. Founder writes, everyone reads; `GET /founding/context` is the planning read path. Rejected: project_settings JSON, answers inside task prose, a store per door.](0408-a-genesis-stage-is-three-doors-onto-one-record.md) | onboarding / genesis |
 | 0406 | [**Every project gets a sandbox that follows main, and live moves only when a person promotes** ([task 1005288](https://cloudbongos.com/builders#/task/1005288), goal 1000106; owner 2026-11-13). One repository, no sandbox branch: a second Render web service on the free plan auto-deploys every landing on `main`, and the live service stops auto-deploying and takes only the commit a person promotes (with the Render key typed in for that request). Fake data and test keys by default; lent real keys should be read-only, behind an outbound gate that refuses sends, charges and writes. Render's free database expires in 30 days, so the sandbox gets a second database in the app's paid one. A project with no app gets no hosted sandbox; Cloud Bongos runs the same rule over its release pin.](0406-every-project-gets-a-sandbox-that-follows-main-and-live-moves-only-when-a-person-promotes.md) | provisioning / hosting |
 | 0407 | [**A hosted project's grant is made by its owner, not witnessed at sign-in** ([task 1004753](https://cloudbongos.com/builders#/task/1004753), goal 1000106; accepted by the owner 2026-11-13). Replaces ADR 0328's suspended Phase 2: no `membership_kind` admits anyone, because sign-in writes `member` for any GitHub user (the device flow included) and check-in is the project's own word. A new `provisioning_project_grants` row, one writer (`grants.js`), created only by the project's owner from their hub session (no archon create; owner, grantee or archon may revoke), read live in `requireProjectOwner` on routes that opt in with `{ grantee: 'operate' }`: the project read, settings read, env-manifest (names only) and restart. Teardown, disconnect, domain, the GitHub/Render/repo-private actions, settings and look writes stay owner-only. Audit actor `api:grantee:<id>`. The sign-in default stays `member`. A visitor or pending applicant gets 403 `project_membership_required` with the join path; a member without a grant gets 403 `project_access_required` (ask the owner); a stranger keeps the 404.](0407-a-project-grant-is-made-by-the-owner-not-witnessed-at-sign-in.md) | provisioning / permissions |

package/docs/api/openapi.json

@@ -7671,6 +7671,37 @@
         ]
       }
     },
+    "/founding/context": {
+      "get": {
+        "operationId": "get_founding_context",
+        "tags": [
+          "founding"
+        ],
+        "summary": "GET /founding/context",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/founding/enabled": {
       "put": {
         "operationId": "put_founding_enabled",
@@ -7893,6 +7924,466 @@
         ]
       }
     },
+    "/founding/work": {
+      "get": {
+        "operationId": "get_founding_work",
+        "tags": [
+          "founding"
+        ],
+        "summary": "GET /founding/work",
+        "description": "The read path for every door and for AI sessions planning a goal or task.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/founding/work/{stage}": {
+      "get": {
+        "operationId": "get_founding_work_stage",
+        "tags": [
+          "founding"
+        ],
+        "summary": "GET /founding/work/:stage",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          }
+        ],
+        "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": []
+          }
+        ]
+      }
+    },
+    "/founding/work/{stage}/answers/{question}": {
+      "put": {
+        "operationId": "put_founding_work_stage_answers_question",
+        "tags": [
+          "founding"
+        ],
+        "summary": "PUT /founding/work/:stage/answers/:question",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          },
+          {
+            "name": "question",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `question`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutFoundingWorkStageAnswersQuestionRequest"
+              }
+            }
+          },
+          "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": []
+          }
+        ]
+      },
+      "delete": {
+        "operationId": "delete_founding_work_stage_answers_question",
+        "tags": [
+          "founding"
+        ],
+        "summary": "DELETE /founding/work/:stage/answers/:question",
+        "description": "Un-answer: back to empty, which is not the same as skipped.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          },
+          {
+            "name": "question",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `question`."
+          }
+        ],
+        "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": []
+          }
+        ]
+      }
+    },
+    "/founding/work/{stage}/answers/{question}/history": {
+      "get": {
+        "operationId": "get_founding_work_stage_answers_question_history",
+        "tags": [
+          "founding"
+        ],
+        "summary": "GET /founding/work/:stage/answers/:question/history",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          },
+          {
+            "name": "question",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `question`."
+          }
+        ],
+        "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": []
+          }
+        ]
+      }
+    },
+    "/founding/work/{stage}/assist": {
+      "get": {
+        "operationId": "get_founding_work_stage_assist",
+        "tags": [
+          "founding"
+        ],
+        "summary": "GET /founding/work/:stage/assist",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          }
+        ],
+        "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": []
+          }
+        ]
+      }
+    },
+    "/founding/work/{stage}/door": {
+      "put": {
+        "operationId": "put_founding_work_stage_door",
+        "tags": [
+          "founding"
+        ],
+        "summary": "PUT /founding/work/:stage/door",
+        "description": "The founder's writes.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutFoundingWorkStageDoorRequest"
+              }
+            }
+          },
+          "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": []
+          }
+        ]
+      }
+    },
+    "/founding/work/{stage}/link": {
+      "put": {
+        "operationId": "put_founding_work_stage_link",
+        "tags": [
+          "founding"
+        ],
+        "summary": "PUT /founding/work/:stage/link",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutFoundingWorkStageLinkRequest"
+              }
+            }
+          },
+          "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": []
+          }
+        ]
+      }
+    },
+    "/founding/work/{stage}/page": {
+      "put": {
+        "operationId": "put_founding_work_stage_page",
+        "tags": [
+          "founding"
+        ],
+        "summary": "PUT /founding/work/:stage/page",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/genesis-work.js",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `stage`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutFoundingWorkStagePageRequest"
+              }
+            }
+          },
+          "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": []
+          }
+        ]
+      }
+    },
     "/front-door-guide/conversations": {
       "post": {
         "operationId": "post_front_door_guide_conversations",
@@ -43958,6 +44449,57 @@
         },
         "additionalProperties": false
       },
+      "PutFoundingWorkStageAnswersQuestionRequest": {
+        "type": "object",
+        "properties": {
+          "state": {
+            "type": "string",
+            "maxLength": 16
+          },
+          "text": {
+            "type": "string"
+          },
+          "origin": {
+            "type": "string",
+            "maxLength": 16
+          },
+          "if_empty": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      },
+      "PutFoundingWorkStageDoorRequest": {
+        "type": "object",
+        "properties": {
+          "door": {
+            "type": "string",
+            "maxLength": 16
+          }
+        },
+        "required": [
+          "door"
+        ],
+        "additionalProperties": false
+      },
+      "PutFoundingWorkStageLinkRequest": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "PutFoundingWorkStagePageRequest": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
       "PutGovernmentAsksMatterIdResponse": {
         "type": "object",
         "properties": {
@@ -44352,8 +44894,8 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 709,
-  "x-schema-count": 745,
+  "x-endpoint-count": 719,
+  "x-schema-count": 749,
   "x-undocumented-bodies": 12,
   "x-response-schemas": 468,
   "x-generated-by": "scripts/bongos/gen-api-docs.js"