costlayers 0.8.16 → 0.8.20

package/README.md

@@ -1,6 +1,6 @@
 # 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 a cost-optimization layer for AI coding agents. It reduces repeated token waste from repo exploration, 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
 
@@ -8,16 +8,16 @@ Daily Codex use:
 
 ```bash
 cd your-repo
-npx -y costlayers@latest codex --email you@example.com
+npx -y https://costlayers.com/costlayers-0.8.20.tgz codex --email you@example.com --chatgpt
 ```
 
-If `OPENAI_API_KEY` is set, CostLayers automatically uses API invoice mode.
-If no API key is set, it uses ChatGPT-login usage-stretch mode.
+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`.
 
 Run a one-command API savings test:
 
 ```bash
-npx -y costlayers@latest test --email you@example.com
+export OPENAI_API_KEY=sk-proj-...
+npx -y https://costlayers.com/costlayers-0.8.20.tgz test --email you@example.com
 ```
 
 ## Usage
@@ -25,7 +25,7 @@ npx -y costlayers@latest test --email you@example.com
 Inside a repo:
 
 ```bash
-npx -y costlayers@latest codex --email you@example.com
+npx -y https://costlayers.com/costlayers-0.8.20.tgz codex --email you@example.com --chatgpt
 ```
 
 This gives Codex `.agentspend/repo-pack.md` and `.agentspend/runtime-plan.md`
@@ -45,7 +45,7 @@ API write permission:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-...
-npx -y costlayers@latest codex --email you@example.com
+npx -y https://costlayers.com/costlayers-0.8.20.tgz codex --email you@example.com --api
 ```
 
 ChatGPT-login Codex can be metered, but it does not create per-request OpenAI
