docs(guide): scaffold the CastCodes → Coven demo loop

content/docs/guide/demo-loop/finish-loop.mdx

@@ -0,0 +1,106 @@
+---
+title: "Step 5 — Finish the loop"
+description: "Every session ends explicitly: merge, PR, archive, or sacrifice. Pick one and the loop closes."
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Mermaid } from '@/components/mermaid';
+
+A session that never ends explicitly is the failure mode Coven exists to prevent. Step 5 is the rule: pick one of four outcomes, and the loop closes. No "ghost" sessions, no implicit completion.
+
+## The four outcomes
+
+<Mermaid chart={`
+flowchart TD
+  Inspect{Work usable?} -->|Yes, ship it| Merge["Merge to branch"]
+  Inspect -->|Yes, but needs review| PR["Open a pull request"]
+  Inspect -->|No, but keep the log| Archive["Archive session"]
+  Inspect -->|No, throw it away| Sacrifice["Sacrifice session"]
+`} />
+
+| Outcome | What it means | Reversible? |
+| --- | --- | --- |
+| **Merge** | The agent's worktree changes land on your active branch. | Yes (revert commit). |
+| **PR** | A pull request is opened for review. | Yes (close the PR). |
+| **Archive** | The session record + event log stay; the live PTY stops. | Yes (rejoin replays the log). |
+| **Sacrifice** | The session record, event log, and worktree are deleted. | No. |
+
+## The flow
+
+<Steps>
+  <Step>
+    ### Merge
+
+    Land the worktree's changes on your active branch. Useful when you trust the work and want it in mainline immediately.
+
+    > TODO: CastCodes UI — the "Merge" pane menu action. Document whether it: (a) merges the worktree branch into the active branch in your main checkout, (b) replays the diff as a commit, (c) something else. Also document the cleanup of the worktree afterward.
+
+    CLI equivalent:
+
+    ```bash
+    git checkout main
+    git merge <worktree-branch>
+    git worktree remove <worktree-path>
+    coven sessions archive <session-id>
+    ```
+  </Step>
+
+  <Step>
+    ### Open a PR
+
+    Push the worktree branch and open a pull request — the standard review path when you want a teammate (or your future self) to look first.
+
+    > TODO: CastCodes UI — pane action label. Confirm whether it (a) just runs `gh pr create`, (b) opens a draft PR form, (c) integrates with a specific provider.
+
+    CLI equivalent:
+
+    ```bash
+    git push -u origin <worktree-branch>
+    gh pr create --title "..." --body "..."
+    coven sessions archive <session-id>
+    ```
+  </Step>
+
+  <Step>
+    ### Archive
+
+    Stop the PTY (if still running), but keep the session record and event log so you can rejoin and replay the work later. Useful when you don't want to ship the changes but want to remember what the agent tried.
+
+    ```bash
+    coven sessions archive <session-id>
+    ```
+
+    Archived sessions appear in `coven sessions --all` and remain replayable through `coven rejoin --replay`.
+  </Step>
+
+  <Step>
+    ### Sacrifice
+
+    Delete the session record, its event log, and (if it lived in a per-lane worktree) the worktree itself. This is the explicit "throw it all away" path.
+
+    ```bash
+    coven sessions sacrifice <session-id>
+    ```
+
+    <Callout type="warn" title="Destructive">
+      Sacrifice is irreversible. The event log is gone — there's no replay. Use this when the agent's attempt was a dead end and the log isn't worth keeping.
+    </Callout>
+  </Step>
+</Steps>
+
+## Why "explicit either way" matters
+
+Implicit cleanup is how agent workflows accumulate ghost branches, untracked worktrees, and "wait, what did the agent change?" mysteries. The demo loop is built around the inverse:
+
+- **Step 1** makes the *project boundary* explicit (root and cwd).
+- **Step 2** makes the *intent* explicit (harness + prompt + title).
+- **Step 3** makes the *work* explicit (live pane + event log).
+- **Step 4** makes the *result* explicit (diff + validation).
+- **Step 5** makes the *outcome* explicit (one of four, by your choice).
+
+If you finished step 5, the session is closed. The next loop starts again at step 1.
+
+<Callout type="info" title="Back to the overview">
+  Loop closed. Return to [the demo loop overview](/docs/guide/demo-loop) or start a new loop from [step 1](/docs/guide/demo-loop/open-project).
+</Callout>

