copilot-metrics 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.4 - 2026-05-31
+
+### Changed
+
+- `setup` now performs setup by default: VS Code settings are merged into user settings and Copilot hooks are installed for the selected scope. `--print` keeps the old print-only behavior.
+- `report label <id>` now includes a per-model breakdown by default while `report labels` remains accumulated by label.
+- Human reports rename `Credits`/`Status` to clearer `AI Credits est.` and `Usage status` wording.
+
+### Fixed
+
+- `hooks --surface both` now installs both Copilot CLI and VS Code hook event names.
+- Report auto-import skips already imported Copilot session-state files and imported JSONL lines instead of reparsing all historical session files on each report.
+- Existing config files are upgraded with the Copilot session-state source instead of being left stale.
+
+## 0.1.3 - 2026-05-31
+
+### Fixed
+
+- Hook install now avoids embedding transient `npx` cache shims, which can break when their shebang points at a removed Node install. Generated hooks use a stable `npx -y copilot-metrics@<version>` package invocation for those cache paths.
+
 ## 0.1.2 - 2026-05-31
 
 ### Fixed

package/README.md

@@ -9,8 +9,8 @@ Costs are estimates, not official billing records. GitHub billing remains the so
 From npm:
 
 ```bash
-npx copilot-metrics@0.1.2 --help
-npx copilot-metrics@0.1.2 init
+npx copilot-metrics@0.1.4 --help
+npx copilot-metrics@0.1.4 init
 ```
 
 From this checkout:
@@ -38,27 +38,35 @@ export COPILOT_METRICS_HOME=/path/to/copilot-metrics-data
 Useful commands:
 
 ```bash
-npx copilot-metrics@0.1.2 init
-npx copilot-metrics@0.1.2 paths --json
+npx copilot-metrics@0.1.4 init
+npx copilot-metrics@0.1.4 paths --json
 ```
 
+`init` only creates the central data directory and local config. It does not modify editor or hook settings. `setup` performs integration setup for the current machine/workspace.
+
 ## Configure Telemetry
 
 For Copilot CLI, `init` plus hooks are enough for local token reporting. Reports import Copilot's local session-state `events.jsonl` files and extract shutdown usage totals without requiring telemetry environment variables.
 
-Print VS Code Insiders Copilot Chat OpenTelemetry settings:
+Install VS Code Copilot Chat OpenTelemetry settings:
 
 ```bash
-npx copilot-metrics@0.1.2 setup vscode
+npx copilot-metrics@0.1.4 setup vscode
 ```
 
-Print Copilot CLI OpenTelemetry environment exports:
+Install Copilot CLI hooks for the current workspace:
 
 ```bash
-npx copilot-metrics@0.1.2 setup copilot-cli
+npx copilot-metrics@0.1.4 setup copilot-cli
 ```
 
-This is optional. Use it only when you also want Copilot CLI OTel JSONL output.
+Or set up both VS Code settings and workspace hooks in one command:
+
+```bash
+npx copilot-metrics@0.1.4 setup
+```
+
+Use `setup vscode --print` or `setup copilot-cli --print` to print the settings/optional environment exports without writing files. Copilot CLI OTel exports are optional because CLI token usage is read from local session-state files.
 
 Content capture is disabled by default. Do not enable richer prompt capture unless you explicitly accept the privacy tradeoff.
 
@@ -67,14 +75,14 @@ Content capture is disabled by default. Do not enable richer prompt capture unle
 Preview repo-local hook config. The default `--surface both` emits the Copilot CLI lower camel case hook format:
 
 ```bash
-npx copilot-metrics@0.1.2 hooks preview --scope local --surface both
+npx copilot-metrics@0.1.4 hooks preview --scope local --surface both
 ```
 
 Install repo-local or user-global hook config:
 
 ```bash
-npx copilot-metrics@0.1.2 hooks install --scope local --surface both
-npx copilot-metrics@0.1.2 hooks install --scope global --surface both
+npx copilot-metrics@0.1.4 hooks install --scope local --surface both
+npx copilot-metrics@0.1.4 hooks install --scope global --surface both
 ```
 
 Local install writes `.github/hooks/copilot-metrics.json`. Global install updates `~/.copilot/settings.json` idempotently, replacing prior `copilot-metrics` hook entries while preserving other settings and hooks. Use `--surface vscode` for VS Code-only PascalCase events or `--surface copilot-cli` for CLI-native lower camel case events. The hook logger writes redacted JSONL metadata to the central data directory. It extracts Jira-style labels such as `DEMO-12345` from safe metadata and does not store full prompt text by default.
