@bongos/core 1.17.0 → 1.17.2

package/scripts/gds/claude-materialize.js

@@ -5,7 +5,7 @@
 //
 // WHY. Claude Code discovers .claude/settings.json + hooks/ + skills/ from the PROJECT ROOT, never
 // from a dependency. Once the Cloud Bongos core installs as a pinned npm package (ADR 0108), the
-// ~35 skills sit in node_modules/@cloudbongos/core/.claude/skills/ where Claude Code will not look —
+// ~35 skills sit in node_modules/@bongos/core/.claude/skills/ where Claude Code will not look —
 // so `bongos init`/`upgrade` must COPY .claude/ into the instance repo. And a copied skill can't run
 // `node scripts/gds/<x>.js`: scripts/ lives in the package, not at the instance root. So every
 // invocation is rewritten to the `bongos` bin, which resolves the heavy CLI inside the package —
@@ -15,8 +15,9 @@
 // copy+transform. hooks/ + settings.json are TOPOLOGY (PROTECTED_TOPOLOGY_EXCLUDE) → NOT in the
 // package; this module copies+transforms them when they ARE present at the core root (today's single
 // checkout, and the core repo itself), and no-ops with a note when they aren't (an installed package).
-// Rewriting hook *.js internals + shipping a topology STARTER for a package-only install is a
-// follow-up (idea captured by task 1883) — this lands the skills materialization + the transform.
+// Hooks self-resolve their core require()s at RUNTIME via the copied _core-resolve.js sibling
+// (task 2139, the former W3 follow-up), so no require-path rewriting happens here; shipping a
+// topology STARTER for a package-only install (hooks absent at the core root) stays a follow-up (task 1883).
 //
 // SELF-COPY GUARD. When the instance dir IS the core root (running init inside the core checkout /
 // OTB today), there is nothing to materialize — a self-copy would be a no-op at best and corrupting
@@ -25,6 +26,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
+const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
+const { renderInstanceClaudeMd } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
 
 // script basename (e.g. "ship.js") → dedicated bongos verb, for verbs that map to a bare script with
 // NO prefixArgs. Verbs whose script is driven by prefixArgs (box → api.js) are EXCLUDED so a generic
@@ -59,6 +62,88 @@ function bongosify(text, verbs = VERBS) {
     .replace(OTHER_SCRIPT_RE, (_whole, rel) => `bongos exec scripts/${rel}`);
 }
 
