From a89048f6c59ae3f37c7d0d2a4ac896abf7f0799e Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Thu, 21 May 2026 23:17:51 +0200
Subject: [PATCH] docs(ui): finalize MVP plan structure and de-archaeologize
 topic docs

MVP web client (Phases 1-30) is complete; reorganize planning + living docs around that.

- PLAN.md kept as the staged MVP record (1-30) with a status block + pointers; removed the 31-36 stages, regression scenarios, and deferred-TODO section (moved out); fixed a stale cross-machine plan path.

- ui/PLAN-finalize.md (new): active web-finalization plan in 8 stages (visual system, a11y, i18n, error UX, PWA, build hygiene, docs, owner manual-QA loop); absorbs former Phases 33 and 35.

- ui/ROADMAP.md (new): post-MVP (Wails, Capacitor, realistic projection, acceptance + regression scenarios) and triaged deferred follow-ups.

- ui/docs/README.md (new): grouped topic-doc index.

- De-archaeologized all 20 ui/docs topic docs + ui/README.md + ui/core/README.md: stripped Phase-N build history, rewritten as current-state; deferred work now points at ROADMAP.md / PLAN-finalize.md. Docs-only; no code change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ui/PLAN-finalize.md            | 130 +++++++++++
 ui/PLAN.md                     | 396 ++-------------------------------
 ui/README.md                   |  94 ++++----
 ui/ROADMAP.md                  | 156 +++++++++++++
 ui/core/README.md              |  47 ++--
 ui/docs/README.md              |  60 +++++
 ui/docs/auth-flow.md           |  33 ++-
 ui/docs/battle-viewer-ux.md    |  14 +-
 ui/docs/calc-bridge.md         | 132 +++++------
 ui/docs/calculator-ux.md       |   8 +-
 ui/docs/cargo-routes-ux.md     |  31 ++-
 ui/docs/diplomail-ui.md        |  16 +-
 ui/docs/events.md              |  14 +-
 ui/docs/game-state.md          | 108 +++++----
 ui/docs/i18n.md                |  24 +-
 ui/docs/lobby.md               |  34 ++-
 ui/docs/navigation.md          | 121 +++++-----
 ui/docs/order-composer.md      | 144 ++++++------
 ui/docs/renderer.md            |  45 ++--
 ui/docs/report-view.md         |  12 +-
 ui/docs/science-designer-ux.md |  18 +-
 ui/docs/ship-group-actions.md  |  30 ++-
 ui/docs/storage.md             |  57 ++---
 ui/docs/sync-protocol.md       |  14 +-
 ui/docs/testing.md             |  19 +-
 ui/docs/wasm-toolchain.md      |   8 +-
 26 files changed, 836 insertions(+), 929 deletions(-)
 create mode 100644 ui/PLAN-finalize.md
 create mode 100644 ui/ROADMAP.md
 create mode 100644 ui/docs/README.md

diff --git a/ui/PLAN-finalize.md b/ui/PLAN-finalize.md
new file mode 100644
index 0000000..c40f2bc
--- /dev/null
+++ b/ui/PLAN-finalize.md
@@ -0,0 +1,130 @@
+# UI Client — Finalization Plan
+
+The MVP web client (Phases 1–30, [PLAN.md](PLAN.md)) is functionally
+complete. This plan finalizes the **web** experience — visual
+consistency, accessibility, localisation, error UX, installability, and
+documentation — before the native platform wrappers in
+[ROADMAP.md](ROADMAP.md). It absorbs the original Phases 33 (PWA) and 35
+(Polish), which were pulled forward to here.
+
+**This is a finalization pass, not the final word.** After it ships, the
+owner exercises the whole UI by hand and brings small-nuance fixes; the
+last stage (F8) is an explicit, open-ended owner-driven refinement loop.
+The earlier stages are "done" when their acceptance holds; the feature
+set is "final" only when the owner signs off.
+
+Each stage ends with a runnable, reviewable artifact and is gated on the
+per-stage CI rule (push, watch `go-unit` / `ui-test` to green) before
+being marked done.
+
+---
+
+## F1 — Visual design system
+
+Goal: replace the ad-hoc per-component styling (inline hex colors like
+`#0a0e1a`, one-off spacing) with a shared design language so every view
+looks like one product.
+
+- `ui/frontend/src/lib/theme/` (or `app.css` `:root`) design tokens:
+  color palette (surface / border / text / accent / danger), spacing
+  scale, radii, typography, focus-ring style — as CSS custom properties.
+- Migrate components to the tokens (calculator, inspectors, sidebar,
+  tables, lobby, auth) — replace literal hex/px with `var(--…)`.
+- Topic doc `ui/docs/design-system.md` documenting the tokens and usage.
+
+Acceptance: no literal theme colors left in component `<style>` blocks
+(spot-checked); a single token change restyles the app coherently.
+Consider the `frontend-design` skill for the palette/spacing pass.
+
+## F2 — Accessibility (WCAG 2.2 AA)
+
+(From Phase 35.) Goal: the whole client is usable by keyboard and
+assistive tech.
+
+- Keyboard-only paths for login, lobby, and the in-game shell; visible
+  focus rings (from the F1 token); ARIA labels/roles; screen-reader-only
+  text where needed.
+- `ui/docs/a11y.md` audit results.
+
+Acceptance: WCAG 2.2 AA on lobby, login, and the in-game shell per an
+axe-core scan; full keyboard reachability with visible focus.
+Tests: axe-core integration tests on every top-level view; Playwright
+keyboard-only navigation.
+
+## F3 — Localisation completeness
+
+(From Phase 35.) Goal: every visible string is translated (en + ru).
+
+- Audit all components for hard-coded strings; move them into the i18n
+  bundles; missing-key detection test; locale-switch persistence across
+  reloads.
+
+Acceptance: no untranslated visible strings; missing-translation test is
+green; locale persists. Tests: Vitest i18n bundle-structure +
+missing-key detection.
+
+## F4 — Error & state UX
+
+(From Phase 35, plus the deferred Phase 13/35 items.) Goal: consistent,
+actionable feedback everywhere.
+
+- `ui/frontend/src/lib/error/` central error surface with stable codes
+  and retry/escalation guidance; every server-side error mapped to a
+  translated, actionable message (en/ru).
+- Consistent empty / loading / error states across views.
+- Selected-planet visual on the map (ring/halo) off the `SelectionStore`
+  (deferred from Phase 35).
+- Mobile bottom-sheet swipe-down + tap-outside dismissal (deferred from
+  Phase 13/35).
+
+Acceptance: every server error → a translated actionable message;
+consistent empty/loading/error states; the selected planet is visually
+marked.
+
+## F5 — PWA (was Phase 33)
+
+Goal: the web build is installable and offline-tolerant. Depends on F6
+(wasm in CI) so the service worker caches a freshly-built artefact.
+
+- `ui/frontend/src/service-worker.ts` cache-first assets with
+  stale-invalidation on app update; `manifest.webmanifest`;
+  `ui/frontend/static/icons/` web icon set; `ui/docs/pwa-strategy.md`.
+
+Acceptance: installs as a PWA on Chrome, Edge, and iOS Safari; the SW
+survives an app update without serving stale code. Tests: Lighthouse PWA
+≥ 90; Playwright install→offline→cached-login; version-bump invalidation.
+
+## F6 — Build hygiene: build core.wasm in CI
+
+(From the PLAN.md TODO; timely — the binary is currently committed and
+must be rebuilt by hand on every Go-bridge change, which has already
+bitten us.) Goal: stop shipping the binary in git.
+
+- Install TinyGo on the gitea Actions runner (Linux tarball /
+  `curl … | tar -xz`, since `brew` is macOS-only); add `make -C ui wasm`
+  ahead of the Vitest step in `.gitea/workflows/ui-test.yaml`.
+- Remove `ui/frontend/static/core.wasm` and `wasm_exec.js` from the repo
+  and re-tighten `ui/.gitignore`.
+
+Acceptance: CI builds the wasm and Vitest/Playwright pass against the
+freshly built artefact; the binaries are no longer tracked.
+
+## F7 — Documentation finalization
+
+Goal: living docs read as current state, not build archaeology.
+
+- De-archaeologize the 20 `ui/docs/` topic docs: strip "Phase N adds…"
+  history, rewrite as present-tense descriptions of how things work.
+- `ui/docs/README.md` index (added during this reorganization).
+- Sync `ui/README.md`, `docs/ARCHITECTURE.md`, and `docs/FUNCTIONAL.md`
+  (+ `_ru` mirror) with the finalized UI.
+
+Acceptance: no stray "Phase N" references in `ui/docs/`; the index links
+every topic doc; READMEs/ARCHITECTURE describe current state.
+
+## F8 — Owner manual-QA refinement loop
+
+Open-ended, owner-driven. The owner exercises the whole UI by hand and
+files small-nuance fixes; each is folded in as it surfaces. There is no
+fixed acceptance gate here — finalization is "done" when the owner signs
+off and the client moves on to the ROADMAP platform wrappers.
diff --git a/ui/PLAN.md b/ui/PLAN.md
index 0d975f3..c77fb37 100644
--- a/ui/PLAN.md
+++ b/ui/PLAN.md
@@ -10,11 +10,18 @@ libraries (iOS/Android), and embedded directly in Wails (desktop). All
 network I/O lives on the TypeScript side via ConnectRPC, so the Go
 module is a pure compute boundary on every platform.
 
+> **Status — MVP complete.** Phases 1–30 below (the full web client) are
+> done. Remaining work is tracked outside this file: the active web
+> finalization pass (visual system, accessibility, localisation, error
+> UX, PWA, docs) in [PLAN-finalize.md](PLAN-finalize.md), and the
+> deferred platform wrappers (Wails desktop, Capacitor mobile), the
+> realistic multi-turn projection, and the cross-platform acceptance
+> pass in [ROADMAP.md](ROADMAP.md). This file is retained as the staged
+> record of how the MVP was built.
+
 The existing Fyne client in `client/` is deprecated and is not modified
-or imported by the new code. The strategy and rationale behind these
-choices live in the plan file at
-`/Users/id/.claude/plans/buzzing-questing-fountain.md`; the architectural
-overview is mirrored into `ui/README.md` as part of Phase 1.
+or imported by the new code. The architectural overview is mirrored into
+`ui/README.md`.
 
 Each phase ends with a runnable artifact. The visual progression is:
 empty page → navigation skeleton → stubbed views → live data → real
@@ -26,7 +33,9 @@ plan can be adjusted with at most one phase of rework.
 
 ## Summary
 
-This plan breaks implementation into 36 small reviewable phases. Each
+This plan staged the MVP web client as 30 small reviewable phases (1–30,
+all complete; the finalization pass and post-MVP work live in
+[PLAN-finalize.md](PLAN-finalize.md) and [ROADMAP.md](ROADMAP.md)). Each
 phase has a single primary goal, clear deliverables, explicit
 dependencies, acceptance criteria, and focused tests. Tests live
 alongside the code added in the phase; a phase is not closed until its
@@ -3408,380 +3417,3 @@ Note: the WASM artefact `ui/frontend/static/core.wasm` must be rebuilt
 (`make wasm`, needs TinyGo) for the new bridge functions to be present
 at runtime and in the Playwright suite; Vitest injects a fake `Core`
 and does not need the rebuild.
