@miller-tech/uap 1.93.0 → 1.94.0

package/docs/guides/MULTI_MODEL.md

@@ -1,18 +1,28 @@
 # Multi-Model Routing
 
-> Applies to UAP **v1.40.0**
+> Applies to UAP **v1.93.1**
+
+> **🏭 Where this fits:** PREP/ROUTING — this is the station where a normal
+> agentic workflow sends *everything* to one model: paying premium-model rates
+> for routine edits, or trusting a cheap model with reasoning it can't handle.
+> **What it delivers:** the right job goes to the right station — a strong
+> planner for hard reasoning, a cheap/local executor for the bulk of the work —
+> so you pay for expensive thinking only when the work actually needs it.
 
 UAP runs agentic work across multiple LLMs instead of one. A high-capability
 model plans, a cheaper or local model executes, and a reviewer model checks the
 result. Routing decisions are made per task (and per subtask) so you pay for
-expensive reasoning only when the work actually needs it.
+expensive reasoning only when the work actually needs it — one of the early
+stations on your [delivery pipeline](./DELIVERY_PIPELINE.md), before a single
+line of code is written.
 
 ## Why multi-model
 
 A single frontier model is the simplest setup, but most of the tokens an agent
 spends are on routine execution — applying an edit, running a tool, writing a
 test — not on hard reasoning. Sending all of that to a premium model is
-expensive and slow.
+expensive and slow. Sending the *hard* reasoning to a cheap model is the
+opposite failure. Routing fixes both.
 
 Multi-model routing lets you:
 
@@ -130,6 +140,12 @@ The matched role is resolved to a concrete model via your role assignments.
 - `balanced` — balance cost and performance (default)
 - `adaptive` — learn from task results over time
 
+> **One nuance worth internalizing:** when an executor stalls and the work
+> escalates, escalate to a **stronger, distinct** model — not the same model in
+> a different seat. A same-model judge (a local model grading its own output)
+> was measured to add no lift. The value of routing comes from the *difference*
+> in capability between the station that got stuck and the one you hand off to.
+
 ## The `uap model` CLI
 
 All subcommands are defined in `src/cli/model.ts`.

package/docs/guides/POLICIES.md

@@ -1,6 +1,8 @@
 # Policies
 
-> Applies to UAP v1.40.0
+> Applies to UAP v1.93.1
+
+> **🏭 Where this fits:** CROSS-CUTTING — the executable rules bolted to every station of the [delivery pipeline](./DELIVERY_PIPELINE.md). In a normal agentic workflow the "rules" live in a prose prompt the model is free to ignore; that's how work escapes isolation, skips tests, or ships without review. **What it delivers:** each rule is a Python enforcer that actually inspects an operation and can *block* it before it runs — worktree isolation, test deltas, expert review, schema diffs, artifact hygiene, and more — so the guardrails hold instead of merely being suggested.
 
 UAP policies are **executable gates, not prose**. Each policy can carry a Python
 enforcer that inspects an operation and decides whether it may proceed. A
@@ -51,7 +53,7 @@ on the rails — not as a containment mechanism against untrusted code.
 
 ## The enforcers
 
-The enforcers in
+Each enforcer guards a specific station of the pipeline. The enforcers in
 [`src/policies/enforcers/`](../../src/policies/enforcers/) group as follows.
 `_common.py` is shared helper code, not an enforcer.
 

package/docs/guides/QWEN36_LLAMACPP.md

@@ -1,12 +1,21 @@
 # Qwen3.6 35B-A3B on llama.cpp, by VRAM tier — with UAP
 
+> **🏭 Where this fits:** BUILD — this is the station where a one-shot local
+> model breaks: it flails on a non-trivial change, emits plausible-but-wrong
+> code, or stalls. **What it delivers:** a copy-paste local stack (8–32 GB GPU)
+> where `uap deliver` drives the model against your real gates until the change
+> is *verified* — a cheap, on-your-own-hardware model that punches above its
+> weight.
+
 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.
