OpenCoven · BunsDev · May 24, 2026 · May 24, 2026
diff --git a/content/docs/familiars/harnesses.mdx b/content/docs/familiars/harnesses.mdx
@@ -10,6 +10,8 @@ import { Mermaid } from '@/components/mermaid';
 
 Coven v0 supports Codex and Claude Code. This guide describes the current adapter shape and the bar for adding more harnesses.
 
+For install, provider-auth, project-root, and per-harness operational details, see the first-class [Harnesses deep dives](/docs/harnesses/what-is-a-harness).
+
 ## Current Adapter Shape
 
 A built-in harness adapter defines a compact launch contract.

diff --git a/content/docs/harnesses/claude-code.mdx b/content/docs/harnesses/claude-code.mdx
@@ -0,0 +1,69 @@
+---
+title: "Claude Code Harness"
+summary: "Run Anthropic Claude Code under Coven supervision with harness id claude."
+description: "Claude Code harness deep dive: setup, provider auth, launch arguments, project-root behavior, and troubleshooting."
+read_when:
+  - Setting up Claude Code for Coven
+  - Diagnosing Claude-specific launch or auth failures
+---
+
+import { Mermaid } from '@/components/mermaid';
+
+# Claude Code Harness
+
+Claude Code is Anthropic's coding-agent CLI. Coven launches it as a project-rooted PTY and records the run as a Coven session.
+
+| Field | Value |
+| --- | --- |
+| Harness id | `claude` |
+| Executable | `claude` |
+| Install | `npm install -g @anthropic-ai/claude-code` |
+| Provider auth | `claude doctor` |
+| First run | `coven run claude "polish this UI"` |
+
+## Setup
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude doctor
+coven doctor
+```
+
+`coven doctor` checks that `claude` is available on `PATH`. It does not read Anthropic credentials.
+
+## Launch
+
+```bash
+coven run claude "refactor this component" --cwd packages/web --title "Web refactor"
+```
+
+In interactive terminals, Coven launches Claude Code with the prompt as the final argument. In non-interactive mode, Coven uses Claude Code's `--print` shape so output can be captured by callers.
+
+## Supervision flow
+
+<Mermaid chart={`
+sequenceDiagram
+  participant U as User
+  participant C as coven CLI
+  participant D as Coven daemon
+  participant L as Claude Code PTY
+  participant A as Anthropic
+
+  U->>C: coven run claude "polish this UI"
+  C->>D: Launch session request
+  D->>D: validate harness id, project root, cwd
+  D->>L: spawn claude in PTY
+  L->>A: provider auth and model calls
+  L-->>D: stdout, stderr, exit
+  D-->>C: session id and status
+`} />
+
+## Common failures
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `coven doctor` reports Claude Code missing | `claude` is not on daemon `PATH` | Install Claude Code, restart daemon, rerun doctor. |
+| Claude prompts for setup | Provider auth is incomplete | Run `claude doctor`. |
+| Launch rejects cwd | `--cwd` escapes the project root | Use a cwd inside the project. |
+
+For shared setup rules, see [Install harness CLIs](/docs/harnesses/installing) and [Provider auth boundary](/docs/harnesses/provider-auth).
diff --git a/content/docs/harnesses/codex.mdx b/content/docs/harnesses/codex.mdx
@@ -0,0 +1,69 @@
+---
+title: "Codex Harness"
+summary: "Run OpenAI Codex CLI under Coven supervision with harness id codex."
+description: "Codex harness deep dive: setup, provider auth, launch arguments, project-root behavior, and troubleshooting."
+read_when:
+  - Setting up Codex for Coven
+  - Diagnosing Codex-specific launch or auth failures
+---
+
+import { Mermaid } from '@/components/mermaid';
+
+# Codex Harness
+
+Codex is OpenAI's coding-agent CLI. Coven launches it as a project-rooted PTY and records the run as a Coven session.
+
+| Field | Value |
+| --- | --- |
+| Harness id | `codex` |
+| Executable | `codex` |
+| Install | `npm install -g @openai/codex` |
+| Provider auth | `codex login` |
+| First run | `coven run codex "fix the failing tests"` |
+
+## Setup
+
+```bash
+npm install -g @openai/codex
+codex login
+coven doctor
+```
+
+`coven doctor` checks that `codex` is available on `PATH`. It does not read Codex's OpenAI credentials.
+
+## Launch
+
+```bash
+coven run codex "audit this repo" --cwd packages/cli --title "CLI audit"
+```
+
+In interactive terminals, Coven launches Codex with the prompt as the final argument. In non-interactive mode, Coven uses Codex's `exec --skip-git-repo-check --color never` shape so output is easier to capture.
+
+## Supervision flow
+
+<Mermaid chart={`
+sequenceDiagram
+  participant U as User
+  participant C as coven CLI
+  participant D as Coven daemon
+  participant X as Codex PTY
+  participant O as OpenAI
+
+  U->>C: coven run codex "audit this repo"
+  C->>D: Launch session request
+  D->>D: validate harness id, project root, cwd
+  D->>X: spawn codex in PTY
+  X->>O: provider auth and model calls
+  X-->>D: stdout, stderr, exit
+  D-->>C: session id and status
+`} />
+
+## Common failures
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `coven doctor` reports Codex missing | `codex` is not on daemon `PATH` | Install Codex, restart daemon, rerun doctor. |
+| Codex asks for login | OAuth state expired or missing | Run `codex login`. |
+| Launch rejects cwd | `--cwd` escapes the project root | Use a cwd inside the project. |
+
+For shared setup rules, see [Install harness CLIs](/docs/harnesses/installing) and [Provider auth boundary](/docs/harnesses/provider-auth).
diff --git a/content/docs/harnesses/custom-adapters.mdx b/content/docs/harnesses/custom-adapters.mdx
@@ -0,0 +1,45 @@
+---
+title: "Custom Adapters"
+summary: "The adapter bar for future harnesses: stable ids, fixed argv, PATH detection, provider-auth separation, and daemon validation."
+description: "Guidance for adding future Coven harness adapters without weakening daemon authority or provider credential boundaries."
+read_when:
+  - Evaluating a future harness integration
+  - Reviewing whether a custom adapter belongs in Coven
+---
+
+# Custom Adapters
+
+Coven v0 ships built-in adapters for Codex and Claude Code. Future adapters should meet the same bar before they are documented as supported.
+
+## Adapter contract
+
+An adapter needs:
+
+| Field | Meaning |
+| --- | --- |
+| Stable `Harness id` | The id clients pass to `coven run` and the socket API. |
+| Label | Human-readable display name. |
+| Executable | Binary name resolved on `PATH`; not an arbitrary client-supplied path. |
+| Interactive prompt args | Fixed argv prefix for terminal sessions. |
+| Non-interactive prompt args | Fixed argv prefix for scripts and output capture. |
+| Install hint | Actionable setup text for `coven doctor`. |
+
+The prompt should be the final argument after any fixed prefix args unless the adapter design explicitly proves a different shape is safer.
+
+## Review checklist
+
+Before adding a new adapter, verify:
+
+- The CLI can run inside a normal PTY.
+- It has a stable command-line prompt shape.
+- It can run from an explicit working directory.
+- Provider credentials stay with the harness.
+- It has a clear install/auth story.
+- It does not require clients to pass secrets through Coven.
+- It can fail closed when the executable is missing.
+
+## Planned does not mean supported
+
+Hermes, Aider, Gemini CLI, Cline, and other runtimes may become useful future harnesses. Until they land in the adapter table and `coven doctor`, docs should describe them as roadmap or design work, not current support.
+
+For current commands, use [Codex](/docs/harnesses/codex), [Claude Code](/docs/harnesses/claude-code), and [CLI run reference](/docs/cli/run).
diff --git a/content/docs/harnesses/index.mdx b/content/docs/harnesses/index.mdx
@@ -0,0 +1,58 @@
+---
+title: "Harnesses"
+summary: "Harnesses are external coding-agent CLIs that Coven launches, supervises, records, and exposes through project-scoped sessions."
+description: "Overview of Coven harnesses, supported v0 adapters, provider-auth boundaries, project-root rules, and adapter direction."
+read_when:
+  - Choosing whether to run Codex or Claude Code through Coven
+  - Explaining the difference between a harness, a familiar, and the daemon
+---
+
+import { Mermaid } from '@/components/mermaid';
+
+# Harnesses
+
+A harness is an external coding-agent CLI that Coven can launch inside a project root. Coven owns the PTY, session record, event log, attach/replay flow, and local API boundary. The harness owns the conversation, provider authentication, and tool execution inside its own process.
+
+The current v0 harness ids are `codex` and `claude`.
+
+## Supported v0 harnesses
+
+| Harness | Harness id | Executable | First command |
+| --- | --- | --- | --- |
+| Codex | `codex` | `codex` | `coven run codex "fix the failing tests"` |
+| Claude Code | `claude` | `claude` | `coven run claude "polish this UI"` |
+
+## Runtime boundary
+
+<Mermaid chart={`
+flowchart LR
+  User[User or client] --> CLI[coven CLI / API client]
+  CLI --> Daemon[Coven daemon]
+  Daemon --> Adapter[Harness adapter table]
+  Adapter --> Codex[Codex PTY]
+  Adapter --> Claude[Claude Code PTY]
+  Codex --> OpenAI[OpenAI provider auth]
+  Claude --> Anthropic[Anthropic provider auth]
+  Daemon --> Ledger[(SQLite sessions + events)]
+
+  style Daemon fill:#9A8ECD,stroke:#D4B5FF,color:#1A1825
+  style Adapter fill:#3D3547,stroke:#9A8ECD,color:#fff
+`} />
+
+The daemon validates the harness id, project root, working directory, session id, live-session state, and control actions. It does not read provider credentials and does not become the provider client.
+
+## Read next
+
+- [What is a harness?](/docs/harnesses/what-is-a-harness) for the concept boundary.
+- [Install harness CLIs](/docs/harnesses/installing) for Codex and Claude Code setup.
+- [Provider auth boundary](/docs/harnesses/provider-auth) before auditing credentials.
+- [Project roots](/docs/harnesses/project-roots) and [working directories](/docs/harnesses/working-directories) before debugging launch rejects.
+- [Codex](/docs/harnesses/codex) and [Claude Code](/docs/harnesses/claude-code) for adapter-specific behavior.
+- [Custom adapters](/docs/harnesses/custom-adapters) for the future adapter bar.
+- [Troubleshooting](/docs/harnesses/troubleshooting) when `coven doctor` or `coven run` fails.
+
+## Related
+
+- [CLI run reference](/docs/cli/run)
+- [Session lifecycle](/docs/familiars/sessions)
+- [Daemon security posture](/docs/daemon/security)
diff --git a/content/docs/harnesses/installing.mdx b/content/docs/harnesses/installing.mdx
@@ -0,0 +1,67 @@
+---
+title: "Install Harness CLIs"
+summary: "Coven detects external harness CLIs on PATH and fails closed with setup hints when they are missing."
+description: "How to install Codex and Claude Code for Coven, how detection works, and how to recover from PATH or auth setup problems."
+read_when:
+  - Setting up a new machine for Coven
+  - Resolving missing harness errors from coven doctor
+---
+
+import { Mermaid } from '@/components/mermaid';
+
+# Install Harness CLIs
+
+Coven does not bundle harness CLIs. Each harness is installed and authenticated through its own provider's tooling, then Coven detects the executable on `PATH`.
+
+## Supported v0 harnesses
+
+| Harness id | Executable | Install command | Provider login |
+| --- | --- | --- | --- |
+| `codex` | `codex` | `npm install -g @openai/codex` | `codex login` |
+| `claude` | `claude` | `npm install -g @anthropic-ai/claude-code` | `claude doctor` |
+
+After installing, run:
+
+```bash
+coven doctor
+```
+
+`coven doctor` reports whether the executable is available. It does not read provider credentials; the login command remains provider-owned.
+
+## Detection flow
+
+<Mermaid chart={`
+flowchart LR
+  Run["coven run codex prompt"] --> Lookup{Known harness id?}
+  Lookup -- no --> RejectUnsupported[Reject unsupported harness]
+  Lookup -- yes --> Path{Executable on PATH?}
+  Path -- no --> Hint[Fail closed with install hint]
+  Path -- yes --> Spawn[Spawn fixed adapter argv in PTY]
+`} />
+
+Only built-in harness ids are accepted. A client cannot send an arbitrary executable path through the daemon API.
+
+## PATH and daemon environment
+
+If you install a harness after the daemon is already running, restart the daemon so the process environment is fresh:
+
+```bash
+coven daemon restart
+coven doctor
+```
+
+If `coven doctor` still reports a missing harness, check duplicate or unexpected binaries:
+
+```bash
+which -a codex
+which -a claude
+```
+
+## First launch
+
+```bash
+coven run codex "describe this project"
+coven run claude "review this project for risky defaults"
+```
+
+Use [Provider auth boundary](/docs/harnesses/provider-auth) if a harness launches but exits with a provider login error.
diff --git a/content/docs/harnesses/meta.json b/content/docs/harnesses/meta.json
@@ -0,0 +1,18 @@
+{
+  "title": "Harnesses",
+  "description": "Deep dives for Codex, Claude Code, provider auth, project roots, working directories, and adapter boundaries.",
+  "root": true,
+  "icon": "LuCable",
+  "pages": [
+    "index",
+    "what-is-a-harness",
+    "installing",
+    "provider-auth",
+    "project-roots",
+    "working-directories",
+    "codex",
+    "claude-code",
+    "custom-adapters",
+    "troubleshooting"
+  ]
+}
diff --git a/content/docs/harnesses/project-roots.mdx b/content/docs/harnesses/project-roots.mdx
@@ -0,0 +1,46 @@
+---
+title: "Project Roots"
+summary: "Every harness session is pinned to a canonical project root before Coven launches the PTY."
+description: "How Coven resolves project roots for harness sessions and why launch requests cannot widen the project boundary."
+read_when:
+  - A launch fails because Coven cannot resolve the project
+  - You are building a client that sends project-rooted session requests
+---
+
+# Project Roots
+
+Every harness session starts from a project root. Coven resolves and canonicalizes that root before it launches a PTY or records the session.
+
+## Why it matters
+
+Project roots make sessions auditable. A session record can answer:
+
+- Which repository or project was the work tied to?
+- Which harness id ran?
+- Which working directory did the process start in?
+- Which event log belongs to that run?
+
+Without a project root, a harness run is just a loose process. Coven's job is to make it a named, reviewable session.
+
+## CLI behavior
+
+Run from inside a project:
+
+```bash
+cd /path/to/project
+coven run codex "fix the failing tests"
+```
+
+If Coven cannot resolve a project root, `coven doctor` and `coven run` give setup evidence instead of launching a vague process.
+
+## Client behavior
+
+Clients should treat project root as authority-sensitive input. They can collect and display it, but the daemon still validates it.
+
+Do not trust a browser or chat client to enforce project boundaries on its own. The daemon remains the validation boundary described in [Daemon security posture](/docs/daemon/security).
+
+## Related
+
+- [Working directories](/docs/harnesses/working-directories)
+- [CLI run reference](/docs/cli/run)
+- [Session lifecycle](/docs/familiars/sessions)