# Paperclip UI Spec

Status: Draft
Date: 2026-02-17

## 1. Design Philosophy

Paperclip's UI is a professional-grade control plane, not a toy dashboard. It should feel like the kind of tool you live in all day — fast, keyboard-driven, information-dense without being cluttered, dark-themed by default. Every pixel should earn its place.

Design principles:

- **Dense but scannable.** Show maximum information without requiring clicks to reveal it. Use whitespace to separate, not to pad.
- **Keyboard-first.** Global shortcuts for search (Cmd+K), new issue (C), navigation. Power users should rarely touch the mouse.
- **Contextual, not modal.** Inline editing over dialog boxes. Dropdowns over page navigations. The user's mental context should never be broken unnecessarily.
- **Dark theme default.** Neutral grays, not pure black. Accent colors used sparingly for status and priority. Text is the primary visual element.

### Color System

- **Background:** `hsl(220, 13%, 10%)` (dark charcoal, not pure black)
- **Surface/Card:** `hsl(220, 13%, 13%)`
- **Border:** `hsl(220, 10%, 18%)`
- **Text primary:** `hsl(220, 10%, 90%)`
- **Text secondary:** `hsl(220, 10%, 55%)`
- **Accent (interactive):** `hsl(220, 80%, 60%)` (muted blue)

Status colors (consistent across all entities):
- **Backlog:** gray `hsl(220, 10%, 45%)`
- **Todo:** gray-blue `hsl(220, 20%, 55%)`
- **In Progress:** yellow `hsl(45, 90%, 55%)`
- **In Review:** violet `hsl(270, 60%, 60%)`
- **Done:** green `hsl(140, 60%, 50%)`
- **Cancelled:** gray `hsl(220, 10%, 40%)`
- **Blocked:** amber `hsl(25, 90%, 55%)`

Priority indicators:
- **Critical:** red circle, filled
- **High:** orange circle, half-filled
- **Medium:** yellow circle, outline
- **Low:** gray circle, outline, dashed

### Typography

- **Font:** System font stack (Inter if loaded, else `-apple-system, BlinkMacSystemFont, 'Segoe UI'`)
- **Body:** 13px / 1.5 line-height
- **Labels/metadata:** 11px / uppercase tracking
- **Headings:** 14-18px / semi-bold, never all-caps

### Icons

Use `lucide-react` throughout. Every sidebar item, every status indicator, every action button should have an icon. Icons are 16px in nav, 14px inline.

---

## 2. Application Shell

The app is a three-zone layout:

```
┌──────────┬────────────────────────────────────────────────┐
│          │  Breadcrumb bar                                │
│ Sidebar  ├──────────────────────────┬─────────────────────┤
│ (240px)  │  Main content            │  Properties panel   │
│          │  (flex-1)                │  (320px, optional)  │
│          │                          │                     │
└──────────┴──────────────────────────┴─────────────────────┘
```

- **Sidebar:** Fixed left, 240px. Collapsible to icon-only (48px) via toggle or keyboard shortcut.
- **Breadcrumb bar:** Spans the full width above main+properties. Shows navigation path, entity actions, and view controls.
- **Main content:** Scrollable. Contains the primary view (list, detail, chart, etc).
- **Properties panel:** Right side, 320px. Shown on detail views (issue detail, project detail, agent detail). Hidden on list views and dashboard. Resizable.

The properties panel slides in when you click into a detail view and slides out when you go back to a list. It is NOT a sidebar — it's contextual to the selected entity.

---

## 3. Sidebar

The sidebar is the primary navigation. It is grouped into logical sections with collapsible headers.

### 3.1 Company Header

Top of sidebar. Always visible.

```
┌─────────────────────────┐
│ [icon] Acme Corp      ▼ │  ← Company switcher dropdown
├─────────────────────────┤
│ [🔍]  [✏️]              │  ← Search + New Issue
└─────────────────────────┘
```

**Company switcher** is a dropdown button that occupies the full width of the sidebar header. It shows:
- Company icon (first letter avatar with company color, or uploaded icon)
- Company name (truncated with ellipsis if long)
- Chevron-down icon

Clicking opens a dropdown with:
- List of all companies (with status dot: green=active, yellow=paused, gray=archived)
- Search field at top of dropdown (for users with many companies)
- Divider
- `+ Create company` action at the bottom

Below the company name, a row of icon buttons:
- **Search** (magnifying glass icon) — opens Cmd+K search modal
- **New Issue** (pencil/square-pen icon) — opens new issue modal in the current company context

### 3.2 Personal Section

No section header — these are always at the top, below the company header.

```
  Inbox                    3
  My Issues
```

- **Inbox** — items requiring the board operator's attention. Badge count on the right. Includes: pending approvals, budget alerts, failed heartbeats. The number is the total unread/unresolved count.
- **My Issues** — issues created by or assigned to the board operator.

### 3.3 Work Section

