@miller-tech/uap 1.39.0 → 1.40.1

package/docs/getting-started/OVERVIEW.md

@@ -1,324 +0,0 @@
-# UAP - Universal Agent Protocol
-
-> **Version:** 1.18.0  
-> **Last Updated:** 2026-03-28  
-> **License: A persistent memory system for autonomous AI agents
-
-UAP (Universal Agent Protocol) provides a standardized framework for AI agents to maintain persistent context, learn from past interactions, and apply proven patterns across tasks.
-
-## What is UAP?
-
-UAP is an open protocol that enables AI agents to:
-
-1. **Remember Context**: Store and retrieve relevant information across sessions
-2. **Apply Patterns**: Leverage battle-tested workflows and decision frameworks
-3. **Maintain State**: Track progress, failures, and successes over time
-
----
-
-## Core Components
-
-### 1. Memory System (4-Layer Architecture)
-
-| Layer | Type                        | Purpose                             | Speed |
-| ----- | --------------------------- | ----------------------------------- | -----
-| L1    | SQLite (`memories`)         | Working context, recent decisions   | <1ms  |
-| L2    | SQLite (`session_memories`) | Current task session state          | <5ms  |
-| L3    | Qdrant (vector DB)          | Semantic search across all memories | ~50ms |
-| L4    | SQLite (entities/rels)      | Knowledge graph of relationships    | <20ms |
-
-### 2. CLAUDE.md Protocol
-
-Every UAP-enabled project includes a `CLAUDE.md` file that defines:
-- **Directive Hierarchy**: Which rules take precedence
-- **Decision Loop**: Standard workflow for any task
-- **Patterns**: 58+ battle-tested patterns for common scenarios
-- **Skills**: Domain-specific expertise (chess, compression, debugging)
-- **Completion Gates**: Mandatory checks before declaring success
-
-### 3. CLI Tools
-
-```bash
-# Initialize UAP in a project
-uap init
-
-# Create a tracked task with memory
-uap task create --title "Fix login bug" --type bug
-
-# Query semantic memory
-uap memory query "authentication errors"
-
-# Manage worktrees for parallel development
-uap worktree create fix-auth-issue
-```
-
-### 4. Worktree Workflow
-
-UAP enforces a **worktree-only** workflow to prevent accidental changes to main branches:
-# Create worktree for any change (even single file)
-uap worktree create bugfix-description
-
-# Make changes, commit, create PR
-cd .worktrees/NNN-bash: git add -A && git commit -m "type: description"
-uap worktree pr 123
-
-# After merge, cleanup is mandatory
-uap worktree cleanup 123
-```
-
----
-
-## How It Works
-
-### Task Execution Flow
-
-```
-1. CLASSIFY → Is this complex? Does it need memory?
-2. PROTECT   → Backup critical files (configs, DBs)
-3. MEMORY    → Query relevant context + past failures
-4. SKILLS    → Load domain-specific patterns if needed
-5. WORK      → Implement using worktree
-6. REVIEW    → Self-review diff before testing
-7. TEST      → Run verifier/tests minimum 3 times
-8. LEARN     → Store outcome in memory for future tasks
-```
-
-### Memory Retrieval
-
-When starting a task, UAP automatically:
-
-1. **Classifies** the task type (coding, debugging, research, etc.)
-2. **Queries** L1/L2 memory for recent relevant decisions
-3. **Searches** L3 semantic memory for similar past tasks
-4. **Loads** L4 knowledge graph for entity relationships
-5. **Applies** patterns based on classification confidence
-
-### Pattern Router
-
-UAP includes 58+ patterns for common scenarios:
-
-| Pattern ID | Trigger                 | Action                              |
-| ---------- | ----------------------- | ----------------------------------- |
-| P3         | Modifies config/DB      | `cp file file.bak` first            |
-| P12        | Creates files           | `ls -la` verify all outputs exist   |
-| P13        | Tests partial pass      | Fix specific failure, re-run        |
-| P26        | Same error twice        | Change approach completely          |
-| P32        | CLI tool                | Test `./script` not `python script` |
-| P37        | Output format specified | Diff output schema vs expectations  |
-
-### Prerequisites
-
-- Node.js >= 18.0.0
-- npm or yarn
-- Optional: Docker (for Qdrant semantic search)
-
-### Quick Start
-
-```bash
-# Install globally
-npm install -g universal-agent-protocol
-
-# Initialize in your project
-uap init
-
-# Run the interactive setup
-npx universal-agent-protocol init --interactive
-```
-
-### With Qdrant (Recommended for Full Features)
-
-```bash
-cd agents && docker-compose up -d
-```
-
----
-
-## Configuration
-
-### `.uap.json` - Project Settings
-
-```json
-{
-  "project": {
-    "name": "my-project",
-    "description": "Project with UAP memory"
-  },
-  "memory": {
-    "shortTerm": {
-      "enabled": true,
-      "path": "./agents/data/memory/short_term.db"
-    },
-    "longTerm": {
-      "enabled": true,
-      "provider": "qdrant",
-      "endpoint": "localhost:6333"
-    }
-  },
-  "worktrees": {
-    "enabled": true,
-    "directory": ".worktrees"
-  }
-}
-```
-
----
-
-## Best Practices
-
-### DO ✅
-
-- Use `uap task create` for all work items
-- Always use worktrees (never commit to main directly)
-- Run verifier/tests minimum 3 times before declaring done
-- Store outcomes in memory after completing tasks
-- Load relevant skills for domain-specific tasks
-
-### DON'T ❌
-
-- Commit directly to main/develop branches
-- Skip backup steps when modifying critical files
-- Declare success without running tests multiple times
-- Ignore pattern recommendations (they prevent bugs)
-- Leave merged worktrees uncleand
-
----
-
-## Protocol Compliance
-
-UAP enforces **completion gates** before any task is considered done:
-
-```
-[x] If decoder provided: round-trip passes (BLOCKING)
-[x] Outputs verified: ls -la shows all files exist
-[x] Schema diffed against test expectations
-[x] Tests: X/Y pass (must be 100%, run 3+ times)
-[x] CLI tools tested as ./script not python script
-[x] If recovery: artifacts copied before read operation
-```
-
-Run compliance check:
-
-```bash
-npm run verify-uap
-# or
-uap compliance check
-```
-
----
-
-## Integration Points
-
-### Claude Code
-
-UAP integrates with Anthropic's Claude Code via session hooks:
-
-```bash
-uap hooks install
-```
-
-This adds automatic memory queries at task start and outcome storage on completion.
-
-### Factory.AI
-
-UAP provides skills for Factory.AI droids:
-
-- `@Skill:chess-engine.md` - Chess pattern matching
-- `@Skill:compression.md` - Information-theoretic limits
-- `@Skill:adversarial.md` - Security vulnerability analysis
-- `@Skill:git-forensics.md` - Repository recovery
-
-### Multi-Agent Coordination
-
-UAP detects overlapping work between agents via:
-
-```bash
-uap coordination check --agents agent1,agent2,agent3
-```
-
-This prevents duplicate effort and identifies collaboration opportunities.
-
----
-
-## API Reference
-
-### Memory Operations
-
-```typescript
-// Store a memory
-await uap.memory.store('Always validate CSRF tokens in auth flows');
-
-// Query memories
-const results = await uap.memory.query('authentication security', {
-  topK: 5,
-  scoreThreshold: 0.35,
-});
-
-// Clear session memory
-await uap.memory.clearSession();
-```
-
-### Task Management
-
-```typescript
-// Create a task
-const task = await uap.task.create({
-  title: 'Implement rate limiting',
-  type: 'feature',
-  priority: 'high',
-});
-
-// Update task status
-await uap.task.update(task.id, { status: 'in_progress' });	enrichedTask = await uap.task.get(task.id, { includeMemory: true });
-gleshooting
-
-### Common Issues
-
-| Error                      | Solution                                          |
-| -------------------------- | ------------------------------------------------- |
-| `ModuleNotFoundError`      | Run `npm install` after cloning                   |
-| `Qdrant connection failed` | Start Docker: `cd agents && docker-compose up -d` |
-| `Worktree already exists`  | Use `uap worktree cleanup <id>` first             |
-| `Memory DB locked`         | Close other processes using the DB                |
-| `Compliance check failed`  | Review specific gate failure in output            |
-# 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
-
-UAP is open source. Contributions welcome:
-
-1. Fork the repository
-2. Create a worktree: `uap worktree create feature-name`
-3. Make changes and run tests: `npm test`
-4. Submit PR via `uap worktree pr <id>`
-
-### Development Setup
-
-```bash
-git clone https://github.com/DammianMiller/universal-agent-protocol.git
-cd universal-agent-protocol
-npm install
-npm run build
-npm test
-```
-
----
-
-## License
-
-MIT License - See [LICENSE](../LICENSE) file
-
-**Maintained By**: UAP Team  
-**Repository**: https://github.com/DammianMiller/universal-agent-protocol  
-**Issues**: DammianMiller/universal-agent-protocol/issues
-
-</div>

