# 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 | | ----------------------------------------------------------------------- | | | | | | | +=============================================================================+ ``` ### 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 `` 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 `` 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 `` 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 ``` +------------------------------------------------------------------------+ | [pencil] | | [external-link] | | | | Default branch: [pencil] | | Initiatives: , | [0 if none] [trash] | +------------------------------------------------------------------------+ ``` - Project name: `text-sm font-semibold`. The `[pencil]` next to it toggles inline name editing. - Project URL: clickable `` 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 ``` +------------------------------------------------------------------------+ | text-sm font-semibold | | text-xs text-muted-fg | | 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.