@compaction/cli 0.1.1 → 0.1.2

package/README.md

@@ -1,332 +1,197 @@
 # @compaction/cli
 
-**The free, local-first CLI for capturing and measuring AI agent traces.** It
-captures supported agent sessions on your own machine, shows input/output tokens
-and estimated spend with honest labels, and writes local reports and redacted
-share bundles — and, **when you opt in**, prepares those traces for optimization
-and verification via the **Compaction API**.
-
-> **The local CLI captures, measures, and prepares.** Optimization, advanced
-> verification, apply guidance, and team reporting are **not** in the free CLI —
-> they require the **Compaction API** (opt-in).
-
-## What the free CLI does (local, no account, no upload by default)
-
-`@compaction/cli` is a local-first command-line tool. Everything below runs on your
-machine and writes local files only:
-
-- **Capture supported agent sessions.** **Claude Code is the primary supported
-  workflow** (`capture claude-code`, Integration Readiness **Level 2**
-  command-wrapper). Also supported: **OpenAI Agents SDK** (`capture openai-agents`,
-  Level 2 command-wrapper) and **Codex** local-file/trace **import** (`import`,
-  Level 1). These are local capture/import integrations — **not** native/Level 3
-  SDK instrumentation.
-- **Show input/output tokens and estimated spend.** `analyze` and the local report
-  show input/output token counts and a per-run **estimated** cost. Token counts are
-  **provider-reported** only when the captured run carries provider usage metadata;
-  otherwise they are a **local estimate (chars/4)**. Cost is a **price-table
-  estimate** labeled `local estimate` / `token-estimated cost` — **never
+**The free, local-first CLI for capturing and measuring AI agent traces.** It captures
+supported agent sessions on your own machine, shows input/output tokens and estimated spend
+with honest labels, and writes local reports and redacted share bundles. Everything runs
+locally and writes local files only — **no account, no telemetry, no upload by default.**
+
+> **The free CLI captures, measures, inspects, reports, and redacts.** Optimization, advanced
+> verification, apply guidance, policies, and team reporting are **not** in the free CLI — they
+> are the **opt-in Compaction API**, which is **not a live hosted service yet**.
+
+## What the CLI does
+
+Everything below runs on your machine and writes local files only:
+
+- **Capture supported agent sessions.** Claude Code is the primary supported workflow
+  (`capture claude-code`); OpenAI Agents SDK (`capture openai-agents`) and Codex / local-file
+  traces (`import`) are also supported. These are local capture/import integrations — **not**
+  native SDK instrumentation.
+- **Show input/output tokens and estimated spend.** `analyze` shows input/output token counts
+  and a per-run **estimated** cost. Token counts are **provider-reported** only when the captured
+  run carries provider usage metadata; otherwise they are a **local estimate (chars/4)**. Cost is
+  a **price-table estimate** labeled `local estimate` / `token-estimated cost` — **never
   billing-confirmed**.
-- **Create local reports.** `analyze` / `compact` write local JSON + Markdown
-  reports under an operator-chosen output directory. Local files only.
-- **Create redacted, content-free share bundles.** `feedback --redact` writes a
-  redacted, privacy-safe bundle as a **local file only — never uploaded**, and only
-  with an explicit write gesture (`--yes`).
-- **No upload by default.** There is **no telemetry**. The **only** network call in
-  the free CLI is the explicitly operator-invoked, read-only `capture
-  provider-usage` (credential supplied via an environment variable only; aggregate
-  usage/cost figures only, no prompt/completion content).
-
-The free CLI deliberately answers the first-value question — *"where is my context
-being wasted, and roughly what does it cost?"* — entirely locally, with honest
-labels.
+- **Inspect spend and roll up runs.** `spend`, `summary`, and `aggregate` summarize where context
+  spend came from and roll up local runs — local files only, no hosted dashboard.
+- **Write local reports.** `analyze` writes local JSON + Markdown reports under an
+  operator-chosen output directory. Local files only.
+- **Create redacted, content-free share bundles.** `feedback --redact` writes a redacted,
+  privacy-safe bundle as a **local file only — never uploaded**, and only with an explicit write
+  gesture (`--yes`).
+- **No upload by default.** There is **no telemetry**. The **only** network call in the free CLI
+  is the explicitly operator-invoked, read-only `capture provider-usage` (credential supplied via
+  an environment variable only; aggregate usage/cost figures only, no prompt/completion content).
+
+The free CLI deliberately answers the first-value question — *"where is my context being wasted,
+and roughly what does it cost?"* — entirely locally, with honest labels.
 
 ## What requires the Compaction API (opt-in — not in the free CLI)
 
