@thebassclef/lite 0.1.3 → 1.0.1

package/dist/cli.js

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 import { version } from "./index.js";
-import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readFileSync, existsSync } from "node:fs";
-import { isAbsolute, resolve, dirname, join } from "node:path";
+import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readlinkSync, readFileSync, chmodSync, readdirSync, existsSync } from "node:fs";
+import { isAbsolute, resolve, dirname, join, normalize, relative, basename as basename$1 } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { createRequire } from "node:module";
 import { createInterface } from "node:readline/promises";
 import { stdin, stderr, stdout } from "node:process";
 const DEFAULTS$2 = {
@@ -14,7 +13,9 @@ const DEFAULTS$2 = {
   verbose: false,
   allowRoot: false,
   allowAnyDir: false,
-  dir: void 0
+  dir: void 0,
+  yes: false,
+  json: false
 };
 let ArgvError$1 = class ArgvError extends Error {
   name = "ArgvError";
@@ -49,6 +50,16 @@ function parseInitArgs(argv) {
       i += 1;
       continue;
     }
+    if (token === "--yes") {
+      out.yes = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--json") {
+      out.json = true;
+      i += 1;
+      continue;
+    }
     if (token === "--dir") {
       const value = argv[i + 1];
       if (value === void 0 || value.startsWith("--")) {
@@ -117,6 +128,13 @@ function isUnder(child, parent) {
   if (rel === par) return true;
   return rel.startsWith(par + "/");
 }
+function readlinkOrNull(path) {
+  try {
+    return readlinkSync(path);
+  } catch {
+    return null;
+  }
+}
 class WriteError extends Error {
   name = "WriteError";
   kind;
@@ -150,7 +168,12 @@ function writeSafely(path, content, opts = {}) {
     else throw new WriteError("Unknown", `cannot stat ${path}: ${err.code ?? "unknown"}`);
   }
   if (existing === "symlink") {
-    throw new WriteError("SymlinkRefused", `refusing to follow symlink at target path: ${path}`);
+    const target = readlinkOrNull(path);
+    const targetClause = target ? ` (points to: ${target})` : "";
+    throw new WriteError(
+      "SymlinkRefused",
+      `refusing to follow symlink at target path: ${path}${targetClause}. Delete or move the symlink and rerun bassclef init.`
+    );
   }
   if (existing !== "none" && !opts.force) {
     throw new WriteError("AlreadyExists", `file already exists (pass --force to overwrite): ${path}`);
@@ -220,22 +243,6 @@ function hashContent(content) {
   normalized = normalized.replace(/\r\n/g, "\n");
   return createHash("sha256").update(normalized, "utf8").digest("hex");
 }
-const SETTINGS_TEMPLATE_VERSION = "0.0.1";
-function settingsJsonTemplate(pkgVersion) {
-  const value = {
-    $bassclef: {
-      template: "settings.json",
-      template_version: SETTINGS_TEMPLATE_VERSION,
-      generated_by: "@thebassclef/core",
-      generated_by_version: pkgVersion
-    },
-    permissions: {
-      additionalDirectories: []
-    },
-    hooks: {}
-  };
-  return JSON.stringify(value, null, 2) + "\n";
-}
 const SUBSTRATE_CONFIG_TEMPLATE_VERSION = "0.0.1";
 function substrateConfigMdTemplate(pkgVersion) {
   return [
@@ -283,8 +290,10 @@ function substrateConfigMdTemplate(pkgVersion) {
   ].join("\n");
 }
 const MANIFEST_SCHEMA_VERSION = "0.1.0";
+const MANIFEST_SHAPE_VERSION = 2;
 function manifestTemplate(input) {
   const value = {
+    schema_version: MANIFEST_SHAPE_VERSION,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: MANIFEST_SCHEMA_VERSION,
@@ -306,6 +315,15 @@ class ManifestReadError extends Error {
     this.kind = kind;
   }
 }
+function readManifestShapeVersion(targetDir) {
+  try {
+    const parsed = readManifest(targetDir);
+    if (typeof parsed.schema_version === "number") return parsed.schema_version;
+    return null;
+  } catch {
+    return null;
+  }
+}
 function readManifest(targetDir) {
   const path = join(targetDir, MANIFEST_RELATIVE_PATH);
   let raw;
@@ -386,129 +404,347 @@ async function computeConfigHashes(targetDir, paths) {
   }
   return out;
 }
-const SUBSTRATE_ROOT = "substrate";
+class CopyFailure extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+    this.name = "CopyFailure";
+  }
+}
+function resolveHome(opts) {
+  const raw = process.env.HOME;
+  if (raw === void 0 || raw === "") {
+    throw new CopyFailure(
+      "EnvironmentIncomplete",
+      "HOME environment variable is unset. bassclef init needs HOME set to resolve user-scope hook targets. Set HOME to your home directory and rerun."
+    );
+  }
+  if (raw === "/root" && !opts.allowRoot) {
+    throw new CopyFailure(
+      "SudoBypassRefused",
+      "HOME resolves to /root — sudo bypass detected. Routing user-scope hooks to /root breaks the adopter maintenance model. Run bassclef init without sudo, or pass --allow-root if this is intentional."
+    );
+  }
+  const canonical = raw === homedir() ? homedir() : raw;
+  try {
+    return realpathSync(canonical);
+  } catch {
+    return canonical.endsWith("/") ? canonical.slice(0, -1) : canonical;
+  }
+}
+const PREFIX_HOME = "$HOME/";
+const PREFIX_PROJECT = "$CLAUDE_PROJECT_DIR/";
+function classify$1(hook, opts) {
+  const cmd = hook.command;
+  if (typeof cmd !== "string" || cmd.length === 0) {
+    throw new CopyFailure(
+      "UnknownScopePrefix",
+      "Hook command is empty. settings.json must supply a non-empty command string."
+    );
+  }
+  if (cmd.startsWith(PREFIX_HOME)) {
+    return classifyUser(cmd.slice(PREFIX_HOME.length), opts);
+  }
+  if (cmd.startsWith(PREFIX_PROJECT)) {
+    return classifyProject(cmd.slice(PREFIX_PROJECT.length), opts);
+  }
+  throw new CopyFailure(
+    "UnknownScopePrefix",
+    `Hook command "${cmd}" uses an unknown scope prefix. cli 1.0.1 handles "$HOME/..." and "$CLAUDE_PROJECT_DIR/..." only. Upgrade cli to a version that supports this prefix.`
+  );
+}
+function classifyUser(relPath, opts) {
+  const home = resolveHome({ allowRoot: opts.allowRoot });
+  const cleaned = normalizeRel(relPath);
+  const targetPath = normalize(join(home, cleaned));
+  assertContained(targetPath, home, opts.allowRoot ? "/root" : null);
+  return { scope: "user", targetPath };
+}
+function classifyProject(relPath, opts) {
+  const cleaned = normalizeRel(relPath);
+  const targetPath = normalize(join(opts.targetDir, cleaned));
+  assertContained(targetPath, opts.targetDir);
+  return { scope: "project", targetPath };
+}
+function normalizeRel(rel) {
+  return rel.replace(/\/{2,}/g, "/");
+}
+function assertContained(target, root, altRoot) {
+  const resolvedTarget = resolve(target);
+  const resolvedRoot = resolve(root);
+  if (resolvedTarget === resolvedRoot) return;
+  if (resolvedTarget.startsWith(resolvedRoot + "/")) return;
+  if (altRoot) {
+    const resolvedAlt = resolve(altRoot);
+    if (resolvedTarget === resolvedAlt) return;
+    if (resolvedTarget.startsWith(resolvedAlt + "/")) return;
+  }
+  throw new CopyFailure(
+    "PathTraversalRefused",
+    `Hook target "${target}" escapes ${root}. settings.json commands must resolve inside the declared scope root. If this is a bassclef-upstream bundle defect, file at sunj-labs/bassclef-upstream.`
+  );
+}
+const HOOK_EXECUTABLE_MODE = 493;
+function setExecutable(targetPath) {
+  if (process.platform === "win32") {
+    process.stderr.write(
+      `bassclef init: executable bit not applicable on this OS (${targetPath}). Claude Code will still invoke the hook if a POSIX shell layer is present.
+`
+    );
+    return;
+  }
+  chmodSync(targetPath, HOOK_EXECUTABLE_MODE);
+}
+const HOOKS_SUBPATH = ".claude/hooks/";
+const SETTINGS_SUBPATH = ".claude/settings.json";
 const CONFIG_FILES = [
   ".claude/settings.json",
   "substrate.config.md",
   "substrate.secrets.md"
 ];
 const CURRENT_ENTRY_COUNT = 149;
+const EXPECTED_WIRING_SCHEMA_MAJOR = 2;
+const WIRING_MANIFEST_RELATIVE = "standards/bassclef-wiring-manifest.json";
 function copySubstrate(targetDir, options = {}) {
   const bundleRoot = resolveBundleRoot(options.bundleRoot);
-  const manifest = loadBundledManifest(bundleRoot);
+  const manifest = readWiringManifest(bundleRoot);
   const result = {
     copied: [],
+    copiedEntries: [],
     refused: [],
     errored: [],
-    erroredMessages: []
+    erroredMessages: [],
+    hookCount: 0,
+    wiringVersion: manifest.version
   };
   if (options.dryRun) result.wouldCopy = [];
-  const groups = groupByTopDirectory(manifest.entries);
-  for (const [directory, entries] of groups) {
+  const files = walkDistTree(bundleRoot);
+  const groups = groupByTopDirectory(files);
+  const bundleHookRelPaths = new Set(files.filter(isHookFile));
+  const scopeMap = buildScopeMap(bundleRoot, targetDir, options, bundleHookRelPaths);
+  for (const [directory, groupFiles] of groups) {
     let completedInGroup = 0;
-    for (const entry of entries) {
-      const outcome = copyOne(entry, bundleRoot, targetDir, options, result);
+    for (const relPath of groupFiles) {
+      const outcome = copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap);
       if (outcome !== "skipped") completedInGroup += 1;
     }
     if (options.onProgress) options.onProgress(directory, completedInGroup);
   }
+  result.hookCount = readHookCount(
+    options.dryRun ? join(bundleRoot, ".claude/settings.json") : join(targetDir, ".claude/settings.json")
+  );
   return result;
 }
-function copyOne(entry, bundleRoot, targetDir, options, result) {
-  const sourcePath = join(bundleRoot, entry.path);
-  const targetPath = join(targetDir, entry.path);
+function readWiringManifest(bundleRoot) {
+  const manifestPath = join(bundleRoot, WIRING_MANIFEST_RELATIVE);
+  if (!fileExists(manifestPath)) {
+    throw new CopyFailure(
+      "ManifestMissing",
+      `Wiring manifest missing at ${manifestPath}. Cli built for schema_version ${EXPECTED_WIRING_SCHEMA_MAJOR}.x. Run \`npm install @thebassclef/lite@latest\` to fix.`
+    );
+  }
+  let manifest;
+  let raw;
+  try {
+    raw = readFileSync(manifestPath, "utf8");
+  } catch (e) {
+    const err = e;
+    throw new CopyFailure(
+      "ManifestMissing",
+      `Wiring manifest at ${manifestPath} unreadable (${err.code ?? "unknown"}). Reinstall @thebassclef/lite to restore the bundle.`
+    );
+  }
+  try {
+    manifest = JSON.parse(raw);
+  } catch (e) {
+    const err = e;
+    throw new CopyFailure(
+      "SchemaIncompatible",
+      `Wiring manifest at ${manifestPath} is not valid JSON: ${err.message}. Reinstall @thebassclef/lite to restore the bundle.`
+    );
+  }
+  if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+    throw new CopyFailure(
+      "SchemaIncompatible",
+      `Wiring manifest at ${manifestPath} missing 'version' field. Cli requires schema_version ${EXPECTED_WIRING_SCHEMA_MAJOR}.x. Reinstall @thebassclef/lite to fix.`
+    );
+  }
+  const major = parseInt(manifest.version.split(".")[0] ?? "0", 10);
+  if (major !== EXPECTED_WIRING_SCHEMA_MAJOR) {
+    throw new CopyFailure(
+      "SchemaIncompatible",
+      `Wiring manifest at ${manifestPath} has version ${manifest.version}. Cli built for schema_version ${EXPECTED_WIRING_SCHEMA_MAJOR}.x. Upgrade cli OR downgrade @thebassclef/lite to a compatible version.`
+    );
+  }
+  return { version: manifest.version };
+}
+function walkDistTree(bundleRoot) {
+  if (!dirExists(bundleRoot)) {
+    throw new CopyFailure(
+      "BundleMissing",
+      `Bundled substrate missing at ${bundleRoot}. Reinstall @thebassclef/lite to restore the bundle.`
+    );
+  }
+  const results = [];
+  function walk(dir) {
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name);
+      const st = statSync(full);
+      if (st.isDirectory()) walk(full);
+      else results.push(relative(bundleRoot, full));
+    }
+  }
+  walk(bundleRoot);
+  results.sort();
+  return results;
+}
+const GITIGNORE_BUNDLE_NAME = "gitignore";
+const GITIGNORE_ADOPTER_NAME = ".gitignore";
+function mapAdopterPath(relPath) {
+  if (relPath === GITIGNORE_BUNDLE_NAME) return GITIGNORE_ADOPTER_NAME;
+  return relPath;
+}
+function buildScopeMap(bundleRoot, targetDir, options, bundleHookRelPaths) {
+  const map = /* @__PURE__ */ new Map();
+  const settingsPath = join(bundleRoot, SETTINGS_SUBPATH);
+  if (!fileExists(settingsPath)) return map;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch {
+    return map;
+  }
+  const allowRoot = options.allowRoot ?? false;
+  for (const eventBlocks of Object.values(parsed.hooks ?? {})) {
+    for (const block of eventBlocks) {
+      for (const entry of block.hooks ?? []) {
+        const cmd = entry.command;
+        if (typeof cmd !== "string" || cmd.length === 0) continue;
+        if (!cmd.startsWith("$")) continue;
+        const decision = classify$1({ command: cmd }, { targetDir, allowRoot });
+        const relSource = cmd.replace(/^\$HOME\//, "").replace(/^\$CLAUDE_PROJECT_DIR\//, "").replace(/\/{2,}/g, "/");
+        if (!bundleHookRelPaths.has(relSource)) continue;
+        map.set(relSource, decision);
+      }
+    }
+  }
+  return map;
+}
+function isHookFile(relPath) {
+  return relPath.startsWith(HOOKS_SUBPATH) && relPath.endsWith(".sh");
+}
+function copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap) {
+  const sourcePath = join(bundleRoot, relPath);
+  const adopterRelPath = mapAdopterPath(relPath);
+  const scopeDecision = isHookFile(relPath) ? scopeMap.get(relPath) : void 0;
+  const targetPath = scopeDecision ? scopeDecision.targetPath : join(targetDir, adopterRelPath);
+  const scope = scopeDecision ? scopeDecision.scope : "project";
   let content;
   try {
     content = readFileSync(sourcePath, "utf8");
   } catch (e) {
     const err = e;
-    const message = `${entry.path} — cannot read bundled source (${err.code ?? "unknown"}). Reinstall @thebassclef/core to restore the bundle.`;
-    result.errored.push(entry.path);
-    result.erroredMessages?.push(message);
-    return "errored";
-  }
-  const declaredHash = stripHashPrefix(entry.content_hash);
-  const actualHash = sha256Hex(content);
-  if (declaredHash !== actualHash) {
-    const message = `${entry.path} — bundled content hash does not match the manifest. Reinstall @thebassclef/core to repair the bundle, then rerun bassclef init --force.`;
-    result.errored.push(entry.path);
+    const message = `${relPath} — cannot read bundled source (${err.code ?? "unknown"}). Reinstall @thebassclef/lite to restore the bundle.`;
+    result.errored.push(adopterRelPath);
     result.erroredMessages?.push(message);
     return "errored";
   }
+  const outputContent = options.transform ? options.transform(adopterRelPath, content) : content;
   if (options.dryRun) {
-    result.wouldCopy?.push(entry.path);
+    result.wouldCopy?.push(adopterRelPath);
     return "wouldCopy";
   }
   try {
     mkdirSafely(dirname(targetPath));
-    writeSafely(targetPath, content, { force: options.force ?? false });
-    result.copied.push(entry.path);
+    writeSafely(targetPath, outputContent, { force: options.force ?? false });
+    if (isHookFile(relPath)) {
+      setExecutable(targetPath);
+    }
+    result.copied.push(adopterRelPath);
+    result.copiedEntries.push({ path: adopterRelPath, scope });
     return "copied";
   } catch (e) {
     if (e instanceof WriteError) {
       if (e.kind === "AlreadyExists") {
-        result.refused.push(entry.path);
+        result.refused.push(adopterRelPath);
         return "refused";
       }
       if (e.kind === "SymlinkRefused") {
-        result.refused.push(entry.path);
+        result.refused.push(adopterRelPath);
+        process.stderr.write(`bassclef init: ${e.message}
+`);
         return "refused";
       }
-      const message = `${entry.path} — write failed (${e.kind}): ${e.message}. Check the target directory exists and is writable, then rerun.`;
-      result.errored.push(entry.path);
+      const message = `${adopterRelPath} — write failed (${e.kind}): ${e.message}. Check the target directory exists and is writable, then rerun.`;
+      result.errored.push(adopterRelPath);
       result.erroredMessages?.push(message);
       return "errored";
     }
     throw e;
   }
 }
-function loadBundledManifest(bundleRoot) {
-  const manifestPath = join(bundleRoot, ".bassclef", "lite-manifest.json");
-  const raw = readFileSync(manifestPath, "utf8");
-  const parsed = JSON.parse(raw);
-  if (!Array.isArray(parsed.entries)) {
-    throw new Error(
-      `bundled manifest at ${manifestPath} has no entries[] array. Reinstall @thebassclef/core to restore the bundle.`
-    );
-  }
-  return parsed;
-}
 function resolveBundleRoot(explicit) {
   if (explicit && explicit.length > 0) return resolve(explicit);
   const thisFile = fileURLToPath(import.meta.url);
   let dir = dirname(thisFile);
   for (let i = 0; i < 5; i += 1) {
-    try {
-      readFileSync(join(dir, "package.json"), "utf8");
-      return join(dir, SUBSTRATE_ROOT);
-    } catch {
-      const parent = dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
+    if (fileExists(join(dir, "package.json"))) {
+      return join(dir, "dist", "lite");
     }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
-  const require2 = createRequire(import.meta.url);
-  const pkgJsonPath = require2.resolve("@thebassclef/core/package.json");
-  const pkgRoot = dirname(pkgJsonPath);
-  return join(pkgRoot, SUBSTRATE_ROOT);
+  throw new CopyFailure(
+    "BundleMissing",
+    `Cannot resolve bundled substrate root — package.json unreachable from ${thisFile}. Reinstall @thebassclef/lite.`
+  );
 }
-function groupByTopDirectory(entries) {
+function groupByTopDirectory(files) {
   const groups = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
-    const parts = entry.path.split("/");
+  for (const p of files) {
+    const parts = p.split("/");
     const top = parts.length >= 2 ? parts.slice(0, 2).join("/") : parts[0] ?? "";
     if (!groups.has(top)) groups.set(top, []);
-    groups.get(top).push(entry);
+    groups.get(top).push(p);
   }
   return groups;
 }
-function stripHashPrefix(value) {
-  const prefix = "sha256:";
-  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+function readHookCount(settingsPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+    let count = 0;
+    for (const matcherBlocks of Object.values(parsed.hooks ?? {})) {
+      for (const block of matcherBlocks) {
+        count += (block.hooks ?? []).length;
+      }
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}
+function fileExists(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
 }
-function sha256Hex(content) {
-  return createHash("sha256").update(content).digest("hex");
+function dirExists(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
 }
+const RESOLVED_TIER = "lite";
+const PLACEHOLDER_FILES = /* @__PURE__ */ new Set([
+  "CLAUDE.md",
+  "docs/whereami.md",
+  "whereami.md",
+  ".bassclef-source.json"
+]);
 function runInit(argv) {
   let args;
   try {
@@ -544,7 +780,10 @@ function runInit(argv) {
     }
     throw e;
   }
-  if (!args.force && !args.dryRun) {
+  const advisoryOutcome = maybeEmitUpgradeAdvisory(targetDir, args.yes);
+  if (advisoryOutcome === "refused") return 1;
+  const upgradeApproved = advisoryOutcome === "upgrade-approved";
+  if (!args.force && !args.dryRun && !upgradeApproved) {
     const manifestPath = join(targetDir, MANIFEST_RELATIVE_PATH);
     if (existsSync(manifestPath)) {
       process.stderr.write(
@@ -554,14 +793,6 @@ function runInit(argv) {
     }
   }
   const plans = [
-    {
-      label: "settings.json",
-      relativePath: ".claude/settings.json",
-      fullPath: join(targetDir, ".claude", "settings.json"),
-      content: settingsJsonTemplate(version),
-      templateName: "settings.json",
-      templateVersion: SETTINGS_TEMPLATE_VERSION
-    },
     {
       label: "substrate.config.md",
       relativePath: "substrate.config.md",
@@ -573,30 +804,54 @@ function runInit(argv) {
   ];
   if (args.dryRun) {
     runDryRun$1(plans);
-    dispatchSubstrateCopy(targetDir, args.force, args.verbose, true);
-    return 0;
+    return dispatchSubstrateCopy(targetDir, args.force || upgradeApproved, args.verbose, true, args.allowRoot, args.json);
   }
-  const exitCode = runReal$1(plans, args.force, args.verbose, targetDir);
-  if (exitCode === 0) {
-    dispatchSubstrateCopy(targetDir, args.force, args.verbose, false);
+  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json);
+}
+function maybeEmitUpgradeAdvisory(targetDir, yes) {
+  const manifestPath = join(targetDir, MANIFEST_RELATIVE_PATH);
+  if (!existsSync(manifestPath)) return "ok";
+  const version2 = readManifestShapeVersion(targetDir);
+  if (version2 !== null && version2 >= 2) return "ok";
+  process.stdout.write(
+    `bassclef init: cli 1.0.1 introduces user-scope hook installation at ~/${HOOKS_SUBPATH}. cli 1.0.0 did not write there.
+`
+  );
+  if (yes) return "upgrade-approved";
+  process.stdout.write("bassclef init: continue? (y/N) ");
+  const answer = readOneLineFromStdin();
+  if (answer === "" || answer === "y" || answer === "Y") return "upgrade-approved";
+  process.stdout.write("bassclef init: aborted by adopter.\n");
+  return "refused";
+}
+function readOneLineFromStdin() {
+  try {
+    const buf = Buffer.alloc(256);
+    const n = require("node:fs").readSync(0, buf, 0, 256, null);
+    return n > 0 ? buf.slice(0, n).toString("utf8").trim() : "";
+  } catch {
+    return "";
   }
-  return exitCode;
 }
-function dispatchSubstrateCopy(targetDir, force, verbose, dryRun) {
+function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, json) {
+  const substitute = makePlaceholderTransform(targetDir);
   let result;
   try {
-    result = copySubstrate(targetDir, { force, dryRun });
+    result = copySubstrate(targetDir, {
+      force,
+      dryRun,
+      transform: substitute,
+      allowRoot
+    });
   } catch (e) {
-    const err = e;
-    process.stderr.write(
-      `bassclef init: substrate copy failed — ${err.message}
-  cause: the installed @thebassclef/core package is missing the bundled substrate manifest.
-  fix: reinstall with \`npm install -g @thebassclef/core@latest --force\`.
-       If the reinstall does not help, file an issue at
-       https://github.com/sunj-labs/bassclef-cli/issues with your package version.
-`
-    );
-    process.exit(2);
+    if (e instanceof CopyFailure) {
+      process.stderr.write(`bassclef init: ${e.message}
+`);
+      if (e.kind === "ManifestMissing") return 4;
+      if (e.kind === "SchemaIncompatible") return 5;
+      return 2;
+    }
+    throw e;
   }
   if (dryRun) {
     const wouldCopy = result.wouldCopy ?? [];
@@ -611,10 +866,14 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun) {
 `
       );
     }
-    return;
+    process.stdout.write(
+      `bassclef init: ${result.hookCount} hooks armed (${RESOLVED_TIER} tier).
+`
+    );
+    return 0;
   }
   if (result.copied.length === 0 && result.refused.length === 0 && result.errored.length === 0) {
-    return;
+    return 0;
   }
   const groupCounts = /* @__PURE__ */ new Map();
   for (const path of result.copied) {
@@ -632,17 +891,56 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun) {
   if (result.errored.length > 0) parts.push(`${result.errored.length} error(s)`);
   process.stdout.write(`bassclef init: ${parts.join(", ")}.
 `);
-  const grandTotal = 2 + result.copied.length;
+  const grandTotal = 1 + result.copied.length;
   process.stdout.write(
-    `bassclef init: ${grandTotal} files total (2 config + ${result.copied.length} substrate).
+    `bassclef init: ${grandTotal} files total (1 config + ${result.copied.length} substrate).
 `
   );
+  const copiedHookEntries = result.copiedEntries.filter(
+    (e) => e.path.startsWith(HOOKS_SUBPATH) && e.path.endsWith(".sh")
+  );
+  const copiedCount = copiedHookEntries.length;
+  const declaredCount = result.hookCount;
+  const failedCount = result.refused.length + result.errored.length;
+  const userScope = copiedHookEntries.filter((e) => e.scope === "user").length;
+  const projectScope = copiedHookEntries.filter((e) => e.scope === "project").length;
+  const scopeSuffix = userScope + projectScope > 0 ? ` ${projectScope} in <repo>/${HOOKS_SUBPATH.replace(/\/$/, "")}, ${userScope} in ~/${HOOKS_SUBPATH.replace(/\/$/, "")}.` : "";
+  if (failedCount > 0) {
+    process.stdout.write(
+      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix} ${failedCount} failed — see errors above. Rerun bassclef init to retry.
+`
+    );
+  } else {
+    process.stdout.write(
+      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix}
+`
+    );
+  }
+  if (json) {
+    const report = {
+      copied: copiedCount,
+      declared: declaredCount,
+      failed: failedCount,
+      scope_counts: { user: userScope, project: projectScope },
+      tier: RESOLVED_TIER
+    };
+    process.stderr.write(JSON.stringify(report) + "\n");
+  }
   if (verbose && result.erroredMessages) {
     for (const msg of result.erroredMessages) {
       process.stderr.write(`  substrate: ${msg}
 `);
     }
   }
+  return result.errored.length > 0 ? 2 : 0;
+}
+function makePlaceholderTransform(targetDir) {
+  const repoName = basename$1(targetDir);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  return (relPath, content) => {
+    if (!PLACEHOLDER_FILES.has(relPath)) return content;
+    return content.replace(/\[REPO_NAME\]/g, repoName).replace(/\[ISO_TIMESTAMP\]/g, timestamp).replace(/\[TIER\]/g, RESOLVED_TIER).replace(/\[Repo name\]/g, repoName).replace(/<tier>/g, RESOLVED_TIER);
+  };
 }
 function runDryRun$1(plans) {
   for (const p of plans) {
@@ -669,7 +967,7 @@ function runDryRun$1(plans) {
   }
   return 0;
 }
-function runReal$1(plans, force, verbose, targetDir) {
+function runReal$1(plans, force, verbose, targetDir, allowRoot, json) {
   const results = [];
   let anyRefused = false;
   let anyError = false;
@@ -726,8 +1024,8 @@ function runReal$1(plans, force, verbose, targetDir) {
     process.stderr.write(`bassclef init: ${tag}: ${r.message ?? "write failed"}: ${r.plan.fullPath}
 `);
   }
-  writeManifest(targetDir, results);
   if (anyError) {
+    writeManifest(targetDir, results);
     const parts = [];
     if (created > 0) parts.push(`${created} created`);
     if (unchanged > 0) parts.push(`${unchanged} unchanged`);
@@ -738,28 +1036,26 @@ function runReal$1(plans, force, verbose, targetDir) {
 `);
     return 2;
   }
-  if (created === 0 && unchanged === plans.length) {
-    process.stdout.write("bassclef init: already initialized. No changes.\n");
-    return 0;
-  }
   if (anyRefused && created > 0) {
     process.stdout.write(
       `bassclef init: ${created} config files created, ${unchanged} unchanged. Pass --force to overwrite.
 `
     );
+  } else if (created === 0 && unchanged === plans.length) {
+    process.stdout.write("bassclef init: already initialized. No changes.\n");
+  } else {
+    process.stdout.write(`bassclef init: ${created} config files created, ${unchanged} unchanged.
+`);
+  }
+  const walkerExit = dispatchSubstrateCopy(targetDir, force, verbose, false, allowRoot, json);
+  writeManifest(targetDir, results);
+  if (walkerExit === 0) {
     process.stdout.write(
       `bassclef init: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
 `
     );
-    return 0;
   }
-  process.stdout.write(`bassclef init: ${created} config files created, ${unchanged} unchanged.
-`);
-  process.stdout.write(
-    `bassclef init: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
-`
-  );
-  return 0;
+  return walkerExit;
 }
 function shouldRefuseRoot(currentUid, allowRoot) {
   if (currentUid === void 0) return false;
@@ -807,17 +1103,22 @@ function usage$2() {
     "  --allow-any-dir    Allow --dir outside your home directory. Default: refuse.",
     "  --verbose          Print per-file result.",
     "",
+    "Exit codes:",
+    "  0 — success",
+    "  1 — refused by policy (existing file; running as root; outside HOME)",
+    "  2 — safety check failed at write (symlink; parent not writable)",
+    "  3 — invalid args",
+    "  4 — wiring manifest missing from bundled substrate (reinstall @thebassclef/lite)",
+    "  5 — wiring manifest schema major version incompatible with this cli",
+    "",
     "Files written under <target>:",
-    "  .claude/settings.json          Claude Code settings (minimal, opt-in blocks)",
     "  substrate.config.md            Bassclef project manifest",
     "  .bassclef/init.manifest.json   Record of what init wrote (used by sync)",
     "",
-    "  Plus the bundled substrate tree (~280 files):",
-    "  .claude/{agents,hooks,luminaries,rules,skills}/",
-    "  standards/, templates/, scripts/, lib/, presence/install/",
-    "  architecture/decisions/",
-    "  AGENTS.md, CLAUDE-lite.md, README.md, CONTRIBUTING.md,",
-    "  SECURITY.md, CODE_OF_CONDUCT.md",
+    "  Plus the bundled substrate tree from dist/lite/:",
+    "  .claude/settings.json          Claude Code settings (verbatim from bundle)",
+    "  CLAUDE.md, whereami.md, .bassclef-source.json, .gitignore",
+    "                                 Templates with placeholders substituted",
     "",
     "  Run with --dry-run first to preview the full file list before",
     "  writing anything to disk.",
@@ -899,12 +1200,6 @@ function parseSyncArgs(argv) {
   return out;
 }
 const TEMPLATES = [
-  {
-    templateName: "settings.json",
-    currentVersion: SETTINGS_TEMPLATE_VERSION,
-    render: settingsJsonTemplate,
-    hasMarker: (c) => c.includes('"$bassclef"')
-  },
   {
     templateName: "substrate.config.md",
     currentVersion: SUBSTRATE_CONFIG_TEMPLATE_VERSION,
@@ -1405,6 +1700,7 @@ Proceed?`,
   );
   const errored = copyResult.errored;
   const newManifest = {
+    schema_version: MANIFEST_SHAPE_VERSION,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: "0.1.0",