agent-hotwash 0.1.0__tar.gz

agent_hotwash-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    env:
+      NO_COLOR: "1"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Run checks
+        run: make check

agent_hotwash-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

agent_hotwash-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

agent_hotwash-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+Semver. Each release gets a short, user-facing note: what changed for someone *using* the platform (operators, API consumers, deployers), not internal refactors. Keep entries minimal — one line where possible, grouped under `Added` / `Changed` / `Fixed` / `Removed` only when needed.
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+## [0.1.0] — 2026-07-05
+
+### Added
+- Initial Release

agent_hotwash-0.1.0/CLAUDE.md

@@ -0,0 +1,37 @@
+# CLAUDE.md
+
+`agent-hotwash` analyzes coding-agent traces (code-bench runs, native Claude
+project dirs, native Codex rollouts) to surface improvement opportunities and
+bad patterns. Python 3.12, managed with `uv`.
+
+See `README.md` for usage/CLI and `docs/DESIGN.md` for architecture — don't
+duplicate them here.
+
+## Git policy
+
+**Never make any git changes (commit, push, tag, branch, rebase, etc.) unless
+the user explicitly requests it.** Leave the working tree for the user to
+review; when work is done, report what changed and stop.
+
+## Layout
+
+- `src/agent_hotwash/cli.py` — CLI entrypoint (`agent-hotwash`).
+- `src/agent_hotwash/sources/` — trace loaders + format autodetect (`detect.py`).
+- `src/agent_hotwash/primitives/` — shared trace primitives (windows, file state, errors, commands).
+- `src/agent_hotwash/analytics.py`, `aggregate.py`, `events.py` — analytics pipeline.
+- `src/agent_hotwash/detectors/` — pattern detectors + registry/taxonomy.
+- `src/agent_hotwash/report/` — output renderers (table/json/csv/html).
+- `src/agent_hotwash/config.py`, `config/defaults.toml` — config + defaults.
+- `tests/` — pytest suite. `docs/` — design notes and research.
+
+## Checks — use the Makefile
+
+Always run checks via the Makefile targets. They are **quiet on success** (one
+`<Name>: OK` line, full tool output only on failure) to keep transcripts short.
+
+- `make check` — full gate: format-check, lint, typecheck, tests (parallel). Use before finishing work.
+- `make lint` / `make format-check` / `make typecheck` / `make test` — individual legs.
+- `make format` — apply ruff formatting (mutates files).
+- `make install` — sync the venv from `uv.lock`. `make help` — list all targets.
+
+Prefer these over calling `uv run ruff`/`pytest`/`ty` directly.

agent_hotwash-0.1.0/FINDINGS.md