package/docs/getting-started/SETUP.md

@@ -1,377 +0,0 @@
-# UAP Setup Guide
-
-> **Version:** 1.18.0  
-> **Last Updated:** 2026-03-28  
-> **Status:** ✅ Production Ready
-
----
-
-## Quick Start
-
-```bash
-# Install UAP CLI
-npm install -g universal-agent-protocol
-
-# Run comprehensive setup
-npm run setup
-
-# Initialize in your project
-uap init
-```
-
-## Dependencies
-
-### Required
-
-- **Node.js >= 18.0.0** - Runtime environment
-- **git** - Version control (required for git hooks)
-- **npx** - Runs CLI tools (included with npm)
-
-### Optional but Recommended
-
-- **Docker** - Enables local Qdrant for semantic search
-- **Python 3** - Enables Pattern RAG indexing
-- **pre-commit** - Provides advanced git hooks
-
-## Installation by Platform
-
-### macOS
-
-```bash
-# Install all dependencies
-brew install node@18 git python docker
-
-# Install UAP
-npm install -g universal-agent-protocol
-
-# Run setup
-npm run setup
-```
-
-### Ubuntu/Debian
-
-```bash
-# Install Node.js 20.x
-curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
-git python3 docker.io
-
-# Install UAP
-npm install -g universal-agent-protocol
-
-# Run setup
-npm run setup
-```
-
-### Windows
-
-```powershell
-# Install all dependencies using winget
-winget install OpenJS.NodeJS.LTS
-winget install Git.Git
-winget install Python.Python.3.12
-winget install Docker.DockerDesktop
-
-# Install UAP
-npm install -g universal-agent-protocol
-
-# Run setup
-npm run setup
-```
-
-## Git Hooks
-
-The setup script automatically configures the following git hooks:
-
-### Pre-commit Hook
-
-- Checks for secrets in committed files
-- Runs linter with zero warnings allowed
-- Prevents accidental commits of sensitive data
-
-### Commit-msg Hook
-
-- Validates conventional commits format
-- Suggests proper format if invalid
-- Allows override with confirmation
-
-### Pre-push Hook
-
-- Runs all tests before pushing
-- Prevents pushing broken code
-
-## Environment Setup
-
-### Required Environment Variables
-
-None required for basic functionality.
-
-### Optional Environment Variables
-
-```bash
-# GitHub token for GitHub memory backend
-export GITHUB_TOKEN=your_token_here
-
-# Qdrant Cloud credentials for semantic search
-export QDRANT_API_KEY=your_key_here
-export QDRANT_URL=your_url_here
-
-# Local Qdrant (if running Docker)
-export QDRANT_URL=http://localhost:6333
-```
-
-## Verification
-
-After setup, verify everything is working:
-
-```bash
-# Check UAP CLI
-uap --version
-
-# Check memory status
-uap memory status
-
-# Run tests
-npm test
-
-# Check git hooks
-ls -la .git/hooks/
-```
-
-## Troubleshooting
-
-### Git hooks not running
-
-```bash
-# Make hooks executable
-chmod +x .git/hooks/*
-
-# Verify hooks are active
-ls -la .git/hooks/ | grep -v sample
-```
-
-### TypeScript build fails
-
-```bash
-# Clear cache and rebuild
-rm -rf dist node_modules/.cache
-npm run build
-```
-
-### npm install fails
-
-```bash
-# Clear npm cache
-npm cache clean --force
-
-# Reinstall
-rm -rf node_modules package-lock.json
-npm install
-```
-
-### Docker not available
-
-No problem! UAP will use cloud backends. You can add Docker later:
-# Install Docker
-curl -fsSL https://get.docker.com | sh
-
-# Start Qdrant
-uap memory start
-```
-
-## Next Steps
-
-1. **Review the generated CLAUDE.md** - Customize as needed
-2. **Set up cloud backends** - Add your API keys
-3. **Start working** - Your AI assistant will follow the workflows automatically
-
-## Uninstallation
-
-```bash
-# Remove global package
-npm uninstall -g universal-agent-protocol
-
-# Remove from your project
-rm -rf .uap.json CLAUDE.md agents/ .worktrees/
-
-**Documentation**: [GitHub README](https://github.com/DammianMiller/universal-agent-protocol)
-
-**Issues:** https://github.com/DammianMiller/universal-agent-protocol/issues
-
-**Last Updated:** 2026-03-28  
-> **Status:** ✅ Production Ready
-
----
-
-## Quick Setup
-
-```bash
-# Install UAP CLI
-npm install -g universal-agent-protocol
-
-# Run comprehensive setup
-npm run setup
-
-# Initialize in your project
-uap init
-```
-
-## Dependencies
-
-### Required
-
-- **Node.js >= 18.0.0** - Runtime environment
-- **npm, yarn)
-- **npm** - Package manager
-- **git** - Version control (required for git hooks)
-- **npx** - Runs CLI tools (included with npm)
-
-### Optional but Recommended
-
-- **Docker** - Enables local Qdrant for semantic search
-- **Python 3** - Enables Pattern RAG indexing
-- **pre-commit** - Provides advanced git hooks
-
-## Installation by Platform
-
-### macOS
-
-```bash
-# Install all dependencies
-brew install node@18 git python docker
-
-# Install UAP
-npm install -g universal-agent-protocol
-
-# Run setup
-npm run setup
-```
-
-### Pre-commit Hook
-# Check for secrets in committed files
-# Runs linter with zero warnings allowed
-# Prevents accidental commits of sensitive data
-
-### Commit-msg Hook
-
-- Validates conventional commits format
-- Suggests proper format if invalid
-- Allows override with confirmation
-
-### Pre-push Hook
-
-- Runs all tests before pushing
-- Prevents pushing broken code
-
-## Environment Setup
-
-### Required Environment Variables
-
-None required for basic functionality.
-
-### Optional Environment Variables
-
-```bash
-# GitHub token for GitHub memory backend
-export GITHUB_TOKEN=your_token_here
-
-# Qdrant Cloud credentials for semantic search
-export QDRANT_API_KEY=your_key_here
-export QDRANT_URL=your_url_here
-
-# Local Qdrant (if running Docker)
-export QDRANT_URL=http://localhost:6333
-```
-
-## Verification
-
-After setup, verify everything is working:
-
-```bash
-# Check UAP CLI
-uap --version
-
-# Check memory status
-uap memory status
-
-# Run tests
-npm test
-
-# Check git hooks
-ls -la .git/hooks/
-```
-
-## Troubleshooting
-
-### Git hooks not running
-
-```bash
-# Make hooks executable
-chmod +x .git/hooks/*
-
-# Verify hooks are active
-ls -la .git/hooks/ | grep -v sample
-```
-
-### TypeScript build fails
-
-```bash
-# Clear cache and rebuild
-rm -rf dist node_modules/.cache
-npm run build
-```
-
-### npm install fails
-
-```bash
-# Clear npm cache
-npm cache clean --force
-
-# Reinstall
-rm -rf node_modules package-lock.json
-npm install
-```
-
-### Docker not available
-
-No problem! UAP will use cloud backends. You can add Docker later:
-
-# Install Docker
-curl -fsSL https://get.docker.com | sh
-
-# Start Qdrant
-uap memory start
-```
-
-## Next Steps
-
-1. **Review the generated CLAUDE.md** - Customize as needed
-2. **Set up cloud backends** - Add your API keys
-3. **Start working** - Your AI assistant will follow the workflows automatically
-
-## Uninstallation
-
-```bash
-# Remove global package
-npm uninstall -g universal-agent-protocol
-
-# Remove from your project
-rm -rf .uap.json CLAUDE.md agents/ .worktrees/
-```
-
-**Documentation**: [GitHub README](https://github.com/DammianMiller/universal-agent-protocol)
-
-**Issues:** https://github.com/DammianMiller/universal-agent-protocol/issues
-
-## Support
-
-- **Documentation**: [GitHub README](https://github.com/DammianMiller/universal-agent-protocol)
-- **Issues:** https://github.com/DammianMiller/universal-agent-protocol/issues
-
-**Documentation**: [GitHub README](https://github.com/DammianMiller/universal-agent-protocol)
-
-- **Issues:** https://github.com/DammianMiller/universal-agent-protocol/issues
-
-## Support
-
-- **Documentation**: [GitHub README](https://github.com/DammianMiller/universal-agent-protocol)
-- **Issues:** https://github.com/DammianMiller/universal-agent-protocol/issues