@bongos/core 1.21.128 → 1.21.129

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.129",
+  "core_contract": "1.21.129",
+  "source_commit": "e1853bcff638c4af78b2c735629a68e92b323d41",
   "source_ref": "HEAD",
-  "built_at": "2026-10-15T16:35:02.176Z",
+  "built_at": "2026-10-15T16:58:38.452Z",
   "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": "86956dd5cf1f736d879fcefe1c8c370b4b62f58d3e0cb3876a00e8d4d0c25d0c",
   "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": "1735499acdd1ee22b83fc0be539e3371072b289b2b3c1d89e7996ec360190077"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f5e9ba961f5fad8945bbcba2e6daefdde31efba3e6e6b41dde6d52aa06b07065"
+      "sha256": "791b40816885c77100c1ff5ea9773f66a122d0bb6fc1dc2163fe43c5d89b0d1b"
     },
     {
       "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",
@@ -7934,6 +7939,11 @@
       "mode": "0000644",
       "sha256": "18984c946d746da66ff7678379e9f49c9cfdcdb8f70d2acd852ab29c820baad0"
     },
+    {
+      "path": "modules/onboarding/howto-moments.js",
+      "mode": "0000644",
+      "sha256": "1f22e2c271c92c2e1e263fab265e73b88ba796b44e519ecd5f3266b10481bf17"
+    },
     {
       "path": "modules/onboarding/howto-state.js",
       "mode": "0000644",
@@ -10492,12 +10502,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b7d2956b1155f633fbfbbfafe4211befef0d545b02671ce8cd9096ee22a1f734"
+      "sha256": "fd49f31fc91c5005e4e306248e0745842d89df367cdb32fd03b04b5bc844bffb"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4cbf0ddd56ffbee1d0d4cdd8388793c2590a243737608cf18556e0400e946fed"
+      "sha256": "da9de77dd1ad1af7aa7a30243b2f0e12b9553e10a15a858cf3e899013769f58e"
     },
     {
       "path": "public-docs/index.html",
@@ -10517,7 +10527,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "f5b81f238e17e854f85e2af52d9c3661acf519c8bd9634aaa95206e8f107bc5b"
+      "sha256": "7211540da2e00897f888df0f4642fd0d286a04ed3433bb0683d1acb7843d8b77"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10842,7 +10852,7 @@
     {
       "path": "scripts/gds/claude-md-template.js",
       "mode": "0000644",
-      "sha256": "d8560389c6a72cda1f7fe958af67b943e825b68fdd8f0fa28bf9143e42a1ece9"
+      "sha256": "e783238968b9c1dcac8e7d9e49f0f4520bde8369e95e111dcd086cb77ab28189"
     },
     {
       "path": "scripts/gds/cleanup-orphans.js",
@@ -11249,6 +11259,11 @@
       "mode": "0000644",
       "sha256": "b7c61201d165b8c2b7e51b3a057153c3c7238bfc8bd55412acaf0ba87acd367d"
     },
+    {
+      "path": "scripts/gds/howto.js",
+      "mode": "0000644",
+      "sha256": "febb8812a719ca76ef34b312b387953b723add58357441888183ba1e9577e45f"
+    },
     {
       "path": "scripts/gds/http-api-client.js",
       "mode": "0000644",
@@ -12867,7 +12882,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "638e7c6e9ff2e460bacc69abc98b8f6721b6d2ade29ba79aa166920e1f71f7e7"
+      "sha256": "854a2036806028bf527d76593e2c9a5e5b57d7daa1183f18065889afe9f6d373"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -15649,6 +15664,11 @@
       "mode": "0000644",
       "sha256": "8e9b206fdde738f289bc11e204852595e9128b523cfc20cd67e3e83fb60a2fac"
     },
+    {
+      "path": "tests/howto_moments.mjs",
+      "mode": "0000644",
+      "sha256": "6fc5a865345c3db90336748eebd79425ee64496b73dd98f89c87d9da21174e54"
+    },
     {
       "path": "tests/howto_state.mjs",
       "mode": "0000644",
@@ -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)
 │       ├── 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,7 @@ 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)
 ---------------------------------------------------------------------------
 ```

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-moments.js

@@ -0,0 +1,91 @@
+// 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;
+
+// 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, openMoments, unreadForMoment, pickSteps, renderForAi, renderForPerson };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.128",
+  "version": "1.21.129",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.128",
+      "version": "1.21.129",
       "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.129",
   "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,15 @@
       "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."
+    }
   ]
 }

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). 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,65 @@
+#!/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.
+//
+// Usage:
+//   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 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);
+}
+
+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());
+  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 };

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.129'; // 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_moments.mjs

@@ -0,0 +1,136 @@
+// 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 } = 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('\nthe Conductor:');
+
+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/);
+});