@bilalimamoglu/sift 0.3.1 → 0.3.3

package/README.md

@@ -1,436 +1,245 @@
 # sift
 
-<img src="assets/brand/sift-logo-badge-monochrome.svg" alt="sift logo" width="88" />
+[![npm version](https://img.shields.io/npm/v/@bilalimamoglu/sift)](https://www.npmjs.com/package/@bilalimamoglu/sift)
+[![license](https://img.shields.io/github/license/bilalimamoglu/sift)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/bilalimamoglu/sift/ci.yml?branch=main&label=CI)](https://github.com/bilalimamoglu/sift/actions/workflows/ci.yml)
 
-`sift` turns a long terminal wall of text into a short answer you can act on.
+<img src="assets/brand/sift-logo-minimal-teal-default.svg" alt="sift logo" width="140" />
 
-Think of it like this:
-- `standard` = map
-- `focused` or `rerun --remaining` = zoom
-- raw traceback = last resort
-
-It is a good fit when a human, agent, or CI job needs the answer faster than it needs the whole log.
-
-Common uses:
-- test failures
-- typecheck failures
-- lint failures
-- build logs
-- `git diff`
-- `npm audit`
-- `terraform plan`
+Your AI agent should not be reading 13,000 lines of test output.
 
-Do not use it when:
-- the exact raw log is the main thing you need
-- the command is interactive or TUI-based
-- shell behavior depends on exact raw command output
-
-## Install
-
-Requires Node.js 20 or later.
+**Before:** 128 failures, 198K tokens, 16 tool calls, agent reconstructs the failure shape from scratch.
+**After:** 6 lines, 129 tokens, 4 tool calls, agent acts on a grouped diagnosis immediately.
 
 ```bash
-npm install -g @bilalimamoglu/sift
-```
-
-## One-time setup
-
-The easiest setup path is:
-
-```bash
-sift config setup
+sift exec --preset test-status -- pytest -q
 ```
 
-That writes a machine-wide config to:
-
 ```text
-~/.config/sift/config.yaml
+- Tests did not pass.
+- 3 tests failed. 125 errors occurred.
+- Shared blocker: 125 errors share the same root cause - a missing test environment variable.
+  Anchor: tests/conftest.py
+  Fix: Set the required env var before rerunning DB-isolated tests.
+- Contract drift: 3 snapshot tests are out of sync with the current API or model state.
+  Anchor: tests/contracts/test_feature_manifest_freeze.py
+  Fix: Regenerate the snapshots if the changes are intentional.
+- Decision: stop and act.
 ```
 
-After that, any terminal on the machine can use `sift`. A repo-local config can still override it later.
+If 125 tests fail for one reason, the agent should pay for that reason once.
 
-To switch between saved native providers without editing YAML:
+## Who is this for
 
-```bash
-sift config use openai
-sift config use openrouter
-```
+Developers using coding agents — Claude Code, Codex, Cursor, Windsurf, Copilot, or any LLM-driven workflow that runs shell commands and reads the output.
+
+`sift` sits between the command and the agent. It captures noisy output, groups repeated failures into root-cause buckets, and returns a short diagnosis with an anchor, a likely fix, and a decision signal. The agent gets a map instead of a wall of text.
 
-If you prefer manual setup, this is the smallest useful OpenAI setup:
+## Install
 
 ```bash
-export SIFT_PROVIDER=openai
-export SIFT_BASE_URL=https://api.openai.com/v1
-export SIFT_MODEL=gpt-5-nano
-export OPENAI_API_KEY=your_openai_api_key
+npm install -g @bilalimamoglu/sift
 ```
 
-If you prefer manual setup, this is the smallest useful OpenRouter setup:
+Requires Node.js 20+.
 
-```bash
-export SIFT_PROVIDER=openrouter
-export OPENROUTER_API_KEY=your_openrouter_api_key
-```
+## Quick start
 
-Then check it:
+Guided setup writes a machine-wide config and verifies the provider:
 
 ```bash
+sift config setup
 sift doctor
 ```
 
-## Start here
-
-The default path is simple:
-1. run the noisy command through `sift`
-2. read the short `standard` answer first
-3. only zoom in if `standard` clearly tells you more detail is still worth it
+Config lives at `~/.config/sift/config.yaml`. A repo-local `sift.config.yaml` can override it later.
 
-Examples:
+Then run noisy commands through `sift`:
 
 ```bash
+sift exec --preset test-status -- <test command>
 sift exec "what changed?" -- git diff
-sift exec --preset test-status -- pytest -q
-sift rerun
-sift rerun --remaining --detail focused
-sift rerun --remaining --detail verbose --show-raw
-sift watch "what changed between cycles?" < watcher-output.txt
-sift exec --watch "what changed between cycles?" -- node watcher.js
-sift exec --preset typecheck-summary -- npm run typecheck
-sift exec --preset lint-failures -- eslint .
 sift exec --preset audit-critical -- npm audit
 sift exec --preset infra-risk -- terraform plan
-sift agent install codex --dry-run
 ```
 
-## Simple workflow
+Useful flags:
+- `--dry-run` to preview the reduced input and prompt without calling a provider
+- `--show-raw` to print captured raw output to `stderr`
+- `--fail-on` to let reduced results fail CI for commands such as `npm audit` or `terraform plan`
 
-For most repos, this is the whole story:
+If you prefer environment variables instead of setup:
 
 ```bash
-sift exec --preset test-status -- <test command>
-sift rerun
-sift rerun --remaining --detail focused
-```
-
-Mental model:
-- `sift escalate` = same cached output, deeper render
-- `sift rerun` = rerun the cached full command at `standard` and prepend what resolved, remained, or changed
-- `sift rerun --remaining` = rerun only the remaining failing pytest node IDs for a zoomed-in view
-- `sift watch` / `sift exec --watch` = treat redraw-style output as cycles and summarize what changed
-- `Decision: stop and act` = trust the current diagnosis and go read or fix code
-- `Decision: zoom` = one deeper sift pass is justified before raw
-- `Decision: raw only if exact traceback is required` = raw is last resort, not the next default step
-
-If your project uses `pytest`, `vitest`, `jest`, `bun test`, or another test runner instead of `npm test`, use the same preset with that command.
-
-What `sift` does in `exec` mode:
-1. runs the child command
-2. captures `stdout` and `stderr`
-3. keeps the useful signal
-4. returns a short answer or JSON
-5. preserves the child command exit code
-
-Useful debug flags:
-- `--dry-run`: show the reduced input and prompt without calling the provider
-- `--show-raw`: print the captured raw input to `stderr`
-
-## When tests fail
+# OpenAI
+export SIFT_PROVIDER=openai
+export SIFT_BASE_URL=https://api.openai.com/v1
+export SIFT_MODEL=gpt-5-nano
+export OPENAI_API_KEY=your_openai_api_key
 
-Start with the map:
+# OpenRouter
+export SIFT_PROVIDER=openrouter
+export OPENROUTER_API_KEY=your_openrouter_api_key
 
-```bash
-sift exec --preset test-status -- <test command>
+# Any OpenAI-compatible endpoint
+export SIFT_PROVIDER=openai-compatible
+export SIFT_BASE_URL=https://your-endpoint/v1
+export SIFT_PROVIDER_API_KEY=your_api_key
 ```
 
-If `standard` already names the main failure buckets, counts, and hints, stop there and read code.
+## How it works
 
-If `standard` still includes an unknown bucket or ends with `Decision: zoom`, do one deeper sift pass before you fall back to raw traceback.
+`sift` follows a cheapest-first pipeline:
 
-Then use this order:
-1. `sift exec --preset test-status -- <test command>`
-2. `sift rerun`
-3. `sift rerun --remaining --detail focused`
-4. `sift rerun --remaining --detail verbose`
-5. `sift rerun --remaining --detail verbose --show-raw`
-6. raw pytest only if exact traceback lines are still needed
+1. Capture command output.
+2. Sanitize sensitive-looking material.
+3. Apply local heuristics for known failure shapes.
+4. Escalate to a cheaper provider only if needed.
+5. Return a short diagnosis to the main agent.
 
-The normal stop budget is `standard` first, then at most one zoom step before raw.
+The core abstraction is a **bucket** — one distinct root cause, no matter how many tests it affects. Instead of making an agent reason over 125 repeated tracebacks, `sift` compresses them into one actionable bucket with a label, an affected count, an anchor, and a likely fix.
 
-If you want the older explicit compare shape, `sift exec --preset test-status --diff -- <test command>` still works. `sift rerun` is the shorter normal path for the same idea.
+It also returns a decision signal:
+- `stop and act` when the diagnosis is already actionable
+- `zoom` when one deeper pass is justified
+- raw logs only as a last resort
 
-## Diagnose JSON
+The deepest local coverage today is test debugging, especially `pytest`, with growing support for `vitest` and `jest`.
 
-Most of the time, you do not need JSON. Start with text first.
+## Built-in presets
 
-If `standard` already shows bucket-level root cause, `Anchor`, and `Fix`, do not re-verify the same bucket with raw pytest. At most do one targeted source read before you edit.
+Every preset runs local heuristics first. When the heuristic confidently handles the output, the provider is never called — zero tokens, zero latency, fully deterministic.
 
-If diagnose output still contains an unknown bucket or `Decision: zoom`, take one sift zoom step before raw traceback.
+| Preset | Heuristic | What it does |
+|--------|-----------|-------------|
+| `test-status` | Deep | Bucket/anchor/decision system for pytest, vitest, jest. 30+ failure patterns, confidence-gated stop/zoom decisions. |
+| `typecheck-summary` | Deterministic | Parses `tsc` output (standard and pretty formats), groups by error code, returns max 5 bullets. |
+| `lint-failures` | Deterministic | Parses ESLint stylish output, groups by rule, distinguishes errors from warnings, detects fixable hints. |
+| `audit-critical` | Deterministic | Extracts high/critical vulnerabilities from `npm audit` or similar. |
+| `infra-risk` | Deterministic | Detects destructive signals in `terraform plan` output. Returns pass/fail verdict. |
+| `build-failure` | Deterministic-first | Extracts the first concrete build error for recognized webpack, esbuild/Vite, Cargo, Go, GCC/Clang, and `tsc --build` output; falls back to the provider for unsupported formats. |
+| `diff-summary` | Provider | Summarizes changes and risks in diff output. |
+| `log-errors` | Provider | Extracts top error signals from log output. |
 
-Use diagnose JSON only when automation or machine branching really needs it:
+Presets marked **Deterministic** bypass the provider entirely for recognized output formats. Presets marked **Deterministic-first** try a local heuristic first and fall back to the provider only when the captured output is unsupported or ambiguous. Presets marked **Provider** always call the LLM but benefit from input sanitization and truncation.
 
 ```bash
-sift exec --preset test-status --goal diagnose --format json -- pytest -q
-sift rerun --goal diagnose --format json
-sift watch --preset test-status --goal diagnose --format json < pytest-watch.txt
+sift exec --preset typecheck-summary -- npx tsc --noEmit
+sift exec --preset lint-failures -- npx eslint src/
+sift exec --preset build-failure -- npm run build
+sift exec --preset audit-critical -- npm audit
+sift exec --preset infra-risk -- terraform plan
 ```
 
-Default diagnose JSON is summary-first:
-- `remaining_summary` and `resolved_summary` keep the answer small
-- `read_targets` points to the first file or line worth reading
-- `read_targets.context_hint` can tell an agent to read only a small line window first
-- if `context_hint` only includes `search_hint`, search for that string before reading the whole file
-- `remaining_subset_available` tells you whether `sift rerun --remaining` can zoom safely
+On an interactive terminal, `sift` also shows a small stderr footer so humans can see whether the provider was skipped:
 
-If an agent truly needs every raw failing test ID, opt in:
-
-```bash
-sift exec --preset test-status --goal diagnose --format json --include-test-ids -- pytest -q
+```text
+[sift: heuristic • LLM skipped • summary 47ms]
+[sift: provider • LLM used • 380 tokens • summary 1.2s]
 ```
 
-`--goal diagnose --format json` is currently supported only for `test-status`, `rerun`, and `test-status` watch flows.
-
-## Watch mode
-
-Use watch mode when command output redraws or repeats and you care about cycle-to-cycle change summaries more than the raw stream:
+Suppress the footer with `--quiet`:
 
 ```bash
-sift watch "what changed between cycles?" < watcher-output.txt
-sift exec --watch "what changed between cycles?" -- node watcher.js
-sift exec --watch --preset test-status -- pytest -f
+sift exec --preset typecheck-summary --quiet -- npx tsc --noEmit
 ```
 
-`sift watch` keeps the current summary and change summary together:
-- cycle 1 = current state
-- later cycles = what changed, what resolved, what stayed, and the next best action
-- for `test-status`, resolved tests drop out and remaining failures stay in focus
-
-If the stream clearly looks like a redraw/watch session, `sift` can auto-switch to watch handling and prints a short stderr note when it does.
+## Test debugging workflow
 
-## `test-status` detail modes
+This is where `sift` is strongest today.
 
-If you are running `npm test` and want `sift` to check the result, use `--preset test-status`.
-
-`test-status` becomes test-aware because you chose the preset. It does **not** infer “this is a test command” from `pytest`, `vitest`, `npm test`, or any other runner name.
-
-Available detail levels:
-
-- `standard`
-  - short default summary
-  - no file list
-- `focused`
-  - groups failures by error type
-  - shows a few representative failing tests or modules
-- `verbose`
-  - flat list of visible failing tests or modules and their normalized reason
-  - useful when Codex needs to know exactly what to fix first
-
-Examples:
-
-```bash
-sift exec --preset test-status -- npm test
-sift rerun
-sift rerun --remaining --detail focused
-sift rerun --remaining --detail verbose
-sift rerun --remaining --detail verbose --show-raw
-```
+Think of it like this:
+- `standard` = map
+- `focused` = zoom
+- raw traceback = last resort
 
-If you use a different runner, swap in your command:
+Typical loop:
 
 ```bash
-sift exec --preset test-status -- pytest
+sift exec --preset test-status -- <test command>
 sift rerun
 sift rerun --remaining --detail focused
-sift rerun --remaining --detail verbose --show-raw
 ```
 
-`sift rerun --remaining` currently supports only cached argv-mode `pytest ...` or `python -m pytest ...` runs. If the cached command is not subset-capable, run a narrowed pytest command manually with `sift exec --preset test-status -- <narrowed pytest command>`.
-
-Typical shapes:
+If `standard` already gives you the root cause, anchor, and fix, stop there and act.
 
-`standard`
-```text
-- Tests did not complete.
-- 114 errors occurred during collection.
-- Import/dependency blocker: repeated collection failures are caused by missing dependencies.
-- Anchor: path/to/failing_test.py
-- Fix: Install the missing dependencies and rerun the affected tests.
-- Decision: stop and act. Do not escalate unless you need exact traceback lines.
-- Next: Fix bucket 1 first, then rerun the full suite at standard.
-- Stop signal: diagnosis complete; raw not needed.
-```
-
-`standard` can also separate more than one failure family in a single pass:
-```text
-- Tests did not pass.
-- 3 tests failed. 124 errors occurred.
-- Shared blocker: DB-isolated tests are missing a required test env var.
-- Anchor: search <TEST_ENV_VAR> in path/to/test_setup.py
-- Fix: Set the required test env var and rerun the suite.
-- Contract drift: snapshot expectations are out of sync with the current API or model state.
-- Anchor: search <route-or-entity> in path/to/freeze_test.py
-- Fix: Review the drift and regenerate the snapshots if the change is intentional.
-- Decision: stop and act. Do not escalate unless you need exact traceback lines.
-- Next: Fix bucket 1 first, then rerun the full suite at standard. Secondary buckets are already visible behind it.
-- Stop signal: diagnosis complete; raw not needed.
-```
-
-`focused`
-```text
-- Tests did not complete.
-- 114 errors occurred during collection.
-- Import/dependency blocker: missing dependencies are blocking collection.
-  - Missing modules include <module-a>, <module-b>.
-  - path/to/test_a.py -> missing module: <module-a>
-  - path/to/test_b.py -> missing module: <module-b>
-  - Hint: Install the missing dependencies and rerun the affected tests.
- - Next: Fix bucket 1 first, then rerun the full suite at standard.
- - Stop signal: diagnosis complete; raw not needed.
-```
-
-`verbose`
-```text
-- Tests did not complete.
-- 114 errors occurred during collection.
-- Import/dependency blocker: missing dependencies are blocking collection.
-  - path/to/test_a.py -> missing module: <module-a>
-  - path/to/test_b.py -> missing module: <module-b>
-  - path/to/test_c.py -> missing module: <module-c>
-  - Hint: Install the missing dependencies and rerun the affected tests.
- - Next: Fix bucket 1 first, then rerun the full suite at standard.
- - Stop signal: diagnosis complete; raw not needed.
-```
-
-Recommended debugging order for tests:
-1. Use `standard` for the full suite first.
-2. Treat `standard` as the map. If it already shows bucket-level root cause, `Anchor`, and `Fix`, trust it and report or act from there directly.
-3. Use `sift escalate` only when you want a deeper render of the same cached output without rerunning the command.
-4. After fixing something, run `sift rerun` to refresh the full-suite truth at `standard`.
-5. Only then use `sift rerun --remaining --detail focused` as the zoom lens after the full-suite truth is refreshed.
-6. Then use `sift rerun --remaining --detail verbose`.
-7. Then use `sift rerun --remaining --detail verbose --show-raw`.
-8. Fall back to the raw pytest command only if you still need exact traceback lines for the remaining failing subset.
-
-## Built-in presets
-
-- `test-status`: summarize test runs
-- `typecheck-summary`: group blocking type errors by root cause
-- `lint-failures`: group repeated lint violations and highlight the files or rules that matter
-- `audit-critical`: extract only high and critical vulnerabilities
-- `infra-risk`: return a safety verdict for infra changes
-- `diff-summary`: summarize code changes and risks
-- `build-failure`: explain the most likely build failure
-- `log-errors`: extract the most relevant error signals
-
-List or inspect them:
-
-```bash
-sift presets list
-sift presets show test-status
-```
+`sift rerun --remaining` currently supports only cached `pytest` or `python -m pytest` runs. For other runners, rerun a narrowed command manually with `sift exec --preset test-status -- <narrowed command>`.
 
 ## Agent setup
 
-If you want Codex or Claude Code to use `sift` by default, let `sift` install a managed instruction block for you.
-
-Repo scope is the default because it is safer:
+`sift` can install a managed instruction block so coding agents use it by default for long command output:
 
 ```bash
-sift agent show codex
-sift agent show codex --raw
-sift agent install codex --dry-run
-sift agent install codex --dry-run --raw
-sift agent install codex
 sift agent install claude
+sift agent install codex
 ```
 
-You can also install machine-wide instructions explicitly:
-
-```bash
-sift agent install codex --scope global
-sift agent install claude --scope global
-```
-
-Useful commands:
+This writes a tuned set of rules into your agent's config (CLAUDE.md, AGENTS.md, etc.) so the agent routes noisy commands through `sift` automatically — no manual prompting needed.
 
 ```bash
 sift agent status
-sift agent remove codex
+sift agent show claude
 sift agent remove claude
 ```
 
-`sift agent show ...` is a preview. It also tells you whether the managed block is already installed in the current scope.
-
-What the installer does:
-- writes to `AGENTS.md` or `CLAUDE.md` by default in the current repo
-- uses marked managed blocks instead of rewriting the whole file
-- preserves your surrounding notes and instructions
-- can use global files when you explicitly choose `--scope global`
-- keeps previews short by default
-- shows the exact managed block or final dry-run content only with `--raw`
+## Where `sift` helps most
 
-What the managed block tells the agent:
-- start with `sift` for long non-interactive command output so the agent spends less context-window and token budget on raw logs
-- for tests, begin with the normal `test-status` summary
-- if `standard` already identifies the main buckets, stop there instead of escalating automatically
-- use `sift escalate` only for the same cached output when more detail is needed without rerunning the command
-- after a fix, refresh the truth with `sift rerun`
-- only then zoom into the remaining failing pytest subset with `sift rerun --remaining --detail focused`, then `verbose`, then `--show-raw`
-- fall back to the raw test command only when exact traceback lines are still needed
+`sift` is strongest when output is:
+- long
+- repetitive
+- triage-heavy
+- shaped by a small number of root causes
 
-## CI-friendly usage
+Good fits:
+- large `pytest`, `vitest`, or `jest` runs (deterministic heuristics)
+- `tsc` type errors and `eslint` lint failures (deterministic heuristics)
+- build failures from webpack, esbuild, cargo, go, gcc
+- `npm audit` and `terraform plan` (deterministic heuristics)
+- repeated CI blockers
+- noisy diffs and log streams
 
-Some commands succeed technically but should still block CI. `--fail-on` handles that for the built-in semantic presets that have stable machine-readable output:
+## Where it helps less
 
-```bash
-sift exec --preset audit-critical --fail-on -- npm audit
-sift exec --preset infra-risk --fail-on -- terraform plan
-```
+`sift` adds less value when:
+- the output is already short and obvious
+- the command is interactive or TUI-based
+- the exact raw log matters
+- the output does not expose enough evidence for reliable grouping
 
-Supported presets for `--fail-on`:
-- `audit-critical`
-- `infra-risk`
+When it cannot be confident, it tells you to zoom or read raw instead of pretending certainty.
 
-## Config
+## Benchmark
 
-Useful commands:
+On a real 640-test Python backend (125 repeated setup errors, 3 contract failures, 510 passing tests):
 
-```bash
-sift config setup
-sift config use openrouter
-sift config init
-sift config show
-sift config validate
-sift doctor
-```
+| Metric | Raw agent | sift-first | Reduction |
+|--------|-----------|------------|-----------|
+| Tokens | 305K | 600 | 99.8% |
+| Tool calls | 16 | 7 | 56% |
+| Diagnosis | Same | Same | — |
 
-`sift config show` masks secrets by default. Use `--show-secrets` only when you explicitly need raw values.
+The headline numbers (62% token reduction, 71% fewer tool calls, 65% faster) come from the end-to-end wall-clock comparison. The table above shows the token-level reduction on the largest real fixture.
 
-Config precedence:
-1. CLI flags
-2. environment variables
-3. repo-local `sift.config.yaml` or `sift.config.yml`
-4. machine-wide `~/.config/sift/config.yaml` or `~/.config/sift/config.yml`
-5. built-in defaults
+Methodology and caveats live in [BENCHMARK_NOTES.md](BENCHMARK_NOTES.md).
 
-## Maintainer benchmark
+## Configuration
 
-To compare raw pytest output against the `test-status` reduction ladder on fixed fixtures, run:
+Inspect and validate config with:
 
 ```bash
-npm run bench:test-status-ab
-npm run bench:test-status-live
+sift config show
+sift config show --show-secrets
+sift config validate
 ```
 
-This uses the real `o200k_base` tokenizer and reports both:
-- command-output budget as the primary benchmark
-- deterministic recipe-budget comparisons as supporting evidence only
-- live-session scorecards for captured mixed full-suite agent transcripts
+To switch between saved providers without editing files:
 
-The benchmark is meant to show context-window and command-output reduction first. In normal debugging flows, `test-status` should usually stop at `standard`; `focused` and `verbose` are escalation tools, and raw pytest is the last resort when exact traceback evidence is still needed.
-
-If you pass `--config <path>`, that path is strict. Missing explicit config paths are errors.
+```bash
+sift config use openai
+sift config use openrouter
+```
 
-Minimal config example:
+Minimal YAML config:
 
 ```yaml
 provider:
@@ -449,63 +258,10 @@ runtime:
   rawFallback: true
 ```
 
-## OpenAI vs OpenRouter vs OpenAI-compatible
-
-Use `provider: openai` for `api.openai.com`.
-
-Use `provider: openrouter` for the native OpenRouter path. It defaults to:
-- `baseUrl: https://openrouter.ai/api/v1`
-- `model: openrouter/free`
-
-Use `provider: openai-compatible` for third-party compatible gateways or self-hosted endpoints.
-
-For OpenAI:
-```bash
-export OPENAI_API_KEY=your_openai_api_key
-```
-
-For OpenRouter:
-```bash
-export OPENROUTER_API_KEY=your_openrouter_api_key
-```
-
-For third-party compatible endpoints, use either the endpoint-native env var or:
-
-```bash
-export SIFT_PROVIDER_API_KEY=your_provider_api_key
-```
-
-Known compatible env fallbacks include:
-- `OPENROUTER_API_KEY`
-- `TOGETHER_API_KEY`
-- `GROQ_API_KEY`
-
-## Safety and limits
-
-- redaction is optional and regex-based
-- retriable provider failures such as `429`, timeouts, and `5xx` are retried once
-- `sift exec` detects simple prompt-like output such as `[y/N]` or `password:` and skips reduction
-- pipe mode does not preserve upstream shell pipeline failures; use `set -o pipefail` if you need that behavior
-
-## Releasing
-
-This repo uses a manual GitHub Actions release workflow with npm trusted publishing.
-
-Release flow:
-1. bump `package.json`
-2. merge to `main`
-3. run the `release` workflow manually
-
-The workflow runs typecheck, tests, coverage, build, packaging smoke checks, npm publish, tag creation, and GitHub Release creation.
-
-## Brand assets
-
-Curated public logo assets live in `assets/brand/`.
+## Docs
 
-Included SVG sets:
-- badge/app: teal, black, monochrome
-- icon-only: teal, black, monochrome
-- 24px icon: teal, black, monochrome
+- CLI reference: [docs/cli-reference.md](docs/cli-reference.md)
+- Benchmark methodology: [BENCHMARK_NOTES.md](BENCHMARK_NOTES.md)
 
 ## License