feat(settings): lead with version + update, tail the rest of System

App Settings opened on a System section that mixed the two things worth seeing
immediately (what this install runs, whether a newer release is waiting) with
three groups nobody sets twice (CLAUDE.md template path, default working
directory, image watcher, Cloudflare tunnel).

Split in two. **Updates** is now the first section and carries only the current
version and the update action, so the modal opens on it and the second thing in
reach is Terminal & Input, where Local Echo lives. **System** keeps Paths,
Automation and Remote access and tails the document, last in the rail.

Also fixes the admin-ui load-order test, which broke on this branch: it located
the modules with a bare `indexOf('session-ui.js')`, and the modal markup now
cites those modules in comments well above the script tags, so it was comparing
a comment against a `<script src>`. It matches the script tag itself now.

CLAUDE.md

@@ -13,7 +13,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | Task        | Command                                                                                                                                                             |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Dev server  | `npm run dev` (or `npx tsx src/index.ts web`)                                                                                                                       |
-| Type check  | `tsc --noEmit`                                                                                                                                                      |
+| Type check  | `npm run typecheck` (= `tsc --noEmit`)                                                                                                                                                      |
 | Lint        | `npm run lint` (fix: `npm run lint:fix`)                                                                                                                            |
 | Format      | `npm run format` (check: `npm run format:check`)                                                                                                                    |
 | Single test | `npm test -- test/<file>.test.ts` (or `npx vitest run --config config/vitest.config.ts test/<file>.test.ts`) — ⚠ **never** run bare `npm test`, see Testing section |
@@ -159,15 +159,15 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Search**       | `src/search-service.ts`                                                                                | Pure in-memory core for `GET /api/search`                                                        |
 | **Attachments**  | `src/attachment-registry.ts`, `attachment-magic`, `generated-artifact-attachments`, `session-attachment-history`, `document-preview-cache`, `document-thumbnailer`, `document-conversion-limiter`, `config/attachment-guard` | See Key Patterns                                                                                 |
 | **Plan**         | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`) | `templates/` holds the CLAUDE.md scaffold generated into new cases                                |
-| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (20 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
-| **Frontend**     | `src/web/public/app.js` (~5K lines, core) + 28 modules + `sw.js`                                       | See Frontend section for the load order, which is authoritative                                  |
-| **Types**        | `src/types/index.ts` (barrel) → 20 domain files; also `src/types.ts` root re-export                    | See `@fileoverview` in index.ts                                                                  |
+| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (23 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
+| **Frontend**     | `src/web/public/app.js` (~5K lines, core) + 29 modules + `sw.js`                                       | See Frontend section for the load order, which is authoritative                                  |
+| **Types**        | `src/types/index.ts` (barrel) → 22 domain files; also `src/types.ts` root re-export                    | See `@fileoverview` in index.ts                                                                  |
 
 ★ = Large, central file (>50KB) — read its `@fileoverview` first. All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`.
 
 **Local packages**: `packages/xterm-zerolag-input/` (local echo overlay, single-source, see Gotchas). `packages/gesture-control/` (`codeman-gesture-control`, hand-tracking overlay source, built via `npm run build:gesture`).
 
-**Config**: `src/config/` — 17 files, no barrel (`index.ts`) exists; import from the specific file.
+**Config**: `src/config/` — 20 files, no barrel (`index.ts`) exists; import from the specific file.
 
 **Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).
 
@@ -200,7 +200,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Docker cases**: a case can point at a **container**, with any of the five CLI backends running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design)
 
-**External CLI modes (OpenCode, Codex, Gemini, Antigravity)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All four **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. ⚠️ **Codex sessions use PREDICTIVE WRITE-THROUGH echo, never the buffer overlay** (`_localEchoPolicy` in `_updateLocalEchoState`, terminal-ui.js): codex's composer reacts per keystroke ("/" pops a live-filtering picker, arrows edit server-side state, the composer grows as it wraps), so buffer-until-Enter starved it into issues #218/#219/#220/#222 and stays disabled (`_localEchoEnabled` remains false for codex). Instead, `PredictiveEchoAddon` (separate `vendor/xterm-predictive-echo.js` bundle) paints each keystroke at the predicted cell while the wire path stays BYTE-IDENTICAL: the onData hook (`_predictHookOnData`) is a plain statement with no `return`, so control always falls through into the untouched send path — pinned by vm and E2E byte-identity tests. Predictions reconcile against the parsed buffer and only while the cursor sits on the measured composer row (`isCodexComposerRow`, `/^› /`). Codex also **drops keystrokes that share a PTY read with a bracketed paste**, so flushed text and the paste sequence must go out as separate delayed writes (mirroring the Enter branch's delayed `\r`). Tests: `test/local-echo-codex-gating.test.ts`, `test/codex-predictive-echo.test.ts` (E2E vs real codex), `packages/xterm-zerolag-input/test/codex-replay.test.ts`. → [architecture-invariants#external-cli-modes-opencode-codex-gemini](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini)
+**External CLI modes (OpenCode, Codex, Gemini, Antigravity)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All four **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. ⚠️ **Codex sessions use PREDICTIVE WRITE-THROUGH echo, never the buffer overlay** (`_localEchoPolicy` in `_updateLocalEchoState`, terminal-ui.js): codex's composer reacts per keystroke ("/" pops a live-filtering picker, arrows edit server-side state, the composer grows as it wraps), so buffer-until-Enter starved it into issues #218/#219/#220/#222 and stays disabled (`_localEchoEnabled` remains false for codex). Instead, `PredictiveEchoAddon` (separate `vendor/xterm-predictive-echo.js` bundle) paints each keystroke at the predicted cell while the wire path stays BYTE-IDENTICAL: the onData hook (`_predictHookOnData`) is a plain statement with no `return`, so control always falls through into the untouched send path — pinned by vm and E2E byte-identity tests. Predictions reconcile against the parsed buffer and only while the cursor sits on the measured composer row (`isCodexComposerRow`, `/^› /`). Codex also **drops keystrokes that share a PTY read with a bracketed paste**, so flushed text and the paste sequence must go out as separate delayed writes (mirroring the Enter branch's delayed `\r`). Tests: `test/local-echo-codex-gating.test.ts`, `test/codex-predictive-echo.test.ts` (E2E vs real codex), `packages/xterm-zerolag-input/test/codex-replay.test.ts`. → [architecture-invariants#external-cli-modes-opencode-codex-gemini](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity)
 
 **Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. `_ensureCreatedSessionVisible()` runs before `selectSession()`, and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first ordering both produce exactly one rendered tab. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization)
 
