ai-spend-agent 0.7.3 → 0.8.1

package/dist/index.js

@@ -4,18 +4,38 @@ import { mkdir, readFile, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { analyzeSpend, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, loadLocalAgentUsage, loadLocalAgentFinancialUsage, localAgentFormatDescriptors, localAgentFormatLabel, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, readActivitySnapshot, recordActivitySnapshotRefreshFailure, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
+import { analyzeSpend, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, summarizeProviderFinancials, providerFinancialCompleteness, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, loadLocalAgentUsage, loadLocalAgentFinancialUsage, localAgentFormatDescriptors, localAgentFormatLabel, localAgentFormatSupports, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createProviderConnection, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, applyProviderContractGate, applyProviderContractGateToSourceRegistry, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, readActivitySnapshot, recordActivitySnapshotRefreshFailure, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
 import { StatuslineInstallerError, installClaudeStatusline, uninstallClaudeStatusline } from "./statuslineInstaller.js";
 import { readStatuslineCache, renderStatusline } from "./statuslineRuntime.js";
 import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions } from "@agent-finops/report";
 export async function runCli(argv = process.argv.slice(2), runtime = {}) {
-    if (argv.includes("--version") || argv.includes("-v")) {
+    if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
         return ok(await cliVersion());
     }
     if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
         return ok(helpText());
     }
     const args = parseArgs(argv);
+    if (args.parseErrors.length > 0) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                ...args.parseErrors.map((error) => `Invalid arguments: ${sanitizeSecretishError(error)}`),
+                "Run `npx aibill --help` to see supported commands and flags."
+            ].join("\n")
+        };
+    }
+    if (args.json && args.command !== "context" && args.command !== "context-health" && args.command !== "glance") {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                "--json is not available for the main receipt yet; no text receipt was substituted.",
+                "Use `npx aibill context --json` for the canonical Context Health object or `npx aibill glance` for the canonical Glance snapshot."
+            ].join("\n")
+        };
+    }
     if (args.groupByInvalid) {
         return {
             exitCode: 1,
@@ -23,10 +43,8 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
             stderr: `--group-by needs a dimension: ${groupByDimensions.join("|")}\nexample: npx aibill --group-by project`
         };
     }
-    // Zero-key instant demo is the DEFAULT first run. Running `ai-spend-agent`
-    // with no subcommand (or `npx ai-spend-agent`), or with only flags such as
-    // `--group-by agent`, lands the wow immediately on sample / auto-detected
-    // local data — no credential required.
+    // Running with no subcommand reads only evidence available on this machine.
+    // Illustrative records are reachable only through an explicit --sample.
     if (!args.command || args.command.startsWith("--") || args.command === "quickstart" || args.command === "demo") {
         return quickstartCommand(args);
     }
@@ -84,14 +102,24 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
     return {
         exitCode: 1,
         stdout: "",
-        stderr: `Unknown command: ${args.command}\n${helpText()}`
+        stderr: `Unknown command: ${sanitizeSecretishError(args.command)}\n${helpText()}`
     };
 }
 async function quickstartCommand(args) {
     const sinceDays = args.sinceDays ?? 30;
     if (!validSinceDays(sinceDays))
         return invalidSinceDaysResult();
+    if (args.plan && !planOverrideFromFlag(args.plan)) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+        };
+    }
     const { records, mode, warnings, providerCoverage, codexInvocationFiles } = await loadInstantReadData(args);
+    if (records.length === 0) {
+        return noEvidenceResult("receipt", warnings, sinceDays);
+    }
     const summaryRecords = mode === "connected"
         ? selectProviderFinancialHeadlineRecords(records)
         : records;
@@ -100,6 +128,7 @@ async function quickstartCommand(args) {
     // ("which project burns my plan"); demo/connected keep by-model.
     const groupBy = args.groupBy ?? (mode === "local-logs" ? "project" : "model");
     const color = args.noColor ? false : undefined;
+    const outputWidth = terminalOutputWidth();
     // Persona: --plan override wins; otherwise read the plans the coding agents
     // themselves persisted locally (read-only, whitelisted fields, no network).
     let detectedPlans;
@@ -114,7 +143,7 @@ async function quickstartCommand(args) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlans = [override];
@@ -173,12 +202,17 @@ async function quickstartCommand(args) {
         nextSteps,
         deadContext,
         detectedPlans,
+        width: outputWidth,
         // An explicit --group-by is a drill-down question: answer with just the
         // table + window instead of repeating the whole readout.
-        view: args.groupBy ? "breakdown" : "full"
+        view: args.groupBy ? "breakdown" : args.full ? "full" : "compact"
     });