-The following are **not** part of the free local CLI. They are the **opt-in
-Compaction API**:
+These are **not** part of the free local CLI:
 
 - **Optimization** — producing a compacted context from a captured trace.
 - **Advanced verification** — stronger checks on what a compacted context retains.
-- **Apply guidance** — a readiness verdict and a review/approval path before any
-  context is applied.
-- **Team reporting** — cross-run / cross-session reporting when enabled.
-
-> **The Compaction API is not broadly hosted yet.** There is **no live hosted
-> service today**. The API path is **designed to** optimize and verify **when you
-> opt in** — this README does **not** claim those run as a live service. Until the
-> API is available, these capabilities are **on the roadmap / opt-in**, not present
-> in the free CLI.
-
-When the API is available, the honesty rails carry over unchanged: cost stays an
-**estimate** unless billing-confirmed (no figure carries that label today);
-verification is **deterministic recoverability, NOT semantic/meaning preservation**;
-integration stays **Level 1/2**; and there is **no auto-apply** — every application
-is an explicit operator gesture.
-
-## The free local loop (recommended first run: your OWN workflow)
-
-**capture → analyze / measure → (local report) → redact / share**
-
-The recommended first run is on **your own** captured/imported workflow — **not a
-demo**. Synthetic/demo traces exist only as illustration; they are never the
-recommended first value.
-
-1. **Capture** a real workflow trace. **Claude Code is the primary supported
-   workflow** (`capture claude-code --session <path>`, Level 2 command-wrapper).
-   Also supported: OpenAI Agents SDK (`capture openai-agents`, Level 2) and Codex
-   local-file import (`import`, Level 1).
-2. **Analyze / measure** input/output tokens and estimated spend, and see where the
-   spend came from (`analyze`).
-3. **Local report** — read the local JSON / Markdown report written under your
-   chosen output directory.
-4. **Redact / share** — `feedback --redact` writes a redacted, content-free bundle
-   you can hand a teammate or founder. Local file only, never uploaded.
-
-> **Optimization, advanced verification, apply guidance, and team reporting** are
-> the **opt-in Compaction API**, not steps of the free local CLI (see the section
-> above).
+- **Apply guidance** — a readiness verdict and a review/approval path before any context is applied.
+- **Policies & team reporting** — configurable behavior controls and cross-run / team reporting.
 
-## Evidence levels and claims
-
-Every figure this tool produces carries one of these labels — and nothing stronger:
-
-| Label | Meaning |
-|---|---|
-| **local estimate** | chars/4 token heuristics and price-table cost approximations computed locally |
-| **provider-reported token delta** | token counts read from the provider's own API response/usage metadata (operator-entered or captured); input tokens are deterministic for a fixed context+prompt |
-| **token-estimated cost** | a price-table estimate applied to provider-reported token counts (`price_table_estimate`) — an estimate, never a billed figure |
-| **operator-entered billing record** | billed costs the operator read from their own provider console; recorded, not provider-verified by this tool |
-| **billing-confirmed** | only with real provider billing/invoice evidence **AND** the accepted measurement criterion met on those billed runs (N ≥ 3 runs per arm AND the delta-of-means ±2·SE interval excludes zero) — the statistical criterion alone is a bar on operator-entered figures, not proof of billing, so it is never sufficient by itself — **no figure in this repository currently carries this label** |
-
-**What is NOT claimed:** no billing-confirmed savings claim; no invoice savings claim; no general savings claim (all results are workflow-scoped and caveated); no auto-apply (every application is an explicit operator gesture); no hosted service or control plane (the free CLI is local-first, file-based); no universal "no context is lost" claim; no semantic/meaning preservation claim (it stays `not_evaluated`); no native/production/Level 3 integration claim.
+> **The Compaction API is not broadly hosted yet.** There is **no live hosted service today**.
+> Until the API is available, these capabilities are **on the roadmap / opt-in**, not present in
+> the free CLI. The honesty rails carry over unchanged: cost stays an **estimate** unless
+> billing-confirmed (no figure carries that label today); verification is **deterministic
+> recoverability, NOT semantic/meaning preservation**; and there is **no auto-apply** — every
+> application is an explicit operator gesture.
 
 ## Install
 