+// ---- instance rebrand (task 2103) -----------------------------------------
+// The scaffolded .claude/ used to carry the SOURCE instance's identity verbatim:
+// hooks hardcoded the founder origin (e.g. a `https://amazonprimea.com` fallback)
+// and config dir (`~/.config/otb`), so a fresh clone's hooks phoned home to the
+// WRONG instance — the 2026-07-08 demo-session failure. materialize now rewrites
+// those founder literals to the TARGET instance's own values, derived from the two
+// branding objects, so no source host survives. Focused + FULL-HOST (a subdomain
+// like demo.cloudbongos.com is preserved), fail-open (a missing field drops that
+// one rule), a no-op when source == target, and it touches ONLY the copied output
+// (never the running source hooks). It does NOT rewrite hooks' internal
+// require('scripts/gds/…') paths — those self-resolve at runtime via the copied
+// _core-resolve.js sibling (task 2139); this rule lands the origin/config-dir neutralization.
+
+function reEsc(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function hostOf(origin) { try { return new URL(String(origin)).host || null; } catch { return null; } }
+
+// Effective config dir / env prefix for a branding — the SAME neutral fallbacks
+// instance-config uses, so nothing here is ever a founder literal (R76-safe).
+function effConfigDir(b) { return (b && b.configDir) || ic.FALLBACK_DIR; }
+function effEnvPrefix(b) { return (b && b.envPrefix) || ic.FALLBACK_ENV_PREFIX; }
+
+// Ordered source→target rebrand rules from two branding objects. PURE + exported.
+function buildRebrandRules(from = {}, to = {}) {
+  const rules = [];
+  const add = (a, b) => { if (a && b && a !== b) rules.push({ pattern: new RegExp(reEsc(a), 'g'), replace: b }); };
+  // Every configured origin HOST (public/builders/status/oauth) → the target's SAME-key
+  // host, or its publicOrigin host when that key is unset (so a source subdomain like
+  // builders.<founder> maps to the target's canonical origin, not builders.<target>).
+  // Full-host keeps real target subdomains; a bare founder host anywhere is caught too.
+  // Dedup by source host (first mapping wins) so one founder host can't spawn conflicting rules.
+  const fromD = from.domains || {}, toD = to.domains || {};
+  const toPublicHost = hostOf(toD.publicOrigin);
+  const hostMap = new Map();
+  for (const key of Object.keys(fromD)) {
+    const fh = hostOf(fromD[key]);
+    if (!fh || hostMap.has(fh)) continue;
+    const th = hostOf(toD[key]) || toPublicHost;
+    if (th) hostMap.set(fh, th);
+  }
+  for (const [fh, th] of hostMap) add(fh, th);
+  // Config dir in the shapes hooks reference it (~/.config/<dir>, /etc/<dir>, the [<dir>] log tag).
+  const fc = effConfigDir(from), tc = effConfigDir(to);
+  add(`.config/${fc}`, `.config/${tc}`);
+  add(`/etc/${fc}`, `/etc/${tc}`);
+  add(`[${fc}]`, `[${tc}]`);
+  // The instance env-var prefix (e.g. OTB_ → CLOUDBONGOS_), bounded by its underscore.
+  add(`${effEnvPrefix(from)}_`, `${effEnvPrefix(to)}_`);
+  // Longest literal first so a full host is replaced before any bare token inside it.
+  rules.sort((x, y) => y.pattern.source.length - x.pattern.source.length);
+  return rules;
+}
+
+function rebrandText(text, rules) {
+  if (typeof text !== 'string' || !text || !rules || !rules.length) return text;
+  let out = text;
+  for (const r of rules) out = out.replace(r.pattern, r.replace);
+  return out;
+}
+
+function readJsonSafe(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } }
+
+// Skills owned by a module that is DISABLED in the TARGET instance (task 2103b).
+// Each module.json declares `contributes.skills`; a module is enabled when the
+// target's config/modules.json says so, else by its own `default`. A skill owned
+// by NO module is core and is never skipped. PURE-ish (reads the fs) + exported.
+function disabledModuleSkills({ coreRoot, instanceDir }) {
+  const skip = new Set();
+  const modulesDir = path.join(coreRoot, 'modules');
+  if (!fs.existsSync(modulesDir)) return skip;
+  const targetCfg = readJsonSafe(path.join(instanceDir, 'config', 'modules.json')) || {};
+  const enabledMap = (targetCfg.modules && typeof targetCfg.modules === 'object') ? targetCfg.modules : {};
+  for (const dir of fs.readdirSync(modulesDir)) {
+    const mj = readJsonSafe(path.join(modulesDir, dir, 'module.json'));
+    const skills = mj && mj.contributes && mj.contributes.skills;
+    if (!Array.isArray(skills)) continue;
+    const explicit = enabledMap[mj.key || dir];
+    const enabled = explicit === undefined ? mj.default === true : explicit === true;
+    if (!enabled) for (const s of skills) skip.add(s);
+  }
+  return skip;
+}
+
 // ---- I/O: copy a tree, transforming text files through bongosify ----------
 
 const TEXT_EXT = new Set(['.md', '.txt', '.sh']); // command-bearing text we rewrite (skills are SKILL.md)
@@ -67,10 +152,16 @@ const TEXT_EXT = new Set(['.md', '.txt', '.sh']); // command-bearing text we rew
 // `overwrite: false` is the `bongos init --adopt` layering path (ADR 0121): a file
 // that already exists at the destination is NEVER clobbered — it is skipped and
 // recorded in the returned `skipped[]` so the caller can report it.