+*verified*. That convergence loop is the station that keeps a small, cheap,
+local model on the rails and lets it **punch well above its weight**: one-shot
+it would flail; driven to green it delivers. (This is the BUILD stage of your
+[delivery pipeline](./DELIVERY_PIPELINE.md) — the point where naive agentic
+workflows ship stubs.)
 
 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**

package/docs/guides/WORKTREE_WORKFLOW.md

@@ -1,11 +1,15 @@
 # Worktree Workflow
 
-> Applies to UAP v1.40.0
+> Applies to UAP v1.93.1
+
+> **🏭 Where this fits:** ISOLATION — the station where a normal agentic workflow smears half-finished edits across `main`, clobbers files, and lets parallel agents collide into corrupt merge state. **What it delivers:** every agent works on its own branch in its own checkout, so the project root stays clean, each unit of work has a tidy PR boundary, and any number of agents can run at once without stepping on each other.
 
 UAP runs agents — often many of them at once — against a single repository. The
 worktree workflow exists to keep every edit an agent makes isolated on its own
 branch and its own checkout, so that agent work never touches the project root
-and parallel agents never collide. This guide explains why that matters, walks
+and parallel agents never collide. Think of it as giving each agent its own
+workstation on the [delivery pipeline](./DELIVERY_PIPELINE.md) instead of
+crowding them around one bench. This guide explains why that matters, walks
 through the full lifecycle, and documents every `uap worktree` subcommand.
 
 The implementation lives in [`src/cli/worktree.ts`](../../src/cli/worktree.ts).

package/docs/integrations/MCP_ROUTER.md

@@ -1,6 +1,13 @@
 # MCP Router
 
-`v1.40.0` · `src/mcp-router/`
+`v1.93.1` · `src/mcp-router/`
+
+> **🏭 Where this fits:** Cross-cutting (keeps the belt from jamming) — every
+> station downstream stalls when your agent's context window is choked with
+> hundreds of tool schemas and raw tool dumps, so it loses the thread and burns
+> budget before doing any work. **What it delivers:** up to 98% fewer
+> tool-definition tokens and relevance-ranked tool output, so context stays lean
+> and work keeps moving down the [delivery pipeline](../guides/DELIVERY_PIPELINE.md).
 
 The MCP Router is a hierarchical Model Context Protocol server that sits in
 front of all of your downstream MCP servers and dramatically reduces the tokens
@@ -18,7 +25,8 @@ A normal MCP setup exposes every tool from every server directly to the model.
 With a dozen servers that is easily 150+ tool schemas at roughly ~500 tokens
 each — tens of thousands of tokens of context burned before the agent does any
 work. On top of that, tools like file readers and shell wrappers return large
-outputs that flood the context window.
+outputs that flood the context window. Either way, the belt jams: your agent is
+reasoning around clutter instead of the task.
 
 The router fixes both:
 
@@ -144,4 +152,5 @@ router's view, not deleted) and re-run `uap mcp-setup`.
   per-output FTS5 savings are computed live for each call and reported by
   `uap mcp-router stats`.
 - Pair the router with **RTK** for CLI-output savings — see
-  [RTK.md](RTK.md). The two are complementary (tool definitions + CLI output).
+  [RTK.md](RTK.md). The two are complementary (tool definitions + CLI output),
+  and together they keep the whole belt clear of context clutter.

package/docs/integrations/RTK.md

@@ -1,6 +1,13 @@
 # RTK — Rust Token Killer
 
-`v1.40.0` · `src/cli/rtk.ts`
+`v1.93.1` · `src/cli/rtk.ts`
+
+> **🏭 Where this fits:** Cross-cutting (keeps the belt from jamming) — every
+> `git status`, test run, and file dump your agent echoes floods the context
+> window, so it loses focus and burns budget on terminal noise. **What it
+> delivers:** 60–90% fewer tokens on CLI-command output, transparently, so
+> context stays lean at every station of the
+> [delivery pipeline](../guides/DELIVERY_PIPELINE.md).
 
 RTK (Rust Token Killer) is a fast CLI proxy that compresses and filters the
 output of command-line tools — `git status`, test runs, file reads, and similar
@@ -15,7 +22,9 @@ it; `uap rtk` manages installation and wiring.
 
 ## Why RTK + the MCP Router
 
