diff --git a/AGENTS.md b/AGENTS.md
index fe7356e..1f1e172 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -92,6 +92,25 @@ numbers, which is exactly what "works in my headless run" cannot tell you.
 Extend it when the next geometry puzzle appears; the endpoint takes whatever
 fields `SnapReport` declares.
 
+## Keep the two documents current
+
+This is a running system under continual change, not a build being executed, so
+both live documents decay unless updating them is part of finishing the work —
+not a tidy-up afterwards.
+
+- **`docs/plan.md`** — when a decision changes, change it here. A plan that
+  contradicts the code is worse than no plan, because someone believes it. If
+  you find a section describing behaviour that no longer exists, that is a bug
+  in the document; fix it in the same commit that revealed it.
+- **`docs/implementation.md`** — append when a fix was not obvious. The bar is
+  "would this have saved me an hour": wrong theories that were measured and
+  killed, the evidence that settled it, the thing that looked like one bug and
+  was another. Not every fix. A log of trivia stops being read, and then the
+  useful entries go unread too.
+
+Rule of thumb: if you needed a measurement to be sure, write down what it was.
+Git records what changed; these record why it was hard.
+
 ## Direction of travel
 
 Two live planning documents, both written to be refactored toward rather than
diff --git a/README.md b/README.md
index 7455a4e..bd2161e 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,11 @@ rediscover. What it cost to get there is in
 [`docs/implementation.md`](docs/implementation.md): a dated log of problems and
 their resolutions, kept as a learning record alongside git.
 
+Both are living documents. The app is past the point of being built and into
+being maintained, so a change that makes either one wrong is not finished —
+correcting the plan, or logging what was hard, is part of the work rather than
+housekeeping after it.
+
 ## Local development
 
 ```bash
diff --git a/docs/plan.md b/docs/plan.md
index f011119..acb8640 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -1,7 +1,12 @@
 # /ES Multi-Timeframe Confluence Chart — Implementation Plan
 
-**Audience:** the implementing agent. This document is the spec; it is written to be
-executed top-to-bottom without re-deriving decisions.
+**Audience:** whoever is changing this next. It was written as a spec to execute
+top-to-bottom; it is now a reference for a running system. Read the section that
+covers what you are touching, not the whole thing.
+
+**This is a living document.** When a decision here stops being true, change it
+here — a plan that disagrees with the code is worse than no plan, because it is
+believed. What went wrong on the way belongs in `docs/implementation.md`.
 
 **One-line goal:** stream `/ES` 1-minute bars from Schwab, aggregate them into every
 larger timeframe locally, derive trendlines and moving averages on each timeframe,
@@ -1066,6 +1071,13 @@ Add `pytest` to a `requirements-dev.txt`.
 
 ## 13. Milestones
 
+> **All of M0–M10 are built and deployed.** This section is kept as a record of
+> what each subsystem was required to do, not as a queue. The "Done when"
+> criteria still earn their place: they describe correct behaviour, and several
+> have since become tests. Treat them as the specification of a working
+> subsystem — and if one no longer matches reality, the code changed and this
+> did not, which is a bug in this document.
+
 Ordered so the user's stated priority — **live realtime charts first** — lands
 earliest, and so nothing later is blocked on market hours.