@bongos/core 1.21.127 → 1.21.129

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/modules/onboarding/howto-state.js

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

package/modules/onboarding/migrations/onboarding_001_howto_reads.sql

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

package/modules/onboarding/module.json

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

package/modules/onboarding/routes/onboarding.js

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

package/package-lock.json

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

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