-The two integrations target different sources of token waste and stack:
+The two integrations guard the same cross-cutting concern — keeping context lean
+so no station downstream jams — but target different sources of token waste, and
+they stack:
 
 | Layer | Tool | Saves on |
 |-------|------|----------|
@@ -76,7 +85,8 @@ Reports whether the `rtk` binary is installed, whether the rewrite hook
 Once the rewrite hook is installed, heavy CLI commands are transparently routed
 through RTK (e.g. `git status` is rewritten to `rtk git status`) with zero
 extra tokens of overhead — the agent issues normal commands and RTK compresses
-the output before it reaches the model.
+the output before it reaches the model. Your agent never knows the belt is being
+kept clear underneath it.
 
 UAP can nudge agents to route heavy CLIs through RTK via the `rtk_wrap.py`
 policy enforcer (`src/policies/enforcers/rtk_wrap.py`).
@@ -99,4 +109,5 @@ rtk --version         # verify the install
 reduction from both layers at once.
 
 See also: [MCP_ROUTER.md](MCP_ROUTER.md) ·
-[../architecture/OVERVIEW.md](../architecture/OVERVIEW.md)
+[../architecture/OVERVIEW.md](../architecture/OVERVIEW.md) ·
+[../guides/DELIVERY_PIPELINE.md](../guides/DELIVERY_PIPELINE.md)

package/docs/reference/API.md

@@ -1,8 +1,15 @@
 # UAP Programmatic API Reference
 
-> Public API of the `@miller-tech/uap` package. Version v1.40.0.
+> Public API of the `@miller-tech/uap` package. Version v1.93.1.
 
-Install and import:
+> **🏭 Where this fits:** Cross-cutting — the machine parts behind the line.
+> **What it delivers:** when the `uap` CLI isn't the right shape for your job,
+> these exports let you wire UAP's memory, routing, coordination, and MCP
+> stations straight into your own tools and drive the [delivery pipeline](../guides/DELIVERY_PIPELINE.md)
+> from your own code.
+
+If the CLI is the control panel, this is the parts bin — the same subsystems,
+exposed so you can bolt them into your own harness. Install and import:
 
 ```bash
 npm install @miller-tech/uap

package/docs/reference/CLI.md

@@ -1,13 +1,19 @@
 # UAP CLI Reference
 
 > Complete command reference for the Universal Agent Protocol command-line interface (`uap`).
-> Version v1.50.0.
-
-The `uap` binary is the single entry point for every UAP capability: project
-initialization, the tiered memory system, git worktree workflow, multi-agent
-coordination, task management, the multi-model architecture, the MCP router,
-policy enforcement, the delivery convergence loop, and platform hook
-management.
+> Version v1.93.1.
+
+> **🏭 Where this fits:** Every station — this is the control panel for the whole
+> line. **What it delivers:** one binary that drives each stage of your
+> [delivery pipeline](../guides/DELIVERY_PIPELINE.md), from understanding the work
+> to shipping it safely, so you operate the factory from a single door.
+
+The `uap` binary is the single entry point for every UAP capability — the
+control panel for the whole line. From here you run project initialization, the
+tiered memory system (Intake/Feedback), the git worktree workflow (Isolation),
+multi-agent coordination (Line coordination), task management, the multi-model
+architecture (Prep/Routing), the MCP router, policy enforcement (cross-cutting),
+the delivery convergence loop (Build → QC/Verify), and platform hook management.
 
 ```bash
 uap --help          # top-level command list

package/docs/reference/CONFIGURATION.md

@@ -1,9 +1,15 @@
 # Configuration Reference
 
-> Universal Agent Protocol (UAP) v1.40.0
+> Universal Agent Protocol (UAP) v1.93.1
 
-All configuration surfaces below are verified against source. Only options that
-exist in code are documented here.
+> **🏭 Where this fits:** Cross-cutting — the settings that tune every station.
+> **What it delivers:** the dials that decide how your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)
+> runs — where memory lives, which model builds, how strict the gates are — so
+> the line behaves the way your project needs.
+
+Think of this as the machine's control settings: the values that tune each
+station on the line. All configuration surfaces below are verified against
+source. Only options that exist in code are documented here.
 
 ## Config files
 

