panopticon-cli 0.1.6 → 0.3.0

package/README.md

@@ -19,12 +19,142 @@ Panopticon is a unified orchestration layer for AI coding assistants. It works w
 ### 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
-- **GUPP Hooks** - Self-propelling agents that auto-resume work
+- **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
+
+> **"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
@@ -107,8 +237,22 @@ Create `~/.panopticon.env`:
 ```bash
 LINEAR_API_KEY=lin_api_xxxxx
 GITHUB_TOKEN=ghp_xxxxx  # Optional: for GitHub-tracked projects
+RALLY_API_KEY=_xxxxx    # Optional: for Rally as secondary tracker
 ```
 
+### Issue Trackers
+
+Panopticon supports multiple issue trackers:
+
+| Tracker | Role | Configuration |
+|---------|------|---------------|
+| **Linear** | Primary tracker | `LINEAR_API_KEY` in `.panopticon.env` |
+| **GitHub Issues** | Secondary tracker | `GITHUB_TOKEN` or `gh auth login` |
+| **GitLab Issues** | Secondary tracker | `glab auth login` |
+| **Rally** | Secondary tracker | `RALLY_API_KEY` in `.panopticon.env` |
+
+Secondary trackers sync issues to the dashboard alongside Linear issues, allowing unified project management.
+
 ### Register Projects
 
 Register your local project directories so Panopticon knows where to create workspaces:
@@ -144,18 +288,184 @@ 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.
 
+## Cloister: AI Lifecycle Manager
+
+Cloister is Panopticon's intelligent agent lifecycle manager. It monitors all running agents and automatically handles:
+
+- **Model Routing** - Routes tasks to appropriate models based on complexity
+- **Stuck Detection** - Identifies agents that have stopped making progress
+- **Automatic Handoffs** - Escalates to specialists when needed
+- **Specialist Coordination** - Manages test-agent, review-agent, and merge-agent
+
+### How Cloister Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CLOISTER SERVICE                         │
+│                                                              │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
+│  │  Heartbeat  │───▶│   Trigger   │───▶│   Handoff   │     │
+│  │   Monitor   │    │   Detector  │    │   Manager   │     │
+│  └─────────────┘    └─────────────┘    └─────────────┘     │
+│         │                  │                  │             │
+│         ▼                  ▼                  ▼             │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
+│  │   Agent     │    │  Complexity │    │ Specialists │     │
+│  │   Health    │    │   Analysis  │    │             │     │
+│  └─────────────┘    └─────────────┘    └─────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Starting Cloister
+
+```bash
+# Via dashboard - click "Start" in the Cloister status bar
+# Or via CLI:
+pan cloister start
+
+# Check status
+pan cloister status
+
+# Stop monitoring
+pan cloister stop
+```
+
+### Specialists
+
+Cloister manages specialized agents that handle specific phases of the development lifecycle:
+
+| Specialist | Purpose | Trigger |
+|------------|---------|---------|
+| **test-agent** | Runs test suite after implementation | `implementation_complete` signal |
+| **review-agent** | Code review before merge | After tests pass (manual trigger) |
+| **merge-agent** | Handles git merge and conflict resolution | "Approve & Merge" button |
+
+### Automatic Handoffs
+
+Cloister detects situations that require intervention:
+
+| Trigger | Condition | Action |
+|---------|-----------|--------|
+| **stuck_escalation** | No activity for 30+ minutes | Escalate to more capable model |
+| **complexity_upgrade** | Task complexity exceeds model capability | Route to Opus |
+| **implementation_complete** | Agent signals work is done | Wake test-agent |
+| **merge_requested** | User clicks "Approve & Merge" | Wake merge-agent |
+
+### Heartbeat Monitoring
+
+Agents send heartbeats via Claude Code hooks. Cloister tracks:
+
+- Last tool use and timestamp
+- Current task being worked on
+- Git branch and workspace
+- Process health
+
+Heartbeat files are stored in `~/.panopticon/heartbeats/`:
+
+```json
+{
+  "timestamp": "2024-01-22T10:30:00-08:00",
+  "agent_id": "agent-min-123",
+  "tool_name": "Edit",
+  "last_action": "{\"file_path\":\"/path/to/file.ts\"...}",
+  "git_branch": "feature/min-123",
+  "workspace": "/home/user/projects/myapp/workspaces/feature-min-123"
+}
+```
+
+### Configuration
+
+Cloister configuration lives in `~/.panopticon/cloister/config.json`:
+
+```json
+{
+  "monitoring": {
+    "heartbeat_interval_ms": 5000,
+    "stuck_threshold_minutes": 30,
+    "health_check_interval_ms": 30000
+  },
+  "specialists": {
+    "test_agent": { "enabled": true, "auto_wake": true },
+    "review_agent": { "enabled": true, "auto_wake": false },
+    "merge_agent": { "enabled": true, "auto_wake": false }
+  },
+  "triggers": {
+    "stuck_escalation": { "enabled": true },
+    "complexity_upgrade": { "enabled": true }
+  }
+}
+```
+
+---
+
+## Multi-Project Support
+
+Panopticon supports managing multiple projects with intelligent issue routing.
+
+### Project Registry
+
+Projects are registered in `~/.panopticon/projects.yaml`:
+
+```yaml
+projects:
+  myn:
+    name: "Mind Your Now"
+    path: /home/user/projects/myn
+    linear_team: MIN
+    issue_routing:
+      - labels: [splash, landing-pages, seo]
+        path: /home/user/projects/myn/splash
+      - labels: [docs, marketing]
+        path: /home/user/projects/myn/docs
+      - default: true
+        path: /home/user/projects/myn
+
+  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/`.
+
+### 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
+```
+
+---
+
 ## Commands
 
 ### Core Commands
 
 ```bash
 pan init              # Initialize ~/.panopticon/
