diff --git a/README.md b/README.md
index 3824d46..82d5e88 100644
--- a/README.md
+++ b/README.md
@@ -44,14 +44,18 @@ Three layers, one hard boundary — **we never reimplement an agent runtime**
 ### GitHub Copilot CLI
 
 ```bash
-# direct from the repo
-copilot plugin install redsentech/lean-harness
-
-# or via the marketplace
+# preferred: via the marketplace this repo publishes (verified end-to-end, no warning)
 copilot plugin marketplace add redsentech/lean-harness
 copilot plugin install redsen-lean-harness@redsen
+
+# also works, but Copilot CLI prints a deprecation warning for direct-source installs
+copilot plugin install redsentech/lean-harness
 ```
 
+Either form installs only the **behaviour layer** (agents, skills, instructions, MCP config),
+host-wide across every repo you open with that Copilot CLI account. You still need the `lh`
+CLI on `PATH` separately — see below.
+
 ### VS Code Copilot
 
 Clone the repo and point VS Code's Copilot customization settings at it, or copy the `.github/`
@@ -63,11 +67,19 @@ read by both hosts.
 
 ### The `lh` CLI
 
+The behaviour layer above only works if the agents can actually call `lh` — it's what runs
+`lh init`/`lh doctor`/`lh graph`/etc. under the hood. Not yet on the npm registry, so today:
+
 ```bash
-npm install -g @redsen/lean-harness   # or: npx @redsen/lean-harness <command>
+git clone git@github.com:redsentech/lean-harness.git && cd lean-harness && npm install
+npm link                              # puts `lh` on PATH globally
+# once published: npm install -g @redsen/lean-harness   (or: npx @redsen/lean-harness <command>)
 lh doctor                             # verify the environment
 ```
 
