@miller-tech/uap 1.40.0 → 1.41.0

package/docs/benchmarks/README.md

@@ -1,200 +1,25 @@
 # UAP Benchmarks
 
-> **Version:** 1.18.0  
-> **Last Updated:** 2026-03-28  
-> **Status:** ✅ Production Ready
+Performance and accuracy results for the Universal Agent Protocol, measured on Terminal-Bench 2.0.
 
----
+## Headline results
 
-## Benchmark Overview
+UAP-on vs. baseline, 12 representative tasks across 8 categories:
 
-This directory contains comprehensive benchmark results and validation data for UAP v1.18.0 with OpenCode integration.
+| Metric | Baseline | With UAP | Δ |
+|---|---|---|---|
+| Tokens consumed | 558,000 | 280,438 | **−49.7%** |
+| Task success rate | 25% | 58% | **+33pp** |
+| Errors per task | 1.17 | 0.42 | **−68%** |
+| Wall-clock (total) | 618s | 266s | **−57%** |
 
-### Quick Stats
+## Reports
 
-| Metric | Baseline | UAP v1.17 | UAP v1.18 + OpenCode | Improvement |
-|--------|----------|-----------|---------------------|-------------|
-| **Success Rate** | 75% | 92% | **100%** | +25pp |
-| **Avg Tokens/Task** | 52,000 | 28,500 | **23,400** | -55% |
-| **Avg Time/Task** | 45s | 38s | **32s** | -29% |
-| **Error Rate** | 12% | 4% | **0%** | -100% |
-| **Quality Score** | 3.2/5 | 4.1/5 | **4.7/5** | +47% |
+| Doc | What it covers |
+|---|---|
+| [Validation Results](VALIDATION_RESULTS.md) | Full methodology + per-task breakdown |
+| [Token Optimization](TOKEN_OPTIMIZATION.md) | Where the token savings come from |
+| [Accuracy Analysis](ACCURACY_ANALYSIS.md) | Success-rate and error analysis |
+| [Comprehensive Benchmarks](COMPREHENSIVE_BENCHMARKS.md) | Extended measurements |
 
