@miller-tech/uap 1.20.32 → 1.20.34

package/docs/architecture/SYSTEM_ANALYSIS.md

@@ -1,561 +1,79 @@
-# Universal Agent Memory (UAP) - Complete Feature Analysis
+# UAP - Universal Agent Protocol
 
-> Comprehensive analysis of UAP functionality, architecture, and implications on AI agent performance. UAP provides persistent memory, multi-agent coordination, intelligent worktree management, and automated context generation for AI coding assistants.
-
-## Table of Contents
-
-1. [Executive Summary](#executive-summary)
-2. [System Architecture](#system-architecture)
-3. [CLI Command Reference](#cli-command-reference)
-4. [Memory System](#memory-system)
-5. [Multi-Agent Coordination](#multi-agent-coordination)
-6. [Task Management System](#task-management-system)
-7. [Worktree Workflow](#worktree-workflow)
-8. [CLAUDE.md Generation](#claudemd-generation)
-9. [Deploy Batching](#deploy-batching)
-10. [Agent Performance Implications](#agent-performance-implications)
-11. [Integration Patterns](#integration-patterns)
-
----
-
-## Executive Summary
-
-UAP (Universal Agent Memory) is a comprehensive system designed to enhance AI agent capabilities through:
-
-| Capability                   | Impact on Agent Performance                     |
-| ---------------------------- | ----------------------------------------------- |
-| **4-Layer Memory**           | 10x context retention, reduces repetition       |
-| **Multi-Agent Coordination** | Eliminates merge conflicts, enables parallelism |
-| **Task Management**          | Structured work tracking, dependency awareness  |
-| **Worktree Isolation**       | Safe experimentation, atomic PRs                |
-| **Deploy Batching**          | 50-80% CI/CD cost reduction                     |
-| **CLAUDE.md Generation**     | Project-aware context, reduced hallucination    |
-
----
-
-## System Architecture
-
-```mermaid
-graph TB
-    subgraph "AI Agent Layer"
-        CLAUDE[Claude/GPT Agent]
-        FACTORY[Factory.AI Agent]
-        VSCODE[VSCode Copilot]
-    end
-
-    subgraph "UAP Core"
-        CLI[CLI Interface]
-        MEM[Memory System]
-        COORD[Coordination Service]
-        TASK[Task Service]
-        DEPLOY[Deploy Batcher]
-        GEN[CLAUDE.md Generator]
-    end
-
-    subgraph "Storage Layer"
-        SQLITE[(SQLite)]
-        QDRANT[(Qdrant Vector DB)]
-        GIT[(Git Repository)]
-    end
-
-    subgraph "External Services"
-        OLLAMA[Ollama Embeddings]
-        GITHUB[GitHub API]
-        DOCKER[Docker]
-    end
-
-    CLAUDE --> CLI
-    FACTORY --> CLI
-    VSCODE --> CLI
-
-    CLI --> MEM
-    CLI --> COORD
-    CLI --> TASK
-    CLI --> DEPLOY
-    CLI --> GEN
-
-    MEM --> SQLITE
-    MEM --> QDRANT
-    MEM --> OLLAMA
-
-    COORD --> SQLITE
-    TASK --> SQLITE
-    DEPLOY --> SQLITE
-    DEPLOY --> GIT
-    DEPLOY --> GITHUB
-
-    GEN --> GIT
-    GEN --> MEM
-
-    style MEM fill:#e3f2fd
-    style COORD fill:#fff3e0
-    style TASK fill:#f3e5f5
-    style DEPLOY fill:#e8f5e9
-```
-
-### Component Overview
-
-```mermaid
-mindmap
-  root((UAP))
-    Memory
-      Short-term SQLite
-      Long-term Qdrant
-      Session Memory
-      Knowledge Graph
-    Coordination
-      Agent Registry
-      Work Announcements
-      Message Bus
-      Overlap Detection
-    Tasks
-      Create/Update/Close
-      Dependencies
-      Priorities
-      Sync to JSONL
-    Worktrees
-      Create Branches
-      PR Generation
-      Cleanup
-    Deploy
-      Queue Actions
-      Batch Creation
-      Squash Commits
-      Parallel Execute
-    Generation
-      CLAUDE.md
-      AGENT.md
-      Project Analysis
-```
+> **Version:** 1.20.32  
+> **Last Updated:** 2026-04-08  
+> \*\*License: AI agents to maintain persistent context, learn from past interactions, and apply proven patterns across tasks.
 
 ---
 
-## CLI Command Reference
-
-### Command Hierarchy
+## Quick Start
 
-```mermaid
-flowchart TB
-    UAP[uap]
-
-    UAP --> INIT[init]
-    UAP --> ANALYZE[analyze]
-    UAP --> GENERATE[generate]
-    UAP --> UPDATE[update]
-
-    UAP --> MEMORY[memory]
-    MEMORY --> M_STATUS[status]
-    MEMORY --> M_START[start]
-    MEMORY --> M_STOP[stop]
-    MEMORY --> M_QUERY[query]
-    MEMORY --> M_STORE[store]
-    MEMORY --> M_PREPOP[prepopulate]
-
-    UAP --> WORKTREE[worktree]
-    WORKTREE --> W_CREATE[create]
-    WORKTREE --> W_LIST[list]
-    WORKTREE --> W_PR[pr]
-    WORKTREE --> W_CLEANUP[cleanup]
-
-    UAP --> AGENT[agent]
-    AGENT --> A_REG[register]
-    AGENT --> A_HB[heartbeat]
-    AGENT --> A_STATUS[status]
-    AGENT --> A_ANN[announce]
-    AGENT --> A_COMP[complete]
-    AGENT --> A_OVER[overlaps]
-    AGENT --> A_BROAD[broadcast]
-    AGENT --> A_SEND[send]
-    AGENT --> A_RECV[receive]
-    AGENT --> A_DEREG[deregister]
-
-    UAP --> COORD[coord]
-    COORD --> C_STATUS[status]
-    COORD --> C_FLUSH[flush]
-    COORD --> C_CLEAN[cleanup]
-
-    UAP --> DEPLOY[deploy]
-    DEPLOY --> D_QUEUE[queue]
-    DEPLOY --> D_BATCH[batch]
-    DEPLOY --> D_EXEC[execute]
-    DEPLOY --> D_STATUS[status]
-    DEPLOY --> D_FLUSH[flush]
-
-    UAP --> TASK[task]
-    TASK --> T_CREATE[create]
-    TASK --> T_LIST[list]
-    TASK --> T_SHOW[show]
-    TASK --> T_UPDATE[update]
-    TASK --> T_CLOSE[close]
-    TASK --> T_DEP[dep/undep]
-    TASK --> T_CLAIM[claim]
-    TASK --> T_RELEASE[release]
-    TASK --> T_STATS[stats]
-    TASK --> T_SYNC[sync]
-
-    style MEMORY fill:#e3f2fd
-    style AGENT fill:#fff3e0
-    style DEPLOY fill:#e8f5e9
-    style TASK fill:#f3e5f5
+```bash
+npm install -g @miller-tech/uap
+uap init
+uap setup -p all
 ```
 
-### Command Summary Table
-
-| Command        | Subcommand        | Purpose                                              |
-| -------------- | ----------------- | ---------------------------------------------------- |
-| `uap init`     | -                 | Initialize project with CLAUDE.md, memory, worktrees |
-| `uap analyze`  | -                 | Analyze project structure, generate metadata         |
-| `uap generate` | -                 | Generate/regenerate CLAUDE.md                        |
-| `uap update`   | -                 | Update all UAP components                            |
-| `uap memory`   | `status`          | Show memory system status                            |
-|                | `start/stop`      | Control Qdrant container                             |
-|                | `query <term>`    | Search memories                                      |
-|                | `store <content>` | Store new memory                                     |
-|                | `prepopulate`     | Import from docs/git history                         |
-| `uap worktree` | `create <slug>`   | Create isolated worktree                             |
-|                | `list`            | List all worktrees                                   |
-|                | `pr <id>`         | Create PR from worktree                              |
-|                | `cleanup <id>`    | Remove worktree and branch                           |
-| `uap agent`    | `register`        | Register new agent                                   |
-|                | `announce`        | Announce work intent                                 |
-|                | `overlaps`        | Check for conflicts                                  |
-|                | `broadcast/send`  | Inter-agent messaging                                |
-| `uap coord`    | `status`          | Show coordination status                             |
-|                | `cleanup`         | Remove stale data                                    |
-| `uap deploy`   | `queue`           | Queue deploy action                                  |
-|                | `batch`           | Create batch from pending                            |
-|                | `execute`         | Execute batch                                        |
-|                | `flush`           | Execute all pending                                  |
-| `uap task`     | `create`          | Create task                                          |
-|                | `list/show`       | View tasks                                           |
-|                | `claim/release`   | Work lifecycle                                       |
-|                | `dep/undep`       | Manage dependencies                                  |
-
 ---
 
-## Memory System
+## Architecture
 
-### Four-Layer Architecture
+### Four-Layer Memory System
 
 ```mermaid
 graph TB
-    subgraph "L1: Working Memory"
-        direction LR
-        W1[Recent Actions]
-        W2[Current Context]
-        W3[Active Decisions]
-    end
-
-    subgraph "L2: Session Memory"
-        direction LR
-        S1[Session Decisions]
-        S2[Important Context]
-        S3[Cross-Request State]
-    end
-
-    subgraph "L3: Semantic Memory"
-        direction LR
-        SE1[Learned Lessons]
-        SE2[Patterns]
-        SE3[Solutions]
-    end
-
     subgraph "L4: Knowledge Graph"
-        direction LR
         K1[Entities]
         K2[Relationships]
-        K3[File Dependencies]
-    end
-
-    W1 --> S1
-    W2 --> S2
-    S1 --> SE1
-    S2 --> SE2
-    SE1 --> K1
-    SE2 --> K2
-
-    style W1 fill:#ffcdd2
-    style W2 fill:#ffcdd2
-    style W3 fill:#ffcdd2
-    style S1 fill:#fff9c4
-    style S2 fill:#fff9c4
-    style S3 fill:#fff9c4
-    style SE1 fill:#c8e6c9
-    style SE2 fill:#c8e6c9
-    style SE3 fill:#c8e6c9
-    style K1 fill:#bbdefb
-    style K2 fill:#bbdefb
-    style K3 fill:#bbdefb
-```
-
-### Memory Layer Characteristics
-
-| Layer             | Storage                         | Capacity   | Latency | Retention         |
-| ----------------- | ------------------------------- | ---------- | ------- | ----------------- |
-| **L1: Working**   | SQLite `memories`               | 50 entries | <1ms    | Session           |
-| **L2: Session**   | SQLite `session_memories`       | Unlimited  | <5ms    | Project lifecycle |
-| **L3: Semantic**  | Qdrant vectors                  | Unlimited  | ~50ms   | Permanent         |
-| **L4: Knowledge** | SQLite `entities/relationships` | Unlimited  | <20ms   | Permanent         |
-
-### Hierarchical Memory Manager
-
-```mermaid
-stateDiagram-v2
-    [*] --> Hot: add()
-
-    Hot --> Hot: access() high frequency
-    Hot --> Warm: rebalance() overflow
-
-    Warm --> Hot: access() promotion
-    Warm --> Cold: rebalance() overflow
-
-    Cold --> Warm: query() retrieval
-    Cold --> Summary: consolidate()
-
-    Summary --> Cold: store summary
-
-    note right of Hot
-        In-context memory
-        Max 10 entries
-        2000 tokens limit
-    end note
-
-    note right of Warm
-        Cached memory
-        Max 50 entries
-        Frequent access
-    end note
-
-    note right of Cold
-        Archived memory
-        Max 500 entries
-        Semantic search only
-    end note
-```
-
-### Memory Decay Formula
-
-```
-effective_importance = importance × (0.95 ^ days_since_access)
-```
-
-Example decay over time:
-
-- Day 0: importance = 10.0
-- Day 7: importance = 6.98 (30% decay)
-- Day 30: importance = 2.15 (78% decay)
-- Day 90: importance = 0.10 (99% decay)
-
-### Memory Operations Flow
-
-```mermaid
-sequenceDiagram
-    participant Agent
-    participant CLI as uap memory
-    participant SQLite
-    participant Qdrant
-    participant Ollama
-
-    Note over Agent: Store Memory
-    Agent->>CLI: uap memory store "lesson"
-    CLI->>SQLite: INSERT into memories
-    CLI->>SQLite: INSERT into session_memories
-
-    alt importance >= 7
-        CLI->>Ollama: Generate embedding
-        Ollama-->>CLI: 384-dim vector
-        CLI->>Qdrant: Upsert to collection
-    end
-
-    Note over Agent: Query Memory
-    Agent->>CLI: uap memory query "pattern"
-    CLI->>SQLite: SELECT from memories (text match)
-    CLI->>SQLite: SELECT from session_memories
-
-    alt Need semantic search
-        CLI->>Ollama: Embed query
-        CLI->>Qdrant: Vector similarity search
-        Qdrant-->>CLI: Relevant memories
-    end
-
-    CLI-->>Agent: Combined results
-```
-
-### Prepopulation Sources
-
-```mermaid
-flowchart LR
-    subgraph "Sources"
-        DOCS[Documentation]
-        GIT[Git History]
-        SKILLS[Skills/Droids]
-    end
-
-    subgraph "Extraction"
-        PARSE[Parse Content]
-        EXTRACT[Extract Patterns]
-        CLASSIFY[Classify Type]
-    end
-
-    subgraph "Storage"
-        ST[Short-term]
-        LT[Long-term]
-        KG[Knowledge Graph]
     end
 
-    DOCS --> PARSE
-    GIT --> PARSE
-    SKILLS --> PARSE
-
-    PARSE --> EXTRACT
-    EXTRACT --> CLASSIFY
-
-    CLASSIFY --> ST
-    CLASSIFY --> LT
-    CLASSIFY --> KG
-```
-
----
-
-## Multi-Agent Coordination
-
-### Agent Lifecycle
-
-```mermaid
-stateDiagram-v2
-    [*] --> Registered: register()
-
-    Registered --> Active: heartbeat()
-    Active --> Active: heartbeat()
-    Active --> Idle: no current task
-    Idle --> Active: claim work
-
-    Active --> Completed: deregister()
-    Idle --> Completed: deregister()
-
-    Active --> Failed: heartbeat timeout
-    Idle --> Failed: heartbeat timeout
-
-    Completed --> [*]
-    Failed --> [*]
-```
-
-### Work Coordination Model
-
-UAP uses **announcements** (not locks) for coordination. Agents work in isolated worktrees, so hard locks are unnecessary.
-
-```mermaid
-flowchart TB
-    subgraph "Agent A (Worktree A)"
-        A1[Announce: editing src/auth.ts]
-        A2[Work in isolation]
-        A3[Complete work]
-    end
-
-    subgraph "Agent B (Worktree B)"
-        B1[Check overlaps]
-        B2[See Agent A working on auth]
-        B3[Choose different file or coordinate]
+    subgraph "L3: Semantic Memory"
+        S1[Qdrant Vectors]
+        S2[Similarity Search]
     end
 
-    subgraph "Coordination Service"
-        CS[Overlap Detection]
-        MSG[Message Bus]
-        SUGG[Collaboration Suggestions]
+    subgraph "L2: Session Memory"
+        SE1[High-Importance Decisions]
+        SE2[Per-Session State]
     end
 
-    A1 --> CS
-    B1 --> CS
-    CS --> B2
-    CS --> SUGG
-    SUGG --> B3
-
-    A3 --> MSG
-    MSG --> B3
-```
-
-### Overlap Detection & Conflict Risk
-
-```mermaid
-flowchart TB
-    subgraph "Risk Assessment"
-        R1{Same File?}
-        R2{Same Directory?}
-        R3{Overlapping Files?}
-        R4{Intent Types?}
+    subgraph "L1: Working Memory"
+        W1[SQLite + FTS5]
+        W2[Recent Actions]
     end
 
-    subgraph "Risk Levels"
-        CRIT[CRITICAL: Multiple editing same file]
-        HIGH[HIGH: Refactoring + editing same area]
-        MED[MEDIUM: Same directory]
-        LOW[LOW: Review/test/document]
-        NONE[NONE: No overlap]
-    end
+    K1 --> S1
+    S1 --> SE1
+    SE1 --> W1
 
-    R1 -->|Yes + editing| CRIT
-    R1 -->|Yes + mixed| HIGH
-    R1 -->|No| R2
-    R2 -->|Yes| MED
-    R2 -->|No| R3
-    R3 -->|Yes| MED
-    R3 -->|No| R4
-    R4 -->|Low risk types| LOW
-    R4 -->|No overlap| NONE
-
-    style CRIT fill:#ffcdd2
-    style HIGH fill:#ffab91
-    style MED fill:#fff9c4
-    style LOW fill:#c8e6c9
-    style NONE fill:#bbdefb
+    style K1 fill:#e3f2fd,stroke:#1976d2
+    style S1 fill:#fff3e0,stroke:#f57c00
+    style SE1 fill:#f3e5f5,stroke:#7b1fa2
+    style W1 fill:#c8e6c9,stroke:#388e3c
 ```
 
-### Collaboration Suggestions
-
-| Risk Level   | Suggestion                                      |
-| ------------ | ----------------------------------------------- |
-| **Critical** | STOP - One agent should wait or request handoff |
-| **High**     | Sequential work - agree on who merges first     |
-| **Medium**   | Announce changes, coordinate merge order        |
-| **Low**      | Parallel work safe, watch shared imports        |
-| **None**     | Full parallel execution                         |
-
-### Inter-Agent Messaging
-
-```mermaid
-sequenceDiagram
-    participant A1 as Agent 1
-    participant CS as Coordination Service
-    participant A2 as Agent 2
-    participant A3 as Agent 3
-
-    Note over A1,A3: Broadcast Message
-    A1->>CS: broadcast(channel: coordination)
-    CS->>A2: Message queued
-    CS->>A3: Message queued
-    A2->>CS: receive()
-    CS-->>A2: Messages
-
-    Note over A1,A2: Direct Message
-    A1->>CS: send(to: Agent2)
-    A2->>CS: receive()
-    CS-->>A2: Direct message
-```
+| Layer         | Storage                   | Capacity   | Latency |
+| ------------- | ------------------------- | ---------- | ------- |
+| L1: Working   | SQLite `memories`         | 50 entries | <1ms    |
+| L2: Session   | SQLite `session_memories` | Unlimited  | <5ms    |
+| L3: Semantic  | Qdrant vectors            | Unlimited  | ~50ms   |
+| L4: Knowledge | SQLite entities/rels      | Unlimited  | <20ms   |
 
----
+### Multi-Agent Coordination**Agent Registry**: Track active agents with heartbeat monitoring
 
-## Task Management System
+- **Work Announcements**: Declare intent before editing resources
+- **Overlap Detection**: Prevent conflicts via resource analysis
+- **Inter-Agent Messaging**: Broadcast, direct, and channel-based communication
+- **Deploy Batching**: Squash, merge, parallelize deploy actions
 
-### Task State Machine
+### Task Management (7 modules)
 
-```mermaid
+````mermaid
 stateDiagram-v2
     [*] --> open: create()
-
     open --> in_progress: update(status)
     open --> blocked: dependency added
 
-    in_progress --> blocked: blocker discovered
     in_progress --> done: close()
     in_progress --> wont_do: close(reason)
 
@@ -564,554 +82,253 @@ stateDiagram-v2
 
     done --> [*]
     wont_do --> [*]
-```
-
-### Task Hierarchy
 
-```mermaid
-graph TB
-    subgraph "Task Types"
-        EPIC[Epic]
-        FEATURE[Feature]
-        STORY[Story]
-        TASK[Task]
-        BUG[Bug]
-        CHORE[Chore]
-    end
+    style open fill:#c8e6c9,stroke:#388e3c
+    | Storage | Capacity      | Latency |
+|----------|--------------------------|---------------|---------|
+| L1: Working | SQLite `memories`        | 50 entries    | <1ms    |
+| L2: Session | SQLite `session_memories`| Unlimited     | <5ms    |
+| L3: Semantic | Qdrant vectors           | Unlimited     | ~50ms   |
+| L4: Knowledge | SQLite entities/rels     | Unlimited     | <20ms   |
 
-    EPIC --> FEATURE
-    EPIC --> STORY
-    FEATURE --> TASK
-    FEATURE --> BUG
-    STORY --> TASK
-    STORY --> CHORE
+---
 
-    style EPIC fill:#e1bee7
-    style FEATURE fill:#b3e5fc
-    style STORY fill:#c8e6c9
-```
+## CLI Reference
 
-### Priority Levels
+### 25 Top-Level Commands
 
-| Priority | Label    | Use Case                         |
-| -------- | -------- | -------------------------------- |
-| P0       | Critical | Production down, security breach |
-| P1       | High     | Major functionality broken       |
-| P2       | Medium   | Important but not urgent         |
-| P3       | Low      | Nice to have                     |
-| P4       | Backlog  | Future consideration             |
+| Command | Description |
+|---------|-------------|
+| `uap init` | Initialize UAP in a project |
+| `uap setup -p all` | Full setup (memory, Qdrant, hooks, patterns) |
+| `uap memory <action>` | Memory management (9 subcommands) |
+| `uap worktree <action>` | Git worktree management (5 subcommands) |
+| `uap agent <action>` | Agent lifecycle (10 subcommands) |
+| `uap deploy <action>` | Deploy batching (8 subcommands) |
+| `uap task <action>` | Task management (15 subcommands) |
+| `uap policy <action>` | Policy management (15 subcommands) |
+| `uap model <action>` | Multi-model management (8 subcommands) |
+| `uap patterns <action>` | Pattern RAG management (4 subcommands) |
 
-### Task-Agent Integration
+**Total: 109 commands and subcommands.**
 
-```mermaid
-sequenceDiagram
-    participant Agent
-    participant TaskSvc as Task Service
-    participant CoordSvc as Coordination Service
-    participant Worktree as Worktree Manager
-
-    Note over Agent: Claim Task
-    Agent->>TaskSvc: task claim <id>
-    TaskSvc->>TaskSvc: Update assignee
-    TaskSvc->>TaskSvc: Set status = in_progress
-    TaskSvc->>CoordSvc: Announce work intent
-    TaskSvc->>Worktree: Create worktree
-    Worktree-->>Agent: Worktree path
-
-    Note over Agent: Release Task
-    Agent->>TaskSvc: task release <id>
-    TaskSvc->>TaskSvc: Set status = done
-    TaskSvc->>CoordSvc: Announce completion
-    CoordSvc->>CoordSvc: Notify blocked tasks
-```
+### Common Operations
 
-### Dependency Management
+```bash
+# Query semantic memory
+uap memory query "authentication errors"
 
-```mermaid
-graph LR
-    subgraph "Dependency Types"
-        BLOCKS[blocks: A must complete before B]
-        RELATED[related: A and B are connected]
-        DISC[discovered_from: B found while working A]
-    end
+# Create tracked task
+uap task create --title "Fix login bug" --type bug
 
-    T1[Task 1: Setup DB]
-    T2[Task 2: Add API]
-    T3[Task 3: Add Tests]
-    T4[Task 4: Documentation]
+# Check for agent overlaps
+uap agent overlaps --resource src/auth.ts
 
-    T1 -->|blocks| T2
-    T2 -->|blocks| T3
-    T2 -.->|related| T4
-    T3 -.->|discovered_from| T4
-```
+# Queue deploy action
+uap deploy queue --action commit --target main --message> View dashboard
+uap dashboard
+````
 
 ---
 
-## Worktree Workflow
-
-### Worktree Lifecycle
-
-```mermaid
-stateDiagram-v2
-    [*] --> Created: worktree create <slug>
-
-    Created --> Working: cd .worktrees/NNN-slug
-    Working --> Working: commits, changes
-    Working --> PRCreated: worktree pr <id>
-
-    PRCreated --> Merged: PR approved
-    PRCreated --> Working: changes requested
-
-    Merged --> Cleaned: worktree cleanup <id>
-    Cleaned --> [*]
-```
-
-### Worktree Directory Structure
-
-```
-project/
-├── .worktrees/
-│   ├── 001-add-auth/           # Worktree 1
-│   │   ├── src/
-│   │   └── ...
-│   ├── 002-fix-bug/            # Worktree 2
-│   │   ├── src/
-│   │   └── ...
-│   └── 003-refactor-api/       # Worktree 3
-├── src/                        # Main working directory
-└── ...
-```
-
-### Worktree + Agent Coordination
-
-```mermaid
-sequenceDiagram
-    participant A1 as Agent 1
-    participant A2 as Agent 2
-    participant WT as Worktree Manager
-    participant GIT as Git
-    participant CS as Coordination
-
-    A1->>WT: create add-auth
-    WT->>GIT: git worktree add -b feature/001-add-auth
-    GIT-->>WT: Created
-    WT-->>A1: .worktrees/001-add-auth
-
-    A2->>WT: create fix-bug
-    WT->>GIT: git worktree add -b feature/002-fix-bug
-    GIT-->>WT: Created
-    WT-->>A2: .worktrees/002-fix-bug
-
-    Note over A1,A2: Parallel Work in Isolation
-
-    A1->>CS: announce(editing src/auth.ts)
-    A2->>CS: overlaps check
-    CS-->>A2: No overlap (different worktree)
-
-    A1->>WT: pr 1
-    WT->>GIT: push + gh pr create
-
-    A2->>WT: pr 2
-    WT->>GIT: push + gh pr create
-```
+## Pattern System (23 Patterns)
+
+Battle-tested patterns from Terminal-Bench 2.0:
+
+| Pattern | ID | Missing output files (37% of failures) |
+| Iterative Refinement | P13 | First-attempt acceptance |
+| Output Format | P14 | Wrong format/encoding |
+| Task-First | P16 | Over-planning before doing |
+| Constraint Extraction | P17 | Missing hidden requirements |
+| Impossible Refusal | P19 | Attempting impossible tasks |
+| Chess Engine | P21 | Reinventing Stockfish |
+| Git Recovery | P22 | Data loss during git ops |
+| Compression Check | P23 | Lossy compression errors |
+| Polyglot | P24 | Single-language thinking |
+| Near-Miss | P26 | Almost-correct solutions |
+| Smoke Test | P28 | Untested changes |
+| Performance Threshold | P30 | Missing perf targets |
+| Round-Trip | P31 | Encode/decode mismatches |
+| CLI Verify | P32 | Broken CLI commands |
+| Numerical Stability | P33 | Floating point errors |
+| Image Pipeline | P34 | Image processing errors |
+| Decoder-First | P35 | Wrong problem decomposition |
+| Competition Domain | P36 | Missing domain knowledge |
+| Ambiguity Detection | P37 | Ambiguous task descriptions |
+| IaC Parity | IaC | Config drift |
 
 ---
 
-## CLAUDE.md Generation
+## Multi-Model Architecture
 
-### Generation Pipeline
+### 3-Tier Execution
 
 ```mermaid
-flowchart TB
-    subgraph "Input Sources"
-        PKG[package.json]
-        GIT[Git History]
-        FS[File System]
-        SKILLS[Skills/Droids]
-        MEM[Memory DB]
-    end
-
-    subgraph "Analysis"
-        ANALYZE[Project Analyzer]
-        DETECT[Pattern Detection]
-        PREP[Prepopulate Memory]
+flowchart LR
+    subgraph "Tier 1: TaskPlanner"
+        P1[Decompose task]
+        P2[Analyze dependencies]
     end
 
-    subgraph "Generation"
-        TPL[Template Loader]
-        HBS[Handlebars Compile]
-        CTX[Context Builder]
+    subgraph "Tier 2: ModelRouter"
+        R1[Assign optimal model]
+        R2[Cost optimization]
     end
 
-    subgraph "Output"
-        CLAUDE[CLAUDE.md]
-        AGENT[AGENT.md]
+    subgraph "Tier 3: TaskExecutor"
+        E1[Execute with validation]
+        E2[Dynamic temperature]
+        E3[Rate limiting]
     end
 
-    PKG --> ANALYZE
-    GIT --> ANALYZE
-    FS --> ANALYZE
-    SKILLS --> ANALYZE
-    MEM --> PREP
-
-    ANALYZE --> DETECT
-    DETECT --> CTX
-    PREP --> CTX
+    P1 --> R1
+    P2 --> R2
+    R1 --> E1
+    R2 --> E2
+    E2 --> E3
 
-    CTX --> HBS
-    TPL --> HBS
-
-    HBS --> CLAUDE
-    HBS --> AGENT
-```
-
-### Generated Context Categories
-
-```mermaid
-mindmap
-  root((CLAUDE.md))
-    Project
-      Name
-      Description
-      Default Branch
-    Memory
-      DB Paths
-      Commands
-      Limits
-    Worktree
-      Directory
-      Commands
-      Branch Prefix
-    Skills
-      Mappings
-      Language Droids
-      File Routing
-    Structure
-      Repository Layout
-      Core Components
-      Config Files
-    Knowledge
-      Recent Activity
-      Lessons Learned
-      Gotchas
-      Hot Spots
+    style P1 fill:#e3f2fd,stroke:#1976d2
+    style R1 fill:#fff3e0,stroke:#f57c00
+    style E1 fill:#c8e6c9,stroke:#388e3c
 ```
 
-### Template Variables
-
-| Variable               | Source            | Purpose                   |
-| ---------------------- | ----------------- | ------------------------- |
-| `PROJECT_NAME`         | package.json      | Project identification    |
-| `MEMORY_DB_PATH`       | config            | Memory database location  |
-| `TEST_COMMAND`         | package.json      | How to run tests          |
-| `REPOSITORY_STRUCTURE` | File system scan  | Directory layout          |
-| `LANGUAGE_DROIDS`      | Discovered skills | Language specialists      |
-| `TROUBLESHOOTING`      | Git history       | Known issues/fixes        |
-| `HOT_SPOTS`            | Git analysis      | Frequently modified files |
-
 ---
 
-## Deploy Batching
+## MCP Router
 
-_(See [DEPLOY_BATCHER_ANALYSIS.md](./DEPLOY_BATCHER_ANALYSIS.md) for detailed analysis)_
+Replaces N tool definitions with 2 meta-tools for **98% token reduction**.
 
-### Quick Reference
+### Components (10 modules)
 
-```mermaid
-flowchart LR
-    subgraph "Queue"
-        Q1[Commit 1]
-        Q2[Commit 2]
-        Q3[Push]
-        Q4[Workflow]
-    end
+| Component     | Purpose                                     |
+| ------------- | ------------------------------------------- |
+| MCP Server    | Exposes `discover_tools` and `execute_tool` |
+| Config Parser | Loads MCP configs from standard paths       |
+| Fuzzy Search  | Tool discovery with fuzzy matching          |
+| Client Pool   | Manages connections to MCP servers          |
+| Tool Execute  | Tool execution with policy gate             |
 
-    subgraph "Batch"
-        B[Squash + Group]
-    end
+---
 
-    subgraph "Execute"
-        E1[Single Commit]
-        E2[Single Push]
-        E3[Workflow]
-    end
+## Policy Enforcement (8 modules)
 
-    Q1 --> B
-    Q2 --> B
-    Q3 --> B
-    Q4 --> B
+### Enforcement Levels
 
-    B --> E1
-    B --> E2
-    B --> E3
-```
+| Level       | Behavior                                        |
+| ----------- | ----------------------------------------------- |
+| REQUIRED    | Blocks execution, throws `PolicyViolationError` |
+| RECOMMENDED | Logged but does not block                       |
+| OPTIONAL    | Informational only                              |
 
-### Window Configuration
+### CLI Commands
 
-| Action   | Window | Rationale              |
-| -------- | ------ | ---------------------- |
-| Push     | 5s     | Fast PR feedback       |
-| Workflow | 5s     | Responsive CI triggers |
-| Merge    | 10s    | Moderate safety        |
-| Commit   | 30s    | Allow squashing        |
-| Deploy   | 60s    | Production safety      |
+```bash
+uap policy list                    # List all policies
+uap policy install <name>          # Install built-in policy
+uap policy enable <id>             # Enable a policy
+uap policy disable <id>            # Disable a policy
+uap policy check -o <operation>    # Check if allowed
+uap policy audit                   # View audit trail
+```
 
 ---
 
-## Agent Performance Implications
+## Browser Automation
 
-### Performance Impact Matrix
+Stealth web browser via CloakBrowser (Playwright drop-in):
 
-```mermaid
-quadrantChart
-    title UAP Feature Impact on Agent Performance
-    x-axis Low Token Usage --> High Token Usage
-    y-axis Low Task Completion --> High Task Completion
-    quadrant-1 Optimize
-    quadrant-2 Essential
-    quadrant-3 Avoid
-    quadrant-4 Consider
-    Memory Query: [0.3, 0.8]
-    Memory Store: [0.2, 0.7]
-    Task Create: [0.2, 0.6]
-    Worktree Create: [0.3, 0.9]
-    Agent Announce: [0.2, 0.7]
-    Overlap Check: [0.1, 0.8]
-    Deploy Queue: [0.2, 0.6]
-    CLAUDE.md Gen: [0.6, 0.9]
-    Prepopulate: [0.7, 0.5]
-```
+```typescript
+import { createWebBrowser } from '@miller-tech/uap/browser';
 
-### Token Efficiency Analysis
+const browser = createWebBrowser();
+await browser.launch({ headless: true, humanize: true });
+await browser.goto('https://example.com');
+const content = await browser.getContent();
+await browser.close();
+```
 
-| Operation             | Tokens Used | Value Delivered       | ROI               |
-| --------------------- | ----------- | --------------------- | ----------------- |
-| Memory query (cached) | ~50         | Avoids re-learning    | High              |
-| Memory store (lesson) | ~100        | Future reuse          | High              |
-| Task create           | ~80         | Structured tracking   | Medium            |
-| Worktree create       | ~60         | Safe isolation        | Very High         |
-| Agent announce        | ~40         | Conflict prevention   | High              |
-| Overlap check         | ~30         | Merge avoidance       | Very High         |
-| Deploy batch          | ~50         | CI/CD savings         | Very High         |
-| CLAUDE.md generate    | ~2000       | Context bootstrapping | Medium (one-time) |
+---
 
-### Memory Impact on Context Window
+## Testing & Quality
 
-```mermaid
-pie title Context Window Usage (8K example)
-    "System Prompt" : 1500
-    "CLAUDE.md" : 2500
-    "Hot Memory" : 500
-    "User Messages" : 2000
-    "Available" : 1500
+```bash
+npm test              # 693 tests across 45 test files
+npm run build         # TypeScript compilation
+npm run lint          # ESLint
+npm run format        # Prettier
+npm run test:coverage # Coverage report (50% thresholds)
 ```
 
-### Performance Recommendations
+---
 
-```mermaid
-flowchart TB
-    START[Agent Session Start]
-
-    START --> QUERY[Query recent memories]
-    QUERY --> CHECK[Check active work/overlaps]
-    CHECK --> TASK[Check/create task]
-    TASK --> WT[Use worktree if editing]
-
-    WT --> WORK[Perform work]
-    WORK --> STORE[Store important lessons]
-    STORE --> DEPLOY[Queue deploy actions]
-    DEPLOY --> END[Session end]
-
-    style QUERY fill:#c8e6c9
-    style CHECK fill:#c8e6c9
-    style WT fill:#c8e6c9
-    style STORE fill:#fff9c4
-    style DEPLOY fill:#bbdefb
+## Configuration
+
+### .uap.json (Project Settings)
+
+```json
+{
+  "version": "1.0.0",
+  "project": { "name": "my-project", "defaultBranch": "main" },
+  "memory": {
+    "shortTerm": { "enabled": true, "path": "./agents/data/memory/short_term.db" },
+    "longTerm": { "enabled": true, "provider": "qdrant" }
+  },
+  "multiModel": {
+    "enabled": true,
+    "models": ["opus-4.6", "qwen35"],
+    "roles": { "planner": "opus-4.6", "executor": "qwen35" },
+    "routingStrategy": "balanced"
+  },
+  "worktrees": { "enabled": true, "directory": ".worktrees" }
+}
 ```
 
-### Anti-Patterns to Avoid
+---
 
-| Anti-Pattern               | Impact           | Solution                    |
-| -------------------------- | ---------------- | --------------------------- |
-| Querying memory every turn | Token waste      | Query at session start      |
-| Storing trivial memories   | DB bloat         | Only store importance >= 5  |
-| Skipping overlap check     | Merge conflicts  | Always check before editing |
-| Direct commits to main     | Risk of breakage | Always use worktrees        |
-| Individual CI triggers     | Wasted minutes   | Use deploy batching         |
+## Requirements
 
----
+| Dependency | Version   | Required | Purpose                    |
+| ---------- | --------- | -------- | -------------------------- |
+| Node.js    | >= 18.0.0 | Yes      | Runtime                    |
+| git        | Latest    | Yes      | Version control, worktrees |
+| Docker     | Latest    | No       | Local Qdrant               |
+| Python 3   | Latest    | No       | Embeddings, Pattern RAG    |
 
-## Integration Patterns
+---
 
-### Agent Session Workflow
+## Performance Impact
 
-```mermaid
-sequenceDiagram
-    participant User
-    participant Agent
-    participant UAP
-    participant Git
-
-    Note over Agent: Session Start
-    Agent->>UAP: uap memory query <recent>
-    Agent->>UAP: uap task ready
-    Agent->>UAP: uap agent overlaps
-
-    User->>Agent: "Fix the auth bug"
-    Agent->>UAP: uap task create --title "Fix auth bug" --type bug
-    Agent->>UAP: uap worktree create fix-auth-bug
-    Agent->>UAP: uap agent announce --resource src/auth.ts
-
-    Agent->>Agent: Implement fix
-    Agent->>UAP: uap deploy queue --action-type commit
-
-    Agent->>UAP: uap memory store "Fixed auth by..."
-    Agent->>UAP: uap agent complete
-    Agent->>UAP: uap task close <id>
-    Agent->>UAP: uap worktree pr <id>
-
-    Note over Agent: Session End
-    Agent->>UAP: uap deploy flush
-```
+| Feature               | Token Savings | Task Completion Impact      |
+| --------------------- | ------------- | --------------------------- |
+| Memory query (cached) | ~50 tokens    | High (avoids re-learning)   |
+| Worktree create       | ~60 tokens    | Very High (safe isolation)  |
+| Agent announce        | ~40 tokens    | High (conflict prevention)  |
+| Overlap check         | ~30 tokens    | Very High (merge avoidance) |
+| Deploy batch          | ~50 tokens    | Very High (CI/CD savings)   |
 
-### Multi-Agent Parallel Work
+**Overall Impact:**
 
-```mermaid
-sequenceDiagram
-    participant A1 as Agent 1
-    participant A2 as Agent 2
-    participant UAP
-    participant Main as Main Branch
-
-    par Agent 1 Path
-        A1->>UAP: worktree create feature-a
-        A1->>UAP: announce(src/moduleA)
-        A1->>A1: Implement Feature A
-        A1->>UAP: deploy queue commit
-        A1->>UAP: complete
-    and Agent 2 Path
-        A2->>UAP: worktree create feature-b
-        A2->>UAP: overlaps check (clear)
-        A2->>UAP: announce(src/moduleB)
-        A2->>A2: Implement Feature B
-        A2->>UAP: deploy queue commit
-        A2->>UAP: complete
-    end
+- **60-80%** reduction in context repetition
+- **50-80%** reduction in CI/CD minutes
+- **Near-zero** merge conflicts in multi-agent scenarios
 
-    UAP->>UAP: createBatch()
-    UAP->>Main: Squashed commits
-    UAP->>Main: Single CI run
-```
+---
 
-### Database Schema Overview
+## Documentation
 
-```mermaid
-erDiagram
-    agent_registry ||--o{ work_announcements : announces
-    agent_registry ||--o{ work_claims : claims
-    agent_registry ||--o{ agent_messages : sends
-    agent_registry ||--o{ deploy_queue : queues
-
-    memories {
-        INTEGER id PK
-        TEXT timestamp
-        TEXT type
-        TEXT content
-    }
-
-    session_memories {
-        INTEGER id PK
-        TEXT session_id
-        TEXT timestamp
-        TEXT type
-        TEXT content
-        INTEGER importance
-    }
-
-    entities {
-        INTEGER id PK
-        TEXT type
-        TEXT name
-        TEXT first_seen
-        TEXT last_seen
-        INTEGER mention_count
-    }
-
-    relationships {
-        INTEGER id PK
-        INTEGER source_id FK
-        INTEGER target_id FK
-        TEXT relation
-        TEXT timestamp
-    }
-
-    agent_registry {
-        TEXT id PK
-        TEXT name
-        TEXT session_id
-        TEXT status
-        TEXT worktree_branch
-    }
-
-    work_announcements {
-        INTEGER id PK
-        TEXT agent_id FK
-        TEXT intent_type
-        TEXT resource
-        TEXT announced_at
-    }
-
-    deploy_queue {
-        INTEGER id PK
-        TEXT agent_id FK
-        TEXT action_type
-        TEXT target
-        TEXT status
-        TEXT batch_id
-    }
-
-    deploy_batches {
-        TEXT id PK
-        TEXT created_at
-        TEXT status
-    }
-
-    tasks {
-        TEXT id PK
-        TEXT title
-        TEXT status
-        TEXT type
-        INTEGER priority
-        TEXT assignee
-    }
-
-    task_dependencies {
-        TEXT from_id FK
-        TEXT to_id FK
-        TEXT type
-    }
-```
+- **[Getting Started](docs/getting-started/OVERVIEW.md)**: Core concepts and setup
+- **[Architecture](docs/architecture/SYSTEM_ANALYSIS.md)**: Complete system analysis
+- **[CLI Reference](docs/reference/UAP_CLI_REFERENCE.md)**: Full command reference
+- **[Deployment](docs/deployment/DEPLOYMENT.md)**: Production deployment guide
+- **[Benchmarks](docs/benchmarks/README.md)**: Performance analysis
 
 ---
 
-## Summary
+## Attribution
 
-UAP provides a comprehensive system for enhancing AI agent performance through:
+- Terminal-Bench patterns from [Terminal-Bench 2.0](https://github.com/aptx432/terminal-bench)
+- CloakBrowser from [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
 
-| System                       | Agent Benefit                                                       |
-| ---------------------------- | ------------------------------------------------------------------- |
-| **4-Layer Memory**           | Persistent learning, reduced repetition, faster context building    |
-| **Multi-Agent Coordination** | Safe parallel work, conflict prevention, efficient resource usage   |
-| **Task Management**          | Structured work tracking, dependency awareness, progress visibility |
-| **Worktree Isolation**       | Safe experimentation, atomic changes, easy rollback                 |
-| **Deploy Batching**          | Reduced CI/CD costs, faster deployments, commit squashing           |
-| **CLAUDE.md Generation**     | Project-aware context, reduced hallucination, consistent behavior   |
-
-**Overall Impact**: Agents using UAP show:
+---
 
-- **60-80%** reduction in context repetition
-- **50-80%** reduction in CI/CD minutes
-- **Near-zero** merge conflicts in multi-agent scenarios
-- **Improved** task completion rates through structured tracking
-- **Better** code quality through worktree isolation
+**[Documentation](docs/INDEX.md)** | **[npm](https://www.npmjs.com/package/@miller-tech/uap)** | **[GitHub](https://github.com/DammianMiller/universal-agent-protocol)**