-function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true } = {}) {
+// `transform` (text→text) is applied to any file whose extension is in `textExt`
+// (default: bongosify over .md/.txt/.sh — the historical skills behavior). `skip(rel)`
+// excludes a whole subtree BEFORE it is walked (task 2103b — drop a disabled module's
+// skill dir); excluded top-level entries are returned in `excluded[]`.
+function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true, transform = bongosify, textExt = TEXT_EXT, skip } = {}) {
   let files = 0;
   const skipped = [];
+  const excluded = [];
   const walk = (rel) => {
+    if (skip && skip(rel)) { excluded.push(rel); return; }
     const absSrc = path.join(srcDir, rel);
     const st = fs.statSync(absSrc);
     if (st.isDirectory()) {
@@ -86,16 +177,16 @@ function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true
     files += 1;
     if (dryRun) { if (onFile) onFile(rel); return; }
     fs.mkdirSync(path.dirname(absDest), { recursive: true });
-    if (TEXT_EXT.has(path.extname(rel))) {
-      fs.writeFileSync(absDest, bongosify(fs.readFileSync(absSrc, 'utf8')));
+    if (textExt.has(path.extname(rel))) {
+      fs.writeFileSync(absDest, transform(fs.readFileSync(absSrc, 'utf8')));
     } else {
-      fs.copyFileSync(absSrc, absDest); // .js / binary / json (settings handled separately) — verbatim
+      fs.copyFileSync(absSrc, absDest); // binary / other — verbatim
     }
     if (onFile) onFile(rel);
   };
-  if (!fs.existsSync(srcDir)) return { files: 0, skipped, present: false };
+  if (!fs.existsSync(srcDir)) return { files: 0, skipped, excluded, present: false };
   for (const name of fs.readdirSync(srcDir)) walk(name);
-  return { files, skipped, present: true };
+  return { files, skipped, excluded, present: true };
 }
 
 // Transform settings.json: parse, rewrite every hook command through bongosify, re-serialize. Keeps
@@ -121,8 +212,10 @@ function transformSettings(srcPath) {
 // `overwrite` defaults true (greenfield init / upgrade — unchanged). `overwrite: false`
 // is the `bongos init --adopt` layering path (ADR 0121): every pre-existing .claude/
 // file is LEFT untouched and recorded in `summary.skippedFiles` (never clobbered).
+const HOOK_TEXT_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.sh', '.md', '.txt']); // hooks are .js — rebrand them too
+
 function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
-  const summary = { skipped: false, skills: 0, settings: false, hooks: 0, skippedFiles: [], notes: [] };
+  const summary = { skipped: false, skills: 0, settings: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], rebrandRules: 0, claudeMd: false, notes: [] };
   if (path.resolve(instanceDir) === path.resolve(coreRoot)) {
     summary.skipped = true;
     summary.notes.push('instance dir is the core root — nothing to materialize (byte-identical no-op).');
@@ -133,13 +226,33 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   const destClaude = path.join(instanceDir, '.claude');
   const left = (n) => (overwrite || n === 0 ? '' : ` (${n} left untouched)`);
 
-  // 1. skills — ship in the core package; copy + rewrite invocations.
+  // Rebrand: rewrite the SOURCE instance's identity (origin host, config dir, env
+  // prefix) to the TARGET's, so a copied hook never phones home to the founder's
+  // instance (task 2103a). Derived from both config/branding.json files; empty — and
+  // thus a no-op — when they match or either is unreadable.
+  const fromBranding = readJsonSafe(path.join(coreRoot, 'config', 'branding.json')) || {};
+  const toBranding = readJsonSafe(path.join(instanceDir, 'config', 'branding.json')) || {};
+  const rebrandRules = buildRebrandRules(fromBranding, toBranding);
+  const rebrand = (t) => rebrandText(t, rebrandRules);
+  summary.rebrandRules = rebrandRules.length;
+  if (rebrandRules.length) log(`  • rebranding ${rebrandRules.length} founder literal(s) in the copied .claude/ → this instance's identity.`);
+
+  // Drop skills owned by a module this instance hasn't enabled (task 2103b).
+  const skipSkills = disabledModuleSkills({ coreRoot, instanceDir });
+  const skillSkip = (rel) => skipSkills.has(String(rel).split(/[\\/]/)[0]);
+
+  // 1. skills — ship in the core package; copy, rewrite invocations→bongos, rebrand
+  //    identity, and exclude any skill owned by a disabled module.
   const skillsSrc = path.join(srcClaude, 'skills');
-  const skillsRes = copyTreeTransformed(skillsSrc, path.join(destClaude, 'skills'), { dryRun, overwrite });
+  const skillsRes = copyTreeTransformed(skillsSrc, path.join(destClaude, 'skills'), {
+    dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), skip: skillSkip,
+  });
   summary.skills = skillsRes.files;
+  summary.excludedSkills = skillsRes.excluded || [];
   for (const rel of skillsRes.skipped || []) summary.skippedFiles.push(`skills/${rel}`);
   if (!skillsRes.present) summary.notes.push('.claude/skills not found at the core root — none materialized.');
-  log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${skillsRes.files} skill file(s) → .claude/skills/ (invocations rewritten to bongos)${left((skillsRes.skipped || []).length)}`);
+  if (summary.excludedSkills.length) log(`  • excluded ${summary.excludedSkills.length} skill(s) owned by disabled module(s): ${summary.excludedSkills.join(', ')}`);
+  log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${skillsRes.files} skill file(s) → .claude/skills/ (invocations→bongos, identity rebranded)${left((skillsRes.skipped || []).length)}`);
 
   // 2. settings.json — topology; present in the checkout/core repo, absent in a package-only install.
   const settingsSrc = path.join(srcClaude, 'settings.json');
@@ -151,26 +264,67 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
     } else {
       if (!dryRun) {
         fs.mkdirSync(destClaude, { recursive: true });
-        fs.writeFileSync(settingsDest, transformSettings(settingsSrc));
+        fs.writeFileSync(settingsDest, rebrand(transformSettings(settingsSrc)));
       }
       summary.settings = true;
-      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (hook commands rewritten to bongos)`);
+      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (hook commands→bongos, identity rebranded)`);
     }
   } else {
     summary.notes.push('.claude/settings.json not present at the core root (topology, excluded from the package) — provide it from a starter.');
   }
 