content/docs/guide/demo-loop/index.mdx

@@ -0,0 +1,40 @@
+---
+title: "The CastCodes → Coven demo loop"
+description: "The five-step path from an open project to a finished agent session — open, launch, watch, inspect, finish."
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Mermaid } from '@/components/mermaid';
+
+The demo loop is the canonical end-to-end story for working in Coven through CastCodes. It traces a single piece of intent from the moment you open a project to the moment you explicitly finish the session — merge, PR, archive, or sacrifice. The same loop runs from the `coven` CLI without CastCodes; this guide just adds the visible cockpit on top.
+
+<Callout type="info" title="What the loop is for">
+  Every step makes the agent's work explicit. There is no hidden background work, no implicit completion. Intent enters at step 1; an artifact (merged code, PR, archived log, or deleted session) leaves at step 5.
+</Callout>
+
+## The five steps
+
+<Mermaid chart={`
+flowchart LR
+  S1["1. Open project"] --> S2["2. Launch session"]
+  S2 --> S3["3. Watch session"]
+  S3 --> S4["4. Inspect changes"]
+  S4 --> S5["5. Finish loop"]
+  S5 -.-> S1
+`} />
+
+| Step | What you do | Where it happens |
+| --- | --- | --- |
+| [1. Open project](/docs/guide/demo-loop/open-project) | Pick a project root and confirm the daemon is running. | CastCodes project sidebar + `coven daemon status` |
+| [2. Launch session](/docs/guide/demo-loop/launch-session) | Choose a harness, write a prompt, kick it off. | CastCodes agent launcher or `coven run <harness> "<prompt>"` |
+| [3. Watch session](/docs/guide/demo-loop/watch-session) | Watch output stream into a visible pane. | CastCodes session pane or `coven sessions` / `coven rejoin` |
+| [4. Inspect changes](/docs/guide/demo-loop/inspect-changes) | Read the diff, run validation, decide. | CastCodes diff view + your usual test/lint commands |
+| [5. Finish loop](/docs/guide/demo-loop/finish-loop) | Merge, PR, archive, or sacrifice. Explicit either way. | CastCodes pane menu or `coven sessions archive` / `sacrifice` |
+
+## CLI parity
+
+Every step in the loop has a CLI equivalent in [the `coven` reference](/docs/cli). CastCodes is the visible cockpit — useful, not required. If you're scripting the loop in CI or working over SSH, the CLI runs the same daemon and the same harness sessions.
+
+<Callout type="warn" title="Scaffold in progress">
+  This page set is the first pass at the demo-loop docs. Each step page is a scaffold with the right structure, accurate CLI commands, and TODO markers for the CastCodes-side UI details (screenshots, exact menu labels). Track progress under the `community/roadmap-loop` group in the [Docs Issue Plan](/docs/reference/issue-plan).
+</Callout>

content/docs/guide/demo-loop/inspect-changes.mdx

