# AWP — Canonical UI Screen Atlas **Version:** v2.0 **Date:** 2026-08-19 **Status:** Canonical UX baseline before further architecture/design deepening. **Representation policy:** All screens in this document are **text/ASCII wireframes only**. No HTML, image, or decorative mockup is part of the canonical screen contract. --- ## 1. Product UX contract AWP's internal architecture may contain Projects, Plans, FactoryRuns, AgentRuns, CI, Reviews, Releases, Deployments, Incidents, Accounts, Providers, Cluster objects, and many other domain types. The normal user experience must not require the user to navigate that ontology to understand work. Every primary operational surface should answer these five questions as directly as possible: ```text 1. What did I ask for? 2. Where is it now? 3. What happened last? 4. What happens next? 5. Do I need to act? ``` Cross-cutting UX invariants: ```text UX-001 Navigation does not mirror backend module decomposition. UX-002 Home is work-first and board-dominant. UX-003 Owner-facing default lifecycle is Asked / In progress / Waiting / Done. UX-004 Operational objects expose last / current / next / attention. UX-005 Waiting always explains itself. UX-006 Failure tells a recovery story before exposing raw logs. UX-007 Relationship/provenance context survives drill-down. UX-008 Planning exposes consequences before methodology labels. UX-009 Approvals are decision briefs with impact and reversibility. UX-010 One primary action per view/section. UX-011 Data views specify loading / empty / error / populated / stale states. UX-012 Meaningful view state survives refresh/share through URL truth. UX-013 High-impact commands require live authoritative connectivity. UX-014 Keyboard/focus/accessibility behavior is part of the screen contract. UX-015 Raw IDs, config keys, provider JSON, logs, and Kubernetes detail are evidence layers. ``` --- ## 2. Navigation v2 The normal desktop shell exposes six goal-oriented areas: ```text AWP | +-- HOME | +-- Work command center | +-- Needs your attention | +-- WORK | +-- Projects | +-- Plans | +-- Requests / Work Items | +-- Saved views | +-- EXECUTION | +-- Factory Runs | +-- Agents | +-- CI | +-- DELIVERY | +-- Reviews | +-- Releases | +-- Deployments | +-- OPERATIONS | +-- Incidents | +-- Cluster | +-- Queues | +-- Health | +-- SETTINGS +-- Accounts & Models +-- Providers +-- Configuration +-- Security +-- Integrations / Communications +-- Audit ``` `Needs your attention` is globally reachable as a badge/drawer and as a full page. Global search / command palette is available everywhere. --- ## 3. Canonical interaction patterns ### UI-PATTERN-01 — Human-readable identity first Primary labels use request/task/project names. IDs remain available as secondary evidence. ### UI-PATTERN-02 — Last / current / next / attention Operational detail headers expose: ```text LAST latest meaningful state-changing event CURRENT authoritative current state and owner NEXT expected transition or next responsible actor ATTENTION whether the user can or should act ``` ### UI-PATTERN-03 — Explain Waiting Every `WAITING`, `QUEUED`, `BLOCKED`, `PAUSED`, or `PENDING APPROVAL` state exposes: ```text waiting for since when why required current owner latest progress timeout / escalation where applicable what happens next whether the user can or should act ``` ### UI-PATTERN-04 — Failure / recovery narrative Before raw logs, failure views answer: ```text What failed? Why? What has AWP already tried? What is happening now? What happens next? What can the user safely do? ``` ### UI-PATTERN-05 — Lifecycle Rail Work-item detail preserves the complete story: ```text Asked -> Planned -> Factory -> Change -> Review -> CI -> Merged -> Released -> Deployed ``` The current stage is dominant; completed stages are compact; future stages are subdued. Selecting a stage opens context without losing the current work item. ### UI-PATTERN-06 — Complete data states Every data-driven screen defines: ```text Loading Empty Error Populated Stale / disconnected where applicable ``` Loading uses geometry-compatible skeletons/reserved space. Empty states provide one human sentence and one useful action. Error states explain what failed and what the user can do. ### UI-PATTERN-07 — Action hierarchy ```text Primary one per view/section Secondary limited Tertiary text / ghost / context menu Destructive physically and visually separated ``` Routine reversible operations should prefer undo/reversal over unnecessary confirmation. High-impact actions expose consequences before confirmation. ### UI-PATTERN-08 — Context Inspector Boards, lists, and graphs may open a right-side inspector containing: ```text human-readable identity state relationship context last meaningful event why next attention/action open full detail ``` Opening/closing the inspector preserves board/table position. ### UI-PATTERN-09 — URL truth Meaningful state is reproducible through the URL where practical: ```text project view / tab search filters sort / grouping page selected item ``` ### UI-PATTERN-10 — Keyboard / command model ```text Cmd/Ctrl+K command palette / global search J/K or arrows move through rows/cards where applicable Enter open selected item Esc close inspector/modal/clear transient selection ? shortcut reference ``` Shortcuts supplement visible controls. ### UI-PATTERN-11 — Long-running mutations Start, retry, cancel, deploy, rollback, enrollment, and similar actions: ```text 1. acknowledge immediately 2. prevent duplicate mutation 3. expose current phase 4. allow safe navigation away 5. restore progress when returning 6. produce explicit completion/failure result ``` ### UI-PATTERN-12 — Offline / stale safety Cached data may remain readable. Safe drafts/preferences may be queued. High-impact control-plane commands are never silently queued offline, including approval, merge, production deployment, rollback, and security/credential changes. ### UI-PATTERN-13 — Accessibility / focus contract All screen implementations require semantic controls, visible focus, predictable tab order, modal focus trap/return, non-color-only state encoding, usable target sizes, async status announcements, and no hover-only critical action. ### UI-PATTERN-14 — Canonical collections Projects, Plans, Factory Runs, Agents, CI, Reviews, Releases, Deployments, Incidents, Accounts, Models, Audit, Queues, and similar collections reuse one model: ```text Search | Filter | Sort | Group | Saved views | Board/List where meaningful Keyboard row/card navigation | URL-persisted state | pagination/load-more ``` --- # 4. Ten core ASCII screen contracts These ten screens establish the v2 mental model. Other screens in the catalog inherit their patterns. ## UI-SHELL-01 — Desktop Application Shell v2 **Job:** Provide stable wayfinding without exposing every internal domain as equal-weight navigation. ```text +--------------------------------------------------------------------------------------------------+ | AWP Search / command... Attention: 3 | +----------------------+---------------------------------------------------------------------------+ | HOME | | | Work | CURRENT PAGE | | Needs your attention| | | | | | WORK | | | Projects | | | Plans | | | Requests | | | | | | EXECUTION | | | Factory Runs | | | Agents | | | CI | | | | | | DELIVERY | | | Reviews | | | Releases | | | Deployments | | | | | | OPERATIONS | | | Incidents | | | Cluster | | | | | | SETTINGS | | +----------------------+---------------------------------------------------------------------------+ ``` Rules: - current group and page are visible; - sidebar may collapse without losing labels entirely at desktop compact widths; - attention count represents actionable items, not generic notifications; - project context/filter lives in page-level context rather than multiplying navigation trees. --- ## UI-OVERVIEW-01 — Work Command Center v2 **Job:** Answer what was asked, what is moving, what is waiting, and whether intervention is required. ```text +--------------------------------------------------------------------------------------------------+ | Work Search... Project: All Updated 4s | +--------------------------------------------------------------------------------------------------+ | IN FLIGHT QUEUED NEEDS YOU SHIPPED TODAY | | 4 / 5 lanes 7 3 6 | +--------------------------------------------------------------------------------------------------+ | Asked | In progress | Waiting | Done | |--------------------------+--------------------------+----------------------------+---------------| | Fix SEO rollback | Cloudflare backend | Translation E2E | Node upgrade | | Press.zone • 18m | agent: codex-2 | WAITING FOR: CI-208 | shipped 14m | | next: plan | last: tests green 2m | WHY: integration tests | | | | next: review change | NEXT: auto-continue | | |--------------------------+--------------------------+----------------------------+---------------| | Add account lock | AWP UI atlas v2 | Release 0.9.37 | ... | | AWP • 32m | current: UX integration | NEEDS YOU: approval | | | next: clarify | next: publish docs | blocking: production | | |--------------------------+--------------------------+----------------------------+---------------| | independent column scrolling; visible WIP where relevant | +--------------------------------------------------------------------------------------------------+ | RECENT REQUESTS — last 5 | | 18m Fix SEO rollback symmetry Press.zone In progress last update 2m | | 31m Move backend UI to Cloudflare Press.zone Waiting needs approval | | ... | +--------------------------------------------------------------------------------------------------+ ``` Rules: - board consumes most vertical space; - default owner lifecycle is `Asked / In progress / Waiting / Done`; - internal `Ready`/queue states may exist without requiring another owner-facing column; - each visible card carries current state, last meaningful update, and next step; - waiting cards always explain why; - Done is visually quieter; - recent request log is capped at five rows. --- ## UI-PLAN-02 — Plan Work Board / Kanban v2 **Job:** Manage one plan's work while keeping outcome, WIP, and blockers visible. ```text +--------------------------------------------------------------------------------------------------+ | Plan: Translation backend migration Goal: move plugin/backend to Cloudflare | | Progress: 7/12 accepted WIP: 3/4 Blocked: 1 [List] [Board selected] | +--------------------------------------------------------------------------------------------------+ | Asked | In progress | Waiting | Done | |--------------------------+--------------------------+----------------------------+---------------| | Migrate backend UI | Worker API contract | Plugin E2E | DB schema | | priority: high | owner: factory-18 | waiting for: test env | accepted | | next: refine | last: impl updated | why: remote fixture | | |--------------------------+--------------------------+----------------------------+---------------| | Add rollback drill | Plugin adapter | | Auth mapping | | next: schedule | owner: agent-44 | | accepted | +--------------------------------------------------------------------------------------------------+ | Filters: [owner] [priority] [attention] [wave] Group: lifecycle Saved view: Default | +--------------------------------------------------------------------------------------------------+ ``` Rules: - board lifecycle remains human-readable even if workflow policy is Scrum/Kanban/Scrumban/Custom; - WIP limit is visible where it affects execution; - drag/drop is optional convenience, never the only way to transition work; - invalid transitions explain policy instead of silently refusing; - card opening uses the context inspector by default, with full detail available. --- ## UI-PLAN-05 — Task / Work Item Detail v2 **Job:** Reconstruct the entire story of one request without navigating domain-by-domain. ```text +--------------------------------------------------------------------------------------------------+ | Fix SEO rollback symmetry Press.zone • Task | | State: IN PROGRESS Owner: AgentRun 44 Updated 2m ago [Steer] [More...] | +--------------------------------------------------------------------------------------------------+ | LIFECYCLE | | [Asked ✓] -> [Planned ✓] -> [Factory ●] -> [Change] -> [Review] -> [CI] -> [Merged] -> [Deploy]| +--------------------------------------------------------------------------------------------------+ | LAST | CURRENT | NEXT | | implementation updated 2m ago | agent verifying finalizer | run focused tests | | | no human action needed | then create ChangeSet | +--------------------------------------------------------------------------------------------------+ | REQUEST | | Ensure SEO rollback is symmetric with ACF rollback on every finalizer failure path. | +--------------------------------------------------------------------------------------------------+ | LATEST MEANINGFUL ACTIVITY | | 09:18 Agent found asymmetric rollback path in TranslationFinalizer | | 09:23 Patch applied | | 09:26 PHP unit tests green | | | | [Open Factory context] [Open evidence] [Full activity] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - human request stays at the top; - lifecycle rail preserves provenance across FactoryRun/AgentRun/ChangeSet/CI/Release/Deployment; - technical IDs are secondary metadata; - raw logs/tool calls are evidence, not the default narrative. --- ## UI-PLANNING-02 — Interactive Software Planning v2 **Job:** Turn an intent into a structured plan interactively while keeping the draft legible. ```text +--------------------------------------------------------------------------------------------------+ | Plan software Draft saved 3s ago | +--------------------------------------------------------------------------------------------------+ | Conversation / interview | Structured draft | |---------------------------------------------+----------------------------------------------------| | You: Move the backend to Cloudflare... | Goal | | | Move API + backend UI without breaking plugin | | AWP: The current backend has two deploy | | | targets. Should the migration preserve... | Constraints | | | - Cloudflare compatible | | [message...] | - Existing plugin remains usable during cutover | | | | | | Open decisions | | | 1. persistence migration | | | 2. staged cutover | | | | | | Proposed work | | | Wave 1 platform | | | Wave 2 backend | | | Wave 3 plugin | +--------------------------------------------------------------------------------------------------+ | [Add source/context] | [Review plan contract] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - planning conversation and structured draft remain synchronized; - draft autosaves; - unresolved decisions are visible, not hidden in chat history; - methodology jargon is not required to begin planning; - source material/evidence remains attributable. --- ## UI-PLANNING-03 — Delivery Design v2 **Job:** Configure how work should move by consequences first; methodology names are presets/interpretations. ```text +--------------------------------------------------------------------------------------------------+ | Delivery design — Translation backend migration | +--------------------------------------------------------------------------------------------------+ | How should work enter execution? | | (x) Start when ready ( ) Start in planned batches | | | | How much may run at once? | | Parallel work / WIP: [ 4 ] | | | | When priorities change during active work: | | (x) Allow immediately ( ) After current work finishes ( ) Require approval | | | | Review cadence: | | (x) Each task ( ) Each wave ( ) Before release | | | | Release cadence: | | ( ) Each accepted change (x) Each wave ( ) End of plan | | | | Policy match: Scrumban | | The preset label describes these settings; it does not place the project in a separate mode. | +--------------------------------------------------------------------------------------------------+ | Changes from project defaults: WIP 3 -> 4; release cadence end-of-plan -> each wave | | [Cancel] [Save delivery design] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - consequence questions are primary; - `Scrum / Kanban / Scrumban / Custom` are presets that fill settings and remain selectable shortcuts; - switching a preset shows the exact rule delta before applying it; - project/plan inheritance is explicit. --- ## UI-FACTORY-02 — Factory Run Overview v2 **Job:** Explain execution in human terms before showing the graph. ```text +--------------------------------------------------------------------------------------------------+ | Factory Run — Fix SEO rollback symmetry Running • started 18m ago | | Task: Press.zone / Fix SEO rollback symmetry [Cancel] [More...] | +--------------------------------------------------------------------------------------------------+ | CURRENT STORY | | Requested Make SEO rollback symmetric with ACF rollback | | Current stage Verification | | Owner AgentRun 44 | | Last Focused PHP tests passed 2m ago | | Next Validate JS gate, then prepare ChangeSet | | Attention No action needed | +--------------------------------------------------------------------------------------------------+ | STAGES | | [Plan ✓] -> [Implement ✓] -> [Verify ●] -> [ChangeSet] -> [Review] | +--------------------------------------------------------------------------------------------------+ | Latest meaningful activity | | 09:18 Found asymmetric failure path | | 09:23 Updated rollback transaction | | 09:26 PHP tests passed | | | | [Graph] [Agent] [Files] [Evidence] [Raw events] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - graph remains first-class diagnostic detail but is not the default explanation; - current objective/state/owner/last/next/attention appear before provider details; - graph node selection opens the context inspector without losing the run overview. --- ## UI-AGENT-01 — Agent Run / Steering v2 **Job:** Understand what an agent is doing and steer it without reading every tool invocation. ```text +--------------------------------------------------------------------------------------------------+ | AgentRun 44 — Codex RUNNING FactoryRun 18 | +--------------------------------------------------------------------------------------------------+ | OBJECTIVE | | Verify rollback symmetry and close any contract drift. | | | | CURRENT | | Reading finalizer failure paths | | | | LATEST MEANINGFUL FINDING | | One SEO rollback path did not mirror the ACF transaction rollback. | | | | NEXT | | Patch path -> focused tests -> ChangeSet | | | | BLOCKER / QUESTION | | None | +--------------------------------------------------------------------------------------------------+ | STEER | | [Focus only on rollback symmetry; do not refactor unrelated finalizer code. ] | | [Send steering] | +--------------------------------------------------------------------------------------------------+ | Technical activity (collapsed) 31 tool calls • 8 files • 3 commands [Open] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - tool calls, command output, files, and raw events are collapsed evidence by default; - steering acknowledgement is immediate and clearly associated with the running AgentRun; - steering never looks like creation of a new task; - idle/running/waiting/failed state remains visible. --- ## UI-APPROVAL-01 — Approval Decision Brief v2 **Job:** Let a user make a safe decision without first decoding architecture internals. ```text +--------------------------------------------------------------------------------------------------+ | Decision needed Architecture • waiting 23m | | AWP / Foundation / Cluster identity model [x] | +--------------------------------------------------------------------------------------------------+ | DECIDE | | How should ephemeral agent workloads receive cluster identity? | +--------------------------------------------------------------------------------------------------+ | RECOMMENDED | | ServiceAccount per AgentRun | | | | Why: smallest blast radius; identity expires with the run. | | Impact: affects all new AgentRuns | | Reversible: yes — configuration change | | Blocking: 2 tasks / 1 Factory Run | +--------------------------------------------------------------------------------------------------+ | Alternative: shared factory identity [Compare details] | +--------------------------------------------------------------------------------------------------+ | Evidence: security model • K3s capability test • affected policy [Open evidence] | +--------------------------------------------------------------------------------------------------+ | [Request changes] [Reject] [Approve recommendation] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - exactly one primary action; - recommendation, impact, reversibility, and blocked work are visible before action; - technical comparison is progressively disclosed; - production/destructive/high-risk decisions receive proportionate confirmation; - ordinary reversible decisions should not accumulate confirmation ceremony. --- ## UI-DEPLOYMENT-02 — Deployment Failure / Recovery v2 **Job:** Explain a failed deployment and recovery status before exposing infrastructure logs. ```text +--------------------------------------------------------------------------------------------------+ | Deployment — press-zone-backend / production RECOVERING | | Release 0.9.37 • Cloudflare [More] | +--------------------------------------------------------------------------------------------------+ | WHAT FAILED | | Health verification did not reach the required success threshold after rollout. | | | | WHY | | /site/overview returned an incompatible response from the new worker revision. | | | | WHAT AWP ALREADY TRIED | | 1. retried health check | | 2. confirmed old revision remains healthy | | 3. stopped traffic promotion | | | | WHAT IS HAPPENING NOW | | Resolver is comparing the release contract with the deployed response. | | | | WHAT HAPPENS NEXT | | If deterministic repair is not accepted in 8m, rollback remains available. | +--------------------------------------------------------------------------------------------------+ | [Open resolver] [Evidence] [Logs] [Rollback release] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - the same failure/recovery narrative applies to Factory, Agent, CI, Merge, Release, Deployment, Cluster, and Provider failures; - logs are an evidence layer; - destructive/recovery actions state target and consequence; - progress remains recoverable after navigation/reload. --- # 5. Screen catalog and v2 dispositions The following screen IDs remain part of the product surface. Their detailed implementations inherit the v2 patterns above. Where an older screen contract conflicts with this document, this v2 atlas is authoritative. ```text SHELL / GLOBAL UI-SHELL-01 Desktop application shell v2 UI-SHELL-02 Global search / command palette UI-SHELL-03 Needs-your-attention drawer/inbox HOME / WORK UI-OVERVIEW-01 Work Command Center v2 UI-OVERVIEW-02 Create / import project UI-PROJECT-01 Project overview — work/activity dominant, KPI-light UI-PLAN-01 Plan overview — active work + blockers dominant UI-PLAN-02 Plan Work Board / Kanban v2 UI-PLAN-03 Plan hierarchy / power-user structure UI-PLAN-04 Plan timeline UI-PLAN-05 Task / Work Item Detail v2 ONBOARDING UI-ONBOARD-01 Choose create / adopt existing project UI-ONBOARD-02 Repository/source selection UI-ONBOARD-03 Project discovery UI-ONBOARD-04 Existing configuration inventory UI-ONBOARD-05 Proposed adoption mapping UI-ONBOARD-06 Diff-before-write adoption review UI-ONBOARD-07 Onboarding result / unresolved items PLANNING UI-PLANNING-01 What do you want done? / planning entry UI-PLANNING-02 Interactive Software Planning v2 UI-PLANNING-03 Delivery Design v2 UI-PLANNING-04 Plan contract review / publish EXECUTION UI-FACTORY-01 Factory Runs collection UI-FACTORY-02 Factory Run Overview v2 UI-FACTORY-03 Execution graph UI-FACTORY-04 Factory event/activity view UI-FACTORY-05 Factory artifacts/files UI-FACTORY-06 Factory waiting/blocker detail UI-FACTORY-07 Factory failure/recovery detail UI-AGENT-01 Agent Run / Steering v2 UI-AGENT-02 Agent technical activity UI-CI-01 CI runs collection UI-CI-02 CI run summary UI-CI-03 Check/gate detail UI-CI-04 Change-impact explanation UI-CI-05 CI failure/recovery DELIVERY UI-REVIEWS-01 Reviews collection UI-APPROVALS-01 Decision/approval inbox UI-APPROVAL-01 Approval Decision Brief v2 UI-RELEASE-01 Release detail + lifecycle next transition UI-DEPLOYMENT-01 Deployment detail UI-DEPLOYMENT-02 Deployment Failure / Recovery v2 OPERATIONS UI-CLUSTER-01 Cluster overview UI-CLUSTER-02 Machine/node collection UI-MACHINE-01 Machine detail UI-MACHINE-02 Enrollment UI-MACHINE-03 Enrollment progress UI-MACHINE-04 Machine capability/placement detail UI-MACHINE-05 Maintenance/upgrade UI-MACHINE-06 Machine failure/recovery UI-INCIDENT-01 Incident detail — hypothesis + next action before raw timeline UI-RESOLVER-01 Resolver proposal/decision UI-QUEUES-01 Queue / waiting view UI-HEALTH-01 Provider/system health SETTINGS / EVIDENCE UI-ACCOUNTS-01 Accounts & model capacity UI-PROVIDERS-01 Provider registry/capabilities UI-AUTONOMY-01 Human-in-the-loop preset + semantic rule delta UI-AUTONOMY-02 Advanced autonomy rules UI-CONFIG-01 Configuration matrix — human labels primary, raw keys secondary UI-SECURITY-01 Security / credential references / admission locks UI-INTEGRATIONS-01 Integrations / communications UI-AUDIT-01 Audit collection UI-AUDIT-02 Audit event detail ``` Catalog rules: - collection screens use `UI-PATTERN-14`; - detail screens use `Last / Current / Next / Attention` where operationally meaningful; - every waiting state uses `UI-PATTERN-03`; - every failure state uses `UI-PATTERN-04`; - provenance-linked work uses the lifecycle rail rather than requiring global-navigation hopping. --- # 6. Revised supporting screen contracts ## UI-ONBOARD-06 — Adopt-first, diff-before-write Existing repositories are never silently rewritten to satisfy AWP conventions. ```text +--------------------------------------------------------------------------------------------------+ | Adopt existing project — Review proposed changes | +--------------------------------------------------------------------------------------------------+ | DISCOVERED | AWP PROPOSAL | ACTION | |------------------------------------+------------------------------------+-------------------------| | existing CI workflow | adopt as BuildCheck provider | [Adopt] | | existing release script | map to release preparation | [Adopt] | | .secrets directory | keep local; never expose plaintext | [Policy details] | | custom deploy script | wrap as DeploymentProvider adapter | [Review diff] | +--------------------------------------------------------------------------------------------------+ | No repository file will be changed until the proposed diff is explicitly accepted. | | [Back] [Accept selected adoption plan] | +--------------------------------------------------------------------------------------------------+ ``` ## UI-CONFIG-01 — Human-readable configuration ```text +--------------------------------------------------------------------------------------------------+ | Configuration Scope: Project / AWP Search... | +--------------------------------------------------------------------------------------------------+ | Setting Effective Defined at Inherited from Status | |---------------------------+---------------+----------------+---------------------+----------------| | Maximum parallel agents | 4 | Project | System: 3 | overridden | | Change-impact CI | enabled | System | — | inherited | | Merge approval | required | Project | System: automatic | overridden | +--------------------------------------------------------------------------------------------------+ | Selected: Maximum parallel agents | | Canonical key: factory.maxAgents Why effective: project override [History] [Edit] | +--------------------------------------------------------------------------------------------------+ ``` Raw keys remain available for engineering/support but are not the primary labels. --- # 7. Responsive behavior Desktop is the primary dense operational surface, but contracts must degrade without losing meaning. ```text Wide desktop sidebar + full board/list + optional context inspector Narrow desktop / tablet compact sidebar inspector becomes overlay/drawer board columns may horizontally scroll with clear lifecycle labels Mobile navigation becomes drawer board defaults to one lifecycle lane at a time with lane switcher work-item story remains readable before evidence destructive/primary actions remain separated ``` No breakpoint may hide waiting reasons, approval impact, failure recovery state, or the current/next action merely to save space. --- # 8. State language Human-facing lifecycle language should remain stable even when provider/domain state machines are richer. ```text Owner-facing work lifecycle Asked In progress Waiting Done Supporting qualifiers Queued Needs you Failed / Recovering Cancelled Paused ``` Provider-specific states may appear in technical detail, but should not become the only explanation. --- # 9. UX validation before deeper visual design Detailed styling of every catalog screen should wait until the v2 mental model survives task-based testing. Required tests: ```text A. Recover an old request Find work requested previously and state current status, last event, next step, and attention need. B. Explain waiting State exactly what work is waiting for, why, who owns the dependency, and whether it continues automatically. C. Make a production decision Understand recommendation, impact, reversibility, blockers, and evidence before approving/rejecting. D. Steer a running agent Reach the active AgentRun from the work item, understand its objective, send steering, see acknowledgement. E. Recover a failed deployment Understand failure reason, attempted recovery, active resolver state, next step, and rollback availability. ``` Primary measurements: ```text task success rate time to locate target work time to answer the five core questions wrong-navigation count backtracking count approval decision confidence accidental/high-risk action rate waiting-state open-to-understanding time ``` Target for the primary owner workflow: after locating a work item, the user should be able to understand its state story in seconds without reading raw logs. --- # 10. Design freeze boundary Before architecture/spec deepening introduces additional user-visible concepts, preserve these decisions: ```text work-first information architecture six goal-oriented navigation groups board-dominant Home Asked / In progress / Waiting / Done default lifecycle persistent work provenance/lifecycle rail consequence-first delivery planning human narrative before execution graph/tool noise approval decision briefs failure/recovery narrative complete async/data states URL truth + keyboard/focus contracts ASCII-only canonical screen representation during this design phase ``` Future screen additions should demonstrate why they cannot be expressed through the existing navigation, collection, detail, inspector, waiting, approval, or recovery patterns before introducing another interaction model.