Skip to content

docs: reshape canonical first-session and troubleshooting journey - #79

Open
CompleteDotTech wants to merge 2 commits into
OpenCoven:mainfrom
CompleteDotTech:agent/issue-775-docs-reshape-canonical-first-session-and
Open

docs: reshape canonical first-session and troubleshooting journey#79
CompleteDotTech wants to merge 2 commits into
OpenCoven:mainfrom
CompleteDotTech:agent/issue-775-docs-reshape-canonical-first-session-and

Conversation

@CompleteDotTech

Copy link
Copy Markdown
Member

Summary

Reshape the two docs-owned journey pages so coven-docs is the progressive end-user path issue #775 asks for:

  • guide/getting-started now walks the whole first-session journey in order: install and verify (npm install -g @opencoven/clicoven --versioncoven doctor), connect a harness (coven setup codex|claude|copilot), run one recorded session (coven daemon startcoven run codex "explain this repo in 5 bullets"coven sessions), inspect the record (coven sessions show/events/log, coven attach, coven status), then a new Recover when a step fails leg and an explicit Advanced next steps table (provider setup, harnesses, daemon, deployments, sessions, local API, memory as preview, hub/scheduler) plus coven help --all for the full grouped command surface. The old flat "Continue" list is replaced by that grouped expansion.
  • reference/troubleshooting becomes the explicit recovery leg of the journey: a new Recovery rules section (fix the first failing branch, rerun doctor, inspect before you mutate, sacrifice permanence) and a journey-stage → section map (install → harness → daemon → run → session). The existing ordered decision tree, error-code lookup, and all failure sections are unchanged, so every existing anchor stays valid.

Docs-only diff (2 files, +80/−15). No CLI-reference pages touched.

Issue

Refs OpenCoven/coven#775 (child of OpenCoven/coven#670). Closes OpenCoven/coven#775 on upstream merge (cross-reference — GitHub cannot auto-close a coven issue from this repository).

How claims were verified

  • Commands, flags, and subcommands checked against OpenCoven/coven@main (1364cec9dbaf1e2aca2e4544dec0e1ce807d859c): crates/coven-cli/src/main.rs (doctor, setup + Selector::{Codex,Claude,Copilot} and --verify, daemon start/status/restart/stop, run with --cwd, sessions {search,show,events,log} with --plain/--manage/--all, attach, archive, sacrifice --yes, summon, status, pc), crates/coven-cli/src/help.rs (coven help --all), crates/coven-cli/src/pc/mod.rs (status/top/disk + --confirm relief).
  • Stability labels respected per docs/site-manifest.json: guide and reference are stable and owned by OpenCoven/coven-docs; memory-models is labeled "(preview)" in the advanced table; no experimental work is presented as supported.
  • Required getting-started onboarding mentions from scripts/check-cli-docs.mjs are preserved verbatim.

Test plan

  • pnpm run typecheck (after pnpm exec fumadocs-mdx to regenerate .source)
  • pnpm run check:content (site-manifest, source-lock, english-only, no-leading-h1, product-scope, fumadocs, daemon/cli/coven-code/harness/memory docs contracts, mermaid parse — 14 diagrams valid)
  • pnpm run check:links — 0 errors
  • pnpm run check:anchors — passed across 86 MDX pages
  • pnpm run check:automation, pnpm run check:generated, pnpm run test:api-runner (23 pass)
  • git diff --check
  • pnpm run build (Next.js production build) — deferred to CI
  • pnpm run test:smoke (rendered-route assertions incl. /docs/guide/getting-started → "Run a first session") — deferred to CI

Make the first-session page the progressive end-user path from #775:
install and verify, connect a harness, one recorded session, inspect the
record, then an explicit recovery leg and grouped advanced next steps
including `coven help --all`. Give Troubleshooting recovery rules and a
journey-stage map so failures route back through doctor.

Claims verified against OpenCoven/coven@main (crates/coven-cli/src/main.rs,
setup/mod.rs, pc/mod.rs): command names, flags, and subcommands.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@vercel

vercel Bot commented Aug 30, 2026

Copy link
Copy Markdown

@CompleteDotTech is attempting to deploy a commit to the 0xBuns Team on Vercel.

A member of the Team first needs to authorize it.

- doctor: document the new install:conflicts check (shadowed installs,
  prose Installs: section, path-free JSON warning, warn-not-fail exit code)
- daemon: new Routine automations page covering the coven.automations
  capability, definition schema, 60-second scheduler tick, and run ledger
- daemon: complete index/configuration/observability enumerations for
  automation routines in coven.sqlite3 and automations tick failures in
  daemon-recovery.log
- source-lock: bump verification boundary to 39feb6de98816d10b490091e918f62035e6ce0df
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: reshape canonical first-session and troubleshooting journey

1 participant