# Settings Pages (v2)

### Route: `/settings/*`
### Source: `packages/web/src/routes/settings.tsx`, `packages/web/src/routes/settings/*.tsx`

---

## v1 -> v2 Changes

| Aspect | v1 | v2 |
|--------|----|----|
| Sub-pages | Health Check, Projects (2 pages) | Health Check, Accounts, Projects, Workspace, Danger Zone (5 pages) |
| Nav style | Plain text tabs | Icon + label tabs with active indicator |
| Projects error state | None | `[AlertCircle]` + "Failed to load projects" + `[Retry]` |
| Delete button | Immediate (with `window.confirm`) | Shows `[spinner]` during mutation, toast "Deleted" on success before card animates out |
| Health Check | Basic server status only | Server vitals (uptime, PID, process count, DB size), version info |
| Accounts | Embedded in Health Check | Dedicated sub-page with add/remove actions, exhaustion status, usage bars |
| Workspace | None | `.cwrc` settings: workspace name, default execution mode |
| Danger Zone | None | Reset workspace, clear all data, destructive operations |

---

## Settings Layout

```
+=============================================================================+
| [CW]  Initiatives  Agents  [*Settings*]                 [cmd-k]  [sun]  * |
+=============================================================================+
|                                                                             |
|  Settings                                                                   |
|  [heart] Health   [key] Accounts   [folder] Projects                       |
|  [sliders] Workspace   [alert-triangle] Danger Zone                        |
|  -----------------------------------------------------------------------    |
|                                                                             |
|                        <Settings Page Outlet>                               |
|                                                                             |
+=============================================================================+
```

### Sub-page nav anatomy

- Each tab: Lucide icon (16px) + label, `gap-1.5`
- Active: `bg-muted text-foreground font-medium rounded-md px-3 py-1.5`
- Inactive: `text-muted-foreground hover:text-foreground px-3 py-1.5`
- Danger Zone tab: icon and text use `text-destructive` when active (not `text-foreground`)
- Tabs wrap to two rows naturally on narrower viewports (no breakpoint logic)

### Sub-page icons

| Sub-page | Lucide Icon | Route |
|----------|-------------|-------|
| Health | `HeartPulse` | `/settings/health` |
| Accounts | `KeyRound` | `/settings/accounts` |
| Projects | `FolderGit2` | `/settings/projects` |
| Workspace | `SlidersHorizontal` | `/settings/workspace` |
| Danger Zone | `AlertTriangle` | `/settings/danger` |

`/settings` redirects to `/settings/health`.

---

## Health Check -- Default State