-  // 3. hooks — topology; copied verbatim when present (JS-internal script requires are a follow-up).
-  const hooksRes = copyTreeTransformed(path.join(srcClaude, 'hooks'), path.join(destClaude, 'hooks'), { dryRun, overwrite });
+  // 3. hooks — topology; copied WITH an identity rebrand (their .js internals carried
+  //    the founder origin/config-dir). Their core require()s self-resolve at runtime via
+  //    the copied _core-resolve.js sibling (task 2139) — no path rewriting needed here.
+  const hooksRes = copyTreeTransformed(path.join(srcClaude, 'hooks'), path.join(destClaude, 'hooks'), {
+    dryRun, overwrite, transform: rebrand, textExt: HOOK_TEXT_EXT,
+  });
   summary.hooks = hooksRes.files;
   for (const rel of hooksRes.skipped || []) summary.skippedFiles.push(`hooks/${rel}`);
   if (!hooksRes.present) {
     summary.notes.push('.claude/hooks not present at the core root (topology, excluded from the package) — provide them from a starter.');
   } else {
-    log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${hooksRes.files} hook file(s) → .claude/hooks/${left((hooksRes.skipped || []).length)}`);
-    summary.notes.push('hooks copied verbatim; their internal `require(scripts/gds/…)` paths are NOT yet rewritten to resolve inside the package (W3 follow-up).');
+    log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${hooksRes.files} hook file(s) → .claude/hooks/ (founder identity rebranded)${left((hooksRes.skipped || []).length)}`);
+    summary.notes.push('hooks: founder origin/config-dir rebranded to this instance; their internal `require(scripts/gds/…)` paths self-resolve inside the package at runtime via the copied _core-resolve.js sibling (task 2139).');
+  }
+
+  // 3b. scheduled-tasks — the cron routines (System 4 dispatcher, ADR 0078; task 2138). TOPOLOGY
+  //     like hooks (NOT in the package — PROTECTED_TOPOLOGY_EXCLUDE), so materialized by copy when
+  //     present at the core root and a no-op-with-note in a package-only install. Bodies (.md) are
+  //     bongosified so a judgment routine's `node scripts/gds/x.js` model-instructions become
+  //     `bongos exec …`; the deterministic routines' `.claude/scheduled-tasks/<x>.js` step commands
+  //     are NOT matched by bongosify and stay as-is. Companion .js are rebranded but keep their
+  //     paths: they resolve core require()s at runtime via the copied _core-resolve.js sibling
+  //     (task 2139), and run-routine.js finds the routines under resolveInstanceRoot() post-split.
+  const routinesRes = copyTreeTransformed(path.join(srcClaude, 'scheduled-tasks'), path.join(destClaude, 'scheduled-tasks'), {
+    dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), textExt: HOOK_TEXT_EXT,
+  });
+  summary.scheduledTasks = routinesRes.files;
+  for (const rel of routinesRes.skipped || []) summary.skippedFiles.push(`scheduled-tasks/${rel}`);
+  if (!routinesRes.present) {
+    summary.notes.push('.claude/scheduled-tasks not present at the core root (topology, excluded from the package) — provide them from a starter.');
+  } else {
+    log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${routinesRes.files} scheduled-task file(s) → .claude/scheduled-tasks/ (bodies→bongos, founder identity rebranded)${left((routinesRes.skipped || []).length)}`);
+    summary.notes.push('scheduled-tasks: cron routines materialized; run-routine.js resolves them under resolveInstanceRoot() and their companion .js resolve core via the copied _core-resolve.js sibling (task 2138).');
+  }
+
+  // 4. CLAUDE.md — the project-root framing an agent reads every session (task 2104).
+  //    Written from the neutral starter template, brand-substituted from THIS instance's
+  //    branding. Written only when ABSENT — never clobber a CLAUDE.md the instance has
+  //    grown (safe for init, adopt, and upgrade alike; the self-copy guard above already
+  //    keeps this from ever touching the core/OTB checkout's own CLAUDE.md).
+  const claudeMdPath = path.join(instanceDir, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
+  } else {
+    if (!dryRun) {
+      fs.mkdirSync(instanceDir, { recursive: true });
+      fs.writeFileSync(claudeMdPath, renderInstanceClaudeMd(toBranding));
+    }
+    summary.claudeMd = true;
+    log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} CLAUDE.md (starter, brand-substituted for this instance)`);
   }
   return summary;
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, GDS_INVOCATION_RE };
+module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills };

