living-docs-kit 0.1.0

package/skills/docs-init/assets/site-template/engine/build.mjs

@@ -0,0 +1,432 @@
+// Builds content/**/*.md into a static site in dist/.
+// Usage: node engine/build.mjs [--hosted] [--out dist]
+//   --hosted  code links point to codeLinks.webBase instead of local editor paths
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { Marked } from 'marked';
+import {
+  SITE_DIR, CONTENT_DIR, loadConfig, loadPages, loadThemes, resolveTheme, themeToCss, relHref, rootPrefix,
+  codeUrls, freshness, git, slugify, escapeHtml, walk, parentOf,
+} from './lib.mjs';
+import { strings } from './i18n.mjs';
+
+const CALLOUTS = ['NOTE', 'TIP', 'WARNING', 'EDGE', 'RISK', 'UNVERIFIED', 'DECISION'];
+
+export async function build({ outDir = path.join(SITE_DIR, 'dist'), hosted = false, dev = false, quiet = false } = {}) {
+  const t0 = Date.now();
+  const cfg = loadConfig();
+  const S = strings(cfg.uiLanguage);
+  const themes = loadThemes();
+  if (!themes.length) throw new Error('No theme found in themes/. Use the docs-design skill to create one.');
+  if (!themes.some((t) => t.id === cfg.defaultTheme)) {
+    console.warn(`! defaultTheme "${cfg.defaultTheme}" does not exist; using "${themes[0].id}".`);
+    cfg.defaultTheme = themes[0].id;
+  }
+
+  let pages = loadPages();
+  pages = addMissingSections(pages);
+  const byUrl = new Map(pages.map((p) => [p.url, p]));
+  const tree = buildTree(pages);
+  const head = git(cfg, ['rev-parse', '--short', 'HEAD']);
+  const builtAt = new Date();
+  const warnings = [];
+
+  for (const p of pages) p.fresh = freshness(cfg, p);
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(path.join(outDir, 'assets'), { recursive: true });
+
+  // assets
+  for (const f of fs.readdirSync(path.join(SITE_DIR, 'engine', 'assets'))) {
+    fs.copyFileSync(path.join(SITE_DIR, 'engine', 'assets', f), path.join(outDir, 'assets', f));
+  }
+  const mermaidSrc = path.join(SITE_DIR, 'engine', 'vendor', 'mermaid.min.js');
+  const hasMermaid = fs.existsSync(mermaidSrc);
+  if (hasMermaid) fs.copyFileSync(mermaidSrc, path.join(outDir, 'assets', 'mermaid.min.js'));
+  fs.writeFileSync(path.join(outDir, 'assets', 'themes.css'), themes.map(themeToCss).join('\n'));
+
+  // non-markdown files inside content/ (images, attachments)
+  for (const f of walk(CONTENT_DIR, (x) => !x.toLowerCase().endsWith('.md'))) {
+    const rel = path.relative(CONTENT_DIR, f);
+    fs.mkdirSync(path.dirname(path.join(outDir, rel)), { recursive: true });
+    fs.copyFileSync(f, path.join(outDir, rel));
+  }
+
+  const clientCfg = {
+    id: cfg.id,
+    defaultTheme: cfg.defaultTheme,
+    themes: themes.map((t) => {
+      const r = resolveTheme(t);
+      return { id: t.id, label: t.label || t.id, mode: t.mode || 'light', font: r.fonts.googleFontsUrl || '', baseSize: r.typography.baseSize };
+    }),
+    s: S,
+    mermaid: hasMermaid ? 'assets/mermaid.min.js' : 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js',
+  };
+
+  const searchIndex = [];
+  const recent = pages
+    .filter((p) => p.url !== '' && p.data.updated && !p.synthetic)
+    .sort((a, b) => String(b.data.updated).localeCompare(String(a.data.updated)))
+    .slice(0, 6);
+
+  for (const page of pages) {
+    const r = renderMarkdown(page, cfg, S, hosted, warnings);
+    const html = pageHtml({ page, cfg, S, tree, byUrl, clientCfg, rendered: r, recent, head, builtAt, hosted, dev });
+    const outFile = path.join(outDir, page.url, 'index.html');
+    fs.mkdirSync(path.dirname(outFile), { recursive: true });
+    fs.writeFileSync(outFile, html);
+    if (page.data.search !== false) {
+      searchIndex.push({
+        t: page.title,
+        u: page.url,
+        s: page.summary,
+        h: r.headings.map((h) => h.text).join(' · '),
+        x: r.html.replace(/<pre class="diagram-src">[\s\S]*?<\/pre>/g, ' ').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').slice(0, 2000),
+      });
+    }
+  }
+
+  // status page
+  const statusPage = {
+    url: '_status/', segs: ['_status'], depth: 1, title: S.status, summary: S.statusIntro, data: {}, sources: [], synthetic: true, isIndex: false, fresh: { status: 'none' },
+  };
+  const statusHtml = pageHtml({
+    page: statusPage, cfg, S, tree, byUrl, clientCfg, recent: [], head, builtAt, hosted, dev,
+    rendered: { html: statusTable(pages, S), headings: [] },
+  });
+  fs.mkdirSync(path.join(outDir, '_status'), { recursive: true });
+  fs.writeFileSync(path.join(outDir, '_status', 'index.html'), statusHtml);
+
+  fs.writeFileSync(path.join(outDir, 'assets', 'search-index.js'), 'window.__LD_SEARCH__=' + JSON.stringify(searchIndex) + ';');
+
+  const stale = pages.filter((p) => p.fresh.status === 'stale').length;
+  if (!quiet) {
+    console.log(`✓ ${pages.length} pages, ${themes.length} themes → ${path.relative(process.cwd(), outDir) || outDir} (${Date.now() - t0} ms)`);
+    if (stale) console.log(`! ${stale} pages possibly outdated (see /_status/)`);
+    for (const w of warnings) console.log('! ' + w);
+  }
+  return { pages: pages.length, warnings, stale };
+}
+
+// ---------- structure ----------
+
+function addMissingSections(pages) {
+  const urls = new Set(pages.map((p) => p.url));
+  const extra = [];
+  for (const p of pages) {
+    let u = p.parentUrl;
+    while (u !== null && u !== undefined) {
+      if (!urls.has(u)) {
+        urls.add(u);
+        const segs = u.split('/').filter(Boolean);
+        extra.push({
+          url: u, segs, depth: segs.length, isIndex: true, parentUrl: parentOf(u), data: {}, body: '', sources: [],
+          title: u === '' ? 'Home' : prettify(segs.at(-1)), summary: '', order: 1000, synthetic: true, rel: null,
+        });
+      }
+      u = parentOf(u);
+    }
+  }
+  return [...pages, ...extra];
+}
+
+function prettify(seg) {
+  const s = seg.replace(/[-_]+/g, ' ');
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function buildTree(pages) {
+  const nodes = new Map(pages.map((p) => [p.url, { page: p, children: [] }]));
+  for (const p of pages) {
+    if (p.url === '') continue;
+    const parent = nodes.get(p.parentUrl);
+    if (parent) parent.children.push(nodes.get(p.url));
+  }
+  const sort = (n) => {
+    n.children.sort((a, b) => a.page.order - b.page.order || a.page.title.localeCompare(b.page.title));
+    n.children.forEach(sort);
+  };
+  const root = nodes.get('');
+  sort(root);
+  return { root, nodes };
+}
+
+// ---------- markdown ----------
+
+function renderMarkdown(page, cfg, S, hosted, warnings) {
+  const headings = [];
+  const used = new Map();
+  const where = page.rel ? `content/${page.rel}` : page.url;
+  const m = new Marked({ gfm: true });
+  let diagramCount = 0;
+
+  m.use({
+    renderer: {
+      heading({ tokens, depth, text }) {
+        const inner = this.parser.parseInline(tokens);
+        let id = slugify(text);
+        const n = used.get(id) || 0;
+        used.set(id, n + 1);
+        if (n) id += '-' + n;
+        if (depth === 2 || depth === 3) headings.push({ depth, id, text: inner.replace(/<[^>]+>/g, '') });
+        return `<h${depth} id="${id}">${inner}<a class="anchor" href="#${id}" aria-label="link">#</a></h${depth}>\n`;
+      },
+      link({ href, title, tokens }) {
+        const text = this.parser.parseInline(tokens);
+        const t = title ? ` title="${escapeHtml(title)}"` : '';
+        if (href.startsWith('code:')) return codeLink(cfg, href, text, S, hosted);
+        if (href.startsWith('/')) return `<a href="${escapeHtml(relHref(page.url, href))}"${t}>${text}</a>`;
+        if (/^https?:\/\//.test(href)) return `<a href="${escapeHtml(href)}"${t} target="_blank" rel="noopener">${text}</a>`;
+        return `<a href="${escapeHtml(href)}"${t}>${text}</a>`;
+      },
+      image({ href, title, text }) {
+        const src = href.startsWith('/') ? relHref(page.url, href).replace(/\/index\.html$/, '') : href;
+        return `<img src="${escapeHtml(src)}" alt="${escapeHtml(text || '')}"${title ? ` title="${escapeHtml(title)}"` : ''} loading="lazy">`;
+      },
+      code({ text, lang }) {
+        const l = (lang || '').trim().split(/\s+/)[0];
+        if (l === 'mermaid') {
+          diagramCount++;
+          return diagramHtml(page, text, S);
+        }
+        if (l === 'decision') return decisionHtml(page, text, cfg, S, hosted, warnings, where);
+        return `<pre class="code"><code${l ? ` class="language-${escapeHtml(l)}"` : ''}>${escapeHtml(text)}</code></pre>\n`;
+      },
+    },
+  });
+
+  let html = m.parse(page.body || '');
+  html = html.replace(
+    new RegExp(`<blockquote>\\s*<p>\\[!(${CALLOUTS.join('|')})\\][ \\t]*([^\\n<]*)\\n?`, 'g'),
+    (_, type, title) => {
+      const label = S.callout[type] + (title.trim() ? ': ' + title.trim() : '');
+      return `<blockquote class="callout callout-${type.toLowerCase()}"><p class="callout-title">${label}</p><p>`;
+    },
+  );
+  html = html.replace(/<p>\s*<\/p>/g, '');
+  html = html.replace(/<table>/g, '<div class="table-wrap"><table>').replace(/<\/table>/g, '</table></div>');
+  return { html, headings, diagramCount };
+}
+
+function codeLink(cfg, href, text, S, hosted) {
+  const u = codeUrls(cfg, href, { hosted });
+  const label = text && text !== href ? text : `<code>${escapeHtml(u.label)}</code>`;
+  const primary = u.editor || u.web;
+  let out = primary
+    ? `<a class="code-link" href="${escapeHtml(primary)}" title="${escapeHtml((u.editor ? S.openInEditor : S.openOnWeb) + ': ' + u.label)}">${label}</a>`
+    : `<span class="code-link" title="${escapeHtml(u.label)}">${label}</span>`;
+  if (u.editor && u.web) out += ` <a class="code-web" href="${escapeHtml(u.web)}" target="_blank" rel="noopener">${S.openOnWeb}</a>`;
+  return out;
+}
+
+function diagramHtml(page, src, S) {
+  let caption = '';
+  const lines = src.split('\n').map((line) => {
+    const cap = line.match(/^\s*%%\s*caption:\s*(.+)$/i);
+    if (cap) {
+      caption = cap[1].trim();
+      return line;
+    }
+    // click Node "/site/path/" ["tooltip"]  → relative link
+    return line.replace(/^(\s*click\s+\S+\s+(?:href\s+)?)"(\/[^"]*)"/, (_, pre, href) => `${pre}"${relHref(page.url, href)}"`);
+  });
+  const fixed = lines.join('\n');
+  const cap = caption ? `<figcaption>${escapeHtml(caption)}</figcaption>` : '';
+  return `<figure class="diagram">${cap}<div class="diagram-canvas" aria-label="${escapeHtml(caption || 'diagram')}"></div><pre class="diagram-src">${escapeHtml(fixed)}</pre><button type="button" class="diagram-zoom" aria-label="${S.zoom}" title="${S.zoom}">⤢</button></figure>\n`;
+}
+
+function decisionHtml(page, src, cfg, S, hosted, warnings, where) {
+  let d;
+  try {
+    d = yaml.load(src);
+    if (!d || !Array.isArray(d.inputs) || !Array.isArray(d.rules)) throw new Error('requires "inputs" and "rules"');
+  } catch (e) {
+    warnings.push(`${where}: invalid decision block (${e.message})`);
+    return `<div class="callout callout-warning"><p class="callout-title">decision</p><p>${escapeHtml(e.message)}</p><pre>${escapeHtml(src)}</pre></div>`;
+  }
+  const inputs = d.inputs.map((i) => (typeof i === 'string' ? { id: i, label: i } : { label: i.id, ...i }));
+  const rules = d.rules.map((r) => ({ when: r.when || {}, then: r.then ?? '', note: r.note || '', code: r.code || '' }));
+  for (const inp of inputs) {
+    const vals = new Set((inp.values || []).map(String));
+    for (const r of rules) if (r.when[inp.id] !== undefined) vals.add(String(r.when[inp.id]));
+    inp.values = [...vals];
+  }
+  const data = { inputs: inputs.map(({ id, values }) => ({ id, values })), rules: rules.map((r) => ({ when: Object.fromEntries(Object.entries(r.when).map(([k, v]) => [k, String(v)])), then: String(r.then) })) };
+  const controls = inputs
+    .map((i) => `<label><span>${escapeHtml(i.label)}</span><select data-input="${escapeHtml(i.id)}"><option value="">${S.decisionAny}</option>${i.values.map((v) => `<option>${escapeHtml(v)}</option>`).join('')}</select></label>`)
+    .join('');
+  const rows = rules
+    .map((r, idx) => {
+      const cells = inputs.map((i) => `<td>${r.when[i.id] !== undefined ? escapeHtml(String(r.when[i.id])) : '<span class="muted">—</span>'}</td>`).join('');
+      const note = [r.note ? escapeHtml(r.note) : '', r.code ? codeLink(cfg, 'code:' + r.code, '', S, hosted) : ''].filter(Boolean).join(' ');
+      return `<tr data-rule="${idx}"><td class="num">${idx + 1}</td>${cells}<td class="then">${escapeHtml(String(r.then))}</td><td>${note}</td></tr>`;
+    })
+    .join('');
+  return `<div class="decision" data-decision="${escapeHtml(JSON.stringify(data))}">
+${d.title ? `<p class="decision-title">${escapeHtml(d.title)}</p>` : ''}<p class="decision-hint">${S.decisionHint}</p>
+<div class="decision-controls">${controls}</div><div class="decision-result" aria-live="polite"></div>
+<div class="table-wrap"><table><thead><tr><th>#</th>${inputs.map((i) => `<th>${escapeHtml(i.label)}</th>`).join('')}<th>${escapeHtml(d.output || S.decisionResult)}</th><th>${S.note}</th></tr></thead><tbody>${rows}</tbody></table></div></div>\n`;
+}
+
+// ---------- page chrome ----------
+
+function navHtml(node, page, root, depth = 0) {
+  return node.children
+    .filter((c) => c.page.data.nav !== false)
+    .map((c) => {
+      const p = c.page;
+      const href = relHref(page.url, '/' + p.url);
+      const current = p.url === page.url;
+      const inPath = page.url.startsWith(p.url) && p.url !== '';
+      const a = `<a href="${href}"${current ? ' aria-current="page"' : ''}>${escapeHtml(p.title)}</a>`;
+      const kids = c.children.filter((k) => k.page.data.nav !== false);
+      if (!kids.length) return `<li>${a}</li>`;
+      return `<li><details${inPath || depth === 0 && p.data.navOpen ? ' open' : ''}><summary>${a}</summary><ul>${navHtml(c, page, root, depth + 1)}</ul></details></li>`;
+    })
+    .join('');
+}
+
+function breadcrumbs(page, byUrl, S) {
+  if (page.url === '') return '';
+  const parts = [];
+  let u = parentOf(page.url);
+  while (u !== null) {
+    const p = byUrl.get(u);
+    parts.unshift(`<a href="${relHref(page.url, '/' + u)}">${escapeHtml(p ? (u === '' ? S.home : p.title) : u)}</a>`);
+    u = parentOf(u);
+  }
+  return `<nav class="crumbs" aria-label="breadcrumb">${parts.join('<span aria-hidden="true">/</span>')}</nav>`;
+}
+
+function badge(page, S) {
+  const f = page.fresh || { status: 'none' };
+  if (f.status === 'none') return '';
+  const date = page.data.updated ? ` · ${escapeHtml(String(page.data.updated))}` : '';
+  const miss = f.missing && f.missing.length ? ` <span class="badge badge-stale">${S.missing}: ${escapeHtml(f.missing.join(', '))}</span>` : '';
+  const txt = { fresh: S.fresh + date, stale: S.stale, unverified: S.unverified }[f.status];
+  return `<p class="freshness"><span class="badge badge-${f.status}">${txt}</span>${miss}</p>`;
+}
+
+function childrenHtml(page, tree, S) {
+  if (!page.isIndex || page.data.children === false) return '';
+  const node = tree.nodes.get(page.url);
+  if (!node) return '';
+  const kids = node.children.filter((k) => k.page.data.nav !== false);
+  if (!kids.length) return '';
+  const items = kids
+    .map((k) => `<li><a href="${relHref(page.url, '/' + k.page.url)}"><span class="child-title">${escapeHtml(k.page.title)}</span>${k.page.summary ? `<span class="child-summary">${escapeHtml(k.page.summary)}</span>` : ''}</a></li>`)
+    .join('');
+  return `<section class="children" aria-labelledby="deeper"><h2 id="deeper">${S.deeper}</h2><ul>${items}</ul></section>`;
+}
+
+function sourcesHtml(page, cfg, S, hosted) {
+  if (!page.sources.length) return '';
+  return `<aside class="sources"><p>${S.sources}</p><ul>${page.sources.map((s) => `<li>${codeLink(cfg, 'code:' + s, '', S, hosted)}</li>`).join('')}</ul></aside>`;
+}
+
+function recentHtml(page, recent, S) {
+  if (page.url !== '' || !recent.length) return '';
+  return `<section class="recent"><h2 id="recent">${S.recent}</h2><ul>${recent
+    .map((p) => `<li><a href="${relHref('', '/' + p.url)}">${escapeHtml(p.title)}</a> <span class="muted">${escapeHtml(String(p.data.updated))}</span></li>`)
+    .join('')}</ul></section>`;
+}
+
+function statusTable(pages, S) {
+  const order = { stale: 0, unverified: 1, fresh: 2, none: 3 };
+  const label = { stale: S.stale, unverified: S.unverified, fresh: S.fresh, none: S.noSources };
+  const rows = pages
+    .filter((p) => !p.synthetic)
+    .sort((a, b) => order[a.fresh.status] - order[b.fresh.status] || a.url.localeCompare(b.url))
+    .map((p) => `<tr><td><a href="${relHref('_status/', '/' + p.url)}">${escapeHtml(p.title)}</a><br><span class="muted">/${escapeHtml(p.url)}</span></td><td><span class="badge badge-${p.fresh.status}">${label[p.fresh.status]}</span></td><td>${escapeHtml(String(p.data.updated || '—'))}</td></tr>`)
+    .join('');
+  return `<div class="table-wrap"><table><thead><tr><th>${S.page}</th><th>${S.state}</th><th>${S.updated}</th></tr></thead><tbody>${rows}</tbody></table></div>`;
+}
+
+function tocHtml(headings, S) {
+  if (headings.length < 2) return '';
+  return `<nav class="toc" aria-label="${S.onThisPage}"><p>${S.onThisPage}</p><ul>${headings
+    .map((h) => `<li class="toc-${h.depth}"><a href="#${h.id}">${h.text}</a></li>`)
+    .join('')}</ul></nav>`;
+}
+
+function pageHtml({ page, cfg, S, tree, byUrl, clientCfg, rendered, recent, head, builtAt, hosted, dev }) {
+  const root = rootPrefix(page.url);
+  const siteTitle = escapeHtml(cfg.title);
+  const title = page.url === '' ? siteTitle : `${escapeHtml(page.title)} · ${siteTitle}`;
+  const boot = `window.__LD__=${JSON.stringify({ ...clientCfg, root, url: page.url })};
+(function(){var c=window.__LD__,d=document.documentElement,t=null;d.classList.add('js');try{t=localStorage.getItem('ld:'+c.id+':theme')}catch(e){}
+if(!t||!c.themes.some(function(x){return x.id===t}))t=c.defaultTheme;d.setAttribute('data-theme',t);
+var th=c.themes.filter(function(x){return x.id===t})[0];if(th&&th.font){var l=document.createElement('link');l.rel='stylesheet';l.id='ld-font';l.href=th.font;document.head.appendChild(l);}})();`;
+  const date = builtAt.toISOString().slice(0, 16).replace('T', ' ');
+  const home = `<a class="brand" href="${root}index.html">${siteTitle}</a>`;
+  const reload = dev ? `<script>try{new EventSource('/__reload').onmessage=function(){location.reload()}}catch(e){}</script>` : '';
+  return `<!doctype html>
+<html lang="${escapeHtml(cfg.uiLanguage)}" data-theme="${escapeHtml(cfg.defaultTheme)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>${title}</title>
+${page.summary ? `<meta name="description" content="${escapeHtml(page.summary)}">` : ''}
+<link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="${root}assets/themes.css">
+<link rel="stylesheet" href="${root}assets/base.css">
+<script>${boot}</script>
+</head>
+<body>
+<a class="skip" href="#main">Skip</a>
+<header class="topbar">
+  <button class="nav-toggle" type="button" aria-expanded="false" aria-controls="sidebar">${S.menu}</button>
+  ${home}
+  <div class="search" role="search">
+    <input id="search" type="search" placeholder="${S.search}" aria-label="${S.search}" autocomplete="off" spellcheck="false">
+    <kbd>/</kbd>
+    <div class="search-results" id="search-results" hidden></div>
+  </div>
+  <div class="controls">
+    <div class="fontsize" role="group" aria-label="${S.fontSize}" title="${escapeHtml(S.fontSizeHint)}">
+      <button type="button" data-fs="-1" aria-label="${S.smaller}">A−</button>
+      <button type="button" data-fs="0" class="fs-value" aria-label="${S.reset}">100%</button>
+      <button type="button" data-fs="1" aria-label="${S.larger}">A+</button>
+    </div>
+    <label class="theme-pick"><span class="sr">${S.theme}</span><select id="theme-select" aria-label="${S.theme}"></select></label>
+  </div>
+</header>
+<div class="layout">
+  <aside class="sidebar" id="sidebar">
+    <nav aria-label="${S.menu}"><ul class="nav-root"><li><a href="${root}index.html"${page.url === '' ? ' aria-current="page"' : ''}>${S.home}</a></li>${navHtml(tree.root, page, tree.root)}</ul></nav>
+  </aside>
+  <main id="main">
+    <article class="page">
+      ${breadcrumbs(page, byUrl, S)}
+      <h1>${escapeHtml(page.url === '' ? page.title || cfg.title : page.title)}</h1>
+      ${page.summary ? `<p class="summary">${escapeHtml(page.summary)}</p>` : ''}
+      ${badge(page, S)}
+      <div class="prose">${rendered.html}</div>
+      ${childrenHtml(page, tree, S)}
+      ${recentHtml(page, recent, S)}
+      ${sourcesHtml(page, cfg, S, hosted)}
+    </article>
+    <footer class="footer">${S.generated} ${date}${head ? ` ${S.fromCommit} <code>${escapeHtml(head)}</code>` : ''} · <a href="${root}_status/index.html">${S.status}</a></footer>
+  </main>
+  ${tocHtml(rendered.headings, S)}
+</div>
+<div class="zoom-overlay" hidden><div class="zoom-bar"><button type="button" data-z="in" aria-label="${S.zoomIn}">+</button><button type="button" data-z="out" aria-label="${S.zoomOut}">−</button><button type="button" data-z="fit">${S.fit}</button><button type="button" data-z="close">${S.close} (Esc)</button></div><div class="zoom-stage"></div></div>
+<script src="${root}assets/search-index.js" defer></script>
+<script src="${root}assets/app.js" defer></script>
+${reload}
+</body>
+</html>
+`;
+}
+
+// ---------- cli ----------
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+if (isMain || process.argv[1]?.endsWith('build.mjs')) {
+  const args = process.argv.slice(2);
+  const outIdx = args.indexOf('--out');
+  build({ hosted: args.includes('--hosted'), outDir: outIdx > -1 ? path.resolve(args[outIdx + 1]) : undefined }).catch((e) => {
+    console.error('✗ ' + e.message);
+    process.exit(1);
+  });
+}

package/skills/docs-init/assets/site-template/engine/check.mjs

@@ -0,0 +1,100 @@
+// Validates content/: frontmatter, internal links, diagram links, code references, limits, freshness.
+// Usage: node engine/check.mjs [--json]      exit code 1 when there are errors
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { loadConfig, loadPages, freshness, parseCodeRef, hrefToUrlKey, wordCount, CONTENT_DIR, GUIDE_FILE } from './lib.mjs';
+
+const cfg = loadConfig();
+const pages = loadPages();
+const urls = new Set(pages.map((p) => p.url));
+// directories without index.md still get an auto-generated section page
+for (const p of pages) { let u = p.parentUrl; while (u) { urls.add(u); u = u.split('/').filter(Boolean).slice(0, -1).join('/'); u = u ? u + '/' : null; } }
+urls.add('');
+urls.add('_status/');
+
+const issues = [];
+const add = (level, page, msg) => issues.push({ level, page: page ? 'content/' + page.rel : '-', msg });
+const DIAGRAM_TYPES = /^(flowchart|graph|sequenceDiagram|classDiagram|stateDiagram(-v2)?|erDiagram|journey|gantt|pie|mindmap|timeline|gitGraph|C4Context|C4Container|C4Component|C4Dynamic|C4Deployment|quadrantChart|requirementDiagram|sankey(-beta)?|xychart(-beta)?|block(-beta)?|packet(-beta)?|architecture(-beta)?|kanban|radar(-beta)?|treemap(-beta)?)\b/;
+
+function checkCodeRef(page, ref, where) {
+  const { file, line } = parseCodeRef(ref);
+  const abs = path.join(cfg.projectRootAbs, file);
+  if (!fs.existsSync(abs)) return add('error', page, `${where}: file does not exist: ${file}`);
+  if (line && fs.statSync(abs).isFile()) {
+    const n = fs.readFileSync(abs, 'utf8').split('\n').length;
+    if (line > n) add('error', page, `${where}: ${file} has only ${n} lines (reference to line ${line})`);
+  }
+}
+
+function checkInternal(page, href, where) {
+  const key = hrefToUrlKey(href);
+  if (path.posix.extname(key.replace(/\/$/, ''))) {
+    if (!fs.existsSync(path.join(CONTENT_DIR, key))) add('error', page, `${where}: missing file in content/: /${key}`);
+    return;
+  }
+  if (!urls.has(key)) add('error', page, `${where}: link to a page that does not exist: ${href}`);
+}
+
+if (!fs.existsSync(GUIDE_FILE)) add('warning', null, 'DOCS-GUIDE.md is missing: the docs-guide skill can recreate it');
+
+for (const page of pages) {
+  const d = page.data;
+  if (page.frontmatterError) { add('error', page, 'frontmatter YAML invalid: ' + page.frontmatterError); continue; }
+  if (!d.title) add('error', page, 'missing "title" in frontmatter');
+  if (!d.summary) add('error', page, 'missing "summary" (1–2 sentences, used for overviews and search)');
+  else if (String(d.summary).length > cfg.limits.summaryMaxChars) add('warning', page, `summary has ${String(d.summary).length} characters (limit ${cfg.limits.summaryMaxChars})`);
+  if (/<!--\s*stub\s*-->/.test(page.body)) add('warning', page, 'stub page, not written yet');
+  const words = wordCount(page.body);
+  if (words > cfg.limits.pageMaxWords) add('warning', page, `page has ~${words} words (limit ${cfg.limits.pageMaxWords}); split it into subpages`);
+  for (const s of page.sources) checkCodeRef(page, s, 'sources');
+  const f = freshness(cfg, page);
+  if (f.status === 'stale') add('info', page, 'possibly outdated: its sources changed after the last stamp');
+  if (f.status === 'unverified') add('info', page, 'has sources but was never verified (run facts.mjs stamp after verifying)');
+
+  const body = page.body.replace(/\r\n/g, '\n');
+  // fenced blocks first, then strip them for link scanning
+  const fences = [...body.matchAll(/^```([^\n]*)\n([\s\S]*?)^```/gm)];
+  for (const [, info, code] of fences) {
+    const lang = info.trim().split(/\s+/)[0];
+    if (lang === 'mermaid') {
+      const first = code.split('\n').map((l) => l.trim()).find((l) => l && !l.startsWith('%%'));
+      if (!first || !DIAGRAM_TYPES.test(first)) add('error', page, `mermaid diagram without a valid type on its first line ("${(first || '').slice(0, 30)}")`);
+      for (const m of code.matchAll(/^\s*click\s+\S+\s+(?:href\s+)?"([^"]+)"/gm)) {
+        if (m[1].startsWith('/')) checkInternal(page, m[1], 'diagram click');
+      }
+      const nodes = (code.match(/^\s*\w+\s*[\[\(\{>]/gm) || []).length;
+      if (nodes > 25) add('warning', page, `diagram with ~${nodes} nodes; above ~15 it gets hard to read, split it into levels`);
+    }
+    if (lang === 'decision') {
+      try {
+        const dd = yaml.load(code);
+        if (!Array.isArray(dd?.inputs) || !Array.isArray(dd?.rules)) throw new Error('requires "inputs" and "rules"');
+        dd.rules.forEach((r, i) => { if (r.code) checkCodeRef(page, r.code, `decision rule ${i + 1}`); });
+      } catch (e) {
+        add('error', page, 'invalid decision block: ' + e.message);
+      }
+    }
+  }
+  const prose = body.replace(/^```[\s\S]*?^```/gm, '').replace(/`[^`\n]*`/g, '');
+  for (const m of prose.matchAll(/\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+    const href = m[1];
+    if (href.startsWith('code:')) checkCodeRef(page, href, 'code link');
+    else if (href.startsWith('/')) checkInternal(page, href, 'link');
+    else if (!/^(https?:|mailto:|#)/.test(href)) add('warning', page, `relative link "${href}": use site-absolute paths (/section/page/)`);
+  }
+}
+
+const sections = new Set(pages.map((p) => p.parentUrl).filter((u) => u !== null && u !== undefined));
+for (const u of sections) if (u && !pages.some((p) => p.url === u)) add('warning', null, `section /${u} has no index.md (an empty page is generated)`);
+
+if (process.argv.includes('--json')) console.log(JSON.stringify(issues, null, 2));
+else {
+  const icon = { error: '✗', warning: '!', info: '·' };
+  for (const i of issues.sort((a, b) => ['error', 'warning', 'info'].indexOf(a.level) - ['error', 'warning', 'info'].indexOf(b.level))) {
+    console.log(`${icon[i.level]} ${i.level.toUpperCase().padEnd(7)} ${i.page}: ${i.msg}`);
+  }
+  const c = (l) => issues.filter((i) => i.level === l).length;
+  console.log(`\n${pages.length} pages · ${c('error')} errors · ${c('warning')} warnings · ${c('info')} notes`);
+}
+process.exit(issues.some((i) => i.level === 'error') ? 1 : 0);

package/skills/docs-init/assets/site-template/engine/dev.mjs

@@ -0,0 +1,49 @@
+// Local preview: builds, serves dist/ and rebuilds + reloads the browser on every change.
+// Usage: node engine/dev.mjs [--port 4321]
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { build } from './build.mjs';
+import { SITE_DIR } from './lib.mjs';
+
+const args = process.argv.slice(2);
+const port = +(args[args.indexOf('--port') + 1] || process.env.PORT || 4321) || 4321;
+const dist = path.join(SITE_DIR, 'dist');
+const clients = new Set();
+const types = { '.html': 'text/html; charset=utf-8', '.css': 'text/css', '.js': 'text/javascript', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
+
+async function rebuild() {
+  try {
+    await build({ dev: true });
+    for (const res of clients) res.write('data: reload\n\n');
+  } catch (e) {
+    console.error('✗ ' + e.message);
+  }
+}
+
+await rebuild();
+
+let timer;
+const schedule = () => { clearTimeout(timer); timer = setTimeout(rebuild, 150); };
+for (const p of ['content', 'themes', 'engine']) {
+  const dir = path.join(SITE_DIR, p);
+  if (fs.existsSync(dir)) fs.watch(dir, { recursive: true }, (_, f) => { if (!String(f).includes('vendor')) schedule(); });
+}
+fs.watch(path.join(SITE_DIR, 'docs.config.json'), schedule);
+
+http.createServer((req, res) => {
+  const url = decodeURIComponent(req.url.split('?')[0]);
+  if (url === '/__reload') {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+    res.write(': ok\n\n');
+    clients.add(res);
+    req.on('close', () => clients.delete(res));
+    return;
+  }
+  let file = path.join(dist, url);
+  if (!file.startsWith(dist)) { res.writeHead(403); return res.end(); }
+  if (fs.existsSync(file) && fs.statSync(file).isDirectory()) file = path.join(file, 'index.html');
+  if (!fs.existsSync(file)) { res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); return res.end('404 — page not found'); }
+  res.writeHead(200, { 'Content-Type': types[path.extname(file)] || 'application/octet-stream', 'Cache-Control': 'no-store' });
+  fs.createReadStream(file).pipe(res);
+}).listen(port, () => console.log(`→ http://localhost:${port}  (Ctrl+C to stop)`));