costlayers 0.8.17 → 0.8.27

package/README.md

@@ -1,23 +1,23 @@
 # CostLayers CLI
 
-CostLayers helps coding-agent users stop paying for repeated repo context. API users can route model calls through the gateway for invoice savings. ChatGPT-login Codex users get a usage-stretch meter that shows how much repeated context was avoided.
+CostLayers is an AI spend control layer for coding-agent teams. It starts with a free audit, finds repeated context waste, gives API users invoice-mode savings, and gives ChatGPT-login Codex users a usage-stretch meter that shows how much repeated context was avoided.
 
 ## Quick Start
 
-Daily Codex use:
+Run a free AI spend audit:
 
 ```bash
 cd your-repo
-npx -y costlayers@latest codex --email you@example.com --chatgpt
+npx -y https://costlayers.com/costlayers-0.8.27.tgz audit --monthly-spend 10000
 ```
 
-This default path preserves Codex's native ChatGPT-login/provider flow and shows a usage-stretch meter. CostLayers only routes billable API traffic when you explicitly pass `--api`.
+Use your real monthly AI spend if you have it. Omit `--monthly-spend` to get a repo-only audit. The audit writes `.agentspend/ai-spend-audit.md` and labels scan estimates separately from verified invoice savings. After the audit, `costlayers dashboard` shows the local result even before signup.
 
 Run a one-command API savings test:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-...
-npx -y costlayers@latest test --email you@example.com
+npx -y https://costlayers.com/costlayers-0.8.27.tgz test --email you@example.com
 ```
 
 ## Usage
@@ -25,7 +25,13 @@ npx -y costlayers@latest test --email you@example.com
 Inside a repo:
 
 ```bash
-npx -y costlayers@latest codex --email you@example.com --chatgpt
+npx -y https://costlayers.com/costlayers-0.8.27.tgz audit --monthly-spend 10000
+```
+
+Then run Codex with CostLayers:
+
+```bash
+npx -y https://costlayers.com/costlayers-0.8.27.tgz codex --email you@example.com --chatgpt
 ```
 
 This gives Codex `.agentspend/repo-pack.md` and `.agentspend/runtime-plan.md`
@@ -45,7 +51,7 @@ API write permission:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-...
-npx -y costlayers@latest codex --email you@example.com --api
+npx -y https://costlayers.com/costlayers-0.8.27.tgz codex --email you@example.com --api
 ```
 
 ChatGPT-login Codex can be metered, but it does not create per-request OpenAI
@@ -56,12 +62,13 @@ Platform invoice savings because it is not billed through your Platform API key.
 - ChatGPT-login Codex: use `costlayers codex --email you@example.com --chatgpt` to reduce repeated repo context and stretch usage limits.
 - OpenAI Platform API billing: set `OPENAI_API_KEY`, then use `costlayers codex --email you@example.com --api` for invoice-backed savings.
 - Savings proof: set `OPENAI_API_KEY`, then run `costlayers test --email you@example.com`.
+- Free audit: run `costlayers audit --monthly-spend <usd>` before changing a workflow.
 - Other OpenAI-compatible clients: point the client at the CostLayers gateway URL and check `costlayers gateway report`.
 
 To install only the Codex profile after signup:
 
 ```bash
-npx -y costlayers@latest codex-profile
+npx -y https://costlayers.com/costlayers-0.8.27.tgz codex-profile
 codex --profile costlayers
 ```
 
@@ -88,9 +95,13 @@ The hosted reducer defaults to quality-safe reduction:
 - certified compaction preserves the current user request
 - prior context is compacted only when there is a safe structural boundary
 - opaque single-message prompts are forwarded unchanged
+- hosted raw provider-response caching is off by default; receipts use hashes,
+  token counts, costs, timestamps, and quality labels
 
 Output:
 
+- `.agentspend/ai-spend-audit.md`
+- `.agentspend/ai-spend-audit.json`
 - `.agentspend/repo-pack.md`
 - `.agentspend/savings-report.md`
 - `.agentspend/savings-report.json`
@@ -118,4 +129,12 @@ No private internals are included in this package.
 
 ## Closed Engine
 
-The npm package is a controller. The stronger reduction engine and cost gateway run separately and are not shipped in the public package.
+The npm package is a controller for the CostLayers optimization layer. The stronger reduction engine and cost gateway run separately and are not shipped in the public package.
+
+## Privacy Default
+
+The CLI scans source locally. When connected, it sends savings reports, artifact
+hashes, and usage metadata so the dashboard can show found waste and metered
+savings. It does not send the repo-pack preview by default. ChatGPT-login Codex
+mode does not route model calls through CostLayers. API invoice mode routes
+requests through the hosted optimization layer only when you pass `--api`.

package/bin/agentspend.js