-
-## Phase 31. Wails Desktop Wrapper
-
-Status: pending. Re-evaluate Wails v2 vs v3 at phase start.
-
-Goal: build a native desktop app for macOS, Windows, and Linux that
-runs the same frontend bundle and replaces the WASM core with embedded
-Go code.
-
-Artifacts:
-
-- topic doc `ui/docs/wails-version.md` recording the v2-vs-v3
-  decision made at phase start with rationale
-- `ui/desktop/main.go` Wails entry point
-- `ui/desktop/app.go` IPC bindings exposing `ui/core` API to the
-  WebView through a structured adapter
-- `ui/desktop/keychain/` per-OS secure-storage helpers (macOS Keychain
-  via `Security` framework, Windows DPAPI, Linux Secret Service / file
-  fallback at `~/.config/galaxy/keypair` with mode `0600`)
-- `ui/desktop/sqlite/` `modernc.org/sqlite` cache wired through Wails
-  IPC
-- `ui/frontend/src/platform/core/wails.ts` `WailsCore` adapter
-- `ui/frontend/src/platform/store/wails.ts` `WailsKeyStore` and
-  `WailsCache` adapters
-- `ui/desktop/build/icon.icns` macOS app icon
-- `ui/desktop/build/icon.ico` Windows app icon
-- `ui/desktop/build/icon.png` Linux app icon
-- `ui/Makefile` targets `desktop-mac`, `desktop-win`, `desktop-linux`
-- topic doc `ui/docs/desktop-secure-storage.md` documenting the
-  Linux/Windows file fallback for missing keychains
-
-Dependencies: Phase 6 (KeyStore and Cache interfaces); Phases 7
-through 30 in their web form (the desktop wrapper exercises the same
-TypeScript code).
-
-Acceptance criteria:
-
-- the macOS, Windows, and Linux binaries each launch, complete login,
-  and preserve the keypair across restarts on a fresh user profile;
-- a single source codebase produces all three OS bundles;
-- the same `Core` and `Storage` TypeScript interfaces are satisfied as
-  on web, with no platform-specific code outside `platform/`;
-- Linux file fallback activates when Secret Service is absent and
-  writes with `0600` permissions.
-
-Targeted tests:
-
-- Go unit tests for each keychain helper, including file fallback;
-- desktop e2e smoke test driven by Wails headless mode running the
-  Phase 7 login Playwright scenario via CDP;
-- regression test: keychain absence on a Linux container without
-  libsecret falls back to file storage.
-
-## Phase 32. Capacitor Mobile Wrapper
-
-Status: pending.
-
-Goal: build native iOS and Android apps that run the same frontend
-bundle and call into a gomobile-compiled `ui/core`.
-
-Artifacts:
-
-- `ui/mobile-bridge/bridge.go` gomobile-friendly façade over `ui/core`
-- `ui/Makefile` target `gomobile` producing `Galaxy.framework` and
-  `galaxy.aar`
-- `ui/mobile/capacitor.config.ts` Capacitor project configuration
-- `ui/mobile/plugins/galaxy-core/` custom Capacitor plugin (Swift +
-  Kotlin) wrapping the gomobile artifacts
-- `ui/frontend/src/platform/core/capacitor.ts` `CapacitorCore` adapter
-- `ui/frontend/src/platform/store/capacitor.ts` `CapacitorKeyStore`
-  and `CapacitorCache` using `@capacitor-community/secure-storage-plugin`
-  and `@capacitor-community/sqlite`
-- `ui/mobile/ios/App/Assets.xcassets/AppIcon.appiconset/` iOS app
-  icon set
-- `ui/mobile/android/app/src/main/res/mipmap-*/` Android app icon
-  set
-- iOS launch screen and Android splash screen
-- `ui/Makefile` targets `ios` and `android`
-- topic doc `ui/docs/mobile-bridge.md` describing the plugin
-  API, marshalling strategy, and the manual smoke procedure for this
-  phase
-
-Dependencies: Phase 6; Phases 7 through 30 in their web form.
-
-Acceptance criteria:
-
-- both the iOS Simulator and an Android Emulator launch the app,
-  complete login, and preserve the keypair across restarts (validated
-  by manual smoke);
-- the same `Core` and `Storage` TypeScript interfaces are satisfied as
-  on web and desktop;
-- gomobile build produces deterministic outputs reproducible in CI on
-  a macOS runner.
-
-Targeted tests:
-
-- Go unit tests for the `mobile-bridge` façade;
-- Capacitor plugin unit tests on iOS (XCTest) and Android (Espresso);
-- manual smoke procedure: login flow on iOS Simulator and Android
-  Emulator, recorded in `ui/docs/mobile-bridge.md`. Full Appium
-  automation lands in Phase 36 as part of the acceptance pass.
-
-## Phase 33. PWA — Service Worker, Manifest, Web Icons
-
-Status: pending.
-
-Goal: make the web build installable and offline-tolerant on every
-browser. Native packaging icons live with their respective wrapper
-phases (31 for desktop, 32 for mobile) — this phase is web-only.
-
-Artifacts:
-
-- `ui/frontend/src/service-worker.ts` cache-first asset strategy with
-  stale invalidation on app update
-- `ui/frontend/static/manifest.webmanifest` PWA manifest
-- `ui/frontend/static/icons/` web icon set sized per
-  `manifest.webmanifest` requirements
-- topic doc `ui/docs/pwa-strategy.md` covering update flow and
-  offline scope
-
-Dependencies: Phase 25 (offline order queue).
-
-Acceptance criteria:
-
-- the web app installs as a PWA on Chrome, Edge, and iOS Safari;
-- the service worker survives an app update without serving stale code
-  on the next reload.
-
-Targeted tests:
-
-- Lighthouse PWA audit at score ≥ 90;
-- Playwright test: install the app, take it offline, verify the cached
-  login route still loads;
-- regression test: bumping the app version invalidates the prior
-  service worker.
-
-## Phase 34. Multi-Turn Projection — Realistic Planet Forecast
-
-Status: pending. Long-term scope deferred but this phase ships real
-features.
-
-Goal: ship a realistic multi-turn planet projection and surface it in
-the planet inspector and in the calculator's planet area. Reach circles
-already shipped in Phase 30 (auto-drawn from the calculator's selected
-planet); this phase no longer owns them.
-
-The Phase 30 planet area is single-turn (MAT-only): it answers "ships
-this turn / turns per ship" at the current or overridden MAT. This phase
-makes it realistic and multi-turn by extracting the planet economy into
-`pkg/calc` and simulating turns: population growth (`×1.08`), material /
-capital / colonist supply, and the capital/colonist unpacking that
-mirrors `MakeTurn` steps 09/12/14/15. CAP and COL only affect future
-turns (post-production unpacking), so they become meaningful here and
-are added to the calculator's planet area as supply inputs alongside
-MAT.
-
-Artifacts:
-
-- `pkg/calc/` planet-economy extraction (single-sourced, engine
-  delegates): `PlanetProduction`, `ProducePopulation`,
-  `UnpackColonists`, `UnpackCapital`, reusing `ProduceShipsInTurn`; a
-  multi-turn projector `ProjectPlanetBuild` answering "K ships in M
-  turns" under guaranteed per-turn supply
-- thin bridges in `ui/core/calc/` + `Core` typings
-- planet inspector forecast section (next-turn population, industry,
-  materials, production progress)
-- calculator planet area gains CAP and COL supply inputs and switches
-  its readout to the multi-turn projector
-- topic doc `ui/docs/multi-turn-projection.md` (long-term vision:
-  multi-turn planning mode, scenario branches)
-
-Dependencies: Phases 17, 18, 30.
-
-Acceptance criteria:
-
-- projector output is byte-identical to running the engine's per-turn
-  planet update over the same turns (Go parity);
-- the planet inspector shows a forecast section matching it;
-- the calculator planet area honours MAT / CAP / COL supply and shows
-  "K ships in M turns" consistent with the projector.
-
-Targeted tests:
-
-- Go parity tests for each extracted economy formula and the projector;
-- Vitest for the calculator planet area with supply inputs;
-- Playwright e2e: planet inspector forecast section.
-
-## Phase 35. Polish — Accessibility, Localisation, Error UX
-
-Status: pending.
-
-Goal: prepare the client for technical beta with end-user-quality
-polish.
-
-Artifacts:
-
-- `ui/frontend/src/lib/i18n/` translation bundles for English and
-  Russian, covering every visible string
-- `ui/frontend/src/lib/error/` central error surface with stable codes
-  and retry / escalation guidance
-- accessibility audit results recorded under `ui/docs/a11y.md`
-- keyboard-only navigation paths for lobby, game view, and login
-- focus rings, ARIA labels, screen-reader-only text where needed
-- mobile bottom-sheet swipe-down dismissal and tap-outside dismissal,
-  on top of the close button shipped in Phase 13
-- selected-planet visual on the map (ring or halo), wired off the
-  Phase 13 `SelectionStore`
-
-Dependencies: Phase 33.
-
-Acceptance criteria:
-
-- WCAG 2.2 AA compliance on lobby, login, and the in-game shell per
-  axe-core scan;
-- the entire UI is reachable by keyboard only with visible focus
-  rings;
-- every server-side error is mapped to a translated, actionable user
-  message in both languages;
-- locale switch persists across reloads on every platform.
-
-Targeted tests:
-
-- axe-core integration tests on every top-level view;
-- Vitest tests for the i18n bundle structure and missing-translation
-  detection;
-- Playwright keyboard-only navigation tests.
-
-## Phase 36. Acceptance Pass
-
-Status: pending.
-
-Goal: reconcile implementation, documentation, and regression coverage
-before declaring the client ready for technical beta.
-
-Artifacts:
-
-- updated `ui/README.md`, topic docs, and any drift in
-  `docs/ARCHITECTURE.md` or `docs/FUNCTIONAL.md` (mirrored to
-  `docs/FUNCTIONAL_ru.md`)
-- final cross-platform regression run on a release-candidate build
-- `ui/docs/release-checklist.md` for repeatable releases
-- visual regression baselines committed under
-  `ui/frontend/tests/__snapshots__/`; if maintenance proves heavy,
-  follow-up issue to switch to self-hosted Argos
-- Appium harness for iOS Simulator and Android Emulator covering the
-  login flow, push-event flow, and at least one full turn loop;
-  `.gitea/workflows/ui-release.yaml` extended with macOS-runner Appium
-  job (mandatory pre-release gate)
-
-Dependencies: Phases 1 through 35.
-
-Acceptance criteria:
-
-- implementation matches every documented contract and live topic
-  doc;
-- the cross-cutting regression scenarios listed below pass on web,
-  desktop, and mobile;
-- Appium smoke passes on both iOS and Android in CI.
-
-Targeted tests:
-
-- run focused package tests for `ui/core` and every TypeScript
-  module;
-- rerun cross-platform Playwright suites against release-candidate
-  builds;
-- run Tier 2 visual regression baselines;
-- run Appium smoke suites on iOS and Android.
-
----
-
-## Cross-Cutting Regression Scenarios
-
-- A fresh device generates a keypair, completes email-code login, and
-  successfully signs a follow-up authenticated request on every target
-  platform.
-- A returning device resumes its session without re-login, preserves
-  queued orders, and continues receiving push events without gaps.
-- Server-side session revocation tears down the active push stream and
-  forces a re-login on every target platform within one second.
-- Tampering with `payload_bytes`, `payload_hash`, `request_id`,
-  `message_type`, or any signature byte is rejected by the verifier
-  in `ui/core` with a stable error code.
-- Requests outside the freshness window are rejected before they
-  reach network, and the client surfaces a clock-skew warning when
-  its local clock disagrees with the server time event by more than
-  the freshness window.
-- The map renderer holds 60 fps with a 1000-primitive fixture on
-  mid-range hardware on web (Chrome, Edge, Safari, Firefox), desktop
-  (Wails on macOS, Windows, Linux), and mobile (latest iPhone, mid-
-  range Android).
-- The single-tool sidebar preserves state across tab switches; the
-  active view preserves state across view switches; designers
-  preserve their in-progress state when navigating to the map and
-  back through a transient overlay.
-- Order draft is preserved across page reloads, view switches, network
-  drops, and history-mode entry / exit.
-- Orders queued offline are flushed in order on reconnect; a turn-
-  cutoff conflict surfaces as a clearly failed-order banner without
-  retrying forever.
-- History mode applies to every view; the order tab disappears in
-  history mode and the prior draft is restored on return to the
-  current turn.
-- The ship-class designer's calculations match `pkg/calc/` byte-for-
-  byte; any drift between client mirror and server fails CI.
-- Linux desktop builds without Secret Service still complete login by
-  falling back to the `0600` file under `~/.config/galaxy/`.
-- The web service worker invalidates correctly on app update and
-  never serves stale code on the first load after a deploy.
-- Push-event signature verification is mandatory; any verification
-  failure tears down the stream and reconnects with backoff.
-- Locale switch persists across reloads and applies to every visible
-  string on every platform.
-
-## TODO — deferred follow-ups from Phases 1-5
-
-These items are explicit decisions to defer, not unknown work. Each
-should be picked up either as a follow-up patch or folded into the
-phase listed in the parenthesis when that phase lands.
-
-- **Build `core.wasm` in CI, drop the committed artefacts** — install
-  TinyGo on the Gitea Actions runner (`brew install tinygo` is not
-  available on Linux runners, so use the official tarball or
-  `curl … | tar -xz` step), add `make -C ui wasm` ahead of the Vitest
-  step in `.gitea/workflows/ui-test.yaml`, then remove
-  `ui/frontend/static/core.wasm` and `ui/frontend/static/wasm_exec.js`
-  from the repo and re-tighten `ui/.gitignore`. Phase 5 committed the
-  binaries only as a stop-gap so contributors did not have to install
-  TinyGo. (Phase 5 cleanup, blocks before Phase 33 PWA.)
-- **Restore `js.CopyBytesToGo` when TinyGo fixes the
-  `instanceof Uint8Array` check** — the per-element loop in
-  `ui/wasm/main.go::copyBytesFromJS` is a workaround for TinyGo 0.41
-  panicking on Uint8Arrays whose prototype chain crosses Node's
-  `Buffer`. Track upstream
-  (<https://github.com/tinygo-org/tinygo/issues>) and revert the
-  helper once a release is pinned. (Phase 5 follow-up.)
-- **Migrate TS codegen to Connect-ES v2 BSR plugin once published** —
-  `ui/buf.gen.yaml` runs `protoc-gen-es` v2 locally because
-  `buf.build/connectrpc/es` is still on v1.6.1 and emits
-  v1-incompatible imports. When the v2 plugin lands on the BSR, we
-  can either keep the local plugin (no network dep) or move back to
-  the remote, depending on whether buf.build rate limits are hit in
-  CI. (Phase 5 follow-up; revisit when next regenerating.)
-- **Rename `gateway/internal/grpcapi/` → `gateway/internal/connectapi/`**
-  — the package now hosts a Connect-Go listener that natively serves
-  Connect, gRPC, and gRPC-Web; the `grpcapi` name is historical.
-  Touches imports in `gateway/cmd/gateway/main.go` and a couple of
-  cross-package refs. Pure rename, no behaviour change. (Phase 4
-  cleanup; do alongside the next gateway change.)
-- **Rename `GATEWAY_AUTHENTICATED_GRPC_*` env vars to drop the `GRPC`
-  infix** — they label the authenticated-edge tier, not the wire
-  protocol. Affects `gateway/internal/config/`, the integration
-  testenv defaults in `integration/testenv/gateway.go`, the README,
-  and the runbook. Coordinated with the package rename above.
-  (Phase 4 cleanup; not before the env vars are referenced by
-  external operators.)
-- **Add a Docker-stack integration test for Connect end-to-end** —
-  Phase 4 closed with service-level Connect tests only. Once a phase
-  already brings up the full stack (Phase 7 onward, since auth flow
-  needs backend), drop a `integration/connect_call_test.go` that
-  exercises a unary Connect call and a server-streaming Connect call
-  through `testenv.Bootstrap`. (Phase 7+, fold into the phase that
-  needs it.)
-- **Battle viewer — push event `game.battle.new`** — when a battle
-  involving the current player lands, emit a backend notification
-  intent (idempotency `battle-new:<game_id>:<turn>:<battle_id>`,
-  payload `{game_id, turn, battle_id}`) so the in-game shell
-  surfaces a toast with a deep link into the Battle Viewer.
-  (Phase 27 deferred; needs an engine emit-side change.)
-- **Battle viewer — richer ship-class visuals** — current MVP draws
-  one small circle plus `<class>:<numLeft>` label per `(race,
-  className)` pair. Future work derives shape / scale from mass,
-  armament, shields, and the number of ships in the group.
-  (Phase 27 deferred.)
-- **Battle viewer — animated re-distribution on elimination** —
-  current implementation hard-jumps to the new spacing on the next
-  frame; replace with an easing so the survivors visibly slide
-  along the outer ring. (Phase 27 deferred.)
diff --git a/ui/README.md b/ui/README.md
index 12abcde..985532d 100644
--- a/ui/README.md
+++ b/ui/README.md
@@ -14,24 +14,22 @@ boundary on every platform.
 The legacy Fyne client under `client/` is reference-only.
 Nothing in `ui/` imports from it.
 
-The full staged implementation plan lives in `PLAN.md`. The
-strategic rationale (why Svelte, why PixiJS, why Go-as-WASM, why
+The strategic rationale (why Svelte, why PixiJS, why Go-as-WASM, why
 Wails+Capacitor) lives outside the repo at
 `~/.claude/plans/buzzing-questing-fountain.md`. This README is a
-quick orientation; deeper per-phase design notes earn their place
-under `ui/docs/` as they are introduced.
+quick orientation; deeper design notes live under `ui/docs/`.
 
 ## Targets
 
-| Target          | Wrapper          | Toolchain               | Phase    |
-| --------------- | ---------------- | ----------------------- | -------- |
-| web             | browser tab      | Vite + WASM             | 5+       |
-| web-mobile      | mobile browser   | Vite + WASM             | 5+       |
-| desktop (mac)   | Wails v2         | Go + Wails CLI          | 31       |
-| desktop (win)   | Wails v2         | Go + Wails CLI          | 31       |
-| desktop (linux) | Wails v2         | Go + Wails CLI          | 31       |
-| iOS             | Capacitor        | gomobile + Xcode        | 32+      |
-| Android         | Capacitor        | gomobile + Gradle       | 32+      |
+| Target          | Wrapper          | Toolchain               | Status                         |
+| --------------- | ---------------- | ----------------------- | ------------------------------ |
+| web             | browser tab      | Vite + WASM             | implemented                    |
+| web-mobile      | mobile browser   | Vite + WASM             | implemented                    |
+| desktop (mac)   | Wails v2         | Go + Wails CLI          | planned (see ROADMAP.md)       |
+| desktop (win)   | Wails v2         | Go + Wails CLI          | planned (see ROADMAP.md)       |
+| desktop (linux) | Wails v2         | Go + Wails CLI          | planned (see ROADMAP.md)       |
+| iOS             | Capacitor        | gomobile + Xcode        | planned (see ROADMAP.md)       |
+| Android         | Capacitor        | gomobile + Gradle       | planned (see ROADMAP.md)       |
 
 ## Layered architecture
 
@@ -58,7 +56,9 @@ under `ui/docs/` as they are introduced.
 
 ```text
 ui/
-├── PLAN.md                 staged implementation plan (Phases 1-36)
+├── PLAN.md                 staged implementation plan
+├── ROADMAP.md              planned desktop / mobile / multi-turn features
+├── PLAN-finalize.md        PWA, accessibility, localisation, error UX
 ├── Makefile                wasm / ts-protos / web / mobile / desktop targets
 ├── README.md               this file
 ├── buf.gen.yaml            local-plugin TS Protobuf-ES generator
@@ -71,6 +71,9 @@ ui/
 │   └── wasm-toolchain.md    TinyGo build, JSDOM loading, bundle budget
 ├── core/                    ui/core Go module (canonical bytes, keypair)
 ├── wasm/                    TinyGo entry point exposing Core to JS
+├── mobile-bridge/           gomobile bindings (planned — see ROADMAP.md)
+├── desktop/                 Wails project (planned — see ROADMAP.md)
+├── mobile/                  Capacitor project (planned — see ROADMAP.md)
 └── frontend/                SvelteKit / Vite source
     ├── src/api/             GalaxyClient + typed Connect client + auth + session
     ├── src/lib/             env config, session store, revocation watcher
@@ -98,40 +101,23 @@ Linked topic docs:
 - [`docs/testing.md`](docs/testing.md) — Tier 1 per-PR + Tier 2
   release test tiers.
 
-```text
-ui/
-├── README.md                 this file
-├── PLAN.md                   staged implementation plan
-├── Makefile                  cross-target build placeholders
-├── pnpm-workspace.yaml       pnpm workspace root
-├── .gitignore
-├── docs/                     per-phase topic docs (added per phase)
-├── frontend/                 TS + Svelte source, shared across targets
-├── core/                     Go module ui/core (Phase 3+)
-├── wasm/                     TinyGo entry point for core.wasm (Phase 5)
-├── mobile-bridge/            gomobile bindings (Phase 32+)
-├── desktop/                  Wails project (Phase 31)
-├── mobile/                   Capacitor project (Phase 32+)
-└── web/                      static deploy assets (Phase 30+)
-```
-
 ## Build pipeline
 
-Every cross-target build flows through `make` at this level. All
-named targets are placeholders until the named phase lands; running
-`make` with no arguments prints the current placeholder map.
+Every cross-target build flows through `make` at this level.
+Native targets are placeholders until their platform work lands;
+running `make` with no arguments prints the current placeholder map.
 
 ```text
-make web             Vite production build                      Phase 5+
-make wasm            TinyGo → core.wasm                         Phase 5
-make ts-protos       Connect-ES + Protobuf-ES gen               Phase 5
-make fbs-ts          FlatBuffers TS bindings via flatc          Phase 8
-make gomobile        gomobile bind → ios + android              Phase 32+
-make desktop-mac     Wails build for darwin                     Phase 31
-make desktop-win     Wails build for windows                    Phase 31
-make desktop-linux   Wails build for linux                      Phase 31
-make ios             Capacitor + xcodebuild                     Phase 32+
-make android         Capacitor + gradle                         Phase 32+
+make web             Vite production build
+make wasm            TinyGo → core.wasm
+make ts-protos       Connect-ES + Protobuf-ES gen
+make fbs-ts          FlatBuffers TS bindings via flatc
+make gomobile        gomobile bind → ios + android   (planned — see ROADMAP.md)
+make desktop-mac     Wails build for darwin           (planned — see ROADMAP.md)
+make desktop-win     Wails build for windows          (planned — see ROADMAP.md)
+make desktop-linux   Wails build for linux            (planned — see ROADMAP.md)
+make ios             Capacitor + xcodebuild           (planned — see ROADMAP.md)
+make android         Capacitor + gradle               (planned — see ROADMAP.md)
 make all             every target above
 ```
 
@@ -159,18 +145,20 @@ hostnames — use the long-lived dev environment at
 [`../tools/dev-deploy/`](../tools/dev-deploy/README.md). It is
 redeployed by Gitea Actions on every merge into `development`.
 
-## Per-phase docs
+## Topic docs
 
-Topic docs live under `ui/docs/` and are added per phase as they're
-needed (testing tiers, WASM toolchain, navigation shell, renderer
-internals, sync protocol, auth flow, and so on). The staged plan in
-`PLAN.md` names the topic doc each phase produces.
+Topic docs live under `ui/docs/` (testing tiers, WASM toolchain,
+navigation shell, renderer internals, sync protocol, auth flow, and
+so on).
 
 ## Cross-references
 
-- [`PLAN.md`](./PLAN.md) — staged implementation plan with goals,
-  artifacts, dependencies, acceptance criteria, and targeted tests
-  per phase.
+- [`PLAN.md`](./PLAN.md) — staged implementation plan (historical
+  record of completed work).
+- [`ROADMAP.md`](./ROADMAP.md) — planned desktop / mobile / multi-turn
+  projection features.
+- [`PLAN-finalize.md`](./PLAN-finalize.md) — PWA, accessibility,
+  localisation, error UX finalization work.
 - [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) — platform
   architecture and the transport security model (§15) the client
   envelope contract derives from.
@@ -178,4 +166,4 @@ internals, sync protocol, auth flow, and so on). The staged plan in
   stories that drive the UI flows.
 - [`../docs/TESTING.md`](../docs/TESTING.md) — project-wide testing
   layers; UI-specific test tiers (Vitest, Playwright) live in
-  `ui/docs/testing.md` from Phase 2 onward.
+  `ui/docs/testing.md`.
diff --git a/ui/ROADMAP.md b/ui/ROADMAP.md
new file mode 100644
index 0000000..cb2ddb1
--- /dev/null
+++ b/ui/ROADMAP.md
@@ -0,0 +1,156 @@
+# UI Client — Post-MVP Roadmap
+
+The MVP web client (Phases 1–30 of [PLAN.md](PLAN.md)) is complete. The
+near-term web **finalization** pass — visual system, accessibility,
+localisation, error UX, PWA, docs — is tracked separately in
+[PLAN-finalize.md](PLAN-finalize.md).
+
+This roadmap holds the work deliberately deferred until after the web
+client is finalized: the native platform wrappers, the realistic
+multi-turn projection (a feature, not polish), the cross-platform
+acceptance pass, and a set of non-blocking follow-ups. Items keep their
+original PLAN.md phase numbers for continuity; their full original specs
+live in the PLAN.md git history.
+
+---
+
+## Phase 31 — Wails Desktop Wrapper
+
+Goal: native desktop app (macOS, Windows, Linux) running the same
+frontend bundle, with `ui/core` embedded as Go instead of WASM.
+
+Key artifacts: `ui/desktop/` Wails entry + IPC bindings; per-OS secure
+storage (macOS Keychain, Windows DPAPI, Linux Secret Service with a
+`0600` file fallback); `modernc.org/sqlite` cache; `WailsCore` /
+`WailsKeyStore` / `WailsCache` adapters; OS icons; `ui/Makefile`
+`desktop-*` targets; `ui/docs/desktop-secure-storage.md`. Re-evaluate
+Wails v2 vs v3 at phase start.
+
+Depends on: Phase 6 (KeyStore/Cache interfaces) and the web form of
+Phases 7–30. Acceptance: all three OS binaries launch, log in, and
+persist the keypair on a fresh profile from one codebase; Linux file
+fallback activates without libsecret and writes `0600`.
+
+## Phase 32 — Capacitor Mobile Wrapper
+
+Goal: native iOS and Android apps running the same frontend bundle,
+calling a gomobile-compiled `ui/core`.
+
+Key artifacts: `ui/mobile-bridge/bridge.go` gomobile façade;
+`ui/Makefile` `gomobile`/`ios`/`android` targets; Capacitor project +
+custom `galaxy-core` plugin (Swift + Kotlin); `CapacitorCore` /
+`CapacitorKeyStore` / `CapacitorCache` adapters (secure-storage +
+sqlite community plugins); app icons + splash; `ui/docs/mobile-bridge.md`.
+
+Depends on: Phase 6 and the web form of Phases 7–30. Acceptance: iOS
+Simulator and Android Emulator launch, log in, and persist the keypair
+across restarts (manual smoke); same `Core`/`Storage` TS interfaces as
+web/desktop. Full Appium automation lands in Phase 36.
+
+## Phase 34 — Multi-Turn Projection (realistic planet forecast)
+
+Goal: a realistic multi-turn planet projection, surfaced in the planet
+inspector and the calculator's planet area. (Reach circles already
+shipped in Phase 30; this phase no longer owns them.)
+
+The Phase 30 planet area is single-turn (MAT-only). This phase makes it
+realistic and multi-turn by extracting the planet economy into `pkg/calc`
+(single-sourced, engine delegates): `PlanetProduction`,
+`ProducePopulation`, `UnpackColonists`, `UnpackCapital`, reusing
+`ProduceShipsInTurn`; plus a `ProjectPlanetBuild` projector ("K ships in
+M turns" under guaranteed per-turn supply) mirroring `MakeTurn` steps
+09/12/14/15. CAP and COL only affect future turns (post-production
+unpacking), so they become meaningful here and join MAT as supply inputs
+in the calculator's planet area.
+
+Key artifacts: the `pkg/calc` economy extraction + bridges + `Core`
+typings; planet-inspector forecast section (next-turn population,
+industry, materials, progress); calculator planet area gains CAP/COL
+supply; `ui/docs/multi-turn-projection.md`.
+
+Depends on: Phases 17, 18, 30. Acceptance: projector output byte-
+identical to running the engine's per-turn planet update over the same
+turns (Go parity); inspector + calculator readouts consistent with it.
+
+## Phase 36 — Acceptance Pass
+
+Goal: reconcile implementation, documentation, and regression coverage
+before declaring the client ready for technical beta.
+
+Key artifacts: final cross-platform regression run on a release
+candidate; `ui/docs/release-checklist.md`; visual-regression baselines;
+Appium harness (iOS Simulator + Android Emulator) covering login, push,
+and a full turn loop, wired into a macOS-runner CI job as a pre-release
+gate; a docs/README/ARCHITECTURE/FUNCTIONAL drift sweep.
+
+Depends on: Phases 1–35 (incl. the finalization plan). Acceptance:
+implementation matches every documented contract; the cross-cutting
+regression scenarios below pass on web, desktop, and mobile; Appium
+smoke passes on iOS and Android in CI.
+
+### Cross-cutting regression scenarios
+
+- A fresh device generates a keypair, completes email-code login, and
+  signs a follow-up authenticated request on every platform.
+- A returning device resumes its session without re-login, preserves
+  queued orders, and keeps receiving push events without gaps.
+- Server-side session revocation tears down the push stream and forces
+  re-login on every platform within one second.
+- Tampering with `payload_bytes`, `payload_hash`, `request_id`,
+  `message_type`, or any signature byte is rejected by `ui/core` with a
+  stable error code.
+- Requests outside the freshness window are rejected before network; a
+  clock-skew warning surfaces when the local clock disagrees beyond it.
+- The map renderer holds 60 fps with a 1000-primitive fixture on web
+  (Chrome, Edge, Safari, Firefox), desktop (Wails on mac/win/linux),
+  and mobile (latest iPhone, mid-range Android).
+- The sidebar preserves tool state across tab switches; the active view
+  preserves state across view switches.
+- Order draft survives reloads, view switches, network drops, and
+  history-mode entry/exit.
+- Orders queued offline flush in order on reconnect; a turn-cutoff
+  conflict surfaces as a failed-order banner without retrying forever.
+- History mode applies to every view; the order tab disappears in
+  history mode and the prior draft is restored on return.
+- The calculator's math matches `pkg/calc/` byte-for-byte; drift fails
+  CI.
+- Linux desktop without Secret Service completes login via the `0600`
+  file fallback.
+- The web service worker invalidates on app update and never serves
+  stale code on the first load after deploy.
+- Push-event signature verification is mandatory; any failure tears
+  down the stream and reconnects with backoff.
+- Locale switch persists across reloads and applies to every visible
+  string on every platform.
+
+---
+
+## Deferred follow-ups (non-blocking)
+
+Explicit deferral decisions, to fold into the phase noted when it lands.
+(The "build core.wasm in CI / drop the committed artefact" follow-up
+moved to [PLAN-finalize.md](PLAN-finalize.md) F6, since it is timely.)
+
+- **Restore `js.CopyBytesToGo`** when TinyGo fixes the
+  `instanceof Uint8Array` check — the per-element loop in
+  `ui/wasm/main.go::copyBytesFromJS` is a TinyGo 0.41 workaround. Track
+  upstream and revert once a fixed release is pinned.
+- **Migrate TS codegen to the Connect-ES v2 BSR plugin** once published —
+  `ui/buf.gen.yaml` runs `protoc-gen-es` v2 locally because
+  `buf.build/connectrpc/es` still emits v1-incompatible imports.
+- **Rename `gateway/internal/grpcapi/` → `connectapi/`** — historical
+  name; the package serves Connect/gRPC/gRPC-Web. Pure rename. (Fold
+  into the next gateway change; not a UI task.)
+- **Rename `GATEWAY_AUTHENTICATED_GRPC_*` env vars** to drop the `GRPC`
+  infix — they label the authenticated edge tier, not the wire protocol.
+  (Coordinate with the rename above; not a UI task.)
+- **Add a Docker-stack Connect end-to-end integration test** —
+  `integration/connect_call_test.go` exercising a unary + a
+  server-streaming Connect call through `testenv.Bootstrap`.
+- **Battle viewer — push event `game.battle.new`** — emit a backend
+  notification intent (idempotency
+  `battle-new:<game_id>:<turn>:<battle_id>`) so the shell shows a toast
+  deep-linking into the Battle Viewer. Needs an engine emit-side change.
+- **Battle viewer — richer ship-class visuals** — derive shape/scale
+  from mass, armament, shields, and ship count instead of the MVP
+  one-circle-plus-label per `(race, className)`.
diff --git a/ui/core/README.md b/ui/core/README.md
index c8708cd..00c2d61 100644
--- a/ui/core/README.md
+++ b/ui/core/README.md
@@ -4,8 +4,9 @@
 Galaxy cross-platform UI client. It carries v1 transport-envelope
 canonical bytes, signature verification, and Ed25519 keypair
 helpers. Network I/O and persistent storage live elsewhere on
-purpose: this module compiles unchanged to WASM (Phase 5),
-gomobile (Phase 32), and Wails-embedded native (Phase 31).
+purpose: this module compiles unchanged to WASM (the web target today)
+and is designed to also compile to gomobile (mobile) and Wails-embedded
+native (desktop) — both planned, see [`../ROADMAP.md`](../ROADMAP.md).
 
 The authoritative byte contract is defined in
 [`docs/ARCHITECTURE.md` §15](../../docs/ARCHITECTURE.md). The gateway
@@ -39,8 +40,11 @@ parity and round-trip sign/verify are exercised by
 ```text
 ui/core/
 ├── go.mod               module galaxy/core (Go 1.26.0)
-├── calc/                ship-math wrappers over `pkg/calc/ship.go`
-│   └── ship.go          Phase 18 designer preview bridge
+├── calc/                thin wrappers over `pkg/calc/` (no math here)
+│   ├── ship.go          ship geometry, mass, speed, combat
+│   ├── planet.go        ship build cost / per-turn production
+│   ├── solve.go         goal-seek inverse solvers
+│   └── number.go        display rounding (Ceil3)
 ├── canon/               canonical-bytes builders and verifiers
 │   ├── canon.go         length-prefix helpers
 │   ├── request.go       galaxy-request-v1 fields and signing input
@@ -92,20 +96,16 @@ ui/core/
 
 ### `galaxy/core/calc`
 
-Thin Go bridge over `pkg/calc/ship.go`, surfaced via WASM to the
-Phase 18 ship-class designer preview. Each function is a one-line
-passthrough — no math lives here.
+Thin Go bridges over `pkg/calc/`, surfaced via WASM to the ship-class
+calculator and the ship-group inspector. Each function is a one-line
+passthrough — no math lives here. Coverage spans ship geometry / mass /
+speed / cargo, combat (attack, defence, bombing), block-upgrade and
+per-turn ship-build cost, the single-target goal-seek inverse solvers,
+and display rounding (`Ceil3`).
 
-- `DriveEffective(drive, driveTech float64) float64`
-- `EmptyMass(drive, weapons float64, armament uint, shields, cargo float64) (float64, bool)`
-- `WeaponsBlockMass(weapons float64, armament uint) (float64, bool)`
-- `FullMass(emptyMass, carryingMass float64) float64`
-- `Speed(driveEffective, fullMass float64) float64`
-- `CargoCapacity(cargo, cargoTech float64) float64`
-- `CarryingMass(load, cargoTech float64) float64`
-
-The full audit trail (which UI feature uses what, what is still
-deferred) lives in [`ui/docs/calc-bridge.md`](../docs/calc-bridge.md).
+The authoritative function surface (which UI feature uses what, parity
+rules, what is still deferred) lives in
+[`ui/docs/calc-bridge.md`](../docs/calc-bridge.md).
 
 ### `galaxy/core/types`
 
@@ -146,14 +146,15 @@ versa) is enforced from
 ## What this module is **not**
 
 - Not a network client. ConnectRPC over `@connectrpc/connect-web`
-  on the TypeScript side is the only network surface (Phase 5+).
-- Not a key store. Per-platform secure storage lives in Phase 6.
+  on the TypeScript side is the only network surface.
+- Not a key store. Per-platform secure storage lives in the platform
+  `KeyStore` / `Cache` layer on the TypeScript side.
 - Not a freshness gate. Server-side `±5 min` freshness checks
   remain in `gateway/internal/grpcapi/freshness_replay.go`. The
   client is expected to stamp its own `timestamp_ms` accurately
   via `time.Now`, but does not enforce a window.
-- Not a FlatBuffers codec — that lands in a later phase, so the
-  module today is small on purpose.
+- Not a FlatBuffers codec — report decoding lives on the TypeScript
+  side, so this module stays small on purpose.
 
 ## Cross-references
 
@@ -161,5 +162,5 @@ versa) is enforced from
   authoritative byte contract.
 - [`../../gateway/authn`](../../gateway/authn) — server mirror of
   the same canonical bytes.
