fathom-cli 0.3.5 → 0.3.6

package/dist/index.js

@@ -102,7 +102,7 @@ var require_extend = __commonJS({
 
 // src/index.ts
 import "dotenv/config";
-import { Command as Command22 } from "commander";
+import { Command as Command24 } from "commander";
 
 // ../../node_modules/.pnpm/bail@2.0.2/node_modules/bail/index.js
 function bail(error) {
@@ -1104,7 +1104,7 @@ var Processor = class _Processor extends CallableInstance {
     assertParser("process", this.parser || this.Parser);
     assertCompiler("process", this.compiler || this.Compiler);
     return done ? executor(void 0, done) : new Promise(executor);
-    function executor(resolve25, reject) {
+    function executor(resolve26, reject) {
       const realFile = vfile(file);
       const parseTree = (
         /** @type {HeadTree extends undefined ? Node : HeadTree} */
@@ -1135,8 +1135,8 @@ var Processor = class _Processor extends CallableInstance {
       function realDone(error, file2) {
         if (error || !file2) {
           reject(error);
-        } else if (resolve25) {
-          resolve25(file2);
+        } else if (resolve26) {
+          resolve26(file2);
         } else {
           ok(done, "`done` is defined if `resolve` is not");
           done(void 0, file2);
@@ -1238,7 +1238,7 @@ var Processor = class _Processor extends CallableInstance {
       file = void 0;
     }
     return done ? executor(void 0, done) : new Promise(executor);
-    function executor(resolve25, reject) {
+    function executor(resolve26, reject) {
       ok(
         typeof file !== "function",
         "`file` can\u2019t be a `done` anymore, we checked"
@@ -1252,8 +1252,8 @@ var Processor = class _Processor extends CallableInstance {
         );
         if (error) {
           reject(error);
-        } else if (resolve25) {
-          resolve25(resultingTree);
+        } else if (resolve26) {
+          resolve26(resultingTree);
         } else {
           ok(done, "`done` is defined if `resolve` is not");
           done(void 0, resultingTree, file2);
@@ -4081,10 +4081,10 @@ function resolveAll(constructs2, events, context) {
   const called = [];
   let index2 = -1;
   while (++index2 < constructs2.length) {
-    const resolve25 = constructs2[index2].resolveAll;
-    if (resolve25 && !called.includes(resolve25)) {
-      events = resolve25(events, context);
-      called.push(resolve25);
+    const resolve26 = constructs2[index2].resolveAll;
+    if (resolve26 && !called.includes(resolve26)) {
+      events = resolve26(events, context);
+      called.push(resolve26);
     }
   }
   return events;
@@ -8533,7 +8533,12 @@ var FeatureEstimate = external_exports.object({
     errorRecovery: external_exports.number(),
     planning: external_exports.number(),
     review: external_exports.number()
-  })
+  }),
+  confidence: external_exports.object({
+    low: external_exports.object({ tokens: external_exports.number(), cost: external_exports.number() }),
+    expected: external_exports.object({ tokens: external_exports.number(), cost: external_exports.number() }),
+    high: external_exports.object({ tokens: external_exports.number(), cost: external_exports.number() })
+  }).optional()
 });
 var SensitivityScenario = external_exports.object({
   name: external_exports.string(),
@@ -8751,7 +8756,7 @@ var AgentsFile = external_exports.object({
 });
 function loadYaml(filePath, schema) {
   const content3 = readFileSync(filePath, "utf-8");
-  const raw = jsYaml.load(content3);
+  const raw = jsYaml.load(content3, { schema: jsYaml.JSON_SCHEMA });
   return schema.parse(raw);
 }
 function findDataDir() {
@@ -8764,18 +8769,32 @@ function findDataDir() {
     return resolve(base, "../../../data");
   }
 }
-function loadData(dataDir) {
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+var cacheMap = /* @__PURE__ */ new Map();
+function loadData(dataDir, ttlMs) {
   const dir = dataDir ?? findDataDir();
+  const resolvedDir = resolve(dir);
+  const ttl = ttlMs ?? DEFAULT_TTL_MS;
+  if (ttl > 0) {
+    const cached = cacheMap.get(resolvedDir);
+    if (cached && Date.now() - cached.timestamp < ttl) {
+      return cached.data;
+    }
+  }
   const modelsFile = loadYaml(resolve(dir, "models.yaml"), ModelsFile);
   const profilesFile = loadYaml(resolve(dir, "task-profiles.yaml"), TaskProfilesFile);
   const agentsFile = loadYaml(resolve(dir, "agents.yaml"), AgentsFile);
-  return {
+  const data = {
     models: modelsFile.models,
     profiles: profilesFile.profiles,
     complexityMultipliers: profilesFile.complexity_multipliers,
     overhead: profilesFile.overhead_multipliers,
     recommendations: agentsFile.recommendations
   };
+  if (ttl > 0) {
+    cacheMap.set(resolvedDir, { data, timestamp: Date.now() });
+  }
+  return data;
 }
 function getProfile(profiles, taskType) {
   return profiles[taskType];
@@ -8861,6 +8880,20 @@ function estimateFeature(feature, data) {
   const overheadOutput = Math.round(baseOutput * multiplier + breakdown.toolCalls * 0.75);
   const overheadTotal = overheadInput + overheadOutput;
   const cost = calculateCost(overheadInput, overheadOutput, pricing);
+  const confidence = {
+    low: {
+      tokens: Math.round(overheadTotal * 0.7),
+      cost: Math.round(cost * 0.7 * 100) / 100
+    },
+    expected: {
+      tokens: overheadTotal,
+      cost
+    },
+    high: {
+      tokens: Math.round(overheadTotal * 1.5),
+      cost: Math.round(cost * 1.5 * 100) / 100
+    }
+  };
   return {
     featureId: feature.id,
     featureName: feature.name,
@@ -8871,7 +8904,8 @@ function estimateFeature(feature, data) {
     baseTokens: { input: baseInput, output: baseOutput, total: baseTotal },
     withOverhead: { input: overheadInput, output: overheadOutput, total: overheadTotal },
     estimatedCost: cost,
-    overheadBreakdown: breakdown
+    overheadBreakdown: breakdown,
+    confidence
   };
 }
 function estimateAll(features, data) {
@@ -10005,7 +10039,40 @@ async function syncVelocity(data) {
   }
 }
 
+// src/ux/spinner.ts
+var FRAMES = ["\u28CB", "\u28D9", "\u28F9", "\u28F8", "\u28FC", "\u28F4", "\u28E6", "\u28E7", "\u28C7", "\u28CF"];
+var INTERVAL_MS = 80;
+async function withSpinner(text3, fn) {
+  const start = Date.now();
+  const isTTY = process.stderr.isTTY;
+  if (!isTTY) {
+    return fn();
+  }
+  let frameIndex = 0;
+  const timer = setInterval(() => {
+    const frame = FRAMES[frameIndex % FRAMES.length];
+    process.stderr.write(`\r\x1B[K${frame} ${text3}`);
+    frameIndex++;
+  }, INTERVAL_MS);
+  try {
+    const result = await fn();
+    clearInterval(timer);
+    const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
+    process.stderr.write(`\r\x1B[K\x1B[32m\u2713\x1B[0m ${text3} (${elapsed}s)
+`);
+    return result;
+  } catch (error) {
+    clearInterval(timer);
+    process.stderr.write(`\r\x1B[K\x1B[31m\u2717\x1B[0m ${text3}
+`);
+    throw error;
+  }
+}
+
 // src/commands/intake.ts
+function isWithinBoundary(resolvedPath, boundary) {
+  return resolvedPath.startsWith(boundary);
+}
 function findLocalMarkdownFiles() {
   try {
     const cwd = process.cwd();
@@ -10027,16 +10094,24 @@ async function runIntakeFlow(projectName) {
     process.exit(1);
   }
   const provider = hasAnthropicKey ? "anthropic" : "openai";
-  console.log(chalk3.dim(`
-  Extracting work items via ${provider === "anthropic" ? "Claude" : "OpenAI"}...`));
   let items;
   try {
-    items = await extractWorkItems(rawInput, {
-      provider,
-      ...provider === "openai" ? { openaiApiKey: process.env.OPENAI_API_KEY } : {}
-    });
+    items = await withSpinner(
+      `Extracting work items via ${provider === "anthropic" ? "Claude" : "OpenAI"}...`,
+      async () => extractWorkItems(rawInput, {
+        provider,
+        ...provider === "openai" ? { openaiApiKey: process.env.OPENAI_API_KEY } : {}
+      })
+    );
   } catch (err) {
-    console.error(chalk3.red("  Extraction failed:"), err.message);
+    let errMsg = err.message;
+    for (const envKey of ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]) {
+      const val = process.env[envKey];
+      if (val && errMsg.includes(val)) {
+        errMsg = errMsg.replaceAll(val, val.length <= 6 ? "***" : val.slice(0, 3) + "***" + val.slice(-3));
+      }
+    }
+    console.error(chalk3.red("  Extraction failed:"), errMsg);
     process.exit(1);
   }
   if (items.length === 0) {
@@ -10094,6 +10169,10 @@ async function resolveInput(cwd) {
     } else if (chosen === "__other__") {
       const filePath = await input({ message: "Path to input file:", default: cwd + "/" });
       const resolved = resolve5(filePath.trim());
+      if (!isWithinBoundary(resolved, cwd)) {
+        console.error(chalk3.red("Path traversal rejected: file must be within project directory"));
+        process.exit(1);
+      }
       if (!existsSync4(resolved)) {
         console.error(chalk3.red(`File not found: ${resolved}`));
         process.exit(1);
@@ -10113,6 +10192,10 @@ async function resolveInput(cwd) {
   if (inputType === "file") {
     const filePath = await input({ message: "Path to input file:", default: cwd + "/" });
     const resolved = resolve5(filePath.trim());
+    if (!isWithinBoundary(resolved, cwd)) {
+      console.error(chalk3.red("Path traversal rejected: file must be within project directory"));
+      process.exit(1);
+    }
     if (!existsSync4(resolved)) {
       console.error(chalk3.red(`File not found: ${resolved}`));
       process.exit(1);
@@ -10175,6 +10258,10 @@ var intakeCommand = new Command2("intake").description("Extract work items from
     let source;
     if (options.file) {
       const filePath = resolve5(options.file);
+      if (!isWithinBoundary(filePath, cwd)) {
+        console.error(chalk3.red("Path traversal rejected: file must be within project directory"));
+        process.exit(1);
+      }
       if (!existsSync4(filePath)) {
         console.error(chalk3.red(`File not found: ${filePath}`));
         process.exit(1);
@@ -10210,6 +10297,10 @@ var intakeCommand = new Command2("intake").description("Extract work items from
             default: cwd + "/"
           });
           const resolved = resolve5(filePath.trim());
+          if (!isWithinBoundary(resolved, cwd)) {
+            console.error(chalk3.red("Path traversal rejected: file must be within project directory"));
+            process.exit(1);
+          }
           if (!existsSync4(resolved)) {
             console.error(chalk3.red(`File not found: ${resolved}`));
             process.exit(1);
@@ -10234,6 +10325,10 @@ var intakeCommand = new Command2("intake").description("Extract work items from
             default: cwd + "/"
           });
           const resolved = resolve5(filePath.trim());
+          if (!isWithinBoundary(resolved, cwd)) {
+            console.error(chalk3.red("Path traversal rejected: file must be within project directory"));
+            process.exit(1);
+          }
           if (!existsSync4(resolved)) {
             console.error(chalk3.red(`File not found: ${resolved}`));
             process.exit(1);
@@ -10263,16 +10358,24 @@ var intakeCommand = new Command2("intake").description("Extract work items from
       }
       provider = hasAnthropicKey ? "anthropic" : "openai";
     }
-    console.log(chalk3.dim(`
-Extracting work items via ${provider === "anthropic" ? "Claude" : "OpenAI"}...`));
     let items;
     try {
-      items = await extractWorkItems(rawInput, {
-        provider,
-        ...provider === "openai" ? { openaiApiKey: process.env.OPENAI_API_KEY } : {}
-      });
+      items = await withSpinner(
+        `Extracting work items via ${provider === "anthropic" ? "Claude" : "OpenAI"}...`,
+        async () => extractWorkItems(rawInput, {
+          provider,
+          ...provider === "openai" ? { openaiApiKey: process.env.OPENAI_API_KEY } : {}
+        })
+      );
     } catch (err) {
-      console.error(chalk3.red("Extraction failed:"), err.message);
+      let errMsg = err.message;
+      for (const envKey of ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]) {
+        const val = process.env[envKey];
+        if (val && errMsg.includes(val)) {
+          errMsg = errMsg.replaceAll(val, val.length <= 6 ? "***" : val.slice(0, 3) + "***" + val.slice(-3));
+        }
+      }
+      console.error(chalk3.red("Extraction failed:"), errMsg);
       process.exit(1);
     }
     if (items.length === 0) {
@@ -10754,9 +10857,9 @@ async function runSettingsFlow(projectName) {
     switch (setting) {
       case "intent": {
         const intentData = await captureIntentFlow(projectName);
-        const { saveIntent } = await import("./dist-XKZLNUDU.js");
+        const { saveIntent } = await import("./dist-VMLJKWUO.js");
         await saveIntent(process.cwd(), intentData);
-        const { writeProjections } = await import("./dist-KXBSLOHP.js");
+        const { writeProjections } = await import("./dist-HPXMBCZX.js");
         const files = await writeProjections(process.cwd(), intentData);
         console.log(chalk4.green(`
   \u2713 Intent saved to .fathom/intent.yaml`));
@@ -10765,7 +10868,7 @@ async function runSettingsFlow(projectName) {
         break;
       }
       case "budget": {
-        const { loadIntent, saveIntent } = await import("./dist-XKZLNUDU.js");
+        const { loadIntent, saveIntent } = await import("./dist-VMLJKWUO.js");
         let existing;
         try {
           existing = await loadIntent(process.cwd());
@@ -10823,11 +10926,11 @@ var goCommand = new Command3("go").description("Run the full workflow: intake \u
       });
       if (captureNow) {
         const intentData = await captureIntentFlow(projectName);
-        const { saveIntent } = await import("./dist-XKZLNUDU.js");
+        const { saveIntent } = await import("./dist-VMLJKWUO.js");
         await saveIntent(process.cwd(), intentData);
         projectName = intentData.project;
         updateProjectConfig({ project: projectName });
-        const { writeProjections } = await import("./dist-KXBSLOHP.js");
+        const { writeProjections } = await import("./dist-HPXMBCZX.js");
         const files = await writeProjections(process.cwd(), intentData);
         console.log(chalk4.green(`
   \u2713 Intent saved to .fathom/intent.yaml`));
@@ -10841,11 +10944,11 @@ var goCommand = new Command3("go").description("Run the full workflow: intake \u
       console.log();
       const intentData = await captureIntentFlow(basename3(process.cwd()));
       projectName = intentData.project;
-      const { saveIntent } = await import("./dist-XKZLNUDU.js");
+      const { saveIntent } = await import("./dist-VMLJKWUO.js");
       await saveIntent(process.cwd(), intentData);
       scaffoldProject(projectName, { quiet: true });
       updateProjectConfig({ project: projectName });
-      const { writeProjections } = await import("./dist-KXBSLOHP.js");
+      const { writeProjections } = await import("./dist-HPXMBCZX.js");
       const files = await writeProjections(process.cwd(), intentData);
       console.log(chalk4.green(`
   \u2713 Project "${projectName}" initialized`));
@@ -11075,16 +11178,23 @@ async function executeBuildMode(mode, promptPath, state) {
         console.log(chalk4.yellow("  No features in queue for worktree."));
         return false;
       }
+      if (!/^[a-zA-Z0-9_-]+$/.test(featureId)) {
+        console.log(chalk4.red(`  Invalid feature ID: "${featureId}" \u2014 only letters, digits, hyphens, underscores allowed`));
+        return false;
+      }
       const worktreePath = resolve7(process.cwd(), ".worktrees", featureId);
       const branchName = `feat/${featureId}`;
       console.log(chalk4.dim(`
   Creating worktree: ${branchName}`));
       try {
-        const { execSync: execSync2 } = await import("child_process");
-        execSync2(`git worktree add "${worktreePath}" -b "${branchName}"`, {
+        const { spawnSync } = await import("child_process");
+        const result = spawnSync("git", ["worktree", "add", worktreePath, "-b", branchName], {
           stdio: "pipe",
           cwd: process.cwd()
         });
+        if (result.status !== 0) {
+          throw new Error(result.stderr?.toString() || "git worktree failed");
+        }
         console.log(chalk4.green(`  \u2713 Worktree created at ${worktreePath}`));
       } catch {
         console.log(chalk4.yellow(`  \u26A0 Worktree creation failed \u2014 launching in current directory`));
@@ -11113,7 +11223,7 @@ async function executeBuildMode(mode, promptPath, state) {
   return false;
 }
 function launchClaude(promptPath, cwd, firstFeature) {
-  return new Promise((resolve25) => {
+  return new Promise((resolve26) => {
     const promptContent = readFileSync7(promptPath, "utf-8");
     const initialPrompt = firstFeature ? `Read the build context in your system prompt. Start working on feature \`${firstFeature}\` \u2014 read the spec reference, plan the implementation, and begin.` : "Read the build context in your system prompt and start working on the first feature in the priority queue.";
     const child = spawn("claude", ["--append-system-prompt", promptContent, initialPrompt], {
@@ -11130,11 +11240,11 @@ function launchClaude(promptPath, cwd, firstFeature) {
       } else {
         console.error(chalk4.red(`  Failed to launch Claude Code: ${err.message}`));
       }
-      resolve25();
+      resolve26();
     });
     child.on("close", () => {
       process.removeListener("SIGINT", sigintHandler);
-      resolve25();
+      resolve26();
     });
   });
 }
@@ -11312,21 +11422,24 @@ var pricingCommand = new Command5("pricing").description("Show current model pri
   if (options.sync) {
     const client = getConvexClient();
     if (client) {
-      let synced = 0;
-      for (const m of data.models) {
-        try {
-          await client.mutation(api.modelPricing.upsert, {
-            model: m.name,
-            provider: "anthropic",
-            inputPerMTok: m.input_per_mtok,
-            outputPerMTok: m.output_per_mtok,
-            cacheReadPerMTok: m.cache_read_per_mtok,
-            batchDiscount: m.batch_discount
-          });
-          synced++;
-        } catch {
+      const synced = await withSpinner("Fetching latest pricing data...", async () => {
+        let count = 0;
+        for (const m of data.models) {
+          try {
+            await client.mutation(api.modelPricing.upsert, {
+              model: m.name,
+              provider: "anthropic",
+              inputPerMTok: m.input_per_mtok,
+              outputPerMTok: m.output_per_mtok,
+              cacheReadPerMTok: m.cache_read_per_mtok,
+              batchDiscount: m.batch_discount
+            });
+            count++;
+          } catch {
+          }
         }
-      }
+        return count;
+      });
       logConvexStatus(synced > 0);
       if (synced > 0) {
         console.log(chalk6.dim(`  ${synced} models synced to Convex.`));
@@ -11354,7 +11467,13 @@ var statusCommand = new Command6("status").description("Show project status from
     );
     return;
   }
-  const registry = JSON.parse(readFileSync9(registryPath, "utf-8"));
+  let registry;
+  try {
+    registry = JSON.parse(readFileSync9(registryPath, "utf-8"));
+  } catch {
+    console.error(`Failed to parse ${registryPath}: file contains invalid JSON`);
+    return process.exit(1);
+  }
   const projectName = options.project ?? registry.project ?? getProjectName();
   const summaryPath = resolve9(
     process.cwd(),
@@ -11366,7 +11485,13 @@ var statusCommand = new Command6("status").description("Show project status from
   const hasTracking = existsSync8(summaryPath);
   const actuals = /* @__PURE__ */ new Map();
   if (hasTracking) {
-    const summary = JSON.parse(readFileSync9(summaryPath, "utf-8"));
+    let summary;
+    try {
+      summary = JSON.parse(readFileSync9(summaryPath, "utf-8"));
+    } catch {
+      console.error(`Failed to parse ${summaryPath}: file contains invalid JSON`);
+      return process.exit(1);
+    }
     for (const s of summary.sessions) {
       if (!s.featureId || s.status === "untagged") continue;
       const existing = actuals.get(s.featureId) ?? { tokens: 0, sessions: 0 };
@@ -11832,399 +11957,542 @@ function applyStatsAttribution(sessions, cache) {
 }
 
 // src/commands/track.ts
-var trackCommand = new Command7("track").description("Import Claude Code sessions and auto-tag to features").option("-p, --project <name>", "Project name").option("--registry <path>", "Path to registry.json").option("--sessions-dir <path>", "Path to sessions directory").option("--backfill", "Process all existing sessions (not just new)").action(
+import { confirm as confirm3 } from "@inquirer/prompts";
+var trackCommand = new Command7("track").description("Import Claude Code sessions and auto-tag to features").option("-p, --project <name>", "Project name").option("--registry <path>", "Path to registry.json").option("--sessions-dir <path>", "Path to sessions directory").option("--backfill", "Process all existing sessions (not just new)").option("--dry-run", "Show what would change without modifying files").option("-y, --yes", "Skip confirmation prompt").action(
   async (options) => {
-    const registryPath = options.registry ?? resolve10(process.cwd(), ".claude", "te", "registry.json");
-    if (!existsSync10(registryPath)) {
+    try {
+      const registryPath = options.registry ?? resolve10(process.cwd(), ".claude", "te", "registry.json");
+      if (!existsSync10(registryPath)) {
+        console.log(
+          chalk8.yellow(
+            "No registry found. Run `fathom analyze <spec> --project <name>` first."
+          )
+        );
+        return;
+      }
+      let registry;
+      try {
+        registry = JSON.parse(readFileSync11(registryPath, "utf-8"));
+      } catch {
+        console.error(`Failed to parse ${registryPath}: file contains invalid JSON`);
+        return process.exit(1);
+      }
+      const projectName = options.project ?? registry.project ?? getProjectName();
+      console.log(chalk8.dim("Scanning for sessions..."));
+      const sessionFiles = findSessionFiles(options.sessionsDir);
+      if (sessionFiles.length === 0) {
+        console.log(
+          chalk8.yellow("No session files found. Run some Claude Code sessions first.")
+        );
+        return;
+      }
+      const trackingDir = resolve10(
+        process.cwd(),
+        ".claude",
+        "te",
+        "tracking",
+        "sessions"
+      );
+      const summaryPath = resolve10(
+        process.cwd(),
+        ".claude",
+        "te",
+        "tracking",
+        "summary.json"
+      );
+      const trackedIds = /* @__PURE__ */ new Set();
+      if (!options.backfill && existsSync10(summaryPath)) {
+        let summary;
+        try {
+          summary = JSON.parse(readFileSync11(summaryPath, "utf-8"));
+        } catch {
+          console.error(`Failed to parse ${summaryPath}: file contains invalid JSON`);
+          process.exit(1);
+        }
+        for (const s of summary.sessions ?? []) {
+          trackedIds.add(s.sessionId);
+        }
+      }
+      const results = [];
+      for (const file of sessionFiles) {
+        const session = parseSessionFile(file);
+        if (!session) continue;
+        if (trackedIds.has(session.sessionId)) continue;
+        const tag = autoTag(session, registry.features);
+        results.push({ session, tag });
+      }
+      if (results.length === 0) {
+        console.log(
+          chalk8.dim("No new sessions to process.")
+        );
+        return;
+      }
+      const statsCache = readStatsCache();
+      let attributionSummary = null;
+      if (statsCache) {
+        const allSessions = results.map((r) => r.session);
+        const attribution = applyStatsAttribution(allSessions, statsCache);
+        if (attribution.upgraded > 0) {
+          attributionSummary = `Stats-cache: ${attribution.upgraded} sessions upgraded, ${attribution.unchanged} had API data, ${attribution.unattributed} unattributed`;
+        }
+      }
       console.log(
-        chalk8.yellow(
-          "No registry found. Run `fathom analyze <spec> --project <name>` first."
+        chalk8.bold(`
+Fathom \u2014 Track: ${projectName} (${results.length} sessions)`)
+      );
+      console.log(chalk8.dim("\u2500".repeat(65)));
+      const table = new Table5({
+        head: [
+          chalk8.white("Session"),
+          chalk8.white("Feature"),
+          chalk8.white("Confidence"),
+          chalk8.white("Tag"),
+          chalk8.white("Tokens"),
+          chalk8.white("Token Src")
+        ],
+        colAligns: ["left", "left", "center", "center", "right", "center"]
+      });
+      let totalTokens = 0;
+      let autoTagged = 0;
+      let likely = 0;
+      let untagged = 0;
+      for (const { session, tag } of results) {
+        const tokens = session.inputTokens + session.outputTokens;
+        totalTokens += tokens;
+        const featureLabel = tag.featureId ? registry.features.find((f) => f.id === tag.featureId)?.name ?? tag.featureId : chalk8.dim("\u2014");
+        const confidenceColor = tag.status === "auto-tagged" ? chalk8.green : tag.status === "likely" ? chalk8.yellow : chalk8.dim;
+        if (tag.status === "auto-tagged") autoTagged++;
+        else if (tag.status === "likely") likely++;
+        else untagged++;
+        const srcColor = session.tokenSource === "api" ? chalk8.green : session.tokenSource === "stats-cache" ? chalk8.cyan : session.tokenSource === "tokenizer" ? chalk8.yellow : chalk8.dim;
+        table.push([
+          session.sessionId.slice(0, 12) + "\u2026",
+          featureLabel,
+          confidenceColor(`${(tag.confidence * 100).toFixed(0)}%`),
+          tag.source,
+          tokens.toLocaleString(),
+          srcColor(session.tokenSource)
+        ]);
+      }
+      console.log(table.toString());
+      console.log(
+        chalk8.dim(
+          `
+Total: ${totalTokens.toLocaleString()} tokens across ${results.length} sessions`
         )
       );
-      return;
-    }
-    const registry = JSON.parse(
-      readFileSync11(registryPath, "utf-8")
-    );
-    const projectName = options.project ?? registry.project ?? getProjectName();
-    console.log(chalk8.dim("Scanning for sessions..."));
-    const sessionFiles = findSessionFiles(options.sessionsDir);
-    if (sessionFiles.length === 0) {
       console.log(
-        chalk8.yellow("No session files found. Run some Claude Code sessions first.")
+        chalk8.dim(
+          `Tags: ${autoTagged} auto-tagged, ${likely} likely, ${untagged} untagged`
+        )
       );
-      return;
+      if (attributionSummary) {
+        console.log(chalk8.cyan(`  ${attributionSummary}`));
+      }
+      if (options.dryRun) {
+        console.log(chalk8.dim(`
+[dry-run] Would write ${results.length} sessions to tracking. No files modified.`));
+        return;
+      }
+      if (!options.yes) {
+        const proceed = await confirm3({
+          message: `Track ${results.length} sessions and update summary? (use --yes to skip)`,
+          default: true
+        });
+        if (!proceed) {
+          console.log(chalk8.dim("\n  Aborted."));
+          return;
+        }
+      }
+      mkdirSync8(trackingDir, { recursive: true });
+      const sessionRecords = results.map(({ session, tag }) => ({
+        sessionId: session.sessionId,
+        featureId: tag.featureId,
+        confidence: tag.confidence,
+        source: tag.source,
+        status: tag.status,
+        inputTokens: session.inputTokens,
+        outputTokens: session.outputTokens,
+        cacheReadTokens: session.cacheReadTokens,
+        model: session.model,
+        sessionStart: session.sessionStart,
+        sessionEnd: session.sessionEnd,
+        activeMinutes: session.activeMinutes,
+        tokenSource: session.tokenSource,
+        trackedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+      let existing = { sessions: [] };
+      if (existsSync10(summaryPath)) {
+        try {
+          existing = JSON.parse(readFileSync11(summaryPath, "utf-8"));
+        } catch {
+          console.error(`Failed to parse ${summaryPath}: file contains invalid JSON`);
+          process.exit(1);
+        }
+      }
+      existing.sessions.push(...sessionRecords);
+      writeFileSync7(
+        summaryPath,
+        JSON.stringify(
+          {
+            project: projectName,
+            sessions: existing.sessions,
+            lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+          },
+          null,
+          2
+        )
+      );
+      console.log(chalk8.dim(`
+Tracking saved: ${summaryPath}`));
+      if (isConvexConnected()) {
+        const syncCount = await withSpinner("Syncing to Convex...", async () => {
+          let count = 0;
+          for (const { session, tag } of results) {
+            const synced = await syncActual({
+              projectName,
+              sessionId: session.sessionId,
+              provider: "claude",
+              model: session.model,
+              inputTokens: session.inputTokens,
+              outputTokens: session.outputTokens,
+              cacheReadTokens: session.cacheReadTokens,
+              cacheCreateTokens: 0,
+              toolCalls: 0,
+              estimatedCost: 0,
+              sessionStart: session.sessionStart,
+              sessionEnd: session.sessionEnd,
+              activeMinutes: session.activeMinutes,
+              featureId: tag.featureId,
+              tagConfidence: tag.confidence,
+              tagSource: tag.source,
+              tagStatus: tag.status
+            });
+            if (synced) count++;
+          }
+          return count;
+        });
+        logConvexStatus(syncCount > 0);
+        if (syncCount > 0) {
+          console.log(chalk8.dim(`  ${syncCount} sessions synced to Convex.`));
+        }
+      } else {
+        logConvexStatus(false);
+      }
+    } catch (err) {
+      if (err && typeof err === "object" && "name" in err && err.name === "ExitPromptError") {
+        console.log(chalk8.dim("\n  Exiting.\n"));
+        return;
+      }
+      throw err;
     }
-    const trackingDir = resolve10(
-      process.cwd(),
-      ".claude",
-      "te",
-      "tracking",
-      "sessions"
+  }
+);
+
+// src/commands/reconcile.ts
+import { Command as Command8 } from "commander";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync8, existsSync as existsSync11, mkdirSync as mkdirSync9 } from "fs";
+import { resolve as resolve11 } from "path";
+import chalk9 from "chalk";
+import Table6 from "cli-table3";
+import { confirm as confirm4 } from "@inquirer/prompts";
+function computeCalibrationEntries(features, actuals, sessions) {
+  const entries = [];
+  for (const feature of features) {
+    const actual = actuals.get(feature.id);
+    if (!actual) continue;
+    const featureSessions = sessions.filter(
+      (s) => s.featureId === feature.id && s.status !== "untagged"
     );
-    const summaryPath = resolve10(
+    const dominantModel = featureSessions.length > 0 ? featureSessions[0].model : "unknown";
+    entries.push({
+      model: dominantModel,
+      taskType: "mixed",
+      // features span multiple task types
+      complexity: "M",
+      // default; could be refined with registry metadata
+      estimatedTokens: feature.estimated_tokens,
+      actualTokens: actual.tokens,
+      accuracy: feature.estimated_tokens > 0 ? actual.tokens / feature.estimated_tokens : 0,
+      timestamp: Date.now()
+    });
+  }
+  return entries;
+}
+function persistCalibration(entries, projectDir = process.cwd()) {
+  const calPath = resolve11(projectDir, ".fathom", "store", "calibration.json");
+  mkdirSync9(resolve11(projectDir, ".fathom", "store"), { recursive: true });
+  let existing = { entries: [] };
+  try {
+    existing = JSON.parse(readFileSync12(calPath, "utf-8"));
+  } catch {
+  }
+  existing.entries.push(...entries);
+  writeFileSync8(calPath, JSON.stringify(existing, null, 2));
+}
+var reconcileCommand = new Command8("reconcile").description("Compare estimates vs actuals per feature").option("-p, --project <name>", "Project name").option("--registry <path>", "Path to registry.json").option("--dry-run", "Show reconciliation without syncing").option("-y, --yes", "Skip confirmation prompt").action(async (options) => {
+  try {
+    const registryPath = options.registry ?? resolve11(process.cwd(), ".claude", "te", "registry.json");
+    const summaryPath = resolve11(
       process.cwd(),
       ".claude",
       "te",
       "tracking",
       "summary.json"
     );
-    const trackedIds = /* @__PURE__ */ new Set();
-    if (!options.backfill && existsSync10(summaryPath)) {
-      const summary = JSON.parse(readFileSync11(summaryPath, "utf-8"));
-      for (const s of summary.sessions ?? []) {
-        trackedIds.add(s.sessionId);
-      }
-    }
-    const results = [];
-    for (const file of sessionFiles) {
-      const session = parseSessionFile(file);
-      if (!session) continue;
-      if (trackedIds.has(session.sessionId)) continue;
-      const tag = autoTag(session, registry.features);
-      results.push({ session, tag });
+    if (!existsSync11(registryPath)) {
+      console.log(
+        chalk9.yellow(
+          "No registry found. Run `fathom analyze <spec> --project <name>` first."
+        )
+      );
+      return;
     }
-    if (results.length === 0) {
+    if (!existsSync11(summaryPath)) {
       console.log(
-        chalk8.dim("No new sessions to process.")
+        chalk9.yellow(
+          "No tracking data found. Run `fathom track --project <name>` first."
+        )
       );
       return;
     }
-    const statsCache = readStatsCache();
-    let attributionSummary = null;
-    if (statsCache) {
-      const allSessions = results.map((r) => r.session);
-      const attribution = applyStatsAttribution(allSessions, statsCache);
-      if (attribution.upgraded > 0) {
-        attributionSummary = `Stats-cache: ${attribution.upgraded} sessions upgraded, ${attribution.unchanged} had API data, ${attribution.unattributed} unattributed`;
-      }
+    let registry;
+    try {
+      registry = JSON.parse(readFileSync12(registryPath, "utf-8"));
+    } catch {
+      console.error(`Failed to parse ${registryPath}: file contains invalid JSON`);
+      return process.exit(1);
+    }
+    let summary;
+    try {
+      summary = JSON.parse(readFileSync12(summaryPath, "utf-8"));
+    } catch {
+      console.error(`Failed to parse ${summaryPath}: file contains invalid JSON`);
+      return process.exit(1);
+    }
+    const projectName = options.project ?? registry.project ?? getProjectName();
+    const data = loadData();
+    const actuals = /* @__PURE__ */ new Map();
+    for (const session of summary.sessions) {
+      if (!session.featureId || session.status === "untagged") continue;
+      const existing = actuals.get(session.featureId) ?? {
+        tokens: 0,
+        cost: 0,
+        sessions: 0,
+        minutes: 0
+      };
+      const totalTokens = session.inputTokens + session.outputTokens;
+      const pricing = getModelPricing(data.models, session.model);
+      const cost = pricing ? session.inputTokens / 1e6 * pricing.input_per_mtok + session.outputTokens / 1e6 * pricing.output_per_mtok + session.cacheReadTokens / 1e6 * pricing.cache_read_per_mtok : 0;
+      existing.tokens += totalTokens;
+      existing.cost += cost;
+      existing.sessions += 1;
+      existing.minutes += session.activeMinutes ?? 0;
+      actuals.set(session.featureId, existing);
     }
     console.log(
-      chalk8.bold(`
-Fathom \u2014 Track: ${projectName} (${results.length} sessions)`)
+      chalk9.bold(`
+Fathom \u2014 Reconcile: ${projectName}`)
     );
-    console.log(chalk8.dim("\u2500".repeat(65)));
-    const table = new Table5({
+    console.log(chalk9.dim("\u2500".repeat(75)));
+    const table = new Table6({
       head: [
-        chalk8.white("Session"),
-        chalk8.white("Feature"),
-        chalk8.white("Confidence"),
-        chalk8.white("Tag"),
-        chalk8.white("Tokens"),
-        chalk8.white("Token Src")
+        chalk9.white("Feature"),
+        chalk9.white("Est. Tokens"),
+        chalk9.white("Act. Tokens"),
+        chalk9.white("Drift"),
+        chalk9.white("Act. Cost"),
+        chalk9.white("Sessions")
       ],
-      colAligns: ["left", "left", "center", "center", "right", "center"]
+      colAligns: ["left", "right", "right", "center", "right", "center"]
     });
-    let totalTokens = 0;
-    let autoTagged = 0;
-    let likely = 0;
-    let untagged = 0;
-    for (const { session, tag } of results) {
-      const tokens = session.inputTokens + session.outputTokens;
-      totalTokens += tokens;
-      const featureLabel = tag.featureId ? registry.features.find((f) => f.id === tag.featureId)?.name ?? tag.featureId : chalk8.dim("\u2014");
-      const confidenceColor = tag.status === "auto-tagged" ? chalk8.green : tag.status === "likely" ? chalk8.yellow : chalk8.dim;
-      if (tag.status === "auto-tagged") autoTagged++;
-      else if (tag.status === "likely") likely++;
-      else untagged++;
-      const srcColor = session.tokenSource === "api" ? chalk8.green : session.tokenSource === "stats-cache" ? chalk8.cyan : session.tokenSource === "tokenizer" ? chalk8.yellow : chalk8.dim;
-      table.push([
-        session.sessionId.slice(0, 12) + "\u2026",
-        featureLabel,
-        confidenceColor(`${(tag.confidence * 100).toFixed(0)}%`),
-        tag.source,
-        tokens.toLocaleString(),
-        srcColor(session.tokenSource)
-      ]);
+    let totalEstimated = 0;
+    let totalActual = 0;
+    let totalCost = 0;
+    for (const feature of registry.features) {
+      const actual = actuals.get(feature.id);
+      const estimated = feature.estimated_tokens;
+      totalEstimated += estimated;
+      if (actual) {
+        totalActual += actual.tokens;
+        totalCost += actual.cost;
+        const drift = (actual.tokens - estimated) / estimated * 100;
+        const driftLabel = drift > 20 ? chalk9.red(`+${drift.toFixed(0)}%`) : drift < -20 ? chalk9.green(`${drift.toFixed(0)}%`) : chalk9.white(`${drift >= 0 ? "+" : ""}${drift.toFixed(0)}%`);
+        table.push([
+          feature.name,
+          estimated.toLocaleString(),
+          actual.tokens.toLocaleString(),
+          driftLabel,
+          `$${actual.cost.toFixed(2)}`,
+          actual.sessions.toString()
+        ]);
+      } else {
+        table.push([
+          feature.name,
+          estimated.toLocaleString(),
+          chalk9.dim("\u2014"),
+          chalk9.dim("\u2014"),
+          chalk9.dim("\u2014"),
+          chalk9.dim("0")
+        ]);
+      }
     }
     console.log(table.toString());
+    const overallDrift = totalEstimated > 0 ? (totalActual - totalEstimated) / totalEstimated * 100 : 0;
+    const driftColor = Math.abs(overallDrift) > 20 ? overallDrift > 0 ? chalk9.red : chalk9.green : chalk9.white;
     console.log(
-      chalk8.dim(
+      chalk9.bold(
         `
-Total: ${totalTokens.toLocaleString()} tokens across ${results.length} sessions`
+Overall: ${totalActual.toLocaleString()} / ${totalEstimated.toLocaleString()} tokens \u2014 ` + driftColor(
+          `${overallDrift >= 0 ? "+" : ""}${overallDrift.toFixed(1)}% drift`
+        )
       )
     );
+    console.log(chalk9.dim(`Total actual cost: $${totalCost.toFixed(2)}`));
     console.log(
-      chalk8.dim(
-        `Tags: ${autoTagged} auto-tagged, ${likely} likely, ${untagged} untagged`
+      chalk9.dim(
+        `Features with data: ${actuals.size} / ${registry.features.length}`
       )
     );
-    if (attributionSummary) {
-      console.log(chalk8.cyan(`  ${attributionSummary}`));
-    }
-    mkdirSync8(trackingDir, { recursive: true });
-    const sessionRecords = results.map(({ session, tag }) => ({
-      sessionId: session.sessionId,
-      featureId: tag.featureId,
-      confidence: tag.confidence,
-      source: tag.source,
-      status: tag.status,
-      inputTokens: session.inputTokens,
-      outputTokens: session.outputTokens,
-      cacheReadTokens: session.cacheReadTokens,
-      model: session.model,
-      sessionStart: session.sessionStart,
-      sessionEnd: session.sessionEnd,
-      activeMinutes: session.activeMinutes,
-      tokenSource: session.tokenSource,
-      trackedAt: (/* @__PURE__ */ new Date()).toISOString()
-    }));
-    let existing = { sessions: [] };
-    if (existsSync10(summaryPath)) {
-      existing = JSON.parse(readFileSync11(summaryPath, "utf-8"));
+    const config = readProjectConfig();
+    const adminKey = resolveAdminKey(config?.anthropicAdminKey ?? void 0);
+    let adminReport = null;
+    if (adminKey) {
+      const sessions = summary.sessions;
+      const starts = sessions.map((s) => s.sessionStart).filter((t) => typeof t === "number" && t > 0);
+      if (starts.length > 0) {
+        const earliest = new Date(Math.min(...starts));
+        const latest = /* @__PURE__ */ new Date();
+        earliest.setHours(0, 0, 0, 0);
+        adminReport = await withSpinner(
+          "Fetching admin usage data...",
+          async () => fetchAdminUsage({
+            adminKey,
+            startingAt: earliest.toISOString(),
+            endingAt: latest.toISOString(),
+            bucketWidth: "1d",
+            groupBy: ["model"]
+          })
+        );
+        if (adminReport) {
+          const billedTotal = adminReport.totalInputTokens + adminReport.totalOutputTokens;
+          const gap = billedTotal - totalActual;
+          const gapPct = totalActual > 0 ? gap / totalActual * 100 : 0;
+          console.log(chalk9.bold("\n  Billed vs Tracked (Admin API)"));
+          console.log(chalk9.dim("  " + "\u2500".repeat(45)));
+          console.log(
+            chalk9.dim(
+              `  Tracked: ${totalActual.toLocaleString()} tokens`
+            )
+          );
+          console.log(
+            chalk9.dim(
+              `  Billed:  ${billedTotal.toLocaleString()} tokens`
+            )
+          );
+          const gapColor = Math.abs(gapPct) > 20 ? chalk9.red : chalk9.yellow;
+          console.log(
+            gapColor(
+              `  Gap:     ${gap.toLocaleString()} tokens (${gapPct >= 0 ? "+" : ""}${gapPct.toFixed(1)}%)`
+            )
+          );
+          if (adminReport.totalCacheReadTokens > 0) {
+            console.log(
+              chalk9.dim(
+                `  Cache:   ${adminReport.totalCacheReadTokens.toLocaleString()} cache-read, ${adminReport.totalCacheCreationTokens.toLocaleString()} cache-create`
+              )
+            );
+          }
+        } else {
+          console.log(
+            chalk9.dim("\n  Admin API: Could not fetch usage data (check key/permissions)")
+          );
+        }
+      }
     }
-    existing.sessions.push(...sessionRecords);
-    writeFileSync7(
-      summaryPath,
-      JSON.stringify(
-        {
-          project: projectName,
-          sessions: existing.sessions,
-          lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
-        },
-        null,
-        2
-      )
+    const calibrationEntries = computeCalibrationEntries(
+      registry.features,
+      actuals,
+      summary.sessions
     );
-    console.log(chalk8.dim(`
-Tracking saved: ${summaryPath}`));
-    if (isConvexConnected()) {
-      let syncCount = 0;
-      for (const { session, tag } of results) {
-        const synced = await syncActual({
-          projectName,
-          sessionId: session.sessionId,
-          provider: "claude",
-          model: session.model,
-          inputTokens: session.inputTokens,
-          outputTokens: session.outputTokens,
-          cacheReadTokens: session.cacheReadTokens,
-          cacheCreateTokens: 0,
-          toolCalls: 0,
-          estimatedCost: 0,
-          sessionStart: session.sessionStart,
-          sessionEnd: session.sessionEnd,
-          activeMinutes: session.activeMinutes,
-          featureId: tag.featureId,
-          tagConfidence: tag.confidence,
-          tagSource: tag.source,
-          tagStatus: tag.status
-        });
-        if (synced) syncCount++;
-      }
-      logConvexStatus(syncCount > 0);
-      if (syncCount > 0) {
-        console.log(chalk8.dim(`  ${syncCount} sessions synced to Convex.`));
-      }
-    } else {
-      logConvexStatus(false);
+    if (calibrationEntries.length > 0) {
+      const avgAccuracy = calibrationEntries.reduce((sum, e) => sum + e.accuracy, 0) / calibrationEntries.length;
+      const pct = Math.round(
+        Math.min(avgAccuracy, 1 / avgAccuracy) * 100
+      );
+      console.log(
+        chalk9.bold(
+          `
+  Calibration: ${calibrationEntries.length} features reconciled. Average accuracy: ${pct}%.`
+        )
+      );
     }
-  }
-);
-
-// src/commands/reconcile.ts
-import { Command as Command8 } from "commander";
-import { readFileSync as readFileSync12, existsSync as existsSync11 } from "fs";
-import { resolve as resolve11 } from "path";
-import chalk9 from "chalk";
-import Table6 from "cli-table3";
-var reconcileCommand = new Command8("reconcile").description("Compare estimates vs actuals per feature").option("-p, --project <name>", "Project name").option("--registry <path>", "Path to registry.json").action(async (options) => {
-  const registryPath = options.registry ?? resolve11(process.cwd(), ".claude", "te", "registry.json");
-  const summaryPath = resolve11(
-    process.cwd(),
-    ".claude",
-    "te",
-    "tracking",
-    "summary.json"
-  );
-  if (!existsSync11(registryPath)) {
-    console.log(
-      chalk9.yellow(
-        "No registry found. Run `fathom analyze <spec> --project <name>` first."
-      )
-    );
-    return;
-  }
-  if (!existsSync11(summaryPath)) {
-    console.log(
-      chalk9.yellow(
-        "No tracking data found. Run `fathom track --project <name>` first."
-      )
-    );
-    return;
-  }
-  const registry = JSON.parse(readFileSync12(registryPath, "utf-8"));
-  const summary = JSON.parse(readFileSync12(summaryPath, "utf-8"));
-  const projectName = options.project ?? registry.project ?? getProjectName();
-  const data = loadData();
-  const actuals = /* @__PURE__ */ new Map();
-  for (const session of summary.sessions) {
-    if (!session.featureId || session.status === "untagged") continue;
-    const existing = actuals.get(session.featureId) ?? {
-      tokens: 0,
-      cost: 0,
-      sessions: 0,
-      minutes: 0
-    };
-    const totalTokens = session.inputTokens + session.outputTokens;
-    const pricing = getModelPricing(data.models, session.model);
-    const cost = pricing ? session.inputTokens / 1e6 * pricing.input_per_mtok + session.outputTokens / 1e6 * pricing.output_per_mtok + session.cacheReadTokens / 1e6 * pricing.cache_read_per_mtok : 0;
-    existing.tokens += totalTokens;
-    existing.cost += cost;
-    existing.sessions += 1;
-    existing.minutes += session.activeMinutes ?? 0;
-    actuals.set(session.featureId, existing);
-  }
-  console.log(
-    chalk9.bold(`
-Fathom \u2014 Reconcile: ${projectName}`)
-  );
-  console.log(chalk9.dim("\u2500".repeat(75)));
-  const table = new Table6({
-    head: [
-      chalk9.white("Feature"),
-      chalk9.white("Est. Tokens"),
-      chalk9.white("Act. Tokens"),
-      chalk9.white("Drift"),
-      chalk9.white("Act. Cost"),
-      chalk9.white("Sessions")
-    ],
-    colAligns: ["left", "right", "right", "center", "right", "center"]
-  });
-  let totalEstimated = 0;
-  let totalActual = 0;
-  let totalCost = 0;
-  for (const feature of registry.features) {
-    const actual = actuals.get(feature.id);
-    const estimated = feature.estimated_tokens;
-    totalEstimated += estimated;
-    if (actual) {
-      totalActual += actual.tokens;
-      totalCost += actual.cost;
-      const drift = (actual.tokens - estimated) / estimated * 100;
-      const driftLabel = drift > 20 ? chalk9.red(`+${drift.toFixed(0)}%`) : drift < -20 ? chalk9.green(`${drift.toFixed(0)}%`) : chalk9.white(`${drift >= 0 ? "+" : ""}${drift.toFixed(0)}%`);
-      table.push([
-        feature.name,
-        estimated.toLocaleString(),
-        actual.tokens.toLocaleString(),
-        driftLabel,
-        `$${actual.cost.toFixed(2)}`,
-        actual.sessions.toString()
-      ]);
-    } else {
-      table.push([
-        feature.name,
-        estimated.toLocaleString(),
-        chalk9.dim("\u2014"),
-        chalk9.dim("\u2014"),
-        chalk9.dim("\u2014"),
-        chalk9.dim("0")
-      ]);
+    if (!options.dryRun && calibrationEntries.length > 0) {
+      persistCalibration(calibrationEntries);
+      console.log(
+        chalk9.dim(
+          `  Calibration data saved to .fathom/store/calibration.json`
+        )
+      );
     }
-  }
-  console.log(table.toString());
-  const overallDrift = totalEstimated > 0 ? (totalActual - totalEstimated) / totalEstimated * 100 : 0;
-  const driftColor = Math.abs(overallDrift) > 20 ? overallDrift > 0 ? chalk9.red : chalk9.green : chalk9.white;
-  console.log(
-    chalk9.bold(
-      `
-Overall: ${totalActual.toLocaleString()} / ${totalEstimated.toLocaleString()} tokens \u2014 ` + driftColor(
-        `${overallDrift >= 0 ? "+" : ""}${overallDrift.toFixed(1)}% drift`
-      )
-    )
-  );
-  console.log(chalk9.dim(`Total actual cost: $${totalCost.toFixed(2)}`));
-  console.log(
-    chalk9.dim(
-      `Features with data: ${actuals.size} / ${registry.features.length}`
-    )
-  );
-  const config = readProjectConfig();
-  const adminKey = resolveAdminKey(config?.anthropicAdminKey ?? void 0);
-  let adminReport = null;
-  if (adminKey) {
-    const sessions = summary.sessions;
-    const starts = sessions.map((s) => s.sessionStart).filter((t) => typeof t === "number" && t > 0);
-    if (starts.length > 0) {
-      const earliest = new Date(Math.min(...starts));
-      const latest = /* @__PURE__ */ new Date();
-      earliest.setHours(0, 0, 0, 0);
-      adminReport = await fetchAdminUsage({
-        adminKey,
-        startingAt: earliest.toISOString(),
-        endingAt: latest.toISOString(),
-        bucketWidth: "1d",
-        groupBy: ["model"]
+    if (options.dryRun) {
+      console.log(chalk9.dim(`
+[dry-run] Would sync reconciliation to Convex. No changes made.`));
+      return;
+    }
+    if (!options.yes) {
+      const proceed = await confirm4({
+        message: "Sync reconciliation data? (use --yes to skip)",
+        default: true
       });
-      if (adminReport) {
-        const billedTotal = adminReport.totalInputTokens + adminReport.totalOutputTokens;
-        const gap = billedTotal - totalActual;
-        const gapPct = totalActual > 0 ? gap / totalActual * 100 : 0;
-        console.log(chalk9.bold("\n  Billed vs Tracked (Admin API)"));
-        console.log(chalk9.dim("  " + "\u2500".repeat(45)));
-        console.log(
-          chalk9.dim(
-            `  Tracked: ${totalActual.toLocaleString()} tokens`
-          )
-        );
-        console.log(
-          chalk9.dim(
-            `  Billed:  ${billedTotal.toLocaleString()} tokens`
-          )
-        );
-        const gapColor = Math.abs(gapPct) > 20 ? chalk9.red : chalk9.yellow;
-        console.log(
-          gapColor(
-            `  Gap:     ${gap.toLocaleString()} tokens (${gapPct >= 0 ? "+" : ""}${gapPct.toFixed(1)}%)`
-          )
-        );
-        if (adminReport.totalCacheReadTokens > 0) {
-          console.log(
-            chalk9.dim(
-              `  Cache:   ${adminReport.totalCacheReadTokens.toLocaleString()} cache-read, ${adminReport.totalCacheCreationTokens.toLocaleString()} cache-create`
-            )
-          );
-        }
-      } else {
-        console.log(
-          chalk9.dim("\n  Admin API: Could not fetch usage data (check key/permissions)")
-        );
+      if (!proceed) {
+        console.log(chalk9.dim("\n  Aborted."));
+        return;
       }
     }
+    const overallAccuracy = totalEstimated > 0 ? 1 - Math.abs(totalActual - totalEstimated) / totalEstimated : 0;
+    const featureDeltas = registry.features.filter((f) => actuals.has(f.id)).map((f) => {
+      const actual = actuals.get(f.id);
+      const delta = actual.tokens - f.estimated_tokens;
+      const accuracy = f.estimated_tokens > 0 ? 1 - Math.abs(delta) / f.estimated_tokens : 0;
+      return {
+        featureId: f.id,
+        featureName: f.name,
+        estimatedTokens: f.estimated_tokens,
+        actualTokens: actual.tokens,
+        delta,
+        accuracy,
+        modelRecommended: "sonnet",
+        modelUsed: "sonnet",
+        sessionsCount: actual.sessions,
+        activeMinutes: actual.minutes,
+        tagQuality: { autoTagged: actual.sessions, likelyTagged: 0, manualTagged: 0 },
+        insights: delta > 0 ? [`Over estimate by ${(delta / f.estimated_tokens * 100).toFixed(0)}%`] : [`Under estimate by ${(Math.abs(delta) / f.estimated_tokens * 100).toFixed(0)}%`]
+      };
+    });
+    const totalSessions = Array.from(actuals.values()).reduce((s, a) => s + a.sessions, 0);
+    const autoTagged = summary.sessions.filter(
+      (s) => s.status === "auto-tagged"
+    ).length;
+    const autoTagAccuracy = totalSessions > 0 ? autoTagged / totalSessions : 0;
+    const synced = await withSpinner(
+      "Syncing reconciliation...",
+      async () => syncReconciliation({
+        projectName,
+        featureDeltas,
+        overallAccuracy,
+        autoTagAccuracy,
+        suggestedAdjustments: []
+      })
+    );
+    logConvexStatus(synced);
+  } catch (err) {
+    if (err && typeof err === "object" && "name" in err && err.name === "ExitPromptError") {
+      console.log(chalk9.dim("\n  Exiting.\n"));
+      return;
+    }
+    throw err;
   }
-  const overallAccuracy = totalEstimated > 0 ? 1 - Math.abs(totalActual - totalEstimated) / totalEstimated : 0;
-  const featureDeltas = registry.features.filter((f) => actuals.has(f.id)).map((f) => {
-    const actual = actuals.get(f.id);
-    const delta = actual.tokens - f.estimated_tokens;
-    const accuracy = f.estimated_tokens > 0 ? 1 - Math.abs(delta) / f.estimated_tokens : 0;
-    return {
-      featureId: f.id,
-      featureName: f.name,
-      estimatedTokens: f.estimated_tokens,
-      actualTokens: actual.tokens,
-      delta,
-      accuracy,
-      modelRecommended: "sonnet",
-      modelUsed: "sonnet",
-      sessionsCount: actual.sessions,
-      activeMinutes: actual.minutes,
-      tagQuality: { autoTagged: actual.sessions, likelyTagged: 0, manualTagged: 0 },
-      insights: delta > 0 ? [`Over estimate by ${(delta / f.estimated_tokens * 100).toFixed(0)}%`] : [`Under estimate by ${(Math.abs(delta) / f.estimated_tokens * 100).toFixed(0)}%`]
-    };
-  });
-  const totalSessions = Array.from(actuals.values()).reduce((s, a) => s + a.sessions, 0);
-  const autoTagged = summary.sessions.filter(
-    (s) => s.status === "auto-tagged"
-  ).length;
-  const autoTagAccuracy = totalSessions > 0 ? autoTagged / totalSessions : 0;
-  const synced = await syncReconciliation({
-    projectName,
-    featureDeltas,
-    overallAccuracy,
-    autoTagAccuracy,
-    suggestedAdjustments: []
-  });
-  logConvexStatus(synced);
 });
 
 // src/commands/calibrate.ts
@@ -12250,8 +12518,20 @@ var calibrateCommand = new Command9("calibrate").description("Show calibration d
     );
     return;
   }
-  const registry = JSON.parse(readFileSync13(registryPath, "utf-8"));
-  const summary = JSON.parse(readFileSync13(summaryPath, "utf-8"));
+  let registry;
+  try {
+    registry = JSON.parse(readFileSync13(registryPath, "utf-8"));
+  } catch {
+    console.error(`Failed to parse ${registryPath}: file contains invalid JSON`);
+    return process.exit(1);
+  }
+  let summary;
+  try {
+    summary = JSON.parse(readFileSync13(summaryPath, "utf-8"));
+  } catch {
+    console.error(`Failed to parse ${summaryPath}: file contains invalid JSON`);
+    return process.exit(1);
+  }
   const projectName = options.project ?? registry.project ?? getProjectName();
   const actuals = /* @__PURE__ */ new Map();
   for (const session of summary.sessions) {
@@ -12420,6 +12700,15 @@ var estimateCommand = new Command10("estimate").description("Quick single-featur
     console.log(
       chalk11.bold(`  Estimated cost: $${estimate.estimatedCost.toFixed(2)}`)
     );
+    if (estimate.confidence) {
+      const c = estimate.confidence;
+      console.log(
+        chalk11.dim(`  Confidence:     $${c.low.cost.toFixed(2)} \u2013 $${c.expected.cost.toFixed(2)} \u2013 $${c.high.cost.toFixed(2)}  (low / expected / high)`)
+      );
+      console.log(
+        chalk11.dim(`                  ${c.low.tokens.toLocaleString()} \u2013 ${c.expected.tokens.toLocaleString()} \u2013 ${c.high.tokens.toLocaleString()} tokens`)
+      );
+    }
     console.log(chalk11.dim("\n  Overhead breakdown:"));
     console.log(
       `    Context resend: ${estimate.overheadBreakdown.contextResend.toLocaleString()} tokens`
@@ -12846,8 +13135,20 @@ var velocityCommand = new Command12("velocity").description("Show velocity metri
       );
       return;
     }
-    const registry = JSON.parse(readFileSync15(registryPath, "utf-8"));
-    const summary = JSON.parse(readFileSync15(summaryPath, "utf-8"));
+    let registry;
+    try {
+      registry = JSON.parse(readFileSync15(registryPath, "utf-8"));
+    } catch {
+      console.error(`Failed to parse ${registryPath}: file contains invalid JSON`);
+      return process.exit(1);
+    }
+    let summary;
+    try {
+      summary = JSON.parse(readFileSync15(summaryPath, "utf-8"));
+    } catch {
+      console.error(`Failed to parse ${summaryPath}: file contains invalid JSON`);
+      return process.exit(1);
+    }
     const projectName = options.project ?? registry.project ?? getProjectName();
     const data = loadData();
     const featureDataMap = /* @__PURE__ */ new Map();
@@ -12985,8 +13286,8 @@ Fathom \u2014 Velocity: ${projectName}`));
 // src/commands/init.ts
 import { Command as Command13 } from "commander";
 import {
-  writeFileSync as writeFileSync8,
-  mkdirSync as mkdirSync9,
+  writeFileSync as writeFileSync9,
+  mkdirSync as mkdirSync10,
   existsSync as existsSync15,
   readFileSync as readFileSync16,
   readdirSync as readdirSync3
@@ -12995,7 +13296,7 @@ import { resolve as resolve15, dirname as dirname6 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { execSync } from "child_process";
 import chalk14 from "chalk";
-import { confirm as confirm3 } from "@inquirer/prompts";
+import { confirm as confirm5 } from "@inquirer/prompts";
 var initCommand = new Command13("init").description("Initialize Fathom: create global config and scaffold project directory").option("--convex-url <url>", "Convex deployment URL").option("--team <name>", "Team name").option("--admin-key <key>", "Anthropic Admin API key (sk-ant-admin...)").option("--project <name>", "Project name (auto-detected from package.json if omitted)").option("--project-dir <dir>", "Project directory (defaults to current directory)").action(async (options) => {
   const projectDir = options.projectDir ? resolve15(options.projectDir) : process.cwd();
   const projectName = options.project ?? detectProjectName(projectDir);
@@ -13007,7 +13308,7 @@ Fathom \u2014 Init: ${projectName}`));
     ".config",
     "fathom"
   );
-  mkdirSync9(configDir, { recursive: true });
+  mkdirSync10(configDir, { recursive: true });
   const configPath = resolve15(configDir, "config.json");
   let existing = {};
   if (existsSync15(configPath)) {
@@ -13023,7 +13324,7 @@ Fathom \u2014 Init: ${projectName}`));
     ...options.adminKey && { anthropicAdminKey: options.adminKey },
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  writeFileSync8(configPath, JSON.stringify(config, null, 2));
+  writeFileSync9(configPath, JSON.stringify(config, null, 2));
   console.log(chalk14.green(`  \u2713 Global config: ${configPath}`));
   if (options.convexUrl) {
     console.log(chalk14.dim(`    Convex URL: ${options.convexUrl}`));
@@ -13042,7 +13343,7 @@ Fathom \u2014 Init: ${projectName}`));
   if (claudeDetected) {
     console.log("");
     console.log(chalk14.cyan("  Claude Code detected!"));
-    const installPlugin = await confirm3({
+    const installPlugin = await confirm5({
       message: "Install Fathom plugin for Claude Code? (adds skills + MCP config)",
       default: true
     });
@@ -13065,8 +13366,8 @@ Fathom \u2014 Init: ${projectName}`));
             "fathom",
             skillDir
           );
-          mkdirSync9(destDir, { recursive: true });
-          writeFileSync8(
+          mkdirSync10(destDir, { recursive: true });
+          writeFileSync9(
             resolve15(destDir, "SKILL.md"),
             readFileSync16(src, "utf-8")
           );
@@ -13080,8 +13381,8 @@ Fathom \u2014 Init: ${projectName}`));
       );
       if (existsSync15(pluginJsonSrc)) {
         const destDir = resolve15(projectDir, ".claude-plugin");
-        mkdirSync9(destDir, { recursive: true });
-        writeFileSync8(
+        mkdirSync10(destDir, { recursive: true });
+        writeFileSync9(
           resolve15(destDir, "plugin.json"),
           readFileSync16(pluginJsonSrc, "utf-8")
         );
@@ -13097,63 +13398,96 @@ Fathom \u2014 Init: ${projectName}`));
 
 // src/commands/rename.ts
 import { Command as Command14 } from "commander";
-import { readFileSync as readFileSync17, writeFileSync as writeFileSync9, existsSync as existsSync16 } from "fs";
+import { readFileSync as readFileSync17, writeFileSync as writeFileSync10, existsSync as existsSync16 } from "fs";
 import { resolve as resolve16 } from "path";
 import chalk15 from "chalk";
-var renameCommand = new Command14("rename").description("Rename the project in all .claude/te/ config files").argument("<name>", "New project name").action((name) => {
-  const baseDir = process.cwd();
-  const teDir = resolve16(baseDir, ".claude", "te");
-  if (!existsSync16(teDir)) {
-    console.error(
-      chalk15.red("\n  Error: .claude/te/ not found. Run `fathom setup` first.\n")
-    );
-    process.exit(1);
-  }
-  const jsonFiles = [
-    resolve16(teDir, "config.json"),
-    resolve16(teDir, "registry.json"),
-    resolve16(teDir, "tracking", "summary.json")
-  ];
-  let oldName = "unnamed";
-  let updated = 0;
-  for (const filePath of jsonFiles) {
-    if (!existsSync16(filePath)) continue;
-    const data = JSON.parse(readFileSync17(filePath, "utf-8"));
-    if (data.project) {
-      oldName = data.project;
-      data.project = name;
-      writeFileSync9(filePath, JSON.stringify(data, null, 2) + "\n");
-      updated++;
-    }
-  }
-  const skillPath = resolve16(baseDir, ".claude", "skills", "fathom", "SKILL.md");
-  if (existsSync16(skillPath)) {
-    const content3 = readFileSync17(skillPath, "utf-8");
-    const newContent = content3.replaceAll(oldName, name);
-    if (newContent !== content3) {
-      writeFileSync9(skillPath, newContent);
-      updated++;
-    }
-  }
-  const hookPath = resolve16(baseDir, ".claude", "hooks", "te-session-sync.sh");
-  if (existsSync16(hookPath)) {
-    const content3 = readFileSync17(hookPath, "utf-8");
-    const newContent = content3.replaceAll(oldName, name);
-    if (newContent !== content3) {
-      writeFileSync9(hookPath, newContent);
-      updated++;
+import { confirm as confirm6 } from "@inquirer/prompts";
+var renameCommand = new Command14("rename").description("Rename the project in all .claude/te/ config files").argument("<name>", "New project name").option("-y, --yes", "Skip confirmation prompt").action(async (name, options) => {
+  try {
+    const baseDir = process.cwd();
+    const teDir = resolve16(baseDir, ".claude", "te");
+    if (!existsSync16(teDir)) {
+      console.error(
+        chalk15.red("\n  Error: .claude/te/ not found. Run `fathom setup` first.\n")
+      );
+      process.exit(1);
     }
-  }
-  console.log(
-    chalk15.bold(`
+    const jsonFiles = [
+      resolve16(teDir, "config.json"),
+      resolve16(teDir, "registry.json"),
+      resolve16(teDir, "tracking", "summary.json")
+    ];
+    let oldName = "unnamed";
+    const configPath = resolve16(teDir, "config.json");
+    if (existsSync16(configPath)) {
+      try {
+        const configData = JSON.parse(readFileSync17(configPath, "utf-8"));
+        if (configData.project) oldName = configData.project;
+      } catch {
+      }
+    }
+    if (!options.yes) {
+      const proceed = await confirm6({
+        message: `Rename project "${oldName}" to "${name}"?`,
+        default: true
+      });
+      if (!proceed) {
+        console.log(chalk15.dim("\n  Aborted."));
+        return;
+      }
+    }
+    let updated = 0;
+    for (const filePath of jsonFiles) {
+      if (!existsSync16(filePath)) continue;
+      let data;
+      try {
+        data = JSON.parse(readFileSync17(filePath, "utf-8"));
+      } catch {
+        console.error(`Failed to parse ${filePath}: file contains invalid JSON`);
+        return process.exit(1);
+      }
+      if (data.project) {
+        oldName = data.project;
+        data.project = name;
+        writeFileSync10(filePath, JSON.stringify(data, null, 2) + "\n");
+        updated++;
+      }
+    }
+    const skillPath = resolve16(baseDir, ".claude", "skills", "fathom", "SKILL.md");
+    if (existsSync16(skillPath)) {
+      const content3 = readFileSync17(skillPath, "utf-8");
+      const newContent = content3.replaceAll(oldName, name);
+      if (newContent !== content3) {
+        writeFileSync10(skillPath, newContent);
+        updated++;
+      }
+    }
+    const hookPath = resolve16(baseDir, ".claude", "hooks", "te-session-sync.sh");
+    if (existsSync16(hookPath)) {
+      const content3 = readFileSync17(hookPath, "utf-8");
+      const newContent = content3.replaceAll(oldName, name);
+      if (newContent !== content3) {
+        writeFileSync10(hookPath, newContent);
+        updated++;
+      }
+    }
+    console.log(
+      chalk15.bold(`
   Renamed "${oldName}" \u2192 "${name}" (${updated} files updated)
 `)
-  );
+    );
+  } catch (err) {
+    if (err && typeof err === "object" && "name" in err && err.name === "ExitPromptError") {
+      console.log(chalk15.dim("\n  Exiting.\n"));
+      return;
+    }
+    throw err;
+  }
 });
 
 // src/commands/research.ts
 import { Command as Command15 } from "commander";
-import { writeFileSync as writeFileSync10, existsSync as existsSync17 } from "fs";
+import { writeFileSync as writeFileSync11, existsSync as existsSync17 } from "fs";
 import { resolve as resolve17 } from "path";
 import chalk16 from "chalk";
 
@@ -13235,6 +13569,10 @@ function loadLocalPricing(fetchedAt, error) {
 }
 
 // src/fetchers/intelligence-fetcher.ts
+function maskKey(key) {
+  if (key.length <= 6) return "***";
+  return key.slice(0, 3) + "***" + key.slice(-3);
+}
 async function getAnthropicClient3(apiKey) {
   const { default: AnthropicSDK } = await import("@anthropic-ai/sdk");
   return new AnthropicSDK({ apiKey: apiKey ?? process.env.ANTHROPIC_API_KEY });
@@ -13307,7 +13645,10 @@ ${recsDesc}`;
       fetchedAt: now
     };
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    let errorMsg = err instanceof Error ? err.message : String(err);
+    if (apiKey) {
+      errorMsg = errorMsg.replaceAll(apiKey, maskKey(apiKey));
+    }
     if (options.verbose) {
       console.log(`  Intelligence fetch failed: ${errorMsg}`);
     }
@@ -13470,13 +13811,16 @@ var researchCommand = new Command15("research").description("Check and update mo
     console.log(chalk16.yellow("  Warning: could not load local data files"));
     localData = { models: [], recommendations: {} };
   }
-  const [pricingResult, intelligenceResult] = await Promise.all([
-    fetchPricing({ offline: options.offline, verbose: options.verbose }),
-    fetchIntelligence(localData.models, localData.recommendations, {
-      offline: options.offline,
-      verbose: options.verbose
-    })
-  ]);
+  const [pricingResult, intelligenceResult] = await withSpinner(
+    "Researching pricing intelligence...",
+    async () => Promise.all([
+      fetchPricing({ offline: options.offline, verbose: options.verbose }),
+      fetchIntelligence(localData.models, localData.recommendations, {
+        offline: options.offline,
+        verbose: options.verbose
+      })
+    ])
+  );
   if (options.verbose) {
     const elapsed = Date.now() - startTime;
     console.log(chalk16.dim(`
@@ -13509,10 +13853,10 @@ var researchCommand = new Command15("research").description("Check and update mo
     const dataDir = findDataDir2();
     const modelsPath = resolve17(dataDir, "models.yaml");
     const agentsPath = resolve17(dataDir, "agents.yaml");
-    writeFileSync10(modelsPath, generateModelsYaml(mergeResult.models.merged));
+    writeFileSync11(modelsPath, generateModelsYaml(mergeResult.models.merged));
     console.log(chalk16.green(`
   Updated: ${modelsPath}`));
-    writeFileSync10(agentsPath, generateAgentsYaml(mergeResult.recommendations.merged));
+    writeFileSync11(agentsPath, generateAgentsYaml(mergeResult.recommendations.merged));
     console.log(chalk16.green(`  Updated: ${agentsPath}`));
   }
   if (options.sync) {
@@ -13636,10 +13980,10 @@ var projectCommand = new Command16("project").description("View or update projec
       console.log(chalk17.dim("  Run `fathom` to set up a project with intent capture.\n"));
       return;
     }
-    const { loadIntent } = await import("./dist-XKZLNUDU.js");
+    const { loadIntent } = await import("./dist-VMLJKWUO.js");
     const intent = await loadIntent(cwd);
     if (options.regenerate) {
-      const { writeProjections } = await import("./dist-KXBSLOHP.js");
+      const { writeProjections } = await import("./dist-HPXMBCZX.js");
       const files = await writeProjections(cwd, intent);
       console.log(chalk17.green(`
   \u2713 Regenerated ${files.length} projection files from intent`));
@@ -13673,7 +14017,7 @@ var projectCommand = new Command16("project").description("View or update projec
       console.log(`    Alert at ${Math.round(intent.budget.alert_threshold * 100)}%`);
     }
     if (intent.guardrails) {
-      const { resolveGuardrails } = await import("./dist-XKZLNUDU.js");
+      const { resolveGuardrails } = await import("./dist-VMLJKWUO.js");
       const resolved = resolveGuardrails(intent);
       const total = resolved.security.length + resolved.quality.length + resolved.process.length;
       console.log(chalk17.bold(`
@@ -13713,16 +14057,16 @@ var projectCommand = new Command16("project").description("View or update projec
 
 // src/commands/report.ts
 import { Command as Command17 } from "commander";
-import { writeFileSync as writeFileSync11, mkdirSync as mkdirSync10, existsSync as existsSync19 } from "fs";
+import { writeFileSync as writeFileSync12, mkdirSync as mkdirSync11, existsSync as existsSync19 } from "fs";
 import { resolve as resolve19, join as join4 } from "path";
 import chalk18 from "chalk";
 
 // ../store/dist/index.js
 import { randomUUID } from "crypto";
-import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { mkdir, readFile, rename, unlink, writeFile } from "fs/promises";
 import { dirname as dirname7, join as join3 } from "path";
 import { readFile as readFile2 } from "fs/promises";
-import { join as join22 } from "path";
+import { isAbsolute, join as join22, normalize } from "path";
 var OverheadBreakdownSchema = external_exports.object({
   contextResend: external_exports.number(),
   toolCalls: external_exports.number(),
@@ -13926,9 +14270,15 @@ async function readJsonFile(path) {
 }
 async function writeJsonFile(path, data) {
   await ensureDir(path);
-  const tmp = `${path}.tmp`;
+  const tmp = `${path}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
   await writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
-  await rename(tmp, path);
+  try {
+    await rename(tmp, path);
+  } catch (err) {
+    await unlink(tmp).catch(() => {
+    });
+    throw err;
+  }
 }
 var FileStore = class {
   baseDir;
@@ -14147,7 +14497,8 @@ var ConvexStore = class {
           this.client = new convex.ConvexHttpClient(this.url);
           this.api = convex.anyApi;
           return true;
-        } catch {
+        } catch (err) {
+          console.error(`[FathomStore] Convex client init failed:`, err);
           return false;
         }
       })();
@@ -14162,7 +14513,8 @@ var ConvexStore = class {
     if (!await this.init()) return null;
     try {
       return await this.client.query(fn, args);
-    } catch {
+    } catch (err) {
+      console.error(`[FathomStore] query failed:`, err);
       return null;
     }
   }
@@ -14174,7 +14526,8 @@ var ConvexStore = class {
     if (!await this.init()) return null;
     try {
       return await this.client.mutation(fn, args);
-    } catch {
+    } catch (err) {
+      console.error(`[FathomStore] mutation failed:`, err);
       return null;
     }
   }
@@ -14409,6 +14762,15 @@ var ConvexStore = class {
     );
   }
 };
+function validateStorePath(storePath) {
+  if (isAbsolute(storePath)) {
+    throw new Error(`Store path must be relative, got absolute path: "${storePath}"`);
+  }
+  const normalized = normalize(storePath);
+  if (normalized.startsWith("..")) {
+    throw new Error(`Store path must not escape project directory: "${storePath}"`);
+  }
+}
 async function loadStoreConfig(dir) {
   try {
     const raw = await readFile2(join22(dir, ".fathom", "config.json"), "utf-8");
@@ -14416,6 +14778,7 @@ async function loadStoreConfig(dir) {
     if (config.store && typeof config.store === "object") {
       const store = config.store;
       if (store.type === "file" && typeof store.path === "string") {
+        validateStorePath(store.path);
         return { type: "file", path: store.path };
       }
       if (store.type === "convex" && typeof store.url === "string") {
@@ -14433,7 +14796,8 @@ function createStore(config) {
   }
   switch (config.type) {
     case "file":
-      return new FileStore(config.path);
+      validateStorePath(config.path);
+      return new FileStore(join22(process.cwd(), config.path));
     case "convex":
       return new ConvexStore({ url: config.url });
     default:
@@ -15347,9 +15711,9 @@ Fathom \u2014 Project Report: ${projectName}`));
       const outputPath = options.output ? resolve19(options.output) : defaultPath;
       const dir = resolve19(outputPath, "..");
       if (!existsSync19(dir)) {
-        mkdirSync10(dir, { recursive: true });
+        mkdirSync11(dir, { recursive: true });
       }
-      writeFileSync11(outputPath, report, "utf-8");
+      writeFileSync12(outputPath, report, "utf-8");
       console.log(
         chalk18.green(`
   \u2713 Report generated: ${outputPath}`)
@@ -15365,17 +15729,29 @@ Fathom \u2014 Project Report: ${projectName}`));
 
 // src/commands/contribute.ts
 import { Command as Command18 } from "commander";
-import { readFileSync as readFileSync18, writeFileSync as writeFileSync12, existsSync as existsSync20, mkdirSync as mkdirSync11 } from "fs";
+import { readFileSync as readFileSync18, writeFileSync as writeFileSync13, existsSync as existsSync20, mkdirSync as mkdirSync12 } from "fs";
 import { resolve as resolve20 } from "path";
 import chalk19 from "chalk";
-import { confirm as confirm4 } from "@inquirer/prompts";
+import { confirm as confirm7 } from "@inquirer/prompts";
 function loadCalibratedProfiles() {
   const profiles = [];
   const registryPath = resolve20(process.cwd(), ".claude", "te", "registry.json");
   const summaryPath = resolve20(process.cwd(), ".claude", "te", "tracking", "summary.json");
   if (existsSync20(registryPath) && existsSync20(summaryPath)) {
-    const registry = JSON.parse(readFileSync18(registryPath, "utf-8"));
-    const summary = JSON.parse(readFileSync18(summaryPath, "utf-8"));
+    let registry;
+    try {
+      registry = JSON.parse(readFileSync18(registryPath, "utf-8"));
+    } catch {
+      console.error(`Failed to parse ${registryPath}: file contains invalid JSON`);
+      return process.exit(1);
+    }
+    let summary;
+    try {
+      summary = JSON.parse(readFileSync18(summaryPath, "utf-8"));
+    } catch {
+      console.error(`Failed to parse ${summaryPath}: file contains invalid JSON`);
+      return process.exit(1);
+    }
     const actuals = /* @__PURE__ */ new Map();
     for (const session of summary.sessions ?? []) {
       if (!session.featureId || session.status === "untagged") continue;
@@ -15452,7 +15828,7 @@ var contributeCommand = new Command18("contribute").description("Share anonymize
   }
   if (!options.yes) {
     try {
-      const confirmed = await confirm4({
+      const confirmed = await confirm7({
         message: "Share this data?",
         default: false
       });
@@ -15466,11 +15842,11 @@ var contributeCommand = new Command18("contribute").description("Share anonymize
     }
   }
   const contributionsDir = resolve20(process.cwd(), ".fathom", "contributions");
-  mkdirSync11(contributionsDir, { recursive: true });
+  mkdirSync12(contributionsDir, { recursive: true });
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const outputPath = resolve20(contributionsDir, `${today}.json`);
   const json = exportContribution(dataPoints);
-  writeFileSync12(outputPath, json, "utf-8");
+  writeFileSync13(outputPath, json, "utf-8");
   console.log(chalk19.green(`
   \u2713 Contribution saved to .fathom/contributions/${today}.json`));
   console.log(chalk19.green("  \u2713 Thank you! This helps make Fathom better for everyone."));
@@ -15479,7 +15855,7 @@ var contributeCommand = new Command18("contribute").description("Share anonymize
 
 // src/commands/feedback.ts
 import { Command as Command19 } from "commander";
-import { writeFileSync as writeFileSync13, mkdirSync as mkdirSync12, readFileSync as readFileSync19, existsSync as existsSync21 } from "fs";
+import { writeFileSync as writeFileSync14, mkdirSync as mkdirSync13, readFileSync as readFileSync19, existsSync as existsSync21 } from "fs";
 import { resolve as resolve21, join as join5 } from "path";
 import chalk20 from "chalk";
 function getIntentSummary() {
@@ -15507,7 +15883,7 @@ function getSystemInfo() {
 }
 function saveFeedback(type, description) {
   const feedbackDir = resolve21(process.cwd(), ".fathom", "feedback");
-  mkdirSync12(feedbackDir, { recursive: true });
+  mkdirSync13(feedbackDir, { recursive: true });
   const sys = getSystemInfo();
   const intent = getIntentSummary();
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
@@ -15544,7 +15920,7 @@ function saveFeedback(type, description) {
     "Review this file, add any additional details, then email to feedback@fathom.dev"
   );
   lines.push("");
-  writeFileSync13(filepath, lines.join("\n"));
+  writeFileSync14(filepath, lines.join("\n"));
   return filepath;
 }
 var feedbackCommand = new Command19("feedback").description("How to report bugs and request features").option("--bug <description>", "Save a bug report to .fathom/feedback/").option(
@@ -15605,9 +15981,10 @@ here's how to reach us:
 // src/commands/sync.ts
 import { Command as Command20 } from "commander";
 import chalk21 from "chalk";
+import { confirm as confirm8 } from "@inquirer/prompts";
 
 // ../sync/dist/index.js
-import { readFileSync as readFileSync20, writeFileSync as writeFileSync14, mkdirSync as mkdirSync13, existsSync as existsSync23 } from "fs";
+import { readFileSync as readFileSync20, writeFileSync as writeFileSync15, mkdirSync as mkdirSync14, existsSync as existsSync23 } from "fs";
 import { resolve as resolve22, dirname as dirname8 } from "path";
 var SyncStatusSchema = external_exports.enum([
   "backlog",
@@ -16300,8 +16677,8 @@ function loadLedger(ledgerPath) {
   return { provider: "", projectKey: "", items: [], lastSync: 0 };
 }
 function saveLedger(ledgerPath, ledger) {
-  mkdirSync13(dirname8(ledgerPath), { recursive: true });
-  writeFileSync14(ledgerPath, JSON.stringify(ledger, null, 2) + "\n");
+  mkdirSync14(dirname8(ledgerPath), { recursive: true });
+  writeFileSync15(ledgerPath, JSON.stringify(ledger, null, 2) + "\n");
 }
 function createSyncManager(config, options) {
   const apiKey = resolveApiKey(config);
@@ -16412,7 +16789,7 @@ function formatStatus2(status) {
   };
   return (colors[status] ?? chalk21.white)(status);
 }
-var syncCommand = new Command20("sync").description("Sync spec slices to external PM tools (Linear, GitHub, Notion, Jira)").requiredOption("--provider <provider>", "PM tool provider (linear, github, notion, jira)").requiredOption("--project-key <key>", "Project key (Linear team key, GitHub owner/repo, Notion database ID, Jira host/project)").option("--pull", "Only pull status updates, don't push new slices").option("--dry-run", "Show what would be synced without making changes").action(async (options) => {
+var syncCommand = new Command20("sync").description("Sync spec slices to external PM tools (Linear, GitHub, Notion, Jira)").requiredOption("--provider <provider>", "PM tool provider (linear, github, notion, jira)").requiredOption("--project-key <key>", "Project key (Linear team key, GitHub owner/repo, Notion database ID, Jira host/project)").option("--pull", "Only pull status updates, don't push new slices").option("--dry-run", "Show what would be synced without making changes").option("-y, --yes", "Skip confirmation prompt").action(async (options) => {
   try {
     const config = loadSyncConfig(options);
     if (!config.projectKey) {
@@ -16435,10 +16812,23 @@ Fathom \u2014 Sync to ${config.provider.charAt(0).toUpperCase() + config.provide
           console.log(chalk21.dim(`    - ${s.sliceId}: ${s.title}`));
         }
       } else {
+        if (!options.yes) {
+          const proceed = await confirm8({
+            message: `Sync ${slices.length} slices to ${config.provider}?`,
+            default: true
+          });
+          if (!proceed) {
+            console.log(chalk21.dim("\n  Aborted."));
+            return;
+          }
+        }
         console.log(chalk21.dim(`
   Syncing ${slices.length} pending slice(s) to ${config.provider} project ${config.projectKey}...
 `));
-        const results = await manager.syncSlices(slices);
+        const results = await withSpinner(
+          `Syncing slices to ${config.provider}...`,
+          async () => manager.syncSlices(slices)
+        );
         if (results.length === 0) {
           console.log(chalk21.dim("  All slices already synced."));
         } else {
@@ -16450,7 +16840,10 @@ Fathom \u2014 Sync to ${config.provider.charAt(0).toUpperCase() + config.provide
     }
     if (!options.dryRun) {
       console.log(chalk21.dim("\n  Pulling status updates..."));
-      const updates = await manager.pullStatus();
+      const updates = await withSpinner(
+        "Pulling status updates...",
+        async () => manager.pullStatus()
+      );
       if (updates.length === 0) {
         console.log(chalk21.dim("  No status changes."));
       } else {
@@ -16481,9 +16874,9 @@ Fathom \u2014 Sync to ${config.provider.charAt(0).toUpperCase() + config.provide
 // src/commands/install-plugin.ts
 import { Command as Command21 } from "commander";
 import {
-  writeFileSync as writeFileSync15,
+  writeFileSync as writeFileSync16,
   readFileSync as readFileSync23,
-  mkdirSync as mkdirSync14,
+  mkdirSync as mkdirSync15,
   existsSync as existsSync25,
   readdirSync as readdirSync4
 } from "fs";
@@ -16523,8 +16916,8 @@ var installPluginCommand = new Command21("install-plugin").description(
         "fathom",
         skillDir
       );
-      mkdirSync14(destDir, { recursive: true });
-      writeFileSync15(resolve24(destDir, "SKILL.md"), readFileSync23(src, "utf-8"));
+      mkdirSync15(destDir, { recursive: true });
+      writeFileSync16(resolve24(destDir, "SKILL.md"), readFileSync23(src, "utf-8"));
       console.log(chalk22.green(`  \u2713 .claude/skills/fathom/${skillDir}/SKILL.md`));
     }
   }
@@ -16535,8 +16928,8 @@ var installPluginCommand = new Command21("install-plugin").description(
   );
   if (existsSync25(pluginJsonSrc)) {
     const destDir = resolve24(projectDir, ".claude-plugin");
-    mkdirSync14(destDir, { recursive: true });
-    writeFileSync15(
+    mkdirSync15(destDir, { recursive: true });
+    writeFileSync16(
       resolve24(destDir, "plugin.json"),
       readFileSync23(pluginJsonSrc, "utf-8")
     );
@@ -16556,7 +16949,7 @@ var installPluginCommand = new Command21("install-plugin").description(
     command: "npx",
     args: ["-y", "fathom-token-mcp@latest", "--project-dir", "."]
   };
-  writeFileSync15(mcpPath, JSON.stringify(mcpConfig, null, 2) + "\n");
+  writeFileSync16(mcpPath, JSON.stringify(mcpConfig, null, 2) + "\n");
   console.log(chalk22.green("  \u2713 .mcp.json (MCP auto-discovery)"));
   console.log(chalk22.bold("\n\u2713 Fathom plugin installed"));
   console.log(
@@ -16564,8 +16957,261 @@ var installPluginCommand = new Command21("install-plugin").description(
   );
 });
 
+// src/commands/completions.ts
+import { Command as Command22 } from "commander";
+var COMMANDS = [
+  "go",
+  "intake",
+  "analyze",
+  "estimate",
+  "setup",
+  "init",
+  "track",
+  "reconcile",
+  "calibrate",
+  "velocity",
+  "report",
+  "project",
+  "contribute",
+  "feedback",
+  "sync",
+  "install-plugin",
+  "status",
+  "pricing",
+  "validate",
+  "rename",
+  "research",
+  "doctor",
+  "completions"
+];
+var GLOBAL_FLAGS = ["--help", "--version"];
+function generateBashCompletion() {
+  const words = [...COMMANDS, ...GLOBAL_FLAGS].join(" ");
+  return `#!/bin/bash
+# bash completion for fathom
+
+_fathom() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local commands="${words}"
+  COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )
+  return 0
+}
+
+complete -F _fathom fathom
+`;
+}
+function generateZshCompletion() {
+  const words = [...COMMANDS, ...GLOBAL_FLAGS].join(" ");
+  return `#compdef fathom
+# zsh completion for fathom
+
+_fathom() {
+  local -a commands
+  commands=(${words})
+  compadd -a commands
+}
+
+_fathom "$@"
+`;
+}
+var completionsCommand = new Command22("completions").description("Generate shell completion scripts").argument("<shell>", "Shell type: bash or zsh").action((shell) => {
+  switch (shell) {
+    case "bash":
+      process.stdout.write(generateBashCompletion());
+      break;
+    case "zsh":
+      process.stdout.write(generateZshCompletion());
+      break;
+    default:
+      console.error(
+        "Unsupported shell. Use: fathom completions bash|zsh"
+      );
+      process.exitCode = 1;
+  }
+});
+
+// src/commands/doctor.ts
+import { Command as Command23 } from "commander";
+import { existsSync as existsSync26, readFileSync as readFileSync24 } from "fs";
+import { resolve as resolve25 } from "path";
+import chalk23 from "chalk";
+async function runChecks(cwd) {
+  const results = [];
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  results.push({
+    name: "Node version >= 20",
+    ok: nodeMajor >= 20,
+    message: nodeMajor >= 20 ? `Node.js v${process.versions.node}` : "Upgrade to Node.js 20 or later"
+  });
+  const fathomDir = resolve25(cwd, ".fathom");
+  const hasFathomDir = existsSync26(fathomDir);
+  results.push({
+    name: ".fathom/ directory",
+    ok: hasFathomDir,
+    message: hasFathomDir ? ".fathom/ found" : "Run `fathom init` to create project config"
+  });
+  const configPath = resolve25(fathomDir, "config.json");
+  let configOk = false;
+  let configMsg = "Run `fathom init` to create project config";
+  if (hasFathomDir && existsSync26(configPath)) {
+    try {
+      JSON.parse(readFileSync24(configPath, "utf-8"));
+      configOk = true;
+      configMsg = "config.json valid";
+    } catch {
+      configMsg = "Delete .fathom/config.json and run `fathom init`";
+    }
+  } else if (hasFathomDir) {
+    configMsg = "Run `fathom init` to create config.json";
+  }
+  results.push({
+    name: "config.json valid",
+    ok: configOk,
+    message: configMsg
+  });
+  const intentPath = resolve25(fathomDir, "intent.yaml");
+  let intentOk = false;
+  let intentMsg = "Run `fathom init` to create intent.yaml";
+  if (hasFathomDir && existsSync26(intentPath)) {
+    try {
+      jsYaml.load(readFileSync24(intentPath, "utf-8"), { schema: jsYaml.JSON_SCHEMA });
+      intentOk = true;
+      intentMsg = "intent.yaml parseable";
+    } catch {
+      intentMsg = "Check intent.yaml syntax \u2014 run `fathom validate`";
+    }
+  }
+  results.push({
+    name: "intent.yaml parseable",
+    ok: intentOk,
+    message: intentMsg
+  });
+  const legacyDir = resolve25(cwd, ".claude", "te");
+  const legacyRegistry = resolve25(legacyDir, "registry.json");
+  const legacyTracking = resolve25(legacyDir, "tracking", "summary.json");
+  const hasLegacyRegistry = existsSync26(legacyRegistry);
+  const hasLegacyTracking = existsSync26(legacyTracking);
+  if (existsSync26(legacyDir)) {
+    results.push({
+      name: "Legacy .claude/te/ data",
+      ok: hasLegacyRegistry && hasLegacyTracking,
+      message: hasLegacyRegistry && hasLegacyTracking ? "Legacy registry and tracking data found" : `Missing ${!hasLegacyRegistry ? "registry.json" : ""}${!hasLegacyRegistry && !hasLegacyTracking ? " and " : ""}${!hasLegacyTracking ? "tracking/summary.json" : ""} \u2014 run \`fathom analyze\` and \`fathom track\` to populate`
+    });
+  }
+  let dataOk = false;
+  let dataMsg = "Reinstall fathom \u2014 `npm i -g fathom`";
+  try {
+    loadData();
+    dataOk = true;
+    dataMsg = "Core data files loaded";
+  } catch {
+  }
+  results.push({
+    name: "Data files loadable",
+    ok: dataOk,
+    message: dataMsg
+  });
+  return results;
+}
+var doctorCommand = new Command23("doctor").description("Check project health and configuration").action(async () => {
+  console.log(chalk23.bold("\nFathom \u2014 Doctor"));
+  console.log(chalk23.dim("\u2500".repeat(50)));
+  const results = await runChecks(process.cwd());
+  let passed = 0;
+  for (const r of results) {
+    if (r.ok) {
+      console.log(chalk23.green(`  \u2713 ${r.name}`));
+      passed++;
+    } else {
+      console.log(chalk23.red(`  \u2717 ${r.name} \u2014 ${r.message}`));
+    }
+  }
+  console.log(
+    chalk23.dim(`
+${passed}/${results.length} checks passed
+`)
+  );
+  if (passed < results.length) {
+    process.exit(1);
+  }
+});
+
+// src/index.ts
+import chalk24 from "chalk";
+
+// src/ux/update-checker.ts
+import { readFileSync as readFileSync25, writeFileSync as writeFileSync17, mkdirSync as mkdirSync16, existsSync as existsSync27 } from "fs";
+import { join as join6 } from "path";
+import { homedir as homedir3 } from "os";
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+function getCachePath() {
+  return join6(homedir3(), ".fathom", "update-check.json");
+}
+function readCache() {
+  try {
+    const cachePath = getCachePath();
+    if (!existsSync27(cachePath)) return null;
+    const raw = readFileSync25(cachePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function writeCache(latest) {
+  try {
+    const cachePath = getCachePath();
+    const dir = join6(homedir3(), ".fathom");
+    if (!existsSync27(dir)) {
+      mkdirSync16(dir, { recursive: true });
+    }
+    writeFileSync17(
+      cachePath,
+      JSON.stringify({ latest, checkedAt: (/* @__PURE__ */ new Date()).toISOString() })
+    );
+  } catch {
+  }
+}
+function isCacheFresh(cache) {
+  const checkedAt = new Date(cache.checkedAt).getTime();
+  return Date.now() - checkedAt < CACHE_TTL_MS;
+}
+async function checkForUpdate() {
+  try {
+    const current = VERSION;
+    const cache = readCache();
+    if (cache && isCacheFresh(cache)) {
+      return {
+        current,
+        latest: cache.latest,
+        updateAvailable: cache.latest !== current
+      };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e3);
+    try {
+      const response = await fetch(
+        "https://registry.npmjs.org/fathom-cli/latest",
+        { signal: controller.signal }
+      );
+      if (!response.ok) return null;
+      const data = await response.json();
+      const latest = data.version;
+      writeCache(latest);
+      return {
+        current,
+        latest,
+        updateAvailable: latest !== current
+      };
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch {
+    return null;
+  }
+}
+
 // src/index.ts
-var program = new Command22();
+var program = new Command24();
 program.name("fathom").description("Workflow intelligence platform for AI-augmented development").version(VERSION);
 program.addCommand(goCommand, { isDefault: true });
 program.addCommand(intakeCommand);
@@ -16588,5 +17234,17 @@ program.addCommand(pricingCommand);
 program.addCommand(validateCommand);
 program.addCommand(renameCommand);
 program.addCommand(researchCommand);
+program.addCommand(completionsCommand);
+program.addCommand(doctorCommand);
 program.parse();
+checkForUpdate().then((result) => {
+  if (result?.updateAvailable) {
+    console.error(
+      chalk24.yellow(`
+Update available: ${result.current} \u2192 ${result.latest}`)
+    );
+    console.error(chalk24.yellow(`Run: npm i -g fathom-cli`));
+  }
+}).catch(() => {
+});
 //# sourceMappingURL=index.js.map