diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx new file mode 100644 index 0000000..70136b8 --- /dev/null +++ b/content/docs/guides/index.mdx @@ -0,0 +1,56 @@ +--- +title: "Guides" +summary: "End-to-end, step-by-step guides that walk through one common task at a time, from prerequisites to a verified working result." +description: "Catalog of task-oriented Coven guides: what every guide contains, which guides are planned, and where to start while the catalog grows." +read_when: + - You want a complete walkthrough of one task instead of reference material + - You are new to Coven and want the shortest path to a working result +--- + +Guides are task-oriented, step-by-step walkthroughs. Each one answers a single common question end to end: what to install, which commands to run, what output to expect, and how to recover when a step fails. + +They complement the rest of the documentation rather than replacing it: + +- The [Guide](/docs/guide/getting-started) section explains how Coven works — concepts, surfaces, and architecture. +- Reference sections ([CLI](/docs/cli), [Daemon](/docs/daemon), [Harnesses](/docs/harnesses), [Memory Models](/docs/memory-models)) document every command and behavior. +- Guides connect the two: one concrete goal, numbered steps, verified commands. + +## What every guide contains + +Every guide follows the same structure, so you always know what to expect: + +1. **Prerequisites** — what must already be installed or configured, with links. +2. **Numbered steps** — each step is one action with a copy-pasteable command. +3. **Expected output** — what a successful step looks like, so you can verify before moving on. +4. **Troubleshooting** — a footer covering the common ways each step fails, linking into [Troubleshooting](/docs/reference/troubleshooting). + +Commands in guides are verified against the current Coven CLI before publishing. If a guide disagrees with your installed version, run `coven doctor` and check the [changelog](/docs/reference/changelog). + +## Guide catalog + +The catalog is being built out one guide at a time, prioritized by the questions users ask most: + +| Planned guide | Question it answers | +| --- | --- | +| Install and first run | How do I go from nothing to my first supervised session? | +| Connect a harness | How do I run Codex, Claude Code, or Copilot through Coven? | +| Set up the daemon | How do I start the daemon and confirm it is healthy? | +| Set up memory | How do I enable memory and inspect what is stored? | +| Fix a failed install | My install broke — how do I diagnose and repair it? | +| Upgrade Coven | How do I upgrade safely without losing sessions? | +| Script the API | How do I call the daemon API from my own scripts? | + +## Start here today + +Until the catalog fills in, these existing pages cover the same ground: + +- [Getting started](/docs/guide/getting-started) for the guided tour of Coven. +- [Install the CLI](/docs/cli/install) for installation options and platform notes. +- [Run a harness](/docs/cli/run) for launching your first session. +- [Troubleshooting](/docs/reference/troubleshooting) when something breaks — start with `coven doctor`. + +## Related + +- [How Coven works](/docs/guide/concepts) +- [CLI reference](/docs/cli) +- [Daemon reference](/docs/daemon) diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json new file mode 100644 index 0000000..4e21f73 --- /dev/null +++ b/content/docs/guides/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Guides", + "description": "Step-by-Step How-Tos", + "root": true, + "icon": "LuCompass", + "pages": ["index"] +} diff --git a/content/docs/meta.json b/content/docs/meta.json index 4b19f89..f4f852b 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,3 +1,3 @@ { - "pages": ["guide", "cli", "coven-code", "daemon", "harnesses", "memory-models", "openapi", "reference"] + "pages": ["guide", "guides", "cli", "coven-code", "daemon", "harnesses", "memory-models", "openapi", "reference"] } diff --git a/lib/source.ts b/lib/source.ts index 8f44de0..51a11af 100644 --- a/lib/source.ts +++ b/lib/source.ts @@ -18,6 +18,7 @@ const lucideIcons = { LuTerminal: icons.Terminal, LuCable: icons.Cable, LuBrainCircuit: icons.BrainCircuit, + LuCompass: icons.Compass, }; export const source = loader({ diff --git a/package.json b/package.json index 8031974..8363087 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "scripts": { "preinstall": "npx -y only-allow pnpm", "dev": "next dev", - "build": "pnpm run check:english-only && pnpm run check:no-leading-h1 && pnpm run check:daemon-docs && pnpm run check:cli-docs && pnpm run check:coven-code-docs && pnpm run check:harness-docs && pnpm run check:memory-models-docs && pnpm run check:mermaid && pnpm run openapi:samples && next build", + "build": "pnpm run check:english-only && pnpm run check:no-leading-h1 && pnpm run check:daemon-docs && pnpm run check:cli-docs && pnpm run check:coven-code-docs && pnpm run check:harness-docs && pnpm run check:memory-models-docs && pnpm run check:guides-docs && pnpm run check:mermaid && pnpm run openapi:samples && next build", "check:fumadocs": "node scripts/check-fumadocs-platform.mjs", "check:english-only": "node scripts/check-english-only.mjs", "check:no-leading-h1": "node scripts/check-no-leading-h1.mjs", @@ -21,6 +21,7 @@ "check:harness-docs": "node scripts/check-harness-docs.mjs", "check:coven-code-docs": "node scripts/check-coven-code-docs.mjs", "check:memory-models-docs": "node scripts/check-memory-models-docs.mjs", + "check:guides-docs": "node scripts/check-guides-docs.mjs", "check:links": "node scripts/validate-links.mjs", "check:mermaid": "node scripts/check-mermaid-transform.mjs && node scripts/check-mermaid-svg-normalize.mjs && node scripts/check-mermaid-parse.mjs", "check:mermaid-parse": "node scripts/check-mermaid-parse.mjs", diff --git a/scripts/check-guides-docs.mjs b/scripts/check-guides-docs.mjs new file mode 100644 index 0000000..f19fed8 --- /dev/null +++ b/scripts/check-guides-docs.mjs @@ -0,0 +1,89 @@ +import { existsSync, readFileSync } from 'node:fs'; +import { join } from 'node:path'; + +const root = process.cwd(); +const docsRoot = join(root, 'content', 'docs'); +const guidesRoot = join(docsRoot, 'guides'); + +const requiredPages = ['index']; + +const requiredMentions = [ + 'step-by-step', + 'Prerequisites', + 'Numbered steps', + 'Expected output', + 'Troubleshooting', + 'copy-pasteable', + 'coven doctor', +]; + +function fail(message) { + console.error(`Guides docs check failed: ${message}`); + process.exit(1); +} + +function readJson(path) { + try { + return JSON.parse(readFileSync(path, 'utf8')); + } catch (error) { + fail(`could not read JSON at ${path}: ${error.message}`); + } +} + +const topLevelMeta = readJson(join(docsRoot, 'meta.json')); + +if (!Array.isArray(topLevelMeta.pages) || !topLevelMeta.pages.includes('guides')) { + fail('content/docs/meta.json must include a first-class "guides" nav section.'); +} + +const guidesMetaPath = join(guidesRoot, 'meta.json'); +if (!existsSync(guidesMetaPath)) { + fail('content/docs/guides/meta.json is missing.'); +} + +const guidesMeta = readJson(guidesMetaPath); + +if (guidesMeta.title !== 'Guides') { + fail('content/docs/guides/meta.json must use title "Guides".'); +} + +if (guidesMeta.description !== 'Step-by-Step How-Tos') { + fail('content/docs/guides/meta.json description must describe the step-by-step how-to section.'); +} + +const actualPages = Array.isArray(guidesMeta.pages) ? guidesMeta.pages : []; +const missingPages = requiredPages.filter((page) => !actualPages.includes(page)); +if (missingPages.length > 0) { + fail(`content/docs/guides/meta.json is missing pages: ${missingPages.join(', ')}.`); +} + +const sources = []; +for (const page of requiredPages) { + const file = join(guidesRoot, `${page}.mdx`); + if (!existsSync(file)) { + fail(`missing guides doc page: content/docs/guides/${page}.mdx.`); + } + + const source = readFileSync(file, 'utf8'); + sources.push(source); + + if (source.includes('Stub') || source.includes('fill in')) { + fail(`content/docs/guides/${page}.mdx still contains stub text.`); + } + + if (!source.includes('read_when:')) { + fail(`content/docs/guides/${page}.mdx is missing read_when frontmatter.`); + } +} + +const joined = sources.join('\n'); +const missingMentions = requiredMentions.filter((mention) => !joined.includes(mention)); +if (missingMentions.length > 0) { + fail(`Guides docs are missing required mentions: ${missingMentions.join(', ')}.`); +} + +if (!joined.includes('/docs/guide/getting-started') || !joined.includes('/docs/reference/troubleshooting')) { + fail('Guides docs must cross-link the getting-started guide and the troubleshooting reference.'); +} + +console.log('Guides docs check passed.');