Section header: **Work** (collapsible, with a chevron toggle)

```
  Work                     ▼
    Issues
    Projects
    Goals
    Views
```

- **Issues** — main task list for the selected company. This is the workhorse view.
- **Projects** — project list. Projects group issues and link to goals.
- **Goals** — company goal hierarchy.
- **Views** — saved filter/sort configurations (e.g., "Critical bugs", "Unassigned tasks", "CEO's tasks"). Users can create, name, and pin custom views here.

### 3.4 Company Section

Section header: **Company** (collapsible)

```
  Company                  ▼
    Dashboard
    Org Chart
    Agents
    Costs
    Activity
```

- **Dashboard** — company health overview: agent statuses, task velocity, cost burn, pending approvals count.
- **Org Chart** — interactive tree visualization of the agent reporting hierarchy.
- **Agents** — flat list of all agents with status, role, last heartbeat, spend.
- **Costs** — cost dashboard with breakdowns by agent, project, model, time.
- **Activity** — audit log of all system events.

Note: Approvals do not have a top-level sidebar entry. They are surfaced through the **Inbox** (primary interaction point), **Dashboard** (pending count metric), and **inline on entity pages** (e.g., an agent detail page shows the approval that authorized its hire). The `/approvals` route still exists and is reachable via "See all approvals" links in Inbox and Dashboard, but it is not in the sidebar navigation.

### 3.5 Section Behavior

- Each section header is clickable to collapse/expand its children.
- Collapsed state persists in localStorage.
- Active nav item is highlighted with a left-border accent and background tint.
- Hovering a nav item shows a subtle background highlight.
- Badge counts are right-aligned, rendered as small pills (e.g., `3` in a rounded rect).
- Icons are 16px, left-aligned, with 8px gap to label text.

### 3.6 Sidebar Icons

Each nav item has a distinctive icon (lucide-react):

| Item | Icon |
|------|------|
| Inbox | `Inbox` |
| My Issues | `CircleUser` |
| Issues | `CircleDot` |
| Projects | `Hexagon` |
| Goals | `Target` |
| Views | `LayoutList` |
| Dashboard | `LayoutDashboard` |
| Org Chart | `GitBranch` |
| Agents | `Bot` |
| Costs | `DollarSign` |
| Activity | `History` |

---

## 4. Breadcrumb Bar

The breadcrumb bar sits above the main content and properties panel. It serves as both navigation and context indicator.

### 4.1 Structure

```
┌─────────────────────────────────────────────────────────────────────┐
│ Projects › Paperclip › Issues › CLIP-42  [⭐] [···]     [🔔] [⬜] │
└─────────────────────────────────────────────────────────────────────┘
```

**Left side:**
- Breadcrumb segments, separated by `›` chevrons.
- Each segment is clickable to navigate to that level.
- Current segment is non-clickable, slightly bolder text.
- Star icon to favorite/pin the current entity.
- Three-dot menu for entity actions (delete, archive, duplicate, copy link, etc.)

**Right side:**
- Notification bell (if in a detail view — subscribe to changes on this entity)
- Panel toggle (show/hide the right properties panel)

### 4.2 View-Specific Tabs

On certain detail pages, the breadcrumb bar also contains a tab row below the breadcrumbs:

**Project detail:**
```
  Overview    Updates    Issues    Settings
```

**Agent detail:**
```
  Overview    Heartbeats    Issues    Costs
```

Tabs are rendered as pill-shaped buttons. Active tab has a subtle background fill.

---

## 5. Issues (Task Management)

Issues are the core work unit. This section details the full issue experience.

### 5.1 Issue List View

The issue list is the default view when clicking "Issues" in the sidebar.

**Layout:**
```
┌─────────────────────────────────────────────────────────────────┐
│ [All Issues] [Active] [Backlog]  [⚙ Settings]    [≡ Filter]  [Display ▼] │
├─────────────────────────────────────────────────────────────────┤
│ ▼ Todo                                                3    [+] │
│ ☐ --- CLIP-5  ○ Implement user auth          @CTO    Feb 16  │
│ ☐ --- CLIP-3  ○ Set up CI pipeline           @DevOps Feb 16  │
│ ☐ --- CLIP-8  ○ Write API documentation      @Writer Feb 17  │
│                                                                 │
│ ▼ In Progress                                         2    [+] │
│ ☐ !!! CLIP-1  ◐ Build landing page           @FE     Feb 15  │
│ ☐ --- CLIP-4  ◐ Database schema design       @CTO    Feb 14  │
│                                                                 │
│ ▼ Backlog                                             5    [+] │
│ ☐ --- CLIP-9  ◌ Research competitors                  Feb 17  │
│ ...                                                             │
└─────────────────────────────────────────────────────────────────┘
```

