@bongos/core 1.21.126 → 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.126",
-  "core_contract": "1.21.126",
-  "source_commit": "94a48727259da5ad6269d8e1982648c5a263116b",
+  "core_version": "1.21.128",
+  "core_contract": "1.21.128",
+  "source_commit": "31d87d7e4b4e2c97040083251efcd43c9c97c935",
   "source_ref": "HEAD",
-  "built_at": "2026-10-15T15:32:06.327Z",
+  "built_at": "2026-10-15T16:35:02.176Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 606,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3133,
+    "functional_verbatim": 3141,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3768,
-  "tree_sha256": "aaa23a52f299e82601309b1dc11007fe842e9686674c9c5cc96991f5412286e3",
+  "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",
@@ -1887,7 +1887,7 @@
     {
       "path": "docs/adr/0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md",
       "mode": "0000644",
-      "sha256": "6043bb19c2b18074c132750b0480b03f627733536c3263ab79c049f40f314e57"
+      "sha256": "957ee2f99f8b8ac8a22723c7af73798540499a0ea859f010decb87b09cf0a02f"
     },
     {
       "path": "docs/adr/0286-a-gated-project-s-manifest-tells-a-stranger-how-to-sign-in-and-nothing-else.md",
@@ -2232,7 +2232,7 @@
     {
       "path": "docs/adr/0354-a-builder-hosts-one-project-free-and-more-takes-the-fleet-permission.md",
       "mode": "0000644",
-      "sha256": "962d868c0887244c53b53c58754f7232715a20df6feec694f30cbda707f9e17e"
+      "sha256": "47b6fbbe4da97fd83f1b7e9914f102bbd5924d88b02dca6d87a4e2cf44af8664"
     },
     {
       "path": "docs/adr/0355-a-soft-limit-is-a-rule-with-a-reason-and-nobody-enforces-it.md",
@@ -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": "8b70cfa6cac3da1e08d0f969f6d2a3f0c43ca0533b28d7e8a58ca12044165c26"
+      "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": "341426e0e35db5113dd017485f4479dc0674db124643388aeec9d883e113f7e3"
+      "sha256": "b7d2956b1155f633fbfbbfafe4211befef0d545b02671ce8cd9096ee22a1f734"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f5522e5c98564bbf8ffd3a4817e094732239f369a1850e1b743030a4b03d00b2"
+      "sha256": "4cbf0ddd56ffbee1d0d4cdd8388793c2590a243737608cf18556e0400e946fed"
     },
     {
       "path": "public-docs/index.html",
@@ -10507,7 +10517,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "4fbea8b3dd2714eb5ec49751e18f66a0b995e94d64163edfbbf5fa837b196d81"
+      "sha256": "f5b81f238e17e854f85e2af52d9c3661acf519c8bd9634aaa95206e8f107bc5b"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -11022,7 +11032,7 @@
     {
       "path": "scripts/gds/exec-path-guard.js",
       "mode": "0000644",
-      "sha256": "cda9e125cfb2cb354c7d4e20065c36712a75955d3981203012c2334d0ce637ae"
+      "sha256": "5b5f2b8b40d62dab10a0ea9b43768944dcbe60a8af550b35229ce278deaceffc"
     },
     {
       "path": "scripts/gds/feedback-send.js",
@@ -11097,7 +11107,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "88a99a1a1455477dd9f7987c0f6c48f20464cc4ab98cc2f224c1a5536483fd2d"
+      "sha256": "e2f483de1afd806d77fc5b62d6f1b08d762ea4fec9eaddb91d2ef1f25f00112e"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -11404,6 +11414,11 @@
       "mode": "0000644",
       "sha256": "b21c85714a8b93e43857c26237eec9dca9830abb53f44146957525f262fb8e7b"
     },
+    {
+      "path": "scripts/gds/module-error-report.js",
+      "mode": "0000644",
+      "sha256": "dc8e6794d0c09479891136c8b0ab4da7ce73c1797522e03b9457db113b2534e2"
+    },
     {
       "path": "scripts/gds/module-test-runner.js",
       "mode": "0000644",
@@ -11422,7 +11437,7 @@
     {
       "path": "scripts/gds/module.js",
       "mode": "0000644",
-      "sha256": "b02d07e9e7e1d2e2852676383e054f13d8e423755534fe23ed3e10cbfefb4086"
+      "sha256": "9391cc7d6881150cd5d196aa5e63245db032093063ce90e1e1ae5c26dafcb49c"
     },
     {
       "path": "scripts/gds/move-escalation.js",
@@ -11549,6 +11564,11 @@
       "mode": "0000644",
       "sha256": "2102af404ac985f0d7b037da973600234b2ef8f90b6c689ca164b9ac1f46262f"
     },
+    {
+      "path": "scripts/gds/provision-caps.js",
+      "mode": "0000644",
+      "sha256": "0dee61336a309cf3eda2cb715bb53680773c17d65186864384e3cb0bc9dadaba"
+    },
     {
       "path": "scripts/gds/provision-config.js",
       "mode": "0000644",
@@ -11587,7 +11607,7 @@
     {
       "path": "scripts/gds/provision-process.js",
       "mode": "0000644",
-      "sha256": "6a784f63078e5cb2c0f85475672b02b18ded67a36a8041b1ba3643b227a465d0"
+      "sha256": "4689867d4925672e3e12c56620ef2e4e6ad2474dfaaa309571da9533af49b997"
     },
     {
       "path": "scripts/gds/provision-render.js",
@@ -11617,12 +11637,12 @@
     {
       "path": "scripts/gds/provision-units.js",
       "mode": "0000644",
-      "sha256": "eb6cf09ce1eb97330b20fe97c61068e2b7cc8bb4556a54df39e3a3978fe6ffa2"
+      "sha256": "02173656cffc347b23b68fa5036826d16bfedbb0e490161b8e5853b5cbb9b8a9"
     },
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "ea11cc49dbc298c8b3ed4ad88e25a3acfbba65fcd65727c9b47c43ee41e24437"
+      "sha256": "bf16a2ef196d64088c7755e3d6ccbdd8f7917eb907efdbb8ec132e7df9694a52"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -12847,17 +12867,22 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "05cbabab7a15ea12d403cdce32d0e9accfb56fe1dc44c691dc5e8920933edaf0"
+      "sha256": "638e7c6e9ff2e460bacc69abc98b8f6721b6d2ade29ba79aa166920e1f71f7e7"
     },
     {
       "path": "src/module-loader/catalog.js",
       "mode": "0000644",
       "sha256": "633042ab3228780fd18f96ce6a2dd0d84452a124948720678d4484c29df0acd8"
     },
+    {
+      "path": "src/module-loader/error-tally.js",
+      "mode": "0000644",
+      "sha256": "00f37bb206c47a75c5ee1420831781a38eb88b9446a9ce1cc3e8ee5a47e09334"
+    },
     {
       "path": "src/module-loader/loader.js",
       "mode": "0000644",
-      "sha256": "04458c645d876011324e5ae11011774699c06e39ff2fa1ba1cf58a2d2775f887"
+      "sha256": "4520d7cb0a91dd3f6cb52c52ced8caf2039126fa7c942e3f0714e91600cebb80"
     },
     {
       "path": "src/module-loader/manifest-schema.js",
@@ -12892,7 +12917,7 @@
     {
       "path": "src/platform-server.js",
       "mode": "0000644",
-      "sha256": "773372a16a32d3936aa53d0ca5ec0e19833e45cadcc16688102b5e81c117e5bf"
+      "sha256": "435a89e5f5becab510ee5ad3f4246f34ee6a6abac859d49823edc74fd1bcdf4f"
     },
     {
       "path": "src/role-responsibilities.js",
@@ -15624,6 +15649,11 @@
       "mode": "0000644",
       "sha256": "8e9b206fdde738f289bc11e204852595e9128b523cfc20cd67e3e83fb60a2fac"
     },
+    {
+      "path": "tests/howto_state.mjs",
+      "mode": "0000644",
+      "sha256": "8b8d3eeeffd1bb7d0deaec51c91165b06302737b72b1a710547340c7ecadcec6"
+    },
     {
       "path": "tests/html_comment_nesting.mjs",
       "mode": "0000644",
@@ -16409,6 +16439,11 @@
       "mode": "0000644",
       "sha256": "50e4d45bf544efe755dda538a93eafc40dcd9caa071e987d8833d97ecf1b7e0f"
     },
+    {
+      "path": "tests/module_error_counts.mjs",
+      "mode": "0000644",
+      "sha256": "7c5e8009a416c72d5659677c0a23d90408001f33ff6b56b121ed06a2beceb739"
+    },
     {
       "path": "tests/module_exports_unique_keys.mjs",
       "mode": "0000644",
@@ -16702,7 +16737,7 @@
     {
       "path": "tests/own_scope_guard.mjs",
       "mode": "0000644",
-      "sha256": "e9ad80ce9837076d550dbb4b77a4c0f01f087ad3e515f8af8a672221af995ca4"
+      "sha256": "cdd964e66b9ebe74c504a3916eb3a10b36497af4f5b94924534d2d73f136801a"
     },
     {
       "path": "tests/own_session_revoke.mjs",
@@ -17132,7 +17167,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "2c31c74c71147c5fe96beb8e6a53f8793ea3f42870512a6005f43df7c6fb5382"
+      "sha256": "dc30483813143d76ed6597f4b68d61db3dd2ae9bf34d15b9ce8ddd57caf0f79f"
     },
     {
       "path": "tests/provision_account_identity.mjs",
@@ -17169,6 +17204,11 @@
       "mode": "0000644",
       "sha256": "f99d0a4a54fa9d846efc772148156e06023d3ad4e2afbddce8dd1d9a62821b96"
     },
+    {
+      "path": "tests/provision_resource_caps.mjs",
+      "mode": "0000644",
+      "sha256": "491c29cbeee40a677a01ee71f1f54a787017456b4baa8416219480f337e3c3e3"
+    },
     {
       "path": "tests/provision_restart.mjs",
       "mode": "0000644",

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/adr/0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md

@@ -80,3 +80,9 @@ The measured cost is the same **unit** for `co-tenant` and `standalone`. What se
 - **+** Billing has a unit cost for a shared slot.
 - **−** The page-cache reserve is an allowance, not a measurement. If a ceiling is ever approached, re-measure `MemAvailable` then instead of trusting the 250 MB.
 - **−** These are **idle-fleet** numbers. A project with real traffic or large data will sit above 80 MB, so the ceiling is an upper bound for quiet projects. Re-measure the same way (`Pss` + `SwapPss` per unit, `memory.peak`, `pg_stat_activity`) as projects gain users.
+
+## Amendment — 2026-10-15 (task 1004414): each hosted project is capped
+
+**The owner's numbers**, sized from the measurement above: `MemoryHigh=160M`, `MemoryMax=256M`, `CPUQuota=50%`, `TasksMax=256` on every hosted project's unit. A project idles at 45–70 MB and its boot peak is 118–134 MB with page cache, so `MemoryHigh` sits above the boot peak and makes the kernel reclaim before `MemoryMax` kills. A killed project comes back through `Restart=always`. Half a core is about a thousand times the measured idle use, and 256 tasks is far above what one Node process starts. The caps bound one runaway project; they do not change the ceiling, which still counts ~80 MB per project.
+
+New units render the caps (`serviceUnit`). An existing unit takes them with `systemctl set-property`, live and without a restart, through `node scripts/gds/provision.js apply-caps --apply` on the control plane. The unit file is not rewritten, because a project made before the per-instance accounts (task 1003369) would be moved onto an account that does not exist. The numbers live in `scripts/gds/provision-caps.js`, and `tests/provision_resource_caps.mjs` pins them, so changing one is a decision. A project with real traffic or an adopted repo with heavy dependencies may need more; re-measure as above before raising them.

package/docs/adr/0354-a-builder-hosts-one-project-free-and-more-takes-the-fleet-permission.md

@@ -36,7 +36,7 @@ The count and the insert are two separate steps, so two requests sent together w
 ## Consequences
 
 - New users can create a project from the wizard again. Each project costs us about $0.80 a month (ADR 0285).
-- A stranger's code now runs on the shared box, on the same server as the hub. It runs in its own locked account (task 1003369), and the hub's sign-in cookie no longer reaches project halls (task 1004357). **Nothing caps a hosted project's memory or CPU**, so one misbehaving project can slow every hall and the hub. That was already true of every hosted project; this decision widens who can have one.
+- A stranger's code now runs on the shared box, on the same server as the hub. It runs in its own locked account (task 1003369), and the hub's sign-in cookie no longer reaches project halls (task 1004357). **Nothing caps a hosted project's memory or CPU**, so one misbehaving project can slow every hall and the hub. That was already true of every hosted project; this decision widens who can have one. (Closed by task 1004414: each hosted project is now capped. See the ADR 0285 amendment.)
 - Each first-free request holds one database connection from its count to its insert. Creates are rare, so the pool can carry it.
 
 ## Alternatives considered

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

@@ -3089,5 +3089,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.124 with no explicit bump. run 38759002066. (task 1002620)
   1.21.126 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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)
 ---------------------------------------------------------------------------
 ```