specrails-desktop 2.18.2 → 2.19.0

package/docs/internals/switch-to-agent-mode-design.md

@@ -0,0 +1,301 @@
+# Switch to Agent Mode — Design Dossier
+
+> **Status: pre-implementation design artifact (explore mode).** This document consolidates 8 structured investigation slices into a single implementation plan. No application code is written here. It defines the shell swap, the shared conversation-view extraction, the left-sidebar restructure, the three "On workspace" tools, the full attachment-parity plan, search wiring, and the cross-cutting concerns. Section 10 carries the consolidated RISKS and the numbered OPEN DECISIONS that a human must resolve before implementation begins.
+
+---
+
+## 1. Overview + decided constraints
+
+**Goal.** Add an app-global **Agent Mode** UI that replaces the Kanban route-driven center with a Cursor-style agent workspace: a full-height conversation surface, a restructured left sidebar (project→conversation trees), a hidden navbar search (moved into the sidebar), and a right "On workspace" toolbar exposing three tools (Terminal, Files, Browser). The floating agent bubble/panel are suppressed while in Agent Mode — the same conversation UI is hoisted inline.
+
+**Decided constraints (fixed inputs to this design):**
+
+1. **`uiMode` is persisted.** A new app-global `uiMode: 'kanban' | 'agent'` lives in its own small context (`UiModeProvider`), localStorage-backed, no project dependency. It gates the shell swap, the sidebar buttons, the search pill, and the floating surfaces.
+2. **Brave option A — inline CodePage.** The Files tool embeds the existing `CodePage` inline (decoupled from `ProjectLayout` and the `/code` route) rather than shipping a stripped-down viewer. This is a real refactor of `CodePage` into a controlled component.
+3. **Brave option B — full attachment parity + wired Browser.** The Agent composer reaches **full parity** with the Explore Add-Spec composer: `RichAttachmentEditor` (file-pick / drag-drop / image-paste / @-pills) **plus** the live `BrowserCaptureModal` / `CapturedDomPanel` browser-capture flow, all uploaded through a new app-global agent attachment endpoint and folded into the provider prompt. The Browser "On workspace" tool reuses the same capture stack.
+4. **All three "On workspace" tools require an active project.** They are disabled when `activeProjectId` is null.
+
+**Two things that stay byte-identical:** Kanban mode must render exactly as today, and the CommandPalette (Cmd+K) keeps its own global keydown listener so the shortcut keeps working regardless of which mode is active.
+
+---
+
+## 2. Architecture diagram (shell swap + provider tree)
+
+```
+main.tsx  →  <BrowserRouter>            (single app-wide router; main.tsx:17-19)
+             └─ SharedWebSocketProvider (App.tsx:433 — above routes; CodePage/FileTree/FileViewer depend on it)
+                └─ App()
+                   └─ DesktopProvider                          (App.tsx:440 — projects, activeProjectId, api base)
+                      └─ ★ UiModeProvider ★   ◄── NEW, inserted here (wraps TitleBar onward, closes before </DesktopProvider> App.tsx:465)
+                         ├─ TitleBar          (App.tsx:442) ── reads uiMode → HIDES SearchPill when 'agent' (TitleBar.tsx:175,215)
+                         ├─ SpecGen / ContractRefine / Smash / SidebarPin / Terminals / RailMetrics / MinimizedChats providers
+                         │   (TerminalsProviderWithDesktop App.tsx:447 — already app-level; terminal state is mode-agnostic)
+                         └─ AgentChatProvider (App.tsx:450) ── reads uiMode → SUPPRESSES AgentChatPanel(:293)+AgentBubble(:296)
+                            └─ TicketDetailModalProvider ...
+                               └─ DesktopApp   (App.tsx:453 / body 230-330)
+                                  │
+                                  │  flex h-full row:
+                                  ├─ ArcSidebar (App.tsx:233-239) ── reads uiMode → sidebar buttons + project/conversation trees
+                                  │
+                                  ├─ main-area column  <div flex flex-col flex-1>  (App.tsx:242-297)
+                                  │   ├─ project-switching progress bar (:244-249)
+                                  │   ├─ content box <div flex-1 overflow-hidden> (:252-296)
+                                  │   │     {isInSetup ? SetupWizard
+                                  │   │      : uiMode==='agent' ? ★ <AgentModeSurface/> ★   ◄── NEW center swap
+                                  │   │      : <Suspense><Routes> … ProjectLayout … </Routes></Suspense>}   (existing, :261-294)
+                                  │   │
+                                  │   └─ ★ <BottomPanel/> + <StatusBar/> ★   ◄── HOISTED here from ProjectLayout (both modes, one instance)
+                                  │         gated on activeProject; chevronSlot gated on uiMode==='kanban'
+                                  │
+                                  └─ right sidebar (App.tsx:302)
+                                        {uiMode==='agent'
+                                           ? activeProject && !isInSetup && ★ <AgentWorkspaceSidebar/> ★   ◄── NEW (Browser/Terminal/Files)
+                                           : activeProject && !isInSetup && !/loops && <ProjectRightSidebar/>}   (existing)
+```
+
+Key structural moves shown above:
+
+- **`UiModeProvider` mounts just inside `DesktopProvider`** (App.tsx:440) so `TitleBar`, `AgentChatProvider`, `ArcSidebar`, the center, and both right sidebars all read it.
+- **`BottomPanel` + `StatusBar` are HOISTED** out of the route element `ProjectLayout` (currently ProjectLayout.tsx:124-134) into the `DesktopApp` main-area column (App.tsx ~:296), so the terminal survives when the center is no longer a route. `TerminalsProvider` is already app-level (App.tsx:447), so only the *visual* panel needs hoisting.
+
+---
+
+## 3. Component / module inventory
+
+### NEW files to create
+
+| File | Responsibility | Key anchors |
+|---|---|---|
+| `client/src/context/UiModeContext.tsx` | App-global `uiMode: 'kanban'\|'agent'` + `setUiMode`/`toggle`, localStorage-persisted; `useUiMode()` with NOOP fallback for tests. | Insert provider at App.tsx:440-441; consumed by TitleBar/ArcSidebar/AgentChatContext/DesktopApp. |
+| `client/src/components/agent-chat/AgentConversationView.tsx` | Shared inner UI (banners + sticky-scroll message list + streaming + activity chip + composer) consumed by BOTH the floating panel and the inline surface; `variant: 'floating'\|'inline'`. | Extracted from AgentChatPanel.tsx:158-269. |
+| `client/src/components/agent-chat/AgentModeSurface.tsx` | Inline center surface: EMPTY (`active===null` → centered composer card) vs ACTIVE (`<AgentConversationView variant='inline'/>` + optional Files/code split). Does NOT call `ensureActive` on mount. | Mounted at App.tsx center swap (:252-296). |
+| `client/src/components/agent-chat/AgentWorkspaceSidebar.tsx` | Right "On workspace" toolbar in Agent Mode: Browser / Terminal / Files buttons, each disabled when `activeProjectId` is null. | Mounted at App.tsx:302 (agent branch). |
+| `client/src/components/agent-chat/AgentModeCodePane.tsx` (optional wrapper) | Resizable split host that mounts `<CodePage embedded/>` as a secondary pane beside the thread; own `<Suspense>` boundary. | Wraps CodePage.tsx (lazy). |
+| `server/agent-attachment-routes` (in `agent-chat-router.ts`) | App-global attachment endpoints: `POST/GET/DELETE /api/agent/conversations/:id/attachments` (multer single 'file', 25MB, mime filter). | Mirror project-router-tickets.ts:1839-1917. |
+| `server/agent-store` migration | Persist attachment id list per agent turn (new nullable `attachments` JSON column on `agent_messages`, or sibling `agent_message_attachments` table). | agent-store.ts:24-30,111-128. |
+
+### EXISTING files to modify
+
+| File | Change | Key anchors |
+|---|---|---|
+| `client/src/App.tsx` | Insert `UiModeProvider`; branch center on `uiMode`; branch right sidebar; hoist `BottomPanel`+`StatusBar` into main-area column; source `viewportHeight`/`panelState`/`connectionStatus` at DesktopApp scope. | 230-330 (shell), 440-461 (providers). |
+| `client/src/components/ProjectLayout.tsx` | REMOVE the `BottomPanel`/`StatusBar` render (hoisted); keep `<Outlet/>`, ChatContext; gate chevronSlot on `uiMode==='kanban'`; relocate the `viewportHeight` ResizeObserver + `panelState` up. | 66-95, 124-134. |
+| `client/src/components/TitleBar.tsx` | Hide `SearchPill` when `uiMode==='agent'` at both mount sites. | 66-129 (pill), 175 & 215 (mounts). |
+| `client/src/context/AgentChatContext.tsx` | Gate `AgentChatPanel`(:293) + `AgentBubble`(:296) off when `uiMode==='agent'`; expose a public `refreshConversations`; extend `newConversation(projectId?)`. | 39-70, 246-253, 290-298. |
+| `client/src/components/agent-chat/AgentChatPanel.tsx` | Reduce to thin chrome wrapper rendering `<AgentConversationView variant='floating'/>`; keep `useMovableResizableModal`/maximize/header/`ResizeGrips`. | 30-119 (chrome), 121-284 (body). |
+| `client/src/components/ArcSidebar.tsx` | Add `useAgentChat()` + `useUiMode()`; add [Switch mode]/[New agent]/[Search] buttons above Loops; make `ProjectItem` expandable; render conversation children + Home group; branch `handleSelectProject` by mode. | 1-9, 19-106, 135-166, 206-259. |
+| `client/src/pages/CodePage.tsx` | Add controlled/`embedded` props; neutralize `navigate({pathname:'/code'})` calls; gate URL→state effects when embedded. | 51-96, 129-160. |
+| `server/agent-chat-router.ts` | Parse `attachments:{ids}` on `POST /:id/send`; add attachment endpoints. | 144-163. |
+| `server/agent-chat-manager.ts` | Resolve attachment textBlocks via `attachmentManager.getClaudeArgs`, fold into `prompt` before pinned-project prefix; append note for codex/gemini into prompt. | 72-235 (fold near :97-102, chokepoint :151). |
+| `server/attachment-manager.ts` | Add app-global agent storage root (`~/.specrails/agent/<conversationId>/attachments/`) or overload; keep traversal guards. | 89-133, 287-348. |
+
+---
+
+## 4. `AgentConversationView` extraction plan (shared by floating panel + inline surface)
+
+**Boundary.** `AgentChatPanel.tsx` currently fuses two separable concerns. Split them:
+
+- **WINDOW-CHROME WRAPPER (stays in `AgentChatPanel.tsx`):** `useMovableResizableModal` (AgentChatPanel:30-37), `maximized` + `MAXIMIZED_STYLE` (:27,:41), the `motion.div` shell (:123-135), the header drag band with `Bot` icon + maximize/minimize buttons (:137-155), the `ResizeGrips` overlay (:277-281), and the persisted geometry `persistKey 'specrails-desktop:agent-panel-geom'`. **Chrome-only — must NOT leak into the inline variant.**
+- **SHARED `<AgentConversationView>` (NEW):** the two banners (no-provider :158-166, MCP-degraded :169-177), the messages scroll region including empty placeholder (:180-199), `messages.map(<AgentMessage/>)` (:188-190), the streaming block with `useSmoothStream` + `<AgentActivityChip/>` (:191-198), and the entire composer (:202-269). The local state that powers these **moves with the view:** `input` (:26), `scrollRef`/`pinnedRef` sticky-scroll (:28,:49-58), `useSmoothStream(streamingText,isStreaming)` (:43), prompt-history `histIndex`/`history`/`recall`/`onComposerKeyDown` (:61-109). The Shift+Tab tier-cycle handler `onPanelKeyDown` (:113-119) must be **re-bound onto the shared view's root wrapper** (it only calls `cycleTier()` from context, so it is portable).
+
+**Prop / context boundary.** The view is **almost entirely context-driven** via `useAgentChat()` (AgentChatContext:39-70): `active`, `messages`, `streamingText`, `isStreaming`, `liveTools`, `mcpEnabled`, `enablingMcp`, `enableMcpServer`, `providersReady`, `send`, `abort`, `cycleTier`, `setProvider`, `setModel`, `setPinnedProject`. The **only props** are presentational: `variant: 'floating'|'inline'` (switches padding, rounded corners, whether the composer docks bottom vs centers), and optionally a `newConversation` callback carrying the active project for the inline [New agent] flow.
+
+**EMPTY vs ACTIVE (inline surface).** Derived purely from context: `active===null` → **EMPTY** (centered "Plan, Build" composer card); `active!==null` → **ACTIVE** (full thread + docked composer). Note the floating panel's in-scroll placeholder uses `messages.length===0 && !isStreaming` (:181) while a conversation may still be active — the inline surface must use `active===null` instead. Because `open()/ensureActive()` (:176-209) auto-creates/loads a conversation, `AgentModeSurface` must **not** call `ensureActive` on mount, or the EMPTY state can never appear.
+
+**Re-homing the project selector.** `AgentProjectSelector` (AgentProjectSelector.tsx:13-91) currently sits in the panel **header (chrome)** (AgentChatPanel:143). Extracting only the inner subtree would drop it from Agent Mode — it must be **re-homed into the composer or the empty-state card**.
+
+**Pin defaulting.** `newConversation()` (AgentChatContext:246-253) hardcodes `pinnedProjectId: active?.pinned_project_id ?? null` and takes no args. Extend to `newConversation(projectId?: string|null)` using `projectId!==undefined ? projectId : (active?.pinned_project_id ?? null)` so the floating panel's arg-less call (AgentChatPanel:145) stays backward-compatible while the inline [New agent] can pass `useDesktop().activeProjectId` (useDesktop:269).
+
+---
+
+## 5. Left sidebar restructure (`ArcSidebar.tsx`)
+
+`ArcSidebar` is self-contained (consumes `useDesktop()` + `useSidebarPin()` at :122, imports at :1-9) and sits inside both `DesktopProvider` and `AgentChatProvider` (App.tsx:440-457), so it can safely add `useAgentChat()` (NOOP fallback at AgentChatContext:301-318 keeps it test-mountable) and `useUiMode()`.
+
+**New buttons cluster (inserted ABOVE the Loops block, before ArcSidebar:206):**
+
+- **[Switch to Agent/Kanban mode]** — always shown (both modes). `onClick=toggleUiMode`. JSX mirrors the Loops button (:209-225): `type=button`, icon (Bot/Sparkles for agent, LayoutGrid/Columns for kanban) + `{expanded && <span>…</span>}`. Label flips on current `uiMode`.
+- **[New agent]** — agent mode only. `onClick=newConversation(activeProjectId?)` (see §4 pin defaulting). Icon `Plus`.
+- **[Search]** — agent mode only (replaces the hidden navbar pill). `onClick` dispatches the synthetic Cmd+K keydown (see §8). Icon `Search`.
+
+**Project→conversation trees (agent mode):**
+
+- Group `useAgentChat().conversations` (agent-api.ts:10-20) by `pinned_project_id` via `useMemo`: `Map<string|null, AgentConversation[]>`. Use a **sentinel** for the `null` key.
+- Each `ProjectItem` (:19-106) becomes expandable: add a leading chevron hit-area (ChevronRight/ChevronDown) that toggles tree expansion **independently** of row activation. Split the current whole-row `onClick=onSelect` (:67): chevron toggles expand, row body sets active project. Only render the chevron in agent mode when the project has >0 conversations.
+- Render conversation children (indented) for `pinned_project_id === project.id`; each `onClick=selectConversation(id)` (async, loads thread) **and** ensures `uiMode==='agent'`; highlight when `conv.id === active?.id`. Fallback label for nullable `title` (agent-api.ts:12) — e.g. "Untitled".
+- A synthetic **Home pseudo-group** (agent mode only) renders conversations with `pinned_project_id === null`, not nested under any project.
+
+**Expand state.** Held locally in `ArcSidebar` as `useState<Set<string>>` (or `Record`), initialized from and persisted to a **new** localStorage key (e.g. `specrails-desktop:agentTreeExpanded`), default-expanding the active project. This is orthogonal to the existing sidebar-width `expanded` flag (:149, from `useSidebarPin`), which only controls label visibility.
+
+**Click semantics reconciliation.** Branch `handleSelectProject` (:135-147) by `uiMode`. In **agent mode** skip the `navigate('/')`/route-memory path (the center is the agent surface, not routes) and just `setActiveProjectId(projectId)` (useDesktop:90-102) + toggle expand — `setActiveProjectId` has side effects (`writeSavedProjectId` + `setApiActiveProjectId` :91-92, 400ms switching flag) but must NOT trigger visible route navigation. In **kanban mode** keep today's behavior exactly.
+
+**Refresh gap.** `AgentChatContextValue` exposes **no** standalone refresh — `conversations[]` is only refreshed inside `open()`/`toggle()` (AgentChatContext:193,204). Entering agent mode must expose/call a `refreshConversations` (preferred over calling `open()`, which would set `visibility='open'` and mount the now-suppressed floating panel).
+
+---
+
+## 6. The three "On workspace" tools
+
+All three are gated on `!!activeProjectId` (disabled tooltip otherwise), matching the decided rule.
+
+### 6a. Terminal — hoist `BottomPanel`
+
+`TerminalsProvider` is **already app-level** (App.tsx:447) and keyed off the active project, so PTYs, xterm instances, WS sockets and per-project panel state already survive route/project switches (durable refs at TerminalsContext:209-229; server-sync effect keyed on `activeProjectId` :297-334; disposal only on explicit kill/unmount :428-466). The **single hidden `#specrails-terminal-host`** (:178-194) and the single-adopter `TerminalViewport` reparenting invariant (TerminalViewport:126-139) mean unmounting the visible panel does NOT dispose the terminal — the DOM node simply returns to the host.
+
+- **Reuse:** `useTerminals()` (already in DesktopApp App.tsx:152), `useProjectTerminals(activeProjectId)` (ProjectLayout:68), `setVisibility(projectId,'restored')` (TerminalsContext:273), `togglePanel(projectId)` (:277, the Cmd+J action App.tsx:196), `<BottomPanel projectId provider providers state viewportHeight statusBarHeight/>` (BottomPanel:36, returns null when hidden), `projectProviders(project)`, `PanelChevronButton`.
+- **New work:** hoist the `BottomPanel` render (ProjectLayout:124-133) to the DesktopApp main-area column (App.tsx ~:296), driven by `activeProjectId` + `useProjectTerminals(activeProjectId)`, so **one** instance serves both modes; move the `viewportHeight` ResizeObserver (ProjectLayout:69-83) + `STATUSBAR_HEIGHT_PX` up; gate `chevronSlot` on `uiMode==='kanban'` (ProjectLayout:90-95); wire the sidebar Terminal button to `setVisibility(activeProjectId,'restored')`. **Ensure only ONE `BottomPanel`/`TerminalViewport` is mounted at any time** (remove the ProjectLayout copy) to preserve the single-adopter invariant.
+
+### 6b. Files — inline `CodePage`
+
+`CodePage`'s data layer is bound to the **active project**, not route context: `FileTree`/`FileViewer`/provenance fetch via `getApiBase()` (api.ts:13-28, module singleton set by `DesktopProvider`) and read `activeProjectId` via `useDesktop()`. It consumes **zero** context that `ProjectLayout` provides (no `useTerminals`, no `useChat`, no `BottomPanel`); the only transitive app-level provider is `useSharedWebSocket` (App.tsx:433, above routes). The **only** true shell coupling is React Router: `useSearchParams`/`useNavigate` pinned to `pathname:'/code'` (CodePage:133,140,147,159).
+
+- **Reuse:** `getApiBase()` (throws when no active project — enforces the "requires active project" rule), `useDesktop().activeProjectId`, controlled `FileTree` props (`onOpenFile`, `selectedPath`, `filterJobId`, `filterTicketId`), controlled `FileViewer` props (`relPath`, `onFilterJob`, …), `useSharedWebSocket()`.
+- **New work:** refactor `CodePage` into a **controlled** component — add optional props (`selectedPath?`, `onSelectedPathChange?`, `jobFilter?`/`ticketFilter?`, `onFilterChange?`, `embedded?`); when provided, lift internal state and **replace the `navigate({pathname:'/code'})` calls (:133,140,147,159) with callbacks**; gate the URL→state sync effect (:71-75) + searchParams effects to no-op when embedded. Mount inside `AgentModeSurface` as a **split** secondary pane (thread | code) with its own `<Suspense>` boundary (CodePage is `React.lazy`, App.tsx:21). Store code selection in the Agent Mode context/state (NOT the URL). Mind the nested-split min-width math (`MIN_MAIN_WIDTH=520` + `MIN_TREE_WIDTH=240`).
+
+### 6c. Browser — capture reuse
+
+The Explore browser-capture stack is fully project-scoped and reusable verbatim.
+
+- **Reuse:** `BrowserCaptureModal` (props `{open,onClose,projectId,pendingSpecId,onCaptured,confirmLabel}`), `CapturedDomPanel` (props `{dom,onRemove?}`), the `client/src/lib/browser-capture.ts` REST helpers (`createBrowserSession`, `navigateBrowser`, `captureBrowserRegion`, `captureBrowserBreakpoints`, `uploadCaptureImage`), `isBrowserCaptureEnabled()` (client flag `VITE_FEATURE_BROWSER_CAPTURE`), and server `requireBrowserCaptureEnabled`/`SPECRAILS_BROWSER_CAPTURE` (feature-flags.ts:9-13). Server session endpoints at project-router-terminals.ts:200-410.
+- **New work:** wire the sidebar Browser button to open `BrowserCaptureModal` with the current `activeProjectId` and the agent conversation's pending id; route `onCaptured` into the composer capture chips (see §7). Requires an active project (browser sessions are project-scoped).
+
+---
+
+## 7. Full attachment-parity plan
+
+Today the agent turn is **text-only**. `POST /api/agent/conversations/:id/send` accepts `{text, tierLevel?, model?}` (agent-chat-router:150-162) → `AgentChatManager.sendMessage` builds `prompt = optional '[Active project…]' prefix + userText` (agent-chat-manager:100-102) → `runAiCliInvocation` passes it as an argv positional (`buildOpts.prompt`, :151). There is **no** upload endpoint, **no** attachment path, and **no** per-turn `ai_invocations` accounting. The Explore side already has the complete mechanism; most of the work is wiring, not new storage.
+
+### 7a. Enumerated Explore affordances to port (parity list)
+
+From `RichAttachmentEditor` + `ExploreSpecShell`:
+
+1. **File picker** — footer "Attach files" button (RichAttachmentEditor:562-570) → hidden `<input type=file multiple accept=ATTACHMENT_ACCEPT_MIME>` (:578-585) → `handleBrowseChange` (:490-498) → `uploadFiles`.
+2. **Drag-drop** — root drop zone (:504-511) + "Drop to add context" overlay (:587-606) → `handleDrop` (:475-485) → `uploadFiles`.
+3. **Image paste** — `handlePaste` (:390-422): clipboard image item → renamed `paste-<date>-<n>.png` → `uploadFile`; non-image paste forced to plain text (HTML stripped).
+4. **Backspace/Delete on a pill** — removes attachment (`handleKeyDown` :342-388) + fires `onAttachmentRemoved` (Explore → DELETE on the attachments endpoint, ExploreSpecShell:966-971).
+5. **@-mention pills** — inline pills in the contenteditable (`buildPill` :79-98, serialized `@[filename](id)` :104-126). Pills are created **only** by uploads (no free-text @-typeahead).
+6. **Browser capture ("From a website")** — `footerExtra` Globe button (ExploreSpecShell:978-989) → `BrowserCaptureModal` (:1150-1159). User drives a live headless browser, selects a region/element, optionally annotates and/or captures at 3 breakpoints. `captureBrowserRegion`/`captureBrowserBreakpoints` write **TWO** attachments per capture (PNG screenshot + DOM JSON) into the same pending dir, returning `CaptureResult`. `handleCaptured` (:258-291) either auto-sends a feedback turn (`sendCaptureFeedback` :574-600) or queues a chip under the composer (:991-1033) that rides the next message.
+
+### 7b. Attachment data model
+
+- **Client:** an attachment is the `Attachment` type (`{id, filename, mimeType, storedName, …}`). The editor tracks `attached: Attachment[]` + DOM pills; `getAttachmentIds()` (RichAttachmentEditor:306-311) reads all `[data-attachment-id]`. Captures are tracked separately in `ExploreSpecShell.captures: BrowserCaptureEntry[]` (screenshotId, domAttachmentId, breakpoints[]) so both ids merge in.
+- **Server:** each attachment = file + `<id>.meta.json` sidecar under `~/.specrails/projects/<slug>/attachments/<ticketKey>/` (attachment-manager:96-133). `ticketKey` is a `pendingSpecId` (UUID) during Explore, path-sanitized. On Create Spec, `migrateToTicket` (attachment-manager:248-273) renames the pending dir to the real ticket id.
+
+### 7c. Server storage + upload endpoints (NEW for agent)
+
+- **New app-global upload route:** `POST /api/agent/conversations/:id/attachments` (multer `single('file')`, `memoryStorage`, 25MB cap, `isSupportedUploadedFile` filter) → `attachmentManager.upload(...)` with an agent-scoped key; returns `201 {attachment}`. Add `GET` (list), `GET /:attachmentId` (download), `DELETE` for parity. Mirror project-router-tickets.ts:1839-1917.
+- **New agent-scoped storage root:** `~/.specrails/agent/<conversationId>/attachments/` (the agent per-conversation dir already exists for mcp.json, agent-mcp-config.ts:135,162-169). Add an `agentAttachmentsRoot()`/overload on `AttachmentManager` (or a thin wrapper), **keeping the path-traversal guards** (attachment-manager:100-110). Do NOT reuse `projects/<slug>/attachments` with a synthetic slug — it risks colliding with a real project slug.
+- **Cleanup:** `deleteAgentConversation` (agent-store:107) must remove the attachment dir (a `deleteAll` analog).
+
+### 7d. Agent send-flow changes (payload / adapter contract / per-provider)
+
+- **Payload:** extend `POST /:id/send` to parse `attachments: { ids: string[] }` (the `conversationId` is the storage key — no slug needed). Mirror the chat parse at project-router-chat.ts:276-286.
+- **Fold point:** in `AgentChatManager.sendMessage`, resolve `attachmentManager.getClaudeArgs(agentKey, ids)` (attachment-manager:287, **async** — pdf/xlsx extraction) → `{imageFlags:[], textBlocks:string[]}` and fold `textBlocks` into `prompt` **before** the pinned-project prefix (between agent-chat-manager:97 and :100), exactly mirroring chat-manager:585-609 ("## Attached Resources" + `USER_ATTACHMENT_SYSTEM_NOTE`). `buildOpts.prompt` (:151) is the single chokepoint. Wrap in try/catch so extraction failure degrades to a text-only turn.
+- **Adapter contract:** prompt transport is **argv, not stdin** for all three providers — claude `-p opts.prompt` (claude-adapter:97,110), codex positional to `exec` (codex-adapter:88, folds systemPrompt :101), gemini `-p opts.prompt` (gemini-adapter:76). `SpawnOptions.attachmentTextBlocks?` is **reserved but unused** (providers/types.ts:40-41) — either fold-into-prompt (fast, matches Explore, recommended) or wire `attachmentTextBlocks` through the 3 adapters' `buildArgs` (cleaner, more edits).
+- **Per-provider image reality:** `getClaudeArgs` emits images as `@<abs-path>` refs. **Claude Code resolves these natively → images work.** codex/gemini receive the `@path` as **literal prompt text → the image is silently NOT loaded.** Extracted-text attachments (pdf/csv/xlsx/txt/json/sql) become inline `<user-attachment>` text and work for **all three**. LCD for v1 = text-extractable attachments for all providers; images are claude-only until per-adapter native image flags are added. This needs a UX decision (block images on non-claude vs attempt native flags) — see Open Decisions.
+- **Persistence:** `agent_messages` has only `{id, conversation_id, role, content}` (agent-store:24-30). To re-render pills/thumbnails after refresh, add a nullable `attachments` JSON column (new migration) or a sibling `agent_message_attachments` table.
+- **Metering (recommended, optional):** agent turns are currently **unmetered** — `AgentChatManager` is absent from the `ai_invocations` consumer set. Adding `finaliseInvocationResult` in the same change makes attachment-heavy turns visible on `/analytics`, matching Explore.
+
+---
+
+## 8. Search / Cmd+K plan
+
+The "navbar search box" is the **`SearchPill` inside `TitleBar.tsx`** (:64-129), not `Navbar.tsx` (which has no search). It does no inline searching — `handleClick` (:70-74) dispatches a synthetic `Cmd+K` keydown that the already-mounted `CommandPalette` (App.tsx:321-325, cmdk-based) listens for via a **global window keydown listener** (CommandPalette:53-62). There is **no imperative open API** — the synthetic-keydown dispatch is the only sanctioned seam.
+
+- **Hide** `SearchPill` when `uiMode==='agent'` (gate render at TitleBar:175 and :215). The palette's own listener keeps Cmd+K working with the pill hidden.
+- **New sidebar [Search] button** (agent mode) copies `SearchPill.handleClick` verbatim: `window.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', metaKey: true, bubbles: true }))`. Cross-platform: the palette listener accepts `metaKey||ctrlKey`, and the synthetic event sets `metaKey:true`, so it works on Windows/Linux too.
+- **Optional:** extract a tiny shared `openCommandPalette()` helper so both call sites share one function.
+
+Note the dispatch **toggles** — clicking [Search] while the palette is already open would close it (CommandPalette:57). v1 reuses the generic palette (projects/commands/jobs/nav); a scoped agent-conversation search would require refactoring `CommandPalette` to accept controlled open state.
+
+---
+
+## 9. Cross-cutting concerns
+
+- **Feature flag.** Gate the whole feature behind a client flag (e.g. `VITE_FEATURE_AGENT_MODE`, default per policy) resolved through `client/src/lib/feature-flags.ts` (string `"false"` = off, everything else = on), mirroring `VITE_FEATURE_CODE_EXPLORER`/`VITE_FEATURE_TERMINAL_PANEL`. When off, `UiModeProvider` pins `'kanban'` and none of the new buttons render — Kanban stays byte-identical.
+- **i18n (`agent` namespace).** The `agent` namespace already exists (×8 locales). Add keys for the new surfaces: `switchToAgentMode`/`switchToKanbanMode`, `newAgent`, `search` (reuse `titleBar.searchShortcut`/`searchPlaceholder` from `nav.json` for the button label), the "On workspace" tool labels (`workspace.terminal`/`.files`/`.browser`), disabled-tooltip ("requires an active project"), the EMPTY-state "Plan, Build" copy, and Home-group label. **All 8 locales must mirror English** (locale-parity test enforces key tree + placeholders).
+- **WS events.** No new WS event types are strictly required for the shell swap (uiMode is client-local). Attachment parity may add attachment refs to the existing `agent_done`/message echo, or a new project-scoped-free (app-global, no `projectId`) event so non-initiating subscribers render user-turn attachments. Browser capture reuses the existing project-scoped browser WS. Terminal reuses the dedicated `/ws/terminal/:id`.
+- **Coverage / tests (per CLAUDE.md — server 80% lines/functions/statements + 70% branches, client 80% lines/statements + 70% functions, 70% global).**
+  - *Client:* `UiModeContext` (persistence, NOOP fallback), `AgentConversationView` (EMPTY vs ACTIVE from context, tier-cycle rebind, composer submit), `AgentModeSurface`, `AgentWorkspaceSidebar` (disabled gating), `ArcSidebar` agent-mode branch (grouping, expand state, click semantics, Home group), `CodePage` embedded/controlled mode (navigate suppression, URL-effect no-op), the [Search] dispatch. Attachment editor reuse is largely covered by existing Explore tests; add agent-composer wiring tests.
+  - *Server:* new agent attachment endpoints (upload/list/delete, 25MB cap, mime filter, traversal guard on `conversationId`), `AgentChatManager.sendMessage` prompt-fold (text blocks in, extraction-failure degrades to text-only), agent-scoped storage root, conversation-delete cleanup, and (if added) `ai_invocations` recording.
+  - Structurally-unreachable Tauri-only paths may be excluded with an inline documented reason (per policy), never to mask missing tests.
+
+---
+
+## 10. Consolidated RISKS + numbered OPEN DECISIONS
+
+### RISKS (deduped across slices, most-load-bearing first)
+
+1. **Double-mount of the terminal (single-adopter invariant).** If `BottomPanel` is hoisted to `DesktopApp` but `ProjectLayout` still renders its own copy (ProjectLayout:124-133) in Kanban, TWO `TerminalViewport`s fight over the same active container in `#specrails-terminal-host` — the second `appendChild` steals the node, the first's cleanup moves it back → flicker/blank terminal. The ProjectLayout copy **must** be removed.
+2. **CodePage's hardcoded `navigate({pathname:'/code'})` (CodePage:133,140,147,159).** Embedded without neutralizing these, any file/filter click routes the whole app to `/code` and pops the user out of Agent Mode. Highest CodePage coupling. Paired risk: the searchParams source-of-truth effect (:71-75) would force-reset `relPath` on every non-`/code` search change unless gated by `embedded`.
+3. **Hoisting `BottomPanel`/`StatusBar` risks Kanban layout regressions.** `StatusBar` needs `connectionStatus` from `usePipeline()` (ProjectLayout:25) — verify it works at DesktopApp scope. The `viewportHeight`/`STATUSBAR_HEIGHT_PX` maximize math depends on the panel's container height and whether a StatusBar exists; wrong values overshoot/undershoot maximize. Kanban must render exactly as today.
+4. **Images silently no-op on codex/gemini.** `@<abs-path>` is literal text to them; users will believe the image was seen. Needs per-provider UX gating. Also `getClaudeArgs` `@path` refs only resolve if the agent CLI spawn has read access to the agent attachments dir — confirm cwd/permissions parity with the chat spawn.
+5. **Agent attachment storage has no natural home / lifecycle.** Agent conversations are app-global (no slug); the `projects/<slug>/attachments/<ticketKey>` convention doesn't fit and a synthetic slug risks collision. An unpinned "Home" conversation has no project at all. Agent convos never become tickets, so there's no migration/permanence path, and `deleteAgentConversation` doesn't clean up files today.
+6. **`AgentChatContext` has no public `refreshConversations`** (only `open()`/`toggle()` refresh, :193,204) — the sidebar project tree can show a stale/empty list on mode entry; and `selectConversation` only loads the thread (doesn't set visibility/uiMode), so sidebar clicks need new coordination.
+7. **`AgentProjectSelector` lives in the panel header (chrome).** Naive extraction of only the inner subtree drops the project selector from Agent Mode — it must be re-homed into the composer/empty-state.
+8. **Center-as-route assumption breaks in Agent Mode.** `useProjectRouteMemory` (App.tsx:166) and `/code`/`/jobs` routes don't mount; route memory must still restore correctly on switching back to Kanban.
+9. **`ProjectItem` onClick split** (chevron-toggle vs row-activate) risks breaking keyboard handling (`handleSelectKeyDown` :57-61) and the remove-confirm `stopPropagation` flow (:88-101); nested interactives need a11y care.
+10. **Prompt bloat / argv limits.** Folding large extracted PDF/xlsx text into one argv prompt can hit OS `E2BIG`; same exposure as ChatManager but worth noting.
+
+### OPEN DECISIONS (the human must resolve these before implementation — this is the next phase)
+
+1. **Do global routes `/loops` and `/docs` (App.tsx:263-269) still function in Agent Mode, or is the entire center replaced by `AgentModeSurface` regardless of URL?** Determines whether the `uiMode` branch wraps only the project-route block or the whole `<Routes>`.
+2. **Is `BottomPanel`+`StatusBar` truly hoisted to `DesktopApp` (single instance, both modes) or duplicated into `AgentModeSurface`?** Hoisting is cleaner but edits `ProjectLayout`; confirm the acceptable refactor scope. (Recommendation across slices: single hoisted instance.)
+3. **Is there any footer/StatusBar in Agent Mode at all?** If not, `statusBarHeight` passed to `BottomPanel` is 0 and the terminal chevron entry point lives solely in the right sidebar.
+4. **Where does the terminal render vertically in Agent Mode** — under the agent center only, or spanning full width beneath both the agent surface and the `AgentWorkspaceSidebar`? (Today's BottomPanel spans only the routed main column.)
+5. **Can Agent Mode be entered with no active project (Home group only), or does the toggle force an active project?** Affects `activeProject` gating on `AgentWorkspaceSidebar` and the hoisted `BottomPanel`.
+6. **When switching Kanban→Agent while the panel is `restored`/`maximized`, does it stay open (same session) or auto-hide?** And is the sidebar Terminal button open-only (`setVisibility('restored')`) or a toggle (`togglePanel`)?
+7. **Does entering Agent Mode call `open()` (mounts the now-suppressed floating panel) or a new lighter `refreshConversations`?** (Recommendation: expose a standalone refresh.)
+8. **Does `[New agent]` pin to the currently-active project or always create a Home (null) conversation?** And does `newConversation` gain an explicit `projectId` param, or read `useDesktop` internally? (Recommendation: explicit arg keeps the context decoupled from routing.)
+9. **Persistence key + shape for per-project tree expansion** (Set vs Record) and default (expand active only vs expand all vs remember last).
+10. **In Agent Mode, does a project-row click with zero conversations still toggle (empty group) or only set active?**
+11. **Does the inline EMPTY state reuse the exact ACTIVE composer (variant-driven layout) or a dedicated "Plan, Build" card variant?** (Recommendation: same composer, variant layout, to guarantee attachment parity.)
+12. **Where do provider/model/tier controls + the project/Home indicator live in Agent Mode** — inside the composer row (as today) or a header strip?
+13. **When entering Agent Mode with an existing active conversation, show ACTIVE immediately or reset to EMPTY?** (`active` persists across mode toggles.)
+14. **Files: split vs full-replace when opened.** (Recommendation: SPLIT — thread + collapsible code pane — since the workflow is "chat while inspecting code"; confirm nested-split min-width math fits `MIN_MAIN_WIDTH=520`+`MIN_TREE_WIDTH=240`.)
+15. **Where does code selection persist** — per-conversation (reopen where left off) or per session — and is it context-state only (design keeps Agent Mode off `/code`) or also reflected as a shareable query param?
+16. **Does the embedded Files pane keep the provenance toolbar/filters (jobId/ticketId), or a stripped tree+viewer?** (Provenance filters are URL-driven today; keeping them needs the same controlled-state treatment.)
+17. **Does `[Search]` open the same generic palette (projects/commands/jobs/nav) or a scoped agent-conversation search?** (Recommendation: reuse generic palette for v1.)
+18. **Agent attachment storage key scheme:** distinct root `~/.specrails/agent/<conversationId>/attachments/` (recommended) vs reusing `AttachmentManager` with a synthetic slug/ticketKey.
+19. **What backs attachment storage for unpinned "Home" conversations with no active/pinned project** — is an active project mandatory to attach, or do we introduce app-global attachment storage?
+20. **Do agent turns persist their attachment id list** (new migration on `agent_messages` / new table) so historical turns re-render pills, or is display-on-send enough (folded into prompt only)?
+21. **Do we meter agent turns in `ai_invocations` now** (none today) or keep agent unmetered and only fold attachments?
+22. **Images on codex/gemini:** block/disable image attachments for non-claude providers, or attempt native image flags? What parity bar is acceptable for v1?
+23. **Does the agent composer replicate the auto-send-capture-feedback behavior (`sendCaptureFeedback`)** or only queue captures as chips that ride the next manual message?
+24. **Are the 25MB per-file cap and `ATTACHMENT_ACCEPT_MIME` allowlist acceptable unchanged for agent mode**, or does agent mode want different limits/types?
+25. **Attachment transport at send:** pre-upload then pass ids (Explore model, recommended for streaming compat) vs multipart on the send call itself.
+
+---
+
+## 11. RESOLVED DECISIONS (human sign-off, 2026-07-01)
+
+The 25 open decisions are resolved as follows. The 4 taste-forks were decided by the human; the rest take the recommended defaults.
+
+**Human-decided forks:**
+- **D1 → Loops/Docs STAY in Agent Mode.** The center branch is `isInSetup ? Wizard : (location==='/loops'||'/docs') ? <Routes> : uiMode==='agent' ? <AgentModeSurface/> : <Routes>`. Global routes render in the center without leaving Agent Mode; only project-route/dashboard content is replaced by the agent surface.
+- **D14 → Files = SPLIT (Cursor-style).** Thread stays visible; `CodePage` opens in a resizable secondary pane beside it, with a maximize toggle to widen the code pane (Cursor behaviour). Honour `MIN_MAIN_WIDTH=520`+`MIN_TREE_WIDTH=240`.
+- **D5 → Agent Mode CAN be entered with no active project.** Home-group (null-pinned) conversations are first-class. `AgentWorkspaceSidebar` Browser/Terminal/Files are disabled until a project is active; **file/paste/drag attachments still work** (they are conversation-keyed, project-independent). Only Browser-capture requires an active project (sessions are project-scoped).
+- **D22 → Images: NATIVE FLAGS, verified against real binaries (2026-07-01).** Empirical `--help` check on the installed CLIs:
+  - **codex-cli 0.141.0 → `-i, --image <FILE>...`** (present on both `codex` and `codex exec`). Wire this into `buildCodexArgs` (codex-adapter:75) — real native image support.
+  - **claude 2.1.197 →** images via `@<abs-path>` in the prompt, resolved natively (unchanged).
+  - **gemini 0.49.0 → NO dedicated image flag** (`-i` is `--prompt-interactive`). Relies on `@path` in-prompt injection (already emitted by `getClaudeArgs`); the Gemini model is multimodal so it *may* vision-load it under `-p`, but this is **UNVERIFIED** and must be smoke-tested live during implementation. Fallback: if it doesn't load, images degrade to claude+codex only and are disabled in the composer for gemini convos.
+  - **Contract:** add `supportsImageInput` to `ProviderCapabilities` (types.ts:91-120) and gate the composer's image affordance on the flag (never on `provider === id`). Add a new image-paths field on `SpawnOptions` threaded through `buildCodexArgs` (emits `--image`); claude/gemini keep the `@path` route.
+
+**Default-resolved:**
+- **D2/D3 →** Single hoisted `BottomPanel`+`StatusBar` in `DesktopApp` (remove ProjectLayout copy). StatusBar exists in both modes (maximize math needs its height); footer chevron gated to `uiMode==='kanban'`.
+- **D4 →** Terminal spans full width beneath surface + `AgentWorkspaceSidebar`.
+- **D6 →** Entering Agent Mode does NOT auto-hide an open panel. Sidebar Terminal button = `togglePanel(activeProjectId)`.
+- **D7 →** Expose a standalone `refreshConversations` (do NOT call `open()`).
+- **D8 →** `newConversation(projectId?)` explicit arg; `[New agent]` defaults the pin to `activeProjectId` (null ⇒ Home).
+- **D9 →** Expansion state = `Set<string>` in localStorage `specrails-desktop:agentTreeExpanded`, default-expand the active project.
+- **D10 →** Project-row click always sets active + toggles expand (even with zero conversations).
+- **D11 →** EMPTY reuses the ACTIVE composer via `variant` layout (guarantees attachment parity), styled as the centered "Plan, Build" card.
+- **D12 →** provider/model/tier + project/Home indicator stay in the composer row.
+- **D13 →** Entering Agent Mode with an existing `active` shows ACTIVE immediately.
+- **D15/D16 →** Code selection persists per-conversation in Agent-Mode context state (NOT the URL); embedded Files pane keeps the provenance toolbar/filters (controlled-state, not URL-driven).
+- **D17 →** `[Search]` reuses the generic CommandPalette (synthetic Cmd+K dispatch) for v1.
+- **D18/D19 →** Distinct storage root `~/.specrails/agent/<conversationId>/attachments/`; attachments are conversation-keyed and work for Home convos with no project.
+- **D20 →** Persist the attachment id list per turn (new nullable `attachments` JSON column on `agent_messages`) so history re-renders pills.
+- **D21 →** METER agent turns in `ai_invocations` now (`surface='agent'` or similar), for Analytics coherence.
+- **D23 →** Agent composer queues captures as chips that ride the next manual message (no auto-send-feedback in v1).
+- **D24 →** Keep 25MB cap + `ATTACHMENT_ACCEPT_MIME` allowlist unchanged.
+- **D25 →** Pre-upload then pass ids (streaming-compatible).

package/docs/internals/visual-design-audit.md

@@ -0,0 +1,184 @@
+# Specrails Desktop — Design Synthesis (Visual System · Mechanical Fixes · Rails Redesign)
+
+Verified against working tree: `client/package.json` has no animate plugin; `globals.css:64` = `--radius: 0.75rem`; `RailRow.tsx:289` shadow uses undefined `--accent-info`; `glow-*` utilities exist at `globals.css:345-350`; 175 `aurora-light:` dual-class sites.
+
+---
+
+# PART 1 — VISUAL SYSTEM
+
+The canon below is the **majority-existing code**, promoted to law. Reference implementations: **AnalyticsPage** (layout/cards/type), **agent-chat family** (motion/glass/tokens), **Add Spec + StatusBar** (token hygiene). Nothing here invents a new aesthetic; it deletes the two losing dialects (raw-palette+`aurora-light:` forks, dracula literals) and keeps the winning one.
+
+## 1.1 Color: one token dialect
+- **Only semantic tokens.** `accent-primary` (brand/AI/specs) · `accent-secondary` (rails) · `accent-info` (running/live/links/inline-code) · `accent-success` (done/go) · `accent-warning` (cost/caution) · `accent-highlight` (explore) · `destructive` (error/delete) · `muted`/`muted-foreground` (inactive). The 175-site `text-blue-400 aurora-light:text-accent-info` idiom collapses to the token alone — the token is already themed for all five themes.
+- **Text on accent backgrounds = `text-background`** (the `SetupWizard.tsx:550` pattern), never `text-white`. On `bg-primary`/`bg-destructive` use their `-foreground` pair.
+- **Glows** only via the existing utilities `glow-primary/-secondary/-info/-success/-warning/-highlight` (`globals.css:345-350`) or the `color-mix(in srgb, var(--color-accent-*) N%, transparent)` form. `hsl(var(--accent-*)/N)` is INVALID (tokens are `--color-*` holding complete `hsl()` values) — it silently renders nothing.
+- **Status mapping (frozen):** running = `accent-info` + `Loader2` spin · success = `accent-success` + `CheckCircle2` · failed = `destructive` + `XCircle` · canceled/queued = `muted` + `Ban` · warning/cost = `accent-warning` + `AlertTriangle`/`DollarSign`.
+- **Priority canon** (the ProposeSpecModal set — the only fully tokenized one): critical=`destructive`, high=`accent-warning`, medium=`accent-info`, low=`muted`.
+- **Left sidebar title = accent-primary, right sidebars = accent-secondary** (existing rule; document, keep).
+
+## 1.2 Icon scale (lucide, `w-N h-N` pair idiom — never `size={}` props)
+| Context | Size | Margin |
+|---|---|---|
+| Nav rows, page/dialog headers, icon-buttons ≥ h-8, palette rows | `w-4 h-4` | `mr-2` |
+| Dense rows, `size="sm"` button leading icons, toolbars, settings headings | `w-3.5 h-3.5` | `mr-1.5` |
+| Chips/badges/breadcrumbs/`h-7` buttons/select chevrons (ui/select `w-3` is the codified convention) | `w-3 h-3` | `mr-1` |
+| Micro close/status inside pills & tab strips | `w-2.5 h-2.5` | — |
+| Step/hero icons | `w-6 h-6` | — |
+| Page-level empty-state pictograms (`w-6` for narrow panels) | `w-8 h-8` | — |
+Chevron next to a row icon = one tier below the row icon. Stroke = lucide default 2 (exceptions: TitleBar window controls, PanelChevronButton). **No emoji, no text glyphs (`×`, `↺`, `✓`, `+`) where a lucide icon exists** — `kbd` glyphs (`⌘⇧↵`) exempt.
+
+## 1.3 Lines, radius, shadow (three-stop border system)
+Prereq: delete/rename `--radius: 0.75rem` (`globals.css:64`) so bare `rounded` stops meaning 12px; raise `[data-theme="specrails"] --color-border` from `/0.11` to `~/0.16` for modifier headroom. Sanctioned opacity stops: **full, `/60`, `/40`, `/50` (cards only)**. Kill list: `/10 /20 /25 /70`, `shadow-black/*`, raw `rgba()`/`hsl()` shadow literals, bare `border` without color, `ring-1 ring-border` as pseudo-border.
+| Tier | Recipe |
+|---|---|
+| App-frame chrome hairline (sidebars, title/status bar, pane splits, board headers) | `border-border` (full — the token IS the hairline) |
+| Inset divider (rows inside cards/modals, `divide-*`) | `border-border/40` |
+| Page block card | `rounded-xl border border-border/50 bg-card/40 p-4` (hero: `p-5 bg-gradient-to-br from-card/80 to-card/40`) |
+| Row card | `rounded-lg border-border/40 bg-card/60 hover:border-border/60` |
+| Menu/popover | `rounded-lg border-border/60 bg-popover/95 backdrop-blur-md shadow-xl` |
+| Tooltip | `rounded-md border-border shadow-md` (as-is) |
+| Centered modal | `rounded-xl border-border/40 bg-popover shadow-2xl backdrop-blur-md` |
+| Floating glass (agent bubble/panel, dock) | `rounded-2xl border-border/60 bg-card/90 shadow-2xl backdrop-blur-xl` |
+| Form controls | `rounded-md` (input/button/select trigger all match) |
+| Focus | `focus-visible:ring-2 focus-visible:ring-ring` everywhere |
+| Scrims | standard `bg-black/60 backdrop-blur-sm`; immersive (lightbox/onboarding) `bg-black/80 backdrop-blur-md` |
+
+## 1.4 Motion vocabulary
+Prereq (fix #1): `npm i tw-animate-css` + `@import "tw-animate-css";` in `globals.css` — resurrects the ~22 authored-but-dead `animate-in/out` surfaces.
+- **150ms micro** — hover colors, opacity, chevron rotate, overlay fades. Bare `transition-colors` (default duration).
+- **200ms structural-small** — modal/popover/tooltip enter: `animate-in fade-in-0 zoom-in-95 duration-200`, exit via `data-[state=closed]:animate-out`.
+- **250–300ms structural-large** — panel slides (terminal, sidebars), height disclosures (`grid-template-rows 0fr→1fr` trick), `ease-out`.
+- **400–500ms ambient** — progress bars, status frames only.
+- **Easings:** enters `ease-out`; house arrival overshoot `cubic-bezier(0.34,1.56,0.64,1)` registered once as `--ease-arrive` in `@theme`, reserved for floating-object arrival (chat panel, chips, swipe snap-back); springs `stiffness 350–420 / damping 28–34` for layout morphs (AgentModeSurface/AgentBubble values).
+- **Morph vs fade:** `layoutId` spring when the SAME object persists (chip⇄panel, tab underline, kanban cross-column); fade+zoom for transient surfaces. Never `transition-all` on size-changing containers (use `transition-[width]` etc.).
+- **Reduced motion:** one `<MotionConfig reducedMotion="user">` at app root; `motion-safe:` on decorative loops; global `prefers-reduced-motion` clamp in `globals.css` with `.motion-keep` escape for spinners.
+
+## 1.5 Spacing & type rhythm
+- Page gutter `px-6`; scrolling pages `py-6`; full-height pages: header `px-6 pt-4 pb-3 border-b border-border`.
+- Three container archetypes: **workspace** full-bleed (Dashboard, Code, LoopBuilder) · **data page** `max-w-6xl mx-auto w-full` (Analytics, Jobs, JobDetail, Loops) · **reading/forms** `max-w-3xl` (Settings, Docs).
+- Section gap `gap-6`/`space-y-6`; heading→content `space-y-2`.
+- Two sanctioned header voices: **page header** `h1 text-lg font-semibold` + `text-xs text-muted-foreground mt-0.5` subtitle; **workspace pane header** `px-4 h-12 border-b border-border/40` + `text-sm font-semibold` tinted h2 (SpecsBoard/RailsBoard form). No third variant.
+- Type scale: kicker `text-xs font-semibold uppercase tracking-wider text-muted-foreground` · card title `text-sm font-semibold` · body `text-sm` · metadata `text-xs` · dense-chrome floor `text-[11px]` · badge floor `text-[10px]` (**`text-[9px]` banned**) · display numbers `text-5xl font-semibold tabular-nums tracking-tight`, heroes only.
+- Contrast floor: never below `text-muted-foreground/50` under 12px. Interactive elements never below `text-[11px]`, native form controls never below `h-7 text-xs`.
+- One shared `<EmptyState icon title description action?>` (RecentJobs pattern: dashed card, `w-8 h-8 opacity-20` icon, `text-sm font-medium` title, `text-xs text-muted-foreground/60` hint, `py-12`).
+
+## 1.6 Concept → icon + accent (canonical)
+| Concept | Icon | Accent |
+|---|---|---|
+| Spec/ticket entity | `Ticket` | accent-primary |
+| Rails / execution lane | `Layers` (exclusive — epic filter → `FolderTree`, batch → `ListChecks`) | accent-secondary |
+| Job | `Briefcase` | accent-info |
+| Job running / in-flight action | `Loader2` spin | accent-info |
+| Job success | `CheckCircle2` | accent-success |
+| Job failed | `XCircle` | destructive |
+| Job canceled | `Ban` | muted-foreground |
+| App agent (chat/mode) | `Bot` | accent-primary |
+| Pipeline agents/profiles | `BrainCircuit` | accent-primary |
+| MCP | `Plug` | accent-info |
+| AI generate/magic | `Sparkles` | accent-primary (one tint) |
+| Explore | `MessagesSquare` | accent-highlight |
+| Quick spec | `Zap` | accent-secondary |
+| Sidebar chat / comments | `MessageSquare` / `MessageSquareText` | accent-primary |
+| Project analytics / Desktop analytics | `BarChart3` / `PieChart` | neutral |
+| Docs / Code / Terminal / Loops | `BookOpen` / `Code2` / `Terminal` / `Workflow` | neutral |
+| Cost | `DollarSign` | accent-warning |
+| Refresh data / retry op / browser reload | `RefreshCw` / `RotateCcw` / `RotateCw` | — |
+| Send | `Send w-3.5` | — |
+| Provider | `Cpu` (kill the `🤖⚡✨` emoji) | neutral |
+
+**Regression guards (CI grep-deny, extends the existing `dracula-*` guard):** `aurora-light:` outside globals.css · `#50fa7b|#ff5555|#f1fa8c|#6272a4|#44475a|rgba\(139,233|rgba\(189,147` · `text-white` on `bg-accent`/`bg-emerald`/`bg-green` lines · `hsl\(var\(--` · `border-border/(10|20|25|70)` · `shadow-black/` · `text-\[9px\]` · bare `rounded[" ]` (post-codemod).
+
+---
+
+# PART 2 — MECHANICAL FIX LIST (top 40, deduplicated, ranked by visibility)
+
+1. `client/package.json` + `client/src/globals.css:2` — missing animate plugin → `npm i tw-animate-css` + `@import "tw-animate-css";`. Single change lights up ~22 dead surfaces (dialog.tsx:31/75/98, select.tsx:66, tooltip.tsx:17, TicketDetailModal:338, ExploreSpecShell:768, JobDetailModal:190, lightbox, AiEditShell:179, ProposeSpecModal:451, SmashConfirmModal:73, OnboardingWizard:725/732). Highest ROI line in the entire audit.
+2. `client/src/globals.css:64` — `--radius: 0.75rem;` → delete (nothing consumes it; it hijacks bare `rounded` to 12px, inverting the radius scale at 254 sites). Follow with codemod: bare `rounded` → `rounded-sm` (chips/kbd) / `rounded-md` (controls).
+3. `components/ui/badge.tsx:14-20` — raw `bg-emerald-500/20 … aurora-light:*` pairs → semantic alone: `success: bg-accent-success/15 text-accent-success border-accent-success/30`, `running: …accent-info…`, `warning: …accent-warning…`, `failed: …destructive…`, `queued/canceled: bg-muted text-muted-foreground border-border`. The shared status primitive — every job/status chip inherits.
+4. `components/RailRow.tsx:289,310,312,530` — invalid `shadow-[…hsl(var(--accent-info)/0.35)…]` (never rendered) → `glow-info` utility or `color-mix(in_srgb,var(--color-accent-info)_35%,transparent)` form; `:554` delete the duplicate hardcoded dot `bg-emerald-400 shadow-[0_0_4px_hsl(142_70%_56%/0.8)]` → `bg-accent-success` + fixed :310 shadow.
+5. `components/CommandGrid.tsx:32-86` — dracula rgba glow literals → `hover:glow-info hover:border-accent-info/50` (map per card accent); `:225/:227` — `Zap w-3.5` → `w-4 h-4` to match sibling ArrowRight.
+6. `components/ProjectHealthWidget.tsx:51,92,110-124,141` + `components/HealthIndicatorBadge.tsx:28-31` — `#50fa7b/#f1fa8c/#ff5555` → `text-accent-success/text-accent-warning/text-destructive` (`var(--color-*)` for Recharts fills); ProjectHealthWidget:124 `AlertCircle` → `Ban`.
+7. `components/terminal/TerminalSearchOverlay.tsx:94,105-138` — `#f8f8f2/#6272a4/#44475a` → `text-foreground/bg-accent-primary/40/bg-muted`; `:107,115,126` `size={14}` → `className="w-3.5 h-3.5"`.
+8. `types/context-scope.ts:51-54` — `text-white` ×4 in `submitAccentForTier` → `text-background` (white on pastel accent-warning is unreadable).
+9. `components/UltracodeLaunchDialog.tsx:91` — `bg-emerald-500 text-white hover:bg-emerald-400 focus-visible:ring-emerald-400` → `bg-accent-success text-background hover:bg-accent-success/90 focus-visible:ring-accent-success`; `:58` `h-4.5 w-4.5` → `h-4 w-4` (only off-scale icon in the app).
+10. `components/RailControls.tsx:78-85` — raw red/emerald/amber + `aurora-light:` → `text-destructive/text-accent-success/text-accent-warning`; `:42` `hsl(191_97%_77%/0.22)` → `color-mix(in srgb, var(--color-accent-info) 22%, transparent)`; `:88` add `disabled:opacity-40`; bump button `h-5 w-5`→`h-7 w-7`, icon `w-2.5`→`w-3.5`.
+11. `components/RailsBoard.tsx:167` — `text-emerald-400 bg-emerald-400/10` → `text-accent-success bg-accent-success/10`.
+12. `components/ActiveJobCard.tsx:78,83` — `border-blue-500/30 bg-blue-500/5` / `text-blue-400` → `border-accent-info/30 bg-accent-info/5` / `text-accent-info` (copy JobStatusPanel:189).
+13. `components/JobStatusPanel.tsx:191-199` — success/fail frame raw → `border-accent-success/30 bg-accent-success/5 text-accent-success` / destructive set; `:219,317,342` `text-yellow-400` → `text-accent-warning`; `:365` `text-cyan-400/80` → `text-accent-info`; `:423,447,450` `text-muted-foreground/30` → `/50`.
+14. `components/PipelineProgress.tsx:34-87` — all phase-state raw palette → `accent-info` (running) / `accent-success` (done) / `destructive` (failed).
+15. `components/TicketStatusIndicator.tsx:33-47,138-140` — raw status dots/chips → tokens per §1.1 status map.
+16. `components/Navbar.tsx:38-43` — connection pill raw blue/orange/green/red → `accent-info/accent-warning/accent-success/destructive`.
+17. `pages/AnalyticsPage.tsx:413-417` — load-failure banner `accent-warning` → `border-destructive/30 bg-destructive/10 text-destructive` (errors are destructive, app-wide).
+18. `components/analytics/SpendingTimeline.tsx:82` — smash series `var(--color-accent-highlight)` (duplicates explore) → `var(--color-accent-secondary)`.
+19. Scrim normalization — `JobDetailModal.tsx:183` `black/50`→`black/60 backdrop-blur-sm`; `ai-edit/AiEditShell.tsx:179` `black/40`→`black/60`; `TicketDetailModal.tsx:798` + `SplitViewShell.tsx:177` `black/70` (no blur)→`black/60 backdrop-blur-sm`; `OnboardingWizard.tsx:725` + `AttachmentPreviewLightbox.tsx:74` → `black/80 backdrop-blur-md`.
+20. `components/ui/dialog.tsx:75,98` — `border-border/30 … shadow-xl` → `border-border/40 … shadow-2xl` (base dialog currently weaker than its own flagship children).
+21. `components/ui/select.tsx:17` — SelectTrigger `rounded-lg` → `rounded-md` (matches input/button); `:24` add `transition-transform duration-150 group-data-[state=open]:rotate-180` to chevron.
+22. `components/ui/card.tsx:9` — append `transition-colors` (consumers adding `hover:border-*` currently snap).
+23. `components/CommandPalette.tsx:141` — `border-border/30` → `border-border/40`; after fix #1, append `animate-in fade-in-0 zoom-in-95 slide-in-from-top-2 duration-150 ease-out` + dimmed overlay `bg-black/50 backdrop-blur-sm`.
+24. `components/TicketDetailModal.tsx:337-338` — drop `shadow-black/50` (keep `shadow-2xl`); `:623` popover `rounded border-border/50 shadow-lg` → `rounded-lg border-border/60 shadow-xl`.
+25. App-frame hairline continuity — `components/StatusBar.tsx:84` `border-t border-border/30` → `border-border`; `components/ChatPanel.tsx:79,114,211,220` structural `/30` → full; `components/agent-chat/AgentModeCodePane.tsx:74` `/60` → full (sibling AgentWorkspaceSidebar:77 already full).
+26. `components/settings/TerminalSettingsSection.tsx:196,262` — bare `border` (renders `currentColor`, harsh) → add `border-input`; `:266` `border-t` → `border-t border-border`.
+27. Invisible dividers — `components/SpecComparePicker.tsx:96` `divide-border/10` → `/40`; `/20` hairlines at `RailRow.tsx:645`, `JobStatusPanel.tsx:237`, `JobComparisonModal.tsx:43`, `LogViewer.tsx`, `ChatInput.tsx`, `InstallInstructionsModal.tsx`, `TicketGridView.tsx` → `/40`; `RailRow.tsx:690` `/25` → `/40`; `pages/CodePage.tsx:292` `/70` → `/60`.
+28. Analytics skeleton/loaded border flash — `components/analytics/{CostScatter:43,ModelBreakdown:20,ProviderBreakdownCard:39,QuickVsExploreCard:93,SpendingHero:59,SpendingTimeline:13,TopTicketsCrossSurface:14}` skeleton `border-border/40` → `/50`.
+29. H1 normalization — `pages/JobsPage.tsx:95` `text-sm font-semibold` → `text-lg font-semibold`; `pages/AnalyticsPage.tsx:313` `text-base` → `text-lg`; `pages/DesktopAnalyticsPage.tsx:340` `text-sm` → `text-lg`; `pages/ActivityFeedPage.tsx:78` `text-sm font-medium` → `text-lg font-semibold`.
+30. Gutter normalization — `pages/SettingsPage.tsx:248` `max-w-2xl mx-auto px-4` → `max-w-3xl mx-auto px-6`; `pages/JobsPage.tsx:93` `max-w-4xl px-4` → `max-w-6xl px-6`; `pages/JobDetailPage.tsx:395,348,360` `px-4` → `px-6`; `pages/AnalyticsPage.tsx:308-310` `p-4 pb-12`/`-mx-4 px-4` → `px-6 pt-6 pb-12`/`-mx-6 px-6`.
+31. `text-[9px]` purge → `text-[10px]`: `SpecCard.tsx:153-224` (or delete override, Badge base is 10px), `TicketPostitCard.tsx:244-286`, `TicketGridView.tsx:185-239`, `TicketListView.tsx:351-383`, `RecentJobs.tsx:368,377`, `DesktopAnalyticsPage.tsx:207`, `RailRow.tsx:600` (+ `tabular-nums`).
+32. 10px interactive controls — `TicketListView.tsx:218,234` `text-[10px]` → `text-[11px]`; `:251,266` `h-6 text-[10px]` → `h-7 text-xs`; `RecentJobs.tsx:200,216,283-292` → `text-[11px]`, `:233,240` → `h-7 text-xs`; `GlobalSettingsPage.tsx:554,643` checkbox labels → `text-xs`, `:438-681` descriptions `text-[10px]` → `text-[11px]`.
+33. `components/RailRow.tsx:693` — empty state `text-[10px] text-muted-foreground/30` + `border-border/25` → `text-[11px] text-muted-foreground/60` + `border-border/40` (the surface's main onboarding cue fails contrast).
+34. Destructive-red sweep — `SpecCard.tsx:235`, `RailRow.tsx:510,613-620`, `agents/PromptDialog.tsx:120` `bg-red-500 text-white hover:bg-red-600` → `bg-destructive text-destructive-foreground hover:bg-destructive/90`; `TicketGridView.tsx:495` `bg-red-950/10` → `bg-destructive/10`; `JobComparisonModal.tsx:90` `text-rose-400` → `text-destructive`.
+35. `text-white` sweep → `text-background` (or `-foreground` pair): `ProposeSpecModal.tsx:661`, `App.tsx:466`, `agent-chat/AgentComposer.tsx:267`, `AgentConversationView.tsx:69`, `jira/JiraIntegrationCard.tsx:93`, `ai-edit/AiEditShell.tsx:904`, `ChatPanel.tsx:86`, `LoopsPage.tsx:325`, `LoopBuilderPage.tsx:429`, `IntegrationsPage.tsx:255,632,676`; `FeatureProposalModal.tsx:259,272` `bg-green-600` → `bg-accent-success text-background`, `:314` `CheckCircle` → `CheckCircle2 text-accent-success`.
+36. Icon one-liners — `ArcSidebar.tsx:385` BarChart2→PieChart; `DesktopAnalyticsPage.tsx:339` TrendingUp→PieChart; `CommandPalette.tsx:261` FileText→BookOpen; `ActivityFeedPage.tsx:30` Zap→Loader2; `RecentJobs.tsx:183` ClipboardList→Briefcase; `AgentWorkspaceSidebar.tsx:3` TerminalSquare→Terminal + FileCode2→Code2; `GlobalSettingsPage.tsx:13` TerminalSquare→Terminal; `SetupWizard.tsx:451` Bot→Plug; `CodePage.tsx:4` RotateCw→RefreshCw.
+37. Markdown/code accent unification → `accent-info`: `ExploreSpecShell.tsx:1236-1240` (accent-primary→info), `SetupChat.tsx:13` + `TicketDetailModal.tsx:1040,1055` + `LogViewer.tsx:446,449` (cyan-300/blue-400→`text-accent-info`), `JobsPage.tsx:127` `prose-code:text-cyan-300` → `prose-code:text-accent-info`; Sparkles tint: `ProposeSpecModal.tsx:405`, `SpecDraftPanel.tsx:39`, `AiEditComposer.tsx:63` `text-primary/70` → `text-accent-primary`.
+38. Motion micro — terminal `duration-120` delete (`PanelChevronButton.tsx:32`, `TerminalSidebar.tsx:92,129,145`, `TerminalDragHandle.tsx:86`, `TerminalTopBar.tsx:126`); `ArcSidebar.tsx:401` + `ProjectRightSidebar.tsx:58` `transition-all` → `transition-[width]`; `SpecCard.tsx:124` + `RailRow.tsx:295,527` `animate-jiggle` → `motion-safe:animate-jiggle`; `RailRow.tsx:535` snap-back curve → `cubic-bezier(0.34,1.56,0.64,1)`.
+39. Reduced-motion consolidation — wrap the agent-chat portal root in `context/AgentChatContext.tsx` with one `<MotionConfig reducedMotion="user">`, delete the local one at `AgentModeSurface.tsx:41`; add the global `prefers-reduced-motion` clamp to `globals.css`.
+40. Glyph → lucide — `AddProjectDialog.tsx:284` `'✓'` → `<Check className="w-2.5 h-2.5"/>`; `ChatHeader.tsx:51` `'+'` → `<Plus className="h-3.5 w-3.5"/>`, `:61-100` four hand-rolled SVGs → `Trash2/Minimize2/Maximize2/X` `h-3.5`; `ModelSelector.tsx:211` `'↺'` → `<RotateCcw className="w-3 h-3"/>`; `×` dismissals (`ProposeSpecModal.tsx:527`, `ChatPanel.tsx:140`, `AttachmentChip.tsx:86`, `AttachmentsSection.tsx:140`, `AnalyticsPage.tsx:332`) → `<X className="w-3 h-3"/>`; `SpecsBoard.tsx:693` done-bucket drag tint `bg-emerald-500/[0.04] aurora-light:*` → `bg-accent-success/[0.06]`; `DashboardPage.tsx:1047` ghost `border-primary/40` → `border-accent-info/40`.
+
+Deferred to a dedicated bulk change (mechanical but broad): the remaining ~40-file `aurora-light:` fork sweep (S1), `pages/AgentsPage.tsx:82-96` yellow banner, `TicketContextMenu`, `AiEditShell` body, `ActivityFeedPage` maps, kicker `font-medium→font-semibold` in 6 analytics files, `ui/card.tsx` recipe migration.
+
+---
+
+# PART 3 — RAILS REDESIGN PROPOSAL
+
+## 3.1 Diagnosis (one sentence)
+A single idle rail exposes **13 controls, six of them 10px native `<select>`s explained only by icon+`title`**, the primary action is the smallest target on the card (20px), a running rail is a **black box** (all config unmounts → layout jump; no loop/engine/model/phase shown), failure is **invisible after a 4s toast** (`RailStatus 'failed'` is dead code), and rail identity is three disagreeing coordinate systems (id-number vs array-index vs server-index) sitting on a localStorage/server split-brain.
+
+## 3.2 Target layout (normal density)
+
+```
+┌─ rail card ─ rounded-xl border-border/40 bg-card/60 ─────────────────┐
+│ ⠿  ●  Backend refactor            2 specs      [▶ Run]  [⋮]         │  header h-9
+│ ─────────────────────────────────────────────── border-border/40 ── │
+│   #142  Fix auth token refresh                     ▲ high           │  droppable body
+│   #147  Add rate limiter                           ■ med            │  (SpecCard rows)
+│ ─────────────────────────────────────────────────────────────────── │
+│   Implement · Claude · Sonnet · balanced · normal effort        ⌄   │  config summary
+└──────────────────────────────────────────────────────────────────── ┘
+```
+
+- **Header:** grip (`GripVertical w-3.5 text-muted-foreground/30`) · status dot **`w-2 h-2`** (up from 6px; `bg-accent-success glow-success` running, `bg-destructive` failed, `bg-muted-foreground/25` idle) · free-form name (kill the forced `"Rail "` prefix wrapper at `DashboardPage.tsx:325`; server already models name-or-null) · ticket count `text-[10px] tabular-nums bg-muted/40` · **`[▶ Run]` = `h-7` labeled button** (`text-accent-success`, `w-3.5` icon — no longer a 20px ghost) · **`[⋮]` kebab** (Radix DropdownMenu, menu-tier recipe): Rename / Duplicate / Move all to Specs / Delete (`text-destructive`). Kebab replaces the undiscoverable 800ms long-press-jiggle on desktop; jiggle+swipe stay for touch.
+- **Config summary strip (the key consolidation):** the six micro-selects collapse into **one readable sentence of chips** — `<Loop> · <Engine> · <Model> · <Profile> · <Effort>` at `text-[11px]`, each chip a real `ui/tooltip.tsx`-labeled target. Clicking any chip (or `⌄`) opens **one config popover** (menu-tier recipe, `rounded-lg border-border/60 bg-popover/95 backdrop-blur-md shadow-xl`, grid-rows disclosure at 250ms) containing proper **labeled Radix `ui/select`s** — Loop, Engine, Model, Profile, Reasoning effort — plus the **Interactive switch** (moved here from the transport row; it is config, not transport). Visible controls per idle rail: **13 → 5** (grip, name, Run, kebab, config strip). All selector visibility rules (multi-provider, claude-only profile, mode-derived model/effort) survive unchanged inside the popover.
+- **Empty body:** `text-[11px] text-muted-foreground/60` on `border-border/40` dashed — "Drag specs here" finally visible.
+
+## 3.3 States and motion
+
+| State | Card | Config strip | Right slot | Motion |
+|---|---|---|---|---|
+| **idle** | `border-border/40` | chips, editable | `▶ Run` (disabled `opacity-40` at 0 tickets) | drop-hover: body `bg-accent-info/[0.06]` + card `border-accent-info/50 glow-info` — ONE accent for one interaction (kill the `primary` variant at RailRow:530) |
+| **running** | `border-accent-info/40` + **`glow-info`** (works once fix #4 lands) | **stays mounted**, `opacity-60 pointer-events-none` — no layout jump; chips show the resolved run (`loopName · provider · model` already returned by `rails-router.ts:86-105`, today thrown away) | `■ Stop` (`text-destructive`) + `Log` | below strip: live line `Loader2 w-3 animate-spin text-accent-info` + `elapsed · steps · lines` `text-[11px] tabular-nums`, plus **mini `PipelineProgress`** (compact variant of the existing component, fed by the same WS stream `RailMetricsContext` already consumes) with `AgentActivityChip`-style AnimatePresence crossfade on phase change |
+| **done** | 800ms `border-accent-success/50 glow-success` wash, then back to idle | re-enabled | `▶ Run` | persistent last-run line replaces the live line: `CheckCircle2 w-3 text-accent-success` `Shipped 3 specs · 12m · $0.84` until next config touch; completion toast uses the rail **label**, not "Rail {{n}}" |
+| **failed** | **persistent** `border-destructive/40` + dot `bg-destructive` (resurrect the dead `'failed'` status: `applyRailJobOutcome` at `RailsBoard.tsx:56-72` must set it — the `RailControls.tsx:81-98` retry affordance already exists, unreachable today) | re-enabled | `AlertTriangle` Retry + `Log` + dismiss-`X` | card does one `motion-safe` shake-in (4px, 300ms); state survives until retry/dismiss |
+
+**Stop guard:** Stop cancels N billed jobs — replace bare kill with a 5s undo toast (`ThemedToaster` action pattern, `App.tsx:434`) or a one-line confirm; no new component needed.
+
+## 3.4 Reused components (nothing new except one popover)
+`ui/select.tsx` + `ui/tooltip.tsx` + `ui/dropdown` primitives (Radix, already shipped) · `PipelineProgress` (add a `variant="mini"` — h-1.5 bar + phase label) · `Badge` (post fix #3, for ticket/status chips) · `AgentActivityChip` crossfade pattern (copy verbatim for phase/status text) · `glow-*` utilities (`globals.css:345-350`) · `TicketDetailModalProvider` (compact ticket-pill clicks, unchanged) · `MoveToRailPopover`, `UltracodeLaunchDialog` (kept as-is, minus emerald CTA per fix #9) · existing WS events + `GET /rails` enrichment (`activeLoopRuns.loopName/provider/model/iteration` — zero server work to show run identity) · shared `<EmptyState>` (new, but mandated app-wide by §1.5). Compact density is **retired as a separate design system**: it becomes the same card with the body collapsed — the compact branch is already the token-correct one, so normal density adopts its token language rather than maintaining two.
+
+## 3.5 Phased plan
+
+**Phase 0 — identity + persistence prerequisite (structural bug fix, blocks everything).** Collapse the three coordinate systems: put the **server railIndex** on `RailState` as the single key; rename (`DashboardPage.tsx:329` `parseInt(railId)-1`), profile/engine/launch/stop (`:764,:820,:835` `findIndex`), and WS mirrors (`:362,:375,:404`) all route through it. Today, reordering/deleting a rail mis-routes PUTs and lights up the wrong card. Fix N+1 fetches by hoisting profile/loop fetches to `RailsBoard` (one fetch, pass down). Delete dead plumbing (`RailControls.tsx:31` `loopAvailable`/`onModeChange`, `DashboardPage.tsx:758-760`).
+
+**Phase 1 — cosmetic reskin (pure class/markup, ships independently).** All rails-touching mechanical fixes (#4, #9, #10, #11, #31, #33, #34, #38): working glow-info running border, token status dot at `w-2 h-2`, `h-7` labeled Run/Stop, 11px floor on selects/pills/empty state (`h-6 text-[11px]` interim on the native selects), one drop accent (accent-info), destructive-token delete affordances, icon on the loop-model select, toast copy uses rail label + translated loop name (`DashboardPage.tsx:938,407-412`). **Config strip stays mounted while running** (disabled, not unmounted) — kills the layout jump with zero structural change. Add the run-identity chips from the already-delivered `activeLoopRuns` payload.
+
+**Phase 2 — structural.** (a) **Rails fully server-side**: server already persists tickets/mode/profile/engine/name and broadcasts `rail.updated`; localStorage demotes to cache; lift the hardwired `[0,1,2]` (`rails-store.ts:59`) so rails 4+ exist for the mobile companion too. (b) **Config popover** replacing the six inline selects (the 13→5 consolidation above), Interactive as a switch inside it. (c) **Failed state wiring** end-to-end (`applyRailJobOutcome` → `'failed'`, retry/dismiss UI). (d) **Mini PipelineProgress + last-run summary line.** (e) **Kebab menu + Stop undo-toast + free-form names** (drop the `"Rail "` prefix contract, default label only when name is null). (f) Motion polish: spring arrival for added rails, FLIP (`motion` `layoutId`) for spec cards moving board⇄rail — same `LayoutGroup` work as the SpecsBoard cross-column fix, shared spring `{stiffness:350,damping:34}`.
+
+Acceptance for "premium": no text below 11px on the surface, one accent per interaction, running rail answers "what is running, with what, how far along" without leaving the dashboard, failure is visible until acknowledged, and every glow actually renders.

package/docs/mcp.md

@@ -154,10 +154,11 @@ bridge and connect to:
 http://127.0.0.1:4200/api/mcp
 ```
 
-with the scoped token as a bearer header:
+with the scoped token in either header form (both are accepted):
 
 ```
 Authorization: Bearer <your mcp token>
+X-Desktop-Token: <your mcp token>
 ```
 
 Get the token from **Settings ▸ MCP ▸ Copy token** (or read
@@ -167,6 +168,30 @@ HTTP-capable clients, not for exposing Specrails on a network. (`4200` is the
 default app port; if you've changed it, the panel's config reflects the real
 one.)
 
+#### One-liners for the common CLIs
+
+**Claude Code** (HTTP transport):
+
+```bash
+claude mcp add --transport http specrails http://localhost:4200/api/mcp \
+  --header "X-Desktop-Token: <your mcp token>"
+```
+
+**Gemini CLI** (HTTP transport — same shape):
+
+```bash
+gemini mcp add --transport http specrails http://localhost:4200/api/mcp \
+  --header "X-Desktop-Token: <your mcp token>"
+```
+
+**Codex CLI** (stdio — register the bundled bridge; copy the exact bridge
+command from **Settings ▸ MCP ▸ Copy config**, it embeds the app's bundled
+Node + script path):
+
+```bash
+codex mcp add specrails -- <bridge command from Settings ▸ MCP>
+```
+
 ## Security model
 
 - **A scoped token, not the master token.** The MCP surface is authenticated by