package/docs/reference/DATABASE_SCHEMA.md

@@ -1,11 +1,18 @@
 # Database Schema Reference
 
-> Universal Agent Protocol (UAP) v1.40.0
-
-UAP persists state in a set of SQLite databases (via `better-sqlite3`, WAL mode)
-plus a Qdrant vector store for semantic search. All schemas below are grounded
-in source. Paths are resolved relative to the project working directory unless
-noted otherwise.
+> Universal Agent Protocol (UAP) v1.93.1
+
+> **🏭 Where this fits:** Cross-cutting — the shop's records and shift log.
+> **What it delivers:** the durable memory of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)
+> — tasks, coordination, policies, and what the floor has learned — so nothing a
+> station knows is lost when the session ends.
+
+These databases are the factory's paperwork: the job tickets, the coordination
+board, the enforced rulebook, and the long-term memory that lets tomorrow's
+session pick up where today's left off. UAP persists state in a set of SQLite
+databases (via `better-sqlite3`, WAL mode) plus a Qdrant vector store for
+semantic search. All schemas below are grounded in source. Paths are resolved
+relative to the project working directory unless noted otherwise.
 
 ## SQLite databases
 

package/docs/reference/FEATURES.md

@@ -1,14 +1,65 @@
 # Feature Catalog
 
-> Universal Agent Protocol (UAP) v1.40.0
-
-UAP is a universal AI-agent memory, coordination, and enforcement system. This
-catalog groups its features by source subsystem under `src/`. Each entry is a
-code-grounded summary of what the subsystem provides.
-
-## Memory (`src/memory/`)
-
-Hierarchical, tiered memory with semantic recall — the largest subsystem.
+> Universal Agent Protocol (UAP) v1.93.1
+
+> **🏭 Where this fits:** Every station on the line — this catalog is the parts list for the whole factory. **What it delivers:** each feature below is mapped to the stage of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md) it protects, so you can see exactly where your agent's work stops being plausible-looking and starts being genuinely shippable.
+
+Think of getting software out of an agent as a line in a factory. Raw intent
+comes in one end; a working, shipped change comes out the other. Between those
+two points sit eight stations, and typical agentic workflows break at
+predictable ones — the agent forgets what it learned last session, edits the
+wrong file, or (the big one) declares "done" on code that never ran.
+
+UAP is the machinery bolted to that line: memory, coordination, and enforcement
+that keep the work moving from station to station without silently shipping a
+defect. The features below are grouped by source subsystem under `src/`, and
+each entry names the pipeline stage it guards so you can see what it does *for
+you*, not just what it is.
+
+## The line at a glance
+
+Every feature in this catalog serves one of eight stations. When your agent
+"goes wrong," it is almost always because one of these stations had no guard:
+
+1. **Intake** — understand the work. Agents forget past sessions and hallucinate
+   scope; 4-tier memory, reactor per-prompt injection, and DESIGN.md keep intent
+   grounded.
+2. **Prep / Routing** — send the right job to the right station. Pattern router,
+   query-complexity scoring, and multi-model routing stop over- and
+   under-thinking.
+3. **Isolation** — give each job its own bench. Worktree-per-feature, always-on
+   file coordination, and the delivery gate keep agents off `main` and out of
+   each other's files.
+4. **Build** — make the thing. The deliver convergence loop, serving-layer
+   recipes, and proxy/local-model guardrails turn plausible-but-wrong output
+   into real files.
+5. **QC / Verify** — prove it runs. **The station everyone skips.** Completion
+   gates, execution/runtime verification, the acceptance judge, and a
+   generator≠evaluator split mean "done" is checked by something other than the
+   model that wrote the code.
+6. **Line coordination** — many workers, one floor. The coordination DB, the
+   collaboration board with challenge mode, model-slot concurrency, and deploy
+   batching keep parallel agents from colliding or deadlocking.
+7. **Shipping** — out the door safely. The worktree→PR flow, version/completion
+   gates, the CI feedback watcher, and git-safety stop regressions and force-push
+   disasters.
+8. **Feedback** — the floor learns. Memory promotion, pattern reinforcement, and
+   session analysis make sure the same mistake doesn't recur every session.
+
+Two things run *across* every station: **policy gates** turn your rules into
+executable checks enforced at each bench (not prose in a README), and the **MCP
+router** keeps the context window lean so the line stays fast. It all works
+across 9 agent harnesses.
+
+## Memory (`src/memory/`) — Intake & Feedback
+
+> **Stage: Intake / Feedback.** Your agent walks onto the floor every session
+> with amnesia. This subsystem is its long-term memory of what the shop already
+> learned, so it stops re-discovering the same facts and re-making the same
+> mistakes.
+
+Hierarchical, tiered memory with semantic recall — the largest subsystem, and
+the reason a UAP agent picks up where the last one left off.
 
 | Feature | Description |
 |---------|-------------|
