@bongos/core 1.21.127 → 1.21.128

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.127",
-  "core_contract": "1.21.127",
-  "source_commit": "ea6cb74e9eba8805eb016b8ac0420841e429c290",
+  "core_version": "1.21.128",
+  "core_contract": "1.21.128",
+  "source_commit": "31d87d7e4b4e2c97040083251efcd43c9c97c935",
   "source_ref": "HEAD",
-  "built_at": "2026-10-15T15:58:58.689Z",
+  "built_at": "2026-10-15T16:35:02.176Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 606,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3138,
+    "functional_verbatim": 3141,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3773,
-  "tree_sha256": "2af5f5b320f78e843791c36c370aa8f198a28c9bd3b085c1875f39869558c2cd",
+  "file_count": 3776,
+  "tree_sha256": "63aa30ff5172b9c025bc2092a63f9109f261f2a5d46b47638378c0505428b3f4",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -317,12 +317,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "8ec09fb234db73a4cb92ad78c4da3532d5717f48106dd97fbb860fa17b1b1b5b"
+      "sha256": "9aea69205101517f33e85bd80593333deb8a015d6c98ae55d73ddc59c3067d12"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "2f89099d91db14e37dc9d67ef68a81ba410740446758e639cb50de51a6942d79"
+      "sha256": "23208de4f2aa8f0c1c5ec2f7939e637224280c3cf520958148549e2f79c02c9d"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -332,17 +332,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "14f0fa81adc576c014950856f70d6721bb796104e65b3fecadb7d5b1370010b2"
+      "sha256": "25dd808eae862cd02ed9a494f5e0ce2ee8d31bb664f78a23c151a95dc1f0c25f"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "c13884fb0bd175f8bc9745150b2ca5ed254dd0ad14bcaa63511cf892cdbaec36"
+      "sha256": "d98b7b69f7e2db071b9b10e5e039afdf95262b7196450ef56c73c0acac8717a7"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "b77e22573f2d8c9c9f2f1b3a1642e9258cd4fec394d1416ae816c6bf56a3295d"
+      "sha256": "c3a776cd09ddde2c4d1d3ed8b3f90daed304c6cc8d459a688585526360c2b5e5"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2377,12 +2377,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "cda3b2d273704ab0bebe67efe46f0101e1809ec8e8beef2ad3614b6fc5845a31"
+      "sha256": "9ec7dd570500edd3705cd871886734d89780b92df6f185cdc86002288fe7aa7d"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "cd89b6776167172503ef68a77b1cfa68a00bf886d8f586c456f67e3cfef84fba"
+      "sha256": "319fce626080497fdf50a50064f0faa56951b1aa021e97edd6ad481d8ee5c9b9"
     },
     {
       "path": "docs/architecture.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "de498901b8143d15779aafd30051f97e04ae01f32c880902da3a8234a6e262e7"
+      "sha256": "f5e9ba961f5fad8945bbcba2e6daefdde31efba3e6e6b41dde6d52aa06b07065"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7934,10 +7934,20 @@
       "mode": "0000644",
       "sha256": "18984c946d746da66ff7678379e9f49c9cfdcdb8f70d2acd852ab29c820baad0"
     },
