@miller-tech/uap 1.39.0 → 1.40.1

package/docs/DOCUMENTATION_AUDIT_REPORT.md

@@ -1,131 +0,0 @@
-# UAP Documentation Audit Report
-
-The Universal Agent Protocol (UAP) project has comprehensive foundational documentation but needs improvements in:
-
-- Inline JSDoc comments (140+ exports missing docs)
-- Module-level README files
-- Database schema accuracy
-- CLI command completeness
-
-## Current State Assessment:
-
-- Comprehensive README.md (542 lines) with feature overview
-- Extensive CLI reference documentation (620 lines)
-- Architecture documentation with Mermaid diagrams
-- Benchmark results thoroughly documented
-
-## Documentation Gaps by Priority:
-
-### CRITICAL (Must-Have):
-
-1. **Inline JSDoc for Public APIs** - Missing from src/index.ts exports
-2. **CLI Command Completeness** - Dashboard (13 views), model commands (8 subcommands), policy commands (15 subcommands) under-documented
-3. **Configuration Schema Documentation** - .uap.json schema incomplete, missing validation rules
-4. **Database Schema Accuracy** - API_REFERENCE.md shows outdated table structures
-5. **Hook System Implementation Details** - Pre-edit build gate enforcement mechanism not explained
-
-### HIGH PRIORITY (Should-Have):
-
-6. **Memory System Architecture Diagram** - Current diagram has placeholder text
-7. **Pattern Library Reference** - All 23+ patterns need detailed descriptions
-8. **Multi-Agent Coordination Flow** - Heartbeat mechanism details missing
-9. **Policy Enforcement Workflow** - Policy evaluation order not documented
-10. **Testing and Quality Gates** - Test coverage requirements (50% threshold) undocumented
-
-### MEDIUM PRIORITY (Nice-to-Have):
-
-11. **Benchmark Methodology** - Terminal-Bench adapter details
-12. **Deployment Guides** - Production Qdrant setup
-13. **Troubleshooting Matrix** - Error code reference
-14. **Integration Patterns** - RTK token compression details
-15. **Performance Optimization Guide** - Token budget management
-
-## Recommended Documentation Strategy: Hybrid Approach
-
-**Combine comprehensive README with inline JSDoc:**
-
-**Pros:**
-
-- Single source of truth in README for quick onboarding
-- IDE autocomplete via JSDoc for developers
-- Lower maintenance burden than separate docs site
-
-**Cons:**
-
-- README can become unwieldy (542+ lines)
-- Inline docs can drift from code if not maintained
-
-## Implementation Roadmap:
-
-### Phase 1: Critical Fixes (Weeks 1-2)
-
-| Task                               | Files                               | Effort  | Priority |
-| ---------------------------------- | ----------------------------------- | ------- | -------- |
-| Add JSDoc to src/index.ts exports  | src/index.ts                        | 8 hours | CRITICAL |
-| Update database schemas            | docs/reference/API_REFERENCE.md     | 4 hours | CRITICAL |
-| Update configuration schema        | README.md, docs/INDEX.md            | 3 hours | CRITICAL |
-| Complete CLI command documentation | docs/reference/UAP_CLI_REFERENCE.md | 6 hours | HIGH     |
-
-### Phase 2: Module Documentation (Weeks 3-4)
-
-| Task                              | Files                      | Effort  | Priority |
-| --------------------------------- | -------------------------- | ------- | -------- |
-| Create memory module README       | src/memory/README.md       | 4 hours | HIGH     |
-| Create coordination module README | src/coordination/README.md | 3 hours | HIGH     |
-| Create policies module README     | src/policies/README.md     | 3 hours | HIGH     |
-| Create models module README       | src/models/README.md       | 3 hours | MEDIUM   |
-
-### Phase 3: Advanced Documentation (Months 2-3)
-
-| Task                                   | Files                             | Effort  | Priority |
-| -------------------------------------- | --------------------------------- | ------- | -------- |
-| Generate API docs with TypeDoc         | docs/api/                         | 8 hours | MEDIUM   |
-| Create pattern library reference       | docs/reference/PATTERN_LIBRARY.md | 6 hours | HIGH     |
-| Add memory architecture diagram        | docs/INDEX.md                     | 2 hours | HIGH     |
-| Establish documentation review process | CONTRIBUTING.md                   | 3 hours | MEDIUM   |
-
-## Module-Level Documentation Analysis:
-
-### Source Code Structure (143 files):
-
-| Directory         | Files    | Documentation Status | Gaps                                                  |
-| ----------------- | -------- | -------------------- | ----------------------------------------------------- |
-| src/memory/       | 22 files | ⚠️ PARTIAL           | Predictive memory, context pruner, ambiguity detector |
-| src/models/       | 10 files | ⚠️ PARTIAL           | Unified router logic, execution profile loading       |
-| src/coordination/ | 6 files  | ⚠️ PARTIAL           | Capability router (18 types), adaptive patterns       |
-| src/cli/          | 27 files | ✅ GOOD              | Dashboard views, model commands need examples         |
-| src/utils/        | 10 files | ✅ GOOD              | Well-documented utilities                             |
-| src/policies/     | 8 files  | ⚠️ PARTIAL           | Policy gate middleware, Python enforcement tools      |
-| src/mcp-router/   | 10 files | ⚠️ PARTIAL           | Client pool management, session stats tracking        |
-| src/tasks/        | 7 files  | ⚠️ PARTIAL           | Event bus implementation, decoder gate mechanism      |
-| src/browser/      | 2 files  | ❌ MINIMAL           | Stealth techniques, error handling                    |
-| src/dashboard/    | 2 files  | ❌ MINIMAL           | Server and event-stream not tested                    |
-| src/telemetry/    | 0 tests  | ❌ MISSING           | Session telemetry untested                            |
-
-## Test Coverage Gaps:
-
-| Module              | Test Files | Tests | Coverage Status | Missing                                         |
-| ------------------- | ---------- | ----- | --------------- | ----------------------------------------------- |
-| Browser             | 1 file     | 4     | ❌ MINIMAL      | Stealth techniques, error handling, performance |
-| MCP Router          | 3 files    | 40+   | ⚠️ PARTIAL      | Client pool, session stats, tool execution      |
-| Dashboard           | 2 files    | ~10   | ❌ MINIMAL      | Server, event-stream, real-time updates         |
-| Telemetry           | 0 files    | 0     | ❌ MISSING      | Session tracking, model usage metrics           |
-| Benchmarks (agents) | 0 files    | 0     | ❌ MISSING      | Agent implementation tests                      |
-
-## Conclusion:
-
-The UAP project has **solid foundational documentation** with comprehensive CLI references and good architectural overviews. However, there are significant gaps that need addressing.
-
-### Top 5 Priorities:
-
-1. **Add JSDoc to src/index.ts** (2-3 hours) - Affects IDE autocomplete for all users
-2. **Update database schemas in API_REFERENCE.md** (4 hours) - Critical for developers
-3. **Create module-level READMEs** (12 hours total) - Improves code navigation
-4. **Complete CLI command documentation** (6 hours) - Helps power users
-5. **Document configuration schema** (3 hours) - Essential for setup
-
-### Recommended Strategy: Hybrid Approach
-
-Best balance of developer experience and maintenance burden.
-
-**Total Effort:** ~52 hours over 3 months

package/docs/GETTING_STARTED.md

@@ -1,288 +0,0 @@
-# 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)