@narrativetrace/cli 0.1.3 → 0.2.0

package/dist/cli-bin.cjs

@@ -1,373 +1,135 @@
 #!/usr/bin/env node
 "use strict";
 
-// src/doctor/doc-urls.ts
-var BASE = "https://github.com/narrativetrace/narrativetrace-typescript/blob/main/documentation/";
-var DOC = {
-  installationPrerequisites: `${BASE}installation-guide.md#prerequisites`,
-  installationDependencies: `${BASE}installation-guide.md#1-add-dependencies`,
-  vitestConfiguration: `${BASE}configuration-guide.md#2-vitest-configuration`,
-  whereSettingsComeFrom: `${BASE}configuration-guide.md#2b-where-settings-come-from`,
-  proxyOptions: `${BASE}configuration-guide.md#6-proxy-options`,
-  eventPipelineBuffering: `${BASE}configuration-guide.md#8-event-pipeline-buffering-bufferedeventconsumer`,
-  noTraceFilesWritten: `${BASE}troubleshooting.md#no-trace-files-are-written`,
-  manualParameterNames: `${BASE}troubleshooting.md#parameters-show-as-arg0-arg1`,
-  redactionSurfaceBySurface: `${BASE}privacy-and-redaction.md#redaction-surface-by-surface`,
-  approvalTracesEndToEnd: `${BASE}structural-trace-format.md#approval-traces-end-to-end`,
-  sixtySecondsNewProject: `${BASE}sixty-seconds.md#1-new-project-add-the-packages`
-};
+// ../../node_modules/.pnpm/tsup@8.5.1_@swc+core@1.15.18_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3_yaml@2.9.0/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
-// src/doctor/finding.ts
-function pass(id, message, docUrl) {
-  return { id, status: "pass", message, fix: "", docUrl };
-}
-function fail(id, message, fix, docUrl) {
-  return { id, status: "fail", message, fix, docUrl };
-}
-
-// src/doctor/checks/approval-traces.ts
-var ID = "trap.approval-traces";
-var FIX = "Review each .received.nt diff against its .approved.nt baseline, then run pnpm run approve-narratives (or narrativetrace-approve) to promote it, or delete it if the change was wrong \u2014 never commit a .received.nt file.";
-var checkApprovalTraces = (snapshot) => {
-  const paths = [...snapshot.approvedDirFiles.keys()];
-  if (paths.length === 0) {
-    return pass(
-      ID,
-      "no approval traces configured yet \u2014 nothing to check",
-      DOC.approvalTracesEndToEnd
-    );
-  }
-  const received = paths.filter((p) => p.endsWith(".received.nt"));
-  if (received.length > 0) {
-    const message2 = `${received.length} stale received trace(s) found: ${received.join(", ")}`;
-    return fail(ID, message2, FIX, DOC.approvalTracesEndToEnd);
-  }
-  const approved = paths.filter((p) => p.endsWith(".approved.nt"));
-  const message = `${approved.length} approved trace(s) found, no pending received diffs`;
-  return pass(ID, message, DOC.approvalTracesEndToEnd);
-};
-
-// src/doctor/checks/llms-before-you-start.ts
-var ID2 = "trap.llms-before-you-start";
-var PLAIN_JS = /\.js$/;
-var ESM_IMPORT = /^\s*import\s/m;
-var FIX2 = "Run `npm pkg set type=module` before `npm add` \u2014 without it, Node throws SyntaxError: Cannot use import statement outside a module (pnpm/yarn default to it and never hit this).";
-var checkLlmsBeforeYouStart = (snapshot) => {
-  if (snapshot.rootPackageJson?.type === "module") {
-    return pass(ID2, 'package.json declares "type": "module"', DOC.sixtySecondsNewProject);
-  }
-  const offender = [...snapshot.sourceFiles].find(
-    ([path2, content]) => PLAIN_JS.test(path2) && ESM_IMPORT.test(content)
-  );
-  if (!offender) {
-    const message2 = 'no plain .js file uses ESM import syntax without "type": "module"';
-    return pass(ID2, message2, DOC.sixtySecondsNewProject);
-  }
-  const [path] = offender;
-  const message = `${path} uses ESM import syntax but package.json has no "type": "module"`;
-  return fail(ID2, message, FIX2, DOC.sixtySecondsNewProject);
-};
-
-// src/semver-lite.ts
-function parseVersion(raw) {
-  const cleaned = raw.trim().replace(/^v/, "");
-  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(cleaned);
-  if (!match) return void 0;
-  return {
-    major: Number(match[1]),
-    minor: match[2] === void 0 ? 0 : Number(match[2]),
-    patch: match[3] === void 0 ? 0 : Number(match[3])
-  };
-}
-function compareVersions(left, right) {
-  if (left.major !== right.major) return left.major - right.major;
-  if (left.minor !== right.minor) return left.minor - right.minor;
-  return left.patch - right.patch;
-}
-function satisfiesGte(version, floor) {
-  return compareVersions(version, floor) >= 0;
-}
-function satisfiesCaret(version, base) {
-  if (compareVersions(version, base) < 0) return false;
-  if (base.major > 0) return version.major === base.major;
-  if (base.minor > 0) return version.major === 0 && version.minor === base.minor;
-  return version.major === 0 && version.minor === 0 && version.patch === base.patch;
-}
-function satisfiesClause(version, trimmed) {
-  if (trimmed.startsWith("^")) {
-    const base = parseVersion(trimmed.slice(1));
-    return base !== void 0 && satisfiesCaret(version, base);
-  }
-  if (trimmed.startsWith(">=")) {
-    const floor = parseVersion(trimmed.slice(2));
-    return floor !== void 0 && satisfiesGte(version, floor);
-  }
-  if (/\.x\b/.test(trimmed)) {
-    const base = parseVersion(trimmed.replace(/\.x/g, ".0"));
-    return base !== void 0 && satisfiesCaret(version, base);
-  }
-  const exact = parseVersion(trimmed);
-  return exact !== void 0 && compareVersions(version, exact) === 0;
-}
-function satisfiesRange(versionRaw, range) {
-  const version = parseVersion(versionRaw);
-  if (!version) return false;
-  return range.split("||").map((clause) => clause.trim()).filter(Boolean).some((clause) => satisfiesClause(version, clause));
-}
-
-// src/doctor/checks/node-engine.ts
-var ID3 = "toolchain.node-engine";
-var DEFAULT_ENGINE_RANGE = ">=20";
-function requiredRange(snapshot) {
-  const core = snapshot.installedPackages.get("@narrativetrace/core");
-  const coreNode = snapshot.installedPackages.get("@narrativetrace/core-node");
-  return core?.engines?.node ?? coreNode?.engines?.node ?? DEFAULT_ENGINE_RANGE;
-}
-var checkNodeEngine = (snapshot) => {
-  const required = requiredRange(snapshot);
-  if (satisfiesRange(snapshot.nodeVersion, required)) {
-    return pass(
-      ID3,
-      `Node ${snapshot.nodeVersion} satisfies the required ${required}`,
-      DOC.installationPrerequisites
-    );
-  }
-  return fail(
-    ID3,
-    `Node ${snapshot.nodeVersion} does not satisfy the required ${required}`,
-    `Upgrade Node to a version satisfying ${required} (nvm, volta, asdf, or your CI image).`,
-    DOC.installationPrerequisites
-  );
-};
-
-// src/doctor/checks/output-env.ts
-var ID4 = "config.output-env";
-var VALID_VALUES = /* @__PURE__ */ new Set(["true", "false"]);
-var checkOutputEnv = (snapshot) => {
-  const raw = snapshot.env.NARRATIVETRACE_OUTPUT;
-  if (raw === void 0) {
-    return pass(
-      ID4,
-      "NARRATIVETRACE_OUTPUT is not set \u2014 output stays on its default (on)",
-      DOC.whereSettingsComeFrom
-    );
-  }
-  if (VALID_VALUES.has(raw.toLowerCase())) {
-    return pass(ID4, `NARRATIVETRACE_OUTPUT=${raw}`, DOC.whereSettingsComeFrom);
-  }
-  return fail(
-    ID4,
-    `NARRATIVETRACE_OUTPUT is set to '${raw}', which is neither "true" nor "false"`,
-    "Set NARRATIVETRACE_OUTPUT=true or NARRATIVETRACE_OUTPUT=false (or unset it) \u2014 any other value is read as a truthy string, most likely turning output on when you meant to turn it off.",
-    DOC.whereSettingsComeFrom
-  );
-};
-
-// src/doctor/checks/parameter-arg0.ts
-var ID5 = "trap.parameter-arg0";
-var ARG_PLACEHOLDER = /\barg0\b/;
-var FIX3 = 'Pass parameter names explicitly: traceObject(target, context, { methodName: ["paramA", "paramB"] }) \u2014 required for classes you do not own, or when a build tool strips them.';
-var checkParameterArg0 = (snapshot) => {
-  if (snapshot.outputFiles.size === 0) {
-    const message2 = "no rendered output found yet \u2014 run your tests or app once to check this";
-    return pass(ID5, message2, DOC.manualParameterNames);
-  }
-  const offender = [...snapshot.outputFiles].find(([, content]) => ARG_PLACEHOLDER.test(content));
-  if (!offender) {
-    const message2 = "rendered output carries real parameter names \u2014 no arg0 placeholders found";
-    return pass(ID5, message2, DOC.manualParameterNames);
-  }
-  const [path] = offender;
-  const message = `rendered output shows arg0-style placeholders (first seen in ${path}) \u2014 parameter names were not captured`;
-  return fail(ID5, message, FIX3, DOC.manualParameterNames);
-};
-
-// src/doctor/checks/redaction-proof.ts
-var ID6 = "trap.redaction-proof";
-var TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/;
-var REDACTED_ASSERTION = /\[REDACTED\]/;
-var checkRedactionProof = (snapshot) => {
-  const testFiles = [...snapshot.sourceFiles].filter(([path]) => TEST_FILE.test(path));
-  const proven = testFiles.some(([, content]) => REDACTED_ASSERTION.test(content));
-  if (proven) {
-    return pass(
-      ID6,
-      "a test asserts [REDACTED] for a deny-listed parameter name",
-      DOC.redactionSurfaceBySurface
-    );
-  }
-  return fail(
-    ID6,
-    "no test asserts [REDACTED] \u2014 redaction is unproven",
-    'Render a call with a deny-listed parameter name (e.g. "password", "token") in a test and assert the output contains "[REDACTED]" \u2014 and that a neighboring, non-sensitive value is still present, so an over-broad redaction also fails.',
-    DOC.redactionSurfaceBySurface
-  );
-};
-
-// src/doctor/checks/reporter-subpath.ts
-var ID7 = "config.reporter-subpath";
-var VITEST_CONFIG_NAME = /(^|\/)vitest\.config\.[cm]?[jt]s$/;
-var REPORTER_NAMES = /\b(ClaritySuiteReporter|GlossarySuiteReporter|StructuralSuiteReporter)\b/;
-var ROOT_IMPORT = /from\s+["']@narrativetrace\/vitest["']/;
-var SUBPATH_IMPORT = /from\s+["']@narrativetrace\/vitest\/reporters["']/;
-function importsFromRoot(content) {
-  return REPORTER_NAMES.test(content) && ROOT_IMPORT.test(content) && !SUBPATH_IMPORT.test(content);
-}
-var checkReporterSubpath = (snapshot) => {
-  const configs = [...snapshot.sourceFiles].filter(([path]) => VITEST_CONFIG_NAME.test(path));
-  const offender = configs.find(([, content]) => importsFromRoot(content));
-  if (offender) {
-    const [path] = offender;
-    return fail(
-      ID7,
-      `${path} imports a NarrativeTrace vitest reporter from the package root, not the /reporters subpath`,
-      'Import reporters from "@narrativetrace/vitest/reporters" \u2014 importing from the package root also loads vitest itself and crashes config loading.',
-      DOC.vitestConfiguration
-    );
-  }
-  const message = configs.length === 0 ? "no vitest.config found \u2014 nothing to check" : "every registered reporter is imported from the /reporters subpath";
-  return pass(ID7, message, DOC.vitestConfiguration);
-};
-
-// src/doctor/checks/sibling-packages.ts
-var ID8 = "toolchain.sibling-packages";
-var checkSiblingPackages = (snapshot) => {
-  const ntVitest = snapshot.installedPackages.get("@narrativetrace/vitest");
-  if (!ntVitest) {
-    const message2 = "@narrativetrace/vitest is not installed \u2014 nothing to check";
-    return pass(ID8, message2, DOC.installationDependencies);
-  }
-  const siblings = Object.keys(ntVitest.dependencies ?? {}).filter(
-    (n) => n.startsWith("@narrativetrace/")
-  );
-  const unresolved = siblings.filter((name) => !snapshot.installedPackages.has(name));
-  if (unresolved.length === 0) {
-    const message2 = `all ${siblings.length} sibling package(s) of @narrativetrace/vitest resolve from the consumer`;
-    return pass(ID8, message2, DOC.installationDependencies);
-  }
-  const message = `${unresolved.length} sibling package(s) of @narrativetrace/vitest do not resolve from the consumer: ${unresolved.join(", ")}`;
-  const fix = `Add ${unresolved.join(", ")} as explicit direct dependencies \u2014 pnpm's strict layout does not hoist a dependency's own transitive dependencies to your project root.`;
-  return fail(ID8, message, fix, DOC.installationDependencies);
-};
-
-// src/doctor/checks/silent-sink.ts
-var ID9 = "trap.silent-sink";
-var TRACE_OBJECT_CALL = /\btraceObject\s*\(/;
-var SINK_SIGNAL = /\b(BufferedEventConsumer|captureTrace|registerConsumer|createNarrativeTest|narrativeTest)\b|@narrativetrace\/(vitest|pino|winston|opentelemetry|observability)\b/;
-var checkSilentSink = (snapshot) => {
-  const contents = [...snapshot.sourceFiles.values()];
-  if (!contents.some((content) => TRACE_OBJECT_CALL.test(content))) {
-    return pass(ID9, "traceObject() is not used \u2014 nothing to check", DOC.noTraceFilesWritten);
-  }
-  if (contents.some((content) => SINK_SIGNAL.test(content))) {
-    return pass(
-      ID9,
-      "traceObject() is used and a consumer/sink is attached",
-      DOC.noTraceFilesWritten
-    );
-  }
-  return fail(
-    ID9,
-    "traceObject() is used but no consumer or sink (BufferedEventConsumer, captureTrace(), a log/OTel bridge, or @narrativetrace/vitest) was found",
-    "Attach a sink: pass a BufferedEventConsumer to your pipeline, call captureTrace() and do something with the tree, or wire a log/OTel bridge \u2014 otherwise every traced call narrates to nowhere.",
-    DOC.noTraceFilesWritten
-  );
-};
-
-// src/doctor/checks/trace-object-keys.ts
-var ID10 = "config.trace-object-keys";
-var OLD_SHAPE = /\bmethods\s*:\s*\{[^{}]*:\s*\[/;
-var checkTraceObjectKeys = (snapshot) => {
-  const offender = [...snapshot.sourceFiles].find(([, content]) => OLD_SHAPE.test(content));
-  if (offender) {
-    const [path] = offender;
-    return fail(
-      ID10,
-      `${path} calls traceObject(...) with a method entry that skips the per-method config object`,
-      "Nest the parameter names under params: traceObject(target, context, { methods: { methodName: { params: [...] } } }) \u2014 a bare array under the method name throws.",
-      DOC.proxyOptions
-    );
-  }
-  return pass(
-    ID10,
-    "no traceObject(...) call uses the old { methods: { ... } } option shape",
-    DOC.proxyOptions
-  );
-};
+// src/cli-bin.ts
+var import_tooling4 = require("@narrativetrace/tooling");
 
-// src/doctor/checks/vitest-peer.ts
-var ID11 = "toolchain.vitest-peer";
-function noVitestInstalled(range) {
-  const message = `@narrativetrace/vitest requires a peer vitest@${range}, but no vitest install was found`;
-  const fix = `Install a vitest version satisfying ${range} (npm add -D vitest, then npm ci for a clean lockfile install).`;
-  return fail(ID11, message, fix, DOC.vitestConfiguration);
-}
-function mismatchedVitest(range, installed) {
-  const message = `vitest@${installed} does not satisfy @narrativetrace/vitest's declared peer range ${range}`;
-  const fix = `Install a vitest version satisfying ${range}, then reinstall clean (rm -rf node_modules && npm ci) \u2014 a mismatched peer here is the one failure mode that breaks the library's own build.`;
-  return fail(ID11, message, fix, DOC.vitestConfiguration);
+// src/carrier-locator.ts
+var import_node_path = require("path");
+var import_node_url = require("url");
+var import_tooling = require("@narrativetrace/tooling");
+function cliPackageDirectory() {
+  return (0, import_node_path.dirname)((0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl)));
 }
-function evaluateInstalledVitest(range, vitest) {
-  if (!vitest?.version) return noVitestInstalled(range);
-  if (satisfiesRange(vitest.version, range)) {
-    const message = `vitest@${vitest.version} satisfies the declared peer range ${range}`;
-    return pass(ID11, message, DOC.vitestConfiguration);
-  }
-  return mismatchedVitest(range, vitest.version);
+function openCarrierFor(projectDirectory, from) {
+  return (0, import_tooling.resolveCarrier)({ projectDirectory, bundledDirectory: cliPackageDirectory(), from });
 }
-var checkVitestPeer = (snapshot) => {
-  const ntVitest = snapshot.installedPackages.get("@narrativetrace/vitest");
-  const range = ntVitest?.peerDependencies?.vitest;
-  if (!ntVitest || !range) {
-    return pass(
-      ID11,
-      "@narrativetrace/vitest is not installed \u2014 nothing to check",
-      DOC.vitestConfiguration
-    );
-  }
-  return evaluateInstalledVitest(range, snapshot.installedPackages.get("vitest"));
-};
 
-// src/doctor/doctor.ts
-var DOCTOR_CHECKS = [
-  checkNodeEngine,
-  checkVitestPeer,
-  checkSiblingPackages,
-  checkOutputEnv,
-  checkReporterSubpath,
-  checkTraceObjectKeys,
-  checkSilentSink,
-  checkParameterArg0,
-  checkRedactionProof,
-  checkApprovalTraces,
-  checkLlmsBeforeYouStart
-];
-function runDoctor(snapshot) {
-  const findings = DOCTOR_CHECKS.map((check) => check(snapshot));
-  const exitCode2 = findings.some((f) => f.status === "fail") ? 1 : 0;
-  return { findings, exitCode: exitCode2 };
-}
+// src/cli.ts
+var import_tooling3 = require("@narrativetrace/tooling");
 
-// src/doctor/render.ts
-function renderFinding(finding) {
-  const tag = finding.status === "fail" ? "FAIL" : "PASS";
-  const lines = [`[${tag}] ${finding.id} \u2014 ${finding.message}`];
-  if (finding.status === "fail") {
-    lines.push(`  fix:  ${finding.fix}`, `  docs: ${finding.docUrl}`);
-  }
-  lines.push("");
-  return lines;
-}
-function renderHuman(report) {
-  const failing = report.findings.filter((f) => f.status === "fail");
-  const passing = report.findings.filter((f) => f.status === "pass");
-  const header = `narrativetrace doctor \u2014 ${report.findings.length} check(s), ${failing.length} finding(s)`;
-  const summary = failing.length === 0 ? "All checks passed." : `${failing.length} finding(s). Exit code ${report.exitCode}.`;
-  const body = [...failing, ...passing].flatMap(renderFinding);
-  return [header, "", ...body, summary].join("\n");
-}
-function renderJson(report) {
-  return JSON.stringify(report, null, 2);
+// src/installer-arguments.ts
+var import_tooling2 = require("@narrativetrace/tooling");
+var VALUE_FLAGS = /* @__PURE__ */ new Set(["--only", "--vendor", "--from"]);
+var SWITCHES = /* @__PURE__ */ new Map([
+  [
+    "--dry-run",
+    (reading) => {
+      reading.draft.dryRun = true;
+    }
+  ],
+  [
+    "--write-existing",
+    (reading) => {
+      reading.draft.writeExisting = true;
+    }
+  ],
+  [
+    "--force",
+    (reading) => {
+      reading.draft.force = true;
+    }
+  ],
+  [
+    "--json",
+    (reading) => {
+      reading.json = true;
+    }
+  ],
+  [
+    "--help",
+    (reading) => {
+      reading.help = true;
+    }
+  ],
+  [
+    "-h",
+    (reading) => {
+      reading.help = true;
+    }
+  ]
+]);
+function fail(reading, message) {
+  reading.error ??= message;
+}
+function readScope(value, reading) {
+  if (value === "skills" || value === "agents-md") reading.draft.scope = value;
+  else fail(reading, `--only takes skills or agents-md, got "${value}"`);
+}
+function readVendor(value, reading) {
+  if (value === "claude") reading.draft.vendorClaude = "on";
+  else if (value === "none") reading.draft.vendorClaude = "off";
+  else fail(reading, `--vendor takes claude or none, got "${value}"`);
+}
+function nextFlagMessage(name, value) {
+  return `${name} needs a value, and "${value}" reads as the next flag \u2014 write ${name}=${value} if it really is the value`;
+}
+function readValued(name, value, spelledOut, reading) {
+  if (value === void 0 || value === "") {
+    fail(reading, `${name} needs a value`);
+    return false;
+  }
+  if (!spelledOut && value.startsWith("--")) {
+    fail(reading, nextFlagMessage(name, value));
+    return false;
+  }
+  if (name === "--only") readScope(value, reading);
+  else if (name === "--vendor") readVendor(value, reading);
+  else reading.from = value;
+  return true;
+}
+function splitArgument(argument) {
+  const equals = argument.indexOf("=");
+  return equals < 0 ? { name: argument, spelled: void 0 } : { name: argument.slice(0, equals), spelled: argument.slice(equals + 1) };
+}
+function readOne(args, index, reading) {
+  const argument = args[index];
+  const { name, spelled } = splitArgument(argument);
+  const turnOn = SWITCHES.get(name);
+  if (turnOn !== void 0) {
+    if (spelled === void 0) turnOn(reading);
+    else fail(reading, `${name} takes no value, got "${argument}"`);
+    return index;
+  }
+  if (!VALUE_FLAGS.has(name)) {
+    fail(reading, `unknown option: "${argument}"`);
+    return index;
+  }
+  const valueIndex = spelled === void 0 ? index + 1 : index;
+  const value = spelled ?? args[valueIndex];
+  return readValued(name, value, spelled !== void 0, reading) ? valueIndex : index;
+}
+function parseInstallerArguments(args) {
+  if (args == null) throw new TypeError("a command line is a list of arguments, never null");
+  const reading = {
+    draft: {},
+    from: void 0,
+    json: false,
+    help: false,
+    error: void 0
+  };
+  for (let index = 0; index < args.length; index += 1) index = readOne(args, index, reading);
+  return Object.freeze({
+    options: (0, import_tooling2.initOptions)(reading.draft),
+    from: reading.from,
+    json: reading.json,
+    help: reading.help,
+    error: reading.error
+  });
 }
 
 // src/cli.ts
@@ -375,9 +137,14 @@ var USAGE = `narrativetrace \u2014 one CLI over NarrativeTrace's open artifact f
 
 Usage:
   narrativetrace doctor [--json]
+  narrativetrace init [--dry-run] [--write-existing] [--force] [--only <half>] [--vendor <vendor>]
+                      [--from <dir>] [--json]
+  narrativetrace uninstall [--dry-run] [--only <half>] [--json]
 
 Commands:
-  doctor    Read-only project diagnosis: toolchain, configuration, and known traps. Zero network.
+  doctor     Read-only project diagnosis: toolchain, configuration, and known traps. Zero network.
+  init       Installs the NarrativeTrace agent skills and the AGENTS.md section into this project.
+  uninstall  Removes exactly what init wrote, and nothing beside it.
 
 Options:
   --json    Machine-readable output instead of human text.
@@ -386,6 +153,43 @@ var DOCTOR_USAGE = `narrativetrace doctor [--json]
 
 Read-only. Checks toolchain/install state, configuration, and known traps against the current
 project. Exit 0 = clean, 1 = findings, 2 = could not run.`;
+var INSTALLER_OPTIONS = `  --dry-run         Show the plan and the unified diff. Writes nothing, always exits 0.
+  --write-existing  Permission to touch an AGENTS.md or CLAUDE.md that is already there.
+  --force           Permission to overwrite a skill directory somebody else owns.
+  --only <half>     skills | agents-md. Both halves by default.
+  --vendor <vendor> claude | none. Detected from the project by default.
+  --from <dir>      A directory holding the carrier: a checked-out @narrativetrace/skills, or an
+                    unpacked tarball of one. The copy bundled with this CLI by default.
+  --json            Machine-readable output instead of human text.
+
+Exit 0 = applied (or a dry run), 1 = something was refused, 2 = could not run.`;
+var INIT_USAGE = `narrativetrace init [options]
+
+Copies the NarrativeTrace agent skills into .agents/skills/ (and .claude/skills/ where the project
+is one of that vendor's) and writes one marked section into AGENTS.md. Zero network.
+
+Run it again to refresh: this CLI installs no build hook and schedules nothing, so a re-run IS the
+refresh. On a project that already carries the skills it rewrites only our own pages and our own
+marked section, and leaves everything else where it is.
+
+${INSTALLER_OPTIONS}`;
+var UNINSTALL_OPTIONS = `  --dry-run         Show the plan and the unified diff. Removes nothing, always exits 0.
+  --only <half>     skills | agents-md. Both halves by default.
+  --json            Machine-readable output instead of human text.
+
+The install-only flags (--write-existing, --force, --vendor, --from) are accepted and ignored: there
+is no carrier to open and no permission to ask for when removing what this tool itself wrote.
+
+Exit 0 = removed (or a dry run), 1 = something was refused, 2 = could not run.`;
+var UNINSTALL_USAGE = `narrativetrace uninstall [options]
+
+Removes exactly what init wrote: skill directories carrying its provenance line, the marked
+section, and the one @AGENTS.md import line. Never touches anything else.
+
+${UNINSTALL_OPTIONS}`;
+var CARRIER_HINT = `Nothing was fetched: this command makes no network call. Point --from at a carrier you have:
+  --from node_modules/@narrativetrace/skills
+  npm pack @narrativetrace/skills && tar xzf narrativetrace-skills-*.tgz && narrativetrace init --from package`;
 function runDoctorCommand(rest, deps) {
   if (rest.includes("--help") || rest.includes("-h")) {
     deps.log(DOCTOR_USAGE);
@@ -404,179 +208,96 @@ ${DOCTOR_USAGE}`);
     deps.error(`Could not run: no readable package.json found at ${deps.cwd}`);
     return 2;
   }
-  const report = runDoctor(snapshot);
-  deps.log(json ? renderJson(report) : renderHuman(report));
-  return report.exitCode;
+  const report2 = (0, import_tooling3.runDoctor)(snapshot);
+  deps.log(json ? (0, import_tooling3.renderJson)(report2) : (0, import_tooling3.renderHuman)(report2));
+  return report2.exitCode;
 }
-function runCli(argv, deps) {
-  const [verb, ...rest] = argv;
-  if (verb === void 0) {
-    deps.error(USAGE);
-    return 2;
-  }
-  if (verb === "--help" || verb === "-h") {
-    deps.log(USAGE);
-    return 0;
+function report(plan, parsed, deps) {
+  const options = { json: parsed.json };
+  if (parsed.options.dryRun) {
+    deps.print((0, import_tooling3.renderPlan)(plan, options));
+    return (0, import_tooling3.planExitCode)(plan);
   }
-  if (verb !== "doctor") {
-    deps.error(`Unknown command: ${verb}
-
-${USAGE}`);
-    return 2;
-  }
-  return runDoctorCommand(rest, deps);
+  const executed = (0, import_tooling3.applyPlan)(plan, deps.cwd);
+  deps.print((0, import_tooling3.renderReport)(executed, options));
+  return (0, import_tooling3.reportExitCode)(executed);
 }
-
-// src/doctor/environment.ts
-var import_node_fs = require("fs");
-var import_node_module = require("module");
-var import_node_path = require("path");
-var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
-  // Stryker disable next-line StringLiteral: equivalent — every dot-prefixed entry name is
-  // already excluded earlier, in visitEntry's leading-dot check (the only exception there is
-  // ".env", which isn't a directory this set would ever mention), so ".git" never actually
-  // reaches this set's `.has()` check.
-  ".git",
-  // Stryker disable next-line StringLiteral: same equivalence as ".git" above.
-  ".turbo",
-  // Stryker disable next-line StringLiteral: same equivalence as ".git" above.
-  ".stryker-tmp",
-  // Not dot-prefixed, so NOT equivalent — reaching this set's `.has()` check is the only thing
-  // that excludes each of the four names below; each is covered by a real test.
-  "node_modules",
-  "dist",
-  "build",
-  "coverage"
-]);
-var SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"];
-var BASE_PACKAGES = [
-  "vitest",
-  "@narrativetrace/core",
-  "@narrativetrace/core-node",
-  "@narrativetrace/vitest"
-];
-var MAX_FILES = 2e4;
-function readJson(path) {
+function runPlan(planner, parsed, deps) {
   try {
-    return JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
-  } catch {
-    return void 0;
+    return report(planner((0, import_tooling3.readProjectState)(deps.cwd, deps.env)), parsed, deps);
+  } catch (cause) {
+    deps.error(cause.message);
+    return 1;
   }
 }
-function resolvePackageJson(name, cwd) {
-  try {
-    const require2 = (0, import_node_module.createRequire)((0, import_node_path.join)(cwd, "package.json"));
-    return readJson(require2.resolve(`${name}/package.json`));
-  } catch {
-    return void 0;
-  }
+function noteVersions(carrier, state, deps) {
+  const warning = (0, import_tooling3.carrierVersionWarning)(carrier, state);
+  if (warning !== void 0) deps.error(warning);
 }
-function isDirectorySafe(path) {
+function runInit(parsed, deps) {
+  let carrier;
   try {
-    return (0, import_node_fs.statSync)(path).isDirectory();
-  } catch {
-    return void 0;
-  }
-}
-function safeRead(path) {
-  try {
-    return (0, import_node_fs.readFileSync)(path, "utf8");
-  } catch {
-    return "";
-  }
+    carrier = deps.openCarrier(parsed.from);
+  } catch (cause) {
+    deps.error(`${cause.message}
+
+${CARRIER_HINT}`);
+    return 1;
+  }
+  return runPlan(
+    (state) => {
+      noteVersions(carrier, state, deps);
+      return (0, import_tooling3.planInstall)(state, carrier, parsed.options);
+    },
+    parsed,
+    deps
+  );
 }
-function listDirectory(dir) {
-  try {
-    return (0, import_node_fs.readdirSync)(dir);
-  } catch {
-    return [];
+function runInstaller(install, rest, deps) {
+  const parsed = parseInstallerArguments(rest);
+  const usage = install ? INIT_USAGE : UNINSTALL_USAGE;
+  if (parsed.help) {
+    deps.log(usage);
+    return 0;
   }
-}
-function classify(rel, outputDirName, approvedDirName) {
-  const topSegment = rel.split("/")[0];
-  if (topSegment === outputDirName) return "output";
-  if (topSegment === approvedDirName) return "approved";
-  return SOURCE_EXTENSIONS.some((ext) => rel.endsWith(ext)) ? "source" : "skip";
-}
-function bucketFor(state, kind) {
-  return kind === "output" ? state.outputFiles : kind === "approved" ? state.approvedDirFiles : state.sourceFiles;
-}
-function visitEntry(ctx, dir, entry) {
-  if (entry.startsWith(".") && entry !== ".env") return;
-  const full = (0, import_node_path.join)(dir, entry);
-  const isDir = isDirectorySafe(full);
-  if (isDir === void 0) return;
-  if (isDir) {
-    if (!EXCLUDED_DIRS.has(entry)) ctx.queue.push(full);
-    return;
+  if (parsed.error !== void 0) {
+    deps.error(`${parsed.error}
+
+${usage}`);
+    return 2;
   }
-  ctx.state.visited++;
-  const rel = (0, import_node_path.relative)(ctx.root, full);
-  const kind = classify(rel, ctx.output, ctx.approved);
-  if (kind === "skip") return;
-  bucketFor(ctx.state, kind).set(rel, safeRead(full));
+  return install ? runInit(parsed, deps) : runPlan((state) => (0, import_tooling3.planUninstall)(state, parsed.options), parsed, deps);
 }
-function walk(root, output, approved) {
-  const state = {
-    sourceFiles: /* @__PURE__ */ new Map(),
-    outputFiles: /* @__PURE__ */ new Map(),
-    approvedDirFiles: /* @__PURE__ */ new Map(),
-    visited: 0
-  };
-  const ctx = { state, root, output, approved, queue: [root] };
-  while (ctx.queue.length > 0 && state.visited < MAX_FILES) {
-    const dir = ctx.queue.shift();
-    for (const entry of listDirectory(dir)) {
-      if (state.visited >= MAX_FILES) break;
-      visitEntry(ctx, dir, entry);
-    }
+function runCli(argv, deps) {
+  const [verb, ...rest] = argv;
+  if (verb === void 0) {
+    deps.error(USAGE);
+    return 2;
   }
-  return state;
-}
-function resolveBasePackages(cwd) {
-  const installed = /* @__PURE__ */ new Map();
-  for (const name of BASE_PACKAGES) {
-    const pkg = resolvePackageJson(name, cwd);
-    if (pkg) installed.set(name, pkg);
+  if (verb === "--help" || verb === "-h") {
+    deps.log(USAGE);
+    return 0;
   }
-  return installed;
-}
-function resolveVitestSiblings(cwd, installed) {
-  const ntVitest = installed.get("@narrativetrace/vitest");
-  for (const name of Object.keys(ntVitest?.dependencies ?? {})) {
-    if (!name.startsWith("@narrativetrace/") || installed.has(name)) continue;
-    const pkg = resolvePackageJson(name, cwd);
-    if (pkg) installed.set(name, pkg);
+  if (verb === "doctor") return runDoctorCommand(rest, deps);
+  if (verb === "init" || verb === "uninstall") {
+    return runInstaller(verb === "init", rest, deps);
   }
-}
-function resolveInstalledPackages(cwd) {
-  const installed = resolveBasePackages(cwd);
-  resolveVitestSiblings(cwd, installed);
-  return installed;
-}
-function buildSnapshot(cwd, env) {
-  const output = env.NARRATIVETRACE_OUTPUT_DIR ?? "narrativetrace-output";
-  const approved = env.NARRATIVETRACE_APPROVED_DIR ?? "narratives";
-  const { sourceFiles, outputFiles, approvedDirFiles } = walk(cwd, output, approved);
-  return {
-    cwd,
-    nodeVersion: process.version.replace(/^v/, ""),
-    env,
-    rootPackageJson: readJson((0, import_node_path.join)(cwd, "package.json")),
-    sourceFiles,
-    outputFiles,
-    approvedDirFiles,
-    installedPackages: resolveInstalledPackages(cwd)
-  };
+  deps.error(`Unknown command: ${verb}
+
+${USAGE}`);
+  return 2;
 }
 
 // src/cli-bin.ts
+var cwd = process.cwd();
 var exitCode = runCli(process.argv.slice(2), {
-  cwd: process.cwd(),
+  cwd,
   env: process.env,
-  buildSnapshot,
+  buildSnapshot: (c, e) => (0, import_tooling4.buildSnapshot)(c, e, cliPackageDirectory()),
+  openCarrier: (from) => openCarrierFor(cwd, from),
   log: (message) => process.stdout.write(`${message}
 `),
+  print: (text) => process.stdout.write(text),
   error: (message) => process.stderr.write(`${message}
 `)
 });