-- [`../PLAN.md`](../PLAN.md) Phase 3 — the staged plan that
-  describes how this module fits into the wider client.
+- [`../PLAN.md`](../PLAN.md) — the staged plan that describes how this
+  module fits into the wider client.
diff --git a/ui/docs/README.md b/ui/docs/README.md
new file mode 100644
index 0000000..55947cc
--- /dev/null
+++ b/ui/docs/README.md
@@ -0,0 +1,60 @@
+# UI client — topic docs
+
+Deeper, topic-based documentation for the Galaxy web/cross-platform UI
+client, beyond what fits in [`../README.md`](../README.md). Each file
+describes how one area works (current state); the staged build history
+lives in [`../PLAN.md`](../PLAN.md), the active web finalization in
+[`../PLAN-finalize.md`](../PLAN-finalize.md), and deferred work in
+[`../ROADMAP.md`](../ROADMAP.md).
+
+## Foundation & platform
+
+- [navigation.md](navigation.md) — routes, the sidebar tabs, and the
+  state-preservation rules across view/tab switches.
+- [storage.md](storage.md) — the `KeyStore` and `Cache` abstractions and
+  their web (IndexedDB) implementations.
+- [game-state.md](game-state.md) — decoding the FlatBuffers report into
+  `GameReport` and the `GameState` / rendered-report stores.
+- [sync-protocol.md](sync-protocol.md) — order-draft sync, turn cutoff,
+  conflict handling, and auto-pause.
+- [events.md](events.md) — the signed push channel and event handling.
+- [calc-bridge.md](calc-bridge.md) — the `pkg/calc` → WASM → TypeScript
+  bridge, with the live function surface and parity rules.
+- [wasm-toolchain.md](wasm-toolchain.md) — building `ui/core` to
+  `core.wasm` with TinyGo.
+- [testing.md](testing.md) — the UI test layers (Vitest + Playwright).
+
+## Auth & lobby
+
+- [auth-flow.md](auth-flow.md) — device keypair, email-code login, and
+  request signing on the client.
+- [lobby.md](lobby.md) — the lobby/game-list UI and membership flows.
+
+## Map & active views
+
+- [renderer.md](renderer.md) — the PixiJS map renderer contract (world
+  model, hit-test, torus / no-wrap).
+- [order-composer.md](order-composer.md) — the order tab and the
+  optimistic order overlay.
+- [report-view.md](report-view.md) — the Reports view.
+
+## Tools & inspectors
+
+- [calculator-ux.md](calculator-ux.md) — the ship-class calculator
+  (design + goal-seek + planet build + reach circles + modernization).
+- [science-designer-ux.md](science-designer-ux.md) — the science
+  designer.
+- [ship-group-actions.md](ship-group-actions.md) — ship-group inspector
+  actions (move, send, upgrade, …).
+- [cargo-routes-ux.md](cargo-routes-ux.md) — cargo-route composition and
+  reach filtering.
+
+## Combat & comms
+
+- [battle-viewer-ux.md](battle-viewer-ux.md) — the battle viewer.
+- [diplomail-ui.md](diplomail-ui.md) — the diplomatic-mail view.
+
+## Localisation
+
+- [i18n.md](i18n.md) — the localisation mechanism and translation
+  bundles.
diff --git a/ui/docs/auth-flow.md b/ui/docs/auth-flow.md
index 15e75a6..0819ab8 100644
--- a/ui/docs/auth-flow.md
+++ b/ui/docs/auth-flow.md
@@ -96,7 +96,7 @@ The keypair lives next to the id in the same database (object
 store `keypair`, key `device`). Clearing site data wipes both;
 the next load generates a fresh keypair and the user must log in
 again. This is the documented re-login path — there is no paired
-"reissue device session" flow in Phase 7.
+"reissue device session" flow.
 
 ## Browser support
 
