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

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