docs: add connect-a-harness guide (guides checkpoint 3)

content/docs/guides/connect-a-harness.mdx

@@ -0,0 +1,106 @@
+---
+title: "Connect a Harness"
+summary: "Install, authenticate, and verify a coding-agent CLI — Codex, Claude Code, Coven Code, or Copilot — so Coven can supervise it."
+description: "Step-by-step guide to connecting a harness to Coven: choose one, install its CLI, authenticate with the provider, verify with doctor, and run it."
+read_when:
+  - coven doctor reports a harness as missing
+  - You want to add a second harness or switch providers
+---
+
+Coven launches and supervises external coding-agent CLIs called [harnesses](/docs/harnesses). This guide connects one: install its CLI, authenticate it with its provider, and verify Coven can launch it.
+
+## Prerequisites
+
+- The Coven CLI installed and passing its store checks — see [Install and first run](/docs/guides/install-and-first-run).
+- An account with the provider of the harness you choose (OpenAI, Anthropic, or GitHub). Coven Code needs no separate CLI account setup beyond its engine auth.
+- npm (or Homebrew on macOS) to install the harness CLI.
+
+## Step 1 — Choose a harness
+
+The four built-in harness ids:
+
+| Harness | Harness id | Provider account |
+| --- | --- | --- |
+| Codex | `codex` | OpenAI |
+| Claude Code | `claude` | Anthropic |
+| Coven Code | `coven-code` | Connected engine providers |
+| Copilot CLI | `copilot` | GitHub |
+
+External adapters (like `grok` or `hermes`) can register more via `coven adapter install` — see [Custom adapters](/docs/harnesses/custom-adapters). The rest of this guide uses Codex; every step maps one-to-one to the other harnesses.
+
+## Step 2 — Install the harness CLI
+
+```bash
+npm install -g @openai/codex
+```
+
+The equivalents for the other harnesses:
+
+```bash
+npm install -g @anthropic-ai/claude-code   # Claude Code
+npm install -g @github/copilot             # Copilot CLI
+coven engine install                       # Coven Code
+```
+
+On macOS, Codex and Copilot are also on Homebrew: `brew install --cask codex` and `brew install --cask copilot-cli`. Details per harness live in [Installing harness CLIs](/docs/harnesses/installing).
+
+**Expected output:** the package installs without errors and the executable is on `PATH` — `which codex` prints a path.
+
+## Step 3 — Authenticate with the provider
+
+Each harness owns its provider credentials; Coven never reads them ([Provider auth](/docs/harnesses/provider-auth)):
+
+```bash
+codex login
+```
+
+The equivalents:
+
+```bash
+claude doctor    # Claude Code: finishes local auth/setup
+copilot login    # Copilot CLI
+```
+
+**Expected output:** the harness CLI confirms you are logged in. Run the harness once on its own (for example plain `codex`) if you want to confirm it works before Coven supervises it.
+
+## Step 4 — Verify with doctor
+
+```bash
+coven doctor
+```
+
+**Expected output:** the harness line flips from missing to ready:
+
+```text
+Harnesses:
+  [OK] Codex              `codex` is ready (built-in)
+```
+
+If it still shows `[!!] … missing`, open a new terminal so `PATH` changes apply, then rerun `coven doctor`. Doctor's install hint under the failing line tells you the exact missing step.
+
+## Step 5 — Run it through Coven
+
+From a project directory:
+
+```bash
+coven run codex "explain this repo in 5 bullets"
+```
+
+**Expected output:** the `Coven session created` banner with `harness: codex`, then the live harness session. Selecting an unavailable harness fails fast instead: Coven reports that the harness is not available and repeats the same install hint doctor shows.
+
+Repeat this guide any time you add another harness — sessions from every harness land in the same recorded list under `coven sessions`.
+
+## Troubleshooting
+
+- **Doctor still reports the harness missing** — `PATH` is stale or the executable landed outside your shell profile's `PATH`; see [Harness missing](/docs/reference/troubleshooting#harness-missing).
+- **The harness launches but immediately exits with an auth error** — rerun the provider login step (`codex login`, `copilot login`) or `claude doctor`; see [Provider auth](/docs/harnesses/provider-auth).
+- **`coven run` fails with `pty_spawn_failed`** — the executable disappeared between doctor and run; see the [error code lookup](/docs/reference/troubleshooting#error-code-lookup).
+- **You want a harness that is not built in** — follow [Custom adapters](/docs/harnesses/custom-adapters).
+- **Anything else** — [Harness troubleshooting](/docs/harnesses/troubleshooting).
+
+## Related
+
+- [What is a harness?](/docs/harnesses/what-is-a-harness)
+- [Installing harness CLIs](/docs/harnesses/installing)
+- [Run reference](/docs/cli/run)
+- [Install and first run](/docs/guides/install-and-first-run)

content/docs/guides/index.mdx

@@ -33,7 +33,7 @@ The catalog is being built out one guide at a time, prioritized by the questions
 | Guide | Question it answers |
 | --- | --- |
 | [Install and first run](/docs/guides/install-and-first-run) | How do I go from nothing to my first supervised session? |
-| Connect a harness | How do I run Codex, Claude Code, or Copilot through Coven? |
+| [Connect a harness](/docs/guides/connect-a-harness) | How do I run Codex, Claude Code, or Copilot through Coven? |
 | Set up the daemon | How do I start the daemon and confirm it is healthy? |
 | Set up memory | How do I enable memory and inspect what is stored? |
 | Fix a failed install | My install broke — how do I diagnose and repair it? |

content/docs/guides/meta.json

@@ -3,5 +3,5 @@
   "description": "Step-by-Step How-Tos",
   "root": true,
   "icon": "LuCompass",
-  "pages": ["index", "install-and-first-run"]
+  "pages": ["index", "install-and-first-run", "connect-a-harness"]
 }

scripts/check-guides-docs.mjs

@@ -5,7 +5,7 @@ const root = process.cwd();
 const docsRoot = join(root, 'content', 'docs');
 const guidesRoot = join(docsRoot, 'guides');
 
-const requiredPages = ['index', 'install-and-first-run'];
+const requiredPages = ['index', 'install-and-first-run', 'connect-a-harness'];
 
 const requiredMentions = [
   'step-by-step',
@@ -23,6 +23,10 @@ const requiredMentions = [
   'coven run codex',
   'coven sessions --plain',
   'Coven session created',
+  'coven engine install',
+  'coven adapter install',
+  '@github/copilot',
+  'copilot login',
 ];
 
 function fail(message) {
@@ -98,4 +102,8 @@ if (!readFileSync(join(guidesRoot, 'install-and-first-run.mdx'), 'utf8').include
   fail('install-and-first-run guide must link to the install debugging reference.');
 }
 
+if (!readFileSync(join(guidesRoot, 'connect-a-harness.mdx'), 'utf8').includes('/docs/harnesses/provider-auth')) {
+  fail('connect-a-harness guide must link to the provider auth boundary.');
+}
+
 console.log('Guides docs check passed.');