@@ -23,7 +74,7 @@ Hierarchical, tiered memory with semantic recall — the largest subsystem.
 | Speculative cache (`speculative-cache.ts`) | Pre-fetches likely-needed memory. |
 | Consolidator / maintenance (`memory-consolidator.ts`, `memory-maintenance.ts`) | Consolidate and garbage-collect memory over time. |
 | Write gate (`write-gate.ts`) | Quality filter for what gets written to memory. |
-| Daily log (`daily-log.ts`) | Staging log with promotion (`gate_score`) to long-term memory. |
+| Daily log (`daily-log.ts`) | Staging log with promotion (`gate_score`) to long-term memory — the Feedback path where a session's lessons graduate to permanent knowledge. |
 | Correction propagation (`correction-propagator.ts`) | Supersedes stale entries when corrections are made. |
 | Predictive memory (`predictive-memory.ts`) | Learns query patterns to predict needed context. |
 | Knowledge graph (`knowledge-graph.ts`) | L4 entity/relationship graph. |
@@ -33,7 +84,12 @@ Hierarchical, tiered memory with semantic recall — the largest subsystem.
 | Prepopulate (`prepopulate.ts`) | Seeds memory and discovers skills for CLAUDE.md generation. |
 | Terminal-bench knowledge (`terminal-bench-knowledge.ts`) | Curated benchmark knowledge. |
 
-## Models (`src/models/`)
+## Models (`src/models/`) — Prep / Routing
+
+> **Stage: Prep / Routing.** The wrong worker on the wrong job wastes the whole
+> shift. This subsystem sizes up each task and routes it to the right model and
+> the right amount of thinking — no more over-planning a one-liner or
+> under-powering a refactor.
 
 Multi-model, two-tier (planner/executor) architecture.
 
@@ -47,7 +103,12 @@ Multi-model, two-tier (planner/executor) architecture.
 | Analytics (`analytics.ts`) | Per-task token/cost/outcome metrics (`model_analytics.db`). |
 | OpenAI-compat client (`openai-compat-client.ts`) | OpenAI `/v1`-compatible client (default endpoint `http://localhost:4000/v1`). |
 
-## Coordination (`src/coordination/`)
+## Coordination (`src/coordination/`) — Line coordination & Prep
+
+> **Stage: Line coordination.** Put many agents on one floor and they collide,
+> duplicate work, or deadlock. This layer is the shop foreman: it tracks who is
+> doing what, routes work by capability, and batches shipping actions so nobody
+> trips over anybody.
 
 Multi-agent coordination layer.
 
@@ -58,10 +119,14 @@ Multi-agent coordination layer.
 | Capability router (`capability-router.ts`) | Routes tasks to droids by capability. |
 | Auto-agent (`auto-agent.ts`) | Auto-agent driver. |
 | Pattern router (`pattern-router.ts`) | Matches tasks to execution patterns; always includes P12/P35. |
-| Adaptive patterns (`adaptive-patterns.ts`) | Tracks pattern success outcomes to adapt selection. |
+| Adaptive patterns (`adaptive-patterns.ts`) | Tracks pattern success outcomes to adapt selection — Feedback that makes routing smarter over time. |
 | Expert orchestrator (`expert-orchestrator.ts`) | Orchestrates parallel expert/droid review. |
 