@@ -222,7 +222,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Detached start + service install** (issue #231): `codeman web -d` relaunches the SAME entry script with `detached:true` (setsid), so there is no controlling terminal and no shell job entry. ⚠️ `nohup` is NOT what makes this work: Node re-arms SIGHUP to its default disposition even when it inherits "ignore", and `cli.ts` handles SIGHUP with a graceful shutdown, so a delivered HUP still stops the server. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile check + `/api/status` probe): a second instance on the shared tmux socket attaches PTYs to the first one's live sessions. ⚠️ Neither may report success it has not observed — the parent polls `/api/status` until the child answers or dies, since `launchctl load` and a clean spawn are both silent about a server that starts and immediately exits. `--stop` verifies the pid still LOOKS like a Codeman server (`ps -o command=`) before signalling, because pids get recycled. Unit/label names live in `config/service-names.ts` so install.sh, `detectSupervisor()` and `service install` cannot drift into supervising two copies; they are instance-scoped, and identical to the historical names for the default instance. `service install` bakes the installing shell's PATH into the unit (launchd gives a job `/usr/bin:/bin:/usr/sbin:/sbin`, which finds neither a Homebrew/nvm `node` nor `tmux`/`claude`) and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install)
 
-**Self-update** (App Settings → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. → [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
+**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. → [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
 
 **Attachments** (live external document references; all wiring in `file-routes.ts`): a **registry** maps a stable `attachmentId` to a realpath-resolved, extension-allowlisted absolute path, so browser requests never carry arbitrary absolute paths. ⚠️ The **magic-link scanner** (`codeman://attach?...` in terminal output) is **prompt-injectable**, so its scan path is force-confined to the session workspace; a hostile prompt could otherwise exfiltrate arbitrary host files over SSE. The security gate is an extension **allowlist**, not a blocklist. `document-conversion-limiter.ts` caps converter spawns globally: without it, N large docs detected at once fork N multi-minute processes, which is a resource-exhaustion vector. → [architecture-invariants#attachments](docs/architecture-invariants.md#attachments)
 
@@ -264,7 +264,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Per-device vs synced settings**: the `displayKeys` set in settings-ui.js is a **client-side merge policy**, not a wire filter. A display key seeds from the server only when localStorage has no value for it, which is what prevents one device overwriting another; `showPlanUsageLimits` is additionally `delete`d from the incoming payload outright. Separately, `SettingsUpdateSchema` is `.strict()` and simply **does not declare** `skin`, `showFileViewerButton`, `showCronButton`, `webglRendererEnabled`, `localEchoEnabled`, `cjkInputEnabled`, or `extendedKeyboardBar`, so sending one of those is a validation error. The rest (`showResponseViewer`, `showPlanUsageLimits`, `language`, and most `show*` keys) ARE in the schema and do persist server-side; they are per-device by client policy only. ⚠️ Adding a new per-device setting means deciding **both** questions: membership in `displayKeys`, and presence in the schema.
 
-**App Settings modal** (`#appSettingsModal`): a left rail that is a **table of contents over ONE scrolling document**, not a tab switcher. Every section stays mounted (`.set-section`, ids `settings-terminal|appearance|layout|models|clis|notifications|voice|shortcuts|system`), the rail follows the scroll, and `switchSettingsTab(id)` keeps its historical name but SCROLLS instead of hiding. Phones swap the rail for the sticky `#appSettingsJump` pill (compact layout at ≤860px in mobile.css). ⚠️ **The load/save contract is `getElementById` by id**: `openAppSettings()`/`saveAppSettings()` read every control by a fixed id, so moving a control between sections is free but renaming or dropping one silently stops it loading or saving. `test/app-settings-structure.test.ts` is the static guard. ⚠️ Model cards (`#appSettingsModelCards`) and the effort segment are **views over hidden `<select>`s** that remain the source of truth; the cards hold the BASE model and the "1M context window" switch composes `base + [1m]` back into `claudeModel`, which is what retires the old "takes precedence over the toggle below" trap. ⚠️ `.modal-tabs`/`.modal-tab-btn`/`.modal-tab-content` are still used by `#sessionOptionsModal` and `#createCaseModal`; the settings rail uses its own `set-*` classes and must not restyle them. ⚠️ `admin-ui.js` injects the multi-user Users entry into `.set-rail-items` + `.set-doc`, so those hooks must survive any restructure.
+**Settings surface** (`#appSettingsModal` + `#sessionOptionsModal` + `#createCaseModal`): the `set-*` language (left rail, groups of rows, control pinned right) is shared by all three modals through ONE `:is(#appSettingsModal, #sessionOptionsModal, #createCaseModal)` scope in styles.css: an `:is()` list takes its most specific argument's specificity, so every rule keeps the id weight it had and nothing downstream shifts. **App Settings** is a rail that is a **table of contents over ONE scrolling document**, not a tab switcher: every section stays mounted (`.set-section`, ids `settings-updates|terminal|layout|appearance|models|clis|notifications|voice|shortcuts|system`, in that order, the version and the updater leading and the rest of the system settings tailing), and `switchSettingsTab(id)` keeps its historical name but SCROLLS instead of hiding. **Session Options** and **Add Case** use the same surface with a rail that really SWITCHES (`switchOptionsTab` / `switchCaseModalTab` show one `.set-section` and `.hidden` the rest, since Summary owns its own scroller, Respawn is long, and Add Case is six independent forms). ⚠️ They also take a deliberate **size-up** that App Settings does not (900px shell, 236px rail, `height:auto` between `min(560px,80vh)` and 88vh, vs App Settings' tight 760×620): they are short task panels, not a document you scan, and at scanning density they read as a few fields marooned in an empty frame. Those per-modal blocks are the design, not drift. Phones (≤860px) give App Settings the sticky `#appSettingsJump` pill and give the other two a horizontal rail strip, which neither has a pill for. ⚠️ The Session Options rail entry labelled **Session** still keys off `context` (`data-tab="context"`, `#context-tab`, `switchOptionsTab('context')`), the rename is label-only. Add Case keeps its legacy `.form-row` markup (six panels of it, every id read back by session-ui.js) and is mapped onto the look by an adapter block scoped to `#createCaseModal .set-doc`. Do not restructure those forms just to reach the row classes. ⚠️ That adapter's `summary { display:flex }` **kills the native disclosure triangle**, so every `<details>` there needs the explicit `.set-adv-chev` and both marker suppressions (`list-style` + `::-webkit-details-marker`); without it five collapsed blocks render as plain headings nobody clicks. ⚠️ **The load/save contract is `getElementById` by id**: `openAppSettings()`/`saveAppSettings()`/`openSessionOptions()` read every control by a fixed id, so moving a control between sections is free but renaming or dropping one silently stops it loading or saving. Static guards: `test/app-settings-structure.test.ts` + `test/session-options-structure.test.ts` (rail↔section pairing, one-visible-section, the `data-claude-only` entries external CLIs drop). ⚠️ Model cards (`#appSettingsModelCards`) and the effort segment are **views over hidden `<select>`s** that remain the source of truth; the cards hold the BASE model and the "1M context window" switch composes `base + [1m]` back into `claudeModel`, which is what retires the old "takes precedence over the toggle below" trap. ⚠️ `.modal-tabs`/`.modal-tab-btn`/`.modal-tab-content` are RETIRED: no modal uses them and their CSS is deleted, and a reappearance means a modal drifted off the shared surface. ⚠️ The **Header & Panels live preview** is a scale model rebuilt from the chips (`_syncLayoutPreview`); it owns NO icons, it CLONES `.set-chip-ico` out of the chip, so each icon has exactly one copy in index.html. A chip joins it via `data-preview` (slot) + `data-preview-order`, or `data-preview-text` for readouts that are not buttons. Its frame is painted from skin tokens only (hardcoded black alphas turned it into a grey slab on the light skins) and is `data-i18n-skip`. ⚠️ In Session Options → Respawn, auto-resume is a `.set-callout` whose `<label>` **wraps its own switch with no `for=`** (nesting associates them; the label+`for` pair has historically double-fired), and the cycle steps are real checkboxes (`.set-checks`), not chips. ⚠️ `admin-ui.js` injects the multi-user Users entry into `.set-rail-items` + `.set-doc`, so those hooks must survive any restructure. → [architecture-invariants#settings-surface-app-settings-session-options-add-case](docs/architecture-invariants.md#settings-surface-app-settings-session-options-add-case)
 
 **Header button visibility**: most header controls are opt-in and hidden by a marker class (`btn-multimonitor--hidden`, `btn-response-viewer-header--hidden`, `btn-file-viewer--hidden`, `btn-cron--hidden`) that `applyHeaderVisibilitySettings()` (settings-ui.js) toggles after settings load; the multi-monitor button is instead stripped at render by `renderIndexHtml`. ⚠️ Hiding must go through the marker class: the base rules are `display:inline-flex !important`, so an inline style cannot override them. Current desktop default is WS/CPU/MEM + File Viewer + gear, with the token chip and lifecycle-log button OFF. ⚠️ New header controls must not leak onto phones; `test/mobile-header-buttons-policy.test.ts` is the static guard. → [architecture-invariants#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron](docs/architecture-invariants.md#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron)
 
@@ -314,7 +314,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### SSE Event Registry
 
-154 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync** — they are currently exactly in sync, and the backend file's `@fileoverview` carries the per-category breakdown.
+154 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync**, and `test/sse-registry-parity.test.ts` is the guard that pins it (currently exactly in sync, 154 = 154, no drift either direction). The backend file's `@fileoverview` carries the per-category breakdown.
 
 ### API Routes
 

README.md

@@ -254,7 +254,7 @@ Click **+ New Session** (or **Quick Start**). A session is one AI CLI running in
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | **Working directory / case** | The folder the agent operates in. A "case" is just a named working dir Codeman remembers. **Add Case** creates one from scratch, links an existing folder, or clones a GitHub repo straight into one (**Clone Repo**). |
 | **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Antigravity`, `Gemini`, or `Terminal` (plain shell).                       |
-| **Model**                    | Per-session model (App Settings → Claude Model). A soft default — `/model` still works in-session.                  |
+| **Model**                    | Per-session model (App Settings → Models → New Claude sessions). A soft default — `/model` still works in-session.                  |
 | **Effort / Ultracode**       | Reasoning effort (`low`–`max`) or `ultracode` for dynamic multi-agent workflows. Switchable anytime with `/effort`. |
 
 Hit start — Codeman spawns the CLI via a real PTY and streams it to your browser over SSE.
@@ -278,7 +278,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
 | **Respawn**      | Long unattended runs — auto-restarts the CLI on idle/limit, with adaptive timing. Presets: `solo-work`, `overnight-autonomous`, … | Respawn tab                                                         |
 | **Orchestrator** | Turn one goal into a phased plan and drive it to completion across agents.                                                        | Orchestrator panel                                                  |
-| **Cron**         | Saved, named jobs on a schedule (`once`/`interval`/`daily`/`weekly`) that spawn a session and send a prompt when due.             | ⏰ Cron button _(opt-in: App Settings → Display → Header Displays)_ |
+| **Cron**         | Saved, named jobs on a schedule (`once`/`interval`/`daily`/`weekly`) that spawn a session and send a prompt when due.             | ⏰ Cron button _(opt-in: App Settings → Header & Panels → Scheduling)_ |
 | **Auto-resume**  | Automatically continue after a subscription rate-limit resets.                                                                    | Respawn tab (top)                                                   |
 
 ### 6. Reach it from anywhere
@@ -291,7 +291,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 
 - **App Settings** — model, effort, permission startup mode, theme/skin, notifications, display toggles, per-CLI options, a synced custom display name, and per-device English/Simplified Chinese UI language.
 - **Run it in the background** — `codeman web -d` detaches from your shell (`--status`, `--stop`); `codeman service install` makes it a systemd user unit / macOS LaunchAgent that survives reboots. Both verify the server actually answers before reporting success, and both refuse to start a second server on one data dir. See [Keep it running in the background](#quick-start---installation).
-- **Self-update** — git-clone installs update in place from **Settings → Updates**.
+- **Self-update** — git-clone installs update in place from **App Settings → System → Updates**.
 - **Deploy your own changes** — see [Development](#development).
 
 > ⚠️ **Safety:** if you're working _inside_ a Codeman-managed session (`echo $CODEMAN_MUX` → `1`), never run `tmux kill-session` / `pkill claude` directly — use the web UI or `./scripts/tmux-manager.sh`.
@@ -427,7 +427,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 ## More Features
 
 - **Background daemon & service install** — `codeman web -d` runs the server detached with a pidfile, `~/.codeman/web.log`, and verified startup (it polls the server until it answers, so a port clash never reads as success); `codeman service install` writes a systemd user unit (Linux) or LaunchAgent (macOS) with your shell's PATH baked in, so an nvm or Homebrew `node`, `tmux` and `claude` are actually found. Secrets are never written into unit files
-- **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
+- **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → System → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
 - **Clone a GitHub repo as a case** — paste a repository URL into **Add Case → Clone Repo** and Codeman clones it into `~/codeman-cases/<name>` and registers it as a normal case, ready to run an agent in. It preflights the URL while you type (tells you whether it can be cloned anonymously and offers the repo's real branches and tags for the optional branch/tag field), fills the case name in from the URL, and lets you pick which CLI the Run button should use. Public repositories over `https://`; Codeman never collects or stores credentials
 - **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, or **Gemini** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
 - **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)
@@ -435,9 +435,9 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 - **Effort & Ultracode** — set a per-session default effort (`low`–`max`) or enable **ultracode** (dynamic multi-agent workflows). Soft defaults only — switchable anytime with `/effort` in-session. Extended-thinking budget is configurable too
 - **Voice input** — dictate prompts with Deepgram Nova-3 (Web Speech API fallback): toggle recording, auto-silence stop, live level meter (`Ctrl+Shift+V`)
 - **Image input** — paste or drag-and-drop images straight into a session
-- **Gesture control** _(opt-in)_ — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Display
+- **Gesture control** _(opt-in)_ — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Terminal & Input
 - **Multi-monitor span** _(macOS)_ — one click opens a browser window maximized across all displays, so floating agent/gesture panels can cross the physical seam
-- **File Viewer button** _(opt-in)_ — a header button that toggles the built-in file browser panel with one tap; enable under App Settings → Display → Header Displays
+- **File Viewer button** _(opt-in)_ — a header button that toggles the built-in file browser panel with one tap; enable under App Settings → Header & Panels → Header buttons
 - **CJK / IME input** — full composition support for Chinese / Japanese / Korean
 - **OS notifications & hostname-aware titles** — desktop alerts and tab titles are prefixed `codeman:<host>` so multi-host setups stay unambiguous
 
@@ -521,7 +521,7 @@ The script auto-installs a systemd user service on first run. The tunnel URL is
 systemctl --user enable codeman-tunnel
 loginctl enable-linger $USER
 
-# Or via the Codeman web UI: Settings → Tunnel → Toggle On
+# Or via the Codeman web UI: App Settings → System → Remote access → Cloudflare Tunnel
 ```
 
 </details>
@@ -623,7 +623,7 @@ By default Codeman launches sessions with `--dangerously-skip-permissions`, so t
 - **Loopback by default** — the server binary binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box (the guided installer asks about network access and configures the binding + password for you). Binding a non-loopback host without `CODEMAN_PASSWORD` _starts but prints a loud warning_ with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
 - **Optional auth, real sessions** — HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Success issues an opaque 256-bit `codeman_session` cookie (`randomBytes(32)`) — validated server-side, not client-signed, so it can't be forged offline (24h TTL, auto-extend, device-context audit log)
 - **Per-IP rate limiting** — 10 failed attempts → `429` with `Retry-After` (15-min decay). A valid cookie or correct password recovers _immediately_ even while an attacker hammers the same IP — important because all tunnel traffic shares one loopback IP. QR auth has its own separate limiter
-- **Configurable permission mode** - `--dangerously-skip-permissions` is only the default. **App Settings → Claude CLI → Startup Mode** can switch new sessions to Anthropic's classifier-guarded `auto` mode (low-prompt, needs Claude Code 2.1.207+), `normal` prompting, or an explicit allowed-tools list. In multi-user mode, non-granted users are forced to `auto`, and shell sessions / skip-permissions require an explicit per-user grant
+- **Configurable permission mode** - `--dangerously-skip-permissions` is only the default. **App Settings → Agents & CLIs → Claude → Startup Mode** can switch new sessions to Anthropic's classifier-guarded `auto` mode (low-prompt, needs Claude Code 2.1.207+), `normal` prompting, or an explicit allowed-tools list. In multi-user mode, non-granted users are forced to `auto`, and shell sessions / skip-permissions require an explicit per-user grant
 
 ### Always-on browser hardening (v0.9.5)
 
@@ -696,7 +696,7 @@ For AI agents and automation that control Codeman without a browser: an agent th
 >
 > - `npx skills add Ark0N/Codeman --skill codeman -g`: global, works for any skills-aware agent
 > - `codeman skill install` (global) or `codeman skill install --case <name>`: for npm installs that never cloned the repo; `codeman skill uninstall` reverses it
-> - **App Settings → Agent Skill** (`agentSkillEnabled`, default off): Codeman then injects the skill into each case on Claude session create; a user-authored `skills/codeman` in the case is never overwritten
+> - **App Settings → Agents & CLIs → Claude → Agent Skill** (`agentSkillEnabled`, default off): Codeman then injects the skill into each case on Claude session create; a user-authored `skills/codeman` in the case is never overwritten
 >
 > A global install (`codeman skill install`, or `npx skills add`) is picked up by **every new Claude Code session on the machine**, inside Codeman or not. The skill self-gates: outside a Codeman session (`CODEMAN_MUX` unset) it refuses to act, so a global install costs an idle session nothing.
 >

docs/browser-testing-guide.md

@@ -300,6 +300,11 @@ For reference when writing browser tests:
 .xterm                   // Terminal container
 #helpModal               // Help modal
 #appSettingsModal        // Settings modal
+#sessionOptionsModal     // Session Options (same set-* surface)
+#createCaseModal         // Add Case (same set-* surface)
+.set-rail-item           // Rail entry: scrolls in App Settings, switches in the other two
+.set-section             // A settings section (`.hidden` on the inactive ones outside App Settings)
+.set-row                 // One setting: label + description left, control right
 .modal-content           // Modal content
 .modal-close             // Modal close button
 .header-brand .logo      // Logo text

docs/readmymind.md

@@ -11,7 +11,7 @@ Codeman's per-case memory of what you are trying to accomplish, and the 🧠 but
 
 ## Turning it on
 
-App Settings → Panels → **Read My Mind** (synced setting `readMyMindEnabled`, default **OFF**). It gates everything: capture, the header button, and nothing shows anywhere while it is off. The API equivalent:
+App Settings → Header & Panels → Cross-session features → **Read My Mind** (synced setting `readMyMindEnabled`, default **OFF**). It gates everything: capture, the header button, and nothing shows anywhere while it is off. The API equivalent:
 
 ```bash
 curl -sk -X PUT https://localhost:3000/api/settings \
@@ -93,7 +93,7 @@ A steer-note input on Rethink ("no, I meant the mobile bug"; the API already acc
 
 | Symptom | Cause / fix |
 | ------- | ----------- |
-| No 🧠 button in the header | `readMyMindEnabled` is OFF (App Settings → Panels), you are on a phone (there it is a key on the keyboard accessory bar instead, visible while typing), or the active session is not claude-mode |
+| No 🧠 button in the header | `readMyMindEnabled` is OFF (App Settings → Header & Panels → Cross-session features), you are on a phone (there it is a key on the keyboard accessory bar instead, visible while typing), or the active session is not claude-mode |
 | Prediction feels generic | The profile is thin: record goals (PUT or ask your agent to), and let capture accumulate a few real prompts first |
 | "A prediction is already running" (409) | One per session at a time; wait for the current one (up to 90 s) |
 | Prediction fails (502) | The model returned no usable JSON, or the CLI could not start; retry. Check `readMyMindModel` if you overrode it |

src/web/public/home-sessions.js

@@ -393,10 +393,14 @@ Object.assign(CodemanApp.prototype, {
     // that collide with state strings on other surfaces.
     pill.setAttribute('data-i18n-skip', '');
     pill.textContent = row.pill;
-    item.appendChild(pill);
 
-    // Wraps onto its own line (the row is flex-wrap) so it gets the full width.
-    item.appendChild(this._buildHomeSessionsMeta(row));
+    // The stamps line wraps onto its own full-width line (the row is flex-wrap)
+    // and the pill rides along at its right end, rather than sitting beside the
+    // name: that hands the whole width of the rail to the session name, which is
+    // what stops it ellipsizing.
+    const meta = this._buildHomeSessionsMeta(row);
+    meta.appendChild(pill);
+    item.appendChild(meta);
 
     return item;
   },
@@ -439,7 +443,14 @@ Object.assign(CodemanApp.prototype, {
     pill.className = 'home-sessions-pill home-sessions-pill--web';
     pill.setAttribute('data-i18n-skip', '');
     pill.textContent = 'web';
-    item.appendChild(pill);
+
+    // Same bottom line as a session row (minus the stamps, a dashboard has
+    // none), so the pill sits in the same place on every row in the rail.
+    const foot = document.createElement('span');
+    foot.className = 'home-sessions-row-meta';
+    foot.setAttribute('data-i18n-skip', '');
+    foot.appendChild(pill);
+    item.appendChild(foot);
 
     return item;
   },

src/web/public/mobile.css

@@ -223,24 +223,6 @@ html.mobile-init .file-browser-panel {
     min-height: 56px;
   }
 
-  .modal-tabs {
-    overflow-x: auto;
-    -webkit-overflow-scrolling: touch;
-    scrollbar-width: none;
-    flex-wrap: nowrap;
-  }
-
-  .modal-tabs::-webkit-scrollbar {
-    display: none;
-  }
-
-  .modal-tab-btn {
-    padding: 0.4rem 0.75rem;
-    font-size: 0.7rem;
-    white-space: nowrap;
-    flex-shrink: 0;
-  }
-
   /* Settings grid stays 2-col on tablet but tighter */
   .settings-grid {
     gap: 0.4rem 0.75rem;
@@ -2077,45 +2059,8 @@ html.mobile-init .file-browser-panel {
 
   /* ---- Settings Modal: Mobile Optimizations ---- */
 
-  /* Scrollable tabs row - prevent overflow on small screens */
-  .modal-tabs {
-    overflow-x: auto;
-    -webkit-overflow-scrolling: touch;
-    scrollbar-width: none;
-    gap: 0.25rem;
-    padding: 0 0.75rem 0.5rem 0.75rem;
-    flex-wrap: nowrap;
-  }
-
-  .modal-tabs::-webkit-scrollbar {
-    display: none;
-  }
-
-  .modal-tab-btn {
-    padding: 0.35rem 0.6rem;
-    font-size: 0.65rem;
-    white-space: nowrap;
-    flex-shrink: 0;
-  }
-
   /* ---- Case Modal: Mobile Touch Optimizations ---- */
 
-  /* Larger tab buttons for case modal - easy to tap */
-  #createCaseModal .modal-tabs {
-    gap: 0.5rem;
-    padding: 0.5rem 1rem 0.75rem;
-  }
-
-  #createCaseModal .modal-tab-btn {
-    flex: 1;
-    min-height: 44px;
-    padding: 0.6rem 1rem;
-    font-size: 0.8rem;
-    font-weight: 500;
-    border-radius: 8px;
-    justify-content: center;
-    text-align: center;
-  }
 
   /* Touch-friendly form inputs in case modal */
   #createCaseModal .form-row {
@@ -3170,21 +3115,21 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
    stack of separate cards: at 390px the per-card borders were most of the pixels.
    ============================================================================ */
 @media (max-width: 860px) {
-  #appSettingsModal .modal-content.modal-lg {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .modal-content.modal-lg {
     width: 100%;
     max-width: 100%;
     height: 100%;
     max-height: 100%;
   }
 
-  #appSettingsModal .set-body {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-body {
     display: flex;
     flex-direction: column;
     min-height: 0;
   }
 
   /* Rail keeps only its search field, laid out as a bar */
-  #appSettingsModal .set-rail {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-rail {
     flex-direction: row;
     align-items: center;
     border-right: 0;
@@ -3195,37 +3140,37 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     flex-shrink: 0;
   }
 
-  #appSettingsModal .set-rail-items,
-  #appSettingsModal .set-rail-foot {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-rail-items,
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-rail-foot {
     display: none;
   }
 
-  #appSettingsModal .set-search {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-search {
     margin: 0;
     flex: 1;
   }
 
-  #appSettingsModal .set-search input {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-search input {
     padding: 9px 10px 9px 30px;
     border-radius: 10px;
   }
 
   /* Save moves into the header; the bottom action bar would cost 60px */
-  #appSettingsModal .set-head-save {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-head-save {
     display: inline-flex;
   }
 
-  #appSettingsModal .set-foot {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-foot {
     display: none;
   }
 
-  #appSettingsModal .set-doc {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-doc {
     padding: 0 14px 34px;
     flex: 1;
   }
 
   /* ── jump control ──────────────────────────────────────────────────── */
