@bongos/core 1.21.123 → 1.21.125

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.123",
-  "core_contract": "1.21.123",
-  "source_commit": "bfe95a4e390577d4579a3da16d81d5ada6bc8b9a",
+  "core_version": "1.21.125",
+  "core_contract": "1.21.125",
+  "source_commit": "6537f85e10dcb60107037c138237fe4e5d855500",
   "source_ref": "HEAD",
-  "built_at": "2026-10-14T19:30:01.919Z",
+  "built_at": "2026-10-15T15:06:45.205Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 605,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3122,
+    "functional_verbatim": 3128,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3756,
-  "tree_sha256": "c5becc4dfe0e822803424a46f1041b66adce70cbe65f85be941603de3db80cee",
+  "file_count": 3762,
+  "tree_sha256": "7fb72ed794b2cdaa7f0fe66ffdccb7b56f5c18a9d4d66f18b4767254072e1827",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -312,7 +312,7 @@
     {
       "path": "bin/bongos.js",
       "mode": "0000755",
-      "sha256": "20794ff2c632668d2a65ab1ca1a0e6d5b240c19769dbabf6999c7347d41f54e6"
+      "sha256": "f2a64dc742bb1f13938840c9f294ea7a60f1895dc9366200e33d53891e5e0fe5"
     },
     {
       "path": "clients/bongos-client/README.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f2b2bf656d2fa819a7bd0f10ceb966b5414c1c06f05f2e8ccaa9ed326a7227ed"
+      "sha256": "a1ec4ace0bc91b34031c59bb4fd08263af542f5ddd1284204bfd821cf843b527"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7242,7 +7242,7 @@
     {
       "path": "modules/lifecycle/github-push.js",
       "mode": "0000644",
-      "sha256": "65386fff8736c1b55c1f105c595758161e718352077603d1ba9aa7dd05d6d1d6"
+      "sha256": "b15eb0c36f0acb41d11f52393ca9696de55b9326a483de02624b3a4d5e87250c"
     },
     {
       "path": "modules/lifecycle/goal-advisory.js",
@@ -7349,6 +7349,11 @@
       "mode": "0000644",
       "sha256": "69e9bf495dfdbc324e7f5664e09a5ad30e6eac896c12656b7d6ecb38d6be81f9"
     },
+    {
+      "path": "modules/lifecycle/local-land-proof.js",
+      "mode": "0000644",
+      "sha256": "7698b11de1978c29c1744032da5b28831a1f6823b905d60c8be8ac469916d46a"
+    },
     {
       "path": "modules/lifecycle/matter-acts.js",
       "mode": "0000644",
@@ -7507,7 +7512,7 @@
     {
       "path": "modules/lifecycle/publish-reconciler.js",
       "mode": "0000644",
-      "sha256": "5d8bf02c3646f12debc411aa6291110c5bc4f1fe8917af9e17a4ecc5f6451e76"
+      "sha256": "d03c36a2b3e50bb2334db66d177514542185a7277873891ee6d3a99c5ad10464"
     },
     {
       "path": "modules/lifecycle/removal-derivation.js",
@@ -7924,6 +7929,11 @@
       "mode": "0000644",
       "sha256": "22904d8c06daabb634b55f240b895c906e90ba4c6ed81e7a41cdbbb78635ace8"
     },
+    {
+      "path": "modules/onboarding/howto-guide.js",
+      "mode": "0000644",
+      "sha256": "18984c946d746da66ff7678379e9f49c9cfdcdb8f70d2acd852ab29c820baad0"
+    },
     {
       "path": "modules/onboarding/module.json",
       "mode": "0000644",
@@ -10467,12 +10477,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "e92fbdef629a9283a773d94986531ae9d30412fe05dc3012dd918be8fb859030"
+      "sha256": "cb1fe1a974c6063f91ae16893f1daddb028647374dc13d9df725ea4be5074d9a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "cf96b6c94e06d4306f0b3e3c0626c051729a0498bd3e6760012ce86350286d16"
+      "sha256": "e92ae06c5b33aa14e3ec516f009526f335ebec59b5e03b4e774a4a48c252d087"
     },
     {
       "path": "public-docs/index.html",
@@ -10492,7 +10502,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "86c4edcb22bf8005ac7f4e479a9b4037d2bdad36618ed1e8f739a3a786952344"
+      "sha256": "415b376c73ce06c6803897093c02aa9157378d55487a0f84dd8387dc749a75a0"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10869,6 +10879,11 @@
       "mode": "0000644",
       "sha256": "9dd80d2c37602c59cb75db0be02cfadc737fc64891a81d03f5be5f0ea5e35a27"
     },
+    {
+      "path": "scripts/gds/core-pin-sync.js",
+      "mode": "0000644",
+      "sha256": "f8a3a0ee2c0f4dbc2583603cd6e7b547140a5f8dc286b7c5f0b6dadd6096a002"
+    },
     {
       "path": "scripts/gds/coreB-carve-proof.sh",
       "mode": "0000644",
@@ -12812,7 +12827,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "01bc6b541cf12105be05701170377582f537316fe3f70fdea2681bae07864bf7"
+      "sha256": "81694f072dbbb4e64a286a4f5157d07a8e1105ae8a94d800f09eba00f30848e6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13824,6 +13839,11 @@
       "mode": "0000644",
       "sha256": "a3cf352d5dc340b453b22513c28d8c0a439526862535f51f84b7aea2161c734f"
     },
+    {
+      "path": "tests/core_pin_sync.mjs",
+      "mode": "0000644",
+      "sha256": "ac3714b1b089ba2450f1125c74cbe5491deb4ddec1eec77c4c83a8a635a84d93"
+    },
     {
       "path": "tests/core_update_banner.mjs",
       "mode": "0000644",
@@ -15579,6 +15599,11 @@
       "mode": "0000644",
       "sha256": "7cd031d48b41424a654ddc66404cf112a21ecc7d558256ac27ec9357401f112c"
     },
+    {
+      "path": "tests/howto_guide.mjs",
+      "mode": "0000644",
+      "sha256": "8e9b206fdde738f289bc11e204852595e9128b523cfc20cd67e3e83fb60a2fac"
+    },
     {
       "path": "tests/html_comment_nesting.mjs",
       "mode": "0000644",
@@ -16109,6 +16134,11 @@
       "mode": "0000644",
       "sha256": "64f8bd94dc461ca9b4ef82fae929d49675231afa6a24d6d65ba2dbe8721efc89"
     },
+    {
+      "path": "tests/local_land_proof.mjs",
+      "mode": "0000644",
+      "sha256": "0a7825f1e35c7251c66ab986555b71728575d3dff8be95f8a017dd66190d186f"
+    },
     {
       "path": "tests/local_preview.mjs",
       "mode": "0000644",
@@ -17342,7 +17372,7 @@
     {
       "path": "tests/publish_reconciler.mjs",
       "mode": "0000644",
-      "sha256": "fac182001ce8a53bafea2d59661d2879c2ccbac55600936d151d1fe86ca59b71"
+      "sha256": "882dfd49bebd89bed3c2bb20d0bf78e5f7b4da45e525492e8742b43f9c4e19a9"
     },
     {
       "path": "tests/publish_status_branch.mjs",

package/bin/bongos.js

@@ -190,6 +190,15 @@ function main(argv) {
     return 0;
   }
 
+  // Run the core the checkout PINS (task 1004632). A task worktree has no node_modules
+  // of its own, so after a core update lands it resolves the main checkout's older core
+  // and the ship fails on a bug the pin already fixed. `ship` installs the pinned core
+  // into the checkout and re-runs under it; scripts/gds/core-pin-sync.js.
+  if (!COMPILED && verb === 'ship') {
+    const synced = require('../scripts/gds/core-pin-sync.js').ensurePinnedCore({ coreRoot: REPO_ROOT, argv });
+    if (synced != null) return synced;
+  }
+
   // `bongos exec <relpath> [args]` — run a core script by its package-relative path (see above).
   if (verb === 'exec') {
     if (COMPILED) {

package/docs/module-api-changelog.md

@@ -3083,5 +3083,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.121 with no explicit bump. run 38620147259. (task 1002620)
   1.21.123 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.122 with no explicit bump. run 38624070870. (task 1002620)
+  1.21.124 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.123 with no explicit bump. run 38626749089. (task 1002620)
+  1.21.125 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.124 with no explicit bump. run 38757326466. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/github-push.js

@@ -1194,7 +1194,8 @@ async function landProvenForTask({ taskId, publishedSha, status }, deps = {}) {
 async function isAncestorOfDefaultBranch({ sha, base = 'main' } = {}, deps = {}) {
   if (typeof sha !== 'string' || !SAFE_SHA_RE.test(sha)) return false;
   const token = await resolveToken(deps);
-  if (!token) throw err('PUSH_UNCONFIGURED');
+  // task 1004633: no credential (a laptop-mode instance) → ask the instance's own checkout.
+  if (!token) return (deps.localLandProof || require('./local-land-proof')).isOnOriginMain({ sha, base }, deps.local || {});
   const repoInfo = deps.repoInfo || loadRepoInfo();
   if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
   const { owner, repo } = repoInfo;

package/modules/lifecycle/local-land-proof.js

@@ -0,0 +1,126 @@
+'use strict';
+
+// local-land-proof — prove a land from the instance's OWN git checkout when the
+// server holds no GitHub credential (task 1004633).
+//
+// WHY. Every land proof the lifecycle had asked GitHub: isAncestorOfDefaultBranch
+// runs the compare API, and the publish reconciler returned early when
+// isConfigured() was false. A laptop-mode instance (the owner's mercury project)
+// merges a ship LOCALLY and pushes main itself — no PR, no server credential. So
+// POST /tasks/:id/ship refused `ship_land_not_proven` (the compare threw
+// PUSH_UNCONFIGURED, swallowed as "no proof"), the sweep never ran, and task 48
+// sat at 'confirmed' with its merge commit on origin/main.
+//
+// THE PROOF is the same one the GitHub path makes, asked of a different witness:
+// is the claim's recorded tip (claims.published_head_sha, written by attest-gate
+// before its own credential check) an ancestor of origin/<base>? The witness is
+// the remote-tracking ref after a fetch, never the local branch: a laptop ship
+// merges into local main BEFORE it pushes, and a merge whose push failed must not
+// count. A failed fetch (offline) falls back to the last fetched ref, which can
+// only be behind the truth, so it can delay a ship but never invent one.
+//
+// Pure w.r.t. an injected `git` runner, so it unit-tests with no repository.
+
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileP = promisify(execFile);
+
+// A real commit sha only: `merge-base` resolves refs, so "HEAD" or a branch name
+// would answer about something other than the claim's tip.
+const SAFE_SHA_RE = /^[0-9a-f]{7,64}$/;
+const SAFE_BASE_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,100}$/;
+
+function defaultGit(root) {
+  return (args) => execFileP('git', args, { cwd: root, timeout: 60_000, windowsHide: true });
+}
+
+function resolveRoot(deps) {
+  if (deps.root) return deps.root;
+  return require('../../src/module-api').resolveInstanceRoot();
+}
+
+async function fetchOrigin(git, base) {
+  try {
+    await git(['fetch', '--quiet', 'origin', base]);
+  } catch (_) {
+    /* offline or no credential: the last fetched origin ref still answers, only later */
+  }
+}
+
+// true = the tip is in origin/<base>; false = it is not (or git does not know the
+// commit). Throws LOCAL_PROOF_UNAVAILABLE when there is no usable checkout (git
+// missing, not a repository) so a caller can tell "not landed" from "cannot say".
+async function isOnOriginMain({ sha, base = 'main' } = {}, deps = {}) {
+  if (typeof sha !== 'string' || !SAFE_SHA_RE.test(sha)) return false;
+  if (typeof base !== 'string' || !SAFE_BASE_RE.test(base) || base.includes('..')) return false;
+  const git = deps.git || defaultGit(resolveRoot(deps));
+  if (!deps.fetched) await fetchOrigin(git, base);
+  try {
+    await git(['merge-base', '--is-ancestor', sha, `refs/remotes/origin/${base}`]);
+    return true;
+  } catch (e) {
+    // 1 = not an ancestor; 128 = an unknown commit (never reached origin).
+    if (e && (e.code === 1 || e.code === 128)) return false;
+    const out = new Error('LOCAL_PROOF_UNAVAILABLE');
+    out.code = 'LOCAL_PROOF_UNAVAILABLE';
+    out.cause = e;
+    throw out;
+  }
+}
+
+// The reconciler's sweep for a host with no GitHub credential. Tip proof only: no
+// PR, branch or deploy probe exists to consult, and a row with no recorded tip
+// has nothing local to prove, so it waits (strand-watch reports it).
+// One root and one fetch per sweep, not per row: origin/main is the same ref for
+// every confirmed task the sweep reads.
+async function sweepByLocalProof(rows, { db, emit, log = console.log, error = console.error, proof } = {}) {
+  if (!proof) {
+    let shared = null;
+    proof = async ({ sha }) => {
+      if (!shared) {
+        shared = { git: defaultGit(resolveRoot({})), fetched: true };
+        await fetchOrigin(shared.git, 'main');
+      }
+      return isOnOriginMain({ sha }, shared);
+    };
+  }
+  let checked = 0;
+  let reconciled = 0;
+  let errors = 0;
+  for (const r of rows || []) {
+    const tip = r && r.published_head_sha;
+    if (!tip || !SAFE_SHA_RE.test(String(tip))) continue;
+    checked++;
+    let landed = false;
+    try {
+      landed = await proof({ sha: String(tip) });
+    } catch (e) {
+      errors++;
+      error(`[publish-reconciler] task ${r.task_id}: local land proof unavailable: ${e && e.message}`);
+      continue;
+    }
+    if (!landed) continue;
+    const reason = `published tip ${String(tip).slice(0, 8)} in origin/main (local checkout; no GitHub credential)`;
+    try {
+      const shipped = await db.shipTask({
+        taskId: r.task_id,
+        builderId: r.builder_id,
+        landAssurance: { kind: 'proof', reason },
+      });
+      reconciled++;
+      log(`[publish-reconciler] task ${r.task_id} (${reason}) landed → shipped`);
+      try { await emit('task.shipped', shipped); } catch (e) {
+        error(`[publish-reconciler] ship broadcast for task ${r.task_id} (non-blocking): ${e && e.message}`);
+      }
+    } catch (e) {
+      if (!e || e.code !== 'TASK_NOT_CONFIRMED') {
+        errors++;
+        error(`[publish-reconciler] shipTask ${r.task_id} failed: ${e && e.message}`);
+      }
+    }
+  }
+  return { checked, reconciled, errors };
+}
+
+module.exports = { isOnOriginMain, sweepByLocalProof, SAFE_SHA_RE };

package/modules/lifecycle/publish-reconciler.js

@@ -76,6 +76,7 @@
 const githubPush = require('./github-push');
 const seams = require('../../src/module-api');
 const conflictResolve = require('./conflict-resolve');
+const localLandProof = require('./local-land-proof'); // task 1004633
 // The claim gate's grace for a strand its builder may be unable to clear — imported
 // rather than restated so the sweep's escalation and the gate agree on one number
 // (task 1003294).
@@ -195,10 +196,22 @@ async function runSweep(deps = {}) {
     if (!warn.unconfigured) {
       warn.unconfigured = true;
       errFn(
-        `[publish-reconciler] WARN ${describeTarget({ configured: false, repo: resolveTarget(deps) })} — confirmed→shipped can NEVER land until a credential is set (GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY — installation id is auto-discovered — or GITHUB_PUSH_TOKEN). Subsequent sweeps stay quiet until this changes.`
+        `[publish-reconciler] WARN ${describeTarget({ configured: false, repo: resolveTarget(deps) })} — no GitHub credential (GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY — installation id is auto-discovered — or GITHUB_PUSH_TOKEN): confirmed→shipped lands only on a recorded tip this instance's own checkout finds in origin/main. Subsequent sweeps stay quiet until this changes.`
       );
     }
-    return { skipped: 'unconfigured', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 0, strandsFlagged: 0 };
+    // task 1004633: a laptop-mode instance merges and pushes main itself, with no
+    // server credential. Returning here stranded its merged tasks at 'confirmed'
+    // forever (mercury task 48), so prove the recorded tip from the local checkout.
+    const local = deps.localLandProof || localLandProof;
+    let rows = [];
+    try {
+      rows = await db.listConfirmedTasksForReconcile({ limit: deps.limit || SWEEP_LIMIT });
+    } catch (e) {
+      errFn(`[publish-reconciler] could not list confirmed tasks: ${e && e.message}`);
+      return { skipped: 'unconfigured', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 1, strandsFlagged: 0 };
+    }
+    const swept = await local.sweepByLocalProof(rows, { db, emit, log: logFn, error: errFn });
+    return { skipped: 'unconfigured', checked: swept.checked, reconciled: swept.reconciled, merged: 0, resolvedConflicts: 0, errors: swept.errors, strandsFlagged: 0 };
   }
   warn.unconfigured = false; // re-arm: a later credential LOSS must warn again
 

package/modules/onboarding/howto-guide.js

@@ -0,0 +1,259 @@
+// modules/onboarding/howto-guide.js — the in-session how-to guide: ~25 short steps an AI walks a person through (task 1004627)
+//
+// WHY. The owner opened Bongos on their own project and did not know where to begin:
+// nothing told them `/builder-start` exists, what a goal is for, or what happens on a
+// first ship. This guide is the CONTENT an AI assistant walks a person through inside
+// their own session, one short step at a time, at the moment it is useful — so someone
+// who has never heard of a Bongos command is never lost.
+//
+// It is the single source of truth for the three tasks that build on it:
+//   • task 1004634 stores each person's read/unread state per step id;
+//   • task 1004635 shows the right unread step when its moment arrives, then marks it read;
+//   • task 1004636 lets a person reopen the guide, see progress, or skip it.
+// So the step ids are STABLE: a stored "read" mark names one. Never rename or reuse an
+// id — retire a step by deleting it and add a new id for new content
+// (tests/howto_guide.mjs pins the shape and the plain-language rule).
+//
+// Each step is: what the feature is FOR (`what`), WHEN to reach for it (`when`), and the
+// exact words or command to TRY (`try`). Plain language throughout — the reader may not
+// be technical; the test bans the accessibility scorer's jargon list. Commands are the
+// ones an instance actually gets (core skills + `npx bongos` verbs); a step names a
+// slash command AND the plain words that reach it, because typed-only commands do not
+// answer to plain words.
+//
+// Read it in a terminal: `node modules/onboarding/howto-guide.js` (add `--moment <id>`).
+
+'use strict';
+
+// The moments, in the order a new project meets them. `trigger` says, for task 1004635,
+// what event opens the moment; it is descriptive here, not wiring.
+const MOMENTS = Object.freeze([
+  { id: 'first_open', title: 'Opening the project for the first time', trigger: 'the first prompt of the first session in a project folder' },
+  { id: 'setup', title: 'Setting up the project', trigger: 'the project has no goal yet, or setup is unfinished' },
+  { id: 'goal', title: 'Creating a goal', trigger: 'the person asks to plan work, or the project has no open goal' },
+  { id: 'task', title: 'Creating a task', trigger: 'the person describes a change they want, or a goal has no tasks' },
+  { id: 'find_work', title: 'Finding work', trigger: 'the person asks what to do next, or starts a session with nothing claimed' },
+  { id: 'first_claim', title: 'Claiming your first task', trigger: 'the person claims a task for the first time' },
+  { id: 'first_ship', title: 'Your first ship', trigger: 'the person finishes the work on their first claimed task' },
+  { id: 'after_ship', title: 'After a ship', trigger: 'a task reaches shipped for the first time' },
+  { id: 'invite', title: 'Inviting people', trigger: 'the person mentions a teammate, or asks how others can help' },
+  { id: 'settings', title: 'Settings', trigger: 'the person asks to change how Bongos behaves for them or the project' },
+  { id: 'stuck', title: 'When something goes wrong', trigger: 'a command fails, or the person says they are stuck or confused' },
+]);
+
+const STEPS = Object.freeze([
+  // first_open
+  {
+    id: 'welcome', moment: 'first_open', title: 'What Bongos is',
+    what: 'Bongos keeps the list of everything your project needs, and the AI does the building. You decide what gets made; the AI does the work and records it.',
+    when: 'The first time you open this project with an AI assistant.',
+    try: 'Ask: "What is Bongos and what can it do for me?"',
+  },
+  {
+    id: 'where_to_start', moment: 'first_open', title: 'Where to start',
+    what: 'There are three ways in: finish setting up the project, make a goal (a bigger outcome you want), or make a task (one piece of work).',
+    when: 'Any time you are not sure what to do first.',
+    try: 'Say: "Where should I start?" The AI will look at the project and suggest one of the three.',
+  },
+  {
+    id: 'ask_in_plain_words', moment: 'first_open', title: 'Just ask in plain words',
+    what: 'You never need to memorise commands. Describe what you want and the AI picks the right one, then tells you which it used.',
+    when: 'Whenever you want something done and do not know the command.',
+    try: 'Say: "I want to add a contact form to the website."',
+  },
+  {
+    id: 'the_hall', moment: 'first_open', title: 'The hall: your project in a browser',
+    what: 'The hall is your project\'s web page. It shows goals, tasks, who is working on what, and what has shipped.',
+    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?"',
+  },
+  // setup
+  {
+    id: 'sign_in', moment: 'setup', title: 'Sign in once',
+    what: 'Signing in links this computer to your project, so the AI can claim and ship work in your name.',
+    when: 'The first time on a new computer, or when the AI says your sign-in has expired.',
+    try: 'Type /builder-setup, or in a terminal run `npx bongos login`.',
+  },
+  {
+    id: 'check_setup', moment: 'setup', title: 'Check everything is ready',
+    what: 'A quick health check of this computer and your sign-in, with a plain fix for anything missing.',
+    when: 'Before your first task, or when something that used to work stops working.',
+    try: 'Say: "Check my setup", or run `npx bongos doctor`.',
+  },
+  {
+    id: 'project_status', moment: 'setup', title: 'See where the project stands',
+    what: 'A summary of the current version: what is done, what is left, and what is blocking.',
+    when: 'At the start of a working session, or before planning.',
+    try: 'Type /status, or say "How far along is the project?"',
+  },
+  // goal
+  {
+    id: 'what_is_a_goal', moment: 'goal', title: 'What a goal is',
+    what: 'A goal is a bigger outcome, like "people can sign up" — a home for the tasks that get you there, with a clear "done when".',
+    when: 'When what you want is too big to finish in one sitting.',
+    try: 'Ask: "Should this be a goal or a single task?"',
+  },
+  {
+    id: 'create_goal', moment: 'goal', title: 'Create a goal',
+    what: 'The AI asks what the goal is for and what "done" looks like, then writes it up with its first few tasks.',
+    when: 'When you have decided on a new outcome to work towards.',
+    try: 'Type /goal-create, or say "Make a goal for letting people sign up."',
+  },
+  // task
+  {
+    id: 'what_is_a_task', moment: 'task', title: 'What a task is',
+    what: 'A task is one piece of work small enough to finish and check in one go. Every change to the project belongs to a task, so there is always a record of it.',
+    when: 'Whenever you want something changed.',
+    try: 'Ask: "What makes a good task?"',
+  },
+  {
+    id: 'create_task', moment: 'task', title: 'Create a task',
+    what: 'Describe the change and how you will know it is done. The AI writes it up and files it under the right goal.',
+    when: 'When you know a specific change you want.',
+    try: 'Say: "Make a task: the contact form should email me each message."',
+  },
+  {
+    id: 'capture_an_idea', moment: 'task', title: 'Save an idea for later',
+    what: 'Not ready to commit to it? Save it as an idea. Ideas wait in a list until you decide to turn them into tasks or drop them.',
+    when: 'When a thought comes up in the middle of other work.',
+    try: 'Say: "Save an idea: a dark mode for the website."',
+  },
+  // find_work
+  {
+    id: 'whats_claimable', moment: 'find_work', title: 'See what you can work on',
+    what: 'A list of the tasks that are ready right now and safe to start without clashing with anyone else\'s work.',
+    when: 'At the start of a session, or when you finish a task.',
+    try: 'Type /builder-start, or say "What can I work on?"',
+  },
+  {
+    id: 'work_a_goal', moment: 'find_work', title: 'Work through a whole goal',
+    what: 'The AI takes the goal\'s tasks one at a time — start, build, ship, next — and stops to ask you only when it needs a decision.',
+    when: 'When a goal has several tasks that follow on from each other.',
+    try: 'Say: "Work through goal 12 end to end", or type /builder-sequence.',
+  },
+  // first_claim
+  {
+    id: 'claim_a_task', moment: 'first_claim', title: 'Claiming a task',
+    what: 'Claiming says "I am on this one", so nobody else starts the same work. The AI then works on it in its own separate copy of the project, so your main folder stays tidy.',
+    when: 'When you pick a task to work on.',
+    try: 'Type /builder-claim followed by the task number, or say "Claim task 42."',
+  },
+  {
+    id: 'give_a_task_back', moment: 'first_claim', title: 'Give a task back',
+    what: 'Changed your mind? Giving it back makes the task available again. Nothing is lost and nothing is charged.',
+    when: 'When you will not finish a task you claimed.',
+    try: 'Type /builder-release, or say "Give this task back."',
+  },
+  {
+    id: 'preview_before_ship', moment: 'first_claim', title: 'See a change before it ships',
+    what: 'For changes you can see, the AI can show you the page as it will look, before anything goes live.',
+    when: 'When the task changes something on screen.',
+    try: 'Say: "Let me see it before you ship", or type /builder-stage.',
+  },
+  // first_ship
+  {
+    id: 'what_ship_does', moment: 'first_ship', title: 'What shipping does',
+    what: 'Shipping finishes a task: automatic reviewers check the work, then it is added to the project. Going live for your users can wait for a person to say yes.',
+    when: 'When the work on your task is finished.',
+    try: 'Type /builder-ship, or say "Ship it."',
+  },
+  {
+    id: 'review_findings', moment: 'first_ship', title: 'When the reviewers ask for fixes',
+    what: 'If the reviewers find a problem, the task is held, not lost. The AI fixes what they listed and asks for another review.',
+    when: 'When a ship says it needs fixes.',
+    try: 'Say: "Fix what the reviewers found and try again."',
+  },
+  // after_ship
+  {
+    id: 'what_happens_after', moment: 'after_ship', title: 'What happens after a ship',
+    what: 'The task is marked shipped, anything that was waiting on it becomes ready, and the record of the work is kept for the next person.',
+    when: 'Right after your first task ships.',
+    try: 'Ask: "What did that ship unlock?"',
+  },
+  {
+    id: 'fresh_session', moment: 'after_ship', title: 'Start fresh after a few tasks',
+    what: 'A long conversation gets slower and costlier. After a few tasks, the AI can write a short note so a fresh conversation picks up exactly where you left off.',
+    when: 'After three or so tasks in one conversation.',
+    try: 'Say: "Hand this off to a fresh session", or type /session-handoff.',
+  },
+  // invite
+  {
+    id: 'invite_people', moment: 'invite', title: 'Invite people',
+    what: 'Bring someone onto the project by their GitHub name. You choose whether anyone can join, people must ask first, or only invited people can sign in.',
+    when: 'When you want someone else to help build.',
+    try: 'In the hall, use "Invite someone" and enter their GitHub name, or ask "How do I invite someone?"',
+  },
+  {
+    id: 'ask_for_help', moment: 'invite', title: 'Ask a teammate for help',
+    what: 'Send a named person, or anyone with the right skills, a request for help on a task. It shows up in their own list.',
+    when: 'When you are stuck on a task and someone else knows the area.',
+    try: 'Say: "Ask Sam to help with task 42", or type /ask-for-help.',
+  },
+  // settings
+  {
+    id: 'ship_mode', moment: 'settings', title: 'Ship mode: who starts a ship',
+    what: 'In Auto, the AI ships a finished task by itself. In Manual, it stops and waits for you to say "ship it".',
+    when: 'When you want more, or less, control over when work is added to the project.',
+    try: 'In the hall\'s project settings pick Auto or Manual, or run `npx bongos ship-mode` to see the current one.',
+  },
+  {
+    id: 'how_the_ai_talks', moment: 'settings', title: 'How the AI talks to you',
+    what: 'Tell Bongos how technical you are and how long you like answers. Every AI session on this project follows it.',
+    when: 'When answers feel too technical, too long, or too short.',
+    try: 'Open your settings in the hall and look for how the AI talks to you, or say "Keep your answers shorter."',
+  },
+  // stuck
+  {
+    id: 'when_stuck', moment: 'stuck', title: 'When something goes wrong',
+    what: 'Every refusal comes with a plain explanation: what happened, what the AI will do, and whether it needs you. Most fix themselves.',
+    when: 'When a command fails or you do not understand what happened.',
+    try: 'Say: "Explain that in plain words and fix it."',
+  },
+  {
+    id: 'tell_the_bongos_team', moment: 'stuck', title: 'Tell the Bongos team',
+    what: 'If Bongos itself gets in your way, say so. Your words go to the people who build Bongos, and each complaint becomes a fix.',
+    when: 'Whenever Bongos is confusing, slow, or broken.',
+    try: 'Say: "Bongos feedback: …" followed by what went wrong.',
+  },
+]);
+
+const MOMENT_IDS = new Set(MOMENTS.map((m) => m.id));
+
+function stepById(id) { return STEPS.find((s) => s.id === id) || null; }
+
+// The steps for one moment, in guide order. Unknown moment → [].
+function stepsForMoment(momentId) { return STEPS.filter((s) => s.moment === momentId); }
+
+// The first step not in `readIds` (an iterable of step ids), in guide order — what
+// "continue the tutorial" means. null when everything is read.
+function nextUnread(readIds) {
+  const read = new Set(readIds || []);
+  return STEPS.find((s) => !read.has(s.id)) || null;
+}
+
+function formatStep(step) {
+  return [`${step.title}  [${step.id}]`, `  What it is for: ${step.what}`, `  When: ${step.when}`, `  Try: ${step.try}`].join('\n');
+}
+
+function formatGuide({ moment = null } = {}) {
+  const out = [];
+  for (const m of MOMENTS) {
+    if (moment && m.id !== moment) continue;
+    out.push(`## ${m.title}`);
+    for (const s of stepsForMoment(m.id)) out.push(formatStep(s), '');
+  }
+  return out.join('\n').trimEnd() + '\n';
+}
+
+if (require.main === module) {
+  const i = process.argv.indexOf('--moment');
+  const moment = i > -1 ? process.argv[i + 1] : null;
+  if (moment && !MOMENT_IDS.has(moment)) {
+    process.stderr.write(`unknown moment "${moment}" — one of: ${[...MOMENT_IDS].join(', ')}\n`);
+    process.exitCode = 2;
+  } else {
+    process.stdout.write(formatGuide({ moment }));
+  }
+}
+
+module.exports = { MOMENTS, STEPS, MOMENT_IDS, stepById, stepsForMoment, nextUnread, formatStep, formatGuide };

package/package-lock.json

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

package/package.json

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