groundwork-method 0.0.1 → 0.10.0

package/src/generators/docs-site/files/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "<%= fileName %>",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "postinstall": "fumadocs-mdx"
+  },
+  "dependencies": {
+    "fumadocs-core": "14.7.7",
+    "fumadocs-mdx": "11.10.1",
+    "fumadocs-ui": "14.7.7",
+    "lucide-react": "^0.460.0",
+    "mermaid": "^11.4.0",
+    "next": "15.1.8",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "22.9.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.15",
+    "typescript": "5.6.3"
+  }
+}

package/src/generators/docs-site/files/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+# pnpm 10+ gates dependency build scripts by default and exits non-zero
+# (ERR_PNPM_IGNORED_BUILDS) when it skips them — which also makes `pnpm dev` and
+# `pnpm build` fail their pre-run dependency check. The skipped scripts here are
+# first-party Next.js build deps (esbuild, sharp) whose native binaries this app
+# legitimately wants, so allow dependency builds to run — the same behaviour npm
+# and yarn give by default. (These settings moved out of .npmrc in pnpm 10.)
+dangerouslyAllowAllBuilds: true

package/src/generators/docs-site/files/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/src/generators/docs-site/files/source.config.ts

@@ -0,0 +1,77 @@
+import { defineDocs, defineConfig, frontmatterSchema } from 'fumadocs-mdx/config';
+import { z } from 'zod';
+
+// GroundWork docs carry `title` + `description` frontmatter (required by the
+// groundwork-writer skill); the site renders them as the page heading and subtitle.
+// `title` is relaxed to optional only as a fallback: when a doc omits it, the schema
+// derives the title from the document's first `# H1`, so the site still serves any
+// doc (bets, hand-written pages) with a real title in the sidebar and on the page.
+//
+// Note: the schema function runs before remark, so we read the raw `source`. The
+// first `# ` line is the title; a `#` inside an opening code fence is not a case
+// GroundWork docs hit.
+export const { docs, meta } = defineDocs({
+  // Direct compile-time access to the pristine root docs directory.
+  dir: '../../docs',
+  docs: {
+    schema: (ctx) =>
+      frontmatterSchema
+        .extend({ title: z.string().optional() })
+        .transform(
+          (data): { title: string; description?: string; icon?: string; full?: boolean } => {
+            const fm = data as {
+              title?: string;
+              description?: string;
+              icon?: string;
+              full?: boolean;
+            };
+            const match = ctx.source.match(/^\s{0,3}#\s+(.+?)\s*#*\s*$/m);
+            return {
+              title: fm.title ?? (match ? match[1].trim() : 'Untitled'),
+              description: fm.description,
+              icon: fm.icon,
+              full: fm.full,
+            };
+          }
+        ),
+  },
+});
+
+// Render fenced ```mermaid blocks CLIENT-SIDE, with zero build-time dependency on a
+// headless browser. A small remark transform rewrites each `code` node with lang `mermaid`
+// into a `<Mermaid chart="…" />` MDX element (resolved from the components map in the docs
+// page); the `Mermaid` client component renders it in the browser. We deliberately avoid
+// `rehype-mermaid` — it transitively imports `mermaid-isomorphic` → `playwright`, so merely
+// importing it makes `next build`/codegen require Playwright even when no diagram renders at
+// build. The content stays plain Markdown: GitHub renders the same fenced block natively,
+// agents cold-read it, and this site renders it client-side — one source, three readers, no
+// MDX components in the content itself.
+function remarkMermaid() {
+  return (tree: { children?: unknown[] }) => {
+    const walk = (node: { children?: unknown[] }) => {
+      if (!node || !Array.isArray(node.children)) return;
+      node.children = node.children.map((child) => {
+        const c = child as { type?: string; lang?: string; value?: string };
+        if (c.type === 'code' && c.lang === 'mermaid') {
+          return {
+            type: 'mdxJsxFlowElement',
+            name: 'Mermaid',
+            attributes: [
+              { type: 'mdxJsxAttribute', name: 'chart', value: c.value ?? '' },
+            ],
+            children: [],
+          };
+        }
+        return child;
+      });
+      for (const child of node.children) walk(child as { children?: unknown[] });
+    };
+    walk(tree);
+  };
+}
+
+export default defineConfig({
+  mdxOptions: {
+    remarkPlugins: (v) => [remarkMermaid, ...v],
+  },
+});

package/src/generators/docs-site/files/tailwind.config.js

@@ -0,0 +1,10 @@
+import { createPreset } from 'fumadocs-ui/tailwind-plugin';
+
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './app/**/*.{ts,tsx}',
+    './node_modules/fumadocs-ui/dist/**/*.js',
+  ],
+  presets: [createPreset()],
+};

