Build interactive native workspace vertical slice

docs/UX_VERTICAL_SLICE.md

@@ -0,0 +1,107 @@
+# Decisive native workspace vertical slice
+
+## Outcome
+
+The slice must let an engineer notice one waiting agent, move focus to it from
+the keyboard, inspect the request, and choose a safe next action without losing
+the state of five other busy surfaces. It is a product interaction test and a
+framework decision gate, not a decorative dashboard.
+
+## Current-run audit
+
+The 2026-08-31 GPUI baseline succeeds at calm density: the six surfaces are easy
+to scan, typography is consistent, and local/remote targets remain visible. It
+fails the task flow in four important ways:
+
+1. all panes have equal visual priority, so `NEEDS INPUT` is too easy to miss;
+2. no pane exposes visible keyboard focus or selection;
+3. the command palette affordance has no interaction behind it;
+4. status and usage text in the footer is too quiet to explain provenance or
+   confidence at a glance.
+
+Screenshots for the audit are stored outside Git under
+`~/shots/2026-08/lumbridge-ui-audit/`. Accessibility and IME correctness cannot
+be established from screenshots and remain explicit runtime gates.
+
+## Preserved design language
+
+- Near-black blue surfaces with one cool-blue action accent.
+- Thin borders and compact spacing; no elevated card shadows.
+- Text carries most hierarchy. Color is supplementary and never the only state
+  signal.
+- Monospace content inside terminal surfaces; system UI typography elsewhere.
+- Dense information, but only the focused or waiting surface becomes prominent.
+
+## Orca reference, translated for Lumbridge
+
+The visual reference is the MIT-licensed Orca repository at researched commit
+`02a7742406a5a84fb372d6255d5a4367421990bd`. Its screenshots are product
+research, not source assets for Lumbridge. We adapt these interaction patterns:
+
+- a worktree/task-first sidebar whose rows show state without becoming large
+  cards;
+- a quiet top tab strip for mixed terminal, Markdown, browser, and review
+  surfaces;
+- one primary work surface with optional splits, instead of forcing every
+  surface into an equal dashboard tile;
+- narrow contextual tools, such as files, review, or Buzz, that can collapse
+  when the terminal needs the space;
+- usage and agent state at the edge of the workspace rather than in modal
+  account pages.
+
+Lumbridge deliberately differs where its product model differs: remote runtime
+ownership is always visible, `needs input` receives a dedicated attention path,
+usage includes provenance and uncertainty, and Buzz is a signed collaboration
+surface rather than a hosted Lumbridge control plane.
+
+## Visual hierarchy
+
+1. The top bar names the current workspace, repository/branch, and command
+   palette shortcut.
+2. The sidebar starts with a compact `ATTENTION` group, followed by workspaces
+   and remote hosts. It does not become a notification feed.
+3. The active pane receives a two-pixel accent edge plus a quiet tinted header.
+4. A waiting pane uses an amber semantic label and remains visible when another
+   pane is selected. The label always includes words such as `NEEDS INPUT`.
+5. Pane headers expose title, execution target, harness state, and unread count
+   in a stable order.
+6. The footer groups connection state, selected-harness identity, usage-window
+   provenance, and burn forecast into readable regions.
+
+## Keyboard task flow
+
+- Arrow keys or `h/j/k/l`: move focus through the 2×3 pane grid.
+- `1` through `6`: focus a pane directly.
+- `Cmd+K` on macOS or `Ctrl+K` on Linux: open the command palette.
+- Typing while the palette is open changes its query; arrows change the result;
+  `Enter` runs it; `Escape` closes it and restores pane focus.
+- `Enter` on a waiting agent opens its request detail. Approval remains a
+  separate explicit action and is never triggered by focusing the pane.
+- `Escape` closes transient UI before it changes workspace state.
+
+Every command is represented by the shared interaction model so GPUI and Floem
+receive the same state transitions and tests.
+
+## Decisive workload
+
+- One deterministic tick invalidates all six surfaces and appends bounded output
+  to the three terminal panes. Framework adapters consume the same event trace.
+- One pane enters and leaves `needs input` through a deterministic event.
+- Markdown, browser-boundary, and review panes update counters without using a
+  web application shell.
+- The model records actions, revisions, six-surface updates, and bounded terminal
+  line counts. Framework adapters label each measured timing stage explicitly;
+  element-build timing is never presented as display-present timing.
+- A later PTY adapter replaces one synthetic stream without changing the UI
+  contract. Synthetic streams stay available for repeatable performance tests.
+
+## Hard gates
+
+- Every focus movement and palette command is unit tested without a window.
+- Focus and `needs input` remain distinguishable in monochrome screenshots.
+- The current-GPUI input probe preserves composed Unicode and multi-codepoint
+  graphemes. Real candidate-window placement still requires Linux/macOS testing.
+- The accessibility tree names each pane, selected state, execution target, and
+  waiting state.
+- Six streams remain responsive while the palette is open.
+- Closing the UI never implies that a runtime-owned session has stopped.