@@ -9,8 +9,16 @@ const https = require("https");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
-const VERSION = "0.8.17";
-const INSTALL_SPEC = "costlayers@latest";
+function packageVersion() {
+  try {
+    return require(path.join(__dirname, "..", "package.json")).version || "0.8.27";
+  } catch (_err) {
+    return "0.8.27";
+  }
+}
+
+const VERSION = packageVersion();
+const INSTALL_SPEC = process.env.COSTLAYERS_INSTALL_SPEC || `https://costlayers.com/costlayers-${VERSION}.tgz`;
 const DEFAULT_RUNS_PER_WEEK = 20;
 const WEEKS_PER_MONTH = 4.33;
 const DEFAULT_EXCLUDES = new Set([
@@ -45,11 +53,14 @@ const SOURCE_EXTENSIONS = new Set([
   ".md", ".mdx", ".json", ".yaml", ".yml", ".toml", ".sql"
 ]);
 
+const SEMANTIC_SLICE_LIMIT_PER_AREA = 24;
+
 function usage(exitCode = 0) {
   const text = `
 CostLayers ${VERSION}
 
 Usage:
+  costlayers audit [--email <email>] [--monthly-spend <usd>] [--usage-file <path>]
   costlayers codex [--email <email>] [--chatgpt|--api] [-- <codex args>]
   costlayers test [--email <email>] [--prompt <text>]
   costlayers init [--repo <path>]
@@ -66,6 +77,7 @@ Usage:
   costlayers doctor
 
 Commands:
+  audit   Run a free AI spend audit: repo context waste plus optional monthly spend/imported usage.
   codex   Start Codex with CostLayers. Defaults to ChatGPT-login mode unless --api is passed.
   test    Run a safe read-only API invoice-mode Codex task and print the CostLayers savings report.
   init    Create .agentspend config and agent instructions.
@@ -185,10 +197,10 @@ function repoConnectionPath(repo) {
   return path.join(repo, ".agentspend", "connection.json");
 }
 
-function ensureAgentSpendGitignore(outDir) {
+function ensureCostLayersGitignore(outDir) {
   ensureDir(outDir);
   const file = path.join(outDir, ".gitignore");
-  const required = ["connection.json", "*.secret.json", "gateway-key.txt"];
+  const required = ["connection.json", "*.secret.json", "gateway-key.txt", "local-cache.json"];
   let current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
   const lines = new Set(current.split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
   let changed = false;
@@ -229,7 +241,7 @@ function writePrivateJson(file, payload) {
 function saveConnection(repo, connection) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
-  ensureAgentSpendGitignore(outDir);
+  ensureCostLayersGitignore(outDir);
   const connectionId = connectionIdFor(repo, connection);
   const full = {
     ...connection,
@@ -260,6 +272,12 @@ function estimateTokens(text) {
   return Math.ceil(String(text || "").length / 4);
 }
 
+function stableJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stableJson(item)).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+}
+
 function walkFiles(root) {
   const out = [];
   function walk(dir) {
@@ -383,6 +401,7 @@ function buildRepoPack(repo, summary) {
   parts.push("");
   parts.push("## Agent Operating Rule");
   parts.push("- Start with this pack before reading many files.");
+  parts.push("- Use .agentspend/semantic-slices.md for route and symbol facts before opening broad source context.");
   parts.push("- Prefer targeted reads of files listed above.");
   parts.push("- If a file hash is unchanged, do not reread it unless the task requires exact code.");
   parts.push("- Update this pack after major repo changes with `costlayers scan`.");
@@ -390,15 +409,194 @@ function buildRepoPack(repo, summary) {
   return parts.join("\n");
 }
 
+
+function semanticArea(row) {
+  const rel = String(row.rel || "").toLowerCase();
+  const signals = row.signals || {};
+  if ((signals.routeHints || []).length > 0) return "entrypoints-routes";
+  if (/(^|\/)(__tests__|test|tests|spec|specs)(\/|$)/.test(rel) || /\.(test|spec)\.[^.]+$/.test(rel)) return "tests";
+  if (/(^|\/)(package\.json|pyproject\.toml|cargo\.toml|go\.mod|requirements[^/]*\.txt|pom\.xml|build\.gradle|dockerfile|compose\.ya?ml|tsconfig\.json|vite\.config|next\.config|nuxt\.config)/.test(rel)) return "config-build";
+  if (/\.(md|mdx)$/.test(rel)) return "docs";
+  if (/(^|\/)(schema|schemas|model|models|migration|migrations|db|database)(\/|$)/.test(rel) || /\.sql$/.test(rel)) return "data-model";
+  if (/(^|\/)(api|server|service|services|controller|controllers|handler|handlers)(\/|$)/.test(rel)) return "services";
+  if (/(^|\/)(component|components|page|pages|app|ui|view|views)(\/|$)/.test(rel)) return "ui";
+  if (/(^|\/)(cli|bin|cmd|command|commands)(\/|$)/.test(rel)) return "cli-tools";
+  return "core";
+}
+
+function semanticAreaTitle(area) {
+  return ({
+    "entrypoints-routes": "Entry Points And Routes",
+    "config-build": "Config And Build",
+    "data-model": "Data Model",
+    "cli-tools": "CLI And Tools",
+    services: "Services",
+    tests: "Tests",
+    docs: "Docs",
+    ui: "UI",
+    core: "Core"
+  })[area] || area;
+}
+
+function semanticSymbolName(definitionLine) {
+  const text = String(definitionLine || "").replace(/^\d+:\s*/, "").trim();
+  const patterns = [
+    /(?:export\s+)?(?:async\s+)?(?:function|class|interface|type|const|let|var)\s+([A-Za-z0-9_$]+)/,
+    /(?:def|class)\s+([A-Za-z0-9_]+)/,
+    /func\s+(?:\([^)]+\)\s*)?([A-Za-z0-9_]+)/
+  ];
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match) return match[1];
+  }
+  return text.slice(0, 80);
+}
+
+function semanticFileFact(row) {
+  const signals = row.signals || {};
+  const symbols = (signals.defs || []).map(semanticSymbolName).filter(Boolean).slice(0, 12);
+  const routes = (signals.routeHints || []).slice(0, 8);
+  const imports = (signals.imports || []).slice(0, 6);
+  return {
+    path: row.rel,
+    area: semanticArea(row),
+    hash: row.hash,
+    tokens: row.tokens,
+    lines: signals.lineCount || 0,
+    symbols,
+    routes,
+    imports
+  };
+}
+
+function semanticFactCount(fact) {
+  return 1 + fact.symbols.length + fact.routes.length + Math.min(fact.imports.length, 3);
+}
+
+function semanticFactScore(fact) {
+  return fact.routes.length * 50 + fact.symbols.length * 8 + fact.imports.length * 2 + Math.min(fact.tokens / 1000, 20);
+}
+
+function buildSemanticSlices(repo, summary) {
+  const facts = summary.files.map(semanticFileFact);
+  const groups = new Map();
+  for (const fact of facts) {
+    if (!groups.has(fact.area)) groups.set(fact.area, []);
+    groups.get(fact.area).push(fact);
+  }
+  const slices = Array.from(groups.entries()).map(([area, files]) => {
+    const sorted = files.slice().sort((a, b) => semanticFactScore(b) - semanticFactScore(a) || b.tokens - a.tokens || a.path.localeCompare(b.path));
+    const included = sorted.slice(0, SEMANTIC_SLICE_LIMIT_PER_AREA);
+    const sourceTokens = files.reduce((acc, item) => acc + Number(item.tokens || 0), 0);
+    const factCount = files.reduce((acc, item) => acc + semanticFactCount(item), 0);
+    const sliceSeed = {
+      area,
+      files: files.map((item) => ({ path: item.path, hash: item.hash, tokens: item.tokens })).sort((a, b) => a.path.localeCompare(b.path))
+    };
+    return {
+      id: `sem_${sha256(stableJson(sliceSeed)).slice(0, 12)}`,
+      area,
+      title: semanticAreaTitle(area),
+      file_count: files.length,
+      included_file_count: included.length,
+      omitted_file_count: Math.max(0, files.length - included.length),
+      source_tokens_covered: sourceTokens,
+      fact_count: factCount,
+      files: included
+    };
+  }).sort((a, b) => b.source_tokens_covered - a.source_tokens_covered || a.title.localeCompare(b.title));
+  const receiptSeed = {
+    artifact_version: 1,
+    mode: "offline-semantic-slices",
+    repo: path.basename(repo),
+    files_indexed: summary.files.length,
+    source_tokens_indexed: summary.totalTokens,
+    slices: slices.map((slice) => ({
+      id: slice.id,
+      area: slice.area,
+      file_count: slice.file_count,
+      source_tokens_covered: slice.source_tokens_covered,
+      fact_count: slice.fact_count
+    }))
+  };
+  return {
+    artifact_version: 1,
+    mode: "offline-semantic-slices",
+    created_utc: new Date().toISOString(),
+    repo: path.basename(repo),
+    files_indexed: summary.files.length,
+    source_tokens_indexed: summary.totalTokens,
+    file_fact_count: facts.length,
+    fact_count: slices.reduce((acc, slice) => acc + slice.fact_count, 0),
+    receipt_sha256: sha256(stableJson(receiptSeed)),
+    slices
+  };
+}
+
+function buildSemanticSlicesMarkdown(index) {
+  const lines = [];
+  lines.push("# CostLayers Semantic Slices");
+  lines.push("");
+  lines.push("Offline semantic facts from local source scanning. This artifact is not used for live gateway request reduction; use it to choose exact files before opening broad context.");
+  lines.push("");
+  lines.push(`Receipt: ${index.receipt_sha256}`);
+  lines.push(`Files indexed: ${index.files_indexed.toLocaleString()}`);
+  lines.push(`Source tokens covered: ${index.source_tokens_indexed.toLocaleString()}`);
+  lines.push(`Slices: ${index.slices.length.toLocaleString()}`);
+  lines.push("");
+  for (const slice of index.slices) {
+    lines.push(`## ${slice.title}`);
+    lines.push(`- Slice id: ${slice.id}`);
+    lines.push(`- Files covered: ${slice.file_count.toLocaleString()}`);
+    lines.push(`- Source tokens covered: ${slice.source_tokens_covered.toLocaleString()}`);
+    if (slice.omitted_file_count > 0) lines.push(`- Additional files in JSON artifact: ${slice.omitted_file_count.toLocaleString()}`);
+    for (const file of slice.files.slice(0, 12)) {
+      lines.push(`- ${file.path} (${Number(file.tokens || 0).toLocaleString()} tokens, ${Number(file.lines || 0).toLocaleString()} lines, hash ${file.hash})`);
+      if (file.routes.length) lines.push(`  - routes: ${file.routes.slice(0, 3).join(" | ")}`);
+      if (file.symbols.length) lines.push(`  - symbols: ${file.symbols.slice(0, 8).join(", ")}`);
+      if (file.imports.length) lines.push(`  - imports: ${file.imports.slice(0, 3).join(" | ")}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function semanticReportSummary(index, semanticMarkdown, baselineBroadReadTokens) {
+  const semanticIndexTokens = estimateTokens(semanticMarkdown);
+  const potentialAvoided = Math.max(0, Number(baselineBroadReadTokens || 0) - semanticIndexTokens);
+  const potentialPct = baselineBroadReadTokens > 0 ? potentialAvoided / baselineBroadReadTokens * 100 : 0;
+  return {
+    mode: "offline_local_only",
+    artifact: ".agentspend/semantic-slices.md",
+    json_artifact: ".agentspend/semantic-slices.json",
+    receipt_hash: index.receipt_sha256,
+    slice_count: index.slices.length,
+    file_fact_count: index.file_fact_count,
+    fact_count: index.fact_count,
+    source_tokens_covered: index.source_tokens_indexed,
+    semantic_index_tokens: semanticIndexTokens,
+    potential_tokens_avoided_per_repeated_task: potentialAvoided,
+    potential_reduction_percent: Number(potentialPct.toFixed(2)),
+    top_slices: index.slices.slice(0, 8).map((slice) => ({
+      id: slice.id,
+      title: slice.title,
+      file_count: slice.file_count,
+      source_tokens_covered: slice.source_tokens_covered,
+      fact_count: slice.fact_count
+    }))
+  };
+}
+
 function buildInstructions() {
   return `# CostLayers Agent Instructions
 
 Before broad repo exploration:
 
 1. Read .agentspend/repo-pack.md.
-2. Use the listed entry points, route hints, and symbol hints to target file reads.
-3. Avoid rereading unchanged large files unless exact code is required.
-4. After major repo changes, ask the user to run \`costlayers scan\`.
+2. Read .agentspend/semantic-slices.md for route and symbol facts when a compact semantic map is enough.
+3. Use the listed entry points, route hints, and symbol hints to target file reads.
+4. Avoid rereading unchanged large files unless exact code is required.
+5. After major repo changes, ask the user to run \`costlayers scan\`.
 
 Goal: reduce repeated context spend while preserving answer quality.
 `;
@@ -412,15 +610,16 @@ This repo uses CostLayers to reduce repeated AI coding-agent context spend.
 Before broad exploration:
 
 1. Read .agentspend/repo-pack.md if it exists.
-2. Read .agentspend/agent-instructions.md.
-3. Prefer targeted file reads based on the repo pack.
-4. Avoid rereading unchanged large files unless exact code is required.
-5. After major repo changes, run or ask for \`costlayers scan\`.
+2. Read .agentspend/semantic-slices.md when route and symbol facts are enough to target the next read.
+3. Read .agentspend/agent-instructions.md.
+4. Prefer targeted file reads based on the repo pack.
+5. Avoid rereading unchanged large files unless exact code is required.
+6. After major repo changes, run or ask for \`costlayers scan\`.
 
 `;
 }
 
-function buildReport(summary, repoPack, tasks, pricePer1m, runsPerWeek) {
+function buildReport(summary, repoPack, tasks, pricePer1m, runsPerWeek, semanticIndex = null, semanticMarkdown = "") {
   const packTokens = estimateTokens(repoPack);
   const broadReadTokens = Math.max(
     summary.totalTokens,
@@ -434,6 +633,7 @@ function buildReport(summary, repoPack, tasks, pricePer1m, runsPerWeek) {
   const projectedWeeklyUsd = savedPerRunUsd * runsPerWeek;
   const projectedMonthlyUsd = projectedWeeklyUsd * WEEKS_PER_MONTH;
   const reductionPct = broadReadTokens > 0 ? avoidedPerTask / broadReadTokens * 100 : 0;
+  const semanticSummary = semanticIndex ? semanticReportSummary(semanticIndex, semanticMarkdown, broadReadTokens) : null;
   return {
     created_utc: new Date().toISOString(),
     files_indexed: summary.files.length,
@@ -453,24 +653,99 @@ function buildReport(summary, repoPack, tasks, pricePer1m, runsPerWeek) {
       path: row.rel,
       tokens: row.tokens,
       hash: row.hash
-    }))
+    })),
+    ...(semanticSummary ? { semantic_slices: semanticSummary } : {})
   };
 }
 
+function summaryFingerprint(summary) {
+  const files = (summary.files || []).map((row) => ({
+    path: row.rel,
+    size: row.size,
+    hash: row.hash,
+    tokens: row.tokens
+  })).sort((a, b) => a.path.localeCompare(b.path));
+  return sha256(stableJson({ artifact_version: 1, files }));
+}
+
+function readLocalCache(outDir) {
+  return readJsonIfExists(path.join(outDir, "local-cache.json"));
+}
+
+function writeLocalCache(outDir, payload) {
+  fs.writeFileSync(path.join(outDir, "local-cache.json"), JSON.stringify(payload, null, 2) + "\n", "utf8");
+}
+
 function scanToFiles(repo, args) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
+  ensureCostLayersGitignore(outDir);
   const tasks = Number(args.tasks || 100);
   const runsPerWeek = Number(args["runs-per-week"] || DEFAULT_RUNS_PER_WEEK);
   const pricePer1m = Number(args["price-per-1m"] || 2.0);
   const summary = summarizeRepo(repo);
+  const fingerprint = summaryFingerprint(summary);
+  const cached = readLocalCache(outDir);
+  if (!args.force && cached && cached.fingerprint === fingerprint) {
+    const packFile = path.join(outDir, "repo-pack.md");
+    const semanticJsonFile = path.join(outDir, "semantic-slices.json");
+    const semanticMdFile = path.join(outDir, "semantic-slices.md");
+    const reportFile = path.join(outDir, "savings-report.json");
+    if (fs.existsSync(packFile) && fs.existsSync(semanticJsonFile) && fs.existsSync(semanticMdFile) && fs.existsSync(reportFile)) {
+      return {
+        outDir,
+        summary,
+        pack: fs.readFileSync(packFile, "utf8"),
+        report: readJsonIfExists(reportFile),
+        semanticIndex: readJsonIfExists(semanticJsonFile),
+        semanticMarkdown: fs.readFileSync(semanticMdFile, "utf8"),
+        localCacheHit: true,
+        fingerprint
+      };
+    }
+  }
+  const semanticIndex = buildSemanticSlices(repo, summary);
+  const semanticMarkdown = buildSemanticSlicesMarkdown(semanticIndex);
   const pack = buildRepoPack(repo, summary);
-  const report = buildReport(summary, pack, tasks, pricePer1m, runsPerWeek);
+  const report = buildReport(summary, pack, tasks, pricePer1m, runsPerWeek, semanticIndex, semanticMarkdown);
   fs.writeFileSync(path.join(outDir, "repo-pack.md"), pack, "utf8");
+  fs.writeFileSync(path.join(outDir, "semantic-slices.json"), JSON.stringify(semanticIndex, null, 2) + "\n", "utf8");
+  fs.writeFileSync(path.join(outDir, "semantic-slices.md"), semanticMarkdown, "utf8");
   fs.writeFileSync(path.join(outDir, "agent-instructions.md"), buildInstructions(), "utf8");
   fs.writeFileSync(path.join(outDir, "savings-report.json"), JSON.stringify(report, null, 2) + "\n", "utf8");
   fs.writeFileSync(path.join(outDir, "savings-report.md"), reportMarkdown(report), "utf8");
-  return { outDir, summary, pack, report };
+  writeLocalCache(outDir, {
+    artifact_version: 1,
+    fingerprint,
+    created_utc: new Date().toISOString(),
+    files_indexed: summary.files.length,
+    source_tokens_indexed: summary.totalTokens,
+    repo_pack_sha256: sha256(pack),
+    report_sha256: sha256(stableJson(report)),
+    semantic_receipt_sha256: semanticIndex.receipt_sha256
+  });
+  return { outDir, summary, pack, report, semanticIndex, semanticMarkdown, localCacheHit: false, fingerprint };
+}
+
+
+function semanticReportMarkdown(report) {
+  const semantic = report.semantic_slices;
+  if (!semantic || !semantic.slice_count) return "";
+  const top = Array.isArray(semantic.top_slices) ? semantic.top_slices : [];
+  return `## Offline Semantic Slices
+
+- Artifact: \`${semantic.artifact}\`
+- JSON: \`${semantic.json_artifact}\`
+- Receipt hash: \`${semantic.receipt_hash}\`
+- Slice count: ${Number(semantic.slice_count || 0).toLocaleString()}
+- Semantic index tokens: ${Number(semantic.semantic_index_tokens || 0).toLocaleString()}
+- Potential tokens avoided per repeated task: ${Number(semantic.potential_tokens_avoided_per_repeated_task || 0).toLocaleString()}
+- Potential reduction vs broad read: ${semantic.potential_reduction_percent}%
+
+${top.map((slice) => `- ${slice.title}: ${Number(slice.file_count || 0).toLocaleString()} files, ${Number(slice.source_tokens_covered || 0).toLocaleString()} source tokens, ${Number(slice.fact_count || 0).toLocaleString()} facts`).join("\n")}
+
+These slices are generated offline from local file paths, hashes, imports, routes, and symbol lines. They enrich the local receipt and runtime plan without changing live provider prompts.
+`;
 }
 
 function reportMarkdown(report) {
@@ -504,7 +779,7 @@ Generated: ${report.created_utc}
 
 ${report.largest_files.map((row) => `- ${row.path}: ${row.tokens.toLocaleString()} tokens, hash ${row.hash}`).join("\n")}
 
-## Caveat
+${semanticReportMarkdown(report)}## Caveat
 
 This public scanner estimates repeated context waste. Real savings should be validated against provider usage or invoices.
 `;
@@ -513,7 +788,7 @@ This public scanner estimates repeated context waste. Real savings should be val
 function init(repo, options = {}) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
-  ensureAgentSpendGitignore(outDir);
+  ensureCostLayersGitignore(outDir);
   writeIfMissing(path.join(outDir, "config.json"), JSON.stringify({
     version: VERSION,
     created_utc: new Date().toISOString(),
@@ -532,14 +807,21 @@ function init(repo, options = {}) {
   if (!options.suppressNext) process.stdout.write("Next: costlayers scan\n");
 }
 
-function scan(repo, args) {
+async function scan(repo, args) {
   process.stdout.write(`Scanning repo: ${repo}\n`);
   const precomputed = scanToFiles(repo, args);
   const { outDir, report } = precomputed;
   process.stdout.write(`CostLayers scan complete\n`);
+  if (precomputed.localCacheHit) process.stdout.write(`Local exact cache hit: source hashes unchanged, reused CostLayers artifacts\n`);
   process.stdout.write(`Repo pack: ${path.join(outDir, "repo-pack.md")}\n`);
+  process.stdout.write(`Semantic slices: ${path.join(outDir, "semantic-slices.md")}\n`);
   process.stdout.write(`Report: ${path.join(outDir, "savings-report.md")}\n`);
   printSavingsSummary(report);
+  await trackEvent(repo, args, "cli_scan", {
+    files_indexed: report.files_indexed,
+    context_tokens_avoided_per_task: report.tokens_avoided_per_repeated_task,
+    local_cache_hit: Boolean(precomputed.localCacheHit)
+  });
 }
 
 function connectEngine(repo, args) {
@@ -582,6 +864,58 @@ function loadConnection(repo, args) {
   };
 }
 
+function localAudit(repo) {
+  const auditPath = path.join(repo, ".agentspend", "ai-spend-audit.json");
+  const savingsPath = path.join(repo, ".agentspend", "savings-report.json");
+  const auditReportPath = path.join(repo, ".agentspend", "ai-spend-audit.md");
+  const savingsReportPath = path.join(repo, ".agentspend", "savings-report.md");
+  const audit = readJsonIfExists(auditPath);
+  const savings = readJsonIfExists(savingsPath);
+  if (!audit && !savings) return null;
+  return { audit, savings, auditReportPath, savingsReportPath };
+}
+
+function printLocalDashboard(repo) {
+  const local = localAudit(repo);
+  if (!local) {
+    process.stderr.write([
+      "No CostLayers dashboard is available for this repo yet.",
+      "",
+      "Run a free local audit first:",
+      `  npx -y ${INSTALL_SPEC} audit --monthly-spend 10000`,
+      "",
+      "Or create a hosted dashboard:",
+      `  npx -y ${INSTALL_SPEC} signup --email you@example.com`,
+      ""
+    ].join("\n"));
+    return false;
+  }
+  const audit = local.audit || {};
+  const savings = local.savings || {};
+  const contextTokens = audit.tokens_avoided_per_run ?? savings.tokens_avoided_per_repeated_task ?? 0;
+  const contextReduction = audit.context_reduction_percent ?? savings.estimated_reduction_percent ?? 0;
+  const contextPackTokens = audit.context_pack_tokens ?? savings.context_pack_tokens ?? 0;
+  const sourceTokens = audit.source_tokens_indexed ?? savings.source_tokens_indexed ?? 0;
+  process.stdout.write(`CostLayers Local Dashboard\n`);
+  process.stdout.write(`status: local audit only; no hosted account connected\n`);
+  process.stdout.write(`repo: ${path.basename(repo)}\n`);
+  if (audit.spend_analyzed_display) process.stdout.write(`ai_spend_analyzed: ${audit.spend_analyzed_display}\n`);
+  if (audit.waste_found_display) process.stdout.write(`candidate_waste_found: ${audit.waste_found_display}\n`);
+  if (audit.safe_savings_display) process.stdout.write(`quality_safe_savings_now: ${audit.safe_savings_display}\n`);
+  process.stdout.write(`context_tokens_avoided_per_agent_run: ${formatInt(contextTokens)}\n`);
+  process.stdout.write(`context_reduction: ${Number(contextReduction || 0).toFixed(2)}%\n`);
+  process.stdout.write(`before_after_context: ${formatInt(sourceTokens)} -> ${formatInt(contextPackTokens)} tokens\n`);
+  process.stdout.write(`local_report: ${local.audit ? local.auditReportPath : local.savingsReportPath}\n`);
+  process.stdout.write(`\nNext:\n`);
+  process.stdout.write(`  Open the local report above, or create the hosted savings meter:\n`);
+  process.stdout.write(`  npx -y ${INSTALL_SPEC} signup --email you@example.com\n`);
+  process.stdout.write(`\nEvidence labels:\n`);
+  process.stdout.write(`  Context estimate: local scan, visible immediately.\n`);
+  process.stdout.write(`  Usage stretch: appears after Codex profile token events.\n`);
+  process.stdout.write(`  API invoice savings: appears only after API-billed traffic is routed through CostLayers.\n`);
+  return true;
+}
+
 function defaultPublicGatewayUrl(engineUrl, apiKey) {
   try {
     const url = new URL(engineUrl);
@@ -620,14 +954,45 @@ function savingsProjection(report) {
   };
 }
 
+function savingsVerdict(report) {
+  const projection = savingsProjection(report);
+  const avoided = Number(report.tokens_avoided_per_repeated_task || 0);
+  const sourceTokens = Number(report.source_tokens_indexed || 0);
+  const reduction = Number(report.estimated_reduction_percent || 0);
+  const meaningful = avoided >= 1000 && reduction >= 15 && projection.monthlyUsd >= 0.25;
+  return {
+    projection,
+    avoided,
+    sourceTokens,
+    reduction,
+    meaningful,
+    smallRepo: sourceTokens < 5000 || avoided < 1000
+  };
+}
+
 function dashboardUrlFromConnection(connection) {
   return (connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key)).replace("/gateway/", "/engine/dashboard/");
 }
 
-function printSavingsSummary(report) {
-  const projection = savingsProjection(report);
-  const avoided = Number(report.tokens_avoided_per_repeated_task || 0);
-  process.stdout.write(`\n${avoided > 0 ? "CostLayers found repeated context waste" : "CostLayers built your repo context pack"}\n`);
+function printSavingsSummary(report, options = {}) {
+  const verdict = savingsVerdict(report);
+  const projection = verdict.projection;
+  const avoided = verdict.avoided;
+  if (options.compact) {
+    if (!verdict.meaningful) {
+      process.stdout.write(`CostLayers: repo scanned; no meaningful savings claim for this small/simple repo.\n`);
+    } else {
+      process.stdout.write(`CostLayers found context waste: ${formatInt(report.tokens_avoided_per_repeated_task)} tokens/run avoided (${report.estimated_reduction_percent}% less).\n`);
+      process.stdout.write(`Usage-stretch estimate: ${formatUsd(projection.monthlyUsd)}/month at ${formatInt(projection.runsPerWeek)} agent runs/week.\n`);
+    }
+    process.stdout.write(`Invoice savings require API mode; ChatGPT-login mode keeps native Codex auth.\n`);
+    return;
+  }
+  if (!verdict.meaningful) {
+    process.stdout.write(`\nCostLayers installed. This repo is too small for a meaningful savings claim.\n`);
+  } else {
+    process.stdout.write(`\nCostLayers found repeated context waste\n`);
+  }
   process.stdout.write(`  Evidence: context estimate from local repo scan\n`);
   process.stdout.write(`  Tokens avoided per repeated task: ${formatInt(report.tokens_avoided_per_repeated_task)}\n`);
   if (avoided > 0) {
@@ -638,9 +1003,187 @@ function printSavingsSummary(report) {
   }
   process.stdout.write(`  Estimated waste value per ${formatInt(report.repeated_tasks_modeled)} repeated tasks: ${formatUsd(report.estimated_usd_saved)}\n`);
   process.stdout.write(`  Usage-stretch estimate at ${formatInt(projection.runsPerWeek)} agent runs/week: ${formatUsd(projection.weeklyUsd)}/week, ${formatUsd(projection.monthlyUsd)}/month\n`);
+  if (!verdict.meaningful) {
+    process.stdout.write(`  Verdict: no savings claim for this repo. CostLayers is strongest on large repos and repeated agent sessions.\n`);
+  }
   process.stdout.write(`  Invoice savings require API traffic through CostLayers invoice mode.\n`);
   process.stdout.write(`  Source tokens indexed: ${formatInt(report.source_tokens_indexed)}\n`);
   process.stdout.write(`  Compact repo pack: ${formatInt(report.context_pack_tokens)} tokens\n`);
+  const semantic = report.semantic_slices || null;
+  if (semantic && semantic.slice_count) {
+    process.stdout.write(`  Offline semantic slices: ${formatInt(semantic.slice_count)} slices, ${formatInt(semantic.semantic_index_tokens)} tokens, receipt ${String(semantic.receipt_hash || "").slice(0, 12)}\n`);
+  }
+}
+
+function moneyNumber(value) {
+  const text = String(value || "").replace(/[$,_\s]/g, "");
+  const number = Number(text);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+function usageSpendFromObject(value) {
+  if (!value) return 0;
+  if (Array.isArray(value)) return value.reduce((sum, item) => sum + usageSpendFromObject(item), 0);
+  if (typeof value !== "object") return 0;
+  const directKeys = [
+    "cost_usd",
+    "total_cost_usd",
+    "billed_usd",
+    "spend_usd",
+    "amount_usd",
+    "total_usd",
+    "cost",
+    "total_cost",
+    "amount",
+    "usd"
+  ];
+  for (const key of directKeys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      const amount = moneyNumber(value[key]);
+      if (amount > 0) return amount;
+    }
+  }
+  const nestedKeys = ["data", "rows", "items", "usage", "results", "records"];
+  let total = 0;
+  for (const key of nestedKeys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) total += usageSpendFromObject(value[key]);
+  }
+  return total;
+}
+
+function parseCsvSpend(text) {
+  const lines = String(text || "").split(/\r?\n/).filter(Boolean);
+  if (lines.length < 2) return 0;
+  const headers = lines[0].split(",").map((item) => item.trim().replace(/^"|"$/g, "").toLowerCase());
+  const spendColumns = headers
+    .map((name, index) => ({ name, index }))
+    .filter(({ name }) => /^(cost_usd|total_cost_usd|billed_usd|spend_usd|amount_usd|total_usd|cost|amount|usd)$/.test(name));
+  if (!spendColumns.length) return 0;
+  let total = 0;
+  for (const line of lines.slice(1)) {
+    const cells = line.split(",");
+    const column = spendColumns.find(({ index }) => moneyNumber(cells[index]) > 0);
+    if (column) total += moneyNumber(cells[column.index]);
+  }
+  return total;
+}
+
+function loadSpendInput(args) {
+  const supplied = moneyNumber(args["monthly-spend"] || args.spend);
+  if (supplied > 0) return { monthlySpendUsd: supplied, source: "user-supplied monthly spend" };
+  const usageFile = args["usage-file"] ? path.resolve(String(args["usage-file"])) : "";
+  if (!usageFile) return { monthlySpendUsd: 0, source: "not supplied" };
+  if (!fs.existsSync(usageFile)) {
+    process.stderr.write(`Usage file not found: ${usageFile}\n`);
+    process.exit(2);
+  }
+  const text = fs.readFileSync(usageFile, "utf8");
+  let total = 0;
+  if (usageFile.toLowerCase().endsWith(".json")) {
+    try {
+      total = usageSpendFromObject(JSON.parse(text));
+    } catch (err) {
+      process.stderr.write(`Could not parse usage JSON: ${err.message}\n`);
+      process.exit(2);
+    }
+  } else {
+    total = parseCsvSpend(text);
+  }
+  return { monthlySpendUsd: total, source: `usage import: ${usageFile}` };
+}
+
+function buildAuditMarkdown(audit) {
+  return `# CostLayers AI Spend Audit
+
+Generated: ${audit.created_utc}
+Repo: ${audit.repo}
+
+## Executive Summary
+
+- AI spend analyzed: ${audit.spend_analyzed_display}
+- Candidate waste found: ${audit.waste_found_display}
+- Quality-safe savings available now: ${audit.safe_savings_display}
+- First-scan context reduction: ${audit.context_reduction_percent}%
+- Repeated-context tokens avoided/run: ${audit.tokens_avoided_per_run.toLocaleString()}
+
+## Evidence Labels
+
+- Safe estimate: local repo scan found repeated context that agents can avoid before broad exploration.
+- Verified invoice savings: requires API-mode traffic through CostLayers and provider cost rows.
+- Risky savings: not counted here. CostLayers should forward unchanged when a reduction boundary is unsafe.
+
+## Recommended Next Step
+
+${audit.next_step}
+
+## Largest Repeated Context Sources
+
+${audit.largest_files.map((row) => `- ${row.path}: ${row.tokens.toLocaleString()} tokens`).join("\n")}
+`;
+}
+
+function buildAuditReport(repo, report, args) {
+  const projection = savingsProjection(report);
+  const spendInput = loadSpendInput(args);
+  const spendAnalyzed = spendInput.monthlySpendUsd;
+  const contextSafeSavings = projection.monthlyUsd;
+  const contextRatio = Math.max(0, Math.min(1, Number(report.estimated_reduction_percent || 0) / 100));
+  const budgetWasteEstimate = spendAnalyzed > 0 ? spendAnalyzed * Math.min(0.25, contextRatio * 0.2) : 0;
+  const wasteFound = Math.max(contextSafeSavings, budgetWasteEstimate);
+  const safeSavings = contextSafeSavings;
+  return {
+    created_utc: new Date().toISOString(),
+    repo: path.basename(repo),
+    spend_source: spendInput.source,
+    monthly_spend_analyzed_usd: Number(spendAnalyzed.toFixed(6)),
+    waste_found_usd_per_month: Number(wasteFound.toFixed(6)),
+    quality_safe_savings_usd_per_month: Number(safeSavings.toFixed(6)),
+    context_reduction_percent: Number(report.estimated_reduction_percent || 0),
+    tokens_avoided_per_run: Number(report.tokens_avoided_per_repeated_task || 0),
+    source_tokens_indexed: Number(report.source_tokens_indexed || 0),
+    context_pack_tokens: Number(report.context_pack_tokens || 0),
+    largest_files: report.largest_files || [],
+    spend_analyzed_display: spendAnalyzed > 0 ? `${formatUsd(spendAnalyzed)}/month (${spendInput.source})` : "not supplied; using repo-scan savings only",
+    waste_found_display: `${formatUsd(wasteFound)}/month candidate estimate`,
+    safe_savings_display: `${formatUsd(safeSavings)}/month from local context scan`,
+    next_step: spendAnalyzed > 0
+      ? "Enable API invoice mode on one controlled coding-agent workflow so CostLayers can turn the audit estimate into verified provider-dollar savings."
+      : "Rerun with --monthly-spend <usd> or --usage-file <path>, then enable API invoice mode on one controlled workflow."
+  };
+}
+
+function writeAuditReport(outDir, repo, report, args) {
+  const auditReport = buildAuditReport(repo, report, args);
+  fs.writeFileSync(path.join(outDir, "ai-spend-audit.json"), JSON.stringify(auditReport, null, 2) + "\n", "utf8");
+  fs.writeFileSync(path.join(outDir, "ai-spend-audit.md"), buildAuditMarkdown(auditReport), "utf8");
+  return auditReport;
+}
+
+async function audit(repo, args) {
+  process.stdout.write(`Running CostLayers AI spend audit for: ${repo}\n`);
+  const precomputed = scanToFiles(repo, args);
+  const { outDir, report } = precomputed;
+  const auditReport = writeAuditReport(outDir, repo, report, args);
+  process.stdout.write(`\nCostLayers AI Spend Audit\n`);
+  process.stdout.write(`\nYou found repeated context waste\n`);
+  process.stdout.write(`  AI spend analyzed: ${auditReport.spend_analyzed_display}\n`);
+  process.stdout.write(`  Candidate waste found: ${auditReport.waste_found_display}\n`);
+  process.stdout.write(`  Quality-safe savings available now: ${auditReport.safe_savings_display}\n`);
+  process.stdout.write(`  Context reduction: ${auditReport.context_reduction_percent}%\n`);
+  process.stdout.write(`  Tokens avoided per agent run: ${formatInt(auditReport.tokens_avoided_per_run)}\n`);
+  process.stdout.write(`  Audit report: ${path.join(outDir, "ai-spend-audit.md")}\n`);
+  process.stdout.write(`\nView this result any time:\n`);
+  process.stdout.write(`  npx -y ${INSTALL_SPEC} dashboard\n`);
+  process.stdout.write(`\nNext best step:\n`);
+  process.stdout.write(`  ${auditReport.next_step}\n`);
+  process.stdout.write(`\nHosted dashboard, optional:\n`);
+  process.stdout.write(`  npx -y ${INSTALL_SPEC} signup --email you@example.com\n`);
+  await trackEvent(repo, args, "ai_spend_audit", {
+    monthly_spend_analyzed_usd: auditReport.monthly_spend_analyzed_usd,
+    waste_found_usd_per_month: auditReport.waste_found_usd_per_month,
+    quality_safe_savings_usd_per_month: auditReport.quality_safe_savings_usd_per_month,
+    context_tokens_avoided_per_task: auditReport.tokens_avoided_per_run
+  });
 }
 
 function codexHomeDir() {
@@ -698,6 +1241,15 @@ function profileTomlString(connection, args = {}) {
   const baseUrl = `${gateway}/v1`;
   const engineUrl = String(connection.engine_url || "https://costlayers.com/engine").replace(/\/+$/, "");
   const apiKeyEnv = codexProxyApiKeyEnv(args);
+  const otelExporter = {
+    "otlp-http": {
+      endpoint: `${engineUrl}/v1/codex-meter`,
+      protocol: "json",
+      headers: {
+        "x-costlayers-key": connection.api_key || ""
+      }
+    }
+  };
   const lines = [
     "# Generated by CostLayers. This profile sends Codex telemetry to the CostLayers meter.",
     "# Keep this file private because it contains your keyed CostLayers endpoint.",
@@ -723,18 +1275,27 @@ function profileTomlString(connection, args = {}) {
     "[otel]",
     'environment = "costlayers"',
     "log_user_prompt = false",
-    "",
-    '[otel.exporter."otlp-http"]',
-    `endpoint = ${JSON.stringify(`${engineUrl}/v1/codex-meter`)}`,
-    'protocol = "json"',
-    "",
-    '[otel.exporter."otlp-http".headers]',
-    `"x-costlayers-key" = ${JSON.stringify(connection.api_key || "")}`,
+    `exporter = ${toTomlInline(otelExporter)}`,
     ""
   );
   return lines.join("\n");
 }
 
+function toTomlInline(value) {
+  if (value === null || value === undefined) return '""';
+  if (Array.isArray(value)) return `[${value.map((item) => toTomlInline(item)).join(", ")}]`;
+  if (typeof value === "object") {
+    return `{ ${Object.entries(value).map(([key, item]) => `${tomlKey(key)} = ${toTomlInline(item)}`).join(", ")} }`;
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return JSON.stringify(String(value));
+}
+
+function tomlKey(key) {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key);
+}
+
 function writeCodexProfile(connection, args = {}) {
   const dir = codexHomeDir();
   ensureDir(dir);
@@ -821,18 +1382,23 @@ async function ensureConnection(repo, args) {
 
 async function signup(repo, args) {
   const connection = await signupConnection(repo, args);
+  await trackEvent(repo, args, "signup", { label: connection.label || path.basename(repo) }, connection);
   process.stdout.write(`CostLayers self-serve key created\n`);
   process.stdout.write(`Engine: ${connection.engine_url}\n`);
   process.stdout.write(`Gateway: ${connection.gateway_url}\n`);
   process.stdout.write(`Dashboard: ${dashboardUrlFromConnection(connection)}\n`);
   process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
   process.stdout.write(`Plan: free beta\n`);
-  process.stdout.write(`Next: costlayers gateway start --mode reduce --provider-url https://api.openai.com\n`);
+  process.stdout.write(`\nNext:\n`);
+  process.stdout.write(`  View dashboard: npx -y ${INSTALL_SPEC} dashboard\n`);
+  process.stdout.write(`  Run Codex with usage-stretch metering: npx -y ${INSTALL_SPEC} codex --email ${connection.email || "you@example.com"} --chatgpt\n`);
+  process.stdout.write(`  Prove API invoice savings: export OPENAI_API_KEY=sk-proj-... && npx -y ${INSTALL_SPEC} test --email ${connection.email || "you@example.com"}\n`);
 }
 
 async function codexProfile(repo, args) {
   const connection = await ensureConnection(repo, args);
   const profilePath = writeCodexProfile(connection, args);
+  await trackEvent(repo, args, "codex_profile", { profile_mode: codexProxyEnabled(args) ? "api" : "chatgpt" }, connection);
   process.stdout.write(`CostLayers Codex profile installed\n`);
   process.stdout.write(`Profile: ${profilePath}\n`);
   process.stdout.write(`Mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode, native Codex provider preserved"}\n`);
@@ -883,38 +1449,91 @@ function postJson(urlString, payload, apiKey) {
   });
 }
 
