From b39107bccd08c13e470b6517f846a5fd5803f018 Mon Sep 17 00:00:00 2001 From: Val Alexander <68980965+BunsDev@users.noreply.github.com> Date: Sun, 24 May 2026 16:24:36 -0500 Subject: [PATCH] docs: clarify Coven as a substrate for harnesses, not a harness itself - getting-started: replace 'local-first runtime for harnesses' with substrate framing; add benefits (provider independence, enforced boundaries, auditable history, unified client surface) - concepts: expand Coven definition to explicitly state it is not a harness and explain what the substrate provides - what-is-a-harness: add prominent 'Coven is not a harness' note at top of the page; add read_when entry for the substrate distinction Co-authored-by: Nova --- content/docs/guide/concepts.mdx | 2 ++ content/docs/guide/getting-started.mdx | 13 +++++++++++-- content/docs/harnesses/what-is-a-harness.mdx | 3 +++ 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/content/docs/guide/concepts.mdx b/content/docs/guide/concepts.mdx index 691c510..6953550 100644 --- a/content/docs/guide/concepts.mdx +++ b/content/docs/guide/concepts.mdx @@ -43,6 +43,8 @@ Use **OpenCoven** when talking about the broader project family. Coven is the local runtime substrate. It owns project-scoped harness sessions, PTYs, logs, local daemon state, and the socket API. +Coven is **not a harness**. Harnesses — Codex, Claude Code, and future adapters — are external coding-agent CLIs that operate *within* Coven's substrate. Coven provides the shared layer they all run on: enforced project boundaries, supervised PTY lifecycle, append-only session records, and a stable local API that any client can talk to regardless of which harness is running. + Use **Coven** for the CLI, daemon, Rust crate, npm wrapper, and local session runtime. ## CovenCLI diff --git a/content/docs/guide/getting-started.mdx b/content/docs/guide/getting-started.mdx index b901ba4..e7d0b84 100644 --- a/content/docs/guide/getting-started.mdx +++ b/content/docs/guide/getting-started.mdx @@ -9,11 +9,20 @@ This guide takes a new user from a fresh checkout or npm install to a visible pr ## What Coven Is -Coven is a local-first runtime for coding-agent harnesses. It runs supported CLIs such as Codex and Claude Code inside explicit project boundaries, records session metadata and events, and exposes the work through a CLI, TUI, and local socket API. +Coven is not a harness. It is the **substrate** that harnesses operate within. + +A harness — Codex, Claude Code, or any future adapter — brings its own provider credentials, model selection, and tool runtime. Coven provides the shared layer underneath: enforced project boundaries, supervised PTY processes, an append-only session record, and a stable local API. When work passes through Coven, every run gains consistent lifecycle management, replay, and auditability regardless of which harness ran it. + +This matters in practice: + +- **Provider independence** — switch between Codex and Claude Code without rewiring your workflow; the substrate stays the same. +- **Enforced boundaries** — harnesses can only operate inside the project root you declared; no harness can silently widen scope. +- **Auditable history** — every session is recorded and replayable; completed work survives process restarts. +- **Unified client surface** — any client (CLI, TUI, CastCodes, OpenClaw, or a script) talks to any harness through one local API. The short promise: -> One project. Any harness. Visible work. +> One substrate. Any harness. Reproducible, auditable work. ## Install Paths diff --git a/content/docs/harnesses/what-is-a-harness.mdx b/content/docs/harnesses/what-is-a-harness.mdx index 534b60e..1432bcb 100644 --- a/content/docs/harnesses/what-is-a-harness.mdx +++ b/content/docs/harnesses/what-is-a-harness.mdx @@ -4,11 +4,14 @@ summary: "A harness is a PTY-driven adapter for one external coding-agent CLI." description: "Definition of a Coven harness and the boundary between harnesses, familiars, clients, and the daemon." read_when: - You are new to Coven terminology + - You need to explain why a harness is not the same thing as Coven itself - You need to explain why a harness is not the same thing as a familiar --- A harness is a coding-agent CLI that Coven can run as a supervised process. The harness is not the daemon, not a familiar, and not the user interface. It is the external agent runtime that receives a prompt and works inside a PTY. +**Coven is not a harness.** Coven is the substrate that harnesses run within. It provides enforced project boundaries, supervised PTY lifecycle, session records, event logs, and a unified local API — so that any harness can operate in a well-defined, auditable, reproducible way without each one needing to reinvent lifecycle management, boundary enforcement, or client access. + ## Boundary map | Term | Role |