-  #appSettingsModal .set-jump {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump {
     display: flex;
     position: sticky;
     top: 0;
@@ -3246,30 +3191,30 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     cursor: pointer;
   }
 
-  #appSettingsModal .set-jump-ico {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-ico {
     color: var(--accent);
     flex-shrink: 0;
   }
 
-  #appSettingsModal .set-jump-label {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-label {
     font-weight: 580;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
 
-  #appSettingsModal .set-jump-chev {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-chev {
     margin-left: auto;
     color: var(--text-muted);
     flex-shrink: 0;
     transition: transform 0.18s;
   }
 
-  #appSettingsModal .set-jump[aria-expanded='true'] .set-jump-chev {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump[aria-expanded='true'] .set-jump-chev {
     transform: rotate(180deg);
   }
 
-  #appSettingsModal .set-jump-veil {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-veil {
     display: none;
     position: fixed;
     inset: 0;
@@ -3277,7 +3222,7 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     background: rgba(4, 8, 13, 0.62);
   }
 
-  #appSettingsModal .set-jump-menu {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-menu {
     display: none;
     position: absolute;
     left: 14px;
@@ -3299,7 +3244,7 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     display: block;
   }
 
-  #appSettingsModal .set-jump-row {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-row {
     display: flex;
     align-items: center;
     gap: 11px;