+    {
+      "path": "modules/onboarding/howto-state.js",
+      "mode": "0000644",
+      "sha256": "9b6d361568feaa4f9a9f299bddcd4bc649861cf79a9a6045ea00389bd86cc01c"
+    },
+    {
+      "path": "modules/onboarding/migrations/onboarding_001_howto_reads.sql",
+      "mode": "0000644",
+      "sha256": "cb5a3a58b4db75c028ccc53ea3316bb733fda650218b16b494d69de58c84e982"
+    },
     {
       "path": "modules/onboarding/module.json",
       "mode": "0000644",
-      "sha256": "5ec905fe4a387bbb26ec157ac8d67a05bd02986fc661aa2621b84df260f45774"
+      "sha256": "363a44b85c87bfbc2bb473656319099c39e7817e47294f3ceb4a33ee6bc85421"
     },
     {
       "path": "modules/onboarding/newcomer-restock.js",
@@ -7967,7 +7977,7 @@
     {
       "path": "modules/onboarding/routes/onboarding.js",
       "mode": "0000644",
-      "sha256": "385deea4dfc4e737f756dc56c1cd6c8891ebdb202e66cf15e235e6b10e498788"
+      "sha256": "011dfc781cbe8c7a17956fa2020e0327cf0e46f537a9057cf2b4911752ba813a"
     },
     {
       "path": "modules/page-notes/CLAUDE.md",
@@ -10482,12 +10492,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "efe64aff087c9fac228bb0502df35fdb706ea66215ba9a7b20a16575b4568a6d"
+      "sha256": "b7d2956b1155f633fbfbbfafe4211befef0d545b02671ce8cd9096ee22a1f734"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "65dbc0fd1642caa7dd0907f8ca5f8d6e3808087637f31aaff0b5b3b2e22da1da"
+      "sha256": "4cbf0ddd56ffbee1d0d4cdd8388793c2590a243737608cf18556e0400e946fed"
     },
     {
       "path": "public-docs/index.html",
@@ -10507,7 +10517,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "b3c808cc70f6d027e4dc58fad374f2dff423b73416eee5c5a96e8779ddd2d04f"
+      "sha256": "f5b81f238e17e854f85e2af52d9c3661acf519c8bd9634aaa95206e8f107bc5b"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -12857,7 +12867,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8ff71d0200dd2b11afa13be91155669caee7ba000a537df94e37426a6485e7f1"
+      "sha256": "638e7c6e9ff2e460bacc69abc98b8f6721b6d2ade29ba79aa166920e1f71f7e7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -15639,6 +15649,11 @@
       "mode": "0000644",
       "sha256": "8e9b206fdde738f289bc11e204852595e9128b523cfc20cd67e3e83fb60a2fac"
     },
+    {
+      "path": "tests/howto_state.mjs",
+      "mode": "0000644",
+      "sha256": "8b8d3eeeffd1bb7d0deaec51c91165b06302737b72b1a710547340c7ecadcec6"
+    },
     {
       "path": "tests/html_comment_nesting.mjs",
       "mode": "0000644",
@@ -16722,7 +16737,7 @@
     {
       "path": "tests/own_scope_guard.mjs",
       "mode": "0000644",
-      "sha256": "e9ad80ce9837076d550dbb4b77a4c0f01f087ad3e515f8af8a672221af995ca4"
+      "sha256": "cdd964e66b9ebe74c504a3916eb3a10b36497af4f5b94924534d2d73f136801a"
     },
     {
       "path": "tests/own_session_revoke.mjs",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 555 operations across 76 resource groups
+- 558 operations across 76 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -735,6 +735,12 @@ function createClient(opts = {}) {
       getMeGuilds: (args) => request("GET", "/me/guilds", { hasBody: false }, args),
       // PATCH /me/handle — rank: any-builder — PATCH /me/handle
       patchMeHandle: (args) => request("PATCH", "/me/handle", { hasBody: true }, args),
+      // GET /me/howto — rank: any-builder — GET /me/howto
+      getMeHowto: (args) => request("GET", "/me/howto", { hasBody: false }, args),
+      // POST /me/howto/read — rank: any-builder — POST /me/howto/read
+      postMeHowtoRead: (args) => request("POST", "/me/howto/read", { hasBody: true }, args),
+      // POST /me/howto/reset — rank: any-builder — POST /me/howto/reset
+      postMeHowtoReset: (args) => request("POST", "/me/howto/reset", { hasBody: true }, args),
       // GET /me/interaction — rank: any-builder — GET /me/interaction
       getMeInteraction: (args) => request("GET", "/me/interaction", { hasBody: false }, args),
       // PATCH /me/interaction — rank: any-builder — PATCH /me/interaction

package/clients/bongos-client/index.cjs

@@ -734,6 +734,12 @@ function createClient(opts = {}) {
       getMeGuilds: (args) => request("GET", "/me/guilds", { hasBody: false }, args),
       // PATCH /me/handle — rank: any-builder — PATCH /me/handle
       patchMeHandle: (args) => request("PATCH", "/me/handle", { hasBody: true }, args),
+      // GET /me/howto — rank: any-builder — GET /me/howto
+      getMeHowto: (args) => request("GET", "/me/howto", { hasBody: false }, args),
+      // POST /me/howto/read — rank: any-builder — POST /me/howto/read
+      postMeHowtoRead: (args) => request("POST", "/me/howto/read", { hasBody: true }, args),
+      // POST /me/howto/reset — rank: any-builder — POST /me/howto/reset
+      postMeHowtoReset: (args) => request("POST", "/me/howto/reset", { hasBody: true }, args),
       // GET /me/interaction — rank: any-builder — GET /me/interaction
       getMeInteraction: (args) => request("GET", "/me/interaction", { hasBody: false }, args),
       // PATCH /me/interaction — rank: any-builder — PATCH /me/interaction

package/clients/bongos-client/index.d.ts

@@ -429,6 +429,8 @@ export interface PostMeAnthropicLinkRequest { anthropic_email: string; anthropic
 export interface PostMeAnthropicLinkResponse { linked: unknown }
 export interface PostMeFilterViewsRequest { page: string; name: string; values: Record<string, unknown>; is_default?: boolean }
 export interface PostMeFilterViewsResponse { page: unknown; view: unknown; views: unknown }
+export interface PostMeHowtoReadRequest { steps?: unknown[]; all?: boolean; how?: string }
+export interface PostMeHowtoResetRequest { steps?: unknown[]; all?: boolean }
 export interface PostMeSessionsRevokeAllResponse { ok: boolean; revoked: unknown }
 export interface PostMeSessionsRevokeRequest { session_id?: StringifiableId }
 export interface PostMeSessionsRevokeResponse { ok: boolean; revoked: unknown }
@@ -1260,6 +1262,12 @@ export interface BongosClient {
     getMeGuilds(args?: RequestArgs): Promise<GetMeGuildsResponse>;
     /** PATCH /me/handle — rank: any-builder */
     patchMeHandle(args: RequestArgs & { body: PatchMeHandleRequest }): Promise<PatchMeHandleResponse>;
+    /** GET /me/howto — rank: any-builder */
+    getMeHowto(args?: RequestArgs): Promise<ApiResponse>;
+    /** POST /me/howto/read — rank: any-builder */
+    postMeHowtoRead(args?: RequestArgs & { body?: PostMeHowtoReadRequest }): Promise<ApiResponse>;
+    /** POST /me/howto/reset — rank: any-builder */
+    postMeHowtoReset(args?: RequestArgs & { body?: PostMeHowtoResetRequest }): Promise<ApiResponse>;
     /** GET /me/interaction — rank: any-builder */
     getMeInteraction(args?: RequestArgs): Promise<ApiResponse>;
     /** PATCH /me/interaction — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -731,6 +731,12 @@ export function createClient(opts = {}) {
       getMeGuilds: (args) => request("GET", "/me/guilds", { hasBody: false }, args),
       // PATCH /me/handle — rank: any-builder — PATCH /me/handle
       patchMeHandle: (args) => request("PATCH", "/me/handle", { hasBody: true }, args),
+      // GET /me/howto — rank: any-builder — GET /me/howto
+      getMeHowto: (args) => request("GET", "/me/howto", { hasBody: false }, args),
+      // POST /me/howto/read — rank: any-builder — POST /me/howto/read
+      postMeHowtoRead: (args) => request("POST", "/me/howto/read", { hasBody: true }, args),
+      // POST /me/howto/reset — rank: any-builder — POST /me/howto/reset
+      postMeHowtoReset: (args) => request("POST", "/me/howto/reset", { hasBody: true }, args),
       // GET /me/interaction — rank: any-builder — GET /me/interaction
       getMeInteraction: (args) => request("GET", "/me/interaction", { hasBody: false }, args),
       // PATCH /me/interaction — rank: any-builder — PATCH /me/interaction

package/docs/api/openapi.json

@@ -13518,6 +13518,121 @@
         ]
       }
     },
+    "/me/howto": {
+      "get": {
+        "operationId": "get_me_howto",
+        "tags": [
+          "me"
+        ],
+        "summary": "GET /me/howto",
+        "description": "the caller's own read state.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/onboarding.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/me/howto/read": {
+      "post": {
+        "operationId": "post_me_howto_read",
+        "tags": [
+          "me"
+        ],
+        "summary": "POST /me/howto/read",
+        "description": "marks the caller's own steps read ({ steps }) or skips the guide ({ all: true, how: 'skipped' }).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/onboarding.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostMeHowtoReadRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/me/howto/reset": {
+      "post": {
+        "operationId": "post_me_howto_reset",
+        "tags": [
+          "me"
+        ],
+        "summary": "POST /me/howto/reset",
+        "description": "forgets the caller's own marks ({ steps }, or everything when none are named).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/onboarding/routes/onboarding.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostMeHowtoResetRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/me/interaction": {
       "get": {
         "operationId": "get_me_interaction",
@@ -32403,6 +32518,36 @@
           "views"
         ]
       },
+      "PostMeHowtoReadRequest": {
+        "type": "object",
+        "properties": {
+          "steps": {
+            "type": "array",
+            "maxItems": 100
+          },
+          "all": {
+            "type": "boolean"
+          },
+          "how": {
+            "type": "string",
+            "maxLength": 16
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostMeHowtoResetRequest": {
+        "type": "object",
+        "properties": {
+          "steps": {
+            "type": "array",
+            "maxItems": 100
+          },
+          "all": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      },
       "PostMeSessionsRevokeAllResponse": {
         "type": "object",
         "properties": {
@@ -35469,8 +35614,8 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 555,
-  "x-schema-count": 592,
+  "x-endpoint-count": 558,
+  "x-schema-count": 594,
   "x-undocumented-bodies": 12,
   "x-response-schemas": 390,
   "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. 555 endpoints across 95 route files.
+> **Generated from the live route files** — the route file is authoritative. 558 endpoints across 95 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`.
@@ -489,7 +489,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/llm-cache/lookup` | `metic+archon` | `cache_key`, `tokens_saved_est` | POST /llm-cache/lookup — hit/miss + atomic hit_count bump. |
 | POST | `/api/bongos/llm-cache/store` | `metic+archon` | `spec`, `result_stdout`, `result_cost_usd` | POST /llm-cache/store — upsert a freshly-produced result. |
 
-## `me` (39)
+## `me` (42)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -512,6 +512,9 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/me/guild-requests` | `any-builder` | — | MY queue: invites addressed to me, each carrying the card (the guild's current visibility, which an accept must echo back), the join requ… |
 | GET | `/api/bongos/me/guilds` | `any-builder` | — | MY guilds, each with my own two switches. |
 | PATCH | `/api/bongos/me/handle` | `any-builder` | `handle` | rename the caller's OWN handle (own data, keyed on the authenticated github_id). |
+| GET | `/api/bongos/me/howto` | `any-builder` | — | the caller's own read state. |
+| POST | `/api/bongos/me/howto/read` | `any-builder` | `steps`, `all`, `how` | marks the caller's own steps read ({ steps }) or skips the guide ({ all: true, how: 'skipped' }). |
+| POST | `/api/bongos/me/howto/reset` | `any-builder` | `steps`, `all` | forgets the caller's own marks ({ steps }, or everything when none are named). |
 | GET | `/api/bongos/me/interaction` | `any-builder` | — | Per-builder INTERACTION PROFILE (task 2010, shares the behavior_prefs jsonb / migration 119). |
 | PATCH | `/api/bongos/me/interaction` | `any-builder` | _undocumented_ | PATCH the interaction profile. |
 | GET | `/api/bongos/me/model-allocation` | `any-builder` | — |  |

package/docs/module-api-changelog.md

@@ -3091,5 +3091,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.125 with no explicit bump. run 38761052564. (task 1002620)
   1.21.127 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.126 with no explicit bump. run 38764985266. (task 1002620)
+  1.21.128 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.127 with no explicit bump. run 38770118067. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/onboarding/howto-state.js

@@ -0,0 +1,108 @@
+// modules/onboarding/howto-state.js — each person's read/unread state for the how-to steps (task 1004634)
+//
+// WHY. The how-to guide (howto-guide.js, task 1004627) is shown one step at a time
+// at the moment it is useful, and a step once read must never be shown again — on
+// this computer or any other, in Claude or another AI tool. So the read marks live in
+// Bongos, per person (owner decision 2026-10-08), in `onboarding_howto_reads`
+// (migrations/onboarding_001_howto_reads.sql): one row per step read, unread = no row.
+//
+// Three operations, served by routes/onboarding.js under /me/howto:
+//   • readState  — every step with read / skipped / unread, the count, and the next unread
+//   • markRead   — mark steps read (or skipped); `all: true` skips the whole guide
+//   • reset      — forget some steps, or all of them, so they show again
+// Step ids are checked against the guide: an id it does not name is refused, so a
+// typo cannot store a mark nothing will ever read. Marking is idempotent and keeps the
+// FIRST read time (a re-mark does not move it), except that reading a step you had
+// skipped upgrades it to read.
+//
+// Pure of core require(): the pool comes from the doorway, or is injected (tests).
+
+'use strict';
+
+const guide = require('./howto-guide');
+
+const HOWS = Object.freeze(['read', 'skipped']);
+
+function poolFor(deps) {
+  if (deps && deps.pool) return deps.pool;
+  return require('../../src/module-api').pool;
+}
+
+// Validate a list of step ids against the guide. Returns { ok, ids } or { ok:false, unknown }.
+function checkSteps(ids) {
+  const list = [...new Set((Array.isArray(ids) ? ids : [ids]).map((s) => String(s || '').trim()).filter(Boolean))];
+  const unknown = list.filter((id) => !guide.stepById(id));
+  return unknown.length ? { ok: false, unknown } : { ok: true, ids: list };
+}
+
+// Pure: shape stored rows into the API answer, in guide order.
+function shapeState(rows) {
+  const byId = new Map((rows || []).map((r) => [r.step_id, r]));
+  const steps = guide.STEPS.map((s) => {
+    const r = byId.get(s.id);
+    return {
+      id: s.id, moment: s.moment, title: s.title,
+      state: r ? (r.how === 'skipped' ? 'skipped' : 'read') : 'unread',
+      read_at: r ? new Date(r.read_at).toISOString() : null,
+    };
+  });
+  const done = steps.filter((s) => s.state !== 'unread');
+  const next = guide.nextUnread(done.map((s) => s.id));
+  return {
+    steps,
+    total: steps.length,
+    read: steps.filter((s) => s.state === 'read').length,
+    skipped: steps.filter((s) => s.state === 'skipped').length,
+    unread: steps.length - done.length,
+    next_unread: next ? next.id : null,
+  };
+}
+
+async function readState(builderId, deps = {}) {
+  const pool = poolFor(deps);
+  const { rows } = await pool.query(
+    'SELECT step_id, how, read_at FROM onboarding_howto_reads WHERE builder_id = $1',
+    [builderId],
+  );
+  return shapeState(rows);
+}
+
+// { steps: [...] } or { all: true }; how = 'read' | 'skipped'.
+async function markRead(builderId, { steps, all = false, how = 'read' } = {}, deps = {}) {
+  if (!HOWS.includes(how)) return { ok: false, reason: 'bad_how' };
+  let ids;
+  if (all) ids = guide.STEPS.map((s) => s.id);
+  else {
+    const c = checkSteps(steps);
+    if (!c.ok) return { ok: false, reason: 'unknown_step', unknown: c.unknown };
+    if (!c.ids.length) return { ok: false, reason: 'no_steps' };
+    ids = c.ids;
+  }
+  const pool = poolFor(deps);
+  // One statement: first read time is kept; a 'skipped' row becomes 'read' when the
+  // step is read for real, never the other way round.
+  await pool.query(
+    `INSERT INTO onboarding_howto_reads (builder_id, step_id, how)
+     SELECT $1, s, $3 FROM unnest($2::text[]) AS s
+     ON CONFLICT (builder_id, step_id) DO UPDATE
+       SET how = 'read'
+       WHERE onboarding_howto_reads.how = 'skipped' AND EXCLUDED.how = 'read'`,
+    [builderId, ids, how],
+  );
+  return { ok: true, state: await readState(builderId, deps) };
+}
+
+// { steps: [...] } forgets those; no steps (or all: true) forgets every mark.
+async function reset(builderId, { steps, all = false } = {}, deps = {}) {
+  const pool = poolFor(deps);
+  if (all || steps == null || (Array.isArray(steps) && steps.length === 0)) {
+    await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id = $1', [builderId]);
+  } else {
+    const c = checkSteps(steps);
+    if (!c.ok) return { ok: false, reason: 'unknown_step', unknown: c.unknown };
+    await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id = $1 AND step_id = ANY($2::text[])', [builderId, c.ids]);
+  }
+  return { ok: true, state: await readState(builderId, deps) };
+}
+
+module.exports = { HOWS, checkSteps, shapeState, readState, markRead, reset };

package/modules/onboarding/migrations/onboarding_001_howto_reads.sql

@@ -0,0 +1,33 @@
+-- onboarding_001_howto_reads.sql — which how-to steps each person has read (task 1004634).
+--
+-- The in-session how-to guide (modules/onboarding/howto-guide.js, task 1004627) is
+-- walked one step at a time, and a step once read must never be shown again. The
+-- owner's call (2026-10-08): the read state is PER PERSON and lives in Bongos, so it
+-- follows them across computers and AI tools.
+--
+-- One row per (builder, step) that has been read. Unread = no row, so a step added to
+-- the guide later is unread for everyone with no backfill, and a reset is a DELETE.
+-- `step_id` is the guide's stable id; it is not constrained here because the guide is
+-- code — the API refuses an id the guide does not name, and a row for a step the guide
+-- later retires is simply ignored on read. `how` records whether the person read the
+-- step or skipped it (task 1004636's "skip the tutorial"), so progress can tell them
+-- apart.
+--
+-- ADDITIVE, module-owned (ADR 0083 §Decision #5). Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS onboarding_howto_reads (
+  builder_id  bigint      NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  step_id     text        NOT NULL,
+  how         text        NOT NULL DEFAULT 'read',
+  read_at     timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (builder_id, step_id),
+  CONSTRAINT onboarding_howto_reads_how_chk CHECK (how IN ('read', 'skipped')),
+  CONSTRAINT onboarding_howto_reads_step_chk CHECK (step_id ~ '^[a-z][a-z0-9_]{2,39}$')
+);
+
+INSERT INTO schema_migrations (version) VALUES ('onboarding_001_howto_reads')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/modules/onboarding/module.json

@@ -6,7 +6,7 @@
   "coreVersion": "^1.19.532",
   "default": true,
   "maintenance": { "status": "core-maintained" },
-  "contributes": { "routes": ["onboarding"] },
+  "contributes": { "routes": ["onboarding"], "migrations": true },
   "provides": ["onboarding"],
   "consumes": []
 }

package/modules/onboarding/routes/onboarding.js

@@ -37,6 +37,7 @@ const buildAccessRequestsRouter = require('./access-requests');
 const foundingBuilders = require('../founding-builders');
 const genesis = require('../genesis-home');
 const foundingBirth = require('../founding-birth');
+const howtoState = require('../howto-state');
 
 // Register the `onboarding` kernel PORT. See the header + port.js for the full
 // consumer list and the graceful-degradation contract.
@@ -58,15 +59,61 @@ module.exports = function buildOnboardingRouter() {
   // ranks page and the home's founding wall; an empty list on a project that was
   // never founded, so those surfaces render exactly as before. Signed-in, like the
   // hall pages that read it; it carries nothing the roster does not already show.
-  router.get('/founding/builders', api.requireBuilder, async (req, res) => {
+  router.get('/founding/builders', api.requireBuilder, async (_req, res) => {
     const builders = await foundingBuilders.foundingBuildersFor();
     res.set('Cache-Control', 'private, max-age=60');
     res.json({ builders });
   });
   mountGenesisRoutes(router);
+  mountHowtoRoutes(router);
   return router;
 };
 
+// ── the how-to read state (task 1004634) ─────────────────────────────────────
+// Each person's own read/unread marks for the in-session how-to guide. Self-scoped:
+// every route reads and writes only req.builder's rows, so any signed-in builder may
+// call them (the /me/wandering posture). The AI marks a step read after walking the
+// person through it (task 1004635); reopen / continue / skip use the same three calls
+// (task 1004636).
+const HOWTO_REFUSALS = { unknown_step: 422, no_steps: 422, bad_how: 422 };
+
+function mountHowtoRoutes(router) {
+  const handle = (fn) => async (req, res) => {
+    try {
+      const r = await fn(req);
+      if (r && r.ok === false) {
+        return res.status(HOWTO_REFUSALS[r.reason] || 422).json({
+          error: { code: r.reason, message: r.unknown ? `not a how-to step: ${r.unknown.join(', ')}` : r.reason },
+        });
+      }
+      res.set('Cache-Control', 'no-store');
+      res.json(r && r.state ? r.state : r);
+    } catch (err) {
+      api.logger('onboarding').error('[onboarding] howto', err);
+      res.status(500).json({ error: { code: 'howto_failed', message: 'internal error' } });
+    }
+  };
+  // rank: any-builder — the caller's own read state.
+  router.get('/me/howto', api.requireBuilder, handle((req) => howtoState.readState(req.builder.id)));
+  // rank: any-builder — marks the caller's own steps read ({ steps }) or skips the guide ({ all: true, how: 'skipped' }).
+  router.post('/me/howto/read', api.requireBuilder, (req, res, next) => {
+    if (api.validateOrRespond(req, res, {
+      steps: { type: 'array', maxItems: 100 },
+      all: { type: 'boolean' },
+      how: { type: 'string', maxLength: 16 },
+    })) return;
+    next();
+  }, handle((req) => howtoState.markRead(req.builder.id, req.body || {})));
+  // rank: any-builder — forgets the caller's own marks ({ steps }, or everything when none are named).
+  router.post('/me/howto/reset', api.requireBuilder, (req, res, next) => {
+    if (api.validateOrRespond(req, res, {
+      steps: { type: 'array', maxItems: 100 },
+      all: { type: 'boolean' },
+    })) return;
+    next();
+  }, handle((req) => howtoState.reset(req.builder.id, req.body || {})));
+}
+
 // ── the genesis home (task 1004423) ──────────────────────────────────────────
 // Read by any signed-in builder of a founding project (everyone sees where genesis
 // is); every write is the project owner's, behind the same atom that guards the

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.127",
+  "version": "1.21.128",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.127",
+      "version": "1.21.128",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.127",
+  "version": "1.21.128",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9760,5 +9760,11 @@
       "id": "1004414",
       "text": "Each hosted project now has a memory and CPU limit, so one runaway project can no longer slow down every other project or the hub."
     }
+  ],
+  "1.21.128": [
+    {
+      "id": "1004634",
+      "text": "Bongos now remembers, for each person, which how-to steps they have already seen, so the AI never shows the same tip twice, on any computer."
+    }
   ]
 }

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.127'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.128'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/howto_state.mjs

@@ -0,0 +1,178 @@
+// tests/howto_state.mjs — per-person read/unread state for the how-to steps (task 1004634)
+//
+// Two halves. The DB-free half drives howto-state.js against an in-memory pool that
+// honours the three statements it issues, so the contract runs everywhere: unread by
+// default, mark read, skip all, a read upgrades a skip (never the reverse), the first
+// read time is kept, reset some or all, and an id the guide does not name is refused.
+// The DB half applies the real migration and runs the same calls against Postgres; it
+// skips when no Postgres is reachable (DATABASE_URL), like copy_desk_flags_db.mjs.
+//
+// Run:  node tests/howto_state.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+const hs = require('../modules/onboarding/howto-state.js');
+const guide = require('../modules/onboarding/howto-guide.js');
+const ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// An in-memory stand-in for the three statements howto-state.js runs.
+function fakePool() {
+  const rows = new Map(); // `${b}|${step}` → { builder_id, step_id, how, read_at }
+  let clock = 0;
+  return {
+    rows,
+    async query(sql, params) {
+      if (/^SELECT step_id/.test(sql)) {
+        return { rows: [...rows.values()].filter((r) => r.builder_id === params[0]) };
+      }
+      if (/^INSERT INTO onboarding_howto_reads/.test(sql)) {
+        const [b, ids, how] = params;
+        for (const s of ids) {
+          const k = `${b}|${s}`;
+          const cur = rows.get(k);
+          if (!cur) rows.set(k, { builder_id: b, step_id: s, how, read_at: new Date(1e12 + ++clock * 1000) });
+          else if (cur.how === 'skipped' && how === 'read') cur.how = 'read';
+        }
+        return { rows: [] };
+      }
+      if (/^DELETE FROM onboarding_howto_reads WHERE builder_id = \$1 AND/.test(sql)) {
+        for (const s of params[1]) rows.delete(`${params[0]}|${s}`);
+        return { rows: [] };
+      }
+      if (/^DELETE FROM onboarding_howto_reads WHERE builder_id = \$1$/.test(sql)) {
+        for (const [k, r] of rows) if (r.builder_id === params[0]) rows.delete(k);
+        return { rows: [] };
+      }
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+  };
+}
+
+async function contract(label, deps, A, B) {
+  const first = guide.STEPS[0].id;
+  const second = guide.STEPS[1].id;
+
+  await test(`${label}: a new person has every step unread, next is the first`, async () => {
+    const s = await hs.readState(A, deps);
+    assert.equal(s.total, guide.STEPS.length);
+    assert.equal(s.unread, s.total);
+    assert.equal(s.next_unread, first);
+    assert.ok(s.steps.every((x) => x.state === 'unread' && x.read_at === null));
+  });
+
+  await test(`${label}: mark one read → it is read, next moves on, other people untouched`, async () => {
+    const r = await hs.markRead(A, { steps: [first] }, deps);
+    assert.equal(r.ok, true);
+    assert.equal(r.state.read, 1);
+    assert.equal(r.state.next_unread, second);
+    assert.equal(r.state.steps[0].state, 'read');
+    assert.ok(r.state.steps[0].read_at);
+    const other = await hs.readState(B, deps);
+    assert.equal(other.read, 0, 'per person');
+  });
+
+  await test(`${label}: re-marking keeps the first read time (idempotent)`, async () => {
+    const before = (await hs.readState(A, deps)).steps[0].read_at;
+    await hs.markRead(A, { steps: [first] }, deps);
+    assert.equal((await hs.readState(A, deps)).steps[0].read_at, before);
+  });
+
+  await test(`${label}: an unknown step id is refused and nothing is stored`, async () => {
+    const r = await hs.markRead(A, { steps: [second, 'not_a_step'] }, deps);
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'unknown_step');
+    assert.deepEqual(r.unknown, ['not_a_step']);
+    assert.equal((await hs.readState(A, deps)).read, 1);
+    assert.equal((await hs.markRead(A, { steps: [] }, deps)).reason, 'no_steps');
+    assert.equal((await hs.markRead(A, { steps: [second], how: 'seen' }, deps)).reason, 'bad_how');
+  });
+
+  await test(`${label}: skip all marks every other step skipped; nothing left unread`, async () => {
+    const r = await hs.markRead(A, { all: true, how: 'skipped' }, deps);
+    assert.equal(r.state.unread, 0);
+    assert.equal(r.state.next_unread, null);
+    assert.equal(r.state.read, 1, 'the step already read stays read');
+    assert.equal(r.state.skipped, guide.STEPS.length - 1);
+  });
+
+  await test(`${label}: reading a skipped step upgrades it; skipping a read one does not downgrade`, async () => {
+    await hs.markRead(A, { steps: [second] }, deps);
+    let s = await hs.readState(A, deps);
+    assert.equal(s.steps[1].state, 'read');
+    await hs.markRead(A, { steps: [second], how: 'skipped' }, deps);
+    s = await hs.readState(A, deps);
+    assert.equal(s.steps[1].state, 'read');
+  });
+
+  await test(`${label}: reset some steps, then reset everything`, async () => {
+    let r = await hs.reset(A, { steps: [first] }, deps);
+    assert.equal(r.state.steps[0].state, 'unread');
+    assert.equal(r.state.next_unread, first);
+    assert.equal((await hs.reset(A, { steps: ['nope_nope'] }, deps)).reason, 'unknown_step');
+    r = await hs.reset(A, {}, deps);
+    assert.equal(r.state.unread, guide.STEPS.length);
+  });
+}
+
+await test('shapeState ignores a stored mark for a step the guide no longer has', async () => {
+  const s = hs.shapeState([{ step_id: 'retired_step', how: 'read', read_at: new Date() }]);
+  assert.equal(s.read, 0);
+  assert.equal(s.total, guide.STEPS.length);
+});
+
+await test('the module declares its migration and the routes are mounted', async () => {
+  const mod = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/onboarding/module.json'), 'utf8'));
+  assert.equal(mod.contributes.migrations, true);
+  assert.ok(fs.existsSync(path.join(ROOT, 'modules/onboarding/migrations/onboarding_001_howto_reads.sql')));
+  const src = fs.readFileSync(path.join(ROOT, 'modules/onboarding/routes/onboarding.js'), 'utf8');
+  for (const r of ["router.get('/me/howto'", "router.post('/me/howto/read'", "router.post('/me/howto/reset'"]) assert.ok(src.includes(r), r);
+});
+
+await contract('in-memory', { pool: fakePool() }, 1, 2);
+
+// ── the real database ────────────────────────────────────────────────────────
+const { Pool } = require('pg');
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+let dbUp = true;
+try { await pool.query('SELECT 1'); } catch (e) {
+  dbUp = false;
+  console.log(`  (db half SKIPPED — no reachable Postgres: ${e.code || e.message}. Set DATABASE_URL to run.)`);
+}
+if (dbUp) {
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY);
+    CREATE TABLE IF NOT EXISTS builders (id bigserial PRIMARY KEY, github_login text);
+  `);
+  await pool.query(fs.readFileSync(path.join(ROOT, 'modules/onboarding/migrations/onboarding_001_howto_reads.sql'), 'utf8'));
+  await pool.query(fs.readFileSync(path.join(ROOT, 'modules/onboarding/migrations/onboarding_001_howto_reads.sql'), 'utf8')); // idempotent
+  const A = 910000001;
+  const B = 910000002;
+  await pool.query('INSERT INTO builders (id, github_login) VALUES ($1, $2), ($3, $4) ON CONFLICT (id) DO NOTHING', [A, 'howto-a', B, 'howto-b']);
+  await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id IN ($1, $2)', [A, B]);
+  try {
+    await contract('postgres', { pool }, A, B);
+    await test('postgres: the CHECK refuses a malformed step id and a bad how', async () => {
+      await assert.rejects(pool.query("INSERT INTO onboarding_howto_reads (builder_id, step_id) VALUES ($1, 'Bad Id')", [A]));
+      await assert.rejects(pool.query("INSERT INTO onboarding_howto_reads (builder_id, step_id, how) VALUES ($1, 'welcome', 'seen')", [A]));
+    });
+  } finally {
+    await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id IN ($1, $2)', [A, B]).catch(() => {});
+    await pool.query('DELETE FROM builders WHERE id IN ($1, $2)', [A, B]).catch(() => {});
+  }
+}
+await pool.end().catch(() => {});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/own_scope_guard.mjs

@@ -164,6 +164,12 @@ const OWN_SCOPED_SURFACES = [
       },
     ],
   },
+  {
+    file: 'modules/onboarding/routes/onboarding.js',
+    why: "the how-to read state (task 1004634). GET /me/howto and POST /me/howto/read|reset read and write the CALLER's own marks, keyed on req.builder.id; the body names step ids, never a builder. The rest of the router is /founding/*, whose one path param names a founding STAGE, not a builder.",
+    minOwnScoped: 1,
+    crossOwner: [],
+  },
 ];
 
 // Floors that keep this guard from going quietly vacuous (a regex that stops