feat: ship agent-first mission control v0.2.57

docs/audits/2026-07-26/STRUCTURAL_PROOF_PREFLIGHT.md

@@ -0,0 +1,117 @@
+# Structural proof preflight
+
+- Product, route, or flow: Nexus authenticated legacy shell and the first migrated grid route, `/agents`
+- Selected direction or inspected source: `/dashboard`, captured in `screenshots/02-dashboard-desktop.png`
+- First bounded slice: shared V2 tokens, legacy sidebar/topbar/content frame, and the Agents overview
+- Explicit exclusions: dashboard and login visuals; route targets; stores, services, API contracts, backend behavior, and domain state transitions
+- Owner: Codex
+- Status: passed
+
+## Entry contract
+
+- Entry mode: task-first
+- Minimum context required before the first real action: current route title, gateway state, agent count, and any loading/error warning
+- Why each preceding block is necessary: the shell orients the user; the route header identifies the operational scope; gateway feedback determines whether agent data is trustworthy
+- First real action or task-entry control: open an agent profile
+- Success destination: the existing `/agents/:id` route
+- Blocked-destination reason and recovery: when no agents are returned, the existing empty state names gateway reachability and configuration as the recovery path
+
+| Viewport or container | Initial `scrollY` | Identifying context rectangle | Action rectangle | Required reserve | Destination and sticky offset | Settled result |
+| --- | ---: | --- | --- | ---: | --- | --- |
+| Narrowest supported / `375px` | 0 | `x=14`, `y=76`, `w=332`; identity and gateway status wrap inside the page frame | first agent card `x=14`, `y=186`, `w=332`; keyboard activation verified | 14px page inset | `/agents/iris`; 62px topbar remains visible | passed; no page or content x-overflow |
+| Representative wide / `1280px` rendered browser ceiling | 0 | `x=268`, `y=82`, `w=977`; title uses Space Grotesk 24/30, 700 | first agent card `x=268`, `y=161`, `w=316` | 20px page inset | `/agents/iris`; 62px topbar remains visible | passed; 248px sidebar and 62px topbar measured |
+
+## Section grammar
+
+| Order | Section | Primary role | User question | Evidence or input | Layout grammar | Density and disclosure | Narrow transformation | State responsibility |
+| ---: | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | Legacy shell | orient | Where am I and what can I open? | registered navigation and existing counts | fixed sidebar plus topbar | compact operational chrome | sidebar becomes an overlay | active route, connection status, mobile navigation |
+| 2 | Route header | orient | Which agent surface and gateway state am I seeing? | agent count and gateway response | title cluster plus status badge | concise | stack and wrap | loading, gateway warning, error |
+| 3 | Agent grid | act | Which agent should I inspect? | existing agent data | responsive card grid | operational summary per agent | 3 to 2 to 1 columns | runtime state and profile navigation |
+| 4 | Empty/error message | recover | Why is no agent available and what can I check? | existing error and empty copy | single glass state panel | readable | full-width | diagnostic and next valid check |
+
+- Accidental preamble removed or justified: no decorative preamble is added before the route identity.
+- Repeated wrappers or layout grammars that need a product reason: cards are reserved for comparable agents and operational panels.
+- Evidence kept with its claim: gateway state remains in the route header; runtime state remains inside its agent card.
+- Actions kept with their object and consequence: profile navigation remains on the corresponding agent card.
+- Recovery kept in destination context: loading, warning, error, and empty feedback stays inside the Agents page.
+
+## Signature-gesture distribution
+
+- Gesture: blue-to-violet gradient with controlled glow
+- One dominant use: active navigation and primary action
+- Supporting echo 1: brand mark
+- Supporting echo 2: a meaningful active or blocked status
+- Prohibited sections or states: ordinary data cards, neutral inputs, metadata, empty states, long-form copy, and destructive confirmation surfaces
+- Plain operational, error, and recovery grammar: glass surface, semantic border/status color, no decorative glow
+
+## Content and type pressure
+
+| Pressure input | Exact fixture or source | Narrow result | Wide result | Fix or accepted rationale | Status |
+| --- | --- | --- | --- | --- | --- |
+| Longest heading | existing route titles such as `Notifications` and `Project Detail` | retained at 24/30 and allowed to wrap | retained at 24/30 | wrap rather than shrink below the title contract | passed for the slice |
+| Longest control label | `Iris, Chief of Staff: View Profile` accessible name | keyboard reachable without changing visual copy | card action remains local to its object | preserve copy; allow action rows to wrap | passed |
+| Largest value or identifier | `claude-sonnet-4-5` | contained in the card metadata track | contained in the three-column grid | mono text keeps the existing ellipsis policy | passed |
+| Longest error, limitation, and recovery copy | authored error plus the existing gateway/configuration recovery copy | both wrap inside 332px | state surface remains inside the page frame | full-width glass state panels with natural wrapping | passed |
+| Required localization | current German and English UI strings | German copy wraps naturally; English labels remain intact | no content rewrite | do not rewrite product copy in this visual migration | passed |
+| `200%` zoom | represented structurally by the single-column narrow transformation and adjacent breakpoint matrix | no x-overflow | n/a | page remains vertically scrollable; controls wrap | accepted; final responsive matrix passed |
+| Narrow parent container | 375px required viewport | `scrollWidth=clientWidth=375`; content overflow delta `0` | n/a | `min-width: 0`, safe wrapping, and no page-level x overflow | passed |
+
+- Important instructions, limitations, provenance, status, safety, consequences, and recovery are at least `14px`: required for final proof.
+- Any `12px` use is truly secondary and nonessential, with contrast and line-height evidence: reserved for compact interface labels; metadata uses JetBrains Mono at 11px minimum.
+- Min-content and unbreakable-content policy: content columns use `minmax(0, 1fr)` and `min-width: 0`; identifiers wrap or use an existing internal scroller only on horizontal workspaces.
+- Risky breakpoints and adjacent widths: 375, 767/768, 1023/1024, 1440, and 1920px.
+
+## State-and-copy truth table
+
+| State | Entry cause | Visible facts | Allowed actions | Forbidden stale copy or values | Recovery or next action | Focus target | URL, history, and storage effect |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Initial/loading | route mounts and requests data | route title and loading message | navigation remains available | stale success state must not be presented as current | wait or navigate elsewhere | route heading | unchanged |
+| Success | API returns agents and gateway data | count, gateway state, cards, runtime metadata | open an agent, navigate, refresh | loading/error copy | select an agent profile | first actionable card | existing router history only |
+| Failure | API or gateway request fails | existing diagnostic message | navigate or refresh | stale cards presented as newly loaded | retry through the existing refresh/re-entry path | error message then next control | unchanged |
+| Recovery/empty | response contains no agents | existing empty-state reason and checks | navigate or re-enter after configuration changes | invented agents or changed recovery copy | check gateway reachability/configuration | empty-state heading | unchanged |
+
+- Additional orthogonal states required: connected, thinking, blocked, ready, stale, error, unsupported, mobile navigation open/closed, and keyboard focus.
+- Atomic stale-content removal rule: visual CSS must not change existing state guards or data replacement behavior.
+- Exact reset or recovery snapshot: current store and component behavior remains the source of truth.
+
+## Action vocabulary ledger
+
+| User intent | Idle control | Pending or progress | Success or result | Failure and next action | Recovery, undo, or reversal |
+| --- | --- | --- | --- | --- | --- |
+| Refresh operational data | Refresh | existing loading/spinner treatment | updated current state | existing error message | invoke Refresh again |
+| Inspect an agent | View Profile / agent card | route transition | agent detail route | existing route/error behavior | return through existing navigation |
+
+- Same user-recognized verb and domain noun retained through the journey: yes; no product copy or action is renamed by the visual migration.
+- Labels, statuses, toasts, confirmations, errors, recovery, and assistive announcements agree: existing strings remain authoritative.
+- Empty and failure states name the next valid action: existing page copy is preserved and presented accessibly.
+
+## Proof architecture
+
+- Stable semantic selectors, state attributes, and dedicated value nodes: route root classes, shell landmarks, existing data/state classes, and `data-route` on the legacy content frame
+- Assertions intentionally independent of translated copy, neighboring text, wrappers, and visual position: geometry and overflow checks target landmarks and route roots
+- Explicit settle conditions for scroll, fonts, media, transitions, async state, and geometry: document fonts loaded, fixture/API requests settled, no pending transitions, and two animation frames after route mount
+- Independent oracle or source of truth: router registration plus the independently authored audit fixture; production stores and API contracts are not modified
+- Required positive and negative assertions: every registered route renders; no page-level horizontal overflow; dashboard/login source files remain visually untouched; navigation/events/handlers remain registered
+- Source, build, harness, fixture, oracle, and capture bindings: repository HEAD and working tree, frontend build, local fixture, route matrix, and dated screenshots under this audit folder
+- Capture claim ledger location: `design-qa.md` and `docs/audits/2026-07-26/DESIGN_MIGRATION_AUDIT.md`
+- Failure classification: product / harness / evidence / environment
+
+## Structural slice gate
+
+| Gate | Narrow evidence | Wide evidence | Independent rendered review | Status |
+| --- | --- | --- | --- | --- |
+| Entry mode and minimum context remain true | title, count, gateway state, and first agent/action are visible | same hierarchy inside the standard page frame | accepted from rendered captures | passed |
+| First action is reachable and completely framed | first card is fully framed and opens by Enter | first row is visible above the fold | `/agents/iris` navigation verified | passed |
+| Section roles and layout grammars remain distinct | shell, identity, grid/state surface remain separate | same roles with three-column grid | accepted | passed |
+| Signature-gesture budget is respected | gradient is limited to active navigation, brand/primary action, and card identity accents | ordinary panels remain plain glass | accepted | passed |
+| Long content, localization, and min-content pressure pass | long descriptions, model IDs, tags, and recovery copy wrap without x-overflow | three-column content remains contained | accepted for bounded slice | passed |
+| Core path passes success, failure, and recovery | success grid, empty recovery, and API error were rendered | success grid rendered | fixture states captured independently | passed |
+| Focus, state copy, controls, and recovery agree | focused agent card measured with 2px blue outline and 2px offset | keyboard Enter opened the existing destination | accepted | passed |
+| Proof selectors, settle conditions, negatives, oracle, and capture binding pass | `data-route`, route root, landmark geometry, authored fixture, and dated captures recorded | same | typecheck passed; dashboard/login source files untouched | passed |
+
+- Automated result: candidate
+- Independent rendered-review result: accepted
+- Defects and classification: the initial comparison host was capped at 1280px; exact 1440px route checks and 1920px family checks were completed separately and passed.
+- Contract corrections: moved the gateway chip below the identity cluster on narrow screens; kept all recovery copy in glass state panels; added keyboard-equivalent link semantics to agent cards.
+- Expansion decision: proceed