create-claude-cabinet 0.49.0 → 0.51.0

package/lib/output-register.js

@@ -0,0 +1,629 @@
+/**
+ * output-register.js — install the Cabinet Register output style (user-level)
+ * and report where the register stands (act:9a0af01a).
+ *
+ * WHY AN OUTPUT STYLE. Plain-English, concept-first communication is already
+ * written down in three places that agree with each other (~/.claude/CLAUDE.md
+ * "Communication Style", .claude/rules/plain-english-decisions.md,
+ * skill-output-conventions.md §9). What none of them has is RE-ASSERTION: each
+ * is stated once, then competes with everything else in a growing context. An
+ * output style lands the contract in the SYSTEM PROMPT — re-sent in full on
+ * every request, never decays, unaffected by compaction. That is the strongest
+ * placement the platform offers. It is still prompt context, not a hook: this
+ * is not a move up the compliance stack and does not claim to be.
+ *
+ * THE FOOTGUN THIS FILE EXISTS TO GUARD (§4 of the plan).
+ * `keep-coding-instructions` was added in Claude Code v2.0.37. Below that
+ * version the field is SILENTLY IGNORED, its `false` default applies, and
+ * Claude Code's own software-engineering instructions are STRIPPED from the
+ * system prompt with no error. Verified in the shipped 2.1.209 binary:
+ *
+ *     p = TEt(o["keep-coding-instructions"])                 // kebab, raw read
+ *     function TEt(e){ if(e===!0||e==="true")return!0;
+ *                      if(e===!1||e==="false")return!1; return }   // absent → undefined
+ *     c===null || c.keepCodingInstructions===!0 ? Qh_() : null     // strict === true
+ *
+ * A test that the field is PRESENT IN THE FILE passes on every version ever
+ * shipped and detects this never — it guards the author forgetting the field,
+ * not the platform refusing to honor it. Only a `claude --version` check can.
+ * Hence versionGate(), and hence validateStyleSource() runs against the
+ * INSTALLED copy in ~/.claude/output-styles/ — the file Claude Code actually
+ * reads — not just the template.
+ *
+ * OWNERSHIP: seed-if-absent, never overwrite, validate loudly.
+ * A prose register is the most edit-inviting artifact CC ships — the operator
+ * WILL hand-tune it. The two sibling engines are opposites and neither is right
+ * here: mux-setup compares a cached manifest hash (a hand edit is never
+ * re-examined, so a footgun persists forever), watchtower-setup compares the
+ * dest's on-disk bytes and reconverges (hand edits reverted every reinstall).
+ * We take the third path CC already built — isProjectOwnedSeed()'s semantics
+ * (lib/copy.js, act:2001bf54): seed if absent, NEVER overwrite, omit from the
+ * project manifest — then close the gap that opens by validating the installed
+ * copy on every install and FAILING LOUD rather than silently rewriting it.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { sha256, compareVersions, readGlobalManifest, writeGlobalManifest, globalManifestPath } = require('./installer-gate');
+
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'templates', 'output-styles');
+
+/**
+ * The style's identity. Claude Code keys a custom style by its FRONTMATTER
+ * `name`, verbatim — the filename is only a fallback when `name` is absent.
+ * Verified in 2.1.209:
+ *   c = basename(n).replace(/\.md$/,""),
+ *   u = (o.name != null ? String(o.name) : void 0) || c
+ * ...then folded into a map keyed by `.name` and selected by exact lookup
+ * (`e[settings.outputStyle] ?? null`). So THIS STRING is what must land in the
+ * `outputStyle` settings key, and it must stay in step with the frontmatter of
+ * templates/output-styles/cabinet-register.md (asserted by the test suite).
+ */
+const REGISTER_STYLE_NAME = 'Cabinet Register';
+
+/**
+ * The floor below which `keep-coding-instructions` does not exist. Changelog:
+ * v1.0.81 released output styles · v2.0.30 DEPRECATED them · v2.0.32
+ * un-deprecated on community feedback · v2.0.37 ADDED the field · v2.1.94 added
+ * it for plugin styles. That leaves a ~250-version window where output styles
+ * work and the field is silently ignored — the window this gate closes.
+ */
+const MIN_CLAUDE_VERSION = '2.0.37';
+
+/**
+ * Anthropic's built-in style roster, so we never ship a name that collides
+ * (a collision would make which-style-wins depend on load order).
+ * SNAPSHOT, verified against 2.1.209's registry:
+ *   Lle = { default: null, Proactive: {...}, Explanatory: {...}, Learning: {...} }
+ * This roster is Anthropic's and it GROWS — Proactive post-dates the release
+ * that introduced output styles, and the published schema is already stale
+ * against the binary. A future built-in named "Cabinet Register" is
+ * vanishingly unlikely, but if this list goes stale the failure is a silent
+ * shadow, so re-verify it against the binary rather than trusting the docs.
+ */
+const BUILT_IN_STYLE_NAMES = ['default', 'Proactive', 'Explanatory', 'Learning'];
+
+/** Where Claude Code reads user-level custom styles from. */
+function userStyleDir(home = os.homedir()) {
+  return path.join(home, '.claude', 'output-styles');
+}
+
+/**
+ * The shipped style set, discovered by GLOB — never hand-enumerated.
+ * The manifest-integrity orphan test only scans templates/skills/, so a style
+ * added under templates/output-styles/ but missing from a hardcoded list would
+ * ship to nobody with every test green. Globbing makes the engine's managed set
+ * equal to what is on disk by construction.
+ */
+function styleTemplates(templateDir = TEMPLATE_DIR) {
+  if (!fs.existsSync(templateDir)) return [];
+  return fs
+    .readdirSync(templateDir)
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+    .map((f) => ({ file: f, src: path.join(templateDir, f) }));
+}
+
+/**
+ * Parse the leading `---` frontmatter block. Deliberately minimal — the style
+ * frontmatter is flat `key: value` scalars and CC ships no YAML dependency
+ * (the two-dependency footprint is intentional). Returns
+ * `{ ok, frontmatter, error }`; a file with no frontmatter block is `ok:false`.
+ */
+function parseFrontmatter(text) {
+  const src = String(text || '');
+  if (!/^---\r?\n/.test(src)) return { ok: false, frontmatter: {}, error: 'no frontmatter block' };
+  const end = src.indexOf('\n---', 3);
+  if (end === -1) return { ok: false, frontmatter: {}, error: 'unterminated frontmatter block' };
+  const body = src.slice(4, end);
+  const frontmatter = {};
+  for (const rawLine of body.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    frontmatter[key] = value;
+  }
+  return { ok: true, frontmatter, error: null };
+}
+
+/**
+ * Claude Code's own coercion for `keep-coding-instructions`, mirrored exactly
+ * (function TEt in 2.1.209): true/"true" → true, false/"false" → false,
+ * ANYTHING ELSE → undefined, and the gate then requires a strict `=== true`.
+ * So `keep-coding-instructions: yes` — valid YAML truth, wrong here — reads as
+ * undefined and strips the coding instructions. We reject anything that does
+ * not coerce to exactly true.
+ */
+function coerceKeepCoding(value) {
+  if (value === true || value === 'true') return true;
+  if (value === false || value === 'false') return false;
+  return undefined;
+}
+
+/**
+ * Validate one style file's SOURCE TEXT against everything that can silently
+ * break it. Used for BOTH the template and the installed copy — the installed
+ * copy is the one Claude Code reads, and validating only the template would be
+ * checking the one file that cannot cause the failure.
+ *
+ * @returns {{ ok: boolean, name: string|null, problems: string[] }}
+ */
+function validateStyleSource(text, { label = 'style' } = {}) {
+  const problems = [];
+  const { ok, frontmatter, error } = parseFrontmatter(text);
+  if (!ok) {
+    return { ok: false, name: null, problems: [`${label}: ${error}`] };
+  }
+  const name = typeof frontmatter.name === 'string' && frontmatter.name.trim() ? frontmatter.name.trim() : null;
+  if (!name) problems.push(`${label}: frontmatter is missing a \`name\` (the key Claude Code selects the style by)`);
+  if (!frontmatter.description || !String(frontmatter.description).trim()) {
+    problems.push(`${label}: frontmatter is missing a \`description\` (shown in the /config picker)`);
+  }
+  if (coerceKeepCoding(frontmatter['keep-coding-instructions']) !== true) {
+    problems.push(
+      `${label}: \`keep-coding-instructions: true\` is missing or not literally true — ` +
+        `without it Claude Code STRIPS its software-engineering instructions from the system prompt`
+    );
+  }
+  if (name && BUILT_IN_STYLE_NAMES.includes(name)) {
+    problems.push(`${label}: name "${name}" collides with a built-in output style (${BUILT_IN_STYLE_NAMES.join(', ')})`);
+  }
+  return { ok: problems.length === 0, name, problems };
+}
+
+// ── The version gate ────────────────────────────────────────────────────────
+
+/**
+ * Read the installed Claude Code version. `exec` is injectable so tests can
+ * drive every arm without a real binary.
+ * @returns {{ status: 'ok'|'absent'|'unparseable', version: string|null, raw: string|null }}
+ */
+function detectClaudeVersion({ exec } = {}) {
+  const run =
+    exec ||
+    (() =>
+      execFileSync('claude', ['--version'], {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }));
+  let raw;
+  try {
+    raw = run();
+  } catch {
+    // No binary on PATH, non-zero exit, timeout — absence is NOT an old
+    // version, so this fails OPEN (see versionGate).
+    return { status: 'absent', version: null, raw: null };
+  }
+  const m = /(\d+\.\d+\.\d+)/.exec(String(raw || ''));
+  if (!m) return { status: 'unparseable', version: null, raw: String(raw || '').trim() };
+  return { status: 'ok', version: m[1], raw: String(raw).trim() };
+}
+
+/**
+ * Decide whether it is safe to install the style on this Claude Code.
+ *
+ * Below MIN_CLAUDE_VERSION we REFUSE: installing here would work — the style
+ * loads fine — and silently strip CC's software-engineering instructions. The
+ * failure is invisible from inside the file, which is why refusing is the only
+ * honest option.
+ *
+ * An ABSENT or UNPARSEABLE version fails OPEN: absence is not evidence of an
+ * old version, and refusing to install because we couldn't find a binary would
+ * break every CI/container install for a hazard we have no reason to believe
+ * exists there.
+ *
+ * @returns {{ allowed: boolean, reason: string, version: string|null, status: string }}
+ */
+function versionGate(detected) {
+  const { status, version } = detected;
+  if (status === 'absent') {
+    return {
+      allowed: true,
+      status,
+      version: null,
+      reason: `could not run \`claude --version\` — installing anyway (absence is not an old version). ` +
+        `If this Claude Code is older than v${MIN_CLAUDE_VERSION}, \`keep-coding-instructions\` is ignored there.`,
+    };
+  }
+  if (status === 'unparseable') {
+    return {
+      allowed: true,
+      status,
+      version: null,
+      reason: `could not parse a version out of \`claude --version\` — installing anyway (fail-open).`,
+    };
+  }
+  if (compareVersions(version, MIN_CLAUDE_VERSION) < 0) {
+    return {
+      allowed: false,
+      status,
+      version,
+      reason:
+        `Claude Code v${version} is older than v${MIN_CLAUDE_VERSION}, which is when ` +
+        `\`keep-coding-instructions\` was added. On this version the field is silently ignored, its ` +
+        `\`false\` default applies, and Claude Code's software-engineering instructions are STRIPPED ` +
+        `from the system prompt with no error. Upgrade Claude Code, then re-run the installer.`,
+    };
+  }
+  return { allowed: true, status, version, reason: `Claude Code v${version} honors \`keep-coding-instructions\`.` };
+}
+
+// ── The enumerator ──────────────────────────────────────────────────────────
+
+/**
+ * The settings layers we can actually READ, low → high precedence. Verified in
+ * 2.1.209, whose own comment on the precedence array reads "Ordered low-to-high
+ * priority — later entries override earlier ones":
+ *   ["userSettings","projectSettings","localSettings","flagSettings","policySettings"]
+ * The last two are deliberately absent here — see resolveRegisterLevel.
+ */
+const SETTINGS_LAYERS = [
+  { layer: 'userSettings', label: 'User settings', rel: null },
+  { layer: 'projectSettings', label: 'Project settings', rel: path.join('.claude', 'settings.json') },
+  { layer: 'localSettings', label: 'Local settings', rel: path.join('.claude', 'settings.local.json') },
+];
+
+function layerPaths({ projectDir = process.cwd(), home = os.homedir() } = {}) {
+  return SETTINGS_LAYERS.map((l) => ({
+    ...l,
+    path: l.rel === null ? path.join(home, '.claude', 'settings.json') : path.join(projectDir, l.rel),
+  }));
+}
+
+/**
+ * Read one settings layer's `outputStyle`, distinguishing every way it can be
+ * non-informative. "Unparseable" must NEVER read as "absent" — that would turn
+ * a broken settings file into a confident "the register is off".
+ *
+ * state ∈ 'absent'      — no such file
+ *       | 'unparseable' — file exists, JSON.parse threw
+ *       | 'not-an-object' — parsed to [] / null / a scalar
+ *       | 'no-key'      — parsed fine, no outputStyle key
+ *       | 'null'        — outputStyle: null
+ *       | 'empty'       — outputStyle: ""
+ *       | 'non-string'  — outputStyle: 7 / {} / []
+ *       | 'set'         — outputStyle names a style
+ */
+function readLayerOutputStyle(filePath) {
+  if (!fs.existsSync(filePath)) return { state: 'absent', value: null };
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return { state: 'unparseable', value: null };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { state: 'not-an-object', value: null };
+  }
+  if (!Object.prototype.hasOwnProperty.call(parsed, 'outputStyle')) return { state: 'no-key', value: null };
+  const v = parsed.outputStyle;
+  if (v === null) return { state: 'null', value: null };
+  if (typeof v !== 'string') return { state: 'non-string', value: v };
+  if (v.trim() === '') return { state: 'empty', value: v };
+  return { state: 'set', value: v };
+}
+
+/**
+ * Resolve what the NEXT session's output style will be, as best as a file
+ * reader can know it.
+ *
+ * THIS ENUMERATES; IT DOES NOT ADJUDICATE. Three layers are invisible to it:
+ * a plugin's `force-for-plugin` (which overrides `outputStyle` entirely), CLI
+ * `--settings`, and enterprise managed policy — all of which outrank everything
+ * below. A tool rendering a verdict it cannot back is exactly the fact-shaped
+ * guess verify-before-asserting.md exists to prevent, shipped as a feature. So
+ * the contract is honest about its own blind spots and points at `/status` and
+ * `/context` for ground truth.
+ *
+ * THREE-VALUED, deliberately: a foreign style reports its literal name with
+ * `ours:false`, which is NOT the same as `off`. Collapsing "Explanatory" into
+ * "off" is what would let a never-clobber guard clobber it.
+ *
+ * @returns {{ level: string, ours: boolean, source: string|null, uncertain: boolean, sources: object[] }}
+ *   level: the style name, or 'off' (no layer names one), or 'unknown' (a layer
+ *   we could not read sits ABOVE whatever we could).
+ */
+function resolveRegisterLevel({ projectDir = process.cwd(), home = os.homedir() } = {}) {
+  const sources = [];
+  let winner = null;
+  let unreadableAboveWinner = false;
+
+  for (const l of layerPaths({ projectDir, home })) {
+    const read = readLayerOutputStyle(l.path);
+    sources.push({ layer: l.layer, label: l.label, path: l.path, state: read.state, value: read.value });
+    if (read.state === 'set') {
+      winner = { layer: l.layer, value: read.value };
+      unreadableAboveWinner = false; // this layer outranks anything unreadable below it
+    } else if (read.state === 'unparseable' || read.state === 'not-an-object' || read.state === 'non-string') {
+      unreadableAboveWinner = true;
+    }
+  }
+
+  if (unreadableAboveWinner) {
+    return { level: 'unknown', ours: false, source: null, uncertain: true, sources };
+  }
+  if (!winner) {
+    return { level: 'off', ours: false, source: null, uncertain: false, sources };
+  }
+  return {
+    level: winner.value,
+    ours: winner.value === REGISTER_STYLE_NAME,
+    source: winner.layer,
+    uncertain: false,
+    sources,
+  };
+}
+
+const STATE_PROSE = {
+  absent: 'no such file',
+  unparseable: 'FILE EXISTS BUT IS NOT VALID JSON — cannot tell what it says',
+  'not-an-object': 'FILE EXISTS BUT IS NOT A JSON OBJECT — cannot tell what it says',
+  'no-key': 'no outputStyle key',
+  null: 'outputStyle: null (present, names nothing)',
+  empty: 'outputStyle: "" (present, names nothing)',
+  'non-string': 'outputStyle is not a string — Claude Code will not resolve it',
+};
+
+/**
+ * Render `--register`: every settings file that mentions outputStyle, what each
+ * says, the layers we could NOT consult, and where the real answer lives.
+ */
+function renderRegisterReport({ projectDir = process.cwd(), home = os.homedir() } = {}) {
+  const lines = [];
+  const res = resolveRegisterLevel({ projectDir, home });
+
+  if (res.level === 'off') {
+    lines.push('  Register: OFF — no settings file names an output style.');
+  } else if (res.level === 'unknown') {
+    lines.push('  Register: UNKNOWN — a settings file could not be read (see below).');
+  } else if (res.ours) {
+    lines.push(`  Register: ON — "${res.level}" (set in ${res.source}).`);
+  } else {
+    lines.push(`  Register: a DIFFERENT style is active — "${res.level}" (set in ${res.source}). Not ours; left alone.`);
+  }
+
+  lines.push('');
+  lines.push('  What each settings file says (low → high precedence):');
+  for (const s of res.sources) {
+    const said = s.state === 'set' ? `outputStyle: "${s.value}"` : STATE_PROSE[s.state] || s.state;
+    lines.push(`    ${s.label.padEnd(16)} ${said}`);
+    lines.push(`    ${''.padEnd(16)} ${s.path}`);
+  }
+
+  const styleDir = userStyleDir(home);
+  const installed = fs.existsSync(styleDir) ? fs.readdirSync(styleDir).filter((f) => f.endsWith('.md')) : [];
+  lines.push('');
+  lines.push(`  Installed styles in ${styleDir}: ${installed.length ? installed.join(', ') : '(none)'}`);
+
+  lines.push('');
+  lines.push('  This is an ENUMERATOR, not a verdict. It cannot see:');
+  lines.push('    - a plugin\'s force-for-plugin style, which overrides outputStyle entirely');
+  lines.push('    - command-line --settings, which outranks every file above');
+  lines.push('    - enterprise managed policy, which outranks everything');
+  lines.push('  For ground truth: `/status` shows the active settings sources, and');
+  lines.push('  `/context` shows the system prompt — the only place that proves the style landed.');
+  lines.push('');
+  lines.push('  Note: this reports what the NEXT session will start with. Output style is');
+  lines.push('  fixed at session start (for prompt caching); changing it mid-session does');
+  lines.push('  nothing until /clear or a new session.');
+
+  return lines;
+}
+
+// ── The installer ───────────────────────────────────────────────────────────
+
+/**
+ * Seed `outputStyle` into the PROJECT's .claude/settings.json.
+ *
+ * Project-level, not user-level, on purpose: this module is selected per
+ * project, so turning the register on portfolio-wide as a side effect of a
+ * single project's install would be a surprise. A project install changes the
+ * project. (The operator's $HOME CC install is the global layer — installing
+ * there sets it everywhere, which is exactly what that layer is for.)
+ *
+ * Seed-if-absent, never clobber: an incumbent style — ours or foreign, at ANY
+ * layer — is reported and left alone.
+ *
+ * Atomic + read-back: re-read immediately before writing and verify after, so a
+ * concurrent writer (healUserSettings and mergeSettings are both non-atomic
+ * read-modify-writes elsewhere in this install) can't leave us announcing a
+ * write that didn't land.
+ */
+function seedOutputStyleSetting({ projectDir, dryRun = false, home = os.homedir(), results }) {
+  const res = resolveRegisterLevel({ projectDir, home });
+
+  if (res.level === 'unknown') {
+    results.push(`  ⚠ Not setting outputStyle: a settings file is unreadable, so the incumbent is unknown.`);
+    results.push(`    Run \`npx create-claude-cabinet --register\` to see which file.`);
+    return { status: 'skipped-uncertain' };
+  }
+  if (res.ours) {
+    results.push(`  ✓ Register already active — "${REGISTER_STYLE_NAME}" (set in ${res.source}).`);
+    return { status: 'already-set' };
+  }
+  if (res.level !== 'off') {
+    results.push(`  ⚠ Leaving the existing output style alone: "${res.level}" is set in ${res.source}.`);
+    results.push(`    Only one style can be active. To switch, set outputStyle to "${REGISTER_STYLE_NAME}" there, or use /config.`);
+    return { status: 'incumbent' };
+  }
+
+  const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+  if (dryRun) {
+    results.push(`  [dry-run] would set outputStyle: "${REGISTER_STYLE_NAME}" in ${settingsPath}`);
+    return { status: 'would-set' };
+  }
+
+  // Read immediately before writing — not from the resolve above — so a
+  // concurrent writer's changes are preserved rather than reverted.
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) settings = parsed;
+    } catch {
+      results.push(`  ⚠ ${settingsPath} is not valid JSON — not touching it. Set outputStyle by hand or via /config.`);
+      return { status: 'skipped-unparseable' };
+    }
+  }
+  settings.outputStyle = REGISTER_STYLE_NAME;
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  const tmp = settingsPath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+  fs.renameSync(tmp, settingsPath);
+
+  // Verify the write, don't announce it from the call's success.
+  const after = readLayerOutputStyle(settingsPath);
+  if (after.state !== 'set' || after.value !== REGISTER_STYLE_NAME) {
+    results.push(`  ⚠ Wrote outputStyle to ${settingsPath} but reading it back did not confirm it (${after.state}).`);
+    return { status: 'write-unconfirmed' };
+  }
+  results.push(`  ✓ Set outputStyle: "${REGISTER_STYLE_NAME}" in ${path.relative(projectDir, settingsPath)} (takes effect next session).`);
+  return { status: 'set' };
+}
+
+/**
+ * postInstall handler for the `output-register` module.
+ *
+ * @param {object} opts
+ * @param {boolean} [opts.dryRun]
+ * @param {string}  [opts.projectDir]
+ * @param {string}  [opts.home]          — injectable for tests
+ * @param {Function} [opts.exec]         — injectable `claude --version` runner
+ * @returns {{ results: string[], status: 'refused'|'installed'|'unchanged'|'failed' }}
+ */
+function setupOutputRegister(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const projectDir = opts.projectDir || process.cwd();
+  const home = opts.home || os.homedir();
+  const results = opts.results || [];
+
+  results.push('Installing the Cabinet Register output style');
+
+  // 1. The version gate — the only guard that can catch the real hazard.
+  const detected = detectClaudeVersion({ exec: opts.exec });
+  const gate = versionGate(detected);
+  if (!gate.allowed) {
+    results.push(`  ✗ REFUSED: ${gate.reason}`);
+    return { results, status: 'refused' };
+  }
+  results.push(`  ${gate.status === 'ok' ? '✓' : '⚠'} ${gate.reason}`);
+
+  const templates = styleTemplates();
+  if (templates.length === 0) {
+    results.push('  ⚠ No styles found under templates/output-styles/ — nothing to install.');
+    return { results, status: 'failed' };
+  }
+
+  const styleDir = userStyleDir(home);
+  // Resolve the manifest against THIS run's home, not os.homedir() — `home` is
+  // injectable, and a bare readGlobalManifest() would escape the sandbox.
+  const manifestPath = globalManifestPath(home);
+  const manifest = readGlobalManifest(manifestPath);
+  let seeded = 0;
+  let failures = 0;
+
+  for (const t of templates) {
+    const content = fs.readFileSync(t.src, 'utf8');
+
+    // 2. Validate the TEMPLATE (author error — catch it before it ships).
+    const srcCheck = validateStyleSource(content, { label: `template ${t.file}` });
+    if (!srcCheck.ok) {
+      for (const p of srcCheck.problems) results.push(`  ✗ ${p}`);
+      failures++;
+      continue;
+    }
+
+    const dest = path.join(styleDir, t.file);
+
+    if (fs.existsSync(dest)) {
+      // 3. NEVER overwrite — but validate the INSTALLED copy, the one Claude
+      //    Code actually reads. A copy missing the flag fails LOUD rather than
+      //    being silently rewritten (which would eat the operator's tuning).
+      let installedText = '';
+      try {
+        installedText = fs.readFileSync(dest, 'utf8');
+      } catch (err) {
+        results.push(`  ✗ Installed style ${dest} is unreadable: ${err.message}`);
+        failures++;
+        continue;
+      }
+      const check = validateStyleSource(installedText, { label: `installed ${t.file}` });
+      if (!check.ok) {
+        for (const p of check.problems) results.push(`  ✗ ${p}`);
+        results.push(`    Not overwriting your copy — fix ${dest} by hand, or delete it and re-run to reseed.`);
+        failures++;
+        continue;
+      }
+      const edited = sha256(installedText) !== sha256(content);
+      results.push(`  ✓ ${t.file} already installed${edited ? ' (your edits preserved — never overwritten)' : ''}`);
+      continue;
+    }
+
+    // 4. Seed.
+    if (dryRun) {
+      results.push(`  [dry-run] ${t.file} → ${dest}`);
+      seeded++;
+      continue;
+    }
+    fs.mkdirSync(styleDir, { recursive: true });
+    fs.writeFileSync(dest, content);
+
+    // Verify the seed by re-reading the file Claude Code will read.
+    const after = validateStyleSource(fs.readFileSync(dest, 'utf8'), { label: `installed ${t.file}` });
+    if (!after.ok) {
+      for (const p of after.problems) results.push(`  ✗ ${p}`);
+      failures++;
+      continue;
+    }
+    // Global-manifest bookkeeping only: the style is project-owned the moment
+    // it lands, so this records WHAT WE SEEDED (so --reset can find it), never
+    // a claim we may overwrite it.
+    manifest.files[dest] = sha256(content);
+    results.push(`  ✓ Seeded ${t.file} → ${dest}`);
+    seeded++;
+  }
+
+  if (!dryRun && seeded > 0) {
+    manifest.installedAt = new Date().toISOString();
+    writeGlobalManifest(manifest, manifestPath);
+  }
+
+  if (failures > 0) return { results, status: 'failed' };
+
+  // 5. Turn it on — offering, never clobbering.
+  seedOutputStyleSetting({ projectDir, dryRun, home, results });
+
+  results.push('  Check where the register stands any time: npx create-claude-cabinet --register');
+  return { results, status: seeded > 0 ? 'installed' : 'unchanged' };
+}
+
+module.exports = {
+  setupOutputRegister,
+  resolveRegisterLevel,
+  renderRegisterReport,
+  detectClaudeVersion,
+  versionGate,
+  validateStyleSource,
+  parseFrontmatter,
+  coerceKeepCoding,
+  styleTemplates,
+  userStyleDir,
+  seedOutputStyleSetting,
+  readLayerOutputStyle,
+  REGISTER_STYLE_NAME,
+  MIN_CLAUDE_VERSION,
+  BUILT_IN_STYLE_NAMES,
+  SETTINGS_LAYERS,
+  TEMPLATE_DIR,
+};