panopticon-cli 0.1.3 → 0.2.0

package/README.md

@@ -25,14 +25,142 @@ Panopticon is a unified orchestration layer for AI coding assistants. It works w
 - **Context Engineering** - Structured state management (STATE.md, WORKSPACE.md)
 - **Agent CVs** - Work history tracking for capability-based routing
 
+---
+
+## Legacy Codebase Support
+
+> **"AI works great on greenfield projects, but it's hopeless on our legacy code."**
+>
+> Sound familiar? Your developers aren't wrong. But they're not stuck, either.
+
+### The Problem Every Enterprise Faces
+
+AI coding assistants are trained on modern, well-documented open-source code. When they encounter your 15-year-old monolith with:
+
+- Mixed naming conventions (some `snake_case`, some `camelCase`, some `SCREAMING_CASE`)
+- Undocumented tribal knowledge ("we never touch the `processUser()` function directly")
+- Schemas that don't match the ORM ("the `accounts` table is actually users")
+- Three different async patterns in the same codebase
+- Build systems that require arcane incantations
+
+...they stumble. Repeatedly. Every session starts from zero.
+
+### Panopticon's Unique Solution: Adaptive Learning
+
+Panopticon includes two AI self-monitoring skills that **no other orchestration framework provides**:
+
+| Skill | What It Does | Business Impact |
+|-------|--------------|-----------------|
+| **Knowledge Capture** | Detects when AI makes mistakes or gets corrected, prompts to document the learning | AI gets smarter about YOUR codebase over time |
+| **Refactor Radar** | Identifies systemic code issues causing repeated AI confusion, creates actionable proposals | Surfaces technical debt that's costing you AI productivity |
+
+#### How It Works
+
+```
+Session 1: AI queries users.created_at → Error (column is "createdAt")
+           → Knowledge Capture prompts: "Document this convention?"
+           → User: "Yes, create skill"
+           → Creates project-specific skill documenting naming conventions
+
+Session 2: AI knows to use camelCase for this project
+           No more mistakes on column names
+
+Session 5: Refactor Radar detects: "Same entity called 'user', 'account', 'member'
+           across layers - this is causing repeated confusion"
+           → Offers to create issue with refactoring proposal
+           → Tech lead reviews and schedules cleanup sprint
+```
+
+#### The Compound Effect
+
+| Week | Without Panopticon | With Panopticon |
+|------|-------------------|-----------------|
+| 1 | AI makes 20 mistakes/day on conventions | AI makes 20 mistakes, captures 8 learnings |
+| 2 | AI makes 20 mistakes/day (no memory) | AI makes 12 mistakes, captures 5 more |
+| 4 | AI makes 20 mistakes/day (still no memory) | AI makes 3 mistakes, codebase improving |
+| 8 | Developers give up on AI for legacy code | AI is productive, tech debt proposals in backlog |
+
+#### Shared Team Knowledge
+
+**When one developer learns, everyone benefits.**
+
+Captured skills live in your project's `.claude/skills/` directory - they're version-controlled alongside your code. When Sarah documents that "we use camelCase columns" after hitting that error, every developer on the team - and every AI session from that point forward - inherits that knowledge automatically.
+
+```
+myproject/
+├── .claude/skills/
+│   └── project-knowledge/     # ← Git-tracked, shared by entire team
+│       └── SKILL.md           # "Database uses camelCase, not snake_case"
+├── src/
+└── ...
+```
+
+No more repeating the same corrections to AI across 10 different developers. No more tribal knowledge locked in one person's head. The team's collective understanding of your codebase becomes permanent, searchable, and automatically applied.
+
+**New hire onboarding?** The AI already knows your conventions from day one.
+
+#### For Technical Leaders
+
+**What gets measured gets managed.** Panopticon's Refactor Radar surfaces the specific patterns that are costing you AI productivity:
+
+- "Here are the 5 naming inconsistencies causing 40% of AI errors"
+- "These 3 missing FK constraints led to 12 incorrect deletions last month"
+- "Mixed async patterns in payments module caused 8 rollbacks"
+
+Each proposal includes:
+- **Evidence**: Specific file paths and examples
+- **Impact**: How this affects AI (and new developers)
+- **Migration path**: Incremental fix that won't break production
+
+#### For Executives
+
+**ROI is simple:**
+
+- $200K/year senior developer spends 2 hours/day correcting AI on legacy code
+- That's $50K/year in wasted productivity per developer
+- Team of 10 = **$500K/year** in AI friction
+
+Panopticon's learning system:
+- Captures corrections once, applies them forever
+- Identifies root causes (not just symptoms)
+- Creates actionable improvement proposals
+- Works across your entire AI toolchain (Claude, Codex, Cursor, Gemini)
+
+**This isn't "AI for greenfield only." This is AI that learns your business.**
+
+#### Configurable Per Team and Per Developer
+
+Different teams have different ownership boundaries. Individual developers have different preferences. Panopticon respects both:
+
+```markdown
+# In ~/.claude/CLAUDE.md (developer's personal config)
+
+## AI Suggestion Preferences
+
+### refactor-radar
+skip: database-migrations, infrastructure  # DBA/Platform team handles these
+welcome: naming, code-organization         # Always happy for these
+
+### knowledge-capture
+skip: authentication                       # Security team owns this
+```
+
+- **"Skip database migrations"** - Your DBA has a change management process
+- **"Skip infrastructure"** - Platform team owns that
+- **"Welcome naming fixes"** - Low risk, high value, always appreciated
+
+The AI adapts to your org structure, not the other way around.
+
+---
+
 ## Quick Start
 
 ```bash
 # Install Panopticon
 npm install -g panopticon-cli
 
-# Initialize configuration
-pan init
+# Install prerequisites and setup (includes optional HTTPS/Traefik)
+pan install
 
 # Sync skills to all AI tools
 pan sync
@@ -41,12 +169,64 @@ pan sync
 pan doctor
 ```
 