@@ -3314,43 +3259,43 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     text-align: left;
   }
 
-  #appSettingsModal .set-jump-row svg {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-row svg {
     color: var(--text-muted);
     flex-shrink: 0;
   }
 
-  #appSettingsModal .set-jump-row .set-jump-count {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-row .set-jump-count {
     margin-left: auto;
     font-size: 0.62rem;
     color: var(--text-muted);
   }
 
-  #appSettingsModal .set-jump-row.active {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-row.active {
     background: rgba(var(--accent-rgb), 0.14);
     color: var(--text);
     font-weight: 570;
   }
 
-  #appSettingsModal .set-jump-row.active svg {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-jump-row.active svg {
     color: var(--accent);
   }
 
   /* ── sections step down: the jump pill already names the current one ── */
-  #appSettingsModal .set-section {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-section {
     padding-top: 0;
   }
 
-  #appSettingsModal .set-section + .set-section {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-section + .set-section {
     border-top: 0;
     margin-top: 0;
   }
 
-  #appSettingsModal .set-section-head {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-section-head {
     gap: 7px;
     margin: 18px 0 2px;
   }
 
-  #appSettingsModal .set-section-head svg {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-section-head svg {
     padding: 0;
     border: 0;
     background: none;
@@ -3359,7 +3304,7 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     height: 12px;
   }
 
