@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.80.0",
+  "version": "5.0.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",
@@ -14,8 +14,7 @@
   "types": "./dist/index.d.ts",
   "bin": {
     "smartstack": "./dist/index.js",
-    "ss": "./dist/index.js",
-    "smartstack-mcp": "./dist/mcp-entry.mjs"
+    "ss": "./dist/index.js"
   },
   "files": [
     "dist",
@@ -54,36 +53,25 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js || exit 0",
     "dev": "tsup --watch",
-    "build:html": "node templates/skills/business-analyse-html/html/build-html.js",
-    "build": "npm run build:html && npx tsup",
+    "build": "npx tsup",
     "lint": "eslint src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\"",
     "prepublishOnly": "npm run build",
     "test": "node --test",
+    "test:cli": "vitest run src",
     "link": "npm run build && npm link",
     "install:local": "npm run build && node dist/index.js install --local --force",
     "install:global": "npm run build && node dist/index.js install --force",
     "status:local": "node dist/index.js status --local --verbose",
     "status:global": "node dist/index.js status --verbose",
     "doctor": "node dist/index.js doctor",
-    "check-mcp": "node dist/index.js check-mcp",
     "ralph:start": "node dist/index.js ralph start",
     "ralph:status": "node dist/index.js ralph status",
     "ralph:logs": "node dist/index.js ralph logs",
-    "health": "node dist/index.js doctor --json",
-    "test:mcp": "vitest run --config vitest.mcp.config.ts",
-    "test:mcp:watch": "vitest --config vitest.mcp.config.ts",
-    "test:mcp:coverage": "vitest run --config vitest.mcp.config.ts --coverage",
-    "test:ba": "vitest run --config vitest.ba.config.ts",
-    "test:ba:watch": "vitest --config vitest.ba.config.ts",
-    "test:ba:coverage": "vitest run --config vitest.ba.config.ts --coverage",
-    "test:all": "npm run test:mcp && npm run test:ba"
+    "health": "node dist/index.js doctor --json"
   },
   "dependencies": {
-    "@atlashub/smartstack-cli": "file:",
-    "@modelcontextprotocol/sdk": "^1.0.0",
     "axios": "^1.7.0",
-    "bcryptjs": "^2.4.3",
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.3",
     "commander": "^12.0.0",
@@ -92,16 +80,13 @@
     "handlebars": "^4.7.8",
     "inquirer": "^9.2.12",
     "jsonwebtoken": "^9.0.3",
-    "mssql": "^11.0.1",
     "ora": "^8.0.1",
     "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@types/bcryptjs": "^2.4.6",
     "@types/fs-extra": "^11.0.4",
     "@types/inquirer": "^9.0.7",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/mssql": "^9.1.5",
     "@types/node": "^20.10.6",
     "@typescript-eslint/eslint-plugin": "^6.18.0",
     "@typescript-eslint/parser": "^6.18.0",

package/scripts/generate-docs/README.md

@@ -0,0 +1,87 @@
+# SmartStack CLI Documentation Generator
+
+Generates the static HTML documentation served by `ss docs` from:
+
+- **Skill metadata** — every `templates/skills/**/SKILL.md` YAML frontmatter
+  (`name`, `description`, `argument-hint`, `allowed-tools`, `phase`, …)
+- **Page narrative** — `docs-src/*.md` with frontmatter for slug, title, icon,
+  breadcrumb and chosen page template
+- **Sidebar layout** — `docs-src/_data/sidebar.json`
+- **Package version** — `package.json:version` (auto-injected as the badge)
+
+Output: `.documentation/*.html` (13 pages), committed to git so the npm package
+ships ready-to-view documentation.
+
+## Commands
+
+```bash
+npm run build:docs          # one-shot regeneration
+npm run build:docs:watch    # rebuild on change (chokidar)
+npm run docs:check          # exit 1 on drift (CI gate)
+npm run docs:dev            # build + serve at http://localhost:8080
+```
+
+The `prebuild` npm hook automatically runs `build:docs` before `npm run build`,
+and `prepublishOnly` chains `docs:check && build` so a stale tree cannot ship.
+
+## Architecture
+
+```
+scripts/generate-docs/
+├── index.ts                # orchestrator
+├── lib/
+│   ├── skill-parser.ts     # walks templates/skills/**/SKILL.md
+│   ├── markdown-parser.ts  # gray-matter + marked on docs-src/*.md
+│   ├── sidebar-builder.ts  # loads + validates docs-src/_data/sidebar.json
+│   ├── context-builder.ts  # per-page Handlebars context
+│   ├── handlebars-setup.ts # helpers + partial registration
+│   ├── stats.ts            # counts skills/agents/hooks/cli commands
+│   └── version.ts          # reads package.json
+├── templates/
+│   ├── layout.hbs          # outer HTML shell
+│   ├── partials/           # header, sidebar, skill-card, ...
+│   └── pages/              # one .hbs per logical page kind
+└── README.md               # this file
+```
+
+The generator NEVER touches `.documentation/css/styles.css` or
+`.documentation/js/app.js` — those are hand-maintained shells.
+
+## How do I…
+
+### Add a new page
+
+1. Create `docs-src/<slug>.md` with frontmatter (see existing pages).
+2. Either reuse `pages/_generic.hbs` (set `page: _generic`) or add a custom
+   template under `templates/pages/<slug>.hbs`.
+3. Add an entry to `docs-src/_data/sidebar.json` (validation enforces this).
+4. Run `npm run build:docs` and commit the new `.documentation/<slug>.html`.
+
+### Rename a skill
+
+1. Update the skill's `SKILL.md` frontmatter (`name:`) and rename the folder
+   under `templates/skills/`.
+2. The installer's deploy rule (`src/lib/installer.ts:remapSkillPath`) and the
+   doc generator's identical mirror (`templates/skills/lib/skill-slug.ts`)
+   both pick up the new slug — no other change needed.
+3. `npm run build:docs` regenerates every page that lists the skill (commands,
+   business-analyse, ba-develop, etc.).
+
+### Add a new sidebar section
+
+Edit `docs-src/_data/sidebar.json` → `sections[]`. Each item references a page
+slug; missing slugs fail the build (see `sidebar-builder.ts:validateSidebar`).
+
+### Debug a render
+
+`{{json someValue}}` Handlebars helper dumps any context value. Useful when
+extending partials. Remove before committing.
+
+## Anti-patterns
+
+- ❌ **Do not edit `.documentation/*.html` directly.** They carry an
+  `AUTO-GENERATED` header comment; CI rejects hand-edits via `docs:check`.
+- ❌ **Do not duplicate skill descriptions** in `docs-src/*.md`. The whole point
+  is that the YAML frontmatter is the single source of truth.
+- ❌ **Do not bake the version number** into any markdown — it is injected at
+  build time from `package.json`.

package/scripts/generate-docs/index.ts

@@ -0,0 +1,175 @@
+/**
+ * scripts/generate-docs/index.ts
+ *
+ * Entry point of the SmartStack CLI documentation generator.
+ * Reads `templates/skills/<...>/SKILL.md` + `docs-src/*.md`, renders the
+ * Handlebars page templates, and writes everything to `.documentation/`.
+ *
+ * Modes:
+ *   npx tsx scripts/generate-docs/index.ts            # build
+ *   npx tsx scripts/generate-docs/index.ts --check    # exit 1 on drift
+ *   npx tsx scripts/generate-docs/index.ts --watch    # rebuild on change
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+import { parseAllSkills } from './lib/skill-parser';
+import { parseAllPages, type PageMeta } from './lib/markdown-parser';
+import { validateSidebar, buildSidebarForPage } from './lib/sidebar-builder';
+import { collectStats } from './lib/stats';
+import { buildContext } from './lib/context-builder';
+import { loadLayoutTemplate, loadPageTemplate } from './lib/handlebars-setup';
+
+const REPO_ROOT = join(__dirname, '..', '..');
+const DOCS_OUT = join(REPO_ROOT, '.documentation');
+
+interface CliFlags {
+  check: boolean;
+  watch: boolean;
+  verbose: boolean;
+}
+
+function parseFlags(argv: string[]): CliFlags {
+  return {
+    check: argv.includes('--check'),
+    watch: argv.includes('--watch'),
+    verbose: argv.includes('--verbose') || argv.includes('-v'),
+  };
+}
+
+/**
+ * Render one page to its final HTML string. The page template renders the
+ * "body" — i.e. main content of the page — and the layout wraps it in the
+ * shared HTML chrome (head, header, sidebar, footer).
+ */
+function renderPage(page: PageMeta, allSkills: ReturnType<typeof parseAllSkills>, stats: ReturnType<typeof collectStats>): string {
+  const sidebar = buildSidebarForPage(page.slug);
+  const ctx = buildContext(page, sidebar, allSkills, stats);
+
+  // 1. Render the page template (often just `{{{bodyHtml}}}` plus auto-injected
+  //    skill grids); the result is the inner content placed in the layout's
+  //    {{{bodyHtml}}} slot.
+  const pageTpl = loadPageTemplate(page.pageTemplate);
+  const innerHtml = pageTpl(ctx);
+
+  // 2. Render the outer layout with the inner content as its body.
+  const layoutTpl = loadLayoutTemplate();
+  const html = layoutTpl({ ...ctx, bodyHtml: innerHtml });
+
+  // 3. Normalise line endings — committed files use LF (see .gitattributes).
+  return html.replace(/\r\n/g, '\n');
+}
+
+interface RenderResult {
+  generated: Map<string, string>;
+  duration: number;
+}
+
+function build(): RenderResult {
+  const t0 = performance.now();
+  const skills = parseAllSkills();
+  const pages = parseAllPages();
+  validateSidebar(pages.map((p) => p.slug));
+  const stats = collectStats();
+
+  const generated = new Map<string, string>();
+  for (const page of pages) {
+    generated.set(page.slug, renderPage(page, skills, stats));
+  }
+  return { generated, duration: performance.now() - t0 };
+}
+
+function writeAll(generated: Map<string, string>): void {
+  if (!existsSync(DOCS_OUT)) mkdirSync(DOCS_OUT, { recursive: true });
+  for (const [slug, html] of generated) {
+    writeFileSync(join(DOCS_OUT, `${slug}.html`), html, 'utf-8');
+  }
+}
+
+function checkDrift(generated: Map<string, string>): number {
+  let drift = 0;
+  for (const [slug, expected] of generated) {
+    const file = join(DOCS_OUT, `${slug}.html`);
+    const actual = existsSync(file) ? readFileSync(file, 'utf-8').replace(/\r\n/g, '\n') : '';
+    if (actual !== expected) {
+      drift++;
+      // eslint-disable-next-line no-console
+      console.error(`DRIFT: .documentation/${slug}.html differs from generator output`);
+      if (process.env.DOCS_CHECK_DIFF === '1') {
+        // Minimal first-divergence diff — full diff via the `diff` package on demand
+        const minLen = Math.min(actual.length, expected.length);
+        let i = 0;
+        while (i < minLen && actual[i] === expected[i]) i++;
+        const ctx = (s: string) => s.slice(Math.max(0, i - 40), i + 80);
+        // eslint-disable-next-line no-console
+        console.error(`  first diff at offset ${i}:`);
+        // eslint-disable-next-line no-console
+        console.error(`    actual:   ...${JSON.stringify(ctx(actual))}...`);
+        // eslint-disable-next-line no-console
+        console.error(`    expected: ...${JSON.stringify(ctx(expected))}...`);
+      }
+    }
+  }
+  return drift;
+}
+
+async function main(): Promise<number> {
+  const flags = parseFlags(process.argv.slice(2));
+
+  const { generated, duration } = build();
+  const count = generated.size;
+
+  if (flags.check) {
+    const drift = checkDrift(generated);
+    if (drift > 0) {
+      // eslint-disable-next-line no-console
+      console.error(`\n${drift} file(s) out of sync. Run \`npm run build:docs\` to regenerate.`);
+      return 1;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`docs in sync (${count} pages, ${duration.toFixed(0)}ms)`);
+    return 0;
+  }
+
+  writeAll(generated);
+  // eslint-disable-next-line no-console
+  console.log(`Generated ${count} pages in ${duration.toFixed(0)}ms → .documentation/`);
+
+  if (flags.watch) {
+    const { watch } = await import('chokidar');
+    const watcher = watch(
+      [
+        join(REPO_ROOT, 'docs-src', '**', '*'),
+        join(REPO_ROOT, 'templates', 'skills', '**', 'SKILL.md'),
+        join(__dirname, 'templates', '**', '*'),
+      ],
+      { ignoreInitial: true }
+    );
+    watcher.on('all', (event, path) => {
+      try {
+        // eslint-disable-next-line no-console
+        console.log(`[${event}] ${path} → rebuild`);
+        const { generated: g } = build();
+        writeAll(g);
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error('build failed:', err);
+      }
+    });
+    // eslint-disable-next-line no-console
+    console.log('watching for changes (Ctrl+C to stop)…');
+    return new Promise<number>(() => undefined); // never resolves
+  }
+
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    // eslint-disable-next-line no-console
+    console.error(err);
+    process.exit(2);
+  }
+);