-pan sync              # Sync skills to all AI tools
+pan sync              # Sync skills, commands, agents, AND hooks to all AI tools
+pan sync --dry-run    # Preview what will be synced
 pan doctor            # Check system health
 pan skills            # List available skills
 pan status            # Show running agents
 ```
 
+> **Note:** `pan sync` now automatically syncs heartbeat hooks to `~/.panopticon/bin/`. This happens automatically on `npm install/upgrade` as well.
+
 ### Agent Management
 
 ```bash
@@ -210,6 +520,11 @@ This allows multiple agents to work on different features simultaneously without
 
 #### 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:
 
 ```
@@ -222,6 +537,13 @@ workspaces/feature-min-123/
 └── ... (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
@@ -319,8 +641,35 @@ pan work recover min-123
 pan work recover --all
 ```
 
+### Cloister Commands
+
+```bash
+# Start Cloister monitoring service
+pan cloister start
+
+# Stop Cloister
+pan cloister 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
+
+# View specialist queue
+pan specialists queue
+
+# Reset specialist state
+pan specialists reset merge-agent
+```
+
 ## Dashboard
 
+![Panopticon Dashboard](docs/dashboard-overview.png)
+
 Start the monitoring dashboard:
 
 ```bash
@@ -337,36 +686,239 @@ This runs everything in Docker containers, avoiding port conflicts with your oth
 ```bash
 pan up --minimal
 ```
-- Dashboard: http://localhost:3001
+- 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 |
+
+### Issue Cards
+
+Issue cards on the Kanban board display:
+
+- **Cost badges** - Color-coded by amount ($0-5 green, $5-20 yellow, $20+ red)
+- **Container status** - Shows if workspace has Docker containers (running/stopped)
+- **Agent status** - Indicates if an agent is currently working on the issue
+- **Workspace status** - Shows if workspace exists, is corrupted, or needs creation
+
+### Workspace Actions
+
+Click an issue card to open the workspace detail panel:
+
+| Button | Action |
+|--------|--------|
+| **Create Workspace** | Creates git worktree for the issue |
+| **Containerize** | Adds Docker containers to an existing workspace |
+| **Start Containers** | Starts stopped Docker containers |
+| **Start Planning** | Opens interactive planning session with AI |
+| **Start Agent** | Spawns autonomous agent in tmux |
+| **Approve & Merge** | Triggers merge-agent to handle PR merge |
+
+### Interactive Planning
+
+The planning dialog provides a real-time terminal for collaborative planning:
+
+- **Discovery questions** - AI asks clarifying questions before implementation
+- **Codebase exploration** - AI reads files and understands patterns
+- **Pull/Push buttons** - Git operations to share planning context with teammates
+- **AskUserQuestion rendering** - Questions from the AI appear as interactive prompts
+
+### 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 |
 
-### Reserved Skill Names
+### 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-*)
 
-Panopticon reserves the following skill names. **Do not use these names for project-specific skills** to avoid conflicts:
+| 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-restart` | Safely restart Panopticon dashboard and services |
+| `pan-code-review` | Orchestrate parallel code review (3 reviewers + synthesis) |
+| `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 |
+
+## Subagents
+
+Panopticon includes specialized subagent templates for common development tasks. Subagents are invoked via the Task tool or convoy orchestration for parallel execution.
+
+### Code Review Subagents
+
+| Subagent | Model | Focus | Output |
+|----------|-------|-------|--------|
+| `code-review-correctness` | haiku | Logic errors, edge cases, type safety | `.claude/reviews/<timestamp>-correctness.md` |
+| `code-review-security` | sonnet | OWASP Top 10, vulnerabilities | `.claude/reviews/<timestamp>-security.md` |
+| `code-review-performance` | haiku | Algorithms, N+1 queries, memory | `.claude/reviews/<timestamp>-performance.md` |
+| `code-review-synthesis` | sonnet | Combines all findings into unified report | `.claude/reviews/<timestamp>-synthesis.md` |
+
+**Usage Example:**
+```bash
+/pan-code-review --files "src/auth/*.ts"
+```
 
-**Pan operations:**
-`pan-down`, `pan-help`, `pan-install`, `pan-issue`, `pan-plan`, `pan-quickstart`, `pan-setup`, `pan-status`, `pan-up`
+This spawns all three reviewers in parallel, then synthesizes their findings into a prioritized report.
+
+### Planning & Exploration Subagents
+
+| Subagent | Model | Focus | Permission Mode |
+|----------|-------|-------|-----------------|
+| `planning-agent` | sonnet | Codebase research, execution planning | `plan` (read-only) |
+| `codebase-explorer` | haiku | Fast architecture discovery, pattern finding | `plan` (read-only) |
+| `triage-agent` | haiku | Issue categorization, complexity estimation | default |
+| `health-monitor` | haiku | Agent stuck detection, log analysis | default |
+
+**Usage Examples:**
+```bash
+# Explore codebase architecture
+Task(subagent_type='codebase-explorer', prompt='Map out the authentication system')
+
+# Triage an issue
+Task(subagent_type='triage-agent', prompt='Categorize and estimate ISSUE-123')
+
+# Check agent health
+Task(subagent_type='health-monitor', prompt='Check status of all running agents')
+```
+
+### Parallel Code Review Workflow
+
+The `/pan-code-review` skill orchestrates a comprehensive parallel review:
+
+```
+1. Determine scope (git diff, files, or branch)
+2. Spawn 3 parallel reviewers:
+   ├─→ correctness (logic, types)
+   ├─→ security (vulnerabilities)
+   └─→ performance (bottlenecks)
+3. Each writes findings to .claude/reviews/
+4. Spawn synthesis agent
+5. Synthesis combines all findings
+6. Present unified, prioritized report
+```
+
+**Benefits:**
+- **3x faster** than sequential reviews
+- **Comprehensive coverage** across all dimensions
+- **Prioritized findings** (blocker > critical > high > medium > low)
+- **Actionable recommendations** with code examples
+
+**Review Output:**
+```markdown
+# Code Review - Complete Analysis
+
+## Executive Summary
+**Overall Assessment:** Needs Major Revisions
+**Key Findings:**
+- 1 blocker (SQL injection)
+- 4 critical issues
+- 6 high-priority items
+
+## Blocker Issues
+### 1. [Security] SQL Injection in login endpoint
+...
+
+## Critical Issues
+...
+```
+
+### Creating Custom Subagents
+
+Use the `/pan-subagent-creator` skill to create project-specific subagents:
+
+```bash
+/pan-subagent-creator
+```
+
+Subagent templates live in `~/.panopticon/agents/` and sync to `~/.claude/agents/`.
+
+### Reserved Skill Names
 
-**Workflow skills:**
-`beads`, `bug-fix`, `code-review`, `code-review-performance`, `code-review-security`, `dependency-update`, `feature-work`, `incident-response`, `onboard-codebase`, `refactor`, `release`, `session-health`, `skill-creator`, `web-design-guidelines`, `work-complete`
+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.
 
@@ -458,17 +1010,39 @@ This ensures every Panopticon-managed project has a well-defined canonical PRD t
 
 ```
 ~/.panopticon/