+`scripts/onboard.mjs` (see [Onboarding a new project](#onboarding-a-new-project)) does the
+clone-free equivalent of `npm link`, scoped to one target repo, in a single command.
+
 ### Context7
 
 Mandatory before any external-library work. The key is read from the environment **only** — the
@@ -79,7 +91,8 @@ export CONTEXT7_API_KEY="<your key>"   # add to ~/.bashrc or ~/.zshrc
 
 ## Quick start
 
-> Full walkthrough with troubleshooting: [docs/QUICKSTART.md](docs/QUICKSTART.md)
+> Full walkthrough — install paths compared, troubleshooting, and exactly when you (vs. the
+> agents) need to run `lh` yourself: [docs/QUICKSTART.md](docs/QUICKSTART.md)
 
 ```bash
 cd your-repo
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 7b11f9b..f7c3d22 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -19,36 +19,59 @@ 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.
+The harness has **two layers you install separately**: the *behaviour* layer
+(`.github/agents`, `skills`, `instructions`, `prompts`, `mcp.json` — markdown, read by the
+host) and the *determinism* layer (the `lh` CLI — Node, called by the agents). Every install
+path below gets you the behaviour layer; only B and C also give you `lh` on `PATH` in one step.
 
-### A. Fresh clone, working inside this repo
+### A. Copilot CLI plugin (recommended — start here)
+
+This is the primary distribution path for **GitHub Copilot CLI** users. It registers the
+agents/skills/instructions host-wide, so every repo you open in that Copilot CLI account can
+use `@conductor`, `/fast-track`, etc. — verified end-to-end on this machine:
+
+```bash
+# preferred: via the marketplace this repo publishes (no npm publish required, no deprecation warning)
+copilot plugin marketplace add redsentech/lean-harness
+copilot plugin install redsen-lean-harness@redsen
+
+# also works, but Copilot CLI prints a deprecation warning for direct-source installs:
+copilot plugin install redsentech/lean-harness
+```
+
+Use this when: you're a day-to-day Copilot CLI user who wants the harness available across
+multiple projects and doesn't need to modify the harness itself.
+
+Limitation: this installs the *behaviour* layer only. You still need `lh` on `PATH` (see
+below) for `lh init`/`lh doctor` and everything the agents call automatically — the package
+isn't on the npm registry yet, so today that means step B or C, not `npm install -g` (the
+README's `npm install -g @redsen/lean-harness` line is the path once it's published).
+
+### B. Bootstrap an existing repo with the onboarding script
+
+Use this when: you're on **VS Code Copilot** (which has no plugin installer and reads
+`.github/` directly), you want to try the harness against one specific repo before deciding to
+install it host-wide, or you want `lh` linked in one shot without a separate npm step.
+
+```bash
+git clone git@github.com:redsentech/lean-harness.git   # one-time, holds the source of scripts/onboard.mjs
+cd lean-harness && npm install
+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 into `/path/to/your-project`, `npm link`s the `lh` CLI onto
+`PATH` there, and runs `lh init` + `lh doctor` for you. Safe to re-run.
+
+### C. Clone and work inside this repo directly
+
+Use this when: you're contributing to the harness itself (fixing an agent, a skill, or `lh`).
 
 ```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
+npm link   # puts `lh` on PATH globally, pointing at this checkout
 ```
 
 ## 2. Initialize and verify the environment
@@ -104,14 +127,32 @@ sequentially, and `scribe` journals everything as it happens.
 /onboard
 ```
 
-## 4. Watch it work
+## 4. When do *you* need to type `lh` yourself?
 
-- `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.
+Short answer: **almost never during a normal pipeline run.** Every agent's instructions
+require it to call the relevant `lh` subcommand itself, at a specific point, every time —
+you don't ask for it and you can't opt it out. The table below is exhaustive: every `lh`
+subcommand, who calls it, and when.
+
+| Command | Who runs it | When |
+| --- | --- | --- |
+| `lh index` | `interrogator`, `scout`, `architect`, `splitter` | Automatically, before reading files, to build token-budgeted context |
+| `lh host` | `conductor` | Automatically, first thing, to pick parallel-vs-sequential strategy |
+| `lh run start/event/end` | `conductor` (start/end), every agent (event) | Automatically, for every phase transition — never skipped |
+| `lh lane create/status/merge` | `conductor`, `builder`, `integrator` | Automatically, before a write lane starts and when it merges |
+| `lh memory get/put/scan` | `interrogator`, `architect`, `builder`, `scribe` | Automatically, to pull relevant shards before work and record facts/failures after |
+| `lh graph` | `verifier` (always), plus `architect`/`splitter`/`conductor`/`reviewer`/`scout`/`integrator` at their own checkpoints | Automatically — it's exit criterion #3, never skipped |
+| `lh init` | You (or `scripts/onboard.mjs` on your behalf) | Once per repo, at setup, or to repair a missing `.agents/` baseline |
+| `lh doctor` | You | Whenever you want to check the environment yourself — before starting, after upgrading Node/git/the plugin, or to diagnose a stuck run. Also run once automatically right after `lh init` |
+| `lh report <run-id>` | You | After a run, when you want a human-readable markdown summary instead of raw NDJSON. No agent generates this for you |
+
+So the only commands you are expected to type by hand in everyday use are `lh init` (setup),
+`lh doctor` (diagnostics), and `lh report` (reading a past run's summary). Everything else —
+`lh index`, `lh host`, `lh run`, `lh lane`, `lh memory`, `lh graph` — is invoked by the agents
+as a scripted, mandatory step in their own instructions. You'd only run one of those manually
+if you're debugging outside the agent flow (e.g. `lh graph` on its own to check structure
+before opening Copilot at all, or `lh memory get --shard failures` to read what the harness has
+learned).
 
 ## 5. Know when it's actually done
 
@@ -147,6 +188,8 @@ Everything the harness does is self-documenting — nothing lives only in a chat
 | `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 |
+| Agents/skills installed via `copilot plugin install` but `lh init`/`lh doctor` fail with "command not found" | Expected — plugin install only adds the behaviour layer. Run `npm link` from a clone (path C) or `scripts/onboard.mjs` (path B) to get `lh` on `PATH` |
+| `copilot plugin install owner/repo` prints a deprecation warning | Expected for direct-source installs. Use `copilot plugin marketplace add` + `copilot plugin install name@marketplace` instead (path A) |
 | Pipeline stuck at design gate | `interrogator` is waiting on your answers — this is intentional, answer the questions |
 
 ## Next steps