living-docs-kit 0.1.0

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

@@ -0,0 +1,157 @@
+// Deterministic facts about the project, so the agent documents what exists instead of guessing.
+//
+//   node engine/facts.mjs                 JSON: stack, structure, tests, git, docs coverage
+//   node engine/facts.mjs changes         JSON: files changed since last generation + affected pages
+//   node engine/facts.mjs stamp <page.md…> record that these pages were verified against their sources NOW
+//   node engine/facts.mjs mark            record HEAD as the last full generation point
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { SITE_DIR, CONTENT_DIR, loadConfig, saveConfig, loadPages, freshness, hashSources, parseCodeRef, git } from './lib.mjs';
+
+const cfg = loadConfig();
+const [cmd = 'facts', ...rest] = process.argv.slice(2);
+
+const MANIFESTS = ['package.json', 'pnpm-workspace.yaml', 'tsconfig.json', 'pyproject.toml', 'requirements.txt', 'setup.py', 'Pipfile', 'go.mod', 'Cargo.toml', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'composer.json', 'Gemfile', 'mix.exs', 'pubspec.yaml', 'Package.swift', 'Dockerfile', 'docker-compose.yml', 'compose.yaml', 'openapi.yaml', 'openapi.json', 'schema.prisma', '.env.example'];
+const TEST_RE = /(^|\/)(tests?|__tests__|spec|specs)\/|\.(test|spec)\.[a-z0-9]+$|_test\.(go|py|rb|exs)$|(^|\/)test_[^/]+\.py$|Tests?\.(cs|java|kt|swift)$/i;
+const ENTRY_RE = /(^|\/)(main|index|app|server|cli|program|manage|wsgi|asgi)\.[a-z]+$|(^|\/)cmd\/[^/]+\/main\.go$|(^|\/)src\/main\//i;
+
+function listProjectFiles() {
+  const viaGit = git(cfg, ['ls-files', '--cached', '--others', '--exclude-standard']);
+  let files;
+  if (viaGit !== null) files = viaGit.split('\n').filter(Boolean);
+  else {
+    files = [];
+    const ex = new Set(cfg.excludeAll.map((e) => e.split('/').pop()));
+    (function rec(d) {
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+        if (e.name.startsWith('.') || ex.has(e.name)) continue;
+        const f = path.join(d, e.name);
+        if (e.isDirectory()) rec(f);
+        else files.push(path.relative(cfg.projectRootAbs, f).split(path.sep).join('/'));
+      }
+    })(cfg.projectRootAbs);
+  }
+  return files.filter((f) => !cfg.excludeAll.some((e) => f === e || f.startsWith(e + '/') || f.includes('/' + e + '/')));
+}
+
+function facts() {
+  const files = listProjectFiles();
+  const langs = {};
+  const dirs = {};
+  for (const f of files) {
+    const ext = path.extname(f).slice(1).toLowerCase() || '(no extension)';
+    langs[ext] = (langs[ext] || 0) + 1;
+    const parts = f.split('/');
+    const key = parts.length > 2 ? parts.slice(0, 2).join('/') : parts.length === 2 ? parts[0] : '.';
+    dirs[key] = (dirs[key] || 0) + 1;
+  }
+  const tests = files.filter((f) => TEST_RE.test(f));
+  const pages = loadPages();
+  const covered = new Set();
+  for (const p of pages) for (const s of p.sources) covered.add(parseCodeRef(s).file.replace(/\/$/, ''));
+  const isCovered = (f) => [...covered].some((c) => f === c || f.startsWith(c + '/'));
+  const codeFiles = files.filter((f) => /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|rb|php|swift|ex|exs|dart|vue|svelte|scala|c|cc|cpp|h|hpp|sql)$/i.test(f) && !TEST_RE.test(f));
+  const statuses = pages.map((p) => ({ page: 'content/' + p.rel, title: p.title, ...freshness(cfg, p) }));
+  return {
+    projectRoot: cfg.projectRootAbs,
+    site: path.relative(cfg.projectRootAbs, SITE_DIR) || '.',
+    git: {
+      available: git(cfg, ['rev-parse', '--is-inside-work-tree']) === 'true',
+      head: git(cfg, ['rev-parse', 'HEAD']),
+      branch: git(cfg, ['rev-parse', '--abbrev-ref', 'HEAD']),
+      remote: git(cfg, ['remote', 'get-url', 'origin']),
+      uncommitted: (git(cfg, ['status', '--porcelain']) || '').split('\n').filter(Boolean).length,
+    },
+    totals: { files: files.length, codeFiles: codeFiles.length, testFiles: tests.length },
+    languages: Object.fromEntries(Object.entries(langs).sort((a, b) => b[1] - a[1]).slice(0, 15)),
+    structure: Object.fromEntries(Object.entries(dirs).sort((a, b) => b[1] - a[1]).slice(0, 40)),
+    manifests: files.filter((f) => MANIFESTS.includes(path.basename(f))).slice(0, 40),
+    readmes: files.filter((f) => /(^|\/)(readme|agents|claude|contributing|architecture)[^/]*\.md$/i.test(f)).slice(0, 60),
+    entryCandidates: files.filter((f) => ENTRY_RE.test(f) && !TEST_RE.test(f)).slice(0, 30),
+    tests: { sample: tests.slice(0, 40) },
+    docs: {
+      pages: pages.length,
+      guideApproved: cfg.state.guideApproved,
+      lastGeneratedCommit: cfg.state.lastGeneratedCommit,
+      lastGeneratedAt: cfg.state.lastGeneratedAt,
+      stale: statuses.filter((s) => s.status === 'stale').map((s) => s.page),
+      unverified: statuses.filter((s) => s.status === 'unverified').map((s) => s.page),
+      missingSources: statuses.filter((s) => s.missing && s.missing.length).map((s) => ({ page: s.page, missing: s.missing })),
+      uncoveredCodeFiles: codeFiles.filter((f) => !isCovered(f)).slice(0, 80),
+      uncoveredCount: codeFiles.filter((f) => !isCovered(f)).length,
+    },
+  };
+}
+
+function changes() {
+  const since = rest[0] || cfg.state.lastGeneratedCommit;
+  const base = since && git(cfg, ['cat-file', '-e', since + '^{commit}']) !== null ? since : 'HEAD';
+  let changed = [];
+  {
+    changed = (git(cfg, ['diff', '--name-status', base]) || '').split('\n').filter(Boolean).map((l) => {
+      const [st, ...p] = l.split('\t');
+      return { status: st[0], file: p.at(-1) };
+    });
+  }
+  const untracked = (git(cfg, ['ls-files', '--others', '--exclude-standard']) || '').split('\n').filter(Boolean).map((f) => ({ status: '?', file: f }));
+  const all = [...changed, ...untracked].filter((c) => !cfg.excludeAll.some((e) => c.file === e || c.file.startsWith(e + '/')));
+  const pages = loadPages();
+  const affected = [];
+  for (const p of pages) {
+    const hits = all.filter((c) => p.sources.some((s) => { const f = parseCodeRef(s).file.replace(/\/$/, ''); return c.file === f || c.file.startsWith(f + '/'); }));
+    const st = freshness(cfg, p).status;
+    if (hits.length || st === 'stale') affected.push({ page: 'content/' + p.rel, status: st, files: hits.map((h) => h.file) });
+  }
+  const coveredBySomePage = (f) => pages.some((p) => p.sources.some((s) => { const x = parseCodeRef(s).file.replace(/\/$/, ''); return f === x || f.startsWith(x + '/'); }));
+  return {
+    since: since || null,
+    head: git(cfg, ['rev-parse', 'HEAD']),
+    log: since ? (git(cfg, ['log', '--oneline', '--no-merges', `${since}..HEAD`]) || '').split('\n').filter(Boolean).slice(0, 50) : [],
+    changedFiles: all,
+    affectedPages: affected,
+    uncoveredChanges: all.filter((c) => c.status !== 'D' && !coveredBySomePage(c.file)).map((c) => c.file),
+    deletedFiles: all.filter((c) => c.status === 'D').map((c) => c.file),
+  };
+}
+
+function stamp(targets) {
+  if (!targets.length) throw new Error('stamp: pass at least one page, e.g. content/architecture/api.md');
+  const today = new Date().toISOString().slice(0, 10);
+  const head = git(cfg, ['rev-parse', '--short', 'HEAD']);
+  const out = [];
+  for (const t of targets) {
+    const file = path.isAbsolute(t) ? t : fs.existsSync(path.resolve(t)) ? path.resolve(t) : path.join(SITE_DIR, t);
+    if (!fs.existsSync(file)) throw new Error('not found: ' + t);
+    const src = fs.readFileSync(file, 'utf8');
+    const parsed = matter(src, {});
+    const sources = [].concat(parsed.data.sources || []);
+    if (!sources.length) { out.push({ page: t, skipped: 'no sources' }); continue; }
+    const { hash, missing } = hashSources(cfg, sources);
+    if (missing.length) throw new Error(`${t}: sources not found: ${missing.join(', ')}`);
+    parsed.data.sourcesHash = hash;
+    parsed.data.updated = today;
+    if (head) parsed.data.commit = head;
+    fs.writeFileSync(file, matter.stringify(parsed.content, parsed.data, { lineWidth: -1 }));
+    out.push({ page: path.relative(SITE_DIR, file), hash });
+  }
+  return out;
+}
+
+function mark() {
+  const head = git(cfg, ['rev-parse', 'HEAD']);
+  const at = new Date().toISOString();
+  saveConfig((c) => {
+    c.state = { ...(c.state || {}), lastGeneratedCommit: head, lastGeneratedAt: at };
+  });
+  return { lastGeneratedCommit: head, lastGeneratedAt: at };
+}
+
+try {
+  const result = cmd === 'facts' ? facts() : cmd === 'changes' ? changes() : cmd === 'stamp' ? stamp(rest) : cmd === 'mark' ? mark() : null;
+  if (!result) throw new Error(`unknown command "${cmd}". Use: facts | changes [commit] | stamp <pages…> | mark`);
+  console.log(JSON.stringify(result, null, 2));
+} catch (e) {
+  console.error('✗ ' + e.message);
+  process.exit(1);
+}

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