-This is a local-first CLI. It makes no network calls by default; the only
-command that reaches the network is the explicitly operator-invoked
-`capture provider-usage`, and only when the operator supplies a credential via
-an environment variable. There is no telemetry.
-
-### npm / npx — LIVE NOW (`@compaction/cli@0.1.1` is published)
+A local-first CLI. It makes no network calls by default; the only command that reaches the
+network is the explicitly operator-invoked `capture provider-usage`. There is no telemetry.
 
-**`@compaction/cli` is published to npm and installs today.** Install it globally,
-or run it with no global install via `npx`:
+### npm / npx
 
 ```bash
-# Published and live now (v0.1.1):
 npm install -g @compaction/cli   # then: compaction init
 npx @compaction/cli init         # no global install
 npx @compaction/cli --help       # no install at all
 ```
 
 The installed binary is `compaction`. After a global install, sanity-check with
-`compaction --version` (→ `0.1.1`) and `compaction --help`.
+`compaction --version` (→ `0.1.2`) and `compaction --help`.
 
-### curl one-liner (`cli.compaction.dev`) — LIVE NOW
+### curl one-liner
 
-**The hosted curl install path is live** at `https://cli.compaction.dev/install`
-(HTTPS, valid TLS). The installer is served as `text/plain` (no caching) and its only
-network call is the `npm install` of the published package. Read it first, then run it:
+The hosted installer at `https://cli.compaction.dev/install` is served as `text/plain` and its
+only network call is the `npm install` of the published package. It uses **no `sudo` by default**
+(installs into a user-writable prefix), collects **no telemetry**, supports macOS + Linux, and
+**fails clearly** rather than faking success. Read it first, then run it:
 
 ```bash
-# LIVE NOW.
-# Inspect it first (recommended): pipe to `less`, or download and read, before sh.
+# Inspect it first (recommended):
 curl -fsSL https://cli.compaction.dev/install | less
-# One-line installer:
+# Install:
 curl -fsSL https://cli.compaction.dev/install | sh
+# Or preview exactly what it would do without installing anything:
+curl -fsSL https://cli.compaction.dev/install | sh -s -- --dry-run
 ```
 
-The installer ([`scripts/install.sh`](scripts/install.sh)) is checked into the repo
-and readable now: it uses **no `sudo` by default** (installs into a user-writable
-prefix), makes **no network call except the npm install** of the published package
-(no telemetry), supports macOS + Linux, and **fails clearly** rather than faking
-success. Preview exactly what it would do without installing anything:
-
-```bash
-sh scripts/install.sh --dry-run
-```
-
-See [`docs/ops/install-readiness.md`](docs/ops/install-readiness.md) for the full
-install-readiness contract (hosting, package name, version pinning, platforms) and
-[`docs/ops/cli-install-domain-readiness.md`](docs/ops/cli-install-domain-readiness.md)
-for the curl-route deploy/DNS execution record.
-
-This repository is licensed under **AGPL-3.0-only** (see [`LICENSE`](LICENSE)). The
-npm **package name is `@compaction/cli`** (scoped, public; the installed binary
-stays `compaction`) and it is **published and live now** (v0.1.1). The **npm/npx and
-curl install paths are all live.**
-
-### From source — for contributors / local development
-
-(For just running the tool, the **npm / npx** path above is now the simplest. Build
-from source when you want to hack on the CLI itself.)
-
-```bash
-git clone <repo-url>
-cd compaction-dev
-npm ci
-npm run build
-# optional: expose the `compaction` binary on your PATH
-npm link
-```
-
-For reproducible local validation, use `npm ci` (not `npm install`).
+## Quick start
 