-  #appSettingsModal .set-section-head h2 {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-section-head h2 {
     font-size: 0.6rem;
     font-weight: 640;
     letter-spacing: 0.1em;
@@ -3367,36 +3312,45 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     color: var(--text-muted);
   }
 
-  #appSettingsModal .set-section-head::after {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-section-head::after {
     content: '';
     flex: 1;
     height: 1px;
     background: linear-gradient(90deg, var(--border), transparent);
   }
 
-  #appSettingsModal .set-section-blurb {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-section-blurb {
     display: none;
   }
 
+  /* ── live layout preview ───────────────────────────────────────────── */
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-preview {
+    margin-bottom: 12px;
+  }
+
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-preview-stage {
+    min-height: 62px;
+  }
+
   /* ── inset grouped list ────────────────────────────────────────────── */
-  #appSettingsModal .set-group {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group {
     margin-top: 14px;
   }
 
-  #appSettingsModal .set-group + .set-group {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group + .set-group {
     margin-top: 16px;
   }
 
-  #appSettingsModal .set-group-head {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-head {
     margin-bottom: 7px;
     padding: 0 3px;
   }
 
-  #appSettingsModal .set-group-hint {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-hint {
     padding: 0 3px;
   }
 
-  #appSettingsModal .set-group-body {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body {
     gap: 0;
     background: rgba(255, 255, 255, 0.035);
     border: 1px solid rgba(255, 255, 255, 0.06);
@@ -3404,7 +3358,7 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     overflow: hidden;
   }
 
-  #appSettingsModal .set-group-body > .set-row {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body > .set-row {
     background: transparent;
     border: 0;
     border-radius: 0;
@@ -3412,104 +3366,147 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
     gap: 12px;
   }
 
-  #appSettingsModal .set-group-body > .set-row + .set-row {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body > .set-row + .set-row {
     border-top: 1px solid rgba(255, 255, 255, 0.055);
   }
 
-  #appSettingsModal .set-group-body > .set-chips,
-  #appSettingsModal .set-group-body > .set-modelgrid,
-  #appSettingsModal .set-group-body > .set-minigrid,
-  #appSettingsModal .set-group-body > #appSettingsShortcutsList {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body > .set-chips,
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body > .set-modelgrid,
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body > .set-minigrid,
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body > #appSettingsShortcutsList {
     padding: 12px;
   }
 
-  #appSettingsModal .set-group-body > .event-type-grid {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-group-body > .event-type-grid {
     padding: 12px;
     margin: 0;
   }
 
-  #appSettingsModal .set-row-label {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row-label {
     font-size: 0.84rem;
   }
 
-  #appSettingsModal .set-row-desc {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row-desc {
     font-size: 0.69rem;
     max-width: none;
   }
 
   /* Fields go full width under their label instead of fighting for the row */
-  #appSettingsModal .set-row.has-field {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row.has-field {
     flex-direction: column;
     align-items: stretch;
     gap: 9px;
   }
 
-  #appSettingsModal .set-row.has-field .set-select,
-  #appSettingsModal .set-row.has-field .set-input {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row.has-field .set-select,
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row.has-field .set-input {
     width: 100%;
     min-width: 0;
     max-width: none;
     box-sizing: border-box;
   }
 
-  #appSettingsModal .set-row-actions-wide {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row-actions-wide {
     width: 100%;
   }
 
-  #appSettingsModal .set-row-actions-wide .set-input {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row-actions-wide .set-input {
     flex: 1;
     min-width: 0;
   }
 
-  #appSettingsModal .set-num {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-num {
     width: 76px;
   }
 
   /* Bigger touch targets for the toggles and chips */
-  #appSettingsModal .switch-sm {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .switch-sm {
     width: 40px;
     height: 24px;
   }
 
-  #appSettingsModal .switch-sm .slider:before {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .switch-sm .slider:before {
     height: 18px;
     width: 18px;
   }
 
-  #appSettingsModal .switch-sm input:checked + .slider:before {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .switch-sm input:checked + .slider:before {
     transform: translateX(16px);
   }
 
-  #appSettingsModal .set-chip {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-chip {
     font-size: 0.78rem;
     padding: 9px 14px;
   }
 
-  #appSettingsModal .set-modelgrid {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-modelgrid {
     grid-template-columns: repeat(2, minmax(0, 1fr));
     gap: 8px;
   }
 
-  #appSettingsModal .set-minigrid {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-minigrid {
     grid-template-columns: 1fr;
   }
 
-  #appSettingsModal .set-mini .set-select {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-mini .set-select {
     width: 148px;
   }
 
   /* One scrollable line beats a ragged two-row wrap for 7 effort levels */
-  #appSettingsModal .set-segment {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-segment {
     overflow-x: auto;
     scrollbar-width: none;
   }
 
-  #appSettingsModal .set-segment::-webkit-scrollbar {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-segment::-webkit-scrollbar {
     display: none;
   }
 
