diff --git a/README.md b/README.md
index 7e0718c..d52cda4 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,36 @@
# Do Work
-A Claude Code and Codex skill that turns natural-language briefs into discrete, traceable tasks and executes them autonomously — with TDD, evidence gates, review, and a git commit per task.
+An agent-harness skill that turns natural-language briefs into discrete, traceable tasks and executes them autonomously — with TDD, evidence gates, review, and a git commit per task. Works with any agent that loads skills from a shared hub (Claude Code, Codex, Cursor, and others).
Two commands: `/do-work start` to define the work, `/do-work go` to execute it.
+## User documentation
+
+Task-based guides for installing and running `/do-work` (not contributor internals):
+
+| Guide | Contents |
+|-------|----------|
+| [docs/README.md](docs/README.md) | Docs index |
+| [docs/getting-started.md](docs/getting-started.md) | Install → first start → first go |
+| [docs/concepts.md](docs/concepts.md) | UR, REQ, gates, evidence |
+| [docs/commands.md](docs/commands.md) | Command and flag reference |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Common failure symptoms |
+| [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md) | Phase-by-phase deep dive |
+
- Supported AI Providers
+ Any agent harness
- 
+ 
- 
+ 
+ 
---
@@ -44,7 +58,7 @@ curl -fsSL https://raw.githubusercontent.com/agent-native/do-work/main/install.s
git clone https://github.com/agent-native/do-work.git ~/.agents/skills/do-work
```
-Override the hub directory with `AGENTS_SKILLS_HUB` (same as `install.sh`). Wire Claude Code, Codex, or other agents to load skills from that hub.
+Override the hub directory with `AGENTS_SKILLS_HUB` (same as `install.sh`). Wire any agent harness to load skills from that hub.
---
diff --git a/docs/HOW-IT-WORKS.md b/docs/HOW-IT-WORKS.md
index db693ff..b59d00d 100644
--- a/docs/HOW-IT-WORKS.md
+++ b/docs/HOW-IT-WORKS.md
@@ -1,12 +1,14 @@
# How do-work Works
+> **Operators / first run:** use [getting-started.md](getting-started.md) for install and the happy path. This page is the phase-by-phase deep dive (design rationale included).
+
A walkthrough of the do-work system — every phase, every file it produces, and the design reasoning behind each choice.
---
## What it is
-do-work is a Claude Code skill that turns a natural-language brief into a sequence of small, traceable, individually-committed tasks — executed autonomously with TDD.
+do-work is an agent-harness skill that turns a natural-language brief into a sequence of small, traceable, individually-committed tasks — executed autonomously with TDD. It runs on any agent that loads skills from a shared hub.
It is **file-based**: every artifact (brief, decomposed task, claim stamp, commit) is a file in the project's git history. There is no daemon, no database, no in-memory queue, no central coordinator.
@@ -328,6 +330,10 @@ Defaults are picked from REQ shape (parallel claim ordering, layer enforcement)
## Reference
+- [getting-started.md](getting-started.md) — install and first run
+- [concepts.md](concepts.md) — user-facing mental model
+- [commands.md](commands.md) — command reference
+- [troubleshooting.md](troubleshooting.md) — failure symptoms
- `SKILL.md` — full command reference and migration semantics
- `agents/*.md` — per-phase agent instructions
- `lib/*.sh` — coordination primitives (claim, footprint, deps, heartbeat, deadlock, cycle)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..0037402
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,43 @@
+# Do Work — user documentation
+
+Task-based guides for people who install and run `/do-work` in a project. Works with any agent harness wired to the shared skills hub.
+
+## Start here
+
+| If you want to… | Read |
+|-----------------|------|
+| Install the skill and run your first brief end-to-end | [Getting started](getting-started.md) |
+| Understand UR, REQ, `start` / `go`, and the gates | [Concepts](concepts.md) |
+| Look up a command or flag | [Commands](commands.md) |
+| Fix a failure symptom | [Troubleshooting](troubleshooting.md) |
+
+## Deeper reference
+
+| Page | Audience |
+|------|----------|
+| [How it works](HOW-IT-WORKS.md) | Operators who want phase-by-phase design detail |
+| [../README.md](../README.md) | Install one-liner, quick start, config overview |
+| [../agents/config.md](../agents/config.md) | Full `config.yml` schema |
+| [../SKILL.md](../SKILL.md) | Skill entrypoint and full behavioural reference |
+| [../CONTRIBUTING.md](../CONTRIBUTING.md) | Contributors changing the skill itself |
+
+## Happy path (two commands)
+
+```text
+/do-work start I need a user settings page with email and password change
+/do-work go UR-001
+```
+
+`start` records the brief and builds the backlog. `go` checks coverage, then runs the backlog when confidence meets the project threshold (default 90%).
+
+## Docs map
+
+```text
+docs/
+├── README.md ← you are here (index)
+├── getting-started.md ← install → first start → first go
+├── concepts.md ← mental model
+├── commands.md ← command reference
+├── troubleshooting.md ← symptoms → fixes
+└── HOW-IT-WORKS.md ← deep dive (design + phases)
+```
diff --git a/docs/commands.md b/docs/commands.md
new file mode 100644
index 0000000..95ccb53
--- /dev/null
+++ b/docs/commands.md
@@ -0,0 +1,248 @@
+# Commands reference
+
+Lookup for `/do-work` commands: what each one does, when to use it, and which flags exist in the skill today.
+
+Invoke with no subcommand for help plus suggested next steps:
+
+```text
+/do-work
+```
+
+## Command map (when to use which)
+
+| Goal | Command |
+|------|---------|
+| First-time project folders | `/do-work install` |
+| Align old `.do-work/` with current skill | `/do-work upgrade` |
+| New work end-to-end (define) | `/do-work start [brief]` |
+| Execute a defined UR | `/do-work go UR-NNN` |
+| Record brief only | `/do-work intake [brief]` |
+| Creative review only | `/do-work ideate UR-NNN` |
+| Grill the brief | `/do-work question UR-NNN` |
+| Decompose only | `/do-work capture UR-NNN` |
+| Score coverage only | `/do-work verify UR-NNN` |
+| Sharpen REQ quality | `/do-work audit UR-NNN` |
+| Run backlog (no verify gate) | `/do-work run [UR-NNN]` |
+| Live situation room | `/do-work status [UR-NNN]` |
+| Stuck REQ → backlog | `/do-work unblock REQ-NNN` |
+| Re-dispatch stopped REQ | `/do-work resume REQ-NNN` |
+| Validate integrated UR paths | `/do-work close UR-NNN` |
+| Learn from run history | `/do-work retro` |
+| Draft social posts | `/do-work log` |
+
+---
+
+## Orchestrators
+
+### `/do-work start [brief]`
+
+**Job:** Record a brief and build the REQ backlog in one shot.
+
+**Pipeline:** intake → ideate (default) → capture. Does **not** run verify or implementation.
+
+| Flag | Effect |
+|------|--------|
+| `--no-ideate` | Skip ideate and its Grill/Continue/Stop gate |
+| `--no-layers` | Skip layer-coverage checks for this UR; records `layers_in_scope: []` |
+
+**Notes:**
+
+- Auto-installs `.do-work/` if missing
+- Ideate gate: **Grill** / **Continue** / **Stop** (Stop halts before capture)
+- After success, may offer next steps (Run Go / Verify only / Skip) when `next_steps.enabled` is true
+
+**Example:**
+
+```text
+/do-work start Add password reset email with rate limiting
+/do-work start Quick typo fix in README --no-ideate --no-layers
+```
+
+### `/do-work go [UR-NNN]`
+
+**Job:** Verify coverage for a UR, then audit and run when the confidence gate passes.
+
+**Pipeline:** verify → (if gate passes) audit → run → optional close offer → optional log.
+
+| Flag | Effect |
+|------|--------|
+| `--force` | Run even if score < threshold; verify still runs |
+| `--auto-fix` | One verify pass that creates missing REQs, re-scores; run only if ≥ threshold afterward |
+| `--no-layers` | Skip layer-coverage checks; passed through to capture if `--auto-fix` re-runs capture |
+
+**Threshold:** `verify.threshold` in `.do-work/config.yml` (default **90**).
+
+**Example:**
+
+```text
+/do-work go UR-001
+/do-work go UR-001 --auto-fix
+/do-work go UR-001 --force
+```
+
+---
+
+## Setup
+
+### `/do-work install`
+
+Creates the per-project `.do-work/` folder structure and default `config.yml` in the current project.
+
+Use when you want structure before the first brief. `/do-work start` also installs automatically.
+
+### `/do-work upgrade`
+
+Brings existing `.do-work/` state into conformance with the current skill (detectors + fixes). Destructive rows require interactive confirmation. Idempotent.
+
+Use after upgrading the skill install when help or startup mentions pending migration / stale config keys.
+
+---
+
+## Define work (granular)
+
+### `/do-work intake [brief]`
+
+Records the brief **verbatim** as the next `UR-NNN/input.md`. No decomposition.
+
+Use when you want the UR on disk before ideate/capture, or to script the pipeline yourself.
+
+### `/do-work ideate [UR-NNN]`
+
+Surfaces assumptions, risks, and connections into `UR-NNN/ideate.md`. Ends with the interactive gate when run in flows that expect it.
+
+Use to pressure-test a brief without starting capture yet (or re-run after edits).
+
+### `/do-work question [UR-NNN]`
+
+Grills you one question at a time about the brief (assumptions, gaps, constraints).
+
+Use from the ideate **Grill** path or standalone when the brief is thin.
+
+### `/do-work capture [UR-NNN]`
+
+Decomposes `input.md` (and `ideate.md` if present) into backlog `REQ-NNN-slug.md` files. Applies layer rules, integration blocks, dependency cycle checks.
+
+Use to resume after a failed start-at-capture, or to re-decompose after you edited the brief.
+
+---
+
+## Check quality
+
+### `/do-work verify [UR-NNN]`
+
+Scores REQ coverage against the original brief (0–100%) and lists gaps. Includes layer, integration-block, and partial-confidence structural checks.
+
+| Flag | Effect |
+|------|--------|
+| `--auto-fix` | Create missing REQs, then re-score |
+
+Use before `run` when you are not using `go`, or after manual REQ edits.
+
+### `/do-work audit [UR-NNN]`
+
+Interrogates acceptance criteria quality; auto-fixes vague spots; reports changes. Always runs inside `go` when execution will proceed; does not re-score verify.
+
+Use standalone to sharpen REQs without starting the run loop.
+
+---
+
+## Execute and observe
+
+### `/do-work run [UR-NNN]`
+
+Executes the backlog: claim REQ → worker TDD loop → evidence validation → policy checks → post-build review → archive/ledger. Optional `UR-NNN` limits work to that UR’s REQs.
+
+Does **not** run the verify confidence gate (unlike `go`).
+
+| Flag | Effect |
+|------|--------|
+| `--parallel N` | One terminal dispatches up to N concurrent workers (default serial; capped at 10). Uses `parallel.max_workers` defaults when applicable |
+| `--budget ` | Cap estimated model spend for this run; overrides `cost.budget`. Stops at the next REQ boundary after the in-flight REQ finishes integration. Empty budget = unlimited |
+
+**Parallelism without flags:** open multiple terminals and run `/do-work run` in each; claims coordinate via the filesystem/`git mv`.
+
+### `/do-work status [UR-NNN]`
+
+Read-only situation room: REQs, claimers (`hostname.pid`), heartbeats, deadlock warnings, coverage rollup. Optional UR scope.
+
+Use whenever something looks stuck or you are running parallel workers.
+
+### `/do-work unblock REQ-NNN`
+
+Forces a REQ out of `working/` back to the backlog: strips claim stamp, resets status. Includes judgment when partial commits exist.
+
+Use when a worker died, heartbeat is stale, or you need to break a deadlock after triage with `status`.
+
+Requires a REQ id (example: `/do-work unblock REQ-042`).
+
+### `/do-work resume REQ-NNN`
+
+Re-dispatches a fresh worker for a **stopped** REQ while preserving the claim and refreshing the heartbeat.
+
+Use after `concurrent-conflict` or a transient worker failure—not as a substitute for `unblock` when the claim should be cleared.
+
+Requires a REQ id (example: `/do-work resume REQ-042`).
+
+### `/do-work close UR-NNN`
+
+Validates the integrated result of a UR against the verbatim brief: walks path-unit entry points to terminal states and writes a closure report under the UR folder.
+
+Requires a UR id. `go` may offer close after a clean drain when path-unit REQs exist and no `closure.md` yet. Closure gaps do not block the log step.
+
+---
+
+## Learn and publish drafts
+
+### `/do-work retro`
+
+Mines the run ledger (and related feedback signals) into a human report and regenerates `.do-work/state/calibration.md` as advisory capture guidance.
+
+Use after several runs when you want capture to learn from history.
+
+### `/do-work log`
+
+Generates build-in-public **draft** posts for platforms listed in `log.platforms` (for example `x`, `linkedin`, `blog`). You choose drafts; history is recorded so the same work is not re-prompted forever.
+
+Skipped when `log.enabled` is false or `platforms` is empty. `go` can trigger log automatically after a clean run.
+
+---
+
+## Quick reference table
+
+Same surface as README / SKILL quick reference:
+
+| Command | What it does |
+|---------|--------------|
+| `/do-work start [brief]` | Brief + REQs; ideate on by default |
+| `/do-work start [brief] --no-ideate` | Skip creative review |
+| `/do-work start [brief] --no-layers` | Skip layer checks for this UR |
+| `/do-work go [UR-NNN]` | Verify; auto-run if ≥ threshold |
+| `/do-work go [UR-NNN] --force` | Verify + run regardless of score |
+| `/do-work go [UR-NNN] --auto-fix` | Verify, fix gaps once, run if ≥ threshold |
+| `/do-work go [UR-NNN] --no-layers` | Verify + run; skip layer checks |
+| `/do-work install` | Create `.do-work/` |
+| `/do-work upgrade` | Conformance fixes for `.do-work/` |
+| `/do-work intake [brief]` | Verbatim UR only |
+| `/do-work capture [UR-NNN]` | UR → REQ files |
+| `/do-work question [UR-NNN]` | Interactive grilling |
+| `/do-work audit [UR-NNN]` | REQ quality pass |
+| `/do-work ideate [UR-NNN]` | Assumptions and risks |
+| `/do-work verify [UR-NNN]` | Coverage score + gaps |
+| `/do-work verify [UR-NNN] --auto-fix` | Verify + create missing REQs |
+| `/do-work run [UR-NNN]` | Execute backlog (optional UR scope) |
+| `/do-work run --parallel N` | Single-session parallel workers |
+| `/do-work run --budget ` | Spend cap for the run |
+| `/do-work status [UR-NNN]` | Situation room |
+| `/do-work close UR-NNN` | Integrated UR closure report |
+| `/do-work unblock REQ-NNN` | Stuck REQ → backlog |
+| `/do-work resume REQ-NNN` | Re-dispatch stopped REQ |
+| `/do-work retro` | Ledger → calibration report |
+| `/do-work log` | Build-in-public drafts |
+| `/do-work` | Help |
+
+## Related
+
+- [Getting started](getting-started.md)
+- [Concepts](concepts.md)
+- [Troubleshooting](troubleshooting.md)
+- Config schema: [`agents/config.md`](../agents/config.md)
diff --git a/docs/concepts.md b/docs/concepts.md
new file mode 100644
index 0000000..7eea5f4
--- /dev/null
+++ b/docs/concepts.md
@@ -0,0 +1,140 @@
+# Concepts
+
+Minimal mental model for do-work: what a brief becomes, how work is gated, and what “done” means.
+
+## Why it matters
+
+do-work turns a natural-language brief into small, traceable tasks and runs them with tests and evidence—not one opaque “agent did stuff” blob. Knowing the nouns (UR, REQ) and the two-command loop (`start` → `go`) keeps you in control of the gates.
+
+## How it works (minimal model)
+
+```text
+Your brief
+ │
+ ▼
+ UR-NNN user request (verbatim input + side artifacts)
+ │
+ ▼
+ REQ-NNN-… backlog tasks (one file each)
+ │
+ ▼
+ working/ claimed, in flight (one worker / worktree per REQ)
+ │
+ ▼
+ archive/ done, with proof metadata
+```
+
+**Two-command surface**
+
+| Command | Role |
+|---------|------|
+| `/do-work start …` | Define work: intake → ideate (default) → capture |
+| `/do-work go UR-NNN` | Execute work: verify → audit → run (then optional close/log) |
+
+Granular commands (`intake`, `capture`, `verify`, `run`, …) are the same building blocks; `start` and `go` chain them with defaults and human gates.
+
+**File-based state.** Everything lives under the project’s `.do-work/` (config, URs, backlog REQs, `working/`, `archive/`, `runs/`, `state/`). There is no separate do-work server. `git` history is the audit trail.
+
+## Key terms
+
+### UR (user request)
+
+- Folder: `.do-work/user-requests/UR-NNN/`
+- Core file: `input.md` — your brief **verbatim** (do-work does not “improve” the wording on intake)
+- May also hold `ideate.md`, `assets/`, later `closure.md`
+- Numbering: sequential, zero-padded (`UR-001`, `UR-002`, …); next id is max+1 (gaps are not filled)
+
+### REQ (requirement / task)
+
+- Backlog file: `.do-work/REQ-NNN-slug.md`
+- One discrete unit of work with acceptance criteria, verification steps, optional dependencies, layer, and file footprint
+- Lifecycle locations: backlog root → `working/` (claimed) → `archive/` (done)
+- Each completed REQ normally produces **one git commit** on a `req/REQ-NNN` branch, then delivery per `delivery.mode` (`merge` default, or `pr`)
+
+### Start vs go
+
+- **start** = record + shape the backlog (does not run implementation)
+- **go** = score the backlog against the brief, then run if the gate passes
+
+That split is intentional: you get a human decision point before autonomous execution.
+
+### Ideate gate
+
+On `start` (unless `--no-ideate`), ideate ends with:
+
+- **Grill** — one-at-a-time questions (`question`)
+- **Continue** — capture as-is
+- **Stop** — you revise `input.md` yourself; capture does not run
+
+### Verify gate (confidence)
+
+`go` runs verify first. Score is 0–100% coverage of the brief, plus structural checks:
+
+1. Layer coverage (declared layers represented or explicitly skipped)
+2. Integration block on new-surface feature REQs
+3. Partial-confidence acknowledgements from capture
+
+Default threshold: **`verify.threshold: 90`** in `.do-work/config.yml`.
+
+| Outcome | Behaviour |
+|---------|-----------|
+| Score ≥ threshold | Proceed to audit + run |
+| Score < threshold | Halt; show gaps (unless `--force` or successful `--auto-fix`) |
+
+### Layers
+
+Project-declared slices of the stack in config, for example:
+
+```yaml
+layers: [frontend, backend]
+```
+
+Capture tags each REQ with a layer (or `none` for bug-fix / pure refactor). Feature briefs that ignore a declared layer get a prompt—or halt if layers are empty and you did not pass `--no-layers`. See README “Layers and Integration”.
+
+### Integration block
+
+For feature REQs that add **new surface** (page, route, command, endpoint, …), capture writes `## Integration` with codebase-checked answers:
+
+- Reachability
+- Data dependencies
+- Service dependencies
+
+Stops “compiles but unreachable” work from looking done at decomposition time.
+
+### TDD loop (per REQ)
+
+During run, a fresh worker typically:
+
+1. Works in a dedicated git worktree on `req/REQ-NNN`
+2. Writes a failing test for an acceptance criterion
+3. Implements until it passes; repeats for remaining criteria
+4. Runs the project suite when configured
+5. Returns structured evidence to the orchestrator
+
+### Evidence and review gates
+
+A worker report alone does **not** mean archived. The orchestrator validates acceptance evidence, runs policy checks (blocked paths/commands), runs post-build review, writes closure proof fields, and only then archives. Failed review is a **stopper**, not a successful REQ.
+
+### Delivery modes
+
+From `.do-work/config.yml` (`delivery.mode`):
+
+- **`merge`** (default) — merge `req/REQ-NNN` into the base branch locally, archive, tear down worktree, delete branch
+- **`pr`** — push and open a GitHub PR via `gh`; requires remote + `gh`. Missing credentials → `missing-creds` stopper (no silent merge fallback)
+
+### Parallelism (short)
+
+- Multi-terminal: several `/do-work run` sessions claim different REQs via atomic `git mv`
+- Single-session: `/do-work run --parallel N` (N capped at 10)
+
+Claim stamps, heartbeats, footprint checks, and dependency checks reduce collisions. Recovery: `status`, `unblock`, `resume`.
+
+### Build-in-public log
+
+Optional drafts for X / LinkedIn / blog from completed archive work. Runs after a clean `go` when `log.enabled` is true and `log.platforms` is non-empty—or on demand via `/do-work log`.
+
+## What to do next
+
+1. [Getting started](getting-started.md) — install and first `start` / `go`
+2. [Commands](commands.md) — when to use each command
+3. [Troubleshooting](troubleshooting.md) — gate failures and stuck REQs
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..d8df2cf
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,173 @@
+# Getting started with do-work
+
+Install the skill, wire it into your agent, then run your first brief with `/do-work start` and `/do-work go`.
+
+## Before you start
+
+- Any agent harness that can load skills from a shared hub (Claude Code, Codex CLI, Cursor, and others pointed at the same hub)
+- `git` available on your PATH
+- A project directory where you want work tracked under `.do-work/`
+- Optional: a project test command you can put in `.do-work/config.yml` as `test.suite_command` (for example `npx vitest run` or `./vendor/bin/pest`)
+
+Time: a few minutes to install; first `start` + `go` depends on the size of your brief.
+
+Related: [Concepts](concepts.md) · [Commands](commands.md)
+
+## Steps
+
+### 1. Install the skill into the skills hub
+
+Default hub path: `~/.agents/skills/do-work`.
+
+Override the hub with `AGENTS_SKILLS_HUB` if your agents load skills from somewhere else.
+
+**Option A — clone this repository (recommended for rawphp/do-work):**
+
+```bash
+git clone https://github.com/rawphp/do-work.git ~/.agents/skills/do-work
+```
+
+**Option B — run `install.sh` from a checkout:**
+
+```bash
+git clone https://github.com/rawphp/do-work.git
+cd do-work
+bash install.sh
+```
+
+`install.sh` clones or updates into `$AGENTS_SKILLS_HUB/do-work` (default `~/.agents/skills/do-work`).
+
+If you use the script’s default remote without a local checkout, note the current default in `install.sh`:
+
+```bash
+# Default REPO_URL inside install.sh (override if needed):
+# DO_WORK_REPO_URL defaults to https://github.com/agent-native/do-work.git
+DO_WORK_REPO_URL=https://github.com/rawphp/do-work.git bash install.sh
+```
+
+**Option C — live symlink from a checkout (development):**
+
+```bash
+cd /path/to/do-work
+bash install.sh --from-cwd
+# or: bash install.sh --source /path/to/do-work
+```
+
+`--env` is accepted and ignored. All agents share one hub install.
+
+### 2. Wire your agent to the hub
+
+Point your agent harness at the skills hub so it can load `do-work` (`SKILL.md` in the install directory). Exact settings differ by product; the install only places files on disk.
+
+You should be able to invoke `/do-work` (or bare `/do-work` for help) inside a project session.
+
+### 3. Open your project and start a brief
+
+In the project root (or any directory where you want `.do-work/` created):
+
+```text
+/do-work start I need a user settings page with email and password change
+```
+
+What this does:
+
+1. Creates `.do-work/` on first use if needed (same as `/do-work install`)
+2. Records your brief **verbatim** as the next `UR-NNN` under `.do-work/user-requests/UR-NNN/input.md`
+3. Runs **ideate** by default (assumptions, risks, connections), then an interactive gate: **Grill** / **Continue** / **Stop**
+4. **Capture** decomposes the brief into backlog REQ files (`.do-work/REQ-NNN-slug.md`)
+
+Useful flags:
+
+- `--no-ideate` — skip creative review and the ideate gate
+- `--no-layers` — skip layer-coverage checks for this UR (recorded for audit)
+
+If capture stops because layers are undeclared, either set layers in config or pass `--no-layers` (see [Troubleshooting](troubleshooting.md)).
+
+### 4. Configure layers and tests (recommended before a large feature)
+
+On first install, edit `.do-work/config.yml`:
+
+```yaml
+project:
+ name: "my-project"
+
+layers: [frontend, backend] # example for a web app; [] opts out until you set them
+
+test:
+ suite_command: "npx vitest run" # your real suite command
+
+verify:
+ threshold: 90 # go auto-runs only at or above this score unless --force
+```
+
+Empty `layers: []` opts out of layer gap-checks, but **feature** briefs may halt capture until you declare layers or pass `--no-layers`.
+
+Full key list: [`agents/config.md`](../agents/config.md).
+
+### 5. Execute with go
+
+Use the UR number from the start report (example `UR-001`):
+
+```text
+/do-work go UR-001
+```
+
+What this does:
+
+1. **Verify** — scores REQ coverage against your original brief (0–100%) plus structural checks
+2. If score ≥ `verify.threshold` (default **90**): **audit** (sharpen acceptance criteria), then **run** the backlog
+3. Each REQ: claim → worktree on `req/REQ-NNN` → TDD → evidence and review gates → archive + commit
+4. Optional **close** offer (path-unit flows) and **log** drafts if logging is enabled
+
+Flags:
+
+- `--force` — run even when confidence is below threshold (verify still runs so you see the report)
+- `--auto-fix` — create missing REQs once, re-score, then run only if still ≥ threshold
+- `--no-layers` — skip layer-coverage checks for this UR (threaded into verify/capture when auto-fix runs)
+
+### 6. Check status while work runs
+
+```text
+/do-work status
+/do-work status UR-001
+```
+
+Read-only situation room: backlog vs working vs archive, claimers, heartbeats, deadlock warnings, coverage rollup.
+
+## How you know it worked
+
+After install:
+
+- Directory exists: `~/.agents/skills/do-work` (or `$AGENTS_SKILLS_HUB/do-work`) with a `SKILL.md` inside
+- Your agent exposes `/do-work` / do-work help
+
+After `start`:
+
+- `.do-work/user-requests/UR-NNN/input.md` holds your brief under `## Request`
+- One or more `.do-work/REQ-*-*.md` files appear in the backlog root
+- Start report lists REQs and totals
+
+After a successful `go`:
+
+- Message like `Go complete for UR-NNN` with verify %, audit outcome, and run count
+- Completed REQs under `.do-work/archive/` with status done
+- Git history includes commits shaped like `feat(REQ-NNN): short title`
+- Optional: `.do-work/runs/RUN-NNN.yml` when `ledger.enabled` is true
+
+## If something goes wrong
+
+| Symptom | What to do |
+|---------|------------|
+| `/do-work` not found | Confirm hub path and agent skill loading; re-run install |
+| Capture halts on layers | Set `layers` in config or use `--no-layers` |
+| `go` stops below 90% | Read verify gaps; fix REQs, or use `--auto-fix` / `--force` |
+| UR not found | Check `.do-work/user-requests/` for the real `UR-NNN` |
+| REQ stuck in `working/` | `/do-work status` then `/do-work unblock REQ-NNN` or `/do-work resume REQ-NNN` |
+
+Full table: [Troubleshooting](troubleshooting.md).
+
+## Related
+
+- [Concepts](concepts.md) — UR, REQ, gates, evidence
+- [Commands](commands.md) — full command list
+- [How it works](HOW-IT-WORKS.md) — phase design deep dive
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..6adc086
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,295 @@
+# Troubleshooting do-work
+
+Symptom-first fixes for install, `start` / `go` gates, capture, and stuck runs.
+
+## Quick checks
+
+1. Skill installed where the agent loads skills (`$AGENTS_SKILLS_HUB/do-work` or `~/.agents/skills/do-work`) and contains `SKILL.md`
+2. You are in the **project** directory that should own `.do-work/`
+3. `UR-NNN` / `REQ-NNN` ids match folders and filenames under `.do-work/`
+4. Read `/do-work status` before force-changing in-flight work
+5. For feature work: either declare `layers` in `.do-work/config.yml` or pass `--no-layers`
+
+---
+
+## Install and discovery
+
+### `/do-work` is not available in the agent
+
+**Cause:** Skill not installed, or agent not wired to the skills hub.
+
+**Fix:**
+
+1. Confirm the directory exists and has `SKILL.md`:
+ ```bash
+ ls "${AGENTS_SKILLS_HUB:-$HOME/.agents/skills}/do-work/SKILL.md"
+ ```
+2. Reinstall:
+ ```bash
+ git clone https://github.com/rawphp/do-work.git ~/.agents/skills/do-work
+ # or from a checkout:
+ DO_WORK_REPO_URL=https://github.com/rawphp/do-work.git bash install.sh
+ ```
+3. Point the agent at the same hub path your install used.
+
+### Install cloned a different GitHub org than expected
+
+**Cause:** `install.sh` defaults `DO_WORK_REPO_URL` to `https://github.com/agent-native/do-work.git` unless overridden.
+
+**Fix:** Set the URL explicitly:
+
+```bash
+DO_WORK_REPO_URL=https://github.com/rawphp/do-work.git bash install.sh
+```
+
+Or clone `rawphp/do-work` directly into the hub (see [Getting started](getting-started.md)).
+
+### Existing hub directory blocked update
+
+**Cause:** Non-git directory or leftover symlink at the skill path.
+
+**Fix:** Re-run `install.sh`. It backs up non-git directories under `$HUB/.backups/` and replaces symlinks when reinstalling from git. For a live dev link, use `bash install.sh --from-cwd` or `--source `.
+
+---
+
+## Start and capture
+
+### Capture halts because layers are not declared
+
+**Cause:** Feature-class brief with `layers: []` (or unset equivalent) and no `--no-layers`. Capture expects either declared layers or an explicit opt-out.
+
+**Fix:**
+
+1. Set layers in `.do-work/config.yml`, for example:
+ ```yaml
+ layers: [frontend, backend]
+ ```
+2. Or skip for this UR:
+ ```text
+ /do-work start "…" --no-layers
+ /do-work capture UR-NNN --no-layers
+ ```
+ (Pass `--no-layers` on the orchestrator you use; start/go thread it into capture.)
+
+### Start stopped at ideate gate
+
+**Cause:** You chose **Stop** after ideate (or the gate halted the orchestrator).
+
+**Fix:** Edit `.do-work/user-requests/UR-NNN/input.md`, then either:
+
+```text
+/do-work capture UR-NNN
+```
+
+or run start again only if you intend a **new** UR (intake always creates the next number). Prefer `capture` on the existing UR after revising the brief.
+
+### Start failed at capture; UR exists with no REQs
+
+**Cause:** Capture error after intake succeeded.
+
+**Fix:** Read the error from the agent output, then:
+
+```text
+/do-work capture UR-NNN
+```
+
+### Feature REQs missing UI or wiring
+
+**Cause:** Layers undeclared or integration block skipped/incomplete; brief under-specified.
+
+**Fix:**
+
+1. Declare layers and re-capture or use verify `--auto-fix`
+2. Run `/do-work ideate UR-NNN` / `/do-work question UR-NNN` before capture
+3. Run `/do-work verify UR-NNN` and add REQs for gaps
+4. Ensure new-surface REQs have a filled `## Integration` section
+
+### Warning: REQs missing verification steps
+
+**Cause:** Help/status heuristics found backlog REQs without typed `## Verification Steps`.
+
+**Fix:**
+
+```text
+/do-work verify UR-NNN --auto-fix
+```
+
+Or edit each REQ to add test/build/runtime/ui verification steps before `/do-work run`.
+
+---
+
+## Go and verify
+
+### `go` stops with score below threshold
+
+**Cause:** Verify confidence < `verify.threshold` (default 90) and neither `--force` nor a successful `--auto-fix` applied.
+
+**Fix:**
+
+1. Read the gap list from verify
+2. Add or edit REQs manually, or:
+ ```text
+ /do-work go UR-NNN --auto-fix
+ ```
+3. If you accept the risk of incomplete coverage:
+ ```text
+ /do-work go UR-NNN --force
+ ```
+4. Lowering `verify.threshold` in config changes the gate for future runs—prefer fixing coverage when you can
+
+### `UR-NNN not found`
+
+**Cause:** Wrong number, or `.do-work` lives in another directory.
+
+**Fix:** List requests:
+
+```bash
+ls .do-work/user-requests/
+```
+
+Confirm `user-requests/UR-NNN/input.md` exists. Re-run go with the correct id.
+
+### Auto-fix still below threshold
+
+**Cause:** One `--auto-fix` pass cannot invent missing product intent; score remains under threshold.
+
+**Fix:** Manual review of gaps; extend the brief or REQs; re-run verify/go. Do not expect multiple silent auto-fix loops—`go` runs auto-fix **once**.
+
+### Audit changed my REQs
+
+**Cause:** Expected. Audit inside `go` sharpens vague acceptance criteria before run.
+
+**Fix:** Read the audit change report. Adjust criteria if the auto-fix misread intent, then continue or re-run verify if you changed scope substantially (audit alone does not re-score).
+
+---
+
+## Run, parallel, delivery
+
+### REQ stuck in `working/`
+
+**Cause:** Worker crashed, session killed, or heartbeat went stale.
+
+**Fix:**
+
+```text
+/do-work status
+/do-work unblock REQ-NNN
+```
+
+Then `/do-work run` or `/do-work go UR-NNN` again as appropriate. Unblock may ask what to do about partial commits—answer deliberately.
+
+### `status: stopped`, `reason: concurrent-conflict`
+
+**Cause:** Parallel workers collided on shared files after retries (~110s backoff).
+
+**Fix:**
+
+```text
+/do-work resume REQ-NNN
+```
+
+Reduce overlap (narrow `**Files:**` footprints) or run fewer parallel workers.
+
+### Deadlock banner in status
+
+**Cause:** Circular wait among in-flight REQs (`Depends on:` chains).
+
+**Fix:**
+
+```text
+/do-work status
+/do-work unblock REQ-NNN # break the cycle on one participant
+```
+
+Fix dependency declarations in backlog REQs if the graph is wrong. Capture-time cycle check should prevent many bad graphs; runtime deadlocks still need human triage.
+
+### `missing-creds` stopper (PR delivery)
+
+**Cause:** `delivery.mode: pr` but `gh` or git remote is missing/misconfigured. do-work does **not** silently fall back to merge.
+
+**Fix:** Configure remote + authenticated `gh`, or set `delivery.mode: merge` in `.do-work/config.yml` if local merge is intended.
+
+### Review or evidence gate failed
+
+**Cause:** Worker finished coding but orchestrator rejected evidence, policy, or post-build review.
+
+**Fix:** Read the stopper output and the REQ in `working/`. Fix tests/evidence or policy violations; `resume` or `unblock` per status. Do not treat a worker narrative alone as proof of archive.
+
+### Budget stop
+
+**Cause:** `/do-work run --budget …` or `cost.budget` reached after finishing the in-flight REQ’s integration.
+
+**Fix:** Raise or clear the budget and run again; remaining backlog REQs stay eligible.
+
+### Worktree / dependency issues
+
+**Cause:** Isolated worktree missing `node_modules`, `vendor`, etc.
+
+**Fix:** Configure `worktree.link_paths` and/or `worktree.setup_command` in `.do-work/config.yml` (see `agents/config.md`). Ensure the main checkout has dependency dirs the provisioner can symlink.
+
+---
+
+## Upgrade and legacy layout
+
+### Prompt to run `/do-work upgrade`
+
+**Cause:** Conformance scan found legacy paths, stale config keys, or similar.
+
+**Fix:**
+
+```text
+/do-work upgrade
+```
+
+Confirm destructive rows interactively. Prefer an idle project (no mid-flight `run`) before migrating layouts.
+
+### State still under legacy `do-work/` (non-hidden)
+
+**Cause:** Older projects used a visible `do-work/` directory; current default is `.do-work/`.
+
+**Fix:** Follow skill migration / `/do-work upgrade` guidance in `SKILL.md`. Do not hand-move `working/` files while a run is active.
+
+---
+
+## Log and close
+
+### Log did nothing after `go`
+
+**Cause:** Stopper hit; or `log.enabled: false`; or `log.platforms` empty.
+
+**Fix:** Check `.do-work/config.yml`:
+
+```yaml
+log:
+ enabled: true
+ platforms: [x, linkedin]
+```
+
+Run `/do-work log` manually after archive has new REQs.
+
+### Close not offered / closure gaps
+
+**Cause:** Close applies when path-unit REQs (entry point + terminal state) exist; gaps mean a path did not reach the expected terminal state in the merged app.
+
+**Fix:** Run explicitly:
+
+```text
+/do-work close UR-NNN
+```
+
+Treat gap rows as product issues to fix with new REQs; they do not by themselves block logging.
+
+---
+
+## Still stuck
+
+1. `/do-work status UR-NNN`
+2. Inspect `.do-work/working/`, `.do-work/archive/`, and latest `.do-work/runs/RUN-*.yml` if ledger is enabled
+3. Re-read [Concepts](concepts.md) for gate meaning
+4. Deep dive: [How it works](HOW-IT-WORKS.md) and `SKILL.md`
+
+## Related
+
+- [Getting started](getting-started.md)
+- [Commands](commands.md)
+- [Concepts](concepts.md)