docs: record editor-first UI-scene convention (ADR 0001)

Capture the direction change from M3-b: UI screens are authored editor-first
as .tscn node trees (previewable/arrangeable in the Godot editor), scripts do
on-load work only — never build the tree in _ready(). Add ADR 0001, a
"UI scene conventions" how-to in client/docs, a §16 mandate in the charter,
and mark M3-a/M3-b done in the roadmap.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/adr/0001-editor-first-ui-scenes.md

@@ -0,0 +1,86 @@
+# 0001 — UI screens are editor-authored scenes, not code-built
+
+- **Status:** accepted
+- **Date:** 2026-07-11 (M3-b, Main Window shell)
+
+## Context
+
+The M3-b Main Window shell was first built by constructing every Control node in
+`_ready()` (a pattern borrowed from `theme_showcase.gd`, where it was fine because
+the showcase is a throwaway proof). For a real screen this was wrong:
+
+- **It does not preview in the Godot editor.** Opening the `.tscn` showed a bare
+  root Control — every widget only existed at runtime — so the human could not see
+  or arrange the layout in the editor. Tuning meant editing pixel offsets in code,
+  running, eyeballing, repeating.
+- It buried layout, styling, and content in GDScript, where it is verbose and
+  hard to reason about, and it drifted from charter §16's own words: *"each screen
+  is recreated as a Godot 4.7 Control-node scene."*
+
+The human asked to be able to arrange the scene in the editor "as much as
+possible," with code only for genuine on-load work.
+
+## Decision
+
+**UI screens (and their sub-scenes) are authored editor-first as `.tscn` node
+trees.** The split:
+
+- **In the `.tscn` (editor):** the whole node tree — containers, panels, labels,
+  buttons, art-slot placeholders — with the shared `Theme` assigned on the scene
+  root and every `theme_type_variation` set on its node. Authored placeholder
+  text/values so the screen previews with representative content. Sub-screens are
+  **instanced** (`ExtResource` PackedScene), not rebuilt.
+- **In the script (on-load only):** `@onready` references to named nodes; wiring
+  (signals, the DM loop, injected services); animations (e.g. the dock slide);
+  and **binding state into the authored nodes** (setting label text/colours from
+  the model). Never construct the tree in `_ready()`.
+- **Data-driven repeats** (turn-order tokens, consumable slots, later inventory
+  grids) are a **fixed set of authored nodes** bound from state at runtime —
+  spare slots hide. This keeps them previewable; combat/inventory become the
+  writers later. (Author enough slots for the common case; if a screen ever needs
+  a genuinely unbounded list, revisit with a code-instanced container then.)
+
+Supporting conventions established alongside this decision:
+
+- **Scene root sizing.** Give the `.tscn` root a fixed size (e.g. 1920×1080) via
+  offsets so it previews, but **no full-rect anchors on the root** — a root
+  Control run via F6 is not sized by full-rect anchors and collapses to (0,0).
+  The script keeps `size = get_viewport_rect().size` on `_ready` +
+  `size_changed` (the M3-a lesson).
+- **Button styling uses Button-base theme variations.** Never apply a
+  PanelContainer-base variation (`DarkPanel`, `ParchmentCard`) to a `Button` — a
+  Button looks up `normal/hover/pressed`, which a `panel`-only variation lacks, so
+  it renders unskinned. M3-b added Button-base `DockButton` and `ParchmentButton`
+  to the theme for exactly this.
+- **RichTextLabel prose reads its style from the theme.** `RichTextLabel` does
+  **not** inherit `default_font`/`default_color`, so without a theme entry its
+  text renders near-white (unreadable on parchment). The theme now sets a base
+  `RichTextLabel` style (dark `INK_BODY` serif + italic face). All colours still
+  come from `Palette` via the theme builder — no hex in scripts or `.tscn`.
+
+## Consequences
+
+**Easier:**
+
+- The human arranges any screen directly in the Godot editor; layout persists in
+  the `.tscn`. Fine-tuning is drag-and-drop, not code-run-eyeball.
+- Screens preview with themed, representative content on open.
+- Scripts shrink to logic; less code, easier to review, focused files.
+- The look stays one system (theme assigned per scene root).
+
+**Caveats / harder:**
+
+- **Shader surfaces render only at runtime.** `DarkBay`/`VignetteOverlay` set
+  their `ShaderMaterial` in `_ready()` (M3-a accepted deviation), so their
+  texture appears only on an F6 run — the editor shows layout but a plain panel
+  behind it. Layout still previews fine.
+- Tests reference nodes by their authored `@onready` paths; renaming/moving a
+  node in the editor means updating the path (and any test that reads it).
+- The visual gate stays a **human F6 eyeball** — headless tests prove structure
+  (nodes mount, sizes are non-zero, bindings run) but not rendering.
+
+## Reference implementation
+
+M3-b shell scenes: `client/scenes/shell/{MainWindowShell,SystemDock,NarrationBook}.tscn`
+with their `client/scripts/ui/shell/*.gd` scripts. Practical how-to lives in
+[`client/docs/README.md`](../../client/docs/README.md) → "UI scene conventions."