-    const header = [`  ${dataModeBanner(mode)}`, ...warnings.map((warning) => `  ! ${warning}`)].join("\n");
-    return ok(`${header}\n${summaryText}`);
+    const detailedView = Boolean(args.groupBy || args.full);
+    const header = [
+        ...(detailedView ? wrapCliHeader(dataModeBanner(mode, summaryRecords), "  ", outputWidth) : []),
+        ...warnings.flatMap((warning) => wrapCliHeader(warning, "  ! ", outputWidth))
+    ].join("\n");
+    return ok(header ? `${header}\n${summaryText}` : summaryText);
 }
 async function glanceCommand(args) {
     const sinceDays = args.sinceDays ?? 30;
@@ -187,12 +221,14 @@ async function glanceCommand(args) {
     const logs = await loadLocalAgentUsage({
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
         codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
         sinceIso: sinceIsoForDays(sinceDays),
         collectCodexInvocationEvidence: true
     });
+    const glanceCalls = logs.calls.filter((call) => (localAgentFormatSupports(call.agent, "glance")));
     const calls = args.project
-        ? logs.calls.filter((call) => call.project === args.project)
-        : logs.calls;
+        ? glanceCalls.filter((call) => call.project === args.project)
+        : glanceCalls;
     const latestWorkingDirectory = latestObservedWorkingDirectory(calls);
     const contextProjectDir = args.pathExplicit
         ? resolve(args.path)
@@ -204,7 +240,7 @@ async function glanceCommand(args) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlans = [override];
@@ -228,10 +264,12 @@ async function glanceCommand(args) {
         codexInvocationFiles: logs.codexInvocationFiles
     });
     const snapshot = buildUsageGlance(calls, {
-        filesParsed: logs.filesParsed,
-        detectedAgents: logs.agentsDetected,
+        filesParsed: logs.sourceScans
+            .filter((scan) => localAgentFormatSupports(scan.agent, "glance"))
+            .reduce((total, scan) => total + scan.filesParsed, 0),
+        detectedAgents: logs.agentsDetected.filter((agent) => (localAgentFormatSupports(agent, "glance"))),
         detectedPlans,
-        limitCalls: logs.calls,
+        limitCalls: glanceCalls,
         contextHealth
     });
     return ok(JSON.stringify(snapshot));
@@ -244,12 +282,14 @@ async function contextHealthCommand(args) {
     const logs = await loadLocalAgentUsage({
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
         codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
         sinceIso,
         collectCodexInvocationEvidence: true
     });
+    const contextCalls = logs.calls.filter((call) => (localAgentFormatSupports(call.agent, "contextHealth")));
     const calls = args.project
-        ? logs.calls.filter((call) => call.project === args.project)
-        : logs.calls;
+        ? contextCalls.filter((call) => call.project === args.project)
+        : contextCalls;
     const health = await loadContextHealth(calls, {
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
         codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
@@ -320,13 +360,13 @@ function quickstartNextSteps(mode, detected) {
     if (detected.length > 0) {
         const names = detected.map((credential) => `${credential.provider} (${credential.hint})`).join(", ");
         steps.push(`Found local key${detected.length === 1 ? "" : "s"}: ${names}`);
-        steps.push(`npx aibill connect ${detected[0].provider}   add official provider-reported cost (ADMIN/owner key)`);
+        steps.push(`npx aibill connect ${detected[0].provider}   set up the admin connector, then sync provider-reported cost`);
     }
     steps.push(mode === "demo"
         ? "npx aibill report --sample     write a clearly labeled demo Markdown + HTML report"
         : "npx aibill report              write a shareable Markdown + HTML report");
     steps.push("npx aibill --group-by project  see which project has the most observed activity");
-    steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://ai-spend-agent.vercel.app");
+    steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://asktilden.com");
     return steps;
 }
 async function readPersistedSpend(rootPath, options = {}) {
@@ -343,9 +383,12 @@ async function readPersistedSpend(rootPath, options = {}) {
         // tag. A copied/tampered sample must never become connected billing merely
         // because `mode` was changed in JSON.
         const mode = isBundledSampleUsage(parsedRecords) ? "sample" : storedMode;
-        const records = mode === "sample" || mode === undefined
+        const parsedModeRecords = mode === "sample" || mode === undefined
             ? downgradeSampleUsageEvidence(parsedRecords)
             : parsedRecords;
+        const records = mode === "connected_provider"
+            ? applyProviderContractGate(parsedModeRecords)
+            : parsedModeRecords;
         if (spend.checkedAt !== undefined && !validIsoString(spend.checkedAt)) {
             throw new Error("persisted spend checkedAt must be an ISO timestamp");
         }
@@ -410,7 +453,7 @@ async function loadInstantReadData(args) {
         looksConnected &&
         persisted.connectedTrust?.trusted === true) {
         return {
-            records: persisted.records,
+            records: applyProviderContractGate(persisted.records),
             mode: "connected",
             warnings,
             ...(persisted.providerCoverage ? { providerCoverage: persisted.providerCoverage } : {})
@@ -420,13 +463,22 @@ async function loadInstantReadData(args) {
         warnings.push(`${persisted.connectedTrust.message} CLI: run \`npx aibill connect <provider>\` or repeat the prior \`npx aibill sync-provider ...\` command. The repository-provided connected totals were ignored.`);
     }
     // Real local agent logs (Claude Code / Codex) beat any sample/legacy state.
-    const logs = await loadLocalAgentUsage({
-        // Env overrides keep tests (and unusual installs) isolated from $HOME.
-        claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
-        sinceIso: sinceIsoForDays(args.sinceDays ?? 30),
-        collectCodexInvocationEvidence: true
-    }).catch(() => undefined);
+    let logs;
+    try {
+        logs = await loadLocalAgentUsage({
+            // Env overrides keep tests (and unusual installs) isolated from $HOME.
+            claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
+            sinceIso: sinceIsoForDays(args.sinceDays ?? 30),
+            collectCodexInvocationEvidence: true
+        });
+    }
+    catch {
+        // A failed read is not the same as an honest empty scan. Keep the compact
+        // result useful without leaking a local path or raw parser exception.
+        warnings.push("Some local agent evidence could not be read; coverage is incomplete.");
+    }
     if (logs && logs.records.length > 0) {
         // Persisted local_logs state (written by report/apply-artifact) is the
         // same data source we just re-read — superseding it silently is correct,
@@ -441,25 +493,99 @@ async function loadInstantReadData(args) {
             codexInvocationFiles: logs.codexInvocationFiles
         };
     }
-    // No real logs. Persisted sample/legacy state may still be shown, but only as
-    // DEMO (never as connected), with a warning when its origin is unknown.
+    const geminiPresence = logs?.sourceScans.find((scan) => scan.agent === "gemini-cli");
+    if (geminiPresence && ((geminiPresence.detectionSignals ?? 0) > 0 || geminiPresence.filesDiscovered > 0)) {
+        warnings.push("Gemini CLI was detected, but no supported chats JSON/JSONL financial evidence was found. No financial rows were created; logs.json is presence-only evidence. Need this coverage? +1 or contribute a synthetic fixture: https://github.com/futurastudio/ai-spend-agent/issues/new?template=provider_or_agent.yml");
+        return {
+            records: [],
+            mode: "local-logs",
+            warnings,
+            codexInvocationFiles: logs?.codexInvocationFiles
+        };
+    }
+    // No real logs. Sample and legacy persisted state must never appear unless
+    // this invocation explicitly opted into --sample.
     if (persisted && persisted.records.length > 0 && persisted.mode !== "connected_provider" && persisted.mode !== "local_logs") {
-        if (persisted.mode === undefined) {
-            warnings.push("Persisted state in .ai-spend-agent/spend.json is from an older format with no data-mode tag — treating it as demo. Run `npx aibill reset`, then re-scan to refresh.");
-        }
-        return { records: persisted.records, mode: "demo", warnings };
+        warnings.push(persisted.mode === "sample"
+            ? "Sample state exists but was not displayed because this run did not include --sample."
+            : "Legacy state with no trustworthy data-mode label was ignored. Run `npx aibill reset`, then collect fresh evidence.");
     }
     if (persisted?.mode === "local_logs") {
         warnings.push("Ignored persisted local-log cache because no current Claude Code/Codex source records were found. Re-run the local agent activity first; repository state alone cannot authorize an Apply action.");
     }
-    // loadSampleUsageData resolves the bundled CSVs relative to the installed
-    // package, so this works from ANY directory (true zero-config).
-    return { records: await loadSampleUsageData(), mode: "demo", warnings };
+    return { records: [], mode: "local-logs", warnings };
+}
+function noEvidenceResult(surface, warnings, sinceDays) {
+    const surfaceLine = surface === "watch"
+        ? "Watch has no financial baseline yet; no zero total or sample activity was recorded."
+        : surface === "report-card"
+            ? "No receipt was written because there is no supported financial evidence to summarize."
+            : `No supported AI usage evidence was found in the last ${sinceDays} days.`;
+    return {
+        exitCode: surface === "receipt" ? 0 : 1,
+        stdout: surface === "receipt"
+            ? [
+                "aibill · local only",
+                "",
+                surfaceLine,
+                "Looked for: Claude Code, Codex, and Gemini CLI local history.",
+                "Nothing was uploaded. No sample data was substituted.",
+                ...warnings.map((warning) => `! ${warning}`),
+                "",
+                "Next",
+                "  npx aibill doctor --sources       see the exact evidence gap and setup paths"
+            ].join("\n")
+            : "",
+        stderr: surface === "receipt"
+            ? ""
+            : [
+                surfaceLine,
+                "Run `npx aibill doctor --sources` to see the exact evidence gap.",
+                "Local evidence: use Claude Code, Codex, or Gemini CLI normally, then retry.",
+                "Provider billing: connect openai, anthropic, cursor, or github-copilot with an admin credential reference.",
+                "For illustrative output only, rerun this command with --sample."
+            ].join("\n")
+    };
+}
+function terminalOutputWidth() {
+    const envColumns = Number(process.env.COLUMNS);
+    const ttyColumns = process.stdout.columns;
+    const requested = Number.isFinite(envColumns) && envColumns > 0
+        ? envColumns
+        : Number.isFinite(ttyColumns) && (ttyColumns ?? 0) > 0
+            ? ttyColumns
+            : 72;
+    return Math.max(40, Math.min(120, Math.floor(requested)));
+}
+function wrapCliHeader(text, prefix, width) {
+    const available = Math.max(12, width - prefix.length);
+    const words = text.trim().split(/\s+/u);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (!current) {
+            current = word;
+            continue;
+        }
+        if (`${current} ${word}`.length <= available) {
+            current += ` ${word}`;
+            continue;
+        }
+        lines.push(current);
+        current = word;
+    }
+    if (current)
+        lines.push(current);
+    const continuationPrefix = " ".repeat(prefix.length);
+    return lines.map((line, index) => `${index === 0 ? prefix : continuationPrefix}${line}`);
 }
 /** A one-line, unmissable banner telling the user which data they're seeing. */
-function dataModeBanner(mode) {
-    if (mode === "local-logs")
-        return "DATA MODE: your local agent logs (estimated at API-equivalent rates)";
+function dataModeBanner(mode, records) {
+    if (mode === "local-logs") {
+        return records.some((record) => typeof record.amountUsd === "number")
+            ? "DATA MODE: your local agent logs (estimated at API-equivalent rates)"
+            : "DATA MODE: local agent evidence (financial value unavailable; no demo sample substituted)";
+    }
     if (mode === "connected")
         return "DATA MODE: connected provider billing";
     return "DATA MODE: demo sample (illustrative — not your real spend)";
@@ -479,12 +605,18 @@ async function doctorCommand(args) {
         : "no state";
     const logs = await loadLocalAgentUsage({
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR
     }).catch(() => undefined);
     const detected = logs?.agentsDetected ?? [];
     const claudeFound = detected.includes("claude-code");
     const codexFound = detected.includes("codex");
-    const hasLogs = claudeFound || codexFound;
+    const geminiScan = logs?.sourceScans.find((scan) => scan.agent === "gemini-cli");
+    const geminiFinancialFound = detected.includes("gemini-cli");
+    const geminiPresenceFound = Boolean(geminiScan && ((geminiScan.detectionSignals ?? 0) > 0 || geminiScan.filesDiscovered > 0));
+    const geminiFound = geminiFinancialFound || geminiPresenceFound;
+    const hasFinancialLogs = claudeFound || codexFound || geminiFinancialFound;
+    const hasLocalSource = hasFinancialLogs || geminiPresenceFound;
     const detection = await detectLocalCredentials({
         cwd: rootPath,
         home: process.env.AI_SPEND_CLAUDE_HOME_DIR
@@ -505,15 +637,20 @@ async function doctorCommand(args) {
     if (persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === false) {
         warnings.push(`${persisted.connectedTrust.message} Run \`npx aibill connect <provider>\` or repeat the prior \`npx aibill sync-provider ...\` command.`);
     }
-    if (!hasLogs)
-        warnings.push("no real Claude Code / Codex logs found — a first run here will show DEMO sample data");
+    if (geminiPresenceFound && !geminiFinancialFound) {
+        warnings.push("Gemini CLI detected, but no supported chats JSON/JSONL financial evidence was found. No financial rows were created; logs.json is presence-only evidence. Need this coverage? +1 or contribute a synthetic fixture: https://github.com/futurastudio/ai-spend-agent/issues/new?template=provider_or_agent.yml");
+    }
+    if (!hasLocalSource)
+        warnings.push("no supported Claude Code, Codex, or Gemini CLI session evidence found — the default receipt will remain empty; use --sample only for the labeled demo");
     if (providerRefs.length === 0)
-        warnings.push("no provider admin keys detected — connect OpenAI/Anthropic to add official provider-reported cost (local logs stay API-equivalent estimates)");
+        warnings.push("no provider admin keys detected — set up and sync an OpenAI/Anthropic admin connector for provider-reported cost (local logs stay API-equivalent estimates)");
     const predictedMode = connectedStateTrusted
         ? "connected provider billing"
-        : hasLogs
+        : hasFinancialLogs
             ? "your local agent logs (estimated at API-equivalent rates)"
-            : "demo sample (illustrative)";
+            : geminiPresenceFound
+                ? "local Gemini CLI presence only (financial evidence unavailable; no sample substituted)"
+                : "no supported evidence yet (no sample substituted)";
     const lines = [
         "aibill doctor",
         `node version: ${process.version}`,
@@ -524,6 +661,11 @@ async function doctorCommand(args) {
         `state mode: ${stateMode}`,
         `Claude Code logs: ${claudeFound ? "found" : "not found"}`,
         `Codex logs: ${codexFound ? "found" : "not found"}`,
+        `Gemini CLI sessions: ${geminiFinancialFound
+            ? "found"
+            : geminiPresenceFound
+                ? "detected, but no supported chats financial rows found"
+                : "not found"}`,
         `provider env references: ${providerRefs.length > 0 ? providerRefs.join(", ") : "none detected"}`,
         `subscription plans: ${planLine}`,
         "redaction policy: secrets are never printed or persisted",
@@ -549,7 +691,8 @@ async function doctorSourcesCommand(args) {
     try {
         localLogs = await loadLocalAgentUsage({
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR
         });
     }
     catch (error) {
@@ -659,14 +802,18 @@ function localFinancialEvidenceNote(records, evidence, scan) {
         if (scan.directoryStatus === "unreadable") {
             return "The local transcript path could not be read; absence of usage cannot be confirmed.";
         }
+        if (scan.agent === "gemini-cli" && (scan.detectionSignals ?? 0) > 0 &&
+            scan.filesDiscovered === 0) {
+            return "Gemini CLI detected, but no supported chats JSON/JSONL financial evidence was found. logs.json is presence-only evidence; zero financial rows were created. Need this coverage? +1 or contribute a synthetic fixture: https://github.com/futurastudio/ai-spend-agent/issues/new?template=provider_or_agent.yml";
+        }
         if (scan.filesDiscovered === 0) {
-            return "The local transcript directory was readable, but no JSONL files were found.";
+            return "The local transcript directory was readable, but no supported session files were found.";
         }
         if (scan.unreadableFiles > 0) {
             return `${scan.filesDiscovered} transcript file(s) were found, but ${scan.unreadableFiles} could not be read; absence of usage cannot be confirmed.`;
         }
         if (scan.malformedLines > 0) {
-            return `${scan.filesDiscovered} transcript file(s) were found, but no valid usage rows were parsed; ${scan.malformedLines} malformed JSONL line(s) were skipped.`;
+            return `${scan.filesDiscovered} transcript file(s) were found, but no valid usage rows were parsed; ${scan.malformedLines} malformed session record(s) were skipped.`;
         }
         return `${scan.filesDiscovered} transcript file(s) were found, but no supported usage rows were observed.`;
     }
@@ -697,9 +844,13 @@ function localFinancialEvidenceNote(records, evidence, scan) {
 function localAgentDiagnosticSummary(diagnostics) {
     const relevant = diagnostics.filter((diagnostic) => diagnostic.code !== "directory_missing");
     const unsupported = relevant.filter((diagnostic) => diagnostic.code === "unsupported_token_shape");
-    const malformed = relevant.filter((diagnostic) => diagnostic.code === "malformed_jsonl");
+    const malformed = relevant.filter((diagnostic) => (diagnostic.code === "malformed_jsonl" || diagnostic.code === "malformed_session_file"));
     const messages = [...new Set(relevant
-            .filter((diagnostic) => !["unsupported_token_shape", "malformed_jsonl"].includes(diagnostic.code))
+            .filter((diagnostic) => ![
+            "unsupported_token_shape",
+            "malformed_jsonl",
+            "malformed_session_file"
+        ].includes(diagnostic.code))
             .map((diagnostic) => diagnostic.message))];
     const unsupportedCount = unsupported
         .reduce((total, diagnostic) => total + diagnostic.count, 0);
@@ -709,7 +860,7 @@ function localAgentDiagnosticSummary(diagnostics) {
     const malformedCount = malformed
         .reduce((total, diagnostic) => total + diagnostic.count, 0);
     if (malformedCount > 0) {
-        messages.push(`${malformedCount} malformed JSONL line(s) were skipped in ${localAgentFormatLabel(malformed[0].agent)} transcripts.`);
+        messages.push(`${malformedCount} malformed session record(s) were skipped in ${localAgentFormatLabel(malformed[0].agent)} transcripts.`);
     }
     return messages.length > 0 ? messages.join(" ") : undefined;
 }
@@ -981,7 +1132,7 @@ async function resetCommand(args) {
             "aibill reset",
             `path: ${rootPath}`,
             "nothing to clear (no persisted spend state found)",
-            "next run will re-read your real local agent logs (or demo sample if none)."
+            "next run will re-read your real local agent logs; no sample is substituted without --sample."
         ].join("\n"));
     }
     // Clear derived spend state so a prior `scan --sample` (or stale provider
@@ -1001,7 +1152,7 @@ async function resetCommand(args) {
         "aibill reset",
         `path: ${rootPath}`,
         removed.length > 0 ? `cleared: ${removed.join(", ")}` : "nothing to clear (no persisted spend state found)",
-        "next run will re-read your real local agent logs (or demo sample if none)."
+        "next run will re-read your real local agent logs; no sample is substituted without --sample."
     ].join("\n"));
 }
 async function statuslineCommand(args, runtime) {
@@ -1117,7 +1268,7 @@ async function initCommand(args, runtime = {}) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlanOverride = [override];
@@ -1210,6 +1361,7 @@ async function collectAndPublishActivitySnapshot(input) {
         logs = await loadLocalAgentFinancialUsage({
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
             codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
             sinceIso: sinceIsoForDays(30, asOf)
         });
     }
@@ -1222,13 +1374,14 @@ async function collectAndPublishActivitySnapshot(input) {
     const persisted = persistedResult.persisted;
     const trustedProviderRecords = persisted?.mode === "connected_provider" &&
         persisted.connectedTrust?.trusted === true
-        ? selectProviderFinancialHeadlineRecords(persisted.records)
+        ? selectProviderFinancialHeadlineRecords(applyProviderContractGate(persisted.records))
         : [];
     let activitySnapshot;
     let cacheStatus;
+    const statuslineSourceScans = logs?.sourceScans.filter((scan) => (localAgentFormatSupports(scan.agent, "statuslineSnapshot"))) ?? [];
     const structuredSourceFailure = logs !== undefined &&
-        logs.sourceScans.some((scan) => scan.directoryStatus === "unreadable") &&
-        !logs.sourceScans.some((scan) => scan.directoryStatus === "readable");
+        statuslineSourceScans.some((scan) => scan.directoryStatus === "unreadable") &&
+        !statuslineSourceScans.some((scan) => scan.directoryStatus === "readable");
     if (logs && !structuredSourceFailure) {
         let refreshErrorCode = "invalid_evidence";
         try {
@@ -1298,7 +1451,7 @@ async function refreshStatuslineCommand(args, runtime) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlanOverride = [override];
@@ -1516,13 +1669,18 @@ function activitySnapshotProvider(provider) {
 function formatInitReceipt(input) {
     const records = input.logs?.records ?? [];
     const pricedRecords = records.filter((record) => typeof record.amountUsd === "number");
+    const registryOnlyLines = initRegistryOnlyFinancialLines(records);
     const sourceFailures = (input.logs?.sourceScans ?? []).some((scan) => scan.directoryStatus === "unreadable") ||
         (input.logs?.diagnostics ?? []).some((diagnostic) => diagnostic.severity === "error");
-    const receiptLines = input.scanError || sourceFailures && records.length === 0
+    const snapshotLines = input.scanError || sourceFailures && records.length === 0
         ? ["API-equivalent usage value: unavailable — the local scan could not prove an empty result"]
         : input.activitySnapshot
             ? initApiEquivalentWindowLines(input.activitySnapshot)
             : ["API-equivalent usage value: unavailable — no snapshot was produced"];
+    const receiptLines = registryOnlyLines.length > 0 &&
+        input.activitySnapshot?.mode === "empty" && !input.scanError
+        ? registryOnlyLines
+        : [...snapshotLines, ...registryOnlyLines];
     const planLine = input.detectedPlans.length > 0
         ? input.detectedPlans.map((plan) => {
             const known = plan.planId ?? "unrecognized plan";
@@ -1536,7 +1694,10 @@ function formatInitReceipt(input) {
         const validation = scan.jsonlValidationCoverage === "financial_events_only"
             ? "; financial-event JSONL validation only"
             : "";
-        return `  ${scan.agent}: ${scan.directoryStatus}; ${scan.filesParsed}/${scan.filesDiscovered} files parsed; ${priced}/${agentRecords.length} rows priced${skipped > 0 ? `; ${skipped} old files skipped` : ""}${validation}`;
+        const detection = (scan.detectionSignals ?? 0) > 0
+            ? `; ${scan.detectionSignals} presence-only signal(s)`
+            : "";
+        return `  ${scan.agent}: ${scan.directoryStatus}; ${scan.filesParsed}/${scan.filesDiscovered} files parsed; ${priced}/${agentRecords.length} rows priced${detection}${skipped > 0 ? `; ${skipped} old files skipped` : ""}${validation}`;
     });
     const diagnosticLines = (input.logs?.diagnostics ?? [])
         .filter((diagnostic) => diagnostic.code !== "directory_missing")
@@ -1545,7 +1706,7 @@ function formatInitReceipt(input) {
     return [
         "aibill init",
         `state project: ${sanitizeSecretishError(basename(input.rootPath))}`,
-        "local usage scope: all Claude Code + Codex activity on this machine (last 30 days)",
+        "local usage scope: supported Claude Code, Codex, and Gemini CLI financial evidence on this machine (last 30 days)",
         "provider scope: trusted connected billing from this state project only (shown separately)",
         "",
         "FIRST RECEIPT · API-equivalent usage value · last 30 days",
@@ -1565,6 +1726,25 @@ function formatInitReceipt(input) {
         "next: npx aibill doctor --sources"
     ].filter((line) => line !== "").join("\n");
 }
+function initRegistryOnlyFinancialLines(records) {
+    const lines = [];
+    for (const descriptor of localAgentFormatDescriptors) {
+        if (descriptor.capabilities.statuslineSnapshot)
+            continue;
+        const sourceRecords = records.filter((record) => record.agentId === descriptor.id);
+        if (sourceRecords.length === 0)
+            continue;
+        const priced = sourceRecords.filter((record) => typeof record.amountUsd === "number");
+        if (priced.length === 0) {
+            lines.push(`${descriptor.id} API-equivalent value: unavailable — ${sourceRecords.length} observed row(s) lacked complete token components or a supported model price`);
+            continue;
+        }
+        const amount = analyzeSpend(priced).totalUsd;
+        const unpriced = sourceRecords.length - priced.length;
+        lines.push(`${descriptor.id} experimental value: ~${formatOptionalUsd(amount)} 30d (API-equivalent; fixture-verified; not billed spend${unpriced > 0 ? `; ${unpriced} row(s) unpriced` : ""})`);
+    }
+    return lines;
+}
 function formatInitProviderEvidence(input) {
     const windowStart = input.asOf.getTime() - 30 * 24 * 60 * 60 * 1_000;
     const inWindow = input.trustedProviderRecords.filter((record) => {
@@ -1629,7 +1809,7 @@ function initApiEquivalentWindowLines(snapshot) {
                 agent.unsupportedUsageSnapshots === 0 &&
                 agent.jsonlValidationCoverage === "complete");
         return [completeZero
-                ? "API-equivalent value: ~$0.00 1d · ~$0.00 7d · ~$0.00 30d (estimated value; not billed spend)"
+                ? "API-equivalent usage value: unavailable — no priced evidence was observed in readable local sources"
                 : "API-equivalent usage value: unavailable — local source coverage is incomplete; no zero total was inferred"];
     }
     if (snapshot.mode === "unresolved" && snapshot.unresolved) {
@@ -1749,7 +1929,7 @@ async function scanCommand(args) {
         const mappings = attributeUsageRecords(records);
         await writeLocalSpendState(stateDir, records, summary, mappings, "sample");
         lines.push(`sample records: ${records.length}`);
-        lines.push(`total spend: $${summary.totalUsd.toFixed(2)}`);
+        lines.push(`total spend: ${formatOptionalUsd(summary.totalUsd)}`);
         lines.push(`attribution mappings: ${mappings.length}`);
     }
     if (discovery.signals.length > 0) {
@@ -1781,6 +1961,9 @@ async function watchCommand(args) {
     while (unbounded || iteration < cycles) {
         const previous = await readOptionalJson(join(stateDir, "watch-latest.json"), null);
         const { summary, snapshot, records, mode } = await runWatchCycle(stateDir, args);
+        if (records.length === 0) {
+            return noEvidenceResult("watch", [], args.sinceDays ?? 30);
+        }
         const deltaHeadline = buildDeltaHeadline(previous, snapshot);
         // Watch's job is DELTAS: render the compact breakdown view per cycle, not
         // the whole diagnose→verify readout again (the quickstart owns that).
@@ -1789,6 +1972,7 @@ async function watchCommand(args) {
             groupBy: args.groupBy ?? "model",
             color: args.noColor ? false : undefined,
             mode: mode === "sample" ? "demo" : mode === "connected_provider" ? "connected" : "local-logs",
+            width: terminalOutputWidth(),
             view: "breakdown"
         });
         const stamped = [
@@ -1836,7 +2020,7 @@ async function runWatchCycle(stateDir, args) {
             // Watch may observe an already trusted provider snapshot, but it may not
             // mint trust from repository-authored provider-records.json or rewrite
             // connected state. Only an explicit provider sync can do that.
-            records = persisted.records;
+            records = applyProviderContractGate(persisted.records);
             mode = "connected_provider";
         }
         else {
@@ -1844,31 +2028,35 @@ async function runWatchCycle(stateDir, args) {
             // never serve a stale snapshot.
             const logs = await loadLocalAgentUsage({
                 claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-                codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+                codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+                geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR
             }).catch(() => undefined);
             if (logs && logs.records.length > 0) {
                 records = logs.records;
                 mode = "local_logs";
             }
             else {
-                records = await loadSampleUsageData();
-                mode = "sample";
+                records = [];
+                mode = "local_logs";
             }
         }
     }
     const headlineRecords = mode === "connected_provider"
-        ? selectProviderFinancialHeadlineRecords(records)
+        ? selectProviderFinancialHeadlineRecords(applyProviderContractGate(records))
         : records;
     const summary = analyzeSpend(headlineRecords);
+    const financialAmountAvailable = headlineRecords.some((record) => typeof record.amountUsd === "number");
     const mappings = attributeUsageRecords(records);
     if (mode !== "connected_provider") {
         await writeLocalSpendState(stateDir, records, summary, mappings, mode);
     }
     const snapshot = {
         capturedAt: new Date().toISOString(),
-        totalUsd: summary.totalUsd,
+        totalUsd: financialAmountAvailable ? summary.totalUsd : null,
         recordCount: summary.recordCount,
-        byModel: summary.byModel.map((entry) => ({ key: entry.key, amountUsd: entry.amountUsd }))
+        byModel: financialAmountAvailable
+            ? summary.byModel.map((entry) => ({ key: entry.key, amountUsd: entry.amountUsd }))
+            : []
     };
     // Append to the rolling history and persist the latest snapshot for the next run.
     const history = await readOptionalJson(join(stateDir, "watch-history.json"), []);
@@ -1878,24 +2066,35 @@ async function runWatchCycle(stateDir, args) {
         timestamp: snapshot.capturedAt,
         action: "scan_completed",
         sourceId: "watch",
-        detail: `Watch cycle captured ${snapshot.recordCount} records totaling $${snapshot.totalUsd.toFixed(2)}.`
+        detail: snapshot.totalUsd === null
+            ? `Watch cycle captured ${snapshot.recordCount} records with no priced financial evidence; total unavailable.`
+            : `Watch cycle captured ${snapshot.recordCount} records totaling ${formatOptionalUsd(snapshot.totalUsd)}.`
     });
     return { summary, snapshot, records: headlineRecords, mode };
 }
 function buildDeltaHeadline(previous, current) {
     if (!previous) {
-        return `First watch snapshot. Baseline AI spend is $${current.totalUsd.toFixed(2)} across ${current.recordCount} charges. Future cycles will report what changed.`;
+        if (current.totalUsd === null) {
+            return `First watch snapshot. Financial baseline is unavailable across ${current.recordCount} records; missing/null is not zero. Future priced cycles will establish a numeric baseline.`;
+        }
+        return `First watch snapshot. Baseline AI spend is ${formatOptionalUsd(current.totalUsd)} across ${current.recordCount} charges. Future cycles will report what changed.`;
+    }
+    if (current.totalUsd === null) {
+        return `Financial evidence is unavailable across ${current.recordCount} records; missing/null is not zero and no numeric delta was calculated.`;
+    }
+    if (previous.totalUsd === null) {
+        return `A priced financial baseline is now available at ${formatOptionalUsd(current.totalUsd)} across ${current.recordCount} records. The prior snapshot was unavailable, so no numeric delta was calculated.`;
     }
     const deltaUsd = roundMoneyCli(current.totalUsd - previous.totalUsd);
     const lines = [];
-    if (Math.abs(deltaUsd) < 0.01) {
-        lines.push(`No change since the last check: AI spend is holding at $${current.totalUsd.toFixed(2)}.`);
+    if (deltaUsd === 0) {
+        lines.push(`No change since the last check: AI spend is holding at ${formatOptionalUsd(current.totalUsd)}.`);
     }
     else {
         const direction = deltaUsd > 0 ? "UP" : "DOWN";
         const percent = previous.totalUsd > 0 ? Math.round((deltaUsd / previous.totalUsd) * 100) : 100;
-        lines.push(`Spend is ${direction} $${Math.abs(deltaUsd).toFixed(2)} (${Math.abs(percent)}%) since the last check — ` +
-            `from $${previous.totalUsd.toFixed(2)} to $${current.totalUsd.toFixed(2)}.`);
+        lines.push(`Spend is ${direction} ${formatOptionalUsd(Math.abs(deltaUsd))} (${Math.abs(percent)}%) since the last check — ` +
+            `from ${formatOptionalUsd(previous.totalUsd)} to ${formatOptionalUsd(current.totalUsd)}.`);
     }
     // New-model and per-model spike detection versus the previous snapshot.
     const previousModels = new Map(previous.byModel.map((entry) => [entry.key, entry.amountUsd]));
@@ -1904,12 +2103,12 @@ function buildDeltaHeadline(previous, current) {
         const before = previousModels.get(entry.key);
         if (before === undefined) {
             if (entry.amountUsd >= 1) {
-                anomalies.push(`New model "${entry.key}" appeared, already at $${entry.amountUsd.toFixed(2)}.`);
+                anomalies.push(`New model "${entry.key}" appeared, already at ${formatOptionalUsd(entry.amountUsd)}.`);
             }
             continue;
         }
         if (before > 0 && entry.amountUsd - before >= 5 && entry.amountUsd / before >= 1.5) {
-            anomalies.push(`"${entry.key}" jumped from $${before.toFixed(2)} to $${entry.amountUsd.toFixed(2)}.`);
+            anomalies.push(`"${entry.key}" jumped from ${formatOptionalUsd(before)} to ${formatOptionalUsd(entry.amountUsd)}.`);
         }
     }
     if (anomalies.length > 0) {
@@ -1921,7 +2120,7 @@ function sleep(milliseconds) {
     return new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
 }
 function roundMoneyCli(value) {
-    return Math.round(value * 100) / 100;
+    return Math.round(value * 10_000) / 10_000;
 }
 async function addSourceCommand(args) {
     const rootPath = resolve(args.path);
@@ -1982,6 +2181,10 @@ const adminUpgradeProviders = {
     "github-copilot": "requires a GitHub BILLING-ADMIN token (org/enterprise)",
     copilot: "requires a GitHub BILLING-ADMIN token (org/enterprise)"
 };
+const supportedAdminProviders = new Set(["openai", "anthropic", "cursor", "github-copilot"]);
+const providerAliases = {
+    copilot: "github-copilot"
+};
 const providerAdminEnvHint = {
     openai: "env:OPENAI_ADMIN_KEY",
     anthropic: "env:ANTHROPIC_ADMIN_KEY",
@@ -1989,10 +2192,20 @@ const providerAdminEnvHint = {
     "github-copilot": "env:GITHUB_TOKEN",
     copilot: "env:GITHUB_TOKEN"
 };
+function providerSyncSetupCommand(provider, adminRef) {
+    if (provider === "cursor") {
+        return `npx aibill sync-provider --provider cursor --auth-reference ${adminRef} --account-id <team-label>`;
+    }
+    if (provider === "github-copilot") {
+        return `npx aibill sync-provider --provider github-copilot --auth-reference ${adminRef} --org <organization>`;
+    }
+    return `npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`;
+}
 async function connectCommand(args) {
     const rootPath = resolve(args.path);
     const stateDir = join(rootPath, ".ai-spend-agent");
-    const provider = args.provider ?? "unknown";
+    const requestedProvider = (args.provider ?? "unknown").trim().toLowerCase();
+    const provider = providerAliases[requestedProvider] ?? requestedProvider;
     if (!provider || provider === "unknown") {
         return {
             exitCode: 1,
@@ -2008,6 +2221,20 @@ async function connectCommand(args) {
         };
     }
     const type = args.sourceType ?? "provider_api";
+    if (!supportedAdminProviders.has(provider) || type !== "provider_api") {
+        const reason = !supportedAdminProviders.has(provider)
+            ? `connect does not implement provider "${sanitizeSecretishError(requestedProvider)}".`
+            : `connect supports provider_api only; received "${sanitizeSecretishError(type)}".`;
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                reason,
+                "Supported admin connectors: openai, anthropic, cursor, github-copilot.",
+                "For an approved file/export boundary, use `npx aibill add-source` instead."
+            ].join("\n")
+        };
+    }
     const registry = await readSourceRegistry(stateDir, rootPath);
     const source = createProviderConnectorStub(provider, type);
     const nextRegistry = addApprovedSource(registry, source);
@@ -2034,7 +2261,7 @@ async function connectCommand(args) {
         `boundary approval: ${source.boundaryApproval}`,
         `validation coverage: ${source.validationCoverage}`,
         `financial evidence: ${source.financialEvidence}`,
-        "secrets: no raw secrets stored; we only reference a local env var such as env:OPENAI_ADMIN_KEY"
+        `secrets: no raw secrets stored; we only reference a local env var such as ${providerAdminEnvHint[provider] ?? "env:YOUR_ADMIN_KEY"}`
     ];
     if (selfServeProviders.has(provider)) {
         lines.push("tier: self-serve — an org owner can enable this in ~2 minutes");
@@ -2048,19 +2275,19 @@ async function connectCommand(args) {
         lines.push(`auto-detected: a ${provider} key in ${detected.reference} (${detected.hint}) from ${describeOrigin(detected)}`);
         if (detected.isLikelyAdminKey) {
             const adminRef = providerAdminEnvHint[provider] ?? detected.reference;
-            lines.push(`next: npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`);
+            lines.push(`next: ${providerSyncSetupCommand(provider, adminRef)}`);
         }
         else {
             const adminRef = providerAdminEnvHint[provider] ?? "env:YOUR_ADMIN_KEY";
             lines.push(`this looks like a regular key — for COST data set an admin key in ${adminRef}, then:`);
-            lines.push(`  npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`);
+            lines.push(`  ${providerSyncSetupCommand(provider, adminRef)}`);
         }
     }
     else {
         const adminRef = providerAdminEnvHint[provider] ?? "env:YOUR_ADMIN_KEY";
         lines.push("");
         lines.push(`next: export an admin key reference, e.g. ${adminRef}, then run:`);
-        lines.push(`  npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`);
+        lines.push(`  ${providerSyncSetupCommand(provider, adminRef)}`);
     }
     lines.push(`missing: ${source.fieldsMissing.join(", ")}`);
     return ok(lines.join("\n"));
@@ -2089,17 +2316,62 @@ function describeOrigin(credential) {
 async function syncProviderCommand(args) {
     const rootPath = resolve(args.path);
     const stateDir = join(rootPath, ".ai-spend-agent");
-    if (!args.provider || !args.authReference || !args.startTime) {
+    const requestedProvider = (args.provider ?? "").trim().toLowerCase();
+    const provider = providerAliases[requestedProvider] ?? requestedProvider;
+    if (!provider) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                "sync-provider requires --provider.",
+                "Supported admin connectors: openai, anthropic, cursor, github-copilot."
+            ].join("\n")
+        };
+    }
+    if (!supportedAdminProviders.has(provider)) {
         return {
             exitCode: 1,
             stdout: "",
             stderr: [
-                "sync-provider requires --provider, --auth-reference env:NAME, and --start-time <unix seconds>.",
-                "example:",
-                "  npx aibill sync-provider --provider anthropic --auth-reference env:ANTHROPIC_ADMIN_KEY --start-time 1750000000"
+                `sync-provider does not implement provider "${sanitizeSecretishError(requestedProvider)}".`,
+                "Supported admin connectors: openai, anthropic, cursor, github-copilot."
             ].join("\n")
         };
     }
+    if (!args.authReference) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `sync-provider ${provider} requires --auth-reference env:NAME; raw secrets are not accepted.`
+        };
+    }
+    const usesRequestedTimeBounds = provider === "openai" || provider === "anthropic";
+    if (usesRequestedTimeBounds && args.startTime === undefined) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                `sync-provider ${provider} requires --start-time <unix seconds>; --end-time is optional.`,
+                `example: npx aibill sync-provider --provider ${provider} --auth-reference ${providerAdminEnvHint[provider]} --start-time 1750000000`
+            ].join("\n")
+        };
+    }
+    if (!usesRequestedTimeBounds && (args.startTime !== undefined || args.endTime !== undefined)) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: provider === "cursor"
+                ? "Cursor Admin spend is returned for the provider's current team subscription cycle; --start-time/--end-time are not accepted because the connector cannot enforce them."
+                : "GitHub Copilot returns its latest metrics-report window plus current seat data; --start-time/--end-time are not accepted because the connector cannot enforce them."
+        };
+    }
+    if (provider === "github-copilot" && Boolean(args.org) === Boolean(args.enterprise)) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "GitHub Copilot sync requires exactly one of --org <organization> or --enterprise <enterprise>."
+        };
+    }
     try {
         // A provider sync may merge only a prior connected snapshot whose exact
         // repository bytes have a matching external machine receipt. A cloned
@@ -2111,21 +2383,36 @@ async function syncProviderCommand(args) {
             ? priorSpend
             : undefined;
         const result = await fetchProviderUsageRecords({
-            provider: args.provider,
-            sourceId: `${args.provider}-provider-api`,
+            provider,
+            sourceId: `${provider}-provider-api`,
             authReference: args.authReference,
-            startTime: args.startTime,
+            // Core keeps a single connector input contract. Non-time-bounded
+            // adapters ignore this sentinel and the CLI rejects user-supplied bounds
+            // above so no requested interval can be silently discarded.
+            startTime: usesRequestedTimeBounds ? args.startTime : 0,
             endTime: args.endTime,
             org: args.org,
             enterprise: args.enterprise,
             accountId: args.accountId
         });
-        const records = [
+        const syncedRecords = applyProviderContractGate(result.records);
+        const syncedFinancials = summarizeProviderFinancials(syncedRecords);
+        const syncedCompleteness = providerFinancialCompleteness(syncedRecords, result.coverage);
+        const syncedSource = createProviderConnection({
+            provider: result.provider,
+            sourceId: result.source.id,
+            authReference: args.authReference,
+            verifiedRecordCount: syncedRecords.length,
+            totalUsd: syncedFinancials.headlineUsd,
+            completeness: syncedCompleteness,
+            fetchedAt: new Date(result.fetchedAt)
+        });
+        const records = applyProviderContractGate([
             ...(trustedPrior?.records ?? []).filter((record) => record.source.provider !== result.provider),
-            ...result.records
-        ].sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+            ...syncedRecords
+        ]).sort((left, right) => left.timestamp.localeCompare(right.timestamp));
         const registry = await readSourceRegistry(stateDir, rootPath);
-        const nextRegistry = addApprovedSource(registry, result.source);
+        const nextRegistry = addApprovedSource(registry, syncedSource);
         const headlineRecords = selectProviderFinancialHeadlineRecords(records);
         const summary = analyzeSpend(headlineRecords);
         const mappings = attributeUsageRecords(records);
@@ -2139,7 +2426,7 @@ async function syncProviderCommand(args) {
         };
         const financialsByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "financialsByProvider"),
-            [result.provider]: result.financials
+            [result.provider]: syncedFinancials
         };
         const checkedAtByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "checkedAtByProvider"),
@@ -2160,10 +2447,10 @@ async function syncProviderCommand(args) {
         await writeJson(join(stateDir, "provider-records.json"), {
             provider: result.provider,
             fetchedAt: result.fetchedAt,
-            completeness: result.completeness,
+            completeness: syncedCompleteness,
             coverage: result.coverage,
-            financials: result.financials,
-            sourceId: result.source.id,
+            financials: syncedFinancials,
+            sourceId: syncedSource.id,
             records,
             qa: result.qa,
             qaByProvider,
@@ -2189,31 +2476,36 @@ async function syncProviderCommand(args) {
         await appendAuditEvent(stateDir, {
             timestamp: result.fetchedAt,
             action: "source_scanned",
-            sourceId: result.source.id,
+            sourceId: syncedSource.id,
             detail: `${args.provider} provider connector synced ${result.records.length} evidence records with ${result.coverage} coverage. Auth reference only; no raw secrets stored.`
         });
         await writeConnectedSpendTrustReceipt(rootPath, await readSafeStateText(stateDir, "spend.json"), { sourceRegistryContents: await readSafeStateText(stateDir, "sources.json") });
         return ok([
             "aibill sync-provider",
             `provider: ${result.provider}`,
-            `source: ${result.source.id}`,
-            `boundary approval: ${result.source.boundaryApproval}`,
-            `validation coverage: ${result.source.validationCoverage}`,
-            `financial evidence: ${result.source.financialEvidence}`,
+            `source: ${syncedSource.id}`,
+            `boundary approval: ${syncedSource.boundaryApproval}`,
+            `validation coverage: ${syncedSource.validationCoverage}`,
+            `financial evidence: ${syncedSource.financialEvidence}`,
             `coverage: ${result.coverage}`,
             `records fetched: ${result.records.length}`,
-            `headline basis: ${result.financials.headlineBasis}`,
-            `synced provider headline: ${formatOptionalUsd(result.financials.headlineUsd)}`,
+            provider === "cursor"
+                ? "source window: current team subscription cycle returned by Cursor"
+                : provider === "github-copilot"
+                    ? "source window: latest Copilot metrics-report window plus current seat data"
+                    : `source window: requested from ${new Date(args.startTime * 1_000).toISOString()}${args.endTime === undefined ? " through provider current time" : ` through ${new Date(args.endTime * 1_000).toISOString()}`}`,
+            `headline basis: ${syncedFinancials.headlineBasis}`,
+            `synced provider headline: ${formatOptionalUsd(syncedFinancials.headlineUsd)}`,
             `combined headline spend: ${selectProviderFinancialHeadlineRecords(records).some((record) => typeof record.amountUsd === "number") ? formatOptionalUsd(summary.totalUsd) : "unavailable"}`,
-            ...(result.financials.apiEquivalentEstimatedUsd !== null
-                ? [`API-equivalent estimate (kept separate): $${result.financials.apiEquivalentEstimatedUsd.toFixed(2)}`]
+            ...(syncedFinancials.apiEquivalentEstimatedUsd !== null
+                ? [`API-equivalent estimate (kept separate): ${formatOptionalUsd(syncedFinancials.apiEquivalentEstimatedUsd)}`]
                 : []),
             "auth: reference-only; raw secrets were not persisted or printed"
         ].join("\n"));
     }
     catch (error) {
         const sanitizedError = sanitizeSecretishError(error instanceof Error ? error.message : String(error), args.authReference);
-        await recordProviderSourceAttempt(stateDir, args.provider, new Date().toISOString(), sanitizedError).catch(() => {
+        await recordProviderSourceAttempt(stateDir, provider, new Date().toISOString(), sanitizedError).catch(() => {
             // Source-status state is diagnostic only. Do not hide the provider's
             // real error if derived-state persistence is unavailable.
         });
@@ -2323,8 +2615,11 @@ async function reportCommand(args) {
             `verification plan: ${artifactPaths.verificationPlan}`,
             `demo package: ${artifactPaths.demoPackage}`,
             reportInput.dataMode === "sample"
-                ? `DEMO SAMPLE · illustrative cost/value evidence total: $${reportInput.summary.totalUsd.toFixed(2)} · not user data`
-                : `cost/value evidence total: $${reportInput.summary.totalUsd.toFixed(2)}`,
+                ? `DEMO SAMPLE · illustrative cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)} · not user data`
+                : reportInput.dataMode === "connected_provider" &&
+                    !(reportInput.allRecords ?? reportInput.providerRecords ?? []).some((record) => typeof record.amountUsd === "number")
+                    ? "cost/value evidence total: Unavailable · no priced financial evidence; missing/null is not zero"
+                    : `cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)}`,
             "privacy: report rendered locally with no aibill telemetry; only explicit sync-provider contacts the selected provider",
             "",
             "next:",
@@ -2339,7 +2634,7 @@ async function reportCommand(args) {
         return {
             exitCode: 1,
             stdout: "",
-            stderr: `Couldn't build a report: ${error instanceof Error ? error.message : String(error)}`
+            stderr: `Couldn't build a report: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`
         };
     }
 }
@@ -2363,7 +2658,10 @@ async function reportCardCommand(args) {
         // would reject a harmless receipt written from the user's home directory.
         // Output still goes through the safe-write/symlink checks below.
         const rootPath = args.sample ? resolve(args.path) : await resolveSafeScanRoot(args.path);
-        const { records, mode, providerCoverage } = await loadInstantReadData(args);
+        const { records, mode, providerCoverage, warnings } = await loadInstantReadData(args);
+        if (records.length === 0) {
+            return noEvidenceResult("report-card", warnings, args.sinceDays ?? 30);
+        }
         const headlineRecords = mode === "connected"
             ? selectProviderFinancialHeadlineRecords(records)
             : records;
@@ -2403,7 +2701,7 @@ async function reportCardCommand(args) {
         return {
             exitCode: 1,
             stdout: "",
-            stderr: `Couldn't write the report card: ${error instanceof Error ? error.message : String(error)}`
+            stderr: `Couldn't write the report card: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`
         };
     }
 }
@@ -2437,6 +2735,13 @@ async function applyArtifactCommand(args) {
                 codingPrompt.trimEnd()
             ].join("\n"));
         }
+        const noCandidateGuidance = codingPrompt.includes("NO SCOPED CHANGE CANDIDATE")
+            ? [
+                "",
+                "No scoped change is supported yet. Collect the missing source evidence instead of guessing:",
+                ...applyEvidenceAcquisitionLines(reportInput)
+            ]
+            : [];
         return ok([
             "aibill apply-artifact",
             `path: ${rootPath}`,
@@ -2445,6 +2750,7 @@ async function applyArtifactCommand(args) {
             `verification plan: ${artifactPaths.verificationPlan}`,
             `demo package: ${artifactPaths.demoPackage}`,
             "safety: generated artifacts only; no external systems changed",
+            ...noCandidateGuidance,
             "",
             `──── copy everything below into Claude Code / Codex (also saved at ${artifactPaths.codingPrompt}) ────`,
             "",
@@ -2455,10 +2761,35 @@ async function applyArtifactCommand(args) {
         return {
             exitCode: 1,
             stdout: "",
-            stderr: `Couldn't build apply artifacts: ${error instanceof Error ? error.message : String(error)}`
+            stderr: [
+                `Couldn't build apply artifacts: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`,
+                "Collect evidence, then retry Apply:",
+                "- Claude Code / Codex / Gemini CLI: use the agent normally so supported local history exists.",
+                "- OpenAI / Anthropic / Cursor / GitHub Copilot: run `npx aibill connect <provider>` with an admin credential reference.",
+                "- Diagnose the exact gap: `npx aibill doctor --sources`.",
+                "- Demo only: `npx aibill apply --sample` (non-executable)."
+            ].join("\n")
         };
     }
 }
+function applyEvidenceAcquisitionLines(input) {
+    const records = input.allRecords ?? input.providerRecords ?? [];
+    const providers = new Set(records.map((record) => record.source.provider));
+    const lines = [];
+    if (providers.has("anthropic") || providers.has("openai") || input.dataMode === "local_logs") {
+        lines.push("- Local coding agents: run `npx aibill context --json` after comparable Claude Code/Codex sessions to inspect action-capable context evidence.");
+    }
+    if (providers.has("gemini") || providers.has("gemini-cli")) {
+        lines.push("- Gemini CLI: current chat evidence is financial-only; unsupported context/action evidence remains missing.");
+    }
+    if (input.dataMode === "connected_provider") {
+        lines.push("- Provider billing: sync explicit call/invocation-level workload evidence; aggregate owner or spend rows do not authorize a change.");
+    }
+    if (lines.length === 0) {
+        lines.push("- Run `npx aibill doctor --sources` to see which local or provider evidence is missing.");
+    }
+    return lines;
+}
 async function buildExplicitSampleReportInput(rootPath) {
     const records = await loadSampleUsageData();
     return {
@@ -2510,9 +2841,12 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
         // A bundled sample remains sample even if a conflicting mode was written.
         // This guards report and Apply separately from the quickstart read path.
         const mode = isBundledSampleUsage(parsedRecords) ? "sample" : storedMode;
-        const records = mode === "sample" || mode === undefined
+        const parsedModeRecords = mode === "sample" || mode === undefined
             ? downgradeSampleUsageEvidence(parsedRecords)
             : parsedRecords;
+        const records = mode === "connected_provider"
+            ? applyProviderContractGate(parsedModeRecords)
+            : parsedModeRecords;
         unavailablePersistedLocalLogs = mode === "local_logs";
         const headlineRecords = mode === "connected_provider"
             ? selectProviderFinancialHeadlineRecords(records)
@@ -2560,6 +2894,7 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
         const logs = await loadLocalAgentUsage({
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
             codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
             sinceIso,
             collectCodexInvocationEvidence: true
         }).catch(() => undefined);
@@ -2588,11 +2923,12 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
             throw new Error(`${untrustedConnectedStateMessage} No connected totals or Apply actions were generated.`);
         }
         if (unavailablePersistedLocalLogs) {
-            throw new Error("Persisted local-log state is an untrusted cache and its source Claude Code/Codex records are unavailable. " +
+            throw new Error("Persisted local-log state is an untrusted cache and its source local-agent records are unavailable. " +
                 "Re-run `npx aibill` while the local transcripts are available; no report or Apply action was generated from repository state alone.");
         }
-        throw new Error("no persisted spend state and no local Claude Code/Codex logs found. " +
-            "Run `npx aibill` first (or `npx aibill scan --sample --path <dir>` for a demo-data report).");
+        throw new Error("no persisted spend state and no supported local-agent financial evidence found. " +
+            "Use Claude Code, Codex, or Gemini CLI normally; connect an admin provider for billed cost; " +
+            "or run `npx aibill doctor --sources` to inspect the exact gap.");
     }
     const [discovery, sourceRegistry, missingSourcePrompts, confirmedMappings, persistedProviderRecordsState] = await Promise.all([
         readOptionalJson(join(stateDir, "discovery.json"), emptyDiscovery(rootPath)),
@@ -2651,7 +2987,7 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
     // If live transcript calls are unavailable, omit it instead of fabricating a
     // session-level recommendation from day-aggregate spend records.
     const contextHealth = spendState.mode === "local_logs" && freshLocalCalls
-        ? await loadContextHealth(freshLocalCalls, {
+        ? await loadContextHealth(freshLocalCalls.filter((call) => (localAgentFormatSupports(call.agent, "contextHealth"))), {
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
             codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
             claudeHomeDir: process.env.AI_SPEND_CLAUDE_HOME_DIR,
@@ -2740,7 +3076,8 @@ function parseArgs(argv) {
     const parsed = {
         command,
         sample: false,
-        path: process.cwd()
+        path: process.cwd(),
+        parseErrors: []
     };
     if (command === "statusline" && rest[0] && !rest[0].startsWith("--")) {
         parsed.statuslineAction = rest.shift();
@@ -2749,8 +3086,26 @@ function parseArgs(argv) {
         parsed.provider = rest[0];
         rest.shift();
     }
+    const valueFlags = new Set([
+        "--plan", "--since-days", "--path", "--out",
+        "--source-path", "--type", "--provider", "--source-id", "--team",
+        "--person", "--client", "--project", "--agent", "--workflow",
+        "--evidence", "--confidence", "--label", "--auth-reference",
+        "--start-time", "--end-time", "--org", "--enterprise", "--account-id",
+        "--interval", "--cycles"
+    ]);
+    const numericValueFlags = new Set([
+        "--since-days", "--confidence", "--start-time", "--end-time", "--interval", "--cycles"
+    ]);
     for (let index = 0; index < rest.length; index += 1) {
         const arg = rest[index];
+        const nextValue = rest[index + 1];
+        const nextLooksLikeFlag = nextValue?.startsWith("--") ||
+            (!numericValueFlags.has(arg) && nextValue?.startsWith("-"));
+        if (valueFlags.has(arg) && (nextValue === undefined || nextLooksLikeFlag)) {
+            parsed.parseErrors.push(`${arg} requires a value`);
+            continue;
+        }
         if (arg === "--sample") {
             parsed.sample = true;
             continue;
@@ -2763,6 +3118,10 @@ function parseArgs(argv) {
             parsed.json = true;
             continue;
         }
+        if (arg === "--full") {
+            parsed.full = true;
+            continue;
+        }
         if (arg === "--sources") {
             parsed.sources = true;
             continue;
@@ -2846,6 +3205,10 @@ function parseArgs(argv) {
                 parsed.sourceType = next;
                 index += 1;
             }
+            else if (next) {
+                parsed.parseErrors.push(`--type received unsupported source type "${next}"`);
+                index += 1;
+            }
             continue;
         }
         if (arg === "--provider") {
@@ -2928,6 +3291,9 @@ function parseArgs(argv) {
                 if (Number.isFinite(value) && value >= 0 && value <= 1) {
                     parsed.confidence = value;
                 }
+                else {
+                    parsed.parseErrors.push("--confidence must be a number between 0 and 1");
+                }
                 index += 1;
             }
             continue;
@@ -2951,7 +3317,11 @@ function parseArgs(argv) {
         if (arg === "--start-time") {
             const next = rest[index + 1];
             if (next) {
-                parsed.startTime = Number(next);
+                const value = Number(next);
+                if (Number.isFinite(value))
+                    parsed.startTime = value;
+                else
+                    parsed.parseErrors.push("--start-time must be a finite Unix timestamp");
                 index += 1;
             }
             continue;
@@ -2959,7 +3329,11 @@ function parseArgs(argv) {
         if (arg === "--end-time") {
             const next = rest[index + 1];
             if (next) {
-                parsed.endTime = Number(next);
+                const value = Number(next);
+                if (Number.isFinite(value))
+                    parsed.endTime = value;
+                else
+                    parsed.parseErrors.push("--end-time must be a finite Unix timestamp");
                 index += 1;
             }
             continue;
@@ -2991,7 +3365,11 @@ function parseArgs(argv) {
         if (arg === "--interval") {
             const next = rest[index + 1];
             if (next) {
-                parsed.interval = Number(next);
+                const value = Number(next);
+                if (Number.isFinite(value) && value > 0)
+                    parsed.interval = value;
+                else
+                    parsed.parseErrors.push("--interval must be a positive number of seconds");
                 index += 1;
             }
             continue;
@@ -2999,11 +3377,18 @@ function parseArgs(argv) {
         if (arg === "--cycles") {
             const next = rest[index + 1];
             if (next) {
-                parsed.cycles = Number(next);
+                const value = Number(next);
+                if (Number.isInteger(value) && value >= 0)
+                    parsed.cycles = value;
+                else
+                    parsed.parseErrors.push("--cycles must be a whole number of 0 or greater");
                 index += 1;
             }
             continue;
         }
+        parsed.parseErrors.push(arg.startsWith("-")
+            ? `unknown flag "${arg}"`
+            : `unexpected argument "${arg}"`);
     }
     return parsed;
 }
@@ -3057,7 +3442,7 @@ async function readSourceRegistry(stateDir, rootPath) {
             if (parsedSpend.mode === "connected_provider") {
                 const trust = await verifyConnectedSourceRegistryTrustReceipt(rootPath, exactSpendContents, exactSourceRegistryContents);
                 if (trust.trusted)
-                    return registry;
+                    return applyProviderContractGateToSourceRegistry(registry);
             }
         }
         catch {
@@ -3065,7 +3450,7 @@ async function readSourceRegistry(stateDir, rootPath) {
             // controlled validation/evidence claims are never promoted without the
             // matching external provider-sync receipt.
         }
-        return downgradeUntrustedSourceRegistryClaims(registry);
+        return applyProviderContractGateToSourceRegistry(downgradeUntrustedSourceRegistryClaims(registry));
     }
     catch {
         return createLocalFolderSourceRegistry(rootPath);
@@ -3131,7 +3516,9 @@ function helpText() {
         "aibill — your AI cost and usage evidence in one private view",
         "",
         "Run with no command for an instant, zero-key local readout:",
-        "  npx aibill                           Show available AI cost/value evidence (sample or local data)",
+        "  npx aibill                           Show a compact receipt from available local/connected evidence",
+        "  npx aibill --full                    Show the complete diagnose → recommend → apply → verify audit",
+        "  npx aibill --sample                  Show the clearly labeled illustrative demo (never implicit)",
         "  npx aibill --group-by agent          Drill down by source|model|client|project|agent|user|workspace|apiKey",
         "  npx aibill --plan <id>               Declare your plan when auto-detection can't (claude-max-5x|claude-max-20x|claude-pro|chatgpt-plus|chatgpt-pro)",
         "",
@@ -3161,12 +3548,14 @@ function helpText() {
         "  scan [--path <dir>]     Scan a local workspace for AI usage signals",
         "  scan --sample           Include deterministic sample spend analysis",
         "  quickstart [--sample] [--since-days N] Plain-English local readout (default 30 days)",
+        "    [--full]            Render the complete audit; default is the compact receipt",
         "    [--group-by source|model|client|project|agent|user|workspace|apiKey]  Default: project for local logs; model otherwise",
         "  report [--sample] [--out <name>] [--since-days N] Generate local Markdown and HTML reports from the same window",
         "  report-card [--out f.svg] Write your AI Receipt — a redacted, shareable SVG + caption",
         "  glance [--project <name>] [--plan <id>] [--since-days N] Emit the local, machine-readable Glance snapshot JSON",
         "  context [--project <name>] [--since-days N] Show hook-aware Context Health in the terminal",
         "    [--json]              Emit the same canonical Context Health object used by MCP and Glance",
+        "  Main receipt JSON is not published yet; unsupported --json requests fail instead of returning text.",
         "  apply [--sample] [--since-days N]  Print an evidence-constrained inspection/approval prompt + verification plans",
         "  apply-artifact          Same as `apply` (long form)",
         "",
@@ -3215,7 +3604,7 @@ export async function runMain() {
     if (isInstantDemo && process.stdout.isTTY && !process.env.NO_COLOR) {
         try {
             const { default: yoctoSpinner } = await import("yocto-spinner");
-            spinner = yoctoSpinner({ text: "Analyzing your AI spend…" }).start();
+            spinner = yoctoSpinner({ text: "Reading local AI evidence…" }).start();
         }
         catch {
             // Spinner is optional; never block the wow on it.