**Top toolbar:**
- **Status tabs:** `All Issues`, `Active` (todo + in_progress + in_review + blocked), `Backlog`. Each tab shows a status icon and count. Active tab is filled, others outlined.
- **Settings gear:** Configure issue display defaults, custom fields.
- **Filter button:** Opens a filter bar below the toolbar.
- **Display dropdown:** Toggle between grouping modes (by status, by priority, by assignee, by project, none) and layout modes (list, board/kanban).

**Grouping:**
- Issues are grouped by status by default (matching the reference screenshots).
- Each group header shows: collapse chevron, status icon, status name, count, and a `+` button to create a new issue in that status.
- Groups are collapsible. Collapsed groups show just the header with count.

**Issue rows:**
Each row contains, left to right:
1. **Checkbox** — for bulk selection. Hidden by default, appears on hover (left of priority).
2. **Priority indicator** — icon representing critical/high/medium/low (see Color System above). Always visible.
3. **Issue key** — e.g., `CLIP-5`. Monospace, muted color. The prefix is derived from the project (or company if no project).
4. **Status circle** — clickable to open status change dropdown (same as reference screenshot). The circle's fill/color reflects current status.
5. **Title** — primary text, truncated with ellipsis if too long.
6. **Assignee** — avatar (agent icon) + agent name, right-aligned. If unassigned, shows a dashed circle placeholder.
7. **Date** — creation date or target date, muted text, far right.

**Row interactions:**
- Click row → navigate to issue detail view.
- Click status circle → opens inline status dropdown (Backlog, Todo, In Progress, In Review, Done, Cancelled) with keyboard numbers as shortcuts (1-6).
- Click checkbox → selects for bulk actions. When any checkbox is selected, a bulk action bar appears at the bottom of the list.
- Hover → shows checkbox, and row gets subtle background highlight.
- Right-click → context menu (same actions as three-dot menu).

**Bulk action bar:**
When one or more issues are selected, a floating bar appears at the bottom:
```
┌─────────────────────────────────────────────────────────┐
│  3 selected    [Status ▼] [Priority ▼] [Assignee ▼] [Project ▼]  [🗑 Delete]  [✕ Cancel] │
└─────────────────────────────────────────────────────────┘
```

### 5.2 Issue Filter Bar

Clicking "Filter" reveals a filter bar below the toolbar:

```
┌─────────────────────────────────────────────────────────┐
│ [+ Add filter]  Status is Todo, In Progress  [×]        │
│                 Priority is Critical, High    [×]        │
│                 Assignee is CTO-Agent         [×]        │
└─────────────────────────────────────────────────────────┘
```

- Each filter is a chip showing `field operator value`.
- Click a chip to edit it.
- `×` removes the filter.
- `+ Add filter` opens a dropdown of available fields: Status, Priority, Assignee, Project, Goal, Created date, Labels, Creator.
- Filters are AND-composed.
- Active filters persist in the URL query string so they're shareable/bookmarkable.

### 5.3 Issue Detail View (Three-Pane)

Clicking an issue opens the detail view. The main content area splits into two zones, with the sidebar still visible on the left.

```
┌──────────┬────────────────────────────────┬──────────────────────┐
│          │ Issues › CLIP-42               │                      │
│ Sidebar  │                                │   Properties     [+] │
│          │ Fix user authentication bug    │                      │
│          │ Implement proper token...      │   Status    In Progress │
│          │                                │   Priority  High     │
│          │ ┌──────────────────────────┐   │   Assignee  CTO      │
│          │ │ Properties bar (inline)  │   │   Project   Auth     │
│          │ │ In Progress · High ·     │   │   Goal      Security │
│          │ │ CTO · Auth project · ... │   │   Labels    bug, auth│
│          │ └──────────────────────────┘   │   Start     Feb 15   │
│          │                                │   Target    Feb 20   │
│          │ Description                    │   Created   Feb 14   │
│          │ ─────────────────              │                      │
│          │ The current authentication     │   ─────────────────  │
│          │ system has a token refresh...  │   Activity           │
│          │                                │   CTO commented 2h   │
│          │ Comments                       │   Status → In Prog   │
│          │ ─────────────────              │   Created by Board   │
│          │ [avatar] CTO · 2 hours ago     │                      │
│          │ I've identified the root...    │                      │
│          │                                │                      │
│          │ [avatar] DevOps · 1 hour ago   │                      │
│          │ The CI is set up to run...     │                      │
│          │                                │                      │
│          │ ┌──────────────────────────┐   │                      │
│          │ │ Write a comment...       │   │                      │
│          │ └──────────────────────────┘   │                      │
└──────────┴────────────────────────────────┴──────────────────────┘
```

#### Middle Pane (Main Content)

**Header area:**
- Issue title, large (18px, semi-bold), editable on click (inline editing).
- Subtitle: issue key `CLIP-42` in muted text.
- Below the title: inline properties bar showing key properties as clickable chips (same pattern as reference screenshots): `[○ In Progress] [!!! High] [👤 CTO] [📅 Target date] [📁 Auth] [···]`. Each chip is clickable to change that property inline.

