diff --git a/README.md b/README.md
index 5e6aaea..97e7299 100644
--- a/README.md
+++ b/README.md
@@ -823,7 +823,37 @@ Non‑blocking observations such as:
 
 ---
 
-## 8. Platform Support
+## 8. Using witr with AI Agents
+
+AI coding agents (Claude Code, Codex, Cursor, etc.) constantly hit port-in-use
+errors, zombie servers, and container confusion during local development.
+Instead of chaining `lsof` / `ps` / `netstat` / `docker ps` manually, point the
+agent at witr — the causal chain, source and warnings come back in one call.
+
+`--json` is the machine-output flag: a single structured line the agent can
+parse directly. Exit codes are already scriptable (see [7.2 Exit Codes](#72-exit-codes)).
+
+### AGENTS.md / CLAUDE.md snippet
+
+Add this to your project's agent instructions:
+
+```markdown
+Process/port debugging: use witr before manual lsof/ps/netstat chains.
+- Port conflict:   witr --port <PORT> --json
+- Stuck process:   witr <name> --json   or   witr --pid <PID> --tree
+- Container issue: witr --container <name> --verbose --json
+```
+
+The output is structured for machine consumption: `--json` emits one line with
+the full process tree (pid, parent, command, user), the resolved cause, and any
+warnings (running as root, public interface, deleted binary, container
+mismatch). Non-zero exit codes signal the outcome — 2 for "no match found", so
+an agent can branch on empty-vs-found without parsing prose. Run `witr --help`
+for the complete flag list.
+
+---
+
+## 9. Platform Support
 
 - **Linux** (x86_64, arm64) - Full feature support (`/proc`).
 - **macOS** (x86_64, arm64) - Uses `ps`, `lsof`, `sysctl`, `pgrep`.
@@ -832,7 +862,7 @@ Non‑blocking observations such as:
 
 ---
 
-### 8.1 Feature Compatibility Matrix
+### 9.1 Feature Compatibility Matrix
 
 | Feature | Linux | macOS | Windows | FreeBSD | Notes |
 |---------|:-----:|:-----:|:-------:|:-------:|-------|
@@ -918,7 +948,7 @@ On Windows, witr talks directly to Win32 APIs (ToolHelp32, PSAPI, Service Contro
 
 ---
 
-## 9. Success Criteria
+## 10. Success Criteria
 
 witr is successful if:
 
@@ -929,7 +959,7 @@ witr is successful if:
 
 ---
 
-## 10. Sponsors
+## 11. Sponsors
 
 Special thanks to the people who supported **witr** ❤️