@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/claude-materialize.js

@@ -0,0 +1,1200 @@
+#!/usr/bin/env node
+'use strict';
+// claude-materialize.js — materialize the .claude/ methodology surface into an instance
+// (ADR 0108 §3, configurable-root W3 / task 1883).
+//
+// 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/@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/bongos/<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 —
+// a dedicated verb where one exists (`bongos ship`), else the generic `bongos exec scripts/bongos/<x>.js`.
+//
+// BOUNDARY (publish-manifest). skills/ ships IN the core package (isPublishable) → materialized by
+// 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).
+// 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. The topology
+// STARTER for a package-only install is now HALF built: settings.json is written from
+// renderStarterSettings() below — permissions only, no hooks — because an instance that received
+// the skills but no permissions met the classifier on every blessed command (task 1003962). A hooks
+// starter remains a follow-up (task 1883), and is a different question: hooks ARE gate machinery,
+// where a list of allowed command names is not.
+//
+// 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
+// at worst. This module detects that and skips, so it is byte-identical for the live instance.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const crypto = require('node:crypto');
+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 { isCorePackageName, CORE_PACKAGE_NAMES } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
+const { renderInstanceClaudeMd, refreshStarterCliLines } = 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
+// `node scripts/bongos/dev.js …` never mis-maps to `bongos serve`; those fall to `bongos exec`. `exec`
+// itself has no script and is skipped.
+function scriptToVerb(verbs = VERBS) {
+  const m = {};
+  for (const [verb, def] of Object.entries(verbs)) {
+    if (!def || def.prefixArgs || !def.script) continue;
+    if (!(def.script in m)) m[def.script] = verb;
+  }
+  return m;
+}
+
+// Match `node [<quote>][$CLAUDE_PROJECT_DIR/|./]scripts/bongos/<name>.js[<quote>]` — the invocation form
+// skills + settings.json hooks use. The optional $CLAUDE_PROJECT_DIR/ or ./ prefix and surrounding
+// quote are consumed so the whole thing collapses to the bongos form. `.claude/hooks/<x>.js` refs are
+// deliberately NOT matched (this targets scripts/bongos/) — those stay instance-local after materialize.
+// The launcher is bare `node`, OR the hook resolver `sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"`
+// that every settings.json hook command goes through since task 1003548 (it finds node when the hook
+// shell's PATH lacks it). Both collapse to the same bongos form; a resolver call whose target is a
+// .claude/hooks/*.js stays untouched exactly like the bare-node form did.
+const LAUNCHER = String.raw`(?:node|sh\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?\.claude\/hooks\/run-node\.sh"?)`;
+const GDS_INVOCATION_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/(?:gds|bongos)\/([a-zA-Z0-9_-]+)\.js"?`, 'g');
+// A non-gds core script under scripts/ (rare in skills, but keep the transform total).
+const OTHER_SCRIPT_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!(?:gds|bongos)\/)[a-zA-Z0-9_./-]+\.js)"?`, 'g');
+
+// How a project runs the CLI (task 1004621). The `bongos` bin ships inside the @bongos/core
+// dependency (node_modules/.bin/bongos), which is NOT on PATH, so a bare `bongos ship` written
+// into a project's skills failed with `command not found` on every session's first call and the
+// assistant had to recover by retrying through npx. `npx` finds the project's own bin right after
+// `npm install`, with no setup, on every OS and shell — so that is the spelling a project reads.
+const PROJECT_CLI = 'npx bongos';
+
+// A hand-written bare `bongos <verb>` in skill prose (e.g. "`bongos paste-token <token>`"), so it
+// takes the npx spelling too. Case-sensitive on purpose ("Bongos status" is a product noun), only a
+// KNOWN verb, and never when already prefixed by `npx ` or glued to a path/name (`@bongos/core`,
+// `bongos-feedback`, `bongos: command not found` all stay). The `npx ` lookbehind is what keeps a
+// second run from writing `npx npx bongos`.
+function bareVerbRe(verbs) {
+  const names = Object.keys(verbs || {}).filter((v) => /^[a-z][a-z-]*$/.test(v));
+  if (!names.length) return null;
+  names.sort((a, b) => b.length - a.length); // `paste-token` before a shorter prefix of it
+  return new RegExp(String.raw`(?<![\w@/.\-])(?<!npx )bongos (${names.join('|')})(?![\w-])`, 'g');
+}
+
+// Pure: rewrite core-script invocations in a skill/settings command string to the project's CLI
+// spelling (`npx bongos <verb>`, else `npx bongos exec scripts/bongos/<x>.js`), and give any bare
+// `bongos <verb>` the same npx prefix. Idempotent: its own output contains neither a
+// `node scripts/…` invocation nor an un-prefixed `bongos <verb>`, so a second run changes nothing.
+function bongosify(text, verbs = VERBS) {
+  const map = scriptToVerb(verbs);
+  const bare = bareVerbRe(verbs);
+  let out = String(text == null ? '' : text);
+  if (bare) out = out.replace(bare, (_whole, verb) => `${PROJECT_CLI} ${verb}`);
+  return out
+    .replace(GDS_INVOCATION_RE, (_whole, script) => {
+      const verb = map[`${script}.js`];
+      return verb ? `${PROJECT_CLI} ${verb}` : `${PROJECT_CLI} exec scripts/bongos/${script}.js`;
+    })
+    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `${PROJECT_CLI} 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://example.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/bongos/…') 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; }
+// The brand token outbound User-Agents are built from, mirroring src/branding.js
+// userAgent(): repo name, else env prefix, lowercased. Kept in sync by the
+// tests/claude_materialize.mjs UA-rule case + tests/hook_user_agents.mjs.
+function effUaBase(b) {
+  const base = (b && b.repo && b.repo.name) || (b && b.envPrefix) || '';
+  return String(base).toLowerCase();
+}
+
+// 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_ → BONGOS_), bounded by its underscore.
+  add(`${effEnvPrefix(from)}_`, `${effEnvPrefix(to)}_`);
+  // task 1002672: the bare User-Agent brand token (e.g. `example-gds-cli/1.0`
+  // in a hook's outbound fetch). It carries no TLD, so none of the HOST rules above
+  // ever matched it and a founder-branded UA leaked into every materialized
+  // instance verbatim. Bounded by the `-gds` suffix (the userAgent() convention)
+  // so a bare founder word in prose is NOT rewritten — only the UA token shape.
+  // Both bases must resolve: an empty side would degenerate into a bare `-gds`
+  // rule that rewrites every occurrence of the suffix itself.
+  const fromUa = effUaBase(from), toUa = effUaBase(to);
+  if (fromUa && toUa) add(`${fromUa}-gds`, `${toUa}-gds`);
+  // 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; } }
+
+// Every module that declares `contributes.skills`, with whether the TARGET instance
+// enables it: the target's config/modules.json wins, else the module's own `default`.
+// The one place that rule lives — disabledModuleSkills and moduleSkillSources both
+// read it. PURE-ish (reads the fs) + exported.
+function moduleSkillRoster({ coreRoot, instanceDir }) {
+  const roster = [];
+  const modulesDir = path.join(coreRoot, 'modules');
+  if (!fs.existsSync(modulesDir)) return roster;
+  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 key = mj.key || dir;
+    const explicit = enabledMap[key];
+    const enabled = explicit === undefined ? mj.default === true : explicit === true;
+    roster.push({ key, dir: path.join(modulesDir, dir), enabled, skills });
+  }
+  return roster;
+}
+
+// Skills owned by a module that is DISABLED in the TARGET instance (task 2103b).
+// A skill owned by NO module is core and is never skipped.
+function disabledModuleSkills(opts) {
+  const skip = new Set();
+  for (const m of moduleSkillRoster(opts)) if (!m.enabled) for (const s of m.skills) skip.add(s);
+  return skip;
+}
+
+// A declared skill name is a path segment the materialiser WRITES under
+// .claude/skills/, so it is allowlisted before it ever reaches path.join: lowercase
+// slug only, no dots, no separators. A manifest carrying "../x" names nothing.
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// The vendoring gate a THIRD-PARTY skill must pass at copy time, not only in CI
+// (ADR 0198 §1–3): a PROVENANCE.md sidecar whose frontmatter names a licence on the
+// allowlist and a scan verdict that may land. The module's own skills/policy.json
+// (the ui-design shape) is the source of both lists when present; these defaults
+// are the same five licences and two verdicts otherwise. A gate that cannot read
+// the sidecar refuses — an unvetted copy never lands because a file was missing.
+const VENDOR_DEFAULT_POLICY = Object.freeze({
+  licenceAllowlist: ['Apache-2.0', 'MIT', 'BSD-2-Clause', 'BSD-3-Clause', 'CC-BY-4.0'],
+  verdictsThatMayLand: ['clean', 'caution'],
+});
+
+function sidecarFrontmatter(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; }
+  const m = text.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) out[kv[1]] = kv[2].replace(/^["']|["']$/g, '').trim();
+  }
+  return out;
+}
+
+// → { ok: true } or { ok: false, reason } for one vendored skill dir. Exported for the test.
+function vendoredSkillGate(dir, policy = VENDOR_DEFAULT_POLICY) {
+  const fm = sidecarFrontmatter(path.join(dir, 'PROVENANCE.md'));
+  if (!fm) return { ok: false, reason: 'no PROVENANCE.md sidecar (or no frontmatter)' };
+  const licences = Array.isArray(policy.licenceAllowlist) ? policy.licenceAllowlist : VENDOR_DEFAULT_POLICY.licenceAllowlist;
+  const verdicts = Array.isArray(policy.verdictsThatMayLand) ? policy.verdictsThatMayLand : VENDOR_DEFAULT_POLICY.verdictsThatMayLand;
+  if (!licences.includes(fm.licence)) return { ok: false, reason: `licence "${fm.licence || ''}" is not on the allowlist` };
+  if (!verdicts.includes(fm.scanVerdict)) return { ok: false, reason: `scan verdict "${fm.scanVerdict || ''}" may not land` };
+  return { ok: true };
+}
+
+// Skills a module ships from its OWN tree instead of .claude/skills/ (task 1003321,
+// ADR 0198): modules/<key>/skills/<name>/ for a skill the module authors, or
+// modules/<key>/skills/vendor/<name>/ for a third-party skill carried with its
+// PROVENANCE.md sidecar (the `vendor/` segment is the one fitness-ratchets exempts
+// from the first-party line budgets). Only a name the module DECLARES in
+// contributes.skills resolves — the manifest stays the single declaration — a name
+// that fails SKILL_NAME_RE is refused before any path is built, a dir with no
+// SKILL.md is not a skill, and a vendored dir must pass vendoredSkillGate. Refusals
+// come back in `refused[]` so the caller can log them. Accepts a precomputed
+// `roster` so materializeClaude walks modules/ once. PURE-ish (reads the fs) + exported.
+function moduleSkillSources(opts) {
+  const out = [];
+  const refused = [];
+  const roster = (opts && opts.roster) || moduleSkillRoster(opts);
+  for (const m of roster) {
+    const policy = readJsonSafe(path.join(m.dir, 'skills', 'policy.json')) || VENDOR_DEFAULT_POLICY;
+    for (const name of m.skills) {
+      if (typeof name !== 'string' || !SKILL_NAME_RE.test(name)) { refused.push({ name: String(name), module: m.key, reason: 'name is not a lowercase slug' }); continue; }
+      const own = path.join(m.dir, 'skills', name);
+      const vendored = path.join(m.dir, 'skills', 'vendor', name);
+      const src = [own, vendored].find((p) => fs.existsSync(path.join(p, 'SKILL.md')));
+      if (!src) continue;
+      if (src === vendored) {
+        const gate = vendoredSkillGate(src, policy);
+        if (!gate.ok) { refused.push({ name, module: m.key, reason: gate.reason }); continue; }
+      }
+      out.push({ name, module: m.key, dir: src, enabled: m.enabled, vendored: src === vendored });
+    }
+  }
+  out.refused = refused;
+  return out;
+}
+
+// ---- retired core skills: the tombstone list (task 1004482) -----------------
+// A skill the core USED to ship from its own .claude/skills/ and no longer does (the dev-box
+// verbs, the old /dev /ideate /paint role playbooks, the pixel-art skills that moved into a
+// default-off module). Every instance materialized before task 1004482 received them as core
+// skills, and the provenance manifest then recorded only module-declared names — so step 1c
+// could never prove it had put them there and they stayed in .claude/skills/ for the harness to
+// load and the hall's Commands page to list, forever.
+//
+// From task 1004482 on the manifest records EVERY skill a materialize lands, so a skill the core
+// drops later is withdrawn by step 1c's ordinary rule. This list closes the historical gap only,
+// and is therefore a closed set: it should not need a new entry.
+//
+// "Never touch a skill the instance authored" is held by a fingerprint, not by the name: each
+// entry lists sha256 digests (first 16 hex) of every description the core ever shipped under that
+// name, as written and as bongosify() rewrote it. A dir whose SKILL.md description matches none of
+// them is not ours and is left in place with a note — an owner who wrote their own /dev keeps it.
+const RETIRED_CORE_SKILLS_FILE = path.join(__dirname, 'retired-core-skills.json');
+
+// The `description:` value of a SKILL.md's frontmatter, whitespace-collapsed — a plain scalar,
+// a quoted one, or a block scalar (`>` / `|`) with its indented continuation lines. null when
+// the file has no frontmatter or no description. PURE + exported.
+function skillDescription(text) {
+  const m = String(text == null ? '' : text).replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!m) return null;
+  const lines = m[1].split('\n');
+  const i = lines.findIndex((l) => /^description:/.test(l));
+  if (i < 0) return null;
+  const parts = [lines[i].replace(/^description:\s*/, '')];
+  if (/^[>|][+-]?$/.test(parts[0])) parts[0] = '';
+  for (let j = i + 1; j < lines.length && /^\s+\S/.test(lines[j]); j += 1) parts.push(lines[j]);
+  const value = parts.join(' ').replace(/\s+/g, ' ').trim().replace(/^(["'])([\s\S]*)\1$/, '$2').trim();
+  return value || null;
+}
+
+function descriptionDigest(desc) {
+  return crypto.createHash('sha256').update(String(desc)).digest('hex').slice(0, 16);
+}
+
+// Does this instance skill dir carry a description the core shipped under `name`? Reads the
+// tombstone's digests; an unreadable SKILL.md or a missing description answers "no" (keep it).
+function isRetiredCoreCopy(dir, digests) {
+  if (!Array.isArray(digests) || !digests.length) return false;
+  let text;
+  try { text = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8'); } catch { return false; }
+  const desc = skillDescription(text);
+  return desc != null && digests.includes(descriptionDigest(desc));
+}
+
+function readRetiredCoreSkills(file = RETIRED_CORE_SKILLS_FILE) {
+  const j = readJsonSafe(file);
+  return j && j.skills && typeof j.skills === 'object' ? j.skills : {};
+}
+
+// ---- 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)
+
+// Every file under `dir`, as paths relative to it. Used to name a withdrawn skill dir's
+// files before it is removed — a deletion git reports one file at a time, never the dir.
+function listFilesRecursive(dir, base = '') {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(path.join(dir, base), { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const rel = path.join(base, e.name);
+    if (e.isDirectory()) out.push(...listFilesRecursive(dir, rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+// `overwrite` defaults true (greenfield init / upgrade — byte-identical to before).
+// `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.
+// `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()) {
+      for (const name of fs.readdirSync(absSrc)) walk(path.join(rel, name));
+      return;
+    }
+    const absDest = path.join(destDir, rel);
+    if (!overwrite && fs.existsSync(absDest)) { // adopt: leave-and-report, never clobber
+      skipped.push(rel);
+      if (onFile) onFile(rel, { skipped: true });
+      return;
+    }
+    files += 1;
+    if (dryRun) { if (onFile) onFile(rel); return; }
+    fs.mkdirSync(path.dirname(absDest), { recursive: true });
+    if (textExt.has(path.extname(rel))) {
+      fs.writeFileSync(absDest, transform(fs.readFileSync(absSrc, 'utf8')));
+    } else {
+      fs.copyFileSync(absSrc, absDest); // binary / other — verbatim
+    }
+    if (onFile) onFile(rel);
+  };
+  if (!fs.existsSync(srcDir)) return { files: 0, skipped, excluded, present: false };
+  for (const name of fs.readdirSync(srcDir)) walk(name);
+  return { files, skipped, excluded, present: true };
+}
+
+// Transform settings.json: parse, rewrite every hook command through bongosify, re-serialize. Keeps
+// .claude/hooks/*.js commands (instance-local) untouched and rewrites the scripts/bongos/*.js ones.
+// The blessed commands an instance builder runs to do the methodology, one rule
+// each (task 1003962). This MIRRORS the core repo's own `.claude/settings.json`
+// allow-list (ADR 0104 / task 1051), translated from `node scripts/bongos/<x>.js`
+// into the verb form a materialized instance actually invokes — bongosify()
+// rewrites every skill to `bongos <verb>`, so a path-shaped rule would match
+// nothing there.
+//
+// THE GAP THIS CLOSES. `.claude/settings.json` is excluded from the published
+// package on purpose (PROTECTED_TOPOLOGY_EXCLUDE, beside infra/ and .github/):
+// the core's own copy is deploy and gate machinery that means nothing on an
+// instance. But the skills ship, so an instance received the methodology and
+// none of the permissions that let it run — every instance builder met the
+// auto-mode classifier on the normal workflow, which is how a live builder came
+// to be stuck mid-re-auth with no way forward.
+//
+// WHY THIS IS NOT AN AUTHORITY GRANT (ADR 0016). An allow-rule stops the local
+// agent REFUSING to run a command; it changes nothing about what the server
+// permits. Rank is read fresh from the database on every request by
+// `requireRank`, so a builder who edits this file grants themselves exactly
+// nothing. That is the distinction that makes shipping a list of command names
+// safe where shipping hooks — actual local gate machinery — is not.
+//
+// DELIBERATELY ABSENT: `bongos exec`. It runs any script inside the core by
+// path and is the agent's escape hatch, so allow-listing it would be a blanket
+// grant wearing a narrow rule's clothes. The one script the core's own list
+// blesses (`api.js`) is named in full instead.
+//
+// EVERY RULE IS THE `npx bongos` SPELLING (task 1004621): a project has no bare
+// `bongos` on PATH, so its skills, its CLAUDE.md and Settings → CLI access
+// (task 1004575) all say `npx bongos …`, and a bare-`bongos` rule would allow a
+// command nothing runs. An instance that took the older bare starter gains the
+// npx twin of each bare rule it still holds on its next upgrade
+// (topUpNpxAllowTwins below).
+const STARTER_COMMANDS = [
+  'npx bongos claim:*',
+  'npx bongos ship:*',
+  'npx bongos release:*',
+  'npx bongos reauth:*',
+  'npx bongos paste-token:*',
+  'npx bongos exec scripts/bongos/api.js:*',
+  // The read-only subset (task 1003992, ADR 0304). `git branch` and `git fetch`
+  // are exact forms on purpose: a flag turns either into a write or an exec. No
+  // `git diff|log|show` rule, also on purpose: the harness already runs their
+  // read-only forms unprompted, and a prefix rule would switch off its flag check
+  // (`--output=<file>` writes anywhere, `diff --no-index` reads any file).
+  // tests/cli_allowlist_permissions.mjs pins this list to the core's, rule for rule.
+  'npx bongos start:*',
+  'npx bongos status:*',
+  // Exact form, no `:*`: reading the ship mode is how the agent knows whether to ship on its own
+  // (task 1004631, ADR 0369). `ship-mode auto|manual` WRITES it, and stays a prompt.
+  'npx bongos ship-mode',
+  'npx bongos recall:*',
+  'npx bongos exec scripts/bongos/me.js:*',
+  'npx bongos doctor:*',
+  'npx bongos exec scripts/bongos/preflight.js:*',
+  'npx bongos exec scripts/bongos/skill-preflight.js:*',
+  'npx bongos exec scripts/bongos/ship-check.js:*',
+  'npx bongos exec scripts/bongos/fitness.js:*',
+  'npx bongos exec scripts/bongos/strand-watch.js:*',
+  'npx bongos exec scripts/bongos/stale-worktrees.js:*',
+  'npx bongos exec scripts/bongos/read-session-export.js:*',
+  'git status:*',
+  'git branch --list',
+  'git branch --show-current',
+  'git branch -a',
+  'git branch -vv',
+  'git fetch',
+  'git fetch origin',
+  'git fetch origin main',
+  'gh pr view:*',
+  'gh pr checks:*',
+  'gh pr list:*',
+  'gh run view:*',
+  'gh run list:*',
+];
+// One rule per command PER SHELL TOOL (task 1004014): the shell tool is `PowerShell` on a Windows
+// laptop, and a `Bash(...)` rule says nothing about its commands. The tools are the ones the guards
+// see (`.claude/hooks/shell-tools.js`) — held equal by tests/cli_allowlist_permissions.mjs, not a require.
+const STARTER_SHELL_TOOLS = ['Bash', 'PowerShell'];
+const STARTER_ALLOW = STARTER_SHELL_TOOLS.flatMap((tool) => STARTER_COMMANDS.map((command) => `${tool}(${command})`));
+
+// The deny half (task 1003966): what the local agent may not READ. Keys are the
+// same exposure on every instance, so those rules ship verbatim.
+const STARTER_DENY_SECRETS = [
+  'Read(.env)', 'Read(**/.env)', 'Read(.env.local)', 'Read(**/.env.local)',
+  'Read(.env.*.local)', 'Read(**/.env.*.local)',
+  'Read(**/*.pem)', 'Read(**/id_rsa*)', 'Read(**/id_ed25519*)',
+];
+const SESSION_STORE_DENY = `Read(~/.config/${ic.FALLBACK_DIR}/instances/**)`;
+
+// A checkout's settings.json takes the identity rebrand like every copied file, and the store's
+// dir is one of the core's `.config/<dir>` literals it rewrites. The store does not move with the
+// brand (task 1003741), so its rule is put back where the CLI reads it (task 1004155).
+function rebrandSettings(text, rebrand) {
+  const moved = rebrand(SESSION_STORE_DENY);
+  return rebrand(text).split(JSON.stringify(moved)).join(JSON.stringify(SESSION_STORE_DENY));
+}
+
+// Credential files are derived from where the CLI actually reads them, not rebranded from the
+// core's literals: the rebrand would also move the host-keyed store, which sits at a fixed anchor
+// whatever the brand (cli-lib sessionStoreDir, task 1003741).
+//
+// credentialDeny is the half that may be added to a settings.json the instance already owns.
+// Every rule here stops the agent READING A SECRET, and nothing an instance legitimately does
+// requires reading its own key or session token from inside an agent session — which is what
+// makes appending one provably safe (ADR 0326: a deny rule is monotonic in the safe direction).
+function credentialDeny(branding = {}) {
+  const dirs = [...new Set([effConfigDir(branding), ...ic.LEGACY_DIRS])];
+  const credentialFiles = ['env', ...ic.SESSION_FILENAMES];
+  return [
+    ...STARTER_DENY_SECRETS,
+    ...dirs.flatMap((dir) => credentialFiles.map((file) => `Read(~/.config/${dir}/${file})`)),
+    SESSION_STORE_DENY,
+  ];
+}
+
+// starterDeny — what a FRESH instance gets: the credential half plus the shelf rules, which are
+// the only layer an instance has against the repo-global stash stack since the git-guard hook is
+// topology and does not ship.
+//
+// The shelf rules are starter-only, and deliberately NOT in the top-up (task 1004158, amending
+// ADR 0326, which named this exclusion as the remedy if the rule ever bit). They guard a WORKFLOW
+// rather than a secret, so the monotonicity argument that licenses the top-up does not reach them:
+// with no provenance by design, and deny beating allow in Claude Code's permission order, an
+// instance whose builders used the shelf as a set-aside could not re-enable it from its own
+// settings.json afterwards. A fresh instance is different in kind — there the rule is a visible
+// default present from the first commit, editable before any workflow has grown around it.
+function starterDeny(branding = {}) {
+  return [
+    ...credentialDeny(branding),
+    ...STARTER_SHELL_TOOLS.map((tool) => `${tool}(git stash:*)`),
+  ];
+}
+
+// topUpStarterDeny — the deny rules an instance's OWN settings.json is missing, added to it
+// (task 1004156). The starter is only ever written when the file is ABSENT, so every instance
+// that took the allow-only starter from task 1003962 keeps it forever and its local agent can
+// still read .env files, keys and session tokens. ADDING is the whole safety argument: a deny
+// rule can only ever narrow what the agent may do, so appending one cannot widen this instance's
+// permissions — which is why the owner's call (task 1004156) was "add them, and say which".
+// "Never clobber" is unchanged in the sense that matters: nothing the instance wrote is removed
+// or rewritten. Returns { text, added, reason }; `text` is null when nothing should be written.
+// `reason` is the STRUCTURED signal that the file could not be CHECKED — null means "healthy",
+// so callers branch on its presence rather than on the wording of a message. An unparseable or
+// unexpectedly-shaped file is LEFT ALONE and reported, the posture task 1004023 took for a
+// settings.json that will not parse: a half-understood rewrite of a permissions file is worse
+// than the gap it closes. Note the write re-emits the whole document at 2-space JSON, so an
+// instance indented some other way sees a whole-file diff — the RULES are still append-only,
+// which is what the safety argument rests on, and the run output says so.
+function topUpStarterDeny(existingText, wanted) {
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const cannotCheck = (reason) => ({ text: null, added: [], reason });
+  let doc;
+  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
+  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
+  const perms = doc.permissions === undefined ? {} : doc.permissions;
+  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
+  const deny = perms.deny === undefined ? [] : perms.deny;
+  if (!Array.isArray(deny)) return cannotCheck('its "permissions.deny" is not an array');
+  const have = new Set(deny);
+  const added = wanted.filter((rule) => !have.has(rule));
+  if (!added.length) return { text: null, added: [], reason: null }; // healthy: every rule already there
+  const next = { ...doc, permissions: { ...perms, deny: [...deny, ...added] } };
+  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
+}
+
+// topUpNpxAllowTwins — the `npx bongos` twin of every bare-`bongos` allow rule an instance's OWN
+// settings.json holds (task 1004621). The skills an upgrade lands now say `npx bongos ship`, and a
+// `Bash(bongos ship:*)` rule does not match that, so without the twin the upgrade would trade a
+// `command not found` for a permission prompt on every blessed command. This is NOT the shell-rule
+// top-up task 1004158 ruled out: nothing new is offered. Each twin is a rule the owner already
+// holds, respelled for the one launcher that reaches the same project-local bin — a rule they
+// removed gets no twin, and nothing they wrote is removed or rewritten. Same { text, added, reason }
+// contract as topUpStarterDeny; an unreadable shape is left alone and reported.
+const BARE_BONGOS_RULE_RE = /^(\w+)\(bongos (.+)\)$/;
+function topUpNpxAllowTwins(existingText) {
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const cannotCheck = (reason) => ({ text: null, added: [], reason });
+  let doc;
+  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
+  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
+  const perms = doc.permissions === undefined ? {} : doc.permissions;
+  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
+  const allow = perms.allow === undefined ? [] : perms.allow;
+  if (!Array.isArray(allow)) return cannotCheck('its "permissions.allow" is not an array');
+  const have = new Set(allow);
+  const added = [];
+  for (const rule of allow) {
+    const m = typeof rule === 'string' && rule.match(BARE_BONGOS_RULE_RE);
+    const twin = m && `${m[1]}(${PROJECT_CLI} ${m[2]})`;
+    if (twin && !have.has(twin)) { have.add(twin); added.push(twin); }
+  }
+  if (!added.length) return { text: null, added: [], reason: null };
+  const next = { ...doc, permissions: { ...perms, allow: [...allow, ...added] } };
+  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
+}
+
+// The starter an instance gets when the core root carries no settings.json — a
+// package-only install. Permissions ONLY: no hooks (they are topology), no env.
+function renderStarterSettings(branding = {}) {
+  return `${JSON.stringify({
+    _doc: 'Starter written by scripts/bongos/claude-materialize.js (tasks 1003962, 1003966). Permissions only — the blessed Bongos commands, mirroring the core repo\'s own allow-list (ADR 0104), and the deny rules that keep the local agent from reading keys and session tokens. An allow-rule lets the local agent RUN a command; it grants no authority, which the server decides per request from your live rank (ADR 0016). Yours to edit: a later materialize never removes or rewrites a rule you wrote. It will ADD a CREDENTIAL deny rule this starter has gained since (task 1004156) and name it in the run output — additive only, so it can never widen what the local agent may do. Only that half is topped up: the shell rules below guard a workflow rather than a secret, so once this file exists they are yours alone and an upgrade will neither add nor remove one (task 1004158).',
+    permissions: { allow: STARTER_ALLOW, deny: starterDeny(branding) },
+  }, null, 2)}\n`;
+}
+
+// readSettingsTransform — the transform, as a result rather than a string:
+// { text, parsed, reason }. transformSettings below is the string face of it,
+// kept because that is what the tests and the historical callers use.
+//
+// WHY A PARSE FAILURE IS COPIED THROUGH UNTOUCHED (task 1004023). The old
+// fallback was `bongosify(raw)` — a best-effort regex rewrite over the whole
+// file. The script-invocation regex ends in an optional quote so it can swallow the
+// closing quote of a QUOTED PATH inside a command; run over raw JSON text it
+// swallows the JSON string's own closing quote instead:
+//
+//     bongosify('{"command": "node scripts/bongos/strand-watch.js", }')
+//     -> {"command": "bongos exec scripts/bongos/strand-watch.js, }
+//
+// So a file that was one trailing comma from valid was written to the instance
+// MORE broken than it arrived, with its strings running into each other. A
+// rewrite of text we could not parse is not worth a worse file: the raw bytes
+// are copied through unchanged and the caller is handed a reason to report. The
+// operator fixes one comma instead of unpicking mangled strings.
+//
+// The parse failure is NOT made fatal: the core's own settings.json is valid
+// JSON (pinned by a test), so reaching this means the operator has edited
+// theirs, and refusing the whole materialize over one file would be a worse
+// trade than copying it and saying so.
+function readSettingsTransform(srcPath) {
+  const raw = fs.readFileSync(srcPath, 'utf8');
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    return { text: raw, parsed: false, reason: (err && err.message) || 'not valid JSON' };
+  }
+  const hooks = json && json.hooks;
+  if (hooks && typeof hooks === 'object') {
+    for (const event of Object.values(hooks)) {
+      for (const matcher of Array.isArray(event) ? event : []) {
+        for (const h of (matcher && Array.isArray(matcher.hooks)) ? matcher.hooks : []) {
+          if (typeof h.command === 'string') h.command = bongosify(h.command);
+        }
+      }
+    }
+  }
+  // Permission rules name the SAME commands the hooks and skills do, so they take the same
+  // rewrite — a rule left as `node scripts/bongos/ship.js` matches nothing once the instance's
+  // skills run `bongos ship` (task 1004012). `allow` gets the one spelling the skills use; a
+  // restrictive list gets BOTH ways an instance can reach the script, or it guards only one.
+  const perms = json && json.permissions;
+  if (perms && typeof perms === 'object') {
+    for (const [key, rules] of Object.entries(perms)) {
+      if (!Array.isArray(rules)) continue;
+      // an empty verb table makes bongosify emit the `bongos exec scripts/bongos/<x>.js` spelling
+      const spellings =(r) => (key === 'allow' ? [bongosify(r)] : [bongosify(r), bongosify(r, {})]);
+      perms[key] = [...new Set(rules.flatMap((r) => (typeof r === 'string' ? spellings(r) : [r])))];
+    }
+  }
+  return { text: JSON.stringify(json, null, 2) + '\n', parsed: true, reason: null };
+}
+
+// transformSettings — the string face of readSettingsTransform. A caller that
+// only wants the bytes keeps working; one that needs to know the file could not
+// be parsed calls readSettingsTransform and reads `parsed`.
+function transformSettings(srcPath) {
+  return readSettingsTransform(srcPath).text;
+}
+
+// Materialize the .claude/ surface from `coreRoot` into `instanceDir`. Returns a summary.
+// `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). The ONE
+// exception is settings.json in a package-only install, which GAINS any starter deny rule it is
+// missing and reports them in `summary.settingsDenyAdded` (task 1004156) — additive only, so
+// nothing the instance wrote is removed or rewritten.
+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, moduleSkills: 0, settings: false, settingsUnparsed: false, settingsDenyAdded: [], settingsDenyUncheckable: null, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, writtenPaths: [], notes: [] };
+  // Every instance-relative path this run WROTE or REMOVED (task 1003957). `bongos upgrade`
+  // hands these to persistPin as artifactPaths, exactly as task 1003926 already does for
+  // regenerateApiArtifacts' output: committing only the pin left the materialized files dirty,
+  // so the NEXT sweep's clean-tree guard called them "a human's work" and skipped the instance
+  // FOREVER — an enrolled co-tenant upgraded exactly once (proven on `charter` 2026-09-16).
+  //
+  // Recording what we wrote is a STRONGER provenance than a static file list: every path here
+  // is one this very run produced. It cannot carry an owner's edit either, and not for the
+  // "generated end to end" reason API_ARTIFACT_FILES gives — for a sharper one. Under
+  // `overwrite` the copy ALREADY replaced whatever the file held before reaching this line, so
+  // the only choice left is commit that overwrite or strand the instance; leaving it dirty
+  // protects nothing and stops every future update. Under `overwrite: false` (the `init
+  // --adopt` path) nothing is clobbered — copyTreeTransformed reports those as `skipped` and
+  // addWritten ignores them — so an adopting instance records nothing here and commits nothing.
+  const rel = (p) => String(p).split(path.sep).join('/');
+  const addWritten = (p) => { summary.writtenPaths.push(rel(p)); };
+  // A copyTreeTransformed onFile that records real writes under `base` and ignores the
+  // leave-and-report entries adopt mode emits.
+  const recordUnder = (base) => (r, info) => { if (!info || !info.skipped) addWritten(path.join(base, r)); };
+  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).');
+    log('  • .claude/ materialize: instance dir == core root — skipped (nothing to copy).');
+    return summary;
+  }
+  const srcClaude = path.join(coreRoot, '.claude');
+  const destClaude = path.join(instanceDir, '.claude');
+  const left = (n) => (overwrite || n === 0 ? '' : ` (${n} left untouched)`);
+
+  // 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). One
+  // walk of modules/ serves both this skip and step 1b's module-owned sources.
+  const roster = moduleSkillRoster({ coreRoot, instanceDir });
+  const skipSkills = new Set();
+  for (const m of roster) if (!m.enabled) for (const s of m.skills) skipSkills.add(s);
+  // A core checkout that materialised module skills into its own .claude/skills/ (task 1003330)
+  // carries them as untracked copies plus two dotfiles; step 1 must not ship those as core
+  // skills — step 1b lands them from the module, transformed, like everywhere else.
+  const materialisedInCore = readModuleSkillsManifest(path.join(coreRoot, '.claude', 'skills')).skills;
+  // The INSTANCE's own provenance record — what a PREVIOUS materialize landed here.
+  // Distinct from materialisedInCore above (that one is the core checkout's). Step 1c
+  // withdraws from this set and nothing else.
+  const landedPreviously = readInstanceSkillsManifest(path.join(destClaude, 'skills')).skills;
+  const skillSkip = (rel) => { const top = String(rel).split(/[\\/]/)[0]; return skipSkills.has(top) || top === MODULE_SKILLS_MANIFEST || top === INSTANCE_SKILLS_MANIFEST || top === '.gitignore' || Object.prototype.hasOwnProperty.call(materialisedInCore, top); };
+
+  // 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, transform: (t) => rebrand(bongosify(t)), skip: skillSkip,
+    onFile: recordUnder('.claude/skills'),
+  });
+  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.');
+  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)}`);
+
+  // 1b. module-owned skills — shipped from modules/<key>/skills/ (own) or
+  //     modules/<key>/skills/vendor/ (third-party + PROVENANCE.md) and landed in the
+  //     SAME .claude/skills/<name>/ the builder's harness reads (task 1003321, ADR
+  //     0198). Same transforms as step 1; a disabled module's are excluded by the same
+  //     rule; a name the core's own .claude/skills/ already carries keeps the core copy;
+  //     a name that is not a slug, or a vendored dir that fails the sidecar gate, is
+  //     REFUSED here at copy time — the CI test is the second line, not the only one.
+  const sources = moduleSkillSources({ roster });
+  for (const r of sources.refused) {
+    summary.notes.push(`module skill "${r.name}" (${r.module}) refused: ${r.reason}.`);
+    log(`  ✗ refused module skill "${r.name}" (${r.module}): ${r.reason}`);
+  }
+  for (const s of sources) {
+    if (!s.enabled) { if (!summary.excludedSkills.includes(s.name)) summary.excludedSkills.push(s.name); continue; }
+    if (fs.existsSync(path.join(skillsSrc, s.name)) && !Object.prototype.hasOwnProperty.call(materialisedInCore, s.name)) {
+      summary.notes.push(`module skill "${s.name}" (${s.module}) also exists under the core's .claude/skills/ — the core copy was materialized, the module copy ignored.`);
+      continue;
+    }
+    const r = copyTreeTransformed(s.dir, path.join(destClaude, 'skills', s.name), { dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), onFile: recordUnder(`.claude/skills/${s.name}`) });
+    summary.moduleSkills += r.files;
+    for (const rel of r.skipped || []) summary.skippedFiles.push(`skills/${s.name}/${rel}`);
+  }
+  if (summary.moduleSkills) log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${summary.moduleSkills} module-owned skill file(s) → .claude/skills/ (from modules/<key>/skills/)`);
+
+  // 1c. WITHDRAW a skill a previous materialize landed here that this run no longer
+  //     lands — the module was switched off (or stopped declaring the name) on an
+  //     instance that ALREADY has the files. Step 1's skillSkip and step 1b's
+  //     `enabled` check both only decline to COPY, which is the whole bug: disabling
+  //     a module was honoured on a fresh instance and silently ignored on
+  //     `bongos upgrade`, leaving stale dirs in .claude/skills/ for the harness to
+  //     keep loading (task 1003632, found by the on/off proof of task 1003331).
+  //     materializeModuleSkillsIntoCore has done this for the core checkout since
+  //     task 1003330; this is the same mechanism for the instance side.
+  //
+  //     PROVENANCE-GATED, and that gate is the safety property: only a name the
+  //     manifest says a previous run LANDED is eligible. A skill the instance's owner
+  //     wrote by hand was never in the manifest, so it can never be deleted here even
+  //     if a module happens to declare the same name. With no manifest at all — an
+  //     instance last materialized before this shipped — nothing is withdrawn and a
+  //     note says so: that first run writes the provenance, and every run after it
+  //     honours a disable. Refusing to guess is the point; deleting a builder's skill
+  //     because we cannot prove we put it there is the one outcome worth avoiding.
+  const skillsDest = path.join(destClaude, 'skills');
+  const landedNow = {};
+  for (const src of sources) {
+    if (!src.enabled) continue;
+    // A dry run copied nothing, so it records what WOULD land; a real run confirms
+    // the dir is actually there before claiming provenance over it.
+    if (!dryRun && !fs.existsSync(path.join(skillsDest, src.name))) continue;
+    landedNow[src.name] = { module: src.module, source: path.relative(coreRoot, src.dir).split(path.sep).join('/'), vendored: src.vendored };
+  }
+  // A core-SHIPPED skill whose name a module also declares is landed by step 1, not
+  // step 1b — but it is withdrawable by the same disabled-module rule, so it needs
+  // provenance too.
+  for (const mod of roster) {
+    if (!mod.enabled) continue;
+    for (const name of mod.skills) {
+      if (landedNow[name] || !fs.existsSync(path.join(skillsSrc, name))) continue;
+      landedNow[name] = { module: mod.key, source: `.claude/skills/${name}`, coreShipped: true };
+    }
+  }
+  // A name the CORE ships now is the core's, whatever an older manifest said — a core
+  // skill can take over a name a module once owned, and step 1 copies it in on this very
+  // run. Without this guard 1c deleted it again immediately (task 1003818, a regression
+  // in 1003632's own first cut). materializeModuleSkillsIntoCore states the same rule for
+  // the checkout side via its `tracked(name)` check; this is the instance-side twin.
+  //
+  // The `!skipSkills.has(name)` half is load-bearing, not belt-and-braces: when a DISABLED
+  // module declares a core-shipped name, step 1 SKIPS the copy (that is the task 2103b
+  // exclusion), so the instance's dir really is stale and must still be withdrawn. Keeping
+  // it on the strength of "the core ships this name" would resurrect exactly the bug 1c
+  // exists to fix. Deliberately asked of the CORE source tree rather than the roster, so a
+  // name no enabled module declares any more is still recognised as legitimately sourced.
+  const coreShipsNow = (name) => fs.existsSync(path.join(skillsSrc, name)) && !skipSkills.has(name);
+  // Every CORE skill step 1 landed is recorded too (task 1004482), so a skill the core stops
+  // shipping in a later release is withdrawn by the rule below instead of lingering forever.
+  // When the core's .claude/skills/ could not be read at all, nothing was landed from it and
+  // nothing may be withdrawn on that account: the previous core entries are carried forward.
+  const coreTreeRead = skillsRes.present;
+  if (coreTreeRead) {
+    for (const name of fs.readdirSync(skillsSrc)) {
+      if (landedNow[name] || !SKILL_NAME_RE.test(name) || skillSkip(name)) continue;
+      if (!fs.statSync(path.join(skillsSrc, name)).isDirectory()) continue;
+      if (!dryRun && !fs.existsSync(path.join(skillsDest, name))) continue;
+      landedNow[name] = { source: `.claude/skills/${name}`, coreShipped: true };
+    }
+  } else {
+    for (const [name, rec] of Object.entries(landedPreviously)) if (rec && rec.coreShipped && !rec.module && !landedNow[name]) landedNow[name] = rec;
+  }
+  const withdrawable = Object.keys(landedPreviously).filter((n) => SKILL_NAME_RE.test(n) && !landedNow[n] && !coreShipsNow(n));
+  // The historical half (task 1004482): a skill the core retired BEFORE the manifest recorded
+  // core skills is withdrawn when its dir still carries a description the core shipped under
+  // that name. Anything else under a retired name is the instance's own and stays.
+  const retired = readRetiredCoreSkills();
+  const keptAsOwn = [];
+  for (const [name, entry] of Object.entries(retired)) {
+    if (!SKILL_NAME_RE.test(name) || landedNow[name] || coreShipsNow(name) || withdrawable.includes(name)) continue;
+    const dir = path.join(skillsDest, name);
+    if (!fs.existsSync(dir)) continue;
+    if (isRetiredCoreCopy(dir, entry && entry.descriptionDigests)) withdrawable.push(name);
+    else keptAsOwn.push(name);
+  }
+  if (keptAsOwn.length) summary.notes.push(`${keptAsOwn.length} skill dir(s) share a name the core once shipped but are not the core's copy (their description is not one it shipped), so they were left in place as the instance's own: ${keptAsOwn.sort().join(', ')}.`);
+  if (!overwrite) {
+    // adopt mode never clobbers what the owner already has; withdrawing is a clobber.
+    if (withdrawable.length) summary.notes.push(`${withdrawable.length} skill(s) the core no longer lands here were left in place (adopt mode does not withdraw): ${withdrawable.sort().join(', ')}.`);
+  } else {
+    for (const name of withdrawable.sort()) {
+      const dir = path.join(skillsDest, name);
+      if (!fs.existsSync(dir)) continue;
+      // A DELETION is a dirty path too, and `git status` names the individual files rather
+      // than the directory — so enumerate before removing, or the withdrawal is exactly the
+      // kind of leftover that wedges the next sweep (task 1003957).
+      for (const f of listFilesRecursive(dir)) addWritten(path.join('.claude/skills', name, f));
+      if (!dryRun) fs.rmSync(dir, { recursive: true, force: true });
+      summary.withdrawnSkills.push(name);
+    }
+    if (summary.withdrawnSkills.length) log(`  ${dryRun ? '[dry-run] would withdraw' : '✓ withdrew'} ${summary.withdrawnSkills.length} stale skill dir(s) the core no longer ships here (retired, or its module is off): ${summary.withdrawnSkills.join(', ')}`);
+  }
+  if (!Object.keys(landedPreviously).length && summary.excludedSkills.length) {
+    summary.notes.push('no .instance-skills.json provenance in .claude/skills/ yet, so nothing was withdrawn — this run records it; a later run can withdraw the skills of a module that has since been disabled.');
+  }
+  // Record what landed, so the NEXT run can withdraw what this one placed.
+  //
+  // REPORTED on a dry run, written only on a real one — the same split the starter CLAUDE.md
+  // below already uses. writtenPaths is a "what this run rewrites" list, and a dry run's job is
+  // to preview exactly that: upgrade.js asks for one to decide which dirty paths its clean-tree
+  // pre-flight may ignore (task 1004122), so a generated file missing from the preview is a file
+  // the pre-flight halts on and the real run then rewrites anyway.
+  if (overwrite) {
+    const names = Object.keys(landedNow).sort();
+    const manifest = { _doc: 'GENERATED by scripts/bongos/claude-materialize.js (tasks 1003632, 1004482): every skill a materialize landed in this instance, core and module alike. It is the provenance record that lets a later run WITHDRAW a skill the core stopped shipping or whose module has since been disabled — a name absent from here is never deleted on that account, so a hand-written skill is safe. Commit it; do not hand-edit.', skills: Object.fromEntries(names.map((n) => [n, landedNow[n]])) };
+    if (!dryRun) {
+      fs.mkdirSync(skillsDest, { recursive: true });
+      fs.writeFileSync(path.join(skillsDest, INSTANCE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
+    }
+    addWritten(path.join('.claude/skills', INSTANCE_SKILLS_MANIFEST));
+  }
+
+  // 2. settings.json — topology; present in the checkout/core repo, absent in a package-only install.
+  const settingsSrc = path.join(srcClaude, 'settings.json');
+  if (fs.existsSync(settingsSrc)) {
+    const settingsDest = path.join(destClaude, 'settings.json');
+    if (!overwrite && fs.existsSync(settingsDest)) { // adopt: never clobber an owner's settings.json
+      summary.skippedFiles.push('settings.json');
+      log('  • .claude/settings.json already present — left untouched (adopt merges nothing here yet).');
+    } else {
+      // task 1004023: an unparseable settings.json is copied through BYTE FOR
+      // BYTE — no bongosify, no rebrand. Both are regex passes written for the
+      // strings inside a parsed file, and over raw JSON text they damage it.
+      // The instance gets what the core had, plus a note naming the parse error.
+      const settingsOut = readSettingsTransform(settingsSrc);
+      if (!dryRun) {
+        fs.mkdirSync(destClaude, { recursive: true });
+        fs.writeFileSync(settingsDest, settingsOut.parsed ? rebrandSettings(settingsOut.text, rebrand) : settingsOut.text);
+      }
+      addWritten('.claude/settings.json');
+      summary.settings = true;
+      if (!settingsOut.parsed) {
+        summary.settingsUnparsed = true;
+        summary.notes.push(`.claude/settings.json is not valid JSON (${settingsOut.reason}) — copied through UNCHANGED: no hook-command or permission-rule rewrite to bongos, and no identity rebrand. Fix the JSON at the core root and materialize again, or edit the instance copy by hand.`);
+      }
+      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json ${settingsOut.parsed ? '(hook commands + permission rules→bongos, identity rebranded)' : '(UNCHANGED — not valid JSON, nothing rewritten)'}`);
+    }
+  } else {
+    // Package-only install: the core root carries no settings.json to copy, so
+    // write the STARTER instead of leaving the instance with no permissions at
+    // all (task 1003962 — the note that used to sit here said "provide it from a
+    // starter" and nothing ever did). Written only when ABSENT, the same rule
+    // the starter CLAUDE.md below follows: an instance that has grown its own
+    // permissions owns them, and a later materialize must never clobber them.
+    const settingsDest = path.join(destClaude, 'settings.json');
+    if (fs.existsSync(settingsDest)) {
+      // The instance owns this file — but a deny rule the starter has gained since is ADDED to
+      // it rather than withheld forever (task 1004156). Nothing of theirs is removed or changed.
+      // Only the CREDENTIAL half is offered: the starter's shelf rules guard a workflow, not a
+      // secret, and are starter-only (task 1004158).
+      // The read is guarded: existsSync passing does not mean readable (a directory at that path,
+      // a locked or root-owned file), and this runs AFTER the pin moved and the migrations ran, so
+      // a throw here would leave a half-applied upgrade. It fails soft, like its sibling above.
+      // The npx twins of the owner's own bare-`bongos` allow rules ride the same single read and
+      // write (task 1004621): applied first, so the deny top-up below works on — and writes — the
+      // text that already carries them. An unparseable file trips both the same way and is
+      // reported once, by the deny half.
+      let topUp;
+      let twins = { text: null, added: [], reason: null };
+      try {
+        const raw = fs.readFileSync(settingsDest, 'utf8');
+        twins = topUpNpxAllowTwins(raw);
+        topUp = topUpStarterDeny(twins.text || raw, credentialDeny(toBranding));
+      } catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
+      if (twins.added.length) {
+        summary.settingsAllowTwinsAdded = twins.added;
+        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED the \`npx bongos\` twin of ${twins.added.length} bare-\`bongos\` allow rule(s) it held — the skills now say \`npx bongos …\`, which a bare rule does not match: ${twins.added.join(', ')}`);
+        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} the npx twin of ${twins.added.length} bare-bongos allow rule(s) to .claude/settings.json (skills now run \`npx bongos …\`; every rule you wrote is kept): ${twins.added.join(', ')}`);
+        if (!topUp.text && !topUp.reason) {
+          if (!dryRun) fs.writeFileSync(settingsDest, twins.text);
+          if (!dryRun) addWritten('.claude/settings.json'); // real run only — the same reasoning as the deny write below
+        }
+      }
+      if (topUp.text) {
+        if (!dryRun) fs.writeFileSync(settingsDest, topUp.text);
+        // Reported as written only on the REAL run, deliberately. writtenPaths doubles as the set
+        // the upgrade pre-flight IGNORES when it checks for a dirty tree (task 1004122), and that
+        // waiver is justified by "materialize overwrites these unconditionally, so whatever they
+        // hold now is discarded either way" — which is precisely NOT true of a top-up, the one
+        // path here that preserves existing content. Leaving it out of the dry-run preview keeps
+        // an owner's uncommitted edit to settings.json halting the bump, as it always did; putting
+        // it in the real run's summary still hands it to persistPin, so the pin commit carries the
+        // added rules and the next upgrade does not read them as a human's stray work.
+        if (!dryRun) addWritten('.claude/settings.json');
+        summary.settingsDenyAdded = topUp.added;
+        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED ${topUp.added.length} missing deny rule(s) — an instance that took the starter before task 1003966 carried none of them, so its local agent could still read keys and session tokens: ${topUp.added.join(', ')}`);
+        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} ${topUp.added.length} missing deny rule(s) to .claude/settings.json — every rule you wrote is kept, the file is re-indented to 2 spaces: ${topUp.added.join(', ')}`);
+      } else if (topUp.reason) {
+        // The security gap PERSISTS here, so it does not get the same quiet bullet as the
+        // all-clear. upgrade.js never iterates summary.notes, so this log line is the only
+        // channel that reaches the operator's terminal.
+        summary.skippedFiles.push('settings.json');
+        summary.settingsDenyUncheckable = topUp.reason;
+        summary.notes.push(`.claude/settings.json could not be checked for missing deny rules — ${topUp.reason}. It was left exactly as it is, so if it predates task 1003966 its local agent can still read keys and session tokens; compare its permissions.deny against the starter by hand, or fix the file and upgrade again.`);
+        log(`  ! .claude/settings.json could NOT be checked for missing deny rules — ${topUp.reason}. Left untouched; its deny half may still be missing.`);
+      } else if (!twins.added.length) {
+        summary.skippedFiles.push('settings.json');
+        log('  • .claude/settings.json already present — left untouched (the instance owns it; it already carries every credential deny rule. The starter\'s shelf rules are not offered here — they guard a workflow, not a secret, and are starter-only: task 1004158).');
+      }
+    } else {
+      if (!dryRun) {
+        fs.mkdirSync(destClaude, { recursive: true });
+        fs.writeFileSync(settingsDest, renderStarterSettings(toBranding));
+      }
+      addWritten('.claude/settings.json');
+      summary.settings = true;
+      summary.notes.push(`.claude/settings.json written from the starter — ${STARTER_COMMANDS.length} blessed command(s) for each of ${STARTER_SHELL_TOOLS.join(' + ')}, permissions only.`);
+      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (starter: ${STARTER_COMMANDS.length} blessed commands × ${STARTER_SHELL_TOOLS.length} shell tools, no hooks)`);
+    }
+  }
+
+  // 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, onFile: recordUnder('.claude/hooks'),
+  });
+  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/ (founder identity rebranded)${left((hooksRes.skipped || []).length)}`);
+    summary.notes.push('hooks: founder origin/config-dir rebranded to this instance; their internal `require(scripts/bongos/…)` 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/bongos/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, onFile: recordUnder('.claude/scheduled-tasks'),
+  });
+  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).
+  //    One narrow exception (task 1004621): the starter's OWN sentences that told the assistant to
+  //    type a bare `bongos …` — not on PATH in a project — are swapped for their `npx bongos …` form
+  //    where they still read exactly as the starter wrote them (refreshStarterCliLines). Not in
+  //    adopt mode, which never touches what the owner already had.
+  const claudeMdPath = path.join(instanceDir, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    let refreshed = { changed: 0 };
+    if (overwrite) {
+      try { refreshed = refreshStarterCliLines(fs.readFileSync(claudeMdPath, 'utf8')); } catch { /* unreadable: leave it, as before */ }
+    }
+    if (refreshed.changed) {
+      if (!dryRun) fs.writeFileSync(claudeMdPath, refreshed.text);
+      // Real run only, like the settings top-up: it preserves content, so the upgrade pre-flight's
+      // "materialize overwrites this anyway" waiver must not cover an owner's uncommitted edit.
+      if (!dryRun) addWritten('CLAUDE.md');
+      summary.claudeMdCliLines = refreshed.changed;
+      summary.notes.push(`CLAUDE.md kept as the instance's own, except ${refreshed.changed} unedited starter sentence(s) now say \`npx bongos …\` — the CLI is not on PATH in a project, so a bare \`bongos\` failed with command not found.`);
+      log(`  ${dryRun ? '[dry-run] would update' : '✓ updated'} ${refreshed.changed} unedited starter sentence(s) in CLAUDE.md to \`npx bongos …\` (everything else untouched)`);
+    } else {
+      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));
+    }
+    addWritten('CLAUDE.md');
+    summary.claudeMd = true;
+    log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} CLAUDE.md (starter, brand-substituted for this instance)`);
+  }
+  return summary;
+}
+
+// materializeWillRewrite — the instance-relative paths a materialize WOULD rewrite here, changing
+// nothing. `bongos upgrade` asks before it starts, to decide which dirty paths its clean-tree
+// pre-flight may waive.
+//
+// THE WEDGE THIS EXISTS FOR (task 1004122). The upgrade's materialize step rewrites `.claude/`
+// from the new core on EVERY bump, so after an upgrade that did not commit it — one from before
+// task 1003957, or any run without --commit-pin — the instance carries ~40 modified
+// `.claude/skills/*` files that nobody edited. upgrade.js's clean-tree pre-flight then read them
+// as a human's uncommitted work and refused, so the instance took exactly one upgrade and stuck:
+// `test4` (instance 11) failed its Deploy-page upgrade this way, and provision-core-upgrade.js
+// passes --commit-pin but NOT --force, so the button stayed dead until someone committed by hand.
+//
+// Asking materializeClaude what it WOULD write is a real provenance answer, not a path
+// allow-list: the set is derived from the core actually installed here, and every path in it
+// is one the materialize step overwrites unconditionally a few seconds later. Whatever those files hold right
+// now is discarded either way, so refusing on them protects nothing and stops every future
+// update. A path materialize would NOT touch — an owner's own skill, a dirty migration, a
+// half-finished edit — is absent from the set and still halts the bump, which is the whole
+// safety property. Under --commit-pin the same paths come back from that step as persistPin's
+// artifactPaths and are committed, so the tree ends clean and the next upgrade needs none of this.
+//
+// Probed against the core on disk NOW, not the target: the target is not installed yet, and the
+// two ship the same `.claude/` surface. Fail-soft — a materialize that throws (no core
+// installed, an unreadable tree) returns nothing and the pre-flight is as strict as it ever was.
+function materializeWillRewrite({ instanceDir, coreRoot, materialize = materializeClaude }, err = console.error) {
+  try {
+    const root = coreRoot || path.join(instanceDir, 'node_modules', CORE_PACKAGE_NAMES[0]);
+    const sum = materialize({ coreRoot: root, instanceDir, dryRun: true, log: () => {} });
+    return (sum && Array.isArray(sum.writtenPaths)) ? sum.writtenPaths : [];
+  } catch (e) {
+    err(`  ! could not preview the .claude/ materialization (${e && e.message ? e.message : e}) — pre-flight will treat every dirty path as a human's work.`);
+    return [];
+  }
+}
+
+// ---- the dev checkout: module-owned skills materialised INTO the core (task 1003330, ADR 0224) ----
+// materializeClaude's self-copy guard is right for init/upgrade (instance == core is a no-op),
+// but Claude Code discovers only .claude/skills/ at the project root, so a builder working IN
+// the core checkout never sees modules/<key>/skills/. This lands every ENABLED module's skills
+// there as UNTRACKED, self-ignored dirs: verbatim copies (no bongosify — the checkout runs
+// `node scripts/bongos/…`), a generated .claude/skills/.module-skills.json manifest naming what
+// was materialised and from where, and a generated .claude/skills/.gitignore covering the
+// manifest, itself and every materialised dir, so `git status` shows nothing new and nothing
+// can be committed by accident. The same vendoredSkillGate + SKILL_NAME_RE apply; a name the
+// core's own tracked .claude/skills/ carries is left to the core. Idempotent: every run first
+// removes what the last manifest named (so a skill a module stopped declaring does not
+// linger), then lands the current set; `clean` stops after the removal.
+// Is `root` the core CHECKOUT — a workbench a builder edits — rather than the core
+// package installed under a scaffolded instance's node_modules? Only a checkout's own
+// .claude/skills/ is the directory Claude Code reads for that project, so only there
+// does materialising the module-owned skills put them in front of anyone; an instance
+// already received them at ITS root from `bongos init`, and a second copy under
+// node_modules/@bongos/core would be invisible (task 1003486). Fail-soft by
+// construction: an unreadable package.json answers "not the core checkout", which is
+// the conservative no-op rather than a copy into a tree we could not identify.
+function isCoreCheckoutRoot(root) {
+  try {
+    const abs = path.resolve(root);
+    if (abs.split(/[\\/]+/).includes('node_modules')) return false;
+    return isCorePackageName(JSON.parse(fs.readFileSync(path.join(abs, 'package.json'), 'utf8')).name);
+  } catch (_) {
+    return false;
+  }
+}
+
+const MODULE_SKILLS_MANIFEST = '.module-skills.json';
+// The INSTANCE-side provenance record, deliberately a DIFFERENT filename from the
+// core's (task 1003632). They are different artifacts: MODULE_SKILLS_MANIFEST lists
+// the untracked copies materializeModuleSkillsIntoCore made inside a core CHECKOUT,
+// and is asserted never to travel to an instance; this one lists what materializeClaude
+// landed INTO an instance, and is what step 1c withdraws against. Sharing one name made
+// the instance's own record look like a core dotfile that had leaked across the boundary.
+const INSTANCE_SKILLS_MANIFEST = '.instance-skills.json';
+function readSkillsManifest(skillsDir, file) {
+  const m = readJsonSafe(path.join(skillsDir, file));
+  return m && m.skills && typeof m.skills === 'object' ? m : { skills: {} };
+}
+function readModuleSkillsManifest(skillsDir) {
+  return readSkillsManifest(skillsDir, MODULE_SKILLS_MANIFEST);
+}
+function readInstanceSkillsManifest(skillsDir) {
+  return readSkillsManifest(skillsDir, INSTANCE_SKILLS_MANIFEST);
+}
+function materializeModuleSkillsIntoCore({ coreRoot, dryRun = false, clean = false, log = () => {} }) {
+  const skillsDir = path.join(coreRoot, '.claude', 'skills');
+  const summary = { materialized: [], removed: [], refused: [], excluded: [], keptCore: [], files: 0, notes: [] };
+  const previous = readModuleSkillsManifest(skillsDir);
+  // A dir git tracks is the core's, whatever an older manifest said (a core skill can take
+  // over a name a module once owned); it is never removed or overwritten here.
+  const tracked = (name) => { try { return spawnSync('git', ['-C', coreRoot, 'ls-files', '--error-unmatch', '--', `.claude/skills/${name}`], { encoding: 'utf8' }).status === 0; } catch { return false; } };
+  for (const name of Object.keys(previous.skills)) {
+    const dir = path.join(skillsDir, name);
+    if (!SKILL_NAME_RE.test(name) || !fs.existsSync(dir)) continue;
+    if (tracked(name)) { summary.keptCore.push(name); summary.notes.push(`"${name}" is tracked by git now — the last manifest's copy was not removed; the core's dir is kept.`); continue; }
+    if (!dryRun) fs.rmSync(dir, { recursive: true, force: true });
+    summary.removed.push(name);
+  }
+  if (clean) {
+    for (const f of [MODULE_SKILLS_MANIFEST, '.gitignore']) { const p = path.join(skillsDir, f); if (fs.existsSync(p) && !dryRun) fs.rmSync(p); }
+    log(`  ${dryRun ? '[dry-run] would remove' : '✓ removed'} ${summary.removed.length} materialised module skill dir(s), the manifest and .claude/skills/.gitignore`);
+    return summary;
+  }
+  const roster = moduleSkillRoster({ coreRoot, instanceDir: coreRoot });
+  const sources = moduleSkillSources({ roster });
+  for (const r of sources.refused) { summary.refused.push(`${r.name} (${r.module}): ${r.reason}`); log(`  ✗ refused module skill "${r.name}" (${r.module}): ${r.reason}`); }
+  const manifest = { _doc: 'GENERATED by `node scripts/bongos/claude-materialize.js --module-skills-only` (task 1003330, ADR 0224): the module-owned skills materialised into this core checkout as UNTRACKED copies so Claude Code sees them here. Every dir named below is ignored by the sibling .gitignore and removed by --clean; edit the module\'s skills/<name>/ source, never these copies, and re-run to refresh.', skills: {} };
+  for (const s of sources) {
+    if (!s.enabled) { summary.excluded.push(s.name); continue; }
+    const dest = path.join(skillsDir, s.name);
+    if (fs.existsSync(dest) && (!Object.prototype.hasOwnProperty.call(previous.skills, s.name) || tracked(s.name))) {
+      summary.keptCore.push(s.name);
+      summary.notes.push(`"${s.name}" (${s.module}) already exists under .claude/skills/ and is not a materialised copy — the core's own dir is kept.`);
+      continue;
+    }
+    const r = copyTreeTransformed(s.dir, dest, { dryRun, overwrite: true, transform: (t) => t });
+    summary.files += r.files;
+    summary.materialized.push(s.name);
+    manifest.skills[s.name] = { module: s.module, source: path.relative(coreRoot, s.dir).split(path.sep).join('/'), vendored: s.vendored, files: r.files };
+  }
+  const names = Object.keys(manifest.skills).sort();
+  manifest.skills = Object.fromEntries(names.map((n) => [n, manifest.skills[n]]));
+  const ignore = ['# GENERATED by scripts/bongos/claude-materialize.js --module-skills-only (task 1003330): the module-owned skills', '# materialised into this checkout are untracked copies; this file and the manifest ignore themselves. Never commit these.', '/.gitignore', `/${MODULE_SKILLS_MANIFEST}`, ...names.map((n) => `/${n}/`)].join('\n') + '\n';
+  if (!dryRun) {
+    fs.mkdirSync(skillsDir, { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, MODULE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
+    fs.writeFileSync(path.join(skillsDir, '.gitignore'), ignore);
+  }
+  log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${summary.materialized.length} module-owned skill(s) (${summary.files} file(s)) → .claude/skills/ as untracked copies: ${names.join(', ') || 'none'}`);
+  return summary;
+}
+
+// The CLI entry is the dev-checkout path only; init/upgrade call materializeClaude directly.
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  if (!argv.includes('--module-skills-only') || argv.includes('--help')) {
+    process.stderr.write('usage: node scripts/bongos/claude-materialize.js --module-skills-only [--dry-run] [--clean]\n  Lands every enabled module\'s skills (modules/<key>/skills/<name>/) into THIS checkout\'s .claude/skills/ as untracked,\n  self-ignored copies so Claude Code sees them here (task 1003330). --clean removes them. The library behind bongos init / upgrade otherwise.\n');
+    process.exit(argv.includes('--help') ? 0 : 2);
+  }
+  const s = materializeModuleSkillsIntoCore({ coreRoot: path.resolve(__dirname, '..', '..'), dryRun: argv.includes('--dry-run'), clean: argv.includes('--clean'), log: (l) => process.stdout.write(l + '\n') });
+  for (const n of s.notes) process.stdout.write(`  • ${n}\n`);
+  process.stdout.write(`module skills → .claude/skills/: ${s.materialized.length} materialised (${s.files} file(s)), ${s.removed.length} refreshed or removed, ${s.excluded.length} excluded (module off), ${s.keptCore.length} kept as the core's own, ${s.refused.length} refused\n`);
+  process.exit(s.refused.length ? 1 : 0);
+}
+
+module.exports = { skillDescription, descriptionDigest, isRetiredCoreCopy, readRetiredCoreSkills, RETIRED_CORE_SKILLS_FILE, scriptToVerb, bongosify, PROJECT_CLI, topUpNpxAllowTwins, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };