@miller-tech/uap 1.20.32 → 1.20.34

package/docs/GETTING_STARTED.md

@@ -0,0 +1,288 @@
+# UAP - Universal Agent Protocol
+
+> **Version:** 1.20.32  
+> **Last Updated:** 2026-04-08  
+> **License:**
+
+**Universal Agent Protocol (UAP)** is an open protocol that enables AI agents to maintain persistent context, learn from past interactions, and apply proven patterns across tasks.
+
+---
+
+## Core Capabilities
+
+1. **Persistent Memory**: Store and retrieve information across sessions with 4-layer architecture
+2. **Pattern Application**: Leverage 58+ battle-tested workflows and decision frameworks
+3. **Multi-Agent Coordination**: Coordinate work between agents to prevent conflicts
+4. **CI/CD Optimization**: Reduce pipeline costs by 50-80% through intelligent batching
+5. **MCP Integration**: Achieve 98% token reduction via meta-tool routing
+
+### Quick Start
+
+```bash
+# Install UAP CLI
+npm install -g universal-agent-protocol
+
+# Initialize in your project
+uap init
+
+# Create a tracked task
+uap task create "Implement feature X"
+
+# Use worktree for safe development
+uap worktree create feature-name
+cd .worktrees/NNN-feature-name/
+# Make changes...
+uap worktree pr <id>
+```
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm or yarn
+- Optional: Docker (for Qdrant semantic search)
+
+---
+
+## Architecture
+
+### System Overview
+
+UAP implements a **4-layer memory architecture** combined with multi-agent coordination:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AI Agent Layer                           │
+│            (Claude, Factory.AI, OpenCode, etc.)             │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                    UAP Core Layer                           │
+│  CLI │ Memory │ Coordination │ Task │ Deploy Batcher        │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                   │
+│  CLI │ Memory │ Coordination │ Task │ Deploy Batcher        │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                    │  CLI │ Memory │ Coordination │ Task │ Deploy Batcher        │
+──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                    Storage Layer                         │
+│  SQLite (Working) │ Qdrant (Semantic) │ Git (History)       │	─────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component           | Purpose                      | Impact                   |
+| ------------------- | ---------------------------- | ------------------------ |
+| **Memory System**   | 4-layer persistent context   | 10x retention            |
+| ination\*\*         | Multi-agent sync via SQLite  | Zero conflicts           |
+| **Task Management** | Structured workflow tracking | Full lifecycle           |
+| **Deploy Batcher**  | CI/CD optimization           | 50-80% savings           |
+| **MCP Router**      | Meta-tool routing            | 98% token reduction      |
+| Worktrees\*\*       | Safe isolated development    | No main branch pollution |
+
+---
+
+## Reference
+
+### CLI Commands
+
+#### Task Management
+
+```bash
+# Create and track tasks
+uap task create "Fix bug" --priority high
+uap task list --active
+uap task complete --reason "Fixed"
+```
+
+#### Memory Operations
+
+```bash
+# Store and query memories
+uap memory store "Best practice: validate inputs"
+uap memory query "authentication" --top-k 5
+uap memory status
+```
+
+#### Worktree Workflow
+
+```bash
+# Safe isolated development
+uap worktree create feature-name
+cd .worktrees/NNN-feature-name/
+ges...
+uap worktree pr <id>
+uap worktree cleanup <id>  # After merge
+```
+
+#### Compliance
+
+```bash
+# Verify protocol compliance
+uap compliance check
+uap hooks install all
+```
+
+### Database Schema
+
+UAP uses SQLite for structured data and Qdrant for semantic search:
+
+**SQLite Tables:**
+
+- `memories` - Short-term working memory (50 entries)
+- `session_memories` - Current session state
+- `entities/relationships` - Knowledge graph
+- `agent_registry` - Multi-agent coordination
+- `deploy_queue` - CI/CD batching queue
+
+**Qdrant Collections:**
+
+- `agent_memory` - Semantic embeddings (384-dim vectors)
+- `agent_patterns` - Pattern library indexing
+
+---
+
+## Deployment
+
+### Production Setup
+
+```bash
+# Start Qdrant for semantic search
+cd agents && docker-compose up -d
+
+# Install hooks
+uap hooks install all
+
+# Verify setup
+uap task ready
+```
+
+### CI/CD Integration
+
+UAP integrates with GitHub Actions via the DeployBatcher:
+
+```yaml
+name: UAP CI
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run UAP benchmarks
+        run: npm run benchmark:full
+```
+
+### Model Providers
+
+| Provider              | Use Case          | Configuration           |
+| --------------------- | ----------------- | ----------------------- |
+| **Qwen3.5**           | General tasks     | Default, cost-effective |
+| **Claude Opus**       | Complex reasoning | High-accuracy scenarios |
+| **GPT-4**             | Analysis tasks    | Code generation         |
+| **Local (llama.cpp)** | Privacy-focused   | Self-hosted deployments |
+
+---
+
+## Benchmarks
+
+### Performance Summary
+
+| Metric           | Baseline | UAP v1.18 | Improvement |
+| ---------------- | -------- | --------- | ----------- |
+| **Success Rate** | 75%      | **100%**  | +25pp       |
+| **Tokens/Task**  | 52K      | **23.4K** | -55%        |
+| **Time/Task**    | 45s      | **32s**   | -29%        |
+| **Error Rate**   | 12%      | **0%**    | -100%       |
+
+### Full Benchmark Suite
+
+Run the complete benchmark suite:
+
+```bash
+# Quick test (10 tasks)
+npm run benchmark:short
+
+# Full validation (14 tasks)
+npm run benchmark:full
+
+# Overnight extended run
+npm run benchmark:overnight
+```
+
+Results are documented in [COMPREHENSIVE_BENCHMARKS.md](benchmarks/COMPREHENSIVE_BENCHMARKS.md).
+
+## Operations
+
+### Troubleshooting
+
+| Issue                      | Solution                               |
+| -------------------------- | -------------------------------------- |
+| `Qdrant connection failed` | `cd agents && docker-compose up -d`    |
+| `Worktree already exists`  | `uap worktree cleanup <id>`            |
+| Memory DB locked`          | Close other processes using the DB     |
+| `Compliance check failed`  | Review specific gate failure in output |
+
+### Debug Mode
+
+```bash
+# Enable verbose logging
+export UAP_VERBOSE=true
+
+# Check memory queries
+uap task ready --verbose
+
+# Inspect database directly
+sqlite3 ./agents/data/memory/short_term.db ".tables"
+```
+
+---
+
+## Contributing
+
+### Development Setup
+
+```bash
+git clone https://github.com/DammianMiller/universal-agent-protocol.git
+cd universal-agent-protocol
+npm install
+npm run build
+npm test
+```
+
+### Worktree Workflow
+
+All changes must be made in a worktree:
+
+```bash
+# Create worktree for your feature
+uap worktree create feature-description
+
+# Make changes, commit, create PR
+cd .worktrees/NNN-feature-description/
+git add -A && git commit -m "feat: description"
+uap worktree pr <id>
+
+# After merge, cleanup is mandatory
+uap worktree cleanup <id>
+```
+
+---
+
+## License
+
+MIT License - See [LICENSE](../LICENSE) file
+
+---
+
+<div align="center">
+
+**Maintained by:** UAP Team  
+**Repository:** https://github.com/DammianMiller/universal-agent-protocol  
+**Issues:** https://github.com/DammianMiller/universal-agent-protocol/issues
+306 lines)

package/docs/INDEX.md

@@ -1,76 +1,306 @@
 # UAP Documentation
 
-> @miller-tech/uap -- Documentation Hub
+> **Version:** 1.18.0  
+> **Last Updated:** 2026-03-28  
+> **License:** MIT
+
+---
+
+## Quick Links
+
+| Section | Description |
+|---------|-------------|
+| [Getting Started](#getting-started) | Installation and quick start |
+| [Architecture](#architecture) | System design and components |
+| [Reference](#reference) | API documentation and CLI commands |
+| [Deployment](#deployment) | Production deployment guides |
+| [Benchmarks](#benchmarks) | Performance results and validation |
+| [Operations](#operations) | Troubleshooting and maintenance |
 
 ---
 
 ## Getting Started
 
-- [Overview](getting-started/OVERVIEW.md) -- What is UAP, core concepts, 4-layer memory architecture
-- [Setup](getting-started/SETUP.md) -- Installation, dependencies, configuration
-- [Integration](getting-started/INTEGRATION.md) -- Claude Code, Factory.AI, OpenCode, ForgeCode, VSCode, Cursor
+### What is UAP?
+
+**Universal Agent Protocol (UAP)** is an open protocol that enables AI agents to maintain persistent context, learn from past interactions, and apply proven patterns across tasks.
+
+### Core Capabilities
+
+1. **Persistent Memory**: Store and retrieve information across sessions with 4-layer architecture
+2. **Pattern Application**: Leverage 58+ battle-tested workflows and decision frameworks
+3. **Multi-Agent Coordination**: Coordinate work between agents to prevent conflicts
+4. **CI/CD Optimization**: Reduce pipeline costs by 50-80% through intelligent batching
+5. **MCP Integration**: Achieve 98% token reduction via meta-tool routing
+
+### Quick Start
+
+```bash
+# Install UAP CLI
+npm install -g universal-agent-protocol
+
+# Initialize in your project
+uap init
+
+# Create a tracked task
+uap task create "Implement feature X"
+
+# Use worktree for safe development
+uap worktree create feature-name
+cd .worktrees/NNN-feature-name/
+# Make changes...
+uap worktree pr <id>
+```
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm or yarn
+- Optional: Docker (for Qdrant semantic search)
+
+---
 
 ## Architecture
 
-- [System Analysis](architecture/SYSTEM_ANALYSIS.md) -- Complete UAP feature analysis and architecture
-- [Multi-Model Architecture](architecture/MULTI_MODEL.md) -- Planner/executor two-tier design
-- [UAP Protocol](architecture/UAP_PROTOCOL.md) -- Protocol specification and compliance requirements
-- [UAP Compliance](architecture/UAP_COMPLIANCE.md) -- Protocol enforcement plan
-- [Strict Droids](architecture/UAP_STRICT_DROIDS.md) -- JSON schema validation for droid definitions
+### System Overview
+
+UAP implements a **4-layer memory architecture** combined with multi-agent coordination:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AI Agent Layer                           │
+│            (Claude, Factory.AI, OpenCode, etc.)             │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                    UAP Core Layer                           │
+│  CLI │ Memory │ Coordination │ Task │ Deploy Batcher        │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                   │  CLI │ Memory │ Coordination │ Task │ Deploy Batcher        │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                    │  CLI │ Memory │ Coordination │ Task │ Deploy Batcher        │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────────────┐
+│                    Storage Layer                         │
+│  SQLite (Working) │ Qdrant (Semantic) │ Git (History)       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component | Purpose | Impact |
+|-----------|---------|--------|
+| **Memory System** | 4-layer persistent context | 10x retention |
+| **Coordination** | Multi-agent sync via SQLite | Zero conflicts |
+| **Task Management** | Structured workflow tracking | Full lifecycle |
+| **Deploy Batcher** | CI/CD optimization | 50-80% savings |
+| **MCP Router** | Meta-tool routing | 98% token reduction |
+| **Worktrees** | Safe isolated development | No main branch pollution |
+
+---
 
 ## Reference
 
-- [API Reference](reference/API_REFERENCE.md) -- CLI commands, DB schema, API endpoints
-- [CLI Reference](reference/UAP_CLI_REFERENCE.md) -- Full CLI command reference (25 commands, 109 subcommands)
-- [Feature Inventory](reference/FEATURES.md) -- Complete feature status and implementation details
-- [Harness Matrix](reference/HARNESS-MATRIX.md) -- Per-harness integration details
+### CLI Commands
+
+#### Task Management
+
+```bash
+# Create and track tasks
+uap task create "Fix bug" --priority high
+uap task list --active
+uap task complete --reason "Fixed"
+```
+
+#### Memory Operations
+
+```bash
+# Store and query memories
+uap memory store "Best practice: validate inputs"
+uap memory query "authentication" --top-k 5
+uap memory status
+```
+
+#### Worktree Workflow
+
+```bash
+# Safe isolated development
+uap worktree create feature-name
+cd .worktrees/NNN-feature-name/
+g changes...
+uap worktree pr <id>
+uap worktree cleanup <id>  # After merge
+```
+
+#### Compliance
+
+```bash
+# Verify protocol compliance
+uap compliance check
+uap hooks install all
+```
+
+### Database Schema
+
+UAP uses SQLite for structured data and Qdrant for semantic search:
+
+**SQLite Tables:**
+- `memories` - Short-term working memory (50 entries)
+- `session_memories` - Current session state
+- `entities/relationships` - Knowledge graph
+- `agent_registry` - Multi-agent coordination
+- `deploy_queue` - CI/CD batching queue
+
+**Qdrant Collections:**
+- `agent_memory` - Semantic embeddings (384-dim vectors)
+- `agent_patterns` - Pattern library indexing
+
+---
 
 ## Deployment
 
-- [Deployment Guide](deployment/DEPLOYMENT.md) -- Model providers, IaC, CI/CD pipelines
-- [Deployment Strategies](deployment/DEPLOYMENT_STRATEGIES.md) -- Window bucketing, batch processing
-- [Deploy Batching](deployment/DEPLOY_BATCHING.md) -- Batch windows and bucketing system
-- [Deploy Batcher Analysis](deployment/DEPLOY_BATCHER_ANALYSIS.md) -- DeployBatcher architecture
-- [Deploy Bucketing Analysis](deployment/DEPLOY_BUCKETING_ANALYSIS.md) -- Bucketing capability report
-- [Qwen3.5 / llama.cpp](deployment/QWEN35_LLAMA_CPP.md) -- Local LLM deployment with LoRA fine-tuning
+### Production Setup
+
+```bash
+# Start Qdrant for semantic search
+cd agents && docker-compose up -d
+
+# Install hooks
+uap hooks install all
+
+# Verify setup
+uap task ready
+```
 
-## Integrations
+### CI/CD Integration
 
-- [MCP Router](integrations/MCP_ROUTER_SETUP.md) -- 98% token reduction via meta-tool routing
-- [RTK Integration](integrations/RTK_INTEGRATION.md) -- Rust Token Killer CLI proxy
+UAP integrates with GitHub Actions via the DeployBatcher:
+
+```yaml
+name: UAP CI
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run UAP benchmarks
+        run: npm run benchmark:full
+```
+
+### Model Providers
+
+| Provider | Use Case | Configuration |
+|----------|----------|---------------|
+| **Qwen3.5** | General tasks | Default, cost-effective |
+| **Claude Opus** | Complex reasoning | High-accuracy scenarios |
+| **GPT-4** | Analysis tasks | Code generation |
+| **Local (llama.cpp)** | Privacy-focused | Self-hosted deployments |
+
+---
 
 ## Benchmarks
 
-- [Validation Plan](benchmarks/VALIDATION_PLAN.md) -- Benchmark methodology and test cases
-- [Validation Results](benchmarks/VALIDATION_RESULTS.md) -- Benchmark results
-- [Speculative Decoding Journey (2026-03)](benchmarks/SPECULATIVE_DECODING_JOURNEY_2026-03.md) -- End-to-end tuning, fixes, and soak outcomes
-- [Token Optimization](benchmarks/TOKEN_OPTIMIZATION.md) -- Per-feature token savings analysis
-- [Accuracy Analysis](benchmarks/ACCURACY_ANALYSIS.md) -- Internal vs Terminal-Bench comparison
+### Performance Summary
+
+| Metric | Baseline | UAP v1.18 | Improvement |
+|--------|----------|-----------|-------------|
+| **Success Rate** | 75% | **100%** | +25pp |
+| **Tokens/Task** | 52K | **23.4K** | -55% |
+| **Time/Task** | 45s | **32s** | -29% |
+| **Error Rate** | 12% | **0%** | -100% |
 
-## Blog
+### Full Benchmark Suite
 
-- [Speculative Decoding Production Playbook](blog/SPECULATIVE_DECODING_PRODUCTION_PLAYBOOK.md) -- Long-form narrative on throughput gains, failure modes, and stable profiles
+Run the complete benchmark suite:
 
-## PR Templates
+```bash
+# Quick test (10 tasks)
+npm run benchmark:short
 
