@miller-tech/uap 1.93.0 → 1.94.0

package/docs/design/UAP_REACTOR.md

@@ -5,16 +5,28 @@ Goal: every UAP capability that is appropriate to apply automatically fires
 automatically and *dynamically* (context-aware) across all supported coding
 agents, instead of requiring manual invocation.
 
+> **🏭 Where this fits:** Intake & Prep/routing stations (with a cross-cutting
+> enforce arm) — a capability nobody remembers to invoke never fires, so your
+> agent walks into the work without the right memory, expert, skill, or model
+> and skips the gates it should have hit. **What it delivers:** per-prompt,
+> context-aware auto-application — the right context is injected at intake and
+> routing without you asking, and the hard gates fire on their own — so the
+> [delivery pipeline](../guides/DELIVERY_PIPELINE.md)'s stations run themselves
+> instead of relying on the agent's memory.
+
 ## 1. Two modes (never conflated)
 
 - **Enforce** — deterministic, hard gates that must always fire (worktree,
   policy/compliance, delivery, schema-diff, completion). These *block*
-  (exit 2 / throw). Already largely wired; this feature fills the gaps.
+  (exit 2 / throw). Already largely wired; this feature fills the gaps. (These
+  are the station gates across isolation, build, QC, and shipping.)
 - **Assist** — capabilities that *should* fire when contextually appropriate
   (memory recall, pattern RAG, expert-route, skill surfacing, model routing,
   task linking). These *inject context* the model sees — raising the odds it
   uses the right tool without removing judgement. Optionally **auto-spawn**
-  an expert above a confidence threshold for whitelisted task types.
+  an expert above a confidence threshold for whitelisted task types. (This is
+  the intake/routing work: getting the right context and approach onto the belt
+  before the agent commits.)
 
 ## 2. Architecture: one resolver, many adapters
 