@@ -0,0 +1,94 @@
+---
+title: "Step 4 — Inspect files and diffs"
+description: "Read what the agent changed, run validation, and decide whether the work is acceptable before finishing the loop."
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { File, Files, Folder } from 'fumadocs-ui/components/files';
+
+The harness has been editing files on disk inside the project root. Step 4 is the human check: read the diff, run your usual validation, and form an opinion about whether step 5 should merge or sacrifice the work.
+
+## What "inspect" means in Coven
+
+Coven does not own diffs or test runners — it owns the **session** (a PTY-backed harness invocation and its event log). File changes are just regular edits in your working tree, observable through git, your editor, or CastCodes' file browser. Coven's contribution is making it obvious *which session* produced *which changes*.
+
+<Files>
+  <Folder name="example-project" defaultOpen>
+    <Folder name="src" defaultOpen>
+      <File name="index.ts" />
+    </Folder>
+    <Folder name=".coven" defaultOpen>
+      <File name="sessions.db" />
+      <File name="events.log" />
+    </Folder>
+    <File name="package.json" />
+  </Folder>
+</Files>
+
+The agent's edits land in your source files. The session record and event log stay under `~/.coven/` (or `$COVEN_HOME`) — they're not committed.
+
+<Callout type="warn" title="Worktree isolation is a CastCodes feature">
+  If you launched the session into a per-lane git worktree (the CastCodes default for parallel agent lanes — see the "Git worktree isolation per agent lane" roadmap row), the changes live in that worktree, not in your main checkout. Step 5 will help you decide what to do with the lane.
+</Callout>
+
+## The flow
+
+<Steps>
+  <Step>
+    ### Open the diff
+
+    > TODO: CastCodes UI — exact path to the diff view. Is it a pane sibling to the agent pane, a dedicated tab, or an overlay? Document keyboard shortcuts (next file / hunk).
+
+    From the CLI, the usual `git status` / `git diff` work in the session's worktree:
+
+    ```bash
+    git status
+    git diff --stat
+    git diff path/to/changed-file
+    ```
+  </Step>
+
+  <Step>
+    ### Validate
+
+    Run your tests, type checker, linter — whatever you would run before any other commit. Coven does not run these for you.
+
+    ```bash
+    npm test
+    npm run typecheck
+    npm run lint
+    ```
+
+    > TODO: CastCodes UI — is there a "Run validation" button on the pane that runs configured scripts? If so, document the configuration source (package.json scripts? a CastCodes-specific file?).
+  </Step>
+
+  <Step>
+    ### Re-engage the agent (optional)
+
+    If the agent missed something, you can send input to the same session — see [Step 3 → Send input](/docs/guide/demo-loop/watch-session). For a more significant follow-up, launch a new session from step 2 with a refined prompt and let it pick up the worktree state.
+  </Step>
+
+  <Step>
+    ### Form a verdict
+
+    You're now ready to decide between the four explicit outcomes in step 5: merge, PR, archive, or sacrifice.
+  </Step>
+</Steps>
+
+## CLI equivalent
+
+```bash
+# Find the worktree associated with this session (if launched into one)
+coven sessions show <session-id>
+
+# Replay output later if needed
+coven rejoin <session-id> --replay
+
+# View the full event log
+coven sessions log <session-id>
+```
+
+<Callout type="info" title="Next">
+  Continue to [Step 5 — Finish the loop](/docs/guide/demo-loop/finish-loop). Every session ends explicitly.
+</Callout>

content/docs/guide/demo-loop/launch-session.mdx

