@nusoft/nuos-build-catalogue 0.26.0 → 0.28.0

package/dist/cli.js

@@ -427,6 +427,9 @@ Usage:
   nuos-catalogue mode                    print the current operator mode
   nuos-catalogue mode <name>             set operator mode: coaching | standard | developer
 
+  nuos-catalogue render                  regenerate HTML companion views for visual registers
+  nuos-catalogue render <register>       just one register: surfaces | design-system | maps | architecture
+
   nuos-catalogue swarm     status    [--limit=N]  list recent /build-wu runs
   nuos-catalogue swarm     cost      aggregate cost across swarm runs
 
@@ -567,6 +570,17 @@ async function main() {
                 process.exit(code);
             break;
         }
+        case 'render': {
+            const { cmdRender } = await import('./commands/render.js');
+            const code = await cmdRender({
+                cwd: process.cwd(),
+                positional: args.positional[0],
+                buildRootFlag: args.flags['build-root'],
+            });
+            if (code !== 0)
+                process.exit(code);
+            break;
+        }
         case 'swarm': {
             const sub = args.positional[0];
             const { cmdSwarmStatus, cmdSwarmCost } = await import('./commands/swarm.js');

package/dist/commands/render.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `nuos-catalogue render [register]` — regenerate the HTML companion views
+ * for the visual registers (ui-ux, design-system, maps, architecture).
+ *
+ *   nuos-catalogue render                  # render all four
+ *   nuos-catalogue render surfaces         # render just ui-ux/_view.html
+ *   nuos-catalogue render design-system    # render just design-system/_view.html
+ *   nuos-catalogue render maps             # render just maps/_view.html
+ *   nuos-catalogue render architecture     # render just architecture/_view.html
+ *
+ * Companion HTML files are *generated artefacts*. The canonical source for
+ * every register stays markdown — every agent (architect, coder, reviewer)
+ * reads markdown. The HTML exists so the operator can review inherently visual
+ * artefacts in their natural medium.
+ */
+export interface RenderCommandOptions {
+    cwd?: string;
+    /** Optional register name (`surfaces`, `design-system`, `maps`, `architecture`). */
+    positional?: string;
+    /** Override for --build-root flag. */
+    buildRootFlag?: string | boolean;
+    /** Override "now" for deterministic test output. */
+    now?: () => Date;
+}
+export declare function cmdRender(options?: RenderCommandOptions): Promise<number>;

package/dist/commands/render.js

@@ -0,0 +1,40 @@
+/**
+ * `nuos-catalogue render [register]` — regenerate the HTML companion views
+ * for the visual registers (ui-ux, design-system, maps, architecture).
+ *
+ *   nuos-catalogue render                  # render all four
+ *   nuos-catalogue render surfaces         # render just ui-ux/_view.html
+ *   nuos-catalogue render design-system    # render just design-system/_view.html
+ *   nuos-catalogue render maps             # render just maps/_view.html
+ *   nuos-catalogue render architecture     # render just architecture/_view.html
+ *
+ * Companion HTML files are *generated artefacts*. The canonical source for
+ * every register stays markdown — every agent (architect, coder, reviewer)
+ * reads markdown. The HTML exists so the operator can review inherently visual
+ * artefacts in their natural medium.
+ */
+import path from 'node:path';
+import { resolveBuildRoot } from '../path-resolution.js';
+import { RENDERABLE_REGISTERS, runRender } from '../render/run.js';
+export async function cmdRender(options = {}) {
+    const buildRoot = resolveBuildRoot(options.buildRootFlag, { cwd: options.cwd ?? process.cwd() });
+    let only;
+    if (options.positional && options.positional !== 'all') {
+        if (!RENDERABLE_REGISTERS.includes(options.positional)) {
+            console.error(`unknown register: ${options.positional}`);
+            console.error(`available: ${RENDERABLE_REGISTERS.join(', ')}`);
+            return 1;
+        }
+        only = [options.positional];
+    }
+    const report = await runRender({ buildRoot, only, now: options.now });
+    for (const r of report.results) {
+        const status = r.written ? '✓' : '·';
+        const rel = path.relative(process.cwd(), r.outPath);
+        console.log(`  ${status} ${r.register.padEnd(16)} ${r.detail.padEnd(20)} ${r.written ? rel : ''}`);
+    }
+    const writtenCount = report.results.filter((r) => r.written).length;
+    console.log('');
+    console.log(`${writtenCount}/${report.results.length} register${report.results.length === 1 ? '' : 's'} rendered.`);
+    return 0;
+}

package/dist/render/architecture.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render the `architecture/` register as a module gallery with cross-links.
+ *
+ * Each module becomes a card showing its responsibility (one paragraph), the
+ * personas/modules it depends on, and the contracts it owns. The cards link
+ * to each other where dependencies are named, so the operator can navigate the
+ * module graph visually instead of by grep.
+ */
+export interface ArchitectureRenderResult {
+    written: boolean;
+    outPath: string;
+    moduleCount: number;
+}
+export declare function renderArchitecture(opts: {
+    buildRoot: string;
+    projectName: string;
+    generatedAt: string;
+}): Promise<ArchitectureRenderResult>;

package/dist/render/architecture.js

@@ -0,0 +1,74 @@
+/**
+ * Render the `architecture/` register as a module gallery with cross-links.
+ *
+ * Each module becomes a card showing its responsibility (one paragraph), the
+ * personas/modules it depends on, and the contracts it owns. The cards link
+ * to each other where dependencies are named, so the operator can navigate the
+ * module graph visually instead of by grep.
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSections, isPlaceholder } from './parser.js';
+import { pageWrapper, card, emptyState, escapeHtml, renderProse, } from './html.js';
+const SKIP_FILES = new Set(['_index.md', 'module-template.md']);
+export async function renderArchitecture(opts) {
+    const dir = path.join(opts.buildRoot, 'architecture');
+    const outPath = path.join(dir, '_view.html');
+    if (!existsSync(dir)) {
+        return { written: false, outPath, moduleCount: 0 };
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    const modules = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (SKIP_FILES.has(entry.name))
+            continue;
+        const md = await readFile(path.join(dir, entry.name), 'utf8');
+        if (isPlaceholder(md))
+            continue;
+        const titleMatch = md.match(/^#\s+(.+)$/m);
+        modules.push({
+            file: entry.name,
+            slug: entry.name.replace(/\.md$/, ''),
+            title: titleMatch ? titleMatch[1].trim() : entry.name,
+            sections: parseSections(md),
+        });
+    }
+    modules.sort((a, b) => a.title.localeCompare(b.title));
+    const body = modules.length === 0
+        ? card('No modules filed yet', emptyState('Phase B of planning produces this content.'))
+        : [renderModuleIndex(modules), ...modules.map(renderModuleCard)].join('');
+    const html = pageWrapper({
+        title: 'Architecture',
+        projectName: opts.projectName,
+        generatedAt: opts.generatedAt,
+        sourceNote: '<code>docs/build/architecture/</code>',
+        body,
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(outPath, html, 'utf8');
+    return { written: true, outPath, moduleCount: modules.length };
+}
+function renderModuleIndex(modules) {
+    const items = modules
+        .map((m) => `<li><a href="#${escapeHtml(m.slug)}">${escapeHtml(m.title)}</a></li>`)
+        .join('');
+    return card('Modules', `<ul class="sitemap-list">${items}</ul>`);
+}
+function renderModuleCard(m) {
+    const sectionBlocks = [];
+    for (const [heading, body] of m.sections) {
+        if (heading === '' || heading.toLowerCase() === 'notes')
+            continue;
+        const rendered = body.trim() ? renderProse(body) : '';
+        if (!rendered)
+            continue;
+        sectionBlocks.push(`<h4>${escapeHtml(heading)}</h4>${rendered}`);
+    }
+    return `<section id="${escapeHtml(m.slug)}" class="card">
+    <h3>${escapeHtml(m.title)}</h3>
+    <div class="card__body">${sectionBlocks.join('')}</div>
+  </section>`;
+}

package/dist/render/design-system.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Render the `design-system/` register as an interactive companion gallery.
+ *
+ * What gets rendered:
+ *   - Colour tokens — as visual swatches with the hex value beside the name.
+ *   - Type scale — each step rendered at its declared px size with its line-height
+ *     and weight applied so the operator sees the real shape, not a description.
+ *   - Spacing scale — rendered as horizontal bars at the actual pixel widths.
+ *   - Radius & elevation — small boxes showing the corner radius applied.
+ *   - Motion — table only (no animation; would push complexity past MVP scope).
+ *   - Components + patterns — name list with first-paragraph summary.
+ *   - Voice + accessibility — first-paragraph summary blocks.
+ *
+ * Token files use GFM tables with a `Token` column and a value column. The parser
+ * looks for either a `Hex` / `Value` / `Size` / `Used for` column shape and falls
+ * back to "list the table verbatim" when the shape isn't recognised.
+ */
+export interface DesignSystemRenderResult {
+    written: boolean;
+    outPath: string;
+}
+export declare function renderDesignSystem(opts: {
+    buildRoot: string;
+    projectName: string;
+    generatedAt: string;
+}): Promise<DesignSystemRenderResult>;

package/dist/render/design-system.js

@@ -0,0 +1,308 @@
+/**
+ * Render the `design-system/` register as an interactive companion gallery.
+ *
+ * What gets rendered:
+ *   - Colour tokens — as visual swatches with the hex value beside the name.
+ *   - Type scale — each step rendered at its declared px size with its line-height
+ *     and weight applied so the operator sees the real shape, not a description.
+ *   - Spacing scale — rendered as horizontal bars at the actual pixel widths.
+ *   - Radius & elevation — small boxes showing the corner radius applied.
+ *   - Motion — table only (no animation; would push complexity past MVP scope).
+ *   - Components + patterns — name list with first-paragraph summary.
+ *   - Voice + accessibility — first-paragraph summary blocks.
+ *
+ * Token files use GFM tables with a `Token` column and a value column. The parser
+ * looks for either a `Hex` / `Value` / `Size` / `Used for` column shape and falls
+ * back to "list the table verbatim" when the shape isn't recognised.
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSections, parseTable, firstParagraph, isPlaceholder, extractHexColours, } from './parser.js';
+import { pageWrapper, card, emptyState, escapeHtml, renderInlineMarkdown, renderProse, } from './html.js';
+export async function renderDesignSystem(opts) {
+    const dir = path.join(opts.buildRoot, 'design-system');
+    const outPath = path.join(dir, '_view.html');
+    if (!existsSync(dir)) {
+        return { written: false, outPath };
+    }
+    const blocks = [];
+    blocks.push(await renderTokenFile(dir, 'tokens-colour.md', renderColourTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-typography.md', renderTypeTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-spacing.md', renderSpacingTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-radius-elevation.md', renderRadiusTokens));
+    blocks.push(await renderTokenFile(dir, 'tokens-motion.md', renderMotionTokens));
+    blocks.push(await renderListing(path.join(dir, 'components'), 'Components'));
+    blocks.push(await renderListing(path.join(dir, 'patterns'), 'Patterns'));
+    blocks.push(await renderPlainFile(dir, 'voice.md', 'Voice'));
+    blocks.push(await renderPlainFile(dir, 'accessibility.md', 'Accessibility'));
+    const body = blocks.filter(Boolean).join('\n');
+    const html = pageWrapper({
+        title: 'Design system',
+        projectName: opts.projectName,
+        generatedAt: opts.generatedAt,
+        sourceNote: '<code>docs/build/design-system/</code>',
+        body: body || card('Design system not yet populated', emptyState('Phase C of planning populates this register.')),
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(outPath, html, 'utf8');
+    return { written: true, outPath };
+}
+async function renderTokenFile(dir, filename, renderer) {
+    const filePath = path.join(dir, filename);
+    if (!existsSync(filePath))
+        return '';
+    const md = await readFile(filePath, 'utf8');
+    if (isPlaceholder(md)) {
+        return card(prettyTitle(filename), emptyState(`Not yet filled in (${filename}).`), { tone: 'muted' });
+    }
+    const sections = parseSections(md);
+    return renderer(sections, md);
+}
+function renderColourTokens(sections, md) {
+    const swatchBlocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenColumn = findColumn(table, ['Token', 'Name']);
+        const hexColumn = findColumn(table, ['Hex', 'Value']);
+        const useColumn = findColumn(table, ['Used for', 'Role', 'Description']);
+        if (tokenColumn === -1)
+            continue;
+        const swatches = table.rows
+            .map((row) => {
+            const token = stripInline(row[tokenColumn] ?? '');
+            const value = stripInline(row[hexColumn === -1 ? 1 : hexColumn] ?? '');
+            const purpose = useColumn === -1 ? '' : row[useColumn] ?? '';
+            const hexes = extractHexColours(value);
+            const hex = hexes[0];
+            if (!hex)
+                return '';
+            return `<div class="swatch">
+          <div class="swatch__chip" style="background:${escapeHtml(hex)}"></div>
+          <div class="swatch__meta">
+            <code>${escapeHtml(token)}</code>
+            <small>${escapeHtml(hex)}${purpose ? ` · ${escapeHtml(stripInline(purpose))}` : ''}</small>
+          </div>
+        </div>`;
+        })
+            .filter(Boolean)
+            .join('');
+        if (swatches) {
+            swatchBlocks.push(`<h4>${escapeHtml(heading)}</h4>${swatches}`);
+        }
+    }
+    if (swatchBlocks.length === 0) {
+        return card('Colour tokens', renderProse(md));
+    }
+    return card('Colour tokens', swatchBlocks.join(''));
+}
+function renderTypeTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenCol = findColumn(table, ['Token', 'Name']);
+        const sizeCol = findColumn(table, ['Size']);
+        const lineCol = findColumn(table, ['Line height']);
+        const weightCol = findColumn(table, ['Weight']);
+        const useCol = findColumn(table, ['Used for']);
+        if (tokenCol === -1)
+            continue;
+        if (sizeCol !== -1) {
+            const samples = table.rows
+                .map((row) => {
+                const token = stripInline(row[tokenCol] ?? '');
+                const size = stripInline(row[sizeCol] ?? '');
+                const line = lineCol === -1 ? '' : stripInline(row[lineCol] ?? '');
+                const weight = weightCol === -1 ? '' : stripInline(row[weightCol] ?? '');
+                const use = useCol === -1 ? '' : stripInline(row[useCol] ?? '');
+                const cssSize = parsePxOrRem(size) ?? '16px';
+                const cssLine = parseUnitless(line) ?? '1.4';
+                const cssWeight = parseWeight(weight) ?? '400';
+                return `<div class="type-row">
+            <span class="type-sample" style="font-size:${cssSize};line-height:${cssLine};font-weight:${cssWeight}">The quick brown fox</span>
+            <small><code>${escapeHtml(token)}</code> · ${escapeHtml([size, weight, use].filter(Boolean).join(' · '))}</small>
+          </div>`;
+            })
+                .join('');
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${samples}`);
+        }
+        else {
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+        }
+    }
+    if (blocks.length === 0)
+        return card('Typography', renderProse(md));
+    return card('Typography', blocks.join(''));
+}
+function renderSpacingTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenCol = findColumn(table, ['Token', 'Name', 'Step']);
+        const valCol = findColumn(table, ['Value', 'Size', 'px']);
+        if (tokenCol === -1 || valCol === -1) {
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+            continue;
+        }
+        const bars = table.rows
+            .map((row) => {
+            const token = stripInline(row[tokenCol] ?? '');
+            const value = stripInline(row[valCol] ?? '');
+            const px = parsePx(value);
+            if (!px)
+                return '';
+            return `<div class="spacing-row">
+          <small><code>${escapeHtml(token)}</code> · ${escapeHtml(value)}</small>
+          <div class="spacing-bar" style="width:${px}px;max-width:100%"></div>
+        </div>`;
+        })
+            .filter(Boolean)
+            .join('');
+        blocks.push(`<h4>${escapeHtml(heading)}</h4>${bars || renderTableAsTokens(table)}`);
+    }
+    if (blocks.length === 0)
+        return card('Spacing', renderProse(md));
+    return card('Spacing', blocks.join(''));
+}
+function renderRadiusTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (!table)
+            continue;
+        const tokenCol = findColumn(table, ['Token', 'Name']);
+        const valCol = findColumn(table, ['Value', 'Radius', 'Size']);
+        if (tokenCol === -1 || valCol === -1) {
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+            continue;
+        }
+        const examples = table.rows
+            .map((row) => {
+            const token = stripInline(row[tokenCol] ?? '');
+            const value = stripInline(row[valCol] ?? '');
+            const px = parsePx(value);
+            return `<div class="radius-row">
+          <div class="radius-chip" style="border-radius:${px ?? 0}px"></div>
+          <small><code>${escapeHtml(token)}</code> · ${escapeHtml(value)}</small>
+        </div>`;
+        })
+            .join('');
+        blocks.push(`<h4>${escapeHtml(heading)}</h4>${examples}`);
+    }
+    if (blocks.length === 0)
+        return card('Radius & elevation', renderProse(md));
+    return card('Radius & elevation', blocks.join(''));
+}
+function renderMotionTokens(sections, md) {
+    const blocks = [];
+    for (const [heading, body] of sections) {
+        if (heading === '')
+            continue;
+        const table = parseTable(body);
+        if (table)
+            blocks.push(`<h4>${escapeHtml(heading)}</h4>${renderTableAsTokens(table)}`);
+    }
+    if (blocks.length === 0)
+        return card('Motion', renderProse(md));
+    return card('Motion', blocks.join(''));
+}
+// ---------------------------------------------------------------------------
+// Components / patterns listing
+// ---------------------------------------------------------------------------
+async function renderListing(dir, title) {
+    if (!existsSync(dir))
+        return '';
+    const entries = await readdir(dir, { withFileTypes: true });
+    const items = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (entry.name === '_index.md' || entry.name === '_template.md')
+            continue;
+        const md = await readFile(path.join(dir, entry.name), 'utf8');
+        if (isPlaceholder(md))
+            continue;
+        const titleMatch = md.match(/^#\s+(.+)$/m);
+        const name = titleMatch ? titleMatch[1].trim() : entry.name;
+        const summary = firstParagraph(md);
+        items.push(`<div class="listing-item">
+        <strong>${escapeHtml(name)}</strong>
+        ${summary ? `<p>${renderInlineMarkdown(summary)}</p>` : ''}
+        <small><code>${escapeHtml(entry.name)}</code></small>
+      </div>`);
+    }
+    if (items.length === 0)
+        return card(title, emptyState('None filed yet.'), { tone: 'muted' });
+    return card(title, items.join(''));
+}
+async function renderPlainFile(dir, filename, title) {
+    const filePath = path.join(dir, filename);
+    if (!existsSync(filePath))
+        return '';
+    const md = await readFile(filePath, 'utf8');
+    if (isPlaceholder(md)) {
+        return card(title, emptyState(`Not yet filled in (${filename}).`), { tone: 'muted' });
+    }
+    const summary = firstParagraph(md);
+    return card(title, summary ? `<p>${renderInlineMarkdown(summary)}</p>` : renderProse(md));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function prettyTitle(filename) {
+    return filename
+        .replace(/\.md$/, '')
+        .replace(/^tokens-/, '')
+        .replace(/-/g, ' ')
+        .replace(/^./, (c) => c.toUpperCase());
+}
+function findColumn(table, candidates) {
+    const lower = table.headers.map((h) => h.toLowerCase());
+    for (const c of candidates) {
+        const idx = lower.indexOf(c.toLowerCase());
+        if (idx >= 0)
+            return idx;
+    }
+    return -1;
+}
+function stripInline(s) {
+    return s.replace(/^`(.+)`$/, '$1').replace(/\\\|/g, '|').trim();
+}
+function renderTableAsTokens(table) {
+    const head = table.headers.map((h) => `<th>${escapeHtml(h)}</th>`).join('');
+    const rows = table.rows
+        .map((row) => row.map((cell) => `<td>${renderInlineMarkdown(cell)}</td>`).join(''))
+        .map((r) => `<tr>${r}</tr>`)
+        .join('');
+    return `<table class="tokens-table"><thead><tr>${head}</tr></thead><tbody>${rows}</tbody></table>`;
+}
+function parsePxOrRem(s) {
+    const m = s.match(/(\d+(?:\.\d+)?)(px|rem|em)/);
+    return m ? `${m[1]}${m[2]}` : null;
+}
+function parsePx(s) {
+    const m = s.match(/(\d+(?:\.\d+)?)\s*px/i);
+    return m ? Number(m[1]) : null;
+}
+function parseUnitless(s) {
+    const m = s.match(/^(\d+(?:\.\d+)?)$/);
+    return m ? m[1] : null;
+}
+function parseWeight(s) {
+    const m = s.match(/\b(100|200|300|400|500|600|700|800|900)\b/);
+    return m ? m[1] : null;
+}

package/dist/render/html.d.ts

@@ -0,0 +1,47 @@
+/**
+ * HTML primitives shared across the per-register renderers.
+ *
+ * Design notes:
+ *   - Pure static HTML. No JS, no framework, no external CSS or fonts.
+ *   - One self-contained file per register so the operator can open it directly
+ *     in a browser or share it without a build step.
+ *   - Inline styles in a single `<style>` block; CSS variables for the few values
+ *     the renderers care about (token swatches, type previews) so they can be
+ *     overridden per-block without restating the rule set.
+ *   - The visual language is deliberately neutral — cards, restrained spacing,
+ *     system fonts. Consumer projects with strong design opinions can post-process
+ *     or skip companion rendering; the default isn't trying to be a brand.
+ */
+export declare function escapeHtml(s: string): string;
+/**
+ * Convert a single line of markdown to inline HTML — `code`, **bold**, *italic*,
+ * and [text](url) links. Block-level constructs (headings, lists, tables) are not
+ * processed; callers parse those structurally and use this helper on the cells.
+ */
+export declare function renderInlineMarkdown(s: string): string;
+/**
+ * Render a multi-line markdown block as paragraphs. Lists become `<ul>`/`<ol>`.
+ * Sub-headings (### / ####) become `<h4>`. Tables are skipped — the renderer should
+ * have parsed those structurally before getting here.
+ */
+export declare function renderProse(md: string): string;
+export declare function card(title: string, body: string, opts?: {
+    tone?: 'default' | 'muted';
+}): string;
+export declare function grid(items: string[], opts?: {
+    columns?: 'auto' | 'wide';
+}): string;
+export declare function emptyState(message: string): string;
+/**
+ * Wrap rendered fragments into a self-contained HTML document.
+ *
+ * The doc carries an explicit "generated, do not edit" banner so the operator
+ * doesn't try to hand-edit the file — the source of truth is the markdown.
+ */
+export declare function pageWrapper(opts: {
+    title: string;
+    projectName: string;
+    generatedAt: string;
+    sourceNote: string;
+    body: string;
+}): string;