Context
Cornerstone 1's done-signal ("operator starts an agent from the UI") lands inside a SHELL whose mechanics are in flight (#13033 Electron boot root, the control-plane actuator line) — but whose USER EXPERIENCE has no spec anywhere. This is the last cornerstone surface without a drawn bar, and the first thing a stranger touches. The June class (functional-but-unusable) applies with maximum force at the front door. Spec now, while the daemon side is still shaping — retrofitting UX onto shipped shell mechanics is the expensive order.
The specification (the judgment-dense content — implement against this, challenge on the ticket)
1. The first-run experience (the "download and run" moment — this IS the product's first impression):
- Launch → ONE window, the cockpit, immediately useful: no setup wizard walls. Config resolution runs in the background with a visible, honest progress line (the TTFP clock starts at launch — the shell OWNS making that number good).
- Missing credentials/config = an inline, dismissible setup card INSIDE the cockpit (the shipped Accounts pattern) — never a modal gate, never a blank screen. The stranger sees the live surface first, completes setup second.
- First persistence reached → a single quiet confirmation moment (the measured TTFP event fires here).
2. Window management defaults:
- The cockpit is the home window: closing it minimizes to tray (the institution keeps running — that IS the product's thesis); quit is explicit (tray menu / app menu), never accidental.
- Promoted panels (the keeper/dock promote affordance) are real OS windows: independently movable/resizable, restored on relaunch to their last topology (the dock perspective is the persistence unit — composes with the registry-persistence leaf).
- New windows spawn at sensible offsets, never stacked at 0,0; multi-display aware (spawn on the display of the initiating action).
3. Tray/menu semantics (the always-running institution's handle):
- Tray icon = daemon state at a glance (running / degraded / stopped — three states max, the health substrate already computes them).
- Tray menu: Open Cockpit · Start/Stop agents (the control-plane actuator verbs) · Quit. NOTHING else in v1 — the tray is a handle, not a dashboard.
- Degraded state (a daemon down) surfaces as tray-state change + ONE cockpit banner with the diagnosis pointer — never a popup storm.
4. The cockpit-hosting frame:
- Native menu bar minimal: App (about/quit) · View (reload, zoom, devtools behind a dev flag) · Window (standard). No custom chrome in v1 — the web surface is the product; the shell frames it honestly.
- Deep-link protocol registration (
neo://) reserved-but-stubbed in v1 (the share-flow's future entry; registering early avoids the OS-permission dance later).
5. The bar: every state transition in shell surfaces follows the motion standards; the first-run flow gets a deterministic tour segment (it IS the J3 stranger journey's shell half); prefers-reduced-motion + keyboard navigation from day one.
Acceptance Criteria
Out of Scope
Auto-update infrastructure · code signing/notarization pipeline (release-engineering leaf) · the daemon mechanics themselves (#13033 + the actuator line) · custom titlebars/chrome.
Related
#13033 (the mechanics this frames — Ada's) · the control-plane actuator line · #14781 J3 (the stranger journey's shell half) · #14780 (motion bar) · #14766 (topology persistence composes) · the cockpit SSOT (merged).
Claimable — non-Fable implementable; Ada-adjacent (her shell line) or Vega (cockpit owner).
Origin Session ID: b9b95ac6-42f5-47a3-b58f-6071f79657e8
Retrieval Hint: "native shell UX first run tray window defaults cockpit frame download and run moment"
Context
Cornerstone 1's done-signal ("operator starts an agent from the UI") lands inside a SHELL whose mechanics are in flight (#13033 Electron boot root, the control-plane actuator line) — but whose USER EXPERIENCE has no spec anywhere. This is the last cornerstone surface without a drawn bar, and the first thing a stranger touches. The June class (functional-but-unusable) applies with maximum force at the front door. Spec now, while the daemon side is still shaping — retrofitting UX onto shipped shell mechanics is the expensive order.
The specification (the judgment-dense content — implement against this, challenge on the ticket)
1. The first-run experience (the "download and run" moment — this IS the product's first impression):
2. Window management defaults:
3. Tray/menu semantics (the always-running institution's handle):
4. The cockpit-hosting frame:
neo://) reserved-but-stubbed in v1 (the share-flow's future entry; registering early avoids the OS-permission dance later).5. The bar: every state transition in shell surfaces follows the motion standards; the first-run flow gets a deterministic tour segment (it IS the J3 stranger journey's shell half);
prefers-reduced-motion+ keyboard navigation from day one.Acceptance Criteria
Out of Scope
Auto-update infrastructure · code signing/notarization pipeline (release-engineering leaf) · the daemon mechanics themselves (#13033 + the actuator line) · custom titlebars/chrome.
Related
#13033 (the mechanics this frames — Ada's) · the control-plane actuator line · #14781 J3 (the stranger journey's shell half) · #14780 (motion bar) · #14766 (topology persistence composes) · the cockpit SSOT (merged).
Claimable — non-Fable implementable; Ada-adjacent (her shell line) or Vega (cockpit owner).
Origin Session ID: b9b95ac6-42f5-47a3-b58f-6071f79657e8 Retrieval Hint: "native shell UX first run tray window defaults cockpit frame download and run moment"