+function engineUrlFromArgsOrConnection(args = {}, connection = null) {
+  const fromArgs = String(args["engine-url"] || "").replace(/\/+$/, "");
+  if (fromArgs) return fromArgs;
+  const fromConnection = connection && connection.engine_url ? String(connection.engine_url).replace(/\/+$/, "") : "";
+  return fromConnection || "https://costlayers.com/engine";
+}
+
+async function trackEvent(repo, args = {}, eventType, metadata = {}, connection = null) {
+  if (args["no-telemetry"] || process.env.COSTLAYERS_DISABLE_TELEMETRY) return;
+  const engineUrl = engineUrlFromArgsOrConnection(args, connection);
+  const payload = {
+    event_type: eventType,
+    source: "costlayers-cli",
+    email: normalizedEmail(args.email),
+    metadata: {
+      version: VERSION,
+      repo_label: path.basename(repo || process.cwd()),
+      command: args._ ? args._[0] : "",
+      api_mode: apiInvoiceModeRequested(args),
+      chatgpt_mode: chatgptModeRequested(args),
+      platform: process.platform,
+      node: process.version,
+      ...metadata
+    }
+  };
+  try {
+    await postJson(`${engineUrl}/v1/event`, payload, connection ? connection.api_key : null);
+  } catch {
+    // Metrics must never block local developer workflow.
+  }
+}
+
 function buildLocalPlan(report) {
+  const semantic = report.semantic_slices || null;
+  const instructions = [
+    "Read .agentspend/repo-pack.md before broad exploration.",
+    "Use .agentspend/savings-report.md to identify repeated context sources.",
+    "Prefer targeted reads of files listed in the repo pack.",
+    "Do not reread unchanged large files unless exact code is required."
+  ];
+  if (semantic && semantic.slice_count) {
+    instructions.splice(1, 0, "Read .agentspend/semantic-slices.md first when route or symbol facts are enough; open exact files only when needed.");
+  }
   return {
     mode: "local",
     created_utc: new Date().toISOString(),
     plan_summary: "Use the repo pack before broad exploration and avoid rereading unchanged large files.",
     expected_value: {
       tokens_avoided_per_repeated_task: report.tokens_avoided_per_repeated_task,
-      estimated_usd_saved: report.estimated_usd_saved
+      estimated_usd_saved: report.estimated_usd_saved,
+      semantic_slice_count: semantic ? semantic.slice_count : 0,
+      semantic_index_tokens: semantic ? semantic.semantic_index_tokens : 0,
+      semantic_receipt_hash: semantic ? semantic.receipt_hash : ""
     },
-    runtime_instructions: [
-      "Read .agentspend/repo-pack.md before broad exploration.",
-      "Use .agentspend/savings-report.md to identify repeated context sources.",
-      "Prefer targeted reads of files listed in the repo pack.",
-      "Do not reread unchanged large files unless exact code is required."
-    ]
+    runtime_instructions: instructions
   };
 }
 
 async function fetchEnginePlan(connection, repo, pack, report) {
   if (!connection || !connection.engine_url) return null;
+  const semantic = report && report.semantic_slices ? report.semantic_slices : {};
   const payload = {
     version: VERSION,
     repo_name: path.basename(repo),
     repo_pack_sha256: sha256(pack),
-    repo_pack_preview: pack.slice(0, 12000),
-    savings_report: report
+    privacy_mode: argsPrivacyMode(connection),
+    savings_report: report,
+    local_artifacts: {
+      repo_pack_sha256: sha256(pack),
+      savings_report_sha256: sha256(stableJson(report || {})),
+      semantic_receipt_hash: semantic && semantic.receipt_hash ? String(semantic.receipt_hash) : ""
+    }
   };
+  if (connection && connection.send_repo_preview) payload.repo_pack_preview = pack.slice(0, 12000);
   const plan = await postJson(`${connection.engine_url}/v1/plan`, payload, connection.api_key);
   plan.mode = plan.mode || "closed-engine";
   return plan;
 }
 