-  #appSettingsModal .set-segment button {
+  :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-segment button {
     flex: 0 0 auto;
     padding: 8px 12px;
   }
 }
+
+/* ============================================================================
+   Session Options, compact layout (<= 860px)
+
+   App Settings collapses its rail and hands navigation to the sticky
+   #appSettingsJump pill. Session Options has no such pill (and no search), so
+   its rail stays put and becomes a horizontal, scrollable strip — which is
+   what its tab bar was before the two modals started sharing a surface.
+   ============================================================================ */
+@media (max-width: 860px) {
+  :is(#sessionOptionsModal, #createCaseModal) .set-rail {
+    padding: 8px 10px;
+  }
+
+  :is(#sessionOptionsModal, #createCaseModal) .set-rail-items {
+    display: flex;
+    flex-direction: row;
+    flex: 1;
+    min-width: 0;
+    gap: 4px;
+    overflow-x: auto;
+    scrollbar-width: none;
+  }
+
+  :is(#sessionOptionsModal, #createCaseModal) .set-rail-items::-webkit-scrollbar {
+    display: none;
+  }
+
+  :is(#sessionOptionsModal, #createCaseModal) .set-rail-item {
+    white-space: nowrap;
+    padding: 8px 12px;
+  }
+
+  /* The active marker is a left bar in the vertical rail; horizontally that
+     reads as a stray tick, so the strip uses a filled pill instead. */
+  :is(#sessionOptionsModal, #createCaseModal) .set-rail-item.active::before {
+    display: none;
+  }
+
+  :is(#sessionOptionsModal, #createCaseModal) .set-rail-item.active {
+    background: rgba(var(--accent-rgb), 0.13);
+  }
+}

src/web/public/session-ui.js

@@ -1278,8 +1278,8 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('presetDescriptionHint').textContent = '';
 
     // Hide Ralph/Todo tab and Respawn tab for external CLI sessions (not supported)
