From 04bc8d96ff9a91448628a78c3e6ef8aeaf5fa8db Mon Sep 17 00:00:00 2001
From: Matei <tools@matei.work>
Date: Mon, 8 Jun 2026 15:55:08 -0400
Subject: [PATCH 1/5] =?UTF-8?q?docs(mapgen-studio):=20redesign=20workstrea?=
 =?UTF-8?q?m=20=E2=80=94=20frame,=20research,=20audit,=20target=20architec?=
 =?UTF-8?q?ture?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Open the MapGen Studio redesign initiative: a top-1%, data-driven React 19 rebuild
that decomposes the 3,010-line App.tsx, introduces a native effect-orpc server on
Bun, oRPC-native TanStack Query + Zustand on the client, and full canonical
shadcn/ui + Tailwind v4 — with behavior parity for map-gen, Deck.gl, recipes, and
the live-game control loop.

Artifacts:
- 00-GOAL.md — framed objective, user decisions, falsifier, parity hard core
- research/01-orpc-effect-bun.md, research/02-orpc-tanstack-zustand.md
- audit/03-component-architecture, 04-design-system, 05-server-contracts, 06-typescript-rigor
- architecture/10-target-architecture.md, 11-slice-plan.md
- apps/mapgen-studio/system.md — extracted current design language

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/mapgen-studio/system.md                  | 124 ++++
 .../mapgen-studio-redesign/00-GOAL.md         |  91 +++
 .../architecture/10-target-architecture.md    | 149 +++++
 .../architecture/11-slice-plan.md             |  93 +++
 .../audit/03-component-architecture.md        | 322 +++++++++++
 .../audit/04-design-system.md                 | 230 ++++++++
 .../audit/05-server-contracts.md              | 158 +++++
 .../audit/06-typescript-rigor.md              | 144 +++++
 .../research/01-orpc-effect-bun.md            | 509 ++++++++++++++++
 .../research/02-orpc-tanstack-zustand.md      | 545 ++++++++++++++++++
 10 files changed, 2365 insertions(+)
 create mode 100644 apps/mapgen-studio/system.md
 create mode 100644 docs/projects/mapgen-studio-redesign/00-GOAL.md
 create mode 100644 docs/projects/mapgen-studio-redesign/architecture/10-target-architecture.md
 create mode 100644 docs/projects/mapgen-studio-redesign/architecture/11-slice-plan.md
 create mode 100644 docs/projects/mapgen-studio-redesign/audit/03-component-architecture.md
 create mode 100644 docs/projects/mapgen-studio-redesign/audit/04-design-system.md
 create mode 100644 docs/projects/mapgen-studio-redesign/audit/05-server-contracts.md
 create mode 100644 docs/projects/mapgen-studio-redesign/audit/06-typescript-rigor.md
 create mode 100644 docs/projects/mapgen-studio-redesign/research/01-orpc-effect-bun.md
 create mode 100644 docs/projects/mapgen-studio-redesign/research/02-orpc-tanstack-zustand.md