-- [Speculative Docs PR Template](pr/PR_SPECULATIVE_DOCS_TEMPLATE.md) -- Ready-to-submit PR copy, checklist, and reviewer guidance
+# Full validation (14 tasks)
+npm run benchmark:full
 
-## Research
+# Overnight extended run
+npm run benchmark:overnight
+```
 
-- [Memory Systems Comparison](research/MEMORY_SYSTEMS_COMPARISON.md) -- MemGPT, LangGraph, Mem0, A-MEM analysis
-- [Behavioral Patterns](research/BEHAVIORAL_PATTERNS.md) -- Pattern analysis from Terminal-Bench
-- [Terminal-Bench Learnings](research/TERMINAL_BENCH_LEARNINGS.md) -- Universal agent patterns discovered
-- [Performance Analysis](research/PERFORMANCE_ANALYSIS_2026-01-18.md) -- UAP vs baseline benchmarking
-- [Pattern Analysis](research/PATTERN_ANALYSIS_2026-01-18.md) -- Deep failure study
-- [Performance Test Plan](research/PERFORMANCE_TEST_PLAN.md) -- Vanilla vs UAP-enhanced test plan
-- [Domain Strategies](research/DOMAIN_STRATEGIES.md) -- CoreWars, specialized task guides
+Results are documented in [COMPREHENSIVE_BENCHMARKS.md](benchmarks/COMPREHENSIVE_BENCHMARKS.md).
+
+---
 
 ## Operations
 
-- [Troubleshooting](operations/TROUBLESHOOTING.md) -- Common issues, recovery procedures, debugging
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `Qdrant connection failed` | `cd agents && docker-compose up -d` |
+| `Worktree already exists` | `uap worktree cleanup <id>` |
+| `Memory DB locked` | Close other processes using the DB |
+| `Compliance check failed` | Review specific gate failure in output |
+
+### Debug Mode
+
+```bash
+# Enable verbose logging
+export UAP_VERBOSE=true
+
+# Check memory queries
+uap task ready --verbose
+
+# Inspect database directly
+sqlite3 ./agents/data/memory/short_term.db ".tables"
+```
+
+---
+
+## Contributing
+
+### Development Setup
+
+```bash
+git clone https://github.com/DammianMiller/universal-agent-protocol.git
+cd universal-agent-protocol
+npm install
+npm run build
+npm test
+```
+
+### Worktree Workflow
+
+All changes must be made in a worktree:
+
+```bash
+# Create worktree for your feature
+uap worktree create feature-description
+
+# Make changes, commit, create PR
+cd .worktrees/NNN-feature-description/
+git add -A && git commit -m "feat: description"
+uap worktree pr <id>
+
+# After merge, cleanup is mandatory
+uap worktree cleanup <id>
+```
+
+---
+
+## License
+
+MIT License - See [LICENSE](../LICENSE) file
 
 ---
 
-## Archive
+<div align="center">
+
+**Maintained by:** UAP Team  
+**Repository:** https://github.com/DammianMiller/universal-agent-protocol  
+**Issues:** https://github.com/DammianMiller/universal-agent-protocol/issues
 
-Historical documents preserved for reference in [archive/](archive/).
+</div>