package/scripts/generate-docs/lib/context-builder.ts

@@ -0,0 +1,81 @@
+/**
+ * scripts/generate-docs/lib/context-builder.ts
+ *
+ * For every parsed page, compose the full Handlebars render context. This is
+ * the only place that knows what each page needs (e.g. `ba-develop` page gets
+ * only the BA + dev skills, not the whole 84-skill catalogue).
+ */
+import { VERSION } from './version';
+import { collectStats, type Stats } from './stats';
+import type { Skill } from './skill-parser';
+import type { PageMeta } from './markdown-parser';
+import type { Sidebar } from './sidebar-builder';
+
+export interface RenderContext {
+  version: string;
+  page: PageMeta;
+  sidebar: Sidebar;
+  stats: Stats;
+  /** All 84 skills, sorted by slug — available to every page */
+  skills: Skill[];
+  /** The subset of skills relevant to the current page (filtered by phase) */
+  skillsForPage: Skill[];
+  /** The body markdown rendered to HTML (passed through {{{bodyHtml}}}) */
+  bodyHtml: string;
+}
+
+/**
+ * Returns the subset of skills a given page is interested in showing as cards.
+ * Pages not in this map get an empty array (the page template can still loop
+ * over `skills` directly if it wants the full catalogue).
+ */
+function filterSkillsForPage(slug: string, all: Skill[]): Skill[] {
+  switch (slug) {
+    case 'commands':
+      return all;
+    case 'business-analyse':
+      return [];
+    case 'ba-skills':
+      return all.filter((s) => s.phase === 'business-analyse');
+    case 'ba-develop':
+      return all.filter(
+        (s) =>
+          s.slug === 'ba-develop' ||
+          s.slug === 'ba-develop-plan' ||
+          s.slug === 'ba-create-plan-development' ||
+          s.phase.startsWith('development/') ||
+          s.phase === 'devCore' ||
+          s.phase === 'devDomain' ||
+          s.phase === 'devData' ||
+          s.phase === 'devApi' ||
+          s.phase === 'devFrontend'
+      );
+    case 'gitflow':
+      return all.filter((s) => s.slug === 'gitflow');
+    case 'efcore':
+      return all.filter((s) => s.slug === 'efcore');
+    case 'ralph-loop':
+      return [];
+    default:
+      return [];
+  }
+}
+
+export function buildContext(
+  page: PageMeta,
+  sidebar: Sidebar,
+  allSkills: Skill[],
+  stats: Stats
+): RenderContext {
+  return {
+    version: VERSION,
+    page,
+    sidebar,
+    stats,
+    skills: allSkills,
+    skillsForPage: filterSkillsForPage(page.slug, allSkills),
+    bodyHtml: page.bodyHtml,
+  };
+}
+
+export { collectStats };

