@miller-tech/uap 1.40.0 → 1.41.0

package/docs/INDEX.md

@@ -1,306 +1,68 @@
 # UAP Documentation
 
-> **Version:** 1.18.0  
-> **Last Updated:** 2026-03-28  
-> **License:** MIT
+The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.40.0) — a layer that gives AI coding agents memory, judgment, and the discipline to finish the job.
 
----
-
-## 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 |
+New here? Start with the [project README](../README.md), then [Getting Started](getting-started/).
 
 ---
 
-## Getting Started
-
-### 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)
-
----
+## Getting started
+
+| Doc | What it covers |
+|---|---|
+| [Installation](getting-started/INSTALLATION.md) | Prerequisites, `npm install -g @miller-tech/uap`, what `uap setup` does, per-harness hook install |
+| [Quickstart](getting-started/QUICKSTART.md) | 5-minute path: setup → memory → `uap deliver` → dashboard |
+| [Configuration](getting-started/CONFIGURATION.md) | `.uap.json`, environment variables, Qdrant, model profiles |
+
+## Guides
+
+| Doc | What it covers |
+|---|---|
+| [**`uap deliver`**](guides/DELIVER.md) | The delivery harness — convergence loop to verified completion ⭐ |
+| [Memory](guides/MEMORY.md) | The 4-tier memory system, write-gates, semantic recall |
+| [MCP Router](guides/MCP_ROUTER.md) | Token-optimizing tool proxy + FTS5 output compression |
+| [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) | Branch-per-feature isolation, auto-PR, enforcement |
+| [Policies](guides/POLICIES.md) | Executable policy gates that block non-compliant tool calls |
+| [Multi-Model Routing](guides/MULTI_MODEL.md) | Plan → route → execute across 7 model profiles |
+| [Droids & Skills](guides/DROIDS_AND_SKILLS.md) | 38 expert droids, 32 skills, the expert router |
+| [Deploy Batching](guides/DEPLOY_BATCHING.md) | Conflict-free batched git/deploy actions |
+| [Coordination](guides/COORDINATION.md) | Multi-agent overlap detection |
+| [Local Models](guides/LOCAL_MODELS.md) | Running agents against local llama.cpp / Qwen models |
 
 ## 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 |
-| **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 |
-
----
+| Doc | What it covers |
+|---|---|
+| [Overview](architecture/OVERVIEW.md) | System architecture, subsystems, tool-call flow |
+| [Protocol](architecture/PROTOCOL.md) | The harness↔UAP contract, hook lifecycle, decision loop |
 
 ## 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/
-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
-
-### Production Setup
-
-```bash
-# Start Qdrant for semantic search
-cd agents && docker-compose up -d
-
-# Install hooks
-uap hooks install all
+| Doc | What it covers |
+|---|---|
+| [CLI](reference/CLI.md) | Every `uap` command and flag |
+| [API](reference/API.md) | Programmatic API surface |
+| [Features](reference/FEATURES.md) | Full feature catalog by subsystem |
+| [Patterns](reference/PATTERNS.md) | The 23 Terminal-Bench patterns |
+| [Platforms](reference/PLATFORMS.md) | The 9 supported harnesses + support matrix |
+| [Configuration](reference/CONFIGURATION.md) | All config files and env vars |
+| [Database Schema](reference/DATABASE_SCHEMA.md) | SQLite databases + Qdrant collections |
 
-# Verify setup
-uap task ready
-```
+## Integrations
 
-### 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 |
-
----
+| Doc | What it covers |
+|---|---|
+| [MCP Router](integrations/MCP_ROUTER.md) | Setting up the MCP router across harnesses |
+| [RTK](integrations/RTK.md) | Rust Token Killer integration |
 
 ## 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"
-```
-
----
+| Doc | What it covers |
+|---|---|
+| [Validation Results](benchmarks/VALIDATION_RESULTS.md) | Terminal-Bench 2.0 results (−49.7% tokens, +33pp success) |
+| [Token Optimization](benchmarks/TOKEN_OPTIMIZATION.md) | Where the token savings come from |
+| [Accuracy Analysis](benchmarks/ACCURACY_ANALYSIS.md) | Success-rate and error analysis |
 
 ## 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
-
-</div>
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for dev setup, the worktree workflow, completion gates, and PR conventions.