```
+=============================================================================+
|  Settings                                                                   |
|  [*heart*] Health   [key] Accounts   [folder] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                    [ Refresh ]              |
|                                                                             |
|  SERVER VITALS                                                              |
|  +-----------------------------------------------------------------------+  |
|  |  [CheckCircle] Running                                                |  |
|  |                                                                       |  |
|  |  Uptime          2d 14h 32m          PID            48291             |  |
|  |  Started          2026-03-01 08:14   Process count  3                 |  |
|  |  Version         0.9.2               Database       4.2 MB            |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
|  REGISTERED PROJECTS (3)                                                    |
|  +-----------------------------------------------------------------------+  |
|  |  [CheckCircle] backend      github.com/org/backend-api    Clone found |  |
|  |  [CheckCircle] frontend     github.com/org/frontend-app   Clone found |  |
|  |  [XCircle]     shared       github.com/org/shared-lib     Clone missing| |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

### Server vitals card anatomy

Two-column key/value grid inside a single card. Keys are `text-xs text-muted-foreground`, values are `text-sm font-mono`.

| Field | Source | Notes |
|-------|--------|-------|
| Status | Always "Running" (if the page loads, the server is up) | `[CheckCircle]` success icon |
| Uptime | `server.uptime` from `systemHealthCheck` | Formatted as `Xd Xh Xm` |
| Started | `server.startedAt` | ISO datetime, formatted to locale |
| PID | `process.pid` from `status` endpoint | Integer |
| Process count | `health.processCount` | Active agent processes |
| Version | Package version from build | `font-mono` |
| Database | File size of SQLite `.db` file | Formatted as `X.X MB` |

The projects summary in health check is a read-only compact list (no edit actions). For full project management, use the Projects sub-page.

### Health Check -- Error State

```
+=============================================================================+
|  Settings                                                                   |
|  [*heart*] Health   [key] Accounts   [folder] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                                             |
|                        [AlertCircle]                                        |
|                   Failed to load health data                                |
|                                                                             |
|                         [ Retry ]                                           |
|                                                                             |
+=============================================================================+
```

Uses shared `<ErrorState>` component with `onRetry`.

---

## Accounts -- Default State

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [*key*] Accounts   [folder] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                    [ Refresh ]  [ Add ]    |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |  [CheckCircle] alice@company.com                                      |  |
|  |  [claude]  [Pro]                    2 agents (1 active)  Available    |  |
|  |                                                                       |  |
|  |  Session (5h)  [========--------]  62%          resets in 2h 14m      |  |
|  |  Weekly (7d)   [=====-----------]  38%          resets in 4d 11h      |  |
|  |                                                       [trash]         |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |  [AlertTriangle] bob@company.com                                      |  |
|  |  [claude]  [Max]                    1 agent (0 active)   Exhausted    |  |
|  |                                     until 2:45 PM                     |  |
|  |                                                                       |  |
|  |  Session (5h)  [================]  98%          resets in 0h 32m      |  |
|  |  Weekly (7d)   [=============---]  88%          resets in 1d 6h       |  |
|  |                                                       [trash]         |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

### Account card anatomy

Reuses the existing `<AccountCard>` component with two additions:
1. A `[trash]` delete button (bottom-right of card) with Shift+click bypass pattern
2. Exhaustion status uses `status-warning-*` tokens when exhausted

### Add Account dialog

`[ Add ]` opens a dialog:

```
+----------------------------------------------+
|  Add Account                           [x]   |
|                                               |
|  Provider   [claude_____________v]            |
|  Email      [_____________________]           |
|                                               |
|  [ Cancel ]                    [ Add Account ]|
+----------------------------------------------+
```

- Provider dropdown populated from `listProviderNames` tRPC query
- Email is a text input, required
- On success: toast "Account added", invalidate `listAccounts`

### Accounts -- Empty State

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [*key*] Accounts   [folder] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |                                                                       |  |
|  |                [KeyRound]                                             |  |
|  |            No accounts registered                                     |  |
|  |      Use "cw account add" or click below.                            |  |
|  |                                                                       |  |
|  |                [ Add Account ]                                        |  |
|  |                                                                       |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

Uses shared `<EmptyState>` with `KeyRound` icon.

---

## Projects -- Default State

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [key] Accounts   [*folder*] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                    [ Register Project ]     |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |  backend  [pencil]                                                    |  |
|  |  github.com/org/backend-api  [external-link]                         |  |
|  |                                                                       |  |
|  |  Default branch: main  [pencil]                                       |  |
|  |  Initiatives: Auth Overhaul, Payments                     [trash]     |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |  frontend  [pencil]                                                   |  |
|  |  github.com/org/frontend-app  [external-link]                        |  |
|  |                                                                       |  |
|  |  Default branch: develop  [pencil]                                    |  |
|  |  Initiatives: Auth Overhaul                               [trash]     |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

### Project card anatomy

```
+------------------------------------------------------------------------+
|  <project-name>  [pencil]                                              |
|  <project-url>  [external-link]                                        |
|                                                                        |
|  Default branch: <branch>  [pencil]                                    |
|  Initiatives: <name>, <name>   |   [0 if none]              [trash]    |
+------------------------------------------------------------------------+
```

- Project name: `text-sm font-semibold`. The `[pencil]` next to it toggles inline name editing.
- Project URL: clickable `<a>` link, opens in new tab. `[external-link]` (ExternalLink icon, 12px) after URL. `text-xs text-muted-foreground hover:text-foreground underline-offset-2 hover:underline`.
- Default branch `[pencil]`: click to toggle inline branch editing (same as v1).
- Initiatives row: `text-xs text-muted-foreground`. Each initiative name is a link to `/initiatives/$id`. Shows "No initiatives" in dim text if none linked. Data from a new `getProjectInitiatives` query or joined from existing data.
- `[trash]` (Trash2 icon): click triggers `window.confirm()`; Shift+click bypasses. On successful delete, shows `toast.success("Project deleted")` before card animates out with `animate-out fade-out slide-out-to-left` (150ms).

### Inline name editing (click pencil next to name)

```
|  [backend__________]  [enter to save / esc to cancel]                  |
```

Same pattern as branch editing. Validates uniqueness client-side before save.

### Inline branch editing (click pencil next to branch)

```
|  Default branch: [develop________]  [enter to save / esc to cancel]   |
```

---

## Projects -- Error State

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [key] Accounts   [*folder*] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                                             |
|                        [AlertCircle]                                        |
|                   Failed to load projects                                   |
|                                                                             |
|                         [ Retry ]                                           |
|                                                                             |
+=============================================================================+
```