-### Local tarball install (offline / air-gapped fallback)
-
-The package is on npm now (use the npm / npx path above for the normal case). This
-packed-tarball path remains useful for an offline / air-gapped install or to verify
-the exact published layout locally — a **fallback**, not the intended public path:
+Run on **your own** captured/imported workflow — not a demo. The recommended free local loop is
+**capture → analyze → (local report) → redact / share**:
 
 ```bash
-npm pack
-npm install -g ./compaction-cli-0.1.1.tgz
+compaction init                  # one-time local scaffold (writes nothing until you capture)
+# 1. Capture a real workflow (Claude Code shown; --discover lists local sessions):
+compaction capture claude-code --discover
+compaction capture claude-code --session <session.jsonl> --out ./my-trace
+# 2. Measure tokens + estimated spend, and see where it came from:
+compaction analyze ./my-trace/captured-trace.json
+compaction spend ./my-trace/captured-trace.json
+# 3. Share a redacted, content-free bundle (local file only, never uploaded):
+compaction feedback --redact --yes
 ```
 
-The package layout is verified by `npm run smoke:package`, which packs the
-tarball, installs it into a scratch prefix outside the repo, and runs
-`compaction --help`, `compaction init`, and a capture → compact step from the
-installed binary. The packed tarball ships the local CLI, `README.md`, and
-`LICENSE` only.
+Optimization, verification, and apply guidance are the opt-in Compaction API — not steps of the
+free local CLI.
 
-### Sanity check
+## Supported local workflows
 
-```bash
-compaction --help
-```
+- **Claude Code** (`capture claude-code`) — captures a real Claude Code session JSONL (optionally
+  including subagent transcripts), preserving provider-reported token usage from the session's own
+  API response metadata. `--discover` scans the local projects directory read-only (no network).
+  **Integration Readiness Level 2** (local command-wrapper) — not native SDK instrumentation.
+  Captured traces may contain local file content — review before sharing.
+- **OpenAI Agents SDK** (`capture openai-agents`) — runs a local command or reads a local JSONL
+  export of Agents-SDK trace/span events and normalizes them. **Level 2.** Distinguishes
+  provider-reported usage from local estimates; never invents token metadata.
+- **Codex / local-file import** (`import`) — reads a local trace-like JSON/JSONL file (including a
+  `codex exec --json` export) and normalizes it. **Level 1.** Codex token counts on this path are
+  **locally estimated (chars/4)**, not provider-reported. `compaction import --list-sources` lists
+  supported sources.
 
-## CLI (free, local)
+There is **no** native/Level 3 SDK instrumentation, no production proxy, no model routing, and no
+consumer-app (ChatGPT/Claude desktop) support.
 
-The free local commands:
+## Commands
 
 ```bash
-compaction init                                  # scaffold local config
+compaction init                                  # one-time local scaffold
 compaction capture claude-code --session <session.jsonl> [--include-subagents] --out <dir>
 compaction capture claude-code --discover [--projects-dir <path>]
 compaction capture openai-agents --out <dir> -- <command> [args...]
-compaction capture openai-agents --out <dir> --export <local-jsonl-export>
 compaction capture provider-usage --endpoint <url> [--credential-env-var <NAME>] [--out <dir>]
 compaction import <trace-file> --source <source> --out <dir>
 compaction import --list-sources
 compaction analyze <trace-file>
-compaction feedback --redact [--yes]
+compaction spend <trace-or-optimization-path>   # context-spend attribution
+compaction summary                               # roll up local run reports
+compaction aggregate                             # per-session / cross-session local rollups
+compaction feedback --redact [--yes]             # redacted, local-only share bundle
 ```
 
