docs: add standalone quick start guide

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

README.md

@@ -79,6 +79,8 @@ export CONTEXT7_API_KEY="<your key>"   # add to ~/.bashrc or ~/.zshrc
 
 ## Quick start
 
+> Full walkthrough with troubleshooting: [docs/QUICKSTART.md](docs/QUICKSTART.md)
+
 ```bash
 cd your-repo
 lh init            # first-run wizard; writes .agents/harness.config.json

docs/QUICKSTART.md

@@ -0,0 +1,158 @@
+# Quick Start Guide
+
+This walks a new user from zero to a finished, verified change using
+`redsen-lean-harness`. For full command/flag reference see the main
+[README.md](../README.md); this doc is the shortest path to "it worked".
+
+## 0. Prerequisites
+
+- Node >= 20
+- Git
+- GitHub Copilot CLI or VS Code Copilot
+- A `CONTEXT7_API_KEY` (required — `lh doctor` fails without it)
+
+```bash
+export CONTEXT7_API_KEY="<your key>"   # add to ~/.bashrc or ~/.zshrc
+```
+
+The harness never writes this key to disk. It is read from the environment only.
+
+## 1. Get the harness into your project
+
+Pick one path.
+
+### A. Fresh clone, working inside this repo
+
+```bash
+git clone git@github.com:redsentech/lean-harness.git
+cd lean-harness
+npm install
+```
+
+### B. Bootstrap an existing repo (recommended for most users)
+
+From inside a checkout of this repo, point the onboarding script at any target repo:
+
+```bash
+node scripts/onboard.mjs /path/to/your-project --dry-run   # preview only
+node scripts/onboard.mjs /path/to/your-project --yes       # do it
+```
+
+This copies the behaviour layer (`.github/agents`, `skills`, `instructions`, `prompts`,
+`mcp.json`, `copilot-instructions.md`, `AGENTS.md`) into your project, `npm link`s the `lh`
+CLI onto `PATH` there, and runs `lh init` + `lh doctor` for you. Safe to re-run.
+
+### C. Install as a Copilot CLI plugin
+
+```bash
+copilot plugin install redsentech/lean-harness
+# or, once published to a marketplace:
+copilot plugin marketplace add redsentech/lean-harness
+copilot plugin install redsen-lean-harness@redsen
+```
+
+## 2. Initialize and verify the environment
+
+Inside your project (skip if the onboarding script already ran this):
+
+```bash
+lh init      # first-run wizard; writes .agents/harness.config.json
+lh doctor    # confirms Node, git, Context7 key, verify commands, etc.
+```
+
+`lh doctor` should print all green checks. If it flags "no verify command configured", add a
+test/build/lint command to `.agents/harness.config.json` — the Ralph loop uses it to decide
+when a lane is actually done.
+
+This creates a per-repo `.agents/` footprint:
+
+```
+.agents/
+  harness.config.json
+  architecture.md       # living ADR log
+  conventions.md        # living project conventions
+  memory/INDEX.md        # the only file auto-loaded every run
+  memory/{seed,failures,corrections,insights,conventions,quirks}.md
+```
+
+## 3. Run your first task
+
+Open Copilot CLI or VS Code Copilot in the project and pick the entry point that matches the
+size of the change.
+
+**Full pipeline** (new feature, non-trivial change):
+
+```
+@conductor build a rate limiter for the public API
+```
+
+This runs the whole pipeline: `interrogator` asks clarifying questions with recommended
+answers (you must answer before it proceeds — this is a deliberate gate), `architect` writes
+the spec and acceptance criteria, `splitter` breaks it into lanes, `builder`/`verifier` run the
+Ralph loop per lane (in parallel git worktrees when lanes don't overlap), `integrator` merges
+sequentially, and `scribe` journals everything as it happens.
+
+**Small brownfield fix** (skip spec + DAG ceremony):
+
+```
+/fast-track fix the off-by-one in pagination
+```
+
+**Learn an unfamiliar codebase first:**
+
+```
+/onboard
+```
+
+## 4. Watch it work
+
+- `lh run` writes NDJSON telemetry as the pipeline executes; `lh report` turns that into a
+  markdown summary.
+- `lh graph` is the structural gate (duplicates, orphans, unresolved calls) — it must pass
+  before any lane is considered done.
+- Every lane runs inside its own git worktree (`lh lane`) with a file-scope lease, so parallel
+  lanes can't step on each other's files.
+
+## 5. Know when it's actually done
+
+A lane only completes when **all five** hold (otherwise it iterates, and escalates to you at
+the iteration cap):
+
+1. Every declared verify command exits 0
+2. Every acceptance criterion is individually checked off
+3. `lh graph` passes
+4. `reviewer` approves
+5. No files changed outside the lane's declared scope
+
+## 6. Where things are written
+
+Everything the harness does is self-documenting — nothing lives only in a chat transcript:
+
+| What | Where |
+| --- | --- |
+| Design decisions | `.agents/specs/<slug>/decisions.md` |
+| Spec + acceptance criteria | `.agents/specs/<slug>/spec.md` |
+| Lane DAG | `.agents/specs/<slug>/plan.dag.json` |
+| Run telemetry | `.agents/runs/<id>/events.ndjson` |
+| Run journal | `.agents/runs/<id>/journal.md` |
+| ADRs | `.agents/architecture.md` |
+| Durable conventions | `.agents/conventions.md` |
+| Cross-run memory | `.agents/memory/*.md` |
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `lh doctor` fails on Context7 | `export CONTEXT7_API_KEY=...` in your shell, then re-run |
+| `lh doctor` warns "no verify command" | Add a test/build/lint command to `harness.config.json` |
+| `lh init` refuses to run again | Expected — it won't clobber an existing config. Use `lh init --force` to reset |
+| `lh` not found after onboarding | Re-run without `--no-npm-link`, or invoke via the absolute path the script prints |
+| Pipeline stuck at design gate | `interrogator` is waiting on your answers — this is intentional, answer the questions |
+
+## Next steps
+
+- Read the [Pipeline](../README.md#pipeline) and [Agents](../README.md#agents) sections in the
+  README for the full mental model.
+- Read the full [`lh` CLI flag reference](../README.md#lh-commands) for every subcommand.
+- Read [ADR 0001](adr/0001-markdown-behaviour-node-determinism.md) for why the harness is split
+  the way it is.