@bongos/core 1.25.12 → 1.25.14

package/docs/adr/0407-a-project-grant-is-made-by-the-owner-not-witnessed-at-sign-in.md

@@ -0,0 +1,124 @@
+# ADR 0407 — A hosted project's grant is made by its owner, not witnessed at sign-in
+
+- **Status:** accepted — the owner accepted this design as written on 2026-11-13, including its three answers below (no archon-made grants; `operate` = reads, the variable-name list and restart; the sign-in default stays `member`). Design only: nothing here widens a gate. The gate stays owner-or-archon until [task 1004161](https://cloudbongos.com/builders#/task/1004161) builds what is written here.
+- **Date:** 2026-11-13
+- **Task:** [task 1004753](https://cloudbongos.com/builders#/task/1004753) (goal 1000106, check `wa1-members-owner-granted`)
+- **Amends:** [ADR 0328](0328-a-hosted-projects-authority-is-its-membership-row-not-its-owner-column.md) — replaces its suspended Phase 2 and re-states its Decision 3 (what a refused caller is told).
+- **Follow-on tasks (updated 2026-11-13, in the task records):** [task 1004161](https://cloudbongos.com/builders#/task/1004161) is rewritten to build §§1–4 and the attack tests, and is taken off hold with an explicit promote the moment this task lands (promote refuses while this task is unshipped, and nothing else clears a park); [task 1004162](https://cloudbongos.com/builders#/task/1004162) is re-checked against §6 (a third refusal, and it now owns the membership port).
+- **Related:** [ADR 0016](0016-trust-boundary-server-enforced-permissions.md) (authority is read live from the database on every request), [ADR 0083](0083-modular-architecture-strangler-build-plan.md) (modules cooperate through ports), [ADR 0141](<redacted>.md) / [0205](0205-federated-checkin-needs-the-hubs-own-signin-witness.md) (the sign-in witness), [ADR 0151](0151-governance-permissions-as-atom-ranks-as-roles.md) §3 (the ownership axis), [ADR 0176](0176-private-repo-deploy-keys.md) / task 1004194 (repo-private stays owner-only because it uses the owner's GitHub token).
+
+## Context
+
+ADR 0328 Phase 2 would have admitted a `member` row of `<redacted>` onto the hosted-project routes. Its 2026-10-16 amendment suspended that, and every fact behind the suspension was re-checked against the code for this ADR (2026-11-13):
+
+- `recordFederatedSignin` (`modules/platform-identity/platform-identity.js`) inserts `membership_kind = 'member'` with `signin_verified_at = now()` on every completed hub sign-in, and turns a `pending` row into `member`. Its own comment calls it "the only way a membership row is born".
+- It is called from `POST /sso/token` and `POST /sso/device/poll` (`modules/platform-identity/routes/sso.js`). `POST /sso/device/start` takes only a typed `origin` and no session; it refuses only an unknown, inactive or secretless client. So any GitHub user can get a witnessed `member` row on any credentialed project, and the project's own server is never asked.
+- `POST /sso/membership/check-in` (`touchMembership`) lets the **project's server** set any kind, `owner` included, on a row that already has a sign-in witness. On the instance side, `membershipKind` (`src/bongos/auth-admission.js`) reports `owner` for the first admin and `member` for everyone else, and with `admission.policy: open` that is every GitHub sign-up.
+
+So no value of `membership_kind` means "the owner trusts this person with the hosting". `member` means "has signed in here"; `owner` means "this project's server says so". Neither is a fact the hub itself decided.
+
+**What the gate guards today.** `requireProjectOwner` (`modules/provisioning/route-helpers.js`, task 1004159) admits the row's `owner_builder_id`, or a caller whose live rank is `archon`; everyone else gets `404 instance_not_found`. It is mounted on 14 routes. The task's "14 routes" is accurate for that helper, but **28 routes** take a hosted project's `:id`. The other 14 check inline or by permission:
+
+| Gate today | Routes |
+|---|---|
+| `requireProjectOwner` (owner or archon) — 14 | `GET …/:id`; `PATCH …/:id/detail`; `GET …/:id/invite-suggestions`; `GET`/`PATCH …/:id/settings`; `POST …/:id/teardown`; `POST …/:id/restart`; `POST …/:id/domain`; `POST …/:id/github-app` (all `routes/provisioning.js`); `POST …/:id/disconnect` (`routes/disconnect.js`); `GET`/`POST …/:id/env-manifest`, `PATCH`/`DELETE …/:id/env-manifest/:varId` (`routes/env-manifest.js`) |
+| inline, owner or archon — 4 | `GET`/`PATCH …/:id/look`, `PUT`/`DELETE …/:id/logo` (`routes/look.js`) |
+| inline, owner only — 6 | `POST …/:id/demo` (`routes/demo.js`); `POST …/:id/github-app/pick-up` (`routes/github-setup.js`); `GET`/`POST …/:id/render` (`routes/render-standup.js`); `POST …/:id/repo-private` (`routes/repo-private.js`) |
+| owner or `core.pin.move` — 3 | `GET`/`POST …/:id/core-upgrade`, `POST …/:id/update-channel` (`routes/core-upgrade.js`) |
+| `provisioning.fleet.manage` only — 2 | `POST …/:id/force-teardown`; `POST …/:id/update-subscription` |
+
+## Decision
+
+### 1. The grant is its own row, in the provisioning module, with one writer
+
+A new table, `provisioning_project_grants` (migration `<redacted>.sql`, additive, in the module's own namespace):
+
+| Column | Meaning |
+|---|---|
+| `id` | bigint identity |
+| `instance_id` | `provisioning_instances.id`, `ON DELETE CASCADE` (disconnect deletes the row, so its grants go with it) |
+| `grantee_builder_id` | the hub `builders.id` of the person granted — the same key as `owner_builder_id`, so the gate compares like with like |
+| `level` | `text NOT NULL CHECK (level IN ('operate'))` — one level today (§3); a second level is an ADR amendment, never a free string |
+| `granted_by_builder_id`, `granted_at` | who made it, when |
+| `revoked_at`, `revoked_by_builder_id` | null while live; a revoke is a stamp, never a delete, so the record survives |
+
+A partial unique index on `(instance_id, grantee_builder_id) WHERE revoked_at IS NULL` allows one live grant per person per project; re-granting after a revoke makes a new row.
+
+**The single writer** is a new file `modules/provisioning/grants.js` (`grantProjectAccess`, `revokeProjectAccess`, `liveGrant`), called only by the grant routes in §2. Nothing else may insert or update the table; a test greps for any other `INSERT INTO provisioning_project_grants` / `UPDATE provisioning_project_grants`.
+
+**Why here and not in `<redacted>`.** ADR 0328 rejected a separate provisioning table because a second copy of membership would drift. That reason is gone: the membership table does not hold grants, and its writers (sign-in, check-in, invites) are exactly the paths that must never create one. Keeping the grant beside `owner_builder_id` also means the gate reads both facts in one query in the module that owns them, with no cross-module port in the admission path, so "the port is down" can never decide who gets in.
+
+### 2. Who may make and remove a grant
+
+- **Create — the project's owner only, from their own hub session.** `POST /provisioning/instances/:id/grants { github_login }`, gated `requireBuilder` + `requireProjectOwner(loadInstance, { archonOverride: false })`. The login is resolved **server-side** to an existing, active hub builder; no such builder → `404 grantee_not_found` ("they need to sign in to the hub once first"). The reply names the person found (display name and picture), because a GitHub login can change hands. The owner cannot grant themselves. At most 25 live grants per project (`409 grant_limit`).
+- **An archon cannot create a grant** on someone else's project. An archon already has fleet-support reach through the override; a grant would let them hand an owner's project to a third person without the owner, and in doubt we refuse. (Owner choice — see *Open questions*.)
+- **Revoke** — `DELETE /provisioning/instances/:id/grants/:grantId`: the owner; the grantee themselves (leaving); or an archon. A revoke only ever removes access, so the archon door is a safety lever, not a widening.
+- **List** — `GET /provisioning/instances/:id/grants`: owner or archon (the existing gate). A grantee sees their own grant on the project read, not the list.
+
+**How the hub learns of the grant without trusting the visitor:** it does not learn it from anyone. The row is born on the hub from the owner's authenticated session, checked against `owner_builder_id` on the hub's own database. Nothing the visitor sends, nothing a project's server reports at check-in, and no sign-in can create, change or extend it. The gate never reads `<redacted>` to admit anyone.
+
+### 3. What a grantee may do — a short allow-list, opt-in per route
+
+The one level, `operate`, is "help keep it running": look at the project and restart it, and maintain the list of environment variable names. Everything that changes what the project *is*, who can see it, where it lives, or that acts with the owner's own accounts stays owner-only.
+
+| Route | Grantee (`operate`) |
+|---|---|
+| `GET …/:id` | ✅ read — the projection drops `owner_monthly_usd` (the owner's own bill) and `github_install` (an action on the owner's GitHub) |
+| `GET …/:id/settings` | ✅ read |
+| `GET …/:id/env-manifest` | ✅ read — names and purposes only; the platform holds no values (ADR 0323 §6) |
+| `POST …/:id/env-manifest`, `PATCH`/`DELETE …/:id/env-manifest/:varId` | ✅ write — declaring a variable name changes no running behaviour; the manifest exists for builder sessions to read and keep current |
+| `POST …/:id/restart` | ✅ write — recovers a stuck project; changes no data, costs nothing |
+| `teardown`, `disconnect`, `domain`, `github-app`, `github-app/pick-up`, `repo-private`, `render` (GET and POST), `demo` | ❌ owner only (plus the archon override where it exists today). Teardown and disconnect destroy; domain moves the address; github-app, pick-up, repo-private and render act with the owner's own GitHub or Render account |
+| `PATCH …/:id/settings`, `PATCH …/:id/detail`, look and logo (4) | ❌ owner only — who can see and join the project, and how it presents itself, is the owner's call |
+| `GET …/:id/invite-suggestions` | ❌ owner only — inviting is the owner's lever |
+| `core-upgrade` (2), `update-channel` | ❌ unchanged (owner or `core.pin.move`) |
+| `force-teardown`, `update-subscription` | ❌ unchanged (fleet permission) |
+| the grant routes (§2) | ❌ except a grantee revoking their own grant |
+
+**Mechanism — opt-in, never default.** `requireProjectOwner` gains one option, `{ grantee: 'operate' }`. Without it (every route today, and every route added later) a grant admits nothing. With it, the gate admits the owner, then a live `operate` grant for `req.builder.id`, then the archon override, in that order, and sets `req.projectDoor` to `owner` · `grantee` · `archon`. The grant is read inside the gate on every request (no caching, ADR 0016), so a revoke takes effect on the grantee's next request. A failed grant read **denies** — the gate's existing `failFrom(res, err, 'instance_read_failed')`, never a fall-through to "admit". The inline-gated routes are not converted by this design; they stay owner-only by not having the option.
+
+### 4. The audit actor
+
+`projectActor(req)` reads `req.projectDoor`: `api:self` (owner), `api:grantee:<builderId>` (grantee), `api:archon:<builderId>` (archon override). A grantee who is also an archon is recorded as `grantee`, because the owner's grant is what let them in. The grant routes write `provisioning_events` rows `grant-made` and `grant-revoked`, whose `detail` names the grantee's builder id and level; their actor is the same three-way label (a grantee leaving is `api:grantee:<id>`).
+
+### 5. The hub's sign-in default stays `member`
+
+The task asked whether sign-in should stop writing `member`. **This design keeps it**, because once nothing grants on it, the word carries no authority, and changing it reaches three working features for no security gain:
+
+- *My Projects* (`listMembershipsForAccount`) lists every non-`pending` row; a `visitor` default would still list them, but would make the existing project list say "visitor" for people who genuinely build there.
+- The activity-rollup precheck (`membershipBacksRollup`) accepts any witnessed non-`pending` row; unchanged either way.
+- Invites turn `pending` into `member` at sign-in; a `visitor` default would need its own rule for accepted invites.
+
+The word is documented as "has signed in here" (ADR 0328's amendment already says so). If the owner later wants the label changed for clarity, that is its own task, not a security fix.
+
+### 6. What a refused caller is told (replaces ADR 0328 Decision 3; task 1004162)
+
+- **No grant and no membership row** → `404 instance_not_found`, as today. A stranger learns nothing.
+- **Not yet a member of the project** (a `visitor` or `pending` row, no grant) → `403 project_membership_required` with the apply path, as task 1004162 already specifies: a `visitor` is pointed to `POST /my-projects/join` (the shipped ADR 0141 / 0201 / 0247 join flow); a `pending` row is told their request is already on file and the owner decides. The message also says that managing the hosting is something the owner gives separately, so joining is not mistaken for that.
+- **A member of the project (a `member` or `owner` kind row) without a grant** → `403 project_access_required`: "Only the project's owner, and people the owner has given access, can manage its hosting. Ask the owner to give you access." There is no self-serve request for hosting access.
+- **How the row is read.** Through a port, `platform-identity.projectMembershipKind` as ADR 0328 named it, and only after the gate has already refused. If the port is unregistered, throws, or answers an unknown value, the answer is the `404`: on doubt, say less. This read only picks the wording of a refusal and can never admit anyone.
+- **A grantee on a route without the opt-in** → `403 owner_only`, "Only the project's owner can do this." They already know the project exists.
+
+## Consequences
+
+- A team can share one hosted project's day-to-day running, once task 1004161 lands, without the owner handing over teardown, the address or their own accounts.
+- The device-flow attack in the task is closed by construction: running the device flow writes a membership row, and nothing reads that row to admit. Task 1004161's tests must show a GitHub user who only ran the device flow is refused on **all 28** routes, with a member row present.
+- One new table, one new file, three routes, and one gate option. One extra indexed read per request on the 7 opt-in routes, only when the caller is not the owner.
+- An owner can lock themselves out of nothing: a grantee can never revoke the owner, change the owner, or make grants.
+- **Ownership transfer** has no route today. Whatever adds one must decide what happens to live grants; this ADR does not.
+- The owner needs a place to give access. Task 1004161 builds the API and gate; the manage page's "People with access" card may be split into its own task at claim time, but the grant is not usable by a non-technical owner until it exists.
+
+## Alternatives considered
+
+- **Admit `member` rows that a project's check-in reported** (ADR 0328 Phase 2). Rejected: the sign-in default is `member`, and check-in is the project's own word, which on an open project is every sign-up.
+- **A `granted` kind inside `<redacted>`.** Rejected: that table's writers include check-in, which can set any kind; a grant must have one writer and no outside reporter.
+- **Let an archon make grants.** Rejected for now (doubt → refuse); the owner can ask for it.
+- **One grant level that admits every route the archon override admits.** Rejected: it would hand teardown and disconnect to anyone the owner added for a restart.
+- **A self-serve "request hosting access" queue.** Not built: it adds a new inbox and a new notification for a request a person can simply make to the owner.
+
+## Owner decisions (2026-11-13)
+
+1. The design is accepted as written.
+2. An archon may not give access on someone else's project (§2).
+3. A grantee's level, `operate`, is the project read, the settings read, the variable-name list and restart (§3).
+4. Separately, the owner ruled that who may open a project's pages at all is chosen by its founders during genesis, not fixed by a platform default. That is outside this ADR (it is the project's page door, not its hosting) and is filed as an idea for the genesis work.

package/docs/adr/README.md

@@ -522,3 +522,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 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 |
 | 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

@@ -7946,25 +7946,81 @@
             "description": "Path parameter `id`."
           }
         ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
+    "/front-door-guide/conversations/{id}/attach": {
+      "post": {
+        "operationId": "post_front_door_guide_conversations_id_attach",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "POST /front-door-guide/conversations/:id/attach",
+        "description": "the visitor has just signed in; the chat moves onto their account.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/front-door-guide/routes/front-door-guide-plan.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/PostFrontDoorGuideConversationsIdAttachRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetFrontDoorGuideConversationsIdResponse"
+                  "$ref": "#/components/schemas/PostFrontDoorGuideConversationsIdAttachResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
           "404": {
             "$ref": "#/components/responses/NotFound"
           }
         },
-        "security": []
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
     "/front-door-guide/conversations/{id}/messages": {
@@ -8013,6 +8069,90 @@
         "security": []
       }
     },
+    "/front-door-guide/conversations/{id}/plan": {
+      "post": {
+        "operationId": "post_front_door_guide_conversations_id_plan",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "POST /front-door-guide/conversations/:id/plan",
+        "description": "the visitor has no account yet.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/front-door-guide/routes/front-door-guide-plan.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/PostFrontDoorGuideConversationsIdPlanRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
+    "/front-door-guide/mine": {
+      "get": {
+        "operationId": "get_front_door_guide_mine",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "GET /front-door-guide/mine",
+        "description": "my newest chat and plan (the creation wizard's pre-fill reads it).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/front-door-guide/routes/front-door-guide-plan.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetFrontDoorGuideMineResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/front-door-guide/status": {
       "get": {
         "operationId": "get_front_door_guide_status",
@@ -33721,19 +33861,17 @@
           "count"
         ]
       },
-      "GetFrontDoorGuideConversationsIdResponse": {
+      "GetFrontDoorGuideMineResponse": {
         "type": "object",
         "properties": {
           "ok": {
             "type": "boolean"
           },
-          "conversation": {},
-          "transcript": {}
+          "conversation": {}
         },
         "required": [
           "ok",
-          "conversation",
-          "transcript"
+          "conversation"
         ]
       },
       "GetGithubOrgsOrgResponse": {
@@ -38246,6 +38384,32 @@
         },
         "additionalProperties": false
       },
+      "PostFrontDoorGuideConversationsIdAttachRequest": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "maxLength": 64
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "additionalProperties": false
+      },
+      "PostFrontDoorGuideConversationsIdAttachResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "conversation": {}
+        },
+        "required": [
+          "ok",
+          "conversation"
+        ]
+      },
       "PostFrontDoorGuideConversationsIdMessagesRequest": {
         "type": "object",
         "properties": {
@@ -38260,6 +38424,9 @@
           "website": {
             "type": "string",
             "maxLength": 500
+          },
+          "starting_point": {
+            "type": "string"
           }
         },
         "required": [
@@ -38268,12 +38435,32 @@
         ],
         "additionalProperties": false
       },
+      "PostFrontDoorGuideConversationsIdPlanRequest": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "website": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "additionalProperties": false
+      },
       "PostFrontDoorGuideConversationsRequest": {
         "type": "object",
         "properties": {
           "website": {
             "type": "string",
             "maxLength": 500
+          },
+          "starting_point": {
+            "type": "string"
           }
         },
         "additionalProperties": false
@@ -44165,9 +44352,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 706,
-  "x-schema-count": 742,
+  "x-endpoint-count": 709,
+  "x-schema-count": 745,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 467,
+  "x-response-schemas": 468,
   "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. 706 endpoints across 119 route files.
+> **Generated from the live route files** — the route file is authoritative. 709 endpoints across 120 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`.
@@ -328,13 +328,16 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/founding/stages/:stage/close` | `any-builder` | — | task 1005121: one call. |
 | POST | `/api/bongos/founding/start` | `any-builder` | — |  |
 
-## `front-door-guide` (4)
+## `front-door-guide` (7)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
-| POST | `/api/bongos/front-door-guide/conversations` | `public` | `website` | start a chat. |
+| POST | `/api/bongos/front-door-guide/conversations` | `public` | `website`, `starting_point` | start a chat. |
 | GET | `/api/bongos/front-door-guide/conversations/:id` | `public` | — | the transcript, for the plan and the sign-up hand-off. |
-| POST | `/api/bongos/front-door-guide/conversations/:id/messages` | `public` | `token`, `text`, `website` | one visitor message, one guide reply. |
+| POST | `/api/bongos/front-door-guide/conversations/:id/attach` | `any-builder` | `token` | the visitor has just signed in; the chat moves onto their account. |
+| POST | `/api/bongos/front-door-guide/conversations/:id/messages` | `public` | `token`, `text`, `website`, `starting_point` | one visitor message, one guide reply. |
+| POST | `/api/bongos/front-door-guide/conversations/:id/plan` | `public` | `token`, `website` | the visitor has no account yet. |
+| GET | `/api/bongos/front-door-guide/mine` | `any-builder` | — | my newest chat and plan (the creation wizard's pre-fill reads it). |
 | GET | `/api/bongos/front-door-guide/status` | `public` | — | the landing asks before it offers the chat. |
 
 ## `github` (8)