@vkmikc/create-vkm-kit 4.2.0

package/src/settings-io.mjs

@@ -0,0 +1,193 @@
+// Shared primitives for safely reading, merging and writing `~/.claude/settings.json`
+// (and any other user-owned JSON config this kit manages).
+//
+// Extracted from `claude-native-memory.mjs` (Phase 0 groundwork, ADR-0042 train) so new
+// installer modules (token-saver, telemetry, assets) can reuse the exact same battle-tested
+// idiom instead of copying it: read → BOM-strip → parse (backup invalid) → pure merge on a
+// copy → JSON.parse sanity → backup prior → atomic tmp + restrict + rename → symmetric
+// reconcile keyed on ownership markers/stems. Behavior is identical to the pre-extraction
+// code; the existing test suite is the refactor guard.
+//
+// Everything here is either PURE (the merge/remove helpers — never mutate their input) or
+// best-effort I/O with crash-safe semantics (the read/write helpers). Nothing in this module
+// logs; user-facing messages stay in the orchestrators that own the flow.
+import path from "node:path";
+import fse from "fs-extra";
+import { restrictFileToOwner } from "./file-perms.mjs";
+
+/** Literal string every hook/asset file this kit ships carries in its header comment. Used
+ * as a cheap-but-reliable ownership marker before `--uninstall` deletes a file by that name —
+ * a user's own unrelated same-named script is exceedingly unlikely to contain this exact
+ * npm package name in its source. */
+export const KIT_FILE_MARKER = "vkm-kit";
+
+/** Prior markers this kit shipped under other names. Ownership checks accept these too, so
+ * files installed by an older release are still recognized as ours after a rename. Filled at
+ * the 4.0.0 rename (ADR-0041); kept exported so reconcile paths can match both directions. */
+export const LEGACY_FILE_MARKERS = ["create-obsidian-memory"];
+
+/** Strip UTF-8 BOM so JSON.parse succeeds (common when a file was saved from PowerShell). */
+export function stripLeadingUtf8Bom(text) {
+  return typeof text === "string" && text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/**
+ * True if a raw `hooks[event][].hooks[]` entry belongs to this kit's `stem`. Recognizes
+ * BOTH the current exec form (`args` array — the stem shows up in an arg, since args[0] is
+ * always the hook's own file path) AND the legacy single-string shell form a prior version
+ * of this kit (or the even older `.ps1` variant) may have written — the stem is a substring
+ * of that command string too. Never matches an unrelated hook the user added themselves,
+ * since it requires the EXACT filename stem, not just the event/matcher.
+ * @param {unknown} h
+ * @param {string} stem
+ */
+export function hookEntryMatchesStem(h, stem) {
+  if (!h || typeof h !== "object") return false;
+  if (typeof h.command === "string" && h.command.includes(stem)) return true;
+  if (Array.isArray(h.args) && h.args.some((a) => typeof a === "string" && a.includes(stem))) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Merge ONE managed hook entry into `hooks[eventName]`, replacing any entry whose command
+ * matches `stem` (so re-runs, and a legacy variant of the same hook, never duplicate) and
+ * preserving every unrelated entry for that event.
+ * @param {Record<string, unknown>} hooks - the settings' `hooks` object (not mutated)
+ * @param {string} eventName - e.g. "SessionStart", "PreToolUse", "Stop"
+ * @param {string} matcher - hook matcher (e.g. "*" or a tool-name regex)
+ * @param {{ command: string, args: string[] }} hookEntry - exec-form hook command
+ * @param {string} stem - filename stem identifying our managed entry, for dedup
+ * @returns {Record<string, unknown>} a NEW hooks object
+ */
+export function mergeManagedHook(hooks, eventName, matcher, hookEntry, stem) {
+  const prior = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+  const kept = prior.filter((entry) => {
+    const inner = entry && Array.isArray(entry.hooks) ? entry.hooks : [];
+    return !inner.some((h) => hookEntryMatchesStem(h, stem));
+  });
+  kept.push({ matcher, hooks: [{ type: "command", ...hookEntry }] });
+  return { ...hooks, [eventName]: kept };
+}
+
+/**
+ * The removal counterpart to {@link mergeManagedHook}: strip any entry matching `stem` from
+ * `hooks[eventName]`, leaving every unrelated entry (ours or the user's own) untouched. If
+ * removal empties the array, the event key is deleted entirely rather than left as `[]`, so
+ * an uninstalled kit leaves no trace. A no-op (returns `hooks` structurally unchanged, modulo
+ * a shallow copy) when nothing matches — safe to call unconditionally.
+ * @param {Record<string, unknown>} hooks
+ * @param {string} eventName
+ * @param {string} stem
+ * @returns {Record<string, unknown>}
+ */
+export function removeManagedHook(hooks, eventName, stem) {
+  const prior = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+  const kept = prior.filter((entry) => {
+    const inner = entry && Array.isArray(entry.hooks) ? entry.hooks : [];
+    return !inner.some((h) => hookEntryMatchesStem(h, stem));
+  });
+  const next = { ...hooks };
+  if (kept.length) next[eventName] = kept;
+  else delete next[eventName];
+  return next;
+}
+
+/** Assign `settings.hooks = next`, unless `next` is empty AND `settings` never had a
+ * `hooks` key to begin with — avoids a removal function introducing a gratuitous
+ * `"hooks": {}` into settings that had no hooks at all before. */
+export function setOrDeleteHooks(settings, hadHooksBefore, next) {
+  if (Object.keys(next).length || hadHooksBefore) {
+    settings.hooks = next;
+  }
+  return settings;
+}
+
+/** True if `hooks[eventName]` currently contains a managed entry for `stem`. Used to decide
+ * whether a removal is a real action worth announcing (dry-run) or a pure no-op. */
+export function hasManagedHook(hooks, eventName, stem) {
+  const prior = hooks && Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+  return prior.some((entry) => {
+    const inner = entry && Array.isArray(entry.hooks) ? entry.hooks : [];
+    return inner.some((h) => hookEntryMatchesStem(h, stem));
+  });
+}
+
+/**
+ * Read a user-owned JSON settings file without ever throwing: missing file, empty file and
+ * invalid JSON are all first-class outcomes the caller reconciles against, not errors.
+ * The raw prior bytes are returned so the caller can (a) back them up before overwriting and
+ * (b) cheaply detect kit-owned entries by stem on the raw text even when the JSON is broken.
+ * @param {string} settingsFp
+ * @returns {Promise<{ existing: Record<string, unknown>, priorBytes: Buffer | null,
+ *   invalidJson: boolean, rawText: string }>}
+ */
+export async function readSettingsSafe(settingsFp) {
+  let existing = {};
+  let priorBytes = null;
+  let invalidJson = false;
+  if (await fse.pathExists(settingsFp)) {
+    priorBytes = await fse.readFile(settingsFp);
+    const raw = stripLeadingUtf8Bom(priorBytes.toString("utf8")).trim();
+    if (raw) {
+      try {
+        existing = JSON.parse(raw);
+      } catch {
+        invalidJson = true;
+      }
+    }
+  }
+  const rawText = priorBytes ? priorBytes.toString("utf8") : "";
+  return { existing, priorBytes, invalidJson, rawText };
+}
+
+/**
+ * Write `bytes` to a timestamped `<fp>.bak.<ts>` sibling, restricted to the current user
+ * (settings files can carry secrets in keys this kit doesn't own, e.g. a user's own `env`
+ * block). Returns the backup path so the caller can log it. Backups are kept indefinitely;
+ * clean up manually — agent-driven installs that go wrong should be 1 `mv` away from
+ * recovery.
+ * @param {string} fp
+ * @param {Buffer | string} bytes
+ * @returns {Promise<string>}
+ */
+export async function backupRestricted(fp, bytes) {
+  const bak = `${fp}.bak.${Date.now()}`;
+  await fse.writeFile(bak, bytes);
+  await restrictFileToOwner(bak);
+  return bak;
+}
+
+/**
+ * Write JSON to `fp` atomically: stage at `<fp>.tmp.<pid>.<ts>`, restrict to owner, rename.
+ * Crash mid-write leaves the original `fp` intact rather than truncating it. The payload is
+ * serialized with 2-space indent + trailing newline and parsed back once before the write —
+ * never write something that won't parse.
+ * @param {string} fp - target path
+ * @param {unknown} data - JSON-serializable payload
+ */
+export async function atomicWriteJson(fp, data) {
+  const out = `${JSON.stringify(data, null, 2)}\n`;
+  JSON.parse(out); // sanity: never write something that won't parse back
+  await fse.ensureDir(path.dirname(fp));
+  const tmp = `${fp}.tmp.${process.pid}.${Date.now()}`;
+  await fse.writeFile(tmp, out, "utf8");
+  await restrictFileToOwner(tmp);
+  await fse.rename(tmp, fp);
+}
+
+/** True if `fp` contains one of this kit's ownership markers, meaning it's safe to assume
+ * WE wrote it (as opposed to a user's own unrelated same-named file). Read failures
+ * (missing file, etc.) are treated as "not ours" — never delete on doubt.
+ * @param {string} fp
+ * @param {string[]} [markers]
+ */
+export async function isKitOwnedFile(fp, markers = [KIT_FILE_MARKER, ...LEGACY_FILE_MARKERS]) {
+  try {
+    const text = await fse.readFile(fp, "utf8");
+    return markers.some((marker) => text.includes(marker));
+  } catch {
+    return false;
+  }
+}

package/src/settings-writers.mjs

@@ -0,0 +1,150 @@
+// Pure merge/remove writers for the settings.json sections the token-saver and telemetry
+// modules manage: `env`, `permissions.{deny,allow}` and `outputStyle`.
+//
+// Same contract as the hook mergers in `settings-io.mjs`: never mutate the input, preserve
+// every unrelated key/entry, be idempotent under re-runs, and on removal only reverse what
+// we can PROVE is ours — a value the user has since changed is left alone (the same
+// principle `removeSessionStartHook` applies to `autoMemoryEnabled`). Emptied sections are
+// deleted entirely so an uninstalled kit leaves no trace.
+//
+// Nothing here does I/O or logs; orchestrators own the read→merge→write flow via
+// `readSettingsSafe`/`atomicWriteJson` from `settings-io.mjs`.
+
+/** Shallow-copy `existing` when it's a plain object; otherwise start fresh (same guard the
+ * hook mergers use — a corrupt/array/null settings value must never crash a merge). */
+function asSettingsObject(existing) {
+  return existing && typeof existing === "object" && !Array.isArray(existing)
+    ? { ...existing }
+    : {};
+}
+
+/** Plain-object guard for a nested section (`env`, `permissions`). */
+function asSection(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? { ...value } : {};
+}
+
+/**
+ * Set every `envMap` key in `settings.env`, preserving unrelated env vars. Last write wins
+ * for our own keys (re-runs converge). `envMap` values are coerced to strings — settings
+ * env blocks are string-valued.
+ * @param {unknown} existing - parsed `settings.json` (or anything; non-objects are ignored)
+ * @param {Record<string, string | number | boolean>} envMap
+ * @returns {Record<string, unknown>}
+ */
+export function mergeManagedEnv(existing, envMap) {
+  const settings = asSettingsObject(existing);
+  const env = asSection(settings.env);
+  for (const [key, value] of Object.entries(envMap ?? {})) {
+    env[key] = String(value);
+  }
+  settings.env = env;
+  return settings;
+}
+
+/**
+ * The removal counterpart to {@link mergeManagedEnv}: delete each `envMap` key from
+ * `settings.env` ONLY when its current value is still exactly what this kit would have set
+ * — a user-tuned value (e.g. a custom OTLP endpoint) is never silently reverted. Deletes
+ * the `env` section entirely when removal empties it.
+ * @param {unknown} existing
+ * @param {Record<string, string | number | boolean>} envMap - keys + the values we set
+ * @returns {Record<string, unknown>}
+ */
+export function removeManagedEnv(existing, envMap) {
+  const settings = asSettingsObject(existing);
+  if (!settings.env || typeof settings.env !== "object" || Array.isArray(settings.env)) {
+    return settings;
+  }
+  const env = { ...settings.env };
+  for (const [key, value] of Object.entries(envMap ?? {})) {
+    if (env[key] === String(value)) delete env[key];
+  }
+  if (Object.keys(env).length) settings.env = env;
+  else delete settings.env;
+  return settings;
+}
+
+/** Append `rules` to `list` preserving the user's order and entries; ours land at the end,
+ * deduped by exact string so re-runs never duplicate. */
+function mergeRuleList(list, rules) {
+  const prior = Array.isArray(list) ? [...list] : [];
+  for (const rule of rules) {
+    if (!prior.includes(rule)) prior.push(rule);
+  }
+  return prior;
+}
+
+/**
+ * Merge managed permission rules into `settings.permissions.{deny,allow}` (exact-string
+ * dedup; user rules and their order preserved; ours appended).
+ * @param {unknown} existing
+ * @param {{ deny?: string[], allow?: string[] }} rules
+ * @returns {Record<string, unknown>}
+ */
+export function mergeManagedPermissions(existing, { deny = [], allow = [] } = {}) {
+  const settings = asSettingsObject(existing);
+  const permissions = asSection(settings.permissions);
+  if (deny.length) permissions.deny = mergeRuleList(permissions.deny, deny);
+  if (allow.length) permissions.allow = mergeRuleList(permissions.allow, allow);
+  settings.permissions = permissions;
+  return settings;
+}
+
+/**
+ * The removal counterpart to {@link mergeManagedPermissions}: strip exactly the given rule
+ * strings, leaving every other rule (the user's own) untouched. Emptied arrays and an
+ * emptied `permissions` section are deleted entirely.
+ * @param {unknown} existing
+ * @param {{ deny?: string[], allow?: string[] }} rules
+ * @returns {Record<string, unknown>}
+ */
+export function removeManagedPermissions(existing, { deny = [], allow = [] } = {}) {
+  const settings = asSettingsObject(existing);
+  if (
+    !settings.permissions ||
+    typeof settings.permissions !== "object" ||
+    Array.isArray(settings.permissions)
+  ) {
+    return settings;
+  }
+  const permissions = { ...settings.permissions };
+  for (const [key, ours] of [
+    ["deny", deny],
+    ["allow", allow]
+  ]) {
+    if (!Array.isArray(permissions[key])) continue;
+    const kept = permissions[key].filter((rule) => !ours.includes(rule));
+    if (kept.length) permissions[key] = kept;
+    else delete permissions[key];
+  }
+  if (Object.keys(permissions).length) settings.permissions = permissions;
+  else delete settings.permissions;
+  return settings;
+}
+
+/**
+ * Set `settings.outputStyle` to the kit-shipped style. Overwrites a prior value — the
+ * install flow only calls this when the user opted in (default ON under `--full`), and the
+ * removal below refuses to touch anything that isn't exactly ours.
+ * @param {unknown} existing
+ * @param {string} name - output style name (e.g. "vkm-terse")
+ * @returns {Record<string, unknown>}
+ */
+export function setManagedOutputStyle(existing, name) {
+  const settings = asSettingsObject(existing);
+  settings.outputStyle = name;
+  return settings;
+}
+
+/**
+ * The removal counterpart to {@link setManagedOutputStyle}: delete `outputStyle` ONLY when
+ * it still points at our style — a user who switched styles afterwards keeps their choice.
+ * @param {unknown} existing
+ * @param {string} name
+ * @returns {Record<string, unknown>}
+ */
+export function clearManagedOutputStyle(existing, name) {
+  const settings = asSettingsObject(existing);
+  if (settings.outputStyle === name) delete settings.outputStyle;
+  return settings;
+}

package/src/skills-install.mjs

@@ -0,0 +1,96 @@
+// vkm-kit skills + subagent installer (ADR-0049): copies the discipline/spec skills into
+// `~/.claude/skills/` and the implementer subagent template into `~/.claude/agents/`.
+// Pure file assets — no settings.json changes — tracked by content hash through
+// `asset-install.mjs`, so uninstall never deletes a file the user customized. Skills load
+// their body only when invoked (Claude Code progressive disclosure); the always-in-context
+// cost is just each skill's frontmatter description.
+import path from "node:path";
+import { readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import pc from "picocolors";
+import {
+  ASSETS_SIDECAR_BASENAME,
+  installManagedAssets,
+  removeManagedAssets
+} from "./asset-install.mjs";
+
+export const SKILL_NAMES = ["vkm-discipline", "vkm-spec"];
+export const AGENT_BASENAMES = ["vkm-implementer.md"];
+
+function templatesDir() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "templates");
+}
+
+/** The {src,dest} pairs for each asset group under a given `home`. */
+/** Every file under a skill's template dir (SKILL.md + any domain/reference files), as {src,dest}. */
+function skillDirFiles(name, claudeDir) {
+  const root = path.join(templatesDir(), "skills", name);
+  const out = [];
+  for (const rel of readdirSync(root, { recursive: true })) {
+    const src = path.join(root, String(rel));
+    if (!statSync(src).isFile()) continue;
+    out.push({ src, dest: path.join(claudeDir, "skills", name, String(rel)) });
+  }
+  return out;
+}
+
+export function skillAssetFiles(home, { skills = true, agents = true } = {}) {
+  const claudeDir = path.join(home, ".claude");
+  const files = [];
+  if (skills) {
+    for (const name of SKILL_NAMES) files.push(...skillDirFiles(name, claudeDir));
+  }
+  if (agents) {
+    for (const basename of AGENT_BASENAMES) {
+      files.push({
+        src: path.join(templatesDir(), "agents", basename),
+        dest: path.join(claudeDir, "agents", basename)
+      });
+    }
+  }
+  return files;
+}
+
+/**
+ * Install / reconcile / remove the skill + agent assets. Symmetric like the sibling
+ * modules: a piece that is NOT wanted is actively removed (hash-guarded).
+ * @param {string} home
+ * @param {boolean} dryRun
+ * @param {{ skills?: boolean, agents?: boolean }} [opts]
+ */
+export async function configureSkillAssets(home, dryRun, { skills = true, agents = true } = {}) {
+  const sidecarFp = path.join(home, ".claude", ASSETS_SIDECAR_BASENAME);
+  try {
+    const wanted = skillAssetFiles(home, { skills, agents });
+    const unwanted = skillAssetFiles(home, { skills: !skills, agents: !agents });
+    if (dryRun) {
+      for (const { dest } of wanted) console.log(pc.cyan("[dry-run] would install"), pc.dim(dest));
+      for (const { dest } of unwanted) {
+        console.log(pc.cyan("[dry-run] would remove (if unmodified)"), pc.dim(dest));
+      }
+      return;
+    }
+    if (wanted.length) {
+      const { installed } = await installManagedAssets({ files: wanted, sidecarFp });
+      if (skills) console.log(pc.green("Skills installed:"), pc.dim(SKILL_NAMES.join(", ")));
+      if (agents) {
+        console.log(pc.green("Subagent template installed:"), pc.dim(AGENT_BASENAMES.join(", ")));
+      }
+      void installed;
+    }
+    if (unwanted.length) {
+      const { skipped } = await removeManagedAssets({
+        sidecarFp,
+        dests: unwanted.map((f) => f.dest)
+      });
+      for (const fp of skipped) console.warn(pc.yellow("Kept (modified by user):"), fp);
+    }
+  } catch (e) {
+    console.warn(pc.yellow("Could not configure vkm skills/agents (skipped):"), e?.message || e);
+  }
+}
+
+/** Full teardown of both groups (hash-guarded). */
+export async function uninstallSkillAssets(home, dryRun) {
+  await configureSkillAssets(home, dryRun, { skills: false, agents: false });
+}

package/src/telemetry.mjs

@@ -0,0 +1,154 @@
+// vkm-kit local telemetry installer (ADR-0044): wires Claude Code's OTLP metrics export to
+// the local vkm-otel-sink so `vkm-doctor` has real usage data. LOCAL ONLY by construction —
+// the endpoint is 127.0.0.1 and the sink persists to `~/.vkm/telemetry/`; nothing leaves
+// the machine. Two managed pieces, reconciled symmetrically like every other module:
+// (1) the four OTEL env vars in settings.json (`env` block, removal only reverts values
+// still exactly ours), (2) a SessionStart hook that spawns the sink when it isn't running.
+// The sink script itself lives in the kit checkout (`packages/vkm-doctor/`), same
+// wire-by-absolute-path model as the hybrid MCP server — so telemetry needs a kit clone
+// (callers pass `kitRoot`; without one this module is skipped with a hint).
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fse from "fs-extra";
+import pc from "picocolors";
+import {
+  atomicWriteJson,
+  backupRestricted,
+  isKitOwnedFile,
+  mergeManagedHook,
+  readSettingsSafe,
+  removeManagedHook,
+  setOrDeleteHooks
+} from "./settings-io.mjs";
+import { mergeManagedEnv, removeManagedEnv } from "./settings-writers.mjs";
+
+export const ENSURE_SINK_HOOK_STEM = "ensure-otel-sink";
+export const ENSURE_SINK_HOOK_BASENAME = `${ENSURE_SINK_HOOK_STEM}.mjs`;
+
+/** The managed env block (values must stay in sync with vkm-doctor's DEFAULT_PORT). */
+export const TELEMETRY_ENV = {
+  CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+  OTEL_METRICS_EXPORTER: "otlp",
+  OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
+  OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4319"
+};
+
+function packagedHookPath(basename) {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "hooks", basename);
+}
+
+/** `<kitRoot>/packages/vkm-doctor/src/otel-sink.mjs` (the script the hook spawns). */
+export function sinkScriptFromKitRoot(kitRoot) {
+  return path.join(kitRoot, "packages", "vkm-doctor", "src", "otel-sink.mjs");
+}
+
+/**
+ * Install / reconcile / remove local telemetry. Same symmetric contract as the sibling
+ * modules; `enable:false` strips a prior install. Needs `kitRoot` only when enabling.
+ * @param {string} home
+ * @param {boolean} dryRun
+ * @param {{ enable?: boolean, kitRoot?: string | null }} [opts]
+ */
+export async function configureTelemetry(home, dryRun, { enable = true, kitRoot = null } = {}) {
+  const claudeDir = path.join(home, ".claude");
+  const hooksDir = path.join(claudeDir, "hooks");
+  const settingsFp = path.join(claudeDir, "settings.json");
+  const hookDest = path.join(hooksDir, ENSURE_SINK_HOOK_BASENAME);
+
+  try {
+    if (enable && !kitRoot) {
+      console.log(
+        pc.dim("Telemetry skipped: needs a kit clone (--repo-root) to host the OTLP sink.")
+      );
+      return;
+    }
+    let { existing, priorBytes, invalidJson, rawText } = await readSettingsSafe(settingsFp);
+    const oursPresent =
+      rawText.includes(ENSURE_SINK_HOOK_STEM) || rawText.includes("CLAUDE_CODE_ENABLE_TELEMETRY");
+    if (!enable && !oursPresent) return;
+
+    if (dryRun) {
+      console.log(
+        pc.cyan(
+          enable
+            ? "[dry-run] would enable LOCAL telemetry (OTEL env → 127.0.0.1:4319 + SessionStart sink hook)"
+            : "[dry-run] would remove the telemetry env block + sink hook"
+        )
+      );
+      return;
+    }
+
+    const sinkScript = enable ? sinkScriptFromKitRoot(kitRoot) : null;
+    if (enable) {
+      await fse.ensureDir(hooksDir);
+      await fse.copy(packagedHookPath(ENSURE_SINK_HOOK_BASENAME), hookDest, { overwrite: true });
+    }
+
+    if (invalidJson) {
+      const bak = await backupRestricted(settingsFp, priorBytes);
+      console.warn(pc.yellow("Invalid JSON in ~/.claude/settings.json; backed up to"), bak);
+      existing = {};
+    }
+
+    let merged = enable
+      ? mergeManagedEnv(existing, TELEMETRY_ENV)
+      : removeManagedEnv(existing, TELEMETRY_ENV);
+    const hadHooks =
+      merged.hooks && typeof merged.hooks === "object" && !Array.isArray(merged.hooks);
+    let hookMap = hadHooks ? merged.hooks : {};
+    hookMap = enable
+      ? mergeManagedHook(
+          hookMap,
+          "SessionStart",
+          "*",
+          { command: "node", args: [hookDest, sinkScript] },
+          ENSURE_SINK_HOOK_STEM
+        )
+      : removeManagedHook(hookMap, "SessionStart", ENSURE_SINK_HOOK_STEM);
+    merged = setOrDeleteHooks(merged, Boolean(hadHooks), hookMap);
+
+    if (priorBytes && !invalidJson) {
+      const bak = await backupRestricted(settingsFp, priorBytes);
+      console.log(pc.dim("Backed up previous settings.json to"), bak);
+    }
+    await atomicWriteJson(settingsFp, merged);
+
+    if (enable) {
+      console.log(
+        pc.green("Local telemetry:"),
+        pc.dim("OTEL → 127.0.0.1:4319 → ~/.vkm/telemetry/ (run `vkm-doctor` for the report)")
+      );
+    } else if (oursPresent) {
+      console.log(pc.green("Local telemetry removed:"), settingsFp);
+    }
+  } catch (e) {
+    console.warn(pc.yellow("Could not configure telemetry (skipped):"), e?.message || e);
+  }
+}
+
+/** Full teardown: settings pieces + the hook script file (marker-checked). */
+export async function uninstallTelemetry(home, dryRun) {
+  await configureTelemetry(home, dryRun, { enable: false });
+  const fp = path.join(home, ".claude", "hooks", ENSURE_SINK_HOOK_BASENAME);
+  if (!(await fse.pathExists(fp))) return;
+  const owned = await isKitOwnedFile(fp);
+  if (dryRun) {
+    console.log(
+      owned
+        ? pc.cyan("[dry-run] would remove")
+        : pc.yellow("[dry-run] would SKIP (not recognized as this kit's file)"),
+      pc.dim(fp)
+    );
+    return;
+  }
+  if (!owned) {
+    console.warn(pc.yellow("Skipped (not recognized as this kit's file):"), fp);
+    return;
+  }
+  try {
+    await fse.remove(fp);
+    console.log(pc.green("Removed"), pc.dim(fp));
+  } catch (e) {
+    console.warn(pc.yellow("Could not remove"), fp, e?.message || e);
+  }
+}