@bongos/core 1.21.128 → 1.21.130

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.128",
-  "core_contract": "1.21.128",
-  "source_commit": "31d87d7e4b4e2c97040083251efcd43c9c97c935",
+  "core_version": "1.21.130",
+  "core_contract": "1.21.130",
+  "source_commit": "d9a1489516436c9e34730e3c028f4465cfd62474",
   "source_ref": "HEAD",
-  "built_at": "2026-10-15T16:35:02.176Z",
+  "built_at": "2026-10-15T17:14:20.940Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 606,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3141,
+    "functional_verbatim": 3146,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3776,
-  "tree_sha256": "63aa30ff5172b9c025bc2092a63f9109f261f2a5d46b47638378c0505428b3f4",
+  "file_count": 3781,
+  "tree_sha256": "309831afd3ba5a2aed6ebe90ff918936d2c3fd2ea36d1fb2a90e41b7187cb474",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -312,7 +312,7 @@
     {
       "path": "bin/bongos.js",
       "mode": "0000755",
-      "sha256": "f2a64dc742bb1f13938840c9f294ea7a60f1895dc9366200e33d53891e5e0fe5"
+      "sha256": "656e91004fc2236dfd121dd3f46848ba5a51331c2eb17095398eb30a5255b7ef"
     },
     {
       "path": "clients/bongos-client/README.md",
@@ -2387,7 +2387,7 @@
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "688331d1b50b20cca58d8a3addd72776f9531e5360635f1486f992b9793c0ec2"
+      "sha256": "fca9878d8501b33c0258045f61365a90e60e148c2b730b00a83a6f4f89b79b8d"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2912,7 +2912,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "ceb857cecd0293bad85a5e2a33f592c4b1e6a025e9fe597af6f70846554fa07c"
+      "sha256": "18a6694f80109250c168809eb753e4d4f8c7c62d5eed96b9bee217d89189decf"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f5e9ba961f5fad8945bbcba2e6daefdde31efba3e6e6b41dde6d52aa06b07065"
+      "sha256": "a8659f105f89cd130c2772293c07aad2e7071ef6adc4c094e65fad8ac205a2ad"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4154,6 +4154,11 @@
       "mode": "0000644",
       "sha256": "75381af0ac96645f2f8fe254f609c75d2fa83bc2fc1f13887c23165fc8eed58e"
     },
