diff --git a/.gitignore b/.gitignore
index 63061bd..7b5e68e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,6 @@ report/
 deploy/*.env
 # private TLS keys and certificates
 deploy/tls/
+# design/planning documents kept locally, not tracked
+docs/SPECIFICATION.md
+docs/implementation/
diff --git a/README.md b/README.md
index 6d14075..5cada85 100644
--- a/README.md
+++ b/README.md
@@ -3,10 +3,10 @@
 A minimalist web UI that researches a Confluence Data Center instance with a
 [pi](https://github.com/earendil-works/pi) agent running in a fresh, network-less
 rootless Docker container per query, and returns a cited Markdown answer plus
-optional files the agent produced. The design is in
-[docs/SPECIFICATION.md](docs/SPECIFICATION.md); the wire contracts in
-[docs/implementation/CONTRACTS.md](docs/implementation/CONTRACTS.md); the
-integration results in [docs/INTEGRATION_REPORT.md](docs/INTEGRATION_REPORT.md).
+optional files the agent produced. The integration results are in
+[docs/INTEGRATION_REPORT.md](docs/INTEGRATION_REPORT.md); each component
+documents its own interface in `agent/README.md`, `backend/README.md` and
+`frontend/README.md`.
 
 The repository also contains the original standalone
 [Confluence crawler](#standalone-crawler), which is unchanged.