copilot-usage-studio 0.1.0

package/dist/copilot-usage-studio/browser/styles-GZOQ5QIH.css

@@ -0,0 +1 @@
+*{box-sizing:border-box}html,body{margin:0;min-height:100%;font-family:Aptos,Segoe UI Variable,Segoe UI,Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,sans-serif;font-size:14px;line-height:1.45;background:#090d14;color:#d7dde7;text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased}html[data-theme=light],html[data-theme=light] body{background:#f4f7fb;color:#182536}html[data-theme=dark],html[data-theme=dark] body{background:#090d14;color:#d7dde7}button,input,select{font:inherit}.data-refresh{display:grid;justify-items:end;min-width:0}.data-refresh-button{display:inline-flex;align-items:center;justify-content:center;gap:6px;min-height:32px;border:1px solid var(--line);border-radius:9px;padding:5px 10px;background:var(--control-bg);color:var(--text-strong);font-size:12px;font-weight:760;cursor:pointer;box-shadow:var(--shadow-soft)}.data-refresh-button:hover:not(:disabled){border-color:var(--accent);color:var(--accent)}.data-refresh-button:disabled{cursor:progress;opacity:.72}.refresh-icon{display:grid;place-items:center;width:16px;height:16px;font-size:17px;line-height:1;transform-origin:50% 50%}.refresh-icon.spinning{animation:refresh-spin .8s linear infinite}.data-refresh-status{max-width:190px;overflow:hidden;color:var(--muted-2);font-size:10px;line-height:1.2;text-overflow:ellipsis;white-space:nowrap}.data-refresh.error .data-refresh-status{color:var(--danger-text)}@keyframes refresh-spin{to{transform:rotate(360deg)}}@media(max-width:760px){.data-refresh-status{display:none}}@media(max-width:520px){.data-refresh-button>span:last-child{display:none}.data-refresh-button{padding-inline:5px}}

package/dist/copilot-usage-studio/browser/usage-studio.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <defs>
+    <linearGradient id="mark" x1="13" y1="49" x2="51" y2="15" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#27d6b0"/>
+      <stop offset="1" stop-color="#7b68ff"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="15" fill="#0d1520"/>
+  <rect x="13" y="34" width="9" height="16" rx="4.5" fill="url(#mark)"/>
+  <rect x="27.5" y="24" width="9" height="26" rx="4.5" fill="url(#mark)"/>
+  <rect x="42" y="14" width="9" height="36" rx="4.5" fill="url(#mark)"/>
+</svg>

package/docs/local-deployment.md

@@ -0,0 +1,202 @@
+# Local Deployment
+
+The app is intended to run locally, near the VS Code data it reads. It should not require a hosted SaaS backend for the core workflow.
+
+Current release posture: early local developer preview. The npm package is prepared and locally verified; clone-and-run remains available until version `0.1.0` is published to the registry.
+
+Packaging foundation now available: the scanner exposes an in-memory Node API through `lib/scanner-api.mjs`. The existing scan command uses that same API and only adds argument parsing plus JSON persistence. This is the common core for the next local host, an `npx` command, Electron packaging, and a future thin VS Code extension.
+
+Supported source today: VS Code GitHub Copilot Chat and Agent local storage. Visual Studio, JetBrains IDEs, Copilot CLI, GitHub.com chat, and GitHub billing exports are outside the current importer scope.
+
+Default scan paths:
+
+- Windows: `%APPDATA%\Code\User` and `%APPDATA%\Code - Insiders\User`
+- macOS: `~/Library/Application Support/Code/User` and `~/Library/Application Support/Code - Insiders/User`
+- Linux: `~/.config/Code/User` and `~/.config/Code - Insiders/User`
+
+SQLite title/metadata enrichment uses Node's `node:sqlite` support. If that is unavailable on a user's local Node version, the scanner should still import debug-log sessions and report enrichment as skipped.
+
+## Recommended For Development
+
+Use the Angular dev server:
+
+```bash
+npm install
+npm start
+```
+
+Then open the local Angular URL, usually:
+
+```text
+http://127.0.0.1:4200/
+```
+
+Why: this is the fastest loop while the UI and scanner are changing. `npm start` launches the Angular dev server and the local runtime together. The runtime serves the last valid snapshot immediately, performs a background startup scan, and powers the in-app refresh action.
+
+## First Public Release Path
+
+The npm package is configured for a one-command local launch:
+
+```bash
+npx copilot-usage-studio
+```
+
+This command will become available after the package owner publishes version `0.1.0` to npm. It starts the packaged production UI and scanner runtime on `http://127.0.0.1:4312/` by default.
+
+Useful packaged commands:
+
+```bash
+npx copilot-usage-studio
+npx copilot-usage-studio scan
+npx copilot-usage-studio status
+npx copilot-usage-studio --help
+```
+
+The CLI requires Node.js 22.5 or newer because optional VS Code `state.vscdb` enrichment uses Node's built-in SQLite support.
+
+Before registry publication, use the repository flow:
+
+```bash
+git clone <repo-url>
+cd copilot-usage-studio
+npm install
+npm start
+```
+
+Then open the local Angular URL printed by the dev server.
+
+This is acceptable for an early developer preview because the audience is technical, the product is changing quickly, and the scanner needs local VS Code storage access anyway. The release page should be explicit that generated data stays local and may contain prompts, file paths, repository context, and tool results.
+
+Before publishing a release post, run:
+
+```bash
+npm run refresh:data
+npm test -- --watch=false
+npm run test:scripts
+npm run build
+```
+
+Release copy should describe the app as a local Copilot usage debugger for VS Code. The strongest promise is: "VS Code already logs useful usage data locally; this app makes it understandable for developers who do not have billing-console access."
+
+### Packaged Data Location
+
+The packaged CLI stores its current normalized snapshot outside the npm installation:
+
+- Windows: `%LOCALAPPDATA%\Copilot Usage Studio\sessions.json`
+- macOS: `~/Library/Application Support/Copilot Usage Studio/sessions.json`
+- Linux: `${XDG_DATA_HOME:-~/.local/share}/copilot-usage-studio/sessions.json`
+
+The npm tarball contains the compiled UI, scanner, pricing table, and runtime code. It must never contain `public/data/sessions.json` or any other developer's imported session data.
+
+### Publishing
+
+Run the full package gate:
+
+```bash
+npm run release:check
+```
+
+Inspect the tarball list, confirm no local session data or absolute paths are present, then publish deliberately:
+
+```bash
+npm publish --access public
+```
+
+Publishing is an external release action and should not be automated from ordinary development commands.
+
+If the browser shows updated markup with stale component styles, stop the dev server and restart it with a cache reset:
+
+```bash
+npm run start:clean
+```
+
+This clears Angular's local build cache before starting `ng serve`. Use it after larger component-style moves if the dev server appears to mix old CSS with new templates.
+
+## Recommended For Local Use Without Dev Mode
+
+Build static files and serve them locally:
+
+```bash
+npm run scan
+npm run verify:data
+npm run build
+```
+
+Then serve the generated `dist/` output with a small local static server.
+
+Why: Angular production output is just static assets plus the generated `public/data/sessions.json` copy. This is a good first packaging target because it avoids an app server and keeps the data model simple.
+
+Current build status: `npm run build` passes. There is still an initial bundle budget warning to clean up later; it does not block the local preview release.
+
+For day-to-day development, use the in-app **Refresh** action. `npm run refresh:data` remains the explicit command-line scan plus verification path.
+
+## Local Runtime
+
+The local runtime is available separately:
+
+```bash
+npm run runtime
+```
+
+It listens on `http://127.0.0.1:4312/` by default and exposes:
+
+- `GET /api/status`: scan state, timestamps, last error, and session count
+- `GET /api/sessions`: the current normalized in-memory `SessionData`
+- `POST /api/scan`: run a scan, persist the new snapshot, and return it
+- `GET /data/sessions.json`: compatibility route backed by the current in-memory snapshot
+
+The runtime seeds itself from `public/data/sessions.json` when needed, then keeps its live cache under `tmp/local-runtime/`. This avoids triggering an Angular development rebuild every time the user refreshes data. It serves cached data while a scan is running, and a failed scan does not replace the last valid snapshot.
+
+To build the production UI and serve the complete local app with one command:
+
+```bash
+npm run preview:local
+```
+
+Then open `http://127.0.0.1:4312/`.
+
+## Future Option: Desktop App
+
+A desktop wrapper can bundle:
+
+- the static Angular UI
+- the scanner command
+- local settings for VS Code paths
+- optional app-owned SQLite later
+
+Why: a desktop app would make the project easier for non-frontend developers to run. It also gives a natural place for refresh controls, background scanning, and local file permissions.
+
+Recommended first implementation: Electron. The current scanner is Node ESM and uses `node:sqlite`, so Electron can reuse it directly. Tauri remains possible later, but it would require a Node sidecar or a scanner rewrite before it offers a meaningful simplicity advantage.
+
+## Single Command
+
+A lightweight local CLI now provides:
+
+```bash
+copilot-usage-studio scan
+copilot-usage-studio
+copilot-usage-studio scan
+copilot-usage-studio status
+```
+
+Why: this keeps the project local and scriptable without committing to a desktop shell too early.
+
+The shared scanner API, runtime, and npm executable are complete. The same runtime can be embedded by Electron later.
+
+## Future Option: VS Code Companion Extension
+
+A thin VS Code extension can call the shared scanner from the local extension host and show the existing UI in a webview. It should remain a host, not a fork of the pricing and parsing logic.
+
+Why not move the whole product into an extension: keeping the scanner and analysis core editor-independent preserves a path to a desktop app and possible Visual Studio support if Visual Studio exposes equivalent local evidence later.
+
+## Later, Not First Release
+
+Do not optimize for a hosted SaaS version yet.
+
+Reasons:
+
+- The strongest data source is on the developer machine under VS Code workspace storage.
+- Local debug logs can contain sensitive prompts, file paths, repo context, and tool results.
+- The product is currently a cost debugger, not an organization billing system.
+
+If billing reconciliation becomes important later, it can be added as an optional import without changing the local-first default.

package/docs/pricing.md

@@ -0,0 +1,274 @@
+# Pricing
+
+This app is a local usage inspector. It uses GitHub's published Copilot usage-based model pricing to explain why a local Copilot run looks expensive, but it is not a GitHub invoice.
+
+Primary source:
+
+```text
+https://docs.github.com/en/copilot/reference/copilot-billing/models-and-pricing
+```
+
+AI credit and allowance source:
+
+```text
+https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-organizations-and-enterprises
+```
+
+Current version:
+
+```text
+github-copilot-usage-pricing-2026-06-14
+```
+
+The source table says prices are per 1 million tokens. The committed snapshot was checked against GitHub Docs on June 14, 2026.
+
+## Where Pricing Lives
+
+- Shared rate-card data: `data/github-copilot-pricing.json`
+- UI adapter: `src/app/pricing.ts`
+- Scanner consumer: `scripts/scan-vscode-sessions.mjs`
+- Verifier consumer: `scripts/verify-session-data.mjs`
+- Generated session-data metadata: `public/data/sessions.json`
+
+The rate card is a versioned JSON file so the scanner, verifier, and UI use the same pricing rows and fallback model. This avoids a quiet class of bugs where the UI explains one price table while the scanner calculated with another.
+
+`src/app/pricing.ts` is intentionally just an Angular-facing adapter around the shared JSON. It adds TypeScript types and the `estimateCostUsd` helper, but it is not the source of truth.
+
+## Updating The Price Snapshot
+
+This should be a deliberate maintainer update, not a runtime web fetch.
+
+1. Open GitHub's official model pricing page and record the check date.
+2. Update `data/github-copilot-pricing.json`, including model availability, all token buckets, and request-size tiers.
+3. Keep tier thresholds machine-readable. Apply them per model call using normal plus cached input, never aggregated session tokens.
+4. Update the pricing version and snapshot date.
+5. Add or update threshold boundary tests and verify that several smaller calls do not accidentally trigger a long-context tier.
+6. Run `npm run refresh:data` to recalculate the local development snapshot.
+7. Run `npm run release:check` and inspect the Prices page in both themes.
+8. Update this document and the changelog when the pricing contract changed.
+
+The future automation worth adding is a maintainer-only audit that detects changes on GitHub's page and opens a reviewable diff. It should not silently update rates or alter historical calculations at runtime.
+
+## What The App Calculates
+
+For each imported model call, the scanner reads local VS Code debug-log token totals when they are available:
+
+- input tokens
+- output tokens
+- cached input tokens, only if the source exposes them
+- cache-write tokens, only if the source exposes them
+- model id and pricing row
+
+## Calculation
+
+For each model row:
+
+```text
+cost_usd =
+  input_tokens / 1,000,000 * input_price +
+  cached_input_tokens / 1,000,000 * cached_input_price +
+  cache_write_tokens / 1,000,000 * cache_write_price +
+  output_tokens / 1,000,000 * output_price
+```
+
+The app displays this estimate in USD. It does not convert to EUR because GitHub's published rate card, AI-credit conversion, and additional-usage budgets are USD-native.
+
+When `copilotUsageNanoAiu` is not available, GitHub AI credits are calculated from the USD token estimate:
+
+```text
+ai_credits = cost_usd / 0.01
+```
+
+GitHub documents `1 AI credit = $0.01 USD`.
+
+### Long-context tiers
+
+GitHub publishes a second rate tier for GPT-5.4 and GPT-5.5 requests over 272K input tokens, and for Gemini 3.1 Pro requests over 200K input tokens.
+
+The app evaluates that threshold independently for every model call:
+
+```text
+request_input_tokens = normal_input_tokens + cached_input_tokens
+```
+
+This reconstructs the raw request input represented by VS Code's `inputTokens` field. A request exactly at the threshold remains on the default row; only a request above it uses the long-context row. The app never applies a long-context price merely because many smaller calls add up to a large session.
+
+Each model summary therefore stores:
+
+- the pricing tiers encountered across its calls
+- normal-input, cached-input, cache-write, and output cost totals summed from those individually priced calls
+
+When a model used more than one tier, the Cost view says `Per-call tiered rates` rather than showing one misleading rate for the whole run.
+
+## GitHub Source Usage
+
+Newer VS Code Copilot Agent Debug Logs can expose `llm_request.attrs.copilotUsageNanoAiu`.
+
+When present, the app treats this as the primary source-usage total for the run:
+
+```text
+source_ai_credits = copilotUsageNanoAiu / 1,000,000,000
+source_usd = source_ai_credits * 0.01
+```
+
+The token-bucket calculation remains the explanation layer and fallback. In other words:
+
+- **GitHub source usage** answers "what usage did Copilot report locally?" This is the primary run total when present.
+- **Token buckets** answer "why did that usage happen?"
+
+The verifier compares source usage with the token-bucket estimate when `copilotUsageNanoAiu` is present. The main UI should stay simple: show source usage when it exists, and only call out fallback when source usage is absent. Reconciliation details belong in diagnostics or docs unless a divergence would change a user decision.
+
+## Included AI Credit Allowances
+
+The app also shows license allowance context for Copilot Business and Copilot Enterprise.
+
+Standard included amounts:
+
+| Plan               | AI credits per user per month |
+| ------------------ | ----------------------------: |
+| Copilot Business   |                         1,900 |
+| Copilot Enterprise |                         3,900 |
+
+Temporary promotional amounts documented by GitHub for existing customers from June 1 to September 1, 2026:
+
+| Plan               | AI credits per user per month |
+| ------------------ | ----------------------------: |
+| Copilot Business   |                         3,000 |
+| Copilot Enterprise |                         7,000 |
+
+The UI treats these as allowance context, not as billing reconciliation. GitHub pools Business and Enterprise included credits at the billing entity level, so a run's percent-of-allowance is a per-seat mental model unless the app later adds organization seat counts.
+
+For example, a 100-seat Copilot Business organization has a shared standard pool of 190,000 credits, not 100 isolated 1,900-credit buckets.
+
+## What The UI Shows
+
+The selected run header shows:
+
+- GitHub source usage when available, otherwise estimated USD cost
+- GitHub source credits when available, otherwise estimated AI credits
+- selected allowance plan
+- percent of that plan's per-user monthly allowance
+
+The Prices page shows:
+
+- the GitHub model price source used by the app
+- the imported pricing version
+- the Business and Enterprise allowance options
+- the fixed AI credit conversion
+- how the currently imported sessions compare with the selected allowance
+
+This is useful for a quick mental model: "this single run would consume about X% of one Business user's monthly included credits."
+
+## Why The GitHub Prices Page Exists
+
+The user should be able to inspect the cost inputs directly. If a session looks expensive, the UI should make it clear whether that came from:
+
+- high input tokens
+- high output tokens
+- a more expensive model
+- cached input or cache-write accounting
+- a model fallback because the raw model id was not in the known GitHub table
+
+The `GitHub prices` view therefore shows every rate row the app knows about, where it came from, and whether any imported session currently uses it.
+
+The same view also shows the selected Business/Enterprise AI-credit allowance and how the current imported sessions compare with it.
+
+## How Realistic Is The Forecast?
+
+Good for:
+
+- using VS Code's `copilotUsageNanoAiu` source usage as the primary local usage total when that field is present
+- reconciling source usage against app-calculated token pricing so token buckets still explain the total
+- finding which model calls drove a run's local cost estimate
+- comparing two runs under the same local assumptions
+- spotting whether cost came mostly from input/context or output
+- estimating AI credit consumption from visible local token totals, including `cachedTokens` when Agent Debug Logs expose them
+- understanding whether a run is tiny, normal, or a large share of a monthly allowance
+- spotting source-backed request payload clues such as large system prompts, large tool schemas, MCP tool presence, tool-result payload size, cached input totals, and request reasoning effort
+
+Not invoice-grade for:
+
+- exact GitHub invoice reconciliation
+- provider-side cached input or cache-write when the generated session data does not include numeric cache-token fields
+- billing adjustments, promotions, policy effects, or later GitHub pricing changes
+- exact attribution of input tokens to instructions, MCP servers, workspace context, or tool results unless the source logs expose those sections directly
+
+## Cache Reality
+
+The scanner imports input, output, and cached-input token totals from VS Code Agent Debug Log `llm_request` events when those fields are present. In the observed VS Code Agent Debug Log shape, `attrs.cachedTokens` is present on many model calls and is the key field for cached input.
+
+## Evidence For The Token Buckets
+
+GitHub's Copilot pricing docs describe three token categories for usage-based billing: input tokens, output tokens, and cached tokens. The same page defines input as what is sent to the model, output as what the model generates, and cached tokens as context the model reuses or stores.
+
+The GitHub Copilot model pricing table is also bucketed by rate. For OpenAI, Google, Microsoft, and GitHub fine-tuned models, the table has separate `Input`, `Cached input`, and `Output` columns. For Anthropic models, GitHub documents an additional `Cache write` column.
+
+Those docs support this pricing shape:
+
+```text
+cost =
+  normal_input_tokens * input_rate +
+  cached_input_tokens * cached_input_rate +
+  cache_write_tokens * cache_write_rate +
+  output_tokens * output_rate
+```
+
+The local VS Code Agent Debug Log field names are not a public GitHub billing API contract. They are observed local debug-log fields. In the sessions inspected so far, `attrs.inputTokens` is the raw input/context total sent to the model, `attrs.cachedTokens` is the cached portion of that input, and `attrs.outputTokens` is generated output.
+
+Because GitHub prices cached input separately, the app treats the observed local fields like this:
+
+```text
+raw_input_tokens = attrs.inputTokens
+cached_input_tokens = attrs.cachedTokens
+normal_input_tokens = max(0, attrs.inputTokens - attrs.cachedTokens)
+output_tokens = attrs.outputTokens
+```
+
+This avoids double-counting. If the app priced all `inputTokens` at the normal input rate and also priced `cachedTokens` at the cached-input rate, the cached portion would be counted twice.
+
+Confidence level:
+
+- High confidence that GitHub bills Copilot usage with distinct input, cached-input, cache-write, and output buckets where those rate columns exist.
+- High confidence that the observed VS Code debug-log `cachedTokens` field should be treated as cached input, because the name and values match GitHub's cached-token billing category.
+- Medium confidence that `cachedTokens` is always a subset of `inputTokens` for this local debug-log schema. The scanner preserves pricing safety by clamping impossible splits, emits a warning if it ever sees one, and the verifier fails generated data where `cachedInputTokens > inputTokens`. This remains an observed VS Code debug-log convention rather than a separately documented public API.
+- Low confidence in any claim that a missing `cachedTokens` field means no provider-side caching occurred. Missing local fields mean "not visible locally", not "zero on GitHub's invoice".
+
+The generated data now carries an ingestion-level cache audit. Run:
+
+```text
+npm run scan
+npm run verify:data
+```
+
+The verifier prints a line like:
+
+```text
+Cache split audit: 23/116 model calls include cachedTokens; 0 invalid cached/input splits; 3,272,520 normal input + 713,970 cached input from 3,986,490 raw inputTokens.
+```
+
+This audit does not make VS Code's debug-log schema a public billing API, but it proves the local data imported into the app obeys the relationship the pricing math depends on:
+
+```text
+raw_input_tokens = normal_input_tokens + cached_input_tokens
+```
+
+That means:
+
+- `attrs.cachedTokens` is treated as cached input and priced with GitHub's cached-input rate for the model. The normal input bucket is `inputTokens - cachedTokens`.
+- The app keeps raw `inputTokens` on trace events so the original VS Code number remains visible, but session/model pricing uses `inputTokens - cachedTokens` for normal input to avoid double-counting.
+- UI cost views must keep normal input, cached input, cache write, and output separate. Cached input is not merged back into normal input for pricing, even though raw `inputTokens` can be useful when debugging how much context was sent to the model.
+- When `cachedInput` and `cacheWrite` are zero in a debug-log import, that means no numeric cache-token totals were imported for that run. It should not be presented as proof that provider-side cache billing was zero.
+- If Agent Debug Logs expose additional numeric cached-token fields for a model call, ingestion should preserve those exact fields and the Cost view should price them separately.
+- `cache_control` hints or prompt-cache metadata can explain that caching was requested or used, but they are not enough on their own to calculate billable cached-token totals.
+- Cached input is not a discount against output. It is a separate input/context bucket when a billing source exposes it. Output tokens remain priced as output tokens.
+- Input-heavy sessions may be overestimated if GitHub billed a large portion of input as cheaper cached input.
+- Output-heavy sessions are usually easier to reason about because output remains priced as output.
+- The Cost view keeps normal input, cached input, cache write, and output as separate priced categories. If cached-token fields are missing for a run, the app does not infer them.
+
+## Current Limitations
+
+- GitHub billing can still differ because GitHub may apply provider-side cache accounting or billing adjustments not present in local logs.
+- Unknown model ids are preserved for display and priced with a visible fallback until the pricing table is updated.
+- Request payload sizes are optimization evidence, not exact cost allocation. The app can show that a tools file was large or that MCP tools were present, but it should not say "this MCP server cost $X" unless source logs expose section-level token totals.
+- The pricing table should be rechecked against GitHub Docs whenever GitHub changes model availability or usage-based rates.
+- Pricing is intentionally a versioned, committed snapshot rather than a runtime web fetch. This keeps scans reproducible and prevents an unavailable or changed web page from silently altering local historical calculations.

package/docs/scanner-api.md

@@ -0,0 +1,109 @@
+# Shared Scanner API
+
+The scanner is now reusable Node infrastructure rather than only a command that writes `public/data/sessions.json`.
+
+## Stable Boundary
+
+Import the host API from:
+
+```text
+lib/scanner-api.mjs
+```
+
+It exposes:
+
+- `scanVsCodeSessions(options)`
+- `writeSessionData(sessionData, outputFile)`
+- `defaultCodeUserDirs()`
+
+Host code should use this module instead of importing individual parser helpers from `scripts/scan-vscode-sessions.mjs`. Parser functions remain implementation details and can evolve with the observed VS Code schema.
+
+## Scan Without Writing
+
+```js
+import { scanVsCodeSessions } from './lib/scanner-api.mjs';
+
+const sessionData = await scanVsCodeSessions();
+```
+
+The result is the normalized `SessionData` document consumed by the Angular UI. No file is created or changed.
+
+This is the intended path for:
+
+- a local HTTP runtime
+- an `npx` launcher
+- an Electron main process
+- a VS Code extension host
+- tests and schema compatibility checks
+
+## Options
+
+```js
+const sessionData = await scanVsCodeSessions({
+  roots: ['/custom/Code/User'],
+  sqlite: true,
+  generatedAt: new Date(),
+});
+```
+
+- `roots`: optional array of VS Code `User` directories or individual workspace-storage directories. Defaults to stable VS Code and VS Code Insiders paths for the current operating system.
+- `sqlite`: set to `false` to skip optional `state.vscdb` metadata enrichment. Debug-log token and usage import still works.
+- `generatedAt`: optional `Date` or date-compatible value, primarily for deterministic hosts and tests.
+- `usdToEur`: legacy generated-contract conversion value. The product UI is USD-first and callers should normally leave this unset.
+
+Duplicate roots are normalized and scanned once. Each call receives fresh ingestion diagnostics; counters and warnings do not leak from earlier scans in a long-running process.
+
+Only one scan may run at a time within one Node process. Hosts should debounce filesystem events and await the current scan instead of starting overlapping work.
+
+## Local Runtime Host
+
+`lib/local-runtime.mjs` is the first shared API host. It keeps the last valid `SessionData` snapshot in memory, serves it while scans run, and persists successful refreshes.
+
+The runtime intentionally keeps scanner and transport concerns separate:
+
+- the scanner knows how to read and normalize VS Code data
+- the runtime owns cache lifetime, HTTP status, refresh coordination, and static UI delivery
+- the Angular app only consumes normalized session data
+
+This same split can be reused by Electron and a thin VS Code extension without copying parsing or pricing logic.
+
+## Explicit Persistence
+
+```js
+import { scanVsCodeSessions, writeSessionData } from './lib/scanner-api.mjs';
+
+const sessionData = await scanVsCodeSessions();
+const outputFile = writeSessionData(sessionData, 'public/data/sessions.json');
+```
+
+Persistence is separate on purpose. A desktop or extension host can return the in-memory document directly, while the current static Angular workflow can keep using the generated JSON file.
+
+## Existing CLI
+
+The existing command remains compatible:
+
+```bash
+node scripts/scan-vscode-sessions.mjs public/data/sessions.json <optional-root> [...more-roots]
+```
+
+It now performs only three host tasks:
+
+1. parse positional arguments
+2. call `scanVsCodeSessions()`
+3. call `writeSessionData()` and report the result
+
+There is one parser and pricing implementation. Future hosts should not copy scanner logic.
+
+## Privacy And Source Rules
+
+The API reads local VS Code Copilot storage and can encounter prompts, file paths, repository context, tool schemas, and tool results. Hosts must keep results local unless a user explicitly exports them.
+
+The API does not change evidence rules:
+
+- source usage is preferred when VS Code logs it
+- Agent Debug Log token fields drive token-bucket pricing
+- cached input remains separate from normal input and output
+- chat snapshots remain fallback data
+- SQLite is metadata enrichment, not a billing source
+
+See [data-ingestion.md](data-ingestion.md), [debug-log-schema.md](debug-log-schema.md), and [pricing.md](pricing.md) for those contracts.