@@ -84,11 +92,11 @@ Local install writes `.github/hooks/copilot-metrics.json`. Global install update
 Initialize the local SQLite store and import JSONL files manually:
 
 ```bash
-npx copilot-metrics@0.1.2 store init
-npx copilot-metrics@0.1.2 import --source vscode --file ~/.local/share/copilot-metrics/telemetry/vscode-copilot-otel.jsonl
-npx copilot-metrics@0.1.2 import --source copilot-cli --file ~/.local/share/copilot-metrics/telemetry/copilot-cli-otel.jsonl
-npx copilot-metrics@0.1.2 import --source copilot-session --file ~/.copilot/session-state/<session-id>/events.jsonl
-npx copilot-metrics@0.1.2 import --source hooks --file ~/.local/share/copilot-metrics/hooks/copilot-hooks.jsonl
+npx copilot-metrics@0.1.4 store init
+npx copilot-metrics@0.1.4 import --source vscode --file ~/.local/share/copilot-metrics/telemetry/vscode-copilot-otel.jsonl
+npx copilot-metrics@0.1.4 import --source copilot-cli --file ~/.local/share/copilot-metrics/telemetry/copilot-cli-otel.jsonl
+npx copilot-metrics@0.1.4 import --source copilot-session --file ~/.copilot/session-state/<session-id>/events.jsonl
+npx copilot-metrics@0.1.4 import --source hooks --file ~/.local/share/copilot-metrics/hooks/copilot-hooks.jsonl
 ```
 
 Imports persist raw records, normalized LLM usage records, hook events, label evidence, and import warnings. Re-importing the same JSONL rows is idempotent. For Copilot session-state files, only shutdown usage rows are persisted; prompt-bearing session events are used in memory for label extraction and context and are not stored as raw records.
@@ -98,21 +106,25 @@ Imports persist raw records, normalized LLM usage records, hook events, label ev
 Run local reports from the SQLite store:
 
 ```bash
-npx copilot-metrics@0.1.2 report labels
-npx copilot-metrics@0.1.2 report label DEMO-12345
-npx copilot-metrics@0.1.2 report label DEMO-12345 --detail
-npx copilot-metrics@0.1.2 report models
-npx copilot-metrics@0.1.2 report repos
-npx copilot-metrics@0.1.2 report unattributed
+npx copilot-metrics@0.1.4 report labels
+npx copilot-metrics@0.1.4 report label DEMO-12345
+npx copilot-metrics@0.1.4 report label DEMO-12345 --detail
+npx copilot-metrics@0.1.4 report models
+npx copilot-metrics@0.1.4 report repos
+npx copilot-metrics@0.1.4 report unattributed
 ```
 
 Every report supports `--json`:
 
 ```bash
-npx copilot-metrics@0.1.2 report labels --json
+npx copilot-metrics@0.1.4 report labels --json
 ```
 
-Report commands automatically import newly appended configured VS Code OTel, optional Copilot CLI OTel, Copilot CLI session-state, and hook JSONL files before querying. Label reports include input, output, cache read, cache creation, and reasoning token totals. Labels seen only in hooks remain visible as hook-only evidence with zero usage records, so attribution hints do not imply token-bearing usage.
+Report commands automatically import newly appended configured VS Code OTel, optional Copilot CLI OTel, Copilot CLI session-state, and hook JSONL files before querying. Repeated reports skip already imported session-state files and already imported JSONL lines.
+
+`report labels` shows accumulated totals per label. `report label <id>` shows the selected label summary plus a per-model breakdown by default. Label reports include input, output, cache read, cache creation, and reasoning token totals. Labels seen only in hooks remain visible as `evidence-only` with zero usage records, so attribution hints do not imply token-bearing usage.
+
+`AI Credits est.` is a local estimate derived from the pricing table. The project treats 1 AI Credit as $0.01 for estimates; GitHub billing remains the source of truth.
 
 ## Attribution Model
 
@@ -175,7 +187,7 @@ The manual prompt performs one harmless tool call so Copilot CLI hook execution
 ## Current Limits
 
 - Costs are estimates, not official billing records.
-- Official GitHub usage report reconciliation is not included in `0.1.2`.
-- Local OTLP collector mode is not included in `0.1.2`.
-- Richer prompt/content capture and redaction controls are not included in `0.1.2`.
+- Official GitHub usage report reconciliation is not included in `0.1.4`.
+- Local OTLP collector mode is not included in `0.1.4`.
+- Richer prompt/content capture and redaction controls are not included in `0.1.4`.
 - Dashboard views are deferred until the CLI/query model proves useful.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-metrics",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local-first Copilot usage telemetry setup and reporting tools.",
   "type": "commonjs",
   "homepage": "https://github.com/nnexai/copilot-metrics#readme",

package/src/cli.js