@@ -0,0 +1,99 @@
+// UI strings. Add a language by copying one block; set "uiLanguage" in docs.config.json.
+export const STRINGS = {
+  ro: {
+    home: 'Acasă',
+    search: 'Caută în documentație',
+    searchNoResults: 'Niciun rezultat. Încearcă alt cuvânt.',
+    theme: 'Temă',
+    themeDefault: 'Implicită',
+    fontSize: 'Mărime text',
+    fontSizeHint: 'Temporar: se resetează la reîncărcare. Pentru a o păstra, cere agentului să salveze mărimea fontului în design (skill-ul docs-design).',
+    smaller: 'Micșorează textul',
+    larger: 'Mărește textul',
+    reset: 'Mărime implicită',
+    menu: 'Meniu',
+    onThisPage: 'Pe această pagină',
+    deeper: 'Mai în detaliu',
+    sources: 'Cod documentat pe această pagină',
+    openInEditor: 'Deschide în editor',
+    openOnWeb: 'web',
+    recent: 'Actualizate recent',
+    fresh: 'Verificat cu codul',
+    stale: 'Posibil învechit: codul s-a schimbat după ultima verificare',
+    unverified: 'Neverificat cu codul',
+    missing: 'Fișiere sursă lipsă',
+    generated: 'Generat',
+    fromCommit: 'din commit',
+    status: 'Starea documentației',
+    statusIntro: 'Paginile marcate „posibil învechit” descriu cod care s-a schimbat după ultima verificare. Cere agentului să actualizeze documentația.',
+    page: 'Pagină',
+    state: 'Stare',
+    updated: 'Actualizat',
+    noSources: 'fără surse',
+    zoom: 'Mărește diagrama',
+    close: 'Închide',
+    zoomIn: 'Apropie',
+    zoomOut: 'Depărtează',
+    fit: 'Încadrează',
+    diagramError: 'Diagrama nu a putut fi desenată. Sursa ei:',
+    decisionAny: '(oricare)',
+    decisionResult: 'Rezultat',
+    decisionNoMatch: 'Nicio regulă nu se potrivește cu această combinație.',
+    decisionPartial: '{n} reguli posibile. Alege toate valorile pentru un rezultat exact.',
+    decisionHint: 'Alege valori pentru a vedea ce regulă se aplică. Regulile se verifică în ordine; prima potrivire câștigă.',
+    rule: 'Regula',
+    note: 'Notă',
+    code: 'Cod',
+    callout: { NOTE: 'Notă', TIP: 'Sfat', WARNING: 'Atenție', EDGE: 'Caz particular', RISK: 'Risc', UNVERIFIED: 'Neverificat', DECISION: 'Decizie' },
+  },
+  en: {
+    home: 'Home',
+    search: 'Search the docs',
+    searchNoResults: 'No results. Try another word.',
+    theme: 'Theme',
+    themeDefault: 'Default',
+    fontSize: 'Text size',
+    fontSizeHint: 'Temporary: resets on reload. To keep it, ask the agent to save the font size into the design (docs-design skill).',
+    smaller: 'Smaller text',
+    larger: 'Larger text',
+    reset: 'Default size',
+    menu: 'Menu',
+    onThisPage: 'On this page',
+    deeper: 'Go deeper',
+    sources: 'Code documented on this page',
+    openInEditor: 'Open in editor',
+    openOnWeb: 'web',
+    recent: 'Recently updated',
+    fresh: 'Verified against code',
+    stale: 'Possibly outdated: code changed after last verification',
+    unverified: 'Not verified against code',
+    missing: 'Missing source files',
+    generated: 'Generated',
+    fromCommit: 'from commit',
+    status: 'Documentation status',
+    statusIntro: 'Pages marked “possibly outdated” describe code that changed after their last verification. Ask the agent to update the docs.',
+    page: 'Page',
+    state: 'State',
+    updated: 'Updated',
+    noSources: 'no sources',
+    zoom: 'Enlarge diagram',
+    close: 'Close',
+    zoomIn: 'Zoom in',
+    zoomOut: 'Zoom out',
+    fit: 'Fit',
+    diagramError: 'The diagram could not be drawn. Its source:',
+    decisionAny: '(any)',
+    decisionResult: 'Result',
+    decisionNoMatch: 'No rule matches this combination.',
+    decisionPartial: '{n} possible rules. Pick every value for an exact result.',
+    decisionHint: 'Pick values to see which rule applies. Rules are checked in order; the first match wins.',
+    rule: 'Rule',
+    note: 'Note',
+    code: 'Code',
+    callout: { NOTE: 'Note', TIP: 'Tip', WARNING: 'Warning', EDGE: 'Edge case', RISK: 'Risk', UNVERIFIED: 'Unverified', DECISION: 'Decision' },
+  },
+};
+
+export function strings(lang) {
+  return STRINGS[lang] || STRINGS.en;
+}

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