+### HTTPS Setup (Optional)
+
+Panopticon supports local HTTPS via Traefik reverse proxy:
+
+```bash
+# Full install (includes Traefik + mkcert for HTTPS)
+pan install
+
+# Add to /etc/hosts (macOS/Linux)
+echo "127.0.0.1 pan.localhost" | sudo tee -a /etc/hosts
+
+# Start with HTTPS
+pan up
+# → Dashboard: https://pan.localhost
+# → Traefik UI: https://traefik.pan.localhost:8080
+```
+
+**Minimal install** (skip Traefik, use ports):
+```bash
+pan install --minimal
+pan up
+# → Dashboard: http://localhost:3010
+```
+
+See [docs/DNS_SETUP.md](docs/DNS_SETUP.md) for detailed DNS configuration (especially for WSL2).
+
+## Supported Platforms
+
+| Platform | Support |
+|----------|---------|
+| **Linux** | Full support |
+| **macOS** | Full support |
+| **Windows** | WSL2 required |
+
+> **Windows users:** Panopticon requires WSL2 (Windows Subsystem for Linux 2). Native Windows is not supported. [Install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install)
+
 ## Requirements
 
+### Required
 - Node.js 18+
-- tmux (for agent sessions)
 - Git (for worktree-based workspaces)
-- Linear API key (for issue tracking)
+- Docker (for Traefik and workspace containers)
+- tmux (for agent sessions)
+- **ttyd** - Web terminal for interactive planning sessions. Auto-installed by `pan install`.
+- **GitHub CLI (`gh`)** - For GitHub integration (issues, PRs, merges). [Install](https://cli.github.com/)
+- **GitLab CLI (`glab`)** - For GitLab integration (if using GitLab). [Install](https://gitlab.com/gitlab-org/cli)
+
+### Optional
+- **mkcert** - For HTTPS certificates (recommended)
+- **Linear API key** - For issue tracking integration
+- **Beads CLI (bd)** - For persistent task tracking across sessions
+
+### Why CLI tools instead of API tokens?
+
+Panopticon uses `gh` and `glab` CLIs instead of raw API tokens because:
+- **Better auth**: OAuth tokens that auto-refresh (no expiring PATs)
+- **Simpler setup**: `gh auth login` handles everything
+- **Agent-friendly**: Agents can use them for PRs, merges, reviews
 
 ## Configuration
 
@@ -54,9 +234,44 @@ Create `~/.panopticon.env`:
 
 ```bash
 LINEAR_API_KEY=lin_api_xxxxx
-GITHUB_TOKEN=ghp_xxxxx  # Optional: for secondary tracker
+GITHUB_TOKEN=ghp_xxxxx  # Optional: for GitHub-tracked projects
+```
+
+### Register Projects
+
+Register your local project directories so Panopticon knows where to create workspaces:
+
+```bash
+# Register a project
+pan project add /path/to/your/project --name myproject
+
+# List registered projects
+pan project list
 ```
 
+### Map Linear Projects to Local Directories
+
+If you have multiple Linear projects, configure which local directory each maps to. Create/edit `~/.panopticon/project-mappings.json`:
+
+```json
+[
+  {
+    "linearProjectId": "abc123",
+    "linearProjectName": "Mind Your Now",
+    "linearPrefix": "MIN",
+    "localPath": "/home/user/projects/myn"
+  },
+  {
+    "linearProjectId": "def456",
+    "linearProjectName": "Househunt",
+    "linearPrefix": "HH",
+    "localPath": "/home/user/projects/househunt"
+  }
+]
+```
+
+The dashboard uses this mapping to determine where to create workspaces when you click "Create Workspace" or "Start Agent" for an issue.
+
 ## Commands
 
 ### Core Commands
@@ -111,6 +326,93 @@ pan work hook push agent-min-123 "Continue with tests"
 pan work hook mail agent-min-123 "Review feedback received"
 ```
 
+### Workspace Management
+
+**Workspaces are git worktrees** - isolated working directories for each issue/feature. Each workspace:
+- Has its own feature branch (e.g., `feature/min-123-add-login`)
+- Shares git history with the main repo (no separate clone)
+- Can run independently (separate node_modules, builds, etc.)
+- Is located at `{project}/workspaces/{issue-id}/`
+
+This allows multiple agents to work on different features simultaneously without conflicts.
+
+#### Git-Backed Collaborative Planning
+
+| Start Planning | Codebase Exploration | Discovery Questions |
+|----------------|---------------------|---------------------|
+| ![Start](docs/planning-session-dialog.png) | ![Exploring](docs/planning-session-active.png) | ![Discovery](docs/planning-session-discovery.png) |
+| Click to create workspace and start AI planning | Claude explores the codebase, reads docs, understands patterns | Interactive questions to clarify requirements and approach |
+
+Planning artifacts are stored **inside the workspace**, making them part of the feature branch:
+
+```
+workspaces/feature-min-123/
+├── .planning/
+│   ├── output.jsonl          # Full conversation history (tool uses + results)
+│   ├── PLANNING_PROMPT.md    # Initial planning prompt
+│   ├── CONTINUATION_PROMPT.md # Context for continued sessions
+│   └── output-*.jsonl        # Backup of previous rounds
+└── ... (code)
+```
+
+![Planning Session Output](docs/planning-session-output.png)
+
+When the planning session completes, the AI generates:
+- **STATE.md** - Current understanding, decisions made, and implementation plan
+- **Beads tasks** - Trackable sub-tasks with dependencies for the implementation
+- **Feature PRD** - Copied to `docs/prds/active/{issue}-plan.md` for documentation
+
+**This enables:**
+
+1. **Collaborative async planning** - Push your branch, someone else pulls and continues the planning session with full context
+2. **Context recovery** - If Claude's context compacts, the full conversation is preserved in the branch
+3. **Audit trail** - See how planning decisions were made, what files were explored, what questions were asked
+4. **Branch portability** - The planning state travels with the feature branch
+
+**Dashboard workflow (recommended):**
+
+The planning dialog has **Pull** and **Push** buttons that handle git operations automatically:
+
+| Button | What it does |
+|--------|--------------|
+| **Pull** | Fetches from origin, creates workspace from remote branch if needed, pulls latest changes |
+| **Push** | Commits `.planning/` artifacts and pushes to origin |
+
+1. Person A starts planning in dashboard, clicks **Push** when interrupted
+2. Person B opens same issue in dashboard, clicks **Pull** → gets Person A's full context
+3. Person B continues the planning session and clicks **Push** when done
+
+**CLI workflow:**
+```bash
+# Person A starts planning
+pan work plan MIN-123
+# ... answers discovery questions, gets interrupted ...
+
+# Push the branch (includes planning context)
+cd workspaces/feature-min-123
+git add .planning && git commit -m "WIP: planning session"
+git push origin feature/min-123
+
+# Person B continues
+git pull origin feature/min-123
+pan work plan MIN-123 --continue
+# Claude has full context from Person A's session
+```
+
+```bash
+# Create a workspace (git worktree) without starting an agent
+pan workspace create MIN-123
+
+# List all workspaces
+pan workspace list
+
+# Destroy a workspace
+pan workspace destroy MIN-123
+
+# Force destroy (even with uncommitted changes)
+pan workspace destroy MIN-123 --force
+```
+
 ### Project Management
 
 ```bash
@@ -159,33 +461,153 @@ pan work recover --all
 
 ## Dashboard
 
+![Panopticon Dashboard](docs/dashboard-overview.png)
+
 Start the monitoring dashboard:
 
 ```bash
 pan up
 ```
 
-- Frontend: http://localhost:3001
-- API: http://localhost:3002
+**Recommended (containerized with HTTPS):**
+- Dashboard: https://pan.localhost
+- Traefik UI: https://traefik.pan.localhost:8082
+
+This runs everything in Docker containers, avoiding port conflicts with your other projects.
+
+**Minimal install (no Docker):**
+```bash
+pan up --minimal
+```
+- Dashboard: http://localhost:3010
 
 Stop with `pan down`.
 
+### Dashboard Tabs
+
+| Tab | Purpose |
+|-----|---------|
+| **Board** | Kanban view of Linear issues with drag-and-drop status changes |
+| **Agents** | Running agent sessions with terminal output |
+| **Activity** | Real-time `pan` command output log |
+| **Metrics** | Runtime comparison and cost tracking |
+| **Skills** | Available skills and their descriptions |
+| **Health** | System health checks and diagnostics |
+
+### Metrics & Cost Tracking
+
+The **Metrics** tab provides insights into AI agent performance and costs:
+
+- **Per-issue cost badges** - See costs directly on Kanban cards (color-coded by amount)
+- **Issue cost breakdown** - Click an issue to see detailed costs by model and session
+- **Runtime comparison** - Compare success rates, duration, and costs across runtimes (Claude, Codex, etc.)
+- **Capability analysis** - See how different task types (feature, bugfix, refactor) perform
+
+Cost data is stored in `~/.panopticon/`:
+- `session-map.json` - Links Claude Code sessions to issues
+- `runtime-metrics.json` - Aggregated runtime performance data
+- `costs/` - Raw cost logs
+
+**API Endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/costs/summary` | Overall cost summary (today/week/month) |
+| `GET /api/costs/by-issue` | Costs grouped by issue |
+| `GET /api/issues/:id/costs` | Cost details for a specific issue |
+| `GET /api/metrics/runtimes` | Runtime comparison metrics |
+| `GET /api/metrics/tasks` | Recent task history |
+
 ## Skills
 
-Panopticon ships with 10+ high-value skills:
+Panopticon ships with 25+ skills organized into categories:
+
+### Development Workflows
 
 | Skill | Description |
 |-------|-------------|
 | `feature-work` | Standard feature development workflow |
 | `bug-fix` | Systematic bug investigation and fix |
+| `refactor` | Safe refactoring with test coverage |
 | `code-review` | Comprehensive code review checklist |
 | `code-review-security` | OWASP Top 10 security analysis |
 | `code-review-performance` | Algorithm and resource optimization |
-| `refactor` | Safe refactoring with test coverage |
 | `release` | Step-by-step release process |
-| `incident-response` | Production incident handling |
 | `dependency-update` | Safe dependency updates |
+| `incident-response` | Production incident handling |
 | `onboard-codebase` | Understanding new codebases |
+| `work-complete` | Checklist for completing agent work |
+
+### AI Self-Monitoring
+
+| Skill | Description |
+|-------|-------------|
+| `knowledge-capture` | Captures learnings when AI gets confused or corrected |
+| `refactor-radar` | Detects systemic issues causing AI confusion |
+| `session-health` | Detect and clean up stuck sessions |
+
+### Panopticon Operations (pan-*)
+
+| Skill | Description |
+|-------|-------------|
+| `pan-help` | Show all Panopticon commands |
+| `pan-up` | Start dashboard and services |
+| `pan-down` | Stop dashboard and services |
+| `pan-status` | Show running agents |
+| `pan-issue` | Spawn agent for an issue |
+| `pan-plan` | Create execution plan for issue |
+| `pan-tell` | Send message to running agent |
+| `pan-kill` | Kill a running agent |
+| `pan-approve` | Approve agent work and merge |
+| `pan-health` | Check system health |
+| `pan-sync` | Sync skills to AI tools |
+| `pan-install` | Install prerequisites |
+| `pan-setup` | Initial setup wizard |
+| `pan-quickstart` | Quick start guide |
+| `pan-projects` | Manage registered projects |
+| `pan-tracker` | Issue tracker operations |
+| `pan-logs` | View agent logs |
+| `pan-rescue` | Recover crashed agents |
+| `pan-diagnose` | Diagnose agent issues |
+| `pan-docker` | Docker operations |
+| `pan-network` | Network diagnostics |
+| `pan-config` | Configuration management |
+| `pan-convoy-synthesis` | Synthesize convoy coordination |
+| `pan-subagent-creator` | Create specialized subagents |
+| `pan-skill-creator` | Create new skills (guided) |
+
+### Utilities
+
+| Skill | Description |
+|-------|-------------|
+| `beads` | Git-backed issue tracking with dependencies |
+| `skill-creator` | Guide for creating new skills |
+| `web-design-guidelines` | UI/UX review checklist |
+
+### Reserved Skill Names
+
+Panopticon reserves all skill names listed above. **Do not use these names for project-specific skills** to avoid conflicts.
+
+**Recommendation:** Use a project-specific prefix for your skills (e.g., `myn-standards`, `acme-deployment`) to avoid namespace collisions.
+
+### Project-Specific Skills
+
+Projects can have their own skills alongside Panopticon's:
+
+```
+~/.claude/skills/
+├── pan-help/           # Symlink → ~/.panopticon/skills/pan-help/
+├── feature-work/       # Symlink → ~/.panopticon/skills/feature-work/
+└── ... (other pan skills)
+
+{project}/.claude/skills/
+├── myn-standards/      # Project-specific (git-tracked)
+└── myn-api-patterns/   # Project-specific (git-tracked)
+```
+
+Project-specific skills in `{project}/.claude/skills/` are **not managed by Panopticon**. They live in your project's git repo and take precedence over global skills with the same name.
+
+### Skill Distribution
 
 Skills are synced to all supported AI tools via symlinks:
 
@@ -197,21 +619,80 @@ Skills are synced to all supported AI tools via symlinks:
 ~/.gemini/skills/        # Gemini CLI
 ```
 
+## PRD Convention
+
+Panopticon enforces a standard approach to Product Requirements Documents (PRDs) across all managed projects.
+
+### PRD Structure
+
+Every project has a **canonical PRD** that defines the core product:
+
+```
+{project}/
+├── docs/
+│   └── PRD.md              # The canonical PRD (core product definition)
+├── workspaces/
+│   └── feature-{issue}/
+│       └── docs/
+│           └── {ISSUE}-plan.md   # Feature PRD (lives in feature branch)
+```
+
+| PRD Type | Location | Purpose |
+|----------|----------|---------|
+| **Canonical PRD** | `docs/PRD.md` | Core product definition, always on main |
+| **Feature PRD** | `workspaces/feature-{issue}/docs/{ISSUE}-plan.md` | Feature spec, lives in feature branch, merged with PR |
+
+### Feature PRDs Live in Workspaces
+
+When you start planning an issue, Panopticon creates:
+1. A git worktree (workspace) for the feature branch
+2. A planning session that generates a feature PRD
+
+The feature PRD **lives in the workspace** (feature branch) because:
+- It gets merged with the PR (documentation travels with code)
+- If you abort planning and delete the workspace, you don't want orphaned PRDs
+- Clean separation - each feature is self-contained
+
+### Project Initialization
+
+When registering a new project with Panopticon (`pan project add`), the system will:
+
+1. **Check for existing PRD** - Look for `docs/PRD.md`, `PRD.md`, `README.md`, or similar
+2. **If found**: Use it to create/update the canonical PRD format, prompting for any missing crucial information
+3. **If not found**: Generate one by:
+   - Analyzing the codebase structure
+   - Identifying key technologies and patterns
+   - Asking discovery questions about the product
+
+This ensures every Panopticon-managed project has a well-defined canonical PRD that agents can reference.
+
+### PRD Naming Convention
+
+| Document | Naming | Example |
+|----------|--------|---------|
+| Canonical PRD | `PRD.md` | `docs/PRD.md` |
+| Feature PRD | `{ISSUE}-plan.md` | `MIN-123-plan.md`, `PAN-4-plan.md` |
+| Planning artifacts | In `.planning/{issue}/` | `.planning/min-123/STATE.md` |
+
 ## Architecture
 
 ```
 ~/.panopticon/
-  skills/             # Shared skills (SKILL.md format)
-  commands/           # Slash commands
-  agents/             # Per-agent state
+  skills/               # Shared skills (SKILL.md format)
+  commands/             # Slash commands
+  agents/               # Per-agent state
     agent-min-123/
-      state.json      # Agent state
-      health.json     # Health status
-      hook.json       # GUPP work queue
-      cv.json         # Work history
-      mail/           # Incoming messages
-  projects.json       # Managed projects
-  backups/            # Sync backups
+      state.json        # Agent state
+      health.json       # Health status
+      hook.json         # GUPP work queue
+      cv.json           # Work history
+      mail/             # Incoming messages
+  projects.json         # Managed projects
+  project-mappings.json # Linear project → local path mappings
+  session-map.json      # Claude sessions → issue linking
+  runtime-metrics.json  # Runtime performance metrics
+  costs/                # Raw cost logs (JSONL)
+  backups/              # Sync backups
 ```
 
 ## Health Monitoring (Deacon Pattern)
@@ -237,6 +718,148 @@ GUPP ensures agents are self-propelling:
 3. Pending work is injected into the agent's prompt
 4. Completed work is popped from the hook
 
-## License
+## Development
+
+### Dev vs Production Strategy
+
+Panopticon uses a **shared config, switchable CLI** approach:
+
+```
+~/.panopticon/           # Shared by both dev and prod
+├── config.toml          # Settings
+├── projects.json        # Registered projects
+├── project-mappings.json # Linear → local path mappings
+├── agents/              # Agent state
+└── skills/              # Shared skills
+```
+
+Both dev and production versions read/write the same config, so you can switch between them freely.
+
+### Running in Development Mode
+
+```bash
+# Clone and setup
+git clone https://github.com/eltmon/panopticon.git
+cd panopticon
+npm install
+
+# Link dev version globally (makes 'pan' use your local code)
+npm link
+
+# Start the dashboard (with hot reload)
+cd src/dashboard
+npm run install:all
+npm run dev
+# → Frontend: http://localhost:3010
+# → API: http://localhost:3011
+```
+
+### Switching Between Dev and Prod
 
-MIT
+```bash
+# Use dev version (from your local repo)
+cd /path/to/panopticon && npm link
+
+# Switch back to stable release
+npm unlink panopticon-cli
+npm install -g panopticon-cli
+```
+
+### Dashboard Modes
+
+| Mode | Command | Use Case |
+|------|---------|----------|
+| **Production** | `pan up` | Daily usage, containerized, HTTPS at https://pan.localhost |
+| **Dev** | `cd src/dashboard && npm run dev` | Only for active development on Panopticon itself |
+
+**Note:** Use `pan up` for normal usage - it runs in Docker and won't conflict with your project's ports. Only use dev mode when actively working on Panopticon's codebase.
+
+### Working on Panopticon While Using It
+
+If you're both developing Panopticon AND using it for your own projects:
+
+1. **Use `npm link`** so CLI changes take effect immediately
+2. **Run dashboard from source** for hot reload on UI changes
+3. **Config is shared** - workspaces/agents work the same either way
+4. **Test in a real project** - your own usage is the best test
+
+## Troubleshooting
+
+### Slow Vite/React Frontend with Multiple Workspaces
+
+If running multiple containerized workspaces with Vite/React frontends, you may notice CPU spikes and slow HMR. This is because Vite's default file watching polls every 100ms, which compounds with multiple instances.
+
+**Fix:** Increase the polling interval in your `vite.config.mjs`:
+
+```javascript
+server: {
+    watch: {
+        usePolling: true,
+        interval: 3000,  // Poll every 3s instead of 100ms default
+    },
+}
+```
+
+A 3000ms interval supports 4-5 concurrent workspaces comfortably while maintaining acceptable HMR responsiveness.
+
+### Corrupted Workspaces
+
+A workspace can become "corrupted" when it exists as a directory but is no longer a valid git worktree. The dashboard will show a yellow "Workspace Corrupted" warning with an option to clean and recreate.
+
+**Symptoms:**
+- Dashboard shows "Workspace Corrupted" warning
+- `git status` in the workspace fails with "not a git repository"
+- The `.git` file is missing from the workspace directory
+
+**Common Causes:**
+
+| Cause | Description |
+|-------|-------------|
+| **Interrupted creation** | `pan workspace create` was killed mid-execution (Ctrl+C, system crash) |
+| **Manual .git deletion** | Someone accidentally deleted the `.git` file in the workspace |
+| **Disk space issues** | Ran out of disk space during workspace creation |
+| **Git worktree pruning** | Running `git worktree prune` in the main repo removed the worktree link |
+| **Force-deleted main repo** | The main repository was moved or deleted while workspaces existed |
+
+**Resolution:**
+
+1. **Via Dashboard (recommended):**
+   - Click on the issue to open the detail panel
+   - Click "Clean & Recreate" button
+   - Review the files that will be deleted
+   - Check "Create backup" to preserve your work (recommended)
+   - Click "Backup & Recreate"
+
+2. **Via CLI:**
+   ```bash
+   # Option 1: Manual cleanup
+   rm -rf /path/to/project/workspaces/feature-issue-123
+   pan workspace create ISSUE-123
+
+   # Option 2: Backup first
+   cp -r /path/to/project/workspaces/feature-issue-123 /tmp/backup-issue-123
+   rm -rf /path/to/project/workspaces/feature-issue-123
+   pan workspace create ISSUE-123
+   # Then manually restore files from backup
+   ```
+
+**Prevention:**
+- Don't interrupt `pan workspace create` commands
+- Don't run `git worktree prune` in the main repo without checking for active workspaces
+- Ensure adequate disk space before creating workspaces
+
+## ⭐ Star History
+
+<a href="https://star-history.com/#eltmon/panopticon&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=eltmon/panopticon&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=eltmon/panopticon&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=eltmon/panopticon&type=Date" />
+ </picture>
+</a>
+
+## ⚖️ License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)