docs/adr/README.md

@@ -4,7 +4,7 @@ One file per decision: `NNNN-short-title.md`. Record the context, the decision,
 
 ## Index
 
-- _none yet_
+- [0001 — UI screens are editor-authored scenes, not code-built](0001-editor-first-ui-scenes.md) (accepted)
 
 <!-- Template:
 ## NNNN — Title

docs/roadmap.md

@@ -55,9 +55,9 @@ M0–M2 built the **engine** (the contract, the client, the server loop, bounded
 Each screen is recreated as a Godot 4.7 Control-node scene against the mockups (§16); each `.dc.html`'s `Component` class is the behavior spec. Sequenced toward a playable vertical slice (shell → creation → combat → dialogue) first, then breadth.
 
 ### M3 — Visual foundation & shell ◀ *here*
-- ○ **Shared `Theme`** — palette tokens, the three font families, and reusable styleboxes (parchment card, dark panel, primary CTA, tab, item tile, tag/chip) from the mock README as a Godot `Theme` resource. Every screen pulls from it; build it first so the look is one system. *§2: n/a (presentation) · depends on nothing · goal: one consistent visual identity.*
-- ○ **Main Window shell (2a)** — the exploration HUD: isometric world-view slot + the permanent DM "narration book" (wired to the proven `/dm/narrate` loop + considering-state), the turn-order rail, minimap slot, the slide-in system dock (Inventory/Character/Quest/Map/Party toggles), and the bottom command bar (HP/MP/gold, consumables, End Turn). The frame everything else lives in. *§2: state (client owns the HUD, consumes DM text) · depends on the DM loop (M2) · goal: the game's main screen, on screen.*
-- ○ **Title screen** — new game / continue / load / settings; the entry point. *§2: n/a · depends on the Theme · goal: first impression, into the world.*
+- ✅ **Shared `Theme`** — palette tokens, the three font families, and reusable styleboxes (parchment card, dark panel, primary CTA, tab, item tile, tag/chip) from the mock README as a Godot `Theme` resource. Every screen pulls from it; build it first so the look is one system. Merged to `dev`. *§2: n/a (presentation) · depends on nothing · goal: one consistent visual identity.*
+- ✅ **Main Window shell (2a)** — the exploration HUD: isometric world-view slot + the permanent DM "narration book" (wired to the proven `/dm/narrate` loop + considering-state), the turn-order rail, minimap slot, the slide-in system dock (Inventory/Character/Quest/Map/Party/Spellbook toggles), and the bottom command bar (HP/MP/gold, consumables, End Turn). The frame everything else lives in. **Established the editor-first UI-scene convention** (ADR [0001](adr/0001-editor-first-ui-scenes.md); how-to in `client/docs/README.md`) and added Button-base `DockButton`/`ParchmentButton` + a base `RichTextLabel` prose style to the theme. *§2: state (client owns the HUD, consumes DM text) · depends on the DM loop (M2) · goal: the game's main screen, on screen.*
+- ○ **Title screen** — new game / continue / load / settings; the entry point. Author it editor-first (ADR 0001). *§2: n/a · depends on the Theme · goal: first impression, into the world.*
 
 ### M4 — Character creation
 - ○ **Character creation UI** — the mock's screen over our proven model: race + calling cards, six stats with **LCK hidden entirely** (§7), 3d6 floors, the **+3 additive-only spend-up** pool (§8, matches the `character-creation-stats` model), live origin blurb + nameplate. **Reconcile class names** here (§8 vs the mock's callings). Feeds new-game canon-log construction (already built). *§2: state · depends on the creation model (M0) + Theme · goal: build a character.*