@@ -0,0 +1,368 @@
+// Shared helpers for the living-docs engine: config, pages, themes, hashing, git.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import matter from 'gray-matter';
+
+export const SITE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const CONTENT_DIR = path.join(SITE_DIR, 'content');
+export const THEMES_DIR = path.join(SITE_DIR, 'themes');
+export const CONFIG_FILE = path.join(SITE_DIR, 'docs.config.json');
+export const GUIDE_FILE = path.join(SITE_DIR, 'DOCS-GUIDE.md');
+
+const CONFIG_DEFAULTS = {
+  id: 'docs',
+  title: 'Documentation',
+  description: '',
+  uiLanguage: 'en',
+  projectRoot: '..',
+  defaultTheme: 'fjord',
+  codeLinks: { mode: 'editor', editor: 'cursor', webBase: '' },
+  limits: { summaryMaxChars: 280, pageMaxWords: 900 },
+  exclude: ['node_modules', 'dist', 'build', 'out', '.git', 'vendor', '.venv', 'venv', '__pycache__', 'coverage', '.next', 'target'],
+  state: { guideApproved: false, lastGeneratedCommit: null, lastGeneratedAt: null },
+};
+
+export function loadConfig() {
+  let raw = {};
+  if (fs.existsSync(CONFIG_FILE)) raw = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  const cfg = {
+    ...CONFIG_DEFAULTS,
+    ...raw,
+    codeLinks: { ...CONFIG_DEFAULTS.codeLinks, ...(raw.codeLinks || {}) },
+    limits: { ...CONFIG_DEFAULTS.limits, ...(raw.limits || {}) },
+    state: { ...CONFIG_DEFAULTS.state, ...(raw.state || {}) },
+  };
+  cfg.projectRootAbs = path.resolve(SITE_DIR, cfg.projectRoot);
+  const siteRel = path.relative(cfg.projectRootAbs, SITE_DIR).split(path.sep).join('/');
+  cfg.excludeAll = [...new Set([...(cfg.exclude || []), siteRel].filter(Boolean))];
+  return cfg;
+}
+
+export function saveConfig(mutator) {
+  const raw = fs.existsSync(CONFIG_FILE) ? JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')) : {};
+  mutator(raw);
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(raw, null, 2) + '\n');
+  return raw;
+}
+
+// ---------- pages ----------
+
+export function walk(dir, filter = () => true, acc = []) {
+  if (!fs.existsSync(dir)) return acc;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, filter, acc);
+    else if (filter(full)) acc.push(full);
+  }
+  return acc;
+}
+
+/** url is '' for home, 'a/' for a/index.md, 'a/b/' for a/b.md */
+export function fileToUrl(rel) {
+  const noExt = rel.replace(/\\/g, '/').replace(/\.md$/i, '');
+  if (noExt === 'index') return '';
+  if (noExt.endsWith('/index')) return noExt.slice(0, -'index'.length);
+  return noExt + '/';
+}
+
+export function loadPages() {
+  const files = walk(CONTENT_DIR, (f) => f.toLowerCase().endsWith('.md')).sort();
+  return files.map((file) => {
+    const rel = path.relative(CONTENT_DIR, file).split(path.sep).join('/');
+    const src = fs.readFileSync(file, 'utf8');
+    let parsed;
+    try {
+      parsed = matter(src, {});
+    } catch (e) {
+      parsed = { data: {}, content: src, error: e.message };
+    }
+    const url = fileToUrl(rel);
+    const segs = url.split('/').filter(Boolean);
+    const isIndex = /(^|\/)index\.md$/i.test(rel);
+    const data = { ...(parsed.data || {}) };
+    for (const [k, v] of Object.entries(data)) if (v instanceof Date) data[k] = v.toISOString().slice(0, 10);
+    return {
+      file,
+      rel,
+      url,
+      segs,
+      depth: segs.length,
+      isIndex,
+      parentUrl: parentOf(url),
+      data,
+      body: parsed.content || '',
+      frontmatterError: parsed.error || null,
+      title: String(data.title || (segs.at(-1) || 'Home')),
+      summary: data.summary ? String(data.summary).trim() : '',
+      order: typeof data.order === 'number' ? data.order : 1000,
+      sources: normalizeSources(data.sources),
+    };
+  });
+}
+
+export function parentOf(url) {
+  if (!url) return null;
+  const segs = url.split('/').filter(Boolean);
+  segs.pop();
+  return segs.length ? segs.join('/') + '/' : '';
+}
+
+export function normalizeSources(src) {
+  if (!src) return [];
+  const list = Array.isArray(src) ? src : [src];
+  return list.map((s) => String(s).trim()).filter(Boolean);
+}
+
+/** Resolve a site-absolute href ('/a/b/#x') to a relative one from a page url. */
+export function relHref(fromUrl, href) {
+  if (!href.startsWith('/')) return href;
+  const depth = fromUrl.split('/').filter(Boolean).length;
+  const prefix = depth ? '../'.repeat(depth) : './';
+  let [p, hash] = splitHash(href.slice(1));
+  if (p === '' || p.endsWith('/')) p += 'index.html';
+  else if (!path.posix.extname(p)) p += '/index.html';
+  return prefix + p + (hash ? '#' + hash : '');
+}
+
+export function rootPrefix(fromUrl) {
+  const depth = fromUrl.split('/').filter(Boolean).length;
+  return depth ? '../'.repeat(depth) : './';
+}
+
+function splitHash(s) {
+  const i = s.indexOf('#');
+  return i === -1 ? [s, ''] : [s.slice(0, i), s.slice(i + 1)];
+}
+
+/** Normalise an internal link target to a page url key ('a/b/'). */
+export function hrefToUrlKey(href) {
+  let [p] = splitHash(href.replace(/^\//, ''));
+  p = p.replace(/index\.html$/, '');
+  if (p && !p.endsWith('/') && !path.posix.extname(p)) p += '/';
+  return p;
+}
+
+// ---------- code references ----------
+
+/** 'src/a.ts#L10-20' | 'src/a.ts:10' -> { file, line, lineEnd } */
+export function parseCodeRef(ref) {
+  let s = ref.replace(/^code:/, '').trim();
+  let line = null;
+  let lineEnd = null;
+  let m = s.match(/#L(\d+)(?:-L?(\d+))?$/);
+  if (m) {
+    line = +m[1];
+    lineEnd = m[2] ? +m[2] : null;
+    s = s.slice(0, m.index);
+  } else if ((m = s.match(/:(\d+)(?:-(\d+))?$/))) {
+    line = +m[1];
+    lineEnd = m[2] ? +m[2] : null;
+    s = s.slice(0, m.index);
+  }
+  return { file: s.replace(/^\.?\//, ''), line, lineEnd };
+}
+
+export function codeUrls(cfg, ref, { hosted = false } = {}) {
+  const { file, line, lineEnd } = parseCodeRef(ref);
+  const mode = hosted ? 'web' : cfg.codeLinks.mode;
+  const out = {};
+  if ((mode === 'editor' || mode === 'both') && cfg.codeLinks.editor !== 'none') {
+    const abs = path.join(cfg.projectRootAbs, file).split(path.sep).join('/');
+    const scheme = cfg.codeLinks.editor === 'vscode' ? 'vscode' : 'cursor';
+    const absUrl = abs.startsWith('/') ? abs : '/' + abs;
+    out.editor = `${scheme}://file${encodeURI(absUrl)}${line ? ':' + line : ''}`;
+  }
+  if ((mode === 'web' || mode === 'both') && cfg.codeLinks.webBase) {
+    const base = cfg.codeLinks.webBase.replace(/\/?$/, '/');
+    out.web = base + encodeURI(file) + (line ? `#L${line}${lineEnd ? '-L' + lineEnd : ''}` : '');
+  }
+  out.label = file + (line ? `:${line}${lineEnd ? '-' + lineEnd : ''}` : '');
+  out.file = file;
+  out.line = line;
+  return out;
+}
+
+// ---------- hashing / freshness ----------
+
+function listSourceFiles(cfg, rel) {
+  const abs = path.join(cfg.projectRootAbs, rel);
+  if (!fs.existsSync(abs)) return { files: [], missing: true };
+  const st = fs.statSync(abs);
+  if (st.isFile()) return { files: [abs], missing: false };
+  const ex = new Set(cfg.excludeAll.map((e) => e.split('/').pop()));
+  const files = [];
+  (function rec(d) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name.startsWith('.') || ex.has(e.name)) continue;
+      const f = path.join(d, e.name);
+      if (e.isDirectory()) rec(f);
+      else files.push(f);
+    }
+  })(abs);
+  return { files: files.sort(), missing: false };
+}
+
+export function hashSources(cfg, sources) {
+  const h = crypto.createHash('sha1');
+  const missing = [];
+  for (const s of [...sources].sort()) {
+    const { file } = parseCodeRef(s);
+    const { files, missing: miss } = listSourceFiles(cfg, file);
+    if (miss) {
+      missing.push(file);
+      h.update('MISSING:' + file + '\n');
+      continue;
+    }
+    for (const f of files) {
+      h.update(path.relative(cfg.projectRootAbs, f).split(path.sep).join('/') + '\n');
+      h.update(fs.readFileSync(f));
+    }
+  }
+  return { hash: h.digest('hex').slice(0, 16), missing };
+}
+
+/** status: 'fresh' | 'stale' | 'unverified' | 'none' */
+export function freshness(cfg, page) {
+  if (!page.sources.length) return { status: 'none' };
+  const { hash, missing } = hashSources(cfg, page.sources);
+  if (!page.data.sourcesHash) return { status: 'unverified', missing };
+  return { status: page.data.sourcesHash === hash ? 'fresh' : 'stale', missing, hash };
+}
+
+// ---------- git ----------
+
+export function git(cfg, args) {
+  try {
+    return execFileSync('git', args, { cwd: cfg.projectRootAbs, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// ---------- themes ----------
+
+export const REQUIRED_COLORS = ['bg', 'surface', 'text', 'textMuted', 'border', 'accent', 'accentText', 'link'];
+export const OPTIONAL_COLORS = ['heading', 'surfaceAlt', 'codeBg', 'codeText', 'success', 'warning', 'danger', 'info', 'highlight'];
+
+export function loadThemes() {
+  const files = fs.existsSync(THEMES_DIR) ? fs.readdirSync(THEMES_DIR).filter((f) => f.endsWith('.json')).sort() : [];
+  return files.map((f) => {
+    const t = JSON.parse(fs.readFileSync(path.join(THEMES_DIR, f), 'utf8'));
+    t._file = f;
+    if (!t.id) t.id = f.replace(/\.json$/, '');
+    return t;
+  });
+}
+
+export function hexToRgb(hex) {
+  let h = String(hex).trim().replace('#', '');
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) return null;
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+export function rgbToHex([r, g, b]) {
+  return '#' + [r, g, b].map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0')).join('');
+}
+export function mix(a, b, t) {
+  const A = hexToRgb(a);
+  const B = hexToRgb(b);
+  if (!A || !B) return a;
+  return rgbToHex(A.map((v, i) => v + (B[i] - v) * t));
+}
+export function luminance(hex) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return null;
+  const [r, g, b] = rgb.map((v) => {
+    v /= 255;
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export function contrast(a, b) {
+  const la = luminance(a);
+  const lb = luminance(b);
+  if (la == null || lb == null) return null;
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/** Fill optional tokens so every theme exposes the full variable set. */
+export function resolveTheme(t) {
+  const c = { ...(t.colors || {}) };
+  const dark = t.mode === 'dark';
+  c.heading ||= c.text;
+  c.surfaceAlt ||= mix(c.surface, c.text, dark ? 0.08 : 0.05);
+  c.codeBg ||= c.surfaceAlt;
+  c.codeText ||= c.text;
+  c.success ||= dark ? '#5fbf8f' : '#1f7a4d';
+  c.warning ||= dark ? '#e3b04b' : '#8a5a00';
+  c.danger ||= dark ? '#ef7b7b' : '#b42318';
+  c.info ||= c.link;
+  c.highlight ||= mix(c.bg, c.accent, dark ? 0.28 : 0.18);
+  const fonts = {
+    body: "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+    heading: null,
+    mono: "ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace",
+    googleFontsUrl: '',
+    ...(t.fonts || {}),
+  };
+  fonts.heading ||= fonts.body;
+  const typography = { baseSize: 16, lineHeight: 1.65, headingWeight: 700, ...(t.typography || {}) };
+  const layout = { contentMaxWidth: 760, sidebarWidth: 280, radius: 8, ...(t.layout || {}) };
+  const d = t.diagram || {};
+  const diagram = {
+    nodeBg: d.nodeBg || c.surfaceAlt,
+    nodeBorder: d.nodeBorder || c.accent,
+    nodeText: d.nodeText || c.text,
+    lineColor: d.lineColor || c.textMuted,
+    clusterBg: d.clusterBg || c.surface,
+    noteBg: d.noteBg || c.highlight,
+  };
+  return { ...t, colors: c, fonts, typography, layout, diagram };
+}
+
+const kebab = (s) => s.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());
+const px = (v) => (typeof v === 'number' ? v + 'px' : String(v));
+
+export function themeToCss(raw) {
+  const t = resolveTheme(raw);
+  const vars = [];
+  for (const [k, v] of Object.entries(t.colors)) vars.push(`--c-${kebab(k)}:${v}`);
+  for (const [k, v] of Object.entries(t.diagram)) vars.push(`--d-${kebab(k)}:${v}`);
+  vars.push(`--font-body:${t.fonts.body}`, `--font-heading:${t.fonts.heading}`, `--font-mono:${t.fonts.mono}`);
+  vars.push(`--base-size:${px(t.typography.baseSize)}`, `--line-height:${t.typography.lineHeight}`, `--heading-weight:${t.typography.headingWeight}`);
+  vars.push(`--content-max:${px(t.layout.contentMaxWidth)}`, `--sidebar-w:${px(t.layout.sidebarWidth)}`, `--radius:${px(t.layout.radius)}`);
+  vars.push(`color-scheme:${t.mode === 'dark' ? 'dark' : 'light'}`);
+  let css = `:root[data-theme="${t.id}"]{${vars.join(';')}}\n`;
+  if (t.extraCss) css += t.extraCss.trim() + '\n';
+  return css;
+}
+
+// ---------- misc ----------
+
+export function slugify(s) {
+  return String(s)
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/<[^>]+>/g, '')
+    .replace(/[^a-z0-9\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-') || 'sectiune';
+}
+
+export function escapeHtml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+export function wordCount(md) {
+  return md
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/[#>*_`|\-]/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean).length;
+}