- `[AlertCircle]` icon: `h-8 w-8 text-destructive`
- Error message: `text-sm text-destructive`
- `[ Retry ]` button: `variant="outline" size="sm"`, calls `projectsQuery.refetch()`
- `[ Register Project ]` button is hidden during error state

---

## Projects -- Delete In Progress

```
+------------------------------------------------------------------------+
|  backend  [pencil]                                                     |
|  github.com/org/backend-api  [external-link]                          |
|                                                                        |
|  Default branch: main  [pencil]                                        |
|  Initiatives: Auth Overhaul                              [spinner]     |
+------------------------------------------------------------------------+
```

- `[trash]` icon replaced by `[spinner]` (`Loader2` with `animate-spin`) during `deleteMutation.isPending`
- Button is `disabled` to prevent double-click
- Only the card being deleted shows the spinner; other cards remain interactive
- On success: `toast.success("Project deleted")` fires, then the card animates out (`animate-out fade-out slide-out-to-left`, 150ms duration)

---

## Projects -- Empty State

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [key] Accounts   [*folder*] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |                                                                       |  |
|  |                    No projects registered                             |  |
|  |                                                                       |  |
|  |                    [ Register Project ]                                |  |
|  |                                                                       |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

- `[ Register Project ]` button opens `RegisterProjectDialog`
- The top-right `[ Register Project ]` button is hidden when the empty state CTA is visible

---

## Projects -- Loading State

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [key] Accounts   [*folder*] Projects   ...               |
|  -----------------------------------------------------------------------    |
|                                                    [ Register Project ]     |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  | ░░░░░░░░░░░░░░                                                       |  |
|  | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░                                        |  |
|  |                                                                       |  |
|  | ░░░░░░░░░░░░░░░░░░░░░  ░░                            ░░              |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  | ░░░░░░░░░░░░░░                                                       |  |
|  | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░                                        |  |
|  |                                                                       |  |
|  | ░░░░░░░░░░░░░░░░░░░░░  ░░                            ░░              |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

Skeleton cards mirror project card anatomy: name line, URL line, branch line with
pencil/trash placeholders. Shimmer animation sweeps left-to-right on a 1.5s loop.

---

## Workspace -- Default State

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [key] Accounts   [folder] Projects                       |
|  [*sliders*] Workspace   [alert-triangle] Danger Zone                      |
|  -----------------------------------------------------------------------    |
|                                                                             |
|  GENERAL                                                                    |
|  +-----------------------------------------------------------------------+  |
|  |  Workspace root     /Users/dev/my-project                             |  |
|  |  Config file        .cwrc (version 1)                                 |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
|  EXECUTION DEFAULTS                                                         |
|  +-----------------------------------------------------------------------+  |
|  |  Default mode       [REVIEW v]                                        |  |
|  |                     New initiatives start in this execution mode.      |  |
|  |                                                                       |  |
|  |  Merge approval     [x] Require approval for merge tasks              |  |
|  |                     Agents must get human sign-off before merging.     |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

### Workspace settings fields

| Field | Type | Source | Notes |
|-------|------|--------|-------|
| Workspace root | Read-only | `workspaceRoot` from server context | Display only, not editable |
| Config file | Read-only | Parsed `.cwrc` | Shows filename + version |
| Default mode | Select dropdown | `.cwrc` (future) | `review` or `yolo` |
| Merge approval | Checkbox | `.cwrc` (future) | Default for new initiatives |

These fields require extending the `.cwrc` config schema (currently `{ version: 1 }` only). Until the backend supports these, the section renders as read-only with a "Coming soon" badge on the editable fields.

---

## Danger Zone

```
+=============================================================================+
|  Settings                                                                   |
|  [heart] Health   [key] Accounts   [folder] Projects                       |
|  [sliders] Workspace   [*alert-triangle*] Danger Zone                      |
|  -----------------------------------------------------------------------    |
|                                                                             |
|  [AlertTriangle] These actions are irreversible.                            |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |  Clear all agent data                                                 |  |
|  |  Removes all agent records, log chunks, and output history.           |  |
|  |  Projects, initiatives, and tasks are preserved.                      |  |
|  |                                                       [ Clear Agents ]|  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
|  +-----------------------------------------------------------------------+  |
|  |  Reset workspace                                                      |  |
|  |  Deletes ALL data: initiatives, tasks, agents, accounts, projects.    |  |
|  |  The .cwrc config file and git repos are preserved on disk.           |  |
|  |                                                  [ Reset Workspace ]  |  |
|  +-----------------------------------------------------------------------+  |
|                                                                             |
+=============================================================================+
```

### Danger Zone card anatomy

