diff --git a/README.md b/README.md
index f2431cd..e957151 100644
--- a/README.md
+++ b/README.md
@@ -170,3 +170,38 @@ GET  /abilities
 GET  /capabilities
 GET  /search?q=...
 ```
+
+## Agent API Loop
+
+Agents can use the API as a conservative inspect-and-curate loop:
+
+1. Register or find a repository with `POST /repos` or `GET /repos`.
+2. Run analysis with `POST /repos/{id}/analysis-runs`.
+3. Inspect observed facts, content chunks, and the candidate graph:
+
+```bash
+curl http://127.0.0.1:8000/repos/1/observed-facts
+curl http://127.0.0.1:8000/repos/1/content-chunks
+curl http://127.0.0.1:8000/repos/1/analysis-runs/1/candidate-graph
+```
+
+4. Correct candidate claims with review endpoints when needed, then approve:
+
+```bash
+curl -X POST http://127.0.0.1:8000/repos/1/analysis-runs/1/candidate-graph/approve \
+  -H 'content-type: application/json' \
+  -d '{"notes":"Approved after source-linked review"}'
+```
+
+5. Search and inspect only approved registry truth:
+
+```bash
+curl 'http://127.0.0.1:8000/search?q=classify%20email&status=indexed'
+curl http://127.0.0.1:8000/repos/1/ability-map
+```
+
+Search results include `match_type`, `matched_field`, `confidence`,
+`confidence_label`, ability/capability identifiers where available, and
+source/evidence context when the match comes from implementation evidence.
+The generated OpenAPI schema at `/openapi.json` and docs at `/docs` include
+typed response schemas and examples for the main agent-facing responses.