+    {
+      "path": "migrations/core_276_module_release_channels.sql",
+      "mode": "0000644",
+      "sha256": "550884fa117e707b65f5c56faca0e4e3850905db94d3f275cad5d520aa68db03"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -7932,7 +7937,12 @@
     {
       "path": "modules/onboarding/howto-guide.js",
       "mode": "0000644",
-      "sha256": "18984c946d746da66ff7678379e9f49c9cfdcdb8f70d2acd852ab29c820baad0"
+      "sha256": "7b352dda65b04f44e48feb19fc3a959d9a122411c22f2830b9cc967d1a0f6852"
+    },
+    {
+      "path": "modules/onboarding/howto-moments.js",
+      "mode": "0000644",
+      "sha256": "6950e77759f8e574187e7e77871e28492116c3c5ad17d3cd2cebd3a018c0ad6c"
     },
     {
       "path": "modules/onboarding/howto-state.js",
@@ -10492,12 +10502,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b7d2956b1155f633fbfbbfafe4211befef0d545b02671ce8cd9096ee22a1f734"
+      "sha256": "1556b57526d416a0156c23915ba0aaf080eef4732031261f80c7a2c891f49b9d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4cbf0ddd56ffbee1d0d4cdd8388793c2590a243737608cf18556e0400e946fed"
+      "sha256": "5db6c25e29a3abec630266149723a99b09a249bcc375bca40e39bcc8eb5a0d2b"
     },
     {
       "path": "public-docs/index.html",
@@ -10517,7 +10527,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "f5b81f238e17e854f85e2af52d9c3661acf519c8bd9634aaa95206e8f107bc5b"
+      "sha256": "52d4fa7c27b8a7cfe9ead4896e254d332b1abae140b60beb8c848efa1e16fa2f"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10842,7 +10852,7 @@
     {
       "path": "scripts/gds/claude-md-template.js",
       "mode": "0000644",
-      "sha256": "d8560389c6a72cda1f7fe958af67b943e825b68fdd8f0fa28bf9143e42a1ece9"
+      "sha256": "ebfbfe3e5dbd865b5699d65fd7f3fc345f992c92f84b41db716295c40553dacb"
     },
     {
       "path": "scripts/gds/cleanup-orphans.js",
@@ -11249,6 +11259,11 @@
       "mode": "0000644",
       "sha256": "b7c61201d165b8c2b7e51b3a057153c3c7238bfc8bd55412acaf0ba87acd367d"
     },
+    {
+      "path": "scripts/gds/howto.js",
+      "mode": "0000644",
+      "sha256": "06c77dee345d93604e5d1bde431476399e858556897114bae368ed513d3a944c"
+    },
     {
       "path": "scripts/gds/http-api-client.js",
       "mode": "0000644",
@@ -12867,7 +12882,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "638e7c6e9ff2e460bacc69abc98b8f6721b6d2ade29ba79aa166920e1f71f7e7"
+      "sha256": "7c374bdf850a487a15f60f8ddd21aec96c49f644a50b396d1567a1e227bf4e0c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13782,7 +13797,7 @@
     {
       "path": "tests/conductor_main_e2e.mjs",
       "mode": "0000644",
-      "sha256": "807eb68a5149ee73868f814ebeef254725a4baecdfbb4d08b9b483fd8d579c73"
+      "sha256": "5d825f686bbe5351def658bf6e2f011e3ca351312f04009500ee65c8a195914d"
     },
     {
       "path": "tests/confirm_attribution.mjs",
@@ -15647,7 +15662,12 @@
     {
       "path": "tests/howto_guide.mjs",
       "mode": "0000644",
-      "sha256": "8e9b206fdde738f289bc11e204852595e9128b523cfc20cd67e3e83fb60a2fac"
+      "sha256": "72b439c6189e78bed945ec7e16da9cfeb32e34c9f3a4417f024c32dec07a73cf"
+    },
+    {
+      "path": "tests/howto_moments.mjs",
+      "mode": "0000644",
+      "sha256": "fc668c29944ddbbc629e9ee4e6c30dc1cffbc88d12f478a1b95a4585e360a185"
     },
     {
       "path": "tests/howto_state.mjs",
@@ -16474,6 +16494,11 @@
       "mode": "0000644",
       "sha256": "4f5a0c6e24d3883a156798f17c485183cf73be2cf3a0e0c610d5014a142909e5"
     },
+    {
+      "path": "tests/module_release_channels.mjs",
+      "mode": "0000644",
+      "sha256": "8607f9b60a6094296b005def559eb3cfa6861add5bfa473d9264a3dc4025bf44"
+    },
     {
       "path": "tests/module_route_rank.mjs",
       "mode": "0000644",

package/bin/bongos.js

@@ -82,6 +82,7 @@ const VERBS = {
   status:  { script: 'status.js',  group: 'work', summary: 'Version / criterion progress  (bongos status C8)', selfHelp: true },
   recall:  { script: 'recall.js',  group: 'work', summary: 'Search the docs + project knowledge  (bongos recall "x")' },
   cost:    { script: 'cost.js',    group: 'work', summary: 'Log a cost entry' },
+  howto:   { script: 'howto.js',   group: 'work', summary: 'The how-to guide: show the unread steps for a moment  (bongos howto moment first_open)' },
 
   login:   { script: 'login.js',  group: 'account', summary: 'Sign in to an instance  (bongos login <url> — browser click, no paste)' },
   setup:   { script: 'setup.js',  group: 'account', summary: 'Full builder setup on this instance (art key, disciplines, consent)' },

package/docs/architecture.md

@@ -251,6 +251,18 @@ store_module_prices(id, module_key, price_cents, price_credits, set_by, set_at)
               -- in that currency, at least one must be set.
 ```
 
+Module release channels (migration `core_276`, task 1003815, [ADR 0344](adr/0344-a-tester-is-a-project-that-opts-in-once.md) — which channel a published version is on; the data only, the tester-first publish, promotion gate and channel-aware install are their own tasks):
+
+```
+store_release_channels(channel PK, description, serves_installs, sort_order, created_at)
+              -- rows, not a CHECK: tester + general serve installs, withdrawn never does;
+              -- a new channel is an INSERT, not a schema change.
+store_module_version_channels(id, version_id FK store_module_versions, channel FK,
+              reason short code, set_by builder | NULL (system), set_at)
+              -- history; newest row per version is current. Pre-existing versions were
+              -- backfilled to general ('predates_staged_rollout').
+```
+
 Module entitlements (migration `core_259`, task 1003813 — who holds which module, at which version; the record install, update and the telemetry signals consult; it records ownership, never payment — area 8 owns money):
 
 ```

package/docs/file-map.md

@@ -169,6 +169,7 @@
 │       ├── linkify-refs.js      ← rewrite bare `#NNN` task refs across ALL docs → status-dashboard permalinks (stops GitHub's PR/issue autolinker mis-linking them); conservative classifier, token-free id list via /public/ref-ids; --apply / --check (CI gate: tests/linkify_check.mjs, in the required `unit` check) / --dry-run default ([#604](https://example.com/builders#/task/604), [#653](https://example.com/builders#/task/653)).
 │       ├── release.js           ← resolve claim as abandoned (`/builder-release`)
 │       ├── cost.js              ← log a cost entry (`/builder-cost`)
+│       ├── howto.js             ← the how-to guide for AI tools without hooks: `bongos howto moment <id>` prints + marks read the person's unread steps for a moment (task 1004635); `show` / `next` / `skip` / `reset` reopen the guide, continue it, turn it off or start it over (task 1004636)
 │       ├── me.js                ← current builder profile + leaderboard
 │       ├── goal.js              ← goal board CLI: `list` (rollup per goal) + `show <id>` (criteria, tasks, waits-on, next claimable)
 │       ├── seed-v3-tasks.js     ← V3 Planning Session #1: 80 net-new GDS-V3 tasks (V3.R01–V3.R89) + 10 idea_inbox promotions; idempotent on source_ref
@@ -472,7 +473,7 @@ To install on a new machine, symlink each routine's directory under `~/.claude/s
 ├── rank-change-greeting.js   ← promotion/demotion greeting (V3.R28 #249); spawned by session-start.js, also runnable standalone
 ├── pull-memory.js            ← memory pull-on-session-start (V3.R56 #275); spawned by session-start.js (kill-switches: OTB_MEMORY_PULL_OFF / OTB_SUBAGENT)
 ├── recall-hints.js           ← SessionStart: when the session opens holding a claim, surface the top project-knowledge hits for that task via POST /api/bongos/search (#963/V4.R25, ADR 0060)
-├── conductor.js              ← UserPromptSubmit: MAS Conductor advisory + dispatch directive (#427/#439); self-gates on OTB_CONDUCTOR_OFF / OTB_SUBAGENT
+├── conductor.js              ← UserPromptSubmit: MAS Conductor advisory + dispatch directive (#427/#439); self-gates on OTB_CONDUCTOR_OFF / OTB_SUBAGENT; also delivers the how-to step for the moment and marks it read (task 1004635)
 ├── session-cards.js          ← UserPromptSubmit: deterministic delivery of READ-ONLY in-session cards (builder-start, status) — pre-renders the card + injects a one-step render directive (task 1288)
 ├── lifecycle-card.js         ← PostToolUse (Bash|PowerShell): deterministic delivery of MUTATING lifecycle cards (claim/ship/release) — the write-side mirror of session-cards.js (task 1288)
 ├── stuck-detector.js         ← PostToolUse + PostToolUseFailure (Bash|PowerShell): the third time one session hits the same wall — the same `[otb-plain]` card for the same task id, or the same red check — it injects ONE instruction: stop retrying, diagnose (path named), or /ask-for-help. Never blocks; silent with no card; kill-switch BONGOS_STUCK_DETECTOR_OFF=1 (task 1003990)

package/docs/module-api-changelog.md

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

package/migrations/core_276_module_release_channels.sql

@@ -0,0 +1,73 @@
+-- core_276_module_release_channels.sql — which release channel each published
+-- module version sits on: tester first, then general (ADR 0344).
+--
+-- task 1003815 (goal 1000091, working area 5). ADR 0344 D2/D3: every new version
+-- goes to the tester channel first, and moves to general after seven days or on
+-- evidence. This is the DATA ONLY. Putting a new version on tester (task 1003803),
+-- the promotion gate (task 1003804) and install/update honouring the channel
+-- (task 1003805) are their own tasks and read/write these tables.
+--
+--   store_release_channels          the channels that exist, as ROWS, not a CHECK
+--                                   or a boolean. Two serve installs today
+--                                   (tester, general); 'withdrawn' is the third,
+--                                   for a version taken back. A fourth is an
+--                                   INSERT here, never a schema change — the
+--                                   retrofit the task warns about.
+--                                   `serves_installs` says whether a project can
+--                                   be handed a version on that channel; a
+--                                   withdrawn version is never handed out, but a
+--                                   copy already installed keeps working (ADR
+--                                   0338 D2 — nothing here can reach it).
+--   store_module_version_channels   the HISTORY of a version's channel. A channel
+--                                   is a property of a version, not of a module,
+--                                   and store_module_versions is immutable, so a
+--                                   move is a new row and the CURRENT channel is
+--                                   the newest row per version. The history is
+--                                   what lets the promotion gate answer "how long
+--                                   has this been on tester" and who moved it.
+--                                   `set_by` is NULL when the system moved it
+--                                   (the seven-day promotion); `reason` is a
+--                                   short code, never free text.
+--
+-- Versions published before this migration were never on a tester channel, so
+-- each gets one 'general' row with reason 'predates_staged_rollout' — every
+-- version then has a current channel, and nothing already offered to everyone is
+-- taken away from them.
+--
+-- Additive only (two new tables, rows inserted). Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS store_release_channels (
+  channel          text PRIMARY KEY
+                     CHECK (channel ~ '^[a-z][a-z0-9_]{0,31}$'),
+  description      text NOT NULL,
+  serves_installs  boolean NOT NULL,
+  sort_order       integer NOT NULL,
+  created_at       timestamptz NOT NULL DEFAULT now()
+);
+
+INSERT INTO store_release_channels (channel, description, serves_installs, sort_order) VALUES
+  ('tester',    'New versions land here first; only projects that opted in to testing get them (ADR 0344 D1).', true,  10),
+  ('general',   'Offered to every project that has the module.',                                                  true,  20),
+  ('withdrawn', 'Taken back: never handed out again; copies already installed keep working (ADR 0338 D2).',    false, 90)
+ON CONFLICT (channel) DO NOTHING;
+
+CREATE TABLE IF NOT EXISTS store_module_version_channels (
+  id          bigserial PRIMARY KEY,
+  version_id  bigint NOT NULL REFERENCES store_module_versions(id),
+  channel     text NOT NULL REFERENCES store_release_channels(channel),
+  reason      text NOT NULL CHECK (reason ~ '^[a-z][a-z0-9_]{0,39}$'),
+  set_by      bigint REFERENCES builders(id),
+  set_at      timestamptz NOT NULL DEFAULT now()
+);
+
+-- The current channel is the newest row per version; this index answers it.
+CREATE INDEX IF NOT EXISTS idx_store_module_version_channels_current
+  ON store_module_version_channels (version_id, set_at DESC, id DESC);
+
+INSERT INTO store_module_version_channels (version_id, channel, reason)
+SELECT v.id, 'general', 'predates_staged_rollout'
+  FROM store_module_versions v
+ WHERE NOT EXISTS (SELECT 1 FROM store_module_version_channels c WHERE c.version_id = v.id);
+
+INSERT INTO schema_migrations (version) VALUES ('core_276_module_release_channels')
+  ON CONFLICT (version) DO NOTHING;

package/modules/onboarding/howto-guide.js

@@ -67,6 +67,12 @@ const STEPS = Object.freeze([
     when: 'When you want to see everything at a glance instead of asking.',
     try: 'Ask: "Open the hall for this project" or "What is the hall link?"',
   },
+  {
+    id: 'reopen_the_guide', moment: 'first_open', title: 'Come back to this guide',
+    what: 'These tips show up once each, at the moment they help. You can look at the whole list, pick up the next tip, or turn the tips off.',
+    when: 'Whenever you want a refresher, or the tips get in the way.',
+    try: 'Say: "Show me the how-to", "What\'s next in the tutorial?" or "Skip the tutorial."',
+  },
   // setup
   {
     id: 'sign_in', moment: 'setup', title: 'Sign in once',

package/modules/onboarding/howto-moments.js

@@ -0,0 +1,118 @@
+// modules/onboarding/howto-moments.js — which how-to step to show right now, and the words that ask the AI to show it (task 1004635)
+//
+// WHY. The how-to guide (howto-guide.js) is only useful if a step reaches the person
+// at the moment it applies — the first prompt in a new project, the first claim, the
+// first ship — and never again once read (howto-state.js keeps the read marks). This
+// file is the one place that decides WHICH step that is, so every delivery path gives
+// the same answer:
+//   • Claude Code: the Conductor hook (.claude/hooks/conductor.js) reads the signals it
+//     already has (the prompt, the active claims, whether this is the session's first
+//     prompt), injects the step, and marks it read;
+//   • any other AI tool: the instance CLAUDE.md tells it to run
+//     `npx bongos howto moment <id>` (scripts/gds/howto.js), which prints the step and
+//     marks it read the same way.
+//
+// Short by design: at most MAX_STEPS steps, from ONE moment, per prompt. A read (or
+// skipped) step is never picked again.
+//
+// Pure: signals and read ids in, steps and text out. No network, no files.
+
+'use strict';
+
+const guide = require('./howto-guide');
+
+const MAX_STEPS = 2;
+
+// Prompt words that open a moment. Vocabulary-gated so ordinary prompts stay quiet.
+const SHIP_RE = /\/builder-ship\b|\bship (?:it|this)\b|\bi'?m done\b|\bmark (?:this |it )?complete\b/i;
+const STUCK_RE = /\bstuck\b|\bconfus(?:ed|ing)\b|\bi'?m lost\b|\bnot working\b|\bdoesn'?t work\b|\bwhat went wrong\b/i;
+const FIND_WORK_RE = /\bwhat (?:can|should) i (?:work on|do)\b|\bwhat'?s next\b|\/builder-start\b|\bwhat'?s claimable\b/i;
+const GOAL_RE = /\bgoal\b|\/goal-create\b/i;
+const TASK_RE = /\b(?:make|create|file|new|add) (?:a |another )?task\b|\bsave (?:an |this )?idea\b/i;
+const INVITE_RE = /\binvit(?:e|ing)\b|\bteammates?\b|\bco-?workers?\b|\bcolleagues?\b/i;
+const SETTINGS_RE = /\bsettings?\b|\bship[- ]mode\b|\bshorter answers?\b|\btoo (?:long|technical)\b/i;
+const SETUP_RE = /\bset ?up\b|\bsign(?:ed)? ?in\b|\blog ?in\b|\/builder-setup\b/i;
+
+// A person asking for the guide itself (task 1004636): "show me the how-to", "what's
+// next in the tutorial", "skip the tutorial", "start the tutorial over". Checked in
+// this order, so "stop showing me the tutorial" is a skip, not a show.
+// "guide" and "tips" only with a determiner straight before them, so "the style guide"
+// or "tips for the header" are not read as asking for this guide.
+const GUIDE = String.raw`(?:how-?to|tutorial|(?:the|this|your|these|those) (?:guide|tips))`;
+const REQUESTS = [
+  ['skip', new RegExp(String.raw`\b(?:skip|stop|turn off|hide|dismiss|no more)\b.{0,24}\b${GUIDE}\b|\b${GUIDE}\b.{0,12}\b(?:off|away)\b`, 'i')],
+  ['reset', new RegExp(String.raw`\b(?:restart|start over|reset|bring back)\b.{0,24}\b${GUIDE}\b|\b${GUIDE}\b.{0,12}\bover\b`, 'i')],
+  ['next', new RegExp(String.raw`\bnext\b.{0,24}\b${GUIDE}\b|\b(?:continue|resume)\b.{0,12}\b${GUIDE}\b`, 'i')],
+  ['show', new RegExp(String.raw`\b(?:show|open|reopen|see|view)\b.{0,24}\b${GUIDE}\b|\b${GUIDE}\b.{0,12}\bprogress\b`, 'i')],
+];
+
+// 'show' | 'next' | 'skip' | 'reset' when the prompt asks for the guide itself, else null.
+function guideRequest(prompt) {
+  const p = typeof prompt === 'string' ? prompt : '';
+  for (const [kind, re] of REQUESTS) if (re.test(p)) return kind;
+  return null;
+}
+
+// What the AI is told to do for one of those requests: run the matching command and
+// pass its output on. The command changes the stored read state itself.
+function renderRequestForAi(kind) {
+  const said = { show: 'to see the how-to', next: 'for the next how-to step', skip: 'to skip the how-to', reset: 'to start the how-to over' }[kind];
+  return `The person asked ${said}: run \`npx bongos howto ${kind}\` and pass on what it prints in plain words.`;
+}
+
+// The moments open right now, most urgent first. Signals:
+//   firstPrompt  true on the first prompt of a session
+//   prompt       the person's words
+//   claims       null (unknown) | [] (none) | [...] active claims
+//   read         iterable of step ids already read or skipped
+function openMoments({ firstPrompt = false, prompt = '', claims = null, read = [] } = {}) {
+  const p = typeof prompt === 'string' ? prompt : '';
+  const known = Array.isArray(claims);
+  const hasClaim = known && claims.length > 0;
+  const done = new Set(read || []);
+  const out = [];
+  if (STUCK_RE.test(p)) out.push('stuck');
+  if (hasClaim && SHIP_RE.test(p)) out.push('first_ship');
+  if (hasClaim) out.push('first_claim');
+  if (firstPrompt) out.push('first_open');
+  // After a ship: no claim any more, and the shipping walkthrough was already shown.
+  if (known && !hasClaim && guide.stepsForMoment('first_ship').every((s) => done.has(s.id))) out.push('after_ship');
+  if (SETUP_RE.test(p)) out.push('setup');
+  if (GOAL_RE.test(p)) out.push('goal');
+  if (TASK_RE.test(p)) out.push('task');
+  if (FIND_WORK_RE.test(p) || (firstPrompt && known && !hasClaim)) out.push('find_work');
+  if (INVITE_RE.test(p)) out.push('invite');
+  if (SETTINGS_RE.test(p)) out.push('settings');
+  return [...new Set(out)];
+}
+
+// The unread steps of ONE moment, in guide order, at most `max`. Unknown moment → [].
+function unreadForMoment(momentId, read = [], { max = MAX_STEPS } = {}) {
+  const done = new Set(read || []);
+  return guide.stepsForMoment(momentId).filter((s) => !done.has(s.id)).slice(0, max);
+}
+
+// The first open moment that still has unread steps → { moment, steps }, or null.
+function pickSteps(signals = {}, { max = MAX_STEPS } = {}) {
+  for (const id of openMoments(signals)) {
+    const steps = unreadForMoment(id, signals.read, { max });
+    if (steps.length) return { moment: guide.MOMENTS.find((m) => m.id === id), steps };
+  }
+  return null;
+}
+
+// The words handed to the AI: what to tell the person, briefly, once.
+function renderForAi({ moment, steps }) {
+  const parts = steps.map((s) => `"${s.title}": ${s.what} Try: ${s.try}`);
+  return `How-to (${moment.title.toLowerCase()}): the person has not seen this yet. `
+    + 'At the end of your reply, in two or three plain sentences, tell them: '
+    + parts.join(' Then: ')
+    + ' Say it once and keep it short; it is now marked read and will not come back.';
+}
+
+// The same steps for a person reading a terminal (`npx bongos howto moment <id>`).
+function renderForPerson({ moment, steps }) {
+  return [`${moment.title}:`, ...steps.map((s) => `- ${s.title}: ${s.what}\n  Try: ${s.try}`)].join('\n');
+}
+
+module.exports = { MAX_STEPS, guideRequest, renderRequestForAi, openMoments, unreadForMoment, pickSteps, renderForAi, renderForPerson };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.128",
+  "version": "1.21.130",
   "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

@@ -9766,5 +9766,21 @@
       "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."
     }
+  ],
+  "1.21.129": [
+    {
+      "id": "1004635",
+      "text": "When someone is new to Bongos, the AI now gives them the right short tip at the right moment (first time opening the project, first task claimed, first ship) and never repeats a tip once seen. Other AI tools get the same tips"
+    },
+    {
+      "id": "1003815",
+      "text": "The module store can now record which release channel each module version is on — tester first, then everyone — with room for more, like taking a version back. Nothing changes for users yet; the next tasks use it."
+    }
+  ],
+  "1.21.130": [
+    {
+      "id": "1004636",
+      "text": "People can now say 'show me the how-to', 'what's next in the tutorial' or 'skip the tutorial' and the AI does it: shows the whole guide with what they have seen, gives the next tip, or turns the tips off. 'Start the tutorial o"
+    }
   ]
 }

package/scripts/gds/claude-md-template.js

@@ -79,6 +79,7 @@ ${ident}
 - **\`npx bongos ship\`** runs the smoke + grade, then merges and deploys; **\`npx bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
 - **The project's ship mode says who starts a ship** — \`npx bongos ship-mode\` prints it. In **Auto** (the default) you run \`npx bongos ship\` yourself when the task is done; never hand the person commands to run. In **Manual** ask the person first, and ship only after they say yes.
 - **Dependencies gate everything** — a task becomes claimable only once every task it depends on has shipped.
+- **Walk new people through the how-to, once.** The first time the person meets one of these moments, run the matching command and pass its few lines on in plain words at the end of your reply: the first prompt of a session — \`npx bongos howto moment first_open\`; their first claim — \`npx bongos howto moment first_claim\`; finishing their first task — \`npx bongos howto moment first_ship\`. It prints nothing once a step is read, so it never repeats (\`npx bongos howto moments\` lists the rest). When they ask to see the how-to, for the next step, or to skip it, run \`npx bongos howto show\`, \`npx bongos howto next\` or \`npx bongos howto skip\`. Claude Code is handed these steps automatically.
 - **Code you write or touch carries a doc-comment** — each module a header, each public function/class a line or two, saying *what* it does and *why* it exists (never how), in the words someone would search for. Agents find code by searching text, so meaning written into the source is what makes it findable.
 
 ## Where things live

package/scripts/gds/howto.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// scripts/gds/howto.js — the in-session how-to guide from a terminal, for any AI tool (task 1004635)
+//
+// WHY. Claude Code gets the right how-to step injected by the Conductor hook at the
+// moment it applies. Other AI tools (Codex, Cursor, Gemini…) have no such hook, so the
+// instance CLAUDE.md / AGENTS.md tells them to run this at the same moments instead. It
+// prints the person's unread steps for that moment — nothing at all once they are read —
+// and marks them read in Bongos, so no tool shows the same step twice.
+//
+// It is also how a person reopens the guide in plain words (task 1004636): "show me the
+// how-to" → `show` (every step with its read mark and the progress count), "what's next
+// in the tutorial" → `next` (the first unread step, then marked read), "skip the
+// tutorial" → `skip` (every step marked skipped, so no moment shows one again), and
+// "start the tutorial over" → `reset`. The Conductor hook maps those words to these
+// commands for Claude Code; the instance CLAUDE.md names them for other tools.
+//
+// Usage:
+//   node scripts/gds/howto.js show                 the whole guide with read/unread marks + progress
+//   node scripts/gds/howto.js next                 print + mark read the next unread step
+//   node scripts/gds/howto.js skip                 mark every step skipped (the guide goes quiet)
+//   node scripts/gds/howto.js reset                forget every mark, so the guide starts over
+//   node scripts/gds/howto.js moment <moment-id>   print + mark read the unread steps of a moment
+//   node scripts/gds/howto.js moments              list the moment ids and when each applies
+//
+// Also `npx bongos howto …`.
+'use strict';
+
+const { apiCall, requireSession, errCode, cliExit } = require('./cli-lib');
+const guide = require('../../modules/onboarding/howto-guide');
+const moments = require('../../modules/onboarding/howto-moments');
+
+const USAGE = 'usage: node scripts/gds/howto.js show | next | skip | reset | moment <moment-id> | moments';
+
+// The step ids this person has already read or skipped, from GET /me/howto's answer.
+function readIds(state) {
+  return ((state && state.steps) || []).filter((s) => s.state !== 'unread').map((s) => s.id);
+}
+
+const MARK = { read: '[x]', skipped: '[-]', unread: '[ ]' };
+
+// Pure: the whole guide as the person sees it, from GET /me/howto's answer.
+function formatProgress(state) {
+  const byId = new Map(((state && state.steps) || []).map((s) => [s.id, s.state]));
+  const out = [];
+  for (const m of guide.MOMENTS) {
+    out.push(`${m.title}`);
+    for (const s of guide.stepsForMoment(m.id)) out.push(`  ${MARK[byId.get(s.id) || 'unread']} ${s.title}`);
+  }
+  const total = guide.STEPS.length;
+  const read = (state && state.read) || 0;
+  const skipped = (state && state.skipped) || 0;
+  const next = guide.nextUnread(readIds(state));
+  out.push('', `Progress: ${read} of ${total} read${skipped ? `, ${skipped} skipped` : ''}.`);
+  out.push(next ? `Next: ${next.title} — say "what's next in the tutorial".` : 'All done. Say "start the tutorial over" to see it again.');
+  return out.join('\n');
+}
+
+async function readState() {
+  await requireSession();
+  const r = await apiCall('GET', '/api/bongos/me/howto');
+  if (!r.ok) console.error(`Could not read the how-to progress (${r.status}${errCode(r.data) ? `: ${errCode(r.data)}` : ''}).`);
+  return r.ok ? r.data : null;
+}
+
+async function write(route, body, what) {
+  const w = await apiCall('POST', `/api/bongos/me/howto/${route}`, body);
+  if (!w.ok) console.error(`Could not ${what} (${w.status}${errCode(w.data) ? `: ${errCode(w.data)}` : ''}).`);
+  return w.ok;
+}
+
+async function show() {
+  const state = await readState();
+  if (!state) return 1;
+  console.log(formatProgress(state));
+  return 0;
+}
+
+async function next() {
+  const state = await readState();
+  if (!state) return 1;
+  const step = guide.nextUnread(readIds(state));
+  if (!step) { console.log('You have seen every step. Say "start the tutorial over" to see them again.'); return 0; }
+  console.log(moments.renderForPerson({ moment: guide.MOMENTS.find((m) => m.id === step.moment), steps: [step] }));
+  if (!(await write('read', { steps: [step.id] }, 'mark it read'))) return 1;
+  const left = guide.STEPS.length - readIds(state).length - 1;
+  console.log(left > 0 ? `(${left} more to go — say "what's next in the tutorial" for the next one.)` : '(That was the last one.)');
+  return 0;
+}
+
+async function skip() {
+  await requireSession();
+  if (!(await write('read', { all: true, how: 'skipped' }, 'skip the guide'))) return 1;
+  console.log('Skipped. The how-to will not show any more tips. Say "show me the how-to" any time to look at it, or "start the tutorial over" to bring the tips back.');
+  return 0;
+}
+
+async function reset() {
+  await requireSession();
+  if (!(await write('reset', {}, 'start the guide over'))) return 1;
+  console.log('Done. The how-to starts over: each tip will show again at its moment.');
+  return 0;
+}
+
+async function showMoment(id) {
+  if (!guide.MOMENT_IDS.has(id)) {
+    console.error(`unknown moment "${id}" — one of: ${[...guide.MOMENT_IDS].join(', ')}`);
+    return 2;
+  }
+  await requireSession();
+  const r = await apiCall('GET', '/api/bongos/me/howto');
+  if (!r.ok) {
+    console.error(`Could not read the how-to progress (${r.status}${errCode(r.data) ? `: ${errCode(r.data)}` : ''}).`);
+    return 1;
+  }
+  const steps = moments.unreadForMoment(id, readIds(r.data));
+  if (!steps.length) return 0; // all read: say nothing, so it never repeats
+  console.log(moments.renderForPerson({ moment: guide.MOMENTS.find((m) => m.id === id), steps }));
+  const w = await apiCall('POST', '/api/bongos/me/howto/read', { steps: steps.map((s) => s.id) });
+  if (!w.ok) console.error(`(could not mark these read: ${w.status}${errCode(w.data) ? ` ${errCode(w.data)}` : ''})`);
+  return 0;
+}
+
+async function main(argv) {
+  const [cmd, arg] = argv;
+  if (!cmd || cmd === '--help' || cmd === '-h') { console.log(USAGE); return cmd ? 0 : 2; }
+  if (cmd === 'moments') {
+    for (const m of guide.MOMENTS) console.log(`${m.id.padEnd(12)} ${m.trigger}`);
+    return 0;
+  }
+  if (cmd === 'moment' && arg) return showMoment(String(arg).trim());
+  if (cmd === 'show') return show();
+  if (cmd === 'next') return next();
+  if (cmd === 'skip') return skip();
+  if (cmd === 'reset') return reset();
+  console.error(USAGE);
+  return 2;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2))
+    .then((code) => cliExit(code))
+    .catch((err) => { console.error('fatal:', err && err.message ? err.message : err); cliExit(1); });
+}
+
+module.exports = { main, readIds, formatProgress };

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.128'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.130'; // 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/conductor_main_e2e.mjs

@@ -49,7 +49,7 @@ function mePayload({ discipline = 'engineer' } = {}) {
 // Run the hook once in a throwaway HOME whose session points at `base`.
 // `worktree` names a git repo created under the fake home for the hook to stand
 // in — its basename is what binds a claim to "this" tree (task 1002992).
-async function runHook(me, { worktree = null } = {}) {
+async function runHook(me, { worktree = null, prompts = ['hello'] } = {}) {
   const server = http.createServer((req, res) => {
     if (req.url.startsWith('/api/bongos/me')) { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(me)); return; }
     res.writeHead(404); res.end('{}');
@@ -70,14 +70,22 @@ async function runHook(me, { worktree = null } = {}) {
     fs.mkdirSync(cwd, { recursive: true });
     execFileSync('git', ['init', '-q'], { cwd, stdio: 'ignore' });
   }
+  // Several prompts run one after another in ONE session, sharing the hook's cache —
+  // what the per-session repeat filter sees (task 1004636).
+  const sessionId = 'e2e-' + Date.now();
   try {
-    const child = spawn(process.execPath, [HOOK], { env, cwd, stdio: ['pipe', 'pipe', 'pipe'] });
-    let out = ''; let err = '';
-    child.stdout.on('data', (d) => { out += d; });
-    child.stderr.on('data', (d) => { err += d; });
-    child.stdin.end(JSON.stringify({ session_id: 'e2e-' + Date.now(), prompt: 'hello', cwd }));
-    const code = await new Promise((r) => child.on('close', r));
-    return { out, err, code };
+    const outs = [];
+    let err = ''; let code = 0;
+    for (const prompt of prompts) {
+      const child = spawn(process.execPath, [HOOK], { env, cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+      let out = '';
+      child.stdout.on('data', (d) => { out += d; });
+      child.stderr.on('data', (d) => { err += d; });
+      child.stdin.end(JSON.stringify({ session_id: sessionId, prompt, cwd }));
+      code = await new Promise((r) => child.on('close', r));
+      outs.push(out);
+    }
+    return { out: outs[outs.length - 1], outs, err, code };
   } finally {
     await new Promise((r) => server.close(r));
     fs.rmSync(home, { recursive: true, force: true });
@@ -149,4 +157,10 @@ await test('a project with no laws sends no laws block', async () => {
   assert.ok(r.out.includes(INTERACTION), 'and the rest of the hook still runs');
 });
 
+await test('asking for the next how-to step twice in one session reaches the AI both times (task 1004636)', async () => {
+  const r = await runHook(mePayload(), { prompts: ["what's next in the tutorial", "what's next in the tutorial"] });
+  assert.equal(r.outs.length, 2);
+  for (const [i, out] of r.outs.entries()) assert.ok(out.includes('npx bongos howto next'), `ask ${i + 1} was swallowed; stdout: ${JSON.stringify(out.slice(0, 200))}`);
+});
+
 summary();

package/tests/howto_guide.mjs

@@ -66,6 +66,18 @@ test('steps are short and in plain language (no jargon)', () => {
   assert.deepEqual(hits, []);
 });
 
+test('every `npx bongos <verb>` a step names is a real bongos verb', () => {
+  const { VERBS } = require('../bin/bongos.js');
+  let seen = 0;
+  for (const s of guide.STEPS) {
+    for (const m of s.try.matchAll(/npx bongos ([a-z][a-z-]*)/g)) {
+      seen++;
+      assert.ok(Object.prototype.hasOwnProperty.call(VERBS, m[1]), `${s.id}: "npx bongos ${m[1]}" is not a verb in bin/bongos.js`);
+    }
+  }
+  assert.ok(seen > 0, 'the guide names no bongos verbs — has the check stopped matching?');
+});
+
 test('every slash command a step names is a core skill an instance gets', async () => {
   const fs = await import('node:fs');
   const { isPublishable } = require('../scripts/gds/publish-manifest.js');

package/tests/howto_moments.mjs

@@ -0,0 +1,183 @@
+// tests/howto_moments.mjs — the right unread how-to step at the right moment, never twice (task 1004635)
+//
+// The done-when: on a fresh project the first session is walked through the starting
+// step, the first ship triggers the shipping walkthrough, and neither repeats once read.
+// Held here at three layers: the pure picker (modules/onboarding/howto-moments.js), the
+// Conductor advisory built from it (.claude/hooks/conductor.js howtoAdvisory), and the
+// non-Claude path (the `npx bongos howto` verb + the instance CLAUDE.md lines naming it).
+//
+// Run:  node tests/howto_moments.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const guide = require('../modules/onboarding/howto-guide.js');
+const m = require('../modules/onboarding/howto-moments.js');
+const { howtoAdvisory, evaluateTriggers } = require('../.claude/hooks/conductor.js');
+const { VERBS } = require('../bin/bongos.js');
+const { renderInstanceClaudeMd } = require('../scripts/gds/claude-md-template.js');
+const { readIds, formatProgress } = require('../scripts/gds/howto.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+const ids = (pick) => (pick ? pick.steps.map((s) => s.id) : []);
+
+console.log('the picker:');
+
+test('a fresh project: the first prompt walks through what Bongos is and where to start', () => {
+  const pick = m.pickSteps({ firstPrompt: true, prompt: 'hello', claims: [], read: [] });
+  assert.equal(pick.moment.id, 'first_open');
+  assert.deepEqual(ids(pick), ['welcome', 'where_to_start']);
+});
+
+test('once read, the starting step never comes back — the next session moves on', () => {
+  const pick = m.pickSteps({ firstPrompt: true, prompt: 'hello', claims: [], read: ['welcome', 'where_to_start'] });
+  assert.ok(!ids(pick).includes('where_to_start'));
+  assert.ok(!ids(pick).includes('welcome'));
+});
+
+test('an ordinary later prompt with nothing claimed says nothing', () => {
+  assert.equal(m.pickSteps({ firstPrompt: false, prompt: 'rename the button', claims: [], read: [] }), null);
+});
+
+test('the first ship triggers the shipping walkthrough, ahead of the claim steps', () => {
+  const pick = m.pickSteps({ prompt: 'ship it', claims: [{ task_id: 1 }], read: [] });
+  assert.equal(pick.moment.id, 'first_ship');
+  assert.deepEqual(ids(pick), ['what_ship_does', 'review_findings']);
+});
+
+test('the shipping walkthrough does not repeat once read', () => {
+  const read = ['what_ship_does', 'review_findings', 'claim_a_task', 'give_a_task_back', 'preview_before_ship'];
+  assert.equal(m.pickSteps({ prompt: 'ship it', claims: [{ task_id: 1 }], read }), null);
+});
+
+test('holding a claim opens the first-claim steps', () => {
+  assert.equal(m.pickSteps({ prompt: 'go on', claims: [{ task_id: 1 }], read: [] }).moment.id, 'first_claim');
+});
+
+test('after a ship (no claim, shipping walkthrough read) comes what happens next', () => {
+  const pick = m.pickSteps({ prompt: 'ok', claims: [], read: ['what_ship_does', 'review_findings'] });
+  assert.equal(pick.moment.id, 'after_ship');
+});
+
+test('unknown claim state never guesses a claim moment', () => {
+  assert.equal(m.pickSteps({ prompt: 'ship it', claims: null, read: [] }), null);
+});
+
+test('short: never more than two steps, all from one moment', () => {
+  for (const firstPrompt of [true, false]) {
+    for (const prompt of ['ship it', 'I am stuck', 'make a goal', 'invite my teammate', 'what can I work on?']) {
+      const pick = m.pickSteps({ firstPrompt, prompt, claims: [{ task_id: 1 }], read: [] });
+      if (!pick) continue;
+      assert.ok(pick.steps.length <= m.MAX_STEPS);
+      assert.ok(pick.steps.every((s) => s.moment === pick.moment.id));
+    }
+  }
+});
+
+test('every moment the picker can open is a moment the guide defines', () => {
+  const opened = new Set();
+  for (const prompt of ['ship it', 'stuck', 'set up', 'goal', 'make a task', "what's next", 'invite', 'settings']) {
+    for (const claims of [[], [{}], null]) {
+      for (const id of m.openMoments({ firstPrompt: true, prompt, claims, read: [] })) opened.add(id);
+    }
+  }
+  for (const id of opened) assert.ok(guide.MOMENT_IDS.has(id), id);
+});
+
+test('the AI is told to say it once, briefly, and that it is marked read', () => {
+  const text = m.renderForAi(m.pickSteps({ firstPrompt: true, claims: [], read: [] }));
+  assert.match(text, /Where to start/);
+  assert.match(text, /once/);
+  assert.match(text, /marked read/);
+});
+
+console.log('\nasking for the guide itself (task 1004636):');
+
+test('the three plain-word requests, and starting over, are recognised', () => {
+  const cases = {
+    'show me the how-to': 'show',
+    'Can I see my tutorial progress?': 'show',
+    "what's next in the tutorial": 'next',
+    'continue the tutorial': 'next',
+    'skip the tutorial': 'skip',
+    'please stop showing me the tutorial': 'skip',
+    'turn the tips off': 'skip',
+    'start the tutorial over': 'reset',
+  };
+  for (const [prompt, kind] of Object.entries(cases)) assert.equal(m.guideRequest(prompt), kind, prompt);
+});
+
+test('ordinary prompts are not guide requests', () => {
+  for (const p of ['show me the login page', 'what is next on the roadmap', 'skip the failing test', 'ship it', 'show me the style guide', 'add tips for the header']) {
+    assert.equal(m.guideRequest(p), null, p);
+  }
+});
+
+test('each request tells the AI the command that changes the stored state', () => {
+  for (const kind of ['show', 'next', 'skip', 'reset']) assert.match(m.renderRequestForAi(kind), new RegExp(`npx bongos howto ${kind}`));
+});
+
+test('the full guide shows read, skipped and unread marks, the progress, and what is next', () => {
+  const out = formatProgress({ steps: [{ id: 'welcome', state: 'read' }, { id: 'the_hall', state: 'skipped' }], read: 1, skipped: 1 });
+  assert.match(out, /\[x\] What Bongos is/);
+  assert.match(out, /\[-\] The hall/);
+  assert.match(out, /\[ \] Where to start/);
+  assert.match(out, new RegExp(`Progress: 1 of ${guide.STEPS.length} read, 1 skipped`));
+  assert.match(out, /Next: Where to start/);
+});
+
+test('with every step done, the guide says so and how to start over', () => {
+  const out = formatProgress({ steps: guide.STEPS.map((s) => ({ id: s.id, state: 'read' })), read: guide.STEPS.length });
+  assert.match(out, /All done/);
+});
+
+console.log('\nthe Conductor:');
+
+test('a guide request becomes the advisory even with no read state, and replaces the moment tip', () => {
+  const a = howtoAdvisory({ howto: { read: [] }, prompt: 'skip the tutorial', firstPrompt: true, activeClaims: [] });
+  assert.equal(a.id, 'howto-request:skip');
+  assert.equal(a.howtoSteps, undefined, 'a request marks nothing itself — the command does');
+  assert.equal(howtoAdvisory({ howto: null, prompt: 'show me the how-to' }).id, 'howto-request:show');
+});
+
+test('no read state (offline, signed out, no onboarding module) → no how-to advisory', () => {
+  assert.equal(howtoAdvisory({ howto: null, firstPrompt: true, activeClaims: [] }), null);
+});
+
+test('the advisory names the steps it shows, so main() can mark exactly those read', () => {
+  const a = howtoAdvisory({ howto: { read: [] }, firstPrompt: true, activeClaims: [] });
+  assert.deepEqual(a.howtoSteps, ['welcome', 'where_to_start']);
+  assert.equal(a.id, 'howto:welcome,where_to_start');
+});
+
+test('evaluateTriggers carries the how-to advisory on a first prompt, and not once read', () => {
+  const first = evaluateTriggers({ prompt: 'hi', activeClaims: [], howto: { read: [] }, firstPrompt: true });
+  assert.ok(first.some((a) => a.howtoSteps));
+  const all = guide.STEPS.map((s) => s.id);
+  const later = evaluateTriggers({ prompt: 'ship it', activeClaims: [{ task_id: 1 }], howto: { read: all }, firstPrompt: true });
+  assert.ok(!later.some((a) => a.howtoSteps));
+});
+
+console.log('\nother AI tools:');
+
+test('`bongos howto` is a verb, run by scripts/gds/howto.js', () => {
+  assert.equal(VERBS.howto.script, 'howto.js');
+});
+
+test('the instance CLAUDE.md names the three moment commands', () => {
+  const md = renderInstanceClaudeMd({});
+  for (const id of ['first_open', 'first_claim', 'first_ship']) assert.ok(md.includes(`npx bongos howto moment ${id}`), id);
+});
+
+test('the CLI counts read and skipped steps as done', () => {
+  assert.deepEqual(readIds({ steps: [{ id: 'a', state: 'read' }, { id: 'b', state: 'skipped' }, { id: 'c', state: 'unread' }] }), ['a', 'b']);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exitCode = 1;

package/tests/module_release_channels.mjs

@@ -0,0 +1,58 @@
+// tests/module_release_channels.mjs — the release-channel schema a module version
+// sits on (task 1003815, ADR 0344; migration core_276). No database: the migration
+// is read as text and its shape pinned. The integration lane applies it to a real
+// Postgres with every other migration.
+//
+// Run:  node tests/module_release_channels.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SQL = fs.readFileSync(path.join(ROOT, 'migrations', 'core_276_module_release_channels.sql'), 'utf8');
+const DDL = SQL.replace(/--.*$/gm, '');
+
+test('core_276 is additive and idempotent', () => {
+  // the project's own migration linter, so this tracks its unsafe-pattern list as it grows
+  const lint = require('../scripts/gds/lint-migrations.js');
+  assert.deepEqual(lint.scanMigrationSql(SQL).unsafe || [], [], 'additive only');
+  for (const m of DDL.matchAll(/CREATE (TABLE|INDEX)\s+(?!IF NOT EXISTS\b)(\w+)/g)) {
+    assert.fail(`CREATE ${m[1]} ${m[2]} without IF NOT EXISTS is not safe to re-run`);
+  }
+  assert.match(DDL, /ON CONFLICT \(channel\) DO NOTHING/, 're-running does not duplicate the channel rows');
+  assert.match(DDL, /WHERE NOT EXISTS \(SELECT 1 FROM store_module_version_channels c WHERE c\.version_id = v\.id\)/,
+    're-running does not add a second backfill row');
+  assert.match(SQL, /INSERT INTO schema_migrations \(version\) VALUES \('core_276_module_release_channels'\)/);
+});
+
+test('channels are rows, so a fourth needs no schema change; tester, general and withdrawn ship', () => {
+  assert.match(DDL, /CREATE TABLE IF NOT EXISTS store_release_channels \(\s*channel\s+text PRIMARY KEY/);
+  const seeded = [...DDL.matchAll(/\('(\w+)',\s+'[^']*',\s+(true|false),\s+\d+\)/g)].map((m) => [m[1], m[2]]);
+  assert.deepEqual(seeded, [['tester', 'true'], ['general', 'true'], ['withdrawn', 'false']],
+    'two channels serve installs; withdrawn never does');
+  assert.doesNotMatch(DDL, /channel\s+text[^,\n]*CHECK \(channel IN/, 'no closed list of channels in a CHECK');
+  assert.doesNotMatch(DDL, /\bis_tester\b|\btester\s+boolean/, 'not a boolean');
+});
+
+test('a channel belongs to a version, as history: the newest row is current', () => {
+  const t = DDL.match(/CREATE TABLE IF NOT EXISTS store_module_version_channels \(([\s\S]*?)\n\);/);
+  assert.ok(t, 'the history table exists');
+  const body = t[1];
+  assert.match(body, /version_id\s+bigint NOT NULL REFERENCES store_module_versions\(id\)/, 'keyed by version, not module');
+  assert.doesNotMatch(body, /\bmodule_key\b/, 'never by module');
+  assert.match(body, /channel\s+text NOT NULL REFERENCES store_release_channels\(channel\)/);
+  assert.match(body, /reason\s+text NOT NULL CHECK \(reason ~ '\^\[a-z\]\[a-z0-9_\]\{0,39\}\$'\)/, 'a short code, never free text');
+  assert.match(body, /set_by\s+bigint REFERENCES builders\(id\),/, 'nullable: the system can move a version');
+  assert.doesNotMatch(body, /UNIQUE \(version_id\)/, 'a version can move more than once');
+  assert.match(DDL, /ON store_module_version_channels \(version_id, set_at DESC, id DESC\)/, 'current-channel lookup is indexed');
+});
+
+test('versions published before staged rollout stay offered to everyone', () => {
+  assert.match(DDL, /SELECT v\.id, 'general', 'predates_staged_rollout'\s+FROM store_module_versions v/);
+});