package/src/generators/docs-site/files/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/src/generators/docs-site/generator.ts

@@ -0,0 +1,476 @@
+import {
+  formatFiles,
+  generateFiles,
+  Tree,
+  names,
+} from '@nx/devkit';
+import * as path from 'path';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import { registerRunner, readProjectPrefix } from '../shared/scaffold-helpers';
+import {
+  BRAND_TOKENS_PATH,
+  ResolvedVisual,
+  resolveVisual,
+  validColor,
+} from '../shared/brand-tokens';
+
+export interface DocsSiteGeneratorSchema {
+  name: string;
+}
+
+/** "magpie-app" → "Magpie App". Used to title the docs nav from the workspace prefix. */
+function toTitle(s: string): string {
+  return s
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}
+
+// ---------------------------------------------------------------------------
+// Brand projection onto Fumadocs (F1, F2)
+// ---------------------------------------------------------------------------
+//
+// The scaffold runs Fumadocs UI v14 with Tailwind v3 (`createPreset()` +
+// `fumadocs-ui/style.css`). v14 themes through `--fd-*` CSS variables whose
+// values are HSL CHANNEL TRIPLETS in whitespace form (e.g.
+// `--fd-background: 0 0% 100%`) — Fumadocs consumes them internally as
+// `hsl(var(--fd-...))`. So the projection must convert the brand palette
+// (OKLCH or #rrggbb) to an `H S% L%` triplet, not emit a full colour function.
+
+/** Parse `#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa` into 0–255 RGB (alpha dropped —
+ *  Fumadocs theme channels are opaque). Returns null on anything else. */
+function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  let h = hex.trim().replace(/^#/, '');
+  if (h.length === 3 || h.length === 4) {
+    h = h.split('').slice(0, 3).map((c) => c + c).join('');
+  } else if (h.length === 8) {
+    h = h.slice(0, 6);
+  } else if (h.length !== 6) {
+    return null;
+  }
+  const n = parseInt(h, 16);
+  if (!Number.isFinite(n)) return null;
+  return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+}
+
+/** OKLCH string → 0–255 sRGB. Implements the OKLab→linear-sRGB→sRGB pipeline
+ *  (Björn Ottosson's reference matrices). Handles `oklch(L C H)` with L as a
+ *  fraction or percentage; alpha is ignored. Returns null if it cannot parse. */
+function oklchToRgb(value: string): { r: number; g: number; b: number } | null {
+  const m = value
+    .trim()
+    .match(/^oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)(?:deg)?(?:\s*\/\s*[\d.]+%?)?\s*\)$/i);
+  if (!m) return null;
+  let L = m[1].endsWith('%') ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
+  const C = parseFloat(m[2]);
+  const Hdeg = parseFloat(m[3]);
+  if (![L, C, Hdeg].every(Number.isFinite)) return null;
+  const h = (Hdeg * Math.PI) / 180;
+  const a = C * Math.cos(h);
+  const bb = C * Math.sin(h);
+
+  // OKLab → LMS (cube of the l'/m'/s' terms)
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * bb;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * bb;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * bb;
+  const l = l_ ** 3;
+  const mm = m_ ** 3;
+  const s = s_ ** 3;
+
+  // LMS → linear sRGB
+  let lr = +4.0767416621 * l - 3.3077115913 * mm + 0.2309699292 * s;
+  let lg = -1.2684380046 * l + 2.6097574011 * mm - 0.3413193965 * s;
+  let lb = -0.0041960863 * l - 0.7034186147 * mm + 1.707614701 * s;
+
+  const toSrgb = (c: number) => {
+    const x = Math.min(Math.max(c, 0), 1);
+    return x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055;
+  };
+  return {
+    r: Math.round(toSrgb(lr) * 255),
+    g: Math.round(toSrgb(lg) * 255),
+    b: Math.round(toSrgb(lb) * 255),
+  };
+}
+
+/** Any validated brand colour (hex or OKLCH) → an `H S% L%` channel triplet
+ *  for a Fumadocs `--fd-*` variable. Returns null when conversion is not
+ *  possible, so the caller keeps the stock Fumadocs default for that slot. */
+function colorToHslChannels(value: string | null): string | null {
+  if (!value) return null;
+  const rgb = value.startsWith('#') ? hexToRgb(value) : oklchToRgb(value);
+  if (!rgb) return null;
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const lum = (max + min) / 2;
+  let hue = 0;
+  let sat = 0;
+  if (max !== min) {
+    const d = max - min;
+    sat = lum > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r:
+        hue = (g - b) / d + (g < b ? 6 : 0);
+        break;
+      case g:
+        hue = (b - r) / d + 2;
+        break;
+      default:
+        hue = (r - g) / d + 4;
+    }
+    hue /= 6;
+  }
+  const H = Math.round(hue * 360);
+  const S = Math.round(sat * 100);
+  const Lp = Math.round(lum * 100);
+  return `${H} ${S}% ${Lp}%`;
+}
+
+/** Resolve a palette role's light/dark to HSL channel triplets. */
+function paletteChannels(
+  v: ResolvedVisual,
+  role: string,
+): { light: string | null; dark: string | null } {
+  // resolveVisual maps palette roles onto shadcn slots; read them back so the
+  // docs theme tracks the same projection the app uses (one brand, one palette).
+  const SLOT: Record<string, string> = {
+    surface: 'background',
+    surfaceAlt: 'secondary',
+    textBody: 'foreground',
+    primary: 'primary',
+    border: 'border',
+  };
+  const slot = SLOT[role];
+  const ld = slot ? v.shadcn[slot] : undefined;
+  return {
+    light: colorToHslChannels(ld?.light ?? null),
+    dark: colorToHslChannels(ld?.dark ?? null),
+  };
+}
+
+interface DocsBrandInputs {
+  v: ResolvedVisual;
+  displayFamily: string | null;
+  bodyFamily: string | null;
+  wordmark: string | null;
+}
+
+/** Read the brand identity bits the docs site wires beyond the palette: the
+ *  display/body font families (Google-font names) and the wordmark glyph. */
+function readDocsBrandInputs(tree: Tree, v: ResolvedVisual): DocsBrandInputs {
+  let displayFamily: string | null = null;
+  let bodyFamily: string | null = null;
+  let wordmark: string | null = null;
+  if (tree.exists(BRAND_TOKENS_PATH)) {
+    try {
+      const raw = JSON.parse(tree.read(BRAND_TOKENS_PATH, 'utf-8') || '{}');
+      const fam = (x: unknown): string | null =>
+        typeof x === 'string' && /^[\w][\w .'-]{0,48}$/.test(x.trim()) ? x.trim() : null;
+      displayFamily = fam(raw?.visual?.typography?.display?.family);
+      bodyFamily = fam(raw?.visual?.typography?.body?.family);
+      const wm = raw?.identity?.wordmark;
+      wordmark = typeof wm === 'string' && wm.trim() && wm.trim().length <= 4 ? wm.trim() : null;
+    } catch {
+      /* fall back to nulls — stock appearance */
+    }
+  }
+  return { v, displayFamily, bodyFamily, wordmark };
+}
+
+/** Render app/brand.css for the docs site: map the resolved brand palette onto
+ *  Fumadocs v14 `--fd-*` theme variables (HSL channel triplets). Only slots the
+ *  palette actually drives are overridden; every other Fumadocs default is left
+ *  untouched. The reading measure + h1–h4 scale (F2) ship separately in the
+ *  static app/docs.css so they apply even when a slot keeps its Fumadocs default. */
+function renderDocsBrandCss(inp: DocsBrandInputs): string {
+  const { v } = inp;
+  const out: string[] = [];
+  out.push('/* GENERATED by the GroundWork docs-site generator from');
+  out.push(' * .groundwork/config/brand-tokens.json — do not hand-edit this file.');
+  out.push(' * Re-run the design system to evolve the brand, then regenerate.');
+  out.push(' * Maps the brand palette onto Fumadocs v14 --fd-* theme variables');
+  out.push(' * (HSL channel triplets). The reading measure + scale live in docs.css.');
+  out.push(` * Projection source: ${v.source}. */`);
+  out.push('');
+
+  const surface = paletteChannels(v, 'surface');
+  const surfaceAlt = paletteChannels(v, 'surfaceAlt');
+  const text = paletteChannels(v, 'textBody');
+  const primary = paletteChannels(v, 'primary');
+  const border = paletteChannels(v, 'border');
+
+  // Which --fd-* slot each palette role drives. Foregrounds-on-colour
+  // (primary-foreground) keep the Fumadocs default for contrast safety.
+  const lightMap: [string, string | null][] = [
+    ['--fd-background', surface.light],
+    ['--fd-card', surface.light],
+    ['--fd-popover', surface.light],
+    ['--fd-secondary', surfaceAlt.light],
+    ['--fd-muted', surfaceAlt.light],
+    ['--fd-accent', surfaceAlt.light],
+    ['--fd-foreground', text.light],
+    ['--fd-card-foreground', text.light],
+    ['--fd-popover-foreground', text.light],
+    ['--fd-secondary-foreground', text.light],
+    ['--fd-accent-foreground', text.light],
+    ['--fd-primary', primary.light],
+    ['--fd-ring', primary.light],
+    ['--fd-border', border.light],
+  ];
+  const darkMap: [string, string | null][] = [
+    ['--fd-background', surface.dark],
+    ['--fd-card', surface.dark],
+    ['--fd-popover', surface.dark],
+    ['--fd-secondary', surfaceAlt.dark],
+    ['--fd-muted', surfaceAlt.dark],
+    ['--fd-accent', surfaceAlt.dark],
+    ['--fd-foreground', text.dark],
+    ['--fd-card-foreground', text.dark],
+    ['--fd-popover-foreground', text.dark],
+    ['--fd-secondary-foreground', text.dark],
+    ['--fd-accent-foreground', text.dark],
+    ['--fd-primary', primary.dark],
+    ['--fd-ring', primary.dark],
+    ['--fd-border', border.dark],
+  ];
+
+  const block = (selector: string, entries: [string, string | null][]) => {
+    const present = entries.filter(([, val]) => val);
+    if (present.length === 0) return;
+    out.push(`${selector} {`);
+    for (const [name, val] of present) out.push(`  ${name}: ${val};`);
+    out.push('}');
+    out.push('');
+  };
+
+  block(':root', lightMap);
+  block('.dark', darkMap);
+
+  return out.join('\n');
+}
+
+export default async function (tree: Tree, options: DocsSiteGeneratorSchema) {
+  const serviceNames = names(options.name);
+  const projectRoot = `services/${serviceNames.fileName}`;
+
+  // The docs site is a NATIVE RUNNER, not a docker-compose service. It compiles
+  // the repo-root docs/ tree at build time (source.config.ts reads ../../docs),
+  // which only resolves when Next runs from the service directory — that path is
+  // outside any per-service Docker build context, so a containerized build can
+  // never see the docs. Running it natively (`pnpm dev`) also gives live reload
+  // as the delivery loop writes docs. Fixed local port; never joins compose.
+  const assignedPort = 4000;
+
+  const prefix = readProjectPrefix(tree);
+  const navTitle = prefix && prefix !== 'workspace' ? `${toTitle(prefix)} Docs` : 'Documentation';
+  const projectName = prefix && prefix !== 'workspace' ? toTitle(prefix) : 'Project';
+
+  // Resolve the brand projection once. `source` distinguishes a real brand
+  // (visual-block / identity-only) from the unbranded fallback (default): when
+  // there is no brand-tokens.json the docs site keeps the stock Fumadocs
+  // appearance — no brand.css is emitted and layout.tsx imports nothing extra.
+  const visual = resolveVisual(tree);
+  const brand = readDocsBrandInputs(tree, visual);
+  const branded = visual.source !== 'default';
+
+  // The brand body font, when the design system named a Google font family —
+  // it sets the whole site's type. Falls back to Inter (the stock default) when
+  // absent. (A distinct display/heading font can be wired later from the same
+  // tokens; body family is the highest-leverage single choice.)
+  const bodyFont = brand.bodyFamily ?? null;
+
+  const templateOptions = {
+    ...options,
+    ...serviceNames,
+    assignedPort,
+    navTitle,
+    projectName,
+    branded,
+    bodyFont,
+    wordmark: brand.wordmark ?? '',
+    tagline: `Reference documentation for ${projectName}.`,
+    tmpl: '', // required by generateFiles
+  };
+
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'docs-site', 'files'),
+    projectRoot,
+    templateOptions
+  );
+
+  // Nx's generateFiles treats __var__ as template substitution.
+  // Rename the dynamic catch-all route directory to Next's [[...slug]].
+  const oldDir = `${projectRoot}/app/docs/__slug__`;
+  const newDir = `${projectRoot}/app/docs/[[...slug]]`;
+  for (const child of tree.children(oldDir)) {
+    const content = tree.read(`${oldDir}/${child}`);
+    if (content) {
+      tree.write(`${newDir}/${child}`, content);
+      tree.delete(`${oldDir}/${child}`);
+    }
+  }
+
+  // Brand the docs site (WS-F). Project the brand palette onto Fumadocs --fd-*
+  // theme variables (app/brand.css); the reading measure + h1–h4 scale ship in
+  // the static app/docs.css. app/layout.tsx imports both. Unbranded projects
+  // (no brand-tokens.json) skip this entirely and keep today's stock Fumadocs
+  // appearance — brand.css is not written and docs.css is dropped.
+  if (branded) {
+    tree.write(`${projectRoot}/app/brand.css`, renderDocsBrandCss(brand));
+  } else {
+    // Unbranded fallback: no brand.css, and the typography sheet is dropped so
+    // the emitted tree is the stock Fumadocs starter (layout.tsx imports neither).
+    tree.delete(`${projectRoot}/app/docs.css`);
+  }
+
+  // Seed the sidebar ordering as declarative Fumadocs meta.json (WS-G / E1).
+  // This lands in the project's content tree (Tier-2 content seeded into docs/),
+  // ordering the canonical doc set and collapsing the large principles tree so
+  // it no longer dominates the rail. Retires the betsFirst() JS hack. Only seed
+  // it once — never clobber a meta.json the project has since hand-tuned.
+  seedDocsMeta(tree);
+
+  // Register with `./dev` as a native runner so start/stop/status/logs manage it
+  // like any other surface (electron/flutter/cli do the same). Not autostarted —
+  // a docs site is a developer affordance, not part of the boot topology; it is
+  // launched on demand (`pnpm dev` in the service dir, or via the runner).
+  registerRunner(tree, {
+    name: serviceNames.fileName,
+    kind: 'surface',
+    cmd: 'pnpm dev',
+    cwd: projectRoot,
+    env: { PORT: String(assignedPort) },
+    autostart: false,
+  });
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'docs-site', options as unknown as Record<string, unknown>);
+
+  return () => {
+    const { execSync } = require('child_process');
+    const fs = require('fs');
+    try {
+      execSync('pnpm install', { cwd: projectRoot, stdio: 'inherit' });
+    } catch (e) {
+      // pnpm 10+ exits non-zero on ERR_PNPM_IGNORED_BUILDS — the build scripts of
+      // gated dependencies (esbuild/sharp) are skipped by default — even when the
+      // install itself succeeded. Treat a populated node_modules as success (pnpm
+      // already printed its own approve-builds notice); only warn if deps are
+      // genuinely missing, so we never report a false failure over a good install.
+      if (!fs.existsSync(path.join(projectRoot, 'node_modules'))) {
+        console.warn(`Failed to run pnpm install in ${projectRoot}. Run it manually.`);
+      }
+    }
+  };
+}
+
+/** The canonical top-level doc order for the sidebar (E1). The rail reads as a
+ *  product-learning journey: the brief (what the system is) → the design system
+ *  (how it looks and behaves) → the nested architecture section (how it is
+ *  built) → ways of working → getting started (how to run it) → bets (delivery
+ *  work). `...` keeps any doc/folder not named here in its natural position
+ *  after the named set, and `principles` is pushed last and collapsed so its
+ *  large tree never dominates the rail. Lands at docs/meta.json — Fumadocs
+ *  sidebar config, ignored by GitHub and agents, so the docs/ tree stays
+ *  effectively content-pristine. */
+function seedDocsMeta(tree: Tree): void {
+  const metaPath = 'docs/meta.json';
+  if (tree.exists(metaPath)) return; // never clobber a project-tuned ordering
+  // Fumadocs reads `pages` as the sidebar order. Explicit names come first in
+  // the listed order; `...` expands to every remaining page/folder not named;
+  // `principles` is named LAST (after `...`) so the large principles tree sinks
+  // to the bottom of the rail instead of leading it. `architecture` and
+  // `getting-started` are folders here — their own meta.json (below) orders
+  // their children.
+  const meta = {
+    pages: [
+      'product-brief',
+      'design-system',
+      'architecture',
+      'ways-of-working',
+      'getting-started',
+      'bets',
+      '...',
+      'principles',
+    ],
+  };
+  tree.write(metaPath, JSON.stringify(meta, null, 2) + '\n');
+
+  // Order the nested architecture section: the overview (index, was the flat
+  // architecture.md) first, then infrastructure → domain → services → api →
+  // decisions, with `...` catching anything else. Seeded only when the folder
+  // exists and lacks its own meta — never write a meta.json into an empty folder
+  // (Fumadocs renders a content-less folder as a broken nav node and the build
+  // trips over it), and never clobber a project's own grouping. The architecture
+  // skill seeds this when it first creates the folder, so a fresh scaffold gets
+  // the order; this backfills it on regeneration over an older project.
+  const architectureMeta = 'docs/architecture/meta.json';
+  if (tree.exists('docs/architecture') && !tree.exists(architectureMeta)) {
+    tree.write(
+      architectureMeta,
+      JSON.stringify(
+        {
+          pages: [
+            'index',
+            'infrastructure',
+            'domain',
+            'services',
+            'api',
+            'decisions',
+            '...',
+          ],
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+  }
+
+  // Order the getting-started on-ramp: the overview (index) first, then the
+  // setup walkthrough and the ./dev command reference. Same folder-must-exist
+  // guard as architecture above.
+  const gettingStartedMeta = 'docs/getting-started/meta.json';
+  if (tree.exists('docs/getting-started') && !tree.exists(gettingStartedMeta)) {
+    tree.write(
+      gettingStartedMeta,
+      JSON.stringify(
+        { pages: ['index', 'setup', 'dev-cli-reference', '...'] },
+        null,
+        2,
+      ) + '\n',
+    );
+  }
+
+  // Order the principles subtree last + collapsed via its own meta.json. Seeded
+  // only if absent so a project's own grouping is preserved.
+  const principlesMeta = 'docs/principles/meta.json';
+  if (!tree.exists(principlesMeta) && tree.exists('docs/principles')) {
+    tree.write(
+      principlesMeta,
+      JSON.stringify({ defaultOpen: false, pages: ['...'] }, null, 2) + '\n',
+    );
+  }
+
+  // Within the Bets section, sink the `_archive` folder (delivered bets) to the
+  // bottom of the rail so active, in-flight bets read first. `...` expands to
+  // every active bet (sorted), then `_archive` is named LAST. The archive folder
+  // itself is COLLAPSED via its own docs/bets/_archive/meta.json (defaultOpen:
+  // false), written by the dev CLI's `archive` command at delivery time — not
+  // here. (Fumadocs has no leading-underscore hide convention, so `_archive`
+  // stays visible-but-closed, which is the desired collapse.) The scaffold seeds
+  // no docs/bets/ (bets are authored during the lifecycle), so this is normally a
+  // no-op at scaffold time; guarded by tree.exists so it only lands when the bets
+  // tree is present, and never clobbers a project-tuned ordering.
+  const betsMeta = 'docs/bets/meta.json';
+  if (!tree.exists(betsMeta) && tree.exists('docs/bets')) {
+    tree.write(
+      betsMeta,
+      JSON.stringify({ pages: ['...', '_archive'] }, null, 2) + '\n',
+    );
+  }
+}

package/src/generators/docs-site/schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "id": "DocsSiteGenerator",
+  "title": "Docs Site Generator",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the service (e.g. docs)",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      }
+    }
+  },
+  "required": ["name"]
+}