docs(guide): scaffold the CastCodes → Coven demo loop#13
Merged
Conversation
Adds a six-page demo loop walkthrough under content/docs/guide/demo-loop/ matching the five "Next" roadmap items: index — overview, mermaid flow, links to each step open-project — project root + daemon handshake launch-session — harness choice, prompt, POST /sessions watch-session — pane streaming, status transitions, event cursor inspect-changes — diff review and validation (Coven-doesn't-own-diffs framing) finish-loop — the four explicit outcomes: merge, PR, archive, sacrifice Each step page is a "heavy scaffold": Fumadocs <Steps>, <Files>, and <Mermaid> mockups carrying the flow, accurate CLI commands for every action, links into the existing harness/daemon/openapi references, and explicit `> TODO: CastCodes UI` markers where the cockpit-side UI details still need to be filled in (launcher labels, pane chrome, diff view shortcuts, merge-action semantics). Wired into content/docs/guide/meta.json after `cast-codes` and before `architecture` so the reading order matches the onboarding flow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Adds a new “Demo Loop” section under the Guide that scaffolds the CastCodes → Coven five-step walkthrough (open project → launch session → watch session → inspect changes → finish loop), using Fumadocs components and Mermaid diagrams to structure the flow.
Changes:
- Adds
demo-loop/doc section (index + 5 step pages) undercontent/docs/guide/. - Wires the new section into the Guide reading order via
content/docs/guide/meta.json. - Introduces a
demo-loop/meta.jsonto define page ordering within the section.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 18 comments.
Show a summary per file
| File | Description |
|---|---|
| content/docs/guide/meta.json | Adds demo-loop to the Guide sidebar ordering. |
| content/docs/guide/demo-loop/meta.json | Defines “Demo Loop” section metadata and page order. |
| content/docs/guide/demo-loop/index.mdx | Overview page with 5-step loop diagram and navigation. |
| content/docs/guide/demo-loop/open-project.mdx | Step 1 scaffold: daemon readiness + project root concept + handshake diagram. |
| content/docs/guide/demo-loop/launch-session.mdx | Step 2 scaffold: harness selection + session creation via CLI/API + lifecycle diagram. |
| content/docs/guide/demo-loop/watch-session.mdx | Step 3 scaffold: output/event streaming + cursor replay diagram + CLI/API parity. |
| content/docs/guide/demo-loop/inspect-changes.mdx | Step 4 scaffold: diff/validation workflow framing + CLI parity. |
| content/docs/guide/demo-loop/finish-loop.mdx | Step 5 scaffold: explicit outcomes (merge/PR/archive/sacrifice) + CLI parity. |
| import { Step, Steps } from 'fumadocs-ui/components/steps'; | ||
| import { Mermaid } from '@/components/mermaid'; | ||
|
|
||
| Once the harness is running, CastCodes streams its output into a pane and reflects state transitions in the agent panel. From the CLI, the same stream is reachable by polling `/api/v1/sessions/<id>/events` with a cursor, or by rejoining the session interactively. |
Comment on lines
+63
to
+67
| # Tail output for one session | ||
| coven rejoin <session-id> | ||
|
|
||
| # Send input to a running session | ||
| echo "y" | coven sessions input <session-id> |
| ```bash | ||
| # Replayable event stream with afterSeq cursor for resume | ||
| curl --unix-socket "$HOME/.coven/coven.sock" \ | ||
| "http://localhost/api/v1/sessions/<id>/events?afterSeq=0" |
Comment on lines
+88
to
+93
| Client->>D: GET /events?afterSeq=0 | ||
| D->>L: read seq > 0 | ||
| L-->>D: page of events + nextCursor | ||
| D-->>Client: { events, nextCursor: { afterSeq: 42 }, hasMore: true } | ||
| Note over Client: Persist afterSeq=42 for resume after disconnect. | ||
| Client->>D: GET /events?afterSeq=42 |
Comment on lines
+13
to
+16
| ## What "project root" means | ||
|
|
||
| Coven's daemon will refuse any session whose harness `cwd` does not canonicalize inside the requested `projectRoot`. The project root you open in CastCodes is the same string you would pass to `coven run --project <root>` or to a `POST /api/v1/sessions` request. | ||
|
|
Comment on lines
+22
to
+27
| | 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. | |
Comment on lines
+41
to
+46
| ```bash | ||
| git checkout main | ||
| git merge <worktree-branch> | ||
| git worktree remove <worktree-path> | ||
| coven sessions archive <session-id> | ||
| ``` |
Comment on lines
+66
to
+75
| ### 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> |
Comment on lines
+83
to
+87
| 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. |
| participant FS as Project filesystem | ||
|
|
||
| CC->>D: GET /api/v1/health | ||
| D-->>CC: 200 { apiVersion, covenVersion, daemon } |
Comment on lines
+14
to
+18
| | Where | What | Source | | ||
| | --- | --- | --- | | ||
| | Session pane (live) | Raw PTY output, including ANSI colors. | `OutputEvent` rows from the event log. | | ||
| | Status bar / pill | `running`, `completed`, `failed`, `killed`, `orphaned`. | `SessionRecord.status` + `StatusEvent` rows. | | ||
| | Sidebar entry | Title, harness, age, status. | `GET /api/v1/sessions`. | |
| import { Step, Steps } from 'fumadocs-ui/components/steps'; | ||
| import { Mermaid } from '@/components/mermaid'; | ||
|
|
||
| Once the harness is running, CastCodes streams its output into a pane and reflects state transitions in the agent panel. From the CLI, the same stream is reachable by polling `/api/v1/sessions/<id>/events` with a cursor, or by rejoining the session interactively. |
Comment on lines
+63
to
+67
| # Tail output for one session | ||
| coven rejoin <session-id> | ||
|
|
||
| # Send input to a running session | ||
| echo "y" | coven sessions input <session-id> |
Comment on lines
+72
to
+76
| ```bash | ||
| # Replayable event stream with afterSeq cursor for resume | ||
| curl --unix-socket "$HOME/.coven/coven.sock" \ | ||
| "http://localhost/api/v1/sessions/<id>/events?afterSeq=0" | ||
| ``` |
Comment on lines
+88
to
+93
| Client->>D: GET /events?afterSeq=0 | ||
| D->>L: read seq > 0 | ||
| L-->>D: page of events + nextCursor | ||
| D-->>Client: { events, nextCursor: { afterSeq: 42 }, hasMore: true } | ||
| Note over Client: Persist afterSeq=42 for resume after disconnect. | ||
| Client->>D: GET /events?afterSeq=42 |
| 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> |
Comment on lines
+26
to
+28
| | 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` | |
Comment on lines
+30
to
+32
| | [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` | |
Comment on lines
+42
to
+46
| git checkout main | ||
| git merge <worktree-branch> | ||
| git worktree remove <worktree-path> | ||
| coven sessions archive <session-id> | ||
| ``` |
Comment on lines
+58
to
+62
| ```bash | ||
| git push -u origin <worktree-branch> | ||
| gh pr create --title "..." --body "..." | ||
| coven sessions archive <session-id> | ||
| ``` |
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.
Summary
Scaffolds the five-page demo loop walkthrough from the roadmap's CastCodes "Demo loop" Next items, under
content/docs/guide/demo-loop/. Index + 5 step pages, 556 lines.index.mdxopen-project.mdxlaunch-session.mdxPOST /sessionswatch-session.mdxafterSeqresumeinspect-changes.mdxfinish-loop.mdxScaffold philosophy
Heavy scaffold + CSS-only mockups, per the requested depth:
content/docs/{cli,daemon,harnesses,openapi}/references. Every step has accurate CLI commands and (where relevant) a Mermaid sequence diagram showing what hits the daemon socket.<Steps>,<Files>,<Mermaid>,<Callout>— carry the flow so the pages have shape even without screenshots.> TODO: CastCodes UImarkers at every spot where the cockpit-side UI details still need real input (launcher labels, pane chrome controls, diff-view keyboard shortcuts, merge-action semantics, validation hook configuration). Greppable for the next pass:grep -rn "TODO: CastCodes UI" content/docs/guide/demo-loop/.Wiring
content/docs/guide/meta.jsonpages list updated:"cast-codes", + "demo-loop", "architecture"Reading order: existing onboarding → cast-codes intro → demo loop → architecture.
Test plan
npm run check:no-leading-h1— no body H1 in any new MDX (guard enforces it).npm run check:english-only— passes.npx tsc --noEmit— passes.<Files>mockup shows the right tree.Open scoping questions for follow-up PRs
familiars/or stay only underguide/?> TODO: CastCodes UImarkers are intentional placeholders. They can become GitHub issues undercommunity/roadmap-loopfrom Docs Issue Plan.🤖 Generated with Claude Code