@@ -105,25 +105,23 @@ Chrome ≥ 137, Firefox ≥ 130, Safari ≥ 17.4 (see
 [`storage.md`](storage.md) for the rationale). On boot the layout
 runs a sanity probe (`crypto.subtle.generateKey` for `Ed25519`); if
 it rejects, the layout switches to a `browser not supported` page
-instead of rendering `/login`. Phase 7 deliberately does not ship a
-JavaScript Ed25519 fallback — see Phase 6's "modern-browser baseline,
-no JS Ed25519 fallback" decision.
+instead of rendering `/login`. The client deliberately does not ship a
+JavaScript Ed25519 fallback — the design decision is modern-browser
+baseline only.
 
 ## Revocation
 
 The lobby layout opens a long-running `SubscribeEvents` stream as
-soon as `status` becomes `authenticated`. The watcher does not
-process individual events in Phase 7 — that arrives in Phase 24.
-Its only contract is liveness: any non-aborted termination of the
-stream is treated as a server-side session revocation, the watcher
-calls `session.signOut("revoked")`, and the layout effect redirects
-to `/login`.
+soon as `status` becomes `authenticated`. Its only contract is
+liveness: any non-aborted termination of the stream is treated as
+a server-side session revocation, the watcher calls
+`session.signOut("revoked")`, and the layout effect redirects to
+`/login`.
 
-This satisfies the Phase 7 acceptance bar of "session revocation
-closes the active client within one second": the gateway closes
-the stream the moment it observes a `session_invalidation` push
-event from backend, and the watcher reacts on the next event-loop
-tick.
+Session revocation closes the active client within one second: the
+gateway closes the stream the moment it observes a
+`session_invalidation` push event from backend, and the watcher
+reacts on the next event-loop tick.
 
 ## Localisation
 
@@ -140,8 +138,9 @@ drops JS-set `Accept-Language` headers. See
 adding a new language.
 
 The locale is **not** persisted between page reloads; detection
-runs again on every visit. Phase 35's full polish pass will
-revisit persistence and add message-format pluralisation.
+runs again on every visit. Persistence and message-format
+pluralisation are deferred to the finalization plan
+(../Plan-finalize.md).
 
 ## Configuration
 
diff --git a/ui/docs/battle-viewer-ux.md b/ui/docs/battle-viewer-ux.md
index d02bc79..69379a9 100644
--- a/ui/docs/battle-viewer-ux.md
+++ b/ui/docs/battle-viewer-ux.md
@@ -1,9 +1,10 @@
 # Battle Viewer UX
 
-Phase 27 ships a dedicated viewer for battles (`/games/<id>/battle/<battleId>`).
-Bombings stay where they were in Phase 23 — a static table in the
-Reports view (`section-bombings.svelte`). The two domains are
-deliberately not mixed in any visual surface or click target.
+The battle viewer is a dedicated view for battles
+(`/games/<id>/battle/<battleId>`). Bombings are a separate static
+table in the Reports view (`section-bombings.svelte`). The two
+domains are deliberately not mixed in any visual surface or click
+target.
 
 ## Data shape
 
@@ -114,9 +115,8 @@ Below the scene the viewer renders a static `<ol>` text protocol —
 one line per action, formatted from `BattleReportGroup.race` and
 `BattleReportGroup.className`. The line for the current frame is
 highlighted so a non-visual reader can follow along by scrolling
-the log instead of watching the SVG. The list is always present
-and never hidden, satisfying the original Phase 27 acceptance "the
-same data is accessible as a static text log".
+the log instead of watching the SVG. The list is always present and never hidden; the same data is
+accessible as a static text log.
 
 Each log row is also a `<button>`: a click or Enter/Space jumps
 playback to that shot (pauses and seeks). The list auto-scrolls
diff --git a/ui/docs/calc-bridge.md b/ui/docs/calc-bridge.md
index 8a036eb..ffa62ea 100644
--- a/ui/docs/calc-bridge.md
+++ b/ui/docs/calc-bridge.md
@@ -8,17 +8,16 @@ in Go under `pkg/calc/` and are surfaced to the UI through a
 Go → WASM → TypeScript bridge mounted under `ui/core/calc/` and a
 matching TS adapter in `ui/frontend/src/platform/core/`.
 
-Phase 18 lands the **ship-math slice** of the bridge — everything
-the ship-class designer needs to render its preview pane. Phase 20
-extends it with `BlockUpgradeCost` so the ship-group inspector can
-preview modernize cost. Phase 30 extends it with the **combat,
+The bridge covers the **ship-math slice** (everything the ship-class
+designer needs to render its preview pane), `BlockUpgradeCost` (for
+the ship-group inspector's modernize-cost preview), and the **combat,
 planet-build, and goal-seek slice** for the ship-class calculator:
 `EffectiveAttack`, `EffectiveDefence`, `BombingPower`, `ShipBuildCost`,
 `ProduceShipsInTurn`, and the inverse solvers from `pkg/calc/solve.go`.
 Other slices (production/science forecast, the realistic multi-turn
-planet projection) remain deferred to dedicated future phases. This
-document is the running audit trail of what is live, what is missing,
-and how each function maps to its `pkg/calc/` source.
+planet projection) remain deferred. This document is the running audit
+trail of what is live, what is missing, and how each function maps to
+its `pkg/calc/` source.
 
 ## Live bridge surface
 
@@ -52,10 +51,10 @@ on the JS-side `globalThis.galaxyCore` (registered in
 | `ceil3`             | `calc.Ceil3(value)` (`pkg/calc/number.go`)              | `number`        | calculator display rounding (round up to 3 dp) |
 
 `BombingPower` and the per-turn build loop are no longer engine-only:
-Phase 30 extracted `BombingPower` from
-`game/internal/model/game/group.go` and the per-iteration build math
-from `controller.ProduceShip` into `pkg/calc` (`ProduceShipsInTurn`),
-and the engine now delegates to both — a true refactor, not a mirror.
+`BombingPower` was extracted from `game/internal/model/game/group.go`
+and the per-iteration build math from `controller.ProduceShip` into
+`pkg/calc` (`ProduceShipsInTurn`); the engine now delegates to both —
+a true refactor, not a mirror.
 The inverse solvers (`pkg/calc/solve.go`) invert the forward formulas
 for single-target goal-seek and return `null` when infeasible;
 `shieldsForDefence` uses bisection, the rest are analytic. Parity and
@@ -77,12 +76,12 @@ same inputs and asserts byte-equal outputs.
 
 ## Still-deferred slices
 
-Phase 18's Go-side bridge is intentionally narrow: it covers ship
-math and nothing else. Production forecasts, science, ship-build
-progress, and reach (`FligthDistance`) still depend on either
-inline TS arithmetic or the engine-shipped fields on `GameReport`.
-See the table further down for what is missing and the per-feature
-waivers below for the rationale on each deferral.
+The Go-side bridge is intentionally narrow: it covers ship math and
+the combat/planet-build/goal-seek slice. Production forecasts, science,
+and reach (`FligthDistance`) still depend on either inline TS arithmetic
+or the engine-shipped fields on `GameReport`. See the table further down
+for what is missing and the per-feature waivers below for the rationale
+on each deferral.
 
 ## Current `pkg/calc/` exports
 
@@ -91,7 +90,7 @@ waivers below for the rationale on each deferral.
 | `ShipProductionCost(shipEmptyMass float64) float64`    | Production units required per unit of ship empty mass (×10).                                     |
 | `PlanetProduceShipMass(L, Mat, Res float64) float64`   | Ship mass produced per turn given free production `L`, material stockpile `Mat`, resources `Res`.|
 | `DriveEffective`, `Speed`, `EmptyMass`, `FullMass`, …  | Ship-level derivations (`pkg/calc/ship.go`).                                                     |
-| `BlockUpgradeCost(blockMass, currentTech, target)`     | Production cost of upgrading a single ship block (Phase 20 migrated this from `controller`).     |
+| `BlockUpgradeCost(blockMass, currentTech, target)`     | Production cost of upgrading a single ship block (migrated from `controller`).                   |
 | `FligthDistance(driveTech)`, `VisibilityDistance(...)` | Race-level reach formulas (`pkg/calc/race.go`).                                                  |
 | `ValidateShipTypeValues`, `CheckShipTypeValueDWSC`     | Ship-design validators (`pkg/calc/validator.go`).                                                |
 
@@ -105,83 +104,70 @@ never been exported.
 The table below tracks what UI features need from the bridge and
 whether the underlying Go function exists.
 
-| UI feature                                        | Go formula                                                                                                                  | In `pkg/calc/`? | Surfaced to TS? |
-| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | :-------------: | :-------------: |
-| Ship-class designer preview (Phase 18)            | `EmptyMass`, `FullMass`, `Speed`, `DriveEffective`, `CargoCapacity`, `CarryingMass`, `WeaponsBlockMass` (`pkg/calc/ship.go`) |       yes       |       yes       |
-| Ship-group modernize cost preview (Phase 20)      | `BlockUpgradeCost` (`pkg/calc/ship.go`, migrated from `game/internal/controller/ship_group_upgrade.go`)                     |       yes       |       yes       |
-| Ship calculator combat (Phase 30)                 | `EffectiveAttack`, `EffectiveDefence`, `BombingPower` (`pkg/calc/ship.go`; `BombingPower` extracted from `model/game/group.go`) |       yes       |       yes       |
-| Ship calculator goal-seek (Phase 30)              | inverse solvers in `pkg/calc/solve.go`                                                                                      |       yes       |       yes       |
-| Free production potential (`freeIndustry`)        | `Planet.ProductionCapacity` → `industry*0.75 + population*0.25` (`game/internal/model/game/planet.go`)                       |       no        |       no        |
-| Industry production output per turn               | `Planet.ProduceIndustry(freeProduction)` (`planet.go`); `freeProduction/5` modulo material constraint                       |       no        |       no        |
-| Materials production output per turn              | `Planet.ProduceMaterial(freeProduction)` (`planet.go`); `freeProduction * resources`                                          |       no        |       no        |
-| Per-tech research progress (DRIVE/WEAPONS/…)      | `ResearchTech` (`game/internal/model/game/science.go`); `freeProduction / 5000` per tech level                              |       no        |       no        |
-| Custom-science progress                           | weighted form of `ResearchTech` driven by `Race.Sciences[].(Drive\|Weapons\|Shields\|Cargo)` (`science.go`)                  |       no        |       no        |
-| Ship build progress / planet build rate (Phase 30)| `ProduceShipsInTurn(L, Mat, Res, mass)` (`pkg/calc/planet.go`, extracted from `controller.ProduceShip`); `ShipBuildCost`     |       yes       |       yes       |
+| UI feature                                      | Go formula                                                                                                                  | In `pkg/calc/`? | Surfaced to TS? |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | :-------------: | :-------------: |
+| Ship-class designer preview                     | `EmptyMass`, `FullMass`, `Speed`, `DriveEffective`, `CargoCapacity`, `CarryingMass`, `WeaponsBlockMass` (`pkg/calc/ship.go`) |       yes       |       yes       |
+| Ship-group modernize cost preview               | `BlockUpgradeCost` (`pkg/calc/ship.go`, migrated from `game/internal/controller/ship_group_upgrade.go`)                     |       yes       |       yes       |
+| Ship calculator combat                          | `EffectiveAttack`, `EffectiveDefence`, `BombingPower` (`pkg/calc/ship.go`; `BombingPower` extracted from `model/game/group.go`) |       yes       |       yes       |
+| Ship calculator goal-seek                       | inverse solvers in `pkg/calc/solve.go`                                                                                      |       yes       |       yes       |
+| Free production potential (`freeIndustry`)      | `Planet.ProductionCapacity` → `industry*0.75 + population*0.25` (`game/internal/model/game/planet.go`)                       |       no        |       no        |
+| Industry production output per turn             | `Planet.ProduceIndustry(freeProduction)` (`planet.go`); `freeProduction/5` modulo material constraint                       |       no        |       no        |
+| Materials production output per turn            | `Planet.ProduceMaterial(freeProduction)` (`planet.go`); `freeProduction * resources`                                          |       no        |       no        |
+| Per-tech research progress (DRIVE/WEAPONS/…)    | `ResearchTech` (`game/internal/model/game/science.go`); `freeProduction / 5000` per tech level                              |       no        |       no        |
+| Custom-science progress                         | weighted form of `ResearchTech` driven by `Race.Sciences[].(Drive\|Weapons\|Shields\|Cargo)` (`science.go`)                  |       no        |       no        |
+| Ship build progress / planet build rate         | `ProduceShipsInTurn(L, Mat, Res, mass)` (`pkg/calc/planet.go`, extracted from `controller.ProduceShip`); `ShipBuildCost`     |       yes       |       yes       |
 
 `partial` means the Go primitives exist in `pkg/calc/` but the
 composition (and the conversion of TS-side `ReportPlanet`/
 `ShipClass` to the formula inputs) is not implemented anywhere.
 
-## Phase 15 waiver
+## Production forecast waiver
 
-Phase 15 ships the inspector's planet production controls
-(segmented control + sub-pickers + collapse-by-`planetNumber`
-order command) but **deliberately does not surface the per-type
-forecast number**. The planning gate explicitly raised the gap as
-a blocker per the plan's audit clause ("if any are missing in
-`pkg/calc/`, raise as blocker") and the project owner approved
-deferring the forecast to a dedicated future bridge phase. The
-inspector still renders the existing `freeIndustry` row (free
-production potential) — that number is computed engine-side and
-ships in the report payload, so no calc-bridge access is required
-for it today.
+The inspector's planet production controls (segmented control +
+sub-pickers + collapse-by-`planetNumber` order command) do **not**
+surface the per-type forecast number. The inspector renders the
+existing `freeIndustry` row (free production potential) — that number
+is computed engine-side and ships in the report payload, so no
+calc-bridge access is required for it. The per-type forecast number
+is deferred pending promotion of the relevant formulas into
+`pkg/calc/`.
 
