@lhi/tdd-audit 1.16.0 → 1.20.0

package/README.md

@@ -1,162 +1,283 @@
 # @lhi/tdd-audit
+![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)
 [![tdd-audit](https://img.shields.io/badge/tdd--audit-passing-brightgreen)](https://www.npmjs.com/package/@lhi/tdd-audit) <!-- tdd-audit-badge -->
 
-> **v1.15.0** — Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — prove the hole exists, apply the fix, prove it's closed. Enforces ≥ 95% test coverage, README badge, and SECURITY.md on every audit.
+> **Your AI-generated code is probably vulnerable right now.** SQL injection. Hardcoded secrets. Prompt injection backdoors. The same assistant that built your feature in 30 minutes didn't think twice about security. `tdd-audit` finds the holes, proves they're real, and closes them — every fix backed by a failing test before and a passing test after.
+
+## One command. Proven secure.
+
+```bash
+npx @lhi/tdd-audit --local --claude
+```
+
+That's it. In seconds you get:
+
+- A severity-ranked findings report (CRITICAL → LOW) with the exact file and line
+- Exploit tests that **prove the vulnerability is real** — not theoretical
+- Patches that close each hole, verified by a passing test suite
+- ≥ 95% test coverage enforced, a README security badge, and a `SECURITY.md` ready for auditors
+
+No security expertise required. No config needed to start.
+
+---
+
+## Why this exists
+
+Vibecoders move fast. AI assistants hallucinate security. The result: apps with SQL injection in the ORM layer, JWT algorithm confusion, hardcoded API keys one `git log` away from leaking, and LLM prompt injection that hands your backend to anyone who knows the trick.
+
+PMs and security officers feel it too — "is this thing actually secure?" has no good answer when there are no tests proving it.
+
+`tdd-audit` gives you the answer. Every vulnerability is proven closed by a test, not just patched and hoped for the best.
+
+---
 
 ## Install
 
 ```bash
-npx @lhi/tdd-audit
+# Claude Code (recommended)
+npx @lhi/tdd-audit --local --claude
+
+# Gemini CLI / Codex / OpenCode / Cursor
+npx @lhi/tdd-audit --local
 ```
 
 On first run the installer:
 
-1. Scans your codebase for **57 vulnerability patterns** across 6 scanner modules and prints a severity-ranked report
-2. Scaffolds `__tests__/security/` with a framework-matched exploit test boilerplate
-3. Adds `test:security` to `package.json`
-4. Creates `.github/workflows/security-tests.yml` with SHA-pinned actions and `npm audit`
-5. Installs the `/tdd-audit` skill for your AI agent
+1. Scaffolds `__tests__/security/` with framework-matched exploit test boilerplate
+2. Adds `test:security` to `package.json`
+3. Creates `.github/workflows/security-tests.yml` — SHA-pinned actions, `npm audit` on every PR
+4. Installs the `/tdd-audit` skill in your AI agent
 
-### Flags
+Then open your agent and type `/tdd-audit`. It handles the rest.
 
-| Flag | Description |
-|---|---|
-| `--local` | Install into the current project instead of `~` |
-| `--claude` | Use `.claude/` instead of `.agents/` |
-| `--with-hooks` | Add a pre-commit hook that blocks commits on failing security tests |
-| `--skip-scan` | Skip the vulnerability scan on install |
-| `--scan` / `--scan-only` | Scan only — no install, no code changes |
-| `--json` | Output findings as JSON |
-| `--format sarif` | Output findings as SARIF 2.1.0 (GitHub code scanning) |
-| `--config <path>` | Load config from an explicit file path |
-
-### Platform
-
-| Platform | Command |
+### Install flags
+
+| Flag | What it does |
 |---|---|
-| Claude Code | `npx @lhi/tdd-audit --local --claude` |
-| Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
+| `--local` | Install into the current project (recommended) |
+| `--claude` | Use `.claude/` for Claude Code |
+| `--with-hooks` | Block commits that break security tests |
+| `--skip-scan` | Skip the initial vulnerability scan |
+| `--config <path>` | Load config from a specific path |
 
-## Usage
+---
 
-```text
-/tdd-audit
-```
+## What gets caught
 
-The agent detects your stack, presents a CRITICAL → LOW findings report, waits for confirmation, then works through each vulnerability one at a time using Red-Green-Refactor. Pass `--scan` for a report-only run with no code changes.
+100+ patterns across Node.js, Python, Go, React, React Native, Flutter, and Expo — including the AI-specific vulnerabilities that most scanners miss entirely:
 
-## Config file
+**Standard OWASP holes** — SQL/NoSQL/Command injection · Path traversal · Broken auth · XSS · IDOR · Mass assignment · SSRF · Open redirect · XXE · Insecure deserialization · Prototype pollution · Weak crypto · Hardcoded secrets · TLS bypass
 
-Scaffold a starter config with a single command:
+**AI / LLM-specific** (the ones that will actually get you hacked in 2025) — LLM prompt injection · Eval of model output · LangChain ShellTool / ExecChain · Unbounded agent loops · MCP credential leakage · GitHub Actions expression injection · Hardcoded provider keys (OpenAI, Anthropic, Gemini, Cohere, Mistral, HuggingFace) · Missing `max_tokens` · Dynamic require from user input · VM sandbox escape · Electron `nodeIntegration: true`
 
-```bash
-npx @lhi/tdd-audit init
-# or at a custom path:
-npx @lhi/tdd-audit init ~/configs/my-audit.json
-```
+**Vibecoding anti-patterns** — `localStorage` token storage · `Math.random()` for session IDs · `process.env.SECRET || "hardcoded-fallback"` · Silent exception swallowing · Insecure WebSocket URLs
+
+---
+
+## How it works
+
+The full `/tdd-audit` skill run follows Red-Green-Refactor for every finding:
+
+1. **Detect** — scans your stack, scopes patterns to what's actually relevant
+2. **Report** — presents a CRITICAL → LOW findings table with plain-language risk and effort estimate. Waits for your sign-off before touching anything
+3. **Red** — writes an exploit test that **fails** (proves the hole is real)
+4. **Green** — applies the patch (test now passes)
+5. **Refactor** — runs the full suite (zero regressions)
+6. **Harden** — security headers, rate limiting, `npm audit`, secret scan, production error handling
+7. **Coverage gate** — pushes test coverage to ≥ 95% line and branch
+8. **Badge + SECURITY.md** — updates your README badge, creates `SECURITY.md` in GitHub Security Advisory format
+
+Nothing is marked done until a test proves it.
+
+---
+
+## For PMs and security officers
+
+You need evidence, not promises. `tdd-audit` produces:
+
+- **Exploit tests** — a failing test per vulnerability, committed to source, proves the hole existed
+- **Passing tests** — the fix is proven by the test suite, not just code review
+- **`--format report`** — a markdown compliance report with findings table, fix evidence, patch commits, and coverage gate result; ready to attach to SOC 2, ISO 27001, or vendor security questionnaire
+- **`--sbom`** — CycloneDX Software Bill of Materials (required for US federal contracts under EO 14028)
+- **`SECURITY.md`** — GitHub Security Advisory format with your security contact, supported versions, and hardening summary
+- **Webhook + Slack notifications** — findings summary delivered to your security channel on every scan
 
-`.tdd-audit.json` — all CLI flags settable here, loaded automatically from your project root:
+Configure your security contact in `.tdd-audit.json`:
 
 ```json
 {
-  "provider":          "openai",
-  "model":             "gpt-4o",
-  "apiKeyEnv":         "OPENAI_API_KEY",
-  "baseUrl":           null,
-  "output":            "text",
-  "severityThreshold": "LOW",
-  "port":              3000,
-  "serverApiKey":      null,
-  "trustProxy":        false,
-  "ignore":            ["node_modules", "dist", "build", "coverage"]
+  "security_name":  "Alice Smith",
+  "security_email": "security@yourorg.com"
 }
 ```
 
-Point to a config anywhere with `--config`:
+Both fields are optional — use one, both, or neither. When set, they appear in SECURITY.md, the compliance report, and webhook payloads.
+
+---
+
+## AI Audit (`--ai`)
+
+Let the LLM explore and report on your codebase directly:
 
 ```bash
-npx @lhi/tdd-audit serve --config ~/configs/prod-audit.json
+npx @lhi/tdd-audit --ai \
+  --provider anthropic \
+  --api-key $ANTHROPIC_API_KEY \
+  --depth tier-2 \
+  --format json
 ```
 
-## REST API + AI remediation
+### Depth tiers
+
+| Tier | Mode | What you get | Billing unit |
+|---|---|---|---|
+| `tier-1` | Scan only | File, line, severity, snippet | per report |
+| `tier-2` | Scan only | + risk explanation, effort estimate, CWE, OWASP, references | per report |
+| `tier-3` | Full audit, read-only | + copy-ready patches and test snippets — you apply manually | per report |
+| `tier-4` | Full audit, writes | LLM applies every patch via `write_file` | per applied patch |
 
 ```bash
-# Start the API server (now powered by Fastify)
-npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
+# Fast scan — just the findings
+npx @lhi/tdd-audit --ai --depth tier-1 --format json
 
-# Scan any path → JSON
-curl -X POST http://localhost:3000/scan \
-  -H "Authorization: Bearer YOUR_SECRET" \
-  -d '{"path": "."}' | jq '.summary'
+# Full report with context, no changes made
+npx @lhi/tdd-audit --ai --depth tier-2 --format json
 
-# Full automated pipeline: scan + remediate in one shot
-curl -X POST http://localhost:3000/audit \
-  -H "Authorization: Bearer YOUR_SECRET" \
-  -H "Content-Type: application/json" \
-  -d '{"path": ".", "provider": "anthropic", "apiKey": "sk-ant-..."}' \
-  | jq '.jobId'
+# Copy-ready patches — apply yourself
+npx @lhi/tdd-audit --ai --depth tier-3 --format json
+
+# Let the LLM fix everything
+npx @lhi/tdd-audit --ai --depth tier-4 --allow-writes
+```
 
-# Poll job status
-curl http://localhost:3000/jobs/<jobId>
+### AI flags
 
-# Or stream real-time updates via SSE
-curl -N http://localhost:3000/jobs/<jobId>/stream
+| Flag | Description |
+|---|---|
+| `--ai` | Enable LLM agentic audit |
+| `--depth tier-1\|2\|3\|4` | Output depth tier (default: `tier-1`) |
+| `--allow-writes` | Permit the LLM to write files (auto-enabled for `tier-4`) |
+| `--provider <name>` | `anthropic` \| `openai` \| `gemini` \| `ollama` |
+| `--api-key <key>` | Provider API key |
+| `--model <name>` | Model override (e.g. `claude-opus-4-6`, `gpt-4o`) |
+| `--base-url <url>` | Any OpenAI-compatible service |
+| `--format json\|sarif\|report` | Structured output format |
+| `--verbose` | Print tool call details to stderr |
+
+---
+
+## CI integration
+
+### PR gate — block merges on new findings
+
+```yaml
+- run: npx @lhi/tdd-audit@latest --pr --threshold HIGH
+```
+
+Exits non-zero if any finding meets or exceeds the threshold. Sub-second — no AI, no agents, pure static scan. Wire into branch protection rules to stop vulnerable code from merging.
+
+### Org-wide posture scan
+
+```bash
+npx @lhi/tdd-audit@latest --org my-github-org --format report
+```
+
+Scans every repo in the org, produces a cross-org summary and a compliance report. Fires your webhook/Slack with the aggregate payload.
+
+---
+
+## Config file
+
+```bash
+npx @lhi/tdd-audit init                      # scaffold .tdd-audit.json
+npx @lhi/tdd-audit init --provider anthropic  # with Anthropic defaults
+```
+
+`.tdd-audit.json` — everything settable here, CLI flags always win:
 
-# Use any OpenAI-compatible service (Groq, OpenRouter, Together AI, etc.)
-npx @lhi/tdd-audit serve \
-  --provider openai \
-  --base-url https://api.groq.com/openai/v1 \
-  --api-key $GROQ_API_KEY \
-  --model llama-3.3-70b-versatile
+```json
+{
+  "provider":          "anthropic",
+  "model":             "claude-opus-4-6",
+  "apiKeyEnv":         "ANTHROPIC_API_KEY",
+  "severityThreshold": "HIGH",
+  "ignore":            ["node_modules", "dist", "coverage"],
+
+  "security_name":     "Alice Smith",
+  "security_email":    "security@yourorg.com",
+
+  "webhook_url":       "https://hooks.yourorg.com/security",
+  "slack_webhook":     "https://hooks.slack.com/services/...",
+  "slack_channel":     "#security-alerts",
+
+  "severity_overrides": {
+    "CORS Wildcard": "CRITICAL"
+  }
+}
 ```
 
-Supported providers: `anthropic` · `openai` · `gemini` · `ollama` (local) · **any OpenAI-compatible endpoint via `--base-url`**
+Full schema → [docs/configuration.md](docs/configuration.md)
 
-### Endpoints
+---
+
+## REST API
+
+```bash
+npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
+```
 
 | Method | Path | Auth | Description |
 |---|---|---|---|
-| `GET` | `/health` | No | Version + liveness check |
-| `POST` | `/scan` | Yes | Scan a path, return findings |
-| `POST` | `/remediate` | Yes | AI-fix a findings list; returns `jobId` |
-| `POST` | `/audit` | Yes | Full scan+remediate pipeline; returns `jobId` |
+| `GET` | `/health` | No | Liveness check |
+| `POST` | `/audit/ai` | Yes | LLM audit with depth tiers; returns `jobId` |
+| `POST` | `/scan` | Yes | Static scan; returns findings immediately |
+| `POST` | `/remediate` | Yes | AI-fix a provided findings list; returns `jobId` |
 | `GET` | `/jobs/:id` | Yes | Poll job status |
-| `GET` | `/jobs/:id/stream` | Yes | SSE stream — real-time job progress |
-
-## Output formats
+| `GET` | `/jobs/:id/stream` | Yes | SSE — stream live LLM output |
 
 ```bash
-npx @lhi/tdd-audit --scan --json          # structured JSON
-npx @lhi/tdd-audit --scan --format sarif  # GitHub code scanning (inline PR annotations)
-npx @lhi/tdd-audit --scan                 # human-readable text (default)
+# Start an AI audit
+curl -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer YOUR_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "anthropic", "apiKey": "sk-ant-...", "depth": "tier-2"}'
+
+# Stream results live
+curl -N http://localhost:3000/jobs/<jobId>/stream
 ```
 
-## Testing
+Supported providers: `anthropic` · `openai` · `gemini` · `ollama` · **any OpenAI-compatible endpoint via `--base-url`**
+
+---
 
-586 tests across unit, E2E, and security suites:
+## Testing
 
 ```bash
-npm test                  # full suite
-npm run test:unit         # unit tests with coverage (96.6% branch coverage)
+npm test                  # full suite (841 tests)
+npm run test:unit         # unit tests with coverage
 npm run test:security     # security regression tests only
 npm run test:e2e          # end-to-end REST API tests
 ```
 
-Security tests cover prompt injection, path traversal, rate limiting, timing-safe auth, job store bounds, SARIF schema, and more. See [__tests__/security/](__tests__/security/) for all 22 regression tests.
+Security tests cover: prompt injection · path traversal · SSRF via webhook and baseUrl · rate limiting · timing-safe auth · XFF bypass · job store bounds · SARIF schema · AI key redaction · coverage skip detection · and more. Every past vulnerability is a permanent regression test.
+
+---
 
 ## Documentation
 
 | | |
 |---|---|
-| [REST API](docs/rest-api.md) | Endpoints, auth, rate limiting, trust-proxy, request/response schema |
-| [AI Remediation](docs/ai-remediation.md) | Provider setup, `--base-url` for compatible APIs, config file |
-| [Scanner](docs/scanner.md) | Architecture, detection logic, false-positive handling |
-| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 57 patterns — descriptions, grep signatures, fix pointers |
+| [Configuration](docs/configuration.md) | Full schema — all fields, CLI equivalents, payload schemas |
+| [REST API](docs/rest-api.md) | Endpoints, auth, rate limiting, depth tiers, targeted apply |
+| [AI Remediation](docs/ai-remediation.md) | Provider setup, `--base-url` for compatible APIs |
+| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 100+ patterns — descriptions, grep signatures, fix pointers |
 | [TDD Protocol](docs/tdd-protocol.md) | Red-Green-Refactor in full, with framework templates for all 6 stacks |
 | [Agentic AI Security](docs/agentic-ai-security.md) | ASI01–ASI10 — prompt injection, MCP supply chain, Actions injection |
 | [Hardening](docs/hardening.md) | Phase 4 controls — Helmet, CSP, CSRF, rate limiting, gitleaks, SRI |
 | [CI/CD](docs/ci-cd.md) | Workflow templates, existing pipeline integration, secret leak prevention |
 
+---
+
 ## License
 
 MIT

package/SKILL.md

@@ -1,4 +1,8 @@
 ---
+# IMPORTANT CONSTRAINTS
+# 1. NEVER add AI attribution trailers to commits (no "Co-Authored-By: Claude ..." lines).
+# 2. NEVER add AI attribution to any file, comment, or commit message.
+# 3. All commits must appear as human-authored work only.
 name: TDD Remediation Protocol
 description: A comprehensive toolkit for applying Red-Green-Refactor to fix security vulnerabilities.
 category: security
@@ -12,6 +16,8 @@ audit_status: safe
 
 # TDD Remediation Protocol
 
+> **Non-negotiable rule:** Never add AI attribution to any commit, file, or comment. Do not append `Co-Authored-By`, `Generated by`, or any similar trailer. All commits must be plain, human-authored messages.
+
 Applying Test-Driven Development (TDD) to code that has already been generated requires Test-Driven Remediation. You must prove the security hole exists by writing a test that exploits it, apply the fix, and then prove the hole is closed.
 
 ## Autonomous Audit Mode

package/docs/ai-remediation.md

@@ -1,6 +1,31 @@
 # AI Remediation
 
-Pass a provider and API key to have tdd-audit autonomously generate exploit tests, patches, and regression checks for each finding — no agent required.
+`tdd-audit --ai` runs a fully agentic LLM audit: the model explores your codebase with tool calls, identifies vulnerabilities, and (depending on the depth tier) provides copy-ready patches or applies them directly. No agent shell required.
+
+---
+
+## Depth tiers
+
+| Tier | What you get | Writes files? | Billing unit |
+|---|---|---|---|
+| `tier-1` | Scan report: name, severity, file, line, snippet | no | per report |
+| `tier-2` | + risk, effort, CWE, OWASP category, references | no | per report |
+| `tier-3` | + copy-ready `patch` and `testSnippet` per finding | no | per report |
+| `tier-4` | LLM applies patches via `write_file`; `patchesApplied` count in envelope | yes | per applied patch |
+
+```bash
+# Fast scan report
+npx @lhi/tdd-audit --ai --depth tier-1 --format json
+
+# Rich report with CWE/OWASP — review and decide what to fix
+npx @lhi/tdd-audit --ai --depth tier-2 --format json
+
+# Patch included in every finding — copy and apply yourself
+npx @lhi/tdd-audit --ai --depth tier-3 --format json
+
+# Let the LLM write the fixes
+npx @lhi/tdd-audit --ai --depth tier-4
+```
 
 ---
 
@@ -25,13 +50,13 @@ Edit `.tdd-audit.json`:
 `apiKeyEnv` names the environment variable to read the key from — no key ever touches disk. Then just:
 
 ```bash
-npx @lhi/tdd-audit serve
+npx @lhi/tdd-audit --ai --depth tier-2 --format json
 ```
 
 Point to a config at any path:
 
 ```bash
-npx @lhi/tdd-audit serve --config ~/configs/my-audit.json
+npx @lhi/tdd-audit --ai --config ~/configs/my-audit.json --depth tier-3
 ```
 
 ---
@@ -40,15 +65,17 @@ npx @lhi/tdd-audit serve --config ~/configs/my-audit.json
 
 ```bash
 # Anthropic
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider anthropic \
-  --api-key $ANTHROPIC_API_KEY
+  --api-key $ANTHROPIC_API_KEY \
+  --depth tier-2
 
 # OpenAI
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --api-key $OPENAI_API_KEY \
-  --model gpt-4o-mini
+  --model gpt-4o-mini \
+  --depth tier-1
 ```
 
 ---
@@ -60,28 +87,28 @@ The API key is sent in the `Authorization: Bearer` header — never in the URL.
 
 ```bash
 # Groq (fast inference)
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url https://api.groq.com/openai/v1 \
   --model llama-3.3-70b-versatile \
   --api-key $GROQ_API_KEY
 
 # OpenRouter (access 200+ models)
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url https://openrouter.ai/api/v1 \
   --model meta-llama/llama-3.3-70b-instruct \
   --api-key $OPENROUTER_API_KEY
 
 # Together AI
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url https://api.together.xyz/v1 \
   --model mistralai/Mixtral-8x7B-Instruct-v0.1 \
   --api-key $TOGETHER_API_KEY
 
 # LM Studio / vLLM / llama.cpp (fully local)
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider openai \
   --base-url http://localhost:1234/v1 \
   --model local-model
@@ -116,53 +143,95 @@ In `.tdd-audit.json`:
 ## REST API usage
 
 ```bash
-# 1. Scan and get findings
-FINDINGS=$(curl -s -X POST http://localhost:3000/scan \
-  -H "Authorization: Bearer $SERVER_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"path": "."}' | jq '.findings')
+# Start the server
+npx @lhi/tdd-audit serve --port 3000 --api-key $SERVER_KEY
 
-# 2. Submit remediation job (using Groq via --base-url)
-JOB=$(curl -s -X POST http://localhost:3000/remediate \
+# Launch a tier-2 audit job
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
   -H "Authorization: Bearer $SERVER_KEY" \
   -H "Content-Type: application/json" \
   -d "{
-    \"findings\": $FINDINGS,
     \"provider\": \"openai\",
-    \"apiKey\": \"$GROQ_API_KEY\",
-    \"baseUrl\": \"https://api.groq.com/openai/v1\",
-    \"model\": \"llama-3.3-70b-versatile\",
-    \"severity\": \"HIGH\"
-  }")
+    \"apiKey\":   \"$GROQ_API_KEY\",
+    \"baseUrl\":  \"https://api.groq.com/openai/v1\",
+    \"model\":    \"llama-3.3-70b-versatile\",
+    \"depth\":    \"tier-2\"
+  }" | jq -r '.jobId')
+
+# Poll until done
+while true; do
+  STATUS=$(curl -s http://localhost:3000/jobs/$JOB \
+    -H "Authorization: Bearer $SERVER_KEY" | jq -r '.status')
+  [ "$STATUS" = "done" ] || [ "$STATUS" = "error" ] && break
+  sleep 3
+done
+
+# Print summary
+curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer $SERVER_KEY" | jq '.result.summary'
+```
+
+### Targeted apply (tier-4)
 
-JOB_ID=$(echo $JOB | jq -r '.jobId')
+Take a single finding from a tier-3 report and apply its patch without re-scanning:
+
+```bash
+# Get the first finding from a previous tier-3 job
+FINDING=$(curl -s http://localhost:3000/jobs/$TIER3_JOB_ID \
+  -H "Authorization: Bearer $SERVER_KEY" \
+  | jq '.result.findings[0]')
 
-# 3. Poll for results
-curl -s "http://localhost:3000/jobs/$JOB_ID" \
-  -H "Authorization: Bearer $SERVER_KEY" | jq '.status'
+# Apply only that patch
+curl -s -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer $SERVER_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"provider\": \"anthropic\",
+    \"apiKey\":   \"$ANTHROPIC_API_KEY\",
+    \"depth\":    \"tier-4\",
+    \"findings\": [$FINDING]
+  }" | jq '.jobId'
 ```
 
+See [REST API](rest-api.md) for the full endpoint reference.
+
 ---
 
-## What the model returns
+## Output envelope
 
-For each finding the remediator sends a structured prompt and expects back:
+All structured output (`--format json` or via REST API) returns the same envelope shape regardless of tier:
 
 ```json
 {
-  "exploitTest": {
-    "filename": "__tests__/security/xss-comments.test.js",
-    "content": "..."
-  },
-  "patch": {
-    "filename": "src/routes/comments.js",
-    "diff": "--- a/src/routes/comments.js\n+++ ..."
-  },
-  "refactorChecks": ["npm test", "npm run test:security"]
+  "version":             "1.17.0",
+  "provider":            "anthropic",
+  "model":               "claude-opus-4-6",
+  "depth":               "tier-3",
+  "mode":                "full",
+  "stack":               "Node.js / Express",
+  "summary":             { "CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 0 },
+  "patchesApplied":      0,
+  "findings": [
+    {
+      "name":        "SQL Injection",
+      "severity":    "HIGH",
+      "file":        "src/db.js",
+      "line":        42,
+      "snippet":     "db.query(userInput)",
+      "risk":        "Full database read/write via UNION injection",
+      "effort":      "low",
+      "cwe":         "CWE-89",
+      "patch":       "const stmt = db.prepare('SELECT ...');\nstmt.run(id);",
+      "testSnippet": "test('prevents injection', () => { ... });"
+    }
+  ],
+  "likelyFalsePositives": [],
+  "remediation":          [],
+  "scannedAt":            "2026-03-26T12:00:00.000Z"
 }
 ```
 
-The result is returned as-is from the API — review and apply patches manually or pipe into your own automation.
+`patchesApplied` is always `0` for tiers 1–3 (no files written). For tier-4 it counts `remediation` entries where `status === "fixed"` — the billable unit.
 
 ---
 
@@ -174,9 +243,12 @@ ollama pull codellama
 ollama serve
 
 # Run tdd-audit against it
-npx @lhi/tdd-audit serve \
+npx @lhi/tdd-audit --ai \
   --provider ollama \
-  --model codellama
+  --model codellama \
+  --depth tier-1
 ```
 
 No API key required. Ollama must be running on `http://localhost:11434`.
+
+Ollama does not support the tool-use API, so the audit runs in single-shot mode: the project files are bundled into the prompt rather than explored interactively with tool calls. For best results, use `tier-1` or `tier-2` with Ollama.