@@ -4,6 +4,7 @@ const { resolvePaths } = require('./paths');
 const {
   ensureDataDirs,
   vscodeSettings,
+  installVscodeSettings,
   copilotCliEnvironment,
   shellExports,
   hookConfig,
@@ -17,12 +18,13 @@ const { MODEL_PRICES, PRICING_VERSION } = require('./pricing');
 const {
   labelOverview,
   labelSummary,
+  labelModelBreakdown,
   labelDetails,
   modelReport,
   repoReport,
   unattributedReport,
   formatLabels,
-  formatLabelSummary,
+  formatLabelReport,
   formatModels,
   formatRepos,
   formatUnattributed,
@@ -70,8 +72,9 @@ function helpText() {
 Usage:
   copilot-metrics init [--json]
   copilot-metrics paths [--json]
-  copilot-metrics setup vscode [--json]
-  copilot-metrics setup copilot-cli [--json]
+  copilot-metrics setup [all] [--scope local|global] [--json]
+  copilot-metrics setup vscode [--settings-file <path>] [--json]
+  copilot-metrics setup copilot-cli [--scope local|global] [--json]
   copilot-metrics hooks preview [--scope local|global] [--surface both|vscode|copilot-cli] [--json]
   copilot-metrics hooks install [--scope local|global] [--surface both|vscode|copilot-cli] [--json]
   copilot-metrics hook-log --event <name>
@@ -111,6 +114,13 @@ function formatVscode(settings) {
   ].join('\n');
 }
 
+function formatVscodeInstall(results) {
+  return [
+    `Installed VS Code Copilot telemetry settings: ${results.map((result) => result.target).join(', ')}`,
+    'Content capture is disabled.',
+  ].join('\n');
+}
+
 function formatCopilotCli(env) {
   return [
     'Export these variables before running Copilot CLI:',
@@ -122,6 +132,13 @@ function formatCopilotCli(env) {
   ].join('\n');
 }
 
+function formatCopilotCliSetup(result) {
+  return [
+    `Installed ${result.scope} Copilot hook config: ${result.target}`,
+    'Copilot CLI token usage is imported from local session-state; OTel exports are optional.',
+  ].join('\n');
+}
+
 function telemetryDiagnostics(importResults) {
   const hookResult = importResults.find((result) => result.source === 'hooks' && result.raw_records > 0);
   if (!hookResult) return [];
@@ -189,23 +206,49 @@ async function main(args, io) {
 
   if (command === 'setup') {
     if (subcommand === 'vscode') {
-      const settings = vscodeSettings(paths);
-      writeOutput(io.stdout, json ? settings : formatVscode(settings), json);
+      ensureDataDirs(paths);
+      if (flags.print === true || flags.dryRun === true) {
+        const settings = vscodeSettings(paths);
+        writeOutput(io.stdout, json ? settings : formatVscode(settings), json);
+        return;
+      }
+      const results = installVscodeSettings(paths, { env: io.env, target: flags.settingsFile });
+      writeOutput(io.stdout, json ? { installed: results } : formatVscodeInstall(results), json);
       return;
     }
     if (subcommand === 'copilot-cli') {
-      const env = copilotCliEnvironment(paths);
-      writeOutput(io.stdout, json ? env : formatCopilotCli(env), json);
+      ensureDataDirs(paths);
+      if (flags.print === true || flags.dryRun === true) {
+        const env = copilotCliEnvironment(paths);
+        writeOutput(io.stdout, json ? env : formatCopilotCli(env), json);
+        return;
+      }
+      const result = installHook(paths, {
+        cwd: io.cwd,
+        scope: flags.scope || 'local',
+        surface: 'copilot-cli',
+        command: io.commandPath,
+      });
+      writeOutput(io.stdout, json ? { installed: result } : formatCopilotCliSetup({ ...result, scope: flags.scope || 'local' }), json);
       return;
     }
     if (!subcommand || subcommand === 'all') {
-      const snapshot = setupSnapshot({ env: io.env, cwd: io.cwd, home: flags.home, command: io.commandPath });
+      const snapshot = setupSnapshot({
+        env: io.env,
+        cwd: io.cwd,
+        home: flags.home,
+        command: io.commandPath,
+        install: flags.print !== true && flags.dryRun !== true,
+        scope: flags.scope || 'local',
+        surface: flags.surface || 'both',
+        target: flags.settingsFile,
+      });
       writeOutput(io.stdout, json ? snapshot : [
         formatPaths(snapshot.paths),
         '',
-        formatVscode(snapshot.vscode),
+        snapshot.vscodeInstalled.length ? formatVscodeInstall(snapshot.vscodeInstalled) : formatVscode(snapshot.vscode),
         '',
-        formatCopilotCli(snapshot.copilotCli),
+        snapshot.hooksInstalled ? formatCopilotCliSetup({ ...snapshot.hooksInstalled, scope: flags.scope || 'local' }) : formatCopilotCli(snapshot.copilotCli),
       ].join('\n'), json);
       return;
     }
@@ -301,12 +344,13 @@ async function main(args, io) {
       const label = rest[2];
       if (!label) throw new Error('report label requires <id>');
       const summary = await labelSummary(paths.usageDb, label);
+      const models = await labelModelBreakdown(paths.usageDb, label);
       if (flags.detail === true) {
         const details = await labelDetails(paths.usageDb, label);
-        writeOutput(io.stdout, json ? { label: summary, details, diagnostics } : appendDiagnostics(formatLabelSummary(summary, details), diagnostics), json);
+        writeOutput(io.stdout, json ? { label: summary, models, details, diagnostics } : appendDiagnostics(formatLabelReport(summary, models, details), diagnostics), json);
         return;
       }
-      writeOutput(io.stdout, json ? { label: summary, diagnostics } : appendDiagnostics(formatLabelSummary(summary), diagnostics), json);
+      writeOutput(io.stdout, json ? { label: summary, models, diagnostics } : appendDiagnostics(formatLabelReport(summary, models), diagnostics), json);
       return;
     }
     if (subcommand === 'models') {

package/src/ingest.js

@@ -6,7 +6,7 @@ const path = require('node:path');
 const { readJsonl } = require('./jsonl');
 const { normalizePayload, normalizeHookEvent, normalizeCopilotSessionEvents } = require('./otel');
 const { estimateCost, PRICING_VERSION } = require('./pricing');
-const { existingRawFingerprints, insertImport } = require('./sqlite-store');
+const { existingRawFingerprints, importedLineHighWater, insertImport } = require('./sqlite-store');
 const { attachUsageLabelEvidence, attachHookLabelEvidence } = require('./labels');
 const { loadConfiguredExtractors } = require('./label-extractors');
 
@@ -44,9 +44,26 @@ function isCopilotSessionUsageRecord(record) {
 
 async function ingestFile(options) {
   const { dbPath, file, source } = options;
-  const parsed = readJsonl(file);
-  const warnings = [...parsed.warnings];
   const sourceFile = path.resolve(file);
+  const highWaterLine = await importedLineHighWater(dbPath, source, sourceFile);
+  if (source === 'copilot-session' && highWaterLine > 0) {
+    return {
+      source,
+      file,
+      dbPath,
+      raw_records: 0,
+      new_raw_records: 0,
+      skipped_existing_records: highWaterLine,
+      usage_records: 0,
+      hook_events: 0,
+      label_evidence: 0,
+      warnings: [],
+      estimate_label: `estimate:${PRICING_VERSION}`,
+    };
+  }
+  const needsSessionContext = source === 'copilot-session' && highWaterLine === 0;
+  const parsed = readJsonl(file, { afterLine: needsSessionContext ? 0 : highWaterLine });
+  const warnings = [...parsed.warnings];
   const parsedRecords = parsed.records.map((record) => ({
     ...record,
     raw_fingerprint: rawFingerprint(source, sourceFile, record),
@@ -98,7 +115,7 @@ async function ingestFile(options) {
     dbPath,
     raw_records: importableRecords.length,
     new_raw_records: newRecords.length,
-    skipped_existing_records: importableRecords.length - newRecords.length,
+    skipped_existing_records: highWaterLine,
     usage_records: enrichedUsage.length,
     hook_events: enrichedHooks.length,
     label_evidence: enrichedUsage.reduce((sum, usage) => sum + (usage.label_evidence || []).length, 0)

package/src/jsonl.js

@@ -2,19 +2,21 @@
 
 const fs = require('node:fs');
 
-function readJsonl(file) {
+function readJsonl(file, options = {}) {
   const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
   const records = [];
   const warnings = [];
+  const afterLine = Number(options.afterLine || 0);
 
   text.split(/\r?\n/).forEach((line, index) => {
-    if (!line.trim()) return;
+    const lineNumber = index + 1;
+    if (lineNumber <= afterLine || !line.trim()) return;
     try {
-      records.push({ line: index + 1, value: JSON.parse(line) });
+      records.push({ line: lineNumber, value: JSON.parse(line) });
     } catch (error) {
       warnings.push({
         code: 'malformed_jsonl',
-        line: index + 1,
+        line: lineNumber,
         message: error.message,
       });
     }

package/src/reports.js

@@ -19,6 +19,10 @@ function formatCredits(value) {
   return n(value).toFixed(6);
 }
 
+function usageStatus(row) {
+  return n(row.usage_records) > 0 ? 'usage' : 'evidence-only';
+}
+
 function table(headers, rows) {
   const widths = headers.map((header, index) => Math.max(
     header.length,
@@ -48,6 +52,10 @@ SELECT
     WHEN (SELECT COUNT(DISTINCT usage_record_id) FROM label_evidence WHERE label = labels.label AND usage_record_id IS NOT NULL) = 0 THEN 'hook-only'
     ELSE 'token-bearing'
   END AS token_status,
+  CASE
+    WHEN (SELECT COUNT(DISTINCT usage_record_id) FROM label_evidence WHERE label = labels.label AND usage_record_id IS NOT NULL) = 0 THEN 'evidence-only'
+    ELSE 'usage'
+  END AS usage_status,
   (SELECT MIN(COALESCE(ur.timestamp, le.timestamp, le.imported_at)) FROM label_evidence le LEFT JOIN usage_records ur ON ur.id = le.usage_record_id WHERE le.label = labels.label) AS first_seen,
   (SELECT MAX(COALESCE(ur.timestamp, le.timestamp, le.imported_at)) FROM label_evidence le LEFT JOIN usage_records ur ON ur.id = le.usage_record_id WHERE le.label = labels.label) AS last_seen,
   (SELECT MAX(estimate_label) FROM usage_records WHERE id IN (SELECT DISTINCT usage_record_id FROM label_evidence WHERE label = labels.label AND usage_record_id IS NOT NULL)) AS estimate_label
@@ -73,6 +81,10 @@ SELECT
     WHEN (SELECT COUNT(DISTINCT usage_record_id) FROM label_evidence WHERE label = labels.label AND usage_record_id IS NOT NULL) = 0 THEN 'hook-only'
     ELSE 'token-bearing'
   END AS token_status,
+  CASE
+    WHEN (SELECT COUNT(DISTINCT usage_record_id) FROM label_evidence WHERE label = labels.label AND usage_record_id IS NOT NULL) = 0 THEN 'evidence-only'
+    ELSE 'usage'
+  END AS usage_status,
   (SELECT MIN(COALESCE(ur.timestamp, le.timestamp, le.imported_at)) FROM label_evidence le LEFT JOIN usage_records ur ON ur.id = le.usage_record_id WHERE le.label = labels.label) AS first_seen,
   (SELECT MAX(COALESCE(ur.timestamp, le.timestamp, le.imported_at)) FROM label_evidence le LEFT JOIN usage_records ur ON ur.id = le.usage_record_id WHERE le.label = labels.label) AS last_seen,
   (SELECT MAX(estimate_label) FROM usage_records WHERE id IN (SELECT DISTINCT usage_record_id FROM label_evidence WHERE label = labels.label AND usage_record_id IS NOT NULL)) AS estimate_label
@@ -80,6 +92,30 @@ FROM (SELECT DISTINCT label FROM label_evidence WHERE label = ?) labels`, [canon
   return rows[0] || null;
 }
 
+async function labelModelBreakdown(dbPath, label) {
+  await initStore(dbPath);
+  return queryRows(dbPath, `
+SELECT
+  COALESCE(ur.resolved_model, ur.requested_model, 'unknown') AS model,
+  COUNT(DISTINCT ur.id) AS usage_records,
+  COUNT(DISTINCT ur.session_id) AS sessions,
+  SUM(ur.input_tokens) AS input_tokens,
+  SUM(ur.output_tokens) AS output_tokens,
+  SUM(ur.cache_read_tokens) AS cache_read_tokens,
+  SUM(ur.cache_creation_tokens) AS cache_creation_tokens,
+  SUM(ur.reasoning_tokens) AS reasoning_tokens,
+  SUM(COALESCE(ur.estimated_ai_credits, 0)) AS estimated_ai_credits,
+  MAX(ur.estimate_label) AS estimate_label
+FROM usage_records ur
+WHERE ur.id IN (
+  SELECT DISTINCT usage_record_id
+  FROM label_evidence
+  WHERE label = ? AND usage_record_id IS NOT NULL
+)
+GROUP BY COALESCE(ur.resolved_model, ur.requested_model, 'unknown')
+ORDER BY estimated_ai_credits DESC, model`, [canonicalLabel(label)]);
+}
+
 async function labelDetails(dbPath, label) {
   await initStore(dbPath);
   return queryRows(dbPath, `
@@ -173,7 +209,7 @@ ORDER BY ur.timestamp, ur.id`);
 function formatLabels(rows) {
   return [
     table(
-      ['Label', 'Sessions', 'Usage', 'Input', 'Output', 'Cache read', 'Cache create', 'Reasoning', 'Credits', 'Status', 'Evidence', 'Last seen'],
+      ['Label', 'Sessions', 'Usage', 'Input', 'Output', 'Cache read', 'Cache create', 'Reasoning', 'AI Credits est.', 'Usage status', 'Evidence', 'Last seen'],
       rows.map((row) => [
         row.label,
         row.sessions,
@@ -184,39 +220,57 @@ function formatLabels(rows) {
         formatNumber(row.cache_creation_tokens),
         formatNumber(row.reasoning_tokens),
         formatCredits(row.estimated_ai_credits),
-        row.token_status,
+        usageStatus(row),
         row.evidence_count,
         row.last_seen || '',
       ]),
     ),
     '',
-    `Costs are estimates (${estimateLabel(rows)}).`,
+    `AI Credits are estimates (${estimateLabel(rows)}). 1 AI Credit is treated as $0.01 for local estimates.`,
   ].join('\n');
 }
 
-function formatLabelSummary(summary, details = null) {
+function formatLabelSummary(summary) {
   if (!summary) return 'No usage found for label.';
-  const lines = [
-    table(
-      ['Label', 'Sessions', 'Usage', 'Input', 'Output', 'Cache read', 'Cache create', 'Reasoning', 'Credits', 'Status', 'Evidence'],
-      [[
-        summary.label,
-        summary.sessions,
-        summary.usage_records,
-        formatNumber(summary.input_tokens),
-        formatNumber(summary.output_tokens),
-        formatNumber(summary.cache_read_tokens),
-        formatNumber(summary.cache_creation_tokens),
-        formatNumber(summary.reasoning_tokens),
-        formatCredits(summary.estimated_ai_credits),
-        summary.token_status,
-        summary.evidence_count,
-      ]],
-    ),
-  ];
+  return table(
+    ['Label', 'Sessions', 'Usage', 'Input', 'Output', 'Cache read', 'Cache create', 'Reasoning', 'AI Credits est.', 'Usage status', 'Evidence'],
+    [[
+      summary.label,
+      summary.sessions,
+      summary.usage_records,
+      formatNumber(summary.input_tokens),
+      formatNumber(summary.output_tokens),
+      formatNumber(summary.cache_read_tokens),
+      formatNumber(summary.cache_creation_tokens),
+      formatNumber(summary.reasoning_tokens),
+      formatCredits(summary.estimated_ai_credits),
+      usageStatus(summary),
+      summary.evidence_count,
+    ]],
+  );
+}
+
+function formatLabelReport(summary, models, details = null) {
+  const output = [formatLabelSummary(summary)];
+  if (models && models.length > 0) {
+    output.push('', table(
+      ['Model', 'Sessions', 'Usage', 'Input', 'Output', 'Cache read', 'Cache create', 'Reasoning', 'AI Credits est.'],
+      models.map((row) => [
+        row.model,
+        row.sessions,
+        row.usage_records,
+        formatNumber(row.input_tokens),
+        formatNumber(row.output_tokens),
+        formatNumber(row.cache_read_tokens),
+        formatNumber(row.cache_creation_tokens),
+        formatNumber(row.reasoning_tokens),
+        formatCredits(row.estimated_ai_credits),
+      ]),
+    ));
+  }
   if (details) {
-    lines.push('', table(
-      ['Source', 'Field', 'Session', 'Model', 'Input', 'Output', 'Cache read', 'Cache create', 'Reasoning', 'Credits', 'Value'],
+    output.push('', table(
+      ['Source', 'Field', 'Session', 'Model', 'Input', 'Output', 'Cache read', 'Cache create', 'Reasoning', 'AI Credits est.', 'Value'],
       details.map((row) => [
         row.source_type,
         row.source_field,
@@ -232,52 +286,54 @@ function formatLabelSummary(summary, details = null) {
       ]),
     ));
   }
-  lines.push('', `Costs are estimates (${summary.estimate_label || 'estimate:unknown'}).`);
-  return lines.join('\n');
+  output.push('', `AI Credits are estimates (${summary?.estimate_label || estimateLabel(models || [])}). 1 AI Credit is treated as $0.01 for local estimates.`);
+  return output.join('\n');
 }
 
 function formatModels(rows) {
   return [
     table(
-      ['Model', 'Records', 'Input', 'Output', 'Credits'],
+      ['Model', 'Records', 'Input', 'Output', 'AI Credits est.'],
       rows.map((row) => [row.model, row.usage_records, formatNumber(row.input_tokens), formatNumber(row.output_tokens), formatCredits(row.estimated_ai_credits)]),
     ),
     '',
-    `Costs are estimates (${estimateLabel(rows)}).`,
+    `AI Credits are estimates (${estimateLabel(rows)}). 1 AI Credit is treated as $0.01 for local estimates.`,
   ].join('\n');
 }
 
 function formatRepos(rows) {
   return [
     table(
-      ['Repo', 'CWD', 'Sessions', 'Input', 'Output', 'Credits'],
+      ['Repo', 'CWD', 'Sessions', 'Input', 'Output', 'AI Credits est.'],
       rows.map((row) => [row.repo, row.cwd, row.sessions, formatNumber(row.input_tokens), formatNumber(row.output_tokens), formatCredits(row.estimated_ai_credits)]),
     ),
     '',
-    `Costs are estimates (${estimateLabel(rows)}).`,
+    `AI Credits are estimates (${estimateLabel(rows)}). 1 AI Credit is treated as $0.01 for local estimates.`,
   ].join('\n');
 }
 
 function formatUnattributed(rows) {
   return [
     table(
-      ['ID', 'Source', 'Session', 'Repo', 'Branch', 'CWD', 'Model', 'Credits'],
+      ['ID', 'Source', 'Session', 'Repo', 'Branch', 'CWD', 'Model', 'AI Credits est.'],
       rows.map((row) => [row.id, row.source, row.session_id || '', row.repo || '', row.branch || '', row.cwd || '', row.resolved_model || '', formatCredits(row.estimated_ai_credits)]),
     ),
     '',
-    `Costs are estimates (${estimateLabel(rows)}).`,
+    `AI Credits are estimates (${estimateLabel(rows)}). 1 AI Credit is treated as $0.01 for local estimates.`,
   ].join('\n');
 }
 
 module.exports = {
   labelOverview,
   labelSummary,
+  labelModelBreakdown,
   labelDetails,
   modelReport,
   repoReport,
   unattributedReport,
   formatLabels,
   formatLabelSummary,
+  formatLabelReport,
   formatModels,
   formatRepos,
   formatUnattributed,

package/src/setup.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { resolvePaths } = require('./paths');
+const { version: PACKAGE_VERSION } = require('../package.json');
 
 const HOOK_SURFACES = ['both', 'copilot-cli', 'vscode'];
 
@@ -33,6 +34,22 @@ function writePrivateFile(file, data) {
   fs.writeFileSync(file, data, { mode: 0o600 });
 }
 
+function readJsonFile(file) {
+  if (!fs.existsSync(file)) return {};
+  const text = fs.readFileSync(file, 'utf8');
+  try {
+    return JSON.parse(text);
+  } catch {
+    return JSON.parse(stripJsonComments(text).replace(/,\s*([}\]])/g, '$1'));
+  }
+}
+
+function stripJsonComments(text) {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
@@ -42,29 +59,45 @@ function ensureDataDirs(paths) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   }
 
-  if (!fs.existsSync(paths.configJson)) {
-    writePrivateFile(paths.configJson, `${JSON.stringify({
-      version: 1,
-      dataHome: paths.home,
-      contentCapture: false,
-      telemetry: {
-        vscode: paths.vscodeOtelJsonl,
-        copilotCli: paths.copilotCliOtelJsonl,
+  const defaultConfig = {
+    version: 1,
+    dataHome: paths.home,
+    contentCapture: false,
+    telemetry: {
+      vscode: paths.vscodeOtelJsonl,
+      copilotCli: paths.copilotCliOtelJsonl,
+    },
+    sources: {
+      vscode: {
+        telemetry: paths.vscodeOtelJsonl,
+        hooks: paths.hookEventsJsonl,
       },
-      sources: {
-        vscode: {
-          telemetry: paths.vscodeOtelJsonl,
-          hooks: paths.hookEventsJsonl,
-        },
-        copilotCli: {
-          telemetry: paths.copilotCliOtelJsonl,
-          hooks: paths.hookEventsJsonl,
-          sessions: paths.copilotSessionStateDir,
-        },
+      copilotCli: {
+        telemetry: paths.copilotCliOtelJsonl,
+        hooks: paths.hookEventsJsonl,
+        sessions: paths.copilotSessionStateDir,
       },
-      labelExtractors: [],
-    }, null, 2)}\n`);
+    },
+    labelExtractors: [],
+  };
+
+  if (!fs.existsSync(paths.configJson)) {
+    writePrivateFile(paths.configJson, `${JSON.stringify(defaultConfig, null, 2)}\n`);
+    return;
   }
+
+  const current = readJsonFile(paths.configJson);
+  const next = {
+    ...defaultConfig,
+    ...current,
+    telemetry: { ...defaultConfig.telemetry, ...(current.telemetry || {}) },
+    sources: {
+      vscode: { ...defaultConfig.sources.vscode, ...(current.sources?.vscode || {}) },
+      copilotCli: { ...defaultConfig.sources.copilotCli, ...(current.sources?.copilotCli || {}) },
+    },
+    labelExtractors: current.labelExtractors || defaultConfig.labelExtractors,
+  };
+  writePrivateFile(paths.configJson, `${JSON.stringify(next, null, 2)}\n`);
 }
 
 function vscodeSettings(paths) {
@@ -76,6 +109,44 @@ function vscodeSettings(paths) {
   };
 }
 
+function defaultVscodeSettingsTargets(options = {}) {
+  const env = options.env || process.env;
+  const home = env.HOME || process.env.HOME;
+  if (!home) return [];
+  if (process.platform === 'darwin') {
+    return [
+      path.join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
+      path.join(home, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  if (process.platform === 'win32') {
+    const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    return [
+      path.join(appData, 'Code', 'User', 'settings.json'),
+      path.join(appData, 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  return [
+    path.join(home, '.config', 'Code', 'User', 'settings.json'),
+    path.join(home, '.config', 'Code - Insiders', 'User', 'settings.json'),
+  ];
+}
+
+function installVscodeSettings(paths, options = {}) {
+  const settings = vscodeSettings(paths);
+  const explicitTarget = options.target;
+  const candidates = explicitTarget ? [explicitTarget] : defaultVscodeSettingsTargets(options);
+  const existingTargets = candidates.filter((target) => fs.existsSync(target));
+  const targets = existingTargets.length > 0 ? existingTargets : candidates.slice(0, 1);
+  const results = [];
+  for (const target of targets) {
+    const current = readJsonFile(target);
+    writePrivateFile(target, `${JSON.stringify({ ...current, ...settings }, null, 2)}\n`);
+    results.push({ target, settings });
+  }
+  return results;
+}
+
 function copilotCliEnvironment(paths) {
   return {
     COPILOT_OTEL_ENABLED: 'true',
@@ -96,12 +167,21 @@ function packageBinCommand(cwd) {
 }
 
 function commandInvocation(command) {
+  if (isEphemeralPackageShim(command)) {
+    return `npx -y copilot-metrics@${PACKAGE_VERSION}`;
+  }
   const quoted = shellQuote(command);
   return command.endsWith('.js') ? `node ${quoted}` : quoted;
 }
 
+function isEphemeralPackageShim(command) {
+  const normalized = String(command || '').replace(/\\/g, '/');
+  return normalized.includes('/.npm/_npx/') || normalized.endsWith('/node_modules/.bin/copilot-metrics');
+}
+
 function hookEventsForSurface(surface) {
-  if (surface === 'copilot-cli' || surface === 'both') return COPILOT_CLI_HOOK_EVENTS;
+  if (surface === 'both') return Array.from(new Set([...COPILOT_CLI_HOOK_EVENTS, ...VSCODE_HOOK_EVENTS]));
+  if (surface === 'copilot-cli') return COPILOT_CLI_HOOK_EVENTS;
   if (surface === 'vscode') return VSCODE_HOOK_EVENTS;
   throw new Error(`Unknown hook surface "${surface}". Use "both", "copilot-cli", or "vscode".`);
 }
@@ -179,11 +259,20 @@ function installHook(paths, options = {}) {
 function setupSnapshot(options = {}) {
   const paths = resolvePaths(options);
   ensureDataDirs(paths);
+  const vscodeInstalled = options.install === true ? installVscodeSettings(paths, options) : [];
+  const hooksInstalled = options.install === true ? installHook(paths, {
+    cwd: options.cwd,
+    scope: options.scope || 'local',
+    surface: options.surface || 'both',
+    command: options.command,
+  }) : null;
   return {
     paths,
     vscode: vscodeSettings(paths),
+    vscodeInstalled,
     copilotCli: copilotCliEnvironment(paths),
     hooks: hookConfig(paths, options),
+    hooksInstalled,
   };
 }
 
@@ -192,7 +281,9 @@ module.exports = {
   COPILOT_CLI_HOOK_EVENTS,
   VSCODE_HOOK_EVENTS,
   ensureDataDirs,
+  defaultVscodeSettingsTargets,
   vscodeSettings,
+  installVscodeSettings,
   copilotCliEnvironment,
   shellExports,
   shellQuote,

package/src/sqlite-store.js

@@ -183,6 +183,16 @@ async function existingRawFingerprints(dbPath, source, sourceFile, fingerprints)
   return existing;
 }
 
+async function importedLineHighWater(dbPath, source, sourceFile) {
+  await initStore(dbPath);
+  const rows = await queryRows(
+    dbPath,
+    'SELECT COALESCE(MAX(line), 0) AS line FROM raw_records WHERE source = ? AND source_file = ?',
+    [source, sourceFile],
+  );
+  return Number(rows[0]?.line || 0);
+}
+
 async function insertImport(dbPath, source, sourceFile, rawRecords, usageRecords, hookEvents, warnings) {
   await initStore(dbPath);
   const db = await openDatabase(dbPath);
@@ -320,6 +330,7 @@ async function queryRows(dbPath, sql, params = []) {
 
 module.exports = {
   existingRawFingerprints,
+  importedLineHighWater,
   initStore,
   insertImport,
   queryOne,