-## Tasks (`src/tasks/`)
+## Tasks (`src/tasks/`) — Intake & Line coordination
+
+> **Stage: Intake / Line coordination.** Work that isn't written down gets
+> dropped or done twice. This is the job ticket system — what needs doing, what
+> blocks what, and who has claimed the bench.
 
 Task management system (positioned as an alternative to Beads).
 
@@ -73,7 +138,11 @@ Task management system (positioned as an alternative to Beads).
 | Decoder gate (`decoder-gate.ts`) | Full decoder-first (P35) validator. |
 | Event bus (`event-bus.ts`) | `TaskEventBus` for task lifecycle events. |
 
-## Policies (`src/policies/`)
+## Policies (`src/policies/`) — Cross-cutting enforcement
+
+> **Stage: Every station.** Rules written in a README are suggestions your agent
+> ignores. This engine turns them into executable checks fired at each bench, so
+> a policy actually *blocks* the wrong move instead of politely hoping.
 
 DB-driven policy enforcement engine.
 
@@ -86,10 +155,16 @@ DB-driven policy enforcement engine.
 | CLAUDE.md conversion (`convert-policy-to-claude.ts`) | Renders policies into CLAUDE.md. |
 | Enforcers (`enforcers/`) | ~20 Python enforcers (worktree_required, test_gate, schema_diff_gate, memory_before_plan, coord_overlap, mcp_router_first, rtk_wrap, iac_parity, expert_review_required, etc.). |
 
-## Delivery (`src/delivery/`)
+## Delivery (`src/delivery/`) — Build & QC / Verify
 
-Convergence loop that drives a model through execute → apply → verify → feedback
-against real completion gates until "delivered".
+> **Stage: Build → QC / Verify.** This is where the sausage actually gets made,
+> and where the biggest agentic failure lives: declaring "done" on code that
+> doesn't compile or run. The convergence loop drives a model through
+> execute → apply → verify → feedback against your real completion gates until it
+> is genuinely *delivered* — not just claimed.
+
+A loop that keeps building and re-checking until the work passes the same gates
+you'd run by hand.
 
 | Feature | Description |
 |---------|-------------|
@@ -97,15 +172,19 @@ against real completion gates until "delivered".
 | Run coordinator (`run-coordinator.ts`) | Coordinates a delivery run. |
 | Explorer (`explorer.ts`) | Best-of-N candidate generation. |
 | Applier (`applier.ts`) | Applies file changes. |
-| Verifier ladder (`verifier-ladder.ts`) | Build/typecheck/test/lint gate ladder. |
-| Judge / critic (`judge.ts`, `critic.ts`) | Evaluate and critique turns. |
+| Verifier ladder (`verifier-ladder.ts`) | Build/typecheck/test/lint gate ladder — the QC checks that prove it runs. |
+| Judge / critic (`judge.ts`, `critic.ts`) | Evaluate and critique turns with a grader distinct from the builder (generator≠evaluator). |
 | Escalation (`escalation.ts`) | Stagnation escalation ladder. |
 | Auto-optimizer (`auto-optimizer.ts`) | Dynamically enables aids. |
 | Ideation / practice / spec-imports | Divergent strategy seeds, best-practice cards, curated project seeds. |
 | HALO trace (`halo-trace.ts`) | Emits HALO spans. |
-| Integrity (`integrity.ts`) | Test-protection / integrity guard. |
+| Integrity (`integrity.ts`) | Test-protection / integrity guard — stops the model from gutting the tests to "pass." |
+
+## MCP Router (`src/mcp-router/`) — Cross-cutting (lean context)
 
-## MCP Router (`src/mcp-router/`)
+> **Stage: Every station.** A stuffed context window slows and confuses the whole
+> line. This router keeps it lean so every station runs on the signal that
+> matters.
 
 Hierarchical MCP router that collapses 150+ MCP tools to 2
 (`discover_tools`, `execute_tool`) for ~98% token reduction.
@@ -121,7 +200,10 @@ Hierarchical MCP router that collapses 150+ MCP tools to 2
 | Experts (`experts/registry.ts`) | Expert-consult registry. |
 | Tools (`tools/`) | `discover`, `execute`, `deliver` handlers. |
 
