@miller-tech/uap 1.43.1 → 1.43.3

package/docs/INDEX.md

@@ -18,6 +18,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 
 | Doc | What it covers |
 |---|---|
+| [**What UAP Does Automatically**](guides/AUTOMATIC.md) | Every feature in benefit / when-it-kicks-in terms — install once, it all self-applies ⭐ |
 | [**`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 |
@@ -28,6 +29,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 | [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 |
+| [Qwen3.6 on llama.cpp by VRAM](guides/QWEN36_LLAMACPP.md) | Tiered 8/12/16/24/32 GB setup; how `uap deliver` uplifts small local models |
 
 ## Architecture
 

package/docs/guides/AUTOMATIC.md

@@ -0,0 +1,92 @@
+# What UAP Does For You — Automatically
+
+> The whole point of UAP: **you install it once, and every feature applies itself
+> as you code.** You don't call commands or remember protocols. UAP watches the
+> coding agent's lifecycle (session start, every prompt, every tool call, every
+> stop) and injects the right help or enforces the right guardrail *at the moment
+> it's needed*.
+
+```bash
+npx @miller-tech/uap init       # one-time, per project
+# …that's it. Open your coding agent and everything below is live.
+```
+
+`init`/`setup` wire UAP into whichever agent you use — Claude Code, Cursor,
+OpenCode, Factory, VSCode, Codex — by installing lifecycle hooks and the MCP
+router. After that the features are **on by default and apply themselves as
+appropriate**. Nothing here needs to be invoked by hand.
+
+---
+
+## How to read this
+
+Two kinds of automatic behaviour, and they're deliberately different:
+
+- **Assist** (dynamic, *helps* you): surfaces the right context — experts,
+  skills, patterns, memories — by *injecting* it where the model will see it.
+  It's confidence-gated, so quiet on conversational turns and rich on real
+  coding tasks. It never blocks; worst case it stays silent.
+- **Enforce** (deterministic, *protects* you): hard guardrails that *block* a
+  tool call when it would violate a rule (edit outside a worktree, skip
+  delivery, run a dangerous command). Each has an escape hatch for the rare
+  sanctioned exception.
+
+For every feature below: **what it does for you**, and **when it kicks in**.
+
+---
+
+## Assist — the right help shows up on its own
+
+| Feature | What it does for you | When it kicks in |
+|---|---|---|
+| **Reactor** (dynamic routing) | On every prompt, surfaces the expert droids, skills, and enforcement patterns relevant to *this* task, so the agent works like it already knows the domain. | Every substantive prompt (`UserPromptSubmit` / per-message). Confidence-gated — silent on "thanks"/"merge it", rich on "fix the auth race condition". |
+| **Memory recall** | Pulls back the lessons, decisions, and gotchas you (or another agent) learned before, so mistakes aren't repeated and context survives across sessions. | Session start (recent + high-importance memories) and per-prompt semantic recall on the task text. |
+| **Pattern RAG** | Injects battle-tested execution patterns (Output-Existence, Decoder-First, Round-Trip verify, …) mined from Terminal-Bench, so the agent uses the approach that actually passes. | Per-prompt, matched to the task; full set retrievable on demand via Qdrant. |
+| **Expert droids** | Routes domain work (security, performance, data, testing, …) to a specialist persona instead of a generalist guess. | When the capability router matches the task's type/files — recommended automatically, with optional auto-spawn above a confidence threshold. |
+| **Skills** | Surfaces the right *procedure* (git-forensics, compression, SQLite-WAL recovery, polyglot, …) for the task at hand. | Per-prompt match against the task; top-N surfaced. |
+| **Model routing** | Picks the right model tier per step (plan with the strong model, execute with the fast one) instead of one model for everything. | On task classification, by complexity and role. |
+
+You don't ask for any of this. It appears in the agent's context the moment the
+task warrants it, and stays out of the way when it doesn't.
+
+---
+
+## Enforce — the guardrails that keep work safe and verified
+
+| Feature | What it does for you | When it kicks in |
+|---|---|---|
+| **Delivery enforcement** (`uap deliver`, **block by default**) | Routes substantive coding through the **convergence loop** — which iterates a model against your real gates (build, type-check, tests) until the change is *verified*, not just plausible. This is what **uplifts small local models well above their weight**: a 3B-active model that would flail on one shot succeeds when driven to green against the gates. | The moment the agent tries to edit a **source** file directly. Docs/configs/scripts/tests are exempt — only real implementation work is gated. Escape: `UAP_DELIVER_BYPASS=1`, or relax with `UAP_ENFORCE_DELIVERY=advisory`. |
+| **Worktree isolation** | Forces code changes into an isolated `.worktrees/NNN-slug/` branch so you never clobber your working tree and every change is a clean, reviewable branch with an auto-PR. | Any source edit outside a worktree is blocked (`PreToolUse`). |
+| **Policy / compliance gates** | Block non-compliant tool calls before they run — dangerous shell (force-push, `terraform apply`), edits that skip a schema diff, plan-before-read violations, etc. | `PreToolUse` on every Edit/Write/Bash/Task call. |
+| **Schema-diff gate** | Flags breaking API/contract changes so you diff-and-verify consumers before shipping them. | After editing a schema/contract file (`*.schema.ts`, `types.ts`, `.proto`, `.graphql`, …). |
+| **Completion gates** | Won't let the agent declare "done" until build/type-check/tests actually pass and a version bump happened. | On `Stop` (end of turn). |
+| **Coordination** | Detects when multiple agents would touch the same files and prevents them stepping on each other. | Session start (register) + work announcement before claiming a task. |
+| **rtk token-optimization** | Rewrites heavy CLI output (git/docker/npm/…) into compact form so the agent burns far fewer tokens reading command output. | Every wrapped CLI command. |
+| **Deploy batching** | Queues changes into conflict-free batched commits/deploys instead of racy one-off pushes. | On `uap deliver --deploy` success. |
+
+Each enforce-gate has a sanctioned escape hatch (an env var) for the rare case
+you genuinely need to bypass it — so the guardrail is firm, not a cage.
+
+---
+
+## Behind it all
+
+| Feature | What it does for you | When it kicks in |
+|---|---|---|
+| **MCP router** | Exposes a tiny meta-tool surface (`discover_tools`/`execute_tool`/`deliver`/`react`) instead of 150+ tools, cutting tool-schema tokens by ~98%. | Wired at install; used whenever the agent discovers/runs a tool. |
+| **HALO trace analysis** | Mines your execution traces for systemic failure modes (loops, stalls) so the harness gets better over time. | Session end / on demand (`uap harness analyze`). |
+| **4-tier memory** | Short-term (recent), long-term (semantic Qdrant), coordination, and patterns — the substrate the recall/pattern features draw from. | Continuously; written on significant decisions, read on recall. |
+
+---
+
+## The one-liner
+
+**Install UAP, then just code.** The assist layer makes your agent act like a
+domain expert with perfect recall; the enforce layer makes sure whatever it
+produces is isolated, verified, and safe — and it drives even small local models
+to *verified* results they couldn't reach in one shot. You never invoke any of
+it; it applies itself, in the right place, at the right time.
+
+See also: [`uap deliver`](DELIVER.md) · [Local Models](LOCAL_MODELS.md) ·
+[Droids & Skills](DROIDS_AND_SKILLS.md) · [Policies](POLICIES.md) ·
+the [Reactor design](../design/UAP_REACTOR.md).

package/docs/guides/LOCAL_MODELS.md

@@ -7,6 +7,11 @@ UAP can drive its coding/convergence loop against **local models** served by
 This keeps inference on your own hardware (zero per-token cost) and works with
 quantized open-weight models such as Qwen 3.x.
 
+> **Just want the recommended local setup?** See
+> [Qwen3.6 35B-A3B on llama.cpp, by VRAM tier](QWEN36_LLAMACPP.md) for
+> copy-paste launch commands for 8 / 12 / 16 / 24 / 32 GB GPUs, and how
+> `uap deliver` uplifts a small local model to *verified* results.
+
 There are two endpoint shapes involved, and it matters which client speaks
 which protocol:
 

package/docs/guides/QWEN36_LLAMACPP.md

@@ -0,0 +1,110 @@
+# Qwen3.6 35B-A3B on llama.cpp, by VRAM tier — with UAP
+
+This is the recommended local stack for UAP: **Qwen3.6 35B-A3B** (a Mixture-of-
+Experts model with only **~3B active parameters** per token) served by
+**llama.cpp**, driven by **UAP's automatic features** — above all `uap deliver`,
+which iterates the model against your real build/test gates until the change is
+*verified*. That convergence loop is what lets a small, cheap, local model
+**punch well above its weight**: one-shot it would flail; driven to green it
+delivers.
+
+Because the active footprint is ~3B, this model runs usefully even on modest
+GPUs by **offloading the (sparse, mostly-idle) expert tensors to system RAM**
+while keeping attention on the GPU. The knob for that is `--n-cpu-moe`.
+
+## Get the model
+
+A 4-bit quant is the sweet spot for coding (quality vs. size). The full weights
+are ~18–19 GB at IQ4_XS:
+
+```
+Qwen3.6-35B-A3B-UD-IQ4_XS.gguf        # ~18–19 GB on disk
+# (a *-MTP.gguf build adds multi-token prediction for faster decode — use it if you have it)
+```
+
+## The base llama-server command
+
+UAP speaks the OpenAI-compatible endpoint, so serve on `:8080/v1`. The flags
+below are the ones that matter; the per-tier table just changes `--n-cpu-moe`,
+`--ctx-size`, and the KV-cache type.
+
+```bash
+llama-server \
+  --model Qwen3.6-35B-A3B-UD-IQ4_XS.gguf \
+  --host 0.0.0.0 --port 8080 \
+  --gpu-layers 99 \              # put all layers on GPU; experts get pulled back by --n-cpu-moe
+  --n-cpu-moe   <PER TIER> \     # how many layers keep their MoE experts in CPU RAM
+  --ctx-size    <PER TIER> \
+  --cache-type-k <q4_0|q8_0> --cache-type-v <q4_0|q8_0> \   # quantize KV cache to save VRAM
+  --flash-attn on \             # faster + less VRAM
+  --jinja \                     # use the model's chat template (REQUIRED for tool calls)
+  --parallel 1
+```
+
+> **`--jinja` / the chat template is non-negotiable for agent use.** Qwen3.6
+> emits *native* OpenAI tool calls, but only when its chat template is active.
+> If tools silently never fire, that's the cause — run `uap tool-calls setup`
+> to install/repair the template, and `uap tool-calls status` to check.
+
+## VRAM tiers
+
+Values are **starting points** — exact `--n-cpu-moe` depends on your build and
+layer count. Rule of thumb: **raise `--n-cpu-moe` if you OOM, lower it for more
+speed.** "System RAM" is what the offloaded experts need *in addition* to the
+GPU.
+
+| VRAM | `--n-cpu-moe` | `--ctx-size` | KV cache | System RAM | What to expect |
+|---|---|---|---|---|---|
+| **8 GB** | `99` (all experts → CPU) | `8192` | `q4_0` | ≥ 32 GB | Attention on GPU, all experts on CPU. Decode is CPU-bandwidth-bound (a few tok/s) — slow but *real*. `uap deliver` makes it productive by driving to verified completion instead of needing a strong one-shot. |
+| **12 GB** | `~36` | `16384` | `q4_0` | ≥ 32 GB | Keep ~the top experts on GPU, rest on CPU. Noticeably faster than 8 GB. |
+| **16 GB** | `~24` | `24576` | `q4_0` | ≥ 24 GB | Roughly half the experts on GPU. Comfortable for most coding tasks. |
+| **24 GB** | *omit* (full model on GPU) | `32768`–`65536` | `q8_0` | 16 GB | **Sweet spot** (RTX 3090/4090). Weights + KV fit on-GPU; use `q8_0` KV for quality, `q4_0` if you want more context. Add `--flash-attn on`. |
+| **32 GB** | *omit* | `131072` | `q8_0`/`f16` | 16 GB | Full model + large context. Add `--parallel 2–4` for concurrent sessions, bump `--batch-size`/`--ubatch-size`. |
+
+Speed extras (any tier): `--flash-attn on` (always), and if your build supports
+it, **self-speculation / MTP** (the `*-MTP.gguf` model, or `--draft-*` flags with
+a tiny draft model) for materially faster decode.
+
+## Point UAP at it
+
+```bash
+# 1) Tell UAP where the model lives (OpenAI-compatible endpoint)
+export UAP_INFERENCE_ENDPOINT="http://localhost:8080/v1"
+#    (or set the endpoint on the model preset in .uap.json / src/models/types.ts)
+
+# 2) Make sure tool calls work
+uap tool-calls setup        # install the chat template + helpers
+uap tool-calls status       # verify
+
+# 3) That's it — code as normal. Everything is automatic from here.
+```
+
+Once installed, **you don't run `uap deliver` by hand** — delivery enforcement
+is on by default, so when your agent goes to implement something it's routed
+through the convergence loop automatically (see
+[What UAP Does For You, Automatically](AUTOMATIC.md)). If you *want* to drive a
+task explicitly:
+
+```bash
+uap deliver "implement a token-bucket rate limiter with tests"
+```
+
+## Why this punches above its weight
+
+A 3B-active model rarely nails a non-trivial change in one shot. UAP changes the
+game without changing the model:
+
+- **`uap deliver`** loops execute → run-the-gates → fix → re-run until build,
+  type-check, and tests all pass — turning "plausible" into "verified".
+- **Pattern RAG + expert routing** (automatic) put the right approach and the
+  right specialist persona in front of the model before it starts.
+- **Memory** stops it re-making the same mistakes across turns and sessions.
+- **Worktree + completion gates** keep every attempt isolated and only let
+  "done" mean *actually done*.
+
+Net effect: a local, zero-per-token, 4-bit MoE model produces verified results
+that a naive one-shot of a much larger model often won't — and it runs on a GPU
+you already own.
+
+See also: [Local Models](LOCAL_MODELS.md) · [`uap deliver`](DELIVER.md) ·
+[Automatic features](AUTOMATIC.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.43.1",
+  "version": "1.43.3",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,7 @@
     "lint": "eslint src --ext .ts",
     "lint:fix": "eslint src --ext .ts --fix",
     "format": "prettier --write src/**/*.ts",
-    "prepublishOnly": "npm run build && npm test",
+    "prepublishOnly": "npm run build && npm test && bash scripts/maintenance/ensure-exec-bits.sh",
     "install:web": "bash scripts/setup/install-web.sh",
     "install:desktop": "bash scripts/setup/install-desktop.sh",
     "install:cloakbrowser": "tsx scripts/setup/install-cloakbrowser.ts",

package/scripts/maintenance/ensure-exec-bits.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# ensure-exec-bits.sh — guarantee that shipped shebang scripts are executable
+# before publish. npm packs files with their filesystem mode, so a tracked
+# script committed as 100644 ships non-executable. Runs in prepublishOnly.
+#
+# Scope: shipped dirs only (must match package.json "files"). Only files that
+# begin with a shebang (#!) are touched; imported .ts/.cjs modules and .j2
+# templates are left alone (a leading shebang on a module is ignored at import).
+set -euo pipefail
+cd "$(dirname "$0")/../.."
+
+SHIPPED=(src/policies/enforcers tools/agents templates config scripts/setup scripts/maintenance dist)
+fixed=0
+while IFS= read -r f; do
+  [ -f "$f" ] || continue
+  case "$f" in *.ts|*.j2|*.d.ts) continue ;; esac
+  if head -c2 "$f" 2>/dev/null | grep -q '#!' && [ ! -x "$f" ]; then
+    chmod +x "$f"
+    echo "ensure-exec-bits: +x $f"
+    fixed=$((fixed + 1))
+  fi
+done < <(git ls-files -- "${SHIPPED[@]}" 2>/dev/null | grep -E '\.(sh|py|cjs)$')
+
+echo "ensure-exec-bits: ${fixed} script(s) made executable"
+exit 0

package/docs/AGENTS.md</path>CLAUDE.md</path>/home/cogtek/dev/miller-tech/universal-agent-protocol/docs/INDEX.md</path>/home/cogtek/dev/miller-tech/universal-agent-protocol/docs/reference/API_REFERENCE.md</path>/home/cogtek/dev/miller-tech/universal-agent-protocol/docs/reference/UAP_CLI_REFERENCE.md</path>src/index.ts</path>/src/cli/worktree.ts</path>/src/coordination/deploy-batcher.ts</path>/src/policies/policy-gate.ts</path>/src/memory/model-router.ts</path>/src/memory/embeddings.ts</path>/src/models/types.ts</path>/src/types/coordination.ts</path>/src/utils/logger.ts</path>/src/utils/config-loader.ts</path>/src/utils/performance-monitor.ts</path>/src/utils/concurrency.ts</path>/src/utils/concurrency-pool.ts</path>/src/utils/string-similarity.ts</path>/src/utils/rate-limiter.ts</path>/src/utils/system-resources.ts</path>/src/utils/adaptive-cache.ts</path>/src/utils/lazy-imports.ts</path>/src/utils/merge-claude-md.ts</path>/src/utils/stopwords.ts</path>/src/utils/config-loader.ts</path>/src/utils/performance-monitor.ts</path>/src/utils/concurrency.ts</path>/src/utils/concurrency-pool.ts</path>/src/utils/string-similarity.ts</path>/src/utils/rate-limiter.ts</path>/src/utils/system-resources.ts</path>/src/utils/adaptive-cache.ts</path>/src/utils/lazy-imports.ts</path>/src/utils/merge-claude-md.ts</path>/src/utils/stopwords.ts</path>

@@ -1,433 +0,0 @@
-# UAP Project Code Analysis and Documentation Audit Report
-
-## Executive Summary
-
-The Universal Agent Protocol (UAP) is a comprehensive AI agent framework with extensive functionality for persistent memory, multi-agent coordination, pattern-based workflows, and policy enforcement. The project contains approximately 143 TypeScript source files, 74 test files, and over 9 total files (including benchmark results and agent sessions).
-
-## Documentation Quality Assessment
-
-### Current State: GOOD TO VERY GOOD
-
-**Strengths:**
-- Comprehensive README.md (542 lines) with feature overview, CLI reference, and architecture diagrams
-- Extensive CLI reference documentation (620 lines in UAP_CLI_REFERENCE.md)
-- Architecture documentation covering system design and components
-- Benchmark results and validation plans documented
-- Integration guides for multiple platforms (Claude, Factory, OpenCode, etc.)
-- Documentation version mismatch (README shows v1.20.32, INDEX.md shows v1.18.0)
-- Some CLI commands in code don't match documentation
-- Limited inline JSDoc comments in source files
-- Outdated architecture diagrams with placeholder text
-- Missing documentation for several internal modules
-
-## Feature Inventory
-
-### 1. Memory System (27+ modules)
-**Well-documented:**
-- Hierarchical memory (Hot/Warm/Cold tiers)
-- Embedding service with multiple providers
-- Knowledge graph implementation
-- Semantic compression
-- Write gate quality filtering
-- Daily log staging area
-
-**Under-documented:**
-- Predictive memory service
-- Context pruner (token-budget-aware)
-- Ambiguity detector (P37 pattern)
-- Prepopulation from docs/git history
-- Memory maintenance routines
-- Correction propagator for cross-tier updates
-
-### 2. Multi-Agent Coordination (8 modules)
-**Well-documented:**
-- Coordination service and database
-- Agent lifecycle management
-- Work claims and announcements
-- Messaging system with channels
-- Deploy batching with configurable windows
-
-**Under-documented:**
-- Capability router (18 capability types)
-- Auto-agent registration
-- Pattern router implementation
-- Adaptive patterns with success tracking
-
-### 3. Policy Enforcement (8 modules)
-**Well-documented:**
-- Policy schema and database manager
-- Policy memory CRUD operations
-- Enforcement levels (REQUIRED/RECOMMENDED/OPTIONAL)
-- Audit trail functionality
-
-**Under-documented:**
-- Policy gate middleware implementation
-- Enforced tool router
-- Python enforcement tools
-- Policy converter to CLAUDE.md format
-
-### 4. Pattern System (23+ patterns)
-**Well-documented:**
-- Pattern list with descriptions
-- Critical patterns (P12, P35) always active
-- Pattern RAG management
-
-**Under-documented:**
-- Pattern matching algorithm
-- Pattern library storage format
-- Pattern success tracking metrics
-- Custom pattern creation guide
-
-### 5. Worktree System
-**Well-documented:**
-- CLI commands (create, list, pr, cleanup, finish)
-- Git workflow integration
-- Exempt paths documentation
-
-**Under-documented:**
-- Worktree file guard enforcement mechanism
-- Branch naming conventions
-- Conflict resolution strategies
-- Prune functionality details
-
-### 6. Hooks System
-**Well-documented:**
-- Session start hook (5 steps)
-- Pre-compact hook (4 steps)
-- Platform-specific installations
-- Hook status checking
-
-**Under-documented:**
-- Pre-tool-use hooks (mentioned but not detailed)
-- Post-tool-use hooks
-- Custom hook creation guide
-- Hook failure recovery
-
-### 7. MCP Router
-**Well-documented:**
-- 98% token reduction claim
-- Meta-tool routing concept
-- Config parser and fuzzy search
-
-**Under-documented:**
-- Client pool management
-- Output compression algorithm
-- Session statistics tracking
-- Tool discover/execute definitions
-
-### 8. Multi-Model Architecture
-**Well-documented:**
-- 3-tier execution model
-- 13 model profiles
-- Dynamic temperature and rate limiting
-- Model analytics
-
-**Under-documented:**
-- Task planner decomposition algorithm
-- Plan validator cycle detection
-- Unified router logic
-- Execution profile loading
-
-### 9. Browser Automation
-**Well-documented:**
-- CloakBrowser integration
-- Playwright drop-in compatibility
-- Basic usage example
-
-**Under-documented:**
-- Stealth techniques
-- Humanize mode details
-- Error handling
-- Performance characteristics
-
-### 10. Task Management
-**Well-documented:**
-- Task types and statuses
-- Priority levels (P0-P4)
-- Dependencies and claims
-- JSONL sync format
-
-**Under-documented:**
-- Event bus implementation
-- Decoder gate mechanism
-- Task classifier (9 categories)
-- Compaction/archive logic
-
-### 11. Droids & Skills
-**Well-documented:**
-- 8 expert droids listed
-- 33 skills categorized
-- Skill documentation command
-
-**Under-documented:**
-- Droid creation process
-- Skill loading mechanism
-- Custom droid development
-- Skill composition patterns
-
-## Documentation Gaps by Priority
-
-### CRITICAL (Must-Have)
-
-1. **Inline JSDoc for Public APIs**
-   - Missing from src/index.ts exports (340 lines of exports)
-   - Affects: Memory system, coordination, policies, models, MCP router
-   - autocomplete and API documentation generation
-
-2. **CLI Command Completeness**
-   - Dashboard has 11 views but only partially documented
-   - Model commands (8 subcommands) under-documented
-   - Policy commands (15 subcommands) need examples
-   - Worktree finish command behavior not explained
-
-3. **Configuration Schema Documentation**
-   - .uap.json schema incomplete
-   - Missing validation rules
-   - Environment variables not fully listed
-
-4. **Database Schema Accuracy**
-   - API_REFERENCE.md shows outdated table structures
-   - Missing tables: deploy_queue, pattern_index, task_events
-   - Qdrant collection schemas not documented
-
-5. **Hook System Implementation Details**
-   - Pre-edit build gate enforcement mechanism
-   - Worktree file guard blocking logic
-   - Completion gate verification steps
-
-### HIGH PRIORITY (Should-Have)
-
-6. **Memory System Architecture Diagram**
-   - Current diagram has placeholder text
-   - 4-layer architecture needs visual representation
-   - Data flow between tiers unclear
-
-7. **Pattern Library Reference**
-   - All 23+ patterns need detailed descriptions
-   - Pattern selection criteria missing
-   - Pattern composition examples
-
-8. **Multi-Agent Coordination Flow**
-   - Heartbeat mechanism details
-   - Overlap detection algorithm
-   - Message priority handling
-   - Deadlock prevention
-
-9. **Policy Enforcement Workflow**
-   - Policy evaluation order
-   - Violation handling procedures
-   - Audit trail query examples
-
-10. **Testing and Quality Gates**
-    - Test coverage requirements (50% threshold)
-    - Build gate enforcement
-    - Completion gate verification steps
-
-### MEDIUM PRIORITY (Nice-to-Have)
-
-11. **Benchmark Methodology**
-    - Terminal-Bench adapter details
-    - Harbor integration workflow
-    - A/B comparison methodology
-
-12. **Deployment Guides**
-    - Production Qdrant setup
-    - CI/CD pipeline configuration
-    - Horizontal scaling patterns
-
-13. **Troubleshooting Matrix**
-    - Error code reference
-    - Common failure modes
-    - Recovery procedures
-
-14. **Integration Patterns**
-    - RTK token compression details
-    - Platform-specific optimizations
-    - Custom adapter development
-
-15. **Performance Optimization Guide**
-    - Token budget management
-    - Cache warm strategies
-    - Memory pruning thresholds
-
-## Specific Recommendations
-
-### Immediate Actions (Week 1-2)
-
-1. **Add JSDoc to src/index.ts**
-   ```typescript
-   /**
-    * Hierarchical memory manager with hot/warm/cold tiering
-    * @see src/memory/hierarchical-memory.ts for implementation details
-    */
-   export { HierarchicalMemoryManager } from './memory/hierarchical-memory.js';
-documentation/architecture diagrams**
-   - Replace placeholder text in docs/INDEX.md
-   - Create Mermaid diagrams for memory flow
-   - Document data persistence layers
-
-3. **Complete CLI Reference**
-   - Add all 109 commands with examples
-   - Include exit codes and error messages
-   - Document shell completion setup
-
-4. **Fix Version Mismatch**
-   - Update INDEX.md to v1.20.32
-   - Ensure CHANGELOG.md is current
-   - Sync README version numbers
-
-5. **Document Database Schemas**
-   - Update API_REFERENCE.md with actual tables
-   - Add Qdrant collection schemas
-   - Include migration guides
-
-### Short-Term Actions (Week 3-4)
-
-6. **Create Module-Level Documentation**
-   - Add README.md to each src/ subdirectory
-   - Document module responsibilities and dependencies
-   - Include usage examples
-
-7. **Build Pattern Library Reference**
-   - Document all 23+ patterns with use cases
-   - Add pattern selection decision tree
-   - Create pattern composition examples
-
-8. **Enhance Hook Documentation**
-   - Document all hook types (pre/post tool-use)
-   - Add hook failure recovery guide
-   - Include custom hook templates
-
-9. **Complete Configuration Guide**
-   - Full .uap.json schema with validation
-   - Environment variable reference
-   - Platform-specific configs
-
-10. **Add Testing Documentation**
-    - Test coverage requirements
-    - Build gate enforcement
-    - Completion gate checklist
-
-### Long-Term Actions (Month 2+)
-
-11. **Generate API Documentation**
-    - Use TypeDoc for TypeScript APIs
-    - Integrate with GitHub Pages
-    - Keep in sync with code changes
-
-12. **Create Video Tutorials**
-    - Quick start walkthrough
-    - Advanced feature demonstrations
-    - Troubleshooting guides
-
-13. **Develop Interactive Examples**
-    - Code sandbox for CLI commands
-    - Memory system visualization
-    - Multi-agent simulation
-
-14. **Establish Documentation Review Process**
-    - Require docs updates with PRs
-    - Add docs linting to CI
-    - Schedule quarterly reviews
-
-15. **Create Contribution Guide**
-    - Documentation standards
-    - Template examples
-    - Review process
-
-## Proposed Documentation Structure
-
-### Current Structure (Adequate)
-```
-docs/
-├── getting-started/      ✓ Good coverage
-├── architecture/         ⚠ Needs updates
-├── reference/            ✓ CLI ref good, API ref outdated
-├── deployment/           ⚠ Incomplete
-├── benchmarks/           ✓ Comprehensive
-├── operations/           ⚠ Minimal
-├── integrations/         ✓ Good coverage
-├── research/             ⚠ Academic focus
-└── archive/              ℹ Historical reference
-```
-
-### Proposed Enhanced Structure
-```
-docs/
-├── getting-started/
-│   ├── QUICKSTART.md     ← New: 5-minute setup
-│   ├── INSTALLATION.md   ← Updated: Platform-specific
-│   └── TROUBLESHOOTING.md ← Merged from operations/
-│   ├── memory-system.md
-│   ├── coordination.md
-│   ├── patterns.md
-│   └── policies.md
-├── architecture/
-│   ├── OVERVIEW.md       ← Updated with diagrams
-│   ├── COMPONENTS.md     ← New: Module details
-│   ├── DATA_FLOW.md      ← New: Data persistence
-│   └── SCHEMAS.md        ← Updated: Database specs
-├── reference/
-│   ├── CLI_REFERENCE.md  ✓ Complete
-│   ├── API_REFERENCE.md  ← Updated with JSDoc
-│   ├── CONFIG_SCHEMA.md  ← New: Full schema
-│   └── ERROR_CODES.md    ← New: Error reference
-├── guides/               ← New: Practical tutorials
-│   ├── memory-best-practices.md
-│   ├── multi-agent-setup.md
-│   ├── policy-enforcement.md
-│   ├── pattern-library.md
-│   └── worktree-workflow.md
-├── deployment/
-│   ├── PRODUCTION.md     ← Updated
-│   ├── CI_CD.md          ← Updated
-│   ├── SCALING.md        ← New: Horizontal scaling
-│   └── MONITORING.md     ← New: Observability
-├── benchmarks/           ✓ Comprehensive
-├── operations/
-│   ├── MAINTENANCE.md    ← New: Routine tasks
-│   ├── BACKUP_RESTORE.md ← New: Disaster recovery
-│   └── DEBUGGING.md      ← Updated: Debug modes
-├── integrations/         ✓ Good coverage
-├── contributed/          ← New: Community content
-└── archive/              ℹ Historical reference
-```
-
-## Test Coverage Analysis
-
-### Current State
-- 74 test files covering major components
-- Tests for: policies, memory, coordination, models, benchmarks, CLI
-- Vitest configuration with coverage thresholds (50%)
-
-### Gaps
-1. **Browser module** - Minimal test coverage
-2. **MCP router** - Only output-compressor tested
-3. **Dashboard** - Server and event-stream not tested
-4. **Telemetry** - Session telemetry untested
-5. **Benchmarks** - Agent implementations not tested
-
-### Recommendations
-1. Add JSDoc to test files for clarity
-2. Create integration test suite
-3. Document test coverage requirements
-4. Add performance test benchmarks
-
-## Conclusion
-
-The UAP project has **solid foundational documentation** with comprehensive CLI references and good architectural overviews. However, there are significant gaps in:
-   - Inline code documentation (JSDoc)
-2. Module-level documentation for internal components
-3. Accurate database schemas
-4. Configuration schema completeness
-5. Hook system implementation details
-
-**Priority Ranking:**
-- **Must-Have**: JSDoc, CLI completeness, config schema, DB schemas, hook docs
-   - Architecture diagrams, pattern library, coordination flows, policy workflows, testing docs
-- **Nice-to-Have**: Video tutorials, interactive examples, contribution guide, API generation
-- Critical fixes: 2-3 weeks
-- High priority: 4-6 weeks
-- Medium priority: 8-12 weeks
-
-The documentation quality is sufficient for current users but needs improvement to support new contributors and maintain long-term project health.