package/scripts/gds/claude-md-template.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/claude-md-template.js — the starter CLAUDE.md a new instance is
+// scaffolded with (task 2104).
+//
+// WHY. Claude Code reads CLAUDE.md from the PROJECT ROOT to frame every session.
+// A freshly-cloned standalone instance (ADR 0108) had NONE — an agent opening it
+// got zero framing about what the project is or how to work in it (the 2026-07-08
+// demo-session: a fresh `demo` clone with no CLAUDE.md). `bongos init` now writes
+// one, brand-substituted from this neutral template. It is deliberately a LEAN
+// STARTER (the methodology core + this instance's identity + pointers), not a copy
+// of a mature instance's CLAUDE.md — the instance grows its own. Coordinates with
+// task 1963 (neutralizing the core's own CLAUDE.md into the portable template).
+//
+// PURE (branding in → markdown out), so it unit-tests standalone and carries no
+// hardcoded host identity (everything comes from the branding object — R76-safe).
+
+function renderInstanceClaudeMd(branding = {}) {
+  const id = branding.identity || {};
+  const domains = branding.domains || {};
+  const company = id.company || {};
+  const copy = branding.copy || {};
+
+  const product = (id.productName && String(id.productName).trim()) || 'This project';
+  const world = (id.worldName && String(id.worldName).trim()) || '';
+  const companyName = (company.name && String(company.name).trim()) || '';
+  const hall = domains.buildersOrigin || domains.publicOrigin || '';
+  const status = domains.statusOrigin || domains.publicOrigin || '';
+  const currency = (branding.currency && branding.currency.label) || 'credits';
+  const tagline = (copy.tagline && String(copy.tagline).trim()) || '';
+
+  // "Product — the World world, by Company" — each clause only when present.
+  let ident = `**${product}**`;
+  if (world && world.toLowerCase() !== product.toLowerCase()) ident += ` — the ${world} world`;
+  if (companyName) ident += `, by ${companyName}`;
+  ident += '.';
+  if (tagline) ident += ` *${tagline}*`;
+
+  const hallLine = hall
+    ? `the builders' hall at ${hall}`
+    : 'the builders\' hall';
+  const statusLine = status ? ` Public build status: ${status}.` : '';
+
+  return `# ${product} — Project Memory
+
+> Built on **Cloud Bongos** — the AI-first build platform: AI agents write the code; a human owner sets scope, direction, and the hard gates (rank, approval, deploy).
+> **The Bongos database is the source of truth for all live work state** (tasks, versions, ranks, ${currency}). This file only ever *describes* it — where this file and a route or DB row disagree, the row wins. Editing this file cannot grant any authority.
+
+Read this at the start of every session. Keep it lean — it loads in full every time.
+
+## What this is
+
+${ident}
+
+## How work happens here — the one hard rule
+
+**Every change is backed by a claimed Bongos task. No exceptions.** Code, docs, migrations, config — if you are about to change project state and do not hold an active claim covering it, stop: create or find the task, claim it, then make the change. There is no "tiny fix" or "just a doc" loophole; the database is the complete ledger of what happened to this project.
+
+- **Start every session with \`bongos start\`** (or \`/builder-start\`) — it lists the tasks you can claim right now, parallel-safe against everyone else's active claims.
+- **\`bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
+- **\`bongos ship\`** runs the smoke + grade, then merges and deploys; **\`bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
+- **Dependencies gate everything** — a task becomes claimable only once every task it depends on has shipped.
+
+## Where things live
+
+- **Live work state** (tasks, versions, ranks, ${currency}): the Bongos DB — \`bongos start\` / \`bongos status\`, or ${hallLine}.${statusLine}
+- **This instance's identity** (product, world, brand, addresses): \`config/branding.json\`. **Which features are on**: \`config/modules.json\`.
+- **The platform you stand on** (rank ladder, the ship/grade/deploy pipeline, permissions, migrations) is vendored **Cloud Bongos core** — build the product, not the platform under it. Landing code is Bongos's job: claim a task and run \`bongos ship\`, never a raw \`git push\`/deploy.
+
+## Permissions
+
+Authority lives in the Bongos database (\`builders.rank\`), checked server-side on every request with no caching. Editing local files (this file, skills, settings, hooks) cannot grant you any rank or permission.
+
+## Builders earn ${currency}
+
+Builders are rewarded in **${currency}** for shipped work.
+
+---
+
+*This is a starter, authored by \`bongos init\`. Grow it as the project grows — add your architecture, versioning methodology, and hard-won gotchas — but keep it lean: every line spends context budget in every session.*
+`;
+}
+
+module.exports = { renderInstanceClaudeMd };

