@bongos/core 1.21.129 → 1.21.130

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.129",
-  "core_contract": "1.21.129",
-  "source_commit": "e1853bcff638c4af78b2c735629a68e92b323d41",
+  "core_version": "1.21.130",
+  "core_contract": "1.21.130",
+  "source_commit": "d9a1489516436c9e34730e3c028f4465cfd62474",
   "source_ref": "HEAD",
-  "built_at": "2026-10-15T16:58:38.452Z",
+  "built_at": "2026-10-15T17:14:20.940Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 606,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 3781,
-  "tree_sha256": "86956dd5cf1f736d879fcefe1c8c370b4b62f58d3e0cb3876a00e8d4d0c25d0c",
+  "tree_sha256": "309831afd3ba5a2aed6ebe90ff918936d2c3fd2ea36d1fb2a90e41b7187cb474",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2912,7 +2912,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "1735499acdd1ee22b83fc0be539e3371072b289b2b3c1d89e7996ec360190077"
+      "sha256": "18a6694f80109250c168809eb753e4d4f8c7c62d5eed96b9bee217d89189decf"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "791b40816885c77100c1ff5ea9773f66a122d0bb6fc1dc2163fe43c5d89b0d1b"
+      "sha256": "a8659f105f89cd130c2772293c07aad2e7071ef6adc4c094e65fad8ac205a2ad"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7937,12 +7937,12 @@
     {
       "path": "modules/onboarding/howto-guide.js",
       "mode": "0000644",
-      "sha256": "18984c946d746da66ff7678379e9f49c9cfdcdb8f70d2acd852ab29c820baad0"
+      "sha256": "7b352dda65b04f44e48feb19fc3a959d9a122411c22f2830b9cc967d1a0f6852"
     },
     {
       "path": "modules/onboarding/howto-moments.js",
       "mode": "0000644",
-      "sha256": "1f22e2c271c92c2e1e263fab265e73b88ba796b44e519ecd5f3266b10481bf17"
+      "sha256": "6950e77759f8e574187e7e77871e28492116c3c5ad17d3cd2cebd3a018c0ad6c"
     },
     {
       "path": "modules/onboarding/howto-state.js",
@@ -10502,12 +10502,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "fd49f31fc91c5005e4e306248e0745842d89df367cdb32fd03b04b5bc844bffb"
+      "sha256": "1556b57526d416a0156c23915ba0aaf080eef4732031261f80c7a2c891f49b9d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "da9de77dd1ad1af7aa7a30243b2f0e12b9553e10a15a858cf3e899013769f58e"
+      "sha256": "5db6c25e29a3abec630266149723a99b09a249bcc375bca40e39bcc8eb5a0d2b"
     },
     {
       "path": "public-docs/index.html",
@@ -10527,7 +10527,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "7211540da2e00897f888df0f4642fd0d286a04ed3433bb0683d1acb7843d8b77"
+      "sha256": "52d4fa7c27b8a7cfe9ead4896e254d332b1abae140b60beb8c848efa1e16fa2f"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10852,7 +10852,7 @@
     {
       "path": "scripts/gds/claude-md-template.js",
       "mode": "0000644",
-      "sha256": "e783238968b9c1dcac8e7d9e49f0f4520bde8369e95e111dcd086cb77ab28189"
+      "sha256": "ebfbfe3e5dbd865b5699d65fd7f3fc345f992c92f84b41db716295c40553dacb"
     },
     {
       "path": "scripts/gds/cleanup-orphans.js",
@@ -11262,7 +11262,7 @@
     {
       "path": "scripts/gds/howto.js",
       "mode": "0000644",
-      "sha256": "febb8812a719ca76ef34b312b387953b723add58357441888183ba1e9577e45f"
+      "sha256": "06c77dee345d93604e5d1bde431476399e858556897114bae368ed513d3a944c"
     },
     {
       "path": "scripts/gds/http-api-client.js",
@@ -12882,7 +12882,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "854a2036806028bf527d76593e2c9a5e5b57d7daa1183f18065889afe9f6d373"
+      "sha256": "7c374bdf850a487a15f60f8ddd21aec96c49f644a50b396d1567a1e227bf4e0c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13797,7 +13797,7 @@
     {
       "path": "tests/conductor_main_e2e.mjs",
       "mode": "0000644",
-      "sha256": "807eb68a5149ee73868f814ebeef254725a4baecdfbb4d08b9b483fd8d579c73"
+      "sha256": "5d825f686bbe5351def658bf6e2f011e3ca351312f04009500ee65c8a195914d"
     },
     {
       "path": "tests/confirm_attribution.mjs",
@@ -15662,12 +15662,12 @@
     {
       "path": "tests/howto_guide.mjs",
       "mode": "0000644",
-      "sha256": "8e9b206fdde738f289bc11e204852595e9128b523cfc20cd67e3e83fb60a2fac"
+      "sha256": "72b439c6189e78bed945ec7e16da9cfeb32e34c9f3a4417f024c32dec07a73cf"
     },
     {
       "path": "tests/howto_moments.mjs",
       "mode": "0000644",
-      "sha256": "6fc5a865345c3db90336748eebd79425ee64496b73dd98f89c87d9da21174e54"
+      "sha256": "fc668c29944ddbbc629e9ee4e6c30dc1cffbc88d12f478a1b95a4585e360a185"
     },
     {
       "path": "tests/howto_state.mjs",

package/docs/file-map.md

@@ -169,7 +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)
+│       ├── 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

package/docs/module-api-changelog.md

@@ -3095,5 +3095,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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/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

@@ -33,6 +33,33 @@ const INVITE_RE = /\binvit(?:e|ing)\b|\bteammates?\b|\bco-?workers?\b|\bcolleagu
 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
@@ -88,4 +115,4 @@ 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 };
+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.129",
+  "version": "1.21.130",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.129",
+      "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.129",
+  "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

@@ -9776,5 +9776,11 @@
       "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,7 +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.
+- **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

@@ -7,7 +7,18 @@
 // 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
 //
@@ -18,13 +29,78 @@ 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';
+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(', ')}`);
@@ -52,6 +128,10 @@ async function main(argv) {
     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;
 }
@@ -62,4 +142,4 @@ if (require.main === module) {
     .catch((err) => { console.error('fatal:', err && err.message ? err.message : err); cliExit(1); });
 }
 
-module.exports = { main, readIds };
+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.129'; // 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

@@ -17,7 +17,7 @@ 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');
+const { readIds, formatProgress } = require('../scripts/gds/howto.js');
 
 let passed = 0;
 let failed = 0;
@@ -97,8 +97,55 @@ test('the AI is told to say it once, briefly, and that it is marked read', () =>
   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);
 });