----
-
-## Documentation
-
-### Main Documents
-
-| Document | Description | Link |
-|----------|-------------|------|
-| **Comprehensive Benchmarks** | Full benchmark results and analysis | [COMPREHENSIVE_BENCHMARKS.md](COMPREHENSIVE_BENCHMARKS.md) |
-| **Validation Results** | Production validation report | [VALIDATION_RESULTS.md](VALIDATION_RESULTS.md) |
-| **Validation Plan** | Benchmark methodology | [VALIDATION_PLAN.md](VALIDATION_PLAN.md) |
-
-### Analysis Documents
-
-| Document | Description |
-|----------|-------------|
-| **Token Optimization** | Per-feature token savings analysis |
-| **Accuracy Analysis** | Internal vs Terminal-Bench comparison |
-| **Speculative Decoding Journey** | End-to-end tuning narrative |
-
-### Quick Reference
-
-- [Benchmark Results Summary](../README.md#benchmarks)
-- [Token Optimization Details](../benchmarks/TOKEN_OPTIMIZATION.md)
-- [Accuracy Analysis](../benchmarks/ACCURACY_ANALYSIS.md)
-
----
-
-## Running Benchmarks
-
-### Quick Start
-
-```bash
-# Run short benchmark suite (10 tasks)
-npm run benchmark:short
-
-# Run full benchmark suite (14 tasks)
-npm run benchmark:full
-
-# Run overnight suite (extended validation)
-npm run benchmark:overnight
-
-# Generate report from results
-npm run benchmark:report -- --input=<results.json> --output=<report.md>
-```
-
-### Configuration
-
-```json
-{
-  "benchmark": {
-    "tasks": ["T01", "T02", "T03", "T04", "T05", "T06", "T07", "T08", "T09", "T10"],
-    "uapEnabled": true,
-    "openCodeIntegration": true,
-    "tokenTracking": true,
-    "qualityScoring": true
-  }
-}
-```
-
----
-
-## Test Suite
-
-### Task Distribution
-
-```
-System Administration: 25%
-Security: 25%
-ML/Data Processing: 25%
-Development: 25%
-```
-
-### Task List
-
-| ID | Category | Task | Complexity |
-|----|----------|------|------------|
-| T01 | System Admin | Git Repository Recovery | Medium |
-| T02 | Security | Password Hash Recovery | Low |
-| T03 | Security | mTLS Certificate Setup | High |
-| T04 | System Admin | Docker Compose Config | Medium |
-| T05 | ML/Data | ML Model Training | High |
-| T06 | ML/Data | Data Compression | Low |
-| T07 | Development | Chess FEN Parser | Medium |
-| T08 | Security | SQLite WAL Recovery | High |
-| T09 | System Admin | HTTP Server Config | Low |
-| T10 | Development | Code Compression | Low |
-| T11 | ML/Data | MCMC Sampling | High |
-| T12 | Development | Core War Algorithm | Medium |
-| T13 | System Admin | Network Diagnostics | Medium |
-| T14 | Security | Cryptographic Key Gen | Low |
-
----
-
-## Feature Contribution
-
-### Token Savings Breakdown
-
-```
-Pattern Router: 35%
-MCP Output Compression: 25%
-Memory Tiering: 20%
-Knowledge Graph: 10%
-OpenCode Integration: 10%
-```
-
-### Performance Impact
-
-```mermaid
-quadrantChart
-    title Feature Impact Analysis
-    x-axis Low Impact --> High Impact
-    y-axis Low Complexity --> High Complexity
-    quadrant-1 High Value
-    quadrant-2 Consider
-    quadrant-3 Low Priority
-    quadrant-4 Avoid
-    Pattern Router: [0.8, 0.9]
-    MCP Compression: [0.7, 0.8]
-    Memory Tiering: [0.6, 0.7]
-    OpenCode: [0.85, 0.75]
-```
-
----
-
-## Overnight Benchmark Runner
-
-For automated nightly execution, see the [Overnight Runner Guide](OVERNIGHT_RUNNER.md).
-
-### Setup
-
-```bash
-# Make scripts executable
-chmod +x scripts/benchmark-overnight.sh
-
-# Add to crontab (runs at 2:00 AM daily)
-0 2 * * * cd /path/to/uap && npm run benchmark:overnight >> /var/log/uap-benchmark.log 2>&1
-```
-
----
-
-## Enterprise Impact
-
-### Monthly Savings (10K tasks)
-
-| Metric | Baseline | UAP v1.18 | Savings |
-|--------|----------|-----------|---------|
-| Token Cost | $26,000 | $11,700 | **$14,300** |
-| Developer Time | $125,000 | $89,000 | **$36,000** |
-| Bug Fixes | $8,000 | $1,200 | **$6,800** |
-| **Total** | **$159,000** | **$101,900** | **$57,100** |
-
-**ROI:** 35.8% cost reduction, 2.8x faster delivery
-
----
-
-## Validation Status
-
-| Target | Threshold | Actual | Status |
-|--------|-----------|--------|--------|
-| Token Reduction | ≥45% | 55% | ✅ PASS |
-| Success Rate | ≥95% | 100% | ✅ PASS |
-| Error Reduction | ≥90% | 100% | ✅ PASS |
-| Quality Score | ≥4.5 | 4.7 | ✅ PASS |
-| No Regressions | Time ≤ baseline | 32s vs 45s | ✅ PASS |
-
-**Overall Verdict: ✅ EXCEEDS EXPECTATIONS**
-
----
-
-<div align="center">
-
-**Next Steps:**
-- [View Comprehensive Benchmarks](COMPREHENSIVE_BENCHMARKS.md)
-- [Run Overnight Benchmark](OVERNIGHT_RUNNER.md)
-- [View Validation Results](VALIDATION_RESULTS.md)
-
-</div>
+See the [documentation index](../INDEX.md) for the rest of the docs.

package/docs/getting-started/CONFIGURATION.md

@@ -0,0 +1,237 @@
+# Configuration
+
+UAP is configured through a project-level `.uap.json` file plus a set of
+environment variables. `uap init` / `uap setup` create `.uap.json` for you; this
+page documents the options that actually exist in the code so you can tune them
+by hand.
+
+## Project config: `.uap.json`
+
+`.uap.json` lives at the project root and is validated against a strict schema —
+unknown keys and bad types are rejected. Every section is optional except
+`project`; defaults are applied for anything you omit.
+
+```json
+{
+  "version": "1.0.0",
+  "project": {
+    "name": "my-project",
+    "description": "Optional description",
+    "defaultBranch": "main"
+  },
+  "platforms": {
+    "claudeCode": { "enabled": true },
+    "factory": { "enabled": true },
+    "vscode": { "enabled": true },
+    "opencode": { "enabled": true },
+    "codex": { "enabled": true }
+  },
+  "memory": {
+    "shortTerm": { "enabled": true, "path": "./agents/data/memory/short_term.db", "maxEntries": 50 },
+    "longTerm": { "enabled": true, "provider": "qdrant", "collection": "agent_memory", "embeddingModel": "all-MiniLM-L6-v2" },
+    "patternRag": { "enabled": false, "collection": "agent_patterns", "topK": 2, "scoreThreshold": 0.35 }
+  },
+  "worktrees": { "enabled": true, "directory": ".worktrees", "branchPrefix": "feature/", "autoCleanup": true }
+}
+```
+
+### Top-level sections
+
+| Key | Purpose |
+| --- | --- |
+| `project` | **Required.** `name`, optional `description`, `defaultBranch` (default `main`). |
+| `platforms` | Per-harness toggles and memory-budget overrides: `claudeCode`, `factory`, `vscode`, `opencode`, `codex`. Each accepts `enabled`, `shortTermMax`, `searchResults`, `sessionMax`, `patternRag`. |
+| `memory` | Memory tiers: `shortTerm`, `longTerm`, `patternRag` (see below). |
+| `worktrees` | `enabled`, `directory` (default `.worktrees`), `branchPrefix` (default `feature/`), `autoCleanup`. |
+| `droids` | Array of custom droid definitions (`name`, `template`, `description`, `model`, `tools`). |
+| `commands` | Array of custom command definitions (`name`, `template`, `description`, `argumentHint`). |
+| `template` | CLAUDE.md template selection: `extends` and per-section `sections` toggles. |
+| `costOptimization` | Token budgets, embedding batching, and LLM call reduction. |
+| `timeOptimization` | Deploy batch windows, parallel execution limits, service pre-warming. |
+| `multiModel` | Multi-model routing (see [Model profiles](#model-profiles)). |
+| `agentExecution` | Benchmark-proven agent execution feature flags (see below). |
+| `patternRL` | Pattern reinforcement learning: `enabled`, `dbPath`. |
+
+### Memory tiers
+
+`memory.shortTerm`:
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `enabled` | `true` | |
+| `path` | `./agents/data/memory/short_term.db` | SQLite database path. |
+| `webDatabase` | — | IndexedDB name for web platforms. |
+| `maxEntries` | `50` | |
+
+`memory.longTerm` (the semantic tier):
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `enabled` | `true` | |
+| `provider` | `qdrant` | One of `qdrant`, `chroma`, `pinecone`, `github`, `qdrant-cloud`, `serverless`, `none`. |
+| `endpoint` | — | Qdrant endpoint; falls back to `localhost:6333`. |
+| `collection` | `agent_memory` | |
+| `embeddingModel` | `all-MiniLM-L6-v2` | |
+| `github` | — | GitHub-backed memory: `repo`, `token`, `path`, `branch`. |
+| `qdrantCloud` | — | Qdrant Cloud: `url`, `apiKey`, `collection`. |
+| `serverless` | — | Serverless Qdrant (see below). |
+
+`memory.patternRag` (on-demand pattern retrieval): `enabled`, `collection`
+(`agent_patterns`), `embeddingModel` (`all-MiniLM-L6-v2`), `vectorSize` (`384`),
+`scoreThreshold` (`0.35`), `topK` (`2`), and the `indexScript` / `queryScript`
+paths.
+
+### Qdrant configuration
+
+The default local provider talks to Qdrant at `http://localhost:6333` — the
+endpoint `uap setup` starts via docker-compose. Override it with
+`memory.longTerm.endpoint`.
+
+For managed Qdrant, set `memory.longTerm.provider` to `qdrant-cloud` and fill in
+`memory.longTerm.qdrantCloud`:
+
+```json
+{
+  "memory": {
+    "longTerm": {
+      "provider": "qdrant-cloud",
+      "qdrantCloud": {
+        "enabled": true,
+        "url": "https://xyz.qdrant.io",
+        "apiKey": "...",
+        "collection": "agent_memory"
+      }
+    }
+  }
+}
+```
+
+`url` and `apiKey` fall back to the `QDRANT_URL` and `QDRANT_API_KEY` environment
+variables when omitted, so you can keep secrets out of the config file.
+
+For cost-sensitive setups, `memory.longTerm.serverless` enables a lazy-start
+local instance or a cloud-serverless backend:
+
+```json
+{
+  "memory": {
+    "longTerm": {
+      "provider": "serverless",
+      "serverless": {
+        "enabled": true,
+        "mode": "lazy-local",
+        "lazyLocal": { "port": 6333, "autoStart": true, "autoStop": true, "idleTimeoutMs": 300000 }
+      }
+    }
+  }
+}
+```
+
+`mode` is one of `lazy-local`, `cloud-serverless`, or `hybrid`. Hybrid mode picks
+local vs. cloud based on `NODE_ENV`, `UAP_ENV`, or auto-detection.
+
+### Agent execution flags
+
+`agentExecution` exposes benchmark-tuned feature flags for the delivery harness.
+Defaults are the proven-effective subset; some flags are deliberately off because
+they regressed small models. Notable fields:
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `domainHints` | `true` | Domain-specific hints routed by task classification. |
+| `lowTemperature` / `temperature` | `true` / `0.15` | Deterministic sampling. |
+| `preExecutionHooks` | `true` | File backups and tool installs before the agent starts. |
+| `webSearch` | `false` | Off by default; enable for larger (70B+) models. |
+| `reflectionCheckpoints` | `false` | Harmful for small models. |
+| `softBudget` / `hardBudget` | `35` / `50` | Tool-call budget thresholds. |
+
+## Model profiles
+
+UAP includes **7 execution profiles** — feature-flag presets tuned per model
+family. They are auto-detected from the model id but can be forced via the
+`UAP_MODEL_PROFILE` environment variable:
+
+`small-moe`, `small-dense`, `medium`, `large`, `claude`, `gpt`, `gemini`.
+
+Multi-model routing is configured under the `multiModel` section of `.uap.json`:
+
+```json
+{
+  "multiModel": {
+    "enabled": true,
+    "models": ["opus-4.6", "qwen35-a3b"],
+    "roles": {
+      "planner": "opus-4.6",
+      "executor": "qwen35-a3b",
+      "fallback": "qwen35-a3b"
+    }
+  }
+}
+```
+
+`models` may reference built-in presets or inline custom model definitions.
+Built-in presets include `opus-4.6`, `sonnet-4.6`, `qwen35-a3b`, `gpt-5.4`, and
+`gpt-5.3-codex`. Roles default to `opus-4.6` (planner) and `qwen35-a3b`
+(executor/fallback). Inspect routing with `uap model` (status, route, plan,
+compare, presets, select, export, health) and `uap dashboard models`.
+
+## Environment variables
+
+These are the environment variables read by the code.
+
+### Memory & Qdrant
+
+| Variable | Used for |
+| --- | --- |
+| `QDRANT_URL` | Qdrant endpoint for cloud/serverless backends (overridden by config when both are set). |
+| `QDRANT_API_KEY` | Qdrant API key (fallback when not in config). |
+| `UAP_EMBEDDING_ENDPOINT` | Embedding server endpoint for semantic memory. |
+
+### Delivery harness (`uap deliver`)
+
+| Variable | Used for |
+| --- | --- |
+| `UAP_DELIVER_MODEL` | Default model preset for `uap deliver` (fallback `qwen35-a3b`). |
+| `UAP_ESCALATE_MODEL` | Stronger preset used by the escalation ladder. |
+| `UAP_DELIVER_AUTO` | Set to `0` to disable task-aware auto-optimization. |
+| `UAP_DELIVER_UNTIL_DELIVERED` | Set to `0` to disable loop-until-delivered. |
+| `UAP_DELIVER_ACTIVE` | Set to `1` by the loop for its own subprocesses (policy enforcers detect it). |
+| `UAP_DELIVER_SANDBOX` | Sandbox root that confines deliver's target directory (MCP tool). |
+
+### Models & inference
+
+| Variable | Used for |
+| --- | --- |
+| `UAP_MODEL_PROFILE` | Force an execution profile (otherwise auto-detected). |
+| `UAP_LLM_SERVER` | LLM server base URL for tool-call tooling (default `http://127.0.0.1:4000`). |
+| `UAP_INFERENCE_ENDPOINT` | Fallback OpenAI-compatible endpoint (default `http://localhost:4000/v1`). |
+
+### Observability (HALO)
+
+| Variable | Used for |
+| --- | --- |
+| `UAP_HALO_TRACE` | Set to `1` to enable HALO trace collection. |
+| `UAP_HALO_TRACE_PATH` | Trace output file (default `.uap/halo/traces.jsonl`). |
+| `UAP_HALO_PROJECT_ID` | HALO project identifier. |
+
+### Concurrency & runtime
+
+| Variable | Used for |
+| --- | --- |
+| `UAP_MAX_PARALLEL` | Override the auto-detected max parallelism (always wins). |
+| `UAP_PARALLEL` | Set to `false` to disable parallel execution. |
+| `UAP_LOG_LEVEL` | Log verbosity (e.g. `debug`, `warn`). |
+| `UAP_AGENT_ID` | Stable agent identifier used by the coordination layer. |
+| `NODE_ENV` / `UAP_ENV` | Environment detection for hybrid serverless mode (`UAP_ENV=production` selects the prod backend). |
+| `HERMES_HOME` | Hermes config home (default `~/.hermes`). |
+
+### Provider credentials
+
+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `FACTORY_API_KEY`, `DROID_API_KEY`, and
+`GITHUB_TOKEN` are read when the corresponding provider or GitHub-backed memory
+is configured.
+
+## See also
+
+- [Installation](./INSTALLATION.md)
+- [Quickstart](./QUICKSTART.md)

package/docs/getting-started/INSTALLATION.md

@@ -0,0 +1,125 @@
+# Installation
+
+The Universal Agent Protocol (UAP) is an autonomous AI agent memory system with
+CLAUDE.md protocol enforcement. It ships as a single npm package
+(`@miller-tech/uap`, v1.40.0) that installs the `uap` CLI.
+
+## Prerequisites
+
+| Requirement | Needed for | Notes |
+| --- | --- | --- |
+| **Node.js >= 18** | Everything | The CLI is published as ESM and requires Node 18 or newer. |
+| **git** | Worktree workflow, memory prepopulation from history | Any recent git. |
+| **Docker** | Local Qdrant (semantic memory tier) | `uap setup` starts a Qdrant container via docker-compose. Optional — memory degrades gracefully without it. |
+| **Python 3** | Pattern RAG indexing & embeddings | Optional. `uap setup` creates a virtualenv and installs the pattern indexing dependencies. |
+| **A local OpenAI-compatible model** | `uap deliver`, multi-model routing | Optional. Points at an OpenAI-compatible `/v1` endpoint (default `http://localhost:4000/v1`). |
+
+UAP works without Docker, Python, or a local model — those steps are skipped and
+the corresponding features (semantic recall, pattern RAG, the convergence
+harness) are simply unavailable until you provide them.
+
+## Install
+
+Install the CLI globally:
+
+```bash
+npm install -g @miller-tech/uap
+```
+
+### Verify the install
+
+```bash
+uap --version
+```
+
+This prints the installed package version (e.g. `1.40.0`).
+
+## One-command setup
+
+From the root of the project you want to wire up, run:
+
+```bash
+uap setup
+```
+
+`uap setup` chains the individual commands so the whole system "just works". It
+runs the following steps in order:
+
+1. **Initialize the project** (`uap init` under the hood) — creates `.uap.json`,
+   the `agents/data/memory` directory structure, the short-term memory database,
+   a `CLAUDE.md` (or `AGENT.md`), the worktree workflow scaffold, and the Python
+   pattern scripts.
+2. **Start Qdrant** — uses the serverless Qdrant manager if one is configured in
+   `.uap.json`, otherwise starts a Qdrant container via docker-compose. If Docker
+   is unavailable this step warns and continues.
+3. **Wait for the Qdrant healthcheck** (up to 15s). If Qdrant is not reachable,
+   pattern indexing is skipped.
+4. **Start background memory consolidation** and **auto-promote** high-quality
+   daily-log entries into longer-lived memory tiers (non-fatal if unavailable).
+5. **Create the Python virtualenv** for pattern RAG if `init` did not already do
+   so. Skipped with a warning when Python 3 is not on the system.
+6. **Index patterns into Qdrant** — only when both Qdrant and Python are ready.
+7. **Configure the MCP Router** for all detected AI harnesses.
+8. **Install policy-gate and lifecycle hooks** for the project's platforms (run
+   `uap hooks doctor` afterward to verify coverage).
+9. **Print a setup summary** showing which steps succeeded and which optional
+   steps were skipped.
+
+### Useful `uap setup` flags
+
+```bash
+uap setup --no-memory      # init only, skip Qdrant/memory services
+uap setup --no-patterns    # skip pattern RAG setup and indexing
+uap setup -i               # interactive wizard with feature toggles
+uap setup --verbose        # detailed output
+uap setup -d <path>        # set up a project directory other than the cwd
+```
+
+### Init only
+
+If you only want the project scaffold (config, directories, `CLAUDE.md`) without
+starting services, run:
+
+```bash
+uap init
+```
+
+`uap init` accepts `--web` (generate `AGENT.md` for web platforms),
+`--no-memory`, `--no-worktrees`, `--patterns` / `--no-patterns`, and `-f, --force`
+to overwrite existing configuration.
+
+## Installing harness hooks
+
+UAP supports nine AI coding harnesses: **Claude Code, Factory, Cursor, VSCode,
+OpenCode, Codex, ForgeCode, Oh-My-Pi, and Hermes**. `uap setup` installs hooks
+for the project's platforms automatically, but you can install or re-install them
+manually.
+
+Install hooks for every detected harness:
+
+```bash
+uap hooks install
+```
+
+Install for a single harness with `-t` / `--target` (or the `-p` / `--platform`
+alias). Valid targets are `claude`, `factory`, `cursor`, `vscode`, `opencode`,
+`codex`, `forgecode`, `omp`, and `hermes`:
+
+```bash
+uap hooks install -t claude
+uap hooks install -t hermes   # Hermes is global, so it is opt-in
+```
+
+Check installation status and audit policy-gate coverage:
+
+```bash
+uap hooks status     # show what is installed, per platform
+uap hooks doctor     # audit policy-gate coverage (exits non-zero on gaps)
+```
+
+## Next steps
+
+- [Quickstart](./QUICKSTART.md) — a 5-minute path from setup to your first
+  delivered task.
+- [Configuration](./CONFIGURATION.md) — `.uap.json` options, environment
+  variables, Qdrant, and model profiles.

package/docs/getting-started/QUICKSTART.md

@@ -0,0 +1,115 @@
+# Quickstart
+
+Get from a clean checkout to your first delivered task in about five minutes.
+This assumes you have already installed the CLI — see
+[Installation](./INSTALLATION.md) if not.
+
+## 1. Set up your project (~1 min)
+
+From the root of your project:
+
+```bash
+uap setup
+```
+
+This initializes `.uap.json`, the memory directories and database, generates
+`CLAUDE.md`, starts Qdrant (if Docker is available), wires the MCP Router, and
+installs the harness hooks. It finishes with a summary showing which steps
+succeeded.
+
+Confirm memory is healthy:
+
+```bash
+uap memory status
+```
+
+You should see the short-term store initialized and, if Qdrant came up, the
+long-term endpoint reported at `http://localhost:6333`.
+
+## 2. Store and query a memory (~1 min)
+
+Write a learning into long-term memory:
+
+```bash
+uap memory store "API keys are loaded from the QDRANT_API_KEY env var" -t config,memory -i 7
+```
+
+`-t` adds comma-separated tags and `-i` sets the importance score (1-10). The
+store applies a quality write gate by default; pass `-f` to bypass it.
+
+Now query it back semantically:
+
+```bash
+uap memory query "where do api keys come from"
+```
+
+The query runs a semantic search against the long-term store and prints the
+matching entries with their similarity scores. Tune results with
+`-n <limit>` and `-t <threshold>` (minimum similarity, default `0.35`).
+
+## 3. Run `uap deliver` on a small task (~2 min)
+
+`uap deliver` is the convergence harness: it iterates a model against your
+project's **real completion gates** (build, typecheck, test, lint) until every
+required gate passes or the turn budget is exhausted.
+
+First do a dry run to see the detected gates and plan without calling a model:
+
+```bash
+uap deliver "fix the failing test in src/utils/dates" --dry-run
+```
+
+The dry run prints the project root, the model preset, the turn budget, and the
+list of gates it discovered from your `package.json` scripts. If no verifiable
+gates are detected, deliver tells you so instead of running.
+
+When the plan looks right, run it for real:
+
+```bash
+uap deliver "fix the failing test in src/utils/dates"
+```
+
+Notes on behaviour:
+
+- The default model preset is `qwen35-a3b` (override with `-m <preset>` or the
+  `UAP_DELIVER_MODEL` env var).
+- Task-aware auto-optimization is on by default — deliver classifies the task and
+  enables matching convergence aids automatically. Disable with `--no-auto`.
+- Loop-until-delivered is on by default: deliver keeps iterating past
+  `--max-turns` up to a ceiling (default 30, set with `--ceiling`), stopping
+  early on stagnation. Disable with `--no-until-delivered`.
+- Pre-existing test files are protected from modification by default; allow edits
+  with `--no-protect-tests`.
+- Add `--json` for machine-readable output, or `--optimize` to enable every
+  convergence aid (exploration, critic, practices, escalation, ideation, HALO,
+  coordination).
+
+## 4. View the dashboard (~1 min)
+
+UAP ships a rich terminal dashboard. View the full system overview:
+
+```bash
+uap dashboard overview
+```
+
+Other views are available as subcommands — for example:
+
+```bash
+uap dashboard memory     # memory health, capacity, and layer architecture
+uap dashboard tasks      # task breakdown, progress bars, hierarchy trees
+uap dashboard models     # multi-model routing analytics
+```
+
+Prefer a browser? Start the web dashboard with live updates:
+
+```bash
+uap dashboard serve            # http://localhost:3847
+uap dashboard serve -p 4000    # custom port
+```
+
+## Where to go next
+
+- [Configuration](./CONFIGURATION.md) — `.uap.json`, environment variables,
+  Qdrant, and model profiles.
+- [Installation](./INSTALLATION.md) — per-harness hook installation and
+  prerequisites.