-Acceptance criterion 3 of Phase 15 ("forecast output number
-reflects the chosen production type and matches `pkg/calc/`
-outputs") is therefore intentionally not satisfied; the rewritten
-Phase 15 stage text records this decision and points back at this
-document.
+## Reach formula waiver
 
-## Phase 16 waiver
-
-Phase 16 introduces ship-reach filtering for the cargo-route
-destination picker. The engine formula is trivial:
+Ship-reach filtering for the cargo-route destination picker uses
+a trivial engine formula:
 
 ```
 flightDistance = driveTech * 40
 ```
 
-The Go-side reference now lives in
+The Go-side reference lives in
 [`pkg/calc/race.go`](../../pkg/calc/race.go) as
 `FligthDistance(driveTech) float64` (alongside the matching
-`VisibilityDistance` for in-space group reports — used in later
-phases). The engine call sites
-(`game/internal/model/game/race.go.FlightDistance`,
+`VisibilityDistance` for in-space group reports). The engine call
+sites (`game/internal/model/game/race.go.FlightDistance`,
 `game/internal/controller/route.go.PlanetRouteSet`) still wrap the
 Go formula directly; promoting them to call `pkg/calc/` is a
-follow-up cleanup outside Phase 16's scope.
+pending cleanup.
 
-The original Phase 16 stage text described surfacing this through
-`pkg/calc/` and `ui/core/calc/`; with the calc-bridge phase still
-deferred, implementing the WASM glue for one constant-time
-multiplication would be premature scaffolding. The picker
-therefore computes reach inline in TypeScript using
-`torusShortestDelta(planet.x, candidate.x, mapWidth)` and
-`Math.hypot` against `40 * report.localPlayerDrive`, where
-`localPlayerDrive` is decoded from the report's `Player` block by
-matching `Player.name` to `report.race`
+Implementing the WASM glue for one constant-time multiplication
+would be premature scaffolding, so the picker computes reach inline
+in TypeScript using `torusShortestDelta(planet.x, candidate.x,
+mapWidth)` and `Math.hypot` against `40 * report.localPlayerDrive`,
+where `localPlayerDrive` is decoded from the report's `Player` block
+by matching `Player.name` to `report.race`
 (`api/game-state.ts.findLocalPlayerDrive`).
 
-When the calc-bridge phase ships, the inline formula is replaced
-with a single call into the bridge — `calc.FligthDistance(driveTech)`
-becomes the source of truth for both the picker and the
-cargo-route auto-removal at turn cutoff. Until then, the UI
-duplicates `flightDistance` knowingly — same precedent as the
-production forecast deferral above.
+When the remaining bridge work ships, the inline formula will be
+replaced with a single call into the bridge —
+`calc.FligthDistance(driveTech)` becomes the source of truth for
+both the picker and the cargo-route auto-removal at turn cutoff.
+Until then, the UI duplicates `flightDistance` knowingly — same
+precedent as the production forecast deferral above.
 
-## Planned bridge growth (follow-up phases)
+## Planned bridge growth
 
-Phase 18 set up the canonical bridge layout (Go subpackage + WASM
+The canonical bridge layout is established (Go subpackage + WASM
 registration + typed `Core` interface + parity tests). Future calc
 work follows the same shape:
 
diff --git a/ui/docs/calculator-ux.md b/ui/docs/calculator-ux.md
index 81646c2..bce9279 100644
--- a/ui/docs/calculator-ux.md
+++ b/ui/docs/calculator-ux.md
@@ -1,8 +1,8 @@
 # Ship Class Calculator — UX
 
-Phase 30 fuses the ship-class designer and a calculator into one sidebar
-tool (`lib/sidebar/calculator-tab.svelte`). It replaced the standalone
-designer view/route from Phases 17/18. All numeric math lives in
+The ship-class designer and calculator are fused into one sidebar
+tool (`lib/sidebar/calculator-tab.svelte`). The standalone designer
+view/route was replaced by this combined tool. All numeric math lives in
 `pkg/calc` and is reached through the `Core` WASM bridge; the calculator
 holds input state and orchestrates, it never computes.
 
@@ -36,7 +36,7 @@ in as a per-ship result rather than a separate mode.
 3. **Planet area** — when an own planet is selected on the map, shows
    its MAT (overridable) and the single-turn build rate (ships per turn,
    turns per ship). The realistic multi-turn forecast with CAP/COL
-   supply is Phase 34.
+   supply is planned (see ../ROADMAP.md).
 
 ## Locks and goal-seek
 
diff --git a/ui/docs/cargo-routes-ux.md b/ui/docs/cargo-routes-ux.md
index 8d128bc..6d27897 100644
--- a/ui/docs/cargo-routes-ux.md
+++ b/ui/docs/cargo-routes-ux.md
@@ -1,13 +1,12 @@
 # Cargo routes UX
 
-This document covers the cargo-route surface added in Phase 16: the
-four-slot inspector subsection, the map-driven destination pick, and
-the optimistic overlay that keeps the inspector and the map in lock-
-step with the local order draft. The user-visible spec lives in
-[`../PLAN.md`](../PLAN.md) Phase 16; the engine semantics are quoted
-from [`game/rules.txt`](../../game/rules.txt) section "Грузовые
-маршруты" (lines 808–843); this file is the source of truth for how
-the UI surfaces those rules.
+This document covers the cargo-route surface: the four-slot
+inspector subsection, the map-driven destination pick, and the
+optimistic overlay that keeps the inspector and the map in lock-step
+with the local order draft. The engine semantics are quoted from
+[`game/rules.txt`](../../game/rules.txt) section "Грузовые маршруты"
+(lines 808–843); this file is the source of truth for how the UI
+surfaces those rules.
 
 ## Engine semantics in one paragraph
 
@@ -44,7 +43,7 @@ section). `Remove` emits a `removeCargoRoute` command. The collapse
 rule on the order draft store ensures only one entry per
 `(source, loadType)` slot survives in the draft at any time, so a
 sequence of `Add → Edit → Remove` collapses to the latest verb only
-(matching the production-controls pattern from Phase 15).
+(matching the production-controls pattern).
 
 Disabled state: every button is disabled when the
 `OrderDraftStore` or `MapPickService` context is missing (the
@@ -98,8 +97,8 @@ centre + zoom before each remount and restores them when the game
 id is unchanged, so adding a route mid-pan does not jolt the view.
 
 Arrows are drawn as a shaft plus two short arrowhead wings. Per-type
-styling (placeholder Phase 16 colours; final values land in Phase
-35 polish):
+styling (visual refinements are deferred to the finalization plan
+(../PLAN-finalize.md)):
 
 | Load type | Stroke colour | Notes                    |
 | --------- | ------------- | ------------------------ |
@@ -132,11 +131,11 @@ ownership of the *origin*). The picker mirrors that contract: the
 `reachableSet()` in `cargo-routes.svelte` filters out only the
 source planet itself.
 
-Why inline rather than via a Go calc bridge? See the Phase 15 / 16
-deferral note in [`calc-bridge.md`](./calc-bridge.md). The formula
-is trivial (`tech × 40`) and the WASM glue would be premature
-infrastructure; when the calc bridge phase lands the shared
-`pkg/calc.FligthDistance` will replace this implementation.
+Why inline rather than via a Go calc bridge? See the deferral note
+in [`calc-bridge.md`](./calc-bridge.md). The formula is trivial
+(`tech × 40`) and the WASM glue would be premature infrastructure;
+when the calc bridge lands the shared `pkg/calc.FligthDistance` will
+replace this implementation.
 
 ## Tests
 
diff --git a/ui/docs/diplomail-ui.md b/ui/docs/diplomail-ui.md
index 1f71e83..36edb7a 100644
--- a/ui/docs/diplomail-ui.md
+++ b/ui/docs/diplomail-ui.md
@@ -1,9 +1,9 @@
 # In-game diplomatic mail UI
 
-Phase 28 wires the in-game mail view that consumes the `diplomail`
-subsystem in the backend. The route lives at `/games/:id/mail`
-(registered in Phase 10) and replaces the active view when the user
-opens the "diplomatic mail" entry in the header menu.
+The in-game mail view consumes the `diplomail` subsystem in the
+backend. The route lives at `/games/:id/mail` and replaces the
+active view when the user opens the "diplomatic mail" entry in the
+header menu.
 
 ## Wire surface
 
@@ -29,8 +29,8 @@ the gateway translation lives in
 ## Recipient by race name
 
 The compose flow does **not** consult a memberships listing. The
-recipient picker reads `gameState.report.races[].name` (the Phase 22
-projection of `report.player[]`), and the send request carries the
+recipient picker reads `gameState.report.races[].name` (projected
+from `report.player[]`), and the send request carries the
 chosen race name as `recipient_race_name`. The backend resolves it
 against `Memberships.ListMembers(gameID, "active")` and rejects with
 `forbidden` if the matching member is no longer active. This keeps
@@ -55,8 +55,8 @@ projects the union of inbox and sent into:
 
 `read_at` and `deleted_at` are not surfaced to the user in any pane
 — they only drive the badge counter and the optimistic mark-read
-state. This is intentional (per Phase 28 decisions): the user-facing
-spec for diplomatic mail does not promise read receipts.
+state. This is intentional: the user-facing spec for diplomatic mail
+does not promise read receipts.
 
 ## Translation toggle
 
diff --git a/ui/docs/events.md b/ui/docs/events.md
index b079f70..bfc296c 100644
--- a/ui/docs/events.md
+++ b/ui/docs/events.md
@@ -9,9 +9,8 @@ stops it on sign-out.
 
 ## Why a single consumer
 
-Before Phase 24, the watcher in `lib/revocation-watcher.ts` opened a
-parallel stream just to observe session revocation. Phase 24 folds
-that watcher into `EventStream` so that:
+The `EventStream` singleton consolidates what was previously a
+separate revocation watcher in `lib/revocation-watcher.ts` so that:
 
 - there is only **one** SubscribeEvents connection per session
   (avoids doubling the gateway hub load);
@@ -19,7 +18,7 @@ that watcher into `EventStream` so that:
   `Unauthenticated` ConnectError funnel through one
   `session.signOut("revoked")` call site;
 - per-event-type dispatch (turn-ready toasts, lobby/mail/battle
-  notifications later) shares the same verification path.
+  notifications) shares the same verification path.
 
 ## Lifecycle
 
@@ -67,10 +66,9 @@ exponential backoff (base 1 s, ceiling 30 s, unbounded retries).
 - `reconnecting` — transient failure, backoff in flight.
 - `offline` — `navigator.onLine === false` at the moment of failure.
 
-The header connection-state indicator planned in `PLAN.md`
-cross-cutting shell reads this rune; it is not part of Phase 24 but
-the rune is wired now so a later phase can add the dot without
-touching this module.
+The header connection-state indicator reads this rune; the rune is
+wired so a future change can add the indicator dot without touching
+this module.
 
 ## Revocation semantics
 
diff --git a/ui/docs/game-state.md b/ui/docs/game-state.md
index 5a1cf93..ce6a136 100644
--- a/ui/docs/game-state.md
+++ b/ui/docs/game-state.md
@@ -1,10 +1,8 @@
 # Per-game state store
 
 This document describes the per-game state owned by the in-game shell
-layout. Phase 11 introduces the store and uses it for two consumers
-(the header turn counter and the map view); later phases plug
-inspector tabs, the order composer, and the calculator on top of the
-same instance.
+layout. The store serves the header turn counter, the map view,
+inspector tabs, the order composer, and the calculator.
 
 ## Lifecycle
 
@@ -23,10 +21,9 @@ gameId })`. `init`:
 2. calls `setGame(gameId)`, which:
    - reads the per-game wrap-mode preference from `Cache`
      (`game-prefs / <gameId>/wrap-mode`, default `torus`);
-   - calls `lobby.my.games.list` and finds the game record (the
-     Phase 11 wire schema extension on `GameSummary` adds
-     `current_turn`); if the user is not a member, the store flips
-     to `error`;
+   - calls `lobby.my.games.list` and finds the game record
+     (`GameSummary` carries `current_turn`); if the user is not a
+     member, the store flips to `error`;
    - calls `user.games.report` for the discovered turn and decodes
      the FlatBuffers response into a TS-friendly `GameReport` shape.
 
@@ -44,24 +41,21 @@ The store exposes:
 | `wrapMode`    | `torus / no-wrap`             | per-game preference, persisted via `Cache`           |
 | `error`       | `string \| null`              | localised error message when `status === "error"`    |
 
-## Phase boundaries
+## Store extensions
 
-- Phase 11 surfaces only the planet subset of the report. Later
-  phases extend `GameReport` and `decodeReport` as their slice of
-  the wire lands (ships, fleets, sciences, routes, battles, mail).
-- Phase 26 splits `currentTurn` from the turn whose snapshot is
-  displayed (`viewedTurn`) and adds `viewTurn(turn)` /
-  `returnToCurrent()` for history navigation. The derived
-  `historyMode` rune flips automatically when `viewedTurn <
-  currentTurn`; the layout passes it to Phase 12's sidebar /
-  bottom-tabs wiring (which hides the order tab) and to
-  `OrderDraftStore.bindClient` (which gates `add` / `remove` /
-  `move`). See "History mode" below for the cache and refresh
-  rules.
-- Phase 24 replaces the tab-focus refresh with push-event-driven
-  refreshes; the visibility listener stays as a fallback for
-  background tabs that miss a push.
-- Phase 29 wires the wrap-mode toggle UI on top of `setWrapMode`.
+`GameReport` and `decodeReport` are extended as each slice of the
+wire lands (ships, fleets, sciences, routes, battles, mail).
+`currentTurn` is split from `viewedTurn`, and `viewTurn(turn)` /
+`returnToCurrent()` handle history navigation. The derived
+`historyMode` rune flips automatically when `viewedTurn <
+currentTurn`; the layout passes it to the sidebar / bottom-tabs
+wiring (which hides the order tab) and to
+`OrderDraftStore.bindClient` (which gates `add` / `remove` / `move`).
+See "History mode" below for the cache and refresh rules.
+Tab-focus refreshes are supplemented by push-event-driven refreshes;
+the visibility listener stays as a fallback for background tabs that
+miss a push. The wrap-mode toggle UI is wired on top of
+`setWrapMode`.
 
 ## Why `current_turn` lives on `GameSummary`
 
@@ -79,20 +73,19 @@ Extending `GameSummary` reuses the existing lobby pipeline; the
 backend already tracks `current_turn` in its runtime projection
 (`backend/internal/server/handlers_user_lobby_helpers.go`
 `gameSummaryToWire` reads it from `g.RuntimeSnapshot.CurrentTurn`).
-
-The wire change touches Phase 8's already-shipped catalogue, but the
-`current_turn` field defaults to zero on the FB side, so existing
+The `current_turn` field defaults to zero on the FB side, so existing
 tests and the dev sandbox flow continue to work unchanged.
 
 ## State binding
 
 `map/state-binding.ts::reportToWorld(report)` translates a
-`GameReport` into a renderer-ready `World`. Phase 11 emits one Point
+`GameReport` into a renderer-ready `World`. It emits one Point
 primitive per planet across all four kinds (local / other /
 uninhabited / unidentified). Each kind gets a distinct fill colour,
 fill alpha, and point radius so the four classes are
-visually-distinguishable at a glance; later phases will refine the
-colour palette as the visual language stabilises (Phase 35 polish).
+visually-distinguishable at a glance; colour-palette refinement is
+deferred to the finalization plan
+([../PLAN-finalize.md](../PLAN-finalize.md)).
 
 The planet engine number is reused as the primitive id so a hit-test
 result can resolve back to a planet without an extra lookup table.
@@ -108,9 +101,9 @@ unchanged), so a no-op refresh does not flicker the canvas.
 
 In history mode `refresh()` is a no-op — forcing a reload would
 silently bump the user back onto the current turn while they are
-intentionally viewing a past one. Push events (Phase 24) still
-deliver new-turn notifications asynchronously while the user
-explores history, so the pending-turn toast continues to work.
+intentionally viewing a past one. Push events still deliver
+new-turn notifications asynchronously while the user explores
+history, so the pending-turn toast continues to work.
 
 `setWrapMode(mode)` writes to `Cache` and updates the rune; the
 map view's effect picks the change up and re-mounts the renderer
@@ -118,20 +111,19 @@ with the new mode.
 
 ## Map visibility toggles
 
-Phase 29 adds a `mapToggles: MapToggles` rune that drives the
-gear popover in the map view. Every flag defaults to `true` —
-including `unreachablePlanets` (showing every planet by default)
-and `visibleHyperspace` (the fog overlay on by default). The
-exhaustive shape lives in `src/lib/game-state.svelte.ts`; the
-gear popover (`src/lib/active-view/map-toggles.svelte`) is a
-thin view of the rune.
+A `mapToggles: MapToggles` rune drives the gear popover in the map
+view. Every flag defaults to `true` — including `unreachablePlanets`
+(showing every planet by default) and `visibleHyperspace` (the fog
+overlay on by default). The exhaustive shape lives in
+`src/lib/game-state.svelte.ts`; the gear popover
+(`src/lib/active-view/map-toggles.svelte`) is a thin view of the
+rune.
 
-`setMapToggle(key, value)` flips one entry in place and
-persists the whole blob to `Cache` under the
-`game-map-toggles/{gameId}` key. The blob carries a companion
-`lastResetTurn` number — the turn at which the toggles were last
-reset to defaults — so the new-turn reset path (below) can detect
-a stale blob even across a cross-session gap.
+`setMapToggle(key, value)` flips one entry in place and persists
+the whole blob to `Cache` under the `game-map-toggles/{gameId}` key.
+The blob carries a companion `lastResetTurn` number — the turn at
+which the toggles were last reset to defaults — so the new-turn reset
+path (below) can detect a stale blob even across a cross-session gap.
 
 ### New-turn reset
 
@@ -156,7 +148,7 @@ The cache namespace and blob shape are documented in
 
 ## History mode
 
-Phase 26 lets the user step backward through the report timeline
+The store lets the user step backward through the report timeline
 without losing the live snapshot. The store keeps two turn runes:
 
 - `currentTurn` — the server's authoritative latest. Only
@@ -170,7 +162,7 @@ The derived `historyMode` rune (`status === "ready" && viewedTurn
 < currentTurn`) drives every history-aware consumer:
 
 - the layout passes it to `Sidebar` / `BottomTabs` so the order
-  tab vanishes (Phase 12 prop wiring);
+  tab vanishes;
 - the layout passes a `getHistoryMode` getter to
   `OrderDraftStore.bindClient` so `add` / `remove` / `move` are
   no-ops while the user is looking at a past turn;
@@ -179,17 +171,17 @@ The derived `historyMode` rune (`status === "ready" && viewedTurn
 - the new `HistoryBanner` component renders the sticky "Viewing
   turn N · read-only" strip when the flag is true.
 
-`last-viewed-turn` semantics keep their Phase 11 meaning: "the
-latest turn the user was caught up on". `loadTurn` only writes the
-cache row when called with `isCurrent === true` (i.e. when the
-load matches `currentTurn`). Historical excursions are therefore
-ephemeral: closing the tab and reopening the game resumes on the
-last caught-up turn, not on the last clicked one.
+`last-viewed-turn` means "the latest turn the user was caught up
+on". `loadTurn` only writes the cache row when called with
+`isCurrent === true` (i.e. when the load matches `currentTurn`).
+Historical excursions are therefore ephemeral: closing the tab and
+reopening the game resumes on the last caught-up turn, not on the
+last clicked one.
 
 Past-turn reports are cached in the `game-history` namespace
 (`{gameId}/turn/{N}` → `GameReport`). The cache is written by
 `loadTurn` on every successful historical fetch and read first by
 `viewTurn(N)` before falling back to the network. Past turns are
-immutable, so the cache has no TTL and no eviction in Phase 26.
-The current-turn snapshot is deliberately *not* cached — it is
-mutable until the next engine tick.
+immutable, so the cache has no TTL and no eviction. The current-turn
+snapshot is deliberately *not* cached — it is mutable until the next
+engine tick.
diff --git a/ui/docs/i18n.md b/ui/docs/i18n.md
index 4dd92b4..7cfe9e4 100644
--- a/ui/docs/i18n.md
+++ b/ui/docs/i18n.md
@@ -1,14 +1,14 @@
 # i18n (UI)
 
 The UI client ships with a minimal locale primitive used by the
-phase-7 login form, the root layout, and the lobby placeholder. The
-goal is just enough infrastructure to translate user-visible
-strings, switch the active language at runtime, and forward the
-caller's choice to the gateway. Phase 35 will swap this primitive
-for a fuller solution once message-format pluralisation, lazy
-loading, and translator workflows become necessary; until then,
-the surface here covers every authenticated and unauthenticated
-screen the client renders.
+login form, the root layout, and the lobby. The goal is just
+enough infrastructure to translate user-visible strings, switch
+the active language at runtime, and forward the caller's choice to
+the gateway. Swapping this primitive for a fuller solution with
+message-format pluralisation, lazy loading, and translator
+workflows is deferred to the finalization plan
+(../Plan-finalize.md); until then, the surface here covers every
+authenticated and unauthenticated screen the client renders.
 
 ## Surface
 
