docs: add CLI reference section

content/docs/cli/daemon.mdx

@@ -0,0 +1,65 @@
+---
+title: "Daemon Commands"
+summary: "Start, inspect, restart, and stop the local Coven daemon from the CLI."
+description: "CLI reference for coven daemon start, status, restart, and stop."
+read_when:
+  - You need to manage the local daemon process
+  - You are debugging stale sockets or stopped daemon state
+---
+
+# Daemon Commands
+
+The `coven daemon` commands manage the local background process that serves the `/api/v1` socket API and owns live session state.
+
+```bash
+coven daemon start
+coven daemon status
+coven daemon restart
+coven daemon stop
+```
+
+For the process model and recovery behavior, see [Daemon lifecycle](/docs/daemon/lifecycle).
+
+## `coven daemon start`
+
+Starts the daemon, creates `COVEN_HOME` if needed, opens the SQLite store, binds the local socket, and writes daemon metadata.
+
+```bash
+coven daemon start
+```
+
+Use this before daemon-backed clients or local socket integrations.
+
+## `coven daemon status`
+
+Prints whether the daemon is running, stale, or stopped.
+
+```bash
+coven daemon status
+```
+
+Use `status` in support flows before deleting socket files or restarting manually.
+
+## `coven daemon restart`
+
+Stops the current daemon when present, then starts a fresh process and rebinds the socket.
+
+```bash
+coven daemon restart
+```
+
+Use this after upgrades, after changing `COVEN_HOME`, or when `coven doctor` reports stale daemon metadata.
+
+## `coven daemon stop`
+
+Stops the background daemon process.
+
+```bash
+coven daemon stop
+```
+
+Stopping the daemon does not delete the session ledger. Completed session records and event logs remain in `COVEN_HOME`.
+
+## Socket API relationship
+
+The CLI commands are convenience wrappers around the same local authority boundary described in [Daemon lifecycle](/docs/daemon/lifecycle) and [Socket API](/docs/daemon/socket-api). Clients can improve UX, but the daemon validates sensitive decisions.

content/docs/cli/doctor.mdx

@@ -0,0 +1,55 @@
+---
+title: "Doctor"
+summary: "Use coven doctor to inspect store, project, daemon, socket, and harness readiness."
+description: "Reference for coven doctor output and the readiness checks it performs before running harness sessions."
+read_when:
+  - Coven setup is not working
+  - You need evidence before filing a support issue
+---
+
+# Doctor
+
+`coven doctor` is the first command to run after install and the first command to run when something feels broken.
+
+```bash
+coven doctor
+```
+
+It checks the local state directory, project detection, daemon/socket status, and supported harness CLIs.
+
+## What it checks
+
+| Area | What to look for |
+| --- | --- |
+| Store | The path Coven will use for local state. Defaults to `~/.coven` unless `COVEN_HOME` is set. |
+| Project | Whether the current directory resolves to a git/project root. |
+| Daemon | Whether the daemon is running, stale, or stopped, and which socket it owns. |
+| Harnesses | Whether Codex or Claude Code is available on `PATH`. |
+| Next steps | A suggested `coven run <harness> "..."` command when a harness is available. |
+
+## Common next steps
+
+If the daemon is stopped:
+
+```bash
+coven daemon start
+```
+
+If the daemon is stale:
+
+```bash
+coven daemon restart
+```
+
+If no harness is ready, install or authenticate one of the supported harness CLIs, then run `coven doctor` again.
+
+## Support evidence
+
+For support reports, include:
+
+- The exact `coven doctor` output.
+- The command you expected to work.
+- The current working directory, if it is not private.
+- Whether you use custom `COVEN_HOME`.
+
+For daemon-specific failures, continue with [Daemon commands](/docs/cli/daemon) and [Daemon observability](/docs/daemon/observability).

content/docs/cli/index.mdx