**Description:**
- Markdown-rendered description.
- Click to edit — opens a markdown editor in-place.
- Support for headings, lists, code blocks, links, images.

**Subtasks (if any):**
- Listed below description as a collapsible section.
- Each subtask is a mini issue row (status circle + title + assignee).
- `+ Add subtask` button at the bottom.

**Comments:**
- Chronological list of comments.
- Each comment shows: author avatar/icon, author name, timestamp, body (markdown rendered).
- Comment input at the bottom — a text area with markdown support and a "Comment" button.
- Comments from agents show a bot icon; comments from the board show a user icon.

#### Right Pane (Properties Panel)

**Header:** "Properties" label with a `+` button to add a custom field.

**Property list:** Each property is a row with label on the left and editable value on the right.

| Property | Control |
|----------|---------|
| Status | Dropdown with status options + colored dot |
| Priority | Dropdown with priority options + icon |
| Assignee | Agent picker dropdown with search |
| Project | Project picker dropdown |
| Goal | Goal picker dropdown |
| Labels | Multi-select tag input |
| Lead | Agent picker |
| Members | Multi-select agent picker |
| Start date | Date picker |
| Target date | Date picker |
| Created by | Read-only text |
| Created | Read-only timestamp |
| Billing code | Text input |

Below properties, a divider, then:

**Activity section:**
- "Activity" header with "See all" link.
- Compact timeline of recent events: status changes, assignment changes, comments, etc.
- Each entry: icon + description + relative timestamp.

### 5.4 New Issue Modal

Triggered by the sidebar pencil icon, keyboard shortcut `C`, or the `+` buttons in the issue list.

```
┌─────────────────────────────────────────────────────────┐
│ [📁 CLIP] › New issue               [Save as draft] [↗] [×] │
├─────────────────────────────────────────────────────────┤
│                                                         │
│ Issue title                                             │
│ ___________________________________________________     │
│                                                         │
│ Add a description...                                    │
│                                                         │
│                                                         │
│                                                         │
│                                                         │
├─────────────────────────────────────────────────────────┤
│ [○ Todo] [--- Priority] [👤 Assignee] [📁 Project]     │
│ [🏷 Labels] [···]                                       │
├─────────────────────────────────────────────────────────┤
│ [📎]                    [◻ Create more] [Create issue]  │
└─────────────────────────────────────────────────────────┘
```

**Top bar:**
- Breadcrumb showing context: project key (or company key) `›` "New issue".
- "Save as draft" button.
- Expand icon (open as full page instead of modal).
- Close `×`.

**Body:**
- Title field: large input, placeholder "Issue title". Auto-focused on open.
- Description: markdown editor below, placeholder "Add a description...". Expandable.

**Property chips (bottom bar):**
- Compact row of property buttons. Each opens a dropdown to set that property.
- Default chips shown: Status (defaults to Todo), Priority, Assignee, Project, Labels.
- `···` more button reveals: Goal, Start date, Target date, Billing code, Parent issue.

**Footer:**
- Attachment button (paperclip icon).
- "Create more" toggle — when on, creating an issue clears the form and stays open for rapid entry.
- "Create issue" primary button.

**Behavior:**
- `Cmd+Enter` submits the form.
- If opened from within a project context, the project is pre-filled.
- If opened from a specific status group's `+` button, that status is pre-filled.
- The slug/key is auto-generated from the project prefix + incrementing number (shown in breadcrumb).

### 5.5 Issue Board View (Kanban)

Accessible via Display dropdown → Board layout.

Columns represent statuses: Backlog | Todo | In Progress | In Review | Done

Each card shows:
- Issue key (muted)
- Title (primary text)
- Priority icon (bottom-left)
- Assignee avatar (bottom-right)

Cards are draggable between columns. Dragging a card to a new column changes its status (with transition validation — invalid transitions show an error toast).

Each column header has a `+` button to create a new issue in that status.

---

## 6. Projects

### 6.1 Project List View

Similar to the issue list but for projects.

```
┌─────────────────────────────────────────────────────────┐
│ Projects                                [+ New project] │
├─────────────────────────────────────────────────────────┤
│ [icon] Paperclip Auth     Backlog     CTO     Feb 20   │
│ [icon] Marketing Site     In Progress CMO     Mar 01   │
│ [icon] API v2             Planned     CTO     Mar 15   │
└─────────────────────────────────────────────────────────┘
```

Each row: project icon (colored hexagon), name, status badge, lead agent, target date.

### 6.2 Project Detail View (Three-Pane)

Uses the same three-pane layout as issue detail.

**Breadcrumb tabs:** Overview | Updates | Issues | Settings