@@ -79,13 +79,15 @@ any preference, or `DEFAULT_LOCALE` (English) when nothing matches.
 The web target calls it without arguments, in which case the helper
 reads `navigator.languages` (or `navigator.language` as fallback).
 Native wrappers (Wails, Capacitor) will pass their system locale
-once Phase 31/32 lands; the helper is platform-agnostic by design.
+once the desktop/mobile targets land (see ../ROADMAP.md); the
+helper is platform-agnostic by design.
 
 The detection runs once at module load — there is no asynchronous
 init step. Callers that mutate the locale (e.g. the language picker
 on `/login`) call `i18n.setLocale(next)` directly. The choice is
-**not** persisted between page reloads in Phase 7; the next visit
-re-runs detection. Persistence is a phase-35 concern.
+**not** persisted between page reloads; the next visit re-runs
+detection. Persistence is deferred to the finalization plan
+(../Plan-finalize.md).
 
 ## Forwarding the locale to the gateway
 
diff --git a/ui/docs/lobby.md b/ui/docs/lobby.md
index bbfd74e..c8dc065 100644
--- a/ui/docs/lobby.md
+++ b/ui/docs/lobby.md
@@ -2,11 +2,9 @@
 
 The lobby is the first authenticated view; the user lands here after
 the email-code login completes (see
-[`docs/auth-flow.md`](auth-flow.md)). Phase 8 introduced the live
-lobby with five sections, the create-game form, and the TS-side
-FlatBuffers integration the rest of the client builds on. This doc
-captures the sections, the application / invite lifecycle the user
-sees, and the defaults baked into the create-game form.
+[`docs/auth-flow.md`](auth-flow.md)). This doc captures the
+sections, the application / invite lifecycle the user sees, and
+the defaults baked into the create-game form.
 
 ## Sections
 
@@ -23,15 +21,15 @@ width.
 | `my applications`    | `no applications`     | `lobby.my.applications.list` | Status badge (`pending` / `approved` / `rejected`)      |
 | `public games`       | `no public games`     | `lobby.public.games.list`  | Submit application via inline race-name form (`lobby.application.submit`) |
 
-The header preserves the device-session-id `<code>` block from the
-Phase 7 placeholder (kept as a debug affordance) plus a greeting if
-the gateway returns a `display_name` for the caller.
+The header preserves the device-session-id `<code>` block (kept as
+a debug affordance) plus a greeting if the gateway returns a
+`display_name` for the caller.
 
-`GameSummary` carries an extra `current_turn` field (Phase 11
-extension) that the lobby UI does not display directly — the in-game
-shell reads it from the same payload to load the matching
-`user.games.report` for the map view without an additional gateway
-call. See [`game-state.md`](game-state.md) for the consumer's view.
+`GameSummary` carries a `current_turn` field that the lobby UI does
+not display directly — the in-game shell reads it from the same
+payload to load the matching `user.games.report` for the map view
+without an additional gateway call. See
+[`game-state.md`](game-state.md) for the consumer's view.
 
 ## Application lifecycle
 
@@ -104,7 +102,7 @@ and falls back to the gateway-supplied message via
 
 The gateway encodes lobby payloads through `pkg/transcoder/lobby.go`
 into FlatBuffers bytes; the browser must decode them with the same
-schema. Phase 8 ships:
+schema. The TS integration ships:
 
 - `flatbuffers` runtime dependency in `ui/frontend/package.json`;
 - `make -C ui fbs-ts` driving `flatc --ts` to regenerate the bindings
@@ -112,8 +110,6 @@ schema. Phase 8 ships:
 - a Vitest round-trip suite (`tests/lobby-fbs.test.ts`) that catches
   binding drift in CI.
 
-Phase 7's `user.account.get` decode previously used
-`JSON.parse(TextDecoder)`; that path was rewritten in Phase 8 to use
-the same generated `AccountResponse` table, so the lobby greeting now
-works against a real local stack as well as the mocked Playwright
-fixtures.
+`user.account.get` decodes through the generated `AccountResponse`
+table, so the lobby greeting works against a real local stack as well
+as the mocked Playwright fixtures.
diff --git a/ui/docs/navigation.md b/ui/docs/navigation.md
index 0ca04c8..bcc8b98 100644
--- a/ui/docs/navigation.md
+++ b/ui/docs/navigation.md
@@ -18,50 +18,45 @@ two-line wrapper that mounts the matching content component from
 the plan is the file system plus those wrappers — there is no
 separate dispatch component.
 
-| URL                                   | Active view component                          | Phase that fills it     |
-| ------------------------------------- | ---------------------------------------------- | ----------------------- |
-| URL                                        | Active view component                          | Phase that fills it     |
-| ------------------------------------------ | ---------------------------------------------- | ----------------------- |
-| `/games/:id/map`                           | `lib/active-view/map.svelte`                   | Phase 11                |
-| `/games/:id/table/:entity`                 | `lib/active-view/table.svelte`                 | Phase 11 / 17 / 19 / 22 |
-| `/games/:id/report`                        | `lib/active-view/report.svelte` (see [report-view.md](report-view.md)) | Phase 23 |
-| `/games/:id/battle/:battleId?`             | `lib/active-view/battle.svelte`                | Phase 27                |
-| `/games/:id/mail`                          | `lib/active-view/mail.svelte`                  | Phase 28                |
-| `/games/:id/designer/science/:scienceId?`  | `lib/active-view/designer-science.svelte`      | Phase 21                |
+| URL                                        | Active view component                                                  |
+| ------------------------------------------ | ---------------------------------------------------------------------- |
+| `/games/:id/map`                           | `lib/active-view/map.svelte`                                           |
+| `/games/:id/table/:entity`                 | `lib/active-view/table.svelte`                                         |
+| `/games/:id/report`                        | `lib/active-view/report.svelte` (see [report-view.md](report-view.md)) |
+| `/games/:id/battle/:battleId?`             | `lib/active-view/battle.svelte`                                        |
+| `/games/:id/mail`                          | `lib/active-view/mail.svelte`                                          |
+| `/games/:id/designer/science/:scienceId?`  | `lib/active-view/designer-science.svelte`                              |
 
 `/games/:id` (no trailing view) redirects to `/games/:id/map`. The
 optional `:scienceId?` segment on the science designer route matches
 SvelteKit's `[[scienceId]]` syntax — `/designer/science` opens the
 empty new-science form, `/designer/science/{name}` opens the named
-science. Phase 17/18 originally added a parallel ship-class designer
-route; Phase 30 removed it and folded ship-class design into the
-sidebar ship-class calculator (`lib/sidebar/calculator-tab.svelte`,
-see [calculator-ux.md](calculator-ux.md)), reached from the
-ship-classes table and the view/bottom menus.
+science. Ship-class design is folded into the sidebar ship-class
+calculator (`lib/sidebar/calculator-tab.svelte`, see
+[calculator-ux.md](calculator-ux.md)), reached from the ship-classes
+table and the view/bottom menus.
 
 The `entity` slug on the table route is kebab-case (`planets`,
 `ship-classes`, `ship-groups`, `fleets`, `sciences`, `races`).
 `table.svelte` is the active-view router: it dispatches by slug to
-the per-entity component (`ship-classes` → `table-ship-classes.svelte`
-in Phase 17; the others fall back to the Phase 10 stub copy until
-their respective phases land).
+the per-entity component (`ship-classes` → `table-ship-classes.svelte`;
+other entities dispatch to their respective components).
 
 ## Sidebar tools and state preservation
 
 The desktop sidebar hosts three tools:
 
-| Tool       | Component                              | Phase that fills it  |
-| ---------- | -------------------------------------- | -------------------- |
-| Calculator | `lib/sidebar/calculator-tab.svelte`    | Phase 30             |
-| Inspector  | `lib/sidebar/inspector-tab.svelte`     | Phase 13 / 19        |
-| Order      | `lib/sidebar/order-tab.svelte`         | Phase 12 / 14        |
+| Tool       | Component                           |
+| ---------- | ----------------------------------- |
+| Calculator | `lib/sidebar/calculator-tab.svelte` |
+| Inspector  | `lib/sidebar/inspector-tab.svelte`  |
+| Order      | `lib/sidebar/order-tab.svelte`      |
 
 The selected-tab state is a `$state` rune in
 `routes/games/[id]/+layout.svelte`, bound into
 `lib/sidebar/sidebar.svelte` via `$bindable()`. The layout owns the
-rune so external events — Phase 13's planet click, future similar
-flows — can drive the active tab from outside the sidebar without
-plumbing callbacks. The component is mounted by the layout, and
+rune so external events — such as a planet click — can drive the
+active tab from outside the sidebar without plumbing callbacks. The component is mounted by the layout, and
 SvelteKit keeps that layout instance alive while the user navigates
 between child routes (`/games/:id/map` → `/games/:id/report` → …),
 so the rune survives every active-view switch automatically with no
@@ -70,23 +65,21 @@ described below still live inside the sidebar — they mutate the
 bindable in place; the layout sees the change through the binding.
 
 A `?sidebar=calc|calculator|inspector|order` URL param is read once
-on mount and seeds the initial tab. Later phases that want to land
-the user on a particular tool (for example, Phase 14's first
-end-to-end command flow) can set it on navigation.
+on mount and seeds the initial tab. Navigation flows that want to
+land the user on a particular tool can set this param on navigation.
 
 The Order entry is hidden when the layout's `historyMode` flag is
-true. Phase 12 plumbs the flag end-to-end as a prop —
-`+layout.svelte` forwards a derived value to `Sidebar`, which
+true. `+layout.svelte` forwards a derived value to `Sidebar`, which
 forwards `hideOrder` to its `TabBar`; the same flag goes to
 `BottomTabs` so the mobile `Order` button is also suppressed. A
 `?sidebar=order` URL seed that arrives while the flag is true falls
 back to `inspector`, and an `$effect` on the sidebar resets
 `activeTab` away from `order` if the flag flips on mid-session.
 
-Phase 26 wires the flag to the live history signal owned by
-`GameStateStore`. The derivation lives directly in `+layout.svelte`
+The `historyMode` flag is derived from the live history signal owned
+by `GameStateStore`. The derivation lives directly in `+layout.svelte`
 (`const historyMode = $derived(gameState.historyMode)`) — no
-separate `lib/history-mode.ts` module ships, because the layout is
+separate `lib/history-mode.ts` module exists, because the layout is
 the single consumer and the project's compactness rule rejects a
 one-line indirection. The order draft survives the toggle because
 `OrderDraftStore` lives one level above the sidebar in the layout
@@ -100,8 +93,7 @@ for the draft-store side of the flow and
 
 ## Header turn navigator and history banner
 
