purple-ai 0.0.2 → 0.0.4

package/purple-CLIent-technical-PRD.md

@@ -0,0 +1,2514 @@
+# Purple CLIent - Technical PRD
+
+Version: 1.4
+Last Updated: 2026-01-12
+
+---
+
+## 1. Overview
+
+Purple CLIent is a terminal-based workspace manager for the Purple AI agent workflow. It provides a polished TUI for managing workspaces, teams, and feature development sessions that integrate with Claude Code.
+
+**Core Value Proposition:**
+- Elegant workspace and team management
+- Seamless Claude Code integration with status bar overlay
+- Streamlined plugin-driven development workflow (spec → architecture → implementation)
+
+---
+
+## 2. Tech Stack
+
+| Component | Technology | Rationale |
+|-----------|------------|-----------|
+| Language | **Go 1.22+** | Single binary, fast startup, excellent cross-platform support |
+| TUI Framework | **Bubbletea** | Industry-standard Go TUI, composable, well-maintained |
+| Forms/Prompts | **Huh** | Built on Bubbletea, first-class form support |
+| Styling | **Lipgloss** | Declarative styling for terminal UIs |
+| PTY | **creack/pty** | Go PTY library for spawning Claude Code |
+| HTTP Client | **net/http** (stdlib) | Backend API calls |
+| Auth | **Purple Backend** (proxy to Supabase) | Client never talks to Supabase directly |
+| Distribution | **npm wrapper + Go binary** | `npx purple-ai` convenience |
+
+---
+
+## 3. Architecture
+
+### 3.1 Package Structure
+
+```
+purple-client/
+├── cmd/
+│   └── purple/
+│       └── main.go                 # Entry point, CLI flag handling
+├── internal/
+│   ├── auth/
+│   │   ├── auth.go                 # ensureAuth, checkAuth, logout
+│   │   ├── storage.go              # Keychain/file token storage
+│   │   └── types.go                # AuthSession, credentials types
+│   ├── workspace/
+│   │   ├── workspace.go            # Create, load, detect workspace
+│   │   ├── detector.go             # Find purple.json in dir tree
+│   │   ├── config.go               # purple.json read/write
+│   │   └── types.go                # Workspace types
+│   ├── git/
+│   │   ├── repos.go                # List repos (gh CLI or manual)
+│   │   ├── clone.go                # Clone repos to workspace
+│   │   └── detect.go               # Check gh CLI availability
+│   ├── session/
+│   │   ├── session.go              # Feature session management (local only)
+│   │   ├── scanner.go              # Scan workbench/documentation for sessions
+│   │   └── types.go                # Session types
+│   ├── plugins/
+│   │   ├── plugins.go              # Plugin installation and updates
+│   │   ├── catalog.go              # Available plugins from backend
+│   │   ├── installer.go            # Extract plugins to .claude/
+│   │   └── types.go                # Plugin, PluginSummary types
+│   ├── standards/
+│   │   ├── standards.go            # Standards sync logic
+│   │   ├── sync.go                 # Download from API, write to local
+│   │   ├── upload.go               # Upload local changes to API
+│   │   └── types.go                # Standard types
+│   ├── claude/
+│   │   ├── pty.go                  # PTY spawning and management
+│   │   ├── hooks.go                # Hook registration and handling
+│   │   └── commands.go             # Launch with specific commands
+│   ├── tui/
+│   │   ├── app.go                  # Main Bubbletea app model
+│   │   ├── views/
+│   │   │   ├── welcome.go          # Welcome/logo screen
+│   │   │   ├── auth.go             # Login/Register forms
+│   │   │   ├── workspace_picker.go # Workspace selection
+│   │   │   ├── workspace_create.go # New workspace flow
+│   │   │   ├── repo_picker.go      # Multi-select repo list
+│   │   │   ├── plugin_picker.go    # Plugin selection
+│   │   │   ├── session_picker.go   # Feature session list
+│   │   │   └── loading.go          # Progress/spinner views
+│   │   ├── components/
+│   │   │   ├── statusbar.go        # Bottom status bar
+│   │   │   └── header.go           # Top header component
+│   │   └── styles.go               # Lipgloss style definitions
+│   ├── server/
+│   │   ├── status.go               # HTTP server for MCP communication
+│   │   └── types.go                # Status update types
+│   ├── api/
+│   │   ├── client.go               # Backend API client
+│   │   ├── auth.go                 # /auth/* endpoints
+│   │   ├── user.go                 # /user/* endpoints
+│   │   ├── team.go                 # /team/* endpoints
+│   │   ├── workspace.go            # /workspace/* endpoints
+│   │   ├── repo.go                 # /repo/* endpoints
+│   │   ├── standard.go             # /standard/* endpoints
+│   │   ├── plugin.go               # /plugins/* endpoints
+│   │   └── types.go                # API response types
+│   └── config/
+│       ├── settings.go             # ~/.purple/settings.json
+│       └── paths.go                # Standard path helpers
+├── pkg/
+│   └── version/
+│       └── version.go              # Version info for updates
+├── npm/
+│   ├── package.json                # npm wrapper package
+│   ├── bin/
+│   │   └── purple-ai.js            # Node shim that spawns Go binary
+│   └── platform-packages/          # Platform-specific binary packages
+│       ├── darwin-arm64/
+│       ├── darwin-x64/
+│       └── linux-x64/
+├── go.mod
+├── go.sum
+├── Makefile                        # Build targets for all platforms
+└── README.md
+```
+
+### 3.2 Data Models
+
+#### Local Files
+
+**~/.purple/settings.json** (User-level config - minimal)
+```json
+{
+  "theme": "dark"
+}
+```
+
+**{workspace}/purple.json** (Workspace pointer - minimal)
+```json
+{
+  "workspace_id": "uuid"
+}
+```
+
+All other data (user, team, repos, standards, plugins) is fetched from the API.
+
+#### Token Storage
+
+Tokens stored in OS Keychain (not in settings.json):
+- `purple-ai/access_token`
+- `purple-ai/refresh_token`
+
+#### Session Detection (Local Only)
+
+Sessions are detected by scanning the filesystem:
+```
+{workspace}/workbench/documentation/
+
+Each subdirectory (e.g., 260112-auth-feature/) is a session.
+Session name = folder name
+Status = inferred from contents (has implementation-spec = in-progress, etc.)
+Archived sessions live in /archived/ subfolder
+```
+
+Sessions never sync to backend - they are purely local.
+
+---
+
+## 4. API Integration
+
+### 4.1 Configuration Management
+
+#### Build-time vs Runtime Configuration
+
+For a distributed Go binary, configuration is handled via **build-time constants** with optional **environment variable overrides** for development.
+
+```go
+// internal/config/config.go
+
+package config
+
+import "os"
+
+// Build-time constants (set via ldflags during build)
+var (
+    // Version is set at build time: -ldflags "-X config.Version=1.0.0"
+    Version = "dev"
+
+    // DefaultAPIBaseURL is compiled into the binary
+    DefaultAPIBaseURL = "https://api.purple.ai/api/v1"
+)
+
+// Runtime configuration
+type Config struct {
+    APIBaseURL string
+    Debug      bool
+}
+
+// Load returns the runtime configuration
+// Environment variables override compiled defaults (for development only)
+func Load() *Config {
+    apiURL := DefaultAPIBaseURL
+
+    // Allow override for development (not advertised to users)
+    if envURL := os.Getenv("PURPLE_API_URL"); envURL != "" {
+        apiURL = envURL
+    }
+
+    return &Config{
+        APIBaseURL: apiURL,
+        Debug:      os.Getenv("PURPLE_DEBUG") == "1",
+    }
+}
+```
+
+#### Build Process
+
+```makefile
+VERSION := 1.0.0
+API_URL := https://api.purple.ai/api/v1
+
+LDFLAGS := -ldflags "\
+    -X 'purple-client/internal/config.Version=$(VERSION)' \
+    -X 'purple-client/internal/config.DefaultAPIBaseURL=$(API_URL)'"
+
+build-prod:
+    go build $(LDFLAGS) -o dist/purple ./cmd/purple
+
+build-dev:
+    PURPLE_API_URL=http://localhost:3000/api/v1 go run ./cmd/purple
+```
+
+#### Why Not Environment Variables in Production?
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Compiled constants** (chosen) | No setup required, works out of box, single binary | Requires rebuild to change URL |
+| Environment variables | Flexible | Users must configure, easy to misconfigure |
+| Config file | Flexible, documented | Another file to manage, can get lost |
+
+For a CLI tool distributed via `npx`, **compiled constants are ideal**:
+- Zero configuration for end users
+- No `.env` files to manage
+- No risk of pointing to wrong server
+- Development override via env var is hidden/undocumented
+
+#### Configuration Values
+
+| Value | Source | Default |
+|-------|--------|---------|
+| `APIBaseURL` | Compiled | `https://api.purple.ai/api/v1` |
+| `Version` | Compiled | Set at build time |
+| `Debug` | Env: `PURPLE_DEBUG=1` | `false` |
+| `APIOverride` | Env: `PURPLE_API_URL` | (none, dev only) |
+
+### 4.2 HTTP Client Setup
+
+All requests include:
+- `Authorization: Bearer {access_token}` header
+- `Content-Type: application/json`
+- `User-Agent: purple-cli/{version}`
+
+```go
+// internal/api/client.go
+
+type Client struct {
+    baseURL    string
+    httpClient *http.Client
+    token      string
+}
+
+func NewClient(cfg *config.Config) *Client {
+    return &Client{
+        baseURL: cfg.APIBaseURL,
+        httpClient: &http.Client{
+            Timeout: 30 * time.Second,
+        },
+    }
+}
+
+func (c *Client) SetToken(token string) {
+    c.token = token
+}
+
+func (c *Client) request(method, path string, body interface{}) (*http.Response, error) {
+    var bodyReader io.Reader
+    if body != nil {
+        jsonBody, _ := json.Marshal(body)
+        bodyReader = bytes.NewReader(jsonBody)
+    }
+
+    req, _ := http.NewRequest(method, c.baseURL+path, bodyReader)
+    req.Header.Set("Content-Type", "application/json")
+    req.Header.Set("User-Agent", "purple-cli/"+config.Version)
+
+    if c.token != "" {
+        req.Header.Set("Authorization", "Bearer "+c.token)
+    }
+
+    return c.httpClient.Do(req)
+}
+```
+
+### 4.3 API Client Interface
+
+```go
+type APIClient interface {
+    // Auth (proxy to Supabase)
+    Register(email, password, name string) (*AuthResponse, error)
+    Login(email, password string) (*AuthResponse, error)
+    RefreshToken(refreshToken string) (*TokenResponse, error)
+    Logout() error
+
+    // User
+    GetCurrentUser() (*User, error)
+    UpdateUser(name string) (*User, error)
+
+    // Team
+    ListTeams() ([]Team, error)
+    GetTeam(id string) (*Team, error)
+
+    // Workspace
+    CreateWorkspace(name, teamID string) (*Workspace, error)
+    GetWorkspace(id string) (*Workspace, error)
+    UpdateWorkspace(id, name string) (*Workspace, error)
+    DeleteWorkspace(id string) error
+
+    // Repo
+    CreateRepo(workspaceID, remoteURL, defaultBranch string) (*Repo, error)
+    ListRepos(workspaceID string) ([]Repo, error)
+    DeleteRepo(id string) error
+
+    // Standard
+    CreateStandard(workspaceID, path, name, content string) (*Standard, error)
+    ListStandards(workspaceID string) ([]Standard, error)
+    UpdateStandard(id, content string) (*Standard, error)
+    DeleteStandard(id string) error
+
+    // Plugin
+    ListAvailablePlugins() ([]PluginSummary, error)
+    GetPlugin(id string) (*Plugin, error)
+    ListWorkspacePlugins(workspaceID string) ([]PluginSummary, error)
+    InstallPlugin(workspaceID, pluginID string) error
+    UninstallPlugin(workspaceID, pluginID string) error
+}
+```
+
+### 4.4 API Response Types
+
+```go
+// Auth
+type AuthResponse struct {
+    Token        string `json:"token"`
+    RefreshToken string `json:"refreshToken"`
+    User         User   `json:"user"`
+}
+
+type TokenResponse struct {
+    Token        string `json:"token"`
+    RefreshToken string `json:"refreshToken"`
+}
+
+// User
+type User struct {
+    ID        string       `json:"id"`
+    Email     string       `json:"email"`
+    Name      string       `json:"name"`
+    AvatarURL *string      `json:"avatarUrl"`
+    Teams     []TeamRef    `json:"teams"`
+}
+
+type TeamRef struct {
+    ID   string `json:"id"`
+    Name string `json:"name"`
+}
+
+// Team
+type Team struct {
+    ID           string         `json:"id"`
+    Name         string         `json:"name"`
+    EmailDomains []string       `json:"emailDomains"`
+    Workspaces   []WorkspaceRef `json:"workspaces"`
+    UserIDs      []string       `json:"userIds"`
+}
+
+type WorkspaceRef struct {
+    ID   string `json:"id"`
+    Name string `json:"name"`
+}
+
+// Workspace
+type Workspace struct {
+    ID     string `json:"id"`
+    Name   string `json:"name"`
+    TeamID string `json:"teamId"`
+}
+
+// Repo
+type Repo struct {
+    ID            string `json:"id"`
+    WorkspaceID   string `json:"workspaceId"`
+    RemoteURL     string `json:"remoteUrl"`
+    DefaultBranch string `json:"defaultBranch"`
+}
+
+// Standard
+type Standard struct {
+    ID          string `json:"id"`
+    WorkspaceID string `json:"workspaceId"`
+    Path        string `json:"path"`        // folder path, e.g. "code-style/frontend"
+    Name        string `json:"name"`        // filename without extension
+    Content     string `json:"content"`
+    Version     int    `json:"version"`     // auto-increments on update
+}
+
+// Plugin
+type PluginSummary struct {
+    ID          string `json:"id"`
+    Name        string `json:"name"`
+    Description string `json:"description"`
+    Type        string `json:"type"` // "tarball" | "repo"
+}
+
+type Plugin struct {
+    ID          string  `json:"id"`
+    Name        string  `json:"name"`
+    Description string  `json:"description"`
+    Type        string  `json:"type"`
+    RepoURL     *string `json:"repoUrl,omitempty"`  // if type = "repo"
+    Tarball     *string `json:"tarball,omitempty"`  // base64 if type = "tarball"
+}
+```
+
+### 4.5 API Endpoints Reference
+
+```
+Auth:
+  POST /auth/register     { email, password, name } → AuthResponse
+  POST /auth/login        { email, password } → AuthResponse
+  POST /auth/refresh      { refreshToken } → TokenResponse
+  POST /auth/logout       → { success: bool }
+
+User:
+  GET  /user/me           → { user: User }
+  PUT  /user/me           { name } → { user: User }
+
+Team:
+  GET  /team              → { teams: Team[] }
+  GET  /team/{id}         → { team: Team }
+
+Workspace:
+  POST /workspace         { name, teamId } → { workspace: Workspace }
+  GET  /workspace/{id}    → { workspace: Workspace }
+  PUT  /workspace/{id}    { name } → { workspace: Workspace }
+  DELETE /workspace/{id}  → { success: bool }
+
+Repo:
+  POST /repo              { workspaceId, remoteUrl, defaultBranch } → { repo: Repo }
+  GET  /repo?workspaceId= → { repos: Repo[] }
+  DELETE /repo/{id}       → { success: bool }
+
+Standard:
+  POST /standard          { workspaceId, path, name, content } → { standard: Standard }
+  GET  /standard?workspaceId= → { standards: Standard[] }
+  PUT  /standard/{id}     { content } → { standard: Standard }
+  DELETE /standard/{id}   → { success: bool }
+
+Plugin:
+  GET  /plugins           → { plugins: PluginSummary[] }
+  GET  /plugins/{id}      → { plugin: Plugin }
+  GET  /workspace/{id}/plugins → { plugins: PluginSummary[] }
+  POST /workspace/{id}/plugins { pluginId } → { success: bool }
+  DELETE /workspace/{id}/plugins/{pluginId} → { success: bool }
+```
+
+---
+
+## 5. Core Flows
+
+### 5.1 Bootstrap Flow (App Startup)
+
+```go
+func bootstrap() error {
+    // 1. Load token from keychain
+    token, err := auth.LoadToken()
+    if err != nil {
+        return showLoginView()
+    }
+
+    // 2. Check if token expired, refresh if needed
+    if auth.IsExpired(token) {
+        newToken, err := api.RefreshToken(token.RefreshToken)
+        if err != nil {
+            return showLoginView()
+        }
+        auth.SaveToken(newToken)
+        token = newToken
+    }
+
+    // 3. Fetch current user
+    user, err := api.GetCurrentUser()
+    if err != nil {
+        return showLoginView()
+    }
+
+    // 4. Detect workspace
+    return detectWorkspace()
+}
+```
+
+### 5.2 Registration Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Register Form (Huh form)                               │
+│  ┌──────────────────────────────────────┐               │
+│  │ Name: [_____________________]        │               │
+│  │ Email: [_____________________]       │               │
+│  │ Password: [__________________]       │               │
+│  │                                      │               │
+│  │ [Register]  [Back to Login]          │               │
+│  └──────────────────────────────────────┘               │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│  POST /api/v1/auth/register                             │
+│  { email, password, name }                              │
+│                                                         │
+│  Backend:                                               │
+│  - Creates Supabase user                                │
+│  - Creates User in Purple DB                            │
+│  - Creates/joins Team based on email domain             │
+│  - Returns tokens + user                                │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│  If email domain matched existing team:                 │
+│  "You've been added to {TeamName} based on your         │
+│   email domain (@company.com)"                          │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│  Store tokens in OS Keychain                            │
+│  Continue to workspace detection                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 5.3 Workspace Open Flow
+
+```go
+func openWorkspace(workspaceID string) error {
+    // Parallel fetch all workspace data
+    var (
+        workspace  *Workspace
+        repos      []Repo
+        standards  []Standard
+        plugins    []PluginSummary
+    )
+
+    g, ctx := errgroup.WithContext(context.Background())
+
+    g.Go(func() error {
+        var err error
+        workspace, err = api.GetWorkspace(workspaceID)
+        return err
+    })
+
+    g.Go(func() error {
+        var err error
+        repos, err = api.ListRepos(workspaceID)
+        return err
+    })
+
+    g.Go(func() error {
+        var err error
+        standards, err = api.ListStandards(workspaceID)
+        return err
+    })
+
+    g.Go(func() error {
+        var err error
+        plugins, err = api.ListWorkspacePlugins(workspaceID)
+        return err
+    })
+
+    if err := g.Wait(); err != nil {
+        return err
+    }
+
+    // Sync standards to local files
+    if err := syncStandardsToLocal(standards); err != nil {
+        return err
+    }
+
+    // Check for plugin updates
+    if err := checkPluginUpdates(plugins); err != nil {
+        // Non-fatal, just log
+        log.Warn("Failed to check plugin updates:", err)
+    }
+
+    return showSessionList()
+}
+```
+
+### 5.4 Standards Sync
+
+**Download (API → Local):**
+```go
+func syncStandardsToLocal(standards []Standard) error {
+    standardsDir := filepath.Join(workspacePath, "workbench", "standards")
+
+    for _, std := range standards {
+        // Build file path: workbench/standards/{path}/{name}.md
+        filePath := filepath.Join(standardsDir, std.Path, std.Name+".md")
+
+        // Ensure directory exists
+        os.MkdirAll(filepath.Dir(filePath), 0755)
+
+        // Write content
+        if err := os.WriteFile(filePath, []byte(std.Content), 0644); err != nil {
+            return err
+        }
+    }
+    return nil
+}
+```
+
+**Upload (Local → API):**
+```go
+func uploadStandardsToAPI(workspaceID string) error {
+    standardsDir := filepath.Join(workspacePath, "workbench", "standards")
+
+    // Get existing standards from API for ID lookup
+    existing, _ := api.ListStandards(workspaceID)
+    existingMap := make(map[string]*Standard) // key: path/name
+    for _, s := range existing {
+        key := filepath.Join(s.Path, s.Name)
+        existingMap[key] = &s
+    }
+
+    // Walk local standards directory
+    return filepath.Walk(standardsDir, func(path string, info os.FileInfo, err error) error {
+        if err != nil || info.IsDir() || !strings.HasSuffix(path, ".md") {
+            return nil
+        }
+
+        relPath, _ := filepath.Rel(standardsDir, path)
+        dir := filepath.Dir(relPath)
+        name := strings.TrimSuffix(filepath.Base(relPath), ".md")
+        content, _ := os.ReadFile(path)
+
+        key := filepath.Join(dir, name)
+        if existing, ok := existingMap[key]; ok {
+            // Update existing
+            api.UpdateStandard(existing.ID, string(content))
+        } else {
+            // Create new
+            api.CreateStandard(workspaceID, dir, name, string(content))
+        }
+        return nil
+    })
+}
+```
+
+### 5.5 Plugin Installation
+
+```go
+func installPlugin(workspaceID string, plugin *Plugin) error {
+    claudeDir := filepath.Join(workspacePath, ".claude")
+
+    switch plugin.Type {
+    case "tarball":
+        // Decode base64 tarball
+        data, _ := base64.StdEncoding.DecodeString(*plugin.Tarball)
+
+        // Extract to .claude/
+        return extractTarball(bytes.NewReader(data), claudeDir)
+
+    case "repo":
+        // Clone repo to temp, copy agents/ and commands/ to .claude/
+        tmpDir, _ := os.MkdirTemp("", "purple-plugin-")
+        defer os.RemoveAll(tmpDir)
+
+        exec.Command("git", "clone", "--depth=1", *plugin.RepoURL, tmpDir).Run()
+
+        // Copy agents
+        copyDir(filepath.Join(tmpDir, "agents"), filepath.Join(claudeDir, "agents"))
+        // Copy commands
+        copyDir(filepath.Join(tmpDir, "commands"), filepath.Join(claudeDir, "commands"))
+
+        return nil
+    }
+
+    return fmt.Errorf("unknown plugin type: %s", plugin.Type)
+}
+```
+
+---
+
+## 6. Terminal Management
+
+### 6.1 PTY Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     TERMINAL                                │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │                                                       │  │
+│  │                  SCROLL REGION                        │  │
+│  │             (Claude Code output)                      │  │
+│  │                                                       │  │
+│  │  PTY dimensions: cols x (rows - STATUS_BAR_HEIGHT)    │  │
+│  │                                                       │  │
+│  ├───────────────────────────────────────────────────────┤  │
+│  │ ─────────────────────────────────────────────────────│  │  <- Border line
+│  │  Phase: Implementation | Agent: senior-engineer | ... │  │  <- Status content
+│  │                                                       │  │  <- Padding
+│  └───────────────────────────────────────────────────────┘  │
+│                     STATUS_BAR_HEIGHT = 3                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 6.2 Status Bar Communication
+
+Two methods (for redundancy):
+
+**Method 1: MCP Server (Primary)**
+```
+Claude Agent → purple_update_status tool → MCP stdio
+    → MCP Server (Node process) → HTTP POST localhost:7685
+    → Purple HTTP handler → Update status bar
+```
+
+**Method 2: File Watcher (Fallback)**
+```
+Claude Agent → Write to workbench/.purple-state.json
+    → Purple file watcher detects change
+    → Read file → Update status bar
+```
+
+### 6.3 Input Handling
+
+```go
+func handleInput(input []byte, pty *os.File) {
+    // Intercept Ctrl+K for command palette
+    if input[0] == 0x0b { // Ctrl+K
+        showCommandPalette()
+        return
+    }
+
+    // If command palette is visible, route to palette
+    if commandPaletteVisible {
+        result := handlePaletteInput(input)
+        if result.Command != "" {
+            pty.Write([]byte(result.Command + "\n"))
+        }
+        return
+    }
+
+    // Normal input - pass to PTY
+    pty.Write(input)
+}
+```
+
+### 6.4 Hook-based Return Flow
+
+```bash
+# ~/.claude/hooks/session-end.sh
+#!/bin/bash
+# Signal Purple that Claude session ended
+curl -X POST http://127.0.0.1:7685/session-end 2>/dev/null || true
+```
+
+When Purple receives `/session-end`:
+1. Wait for PTY process to fully exit
+2. Restore terminal (disable raw mode, reset scroll region)
+3. Clear screen
+4. Resume Purple TUI
+
+### 6.5 Claude Code Launch Commands
+
+Purple constructs different `claude` commands based on context:
+
+```go
+// internal/claude/commands.go
+
+package claude
+
+import (
+    "fmt"
+    "os/exec"
+    "path/filepath"
+)
+
+type LaunchConfig struct {
+    WorkspacePath string
+    SessionName   string   // For --resume or session naming
+    InitialPrompt string   // First message to send
+    Command       string   // Slash command (e.g., "/build-from-spec")
+    SkipPerms     bool     // --dangerously-skip-permissions
+}
+
+func BuildCommand(cfg LaunchConfig) *exec.Cmd {
+    args := []string{}
+
+    // Always start in workspace directory
+    args = append(args, "--cwd", cfg.WorkspacePath)
+
+    // Resume existing session OR create new named session
+    if cfg.SessionName != "" {
+        // Check if session exists
+        if sessionExists(cfg.SessionName) {
+            args = append(args, "--resume", cfg.SessionName)
+        }
+        // Note: Session will be renamed via /rename after launch
+    }
+
+    // Skip permissions for automated flows (create-standards, build-from-spec)
+    if cfg.SkipPerms {
+        args = append(args, "--dangerously-skip-permissions")
+    }
+
+    // Initial prompt (command + arguments)
+    if cfg.Command != "" {
+        prompt := cfg.Command
+        if cfg.InitialPrompt != "" {
+            prompt = fmt.Sprintf("%s %s", cfg.Command, cfg.InitialPrompt)
+        }
+        args = append(args, "-p", prompt)
+    }
+
+    return exec.Command("claude", args...)
+}
+
+// Example launches:
+
+// 1. New session with /build-from-spec
+func LaunchBuildFromSpec(workspace, specPath string) *exec.Cmd {
+    return BuildCommand(LaunchConfig{
+        WorkspacePath: workspace,
+        Command:       "/build-from-spec",
+        InitialPrompt: specPath,
+        SkipPerms:     true,
+    })
+}
+
+// 2. Resume existing session
+func LaunchResumeSession(workspace, sessionName string) *exec.Cmd {
+    return BuildCommand(LaunchConfig{
+        WorkspacePath: workspace,
+        SessionName:   sessionName,
+    })
+}
+
+// 3. Create standards (first-time setup)
+func LaunchCreateStandards(workspace string) *exec.Cmd {
+    return BuildCommand(LaunchConfig{
+        WorkspacePath: workspace,
+        Command:       "/create-standards",
+        SkipPerms:     true,
+    })
+}
+
+// 4. Interactive session (user just wants Claude)
+func LaunchInteractive(workspace string) *exec.Cmd {
+    return BuildCommand(LaunchConfig{
+        WorkspacePath: workspace,
+    })
+}
+```
+
+**Session Naming Flow:**
+
+After launching with `/build-from-spec`, the command itself renames the session:
+```markdown
+# In build-from-spec.md command
+
+After creating the feature folder (e.g., 260112-auth-feature):
+1. Run /rename 260112-auth-feature
+2. This ensures the Claude session matches the feature folder name
+```
+
+### 6.6 Prerequisites Check
+
+Before launching Claude Code, Purple verifies prerequisites:
+
+```go
+// internal/prereqs/check.go
+
+package prereqs
+
+import (
+    "errors"
+    "os/exec"
+)
+
+type Prerequisite struct {
+    Name    string
+    Command string
+    Args    []string
+    HelpURL string
+}
+
+var Prerequisites = []Prerequisite{
+    {
+        Name:    "Claude Code",
+        Command: "claude",
+        Args:    []string{"--version"},
+        HelpURL: "https://claude.ai/code",
+    },
+    {
+        Name:    "Node.js",
+        Command: "node",
+        Args:    []string{"--version"},
+        HelpURL: "https://nodejs.org",
+    },
+    {
+        Name:    "Git",
+        Command: "git",
+        Args:    []string{"--version"},
+        HelpURL: "https://git-scm.com",
+    },
+}
+
+func CheckAll() []error {
+    var errs []error
+
+    for _, prereq := range Prerequisites {
+        cmd := exec.Command(prereq.Command, prereq.Args...)
+        if err := cmd.Run(); err != nil {
+            errs = append(errs, errors.New(prereq.Name+" not found. Install: "+prereq.HelpURL))
+        }
+    }
+
+    return errs
+}
+
+func CheckOnStartup() error {
+    errs := CheckAll()
+    if len(errs) > 0 {
+        return errs[0] // Return first missing prerequisite
+    }
+    return nil
+}
+```
+
+**Node.js is required** because:
+- MCP server runs on Node.js (official MCP SDK)
+- Claude Code may spawn MCP servers at any time
+- Without Node.js, status bar communication will silently fail
+
+---
+
+## 7. MCP Integration
+
+The Model Context Protocol (MCP) is how Claude Code agents communicate status updates back to Purple CLIent. This enables the real-time status bar that shows current phase, agent, and progress.
+
+### 7.1 Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         CLAUDE CODE SESSION                              │
+│                                                                          │
+│  ┌──────────────────┐    stdio     ┌──────────────────┐                 │
+│  │  Claude Agent    │ ←──────────→ │   MCP Server     │                 │
+│  │  (senior-eng,    │   (mcp       │   (Node.js)      │                 │
+│  │   spec-writer)   │   protocol)  │                  │                 │
+│  └──────────────────┘              └────────┬─────────┘                 │
+│                                             │                            │
+│         Agent calls:                        │ HTTP POST                  │
+│         purple_update_status()              │ localhost:7685             │
+│         purple_set_phase()                  │                            │
+│         purple_report_progress()            ▼                            │
+└─────────────────────────────────────────────┼────────────────────────────┘
+                                              │
+                                              │
+┌─────────────────────────────────────────────┼────────────────────────────┐
+│                      PURPLE CLENT (Go)      │                            │
+│                                             │                            │
+│  ┌──────────────────┐              ┌────────▼─────────┐                 │
+│  │   PTY Manager    │              │  HTTP Server     │                 │
+│  │   (claude code   │              │  (status recv)   │                 │
+│  │    subprocess)   │              │  :7685           │                 │
+│  └────────┬─────────┘              └────────┬─────────┘                 │
+│           │                                 │                            │
+│           │ raw output                      │ status updates             │
+│           ▼                                 ▼                            │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                       TERMINAL RENDERER                          │    │
+│  │  ┌───────────────────────────────────────────────────────────┐  │    │
+│  │  │  [Claude Code output area - PTY scroll region]            │  │    │
+│  │  ├───────────────────────────────────────────────────────────┤  │    │
+│  │  │  Phase: Implementation │ Agent: senior-engineer │ 3/10    │  │    │
+│  │  └───────────────────────────────────────────────────────────┘  │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 MCP Server Implementation
+
+**Decision: Keep MCP Server in TypeScript/Node.js**
+
+Rationale:
+- MCP SDK is officially maintained in TypeScript
+- Claude Code expects Node-based MCP servers
+- MCP server runs as a separate process (spawned by Claude Code, not Purple)
+- Communication to Purple is via simple HTTP POST, language-agnostic
+
+```
+purple-client/
+├── cmd/purple/           # Go CLI
+├── internal/             # Go packages
+└── mcp-server/           # Node.js MCP server (bundled)
+    ├── package.json
+    ├── src/
+    │   └── index.ts
+    └── dist/
+        └── index.js      # Bundled for distribution
+```
+
+### 7.3 MCP Server Code
+
+```typescript
+// mcp-server/src/index.ts
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const PURPLE_STATUS_URL = "http://127.0.0.1:7685/status";
+
+const server = new Server(
+  { name: "purple-status", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+// Define available tools
+server.setRequestHandler("tools/list", async () => ({
+  tools: [
+    {
+      name: "purple_update_status",
+      description: "Update the Purple CLI status bar with current progress",
+      inputSchema: {
+        type: "object",
+        properties: {
+          phase: {
+            type: "string",
+            description: 'Current phase (e.g., "0 - Validation", "3 - Implementation")'
+          },
+          agent: {
+            type: "string",
+            description: 'Active agent name (e.g., "orchestrator", "senior-engineer")'
+          },
+          currentTicket: {
+            type: "number",
+            description: "Current ticket number being worked on"
+          },
+          totalTickets: {
+            type: "number",
+            description: "Total number of tickets"
+          },
+          mode: {
+            type: "string",
+            enum: ["plan", "execute", "review"],
+            description: "Current mode"
+          },
+          tool: {
+            type: "string",
+            description: 'Currently active tool (e.g., "Edit", "Grep")'
+          },
+          activeFile: {
+            type: "string",
+            description: "File currently being worked on"
+          }
+        }
+      }
+    },
+    {
+      name: "purple_set_phase",
+      description: "Quick helper to set just the current phase",
+      inputSchema: {
+        type: "object",
+        properties: {
+          phase: {
+            type: "string",
+            description: 'Phase name (e.g., "1 - Product Spec", "3 - Implementation")'
+          }
+        },
+        required: ["phase"]
+      }
+    },
+    {
+      name: "purple_report_progress",
+      description: "Report ticket progress during implementation",
+      inputSchema: {
+        type: "object",
+        properties: {
+          current: { type: "number", description: "Current ticket number" },
+          total: { type: "number", description: "Total tickets" }
+        },
+        required: ["current", "total"]
+      }
+    }
+  ]
+}));
+
+// Handle tool calls
+server.setRequestHandler("tools/call", async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    // Forward status update to Purple CLI via HTTP
+    await fetch(PURPLE_STATUS_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ tool: name, ...args })
+    });
+
+    return { content: [{ type: "text", text: "Status updated" }] };
+  } catch (error) {
+    // Non-fatal - Purple might not be running
+    return { content: [{ type: "text", text: "Status update sent (Purple may not be active)" }] };
+  }
+});
+
+// Start server
+const transport = new StdioServerTransport();
+server.connect(transport);
+```
+
+### 7.4 Auto-Installation Flow
+
+When Purple starts for the first time, it must register the MCP server with Claude Code.
+
+```go
+// internal/mcp/installer.go
+
+package mcp
+
+import (
+    "encoding/json"
+    "os"
+    "path/filepath"
+)
+
+type MCPConfig struct {
+    MCPServers map[string]MCPServer `json:"mcpServers"`
+}
+
+type MCPServer struct {
+    Command string   `json:"command"`
+    Args    []string `json:"args"`
+}
+
+func EnsureMCPInstalled() error {
+    claudeConfigPath := filepath.Join(os.Getenv("HOME"), ".claude.json")
+    mcpServerPath := getMCPServerPath()
+
+    // Read existing config or create new
+    var config MCPConfig
+    if data, err := os.ReadFile(claudeConfigPath); err == nil {
+        json.Unmarshal(data, &config)
+    }
+    if config.MCPServers == nil {
+        config.MCPServers = make(map[string]MCPServer)
+    }
+
+    // Check if already registered
+    if _, exists := config.MCPServers["purple-status"]; exists {
+        return nil // Already installed
+    }
+
+    // Register purple-status MCP server
+    config.MCPServers["purple-status"] = MCPServer{
+        Command: "node",
+        Args:    []string{mcpServerPath},
+    }
+
+    // Write updated config
+    data, _ := json.MarshalIndent(config, "", "  ")
+    return os.WriteFile(claudeConfigPath, data, 0644)
+}
+
+func getMCPServerPath() string {
+    // MCP server is bundled with Purple installation
+    // Path depends on how Purple was installed
+
+    // If installed via npm (npx purple-ai)
+    if npmPath := getNpmMCPPath(); npmPath != "" {
+        return npmPath
+    }
+
+    // Fallback: look in ~/.purple/mcp-server/
+    return filepath.Join(os.Getenv("HOME"), ".purple", "mcp-server", "dist", "index.js")
+}
+
+func getNpmMCPPath() string {
+    // When installed via npm, MCP server is in the package
+    execPath, _ := os.Executable()
+    packageDir := filepath.Dir(filepath.Dir(execPath))
+    mcpPath := filepath.Join(packageDir, "mcp-server", "dist", "index.js")
+
+    if _, err := os.Stat(mcpPath); err == nil {
+        return mcpPath
+    }
+    return ""
+}
+```
+
+**Installation Trigger Points:**
+
+1. **First run**: When Purple detects no workspace and user is setting up
+2. **Workspace open**: Verify MCP is still registered (user may have reset Claude config)
+3. **Before launching Claude Code**: Always verify MCP is registered
+
+### 7.5 Agent Tool Call Instructions
+
+Agents must be instructed to use Purple's MCP tools. This is done via **agent prompt files** that are part of the Purple Core plugin.
+
+**Example: senior-engineer.md agent prompt**
+
+```markdown
+# Senior Engineer Agent
+
+You are a senior engineer implementing features based on engineering specifications.
+
+## Status Reporting (REQUIRED)
+
+You MUST update Purple's status bar using MCP tools as you work:
+
+1. **At the start of each ticket:**
+   ```
+   Call: purple_report_progress({ current: 1, total: 5 })
+   Call: purple_update_status({ agent: "senior-engineer", mode: "execute" })
+   ```
+
+2. **When switching modes:**
+   ```
+   Call: purple_update_status({ mode: "plan" })   // When planning
+   Call: purple_update_status({ mode: "execute" }) // When coding
+   Call: purple_update_status({ mode: "review" })  // When reviewing
+   ```
+
+3. **When working on a file:**
+   ```
+   Call: purple_update_status({ activeFile: "src/components/Button.tsx" })
+   ```
+
+This keeps the user informed of progress without them needing to read your output.
+
+## Implementation Guidelines
+...
+```
+
+**Example: orchestrator command (build-from-spec.md)**
+
+```markdown
+# Build From Spec
+
+This command orchestrates the full spec-to-implementation workflow.
+
+## Phase Updates (REQUIRED)
+
+Update the phase as you progress:
+
+```
+purple_set_phase({ phase: "0 - Validation" })    // Validating inputs
+purple_set_phase({ phase: "1 - Product Spec" })  // Writing product spec
+purple_set_phase({ phase: "2 - Engineering" })   // Creating architecture
+purple_set_phase({ phase: "3 - Implementation" }) // Building features
+purple_set_phase({ phase: "4 - Review" })        // Final review
+```
+
+## Spawning Sub-Agents
+
+When spawning senior-engineer agents for parallel implementation:
+```
+purple_update_status({
+  phase: "3 - Implementation",
+  agent: "orchestrator",
+  currentTicket: 1,
+  totalTickets: 10
+})
+```
+
+Then spawn the Task with senior-engineer...
+```
+
+### 7.6 Purple HTTP Status Server (Go)
+
+```go
+// internal/server/status.go
+
+package server
+
+import (
+    "encoding/json"
+    "net/http"
+    "sync"
+)
+
+type StatusUpdate struct {
+    Tool          string `json:"tool"`
+    Phase         string `json:"phase,omitempty"`
+    Agent         string `json:"agent,omitempty"`
+    CurrentTicket int    `json:"currentTicket,omitempty"`
+    TotalTickets  int    `json:"totalTickets,omitempty"`
+    Mode          string `json:"mode,omitempty"`
+    ActiveTool    string `json:"tool,omitempty"`
+    ActiveFile    string `json:"activeFile,omitempty"`
+}
+
+type StatusServer struct {
+    mu       sync.RWMutex
+    status   StatusUpdate
+    onChange func(StatusUpdate)
+    server   *http.Server
+}
+
+func NewStatusServer(onChange func(StatusUpdate)) *StatusServer {
+    s := &StatusServer{
+        onChange: onChange,
+    }
+
+    mux := http.NewServeMux()
+    mux.HandleFunc("/status", s.handleStatus)
+    mux.HandleFunc("/session-end", s.handleSessionEnd)
+
+    s.server = &http.Server{
+        Addr:    "127.0.0.1:7685",
+        Handler: mux,
+    }
+
+    return s
+}
+
+func (s *StatusServer) Start() error {
+    return s.server.ListenAndServe()
+}
+
+func (s *StatusServer) Stop() error {
+    return s.server.Close()
+}
+
+func (s *StatusServer) handleStatus(w http.ResponseWriter, r *http.Request) {
+    if r.Method != http.MethodPost {
+        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+        return
+    }
+
+    var update StatusUpdate
+    if err := json.NewDecoder(r.Body).Decode(&update); err != nil {
+        http.Error(w, err.Error(), http.StatusBadRequest)
+        return
+    }
+
+    s.mu.Lock()
+    // Merge update (only set non-empty fields)
+    if update.Phase != "" {
+        s.status.Phase = update.Phase
+    }
+    if update.Agent != "" {
+        s.status.Agent = update.Agent
+    }
+    if update.CurrentTicket > 0 {
+        s.status.CurrentTicket = update.CurrentTicket
+    }
+    if update.TotalTickets > 0 {
+        s.status.TotalTickets = update.TotalTickets
+    }
+    if update.Mode != "" {
+        s.status.Mode = update.Mode
+    }
+    if update.ActiveTool != "" {
+        s.status.ActiveTool = update.ActiveTool
+    }
+    if update.ActiveFile != "" {
+        s.status.ActiveFile = update.ActiveFile
+    }
+    current := s.status
+    s.mu.Unlock()
+
+    // Notify TUI to update
+    if s.onChange != nil {
+        s.onChange(current)
+    }
+
+    w.WriteHeader(http.StatusOK)
+    json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+}
+
+func (s *StatusServer) handleSessionEnd(w http.ResponseWriter, r *http.Request) {
+    // Signal Purple to exit Claude mode and return to TUI
+    // This is handled by the onChange callback with a special signal
+    if s.onChange != nil {
+        s.onChange(StatusUpdate{Tool: "__session_end__"})
+    }
+    w.WriteHeader(http.StatusOK)
+}
+
+func (s *StatusServer) GetStatus() StatusUpdate {
+    s.mu.RLock()
+    defer s.mu.RUnlock()
+    return s.status
+}
+```
+
+### 7.7 Status Bar Rendering
+
+```go
+// internal/tui/components/statusbar.go
+
+package components
+
+import (
+    "fmt"
+    "strings"
+
+    "github.com/charmbracelet/lipgloss"
+)
+
+var (
+    // Status bar uses brand colors from bepurple.ai
+    statusBarStyle = lipgloss.NewStyle().
+        Background(lipgloss.Color("#1A1625")).  // BgCard
+        Foreground(lipgloss.Color("#E8E4EF")).  // Light text
+        Padding(0, 1)
+
+    phaseStyle = lipgloss.NewStyle().
+        Foreground(lipgloss.Color("#B794F6")).  // Purple (primary)
+        Bold(true)
+
+    agentStyle = lipgloss.NewStyle().
+        Foreground(lipgloss.Color("#4ADE80"))   // Success green
+
+    progressStyle = lipgloss.NewStyle().
+        Foreground(lipgloss.Color("#FBBF24"))   // Warning amber
+
+    modeStyle = lipgloss.NewStyle().
+        Foreground(lipgloss.Color("#8B7AA8"))   // PurpleMuted
+
+    separatorStyle = lipgloss.NewStyle().
+        Foreground(lipgloss.Color("#6B5B8C")).  // PurpleDark
+        SetString(" │ ")
+)
+
+type StatusBar struct {
+    Phase         string
+    Agent         string
+    CurrentTicket int
+    TotalTickets  int
+    Mode          string
+    ActiveFile    string
+    Width         int
+}
+
+func (s StatusBar) View() string {
+    var parts []string
+
+    // Phase
+    if s.Phase != "" {
+        parts = append(parts, phaseStyle.Render(s.Phase))
+    }
+
+    // Agent
+    if s.Agent != "" {
+        parts = append(parts, agentStyle.Render(s.Agent))
+    }
+
+    // Progress
+    if s.TotalTickets > 0 {
+        progress := fmt.Sprintf("%d/%d", s.CurrentTicket, s.TotalTickets)
+        parts = append(parts, progressStyle.Render(progress))
+    }
+
+    // Mode
+    if s.Mode != "" {
+        modeIcon := map[string]string{
+            "plan":    "📋",
+            "execute": "⚡",
+            "review":  "🔍",
+        }[s.Mode]
+        parts = append(parts, modeStyle.Render(modeIcon+" "+s.Mode))
+    }
+
+    content := strings.Join(parts, separatorStyle.String())
+
+    // Pad to full width
+    return statusBarStyle.Width(s.Width).Render(content)
+}
+```
+
+### 7.8 MCP Distribution Strategy
+
+The MCP server must be bundled with Purple for reliable operation.
+
+**npm Package Structure:**
+```
+purple-ai/
+├── package.json
+├── bin/
+│   └── purple-ai.js          # Entry point
+├── binaries/
+│   ├── purple-darwin-arm64
+│   ├── purple-darwin-x64
+│   └── purple-linux-x64
+└── mcp-server/
+    ├── package.json
+    └── dist/
+        └── index.js          # Pre-bundled MCP server
+```
+
+**postinstall.js:**
+```javascript
+const { execSync } = require('child_process');
+const path = require('path');
+
+// Install MCP server dependencies
+const mcpDir = path.join(__dirname, 'mcp-server');
+execSync('npm install --production', { cwd: mcpDir, stdio: 'inherit' });
+```
+
+### 7.9 Fallback: File-based Status (No MCP)
+
+If MCP communication fails, agents can write status to a file:
+
+```
+{workspace}/workbench/.purple-state.json
+```
+
+Purple watches this file as a fallback:
+
+```go
+// internal/status/watcher.go
+
+func watchStatusFile(path string, onChange func(StatusUpdate)) {
+    watcher, _ := fsnotify.NewWatcher()
+    watcher.Add(path)
+
+    for event := range watcher.Events {
+        if event.Op&fsnotify.Write == fsnotify.Write {
+            data, _ := os.ReadFile(path)
+            var status StatusUpdate
+            json.Unmarshal(data, &status)
+            onChange(status)
+        }
+    }
+}
+```
+
+Agents are instructed to write to this file if MCP tools aren't available (for users running Claude Code without Purple).
+
+---
+
+## 8. UI/UX Design Principles
+
+Purple CLIent should feel **premium and polished** - not like a typical CLI tool. The goal is a terminal experience that rivals native desktop apps.
+
+### Brand Identity
+
+Purple CLIent uses the official bepurple.ai brand colors. **Dark theme only** - matches the website aesthetic.
+
+| Color | Hex | Usage |
+|-------|-----|-------|
+| **Purple** | `#B794F6` | Primary - logo, headings, selected items |
+| **Purple Light** | `#D4BFFF` | Hover states, highlights |
+| **Purple Muted** | `#8B7AA8` | Buttons, secondary accents |
+| **Purple Dark** | `#6B5B8C` | Borders, separators |
+| **Background** | `#0D0B14` | Main background (deep purple-black) |
+| **Card Background** | `#1A1625` | Terminal cards, elevated surfaces |
+| **Success** | `#4ADE80` | Checkmarks, completion states |
+| **Warning** | `#FBBF24` | In-progress, active states |
+| **Error** | `#F87171` | Error messages, failures |
+| **Muted Text** | `#6B6378` | Secondary text, labels |
+
+### 8.1 Design Philosophy
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Instant feedback** | Every action shows immediate visual response |
+| **No dead ends** | Always show what user can do next |
+| **Graceful degradation** | Errors don't break the UI, they inform |
+| **Progressive disclosure** | Show simple first, details on demand |
+| **Consistent patterns** | Same keys do same things everywhere |
+
+### 8.2 Charm Libraries Usage
+
+#### Bubbletea (Core TUI Framework)
+
+```go
+// Model-View-Update architecture
+type Model struct {
+    state       AppState
+    viewport    viewport.Model    // Scrollable content
+    spinner     spinner.Model     // Loading states
+    list        list.Model        // Session/workspace lists
+    form        *huh.Form         // Input forms
+    statusBar   StatusBar         // Bottom status
+    err         error             // Current error (if any)
+}
+
+// Always return a command for smooth updates
+func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+    switch msg := msg.(type) {
+    case tea.KeyMsg:
+        switch msg.String() {
+        case "q", "ctrl+c":
+            return m, tea.Quit
+        case "?":
+            return m, showHelp  // Help always accessible
+        }
+    case errMsg:
+        m.err = msg.err
+        return m, clearErrorAfter(5 * time.Second)
+    }
+    return m, nil
+}
+```
+
+#### Lipgloss (Styling)
+
+Define a consistent style system:
+
+```go
+// internal/tui/styles.go
+
+package tui
+
+import "github.com/charmbracelet/lipgloss"
+
+var (
+    // Brand colors (from bepurple.ai)
+    Purple       = lipgloss.Color("#B794F6")  // Primary purple - logo, headings
+    PurpleLight  = lipgloss.Color("#D4BFFF")  // Light purple - hover states
+    PurpleMuted  = lipgloss.Color("#8B7AA8")  // Muted purple - buttons, accents
+    PurpleDark   = lipgloss.Color("#6B5B8C")  // Dark purple - borders
+
+    // Backgrounds (dark theme)
+    BgDark       = lipgloss.Color("#0D0B14")  // Main background - deep purple-black
+    BgCard       = lipgloss.Color("#1A1625")  // Card/terminal background
+    BgElevated   = lipgloss.Color("#252033")  // Elevated surfaces
+
+    // Semantic colors
+    Success = lipgloss.Color("#4ADE80")  // Green - checkmarks, completion
+    Warning = lipgloss.Color("#FBBF24")  // Amber - in-progress, caution
+    Error   = lipgloss.Color("#F87171")  // Red - errors, failures
+    Muted   = lipgloss.Color("#6B6378")  // Gray-purple - secondary text
+
+    // Base styles
+    Title = lipgloss.NewStyle().
+        Foreground(Purple).
+        Bold(true).
+        MarginBottom(1)
+
+    Subtitle = lipgloss.NewStyle().
+        Foreground(PurpleLight).
+        Italic(true)
+
+    // Interactive elements
+    Selected = lipgloss.NewStyle().
+        Foreground(lipgloss.Color("#FFFFFF")).
+        Background(Purple).
+        Padding(0, 1)
+
+    Unselected = lipgloss.NewStyle().
+        Foreground(Muted).
+        Padding(0, 1)
+
+    // Status indicators
+    StatusSuccess = lipgloss.NewStyle().
+        Foreground(Success).
+        SetString("✓")
+
+    StatusError = lipgloss.NewStyle().
+        Foreground(Error).
+        SetString("✗")
+
+    StatusPending = lipgloss.NewStyle().
+        Foreground(Warning).
+        SetString("○")
+
+    // Containers
+    Box = lipgloss.NewStyle().
+        Border(lipgloss.RoundedBorder()).
+        BorderForeground(Purple).
+        Padding(1, 2)
+
+    // Error display
+    ErrorBox = lipgloss.NewStyle().
+        Border(lipgloss.RoundedBorder()).
+        BorderForeground(Error).
+        Foreground(Error).
+        Padding(0, 1).
+        MarginTop(1)
+)
+```
+
+#### Huh (Forms & Prompts)
+
+```go
+// Styled, accessible forms
+func loginForm() *huh.Form {
+    return huh.NewForm(
+        huh.NewGroup(
+            huh.NewInput().
+                Key("email").
+                Title("Email").
+                Placeholder("you@company.com").
+                Validate(validateEmail),
+
+            huh.NewInput().
+                Key("password").
+                Title("Password").
+                EchoMode(huh.EchoModePassword),
+        ),
+    ).WithTheme(purpleTheme())
+}
+
+// Custom theme matching our brand
+func purpleTheme() *huh.Theme {
+    t := huh.ThemeBase()
+    t.Focused.Title = t.Focused.Title.Foreground(Purple)
+    t.Focused.Base = t.Focused.Base.BorderForeground(Purple)
+    return t
+}
+```
+
+### 8.3 UX Patterns
+
+#### Loading States
+
+Never leave the user wondering. Show spinners with context:
+
+```go
+func (m Model) viewLoading() string {
+    return lipgloss.JoinVertical(
+        lipgloss.Center,
+        m.spinner.View(),
+        lipgloss.NewStyle().Foreground(Muted).Render(m.loadingMessage),
+    )
+}
+
+// Good loading messages:
+// "Syncing standards..." (not "Loading...")
+// "Cloning react-app (2/3)..." (not "Please wait...")
+// "Authenticating..." (not "Working...")
+```
+
+#### Progress Indicators
+
+For multi-step operations:
+
+```go
+func renderProgress(current, total int, items []string) string {
+    var b strings.Builder
+
+    // Progress bar
+    pct := float64(current) / float64(total)
+    filled := int(pct * 20)
+    bar := strings.Repeat("█", filled) + strings.Repeat("░", 20-filled)
+    b.WriteString(fmt.Sprintf("[%s] %d/%d\n\n", bar, current, total))
+
+    // Item status
+    for i, item := range items {
+        if i < current {
+            b.WriteString(StatusSuccess.Render() + " " + item + "\n")
+        } else if i == current {
+            b.WriteString(m.spinner.View() + " " + item + "\n")
+        } else {
+            b.WriteString(StatusPending.Render() + " " + Muted.Render(item) + "\n")
+        }
+    }
+
+    return Box.Render(b.String())
+}
+```
+
+#### Empty States
+
+Never show a blank screen:
+
+```go
+func (m Model) viewEmptySessions() string {
+    return lipgloss.JoinVertical(
+        lipgloss.Center,
+        "\n",
+        lipgloss.NewStyle().Foreground(Muted).Render("No sessions yet"),
+        "\n",
+        lipgloss.NewStyle().Foreground(Purple).Render("Press 'n' to start a new session"),
+        lipgloss.NewStyle().Foreground(Muted).Render("or 'q' to quit"),
+    )
+}
+```
+
+#### Error Display
+
+Errors should be helpful, not scary:
+
+```go
+func renderError(err error, suggestion string) string {
+    return ErrorBox.Render(
+        lipgloss.JoinVertical(
+            lipgloss.Left,
+            lipgloss.NewStyle().Bold(true).Render("Something went wrong"),
+            "",
+            err.Error(),
+            "",
+            lipgloss.NewStyle().Foreground(Muted).Render("💡 "+suggestion),
+        ),
+    )
+}
+
+// Usage:
+renderError(
+    errors.New("Failed to clone repository"),
+    "Check that you have access to this repo and try again",
+)
+```
+
+#### Keyboard Navigation
+
+Consistent across all views:
+
+```go
+// internal/tui/keys.go
+
+var GlobalKeys = map[string]string{
+    "q":        "Quit",
+    "?":        "Help",
+    "esc":      "Back / Cancel",
+    "enter":    "Select / Confirm",
+    "tab":      "Next field",
+    "shift+tab": "Previous field",
+}
+
+var ListKeys = map[string]string{
+    "j/↓":      "Move down",
+    "k/↑":      "Move up",
+    "g":        "Go to top",
+    "G":        "Go to bottom",
+    "/":        "Search / Filter",
+}
+
+// Show contextual help footer
+func renderHelpFooter(keys map[string]string) string {
+    var parts []string
+    for key, desc := range keys {
+        parts = append(parts, Muted.Render(key)+" "+desc)
+    }
+    return lipgloss.NewStyle().
+        Foreground(Muted).
+        MarginTop(1).
+        Render(strings.Join(parts, "  •  "))
+}
+```
+
+### 8.4 Animation & Transitions
+
+Use subtle animations to make the UI feel alive:
+
+```go
+// Spinner options (pick one style, use consistently)
+var SpinnerStyle = spinner.Dot  // ⣾⣽⣻⢿⡿⣟⣯⣷
+
+// Smooth list scrolling
+list.NewModel(items, delegate, width, height).
+    SetShowHelp(false).
+    SetFilteringEnabled(true).
+    SetShowStatusBar(true)
+
+// Viewport for scrollable content
+viewport.New(width, height).
+    SetContent(longContent).
+    GotoTop()
+```
+
+### 8.5 Accessibility
+
+- **High contrast**: All text readable on dark/light terminals
+- **No color-only indicators**: Icons + color (✓ green, ✗ red)
+- **Keyboard-first**: Everything usable without mouse
+- **Screen reader friendly**: Logical content order
+
+### 8.6 Reference Implementations
+
+Study these Charm-built tools for inspiration:
+
+| Tool | What to learn |
+|------|---------------|
+| [gum](https://github.com/charmbracelet/gum) | Simple, focused interactions |
+| [soft-serve](https://github.com/charmbracelet/soft-serve) | Complex multi-view app |
+| [glow](https://github.com/charmbracelet/glow) | Beautiful markdown rendering |
+| [lazygit](https://github.com/jesseduffield/lazygit) | Complex TUI with panels |
+| [gh-dash](https://github.com/dlvhdr/gh-dash) | Dashboard-style layout |
+
+---
+
+## 9. Distribution
+
+**Single command install**: `npx purple-ai` includes everything:
+- Go binary (platform-specific)
+- MCP server (TypeScript/Node.js, bundled)
+- No separate installation steps required
+
+### 9.1 Build Targets
+
+```makefile
+PLATFORMS := darwin-arm64 darwin-amd64 linux-amd64
+
+build-all:
+    for platform in $(PLATFORMS); do \
+        GOOS=$$(echo $$platform | cut -d- -f1) \
+        GOARCH=$$(echo $$platform | cut -d- -f2) \
+        go build -o dist/purple-$$platform ./cmd/purple; \
+    done
+```
+
+### 9.2 npm Wrapper Structure
+
+```
+npm/
+├── package.json
+├── bin/
+│   └── purple-ai.js      # Entry point
+└── postinstall.js        # Downloads correct binary
+```
+
+**package.json:**
+```json
+{
+  "name": "purple-ai",
+  "version": "1.0.0",
+  "bin": {
+    "purple-ai": "bin/purple-ai.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "os": ["darwin", "linux"],
+  "cpu": ["x64", "arm64"]
+}
+```
+
+**bin/purple-ai.js:**
+```javascript
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const path = require('path');
+
+const platform = `${process.platform}-${process.arch}`;
+const binaryPath = path.join(__dirname, '..', 'bin', `purple-${platform}`);
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit'
+});
+
+child.on('exit', (code) => process.exit(code));
+```
+
+### 9.3 Version Check & Auto-Update
+
+On workspace entry (not every launch):
+```go
+func checkForUpdates() {
+    // Future: GET /api/v1/cli/version endpoint
+    // For now, skip update check
+}
+```
+
+---
+
+## 10. Security
+
+### 10.1 Token Storage
+
+**Primary: OS Keychain**
+```go
+import "github.com/zalando/go-keyring"
+
+func storeTokens(access, refresh string) error {
+    if err := keyring.Set("purple-ai", "access_token", access); err != nil {
+        return err
+    }
+    return keyring.Set("purple-ai", "refresh_token", refresh)
+}
+
+func loadTokens() (access, refresh string, err error) {
+    access, err = keyring.Get("purple-ai", "access_token")
+    if err != nil {
+        return "", "", err
+    }
+    refresh, err = keyring.Get("purple-ai", "refresh_token")
+    return
+}
+
+func clearTokens() error {
+    keyring.Delete("purple-ai", "access_token")
+    keyring.Delete("purple-ai", "refresh_token")
+    return nil
+}
+```
+
+**Fallback: Encrypted file** (if keychain unavailable)
+```
+~/.purple/.credentials (chmod 600)
+Encrypted with machine-specific key derived from:
+- Machine UUID
+- User ID
+```
+
+### 10.2 Git Credential Handling
+
+- Never store git credentials
+- Use system git, which uses system credential helper
+- For `gh` CLI, user must have already run `gh auth login`
+
+---
+
+## 11. Error Handling
+
+**Principle: Never crash the terminal process**
+
+```go
+func handleError(err error) {
+    switch {
+    case errors.Is(err, ErrNoConnection):
+        showErrorView("No internet connection. Please check your network.")
+
+    case errors.Is(err, ErrAuthExpired):
+        // Attempt refresh, if fails show login
+        if refreshErr := refreshAuth(); refreshErr != nil {
+            showLoginView()
+        }
+
+    case errors.Is(err, ErrUnauthorized):
+        showLoginView()
+
+    case errors.Is(err, ErrClaudeNotFound):
+        showErrorView("Claude Code not found. Please install it first.")
+        showInstallInstructions()
+
+    case errors.Is(err, ErrGitCloneFailed):
+        showErrorView(fmt.Sprintf("Failed to clone repo: %v", err))
+        offerRetryOrSkip()
+
+    case errors.Is(err, ErrWorkspaceNotFound):
+        // Workspace deleted from backend
+        showErrorView("This workspace no longer exists.")
+        offerCreateNew()
+
+    default:
+        showErrorView(fmt.Sprintf("An error occurred: %v", err))
+        offerReturnToMenu()
+    }
+}
+```
+
+**Offline Behavior:**
+- On any network call failure, show: "No internet connection"
+- Do not attempt offline mode or caching
+- User must have connection to use Purple
+
+---
+
+## 12. Platform Support
+
+| Platform | Architecture | Status |
+|----------|--------------|--------|
+| macOS | arm64 (M1/M2/M3) | Supported |
+| macOS | x64 (Intel) | Supported |
+| Linux | x64 | Supported |
+| Linux | arm64 | Not in v1 |
+| Windows | any | Not in v1 (use WSL) |
+
+**Claude Code Detection:**
+```go
+func detectClaude() (string, error) {
+    path, err := exec.LookPath("claude")
+    if err != nil {
+        return "", ErrClaudeNotFound
+    }
+    return path, nil
+}
+```
+
+No minimum Claude Code version enforced in v1.
+
+---
+
+## 13. Future Considerations (Out of Scope for v1)
+
+- Windows native support
+- Offline mode with sync
+- Custom plugin marketplace
+- Workspace templates
+- Real-time collaboration
+- Session sync to backend
+- IDE extensions (VS Code, JetBrains)
+
+---
+
+## Appendix A: Current Implementation Reference
+
+The existing Node/TS implementation in `purple-test/src/` demonstrates:
+
+- **PTY spawning**: `src/claude/pty-spawn.ts` - Use `creack/pty` equivalent in Go
+- **Status bar**: `src/ui/status-bar.ts` - Lipgloss equivalent
+- **MCP server**: `mcp-server/src/index.ts` - Keep as-is or rewrite in Go
+- **Auth flow**: `src/auth/` - Reference for token storage patterns
+- **Live flow**: `src/live/index.ts` - Reference for startup sequence
+
+---
+
+## Appendix B: Key Dependencies (Go)
+
+```go
+require (
+    github.com/charmbracelet/bubbletea v0.25.0
+    github.com/charmbracelet/huh v0.3.0
+    github.com/charmbracelet/lipgloss v0.9.0
+    github.com/creack/pty v1.1.21
+    github.com/zalando/go-keyring v0.2.3
+    github.com/google/uuid v1.6.0
+    golang.org/x/sync v0.6.0  // for errgroup
+)
+```
+
+---
+
+## Appendix C: Data Flow Summary
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      PURPLE BACKEND                         │
+│  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐          │
+│  │  User   │ │  Team   │ │Workspace │ │ Plugin  │          │
+│  └────┬────┘ └────┬────┘ └────┬─────┘ └────┬────┘          │
+│       │           │           │            │                │
+│       │           │     ┌─────┴─────┐      │                │
+│       │           │     │           │      │                │
+│       │           │  ┌──┴──┐    ┌───┴───┐  │                │
+│       │           │  │Repo │    │Standard│ │                │
+│       │           │  └─────┘    └───────┘  │                │
+└───────┼───────────┼─────────────────────────────────────────┘
+        │           │           │            │
+        ▼           ▼           ▼            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     PURPLE CLI                              │
+│                                                             │
+│  ~/.purple/           {workspace}/                          │
+│  └─ (theme only)      ├─ purple.json (workspace_id only)   │
+│                       ├─ repos/ (cloned)                    │
+│  Keychain:            ├─ .claude/ (from plugins)            │
+│  └─ tokens            └─ workbench/                         │
+│                          ├─ standards/ (synced from API)    │
+│                          └─ documentation/ (LOCAL ONLY)     │
+│                             ├─ user-originals/              │
+│                             ├─ {feature-folders}/           │
+│                             └─ archived/                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Appendix D: Behavioral Specifications
+
+Detailed decisions for edge cases and UX behaviors.
+
+### D.1 Command Palette (Ctrl+K)
+
+Available commands while in Claude Code session:
+- **Return to Purple** - Exit Claude, return to session list
+- **All /commands** - Dynamically loaded from `.claude/commands/` folder
+- Note: Session-specific commands like archive/delete not available mid-session
+
+### D.2 Repository Selection
+
+**When gh CLI is available:**
+- List repos filtered by organization
+- Multi-select with checkboxes
+- Option to enter manual URL for unlisted repos
+
+**When gh CLI is unavailable:**
+- Show message: "GitHub CLI not found. Enter repository URLs manually."
+- Text input for git URL (validates format)
+- Support both HTTPS and SSH URLs
+
+### D.3 Empty Workspaces
+
+- Workspaces can be created with zero repositories
+- User can add repos later via workspace settings
+- Sessions cannot be started without at least one repo (show helpful message)
+
+### D.4 Session Archiving
+
+```
+Archive action:
+1. Move folder from workbench/documentation/{session}/
+   to workbench/documentation/archived/{session}/
+2. Session no longer appears in main list
+3. Archived sessions viewable via "Show archived" toggle
+```
+
+### D.5 Hook Registration for Session End
+
+Purple registers a hook in Claude Code's settings to signal session completion:
+
+```json
+// ~/.claude.json (managed by Purple)
+{
+  "hooks": {
+    "Stop": [
+      {
+        "type": "command",
+        "command": "curl -s -X POST http://127.0.0.1:7685/session-end"
+      }
+    ]
+  },
+  "mcpServers": {
+    "purple-status": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+### D.6 Standards Generation Failure
+
+If `/create-standards` fails or produces poor results, offer:
+1. **Re-run** - Run `/create-standards` again with fresh context
+2. **Manual edit** - Open `workbench/standards/` in system editor
+3. **Skip** - Continue without standards (not recommended, show warning)
+
+### D.7 Plugin Version Check
+
+On workspace open:
+```go
+func checkPluginUpdates(installed []PluginSummary) error {
+    available, _ := api.ListAvailablePlugins()
+
+    for _, inst := range installed {
+        for _, avail := range available {
+            if inst.ID == avail.ID && inst.Version < avail.Version {
+                // Prompt: "Plugin {name} has an update. Install now?"
+                promptPluginUpdate(inst, avail)
+            }
+        }
+    }
+    return nil
+}
+```
+
+### D.8 Team Selection Flow
+
+1. User logs in / registers
+2. If no workspace found in current directory:
+   - Fetch user's teams via `GET /team`
+   - If multiple teams: show team picker
+   - If single team: auto-select
+3. Then proceed to workspace creation or clone
+
+### D.9 Session List Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Sessions                                          [s]ettings│
+├─────────────────────────────────────────────────────────────┤
+│  > 260112-auth-feature          ● active      Jan 12, 2026  │
+│    260110-dashboard             ✓ done        Jan 10, 2026  │
+│    260108-api-refactor          ✓ done        Jan 8, 2026   │
+│                                                             │
+│  [n] New session  [o] Open Claude  [a] Show archived        │
+└─────────────────────────────────────────────────────────────┘
+
+Status indicators:
+● active (in-progress) - Yellow/Orange
+✓ done (completed)     - Green
+○ new (just created)   - Gray
+```
+
+### D.10 Interactive Claude Sessions
+
+When user selects "Open Claude" (interactive mode):
+- Auto-generate session name: `interactive-{YYMMDD}-{n}` (e.g., `interactive-260112-1`)
+- Creates minimal folder in documentation (for consistency)
+- No `/build-from-spec` command sent
+- User has full control of Claude session
+
+### D.11 Session Resume Verification
+
+```go
+func resumeSession(sessionName string) error {
+    // Check if Claude session exists
+    sessions, _ := listClaudeSessions() // claude --list-sessions
+
+    exists := false
+    for _, s := range sessions {
+        if s.Name == sessionName {
+            exists = true
+            break
+        }
+    }
+
+    if !exists {
+        // Offer options:
+        // 1. Start fresh session in same folder
+        // 2. Return to session list
+        return promptSessionNotFound(sessionName)
+    }
+
+    return launchClaude("--resume", sessionName)
+}
+```
+
+### D.12 Missing Repo Detection
+
+On workspace open:
+```go
+func verifyRepos(workspace *Workspace) error {
+    repos, _ := api.ListRepos(workspace.ID)
+
+    for _, repo := range repos {
+        localPath := filepath.Join(workspace.Path, "repos", repoName(repo.RemoteURL))
+        if _, err := os.Stat(localPath); os.IsNotExist(err) {
+            // Prompt: "Repository {name} is missing. Clone now?"
+            if promptCloneMissing(repo) {
+                cloneRepo(repo, localPath)
+            }
+        }
+    }
+    return nil
+}
+```
+
+### D.13 Branch Selection
+
+During repo selection:
+- Default branch is pre-selected (usually `main` or `master`)
+- User can click/expand to choose different branch
+- Branch stored in `Repo.defaultBranch` field in backend
+
+### D.14 Nested Workspace Detection
+
+```go
+func detectWorkspace(startDir string) (*WorkspaceMatch, error) {
+    // Check current directory
+    if exists(filepath.Join(startDir, "purple.json")) {
+        return &WorkspaceMatch{Path: startDir, Type: "current"}, nil
+    }
+
+    // Check parent directories
+    parent := startDir
+    for {
+        parent = filepath.Dir(parent)
+        if parent == "/" || parent == "." {
+            break
+        }
+        if exists(filepath.Join(parent, "purple.json")) {
+            // Found parent workspace - offer choice
+            return &WorkspaceMatch{
+                Path: parent,
+                Type: "parent",
+                Message: "You're inside an existing workspace. Open it or create nested?",
+            }, nil
+        }
+    }
+
+    // Check subdirectories
+    // ... scan for purple.json in subdirs
+
+    return nil, ErrNoWorkspaceFound
+}
+```
+
+### D.15 Workspace Settings Menu
+
+Accessible via `[s]` key from session list:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Workspace Settings: my-project                             │
+├─────────────────────────────────────────────────────────────┤
+│  > Rename workspace                                         │
+│    Add repository                                           │
+│    Remove repository                                        │
+│    ───────────────────                                      │
+│    Manage plugins                                           │
+│    Re-run /create-standards                                 │
+│    Sync standards from team                                 │
+│    ───────────────────                                      │
+│    View workspace info                                      │
+│                                                             │
+│  [esc] Back                                                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### D.16 Status Bar Default State
+
+Before any MCP updates received:
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Phase: Starting │ Agent: - │ Mode: plan                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### D.17 Logout Behavior
+
+```go
+func logout() error {
+    // Clear tokens from keychain
+    clearTokens()
+
+    // Keep local files:
+    // - ~/.purple/settings.json (theme preference)
+    // - All workspace purple.json files
+    // - All cloned repos and documentation
+
+    // Show login screen
+    return showLoginView()
+}
+```
+
+### D.18 Spec File Handling
+
+**Detection:**
+- Any `.md` file in `workbench/documentation/user-originals/` is a potential spec
+
+**New spec creation:**
+```go
+func createNewSpec(name string) (string, error) {
+    template := `# Feature: {name}
+
+## Overview
+[Describe what this feature does]
+
+## User Stories
+- As a [user type], I want [goal] so that [benefit]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Out of Scope
+- Not included in this feature
+
+## Open Questions
+- Any uncertainties to resolve?
+`
+
+    filename := slugify(name) + ".md"
+    path := filepath.Join(workspace, "workbench/documentation/user-originals", filename)
+
+    content := strings.Replace(template, "{name}", name, -1)
+    return path, os.WriteFile(path, []byte(content), 0644)
+}
+```
+
+### D.19 Clone Progress Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Cloning repositories...                                    │
+├─────────────────────────────────────────────────────────────┤
+│  ✓ org/react-app                                            │
+│  ✓ org/api-server                                           │
+│  ⟳ org/shared-lib                    [===========    ] 67%  │
+│  ○ org/mobile-app                                           │
+│  ○ org/docs                                                 │
+│                                                             │
+│  3/5 repositories cloned                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### D.20 Confirmation Prompts
+
+Required confirmations:
+- **Delete session** - "Permanently delete '{name}'? This cannot be undone."
+- **Archive session** - "Archive '{name}'? You can restore it later."
+- **Remove repository** - "Remove '{repo}' from workspace? Local files will be kept."
+- **Logout** - "Log out of Purple? Your workspaces will remain on this machine."
+
+### D.21 No Claude Code Installed
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ✗ Claude Code not found                                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Purple requires Claude Code to be installed.               │
+│                                                             │
+│  Install with:                                              │
+│  npm install -g @anthropic/claude-code                      │
+│                                                             │
+│  Or visit: https://claude.ai/code                           │
+│                                                             │
+│  [Press any key to exit]                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### D.22 Workspace Rename
+
+```go
+func renameWorkspace(workspaceID, newName string) error {
+    // Update backend
+    _, err := api.UpdateWorkspace(workspaceID, newName)
+    if err != nil {
+        return err
+    }
+
+    // Local purple.json doesn't store name, only ID
+    // So no local file changes needed
+
+    return nil
+}
+```