**Overview tab (middle pane):**
- Project icon + name (editable)
- Description (markdown, editable)
- Inline properties bar: `[◌ Backlog] [--- No priority] [👤 Lead] [📅 Target date] [🏢 Team] [···]`
- "Resources" section: linked documents, URLs
- "Write first project update" CTA (for project updates/status posts)
- Description (markdown body)
- Milestones section (collapsible): list of milestone markers with date and status

**Issues tab:** filtered issue list showing only issues in this project. Same controls as the main issues view.

**Right pane (properties):** Status, Priority, Lead, Members, Start date, Target date, Teams, Labels, Goal link.

**Activity section:** at the bottom of the properties panel.

---

## 7. Goals

### 7.1 Goal List View

Goals are displayed as a hierarchical tree, since goals have parent-child relationships.

```
┌─────────────────────────────────────────────────────────┐
│ Goals                                    [+ New goal]   │
├─────────────────────────────────────────────────────────┤
│ ▼ 🎯 Build the #1 AI note-taking app    Company  Active│
│   ▼ 🎯 Grow signups to 10k              Team     Active│
│       🎯 Launch marketing campaign       Agent  Planned │
│       🎯 Optimize onboarding funnel      Agent  Planned │
│   ▼ 🎯 Ship v2.0 with AI features       Team     Active│
│       🎯 Implement smart search          Task   Planned │
│       🎯 Build auto-summarization        Task   Planned │
└─────────────────────────────────────────────────────────┘
```

Each row: expand chevron (if has children), target icon, title, level badge (Company/Team/Agent/Task), status badge.

Indentation reflects hierarchy. Clicking a goal opens its detail view.

### 7.2 Goal Detail View

Three-pane layout. Middle pane shows title, description, child goals, and linked projects. Right pane shows properties (level, status, owner agent, parent goal) and activity.

---

## 8. Dashboard

The dashboard is the company health overview. Shown when clicking "Dashboard" in the Company section.

### 8.1 Layout

```
┌──────────┬──────────────────────────────────────────────┐
│          │ Dashboard                                     │
│ Sidebar  │                                               │
│          │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────┐│
│          │ │ Agents   │ │ Tasks   │ │ Costs   │ │Apprvl││
│          │ │ 12 total │ │ 47 open │ │ $234.50 │ │ 3    ││
│          │ │ 8 active │ │ 12 prog │ │ 67% bud │ │pending│
│          │ │ 2 paused │ │ 3 block │ │         │ │      ││
│          │ │ 1 error  │ │ 28 done │ │         │ │      ││
│          │ └─────────┘ └─────────┘ └─────────┘ └──────┘│
│          │                                               │
│          │ ┌────────────────────┐ ┌─────────────────────┐│
│          │ │ Recent Activity    │ │ Stale Tasks          ││
│          │ │ ...                │ │ ...                   ││
│          │ └────────────────────┘ └─────────────────────┘│
└──────────┴──────────────────────────────────────────────┘
```

**Top row: Metric cards** (4 across)
1. **Agents** — total, active, running, paused, error counts. Each with colored dots.
2. **Tasks** — open, in progress, blocked, done counts.
3. **Costs** — month-to-date spend in dollars, budget utilization percentage with a mini progress bar.
4. **Approvals** — pending count (clickable to navigate to Inbox, which is the primary approval interaction point).

**Bottom row: Detail panels** (2 across)
5. **Recent Activity** — last ~10 activity log entries, compact timeline format.
6. **Stale Tasks** — tasks that have been in progress for too long without updates. Each shows issue key, title, assignee, time since last activity.

All cards and panels are clickable to navigate to their respective full pages.

---

## 9. Org Chart

Interactive visualization of the agent reporting hierarchy.

### 9.1 Tree View

```
                    ┌─────────┐
                    │ CEO     │
                    │ running │
                    └────┬────┘
            ┌────────────┼────────────┐
       ┌────┴────┐  ┌────┴────┐  ┌───┴─────┐
       │ CTO     │  │ CMO     │  │ CFO     │
       │ active  │  │ idle    │  │ paused  │
       └────┬────┘  └────┬────┘  └─────────┘
       ┌────┴────┐  ┌────┴────┐
       │ Dev-1   │  │ Mktg-1  │
       │ running │  │ idle    │
       └─────────┘  └─────────┘
```

Each node shows:
- Agent name
- Role/title (smaller text)
- Status dot (colored by agent status)
- Agent avatar (bot icon with unique color per agent)

Nodes are clickable to navigate to agent detail.

### 9.2 Interactions

- Zoom/pan with mouse wheel and drag.
- Click a node to select it — shows a brief tooltip with key info (last heartbeat, current task, spend).
- Double-click a node to navigate to agent detail page.
- Right-click node for context menu: View, Pause, Resume, Invoke heartbeat, Edit.

---

## 10. Agents

### 10.1 Agent List View