+function argsPrivacyMode(connection) {
+  return connection && connection.send_repo_preview
+    ? "opt_in_repo_preview"
+    : "hashes_metrics_and_reports_default";
+}
+
 function writeRuntimePrompt(outDir, plan) {
   const lines = [];
   lines.push("# CostLayers Runtime Plan");
@@ -946,27 +1565,33 @@ async function runAgent(repo, args, argv, options = {}) {
   if (connection && connection.engine_url) {
     try {
       plan = await fetchEnginePlan(connection, repo, pack, report);
-      process.stdout.write(`Fetched CostLayers engine plan\n`);
+      if (!options.compactOutput) process.stdout.write(`Fetched CostLayers engine plan\n`);
     } catch (err) {
       process.stderr.write(`Engine unavailable; falling back to local plan: ${err.message}\n`);
     }
   }
   writeRuntimePrompt(outDir, plan);
-  process.stdout.write(`Runtime plan: ${path.join(outDir, "runtime-plan.md")}\n`);
+  if (!options.compactOutput) process.stdout.write(`Runtime plan: ${path.join(outDir, "runtime-plan.md")}\n`);
   let commandToRun = command;
   if (connection && connection.engine_url && isCodexCommand(command)) {
     assertCodexProxyApiKey(args);
     const profilePath = writeCodexProfile(connection, args);
     commandToRun = withCostLayersCodexProfile(command);
-    process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
-    process.stdout.write(`Codex metering enabled: ${commandToRun.join(" ")}\n`);
-    process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
-    process.stdout.write(`Savings dashboard: ${dashboardUrlFromConnection(connection)}\n`);
-    process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
+    await trackEvent(repo, args, "codex_run", { profile_mode: codexProxyEnabled(args) ? "api" : "chatgpt" }, connection);
+    if (options.compactOutput) {
+      process.stdout.write(`Launching Codex with CostLayers profile: ${commandToRun.join(" ")}\n`);
+    } else {
+      process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
+      process.stdout.write(`Codex metering enabled: ${commandToRun.join(" ")}\n`);
+      process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
+      process.stdout.write(`Savings dashboard: ${dashboardUrlFromConnection(connection)}\n`);
+      process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
+    }
   }
   const env = {
     ...process.env,
     AGENTSPEND_REPO_PACK: path.join(outDir, "repo-pack.md"),
+    AGENTSPEND_SEMANTIC_SLICES: path.join(outDir, "semantic-slices.md"),
     AGENTSPEND_RUNTIME_PLAN: path.join(outDir, "runtime-plan.md")
   };
   const result = spawnSync(commandToRun[0], commandToRun.slice(1), {
@@ -1001,6 +1626,7 @@ async function gateway(repo, args) {
     process.stdout.write(`CostLayers gateway ready: ${result.base_url}\n`);
     process.stdout.write(`Set your OpenAI-compatible base URL to: ${result.base_url}\n`);
     process.stdout.write(`Report: costlayers gateway report\n`);
+    await trackEvent(repo, args, "api_mode_start", { mode: payload.mode, dry_run: payload.dry_run }, connection);
     return;
   }
   if (action === "report") {
@@ -1020,6 +1646,7 @@ async function gateway(repo, args) {
     process.stdout.write(`saved_cost_usd: ${summary.saved_cost_usd || 0}\n`);
     process.stdout.write(`gateway_authenticated_actions: ${status.gateway_request_count || 0}\n`);
     process.stdout.write(`dashboard: ${dashboardUrlFromConnection(connection)}\n`);
+    await trackEvent(repo, args, "gateway_report", {}, connection);
     return;
   }
   if (action === "stop") {
@@ -1032,8 +1659,20 @@ async function gateway(repo, args) {
 }
 
 async function dashboard(repo, args) {
-  const connection = loadConnection(repo, args);
-  const status = await postJson(`${connection.engine_url}/v1/me`, {}, connection.api_key);
+  const connection = loadStoredConnection(repo);
+  if (!connection || !connection.engine_url || !connection.api_key) {
+    if (printLocalDashboard(repo)) return;
+    process.exit(2);
+  }
+  let status;
+  try {
+    status = await postJson(`${connection.engine_url}/v1/me`, {}, connection.api_key);
+  } catch (err) {
+    process.stderr.write(`Hosted dashboard unavailable: ${err.message}\n\n`);
+    if (printLocalDashboard(repo)) return;
+    process.exit(1);
+  }
+  await trackEvent(repo, args, "dashboard_open", {}, connection);
   const dashboardUrl = (connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key)).replace("/gateway/", "/engine/dashboard/");
   process.stdout.write(`CostLayers Dashboard\n`);
   process.stdout.write(`URL: ${dashboardUrl}\n`);
@@ -1054,11 +1693,11 @@ async function codexShortcut(repo, args, argv) {
   const codexTail = codexArgsAfterDash(argv);
   const command = codexTail.length > 0 ? codexTail : ["codex"];
   const commandToRun = isCodexCommand(command) ? command : ["codex", ...command];
-  const nextArgs = withAutoCodexMode(args);
+  const nextArgs = withAutoCodexMode({ ...args, "ux-compact": true });
   if (codexProxyEnabled(nextArgs)) {
     process.stdout.write(`CostLayers Codex: API invoice mode explicitly enabled from ${codexProxyApiKeyEnv(nextArgs)}.\n`);
   } else {
-    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Pass --api to route API-billed provider calls for invoice savings.\n`);
+    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Native Codex auth stays unchanged.\n`);
   }
   return start(repo, nextArgs, ["start", "--", ...commandToRun]);
 }
@@ -1084,6 +1723,7 @@ async function savingsTest(repo, args) {
     ? args.prompt
     : "Analyze this repository. Find the main entry points, data flow, and the 5 files most worth reading. Do not edit files.";
   assertCodexProxyApiKey(nextArgs, `npx -y ${INSTALL_SPEC} test --email you@example.com`);
+  await trackEvent(repo, nextArgs, "api_savings_test", {}, loadStoredConnection(repo));
   process.stdout.write("CostLayers savings test: running one safe read-only Codex task.\n");
   const status = await start(repo, nextArgs, ["start", "--", "codex", "exec", "--sandbox", "read-only", prompt], { returnStatus: true });
   process.stdout.write("\nCostLayers savings test report\n");
@@ -1098,27 +1738,39 @@ async function savingsTest(repo, args) {
 async function start(repo, args, argv, options = {}) {
   const dash = argv.indexOf("--");
   const command = dash >= 0 ? argv.slice(dash + 1) : [];
+  const compactOutput = Boolean(args["ux-compact"]);
   const codexTelemetryRun = command.length > 0 && isCodexCommand(command) && !codexProxyEnabled(args);
   if (command.length > 0 && isCodexCommand(command)) assertCodexProxyApiKey(args);
   init(repo, { suppressNext: true });
   process.stdout.write(`Scanning repo: ${repo}\n`);
   const precomputed = scanToFiles(repo, args);
   const { outDir, pack, report } = precomputed;
+  writeAuditReport(outDir, repo, report, args);
   process.stdout.write(`CostLayers scan complete\n`);
-  process.stdout.write(`Report: ${path.join(outDir, "savings-report.md")}\n`);
-  printSavingsSummary(report);
+  if (precomputed.localCacheHit) process.stdout.write(`Local exact cache hit: source hashes unchanged, reused CostLayers artifacts\n`);
+  if (!compactOutput) process.stdout.write(`Report: ${path.join(outDir, "savings-report.md")}\n`);
+  printSavingsSummary(report, { compact: compactOutput });
   const connection = await ensureConnection(repo, args);
+  await trackEvent(repo, args, "cli_start", {
+    files_indexed: report.files_indexed,
+    context_tokens_avoided_per_task: report.tokens_avoided_per_repeated_task,
+    local_cache_hit: Boolean(precomputed.localCacheHit)
+  }, connection);
   try {
     await fetchEnginePlan(connection, repo, pack, report);
     process.stdout.write(`Dashboard synced with first-run savings\n`);
   } catch (err) {
     process.stderr.write(`Dashboard sync delayed; local report is still available: ${err.message}\n`);
   }
-  process.stdout.write(`CostLayers connection ready\n`);
+  if (!compactOutput) process.stdout.write(`CostLayers connection ready\n`);
   let gatewayBaseUrl = connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key);
   if (codexTelemetryRun) {
-    process.stdout.write(`ChatGPT-login Codex mode: native Codex provider preserved; model calls are not routed through CostLayers.\n`);
-    process.stdout.write(`What users get: less repeated repo context and a usage-stretch meter. This does not reduce a flat ChatGPT subscription invoice.\n`);
+    if (compactOutput) {
+      process.stdout.write(`Mode: ChatGPT-login Codex. Model calls are not routed; CostLayers adds repo context discipline and usage-stretch metering.\n`);
+    } else {
+      process.stdout.write(`ChatGPT-login Codex mode: native Codex provider preserved; model calls are not routed through CostLayers.\n`);
+      process.stdout.write(`What users get: repo context discipline and a usage-stretch meter. This does not reduce a flat ChatGPT subscription invoice.\n`);
+    }
   } else {
     const providerUrl = typeof args["provider-url"] === "string" ? args["provider-url"] : "https://api.openai.com";
     const payload = {
@@ -1140,30 +1792,47 @@ async function start(repo, args, argv, options = {}) {
     process.stdout.write(`OpenAI-compatible base URL: ${gatewayBaseUrl}\n`);
     if (codexProxyEnabled(args)) {
       process.stdout.write(`API invoice mode: Codex will use ${codexProxyApiKeyEnv(args)} through the CostLayers gateway.\n`);
+      await trackEvent(repo, args, "api_mode_start", { mode: payload.mode, from_start: true }, connection);
     }
   }
   process.stdout.write(`Dashboard: ${dashboardUrlFromConnection(connection)}\n`);
-  process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
+  if (!compactOutput) process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
   process.stdout.write(`Plan: free beta\n`);
   const profilePath = writeCodexProfile(connection, args);
-  process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
-  process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
+  if (!compactOutput) {
+    process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
+    process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
+  }
   if (command.length > 0) {
-    return runAgent(repo, args, argv, { skipSetup: true, precomputed, returnStatus: options.returnStatus });
+    return runAgent(repo, args, argv, { skipSetup: true, precomputed, returnStatus: options.returnStatus, compactOutput });
   }
-  process.stdout.write(`\nNext options:\n`);
-  process.stdout.write(`  ChatGPT-login Codex: npx -y ${INSTALL_SPEC} codex --email you@example.com --chatgpt\n`);
-  process.stdout.write(`  API invoice Codex: export OPENAI_API_KEY=sk-proj-... && npx -y ${INSTALL_SPEC} codex --email you@example.com --api\n`);
-  process.stdout.write(`  Other OpenAI-compatible client base URL: ${gatewayBaseUrl}\n`);
-  process.stdout.write(`  Prove API savings: npx -y ${INSTALL_SPEC} test --email you@example.com\n`);
-  process.stdout.write(`  Or run Codex directly: codex --profile costlayers\n`);
-  process.stdout.write(`  View report: npx -y ${INSTALL_SPEC} gateway report\n`);
-  process.stdout.write(`  Dashboard: npx -y ${INSTALL_SPEC} dashboard\n`);
+  process.stdout.write(`\nReady.\n`);
+  process.stdout.write(`  Run Codex: codex --profile costlayers\n`);
+  process.stdout.write(`  Dashboard: ${dashboardUrlFromConnection(connection)}\n`);
+  process.stdout.write(`  API invoice proof: export OPENAI_API_KEY=sk-proj-... && npx -y ${INSTALL_SPEC} test --email you@example.com\n`);
 }
 
 function doctor() {
+  const repo = process.cwd();
+  const outDir = path.join(repo, ".agentspend");
+  const saved = loadStoredConnection(repo);
+  const codexCheck = spawnSync("codex", ["--version"], {
+    encoding: "utf8",
+    shell: process.platform === "win32"
+  });
+  const profilePath = path.join(codexHomeDir(), "costlayers.config.toml");
+  const reportPath = path.join(outDir, "savings-report.json");
+  const connectionCount = fs.existsSync(connectionsDir())
+    ? fs.readdirSync(connectionsDir()).filter((name) => name.endsWith(".json")).length
+    : 0;
   process.stdout.write(`CostLayers ${VERSION}\n`);
   process.stdout.write(`Node ${process.version}\n`);
+  process.stdout.write(`Codex: ${codexCheck.status === 0 ? String(codexCheck.stdout || codexCheck.stderr).trim() : "not found"}\n`);
+  process.stdout.write(`Repo: ${repo}${isHomeDirectory(repo) ? " (home directory; use --repo or cd into a project)" : ""}\n`);
+  process.stdout.write(`Local report: ${fs.existsSync(reportPath) ? reportPath : "not found; run costlayers scan"}\n`);
+  process.stdout.write(`Saved repo connection: ${saved && saved.api_key ? "yes" : "no"}\n`);
+  process.stdout.write(`Private connection store entries: ${connectionCount}\n`);
+  process.stdout.write(`Codex profile: ${fs.existsSync(profilePath) ? profilePath : "not installed"}\n`);
   process.stdout.write("Status: ok\n");
 }
 
@@ -1173,8 +1842,9 @@ function main() {
   const cmd = args._[0];
   if (!cmd || args.help || args.h) usage(0);
   const repo = path.resolve(String(args.repo || process.cwd()));
-  if (["init", "scan", "start", "run", "codex-profile", "codex", "test"].includes(cmd)) guardRepoRoot(repo, args);
+  if (["init", "scan", "audit", "start", "run", "codex-profile", "codex", "test"].includes(cmd)) guardRepoRoot(repo, args);
   if (cmd === "doctor") return doctor();
+  if (cmd === "audit") return audit(repo, args);
   if (cmd === "codex") return codexShortcut(repo, args, rawArgv);
   if (cmd === "test") return savingsTest(repo, args);
   if (cmd === "init") return init(repo);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "costlayers",
-  "version": "0.8.17",
+  "version": "0.8.27",
   "description": "CostLayers cost control for AI coding agents. Build compact repo context packs, gateway reports, and savings dashboards.",
   "bin": {
     "agentspend": "bin/agentspend.js",