-### `capture claude-code` (primary supported workflow)
-
-Captures a real Claude Code session JSONL (optionally including subagent
-transcripts) into the internal trace format, preserving provider-reported token
-usage from the session's own API response metadata. `--discover` scans the local
-Claude Code projects directory read-only and lists sessions with metadata (no
-network, no upload). This is **Integration Readiness Level 2** (local
-command-wrapper) — not Level 3 native SDK instrumentation. Captured traces may
-contain local file content — review before sharing.
-
-### `capture openai-agents` (Level 2 command-wrapper)
-
-Runs a local command or reads a local JSONL export containing OpenAI Agents
-SDK-style trace/span events, normalizes the supported events into the internal
-trace format, and writes capture evidence locally. It distinguishes
-provider-reported usage from local estimates: when supported events carry provider
-token fields, those values are labeled provider-reported; when absent, token
-metadata is marked `missing`/`unknown` and **never invented**. This is local
-capture only (Level 2) — it does **not** scrape the ChatGPT app, use undocumented
-APIs, upload traces, proxy provider/model calls, switch providers/models, or add a
-dashboard/auth/billing.
-
-### `capture provider-usage` (the only network call)
-
-Explicitly operator-invoked, read-only read of aggregate usage/cost from a provider
-usage API. The credential comes from an environment variable only (never a flag
-value, never logged, never written into artifacts); absence is a clean refusal. It
-captures aggregate token/cost figures only — no prompt/completion content. The
-resulting record is classified as provider-usage evidence.
+`compaction --help` lists the free local commands.
 
-### `import` (Codex / local-file traces — Level 1)
+## Privacy and security
 
-Reads a local trace-like JSON/JSONL file (including a `codex exec --json` export),
-validates whether it can be converted into the internal trace format, and writes
-normalized intake artifacts to an output directory. Import is local and file-based
-only: it does not mutate the source file, upload data, call provider APIs, route
-models, create a hosted service, use a database, add auth, or add billing. List
-supported sources with `compaction import --list-sources`.
+- **No telemetry; no upload by default.** The free CLI is local-first and file-based.
+- **One network call only.** `capture provider-usage` is explicitly operator-invoked and read-only;
+  its credential comes from an **environment variable only** (never a flag value, never logged,
+  never written into artifacts), and it captures **aggregate** usage/cost figures only — no
+  prompt/completion content. Its absence is a clean refusal.
+- **Captured traces can contain local content.** Capturing a session may include local file
+  content — review a trace before sharing it.
+- **Redacted sharing.** `feedback --redact` produces a redacted, content-free bundle as a local
+  file; writing it requires an explicit `--yes` gesture. There is no upload path.
+- **No sudo by default** in the installer; it installs into a user-writable prefix.
 
-Codex token counts on the import path are **locally estimated (chars/4)**, not
-provider-reported. Live provider/runtime integrations (native Claude Code/Cursor
-instrumentation, live Codex launching, hosted provider APIs) remain future work; the
-Codex support here is intentionally local/export-file based only (Level 1).
-
-### `analyze`
+## Evidence levels and claims
 
-Reads a trace file and prints trace metadata, estimated input/output/total tokens,
-an estimated local cost, conservative waste findings, and suggested
-duplicate-output compaction opportunities (advisory only — the free CLI does **not**
-apply them; optimization is the opt-in Compaction API).
+Every figure this tool produces carries one of these labels — and nothing stronger:
 