```
┌─────────────────────────────────────────────────────────────────┐
│ Agents                                          [+ New agent]   │
├─────────────────────────────────────────────────────────────────┤
│ [🤖] CEO           ceo        ● Running   $45.20/$100   2m ago │
│ [🤖] CTO           cto        ● Active    $23.10/$100   5m ago │
│ [🤖] Dev-1         engineer   ○ Idle      $12.40/$50   15m ago │
│ [🤖] CMO           marketing  ○ Idle      $8.30/$50    30m ago │
│ [🤖] DevOps        devops     ⚠ Paused    $31.00/$50    1h ago │
└─────────────────────────────────────────────────────────────────┘
```

Columns: Avatar/icon, Name, Role, Status (with colored dot), Cost (spent/budget this month), Last Heartbeat (relative time).

Clicking a row navigates to agent detail.

### 10.2 Agent Detail View (Three-Pane)

**Breadcrumb tabs:** Overview | Heartbeats | Issues | Costs

**Overview (middle pane):**
- Agent name + role
- Capabilities description
- Adapter type + config summary
- Current task (if any)
- Reports to: [clickable agent name]
- Direct reports: list of agents

**Heartbeats tab:** table of heartbeat runs — time, source (manual/scheduler), status, duration, error (if any). Invoke button at top.

**Issues tab:** issues assigned to this agent.

**Costs tab:** cost breakdown for this agent — by model, by time period, with budget progress bar.

**Right pane properties:** Status, Role, Title, Reports To, Adapter Type, Context Mode, Budget (monthly), Spent (monthly), Last Heartbeat.

**Quick actions** in breadcrumb bar: [Pause] [Resume] [Invoke Heartbeat] [···]

---

## 11. Approvals (Contextual, Not Standalone)

Approvals are governance gates — decisions the board must make (hire an agent, approve a CEO strategy). They are NOT work items. Their data model stays separate from issues (different status machine, side-effect triggers, unstructured payload). But they don't need their own top-level nav entry.

### 11.1 Where Approvals Surface

**1. Inbox (primary).** Pending approvals are the highest-priority inbox items. The board operator sees them front and center with inline approve/reject actions (see Section 14).

**2. Dashboard metric card.** The "Pending Approvals" card shows the count and links to the full approvals list.

**3. Inline on entity pages.** When an entity was created via an approval, the detail page shows a contextual banner:
- Agent detail page: `"Hired via approval — requested by CEO on Feb 15"` with a link to the approval record.
- An agent in `pending` status (not yet created) could show: `"Pending approval — requested by CEO"` with approve/reject actions inline.

**4. Activity log.** Approval events (created, approved, rejected) appear in the activity timeline like any other event.

### 11.2 Approvals List Page (`/approvals`)

This page still exists — it's the "See all" destination from Inbox and Dashboard. But it's not in the sidebar.

```
┌─────────────────────────────────────────────────────────┐
│ Approvals    [Pending] [Approved] [Rejected] [All]      │
├─────────────────────────────────────────────────────────┤
│ 🟡 Hire Agent: "Marketing Analyst"    CEO    2h ago     │
│ 🟡 CEO Strategy: "Q2 Growth Plan"    CEO    4h ago     │
│ 🟢 Hire Agent: "DevOps Engineer"     CTO    1d ago     │
└─────────────────────────────────────────────────────────┘
```

Status tabs filter by approval status. Each row: status dot, type, title/summary (from payload), requester, relative time.

### 11.3 Approval Detail View

Three-pane layout. Middle pane renders the approval payload nicely based on type:

**`hire_agent` type:** Shows proposed agent name, role, title, reports-to, capabilities, adapter config, budget. Essentially a preview of the agent that will be created.

**`approve_ceo_strategy` type:** Shows the strategy text, proposed goal breakdown, initial task structure.

For pending approvals, prominent action buttons at the top of the middle pane:
```
┌─────────────────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Decision note (optional): _________________________ │ │
│ │                          [✕ Reject]  [✓ Approve]    │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                         │
│ Hire Agent Request                                      │
│ ─────────────────                                       │
│ Name: Marketing Analyst                                 │
│ Role: marketing                                         │
│ Reports to: CMO                                         │
│ Budget: $100/month                                      │
│ ...                                                     │
└─────────────────────────────────────────────────────────┘
```

Right pane: Type, Status, Requested by, Requested at, Decided by, Decided at, Decision note. Activity timeline below.

---

## 12. Costs

### 12.1 Cost Dashboard

```
┌─────────────────────────────────────────────────────────┐
│ Costs                               Feb 2026            │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────┐│
│ │ Month-to-date: $234.50 / $500.00  [====-------] 47% ││
│ └──────────────────────────────────────────────────────┘│
│                                                         │
│ By Agent                              By Project        │
│ ┌──────────────────────┐  ┌──────────────────────┐      │
│ │ CEO        $45.20    │  │ Auth       $67.30    │      │
│ │ CTO        $23.10    │  │ Marketing  $34.50    │      │
│ │ Dev-1      $12.40    │  │ API v2     $12.00    │      │
│ │ ...                  │  │ ...                  │      │
│ └──────────────────────┘  └──────────────────────┘      │
│                                                         │
│ Recent Cost Events                                      │
│ ┌──────────────────────────────────────────────────────┐│
│ │ CEO  openai/gpt-5  1,234 in / 567 out  $0.89  2m ago│
│ │ ...                                                   │
│ └──────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘
```

