token-harness 0.1.6 → 0.1.7

package/README.md

@@ -1,835 +1,259 @@
 # Token Harness
 
-Token Harness has one objective: **maximize the useful coding work you can get from Claude Code
-and Codex usage limits, without hiding quality regressions or pretending that opaque subscription
-quota is exactly equivalent to a token count**.
+**Make Claude Code and Codex easier to understand and use efficiently.**
 
-The scarce resource is no longer just model context. Subscription users are constrained by rolling
-usage windows, weekly limits, model-dependent burn, long-session context growth, MCP/tool schema
-overhead, noisy tool output, and repeated work after poor model or effort choices. Token Harness is
-evolving from a token-reduction control plane into a **quota-aware efficiency layer** for coding
-harnesses.
+Token Harness checks your coding agents, shows subscription allowance when it can be
+observed reliably, reduces avoidable context overhead, and recommends one useful next
+action. It runs locally and never presents local token estimates as subscription quota.
 
-The product therefore optimizes two related budgets:
+## The easy path
 
-1. **subscription headroom** — observe the usage windows the harness itself exposes, pace work
-   against reset time, and choose native model/effort settings that fit the task and remaining
-   budget;
-2. **context sent to the model** — keep instructions, MCP schemas, conversation history, repository
-   context, and tool output as small as possible without removing information needed to finish the
-   task correctly.
+You need [Node.js 22.13 or newer](https://nodejs.org/) and at least one signed-in coding
+agent: Claude Code or Codex.
 
-RTK and HarnessTrim remain useful providers, but reducers are now one layer of the system rather
-than the product definition. Native harness controls come first because choosing the right model,
-effort, context shape, and enabled tools can avoid an expensive turn entirely.
-
-## What Token Harness should optimize
-
-| Layer | Target behavior |
-| --- | --- |
-| Usage-window observability | Read five-hour, weekly, model-specific, or credit-backed limits only from surfaces the harness can actually prove; show reset time, headroom, and burn rate |
-| Native model policy | Prefer economical models/effort for routine work, escalate only for tasks whose expected quality benefit justifies the extra quota |
-| Session hygiene | Detect task boundaries, oversized conversations, and stale context; recommend clear/compact/new-session actions before history dominates each turn |
-| Instruction budget | Keep `CLAUDE.md` / `AGENTS.md` concise and hierarchical instead of injecting one large global instruction file everywhere |
-| MCP/tool budget | Disable irrelevant MCP servers, defer schemas where the harness supports it, and expose only the tools required by the current task |
-| Tool-output budget | Reduce logs, diffs, test output, and repeated command results before they re-enter model context |
-| Cross-harness scheduling | When Claude Code and Codex have independent headroom, recommend the harness that can do the task with the best expected quality per remaining quota |
-| Measurement | Correlate quota delta, model/effort, context size, tool traffic, and task outcome; never convert local token savings into an unproven subscription-quota claim |
-
-## Optimization ecosystem
-
-The priority order below is deliberately different from the original Token Harness roadmap. A tool
-is high priority only when it helps **included Claude Code/Codex capacity**, not merely API cost,
-provider routing, or benchmark token counts.
-
-| Tool or surface | Optimization layer | Token Harness direction |
-| --- | --- | --- |
-| **Claude Code native controls** | Usage status, model/effort choice, context inspection, clear/compact lifecycle | **P0 — build into core**. Prefer native surfaces over third-party credential scraping; discover available models dynamically |
-| **Codex native app-server + profiles** | Structured rate-limit telemetry; model, reasoning effort, verbosity, tool-output and MCP/context controls | **P0 — build into core**. `account/rateLimits/read` is the preferred live quota source when available |
-| [cclimits](https://github.com/cruzanstx/cclimits) | Live/local quota companion across coding tools | **P0 — optional observational companion for Claude**. Token Harness uses only cacheless Claude JSON mode, never reads its credentials, and labels the result `reported` or `cached`. Codex keeps its native app-server reader |
-| [ccusage](https://github.com/ccusage/ccusage) | Local historical token/session/cost analytics for Claude Code and Codex | **P0 — high-priority read-only companion**. Useful for history and baselines; not a substitute for live subscription-limit telemetry |
-| [RTK](https://github.com/rtk-ai/rtk) | Shell-command rewriting and command-output reduction | **P1 — active, keep**. Reduces context that would otherwise be resent on later turns |
-| [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers, harness adapters, skills, pipes, and MCP reduction | **P1 — active, keep**. Continue only on proven non-overlapping surfaces |
-| [Lazy MCP](https://gitlab.com/gitlab-org/ai/lazy-mcp) | Load MCP tool schemas only when needed | **P1 — high priority**. Directly attacks schema/context overhead; benchmark against native Codex tool deferral before installing another owner |
-| [Context Mode](https://github.com/mksglu/context-mode) | Keep raw tool/MCP results outside model context | **P2 — alternative broad context owner**. Evaluate against Headroom, not alongside overlapping reducers by default |
-| [Headroom](https://github.com/headroomlabs-ai/headroom) | Compress tool, MCP, file, and RAG payloads | **P2 — alternative broad context owner**. Admit only after pair-specific quality and attribution fixtures |
-| [Dejavu](https://github.com/Salnika/dejavu) | Emit only the delta when command output repeats | **P2 — useful for test/rerun loops** after the normal output-reduction path is measured |
-| [repowise](https://github.com/repowise-dev/repowise) | Retrieve task-specific repository context | **P2 — conditional**. Its MCP overhead must be lower than the repository context it avoids |
-| LiteLLM, Claude Code Router, RouteLLM, LLMRouter, vLLM Semantic Router | Route requests across models/providers | **P3 — overflow/API routing only**. Useful after included quota is exhausted or for explicit external-provider policy; not a core subscription-quota optimizer |
-| [LLMLingua](https://github.com/microsoft/LLMLingua) | Generic prompt compression | **Research only** until a harness-aware lifecycle proves must-keep recall and quality |
-| [Caveman](https://github.com/JuliusBrussee/caveman) | Reduce visible model-output verbosity | **De-prioritized**. Use native verbosity/effort controls first and measure their effect before adding another instruction owner |
-
-Candidate status still means that Token Harness neither installs nor configures the tool until its
-installation, conflicts, rollback behavior, verification, quality gates, and metrics attribution are
-implemented and tested. The intake evidence lives in
-[docs/provider-landscape.md](docs/provider-landscape.md).
-
-### Why generic routers moved down
-
-The original roadmap treated model routers as high priority. For the new objective that is backwards:
-a router can reduce API cost by sending work to another provider while consuming **none of the
-included Claude Code or Codex allowance**, or it can bypass subscription authentication entirely.
-That can be valuable as explicit overflow, but it does not demonstrate better use of the allowance
-the user already paid for.
-
-Token Harness should first exploit the harness-native choices that are actually inside the plan:
-model tier, reasoning effort, verbosity, session lifecycle, instruction size, MCP exposure, and tool
-output. External routing becomes an opt-in second budget, never an invisible shortcut.
-
-## Quick start
-
-Install the CLI:
-
-```sh
-npm install --global token-harness
-token-harness --version
-```
-
-Then run the complete workflow from the project in which you use your coding agent:
-
-```sh
-# 1. Inspect the machine. This does not change agent configuration.
-token-harness doctor
-
-# 2. Inspect subscription headroom and avoidable context. Still read-only.
-token-harness budget
-token-harness context
-token-harness history --since 7d
-token-harness optimize
-
-# Optional: Claude live quota can use an already-installed cclimits build that
-# supports --no-cache-write. Token Harness never installs it automatically.
-
-# 3. Preview every proposed configuration change.
-token-harness plan
-
-# 4. Apply the reviewed plan. This is the first configuration-changing step.
-token-harness apply --yes
-
-# 5. Restart the coding agent, then run a normal shell command through it.
-
-# 6. Check configuration, real interception evidence, and savings.
-token-harness status
-token-harness verify
-token-harness metrics --since 7d
-```
-
-`doctor` ends with a `NEXT` section. If you are unsure what to do, run the command shown
-there.
-
-### Codex: quota-aware optimization example
-
-For a concrete Codex workflow, keep observation and mutation separate:
+Open a terminal and paste:
 
 ```sh
-# Read-only: inspect live subscription windows.
-token-harness budget --harness codex
-
-# Read-only: inspect the effective model, reasoning effort, project instructions,
-# MCP servers, and visible tool inventory.
-token-harness context --harness codex
-
-# Read-only: combine quota pacing and context pressure into task-specific advice.
-token-harness optimize --harness codex --task standard --profile balanced
-
-# Dry run: preview supported Codex-native policy changes.
-token-harness plan --harness codex --native-policy
-```
-
-A typical optimization can recommend lowering reasoning effort for routine work when quota is
-under-pace, while keeping the current model until empirical model-tier evidence exists. A plan may
-also include reviewed provider actions such as a HarnessTrim skill install.
-
-Apply the exact stored plan only after reviewing it:
-
-```sh
-token-harness apply --plan <plan-id> --yes
-token-harness context --harness codex
-token-harness verify --harness codex
-```
-
-On supported recent Codex builds, Token Harness uses Codex's native app-server for authoritative
-rate-limit windows, effective configuration, model catalog, MCP inventory, and reviewed native
-configuration writes. It does not infer quota from local token counts.
-
-Useful variants:
-
-```sh
-# More conservative reasoning for routine work.
-token-harness optimize --harness codex --task mechanical --profile economy
-
-# Preserve more quality headroom for difficult work.
-token-harness optimize --harness codex --task hard --profile quality
-
-# Inspect MCP exposure directly.
-token-harness mcp --harness codex
-
-# Compare recent local history when available.
-token-harness history --harness codex --since 7d
+npm install --global token-harness@latest
+token-harness setup
 ```
 
-### Cross-harness scheduling and compact handoff
+That is the whole first-time check. `setup` tells you:
 
-`token-harness schedule` is a read-only recommendation, not an automatic router. In the normal
-installed CLI, unknown five-hour and weekly pace fields are hydrated from the same live budget
-observer used by `token-harness budget`. Candidate quality and transfer benefit are hydrated only
-from attributable project-local benchmark evidence. Missing or conflicting evidence returns
-`insufficient-evidence` instead of guessing.
+- which coding agents it found;
+- whether an optimization provider is active;
+- whether the current setup works;
+- what it changed, if anything;
+- exactly one next step.
 
-Start with the minimal command:
+The first run does not change Claude Code, Codex, or project configuration. If Token
+Harness finds a supported improvement, it shows the safe plan and may suggest:
 
 ```sh
-token-harness schedule \
-  --current claude \
-  --candidate codex \
-  --task-class hard \
-  --handoff-bytes 900
+token-harness setup --yes
 ```
 
-If the task is already in progress, generate a bounded handoff rather than copying the transcript:
+`--yes` is always explicit. The change is backed up, applied transactionally, and
+verified. Unsupported combinations are left untouched.
 
-```sh
-token-harness handoff \
-  --objective "Finish the scheduler change without weakening quota evidence" \
-  --decision "Keep Claude and Codex quota observations provider-local" \
-  --changed-file apps/cli/src/schedule-main.ts \
-  --validation "pnpm test passes" \
-  --unresolved "Need one empirical Codex comparison" \
-  --next-action "Run the candidate benchmark in Codex" \
-  --max-bytes 2048 > handoff.md
-```
+## Open the dashboard
 
-To teach future recommendations whether that handoff was actually worth the switch, capture one
-paired experiment. The baseline and optimized variants use the same benchmark id and task class,
-but different harnesses:
+After setup, run:
 
 ```sh
-# 1. Before doing the task in the current harness.
-token-harness benchmark-start \
-  --benchmark-id scheduler-hard-01 \
-  --variant baseline \
-  --task hard \
-  --harness claude
-
-# Run the baseline task in Claude Code, then record its observed outcome.
-token-harness benchmark-finish \
-  --benchmark-id scheduler-hard-01 \
-  --variant baseline \
-  --quality passed \
-  --attempts 1 \
-  --failed-attempts 0
-
-# 2. Before the candidate run, start the optimized variant.
-token-harness benchmark-start \
-  --benchmark-id scheduler-hard-01 \
-  --variant optimized \
-  --task hard \
-  --harness codex
-
-# Give handoff.md to Codex, run the equivalent task, then close the capture.
-token-harness benchmark-finish \
-  --benchmark-id scheduler-hard-01 \
-  --variant optimized \
-  --quality passed \
-  --attempts 1 \
-  --failed-attempts 0
-
-# 3. Evaluate the exact handoff used by the candidate run.
-token-harness transfer \
-  --benchmark-id scheduler-hard-01 \
-  --handoff-file handoff.md
-
-# 4. Persist the immutable transfer verdict for future schedule calls.
-token-harness transfer-record \
-  --benchmark-id scheduler-hard-01 \
-  --handoff-file handoff.md
+token-harness ui
 ```
 
-`transfer-record` re-validates the project-scoped pair, hashes the exact handoff and writes one
-immutable receipt. Future `schedule` calls consume receipts only for the exact route and task class.
-Every attributable receipt must agree on the same non-unknown transfer verdict; one `unknown` or a
-positive/non-positive conflict keeps the recommendation unresolved. Historical receipt sizes never
-replace the current `--handoff-bytes` value.
-
-Manual evidence flags remain available for controlled experiments and debugging. Explicit values,
-including an explicit `unknown`, always override automatic hydration. Run
-`token-harness schedule --help` for the full list.
+The dashboard opens in your browser and shows harness status, active providers,
+allowance windows, the main recommendation, and the next action. It is a small local
+web page served only on `127.0.0.1`: no Electron app, account, or cloud service.
 
-To try the read-only diagnosis without installing Token Harness globally:
+Use `Ctrl+C` in the terminal to close it. If you do not want it to open a browser:
 
 ```sh
-npx token-harness doctor
+token-harness ui --no-open
 ```
 
-`npx` may download Token Harness into npm's cache, but it does not install or configure RTK,
-HarnessTrim, or a coding agent.
-
-### Managed compatibility rows
-
-Token Harness changes a harness configuration only when a reviewed compatibility row covers the
-exact provider version, harness version, platform, and configuration schema. Four rows ship, and each
-names the recording it stands on:
-
-| Provider | Harness | Platform | Tested versions | Tier |
-| --- | --- | --- | --- | --- |
-| RTK | Claude Code | Windows | rtk 0.44.0, Claude Code 2.1.220 | `canary` |
-| HarnessTrim | Claude Code | Windows | harnesstrim 0.1.0, Claude Code 2.1.220 | `config-only` |
-| HarnessTrim | Codex | Windows | harnesstrim 0.1.0, Codex 0.146.0 | `config-only` |
-| HarnessTrim | Codex | Linux (non-WSL) | harnesstrim 0.2.1, Codex 0.152.1 | `config-only` |
-
-Everything else is refused, and that is the design rather than a gap: `doctor` detects and reports on
-every supported platform, and only the *mutation* is narrower. An uncovered combination exits 9 and
-the diagnostic names what is missing — the reviewed fixture, or the nearest row it does have.
-
-A live Linux recording on 2026-09-02 promoted exactly one combination to managed mutation:
-Codex 0.152.1 + HarnessTrim 0.2.1 on non-WSL Linux. The fixture covers an empty state, brownfield
-user-owned files, skills-only apply, drift, verified rollback, and surgical uninstall. Nearby Codex
-or HarnessTrim versions and WSL remain refused.
-
-What is not covered today, and why:
-
-- **macOS, WSL, and other Linux version combinations.** The recordings a row needs are states of a
-  real machine. Only the exact Linux combination above has been reviewed, so all other combinations
-  continue to refuse managed mutation while detection, verification, and measurement still work.
-- **OpenCode, and permanently rather than pending.** Both providers are detected, adopted, verified
-  and measured there, and neither is written. RTK reaches OpenCode through a plugin module its own
-  installer places globally, which this build has no action for. HarnessTrim's OpenCode installer
-  writes a plugin wrapper *and runs an npm install*, so a containment boundary covering what it wrote
-  would hold a `node_modules` tree — and that is not a decision deferred for want of a fixture. A
-  dependency tree is not configuration, so it cannot be a reviewed write set; snapshotting it on
-  every apply to keep the rollback honest would be slow and would be restoring upstream's install
-  rather than our change; and excluding it would leave a transaction claiming a reversibility it does
-  not have. So the assignment is not producible, and RFC 0003 is explicit about what that means: a
-  capability the provider has but cannot be asked for is not an assignable capability. OpenCode stays
-  adoption-only by decision.
-- **RTK on Codex.** Not managed, and no row: RTK writes a Claude-shaped hook list and nothing else.
-- **A newer Claude Code.** The range is a single observed version. `2.1.221` reads `unknown-newer` and
-  refuses rather than assuming it behaves like `2.1.220`.
-
-The recordings are under `tests/fixtures/rows/`, one directory per row, each with a README stating
-which stages exist and which do not.
-
-## How the components fit together
-
-There are three separate layers. Installing one does not automatically provide the others.
-
-| Layer | Examples | Who installs it? |
-| --- | --- | --- |
-| Coding agent (harness) | Claude Code, Codex, OpenCode, Hermes, Pi | You, using the agent's official installer |
-| Token Harness | `token-harness` | You, from npm or this repository |
-| Optimization provider | RTK, HarnessTrim | Both can be installed by Token Harness where a compatibility row covers the combination; otherwise install them with their own installers and Token Harness detects and measures them |
-
-Token Harness does not install Claude Code, Codex, OpenCode, Hermes, or Pi. Install and run at least one of
-them first so that `token-harness doctor` can detect it.
-
-| Provider | Claude Code | Codex | OpenCode | Hermes | Pi | Installed by Token Harness |
-| --- | --- | --- | --- | --- | --- | --- |
-| RTK | Configure, verify, and measure | Not managed | Detect, adopt, verify, and measure | Not managed | Not managed | **Yes**, for the supported Claude Code path |
-| HarnessTrim | Claude skills only; no reducer hook or reduce-pipe instruction | Detect, adopt, verify, and measure | Detect, adopt, verify, and measure | Detect, verify, and measure | Detect, verify, and measure | **Yes**, on a covered row — see above |
+## Ask your AI to install Token Harness
 
-"Not managed" does not mean the upstream tool cannot support that agent. It means this release
-does not claim ownership of that integration and will not modify it.
+You can give this prompt to Claude Code or Codex:
 
-Hermes is read-only in both directions: the adapter finds the HarnessTrim plugin, reads whether it
-is enabled, and imports the telemetry it writes to `~/.hermes/harnesstrim-metrics.jsonl`, but nothing
-here enables the plugin or restarts the gateway. Enabling it is
-`hermes plugins enable harnesstrim`, and that stays your command to run. No compatibility row ships
-for Hermes because a row is the precondition for a *mutation*, and none is proposed.
-
-Pi is read-only in both directions too: the adapter finds the HarnessTrim extension module in the
-directories Pi auto-loads (`~/.pi/agent/extensions/` and `<project>/.pi/extensions/`) and verifies
-the configuration, but nothing here installs it, and nothing here can say which mode it runs in —
-the extension defaults to `dryrun` and only `HARNESSTRIM_MODE=active` in Pi's environment makes it
-reduce. Installing it is `harnesstrim install pi --apply`, and that stays your command to run. No
-compatibility row ships for Pi because a row is the precondition for a *mutation*, and none is
-proposed.
-
-RTK on OpenCode is detected and verified, not written: `rtk init -g --opencode` installs a plugin
-module at `~/.config/opencode/plugins/rtk.ts`, and Token Harness reads that file rather than
-producing it. Note that the plugin is inert under OpenCode Desktop — see
-[docs/matrices.md](docs/matrices.md) for what was measured.
-
-The generated compatibility tables, tested version ranges, platform coverage, and known
-limitations are in [docs/matrices.md](docs/matrices.md).
-
-## Installing each component
-
-### 1. Install Token Harness
-
-Recommended, from npm:
-
-```sh
-npm install --global token-harness
-token-harness --help
-```
-
-If the command is not found after installation, find npm's global binary directory with:
-
-```sh
-npm prefix --global
+```text
+Install the latest stable Token Harness from npm on this computer, then run
+`token-harness setup`. Do not install or replace Claude Code, Codex, or any
+optimization provider unless Token Harness's supported plan explicitly requires it.
+
+Explain the setup result in plain language: what was detected, what already works,
+what would change, and the single next step. Do not expose credentials, cookies,
+tokens, raw home paths, or private project contents. If setup proposes a supported
+configuration change, show me the short plan and ask before running
+`token-harness setup --yes`. After an approved change, verify it and start
+`token-harness ui`. If anything is unsupported, stop safely and explain why.
 ```
 
-Ensure that directory's executable location is on `PATH`, then open a new terminal.
-
-#### Build and install from source
+The AI should ask before the `--yes` step because that is the point where coding-agent
+configuration may change.
 
-The repository uses the pnpm version declared in `package.json`.
+## What normal output looks like
 
-```sh
-git clone https://github.com/giuliastro/token-harness.git
-cd token-harness
-corepack enable
-pnpm install
-pnpm build
-pnpm package
-npm install --global ./dist/package
-token-harness --version
-```
+Human output is intentionally short:
 
-`pnpm build` creates the self-contained CLI at `dist/bundle/token-harness.mjs`.
-`pnpm package` creates the installable package under `dist/package`.
-If `corepack` is unavailable, install the pinned package manager with
-`npm install --global pnpm@10.33.4` instead.
+```text
+TOKEN HARNESS - READY
 
-### 2. Install or adopt RTK
+DETECTED
+  Claude Code: detected
+  Codex: configured
+  harnesstrim: active on Codex
 
-When a reviewed compatibility row covers the installed versions, you normally do **not** install RTK yourself:
+CHANGES
+  Nothing changed.
 
-```sh
-token-harness plan --harness claude --provider rtk
+NEXT STEP
+  token-harness ui
+  Open the dashboard to see status, allowance, and advice.
 ```
 
-Once a matching compatibility row exists, if RTK is absent, the plan contains two actions:
-
-1. install RTK through the selected package manager;
-2. append one RTK entry to Claude Code's `PreToolUse` hook configuration.
-
-The channel selected by this release is:
-
-| Platform | Channel used by the plan | Required command on `PATH` |
-| --- | --- | --- |
-| Windows | WinGet package `rtk-ai.rtk` | `winget` |
-| macOS | Cargo package `rtk` | `cargo` |
-| Linux and WSL | Cargo package `rtk` | `cargo` |
-
-The Cargo path in this release invokes `cargo install rtk`. That channel is declared but has not
-been exercised by this project, and upstream documents a crates.io name collision. On macOS,
-Linux, and WSL, the safer current route is to install RTK with an upstream-recommended method,
-confirm that `rtk gain` works, and let Token Harness adopt and configure the existing binary.
-
-Review the plan's `Network`, `Elevation`, and `Actions` sections before applying it:
+Need the evidence behind the summary? Add `--verbose`:
 
 ```sh
-token-harness apply --yes --harness claude --provider rtk
+token-harness doctor --verbose
 ```
 
-If RTK is already installed and configured, Token Harness adopts it instead of reinstalling or
-rewriting it. User-owned configuration remains user-owned.
-
-Important boundaries:
-
-- Token Harness writes the reviewed hook itself; it does not run `rtk init`.
-- A package install is not reversed by file rollback. `rollback` restores configuration files,
-  not installed binaries.
-- `uninstall` removes only integration entries written by Token Harness; it deliberately leaves
-  the RTK executable installed.
-- On native Windows, Claude Code exposes both Bash and PowerShell tool families. The current RTK
-  matcher covers Bash only, so `doctor` can correctly report PowerShell as bypassed.
-
-For manual installation or use outside Token Harness's managed surface, follow the
-[RTK installation guide](https://github.com/rtk-ai/rtk/blob/master/INSTALL.md), then run:
+Need stable machine-readable output for automation? Add `--json`:
 
 ```sh
-rtk --version
-rtk gain
-token-harness doctor --provider rtk
+token-harness doctor --json
+token-harness ui --json
 ```
 
-`rtk gain` is an important identity check because another unrelated package also uses the name
-`rtk`.
-
-### 3. Install or adopt HarnessTrim
+`--json` keeps the complete schema-1 result and diagnostics; it is not shortened.
 
-With HarnessTrim on `PATH`, `token-harness plan --harness claude` can install its Claude skills
-without creating the competing Bash hook or reduce-pipe instruction. The invocation it delegates to
-is:
+## Three commands to remember
 
 ```sh
-harnesstrim install claude <project> --apply --no-hook --no-instructions
+token-harness setup
+token-harness ui
+token-harness optimize
 ```
 
-Codex and OpenCode remain adoption-only. Install those integrations with HarnessTrim's own CLI,
-first as a dry run and then with its explicit apply flag. Consult the
-[HarnessTrim README](https://github.com/giuliastro/HarnessTrim#quick-start) because its adapter
-contents, modes, and telemetry differ by coding agent.
+| Command | Answer |
+| --- | --- |
+| `setup` | Is Token Harness ready, and what is my one next step? |
+| `ui` | What is active, how much allowance is visible, and what should I do? |
+| `optimize` | What is the best evidence-based action for the task I am starting? |
 
-After installing it:
+For example:
 
 ```sh
-token-harness doctor --provider harnesstrim
-token-harness status --provider harnesstrim
-token-harness verify --provider harnesstrim
-token-harness metrics --provider harnesstrim --since 7d
+token-harness optimize --task hard --profile quality
+token-harness optimize --task mechanical --profile economy
 ```
 
-Do not configure RTK and HarnessTrim to reduce the same shell output. In the `safe` profile,
-Token Harness gives that exclusive surface to RTK and treats an existing overlap as a hard
-conflict instead of guessing an execution order. It never deletes the competing entry for you.
-
-HarnessTrim telemetry is opt-in in some adapters. Without a `.harnesstrim/metrics.jsonl` file,
-verification can still inspect configuration, but `metrics` has no HarnessTrim events to import.
+## Safety and privacy
 
-From `0.1.0`, HarnessTrim publishes a machine-readable capability declaration: the surfaces it
-intercepts per coding agent, the flags that narrow an install, and the paths each install writes.
+Token Harness is conservative by design:
 
-```sh
-harnesstrim capabilities
-```
+- normal read-only commands do not change coding-agent or project configuration;
+- `setup --yes`, `apply --yes`, `update --yes`, `rollback --yes`, and
+  `uninstall --yes` are the explicit configuration-changing forms;
+- plans are checked again immediately before they are applied;
+- existing files are backed up before a managed write;
+- only exact Token Harness-owned entries are removed by `uninstall`;
+- newer or untested combinations are reported, not guessed;
+- the dashboard binds only to the local loopback address and provides no mutation API;
+- source code, prompts, command contents, credentials, and cookies are not sent to a
+  Token Harness service.
 
-Detection reads that declaration and compares it against the one Token Harness records, so an
-upstream change is reported rather than assumed compatible. A disagreement becomes a
-`provider-capabilities-drift` warning naming both sides. A build older than the command cannot
-answer; Token Harness then falls back to its own recorded declaration and reports nothing, because a
-provider that cannot be asked must still be describable.
+Plans, receipts, metrics, and backups stay in the local Token Harness state directory.
+See [RFC 0004](docs/rfcs/0004-execution-safety-ownership-update.md) for the execution
+model and [RFC 0006](docs/rfcs/0006-cli-contract.md) for CLI/JSON guarantees.
 
-## The recommended operating workflow
+## Supported optimizations
 
-### Step 1: diagnose
+Token Harness can detect and measure several independent local tools:
 
-```sh
-token-harness doctor
-```
+| Provider | Purpose | Management |
+| --- | --- | --- |
+| [RTK](https://github.com/rtk-ai/rtk) | Shell-command rewriting and output reduction | Managed only for reviewed combinations |
+| [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers and harness adapters | Managed only for reviewed combinations |
+| [cclimits](https://github.com/cruzanstx/cclimits) | Optional live/local quota companion | Read-only; never installed automatically |
+| [ccusage](https://github.com/ccusage/ccusage) | Local usage history | Read-only; never installed automatically |
 
-This answers:
+A provider you installed yourself remains yours. Token Harness can adopt observable
+configuration without claiming ownership of the executable.
 
-- which supported coding agents are installed;
-- which providers are installed and runnable;
-- which agent configuration files exist;
-- which provider is wired to which agent;
-- whether Token Harness owns the integration or merely adopted it;
-- whether a version, configuration file, or tool-family matcher needs attention;
-- whether the installed provider's own capability declaration still agrees with the one Token
-  Harness records.
+Exact reviewed provider/harness/platform/version combinations are generated in
+[docs/matrices.md](docs/matrices.md). A combination outside that table can still be
+detected and inspected, but Token Harness will not mutate it.
 
-Common states:
+## Advanced commands
 
-| State | Meaning |
-| --- | --- |
-| `not found` / `absent` | The executable and usable configuration were not detected |
-| `installed` | The provider runs but is not connected to a supported agent |
-| `configured` | A relevant hook or plugin entry exists |
-| `broken` | Configuration refers to something missing or unreadable |
-| `set up by you` | Token Harness adopted existing configuration and will not remove it |
-| `set up by this tool` | A committed Token Harness transaction owns the exact entry |
+Most people do not need this section. Run `token-harness <command> --help` for details.
 
-`doctor` is diagnostic. An empty machine is a valid state and exits successfully.
+| Command | Purpose | Changes agent/project config? |
+| --- | --- | --- |
+| `doctor` | Detect harnesses, providers, versions, and problems | No |
+| `budget` | Read authoritative/reported allowance windows | No |
+| `context` | Inspect model settings, instructions, and MCP exposure | No |
+| `mcp` | Focus on MCP server/tool health | No |
+| `history` | Summarize local usage through an installed ccusage | No |
+| `plan` | Prepare exact supported changes | No; stores local plan state |
+| `apply` | Apply a reviewed stored plan | Yes, only with `--yes` |
+| `verify` | Check the declared integration tier | No |
+| `metrics` | Report attributable reducer savings | No |
+| `status` | Report pipelines, drift, and importer modes | No |
+| `update` | Check/update installed providers | Yes, only with `--yes` |
+| `rollback` | Restore the latest transaction snapshot | Yes, only with `--yes` |
+| `uninstall` | Remove owned integration entries | Yes, only with `--yes` |
+| `schedule` | Compare Claude Code and Codex using available evidence | No |
+| `handoff` | Build a bounded cross-harness handoff | No |
+| `benchmark*`, `transfer*` | Capture and compare empirical evidence | Local state only |
 
-### Step 2: review the plan
+## Troubleshooting
 
-```sh
-token-harness plan
-```
+### `token-harness` is not found
 
-Narrow the operation when useful:
+Check that Node is new enough and the package is installed:
 
 ```sh
-token-harness plan --harness claude
-token-harness plan --provider rtk
-token-harness plan --project /path/to/project
+node --version
+npm list --global token-harness
 ```
 
-Read these sections before proceeding:
-
-- `Capability ownership`: which provider is allowed to transform each surface;
-- `Excluded`: detected providers intentionally left out;
-- `Actions`: every package operation and file change;
-- `Network`: destinations contacted by later mutation;
-- `Elevation`: whether administrator/root access would be required;
-- `Backups`: how many files will be snapshotted.
-
-`plan` does not modify agent or project configuration. It may persist the serialized plan in
-Token Harness's private state directory so the exact reviewed artifact can be applied later.
+Node must be at least 22.13. Reopen the terminal after installation if needed.
 
-If the plan prints an ID, apply that exact plan with:
+### Setup needs attention
 
-```sh
-token-harness apply --plan <plan-id> --yes
-```
-
-The stored plan is rejected before any action runs if the project, versions, ownership, or file
-preconditions changed after review.
-
-### Step 3: apply
+Run the single command it prints. For technical evidence:
 
 ```sh
-token-harness apply --yes
+token-harness doctor --verbose
 ```
 
-Without `--yes`, `apply` shows what it would do and exits with code 8. Every affected file is
-snapshotted before mutation, including the prior absence of a newly created file. A failure
-triggers automatic restoration and the result states whether that restoration was verified.
-
-After a successful apply, restart the coding agent so it reloads its hooks or plugins.
-
-### Step 4: create real traffic
+Do not force an unsupported plan. Open an issue with the redacted `--json` result if
+you believe the combination should be supported.
 
-Passive verification needs evidence from an operation that actually passed through the provider.
-Open the configured coding agent and ask it to run a normal shell command such as `git status` or
-a test command. Then return to the terminal.
+### Verification says `not-exercised`
 
-### Step 5: verify configuration and execution
-
-Use both commands; they answer different questions:
+Restart the coding agent, use it for one normal command, and run:
 
 ```sh
-token-harness status
 token-harness verify
 ```
 
-`status` compares the live environment with committed receipts. It finds drift, changed versions,
-and competing entries on exclusive surfaces.
-
-`verify` checks the strongest evidence the integration declares:
-
-| Tier | What it proves |
-| --- | --- |
-| `presence` | The executable resolves and reports a version |
-| `config-only` | The expected configuration entry exists |
-| `canary` | Provider records show a real operation crossed the interception point |
-
-`config-only` is not proof that the hook ran. It is the honest ceiling for integrations whose
-runtime state cannot be observed externally.
+No observed operation is different from a failed integration, so Token Harness reports
+the two states separately.
 
-`not-exercised` means no attributable operation has been observed yet. It is neither success nor
-failure: run a command through the agent and check again.
+## Updating or undoing
 
-### Step 6: inspect savings
+Update the CLI:
 
 ```sh
-token-harness metrics
-token-harness metrics --since 24h
-token-harness metrics --since 2026-07-01 --until 2026-08-01
-token-harness metrics --provider rtk --since 7d
+npm install --global token-harness@latest
+token-harness setup
 ```
 
-The default window is seven days. Durations such as `12h`, `7d`, and `2w`, plus ISO dates, are
-accepted. Date boundaries are midnight UTC.
-
-The report keeps measurement types and units separate:
-
-| Report line | Interpretation |
-| --- | --- |
-| `Exact local` | Before and after token counts were observed for the same operation |
-| `Estimated local` | The payload changed, but the reported unit or tokenizer is an estimate |
-| `Counterfactual` | A dry run measured what could have changed; it is not realized saving |
-| `End-to-end billed` | Comparable billed sessions were measured; otherwise it says `no A/B run` |
-| `Coverage` | Share of relevant operations that were actually changed |
-| `Bypassed` | Operations observed but passed through unchanged or outside coverage |
-
-Token counts are never added to character counts, and estimated or counterfactual values are never
-silently merged into an exact total.
-
-The report covers one project: the one `--project` names, or the current directory. An operation a
-provider recorded without a directory belongs to no project and is excluded, with a count reported
-so the difference is reconcilable. When no project identity can be established the report says so
-rather than presenting every project's events as one project's figures.
-
-## Undoing changes
-
-Choose the command based on what you want to undo:
+Remove only Token Harness-owned integration entries:
 
 ```sh
-# Remove only exact integration entries owned by Token Harness.
 token-harness uninstall --yes
-
-# Restore all files from the most recent committed transaction snapshot.
-token-harness rollback --yes
-```
-
-`uninstall` is usually the safer choice after subsequent manual edits: it is surgical and refuses
-to remove an owned entry if its content no longer matches what Token Harness wrote.
-
-`rollback` restores whole files to their pre-transaction bytes. Changes made to those files after
-the transaction are therefore also reverted. It does not restore or remove provider packages.
-
-Neither command removes user-owned RTK or HarnessTrim configuration.
-
-## Command reference
-
-| Command | Purpose | Changes agent/project configuration? |
-| --- | --- | --- |
-| `doctor` | Detect agents, providers, ownership, versions, and problems | No |
-| `budget` | Read live quota/headroom windows where the harness exposes them | No |
-| `context` | Inspect effective model/config, instructions, MCP exposure, and tool inventory | No |
-| `mcp` | Inspect MCP servers and tool-schema exposure | No |
-| `history` | Summarize attributable local usage history | No |
-| `optimize` | Combine quota pacing, context pressure, and task/profile policy into advice | No |
-| `schedule` | Recommend Claude Code or Codex from independently attributable evidence | No |
-| `handoff` | Build a bounded compact handoff for an in-progress cross-harness move | No |
-| `plan` | Resolve ownership and preview exact actions; use `--native-policy` for supported harness-native changes | No; stores the plan in private state |
-| `apply` | Apply a reviewed plan transactionally | Yes, only with `--yes` |
-| `status` | Detect drift and competing hooks | No |
-| `verify` | Check the declared verification tier | No |
-| `metrics` | Import provider records and report savings | No; updates only Token Harness state |
-| `benchmark` | Compare an explicit baseline/optimized receipt pair | No |
-| `benchmark-start` | Start an empirical task capture | No agent/project config change; records Token Harness benchmark state |
-| `benchmark-finish` | Finish an empirical task capture and record the outcome | No agent/project config change; records Token Harness benchmark state |
-| `benchmark-matrix` | Aggregate complete project-scoped benchmark pairs by task class and evidence | No |
-| `transfer` | Evaluate one empirical cross-harness benchmark pair and exact handoff | No |
-| `transfer-record` | Persist one immutable project-scoped transfer evidence receipt | No agent/project config change; records Token Harness benchmark state |
-| `update` | Query channels and update installed providers | Yes, only with `--yes` |
-| `rollback` | Restore files from the latest committed transaction | Yes, only with `--yes` |
-| `uninstall` | Remove owned integration entries | Yes, only with `--yes` |
-
-Every command supports `--help`. Common filters are:
-
-```text
---harness <id>
---provider <id>
---project <directory>
---task mechanical|standard|hard|critical
---profile economy|balanced|quality|custom
---reserve <percent>
---native-policy
---plan <plan-id>
---json
 ```
 
-## Automation and JSON output
-
-Use `--json` in scripts:
+Restore complete files from the latest committed transaction snapshot:
 
 ```sh
-token-harness doctor --json
-token-harness verify --json
-token-harness metrics --since 7d --json
-```
-
-stdout contains exactly one JSON document with this top-level contract:
-
-```json
-{
-  "schemaVersion": 1,
-  "command": "verify",
-  "toolVersion": "0.1.0",
-  "status": "ok",
-  "exitCode": 0,
-  "data": {},
-  "diagnostics": []
-}
+token-harness rollback --yes
 ```
 
-Important exit codes:
-
-| Code | Meaning |
-| ---: | --- |
-| 0 | Completed with nothing actionable |
-| 2 | Invalid command or argument |
-| 3 | A read-only check found an actionable problem |
-| 4 | A capability conflict blocks the plan |
-| 5 | The environment drifted from the stored plan or journal |
-| 6 | Mutation failed and rollback was verified |
-| 7 | Mutation failed and state was not fully restored; inspect the named paths |
-| 8 | The command needs explicit confirmation (`--yes`) |
-| 9 | Unsupported or unverifiable environment |
-
-Do not treat every non-zero code as the same failure. In particular, code 8 is the expected result
-of previewing a mutating command without approval.
-
-## State, backups, and privacy
-
-Token Harness stores plans, journals, backups, receipts, import cursors, and normalized metrics
-outside the repository:
-
-| Platform | Default state root |
-| --- | --- |
-| Windows | `%LOCALAPPDATA%\TokenHarness` |
-| macOS | `~/Library/Application Support/TokenHarness` |
-| Linux and WSL | `${XDG_STATE_HOME:-~/.local/state}/token-harness` |
-
-Normalized metrics do not contain raw command text, tool output, source code, prompts, credentials,
-or raw file paths. Provider records are read in place; Token Harness imports only normalized event
-data.
-
-## Troubleshooting
-
-### `token-harness` is not found
+`rollback` is whole-file time travel, so it can also revert later manual edits to those
+files. Prefer `uninstall` when you only want to remove Token Harness-owned entries.
 
-Confirm Node and the global npm installation:
-
-```sh
-node --version
-npm list --global token-harness
-npm prefix --global
-```
-
-Node must be at least 22.13.0. Add npm's global executable directory to `PATH`, then reopen the
-terminal.
-
-### `plan` says there is nothing to do
-
-Run `token-harness doctor`. The usual causes are:
-
-- no supported coding agent was detected;
-- the requested provider does not claim that coding agent in this release;
-- an existing user-managed integration already satisfies the target state;
-- the safe profile excluded an overlapping provider.
-
-RTK is written only for Claude Code in 0.1.0. It claims OpenCode too, but the plan builder appends
-a `hooks` entry, which is Claude Code's schema — OpenCode's integration is a plugin module, so an
-OpenCode scope produces no action and the existing installation is adopted instead. A Codex-only
-machine produces no RTK action at all.
-
-### The plan is blocked by `exclusive-scope-contested`
-
-RTK and HarnessTrim both claim the same reducing surface. Token Harness will not choose an order or
-overwrite either configuration. Remove or disable one integration using the tool that owns it, then
-run `doctor` and `plan` again.
-
-### `verify` reports `not-exercised`
-
-Restart the coding agent, ask it to run a shell command through the configured tool family, then
-run `token-harness verify` again. For a `config-only` integration, no stronger external receipt may
-exist; the output states that limitation explicitly.
-
-### `metrics` shows no data
-
-Check all of the following:
-
-- the provider has processed at least one operation in the requested time window;
-- `rtk gain` works for RTK;
-- HarnessTrim telemetry is enabled and `.harnesstrim/metrics.jsonl` exists for the project;
-- `--project` points to the project whose records you expect;
-- `--since` is not excluding older events.
-
-An empty metrics report exits 0 because it is a valid observation, not a command failure.
-
-### `doctor` or `status` reports `provider-capabilities-drift`
-
-The installed provider's own capability declaration no longer agrees with the one Token Harness
-records. The warning names both sides: what the recorded declaration claims, and what the installed
-build reported. Nothing is modified, and the recorded declaration still drives planning.
-
-Three disagreements are reported:
-
-- a coding agent that Token Harness records a capability on is missing from the build's declaration;
-- the reduction surface Token Harness records is absent from the surfaces the build reports;
-- the build no longer covers a reviewed write-set path, or declares a path outside the reviewed
-  containment boundary.
-
-The last one matters most before a delegated install. Rollback restores the reviewed boundary, so a
-path outside it would survive a rollback. Re-review the write set at the installed version, or hold
-at the reviewed one.
-
-### A newer provider or agent version is reported
-
-The tested ranges record versions actually exercised by this project. A newer version is reported
-and handled conservatively rather than assumed compatible. Check [docs/matrices.md](docs/matrices.md)
-and the upstream release notes before applying configuration changes.
-
-## Development
+## Develop from source
 
 ```sh
+git clone https://github.com/giuliastro/token-harness.git
+cd token-harness
 corepack enable
 pnpm install
 pnpm typecheck
@@ -841,15 +265,10 @@ pnpm package
 pnpm smoke:install
 ```
 
-Tests use temporary homes and fake process runners; they do not install third-party tools.
-`pnpm smoke` runs the bundle from outside the workspace, and `pnpm smoke:install` validates the
-packed npm artifact.
-
-Before changing architecture or public behavior, read [PLAN.md](PLAN.md) and the accepted RFCs in
-[docs/rfcs](docs/rfcs). The CLI and JSON contract is defined by
-[RFC 0006](docs/rfcs/0006-cli-contract.md).
+Read [PLAN.md](PLAN.md) and the accepted [RFCs](docs/rfcs) before changing public
+behavior or architecture.
 
 ## License
 
-Token Harness is licensed under the [Apache License 2.0](LICENSE). RTK and HarnessTrim are
-independent upstream projects distributed under their own licenses.
+[Apache License 2.0](LICENSE). Referenced provider tools are independent projects with
+their own licenses.