@@ -0,0 +1,113 @@
+# Code-Bench Trace Findings
+
+Analysis of `window-shop-monorepo-clean/tools/code-bench/runs` (293 runs, ~5.5 GB, 24 experiments)
+using agent-hotwash + targeted subagent investigation. Every quantitative claim below survived a
+second adversarial verification pass against the raw `run.json` / `verification.json` files;
+claims that failed verification were corrected or dropped (noted inline).
+
+Date: 2026-07-05
+
+## Headline: why codex (gpt-5.5) scored below opus-4-8
+
+Verified resolved counts on the main 15-task × 3-repeat baselines:
+
+| Experiment | Harness / model | Resolved |
+|---|---|---|
+| baseline-pi-opus48-xhigh | pi / claude-opus-4-8 | 35/45 |
+| baseline-opus48-xhigh | claude / claude-opus-4-8 | 33/45 |
+| baseline-codex-gpt55-xhigh | codex / gpt-5.5 | 29/45 |
+
+Per-instance matrix (resolved out of 3 repeats; only divergent rows shown — the other 8 tasks are 3/3 everywhere):
+
+| Instance | Codex | Opus (claude) | Opus (pi) |
+|---|---|---|---|
+| agents-3724 | 0 | 3 | 2 |
+| wire-worker-3200 | 0 | 3 | 3 |
+| pilot-web-3460 | 0 | 0 | 3 |
+| checkout-2264 | **3** | 0 | 0 |
+| checkout-3217 | 2 | 3 | 3 |
+| agents-2885 | 0 | 0 | 0 |
+| agents-3452 | 0 | 0 | 0 |
+
+Root causes, ranked by evidence strength:
+
+1. **Over-refactoring breaks test contracts.** On `agents-3724`, codex refactored
+   `getOutfit(id, userId)` into object-style params (283-line patch); the fix logic was right but
+   two test mocks expecting the positional signature failed
+   (`baseline-codex-gpt55-xhigh/agents-3724/20260705T112502Z-codex-r3-878`). Opus made the same fix
+   keeping positional params (218 lines) and passed
+   (`baseline-opus48-xhigh/agents-3724/20260704T193740Z-claude-r3-504`). Same pattern on
+   `wire-worker-3200`: codex introduced a `SessionIdentity`/`PersistedSessionState` interface
+   hierarchy (264 lines) breaking 5 state-hydration tests; opus added properties directly
+   (148 lines) and passed. Codex ships ~30–80% more churn for the same fix.
+2. **No re-iteration after failure.** Failing codex runs average 256s vs ~252s for passing ones —
+   codex declares done and exits without looping back when tests fail. Opus averages ~615s
+   (2.4× longer) and spends most on its failures. (Earlier duration figures of 344s/972s were
+   overstated ~30%; corrected here.)
+3. **Speed cuts both ways.** `checkout-2264` is a codex-only win (3/3 vs opus 0/3) — a simple,
+   localized fix where codex's fast path wins and opus overworks (see "most expensive run" below).
+4. Zero timeouts in any of the three baselines — the gap is not time pressure.
+
+## The most surprising finding: same model, opposite outcome by harness
+
+**pilot-web-3460** (session event buffering task): claude-opus-4-8 goes **0/3 under the Claude Code
+harness but 3/3 under the pi harness**. Root cause is a single code-pattern choice, not the model's
+task understanding:
+
+- Failing claude-harness patches wrapped the store subscription in an `IS_CLIENT_SIDE` guard,
+  which interacts badly with vitest's `vi.doMock()` / module-reset lifecycle — the flush listener
+  never registers on the mocked store, failing 4/7 tests (FIFO order, buffer cap, reconnect).
+- Repeat r2 then **overcorrected** by inventing an `sdkStatus === "connected"` precondition that
+  appears nowhere in the spec → 0/7.
+- Passing pi-harness patches register the subscription unconditionally at module scope → 7/7.
+
+One `if` statement cost three resolved runs. Codex also failed this task 0/3 (imperative
+buffer-and-flush architecture mismatching the test's expectations).
+
+## Other verified anomalies
+
+- **Most expensive run in the archive**: opus-4-8 spent **$12.05, 2028s, 15.9M tokens, 122 tool
+  calls** on `checkout-2264` — and failed on 1 of 94 tests
+  (`baseline-opus48-xhigh/checkout-2264/20260704T200316Z-claude-r3-026`).
+- **Largest token run**: glm-5.2 burned **18.5M tokens, 187 tool calls, $5.80** — and still
+  resolved (`baseline-pi-glm52-xhigh-throughput/checkout-2264/20260705T151954Z-pi-r1-888`).
+- **Silent regressions**: exactly 4 runs broke previously-passing tests (`pass_to_pass_regressed`),
+  e.g. an opus run on `checkout-3846` changed `recordVtoCompletion` from 1 arg to 2 in code it
+  wasn't asked to modify.
+- **`timed_out` semantics look inconsistent**: raw-field count shows 100/293 runs flagged
+  `timed_out=true`, including 87/88 glm-5.2-xhigh runs — yet glm baselines still resolved ~27/44,
+  and a per-baseline check of the three headline experiments found zero timeouts. Worth checking
+  whether `timed_out` means hard-kill vs soft budget in the harness; the two analyses could not be
+  fully reconciled.
+- **Unsolvable tasks**: `agents-2885` and `agents-3452` fail 0/3 across all three harnesses —
+  candidates for task-spec review.
+- **Totals**: $530.79 spend across 293 runs, 210/293 (71.7%) resolved overall. (An earlier
+  $89.47 / 190-285 figure was wrong and is superseded.)
+- Cost-per-resolved comparisons across models (e.g. haiku $0.026 vs opus $3.52) are
+  **apples-to-oranges** — cheap-model runs are smoke/toy tasks, not the 15-task baseline. Do not
+  quote them as model efficiency.
+
+## Library validation (agent-hotwash vs these traces)
+
+The tool parsed all 136 baseline traces (claude, codex, pi) with exit 0, zero crashes, and
+token/cost figures matching source `metrics.json` exactly on spot checks. Issues found and
+**fixed on this branch** (independently re-validated, `make check` green):
+
+1. ~~Codex adapter metrics-blind~~ (file-op metrics all zero, every tool "other") — root cause was
+   a greedy `rglob("rollout-*.jsonl")` in `sources/detect.py` that descended into each code-bench
+   run's internal `traces/codex/sessions/…` rollout copy, so codex experiment dirs were parsed by
+   the *native* adapter instead of the codebench path. One fix cleared four symptoms.
+2. ~~45 run dirs → 46 traces~~ — the extra trace was that internal rollout copy, not a real second
+   session. Now exactly 45.
+3. ~~Cost labeled `estimated`~~ — now `provenance`, using the recorded `metrics.json` cost.
+4. ~~Codex parsing ~25× slower~~ — now 0.43s for 45 runs (was ~78s), faster than the claude path.
+5. Native codex tool names (`exec_command`, `apply_patch`, `read_file`, `update_plan`) now map to
+   execute/write/read/planning, with file paths recovered from `apply_patch` body headers.
+6. claude-native: `isMeta` user records (hook output, injected agent messages, local-command
+   caveats) were counted as genuine user turns — now dropped (14 sessions in the sampled project
+   dir had phantom turns).
+7. The reported `ty` typecheck failure in `tests/test_sources_claude_native.py` was not
+   reproducible (guarded comprehension narrows correctly); gate is green.
+
+Both native traces validated post-fix: a codex rollout (860 events, execute 205 / write 36,
+1.24M input tokens) and a Claude Code session (171 events, 64 tool calls, zero warnings).

agent_hotwash-0.1.0/LICENSE

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

agent_hotwash-0.1.0/Makefile

@@ -0,0 +1,116 @@
+# agent-hotwash -- uv-based dev tasks. Run `make` or `make help` for the list.
+# Convention: a `## description` after a target is picked up by the help target.
+
+# Shared lint/format/typecheck target set.
+SRC := src tests
+
+# Tool invocations live here once so the verbose targets and the quiet `check`
+# gate run byte-identical commands.
+PYTEST        := uv run pytest
+TEST_CMD      := $(PYTEST)
+LINT_CMD      := uv run ruff check $(SRC)
+FMT_CHECK_CMD := uv run ruff format --check $(SRC)
+TYPECHECK_CMD := uv run ty check --force-exclude $(SRC)
+
+# ANSI colors for the check summary (export NO_COLOR=1 to disable).
+ifndef NO_COLOR
+GREEN := \033[32m
+RED   := \033[31m
+BOLD  := \033[1m
+RESET := \033[0m
+endif
+
+# run_quiet: run a command with NO output on success (success = silence, the
+# Unix way) and the full combined stdout+stderr on failure. Used by the
+# standalone static-check targets (`make lint`, `make typecheck`, ...).
+#   usage:  @$(call run_quiet,$(LINT_CMD))
+define run_quiet
+out=$$($(1) 2>&1); st=$$?; [ $$st -eq 0 ] || { printf '%s\n' "$$out"; exit $$st; }
+endef
+
+# run_check: like run_quiet but prints a one-line "<label>: OK" on success (and
+# "<label>: FAIL" + the full output on failure). Used by the `make check` gate
+# so each leg reports that it ran. Output is one atomic block, so it stays
+# readable even when several run_check recipes run concurrently under `make -j`.
+#   usage:  @$(call run_check,Lint,$(LINT_CMD))
+define run_check
+out=$$($(2) 2>&1); st=$$?; if [ $$st -eq 0 ]; then printf '  $(GREEN)%-14s OK$(RESET)\n' '$(1):'; else printf '  $(RED)%-14s FAIL$(RESET)\n' '$(1):'; printf '%s\n' "$$out"; exit $$st; fi
+endef
+
+.PHONY: help install sync format fmt lint format-check typecheck test check \
+	_ck-fmt _ck-lint _ck-type _ck-test release publish clean
+
+help: ## Show this help (default target).
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install: ## Sync the virtualenv from uv.lock (incl. dev group).
+	uv sync
+
+sync: install ## Alias for install.
+
+format: ## Format src + tests with ruff (mutates files).
+	uv run ruff format $(SRC)
+
+fmt: format ## Alias for format.
+
+# The standalone static-check targets are SILENT on success and dump the full
+# combined stdout+stderr only when the tool exits non-zero. (`make check`
+# reports each as "<name>: OK" via its own wrappers below.)
+lint: ## Lint src + tests with ruff (silent unless it fails).
+	@$(call run_quiet,$(LINT_CMD))
+
+format-check: ## Check formatting with ruff (silent unless it fails).
+	@$(call run_quiet,$(FMT_CHECK_CMD))
+
+typecheck: ## Type-check src + tests with ty (silent unless it fails).
+	@$(call run_quiet,$(TYPECHECK_CMD))
+
+test: ## Run the test suite (verbose).
+	$(TEST_CMD)
+
+# check runs every leg via `make -j` so the static checks and tests run
+# concurrently. Output is captured per target, so the summary lines never
+# interleave. Quiet on success: each leg prints one "<name>: OK" line.
+check: ## Full hygiene gate: format/lint/typecheck + tests (parallel). Quiet on success.
+	@printf '$(BOLD)Running make check...$(RESET)\n'
+	@$(MAKE) -j --no-print-directory _ck-fmt _ck-lint _ck-type _ck-test
+	@printf '$(GREEN)$(BOLD)All checks passed.$(RESET)\n'
+
+_ck-fmt:
+	@$(call run_check,Format,$(FMT_CHECK_CMD))
+
+_ck-lint:
+	@$(call run_check,Lint,$(LINT_CMD))
+
+_ck-type:
+	@$(call run_check,Typecheck,$(TYPECHECK_CMD))
+
+_ck-test:
+	@$(call run_check,Tests,$(TEST_CMD))
+
+# release: bump the version, tag it, and build the wheel/sdist. Pass the bump
+# level via BUMP (major|minor|patch; default patch), e.g. `make release BUMP=minor`.
+# Runs the full check gate first so a broken tree never gets tagged.
+BUMP ?= patch
+release: check ## Bump version (BUMP=major|minor|patch), git-tag, and build dists.
+	@[ -z "$$(git status --porcelain)" ] || { echo "Release: FAIL (working tree not clean)"; exit 1; }
+	uv version --bump $(BUMP)
+	@version=$$(uv version --short); \
+		git commit -am "release: v$$version" && \
+		git tag "v$$version" && \
+		printf '$(GREEN)Tagged v%s$(RESET)\n' "$$version"
+	uv build
+
+# publish: rebuild dists from scratch and upload with uv. Credentials via the
+# usual uv env vars (UV_PUBLISH_TOKEN or UV_PUBLISH_USERNAME/PASSWORD).
+publish: check ## Clean dist/, rebuild, and publish to PyPI with uv.
+	rm -rf dist
+	uv build
+	uv publish
+	rm -rf dist
+
+clean: ## Remove caches and build artifacts (keeps .venv and uv.lock).
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+	rm -rf .ruff_cache .pytest_cache dist build
+	find . -type f -name '*.pyc' -delete

agent_hotwash-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: agent-hotwash
+Version: 0.1.0
+Summary: agent-hotwash — analyze coding-agent traces to surface improvement opportunities and bad patterns
+License-File: LICENSE
+Requires-Python: <3.14,>=3.12
+Requires-Dist: click>=8.4.2
+Requires-Dist: pydantic>=2
+Requires-Dist: rich
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# agent-hotwash
+
+Analyzes coding-agent traces (Claude, Codex, pi, code-bench) to surface bad patterns and improvement opportunities via analytics and detectors.
+Point it at what an agent did to learn how it could have done better, with reports in table, JSON, CSV, or HTML for humans or CI.
+
+## Quickstart
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.12.
+
+```bash
+uv sync          # create the venv and install deps (incl. dev tools)
+make check       # run the full hygiene gate (format, lint, typecheck, tests)
+uv run agent-hotwash --help
+```
+
+## Usage
+
+Point `analyze` at any trace file or directory. It auto-detects the format
+(code-bench run/experiment dirs, native Claude project dirs, native Codex
+rollouts, native pi session dirs), runs analytics + detectors, and renders a
+report.
+
+```bash
+uv run agent-hotwash analyze <path>...                 # analyze one or more traces
+uv run agent-hotwash analyze <path> --format table     # human table (default on a TTY)
+uv run agent-hotwash analyze <path> --format json      # machine JSON (default when piped)
+uv run agent-hotwash analyze <path> --format html --out report.html
+uv run agent-hotwash analyze <path> --format csv --out rows.csv
+```
+
+Common flags: `--config FILE` (user TOML merged over defaults), `--no-detectors`
+(analytics only), `--fail-on high` (CI gate: non-zero exit if a finding at/above
+the given severity is present).
+
+Formats: `table` (rich, degrades to plain text off a TTY), `json`, `csv` (one
+row per run + a column per finding id), `html` (single self-contained file, no
+external assets). `--out` takes a file or a directory (writes `report.<ext>`);
+omit it to stream to stdout.
+
+Other commands:
+
+```bash
+uv run agent-hotwash detectors --format json   # list registered detectors
+uv run agent-hotwash config-show               # dump the effective merged config
+uv run agent-hotwash version
+```
+
+**Output contract (AI-friendly):** structured data goes to **stdout**, all
+human/progress messages to **stderr**. Exit codes: `0` success, `1` error,
+`2` no analyzable traces found (or `--fail-on` tripped).
+
+## Make targets
+
+Run `make help` for the full list. The static-check targets are **quiet on
+success** — they print one `<Name>: OK` line and only dump full tool output on
+failure, to keep transcripts short for AI agents.
+
+| Target       | What it does                                                   |
+| ------------ | ------------------------------------------------------------- |
+| `install` / `sync` | Sync the venv from `uv.lock` (incl. dev group).         |
+| `format` / `fmt`   | Format `src` + `tests` with ruff.                       |
+| `lint`       | Lint with ruff (silent unless it fails).                       |
+| `format-check` | Check formatting with ruff (silent unless it fails).        |
+| `typecheck`  | Type-check with [ty](https://github.com/astral-sh/ty).        |
+| `test`       | Run the pytest suite (verbose).                               |
+| `check`      | Full gate: format-check + lint + typecheck + tests, parallel. |
+| `release`    | `make release BUMP=minor` — gate, bump, tag, build dists.      |
+| `clean`      | Remove caches and build artifacts.                            |
+
+## Layout
+
+```
+src/agent_hotwash/   package (CLI entry point in cli.py)
+tests/               pytest suite
+```
+
+## Tooling
+
+- **[uv](https://docs.astral.sh/uv/)** — env and dependency management.
+- **[ruff](https://docs.astral.sh/ruff/)** — lint + format.
+- **[ty](https://github.com/astral-sh/ty)** — type checking.
+- **pytest** — tests.