Top: company-wide budget progress bar (large, prominent).

Two side-by-side tables: breakdown by agent and by project. Each row shows entity name and spend amount.

Bottom: recent cost events table with agent, provider/model, token counts, cost, and timestamp.

---

## 13. Activity Log

A chronological, filterable audit trail.

```
┌─────────────────────────────────────────────────────────┐
│ Activity                            [Filter by type ▼]  │
├─────────────────────────────────────────────────────────┤
│ 🤖 CEO created issue CLIP-12 "Fix auth"      2 min ago │
│ 👤 Board approved hire "Marketing Analyst"    5 min ago │
│ 🤖 CTO changed CLIP-8 status → In Progress  10 min ago │
│ ⚙  System paused agent DevOps (budget limit) 15 min ago│
│ 🤖 Dev-1 commented on CLIP-5                30 min ago │
│ ...                                                     │
└─────────────────────────────────────────────────────────┘
```

Each entry: actor icon (bot for agent, user for board, gear for system), actor name, action description with entity links, relative timestamp.

Filterable by: actor type (agent/user/system), entity type (issue/agent/project/etc), action type, time range.

Infinite scroll with "Load more" fallback.

---

## 14. Inbox

The inbox is the board operator's primary action center. It aggregates everything that needs human attention, with approvals as the highest-priority category.

### 14.1 Inbox List View

```
┌─────────────────────────────────────────────────────────┐
│ Inbox                               [Mark all read]     │
├─────────────────────────────────────────────────────────┤
│ APPROVALS                        See all approvals →    │
│ ● 🛡 Hire Agent: "Marketing Analyst"                    │
│ │  Requested by CEO · 2h ago                            │
│ │  Role: marketing · Reports to: CMO · Budget: $100/mo  │
│ │  [✕ Reject]  [✓ Approve]                              │
│ │                                                       │
│ ● 🛡 CEO Strategy: "Q2 Growth Plan"                     │
│ │  Requested by CEO · 4h ago                            │
│ │  [View details →]                                     │
│                                                         │
│ ALERTS                                                  │
│ ● 🔴 Agent Error: DevOps heartbeat failed       1h ago  │
│ ● ⚠  Budget Alert: CEO at 80% monthly budget   3h ago  │
│                                                         │
│ STALE WORK                                              │
│   ⏰ CLIP-3 "Set up CI pipeline" — no update in 24h     │
│   ⏰ CLIP-7 "Write tests" — no update in 36h            │
└─────────────────────────────────────────────────────────┘
```

### 14.2 Inbox Categories

Items are grouped by category, with the most actionable items first:

**Approvals pending** (top priority). Each approval item shows:
- Shield icon + approval type + title
- Requester + relative timestamp
- Key payload summary (1 line — agent name/role for hires, plan title for strategies)
- Inline **[Approve]** and **[Reject]** buttons for simple approvals (hire_agent). Clicking Approve/Reject shows a brief confirmation with an optional decision note field.
- **[View details →]** link for complex approvals (approve_ceo_strategy) that need full review before deciding.
- "See all approvals →" link in the category header navigates to `/approvals`.

**Alerts.** Agent errors (failed heartbeats, error status) and budget alerts (agents or company approaching 80% or 100% limits). Each links to the relevant agent or cost page.

**Stale work.** Tasks in `in_progress` or `todo` with no activity (no comments, no status changes) beyond a configurable threshold (default: 24h). Each shows issue key, title, and time since last activity. Clicking navigates to the issue.

### 14.3 Inbox Behavior

- Unread items have a filled blue dot indicator on the left.
- Clicking an item marks it as read.
- Approvals disappear from the inbox once approved/rejected (they move to the resolved state).
- Alerts disappear when the underlying condition is resolved (agent resumed, budget increased).
- The sidebar badge count reflects total unresolved inbox items.
- Inbox is computed from live data (pending approvals query + alert conditions), not a separate notification table. This keeps it simple for V1.

---

## 15. Search (Cmd+K Modal)

Global search accessible via `Cmd+K` or the sidebar search icon.

```
┌─────────────────────────────────────────────────────────┐
│ 🔍 Search issues, agents, projects...                   │
├─────────────────────────────────────────────────────────┤
│ Recent                                                  │
│   📋 CLIP-42 Fix user authentication bug                │
│   🤖 CEO                                                │
│   📁 Auth project                                       │
├─────────────────────────────────────────────────────────┤
│ Actions                                                 │
│   ✏️  Create new issue                         C        │
│   🤖 Create new agent                                   │
│   📁 Create new project                                 │
└─────────────────────────────────────────────────────────┘
```

