@bongos/core 1.18.3 → 1.18.18

package/scripts/gds/gen-diagrams.js

@@ -104,8 +104,8 @@ const LIFECYCLE_EDGES = [
   ['blocked', 'active', 'blocker resolved'],
   ['active', 'ready', '/builder-release (no credits)'],
   ['active', 'completed', '/builder-ship: declared done + smoke tests'],
-  ['completed', 'confirmed', 'grader passes  ◀ CREDITS AWARDED HERE'],
-  ['confirmed', 'shipped', 'CI + gate-review → auto-merge + deploy'],
+  ['completed', 'confirmed', 'grader passes  (verified — not yet paid)'],
+  ['confirmed', 'shipped', 'CI + gate-review → auto-merge + deploy  ◀ CREDITS AWARDED HERE'],
   ['backlog', 'abandoned', 'dropped'],
 ];
 
@@ -297,7 +297,7 @@ function drachmaeKarmaMmd(f) {
     `    subgraph CURRENCY["${CUR}  (the builder reward — equity / reputation, a stake, not a spendable currency)"]`,
     '        direction TB',
     '        D_TOKEN["Ship a SESSION — the main reward\\nround(true_cost_usd × 1.20) cents — cost-plus on real token spend\\n(LIVE: priced server-side from token counts; ADR 0054, idempotent per session)"]',
-    '        D_SHIP["Confirm a TASK\\ncredits_reward × kind multiplier (0.8–1.5×)\\n+ 25% idea-promotion bonus to the capturer\\n(LIVE: ADR 0023)"]',
+    '        D_SHIP["SHIP a TASK — books when the code lands on main, not at confirm\\ncredits_reward × kind multiplier (0.8–1.5×)\\n+ 25% idea-promotion bonus to the capturer\\n(LIVE: ADR 0023; pay-on-land ADR 0120; withheld entirely on a cost-plus-only instance, ADR 0146)"]',
     `        D_ACH["Unlock an achievement\\nachievements.credit_bonus (LIVE: ${nAch} seeded)\\n+ small net-negative-ship bonus"]`,
     `        D_BOUNTY["Red-team / security bounty\\n${currency} payout by severity\\n(rate card ${rateCard ? 'LIVE' : 'PLANNED'}: R65 #284 — src/bongos/security.js + shown on /builders;\\nawarding still ${awarding ? 'LIVE' : 'PLANNED'}: R67 #286 + vulnerability_reports R63 #282)"]`,
     '',
@@ -375,10 +375,18 @@ function architectureMmd(f) {
     ? 'GitHub App, short-lived tokens'
     : 'standing push PAT (GitHub App pending — 1028)';
   // The whole box→prod chain LIVE? (all the gated legs + the end-to-end verify.)
-  const chainLive = [919, 897, 904, 774, 1025, 859, 1028, 1027].every(shipped);
+  // NB the deploy leg is the standalone AUTO-PULL (ADR 0108/0129), not a task-gated
+  // GitHub-Actions CI job — so 859 (CI deploy) is intentionally NOT in this set.
+  const chainLive = [919, 897, 904, 774, 1025, 1028, 1027].every(shipped);
   const closingNote = chainLive
-    ? 'The whole box → production path is LIVE and hardware-verified end-to-end (1027 · 1028).'
-    : `Still landing (PLANNED): hardware-verify the box → prod flow end-to-end (${tag(1027)} · 1027) and the GitHub App push credential (${tag(1028)} · 1028).`;
+    ? 'The whole box → production path is LIVE: a credential-less box uploads its branch, the server merges it, and the instance auto-pulls + redeploys — hardware-verified end-to-end (1027 · 1028).'
+    : `Still landing (PLANNED): the server-mediated publish (${tag(1025)} · 1025) and the GitHub App push credential (${tag(1028)} · 1028).`;
+
+  // Product-neutral runtime label: the instance's own product name (branding),
+  // NOT a hard-coded "game" (this core powers any app, not only the reference
+  // game instance). Falls back to a generic phrase when branding carries none.
+  const productName = brand().productName;
+  const appLabel = productName && productName !== 'Cloud Bongos' ? productName : 'app';
 
   // Layout: ELK engine, top-down (task 1066). ELK minimizes edge crossings far
   // better than the default renderer — this map is edge-dense and was a tangle
@@ -390,16 +398,18 @@ function architectureMmd(f) {
   // low-signal annotation edges (box-token→bootstrap, DB-is-king, memory-
   // follows-you) are folded into node labels. (3) WATERFALL ordering (task 1073,
   // off Lars's "put the GitHub box last"): subgraphs are declared in flow order
-  // DEVICE→BOX→SERVER→GH, and the live game is pulled OUT of the SERVER cluster
-  // into its own terminal node at the very bottom (annotated "same droplet · same
-  // Node process" so it stays honest). That makes the map one monotonic top-down
-  // spine — device→box→server→github→live game — where the deploy is the LAST
-  // forward step instead of an edge looping back UP into the server. So SERVER
-  // tucks directly under BOX and the five BOX↔SERVER wires (re-auth, upload,
-  // sync, pull, claim/ship) become short hops instead of detouring the full
-  // height past a mid-stack GitHub. The redundant unlabelled ACTIONS→API edge is
-  // dropped: API and the game are the same Node process, so the single labelled
-  // ACTIONS→GAME deploy edge already carries it. NOTE on direction: we keep TB,
+  // DEVICE→BOX→SERVER→GH, and the live app (the instance's product runtime) is
+  // pulled OUT of the SERVER cluster into its own terminal node at the very
+  // bottom (annotated "same server · same Node process" so it stays honest).
+  // That makes the map one monotonic top-down spine — device→box→server→github→
+  // live app — where the deploy is the LAST forward step instead of an edge
+  // looping back UP into the server. So SERVER tucks directly under BOX and the
+  // BOX↔SERVER wires (re-auth, upload, sync, pull, claim/ship) become short hops
+  // instead of detouring the full height past a mid-stack GitHub. The deploy is
+  // the STANDALONE auto-pull (ADR 0108/0129): merge to the instance's own main →
+  // the server pulls its own repo → migrate/regenerate/restart → the live app —
+  // NOT a GitHub-Actions push-deploy (that was the reference monorepo's model).
+  // NOTE on direction: we keep TB,
   // not a repo-on-the-left LR/RL — the flow is an ~8-deep linear chain, so a
   // sideways layout stretches into an unreadable ~5:1 strip; top-down keeps a
   // legible aspect.
@@ -419,25 +429,26 @@ function architectureMmd(f) {
     `        CODE["the code — git clone + per-builder worktrees (.claude/worktrees/*)\\nfor sub-Metic builders it lives ONLY here · CLAUDE.md is DESCRIPTIVE only"]`,
     '        LOCAL["local ~/.claude memory\\nMAP = MEMORY.md — a one-line index loaded EVERY session\\n(a guard + auto-tidy keep it light; ADR 0074)\\n+ drawer of full notes, loaded only on demand"]',
     '        ORIGIN["credential-less git origin\\n(NO GitHub push secret on the box — by design)"]',
-    `        BOXTOK["box-scoped GDS token\\n(deny-by-default: bootstrap endpoints only;\\nrejected for branch upload → re-auth first — ${tag(919)})"]`,
+    `        BOXTOK["box-scoped Bongos token\\n(deny-by-default: bootstrap endpoints only;\\nrejected for branch upload → re-auth first — ${tag(919)})"]`,
     `        PREVIEW["sandbox preview server on :3000\\n→ a per-builder sandbox URL (${tag(897)})"]`,
     `        SWITCH["on / off + browser terminal\\n(desktop app ${tag(904)} · ttyd-over-tunnel ${tag(774)})"]`,
     '    end',
     '',
-    `    subgraph SERVER["THE SERVER — ${host} (the authority AND production)"]`,
-    '        API["/api/gds/* (same Node process as the game)"]',
+    `    subgraph SERVER["THE INSTANCE SERVER — ${host} (the authority AND production)"]`,
+    '        API["/api/bongos/* (same Node process as the app)"]',
+    '        CORE["@bongos/core — the build platform, VENDORED as a pinned dependency\\n(ADR 0108: central updates are a version-pin bump via `bongos upgrade`, not a merge)"]',
     '        DB["Postgres — tasks · claims · versions · builders.rank\\ncredit_log · grades · idea_inbox · builder_memory\\n(KING for work-state + permissions; CLAUDE.md only describes it)"]',
     '        RANK["auth.requireRank — checked per request, NO caching\\n(ADR 0016: a demotion takes effect on the next request)"]',
     `        SRVMEM["server-side builder_memory store\\n${memLead}: per-builder · isolated · Archon-audited forensic read\\nyour memory follows you across machines & worktrees\\n/recall fetches only the relevant subset (ADR 0060)\\n(${memStatus})"]`,
     `        PUSHTOK["server-held push credential\\n(${pushCred} — the box never holds it)"]`,
+    '        DEPLOY["auto-pull deploy (ADR 0129)\\na timer pulls THIS instance repo every ~2 min →\\nnpm ci if the pin changed → migrate → regenerate docs → restart → healthz"]',
     '    end',
     '',
-    `    subgraph GH["GITHUB — the code repository (${c.repoSlug})"]`,
-    '        MAIN["branch-protected main\\n(no direct push; PR + required checks only)"]',
-    '        ACTIONS["GitHub Actions — deploy-prod.yml"]',
+    `    subgraph GH["GITHUB — the instance's own repo (${c.repoSlug})"]`,
+    '        MAIN["branch-protected main\\n(no direct push; PR + required checks only)\\nholds config + the pinned @bongos/core — NOT the platform source"]',
     '    end',
     '',
-    `    GAME["the live game — ${host}\\n(same server · same Node process as /api/gds/*)"]`,
+    `    LIVEAPP["the live ${appLabel} — ${host}\\n(same server · same Node process as /api/bongos/*)"]`,
     '',
     '    APP -->|"1 · toggle box on / open terminal"| SWITCH',
     '    SWITCH --> WORKER',
@@ -445,8 +456,9 @@ function architectureMmd(f) {
     '    WORKER -->|"3 · re-auth in browser"| API',
     flow('WORKER', 1025, '4 · upload branch as a git bundle', 'API'),
     flow('API', 1025, `5 · push + open PR + auto-merge (${tag(1025)})`, 'MAIN'),
-    flow('MAIN', 859, `6 · merge triggers deploy (${tag(859)})`, 'ACTIONS'),
-    '    ACTIONS -->|"7 · deploy (no droplet key on any box)"| GAME',
+    '    MAIN -->|"6 · the instance auto-pulls its own main"| DEPLOY',
+    '    DEPLOY -->|"7 · migrate · regenerate docs · restart"| LIVEAPP',
+    '    CORE --- API',
     '    PUSHTOK -.-> API',
     '    ORIGIN -. "direct push blocked" .-> MAIN',
     '    API -. "claim / ship / cost" .-> WORKER',
@@ -454,7 +466,7 @@ function architectureMmd(f) {
     `    ${pullEdge}`,
     '',
     `    NEXT["${closingNote}"]`,
-    '    GAME --- NEXT',
+    '    LIVEAPP --- NEXT',
   ];
   return lines.join('\n') + '\n';
 }
@@ -467,6 +479,11 @@ function rebuildAssertions(prev, f) {
   next.rank_ladder.default_rank = f.default_rank;
   next.rank_ladder.wired_ranks = f.wired_ranks;
   next.task_lifecycle.task_statuses = f.task_statuses;
+  // Derived from LIFECYCLE_EDGES so this assertion can never drift from the
+  // rendered diagram again (it silently outlived ADR 0120's move of the award
+  // from completed→confirmed to confirmed→shipped).
+  const creditEdge = LIFECYCLE_EDGES.find(([, , label]) => label.includes('CREDITS AWARDED HERE'));
+  if (creditEdge) next.task_lifecycle.credits_awarded_at = `${creditEdge[0]}->${creditEdge[1]}`;
   // Persist only the stable identity fields (drop started_at ordering helper).
   next.versioning.diagram = '05-versioning';
   next.versioning.versions = f.versions.map((v) => ({ id: v.id, status: v.status }));
@@ -485,11 +502,11 @@ function rebuildAssertions(prev, f) {
 
     // 04-architecture — the ADR 0024 memory chain + the dev-box / box→prod ship
     // flow, merged (task 1059). A piece is LIVE iff its backing task is shipped.
-    const arch = split([273, 274, 275, 276, 904, 774, 897, 919, 1025, 859, 1027, 1028]);
+    const arch = split([273, 274, 275, 276, 904, 774, 897, 919, 1025, 1027, 1028]);
     next.architecture = {
       diagram: '04-architecture',
       _comment:
-        "Pieces of 04-architecture gated on a backing GDS task. A piece is LIVE iff its task is 'shipped'; live_tasks must ALL be shipped, pending_tasks must NOT yet be. Rebuilt by scripts/gds/gen-diagrams.js in lockstep with the diagram, so this is the drift checker's backstop. The device/box/server/GitHub topology is structural (not task-gated); these are the LIVE/PLANNED markers. MEMORY layer (ADR 0024): 273 schema / 274 sync-on-ship / 275 pull-on-start / 276 isolation. DEV BOX + box→prod: 904/774 (on-off + browser terminal), 897 (sandbox preview), 919 (scoped box token), 1025 (server-mediated publish), 859 (CI deploy), 1028 (GitHub App push credential), 1027 (end-to-end hardware-verify). Supersedes the old server_repo_memory + dev_box slices.",
+        "Pieces of 04-architecture gated on a backing GDS task. A piece is LIVE iff its task is 'shipped'; live_tasks must ALL be shipped, pending_tasks must NOT yet be. Rebuilt by scripts/gds/gen-diagrams.js in lockstep with the diagram, so this is the drift checker's backstop. The device/box/server/GitHub topology is structural (not task-gated); these are the LIVE/PLANNED markers. MEMORY layer (ADR 0024): 273 schema / 274 sync-on-ship / 275 pull-on-start / 276 isolation. DEV BOX + box→prod: 904/774 (on-off + browser terminal), 897 (sandbox preview), 919 (scoped box token), 1025 (server-mediated publish), 1028 (GitHub App push credential), 1027 (end-to-end hardware-verify). The deploy leg is the standalone AUTO-PULL (ADR 0108/0129), not a task-gated GitHub-Actions CI job, so 859 is intentionally absent. Supersedes the old server_repo_memory + dev_box slices.",
       live_tasks: arch.live_tasks,
       pending_tasks: arch.pending_tasks,
     };

package/scripts/gds/gen-file-map.js

@@ -32,6 +32,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
 
 // ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — every target of this generator is
 // INSTANCE-materialized content: the .claude/skills + .claude/scheduled-tasks it lists (materialized
@@ -141,7 +142,7 @@ function computeWrites() {
       if (next.indexOf(begin(m.dir + '/')) === -1) { markersMissing.push(m.dir); continue; }
       next = injectSection(next, m);
     }
-    if (next !== cur) writes.push({ full: MAP_PATH, content: next, rel: 'docs/file-map.md' });
+    if (!sameContent(next, cur)) writes.push({ full: MAP_PATH, content: next, rel: 'docs/file-map.md' });
   }
   return { model, writes, missing, stale, markersMissing };
 }

package/scripts/gds/gen-freshness.js

@@ -0,0 +1,32 @@
+// gen-freshness.js — how the doc generators decide "is the committed copy stale?"
+//
+// Shared by gen-repo-map / gen-session-index / gen-file-map / gen-api-docs, whose
+// `--check` / `--check-block` modes back the fitness.js `generated artifacts fresh`
+// hard gate.
+//
+// Why this exists: the generators render their blocks with `join('\n')` — always
+// LF — but read the working copy with readFileSync, which on a `core.autocrlf=true`
+// checkout (every default Windows clone) returns CRLF. A byte-wise `next !== cur`
+// then reports STALE forever, and regenerating never clears it: the write lands as
+// LF, git normalizes it back to CRLF on the next checkout, and the gate is red
+// again. That is worse than noisy — a permanently-failing hard gate trains builders
+// to ignore it, and it hides REAL drift, since the check is red either way.
+//
+// Freshness is a question about content, so compare content. Written bytes are
+// unaffected: callers still write exactly the string they built, and git applies
+// its own eol policy on commit.
+'use strict';
+
+// CRLF → LF. Lone-CR (classic Mac) is not normalized; no generator emits it and
+// no checkout policy produces it, so treating it as content keeps this honest.
+function normalizeEol(s) {
+  return String(s == null ? '' : s).replace(/\r\n/g, '\n');
+}
+
+// True when two documents are identical apart from line-ending convention.
+// Use this for every freshness comparison — never `===` on raw file bytes.
+function sameContent(a, b) {
+  return normalizeEol(a) === normalizeEol(b);
+}
+
+module.exports = { normalizeEol, sameContent };

package/scripts/gds/gen-repo-map.js

@@ -35,6 +35,7 @@ const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-con
 // build the doc link-graph + staleness flags. Requiring it is side-effect-free
 // (its CLI body is require.main-guarded).
 const docsEntropy = require('./docs-entropy');
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
 
 // ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — the generator scans TWO trees.
 // CORE code + the core-owned nested docs live under the core PACKAGE (resolveCoreRoot); the
@@ -475,7 +476,7 @@ function main() {
   const mapPath = path.join(REPO_ROOT, 'docs', 'repo-map.md');
   const mapNext = renderRepoMap(model);
   const mapCur = fs.existsSync(mapPath) ? fs.readFileSync(mapPath, 'utf8') : '';
-  if (mapCur !== mapNext) writes.push({ full: mapPath, content: mapNext, rel: 'docs/repo-map.md', bucket: 'whole' });
+  if (!sameContent(mapCur, mapNext)) writes.push({ full: mapPath, content: mapNext, rel: 'docs/repo-map.md', bucket: 'whole' });
 
   // 2) nested CLAUDE.md generated blocks (tracked; the HARD-gated bucket)
   for (const dir of NESTED_DIRS) {
@@ -486,7 +487,7 @@ function main() {
     }
     const cur = fs.readFileSync(docPath, 'utf8');
     const next = injectBlock(cur, renderNestedBlock(model, dir));
-    if (cur !== next) writes.push({ full: docPath, content: next, rel: `${dir}/CLAUDE.md`, bucket: 'block' });
+    if (!sameContent(cur, next)) writes.push({ full: docPath, content: next, rel: `${dir}/CLAUDE.md`, bucket: 'block' });
   }
 
   if (checkAll || checkWhole || checkBlock) {

package/scripts/gds/gen-session-index.js

@@ -30,8 +30,17 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const { resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+
+// The session log, its index, and the CLAUDE.md §13 snippet are all HOST (instance) content —
+// docs/session-logs/ + docs/session-log-index.md + the instance root CLAUDE.md. Resolve them under
+// the host repo so a STANDALONE instance (core in node_modules, ADR 0108) indexes its OWN sessions,
+// not the vendored core's. On the monorepo/at-ship this still resolves to the checkout (cwd
+// fallback). Do NOT reintroduce a hardcoded `path.resolve(__dirname,'..','..')` — post-split it
+// points INTO node_modules/@bongos/core (the exact bug gen-repo-map/gen-file-map warn against; the
+// reason gen-session-index was writing the core's index on a standalone box — task 1002314).
+const REPO_ROOT = resolveInstanceRoot();
 const LOGS_DIR = path.join(REPO_ROOT, 'docs', 'session-logs');
 const INDEX_PATH = path.join(REPO_ROOT, 'docs', 'session-log-index.md');
 const CLAUDE_PATH = path.join(REPO_ROOT, 'CLAUDE.md');
@@ -100,7 +109,7 @@ function renderIndex(entries) {
   const L = [];
   L.push('# Session log — index');
   L.push('');
-  L.push('> **AUTO-GENERATED — do not hand-edit.** Regenerate with `node scripts/gds/gen-session-index.js` (auto-regenerated + committed at ship, like `gen-repo-map.js`). Generated from the files in [`session-logs/`](session-logs/) so a link can never dangle (retires the recurring §13 drift: idea 57, [#580](https://amazonprimea.com/builders#/task/580)). The session PROSE is canonical in those files (older entries compressed into [`session-log-archive.md`](session-log-archive.md)); the DB session corpus (`session_logs` + the BFG `session_records`) is the structured record. See [ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §8 · [ADR 0063](adr/0063-generated-repo-map-symbol-skeleton.md).');
+  L.push('> **AUTO-GENERATED — do not hand-edit.** Regenerate with `node scripts/gds/gen-session-index.js` (auto-regenerated + committed at ship, like `gen-repo-map.js`). Generated from the files in [`session-logs/`](session-logs/) so a link can never dangle (retires the recurring §13 drift: idea 57, [#580](https://example.com/builders#/task/580)). The session PROSE is canonical in those files (older entries compressed into [`session-log-archive.md`](session-log-archive.md)); the DB session corpus (`session_logs` + the BFG `session_records`) is the structured record. See [ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §8 · [ADR 0063](adr/0063-generated-repo-map-symbol-skeleton.md).');
   L.push('');
   L.push(`**${entries.length} sessions**, newest first.`);
   L.push('');
@@ -144,12 +153,12 @@ function computeWrites() {
   // stays a HARD CI gate. main() gates them separately (--check-block vs --check-whole).
   const idxNext = renderIndex(entries);
   const idxCur = fs.existsSync(INDEX_PATH) ? fs.readFileSync(INDEX_PATH, 'utf8') : '';
-  if (idxCur !== idxNext) writes.push({ full: INDEX_PATH, content: idxNext, rel: 'docs/session-log-index.md', bucket: 'whole' });
+  if (!sameContent(idxCur, idxNext)) writes.push({ full: INDEX_PATH, content: idxNext, rel: 'docs/session-log-index.md', bucket: 'whole' });
 
   if (fs.existsSync(CLAUDE_PATH)) {
     const cur = fs.readFileSync(CLAUDE_PATH, 'utf8');
     const next = injectSnippet(cur, renderSnippet(entries));
-    if (cur !== next) {
+    if (!sameContent(cur, next)) {
       if (next === cur && cur.indexOf(BEGIN) === -1) {
         console.error('gen-session-index: WARN CLAUDE.md has no snippet markers — skipping snippet injection.');
       } else {

package/scripts/gds/hooks/pre-push.js

@@ -28,7 +28,7 @@ const { execSync } = require('node:child_process');
 const path = require('node:path');
 
 const ppc = require(path.join(__dirname, '..', '..', '..', 'src', 'bongos', 'permission-path-check.js'));
-const { apiCall } = require(path.join(__dirname, '..', 'cli-lib.js'));
+const { apiCall, productName } = require(path.join(__dirname, '..', 'cli-lib.js'));
 
 const ZERO = /^0+$/;
 const MAIN_REF = 'refs/heads/main';
@@ -82,7 +82,7 @@ async function liveRank() {
 }
 
 function block(lines) {
-  console.error('\n\x1b[31m✖ push blocked by the Off the Boats permission gate (SEC #863)\x1b[0m');
+  console.error(`\n\x1b[31m✖ push blocked by the ${productName()} permission gate (SEC #863)\x1b[0m`);
   for (const l of lines) console.error('  ' + l);
   console.error('');
   process.exit(1);

package/scripts/gds/init.js

@@ -543,12 +543,51 @@ async function interview({ adopt = false } = {}) {
 // Write + seed
 // ---------------------------------------------------------------------------
 
+// PURE (exported for tests) — the root START-HERE guide (task 1002404, goal
+// 1000052). A freshly-CLONED instance must tell a human what to run FIRST: the
+// `bongos` CLI ships INSIDE the not-yet-installed @bongos/core package, so
+// `npm install` has to come before any `bongos` command (including `bongos dev`).
+// `bongos init` runs npm install during scaffolding, but a later `git clone` of
+// the committed instance repo skips that — so this file is the signpost the clone
+// carries. Owner-friendly and plain-language (the owner may not be an engineer).
+function buildReadme(branding = {}) {
+  const identity = branding.identity || {};
+  const name = identity.productName || 'This Cloud Bongos instance';
+  const origin = (branding.domains && branding.domains.publicOrigin) || '';
+  const loginLine = origin
+    ? `3. \`bongos login ${origin}\` — only if you're signed in to a *different* instance (\`bongos dev\` signs you in the first time).`
+    : `3. \`bongos login <your-instance-url>\` — only if you're signed in to a *different* instance (\`bongos dev\` signs you in the first time).`;
+  return [
+    `# ${name}`,
+    '',
+    'A **Cloud Bongos** instance — an AI-first build platform: AI agents claim tasks and write the code; a human owner sets scope and the gates.',
+    '',
+    '## Start here (first run)',
+    '',
+    'Just cloned this repo? Run these **in order**. The `bongos` CLI ships *inside* the `@bongos/core` dependency, so step 1 comes first — until it runs there is no `bongos` command:',
+    '',
+    '1. `npm install` — installs the toolchain (this is what creates the `bongos` command).',
+    '2. `bongos dev` — one command to run this instance locally: starts Postgres, builds the tables, launches the server, and signs you in.',
+    loginLine,
+    '4. `bongos start` — see what you can work on. (Inside Claude Code, the same thing is `/builder-start`.)',
+    '',
+    'Requires Node >= 22 and Postgres installed locally (macOS/Linux; on Windows use WSL). If anything looks off, `bongos doctor` checks your setup and prints the fix.',
+    '',
+    '## Where to look next',
+    '',
+    '- `CLAUDE.md` — how this project is built (the operating manual agents read first).',
+    '- `bongos --help` — the full CLI: claim, ship, status, recall, and more.',
+    '',
+  ].join('\n');
+}
+
 function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log }) {
   const configDir = path.join(dir, 'config');
   const brandingPath = path.join(configDir, 'branding.json');
   const modulesPath = path.join(configDir, 'modules.json');
   const hierarchyPath = path.join(configDir, 'hierarchy.json');
   const pkgPath = path.join(dir, 'package.json');
+  const readmePath = path.join(dir, 'README.md');
   const branding = buildBrandingConfig(spec);
   const modules = buildModulesConfig(spec);
   const hierarchy = buildHierarchyConfig(spec);
@@ -574,7 +613,8 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
     log(JSON.stringify(hierarchy, null, 2));
     log(`\n[dry-run] would write ${pkgPath} (pins ${CORE_PKG} → ${pinNote}):`);
     log(JSON.stringify(pkg, null, 2));
-    return { brandingPath, modulesPath, hierarchyPath, pkgPath, wrote: false };
+    log(`\n[dry-run] would write ${readmePath} (root START-HERE first-run guide) if absent`);
+    return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: false };
   }
   if (fs.existsSync(brandingPath) && !force) {
     throw new Error(`${brandingPath} already exists — refusing to overwrite. Use --force to replace, or run init in a fresh --dir.`);
@@ -588,7 +628,15 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
   log(`  ✓ wrote ${path.relative(dir, modulesPath)}`);
   log(`  ✓ wrote ${path.relative(dir, hierarchyPath)}`);
   log(`  ✓ wrote ${path.relative(dir, pkgPath)} (pins ${CORE_PKG} → ${pinNote})`);
-  return { brandingPath, modulesPath, hierarchyPath, pkgPath, wrote: true };
+  // README START-HERE (task 1002404): write-if-absent so a --force re-init or an
+  // owner's own README is never clobbered.
+  if (!fs.existsSync(readmePath)) {
+    fs.writeFileSync(readmePath, buildReadme(branding));
+    log(`  ✓ wrote ${path.relative(dir, readmePath)} (first-run START-HERE)`);
+  } else {
+    log(`  • ${path.relative(dir, readmePath)} already present — left untouched`);
+  }
+  return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: true };
 }
 
 // `--adopt` config layering (ADR 0121 §Decision 2 / task 2042). The additive
@@ -955,11 +1003,20 @@ async function main(argv) {
   // catches any lag on the consumer's first CI.
   if (dryRun) {
     console.log('\n[dry-run] would regenerate the API artifacts (OpenAPI spec + reference + typed client) from the pinned core');
+    console.log('[dry-run] would seed the whole-file navigation docs (session-log index) from the pinned core');
   } else {
     console.log('\nRegenerating the API artifacts from the pinned core (OpenAPI spec + reference + typed client):');
     const regen = upgrade.regenerateApiArtifacts({ instanceDir: dir, coreRoot: resolveCoreRoot() });
     if (regen.ok) console.log(`  ✓ regenerated (${regen.ran.join(', ')}) → docs/api/ + docs/api-reference.md + clients/bongos-client/`);
     else console.error(`  ! API-artifact regen skipped (${regen.reason}) — regenerate in ${dir} by hand; the instance-root fitness gate flags the lag otherwise.`);
+    // Seed the whole-file navigation docs (session-log index) so a fresh instance's docs/ isn't
+    // empty before its first deploy-regen (ADR 0110 / task 1002314). Gitignored on the instance —
+    // this is a local seed; the ongoing refresh is regen-instance-docs.js on deploy + `bongos
+    // upgrade`. Best-effort, mirrors the api-artifacts line: a hiccup warns, never fails init.
+    console.log('\nSeeding the navigation docs from the pinned core (session-log index):');
+    const nav = upgrade.regenerateNavDocs({ instanceDir: dir, coreRoot: resolveCoreRoot() });
+    if (nav.ok) console.log(`  ✓ seeded (${nav.ran.join(', ')}) → docs/`);
+    else console.error(`  ! nav-doc seed incomplete (failed: ${nav.failed.map((f) => f.gen).join(', ')}) — the deploy regen (regen-instance-docs.js) retries.`);
   }
 
   let seedResult = {};
@@ -979,7 +1036,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  buildBrandingConfig, buildModulesConfig, buildHierarchyConfig, kickoffTasks, normalizeSpec,
+  buildBrandingConfig, buildModulesConfig, buildHierarchyConfig, buildReadme, kickoffTasks, normalizeSpec,
   validateSpec, versionPayload, slugify, writeConfigs, seedViaApi, interview, main,
   provisioningSlug, provisioningRequest, productionTopologyKickoff,
   // --adopt (brownfield layering, ADR 0121 / task 2042)

package/scripts/gds/install-git-hooks.js

@@ -36,7 +36,7 @@ function registerMergeDriver(root) {
   // mangle %VARS on Windows cmd).
   try {
     execFileSync('git', ['config', `merge.${MERGE_DRIVER_NAME}.name`,
-      'Off the Boats generated-file regenerator (task 1243)'], { cwd: root, stdio: 'ignore' });
+      `${require('./cli-lib').productName()} generated-file regenerator (task 1243)`], { cwd: root, stdio: 'ignore' });
     execFileSync('git', ['config', `merge.${MERGE_DRIVER_NAME}.driver`,
       'node scripts/gds/git-merge-regen.js %O %A %B %P'], { cwd: root, stdio: 'ignore' });
     return { ok: true };

package/scripts/gds/key-card.js

@@ -37,18 +37,27 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const ic = require('../../src/instance-config');
 
+// NOTE the require path: this file lives in scripts/gds/, so branding is two
+// levels up. It read '../src/branding' (= scripts/src/branding, which does not
+// exist) until task 1002428 — so the require ALWAYS threw, safeBrand ALWAYS took
+// the catch, and every key card told the builder to visit the hardcoded founder
+// host regardless of which instance they were signed into.
+//
+// The settings URL now comes from the session-aware base (task 1002427), so it
+// names the instance the builder is actually on; the neutral productName default
+// is kept for the genuinely-unreadable-branding case.
 function safeBrand() {
+  const settingsUrl = `${ic.resolveApiBase()}/builders/settings`;
   try {
-    const b = require('../src/branding').branding();
+    const b = require('../../src/branding').branding();
     return {
       productName: (b.identity && b.identity.productName) || 'Cloud Bongos',
-      settingsUrl: (b.domains && b.domains.publicOrigin)
-        ? `${b.domains.publicOrigin}/builders/settings`
-        : 'https://amazonprimea.com/builders/settings',
+      settingsUrl,
     };
   } catch (_) {
-    return { productName: 'Cloud Bongos', settingsUrl: 'https://amazonprimea.com/builders/settings' };
+    return { productName: 'Cloud Bongos', settingsUrl };
   }
 }
 
@@ -179,7 +188,7 @@ async function resolveWidgetsEnabled() {
     const timer = setTimeout(() => ctrl.abort(), 3000);
     try {
       const res = await fetch(`${base}/api/gds/me`, {
-        headers: { Authorization: `Bearer ${session.token}`, 'User-Agent': 'amazonprimea-key-card/1.0' },
+        headers: { Authorization: `Bearer ${session.token}`, 'User-Agent': require('../../src/branding').userAgent() },
         signal: ctrl.signal,
       });
       if (!res.ok) return true;

package/scripts/gds/key-status.js

@@ -59,7 +59,7 @@ function refuseIfKeyPasted(argv) {
   console.log('✖ That looks like an API key — this tool never accepts one as an argument,');
   console.log('  and keys are never pasted into chat (the transcript is uploaded).');
   console.log('  Add it in Settings instead — it syncs to your box automatically:');
-  console.log('    https://amazonprimea.com/builders/settings#art-key');
+  console.log(`    ${require('./cli-lib').hallBase()}/settings#art-key`);
   return true;
 }
 

package/scripts/gds/linkify-refs.js

@@ -48,11 +48,34 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const RESOLVER_BASE = 'https://amazonprimea.com/builders#/task/';
-const RESOLVER_BASE_IDEA = 'https://amazonprimea.com/builders#/idea/';
-const RESOLVER_BASE_BLOCKER = 'https://amazonprimea.com/builders#/blocker/';
-// API_BASE comes from cli-lib (the single source). Safe for this token-free CI
-// gate: cli-lib does no eager session read or network at module scope.
+// The Builders' Hall deep-link resolver bases (task/idea/blocker), derived from the
+// instance's STABLE public hall — branding.domains.buildersOrigin, falling back to
+// publicOrigin. Deliberately NOT the env-overridable API_BASE: these bases get
+// WRITTEN INTO COMMITTED markdown, so a per-dev CLOUDBONGOS_API_BASE=localhost
+// override must never leak into a committed doc link (task 1002234; the committed-doc
+// twin of the task-1002233 printed-link fix, which purged the last hardcoded
+// `https://amazonprimea.com`). When branding is unreadable the base is the
+// root-relative '/builders#/…' — never a hardcoded founder host. Reading branding is
+// a sync file read (no network), safe at module scope for this token-free CI gate.
+function resolverHallRoot() {
+  try {
+    const d = (require('../../src/branding').branding().domains) || {};
+    const origin = (typeof d.buildersOrigin === 'string' && d.buildersOrigin.trim())
+      || (typeof d.publicOrigin === 'string' && d.publicOrigin.trim())
+      || '';
+    return `${String(origin).replace(/\/+$/, '')}/builders#`;
+  } catch (_) {
+    return '/builders#';
+  }
+}
+const RESOLVER_HALL_ROOT = resolverHallRoot();
+const RESOLVER_BASE = `${RESOLVER_HALL_ROOT}/task/`;
+const RESOLVER_BASE_IDEA = `${RESOLVER_HALL_ROOT}/idea/`;
+const RESOLVER_BASE_BLOCKER = `${RESOLVER_HALL_ROOT}/blocker/`;
+// API_BASE (env → session → branding default) comes from cli-lib (the single
+// source) — used ONLY for the RUNTIME /public/ref-ids fetch below, never for the
+// committed link bases above. Safe for this token-free CI gate: cli-lib does no
+// eager session read or network at module scope.
 const { API_BASE } = require('./cli-lib');
 
 // Every hand-authored markdown file that a reader sees rendered on github.com:
@@ -101,11 +124,14 @@ const GITHUB_NS_RE = /\b(pull requests?|pull|prs?)[`'")\s(:]*$/i;
 // "reports #2–#11" treat BOTH ends the same way.
 const LIST_GLUE_RE = /^[\s,–—-]*(?:and|&|\+|or|to|through)?[\s,–—-]*$/i;
 
-const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-// An existing markdown link of the exact TASK form this script writes:
-// [#N](task-resolver/N). Used only to undo PAST task-resolver mis-links of
+// An existing markdown link of the TASK-resolver form this script writes:
+// [#N](…/builders#/task/N). Used only to undo PAST task-resolver mis-links of
 // entity/idea/blocker refs; the idea/blocker resolver links are left alone.
-const RESOLVER_LINK_RE = new RegExp(`\\[#(\\d{1,5})\\]\\(${escapeRe(RESOLVER_BASE)}(\\d{1,5})\\)`, 'g');
+// HOST-AGNOSTIC (task 1002234 part b): matches any http(s) host OR a root-relative
+// '/builders#/…', so the mislink-cleanup path still recognizes a link a PRIOR run
+// committed under a DIFFERENT host — the legacy `amazonprimea.com` links, a
+// co-tenant's, or this instance's own — not only the current RESOLVER_BASE host.
+const RESOLVER_LINK_RE = /\[#(\d{1,5})\]\((?:https?:\/\/[^/)\s]+)?\/builders#\/task\/(\d{1,5})\)/g;
 
 // Classify a ref by its left context (+ list-glue carry). Returns one of
 // 'github' | 'idea' | 'blocker' | 'entity' | null (null = candidate task ref).

package/scripts/gds/login.js

@@ -23,6 +23,7 @@
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
 const { saveSession } = require('./cli-lib');
+const { branding } = require('../../src/branding');
 
 // --- pure helpers (unit-tested) ---------------------------------------------
 
@@ -149,6 +150,20 @@ async function runDeviceFlow(base, { log, idp = null }) {
   return { state: 'expired' };
 }
 
+// A helpful, instance-agnostic example origin for the sign-in prompt. login is
+// deliberately instance-agnostic (point it at ANY instance), so the example is
+// derived from THIS checkout's branding — a branded checkout shows its own
+// instance; the neutral core shows a neutral placeholder. It never hardcodes
+// another instance's real domain (hardcoding one steered a new builder to the
+// wrong backend — task 1002400, onboarding-audit area 3).
+function exampleInstanceOrigin() {
+  try {
+    const origin = branding().domains && branding().domains.publicOrigin;
+    if (origin && !/localhost|127\.0\.0\.1/.test(origin)) return origin;
+  } catch (_) { /* branding unavailable — fall through to the neutral placeholder */ }
+  return 'https://your-instance.example.com';
+}
+
 // --- main --------------------------------------------------------------------
 
 async function main() {
@@ -158,7 +173,7 @@ async function main() {
 
   let base;
   try {
-    base = normalizeInstanceBase(urlArg || (await prompt('Instance URL (e.g. https://amazonprimea.com): ')));
+    base = normalizeInstanceBase(urlArg || (await prompt(`Instance URL (e.g. ${exampleInstanceOrigin()}): `)));
   } catch {
     console.error('✖ usage: bongos login <instance-url>');
     process.exit(2);

package/scripts/gds/paste-token.js

@@ -28,7 +28,13 @@ const ic = require('../../src/instance-config');
 // WRITE the session to the configured instance dir (OTB → ~/.config/otb,
 // unchanged; a fresh instance → its neutral dir). R61 / task 1200.
 const SESSION_PATH = ic.configPath('gds-session.json');
-const API_BASE = ic.resolveEnv('API_BASE') || 'https://amazonprimea.com';
+// env → the EXISTING session's api_base → this instance's branding default.
+// On a RE-auth a session file already exists, and its api_base is the best signal
+// of which instance the builder is on — this file used to hardcode the founder
+// host here (a straggler the task 1002201 sweep missed), so a token minted by
+// another instance was verified against amazonprimea.com and rejected 401 with a
+// perfectly valid token (task 1002427).
+const API_BASE = ic.resolveApiBase();
 
 function usage(extra) {
   if (extra) console.error(extra);