@miller-tech/uap 1.43.2 → 1.43.3

package/docs/INDEX.md

@@ -18,6 +18,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 
 | Doc | What it covers |
 |---|---|
+| [**What UAP Does Automatically**](guides/AUTOMATIC.md) | Every feature in benefit / when-it-kicks-in terms — install once, it all self-applies ⭐ |
 | [**`uap deliver`**](guides/DELIVER.md) | The delivery harness — convergence loop to verified completion ⭐ |
 | [Memory](guides/MEMORY.md) | The 4-tier memory system, write-gates, semantic recall |
 | [MCP Router](guides/MCP_ROUTER.md) | Token-optimizing tool proxy + FTS5 output compression |
@@ -28,6 +29,7 @@ New here? Start with the [project README](../README.md), then [Getting Started](
 | [Deploy Batching](guides/DEPLOY_BATCHING.md) | Conflict-free batched git/deploy actions |
 | [Coordination](guides/COORDINATION.md) | Multi-agent overlap detection |
 | [Local Models](guides/LOCAL_MODELS.md) | Running agents against local llama.cpp / Qwen models |
+| [Qwen3.6 on llama.cpp by VRAM](guides/QWEN36_LLAMACPP.md) | Tiered 8/12/16/24/32 GB setup; how `uap deliver` uplifts small local models |
 
 ## Architecture
 

package/docs/guides/AUTOMATIC.md

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

package/docs/guides/LOCAL_MODELS.md

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

package/docs/guides/QWEN36_LLAMACPP.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.43.2",
+  "version": "1.43.3",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",