-## Dashboard (`src/dashboard/`)
+## Dashboard (`src/dashboard/`) — Observability
+
+> **Stage: Watching the floor.** You can't fix a line you can't see. The
+> dashboard is the control-room view of tasks, agents, memory, and models.
 
 | Feature | Description |
 |---------|-------------|
@@ -130,28 +212,42 @@ Hierarchical MCP router that collapses 150+ MCP tools to 2
 | Server (`server.ts`) | Web dashboard server (default port 3847). |
 | Data seeder (`data-seeder.ts`) | Seeds demo/initial dashboard data. |
 
-## Analyzers & Generators
+## Analyzers & Generators — Intake
+
+> **Stage: Intake.** Before the line can run, it has to understand the shop it's
+> working in. These build a picture of your project and generate the agent
+> context files from it.
 
 | Subsystem | Description |
 |-----------|-------------|
 | Analyzers (`analyzers/`) | `analyzeProject(cwd)` builds a `ProjectAnalysis` (languages, frameworks, dirs) from `.uap.json`, git, package files. |
 | Generators (`generators/claude-md.ts`) | Handlebars-based CLAUDE.md / web AGENT.md generation from analysis + discovered skills. |
 
-## Observability & Telemetry
+## Observability & Telemetry — Feedback
+
+> **Stage: Feedback.** Traces are how the floor learns *why* it stalled. Opt-in
+> spans feed the HALO engine so systemic failures surface instead of repeating.
 
 | Subsystem | Description |
 |-----------|-------------|
 | Observability (`observability/halo-exporter.ts`) | Emits agent/LLM/tool spans as OTLP/OpenInference JSONL for the HALO engine. Opt-in via `UAP_HALO_TRACE`; zero-overhead when off. |
 | Telemetry (`telemetry/session-telemetry.ts`) | Session-level telemetry capture. |
 
-## Browser & Benchmarks
+## Browser & Benchmarks — QC / Verify
+
+> **Stage: QC / Verify.** Real proof beats a confident claim. The browser wrapper
+> lets an agent actually drive a page, and the benchmark harness measures a plain
+> agent against a UAP-augmented one.
 
 | Subsystem | Description |
 |-----------|-------------|
 | Browser (`browser/web-browser.ts`) | `WebBrowser` automation wrapper for agents. |
 | Benchmarks (`benchmarks/`) | Benchmark harness comparing a naive agent vs UAP-augmented agent; multi-turn loops, token throughput, speculative autotune. |
 
-## Droids
+## Droids — Line coordination
+
+> **Stage: Line coordination.** Specialist reviewers on call. The expert-droid
+> roster gives the orchestrator a bench of named experts to run in parallel.
 
 The expert-droid roster lives as markdown-with-JSON-frontmatter files under
 `.factory/droids/*.md`, discovered at runtime by `discoverDroids()` in
@@ -159,18 +255,19 @@ The expert-droid roster lives as markdown-with-JSON-frontmatter files under
 schema and exposes `uap_droid_list` / `uap_droid_invoke`, plus the
 decoder-first (P35) and worktree gates. See `docs/reference/EXPERT_DROIDS.md`.
 
-## Utilities (`src/utils/`)
+## Utilities (`src/utils/`) — Cross-cutting
 
-Shared helpers: adaptive cache, concurrency pools (retry/timeout/fallback),
-config loader, lazy imports, structured logger, CLAUDE.md merge, performance
-monitor, query-complexity scoring, rate limiter, string similarity, and system
-resource detection.
+Shared helpers that keep the rest of the line reliable: adaptive cache,
+concurrency pools (retry/timeout/fallback), config loader, lazy imports,
+structured logger, CLAUDE.md merge, performance monitor, query-complexity
+scoring (the Prep-stage signal that sizes a task), rate limiter, string
+similarity, and system resource detection.
 
 ## CLI surface (`src/bin/cli.ts`)
 