-### `feedback --redact`
+| Label | Meaning |
+|---|---|
+| **local estimate** | chars/4 token heuristics and price-table cost approximations computed locally |
+| **provider-reported token delta** | token counts read from the provider's own API response/usage metadata (operator-entered or captured); input tokens are deterministic for a fixed context+prompt |
+| **token-estimated cost** | a price-table estimate applied to provider-reported token counts (`price_table_estimate`) — an estimate, never a billed figure |
+| **operator-entered billing record** | billed costs the operator read from their own provider console; recorded, not provider-verified by this tool |
+| **billing-confirmed** | only with real provider billing/invoice evidence **AND** the accepted measurement criterion met on those billed runs (N ≥ 3 runs per arm AND the delta-of-means ±2·SE interval excludes zero) — the statistical criterion alone is a bar on operator-entered figures, not proof of billing, so it is never sufficient by itself — **no figure in this repository currently carries this label** |
 
-Builds a **redacted, privacy-safe feedback bundle** as a **local file only — never
-uploaded**. Redaction is best-effort and the bundle's own README states what is
-included/excluded; writing the bundle requires an explicit write gesture
-(`--yes`/`--confirm`). There is no upload path.
+**What is NOT claimed:** no billing-confirmed savings claim; no invoice savings claim; no general savings claim (all results are workflow-scoped and caveated); no auto-apply (every application is an explicit operator gesture); no hosted service or control plane (the free CLI is local-first, file-based); no universal "no context is lost" claim; no semantic/meaning preservation claim (it stays `not_evaluated`); no native/production/Level 3 integration claim.
 
 ## Known limitations
 
-- **The free CLI captures and measures; it does not optimize or verify.**
-  Optimization, advanced verification, apply guidance, and team reporting are the
-  **opt-in Compaction API** — not the free local CLI. The API is **not broadly
-  hosted yet**.
-- **Cost figures are estimates or operator-entered records, not billing-confirmed.**
-  Locally computed cost figures are price-table estimates; provider-usage records
-  carry operator-entered/captured console figures (not provider-verified by this
-  tool). **No figure anywhere in this repository is billing-confirmed**; the accepted
-  criterion that could one day support such a label (N ≥ 3 per arm, ±2·SE interval
-  excluding zero, on real billed runs) has not been met.
-- **Token counts are local estimates unless provider-reported usage is captured.**
-  The default is a chars/4 estimate, labeled as such; counts are provider-reported
-  only when the captured run carries provider usage metadata. Unknown stays unknown —
-  output tokens, provider, or cost the data does not carry are never inferred.
-- **Integrations are Level 1/2, not native/production.** Claude Code and OpenAI
-  Agents capture are **Level 2** local command-wrappers; Codex/local-file import is
-  **Level 1**. There is **no** native/Level 3 SDK instrumentation, no production
-  proxy, no model routing, and no ChatGPT/Claude consumer-app support.
-- **Advanced verification (API) is deterministic recoverability, not semantic
-  preservation.** Where the opt-in API verifies a compacted context, it checks
-  deterministic recoverability for a **supported** workflow; it does **not** evaluate
-  meaning or task equivalence, and it does **not** re-run your agent through a model.
-  SEMANTIC / meaning preservation remains **not evaluated**, and true model replay is
-  **future work**.
-- **No universal "no context is lost" guarantee.** Any apply-guidance verdict from
-  the opt-in API is **fail-closed and scoped** to supported developer-agent
-  workflows — never a universal guarantee, and never a semantic/meaning claim.
-
-## Product constraints
-
-- CLI-first, not web-app-first. No web framework, no database, no auth or billing, no
-  streaming.
-- No provider integrations in the free CLI except the explicitly operator-invoked,
-  read-only `capture provider-usage` (env-only credential; aggregate usage/cost only).
-  No proxying, no model routing, no live-call interception.
-- No hosted service or control plane in the free CLI; no full observability dashboard.
-
-**On the roadmap / opt-in API (NOT in the free CLI; reads as future/opt-in anywhere
-public):** the Compaction API's optimization and advanced verification, apply
-guidance, and team reporting; a hosted dashboard / control plane; native (Level 3)
-SDK instrumentation; model routing / provider switching / live-call interception; an
-IDE plugin; true model replay; semantic / meaning preservation (today not
-evaluated); and billing-confirmed savings (no figure in this repository carries that
-label). **The Compaction API is not broadly hosted yet** — never imply a live hosted
-service exists.
-
-## Contributing / internal docs
-
-Repository development, the marketing/docs website (`apps/web`), and contributor
-workflows live in the repo's internal documentation, **not** in this npm-facing
-README:
-
-- `AGENTS.md` — the agent operating contract.
-- `ROADMAP.md` — canonical strategy and the long-term path.
-- `docs/product/product-index.md` — the product-docs entry point (`mvp-plan.md`,
-  `decisions.md`).
-- `docs/ops/install-readiness.md` — the install/publish readiness contract.
+- **The free CLI captures and measures; it does not optimize or verify.** Optimization, advanced
+  verification, apply guidance, policies, and team reporting are the **opt-in Compaction API** —
+  not the free local CLI. The API is **not broadly hosted yet**.
+- **Cost figures are estimates or operator-entered records, not billing-confirmed.** Locally
+  computed cost figures are price-table estimates; provider-usage records carry operator-entered/
+  captured console figures (not provider-verified by this tool). **No figure is billing-confirmed.**
+- **Token counts are local estimates unless provider-reported usage is captured.** The default is a
+  chars/4 estimate, labeled as such. Unknown stays unknown — output tokens, provider, or cost the
+  data does not carry are never inferred.
+- **Integrations are Level 1/2, not native/production.** Claude Code and OpenAI Agents capture are
+  Level 2 local command-wrappers; Codex/local-file import is Level 1. There is **no** native/Level 3
+  SDK instrumentation, no production proxy, no model routing, and no consumer-app support.
+- **Verification (opt-in API) is deterministic recoverability, not semantic preservation.** Where
+  the opt-in API verifies a compacted context, it checks deterministic recoverability for a
+  supported workflow; it does **not** evaluate meaning or task equivalence and does **not** re-run
+  your agent through a model. Semantic / meaning preservation remains **not evaluated**; true model
+  replay is future work.
+- **No universal "no context is lost" guarantee.** Any apply-guidance verdict from the opt-in API
+  is **fail-closed and scoped** to supported developer-agent workflows — never a universal
+  guarantee, and never a semantic/meaning claim.
+
+## License
+
+[AGPL-3.0-only](LICENSE). The npm package name is `@compaction/cli` (scoped, public); the installed
+binary is `compaction`.

