fix(site): wire docs into Starlight with a prebuild sync script

The v0.3.0 docs site was broken — site/src/content/docs/
contained only index.mdx, so every sidebar link (why-skdd,
configuration, skill-colony, colony/discovery, integrations/*,
spec/*) rendered as Starlight's 404.

Rather than duplicate the canonical docs under site/, add a
small sync-docs.mjs that copies docs/**/*.md and colony/*.md
into site/src/content/docs/ before each astro dev/build run.
Frontmatter is injected automatically (title from first h1,
description from first blockquote), and relative .md links
are rewritten to Starlight slugs. The generated files are
gitignored so the canonical docs stay the single source of
truth.

Includes a thin wrapper page at spec/colony-v1.md that inlines
docs/spec/colony-v1.json so the sidebar link doesn't 404.

Local build: 23 pages rendered (up from 2).

Author: zakelfassi

.gitignore

@@ -14,6 +14,17 @@ build/
 *.tsbuildinfo
 .astro/
 
+# Starlight generated content (authored copies live in docs/ and colony/)
+site/src/content/docs/why-skdd.md
+site/src/content/docs/configuration.md
+site/src/content/docs/skill-colony.md
+site/src/content/docs/forging-skills.md
+site/src/content/docs/specification-alignment.md
+site/src/content/docs/schemastore-submission.md
+site/src/content/docs/colony/
+site/src/content/docs/integrations/
+site/src/content/docs/spec/
+
 # Environment & secrets
 .env
 .env.*

site/package.json

@@ -5,8 +5,11 @@
   "private": true,
   "description": "Starlight-powered documentation site for Skills-Driven Development.",
   "scripts": {
+    "sync": "node scripts/sync-docs.mjs",
+    "predev": "pnpm sync",
     "dev": "astro dev",
     "start": "astro dev",
+    "prebuild": "pnpm sync",
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro"

site/scripts/sync-docs.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Sync repo docs into Starlight's content collection.
+//
+// Starlight wants Markdown under site/src/content/docs/. Our canonical docs
+// live at docs/**/*.md and colony/**/*.md so they stay co-located with the
+// code. Rather than duplicating, this script copies the canonical files into
+// the content dir before `astro build` runs. Never edit site/src/content/docs
+// by hand (except index.mdx, which is a Starlight landing page).
+
+import { readFile, writeFile, mkdir, rm, readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const siteDir = resolve(scriptDir, "..");
+const repoRoot = resolve(siteDir, "..");
+const contentDir = resolve(siteDir, "src/content/docs");
+
+// Map: { src: path relative to repoRoot, dest: path relative to contentDir }
+// Keep paths aligned with site/astro.config.mjs sidebar entries.
+const mappings = [
+  { src: "docs/why-skdd.md", dest: "why-skdd.md" },
+  { src: "docs/configuration.md", dest: "configuration.md" },
+  { src: "docs/skill-colony.md", dest: "skill-colony.md" },
+  { src: "docs/forging-skills.md", dest: "forging-skills.md" },
+  { src: "docs/specification-alignment.md", dest: "specification-alignment.md" },
+  { src: "docs/schemastore-submission.md", dest: "schemastore-submission.md" },
+  { src: "colony/discovery.md", dest: "colony/discovery.md" },
+  { src: "colony/evolution.md", dest: "colony/evolution.md" },
+  { src: "docs/spec/agent-skills-v1.md", dest: "spec/agent-skills-v1.md" },
+  // Integrations — autogenerated by the sidebar; all markdown files that
+  // aren't README.md (Starlight wants index.md, not README.md).
+  { src: "docs/integrations/claude-code.md", dest: "integrations/claude-code.md" },
+  { src: "docs/integrations/codex.md", dest: "integrations/codex.md" },
+  { src: "docs/integrations/cursor.md", dest: "integrations/cursor.md" },
+  { src: "docs/integrations/github-copilot.md", dest: "integrations/github-copilot.md" },
+  { src: "docs/integrations/gemini-cli.md", dest: "integrations/gemini-cli.md" },
+  { src: "docs/integrations/opencode.md", dest: "integrations/opencode.md" },
+  { src: "docs/integrations/goose.md", dest: "integrations/goose.md" },
+  { src: "docs/integrations/amp.md", dest: "integrations/amp.md" },
+  { src: "docs/integrations/vscode.md", dest: "integrations/vscode.md" },
+  { src: "docs/integrations/junie.md", dest: "integrations/junie.md" },
+  { src: "docs/integrations/roo-code.md", dest: "integrations/roo-code.md" },
+];
+
+function extractTitle(body) {
+  const match = body.match(/^#\s+(.+?)\s*$/m);
+  return match ? match[1].trim() : null;
+}
+
+function extractDescription(body) {
+  const match = body.match(/^>\s+(.+?)\s*$/m);
+  if (!match) return null;
+  return match[1].replace(/\*+/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").trim();
+}
+
+function stripLeadingH1(body) {
+  return body.replace(/^#\s+.+?\s*\n+/, "");
+}
+
+function rewriteRelativeLinks(body) {
+  // Internal .md links should resolve as Starlight slugs. Drop the .md
+  // extension so Starlight's routing picks them up.
+  return body.replace(
+    /(\]\()([^)]+?)\.md(#[^)]*)?(\))/g,
+    (_, pre, path, hash = "", post) => `${pre}${path}/${hash}${post}`,
+  );
+}
+
+function ensureFrontmatter(body, fallbackTitle) {
+  if (body.startsWith("---\n")) return body;
+  const title = extractTitle(body) || fallbackTitle;
+  const description = extractDescription(body);
+  const fm = ["---", `title: ${JSON.stringify(title)}`];
+  if (description) fm.push(`description: ${JSON.stringify(description)}`);
+  fm.push("---", "");
+  return `${fm.join("\n")}\n${stripLeadingH1(body)}`;
+}
+
+async function cleanStaleGenerated() {
+  // Remove everything under contentDir *except* index.mdx so old generated
+  // files don't linger after a mapping changes.
+  const entries = await readdir(contentDir);
+  for (const entry of entries) {
+    if (entry === "index.mdx") continue;
+    await rm(join(contentDir, entry), { recursive: true, force: true });
+  }
+}
+
+async function writeColonySchemaPage() {
+  // The sidebar links /spec/colony-v1/ which isn't a markdown file —
+  // it's a JSON schema. Generate a thin wrapper page so the link works.
+  const schemaPath = resolve(repoRoot, "docs/spec/colony-v1.json");
+  const schema = await readFile(schemaPath, "utf8");
+  const body = `---
+title: "Colony v1 schema"
+description: "JSON Schema for .colony.json (the manifest every SkDD colony ships)."
+---
+
+The \`.colony.json\` file at a colony root conforms to this schema. It's the
+machine-readable entry point for marketplaces, indexers, and \`skdd doctor\`.
+
+See [\`schemastore-submission\`](../schemastore-submission/) for the draft PR
+body we'll use to register this schema with SchemaStore.org (so VS Code and
+JetBrains auto-complete it for every user).
+
+\`\`\`json
+${schema.trimEnd()}
+\`\`\`
+`;
+  const dest = resolve(contentDir, "spec/colony-v1.md");
+  await mkdir(dirname(dest), { recursive: true });
+  await writeFile(dest, body);
+}
+
+async function syncOne({ src, dest }) {
+  const srcPath = resolve(repoRoot, src);
+  const destPath = resolve(contentDir, dest);
+  let body;
+  try {
+    body = await readFile(srcPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      console.warn(`skip (missing): ${src}`);
+      return;
+    }
+    throw err;
+  }
+  const fallbackTitle = dest.replace(/\.md$/, "").replace(/\//g, " · ");
+  const rewritten = rewriteRelativeLinks(body);
+  const withFm = ensureFrontmatter(rewritten, fallbackTitle);
+  await mkdir(dirname(destPath), { recursive: true });
+  await writeFile(destPath, withFm);
+  console.log(`wrote ${relative(repoRoot, destPath)}`);
+}
+
+async function main() {
+  await cleanStaleGenerated();
+  for (const mapping of mappings) {
+    await syncOne(mapping);
+  }
+  await writeColonySchemaPage();
+  console.log(`\n✓ synced ${mappings.length + 1} pages into ${relative(repoRoot, contentDir)}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});