@@ -54,14 +54,14 @@ Platform invoice savings because it is not billed through your Platform API key.
 ## Which Mode Should I Use?
 
 - 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` for invoice-backed savings.
+- 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`.
 - 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.20.tgz codex-profile
 codex --profile costlayers
 ```
 
@@ -88,6 +88,8 @@ 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:
 
@@ -118,4 +120,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.16";
-const INSTALL_SPEC = "costlayers@latest";
+function packageVersion() {
+  try {
+    return require(path.join(__dirname, "..", "package.json")).version || "0.8.20";
+  } catch (_err) {
+    return "0.8.20";
+  }
+}
+
+const VERSION = packageVersion();
+const INSTALL_SPEC = "https://costlayers.com/costlayers-0.8.20.tgz";
 const DEFAULT_RUNS_PER_WEEK = 20;
 const WEEKS_PER_MONTH = 4.33;
 const DEFAULT_EXCLUDES = new Set([
@@ -45,6 +53,8 @@ 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}
@@ -66,8 +76,8 @@ Usage:
   costlayers doctor
 
 Commands:
-  codex   Start Codex with CostLayers. Uses API invoice mode automatically when OPENAI_API_KEY is set.
-  test    Run a safe read-only Codex task and print the CostLayers savings report.
+  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.
   scan    Build repo context pack and savings report.
   start   One-command setup, signup, gateway start, and optional agent run.
@@ -107,6 +117,14 @@ function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
 
+function chmodBestEffort(file, mode) {
+  try {
+    fs.chmodSync(file, mode);
+  } catch {
+    // Windows and some network filesystems may ignore POSIX modes.
+  }
+}
+
 function writeIfMissing(file, content) {
   if (!fs.existsSync(file)) fs.writeFileSync(file, content, "utf8");
 }
@@ -127,7 +145,7 @@ function guardRepoRoot(repo, args) {
     "",
     "Run it inside a project folder instead:",
     "  cd path/to/your-repo",
-    `  npx -y ${INSTALL_SPEC} codex --email you@example.com`,
+    `  npx -y ${INSTALL_SPEC} codex --email you@example.com --chatgpt`,
     "",
     "Or pass --repo path/to/your-repo from anywhere.",
     "If you really intend to scan your whole home directory, add --allow-home.",
@@ -153,10 +171,111 @@ function normalizedEmail(value) {
   return String(value || "").trim().toLowerCase();
 }
 
+function configRoot() {
+  const base = process.env.XDG_CONFIG_HOME
+    ? path.join(process.env.XDG_CONFIG_HOME, "costlayers")
+    : path.join(os.homedir(), ".config", "costlayers");
+  ensureDir(base);
+  chmodBestEffort(base, 0o700);
+  return base;
+}
+
+function connectionsDir() {
+  const dir = path.join(configRoot(), "connections");
+  ensureDir(dir);
+  chmodBestEffort(dir, 0o700);
+  return dir;
+}
+
+function connectionSecretPath(connectionId) {
+  return path.join(connectionsDir(), `${connectionId}.json`);
+}
+
+function repoConnectionPath(repo) {
+  return path.join(repo, ".agentspend", "connection.json");
+}
+
+function ensureAgentSpendGitignore(outDir) {
+  ensureDir(outDir);
+  const file = path.join(outDir, ".gitignore");
+  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;
+  for (const item of required) {
+    if (!lines.has(item)) {
+      current += `${current.endsWith("\n") || current.length === 0 ? "" : "\n"}${item}\n`;
+      changed = true;
+    }
+  }
+  if (changed || !fs.existsSync(file)) fs.writeFileSync(file, current, "utf8");
+}
+
+function connectionIdFor(repo, connection = {}) {
+  if (connection.connection_id) return String(connection.connection_id);
+  const seed = connection.api_key || `${path.resolve(repo)}\n${connection.engine_url || ""}\n${connection.email || ""}`;
+  return `cl_${sha256(seed).slice(0, 24)}`;
+}
+
+function publicConnectionMetadata(connection) {
+  return {
+    version: VERSION,
+    connection_id: connection.connection_id,
+    engine_url: connection.engine_url,
+    email: normalizedEmail(connection.email),
+    label: connection.label || "",
+    connected_utc: connection.connected_utc || new Date().toISOString(),
+    secret_store: "~/.config/costlayers/connections",
+    note: "Live CostLayers keys are stored outside the repo. Run `costlayers dashboard` to print your private dashboard URL."
+  };
+}
+
+function writePrivateJson(file, payload) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  chmodBestEffort(file, 0o600);
+}
+
+function saveConnection(repo, connection) {
+  const outDir = path.join(repo, ".agentspend");
+  ensureDir(outDir);
+  ensureAgentSpendGitignore(outDir);
+  const connectionId = connectionIdFor(repo, connection);
+  const full = {
+    ...connection,
+    connection_id: connectionId,
+    email: normalizedEmail(connection.email),
+    connected_utc: connection.connected_utc || new Date().toISOString()
+  };
+  writePrivateJson(connectionSecretPath(connectionId), full);
+  fs.writeFileSync(repoConnectionPath(repo), JSON.stringify(publicConnectionMetadata(full), null, 2) + "\n", "utf8");
+  return full;
+}
+
+function loadStoredConnection(repo) {
+  const saved = readJsonIfExists(repoConnectionPath(repo));
+  if (!saved) return null;
+  if (saved.api_key || saved.gateway_url) {
+    const migrated = saveConnection(repo, saved);
+    process.stdout.write(`CostLayers moved the live key out of .agentspend into ~/.config/costlayers.\n`);
+    return migrated;
+  }
+  const connectionId = saved.connection_id || connectionIdFor(repo, saved);
+  const secret = readJsonIfExists(connectionSecretPath(connectionId));
+  if (secret && secret.api_key) return { ...saved, ...secret, connection_id: connectionId };
+  return null;
+}
+
 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) {
@@ -280,6 +399,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`.");
@@ -287,15 +407,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.
 `;
@@ -309,15 +608,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,
@@ -331,6 +631,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,
@@ -350,24 +651,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);
+  ensureAgentSpendGitignore(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) {
@@ -401,15 +777,16 @@ 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.
 `;
 }
 
