docs(readme): "Teach your AI agent what not to do" lead, adoption routes, FAQ (RW-3)

[jothimani-rajendran]

README wave item RW-3 (context-report half). README.md only. Merge after chock RW-1 (cover and adopt.png are chock's raw PNG URLs).

Facts table

Number	Value	Source
Plugins sampled / unreachable	18 / 3 (exit 126)	paper/context-report.md rows ~283-285
Latency p50	916.8-941.5 ms (npx), 7.3-53.9 ms (local)	paper table, ~281-282; produced 2026-09-06, n=20, four-CPU Linux (paper line 226)
Context weight	~1,500 to 147,000 tokens	paper line 294
Efficacy	168 recorded transcripts, interval about +/-0.49	paper lines 317, 335
Catalog	71 policies: 35 / 11 / 25	chock-catalog registry.yaml at 9a64623

Claims checked against code

• Producer makes no model/network call: grep -rln "urllib\|anthropic\|http.client\|socket\|requests" src/context_report/produce empty at 3a1c0c3; only efficacy/ and run/ use them.
• Python >=3.10, deps from pyproject.toml; predicate type from src/context_report/rows.py.
• Engine commands as in the agentseam PR (chock 992711a).
• Quickstart block unchanged: tools/quickstart_block.py README.md equals docs/quickstart.sh body.

Outline

Before: The problem, 30-second quickstart, What a report looks like, Three measurements, Who it's for, Two models, Use as a library, Supported agents, Contributing, Part of open-coder-ai, License.
After: Application security for the code your agents write, Install, 30-second quickstart, How it works (Two models, Use as a library), What it stops (Three measurements, Who it's for), Supported agents, FAQ for people and agents, For tools and agents, Contributing, Part of open-coder-ai, License.

Checks

pytest tests/test_quickstart_block.py: 5 passed. ruff check ., ruff format --check .: clean. Figure scripts rerun (cd docs/figures && python make_*.py): git status shows only README.md changed. Self-check grep (pip install chock, free forever, never leaves, would have prevented, [stars], rtk, hallucinat, 100%): 0 hits.

Notes

family-*.svg is stale (39 policies, "four plugin repositories") but its generator docs/figures/make_family.py hard-codes both, so regenerating cannot fix it; the README no longer embeds it and uses a text table. The script is byte-shared across four repos, so the fix belongs in a separate item.

🤖 Generated with Claude Code

---

Generated by Claude Code