@miller-tech/uap 1.40.0 → 1.41.0

package/docs/guides/COORDINATION.md

@@ -0,0 +1,162 @@
+# Multi-Agent Coordination
+
+> UAP v1.40.0
+
+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
+coordination layer lets agents **register**, **announce** what they intend to
+work on, and **check for overlaps** before they start — so parallel work stays
+conflict-free.
+
+The coordination modules live in
+[`src/coordination/`](../../src/coordination/): the shared
+[`service.ts`](../../src/coordination/service.ts) backed by a SQLite store
+([`database.ts`](../../src/coordination/database.ts)), agent lifecycle and
+auto-registration ([`auto-agent.ts`](../../src/coordination/auto-agent.ts)),
+the deploy batcher ([`deploy-batcher.ts`](../../src/coordination/deploy-batcher.ts)),
+and routing/pattern helpers. The CLI entry points are
+[`src/cli/agent.ts`](../../src/cli/agent.ts) and
+[`src/cli/coord.ts`](../../src/cli/coord.ts).
+
+## The model
+
+- **Agents** register with a name, optional capabilities, and an optional
+  worktree branch, and receive an `AGENT_ID`. They send periodic heartbeats so
+  stale agents can be cleaned up.
+- **Work announcements** declare an *intent* (`editing`, `reviewing`,
+  `refactoring`, `testing`, `documenting`) against a *resource* (a file path or
+  other identifier), optionally with affected files, a description, and an
+  estimate in minutes.
+- **Overlap detection** compares your announced resource against active work
+  from other agents and returns a conflict-risk assessment plus a suggestion.
+- **Messaging** lets agents broadcast to a channel or send directly to another
+  agent.
+
+## The announce / overlaps workflow
+
+The recommended flow, printed by `uap agent register` itself:
+
+```bash
+# 1. Register (once per agent)
+uap agent register --name reviewer-1 --worktree feature/042-foo
+#   → prints AGENT_ID=<id>
+
+# 2. Announce what you're about to work on
+uap agent announce --id <id> --resource src/server.ts --intent editing \
+  --description "add request logging" --files src/server.ts --minutes 20
+
+# 3. Check overlaps before editing (anyone can run this, no ID needed)
+uap agent overlaps --resource src/server.ts
+
+# 4. When finished, release the resource
+uap agent complete --id <id> --resource src/server.ts
+```
+
+`announce` immediately reports whether the resource is **CLEAR** or has
+**overlapping work**. For each overlap it lists the other agents, their intent,
+their worktree branch, a conflict-risk badge (`low` → `critical`), and a
+suggestion. When risks exist it may also surface collaboration suggestions,
+including a recommended merge order.
+
+`complete` notifies other agents that the resource is free, so they can safely
+merge.
+
+## CLI reference: `uap agent`
+
+Agent lifecycle, work coordination, and communication.
+
+```bash
+uap agent <action> [options]
+```
+
+| Action       | Purpose | Required options |
+| ------------ | ------- | ---------------- |
+| `register`   | Register a new agent | `--name` |
+| `auto`       | Auto-register an agent that heartbeats (30s) and deregisters on exit | — (`--name` optional) |
+| `heartbeat`  | Send a liveness heartbeat | `--id` |
+| `status`     | Show one agent (`--id`) or all active agents + active work | — |
+| `announce`   | Announce work intent on a resource | `--id`, `--resource`, `--intent` |
+| `complete`   | Mark work complete on a resource (notifies others) | `--id`, `--resource` |
+| `overlaps`   | Show overlaps for a resource, or all active work if none given | — |
+| `broadcast`  | Broadcast a message to a channel | `--id`, `--channel`, `--message` |
+| `send`       | Send a direct message to another agent | `--id`, `--to`, `--message` |
+| `receive`    | Read pending messages | `--id` |
+| `deregister` | Remove an agent | `--id` |
+
+Key options:
+
+- `--name`, `-i/--id`, `--capabilities` (comma-separated), `-w/--worktree`
+  (branch) — registration.
+- `--resource`, `--intent` (`editing|reviewing|refactoring|testing|documenting`),
+  `--description`, `--files` (comma-separated), `--minutes` — announcing work.
+- `-c/--channel` (`broadcast|deploy|review|coordination`), `--message`,
+  `-t/--to`, `--priority` — messaging.
+
+```bash
+# Inspect everything currently in flight
+uap agent status
+
+# Message another agent directly
+uap agent send --id <id> --to <other-id> --message "ready to merge src/a.ts"
+
+# Broadcast on the review channel
+uap agent broadcast --id <id> --channel review --message '{"action":"need-review"}'
+```
+
+## CLI reference: `uap coord`
+
+System-wide coordination status and maintenance.
+
+```bash
+uap coord <status|flush|cleanup> [options]
+```
+
+| Action    | Purpose |
+| --------- | ------- |
+| `status`  | Show active agents, resource claims, the deploy queue, and unread-message counts |
+| `flush`   | Force-execute all pending deploys (see [Deploy Batching](./DEPLOY_BATCHING.md)) |
+| `cleanup` | Mark stale agents as failed and remove expired claims, old messages, and completed entries |
+
+```bash
+uap coord status -v
+uap coord cleanup
+```
+
+## CLI reference: `uap coordination`
+
+Focused overlap checks and resolution.
+
+```bash
+uap coordination <check|resolve> [options]
+```
+
+### `check` — detect overlapping work
+
+```bash
+uap coordination check [--agents <ids|names>] [-r|--resource <resource>] [-v] [--json]
+```
+
+Filters active work by agent and/or resource, then reports overlaps with their
+conflict risk and suggestions. `--json` emits machine-readable output.
+
+### `resolve` — broadcast a resolution
+
+```bash
+uap coordination resolve <overlapId> [--action <assign|merge|delegate>] [--json]
+```
+
+`<overlapId>` is the resource path. The resolution (default `merge`) is
+broadcast on the `coordination` channel so other agents can act on it.
+
+```bash
+uap coordination check --resource src/server.ts
+uap coordination resolve src/server.ts --action merge
+```
+
+## Related
+
+- [Deploy Batching](./DEPLOY_BATCHING.md) — how coordinated commits/pushes are
+  batched to avoid merge conflicts.
+- `uap deliver --coordinate` registers a convergence run with the coordination
+  layer (announce + heartbeat + overlap detection); see
+  [Local Models](./LOCAL_MODELS.md).