@@ -0,0 +1,63 @@
+---
+title: "CLI Reference"
+summary: "The command map for Coven's local CLI: install, doctor, daemon, run, sessions, patch, and pressure diagnostics."
+description: "First-class reference for the coven command and the current Coven CLI command surface."
+read_when:
+  - You want copy-paste Coven commands
+  - You are deciding whether to use the TUI, daemon, run, sessions, or repair flows
+---
+
+# CLI Reference
+
+The user-facing command is `coven`. OpenCoven is the ecosystem and package namespace; Coven is the local runtime and command-line product.
+
+Run `coven` with no arguments when you want the guided interactive shell. Use explicit subcommands when you want a scriptable or copy-paste path.
+
+## Command map
+
+| Command | Use it for |
+| --- | --- |
+| `coven` | Open the interactive chat/shell when stdin/stdout are a terminal. |
+| `coven tui` | Explicitly open the slash-command TUI. |
+| `coven doctor` | Check store, project, daemon, socket, and harness readiness. |
+| `coven daemon start` | Start the local daemon process. |
+| `coven daemon status` | Inspect daemon pid, socket, and health state. |
+| `coven daemon restart` | Rebind the local socket after changes or stale state. |
+| `coven daemon stop` | Stop the local daemon. |
+| `coven run codex "fix tests"` | Launch a project-scoped Codex harness session. |
+| `coven run claude "polish this UI"` | Launch a project-scoped Claude Code harness session. |
+| `coven sessions` | Browse, rejoin, view, archive, summon, or sacrifice sessions. |
+| `coven sessions --all` | Include archived sessions. |
+| `coven sessions --manage` | Force the interactive session browser. |
+| `coven sessions --plain` | Print a plain table for scripts or copying. |
+| `coven sessions --json` | Print a JSON `sessions` array for clients. |
+| `coven attach <session-id>` | Replay/follow a session and forward input to live daemon sessions. |
+| `coven summon <session-id>` | Restore an archived session, then attach. |
+| `coven archive <session-id>` | Hide a completed session while preserving events. |
+| `coven sacrifice <session-id> --yes` | Permanently delete a non-running session and its event log. |
+| `coven patch openclaw` | Launch the guided OpenClaw repair flow. |
+| `coven pc` | Inspect local machine pressure and recovery options. |
+
+## What owns what
+
+The CLI is a client and presentation layer. The daemon is the authority boundary for launches, cwd validation, session liveness, input forwarding, kill requests, and stored event state.
+
+Use these references together:
+
+- [Install](/docs/cli/install) for package and source install paths.
+- [Doctor](/docs/cli/doctor) before opening issues or debugging a setup.
+- [Daemon commands](/docs/cli/daemon) for local process lifecycle.
+- [Run](/docs/cli/run) for project-scoped harness sessions.
+- [Sessions](/docs/cli/sessions) for attach, archive, summon, and sacrifice.
+- [Daemon lifecycle](/docs/daemon/lifecycle) for the process and socket authority model.
+- [Session lifecycle](/docs/familiars/sessions) for status and archive semantics.
+
+## Bare prompt shortcut
+
+When you pass text without a subcommand, Coven treats it as a Cast prompt:
+
+```bash
+coven "explain this repo in 5 bullets"
+```
+
+Use the shortcut for quick interactive work. Use `coven run <harness> <prompt>` when you want an explicit harness and session record.

content/docs/cli/install.mdx

@@ -0,0 +1,57 @@
+---
+title: "Install"
+summary: "Install and run the @opencoven/cli package, or build the coven binary from source."
+description: "Installation reference for Coven CLI through npx, pnpm dlx, global npm install, and source builds."
+read_when:
+  - You need the coven command on PATH
+  - You want to test the published CLI package without installing it globally
+---
+
+# Install
+
+Coven is published as `@opencoven/cli`. The package namespace is OpenCoven, but the command you run is always `coven`.
+
+## Try without installing
+
+Use `npx` or `pnpm dlx` for a one-off check:
+
+```bash
+npx @opencoven/cli doctor
+pnpm dlx @opencoven/cli doctor
+```
+
+This is the safest way to check whether the published package launches on your machine.
+
+## Install globally
+
+Install the wrapper when you want `coven` available repeatedly:
+
+```bash
+npm install -g @opencoven/cli
+coven doctor
+```
+
+The release workflow publishes `@opencoven/cli` plus native platform packages for supported targets. Check npm for the current `latest` tag before writing version-specific install instructions.
+
+## Build from source
+
+Contributors can build the Rust CLI directly:
+
+```bash
+git clone https://github.com/OpenCoven/coven.git
+cd coven
+cargo build --workspace
+cargo run -p coven-cli -- doctor
+```
+
+The source build is useful when you are testing unreleased command behavior. Published package docs should describe released behavior unless the page clearly labels a feature as upcoming.
+
+## First command
+
+After install, run:
+
+```bash
+coven doctor
+```
+
+`doctor` reports local store state, project detection, daemon/socket status, and supported harness availability. See [Doctor](/docs/cli/doctor) for how to read the output.