-function init(repo) {
+function init(repo, options = {}) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
+  ensureAgentSpendGitignore(outDir);
   writeIfMissing(path.join(outDir, "config.json"), JSON.stringify({
     version: VERSION,
     created_utc: new Date().toISOString(),
@@ -425,17 +802,24 @@ function init(repo) {
     process.stdout.write(`AGENTS.md already exists; snippet saved to ${path.join(outDir, "AGENTS_SNIPPET.md")}\n`);
   }
   process.stdout.write(`CostLayers initialized in ${outDir}\n`);
-  process.stdout.write("Next: costlayers scan\n");
+  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) {
@@ -451,21 +835,30 @@ function connectEngine(repo, args) {
     api_key: args["api-key"] ? String(args["api-key"]) : null,
     connected_utc: new Date().toISOString()
   };
-  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(config, null, 2) + "\n", "utf8");
+  saveConnection(repo, config);
   process.stdout.write(`Connected CostLayers engine: ${config.engine_url}\n`);
 }
 
 function loadConnection(repo, args) {
-  const outDir = path.join(repo, ".agentspend");
-  const saved = readJsonIfExists(path.join(outDir, "connection.json")) || {};
+  const saved = loadStoredConnection(repo) || {};
   const engineUrl = String(args["engine-url"] || saved.engine_url || "").replace(/\/+$/, "");
   if (!engineUrl) {
-    process.stderr.write("Missing engine connection. Run `agentspend connect --engine-url <url>` first.\n");
+    process.stderr.write("Missing engine connection. Run `costlayers signup --email you@example.com` first.\n");
+    process.exit(2);
+  }
+  const apiKey = args["api-key"] ? String(args["api-key"]) : saved.api_key || null;
+  if (!apiKey) {
+    process.stderr.write([
+      "CostLayers cannot find the live key for this repo.",
+      "Keys are stored outside the repo in ~/.config/costlayers/connections.",
+      "Run `costlayers signup --email you@example.com` again from this repo to create a fresh key.",
+      ""
+    ].join("\n"));
     process.exit(2);
   }
   return {
     engine_url: engineUrl,
-    api_key: args["api-key"] ? String(args["api-key"]) : saved.api_key || null
+    api_key: apiKey
   };
 }
 
@@ -507,14 +900,35 @@ 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`);
+  const verdict = savingsVerdict(report);
+  const projection = verdict.projection;
+  const avoided = verdict.avoided;
+  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) {
@@ -525,9 +939,16 @@ 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 codexHomeDir() {
@@ -557,23 +978,22 @@ function codexArgsAfterDash(argv) {
 
 function withAutoCodexMode(args = {}, options = {}) {
   const next = { ...args };
-  const keyEnv = codexProxyApiKeyEnv(next);
-  const hasApiKey = Boolean(process.env[keyEnv]);
-  const wantsInvoice = apiInvoiceModeRequested(next) || (options.preferInvoice && hasApiKey);
+  const wantsInvoice = apiInvoiceModeRequested(next) || Boolean(options.forceInvoice);
   if (!chatgptModeRequested(next) && wantsInvoice) next["codex-proxy"] = true;
   return next;
 }
 
-function assertCodexProxyApiKey(args = {}) {
+function assertCodexProxyApiKey(args = {}, rerunCommand = "") {
   if (!codexProxyEnabled(args)) return;
   const keyEnv = codexProxyApiKeyEnv(args);
   if (process.env[keyEnv]) return;
+  const command = rerunCommand || `npx -y ${INSTALL_SPEC} codex --email you@example.com --api`;
   process.stderr.write([
     `CostLayers invoice mode needs ${keyEnv} in this shell.`,
     "",
     "Set an OpenAI Platform API key with Responses API write permission, then rerun:",
     `  export ${keyEnv}=sk-proj-...`,
-    `  npx -y ${INSTALL_SPEC} codex --email you@example.com --api`,
+    `  ${command}`,
     "",
     "ChatGPT-login Codex can be metered, but it cannot produce provider invoice savings because there is no per-request Platform invoice to reduce.",
     ""
@@ -586,6 +1006,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.",
@@ -611,18 +1040,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);
@@ -673,19 +1111,11 @@ async function signupConnection(repo, args) {
     label: payload.label,
     connected_utc: new Date().toISOString()
   };
-  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(connection, null, 2) + "\n", "utf8");
-  return connection;
-}
-
-function saveConnection(repo, connection) {
-  const outDir = path.join(repo, ".agentspend");
-  ensureDir(outDir);
-  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(connection, null, 2) + "\n", "utf8");
+  return saveConnection(repo, connection);
 }
 
 async function ensureConnection(repo, args) {
-  const outDir = path.join(repo, ".agentspend");
-  const saved = readJsonIfExists(path.join(outDir, "connection.json"));
+  const saved = loadStoredConnection(repo);
   const requestedEmail = normalizedEmail(args.email);
   if (saved && saved.engine_url && saved.api_key) {
     if (!requestedEmail) return saved;
@@ -717,6 +1147,7 @@ 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`);
@@ -729,6 +1160,7 @@ async function signup(repo, args) {
 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`);
@@ -779,38 +1211,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");
@@ -837,7 +1322,7 @@ async function runAgent(repo, args, argv, options = {}) {
   }
   if (!options.skipSetup) init(repo);
   const { outDir, pack, report } = options.precomputed || scanToFiles(repo, args);
-  const connection = readJsonIfExists(path.join(outDir, "connection.json"));
+  const connection = loadStoredConnection(repo);
   let plan = buildLocalPlan(report);
   if (connection && connection.engine_url) {
     try {
@@ -854,6 +1339,7 @@ async function runAgent(repo, args, argv, options = {}) {
     assertCodexProxyApiKey(args);
     const profilePath = writeCodexProfile(connection, args);
     commandToRun = withCostLayersCodexProfile(command);
+    await trackEvent(repo, args, "codex_run", { profile_mode: codexProxyEnabled(args) ? "api" : "chatgpt" }, connection);
     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`);
@@ -863,6 +1349,7 @@ async function runAgent(repo, args, argv, options = {}) {
   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), {
@@ -897,6 +1384,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") {
@@ -916,6 +1404,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") {
@@ -930,6 +1419,7 @@ 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);
+  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`);
@@ -950,24 +1440,24 @@ 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, { preferInvoice: true });
+  const nextArgs = withAutoCodexMode(args);
   if (codexProxyEnabled(nextArgs)) {
-    process.stdout.write(`CostLayers Codex: API invoice mode enabled from ${codexProxyApiKeyEnv(nextArgs)}.\n`);
+    process.stdout.write(`CostLayers Codex: API invoice mode explicitly enabled from ${codexProxyApiKeyEnv(nextArgs)}.\n`);
   } else {
-    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Set ${codexProxyApiKeyEnv(nextArgs)} or pass --api for invoice savings.\n`);
+    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Pass --api to route API-billed provider calls for invoice savings.\n`);
   }
   return start(repo, nextArgs, ["start", "--", ...commandToRun]);
 }
 
 async function savingsTest(repo, args) {
-  const nextArgs = withAutoCodexMode(args, { preferInvoice: true });
+  const nextArgs = withAutoCodexMode({ ...args, api: true }, { forceInvoice: true });
   if (!codexProxyEnabled(nextArgs)) {
     const keyEnv = codexProxyApiKeyEnv(nextArgs);
     process.stderr.write([
       `CostLayers test needs ${keyEnv} for real API invoice savings.`,
       "",
       "Set your OpenAI Platform API key, then rerun:",
-      `  source ~/.config/costlayers/env`,
+      `  export ${keyEnv}=sk-proj-...`,
       `  npx -y ${INSTALL_SPEC} test --email you@example.com`,
       "",
       `For ChatGPT-login metering without invoice savings, run:`,
@@ -979,6 +1469,8 @@ async function savingsTest(repo, args) {
   const prompt = typeof args.prompt === "string"
     ? 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");
@@ -995,14 +1487,20 @@ async function start(repo, args, argv, options = {}) {
   const command = dash >= 0 ? argv.slice(dash + 1) : [];
   const codexTelemetryRun = command.length > 0 && isCodexCommand(command) && !codexProxyEnabled(args);
   if (command.length > 0 && isCodexCommand(command)) assertCodexProxyApiKey(args);
-  init(repo);
+  init(repo, { suppressNext: true });
   process.stdout.write(`Scanning repo: ${repo}\n`);
   const precomputed = scanToFiles(repo, args);
   const { outDir, pack, 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(`Report: ${path.join(outDir, "savings-report.md")}\n`);
   printSavingsSummary(report);
   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`);
@@ -1013,7 +1511,7 @@ async function start(repo, args, argv, options = {}) {
   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`);
+    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 = {
@@ -1035,6 +1533,7 @@ 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`);
@@ -1046,18 +1545,33 @@ async function start(repo, args, argv, options = {}) {
   if (command.length > 0) {
     return runAgent(repo, args, argv, { skipSetup: true, precomputed, returnStatus: options.returnStatus });
   }
-  process.stdout.write(`\nNext options:\n`);
-  process.stdout.write(`  Use gateway URL in your model client: ${gatewayBaseUrl}\n`);
-  process.stdout.write(`  Run Codex: npx -y ${INSTALL_SPEC} codex --email you@example.com\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");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "costlayers",
-  "version": "0.8.16",
+  "version": "0.8.20",
   "description": "CostLayers cost control for AI coding agents. Build compact repo context packs, gateway reports, and savings dashboards.",
   "bin": {
     "agentspend": "bin/agentspend.js",
@@ -8,6 +8,10 @@
   },
   "type": "commonjs",
   "license": "UNLICENSED",
+  "homepage": "https://costlayers.com",
+  "bugs": {
+    "url": "mailto:rishabh@costlayers.com"
+  },
   "private": false,
   "engines": {
     "node": ">=18"