Docs have no assigned roles: 12 markdown files overlap; pyproject claims MHE that does not exist; synthetic_day.py names the removed ems_tracking_mpc

[dim-sous]

What is wrong

Twelve markdown files, none with one job:

• README.md (8.5 KB), CLAUDE.md (6.4 KB), backlog.md (4.3 KB) — the repo layout is described in all three; the strategy ladder in at least two.
• Five strategies/*/README.md, four archive/**/README.md.
• No docs/ directory. No single document a returning developer — or an outsider — reads first.

And drift, small but the compounding kind (every stale claim makes every other claim cost a verification step):

• pyproject.toml:4 describes the platform as "stochastic EMS + tracking MPC + EKF/MHE". There is no MHE; core/estimators/ holds ekf.py only. The tracking-MPC strategy was removed in 9edfe77 (the class survives only as EconomicMPC's solver-failure fallback, core/mpc/economic.py:80).
• core/simulator/synthetic_day.py:9,27 still lists ems_tracking_mpc in the documented strategy ladder.
• core/mpc/adapters.py:65 TrackingMPCAdapter has no importer anywhere in the repo.
• backlog.md says "the source code wins" — which is honest, and also the admission that the doc is not trusted.

The clutter the developer feels is not file count. It is that no file has one job, so every question means opening several.

What it should be

• docs/ with Diátaxis roles: how-to (run, add a strategy), reference (config fields — generated from run_simulation takes 15 positional parameters and 9 config dataclasses from one file, with no runtime schema — every caller is welded to the core's shape #5, not hand-kept), explanation (the physics choices, why v5 is shaped as it is), plus findings-log.md and, when there are incidents, failures.md.
• CLAUDE.md becomes an index: one line per rule, each pointing at the test, incident or runbook that holds it (RCWS's shape, ~140 lines).
• backlog.md retired: its two open empirical questions become research issues; its future-work list moves to a roadmap issue; the file points at the tracker.
• README is the fast read for an outsider: what this is, findings and limitations up front, how to run one thing.
• Drift fixed: pyproject description, synthetic_day.py docstring, the orphaned adapter removed or its consumer named.

Done when

• Every markdown file states its role in its first line and does not restate another's content.
• No doc claims a capability the code does not have (spot-checked against the inventory from An experiment has no name: three runner scripts are the interface; no [project.scripts], no list #7).
• backlog.md is gone or a pointer.

Alongside the platform epic; blocks nothing, but should land before phase 3 so the CLI's list and the docs say the same thing.