- Type-ahead search across all entity types (issues, agents, projects, goals).
- Results grouped by type with icons.
- Recent items shown when input is empty.
- Quick actions section at the bottom.
- Arrow keys to navigate, Enter to select, Escape to close.

---

## 16. Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Cmd+K` | Open search |
| `C` | Create new issue |
| `Cmd+Enter` | Submit form (in modals) |
| `Escape` | Close modal / deselect |
| `[` | Toggle sidebar collapsed |
| `]` | Toggle properties panel |
| `J` / `K` | Navigate up/down in lists |
| `Enter` | Open selected item |
| `Backspace` | Go back |
| `S` | Toggle status on selected issue |
| `X` | Toggle checkbox selection |
| `Cmd+A` | Select all (in list context) |

---

## 17. Responsive Behavior

- **>1400px:** Full three-pane layout (sidebar + main + properties).
- **1024-1400px:** Sidebar collapses to icons. Properties panel available via toggle.
- **<1024px:** Sidebar hidden (hamburger menu). Properties panel hidden (toggle or tab).

The properties panel is always dismissible — it should never block the main content.

---

## 18. Empty States

Every list view should have a thoughtful empty state:

- **No issues:** "No issues yet. Create your first issue to start tracking work." with a `[Create issue]` button.
- **No agents:** "No agents in this company. Create an agent to start building your team." with a `[Create agent]` button.
- **No company selected:** "Select a company to get started." with a company switcher or `[Create company]` button.

Empty states should use a muted illustration (simple line art, not cartoons) and a single call-to-action.

---

## 19. Loading and Error States

- **Loading:** Skeleton placeholders matching the layout of the expected content (not spinners). Skeleton blocks animate with a subtle shimmer.
- **Error:** Inline error message with a retry button. Never a full-page error unless the app itself is broken.
- **Conflict (409):** Toast notification: "This issue was updated by another user. Refresh to see changes." with a [Refresh] action.
- **Optimistic updates:** Status changes and property edits should update immediately in the UI, with rollback on failure.

---

## 20. Component Library

Build on top of shadcn/ui components with these customizations:

| Component | Base | Customization |
|-----------|------|---------------|
| StatusBadge | Badge | Colored dot + label, entity-specific palettes |
| PriorityIcon | custom | SVG circles with fills matching priority |
| EntityRow | custom | Standardized list row with hover/select states |
| PropertyEditor | custom | Label + inline-editable value with dropdown |
| CommentThread | custom | Avatar + author + timestamp + markdown body |
| BreadcrumbBar | Breadcrumb | Integrated with router, tabs, and entity actions |
| CommandPalette | Dialog | Cmd+K search with type-ahead and actions |
| FilterBar | custom | Composable filter chips with add/remove |
| SidebarNav | custom | Grouped, collapsible, badge-supporting nav |

---

## 21. URL Structure

All routes are company-scoped after company selection (company context stored in React context, not URL):

```
/                           → redirects to /dashboard
/dashboard                  → company dashboard
/inbox                      → inbox / attention items
/my-issues                  → board operator's issues
/issues                     → issue list
/issues/:issueId            → issue detail
/projects                   → project list
/projects/:projectId        → project detail (overview tab)
/projects/:projectId/issues → project issues
/goals                      → goal hierarchy
/goals/:goalId              → goal detail
/org                        → org chart
/agents                     → agent list
/agents/:agentId            → agent detail
/approvals                  → approval list
/approvals/:approvalId      → approval detail
/costs                      → cost dashboard
/activity                   → activity log
/companies                  → company management (list/create)
/settings                   → company settings
```

---

## 22. Implementation Priority

### Phase 1: Shell and Navigation
1. Sidebar redesign (grouped sections, icons, company switcher, badges)
2. Breadcrumb bar component
3. Three-pane layout system
4. Cmd+K search modal
5. Install `lucide-react`

### Phase 2: Issue Management (Core)
6. Issue list view with grouping, filtering, status circles
7. Issue detail view (three-pane with properties panel)
8. New issue modal
9. Issue comments
10. Bulk selection and actions
11. Kanban board view

### Phase 3: Entity Detail Views
12. Project list + detail view
13. Goal hierarchy view
14. Agent list + detail view

### Phase 4: Company-Level Views
15. Inbox with inline approval actions (primary approval UX)
16. Dashboard redesign with metric cards
17. Org chart interactive visualization
18. Cost dashboard
19. Activity log with filtering
20. Approvals list page (accessed via Inbox "See all", not sidebar)

### Phase 5: Polish
21. Keyboard shortcuts
22. Responsive behavior
23. Empty states and loading skeletons
24. Error handling and toasts
25. Saved views (custom filters)
