docs: clarify Coven as a substrate for harnesses, not a harness itself#15
Merged
Conversation
- 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 <nova@opencoven.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Clarifies Coven’s positioning in the docs as a runtime substrate that harnesses run within (not a harness itself), reducing confusion for new readers across key entry points.
Changes:
- Reframes “What Coven Is” in Getting Started around the substrate/harness distinction and adds practical benefit bullets + updated promise line.
- Updates Concepts to explicitly define Coven as not a harness and explains what the substrate provides to harnesses.
- Adds an upfront “Coven is not a harness” note and a new
read_whenentry to the “What Is a Harness?” page.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| content/docs/harnesses/what-is-a-harness.mdx | Adds explicit “Coven is not a harness” framing and reinforces the substrate boundary. |
| content/docs/guide/getting-started.mdx | Rewrites the opener to define Coven as a substrate and enumerates why that matters. |
| content/docs/guide/concepts.mdx | Strengthens the Coven definition to explicitly separate substrate vs harness responsibilities. |
| 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. |
| - **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. |
|
|
||
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Adds explicit substrate framing in three places:
getting-started.mdxconcepts.mdx(Coven definition)what-is-a-harness.mdxread_whenentry for the substrate distinctionWhy
Readers new to Coven often confuse it with being another coding-agent harness (like Codex or Claude Code). This makes the substrate/harness distinction explicit and consistent across the three highest-traffic entry points.
Co-authored-by: Nova nova@opencoven.dev