package/scripts/generate-docs/lib/handlebars-setup.ts

@@ -0,0 +1,162 @@
+/**
+ * scripts/generate-docs/lib/handlebars-setup.ts
+ *
+ * Registers every partial under `templates/partials/` and every helper the
+ * page templates need. Single entry point: `getHandlebars()`.
+ */
+import Handlebars from 'handlebars';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import type { Skill } from './skill-parser';
+import type { LocalisedString } from './markdown-parser';
+
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+const PARTIALS_DIR = join(TEMPLATES_DIR, 'partials');
+
+let prepared = false;
+
+function isLocalised(value: unknown): value is { fr: string; en: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'fr' in value &&
+    'en' in value
+  );
+}
+
+function localisedValue(value: LocalisedString | undefined, lang: 'fr' | 'en'): string {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  return value[lang] ?? value.fr ?? '';
+}
+
+function registerHelpers(): void {
+  Handlebars.registerHelper('eq', (a: unknown, b: unknown) => a === b);
+
+  Handlebars.registerHelper('i18n', (value: LocalisedString | undefined, lang: 'fr' | 'en') =>
+    localisedValue(value, lang ?? 'fr')
+  );
+
+  // Emit either a plain text node (if value is a string) or two
+  // `<span data-lang>` nodes (if value is a localised object). An optional
+  // second argument is a CSS class added to every emitted <span>.
+  //
+  // Generated DOM examples:
+  //   - value = "Hello", extraClass omitted  → `Hello`
+  //   - value = "Hello", extraClass = "x"    → `<span class="x">Hello</span>`
+  //   - value = {fr, en}, extraClass omitted → `<span data-lang="fr">…</span><span data-lang="en">…</span>`
+  //   - value = {fr, en}, extraClass = "x"   → `<span class="x" data-lang="fr">…</span><span class="x" data-lang="en">…</span>`
+  //
+  // The `app.js` runtime hides the inactive language by toggling
+  // `[data-lang="<inactive>"] { display: none }`. Both spans must therefore
+  // remain valid HTML attributes — earlier implementations used `replace()`
+  // on the class string and produced broken `<span class= data-lang="fr"x">`
+  // markup that the browser rendered as two visible items side by side.
+  Handlebars.registerHelper(
+    'i18nSpans',
+    function (value: LocalisedString | undefined, extraClass?: unknown) {
+      const klass = typeof extraClass === 'string' ? extraClass.trim() : '';
+      const classAttr = klass ? ` class="${klass}"` : '';
+
+      if (value == null) return new Handlebars.SafeString('');
+
+      if (typeof value === 'string') {
+        const text = Handlebars.escapeExpression(value);
+        return new Handlebars.SafeString(
+          klass ? `<span${classAttr}>${text}</span>` : text
+        );
+      }
+
+      if (isLocalised(value)) {
+        const fr = Handlebars.escapeExpression(value.fr);
+        const en = Handlebars.escapeExpression(value.en);
+        return new Handlebars.SafeString(
+          `<span${classAttr} data-lang="fr">${fr}</span><span${classAttr} data-lang="en">${en}</span>`
+        );
+      }
+
+      return new Handlebars.SafeString(Handlebars.escapeExpression(String(value)));
+    }
+  );
+
+  Handlebars.registerHelper('firstSentence', (text: string) => {
+    if (!text) return '';
+    const m = text.match(/^(.*?[.!?])\s/);
+    return m ? m[1] : text.length > 160 ? text.slice(0, 157) + '…' : text;
+  });
+
+  Handlebars.registerHelper('slugify', (text: string) =>
+    String(text ?? '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/(^-|-$)/g, '')
+  );
+
+  Handlebars.registerHelper('count', (arr: unknown) =>
+    Array.isArray(arr) ? arr.length : 0
+  );
+
+  // Group an array of skills by their `phase` field and yield each group as
+  // an object the template can iterate over predictably.
+  Handlebars.registerHelper('groupSkillsByPhase', function (skills: Skill[], options: Handlebars.HelperOptions) {
+    if (!Array.isArray(skills)) return '';
+    const groups = new Map<string, Skill[]>();
+    for (const s of skills) {
+      const arr = groups.get(s.phase) ?? [];
+      arr.push(s);
+      groups.set(s.phase, arr);
+    }
+    const sorted = Array.from(groups.entries()).sort(([a], [b]) => a.localeCompare(b));
+    let out = '';
+    for (const [phase, list] of sorted) {
+      out += options.fn({ phase, skills: list });
+    }
+    return out;
+  });
+
+  // Stringify for debugging — `{{json someValue}}`
+  Handlebars.registerHelper('json', (value: unknown) =>
+    new Handlebars.SafeString(JSON.stringify(value, null, 2))
+  );
+}
+
+function registerPartials(): void {
+  const entries = readdirSync(PARTIALS_DIR);
+  for (const file of entries) {
+    if (!file.endsWith('.hbs')) continue;
+    const name = basename(file, '.hbs');
+    const src = readFileSync(join(PARTIALS_DIR, file), 'utf-8');
+    Handlebars.registerPartial(name, src);
+  }
+}
+
+export function getHandlebars(): typeof Handlebars {
+  if (!prepared) {
+    registerHelpers();
+    registerPartials();
+    prepared = true;
+  }
+  return Handlebars;
+}
+
+/** Compile and cache a single page template by name (no `.hbs` extension). */
+const pageCache = new Map<string, HandlebarsTemplateDelegate>();
+export function loadPageTemplate(name: string): HandlebarsTemplateDelegate {
+  let cached = pageCache.get(name);
+  if (cached) return cached;
+  const file = join(TEMPLATES_DIR, 'pages', `${name}.hbs`);
+  const src = readFileSync(file, 'utf-8');
+  cached = getHandlebars().compile(src, { noEscape: false });
+  pageCache.set(name, cached);
+  return cached;
+}
+
+/** Compile the outer layout once and cache it. */
+let layoutCache: HandlebarsTemplateDelegate | null = null;
+export function loadLayoutTemplate(): HandlebarsTemplateDelegate {
+  if (layoutCache) return layoutCache;
+  const file = join(TEMPLATES_DIR, 'layout.hbs');
+  const src = readFileSync(file, 'utf-8');
+  layoutCache = getHandlebars().compile(src, { noEscape: false });
+  return layoutCache;
+}

package/scripts/generate-docs/lib/markdown-parser.ts

@@ -0,0 +1,86 @@
+/**
+ * scripts/generate-docs/lib/markdown-parser.ts
+ *
+ * Reads `docs-src/*.md`, splits frontmatter (gray-matter) from body, and
+ * converts the body to HTML (marked). Returns `PageMeta[]` ready for the
+ * context builder.
+ *
+ * Frontmatter shape (per page):
+ *   slug: string                  # output filename (slug.html)
+ *   title: string | { fr, en }    # full page title (used in <title> + header)
+ *   pageTitle: string | { fr, en }# short title shown in the header bar
+ *   icon: string                  # emoji or short string
+ *   page: string                  # `pages/<x>.hbs` template name (default: slug)
+ *   breadcrumb: Array<string | { fr, en }>  # optional crumb trail
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import matter from 'gray-matter';
+import { marked } from 'marked';
+
+const DOCS_SRC = join(__dirname, '..', '..', '..', 'docs-src');
+
+export type LocalisedString = string | { fr: string; en: string };
+
+export interface PageMeta {
+  /** Filename slug (without extension): `installation`, `ba-develop`, … */
+  slug: string;
+  /** Full HTML <title> + sidebar tooltip */
+  title: LocalisedString;
+  /** Short label rendered in the header bar */
+  pageTitle: LocalisedString;
+  /** Emoji or short string */
+  icon: string;
+  /** Handlebars template file (without `.hbs`) — defaults to slug */
+  pageTemplate: string;
+  /** Optional breadcrumb segments, leftmost first */
+  breadcrumb: LocalisedString[];
+  /** Pre-rendered HTML from the markdown body */
+  bodyHtml: string;
+  /** Absolute path of the source markdown file */
+  sourcePath: string;
+}
+
+function configureMarked(): void {
+  marked.setOptions({
+    gfm: true,
+    breaks: false,
+  });
+}
+configureMarked();
+
+export function parsePageFile(absPath: string): PageMeta {
+  const raw = readFileSync(absPath, 'utf-8');
+  const { data, content } = matter(raw);
+  const slug = (data.slug as string) || basename(absPath, '.md');
+
+  const bodyHtml = String(marked.parse(content));
+
+  return {
+    slug,
+    title: (data.title as LocalisedString) || slug,
+    pageTitle: (data.pageTitle as LocalisedString) || (data.title as LocalisedString) || slug,
+    icon: (data.icon as string) || '📄',
+    pageTemplate: (data.page as string) || slug,
+    breadcrumb: (data.breadcrumb as LocalisedString[]) || [],
+    bodyHtml,
+    sourcePath: absPath,
+  };
+}
+
+/**
+ * Walks `docs-src/*.md` (excluding `_data/` and `_partials/`), parses each,
+ * and returns them sorted by slug.
+ */
+export function parseAllPages(): PageMeta[] {
+  const entries = readdirSync(DOCS_SRC, { withFileTypes: true });
+  const pages: PageMeta[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name.startsWith('_')) continue;
+    pages.push(parsePageFile(join(DOCS_SRC, entry.name)));
+  }
+  pages.sort((a, b) => a.slug.localeCompare(b.slug));
+  return pages;
+}