panopticon-cli 0.3.7 → 0.4.4

package/README.md

@@ -1,32 +1,72 @@
+<div align="center">
+
 # Panopticon CLI
 
-Multi-agent orchestration for AI coding assistants.
+**Multi-agent orchestration for AI coding assistants**
+
+[![npm version](https://img.shields.io/npm/v/panopticon-cli.svg)](https://www.npmjs.com/package/panopticon-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/eltmon/panopticon/pulls)
 
 > *"The Panopticon had six sides, one for each of the Founders of Gallifrey..."*
 
-## Overview
+<img src="docs/dashboard-overview.png" alt="Panopticon Dashboard" width="800" />
+
+</div>
+
+---
 
-Panopticon is a unified orchestration layer for AI coding assistants. It works with:
+## What is Panopticon?
+
+| Without Panopticon | With Panopticon |
+|:------------------|:----------------|
+| Manually juggle multiple AI agents | **Automatic orchestration** - spawn, monitor, and coordinate agents from a dashboard |
+| Agents start fresh every session | **Persistent context** - skills, state files, and beads track work across sessions |
+| Simple tasks eat Opus credits | **Smart model routing** - Haiku for simple, Sonnet for medium, Opus for complex |
+| Stuck agents waste your time | **Automatic recovery** - detect stuck agents and hand off to specialists |
+| AI tools have separate configs | **Universal skills** - one SKILL.md works across Claude, Codex, Cursor, Gemini |
+
+## Screenshots
+
+<div align="center">
+<table>
+<tr>
+<td><img src="docs/planning-session-dialog.png" alt="Planning Dialog" width="300" /></td>
+<td><img src="docs/planning-session-discovery.png" alt="Discovery Phase" width="300" /></td>
+<td><img src="docs/planning-session-active.png" alt="Active Session" width="300" /></td>
+</tr>
+<tr>
+<td align="center"><em>Start planning</em></td>
+<td align="center"><em>Discovery phase</em></td>
+<td align="center"><em>Active session</em></td>
+</tr>
+</table>
+</div>
+
+## Key Features
+
+| Feature | Description |
+|:--------|:------------|
+| **Multi-Agent Orchestration** | Spawn and manage AI agents in tmux sessions via dashboard or CLI |
+| **Cloister Lifecycle Manager** | Automatic model routing, stuck detection, and specialist handoffs |
+| **Universal Skills** | One SKILL.md format works across all supported AI tools |
+| **Workspaces** | Git worktree-based feature branches with Docker isolation |
+| **Convoys** | Run parallel agents on related issues with auto-synthesis |
+| **Specialists** | Dedicated review, test, and merge agents for quality control |
+| **Heartbeat Monitoring** | Real-time agent activity tracking via Claude Code hooks |
+| **Legacy Codebase Support** | AI self-monitoring skills that learn from your codebase |
+
+## Supported Tools
 
 | Tool | Support |
-|------|---------|
+|:-----|:--------|
 | **Claude Code** | Full support |
 | **Codex** | Skills sync |
 | **Cursor** | Skills sync |
 | **Gemini CLI** | Skills sync |
 | **Google Antigravity** | Skills sync |
 
-### Features
-
-- **Multi-agent orchestration** - Spawn and manage multiple AI agents in tmux sessions
-- **Cloister AI Lifecycle Manager** - Automatic model routing, stuck detection, and specialist handoffs
-- **Universal skills** - One SKILL.md format works across all supported tools
-- **Heartbeat Hooks** - Real-time agent activity monitoring via Claude Code hooks
-- **Multi-project support** - YAML-based project registry with label-based issue routing
-- **Health Monitoring** - Deacon-style stuck detection with auto-recovery
-- **Context Engineering** - Structured state management (STATE.md, WORKSPACE.md)
-- **Agent CVs** - Work history tracking for capability-based routing
-
 ---
 
 ## Legacy Codebase Support
@@ -158,54 +198,12 @@ The AI adapts to your org structure, not the other way around.
 ## Quick Start
 
 ```bash
-# Install Panopticon
-npm install -g panopticon-cli
-
-# Install prerequisites and setup (includes optional HTTPS/Traefik)
-pan install
-
-# Sync skills to all AI tools
-pan sync
-
-# Check system health
-pan doctor
+npm install -g panopticon-cli && pan install && pan sync && pan up
 ```
 
-### HTTPS Setup (Optional)
+**That's it!** Dashboard runs at https://pan.localhost (or http://localhost:3010 if you skip HTTPS setup).
 
-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)
+📖 **[Full installation guide, requirements, and platform support →](https://panopticon-cli.com/quickstart)**
 
 ## Requirements
 
@@ -221,7 +219,8 @@ See [docs/DNS_SETUP.md](docs/DNS_SETUP.md) for detailed DNS configuration (espec
 ### Optional
 - **mkcert** - For HTTPS certificates (recommended)
 - **Linear API key** - For issue tracking integration
-- **Beads CLI (bd)** - For persistent task tracking across sessions
+- **Beads CLI (bd)** - For persistent task tracking across sessions. Auto-installed by `pan install`. Upgrade with `pan beads upgrade`.
+- **Google Stitch MCP** - For AI-powered UI design integration (see below)
 
 ### Platform Support
 
@@ -268,6 +267,111 @@ Panopticon supports multiple issue trackers:
 
 Secondary trackers sync issues to the dashboard alongside Linear issues, allowing unified project management.
 
+### Multi-Model Support
+
+Panopticon integrates with [claude-code-router](https://github.com/musistudio/claude-code-router) to enable using multiple AI model providers alongside Anthropic models. Configure which models to use for different agent types and task complexities.
+
+📖 **[Complete work types guide and configuration examples →](docs/WORK-TYPES.md)**
+📋 **[Configuration file reference and presets →](docs/CONFIGURATION.md)**
+🧠 **[Model recommendations for optimal cost/performance →](docs/MODEL_RECOMMENDATIONS.md)**
+
+#### Supported Providers and Models
+
+**Anthropic** (via Claude Code / Claude API)
+- `claude-opus-4-5` - Most capable, best for planning and complex tasks
+- `claude-sonnet-4-5` - Balanced performance and cost
+- `claude-haiku-4-5` - Fast and cost-effective for simple tasks
+
+**OpenAI**
+- `gpt-5.2-codex` - Agentic coding and research
+- `o3-deep-research` - Deep research capabilities
+- `gpt-4o` - General-purpose model
+- `gpt-4o-mini` - Faster, more cost-effective variant
+
+**Google (Gemini)**
+- `gemini-3-pro-preview` - Supports `thinking_level: high|low`
+- `gemini-3-flash-preview` - Supports `thinking_level: minimal|low|medium|high`
+
+**Z.AI**
+- `glm-4.7` - General-purpose model
+- `glm-4.7-flash` - Faster variant
+
+#### Configuration via Dashboard
+
+1. Open the Panopticon dashboard and navigate to **Settings**
+2. Configure **API keys** for external providers:
+   - OpenAI API Key
+   - Google AI API Key
+   - Z.AI API Key
+3. Configure **models per agent type**:
+   - Review Agent - Model for code review
+   - Test Agent - Model for running tests
+   - Merge Agent - Model for handling merges
+   - Planning Agent - Model for autonomous planning
+4. Configure **models by task complexity** (for PAN-75):
+   - Trivial tasks → Cost-effective models (e.g., `claude-haiku-4-5`)
+   - Expert tasks → Most capable models (e.g., `claude-opus-4-5`)
+
+**Configuration Files:**
+
+Panopticon uses YAML-based configuration (new in v0.5+):
+
+| File | Purpose |
+|------|---------|
+| `~/.panopticon/config.yaml` | Global model settings, provider enable/disable, API key references |
+| `~/.panopticon.env` | API keys and sensitive credentials (auto-loaded) |
+| `.panopticon.yaml` | Per-project config (optional, overrides global) |
+
+**Security:** For added security, restrict file permissions:
+```bash
+chmod 600 ~/.panopticon/config.yaml ~/.panopticon.env
+```
+
+**Environment Variables:** API keys are loaded from `~/.panopticon.env` at startup:
+```bash
+# ~/.panopticon.env
+KIMI_API_KEY="sk-kimi-..."
+OPENAI_API_KEY="sk-..."
+GOOGLE_AI_KEY="AIza..."
+ZAI_API_KEY="..."
+```
+
+In `config.yaml`, reference them with `$` syntax:
+```yaml
+models:
+  providers:
+    kimi:
+      enabled: true
+      api_key: $KIMI_API_KEY
+```
+
+#### Router Configuration
+
+**Panopticon owns the router configuration.** When you save settings in the dashboard, Panopticon automatically generates `~/.claude-code-router/config.json` with the appropriate provider and routing configuration. Manual edits to this file will be overwritten on the next settings change.
+
+#### Example Use Cases
+
+**Cost optimization:**
+```
+Specialist agents → claude-sonnet-4-5 (balanced)
+Planning agent → claude-opus-4-5 (most capable)
+Simple tasks → claude-haiku-4-5 (cost-effective)
+```
+
+**Multi-provider setup:**
+```
+Code review → gpt-4o (OpenAI's code understanding)
+Testing → claude-sonnet-4-5 (Anthropic's reliability)
+Planning → claude-opus-4-5 (Anthropic's reasoning)
+```
+
+**Research-heavy workflows:**
+```
+Research tasks → o3-deep-research (OpenAI)
+Implementation → claude-sonnet-4-5 (Anthropic)
+Code review → gemini-3-pro-preview (Google)
+```
+
 ### Register Projects
 
 Register your local project directories so Panopticon knows where to create workspaces:
@@ -303,6 +407,109 @@ If you have multiple Linear projects, configure which local directory each maps
 
 The dashboard uses this mapping to determine where to create workspaces when you click "Create Workspace" or "Start Agent" for an issue.
 
+## Google Stitch Integration
+
+Panopticon integrates with [Google Stitch](https://stitch.withgoogle.com), Google's AI-powered UI design tool, enabling design-to-code workflows.
+
+### What is Google Stitch?
+
+Google Stitch generates production-ready UI designs from natural language prompts or image inputs. It's free (350 standard + 50 experimental generations/month) and requires only a Google account.
+
+### Setup (Optional)
+
+Use the `/pan-stitch` skill to set up the integration:
+
+```bash
+# Run the setup skill
+/pan-stitch
+
+# Or manually:
+# 1. Install gcloud CLI
+curl -sSL https://sdk.cloud.google.com | bash
+
+# 2. Authenticate
+gcloud auth login
+gcloud auth application-default login
+
+# 3. Create project and enable API
+gcloud projects create stitch-tools-$(date +%s)
+gcloud config set project YOUR_PROJECT_ID
+gcloud billing projects link YOUR_PROJECT_ID --billing-account=YOUR_BILLING_ID
+gcloud beta services mcp enable stitch.googleapis.com  # MUST use beta!
+
+# 4. Register MCP (note "proxy" subcommand)
+claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y @_davideast/stitch-mcp proxy
+```
+
+### How It Works
+
+When Stitch is configured, the planning agent can:
+
+1. **Create UI designs** - Generate screens for UI-related issues
+2. **Document in STATE.md** - Record Stitch project/screen IDs for workers
+3. **Worker agents pick up designs** - Use the Stitch skills to convert to React
+
+### Bidirectional Sync
+
+Designs are stored in your Google account and sync bidirectionally:
+
+```
+Planning Agent creates design via MCP
+    ↓
+Stored in Google Cloud (your account)
+    ↓
+Visible on stitch.withgoogle.com
+    ↓
+Worker agent retrieves via MCP → converts to React
+```
+
+- **MCP → Web UI:** Designs created by agents appear in Stitch web UI
+- **Web UI → MCP:** Designs created in web UI are accessible to agents
+- **Edit anywhere:** Refine AI-generated designs in the web UI before workers convert them
+
+### Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `create_project` | Create a new Stitch project |
+| `list_projects` | List all your projects (owned/shared) |
+| `get_project` | Get project details |
+| `list_screens` | List screens in a project |
+| `get_screen` | Get screen details + HTML/CSS download URLs |
+| `generate_screen_from_text` | Generate a screen from a text prompt |
+
+### Stitch Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/pan-stitch` | Setup and configure Stitch MCP |
+| `/stitch-design-md` | Create DESIGN.md from Stitch projects |
+| `/stitch-react-components` | Convert Stitch HTML to React components |
+
+### STATE.md Integration
+
+When planning UI work, add a Stitch section to STATE.md:
+
+```markdown
+## UI Designs
+
+### Stitch Assets
+- **Project ID:** 12345678
+- **Screen:** "Dashboard" (screen ID: 87654321)
+- **Design Notes:** Dark mode, glassmorphism cards, gradient accents
+- **DESIGN.md:** Generated at `src/components/DESIGN.md`
+
+Worker: Use `/stitch-react-components` to convert the Dashboard screen to React.
+```
+
+### Manual Workflow (No MCP)
+
+If you prefer not to set up the MCP:
+
+1. Design at https://stitch.withgoogle.com
+2. Export HTML/CSS from the UI
+3. Use `/stitch-react-components` with the exported files
+
 ## Cloister: AI Lifecycle Manager
 
 Cloister is Panopticon's intelligent agent lifecycle manager. It monitors all running agents and automatically handles:
@@ -389,6 +596,90 @@ The merge-agent uses a specialized prompt template that instructs it to:
 - Document conflict resolution decisions
 - Provide detailed feedback on what was merged
 
+#### Review Pipeline Flow
+
+The review pipeline is a sequential handoff between specialists:
+
+```
+Human clicks "Review"
+        │
+        ▼
+┌───────────────────┐
+│   review-agent    │ Reviews code, checks for issues
+└─────────┬─────────┘
+          │ If PASSED: queues test-agent
+          │ If BLOCKED: sends feedback to work-agent
+          ▼
+┌───────────────────┐
+│    test-agent     │ Runs test suite, analyzes failures
+└─────────┬─────────┘
+          │ If PASSED: marks ready for merge
+          │ If FAILED: sends feedback to work-agent
+          ▼
+┌───────────────────┐
+│  (Human clicks    │ Human approval required
+│  "Approve & Merge"│ before merge
+└─────────┬─────────┘
+          ▼
+┌───────────────────┐
+│   merge-agent     │ Performs merge, resolves conflicts
+└───────────────────┘
+```
+
+**Key Points:**
+- **Human-initiated start** - A human must click "Review" to start the pipeline
+- **Automatic handoffs** - review-agent → test-agent happens automatically
+- **Human approval for merge** - Merge is NOT automatic; human clicks "Approve & Merge"
+- **Feedback loops** - Failed reviews/tests send feedback back to the work-agent
+
+#### Queue Processing
+
+Each specialist has a task queue (`~/.panopticon/specialists/{name}/hook.json`) managed via the FPP (Fixed Point Principle):
+
+```
+1. Task arrives (via API or handoff)
+        │
+        ▼
+2. wakeSpecialistOrQueue() checks if specialist is busy
+        │
+        ├── If IDLE: Wake specialist immediately with task
+        │
+        └── If BUSY: Add task to queue (hook.json)
+                │
+                ▼
+3. When specialist completes current task:
+        │
+        ├── Updates status via API (passed/failed/skipped)
+        │
+        └── Dashboard automatically wakes specialist for next queued task
+```
+
+**Queue priority order:** `urgent` > `high` > `normal` > `low`
+
+**Completion triggers:** When a specialist reports status (`passed`, `failed`, or `skipped`), the dashboard:
+1. Sets the specialist state to `idle`
+2. Checks the specialist's queue for pending work
+3. If work exists, immediately wakes the specialist with the next task
+
+#### Agent Self-Requeue (Circuit Breaker)
+
+After a human initiates the first review, work-agents can request re-review up to 3 times automatically:
+
+```bash
+# Work-agent requests re-review after fixing issues
+pan work request-review MIN-123 -m "Fixed: added tests for edge cases"
+```
+
+**Circuit breaker behavior:**
+- First human click resets the counter to 0
+- Each `pan work request-review` increments the counter
+- After 3 automatic re-requests, returns HTTP 429
+- Human must click "Review" in dashboard to continue
+
+This prevents infinite loops where an agent repeatedly fails review.
+
+**API endpoint:** `POST /api/workspaces/:issueId/request-review`
+
 #### Specialist Auto-Initialization
 
 When Cloister starts, it automatically initializes specialists that don't exist yet. This ensures the test-agent, review-agent, and merge-agent are ready to receive wake signals without manual setup.
@@ -626,33 +917,593 @@ projects:
       - default: true
         path: /home/user/projects/myn
 
-  panopticon:
-    name: "Panopticon"
-    path: /home/user/projects/panopticon
-    linear_team: PAN
+  panopticon:
+    name: "Panopticon"
+    path: /home/user/projects/panopticon
+    linear_team: PAN
+```
+
+### Label-Based Routing
+
+Issues are routed to different subdirectories based on their labels:
+
+1. **Labeled issues** - Matched against `issue_routing` rules in order
+2. **Default route** - Issues without matching labels use the `default: true` path
+3. **Fallback** - If no default, uses the project root path
+
+Example: An issue with label "splash" in the MIN team would create its workspace at `/home/user/projects/myn/splash/workspaces/feature-min-xxx/`.
+
+### Custom Workspace Commands (Legacy)
+
+> **Note:** For most polyrepo projects, use the built-in `workspace` configuration (see below) instead of custom scripts. Custom commands are only needed for highly specialized setups.
+
+For projects that need logic beyond what the configuration supports, you can specify custom workspace scripts:
+
+```yaml
+projects:
+  myn:
+    name: "Mind Your Now"
+    path: /home/user/projects/myn
+    linear_team: MIN
+    # Custom scripts handle complex workspace setup
+    workspace_command: /home/user/projects/myn/infra/new-feature
+    workspace_remove_command: /home/user/projects/myn/infra/remove-feature
+```
+
+When `workspace_command` is specified, Panopticon calls your script instead of creating a standard git worktree. The script receives the normalized issue ID (e.g., `min-123`) as an argument.
+
+When `workspace_remove_command` is specified, Panopticon calls your script when deleting workspaces (e.g., aborting planning with "delete workspace" enabled). This is important for complex setups that need to:
+- Stop Docker containers and remove volumes
+- Clean up root-owned files created by containers
+- Remove git worktrees from multiple repositories
+- Release port assignments
+- Remove DNS entries
+
+**What your custom script should handle:**
+- Creating git worktrees for multiple repositories (polyrepo structure)
+- Setting up Docker Compose files and dev containers
+- Configuring environment variables and `.env` files
+- Setting up DNS entries for workspace-specific URLs (e.g., Traefik routing)
+- Creating a `./dev` script for container management
+- Copying agent configuration templates (CLAUDE.md, .mcp.json, etc.)
+
+**Example script flow:**
+```bash
+#!/bin/bash
+# new-feature script for a polyrepo project
+ISSUE_ID=$1  # e.g., "min-123"
+
+# Create worktrees for frontend and api repos
+git -C /path/to/frontend worktree add ../workspaces/feature-$ISSUE_ID/fe feature/$ISSUE_ID
+git -C /path/to/api worktree add ../workspaces/feature-$ISSUE_ID/api feature/$ISSUE_ID
+
+# Generate docker-compose from templates
+sed "s/{{FEATURE_FOLDER}}/feature-$ISSUE_ID/g" template.yml > workspace/docker-compose.yml
+
+# Set up DNS and Traefik routing
+# ... additional setup
+```
+
+The standard `pan workspace create` command will automatically detect and use your custom script.
+
+#### Container Configuration Tips
+
+When setting up Docker containers for workspaces, avoid these common pitfalls:
+
+**Maven projects:**
+- DO NOT set `MAVEN_CONFIG=/some/path` as an environment variable
+- Maven interprets `MAVEN_CONFIG` as additional CLI arguments, not a directory path
+- This causes "Unknown lifecycle phase" errors (e.g., "Unknown lifecycle phase /maven-cache")
+- Instead, use `-Dmaven.repo.local=/path/to/cache` in the Maven command
+
+```yaml
+# WRONG - causes Maven startup failure
+environment:
+  - MAVEN_CONFIG=/maven-cache
+
+# CORRECT - use command line argument
+command: ./mvnw spring-boot:run -Dmaven.repo.local=/maven-cache/repository
+volumes:
+  - ~/.m2:/maven-cache:cached
+```
+
+**pnpm projects:**
+- Set `PNPM_HOME=/path` to configure the pnpm store location
+- Mount a named volume for the store to share across containers
+
+### What Your Project Needs to Provide
+
+Panopticon is an orchestration layer - it manages workspaces, agents, and workflows, but **your project repository provides the actual templates and configuration**.
+
+Projects can be as simple as just a git repo (for worktree-only workspaces) or as complex as a full polyrepo with Docker, Traefik, and database seeding. Here's what you need for each level:
+
+### Required: Workspace Templates
+
+Your project needs a `.devcontainer/` or template directory with:
+
+```
+your-project/
+├── infra/
+│   └── .devcontainer-template/      # Template for workspace containers
+│       ├── docker-compose.devcontainer.yml.template
+│       ├── compose.infra.yml.template   # Optional: separate infra services
+│       ├── Dockerfile
+│       └── devcontainer.json.template
+└── ...
+```
+
+**Docker Compose templates** should use placeholders that Panopticon will replace:
+
+```yaml
+# docker-compose.devcontainer.yml.template
+services:
+  api:
+    build: ./api
+    user: vscode  # Run as non-root to avoid permission issues
+    labels:
+      - "traefik.http.routers.{{FEATURE_FOLDER}}-api.rule=Host(`api-{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
+    environment:
+      - DATABASE_URL=postgres://app:app@postgres:5432/mydb
+
+  frontend:
+    build: ./fe
+    user: vscode  # Run as non-root to avoid permission issues
+    labels:
+      - "traefik.http.routers.{{FEATURE_FOLDER}}.rule=Host(`{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
+```
+
+> **⚠️ Important: File Permissions**
+>
+> Always run containers as a non-root user (e.g., `user: vscode`) to avoid permission issues.
+> Files created by root-owned containers cannot be removed by `pan workspace destroy` without sudo.
+> The Microsoft devcontainers base image includes a `vscode` user (UID 1000) that matches most host users.
+
+### Required for HTTPS: Traefik Configuration
+
+If you want local HTTPS (recommended), provide a Traefik compose file:
+
+```
+your-project/
+├── infra/
+│   └── docker-compose.traefik.yml   # Traefik reverse proxy
+└── ...
+```
+
+Example Traefik config:
+```yaml
+# infra/docker-compose.traefik.yml
+services:
+  traefik:
+    image: traefik:v2.10
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ~/.panopticon/traefik/certs:/certs:ro
+    command:
+      - --providers.docker=true
+      - --entrypoints.web.address=:80
+      - --entrypoints.websecure.address=:443
+```
+
+### Required for Database Seeding: Seed Directory
+
+For projects with databases:
+
+```
+your-project/
+├── infra/
+│   └── seed/
+│       └── seed.sql              # Sanitized production data
+└── ...
+```
+
+Your compose template should mount this:
+```yaml
+services:
+  postgres:
+    image: postgres:16
+    volumes:
+      - /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro
+```
+
+### Optional: Agent Templates
+
+For customizing how agents work in your project:
+
+```
+your-project/
+├── infra/
+│   └── .agent-template/
+│       ├── CLAUDE.md.template    # Project-specific AI instructions
+│       └── .mcp.json.template    # MCP server configuration
+└── .claude/
+    └── skills/                   # Project-specific skills
+        └── my-project-standards/
+            └── SKILL.md
+```
+
+### Configuration in projects.yaml
+
+Point Panopticon to your templates:
+
+```yaml
+# ~/.panopticon/projects.yaml
+projects:
+  myproject:
+    name: "My Project"
+    path: /home/user/projects/myproject
+    linear_team: PRJ
+
+    workspace:
+      type: polyrepo  # or monorepo
+      workspaces_dir: workspaces
+
+      docker:
+        traefik: infra/docker-compose.traefik.yml
+        compose_template: infra/.devcontainer-template
+
+      database:
+        seed_file: /home/user/projects/myproject/infra/seed/seed.sql
+        container_name: "{{PROJECT}}-postgres-1"
+
+      agent:
+        template_dir: infra/.agent-template
+        templates:
+          - source: CLAUDE.md.template
+            target: CLAUDE.md
+```
+
+### Quick Checklist
+
+| Component | Required? | Location | Purpose |
+|-----------|-----------|----------|---------|
+| Docker Compose template | Yes (for Docker workspaces) | `infra/.devcontainer-template/` | Container configuration |
+| Traefik config | Only for HTTPS | `infra/docker-compose.traefik.yml` | Reverse proxy |
+| Seed file | Only if database needed | `infra/seed/seed.sql` | Pre-populate database |
+| Agent template | Recommended | `infra/.agent-template/` | AI instructions |
+| Project skills | Optional | `.claude/skills/` | Project-specific workflows |
+
+### Example: Minimal Setup
+
+For a simple monorepo with no Docker:
+
+```yaml
+# ~/.panopticon/projects.yaml
+projects:
+  simple-app:
+    name: "Simple App"
+    path: /home/user/projects/simple-app
+    linear_team: APP
+    # No workspace config needed - uses git worktrees
+```
+
+Panopticon creates workspaces as git worktrees. Docker, HTTPS, and seeding are opt-in.
+
+---
+
+## Polyrepo Workspace Configuration
+
+For projects with multiple git repositories (like separate frontend/backend repos), configure workspace settings directly in `projects.yaml`.
+
+### Recommended: Separate Infra Repository
+
+For polyrepo projects, we strongly recommend maintaining a **dedicated infrastructure repository** alongside your code repos:
+
+```
+myproject/
+├── infra/                    # Infrastructure repo (git)
+│   ├── .devcontainer-template/   # Templates for workspace creation
+│   │   ├── dev.template          # Dev script template
+│   │   ├── compose.infra.yml.template
+│   │   └── docker-compose.devcontainer.yml.template
+│   ├── new-feature              # Script to create workspaces
+│   ├── remove-feature           # Script to clean up workspaces
+│   ├── certs/                   # SSL certificates
+│   └── traefik/                 # Traefik config
+├── frontend/                 # Frontend repo (git)
+├── backend/                  # Backend repo (git)
+└── workspaces/               # Feature workspaces (git worktrees)
+    └── feature-xxx/
+        ├── fe/               # Worktree of frontend
+        ├── api/              # Worktree of backend
+        └── .devcontainer/    # Generated from templates
+```
+
+**Benefits of a separate infra repo:**
+
+1. **Version-controlled templates** - Dev script changes are tracked and shared
+2. **Centralized configuration** - DNS, ports, Traefik rules in one place
+3. **Workspace consistency** - All workspaces use the same templates
+4. **Team collaboration** - Infra changes go through normal PR review
+5. **Easy updates** - Fix a template once, regenerate affected workspaces
+
+**Key files in the infra repo:**
+
+| File | Purpose |
+|------|---------|
+| `dev.template` | Template for `./dev` script (container management) |
+| `new-feature` | Creates workspace with git worktrees + devcontainer |
+| `remove-feature` | Cleans up workspace and worktrees |
+| `.devcontainer-template/` | Docker Compose and devcontainer templates |
+
+
+
+```yaml
+projects:
+  myapp:
+    name: "My App"
+    path: /home/user/projects/myapp
+    linear_team: APP
+
+    workspace:
+      type: polyrepo
+      workspaces_dir: workspaces
+      # Default branch for all repos (optional, defaults to 'main')
+      default_branch: main
+
+      # Git repositories to include in each workspace
+      # Each repo is a SEPARATE git repository with its own .git
+      repos:
+        - name: fe
+          path: frontend           # Relative to project root
+          branch_prefix: "feature/"
+          # default_branch: main   # Can override workspace default per-repo
+        - name: api
+          path: backend
+          branch_prefix: "feature/"
+          # default_branch: develop  # Example: API uses 'develop' as default
+
+      # DNS entries for local development
+      dns:
+        domain: myapp.test
+        entries:
+          - "{{FEATURE_FOLDER}}.{{DOMAIN}}"
+          - "api-{{FEATURE_FOLDER}}.{{DOMAIN}}"
+        sync_method: wsl2hosts  # or: hosts_file, dnsmasq
+
+      # Port assignments for services
+      ports:
+        redis:
+          range: [6380, 6499]
+
+      # Service definitions - how to start each service
+      services:
+        - name: api
+          path: api
+          start_command: ./mvnw spring-boot:run
+          docker_command: ./mvnw spring-boot:run
+          health_url: "https://api-{{FEATURE_FOLDER}}.{{DOMAIN}}/actuator/health"
+          port: 8080
+        - name: frontend
+          path: fe
+          start_command: pnpm start
+          docker_command: pnpm start
+          health_url: "https://{{FEATURE_FOLDER}}.{{DOMAIN}}"
+          port: 3000
+
+      # Docker configuration
+      docker:
+        traefik: infra/docker-compose.traefik.yml
+        compose_template: infra/.devcontainer-template
+
+      # Agent configuration templates
+      agent:
+        template_dir: infra/.agent-template
+        templates:
+          - source: CLAUDE.md.template
+            target: CLAUDE.md
+        symlinks:
+          - .claude/commands
+          - .claude/skills
+
+      # Environment template
+      env:
+        template: |
+          COMPOSE_PROJECT_NAME={{COMPOSE_PROJECT}}
+          FRONTEND_URL=https://{{FEATURE_FOLDER}}.{{DOMAIN}}
+```
+
+**Template Placeholders:**
+
+| Placeholder | Example | Description |
+|------------|---------|-------------|
+| `{{FEATURE_NAME}}` | `min-123` | Normalized issue ID |
+| `{{FEATURE_FOLDER}}` | `feature-min-123` | Workspace folder name |
+| `{{BRANCH_NAME}}` | `feature/min-123` | Git branch name |
+| `{{COMPOSE_PROJECT}}` | `myapp-feature-min-123` | Docker Compose project |
+| `{{DOMAIN}}` | `myapp.test` | DNS domain |
+
+**Service Templates:**
+
+Panopticon provides built-in templates for common frameworks. Use these to avoid boilerplate:
+
+| Template | Start Command | Port |
+|----------|--------------|------|
+| `react` | `npm start` | 3000 |
+| `react-vite` | `npm run dev` | 5173 |
+| `react-pnpm` | `pnpm start` | 3000 |
+| `nextjs` | `npm run dev` | 3000 |
+| `spring-boot-maven` | `./mvnw spring-boot:run` | 8080 |
+| `spring-boot-gradle` | `./gradlew bootRun` | 8080 |
+| `express` | `npm start` | 3000 |
+| `fastapi` | `uvicorn main:app --reload` | 8000 |
+| `django` | `python manage.py runserver` | 8000 |
+
+Use a template by referencing it in your service config:
+
+```yaml
+services:
+  - name: api
+    template: spring-boot-maven
+    path: api
+    health_url: "https://api-{{FEATURE_FOLDER}}.myapp.test/health"
+```
+
+See `/pan-workspace-config` skill for complete documentation.
+
+### Polyrepo Merge Considerations
+
+> **⚠️ Important:** Polyrepo merging requires special handling. The current merge-agent is optimized for monorepos.
+
+For polyrepo projects:
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Workspace creation | ✅ Supported | Creates worktrees in each repo |
+| Branch management | ✅ Supported | Each repo gets its own feature branch |
+| Agent work | ✅ Supported | Agents can work across repos |
+| Merge | ⚠️ Manual | Push each repo's branch, merge via GitLab/GitHub |
+
+**Current workflow for polyrepo merges:**
+
+1. Agent completes work and pushes branches to each repo
+2. Create merge requests for each repo manually (or via `gh pr create`)
+3. Review and merge each MR separately
+4. The "Approve & Merge" button is not yet polyrepo-aware
+
+**Future enhancement:** Polyrepo-aware merge-agent that handles multiple repos automatically.
+
+### Managing Projects
+
+```bash
+# List registered projects
+pan project list
+
+# Add a project
+pan project add /path/to/project --name myproject --linear-team PRJ
+
+# Remove a project
+pan project remove myproject
+```
+
+### Database Seeding
+
+Many projects need a pre-populated database for development and testing. Panopticon provides database seeding commands that work with your existing infrastructure.
+
+**Problem:** Development databases often need:
+- Schema with 100+ migrations already applied
+- Seed data for testing (users, reference data)
+- External QA database connections
+- Database snapshots from staging/production (sanitized)
+
+**Solution:** Configure database seeding in `projects.yaml`:
+
+```yaml
+projects:
+  myapp:
+    workspace:
+      database:
+        # Path to seed file (loaded on first container start)
+        seed_file: /path/to/sanitized-seed.sql
+
+        # Command to create new snapshots from external source
+        snapshot_command: "kubectl exec -n prod pod/postgres -- pg_dump -U app mydb"
+
+        # Or connect to external database directly
+        external_db:
+          host: qa-db.example.com
+          database: myapp_qa
+          user: readonly
+          password_env: QA_DB_PASSWORD
+
+        # Container naming pattern
+        container_name: "{{PROJECT}}-postgres-1"
+
+        # Migration tool (for status checks)
+        migrations:
+          type: flyway  # flyway | liquibase | prisma | typeorm | custom
+          path: src/main/resources/db/migration
+```
+
+**Commands:**
+
+```bash
+# Create a snapshot from production/staging
+pan db snapshot --project myapp --output /path/to/seed.sql
+
+# Seed a workspace database
+pan db seed MIN-123
+
+# Check database status
+pan db status MIN-123
+
+# Clean kubectl noise from pg_dump files
+pan db clean /path/to/dump.sql
+
+# View database configuration
+pan db config myapp
+```
+
+**Workflow for capturing production data:**
+
+1. **Create snapshot** from production (via kubectl or direct connection):
+   ```bash
+   pan db snapshot --project myapp --sanitize
+   ```
+
+2. **Verify** the seed file:
+   ```bash
+   pan db clean /path/to/seed.sql --dry-run
+   ```
+
+3. **Update projects.yaml** with seed file path
+
+4. **Workspaces** automatically seed on first postgres container start
+
+**Container integration:**
+
+Your Docker Compose template should mount the seed directory:
+
+```yaml
+# compose.infra.yml
+services:
+  postgres:
+    image: postgres:16
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      # Seed database on first startup
+      - /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro
 ```
 
-### Label-Based Routing
+**Troubleshooting:**
 
-Issues are routed to different subdirectories based on their labels:
+| Issue | Solution |
+|-------|----------|
+| "relation does not exist" | Seed file missing or incomplete - run `pan db snapshot` |
+| Slow database startup | Large seed file - consider pruning old data |
+| kubectl garbage in dump | Run `pan db clean <file>` to remove stderr noise |
+| Migrations fail after seed | Check Flyway version matches seed file's schema_history |
 
-1. **Labeled issues** - Matched against `issue_routing` rules in order
-2. **Default route** - Issues without matching labels use the `default: true` path
-3. **Fallback** - If no default, uses the project root path
+### Agent Completion Notifications
 
-Example: An issue with label "splash" in the MIN team would create its workspace at `/home/user/projects/myn/splash/workspaces/feature-min-xxx/`.
+Panopticon includes a notification system that alerts you when agents complete their work.
 
-### Managing Projects
+**Desktop Notifications:**
+
+The `notify-complete` script sends desktop notifications across platforms:
 
+| Platform | Notification Method |
+|----------|---------------------|
+| WSL2/Windows | PowerShell toast notifications |
+| macOS | osascript display notification |
+| Linux | notify-send |
+
+**Usage:**
 ```bash
-# List registered projects
-pan project list
+# Send a completion notification
+~/.panopticon/bin/notify-complete MIN-123 "Fixed login button" "https://gitlab.com/mr/456"
+```
 
-# Add a project
-pan project add /path/to/project --name myproject --linear-team PRJ
+**Completion log:** All notifications are logged to `~/.panopticon/agent-completed.log` with timestamps.
 
-# Remove a project
-pan project remove myproject
+**Integration with agent workflows:**
+
+Agents can call `notify-complete` at the end of their work:
+```bash
+# In agent completion script or /work-complete skill
+notify-complete "$ISSUE_ID" "$SUMMARY" "$MR_URL"
 ```
 
 ---
@@ -670,8 +1521,71 @@ pan skills            # List available skills
 pan status            # Show running agents
 pan up                # Start dashboard (Docker or minimal)
 pan down              # Stop dashboard and services
+pan update            # Update Panopticon to latest version
+pan backup            # Create backup of ~/.panopticon/
+pan restore           # Restore from backup
+pan setup hooks       # Install Claude Code hooks (heartbeat, etc.)
+```
+
+### Beads Management
+
+Beads is an optional git-backed issue tracker for persistent task tracking. Panopticon includes commands to manage beads databases and automatic cleanup after merges.
+
+**Installation:** Beads is automatically installed during `pan install`. You can also install/upgrade manually:
+
+```bash
+# Check beads version and available updates
+pan beads upgrade --check
+
+# Upgrade to latest version
+pan beads upgrade
+
+# Show beads statistics (total, open, closed, old)
+pan beads stats
+
+# Compact beads - remove closed issues older than 30 days
+pan beads compact
+
+# Customize the threshold (e.g., 60 days)
+pan beads compact --days 60
+
+# Preview what would be removed (dry run)
+pan beads compact --dry-run
+```
+
+**Recommended version:** v0.47.1+ includes important fixes for git worktree isolation.
+
+**Workspace Isolation:**
+
+With beads v0.47.1+, workspaces share the same database but use labels for isolation:
+
+```bash
+# In workspace for PAN-83, list only that workspace's tasks
+bd list --label workspace:pan-83
+
+# Or use bd ready with label filter
+bd ready --label workspace:pan-83
 ```
 
+Panopticon automatically creates beads with `workspace:<issue-id>` labels when you create a workspace. Agents can filter to see only their workspace's tasks.
+
+**Automatic Compaction:**
+
+After every successful merge, the merge-agent automatically:
+1. Checks for closed beads older than 30 days
+2. If found, runs `bd admin compact --days 30`
+3. Commits the compacted beads
+4. Pushes to remote
+
+This keeps the beads database clean without manual intervention.
+
+**Why compact beads?**
+
+Beads are committed to git for collaborative planning (see "Git-Backed Collaborative Planning" section). Over time, closed issues accumulate. Compaction removes old closed issues while preserving:
+- Open issues (always kept)
+- Recently closed issues (< 30 days by default)
+- All issue history in git commits
+
 #### What `pan sync` Does
 
 `pan sync` synchronizes Panopticon assets to all supported AI tools:
@@ -694,13 +1608,199 @@ pan work issue MIN-123
 # List all running agents
 pan work status
 
-# Send a message to an agent
+# Send a message to an agent (handles Enter key automatically)
 pan work tell min-123 "Please also add tests"
 
 # Kill an agent
 pan work kill min-123
+
+# Show work completed and awaiting review
+pan work pending
+
+# Approve agent work, merge MR, update Linear
+pan work approve min-123
+
+# List issues from configured trackers
+pan work list
+
+# Triage issues from secondary tracker
+pan work triage
+
+# Reopen a closed issue and re-run planning
+pan work reopen min-123
+
+# Request re-review after fixing feedback (for agents, max 3 auto-requeues)
+pan work request-review min-123 -m "Fixed: added tests and removed duplication"
+
+# Deep wipe: completely reset all state for an issue
+pan work wipe min-123           # Cleans up agents, state, Linear status
+pan work wipe min-123 -w        # Also delete workspace
+pan work wipe min-123 -y -w     # Skip confirmation
+
+# Recover crashed agents
+pan work recover min-123
+pan work recover --all
+```
+
+### Convoys: Multi-Agent Orchestration
+
+Convoys enable Panopticon to run multiple AI agents in parallel for complex tasks like code review. Instead of a single agent doing everything, specialized agents focus on specific concerns and a synthesis agent combines their findings.
+
+**Why Convoys?**
+
+When reviewing code, a single AI agent must context-switch between:
+- Checking for logic errors
+- Looking for security vulnerabilities
+- Analyzing performance issues
+
+This leads to:
+- Shallow reviews (can't go deep on everything)
+- Missed issues (focus on one area, miss others)
+- Long sequential execution (can't parallelize)
+
+Convoys solve this by **specialization + parallelization**:
+- 3 focused agents review in parallel (10x faster)
+- Each agent goes deep in their domain
+- Synthesis agent combines findings with prioritization
+
+#### Built-in Convoy Templates
+
+| Template | Agents | Use Case |
+|----------|--------|----------|
+| `code-review` | correctness, security, performance, synthesis | Comprehensive code review |
+| `planning` | planner | Codebase exploration and planning |
+| `triage` | (dynamic) | Parallel issue triage |
+| `health-monitor` | monitor | Check health of running agents |
+
+#### Quick Start
+
+```bash
+# Run a parallel code review
+pan convoy start code-review --files "src/**/*.ts"
+
+# Check status
+pan convoy status
+
+# List all convoys (running and completed)
+pan convoy list
+
+# Stop a convoy
+pan convoy stop <convoy-id>
+```
+
+#### How Code Review Convoy Works
+
+```
+pan convoy start code-review --files "src/**/*.ts"
+    │
+    ├─→ Phase 1 (Parallel): 3 specialized reviewers run simultaneously
+    │     ├─→ Correctness (Haiku) → correctness.md
+    │     ├─→ Security (Sonnet)    → security.md
+    │     └─→ Performance (Haiku)  → performance.md
+    │
+    └─→ Phase 2 (Sequential): Synthesis agent runs after Phase 1 completes
+          └─→ Synthesis reads all 3 reviews → synthesis.md
+```
+
+**Phase 1 - Specialized Reviews (Parallel)**
+- **Correctness** (Haiku) - Logic errors, edge cases, type safety
+- **Security** (Sonnet) - OWASP Top 10, injection, XSS, auth issues
+- **Performance** (Haiku) - N+1 queries, blocking ops, memory leaks
+
+**Phase 2 - Synthesis (Sequential)**
+- Reads all three review files
+- Removes duplicates (same issue found by multiple reviewers)
+- Prioritizes findings (blocker → critical → high → medium → low)
+- Generates unified report with action items
+
+#### What is Synthesis?
+
+Synthesis is the process of combining findings from multiple parallel agents into a single, prioritized, actionable report.
+
+**Without synthesis**, after 3 parallel reviews you get:
+- 3 separate markdown files to read
+- Duplicate findings (same issue reported differently)
+- No prioritization (which to fix first?)
+- Mental overhead to merge them yourself
+
+**With synthesis**, you get:
+- Single unified report
+- Deduplicated findings
+- AI-prioritized by severity × impact
+- Clear action items
+
+**Example synthesis output:**
+
+```markdown
+# Code Review - Complete Analysis
+
+## Executive Summary
+- 2 blockers (MUST FIX)
+- 3 critical issues
+- 5 high-priority items
+
+## Top Priority
+1. SQL injection in auth.ts:42 (Security, Critical)
+2. execSync blocking event loop in sync.ts:89 (Performance, Blocker)
+3. Null pointer in user fetch in api.ts:156 (Correctness, High)
+
+## Blocker Issues
+[Detailed findings with code examples and fixes]
+
+## Critical Issues
+[...]
+
+## Review Statistics
+- Files reviewed: 12
+- Issues found: 10
+- Duplicates removed: 3
+```
+
+#### Convoy Commands
+
+```bash
+# Start a convoy
+pan convoy start <template> [options]
+  --files <pattern>       # File pattern (e.g., "src/**/*.ts")
+  --pr-url <url>          # Pull request URL
+  --issue-id <id>         # Issue ID
+  --project-path <path>   # Project path (defaults to cwd)
+
+# Check convoy status
+pan convoy status [convoy-id]  # Show status (defaults to most recent)
+
+# List convoys
+pan convoy list                # All convoys
+pan convoy list --status running  # Filter by status
+
+# Stop a convoy
+pan convoy stop <convoy-id>    # Kill all agents, mark failed
+```
+
+#### Custom Convoy Templates
+
+Create custom templates in `~/.panopticon/convoy-templates/`:
+
+```json
+{
+  "name": "lightweight-review",
+  "description": "Quick security-only review",
+  "agents": [
+    {
+      "role": "security",
+      "subagent": "code-review-security",
+      "parallel": false
+    }
+  ],
+  "config": {
+    "outputDir": ".claude/reviews",
+    "timeout": 600000
+  }
+}
 ```
 
+Then use with: `pan convoy start lightweight-review --files "src/**/*.ts"`
+
 ### Health Monitoring
 
 ```bash
@@ -714,6 +1814,63 @@ pan work health status
 pan work health daemon --interval 30
 ```
 
+### Test Runner
+
+```bash
+# Run all tests for a workspace
+pan test run min-123
+
+# Run tests for main branch
+pan test run main
+
+# Run specific test suites only
+pan test run min-123 --tests backend,frontend_unit
+
+# List configured tests for a project
+pan test list
+
+# List tests for specific project
+pan test list myproject
+```
+
+**Test Configuration:**
+
+Configure test suites in `projects.yaml`:
+
+```yaml
+projects:
+  myapp:
+    tests:
+      backend:
+        type: maven           # maven, vitest, jest, playwright, pytest, cargo
+        path: api             # Path relative to workspace
+        command: ./mvnw test  # Command to run
+
+      frontend_unit:
+        type: vitest
+        path: fe
+        command: pnpm test:unit --run
+        container: true       # Run inside Docker container
+        container_name: "{{COMPOSE_PROJECT}}-fe-1"
+
+      frontend_e2e:
+        type: playwright
+        path: fe
+        command: pnpm test:e2e
+        env:
+          BASE_URL: "https://{{FEATURE_FOLDER}}.myapp.test"
+```
+
+**Reports:**
+
+Test results are saved to `{project}/reports/test-run-{target}-{timestamp}.md` with detailed logs for each suite.
+
+**Notifications:**
+
+Desktop notifications are sent when tests complete (disable with `--no-notify`).
+
+See `/pan-test-config` skill for complete documentation.
+
 ### FPP Hooks (Fixed Point Principle)
 
 ```bash
@@ -737,6 +1894,67 @@ pan work hook mail agent-min-123 "Review feedback received"
 
 This allows multiple agents to work on different features simultaneously without conflicts.
 
+> **IMPORTANT: Main Project Branch Convention**
+>
+> The main project directory should **ALWAYS** stay on the `main` branch. All feature work happens in workspaces (git worktrees), never in the main project.
+>
+> - **Main project**: Always on `main` - serves as the stable reference point
+> - **Workspaces**: Each has its own feature branch checked out
+> - **Want to check something?** Create a worktree, don't checkout in main
+> - **Quick test?** Create a worktree
+> - **Emergency hotfix?** Create a worktree
+>
+> This convention ensures:
+> 1. Specialists (review-agent, test-agent) always find the correct code
+> 2. Merge operations have a clean target
+> 3. Multiple agents don't interfere with each other
+>
+> If you see a warning like "Main project is on branch 'feature/xxx' instead of 'main'", something has incorrectly checked out a feature branch in the main project. Fix it with `git checkout main`.
+
+#### Git Hooks for Branch Protection
+
+Panopticon provides git hooks to enforce the main branch convention. These hooks are automatically installed:
+
+- **On `pan project add`** - Hooks are installed when registering a new project
+- **On `pan sync`** - Hooks are updated in all registered projects
+
+The hooks are polyrepo-aware and will install in all git repositories within your project.
+
+**Auto-revert behavior:**
+- **Agents & planning sessions**: Automatically revert to `main` if they accidentally checkout a feature branch
+- **Human users**: Display a prominent warning (no auto-revert by default)
+
+To enable auto-revert for humans:
+```bash
+export PANOPTICON_AUTO_REVERT_CHECKOUT=1  # Add to .bashrc/.zshrc
+```
+
+Manual hook installation (for projects not in registry):
+```bash
+./scripts/install-git-hooks.sh /path/to/your/project
+```
+
+#### Planning vs Work Agent Safeguard
+
+The dashboard prevents starting a work agent (`agent-<issue>`) while a planning agent (`planning-<issue>`) is still running for the same issue. This prevents conflicts where both agents try to modify the same workspace.
+
+If you see "Planning agent is still running" when trying to start work:
+1. **Complete the planning session** - Use "Complete Planning" button
+2. **Or abort planning** - Use "Abort Planning" if you want to discard
+3. **Or kill the session manually** - `tmux kill-session -t planning-<issue>`
+
+#### Specialist Agent Safeguards
+
+All specialist agents (review-agent, test-agent, merge-agent) are configured to:
+1. **Run in workspaces only** - Never in the main project directory
+2. **Never checkout branches** - They work with the branch already in the workspace
+3. **Create workspaces if needed** - Use `pan workspace create <ISSUE-ID>` instead of `git checkout`
+
+These safeguards are enforced through:
+- **Prompt instructions** - Clear warnings in all specialist prompts
+- **Code enforcement** - Specialists spawn with workspace as cwd
+- **Git hooks** - Auto-revert if checkout detected in tmux sessions
+
 #### Git-Backed Collaborative Planning
 
 | Start Planning | Codebase Exploration | Discovery Questions |
@@ -744,15 +1962,24 @@ This allows multiple agents to work on different features simultaneously without
 | ![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:
+Planning artifacts are stored **inside the workspace**:
+
+> ⚠️ **Note: `.planning/` is currently ephemeral (not tracked in git)**
+>
+> The `.planning/` directory is listed in `.gitignore` to prevent cross-contamination between issues. When branches merge, planning state from issue A could contaminate issue B's workspace, causing agents to work on the wrong tasks.
+>
+> **Current behavior:** Planning state is local to your machine only. If you switch machines, you'll need to re-run the planning session.
+>
+> See [#111](https://github.com/eltmon/panopticon-cli/issues/111) for the future enhancement to support cross-machine planning sync safely.
 
 ```
 workspaces/feature-min-123/
-├── .planning/
-│   ├── output.jsonl          # Full conversation history (tool uses + results)
-│   ├── PLANNING_PROMPT.md    # Initial planning prompt
+├── .planning/                 # ⚠️ NOT tracked in git (ephemeral)
+│   ├── STATE.md               # Current planning state
+│   ├── output.jsonl           # Full conversation history
+│   ├── PLANNING_PROMPT.md     # Initial planning prompt
 │   ├── CONTINUATION_PROMPT.md # Context for continued sessions
-│   └── output-*.jsonl        # Backup of previous rounds
+│   └── output-*.jsonl         # Backup of previous rounds
 └── ... (code)
 ```
 
@@ -763,47 +1990,24 @@ When the planning session completes, the AI generates:
 - **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 |
+**Future capabilities (currently disabled - see note above):**
 
-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
+1. ~~**Collaborative async planning** - Push your branch, someone else pulls and continues the planning session with full context~~
+2. ~~**Branch portability** - The planning state travels with the feature branch~~
 
-**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
+**What still works:**
 
-# Person B continues
-git pull origin feature/min-123
-pan work plan MIN-123 --continue
-# Claude has full context from Person A's session
-```
+1. **Context recovery** - If Claude's context compacts, STATE.md and beads preserve the planning decisions
+2. **Audit trail** - See decisions made in STATE.md
+3. **Beads tasks** - Sub-tasks created during planning ARE persisted (beads uses label-based isolation)
 
 ```bash
 # Create a workspace (git worktree) without starting an agent
 pan workspace create MIN-123
 
+# Create workspace and start Docker containers
+pan workspace create MIN-123 --docker
+
 # List all workspaces
 pan workspace list
 
@@ -814,6 +2018,69 @@ pan workspace destroy MIN-123
 pan workspace destroy MIN-123 --force
 ```
 
+#### Docker Integration
+
+The `--docker` flag automatically starts containers after workspace creation:
+
+```bash
+pan workspace create MIN-123 --docker
+```
+
+**What it does:**
+1. Creates the workspace (git worktree or custom command)
+2. Looks for docker-compose files in:
+   - `{workspace}/docker-compose.yml`
+   - `{workspace}/docker-compose.yaml`
+   - `{workspace}/.devcontainer/docker-compose.yml`
+   - `{workspace}/.devcontainer/docker-compose.devcontainer.yml`
+   - `{workspace}/.devcontainer/compose.yml`
+3. Runs `docker compose -p "{project}-feature-{issue}" -f {file} up -d --build`
+
+**Docker Project Naming:**
+
+Each workspace gets a unique Docker Compose project name to avoid container conflicts:
+- Format: `{project-name}-feature-{issue-id}` (e.g., `mind-your-now-feature-min-123`)
+- The project name comes from `name` in your `~/.panopticon/projects.yaml`
+- Container names follow: `{project}-{service}-1` (e.g., `mind-your-now-feature-min-123-api-1`)
+
+This allows multiple workspaces to run simultaneously without port or name conflicts.
+
+**Why this matters:**
+- Containers start warming up while you review the issue
+- Environment is ready when the planning agent starts asking questions
+- You can test assumptions during planning without waiting for builds
+
+**Dashboard integration:**
+
+The planning dialog includes a "Start Docker containers" checkbox:
+- **Default:** Enabled (containers start automatically)
+- **Preference saved:** Your choice is remembered in browser localStorage
+- **Key:** `panopticon.planning.startDocker`
+
+To change the default via browser console:
+```javascript
+// Disable Docker by default
+localStorage.setItem('panopticon.planning.startDocker', 'false');
+
+// Enable Docker by default (this is the out-of-box default)
+localStorage.setItem('panopticon.planning.startDocker', 'true');
+```
+
+**Example workflow:**
+```bash
+# From dashboard: click "Start Planning" (Docker enabled by default)
+# Or from CLI:
+pan workspace create MIN-123 --docker
+
+# While containers build in background:
+# - Review the Linear issue
+# - Check related PRs
+# - Think about approach
+
+# By the time you're ready to engage with the planning agent,
+# the dev environment is warm and ready for testing
+```
+
 ### Project Management
 
 ```bash
@@ -823,6 +2090,12 @@ pan project add /path/to/project --name myproject
 # List managed projects
 pan project list
 
+# Show project details
+pan project show myproject
+
+# Initialize project config (creates .panopticon.json)
+pan project init
+
 # Remove a project
 pan project remove myproject
 ```
@@ -869,20 +2142,29 @@ pan cloister start
 # Stop Cloister
 pan cloister stop
 
+# Emergency stop all agents (force kill)
+pan cloister emergency-stop
+
 # Check Cloister status
 pan cloister status
 
 # List all specialists
 pan specialists list
 
-# Wake a specific specialist
-pan specialists wake merge-agent --issue MIN-123
+# Wake a specialist (resumes previous session if exists)
+pan specialists wake merge-agent
+
+# Wake and send a task
+pan specialists wake merge-agent --task "Review PR #123 for security issues"
 
 # View specialist queue
-pan specialists queue
+pan specialists queue merge-agent
 
-# Reset specialist state
+# Reset a single specialist (wipes context)
 pan specialists reset merge-agent
+
+# Reset ALL specialists (fresh start)
+pan specialists reset --all
 ```
 
 ## Dashboard
@@ -920,6 +2202,16 @@ Stop with `pan down`.
 | **Skills** | Available skills and their descriptions |
 | **Health** | System health checks and diagnostics |
 
+### Issue Filtering
+
+The dashboard automatically filters issues to reduce visual clutter:
+
+- **Linear issues** - Shows current cycle issues only
+- **Done column** - Shows items completed in the last 24 hours
+- **Canceled column** - Shows items canceled in the last 24 hours
+
+This filtering applies to both Linear and GitHub issues. Older completed items are excluded from the dashboard but remain in your issue tracker.
+
 ### Issue Cards
 
 Issue cards on the Kanban board display:
@@ -1034,6 +2326,8 @@ Panopticon ships with 25+ skills organized into categories:
 | `pan-convoy-synthesis` | Synthesize convoy coordination |
 | `pan-subagent-creator` | Create specialized subagents |
 | `pan-skill-creator` | Create new skills (guided) |
+| `pan-workspace-config` | Configure polyrepo workspaces, DNS, ports |
+| `pan-test-config` | Configure project test suites |
 
 ### Utilities
 
@@ -1298,6 +2592,26 @@ Each agent's state is tracked in `~/.panopticon/agents/{agent-id}/state.json`:
 
 **State Cleanup:** When an agent is killed or aborted (`pan work kill`), Panopticon automatically cleans up its state files to prevent stale data from affecting future runs.
 
+### Deep Wipe
+
+For issues that get into a stuck or inconsistent state, use `pan work wipe` to completely reset:
+
+```bash
+pan work wipe MIN-123           # Basic cleanup
+pan work wipe MIN-123 -w        # Also delete workspace
+pan work wipe MIN-123 -y -w     # Skip confirmation
+```
+
+**Deep wipe cleans up:**
+- Tmux sessions (`planning-min-123`, `agent-min-123`)
+- Agent state directories (`~/.panopticon/agents/planning-*`, `agent-*`)
+- Legacy planning directories (`project/.planning/min-123/`)
+- Workspace (if `-w` flag is used)
+- Linear issue status (reset to Backlog)
+- Linear labels (removes "Review Ready", "Planning")
+
+**Dashboard UI:** When aborting planning, click "🔥 Deep Wipe" for a complete reset.
+
 ## Health Monitoring (Deacon Pattern)
 
 Panopticon implements the Deacon pattern for stuck agent detection:
@@ -1390,8 +2704,183 @@ If you're both developing Panopticon AND using it for your own projects:
 3. **Config is shared** - workspaces/agents work the same either way
 4. **Test in a real project** - your own usage is the best test
 
+### Developer Skills (dev-skills/)
+
+Panopticon has two types of skills:
+
+| Directory | Purpose | Synced When |
+|-----------|---------|-------------|
+| `skills/` | User-facing skills for all Panopticon users | Always via `pan sync` |
+| `dev-skills/` | Developer-only skills for Panopticon contributors | Only in dev mode |
+
+**Dev mode is automatically detected** when running from the Panopticon source repo (npm link). Skills in `dev-skills/` are:
+- Checked into the repo and version-controlled
+- Only synced to developers' machines, not end users
+- Shown with `[dev]` label in `pan sync --dry-run`
+
+```bash
+# Check what will be synced (including dev-skills)
+pan sync --dry-run
+
+# Output shows:
+# Developer mode detected - dev-skills will be synced
+# ...
+#   + skill/test-specialist-workflow [dev]
+```
+
+### Testing the Specialist System
+
+The `test-specialist-workflow` skill provides end-to-end testing for the specialist handoff pipeline.
+
+**Location:** `dev-skills/test-specialist-workflow/SKILL.md`
+
+**What it tests:**
+- Full approve workflow: review-agent → test-agent → merge-agent
+- Specialist handoffs via `pan specialists wake --task`
+- Merge completion and branch preservation
+
+**Usage:**
+
+```bash
+# First sync to get dev-skills
+pan sync
+
+# In Claude Code, invoke the skill
+/test-specialist-workflow
+```
+
+The skill guides you through:
+
+1. **Prerequisites check** - Dashboard running, specialists available
+2. **Create test issue** - GitHub issue for tracking
+3. **Create workspace** - Git worktree for the test
+4. **Make test change** - Trivial commit to verify merge
+5. **Trigger approve** - Kicks off the specialist pipeline
+6. **Monitor handoffs** - Watch each specialist complete and hand off
+7. **Verify merge** - Confirm change reached main branch
+8. **Cleanup** - Close issue, remove workspace
+
+**Expected timeline:** 2-4 minutes total
+
+**When to use:**
+- After making changes to the specialist system
+- After modifying the approve workflow
+- As a smoke test before releases
+
 ## Troubleshooting
 
+### WSL2 Stability Issues (Windows Users)
+
+WSL2 can experience crashes and networking issues, especially under heavy AI agent workloads. Here are recommended `.wslconfig` settings to improve stability.
+
+**Create/edit `C:\Users\<username>\.wslconfig`:**
+
+```ini
+[wsl2]
+# Resource allocation (adjust based on your system)
+memory=40GB
+processors=18
+swap=8GB
+
+# Localhost forwarding between Windows and WSL
+localhostForwarding=true
+
+# Disable GPU/GUI passthrough - reduces dxg driver errors
+guiApplications=false
+
+# ============================================================
+# WINDOWS 11 ONLY - Comment these out on Windows 10!
+# These settings require Windows 11 22H2 or later.
+# On Windows 10 they are silently ignored or may cause issues.
+# ============================================================
+
+# Route DNS through Windows - prevents getaddrinfo() failures
+# dnsTunneling=true          # Windows 11 only
+
+# Inherit Windows proxy settings
+# autoProxy=true             # Windows 11 only
+
+# Aggressively reclaim cached memory
+# autoMemoryReclaim=dropCache  # Windows 11 only
+
+# Use sparse VHD to allow better memory compaction
+# sparseVhd=true             # Windows 11 only
+
+# Mirrored networking (may conflict with Docker Desktop)
+# networkingMode=mirrored    # Windows 11 only
+```
+
+**After changing `.wslconfig`:**
+```powershell
+wsl --shutdown
+# Then relaunch your WSL terminal
+```
+
+**Verify settings applied:**
+```bash
+# Check resources
+free -h          # Should show configured memory
+nproc            # Should show configured processors
+swapon --show    # Should show configured swap
+
+# Check networking mode (Windows 11 only)
+ip addr show eth0  # NAT mode shows 172.x.x.x IP
+                   # Mirrored mode shares Windows network directly
+```
+
+#### Windows 10 Limitations
+
+| Feature | Windows 10 | Windows 11 22H2+ |
+|---------|-----------|------------------|
+| `memory`, `processors`, `swap` | ✅ Works | ✅ Works |
+| `localhostForwarding` | ✅ Works | ✅ Works |
+| `guiApplications=false` | ✅ Works | ✅ Works |
+| `networkingMode=mirrored` | ❌ Not supported | ✅ Supported |
+| `dnsTunneling=true` | ❌ Not supported | ✅ Supported |
+| `autoProxy=true` | ❌ Not supported | ✅ Supported |
+| `autoMemoryReclaim` | ❌ Not supported | ✅ Supported |
+| `sparseVhd=true` | ❌ Not supported | ✅ Supported |
+
+**Windows 10 users:** Most advanced WSL2 features require Windows 11. On Windows 10, only the basic resource limits and `localhostForwarding`/`guiApplications` settings are supported. Other settings will be silently ignored or may cause instability.
+
+If you experience frequent WSL2 crashes on Windows 10, consider:
+- Using only the basic settings shown above (memory, processors, swap, localhostForwarding, guiApplications)
+- Reducing `memory` allocation if system is under pressure
+- Upgrading to Windows 11 for full WSL2 feature support
+- Checking Windows Event Viewer for specific crash causes
+
+#### Additional Windows 10 Workarounds
+
+If NAT networking is unstable on Windows 10:
+
+```powershell
+# 1. Update WSL to latest version
+wsl --update
+
+# 2. Check for VPN/firewall conflicts
+# Disable VPN temporarily to test if it's causing issues
+
+# 3. Reset Windows network stack (run as Admin)
+netsh winsock reset
+netsh int ip reset
+
+# 4. Restart after network reset
+Restart-Computer
+```
+
+**Common conflict sources:**
+- VPN clients (especially corporate VPNs)
+- Docker Desktop (can conflict with WSL networking)
+- Third-party firewalls
+- Hyper-V virtual switch issues
+
+**If NAT fails completely**, WSL 2.3.25+ automatically falls back to VirtioProxy mode. This is less performant but more stable. You'll see: `"Failed to configure network (networkingMode Nat), falling back to networkingMode VirtioProxy."`
+
+**References:**
+- [Microsoft WSL Networking Documentation](https://learn.microsoft.com/en-us/windows/wsl/networking)
+- [WSL GitHub Issues - Networking](https://github.com/microsoft/WSL/issues?q=networking+mirrored)
+- [WSL NAT Fallback Issue #12297](https://github.com/microsoft/WSL/issues/12297)
+
 ### 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.