diff --git a/docs/RETRO_V4.md b/docs/RETRO_V4.md
new file mode 100644
index 0000000..94353a8
--- /dev/null
+++ b/docs/RETRO_V4.md
@@ -0,0 +1,97 @@
+# PROCITY v4 — THE REAL MAP: the epoch retro
+
+*Fable (integrator), 2026-07-16, written after the `v4.0` tag (`8ac3b18`) per ROUND22 ledger #6.
+Epoch span: the R17 scout → R22 close (charter: [V4_REAL_MAP.md](V4_REAL_MAP.md)). Tags:
+`v4.0-alpha` → `v4.0-beta` → `v4.0`.*
+
+## The epoch in numbers
+
+**23 real Australian towns · 1,210 real shops (298 secondhand heroes) · all 8 states and
+territories · on their actual streets.** Selfcheck grew 15,277 → **161,300** checks. 36 town
+goldens pinned in one commit. Every real graph lands as **1 connected component** with 3 venues.
+The covenant was never broken: `?classic=1` boots the exact v2 town, `0x3fa36874`, byte-identical
+through six rounds of the largest structural change in the project's history. The default
+synthetic town is untouched. One sanctioned golden move per round, every one recorded.
+
+## What shipped, in one breath
+
+Cache schema v2 → the real-graph lift (junction-protected Douglas–Peucker, cull/bridge
+connectivity) → the density widening under John's SUBTLE directive (heroes never subsampled,
+texture capped at 3×, and D proved the heroes *gained* footfall) → cluster-adjacent venues (11/15
+were stranded; 0/15 after) → the tram's shop-adjacency ruling with per-town fencing → the town
+selector → the poster cap → the furniture tri diet → the five-frame release tour, including one
+honestly-dead town. Plus the marriage: **Lane G** (ultra) joined mid-epoch, merged at a round
+boundary, with the depot format ruled (no-Draco) and the G2a atlas contract reviewed.
+
+## What worked — keep doing these
+
+1. **Measurement over brief.** The epoch's defining pattern. A proved my poster "nudge" was
+   geometrically impossible and fixed the root cause. D refuted my prescribed `_rotWithHips`
+   with an in-shell proof. B tested a five-round-old park reason and found it was folklore.
+   D published a self-correction of its own headline metric. F recorded a re-measure that got
+   *worse*, and refused to caption a dead town as proof the floor holds. The brief is a
+   hypothesis; the lane's measurement is the ruling.
+2. **The measure-first fix loop.** R22's blocking gate ran F measured → B diagnosed (91.5%
+   attribution by hide-a-layer) → A confirmed not-A with numbers → E owned it and fixed (−51%)
+   → F re-measured. Four lanes, one gate, zero ego, one round.
+3. **Alpha as failure-list.** R18's brief said the deliverable was the failure list, and it was:
+   fragmentation (105 components), the BIG_CITY misfire, the DP junction-drop — each surfaced by
+   audit, filed with measurements, fixed the next round. Budget the discovery round; don't ask
+   it to also be the fix round.
+4. **Contract-first beats sequencing.** R16's order inverted (lanes ran before F's flip) and
+   nothing broke, because contracts were published in the brief. Same for schema v2, C's mapping
+   table, the backline shape, the G2a atlas contract. The half-day-handshake rule is the
+   project's real synchronization primitive.
+5. **Drops are counted, never silent.** `norm.dropped` by cause, `textureDropped`, fenced towns
+   named, the 6.4% seating tail per-cause-attributed. Nothing in the pack pretends.
+6. **Independent convergence.** The thin-tail finding was discovered twice in one round by
+   different methods (F's tour frame; D's nearest-neighbour spacing metric) — that's the
+   redundancy of honest lanes, and it's why the finding is trustworthy.
+
+## What cost us — fix these
+
+1. **Lane F is the fragile point.** F no-showed R14 and R18, and stalled mid-gate in R21. Every
+   time, the epoch sat untagged with five lanes done. The close is the longest, most serial
+   brief and it runs last, when sessions die. *Mitigation adopted going forward: F's brief is
+   written in resumable numbered items (R21 proved a successor can pick up mid-gate), and the
+   integrator checks for uncommitted F WIP before declaring a round done.*
+2. **Soft ceilings invite drift.** `venue_night` breached the 200k "soft" reference twice
+   (+0.5%, then +11%) before R22 made it blocking. *Rule going forward: a stress view that
+   breaches twice is automatically a blocking gate the next round.*
+3. **Old assets bite in new contexts.** The tri-diet driver was four furniture GLBs sized in
+   R6 for a 22-edge synthetic town, harmless for sixteen rounds until a 966-edge real graph
+   multiplied their cadence. *When the context scales, re-audit the assets it multiplies.*
+4. **The integrator was wrong twice** (the nudge, `_rotWithHips`). Acceptable — that's what
+   measurement-over-brief is for — but both were cases of prescribing the mechanism instead of
+   the outcome. *Briefs should state acceptance; lanes own method.*
+
+## The v4.x ledger (carried, measured, not hidden)
+
+- **The thin-tail clustering floor** (the epoch's parting finding): aliveness is not shop
+  *count* but **clustering** — median nearest-neighbour spacing (darwin 27 m ALIVE vs toowoomba
+  388 m DEAD at the same 12 shops). Candidate law: E curates on spacing, `validateTownCache`
+  warns above a threshold; toowoomba gets re-bboxed or retired.
+- The **6.4% seating tail** (daylesford 19%, fitzroy 13%) — known, per-cause, the drop-and-count
+  ruling stands.
+- `GIG_RANGE` chunk-neighbour lookup (D, 8.7% blind) · instrument `_lo` LOD · tram-stop close-ped
+  tri diet · drummer pelvic-lean v2 · awning fabric ripple · flag retirement (classic keeps
+  soaking) · selector polish beyond debug-grade.
+
+## The next epoch — Fable's recommendation to John
+
+Three chartered candidates remain: **the GODVERSE economy (G2/G3)**, **the editor/override
+layer**, **multiplayer presence**.
+
+**Recommendation: v5 = THE REAL SHOP — the GODVERSE economy.** The argument: v4 made the towns
+real; v5 makes the *shops* real. The marriage lane is already live (G2a contract reviewed, first
+atlases next), dealgod holds 1.77M real items with photos, and the destination — walk Fitzroy's
+real street into a real op shop, riffle a real crate, and the record you buy is one-of-a-kind
+because it's real stock (sold means GONE) — is the most PROCITY-shaped thing either studio can
+build. Sequence per the standing ruling: **G3 design doc first** (both integrators + John;
+the server enriches, never gates — full offline play is non-negotiable), G2a atlases land
+meanwhile, v4.x tail runs as a light parallel lane. The editor and multiplayer stay chartered
+for v6+ — the editor gets stronger the more real content exists to override, and presence gets
+stronger the more there is to visit.
+
+*— Fable. Twenty-two rounds: seed → town → weather → crowd → interiors → stock → gigs → the flip
+→ real roads → real shops → real Australia. The covenant held the whole way.*