content/docs/cli/interactive.mdx

@@ -0,0 +1,49 @@
+---
+title: "Interactive Shell and TUI"
+summary: "Use coven or coven tui for the beginner-friendly interactive Coven shell."
+description: "Reference for the default interactive Coven shell, explicit TUI entrypoint, and bare prompt shortcut."
+read_when:
+  - You are new to Coven and want the guided entrypoint
+  - You want to know when coven without arguments opens an interactive surface
+---
+
+# Interactive Shell and TUI
+
+Run `coven` with no arguments when you want Coven to choose the interactive shell for a terminal session.
+
+```bash
+coven
+```
+
+Run `coven tui` when you want to be explicit:
+
+```bash
+coven tui
+```
+
+The interactive surface is designed for humans who do not want to memorize subcommands. It starts with setup checks and safe first actions before launching a harness.
+
+## Terminal routing
+
+When stdin and stdout are both terminals, `coven` opens the interactive chat/shell. When you pass a bare prompt, Coven routes the text as a Cast prompt:
+
+```bash
+coven "summarize the current project"
+```
+
+Use [Run](/docs/cli/run) if you want to choose a harness explicitly:
+
+```bash
+coven run codex "summarize the current project"
+```
+
+## When to use explicit commands
+
+Use explicit subcommands for automation, support, or docs:
+
+- `coven doctor` for setup checks.
+- `coven daemon status` for daemon process state.
+- `coven sessions --plain` for copyable tables.
+- `coven sessions --json` for client integration.
+
+The interactive shell is the front door. The daemon and session commands are the operational reference paths.

content/docs/cli/meta.json

@@ -0,0 +1,17 @@
+{
+  "title": "CLI Reference",
+  "description": "Install, inspect, run, recover, and automate Coven from the coven command.",
+  "root": true,
+  "icon": "LuTerminal",
+  "pages": [
+    "index",
+    "install",
+    "interactive",
+    "doctor",
+    "daemon",
+    "run",
+    "sessions",
+    "patch-openclaw",
+    "pc"
+  ]
+}

content/docs/cli/patch-openclaw.mdx

@@ -0,0 +1,55 @@
+---
+title: "Patch OpenClaw"
+summary: "Use coven patch openclaw for guided OpenClaw repair sessions."
+description: "Reference for the coven patch openclaw repair flow, options, dry runs, verification profiles, and safety behavior."
+read_when:
+  - You are repairing an OpenClaw checkout
+  - You want Coven to launch a harness with a structured repair brief
+---
+
+# Patch OpenClaw
+
+`coven patch openclaw` is a guided repair flow for OpenClaw contributors and users.
+
+```bash
+coven patch openclaw
+```
+
+It detects an OpenClaw repository, inspects git state, asks what is broken, chooses a supported harness, launches a repair session, and runs a verification profile.
+
+## Non-interactive shape
+
+Use flags when calling from scripts or a higher-level client:
+
+```bash
+coven patch openclaw "fix the failing gateway auth test" \
+  --repo /path/to/openclaw \
+  --harness codex \
+  --verify default \
+  --non-interactive
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--repo <path>` | OpenClaw checkout to repair. |
+| `--harness <id>` | Supported harness id, usually `codex` or `claude`. |
+| `--verify <profile>` | Verification profile for the repair report. |
+| `--non-interactive` | Requires issue text and harness flags instead of prompting. |
+| `--dry-run` | Prints the repair brief without launching the harness. |
+| `--keep-session` | Preserves the session after the repair flow. |
+
+## Dry run
+
+Use `--dry-run` to inspect the repair brief first:
+
+```bash
+coven patch openclaw "diagnose flaky session polling" --repo /path/to/openclaw --harness codex --dry-run
+```
+
+Dry runs are useful for auditing what the harness will receive before work starts.
+
+## Dirty worktrees
+
+When existing changes are detected in interactive mode, Coven warns before launching a harness. It does not silently stash or overwrite work.
+
+This command is purpose-built for OpenClaw. For general project work, use [Run](/docs/cli/run).