```
+------------------------------------------------------------------------+
|  <action-title>                              text-sm font-semibold     |
|  <description>                               text-xs text-muted-fg    |
|  <preserved-note>                            text-xs text-muted-fg    |
|                                              [ Destructive Button ]    |
+------------------------------------------------------------------------+
```

- Cards use `border-destructive/30` border tint
- Buttons use `variant="destructive"` styling
- Each button triggers a `window.confirm()` with explicit confirmation text: "Type RESET to confirm"
- Shift+click bypasses (consistent with app-wide pattern)
- Top banner: `[AlertTriangle]` icon with `text-destructive`, `text-sm font-medium`

---

## Source

- `packages/web/src/routes/settings.tsx`
- `packages/web/src/routes/settings/health.tsx`
- `packages/web/src/routes/settings/accounts.tsx` (proposed)
- `packages/web/src/routes/settings/projects.tsx`
- `packages/web/src/routes/settings/workspace.tsx` (proposed)
- `packages/web/src/routes/settings/danger.tsx` (proposed)
- `packages/web/src/components/RegisterProjectDialog.tsx`
- `packages/web/src/components/AccountCard.tsx`
- `packages/web/src/components/AddAccountDialog.tsx` (proposed)

---

## Design Review Notes

### What was improved in this revision

1. **Sub-page expansion (2 to 5 pages).** The original spec only had Health Check and Projects, which was embarrassingly thin for a workspace managing 10+ agents, multiple API accounts, and multiple git repos. Added: Accounts (dedicated), Workspace settings, Danger Zone. Each maps to real backend capabilities that already exist (`accountProcedures`, `.cwrc` config, `systemHealthCheck`).

2. **Health Check redesigned as a vitals dashboard.** The original wireframe said "Health Check: Unchanged" and showed nothing. The implementation (`health.tsx`) already renders server status, accounts, and projects -- but the wireframe never documented any of it. Now specced: server uptime, PID, process count, DB size, version, and a compact project clone status list. Accounts moved out to their own dedicated sub-page (they deserve more than a read-only summary).

3. **Accounts promoted to first-class sub-page.** The codebase already has `AccountCard` with full usage bars, exhaustion tracking, and agent counts. The health check page was cramming all this into a secondary section. Now accounts get their own page with add/remove actions (the tRPC procedures `addAccount` / `removeAccount` already exist), making it actually useful instead of display-only.

4. **Project cards enriched.** Three additions: (a) inline name editing alongside inline branch editing -- if you can edit the branch, you should be able to edit the name; (b) project URL is now a clickable external link (it was just dead text before -- why show a URL you cannot click?); (c) initiative cross-reference row showing which initiatives use this project (answers "can I safely delete this?").

5. **Delete flow improved.** Added explicit toast confirmation ("Project deleted") before card animates out. The spinner-only approach was correct for preventing double-click, but the user gets zero feedback that the delete succeeded -- the card just vanishes. A brief toast bridges that gap.

6. **Sub-page navigation given visual identity.** Plain text tabs for 5+ items is a mess. Added Lucide icons per sub-page with the same active/inactive styling from app-layout nav. Danger Zone gets destructive-red treatment to warn before you even click.

7. **Workspace settings page.** Currently `.cwrc` is `{ version: 1 }` with zero user-facing config. This wireframe establishes the UI surface for workspace-level defaults (execution mode, merge approval) so when the config schema grows, the frontend is ready. Read-only fields (workspace root, config version) provide orientation.

8. **Danger Zone.** Every serious tool needs one. Two graduated destructive actions: clear agent data (preserves structure) and full workspace reset (nuclear option). Confirmation requires typing "RESET" to prevent accidents. The Shift+click bypass pattern still applies for power users.

### What was NOT added (and why)

- **Keyboard shortcuts remapping page**: Skipped. The app has maybe 5 keyboard shortcuts total (tab switching 1-4, Cmd+K). A remapping UI is premature -- there is not enough shortcut surface to justify a settings page. Revisit when shortcuts exceed 15+.

- **Import/export settings**: Skipped. The `.cwrc` file is already a JSON file at the workspace root that can be committed to git. There is nothing else to export -- accounts are per-machine (OAuth tokens), projects are per-workspace. A dedicated import/export UI would be solving a problem that does not exist yet.

- **Notification preferences**: Skipped. The app has no notification system. Adding a preferences page for a feature that does not exist is pure wireframe theater.

- **Provider configuration page**: Skipped. Provider presets are code-level config (`src/agent/providers/presets.ts`) with 7 built-in providers. There is no user-facing need to edit provider CLI args or session ID extraction patterns. If custom providers are needed later, that is a CLI config concern, not a settings UI concern.
