322 lines
13 KiB
Markdown
322 lines
13 KiB
Markdown
# 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
|
||
|
||
### 2.1 Top-level navigation (left rail)
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ ⌂ 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:
|
||
|
||
1. **Requirements** — checks Node.js because CLI runtimes call the local API through `node -e`.
|
||
2. **Providers** — connects at least one runtime.
|
||
3. **Company** — captures company name, description, and workspace.
|
||
4. **Team Models** — enables the models available to the CEO and workers.
|
||
5. **Mode** — defaults to `ai_ceo`; `ai_cofounder` keeps key decisions human-reviewed.
|
||
6. **Mission** — captures the first goal and acceptance description.
|
||
7. **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):
|
||
|
||
1. **OAuthRow** — "Login" button, optional GHE domain prompt for GitHub Copilot (renders `OAuthPromptDialog`), shows progress (`onProgress` messages) inline as a tiny status line.
|
||
2. **ApiKeyForm** — single password input (masked) + "Reveal" toggle + dropdown "Source: Inline value | Env var name". Save button.
|
||
3. **AzureForm** — fields: `baseUrl`, `resourceName`, `apiVersion`, `deploymentMap` (key/value editor), `apiKey`. Save button.
|
||
4. **AwsForm** — radio: "AWS profile" / "IAM keys" / "Bearer token", each revealing fields. Region (default `us-east-1`). Advanced toggles for `forceCache`, `endpointUrl`, `skipAuth`, `forceHttp1`.
|
||
5. **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" / ❌ "<error message>".
|
||
|
||
### 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.
|