@@ -0,0 +1,109 @@
+---
+title: "Step 2 — Launch a session"
+description: "Choose a harness, write a prompt, and spawn a Coven-backed Codex or Claude Code session inside the project."
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Mermaid } from '@/components/mermaid';
+
+A session is a single harness invocation: a PTY-backed Codex or Claude Code process running inside the project, with its output recorded to the daemon's event log. CastCodes lets you launch one from a menu; the CLI's `coven run` does the same thing.
+
+## What gets created
+
+When you launch, the daemon:
+
+1. Writes a `SessionRecord` to the SQLite ledger with `status: "created"`.
+2. Spawns the harness with the requested `cwd`, `prompt`, and `title`.
+3. Begins appending `OutputEvent` / `StatusEvent` rows to the session's event log.
+4. Flips the record to `status: "running"`.
+
+The session is now reachable by id from the API (`/api/v1/sessions/<id>`), the CLI (`coven sessions`), and CastCodes (it appears as a new pane).
+
+## The flow
+
+<Steps>
+  <Step>
+    ### Pick a harness
+
+    Coven ships with two adapters in `coven.daemon.v1`:
+
+    - **`codex`** — OpenAI Codex CLI. See [Harnesses → Codex](/docs/harnesses/codex).
+    - **`claude`** — Anthropic Claude Code. See [Harnesses → Claude Code](/docs/harnesses/claude-code).
+
+    Other harnesses are tracked in the [roadmap](/docs/reference/roadmap) under "Additional harness adapters."
+
+    > TODO: CastCodes UI — the launcher's harness picker control. Is it a dropdown, a radio, a multi-select for parallel lanes? Document the exact behavior plus the keyboard shortcut.
+  </Step>
+
+  <Step>
+    ### Write the prompt
+
+    The prompt is passed to the harness as its final argument — Codex and Claude Code each interpret it as the initial task. Keep it scoped to one outcome; you can always launch another session for a follow-up.
+
+    > TODO: CastCodes UI — does the prompt input support history? Templates? Cast Codes shortcuts ([Cast Codes](/docs/guide/cast-codes)) for prompts like `/fix` or `/explain`?
+  </Step>
+
+  <Step>
+    ### Launch
+
+    CastCodes posts to the daemon's session endpoint. The PTY spawns; output starts flowing to the new pane.
+
+    > TODO: CastCodes UI — confirm whether the launch button is one click, two-step (prepare → confirm), or whether multi-select launches N panes at once. See the roadmap row "Multi-select agent launches" — that's the path for parallel lanes.
+  </Step>
+</Steps>
+
+## CLI equivalent
+
+```bash
+coven run codex "fix the failing tests"
+
+# Equivalent explicit form:
+coven run \
+  --harness codex \
+  --project ~/code/example-project \
+  --title "fix tests" \
+  "fix the failing tests"
+```
+
+Or directly via the socket API:
+
+```bash
+curl --unix-socket "$HOME/.coven/coven.sock" \
+  -X POST -H 'content-type: application/json' \
+  -d '{
+    "projectRoot": "/Users/example/example-project",
+    "cwd":         "/Users/example/example-project",
+    "harness":     "codex",
+    "prompt":      "fix the failing tests",
+    "title":       "fix tests"
+  }' \
+  http://localhost/api/v1/sessions
+```
+
+See [the API reference](/docs/openapi/sessions/create-session) for the full request shape.
+
+## Launch path
+
+<Mermaid chart={`
+sequenceDiagram
+  participant CC as CastCodes
+  participant D as coven daemon
+  participant L as SQLite ledger
+  participant H as Harness PTY
+
+  CC->>D: POST /api/v1/sessions { projectRoot, cwd, harness, prompt, title }
+  D->>L: INSERT SessionRecord (status: created)
+  D->>H: spawn harness in PTY
+  H-->>D: stdout/stderr stream
+  D->>L: append OutputEvent rows; flip status to running
+  D-->>CC: 201 { id, status: "running", ... }
+`} />
+
+<Callout type="warn" title="Validation, not magic">
+  The daemon validates `projectRoot` and `cwd` (cwd must canonicalize inside the project root) and allowlists `harness` to the two adapters above. Anything else fails closed with `error.code: "invalid_request"` — branch on the code, not the message text.
+</Callout>
+
+<Callout type="info" title="Next">
+  Continue to [Step 3 — Watch the session](/docs/guide/demo-loop/watch-session). Output is streaming.
+</Callout>

content/docs/guide/demo-loop/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Demo Loop",
+  "description": "End-to-end walkthrough from open-project to finish.",
+  "pages": [
+    "index",
+    "open-project",
+    "launch-session",
+    "watch-session",
+    "inspect-changes",
+    "finish-loop"
+  ]
+}