-The header replaces the Phase 11 inline `turn N` text with a
-`← Turn N →` triplet (`lib/header/turn-navigator.svelte`). The
+The header shows a `← Turn N →` triplet (`lib/header/turn-navigator.svelte`). The
 arrows step `viewedTurn` by ±1 (disabled at boundaries `0` and
 `currentTurn`); clicking the middle button opens an absolute
 popover (desktop) or a fixed full-width drawer (mobile, ≤ 767.98
@@ -129,9 +121,8 @@ Three discrete CSS modes matched to the IA section diagrams:
   toggle in the header right corner. Tapping the toggle slides the
   sidebar in as a fixed overlay above the active view; a close
   button on the sidebar dismisses it. The full swipe-from-right
-  gesture in the IA section is deferred to Phase 35 polish — the
-  click toggle satisfies the "layout switches at 768 px" acceptance
-  criterion on Phase 10.
+  gesture is deferred to the finalization plan
+  ([../PLAN-finalize.md](../PLAN-finalize.md)).
 - **< 768 px (mobile)** — the sidebar is hidden entirely and the
   bottom-tabs row appears at the bottom of the viewport. The
   view-menu trigger swaps to a hamburger icon (☰) that opens the
@@ -139,7 +130,7 @@ Three discrete CSS modes matched to the IA section diagrams:
 
 On mobile the bottom tab row does not include `Inspector`. The
 inspector content is reached by tapping a map object instead, which
-raises a bottom-sheet — see [Planet selection](#planet-selection-phase-13).
+raises a bottom-sheet — see [Planet selection](#planet-selection).
 
 ## Mobile bottom-tabs and tool overlay
 
@@ -157,27 +148,27 @@ The next time the user taps a Calc or Order bottom-tab, the
 navigation re-routes them to `/map` and re-applies the overlay.
 
 The `More` button opens a drawer that mirrors the header view-menu
-content. The IA section's narrower "More" list (Mail, Battle log,
-Tables, History, Settings, Logout) is the polish target for Phase 35
-— Phase 10 keeps a single source of truth for destinations.
+content. A narrower "More" list (Mail, Battle log, Tables, History,
+Settings, Logout) is deferred to the finalization plan
+([../PLAN-finalize.md](../PLAN-finalize.md)); the current drawer keeps
+a single source of truth for destinations.
 
 ## Transient map overlays
 
 Some views can push a transient overlay onto `/map` with a back
-affordance. (Phase 30's calculator reach circles are a simpler,
-always-on map extra rather than a back-stacked overlay; the transient
-back-stack mechanism itself is still a Phase 34 concept.) A transient
-overlay clears when the user navigates to any other view via the header
-or the bottom-tabs.
+affordance. (The calculator reach circles are a simpler, always-on
+map extra rather than a back-stacked overlay; the transient
+back-stack mechanism is planned — see
+[../ROADMAP.md](../ROADMAP.md).) A transient overlay clears when the
+user navigates to any other view via the header or the bottom-tabs.
 
-Phase 10 documents this concept but does not implement the
-back-stack mechanism. Phase 34 lands the back-stack alongside its
-first user (multi-turn projection, range circles in the ship-class
-designer).
+The back-stack mechanism is not yet implemented; it is planned
+alongside its first user (multi-turn projection, range circles in the
+ship-class designer) in [../ROADMAP.md](../ROADMAP.md).
 
-## Planet selection (Phase 13)
+## Planet selection
 
-The map view turns into the entry point for the inspector by
+The map view is the entry point for the inspector by
 translating a renderer click into a planet selection. The flow:
 
 1. The renderer (`src/map/render.ts`) exposes `onClick(cb)` next to
@@ -190,9 +181,9 @@ translating a renderer click into a planet selection. The flow:
    `GameStateStore.report`, and calls `SelectionStore.selectPlanet(number)`.
 3. `SelectionStore` (`lib/selection.svelte.ts`) is a runes store
    instantiated by the layout and exposed via Svelte context under
-   `SELECTION_CONTEXT_KEY`. It carries a discriminated union — Phase
-   13 only models `{ kind: "planet"; id: number }`; Phase 19 widens
-   it for ship groups. Selection is in-memory only: it survives the
+   `SELECTION_CONTEXT_KEY`. It carries a discriminated union —
+   `{ kind: "planet"; id: number }` for planets and widened for
+   ship groups. Selection is in-memory only: it survives the
    layout's lifetime (active-view switches inside `/games/:id/*`)
    but does not persist across reloads — that contrast with the
    order draft is intentional.
@@ -211,11 +202,11 @@ translating a renderer click into a planet selection. The flow:
 
 The mobile bottom-sheet is mounted alongside `<BottomTabs />` in the
 layout. Its visibility is conditional on `effectiveTool === "map"` so
-it does not stack on top of the calc / order overlays. Phase 13 ships
-the minimal dismissal surface: a close button (`✕`) that calls
-`SelectionStore.clear()`. Tap-outside and swipe-down dismissal from
-the IA section are deferred to Phase 35 polish. A click that lands on
-empty space is a no-op — selection is mutated only by an explicit
+it does not stack on top of the calc / order overlays. The dismissal
+surface is a close button (`✕`) that calls `SelectionStore.clear()`.
+Tap-outside and swipe-down dismissal are deferred to the finalization
+plan ([../PLAN-finalize.md](../PLAN-finalize.md)). A click that lands
+on empty space is a no-op — selection is mutated only by an explicit
 planet click or by the close button.
 
 The planet inspector itself is a presentational component: it takes
@@ -227,9 +218,9 @@ field the FBS schema carries (`industryStockpile` for `capital`,
 Fields the FBS table does not project for a given kind read as `null`
 and the inspector simply omits the row.
 
-The selected-planet visual on the map (a ring or halo) is **not**
-shipped in Phase 13. It rolls into Phase 35 polish together with the
-sheet's swipe-to-dismiss gesture.
+The selected-planet visual on the map (a ring or halo) is deferred
+to the finalization plan ([../PLAN-finalize.md](../PLAN-finalize.md))
+together with the sheet's swipe-to-dismiss gesture.
 
 ## Auth gate
 
diff --git a/ui/docs/order-composer.md b/ui/docs/order-composer.md
index 736fa6f..dd46e30 100644
--- a/ui/docs/order-composer.md
+++ b/ui/docs/order-composer.md
@@ -25,29 +25,28 @@ during a connectivity hiccup keeps every line the player typed. A
 remote-first composer that reflects the gateway's pending-orders
 queue would force a sync on every keystroke.
 
-Phase 14 lands the submit pipeline with batch semantics: every
-entry the user has marked `valid` is collected into one signed
-`user.games.order` request. The engine validates and stores the
-order, returning per-command `cmdApplied` / `cmdErrorCode` in the
-response body. The gateway re-encodes that JSON into the FBS
-`UserGamesOrderResponse` envelope (with `commands: [CommandItem]`
-populated), and `submitOrder` rejoins the verdict to each draft
-entry by `cmdId`. Successfully applied entries stay visible in
-the draft (the player keeps composing until turn cutoff);
-rejected entries stay until the player edits or removes them.
+The submit pipeline uses batch semantics: every entry the user has
+marked `valid` is collected into one signed `user.games.order`
+request. The engine validates and stores the order, returning
+per-command `cmdApplied` / `cmdErrorCode` in the response body. The
+gateway re-encodes that JSON into the FBS `UserGamesOrderResponse`
+envelope (with `commands: [CommandItem]` populated), and `submitOrder`
+rejoins the verdict to each draft entry by `cmdId`. Successfully
+applied entries stay visible in the draft (the player keeps composing
+until turn cutoff); rejected entries stay until the player edits or
+removes them.
 
-Phase 25 layers a transport-level policy on top of this baseline
-without changing the batch semantics. The submit pipeline now
-goes through `OrderQueue` (see
-[`sync-protocol.md`](sync-protocol.md)): the queue holds the
-submit while the browser is offline, classifies
-`turn_already_closed` and `game_paused` server replies into
-matching banners on the order tab, and exits the loop on the
-sticky states so a stream of mutations does not re-elicit the
-same gateway reply. Recovery from a `conflict` or `paused`
-banner happens on the next `game.turn.ready` push frame via
-`OrderDraftStore.resetForNewTurn`, which clears the local draft
-and re-hydrates from the server for the new turn.
+A transport-level policy layers on top of the batch baseline without
+changing the batch semantics. The submit pipeline goes through
+`OrderQueue` (see [`sync-protocol.md`](sync-protocol.md)): the queue
+holds the submit while the browser is offline, classifies
+`turn_already_closed` and `game_paused` server replies into matching
+banners on the order tab, and exits the loop on the sticky states so
+a stream of mutations does not re-elicit the same gateway reply.
+Recovery from a `conflict` or `paused` banner happens on the next
+`game.turn.ready` push frame via `OrderDraftStore.resetForNewTurn`,
+which clears the local draft and re-hydrates from the server for the
+new turn.
 
 ## Local-validation invariant
 
@@ -58,10 +57,9 @@ pipeline refuses to drain a draft that contains any `invalid`
 entries. The validation step is per-command and pure — it consults
 the current `GameStateStore` snapshot only, never the network.
 
-Phase 14's `planetRename` is the first variant that exercises the
-`draft → valid | invalid` transition. The validator
-(`lib/util/entity-name.ts`) is a TS port of
-`pkg/util/string.go.ValidateTypeName`, exercised on every render
+The `planetRename` variant exercises the `draft → valid | invalid`
+transition. The validator (`lib/util/entity-name.ts`) is a TS port
+of `pkg/util/string.go.ValidateTypeName`, exercised on every render
 in the inline editor and re-run by the store on every `add`. The
 submit pipeline filters the draft to `valid` entries only — any
 `invalid` row blocks the Submit button.
@@ -79,13 +77,12 @@ draft ──validate──▶ valid ──submit──▶ submitting ──ack
 Transitions:
 
 - **`draft → valid` / `draft → invalid`**: local validation. May
-  re-run when the underlying `GameStateStore` snapshot changes
-  (Phase 14+).
+  re-run when the underlying `GameStateStore` snapshot changes.
 - **`valid → submitting`**: the submit pipeline picks the entry off
   the draft and sends it to the gateway.
 - **`submitting → applied` / `submitting → rejected`**: the gateway
   responded; the entry is no longer in flight.
-- **`submitting → conflict`** (Phase 25): the gateway returned
+- **`submitting → conflict`**: the gateway returned
   `resultCode = "turn_already_closed"`. The order tab surfaces a
   banner above the command list. Any subsequent mutation
   re-validates the conflict row back to `valid` / `invalid`; a
@@ -94,10 +91,10 @@ Transitions:
   [`sync-protocol.md`](sync-protocol.md) for the full state
   table and recovery paths.
 
-Phase 14 lands the local validators (`draft → valid | invalid`),
-the submit pipeline (`valid → submitting → applied | rejected`),
-and the optimistic overlay that shows the player's intent on the
-map and inspector while the order is in flight.
+Local validators (`draft → valid | invalid`), the submit pipeline
+(`valid → submitting → applied | rejected`), and the optimistic
+overlay that shows the player's intent on the map and inspector while
+the order is in flight are all implemented.
 
 Statuses are runtime-only — they are not persisted alongside the
 commands themselves. On every `init` the store re-runs
@@ -110,9 +107,7 @@ stored value).
 
 ## Discriminated union shape
 
-`OrderCommand` is a discriminated union on the `kind` field. Phase
-12 shipped the skeleton with a single content-free variant; Phase
-14 added the first real one and Phase 15 added the second:
+`OrderCommand` is a discriminated union on the `kind` field:
 
 ```ts
 interface PlaceholderCommand {
@@ -148,9 +143,9 @@ The `id` field is the canonical identifier the store uses for
 remove and reorder; later variants must keep `id: string` so the
 store API stays uniform. The whole draft round-trips through
 IndexedDB structured clone, so every variant must use only
-JSON-friendly value types. Phase 14 lands `planetRename` together
-with the inline editor in `lib/inspectors/planet.svelte`, the
-local validator (`lib/util/entity-name.ts`, parity with
+JSON-friendly value types. `planetRename` ships with the inline
+editor in `lib/inspectors/planet.svelte`, the local validator
+(`lib/util/entity-name.ts`, parity with
 `pkg/util/string.go.ValidateTypeName`), and the submit pipeline.
 
 `setProductionType` is the wire-mirror of the engine's
@@ -164,10 +159,10 @@ optimistic overlay rewrites `planet.production` using
 mirrors the engine's `Cache.PlanetProductionDisplayName` so the
 overlay stays byte-equal with the next server report.
 
-### Collapse-by-target rule (Phase 15)
+### Collapse-by-target rule
 
-`setProductionType` is the first variant to carry a
-collapse-by-target rule. `OrderDraftStore.add` enforces it:
+`setProductionType` carries a collapse-by-target rule.
+`OrderDraftStore.add` enforces it:
 when the incoming command's `kind` is `"setProductionType"` it
 drops every prior `setProductionType` entry with the same
 `planetNumber` (and the matching keys from `statuses`) before
@@ -187,9 +182,7 @@ coexist — the rules apply within a `kind`, not across.
 `OrderDraftStore` lives in
 [`../frontend/src/sync/order-draft.svelte.ts`](../frontend/src/sync/order-draft.svelte.ts).
 The class is a Svelte 5 runes store, so the file extension is
-`.svelte.ts` (the original PLAN.md artifact line listed `.ts` —
-the deviation is documented inline in `PLAN.md`'s Phase 12
-"Decisions" subsection).
+`.svelte.ts`.
 
 Lifecycle:
 
@@ -212,9 +205,8 @@ Layout integration mirrors `GameStateStore`:
 - Exposed through the `ORDER_DRAFT_CONTEXT_KEY` Svelte context.
 - Disposed in the layout's `onDestroy`.
 
-The order tab consumes the store via
-`getContext(ORDER_DRAFT_CONTEXT_KEY)`; Phase 14's planet inspector
-will use the same key to push a new command.
+The order tab and the planet inspector both consume the store via
+`getContext(ORDER_DRAFT_CONTEXT_KEY)` to push new commands.
 
 ## Submit pipeline
 
@@ -224,9 +216,9 @@ will use the same key to push a new command.
    `markSubmitting(ids)` so each row reads `submitting`, then
    posts the snapshot through `submitOrder`.
 2. `submitOrder` builds the FBS `UserGamesOrder` request (game_id,
-   `updatedAt = 0` in Phase 14, every command encoded as a
-   `CommandItem` with the typed payload union) and signs it via
-   the existing `executeCommand` orchestration.
+   `updatedAt`, every command encoded as a `CommandItem` with the
+   typed payload union) and signs it via the existing
+   `executeCommand` orchestration.
 3. The engine validates, stores, and answers `202 Accepted` with
    the stored order body — `game_id`, `updatedAt`, plus each
    command echoed with `cmdApplied` and (on rejection)
@@ -252,8 +244,7 @@ in-flight entries back to `valid` so the operator can retry.
 `applyOrderOverlay(report, commands, statuses)` (in
 `api/game-state.ts`) returns a copy of the server `GameReport`
 with every command in `applied` or `submitting` status projected
-on top. Phase 14 understands `planetRename` only; future phases
-extend the switch.
+on top.
 
 The overlay has its own context (`RENDERED_REPORT_CONTEXT_KEY`,
 `lib/rendered-report.svelte.ts`) — the in-game shell layout owns
@@ -288,9 +279,7 @@ Cache row layout:
 | -------------- | ------------------ | ---------------- |
 | `order-drafts` | `{gameId}/draft`   | `OrderCommand[]` |
 
-The store writes the full draft on every mutation. Phase 25 may
-profile the submit pipeline and batch into a microtask if write
-amplification becomes a problem; until then the deterministic
+The store writes the full draft on every mutation. The deterministic
 write-on-every-mutation model is what tests assert and what the
 layout relies on for crash safety.
 
@@ -300,14 +289,12 @@ order composer uses the namespace.
 
 ## History mode wiring
 
-Phase 26 implements history mode: the user can step back through
-past turns and see the report as it was. The IA section specifies
-that the Order tab is hidden when history mode is active — the
-player is browsing an immutable snapshot, and composing commands
+History mode lets the user step back through past turns and see the
+report as it was. The Order tab is hidden when history mode is active
+— the player is browsing an immutable snapshot, and composing commands
 against it would be confusing.
 
-Phase 12 wires the flag end-to-end as a prop. The layout owns the
-flag and passes it to:
+The layout owns the `historyMode` flag and passes it to:
 
 - `Sidebar` as `historyMode`. The sidebar forwards it to its
   `TabBar` as `hideOrder`. The Order entry is filtered out of the
@@ -318,17 +305,16 @@ flag and passes it to:
 - `BottomTabs` as `hideOrder`. The mobile bottom-tab `Order`
   button is suppressed when true.
 
-Phase 26 turns the constant into a derived value driven by
-`GameStateStore.historyMode` (`viewedTurn < currentTurn` while
-`status === "ready"`). The same getter is also passed into
-`OrderDraftStore.bindClient` as `getHistoryMode`, which short-
-circuits the `add` / `remove` / `move` mutations to a no-op while
-the flag is true. This makes every Phase 14–22 inspector affordance
-that calls `orderDraft.add(...)` inert in history mode without
-per-component edits — the gate lives in the one chokepoint that
-all callers go through. The conflict / paused banners and the
-in-flight sync pipeline are untouched: they describe state that
-exists independently of the user's current view.
+`historyMode` is a derived value driven by `GameStateStore.historyMode`
+(`viewedTurn < currentTurn` while `status === "ready"`). The same
+getter is also passed into `OrderDraftStore.bindClient` as
+`getHistoryMode`, which short-circuits the `add` / `remove` / `move`
+mutations to a no-op while the flag is true. This makes every
+inspector affordance that calls `orderDraft.add(...)` inert in history
+mode without per-component edits — the gate lives in the one
+chokepoint that all callers go through. The conflict / paused banners
+and the in-flight sync pipeline are untouched: they describe state
+that exists independently of the user's current view.
 
 The store itself stays alive across history-mode round-trips so
 the draft survives the toggle. The `RenderedReportSource` overlay
@@ -346,13 +332,11 @@ the chrome.
 
 ## Testing
 
-Phase 12 + Phase 14 test artifacts:
-
 - [`../frontend/tests/order-draft.test.ts`](../frontend/tests/order-draft.test.ts)
   — Vitest unit tests for the store. Drives `OrderDraftStore`
   directly with `IDBCache` over `fake-indexeddb`. Covers init,
   add, remove, move, per-game isolation, mutations-before-init,
-  dispose hygiene, the Phase 14 status machine
+  dispose hygiene, the status machine
   (`validate` / `markSubmitting` / `applyResults` /
   `revertSubmittingToValid`), and the
   `hydrateFromServer` cache-miss fallback.
@@ -375,12 +359,12 @@ Phase 12 + Phase 14 test artifacts:
   — Vitest component tests for the rename action and the inline
   editor's local validation.
 - [`../frontend/tests/e2e/order-composer.spec.ts`](../frontend/tests/e2e/order-composer.spec.ts)
-  — Playwright spec for the Phase 12 skeleton (seed three
+  — Playwright spec for the order composer skeleton (seed three
   commands, reload, persistence).
 - [`../frontend/tests/e2e/rename-planet.spec.ts`](../frontend/tests/e2e/rename-planet.spec.ts)
-  — Phase 14 end-to-end: select a planet, rename, submit, observe
-  the overlay-applied name on the inspector + map, reload, and
-  see the rename hydrated from `user.games.order.get`.
+  — End-to-end: select a planet, rename, submit, observe the
+  overlay-applied name on the inspector + map, reload, and see the
+  rename hydrated from `user.games.order.get`.
 
 The `__galaxyDebug.seedOrderDraft(gameId, commands)` and
 `__galaxyDebug.clearOrderDraft(gameId)` helpers in
diff --git a/ui/docs/renderer.md b/ui/docs/renderer.md
index b4e12e6..3e210b2 100644
--- a/ui/docs/renderer.md
+++ b/ui/docs/renderer.md
@@ -25,8 +25,7 @@ UI sits on top of. It must:
 2. Support pan and zoom over a toroidal world (`'torus'` mode) and
    over a bounded plane (`'no-wrap'` mode), both first-class.
 3. Run the same algorithm on web, Wails, Capacitor, and PWA
-   targets — only the browser is supported in Phase 9, but no API
-   in this module assumes the platform.
+   targets — no API in this module assumes the platform.
 4. Provide deterministic hit-test for cursor-to-primitive mapping,
    with results that are unit-testable independently of Pixi.
 
@@ -76,11 +75,11 @@ overrides them.
 
 ## Theme
 
-A single dark theme ships in Phase 9. The theme is a record of
-default colours; primitives whose `style` omits a colour fall back
-to the theme. Runtime theme switching is not implemented — Phase
-35 introduces light/dark and the materialise-on-theme-change
-cycle.
+A single dark theme is implemented. The theme is a record of default
+colours; primitives whose `style` omits a colour fall back to the
+theme. Runtime theme switching is not implemented — light/dark and
+the materialise-on-theme-change cycle are deferred to the
+finalization plan ([../PLAN-finalize.md](../PLAN-finalize.md)).
 
 ## Hit-test
 
@@ -134,7 +133,7 @@ Per-primitive distance:
   representation: from `(x1, y1)` to `(x1 + dx, y1 + dy)` where
   `(dx, dy)` is the torus-shortest delta from end-1 to end-2.
 
-The brute-force `O(N)` walk is fine for the Phase 9 target of
+The brute-force `O(N)` walk is fine for the current target of
 ~1000 primitives on every pointer event. Spatial indexing is
 deferred until profiling proves it necessary; PixiJS' culling and
 batching handle the draw side without help.
@@ -260,10 +259,10 @@ average frame time over a scripted drag.
 
 ## Pick mode
 
-Phase 16 introduced a generic *map-driven destination pick* the
-inspector uses for cargo routes and that ship-group dispatch
-(Phase 19/20) will reuse. The renderer owns the visual lifecycle;
-the Svelte side wraps it in a promise-shaped service.
+The renderer provides a generic *map-driven destination pick* that
+the inspector uses for cargo routes and ship-group dispatch. The
+renderer owns the visual lifecycle; the Svelte side wraps it in a
+promise-shaped service.
 
 Lifecycle (`RendererHandle.setPickMode(opts)`):
 
@@ -321,17 +320,17 @@ freshly-pushed extras layer (cargo-route overlay, pending-Send
 tracks) does not silently un-hide a primitive whose id is in the
 current set.
 
-The Phase 29 map view (`src/lib/active-view/map.svelte`) computes
-the set from the per-game `MapToggles` rune + the planet-cascade
-rule and pushes it on every effect run; toggling a checkbox
-flips visibility within one frame without a Pixi remount.
+The map view (`src/lib/active-view/map.svelte`) computes the set
+from the per-game `MapToggles` rune + the planet-cascade rule and
+pushes it on every effect run; toggling a checkbox flips visibility
+within one frame without a Pixi remount.
 
 ## Visible-hyperspace overlay (the "fog")
 
 `RendererHandle.setVisibilityFog(circles)` draws (or removes) the
-Phase 29 fog overlay used to highlight the player's visible
-hyperspace. Each entry describes a circle around a LOCAL planet
-where the player has scanner / visibility coverage:
+fog overlay that highlights the player's visible hyperspace. Each
+entry describes a circle around a LOCAL planet where the player has
+scanner / visibility coverage:
 
 - An empty list destroys the existing fog rectangles and mask.
 - A non-empty list rebuilds a single viewport-level `fogLayer` (a
@@ -381,14 +380,14 @@ pixels:
 - `getMapPrimitives()` returns a snapshot of every primitive in
   the active world: id, kind, priority, current alpha
   (post-overlay), the explicit fill / stroke colour from its
-  `Style` (no theme fallback), and the Phase 29 `visible` flag
-  mirroring the renderer's hide set.
+  `Style` (no theme fallback), and the `visible` flag mirroring the
+  renderer's hide set.
 - `getMapPickState()` returns `{ active, sourcePlanetNumber,
   reachableIds, hoveredId }` — the renderer's view of the
   current pick session.
 - `getMapCamera()` returns the current camera + viewport +
-  canvas-origin snapshot, used by Phase 29 e2e specs to assert
-  camera preservation across wrap-mode flips.
+  canvas-origin snapshot, used by e2e specs to assert camera
+  preservation across wrap-mode flips.
 - `getMapFog()` returns the most recent fog input
   (the list of circles last passed to `setVisibilityFog`).
   Empty when the `visibleHyperspace` toggle is off.
diff --git a/ui/docs/report-view.md b/ui/docs/report-view.md
index 6ee99ef..fbc682e 100644
--- a/ui/docs/report-view.md
+++ b/ui/docs/report-view.md
@@ -1,9 +1,9 @@
-# Report view — Phase 23
+# Report view
 
-The Phase 23 in-game "turn report" view is a single scrollable
-layout with twenty sections, one per array on the FBS `Report`
-table. The route file is the standard two-line wrapper; the
-orchestrator and the per-section components live under
+The in-game "turn report" view is a single scrollable layout with
+twenty sections, one per array on the FBS `Report` table. The route
+file is the standard two-line wrapper; the orchestrator and the
+per-section components live under
 `ui/frontend/src/lib/active-view/report/`.
 
 ## Component layout
@@ -140,7 +140,7 @@ highlight consistent without a second source of truth.
 
 ## i18n namespace
 
-All Phase 23 strings live under `game.report.*`:
+All strings live under `game.report.*`:
 - `game.report.loading` — section loading placeholder.
 - `game.report.back_to_map`, `game.report.toc.title`,
   `game.report.toc.mobile_label` — shell-level strings.
diff --git a/ui/docs/science-designer-ux.md b/ui/docs/science-designer-ux.md
index bc0417b..afd83c9 100644
--- a/ui/docs/science-designer-ux.md
+++ b/ui/docs/science-designer-ux.md
@@ -6,9 +6,9 @@ planet's production is set to a science, the planet's industry
 output for that turn is split between the four tech research tracks
 in those proportions
 (`game/internal/controller/planet/production.go.runScienceResearch`).
-Phase 21 lights up the CRUD list, the designer, and the
-production-picker integration. The wire and the engine validation
-are unchanged from earlier phases — only the UI is new.
+The CRUD list, the designer, and the production-picker integration
+are provided by the UI; the wire and engine validation are handled
+by the backend.
 
 ## Engine semantics in one paragraph
 
@@ -41,12 +41,12 @@ from `100`, and the form's Save button stays disabled until the sum
 matches. A live readout under the inputs displays the running total
 so the player can chase it down without trial-and-error guessing.
 
-The strict-sum gate is a Phase 21 decision (alternatives —
-auto-rebalance, raw-parts-with-engine-normalisation — were
-considered and rejected): keeping the input model close to "what
-gets sent on the wire" minimises surprises when the engine returns
-the science exactly as typed. See `lib/util/science-validation.ts`
-for the validator and the conversion helper.
+The strict-sum gate was chosen over alternatives — auto-rebalance
+and raw-parts-with-engine-normalisation — because keeping the input
+model close to "what gets sent on the wire" minimises surprises when
+the engine returns the science exactly as typed. See
+`lib/util/science-validation.ts` for the validator and the
+conversion helper.
 
 ## Name validation
 
diff --git a/ui/docs/ship-group-actions.md b/ui/docs/ship-group-actions.md
index dabfae6..51b877b 100644
--- a/ui/docs/ship-group-actions.md
+++ b/ui/docs/ship-group-actions.md
@@ -1,7 +1,7 @@
 # Ship-group inspector actions
 
-Phase 20 turns the read-only ship-group inspector
-(`ui/frontend/src/lib/inspectors/ship-group.svelte`) into an
+The ship-group inspector
+(`ui/frontend/src/lib/inspectors/ship-group.svelte`) is an
 interactive command source for the player's own groups in orbit.
 This document is the running spec for the actions panel
 (`ui/frontend/src/lib/inspectors/ship-group/actions.svelte`):
@@ -151,9 +151,8 @@ count. Block masses come from the player's
 - Drive / shields / cargo block mass = the corresponding ship-
   class field (raw value).
 - Weapons block mass = `core.weaponsBlockMass({ weapons,
-  armament })` (Phase 18 bridge); returns null on the invalid
-  weapons/armament pairing, in which case the row contributes
-  zero.
+  armament })`; returns null on the invalid weapons/armament
+  pairing, in which case the row contributes zero.
 
 For `tech === "ALL"` every block whose mass is non-zero
 contributes against the player's race tech as the target. For
@@ -182,21 +181,18 @@ Per-action additional fields are documented on the
 `ui/frontend/src/sync/order-types.ts` next to the JSDoc for each
 variant.
 
-## Decisions baked into Phase 20
+## Design notes
 
-- **`BlockUpgradeCost` migrated to `pkg/calc`**. The cost
-  formula previously lived in
-  `game/internal/controller/ship_group_upgrade.go`. To keep the
-  `ui/core/calc` bridge a wrapper around pure `pkg/calc/`
-  formulas, the function moved to `pkg/calc/ship.go` and the
-  controller now imports it (`controller/ship_group_upgrade.go`).
+- **`BlockUpgradeCost` lives in `pkg/calc`**. The cost formula
+  lives in `pkg/calc/ship.go`; the `ui/core/calc` bridge wraps
+  pure `pkg/calc/` formulas, and the controller imports it
+  (`controller/ship_group_upgrade.go`).
 - **`GameReport.otherRaces`**. The transfer-to-race picker reads
-  from a new `GameReport.otherRaces: string[]` field, populated
-  by walking `report.player[]` and excluding the local race plus
-  every `extinct` entry. Phase 22 (Races View) reuses the same
-  field.
+  from `GameReport.otherRaces: string[]`, populated by walking
+  `report.player[]` and excluding the local race plus every
+  `extinct` entry. The Races View reuses the same field.
 - **Stationed-ship rows are clickable**. The map deliberately
   hides on-planet groups; the planet inspector's stationed-ship
-  rows now pivot the selection to the corresponding ship-group
+  rows pivot the selection to the corresponding ship-group
   variant so the actions panel is reachable from the standard
   click flow.
diff --git a/ui/docs/storage.md b/ui/docs/storage.md
index 89396a9..8180a0e 100644
--- a/ui/docs/storage.md
+++ b/ui/docs/storage.md
@@ -15,8 +15,9 @@ namespace.
 This topic doc covers the web implementation only. The platform-
 agnostic `KeyStore` and `Cache` interfaces in
 `src/platform/store/index.ts` are what the rest of the client codes
-against; later phases bring `WailsStore` and `CapacitorStore` adapters
-that satisfy the same contracts.
+against; `WailsStore` and `CapacitorStore` adapters will satisfy the
+same contracts on their respective platforms (see
+[../ROADMAP.md](../ROADMAP.md)).
 
 Source-of-truth for the cross-service contract is
 [`../../docs/ARCHITECTURE.md` §15 "Transport security model"](../../docs/ARCHITECTURE.md);
@@ -38,13 +39,12 @@ recently:
 
 Browsers older than the baseline above will fail at the first
 `generateKey({ name: 'Ed25519' }, ...)` call with a
-`NotSupportedError`. Phase 6 deliberately does not ship a JavaScript
-fallback (e.g. `@noble/ed25519`) — keeping the keystore on WebCrypto
-is what gives us non-extractable storage on every supported engine.
-The Phase 7 root layout runs a one-time probe on boot and switches
-to a "browser not supported" page (described in
-[`auth-flow.md`](auth-flow.md)) when the probe rejects, instead of
-attempting the keystore generate.
+`NotSupportedError`. No JavaScript fallback (e.g. `@noble/ed25519`)
+is shipped — keeping the keystore on WebCrypto is what gives
+non-extractable storage on every supported engine. The root layout
+runs a one-time probe on boot and switches to a "browser not
+supported" page (described in [`auth-flow.md`](auth-flow.md)) when
+the probe rejects, instead of attempting the keystore generate.
 
 ### WebKit non-determinism note
 
@@ -60,8 +60,9 @@ is missing.
 
 Tests that assert "the same key signs the same message identically"
 must either pin to the Vitest path (Node WebCrypto) or be replaced
-with verify-after-sign assertions. The Phase 6 Playwright spec uses
-the verify path, which works on every engine in the baseline.
+with verify-after-sign assertions. The Playwright spec for the
+keystore uses the verify path, which works on every engine in the
+baseline.
 
 ## IndexedDB schema
 
@@ -112,14 +113,14 @@ wipes every namespace.
 
 Namespaces in current use:
 
-| Namespace          | Key                            | Value type                                    | Owner                              |
-|--------------------|--------------------------------|-----------------------------------------------|------------------------------------|
-| `session`          | `device-session-id`            | `string`                                      | Phase 7+                           |
-| `game-prefs`       | `{gameId}/wrap-mode`           | `WrapMode`                                    | Phase 11+ (`game-state.md`)        |
-| `game-prefs`       | `{gameId}/last-viewed-turn`    | `number`                                      | Phase 11+ (`game-state.md`)        |
-| `order-drafts`     | `{gameId}/draft`               | `OrderCommand[]`                              | Phase 12+ (`order-composer.md`)    |
-| `game-history`     | `{gameId}/turn/{N}`            | `GameReport`                                  | Phase 26+ (`game-state.md`)        |
-| `game-map-toggles` | `{gameId}`                     | `{toggles: MapToggles; lastResetTurn: number}` | Phase 29+ (`game-state.md`)        |
+| Namespace          | Key                            | Value type                                     | Owner                    |
+|--------------------|--------------------------------|------------------------------------------------|--------------------------|
+| `session`          | `device-session-id`            | `string`                                       | `auth-flow.md`           |
+| `game-prefs`       | `{gameId}/wrap-mode`           | `WrapMode`                                     | `game-state.md`          |
+| `game-prefs`       | `{gameId}/last-viewed-turn`    | `number`                                       | `game-state.md`          |
+| `order-drafts`     | `{gameId}/draft`               | `OrderCommand[]`                               | `order-composer.md`      |
+| `game-history`     | `{gameId}/turn/{N}`            | `GameReport`                                   | `game-state.md`          |
+| `game-map-toggles` | `{gameId}`                     | `{toggles: MapToggles; lastResetTurn: number}` | `game-state.md`          |
 
 The `game-map-toggles` blob stores the gear popover's per-game
 visibility state plus a `lastResetTurn` companion field. Reading
@@ -131,10 +132,10 @@ whenever `lastResetTurn < currentTurn`, so a fresh server turn
 always greets the player with every map category visible (see
 `game-state.md` for the new-turn-reset contract).
 
-Later phases will add more per-feature namespaces (fixtures, lobby
-snapshot, etc.). The contract is namespace-strings stay scoped to
-one feature; cross-feature reads through the cache are by convention
-disallowed.
+Additional per-feature namespaces will be added as needed (fixtures,
+lobby snapshot, etc.). The contract is namespace-strings stay scoped
+to one feature; cross-feature reads through the cache are by
+convention disallowed.
 
 ## Keystore lifecycle
 
@@ -176,9 +177,8 @@ Thin orchestration layer over `KeyStore` + `Cache`:
 - `loadDeviceSession(keyStore, cache)` returns
   `{ keypair, deviceSessionId }`. The `keypair` field is always
   populated (loaded if present, freshly generated if not). The
-  `deviceSessionId` field is `null` until Phase 7's
-  `confirm-email-code` handler stores the gateway-issued id via
-  `setDeviceSessionId`.
+  `deviceSessionId` field is `null` until the `confirm-email-code`
+  handler stores the gateway-issued id via `setDeviceSessionId`.
 - `setDeviceSessionId(cache, id)` writes the id to the `session`
   namespace.
 - `clearDeviceSession(keyStore, cache)` wipes both the keypair and
@@ -186,7 +186,7 @@ Thin orchestration layer over `KeyStore` + `Cache`:
   push-event-driven revocation path.
 
 A `null` `deviceSessionId` is the signal that the session is
-unauthenticated — Phase 7 routes such users to `/login`.
+unauthenticated — the root layout routes such users to `/login`.
 
 ## Test layout
 
@@ -211,7 +211,8 @@ the debug entry point never attaches `window.__galaxyDebug`.
 
 ## Future: native targets
 
-Phase 31 (Wails) and Phase 32 (Capacitor) bring native keystores —
+Native desktop and mobile targets (planned in
+[../ROADMAP.md](../ROADMAP.md)) will bring native keystores —
 Keychain on macOS / iOS, DPAPI/Credential Locker on Windows,
 libsecret on Linux, Android Keystore on Android — behind the same
 `KeyStore` interface, plus SQLite-backed `Cache` adapters. The web
diff --git a/ui/docs/sync-protocol.md b/ui/docs/sync-protocol.md
index a1fc22e..20ef17b 100644
--- a/ui/docs/sync-protocol.md
+++ b/ui/docs/sync-protocol.md
@@ -1,11 +1,10 @@
 # UI sync protocol
 
-Phase 25 wires the transport-level policy that keeps the local
-order draft consistent with the gateway across two failure modes
-that Phase 14 punted on: transient network outages and turn
-cutoffs the player did not anticipate. The wiring also reacts to
-admin-initiated game pauses signalled by the new `game.paused`
-push event.
+The transport-level policy keeps the local order draft consistent
+with the gateway across two failure modes: transient network
+outages and turn cutoffs the player did not anticipate. The wiring
+also reacts to admin-initiated game pauses signalled by the
+`game.paused` push event.
 
 The contract lives at three layers:
 
@@ -210,8 +209,7 @@ state machine deterministically.
   status flip on the lobby side without an explicit push event.
   The UI relies on the next `game.turn.ready` for recovery; a
   dedicated `game.resumed` event would let the banner clear
-  immediately without waiting for the next cron tick. Not part
-  of this phase.
+  immediately without waiting for the next cron tick.
 - The conflict banner shows the player-facing template
   unmodified; a future revision may interpolate the explicit
   cutoff timestamp once the server adds it to the error body.
diff --git a/ui/docs/testing.md b/ui/docs/testing.md
index 396b4ac..824db36 100644
--- a/ui/docs/testing.md
+++ b/ui/docs/testing.md
@@ -2,8 +2,7 @@
 
 UI client test toolchain. Project-wide testing layers (service /
 inter-service / system) live in [`../../docs/TESTING.md`](../../docs/TESTING.md);
-this doc only covers the UI-specific tiers added in Phase 2 of
-[`../PLAN.md`](../PLAN.md).
+this doc covers the UI-specific tiers.
 
 ## Tier 1 — per-PR
 
@@ -45,17 +44,18 @@ as Gitea Actions artefacts (`playwright-report` and `playwright-traces`,
 
 Triggered by `.gitea/workflows/ui-release.yaml` on tag push (`v*`).
 Currently mirrors the Tier 1 step set; the dedicated release-only
-checks land in later phases:
+checks are deferred:
 
-- **Visual regression baseline check** — Phase 33. Snapshots live in
+- **Visual regression baseline check** — deferred to the
+  finalization plan (../Plan-finalize.md). Snapshots will live in
   `ui/frontend/tests/__snapshots__/` until the project shifts to
   Argos or another visual-diff service.
-- **iOS smoke (Capacitor + Appium)** — Phase 32. Runs on a `macos-13`
-  runner once the Capacitor mobile wrapper exists.
+- **iOS smoke (Capacitor + Appium)** — planned (see ../ROADMAP.md).
+  Runs on a `macos-13` runner once the Capacitor mobile wrapper
+  exists.
 
 Both blocks are present as commented sections in
-`.gitea/workflows/ui-release.yaml` with the phase number that
-re-enables them.
+`.gitea/workflows/ui-release.yaml`.
 
 ## Local execution
 
@@ -150,8 +150,7 @@ In synthetic mode:
   same synthetic id afterwards redirects to /lobby. Re-load the JSON
   to reseed.
 
-The synthetic-report parity rule (see [`../PLAN.md`](../PLAN.md) §
-Assumptions and Defaults) requires every UI phase that extends
+The synthetic-report parity rule requires every change that extends
 `decodeReport` to also extend the legacy parser in lockstep, or to
 record in the parser's `README.md` that the new field cannot be
 derived from legacy text. This keeps the synthetic-mode coverage in
diff --git a/ui/docs/wasm-toolchain.md b/ui/docs/wasm-toolchain.md
index 3ce0d35..d8fa4f4 100644
--- a/ui/docs/wasm-toolchain.md
+++ b/ui/docs/wasm-toolchain.md
@@ -13,10 +13,10 @@ keystore — see [`storage.md`](storage.md) for the web implementation
 
 Two viable Go-to-WASM toolchains exist:
 
-| Toolchain     | Bundle size (Phase 5)              | Notes                                      |
+| Toolchain     | Bundle size                        | Notes                                      |
 |---------------|------------------------------------|--------------------------------------------|
-| **TinyGo**    | ~903 KB (under 1 MB acceptance bar) | LLVM-based, no full GC, fast cold-start    |
-| Standard Go   | ~2 MB (`GOOS=js GOARCH=wasm`)       | Drops in without extra tooling             |
+| **TinyGo**    | ~903 KB (under 1 MB target)        | LLVM-based, no full GC, fast cold-start    |
+| Standard Go   | ~2 MB (`GOOS=js GOARCH=wasm`)      | Drops in without extra tooling             |
 
 `ui/core` was written under the TinyGo invariants documented in
 `ui/core/README.md` (no `crypto/x509`, no `encoding/pem`, no
@@ -108,7 +108,7 @@ TinyGo being installed in every environment.
 
 | Build        | Date       | Size  |
 |--------------|------------|-------|
-| Phase 5 land | 2026-05-07 | 903 KB |
+| Initial land | 2026-05-07 | 903 KB |
 
 If the artefact ever crosses the 1 MB target, profile via
 `tinygo build -size full` and trim before committing.