0 Fork 0

Files

T

ZacharyZhang-NY e3eb45b08d fix(landing): sync first-run narrative

2026-04-22 15:30:10 -04:00

13 KiB

Raw Blame History

Phase 5 — Design System & Desktop Flows

Visual + interaction system for the rebuild. Anchors: desktop-native, two-mode (AI CEO / AI Co-Founder), thread-runtime first, knowledge-backed. No web-dashboard-in-a-shell affordances.

1. Design intent

A control-plane for an autonomous company. Calm. Information-dense. Keyboard-first. Pause moments are intentional — when AI Co-Founder mode pauses for review, the UI feels like a checkpoint, not a delay.

The aesthetic baseline already lives in landing/ and screenshots/Dashboard.jpeg: dusty navy (#4a5d7a), graphite text, off-white surfaces, restrained accent. We keep that palette and tighten the IA.

2. Information architecture

┌─────────────────────────────────────┐
│ ⌂  Dashboard                        │
│ 📥 Inbox      ⓘ <wait-on-you count>│
│ 🧵 Threads                          │
│ ✓  Tasks & Approvals                │
│ 💼 Workspaces                       │
│ 📚 Knowledge                        │
│ ──                                  │
│ ⚙  Settings                          │
│ 📊 Diagnostics                      │
└─────────────────────────────────────┘

Sidebar collapses to icons at < 1100 px. Active item shows a subtle vertical accent bar.

2.2 Top bar

Per company: company picker · execution-mode pill (AI CEO / AI Co-Founder) · provider chip with active connector + cost-this-month · search · profile.

The mode pill is interactive: clicking opens a small panel explaining the difference, with a switch.

2.3 Onboarding (first run)

Welcome opens the flow. The setup panel then runs 7 sections:

Requirements — checks Node.js because CLI runtimes call the local API through node -e.
Providers — connects at least one runtime.
Company — captures company name, description, and workspace.
Team Models — enables the models available to the CEO and workers.
Mode — defaults to ai_ceo; ai_cofounder keeps key decisions human-reviewed.
Mission — captures the first goal and acceptance description.
Launch — creates the company, CEO agent, workspace, kickoff task, and initial run handoff.

The user lands in Control Center after launch.

2.4 Dashboard

Top: 4 KPI tiles (Active agents, Tasks in review, Spend month-to-date, Waiting-on-you). Below: 3 columns —

"What's happening now" (live runs with brief status)
"Decisions waiting for you" (approval queue mirrors Inbox)
"Recent deliverables" (documents/work-products with reviewer)

Empty states explain what each panel will hold once activity begins.

2.5 Inbox

A single ordered feed of inbox_items:

Type	Source	Action
Wait-on-you (approval)	`thread_wait_states` `waiting_for='human'` + linked approval	Approve / Deny inline
@mention	`agent_messages.body` mention scan	Reply
Subscribed thread update	`thread_subscriptions` + `conversation_events`	Open
Deliverable for review	`tasks.requires_user_review` true	Open task

Counts shown in sidebar mirror the unread/wait totals.

2.6 Threads

A two-pane view: left = thread list (filter: All / Subscribed / Wait / Recent); right = thread transcript with composer.

Transcript items: agent messages, tool executions (collapsible), tool results (collapsible), human posts, wait-state markers ("Waiting on @you to approve bash call …").

Composer: posts a user message into the active thread → triggers wakeup_request for the assigned agent.

2.7 Tasks & Approvals

Existing task/approval surfaces preserved; added:

"Pending tool approvals" section grouped by run (each item shows tool, args summary, "Approve in thread" deep link).

2.8 Workspaces

Existing surface preserved. Adds workspace lock indicator and a "Reveal in Finder/Explorer/Files" button (uses openPath).

2.9 Knowledge

Existing surface preserved. Adds "Inject into agent" affordance — moves a knowledge entry into the prompt-builder context for the next run.

2.10 Settings

Sub-pages:

Settings
  • Profile
  • Providers          ← new (the key addition)
  • Execution defaults (mode default, thinking level, retry counts)
  • Budgets
  • Workspaces
  • Skills
  • Updates
  • Advanced (logs path, profile dir, vault info)

2.11 Diagnostics

Read-only:

Recent runs with status colours
Recent IPC errors
Vault backend label (e.g. "macOS Keychain" or "encrypted file")
Current pi-mono package versions
Open log directory button

3. Settings → Providers panel (the central new surface)

3.1 Layout

┌──────────────────────────────────────────────────────────────────────┐
│ Providers                                                            │
│  Search [             ]      View: [Configured ▾]   [+ Add provider]│
│                                                                      │
│ ── Configured (4) ──────────────────────────────────────────────── │
│   ● Claude Pro/Max     OAuth · claude.pro@gmail.com   [Re-login][⋯] │
│   ● Anthropic API      Key  · sk-ant-…abcd            [Edit]   [⋯] │
│   ● AWS Bedrock        AWS  · profile=prod  region=us-east-1 [Edit] │
│   ! Gemini CLI         OAuth · refresh failed         [Re-login]    │
│                                                                      │
│ ── Available (21) ─────────────────────────────────────────────── │
│   ○ ChatGPT Plus/Pro (Codex)   OAuth      [Login]                   │
│   ○ GitHub Copilot              OAuth      [Login]                   │
│   ○ Antigravity                 OAuth      [Login]                   │
│   ○ OpenAI API                  Key        [Add]                     │
│   …                                                                  │
└──────────────────────────────────────────────────────────────────────┘

Status dot colours:

● green — active
◐ amber — expired (refresh failed)
! red — error
○ neutral — not configured

3.2 Forms

Five hand-written forms (no universal generator):

OAuthRow — "Login" button, optional GHE domain prompt for GitHub Copilot (renders OAuthPromptDialog), shows progress (onProgress messages) inline as a tiny status line.
ApiKeyForm — single password input (masked) + "Reveal" toggle + dropdown "Source: Inline value | Env var name". Save button.
AzureForm — fields: baseUrl, resourceName, apiVersion, deploymentMap (key/value editor), apiKey. Save button.
AwsForm — radio: "AWS profile" / "IAM keys" / "Bearer token", each revealing fields. Region (default us-east-1). Advanced toggles for forceCache, endpointUrl, skipAuth, forceHttp1.
VertexForm — fields: project, location, credentialsPath (file picker, optional), "Use ADC" checkbox.

Each form has a "Test connection" button that performs streamSimple(... { maxTokens: 1 }) against the connector's default model with a 1-character prompt. Outcome: ✅ "OK — used $0.0001" / ❌ "".

3.3 OAuthPromptDialog

Modal triggered by oauth:prompt-request (e.g. GHE domain) and oauth:manual-code-request (fallback when callback server is blocked):

┌─────────────────────────────────────┐
│ GitHub Copilot                       │
│                                      │
│ Enter your GitHub Enterprise domain. │
│ Leave blank for github.com.          │
│                                      │
│ [github.com_______________________]  │
│                                      │
│        [Cancel]   [Submit →]         │
└─────────────────────────────────────┘

4. Mode UX

Mode pill in top bar:

AI CEO — solid green pill. Tooltip: "Tools execute without review. Approvals only for explicit policy gates."
AI Co-Founder — outlined navy pill. Tooltip: "Agents pause at write-side tools (bash, edit, write). You approve in Inbox."

Switching modes is per-company. The switch action writes companies.execution_mode and a confirmation toast.

Pause state in a thread

When a run pauses at beforeToolCall, the thread shows:

┌───────────────────────────────────────────┐
│ ⟳ engineer-01 wants to run                │
│                                           │
│ [bash]  npm install                       │
│         in workspaces/web-frontend        │
│                                           │
│ [Approve]   [Deny]   [Approve & don't ask]│
└───────────────────────────────────────────┘

"Approve & don't ask" sets a per-task auto-approval for the same tool with the same arg shape (writes agent_permissions.permissions_json).

5. Visual system

5.1 Tokens (Tailwind config)

colors:
  navy.700  #2c3a4f
  navy.600  #4a5d7a   ← brand accent
  navy.500  #6f8198
  graphite  #1f1f23   ← primary text
  ash       #56575a   ← secondary text
  fog       #efeff1   ← surface alt
  paper     #f8f8f9   ← surface
  accent    #c98c5a   ← warm accent (warnings, awaiting human)
  ok        #4a8d6f
  warn      #c79a45
  err       #b75252

font:
  sans      Inter, ui-sans-serif
  mono      "JetBrains Mono", ui-monospace

radius:
  sm 4px / md 8px / lg 12px

shadow:
  card  0 1px 2px rgba(0,0,0,0.06), 0 0 0 1px rgba(0,0,0,0.04)

Dark mode: invert paper/fog/graphite axis; navy.600 preserved as accent.

5.2 Spacing scale

4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 px. No off-grid spacing.

5.3 Components reused

src/renderer/components/ui/ already exposes primitives, layout, feedback, hooks. We extend it (no rewrite) with:

<StatusDot status="active|expired|error|none" />
<MaskedSecret value="sk-ant-…" />
<KeyValueEditor /> (Azure deployment map, custom env)
<ModePill mode="ai_ceo" | "ai_co_founder" interactive />
<WaitMarker reason="awaiting human" tool="bash" />

5.4 Density + responsive

Default density: comfortable. Toggle to compact in Settings → Profile.
Window min size: 1024 × 720. Sidebar collapses < 1100. Right panels collapse < 1280.
Drag-and-drop affordances:
- Knowledge entries → agent context (drag onto agent card).
- Files into Workspaces (already supported by underlying tooling; UI affordance added).

5.5 Keyboard

Shortcut	Action
`⌘/Ctrl + K`	Quick open (companies, threads, tasks)
`⌘/Ctrl + 1..9`	Switch sidebar item
`⌘/Ctrl + Enter`	Submit composer / Approve highlighted item
`Esc`	Close dialogs
`?`	Show shortcuts overlay

6. Empty + loading + error states (mandatory per screen)

Every new screen ships:

Empty illustration + 1-line explanation + 1-CTA.
Loading: skeleton blocks (no spinners except > 2 s).
Error: a <FailureCard> with an action button (retry / open logs).

No placeholder copy. No "Coming soon" text on any provider — every provider has either an active form or an inactive form with a clear "Configure" path.

7. Microcopy rules

Lead with verbs ("Approve", "Deny", "Re-login").
Status text uses past tense ("Refreshed 2 min ago").
Cost expressed as $0.012 (3 decimals when < $1, otherwise 2).
Token counts use grouping 12,345.
Times use locale-aware format with absolute hover tooltip.

8. Thread runtime UX bindings

Renderer concept	Binding
"Wait card" in thread	`thread_wait_states` row resolved == null
"Read receipt"	(not in this rebuild)
"Subscribed" badge	`thread_subscriptions` row exists
"Mention" highlight	`agent_messages.body` mentions parsed at render time (existing helper)
"Inject knowledge"	calls `agentCompany.addThreadEvent` with `event_type: 'knowledge_injection'`, then `wakeup_request`

9. Onboarding mode-explainer copy

AI CEO
The CEO agent runs without pausing. Tools execute autonomously.
Best for: research sprints, content batches, long-running automation.

AI Co-Founder
The CEO agent pauses before any tool that writes to your filesystem,
modifies code, or runs a shell command. You approve in your Inbox.
Best for: code in your real workspaces, anything you'd want to review first.

You can switch any company between modes from the top bar.

10. Done criteria for Phase 5

Every screen is named.
Every form is a dedicated component.
Every state (empty/loading/error) has a rule.
Every status surface has a token.
The Providers panel is fully specified per the contract.
The mode UX is concrete, not aspirational.

13 KiB Raw Blame History Unescape Escape