package/dist/cli/index.js

@@ -27,7 +27,7 @@ const program = new Command();
 program
     .name("compaction")
     .description("CLI-first trace compaction tools for AI agent workflows.")
-    .version("0.1.1");
+    .version("0.1.2");
 registerAnalyzeCommand(program);
 registerAdapterCommand(program);
 registerAggregateCommand(program);
@@ -51,6 +51,29 @@ registerReviewCommand(program);
 registerRunCommand(program);
 registerSpendCommand(program);
 registerSummaryCommand(program);
+// Clean default `--help` surface (v0.1.2): show ONLY the free, local-first commands
+// that work without the private engine / Compaction API. Everything else (engine-gated,
+// API-adjacent, and internal/operator commands) is HIDDEN from the top-level command
+// list — NOT removed. Hidden commands remain fully registered and invokable by name
+// (e.g. `compaction compact …`), preserving backward compatibility; engine-gated ones
+// still degrade gracefully with the sanctioned message when the engine is absent.
+const PUBLIC_COMMANDS = new Set([
+    "init",
+    "capture",
+    "import",
+    "analyze",
+    "spend",
+    "summary",
+    "aggregate",
+    "feedback"
+]);
+for (const cmd of program.commands) {
+    if (cmd.name() === "help" || PUBLIC_COMMANDS.has(cmd.name()))
+        continue;
+    // commander hides a command from help via its internal `_hidden` flag; the command
+    // stays parseable/runnable. (No public setter exists for an already-created command.)
+    cmd._hidden = true;
+}
 program.parseAsync(process.argv).catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compaction/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public"
   },