-  skills/             # Shared skills (SKILL.md format)
-  commands/           # Slash commands
-  agents/             # Per-agent state
+  config.toml           # Main configuration
+  projects.yaml         # Multi-project registry with issue routing
+  project-mappings.json # Linear project → local path mappings (legacy)
+  session-map.json      # Claude sessions → issue linking
+  runtime-metrics.json  # Runtime performance metrics
+
+  skills/               # Shared skills (SKILL.md format)
+  commands/             # Slash commands
+  agents/               # Subagent templates (.md files)
+  bin/                  # Hook scripts (synced via pan sync)
+    heartbeat-hook      # Real-time activity monitoring hook
+
+  agents/               # Per-agent runtime 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 (model, phase, complexity)
+      health.json       # Health status
+      hook.json         # GUPP work queue
+      cv.json           # Work history
+      mail/             # Incoming messages
+
+  cloister/             # Cloister AI lifecycle manager
+    config.json         # Cloister settings
+    state.json          # Running state
+    events.jsonl        # Handoff event log
+
+  heartbeats/           # Real-time agent activity
+    agent-min-123.json  # Last heartbeat from agent
+
+  costs/                # Raw cost logs (JSONL)
+  backups/              # Sync backups
+  traefik/              # Traefik reverse proxy config
+    dynamic/            # Dynamic route configs
+    certs/              # TLS certificates
 ```
 
 ## Health Monitoring (Deacon Pattern)