-    const ralphTabBtn = document.querySelector('#sessionOptionsModal .modal-tab-btn[data-tab="ralph"]');
-    const respawnTabBtn = document.querySelector('#sessionOptionsModal .modal-tab-btn[data-tab="respawn"]');
+    const ralphTabBtn = document.querySelector('#sessionOptionsModal .set-rail-item[data-tab="ralph"]');
+    const respawnTabBtn = document.querySelector('#sessionOptionsModal .set-rail-item[data-tab="respawn"]');
     if (isExternalCli) {
       if (ralphTabBtn) ralphTabBtn.style.display = 'none';
       if (respawnTabBtn) respawnTabBtn.style.display = 'none';
@@ -1303,6 +1303,18 @@ Object.assign(CodemanApp.prototype, {
     }
 
     const modal = document.getElementById('sessionOptionsModal');
+
+    // Chips mirror their checkbox onto the label, the same way App Settings does
+    // (settings-ui.js: _syncSettingsChips). Registered once per page, never per
+    // open, or a long-lived tab accumulates one listener per visit.
+    if (modal.dataset.chipsReady !== '1') {
+      modal.dataset.chipsReady = '1';
+      modal.addEventListener('change', e => {
+        if (e.target?.closest?.('.set-chip')) this._syncSettingsChips();
+      });
+    }
+    this._syncSettingsChips();
+
     modal.classList.add('active');
 
     // Activate focus trap
@@ -1500,18 +1512,32 @@ Object.assign(CodemanApp.prototype, {
   // Session Options Modal Tabs
   // ═══════════════════════════════════════════════════════════════
 
+  /**
+   * Show one section of the Session Options modal.
+   *
+   * The chrome is the shared `set-*` settings surface, but unlike App Settings
+   * (whose rail is a table of contents over one scrolling document) this rail
+   * is a real switcher: exactly one `.set-section` is visible and the rest
+   * carry `.hidden`. Summary owns its own scroller and Respawn is long, so
+   * stacking them into a single document would bury both.
+   */
   switchOptionsTab(tabName) {
-    // Toggle active class on tab buttons
-    document.querySelectorAll('#sessionOptionsModal .modal-tab-btn').forEach(btn => {
+    // Toggle active class on rail entries
+    document.querySelectorAll('#sessionOptionsModal .set-rail-item').forEach(btn => {
       btn.classList.toggle('active', btn.dataset.tab === tabName);
     });
 
-    // Toggle hidden class on tab content
+    // Toggle hidden class on the sections
     document.getElementById('respawn-tab').classList.toggle('hidden', tabName !== 'respawn');
     document.getElementById('context-tab').classList.toggle('hidden', tabName !== 'context');
     document.getElementById('ralph-tab').classList.toggle('hidden', tabName !== 'ralph');
     document.getElementById('summary-tab').classList.toggle('hidden', tabName !== 'summary');
 
+    // A switched-to section starts at its own top, not at the scroll offset the
+    // previous one was left at.
+    const doc = document.getElementById('sessionOptionsDoc');
+    if (doc) doc.scrollTop = 0;
+
     // Load run summary data when switching to summary tab
     if (tabName === 'summary' && this.editingSessionId) {
       this.loadRunSummary(this.editingSessionId);
@@ -1782,7 +1808,7 @@ Object.assign(CodemanApp.prototype, {
     this.switchCaseModalTab('case-create');
     // Wire up tab buttons
     const modal = document.getElementById('createCaseModal');
-    modal.querySelectorAll('.modal-tabs .modal-tab-btn').forEach(btn => {
+    modal.querySelectorAll('.set-rail-item').forEach(btn => {
       btn.onclick = () => this.switchCaseModalTab(btn.dataset.tab);
     });
     // Scroll-into-view on focus for mobile keyboard visibility
@@ -1803,14 +1829,17 @@ Object.assign(CodemanApp.prototype, {
   switchCaseModalTab(tabName) {
     this.caseModalTab = tabName;
     const modal = document.getElementById('createCaseModal');
-    // Toggle active class on tab buttons
-    modal.querySelectorAll('.modal-tabs .modal-tab-btn').forEach(btn => {
+    // Toggle active class on rail entries
+    modal.querySelectorAll('.set-rail-item').forEach(btn => {
       btn.classList.toggle('active', btn.dataset.tab === tabName);
     });
-    // Toggle hidden class on tab content
-    modal.querySelectorAll('.modal-tab-content').forEach(content => {
+    // Toggle hidden class on the panels
+    modal.querySelectorAll('.set-section').forEach(content => {
       content.classList.toggle('hidden', content.id !== tabName);
     });
+    // A switched-to panel starts at its own top.
+    const doc = document.getElementById('createCaseDoc');
+    if (doc) doc.scrollTop = 0;
     // Update submit button (hide for manage tab)
     const submitBtn = document.getElementById('caseModalSubmit');
     if (tabName === 'case-manage') {

src/web/public/settings-ui.js

@@ -503,8 +503,11 @@ Object.assign(CodemanApp.prototype, {
     this._syncSettingsChips();
     this._syncModelCards();
     this._syncEffortSegment();
-    // Back to the top of the document (one scroll, not a tab reset).
-    this.switchSettingsTab('settings-terminal');
+    // Back to the top of the document (one scroll, not a tab reset). Updates is
+    // first now: the version this install is running, and whether a newer one is
+    // waiting, are the two things worth seeing before any preference. The rest of
+    // the system settings (paths, automation, remote access) tail the document.
+    this.switchSettingsTab('settings-updates');
     const modal = document.getElementById('appSettingsModal');
     modal.classList.add('active');
 
@@ -687,11 +690,89 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsJump')?.setAttribute('aria-expanded', open ? 'true' : 'false');
   },
 
-  /** Mirror checkbox state onto the chip labels (see _initSettingsNav). */
+  /**
+   * Mirror checkbox state onto the chip labels (see _initSettingsNav).
+   *
+   * Covers Session Options too: it shares the `set-*` surface, and its cycle-step
+   * chips would otherwise depend on `:has()` alone for their checked styling.
+   */
   _syncSettingsChips() {
-    document.querySelectorAll('#appSettingsModal .set-chip').forEach(chip => {
+    document.querySelectorAll('#appSettingsModal .set-chip, #sessionOptionsModal .set-chip').forEach(chip => {
       chip.classList.toggle('is-on', !!chip.querySelector('input')?.checked);
     });
+    this._syncLayoutPreview();
+  },
+
+  /**
+   * Redraw the Header & Panels live preview from the chips above it.
+   *
+   * The preview is a scale model of the app, not a second list of settings, so
+   * every icon is CLONED from the chip that owns it (`.set-chip-ico`): each icon
+   * has exactly ONE copy in index.html and a chip can never drift from the button
+   * it previews. A chip joins the preview purely by carrying `data-preview`
+   * (which slot) and `data-preview-order` (where in that slot); nothing here
+   * needs to know the setting's name.
+   *
+   * `data-preview-text` replaces the icon with a text token for the header
+   * entries that are readouts rather than buttons (plan usage, CPU, font size).
+   */
+  _syncLayoutPreview() {
+    const modal = document.getElementById('appSettingsModal');
+    if (!modal || typeof modal.querySelectorAll !== 'function') return;
+    const slots = {
+      header: document.getElementById('appSettingsPreviewHeader'),
+      panel: document.getElementById('appSettingsPreviewPanels'),
+      toolbar: document.getElementById('appSettingsPreviewToolbar'),
+      float: document.getElementById('appSettingsPreviewFloats'),
+    };
+    if (!slots.header) return;
+    Object.values(slots).forEach(el => {
+      if (el) el.innerHTML = '';
+    });
+
+    const chips = [...modal.querySelectorAll('.set-chip[data-preview]')]
+      .filter(chip => chip.querySelector('input')?.checked)
+      .sort((a, b) => (Number(a.dataset.previewOrder) || 0) - (Number(b.dataset.previewOrder) || 0));
+
+    let shown = 0;
+    for (const chip of chips) {
+      const kind = chip.dataset.preview;
+      const slot = slots[kind];
+      if (!slot) continue;
+      // The label is the chip's own text; the icon span (if any) is skipped by
+      // taking the LAST span, which is always the label.
+      const spans = chip.querySelectorAll('span');
+      const label = (spans[spans.length - 1]?.textContent || '').trim();
+      const el = document.createElement('span');
+      el.title = label;
+      if (kind === 'header') {
+        const text = chip.dataset.previewText;
+        el.className = text ? 'set-preview-chip' : 'set-preview-btn';
+        if (text) el.textContent = text;
+        else this._appendPreviewIcon(el, chip);
+      } else {
+        el.className = `set-preview-${kind}`;
+        this._appendPreviewIcon(el, chip);
+        const name = document.createElement('span');
+        name.textContent = label;
+        el.appendChild(name);
+      }
+      slot.appendChild(el);
+      shown++;
+    }
+
+    const empty = document.getElementById('appSettingsPreviewEmpty');
+    if (empty) empty.hidden = shown > 0;
+  },
+
+  /** Clone a chip's icon into a preview element (see _syncLayoutPreview). */
+  _appendPreviewIcon(target, chip) {
+    const icon = chip.querySelector('.set-chip-ico');
+    if (!icon) return;
+    const clone = icon.cloneNode(true);
+    clone.classList.remove('set-chip-ico');
+    clone.classList.add('set-preview-ico');
+    target.appendChild(clone);
   },
 
   /**
@@ -860,6 +941,10 @@ Object.assign(CodemanApp.prototype, {
       section.classList.toggle('set-hit-hidden', !!q && !hasVisible);
     });
 
+    // The live preview sits outside any group, so it survives the sweep above;
+    // a search is asking for one row, not for the scale model around it.
+    doc.querySelectorAll('.set-preview').forEach(pv => pv.classList.toggle('set-hit-hidden', !!q));
+
     const empty = document.getElementById('appSettingsSearchEmpty');
     if (empty) empty.hidden = !q || anyVisible;
     if (!q) doc.querySelectorAll('.set-group-advanced').forEach(g => g.classList.remove('open'));

test/admin-ui.test.ts

@@ -135,11 +135,16 @@ describe('admin panel modal', () => {
 
 describe('index.html wiring', () => {
   it('loads admin-ui.js after settings-ui.js and before session-ui.js', () => {
-    const settings = INDEX_HTML.indexOf('settings-ui.js');
-    const admin = INDEX_HTML.indexOf('admin-ui.js');
-    const session = INDEX_HTML.indexOf('session-ui.js');
-    expect(admin).toBeGreaterThan(settings);
-    expect(session).toBeGreaterThan(admin);
+    // Match the SCRIPT TAG, not the bare filename: modal markup earlier in the
+    // document cites these modules in comments ("session-ui.js: openSessionOptions"),
+    // and a bare indexOf finds the comment instead of the load order.
+    const at = (file: string) => {
+      const i = INDEX_HTML.indexOf(`src="${file}"`);
+      expect(i, `no <script src="${file}"> in index.html`).toBeGreaterThan(-1);
+      return i;
+    };
+    expect(at('admin-ui.js')).toBeGreaterThan(at('settings-ui.js'));
+    expect(at('session-ui.js')).toBeGreaterThan(at('admin-ui.js'));
   });
 
   it('ships the header Admin Panel button hidden by default', () => {

test/app-settings-structure.test.ts

@@ -59,8 +59,28 @@ describe('App Settings modal structure', () => {
     }
   });
 
-  it('opens on Terminal & Input, so Local Echo is the first thing in reach', () => {
-    expect(settingsUi).toContain("this.switchSettingsTab('settings-terminal')");
+  it('opens on Updates: the version and the updater above everything else', () => {
+    expect(settingsUi).toContain("this.switchSettingsTab('settings-updates')");
+    const modal = settingsModal();
+    const order = [...modal.matchAll(/<section class="set-section" id="([a-z-]+)"/g)].map((m) => m[1]);
+    // Rail and document must agree, or scroll-spy paints the wrong entry.
+    const rail = [...modal.matchAll(/data-section="([a-z-]+)"/g)].map((m) => m[1]);
+    expect(rail.slice(0, 3)).toEqual(['settings-updates', 'settings-terminal', 'settings-layout']);
+    expect(order.slice(0, 3)).toEqual(['settings-updates', 'settings-terminal', 'settings-layout']);
+    // Updates carries ONLY the version and the update action; the rest of the
+    // system settings tail the document under System, out of the way.
+    const updates = modal.match(/id="settings-updates"([\s\S]*?)<\/section>/)?.[1] ?? '';
+    expect(updates).toContain('id="updateCurrentVersion"');
+    expect(updates).toContain('id="updateCheckBtn"');
+    expect(updates).not.toContain('id="appSettingsClaudeMdPath"');
+    expect(rail[rail.length - 1]).toBe('settings-system');
+    expect(order[order.length - 1]).toBe('settings-system');
+    const system = modal.match(/id="settings-system"([\s\S]*?)<\/section>/)?.[1] ?? '';
+    expect(system).toContain('id="appSettingsClaudeMdPath"');
+    expect(system).toContain('id="appSettingsTunnelEnabled"');
+  });
+
+  it('keeps Local Echo the first row of the second section', () => {
     const terminal = settingsModal().match(/id="settings-terminal"([\s\S]*?)<\/section>/);
     const localEcho = terminal?.[1].indexOf('appSettingsLocalEcho') ?? -1;
     const cjk = terminal?.[1].indexOf('appSettingsCjkInput') ?? -1;
@@ -68,6 +88,33 @@ describe('App Settings modal structure', () => {
     expect(localEcho).toBeLessThan(cjk);
   });
 
+  it('gives every previewed chip an icon to clone, and a slot that exists', () => {
+    // _syncLayoutPreview clones `.set-chip-ico` out of the chip, so a chip that
+    // opts into the preview without an icon renders as an empty button, and one
+    // pointing at a slot id that does not exist renders as nothing at all.
+    const layout = settingsModal().match(/id="settings-layout"([\s\S]*?)<\/section>/)?.[1] ?? '';
+    const chips = [...layout.matchAll(/<label class="set-chip"([^>]*)>([\s\S]*?)<\/label>/g)];
+    const previewed = chips.filter(([, attrs]) => attrs.includes('data-preview='));
+    expect(previewed.length).toBeGreaterThanOrEqual(15);
+    for (const [, attrs, body] of previewed) {
+      const kind = attrs.match(/data-preview="([a-z]+)"/)?.[1];
+      expect(['header', 'panel', 'toolbar', 'float']).toContain(kind);
+      expect(attrs, `chip ${body} needs a preview order`).toMatch(/data-preview-order="\d+"/);
+      // A text token replaces the icon for readouts (plan usage, CPU, font size).
+      const hasIcon = body.includes('class="set-chip-ico') || attrs.includes('data-preview-text=');
+      expect(hasIcon, `chip ${body} has nothing to render in the preview`).toBe(true);
+    }
+    for (const id of [
+      'appSettingsPreviewHeader',
+      'appSettingsPreviewPanels',
+      'appSettingsPreviewToolbar',
+      'appSettingsPreviewFloats',
+    ]) {
+      expect(layout).toContain(`id="${id}"`);
+      expect(settingsUi).toContain(`'${id}'`);
+    }
+  });
+
   it('models: keeps the 1M variants as select options behind the context switch', () => {
     const modal = settingsModal();
     const select = modal.match(/id="appSettingsClaudeModel"([\s\S]*?)<\/select>/)?.[1] ?? '';
@@ -80,15 +127,15 @@ describe('App Settings modal structure', () => {
     expect(modal).toContain('id="appSettingsOpusContext1m"');
   });
 
-  it('never hides sections behind .modal-tab-content (that class means display:none)', () => {
+  it('has retired the modal-tab chrome everywhere, not just here', () => {
+    // Session Options and Add Case moved onto this same `set-*` surface, so the
+    // old tab classes have no users left. A reappearance means a modal drifted
+    // back off the shared surface (or the dead CSS was resurrected).
     expect(settingsModal()).not.toContain('modal-tab-content');
-  });
-
-  it('leaves the shared modal tab classes to the other modals', () => {
-    // #sessionOptionsModal and #createCaseModal still use .modal-tabs; the
-    // settings rail must not restyle them out from under those.
-    expect(settingsModal()).not.toContain('class="modal-tabs"');
-    expect(html).toContain('<div class="modal-tabs">');
+    expect(html).not.toContain('class="modal-tabs"');
+    expect(html).not.toContain('modal-tab-btn');
+    const css = readFileSync(resolve(publicDir, 'styles.css'), 'utf8');
+    expect(css).not.toContain('.modal-tab-btn {');
   });
 
   it('exposes the rail hooks admin-ui.js injects the Users section into', () => {

test/session-options-structure.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Session Options structural guard.
+ *
+ * The modal shares the `set-*` settings surface with App Settings, but its rail
+ * is a real switcher: switchOptionsTab shows one `.set-section` and hides the
+ * rest. Like App Settings, its load/save path is `getElementById` by a fixed set
+ * of ids, so dropping or renaming an element in the markup fails silently — the
+ * option just stops loading, or stops being written back.
+ *
+ * These tests read the REAL session-ui.js and index.html and pin that contract.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const publicDir = resolve(import.meta.dirname, '../src/web/public');
+const html = readFileSync(resolve(publicDir, 'index.html'), 'utf8');
+const sessionUi = readFileSync(resolve(publicDir, 'session-ui.js'), 'utf8');
+
+/** The Session Options markup, so assertions can't be satisfied elsewhere. */
+function optionsModal(): string {
+  const start = html.indexOf('<div class="modal" id="sessionOptionsModal">');
+  expect(start).toBeGreaterThan(-1);
+  const end = html.indexOf('<!-- Close Session Confirmation Modal -->', start);
+  expect(end).toBeGreaterThan(start);
+  return html.slice(start, end);
+}
+
+/** Body of a session-ui.js method, by name. */
+function methodBody(signature: string): string {
+  const start = sessionUi.indexOf(`\n  ${signature} {`);
+  expect(start, `${signature} not found in session-ui.js`).toBeGreaterThan(-1);
+  return sessionUi.slice(start, sessionUi.indexOf('\n  },', start));
+}
+
+const TABS = ['respawn', 'context', 'ralph', 'summary'];
+
+describe('Session Options modal structure', () => {
+  it('keeps every element openSessionOptions and switchOptionsTab touch by id', () => {
+    const modal = optionsModal();
+    const ids = new Set<string>();
+    for (const sig of ['openSessionOptions(sessionId)', 'switchOptionsTab(tabName)', 'getRalphConfig()']) {
+      for (const m of methodBody(sig).matchAll(/getElementById\('([A-Za-z0-9_-]+)'\)/g)) ids.add(m[1]);
+    }
+    // openSessionOptions also drives elements outside this modal (tabs, toasts);
+    // only the ones it expects to find in here are this file's contract.
+    const outside = new Set(['sessionOptionsDoc']);
+    const missing = [...ids].filter((id) => !outside.has(id) && !modal.includes(`id="${id}"`));
+    expect(missing).toEqual([]);
+    expect(modal).toContain('id="sessionOptionsDoc"');
+  });
+
+  it('pairs each rail entry with exactly one section, in the same order', () => {
+    const modal = optionsModal();
+    const rail = [...modal.matchAll(/class="set-rail-item[^"]*" data-tab="([a-z]+)"/g)].map((m) => m[1]);
+    expect(rail).toEqual(TABS);
+    for (const tab of TABS) {
+      const hits = modal.split(`id="${tab}-tab"`).length - 1;
+      expect(hits, `section ${tab}-tab should exist exactly once`).toBe(1);
+    }
+    // switchOptionsTab queries the rail by THIS class; `.modal-tab-btn` here
+    // would silently stop the active marker from moving.
+    expect(methodBody('switchOptionsTab(tabName)')).toContain("'#sessionOptionsModal .set-rail-item'");
+    expect(methodBody('openSessionOptions(sessionId)')).toContain('.set-rail-item[data-tab="ralph"]');
+  });
+
+  it('opens with exactly one section visible, the rest hidden', () => {
+    const modal = optionsModal();
+    const visible = TABS.filter((t) => modal.includes(`<section class="set-section" id="${t}-tab"`));
+    expect(visible).toEqual(['respawn']);
+    for (const t of TABS.filter((t) => t !== 'respawn')) {
+      expect(modal).toContain(`<section class="set-section hidden" id="${t}-tab"`);
+    }
+  });
+
+  it('keeps the Claude-only rail entries marked, so external CLIs lose them', () => {
+    const modal = optionsModal();
+    for (const tab of ['respawn', 'ralph']) {
+      const entry = modal.match(new RegExp(`<button[^>]*data-tab="${tab}"[^>]*>`))?.[0] ?? '';
+      expect(entry, `${tab} rail entry`).toContain('data-claude-only');
+    }
+    expect(modal.match(/<button[^>]*data-tab="context"[^>]*>/)?.[0]).not.toContain('data-claude-only');
+  });
+
+  it('uses the shared settings surface rather than the modal-tab chrome', () => {
+    const modal = optionsModal();
+    expect(modal).toContain('class="modal-content modal-lg set-shell"');
+    expect(modal).toContain('class="set-body"');
+    expect(modal).not.toContain('class="modal-tabs"');
+    expect(modal).not.toContain('modal-tab-btn');
+    expect(modal).not.toContain('modal-tab-content');
+    // The `set-*` rules are shared by both modals through one :is() scope.
+    const css = readFileSync(resolve(publicDir, 'styles.css'), 'utf8');
+    expect(css).toContain(':is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-row {');
+    expect(css).toContain(':is(#sessionOptionsModal, #createCaseModal) .set-section.hidden {');
+  });
+});