@@ -107,6 +119,9 @@ export function resolve(
 
 ## 4. Feature → auto-application matrix
 
+Each row is a station capability the reactor fires on your behalf, tagged by
+mode (Assist = intake/routing context; Enforce = a station gate):
+
 | Feature | Trigger | Mode |
 |---|---|---|
 | memory recall | per-prompt (semantic on prompt) | Assist |

package/docs/getting-started/CONFIGURATION.md

@@ -1,15 +1,22 @@
 # 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.
+> **🏭 Where this fits:** The control panel for the whole line — every station's knobs in one place. **What it delivers:** sensible defaults out of the box (via `uap setup`), and precise control when you want to tune how your [delivery pipeline](../guides/DELIVERY_PIPELINE.md) behaves.
+
+Most of the time you won't touch any of this — `uap init` / `uap setup` write a
+working `.uap.json` and a `.uap/proxy.env` for you, and the wizard picks sensible
+defaults for every station on the line. But when you're ready to tune how your
+delivery line behaves, this is the page. UAP is configured through the
+project-level `.uap.json` file plus a set of environment variables, and every
+option below actually exists in the code, so you can adjust it by hand with
+confidence. The proxy auto-loads `.uap/proxy.env`, so model wiring you set there
+is picked up automatically.
 
 ## 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.
+unknown keys and bad types are rejected, so a typo fails loudly instead of
+silently doing the wrong thing. Every section is optional except `project`;
+defaults are applied for anything you omit.
 
 ```json
 {
@@ -177,7 +184,9 @@ compare, presets, select, export, health) and `uap dashboard models`.
 
 ## Environment variables
 
-These are the environment variables read by the code.
+These are the environment variables read by the code. You'll usually leave them
+alone — the wizard writes what's needed into `.uap/proxy.env` — but here's the
+full set for when you want to override something.
 
 ### Memory & Qdrant
 

package/docs/getting-started/INSTALLATION.md

@@ -1,11 +1,22 @@
 # 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.50.0) that installs the `uap` CLI.
+> **🏭 Where this fits:** Setting up the floor — before any station can run, UAP has to be installed and wired into your agent harness. **What it delivers:** one `npm install` + one `uap setup` and every station on the [delivery pipeline](../guides/DELIVERY_PIPELINE.md) is live in your project.
+
+Welcome. The Universal Agent Protocol (UAP) is the discipline layer that turns
+your AI agent into a reliable member of your software delivery line. Left to its
+own devices an agent forgets what it learned yesterday, picks the wrong approach,
+edits your main branch, writes plausible-but-wrong code, and cheerfully declares
+"done" on something that never actually ran. UAP puts a station at each of those
+break points so the work that comes off the line is trustworthy.
+
+It ships as a single npm package (`@miller-tech/uap`, v1.93.1) that installs the
+`uap` CLI. This page gets it onto your machine and wired into your project.
 
 ## Prerequisites
 
+You don't need all of these to start — UAP works with just Node, and turns on
+more stations as you provide the pieces.
+
 | Requirement | Needed for | Notes |
 | --- | --- | --- |
 | **Node.js >= 18** | Everything | The CLI is published as ESM and requires Node 18 or newer. |
@@ -14,9 +25,10 @@ CLAUDE.md protocol enforcement. It ships as a single npm package
 | **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.
+If you skip Docker, Python, or a local model, those steps are simply skipped and
+the matching features (semantic recall, pattern RAG, the convergence harness) sit
+dormant until you provide them later. Nothing breaks — you just start with fewer
+stations lit up.
 
 ## Install
 
@@ -32,7 +44,7 @@ npm install -g @miller-tech/uap
 uap --version
 ```
 
-This prints the installed package version (e.g. `1.50.0`).
+This prints the installed package version (e.g. `1.93.1`).
 
 ## One-command setup
 
@@ -42,14 +54,21 @@ From the root of the project you want to wire up, run:
 uap setup
 ```
 
-`uap setup` is a **guided, arrow-key wizard by default** (powered by
-@clack/prompts). It walks you through the configuration — harnesses, memory
-tiers, coordination, patterns, policies, model provider/profile, hooks — with
-**smart defaults inferred from your environment** (Docker → offer Qdrant; a
-detected local model endpoint → preselect the local provider/profile). Press
-Enter to accept the recommended path. On a non-TTY/CI run, or with
-`--non-interactive`/`-y`, it runs the same flow non-interactively with defaults
-so pipelines never hang on a prompt.
+`uap setup` is a **friendly, arrow-key guided wizard by default** (powered by
+@clack/prompts). It walks you through the whole delivery line, one station at a
+time — memory tiers so your agent remembers, patterns and the policy engine so it
+follows your rules, your model provider/profile, harness hooks, the browser
+dashboard, and the newer stations too: **recipes and the escalation judge,
+delivery gates, model-slot concurrency, cross-agent collaboration, DESIGN.md, and
+the reactor**. Each prompt comes with a **smart default inferred from your
+environment** (Docker → offer Qdrant; a detected local model endpoint →
+preselect the local provider/profile), so you can usually just press Enter to
+accept the recommended path.
+
+When it finishes, setup writes your `.uap.json` and a `.uap/proxy.env` (the proxy
+auto-loads that env file, so your model wiring is picked up automatically). On a
+non-TTY/CI run, or with `--non-interactive`/`-y`, it runs the same flow
+non-interactively with defaults so pipelines never hang on a prompt.
 
 Before it changes anything, setup **backs up your existing agent instruction
 files** (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, …, plus `.uap.json`) to
@@ -135,10 +154,10 @@ to overwrite existing configuration.
 
 ## Installing harness hooks
 
-UAP supports nine AI coding harnesses: **Claude Code, Factory, Cursor, VSCode,
+UAP works with 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.
+for the platforms it finds in your project automatically, but you can install or
+re-install them by hand any time.
 
 Install hooks for every detected harness:
 

package/docs/getting-started/QUICKSTART.md

@@ -1,8 +1,10 @@
 # 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.
+> **🏭 The big idea:** UAP is the discipline layer for your AI delivery line — memory so agents remember, isolation so they don't clobber your repo, real verification so "done" means it actually runs, and coordination so many agents don't collide. See the [delivery pipeline](../guides/DELIVERY_PIPELINE.md) for the full station-by-station tour.
+
+Let's get you from a clean checkout to your first delivered task in about five
+minutes. This assumes you've already installed the CLI — head to
+[Installation](./INSTALLATION.md) first if not.
 
 ## 1. Set up your project (~1 min)
 
@@ -12,12 +14,13 @@ From the root of your project:
 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.
+This lights up the delivery line: it 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 also writes
+a `.uap/proxy.env` that the proxy auto-loads, so your model wiring is ready to
+go. It finishes with a summary showing which steps succeeded.
 
-Confirm memory is healthy:
+Confirm memory — the station that lets your agent remember — is healthy:
 
 ```bash
 uap memory status
@@ -28,7 +31,8 @@ long-term endpoint reported at `http://localhost:6333`.
 
 ## 2. Store and query a memory (~1 min)
 
-Write a learning into long-term memory:
+This is the intake station: instead of starting every task from zero, your agent
+keeps what it learns. 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
@@ -37,7 +41,7 @@ uap memory store "API keys are loaded from the QDRANT_API_KEY env var" -t config
 `-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:
+Now query it back semantically — you don't need the exact words, just the idea:
 
 ```bash
 uap memory query "where do api keys come from"
@@ -49,9 +53,10 @@ matching entries with their similarity scores. Tune results with
 
 ## 3. Run `uap deliver` on a small task (~2 min)
 
-`uap deliver` is the convergence harness: it iterates a model against your
+`uap deliver` is the build-and-QC station: 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.
+required gate passes or the turn budget is exhausted. This is how "done" stops
+meaning "the model said so" and starts meaning "the code actually passed".
 
 First do a dry run to see the detected gates and plan without calling a model:
 
@@ -69,7 +74,7 @@ When the plan looks right, run it for real:
 uap deliver "fix the failing test in src/utils/dates"
 ```
 
-Notes on behaviour:
+A few things worth knowing:
 
 - The default model preset is `qwen35-a3b` (override with `-m <preset>` or the
   `UAP_DELIVER_MODEL` env var).
@@ -86,7 +91,8 @@ Notes on behaviour:
 
 ## 4. View the dashboard (~1 min)
 
-UAP ships a rich terminal dashboard. View the full system overview:
+UAP ships a rich terminal dashboard so you can watch the line from above. View
+the full system overview:
 
 ```bash
 uap dashboard overview

package/docs/guides/AUTOMATIC.md

@@ -2,11 +2,19 @@
 
 > **Install once. Every feature kicks in automatically.**
 
+> **🏭 Where this fits:** CROSS-CUTTING — this is what breaks in most agentic
+> setups: the safeguards exist but nobody remembers to run them, so the line
+> only runs as well as the operator's discipline that day. **What it delivers:**
+> the line runs itself — the right station on your [delivery
+> pipeline](./DELIVERY_PIPELINE.md) activates automatically for each task, with
+> no flags to set and nothing to remember.
+
 UAP is not a set of manual steps you orchestrate. It is a **policy-and-resolver
 layer** that sits between your coding agent (Claude Code, Opencode, Cursor,
 Windsurf, Codex, etc.) and the model you use. Every feature below activates
 **automatically** based on what the agent is doing — no config changes, no
-manual triggers, no prompts to remember.
+manual triggers, no prompts to remember. Each one guards a different station on
+the delivery line so the whole thing keeps running without you standing over it.
 
 ---
 

package/docs/guides/AUTOMATIC_FEATURES.md

@@ -1,6 +1,12 @@
 # UAP Automatic Features — What Fires When
 
-Install UAP (`npm i -g universal-agent-protocol`) and every feature below activates automatically. There are no flags to set, no config to edit. UAP observes your workflow and injects the right capability at the right time.
+> **🏭 Where this fits:** CROSS-CUTTING — this is what breaks in a normal
+> agentic workflow: every safeguard is a manual step, so the one you forget is
+> the one that bites you. **What it delivers:** every station on your [delivery
+> pipeline](./DELIVERY_PIPELINE.md) fires automatically at the right moment —
+> the line runs itself, no flags to set, no config to remember.
+
+Install UAP (`npm i -g universal-agent-protocol`) and every feature below activates automatically. There are no flags to set, no config to edit. UAP observes your workflow and injects the right capability at the right time — the right station on the line kicking in for each task, without you routing work by hand.
 
 ---
 

package/docs/guides/COORDINATION.md

@@ -1,6 +1,8 @@
 # Multi-Agent Coordination
 
-> UAP v1.40.0
+> UAP v1.93.1
+
+> **🏭 Where this fits:** LINE COORDINATION — the station where parallel agents on the [delivery pipeline](./DELIVERY_PIPELINE.md) quietly step on each other: two of them editing the same file, duplicating work, or deadlocking at merge. **What it delivers:** agents register, announce what they're about to touch, and check for overlaps *before* they start — so the line runs many workers at once and still stays conflict-free.
 
 When multiple agents work a codebase in parallel, the expensive failure is two
 of them editing the same file at the same time and colliding at merge. UAP's
@@ -34,7 +36,8 @@ and routing/pattern helpers. The CLI entry points are
 
 ## The announce / overlaps workflow
 
-The recommended flow, printed by `uap agent register` itself:
+The recommended flow, printed by `uap agent register` itself — think of it as
+each worker calling out "I've got this one" before reaching for a part:
 
 ```bash
 # 1. Register (once per agent)

package/docs/guides/DELIVER.md

@@ -1,8 +1,10 @@
 # `uap deliver` — the delivery harness
 
+> **🏭 Where this fits:** BUILD + QC/VERIFY — the two stations where a normal agentic workflow breaks hardest. Your agent writes plausible-but-wrong code (or empty, looping local-model output), then declares "done" on something that never compiled. **What it delivers:** a convergence loop that keeps working the code against your project's *real* gates — build, tests, lint, integration, even a dev deploy — and refuses to call it finished until they actually pass.
+
 `uap deliver` drives a model through a **convergence loop that iterates against your project's real completion gates until the work is actually delivered** — build green, tests passing, lint clean — not until the model *claims* it's done.
 
-It is UAP's answer to "the agent said it finished, but nothing compiles." Instead of a single shot, `deliver` runs an execute → verify → critique → iterate loop, feeding real gate failures back to the model and persisting until the gates pass or the run provably stalls.
+Think of it as the quality-control station on your [delivery pipeline](./DELIVERY_PIPELINE.md): raw code goes in, and nothing leaves the line until it has been inspected against the real definition of done. It is UAP's answer to "the agent said it finished, but nothing compiles." Instead of a single shot, `deliver` runs an execute → verify → critique → iterate loop, feeding real gate failures back to the model and persisting until the gates pass or the run provably stalls.
 
 ```bash
 uap deliver "implement the password reset flow"

package/docs/guides/DELIVERY_PIPELINE.md

@@ -0,0 +1,122 @@
+# The UAP Delivery Pipeline
+
+**A station-by-station tour of where agentic coding actually breaks — and what UAP puts in place to catch it.**
+
+Think of shipping software with an AI agent like running a small factory floor. Raw intent comes in one end; working, verified, merged code should come out the other. In between there are stations — understand the job, set up a workbench, build the thing, check it actually works, ship it — and a break at any one of them quietly ruins everything downstream.
+
+Left to their own devices, coding agents are talented but undisciplined line workers. They forget yesterday's shift, grab the wrong tool, build something that *looks* right, stamp it "done" without plugging it in, and trip over the other workers on the floor. None of that is a model-quality problem you can fix by swapping in a smarter model — it's a *process* problem. UAP is the process: a station at every point where the line usually jams.
+
+Here's the whole floor at a glance, then a walk through each station.
+
+| # | Station | Where a normal agent breaks | What UAP delivers |
+|---|---|---|---|
+| 1 | **Intake** | Starts every session cold; forgets past decisions; invents scope | The agent walks in already knowing your codebase, conventions, and history |
+| 2 | **Prep / routing** | Picks the wrong approach or burns a frontier model on a trivial edit | The right job goes to the right station and the right-sized model |
+| 3 | **Isolation** | Edits `main` directly; clobbers files; two agents overwrite each other | Every job gets its own bench; nothing lands in your working tree by surprise |
+| 4 | **Build** | Produces plausible-but-wrong code, stubs, or (on local models) empty/looping output | Real code that compiles — not scaffolding theatre |
+| 5 | **QC / verify** | Declares "done" on code that never ran, and grades its own homework | "Done" means *verified* done, checked by something other than the author |
+| 6 | **Line coordination** | Parallel agents collide, duplicate work, or deadlock | Agents compound each other's progress instead of fighting over it |
+| 7 | **Shipping** | Regresses on merge, breaks CI, skips the version bump, force-pushes over history | Clean PRs, correct versioning, CI-verified merges |
+| 8 | **Feedback** | Makes the same mistake next session, and the one after | The floor gets a little better every run |
+
+Two things run the length of the whole line: **policy gates** (the rules are *executable hooks that block*, not prose an agent can ignore) and the **MCP Router** (keeps the context window lean so the agent can think). And all of it works across [9 agent harnesses](../reference/PLATFORMS.md) — same line, whichever floor you're standing on.
+
+---
+
+## Station 1 — Intake: understand the work
+
+**The break:** a fresh agent session is amnesiac. It doesn't remember the auth pattern you agreed on last week, the reason you *didn't* use library X, or the shape of your codebase. So it re-derives everything from scratch — and re-makes old mistakes.
+
+**What UAP puts here:**
+- **[4-tier memory](MEMORY.md)** — a daily log, a working cache, semantic recall (Qdrant vectors), and a long-term archive, with write-gates that keep junk and duplicates out. Ask *"how did we handle auth last time?"* and get a real answer.
+- **The reactor** — per-prompt injection of the capabilities, skills, and patterns that match what you just asked for, so relevant context is on the bench before the agent starts.
+- **[DESIGN.md](../../DESIGN.md)** — a design brief the agent interrogates and lints against, so UI work starts from your intent, not its guess.
+
+**Delivered:** the agent shows up already onboarded.
+
+## Station 2 — Prep / routing: the right job to the right station
+
+**The break:** agents over-think a one-line fix and under-think a migration, and they'll happily spend a frontier model's budget rewriting a README.
+
+**What UAP puts here:**
+- **[Multi-model routing](MULTI_MODEL.md)** — cheap tasks go to cheap models, hard tasks get the firepower, across 7 profiles.
+- **Pattern router + query-complexity** — the task is matched to a known [playbook](../reference/PATTERNS.md) and a difficulty tier before work starts.
+- **[Expert droids & skills](DROIDS_AND_SKILLS.md)** — specialist stations (security, tests, performance) that a router recommends per task.
+
+**Delivered:** effort and cost matched to the actual job.
+
+## Station 3 — Isolation: each job gets its own bench
+
+**The break:** an agent editing your working tree directly is one bad diff away from wrecking your afternoon — and two agents in the same repo will overwrite each other.
+
+**What UAP puts here:**
+- **[Worktree workflow](WORKTREE_WORKFLOW.md)** — branch-per-feature, auto-PR, safe cleanup, *enforced* so agents never edit the project root.
+- **Always-on file coordination** — agents announce the files they're touching and same-file edits across agents are blocked live.
+- **The delivery gate** — code changes route through the verified `deliver` path instead of raw edits.
+
+**Delivered:** no more "the agent nuked my working tree."
+
+## Station 4 — Build: actually make the thing
+
+**The break:** this is where "looks right" bites. Agents emit plausible-but-wrong code, quietly replace real files with stubs, and — on cheap local models — spiral into empty or looping output.
+
+**What UAP puts here:**
+- **[`uap deliver`](DELIVER.md)** — a convergence loop that keeps iterating a model against your real gates until the work is actually built.
+- **Serving-layer recipes** — Fusion / Confidence / Ratings / ReMoM run behind the proxy to raise output quality, *escalating to a stronger, distinct judge* when it counts. (A same-model judge — qwen grading qwen — was measured to add nothing, so recipes only spend that budget when a genuinely stronger judge is wired.)
+- **[Local-model handling](LOCAL_MODELS.md)** — the proxy's guardrails (loop-breaker, recon-convergence, the no-tool empty-output guard, path normalization) keep a cheap local model on the rails so it produces real modules, not scaffolding.
+
+**Delivered:** code that compiles, not a convincing mock-up of code that compiles.
+
+## Station 5 — QC / verify: prove it actually works
+
+**The break:** this is the station everyone skips, and it's the expensive one. The agent says "done" on code that doesn't compile, doesn't run, or doesn't do what you asked — and then *grades its own homework* and confirms its own success. A generator that is also its own evaluator will always pass itself.
+
+**What UAP puts here:**
+- **Completion gates** — build, tests, lint, type-check must be green before anything can claim "done."
+- **Execution / runtime verify** (`uap verify`) — the generated code is actually *run* (headless browser, vm-dom, or child process) to prove it works, not just that it parses.
+- **The acceptance judge** — an independent check that the behaviour matches the spec.
+- **Generator ≠ evaluator** — the thing that grades the work is deliberately *not* the thing that wrote it.
+
+**Delivered:** "done" you can trust, because a different checker signed off.
+
+## Station 6 — Line coordination: many workers, one floor
+
+**The break:** fan out to several agents and, without traffic control, they duplicate each other, stomp on shared files, exhaust the inference server's slots, or deadlock waiting on one another.
+
+**What UAP puts here:**
+- **[Coordination service](COORDINATION.md)** — a shared board of who's doing what, with findings, dead-ends, hand-offs, and challenge mode so agents build on each other.
+- **Model-slot concurrency** — a budget + lease so fan-out doesn't exhaust the inference backend's real slot capacity.
+- **[Deploy batching](DEPLOY_BATCHING.md)** — git/deploy actions are batched and de-conflicted.
+
+**Delivered:** more agents make things *faster*, not messier.
+
+## Station 7 — Shipping: out the door safely
+
+**The break:** the last mile is where good work dies — a merge that regresses, a red CI that gets ignored, a skipped version bump, a force-push over someone's history.
+
+**What UAP puts here:**
+- **Worktree → PR flow** with completion and version gates, so merges are clean and versioned.
+- **CI feedback watcher** — when CI goes red after a push, the loop re-converges instead of walking away.
+- **Never-regress + git-safety** — destructive git operations are guarded; passing work stays passing.
+
+**Delivered:** changes reach `main` clean, versioned, and CI-verified.
+
+## Station 8 — Feedback: the floor learns
+
+**The break:** without a memory of what went wrong, an agent re-learns the same lesson every session — forever.
+
+**What UAP puts here:**
+- **Memory promotion** — significant learnings graduate from short-term to long-term memory.
+- **Pattern reinforcement learning** — patterns that work get reinforced; ones that don't fade.
+- **Session analysis** — each session records what got done, what stalled, and why.
+
+**Delivered:** a line that's measurably better next week than it is today.
+
+---
+
+## Where to go next
+
+- New here? Start with the **[Quickstart](../getting-started/QUICKSTART.md)** and let `uap setup` wire the whole line for you.
+- Want the catalog of every station's machinery? See **[Features](../reference/FEATURES.md)**.
+- Want the engineering view of how the stations fit together? See the **[Architecture Overview](../architecture/OVERVIEW.md)**.
+- Care most about the QC station (the one that matters most)? Start with **[`uap deliver`](DELIVER.md)**.

package/docs/guides/DEPLOY_BATCHING.md

@@ -1,10 +1,18 @@
 # Deploy Batching
 
-> UAP v1.40.0
+> UAP v1.93.1
+
+> **🏭 Where this fits:** LINE COORDINATION → SHIPPING — this is the station
+> where parallel agents collide: two push to the same branch within seconds and
+> one gets rejected, or a burst of redundant deploys stampedes CI. **What it
+> delivers:** git and deploy actions are queued, squashed, and deduplicated into
+> one ordered batch — so many agents can ship down the same line without
+> trampling each other.
 
 When several agents work in parallel, they all want to commit, push, merge, and
-deploy at roughly the same time. Left unmanaged, that produces two failure
-modes:
+deploy at roughly the same time. That's the moment a normal agentic workflow
+falls apart at the end of the [delivery pipeline](./DELIVERY_PIPELINE.md). Left
+unmanaged, it produces two failure modes:
 
 - **Merge conflicts** — two agents push to the same branch within seconds of
   each other and the second push is rejected (or worse, races into a conflicted
@@ -15,7 +23,8 @@ modes:
 The deploy batcher solves this by *queueing* git/deploy actions and grouping
 them inside short, per-action-type time windows. Commits to the same branch are
 squashed, duplicate pushes and workflow triggers are deduplicated, and the
-result is executed as a single ordered batch.
+result is executed as a single ordered batch — the line coordinator that keeps
+the shipping station orderly.
 
 The implementation lives in
 [`src/coordination/deploy-batcher.ts`](../../src/coordination/deploy-batcher.ts),

package/docs/guides/DROIDS_AND_SKILLS.md

@@ -1,8 +1,16 @@
 # Droids and Skills
 
-> Applies to UAP **v1.40.0**
+> Applies to UAP **v1.93.1**
 
-UAP ships two complementary extension mechanisms:
+> **🏭 Where this fits:** PREP/ROUTING — this is the station where a
+> generalist agent takes the wrong approach on specialist work: reviewing
+> security like a linter, refactoring without an architect's eye. **What it
+> delivers:** the right specialist station gets put in front of your model
+> *before* it starts — a security auditor for auth work, a language expert for
+> the language at hand — so the approach is right from the first line.
+
+UAP ships two complementary extension mechanisms that decide *who* and *how* at
+the prep stage of your [delivery pipeline](./DELIVERY_PIPELINE.md):
 
 - **Droids** — markdown-defined specialist agents (a reviewer, a language
   expert, an architect). Each droid is a focused persona with its own tools and
@@ -11,7 +19,9 @@ UAP ships two complementary extension mechanisms:
   protocol, a navigation technique, a memory operation).
 
 Droids answer *"who should do this?"*; skills answer *"how is this done?"*. A
-droid can pull in skills when a domain-specific workflow applies.
+droid can pull in skills when a domain-specific workflow applies. Think of them
+as swapping in the right specialist station for the job rather than sending
+everything down one generalist line.
 
 ## What a droid is
 

package/docs/guides/LOCAL_MODELS.md

@@ -1,11 +1,23 @@
 # Running UAP Against Local Models
 
-> UAP v1.40.0
+> UAP v1.93.1
 
-UAP can drive its coding/convergence loop against **local models** served by
-[llama.cpp](https://github.com/ggml-org/llama.cpp) instead of a hosted API.
-This keeps inference on your own hardware (zero per-token cost) and works with
-quantized open-weight models such as Qwen 3.x.
+> **🏭 Where this fits:** BUILD — this is the station where a cheap local model
+> flails: plausible-but-wrong code, empty output, or a loop that never lands a
+> real change. **What it delivers:** the proxy and the convergence loop keep a
+> small, zero-per-token model on the rails so it produces *verified* code
+> instead of stubs — real results on a GPU you already own.
+
+Here's the pain: you *want* to run your agent on a local model — inference on
+your own hardware, zero per-token cost — but on its own a small quantized model
+rarely nails a non-trivial change. It one-shots something that looks right and
+doesn't compile.
+
+Here's the fix: UAP drives its coding/convergence loop against **local models**
+served by [llama.cpp](https://github.com/ggml-org/llama.cpp) instead of a hosted
+API. The loop iterates the model against your real gates until the change is
+verified — that's what turns a modest open-weight model such as Qwen 3.x into a
+productive station on your [delivery pipeline](./DELIVERY_PIPELINE.md).
 
 > **Just want the recommended local setup?** See
 > [Qwen3.6 35B-A3B on llama.cpp, by VRAM tier](QWEN36_LLAMACPP.md) for
@@ -123,8 +135,11 @@ to `http://localhost:4000/v1`.
 | `--deploy`          | On success, queue a commit of applied files into the deploy batcher |
 | `--dry-run`         | Show detected gates and plan without calling the model |
 
-A common local pattern is a cheap local executor that escalates to a hosted
-model only when it stalls:
+A common local pattern is a cheap local executor that escalates to a **stronger,
+distinct** model only when it stalls. This distinction matters: a same-model
+judge (a local model grading its own output) was measured to add no lift —
+escalation only pays off when the model you escalate *to* is genuinely more
+capable than the one that stalled.
 
 ```bash
 uap deliver "implement the retry logic" \

package/docs/guides/MCP_ROUTER.md

@@ -1,6 +1,8 @@
 # MCP Router
 
-> UAP v1.40.0
+> UAP v1.93.1
+
+> **🏭 Where this fits:** CROSS-CUTTING — keeping the context window lean at every station of the [delivery pipeline](./DELIVERY_PIPELINE.md). In a normal agentic workflow every tool call dumps its full result into context, so mostly-irrelevant output crowds out the details your agent actually needs. **What it delivers:** a proxy that compresses tool output before it reaches the model — up to 98% fewer tokens on large results — so the agent keeps room for real work and you spend less per session.
 
 The MCP Router is a token-optimizing proxy that sits between an AI harness and
 its MCP tool servers. It is implemented as 11 modules under

package/docs/guides/MEMORY.md

@@ -1,6 +1,8 @@
 # Memory System
 
-> UAP v1.40.0
+> UAP v1.93.1
+
+> **🏭 Where this fits:** INTAKE + FEEDBACK — the front and back doors of the [delivery pipeline](./DELIVERY_PIPELINE.md). At intake, a fresh agent forgets everything the last session learned and re-hallucinates scope; at feedback, nobody records the lesson, so the same mistake ships again next week. **What it delivers:** a persistent, searchable memory that hands each new agent the relevant past learnings on the way in, and captures durable lessons on the way out — so your team of agents gets smarter every run instead of starting from zero.
 
 The Universal Agent Protocol gives agents a persistent, multi-tier memory so
 that learnings survive across sessions, compactions, and even harness switches.
@@ -14,7 +16,8 @@ only the most relevant ones on demand via semantic search.
 ## The four tiers
 
 Memory flows from a cheap, high-churn staging area down to a durable, searchable
-archive. Each tier has a distinct cost/permanence trade-off.
+archive — think of it as raw notes at the head of the line being refined into
+finished, shelved knowledge. Each tier has a distinct cost/permanence trade-off.
 
 | Tier | Name | Storage | Purpose | Module(s) |
 |------|------|---------|---------|-----------|
@@ -71,7 +74,8 @@ threshold (default `0.35`).
 
 Not every observation deserves to be a memory. The write gate
 ([`write-gate.ts`](../../src/memory/write-gate.ts)) scores incoming content and
-**rejects low-value writes** before they consume storage or pollute recall.
+**rejects low-value writes** before they consume storage or pollute recall —
+quality control at the feedback door, so the archive stays high-signal.
 Rejections include:
 
 - Empty content
@@ -210,7 +214,8 @@ uap memory maintain [-v|--verbose]
 ## How agents use memory
 
 The recommended decision loop (see the project `CLAUDE.md`) wires memory into
-every task:
+every task — pulling context in at intake and pushing lessons back out at
+feedback:
 
 1. **READ** recent context with `uap memory query`.
 2. **QUERY** long-term memory for related learnings (semantic search).