sdx-cli 0.3.0 → 0.3.2

package/dist/lib/readme.js

@@ -0,0 +1,1651 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.README_SECTION_ORDER = void 0;
+exports.parseReadmeSectionList = parseReadmeSectionList;
+exports.generateReadme = generateReadme;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const yaml_1 = __importDefault(require("yaml"));
+const zod_1 = require("zod");
+const architecture_1 = require("./architecture");
+const config_1 = require("./config");
+const constants_1 = require("./constants");
+const contracts_1 = require("./contracts");
+const fileScan_1 = require("./fileScan");
+const fs_1 = require("./fs");
+const github_1 = require("./github");
+const mapBuilder_1 = require("./mapBuilder");
+const repoRegistry_1 = require("./repoRegistry");
+const scope_1 = require("./scope");
+const version_1 = require("./version");
+exports.README_SECTION_ORDER = [
+    'what_is_this_system',
+    'architecture_glance',
+    'service_catalog',
+    'critical_flows',
+    'event_async_topology',
+    'contracts_index',
+    'repository_index',
+    'environments_deployment',
+    'data_stores_boundaries',
+    'security_compliance',
+    'local_dev_contribution',
+    'runbooks_escalation',
+    'adr_index',
+    'glossary',
+    'changelog_metadata',
+];
+const SECTION_SET = new Set(exports.README_SECTION_ORDER);
+const SECTION_TITLES = {
+    what_is_this_system: 'What this org/system is',
+    architecture_glance: 'Architecture at a glance',
+    service_catalog: 'Service catalog table',
+    critical_flows: 'Critical request/data flows',
+    event_async_topology: 'Event and async topology',
+    contracts_index: 'Contracts and interface index',
+    repository_index: 'Repository index with ownership',
+    environments_deployment: 'Environments and deployment topology',
+    data_stores_boundaries: 'Data stores and boundaries',
+    security_compliance: 'Security/compliance considerations',
+    local_dev_contribution: 'Local development and contribution workflow',
+    runbooks_escalation: 'Operational runbooks and escalation paths',
+    adr_index: 'ADR and design decision index',
+    glossary: 'Glossary',
+    changelog_metadata: 'Change log / last generated metadata',
+};
+const REQUIRED_DIAGRAM_NAMES = ['system-context.mmd', 'service-dependency.mmd', 'core-request-flow.mmd'];
+const README_CONFIG_SCHEMA = zod_1.z.object({
+    sections: zod_1.z
+        .object({
+        include: zod_1.z.array(zod_1.z.string()).optional(),
+        exclude: zod_1.z.array(zod_1.z.string()).optional(),
+        enabled: zod_1.z.record(zod_1.z.string(), zod_1.z.boolean()).optional(),
+    })
+        .optional(),
+    repos: zod_1.z
+        .object({
+        include: zod_1.z.array(zod_1.z.string()).optional(),
+        exclude: zod_1.z.array(zod_1.z.string()).optional(),
+    })
+        .optional(),
+    domainGroups: zod_1.z
+        .array(zod_1.z.object({
+        name: zod_1.z.string(),
+        match: zod_1.z.array(zod_1.z.string()).default([]),
+    }))
+        .optional(),
+    ownerTeamOverrides: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    diagram: zod_1.z
+        .object({
+        autoGenerateMissing: zod_1.z.boolean().optional(),
+        includeC4Links: zod_1.z.boolean().optional(),
+    })
+        .optional(),
+    customIntro: zod_1.z.string().optional(),
+    staleThresholdHours: zod_1.z.number().positive().optional(),
+});
+const EMPTY_REPO_INSIGHTS = {
+    summary: 'Unknown',
+    responsibilities: [],
+    interfaces: [],
+    asyncPatterns: [],
+    deployment: [],
+    runbooks: [],
+    localDevelopment: [],
+    security: [],
+    adrs: [],
+    dataStores: [],
+    glossary: [],
+    docReferences: [],
+};
+function normalizeRepoName(value) {
+    return value.trim().replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').split('/').pop() ?? value.trim();
+}
+function asRelative(filePath, cwd) {
+    const relative = node_path_1.default.relative(cwd, filePath);
+    return relative.length === 0 ? '.' : relative.split(node_path_1.default.sep).join('/');
+}
+function toLinkPath(targetPath, outputPath) {
+    const relative = node_path_1.default.relative(node_path_1.default.dirname(outputPath), targetPath).split(node_path_1.default.sep).join('/');
+    if (relative.startsWith('.')) {
+        return relative;
+    }
+    return `./${relative}`;
+}
+function safeTimestamp(value) {
+    if (!value) {
+        return undefined;
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        return undefined;
+    }
+    return parsed;
+}
+function isOlderThan(value, thresholdHours, now) {
+    if (!value) {
+        return true;
+    }
+    const elapsedMs = now.getTime() - value.getTime();
+    return elapsedMs > thresholdHours * 60 * 60 * 1000;
+}
+function loadReadmeConfig(cwd) {
+    const candidates = [
+        node_path_1.default.join(cwd, '.sdx', 'readme.config.json'),
+        node_path_1.default.join(cwd, '.sdx', 'readme.config.yaml'),
+        node_path_1.default.join(cwd, '.sdx', 'readme.config.yml'),
+    ];
+    for (const filePath of candidates) {
+        if (!(0, fs_1.fileExists)(filePath)) {
+            continue;
+        }
+        const text = (0, fs_1.safeReadText)(filePath);
+        const parsed = filePath.endsWith('.json') ? JSON.parse(text) : yaml_1.default.parse(text);
+        const config = README_CONFIG_SCHEMA.parse(parsed);
+        return {
+            config,
+            sourcePath: filePath,
+        };
+    }
+    return { config: {} };
+}
+function parseReadmeSectionList(input) {
+    if (!input) {
+        return [];
+    }
+    const tokens = input
+        .split(',')
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+    const invalid = tokens.filter((token) => !SECTION_SET.has(token));
+    if (invalid.length > 0) {
+        throw new Error(`Unknown section id(s): ${invalid.join(', ')}. Valid ids: ${exports.README_SECTION_ORDER.join(', ')}`);
+    }
+    return [...new Set(tokens)];
+}
+function selectSections(config, includeSections, excludeSections) {
+    let ordered = [...exports.README_SECTION_ORDER];
+    const configEnabled = config.sections?.enabled ?? {};
+    ordered = ordered.filter((section) => configEnabled[section] !== false);
+    const configInclude = (config.sections?.include ?? [])
+        .map((candidate) => candidate.trim())
+        .filter((candidate) => candidate.length > 0);
+    if (configInclude.length > 0) {
+        ordered = ordered.filter((section) => configInclude.includes(section));
+    }
+    const configExclude = (config.sections?.exclude ?? [])
+        .map((candidate) => candidate.trim())
+        .filter((candidate) => candidate.length > 0);
+    if (configExclude.length > 0) {
+        ordered = ordered.filter((section) => !configExclude.includes(section));
+    }
+    if (includeSections.length > 0) {
+        ordered = ordered.filter((section) => includeSections.includes(section));
+    }
+    if (excludeSections.length > 0) {
+        ordered = ordered.filter((section) => !excludeSections.includes(section));
+    }
+    if (ordered.length === 0) {
+        throw new Error('No README sections selected after include/exclude filtering.');
+    }
+    return ordered;
+}
+function readGeneratedAtFromJson(filePath) {
+    if (!(0, fs_1.fileExists)(filePath)) {
+        return undefined;
+    }
+    try {
+        const payload = (0, fs_1.readJsonFile)(filePath);
+        const value = payload['generatedAt'];
+        return typeof value === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sourceFromFile(id, label, filePath, cwd, thresholdHours, now, required) {
+    const exists = (0, fs_1.fileExists)(filePath);
+    const generatedAt = exists
+        ? readGeneratedAtFromJson(filePath) ?? node_fs_1.default.statSync(filePath).mtime.toISOString()
+        : undefined;
+    const stale = exists ? isOlderThan(safeTimestamp(generatedAt), thresholdHours, now) : true;
+    return {
+        id,
+        label,
+        path: asRelative(filePath, cwd),
+        exists,
+        generatedAt,
+        stale,
+        required,
+        note: exists ? undefined : 'Missing source artifact',
+    };
+}
+function detectRepoSyncTimestamp(repos, scopedRepos) {
+    const timestamps = [];
+    for (const repoName of scopedRepos) {
+        const repo = repos.find((entry) => entry.name === repoName);
+        if (!repo?.lastSyncedAt) {
+            return undefined;
+        }
+        const parsed = safeTimestamp(repo.lastSyncedAt);
+        if (!parsed) {
+            return undefined;
+        }
+        timestamps.push(parsed);
+    }
+    if (timestamps.length === 0) {
+        return undefined;
+    }
+    const oldest = timestamps.reduce((min, candidate) => (candidate.getTime() < min.getTime() ? candidate : min), timestamps[0]);
+    return oldest.toISOString();
+}
+function sourceFromRepoSync(repos, scopedRepos, thresholdHours, now) {
+    const generatedAt = detectRepoSyncTimestamp(repos, scopedRepos);
+    const stale = isOlderThan(safeTimestamp(generatedAt), thresholdHours, now);
+    return {
+        id: 'repo-sync',
+        label: 'Repository registry sync state',
+        path: '.sdx/state.db#repo_registry',
+        exists: generatedAt !== undefined,
+        generatedAt,
+        stale,
+        required: true,
+        note: generatedAt ? undefined : 'At least one scoped repo has no lastSyncedAt timestamp',
+    };
+}
+function upsertSourceRef(sources, source) {
+    const index = sources.findIndex((entry) => entry.id === source.id);
+    if (index >= 0) {
+        sources[index] = source;
+        return;
+    }
+    sources.push(source);
+}
+function computeSnapshotTimestamp(sources, fallback) {
+    const sourceCandidates = sources
+        .map((source) => safeTimestamp(source.generatedAt))
+        .filter((entry) => Boolean(entry));
+    if (sourceCandidates.length === 0) {
+        return fallback.toISOString();
+    }
+    return sourceCandidates.reduce((latest, candidate) => (candidate.getTime() > latest.getTime() ? candidate : latest), sourceCandidates[0]).toISOString();
+}
+function markdownPriority(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower === 'readme.md' || lower.endsWith('/readme.md')) {
+        return 0;
+    }
+    if (lower.includes('/docs/architecture/') || lower.includes('/architecture/')) {
+        return 1;
+    }
+    if (lower.includes('/docs/api/') || lower.includes('/api/')) {
+        return 2;
+    }
+    if (lower.includes('/docs/')) {
+        return 3;
+    }
+    return 4;
+}
+function parseOwnerRepo(fullName) {
+    if (!fullName) {
+        return null;
+    }
+    const parts = fullName.split('/').map((part) => part.trim()).filter((part) => part.length > 0);
+    if (parts.length !== 2) {
+        return null;
+    }
+    return { owner: parts[0], repo: parts[1] };
+}
+function normalizeMarkdown(input) {
+    return input
+        .replace(/\r\n/g, '\n')
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1')
+        .replace(/[#>*_~\-]{1,}/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function splitSentences(input) {
+    const cleaned = normalizeMarkdown(input);
+    if (cleaned.length === 0) {
+        return [];
+    }
+    return cleaned
+        .split(/(?<=[.!?])\s+/)
+        .map((sentence) => sentence.trim())
+        .filter((sentence) => sentence.length >= 20);
+}
+function markdownSections(content) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const out = [];
+    let currentHeading = 'root';
+    let buffer = [];
+    function flush() {
+        const body = buffer.join('\n').trim();
+        if (body.length > 0) {
+            out.push({ heading: currentHeading, body });
+        }
+        buffer = [];
+    }
+    for (const line of lines) {
+        const match = line.match(/^#{1,6}\s+(.+)$/);
+        if (match) {
+            flush();
+            currentHeading = match[1].trim().toLowerCase();
+            continue;
+        }
+        buffer.push(line);
+    }
+    flush();
+    return out;
+}
+function firstParagraph(content) {
+    const paragraphs = content
+        .replace(/\r\n/g, '\n')
+        .split(/\n\s*\n/)
+        .map((chunk) => normalizeMarkdown(chunk))
+        .filter((chunk) => chunk.length >= 20);
+    return paragraphs[0];
+}
+function topUnique(values, limit) {
+    const out = [];
+    for (const value of values) {
+        if (out.includes(value)) {
+            continue;
+        }
+        out.push(value);
+        if (out.length >= limit) {
+            break;
+        }
+    }
+    return out;
+}
+function collectLocalMarkdownDocs(repo, maxFiles = 180, maxChars = 180_000) {
+    if (!repo.localPath || !(0, fs_1.fileExists)(repo.localPath)) {
+        return [];
+    }
+    const candidates = (0, fileScan_1.listFilesRecursive)(repo.localPath)
+        .filter((candidate) => /\.(md|mdx)$/i.test(candidate))
+        .map((candidate) => node_path_1.default.relative(repo.localPath, candidate).split(node_path_1.default.sep).join('/'))
+        .sort((a, b) => {
+        const priorityDelta = markdownPriority(a) - markdownPriority(b);
+        if (priorityDelta !== 0) {
+            return priorityDelta;
+        }
+        return a.localeCompare(b);
+    });
+    const selected = candidates.slice(0, maxFiles);
+    const docs = [];
+    for (const relativePath of selected) {
+        const absolutePath = node_path_1.default.join(repo.localPath, relativePath);
+        const raw = (0, fs_1.safeReadText)(absolutePath);
+        const body = raw.slice(0, maxChars);
+        if (normalizeMarkdown(body).length === 0) {
+            continue;
+        }
+        docs.push({
+            path: relativePath,
+            body,
+            source: 'local',
+        });
+    }
+    return docs;
+}
+async function collectRemoteMarkdownDocs(repo, token) {
+    if (!token) {
+        return [];
+    }
+    const ownerRepo = parseOwnerRepo(repo.fullName);
+    if (!ownerRepo) {
+        return [];
+    }
+    try {
+        const files = await (0, github_1.fetchRepositoryMarkdownDocs)({
+            owner: ownerRepo.owner,
+            repo: ownerRepo.repo,
+            defaultBranch: repo.defaultBranch ?? 'main',
+            token,
+            maxFiles: 25,
+            maxBytesPerFile: 120_000,
+        });
+        return files.map((entry) => ({
+            path: entry.path,
+            body: entry.body,
+            source: 'remote',
+            referenceUrl: entry.referenceUrl,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function inferStoresFromDocs(docs) {
+    const keywords = ['postgres', 'mysql', 'mongodb', 'dynamodb', 'redis', 'cassandra', 'sqlite', 'kafka', 'sqs', 'rabbitmq'];
+    const matches = [];
+    for (const doc of docs) {
+        const normalized = normalizeMarkdown(doc.body).toLowerCase();
+        for (const keyword of keywords) {
+            if (normalized.includes(keyword)) {
+                matches.push(keyword);
+            }
+        }
+    }
+    return topUnique(matches.sort((a, b) => a.localeCompare(b)), 6);
+}
+function collectByHeading(docs, matcher, limit) {
+    const collected = [];
+    for (const doc of docs) {
+        const sections = markdownSections(doc.body);
+        for (const section of sections) {
+            if (!matcher.test(section.heading)) {
+                continue;
+            }
+            collected.push(...splitSentences(section.body));
+        }
+    }
+    return topUnique(collected, limit);
+}
+function collectCommands(docs, limit) {
+    const commands = [];
+    for (const doc of docs) {
+        const matches = doc.body.match(/```(?:bash|sh|zsh|shell)?\n([\s\S]*?)```/gi) ?? [];
+        for (const block of matches) {
+            const body = block
+                .replace(/```(?:bash|sh|zsh|shell)?\n?/i, '')
+                .replace(/```$/i, '')
+                .split('\n')
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0 && !line.startsWith('#'));
+            for (const line of body) {
+                commands.push(line);
+            }
+        }
+    }
+    return topUnique(commands, limit);
+}
+function extractGlossaryTerms(docs) {
+    const terms = [];
+    for (const doc of docs) {
+        const glossarySections = markdownSections(doc.body).filter((section) => /glossary|terms/.test(section.heading));
+        for (const section of glossarySections) {
+            for (const line of section.body.split('\n')) {
+                const match = line.match(/^\s*[-*]\s*\*\*([^*]+)\*\*:/);
+                if (match) {
+                    terms.push(match[1].trim());
+                }
+            }
+        }
+    }
+    return topUnique(terms.sort((a, b) => a.localeCompare(b)), 12);
+}
+async function buildRepoInsights(repo, token) {
+    const localDocs = collectLocalMarkdownDocs(repo);
+    const remoteDocs = localDocs.length > 0 ? [] : await collectRemoteMarkdownDocs(repo, token);
+    const docs = [...localDocs, ...remoteDocs];
+    const summary = firstParagraph(docs.find((doc) => /(^|\/)readme\.mdx?$/i.test(doc.path))?.body ?? '') ??
+        firstParagraph(docs[0]?.body ?? '') ??
+        'Unknown';
+    const responsibilities = collectByHeading(docs, /(overview|purpose|responsibilit|architecture|what .*does)/, 5);
+    const interfaces = collectByHeading(docs, /(api|endpoint|contract|schema|graphql|grpc|openapi)/, 5);
+    const asyncPatterns = collectByHeading(docs, /(event|async|queue|topic|stream|kafka|pubsub)/, 5);
+    const deployment = collectByHeading(docs, /(deploy|environment|infrastructure|release|production)/, 5);
+    const runbooks = collectByHeading(docs, /(runbook|incident|on.?call|troubleshoot|escalation)/, 5);
+    const security = collectByHeading(docs, /(security|auth|authorization|compliance|privacy|encryption|secret)/, 5);
+    const adrs = docs
+        .filter((doc) => /(\/|^)docs\/adr\/.+\.mdx?$/i.test(doc.path) || /(\/|^)adr\/.+\.mdx?$/i.test(doc.path))
+        .map((doc) => doc.referenceUrl ?? doc.path);
+    const localDevelopment = collectCommands(docs, 8);
+    const dataStores = inferStoresFromDocs(docs);
+    const glossary = extractGlossaryTerms(docs);
+    const docReferences = topUnique(docs
+        .map((doc) => doc.referenceUrl ?? doc.path)
+        .sort((a, b) => a.localeCompare(b)), 8);
+    return {
+        summary,
+        responsibilities,
+        interfaces,
+        asyncPatterns,
+        deployment,
+        runbooks,
+        localDevelopment,
+        security,
+        adrs,
+        dataStores,
+        glossary,
+        docReferences,
+    };
+}
+async function buildAllRepoInsights(selectedRepos, repoMap, token) {
+    const out = new Map();
+    await Promise.all(selectedRepos.map(async (repoName) => {
+        const repo = repoMap.get(repoName);
+        if (!repo) {
+            out.set(repoName, EMPTY_REPO_INSIGHTS);
+            return;
+        }
+        const insights = await buildRepoInsights(repo, token);
+        out.set(repoName, insights);
+    }));
+    return out;
+}
+function filterReposForReadme(scope, config) {
+    const base = [...scope.effective];
+    const include = new Set((config.repos?.include ?? []).map((value) => normalizeRepoName(value)));
+    const exclude = new Set((config.repos?.exclude ?? []).map((value) => normalizeRepoName(value)));
+    let selected = base;
+    if (include.size > 0) {
+        selected = selected.filter((repo) => include.has(repo));
+    }
+    selected = selected.filter((repo) => !exclude.has(repo));
+    selected.sort((a, b) => a.localeCompare(b));
+    return selected;
+}
+function loadServiceMap(mapId, scope, repoMap, mapDir) {
+    const filePath = node_path_1.default.join(mapDir, 'service-map.json');
+    if ((0, fs_1.fileExists)(filePath)) {
+        return (0, fs_1.readJsonFile)(filePath);
+    }
+    return (0, mapBuilder_1.buildServiceMapArtifact)(mapId, scope, repoMap);
+}
+function loadContracts(mapId, scope, repoMap, mapDir) {
+    const filePath = node_path_1.default.join(mapDir, 'contracts.json');
+    if ((0, fs_1.fileExists)(filePath)) {
+        return (0, fs_1.readJsonFile)(filePath);
+    }
+    return (0, contracts_1.extractContracts)(mapId, scope, repoMap);
+}
+function loadArchitectureModel(mapId, db, cwd) {
+    const filePath = node_path_1.default.join(cwd, 'maps', mapId, 'architecture', 'model.json');
+    if ((0, fs_1.fileExists)(filePath)) {
+        return (0, fs_1.readJsonFile)(filePath);
+    }
+    return (0, architecture_1.buildArchitectureModel)(mapId, db, cwd);
+}
+function diagramPaths(mapId, cwd) {
+    const baseDir = node_path_1.default.join(cwd, 'docs', 'architecture', mapId, 'diagrams');
+    return {
+        baseDir,
+        systemContext: node_path_1.default.join(baseDir, 'system-context.mmd'),
+        serviceDependency: node_path_1.default.join(baseDir, 'service-dependency.mmd'),
+        sequence: node_path_1.default.join(baseDir, 'core-request-flow.mmd'),
+        optionalSystemLandscape: node_path_1.default.join(baseDir, 'system-landscape.mmd'),
+        optionalContainer: node_path_1.default.join(baseDir, 'container-communication.mmd'),
+        optionalArchitectureIndex: node_path_1.default.join(cwd, 'docs', 'architecture', mapId, 'index.md'),
+    };
+}
+function renderFlowchart(nodes, edges) {
+    const lines = ['flowchart LR'];
+    for (const node of nodes.sort((a, b) => a.id.localeCompare(b.id))) {
+        const nodeId = node.id.replace(/[^a-zA-Z0-9_]/g, '_');
+        lines.push(`  ${nodeId}["${node.label}"]`);
+    }
+    const sortedEdges = [...edges].sort((a, b) => {
+        const left = `${a.from}|${a.to}|${a.relation}`;
+        const right = `${b.from}|${b.to}|${b.relation}`;
+        return left.localeCompare(right);
+    });
+    for (const edge of sortedEdges) {
+        const fromId = edge.from.replace(/[^a-zA-Z0-9_]/g, '_');
+        const toId = edge.to.replace(/[^a-zA-Z0-9_]/g, '_');
+        lines.push(`  ${fromId} -->|"${edge.relation}"| ${toId}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderSystemContextDiagram(model) {
+    const allowed = new Set(['service', 'external', 'datastore', 'queue', 'team']);
+    const nodes = model.nodes
+        .filter((node) => allowed.has(node.type))
+        .map((node) => ({ id: node.id, label: node.label }));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = model.edges
+        .filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to))
+        .map((edge) => ({ from: edge.from, to: edge.to, relation: edge.relation }));
+    return renderFlowchart(nodes, edges);
+}
+function renderServiceDependencyDiagram(serviceMap) {
+    const serviceNodes = serviceMap.nodes
+        .filter((node) => node.type === 'service')
+        .map((node) => ({ id: node.id, label: node.label }));
+    const serviceIds = new Set(serviceNodes.map((node) => node.id));
+    const edges = serviceMap.edges
+        .filter((edge) => serviceIds.has(edge.from) && serviceIds.has(edge.to))
+        .map((edge) => ({ from: edge.from, to: edge.to, relation: edge.relation }));
+    return renderFlowchart(serviceNodes, edges);
+}
+function enumerateServiceCallEdges(model) {
+    const out = [];
+    for (const edge of model.edges) {
+        if (edge.relation !== 'calls') {
+            continue;
+        }
+        if (!edge.from.startsWith('service:') || !edge.to.startsWith('service:')) {
+            continue;
+        }
+        out.push({
+            from: edge.from.replace('service:', ''),
+            to: edge.to.replace('service:', ''),
+            confidence: edge.provenance.confidence,
+        });
+    }
+    return out.sort((a, b) => {
+        const score = b.confidence - a.confidence;
+        if (score !== 0) {
+            return score;
+        }
+        const left = `${a.from}|${a.to}`;
+        const right = `${b.from}|${b.to}`;
+        return left.localeCompare(right);
+    });
+}
+function enumerateDependencyEdges(serviceMap) {
+    const out = [];
+    for (const edge of serviceMap.edges) {
+        if (edge.relation !== 'depends_on') {
+            continue;
+        }
+        if (!edge.from.startsWith('service:') || !edge.to.startsWith('service:')) {
+            continue;
+        }
+        out.push({
+            from: edge.from.replace('service:', ''),
+            to: edge.to.replace('service:', ''),
+            confidence: 0.45,
+        });
+    }
+    return out.sort((a, b) => {
+        const left = `${a.from}|${a.to}`;
+        const right = `${b.from}|${b.to}`;
+        return left.localeCompare(right);
+    });
+}
+function bestPath(edges) {
+    if (edges.length === 0) {
+        return [];
+    }
+    const adjacency = new Map();
+    for (const edge of edges) {
+        const candidates = adjacency.get(edge.from) ?? [];
+        candidates.push(edge);
+        adjacency.set(edge.from, candidates);
+    }
+    for (const candidateEdges of adjacency.values()) {
+        candidateEdges.sort((a, b) => {
+            const score = b.confidence - a.confidence;
+            if (score !== 0) {
+                return score;
+            }
+            return `${a.from}|${a.to}`.localeCompare(`${b.from}|${b.to}`);
+        });
+    }
+    const starts = [...new Set(edges.map((edge) => edge.from))].sort((a, b) => a.localeCompare(b));
+    let best = [];
+    let bestScore = -1;
+    const maxDepth = 6;
+    function dfs(current, visited, pathEdges) {
+        const outgoing = adjacency.get(current) ?? [];
+        if (pathEdges.length > 0) {
+            const score = pathEdges.reduce((sum, step) => sum + step.confidence, 0) + pathEdges.length * 0.1;
+            const tieBreakerLeft = pathEdges.map((edge) => `${edge.from}->${edge.to}`).join('|');
+            const tieBreakerRight = best.map((edge) => `${edge.from}->${edge.to}`).join('|');
+            if (score > bestScore || (score === bestScore && tieBreakerLeft.localeCompare(tieBreakerRight) < 0)) {
+                best = [...pathEdges];
+                bestScore = score;
+            }
+        }
+        if (pathEdges.length >= maxDepth) {
+            return;
+        }
+        for (const edge of outgoing) {
+            if (visited.has(edge.to)) {
+                continue;
+            }
+            visited.add(edge.to);
+            pathEdges.push(edge);
+            dfs(edge.to, visited, pathEdges);
+            pathEdges.pop();
+            visited.delete(edge.to);
+        }
+    }
+    for (const start of starts) {
+        const visited = new Set([start]);
+        dfs(start, visited, []);
+    }
+    return best;
+}
+function findCoreRequestPath(model, serviceMap) {
+    const callPath = bestPath(enumerateServiceCallEdges(model));
+    const fallbackPath = callPath.length > 0 ? callPath : bestPath(enumerateDependencyEdges(serviceMap));
+    if (fallbackPath.length === 0) {
+        return [];
+    }
+    return fallbackPath.map((step) => ({
+        from: `service:${step.from}`,
+        to: `service:${step.to}`,
+        relation: 'calls',
+        provenance: {
+            source: callPath.length > 0 ? 'inferred' : 'declared',
+            confidence: step.confidence,
+            evidence: [callPath.length > 0 ? 'architecture_model' : 'service_map_dependency_fallback'],
+        },
+    }));
+}
+function renderCoreSequence(pathEdges) {
+    const lines = ['sequenceDiagram', '  autonumber'];
+    if (pathEdges.length === 0) {
+        lines.push('  participant system as System');
+        lines.push('  system->>system: Unknown flow (insufficient call/dependency evidence)');
+        return `${lines.join('\n')}\n`;
+    }
+    const participants = new Set();
+    for (const edge of pathEdges) {
+        participants.add(edge.from.replace('service:', ''));
+        participants.add(edge.to.replace('service:', ''));
+    }
+    for (const participant of [...participants].sort((a, b) => a.localeCompare(b))) {
+        lines.push(`  participant ${participant.replace(/[^a-zA-Z0-9_]/g, '_')} as ${participant}`);
+    }
+    for (const edge of pathEdges) {
+        const from = edge.from.replace('service:', '').replace(/[^a-zA-Z0-9_]/g, '_');
+        const to = edge.to.replace('service:', '').replace(/[^a-zA-Z0-9_]/g, '_');
+        lines.push(`  ${from}->>${to}: ${edge.relation}`);
+        lines.push(`  ${to}-->>${from}: response`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function ensureRequiredDiagrams(context, db, cwd, writeEnabled) {
+    const refs = [];
+    const threshold = context.staleThresholdHours;
+    const required = REQUIRED_DIAGRAM_NAMES.map((name) => node_path_1.default.join(context.diagrams.baseDir, name));
+    const missing = required.filter((candidate) => !(0, fs_1.fileExists)(candidate));
+    let generatedArchitecturePack = false;
+    const autoGenerateMissing = context.config.diagram?.autoGenerateMissing ?? true;
+    if (writeEnabled && autoGenerateMissing && missing.length > 0) {
+        (0, architecture_1.generateArchitecturePack)({
+            mapId: context.mapId,
+            db,
+            cwd,
+            depth: 'org',
+        });
+        generatedArchitecturePack = true;
+    }
+    if (writeEnabled && autoGenerateMissing && !(0, fs_1.fileExists)(context.diagrams.systemContext)) {
+        (0, fs_1.writeTextFile)(context.diagrams.systemContext, renderSystemContextDiagram(context.architectureModel));
+    }
+    if (writeEnabled && autoGenerateMissing && !(0, fs_1.fileExists)(context.diagrams.serviceDependency)) {
+        (0, fs_1.writeTextFile)(context.diagrams.serviceDependency, renderServiceDependencyDiagram(context.serviceMap));
+    }
+    if (writeEnabled && autoGenerateMissing && !(0, fs_1.fileExists)(context.diagrams.sequence)) {
+        (0, fs_1.writeTextFile)(context.diagrams.sequence, renderCoreSequence(context.coreRequestPath));
+    }
+    refs.push(sourceFromFile('diagram-system-context', 'System context diagram', context.diagrams.systemContext, cwd, threshold, context.now, true));
+    refs.push(sourceFromFile('diagram-service-dependency', 'Service dependency diagram', context.diagrams.serviceDependency, cwd, threshold, context.now, true));
+    refs.push(sourceFromFile('diagram-core-sequence', 'Core request flow sequence', context.diagrams.sequence, cwd, threshold, context.now, true));
+    refs.push(sourceFromFile('diagram-c4-landscape', 'Optional C4 system landscape', context.diagrams.optionalSystemLandscape, cwd, threshold, context.now, false));
+    refs.push(sourceFromFile('diagram-c4-container', 'Optional C4 container communication', context.diagrams.optionalContainer, cwd, threshold, context.now, false));
+    return {
+        generatedArchitecturePack,
+        diagramSources: refs,
+    };
+}
+function readCodeownersOwner(repo) {
+    if (!repo.localPath) {
+        return undefined;
+    }
+    const candidates = [node_path_1.default.join(repo.localPath, 'CODEOWNERS'), node_path_1.default.join(repo.localPath, '.github', 'CODEOWNERS')];
+    for (const candidate of candidates) {
+        if (!(0, fs_1.fileExists)(candidate)) {
+            continue;
+        }
+        const lines = (0, fs_1.safeReadText)(candidate)
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith('#'));
+        for (const line of lines) {
+            const parts = line.split(/\s+/).filter((part) => part.length > 0);
+            const owner = parts.find((part) => part.startsWith('@'));
+            if (owner) {
+                return owner;
+            }
+        }
+    }
+    return undefined;
+}
+function inferRuntimeFramework(repo) {
+    if (!repo.localPath || !(0, fs_1.fileExists)(repo.localPath)) {
+        return 'Unknown';
+    }
+    const packagePath = node_path_1.default.join(repo.localPath, 'package.json');
+    if ((0, fs_1.fileExists)(packagePath)) {
+        try {
+            const payload = (0, fs_1.readJsonFile)(packagePath);
+            const deps = new Set([
+                ...Object.keys(payload.dependencies ?? {}),
+                ...Object.keys(payload.devDependencies ?? {}),
+            ]);
+            if (deps.has('next')) {
+                return 'Node.js (Next.js)';
+            }
+            if (deps.has('nestjs') || deps.has('@nestjs/core')) {
+                return 'Node.js (NestJS)';
+            }
+            if (deps.has('express')) {
+                return 'Node.js (Express)';
+            }
+            return 'Node.js';
+        }
+        catch {
+            return 'Node.js';
+        }
+    }
+    if ((0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'pyproject.toml')) || (0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'requirements.txt'))) {
+        return 'Python';
+    }
+    if ((0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'go.mod'))) {
+        return 'Go';
+    }
+    if ((0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'Cargo.toml'))) {
+        return 'Rust';
+    }
+    if ((0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'pom.xml')) || (0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'build.gradle'))) {
+        return 'JVM';
+    }
+    return 'Unknown';
+}
+function inferDeployTarget(repo) {
+    if (!repo.localPath || !(0, fs_1.fileExists)(repo.localPath)) {
+        return 'Unknown';
+    }
+    if ((0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'vercel.json'))) {
+        return 'Vercel';
+    }
+    if ((0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'serverless.yml')) || (0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'serverless.yaml'))) {
+        return 'Serverless';
+    }
+    const hasKubernetes = (0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'k8s')) ||
+        (0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'helm')) ||
+        (0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'charts'));
+    if (hasKubernetes) {
+        return 'Kubernetes';
+    }
+    if ((0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'Dockerfile')) || (0, fs_1.fileExists)(node_path_1.default.join(repo.localPath, 'docker-compose.yml'))) {
+        return 'Container';
+    }
+    return 'Unknown';
+}
+function formatList(values) {
+    if (values.length === 0) {
+        return 'Unknown';
+    }
+    return values.join(', ');
+}
+function insightsForRepo(repoName, context) {
+    return context.repoInsights.get(repoName) ?? EMPTY_REPO_INSIGHTS;
+}
+function shorten(text, max = 180) {
+    const normalized = normalizeMarkdown(text);
+    if (normalized.length <= max) {
+        return normalized;
+    }
+    return `${normalized.slice(0, max - 1).trimEnd()}…`;
+}
+function formatLinks(links, limit = 3) {
+    if (links.length === 0) {
+        return 'Unknown';
+    }
+    return links
+        .slice(0, limit)
+        .map((value) => {
+        if (/^https?:\/\//.test(value)) {
+            return `[doc](${value})`;
+        }
+        return `\`${value}\``;
+    })
+        .join(', ');
+}
+function inferRuntimeFromInsights(insights) {
+    const corpus = [
+        insights.summary,
+        ...insights.responsibilities,
+        ...insights.interfaces,
+        ...insights.localDevelopment,
+    ]
+        .join(' ')
+        .toLowerCase();
+    if (corpus.includes('next.js') || corpus.includes('nextjs')) {
+        return 'Node.js (Next.js)';
+    }
+    if (corpus.includes('nestjs')) {
+        return 'Node.js (NestJS)';
+    }
+    if (corpus.includes('express')) {
+        return 'Node.js (Express)';
+    }
+    if (corpus.includes('fastapi')) {
+        return 'Python (FastAPI)';
+    }
+    if (corpus.includes('django')) {
+        return 'Python (Django)';
+    }
+    if (corpus.includes('spring boot') || corpus.includes('spring')) {
+        return 'JVM (Spring)';
+    }
+    if (corpus.includes('golang') || corpus.includes('go service') || corpus.includes('go microservice')) {
+        return 'Go';
+    }
+    if (corpus.includes('rust')) {
+        return 'Rust';
+    }
+    return undefined;
+}
+function inferDeployTargetFromInsights(insights) {
+    const corpus = [...insights.deployment, insights.summary].join(' ').toLowerCase();
+    if (corpus.includes('kubernetes') || corpus.includes('helm') || corpus.includes('k8s')) {
+        return 'Kubernetes';
+    }
+    if (corpus.includes('vercel')) {
+        return 'Vercel';
+    }
+    if (corpus.includes('ecs') || corpus.includes('fargate')) {
+        return 'AWS ECS/Fargate';
+    }
+    if (corpus.includes('lambda') || corpus.includes('serverless')) {
+        return 'Serverless';
+    }
+    if (corpus.includes('docker') || corpus.includes('container')) {
+        return 'Container';
+    }
+    return undefined;
+}
+function ownerForService(serviceId, context) {
+    const overrides = context.config.ownerTeamOverrides ?? {};
+    if (overrides[serviceId]) {
+        return overrides[serviceId];
+    }
+    const serviceNode = context.architectureModel.nodes.find((node) => node.id === `service:${serviceId}`);
+    const fromMetadata = serviceNode?.metadata?.['owner'];
+    if (typeof fromMetadata === 'string' && fromMetadata.trim().length > 0) {
+        return fromMetadata.trim();
+    }
+    const repo = context.repoMap.get(serviceId);
+    if (!repo) {
+        return 'Unknown';
+    }
+    const fromCodeowners = readCodeownersOwner(repo);
+    return fromCodeowners ?? 'Unknown';
+}
+function criticalityForService(serviceId, context) {
+    const serviceNode = context.architectureModel.nodes.find((node) => node.id === `service:${serviceId}`);
+    const criticality = serviceNode?.metadata?.['criticality'];
+    if (typeof criticality === 'string' && criticality.trim().length > 0) {
+        return criticality;
+    }
+    return 'Unknown';
+}
+function apiSurfaceForService(serviceId, context) {
+    const serviceContracts = context.contracts.filter((record) => record.repo === serviceId);
+    const byType = new Map();
+    for (const contract of serviceContracts) {
+        byType.set(contract.type, (byType.get(contract.type) ?? 0) + 1);
+    }
+    const typed = [...byType.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([type, count]) => `${type} (${count})`);
+    const insights = insightsForRepo(serviceId, context);
+    const inferred = topUnique([...insights.interfaces, ...insights.asyncPatterns].map((line) => shorten(line, 70)), 2);
+    const composed = [...typed, ...inferred];
+    if (composed.length === 0) {
+        return 'Unknown';
+    }
+    return composed.join(', ');
+}
+function dependenciesForService(serviceId, context) {
+    const sourceId = `service:${serviceId}`;
+    const dependencies = context.serviceMap.edges
+        .filter((edge) => edge.from === sourceId && edge.to.startsWith('service:'))
+        .map((edge) => edge.to.replace('service:', ''));
+    return formatList([...new Set(dependencies)].sort((a, b) => a.localeCompare(b)));
+}
+function datastoresForService(serviceId, context) {
+    const sourceId = `service:${serviceId}`;
+    const stores = context.architectureModel.edges
+        .filter((edge) => edge.from === sourceId && edge.to.startsWith('datastore:'))
+        .map((edge) => edge.to.replace('datastore:', ''));
+    return formatList([...new Set(stores)].sort((a, b) => a.localeCompare(b)));
+}
+function statusForService(serviceId, context) {
+    const repo = context.repoMap.get(serviceId);
+    if (!repo) {
+        return 'Unknown';
+    }
+    if (repo.archived) {
+        return 'Archived';
+    }
+    return 'Active';
+}
+function domainForRepo(repoName, config) {
+    const groups = config.domainGroups ?? [];
+    for (const group of groups) {
+        if (group.match.some((pattern) => repoName.toLowerCase().includes(pattern.toLowerCase()))) {
+            return group.name;
+        }
+    }
+    return 'Ungrouped';
+}
+function serviceCatalog(context) {
+    const serviceIds = context.selectedRepos
+        .filter((repo) => context.serviceMap.nodes.some((node) => node.id === `service:${repo}`))
+        .sort((a, b) => a.localeCompare(b));
+    return serviceIds.map((serviceId) => {
+        const repo = context.repoMap.get(serviceId);
+        const insights = insightsForRepo(serviceId, context);
+        const runtime = repo ? inferRuntimeFramework(repo) : 'Unknown';
+        const runtimeFromDocs = inferRuntimeFromInsights(insights);
+        const deploy = repo ? inferDeployTarget(repo) : 'Unknown';
+        const deployFromDocs = inferDeployTargetFromInsights(insights);
+        const serviceDataStores = [...new Set([...datastoresForService(serviceId, context).split(', ').filter((entry) => entry !== 'Unknown'), ...insights.dataStores])]
+            .filter((entry) => entry.length > 0)
+            .sort((a, b) => a.localeCompare(b));
+        return {
+            serviceName: serviceId,
+            repository: repo?.fullName ?? serviceId,
+            ownerTeam: ownerForService(serviceId, context),
+            runtime: runtime !== 'Unknown' ? runtime : runtimeFromDocs ?? 'Unknown',
+            apiEventSurface: apiSurfaceForService(serviceId, context),
+            dependencies: dependenciesForService(serviceId, context),
+            dataStores: formatList(serviceDataStores),
+            deployTarget: deploy !== 'Unknown' ? deploy : deployFromDocs ?? 'Unknown',
+            tier: criticalityForService(serviceId, context),
+            status: statusForService(serviceId, context),
+        };
+    });
+}
+function sectionAnchor(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-');
+}
+function renderSection(section) {
+    const lines = [];
+    lines.push(`## ${section.title}`);
+    lines.push('');
+    lines.push(...section.body);
+    lines.push('');
+    return lines.join('\n');
+}
+function splitLines(input) {
+    const normalized = input.replace(/\r\n/g, '\n');
+    if (normalized.length === 0) {
+        return [];
+    }
+    const lines = normalized.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+    return lines;
+}
+function diffLines(oldLines, newLines) {
+    const n = oldLines.length;
+    const m = newLines.length;
+    const dp = Array.from({ length: n + 1 }, () => Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            if (oldLines[i] === newLines[j]) {
+                dp[i][j] = dp[i + 1][j + 1] + 1;
+            }
+            else {
+                dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
+            }
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (oldLines[i] === newLines[j]) {
+            ops.push({ type: 'equal', line: oldLines[i] });
+            i += 1;
+            j += 1;
+            continue;
+        }
+        if (dp[i + 1][j] >= dp[i][j + 1]) {
+            ops.push({ type: 'remove', line: oldLines[i] });
+            i += 1;
+        }
+        else {
+            ops.push({ type: 'add', line: newLines[j] });
+            j += 1;
+        }
+    }
+    while (i < n) {
+        ops.push({ type: 'remove', line: oldLines[i] });
+        i += 1;
+    }
+    while (j < m) {
+        ops.push({ type: 'add', line: newLines[j] });
+        j += 1;
+    }
+    return ops;
+}
+function unifiedDiff(oldText, newText, oldLabel, newLabel) {
+    if (oldText === newText) {
+        return '';
+    }
+    const oldLines = splitLines(oldText);
+    const newLines = splitLines(newText);
+    const ops = diffLines(oldLines, newLines);
+    const context = 3;
+    const hunks = [];
+    let current;
+    for (let index = 0; index < ops.length; index += 1) {
+        if (ops[index].type === 'equal') {
+            continue;
+        }
+        const hunkStart = Math.max(0, index - context);
+        const hunkEnd = Math.min(ops.length, index + context + 1);
+        if (!current) {
+            current = { start: hunkStart, end: hunkEnd };
+            continue;
+        }
+        if (hunkStart <= current.end) {
+            current.end = Math.max(current.end, hunkEnd);
+        }
+        else {
+            hunks.push(current);
+            current = { start: hunkStart, end: hunkEnd };
+        }
+    }
+    if (current) {
+        hunks.push(current);
+    }
+    const oldPrefix = [0];
+    const newPrefix = [0];
+    for (const op of ops) {
+        const oldCount = oldPrefix[oldPrefix.length - 1] + (op.type === 'add' ? 0 : 1);
+        const newCount = newPrefix[newPrefix.length - 1] + (op.type === 'remove' ? 0 : 1);
+        oldPrefix.push(oldCount);
+        newPrefix.push(newCount);
+    }
+    const lines = [`--- ${oldLabel}`, `+++ ${newLabel}`];
+    for (const hunk of hunks) {
+        const slice = ops.slice(hunk.start, hunk.end);
+        const oldStart = oldPrefix[hunk.start] + 1;
+        const newStart = newPrefix[hunk.start] + 1;
+        const oldLen = slice.filter((entry) => entry.type !== 'add').length;
+        const newLen = slice.filter((entry) => entry.type !== 'remove').length;
+        lines.push(`@@ -${oldStart},${oldLen} +${newStart},${newLen} @@`);
+        for (const op of slice) {
+            if (op.type === 'equal') {
+                lines.push(` ${op.line}`);
+            }
+            else if (op.type === 'remove') {
+                lines.push(`-${op.line}`);
+            }
+            else {
+                lines.push(`+${op.line}`);
+            }
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+async function buildReadmeContext(mapId, db, cwd, outputPath, config) {
+    const now = new Date();
+    const threshold = config.staleThresholdHours ?? 72;
+    const scope = (0, scope_1.loadScopeManifest)(mapId, cwd);
+    const repos = (0, repoRegistry_1.listAllRepos)(db);
+    const repoMap = new Map(repos.map((repo) => [repo.name, repo]));
+    const selectedRepos = filterReposForReadme(scope, config);
+    const mapDir = node_path_1.default.join(cwd, 'maps', mapId);
+    const serviceMap = loadServiceMap(mapId, scope, repoMap, mapDir);
+    const contracts = loadContracts(mapId, scope, repoMap, mapDir);
+    const model = loadArchitectureModel(mapId, db, cwd);
+    const diagrams = diagramPaths(mapId, cwd);
+    const sourceRefs = [];
+    sourceRefs.push(sourceFromFile('scope', 'Map scope manifest', node_path_1.default.join(mapDir, 'scope.json'), cwd, threshold, now, true));
+    sourceRefs.push(sourceFromFile('service-map-json', 'Service map JSON', node_path_1.default.join(mapDir, 'service-map.json'), cwd, threshold, now, true));
+    sourceRefs.push(sourceFromFile('service-map-md', 'Service map Markdown', node_path_1.default.join(mapDir, 'service-map.md'), cwd, threshold, now, false));
+    sourceRefs.push(sourceFromFile('service-map-mmd', 'Service map Mermaid', node_path_1.default.join(mapDir, 'service-map.mmd'), cwd, threshold, now, false));
+    sourceRefs.push(sourceFromFile('contracts-json', 'Contracts JSON', node_path_1.default.join(mapDir, 'contracts.json'), cwd, threshold, now, true));
+    sourceRefs.push(sourceFromFile('contracts-md', 'Contracts Markdown', node_path_1.default.join(mapDir, 'contracts.md'), cwd, threshold, now, false));
+    sourceRefs.push(sourceFromFile('docs-architecture', 'Generated architecture doc', node_path_1.default.join(cwd, 'docs', 'architecture', `${mapId}.md`), cwd, threshold, now, false));
+    sourceRefs.push(sourceFromFile('docs-dependencies', 'Generated dependency summary', node_path_1.default.join(cwd, 'catalog', 'dependencies', `${mapId}.md`), cwd, threshold, now, false));
+    sourceRefs.push(sourceFromFile('architecture-model', 'Architecture model', node_path_1.default.join(cwd, 'maps', mapId, 'architecture', 'model.json'), cwd, threshold, now, false));
+    sourceRefs.push(sourceFromFile('architecture-validation', 'Architecture validation', node_path_1.default.join(cwd, 'maps', mapId, 'architecture', 'validation.json'), cwd, threshold, now, false));
+    sourceRefs.push(sourceFromRepoSync(repos, selectedRepos, threshold, now));
+    let githubToken;
+    try {
+        const sdxConfig = (0, config_1.loadConfig)(cwd);
+        const tokenEnv = sdxConfig.github?.tokenEnv?.trim() || 'GITHUB_TOKEN';
+        githubToken = process.env[tokenEnv];
+    }
+    catch {
+        githubToken = process.env['GITHUB_TOKEN'];
+    }
+    const repoInsights = await buildAllRepoInsights(selectedRepos, repoMap, githubToken);
+    return {
+        cwd,
+        mapId,
+        scope,
+        selectedRepos,
+        repoMap,
+        serviceMap,
+        contracts,
+        architectureModel: model,
+        diagrams,
+        sources: sourceRefs,
+        staleThresholdHours: threshold,
+        now,
+        outputPath,
+        config,
+        sourceSnapshotAt: computeSnapshotTimestamp(sourceRefs, now),
+        coreRequestPath: findCoreRequestPath(model, serviceMap),
+        sourceRepoSyncAt: sourceRefs.find((source) => source.id === 'repo-sync')?.generatedAt,
+        repoInsights,
+    };
+}
+function buildSections(context) {
+    const outputPath = context.outputPath;
+    const includeC4Links = context.config.diagram?.includeC4Links ?? true;
+    const links = {
+        systemContext: toLinkPath(context.diagrams.systemContext, outputPath),
+        serviceDependency: toLinkPath(context.diagrams.serviceDependency, outputPath),
+        sequence: toLinkPath(context.diagrams.sequence, outputPath),
+        optionalSystemLandscape: toLinkPath(context.diagrams.optionalSystemLandscape, outputPath),
+        optionalContainer: toLinkPath(context.diagrams.optionalContainer, outputPath),
+        optionalArchitectureIndex: toLinkPath(context.diagrams.optionalArchitectureIndex, outputPath),
+    };
+    const catalogRows = serviceCatalog(context);
+    const asyncContracts = context.contracts.filter((record) => record.type === 'asyncapi');
+    const allInsights = context.selectedRepos.map((repoName) => ({
+        repoName,
+        insights: insightsForRepo(repoName, context),
+    }));
+    const datastoreNodes = context.architectureModel.nodes.filter((node) => node.type === 'datastore');
+    const adrDir = node_path_1.default.join(context.cwd, 'docs', 'adr');
+    const adrFiles = (0, fs_1.fileExists)(adrDir)
+        ? node_fs_1.default
+            .readdirSync(adrDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && /\.md$/i.test(entry.name))
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b))
+        : [];
+    const summaryHighlights = allInsights
+        .filter((entry) => entry.insights.summary !== 'Unknown')
+        .sort((a, b) => a.repoName.localeCompare(b.repoName))
+        .slice(0, 8)
+        .map((entry) => `- **${entry.repoName}**: ${shorten(entry.insights.summary, 220)}`);
+    const coreFlowLines = context.coreRequestPath.length > 0
+        ? context.coreRequestPath.map((edge) => {
+            const from = edge.from.replace('service:', '');
+            const to = edge.to.replace('service:', '');
+            return `- ${from} -> ${to}`;
+        })
+        : ['- Unknown'];
+    const coreFlowServices = topUnique(context.coreRequestPath.flatMap((edge) => [edge.from.replace('service:', ''), edge.to.replace('service:', '')]), 8);
+    const coreFlowNotes = coreFlowServices.map((serviceId) => {
+        const insights = insightsForRepo(serviceId, context);
+        const line = insights.responsibilities[0] ?? insights.interfaces[0] ?? insights.summary;
+        return `- **${serviceId}**: ${shorten(line, 180)}`;
+    });
+    const asyncHighlights = topUnique(allInsights.flatMap((entry) => entry.insights.asyncPatterns.map((line) => `- **${entry.repoName}**: ${shorten(line, 180)}`)), 12);
+    const securityHighlights = topUnique(allInsights.flatMap((entry) => entry.insights.security.map((line) => `- **${entry.repoName}**: ${shorten(line, 180)}`)), 10);
+    const runbookHighlights = topUnique(allInsights.flatMap((entry) => entry.insights.runbooks.map((line) => `- **${entry.repoName}**: ${shorten(line, 180)}`)), 10);
+    const localDevCommands = topUnique(allInsights.flatMap((entry) => entry.insights.localDevelopment), 12);
+    const glossaryTerms = topUnique(allInsights.flatMap((entry) => entry.insights.glossary), 20).sort((a, b) => a.localeCompare(b));
+    const repoRows = context.selectedRepos
+        .map((repoName) => {
+        const repo = context.repoMap.get(repoName);
+        const insights = insightsForRepo(repoName, context);
+        return {
+            fullName: repo?.fullName ?? repoName,
+            owner: ownerForService(repoName, context),
+            domain: domainForRepo(repoName, context.config),
+            role: shorten(insights.responsibilities[0] ?? insights.summary, 140),
+            docs: formatLinks(insights.docReferences, 3),
+        };
+    })
+        .sort((a, b) => a.fullName.localeCompare(b.fullName));
+    const environmentRows = catalogRows.map((row) => {
+        const insights = insightsForRepo(row.serviceName, context);
+        const note = insights.deployment[0] ?? insights.runbooks[0] ?? 'Unknown';
+        return `| ${row.serviceName} | ${row.deployTarget} | ${row.runtime} | ${shorten(note, 140)} |`;
+    });
+    const contractsByRepo = new Map();
+    for (const contract of context.contracts) {
+        const entries = contractsByRepo.get(contract.repo) ?? [];
+        entries.push(contract);
+        contractsByRepo.set(contract.repo, entries);
+    }
+    const contractRows = context.selectedRepos.map((repoName) => {
+        const contracts = contractsByRepo.get(repoName) ?? [];
+        const summary = contracts.length > 0
+            ? contracts.map((contract) => `${contract.type}:${contract.path}`).slice(0, 4).join('<br/>')
+            : 'Unknown';
+        return `| ${repoName} | ${summary} |`;
+    });
+    const adrLinks = topUnique([
+        ...adrFiles.map((fileName) => `- [${fileName}](./docs/adr/${fileName})`),
+        ...allInsights.flatMap((entry) => entry.insights.adrs.map((candidate) => /^https?:\/\//.test(candidate)
+            ? `- [${entry.repoName} ADR](${candidate})`
+            : `- ${entry.repoName}: \`${candidate}\``)),
+    ], 30);
+    const sectionById = {
+        what_is_this_system: {
+            id: 'what_is_this_system',
+            title: SECTION_TITLES['what_is_this_system'],
+            body: [
+                context.config.customIntro ??
+                    'SDX traverses repository documentation, contracts, and dependency signals to keep this architecture guide current.',
+                '',
+                `- Scope: \`${context.scope.org}\` org, map \`${context.mapId}\``,
+                `- Repositories in scope: ${context.selectedRepos.length}`,
+                `- Services identified: ${catalogRows.length}`,
+                '',
+                ...(summaryHighlights.length > 0
+                    ? ['### Service purpose highlights', '', ...summaryHighlights]
+                    : ['### Service purpose highlights', '', '- Unknown']),
+            ],
+            sourceIds: ['scope', 'repo-sync', 'service-map-json'],
+        },
+        architecture_glance: {
+            id: 'architecture_glance',
+            title: SECTION_TITLES['architecture_glance'],
+            body: (() => {
+                const lines = [
+                    `- [System context diagram](${links.systemContext})`,
+                    `- [Service dependency graph](${links.serviceDependency})`,
+                    `- [Core request flow sequence](${links.sequence})`,
+                    (0, fs_1.fileExists)(context.diagrams.optionalArchitectureIndex)
+                        ? `- [Architecture pack index](${links.optionalArchitectureIndex})`
+                        : '- Architecture pack index: Not available',
+                ];
+                if (includeC4Links) {
+                    lines.push((0, fs_1.fileExists)(context.diagrams.optionalSystemLandscape)
+                        ? `- [Optional C4 landscape](${links.optionalSystemLandscape})`
+                        : '- Optional C4 landscape: Not available');
+                    lines.push((0, fs_1.fileExists)(context.diagrams.optionalContainer)
+                        ? `- [Optional C4 container](${links.optionalContainer})`
+                        : '- Optional C4 container: Not available');
+                }
+                if (coreFlowLines.length > 0) {
+                    lines.push('');
+                    lines.push('### Primary request path');
+                    lines.push(...coreFlowLines);
+                }
+                return lines;
+            })(),
+            sourceIds: [
+                'service-map-json',
+                'architecture-model',
+                'diagram-system-context',
+                'diagram-service-dependency',
+                'diagram-core-sequence',
+                'diagram-c4-landscape',
+                'diagram-c4-container',
+            ],
+        },
+        service_catalog: {
+            id: 'service_catalog',
+            title: SECTION_TITLES['service_catalog'],
+            body: [
+                '| Service name | Repository | Owner/team | Runtime/framework | API/event surface | Dependencies | Data stores | Deploy target | Tier/criticality | Status |',
+                '|---|---|---|---|---|---|---|---|---|---|',
+                ...(catalogRows.length > 0
+                    ? catalogRows.map((row) => `| ${row.serviceName} | ${row.repository} | ${row.ownerTeam} | ${row.runtime} | ${row.apiEventSurface} | ${row.dependencies} | ${row.dataStores} | ${row.deployTarget} | ${row.tier} | ${row.status} |`)
+                    : ['| Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown |']),
+                '',
+                '### Service briefs',
+                ...(summaryHighlights.length > 0 ? summaryHighlights : ['- Unknown']),
+            ],
+            sourceIds: ['service-map-json', 'contracts-json', 'architecture-model', 'repo-sync'],
+        },
+        critical_flows: {
+            id: 'critical_flows',
+            title: SECTION_TITLES['critical_flows'],
+            body: [
+                `- Primary sequence diagram: [core-request-flow.mmd](${links.sequence})`,
+                '- Current highest-confidence request chain:',
+                ...coreFlowLines,
+                '',
+                '### Service responsibilities in this flow',
+                ...(coreFlowNotes.length > 0 ? coreFlowNotes : ['- Unknown']),
+            ],
+            sourceIds: ['architecture-model', 'service-map-json', 'docs-dependencies', 'diagram-core-sequence'],
+        },
+        event_async_topology: {
+            id: 'event_async_topology',
+            title: SECTION_TITLES['event_async_topology'],
+            body: [
+                '| Contract | Repository | Version | Compatibility | Producers | Consumers |',
+                '|---|---|---|---|---|---|',
+                ...(asyncContracts.length > 0
+                    ? asyncContracts.map((record) => `| ${record.path} | ${record.repo} | ${record.version ?? 'Unknown'} | ${record.compatibilityStatus} | ${formatList(record.producers)} | ${formatList(record.consumers)} |`)
+                    : ['| Unknown | Unknown | Unknown | Unknown | Unknown | Unknown |']),
+                '',
+                '### Async behavior from repository docs',
+                ...(asyncHighlights.length > 0 ? asyncHighlights : ['- Unknown']),
+            ],
+            sourceIds: ['contracts-json', 'architecture-model'],
+        },
+        contracts_index: {
+            id: 'contracts_index',
+            title: SECTION_TITLES['contracts_index'],
+            body: [
+                '| Repository | Contract surfaces |',
+                '|---|---|',
+                ...(contractRows.length > 0 ? contractRows : ['| Unknown | Unknown |']),
+            ],
+            sourceIds: ['contracts-json', 'contracts-md'],
+        },
+        repository_index: {
+            id: 'repository_index',
+            title: SECTION_TITLES['repository_index'],
+            body: [
+                '| Repository | Owner/team | Domain | Role in system | Key docs |',
+                '|---|---|---|---|---|',
+                ...(repoRows.length > 0
+                    ? repoRows.map((row) => `| ${row.fullName} | ${row.owner} | ${row.domain} | ${row.role} | ${row.docs} |`)
+                    : ['| Unknown | Unknown | Unknown | Unknown | Unknown |']),
+            ],
+            sourceIds: ['scope', 'repo-sync'],
+        },
+        environments_deployment: {
+            id: 'environments_deployment',
+            title: SECTION_TITLES['environments_deployment'],
+            body: [
+                '| Service | Deploy target | Runtime/framework | Environment notes |',
+                '|---|---|---|---|',
+                ...(environmentRows.length > 0 ? environmentRows : ['| Unknown | Unknown | Unknown | Unknown |']),
+            ],
+            sourceIds: ['service-map-json', 'repo-sync', 'architecture-model'],
+        },
+        data_stores_boundaries: {
+            id: 'data_stores_boundaries',
+            title: SECTION_TITLES['data_stores_boundaries'],
+            body: [
+                '| Data store | Depending services | Boundary notes |',
+                '|---|---|---|',
+                ...(datastoreNodes.length > 0
+                    ? datastoreNodes
+                        .sort((a, b) => a.label.localeCompare(b.label))
+                        .map((node) => {
+                        const dependers = context.architectureModel.edges
+                            .filter((edge) => edge.to === node.id && edge.from.startsWith('service:'))
+                            .map((edge) => edge.from.replace('service:', ''))
+                            .sort((a, b) => a.localeCompare(b));
+                        return `| ${node.label} | ${formatList([...new Set(dependers)])} | ${String(node.metadata?.['boundary'] ?? 'Unknown')} |`;
+                    })
+                    : ['| Unknown | Unknown | Unknown |']),
+            ],
+            sourceIds: ['architecture-model'],
+        },
+        security_compliance: {
+            id: 'security_compliance',
+            title: SECTION_TITLES['security_compliance'],
+            body: [
+                ...(securityHighlights.length > 0
+                    ? securityHighlights
+                    : [
+                        '- Authentication and authorization approach: Unknown',
+                        '- Data classification and compliance posture: Unknown',
+                        '- Secret management and key handling: Unknown',
+                    ]),
+            ],
+            sourceIds: ['architecture-model', 'contracts-json'],
+        },
+        local_dev_contribution: {
+            id: 'local_dev_contribution',
+            title: SECTION_TITLES['local_dev_contribution'],
+            body: [
+                '```bash',
+                './scripts/sdx status',
+                `./scripts/sdx repo sync --org ${context.scope.org}`,
+                `./scripts/sdx map build ${context.mapId}`,
+                `./scripts/sdx contracts extract --map ${context.mapId}`,
+                `./scripts/sdx architecture generate --map ${context.mapId}`,
+                `./scripts/sdx docs readme --map ${context.mapId}`,
+                '```',
+                '',
+                '### Commands found in service docs',
+                ...(localDevCommands.length > 0
+                    ? ['```bash', ...localDevCommands.map((command) => command.replace(/`/g, '')), '```']
+                    : ['- Unknown']),
+            ],
+            sourceIds: ['scope', 'service-map-json', 'contracts-json'],
+        },
+        runbooks_escalation: {
+            id: 'runbooks_escalation',
+            title: SECTION_TITLES['runbooks_escalation'],
+            body: [
+                ...(runbookHighlights.length > 0
+                    ? runbookHighlights
+                    : ['- Runbooks and escalation notes are not explicitly documented in scanned repositories.']),
+            ],
+            sourceIds: ['architecture-model', 'repo-sync'],
+        },
+        adr_index: {
+            id: 'adr_index',
+            title: SECTION_TITLES['adr_index'],
+            body: [...(adrLinks.length > 0 ? adrLinks : ['- Unknown'])],
+            sourceIds: ['docs-architecture'],
+        },
+        glossary: {
+            id: 'glossary',
+            title: SECTION_TITLES['glossary'],
+            body: [
+                ...(glossaryTerms.length > 0
+                    ? glossaryTerms.map((term) => `- **${term}**: Refer to service-level docs for context.`)
+                    : ['- Unknown']),
+            ],
+            sourceIds: ['scope', 'service-map-json', 'contracts-json', 'architecture-model'],
+        },
+        changelog_metadata: {
+            id: 'changelog_metadata',
+            title: SECTION_TITLES['changelog_metadata'],
+            body: [
+                `- Last generated: ${context.sourceSnapshotAt}`,
+                `- Source snapshot: ${context.sourceSnapshotAt}`,
+                `- Map: ${context.mapId}`,
+                `- Tooling: SDX CLI ${(0, version_1.getCliPackageVersion)()} (schema ${constants_1.SCHEMA_VERSION})`,
+                '- Run `./scripts/sdx docs readme --map <map-id> --check` in CI to verify freshness and drift.',
+            ],
+            sourceIds: context.sources.map((source) => source.id),
+        },
+    };
+    return exports.README_SECTION_ORDER.map((sectionId) => sectionById[sectionId]);
+}
+function renderReadme(sections, context) {
+    const lines = [
+        `# ${context.scope.org} System Architecture`,
+        '',
+        `This README is the architecture entry point for the \`${context.scope.org}\` engineering organization.`,
+        '',
+        `It is generated by SDX from repository docs, contracts, and map artifacts using \`${context.mapId}\`.`,
+        '',
+        '## Table of contents',
+        '',
+        ...sections.map((section) => `- [${section.title}](#${sectionAnchor(section.title)})`),
+        '',
+    ];
+    for (const section of sections) {
+        lines.push(renderSection(section));
+    }
+    return {
+        content: `${lines.join('\n').trimEnd()}\n`,
+        sourceRefs: context.sources,
+    };
+}
+function checkFailures(existingContent, renderedContent, sources) {
+    const stale = sources.filter((source) => source.required && source.stale);
+    const missing = sources.filter((source) => source.required && !source.exists);
+    const changed = existingContent !== renderedContent;
+    return { stale, missing, changed };
+}
+function summarizeResult(outputPath, staleSources, missingSources, changed, checkMode) {
+    const lines = [`README output: ${outputPath}`];
+    lines.push(`Content changed: ${changed ? 'yes' : 'no'}`);
+    lines.push(`Stale sources: ${staleSources.length}`);
+    lines.push(`Missing required sources: ${missingSources.length}`);
+    if (staleSources.length > 0) {
+        lines.push(`Stale source labels: ${staleSources.map((source) => source.label).join(', ')}`);
+    }
+    if (missingSources.length > 0) {
+        lines.push(`Missing source labels: ${missingSources.map((source) => source.label).join(', ')}`);
+    }
+    if (checkMode) {
+        const failed = staleSources.length > 0 || missingSources.length > 0 || changed;
+        lines.push(`Check result: ${failed ? 'FAIL' : 'PASS'}`);
+    }
+    return lines.join('\n');
+}
+async function generateReadme(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.output ?? 'README.md');
+    const includeSections = options.includeSections ?? [];
+    const excludeSections = options.excludeSections ?? [];
+    if (options.check && options.dryRun) {
+        throw new Error('Use either --check or --dry-run, not both.');
+    }
+    const { config, sourcePath } = loadReadmeConfig(cwd);
+    const selectedSections = selectSections(config, includeSections, excludeSections);
+    const context = await buildReadmeContext(options.mapId, options.db, cwd, outputPath, config);
+    if (sourcePath) {
+        context.sources.push(sourceFromFile('readme-config', 'README config', sourcePath, cwd, context.staleThresholdHours, context.now, false));
+    }
+    const writeEnabled = !options.check && !options.dryRun;
+    const diagramResult = ensureRequiredDiagrams(context, options.db, cwd, writeEnabled);
+    context.sources.push(...diagramResult.diagramSources);
+    upsertSourceRef(context.sources, sourceFromFile('docs-architecture', 'Generated architecture doc', node_path_1.default.join(cwd, 'docs', 'architecture', `${options.mapId}.md`), cwd, context.staleThresholdHours, context.now, false));
+    upsertSourceRef(context.sources, sourceFromFile('architecture-model', 'Architecture model', node_path_1.default.join(cwd, 'maps', options.mapId, 'architecture', 'model.json'), cwd, context.staleThresholdHours, context.now, false));
+    upsertSourceRef(context.sources, sourceFromFile('architecture-validation', 'Architecture validation', node_path_1.default.join(cwd, 'maps', options.mapId, 'architecture', 'validation.json'), cwd, context.staleThresholdHours, context.now, false));
+    context.sourceSnapshotAt = computeSnapshotTimestamp(context.sources, context.now);
+    const orderedSections = buildSections(context).filter((section) => selectedSections.includes(section.id));
+    const existingContent = (0, fs_1.safeReadText)(outputPath);
+    const rendered = renderReadme(orderedSections, context);
+    const { stale, missing, changed } = checkFailures(existingContent, rendered.content, rendered.sourceRefs);
+    const shouldWrite = writeEnabled && changed;
+    if (shouldWrite) {
+        (0, fs_1.writeTextFile)(outputPath, rendered.content);
+    }
+    const diff = options.dryRun || (options.check && changed)
+        ? unifiedDiff(existingContent, rendered.content, `${asRelative(outputPath, cwd)}.current`, `${asRelative(outputPath, cwd)}.next`)
+        : undefined;
+    const checkPassed = !options.check || (stale.length === 0 && missing.length === 0 && !changed);
+    return {
+        outputPath,
+        sections: selectedSections,
+        stale: stale.length > 0,
+        staleSources: stale,
+        missingSources: missing,
+        changed,
+        wroteFile: shouldWrite,
+        checkPassed,
+        summary: summarizeResult(outputPath, stale, missing, changed, Boolean(options.check)),
+        diff,
+    };
+}