@subvalue/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SubValue contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRE_RELEASE.md

@@ -0,0 +1,51 @@
+# Package validation
+
+The normal installation command is `npx @subvalue/cli`. These instructions validate a locally bundled package independently of the npm registry. No frontend installation or API key is required.
+
+## Get the package
+
+Install Node.js **24.13 or newer** on Windows, macOS or Linux. Check `node --version`.
+
+With access to the private repository, open the latest successful [Validate run](https://github.com/axelmtn/subvalue/actions/workflows/ci.yml). Download its `subvalue-cli-…` artifact and unzip it. Only `subvalue-cli-0.1.0.tgz` should be inside. The artifact expires after 14 days; a new Validate run regenerates it.
+
+Put the `.tgz` in a new folder outside any repository. Open a terminal in that folder.
+
+```sh
+npx --offline --yes --package ./subvalue-cli-0.1.0.tgz subvalue --dry-run
+npx --offline --yes --package ./subvalue-cli-0.1.0.tgz subvalue
+```
+
+The first command checks detection without reading session contents. The second scans real local usage, opens the browser, and serves only `127.0.0.1`. A different loopback port is selected if 4731 is occupied. No demo data is injected.
+
+## Check the app
+
+1. Confirm the detected providers. A detected provider may have no usage in the selected period.
+2. Enter your billing mode and subscription amount when needed. They are declarations, never inferred from credentials.
+3. Check Overview, 7D/30D/Month, Receipt and Settings. Pricing coverage describes imported usage, not every request ever made.
+4. Export PNG. Check readable amounts and the absence of project names, paths, prompts and session IDs.
+5. Use **Refresh usage** at the top of Overview after new activity. It updates local metadata without restarting the app. Period controls only filter cached data.
+6. Stop the CLI with Ctrl+C. Relaunch the same command. Unchanged files should reuse the persistent cache.
+
+For scan timings and cache counts:
+
+```sh
+npx --offline --yes --package ./subvalue-cli-0.1.0.tgz subvalue --verbose
+```
+
+Default metadata storage:
+
+- Windows: `%LOCALAPPDATA%/SubValue/`
+- macOS: `~/Library/Application Support/SubValue/`
+- Linux: `$XDG_DATA_HOME/subvalue/` or `~/.local/share/subvalue/`
+
+Do not send source logs, databases, credentials or conversation content when reporting a problem. Report the OS, Node version, safe error text, scan timing and cache counts. Review screenshots before sharing them.
+
+## Build from the private checkout
+
+```sh
+npm ci --ignore-scripts --no-audit --no-fund
+npm run build
+npm pack --workspace @subvalue/cli --ignore-scripts --pack-destination artifacts
+```
+
+Move the resulting `.tgz` to the separate test folder and use the commands above. No npm publication is needed. Automatic validations cover Windows, Linux, macOS Apple Silicon and macOS Intel; a tester should also verify their normal desktop browser opens correctly.

package/PRIVACY.md

@@ -0,0 +1,45 @@
+# Privacy and data access
+
+SubValue processes usage on the user's machine. It has no account, cloud usage database, telemetry SDK or runtime upload endpoint.
+
+## Files read
+
+Only these provider sources are opened for usage analysis:
+
+- `~/.codex/sessions/**/*.jsonl`
+- `~/.codex/archived_sessions/*.jsonl`
+- `~/.claude/projects/**/*.jsonl`
+
+The CLI also reads its own bundled assets and its own local application database. It checks source-directory/file metadata to detect providers and changes. It does not open credentials, `.env` files, shell history, browser profiles, repositories or project paths mentioned by a session. Symlinks and junctions are rejected. `--dry-run` detects directories without opening session contents.
+
+Session files colocate counters and conversation text. Complete JSONL lines can therefore pass through memory during a scan; only approved metadata is projected into storage. Prompts, responses, attachments and source code are never persisted or displayed.
+
+## Local metadata retained
+
+- Provider, timestamp, raw model identifier and token/cache counters.
+- Service tier, speed and billable tool counts when present, for pricing accuracy.
+- Quality flags, schema and scan diagnostics.
+- Hashed event/source references and a hashed Claude request identity, for deduplication and provenance.
+- File sizes, modification times, hashes of small byte windows and offsets, for incremental scans.
+- Codex thread identity and cumulative-counter state in scan checkpoints, to preserve deduplication and counter resets. This identity is not sent to the dashboard.
+- User-declared billing settings, provider visibility and onboarding state.
+
+Normalized records omit session/thread identities and project associations. Checkpoints omit unnecessary session, turn and project fields. Existing normalized caches are migrated locally without re-reading source histories or changing event keys and token totals.
+
+The browser receives aggregate totals, daily values, model coverage and safe source statuses. It receives no individual requests, project paths, source filenames or conversation text. Receipt exports contain only the selected period, generated date, provider totals and comparison/coverage.
+
+## Storage and deletion
+
+Metadata is stored in SQLite in the OS application-data directory documented in README. It is not encrypted by SubValue; access relies on the user's OS permissions. It is retained for history and incremental scanning. To remove it, stop SubValue and delete only its application-data directory. This does not delete Codex or Claude files.
+
+## Network boundaries
+
+The dashboard server binds only to `127.0.0.1`. Host/origin checks and a per-launch token protect local mutations. The local dashboard uses bundled fonts, scripts and assets and makes no external requests. Pricing is bundled, with no online lookup of user activity.
+
+Installing or updating with npm/npx contacts the package registry. That installation traffic is separate from usage analysis. Following an external documentation link is an explicit browser action.
+
+The public Vercel landing is separate from the local application. It has no usage API, cloud scanner or usage database; its product example is labeled example data. No analytics SDK is included. As the website host, Vercel can process ordinary website connection metadata (such as IP address and requested URL); the landing never receives local usage. See [Vercel's privacy policy](https://vercel.com/legal/privacy-policy).
+
+## Verification
+
+Synthetic tests check approved file access, blocked links, discarded conversation fields, cache migration, deduplication, safe browser summaries and receipt privacy. Browser tests verify no external application requests and identical preview/export pixels. These checks are not a claim of an independent security certification.

package/README.md

@@ -0,0 +1,119 @@
+# SubValue
+
+Local, read-only Codex and Claude Code API-equivalent usage analysis. No account, API keys, cloud database, AI calls, uploads, or telemetry.
+
+## Install
+
+Requires **Node.js 24.13 or newer** on Windows, macOS or Linux.
+
+```sh
+npx @subvalue/cli --dry-run
+npx @subvalue/cli
+```
+
+The source repository is currently private. For optional installation from a local package, see [Package validation](PRE_RELEASE.md).
+
+## Run locally
+
+Requires **Node.js 24.13 or newer**. Runtime and production build have no external dependencies.
+
+```sh
+npm run build
+npm start -- --dry-run
+npm start
+```
+
+The CLI scans both providers, stores normalized metadata in the OS application-data directory (`%LOCALAPPDATA%/SubValue` on Windows, `~/Library/Application Support/SubValue` on macOS, `$XDG_DATA_HOME/subvalue` or `~/.local/share/subvalue` on Linux), binds to `127.0.0.1:4731` (an OS-selected loopback port if occupied), and opens the default browser. It never modifies provider files.
+
+```sh
+npm start -- --no-open
+npm start -- --scan-only
+npm start -- --verbose
+npm run demo
+```
+
+`--demo` is explicitly labeled fixture data, does not scan local providers, and does not create a usage database. `--port` selects the local port. `--dry-run` checks provider-directory metadata only: no session contents, database, or server.
+
+## Interface
+
+- **Overview:** 7D / 30D / Month / Custom, API equivalent, user-declared billing, optional subscription comparison, providers and daily known API value.
+- **Receipt:** local canvas preview and PNG export of the exact same pixels. No projects, paths, requests or sessions in exports.
+- **Settings:** Sources, Billing, USD, Privacy / data. Inactive providers stay here, with optional manual inclusion.
+
+Month compares the full monthly subscription against usage imported so far. Other ranges use calendar-day proration, including multi-month ranges. Amounts and API prices are USD; no invented exchange rates. Billing declarations do not overwrite historical records or prove their original billing mode. Settings offers bundled, verified ChatGPT/Claude plan presets and a custom amount. Annual presets retain the exact annual price divided by 12, with per-seat plans labeled.
+
+## Source access
+
+Only these session inputs are opened by the scanner:
+
+```text
+~/.codex/sessions/**/*.jsonl
+~/.codex/archived_sessions/*.jsonl
+~/.claude/projects/**/*.jsonl
+```
+
+No credentials, auth files, repositories, attachments, clipboard caches, shell history or browser data. The optional Claude stats cache is deliberately not imported in V1 because its history cannot be allocated safely by request/date. Directories referenced by session metadata are never opened. Project identifiers are hashed locally.
+
+Transcripts contain conversation text alongside metadata. They must be streamed to extract usage. Conversation text is transient and is never persisted, logged, sent to the browser, or exported. Codex response records are skipped before JSON deserialization; Claude objects are immediately projected onto the metadata allowlist.
+
+## Accuracy and pricing
+
+`0`, `UNKNOWN`, `NO DATA`, and partial history are distinct. Null fields are never filled with zero. Each record carries provenance, schema, quality and metadata-only source identity. Token completeness and pricing coverage are separate; percentage priced describes **imported records**, not all historical activity.
+
+Codex excludes inherited ordinal prefixes, uses cumulative deltas, suppresses repeated counters, segments counter resets and preserves unallocated totals. Claude deduplicates message/request identities and does not add nested iteration usage. Conflicting duplicates fail closed as incomplete.
+
+The versioned catalog supports mappings with confidence and primary-source provenance, half-open effective intervals, cache reads/writes, Claude cache durations, and long-context bands. Rates and release evidence were checked against [OpenAI pricing](https://developers.openai.com/api/docs/pricing) and [Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing) on **2026-10-05**. Historical versions include the July 30 Luna/Terra reductions and August 21 Sol promotion. Exact public GPT-5.6/6 and Claude identifiers carry mapping provenance; long-context rates use the verified 272k request threshold. New-model launch days use their documented initial API-equivalent rate. Calendar-dated changes between rates remain unknown because their exact UTC switch time is not documented. Sol pricing after the confirmed promotion remains unavailable. See [the pricing evidence ledger](dist/PRICING.md). Internal/unknown model identifiers are never mapped by resemblance.
+
+Overview and receipt display the sum of priceable events; the compact priced percentage identifies partial pricing, and unpriced model identities remain visible in Details. No guessed price or zero is assigned to unknown events. Both views share a display comparison of the known priced amount with the declared prorated subscription: Observed Value / You Saved is their difference, and Value Multiple is their ratio. The normalized summary still marks the full-usage cost and comparison unknown when pricing is incomplete. Partial coverage remains visible; these observed values do not infer a certain outcome or an exact break-even date. API and mixed billing have no subscription comparison. Totals from several subscriptions cannot include API/mixed providers in a subscription comparison.
+
+## Architecture
+
+```text
+apps/web/                 local UI + static public landing
+packages/core/src/        normalized types, security, scanner, SQLite, summaries
+  providers/codex/        Codex adapter
+  providers/claude/       Claude adapter
+  pricing/                versioned catalog + mapping + calculations
+packages/receipt/         shared receipt model and canvas renderer
+packages/cli/             executable, loopback HTTP server, packaged assets
+tests/                    synthetic parser, pricing, storage and security fixtures
+scripts/                  native build + browser validation
+```
+
+Streaming memory is bounded by a 16 MiB line limit. Checkpoints persist byte offsets, typed parser state, file identity and edge fingerprints, never raw trailing text. Unfinished lines are read again on the next scan. Appended files continue from the checkpoint; changed files are replaced transactionally. Missing sources retain cached history with a missing-file flag. Unchanged files require only small fingerprint checks, not a full stream. Provider-input links and junctions are rejected. Checkpoints cannot prove changes made deliberately while preserving metadata and the edge fingerprints; V1 assumes normally written local logs.
+
+## Development / validation
+
+See [Privacy and data access](PRIVACY.md) for the exact fields retained locally and network boundaries.
+
+Usage refreshes incrementally at each normal CLI launch. While the dashboard is open, use **Refresh usage** on Overview or in Settings. Period controls only filter the imported cache; they do not scan source logs. The local application must still be running.
+
+Agents with a terminal on the user's machine can run the same CLI with Node.js 24.13+ and permission to read the approved usage roots and write SubValue's local metadata directory. Use `--scan-only --verbose` to update the cache and exit, or `--no-open` to serve the dashboard without opening a browser. This is CLI interoperability, not a dedicated MCP integration. Only Codex and Claude Code source logs are supported; Hermes or other agents can launch the CLI, but their own usage formats are not imported.
+
+```sh
+npm test
+npm run build
+npm ci --ignore-scripts --no-audit --no-fund
+npm run typecheck
+npm run lint
+npm run test:e2e
+```
+
+Only development validation requires npm dependencies. Inter and IBM Plex Mono fonts are bundled under their included OFL licenses, with no CDN requests. The native production builder uses Node's TypeScript stripping and produces JavaScript modules, static CSS and assets; no compiler runs at CLI launch. Type stripping is **not** a TypeScript typecheck.
+
+Browser validation uses an isolated headless browser with fixture data. Windows uses installed Edge; elsewhere install Playwright Chromium for development. `SUBVALUE_PLAYWRIGHT_MODULE` can reference an already-installed official Playwright module. No personal browser profile is used.
+
+GitHub Actions validates Windows, Linux, and macOS on both Apple Silicon and Intel. Each runner checks types, lint, build, unit/integration tests, responsive browser pages, receipt PNG export, and the locally packed CLI from a temporary directory outside the checkout. The package requires Node.js 24.13 or newer on each platform.
+
+Static landing output is `apps/web/dist`, suitable for a static host including Vercel. It contains no local API server or user data. Its preview is marked as an example. Public GitHub links remain release placeholders while the repository is private.
+
+## Package / release
+
+```sh
+npm run build
+npm pack --workspace @subvalue/cli --ignore-scripts --pack-destination artifacts
+```
+
+Package contents are allowlisted to `dist/`, README, PRE_RELEASE, PRIVACY, and LICENSE. No lifecycle/postinstall scripts or runtime dependencies. Local databases, exports, attachments and test artifacts are ignored by Git and excluded from npm contents.
+
+The initial npm release is published manually from the audited package. The GitHub repository stays private. npm does not support provenance for private source repositories; no provenance attestation is claimed for this release. The future release workflow remains disabled until trusted publishing is configured and `NPM_PUBLISH_ENABLED=true` is set. It uses a protected environment and OIDC rather than a permanent npm token.

package/dist/PRICING.md

@@ -0,0 +1,46 @@
+# Pricing evidence — catalog 2026-10-05.2
+
+USD per million tokens, standard first-party API equivalent. Exact public model IDs only. A mapping's HIGH confidence describes identity, not completeness of retained history. This catalog is bundled and makes no network requests.
+
+| Model | Effective date | Input / cached input / output | Evidence |
+|---|---|---|---|
+| GPT-5.6 Sol | 2026-07-09 | 5 / 0.50 / 30 | [Launch](https://openai.com/index/gpt-5-6/) |
+| GPT-5.6 Sol | 2026-08-21 | 4 / 0.40 / 20 | [API changelog, Aug 21](https://developers.openai.com/api/docs/changelog), [model](https://developers.openai.com/api/docs/models/gpt-5.6-sol) |
+| GPT-5.6 Luna | 2026-07-09 | 1 / 0.10 / 6 | [Launch](https://openai.com/index/gpt-5-6/) |
+| GPT-5.6 Luna | 2026-07-30 | 0.20 / 0.02 / 1.20 | [Price change](https://openai.com/index/advancing-the-price-performance-frontier-with-gpt-5-6/), [model](https://developers.openai.com/api/docs/models/gpt-5.6-luna) |
+| GPT-6 Astra | 2026-09-03 | 10 / 1 / 50 | [API changelog](https://developers.openai.com/api/docs/changelog), [model](https://developers.openai.com/api/docs/models/gpt-6-astra) |
+| GPT-6 Sol | 2026-09-22 | 2 / 0.20 / 10 | [API changelog, Sep 22](https://developers.openai.com/api/docs/changelog), [model](https://developers.openai.com/api/docs/models/gpt-6-sol) |
+| GPT-6 Luna | 2026-09-22 | 0.10 / 0.01 / 0.50 | [API changelog, Sep 22](https://developers.openai.com/api/docs/changelog) |
+| GPT-6.1 Sol | 2026-09-29 | 2 / 0.10 / 10 | [API changelog, Sep 29](https://developers.openai.com/api/docs/changelog), [model](https://developers.openai.com/api/docs/models/gpt-6.1-sol) |
+| Claude Fable 5 | 2026-06-09; restored 2026-07-01 | 10 / 1 / 50 | [Announcement, including suspension](https://www.anthropic.com/news/claude-fable-5-mythos-5), [release notes](https://platform.claude.com/docs/en/release-notes/overview) |
+| Claude Opus 4.8 | 2026-05-28 | 5 / 0.50 / 25 | [Announcement](https://www.anthropic.com/news/claude-opus-4-8) |
+| Claude Opus 5 | 2026-07-24 | 5 / 0.50 / 25 | [Announcement](https://www.anthropic.com/news/claude-opus-5) |
+| Claude Opus 4.7 / 4.6 / 4.5 | 2026-04-16 / 2026-02-05 / 2025-11-24 | 5 / 0.50 / 25 | [4.7](https://www.anthropic.com/news/claude-opus-4-7), [4.6](https://www.anthropic.com/news/claude-opus-4-6), [4.5](https://www.anthropic.com/news/claude-opus-4-5) |
+| Claude Sonnet 4.5 / 4.6 | 2025-09-29 / 2026-02-17 | 3 / 0.30 / 15 | [4.5](https://www.anthropic.com/news/claude-sonnet-4-5), [4.6](https://www.anthropic.com/news/claude-sonnet-4-6) |
+
+Cache policy: [OpenAI](https://developers.openai.com/api/docs/guides/prompt-caching), [Claude](https://platform.claude.com/docs/en/about-claude/pricing). OpenAI cache writes replace the ordinary input rate, at 1.25× input; cached input and writes are subsets of reported input. Claude input, cache read and cache creation are separate. Claude writes cost 1.25× (5m) or 2× (1h) input. Unknown durations stay unavailable.
+
+GPT-5.6 and GPT-6 long-context requests above 272,000 input tokens use 2× input/cache rates and 1.5× output. The entire request receives the applicable band; reasoning is an output breakdown, never a second charge. An aggregate counter delta with inconsistent last-request metadata cannot determine its request context and remains unavailable.
+
+Claude Opus/Sonnet 4.6 long-context premium was removed [March 13](https://claude.com/blog/1m-context-ga). Earlier requests above 200k remain unavailable in this catalog, rather than receiving today's standard rate. Sonnet 4.5 and Opus 4.5 above 200k also remain unavailable pending complete premium/availability evidence.
+
+A new model has one documented initial rate: launch-day API-equivalent estimates use that rate. Dates of actual changes between rates remain unpriced when the exact switch instant is unknown. Sol's promotional rate is confirmed at least through November 21: November 22 onward stays unavailable until evidence extends or replaces that version. Fable's suspended interval is unpriced. GPT-5.3-Codex is retained as an October 5 current snapshot only, pending historical rate evidence.
+
+`codex-auto-review`, unknown aliases, nonstandard tiers/speeds and server tool charges remain unavailable. No inferred subscription billing, regional surcharge, discounts, batch rate or tax. These are standard API-equivalent estimates, not reconstructed invoices.
+
+
+## Catalog completeness audit — October 5, 2026
+
+The [OpenAI standard text/code pricing table](https://developers.openai.com/api/docs/pricing) was checked in full, including its embedded table data: all 40 rows have matching input, cached-input, cache-write (where published), and output rates. A separate checked fixture verifies every row. Six additional older Codex models are covered from their individual official model pages: GPT-5-Codex, GPT-5.1-Codex, GPT-5.1-Codex-Max, GPT-5.1-Codex-Mini, GPT-5.2-Codex and Codex-Mini-Latest. GPT-5.3-Codex, GPT-5.6-Cyber and Chat-Latest are also explicitly covered. Older/current-only snapshots start October 5; current prices are never silently backdated to unverified historical periods. No prefix-based or invented snapshot aliases.
+
+GPT-5.6 Terra initially cost 2.50 / 0.25 / 15 ([July 9 launch](https://openai.com/index/gpt-5-6/)), then 2 / 0.20 / 12 from the [July 30 reduction](https://openai.com/index/advancing-the-price-performance-frontier-with-gpt-5-6/). Its real price-transition day remains uncertain. GPT-5.4/5.5, including Pro, use the documented >272k long-context band; unsupported Pro caching remains unknown. Cyber is bounded to the verified standard-context band.
+
+All 15 active standard models in [Claude's pricing table](https://platform.claude.com/docs/en/about-claude/pricing) are covered, including Fable/Mythos 5.1, Opus 5.5, Sonnet 5/5.5 and Haiku 4.5. Their launch dates come from [official release notes](https://platform.claude.com/docs/en/release-notes/overview). Fable/Mythos 5.1 cache reads are 0.025x input ($0.25/MTok); Opus 5.5 reads are 0.05x ($0.20/MTok), rather than the ordinary 0.1x. Claude writes retain 1.25x/2x for 5m/1h. Sonnet 5's introductory $2/$10 tariff became permanent August 10: the previously planned September increase is not applied.
+
+Retired Claude Opus 4/4.1, Sonnet 4 and Sonnet 3.7 have explicit historical tariffs bounded by their [official retirement dates](https://platform.claude.com/docs/en/about-claude/model-deprecations). Haiku 3.5's exact identity is recognized, but its historical price reduction date is not established: its currently published $0.80/$4 is not backdated to the $1/$5 launch. Mythos Preview's published $25/$125 input/output tariff is an October 5 snapshot; unverified cache rates remain unknown. Models retired before Claude Code and unsupported dated aliases are not claimed to have complete historical prices.
+
+This audit covers first-party standard text/code token equivalents. Audio, video, image-generation, embeddings, research-specialist models and separate tool charges require categories absent from these coding logs and are outside this catalog. Subscription models, Fast/Batch/Flex tiers, negotiated/region-specific prices and future promotions are not inferred. Codex-Auto-Review and GPT-5.3-Codex-Spark have no verified public API equivalent in this audit.
+
+## Subscription presets
+
+USD plans were checked October 5 against [ChatGPT pricing](https://learn.chatgpt.com/docs/pricing), [Claude pricing](https://claude.com/pricing) and [Claude Max tiers](https://support.claude.com/en/articles/11049741-what-is-the-max-plan). Presets are bundled locally, selected manually and do not rewrite existing amounts. Annual plans use the exact annual total divided by 12 (Claude Pro: $200/year, not $17/month); per-seat rates are explicitly labeled. Enterprise/Edu and usage-dependent enterprise bills use Custom amount. Presets describe current plans, not a reconstructed history of subscription contracts.

package/dist/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./packages/cli/src/index.js";

package/dist/packages/cli/src/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {dataDirectory,openBrowser} from './runtime.js';
+import {detectedProviders,sourceRoots} from '../../core/src/security.js';
+                                                     
+import {scan} from '../../core/src/scanner.js';
+import {startServer} from './server.js';
+const argv=process.argv.slice(2);const allowed=new Set(['--dry-run','--demo','--no-open','--scan-only','--help','--port','--data-dir','--verbose']);
+function value(flag       )                 {const i=argv.indexOf(flag);return i<0?undefined:argv[i+1];}
+async function main(){
+  for(let i=0;i<argv.length;i++){if(!allowed.has(argv[i]))throw new Error('Unknown option. Use --help.');if(['--port','--data-dir'].includes(argv[i])){if(!argv[i+1]||argv[i+1].startsWith('--'))throw new Error('Option requires a value');i++;}}
+  if(argv.includes('--help')){console.log('SubValue\n\nsubvalue [--dry-run] [--no-open] [--scan-only] [--verbose] [--port 4731] [--data-dir DIRECTORY]\nsubvalue --demo\n\nRequires Node.js 24.13+. No account or API keys.');return;}
+  if(argv.includes('--dry-run')){const d=detectedProviders();console.log(`Codex       ${d.codex?'Detected':'Not detected'}\nClaude Code ${d.claude?'Detected':'Not detected'}\n\nSources:`);for(const r of sourceRoots())console.log(r.safeLabel);return;}
+  const demo=argv.includes('--demo');const port=Number(value('--port')??4731);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('Invalid port');
+  let store                ;
+  console.log('SubValue\n');
+  if(!demo){const {Store}=await import('../../core/src/storage.js');store=new Store(value('--data-dir')??dataDirectory());let last=0;const verbose=argv.includes('--verbose');const started=Date.now();console.log('Scanning local usage…');const result=await scan(store,{onProgress:p=>{if(Date.now()-last>1000||p.phase==='complete'){last=Date.now();const text=`${p.provider}: ${p.files}/${p.total} files · ${Math.round(p.bytes/1e6)} MB`;if(verbose)console.log(text);else if(process.stdout.isTTY)process.stdout.write(`\r${text.padEnd(65)}`);}}});if(!verbose&&process.stdout.isTTY)process.stdout.write('\r'+' '.repeat(65)+'\r');for(const s of result)console.log(`${s.provider==='codex'?'Codex      ':'Claude Code'} ${s.diagnostics.records?'✓':s.detected?'No usage found':'Not detected'}`);if(verbose)console.log(`${((Date.now()-started)/1000).toFixed(1)}s · ${result.reduce((n,s)=>n+s.cached,0)} files cached`);if(argv.includes('--scan-only')){store.close();return;}}
+  const running=await startServer({store,port,publicDirectory:path.resolve(path.dirname(fileURLToPath(import.meta.url)),'../../../public'),demo}).catch(e=>{store?.close();throw e;});
+  let closing=false;const close=async()=>{if(closing)return;closing=true;await running.close();store?.close();process.exit(0);};process.on('SIGINT',()=>void close());process.on('SIGTERM',()=>void close());
+  if(demo)console.log('DEMO — fixture data');
+  if(!argv.includes('--no-open')){console.log('Opening dashboard…');console.log(running.url);if(!await openBrowser(running.url))console.log(`Open in your browser: ${running.url}`);}else console.log(running.url);
+}
+main().catch(()=>{console.error('SubValue could not start. Check the port, data-directory permissions, and Node version. No source files were modified.');process.exitCode=1;});

package/dist/packages/cli/src/runtime.js

@@ -0,0 +1,22 @@
+import os from 'node:os';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+
+export function dataDirectory(platform=process.platform,home=os.homedir(),env                  =process.env)        {
+  if(platform==='win32')return path.join(env.LOCALAPPDATA&&path.isAbsolute(env.LOCALAPPDATA)?env.LOCALAPPDATA:path.join(home,'AppData','Local'),'SubValue');
+  if(platform==='darwin')return path.join(home,'Library','Application Support','SubValue');
+  return path.join(env.XDG_DATA_HOME&&path.isAbsolute(env.XDG_DATA_HOME)?env.XDG_DATA_HOME:path.join(home,'.local','share'),'subvalue');
+}
+
+export function openBrowser(url       ,launch=spawn,platform=process.platform)                  {
+  // URLs are generated by our loopback server; no shell interpolation is used.
+  if(!/^http:\/\/127\.0\.0\.1:\d+$/.test(url))return Promise.resolve(false);
+  const executable=platform==='win32'?'rundll32':platform==='darwin'?'open':'xdg-open';
+  const args=platform==='win32'?['url.dll,FileProtocolHandler',url]:[url];
+  return new Promise(resolve=>{
+    const child=launch(executable,args,{stdio:'ignore',windowsHide:true});
+    let finished=false;const done=(ok        )=>{if(finished)return;finished=true;clearTimeout(timeout);resolve(ok);};
+    const timeout=setTimeout(()=>{child.unref();done(true);},3000);
+    child.once('error',()=>done(false));child.once('exit',code=>done(code===0));
+  });
+}

package/dist/packages/cli/src/server.js

@@ -0,0 +1,75 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import {randomBytes,timingSafeEqual} from 'node:crypto';
+                                                     
+import {scan,                 } from '../../core/src/scanner.js';
+import {dateRange,summarize} from '../../core/src/summary.js';
+import {demoData} from '../../core/src/demo.js';
+                                                      
+                                                         
+                                                       
+import {safeDirectory} from '../../core/src/security.js';
+import {subscriptionPlan} from '../../core/src/subscriptions.js';
+const mime                      ={'.html':'text/html; charset=utf-8','.js':'text/javascript; charset=utf-8','.css':'text/css; charset=utf-8','.svg':'image/svg+xml','.woff2':'font/woff2','.txt':'text/plain; charset=utf-8'};
+export function validateSettings(value    )         {
+  if(!value||value.currency!=='USD'||typeof value.onboarded!=='boolean')throw new Error('Invalid settings');
+  const s         ={onboarded:value.onboarded,currency:'USD',billing:{}                       ,include:{}                       };
+  for(const provider of ['codex','claude']         ){const b=value.billing?.[provider];if(!b||!['UNKNOWN','SUBSCRIPTION','API','MIXED'].includes(b.mode)||typeof value.include?.[provider]!=='boolean')throw new Error('Invalid billing settings');if(b.monthly!==null&&(typeof b.monthly!=='number'||!Number.isFinite(b.monthly)||b.monthly<0||b.monthly>1000000))throw new Error('Invalid subscription amount');
+    const plan=b.planId==null?undefined:subscriptionPlan(provider,b.planId);if(b.planId!=null&&!plan)throw new Error('Invalid subscription plan');
+    if(b.mode==='SUBSCRIPTION'&&plan&&(b.monthly===null||Math.abs(b.monthly-plan.monthly)>.005))throw new Error('Subscription amount does not match the selected plan');
+    s.billing[provider]={mode:b.mode,monthly:b.mode==='SUBSCRIPTION'?(plan?.monthly??b.monthly):null};if(b.mode==='SUBSCRIPTION'&&b.planId!==undefined)s.billing[provider].planId=plan?.id??null;s.include[provider]=value.include[provider];}return s;
+}
+export async function startServer(options                                                                             ){
+  const secret=randomBytes(32).toString('hex');const demo=options.demo?demoData():null;let demoSettings=demo?.settings;let scanning=false;let progress                  =null;let sessionOrigin='';
+  let revision='',history                   =null;const summaries=new Map                ();
+  const invalidate=()=>{revision='';history=null;summaries.clear();};
+  const server=http.createServer(async(req,res)=>{
+    const headers={'Cache-Control':'no-store','X-Content-Type-Options':'nosniff','Referrer-Policy':'no-referrer','Cross-Origin-Resource-Policy':'same-origin','X-Frame-Options':'DENY','Content-Security-Policy':"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; connect-src 'self'; font-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'"};
+    const json=(status       ,data        )=>{res.writeHead(status,{...headers,'Content-Type':'application/json'});res.end(JSON.stringify(data));};
+    const expectedHost=new URL(sessionOrigin).host;
+    if(req.headers.host!==expectedHost){json(403,{error:'Host denied'});return;}
+    if(req.headers.origin&&req.headers.origin!==sessionOrigin){json(403,{error:'Origin denied'});return;}
+    if(req.headers['sec-fetch-site']==='cross-site'){json(403,{error:'Cross-site access denied'});return;}
+    const url=new URL(req.url??'/',sessionOrigin);
+    try{
+      if(url.pathname.startsWith('/api/')){
+        // The bootstrap is same-origin only. Mutations require its per-launch token.
+        if(url.pathname==='/api/bootstrap'&&req.method==='GET'){json(200,{token:secret,settings:demoSettings??options.store .settings(),sources:demo?.statuses??options.store .statuses(),demo:!!demo,lastScan:options.store?.get('lastScan')??null,scanning,progress});return;}
+        if(url.pathname==='/api/summary'&&req.method==='GET'){
+          if(scanning){json(503,{error:'Scan in progress'});return;}
+          const range=dateRange(url.searchParams.get('period')??'30d',new Date(),url.searchParams.get('from')??undefined,url.searchParams.get('to')??undefined);
+          // History bounds use all normalized metadata, never original transcripts.
+          const currentRevision=demo?'demo':options.store .revision();if(currentRevision!==revision){invalidate();revision=currentRevision;}
+          const key=JSON.stringify(range);let result=summaries.get(key);
+          if(!result){history??=demo?.records??options.store .records();result=summarize(history,demo?.statuses??options.store .statuses(),demoSettings??options.store .settings(),range,demo?.catalog,!!demo);if(summaries.size>=16)summaries.delete(summaries.keys().next().value );summaries.set(key,result);}
+          json(200,result);return;
+        }
+        const given=req.headers['x-subvalue-token'];if(typeof given!=='string'||given.length!==secret.length||!timingSafeEqual(Buffer.from(given),Buffer.from(secret))){json(403,{error:'Session token required'});return;}
+        if(url.pathname==='/api/settings'&&req.method==='POST'){
+          let body='';for await(const chunk of req){body+=chunk;if(body.length>16384){json(413,{error:'Request too large'});return;}}
+          const settings=validateSettings(JSON.parse(body));if(demo)demoSettings=settings;else options.store .saveSettings(settings);invalidate();json(200,{saved:true});return;
+        }
+        if(url.pathname==='/api/rescan'&&req.method==='POST'){
+          if(demo){json(200,{scanning:false});return;}if(scanning){json(409,{error:'Scan already running'});return;}scanning=true;json(202,{scanning:true});
+          void scan(options.store ,{home:options.home,onProgress:p=>{progress=p;}}).catch(()=>{progress=null;}).finally(()=>{invalidate();scanning=false;});return;
+        }
+        json(404,{error:'Not found'});return;
+      }
+      if(req.method!=='GET'&&req.method!=='HEAD'){json(405,{error:'Method not allowed'});return;}
+      const name=url.pathname==='/'||['/overview','/receipt','/settings'].includes(url.pathname)?'index.html':url.pathname==='/landing'?'landing.html':url.pathname.slice(1);
+      if(!/^[a-zA-Z0-9_./-]+$/.test(name)||name.includes('..')||!mime[path.extname(name)]){json(404,{error:'Not found'});return;}
+      const base=path.resolve(options.publicDirectory),target=path.resolve(base,name);
+      if(!target.startsWith(base+path.sep)||!safeDirectory(path.dirname(target))||!fs.existsSync(target)){json(404,{error:'Not found'});return;}
+      const before=fs.lstatSync(target);if(!before.isFile()||before.isSymbolicLink()||!fs.realpathSync(target).startsWith(fs.realpathSync(base)+path.sep)){json(404,{error:'Not found'});return;}
+      if(req.method==='HEAD'){res.writeHead(200,{...headers,'Content-Type':mime[path.extname(target)]});res.end();return;}
+      const fd=fs.openSync(target,fs.constants.O_RDONLY|(fs.constants.O_NOFOLLOW??0)),after=fs.fstatSync(fd);
+      if(before.ino!==after.ino||before.dev!==after.dev){fs.closeSync(fd);json(404,{error:'Not found'});return;}
+      res.writeHead(200,{...headers,'Content-Type':mime[path.extname(target)]});
+      const stream=fs.createReadStream(target,{fd,autoClose:true});stream.on('error',()=>res.destroy());res.once('close',()=>stream.destroy());stream.pipe(res);
+    }catch{json(400,{error:'Unable to complete request'});}
+  });
+  const listen=(port       )=>new Promise      ((resolve,reject)=>{const error=(e      )=>reject(e);server.once('error',error);server.listen(port,'127.0.0.1',()=>{server.removeListener('error',error);const address=server.address();if(!address||typeof address==='string')return reject(new Error('No listening address'));sessionOrigin=`http://127.0.0.1:${address.port}`;resolve();});});
+  try{await listen(options.port);}catch(e){if(options.port===0||!['EADDRINUSE','EACCES'].includes((e                         ).code??''))throw e;await listen(0);}
+  return {server,url:sessionOrigin,close:()=>new Promise      ((resolve,reject)=>server.close(e=>e?reject(e):resolve()))};
+}

package/dist/packages/core/src/demo.js

@@ -0,0 +1,10 @@
+import {baseRecord} from './metadata.js';
+import {catalog,            } from './pricing/index.js';
+import {defaultSettings,emptyDiagnostics,                                                } from './types.js';
+export function demoData(now=new Date())                                                                                  {
+  const records              =[];const monthDays=now.getDate();const weights=Array.from({length:monthDays},(_,i)=>[4,6,5,8,7,10,6,8,11,9][i%10]);const sum=weights.reduce((a,b)=>a+b,0);let assigned=0;
+  for(let i=0;i<monthDays;i++){const r=baseRecord('codex','fixture-only',`fixture-${i}`);const output=i===monthDays-1?20530000-assigned:Math.floor(20530000*weights[i]/sum);assigned+=output;r.timestamp=new Date(now.getFullYear(),now.getMonth(),i+1,12).toISOString();r.model_raw='gpt-5.3-codex';r.session_id='fixture-session';r.input_tokens=0;r.cached_input_tokens=0;r.cache_creation_tokens=0;r.output_tokens=output;r.reasoning_tokens=0;r.total_tokens=output;r.source_schema='DEMO/fixture';r.notes=['demo-fixture'];records.push(r);}
+  const settings=defaultSettings();settings.onboarded=true;settings.billing.codex={mode:'SUBSCRIPTION',monthly:200};
+  const statuses=(['codex','claude']         ).map(provider=>({provider,detected:true,files:provider==='codex'?1:0,scanned:0,cached:0,errors:0,skippedLinks:0,missingFiles:0,diagnostics:emptyDiagnostics()}));
+  const demoCatalog        ={...catalog,version:'DEMO — fixture prices',prices:catalog.prices.map(p=>({...p,effective_from:'2000-01-01T00:00:00.000Z'}))};return {records,settings,statuses,catalog:demoCatalog};
+}

package/dist/packages/core/src/metadata.js

@@ -0,0 +1,14 @@
+import {createHash} from 'node:crypto';
+                                                                   
+export const hash = (...parts           )         => createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+export const token = (v         )                => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : null;
+export const identifier = (v         )                => typeof v === 'string' && /^[a-zA-Z0-9._:@/-]{1,160}$/.test(v) ? v : null;
+export const modelId = (v         )                => typeof v === 'string' && /^[a-zA-Z0-9._:-]{1,100}$/.test(v) ? v : null;
+export const timestamp = (v         )                => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(v) && Number.isFinite(Date.parse(v)) ? new Date(v).toISOString() : null;
+export function baseRecord(provider          , ref        , event        )              {
+  return {id:hash(provider,event),provider,source_event_id:event,source_file_reference:ref,timestamp:null,session_id:null,request_id:null,thread_id:null,model_raw:null,model_canonical:null,billing_mode:'UNKNOWN',input_tokens:null,cached_input_tokens:null,cache_creation_tokens:null,cache_creation_5m_tokens:null,cache_creation_1h_tokens:null,output_tokens:null,reasoning_tokens:null,unallocated_total_tokens:null,total_tokens:null,project_identifier_hash:null,quality:'HIGH',source_schema:'unknown',notes:[],service_tier:null,speed:null,web_search_requests:null,web_fetch_requests:null};
+}
+export function track(d             , r             )       {
+  d.records++;
+  if(r.timestamp){d.first = !d.first || r.timestamp < d.first ? r.timestamp : d.first;d.last = !d.last || r.timestamp > d.last ? r.timestamp : d.last;}
+}