ai-cost-audit 0.1.0

package/dist/cli.js

@@ -0,0 +1,1286 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import path8 from "path";
+import { Command } from "commander";
+import pc from "picocolors";
+
+// src/config.ts
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import path from "path";
+import { z } from "zod";
+var rangeSchema = z.tuple([z.number().nonnegative(), z.number().nonnegative()]);
+var configSchema = z.object({
+  providers: z.array(z.string()).default(["anthropic"]),
+  models: z.array(z.string()).default(["claude-opus-4-8", "claude-sonnet-5"]),
+  monthlyBudget: z.number().positive().nullable().default(null),
+  developers: z.number().int().positive().default(1),
+  baselineTokenLimit: z.number().positive().nullable().default(null),
+  growthThresholdPct: z.number().positive().default(20),
+  requestsPerDay: z.array(z.number().positive()).default([50, 200, 1e3]),
+  cache: z.object({
+    enabled: z.boolean().default(true),
+    requestsPerSession: z.number().int().positive().default(10)
+  }).default({}),
+  variable: z.object({
+    conversationHistory: rangeSchema.default([8e3, 25e3]),
+    taskFiles: rangeSchema.default([5e3, 15e3])
+  }).default({}),
+  calibration: z.record(z.number().positive()).default({}),
+  pricingOverrides: z.record(
+    z.object({
+      inputPerMTok: z.number().nonnegative(),
+      outputPerMTok: z.number().nonnegative().optional()
+    })
+  ).default({}),
+  mcp: z.object({
+    knownSchemaTokens: z.record(z.number().nonnegative()).default({})
+  }).default({}),
+  duplication: z.object({
+    minBlockTokens: z.number().positive().default(40),
+    similarityThreshold: z.number().min(0).max(1).default(0.8)
+  }).default({}),
+  scan: z.object({
+    include: z.array(z.string()).default([
+      "CLAUDE.md",
+      "CLAUDE.local.md",
+      "AGENTS.md",
+      ".github/copilot-instructions.md",
+      ".github/**/*.instructions.md",
+      ".claude/**/*",
+      ".cursor/rules/**/*",
+      ".cursorrules",
+      ".mcp.json",
+      "mcp.json",
+      "prompts/**/*"
+    ]),
+    exclude: z.array(z.string()).default(["**/node_modules/**", "**/dist/**", "**/.git/**"])
+  }).default({}),
+  refDepth: z.number().int().min(0).max(10).default(3),
+  includeGlobal: z.boolean().default(true)
+}).strict();
+var CONFIG_FILENAME = "ai-cost-audit.json";
+async function loadConfig(projectPath, explicitPath) {
+  let configPath = null;
+  if (explicitPath) {
+    configPath = path.resolve(explicitPath);
+    if (!existsSync(configPath)) {
+      throw new Error(`Config file not found: ${configPath}`);
+    }
+  } else {
+    const candidate = path.join(projectPath, CONFIG_FILENAME);
+    if (existsSync(candidate)) configPath = candidate;
+  }
+  let raw = {};
+  if (configPath) {
+    try {
+      raw = JSON.parse(await readFile(configPath, "utf8"));
+    } catch (err) {
+      throw new Error(
+        `Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  const parsed = configSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid config${configPath ? ` (${configPath})` : ""}:
+${issues}`);
+  }
+  return { config: parsed.data, configPath };
+}
+
+// src/scan.ts
+import path6 from "path";
+
+// src/adapters/claudeCode.ts
+import { readFile as readFile3 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import os from "os";
+import path3 from "path";
+import fg from "fast-glob";
+
+// src/tokenizer.ts
+import { Tiktoken } from "js-tiktoken/lite";
+import o200k_base from "js-tiktoken/ranks/o200k_base";
+
+// src/pricing.ts
+var PRICING_AS_OF = "2026-07-01";
+var PRICING_STALE_AFTER_DAYS = 90;
+var PROVIDERS = {
+  anthropic: {
+    // o200k_base undercounts Claude tokens on typical instruction text;
+    // Claude counts are roughly 1.15-1.25x the o200k count.
+    calibration: 1.2,
+    // Prompt-cache multipliers relative to base input price (5-minute TTL).
+    cache: { write: 1.25, read: 0.1 }
+  },
+  openai: {
+    calibration: 1
+    // No cache modeling seeded; OpenAI's automatic caching differs — users can
+    // approximate via pricingOverrides + a custom provider entry later.
+  }
+};
+var MODELS = [
+  {
+    id: "claude-opus-4-8",
+    provider: "anthropic",
+    inputPerMTok: 5,
+    outputPerMTok: 25
+  },
+  {
+    id: "claude-sonnet-5",
+    provider: "anthropic",
+    inputPerMTok: 3,
+    outputPerMTok: 15,
+    note: "intro pricing $2/$10 per MTok through 2026-08-31"
+  },
+  {
+    id: "claude-haiku-4-5",
+    provider: "anthropic",
+    inputPerMTok: 1,
+    outputPerMTok: 5
+  },
+  {
+    id: "gpt",
+    provider: "openai",
+    inputPerMTok: null,
+    outputPerMTok: null,
+    note: "set inputPerMTok via config.pricingOverrides.gpt"
+  }
+];
+function isPricingStale(now = /* @__PURE__ */ new Date()) {
+  const asOf = new Date(PRICING_AS_OF);
+  const ageDays = (now.getTime() - asOf.getTime()) / (1e3 * 60 * 60 * 24);
+  return ageDays > PRICING_STALE_AFTER_DAYS;
+}
+function resolveModels(cfg) {
+  return cfg.models.map((id) => {
+    const base = MODELS.find((m) => m.id === id);
+    const override = cfg.pricingOverrides[id];
+    if (!base && !override) {
+      return {
+        id,
+        provider: "unknown",
+        inputPerMTok: null,
+        outputPerMTok: null,
+        note: "unknown model \u2014 set pricing via config.pricingOverrides"
+      };
+    }
+    return {
+      id,
+      provider: base?.provider ?? "unknown",
+      inputPerMTok: override?.inputPerMTok ?? base?.inputPerMTok ?? null,
+      outputPerMTok: override?.outputPerMTok ?? base?.outputPerMTok ?? null,
+      note: base?.note
+    };
+  });
+}
+function resolveProvider(name, cfg) {
+  const base = PROVIDERS[name] ?? { calibration: 1 };
+  const calibration = cfg.calibration[name] ?? base.calibration;
+  return { ...base, calibration };
+}
+
+// src/tokenizer.ts
+var encoder = null;
+function getEncoder() {
+  if (!encoder) encoder = new Tiktoken(o200k_base);
+  return encoder;
+}
+function countRawTokens(text) {
+  if (text.length === 0) return 0;
+  return getEncoder().encode(text).length;
+}
+function estimateTokens(text, provider, cfg) {
+  const raw = countRawTokens(text);
+  const { calibration } = resolveProvider(provider, cfg);
+  return Math.round(raw * calibration);
+}
+var DISCLOSURE = "Token counts are offline estimates (\xB1~15-20% for Anthropic models). No model API is called.";
+
+// src/discovery.ts
+import { readFile as readFile2 } from "fs/promises";
+import { existsSync as existsSync2, statSync } from "fs";
+import path2 from "path";
+var AT_IMPORT_RE = /(?:^|\s)@((?:\.{0,2}\/)?[\w./-]+\.(?:md|txt|json))\b/gm;
+var MD_LINK_RE = /\[[^\]]*\]\((?!https?:\/\/|mailto:|#)([^)\s]+?\.(?:md|txt|json))(?:#[^)]*)?\)/g;
+function extractReferences(text) {
+  const refs = /* @__PURE__ */ new Set();
+  for (const match of text.matchAll(AT_IMPORT_RE)) {
+    refs.add(match[1]);
+  }
+  for (const match of text.matchAll(MD_LINK_RE)) {
+    refs.add(match[1]);
+  }
+  return [...refs];
+}
+async function followReferences(rootFile, rootText, projectPath, maxDepth) {
+  const found = [];
+  const visited = /* @__PURE__ */ new Set([path2.resolve(rootFile)]);
+  let frontier = [{ file: rootFile, text: rootText }];
+  for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
+    const next = [];
+    for (const { file, text } of frontier) {
+      for (const ref of extractReferences(text)) {
+        const baseDir = path2.dirname(file);
+        const candidates = [path2.resolve(baseDir, ref), path2.resolve(projectPath, ref)];
+        const resolved = candidates.find(
+          (c) => existsSync2(c) && statSync(c).isFile() && insideProject(c, projectPath)
+        );
+        if (!resolved || visited.has(resolved)) continue;
+        visited.add(resolved);
+        try {
+          const refText = await readFile2(resolved, "utf8");
+          found.push({ absPath: resolved, referencedFrom: file });
+          next.push({ file: resolved, text: refText });
+        } catch {
+        }
+      }
+    }
+    frontier = next;
+  }
+  return found;
+}
+function insideProject(absPath, projectPath) {
+  const rel = path2.relative(path2.resolve(projectPath), absPath);
+  return !rel.startsWith("..") && !path2.isAbsolute(rel);
+}
+function displayPath(absPath, projectPath) {
+  const rel = path2.relative(path2.resolve(projectPath), absPath);
+  return rel.startsWith("..") ? absPath : rel;
+}
+
+// src/adapters/claudeCode.ts
+var claudeCodeAdapter = {
+  name: "claude-code",
+  async discover(projectPath, cfg) {
+    const sources = [];
+    const provider = "anthropic";
+    const addFile = async (absPath, partial) => {
+      if (!existsSync3(absPath)) return null;
+      let text;
+      try {
+        text = await readFile3(absPath, "utf8");
+      } catch {
+        return null;
+      }
+      sources.push({
+        path: partial.path ?? displayPath(absPath, projectPath),
+        adapter: "claude-code",
+        kind: partial.kind,
+        usage: partial.usage,
+        scope: partial.scope,
+        tokens: estimateTokens(text, provider, cfg),
+        confidence: partial.confidence,
+        note: partial.note,
+        referencedFrom: partial.referencedFrom,
+        text
+      });
+      return text;
+    };
+    const rootClaudeMd = path3.join(projectPath, "CLAUDE.md");
+    const rootText = await addFile(rootClaudeMd, {
+      kind: "repo-instructions",
+      usage: "guaranteed",
+      scope: "repo",
+      confidence: "high"
+    });
+    await addFile(path3.join(projectPath, "CLAUDE.local.md"), {
+      kind: "local-instructions",
+      usage: "guaranteed",
+      scope: "repo",
+      confidence: "high",
+      note: "typically gitignored; loads for the local developer only"
+    });
+    if (rootText) {
+      const refs = await followReferences(rootClaudeMd, rootText, projectPath, cfg.refDepth);
+      for (const ref of refs) {
+        await addFile(ref.absPath, {
+          kind: "referenced-doc",
+          usage: "guaranteed",
+          scope: "repo",
+          confidence: "medium",
+          note: "pulled in via reference from an instruction file",
+          referencedFrom: displayPath(ref.referencedFrom, projectPath)
+        });
+      }
+    }
+    if (cfg.includeGlobal) {
+      await addFile(path3.join(os.homedir(), ".claude", "CLAUDE.md"), {
+        path: "~/.claude/CLAUDE.md",
+        kind: "global-instructions",
+        usage: "guaranteed",
+        scope: "global",
+        confidence: "high",
+        note: "user-global; reported but not counted toward the CI budget"
+      });
+    }
+    const agentFiles = await fg(".claude/agents/**/*.md", {
+      cwd: projectPath,
+      absolute: true,
+      dot: true
+    });
+    for (const file of agentFiles.sort()) {
+      await addFile(file, {
+        kind: "agent",
+        usage: "conditional",
+        scope: "repo",
+        confidence: "medium",
+        note: "loads when the agent is invoked; its description line loads every session"
+      });
+    }
+    const skillFiles = await fg(".claude/skills/*/SKILL.md", {
+      cwd: projectPath,
+      absolute: true,
+      dot: true
+    });
+    for (const file of skillFiles.sort()) {
+      let text;
+      try {
+        text = await readFile3(file, "utf8");
+      } catch {
+        continue;
+      }
+      const { frontmatter, body } = splitFrontmatter(text);
+      const rel = displayPath(file, projectPath);
+      if (frontmatter) {
+        sources.push({
+          path: `${rel} (description)`,
+          adapter: "claude-code",
+          kind: "skill-description",
+          usage: "guaranteed",
+          scope: "repo",
+          tokens: estimateTokens(frontmatter, "anthropic", cfg),
+          confidence: "high",
+          note: "skill metadata loads every session (progressive disclosure)",
+          text: frontmatter
+        });
+      }
+      if (body.trim().length > 0) {
+        sources.push({
+          path: `${rel} (body)`,
+          adapter: "claude-code",
+          kind: "skill-body",
+          usage: "conditional",
+          scope: "repo",
+          tokens: estimateTokens(body, "anthropic", cfg),
+          confidence: "high",
+          note: "loads only when the skill is invoked",
+          text: body
+        });
+      }
+    }
+    const commandFiles = await fg(".claude/commands/**/*.md", {
+      cwd: projectPath,
+      absolute: true,
+      dot: true
+    });
+    for (const file of commandFiles.sort()) {
+      await addFile(file, {
+        kind: "command",
+        usage: "conditional",
+        scope: "repo",
+        confidence: "high",
+        note: "loads when the command is invoked"
+      });
+    }
+    return sources;
+  }
+};
+function splitFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { frontmatter: null, body: text };
+  return { frontmatter: match[0], body: text.slice(match[0].length) };
+}
+
+// src/adapters/genericMcp.ts
+import { readFile as readFile4 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import path4 from "path";
+var genericMcpAdapter = {
+  name: "generic-mcp",
+  async discover(projectPath, cfg) {
+    const sources = [];
+    for (const filename of [".mcp.json", "mcp.json"]) {
+      const absPath = path4.join(projectPath, filename);
+      if (!existsSync4(absPath)) continue;
+      let text;
+      try {
+        text = await readFile4(absPath, "utf8");
+      } catch {
+        continue;
+      }
+      let servers = {};
+      try {
+        const parsed = JSON.parse(text);
+        servers = parsed.mcpServers ?? {};
+      } catch {
+        sources.push({
+          path: filename,
+          adapter: "generic-mcp",
+          kind: "mcp-config",
+          usage: "guaranteed",
+          scope: "repo",
+          tokens: estimateTokens(text, "anthropic", cfg),
+          confidence: "low",
+          note: "file is not valid JSON; counted raw",
+          text
+        });
+        continue;
+      }
+      const serverNames = Object.keys(servers);
+      if (serverNames.length === 0) continue;
+      for (const name of serverNames) {
+        const known = cfg.mcp.knownSchemaTokens[name];
+        const configJson = JSON.stringify(servers[name] ?? {}, null, 2);
+        if (known !== void 0) {
+          sources.push({
+            path: `${filename} \u2192 ${name}`,
+            adapter: "generic-mcp",
+            kind: "mcp-config",
+            usage: "guaranteed",
+            scope: "repo",
+            tokens: known,
+            confidence: "medium",
+            note: "schema size pinned via config.mcp.knownSchemaTokens",
+            text: configJson
+          });
+        } else {
+          sources.push({
+            path: `${filename} \u2192 ${name}`,
+            adapter: "generic-mcp",
+            kind: "mcp-config",
+            usage: "guaranteed",
+            scope: "repo",
+            tokens: estimateTokens(configJson, "anthropic", cfg),
+            confidence: "low",
+            note: "live tool schemas not measured (requires a running server); actual context load is usually far larger \u2014 pin via config.mcp.knownSchemaTokens",
+            text: configJson
+          });
+        }
+      }
+    }
+    return sources;
+  }
+};
+
+// src/adapters/instructions.ts
+import { readFile as readFile5 } from "fs/promises";
+import path5 from "path";
+import fg2 from "fast-glob";
+var instructionsAdapter = {
+  name: "instructions",
+  async discover(projectPath, cfg) {
+    const sources = [];
+    const add = async (relPath, kind, usage, confidence, note) => {
+      let text;
+      try {
+        text = await readFile5(path5.join(projectPath, relPath), "utf8");
+      } catch {
+        return;
+      }
+      sources.push({
+        path: relPath,
+        adapter: "instructions",
+        kind,
+        usage,
+        scope: "repo",
+        tokens: estimateTokens(text, "anthropic", cfg),
+        confidence,
+        note,
+        text
+      });
+    };
+    const glob = (pattern) => fg2(pattern, { cwd: projectPath, dot: true, onlyFiles: true }).then((r) => r.sort());
+    for (const file of await glob("AGENTS.md")) {
+      await add(file, "repo-instructions", "guaranteed", "high", "loaded by AGENTS.md-aware tools");
+    }
+    for (const file of await glob(".cursor/rules/**/*.mdc")) {
+      await add(
+        file,
+        "cursor-rules",
+        "guaranteed",
+        "medium",
+        "Cursor rule; may be glob-scoped or manual (frontmatter not parsed in v1)"
+      );
+    }
+    for (const file of await glob(".cursorrules")) {
+      await add(
+        file,
+        "cursor-rules",
+        "guaranteed",
+        "high",
+        "legacy .cursorrules format (Cursor now uses .cursor/rules/*.mdc)"
+      );
+    }
+    for (const file of await glob(".github/copilot-instructions.md")) {
+      await add(file, "copilot-instructions", "guaranteed", "high", "loaded on every Copilot chat request");
+    }
+    for (const file of await glob(".github/**/*.instructions.md")) {
+      await add(
+        file,
+        "copilot-instructions",
+        "conditional",
+        "medium",
+        "path-scoped Copilot instructions; loads when matching files are in play"
+      );
+    }
+    return sources;
+  }
+};
+
+// src/adapters/index.ts
+var ADAPTERS = [
+  claudeCodeAdapter,
+  genericMcpAdapter,
+  instructionsAdapter
+];
+async function discoverAll(projectPath, cfg) {
+  const seen = /* @__PURE__ */ new Set();
+  const all = [];
+  for (const adapter of ADAPTERS) {
+    const sources = await adapter.discover(projectPath, cfg);
+    for (const source of sources) {
+      if (seen.has(source.path)) continue;
+      seen.add(source.path);
+      all.push(source);
+    }
+  }
+  return all;
+}
+
+// src/analysis/duplication.ts
+import { createHash } from "crypto";
+function splitBlocks(source, minBlockTokens) {
+  const parts = source.text.split(/\r?\n(?=#{1,6}\s)|\r?\n\s*\r?\n/).map((p) => p.trim()).filter((p) => p.length > 0);
+  const blocks = [];
+  for (const text of parts) {
+    const normalized = normalize(text);
+    if (normalized.length === 0) continue;
+    const tokens = countRawTokens(normalized);
+    if (tokens < minBlockTokens) continue;
+    blocks.push({ sourcePath: source.path, text, normalized, tokens });
+  }
+  return blocks;
+}
+function normalize(text) {
+  return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function shingles(normalized, k = 3) {
+  const words = normalized.split(" ");
+  const result = /* @__PURE__ */ new Set();
+  if (words.length <= k) {
+    result.add(words.join(" "));
+    return result;
+  }
+  for (let i = 0; i <= words.length - k; i++) {
+    result.add(words.slice(i, i + k).join(" "));
+  }
+  return result;
+}
+function containment(a, b) {
+  let intersection = 0;
+  const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+  for (const item of small) if (large.has(item)) intersection++;
+  const minSize = Math.min(a.size, b.size);
+  return minSize === 0 ? 0 : intersection / minSize;
+}
+function findDuplicates(sources, cfg) {
+  const blocks = sources.flatMap((s) => splitBlocks(s, cfg.duplication.minBlockTokens));
+  const groups = [];
+  const byHash = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    const hash = createHash("sha256").update(block.normalized).digest("hex");
+    const list = byHash.get(hash);
+    if (list) list.push(block);
+    else byHash.set(hash, [block]);
+  }
+  const inExactGroup = /* @__PURE__ */ new Set();
+  for (const group of byHash.values()) {
+    const uniquePaths = [...new Set(group.map((b) => b.sourcePath))];
+    if (group.length < 2 || uniquePaths.length < 2) continue;
+    for (const b of group) inExactGroup.add(b);
+    groups.push({
+      sources: uniquePaths,
+      redundantTokens: group[0].tokens * (group.length - 1),
+      excerpt: excerpt(group[0].text),
+      exact: true
+    });
+  }
+  const remaining = blocks.filter((b) => !inExactGroup.has(b));
+  const shingleCache = /* @__PURE__ */ new Map();
+  const getShingles = (b) => {
+    let s = shingleCache.get(b);
+    if (!s) {
+      s = shingles(b.normalized);
+      shingleCache.set(b, s);
+    }
+    return s;
+  };
+  const claimed = /* @__PURE__ */ new Set();
+  for (let i = 0; i < remaining.length; i++) {
+    const a = remaining[i];
+    if (claimed.has(a)) continue;
+    const cluster = [a];
+    for (let j = i + 1; j < remaining.length; j++) {
+      const b = remaining[j];
+      if (claimed.has(b) || b.sourcePath === a.sourcePath) continue;
+      if (containment(getShingles(a), getShingles(b)) >= cfg.duplication.similarityThreshold) {
+        cluster.push(b);
+      }
+    }
+    if (cluster.length >= 2) {
+      for (const b of cluster) claimed.add(b);
+      const minTokens = Math.min(...cluster.map((b) => b.tokens));
+      groups.push({
+        sources: [...new Set(cluster.map((b) => b.sourcePath))],
+        redundantTokens: minTokens * (cluster.length - 1),
+        excerpt: excerpt(a.text),
+        exact: false
+      });
+    }
+  }
+  return groups.sort((a, b) => b.redundantTokens - a.redundantTokens);
+}
+function excerpt(text) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > 80 ? `${flat.slice(0, 77)}...` : flat;
+}
+
+// src/analysis/findings.ts
+var LARGE_SOURCE_PCT = 25;
+var MCP_SHARE_PCT = 30;
+function deriveFindings(sources, duplicates, gatedBaseline, snapshot, cfg) {
+  const findings = [];
+  for (const group of duplicates) {
+    findings.push({
+      rule: group.exact ? "duplicate-content" : "near-duplicate-content",
+      severity: "warn",
+      message: group.exact ? `${group.redundantTokens.toLocaleString()} redundant tokens: identical content in ${group.sources.join(", ")} ("${group.excerpt}")` : `~${group.redundantTokens.toLocaleString()} redundant tokens: nearly identical content in ${group.sources.join(", ")} ("${group.excerpt}")`,
+      sources: group.sources,
+      tokens: group.redundantTokens
+    });
+  }
+  if (gatedBaseline > 0) {
+    for (const s of sources) {
+      if (s.scope !== "repo" || s.usage !== "guaranteed") continue;
+      const pct = s.tokens / gatedBaseline * 100;
+      if (pct > LARGE_SOURCE_PCT) {
+        findings.push({
+          rule: "large-source",
+          severity: "warn",
+          message: `${s.path} alone is ${Math.round(pct)}% of the baseline (${s.tokens.toLocaleString()} tokens). Consider splitting into on-demand skills or conditional instructions.`,
+          sources: [s.path],
+          tokens: s.tokens
+        });
+      }
+    }
+    const mcpTokens = sources.filter((s) => s.adapter === "generic-mcp" && s.scope === "repo" && s.usage === "guaranteed").reduce((sum, s) => sum + s.tokens, 0);
+    const mcpPct = mcpTokens / gatedBaseline * 100;
+    if (mcpPct > MCP_SHARE_PCT) {
+      findings.push({
+        rule: "mcp-schema-share",
+        severity: "info",
+        message: `MCP configuration is ${Math.round(mcpPct)}% of the baseline (${mcpTokens.toLocaleString()} tokens, likely an undercount \u2014 live schemas unmeasured). Consider restricting MCP tools by task.`,
+        sources: sources.filter((s) => s.adapter === "generic-mcp").map((s) => s.path),
+        tokens: mcpTokens
+      });
+    }
+  }
+  if (snapshot && snapshot.gatedBaseline > 0) {
+    const growthPct = (gatedBaseline - snapshot.gatedBaseline) / snapshot.gatedBaseline * 100;
+    if (growthPct > cfg.growthThresholdPct) {
+      const causes = topGrowthCauses(sources, snapshot);
+      findings.push({
+        rule: "baseline-growth",
+        severity: "warn",
+        message: `Baseline grew ${growthPct.toFixed(0)}% since the last snapshot (${snapshot.gatedBaseline.toLocaleString()} \u2192 ${gatedBaseline.toLocaleString()} tokens).` + (causes.length > 0 ? ` Primary cause: ${causes[0]}` : ""),
+        sources: [],
+        tokens: gatedBaseline - snapshot.gatedBaseline
+      });
+    }
+  }
+  const legacy = sources.filter((s) => s.path === ".cursorrules");
+  if (legacy.length > 0) {
+    findings.push({
+      rule: "legacy-cursorrules",
+      severity: "info",
+      message: "Legacy .cursorrules file found. Cursor now uses .cursor/rules/*.mdc, which supports glob scoping (loading rules only when relevant).",
+      sources: [".cursorrules"]
+    });
+  }
+  const unmeasured = sources.filter(
+    (s) => s.adapter === "generic-mcp" && s.confidence === "low"
+  );
+  if (unmeasured.length > 0) {
+    findings.push({
+      rule: "unmeasured-mcp",
+      severity: "info",
+      message: `${unmeasured.length} MCP server(s) counted by config size only \u2014 live tool schemas require a running server and are usually far larger. Pin measured sizes via config.mcp.knownSchemaTokens.`,
+      sources: unmeasured.map((s) => s.path)
+    });
+  }
+  const severityRank = { error: 0, warn: 1, info: 2 };
+  return findings.sort(
+    (a, b) => severityRank[a.severity] - severityRank[b.severity] || (b.tokens ?? 0) - (a.tokens ?? 0)
+  );
+}
+function topGrowthCauses(sources, snapshot) {
+  const previous = new Map(snapshot.sources.map((s) => [s.path, s.tokens]));
+  const current = new Map(
+    sources.filter((s) => s.scope === "repo" && s.usage === "guaranteed").map((s) => [s.path, s.tokens])
+  );
+  const diffs = [];
+  for (const [path9, tokens] of current) {
+    const prev = previous.get(path9);
+    if (prev === void 0) diffs.push({ path: path9, delta: tokens, added: true });
+    else if (tokens !== prev) diffs.push({ path: path9, delta: tokens - prev, added: false });
+  }
+  for (const [path9, tokens] of previous) {
+    if (!current.has(path9)) diffs.push({ path: path9, delta: -tokens, added: false });
+  }
+  return diffs.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta)).slice(0, 3).map(({ path: path9, delta, added }) => {
+    const sign = delta >= 0 ? "+" : "\u2212";
+    const amount = `${sign}${Math.abs(delta).toLocaleString()} tokens`;
+    if (added) return `Added ${path9} (${amount})`;
+    if (delta < 0 && !added) return `${path9} (${amount})`;
+    return `${path9} grew (${amount})`;
+  });
+}
+
+// src/costModel.ts
+function cacheEffectiveMultiplier(write, read, requestsPerSession) {
+  const n = Math.max(1, requestsPerSession);
+  return (write + read * (n - 1)) / n;
+}
+function cacheFormulaDescription(cfg) {
+  const n = cfg.cache.requestsPerSession;
+  return `cached cost/request = baseline_tokens x input_price x (write + read x (n-1)) / n, with n = ${n} requests/session (anthropic: write 1.25x, read 0.1x, 5-min TTL)`;
+}
+function computeCosts(baselineTokensByProvider, cfg) {
+  return resolveModels(cfg).map((model) => {
+    const tokens = baselineTokensByProvider[model.provider] ?? null;
+    if (tokens === null || model.inputPerMTok === null) {
+      return {
+        model: model.id,
+        provider: model.provider,
+        perRequestUncached: null,
+        perRequestCached: null,
+        daily: cfg.requestsPerDay.map((r) => ({
+          requestsPerDay: r,
+          uncached: null,
+          cached: null
+        })),
+        runwayDays: null
+      };
+    }
+    const perRequestUncached = tokens / 1e6 * model.inputPerMTok;
+    const provider = resolveProvider(model.provider, cfg);
+    let perRequestCached = null;
+    if (cfg.cache.enabled && provider.cache) {
+      const mult = cacheEffectiveMultiplier(
+        provider.cache.write,
+        provider.cache.read,
+        cfg.cache.requestsPerSession
+      );
+      perRequestCached = perRequestUncached * mult;
+    }
+    const daily = cfg.requestsPerDay.map((requestsPerDay) => ({
+      requestsPerDay,
+      uncached: perRequestUncached * requestsPerDay,
+      cached: perRequestCached === null ? null : perRequestCached * requestsPerDay
+    }));
+    let runwayDays = null;
+    if (cfg.monthlyBudget !== null && cfg.requestsPerDay.length > 0) {
+      const sorted = [...cfg.requestsPerDay].sort((a, b) => a - b);
+      const midRate = sorted[Math.floor(sorted.length / 2)];
+      const perDay = (perRequestCached ?? perRequestUncached) * midRate * cfg.developers;
+      if (perDay > 0) runwayDays = cfg.monthlyBudget / perDay;
+    }
+    return {
+      model: model.id,
+      provider: model.provider,
+      perRequestUncached,
+      perRequestCached,
+      daily,
+      runwayDays
+    };
+  });
+}
+
+// src/scan.ts
+var TOOL_NAME = "ai-cost-audit";
+var TOOL_VERSION = "0.1.0";
+async function runScan(projectPath, cfg, snapshot) {
+  const sources = await discoverAll(projectPath, cfg);
+  const repoGuaranteed = sources.filter((s) => s.scope === "repo" && s.usage === "guaranteed");
+  const globalGuaranteed = sources.filter(
+    (s) => s.scope === "global" && s.usage === "guaranteed"
+  );
+  const conditional = sources.filter((s) => s.usage === "conditional");
+  const sum = (list) => list.reduce((total, s) => total + s.tokens, 0);
+  const gatedBaseline = sum(repoGuaranteed);
+  const globalBaseline = sum(globalGuaranteed);
+  const guaranteed = gatedBaseline + globalBaseline;
+  const byKind = {};
+  const byAdapter = {};
+  for (const s of sources) {
+    byKind[s.kind] = (byKind[s.kind] ?? 0) + s.tokens;
+    byAdapter[s.adapter] = (byAdapter[s.adapter] ?? 0) + s.tokens;
+  }
+  const anthropicCalibration = resolveProvider("anthropic", cfg).calibration;
+  const rawBaseline = guaranteed / anthropicCalibration;
+  const baselineByProvider = {};
+  for (const provider of cfg.providers) {
+    baselineByProvider[provider] = Math.round(
+      rawBaseline * resolveProvider(provider, cfg).calibration
+    );
+  }
+  const duplicates = findDuplicates(sources, cfg);
+  const findings = deriveFindings(sources, duplicates, gatedBaseline, snapshot, cfg);
+  const costs = computeCosts(baselineByProvider, cfg);
+  const requestRange = {
+    min: guaranteed + cfg.variable.conversationHistory[0] + cfg.variable.taskFiles[0],
+    max: guaranteed + cfg.variable.conversationHistory[1] + cfg.variable.taskFiles[1]
+  };
+  const calibration = {};
+  for (const provider of cfg.providers) {
+    calibration[provider] = resolveProvider(provider, cfg).calibration;
+  }
+  const report = {
+    meta: {
+      tool: TOOL_NAME,
+      version: TOOL_VERSION,
+      scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectPath: path6.resolve(projectPath),
+      pricingAsOf: PRICING_AS_OF,
+      pricingStale: isPricingStale(),
+      calibration,
+      cacheFormula: cacheFormulaDescription(cfg),
+      disclosure: DISCLOSURE
+    },
+    totals: {
+      gatedBaseline,
+      globalBaseline,
+      guaranteed,
+      conditional: sum(conditional),
+      byKind,
+      byAdapter
+    },
+    sources: sources.map(({ text: _text, ...rest }) => rest),
+    costs,
+    requestRange,
+    findings
+  };
+  return { report, sources };
+}
+
+// src/report/markdown.ts
+var KIND_LABELS = {
+  "repo-instructions": "Repository instructions",
+  "local-instructions": "Local instructions",
+  "global-instructions": "Global instructions (user)",
+  agent: "Agent definitions",
+  "skill-description": "Skill descriptions (always loaded)",
+  "skill-body": "Skill bodies (on demand)",
+  command: "Slash commands",
+  "mcp-config": "MCP configuration",
+  "cursor-rules": "Cursor rules",
+  "copilot-instructions": "Copilot instructions",
+  "referenced-doc": "Referenced documentation"
+};
+function formatUSD(value) {
+  if (value === null) return "\u2014";
+  if (value === 0) return "$0.00";
+  if (value < 0.01) return `$${value.toFixed(4)}`;
+  return `$${value.toFixed(2)}`;
+}
+function num(n) {
+  return n.toLocaleString("en-US");
+}
+function renderMarkdown(report, cfg) {
+  const lines = [];
+  const { totals, costs, findings, meta } = report;
+  lines.push(`# AI Context Cost Audit`);
+  lines.push("");
+  lines.push(`Scanned \`${meta.projectPath}\` at ${meta.scannedAt}`);
+  lines.push("");
+  lines.push(`## Guaranteed Context (loaded on every request)`);
+  lines.push("");
+  lines.push(`| Source kind | Tokens |`);
+  lines.push(`|---|---:|`);
+  const guaranteedSources = report.sources.filter((s) => s.usage === "guaranteed");
+  const kindTotals = /* @__PURE__ */ new Map();
+  for (const s of guaranteedSources) {
+    kindTotals.set(s.kind, (kindTotals.get(s.kind) ?? 0) + s.tokens);
+  }
+  for (const [kind, tokens] of [...kindTotals.entries()].sort((a, b) => b[1] - a[1])) {
+    lines.push(`| ${KIND_LABELS[kind] ?? kind} | ${num(tokens)} |`);
+  }
+  lines.push(`| **Repo baseline (CI-gated)** | **${num(totals.gatedBaseline)}** |`);
+  if (totals.globalBaseline > 0) {
+    lines.push(
+      `| Global user files (not counted toward CI budget) | ${num(totals.globalBaseline)} |`
+    );
+  }
+  lines.push(`| **Total baseline** | **${num(totals.guaranteed)}** |`);
+  lines.push("");
+  if (totals.conditional > 0) {
+    lines.push(
+      `Conditional context (loads for some tasks): ${num(totals.conditional)} tokens across ${report.sources.filter((s) => s.usage === "conditional").length} sources.`
+    );
+    lines.push("");
+  }
+  lines.push(`## Estimated cost per request (baseline input only)`);
+  lines.push("");
+  lines.push(`| Model | Uncached | With caching (typical) |`);
+  lines.push(`|---|---:|---:|`);
+  for (const c of costs) {
+    lines.push(
+      `| ${c.model} | ${formatUSD(c.perRequestUncached)} | ${formatUSD(c.perRequestCached)} |`
+    );
+  }
+  lines.push("");
+  lines.push(
+    `Cost figures use the full guaranteed baseline (repo + global). "With caching" models prompt caching: ${meta.cacheFormula}.`
+  );
+  lines.push("");
+  lines.push(`## Daily usage projections`);
+  lines.push("");
+  for (const c of costs) {
+    if (c.perRequestUncached === null) {
+      lines.push(`- ${c.model}: pricing not set (see config.pricingOverrides)`);
+      continue;
+    }
+    lines.push(`**${c.model}**`);
+    lines.push("");
+    lines.push(`| Requests/day | Uncached | With caching |`);
+    lines.push(`|---:|---:|---:|`);
+    for (const d of c.daily) {
+      lines.push(
+        `| ${num(d.requestsPerDay)} | ${formatUSD(d.uncached)}/day | ${formatUSD(d.cached)}/day |`
+      );
+    }
+    lines.push("");
+    if (c.runwayDays !== null && cfg.monthlyBudget !== null) {
+      const sorted = [...cfg.requestsPerDay].sort((a, b) => a - b);
+      const midRate = sorted[Math.floor(sorted.length / 2)];
+      lines.push(
+        `At ${num(midRate)} requests/day per developer` + (cfg.developers > 1 ? ` (${cfg.developers} developers)` : "") + `, your $${cfg.monthlyBudget}/month budget lasts ~${c.runwayDays.toFixed(1)} days.`
+      );
+      lines.push("");
+    }
+  }
+  lines.push(`## Typical full-request range`);
+  lines.push("");
+  lines.push(
+    `Baseline plus variable context (conversation history ${num(cfg.variable.conversationHistory[0])}\u2013${num(cfg.variable.conversationHistory[1])}, task files ${num(cfg.variable.taskFiles[0])}\u2013${num(cfg.variable.taskFiles[1])} tokens):`
+  );
+  lines.push("");
+  lines.push(
+    `**Estimated request range: ${num(report.requestRange.min)}\u2013${num(report.requestRange.max)} input tokens.**`
+  );
+  lines.push("");
+  lines.push(
+    `Variable context cannot be predicted exactly; these are configurable ranges, not measurements.`
+  );
+  lines.push("");
+  lines.push(`## High-impact findings`);
+  lines.push("");
+  if (findings.length === 0) {
+    lines.push(`No findings. Baseline looks lean.`);
+  } else {
+    for (const [i, f] of findings.entries()) {
+      lines.push(`${i + 1}. **[${f.severity}] ${f.rule}** \u2014 ${f.message}`);
+    }
+  }
+  lines.push("");
+  lines.push(`## All discovered sources`);
+  lines.push("");
+  lines.push(`| Path | Kind | Usage | Scope | Tokens | Confidence |`);
+  lines.push(`|---|---|---|---|---:|---|`);
+  for (const s of [...report.sources].sort((a, b) => b.tokens - a.tokens)) {
+    lines.push(
+      `| ${s.path} | ${s.kind} | ${s.usage} | ${s.scope} | ${num(s.tokens)} | ${s.confidence} |`
+    );
+  }
+  lines.push("");
+  const noted = report.sources.filter((s) => s.note);
+  if (noted.length > 0) {
+    lines.push(`Notes:`);
+    for (const s of noted) {
+      lines.push(`- \`${s.path}\`: ${s.note}`);
+    }
+    lines.push("");
+  }
+  lines.push(`---`);
+  lines.push("");
+  lines.push(`*${meta.disclosure}*`);
+  lines.push("");
+  lines.push(
+    `*Calibration factors (applied to o200k_base counts): ${Object.entries(meta.calibration).map(([provider, factor]) => `${provider} \xD7${factor}`).join(", ")}. Pricing as of ${meta.pricingAsOf}` + (meta.pricingStale ? ` \u2014 **stale (>90 days old)**: verify current pricing and override via config.pricingOverrides` : "") + `.*`
+  );
+  lines.push("");
+  lines.push(`*Generated by ${meta.tool} v${meta.version}.*`);
+  return lines.join("\n");
+}
+
+// src/report/json.ts
+function renderJson(report) {
+  return JSON.stringify(report, null, 2) + "\n";
+}
+
+// src/report/html.ts
+function esc(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function num2(n) {
+  return n.toLocaleString("en-US");
+}
+function renderHtml(report, cfg) {
+  const { totals, costs, findings, meta } = report;
+  const severityColor = {
+    error: "#c0392b",
+    warn: "#b7791f",
+    info: "#2b6cb0"
+  };
+  const kindRows = (() => {
+    const kindTotals = /* @__PURE__ */ new Map();
+    for (const s of report.sources.filter((x) => x.usage === "guaranteed")) {
+      kindTotals.set(s.kind, (kindTotals.get(s.kind) ?? 0) + s.tokens);
+    }
+    return [...kindTotals.entries()].sort((a, b) => b[1] - a[1]).map(([kind, tokens]) => `<tr><td>${esc(kind)}</td><td class="r">${num2(tokens)}</td></tr>`).join("\n");
+  })();
+  const costRows = costs.map(
+    (c) => `<tr><td>${esc(c.model)}</td><td class="r">${formatUSD(c.perRequestUncached)}</td><td class="r">${formatUSD(c.perRequestCached)}</td></tr>`
+  ).join("\n");
+  const findingItems = findings.length === 0 ? `<li>No findings. Baseline looks lean.</li>` : findings.map(
+    (f) => `<li><span class="sev" style="background:${severityColor[f.severity]}">${f.severity}</span> <code>${esc(f.rule)}</code> \u2014 ${esc(f.message)}</li>`
+  ).join("\n");
+  const sourceRows = [...report.sources].sort((a, b) => b.tokens - a.tokens).map(
+    (s) => `<tr><td><code>${esc(s.path)}</code></td><td>${esc(s.kind)}</td><td>${esc(s.usage)}</td><td>${esc(s.scope)}</td><td class="r">${num2(s.tokens)}</td><td>${esc(s.confidence)}</td></tr>`
+  ).join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>AI Context Cost Audit</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 900px; margin: 2rem auto; padding: 0 1rem; }
+  h1 { font-size: 1.6rem; } h2 { font-size: 1.2rem; margin-top: 2rem; }
+  table { border-collapse: collapse; width: 100%; margin: .75rem 0; }
+  th, td { text-align: left; padding: .35rem .6rem; border-bottom: 1px solid rgba(128,128,128,.3); }
+  td.r, th.r { text-align: right; font-variant-numeric: tabular-nums; }
+  tr.total td { font-weight: 700; border-top: 2px solid rgba(128,128,128,.5); }
+  code { font: 13px ui-monospace, Menlo, monospace; }
+  .sev { color: #fff; font-size: 11px; padding: 1px 6px; border-radius: 3px; text-transform: uppercase; }
+  .muted { opacity: .7; font-size: 13px; }
+  li { margin: .4rem 0; }
+  .big { font-size: 1.1rem; font-weight: 600; }
+</style>
+</head>
+<body>
+<h1>AI Context Cost Audit</h1>
+<p class="muted">Scanned <code>${esc(meta.projectPath)}</code> at ${esc(meta.scannedAt)}</p>
+
+<h2>Guaranteed context (loaded on every request)</h2>
+<table>
+<tr><th>Source kind</th><th class="r">Tokens</th></tr>
+${kindRows}
+<tr class="total"><td>Repo baseline (CI-gated)</td><td class="r">${num2(totals.gatedBaseline)}</td></tr>
+${totals.globalBaseline > 0 ? `<tr><td>Global user files (not gated)</td><td class="r">${num2(totals.globalBaseline)}</td></tr>` : ""}
+<tr class="total"><td>Total baseline</td><td class="r">${num2(totals.guaranteed)}</td></tr>
+</table>
+
+<h2>Estimated cost per request (baseline input only)</h2>
+<table>
+<tr><th>Model</th><th class="r">Uncached</th><th class="r">With caching (typical)</th></tr>
+${costRows}
+</table>
+<p class="muted">${esc(meta.cacheFormula)}</p>
+
+<h2>Typical full-request range</h2>
+<p class="big">${num2(report.requestRange.min)}&ndash;${num2(report.requestRange.max)} input tokens</p>
+<p class="muted">Baseline + conversation history (${num2(cfg.variable.conversationHistory[0])}&ndash;${num2(cfg.variable.conversationHistory[1])}) + task files (${num2(cfg.variable.taskFiles[0])}&ndash;${num2(cfg.variable.taskFiles[1])}). Ranges, not measurements.</p>
+
+<h2>High-impact findings</h2>
+<ol>
+${findingItems}
+</ol>
+
+<h2>All discovered sources</h2>
+<table>
+<tr><th>Path</th><th>Kind</th><th>Usage</th><th>Scope</th><th class="r">Tokens</th><th>Confidence</th></tr>
+${sourceRows}
+</table>
+
+<hr>
+<p class="muted">${esc(meta.disclosure)}</p>
+<p class="muted">Calibration: ${esc(
+    Object.entries(meta.calibration).map(([provider, factor]) => `${provider} \xD7${factor}`).join(", ")
+  )}. Pricing as of ${esc(meta.pricingAsOf)}${meta.pricingStale ? " \u2014 <strong>stale, verify and override via config</strong>" : ""}.</p>
+<p class="muted">Generated by ${esc(meta.tool)} v${esc(meta.version)}.</p>
+</body>
+</html>
+`;
+}
+
+// src/snapshot.ts
+import { mkdir, readFile as readFile6, writeFile } from "fs/promises";
+import { existsSync as existsSync5 } from "fs";
+import path7 from "path";
+var SNAPSHOT_DIR = ".ai-cost-audit";
+var SNAPSHOT_FILE = "snapshot.json";
+function snapshotPath(projectPath) {
+  return path7.join(projectPath, SNAPSHOT_DIR, SNAPSHOT_FILE);
+}
+async function readSnapshot(projectPath) {
+  const file = snapshotPath(projectPath);
+  if (!existsSync5(file)) return null;
+  try {
+    const parsed = JSON.parse(await readFile6(file, "utf8"));
+    if (parsed.version !== 1 || !Array.isArray(parsed.sources)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function writeSnapshot(projectPath, sources, gatedBaseline) {
+  const snapshot = {
+    version: 1,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    gatedBaseline,
+    // Per-source tokens (repo-scoped guaranteed only) so growth attribution works.
+    sources: sources.filter((s) => s.scope === "repo" && s.usage === "guaranteed").map((s) => ({ path: s.path, tokens: s.tokens })).sort((a, b) => a.path.localeCompare(b.path))
+  };
+  const file = snapshotPath(projectPath);
+  await mkdir(path7.dirname(file), { recursive: true });
+  await writeFile(file, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+  return file;
+}
+
+// src/budget.ts
+var EXIT_PASS = 0;
+var EXIT_VIOLATION = 1;
+var EXIT_ERROR = 2;
+function evaluateBudget(gatedBaseline, sources, snapshot, cfg) {
+  const messages = [];
+  let pass = true;
+  if (cfg.baselineTokenLimit !== null && gatedBaseline > cfg.baselineTokenLimit) {
+    pass = false;
+    messages.push(
+      `AI context budget failed: baseline ${gatedBaseline.toLocaleString()} tokens exceeds limit ${cfg.baselineTokenLimit.toLocaleString()}.`
+    );
+  }
+  if (snapshot && snapshot.gatedBaseline > 0) {
+    const growthPct = (gatedBaseline - snapshot.gatedBaseline) / snapshot.gatedBaseline * 100;
+    if (growthPct > cfg.growthThresholdPct) {
+      pass = false;
+      const causes = topGrowthCauses(sources, snapshot);
+      messages.push(
+        `AI context budget failed: baseline grew ${growthPct.toFixed(0)}% (threshold ${cfg.growthThresholdPct}%).
+  Previous: ${snapshot.gatedBaseline.toLocaleString()} tokens
+  Current:  ${gatedBaseline.toLocaleString()} tokens
+  Change:   ${growthPct >= 0 ? "+" : ""}${growthPct.toFixed(0)}%` + (causes.length > 0 ? `
+  Primary cause: ${causes.join("; ")}` : "")
+      );
+    } else {
+      messages.push(
+        `Baseline vs snapshot: ${snapshot.gatedBaseline.toLocaleString()} \u2192 ${gatedBaseline.toLocaleString()} tokens (${growthPct >= 0 ? "+" : ""}${growthPct.toFixed(1)}%, within ${cfg.growthThresholdPct}% threshold).`
+      );
+    }
+  } else if (!snapshot) {
+    messages.push(
+      `No snapshot found (${cfg.growthThresholdPct}% growth check skipped). Run \`ai-cost-audit scan --update-snapshot\` and commit .ai-cost-audit/snapshot.json.`
+    );
+  }
+  if (pass && cfg.baselineTokenLimit !== null) {
+    messages.push(
+      `Baseline ${gatedBaseline.toLocaleString()} tokens within limit ${cfg.baselineTokenLimit.toLocaleString()}.`
+    );
+  }
+  return { pass, messages };
+}
+
+// src/cli.ts
+var program = new Command();
+program.name(TOOL_NAME).description(
+  "AI context cost profiler and linter \u2014 know what every AI coding request costs before it's sent"
+).version(TOOL_VERSION);
+program.command("scan").description("Scan a repository for AI context sources and report baseline cost").argument("[path]", "project path to scan", ".").option("-c, --config <file>", "path to config file (default: ./ai-cost-audit.json)").option("-f, --format <format>", "output format: md | json | html", "md").option("-o, --out <file>", "write the report to a file instead of stdout").option("--ci", "run the budget gate: exit 1 on limit breach or growth over threshold").option("--update-snapshot", "write .ai-cost-audit/snapshot.json (commit it for CI diffs)").option("--no-global", "skip user-global files (~/.claude)").option("--ref-depth <n>", "how many levels of @imports / links to follow", parseIntArg).action(async (projectPath, options) => {
+  try {
+    const resolved = path8.resolve(projectPath);
+    const { config, configPath } = await loadConfig(resolved, options.config);
+    if (options.global === false) config.includeGlobal = false;
+    if (options.refDepth !== void 0) config.refDepth = options.refDepth;
+    const snapshot = await readSnapshot(resolved);
+    const { report, sources } = await runScan(resolved, config, snapshot);
+    const format = String(options.format).toLowerCase();
+    let output;
+    if (format === "json") output = renderJson(report);
+    else if (format === "html") output = renderHtml(report, config);
+    else if (format === "md") output = renderMarkdown(report, config);
+    else {
+      process.stderr.write(pc.red(`Unknown format: ${options.format} (use md, json, or html)
+`));
+      process.exit(EXIT_ERROR);
+      return;
+    }
+    if (options.out) {
+      const outPath = path8.resolve(options.out);
+      await writeFile2(outPath, output, "utf8");
+      process.stderr.write(pc.green(`Report written to ${outPath}
+`));
+    } else {
+      process.stdout.write(format === "md" ? colorize(output) : output);
+    }
+    if (configPath === null) {
+      process.stderr.write(
+        pc.dim(`(no ai-cost-audit.json found \u2014 ran with defaults)
+`)
+      );
+    }
+    if (options.updateSnapshot) {
+      const file = await writeSnapshot(resolved, sources, report.totals.gatedBaseline);
+      process.stderr.write(pc.green(`Snapshot written to ${file} \u2014 commit it for CI diffs.
+`));
+    }
+    if (options.ci) {
+      const gate = evaluateBudget(report.totals.gatedBaseline, sources, snapshot, config);
+      for (const message of gate.messages) {
+        process.stderr.write(
+          (gate.pass ? pc.green(message) : pc.red(message)) + "\n"
+        );
+      }
+      process.exit(gate.pass ? EXIT_PASS : EXIT_VIOLATION);
+    }
+  } catch (err) {
+    process.stderr.write(
+      pc.red(`Error: ${err instanceof Error ? err.message : String(err)}
+`)
+    );
+    process.exit(EXIT_ERROR);
+  }
+});
+function parseIntArg(value) {
+  const n = Number.parseInt(value, 10);
+  if (Number.isNaN(n) || n < 0) throw new Error(`Invalid number: ${value}`);
+  return n;
+}
+function colorize(markdown) {
+  return markdown.split("\n").map((line) => {
+    if (line.startsWith("# ")) return pc.bold(pc.cyan(line));
+    if (line.startsWith("## ")) return pc.bold(line);
+    if (/^\d+\. \*\*\[error\]/.test(line)) return pc.red(line);
+    if (/^\d+\. \*\*\[warn\]/.test(line)) return pc.yellow(line);
+    if (/^\d+\. \*\*\[info\]/.test(line)) return pc.blue(line);
+    if (line.startsWith("*") && line.endsWith("*")) return pc.dim(line);
+    return line;
+  }).join("\n");
+}
+program.parseAsync(process.argv);