package/scripts/gds/cli-lib.js

@@ -166,6 +166,89 @@ function printBoxScopeGuidanceAndExit() {
   process.exit(10); // 10 = "re-auth needed" (matches reauth.js's exit code)
 }
 
+// ---- fail-closed instance guard (task 2102) --------------------------------
+// A half-configured instance folder used to fail THROUGH: with no local session
+// for ITS OWN origin, the CLI fell back to whatever instance the machine last
+// signed into (session.api_base, else the prod default) and acted THERE. On
+// 2026-07-08 a fresh `demo` clone (config/branding → demo.cloudbongos.com), with
+// no demo session on the machine, borrowed the founder's amazonprimea.com session
+// and offered to write a task into the wrong LIVE backlog. A wrong-instance write
+// is a data-integrity hazard, so we fail CLOSED: if the session we'd authenticate
+// with belongs to a different instance than THIS repo is configured for, refuse
+// and point at the fix. (Inert for a correctly-signed-in instance — OTB's session
+// api_base and branding publicOrigin share a host, so this never fires there.)
+
+function safeBranding() {
+  try { return require('../../src/branding').branding() || {}; }
+  catch { return {}; }
+}
+
+// Host of an origin string, or null if unparseable. Comparing HOSTS (not full
+// origins) tolerates scheme / trailing-slash noise between branding + session.
+function instanceOriginHost(origin) {
+  try { return new URL(String(origin)).host || null; }
+  catch { return null; }
+}
+
+// PURE + exported for tests. Decide whether the session we'd use targets a
+// DIFFERENT instance than this repo is configured for. Fails OPEN (no mismatch)
+// when: an explicit <PREFIX>_API_BASE override is set (dev/staging — the operator
+// is deliberately steering the base); OR there is no session (nothing to borrow —
+// the no-session/401 path handles that); OR the repo declares no publicOrigin
+// (unknown identity — you can't assert a mismatch you can't define). Otherwise the
+// mismatch is expectedHost !== sessionHost.
+function detectInstanceMismatch({ session, brand = safeBranding(), env = process.env } = {}) {
+  if (ic.resolveEnv('API_BASE', { env })) return { mismatch: false };
+  if (!session || !session.api_base) return { mismatch: false };
+  const expected = brand && brand.domains && brand.domains.publicOrigin;
+  if (!expected) return { mismatch: false };
+  const expectedHost = instanceOriginHost(expected);
+  const actualHost = instanceOriginHost(session.api_base);
+  if (!expectedHost || !actualHost) return { mismatch: false };
+  return { mismatch: expectedHost !== actualHost, expected, actual: session.api_base };
+}
+
+let _instanceMismatchExitInFlight = false;
+
+function printInstanceMismatchAndExit({ expected, actual }) {
+  const pfx = ic.envPrefix();
+  console.error('');
+  console.error('✖ Wrong instance — refusing to act.');
+  console.error('  This project is configured for one Cloud Bongos instance, but your signed-in');
+  console.error('  session belongs to a different one. Acting would write to the wrong place, so');
+  console.error('  I stop here (a wrong-instance write is worse than doing nothing).');
+  console.error('');
+  console.error(`    This project (config/branding.json):  ${expected}`);
+  console.error(`    Your session is signed in to:         ${actual}`);
+  console.error('');
+  console.error('  Sign in to THIS instance, then re-run your command:');
+  console.error(`    bongos login ${expected}`);
+  console.error(`    (or, from a checkout without the bongos bin:  node scripts/gds/login.js ${expected})`);
+  console.error('');
+  console.error('  Intentionally targeting another instance? Set the base explicitly, e.g.');
+  console.error(`    ${pfx}_API_BASE=${actual} <your command>`);
+  console.error('');
+  process.exit(3); // 3 = instance mismatch (distinct from 2 = unauth, 10 = box-scope)
+}
+
+// Fail-closed instance guard for RAW-fetch READ commands (task 2124 / demo-audit C2).
+// apiCall + cliClient guard themselves, but a command that reaches the API through its
+// OWN fetch bypasses that — the 2026-07-08 demo hit exactly this: `bongos status` used a
+// raw fetch(API_BASE/…) and happily printed the MAIN instance's progress while sitting in
+// the demo repo, giving false confidence, while the write path correctly refused. Such a
+// command must call this first. Inert when there is no session, when API_BASE is overridden,
+// or when the session's instance matches this repo's branding — it only fires on a genuine
+// wrong-instance session. Reuses the same detector + message as the write-side guard.
+async function assertInstanceMatch({ allowInstanceMismatch = false } = {}) {
+  if (allowInstanceMismatch || _instanceMismatchExitInFlight) return;
+  const session = await loadSession();
+  const mm = detectInstanceMismatch({ session });
+  if (mm.mismatch) {
+    _instanceMismatchExitInFlight = true;
+    printInstanceMismatchAndExit(mm);
+  }
+}
+
 /**
  * Make an authenticated request to the GDS API.
  *
@@ -175,8 +258,20 @@ function printBoxScopeGuidanceAndExit() {
  * decide whether to re-auth automatically).
  */
 async function apiCall(method, urlPath, body = null, opts = {}) {
-  const { allowUnauthenticated = false, allowBoxScope = false } = opts;
+  const { allowUnauthenticated = false, allowBoxScope = false, allowInstanceMismatch = false } = opts;
   const session = await loadSession();
+  // Fail CLOSED (task 2102) if the session we'd authenticate with belongs to a
+  // different instance than this repo is configured for — never silently borrow
+  // another instance's credentials. Opt out with { allowInstanceMismatch: true }
+  // for a deliberate cross-instance caller (login.js talks to other instances via
+  // its own fetch, so it never reaches here).
+  if (!allowInstanceMismatch && !_instanceMismatchExitInFlight) {
+    const mm = detectInstanceMismatch({ session });
+    if (mm.mismatch) {
+      _instanceMismatchExitInFlight = true;
+      printInstanceMismatchAndExit(mm);
+    }
+  }
   // Instance-agnostic base (V4.R83 / task 1250): `bongos login <instance>` writes
   // that instance's origin to session.api_base, so every later command targets it.
   // Precedence mirrors readSessionToken: an explicit <PREFIX>_API_BASE env wins
@@ -240,8 +335,20 @@ async function apiCall(method, urlPath, body = null, opts = {}) {
 let _clientModPromise = null;
 const _clientCache = new Map();
 async function cliClient(opts = {}) {
-  const { allowUnauthenticated = false, allowBoxScope = false } = opts;
+  const { allowUnauthenticated = false, allowBoxScope = false, allowInstanceMismatch = false } = opts;
   const session = await loadSession();
+  // Fail CLOSED (task 2102) — the same guard as apiCall, on the OTHER HTTP entry
+  // point. cliClient() is the typed client (api.js + newer scripts route through
+  // it), and it resolves the base identically, so it can silently target the wrong
+  // instance too. Guard both, or the hole just moves. Opt out with
+  // { allowInstanceMismatch: true } for a deliberate cross-instance caller.
+  if (!allowInstanceMismatch && !_instanceMismatchExitInFlight) {
+    const mm = detectInstanceMismatch({ session });
+    if (mm.mismatch) {
+      _instanceMismatchExitInFlight = true;
+      printInstanceMismatchAndExit(mm);
+    }
+  }
   const base = ic.resolveEnv('API_BASE') || (session && session.api_base) || 'https://amazonprimea.com';
   const token = (session && session.token) || null;
   const key = `${base}|${token || ''}|${allowUnauthenticated}|${allowBoxScope}`;
@@ -506,6 +613,9 @@ module.exports = {
   printUnauthGuidanceAndExit,
   isBoxScope,
   printBoxScopeGuidanceAndExit,
+  detectInstanceMismatch,
+  assertInstanceMatch,
+  instanceOriginHost,
   fmtMinutes,
   fmtUsd,
   fmtTouches,