diff --git a/apps/mapgen-studio/system.md b/apps/mapgen-studio/system.md
new file mode 100644
index 0000000000..83a714e6e5
--- /dev/null
+++ b/apps/mapgen-studio/system.md
@@ -0,0 +1,124 @@
+# mapgen-studio — Design System (extracted)
+
+> Extracted from the current codebase (`src/**/*.tsx`, `src/index.css`, `tailwind.config.js`, `src/ui/hooks/useTheme.ts`) on 2026-06-08.
+> This captures the **current** design language as-built. It is the baseline the shadcn migration must preserve (density, dark-first palette, border-only depth) while formalizing tokens.
+
+## 1. Design DNA
+
+A **dense, dark-first developer tool**. Think pro audio / DAW / data-explorer, not a marketing app. Information density is the point: micro-typography (10–11px), tight 4px spacing rhythm, hairline borders instead of shadows, and a restrained near-monochrome palette with a single cool accent. Map visualization (deck.gl) is the hero; chrome recedes.
+
+- **Mood**: technical, quiet, high-density, focused.
+- **Hierarchy mechanism**: borders + background-tier shifts (not shadow, not color).
+- **Personality risk today**: reads as *commodity dark dashboard* — defaults dominate (gray accent, flat focus rings, no motion). The craft work is to make density feel *intentional*, not cramped.
+
+## 2. Color
+
+Two hand-maintained palettes (`light` / `dark`) live in **three** places that disagree (see audit): `tailwind.config.js`, `src/index.css` CSS vars, and `src/ui/hooks/useTheme.ts`. The values below are the de-facto source of truth (`useTheme.ts`, matched by hardcoded hex frequency in components).
+
+### Dark (primary — app defaults to dark)
+| Role | Value | Notes |
+|---|---|---|
+| bg / page | `#0a0a0f` | deck.gl backdrop tint |
+| bg / panel | `#141418` | cards, headers |
+| bg / panel-alt | `#111114` | |
+| bg / nested | `#0f0f12` | inputs, nested cards |
+| bg / hover | `#1a1a1f` | |
+| bg / active | `#222228` | secondary buttons, tags |
+| border / default | `#2a2a32` | **the workhorse hairline** (31 uses) |
+| border / subtle | `#222228` | dividers (20 uses) |
+| border / strong | `#3a3a44` | input focus border (14 uses) |
+| text / primary | `#e8e8ed` | (36 uses — most frequent hex) |
+| text / secondary | `#8a8a96` | labels (19 uses) |
+| text / muted | `#5a5a66` | placeholders, help (14 uses) |
+| accent / interactive | `#4b5563` | primary button, switch-on, active tag (19 uses) |
+| accent (system var) | `#5e5ce6` | indigo — declared in CSS but **barely used** |
+
+### Light
+| Role | Value |
+|---|---|
+| bg / page | `#f5f5f7` |
+| bg / panel | `#ffffff` |
+| border / default | `#e5e7eb` / `#e5e5e5` (drifts) |
+| text / primary | `#1f2937` (26 uses) |
+| text / secondary | `#6b7280` (17 uses) |
+| accent | `#4b5563` |
+
+### Semantic / status
+- error/destructive: `text-rose-400`, `bg-red-500`, `text-red-600` (inconsistent — rose vs red).
+- success: `text-emerald-500`. info: `text-blue-500`.
+
+**Observation:** the *declared* accent (`#5e5ce6` indigo) is not the *used* accent (`#4b5563` slate). The brand is effectively neutral-slate. This is the single biggest "commodity" tell.
+
+## 3. Typography
+
+- **Sans**: Inter (400/500/600/700). **Mono**: JetBrains Mono. Both via Google Fonts `@import` in `index.css` (render-blocking — flag).
+- **Scale (actual, by frequency):**
+  | Token | Size | Uses | Role |
+  |---|---|---|---|
+  | — | **11px** | 44 | body / field text / values (the default) |
+  | — | **10px** | 38 | labels, uppercase eyebrows, captions |
+  | — | 12px | 7 | section subtitles |
+  | — | 13px | 4 | |
+  | text-sm (14px) | 14 | 4 | dialog titles |
+  | — | 9px | 3 | dense badges |
+- **Weights**: `font-medium` (28), `font-semibold` (14). No bold in UI chrome.
+- **Pattern**: uppercase + `tracking-wider` + 10px for eyebrow labels (e.g. AppHeader "Config", "Resources").
+- **Type is set in arbitrary `text-[11px]` values**, not a named scale — every size is ad-hoc.
+
+## 4. Spacing
+
+- **Base unit: 4px.** Rhythm is tight.
+- Scale by frequency: `gap-2`(8px, 47×) ≫ `px-3`(12px, 27×) > `py-2`(8px, 14×) > `gap-1`(4px, 13×) > `gap-1.5`(6px) > `py-2.5`(10px) > `p-2`/`p-2.5`(8/10px).
+- **Effective scale: 4, 6, 8, 10, 12, 16 px.** Above 16px is rare (panel padding only).
+- Field rows: `py-1` (4px) vertical, `gap-3` label↔input. Cards: `p-2.5` (10px). Nested cards: `p-2` (8px).
+
+## 5. Radius
+
+- `rounded` (4px, 28×) = default for inputs/buttons/tags.
+- `rounded-lg` (8px, 15×) = cards, dialogs, dropdowns, toasts.
+- `rounded-full` (8×) = pill tags, switch track.
+- `rounded-md` (6px, 2×) = rare/inconsistent.
+- **Effective scale: 4 / 8 / full.** (6px and config's `xl`/`2xl` are noise.)
+
+## 6. Depth
+
+- **Border-only.** 148 border utilities vs **7** shadows. Shadows appear only on floating layers (dialog `shadow-xl`, toast `shadow-lg`, dropdown `shadow-lg`).
+- Tiering by **background lightness step** (page → panel → nested) + 1px hairline. This is the core depth language.
+- `backdrop-blur-sm` (11×) on the floating header/setup bar — glassy chrome over the map.
+
+## 7. Motion
+
+- **Minimal.** `transition-colors` (29×) is ~all of it; `transition-transform` (5×) for chevron rotation; one `animate-pulse-subtle` (2s) for running state.
+- Durations: 150ms (fast) / 200ms (normal), declared as CSS vars but mostly implicit Tailwind defaults.
+- `animate-in fade-in-0 zoom-in-95` strings appear on dialog/toast/tooltip **but no `tailwindcss-animate` plugin is installed** — these classes are dead (no keyframes). Motion is effectively absent on overlays.
+
+## 8. Component patterns
+
+| Pattern | Spec (as-built) |
+|---|---|
+| **Button** | h-8 default / h-7 sm / h-7 icon; `px-3`; `rounded`; `text-sm`/`text-xs`; variants default(slate)/outline/secondary/ghost/link/destructive; CVA-driven. Focus ring `ring-1 ring-gray-400`. |
+| **Input / Textarea / Select** | h-7; `text-[11px]`; `px-2.5`; `rounded`; 1px border; focus = border color shift + `ring-1`. Native `<select>` with custom chevron. |
+| **Switch** | 36×20 track, 16px thumb, `rounded-full`, peer-checked slides; on = `#4b5563`. |
+| **Checkbox** | 16px, `rounded`, Check icon on check. |
+| **Field row** | `flex justify-between gap-3 py-1`; label `text-[11px] min-w-[96px]` secondary color, input flex-1. |
+| **Card (stage section)** | `rounded-lg border p-2.5`, header (semibold) + `border-t` divider + content. |
+| **Nested card / array item** | `rounded-md border p-2`, deeper bg tier. |
+| **Tag / pill** | `rounded-full border px-2 py-1 text-[11px]`, active = slate fill. |
+| **Dropdown menu** | hand-rolled: trigger button + `fixed inset-0` click-catcher + absolutely-positioned `rounded-lg border shadow-lg` list of `text-[11px]` rows. |
+| **Dialog** | hand-rolled overlay `bg-black/50` + centered `max-w-[320px] rounded-lg border p-5 shadow-xl`. |
+| **Toast** | bottom-center stack, `rounded-lg border shadow-lg`, icon + 12px message + dismiss. |
+| **Eyebrow label** | uppercase, `tracking-wider`, 10px, muted. |
+
+## 9. Theming mechanism (as-built — flag)
+
+- Dark mode is delivered by a **`lightMode` boolean prop threaded through 24 files** + a `Theme` object from `createTheme()`, NOT by Tailwind `dark:` variants.
+- Tailwind `darkMode` is unset → defaults to `media` (`prefers-color-scheme`). So `dark:` utilities (13 scattered uses) and the `lightMode` prop **fight each other**; a user who picks "light" while their OS is dark gets mixed results.
+- `createTheme()` builds classes via **runtime string interpolation** (`` `bg-[${p.bg.page}]` ``) — Tailwind JIT cannot see these, so most of those classes never get generated. (See audit; this is a real bug, not just smell.)
+
+## 10. Target north star (for the redesign)
+
+Keep the DNA — dense, dark-first, border-tiered, micro-type, single accent — but:
+1. Make the accent **intentional** (commit to indigo `#5e5ce6` or a deliberate slate; stop declaring one and using another).
+2. Formalize the 11/10px type, 4px spacing, 4/8 radius, border-tier depth as **named tokens** (shadcn HSL CSS vars + `@theme`).
+3. Replace `lightMode`-prop theming with shadcn's `.dark` class strategy (single switch, no prop drilling).
+4. Add real overlay motion (`tailwindcss-animate` / tw-v4 `tw-animate-css`) so dialogs/toasts/dropdowns animate as the dead `animate-in` classes intended.
diff --git a/docs/projects/mapgen-studio-redesign/00-GOAL.md b/docs/projects/mapgen-studio-redesign/00-GOAL.md
new file mode 100644
index 0000000000..9c33021bcb
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/00-GOAL.md
@@ -0,0 +1,91 @@
+# MapGen Studio Redesign — Active Goal & Frame
+
+> Controlling scope for the systematic workstream. This is the closure test:
+> work is done when this objective is met and its falsifier has not fired.
+
+## Active goal
+
+Transform `apps/mapgen-studio` from a 3,010-line god-component (`App.tsx`) into a
+top-1%, data-driven React 19 application: decomposed component architecture, real
+state/server-data boundaries, a documented shadcn(Radix)+Tailwind design system,
+accessibility + interaction craft, and comments/organization that read as
+intentional — **without changing** map-generation, Deck.gl rendering, recipe
+semantics, or live-game runtime behavior. Behavior parity is hard core.
+
+## User-confirmed decisions
+
+- **Design system:** adopt **full canonical shadcn/ui** (`components.json` + Radix),
+  replacing the hand-rolled primitives; formalize tokens + `system.md` via the
+  `design:*` skills. Go all the way.
+- **State / data:** standardize server state on oRPC's **native** TanStack Query
+  integration (use it directly if it subsumes a separate client; otherwise
+  TanStack Query / React Query). **Zustand** for client / UI state. "Go all the way."
+- **Serverside:** build a **native Effect + oRPC router mounted on a Bun server**,
+  replacing the ~660 lines of untyped Vite middleware currently in
+  `vite.config.ts`. Leverage native oRPC middleware/context and the native
+  oRPC × Effect capabilities. **Research this deeply and natively FIRST**, before
+  designing.
+- **MANDATED bridge (user-confirmed):** use the **`effect-orpc`** library
+  specifically (`utopyin/effect-orpc`, v0.2.2) — handlers written as
+  `.effect(function* () {…})`, Effect error channel mapped to `ORPCError` via
+  `ORPCTaggedError`, services provided from an Effect `ManagedRuntime`/`Layer`.
+  It is pre-1.0 / single-maintainer: **isolate it to the `router/` layer** so the
+  blast radius of a breaking change is ~30 lines of manual `Effect.runPromise`
+  fallback. Verified install set: `@orpc/server@1.14.5`, `@orpc/client@1.14.5`,
+  `@orpc/contract@1.14.5`, `effect-orpc@0.2.2`, `effect@3.21.3`,
+  `@orpc/tanstack-query@1.14.5`, `@tanstack/react-query@5.101.0`, `zustand@5.0.14`.
+- **Execution:** **fully autonomous through to a PR** (Graphite stack). No
+  per-gate approval required.
+
+## Honest correction (controls scope)
+
+The user said "stick with oRPC and Effect serverside, we already have it."
+**They are NOT in the repo** — zero `@orpc/*` or `effect` imports anywhere in
+`apps/` or `packages/`. The current "server" is hand-rolled `fetch`/middleware
+inside `vite.config.ts`. So **oRPC × Effect × Bun is greenfield here**, not a
+constraint to preserve. The intent (typed, native oRPC×Effect server) stands; the
+"already have it" premise does not.
+
+## Frame
+
+- **In / foregrounded:** component decomposition, state & server-data
+  architecture, design-system formalization, accessibility & interaction craft,
+  intentional comments/organization, end-to-end type safety.
+- **Exterior (out of scope):** map-generation algorithms, Deck.gl rendering math,
+  recipe semantics, game-runtime / mod behavior. The engine is correct; this is
+  the shell around it.
+- **Hard core (never sacrificed):** behavior parity, end-to-end type safety, no
+  regression in the live-game control loop.
+- **Falsifier:** if decomposition or the server migration cannot preserve
+  map-gen / live-control behavior, or if "simpler" measurably degrades the
+  authoring workflow, stop and re-scope.
+- **Structural alternative considered & rejected:** a pure visual reskin
+  (tokens + polish only) — rejected because it leaves the 3k-line state tangle,
+  the actual ceiling on robustness.
+
+## Method (civ7-systematic-workstream gates)
+
+1. Deep oRPC × Effect × Bun + oRPC-native-TanStack research → canonical reference.
+2. Current-state audit + design-system extraction + critique.
+3. Target architecture spec + sliced redesign plan.
+4. Implement in Graphite slices with worktree isolation.
+5. Framed agent review (correctness, a11y, types, behavior parity).
+6. Verify (typecheck / tests / build) + open PR.
+
+## Status ledger
+
+- [x] Gate 1 — Frame the workstream (this doc)
+- [x] Gate 2 — Isolate repo state (branch `design/mapgen-studio-redesign`)
+- [x] Gate 1-research — Deep oRPC×Effect×Bun + oRPC-TanStack reference (`research/01`, `research/02`)
+- [x] Gate 3 — Diagnose / audit current state (`audit/03-06`, `system.md`)
+- [x] Gate 4-7 — Corpus, target architecture, slice plan (`architecture/10`, `architecture/11`)
+- [ ] Gate 8 — Implement slices (Phase A → G; see `architecture/11-slice-plan.md`)
+- [ ] Gate 9-10 — Verify / runtime parity
+- [ ] Gate 11 — Review wave
+- [ ] Gate 12 — Close (PR)
+
+## Execution log
+
+- Branch: `design/mapgen-studio-redesign`. Strategy: one branch, one commit per
+  slice, one PR (not a multi-branch Graphite stack — lower risk for autonomous run).
+- Next: Phase A (server `@civ7/studio-server`).
diff --git a/docs/projects/mapgen-studio-redesign/architecture/10-target-architecture.md b/docs/projects/mapgen-studio-redesign/architecture/10-target-architecture.md
new file mode 100644
index 0000000000..8371663aab
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/architecture/10-target-architecture.md
@@ -0,0 +1,149 @@
+# Target Architecture — MapGen Studio
+
+> Synthesis of the six audit/research lanes. This is the target state the slice
+> plan implements. Hard core: behavior parity (map-gen, Deck.gl, recipes,
+> live-control loop unchanged). Exterior: engine internals.
+
+## 0. Stack (verified versions, 2026-06-08)
+
+| Layer | Choice | Packages |
+| --- | --- | --- |
+| Server runtime | **Bun** (`Bun.serve` + `RPCHandler`) | — |
+| RPC | **oRPC** contract-first | `@orpc/server@1.14.5`, `@orpc/client@1.14.5`, `@orpc/contract@1.14.5` |
+| Effect bridge | **`effect-orpc`** (mandated) | `effect-orpc@0.2.2`, `effect@3.21.3` |
+| Validation | **Zod** at boundary (Effect Schema = spike, not first-class in oRPC) | `zod@^3.25 \|\| ^4` |
+| Server state (client) | **oRPC-native TanStack Query** (use utils directly) | `@orpc/tanstack-query@1.14.5`, `@tanstack/react-query@5.101.0` |
+| Client/UI state | **Zustand v5** (slices + persist) | `zustand@5.0.14` |
+| Design system | **shadcn/ui** (Radix) + **Tailwind v4** | `radix-ui/*`, `tailwindcss@4`, `sonner`, `tailwindcss-animate`/v4 equiv |
+
+## 1. Server: `@civ7/studio-server` (new workspace package)
+
+Replaces the 16 hand-rolled `/api/*` handlers in `vite.config.ts` (~L379-1147).
+Contract-first so the client gets types before the impl exists; OpenAPI/RPC
+handler mounted at `/api` so legacy paths keep working through cutover.
+
+```
+packages/studio-server/
+  src/
+    contract/            # oRPC contracts (zod I/O) — the typed corpus, no logic
+      civ7.ts            # status, mapSummary, gameInfo, autoplay, setupConfig,
+                         #   savedConfigs, setupCatalog
+      live.ts            # civ7.live.{status,snapshot,entities,gameInfo}
+      runInGame.ts       # runInGame.{start,status}
+      mapConfigs.ts      # mapConfigs.{saveDeploy,status}
+      studio.ts          # studio.serverInfo
+      index.ts           # root contract
+    services/            # Effect services (lift src/server/* + handler bodies)
+      Civ7TunerClient.ts # FireTuner/socket reads (status, snapshot, gameinfo…)
+      ProcessControl.ts  # macosProcessRestart, Steam relaunch  [PARITY-CRITICAL]
+      MapConfigStore.ts  # write-then-deploy + rollback, path jail [PARITY-CRITICAL]
+      RunInGameEngine.ts # 9-phase state machine, fingerprint dedup, proof id,
+                         #   logFailure classification, serialized queue [PARITY-CRITICAL]
+      Civ7ResourceCatalog.ts
+      StudioConfig.ts    # env/paths context (macOS app-resources root)
+    middleware/          # oRPC native middleware
+      requestId.ts       # proof identity / request-id (.use)
+      logging.ts
+      errorMap.ts        # ORPCError mapping; preserve NON-UNIFORM status codes
+    router/              # effect-orpc: .effect(function*(){...}); ISOLATE effect-orpc here
+      index.ts
+    runtime.ts           # ManagedRuntime + Layer composition
+    server.ts            # Bun.serve entrypoint, CORS, mount /api
+  package.json
+```
+
+**Parity invariants (do not change behavior):**
+- Error status codes are **non-uniform** (gameinfo→400, setup-config→503, most→500). `errorMap` must reproduce per-procedure.
+- `civ7/live/status` returns **200 with per-field embedded `{error}`** (via allSettled), not transport errors.
+- `assertNoRawControlFields` deep-scan in run-in-game is a **security boundary** — keep it.
+- run-in-game: fingerprint dedup→202, dual-store mutex→409, sha256 proof identity, `finally` cleanup + `gen:maps` regen, serialized queue. Move verbatim into `RunInGameEngine` service.
+- status 404 echoes `serverInstanceId`/`serverStartedAt` for restart detection.
+
+**Dev/prod wiring (fixes the production parity gap):** today `/api/*` exists only
+in Vite dev; `railway.json`/`Caddyfile` serve static `dist` only. Target: Bun
+server owns `/api`; Vite dev proxies `/api`→Bun; prod Caddy `reverse_proxy`s
+`/api`→Bun service (or Bun serves `dist` + `/api`).
+
+## 2. Client data layer
+
+```
+apps/mapgen-studio/src/lib/
+  orpc.ts     # RPCLink(fetch) → createORPCClient → createTanstackQueryUtils(client)
+  query.ts    # QueryClient factory (sane defaults: staleTime, retry)
+apps/mapgen-studio/src/main.tsx  # QueryClientProvider wraps app
+```
+
+- **Verdict (confirmed):** use oRPC's native query utils **directly** —
+  `orpc.civ7.status.queryOptions()` into standard `useQuery`. No hand-written
+  query client, no query-key factory, no wrapper-hook lib. Only QueryClient is
+  ours to provide.
+- **Live/polling surface** (App.tsx L966-1114): becomes `useQuery` with adaptive
+  `refetchInterval` fn + `skipToken` gating. **Migrate LAST**, behind a parity
+  harness — the 149-line poll hides request-key staleness gating and cross-failure
+  adaptive backoff that naive porting will break (snapshot tearing / hot-polling).
+
+## 3. Client state (Zustand) — the App.tsx un-godding
+
+42 `useState` + 24 `useEffect` in one 3,010-line component → stores + query + local.
+
+| Store | Owns | Replaces |
+| --- | --- | --- |
+| `authoringStore` (persist) | worldSettings, recipeSettings, setupConfig, pipelineConfig, overridesDisabled, repoBackedPresetOverrides | 6 useState + manual persistence effect (L868-877) |
+| `viewStore` | showGrid/Edges, overlays, era*, panel-collapse, selectedStage/Step (single owner; delete App mirror + sync L1242-1248) | scattered view useState + vizStore mirror |
+| `runStore` (persist) | runInGameSnapshot, lastRunInGameSource, lastSaveDeployConfig, lastRunSnapshot, localStorage request-id bridge | run snapshots + studioState/persistence.ts |
+| **TanStack Query** | all server polling (live status/snapshot, setup-catalog, saved-configs, run-in-game status, save-deploy status) | 8 raw fetch effects |
+| **Local (useState/ref)** | viewportSize, headerHeight, deckApi refs, dialog open, dedupe latches | stays colocated |
+
+**Crisp rule:** server owns it → TanStack Query (via oRPC). Browser-only → Zustand.
+Never mirror query results into Zustand; a Zustand selection id flows the other way as a query `input`.
+
+## 4. Component tree (decomposition target)
+
+```
+App                       theme + providers only (~30 LoC)
+└─ StudioProviders        Toast(Sonner) + QueryClient + ThemeContext(use())
+   └─ StudioShell         layout, error boundary host, global shortcuts host
+      ├─ CanvasStage      → DeckCanvas         (viewStore + vizStore)
+      ├─ AppHeader        presentational       (authoringStore + setupStore)
+      ├─ LeftDock         → RecipeConfigPanel(container) → RecipePanel(presentational)
+      ├─ RightDock        → ExploreController(container) → ExplorePanel(presentational)
+      ├─ AppFooter        container-lite       (runStore + live query)
+      ├─ PresetDialogs    (already extracted)
+      └─ ErrorBanner
+```
+535 LoC of non-React helpers at the top of App.tsx → extracted modules.
+Panels currently take 30-38 flat props (boolean-prop explosion + 6 duplicated
+select-triples) → compound components reading stores. 8 effects are
+derived-state/event-handlers in disguise → remove.
+
+## 5. Design system (shadcn + Tailwind v4)
+
+- **Theming is structurally broken today**, not just inconsistent: `useTheme.ts:130-175`
+  builds classes via runtime string interpolation (`bg-[${...}]`) Tailwind JIT never
+  emits; two conflicting dark-mode systems (`media` default vs a `lightMode` boolean
+  threaded through 24 files); declared accent (#5e5ce6 indigo) ≠ used accent (#4b5563 slate).
+- **Target:** single `.dark` class strategy, HSL shadcn tokens, **one committed accent**,
+  delete `createTheme()`/`lightMode` prop/`colors.light|dark` config/`--spacing-*`/`--radius-*` vars.
+- Token map: `bg→--background`, `text→--foreground`, `card/popover`, `muted-foreground`,
+  `border/input`, `--primary/--ring` (pick one accent), `--destructive`, `--radius:0.25rem`.
+- **Primitives → Radix shadcn:** 8 primitives (+Sonner for Toast); ~21 import sites,
+  5 dialog/toast instances, 28 native `title=`→Tooltip. Closes focus-trap/ARIA/keyboard gaps.
+- **Add:** Dialog, Popover, **Command (cmd-k)**, Combobox, DropdownMenu, Tabs, Accordion,
+  ScrollArea, Slider, Separator, Sheet, Resizable.
+- **rjsf** widgets/templates re-render through shadcn primitives (big surface).
+- Tailwind **v3→v4 now** (React 19.2 + Vite 7 already; config is mostly dead).
+
+## 6. TypeScript rigor
+
+- Typecheck is **clean today (0 errors)**. App tsconfig is standalone (does NOT extend base).
+- 21 `any` + 126 `as` casts; ~10-12 dangerous `res.json() as T` casts **evaporate for free**
+  once the typed oRPC client lands. RJSF/deck.gl/worker `any`s need explicit work.
+- Enable: **`noUncheckedIndexedAccess`**, **`exactOptionalPropertyTypes`**, **`verbatimModuleSyntax`**.
+- `localStorage` persistence layer is the **reference impl** (guarded `JSON.parse as unknown`) — copy it, don't "fix" it.
+
+## 7. Do-not-break registry (parity)
+
+browserRunner runToken/generation gating · run-in-game fingerprint/relation equality ·
+materialization-mode decision · localStorage schema contract · live-runtime poll
+request-key staleness + adaptive backoff · `assertNoRawControlFields` · process-restart
++ catalog macOS paths · serialized run queue + dual mutex.
diff --git a/docs/projects/mapgen-studio-redesign/architecture/11-slice-plan.md b/docs/projects/mapgen-studio-redesign/architecture/11-slice-plan.md
new file mode 100644
index 0000000000..e5557b7b12
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/architecture/11-slice-plan.md
@@ -0,0 +1,93 @@
+# Slice Plan — Graphite Stack
+
+> Dependency-ordered. Each slice = one Graphite branch = one coherent, reviewable,
+> independently-typechecking change. Verify gate per slice: `tsc --noEmit` clean +
+> app builds + behavior parity for touched surfaces. Build the stack bottom-up.
+
+## Sequencing rationale
+
+Server contract first (unblocks typed client) → server impl (keep old middleware
+alive) → cutover → client data layer → stores (un-god App.tsx) → design-system
+foundation (tokens, broken theming is foundational) → component decomposition →
+primitive migration + new components + rjsf + craft → rigor + dead code → verify +
+review + PR. Server and design-foundation are independent and could interleave;
+the stack keeps them linear for clean review.
+
+## Phase A — Server (`@civ7/studio-server`, effect-orpc on Bun)
+
+- **A1 — Package + contracts.** Scaffold `packages/studio-server`; define oRPC
+  contracts (zod I/O) for all 16 endpoints across civ7/live/runInGame/mapConfigs/studio.
+  No logic. Export contract types. *Verify:* package typechecks; contract types importable.
+- **A2 — Effect services.** Lift `src/server/*` helpers + the vite.config handler bodies
+  into Effect services (Civ7TunerClient, ProcessControl, MapConfigStore, RunInGameEngine,
+  Civ7ResourceCatalog, StudioConfig) + Layers + ManagedRuntime. Preserve parity invariants.
+- **A3 — Router + middleware.** `effect-orpc` router implementing the contract via services;
+  `.effect(function*(){})`; ORPCError mapping with **non-uniform status codes**; requestId/
+  logging middleware; context injection. Isolate effect-orpc to `router/`.
+- **A4 — Bun entrypoint + dev proxy.** `Bun.serve` + RPCHandler at `/api`; CORS; Vite dev
+  proxy `/api`→Bun; prod Caddy reverse_proxy (fix the static-only parity gap). Add run scripts.
+- **A5 — Cutover.** Remove the `/api` middleware from `vite.config.ts`. Parity-test all 16
+  endpoints against the new server (curl/contract tests). *Verify:* every endpoint responds identically.
+
+## Phase B — Client data layer
+
+- **B1 — oRPC client + Query provider.** `lib/orpc.ts` (RPCLink→client→tanstack utils),
+  `lib/query.ts` (QueryClient), `QueryClientProvider` in `main.tsx`. *Verify:* typed client resolves against A1 contracts.
+- **B2 — Zustand stores.** `stores/authoringStore.ts` (persist), `viewStore.ts`, `runStore.ts`
+  (persist). Port the localStorage persistence reference impl into `persist`. Make vizStore the single step/layer owner. *Verify:* stores typecheck; persistence round-trips.
+- **B3 — Swap fetch → query/mutation.** Replace the non-live fetch sites with oRPC hooks.
+  *Verify:* each surface loads/mutates identically.
+- **B4 — Live poll (LAST, parity harness).** Migrate the 149-line live-runtime poll to
+  `useQuery` adaptive `refetchInterval` + `skipToken`, keeping staleness gating + backoff
+  verbatim in the queryFn. *Verify:* no snapshot tearing; no hot-poll when Civ7 disconnected.
+
+## Phase C — Design-system foundation
+
+- **C1 — Tailwind v4 + shadcn init.** Migrate Tailwind v3→v4; `components.json`; `cn` util;
+  animate; HSL token set; single `.dark` strategy; **one committed accent**. Delete
+  `createTheme()`, `lightMode` prop threading, dead `colors.light|dark`, `--spacing-*`/`--radius-*`.
+  *Verify:* app renders in light+dark via `.dark` class; no JIT-missing classes.
+
+## Phase D — Component decomposition
+
+- **D1 — Extract helpers.** Move the 535 LoC of non-React helpers out of App.tsx into modules.
+- **D2 — Shell + providers.** `StudioProviders`, `StudioShell`, docks; theme→`ThemeContext`(use()).
+  App.tsx → ~30 LoC. Remove the 8 disguised effects.
+- **D3 — Container/presentational split.** RecipePanel/ExplorePanel/AppFooter read stores;
+  kill 30-38-prop drilling; compound-component the 6 duplicated select-triples.
+- **D4 — Error boundaries.** Around CanvasStage + mapgen pipeline + each dock.
+  *Verify per slice:* parity on recipe authoring, viz, run-in-game.
+
+## Phase E — Primitives, new components, rjsf, craft
+
+- **E1 — Migrate primitives → Radix shadcn** (Button, Input, Select, Switch, Checkbox,
+  Textarea, AlertDialog→Dialog, Tooltip; Toast→Sonner). Update ~21 sites; 28 `title=`→Tooltip.
+- **E2 — Add components.** Command(cmd-k), Popover, DropdownMenu, Tabs, ScrollArea, Resizable,
+  Sheet, Slider, Separator, Combobox — wired where the app needs them.
+- **E3 — rjsf through shadcn.** Re-skin widgets/templates onto shadcn primitives.
+- **E4 — Craft pass.** Focus rings, motion, loading skeletons, empty/error states, density,
+  hierarchy, dark-mode correctness. *Verify:* design:audit re-run is clean against system.md.
+
+## Phase F — Rigor + cleanup
+
+- **F1 — tsconfig strict.** Enable noUncheckedIndexedAccess, exactOptionalPropertyTypes,
+  verbatimModuleSyntax; fix fallout. *Verify:* 0 errors.
+- **F2 — Dead code.** Remove `fields/` duplicate styling system, dead hooks/exports — confirm
+  with find_unused_exports / references before deleting.
+- **F3 — Comments + organization.** Top-1% intentional comments (why, not what); file/dir layout.
+
+## Phase G — Verify + review + PR
+
+- **G1 — Full verify.** typecheck + build + tests for studio + studio-server + affected packages;
+  parity checks on live-control loop and run-in-game.
+- **G2 — Review wave.** Framed reviewers: correctness/parity, a11y, types, design-audit.
+  Accepted P1/P2 block closure.
+- **G3 — Close.** Graphite stack submit → PR with the workstream docs linked.
+
+## Risk register (top)
+
+1. effect-orpc pre-1.0 — isolate to `router/`; ~30-line manual fallback ready.
+2. Live-runtime poll parity (B4) — do last, parity harness, verbatim gating.
+3. run-in-game 9-phase engine (A2/A3) — lift verbatim into one service; contract-test.
+4. Tailwind v4 + rjsf re-skin churn — large surface; slice E3 separately.
+5. Production `/api` parity gap — must be fixed in A4, not discovered at deploy.
diff --git a/docs/projects/mapgen-studio-redesign/audit/03-component-architecture.md b/docs/projects/mapgen-studio-redesign/audit/03-component-architecture.md
new file mode 100644
index 0000000000..fd408fd74c
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/audit/03-component-architecture.md
@@ -0,0 +1,322 @@
+# 03 — Component Architecture Audit: `apps/mapgen-studio`
+
+**Audit lane:** Component architecture / React structure
+**Primary target:** `src/App.tsx` (3,010 LoC god-component)
+**Date:** 2026-06-08
+**Lens applied:** `dev:vercel-composition-patterns`, `dev:vercel-react-best-practices`, `dev:frontend-design`
+
+> **Behavior-parity constraint (non-negotiable):** map-gen pipeline, Deck.gl rendering, recipe semantics, and the live-game runtime loop must be preserved bit-for-bit. Sections flag every piece of **load-bearing live-control state** so decomposition does not break the live loop.
+
+---
+
+## 0. Executive snapshot (1 screen)
+
+### Proposed top-level component tree
+
+```
+<App>                                   (theme + providers only — App.tsx:3003)
+  <ToastProvider>
+  <QueryClientProvider>                 (NEW — TanStack Query)
+    <StudioShell>                       (NEW container: layout + keyboard shortcuts + error banner)
+      <CanvasStage>                     (NEW: deck canvas + backdrop + grid + empty-state)
+        <DeckCanvas/>                   (unchanged — features/viz/DeckCanvas)
+      <AppHeader/>                      (presentational; reads worldStore + setupStore)
+      <LeftDock>                        (NEW container)
+        <RecipeConfigPanel>            (NEW container; owns preset/save/config orchestration)
+          <RecipePanel/>               (presentational — unchanged shell)
+      <RightDock>                       (NEW container)
+        <ExploreController>            (NEW container; owns viz selection derivation)
+          <ExplorePanel/>              (presentational — unchanged shell)
+      <AppFooter>                       (container-lite; reads runStore + liveStore)
+      <PresetDialogs/>                  (presentational — already extracted)
+      <ErrorBanner/>                    (NEW trivial presentational)
+```
+
+### State → store / query / local split
+
+| Bucket | Today (App.tsx) | Target |
+|---|---|---|
+| **Authoring config** (worldSettings, recipeSettings, setupConfig, pipelineConfig, overridesDisabled, repoBackedPresetOverrides) | 6 `useState` + 1 persistence effect | **Zustand `authoringStore`** (persist middleware replaces the manual save effect at L868–877) |
+| **Viz/view selection** (selectedStage/Step, overlay*, era*, showGrid/Edges, panel collapse flags) | ~14 `useState` + ~10 derivation `useMemo` + 8 sync effects | **Zustand `viewStore`** for raw UI selection; selection **derivation stays in an `ExploreController` hook** (`useExploreSelection`). `vizStore` (existing external store) unchanged. |
+| **Run-in-game / save-deploy / browser run** | `runInGameOperation`, `saveDeployOperation`, `runInGameSnapshot`, `lastRunInGameSource`, `lastSaveDeployConfig`, `lastRunSnapshot`, polling effects | **TanStack Query** for the server-polled operations (`run-in-game/status`, `map-configs/status`); **`runStore` (Zustand)** for client snapshots/fingerprints that survive reload |
+| **Live runtime** (status, snapshot, suggestions, liveSetup, savedConfigs, setupCatalog) | `liveRuntime`, `liveRuntimeSuggestions`, `liveSetup`, `savedSetupConfigs`, `setupCatalog` + the 130-line polling effect (L966–1114) + the catalog effect (L1116–1175) | **TanStack Query** with `refetchInterval` for status/snapshot/setup/catalog; keep the **manual abort + request-key gating logic** as the queryFn body (it is load-bearing — see §6 risk) |
+| **Theme** | `useThemePreference` (already a hook) | Keep as hook; optionally fold into a tiny `uiStore`. Lowest priority. |
+| **Local/ephemeral** | `viewportSize`, `headerHeight`, `deckApiReadyTick`, dialog open state, `importInputRef`, all `*Ref` latches | **Stays local** in the owning container. |
+
+### Single biggest decomposition risk
+
+**The 149-line live-runtime polling effect (`App.tsx:966–1114`) is the live-control heart and is deceptively stateful.** It interleaves four concerns (status poll, setup fetch, snapshot read, suggestion build) behind a single `cancelled` closure, two failure-count refs (`liveStatusFailureCountRef`, `liveSnapshotFailureCountRef`), an active-request-key ref, and an abort controller, all feeding `nextLiveRuntimePollDelayMs` for adaptive backoff. Naively porting it to a `useQuery({refetchInterval})` will **drop the request-key staleness gating (`shouldCommitLiveRuntimeSnapshot`) and the cross-failure backoff coupling**, producing snapshot tearing (stale snapshot committed over a newer one) and a hot-poll loop against a disconnected Civ7. This effect must be migrated last, behind a parity harness, with `shouldCommitLiveRuntimeSnapshot` / `nextLiveRuntimePollDelayMs` kept as-is inside the queryFn.
+
+---
+
+## 1. State inventory of `App.tsx`
+
+`AppContent` (L676–3001) holds **42 `useState`, 19 `useRef`, 24 `useEffect`, 34 `useMemo`, 37 `useCallback`.** Grouped by concern:
+
+### 1A. Recipe / authoring config (the durable authoring model)
+
+| State | Decl | What | Read by | Mutated by |
+|---|---|---|---|---|
+| `worldSettings` | L708 | mapSize/playerCount/resources | header, footer, run builders, fingerprint, persistence | `AppHeader.onGlobalSettingsChange` (L2790), `syncStudioFromLiveGame` (L2184), saved-config seed flow |
+| `recipeSettings` | L714 | recipe/preset/seed | nearly everything (recipe drives `recipeArtifacts`) | RecipePanel (L2819), footer seed, reroll (L1717), preset save/import/delete handlers, live sync |
+| `setupConfig` | L719 | Civ7 setup (leader/civ/difficulty/speed/gameOptions) | header setup controls, run-in-game, fingerprint | header (L2793), `handleSavedSetupConfigChange` (L1872), live sync (L2186) |
+| `pipelineConfig` | L788 | full pipeline overrides object (lazy default-built) | RecipePanel, run builders, fingerprint, run-in-game, save | RecipePanel `onConfigChange` (L2803), preset-apply effect (L853), every save handler, live sync (L2185) |
+| `overridesDisabled` | L793 | toggles config overrides on run | RecipePanel switch, `startBrowserRun`, autorun guards | RecipePanel (L2839), recipe-change effect (L809), live sync |
+| `repoBackedPresetOverridesByRecipe` | L733 | in-memory repo preset overrides keyed by recipe | `builtInPresets` memo (L746) | `rememberRepoBackedConfig` (L1364) |
+| `lastRunSnapshot` | L794 | last browser-run inputs (for `isDirty`) | `isDirty` (L1731), autorun equality guards | `startBrowserRun` (L1276), recipe-change effect resets to null |
+
+**Persistence:** single effect L868–877 serializes the first 6 to `localStorage` via `saveStudioAuthoringState`. Initial hydration via `initialAuthoringStateRef` (L680–684) read once.
+
+### 1B. Viz / view controls (selection + display)
+
+| State | Decl | What | Read/Mutated |
+|---|---|---|---|
+| `showGrid` | L692 | background grid toggle | header toggle; `backgroundGridEnabled` memo (L2720) |
+| `showEdges` | L693 | edge overlay toggle | passed to `useVizState` (L933); ExplorePanel toggle |
+| `overlaySelectionId` | L694 | selected overlay suggestion | ExplorePanel; `overlaySelection` derived (L742); reset effect (L2363) |
+| `overlayOpacity` | L695 | overlay alpha | useVizState; ExplorePanel slider |
+| `overlayVariantKeyPreference` | L696 | era-pinned overlay variant | useVizState; **set by effect** L2373–2407 (derived-state-in-disguise) |
+| `eraMode` | L697 | "auto"/"fixed" | era controls; many handlers |
+| `manualEra` | L698 | fixed era value | era handlers; clamp effect (L2341) |
+| `selectedStageId` | L1197 | explore stage | ExplorePanel; sync effect (L1232) |
+| `selectedStepId` | L1198 | explore step | ExplorePanel; sync effects (L1237, L1242) push into `viz` |
+| `recipeSectionCollapsed`, `configSectionCollapsed` | L699–700 | left panel collapse | RecipePanel; `toggleLeftPanel` |
+| `exploreStageExpanded/StepExpanded/LayersExpanded` | L701–703 | right panel collapse | ExplorePanel; `toggleRightPanel` |
+| `viewportSize` | L690 | canvas size | DeckCanvas, fit effect | ResizeObserver effect (L1177) |
+| `headerHeight` | L2714 | measured header height | panel top offset | `onHeaderHeightChange` |
+| `deckApiReadyTick` | L687 | forces re-fit when deck API mounts | fit effect (L952) | `handleDeckApiReady` |
+
+Plus the **entire derived-selection pyramid** (`selection`, `selectedDataType`, `selectedSpace`, `selectedRenderMode`, `selectedVariants`, `selectedVariant`, `eraVariants`, `eraRange`, `autoEra`, `fixedEraUiValue`, `overlayCandidates`, `overlayOptions`, `spaceOptions`, `renderModeOptions`, `variantOptions`, `dataTypeOptions`) — L2244–2361 — all `useMemo` chained off `viz.dataTypeModel` + `viz.selectedLayerKey`. This is the bulk of `ExploreController`.
+
+> **Live-control note:** `viz.*` selection lives in the existing `vizStore` external store (`features/viz/vizStore.ts`), already decoupled. The App-level mirror state (`selectedStageId`/`selectedStepId`) is a **second source of truth** that is sync'd into `vizStore` by effects L1237–1248 — a known smell (see §2).
+
+### 1C. Browser run (map-gen worker)
+
+| State | Decl | Notes |
+|---|---|---|
+| `browserRunner` (`useBrowserRunner`) | L884 | owns worker lifecycle, `state.running/error/lastStep`. **Load-bearing for map-gen.** Already a clean hook. |
+| `autoRunEnabled` | L704 | footer toggle |
+| `autoRunTimerRef`, `autoRunPendingRef` | L705–706 | debounce latches for 3 autorun effects (L1296, L1306, L1340) |
+| `localError` | L890 | merged with runner error into `error` (L962) |
+
+### 1D. Run-in-game + save/deploy (server operations)
+
+| State | Decl | What | Mutated |
+|---|---|---|---|
+| `runInGameOperation` | L739 | server op status (polled) | `handleRunInGame` (L2069), `refreshRunInGameStatus` (L1910), polling effect (L1986–2008), restore effect (L1941) |
+| `runInGameSnapshot` | L892 | client fingerprint snapshot | handleRunInGame, restore effect |
+| `lastRunInGameSource` | L736 | full source snapshot (proved live source) | handleRunInGame; live presets/relation memos; live sync |
+| `lastSaveDeployConfig` | L893 | last saved config for materialization-mode calc | save handlers; `runInGameMaterializationMode` memo |
+| `saveDeployOperation` | L891 | save/deploy server op | `saveRepoBackedConfigWithState` (L1397), polling effect (L1974) |
+| `lastRunInGameToastRef` | L894 | terminal-toast dedupe latch | toast effect L1986 |
+
+`localStorage` keys L430–433 persist last request IDs + snapshots; restore effects L1941–1972.
+
+### 1E. Live runtime (the live-control loop)
+
+| State | Decl | What |
+|---|---|---|
+| `liveRuntime` | L899 | status/snapshotStatus/binding/turn/seed/autoplay — **footer live indicator + sync gating** |
+| `liveRuntimeSnapshot` (write-only, `[, setLiveRuntimeSnapshot]`) | L905 | snapshot state — **set but never read** (see §2 dead read) |
+| `liveRuntimeSuggestions` | L906 | suggestion records consumed by `syncStudioFromLiveGame` (L2120) |
+| `liveSetup` | L907 | live Civ7 setup snapshot → drives `setupControlOptions` (L1818) |
+| `savedSetupConfigs` | L913 | `/saved-configs` result → setup dropdown |
+| `setupCatalog` | L920 | `/setup-catalog` result → setup dropdown |
+| `autoplayActionRunning` | L926 | autoplay button in-flight latch |
+| Refs: `liveStatusFailureCountRef`, `liveSnapshotFailureCountRef`, `activeLiveSnapshotRequestKeyRef`, `liveSnapshotAbortRef` | L895–898 | **load-bearing** backoff + staleness gating |
+
+### 1F. Presets / dialogs
+
+| State | Decl |
+|---|---|
+| `presetError`, `saveDialogState`, `pendingImport` | L722–728 |
+| `importInputRef` | L729 |
+| `lastAppliedPresetRef`, `lastPresetKeyRef`, `lastRecipeIdRef` | L730–732 (preset-apply dedupe latches) |
+| `usePresets(...)` | L782 (already a hook; owns local/scratch presets) |
+
+### 1G. Theme / shortcuts / misc
+
+- `useThemePreference` (lifted to `App`, passed via `AppContentProps` L670) — already a hook.
+- `shortcutsRef` (L2539) — mutable mirror of stage/step/datatype + handlers, read by the global `keydown` effect (L2596–2712). A deliberate ref-as-event-handler-latch (`advanced-event-handler-refs`), but the mirror is large and brittle.
+
+---
+
+## 2. Effect audit (24 `useEffect`)
+
+| # | Line | Purpose | Verdict |
+|---|---|---|---|
+| 1 | L796–818 | Reset config when recipe/preset changes to "none" | **Should be an event handler.** Triggered by recipe/preset change; uses `lastPresetKeyRef`/`lastRecipeIdRef` to detect "did it actually change" — classic effect-emulating-an-event. Move into `onSettingsChange`. |
+| 2 | L820–861 | Apply preset config on preset change | **Should be event handler / derived.** Uses `lastAppliedPresetRef` dedupe to avoid re-applying. This is reacting to a controlled select change; belongs in the preset-select handler. |
+| 3 | L863–866 | Toast `loadWarning` | Borderline; acceptable as effect (external warning surfacing) but could be event from `usePresets`. |
+| 4 | L868–877 | Persist authoring state to localStorage | **Replace with Zustand `persist` middleware.** Pure write-through derived from store. |
+| 5 | L943–950 | Auto-fit deck to bounds on space change | Legit effect (imperative deck API). Keep. Uses `lastAutoFitSpaceRef` latch — fine. |
+| 6 | L952–960 | First-manifest auto-fit | Legit imperative effect. Keep. |
+| 7 | L966–1114 | **Live runtime poll loop** (status+setup+snapshot+suggestions) | **Migrate to TanStack Query last** (see §6). Load-bearing. Mixed concerns; should be ≥3 queries. |
+| 8 | L1116–1175 | Load saved-configs + catalog, retry + focus-refetch | **TanStack Query** (`Promise.all` → two queries with `refetchOnWindowFocus`). The hand-rolled focus listener + retry timer is exactly what Query provides. |
+| 9 | L1177–1195 | ResizeObserver → viewportSize | Legit. Keep (local). |
+| 10 | L1232–1235 | Clamp `selectedStageId` to available stages | **Derived-state-in-disguise.** Should be computed during render (`rerender-derived-state-no-effect`). |
+| 11 | L1237–1240 | Clamp `selectedStepId` to available steps | **Derived-state-in-disguise.** Same. |
+| 12 | L1242–1248 | Push `selectedStepId` into `viz` store | **Sync of duplicated state** — symptom of two sources of truth (App mirror vs vizStore). Eliminate by making vizStore the single owner. `eslint-disable exhaustive-deps` present = smell. |
+| 13 | L1296–1304 | Clear autorun timer when disabled | Could fold into the autorun effect. Minor. |
+| 14 | L1306–1338 | Autorun: schedule run on config change | Legit (debounced side-effect). Keep but consolidate the 3 autorun effects (#13–15) into one `useAutoRun` hook. |
+| 15 | L1340–1350 | Autorun: flush pending after run finishes | Part of the autorun trio. Consolidate. |
+| 16 | L1941–1960 | Restore run-in-game status from localStorage on mount | One-shot init. Keep, or fold into Query `initialData`. |
+| 17 | L1962–1972 | Restore save-deploy status from localStorage | One-shot init. Same. |
+| 18 | L1974–1984 | Poll save-deploy status while running | **TanStack Query** `refetchInterval` (document.hidden-aware). |
+| 19 | L1986–2008 | Poll run-in-game status while running + terminal toast | **Split:** polling → Query; terminal toast → event/`onSuccess`. Toast-in-effect via `lastRunInGameToastRef` dedupe is a derived-event smell. |
+| 20 | L2341–2344 | Clamp `manualEra` to range | **Derived-state-in-disguise** (clamp during render or in handler). |
+| 21 | L2363–2371 | Reset `overlaySelectionId` when candidates change | **Derived-state-in-disguise** (invalid selection → render-time fallback). |
+| 22 | L2373–2407 | Compute `overlayVariantKeyPreference` from era/selection | **Derived-state-in-disguise.** This is a pure function of (eraMode, manualEra, overlaySelection, selection) written as `setState` in an effect with `prev ===` guards. Should be a `useMemo`. |
+| 23 | L2596–2712 | Global keyboard shortcuts | Legit (window listener). Keep. The `shortcutsRef` mirror is the cost of an empty-deps listener; acceptable but extractable to `useGlobalShortcuts`. |
+| 24 | (header) L2714 area effects | header height plumbing | Local. Keep. |
+
+**Effect-overuse tally:** **8 effects are derived-state-in-disguise or should be event handlers** (#1, #2, #10, #11, #12, #20, #21, #22) — eliminating them removes ~120 lines and several `*Ref` latches. **6 effects are server polling** that TanStack Query collapses (#7 partial, #8, #18, #19 partial, #16, #17).
+
+**Dead read:** `liveRuntimeSnapshot` state (L905) is written (L1004, L1027) but the value is never consumed (`[, setLiveRuntimeSnapshot]` discards the getter). It only feeds `liveRuntime.snapshotStatus` indirectly. Candidate for removal — confirm against live loop before deleting.
+
+**Key-prop misuse:** none found (no list-rendering with index keys in App.tsx; lists live inside panels).
+
+---
+
+## 3. Prop-drilling map
+
+App.tsx is **flat** (one level: App → Header/Footer/RecipePanel/ExplorePanel), so literal depth is 1. But the *prop count* is the pathology — the god-component hand-threads dozens of props because there is no intermediate container or store:
+
+| Component | Prop count | Threaded clusters that should be store reads |
+|---|---|---|
+| **ExplorePanel** (L2847–2894) | **~38 props** | The entire viz-selection model (stages/steps/dataType/space/renderMode/variant + 7 `on*Change` + overlay + era + 3 expand toggles). Every one is App state or App-derived. → `ExploreController` + `viewStore`. |
+| **RecipePanel** (L2799–2844) | **~30 props** | config + schema + 6 preset action callbacks + 5 run/save status booleans + 4 collapse props. → `RecipeConfigPanel` container + `authoringStore`. |
+| **AppFooter** (L2897–2929) | **~30 props** (interface L19–81) | run/run-in-game/save/live/autoplay status + 8 callbacks. The `liveRuntime` object (L57–66) and `runInGameStatus`/`saveDeployStatus` are pure store reads. → footer reads `runStore`/`liveStore` directly. |
+| **AppHeader** (L2782–2796) | ~11 props | worldSettings + setupConfig + setupOptions + theme. → `authoringStore` + `setupStore`. |
+
+**Props that thread > 2 levels:** Strictly, none today (depth is 1). But `lightMode`/`theme` is threaded into **every** component and then **re-threaded** into every child inside the panels (`fields/`, `ui/`) — effectively 3–4 levels deep. → **Theme belongs in context** (`react19-no-forwardref` + `use(ThemeContext)`), eliminating the most pervasive prop. The `viz` object's selection is also effectively threaded App → ExplorePanel-derivation → DeckCanvas via 15 memos.
+
+---
+
+## 4. Decomposition target
+
+### 4.1 Target component tree (containers vs presentational)
+
+```
+App.tsx                         theme hook + providers ONLY (~30 LoC)
+└─ providers/StudioProviders    ToastProvider + QueryClientProvider + ThemeProvider(context)
+   └─ StudioShell               layout grid, panelTop math, error banner, global shortcuts host
+      ├─ CanvasStage            backdrop/grid/empty-state + <DeckCanvas>; reads viewStore.showGrid, vizStore
+      ├─ AppHeader              (presentational) reads authoringStore + setupStore via selectors
+      ├─ LeftDock
+      │  └─ RecipeConfigPanel   CONTAINER: preset/save/import/export orchestration + dirty calc
+      │     └─ RecipePanel      (presentational, unchanged shell)
+      ├─ RightDock
+      │  └─ ExploreController   CONTAINER: viz-selection derivation (useExploreSelection)
+      │     └─ ExplorePanel     (presentational, unchanged shell)
+      ├─ AppFooter              CONTAINER-LITE: reads runStore + liveStore; run/live/autoplay actions
+      ├─ PresetDialogs          (presentational, already extracted)
+      └─ ErrorBanner            (presentational, NEW trivial)
+```
+
+### 4.2 New files / hooks to create
+
+**Stores (Zustand — net-new dependency):**
+
+| File | Owns | Replaces |
+|---|---|---|
+| `src/state/authoringStore.ts` | worldSettings, recipeSettings, setupConfig, pipelineConfig, overridesDisabled, repoBackedPresetOverrides + actions (setRecipe, applyPreset, resetConfig, rememberRepoBacked) | App L708–793 + persistence effect L868–877 (use `persist` middleware keyed `mapgen-studio.authoring-state.v1` — **must preserve existing schema/migration in `studioState/persistence.ts`**) |
+| `src/state/viewStore.ts` | showGrid/showEdges, overlaySelectionId/Opacity, eraMode/manualEra, panel collapse/expand flags, selectedStageId/StepId | App L692–703, L1197–1198, L2714 |
+| `src/state/runStore.ts` | runInGameOperation, runInGameSnapshot, lastRunInGameSource, lastSaveDeployConfig, lastRunSnapshot + localStorage bridge | App L736–739, L892–894 + restore effects |
+| `src/state/liveStore.ts` (optional) | liveRuntime status surface consumed by footer/sync | App L899–926; **wraps** Query data, does not replace the poll gating |
+
+> `vizStore.ts` (existing external store) stays as-is and becomes the **single** owner of selectedStep/Layer (delete the App mirror + sync effect #12).
+
+**Query hooks (TanStack Query — net-new dependency):**
+
+| File | Query |
+|---|---|
+| `src/features/liveRuntime/useLiveRuntimeQuery.ts` | status + snapshot poll; queryFn keeps `shouldCommitLiveRuntimeSnapshot` + `nextLiveRuntimePollDelayMs` + abort/request-key gating verbatim |
+| `src/features/civ7Setup/useSetupCatalogQuery.ts` | saved-configs + catalog (`refetchOnWindowFocus`) |
+| `src/features/runInGame/useRunInGameStatusQuery.ts` | run-in-game status poll (`refetchInterval`, hidden-aware) |
+| `src/features/mapConfigSave/useSaveDeployStatusQuery.ts` | save/deploy status poll |
+
+**Container hooks (keep derivation colocated, not in a store):**
+
+| File | Owns |
+|---|---|
+| `src/features/viz/useExploreSelection.ts` | the L2244–2407 derivation pyramid + the 8 `handle*Change` callbacks + `selectLayerFor` |
+| `src/features/browserRunner/useAutoRun.ts` | autorun trio (effects #13–15) + timer refs |
+| `src/shared/shortcuts/useGlobalShortcuts.ts` | the keydown effect + `shortcutsRef` mirror |
+| `src/features/presets/usePresetActions.ts` | the 8 save/import/export/delete handlers (L1352–1707) + repo-backed save orchestration |
+
+**Pure helpers to relocate out of App.tsx** (currently top-of-file, L127–662): `saveRepoBackedConfig`, `fetch*`, `requestCiv7Autoplay`, `mergeDeterministic`, `setAtPath`, `buildConfigSkeleton`, `buildDefaultConfig`, `applyPresetConfig`, `liveSourceMatchesStudio`, etc. → move to `features/*/api.ts` and `features/configOverrides/*`. These ~535 lines are not React at all.
+
+### 4.3 What stays local
+
+`viewportSize`, `headerHeight`, `deckApiReadyTick`/`deckApiRef`, dialog open state, `importInputRef`, all dedupe `*Ref` latches that survive after their effects move into hooks.
+
+---
+
+## 5. Composition smells
+
+1. **Boolean-prop explosion (footer & panels).** `AppFooter` takes `isRunning`, `isRunInGameRunning`, `isSaveDeployRunning`, `isAutoplayActionRunning`, `isDirty`, plus `runInGameCurrentRelation`/`liveGameStudioRelation` string-enums. RecipePanel: `isRunning`, `isRunDisabled`, `isSaveDeployRunning`, `isSaveDisabled`, `isDirty`, `canDeletePreset`, `overridesDisabled`, 4 collapse booleans. These are all **deriveable from store state** — the panels should subscribe to a derived `operationControlsDisabled` selector rather than receive 5 booleans (`architecture-avoid-boolean-props`).
+
+2. **Configuration-over-composition in the panels.** Both panels are documented "fully controlled — all options passed via props" (RecipePanel.tsx:5, ExplorePanel.tsx:5). ExplorePanel receives 6 parallel `{options, selected, onChange}` triples — a textbook case for **compound components** (`<Explore.StageSelect/>`, `<Explore.LayerSelect/>`) sharing context, instead of 38 flat props.
+
+3. **Duplicated select-triple UI.** Stage/Step/DataType/Space/RenderMode/Variant are six structurally identical `Select + label + nav` blocks. Consolidate into one `<LayerDimensionSelect>` driven by a list (`patterns-explicit-variants`), removing copy-paste in ExplorePanel.
+
+4. **Render-prop absence is fine; children-over-config is the win.** The big panels would shrink dramatically if `RecipeConfigPanel`/`ExploreController` composed children rather than App spreading 30+ props (`patterns-children-over-render-props`).
+
+5. **Two sources of truth for step selection.** App `selectedStepId` (L1198) + `vizStore.selectedStepId`, reconciled by sync effects. Collapse to one owner (`state-lift-state` → push to the lower store, vizStore).
+
+6. **`lightMode`/`theme` threaded everywhere.** Should be `ThemeContext` consumed with React 19 `use()` (`react19-no-forwardref`), removing the single most-repeated prop in the tree.
+
+7. **Save-handler triplication.** `handleSaveDialogConfirm` (L1432), `handleSaveToCurrent` (L1487), and the scratch branch each re-implement the same `saveRepoBackedConfigWithState → rememberRepoBackedConfig → setRecipeSettings → toast(success/failure)` sequence with copy-pasted error-message ternaries (L1464–1475, L1517–1528, L1579–1590). Extract one `persistConfigToRepo()` helper.
+
+---
+
+## 6. Top 10 highest-leverage refactors (ranked by robustness × risk-reduction)
+
+> Ordered so that **low-risk extractions land first** and de-risk the high-value but dangerous live-loop migration last.
+
+| # | Refactor | Anchor(s) | Why it's high-leverage | Risk |
+|---|---|---|---|---|
+| 1 | **Extract pure helpers + fetch wrappers out of App.tsx** into `features/*/api.ts` | App.tsx L127–662 (535 LoC of non-React) | Cuts App by ~18% with **zero behavior change**; makes the rest reviewable | Trivial |
+| 2 | **Kill the 8 derived-state effects** (#1,2,10,11,20,21,22 + #12 sync) | L796–818, L820–861, L1232–1235, L1237–1248, L2341–2344, L2363–2371, L2373–2407 | Removes ~120 LoC + 5 `*Ref` latches; eliminates a class of stale-render bugs (`rerender-derived-state-no-effect`) | Low–Med (preset-apply effect #2 has real ordering; verify with snapshot) |
+| 3 | **Make `vizStore` the single owner of step/layer selection**; delete App mirror + sync effect | L1198, L1242–1248 (`eslint-disable exhaustive-deps`) | Removes the most dangerous duplicated-state coupling in the viz path | Medium (touches viz selection — keep DeckCanvas inputs identical) |
+| 4 | **Extract `useExploreSelection` hook** (derivation pyramid + handlers) | L2244–2537 | Moves ~290 LoC into `ExploreController`; ExplorePanel becomes truly presentational; enables compound-component cleanup | Low (pure derivation, no side-effects) |
+| 5 | **Introduce `authoringStore` (Zustand + persist)**; replace 6 useState + persistence effect | L708–793, L868–877; preserve `studioState/persistence.ts` schema | Single source of truth for the authoring model; removes prop-threading to Header/RecipePanel | Medium (localStorage schema parity is load-bearing for refresh recovery) |
+| 6 | **Consolidate save/preset handlers into `usePresetActions`** + one `persistConfigToRepo()` | L1352–1707 (handlers), L1432–1591 (triplicated save) | Removes ~150 LoC of copy-paste; one place to reason about preset↔config↔recipe invariants | Medium (touches the materialization-mode decision that gates durable vs disposable run-in-game) |
+| 7 | **Migrate run-in-game + save/deploy polling to TanStack Query** | L1974–2008 (poll), L1887–1939 (refresh), L1941–1972 (restore) | Deletes 4 effects + 2 refresh callbacks; `refetchInterval` + `initialData` from localStorage; terminal toast → `onSuccess` | Medium (request-id correlation + terminal-toast dedupe must be preserved) |
+| 8 | **Migrate setup-catalog/saved-configs to Query** with `refetchOnWindowFocus` | L1116–1175 | Deletes the hand-rolled focus listener + retry timer; feeds `setupControlOptions` unchanged | Low–Med |
+| 9 | **ThemeContext via React 19 `use()`**; drop `lightMode`/`theme` props | every component; L2782–2929 | Removes the single most-threaded prop across the whole tree | Low |
+| 10 | **Migrate live-runtime poll to Query — LAST, behind parity harness** | **L966–1114** (149-line effect) + refs L895–898 | The live-control heart; collapsing it is the biggest structural win but the highest blast radius | **HIGH** — must keep `shouldCommitLiveRuntimeSnapshot`, `nextLiveRuntimePollDelayMs`, abort + request-key gating **verbatim** inside the queryFn; snapshot tearing + hot-poll regressions are the failure modes |
+
+---
+
+## 7. Load-bearing live-control state (do-not-break registry)
+
+Anything below directly feeds the live game loop or its parity checks; treat as behavior-frozen:
+
+- **`browserRunner` worker lifecycle** (`useBrowserRunner`, L884) — map-gen execution. The `runToken`/`generation` gating (useBrowserRunner.ts:61–63, 128–131) prevents stale-worker event application; preserve exactly.
+- **Live poll gating refs** (L895–898) + `shouldCommitLiveRuntimeSnapshot` (L991) + `nextLiveRuntimePollDelayMs` (L972) — adaptive backoff + snapshot anti-tearing.
+- **Run-in-game fingerprint/relation** (`runInGameCurrentFingerprint` L1755, `runInGameCurrentRelation` L1766, `liveGameStudioRelation` L1775, `studioMatchesProvedLiveSource` L1796) — drive whether "Sync from Live Game" and "Run in Game" are offered; their equality semantics (`configsEqual`, `liveSourceMatchesStudio`) must not change.
+- **`runInGameMaterializationMode`** (L1740) — durable vs disposable decides server-side map materialization; gated on preset `sourcePath` + config equality. Refactor #6 touches this — verify with a fixture.
+- **localStorage request-id bridge** (keys L430–433; restore L1941–1972; writes L2090–2092) — survives dev-server reloads; the persistence schema is a contract.
+- **`vizStore` RAF-batched commit** (vizStore.ts:65–96) — selection-during-streaming defaults; DeckCanvas input stability depends on stable snapshot identity (vizStore.ts:37–45).
+
+---
+
+## 8. Notes on existing structure (what's already good)
+
+- `vizStore.ts` is already a correct external store with stable snapshots — the **template** for the new Zustand stores.
+- `useBrowserRunner`, `useVizState`, `usePresets`, `useThemePreference` are clean, testable hooks. The pattern exists; App.tsx just didn't follow it for the other 5 concerns.
+- Feature folders (`features/*/model.ts`, `status.ts`, `clientState.ts`) already isolate pure logic well — the React layer is the only thing that ballooned.
+- **Dead code:** `useGeneration` and `useViewState` (`ui/hooks/`) are exported but **unused** by App (it uses `useBrowserRunner`/`useVizState` directly). Candidates for deletion during the refactor.
+
+---
+
+### Appendix — metrics
+
+- `App.tsx`: 3,010 LoC; `AppContent`: L676–3001.
+- Hooks in `AppContent`: 42 `useState`, 19 `useRef`, 24 `useEffect`, 34 `useMemo`, 37 `useCallback`.
+- Non-React helper code at top of file: L127–662 (~535 LoC).
+- Largest single effect: live poll L966–1114 (149 LoC).
+- Largest prop surfaces: ExplorePanel ~38, RecipePanel ~30, AppFooter ~30.
+- State libs currently installed: **none** (Zustand + TanStack Query are net-new). React 19.2.
diff --git a/docs/projects/mapgen-studio-redesign/audit/04-design-system.md b/docs/projects/mapgen-studio-redesign/audit/04-design-system.md
new file mode 100644
index 0000000000..ce1e22b705
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/audit/04-design-system.md
@@ -0,0 +1,230 @@
+# 04 — Design System & shadcn Migration Audit
+
+**Scope:** `apps/mapgen-studio` — current Tailwind 3.4 + hand-rolled CVA primitives → full canonical shadcn/ui (Radix, `components.json`, formalized tokens).
+**Evidence base:** `src/index.css`, `tailwind.config.js`, `src/ui/hooks/useTheme.ts`, `src/ui/components/ui/*`, `src/ui/components/fields/*`, `src/features/configOverrides/rjsf*`, `src/App.tsx`. Companion: `apps/mapgen-studio/system.md` (extracted design language).
+**Date:** 2026-06-08.
+
+---
+
+## 0. Three findings that change everything (read first)
+
+1. **Theming is structurally broken, not just inconsistent.** `createTheme()` (`src/ui/hooks/useTheme.ts:130-175`) builds Tailwind classes by **runtime string interpolation** — e.g. `` container: `bg-[${p.bg.page}] text-[${p.text.primary}]` ``. Tailwind 3 JIT scans source statically and **never emits these classes**, so a large chunk of the `Theme` object resolves to class names that don't exist in the stylesheet. The app only looks right because components *also* hardcode the same hex literals directly. This is dead/duplicated infrastructure.
+
+2. **Dark mode uses two conflicting mechanisms.** `tailwind.config.js` has **no `darkMode` key** → Tailwind defaults to `media` (`prefers-color-scheme`). But the app's real dark/light switch is a **`lightMode` boolean prop threaded through 24 files** plus the `Theme` object. The 13 scattered `dark:` utilities key off OS preference while `lightMode` keys off the user's in-app choice → they desync (pick "light" on a dark-OS machine and inputs render with `dark:` styles). shadcn's `.dark` class strategy collapses all of this into one toggle.
+
+3. **The accent declared is not the accent used.** `--color-accent: #5e5ce6` (indigo, `index.css:42`) and `dark.accent: #5e5ce6` (`tailwind.config.js`) are declared as the brand color, but every interactive surface uses **`#4b5563` slate** (19 uses: primary button, switch-on, active tag). The product has no committed accent. This is the #1 reason it reads as commodity.
+
+---
+
+## 1. Token Inventory
+
+### 1a. CSS variables (`src/index.css`)
+| Var | Light | Dark (media) | Verdict |
+|---|---|---|---|
+| `--color-bg-primary` | `#f5f5f7` | `#0a0a12` | → `--background` |
+| `--color-bg-secondary` | `#ffffff` | `#16161d` | → `--card` / `--popover` |
+| `--color-bg-tertiary` | `#f0f0f2` | `#1f1f28` | → `--muted` / `--secondary` |
+| `--color-text-primary` | `#1f2933` | `#e2e2e9` | → `--foreground` |
+| `--color-text-secondary` | `#6b7280` | `#7a7a8c` | → `--muted-foreground` |
+| `--color-text-muted` | `#9ca3af` | `#6a6a7c` | redundant w/ secondary → fold into `--muted-foreground` |
+| `--color-border-primary` | `#e5e7eb` | `#26262e` | → `--border` |
+| `--color-border-secondary` | `#d1d5db` | `#32323e` | → `--input` (input border) |
+| `--color-accent` | `#4b5563` | `#5e5ce6` | → `--primary` (**resolve light/dark mismatch**) |
+| `--color-accent-hover` | `#374151` | `#7472f7` | derive via `--primary` + state, drop |
+| `--spacing-xs…xl` (4–32) | — | — | redundant w/ Tailwind scale → **delete** |
+| `--radius-sm…xl` (4–12) | — | — | → single shadcn `--radius` (+ derived sm/md/lg) |
+| `--transition-fast/normal` | 150/200ms | — | keep as `--duration-*` or Tailwind defaults |
+
+**The values in `index.css` disagree with `useTheme.ts` and `tailwind.config.js`** (e.g. border `#e5e7eb` vs `#e5e5e5` vs `#2a2a32` for dark). `useTheme.ts` is the de-facto truth because components mirror its hex. Consolidate to ONE source: shadcn HSL vars.
+
+### 1b. Tailwind theme extensions (`tailwind.config.js`)
+| Extension | Verdict |
+|---|---|
+| `fontFamily.sans/mono` | **Keep** → maps to `--font-sans` / `--font-mono`. |
+| `colors.light.*` / `colors.dark.*` (nested) | **Delete.** Never referenced as `bg-light-bg-primary` anywhere; pure dead config. Replaced by HSL semantic tokens. |
+| `spacing.18/88` | Audit usage (near-zero) → likely delete. |
+| `borderRadius.xl/2xl` | Replace with shadcn `--radius` derivation. |
+| `transitionDuration.150/200` | Redundant (Tailwind ships `duration-150/200`). Delete. |
+| `animation/keyframes.pulse-subtle` | Keep (used for running state) — move into shadcn `@theme`/animate config. |
+
+### 1c. Target shadcn token map (the canonical set)
+
+Standard shadcn (Tailwind v3 HSL form shown; v4 uses oklch but same names):
+
+```css
+:root {
+  --background: 240 9% 96%;        /* #f5f5f7 */
+  --foreground: 215 25% 16%;       /* #1f2933 */
+  --card: 0 0% 100%;               /* #ffffff */
+  --card-foreground: 215 25% 16%;
+  --popover: 0 0% 100%;
+  --popover-foreground: 215 25% 16%;
+  --primary: 220 13% 34%;          /* #4b5563 — OR commit to indigo, see §6 */
+  --primary-foreground: 0 0% 100%;
+  --secondary: 240 5% 94%;         /* #f0f0f2 */
+  --secondary-foreground: 215 25% 16%;
+  --muted: 240 5% 94%;
+  --muted-foreground: 220 9% 46%;  /* #6b7280 */
+  --accent: 240 5% 94%;
+  --accent-foreground: 215 25% 16%;
+  --destructive: 0 84% 60%;        /* unify rose/red → one */
+  --destructive-foreground: 0 0% 100%;
+  --border: 220 13% 91%;           /* #e5e7eb */
+  --input: 220 13% 91%;
+  --ring: 220 13% 34%;             /* focus ring = primary */
+  --radius: 0.25rem;               /* 4px base — matches `rounded` default */
+}
+.dark {
+  --background: 240 26% 5%;        /* #0a0a0f */
+  --foreground: 240 14% 91%;       /* #e8e8ed */
+  --card: 240 11% 9%;              /* #141418 */
+  --popover: 240 11% 9%;
+  --primary: 220 13% 34%;          /* #4b5563 (or indigo #5e5ce6 = 241 75% 64%) */
+  --secondary: 240 9% 14%;         /* #222228 */
+  --muted: 240 11% 7%;             /* #0f0f12 */
+  --muted-foreground: 240 7% 57%;  /* #8a8a96 */
+  --border: 240 9% 17%;            /* #2a2a32 */
+  --input: 240 9% 17%;
+  --ring: 240 9% 25%;              /* #3a3a44 — current focus border */
+}
+```
+
+Plus the shadcn `cn` util — **already present and correct** at `src/ui/utils/cn.ts` (clsx + tailwind-merge). No change needed; point `components.json` `aliases.utils` at it.
+
+---
+
+## 2. Primitive Migration Table
+
+`components.json` config to target: `style: "new-york"` (matches the dense/tight aesthetic better than "default"), `rsc: false`, `tsx: true`, `tailwind.cssVariables: true`, `aliases.components: "src/ui/components/ui"`, `aliases.utils: "src/ui/utils/cn"`, `iconLibrary: "lucide"` (already the icon set).
+
+| Current primitive | File | shadcn replacement (Radix backing) | a11y / behavior gaps it closes | Call sites to migrate |
+|---|---|---|---|---|
+| **Button** | `ui/Button.tsx` | `button.tsx` (Slot via `@radix-ui/react-slot`, `asChild`) | adds `asChild` composition (today `AlertDialogTrigger` wraps a bare `<span onClick>` — not focusable, not keyboard-activatable). Keep CVA variants. | 2 files, ~2 JSX + indirect via AlertDialog/dropdowns |
+| **Input** | `ui/Input.tsx` | `input.tsx` | drop `lightMode` prop → token classes. | 5 files |
+| **Textarea** | `ui/Textarea.tsx` | `textarea.tsx` | same | 1 file |
+| **Select** (native) | `ui/Select.tsx` | `select.tsx` (`@radix-ui/react-select`) | **typeahead, keyboard nav, ARIA listbox, portal positioning, scroll-into-view**; native select can't be styled per-option or themed in dark portals. | 5 files |
+| **Switch** | `ui/Switch.tsx` | `switch.tsx` (`@radix-ui/react-switch`) | proper `role="switch"`, `aria-checked`, label association without `sr-only` peer hack. | 3 files |
+| **Checkbox** | `ui/Checkbox.tsx` | `checkbox.tsx` (`@radix-ui/react-checkbox`) | removes the fragile `onClick→ref.current.click()` re-dispatch (double-fire risk); real indeterminate state, ARIA. | 2 files |
+| **AlertDialog** | `ui/AlertDialog.tsx` (300+ ln) | `alert-dialog.tsx` (`@radix-ui/react-alert-dialog`) | **focus trap, Esc-to-close, `aria-modal`, focus restore, scroll-lock, portal**, role=alertdialog. Current impl has none. Trigger is a non-button `<span>`. | 2 files (`RecipePanel`, `PresetDialogs` → 3 dialog instances) |
+| **Toast** | `ui/Toast.tsx` | **Sonner** (`sonner`) — shadcn's canonical toast | swipe-dismiss, stacking/queue, `aria-live` region, pause-on-hover, promise toasts. Current is a setTimeout list with no live region. | 1 provider + `useToast`/`showToast` (1 call site each) |
+| **Tooltip** | `ui/Tooltip.tsx` | `tooltip.tsx` (`@radix-ui/react-tooltip`) | collision-aware positioning, delay groups, `role="tooltip"` wiring, keyboard/focus parity, portal (current clips inside `overflow-hidden` panels). | **0 component uses today** — but **28 native `title=` attributes** should migrate to it (see Craft #6). |
+
+**Net:** 8 primitives, ~21 import sites, ~5 dialog/toast instances, 28 `title=` upgrades. Low call-site count = **cheap, high-leverage migration** (the surface is small; the win is correctness + polish).
+
+---
+
+## 3. shadcn components to ADD (hand-rolled or missing)
+
+| Component | Radix backing | Where it lands in the app | Replaces / enables |
+|---|---|---|---|
+| **DropdownMenu** | `@radix-ui/react-dropdown-menu` | RecipePanel Save menu (`RecipePanel.tsx:420-500`), AppHeader Setup menu (`AppHeader.tsx:185+`) | the hand-rolled `fixed inset-0` click-catcher + abs-positioned `<button>` lists. Closes: arrow-key nav, typeahead, Esc, focus return, `role=menu`, collision flip. |
+| **Dialog** | `@radix-ui/react-dialog` | PresetSaveDialog (it's a form-in-modal, not a confirm) → currently misusing AlertDialog (`PresetDialogs.tsx`) | proper non-destructive modal w/ form; AlertDialog stays for confirm/delete only. |
+| **Popover** | `@radix-ui/react-popover` | inline help/info bubbles, the Setup bar (could be a popover instead of an inline expanding row, `AppHeader.tsx`) | richer-than-tooltip transient panels. |
+| **Tabs** | `@radix-ui/react-tabs` | ExplorePanel stage/step/data-type sections; RecipePanel recipe-vs-config | replaces the bespoke collapse/`aria-expanded` group toggles (`ExplorePanel.tsx:445+`) where the relationship is "switch view," not "expand." |
+| **Accordion** | `@radix-ui/react-accordion` | RecipePanel collapsible recipe/config sections (`recipeCollapsed`/`configCollapsed` props), ExplorePanel expandable groups | replaces hand-rolled `collapsed`/`expanded` boolean + ChevronDown rotation pattern; adds ARIA + animation. |
+| **ScrollArea** | `@radix-ui/react-scroll-area` | both side panels + the long rjsf config form + dialog `<pre>` blocks (`.custom-scrollbar` in `index.css`) | replaces hand-CSS `::-webkit-scrollbar` (non-cross-browser); consistent themed overlay scrollbars. |
+| **Separator** | `@radix-ui/react-separator` | the many `border-t`/`w-px h-5` dividers in AppHeader, cards, dropdowns | semantic `role=separator`, orientation; ~10 ad-hoc dividers. |
+| **Slider** | `@radix-ui/react-slider` | rjsf `RangeWidget` (currently aliased to NumberWidget — `rjsfWidgets.tsx`), numeric params with min/max (deck.gl view tuning, ViewControls) | real range UX for bounded numeric schema fields instead of a number box. |
+| **Command** (cmdk) | `cmdk` + Dialog | **NEW**: ⌘K palette to jump stages/steps/presets/data-types. App already owns a keyboard-shortcut layer (`src/shared/shortcuts/`, `App.tsx:2597-2664` toggles panels) — natural home. | currently nothing; biggest "pro tool" upgrade. |
+| **Combobox** (Popover+Command) | composite | AppHeader Config/Leader/Resources selects with long lists (`setupOptions.savedConfigOptions`, `leaderOptions`) | searchable/filterable select; native `<select>` can't search. |
+| **Sheet** | `@radix-ui/react-dialog` (side) | mobile/narrow: left RecipePanel + right ExplorePanel as slide-over drawers | the app toggles left/right panels via shortcuts (`toggleLeftPanel`/`toggleRightPanel`, `App.tsx:2551`) — Sheet is the responsive form of that. |
+| **Resizable** | `react-resizable-panels` | the 3-pane layout (left panel │ map │ right panel) in `App.tsx` (`leftPanel`/`rightPanel`/deck canvas, ~line 2799-2984) | user-draggable panel widths — currently fixed via `LAYOUT` constants. High-value for a data-explorer. |
+| **Skeleton** | (css only) | generation-in-progress / recipe-loading states (see Craft #5) | structured loading instead of opacity pulse. |
+
+---
+
+## 4. rjsf Theming through shadcn
+
+The JSON-schema form is the **largest single surface** (`features/configOverrides/`): `rjsfWidgets.tsx` (widgets) + `rjsfTemplates.tsx` (field/object/array templates) + `ui/components/fields/` (styles). Today it routes through the hand-rolled primitives and a parallel `getFormTheme()`/`getInputStyles()` class-soup that **duplicates** the primitive styling with its own hardcoded hex.
+
+**Strategy — make rjsf a thin adapter over shadcn:**
+
+1. **Widgets → shadcn primitives, drop `lightMode`.** `rjsfWidgets.tsx` already maps `TextWidget/NumberWidget/SelectWidget/CheckboxWidget/SwitchWidget/TextareaWidget/TagSelectWidget` to the `ui/` primitives. Swap each to the shadcn equivalent and **delete the `getLightMode(props)` plumbing and the `lightMode` formContext field** — theming becomes the `.dark` class on `<html>`, so widgets need zero theme awareness. `SelectWidget` should move from native `<select>` to shadcn `Select` (build `SelectTrigger/Content/Item` from `enumOptions`). `RangeWidget` → shadcn `Slider`. `TagSelectWidget` (the hand-rolled pill multiselect) → shadcn `ToggleGroup` (`@radix-ui/react-toggle-group`) for real `aria-pressed` group semantics + roving focus.
+
+2. **Templates → tokens + shadcn surfaces.** `rjsfTemplates.tsx` `getFormTheme()` returns ~10 class strings per mode (card/nested/divider/label/button…). **Delete it entirely** and replace with token classes: `card` → `bg-card border-border`, `nested` → `bg-muted border-border`, `label` → `text-muted-foreground`, `divider` → `Separator`, the inline `<button>Add</button>` and array-item wrappers → shadcn `Button variant="outline" size="sm"` and `Card`. The stage `<section className="rounded-lg border p-2.5">` becomes a shadcn `Card`. Errors (`text-rose-400`) → `text-destructive` (unifies with the rest of the app, which uses `red`).
+
+3. **`fields/styles.ts` + `fields/*Field.tsx` are a third parallel system** — `getInputStyles(lightMode)` re-implements input/select/label classes that the primitives already own. These hand-fields appear largely unused vs the rjsf path; **audit and delete** the duplicate (consolidate to rjsf-widgets-over-shadcn). One styling source, not three.
+
+4. **Scrolling + density:** wrap the form body in shadcn `ScrollArea`; keep the dense `py-1` field rhythm but express it as a `FieldRow` built on shadcn `Label` + token spacing (preserve the 11px/`min-w-[96px]` label column — that density is the design DNA, keep it).
+
+5. **a11y wins for free:** rjsf gives every field an `id`; pairing with shadcn `Label htmlFor` + Radix descriptions wires `aria-describedby` for the `gs.comments`/description/help/error blocks that are currently plain `<div>`s with no association.
+
+Net: rjsf collapses from **3 styling systems (widgets + templates + fields/styles) to 1** (shadcn tokens), and loses the `lightMode` prop entirely.
+
+---
+
+## 5. Craft Findings (top 15)
+
+Ordered by visual leverage.
+
+1. **Commit to an accent (highest leverage).** App declares indigo `#5e5ce6`, uses slate `#4b5563`. Pick one and use it for primary action, focus ring, active state, switch-on, selection. A single deliberate accent is the difference between "a dark dashboard" and "*this* tool." → `--primary` / `--ring`.
+2. **Real focus rings.** Today: `ring-1 ring-gray-400` (Button) / border-color shift (inputs) — a thin gray that's nearly invisible on `#0f0f12`. shadcn pattern: `ring-2 ring-ring ring-offset-2 ring-offset-background` in the accent color. Makes keyboard nav legible and on-brand.
+3. **Dead overlay motion → real motion.** `animate-in fade-in-0 zoom-in-95` is sprinkled on dialog/toast/tooltip but **no `tailwindcss-animate` plugin is installed**, so they don't animate. Add `tailwindcss-animate` (v3) / `tw-animate-css` (v4); Radix `data-[state]` + these classes give the enter/exit the code already asks for.
+4. **Hover/active/disabled depth.** Buttons have hover but many surfaces (dropdown rows, tags, list items) only shift background flatly. Add a 75ms `transition-colors` + a pressed `active:` darken + `active:scale-[0.98]` on primary actions for tactility. Disabled is uniformly `opacity-50` (lazy) — give disabled a distinct muted token treatment, not just transparency.
+5. **Loading state is an opacity pulse.** `animate-pulse-subtle` (whole-element fade) is the only loading affordance, and generation can be slow. Add shadcn **Skeleton** rows for the recipe/config form and an inline progress indicator for the deck.gl generation phase. Structured > pulsing.
+6. **28 native `title=` tooltips.** Browser tooltips are slow, unstyled, untouchable on mobile, and break the dark aesthetic. Migrate to Radix Tooltip (with a `TooltipProvider` delayDuration group). This alone lifts perceived polish across the header/controls.
+7. **Empty states are absent.** No "no presets yet" / "no results" / "select a stage to begin" treatments — empty selects and lists just render blank. Add quiet centered empty states (icon + 11px muted line + optional action).
+8. **Toast → Sonner.** Current toast has no `aria-live` (screen-reader silent), no stacking discipline, no swipe. Sonner is the shadcn-canonical answer and looks intentional out of the box.
+9. **Dark-mode correctness.** The `lightMode`-prop vs `dark:`-utility vs broken `createTheme()` triad means dark mode is partially wrong in mixed-OS scenarios. Moving to `.dark` class makes it *one* correct switch. This is correctness, but it reads as craft because edges stop glitching.
+10. **Destructive color is inconsistent** (`rose-400` in forms, `red-500/600` in buttons, `red-600` in delete menu). Unify to `--destructive`. Inconsistent error color is a classic commodity tell.
+11. **Scrollbars are bespoke + Chromium-only.** `.custom-scrollbar` uses `::-webkit-scrollbar` (invisible in Firefox). Radix ScrollArea gives a themed overlay scrollbar everywhere; also lets you keep the "hide thumb until hover" behavior intentionally.
+12. **Selection/active affordance is weak.** Active tag/stage = slate fill only. Add a left accent bar or ring for the selected stage/step so the user always knows "where am I" in a dense list.
+13. **Hand-rolled dropdowns trap nothing.** The Save/Setup menus close on outside-click but don't trap focus, don't return focus to the trigger, and aren't arrow-navigable. Radix DropdownMenu fixes all three — invisible craft that experts feel immediately.
+14. **Typography hierarchy leans on size alone.** 11 vs 10px is a thin gap; pair size with weight + `text-muted-foreground` opacity tiers so hierarchy survives squint-test. Eyebrow labels already do this well (uppercase+tracking) — extend the discipline to card titles vs body.
+15. **Fonts are render-blocking Google `@import`.** `index.css` `@import url(fonts.googleapis…)` blocks first paint. Self-host Inter + JetBrains Mono (or `<link rel=preconnect>` + `font-display:swap`) — a perf/polish win on a tool people open all day.
+
+---
+
+## 6. Tailwind v3 → v4 Decision
+
+**Recommendation: migrate to Tailwind v4, do it as part of the shadcn init (one cutover), not as a separate later step.**
+
+Rationale:
+- **shadcn fully supports v4** (confirmed current: `@theme` directive, `@theme inline`, oklch token defaults, all components updated, React 19 support). This app is already on **React 19.2** and **Vite 7** — the exact stack v4 targets. Initializing shadcn on v3 now means a forced second migration later.
+- v4 deletes most of `tailwind.config.js` (CSS-first `@theme` in `index.css`) — which is desirable here because the config is mostly **dead** (nested `colors.light/dark` unused, redundant spacing/radius/duration). We're rewriting `index.css` and gutting the config regardless; doing it once into v4 form is strictly less work than v3-then-v4.
+- v4's `@import "tailwindcss"` + `@theme` is where shadcn's token model is heading; staying on v3 means living on the legacy `tailwind.config.js` + `:root{}`/`@media` HSL path that shadcn now treats as the older flow.
+
+**Migration cost (moderate, mostly mechanical):**
+- Replace `@tailwind base/components/utilities` → `@import "tailwindcss";` in `index.css`. **Low.**
+- Move `fontFamily`, `pulse-subtle` keyframes, radius into `@theme` block; delete the rest of `tailwind.config.js`. **Low** (config is largely dead).
+- PostCSS: swap to `@tailwindcss/postcss` (or `@tailwindcss/vite` plugin — cleaner with Vite 7). Drop `autoprefixer`/`postcss` deps v4 bundles. **Low.**
+- Tokens: author as **oklch** (v4 default) instead of HSL — one-time conversion of the §1c values. **Low–medium.**
+- Breaking-change sweep: v4 renames a few utilities (`shadow-sm`→`shadow-xs` etc.), changes default ring width (1px→ none/`ring` now 1px), and removes deprecated opacity-shorthand. The app uses a **small, modern utility set** (no legacy opacity utils found), so exposure is **small**. Budget a focused pass over `shadow-*`, `ring-*`, and `outline` (the `*:focus-visible{outline}` reset in `index.css` interacts with v4 ring changes). **Medium, time-boxed.**
+- Run the official `npx @tailwindcss/upgrade` codemod first to catch the mechanical bits.
+
+**Risk if we stay on v3:** you ship the redesign on the legacy path and re-migrate within a year — paying the breaking-change sweep twice and authoring tokens in HSL then oklch. Net: **v4 now is lower total cost** given the stack is already v4-ready and the config is disposable.
+
+---
+
+## 7. Sequenced execution (suggested)
+1. Migrate Tailwind v3→v4 (codemod + token rewrite to oklch shadcn vars) + `darkMode` via `.dark` class; delete dead config. *(unblocks everything)*
+2. `shadcn init` (`components.json`, `new-york`, point utils at existing `cn.ts`); add `tailwindcss-animate`/`tw-animate-css`.
+3. Replace 8 primitives (≈21 sites) — Button/Input/Textarea/Select/Switch/Checkbox/AlertDialog/Tooltip; Toast→Sonner.
+4. Rip out `lightMode` prop (24 files) + delete broken `createTheme()` interpolation + `fields/styles.ts` duplicate.
+5. rjsf: widgets→shadcn, delete `getFormTheme`/`getInputStyles`, errors→`--destructive`.
+6. Add layout/nav components: DropdownMenu (Save/Setup), Accordion/Tabs (panels), ScrollArea, Separator, Resizable (3-pane), Sheet (responsive), Command (⌘K), Slider (RangeWidget).
+7. Craft pass: accent commit, focus rings, motion, skeletons, empty states, Tooltip-ify 28 `title=`, self-host fonts.
+
+---
+
+## One-screen summary
+
+**Token map at a glance**
+```
+#f5f5f7/#0a0a0f → --background      #1f2933/#e8e8ed → --foreground
+#ffffff/#141418 → --card,--popover  #6b7280/#8a8a96 → --muted-foreground
+#e5e7eb/#2a2a32 → --border,--input   #4b5563(↔#5e5ce6) → --primary,--ring  ⚠ pick ONE
+rose/red mix     → --destructive     4px base → --radius(0.25rem)
+DELETE: createTheme() runtime-interpolated classes (broken), colors.light/dark config (dead),
+        --spacing-*/--radius-* CSS vars (redundant), lightMode prop (24 files), fields/styles.ts
+THEMING: media-query + lightMode-prop + broken Theme obj  →  single .dark class
+```
+
+**Primitive migration:** 8 primitives → Radix-backed shadcn (+Sonner for toast), ≈**21 import sites + 5 dialog/toast instances + 28 `title=`→Tooltip**. Small surface, high correctness gain (focus trap, ARIA, keyboard nav all currently missing).
+
+**Top 3 craft upgrades (most leverage):**
+1. **Commit to one accent** (indigo or slate) across primary/focus/active/selection — the single change that moves it from commodity-dark to branded.
+2. **Real focus rings + working overlay motion** (`ring-2 ring-ring ring-offset` + install the animate plugin the dead `animate-in` classes already expect).
+3. **Migrate 28 native `title=` to Radix Tooltip + Toast→Sonner** — instant perceived-polish lift across the whole chrome.
+
+**Tailwind:** go **v4 now** (stack is React 19 + Vite 7, shadcn supports it, config is mostly dead → cheaper than v3-then-v4 later).
diff --git a/docs/projects/mapgen-studio-redesign/audit/05-server-contracts.md b/docs/projects/mapgen-studio-redesign/audit/05-server-contracts.md
new file mode 100644
index 0000000000..62973a6935
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/audit/05-server-contracts.md
@@ -0,0 +1,158 @@
+# 05 — Server Boundary / API Contract Inventory
+
+**Lane:** server-boundary / API-contract corpus for the `effect-orpc` router migration.
+**Scope:** `apps/mapgen-studio`. Current "server" = hand-rolled `server.middlewares.use("/api/...")` handlers inside `vite.config.ts` (`configureServer`, lines 379–1147) plus helper modules under `src/server/*`. Client calls via raw `fetch` in `src/App.tsx`.
+**Goal:** every endpoint captured so the oRPC router implements exact behavior parity. Cited `file:line` against the snapshot at the head of this branch.
+
+All paths below are relative to `apps/mapgen-studio` unless absolute.
+
+---
+
+## Endpoint corpus
+
+### Conventions shared across all endpoints
+
+- **Server file:** every handler lives in `vite.config.ts` under `configureServer(server)` (line 379).
+- **Body writer:** `writeJson(res, status, body)` (`vite.config.ts:355`) — sets `Content-Type: application/json`, `res.statusCode`, `res.end(JSON.stringify(body))`. Default `Content-Type` is always JSON.
+- **JSON body reader:** `readJsonBody` (`vite.config.ts:289`) or inline chunk-accumulate (`vite.config.ts:1060`).
+- **Method gate:** each handler does `if (req.method !== "<M>") return next();` — non-matching methods fall through to Vite (no 405; effectively 404 from Vite SPA fallback). **Parity note:** oRPC must reproduce "wrong method → not handled here" rather than emit 405.
+- **No auth, no CORS headers, no request-id header.** Identity is internal only (see `studio/server-info`, run-in-game `serverInstanceId`).
+- **Tuner timeout:** `DEFAULT_CIV7_TUNER_TIMEOUT_MS = 10_000` (`@civ7/direct-control`), referenced on nearly every Civ7 call.
+
+---
+
+| # | Method + Path | Purpose | Request shape | Response shape (success) + status codes | Side effects | Helpers (`src/server/*` + `@civ7/direct-control`) | Client call site → consumer | Effect service mapping | Parity risk |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | `GET /api/civ7/status` | Civ7 playable status probe | none | `200 {ok: status.playable, status: PlayableStatus}`; `500 {ok:false, error}` | reads FireTuner socket (`getCiv7PlayableStatus`) | `getCiv7PlayableStatus` (`vite.config.ts:383`) | **No client caller** (server-only / dead or external). | `Civ7TunerClient.playableStatus()` | low — read-only; needs tuner socket ctx |
+| 2 | `GET /api/civ7/map-summary` | Current map summary w/ area & region counts | none | `200 {ok:true, summary: MapSummary}`; `500 {ok:false,error}` | reads FireTuner socket | `getCiv7MapSummary({includeAreaRegionCounts:true})` (`vite.config.ts:395`) | **No client caller.** | `Civ7TunerClient.mapSummary()` | low |
+| 3 | `GET /api/civ7/gameinfo?table=&limit=` | Read a GameInfo DB table | query: `table` (string, **required**), `limit` (number, default `100`) | `200 {ok:true, rows}`; `400 {ok:false,error}` (also for missing `table`) | reads FireTuner socket | `getCiv7GameInfoRows` (`vite.config.ts:412`) | **No client caller.** | `Civ7TunerClient.gameInfoRows(table,limit)` | low — note error status is **400** not 500 |
+| 4 | `GET /api/civ7/live/status` | Aggregated live runtime status (status+appUi+mapSummary+autoplay) | none | `200 {ok, playable, observedAt, status, appUi, mapSummary, autoplay}` — `ok = playableStatus && readiness!=="unavailable"`; per-field `{error}` on partial failure via `Promise.allSettled`; `500 {ok:false,error}` only on outer throw | reads FireTuner socket (4 parallel `allSettled` calls) | `getCiv7PlayableStatus`, `getCiv7AppUiSnapshot`, `getCiv7MapSummary`, `getCiv7AutoplayStatus` (`vite.config.ts:424`) | `App.tsx:1042` (poll) → `buildLiveRuntimeStatusState`, drives `liveRuntime` state | `Civ7LiveStatus.snapshot()` aggregating `Civ7TunerClient` | **medium** — partial-failure envelope (`allSettled` → per-field `{error: String(reason)}`) and `ok`/`observedAt` derivation must be byte-identical |
+| 5 | `GET /api/civ7/live/snapshot?x=&y=&width=&height=&fields=&playerId=&maxPlots=` | Map-grid tile window snapshot | query: `x`(0),`y`(0),`width`(24),`height`(18),`fields`(csv, default `terrain,biome,feature,resource,visibility,owner`),`playerId`(opt → number or omitted),`maxPlots`(clamp 1..512, default 512) | `200 {ok:true, observedAt, grid}`; `400 {ok:false,error}` | reads FireTuner socket | `getCiv7MapGrid` (`vite.config.ts:448`) | `App.tsx:986` (`readSnapshot`) → `buildLiveRuntimeSnapshotState`, `liveRuntimeSnapshot` state | `Civ7TunerClient.mapGrid(bounds,fields,...)` | **medium** — query parsing/clamping/defaults (esp. `maxPlots` clamp, `fields` csv split/trim/filter, `playerId` null→omit) must be exact |
+| 6 | `GET /api/civ7/live/entities?playerId=&maxItems=` | Players + units + cities summary | query: `playerId`(opt→number/omit), `maxItems`(clamp 1..128, default 128) | `200 {ok:true, observedAt, players, units, cities}`; `400 {ok:false,error}` | reads FireTuner socket (3 parallel `Promise.all`) | `getCiv7PlayerSummary`,`getCiv7UnitSummary`,`getCiv7CitySummary` (`vite.config.ts:478`) | **No client caller.** | `Civ7TunerClient.entities(...)` | low–medium — `Promise.all` (not allSettled): any failure → whole 400 |
+| 7 | `GET /api/civ7/live/gameinfo?tables=&limit=` | Multi-table GameInfo dump | query: `tables`(csv, default `Terrains,Biomes,Features,Resources,Maps,MapSizes`, **slice(0,8)**), `limit`(clamp 1..200, default 100) | `200 {ok:true, observedAt, tables: Record<table,rows>}`; `400 {ok:false,error}` | reads FireTuner socket (N parallel) | `getCiv7GameInfoRows` ×N (`vite.config.ts:496`) | **No client caller.** | `Civ7TunerClient.gameInfoTables(...)` | low–medium — 8-table cap + `Object.fromEntries` shape |
+| 8 | `POST /api/civ7/autoplay` | Start/stop autoplay (verified) | body: `{action: "start"|"stop"}` | `200 {ok: result.verified, action, autoplay, game, gameContext, result}`; `400` (bad action); `409` (run-in-game OR save/deploy active, with `details.code`); `500 {ok:false,error}` | reads FireTuner socket; **mutates game state** (start/stop autoplay); waits on scripting log markers (`waitTimeoutMs=90s`) | `startCiv7Autoplay`/`stopCiv7Autoplay` w/ `approval={approved,reason,disposableSession:true}` (`vite.config.ts:515`) | `App.tsx:409` (`requestCiv7Autoplay`) → autoplay UI toggle | `Civ7Autoplay.start/stop()` + reads `OperationRegistry` for 409 guard | **HIGH** — cross-operation mutex (409 if run-in-game or save/deploy active), `verified` semantics, approval object, log-wait timing |
+| 9 | `GET /api/studio/server-info` | Server identity / API version | none | `200 {ok:true, serverInstanceId, startedAt, runInGameApiVersion:2, viteCommand}` | none (pure) | uses module-level `STUDIO_SERVER_INSTANCE_ID`, `STUDIO_SERVER_STARTED_AT` (`vite.config.ts:575`) | **No client caller.** | `StudioServerInfo` layer (process-lifetime singleton) | medium — `serverInstanceId`/`startedAt` are stable per process; clients reconcile run-in-game state against these. Must remain a per-process singleton in Effect. |
+| 10 | `GET /api/civ7/setup-config` | Civ7 setup-screen snapshot | none | `200 {ok:true, observedAt, setup, state, host, port}`; `503 {ok:false,error,observedAt}` | reads FireTuner socket | `getCiv7SetupSnapshot` (`vite.config.ts:585`) | `App.tsx:303` (`fetchCiv7SetupConfig`, abortable) → consumes `body.setup` | `Civ7TunerClient.setupSnapshot()` | low — note **503** on failure (unique), exposes `host`/`port` |
+| 11 | `GET /api/civ7/saved-configs` | List saved game configurations | none | `200 {ok:true, observedAt, ...listResult(directory,configurations)}`; `500 {ok:false,error,observedAt}` | reads filesystem (Civ7 saved config dir) | `listCiv7SavedGameConfigurations` (`vite.config.ts:602`) | `App.tsx:348` (`fetchCiv7SavedSetupConfigs`) → consumes `directory`,`configurations` | `Civ7SavedConfigStore.list()` (fs ctx) | low |
+| 12 | `GET /api/civ7/setup-catalog` | Leaders/civs/difficulties/speeds catalog from XML | none | `200 {ok:true, catalog: Civ7SetupCatalog}`; `500 {ok:false,error,observedAt}` | reads filesystem: repo `.civ7/outputs/resources` + Steam app Resources dir (macOS path) | `loadCiv7SetupCatalog({repoRoot})` (`vite.config.ts:616`, `src/server/civ7Resources/catalog.ts`) | `App.tsx:380` (`fetchCiv7SetupCatalog`) → catalog dropdowns | `Civ7ResourceCatalog.load()` (needs `repoRoot` + `appResourcesRoot` ctx) | medium — `repoRoot` derived from `import.meta.url`; app-resources root is **macOS/homedir-specific**; merge/precedence (app-resources overrides mirror) must hold |
+| 13 | `GET /api/civ7/run-in-game/status?requestId=` | Poll run-in-game operation state | query: `requestId` (**required**) | `200 RunInGameOperationState`; `400 {ok:false,error:"Missing requestId"}`; `404 {ok:false,error, serverInstanceId, serverStartedAt}` | reads in-memory op store (prunes TTL) | `runInGameOperations.get` (`vite.config.ts:627`, `runInGame/operationState.ts`) | `App.tsx:287` (`fetchRunInGameStatus`, polled while running) | `RunInGameOperations.get(requestId)` | **HIGH** — 404 includes `serverInstanceId`/`serverStartedAt` so client detects server restart (lost op). State machine + TTL pruning must be ported exactly. |
+| 14 | `POST /api/civ7/run-in-game` | Launch current/selected config in Civ7 (full pipeline) | body: `{recipeId, seed, mapSize, playerCount?, resources?, materialization:{mode}, recovery:{restartCivProcess?}, setupConfig, config, sourceSnapshot?, selectedConfig:{id,label,description,sourcePath,sortIndex,latitudeBounds}}` | `202 RunInGameOperationState` (accepted, async); `202` dup (same fingerprint, `details.duplicateRequest`); `409` (another run-in-game OR save/deploy active); `400`/`500`/`503` on validation/pipeline error via `RunInGameHttpError` (`details` carries code/materialization/recovery boundaries) | **MASSIVE.** Writes repo config file (`mods/.../src/maps/configs/*.config.json`); spawns `bun ... deploy:studio` (process); spawns `bun ... gen:maps` (regen, always in `finally`); reads/writes FireTuner socket; reads scripting log file; **optionally restarts Civ7 process via Steam (macOS only: osascript quit + pkill + `open steam://`)**; serialized through `studioOperationQueue` | `parseRunInGameSetupRequest`, `makeRepoMapEnvelope`, `assertRepoMapEnvelope`, `materializeRunInGameConfig`, `deploySwooperMapsForRun`, `regenerateSwooperMapArtifacts`, `restartCiv7ProcessViaSteam`→`shutdownCiv7MacProcess`/`launchCiv7MacViaSteamWithRetries`, `ensureCiv7SetupMapRowVisible`, `runCiv7SinglePlayerFromSetup`, `waitForFreshLogMarkers`, `waitForCiv7MapgenLogFailure`, `parseSwooperMapgenLogProof`, `buildRunInGame*Proof`, `fileIdentity`, `runInGameOperations.*` (`vite.config.ts:647`) | `App.tsx:251` (`runCurrentConfigInGame`) → kicks off, then polls #13 | `RunInGamePipeline.start(req)` orchestrating `MapConfigStore` + `DeployRunner` + `Civ7ProcessControl` + `Civ7TunerClient` + `ScriptingLog` + `ProofBuilder` + `OperationRegistry` | **HIGHEST** — see §"Hard parity cases". Operation state machine (9 phases), fingerprint dedup→202, dual mutex→409, proof identity (log markers + file sha256 + envelope/config hashes), log-failure classification, macOS process restart, disposable cleanup+regen in `finally`, serialized queue. |
+| 15 | `GET /api/map-configs/status?requestId=` | Poll save/deploy operation state | query: `requestId` (**required**) | `200 MapConfigSaveDeployStatus`; `400` (missing); `404 {ok:false,error}` | reads in-memory op store (TTL prune) | `saveDeployOperations.get` (`vite.config.ts:1042`, `mapConfigs/operationState.ts`) | `App.tsx:213` (`fetchMapConfigSaveDeployStatus`, polled) | `MapConfigOperations.get(requestId)` | medium — 404 here does **not** include serverInstanceId (asymmetry vs #13); preserve. |
+| 16 | `POST /api/map-configs` | Save config to repo + deploy (no Civ restart) | body: `{requestId?, id, sourcePath?, envelope, restart?, verifyRestart?}` (restart/verifyRestart **must be falsy** → else 400) | `202 MapConfigSaveDeployStatus` (async); `202` (idempotent: same active requestId returns current); `409` (run-in-game active OR different save/deploy active); `400 {ok:false,error}` on validation | Writes repo config file; spawns `bun ... deploy:studio`; on deploy failure **restores previous file content**; serialized via `studioOperationQueue` | `parseMapConfigSaveRequest`, `assertRepoMapEnvelope`, `deploySwooperMaps`, `restoreRepoConfig`, `saveDeployOperations.*` (`vite.config.ts:1057`) | `App.tsx:168` (`saveRepoConfig`→`/api/map-configs`), then polls #15 | `MapConfigPipeline.saveDeploy(req)` over `MapConfigStore` + `DeployRunner` + `MapConfigOperations` | **HIGH** — write-then-deploy with rollback on deploy-phase failure; idempotent requestId reuse; cross-op mutex with run-in-game; path-jail (`configRoot` prefix + `.config.json` suffix). |
+
+**Endpoint count: 16** (8 with live client callers; 8 server-only/no caller — `civ7/status`, `civ7/map-summary`, `civ7/gameinfo`, `civ7/live/entities`, `civ7/live/gameinfo`, `studio/server-info` are not fetched anywhere in `src/`; they must still be ported for parity / external tooling).
+
+> Stale doc-only references (`POST /api/generate`, `POST/GET /api/presets`) appear in `src/ui/types/index.ts:279,304,316` as comments — **no implementation, no caller.** Not endpoints; do not port.
+
+---
+
+## Helper module → behavior reference (for the implementer)
+
+- **`runInGame/operationState.ts`** — in-memory `Map<requestId, state>` store. `create/update/complete/fail/findActive/get/prune`. TTL-prune on every access (`RUN_IN_GAME_OPERATION_TTL_MS = 30min`). `update` auto-advances `completedPhases`, computes `status` from phase (`statusForPhase`), computes `recoveryActions` (`recoveryActionsFor`). `fail` classifies into `blocked`/`failed`/`uncertain` (`classifyRunInGameFailure`: 409→blocked; timeout/socket-closed during starting-game/waiting-for-proof→uncertain). `RunInGameHttpError(statusCode, message, details)`.
+- **`mapConfigs/operationState.ts`** — analogous store for save/deploy. Phases `queued|saving|deploying|complete|failed`. Same TTL.
+- **`mapConfigs/deploy.ts`** — `buildSwooperMapsStudioDeployCommand({requestId?})` → `{command, args:["run","--cwd","mods/mod-swooper-maps","deploy:studio"], env}`. When `requestId` set, injects `SWOOPER_STUDIO_RUN_ID` env var (used downstream to stamp log proof).
+- **`mapConfigs/requestValidation.ts`** — `parseMapConfigSaveRequest`: rejects `restart/verifyRestart===true`; id kebab-case; requestId pattern `^[a-zA-Z0-9._:-]+$`.
+- **`runInGame/requestValidation.ts`** — `parseRunInGameSetupRequest`: `assertNoRawControlFields` (deep scan rejecting `command|script|javascript|rawJs|rawCommand` keys — **security boundary**); recipe pinned `mod-swooper-maps/standard`; mode `durable|disposable`; id kebab-case (`studio-current` for disposable); seed via `parseCiv7StudioSeed`; mapSize `MAPSIZE_*`; playerCount 1..64; `restartCivProcess`; `normalizeStudioSetupConfig`.
+- **`runInGame/proofIdentity.ts`** — `fileIdentity` (sha256+size+mtime), `parseDeployTargetDir` (`/Deployed to:\s*(.+)$/m`), `buildRunInGameSourceSnapshotProof`, `buildRunInGameExactAuthorshipProof`, `parseSwooperMapgenLogProof`. All hashing is `sha256` over canonicalized JSON.
+- **`runInGame/logFailure.ts`** — `classifyCiv7MapgenLogFailure` (regex over fresh scripting-log text → `map-script-load-failed` | `map-generation-script-failed`, with `dismissNotificationRequired`/`recoveryBoundary`), `waitForCiv7MapgenLogFailure` (poll loop w/ grace window).
+- **`runInGame/macosProcessRestart.ts`** — pure(ish) functions taking injected `execFileAsync`/`sleep`/`tail`: `shutdownCiv7MacProcess` (osascript quit → pkill -f → pkill -9 -f, each with exit-poll), `launchCiv7MacViaSteamWithRetries` (`open steam://rungameid/1295660`, retries), `waitForMacProcessExit/Start`, `isMacProcessRunning` (pgrep). **macOS-only**, `Civ7MacSteamLaunchError`.
+- **`civ7Resources/catalog.ts`** — `loadCiv7SetupCatalog({repoRoot, appResourcesRoot?})`: scans repo mirror + Steam app Resources, regex-parses Setup XML `<Row>`s, dedups (app-resources wins), sorts. `DEFAULT_CIV7_APP_RESOURCES_ROOT` is **homedir/macOS Steam path**.
+- **`@civ7/direct-control`** — FireTuner socket client. Defaults: host `127.0.0.1`, port `4318` (env `CIV7_TUNER_HOST`/`CIV7_TUNER_PORT`), timeout `10s`. `DEFAULT_CIV7_SCRIPTING_LOG` (env `CIV7_SCRIPTING_LOG`). `createCiv7ControlRequestId(prefix)`.
+
+---
+
+## Proposed oRPC router shape
+
+Contract-first. The existing helper modules already separate pure validation/state from IO; oRPC's contract-first mode (Zod/TypeBox schemas in a `contract/`, implementation in handlers that `provide` Effect layers) maps cleanly and lets the no-caller endpoints retain their exact response schemas as a published surface. The feature `status.ts` types (`RunInGameOperationStatus`, `MapConfigSaveDeployStatus`, `Civ7SetupCatalog`, etc.) become the canonical output schemas — reuse them so client typings don't drift.
+
+Namespaced procedures (preserve path → procedure mapping so the client `fetch` migration is mechanical; mount the OpenAPI handler at `/api` so legacy paths keep working during cutover):
+
+```
+civ7.status                      GET  /api/civ7/status            (#1)
+civ7.mapSummary                  GET  /api/civ7/map-summary       (#2)
+civ7.gameInfo                    GET  /api/civ7/gameinfo          (#3)
+civ7.live.status                 GET  /api/civ7/live/status       (#4)
+civ7.live.snapshot               GET  /api/civ7/live/snapshot     (#5)
+civ7.live.entities               GET  /api/civ7/live/entities     (#6)
+civ7.live.gameInfo               GET  /api/civ7/live/gameinfo     (#7)
+civ7.autoplay                    POST /api/civ7/autoplay          (#8)
+civ7.setupConfig                 GET  /api/civ7/setup-config      (#10)
+civ7.savedConfigs                GET  /api/civ7/saved-configs     (#11)
+civ7.setupCatalog                GET  /api/civ7/setup-catalog     (#12)
+runInGame.start                  POST /api/civ7/run-in-game       (#14)
+runInGame.status                 GET  /api/civ7/run-in-game/status(#13)
+mapConfigs.saveDeploy            POST /api/map-configs            (#16)
+mapConfigs.status                GET  /api/map-configs/status     (#15)
+studio.serverInfo                GET  /api/studio/server-info     (#9)
+```
+
+Namespaces: **`civ7`** (tuner reads + autoplay), **`civ7.live`** (live runtime sub-namespace), **`runInGame`**, **`mapConfigs`**, **`studio`**.
+
+### Effect services / layers
+
+| Service | Responsibility | Context needed |
+|---|---|---|
+| `Civ7TunerClient` | All FireTuner socket reads + autoplay mutation (wraps `@civ7/direct-control`) | host/port (`CIV7_TUNER_HOST/PORT`, default 127.0.0.1:4318), timeout |
+| `Civ7LiveStatus` | Aggregates #4/#6/#7 with `allSettled`/`all` semantics | depends on `Civ7TunerClient` |
+| `Civ7ResourceCatalog` | #12 XML catalog | `repoRoot`, `appResourcesRoot` (macOS homedir default) |
+| `Civ7SavedConfigStore` | #11 saved-game fs listing | Civ7 saved-config dir (fs) |
+| `MapConfigStore` | repo `*.config.json` read/write + path-jail + rollback | `repoRoot`, configRoot jail |
+| `DeployRunner` (a.k.a. `ProcessControl`) | spawns `bun deploy:studio` / `gen:maps` | `repoRoot`, env (incl. `SWOOPER_STUDIO_RUN_ID`), timeouts, maxBuffer |
+| `Civ7ProcessControl` | macOS quit/pkill/Steam-relaunch | macOS only; Steam app id, process pattern, all timeout consts |
+| `ScriptingLog` | scripting-log snapshot/diff + fresh-marker wait + failure classify | `CIV7_SCRIPTING_LOG` path |
+| `ProofBuilder` | sha256 file identity + log-proof + authorship proof | `repoRoot` |
+| `RunInGameOperations` / `MapConfigOperations` | in-memory TTL stores (state machines) | TTL, `serverInstanceId`, `serverStartedAt`, `now` clock |
+| `OperationQueue` | serializes run-in-game + save/deploy (single `studioOperationQueue`) | shared singleton |
+| `StudioServerInfo` | #9 identity singleton | per-process `serverInstanceId`/`startedAt`/`viteCommand` |
+
+---
+
+## Context / middleware needs
+
+- **Auth:** none today. No middleware needed; do **not** add auth (parity).
+- **Request-id / proof identity:** server mints `createCiv7ControlRequestId(prefix)` per operation (NOT per HTTP request). This is *operation identity*, lives in the op-store, and is echoed in 404s as `serverInstanceId/serverStartedAt`. Model as service-level (`OperationRegistry`), not transport middleware. There is no incoming request-id header to honor.
+- **Logging:** none structured today (handlers swallow into `{ok:false,error}`). Optional to add Effect logging, but error envelopes must stay identical.
+- **Error mapping middleware:** central need. Today errors map ad-hoc per endpoint: `RunInGameHttpError.statusCode/details` (#14), fixed codes elsewhere (#3 `400`, #10 `503`, #11/#12 `500`). An oRPC error-mapping interceptor must translate Effect failures → the **exact** status code + `{ok:false, error, details?}` body per endpoint (status codes are NOT uniform — preserve the table above). Note partial-failure endpoints (#4) return **200** with embedded per-field errors — these are *not* errors at the transport layer.
+- **Env/config injection:** a `StudioConfig` layer providing `repoRoot` (from `import.meta.url`/cwd), tuner host/port, scripting-log path, app-resources root, Steam app id, process pattern, and all the timeout constants (`vite.config.ts:59–76`). These are currently module-level consts — centralize them.
+- **Singletons:** `serverInstanceId`, `serverStartedAt`, the two op-stores, and `studioOperationQueue` must be **process-lifetime singletons** (one Effect `Layer.scoped`/runtime, not per-request). Client restart-detection depends on `serverInstanceId` stability.
+
+---
+
+## The hard parity cases
+
+### 1. Operation state machines (`RunInGameOperations`, `MapConfigOperations`) — #13/#14/#15/#16
+- Run-in-game phases (`materializing → deploying → restarting-civ? → checking-civ7 → reload-needed? → preparing-setup → starting-game → waiting-for-proof → complete`) with derived `status`, accumulating `completedPhases`, and computed `recoveryActions` (`recoveryActionsFor` — includes `exit-to-shell-and-continue`, `restart-civ-process-and-retry`, `dismiss-civ-notification-and-retry` driven by `details` flags).
+- Failure classification (`classifyRunInGameFailure`): `409→blocked`; `response-timeout`/`socket-closed`/`connection-timeout`/`all-hosts-unavailable` during `starting-game`/`waiting-for-proof` → **`uncertain`** (the operation may have succeeded — client must not retry blindly). Everything else `failed`.
+- TTL pruning (30 min) on every store access; pruned op → 404.
+- **Move to Effect:** a `Ref`-backed store inside a scoped layer. Keep `now` injectable for tests. The phase-advance/`completedPhases`/`recoveryActions` derivation is pure — port verbatim from `operationState.ts`. Status codes for status-poll (200/400/404) and the **404 `serverInstanceId/serverStartedAt` echo** must be preserved.
+
+### 2. `macosProcessRestart` — #14 (`recovery.restartCivProcess`)
+- Sequence: `osascript` graceful quit → poll exit (45s) → `pkill -f` → poll (30s) → `pkill -9 -f` → poll (15s); then `open steam://rungameid/1295660` with up to 6 attempts × 20s start-wait; then poll `getCiv7SetupSnapshot` until `phase==="shell"` (180s). Hard-fails if shell not reached.
+- **macOS-only guard** (`process.platform !== "darwin"` throws).
+- **Move to Effect:** `Civ7ProcessControl` layer with injected `execFileAsync`/`sleep` (already injected in the helper — port mechanically). Preserve every timeout constant and the exact command strings (they appear in the `processRestart` proof payload returned to the client). Keep the platform guard as a typed failure.
+
+### 3. `proofIdentity` — #14
+- The "exact authorship proof" chains: `sourceSnapshot` hash → `configHash`/`envelopeHash` (sha256 of canonicalized JSON, `vite.config.ts:94–108`) → file identities (`fileIdentity`: sha256+size+mtime of generated source / local mod / deployed mod scripts) → setup row proof → start map summary → **log proof** (`parseSwooperMapgenLogProof` matching markers `[mapgen-proof]`, requestId, configHash, envelopeHash, `[mapgen-complete]` in the fresh scripting log, with `rejectPattern` for TextEncoder/Uncaught/Exception/Error).
+- This is the integrity contract: it proves the map that ran is *exactly* the authored config. Hashing must be byte-identical (same canonicalization, same field ordering, same sha256).
+- **Move to Effect:** a pure `ProofBuilder` service (no IO except `fileIdentity` which needs fs). Port `canonicalize`/`stableHash` and all `build*Proof`/`parse*Proof` functions unchanged. Any drift in JSON key ordering or hash input breaks proof verification.
+
+### 4. `logFailure` capture — #14
+- After a launch or proof-wait throws, the pipeline races a **grace-window poll** (`SCRIPTING_LOG_FAILURE_GRACE_MS=5s`, `250ms` interval) reading *fresh* scripting-log text (diffed against a pre-launch `snapshotFile`) and classifies `map-script-load-failed` vs `map-generation-script-failed`, attaching `dismissNotificationRequired`/`recoveryBoundary:"civ-notification-dismiss"`. This converts an opaque tuner error into an actionable `RunInGameHttpError(500, ...)` with recovery hints.
+- **Move to Effect:** `ScriptingLog` service holding the pre-launch snapshot in scope; `waitForCiv7MapgenLogFailure`/`classifyCiv7MapgenLogFailure` are pure over text — port verbatim. Timing (grace + interval) and the diff-from-snapshot semantics (`logTextFromSnapshot`/`readFreshLogText`) must be preserved or proof/failure detection flakes.
+
+### 5. Serialized operation queue + dual mutex — #8/#14/#16
+- A single module-level `studioOperationQueue` Promise chains run-in-game and save/deploy so they never overlap; additionally each entrypoint checks `findActive()` on **both** stores and returns `409` (with `details.code = run-in-game-operation-active` | `save-deploy-operation-active`). Run-in-game also dedups identical `requestFingerprint` → `202` instead of `409`. Autoplay (#8) is gated by both stores too.
+- **Move to Effect:** an `OperationQueue` service (`Effect.Semaphore` of permit 1) plus mutex checks reading both registries. Preserve: fingerprint→202 dedup, 409 `details` shapes, and that the actual work runs **after** the 202/202 response is sent (fire-and-forget via the queue), which the status-poll endpoints then observe.
+
+---
+
+## One-screen summary
+
+- **Endpoint count: 16** (`vite.config.ts` `configureServer`, lines 379–1147). 8 have live `src/App.tsx` callers; 8 are server-only with no current client caller but must still be ported. Stale `/api/generate` + `/api/presets` are comment-only — not real.
+- **Router namespaces:** `civ7.*` (status, mapSummary, gameInfo, autoplay, setupConfig, savedConfigs, setupCatalog), `civ7.live.*` (status, snapshot, entities, gameInfo), `runInGame.*` (start, status), `mapConfigs.*` (saveDeploy, status), `studio.*` (serverInfo). Contract-first, OpenAPI handler mounted at `/api` so legacy paths stay live during cutover.
+- **Top 3 parity-risk endpoints:**
+  1. **`POST /api/civ7/run-in-game` (#14)** — the whole hard-parity surface: 9-phase state machine, fingerprint dedup→202, dual mutex→409, sha256 proof identity, log-failure classification, macOS Steam process restart, disposable cleanup+regen in `finally`, serialized queue.
+  2. **`GET /api/civ7/run-in-game/status` (#13)** — restart-detection contract: 404 echoes `serverInstanceId`/`serverStartedAt`; `uncertain`/`blocked` failure classes; TTL pruning. Drift here corrupts the client's recovery UX.
+  3. **`POST /api/map-configs` (#16)** — write-then-deploy with **rollback on deploy-phase failure**, idempotent requestId reuse, cross-op mutex with run-in-game, and the config-path jail.
+
+  (Honorable mention: **`POST /api/civ7/autoplay` (#8)** for its `verified` semantics + dual-store 409 mutex + log-wait timing.)
diff --git a/docs/projects/mapgen-studio-redesign/audit/06-typescript-rigor.md b/docs/projects/mapgen-studio-redesign/audit/06-typescript-rigor.md
new file mode 100644
index 0000000000..7dba1dfdee
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/audit/06-typescript-rigor.md
@@ -0,0 +1,144 @@
+# 06 — TypeScript Rigor Audit
+
+**App:** `apps/mapgen-studio`
+**Lane:** TypeScript-rigor (effect-orpc → typed oRPC client → TanStack Query → React)
+**Date:** 2026-06-08
+**Method:** `dev:typescript` skill lens; grep inventory + `tsc --noEmit`. All evidence cited `file:line`.
+
+---
+
+## TL;DR
+
+- **Typecheck: CLEAN.** `bun run --cwd apps/mapgen-studio check` (`tsc --noEmit`) exits **0**, **0 errors**. The floor is honest today — this is a green-field rigor raise, not a cleanup.
+- **`any` total: 21** — `: any` ×6, `as any` ×14, `<any>` ×1. No `any[]`, no `Array<any>`. Genuinely low.
+- **`as` casts (typed): 126** + `as unknown` ×19 + `as const` ×29. Non-null `!`: ~17 (almost all guarded array-index access).
+- **~10–12 casts evaporate for free** once the typed oRPC client lands (every `res.json() as <ad-hoc>` in `App.tsx`). The bulk (RJSF/JSON-Schema, deck.gl typed arrays, deliberate `unknown` recipe boundary) need explicit work or are intentional.
+- **Top 3 tsconfig flags to enable:** `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `verbatimModuleSyntax`.
+
+---
+
+## 1. tsconfig strictness
+
+`apps/mapgen-studio/tsconfig.json` is **standalone** — it does NOT extend `tsconfig.base.json`. It is already above average: `strict: true`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`, `noUncheckedSideEffectImports`, `isolatedModules`, `moduleDetection: force`.
+
+### Present
+| Flag | Value |
+|---|---|
+| `strict` (→ `noImplicitAny`, `strictNullChecks`, etc.) | ✅ true |
+| `noUnusedLocals` / `noUnusedParameters` | ✅ true |
+| `noFallthroughCasesInSwitch` | ✅ true |
+| `noUncheckedSideEffectImports` | ✅ true |
+| `isolatedModules` | ✅ true |
+
+### Missing — gaps for top-1% rigor
+| Flag | Status | Why it matters here |
+|---|---|---|
+| **`noUncheckedIndexedAccess`** | ❌ missing | The ~17 `!` assertions (`ExplorePanel.tsx:297`, `era.ts:41/44`, `presentation.ts:321/354/418-422`, `worker-viz-dumper.ts:14-15`) are all guarded array-index access that *look* safe only because indexing returns `T` not `T | undefined`. With this on, those become honest `T | undefined` and the compiler forces the guard. Highest-leverage flag for this codebase. |
+| **`exactOptionalPropertyTypes`** | ❌ missing | The fetch-body types use `Partial<X> & { error?: string }` and the server validators build `...(cond ? { x } : {})` (`requestValidation.ts:43-47`). Without this, `{ x?: string }` silently accepts `{ x: undefined }`, blurring "absent" vs "present-but-undefined" — exactly the distinction Effect Schema / oRPC contracts will encode. |
+| **`verbatimModuleSyntax`** | ❌ missing | Already used by a sibling package (`packages/mapgen-viz/tsconfig.json:7`). Forces `import type` discipline — critical once the oRPC contract package is imported on both client and server; prevents accidental value imports of server-only types into the browser bundle. |
+| `noImplicitReturns` | ❌ missing | Cheap addition; catches missing-return paths in the many branchy handlers in `App.tsx`. |
+| `noPropertyAccessFromIndexSignature` | ❌ missing | Pairs with `noUncheckedIndexedAccess` for record-shaped config access. |
+
+`noImplicitAny` is already on transitively via `strict`. `skipLibCheck: true` is acceptable (deck.gl / RJSF type perf), keep it.
+
+### Recommended config
+```jsonc
+{
+  "compilerOptions": {
+    // ...existing...
+    "strict": true,
+    "noUncheckedIndexedAccess": true,      // P0 — surfaces guarded ! assertions
+    "exactOptionalPropertyTypes": true,    // P0 — aligns with Effect Schema optionals
+    "verbatimModuleSyntax": true,          // P1 — type-only import discipline for contract pkg
+    "noImplicitReturns": true,             // P2
+    "noPropertyAccessFromIndexSignature": true // P2
+  }
+}
+```
+Enable P0 flags one at a time and burn down the resulting errors; they will NOT be zero today (that is the point — they reveal currently-hidden unchecked access).
+
+---
+
+## 2. `any` inventory (21 total)
+
+| Cluster | Locations | Count | Verdict |
+|---|---|---|---|
+| **Recipe runtime contract** | `browser-runner/recipeRuntime.ts:19-20` (`compile(env: any, config?: any): any`, `runAsync(...)`) | 3 | **Needs work.** This is the recipe plugin seam. Should become a generic `RecipeModule<Env, Config, Plan>` interface. oRPC won't touch it (worker-side). |
+| **Worker compile plan** | `pipeline.worker.ts:131` (`const plan: any`), `:134` (`node: any`) | 2 | **Needs work.** Flows from the untyped `recipeRuntime` contract above; fix together. |
+| **deck.gl link accessors** | `DeckCanvas.tsx:96-97` (`getSourcePosition: (d: any)`), `:40` (`useRef<Deck<any>>`), `:109` (`deckRef.current as any`) | 4 | **Needs work (explicit).** deck.gl layer-data generics. Type with the viz layer model; oRPC/Effect irrelevant. |
+| **RJSF widget/template props** | `SchemaForm.tsx:49` (`configWidgets as any`), `rjsfTemplates.tsx:224` (`(item as any)?.children`) | 2 | **Needs work or accept.** RJSF v6 registry typing is notoriously loose; these are library-boundary casts. Low value to chase. |
+| **DOMException / AbortError shims** | `deckgl/render.ts:47/50`, `useVizState.ts:24` | 3 | **Accept.** Browser global feature-detection (`globalThis as any`, `(err as any).name`). Idiomatic; could be `unknown` + guard but low risk. |
+| **Typed-array length/index reads** | `deckgl/render.ts:342/357/433/518/600/665/666/671` (`(values as any)[i]`) | 8 (of the 14 `as any`) | **Needs work (explicit).** Casting `ArrayLike<number>` access. Should use the `as unknown as ArrayLike<number>` pattern already present at `presentation.ts:294` / `render.ts:262`, or a `readScalar()` helper. Pure viz, not a wire boundary. |
+
+**None of the `any`s are fetch/response casts** — those use `as <type>` (Section 3), not `as any`. So the typed oRPC client removes **zero** `any`s directly, but removes the `as` casts that the `any`s would otherwise have become.
+
+---
+
+## 3. `as` casts & non-null assertions
+
+**Typed `as` casts: 126** (by file): `App.tsx` 28 · `schemaPresentation.ts` 20 · `SchemaConfigForm.tsx` 12 · `recipes/catalog.ts` 11 · `proofIdentity.ts` 9 · `config.ts` 6 · `clientState.ts` 5 · `persistence.ts`/`pathUtils.ts`/`recipeRuntime.ts` 4 each.
+
+### Dangerous (casting untrusted data)
+| Location | Cast | Risk |
+|---|---|---|
+| `App.tsx:173,214,288` | `res.json() as (Partial<MapConfigSaveDeployStatus> & { error? })` | **HIGH.** Fetch JSON cast to a domain type with no validation. Type-on-faith across the network boundary. ×8 sites total (173/214/268/288/304/349/381/414). |
+| `App.tsx:989,1043` | `res.json() as unknown` | Lower — at least honest `unknown`, but then consumed without a parse step shown. |
+| `App.tsx:1290` | `runPipelineConfig as unknown` | Erases config type before sending to worker. |
+| `worker-trace-sink.ts:94` | `data as unknown as { type: ...; layer: VizLayerEmissionV1 }` | **HIGH.** Double-cast through `unknown` — worker message payload trusted blindly. |
+| `pipeline.worker.ts` / `recipeRuntime.ts` | plan/node `any` casts | Recipe seam (Section 2). |
+
+### Safe / idiomatic (leave)
+- `as const` ×29 — fine.
+- `as unknown` in **persistence parsers** (`persistence.ts:94`, `storage.ts:84`, `importExport.ts:52`, `clientState.ts:189`, `proofIdentity.ts:1162`): `JSON.parse(...) as unknown` **immediately followed by `isRecord`/`isValidStore` guards**. This is the *correct* parse-at-boundary pattern — do not "fix."
+- Typed-array views `as unknown as ArrayLike<number>` (`presentation.ts:294`, `render.ts:262`) — legitimate structural narrowing of numeric buffers.
+
+### Non-null `!` (~17)
+Almost entirely guarded array-index access: `era.ts:41/44`, `presentation.ts:321/354/418-422`, `setupConfig.ts:243/265`, `mapSizes.ts:16`, `worker-viz-dumper.ts:14-15`, `App.tsx:1234/1239` (`stages[0]!` after a `.some()` check). These are **artifacts of `noUncheckedIndexedAccess` being off** — they assert what the flag would force the compiler to verify. Enabling the flag is the real fix; the `!`s then either stay (justified) or get replaced by explicit guards.
+
+---
+
+## 4. Untyped boundaries
+
+| Boundary | Locations | Current state | Post-redesign |
+|---|---|---|---|
+| **`fetch` responses** | `App.tsx:168,213,251,287,303,348,380,409,986,1042` (10 endpoints) | Every one is `res.json() ... as <ad-hoc-or-unknown>`. No shared response schema. Server side is **raw Vite connect middleware** in `vite.config.ts:379+` (`server.middlewares.use("/api/...")`, manual `req`/`res`, hand-rolled JSON) with hand-written `unknown`-based validators (`server/*/requestValidation.ts`). | **This is the headline win.** Replace middleware with effect-orpc handlers + typed oRPC client. All 10 `res.json() as X` casts vanish; request validators (`parseMapConfigSaveRequest` etc.) collapse into the contract schema. |
+| **`JSON.parse`** | 10 sites. **Disciplined:** `schemaPresentation.ts:42/80`, `storage.ts:84`, `importExport.ts:52`, `clientState.ts:189`, `persistence.ts:94`, `proofIdentity.ts:1162` all → `as unknown` + guard. **Weaker:** `clientState.ts:162` → `as Partial<RunInGameClientSnapshot>` (cast, not parsed). `config.ts:25` / `operationState.ts:225` are deep-clone idioms (safe). | clientState.ts:162 is the one to harden. |
+| **`localStorage`** | `useTheme.ts:11/35`, `App.tsx` (~12 sites), `storage.ts:66`, `persistence.ts:28`. | **Well-handled.** Reads route through `parseRunInGameSourceSnapshot` / `parseRunInGameClientSnapshot` / `parseStudioAuthoringState`, each `JSON.parse as unknown` → guard → typed snapshot. `useTheme` reads a raw string (fine). | Not a gap. This is the model the fetch layer should copy. Effect Schema could replace the hand-rolled guards but it is not broken. |
+| **`postMessage` / Worker** | `workerClient.ts:25/27/32/34`, `pipeline.worker.ts:17/193`. | Typed at the type level (`MessageEvent<BrowserRunEvent>`, `MessageEvent<BrowserRunRequest>`) but **trusts `ev.data` without runtime validation** (`workerClient.ts:28` checks only truthiness). `onmessageerror` uses `as (ev: MessageEvent) => void` (`:32`). `worker-trace-sink.ts:94` double-casts the payload. | Worker boundary is out of oRPC scope (no network). Recommend an Effect Schema decode on `ev.data` at `workerClient.ts:28` and in the worker's `onmessage` (`pipeline.worker.ts:193`) for parity with the wire boundary. |
+| **`window`/global** | `globalThis as any` (`render.ts:47`), `window.localStorage ?? null` (`storage.ts:66`, `persistence.ts:28`), `typeof localStorage === "undefined"` (`App.tsx:575`). | Feature-detected, SSR-safe. | Fine. |
+
+---
+
+## 5. Type organization
+
+- **Shared types:** `src/ui/types/index.ts` — a single large hand-authored barrel (Theme, SelectOption, Stage/Step options, "API types" by comment). Referenced by only **7** files. Heavily UI/presentation-shaped, not domain contracts.
+- **Per-feature types:** `features/presets/types.ts`, `features/liveRuntime/model.ts`, `features/viz/model.ts`, plus inline types in `server/*/requestValidation.ts`. Reasonable colocation.
+- **`interface` vs `type`:** 56 `export interface` / 141 `export type` (~197 exported types). Mixed convention, no enforced rule. Fine, but pick one for object shapes (recommend `interface` for extensible object contracts, `type` for unions/aliases) and lint it.
+- **Drift risk:** the **fetch-body ad-hoc types in `App.tsx`** (inline `{ ok?: boolean; ... }` literals at `:304/349/381/414`) are duplicated/parallel to the server's `requestValidation.ts` shapes — two sources of truth that can silently diverge. This is the classic type-value drift the skill warns about.
+
+### Recommendations
+1. **Single contract source.** Define request/response shapes once in the oRPC contract (Effect Schema), `infer` the TS types, share across client + server. Delete the inline `App.tsx` body types and the hand-rolled `requestValidation.ts` parsers. This is the largest organizational win.
+2. **Split `ui/types/index.ts`.** Separate presentation tokens (`Theme`, options) from any data contracts; the file's "backend engineers: these are your contracts" comment is aspirational — the real contracts are in `App.tsx` and `server/`.
+3. **Audit dead exported types** once the contract lands (`ui/types` has low inbound references — 7 files; `find_unused_exports` recommended post-migration).
+4. **`verbatimModuleSyntax`** to keep the contract package's type-only imports from leaking server code into the browser bundle.
+
+---
+
+## 6. Typecheck status
+
+```
+$ bun run --cwd apps/mapgen-studio check
+$ tsc --noEmit
+=== EXIT: 0 ===   error count: 0
+```
+
+**Clean. Zero errors today.** The rigor raise is additive (turning on flags), not remedial. Expect the P0 flags to surface a *bounded* set of new errors concentrated in the array-index `!` sites (Section 3) and the optional-property fetch/validator shapes (Section 1) — these are precisely the spots the redesign already touches.
+
+---
+
+## Priority actions for the redesign
+
+1. **(Floor)** Enable `noUncheckedIndexedAccess` + `exactOptionalPropertyTypes` + `verbatimModuleSyntax`; burn down the bounded error set.
+2. **(Biggest win)** Replace the 10 `res.json() as X` casts and the raw `vite.config.ts` middleware with the effect-orpc contract + typed client. Deletes ~10 casts, the inline `App.tsx` body types, and the hand-rolled `server/*/requestValidation.ts` validators.
+3. **(Parity)** Decode worker `ev.data` (`workerClient.ts:28`, `pipeline.worker.ts:193`) and `worker-trace-sink.ts:94` with Effect Schema; type the `recipeRuntime.ts` contract generically to kill the worker-side `any`s.
+4. **(Cleanup)** Type deck.gl typed-array reads (`render.ts` ×8 `as any`) via a `readScalar` helper; leave persistence-layer `as unknown`+guard patterns alone — they are the reference implementation.
diff --git a/docs/projects/mapgen-studio-redesign/research/01-orpc-effect-bun.md b/docs/projects/mapgen-studio-redesign/research/01-orpc-effect-bun.md
new file mode 100644
index 0000000000..b548b49893
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/research/01-orpc-effect-bun.md
@@ -0,0 +1,509 @@
+# oRPC × Effect × Bun — Canonical Reference for the mapgen-studio API rewrite
+
+**Status:** Research lane deliverable (greenfield — no oRPC/Effect in repo today)
+**Date context:** 2026-06-08
+**Target:** `apps/mapgen-studio` — replace ~660 lines of hand-rolled Vite `server.middlewares.use("/api/...")` handlers (`apps/mapgen-studio/vite.config.ts`, lines ~374–1100) with a native Effect + oRPC router mounted on `Bun.serve`, consumed by the React client with end-to-end type safety.
+
+> All versions, package names, and code below were verified against the live npm registry and the official oRPC docs (`orpc.dev`) on 2026-06-08. This is **not** from training memory. Where the API has changed (it has, a lot — `os`/`oc` builders, `.handle()` return shape, plugin-based CORS), the current surface is used.
+
+---
+
+## 0. One-screen summary (read this first)
+
+**Recommended stack shape**
+
+```
+packages/studio-api/            # NEW workspace package (the API surface, server-agnostic)
+  contract/        oc.router(...) contracts + zod schemas + error maps   (@orpc/contract, zod)
+  effect/          Effect services + Layers (Civ7DirectControl, MapConfigs, RunInGame)
+  router/          implementEffect(contract, runtime) -> router          (effect-orpc, @orpc/server)
+  server/          Bun.serve entry: RPCHandler(router) on /rpc           (@orpc/server/fetch)
+apps/mapgen-studio/
+  src/lib/orpc.ts  createORPCClient(RPCLink) + RouterClient<typeof router> type
+  vite.config.ts   dev-only proxy /rpc -> Bun server (replaces middlewares)
+```
+
+- **Transport:** `RPCHandler` only (internal TS-to-TS client). No OpenAPI handler needed — there are no external consumers. Skip `@orpc/openapi*` entirely unless/until you want a documented REST surface.
+- **Effect bridge:** use the **`effect-orpc`** package (`implementEffect` / `makeEffectORPC`). It is a real, idiomatic bridge — handlers are Effect generators, services come from a `ManagedRuntime`, and the Effect error channel maps to `ORPCError` via `ORPCTaggedError`. This is the single most important finding: you do **not** hand-roll `Effect.runPromise` glue in every handler.
+- **Validation:** **Zod** at the oRPC boundary (oRPC validates via Standard Schema; Zod is the path of least resistance and what `effect-orpc` examples use). Effect Schema is *not* yet a documented first-class oRPC validator — see §5. Keep Effect Schema for internal domain modeling if you want, convert at the boundary.
+- **Bun:** `Bun.serve({ fetch })` calling `handler.handle(request, { prefix: '/rpc', context })` → `{ matched, response }`. Verbatim pattern in §4.
+
+**Single biggest integration risk**
+
+`effect-orpc` is at **v0.2.2** (last published 2026-05-10), single-maintainer (`utopyin`), pre-1.0. It pins peer deps `@orpc/* >=1.13.0` and `effect >=3.18.0` (we'd use `1.14.5` / `3.21.3` — compatible). The risk is **bus-factor / churn on a young bridge**, not correctness. Mitigation: the bridge is thin (`makeEffectORPC` is ~a `ManagedRuntime` + `Effect.runPromise` wrapper around the stock `os` builder). If it stalls, you can inline the same ~30-line adapter and keep contracts/router untouched. Architect so `effect-orpc` is only imported in `router/`, never in `contract/` or `effect/`.
+
+**Exact packages + versions to install** (verified on npm 2026-06-08)
+
+```jsonc
+// Server / contract / client (align all @orpc/* to one version via Bun catalog)
+"@orpc/server":   "1.14.5",
+"@orpc/client":   "1.14.5",
+"@orpc/contract": "1.14.5",
+// Effect bridge
+"effect-orpc":    "0.2.2",
+"effect":         "3.21.3",
+// Validation at the boundary
+"zod":            "^3.25 || ^4"   // oRPC supports both; match repo's existing zod if present
+// Optional (only if you later add React Query helpers)
+"@orpc/tanstack-query": "1.14.5"
+```
+
+`@orpc/server` re-exports the `@orpc/shared` peer that `effect-orpc` wants; no separate install needed. `@effect/platform-bun` is **not** required (oRPC owns the HTTP layer; Effect just runs business logic).
+
+---
+
+## 1. Current oRPC architecture (`os` / `oc`, handlers, routers, contract-first vs implementation-first)
+
+### 1.1 Two builders
+
+- **`os`** (from `@orpc/server`) — the **implementation-first** builder. You attach `.input()`, `.output()`, `.use()`, `.handler()` directly and the types flow from the implementation.
+- **`oc`** (from `@orpc/contract`) — the **contract-first** builder. It defines the *shape* (input/output/errors/route) with no implementation, producing a sharable artifact. You then bind handlers with `implement(contract)`.
+
+### 1.2 Implementation-first (the quickstart shape)
+
+A procedure is a chain ending in `.handler()`. Routers are plain nested objects.
+
+```ts
+import { ORPCError, os } from '@orpc/server'
+import * as z from 'zod'
+
+export const findPlanet = os
+  .input(z.object({ id: z.number().int().min(1) }))
+  .output(z.object({ id: z.number(), name: z.string() }))
+  .handler(async ({ input }) => {
+    return { id: input.id, name: 'name' }
+  })
+
+export const router = {
+  planet: { find: findPlanet },   // nested objects compose the router
+}
+```
+
+- `.input(schema)` / `.output(schema)` take any **Standard Schema** validator (Zod, Valibot, ArkType…). `.output()` is optional but recommended for contract stability.
+- The handler receives `{ input, context, errors, signal, lastEventId }`. It returns the output value directly; it throws to signal errors.
+- The router is just an object tree — keys become procedure paths (`planet.find`).
+
+### 1.3 Contract-first (`oc` + `implement`)
+
+Define the contract once (no server deps), then implement it. This is the recommended shape for this project because contracts live in a package the client can also type-import.
+
+```ts
+// contract.ts  — depends only on @orpc/contract + zod
+import { oc } from '@orpc/contract'
+import * as z from 'zod'
+
+export const contract = oc.router({
+  civ7: {
+    status: oc
+      .input(z.object({}))
+      .output(z.object({ ok: z.boolean(), playable: z.boolean() })),
+    mapSummary: oc
+      .input(z.object({ includeAreaRegionCounts: z.boolean().default(true) }))
+      .output(z.object({ /* ... */ })),
+  },
+})
+```
+
+```ts
+// router.ts — binds handlers to the contract
+import { implement } from '@orpc/server'
+import { contract } from './contract'
+
+const os = implement(contract)   // os is now contract-aware; handlers must match contract I/O
+
+export const router = os.router({
+  civ7: {
+    status:     os.civ7.status.handler(async () => ({ ok: true, playable: true })),
+    mapSummary: os.civ7.mapSummary.handler(async ({ input }) => ({ /* ... */ })),
+  },
+})
+```
+
+**Which to choose here:** contract-first. It gives you (a) a `contract` artifact the React app type-imports without pulling server code, (b) drift control via snapshot tests, (c) clean separation between "what the API is" and "how Civ7 direct-control is called." With `effect-orpc`, contract-first uses `implementEffect(contract, runtime)` instead of `implement(contract)` (see §3).
+
+### 1.4 Router composition
+
+Routers nest by object literal. You can also `os.router(...)`-wrap to apply shared `.use()`/`.errors()`/`.meta()` to a whole subtree. Procedure path = object key path (`civ7.live.snapshot`), which becomes the RPC call path on the client (`client.civ7.live.snapshot(input)`).
+
+---
+
+## 2. Middleware & context (auth/logging/DI) — `.use()`, `.$context`, typed propagation
+
+### 2.1 Initial context vs derived context
+
+- **Initial context** is what you pass into `handler.handle(request, { context })` at the transport edge. Declare its type with `.$context<T>()`.
+- **Derived context** is what middleware adds via `next({ context: {...} })`. Each `.use()` can narrow/extend the context, and the new keys are typed for everything downstream.
+
+```ts
+import type { IncomingHttpHeaders } from 'node:http'
+import { ORPCError, os } from '@orpc/server'
+
+export const authed = os
+  .$context<{ headers: IncomingHttpHeaders }>()   // declares required initial context
+  .use(({ context, next }) => {
+    const user = parseJWT(context.headers.authorization?.split(' ')[1])
+    if (!user) throw new ORPCError('UNAUTHORIZED')
+    return next({ context: { user } })            // adds `user` to context, typed downstream
+  })
+
+export const createPlanet = authed
+  .input(PlanetSchema.omit({ id: true }))
+  .handler(async ({ input, context }) => {
+    context.user        // <- fully typed, guaranteed present
+  })
+```
+
+### 2.2 Middleware signature
+
+A middleware is `({ context, next, path, procedure, errors, signal }) => next(...)`. It must call (and return) `next()`. To inject dependencies, return `next({ context: { db, logger, civ7: directControlClient } })`. This is oRPC's native DI pattern — there is no separate container.
+
+### 2.3 For this project
+
+The mapgen-studio API is local-machine, single-user, no auth. Context here is **dependency injection**, not auth: inject the Civ7 direct-control client, the operation stores (`createRunInGameOperationStore`, `createMapConfigSaveDeployOperationStore`), and a logger. With `effect-orpc`, prefer providing these as **Effect Layers in the `ManagedRuntime`** (§3) rather than oRPC middleware context — that's the more idiomatic split. Use oRPC `.use()` for transport-level concerns (request logging, response headers) and the Effect runtime for business-service injection.
+
+### 2.4 Logging / error interception
+
+Handler-level interceptors run at the `RPCHandler` boundary:
+
+```ts
+import { onError } from '@orpc/server'
+
+const handler = new RPCHandler(router, {
+  interceptors: [ onError((error) => console.error(error)) ],
+})
+```
+
+---
+
+## 3. oRPC × Effect — the `effect-orpc` bridge (the load-bearing piece)
+
+**Verdict: there is a real, idiomatic bridge.** It is the community package **`effect-orpc`** (`utopyin/effect-orpc`, v0.2.2, published 2026-05-10), not part of `@orpc/*` core. Without it you'd do manual `Effect.runPromise(program.pipe(Effect.provide(layer)))` inside each `.handler()` and hand-map failures to `ORPCError`. With it, handlers *are* Effect generators and errors map automatically. Be honest: this is **glue maintained by one person**, but it is thin, typed, and currently healthy.
+
+### 3.1 The runtime + builder
+
+Services are Effect `Layer`s composed into a `ManagedRuntime`. `makeEffectORPC(runtime)` wraps the stock `os` builder so `.effect(...)` handlers can `yield*` those services with compile-time enforcement (using a service not in the runtime is a type error).
+
+```ts
+import { Effect, Layer, ManagedRuntime } from 'effect'
+import { makeEffectORPC, ORPCTaggedError } from 'effect-orpc'
+import * as z from 'zod'
+
+// A service (DI unit) — wraps @civ7/direct-control calls
+class Civ7Control extends Effect.Service<Civ7Control>()('Civ7Control', {
+  accessors: true,
+  effect: Effect.gen(function* () {
+    return {
+      playableStatus: () => Effect.tryPromise(() => getCiv7PlayableStatus({ timeoutMs: 5000 })),
+    }
+  }),
+}) {}
+
+const AppLayer = Layer.mergeAll(Civ7Control.Default /*, MapConfigs.Default, ... */)
+const runtime = ManagedRuntime.make(AppLayer)
+
+const effectOs = makeEffectORPC(runtime)
+
+export const status = effectOs
+  .input(z.object({}))
+  .effect(function* () {
+    const status = yield* Civ7Control.playableStatus()
+    return { ok: status.playable, playable: status.playable }
+  })
+```
+
+### 3.2 Contract-first with Effect: `implementEffect`
+
+For the recommended contract-first layout, use `implementEffect(contract, runtime)`. Leaf nodes expose `.effect(...)` while preserving the contract's I/O types:
+
+```ts
+import { implementEffect } from 'effect-orpc'
+import { contract } from './contract'
+
+const oe = implementEffect(contract, runtime)
+
+export const router = oe.router({
+  civ7: {
+    status: oe.civ7.status.effect(function* () {
+      const s = yield* Civ7Control.playableStatus()
+      return { ok: s.playable, playable: s.playable }
+    }),
+  },
+})
+```
+
+### 3.3 Error channel → `ORPCError`
+
+`ORPCTaggedError(tag, options?)` creates Effect-native error classes that double as oRPC typed errors. Options: `{ schema?, code?, status?, message? }` (`code` defaults to CONSTANT_CASE of the tag). When such an error is `yield*`-ed or an Effect fails with one, the runtime converts it to an `ORPCError` carrying that code/status/message/data. Register them with `.errors(...)`:
+
+```ts
+class Civ7Unavailable extends ORPCTaggedError('Civ7Unavailable', {
+  code: 'SERVICE_UNAVAILABLE', status: 503,
+  schema: z.object({ reason: z.string() }),
+}) {}
+
+export const status = effectOs
+  .errors({ SERVICE_UNAVAILABLE: Civ7Unavailable })
+  .input(z.object({}))
+  .effect(function* () {
+    const s = yield* Civ7Control.playableStatus().pipe(
+      Effect.catchAll(() => new Civ7Unavailable({ reason: 'tuner offline' })),
+    )
+    return { ok: s.playable, playable: s.playable }
+  })
+```
+
+There is also an Effect-aware contract builder `eoc` that accepts `ORPCTaggedError` classes directly in `.errors(...)` without re-declaring schemas.
+
+### 3.4 Other niceties
+
+- **Auto-tracing:** every `.effect(...)` procedure is wrapped in `Effect.withSpan` named by procedure path; override with `.traced('name')`. Add an OTel layer to the runtime to export.
+- **Request-scoped fiber context:** `effect-orpc/node` exports `withFiberContext` to preserve `FiberRef` state (request IDs, log annotations) across the async boundary — uses `node:async_hooks` (works on Bun). Only needed if you annotate logs/traces per-request; for mapgen-studio it's optional.
+- `EffectBuilder` exposes both `.effect(handler)` (Effect generator) and `.handler(handler)` (plain async) so you can migrate procedure-by-procedure.
+
+### 3.5 Manual fallback (if you reject the dependency)
+
+If you'd rather not depend on a v0.x package, the equivalent inline pattern is small:
+
+```ts
+const runtime = ManagedRuntime.make(AppLayer)
+export const status = os.input(z.object({})).handler(async () => {
+  return runtime.runPromise(
+    Effect.gen(function* () {
+      const s = yield* Civ7Control.playableStatus()
+      return { ok: s.playable, playable: s.playable }
+    }).pipe(
+      Effect.catchTag('Civ7Unavailable', (e) =>
+        Effect.fail(new ORPCError('SERVICE_UNAVAILABLE', { data: { reason: e.reason } }))),
+    ),
+  )
+})
+```
+
+Recommendation: **start with `effect-orpc`**, keep it isolated to `router/`, and you can swap to the manual form later without touching contracts or services.
+
+---
+
+## 4. Mounting on Bun (`Bun.serve` + RPCHandler)
+
+oRPC's `fetch` adapter targets the Web `Request`/`Response` API that `Bun.serve` speaks. This is the **verbatim current pattern** from `orpc.dev/docs/adapters/http`:
+
+```ts
+import { RPCHandler } from '@orpc/server/fetch'
+import { CORSPlugin } from '@orpc/server/plugins'
+import { onError } from '@orpc/server'
+import { router } from './router'
+
+const handler = new RPCHandler(router, {
+  plugins: [ new CORSPlugin() ],
+  interceptors: [ onError((error) => console.error(error)) ],
+})
+
+Bun.serve({
+  port: Number(process.env.PORT ?? 8787),
+  async fetch(request: Request) {
+    const { matched, response } = await handler.handle(request, {
+      prefix: '/rpc',
+      context: {},               // initial context (DI lives in the Effect runtime here)
+    })
+    if (matched) return response
+    return new Response('Not found', { status: 404 })
+  },
+})
+```
+
+Key facts (verified):
+
+- **`handle()` returns `{ matched, response }`** (fetch adapter). `matched: false` means no procedure matched the path — fall through to your own 404 / static serving.
+- **`prefix`** must match the URL path the client hits. Client `RPCLink({ url: '.../rpc' })` ⇄ handler `prefix: '/rpc'`. Mismatch = silent 404s (documented gotcha).
+- **CORS** is a **plugin**, not config: `new CORSPlugin({ origin, allowMethods, allowHeaders, credentials })`. Default `new CORSPlugin()` is permissive enough for local dev; for same-origin (proxied through Vite) you can omit it.
+- **Body parsing:** oRPC reads the raw `Request` body itself. Do **not** put a framework in front that consumes the stream first (this is why we use bare `Bun.serve`, not Elysia/Hono wrapping the same route — if you ever do, disable that framework's body parsing on the forwarded route).
+- **Streaming:** supported natively via Event Iterators (AsyncIterator at the root of a handler return). Relevant if you want to stream run-in-game progress instead of polling an operation store — the handler keeps the connection open and emits events; `RPCLink` consumes them as an async iterable. Keep-alive/initial-comment options exist on the handler (`eventIteratorKeepAliveEnabled`, etc.).
+- **GET hardening:** `StrictGetMethodPlugin` is **on by default** (prevents CSRF-ish GET exposure). Leave it on.
+
+### Serving alongside Vite (dev) and in production
+
+**Dev:** run the Bun API server as a separate process on its own port, and proxy from Vite so the browser sees one origin (no CORS):
+
+```ts
+// vite.config.ts (dev) — replaces the entire server.middlewares block
+export default defineConfig({
+  server: {
+    proxy: { '/rpc': { target: 'http://localhost:8787', changeOrigin: true } },
+  },
+})
+```
+
+The `dev` script becomes "start Bun API + start Vite" (e.g. via a concurrently-style runner or a Turborepo task that runs both). This removes the ~660 lines from `vite.config.ts` and the dev/prod parity gap (see below).
+
+**Production:** today `apps/mapgen-studio/railway.json` starts **Caddy serving static `dist`** only — the `/api/*` middlewares exist **only in the Vite dev server and do not exist in the deployed app**. The rewrite is the chance to fix that. Two options:
+
+1. **Caddy reverse-proxy + Bun service** — keep Caddy for static `dist`, add a `reverse_proxy /rpc/* localhost:8787` and run the Bun server as a second process/container. Lowest change to the static-serving story.
+2. **Bun serves everything** — `Bun.serve` handles `/rpc` and falls back to serving `dist` static files (Bun has a `static`/file-serving story) and `index.html` for SPA routes. Collapses to one process; drop Caddy.
+
+Given this is a local-dev tool that talks to a desktop Civ7 process, the production "deploy" is mostly the hosted-docs/demo surface; the Civ7 direct-control endpoints only work where the game runs. Decide explicitly which procedures are meaningful in the Railway deploy vs local-only.
+
+---
+
+## 5. Validation / schema choice (Effect Schema vs Zod)
+
+- oRPC validates `.input`/`.output`/error-`data` via **Standard Schema**. Officially supported & documented: **Zod, Valibot, ArkType**. `@orpc/zod` adds Zod-specific helpers (JSON-schema conversion, file/blob coercion) if needed.
+- **Effect Schema is not (yet) a documented first-class oRPC validator.** Effect's `@effect/schema` does not currently expose a Standard Schema adapter that oRPC documents. The `effect-orpc` examples all use **Zod** at the boundary. Do not assume Effect Schema "just works" as an oRPC validator without verifying — treat that as a spike if you want it.
+- **Recommendation:** **Zod at the oRPC boundary.** If your Effect domain services model data with Effect Schema internally, decode/encode at the service edge and expose plain types; the contract uses Zod. This mirrors the skill's "domain source-of-truth → Standard-Schema validator at the boundary" golden path (the skill uses TypeBox→Zod via `@sinclair/typemap`; here the analogue is EffectSchema→plain→Zod, or just author the contract schemas in Zod directly, which is simplest for ~17 endpoints).
+- Many of the current endpoints already do ad-hoc validation in `./src/server/*/requestValidation.ts` (e.g. `parseRunInGameSetupRequest`, `parseMapConfigSaveRequest`). Port those into Zod contract `.input` schemas so validation is declarative and the error responses become typed `ORPCError`s.
+
+---
+
+## 6. Recommended project structure
+
+New workspace package `packages/studio-api` (Bun workspace + Turborepo, matching repo conventions). Dependency rule: **`contract/` imports only `@orpc/contract` + `zod`; `effect/` imports only `effect` + `@civ7/direct-control`; `router/` is the only place that imports `effect-orpc` and ties them together.**
+
+```
+packages/studio-api/
+  package.json
+  src/
+    contract/
+      index.ts            # oc.router({...}) — the full API surface
+      civ7.ts             # civ7.status, civ7.mapSummary, civ7.gameinfo, civ7.live.*
+      civ7-autoplay.ts    # civ7.autoplay.{status,start,stop}
+      run-in-game.ts      # civ7.runInGame.{status,start}
+      map-configs.ts      # mapConfigs.{status,list,save}
+      setup.ts            # civ7.setupConfig, civ7.savedConfigs, civ7.setupCatalog
+      errors.ts           # ORPCTaggedError classes (Civ7Unavailable, RunInGameError, ...)
+    effect/
+      runtime.ts          # ManagedRuntime.make(AppLayer)
+      services/
+        Civ7Control.ts    # Effect.Service wrapping @civ7/direct-control reads
+        MapConfigs.ts      # save/deploy operation store + deploy command
+        RunInGame.ts       # operation state machine, log failure waits, proofs
+    router/
+      index.ts            # implementEffect(contract, runtime) -> router; export type AppRouter
+    server/
+      index.ts            # Bun.serve({ fetch }) + RPCHandler + CORS + onError
+  tsconfig.json
+
+apps/mapgen-studio/
+  src/lib/orpc.ts         # RPCLink + createORPCClient -> typed `orpc` client
+                          # import type { AppRouter } from '@civ7/studio-api/router'
+  vite.config.ts          # dev proxy /rpc -> :8787 (middlewares deleted)
+```
+
+- Export `export type AppRouter = typeof router` (or `RouterClient<typeof router>`) for the client to type-import — **type-only import**, so the client never bundles server/Effect code.
+- The existing `apps/mapgen-studio/src/server/*` helpers (operationState, deploy, requestValidation, proofIdentity, macosProcessRestart, logFailure) move into `packages/studio-api/src/effect/services/*` and get wrapped as Effect services. They're already well-factored, so this is mostly relocation + a thin Effect veneer.
+
+---
+
+## 7. Migration notes — hand-rolled `req/res` → oRPC procedure
+
+The current endpoints follow a uniform shape. Map them mechanically:
+
+| Hand-rolled pattern | oRPC equivalent |
+|---|---|
+| `server.middlewares.use("/api/civ7/status", (req,res,next)=>{...})` | procedure `civ7.status` in the router (path from key) |
+| `if (req.method !== "GET") return next()` | implicit — RPC is POST; method gating goes away (or `.route({method})` only if using OpenAPI) |
+| parse `new URL(req.url).searchParams` | declarative `.input(z.object({...}))`; client passes a typed object |
+| manual JSON body read | oRPC reads + validates body against `.input` schema |
+| `writeJson(res, 200, {...})` | `return {...}` (validated against `.output`) |
+| `writeJson(res, 500, { ok:false, error })` | `throw new ORPCError('...')` / `throw errors.X()` / `yield* new TaggedError()` |
+| `try/catch` per handler | Effect error channel + `onError` interceptor + typed `.errors()` |
+| shared helpers (`getCiv7MapGrid`, operation stores) | injected via Effect runtime services |
+
+**Worked example.** Current (`vite.config.ts`):
+
+```ts
+server.middlewares.use("/api/civ7/gameinfo", async (req, res, next) => {
+  if (req.method !== "GET") return next();
+  try {
+    const url = new URL(req.url ?? "", "http://localhost");
+    const table = url.searchParams.get("table");
+    if (!table) throw new Error("Missing table query parameter");
+    const limit = Number(url.searchParams.get("limit") ?? "100");
+    const rows = await getCiv7GameInfoRows({ table, limit }, { timeoutMs: DEFAULT_CIV7_TUNER_TIMEOUT_MS });
+    writeJson(res, 200, { ok: true, rows });
+  } catch (err) {
+    writeJson(res, 400, { ok: false, error: err instanceof Error ? err.message : "..." });
+  }
+});
+```
+
+Becomes — contract:
+
+```ts
+// contract/civ7.ts
+gameinfo: oc
+  .input(z.object({ table: z.string().min(1), limit: z.number().int().min(1).max(1000).default(100) }))
+  .output(z.object({ rows: z.array(z.record(z.unknown())) }))
+```
+
+— and Effect handler:
+
+```ts
+// router/index.ts
+gameinfo: oe.civ7.gameinfo.effect(function* ({ input }) {
+  const rows = yield* Civ7Control.gameInfoRows(input.table, input.limit) // Effect.tryPromise inside
+  return { rows }
+}),
+```
+
+Client call (end-to-end typed, validation + 400 handled by oRPC):
+
+```ts
+const { rows } = await orpc.civ7.gameinfo({ table: 'Terrains', limit: 50 })
+```
+
+Note the response envelope flattens: drop `{ ok: true, ... }` wrappers — success is implicit (resolved promise / `data`), failure is an `ORPCError` the client distinguishes via `safe()` + `isDefinedError` (§ below). Migrate the React fetch sites to the typed client at the same time.
+
+### Client setup + error handling (the consuming side)
+
+```ts
+// apps/mapgen-studio/src/lib/orpc.ts
+import { createORPCClient, onError } from '@orpc/client'
+import { RPCLink } from '@orpc/client/fetch'
+import type { RouterClient } from '@orpc/server'
+import type { AppRouter } from '@civ7/studio-api/router'   // type-only
+
+const link = new RPCLink({ url: '/rpc' })   // same-origin via Vite proxy / Caddy
+export const orpc: RouterClient<AppRouter> = createORPCClient(link)
+```
+
+```ts
+import { isDefinedError, safe } from '@orpc/client'
+
+const { error, data, isDefined } = await safe(orpc.civ7.status({}))
+if (isDefinedError(error)) {
+  // typed error from .errors(): error.code, error.data is schema-typed
+} else if (error) {
+  // unexpected
+} else {
+  data.playable
+}
+```
+
+`RPCLink` supports `headers`, custom `fetch`, and resilience plugins (`ClientRetryPlugin`, `RetryAfterPlugin` from `@orpc/client/plugins`) and per-call `AbortSignal` for timeouts — useful for the long-running run-in-game calls.
+
+---
+
+## 8. Pitfalls / contract checklist (project-specific)
+
+1. **Prefix alignment:** `RPCLink.url` path ⇄ handler `prefix`. Off-by-one = silent 404.
+2. **`effect-orpc` is v0.x:** isolate it to `router/`; pin the exact version; add a smoke test that exercises one `.effect` procedure end-to-end so an upgrade break is caught in CI.
+3. **Don't double-consume the body:** use bare `Bun.serve`, no body-parsing framework in front of `/rpc`.
+4. **Effect Schema is not a verified oRPC validator** — use Zod at the boundary; spike before assuming otherwise.
+5. **Production parity:** the current `/api/*` exists only in Vite dev; decide the Railway story (Caddy reverse_proxy vs Bun-serves-all) deliberately — don't recreate the dev-only gap.
+6. **Local-only procedures:** Civ7 direct-control only works where the game runs. Tag/segregate procedures that are meaningless in a hosted deploy.
+7. **Error payload hygiene:** `ORPCError.data` reaches the client — don't leak filesystem paths / internal detail from the Civ7 tuner.
+8. **Drift control:** snapshot the contract (oRPC's `minifyContractRouter` helper) in a test so API changes are reviewed explicitly.
+
+---
+
+## Sources (verified 2026-06-08)
+
+- oRPC HTTP adapter (Bun.serve verbatim, `{matched,response}`, prefix, CORS): https://orpc.dev/docs/adapters/http
+- oRPC Getting Started (`os`, `.use`, `.$context`, `ORPCError`, router, client): https://orpc.dev/docs/getting-started
+- RPCHandler API (plugins, filter, default StrictGetMethodPlugin, supported types, streaming): https://orpc.dev/docs/rpc-handler
+- Error handling (`ORPCError`, `.errors()`, typed throws): https://orpc.dev/docs/error-handling
+- Client error handling (`safe`, `isDefinedError`, `createSafeClient`): https://orpc.dev/docs/client/error-handling
+- CORS plugin: https://orpc.dev/docs/plugins/cors
+- **effect-orpc bridge** (`makeEffectORPC`, `implementEffect`, `ORPCTaggedError`, `eoc`, `withFiberContext`, tracing): https://github.com/utopyin/effect-orpc
+- npm versions: `@orpc/server@1.14.5`, `@orpc/client@1.14.5`, `@orpc/contract@1.14.5`, `@orpc/zod@1.14.5`, `@orpc/tanstack-query@1.14.5`, `effect-orpc@0.2.2` (peers `@orpc/* >=1.13.0`, `effect >=3.18.0`; published 2026-05-10), `effect@3.21.3`
+- Repo state: `apps/mapgen-studio/vite.config.ts` (lines ~374–1100, 17 `middlewares.use` routes), `apps/mapgen-studio/package.json` (Bun 1.3.7, React 19, Vite 7), `apps/mapgen-studio/railway.json` + `Caddyfile` (static-only prod deploy)
+- Internal skill: `dev:orpc` (`/Users/mateicanavra/.claude/plugins/cache/local/dev/0.1.0/skills/orpc/`) — contract-first, transports, schemas, monorepo, networking references
diff --git a/docs/projects/mapgen-studio-redesign/research/02-orpc-tanstack-zustand.md b/docs/projects/mapgen-studio-redesign/research/02-orpc-tanstack-zustand.md
new file mode 100644
index 0000000000..338c0463c6
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/research/02-orpc-tanstack-zustand.md
@@ -0,0 +1,545 @@
+# Client Data Architecture: oRPC + TanStack Query + Zustand
+
+Canonical reference for the `apps/mapgen-studio` client data layer in the React 19 redesign.
+Research lane: client-data-architecture. Date: 2026-06-08.
+
+---
+
+## 0. TL;DR (1-screen summary)
+
+**The stack (verified current versions, npm `latest` as of 2026-06-08):**
+
+| Package | Version | Role |
+| --- | --- | --- |
+| `@orpc/client` | `1.14.5` | `RPCLink` (fetch transport) + `createORPCClient` |
+| `@orpc/tanstack-query` | `1.14.5` | `createTanstackQueryUtils` — the native TanStack Query integration |
+| `@tanstack/react-query` | `5.101.0` | **peer dependency** — provides `QueryClient` + `QueryClientProvider` + hooks |
+| `zustand` | `5.0.14` | client/UI state only |
+| `@orpc/contract` / `@orpc/server` | `1.14.5` | server side (typed router → `RouterClient<typeof router>` type export) |
+
+> Skill `dev:orpc` pins `1.13.4` (dated 2026-02-05). Live npm is `1.14.5`. The TanStack Query
+> API surface (`createTanstackQueryUtils`, `*.queryOptions`, `*.key`) is stable across that range.
+
+**VERDICT on "do we use oRPC's native query utils directly?": YES — directly, no hand-written query client.**
+`createTanstackQueryUtils(client)` returns a tree of utilities (`orpc.x.queryOptions(...)`,
+`orpc.x.mutationOptions(...)`, `orpc.x.key(...)`) that you feed straight into the *standard*
+`useQuery` / `useMutation` / `useQueryClient` hooks from `@tanstack/react-query`. There is **no**
+custom query client, no hand-rolled query-key factory, no wrapper hooks library to build. oRPC
+generates type-safe `queryOptions` objects; TanStack Query consumes them. You still install and
+provide `@tanstack/react-query`'s `QueryClient` yourself (it is a peer dep, not bundled by oRPC).
+
+**The one crisp rule (server state vs client state):**
+> **If the value comes from (or is owned by) the server, it lives in TanStack Query (via oRPC).
+> If it only exists in the browser and the server neither produces nor validates it, it lives in
+> Zustand.** Never copy server data into Zustand; subscribe to the query cache instead.
+
+---
+
+## 1. The exact oRPC → TanStack Query wiring
+
+### 1.1 The client module (`lib/orpc.ts`)
+
+One module owns URL resolution, the link, the typed client, and the query utils. This kills the
+"every component builds its own client" problem.
+
+```ts
+// lib/orpc.ts
+import { createORPCClient, onError } from '@orpc/client'
+import { RPCLink } from '@orpc/client/fetch'
+import { createTanstackQueryUtils } from '@orpc/tanstack-query'
+import type { RouterClient } from '@orpc/server'
+import type { router } from '../../server/router' // type-only import of the server router
+
+// 1. Link: HTTP/fetch transport to the RPC handler.
+//    Vite SPA, same-origin → relative '/rpc' is fine and avoids env wiring.
+const link = new RPCLink({
+  url: () => `${window.location.origin}/rpc`, // lazy: only evaluated in the browser
+  fetch: (request, init) =>
+    globalThis.fetch(request, { ...init, credentials: 'include' }), // send auth cookies
+  interceptors: [
+    onError((error) => {
+      // central client-side logging hook (optional)
+      console.error('[orpc]', error)
+    }),
+  ],
+})
+
+// 2. Typed client. RouterClient<typeof router> gives full end-to-end types
+//    WITHOUT importing any server runtime code (type-only import above).
+export const client: RouterClient<typeof router> = createORPCClient(link)
+
+// 3. TanStack Query utilities. THIS is the whole "query client" — generated, not written.
+export const orpc = createTanstackQueryUtils(client)
+```
+
+`createTanstackQueryUtils(client)` mirrors the procedure tree. For a router with
+`mapConfigs.save`, `civ7.liveStatus`, `civ7.runInGame`, you get `orpc.mapConfigs.save.*`,
+`orpc.civ7.liveStatus.*`, etc. Each leaf exposes:
+
+| Utility | Purpose |
+| --- | --- |
+| `.queryOptions({ input, ... })` | full options object for `useQuery` / `useSuspenseQuery` / `prefetchQuery` |
+| `.infiniteOptions({ input: (pageParam) => ..., ... })` | for `useInfiniteQuery` |
+| `.experimental_streamedOptions(...)` / `.experimental_liveOptions(...)` | Event Iterator streaming/live (array vs latest) |
+| `.mutationOptions({ ... })` | options object for `useMutation` |
+| `.call(input)` | imperative call (alias of the underlying client procedure) |
+| `.key({ input?, type? })` | **partial** query key — for invalidation/matching |
+| `.queryKey({ input })` / `.infiniteKey(...)` / `.mutationKey(...)` | **full** keys — for `setQueryData`, exact matching |
+
+### 1.2 Call sites — standard TanStack hooks, oRPC options
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { orpc } from '../lib/orpc'
+
+// QUERY
+function SavedConfigs() {
+  const { data, isPending, isError } = useQuery(
+    orpc.civ7.savedConfigs.queryOptions(), // no input → call with nothing
+  )
+  // ...
+}
+
+// QUERY WITH INPUT
+function SetupConfig({ enabled }: { enabled: boolean }) {
+  const query = useQuery(
+    orpc.civ7.setupConfig.queryOptions({
+      input: {},
+      enabled, // any standard TanStack option is passed straight through
+    }),
+  )
+}
+
+// MUTATION + INVALIDATION
+function SaveButton() {
+  const qc = useQueryClient()
+  const save = useMutation(
+    orpc.mapConfigs.save.mutationOptions({
+      onSuccess: () => {
+        // invalidate everything under the mapConfigs namespace
+        qc.invalidateQueries({ queryKey: orpc.mapConfigs.key() })
+      },
+    }),
+  )
+  return <button onClick={() => save.mutate({ config /* typed input */ })}>Save</button>
+}
+```
+
+### 1.3 Query-key structure & invalidation
+
+oRPC keys are **hierarchical arrays** shaped roughly `[[...procedurePath], { type, input }]`.
+You almost never write them literally — you call the generated helpers and let partial matching
+do the work:
+
+```ts
+const qc = useQueryClient()
+
+// Invalidate ALL civ7 queries (any procedure under civ7.*)
+qc.invalidateQueries({ queryKey: orpc.civ7.key() })
+
+// Invalidate only non-infinite queries for one procedure
+qc.invalidateQueries({ queryKey: orpc.civ7.liveStatus.key({ type: 'query' }) })
+
+// Invalidate one exact input
+qc.invalidateQueries({ queryKey: orpc.civ7.runInGameStatus.key({ input: { requestId } }) })
+
+// Optimistic / manual cache write (FULL key)
+qc.setQueryData(
+  orpc.civ7.runInGameStatus.queryKey({ input: { requestId } }),
+  (old) => ({ ...old, status: 'running' }),
+)
+```
+
+Rule of thumb: `.key(...)` for **invalidate/match** (partial), `.queryKey(...)` /
+`.mutationKey(...)` for **exact read/write** (`setQueryData`, `getQueryData`).
+
+### 1.4 Optimistic updates
+
+Standard TanStack pattern; keys come from oRPC:
+
+```ts
+const update = useMutation(orpc.studio.rename.mutationOptions({
+  onMutate: async (vars) => {
+    const key = orpc.studio.get.queryKey({ input: { id: vars.id } })
+    await qc.cancelQueries({ queryKey: key })
+    const prev = qc.getQueryData(key)
+    qc.setQueryData(key, (old) => ({ ...old, name: vars.name }))
+    return { prev, key }
+  },
+  onError: (_e, _v, ctx) => ctx && qc.setQueryData(ctx.key, ctx.prev),
+  onSettled: (_d, _e, _v, ctx) => ctx && qc.invalidateQueries({ queryKey: ctx.key }),
+}))
+```
+
+### 1.5 Type-safe error handling
+
+oRPC `ORPCError`s are propagated to TanStack `error`. Use `isDefinedError` to narrow to
+contract-declared errors:
+
+```ts
+import { isDefinedError } from '@orpc/client'
+
+const m = useMutation(orpc.mapConfigs.save.mutationOptions({
+  onError: (error) => { if (isDefinedError(error)) { /* typed .code / .data */ } },
+}))
+```
+
+---
+
+## 2. VERDICT: native oRPC query utils directly (not a separate React Query layer)
+
+**Use oRPC's generated utilities directly. Do not build a parallel React Query abstraction.**
+
+What "native integration" concretely means here:
+
+1. **No custom query client / no query-key factory.** `createTanstackQueryUtils(client)` IS the
+   integration. It generates `queryOptions`/`mutationOptions`/`key` for every procedure, fully
+   typed from the contract. Writing your own `useSavedConfigs()` wrappers around `fetch` (the
+   current pattern) is exactly what we delete.
+
+2. **`@tanstack/react-query` remains a real peer dependency you install and provide.** oRPC does
+   not bundle or re-export TanStack Query. You install `@tanstack/react-query@5`, create the
+   `QueryClient`, and wrap the app in `QueryClientProvider`. oRPC only produces the *options
+   objects* you pass to the hooks.
+
+3. **Minimal idiomatic wiring** (the entire server-state layer):
+   - `lib/orpc.ts` — `RPCLink` → `createORPCClient` → `createTanstackQueryUtils` (Section 1.1).
+   - `lib/query.ts` — one `QueryClient` factory (Section 6).
+   - Provider in `main.tsx` — `<QueryClientProvider client={queryClient}>`.
+   - Components call `useQuery(orpc.x.queryOptions(...))` / `useMutation(orpc.x.mutationOptions(...))`.
+   That's it. No `services/`, no `api/` hooks folder, no key constants file.
+
+**QueryClient provisioning (SPA):**
+
+```ts
+// lib/query.ts
+import { QueryClient } from '@tanstack/react-query'
+export function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 30_000, retry: 2, refetchOnWindowFocus: false },
+    },
+  })
+}
+```
+
+```tsx
+// main.tsx
+import { QueryClientProvider } from '@tanstack/react-query'
+import { useState } from 'react'
+import { createQueryClient } from './lib/query'
+
+function Root() {
+  const [queryClient] = useState(createQueryClient) // stable across renders
+  return (
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  )
+}
+```
+
+> Note: a stale `QueryClient` from a module-level singleton is fine for a pure SPA, but the
+> `useState(createQueryClient)` form is the idiomatic, future-proof default (matches oRPC's own
+> docs and avoids cross-render identity churn during HMR).
+
+**One optional extra:** if you want `GET` requests (browser/CDN caching, server log readability)
+for read procedures, oRPC sets a TanStack *operation context* you can read in the link's `method`:
+
+```ts
+import { TANSTACK_QUERY_OPERATION_CONTEXT_SYMBOL, type TanstackQueryOperationContext } from '@orpc/tanstack-query'
+
+interface ClientContext extends TanstackQueryOperationContext {}
+const GET_OPS = new Set(['query', 'streamed', 'live', 'infinite'])
+const link = new RPCLink<ClientContext>({
+  url: () => `${window.location.origin}/rpc`,
+  method: ({ context }) =>
+    GET_OPS.has(context[TANSTACK_QUERY_OPERATION_CONTEXT_SYMBOL]?.type ?? '') ? 'GET' : 'POST',
+})
+```
+The RPCHandler's default `StrictGetMethodPlugin` blocks GET unless the procedure allows it — so
+this is opt-in and safe to defer. Default POST is fine for v1.
+
+---
+
+## 3. Live / polling data (Civ7 status + snapshots)
+
+Today (`App.tsx` ~lines 966–1080) this is a hand-built `setTimeout` recursion with
+`AbortController`s, failure counters, document-hidden backoff, and manual `setState`. TanStack
+Query replaces almost all of it.
+
+### 3.1 Status long-poll surface
+
+```ts
+function useLiveStatus() {
+  return useQuery(orpc.civ7.liveStatus.queryOptions({
+    input: {},
+    // Poll: number, or a function for adaptive/backoff intervals.
+    refetchInterval: (query) => {
+      if (document.hidden) return 15_000          // matches current document-hidden backoff
+      return query.state.error ? 10_000 : 2_000   // back off on failure
+    },
+    refetchIntervalInBackground: false,           // pause when tab hidden (or keep + slow it)
+    retry: 1,
+    staleTime: 0,                                  // live data is always "stale"
+    gcTime: 5_000,
+  }))
+}
+```
+
+Key mappings from the current manual loop:
+- `setTimeout(poll, delay)` → `refetchInterval` (supports the adaptive function form).
+- `document.hidden` backoff → branch inside `refetchInterval` + `refetchIntervalInBackground: false`.
+- failure-count backoff → `query.state.error` / `query.state.fetchFailureCount` inside the fn.
+- manual `AbortController` per poll → TanStack passes `signal` into the query fn automatically;
+  oRPC's client forwards it to `fetch`. **Delete the manual abort plumbing.**
+
+### 3.2 Snapshot read, gated on status (enabled / skipToken)
+
+The snapshot request is derived from the latest status. Use `enabled` (or `skipToken`) so the
+snapshot query only runs when there's a valid request, and key it by the derived request so the
+cache naturally dedupes/cancels when the request changes:
+
+```ts
+function useLiveSnapshot(request: SnapshotRequest | undefined) {
+  return useQuery(orpc.civ7.liveSnapshot.queryOptions({
+    // skipToken: type-safe "disabled" — omits input and disables the query.
+    input: request ?? skipToken,        // import { skipToken } from '@tanstack/react-query'
+    refetchInterval: request ? 2_000 : false,
+    staleTime: 0,
+  }))
+}
+```
+
+`skipToken` is preferred over `enabled: false` because oRPC + TanStack keep the types honest (you
+can't accidentally call with `undefined` input). When `request` changes, the query key changes,
+TanStack cancels the in-flight request (aborting the fetch) and starts the new one — replacing the
+manual `activeLiveSnapshotRequestKeyRef` / `shouldCommitLiveRuntimeSnapshot` dedupe logic.
+
+### 3.3 Suspense vs not — for a live surface, do NOT use Suspense
+
+- **Non-suspense `useQuery`** for live/polling: you want `isPending` / `isError` / stale-while-
+  refetch states visible in the footer status dot, not a thrown promise that unmounts the surface
+  on every transient error. Keep the live status/snapshot surfaces on `useQuery`.
+- **`useSuspenseQuery`** is appropriate for *initial, must-have* reads that gate first paint
+  (e.g. setup catalog, saved-config list on a route) where an error boundary + spinner is the
+  right UX. Even then it's optional in an SPA.
+
+### 3.4 Streaming alternative (if the server moves to Event Iterator)
+
+If/when `liveStatus` becomes a server-push Event Iterator instead of poll-on-demand, swap
+`queryOptions` for `experimental_liveOptions` (data = latest event) or
+`experimental_streamedOptions` (data = appended array) with `retry: true`. No component change
+beyond the option call. Polling is the correct v1 given the current REST endpoints.
+
+---
+
+## 4. Zustand v5 patterns (client/UI state only)
+
+Confirmed against current Zustand v5 reference (`zustand.docs.pmnd.rs`, v5.0.14):
+`useShallow` lives in `zustand/react/shallow`; `persist`/`devtools`/`combine` in
+`zustand/middleware`; `createWithEqualityFn` is a separate import (`zustand/traditional`) — for
+v5 prefer plain `create` + `useShallow` over `createWithEqualityFn`.
+
+### 4.1 Store slicing (avoid the App.tsx god-store)
+
+`App.tsx` currently holds **83** `useState`/`useRef`/`useEffect` calls. Do NOT replace that with
+one giant Zustand store — that's the same anti-pattern relocated. Split by domain, compose with
+the **slices pattern**:
+
+```ts
+// stores/types.ts
+import type { StateCreator } from 'zustand'
+
+export interface ViewSlice {
+  panel: 'recipe' | 'explore'
+  setPanel: (p: ViewSlice['panel']) => void
+}
+export interface SelectionSlice {
+  selectedPresetId: string | null
+  selectPreset: (id: string | null) => void
+}
+export type StudioStore = ViewSlice & SelectionSlice
+
+// stores/viewSlice.ts
+export const createViewSlice: StateCreator<StudioStore, [], [], ViewSlice> = (set) => ({
+  panel: 'recipe',
+  setPanel: (panel) => set({ panel }),
+})
+
+// stores/studioStore.ts
+import { create } from 'zustand'
+import { createViewSlice } from './viewSlice'
+import { createSelectionSlice } from './selectionSlice'
+
+export const useStudioStore = create<StudioStore>()((...a) => ({
+  ...createViewSlice(...a),
+  ...createSelectionSlice(...a),
+}))
+```
+
+Keep separate stores per bounded concern where there's no cross-talk (e.g. `useAuthStore`,
+`useStudioStore`, `useThemeStore`) rather than forcing one root store. Slices are for cohesive
+state that shares a store; separate stores for independent domains.
+
+### 4.2 Selectors + `useShallow`
+
+Always select the minimal slice. A bare `useStudioStore()` subscribes to *everything* and
+re-renders on any change. For object/array selections, wrap in `useShallow` to avoid new-reference
+re-renders:
+
+```ts
+import { useShallow } from 'zustand/react/shallow'
+
+// single value — no useShallow needed
+const panel = useStudioStore((s) => s.panel)
+
+// multiple values / object — useShallow REQUIRED (v5 dropped the auto-equality of bare create)
+const { panel, setPanel } = useStudioStore(
+  useShallow((s) => ({ panel: s.panel, setPanel: s.setPanel })),
+)
+```
+
+> v5 note: in v4 you could pass a 2nd `shallow` arg to the bare `create` hook; v5 removed that.
+> Use `useShallow` (or `createWithEqualityFn` from `zustand/traditional` if you truly need a
+> custom equality fn). Default to `useShallow`.
+
+### 4.3 Persistence (studio + auth state)
+
+The app already persists studio/auth via a hand-rolled `localStorage` wrapper
+(`features/studioState/persistence.ts` — manual `JSON.parse`/`stringify`, a `version` field).
+Replace with the `persist` middleware, which gives versioning + migrations + partialize for free:
+
+```ts
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+export const useStudioStore = create<StudioStore>()(
+  persist(
+    (...a) => ({ ...createViewSlice(...a), ...createSelectionSlice(...a) }),
+    {
+      name: 'mapgen-studio', // localStorage key
+      version: 1,
+      storage: createJSONStorage(() => localStorage),
+      // persist ONLY durable UI prefs — never transient/derived state
+      partialize: (s) => ({ panel: s.panel, selectedPresetId: s.selectedPresetId }),
+      migrate: (persisted, fromVersion) => {
+        if (fromVersion < 1) { /* reshape old payload */ }
+        return persisted as StudioStore
+      },
+    },
+  ),
+)
+```
+
+Auth: persist only the durable token/identity bits (`partialize`), never server-fetched profile
+data (that's a query). Use a separate `useAuthStore` with its own `name`.
+
+> SPA hydration caveat: `persist` rehydrates synchronously from `localStorage` on store creation,
+> so there is no SSR mismatch to guard against (see Section 6). If you later add SSR, use
+> `skipHydration` + `rehydrate()`. Not needed now.
+
+### 4.4 The client-vs-server boundary (crisp rule)
+
+> **Server owns it → TanStack Query (oRPC). Browser-only and server-agnostic → Zustand.**
+
+| Belongs in **TanStack Query** (server state) | Belongs in **Zustand** (client state) |
+| --- | --- |
+| Saved map configs, setup config, setup catalog | Which panel/tab is open, modal open/closed |
+| Civ7 live status + snapshots (polled) | Selected preset id, current selection/hover |
+| Run-in-game status, autoplay state from server | Theme, layout, deck.gl view state (UI camera) |
+| Anything fetched from `/rpc` | Draft/unsaved form input before submit |
+| Anything you'd `invalidateQueries` on | Auth token (persisted), feature toggles |
+
+**Anti-pattern to forbid:** copying query results into Zustand (`useEffect(() => store.set(data))`).
+That duplicates the source of truth and reintroduces the stale-state bugs we're removing.
+Components read server data from the query cache and UI state from Zustand — side by side, never
+mirrored. Cross-references go the *other* way (Zustand selection id → used as query `input`).
+
+---
+
+## 5. Recommended client data-layer file structure
+
+```
+apps/mapgen-studio/src/
+  lib/
+    orpc.ts        # RPCLink → createORPCClient → createTanstackQueryUtils  (export `client`, `orpc`)
+    query.ts       # createQueryClient() factory (QueryClient defaultOptions)
+  stores/
+    studioStore.ts # persisted UI state (slices: view, selection, ...)
+    authStore.ts   # persisted auth/identity (token only; profile is a query)
+    themeStore.ts  # theme/layout prefs (persisted)
+    types.ts       # slice interfaces + combined store types
+  features/
+    civ7/
+      useLiveStatus.ts    # useQuery(orpc.civ7.liveStatus.queryOptions(...)) + refetchInterval
+      useLiveSnapshot.ts  # useQuery gated by skipToken on derived request
+    mapConfigs/
+      useSaveMapConfig.ts # useMutation(orpc.mapConfigs.save.mutationOptions(...)) + invalidate
+  main.tsx         # <QueryClientProvider> wraps <App/>
+```
+
+Conventions:
+- `lib/orpc.ts` exports both `client` (imperative) and `orpc` (query utils). Components import
+  `orpc`; rare imperative calls import `client` or use `orpc.x.call(...)`.
+- No `services/` or `api/` folder, no query-key constants file — keys come from `orpc.*.key()`.
+- Feature hooks are thin: they only choose options (interval, enabled, invalidation targets).
+  All typing/serialization is inherited from the contract.
+- `type`-only import of the server `router` for `RouterClient<typeof router>` — keeps server
+  runtime out of the client bundle.
+
+---
+
+## 6. SSR / dev caveats (Vite SPA — no SSR)
+
+This is a **pure client-rendered Vite SPA** (`vite.config.ts`, no SSR framework). Therefore:
+
+- **No hydration boundary needed.** Skip the entire oRPC "Hydration" section
+  (`StandardRPCJsonSerializer` + `dehydrate`/`HydrationBoundary` + `queryKeyHashFn`). That machinery
+  exists only to transfer a server-rendered cache to the client. Not applicable here.
+- **No per-request client isolation.** A module-level `client`/`orpc` singleton in `lib/orpc.ts`
+  is correct and safe — there is no shared server process holding multiple users' state.
+- **QueryClient provisioning:** `useState(createQueryClient)` in the root component (Section 2).
+  Avoids identity churn on HMR; a bare module singleton also works but the `useState` form is the
+  idiomatic default.
+- **`RPCLink` URL:** use the lazy function form `() => \`${window.location.origin}/rpc\`` so it's
+  only evaluated in the browser (defensive; harmless in an SPA) and needs no `VITE_*` env var when
+  same-origin. If the API is on a different origin in dev, set `url` from `import.meta.env.VITE_SERVER_URL`
+  and ensure CORS + `credentials: 'include'`.
+- **Zustand `persist`:** rehydrates synchronously from `localStorage` at store creation — no
+  hydration-mismatch risk in an SPA. `skipHydration`/`rehydrate()` only matter under SSR; do not
+  add them.
+- **Dev server:** Vite proxy (`server.proxy` in `vite.config.ts`) can route `/rpc` to the Effect+oRPC
+  server during dev, keeping the client same-origin and avoiding CORS entirely.
+
+---
+
+## 7. Migration notes (current → target)
+
+| Current (`App.tsx`) | Target |
+| --- | --- |
+| `fetch('/api/map-configs', { method:'POST' })` | `useMutation(orpc.mapConfigs.save.mutationOptions(...))` |
+| `fetch('/api/map-configs/status?requestId=...')` polling | `useQuery(orpc.mapConfigs.status.queryOptions({ input:{requestId}, refetchInterval }))` |
+| `fetch('/api/civ7/saved-configs')` | `useQuery(orpc.civ7.savedConfigs.queryOptions())` |
+| `fetch('/api/civ7/setup-config')` + `setLiveSetup` | `useQuery(orpc.civ7.setupConfig.queryOptions(...))` |
+| `setTimeout(poll)` + `AbortController` + failure counters (live/status) | `useQuery(...).refetchInterval` adaptive fn; signal is automatic |
+| `activeLiveSnapshotRequestKeyRef` dedupe + `shouldCommitLiveRuntimeSnapshot` | query-key change → automatic cancel/dedupe; `skipToken` gating |
+| `features/studioState/persistence.ts` manual localStorage | Zustand `persist` middleware (`version`, `migrate`, `partialize`) |
+| 83 hooks of `useState`/`useEffect` in `App.tsx` | server state → query cache; UI state → sliced Zustand stores |
+
+**Net deletions:** the hand-rolled query layer, manual abort/dedupe plumbing, the
+`persistence.ts` wrapper, and most of the `App.tsx` `useEffect` polling. **Net additions:**
+`lib/orpc.ts`, `lib/query.ts`, the provider, and per-domain Zustand stores.
+
+---
+
+## Sources
+
+- oRPC TanStack Query Integration — https://orpc.dev/docs/integrations/tanstack-query (scraped 2026-06-08; `createTanstackQueryUtils`, `queryOptions`/`mutationOptions`/`infiniteOptions`/`experimental_streamed|liveOptions`, `key`/`queryKey`/`infiniteKey`/`mutationKey`, `skipToken`, operation context, hydration).
+- oRPC Client-Side Clients — https://orpc.dev/docs/client/client-side (`createORPCClient`, `RouterClient<typeof router>`).
+- oRPC RPCLink — https://orpc.dev/docs/client/rpc-link (fetch link, `credentials:'include'`, lazy `url`, `method` for GET, client context).
+- Zustand v5 Reference — https://zustand.docs.pmnd.rs/reference/index (`create`, `createWithEqualityFn`, `useShallow`, `persist`, `combine`, v5 migration).
+- Skill `dev:orpc` (`references/frontend-react-tanstack-query.md`) — client-module pattern, query-key stability, version context (1.13.4 @ 2026-02-05).
+- npm `latest` versions verified 2026-06-08: `@orpc/tanstack-query@1.14.5`, `@orpc/client@1.14.5`, `@orpc/server@1.14.5`, `@tanstack/react-query@5.101.0`, `zustand@5.0.14`.
+- App current state: `apps/mapgen-studio/src/App.tsx` (fetch sites L168–L1042, live poll loop L966–L1080, 83 hook calls), `apps/mapgen-studio/src/features/studioState/persistence.ts` (manual localStorage), `apps/mapgen-studio/src/features/liveRuntime/model.ts` (live runtime state shapes).
+```

From 02c91df1b16eec49812b0d68f8730ce1fec0bb63 Mon Sep 17 00:00:00 2001
From: Matei <tools@matei.work>
Date: Mon, 8 Jun 2026 16:03:10 -0400
Subject: [PATCH 2/5] =?UTF-8?q?feat(studio-server):=20A1=20=E2=80=94=20sca?=
 =?UTF-8?q?ffold=20@civ7/studio-server=20+=20oRPC=20contracts=20(16=20endp?=
 =?UTF-8?q?oints)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Contract-first oRPC package (zod I/O) covering all 16 current /api endpoints
across civ7.*, civ7.live.*, runInGame.*, mapConfigs.*, studio.* — the typed corpus
the client will consume. No business logic yet (services/router land in A2/A3).

Parity captured as contract-level invariants: live.status embedded-{error} 200
shape, non-uniform error status codes, runInGame.start .catchall so the
assertNoRawControlFields security scan can still reject raw control keys, and the
status-404 serverInstanceId/serverStartedAt restart-detection echo. App-anchored
outputs (run-in-game status, save/deploy status, setup catalog) reproduced
field-for-field from features/*/status.ts without importing app code.

Verified: bunx turbo run check --filter=@civ7/studio-server — clean (0 errors).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/studio-server/package.json           |  6 ++---
 packages/studio-server/src/contract/civ7.ts   | 12 ++-------
 packages/studio-server/src/contract/live.ts   | 10 ++-----
 .../studio-server/src/contract/mapConfigs.ts  | 13 +++-------
 .../studio-server/src/contract/runInGame.ts   | 23 +---------------
 packages/studio-server/src/index.ts           | 26 +++----------------
 packages/studio-server/tsconfig.json          |  8 ------
 7 files changed, 13 insertions(+), 85 deletions(-)

diff --git a/packages/studio-server/package.json b/packages/studio-server/package.json
index 5d5d0ba38f..ea49164540 100644
--- a/packages/studio-server/package.json
+++ b/packages/studio-server/package.json
@@ -21,15 +21,13 @@
     }
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "tsup src/index.ts src/contract/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/contract/index.ts --format esm --dts --watch",
     "check": "tsc -p tsconfig.json --noEmit",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run --config ./vitest.config.ts",
     "clean": "rimraf dist"
   },
   "dependencies": {
-    "@civ7/direct-control": "workspace:*",
     "@orpc/client": "1.14.5",
     "@orpc/contract": "1.14.5",
     "@orpc/server": "1.14.5",
diff --git a/packages/studio-server/src/contract/civ7.ts b/packages/studio-server/src/contract/civ7.ts
index 0628c89b73..38f06fc12a 100644
--- a/packages/studio-server/src/contract/civ7.ts
+++ b/packages/studio-server/src/contract/civ7.ts
@@ -1,7 +1,7 @@
 import { oc } from "@orpc/contract";
 import { z } from "zod";
 
-import { isoTimestamp, unknownRecord } from "./shared.js";
+import { gameInfoRow, isoTimestamp, unknownRecord } from "./shared.js";
 
 /**
  * `civ7.*` namespace — FireTuner socket reads + autoplay mutation.
@@ -51,13 +51,6 @@ export const mapSummary = oc
 // Query: table (string, REQUIRED), limit (number, default 100).
 // Success 200: { ok:true, rows }. Error 400 (incl. missing table): { ok:false, error }.
 // NOTE: error status is 400 here, NOT 500.
-//
-// PARITY REFINEMENT (A3): the legacy handler assigns `rows = await
-// getCiv7GameInfoRows(...)` and writes `{ ok:true, rows }` — i.e. `rows` is the
-// WHOLE `Civ7GameInfoRowsResult` object (`{ host, port, table, source, rows,
-// total, … }`), NOT a bare row array. The A1 contract modelled it as
-// `array(gameInfoRow)`, which does not match `/api`. Refined to the opaque result
-// record to preserve current behavior (the deep payload is internal, per shared.ts).
 export const gameInfo = oc
   .input(
     z.object({
@@ -68,8 +61,7 @@ export const gameInfo = oc
   .output(
     z.object({
       ok: z.literal(true),
-      // Civ7GameInfoRowsResult (@civ7/direct-control). Opaque payload (see shared.ts).
-      rows: unknownRecord,
+      rows: z.array(gameInfoRow),
     }),
   );
 
diff --git a/packages/studio-server/src/contract/live.ts b/packages/studio-server/src/contract/live.ts
index 8cedfe9b20..a23a94c5bd 100644
--- a/packages/studio-server/src/contract/live.ts
+++ b/packages/studio-server/src/contract/live.ts
@@ -1,7 +1,7 @@
 import { oc } from "@orpc/contract";
 import { z } from "zod";
 
-import { isoTimestamp, unknownRecord } from "./shared.js";
+import { gameInfoRow, isoTimestamp, unknownRecord } from "./shared.js";
 
 /**
  * `civ7.live.*` sub-namespace — aggregated live runtime reads.
@@ -107,12 +107,6 @@ export const entities = oc
 //   slice(0,8) — 8-table cap), limit(clamp 1..200, default 100).
 // Success 200: { ok:true, observedAt, tables: Record<table, rows> }.
 // Error 400: { ok:false, error }. N parallel reads.
-//
-// PARITY REFINEMENT (A3): each `tables[table]` value is the WHOLE
-// `Civ7GameInfoRowsResult` object (legacy maps `[table, await
-// getCiv7GameInfoRows(...)]`), not a bare row array — same mismatch as
-// `civ7.gameInfo` (#3). Refined from `array(gameInfoRow)` to the opaque result
-// record to preserve current `/api` behavior.
 export const gameInfo = oc
   .input(
     z.object({
@@ -124,6 +118,6 @@ export const gameInfo = oc
     z.object({
       ok: z.literal(true),
       observedAt: isoTimestamp,
-      tables: z.record(z.string(), unknownRecord),
+      tables: z.record(z.string(), z.array(gameInfoRow)),
     }),
   );
diff --git a/packages/studio-server/src/contract/mapConfigs.ts b/packages/studio-server/src/contract/mapConfigs.ts
index 396d096f6f..bb2585fcc2 100644
--- a/packages/studio-server/src/contract/mapConfigs.ts
+++ b/packages/studio-server/src/contract/mapConfigs.ts
@@ -34,16 +34,9 @@ export const saveDeployStatusSchema = z.object({
   error: z.string().optional(),
   deploy: z
     .object({
-      build: z
-        .object({
-          task: z.string().optional(),
-          stdout: z.string().optional(),
-          stderr: z.string().optional(),
-        })
-        .optional(),
-      targetDir: z.string().optional(),
-      modsDir: z.string().optional(),
-      filesCopied: z.number().optional(),
+      command: z.string().optional(),
+      stdout: z.string().optional(),
+      stderr: z.string().optional(),
     })
     .optional(),
   details: z.record(z.string(), z.unknown()).optional(),
diff --git a/packages/studio-server/src/contract/runInGame.ts b/packages/studio-server/src/contract/runInGame.ts
index 1333472105..56d227ab16 100644
--- a/packages/studio-server/src/contract/runInGame.ts
+++ b/packages/studio-server/src/contract/runInGame.ts
@@ -48,17 +48,6 @@ const fileIdentity = z.object({
   mtimeIso: z.string(),
 });
 
-const contentMarkerProof = z.object({
-  id: z.string(),
-  marker: z.string(),
-  present: z.boolean(),
-});
-
-const fileContentProof = z.object({
-  path: z.string(),
-  markers: z.array(contentMarkerProof),
-});
-
 // RunInGameSourceSnapshotProof
 const sourceSnapshotProof = z.object({
   identityHash: z.string(),
@@ -84,8 +73,6 @@ const materializationStatus = z.object({
   generatedSourceScript: fileIdentity.optional(),
   localModScript: fileIdentity.optional(),
   deployedModScript: fileIdentity.optional(),
-  localModScriptContent: fileContentProof.optional(),
-  deployedModScriptContent: fileContentProof.optional(),
 });
 
 // RunInGameRequestStatus
@@ -260,15 +247,7 @@ export const start = oc
         sourceSnapshot: z.unknown().optional(),
         selectedConfig: z
           .object({
-            // `id` is OPTIONAL: disposable runs send `selectedConfig` without one,
-            // and `parseRunInGameSetupRequest` (apps/.../server/runInGame/
-            // requestValidation.ts) reads `selected.id` defensively (defaulting to
-            // "studio-current" when absent). Declaring it required forced the caller
-            // to launder the request through an `as unknown as Parameters<…>` cast;
-            // making it optional here aligns the contract with the validator + engine
-            // and restores end-to-end input type safety on the
-            // `assertNoRawControlFields`-protected start path.
-            id: z.string().optional(),
+            id: z.string(),
             label: z.string().optional(),
             description: z.string().optional(),
             sourcePath: z.string().optional(),
diff --git a/packages/studio-server/src/index.ts b/packages/studio-server/src/index.ts
index 7973a955c6..9ebd657f22 100644
--- a/packages/studio-server/src/index.ts
+++ b/packages/studio-server/src/index.ts
@@ -1,29 +1,9 @@
 /**
  * `@civ7/studio-server` — public entrypoint.
  *
- * - Contract surface (slice A1): zod I/O for all 16 endpoints.
- * - Effect services (A2): `Civ7TunerClient`, `StudioConfig`.
- * - effect-orpc router (A3): `createStudioRouter` + non-uniform error mapping.
- * - Host handler (A4-lite): `createStudioRpcHandler(context)` → an `RPCHandler`
- *   the host mounts at `/rpc` (the Vite dev middleware this run; a Bun server
- *   later). A standalone Bun process is DEFERRED (FRAME §4.7).
- *
- * The host supplies a {@link StudioServerContext} carrying the process singletons,
- * the catalog loader, and the three stateful engine fns (shared queue + dual-store
- * mutex live host-side) — see ./context.ts.
+ * Slice A1 exports the oRPC contract surface only (zod I/O for all 16 endpoints).
+ * Later slices add Effect services (A2), the effect-orpc router (A3), and the Bun
+ * server entrypoint (A4) behind this barrel.
  */
 export { contract, civ7, live, mapConfigs, runInGame, studio } from "./contract/index.js";
 export type { StudioContract } from "./contract/index.js";
-
-export type {
-  StudioServerContext,
-  StudioInputs,
-  StudioOutputs,
-  SetupCatalog,
-} from "./context.js";
-export { errorMessage, orpcError } from "./errors.js";
-export { createStudioRpcHandler, type StudioRpcHandle } from "./handler.js";
-export { createStudioRouter, type StudioRouter } from "./router/index.js";
-export { makeStudioRuntime, type StudioRuntime } from "./runtime.js";
-export { Civ7TunerClient } from "./services/Civ7TunerClient.js";
-export { StudioConfig } from "./services/StudioConfig.js";
diff --git a/packages/studio-server/tsconfig.json b/packages/studio-server/tsconfig.json
index 1873348175..b1aa97609c 100644
--- a/packages/studio-server/tsconfig.json
+++ b/packages/studio-server/tsconfig.json
@@ -4,14 +4,6 @@
     "rootDir": "./src",
     "outDir": "./dist",
     "types": ["node"],
-    // `effect-orpc` (and our tsup build) ship/consume ESM bundled by a bundler, and
-    // effect-orpc publishes raw `.ts` source via `exports` with extensionless
-    // relative imports that `nodenext` rejects. The package is built with tsup
-    // (bundler semantics) and consumed by the app under Vite (also a bundler), so
-    // typecheck with bundler resolution to match. Our own relative imports keep the
-    // explicit `.js` extension (valid under bundler too) for nodenext-clean output.
-    "module": "esnext",
-    "moduleResolution": "bundler",
     "verbatimModuleSyntax": true
   },
   "include": ["src/**/*.ts"]

From c08e5ffec9a664bd053ea2f9e107e0c4aa07c5d3 Mon Sep 17 00:00:00 2001
From: Matei <tools@matei.work>
Date: Mon, 8 Jun 2026 16:12:04 -0400
Subject: [PATCH 3/5] =?UTF-8?q?docs(mapgen-studio):=20PAUSE=20redesign=20?=
 =?UTF-8?q?=E2=80=94=20live-control=20substrate=20correction?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User correction: no FireTuner reads; consume the actual latest live-control code.
Verified the new effect-oRPC control substrate (control-oRPC router +
Civ7IntelligenceBridge) is NOT in this base (packages/civ7-control-orpc is empty)
— it lives in the 570-branch live-control stack still being consolidated, and the
mapgen-studio Studio link is itself being rebuilt there. Studio reads live state
today via @civ7/direct-control (vite.config.ts:32), the surface being superseded.

Decision: full pause. Re-baseline off `main` once the consolidated control-oRPC
work merges. Server (Phase A) + data (Phase B) + live-coupled decomposition are
blocked; their server-contract audit (05) and architecture §1 are marked
provisional. Design-system / component-architecture / TS-rigor audits and
client-pattern research remain valid. Resume conditions recorded in 00-GOAL.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../mapgen-studio-redesign/00-GOAL.md         | 76 ++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/docs/projects/mapgen-studio-redesign/00-GOAL.md b/docs/projects/mapgen-studio-redesign/00-GOAL.md
index 9c33021bcb..0c7645336c 100644
--- a/docs/projects/mapgen-studio-redesign/00-GOAL.md
+++ b/docs/projects/mapgen-studio-redesign/00-GOAL.md
@@ -88,4 +88,78 @@ constraint to preserve. The intent (typed, native oRPC×Effect server) stands; t
 
 - Branch: `design/mapgen-studio-redesign`. Strategy: one branch, one commit per
   slice, one PR (not a multi-branch Graphite stack — lower risk for autonomous run).
-- Next: Phase A (server `@civ7/studio-server`).
+- Committed `cae889456` (planning), `5dba36d35` (A1 contracts).
+
+## ⚠ LIVE-CONTROL SUBSTRATE CORRECTION (2026-06-08) — Phase A/B PAUSED
+
+User correction: **no FireTuner reads — there is a better way now**, and the
+redesign must consume the **actual latest live-control code**, which is **not in
+this base**.
+
+Ground truth verified:
+- `packages/civ7-control-orpc` is **empty (0 ts files)** on this branch. The new
+  **effect-oRPC control router + `Civ7IntelligenceBridge` ingress** (the target
+  read/action substrate) lives in the **570-branch live-control stack currently
+  being consolidated** — see `docs/projects/graphite-stack-integration/`
+  `LIVE-CONTROL-STACK-CONSOLIDATION-PLAYBOOK.md`. It is **not settled** (local-only,
+  no PRs, folding 570 → ≤50 semantic branches).
+- The studio reads live state **today** via `@civ7/direct-control`
+  (`apps/mapgen-studio/vite.config.ts:32`) — exactly the surface being rebuilt.
+  **FireTuner is being demoted** to canary/parity/diagnostic; the in-game App-UI
+  controller bridge (oRPC/Effect) becomes baseline.
+- The **mapgen-studio ↔ control "Studio link" is itself being rebuilt** inside
+  that stack (playbook rows 38, 42–43). So Phase A (replace the studio server)
+  would collide with / be superseded by that work.
+
+Consequences:
+- **`audit/05-server-contracts.md` and `architecture/10` §1 (server) are PROVISIONAL /
+  superseded** — they model the deprecated `@civ7/direct-control` surface. Re-baseline
+  against the consolidated control-oRPC contracts once that stack settles.
+- **A1 (`@civ7/studio-server` contracts) is provisional** — kept on this isolated
+  branch for reference; will be re-derived from the settled substrate.
+- Reference prior art for the target client stack (effect-oRPC + RPCLink +
+  oRPC-TanStack-Query + Zustand React shell) already exists in the repo's
+  **gt-stack-inspect** toolkit lane — mirror it when re-baselining (that lane is a
+  separate owner and out of scope to modify).
+
+Lane status:
+- ⏸ **PAUSED (blocked on live-control settle):** Phase A (server), Phase B (data
+  layer + live wiring), live-state-coupled parts of Phase D (decomposition).
+- ✅ **Still valid (decoupled from live-control):** Phase C (Tailwind v4 + shadcn +
+  token/theming repair) and the presentational parts of Phase E. These are
+  app-local CSS + primitive components with no `@civ7/direct-control` coupling.
+  Carries minor merge risk against in-flight "Studio link" branches.
+- ✅ **Still-valid audits:** `audit/03` (component architecture), `audit/04`
+  (design system), `audit/06` (TS rigor), `research/02` (client patterns).
+
+## ⏸ WORKSTREAM PAUSED — resume conditions (decided 2026-06-08)
+
+User decision: **full pause**; re-baseline source of truth = **`main`** (not the
+in-flight stack). Do **not** proceed on any lane — including the decoupled design
+system — until resumed.
+
+**Resume trigger:** the consolidated control-oRPC / direct-control substrate
+(effect-oRPC router + `Civ7IntelligenceBridge` ingress + rebuilt mapgen-studio
+"Studio link") has **merged to `main`**. The user will signal, or I re-check `main`.
+
+**On resume, before writing any code:**
+1. `git checkout main && git pull`; rebase `design/mapgen-studio-redesign` onto it.
+2. Re-audit the **settled** substrate on main: read the merged `@civ7/control-orpc`
+   router + contracts, the `Civ7IntelligenceBridge` invoke surface, how Tuner is
+   now scoped (canary/diagnostic), and how the studio is now wired to control.
+3. **Re-baseline** `audit/05-server-contracts.md` and `architecture/10` §1 against
+   those real contracts. Re-derive A1 (`@civ7/studio-server`) — the studio server
+   should consume/extend the control-oRPC substrate, **not** re-implement reads and
+   **not** read FireTuner.
+4. Mirror the repo's existing effect-oRPC + RPCLink + oRPC-TanStack + Zustand
+   pattern (gt-stack-inspect lane) for the client.
+5. Then resume Phase A → G per `architecture/11-slice-plan.md`.
+
+**Unchanged on resume (no re-audit needed):** the design-system, component-
+architecture, and TS-rigor audits and the client-pattern research remain valid.
+
+## Status ledger (paused)
+
+- [x] Frame, isolate, research, audit, target architecture, slice plan
+- [x] A1 — `@civ7/studio-server` contracts (PROVISIONAL — re-derive on resume)
+- [⏸] Everything downstream — blocked until control-oRPC lands on `main`

From 40a048902e4f5ac03ecdcab33573a4c03613face Mon Sep 17 00:00:00 2001
From: Matei <tools@matei.work>
Date: Mon, 8 Jun 2026 16:20:01 -0400
Subject: [PATCH 4/5] docs(mapgen-studio): add post-merge resume prompt for
 redesign workstream
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Self-contained handoff packet (framing-design: objective-framing × audience-export
for a post-compaction recipient). Lets the user re-enter the paused redesign after
the control-oRPC substrate merges to main: read-first docs, confirmed decisions,
realign+re-baseline checklist (consume control-oRPC, no FireTuner), Phase A→G plan,
hard core + falsifier. Includes a guard to STOP if main lacks the substrate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../mapgen-studio-redesign/RESUME-PROMPT.md   | 81 +++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 docs/projects/mapgen-studio-redesign/RESUME-PROMPT.md

diff --git a/docs/projects/mapgen-studio-redesign/RESUME-PROMPT.md b/docs/projects/mapgen-studio-redesign/RESUME-PROMPT.md
new file mode 100644
index 0000000000..5f0ccacbaf
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/RESUME-PROMPT.md
@@ -0,0 +1,81 @@
+# Resume Prompt — MapGen Studio Redesign (post live-control merge, post-compaction)
+
+> Hand the block below back to the agent once the consolidated control-oRPC work
+> has merged to `main`. It is self-contained and assumes zero memory of the prior
+> session. (Mirror copy of this lives in git; the agent should still re-read the
+> linked docs as the source of truth.)
+
+---
+
+You are resuming a **paused, already-framed workstream**: the MapGen Studio
+redesign. You have **no memory** of the prior session — everything you need is in
+the repo. **Do not write any code until you have re-grounded and re-baselined.**
+
+**One-line intent:** Rebuild `apps/mapgen-studio` into a top-1%, data-driven
+React 19 app — decomposed architecture, real state/server-data boundaries, full
+canonical shadcn + Tailwind v4, end-to-end types — **without changing** map-gen,
+Deck.gl, recipe, or live-game behavior. **Behavior parity is hard core.** We
+paused because the live-control substrate the new server must consume was
+mid-consolidation; you are resuming because it has now merged to `main`.
+
+**STEP 0 — Read first (durable source of truth; trust these over any summary):**
+- `docs/projects/mapgen-studio-redesign/00-GOAL.md` — frame, confirmed decisions,
+  the live-control correction, and the exact resume checklist. **Read fully.**
+- `docs/projects/mapgen-studio-redesign/architecture/10-target-architecture.md` and
+  `11-slice-plan.md`.
+- Still valid: `audit/03` (components), `audit/04` (design system), `audit/06`
+  (TS rigor), `research/01` (oRPC×Effect×Bun), `research/02` (oRPC-TanStack+Zustand),
+  `apps/mapgen-studio/system.md`.
+- **Provisional / re-derive:** `audit/05-server-contracts.md` and `architecture/10` §1.
+
+**Confirmed decisions (do NOT re-litigate — the user already chose these):**
+- Server: native **effect-oRPC** router on a **Bun** server. The `effect-orpc`
+  library (utopyin/effect-orpc) is **mandated**; isolate it to the router layer.
+- The studio server must **consume/extend the now-merged `@civ7/control-orpc`
+  substrate** (Civ7IntelligenceBridge ingress). **No FireTuner reads. Do not
+  re-implement live reads.** FireTuner is canary/diagnostic only.
+- Client: oRPC's **native TanStack Query** integration (use the generated query
+  utils directly) + **Zustand** for UI state. Mirror the repo's existing
+  **gt-stack-inspect** pattern (effect-oRPC + RPCLink + oRPC-TanStack + Zustand).
+- Design system: **full canonical shadcn/ui** (Radix, `components.json`) +
+  **Tailwind v4**. Fix the broken theming (`createTheme`/`lightMode`); one
+  committed accent; HSL tokens.
+- Execution: **fully autonomous to a single PR**. One branch
+  `design/mapgen-studio-redesign`, one commit per slice. Use a **team of agents**
+  per the `civ7-systematic-workstream` method.
+
+**STEP 1 — Realign (before any code):**
+1. `git checkout main && git pull`; checkout `design/mapgen-studio-redesign`;
+   rebase it onto `main`.
+2. **Guard:** if `packages/civ7-control-orpc` is still empty / the consolidated
+   substrate is NOT actually on `main`, **STOP and tell the user** — the resume
+   trigger has not fired.
+3. Re-audit the **settled** substrate on `main` (use research/audit agents): the
+   merged `@civ7/control-orpc` router + contracts, the `Civ7IntelligenceBridge`
+   invoke surface, how FireTuner is now scoped, and how mapgen-studio is now wired
+   to control (the rebuilt "Studio link").
+4. **Re-baseline** `audit/05` and `architecture/10` §1 against the real contracts.
+   Re-derive the A1 `@civ7/studio-server` contracts to **consume** control-oRPC
+   (not `@civ7/direct-control`, not FireTuner). Update `00-GOAL.md` status ledger.
+5. Re-confirm the do-not-break parity registry (`architecture/10` §7) against the
+   new substrate.
+
+**STEP 2 — Implement (Phase A→G of `11-slice-plan.md`), fully autonomous:**
+A server (effect-oRPC on Bun, consuming control-oRPC) → B client data layer
+(oRPC-native TanStack + Zustand) → C design-system foundation (Tailwind v4 +
+shadcn + tokens) → D decompose the 3,010-line `App.tsx` → E primitives→Radix
+shadcn + new components + rjsf re-skin + craft → F TS-rigor flags
+(`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `verbatimModuleSyntax`)
++ dead code + intentional comments → G verify + agent review wave + open PR.
+
+**Hard core (never sacrifice):** behavior parity for map-gen, Deck.gl, recipes,
+and the live-control loop; end-to-end type safety.
+**Falsifier:** if decomposition or the server migration cannot preserve those
+behaviors, or "simpler" measurably degrades the authoring workflow — **stop,
+re-scope, and tell the user.**
+
+**Verify** each slice (`tsc --noEmit` clean + app builds) and at the end (tests +
+parity checks on the live-control loop and run-in-game). Commit per slice. Open
+**one** PR linking the workstream docs. Track phases with a task list.
+
+---

From be98643e661aac8ecb11a53ce87848799107d785 Mon Sep 17 00:00:00 2001
From: Matei <tools@matei.work>
Date: Mon, 8 Jun 2026 22:47:14 -0400
Subject: [PATCH 5/5] =?UTF-8?q?docs(mapgen-studio):=20reframe=20redesign?=
 =?UTF-8?q?=20=E2=80=94=20normative=20FRAME,=20un-pause,=20design-system-f?=
 =?UTF-8?q?irst?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add FRAME.md: normative operating model + guardrails (Graphite never-submit,
  design-system-first, OpenSpec-backed slices, live-control seam vs wait-for-merge,
  parity hard core, falsifier).
- Reset controlling goal in 00-GOAL.md (create-goal fallback record); supersede
  the PAUSED/wait-for-merge sections; ACTIVE status ledger in design-system-first
  phase order (P1 design system → P7 hand over unsubmitted stack).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../mapgen-studio-redesign/00-GOAL.md         |  41 ++++-
 docs/projects/mapgen-studio-redesign/FRAME.md | 163 ++++++++++++++++++
 2 files changed, 201 insertions(+), 3 deletions(-)
 create mode 100644 docs/projects/mapgen-studio-redesign/FRAME.md

diff --git a/docs/projects/mapgen-studio-redesign/00-GOAL.md b/docs/projects/mapgen-studio-redesign/00-GOAL.md
index 0c7645336c..5325d3a1ff 100644
--- a/docs/projects/mapgen-studio-redesign/00-GOAL.md
+++ b/docs/projects/mapgen-studio-redesign/00-GOAL.md
@@ -2,6 +2,30 @@
 
 > Controlling scope for the systematic workstream. This is the closure test:
 > work is done when this objective is met and its falsifier has not fired.
+>
+> **Controlling frame:** [`FRAME.md`](FRAME.md) (normative operating model +
+> guardrails). On any conflict, FRAME → this goal → architecture → audits.
+> **Status: ACTIVE (un-paused 2026-06-08).** All "PAUSED / wait-for-merge"
+> sections below are **superseded** by FRAME §4 (Operating Model) and §7
+> (revised phase order). They are retained only as history.
+
+## Active goal (controlling, create-goal fallback record)
+
+Active goal:
+Rebuild `apps/mapgen-studio` into a top-1%, data-driven React 19 app —
+design-system-first, decomposed architecture, real client-state vs server-data
+boundaries (oRPC-native TanStack Query + Zustand), full canonical shadcn +
+Tailwind v4, end-to-end types, intentional comments/organization — WITHOUT
+changing map-gen, Deck.gl, recipe, or live-game behavior (parity is hard core).
+Deliver as a Graphite stack of OpenSpec-backed slices, each a domino;
+**never submit the stack**. Do NOT wait for the live-control stack to merge:
+work off `main`, inspect the TOP of the live-control `codex/*` stack, and design
+the exact studio↔control-oRPC integration seam to bind later (no FireTuner reads,
+no re-implementing live reads). Build the design system FIRST (via `design:*`),
+then consume it everywhere. Fully autonomous; confirm design *direction* once at
+`design:init`. Falsifier: if decomposition/server migration can't preserve
+parity, or "simpler" degrades the authoring workflow, or the designed seam is
+incompatible with what lands on `main` — stop and tell the user.
 
 ## Active goal
 
@@ -158,8 +182,19 @@ system — until resumed.
 **Unchanged on resume (no re-audit needed):** the design-system, component-
 architecture, and TS-rigor audits and the client-pattern research remain valid.
 
-## Status ledger (paused)
+## Status ledger (ACTIVE — supersedes the paused ledger above)
+
+Phase order per [`FRAME.md`](FRAME.md) §7 (design-system-first):
 
 - [x] Frame, isolate, research, audit, target architecture, slice plan
-- [x] A1 — `@civ7/studio-server` contracts (PROVISIONAL — re-derive on resume)
-- [⏸] Everything downstream — blocked until control-oRPC lands on `main`
+- [x] Re-frame + un-pause + normative FRAME.md + goal reset (2026-06-08)
+- [ ] **P1 Design system** (`design:*` chain) — FIRST DOMINO, in progress next
+- [ ] P2 Client data layer (oRPC-native TanStack Query + Zustand, behind seam)
+- [ ] P3 Component decomposition (un-god App.tsx onto the design system)
+- [ ] P4 Primitives→shadcn + new components + rjsf re-skin + craft
+- [ ] P5 Server (effect-oRPC on Bun, aligned to control-oRPC stack-top seam)
+- [ ] P6 Rigor + dead code + comments
+- [ ] P7 Verify + review wave → hand over **built, UNSUBMITTED** Graphite stack
+- [~] A1 `@civ7/studio-server` contracts (PROVISIONAL — re-derive vs stack-top in P5)
+
+Live-control: NOT waiting for merge. Inspect stack-top, design the seam (FRAME §6).
diff --git a/docs/projects/mapgen-studio-redesign/FRAME.md b/docs/projects/mapgen-studio-redesign/FRAME.md
new file mode 100644
index 0000000000..34e3b164a7
--- /dev/null
+++ b/docs/projects/mapgen-studio-redesign/FRAME.md
@@ -0,0 +1,163 @@
+# MapGen Studio Redesign — Normative Operational Frame
+
+> **What this is.** The durable, compaction-surviving operating frame for this
+> workstream. It is the lens, not the task list. Read it first on every resume.
+> It names the objective, what is in/out, what may never break, what would force
+> a reframe, and the guardrails the user set. Concrete code, paths, branches, and
+> skills are *referenced*, not inlined — follow the reference when you need the
+> detail.
+>
+> **Authority order when sources disagree:** this FRAME (intent + guardrails) →
+> [`00-GOAL.md`](00-GOAL.md) (active goal + status ledger) →
+> [`architecture/10-target-architecture.md`](architecture/10-target-architecture.md)
+> + [`architecture/11-slice-plan.md`](architecture/11-slice-plan.md) (how) → the
+> audits/research (`audit/*`, `research/*`). Any prior "PAUSED / wait-for-merge"
+> language is **superseded** by the Operating Model below.
+
+---
+
+## 1. Objective (framed)
+
+Transform `apps/mapgen-studio` from a 3,010-line god-component into a **top-1%,
+data-driven** React 19 application — decomposed architecture, real
+state/server-data boundaries, a **first-class design system**, accessibility and
+interaction craft, and intentional comments/organization — **without changing**
+map-generation, Deck.gl rendering, recipe semantics, or live-game runtime
+behavior. The work is delivered as a **Graphite stack of OpenSpec-backed slices**
+that is **never submitted**, each slice a domino that makes the next easier.
+
+"Data-driven, not commodity content-driven" is the quality bar: structure,
+tokens, contracts, and types carry the interface — not bespoke one-off markup.
+
+## 2. Selection & salience (the frame proper)
+
+- **In / foregrounded:** component decomposition; client state + server-data
+  architecture; **design-system formalization (the first domino)**; accessibility
+  and interaction craft; intentional comments/organization; end-to-end type
+  safety; the *interface seam* to live-control.
+- **Exterior (deliberately out — not absent, constructed-out):** map-generation
+  algorithms, Deck.gl math, recipe semantics, game-runtime/mod behavior, **and
+  the implementation of the live-control substrate itself** (owned by the
+  `codex/*` live-control stack — we design *toward* it, we do not build it).
+- **Structural alternative considered & rejected:** a pure visual reskin
+  (tokens + polish, leave the state tangle). Rejected — the 3k-line state tangle
+  is the actual ceiling on robustness, and a reskin cannot lift it.
+
+## 3. Hard core · protective belt · falsifier
+
+- **Hard core (never sacrificed):** behavior parity for map-gen, Deck.gl,
+  recipes, and the live-control loop; end-to-end type safety; the design system,
+  once established, is the single source of UI truth (no parallel ad-hoc styling).
+- **Protective belt (negotiable under pressure):** exact file/module layout,
+  slice ordering within a phase, which shadcn components ship in which slice,
+  whether the server cutover lands now or is staged behind the live-control seam.
+- **Falsifier (forces a reframe — STOP and tell the user):** if decomposition or
+  the server migration cannot preserve the hard-core behaviors; if "simpler"
+  measurably degrades the authoring workflow; or if the live-control seam we
+  design toward turns out to be incompatible with what lands in `main`.
+
+## 4. Operating model & guardrails (user-set, normative)
+
+These are the standing constraints. Violating one is a defect, not a tradeoff.
+
+1. **Graphite-first, never submit.** All branch/stack/PR-shaped git actions go
+   through `gt` (skill: `graphite`). Build the work as a **stack of slices**,
+   one logical change per branch, bottom-up. **Do not `gt submit`** — not the
+   stack, not a branch. The deliverable is a *local* stack the user reviews and
+   ships themselves. Use `gt sync --no-restack` + `gt restack --upstack` (shared
+   metadata; this repo runs many parallel `codex/*` worktrees — never global
+   restack by accident).
+2. **Design system first, then everything downstream uses it.** The first real
+   work is building the design system via the `design:*` command chain
+   (`design:init` → `design:extract`/`design:audit`/`design:critique`/
+   `design:status`; `design:init` reads the `ui-design` skill and writes a
+   `system.md`). Every later component slice consumes that system; none predates
+   it. This re-orders the slice plan: **design-system foundation precedes server
+   and decomposition work.**
+3. **OpenSpec-backed changesets.** Every logically-grouped change is recorded as
+   an OpenSpec change under `openspec/changes/<change-id>/` (CLI:
+   `bun run openspec -- …`; skill: `civ7-open-spec-workstream`). One OpenSpec
+   change ↔ one Graphite slice ↔ one coherent domino. Validate before stacking.
+4. **Do NOT wait for the live-control stack to merge.** The studio-relevant
+   substrate is mostly already in `main`; the rest is mid-consolidation in the
+   `codex/*` stack (see [the consolidation playbook](../graphite-stack-integration/LIVE-CONTROL-STACK-CONSOLIDATION-PLAYBOOK.md)).
+   That stack is *restacking to catch up to code already on main / our stack* — we
+   are partially ahead. So we work off `main` now and treat live-control as a
+   **coordinated peer team**: inspect the **top of the live-control stack**,
+   design the exact interfaces / flows / boundaries / domain organization the
+   studio needs, and plan toward that eventual integration — without building or
+   blocking on it. See §6.
+5. **No FireTuner reads.** Live state is consumed through the control-oRPC /
+   intelligence-bridge seam, never FireTuner (canary/diagnostic only). When the
+   real surface isn't on `main` yet, design against the stack-top contract and
+   stage behind the seam.
+6. **Fully autonomous to a built (unsubmitted) stack.** No per-gate approval.
+   The one genuine taste fork — design *direction* — is confirmed once at
+   `design:init` per that command's own protocol; everything else proceeds.
+
+## 5. Skills & mechanisms (reference, load on demand)
+
+| Concern | Mechanism / skill | Where |
+| --- | --- | --- |
+| Frame & objective | `framing-design`, `create-goal` | cognition skills (paths in chat) |
+| Systematic method (12 gates) | `civ7-systematic-workstream` | `.agents/skills/` |
+| Changeset phases | `civ7-open-spec-workstream` + OpenSpec CLI | `.agents/skills/`, `openspec/` |
+| Graphite discipline | `graphite` | plugin skill |
+| Design system | `design:init/extract/audit/critique/status` + `ui-design` | `design` plugin (commands) |
+| Component/composition craft | `vercel-react-best-practices`, `vercel-composition-patterns`, `ui-design` | referenced skills |
+| Type rigor | `typescript` | referenced skill |
+| Multi-agent team | `team-design` | referenced skill |
+| Read-only setup introspection | `introspect` | `meta` plugin skill |
+
+## 6. Live-control integration seam (peer-team coordination)
+
+The studio is the "frontend"; the `codex/*` live-control stack is the "backend."
+They must meet at a designed seam, not by accident.
+
+- **Ground truth today:** `packages/civ7-control-orpc` is an **empty placeholder**
+  on this branch and **absent from `main`**; the studio reads live state via
+  `@civ7/direct-control` (`apps/mapgen-studio/vite.config.ts`). The consolidated
+  effect-oRPC control router + intelligence-bridge ingress, and the rebuilt
+  mapgen-studio "Studio link", live in the live-control stack (playbook rows for
+  the Studio link).
+- **Obligation:** before designing the studio's server/data seam, **inspect the
+  top of the live-control stack** (the `codex/*` control-oRPC branches; identify
+  the tip from the consolidation playbook) and capture the *target* control-oRPC
+  contract surface the studio will consume. Record it as the re-baseline of
+  [`audit/05`](audit/05-server-contracts.md) and §1 of
+  [`architecture/10`](architecture/10-target-architecture.md), explicitly marked
+  "designed-toward stack-top, not yet on main."
+- **Posture:** design the exact interfaces/flows/boundaries/domain organization
+  for that integration; build the decoupled studio shell, design system, state,
+  and decomposition now; keep the live-state consumption behind a thin seam that
+  can bind to the real control-oRPC client when it lands. Never re-implement live
+  reads; never read FireTuner.
+
+## 7. Revised phase order (supersedes slice-plan sequencing)
+
+Design-system-first re-orders [`architecture/11-slice-plan.md`](architecture/11-slice-plan.md).
+Canonical order for this workstream:
+
+1. **Design system** (was Phase C) — `design:*` chain → tokens, theming repair,
+   shadcn + Tailwind v4 foundation, documented `system.md`. **First domino.**
+2. **Client data layer** (Phase B) — oRPC-native TanStack Query + Zustand, with
+   live consumption behind the live-control seam (§6).
+3. **Component decomposition** (Phase D) — un-god `App.tsx` onto the design system.
+4. **Primitives → shadcn + new components + rjsf re-skin + craft** (Phase E).
+5. **Server** (Phase A) — effect-oRPC on Bun, consuming/aligned to control-oRPC;
+   staged with respect to the live-control seam, not blocking the UI work.
+6. **Rigor + cleanup** (Phase F) — strict tsconfig flags, dead code, comments.
+7. **Verify + review wave** (Phase G) — but **close by handing the user a built,
+   unsubmitted Graphite stack**, not by submitting a PR.
+
+Each step: OpenSpec change → Graphite slice → `tsc --noEmit` clean + builds +
+parity on touched surfaces → stack, **do not submit**.
+
+## 8. Status anchor
+
+- Branch base: `design/mapgen-studio-redesign` (planning/frame base), stacked on
+  `main`. Implementation slices stack on top.
+- This frame **un-pauses** the workstream under the Operating Model above. The
+  old "full pause until control-oRPC merges to main" resume condition is retired;
+  the live-control seam (§6) replaces it.
+- Live status + closure tracking: [`00-GOAL.md`](00-GOAL.md) § status ledger.