oc-pilot 0.5.1 → 0.88.1

package/README.md

@@ -1,12 +1,16 @@
 # oc-pilot
 
+[![npm](https://img.shields.io/npm/v/oc-pilot?style=flat-square&color=black)](https://www.npmjs.com/package/oc-pilot)
+[![Node.js](https://img.shields.io/node/v/oc-pilot?style=flat-square&color=black)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-MIT-black?style=flat-square)](LICENSE)
+
 Local AI code review, failing-test analysis, documentation generation, and secret scanning for agent CLIs.
 
 `oc-pilot` is a small CLI and MCP server for developers who write code with AI agents. It reviews an uncommitted diff, follows the project beyond the changed lines, catches leaked credentials before they reach a model, explains a failing test, and returns findings as human-readable Markdown or machine-readable JSON.
 
 It works with OpenCode out of the box, with any OpenAI-compatible API (OpenAI, DeepSeek, Groq, OpenRouter, Ollama), and with any MCP-capable agent: Claude Code, OpenAI Codex CLI, Cursor CLI, Gemini CLI, and others.
 
-[Русская документация](README.ru.md)
+[English](README.md) | [Русская документация](README.ru.md) | [MCP integrations](docs/integrations.md) | [Security](SECURITY.md) | [Contributing](CONTRIBUTING.md) | [Changelog](CHANGELOG.md)
 
 ## Why
 
@@ -28,19 +32,19 @@ Agents are good at producing code and bad at reviewing their own work. A normal
 
 ## Install
 
-From GitHub, pinned to a release tag (works before the first npm release):
+From npm. The latest published release is **0.5.1**:
 
 ```bash
-npm install -g https://github.com/MyNameIsNikki/oc-pilot/archive/refs/tags/v0.5.1.tar.gz
+npm install -g oc-pilot
 ```
 
-From npm, once published:
+From the repository, pinned to a release tag. Tag **v0.5.2** is a version-only release with identical runtime behavior:
 
 ```bash
-npm install -g oc-pilot
+npm install -g https://github.com/MyNameIsNikki/oc-pilot/archive/refs/tags/v0.5.2.tar.gz
 ```
 
-For development:
+From source:
 
 ```bash
 git clone https://github.com/MyNameIsNikki/oc-pilot.git
@@ -58,7 +62,7 @@ oc-pilot-mcp --version
 oc-pilot mcp --version
 ```
 
-For development, run `node dist/cli.js` and `node dist/mcp.js` directly.
+During development, run `node dist/cli.js` and `node dist/mcp.js` directly.
 
 ## Quick start (OpenCode)
 
@@ -118,6 +122,9 @@ oc-pilot review --engine openai --model deepseek-chat \
 # Local model through Ollama (no key needed on loopback)
 oc-pilot review --engine openai --model qwen2.5-coder \
   --base-url http://127.0.0.1:11434/v1
+
+# The same, through a preset
+oc-pilot review --engine-preset ollama --model qwen2.5-coder
 ```
 
 | Engine | Best for | Repository tools | Requires |
@@ -127,6 +134,70 @@ oc-pilot review --engine openai --model qwen2.5-coder \
 
 The key is read from `OC_PILOT_API_KEY`, or `OPENAI_API_KEY` when the default variable name is used. Set `apiKeyEnv` to use another variable. Logs and errors never print the key. With the `openai` engine, `repoContext` is forced off and `FULL_FILE_CONTEXT` is added automatically.
 
+### Engine presets
+
+For the common OpenAI-compatible providers, `--engine-preset` fills in the base URL, the key variable and (where it is a sensible default) the model:
+
+| Preset | Base URL | Key variable | Default model |
+| --- | --- | --- | --- |
+| `ollama` | `http://localhost:11434/v1` | `OLLAMA_API_KEY` (not needed on loopback) | `llama3.2` |
+| `lmstudio` | `http://localhost:1234/v1` | `LMSTUDIO_API_KEY` (not needed on loopback) | — |
+| `openrouter` | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` | — |
+
+A preset switches the engine to `openai` unless you say otherwise, and explicit flags always win: `oc-pilot review --engine-preset ollama --model qwen2.5-coder` keeps the preset endpoint and overrides only the model.
+
+### Anthropic engine
+
+`--engine anthropic` talks to the Claude Messages API directly, without an SDK:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-... oc-pilot review --engine anthropic --model claude-sonnet-4-5
+```
+
+The system prompt is sent as a `system` block with `cache_control: {"type": "ephemeral"}`, so repeated reviews reuse the cached prefix. Requests use `anthropic-version: 2023-06-01` and `x-api-key`. Token usage is mapped onto the same cost table as the OpenAI engine, so `--max-cost` and `oc-pilot stats` work unchanged.
+
+Slicing, the two-phase router and the response cache are `openai`-only; the Anthropic engine always sends one request per run.
+
+### Smart slicing (`openai`)
+
+When a diff is too large for a single prompt (300 000 characters), the `openai` engine does not truncate files away. Instead it groups the per-file diff blocks into slices that each fit the budget, runs one API call per slice with the same additional context, and merges the responses back into a single schema-compliant analysis (`meta.slices` shows how many calls were made). Up to three slices run in parallel and their answers are merged in the original file order. A single file whose diff exceeds the budget is sent as its own slice and only then truncated. Slicing applies to `review`, `test-fix`, `custom` and `commit --engine openai`; `fix` keeps a single prompt because it must return one patch.
+
+### Retries
+
+Transient failures are retried instead of failing the run: HTTP 408, 425, 429, 500, 502, 503 and 504 are attempted up to three times with an exponential delay (500 ms, 1 s, 2 s, capped at 8 s). A `Retry-After` header wins over the computed delay. Authentication errors, other 4xx responses, network errors and timeouts still fail immediately, because retrying them only burns time. Slice calls share the same policy.
+
+### Two-phase routing (`openai`)
+
+`review` can route through a cheap triage model before the main review call. The triage model sees the same input with a compact system prompt and answers with a single line: `TRIAGE: REVIEW` or `TRIAGE: LGTM`. Trivially safe diffs (docs, formatting, version bumps, renames) return `LGTM` and skip the main call entirely; everything else runs the full review. Any triage failure or unparsable answer falls back to the full review, so routing can only save money, never skip a real problem. Secret gating (`--fail-on-secrets`) is evaluated independently of the router.
+
+```bash
+oc-pilot review --router --router-model gpt-4.1-mini --engine openai --model gpt-4.1
+```
+
+Enable it per run with `--router`, or permanently with `routerEnabled: true` and `routerModel` in `.oc-pilot.json` (or `OC_PILOT_ROUTER` / `OC_PILOT_ROUTER_MODEL`). `--no-router` disables it for one run. The JSON report includes `meta.router` with the model, decision and duration.
+
+### Provider-cache-friendly prompts
+
+oc-pilot orders every prompt so the stable parts come first and the volatile `GIT_DIFF` comes last: instruction, project type, recipe, repository flags, additional context and the secret report are identical across slices, fix rounds and repeated reviews of the same change. Providers with prefix caching (OpenAI, DeepSeek, Anthropic, OpenRouter) reuse that stable prefix automatically, so the second and later calls on the same context are cheaper and faster. No configuration is needed.
+
+### Response cache (`openai`)
+
+The `openai` engine caches full model responses on disk. The cache key is the sha256 of the model, base URL, system prompt and input, so re-running the same command on the same diff (typical when wiring hooks, CI or scripts) costs zero tokens and returns instantly. Entries live in `.git/oc-pilot/cache/` — inside the repository metadata, never in the worktree or in commits.
+
+The TTL defaults to 24 hours (`cacheTtlSeconds`, or `OC_PILOT_CACHE_TTL`; `0` disables caching). `--no-cache` bypasses the cache for one run, and `oc-pilot cache --stats | --prune | --clear` inspects and maintains it. `doctor --fix` prunes expired entries. The JSON report shows `meta.cache: "hit" | "miss"`. The cache only applies to the `openai` engine (triage, main and slice calls); OpenCode runs are never cached, and a cache error can never fail a review.
+
+### Second opinion (`openai`)
+
+`review --second-opinion` re-checks up to 10 critical findings with a second, skeptical model before failing the build. Each verdict is a single line: `VERDICT: CONFIRM` keeps the finding, `VERDICT: REJECT — <reason>` downgrades it to style and annotates the bullet with `[second opinion: rejected — reason]`. If the verifier errors or is unreachable, findings are kept as-is — verification never weakens a review on failure. Configure the verifier with `--second-opinion-model` / `--second-opinion-base-url` / `--second-opinion-api-key-env` or the config keys `secondOpinionEnabled`, `secondOpinionModel`, `secondOpinionBaseUrl`, `secondOpinionApiKeyEnv`; the result is reported in `meta.secondOpinion`.
+
+### Usage limits and statistics
+
+Every run and API call is recorded to `.git/oc-pilot/stats.jsonl` (findings, engine, exit code, cache hits). `oc-pilot stats` prints runs, API calls, cache hits and findings for today, the week and all time (`--clear` resets). A daily API-call budget can be enforced with `maxDailyApiCalls` or `OC_PILOT_MAX_DAILY_API_CALLS` (`0` disables it); once the limit of uncached calls is reached, the command exits 1 — cache hits never consume the budget. `oc-pilot day --since "1 day ago"` summarizes what the agent did: commits, churn per file, added/deleted lines and oc-pilot findings. A spend cap works the same way: `--max-cost 0.5` (or `maxCostUsd` / `OC_PILOT_MAX_COST`) adds up the estimated cost of today's uncached calls — tokens from the API response times the built-in price table — and refuses the next call once the cap is reached. Pricing is estimated, so treat it as a guard rail rather than an invoice; unknown models count as zero and cache hits are free.
+
+### Agent rules awareness
+
+If the project has an `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules` or `.github/copilot-instructions.md`, oc-pilot includes it in every prompt (first match, up to 10 000 characters, secrets masked). This keeps the reviewer aware of the same conventions the coding agent follows. Disable with `agentRules: false` in the config or `OC_PILOT_AGENT_RULES=0`.
+
 ## Commands
 
 ### `review`
@@ -152,6 +223,55 @@ git diff | oc-pilot review --stdin
 | `--context <text\|@file>` | Extra context for the model |
 | `--no-secret-scan` | Disable secret scanning and redaction |
 | `--fail-on-secrets` | Exit 3 on critical secrets |
+| `--router` | Route through a cheap triage model first (`openai`) |
+| `--no-router` | Disable routing enabled in the config |
+| `--router-model <m>` | Triage model (default: `routerModel` from the config) |
+| `--baseline` | Hide findings already recorded in `.oc-pilot/baseline.json` |
+| `--update-baseline` | Record current findings as the baseline and exit |
+| `--pr` | Post inline review comments to the PR (Actions REST or `gh`) |
+| `--no-pr-inline` | Post a single summary comment instead of inline comments |
+| `--pr-status` | Post a blocking commit status (`failure` on critical findings) |
+| `--mr` | Post the review to a GitLab merge request (`CI_MERGE_REQUEST_IID`) |
+| `--no-mr-inline` | Post a single summary note instead of inline discussions |
+| `--mr-status` | Set the `oc-pilot` commit status in GitLab (`GITLAB_TOKEN`) |
+| `--second-opinion` | Verify critical findings with a second model (`openai`) |
+| `--second-opinion-model <m>` | Verifier model (default: `secondOpinionModel` or the main model) |
+| `--require-tests` | Exit 3 when logic changed without tests |
+| `--no-test-weakening` | Exit 3 when tests were weakened (skips, removed assertions) |
+| `--interactive` | Ask per finding whether to hide it in the baseline (TTY) |
+
+With `--baseline`, findings already recorded in `.oc-pilot/baseline.json` are hidden from the output and no longer affect the exit code, JSON, SARIF or PR comment — only new findings block. A finding fingerprint is `severity | file | normalized text`, without the line number, so known findings survive code shifts. `--update-baseline` rewrites the file from the current review and exits 0; `--interactive` hides findings one by one and appends them to the baseline. `--pr` posts the review to the current PR: inside GitHub Actions it uses the review API with `GITHUB_TOKEN` and attaches up to 25 findings as inline comments on their diff lines (grant `permissions: pull-requests: write`); findings that do not map to a changed line, and every run outside Actions, fall back to one summary comment (locally through `gh pr comment`, which must be installed and authenticated). `--no-pr-inline` forces that summary comment. `--pr-status` posts a commit status under the `oc-pilot` context - `failure` while critical findings remain, `success` otherwise - so a branch protection rule can require it (needs `statuses: write`). It works from text and SARIF runs alike.
+
+Inside GitLab CI, `--mr` posts the review to the merge request: up to 25 findings become inline discussions anchored to their diff lines, and the summary always lands as a note. `CI_MERGE_REQUEST_IID`, `CI_PROJECT_ID` and `CI_API_V4_URL` identify the merge request, and `GITLAB_TOKEN` needs the `api` scope (`CI_JOB_TOKEN` cannot write notes). The discussion position needs `base_sha`/`start_sha`/`head_sha`: they are read from `CI_MERGE_REQUEST_DIFF_BASE_SHA`, `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` and `CI_COMMIT_SHA`, and when those are absent the tool asks the merge request for its `diff_refs` instead. `--no-mr-inline` keeps the summary note only. Add `--mr-status` to set the `oc-pilot` commit status as well. Every part degrades to a warning when the pipeline context, the token or a single position is missing, so a review never fails because of a missing integration.
+
+A minimal job looks like this:
+
+```yaml
+oc-pilot:
+  image: node:22
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - npm i -g oc-pilot
+    - oc-pilot review --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --fail-on critical --mr --mr-status
+  variables:
+    OC_PILOT_API_KEY: $OC_PILOT_API_KEY
+    GITLAB_TOKEN: $GITLAB_TOKEN
+```
+
+Before the model runs, `review` also inspects the diff locally: newly added dependencies are checked for typosquats, unpinned versions and VCS/URL specs across npm, PyPI, Go, Cargo, RubyGems, Packagist, Maven/Gradle and NuGet manifests (`DEPENDENCY_CHANGES` hint, `meta.dependencies`); a large logic change (20+ added code lines) with no test files produces a `TEST_COVERAGE_HINT` (`--require-tests` turns it into exit 3, `meta.testDelta`); weakened tests produce a `TEST_WEAKENING` hint (skipped or focused tests, removed assertions without replacements, commented-out assertions, raised timeouts; `--no-test-weakening` turns it into exit 3, `meta.testWeakening`); and added lines matching prompt-injection heuristics (instruction overrides, role hijacking, prompt exfiltration, base64 blobs, invisible Unicode) produce a `PROMPT_INJECTION_RISKS` warning (`meta.injection`).
+
+See [Second opinion](#second-opinion-openai) for the verification flow.
+
+### Suppressing findings in code
+
+An accepted trade-off should not come back as a finding on every review. Mark it at the source:
+
+```go
+func pay() {} // oc-pilot:ignore: nil is impossible for a legacy wallet
+```
+
+The marker suppresses a finding whose target is that line or the line right below it, so it also works as a comment on its own line above the code. `// oc-pilot:ignore-file: code generated by protoc` in the first ten lines silences the whole file. A reason is mandatory: a bare `oc-pilot:ignore` is ignored, the finding stays, and the run warns about it. Suppressed findings disappear from the text, JSON, SARIF and PR or MR comments and do not affect the exit code, while `meta.suppressed` lists each one with its file, line and reason. `oc-pilot:ignore-secret` belongs to the secret scanner and never hides a review finding.
 
 ### `test-fix`
 
@@ -166,6 +286,27 @@ npm test 2> failures.log; oc-pilot test-fix --log failures.log
 
 A passing test run is skipped unless `--force` is used.
 
+### `test-gen`
+
+Turns a diff into tests that actually run. The model writes tests for the behavior changed in the diff, the patch is applied, the test command runs, and only the green result stays: a failing attempt is rolled back and the failure log goes back to the model as feedback.
+
+```bash
+oc-pilot test-gen --staged --apply
+oc-pilot test-gen --staged --coverage --apply
+oc-pilot test-gen --from-slop --apply
+oc-pilot test-gen src/billing.ts --apply --rounds 1
+oc-pilot test-gen --base main --json
+oc-pilot test-gen --diff changes.diff
+```
+
+Without `--apply` the command only prints the patch. The patch may touch test files only (`*.test.ts`, `*.spec.ts`, `*_test.go`, `test_*.py`, or paths under `test/`); a production file in the patch rejects the whole round. Existing test files are protected unless `--force` is passed, so generated tests never overwrite hand-written ones. `--no-run` applies without executing the suite, `--keep-failing` keeps a red test file for debugging, and `--rounds <n>` (default 2) controls how many times a failure is sent back to the model.
+
+`--coverage` narrows the request to changed lines that no test executed yet. The command reads an lcov, Istanbul JSON, Cobertura XML or Go cover profile report (`--coverage-file <path>` overrides the auto-detected `coverage/lcov.info`, `coverage/coverage-final.json`, `cobertura.xml`, `coverage.out` and similar files), intersects it with the lines added by the diff, and sends only those gaps to the model. When every changed line is already covered, it exits 0 without calling the model.
+
+`--from-slop` ignores the diff and lets the slop scan choose the work: it looks for source files that have no test at all and ranks them by churn, duplicated blocks and unresolved TODOs. `--slop-files <n>` (default 3) caps how many files are sent. The command refuses to mix `--from-slop` with `--diff`, `--staged`, `--base`, `--coverage` or explicit paths, because those already define the input. When every source file has a test, it exits 0 without calling the model.
+
+The JSON payload is `{applied, patch, files, status, tests, rounds, analysis, meta, coverage, targets}` with `status` equal to `pass`, `fail` or `not-run` and `coverage` holding `{report, format, uncoveredLines, gaps, missing}` (or `null` without `--coverage`); `targets` lists the slop-selected files with their scores and reasons (or `null` without `--from-slop`). The exit code is 1 while the tests stay red.
+
 ### `fix`
 
 Asks the model for a unified diff, checks that it applies, and optionally applies it in the project. This is the only command that can modify your working tree, and only with `--apply`.
@@ -180,6 +321,10 @@ oc-pilot fix --apply --command "npm test"
 # Apply but keep the patch even when tests fail
 oc-pilot fix --apply --command "go test ./..." --keep-on-test-failure
 
+# Fix SAST findings in the changed files
+oc-pilot fix --from-sast --staged --apply
+oc-pilot fix --from-authz --staged --apply
+
 # Emit GitHub Actions annotations for the findings
 oc-pilot review --github
 ```
@@ -190,9 +335,16 @@ oc-pilot review --github
 | `--command <cmd>` | Test command after applying; defaults to `testCommand` or auto-detection |
 | `--no-tests` | Apply without running tests |
 | `--keep-on-test-failure` | Do not revert a patch when tests fail |
+| `--no-snapshot` | Skip the safety snapshot before applying |
+| `--from-sast` | Fix high-severity SAST findings in the changed files, then rescan |
+| `--from-authz` | Fix high-severity authorization findings in the changed routes, then rescan |
 
 `fix` never commits or pushes. The patch is reverted when tests fail unless `--keep-on-test-failure` is used. Unrelated working-tree changes are not reverted.
 
+Before applying, `fix` saves a snapshot under `.git/oc-pilot/snapshots/` (tracked changes as a binary patch plus copies of untracked files). Snapshots stay local: they are never committed or pushed. Restore the snapshot with `oc-pilot restore`; skip it with `--no-snapshot`.
+
+With `--from-sast`, `fix` scans the changed files with the built-in SAST rules, asks the model for a patch that removes those findings, applies it, and rescans. The JSON payload gains `sast: {before, after, remaining}`; the exit code is 1 when high-severity findings remain. With `--from-authz`, the same loop targets route authorization findings (an unauthenticated route, an IDOR lookup, an admin path without a role) and the payload gains `authz: {before, after, remaining}`; `--from-sast` and `--from-authz` cannot be combined.
+
 ### `docgen`
 
 Generates GoDoc, RustDoc, JSDoc, Python docstrings, and similar comments without changing the code.
@@ -218,10 +370,343 @@ Offline secret scan. No model call.
 ```bash
 oc-pilot scan
 oc-pilot scan --staged --json
+oc-pilot scan --all
 git diff main...HEAD | oc-pilot scan --stdin
+
+# SARIF 2.1.0 for GitHub Code Scanning
+oc-pilot scan --staged --format sarif -o oc-pilot.sarif
+```
+
+Exit 1 means critical secrets were found. `--strict` also fails on warnings. `--format sarif` writes a SARIF 2.1.0 report (rules `oc-pilot/secret`, `oc-pilot/critical`, `oc-pilot/warning`) that GitHub Code Scanning can upload; secret previews stay redacted.
+
+`--all` scans the whole tree instead of a diff. It respects `.gitignore` and `.oc-pilot/ignore`, skips binaries, `node_modules`, `dist` and files over 512 KB, and reports how many files were checked (`meta.filesScanned`).
+
+### `preflight`
+
+One offline verdict before a commit. Six checks run without a model and without network: secrets in the diff, a deterministic SAST pass over the changed source files (command and SQL injection, path traversal, SSRF, code injection, XSS and more), route authorization over the changed source files (an unauthenticated route, an IDOR lookup, an admin path without a role), dependency health scoped to the files the diff touches, weakened tests (`it.skip`, removed assertions, raised timeouts), and the Slop Index delta against a base ref.
+
+```bash
+oc-pilot preflight
+oc-pilot preflight --staged
+oc-pilot preflight --base main --max-delta 0
+oc-pilot preflight --no-slop --fail-on-issue medium
+oc-pilot preflight --staged --no-sast
+```
+
+Dependency issues are scoped: preflight reports only problems in files the diff changes or packages named in added lines, so a legacy repository does not fail on the first run. Findings recorded in `.oc-pilot/baseline.json` are hidden by default, so the gate reports only new problems; `receipt` uses the same baseline. `--fail-on-issue` (default `high`) sets the gate for SAST, route authorization and dependency severity, and `--max-delta` (default 10 points) sets the Slop Index gate; each check can be disabled with `--no-secret-scan`, `--no-sast`, `--no-authz`, `--no-deps`, `--no-tests` or `--no-slop`. The exit code is 1 if any check fails and 0 otherwise, so one CI step replaces six.
+
+The JSON report is `{status, checks, diff}`, where each check carries `{id, label, status, summary, details}` with `status` equal to `pass`, `fail` or `skip`.
+
+### `receipt`
+
+Turns "it works on my machine" into a checked claim. A receipt runs the tests and the preflight (including SAST and authz), then records the result together with the commit SHA, branch, dirty state, diff stats, and the exact commands. It is written to `.git/oc-pilot/receipt.json`, so it never ends up in the working tree. Pass `--no-sast` or `--no-authz` to skip a check for a change where it does not apply.
+
+```bash
+oc-pilot receipt --staged
+oc-pilot receipt --staged --no-sast
+oc-pilot receipt --json
+oc-pilot receipt --verify
+oc-pilot receipt --verify --receipt path/to/receipt.json
+oc-pilot receipt --keygen receipt.key
+oc-pilot receipt --sign --key receipt.key
+oc-pilot receipt --verify --public-key receipt.key.pub
+```
+
+The file is sealed with a SHA-256 hash of its body. `--verify` recomputes the hash and compares the commit with the current `HEAD`, so an edited file or a receipt from an older commit is reported as invalid: `{path, ok, hashOk, stale, commit, head, signature, reason?}`. The exit code is 1 when the tests fail, the preflight fails or the receipt does not verify.
+
+A hash proves integrity, not authorship. `--sign` signs the hash with an Ed25519 key: `--keygen <file>` writes a private key (mode 0600) and `<file>.pub`; `--key` or `OC_PILOT_RECEIPT_KEY` points at the private key; the receipt gains a `signature` field. Verification checks the signature when a public key is available: `--public-key <file>`, `OC_PILOT_RECEIPT_PUBLIC_KEY`, or the committed `.oc-pilot/receipt.pub`. The `signature` status is `valid`, `invalid`, `missing` or `unchecked`; an unsigned receipt fails verification when a key is supplied. `ready` verifies the signature too when `.oc-pilot/receipt.pub` exists. Keep the private key outside the repository.
+
+A receipt carries `{version, tool, toolVersion, createdAt, commit, branch, dirty, diff, files, tests, preflight, hash, signature?}`. `tests` is `{command, exitCode, timedOut, durationMs, passed, outputTail}` or `null` with `--no-run`; `preflight` is the same report `preflight` prints. Outside a repository the receipt can only be written to an explicit path with `--out`.
+
+### `ready`
+
+Scores how ready a repository is for an AI agent. One offline number from 0 to 100 across nine checks: tests (15), lockfile (10), git hooks (15), Slop Index (15), a fresh receipt (10), agent instructions (10), CI (5), config (5) and security (15). Each check is `pass`, `warn` or `fail` and earns 100%, 50% or 0% of its weight. The security check runs the deterministic SAST and route-authorization rules over the repository and respects `.oc-pilot/baseline.json`. No model call, no network, but it does require a git repository.
+
+```bash
+oc-pilot ready
+oc-pilot ready --json
+oc-pilot ready --badge
+oc-pilot ready --fail-under 85
+oc-pilot ready --fix
+oc-pilot ready --fix --dry-run
+oc-pilot ready --fix --receipt
+```
+
+The score maps to a grade: 85 and above is `agent-ready`, 65 and above `almost`, 40 and above `risky`, anything lower `not-ready`. `--badge` prints a shields.io markdown badge for the README, and `--fail-under <n>` exits with code 1 below the threshold, so the score can gate a pull request.
+
+`--fix` applies only safe, offline repairs: it installs the `pre-commit` hook when no hook exists, writes `.oc-pilot.json` with the detected test command, and creates `AGENTS.md` with the project commands. A foreign hook, an existing config or existing agent instructions are never overwritten; the report lists those as skipped together with checks that need a human, such as the receipt, the lockfile and the Slop Index. `--dry-run` prints the plan without touching the tree, and the score is recomputed after the fixes.
+
+`--receipt` turns `--fix` into a full loop: after the repairs it runs the test command, runs the preflight and saves a receipt for `HEAD`, so the receipt check can pass in the same run. It requires `--fix`; without a test command the receipt is listed as skipped. A failed test run or a failed preflight still produces a receipt — the report says which part failed.
+
+The JSON payload is `{score, grade, checks, commit}`; each check is `{id, label, status, points, max, detail}`, where `detail` names the file that earned or lost the points and the command that fixes it. With `--fix` the payload also carries `fix: {applied, dryRun, fixes, skipped, receipt}`, where `receipt` is `{path, testsPassed, preflight}` or omitted.
+
+### `mutate`
+
+Mutation testing answers a harder question than coverage: do the tests actually catch bugs? The command flips comparison and boolean operators in the changed source files, runs the test suite against each mutant and counts how many mutants the tests killed. A surviving mutant is a line the suite executes but does not really check.
+
+```bash
+oc-pilot mutate --staged
+oc-pilot mutate --base main --max-mutants 10
+oc-pilot mutate src/billing.ts --min-score 80
+oc-pilot mutate --diff changes.diff --json
+```
+
+Operators are `===`/`!==`, `==`/`!=`, `>=`/`<`, `<=`/`>`, `&&`/`||` and `true`/`false`; strings and comments are masked, so only real code is mutated. `--max-mutants <n>` caps the run (default 20, max 500) because every mutant executes the whole suite. `--min-score <n>` exits with code 1 when the mutation score is below the threshold, which makes it a CI gate. A timeout counts as a kill: the mutant changed observable behavior.
+
+The JSON payload is `{command, files, sites, mutants, killed, survived, timedOut, score, truncated, durationMs}`; each mutant is `{file, line, column, operator, original, replacement, status, durationMs}` with `status` equal to `killed`, `survived` or `timeout`.
+
+### `flaky`
+
+Runs the test command several times and compares per-test results. A test that passes in some runs and fails in others is flaky; one that fails every time is simply broken. The command never calls a model: it only runs the suite and parses the output.
+
+```bash
+oc-pilot flaky
+oc-pilot flaky --runs 5
+oc-pilot flaky --shuffle --command "node --test {files}"
+oc-pilot flaky --command "go test ./..." --json
+oc-pilot flaky --fail-on-flaky
+```
+
+`--runs <n>` defaults to 3 and caps at 10. `--command` overrides `testCommand` from `.oc-pilot.json` and the detected test command. `--fail-on-flaky` exits with code 1 when at least one test flipped, which makes it usable as a CI gate.
+
+`--shuffle` turns the run into an order test. It requires `{files}` in `--command`, collects the test files from the repository, shuffles them with a seeded PRNG and substitutes the list into the command. Every run gets a fresh seed derived from the base one, so a test that fails only after a particular neighbour shows up as flaky. `--seed <value>` fixes the base seed when you need to reproduce a failure.
+
+Per-test results are parsed from the Node test runner spec reporter, TAP, Go (`--- PASS`/`--- FAIL`), pytest (`PASSED`/`FAILED`) and Jest/Vitest (`✓`/`✕`). If the output carries no recognizable markers, `parsed` is false and the report only tells you that the exit codes were compared.
+
+The JSON payload is `{command, runs, completed, parsed, tests, flaky, failing, shuffle}`; each test is `{name, passes, failures, status}` with `status` equal to `flaky`, `failing` or `passing`. With `--shuffle`, `shuffle` is `{seed, files}`.
+
+### `authz`
+
+Authorization review of HTTP routes: a route that never checks the session, an object fetched by an id from the request without an ownership check (IDOR), and an admin path without a role guard. It reads the changed source files and never calls a model.
+
+```bash
+oc-pilot authz --staged
+oc-pilot authz --public /health,/login
+oc-pilot authz --staged --fail-on-issue medium
+oc-pilot authz --staged --format sarif -o authz.sarif
+```
+
+Express, Fastify and Koa route calls (`app.get`, `router.post`, ...) are recognized, plus Next.js `app/**/route.ts` and `pages/api/**`. A handler passed by reference (`router.get("/x", controller.list)`) is skipped because the guard may live in the controller. Routes under `/health`, `/login`, `/signup`, `/public`, `/webhooks`, `/oauth` and similar are treated as public; `--public <prefixes>` extends that list.
+
+Suppress a deliberate exception on the route line or the line above:
+
+```js
+// oc-pilot:authz-ignore idor: the gateway scopes the query by tenant
+router.get("/users/:id", handler);
+```
+
+A suppression without a reason is ignored. `--ignore <rules>` skips whole rules and `--no-suppressions` disables inline suppressions.
+
+`--fail-on-issue <high|medium>` sets the exit threshold (default `high`). `--format sarif` emits SARIF 2.1.0 with the rule id, method and route.
+
+`--baseline <file>` hides findings already recorded in `.oc-pilot/baseline.json`, so only new findings fail the run; `--update-baseline` writes the current findings to that file and exits with code 0, which lets a legacy repository adopt the gate without fixing everything at once. The baseline stores SHA-256 fingerprints of the rule, file and snippet (or method and route for `authz`), so entries survive line moves. `preflight` and `receipt` read the same default baseline.
+
+The JSON payload is `{files, routes, findings, suppressed, summary}`; each route is `{file, line, method, route, public}` and each finding adds `{rule, severity, method, route}` to the location. With `--baseline` the payload adds `baselineSuppressed`; with `--update-baseline` it adds `baseline: {path, updated, entries}`.
+
+### `sast`
+
+Deterministic static analysis of the changed files: command and SQL injection, path traversal, SSRF, code execution, XSS, open redirects, disabled TLS verification, wildcard CORS, prototype pollution, weak hashes and JWT `none`. No model call, no network: the same diff always produces the same findings.
+
+```bash
+oc-pilot sast --staged
+oc-pilot sast --base main --fail-on-issue medium
+oc-pilot sast src/server.ts --json
+oc-pilot sast --staged --format sarif -o sast.sarif
 ```
 
-Exit 1 means critical secrets were found. `--strict` also fails on warnings.
+The analysis is taint-aware but heuristic: a sink is reported when request data (`req.query`, `req.body`, `req.params`, headers, cookies, `userInput`, `untrusted*`) or a template interpolation reaches it within the same expression. Constants and parameterized queries are not reported. `path.resolve`, `path.normalize`, `path.basename` and `path.join` suppress path traversal findings.
+
+Suppress a deliberate exception on the finding line or the line above:
+
+```js
+exec(req.query.cmd); // oc-pilot:sast-ignore command-injection: admin-only endpoint
+```
+
+A suppression without a reason is ignored. `--ignore <rules>` skips whole rules, `--no-suppressions` disables inline suppressions for an audit run.
+
+`--fail-on-issue <high|medium|low>` sets the exit code threshold (default `high`). `--format sarif` emits SARIF 2.1.0 for GitHub code scanning and other SARIF consumers.
+
+`--baseline <file>` hides findings already recorded in `.oc-pilot/baseline.json`, so only new findings fail the run; `--update-baseline` writes the current findings to that file and exits with code 0, which lets a legacy repository adopt the gate without fixing everything at once. The baseline stores SHA-256 fingerprints of the rule, file and snippet, so entries survive line moves. `preflight` and `receipt` read the same default baseline.
+
+The JSON payload is `{files, findings, suppressed, summary}`; each finding is `{rule, severity, file, line, column, message, snippet}` and `summary` counts `high`, `medium`, `low`. With `--baseline` the payload adds `baselineSuppressed`; with `--update-baseline` it adds `baseline: {path, updated, entries}`.
+
+### `deps`
+
+Offline health audit of npm, pnpm and yarn dependencies. No model call, no network.
+
+```bash
+oc-pilot deps
+oc-pilot deps --json
+oc-pilot deps --fail-on-issue high
+oc-pilot deps --ignore lint-staged
+oc-pilot deps --fix --dry-run
+oc-pilot deps --fix
+oc-pilot deps --why qs
+oc-pilot deps --audit --fail-on-vuln high
+oc-pilot deps --audit --offline
+oc-pilot deps --sbom sbom.json
+```
+
+It compares `package.json` with what the code actually imports and with the lockfile the project uses: `package-lock.json`, `pnpm-lock.yaml` or `yarn.lock`.
+
+- **phantom** (high) — a package is imported but not declared, so a clean install or CI fails;
+- **unused** (medium) — declared but never imported or mentioned in scripts;
+- **misplaced** (low) — used only by tests but listed in `dependencies`;
+- **duplicate** (low) — two libraries from the same group solve one job (`moment` and `dayjs`);
+- **unpinned** (medium) — `*`, `latest` or an empty spec;
+- **vcs** (high for git/URL, low for `file:`) — a dependency from git, a URL or a local path;
+- **lockfile** (high) — declared but missing from the project lockfile, so a clean install fails (`npm ci`, `pnpm install --frozen-lockfile` or `yarn install --immutable`).
+
+`--fail-on-issue <high|medium|low>` turns the audit into a CI gate (exit 1). `--ignore <names>` accepts a comma-separated list for false positives, for example when a package is loaded dynamically. Workspace packages (`packages/*`) and `@types/*` are handled; peer dependencies are not reported as unused.
+
+`--fix` repairs what can be decided offline: a package used only by tests moves to `devDependencies`, an imported-but-undeclared package is added with the version already resolved in the lockfile (to `devDependencies` when every importer is a test), and a floating `*`/`latest` spec is pinned to the lockfile version. Nothing is invented: a phantom import without a lockfile entry, an unused package, a duplicate or a vcs dependency is listed as skipped with the reason. `--dry-run` prints the plan without touching `package.json`. After writing, the audit re-runs, so the exit code reflects the fixed state.
+
+`--why <name>` answers the question that comes before any cleanup: where does this package actually come from. It reads `package.json` and the lockfile locally and prints the declared field and spec, the files that import it, the packages that depend on it, every installed version and copy count, and the dependency chains from the root. A package that is neither declared, installed nor imported exits with code 1. `--why` cannot be combined with `--fix`.
+
+`--audit` adds known vulnerabilities and licenses. It asks OSV (`api.osv.dev`) for every locked package, reports CVE/GHSA ids, severity and the first fixed version, and caches answers in `.oc-pilot/osv-cache.json` for 24 hours. `--offline` uses the cache without touching the network and fails when the cache is empty. `--osv-url` points the query at a mirror. `--fail-on-vuln <critical|high|medium|low>` turns the result into a security gate: the command exits with code 1 when any vulnerability reaches the threshold. Licenses are read from installed `node_modules` manifests; strong copyleft, proprietary and unknown licenses are listed, and packages without an installed manifest are counted as `missing` instead of guessed.
+
+`--sbom <file>` writes a CycloneDX 1.5 software bill of materials for every locked package, with npm purls, relative to the project root. It needs no network.
+
+The JSON payload is `{packageName, declared, imported, scannedFiles, truncated, lockfile, issues}`; with `--fix` it gains `fix: {applied, dryRun, fixes, skipped}`, with `--why` the command prints a single `DependencyWhy` object: `{name, versions, copies, declared, importedBy, dependents, chains}`, with `--audit` it gains `audit: {checked, unchecked, vulnerabilities, online, stale, cachePath, licenses}`, and with `--sbom` — `sbom: <path>`.
+
+### `commit`
+
+Generates a Conventional Commits message from staged changes and optionally commits it. The model also sees the last 10 commit subjects, so the message matches the project's existing style.
+
+```bash
+oc-pilot commit               # print the message
+oc-pilot commit --apply       # commit staged with the generated message
+oc-pilot commit --json        # machine-readable output
+```
+
+`--apply` works only with staged changes and is blocked (exit 3) when the diff contains critical secrets; pass `--allow-secrets` to override. With `--engine openai` an oversized diff is split into per-file slices (see Engines) and the message covers all of them.
+
+### `install-hook`
+
+Installs native git hooks without husky or any dependency. The managed `pre-commit` hook runs `oc-pilot preflight --staged`: secrets, SAST, route authorization, dependency health scoped to the change, test weakening and the Slop Index delta. `--pre-push` also installs a `pre-push` hook that runs `oc-pilot review --fail-on critical --fail-on-secrets`. Pass `--scan` to keep a lighter pre-commit that only runs `oc-pilot scan --staged`.
+
+```bash
+oc-pilot install-hook
+oc-pilot install-hook --scan
+oc-pilot install-hook --pre-push
+oc-pilot install-hook --uninstall
+```
+
+Hooks are opt-in and reversible. A hook that does not belong to oc-pilot is never overwritten unless `--force` is passed, and then the old file is kept as `<hook>.oc-pilot.bak`. Every managed hook is stamped with a marker; hooks written by older versions are reported as outdated by `oc-pilot doctor` and upgraded in place with `oc-pilot doctor --fix`. Set `OC_PILOT_SKIP=1` to bypass the hooks for a single command. `core.hooksPath` and worktrees are respected.
+
+### `restore`
+
+Restores the working tree from the latest snapshot taken before `fix --apply`.
+
+```bash
+oc-pilot restore          # latest snapshot
+oc-pilot restore --list   # list saved snapshots
+oc-pilot restore <id>     # a specific snapshot
+```
+
+Snapshots live under `.git/oc-pilot/snapshots/` and never enter commits. Restore refuses to run when the branch head has moved since the snapshot, so committed work is never lost. The staged/unstaged split is not restored, and untracked files created after the snapshot are not deleted.
+
+### `cache`
+
+Inspects and maintains the `openai` response cache stored in `.git/oc-pilot/cache/`.
+
+```bash
+oc-pilot cache            # entries, size, expired count
+oc-pilot cache --prune    # delete expired entries
+oc-pilot cache --clear    # delete everything
+```
+
+The cache only works inside a git repository and only applies to the `openai` engine.
+
+### `stats`
+
+Prints usage statistics from `.git/oc-pilot/stats.jsonl`: runs, API calls, cache hits, average call duration and findings (critical/warning/style) for today, the last 7 days and all time.
+
+```bash
+oc-pilot stats
+oc-pilot stats --json
+oc-pilot stats --clear
+```
+
+### `day`
+
+A local activity digest: what was committed since a point in time, which files churned most, lines added/deleted, and the oc-pilot findings for that period.
+
+```bash
+oc-pilot day
+oc-pilot day --since "3 days ago" --json
+```
+
+### `impact`
+
+Shows where else the symbols you changed are used. It extracts function, method, class, type and interface declarations from the diff (both added and removed lines, so renames show up under both names) and greps tracked and untracked files for them. This is a text search, not AST analysis, so it can over-report; it never fails the build.
+
+```bash
+oc-pilot impact
+oc-pilot impact --staged --json
+```
+
+`--json` returns `symbols`, `references`, `scannedFiles` and `touchedFiles`, which is the shape agents want when they need to know what else a change might break.
+
+### `explain`
+
+Explains the findings of the previous review for one place in the code. Every `review` run stores its findings in `.git/oc-pilot/last-review.json`; `explain` looks up the finding on the given line, or the nearest one within three lines, and prints it next to a snippet of the current file. Secrets in the snippet are redacted by the same scanner as everywhere else.
+
+```bash
+oc-pilot explain src/wallet.ts:42
+oc-pilot explain src/wallet.ts:42 --json
+```
+
+Without a line number, or when nothing matches, it falls back to every finding in that file, so the command stays useful when the file shifted.
+
+### `reviewers`
+
+Suggests who should review the current diff. For every changed file it walks the recent commits that touched it, counts the authors and picks the top candidates; bots are skipped. `CODEOWNERS` from `.github/CODEOWNERS`, `CODEOWNERS` or `docs/CODEOWNERS` is read and matched with the same last-rule-wins semantics as GitHub and GitLab.
+
+```bash
+oc-pilot reviewers --base main
+oc-pilot reviewers --staged --limit 5 --exclude renovate
+oc-pilot reviewers --base main --json -o reviewers.json
+```
+
+`--depth` looks further back than the default 50 commits. `--json` returns the files, the candidates (`name`, `email`, `commits`, `files`, `share`) and the matched `codeowners`, which is enough to fill `gh pr create --reviewer`.
+
+### `replay`
+
+Re-renders the last saved review without calling a model. Every `review` writes `.git/oc-pilot/last-review.json`, so a SARIF report or a PR comment can be regenerated for free, or handed to a colleague.
+
+```bash
+oc-pilot replay
+oc-pilot replay --format sarif -o report.sarif
+oc-pilot replay --as md -o pr-comment.md
+oc-pilot replay --in saved.json --fail-on critical
+```
+
+`--format` accepts text, json and sarif; `--as` adds md for the PR comment body. `--in` reads any file with a `findings` array. The exit code follows `--fail-on`, exactly as in `review`.
+
+### `slop`
+
+Measures the entropy that fast, model-assisted coding leaves behind. `oc-pilot slop` scores a repository from 0 (clean) to 100 (rotten) without an API key, a model or network access: it needs only git and the working tree.
+
+| Category | What it finds | Max |
+| --- | --- | --- |
+| Duplicates | Blocks of 72 or more tokens repeated across two different files | 30 |
+| Dead code | Exports whose name appears in no other file (type-only exports and entry points are skipped) | 25 |
+| Churn without tests | Files touched by five or more commits while tests changed in fewer than 40% of them | 25 |
+| TODO graveyard | `TODO`, `FIXME`, `HACK` and `XXX` inside comments, weighted by age from `git blame` | 20 |
+
+```bash
+oc-pilot slop
+oc-pilot slop --since origin/main --max-delta 10
+oc-pilot slop --json -o slop.json
+oc-pilot slop --badge -o slop.svg
+```
+
+`--since <ref>` compares the working tree with a revision and reports what this branch introduced and removed per category, plus `deltaPoints`. The delta matters more than the absolute number: a repository can sit at 50 and still be stable.
+
+Other flags: `--limit` (items per category), `--since-days` (churn and blame window, default 30), `--exclude` (globs or substrings), `--no-blame` (skip `git blame`, much faster), `--max-index` and `--max-delta` (exit code 3 when exceeded), `--badge` (shields-style SVG), `--json`.
+
+False positives go to `.oc-pilot/slopignore`: one glob or substring per line, `#` starts a comment. Comments and string literals are stripped before analysis, and test files, generated files and lock files are skipped. The score is a heuristic, not a verdict.
 
 ### `setup`
 
@@ -270,17 +755,26 @@ One command that explains why a setup is not working:
 oc-pilot doctor
 oc-pilot doctor --json
 oc-pilot doctor --engine openai --model deepseek-chat
+oc-pilot doctor --fix
 ```
 
-It checks Node, the active engine, API credentials, git and repository state, the detected test command, project rules, and every MCP client config. Errors return exit code 1; `--strict` also fails on warnings. No secret values are printed.
+It checks Node, the active engine, API credentials, git and repository state, the detected test command, project rules, oc-pilot git hooks and the response cache, and every MCP client config. `--fix` refreshes outdated oc-pilot hooks (a backup of the previous file is kept) and prunes expired cache entries; foreign hooks are never touched and are reported instead. Errors return exit code 1; `--strict` also fails on warnings. No secret values are printed.
 
 ### `init`
 
 ```bash
 oc-pilot init
+oc-pilot init --preset node
+oc-pilot init --hooks
 ```
 
-Creates `.oc-pilot.json`. It does not overwrite an existing config unless `--force` is passed.
+Creates `.oc-pilot.json`. It does not overwrite an existing config unless `--force` is passed. With `--preset <a,b>` it also writes a curated `.oc-pilot/rules.md` for the stack. One or more presets can be combined, e.g. `--preset react,security`:
+
+`base` (language-agnostic), `node`, `react`, `next`, `vue`, `svelte`, `angular`, `typescript`, `python`, `go`, `rust`, `java`, `kotlin`, `csharp`, `swift`, `php`, `ruby`, `flutter`, `elixir`, `zig`, `scala`, `security` (cross-stack hardening), `devops` (Docker, CI, infrastructure).
+
+The rules file is a normal project rules file - edit it freely.
+
+`--hooks` installs the git hooks from `install-hook`: `preflight --staged` on commit and `review` on push. Existing hooks are backed up, and a missing hook directory is only a warning, so `init` never fails because of it.
 
 ## Common options
 
@@ -289,6 +783,7 @@ Creates `.oc-pilot.json`. It does not overwrite an existing config unless `--for
 | `-C, --cwd <dir>` | current directory | Project directory |
 | `-m, --model <id>` | engine default | Model id (`provider/model` for OpenCode) |
 | `--engine <name>` | `opencode` | `opencode` or `openai` (any compatible API) |
+| `--engine-preset <p>` | — | `ollama`, `lmstudio`, `openrouter` |
 | `--base-url <url>` | `https://api.openai.com/v1` | OpenAI-compatible endpoint |
 | `--api-key-env <name>` | `OC_PILOT_API_KEY` | Environment variable holding the API key |
 | `--agent <name>` | `oc-pilot` | Use another OpenCode agent |
@@ -298,12 +793,15 @@ Creates `.oc-pilot.json`. It does not overwrite an existing config unless `--for
 | `--fail-on <level>` | `none` | Exit 3 on `critical`, `warning`, or `style` findings |
 | `--max-diff <size>` | `120000` | Diff/context budget |
 | `--max-file <size>` | `60000` | Per-file budget for docgen |
+| `--max-cost <usd>` | `0` | Daily spend cap for `openai` calls (`0` disables) |
 | `--timeout <duration>` | `300` | Model/test timeout; supports `5m` |
 | `-o, --output <path>` | stdout | Write the result to a file |
+| `--format <f>` | `text` | Output format: `text`, `json`, `sarif` (`scan`, `review`) |
 | `--json` | off | Machine-readable output |
 | `--dry-run` | off | Print the prompt without calling a model |
 | `--strict` | off | Exit 3 when the output schema is invalid |
 | `--verbose` | off | Stream OpenCode diagnostics |
+| `--no-cache` | off | Bypass the response cache (`openai`) |
 
 ## Project rules
 
@@ -325,7 +823,21 @@ The scanner looks at added diff lines and common source-file patterns:
 - private key blocks;
 - OpenAI, Anthropic, Hugging Face, Groq, Google, GitHub, GitLab, npm, PyPI, Slack, Discord, Telegram, Stripe, SendGrid, DigitalOcean, and AWS keys;
 - Azure storage account keys;
-- JWTs, credentials in URLs, and sensitive `.env` assignments.
+- JWTs, credentials in URLs, and sensitive `.env` assignments;
+- high-entropy assignments (Shannon entropy over 4 bits for values of 20+ characters) reported as critical.
+
+To silence a false positive, add path globs to `.oc-pilot/ignore` (one per line, `#` starts a comment), or append the inline marker to the source line:
+
+```
+# .oc-pilot/ignore
+fixtures/**
+docs/examples/**
+
+# inline, any language
+const TOKEN = "sk-proj-..."; // oc-pilot:ignore-secret
+```
+
+Ignore rules are path- and line-scoped, apply to every scanning point (diff, rules, docgen, full-file context), and never disable scanning for the rest of the project.
 
 Detected values never appear in full in logs or JSON. The model receives `[REDACTED:<kind>]` and a masked preview. Review the provider's data policy before sending proprietary code.
 
@@ -339,7 +851,7 @@ Markdown response:
 ### Analysis: Short conclusion.
 
 #### Findings / Actions
-- **🔴 Critical `wallet.go:10`**: nil pointer dereference.
+- **Critical `wallet.go:10`**: nil pointer dereference.
 
 #### Solution
 ```go
@@ -397,7 +909,10 @@ Markdown response:
   "maxFileChars": 60000,
   "timeoutSeconds": 300,
   "redactSecrets": true,
-  "testCommand": "npm test"
+  "testCommand": "npm test",
+  "agentRules": true,
+  "secondOpinionEnabled": false,
+  "maxDailyApiCalls": 0
 }
 ```
 
@@ -409,7 +924,29 @@ Environment variables: `OC_PILOT_ENGINE`, `OC_PILOT_BASE_URL`, `OC_PILOT_API_KEY
 
 `oc-pilot-mcp` exposes the same recipes as MCP tools over stdio. This is the recommended way to embed oc-pilot in an agent: the agent calls a tool, and no prompt needs to be copied.
 
-Tools: `review`, `test_fix`, `fix`, `docgen`, `custom`, `scan`. The server is read-only by default; start it with `--allow-write` to permit `fix` with `apply: true` and `test_fix` with a command.
+Besides tools, the server exposes read-only MCP resources: `oc-pilot://config` (resolved configuration), `oc-pilot://rules` (project rules with secrets redacted), `oc-pilot://prompt/en` and `oc-pilot://prompt/ru` (the built-in system prompts), and `oc-pilot://version`. `oc-pilot://slop` returns the Slop Index as JSON without calling a model. Resource templates cover live data: `oc-pilot://diff/{mode}` (staged/unstaged/head diff, secrets redacted), `oc-pilot://scan/{mode}` (offline secret scan as JSON) and `oc-pilot://file/{+path}` (any project file up to 2 MB with detected secrets redacted). Hosts can list them with `resources/list` and `resources/templates/list`.
+
+Tools: `review`, `invariants`, `test_fix`, `fix`, `test_gen`, `docgen`, `custom`, `scan`, `commit`, `stats`, `slop`, `mutate`, `fuzz`, `bankruptcy`, `query_ast`, `sandbox`, `hivemind_status`, `flaky`, `impact`, `deps`, `coverage`, `reviewers`, `test_guard`, `env_sync`, `mock_leak`, `ecosystem_verify`, `pack`, `pack_hologram`, `zoom_symbol`, `contract_drift`, `anti_regression`, `boundaries`, `test_plan`, `compliance_verify`, `brag`, `battle`, `cleanup`, `arch_diff`, `roast`, `cinema`, `bounty`, `autopsy`, `echo`, `sast`, `authz`, `preflight`, `ready`, `receipt_verify`. `scan` accepts `all: true` to sweep the whole repository instead of the diff. `slop` runs the offline Slop Index and accepts `since`, `since_days`, `limit`, `exclude` and `no_blame`. `mutate` runs mutation testing on the changed code, accepts `command`, `max_mutants` and `min_score`, and returns the score plus every surviving mutant; a score below `min_score` is a normal result with exit code 1. `flaky` runs the test command several times and compares per-test results, accepting `runs`, `command`, `fail_on_flaky`, `shuffle` and `seed`; it never edits source files itself but does run the project's tests. `impact` lists the declarations the diff changed or removed and every untouched file that still mentions them, accepting the same source flags; the search is textual, so comments and strings can match. `deps` audits declared, imported and locked dependencies, explains a chain with `why`, adds OSV vulnerabilities and licenses with `audit`, and can rewrite `package.json` with `fix` or emit a CycloneDX SBOM; `fix` and `sbom` write files. `coverage` compares changed lines with a local lcov, Istanbul, Cobertura or Go coverage report and returns uncovered lines, missing files and a gate on `fail_under` or `max_uncovered`. `reviewers` ranks the authors who touched the changed files, lists CODEOWNERS owners and accepts `limit`, `depth` and `exclude`; it uses git history only. `test_guard` runs the offline anti-cheating check on the diff: skipped, focused or deleted tests, removed or commented assertions, raised timeouts, strict matchers replaced by existence checks, `@ts-ignore` and empty catch blocks; with `fail_on_weakening` a finding returns exit code 1. `env_sync` compares the environment variables added by the diff (`process.env`, `import.meta.env`, `Deno.env`, `Bun.env`) with the local `.env` files and `.env.example`/`.sample`/`.template`: missing definitions fail with `fail_on_missing`, and defined but undocumented variables warn. `mock_leak` scans added production code for forgotten stubs and hardcode: local paths, test tokens, `if (true)`/`if (false)`, mock/fake/stub identifiers, mock comments and localhost URLs; `fail_on_leak` returns exit code 1 at the chosen severity. `ecosystem_verify` checks that named imports from the changed files exist in the installed package entry or its `.d.ts`, and flags packages that are neither installed nor declared; with `online` it also checks the age and weekly downloads of newly added npm packages, and `fail_on_issue` returns exit code 1 at the chosen severity. `pack` builds a compact context bundle for a task: project rules, changed-file signatures, related references and an optional test log, capped by `budget` characters; it never edits files. `contract_drift` compares changed TypeScript interfaces, Zod objects, Prisma models, Pydantic models and JSON Schema with the previous version, flags removed or newly required fields and type changes, and reports untouched consumers that still use a removed field; `fail_on_drift` returns exit code 1 at the chosen severity. `anti_regression` compares the lines added by the diff with lines a human explicitly deleted in git history, cites the deleting commit and flags re-added code or imports; `fail_on_regression` returns exit code 1. `boundaries` checks added imports against `.oc-pilot/architecture.json` layer rules, reports the file, line, import and rule reason, and `fail_on_violation` returns exit code 1 when a layer boundary is crossed. `test_plan` selects the test files affected by the diff from a static import graph: changed tests, direct and transitive importers, naming matches and symbol references, with uncovered changed files reported and an optional `fail_on_uncovered` gate. `compliance_verify` checks a signed audit manifest for the current commit: SHA-256, commit, previous-manifest hash chain and optional Ed25519 signature; a missing, edited or broken manifest is a normal result with exit code 1. `brag` builds a self-contained HTML or SVG session report from stats, git history, the last review and the receipt; it uses inline assets only, never calls a model or the network, and `no_paths` hides file locations. `test_gen` asks the model for tests that cover the changed code; with `apply` it writes test files, runs the suite and reverts failing tests unless `keep_failing`, while `coverage` narrows generation to uncovered changed lines and `from_slop` picks untested files. `cleanup` builds an offline cleanup plan from dependency issues, the Slop Index, environment variables and weakened tests; `apply` performs only safe dependency fixes and needs `--allow-write`. `arch_diff` renders a Mermaid diagram of the internal imports the diff added and removed: green edges are new dependencies, red dashed edges are removed ones, and `fail_on_removed` returns exit code 1 when a dependency disappears. `roast` turns the diff into a technically grounded comedy roast in a chosen persona (linus, ramsay, corporate or default), cites file:line for every joke and ends with one real fix; it is model-backed and never edits files. `cinema` builds a terminal timelapse of the session from commits, runs, API calls, the last review and the receipt: a self-contained HTML player or an asciinema v2 cast, with no network, external assets or model call; `no_paths` hides subjects and finding locations. `bounty` scores every file from SAST findings, duplicated blocks, dead exports, aged TODOs and churn without tests, then renders an ASCII WANTED poster with the worst file and its reasons; deterministic and offline. `autopsy` performs a post-mortem on a commit: diff stats, SAST on added lines, weakened tests, mock leaks, ranked suspects and a before/after timeline; `fail_on_risk` returns exit 1 for a dangerous verdict. `echo` builds self-contained SVG badges from local stats, git history and the receipt (commits, agent runs, API calls, cache hits, findings and test status); `submit` sends only the nickname, window and aggregate numbers to an explicit `endpoint`, never paths, diffs or secrets, and there is no network by default. `sast` runs the deterministic static analysis over the change or over explicit `paths` and accepts `fail_on_issue`, `ignore` and `no_suppressions`; a finding at or above the gate is a normal result with exit code 1. `authz` checks route authorization over the change or explicit `paths` and accepts `fail_on_issue`, `ignore`, `public` and `no_suppressions`; a route finding at or above the gate is also a normal result with exit code 1. `preflight` returns one offline verdict over the planned change and accepts the same source flags (`diff`, `base`, `staged`, `unstaged`, `include_untracked`), plus `since`, `max_delta`, `fail_on_issue`, `no_secret_scan`, `no_sast`, `no_authz`, `no_deps`, `no_tests` and `no_slop`; a failed check is a normal result with `status: "fail"` and exit code 1, so the agent sees the failing check instead of a tool error. `ready` returns the offline agent readiness score 0-100 and accepts `fail_under`; a score below the threshold is also a normal result with exit code 1. `receipt_verify` recomputes the SHA-256 hash of the receipt, compares the recorded commit with HEAD and reports `ok`, `hashOk` and `stale`; a missing, edited or stale receipt is a normal result with `ok: false` and exit code 1, so an agent can see why the proof failed. The `fix` tool accepts `from_sast` and `from_authz` to repair security findings and rescan; the result then carries `sast` or `authz` with `{before, after, remaining}`. The server is read-only by default; start it with `--allow-write` to permit `fix` with `apply: true`, `commit` with `apply: true`, `test_fix` with a command, `stats` with `clear: true` and `mutate`, which rewrites source files temporarily. `test_gen` with `apply: true` also needs `--allow-write`. The `fix` result carries the unified `patch`, its `files` and `patchStats` (`additions`, `deletions`, `hunks`, `bytes`); patches over 200 000 characters are cut and marked with `patchTruncated` and `patchBytes`, so a host can show or apply the change without parsing the diff again.
+
+`invariants` checks the diff against `.oc-pilot/invariants.md`
+
+`hivemind` is an encrypted TCP mesh for sharing analysis work: `init` creates an ed25519 identity, `trust` pins a peer public key, `serve` accepts signed ECDH X25519 handshakes, and `send` transmits AES-256-GCM encrypted payloads. Only diffs, AST and LLM requests are allowed; executable payloads are rejected, and untrusted peers are dropped before any data is read.
+
+`sandbox run <file>` executes one self-contained JavaScript or ESM file in `node:vm` with a separate context: static imports, `require`, `fetch`, `process.exit` and timers longer than a second are blocked, console output is captured, and execution is capped by `--timeout` and `--memory-limit`. TypeScript runs only from a built `dist/*.js`. This is not an OS sandbox for native code.
+
+`query` runs a chainable AQL query against a lightweight code graph: `find(File|Function|Class|Import|CallExpression).where(field, value).sort(field).limit(n).select(fields...).count()`. It is not SQL and not a full TypeScript AST; it is a fast textual graph that the agent can probe before editing. MCP exposes it as `query_ast`.
+
+`bankruptcy` forecasts technical debt from commit history: it scores each commit by weakened tests, SAST high/medium findings, added TODOs, churn and a slop proxy, smooths the daily series with a 14-day moving average, drops outliers and fits a linear regression. The output is the current score, slope, forecast date and a self-contained SVG chart; fewer than 10 commits returns `[INSUFFICIENT DATA: Need at least 10 commits to compute Slop Velocity]`. `--explain` prints the exact weights, where test weakening (0.35) and security (0.30) dominate.
+
+`fix --shadow` and `battle --shadow` run the applied patch inside `.oc-pilot/shadow-tree`, a detached git worktree, so tests and external compilers see the modified files. The diff is extracted with `git diff` and applied to the real tree only when the run succeeds; a failed run leaves the working tree untouched. `--shadow` requires `--apply`.
+
+`fuzz` discovers exported functions added by the diff and calls them with null, undefined, -1, 0, an empty string, a 10MB string, a `__proto__` object and empty containers. Every target runs in a separate Node process with a hard 2s timeout, a configurable heap cap and mocked fs/net/http/child_process; files that import side-effect modules are blocked before execution, and a crash or timeout is reported with the exact input. No model call.: each `## area` scopes its rules, `[CRITICAL]` marks a blocking rule, and rules whose area touches none of the changed files or their importers are skipped as `[SKIPPED: Out of scope]` without a model call. The model must answer strict JSON; verdicts are cached by the hash of diff and invariants, and violations are warnings by default. A CRITICAL violation or `--strict` / `--fail-on violation` returns exit code 3. `preflight --invariants` adds the same check to the gate.
+
+`pack --hologram` builds a layered context instead of dumping the repository: LOD 0 keeps diff files complete, LOD 1 hides function bodies behind `body hidden` markers with `EFFECTS` hints and adds matching tests, LOD 2 lists export names only. Unbalanced braces fall back to full text with `[Hologram: parse bailout]`, and the final Markdown is secret-scanned. `zoom-symbol <file> <symbol>` returns one hidden body on demand; `pack_hologram` and `zoom_symbol` expose the same flow over MCP.
+
+Every tool accepts `max_findings` (default 50; a capped result also carries `truncated` and `totalFindings`) and `verbosity` (`full` returns the JSON payload, `compact` returns a one-line summary and keeps the same data in `structuredContent`). When a client sends `_meta.progressToken`, the server emits `notifications/progress`; after `logging/setLevel` it also emits `notifications/message` per call. `--max-calls <n>` (or `OC_PILOT_MCP_MAX_CALLS`) caps model-backed calls per session, `0` disables the cap, and the offline tools `scan`, `fuzz`, `bankruptcy`, `query_ast`, `sandbox`, `hivemind_status`, `stats`, `slop`, `flaky`, `impact`, `deps`, `coverage`, `reviewers`, `test_guard`, `env_sync`, `mock_leak`, `ecosystem_verify`, `pack`, `pack_hologram`, `zoom_symbol`, `contract_drift`, `anti_regression`, `boundaries`, `test_plan`, `compliance_verify`, `brag`, `cleanup`, `arch_diff`, `roast`, `cinema`, `bounty`, `autopsy`, `echo`, `sast`, `authz`, `preflight`, `ready` and `receipt_verify` keep working after the budget is exhausted.
+
+Ready-made prompts are advertised through `prompts/list` and rendered by `prompts/get`, so a host can offer them in its own menu: `review-my-diff` (optional `context`), `fix-failing-tests` (optional `log`), `pre-commit-gate` (scan, review and commit in one pass), `secure-change` (security-focused review), `slop-check` (entropy check for vibe-coded changes) and `preflight-before-commit` (run the offline gate, fix the cheapest failing check, rerun until the verdict is pass), `compile-hologram` (build a layered hologram, keep LOD 0 complete, treat hidden LOD 1 bodies as unknown and call `zoom_symbol` before reasoning about them), `check-invariants` (check the change against `.oc-pilot/invariants.md`, explain every violation with file:line and never hide a CRITICAL rule), `fuzz-the-diff` (call the new exports with hostile inputs in isolated processes, fix every crash and never count blocked targets as tested), `forecast-tech-debt` (read the tech-debt trend, explain the score and weights, and use the forecast date to plan repayment instead of gaming TODO counts), `query-the-ast` (locate calls, functions, classes and imports with AQL, verify each hit in the source and use the evidence to plan a refactor), `sandbox-script` (run a generated JS/ESM file in node:vm with imports and side effects blocked, then report its output and exact status), `join-the-swarm` (check the hivemind identity and trusted peers, then exchange only diffs, AST and LLM requests over the encrypted mesh; never send executable commands), `get-ready` (score the repository, fix the safe gaps, prove the result with a receipt and rerun until the score is at least 85), `fix-security` (repair SAST or route-authorization findings and rescan until no high findings remain), `stabilize-flaky` (reproduce a flaky test with repeated and shuffled runs and make the smallest deterministic fix), `check-impact` (find external references to changed declarations, update what the change broke and rerun until no stale references remain), `triage-deps` (audit dependencies and OSV vulnerabilities, fix the cheapest issue first and rerun without hiding findings), `cover-changed-lines` (add tests for the changed lines that no test executed and rerun the same gate), `generate-tests` (generate tests for the change or its uncovered lines, apply them, run the suite and iterate until green), `pick-reviewers` (choose the smallest set of reviewers who know the changed files, with evidence from history and CODEOWNERS), `guard-tests` (find tests the change skipped, weakened or deleted, restore their protection and rerun until the guard passes), `sync-env` (compare the environment variables added by the change with `.env` and `.env.example`, add the missing definitions and document them without inventing secrets), `remove-mocks` (find forgotten mocks, local paths, test tokens and always-true conditions in production code, replace them with the real implementation and rerun until the leak report is clean), `verify-ecosystem` (check that imports exist in installed packages and that new npm packages are not brand new with a handful of downloads, and do not install a suspicious package without a human decision), `pack-context` (build a compact task bundle of rules, signatures, references and test log and use it instead of dumping whole files), `check-contracts` (find removed or narrowed fields in changed types and schemas, update every remaining consumer without silently breaking callers), `guard-regressions` (compare added lines with code a human deleted, inspect the deleting commit and do not re-add it without an explicit decision), `respect-boundaries` (check added imports against the layer rules, fix the dependency direction and rerun until no boundary is crossed), `plan-tests` (run the affected-test plan, run only those tests, add a test for every uncovered changed file and rerun without widening the strategy), `prove-compliance` (verify the signed audit manifest for HEAD, check the hash chain and signature, and never claim completion while the manifest is invalid), `cleanup-plan` (build an offline cleanup plan and apply only safe dependency fixes), `show-arch-diff` (render a Mermaid diagram of the internal imports the change adds and removes), `roast-my-code` (roast the diff in a chosen persona, cite file:line and end with one real fix), `play-session` (build a terminal timelapse of the session as a self-contained HTML player or an asciinema cast), `wanted-poster` (post a WANTED poster for the worst file, explain its reasons and the highest-weight fix, and rerun after the fix), `autopsy-commit` (run a post-mortem on a commit, list its signals, rank the suspects, read the before/after timeline and propose the smallest fix and the test that would have caught it), `share-progress` (build local SVG badges and, only with explicit approval, submit the anonymous aggregate payload to the given endpoint), `prove-tests` (run mutation testing on the change and strengthen the tests until the mutation score is at least 80) and `prove-done` (verify the receipt for HEAD, create a fresh one when it is missing or stale, and refuse to claim completion until `ok` is true and the tests in the receipt passed).
 
 Configure a client automatically:
 
@@ -428,7 +965,7 @@ Start the server manually with an explicit project directory:
 ```bash
 oc-pilot-mcp --cwd /absolute/path/to/project
 # after the npm release, pinned for reproducibility:
-npx -y oc-pilot@0.5.1 mcp --cwd /absolute/path/to/project
+npx -y oc-pilot@0.5.2 mcp --cwd /absolute/path/to/project
 ```
 
 The `diff` and `log` tool arguments are text, not file paths. `paths` and `files` are project-relative and cannot escape the project directory. `context` is literal text, not an `@file` reference. `base` must be a git ref. `lang`, `fail_on`, `repo_context`, and `no_secret_scan` are available where the corresponding CLI command supports them.
@@ -554,7 +1091,7 @@ oc-pilot-mcp --http --host 127.0.0.1 --port 8787 --path /mcp \
 curl http://127.0.0.1:8787/health
 ```
 
-MCP is **read-only by default**, over both stdio and HTTP: `scan`, `review`, `docgen`, `custom`, and patch-proposal `fix` work; `fix` with `apply: true` and `test_fix` that runs a new command are rejected. Add `--allow-write` only for a trusted local client or an authenticated deployment. `oc-pilot setup --allow-write` adds the flag to generated client config.
+MCP is **read-only by default**, over both stdio and HTTP: `scan`, `review`, `docgen`, `custom`, and patch-proposal `fix` work; `fix` with `apply: true`, `test_fix` that runs a new command, and `deps` with `fix: true` or `sbom` are rejected. Add `--allow-write` only for a trusted local client or an authenticated deployment. `oc-pilot setup --allow-write` adds the flag to generated client config.
 
 The MCP endpoint sets `Mcp-Session-Id` on initialize. When `--token` is set, every request needs `Authorization: Bearer <token>` except `GET /health`. A non-loopback bind **refuses to start** without a token of at least 16 characters. Put a TLS-terminating reverse proxy in front of any public deployment.
 
@@ -574,7 +1111,18 @@ Or use `docker-compose up`; the compose file requires `OC_PILOT_MCP_TOKEN`. The
 
 ### Agent skills
 
-`skills/oc-pilot/SKILL.md` is an Agent Skill for Claude Code, Codex, and OpenCode. It teaches an agent when to call `scan`, `review`, `test-fix`, `fix`, and `docgen` through MCP or the CLI. Copy the `skills/oc-pilot` directory into your skills directory, or point the client at this repository.
+`skills/` contains portable Agent Skills for Claude Code, Codex, Cursor, Copilot and OpenCode. Each one teaches an agent a gate to clear before the work is called done:
+
+| Skill | Purpose |
+| --- | --- |
+| `oc-pilot` | Entry point: when to call `scan`, `review`, `test-fix`, `fix` and `docgen`. |
+| `agent-self-review` | Pre-commit loop: scan, review, fix, re-verify, report the exit code. |
+| `test-failure-triage` | Capture the failing log, find the root cause, patch with a snapshot, re-run. |
+| `secure-diff-gate` | Secrets, security rules, prompt-injection signals and dependency risks, plus SARIF. |
+| `commit-discipline` | Conventional Commit message from the staged diff, with a secret gate. |
+| `stack-review-packs` | Combinable rules packs for 23 stacks. |
+
+Copy the directory you need into your skills directory, or point the client at this repository.
 
 See [docs/integrations.md](docs/integrations.md) for protocols, result shapes, setup details, and shell-only fallbacks.
 
@@ -592,7 +1140,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: MyNameIsNikki/oc-pilot@v0.5.1
+      - uses: MyNameIsNikki/oc-pilot@v0.88.1
         with:
           command: scan
           args: --base origin/${{ github.base_ref }} --fail-on-secrets
@@ -615,7 +1163,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - run: npm install -g https://github.com/MyNameIsNikki/oc-pilot/archive/refs/tags/v0.5.1.tar.gz
+      - run: npm install -g https://github.com/MyNameIsNikki/oc-pilot/archive/refs/tags/v0.88.1.tar.gz
       - run: oc-pilot scan --base origin/${{ github.base_ref }}
       - run: oc-pilot review --base origin/${{ github.base_ref }} --fail-on warning --fail-on-secrets --github
         env:
@@ -624,6 +1172,17 @@ jobs:
 
 `--github` turns parsed findings into inline `::error file=...,line=...` and `::warning` annotations. `scan` needs no API key and is suitable for a fast first gate. Add `--json` instead when a later step needs the structured report.
 
+To upload results to GitHub Code Scanning, write a SARIF report and upload it:
+
+```yaml
+      - run: oc-pilot scan --base origin/${{ github.base_ref }} --format sarif -o oc-pilot.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: oc-pilot.sarif
+```
+
+Each release is published from a tag by the repository's own workflow (OIDC trusted publishing with a provenance attestation; set the `NPM_TOKEN` secret to fall back to a granular npm token), and the GitHub release body is taken from the matching `CHANGELOG.md` section. CI runs the suite on Node 22 and 24 and prints an informational coverage table from `node --test --experimental-test-coverage` — no threshold, so a noisy signal never blocks a merge.
+
 ## Security model
 
 - The built-in repo-context agent is read-only: `read`, `glob`, and `grep` only. `edit`, `shell`, `subagent`, web tools, and external directories are denied.
@@ -632,7 +1191,8 @@ jobs:
 - Diff, rules, and full-file content are scanned before being sent to the model.
 - Project rules and code comments are data, not instructions. The system prompt explicitly treats injected instructions as untrusted.
 - The repo-context agent runs inside the analyzed project, so project-level OpenCode config and plugins may load. Use `--no-repo-context` for untrusted repositories.
-- Only `fix --apply` writes to the working tree. It rejects patches that touch files outside the reviewed diff, checks the patch with `git apply --check`, runs the configured tests, and reverts the patch when they fail. It never commits or pushes.
+- Only `fix --apply` writes to the working tree. It rejects patches that touch files outside the reviewed diff, checks the patch with `git apply --check`, saves a local snapshot under `.git/oc-pilot/snapshots/` before applying, runs the configured tests, and reverts the patch when they fail. It never commits or pushes.
+- `install-hook` writes only managed hook files inside the git hooks directory, marks them with a header comment, keeps backups when `--force` replaces a foreign hook, and is fully reversible with `--uninstall`.
 - The HTTP transport uses the MCP session header and an optional bearer token. Plain HTTP has no transport encryption; use a TLS proxy for remote deployments, and do not expose it without a token.
 - No file is modified by `review`, `test-fix`, `docgen`, or `custom`.
 
@@ -661,6 +1221,14 @@ npm run prompt:export
 
 The project has no runtime dependencies. Dev dependencies are TypeScript and `@types/node`.
 
+### Regression tests
+
+Three layers keep the contracts the model sees from drifting:
+
+- `test/golden/` pins the built prompt input for fixed diffs, so section order, empty-value handling and secret redaction only change on purpose. Regenerate with `OC_PILOT_UPDATE_GOLDEN=1 npm test` and read the diff before committing.
+- `test/fixtures/model-output/` holds realistic model replies; `src/core/output-format.test.ts` asserts which severity, location and text the CLI reports for each one.
+- `normalizeLocation` collapses the location shapes models actually emit (`a.ts:10-14`, `a.ts:10,12`, `a.ts#L12`, `a.ts (line 10)` → `a.ts:10`), and bullets inside fenced code blocks are ignored when parsing.
+
 ## License
 
 MIT