docs: scaffold Guides section — step-by-step how-to catalog

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)

content/docs/guides/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Guides",
+  "description": "Step-by-Step How-Tos",
+  "root": true,
+  "icon": "LuCompass",
+  "pages": ["index"]
+}

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"]
 }

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({

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",

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.');