thachvd-kit 1.0.37 → 1.0.39

package/bin/spec-site.js

@@ -0,0 +1,639 @@
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const specState = require('./spec-state');
+
+const DEFAULT_SITE_DIR = '_site';
+const DEFAULT_PORT = 4173;
+const DEFAULT_HOST = '127.0.0.1';
+const TICK = String.fromCharCode(96);
+const FENCE = TICK + TICK + TICK;
+
+function portable(value) {
+    return value.split(path.sep).join('/');
+}
+
+function escapeHtml(value) {
+    return String(value == null ? '' : value)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+function inlineMarkdown(value) {
+    let text = escapeHtml(value);
+    const parts = text.split(TICK);
+    if (parts.length > 1) {
+        text = parts.map(function(part, index) {
+            return index % 2 ? '<code>' + part + '</code>' : part;
+        }).join('');
+    }
+    text = text.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+    text = text.replace(/\*([^*]+)\*/g, '<em>$1</em>');
+    return text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, function(_m, label, href) {
+        const raw = String(href || '').trim();
+        const safe = /^(https?:|mailto:|#|\.{0,2}\/)/i.test(raw) ? escapeHtml(raw) : '#';
+        return '<a href="' + safe + '">' + label + '</a>';
+    });
+}
+
+function isTableSeparator(line) {
+    return /^\s*\|?[\s:|-]+\|[\s:|-|]*\|?\s*$/.test(line || '') && String(line || '').includes('-');
+}
+
+function splitTableRow(line) {
+    return String(line || '').trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(function(cell) {
+        return cell.trim();
+    });
+}
+
+function markdownToHtml(markdown) {
+    const lines = String(markdown || '').replace(/\r\n/g, '\n').split('\n');
+    const out = [];
+    let paragraph = [];
+    let list = null;
+    let items = [];
+    let code = null;
+    let language = '';
+
+    function flushParagraph() {
+        if (!paragraph.length) return;
+        out.push('<p>' + inlineMarkdown(paragraph.join(' ')) + '</p>');
+        paragraph = [];
+    }
+    function flushList() {
+        if (!list) return;
+        out.push('<' + list + '>' + items.map(function(item) {
+            return '<li>' + inlineMarkdown(item) + '</li>';
+        }).join('') + '</' + list + '>');
+        list = null;
+        items = [];
+    }
+    function flush() {
+        flushParagraph();
+        flushList();
+    }
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (code !== null) {
+            if (line.indexOf(FENCE) === 0) {
+                const body = escapeHtml(code.join('\n'));
+                out.push(language.toLowerCase() === 'mermaid'
+                    ? '<pre class="mermaid">' + body + '</pre>'
+                    : '<pre><code' + (language ? ' class="language-' + escapeHtml(language) + '"' : '') + '>' + body + '</code></pre>');
+                code = null;
+                language = '';
+            } else {
+                code.push(line);
+            }
+            continue;
+        }
+
+        if (line.indexOf(FENCE) === 0) {
+            flush();
+            code = [];
+            language = line.slice(FENCE.length).trim();
+            continue;
+        }
+
+        const heading = line.match(/^(#{1,6})\s+(.+)$/);
+        if (heading) {
+            flush();
+            const level = heading[1].length;
+            const title = heading[2].trim();
+            out.push('<h' + level + '>' + inlineMarkdown(title) + '</h' + level + '>');
+            continue;
+        }
+        if (line.trim() === '---') {
+            flush();
+            out.push('<hr>');
+            continue;
+        }
+        if (line.indexOf('> ') === 0) {
+            flush();
+            out.push('<blockquote>' + inlineMarkdown(line.slice(2)) + '</blockquote>');
+            continue;
+        }
+
+        if (line.includes('|') && i + 1 < lines.length && isTableSeparator(lines[i + 1])) {
+            flush();
+            const headers = splitTableRow(line);
+            i += 1;
+            const rows = [];
+            while (i + 1 < lines.length && lines[i + 1].includes('|') && lines[i + 1].trim()) {
+                rows.push(splitTableRow(lines[++i]));
+            }
+            out.push('<div class="table-wrap"><table><thead><tr>' +
+                headers.map(function(cell) { return '<th>' + inlineMarkdown(cell) + '</th>'; }).join('') +
+                '</tr></thead><tbody>' +
+                rows.map(function(row) {
+                    return '<tr>' + headers.map(function(_header, index) {
+                        return '<td>' + inlineMarkdown(row[index] || '') + '</td>';
+                    }).join('') + '</tr>';
+                }).join('') +
+                '</tbody></table></div>');
+            continue;
+        }
+
+        const unordered = line.match(/^\s*[-*+]\s+(.+)$/);
+        const ordered = line.match(/^\s*\d+\.\s+(.+)$/);
+        if (unordered || ordered) {
+            flushParagraph();
+            const type = ordered ? 'ol' : 'ul';
+            if (list && list !== type) flushList();
+            list = type;
+            items.push((ordered || unordered)[1]);
+            continue;
+        }
+
+        if (!line.trim()) {
+            flush();
+            continue;
+        }
+        paragraph.push(line.trim());
+    }
+    if (code !== null) out.push('<pre><code>' + escapeHtml(code.join('\n')) + '</code></pre>');
+    flush();
+    return out.join('\n');
+}
+
+function readText(filePath) {
+    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+}
+
+function readJson(filePath) {
+    if (!fs.existsSync(filePath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (error) {
+        return { __error: error.message };
+    }
+}
+
+function firstHeading(markdown, fallback) {
+    const match = String(markdown || '').match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : fallback;
+}
+
+function listMarkdownFiles(directory) {
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+        .filter(function(entry) { return entry.isFile() && entry.name.toLowerCase().endsWith('.md'); })
+        .map(function(entry) { return path.join(directory, entry.name); })
+        .sort(function(a, b) { return path.basename(a).localeCompare(path.basename(b)); });
+}
+
+function safeCapabilitySlug(value) {
+    const slug = String(value || '');
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) {
+        throw new Error('unsafe capability slug for HTML output: ' + value);
+    }
+    return slug;
+}
+
+function resolveOutputRoot(workspaceRoot, manifest, outputOption) {
+    const workspace = path.resolve(workspaceRoot);
+    const specRoot = path.resolve(workspace, manifest.spec_root);
+    const requested = outputOption ? path.resolve(workspace, outputOption) : path.join(specRoot, DEFAULT_SITE_DIR);
+    const relative = path.relative(workspace, requested);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('site output must stay inside the workspace root');
+    }
+    if (requested === workspace || requested === specRoot) {
+        throw new Error('site output cannot replace the workspace root or spec root');
+    }
+    return requested;
+}
+
+function buildSystemModel(workspaceRoot, manifest, options) {
+    options = options || {};
+    const specRoot = path.resolve(workspaceRoot, manifest.spec_root);
+    const rawVerification = readJson(path.join(specRoot, '_meta', 'verification.json'));
+    const progress = readJson(path.join(specRoot, '_meta', 'reverse-progress.json'));
+    let verification = rawVerification;
+    let verificationError = rawVerification && rawVerification.__error ? rawVerification.__error : null;
+    if (verification && !verificationError) {
+        try {
+            specState.validateVerification(manifest, verification);
+        } catch (error) {
+            verificationError = error.message;
+            verification = null;
+        }
+    }
+    const review = readText(path.join(specRoot, '_meta', 'review.md'));
+    let drift = Object.prototype.hasOwnProperty.call(options, 'driftReport') ? options.driftReport : null;
+    let driftError = null;
+    if (!Object.prototype.hasOwnProperty.call(options, 'driftReport') && verification && !verification.__error) {
+        try {
+            drift = specState.checkSpecDrift(workspaceRoot, manifest, verification);
+        } catch (error) {
+            driftError = error.message;
+        }
+    }
+
+    const verificationCaps = verification && !verification.__error ? verification.capabilities || {} : {};
+    const progressCaps = progress && !progress.__error ? progress.capabilities || {} : {};
+    const capabilityRoot = path.join(specRoot, 'capabilities');
+    const slugs = new Set(Object.keys(verificationCaps).concat(Object.keys(progressCaps)));
+    if (fs.existsSync(capabilityRoot)) {
+        fs.readdirSync(capabilityRoot, { withFileTypes: true }).forEach(function(entry) {
+            if (entry.isDirectory()) slugs.add(entry.name);
+        });
+    }
+
+    const capabilities = Array.from(slugs).sort().map(function(rawSlug) {
+        const slug = safeCapabilitySlug(rawSlug);
+        const root = path.join(capabilityRoot, slug);
+        const prd = readText(path.join(root, 'prd.md'));
+        const design = readText(path.join(root, 'design.md'));
+        const verified = verificationCaps[slug] || null;
+        const progressed = progressCaps[slug] || null;
+        const driftState = drift && drift.capabilities ? drift.capabilities[slug] || null : null;
+        const sourcePaths = (verified && verified.source_paths) || (progressed && progressed.source_paths) || {};
+        let status = verified ? verified.status : 'unverified';
+        if (driftState && driftState.status === 'stale') status = 'stale';
+        else if (driftState && driftState.status === 'unknown') status = 'unknown';
+        return {
+            slug: slug,
+            title: (verified && verified.title) || (progressed && progressed.title) || firstHeading(prd, firstHeading(design, slug)),
+            verification_status: verified ? verified.status : 'unverified',
+            drift_status: driftState ? driftState.status : 'unknown',
+            status: status,
+            repos: Object.keys(sourcePaths).sort(),
+            source_paths: sourcePaths,
+            evidence: verified ? verified.evidence || {} : {},
+            prd_html: markdownToHtml(prd || ''),
+            design_html: markdownToHtml(design || '')
+        };
+    });
+
+    function docs(name) {
+        return listMarkdownFiles(path.join(specRoot, name)).map(function(filePath) {
+            const markdown = readText(filePath) || '';
+            return {
+                name: path.basename(filePath, '.md'),
+                title: firstHeading(markdown, path.basename(filePath, '.md')),
+                html: markdownToHtml(markdown)
+            };
+        });
+    }
+
+    return {
+        generated_at: new Date().toISOString(),
+        system: { name: manifest.name, language: manifest.language, profile: manifest.profile, spec_root: manifest.spec_root },
+        repositories: manifest.repos.map(function(repo) { return { name: repo.name, path: repo.path }; }),
+        capabilities: capabilities,
+        architecture: docs('architecture'),
+        flows: docs('flows'),
+        contracts: docs('contracts'),
+        review_html: markdownToHtml(review || ''),
+        verification: verification && !verification.__error ? {
+            verified_at: verification.verified_at || null,
+            repositories: verification.repositories || {}
+        } : null,
+        verification_error: verificationError,
+        progress_error: progress && progress.__error ? progress.__error : null,
+        drift_error: driftError,
+        counts: {
+            repos: manifest.repos.length,
+            capabilities: capabilities.length,
+            verified: capabilities.filter(function(item) { return item.verification_status === 'verified'; }).length,
+            stale: capabilities.filter(function(item) { return item.drift_status === 'stale'; }).length,
+            needs_review: capabilities.filter(function(item) { return item.verification_status === 'needs_review'; }).length,
+            blocked: capabilities.filter(function(item) { return item.verification_status === 'blocked'; }).length,
+            unverified: capabilities.filter(function(item) { return item.verification_status === 'unverified'; }).length
+        }
+    };
+}
+
+function copy(model) {
+    if (model.system.language === 'vi') {
+        return {
+            overview: 'Tổng quan',
+            architecture: 'Kiến trúc',
+            capabilities: 'Capability',
+            flows: 'Luồng',
+            contracts: 'Contract',
+            health: 'Sức khỏe spec',
+            repositories: 'Repository',
+            verified: 'Đã xác minh',
+            stale: 'Đã lệch',
+            needsReview: 'Cần review',
+            blocked: 'Bị chặn',
+            unverified: 'Chưa xác minh',
+            capabilityHealth: 'Tình trạng capability',
+            viewAll: 'Xem tất cả',
+            latestReview: 'Review gần nhất',
+            noMapping: 'Chưa có mapping repository',
+            details: 'Chi tiết capability',
+            sourceMap: 'Source map',
+            evidence: 'Evidence',
+            drift: 'Drift',
+            filter: 'Lọc capability hoặc repository…',
+            systemExplorer: 'BẢN ĐỒ HỆ THỐNG AS-IS',
+            explorerDescription: 'Được tạo từ Markdown spec và metadata xác minh. HTML chỉ là lớp hiển thị, không phải source of truth.',
+            verification: 'Xác minh',
+            capabilityStatus: 'Trạng thái capability',
+            noCapabilities: 'Chưa có capability spec.'
+        };
+    }
+    return {
+        overview: 'Overview',
+        architecture: 'Architecture',
+        capabilities: 'Capabilities',
+        flows: 'Flows',
+        contracts: 'Contracts',
+        health: 'Spec health',
+        repositories: 'Repositories',
+        verified: 'Verified',
+        stale: 'Stale',
+        needsReview: 'Needs review',
+        blocked: 'Blocked',
+        unverified: 'Unverified',
+        capabilityHealth: 'Capability health',
+        viewAll: 'View all',
+        latestReview: 'Latest review',
+        noMapping: 'No repository mapping',
+        details: 'Capability details',
+        sourceMap: 'Source map',
+        evidence: 'Evidence',
+        drift: 'Drift',
+        filter: 'Filter capabilities or repositories…',
+        systemExplorer: 'AS-IS SYSTEM EXPLORER',
+        explorerDescription: 'Generated from Markdown specs and verification metadata. HTML is a read-only presentation layer.',
+        verification: 'Verification',
+        capabilityStatus: 'Capability status',
+        noCapabilities: 'No capability specs yet.'
+    };
+}
+
+function badge(status) {
+    const tone = ['verified', 'current'].includes(status) ? 'ok' :
+        ['stale', 'needs_review', 'unknown'].includes(status) ? 'warn' :
+        status === 'blocked' ? 'bad' : 'neutral';
+    return '<span class="badge ' + tone + '">' + escapeHtml(String(status || 'unknown').replace(/_/g, ' ')) + '</span>';
+}
+
+function shell(title, model, active, body, depth) {
+    depth = depth || 0;
+    const prefix = depth ? '../'.repeat(depth) : '';
+    const text = copy(model);
+    const links = [
+        ['index.html', text.overview, 'overview'],
+        ['architecture.html', text.architecture, 'architecture'],
+        ['capabilities.html', text.capabilities, 'capabilities'],
+        ['flows.html', text.flows, 'flows'],
+        ['contracts.html', text.contracts, 'contracts'],
+        ['health.html', text.health, 'health']
+    ];
+    const nav = links.map(function(item) {
+        return '<a class="' + (active === item[2] ? 'active' : '') + '" href="' + prefix + item[0] + '">' + item[1] + '</a>';
+    }).join('');
+    return '<!doctype html><html lang="' + escapeHtml(model.system.language || 'en') + '"><head>' +
+        '<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
+        '<title>' + escapeHtml(title) + ' · ' + escapeHtml(model.system.name) + '</title>' +
+        '<link rel="stylesheet" href="' + prefix + 'assets/site.css"><script defer src="' + prefix + 'assets/app.js"></script></head><body>' +
+        '<header class="topbar"><a class="brand" href="' + prefix + 'index.html">' + escapeHtml(model.system.name) + '</a>' +
+        '<span class="top-meta">' + escapeHtml(model.system.profile) + ' · ' + escapeHtml(model.generated_at.slice(0, 19).replace('T', ' ')) + '</span></header>' +
+        '<div class="layout"><nav class="sidebar">' + nav + '</nav><main class="content">' + body + '</main></div></body></html>';
+}
+
+function metric(label, value, tone) {
+    return '<div class="metric ' + (tone || '') + '"><div class="metric-value">' + escapeHtml(value) + '</div><div class="metric-label">' + escapeHtml(label) + '</div></div>';
+}
+
+function renderOverview(model) {
+    const text = copy(model);
+    const repos = model.repositories.map(function(repo) {
+        return '<div class="repo-card"><strong>' + escapeHtml(repo.name) + '</strong><code>' + escapeHtml(repo.path) + '</code></div>';
+    }).join('');
+    const caps = model.capabilities.slice(0, 12).map(function(cap) {
+        return '<a class="cap-row" href="capability/' + encodeURIComponent(cap.slug) + '.html"><span><strong>' +
+            escapeHtml(cap.title) + '</strong><small>' + escapeHtml(cap.repos.join(', ') || text.noMapping) +
+            '</small></span>' + badge(cap.status) + '</a>';
+    }).join('') || '<p class="muted">' + text.noCapabilities + '</p>';
+    return shell('Overview', model, 'overview',
+        '<section class="hero"><p class="eyebrow">' + text.systemExplorer + '</p><h1>' + escapeHtml(model.system.name) +
+        '</h1><p>' + text.explorerDescription + '</p></section>' +
+        '<section class="metrics">' + metric(text.repositories, model.counts.repos) + metric(text.capabilities, model.counts.capabilities) +
+        metric(text.verified, model.counts.verified, 'good') + metric(text.stale, model.counts.stale, model.counts.stale ? 'warning' : '') +
+        metric(text.needsReview, model.counts.needs_review) + metric(text.blocked, model.counts.blocked) + '</section>' +
+        '<section><div class="section-head"><h2>' + text.repositories + '</h2><a href="architecture.html">' + text.architecture + ' →</a></div><div class="repo-grid">' + repos + '</div></section>' +
+        '<section><div class="section-head"><h2>' + text.capabilityHealth + '</h2><a href="capabilities.html">' + text.viewAll + ' →</a></div><div class="cap-list">' + caps + '</div></section>' +
+        (model.review_html ? '<section><h2>' + text.latestReview + '</h2><div class="doc">' + model.review_html + '</div></section>' : ''));
+}
+
+function renderDocs(title, documents, model, active) {
+    const content = documents.map(function(doc) {
+        return '<article class="doc-card"><div class="doc-title"><h2>' + escapeHtml(doc.title) + '</h2><span>' +
+            escapeHtml(doc.name) + '.md</span></div><div class="doc">' + doc.html + '</div></article>';
+    }).join('') || '<p class="muted">No ' + escapeHtml(title.toLowerCase()) + ' documents yet.</p>';
+    return shell(title, model, active, '<h1>' + escapeHtml(title) + '</h1>' + content);
+}
+
+function renderMatrix(model) {
+    if (!model.capabilities.length || !model.repositories.length) return '<p class="muted">No capability mapping available.</p>';
+    const header = model.repositories.map(function(repo) { return '<th>' + escapeHtml(repo.name) + '</th>'; }).join('');
+    const rows = model.capabilities.map(function(cap) {
+        const cells = model.repositories.map(function(repo) {
+            return '<td class="matrix-cell">' + (cap.repos.includes(repo.name) ? '<span class="dot">●</span>' : '') + '</td>';
+        }).join('');
+        return '<tr><th><a href="capability/' + encodeURIComponent(cap.slug) + '.html">' + escapeHtml(cap.title) +
+            '</a><br>' + badge(cap.status) + '</th>' + cells + '</tr>';
+    }).join('');
+    return '<div class="table-wrap"><table class="matrix"><thead><tr><th>Capability</th>' + header + '</tr></thead><tbody>' + rows + '</tbody></table></div>';
+}
+
+function renderCapabilities(model) {
+    const text = copy(model);
+    const cards = model.capabilities.map(function(cap) {
+        const haystack = (cap.title + ' ' + cap.slug + ' ' + cap.repos.join(' ')).toLowerCase();
+        return '<a class="cap-card" data-capability="' + escapeHtml(haystack) + '" href="capability/' + encodeURIComponent(cap.slug) +
+            '.html"><div><h3>' + escapeHtml(cap.title) + '</h3><p>' + escapeHtml(cap.repos.join(' · ') || text.noMapping) +
+            '</p></div><div>' + badge(cap.status) + '</div></a>';
+    }).join('') || '<p class="muted">No capability specs yet.</p>';
+    return shell(text.capabilities, model, 'capabilities',
+        '<h1>' + text.capabilities + '</h1><p class="muted">Business capabilities mapped back to repositories and evidence.</p>' +
+        '<input id="capability-search" class="search" type="search" placeholder="' + escapeHtml(text.filter) + '">' +
+        renderMatrix(model) + '<h2>' + text.details + '</h2><div id="capability-list" class="cap-grid">' + cards + '</div>');
+}
+
+function renderCapability(model, cap) {
+    const text = copy(model);
+    const sources = Object.entries(cap.source_paths || {}).map(function(entry) {
+        return '<div class="source-group"><h3>' + escapeHtml(entry[0]) + '</h3><ul>' +
+            entry[1].map(function(p) { return '<li><code>' + escapeHtml(p) + '</code></li>'; }).join('') + '</ul></div>';
+    }).join('') || '<p class="muted">No source map recorded.</p>';
+    const evidence = Object.entries(cap.evidence || {}).map(function(entry) {
+        return '<tr><th>' + escapeHtml(entry[0].replace(/_/g, ' ')) + '</th><td>' + escapeHtml(entry[1]) + '</td></tr>';
+    }).join('');
+    return shell(cap.title, model, 'capabilities',
+        '<div class="breadcrumbs"><a href="../capabilities.html">Capabilities</a> / ' + escapeHtml(cap.title) + '</div>' +
+        '<div class="detail-head"><div><h1>' + escapeHtml(cap.title) + '</h1><p class="muted">' + escapeHtml(cap.slug) +
+        '</p></div><div>' + badge(cap.status) + ' ' + badge(cap.verification_status) + '</div></div>' +
+        '<section class="two-col"><div><h2>' + text.repositories + '</h2><p>' + escapeHtml(cap.repos.join(' · ') || text.noMapping) +
+        '</p></div><div><h2>' + text.drift + '</h2><p>' + badge(cap.drift_status) + '</p></div></section>' +
+        '<section><h2>' + text.sourceMap + '</h2><div class="source-grid">' + sources + '</div></section>' +
+        (evidence ? '<section><h2>' + text.evidence + '</h2><div class="table-wrap"><table><tbody>' + evidence + '</tbody></table></div></section>' : '') +
+        '<section><h2>PRD</h2><div class="doc">' + (cap.prd_html || '<p class="muted">prd.md not found.</p>') + '</div></section>' +
+        '<section><h2>Design</h2><div class="doc">' + (cap.design_html || '<p class="muted">design.md not found.</p>') + '</div></section>', 1);
+}
+
+function renderHealth(model) {
+    const text = copy(model);
+    const caps = model.capabilities.map(function(cap) {
+        return '<tr><th><a href="capability/' + encodeURIComponent(cap.slug) + '.html">' + escapeHtml(cap.title) +
+            '</a></th><td>' + badge(cap.verification_status) + '</td><td>' + badge(cap.drift_status) + '</td></tr>';
+    }).join('');
+    const warnings = [model.verification_error, model.progress_error, model.drift_error].filter(Boolean);
+    return shell(text.health, model, 'health',
+        '<h1>' + text.health + '</h1>' + (warnings.length ? '<div class="alert">' + warnings.map(escapeHtml).join('<br>') + '</div>' : '') +
+        '<section class="metrics">' + metric(text.verified, model.counts.verified, 'good') +
+        metric(text.stale, model.counts.stale, model.counts.stale ? 'warning' : '') + metric(text.needsReview, model.counts.needs_review) +
+        metric(text.blocked, model.counts.blocked) + metric(text.unverified, model.counts.unverified) + '</section>' +
+        '<section><h2>' + text.capabilityStatus + '</h2><div class="table-wrap"><table><thead><tr><th>Capability</th><th>' + text.verification + '</th><th>' + text.drift + '</th></tr></thead><tbody>' +
+        (caps || '<tr><td colspan="3">No capabilities.</td></tr>') + '</tbody></table></div></section>' +
+        (model.review_html ? '<section><h2>Independent review</h2><div class="doc">' + model.review_html + '</div></section>' : ''));
+}
+
+const SITE_CSS = [
+    ':root{--bg:#f5f5f2;--panel:#fff;--ink:#171714;--muted:#6f7069;--line:#deded8;--accent:#2c5d4c;--ok:#2f6b4f;--warn:#9a6500;--bad:#9f3737;--soft:#ecece7}',
+    '*{box-sizing:border-box}body{margin:0;font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:var(--bg);color:var(--ink);line-height:1.6}a{color:var(--accent);text-decoration:none}a:hover{text-decoration:underline}',
+    '.topbar{height:58px;display:flex;align-items:center;justify-content:space-between;padding:0 24px;border-bottom:1px solid var(--line);background:#fff;position:sticky;top:0;z-index:10}.brand{font-weight:800;color:var(--ink)}.top-meta{font-size:12px;color:var(--muted)}',
+    '.layout{display:grid;grid-template-columns:210px minmax(0,1fr);min-height:calc(100vh - 58px)}.sidebar{padding:24px 14px;border-right:1px solid var(--line);background:#fafaf7;position:sticky;top:58px;height:calc(100vh - 58px)}.sidebar a{display:block;padding:9px 12px;border-radius:8px;color:#454641;margin:2px 0}.sidebar a.active{background:#e7eee9;color:#194b3a;font-weight:700}.content{width:min(1180px,100%);padding:42px 48px 80px}',
+    '.hero{padding:36px;border:1px solid var(--line);border-radius:18px;background:linear-gradient(135deg,#fff,#edf2ee);margin-bottom:24px}.hero h1{font-size:42px;margin:6px 0}.hero p:last-child{max-width:720px;color:var(--muted)}.eyebrow{font-size:12px;letter-spacing:.16em;color:var(--accent);font-weight:800}',
+    '.metrics{display:grid;grid-template-columns:repeat(auto-fit,minmax(130px,1fr));gap:12px;margin:24px 0}.metric{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:18px}.metric-value{font-size:28px;font-weight:800}.metric-label{font-size:12px;color:var(--muted);text-transform:uppercase}.metric.good{border-color:#bdd4c8}.metric.warning{border-color:#dec690}',
+    'section{margin:34px 0}.section-head,.detail-head,.doc-title{display:flex;justify-content:space-between;gap:18px}.repo-grid,.cap-grid,.source-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:12px}.repo-card,.cap-card,.source-group{background:#fff;border:1px solid var(--line);border-radius:12px;padding:16px}.repo-card{display:flex;flex-direction:column}.cap-card{display:flex;justify-content:space-between;color:var(--ink)}',
+    '.cap-list{border:1px solid var(--line);border-radius:12px;overflow:hidden;background:#fff}.cap-row{display:flex;justify-content:space-between;align-items:center;padding:14px 16px;border-bottom:1px solid var(--line);color:var(--ink)}.cap-row small{display:block;color:var(--muted)}',
+    '.badge{display:inline-block;font-size:11px;font-weight:800;text-transform:uppercase;border-radius:999px;padding:4px 8px;background:var(--soft)}.badge.ok{background:#dcece3;color:var(--ok)}.badge.warn{background:#f2e7c9;color:var(--warn)}.badge.bad{background:#f2dada;color:var(--bad)}',
+    '.table-wrap{overflow:auto;border:1px solid var(--line);border-radius:12px;background:#fff}table{border-collapse:collapse;width:100%;font-size:14px}th,td{text-align:left;padding:11px 13px;border-bottom:1px solid var(--line)}thead th{background:#f4f4ef}.matrix-cell{text-align:center}.dot{color:var(--accent)}',
+    '.search{width:100%;padding:12px 14px;border:1px solid var(--line);border-radius:10px;background:#fff;font:inherit;margin-bottom:18px}.muted{color:var(--muted)}.breadcrumbs{font-size:13px;color:var(--muted)}.two-col{display:grid;grid-template-columns:1fr 1fr;gap:18px}',
+    '.doc-card,.doc{background:#fff;border:1px solid var(--line);border-radius:14px;padding:22px;margin:16px 0}.doc-card>.doc{border:0;padding:0}.doc pre{background:#181a18;color:#f2f2ed;padding:16px;border-radius:10px;overflow:auto}.doc :not(pre)>code{background:#efefe9;padding:2px 5px;border-radius:5px}.doc blockquote{padding:8px 16px;border-left:3px solid var(--accent);background:#f4f7f4}.doc .mermaid{background:#fafaf7;color:var(--ink);border:1px dashed var(--line)}.alert{padding:14px;border:1px solid #dfc38e;background:#fff5dc;border-radius:10px}',
+    '@media(max-width:760px){.layout{display:block}.sidebar{position:static;height:auto;display:flex;overflow:auto;padding:8px}.sidebar a{white-space:nowrap}.content{padding:28px 18px}.top-meta{display:none}.two-col{grid-template-columns:1fr}}'
+].join('');
+
+const SITE_JS = [
+    "(function(){",
+    "var search=document.getElementById('capability-search');",
+    "if(search){search.addEventListener('input',function(){var q=search.value.trim().toLowerCase();document.querySelectorAll('[data-capability]').forEach(function(el){el.style.display=!q||el.dataset.capability.includes(q)?'flex':'none';});});}",
+    "})();"
+].join('');
+
+const REMOTE_MERMAID_JS = [
+    "(function(){",
+    "var diagrams=[].slice.call(document.querySelectorAll('pre.mermaid'));",
+    "if(diagrams.length&&navigator.onLine){var script=document.createElement('script');script.src='https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';script.onload=function(){if(window.mermaid){window.mermaid.initialize({startOnLoad:true,securityLevel:'strict'});}};document.head.appendChild(script);}",
+    "})();"
+].join('');
+
+function writeFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function buildSite(workspaceRoot, manifest, options) {
+    options = options || {};
+    const outputRoot = resolveOutputRoot(workspaceRoot, manifest, options.output);
+    if (options.clean !== false) fs.rmSync(outputRoot, { recursive: true, force: true });
+    fs.mkdirSync(outputRoot, { recursive: true });
+    const model = buildSystemModel(workspaceRoot, manifest, options);
+    writeFile(path.join(outputRoot, 'assets', 'site.css'), SITE_CSS + '\n');
+    writeFile(path.join(outputRoot, 'assets', 'app.js'), SITE_JS + (options.remoteMermaid ? REMOTE_MERMAID_JS : '') + '\n');
+    writeFile(path.join(outputRoot, 'index.html'), renderOverview(model));
+    const text = copy(model);
+    writeFile(path.join(outputRoot, 'architecture.html'), renderDocs(text.architecture, model.architecture, model, 'architecture'));
+    writeFile(path.join(outputRoot, 'capabilities.html'), renderCapabilities(model));
+    writeFile(path.join(outputRoot, 'flows.html'), renderDocs(text.flows, model.flows, model, 'flows'));
+    writeFile(path.join(outputRoot, 'contracts.html'), renderDocs(text.contracts, model.contracts, model, 'contracts'));
+    writeFile(path.join(outputRoot, 'health.html'), renderHealth(model));
+    model.capabilities.forEach(function(cap) {
+        writeFile(path.join(outputRoot, 'capability', cap.slug + '.html'), renderCapability(model, cap));
+    });
+    const publicModel = JSON.parse(JSON.stringify(model));
+    publicModel.capabilities.forEach(function(cap) {
+        delete cap.prd_html;
+        delete cap.design_html;
+    });
+    ['architecture', 'flows', 'contracts'].forEach(function(group) {
+        publicModel[group].forEach(function(doc) { delete doc.html; });
+    });
+    delete publicModel.review_html;
+    writeFile(path.join(outputRoot, 'data', 'system.json'), JSON.stringify(publicModel, null, 2) + '\n');
+    return { outputRoot: outputRoot, model: model, pages: 6 + model.capabilities.length };
+}
+
+function createStaticServer(outputRoot) {
+    const root = path.resolve(outputRoot);
+    return http.createServer(function(req, res) {
+        let pathname;
+        try {
+            pathname = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+        } catch (_error) {
+            res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('Bad request');
+            return;
+        }
+        if (pathname === '/') pathname = '/index.html';
+        const requested = path.resolve(root, '.' + pathname);
+        const relative = path.relative(root, requested);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('Forbidden');
+            return;
+        }
+        if (!fs.existsSync(requested) || !fs.statSync(requested).isFile()) {
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('Not found');
+            return;
+        }
+        const types = { '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'application/javascript; charset=utf-8', '.json': 'application/json; charset=utf-8' };
+        res.writeHead(200, { 'content-type': types[path.extname(requested)] || 'application/octet-stream', 'cache-control': 'no-cache' });
+        fs.createReadStream(requested).pipe(res);
+    });
+}
+
+function normalizePort(value) {
+    const port = value == null ? DEFAULT_PORT : Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port: ' + value);
+    return port;
+}
+
+function serveSite(outputRoot, options) {
+    options = options || {};
+    const host = options.host || DEFAULT_HOST;
+    const port = normalizePort(options.port);
+    const server = createStaticServer(outputRoot);
+    if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
+        console.warn('WARNING: spec serve is bound to ' + host + '; system documentation may be reachable from other machines.');
+    }
+    server.on('error', function(error) {
+        console.error('spec serve failed: ' + error.message);
+        process.exitCode = 1;
+    });
+    server.listen(port, host, function() {
+        const address = server.address();
+        const actualPort = address && typeof address === 'object' ? address.port : port;
+        console.log('System spec site: http://' + host + ':' + actualPort);
+        console.log('Serving ' + portable(path.resolve(outputRoot)));
+        console.log('Press Ctrl+C to stop.');
+    });
+    return server;
+}
+
+module.exports = {
+    DEFAULT_SITE_DIR: DEFAULT_SITE_DIR,
+    DEFAULT_PORT: DEFAULT_PORT,
+    DEFAULT_HOST: DEFAULT_HOST,
+    escapeHtml: escapeHtml,
+    markdownToHtml: markdownToHtml,
+    safeCapabilitySlug: safeCapabilitySlug,
+    resolveOutputRoot: resolveOutputRoot,
+    buildSystemModel: buildSystemModel,
+    buildSite: buildSite,
+    createStaticServer: createStaticServer,
+    normalizePort: normalizePort,
+    serveSite: serveSite
+};