-The `uap` CLI exposes (top-level commands): `init`, `setup`, `analyze`,
-`generate`, `memory`, `patterns`, `worktree`, `sync`, `droids`, `expert-route`,
-`deliver`, `harness` (HALO), `ideate`, `coord`, `agent`, `deploy`, `task`,
-`compliance`, `coordination`, `skill`, `update`, `dashboard` (alias `dash`),
-`model`, `mcp-router`, `hooks`, `tool-calls`, `rtk`, `mcp-setup`, `schema-diff`,
-`policy`, `uap-omp`.
+The `uap` CLI is the single door into the whole factory (top-level commands):
+`init`, `setup`, `analyze`, `generate`, `memory`, `patterns`, `worktree`,
+`sync`, `droids`, `expert-route`, `deliver`, `harness` (HALO), `ideate`,
+`coord`, `agent`, `deploy`, `task`, `compliance`, `coordination`, `skill`,
+`update`, `dashboard` (alias `dash`), `model`, `mcp-router`, `hooks`,
+`tool-calls`, `rtk`, `mcp-setup`, `schema-diff`, `policy`, `uap-omp`.

package/docs/reference/PATTERNS.md

@@ -1,18 +1,32 @@
 # Pattern Library Reference
 
-> Universal Agent Protocol (UAP) v1.40.0
-
-UAP ships an execution-pattern library: a set of reusable problem-solving
-strategies that are matched to the current task and surfaced to the agent.
-Patterns are defined as markdown files under `.factory/patterns/`, catalogued
-in `.factory/patterns/index.json`, and retrieved on demand via a Qdrant-backed
+> Universal Agent Protocol (UAP) v1.93.1
+
+> **🏭 Where this fits:** Prep / Routing — before your agent starts cutting, it
+> should pick the right technique for the job. **What it delivers:** the right
+> proven playbook is matched to the task and handed to your agent, so it stops
+> improvising an approach that quietly breaks the [delivery pipeline](../guides/DELIVERY_PIPELINE.md)
+> two stations later.
+
+Left to itself, an agent invents a fresh (and often wrong) approach for every
+task. UAP's execution-pattern library is a rack of proven playbooks — reusable
+problem-solving strategies — that get matched to what you're actually doing and
+handed to the agent before it acts. That's the Prep/Routing station: right job,
+right technique, right bench.
+
+Several of these patterns are quietly the guardrails on the QC station too —
+they exist because agents love to skip verification. Patterns are defined as
+markdown files under `.factory/patterns/`, catalogued in
+`.factory/patterns/index.json`, and retrieved on demand via a Qdrant-backed
 RAG flow (`uap patterns query`).
 
 ## The 23 Patterns
 
 The canonical roster lives in `.factory/patterns/index.json`. Each pattern has
 a numeric (or string) id, a markdown body file, a title, an abbreviation, a
-category, and a keyword set used for retrieval.
+category, and a keyword set used for retrieval. The `Verification` category is
+the QC/Verify station in playbook form — the checks that turn "looks done" into
+"proven done."
 
 | ID | Title | Abbreviation | Category | What it does |
 |----|-------|--------------|----------|--------------|
@@ -42,20 +56,22 @@ category, and a keyword set used for retrieval.
 
 ### Always-on patterns
 
-Two patterns are unconditionally included regardless of the matched task, set
-in `src/coordination/pattern-router.ts`:
+Two patterns are the non-negotiable QC guards on the line — bolted on
+unconditionally regardless of the matched task, set in
+`src/coordination/pattern-router.ts`:
 
 ```js
 const alwaysIncludeIds = ['P12', 'P35']; // Output Existence, Decoder-First
 ```
 
-- **P12 (Output Existence Verification)** — guards against "claiming done"
-  without producing the artifact.
+- **P12 (Output Existence Verification)** — the anti-"claiming done" guard:
+  no artifact, no done.
 - **P35 (Decoder-First Analysis)** — anchors format/reverse-engineering work.
 
 ## How pattern RAG works
 
-Pattern retrieval is semantic, not keyword-based. The flow:
+Pattern retrieval is semantic, not keyword-based — the router matches on what
+the task *means*, not just the words in it. The flow:
 
 1. **Indexing** (`uap patterns index`) runs a generated Python indexer
    (`agents/scripts/index_patterns_to_qdrant.py`). It scans multiple sources —