package/docs/guides/DELIVER.md

@@ -0,0 +1,115 @@
+# `uap deliver` — the delivery harness
+
+`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.
+
+```bash
+uap deliver "implement the password reset flow"
+```
+
+---
+
+## How it works
+
+The loop lives in `src/delivery/` (15 modules). Each turn:
+
+1. **Explore & plan** — the model reads the relevant code and proposes a change. With best-of-N exploration enabled, several candidate approaches are generated and the most promising is taken (`explorer.ts`).
+2. **Apply** — the applier writes the proposed file changes (`applier.ts`). Pre-existing test files, gate configs, and the transitive imports of your spec files are **protected from being overwritten by default** — the model cannot "pass" by editing the tests. A runtime integrity guard hashes protected files and rejects tampering (`integrity.ts`, `spec-imports.ts`).
+3. **Verify** — the verifier ladder runs your real gates — build, typecheck, test, lint — and scores the turn (`verifier-ladder.ts`). Nothing counts as delivered until the required gates are green.
+4. **Critique & feed back** — failures are turned into structured guidance for the next turn (`critic.ts`); learned best-practice cards can be injected and recorded on success (`practice.ts`).
+5. **Iterate until delivered** — the loop continues. By default it **extends past `--max-turns` up to a ceiling**, stopping early only on genuine stagnation (no score improvement across several turns). On stagnation with `--escalate`, it widens exploration, adds a critic pass, and finally escalates to a stronger model (`escalation.ts`).
+
+```
+        ┌──────────── guidance file (optional) ───────────┐
+        ▼                                                  │
+  explore → apply → verify (build/test/lint) → critique ──┘
+     ▲                        │
+     └──── until delivered ◄──┘   (stops on green gates or stagnation)
+```
+
+---
+
+## Autonomy
+
+`deliver` runs the **whole mission without stopping to ask between phases**. It still reports progress, and you can steer it live through a guidance channel:
+
+```bash
+uap deliver "migrate the auth module to JWT" --guidance-file ./guidance.txt
+# in another shell, append guidance at any time — the loop polls it each turn:
+echo "prefer RS256 and keep the existing /login route" >> ./guidance.txt
+```
+
+---
+
+## Auto-optimization
+
+By default every task is **classified by complexity** and the matching convergence aids turn on automatically (`auto-optimizer.ts`). You don't have to tune anything for the common case. To control it explicitly:
+
+```bash
+uap deliver "big refactor across modules" --optimize   # enable every aid
+uap deliver "trivial typo fix"           --no-auto     # disable dynamic optimization
+```
+
+`--optimize` enables exploration, critic, practices, escalation, ideation, HALO spans, and coordination together.
+
+---
+
+## Options
+
+| Flag | Purpose |
+|---|---|
+| `--max-turns <n>` | Maximum execute→verify iterations before until-delivered extension (default `5`) |
+| `--no-until-delivered` | Disable loop-until-delivered (ON by default: extends past `--max-turns` to the ceiling, stopping on stagnation) |
+| `--ceiling <n>` | Hard turn ceiling for until-delivered (1–50, default `30`) |
+| `-m, --model <preset>` | Model preset (default `$UAP_DELIVER_MODEL` or `qwen35-a3b`) |
+| `--endpoint <url>` | Override the model endpoint (OpenAI-compatible `/v1`) |
+| `--escalate-model <preset>` | Stronger model for escalation (default `$UAP_ESCALATE_MODEL`) |
+| `--temperature <t>` | Sampling temperature (default: execution-profile value) |
+| `--gates <ids>` | Gate subset: `build,typecheck,test,lint` |
+| `--candidates <n>` | Best-of-N exploration: candidates per turn (2–8) |
+| `--critic` | Structured critique of failed turns |
+| `--practices` / `--no-semantic` | Inject/record best-practice cards (keyword retrieval with `--no-semantic`) |
+| `--escalate` | Escalation ladder on stagnation |
+| `--ideate` / `--ideate-project <name>` | Divergent ideation strategy seeds |
+| `--halo` | Emit HALO spans (analyze with `uap harness analyze`) |
+| `--coordinate` | Register the run with the coordination layer |
+| `--deploy` | On success, queue a commit of applied files into the deploy batcher |
+| `--optimize` | Enable every convergence aid |
+| `--no-auto` | Disable dynamic optimization |
+| `--no-protect-tests` | Allow the model to modify pre-existing test files (protected by default) |
+| `--guidance-file <path>` | Poll a file each turn for live operator guidance |
+| `--project-root <path>` | Project whose gates define delivery (default: cwd) |
+| `--dry-run` | Show detected gates and plan without calling the model |
+| `--json` | Emit a JSON result |
+
+---
+
+## Local or frontier models
+
+`deliver` speaks the OpenAI-compatible `/v1` API, so it runs against frontier models or a **local model** (e.g. Qwen on llama.cpp). The default preset `qwen35-a3b` targets a local server; point elsewhere with `--endpoint` / `--model`. See **[Local Models](LOCAL_MODELS.md)**.
+
+```bash
+uap deliver "add a healthcheck endpoint" --model qwen35-a3b --endpoint http://127.0.0.1:8080/v1
+```
+
+---
+
+## Automatic routing & enforcement
+
+- **MCP `deliver` meta-tool** — harnesses with the MCP router can auto-route a coding task into `uap deliver` without a shell call (see [MCP Router](../integrations/MCP_ROUTER.md)).
+- **delivery-enforcement policy** — an optional policy gate that routes source edits through `deliver` rather than ad-hoc writes. It is a cooperative-agent guardrail, not a security boundary (see [Policies](POLICIES.md)).
+
+---
+
+## Dry run first
+
+```bash
+uap deliver "add input validation to the signup form" --dry-run
+```
+
+shows the gates UAP detected and the plan, without spending a single model token — the fastest way to confirm `deliver` understands your project's definition of done.
+
+---
+
+See also: [Architecture overview](../architecture/OVERVIEW.md) · [Policies](POLICIES.md) · [Multi-model routing](MULTI_MODEL.md)

package/docs/guides/DEPLOY_BATCHING.md

@@ -0,0 +1,212 @@
+# Deploy Batching
+
+> UAP v1.40.0
+
+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:
+
+- **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
+  state).
+- **Thundering deploys** — a burst of redundant deploys, duplicate workflow
+  triggers, and a noisy commit history full of one-line commits.
+
+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.
+
+The implementation lives in
+[`src/coordination/deploy-batcher.ts`](../../src/coordination/deploy-batcher.ts),
+with the CLI surface in [`src/cli/deploy.ts`](../../src/cli/deploy.ts).
+
+## How it works
+
+1. An agent **queues** an action (`commit`, `push`, `merge`, `deploy`, or
+   `workflow`) against a target (branch, environment, or workflow name).
+2. Each action gets an `execute_after` timestamp computed from its
+   type-specific batch window. Until that time passes, the action stays
+   `pending`.
+3. If a *similar* pending action already exists for the same type + target, the
+   new one is **merged** into it instead of being queued separately:
+   - `commit` actions are squashed (messages concatenated, file lists unioned).
+   - `push` actions to the same branch are merged.
+   - `workflow` triggers are deduplicated.
+4. **Creating a batch** collects every pending action whose window has elapsed,
+   groups them by `actionType:target`, squashes where possible, and assigns a
+   batch ID.
+5. **Executing a batch** runs the actions. State-dependent actions (`commit`,
+   `push`, `merge`, `deploy`) run sequentially in priority order;
+   `workflow` triggers can run in parallel.
+
+Actions are executed with real tooling: `git add` / `git commit` / `git push`
+(`--force-with-lease` when forced) / `git merge`, `gh workflow run`, and a
+configurable deploy command. Each external command runs under a timeout
+(default 300000 ms / 5 minutes) so a hung process can't block the pipeline.
+
+## Batch windows per action type
+
+Each action type has its own default window. Shorter windows favor speed;
+longer windows favor more batching (fewer, larger operations).
+
+| Action type | Default window | Rationale |
+| ----------- | -------------- | --------- |
+| `commit`    | 30000 ms (30s) | Allows squashing multiple commits |
+| `push`      | 5000 ms (5s)   | Fast for PR creation |
+| `merge`     | 10000 ms (10s) | Moderate safety buffer |
+| `workflow`  | 5000 ms (5s)   | Fast workflow triggers |
+| `deploy`    | 60000 ms (60s) | Safety buffer for deployments |
+
+These defaults are defined as `DEFAULT_DYNAMIC_WINDOWS` in
+`deploy-batcher.ts`. Windows below 1000 ms or above 300000 ms trigger a
+validation warning.
+
+### Configuring windows
+
+Windows can be set per project in `.uap.json` under `deploy.batchWindows`:
+
+```json
+{
+  "deploy": {
+    "batchWindows": {
+      "commit": 60000,
+      "push": 3000,
+      "merge": 15000,
+      "workflow": 5000,
+      "deploy": 60000
+    }
+  }
+}
+```
+
+Any window not set in the file falls back to an environment variable, then to
+the default:
+
+| Window     | Environment variable          |
+| ---------- | ----------------------------- |
+| `commit`   | `UAP_DEPLOY_COMMIT_WINDOW`    |
+| `push`     | `UAP_DEPLOY_PUSH_WINDOW`      |
+| `merge`    | `UAP_DEPLOY_MERGE_WINDOW`     |
+| `workflow` | `UAP_DEPLOY_WORKFLOW_WINDOW`  |
+| `deploy`   | `UAP_DEPLOY_DEPLOY_WINDOW`    |
+
+The batcher also exposes named profiles (`fast`, `safe`, `default`) at the API
+level via `DeployBatcher.fromProfile(...)`.
+
+## Urgent mode
+
+Urgent mode collapses every window to its minimum so a time-sensitive change
+fast-tracks through the queue:
+
+| Action type | Urgent window |
+| ----------- | ------------- |
+| `commit`    | 2000 ms       |
+| `push`      | 1000 ms       |
+| `merge`     | 2000 ms       |
+| `workflow`  | 1000 ms       |
+| `deploy`    | 5000 ms       |
+
+Toggle it from the CLI:
+
+```bash
+uap deploy urgent --on    # enable fast windows
+uap deploy urgent --off   # restore default windows
+```
+
+> Note: `uap deploy urgent` applies to the batcher instance it creates, so it
+> is most useful as part of a session that immediately queues and flushes.
+
+## CLI reference: `uap deploy`
+
+```bash
+uap deploy <queue|batch|execute|status|flush|config|set-config|urgent> [options]
+```
+
+### `queue` — add an action to the batch queue
+
+```bash
+uap deploy queue \
+  --agent-id <id> \
+  --action-type <commit|push|merge|deploy|workflow> \
+  --target <branch|environment|workflow> \
+  [options]
+```
+
+`--agent-id`, `--action-type`, and `--target` are required. Type-specific
+options:
+
+| Option              | Applies to | Meaning |
+| ------------------- | ---------- | ------- |
+| `-m, --message`     | `commit`   | Commit message |
+| `-f, --files`       | `commit`   | Comma-separated file list |
+| `-r, --remote`      | `push`     | Git remote (default `origin`) |
+| `--force`           | `push`     | Force push (`--force-with-lease`) |
+| `--ref`             | `workflow` | Git ref to run the workflow against |
+| `--inputs`          | `workflow` | Workflow inputs as JSON |
+| `-p, --priority`    | all        | Priority 1–10 (default 5) |
+
+```bash
+uap deploy queue --agent-id agent-123 --action-type commit --target main \
+  -m "feat: add batcher" -f "src/a.ts,src/b.ts"
+```
+
+### `batch` — create a batch from ready actions
+
+```bash
+uap deploy batch [-v|--verbose]
+```
+
+Collects pending actions whose window has elapsed and prints the new batch ID
+plus the command to execute it.
+
+### `execute` — run a specific batch
+
+```bash
+uap deploy execute --batch-id <id> [--dry-run]
+```
+
+`--batch-id` is required. Reports executed/failed counts, duration, and any
+per-action errors.
+
+### `status` — inspect the queue
+
+```bash
+uap deploy status [-v|--verbose]
+```
+
+Shows pending (unbatched) actions grouped by type, pending batches, and a
+summary.
+
+### `flush` — batch and execute everything pending
+
+```bash
+uap deploy flush [-v|--verbose] [--dry-run]
+```
+
+Repeatedly creates and executes batches until the queue is empty. This is the
+one-shot "do it all now" command.
+
+### `config` / `set-config` — view and change windows
+
+```bash
+uap deploy config
+uap deploy set-config --message '{"commit":60000,"push":3000}'
+```
+
+`set-config` takes a JSON object of window values (ms); every value must be a
+positive number. Changes apply to the current batcher instance.
+
+### `urgent` — toggle fast windows
+
+```bash
+uap deploy urgent --on
+uap deploy urgent --off
+```
+
+## Related
+
+- `uap coord flush` is an alias-style shortcut that flushes all pending
+  deploys (see [Coordination](./COORDINATION.md)).
+- `uap deliver --deploy` queues a commit of applied files into the batcher on a
+  successful convergence run (see [Local Models](./LOCAL_MODELS.md)).

package/docs/guides/DROIDS_AND_SKILLS.md

@@ -0,0 +1,202 @@
+# Droids and Skills
+
+> Applies to UAP **v1.40.0**
+
+UAP ships two complementary extension mechanisms:
+
+- **Droids** — markdown-defined specialist agents (a reviewer, a language
+  expert, an architect). Each droid is a focused persona with its own tools and
+  instructions.
+- **Skills** — reusable workflows that any agent can load on demand (a coding
+  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.
+
+## What a droid is
+
+A droid is a single markdown file under
+[`.factory/droids/`](../../.factory/droids/) with YAML frontmatter followed by a
+prompt body. The frontmatter declares the droid's identity, model, tools, and
+optional coordination/skill metadata.
+
+A minimal droid (the default scaffold from `uap droids add`):
+
+```markdown
+---
+name: my-droid
+description: Custom droid for my-droid
+model: inherit
+tools: ["Read", "LS", "Grep", "Glob"]
+---
+
+You are a specialized assistant for my-droid tasks.
+
+Describe what this droid should do and how it should respond.
+```
+
+A real droid carries richer frontmatter — for example `security-auditor`:
+
+```markdown
+---
+name: security-auditor
+description: Proactive security analyst that reviews all code for vulnerabilities, secrets exposure, injection attacks, and security best practices.
+model: inherit
+coordination:
+  channels: ["review", "broadcast"]
+  claims: ["exclusive"]
+  batches_deploy: true
+skills:
+  - sec-context-review
+---
+# Security Auditor
+
+## Mission
+...
+```
+
+Frontmatter fields used by UAP:
+
+- `name` — **required**, unique across droids. Used to reference the droid.
+- `description` — **required**, at least 5 characters. Shown in listings and
+  used by the expert router for capability matching.
+- `model` — `inherit` (use the caller's routed model) or a specific model id.
+- `tools` — the tool allowlist the droid may use.
+- `coordination` — optional; declares channels, claim semantics
+  (`exclusive` / `shared`), and deploy batching for multi-droid runs.
+- `skills` — optional; skills the droid loads for its domain.
+
+Droids are invoked as subagents, e.g.
+`Task(subagent_type: "security-auditor", prompt: "...")`.
+
+## The droid library
+
+UAP ships **38 droids** in `.factory/droids/`. They cluster into a few
+categories:
+
+- **Language experts** — `python-pro`, `typescript-node-expert`,
+  `javascript-pro`, `go-pro`, `rust-pro`
+- **Reviewers** — `code-quality-reviewer`, `code-quality-guardian`,
+  `security-code-reviewer`, `performance-reviewer`, `test-coverage-reviewer`,
+  `documentation-accuracy-reviewer`, `architect-reviewer`
+- **Architects & planners** — `strategic-architect`, `tactical-architect`,
+  `implementation-planner`, `product-strategist`, `ideation-expert`
+- **Security & compliance** — `security-auditor`, `compliance-officer`,
+  `dependency-auditor`
+- **Quality & testing** — `qa-expert`, `test-strategist`, `test-plan-writer`,
+  `refactoring-specialist`, `debug-expert`
+- **Performance & cost** — `performance-optimizer`, `cost-engineer`,
+  `harness-optimizer`, `terminal-bench-optimizer`
+- **Ops & infrastructure** — `sysadmin-expert`, `observability-engineer`,
+  `incident-responder`, `release-manager`
+- **Domain specialists** — `api-designer`, `cli-design-expert`,
+  `accessibility-tester`, `documentation-expert`, `ml-training-expert`
+
+Run `uap droids list` to see the live set across all sources.
+
+## `uap droids` CLI
+
+Defined in `src/cli/droids.ts` and registered in `src/bin/cli.ts`.
+
+```bash
+uap droids list                       # list droids from all known locations + built-in templates
+uap droids add <name>                 # scaffold a new droid in .factory/droids/
+uap droids add <name> -t <template>   # scaffold from a built-in template
+uap droids import <path>              # import .md droids from another directory
+uap droids validate                  # validate frontmatter + capability-router coverage
+uap droids validate -q               # quiet mode: exit code only
+```
+
+`uap droids list` scans, in order:
+
+- `.factory/droids` (project)
+- `.claude/agents` (Claude Code)
+- `.opencode/agent` (OpenCode)
+- `~/.factory/droids` (personal)
+
+Built-in templates available to `uap droids add -t`: `code-reviewer`,
+`security-reviewer`, `performance-reviewer`, `test-writer`.
+
+`uap droids validate` parses every droid's frontmatter and reports errors for
+missing/short descriptions, missing names, duplicate names, and invalid YAML.
+It also cross-references the capability router so any droid the router expects
+but that is missing on disk is flagged.
+
+## The expert router
+
+`uap expert-route` recommends an ordered **chain** of droids for a task,
+grouped into phases (ideate → plan → design → implement → review → release). It
+is backed by the `ExpertOrchestrator` (`src/coordination/expert-orchestrator.ts`).
+
+```bash
+uap expert-route "add OAuth2 login with JWT sessions"
+uap expert-route "refactor the payment module" --files src/payments/*.ts
+uap expert-route "harden the upload endpoint" --json
+```
+
+Output shows the matched capabilities, a confidence score, and for each step:
+the phase, the droid, whether it runs in parallel, a rationale, and a historical
+success rate (when available). `--files` scopes routing by the affected paths;
+`--json` emits machine-readable output (also used automatically when stdout is
+not a TTY).
+
+## Skills
+
+A skill is a reusable workflow. Skills live in directories under
+[`.factory/skills/`](../../.factory/skills/), each containing a `SKILL.md` file
+with frontmatter (`name`, `version`, `compatibility`) and the workflow body.
+
+UAP ships **32 skills** in `.factory/skills/`, including:
+
+- **Coordination & workflow** — `uap-coordination`, `uap-tasks`,
+  `uap-worktree`, `worktree-workflow`, `parallel-expert-review`, `batch-review`
+- **Memory & context** — `uap-memory`, `memory-management`,
+  `scripts-preload-memory`, `session-context-preservation-droid`
+- **Navigation & analysis** — `codebase-navigator`, `git-forensics`,
+  `uap-patterns`, `compression`
+- **Engineering** — `typescript-node-expert`, `polyglot`, `cli-design-expert`,
+  `llama-cpp-worker`, `infra-worker`, `service-config`
+- **Iteration & benchmarking** — `near-miss`, `near-miss-iteration`,
+  `adversarial`, `terminal-bench`, `terminal-bench-strategies`
+- **Hooks** — `hooks-session-start`, `hooks-pre-compact`, `scripts-tool-router`
+
+### `uap skill` CLI
+
+Defined in `src/cli/skill.ts`.
+
+```bash
+uap skill list                 # list available skills (with source tag)
+uap skill list -c <category>   # filter by path/category substring
+uap skill list --json          # machine-readable listing
+uap skill load <name>          # print a skill's full content for the session
+uap skill load <name> -c <cat> # scope discovery by category
+```
+
+Skills are discovered from three roots, in order: `skills/` (project),
+`.factory/skills/`, and `.claude/skills/`. A directory with a `SKILL.md` is
+treated as a skill, as is any top-level `.md` file in those roots. `load`
+matches names case-insensitively.
+
+## Adding a custom droid
+
+```bash
+# 1. Scaffold (optionally from a template)
+uap droids add my-reviewer -t code-reviewer
+
+# 2. Edit .factory/droids/my-reviewer.md
+#    - set a clear, >= 5-char description (used by the expert router)
+#    - adjust the tools allowlist
+#    - write the prompt body / mission
+
+# 3. Validate before relying on it
+uap droids validate
+```
+
+To bring droids in from another project or platform, drop the `.md` files in a
+folder and run `uap droids import <path>` (existing files are skipped, not
+overwritten).
+
+## See also
+
+- [Multi-Model Routing](./MULTI_MODEL.md) — the models that droids and skills
+  run on, and how tasks are routed to them.