sdtk-brain-kit 0.1.0

package/src/lib/wiki-compile.js

@@ -0,0 +1,2108 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { CliError, ValidationError } = require("./errors");
+const {
+  assertCanonicalWikiWritePath,
+  assertWikiWorkspaceWritePath,
+  getCanonicalWikiPath,
+  getLegacyPersonalBrainPath,
+  getWikiReportsPath,
+  getWikiWorkspacePath,
+  isPathInsideOrEqual,
+  resolveProjectPath,
+} = require("./wiki-paths");
+
+const REPORT_PREFIX = "compile-dry-run-preview";
+const APPLY_PLAN_PREFIX = "compile-apply-plan";
+const APPLY_PLAN_RECORD_TYPE = "sdtk_wiki_compile_apply_plan";
+const APPLY_PLAN_SCHEMA_VERSION = 1;
+const CANONICAL_WIKI_RELATIVE = "wiki";
+const APPLY_MODE = "create_only_or_same_content_noop";
+const ALLOWED_OPERATION_TYPES = new Set([
+  "append_section",
+  "create_page",
+  "add_relation",
+  "add_source_ref",
+]);
+
+function todayStamp(date = new Date()) {
+  return date.toISOString().slice(0, 10);
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function stableHash(value) {
+  return require("crypto").createHash("sha256").update(String(value)).digest("hex");
+}
+
+function isRemoteUrl(value) {
+  return /^(?:https?|ftp):\/\//i.test(String(value || ""));
+}
+
+function resolvePlanPath(planArg, projectPath) {
+  if (!planArg) {
+    throw new ValidationError("sdtk-brain wiki compile requires --plan <path>. No project files were changed.");
+  }
+  if (isRemoteUrl(planArg)) {
+    throw new ValidationError("Remote URL plan inputs are not supported for compile dry-run preview. No project files were changed.");
+  }
+
+  const candidate = path.isAbsolute(planArg) ? path.resolve(planArg) : path.resolve(projectPath, planArg);
+  if (!isPathInsideOrEqual(candidate, projectPath)) {
+    throw new ValidationError(`--plan must resolve inside the project root: ${candidate}. No project files were changed.`);
+  }
+  if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+    throw new ValidationError(`--plan is not a valid file: ${candidate}. No project files were changed.`);
+  }
+  return candidate;
+}
+
+function ensureExistingWorkspace(projectPath) {
+  const workspacePath = getWikiWorkspacePath(projectPath);
+  if (!fs.existsSync(workspacePath) || !fs.statSync(workspacePath).isDirectory()) {
+    throw new ValidationError(
+      `No SDTK-BRAIN workspace found at ${workspacePath}. Run "sdtk-brain init" or "sdtk-brain atlas build" first. No project files were changed.`
+    );
+  }
+  return workspacePath;
+}
+
+function firstSourceRef(record) {
+  const refs = asArray(record.source_refs || record.sourceRefs);
+  return refs.length > 0 ? String(refs[0]) : "semantic_extraction_report";
+}
+
+function sourceHashFor(sourceById, sourceId, fallback = "") {
+  const source = sourceById.get(sourceId);
+  return source && source.source_hash ? String(source.source_hash) : fallback;
+}
+
+function refsFor(record) {
+  return [
+    ...asArray(record.source_refs || record.sourceRefs),
+    ...asArray(record.provenance_refs || record.provenanceRefs),
+    record.source_logical_path,
+    record.source_relative_path,
+  ].filter(Boolean).map(String);
+}
+
+function sourceRefsFor(record) {
+  const refs = asArray(record.source_refs || record.sourceRefs);
+  if (record.source_id) refs.unshift(record.source_id);
+  return [...new Set(refs.filter(Boolean).map(String))];
+}
+
+function provenanceRefsFor(record) {
+  return [...new Set(asArray(record.provenance_refs || record.provenanceRefs).filter(Boolean).map(String))];
+}
+
+function mdList(values) {
+  const items = asArray(values).filter(Boolean).map(String);
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "- None recorded.";
+}
+
+function mdLinkedList(values) {
+  const items = asArray(values).filter(Boolean);
+  if (items.length === 0) return "- None recorded.";
+  return items.map((item) => {
+    const text = String(item);
+    if (/^https?:\/\//i.test(text)) return `- [${text}](${text})`;
+    return `- ${text}`;
+  }).join("\n");
+}
+
+function quoteBlock(value) {
+  const text = String(value || "").replace(/\r?\n/g, " ").trim();
+  return text ? `> ${text}` : "> No extracted snippet recorded in the local source.";
+}
+
+function topicLabelList(entity) {
+  const topics = [...new Set(asArray(entity.topics).filter(Boolean).map(String))];
+  return topics.length > 0 ? topics.map((topic) => `- ${topic}`).join("\n") : "- No topic labels extracted from local sources.";
+}
+
+function relatedRepoList(entity) {
+  const repos = asArray(entity.related_repos);
+  if (repos.length === 0) return "- No related repositories inferred from local topic overlap.";
+  return repos.map((repo) => {
+    const label = repo.name || repo.entity_id || "related repo";
+    const suffix = asArray(repo.shared_topics).length > 0 ? ` (shared topics: ${asArray(repo.shared_topics).join(", ")})` : "";
+    return repo.github_url ? `- [${label}](${repo.github_url})${suffix}` : `- ${label}${suffix}`;
+  }).join("\n");
+}
+
+function relativePersonalBrainLink(targetPagePath) {
+  const text = toPosix(targetPagePath || "");
+  if (text.startsWith("wiki/")) return text.slice("wiki/".length);
+  const marker = ".brain/personal-brain/";
+  const idx = text.indexOf(marker);
+  return idx >= 0 ? text.slice(idx + marker.length) : text;
+}
+
+function conceptAxisList(concept) {
+  const axes = asArray(concept.key_axes);
+  if (axes.length === 0) return "- No key axes were inferred from local evidence.";
+  return axes.map((axis) => `- ${axis.name}: ${axis.evidence_count || 1} local evidence reference(s).`).join("\n");
+}
+
+function conceptImplementationList(concept) {
+  const entities = asArray(concept.related_entity_details);
+  if (entities.length === 0) return "- No implementation examples were extracted from local sources.";
+  return entities.slice(0, 10).map((entity) => {
+    const label = entity.repo_owner && entity.repo_name ? `${entity.repo_owner}/${entity.repo_name}` : (entity.name || "tool candidate");
+    const link = entity.target_page_path ? relativePersonalBrainLink(entity.target_page_path) : "";
+    const target = link ? `[${label}](../${link})` : label;
+    const url = entity.github_url ? `; ${entity.github_url}` : "";
+    return `- ${target}: ${entity.summary || `Local candidate in ${entity.category || "uncategorized"}`}${url}`;
+  }).join("\n");
+}
+
+function conceptPatternList(concept) {
+  const patterns = asArray(concept.patterns);
+  if (patterns.length === 0) return "- No repeated pattern was inferred from local evidence.";
+  return patterns.map((pattern) => `- ${pattern.pattern}: ${pattern.evidence}`).join("\n");
+}
+
+function conceptRelatedPagesList(concept) {
+  const pages = asArray(concept.related_entity_details)
+    .map((entity) => entity.target_page_path)
+    .filter(Boolean)
+    .map((target) => `../${relativePersonalBrainLink(target)}`);
+  return mdList([...new Set(pages)].slice(0, 12));
+}
+
+function confidenceSummaryList(summary) {
+  if (!summary || typeof summary !== "object") return "- No source confidence summary recorded.";
+  const rows = Object.entries(summary).filter(([, count]) => Number(count) > 0);
+  return rows.length > 0 ? rows.map(([tier, count]) => `- ${tier}: ${count}`).join("\n") : "- No source confidence summary recorded.";
+}
+
+function comparisonMatrix(comparison) {
+  const rows = asArray(comparison.matrix_rows);
+  if (rows.length === 0) return "| Candidate | Category | Local evidence | Strengths | Caveats | Recommendation |\n|---|---|---:|---|---|---|\n| None recorded | - | 0 | - | - | - |";
+  const table = [
+    "| Candidate | Category | Local evidence | Strengths | Caveats | Recommendation |",
+    "|---|---|---:|---|---|---|",
+  ];
+  for (const row of rows) {
+    const candidate = row.github_url ? `[${row.name || row.entity_id}](${row.github_url})` : (row.name || row.entity_id || "candidate");
+    table.push(`| ${candidate} | ${row.category || "uncategorized"} | ${row.source_ref_count || 0} | ${asArray(row.strengths).slice(0, 3).join("<br>") || "-"} | ${asArray(row.caveats).slice(0, 3).join("<br>") || "-"} | ${row.local_recommendation || "review"} |`);
+  }
+  return table.join("\n");
+}
+
+function candidateToolList(records) {
+  const rows = asArray(records);
+  if (rows.length === 0) return "- No candidate tools recorded.";
+  return rows.slice(0, 12).map((row) => {
+    const label = row.github_url ? `[${row.name || row.entity_id}](${row.github_url})` : (row.name || row.entity_id || "candidate");
+    return `- ${label}: ${row.local_recommendation || "review"}; confidence ${row.source_confidence || row.confidence_tier || "unknown"}.`;
+  }).join("\n");
+}
+
+function localCandidateLabel(record) {
+  if (!record) return "local candidate";
+  if (record.repo_owner && record.repo_name) return `${record.repo_owner}/${record.repo_name}`;
+  if (record.owner && (record.repo_name || record.repo)) return `${record.owner}/${record.repo_name || record.repo}`;
+  return record.name || record.entity_id || "local candidate";
+}
+
+function candidateEvidenceCount(record) {
+  const explicit = Number(record.source_ref_count || record.local_evidence_count || record.evidence_count || 0);
+  if (explicit > 0) return explicit;
+  const refs = sourceRefsFor(record);
+  return refs.length > 0 ? refs.length : 1;
+}
+
+function topLocalCandidates(records, limit = 3) {
+  return asArray(records)
+    .map((record) => ({
+      record,
+      label: localCandidateLabel(record),
+      evidence: candidateEvidenceCount(record),
+      category: record.category || record.local_category || "uncategorized",
+      confidence: record.source_confidence || record.confidence_tier || record.confidence || "unknown",
+      topics: asArray(record.topics || record.shared_topics).filter(Boolean).map(String),
+      recommendation: record.local_recommendation || record.recommendation || "review",
+      summary: record.summary || record.evidence || "",
+    }))
+    .sort((a, b) => (b.evidence - a.evidence) || a.label.localeCompare(b.label))
+    .slice(0, limit);
+}
+
+function refinedCandidateSentence(candidate) {
+  const topicText = candidate.topics.length > 0 ? `; local topics: ${candidate.topics.slice(0, 4).join(", ")}` : "";
+  return `${candidate.label} (${candidate.category}) has ${candidate.evidence} local evidence reference(s), confidence ${candidate.confidence}${topicText}.`;
+}
+
+function conceptDecisionBrief(concept) {
+  const title = recordTitle(concept, "Concept");
+  const related = asArray(concept.related_entity_details);
+  const candidates = topLocalCandidates(related, 3);
+  const sourceCount = sourceRefCount(concept);
+  const axisNames = asArray(concept.key_axes).map((axis) => axis.name || axis).filter(Boolean).slice(0, 4);
+  const lines = [
+    `- Local evidence profile: ${related.length} related tool candidate(s), ${sourceCount} source reference(s), ${axisNames.length} decision axis/axes.`,
+  ];
+  if (candidates.length > 0) {
+    lines.push(`- First review target: ${refinedCandidateSentence(candidates[0])}`);
+    if (candidates.length > 1) {
+      lines.push(`- Compare next: ${candidates.slice(1).map((candidate) => `${candidate.label} (${candidate.evidence} local ref(s))`).join("; ")}.`);
+    }
+  } else {
+    lines.push("- First review target: no concrete tool candidate was linked to this concept in local evidence.");
+  }
+  if (axisNames.length > 0) {
+    lines.push(`- Decision axes to preserve: ${axisNames.join(", ")}.`);
+  }
+  lines.push(`- Local-only boundary: treat ${title} as a decision queue from local notes, not as proof of current repository health, license, or adoption readiness.`);
+  return lines.join("\n");
+}
+
+function comparisonDecisionGuidance(comparison) {
+  const rows = asArray(comparison.matrix_rows);
+  const candidates = topLocalCandidates(rows, 4);
+  const axisNames = asArray(comparison.decision_axes).map((axis) => axis.name || axis).filter(Boolean).slice(0, 5);
+  const lines = [
+    `- Use this comparison to rank ${rows.length} local candidate(s) across ${axisNames.length || "the recorded"} decision axis/axes.`,
+  ];
+  if (candidates.length > 0) {
+    lines.push(`- Local shortlist: ${candidates.map((candidate) => `${candidate.label} (${candidate.evidence} ref(s), ${candidate.recommendation})`).join("; ")}.`);
+  }
+  if (axisNames.length > 0) {
+    lines.push(`- Review order: score candidates first on ${axisNames.join(", ")}, then verify external facts separately.`);
+  }
+  lines.push("- Do not convert a local shortlist into an adoption recommendation until license, maintenance, security, and current repository identity are verified outside this local evidence set.");
+  return lines.join("\n");
+}
+
+function synthesisDecisionNarrative(synthesis) {
+  const rows = asArray(synthesis.candidate_tools);
+  const candidates = topLocalCandidates(rows, 4);
+  const axisNames = asArray(synthesis.landscape_axes).map((axis) => axis.name || axis).filter(Boolean).slice(0, 5);
+  const lines = [
+    `- This synthesis frames ${rows.length} local candidate(s) as a review backlog, not a final recommendation.`,
+  ];
+  if (candidates.length > 0) {
+    lines.push(`- Best first inspection path: ${candidates.map((candidate) => `${candidate.label} (${candidate.evidence} ref(s), ${candidate.confidence})`).join("; ")}.`);
+  }
+  if (axisNames.length > 0) {
+    lines.push(`- Decision lens: ${axisNames.join(", ")}.`);
+  }
+  if (synthesis.related_comparison_path) {
+    lines.push(`- Use the related comparison page before making a tool choice: ../${relativePersonalBrainLink(synthesis.related_comparison_path)}.`);
+  }
+  lines.push("- Keep unverified claims labeled: local snippets can explain why a tool entered the queue, but not whether it is currently mature, licensed correctly, or maintained.");
+  return lines.join("\n");
+}
+
+function mdEscapeTable(value) {
+  return String(value ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
+}
+
+function rootLink(targetPagePath) {
+  const rel = relativePersonalBrainLink(targetPagePath);
+  return rel ? toPosix(rel) : "";
+}
+
+function dashboardLink(targetPagePath) {
+  const rel = relativePersonalBrainLink(targetPagePath);
+  return rel ? `../${toPosix(rel)}` : "";
+}
+
+function sourceRefCount(record) {
+  return sourceRefsFor(record).length;
+}
+
+function highSignalTools(payload, limit = 12) {
+  return asArray(payload.tool_entities)
+    .map((tool) => ({
+      title: recordTitle(tool, "tool"),
+      path: tool.target_page_path,
+      github_url: tool.github_url,
+      category: tool.category || "uncategorized",
+      topics: asArray(tool.topics).filter(Boolean).map(String),
+      source_refs: sourceRefCount(tool),
+      confidence: tool.confidence_tier || tool.confidence || "medium",
+      summary: tool.summary || "",
+    }))
+    .sort((a, b) => (b.source_refs - a.source_refs) || a.title.localeCompare(b.title))
+    .slice(0, limit);
+}
+
+function topConcepts(payload, limit = 10) {
+  return asArray(payload.concepts)
+    .map((concept) => ({
+      title: recordTitle(concept, "concept"),
+      path: concept.target_page_path,
+      related_count: asArray(concept.related_entity_details).length || asArray(concept.related_entities).length,
+      source_refs: sourceRefCount(concept),
+      axes: asArray(concept.key_axes).map((axis) => axis.name || axis).filter(Boolean),
+    }))
+    .sort((a, b) => (b.related_count - a.related_count) || (b.source_refs - a.source_refs) || a.title.localeCompare(b.title))
+    .slice(0, limit);
+}
+
+function comparisonEntries(payload, limit = 10) {
+  return asArray(payload.comparisons)
+    .map((comparison) => ({
+      title: recordTitle(comparison, "comparison"),
+      topic: comparison.topic || comparison.comparison_id || recordTitle(comparison, "comparison"),
+      path: comparison.target_page_path,
+      rows: asArray(comparison.matrix_rows).length,
+      source_refs: sourceRefCount(comparison),
+      recommendations: asArray(comparison.recommendations),
+    }))
+    .sort((a, b) => (b.rows - a.rows) || (b.source_refs - a.source_refs) || a.title.localeCompare(b.title))
+    .slice(0, limit);
+}
+
+function synthesisEntries(payload, limit = 10) {
+  return asArray(payload.syntheses)
+    .map((synthesis) => ({
+      title: recordTitle(synthesis, "synthesis"),
+      topic: synthesis.topic || synthesis.synthesis_id || recordTitle(synthesis, "synthesis"),
+      path: synthesis.target_page_path,
+      candidates: asArray(synthesis.candidate_tools).length,
+      source_refs: sourceRefCount(synthesis),
+      recommendations: asArray(synthesis.recommendations),
+    }))
+    .sort((a, b) => (b.candidates - a.candidates) || (b.source_refs - a.source_refs) || a.title.localeCompare(b.title))
+    .slice(0, limit);
+}
+
+function sourceEntries(payload, limit = 20) {
+  return asArray(payload.sources)
+    .map((source) => ({
+      title: source.source_logical_path || source.source_relative_path || source.source_id || "source",
+      path: source.target_page_path,
+      source_id: source.source_id,
+      quality_flags: asArray(source.source_quality && source.source_quality.quality_flags),
+      source_url: source.source_url || "",
+      source_hash: source.source_hash || "",
+    }))
+    .slice(0, limit);
+}
+
+function groupToolsByCategory(tools) {
+  const byCategory = new Map();
+  for (const tool of tools) {
+    const key = tool.category || "uncategorized";
+    if (!byCategory.has(key)) byCategory.set(key, []);
+    byCategory.get(key).push(tool);
+  }
+  return [...byCategory.entries()]
+    .map(([category, rows]) => ({ category, rows }))
+    .sort((a, b) => (b.rows.length - a.rows.length) || a.category.localeCompare(b.category));
+}
+
+function linkedListFromRoot(entries) {
+  const rows = asArray(entries).filter((entry) => entry && entry.path);
+  if (rows.length === 0) return "- None recorded.";
+  return rows.map((entry) => `- [${entry.title}](${rootLink(entry.path)}): ${entry.source_refs || 0} source reference(s).`).join("\n");
+}
+
+function linkedListFromDashboard(entries) {
+  const rows = asArray(entries).filter((entry) => entry && entry.path);
+  if (rows.length === 0) return "- None recorded.";
+  return rows.map((entry) => `- [${entry.title}](${dashboardLink(entry.path)}): ${entry.source_refs || 0} source reference(s).`).join("\n");
+}
+
+function dashboardFrontmatter(id, title, payload, generatedAt, relatedPages = []) {
+  return {
+    id,
+    title,
+    type: "dashboard",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: [title],
+    tags: ["dashboard", "navigation"],
+    related_pages: relatedPages,
+    source_refs: asArray(payload.sources).map((source) => source.source_id).filter(Boolean).slice(0, 50),
+    confidence: "medium",
+    review_status: "needs_review",
+  };
+}
+
+function renderResearchToolLandscapeDashboard(payload) {
+  const tools = highSignalTools(payload, 16);
+  const concepts = topConcepts(payload, 8);
+  const comparisons = comparisonEntries(payload, 6);
+  const syntheses = synthesisEntries(payload, 6);
+  const categoryRows = groupToolsByCategory(tools);
+  const table = [
+    "| Category | Candidate count | High-signal examples |",
+    "|---|---:|---|",
+    ...categoryRows.map(({ category, rows }) => {
+      const examples = rows.slice(0, 4).map((tool) => tool.path ? `[${mdEscapeTable(tool.title)}](${dashboardLink(tool.path)})` : mdEscapeTable(tool.title)).join("<br>");
+      return `| ${mdEscapeTable(category)} | ${rows.length} | ${examples || "-"} |`;
+    }),
+  ].join("\n");
+  const highSignalTable = [
+    "| Tool | Category | Local evidence | Topics | Confidence |",
+    "|---|---|---:|---|---|",
+    ...tools.slice(0, 12).map((tool) => {
+      const label = tool.path ? `[${mdEscapeTable(tool.title)}](${dashboardLink(tool.path)})` : mdEscapeTable(tool.title);
+      return `| ${label} | ${mdEscapeTable(tool.category)} | ${tool.source_refs} | ${mdEscapeTable(tool.topics.slice(0, 4).join(", ") || "-")} | ${mdEscapeTable(tool.confidence)} |`;
+    }),
+  ].join("\n");
+  const body = [
+    "# Research / Tool Landscape Dashboard",
+    "",
+    "## Purpose",
+    "",
+    "Use this page as the starting map for browsing locally extracted repository and tool evidence. The links stay inside the generated local wiki and do not imply external verification.",
+    "",
+    "## Top Concepts",
+    "",
+    linkedListFromDashboard(concepts),
+    "",
+    "## Tool Clusters",
+    "",
+    table,
+    "",
+    "## High-Signal Tools",
+    "",
+    highSignalTable,
+    "",
+    "## Comparison And Synthesis Entry Points",
+    "",
+    "Comparisons:",
+    "",
+    linkedListFromDashboard(comparisons),
+    "",
+    "Syntheses:",
+    "",
+    linkedListFromDashboard(syntheses),
+    "",
+    "## Review Notes",
+    "",
+    "- Prefer tools with multiple local source references before opening an external verification issue.",
+    "- Treat topic/category clustering as local evidence only.",
+    "- Use the decision-support dashboard before making adoption recommendations.",
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter(
+    dashboardFrontmatter(
+      "dashboard_research_tool_landscape",
+      "Research / Tool Landscape Dashboard",
+      payload,
+      payload.generated_at || "",
+      ["../index.md", ...concepts.map((entry) => dashboardLink(entry.path)).filter(Boolean)]
+    ),
+    body
+  );
+}
+
+function renderDecisionSupportDashboard(payload) {
+  const comparisons = comparisonEntries(payload, 8);
+  const syntheses = synthesisEntries(payload, 8);
+  const tools = highSignalTools(payload, 10);
+  const comparisonTable = [
+    "| Decision surface | Candidates | Local source refs | First recommendation cue |",
+    "|---|---:|---:|---|",
+    ...comparisons.map((entry) => `| [${mdEscapeTable(entry.title)}](${dashboardLink(entry.path)}) | ${entry.rows} | ${entry.source_refs} | ${mdEscapeTable(entry.recommendations[0] || "review candidates")} |`),
+  ].join("\n");
+  const shortlist = [
+    "| Candidate | Category | Local evidence | Decision note |",
+    "|---|---|---:|---|",
+    ...tools.slice(0, 8).map((tool) => `| [${mdEscapeTable(tool.title)}](${dashboardLink(tool.path)}) | ${mdEscapeTable(tool.category)} | ${tool.source_refs} | Verify license, maintenance, security, and fit before adoption. |`),
+  ].join("\n");
+  const body = [
+    "# Decision-Support Dashboard",
+    "",
+    "## Purpose",
+    "",
+    "Use this page when deciding which locally sourced candidates deserve deeper review. It links comparison, synthesis, and high-signal tool pages without fetching external metadata.",
+    "",
+    "## Comparison Starting Points",
+    "",
+    comparisons.length > 0 ? comparisonTable : "- No comparison pages were generated from the local evidence.",
+    "",
+    "## Synthesis Starting Points",
+    "",
+    linkedListFromDashboard(syntheses),
+    "",
+    "## Candidate Shortlist",
+    "",
+    shortlist,
+    "",
+    "## Decision Checklist",
+    "",
+    "- Confirm the page has multiple local source references or a strong extracted snippet.",
+    "- Check comparison caveats before adoption.",
+    "- Verify license, maintainer activity, security posture, and current repository identity outside this local-only report.",
+    "- Record human acceptance criteria before treating a tool as recommended.",
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter(
+    dashboardFrontmatter(
+      "dashboard_decision_support",
+      "Decision-Support Dashboard",
+      payload,
+      payload.generated_at || "",
+      ["../index.md", ...comparisons.map((entry) => dashboardLink(entry.path)).filter(Boolean)]
+    ),
+    body
+  );
+}
+
+function renderMaintenanceQualityDashboard(payload) {
+  const findings = asArray(payload.source_quality_findings);
+  const unsupported = asArray(payload.unsupported_items);
+  const sources = sourceEntries(payload, 10);
+  const maintenanceLinks = [];
+  if (findings.length > 0 || unsupported.length > 0) {
+    maintenanceLinks.push("[Extraction Quality Review](../maintenance/extraction-quality-review.md)");
+  }
+  const findingList = findings.slice(0, 12).map((finding) =>
+    `- ${finding.finding_id || finding.source_id || "finding"}: ${asArray(finding.quality_flags).join(", ") || finding.reason || "review required"}`
+  ).join("\n") || "- No source-quality findings recorded.";
+  const unsupportedList = unsupported.slice(0, 12).map((item) =>
+    `- ${item.item_id || "unsupported"}: ${item.reason || item.raw_observation_summary || "review required"}`
+  ).join("\n") || "- No unsupported extraction items recorded.";
+  const body = [
+    "# Maintenance / Quality Dashboard",
+    "",
+    "## Purpose",
+    "",
+    "Use this page to triage local extraction quality before relying on generated concept, comparison, synthesis, or tool pages.",
+    "",
+    "## Quality Snapshot",
+    "",
+    `- source-quality findings: ${findings.length}`,
+    `- unsupported items: ${unsupported.length}`,
+    `- source pages tracked: ${asArray(payload.sources).length}`,
+    `- tool candidates tracked: ${asArray(payload.tool_entities).length}`,
+    "",
+    "## Maintenance Entry Points",
+    "",
+    maintenanceLinks.length > 0 ? maintenanceLinks.map((link) => `- ${link}`).join("\n") : "- No dedicated maintenance review page was required for this extraction.",
+    "",
+    "## Source Findings",
+    "",
+    findingList,
+    "",
+    "## Unsupported Items",
+    "",
+    unsupportedList,
+    "",
+    "## Source Pages To Recheck",
+    "",
+    linkedListFromDashboard(sources.map((source) => ({ title: source.title, path: source.path, source_refs: source.quality_flags.length }))),
+    "",
+    "## Operating Notes",
+    "",
+    "- Fix source-quality warnings before treating dashboard rankings as final.",
+    "- Keep destructive cleanup, archive, and delete decisions outside this generated dashboard.",
+    "- Re-run lint after compile/apply to verify internal links and required fields.",
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter(
+    dashboardFrontmatter("dashboard_maintenance_quality", "Maintenance / Quality Dashboard", payload, payload.generated_at || "", ["../index.md"]),
+    body
+  );
+}
+
+function renderSourceCoverageDashboard(payload) {
+  const sources = sourceEntries(payload, 30);
+  const counts = payload.source_counts || {};
+  const sourceTable = [
+    "| Source | Quality flags | Source URL | Hash prefix |",
+    "|---|---|---|---|",
+    ...sources.map((source) => {
+      const label = source.path ? `[${mdEscapeTable(source.title)}](${dashboardLink(source.path)})` : mdEscapeTable(source.title);
+      const sourceUrl = source.source_url ? `[source](${source.source_url})` : "-";
+      return `| ${label} | ${mdEscapeTable(source.quality_flags.join(", ") || "none")} | ${sourceUrl} | ${mdEscapeTable(source.source_hash.slice(0, 12) || "-")} |`;
+    }),
+  ].join("\n");
+  const body = [
+    "# Source Coverage Dashboard",
+    "",
+    "## Purpose",
+    "",
+    "Use this page to understand which local files fed the generated local wiki and where source-level review should start.",
+    "",
+    "## Coverage Snapshot",
+    "",
+    `- sources scanned: ${counts.scanned ?? "(unknown)"}`,
+    `- sources indexed: ${counts.indexed ?? "(unknown)"}`,
+    `- source records: ${asArray(payload.sources).length}`,
+    `- tool candidates: ${asArray(payload.tool_entities).length}`,
+    `- concepts: ${asArray(payload.concepts).length}`,
+    `- comparisons: ${asArray(payload.comparisons).length}`,
+    `- syntheses: ${asArray(payload.syntheses).length}`,
+    "",
+    "## Source Pages",
+    "",
+    sourceTable,
+    "",
+    "## Coverage Notes",
+    "",
+    "- The dashboard is derived from local source registry and semantic extraction output only.",
+    "- Source hashes should remain stable across compile and enrichment/report-only flows.",
+    "- Investigate any lint provenance finding before using the generated graph as a decision record.",
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter(
+    dashboardFrontmatter("dashboard_source_coverage", "Source Coverage Dashboard", payload, payload.generated_at || "", ["../index.md"]),
+    body
+  );
+}
+
+function renderDashboardPage(name, payload) {
+  if (name === "research-tool-landscape") return renderResearchToolLandscapeDashboard(payload);
+  if (name === "decision-support") return renderDecisionSupportDashboard(payload);
+  if (name === "maintenance-quality") return renderMaintenanceQualityDashboard(payload);
+  if (name === "source-coverage") return renderSourceCoverageDashboard(payload);
+  return renderResearchToolLandscapeDashboard(payload);
+}
+
+function yamlScalar(value) {
+  return `"${String(value ?? "").replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, " ").trim()}"`;
+}
+
+function yamlInlineList(values) {
+  const items = [...new Set(asArray(values).filter(Boolean).map(String))];
+  return `[${items.map(yamlScalar).join(", ")}]`;
+}
+
+function frontmatterBlock(fields) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    if (Array.isArray(value)) {
+      lines.push(`${key}: ${yamlInlineList(value)}`);
+    } else {
+      lines.push(`${key}: ${yamlScalar(value)}`);
+    }
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+
+function withPersonalBrainFrontmatter(fields, body) {
+  return `${frontmatterBlock({
+    schema_version: "1",
+    product: "SDTK-BRAIN",
+    managed_by: "sdtk-wiki",
+    status: "generated",
+    aliases: [],
+    tags: [],
+    related_pages: [],
+    source_refs: [],
+    confidence: "medium",
+    review_status: "needs_review",
+    ...fields,
+  })}${String(body || "").replace(/^\s+/, "")}`;
+}
+
+function recordTitle(record, fallback) {
+  return String(record.title || record.name || record.topic || record.entity_id || record.concept_id || record.source_id || fallback || "Generated page");
+}
+
+function renderSourcePage(source, generatedAt) {
+  const title = recordTitle(source, "Source");
+  const body = [
+    `# ${title}`,
+    "",
+    "## Summary",
+    "",
+    `Local source page generated from ${source.source_logical_path || source.source_relative_path || source.source_id}.`,
+    "",
+    "## Source Metadata",
+    "",
+    `- source_id: ${source.source_id}`,
+    `- source_relative_path: ${source.source_relative_path || "(missing)"}`,
+    `- source_logical_path: ${source.source_logical_path || "(missing)"}`,
+    `- source_url: ${source.source_url || "(missing)"}`,
+    `- source_hash: ${source.source_hash || "(missing)"}`,
+    `- encoding_quality: ${source.encoding_quality || "(unknown)"}`,
+    "",
+    "## Source Quality",
+    "",
+    mdList(source.source_quality && source.source_quality.quality_flags),
+    "",
+    "## Thinness Policy",
+    "",
+    "This page is an accepted source/provenance anchor. Its purpose is to preserve local source identity, hash, quality flags, and provenance rather than to carry semantic analysis. Strict stub quality is measured on tool, concept, comparison, and synthesis pages.",
+    "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(source)),
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: source.source_id,
+    title,
+    type: "source",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: source.source_logical_path ? [source.source_logical_path] : [],
+    tags: ["source", source.source_type || "local"],
+    thinness_policy: "accepted_source_provenance_anchor",
+    source_refs: sourceRefsFor(source),
+    confidence: source.source_quality && source.source_quality.low_confidence_extraction ? "low" : "medium",
+    review_status: source.source_quality && source.source_quality.low_confidence_extraction ? "needs_review" : "ready_for_review",
+  }, body);
+}
+
+function renderToolEntityPage(entity, generatedAt) {
+  const title = recordTitle(entity, "Tool entity");
+  const evidenceRecords = asArray(entity.evidence_records);
+  const firstSnippet = asArray(entity.evidence_snippets)[0] || (evidenceRecords[0] && evidenceRecords[0].snippet);
+  const discoverySources = [
+    ...asArray(entity.source_links),
+    ...asArray(entity.discovery_sources),
+    ...evidenceRecords.map((record) => record.source_link || record.source_logical_path).filter(Boolean),
+  ];
+  const sourceCount = sourceRefsFor(entity).length;
+  const whyItMatters = entity.summary
+    ? `Local evidence presents ${title} as relevant to ${entity.category || "the extracted tool landscape"}. ${entity.summary}`
+    : `Local evidence links ${title} to ${entity.category || "the extracted tool landscape"} with ${sourceCount} source reference(s).`;
+  const whenToUse = asArray(entity.topics).length > 0
+    ? `Review when exploring ${asArray(entity.topics).slice(0, 4).join(", ")} options from the local source set.`
+    : "Review when evaluating whether this repository should become a maintained tool note.";
+  const overlap = asArray(entity.related_repos).length > 0
+    ? "Related repositories were inferred from shared local topic labels or category evidence. Treat this as a review cue, not external verification."
+    : "No overlap was inferred from local topic labels in this slice.";
+  const body = [
+    `# ${title}`,
+    "",
+    "## Summary",
+    "",
+    entity.summary || `Generated tool entity page for ${entity.name || entity.entity_id}.`,
+    "",
+    "## Key Facts",
+    "",
+    `- Canonical URL: ${entity.github_url || "(missing)"}`,
+    `- Owner: ${entity.repo_owner || "(missing)"}`,
+    `- Repo name: ${entity.repo_name || "(missing)"}`,
+    `- Category: ${entity.category || "(unknown)"}`,
+    `- Confidence: ${entity.confidence_tier || entity.confidence || "medium"}`,
+    `- Local source refs: ${sourceCount}`,
+    "",
+    "## Discovery Source",
+    "",
+    mdLinkedList([...new Set(discoverySources.filter(Boolean).map(String))]),
+    "",
+    "## Extracted Snippet",
+    "",
+    quoteBlock(firstSnippet),
+    "",
+    "## Topic Labels",
+    "",
+    topicLabelList(entity),
+    "",
+    "## Why It Matters",
+    "",
+    whyItMatters,
+    "",
+    "## When To Use",
+    "",
+    whenToUse,
+    "",
+    "## Related Repos",
+    "",
+    relatedRepoList(entity),
+    "",
+    "## Overlaps / Differences",
+    "",
+    overlap,
+    "",
+    "## Open Questions",
+    "",
+    "- Verify license, maintenance status, and project maturity before relying on this tool.",
+    "- Confirm whether the local topic labels match the repository's actual current scope.",
+    "- Decide whether this should remain a tool entity or be reclassified after review.",
+    "",
+    "## Local Evidence Records",
+    "",
+    evidenceRecords.length > 0
+      ? evidenceRecords.map((record) => [
+        `- source_id: ${record.source_id || "(missing)"}`,
+        `  - source: ${record.source_link || record.source_logical_path || "(missing)"}`,
+        `  - topics: ${asArray(record.topics).join(", ") || "(none)"}`,
+        `  - confidence: ${record.confidence_tier || record.confidence || "(unknown)"}`,
+      ].join("\n")).join("\n")
+      : "- No structured evidence records recorded.",
+    "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(entity)),
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: entity.entity_id,
+    title,
+    type: "tool_entity",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: [entity.repo_name, entity.github_url].filter(Boolean),
+    tags: ["tool", entity.category, ...asArray(entity.topics)].filter(Boolean),
+    source_refs: sourceRefsFor(entity),
+    confidence: entity.confidence_tier || entity.confidence || "medium",
+    review_status: "ready_for_review",
+  }, body);
+}
+
+function renderConceptPage(concept, generatedAt) {
+  const title = recordTitle(concept, "Concept");
+  const relatedCount = asArray(concept.related_entity_details).length || asArray(concept.related_entities).length;
+  const sourceCount = sourceRefsFor(concept).length;
+  const summary = concept.definition
+    || `Local sources contain ${relatedCount} tool candidate(s) and ${sourceCount} source reference(s) related to ${title}.`;
+  const body = [
+    `# ${title}`,
+    "",
+    "## Summary",
+    "",
+    summary,
+    "",
+    "## Decision Brief",
+    "",
+    conceptDecisionBrief(concept),
+    "",
+    "## Key Axes",
+    "",
+    conceptAxisList(concept),
+    "",
+    "## Implementations / Examples",
+    "",
+    conceptImplementationList(concept),
+    "",
+    "## Patterns",
+    "",
+    conceptPatternList(concept),
+    "",
+    "## Recommendations / Caveats",
+    "",
+    "- Treat this concept page as local-evidence synthesis, not external verification.",
+    "- Prioritize examples with multiple source references or stronger extraction confidence.",
+    "- Review source-quality warnings before making architecture or tool adoption decisions.",
+    "",
+    "## Open Questions",
+    "",
+    "- Which extracted implementation is mature enough for real project adoption?",
+    "- Are the local topic labels accurate after human review?",
+    "- Should this concept be split, merged, or promoted after comparison/synthesis enrichment?",
+    "",
+    "## Aliases",
+    "",
+    mdList(concept.aliases),
+    "",
+    "## Related Pages",
+    "",
+    conceptRelatedPagesList(concept),
+    "",
+    "## Source References",
+    "",
+    mdList(sourceRefsFor(concept)),
+    "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(concept)),
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: concept.concept_id,
+    title,
+    type: "concept",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: concept.aliases,
+    tags: ["concept"],
+    related_pages: asArray(concept.related_entity_details).map((entity) => entity.target_page_path ? `../${relativePersonalBrainLink(entity.target_page_path)}` : null).filter(Boolean).slice(0, 12),
+    source_refs: sourceRefsFor(concept),
+    confidence: concept.confidence_tier || concept.confidence || "medium",
+    review_status: "ready_for_review",
+  }, body);
+}
+
+function renderComparisonPage(comparison, generatedAt) {
+  const title = recordTitle(comparison, "Comparison");
+  const body = [
+    `# ${title}`,
+    "",
+    "## Summary",
+    "",
+    comparison.summary || `Local comparison for ${comparison.topic || comparison.comparison_id}.`,
+    "",
+    "## Decision Guidance",
+    "",
+    comparisonDecisionGuidance(comparison),
+    "",
+    "## Decision Axes",
+    "",
+    conceptAxisList({ key_axes: comparison.decision_axes }),
+    "",
+    "## Comparison Matrix",
+    "",
+    comparisonMatrix(comparison),
+    "",
+    "## Candidate Tools / Repos",
+    "",
+    candidateToolList(comparison.matrix_rows),
+    "",
+    "## Recommendations",
+    "",
+    mdList(comparison.recommendations),
+    "",
+    "## Caveats",
+    "",
+    mdList(comparison.caveats),
+    "",
+    "## Source Confidence",
+    "",
+    confidenceSummaryList(comparison.source_confidence_summary),
+    "",
+    "## Open Questions",
+    "",
+    "- Which candidate should be verified first with external source checks?",
+    "- Which criteria matter most for the target SDTK use case?",
+    "- Are any candidates duplicates, abandoned, or misclassified in the local source set?",
+    "",
+    "## Source References",
+    "",
+    mdList(sourceRefsFor(comparison)),
+    "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(comparison)),
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: comparison.comparison_id,
+    title,
+    type: "comparison",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: [comparison.topic].filter(Boolean),
+    tags: ["comparison"],
+    related_pages: asArray(comparison.compared_entity_details).map((entity) => entity.target_page_path ? `../${relativePersonalBrainLink(entity.target_page_path)}` : null).filter(Boolean).slice(0, 12),
+    source_refs: sourceRefsFor(comparison),
+    confidence: comparison.confidence_tier || comparison.confidence || "medium",
+    review_status: "needs_review",
+  }, body);
+}
+
+function renderSynthesisPage(synthesis, generatedAt) {
+  const title = recordTitle(synthesis, "Synthesis");
+  const body = [
+    `# ${title}`,
+    "",
+    "## Summary",
+    "",
+    synthesis.summary || `Generated synthesis page for ${synthesis.topic || synthesis.synthesis_id}.`,
+    "",
+    "## Decision Narrative",
+    "",
+    synthesisDecisionNarrative(synthesis),
+    "",
+    "## Landscape Snapshot",
+    "",
+    candidateToolList(synthesis.candidate_tools),
+    "",
+    "## Key Patterns",
+    "",
+    conceptPatternList({ patterns: synthesis.patterns }),
+    "",
+    "## Decision Axes",
+    "",
+    conceptAxisList({ key_axes: synthesis.landscape_axes }),
+    "",
+    "## Recommended Review Path",
+    "",
+    mdList(synthesis.recommendations),
+    "",
+    "## Caveats",
+    "",
+    mdList(synthesis.caveats),
+    "",
+    "## Source Confidence",
+    "",
+    confidenceSummaryList(synthesis.source_confidence_summary),
+    "",
+    "## Related Comparisons",
+    "",
+    synthesis.related_comparison_path ? mdList([`../${relativePersonalBrainLink(synthesis.related_comparison_path)}`]) : "- None recorded.",
+    "",
+    "## Open Questions",
+    "",
+    "- Which comparison criteria should become product acceptance gates?",
+    "- Which local candidates need external verification before adoption?",
+    "- Does this cluster need a dedicated deeper synthesis pass?",
+    "",
+    "## Source References",
+    "",
+    mdList(sourceRefsFor(synthesis)),
+    "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(synthesis)),
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: synthesis.synthesis_id,
+    title,
+    type: "synthesis",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: [synthesis.topic].filter(Boolean),
+    tags: ["synthesis"],
+    related_pages: synthesis.related_comparison_path ? [`../${relativePersonalBrainLink(synthesis.related_comparison_path)}`] : [],
+    source_refs: sourceRefsFor(synthesis),
+    confidence: synthesis.confidence_tier || synthesis.confidence || "medium",
+    review_status: "needs_review",
+  }, body);
+}
+
+function renderRootPage(name, payload) {
+  const extractionCounts = payload && payload.source_counts ? payload.source_counts : {};
+  const concepts = topConcepts(payload, 8);
+  const comparisons = comparisonEntries(payload, 6);
+  const syntheses = synthesisEntries(payload, 6);
+  const tools = highSignalTools(payload, 10);
+  const sources = sourceEntries(payload, 8);
+  const dashboards = [
+    ["Research / Tool Landscape", "dashboards/research-tool-landscape.md"],
+    ["Decision Support", "dashboards/decision-support.md"],
+    ["Maintenance / Quality", "dashboards/maintenance-quality.md"],
+    ["Source Coverage", "dashboards/source-coverage.md"],
+  ];
+  const titles = {
+    index: "Local Wiki Index",
+    overview: "Local Wiki Overview",
+    ontology: "Local Wiki Ontology",
+    taxonomy: "Local Wiki Taxonomy",
+    graph: "Local Wiki Graph",
+    log: "Local Wiki Generation Log",
+  };
+  const title = titles[name] || "Local Wiki";
+  const dashboardLinks = dashboards.map(([label, target]) => `- [${label}](${target})`).join("\n");
+  const topToolLinks = tools.length > 0
+    ? tools.slice(0, 8).map((tool) => `- [${tool.title}](${rootLink(tool.path)}): ${tool.category}; ${tool.source_refs} source reference(s).`).join("\n")
+    : "- None recorded.";
+  const sourceLinks = sources.length > 0
+    ? sources.map((source) => `- [${source.title}](${rootLink(source.path)}): ${source.quality_flags.length > 0 ? source.quality_flags.join(", ") : "no quality flags"}.`).join("\n")
+    : "- None recorded.";
+  const taxonomyRows = [
+    "| Area | Count | Starting points |",
+    "|---|---:|---|",
+    `| Sources | ${asArray(payload.sources).length} | [Source coverage dashboard](dashboards/source-coverage.md) |`,
+    `| Tool entities | ${asArray(payload.tool_entities).length} | [Research / Tool Landscape](dashboards/research-tool-landscape.md) |`,
+    `| Concepts | ${asArray(payload.concepts).length} | ${concepts.slice(0, 4).map((entry) => entry.path ? `[${mdEscapeTable(entry.title)}](${rootLink(entry.path)})` : mdEscapeTable(entry.title)).join("<br>") || "-"} |`,
+    `| Comparisons | ${asArray(payload.comparisons).length} | ${comparisons.slice(0, 4).map((entry) => entry.path ? `[${mdEscapeTable(entry.title)}](${rootLink(entry.path)})` : mdEscapeTable(entry.title)).join("<br>") || "-"} |`,
+    `| Syntheses | ${asArray(payload.syntheses).length} | ${syntheses.slice(0, 4).map((entry) => entry.path ? `[${mdEscapeTable(entry.title)}](${rootLink(entry.path)})` : mdEscapeTable(entry.title)).join("<br>") || "-"} |`,
+  ].join("\n");
+  const graphRows = [
+    "| Graph surface | Count | Navigation |",
+    "|---|---:|---|",
+    `| Relations | ${asArray(payload.relations).length} | Review relation append sections below. |`,
+    `| Concepts | ${asArray(payload.concepts).length} | ${linkedListFromRoot(concepts.slice(0, 5)).replace(/\n/g, "<br>")} |`,
+    `| Comparisons | ${asArray(payload.comparisons).length} | ${linkedListFromRoot(comparisons.slice(0, 5)).replace(/\n/g, "<br>")} |`,
+    `| Syntheses | ${asArray(payload.syntheses).length} | ${linkedListFromRoot(syntheses.slice(0, 5)).replace(/\n/g, "<br>")} |`,
+  ].join("\n");
+  const pageSpecificSections = {
+    index: [
+      "## Start Here",
+      "",
+      dashboardLinks,
+      "",
+      "## High-Signal Tool Entry Points",
+      "",
+      topToolLinks,
+      "",
+      "## Concept / Comparison / Synthesis Entry Points",
+      "",
+      "Concepts:",
+      "",
+      linkedListFromRoot(concepts),
+      "",
+      "Comparisons:",
+      "",
+      linkedListFromRoot(comparisons),
+      "",
+      "Syntheses:",
+      "",
+      linkedListFromRoot(syntheses),
+    ],
+    overview: [
+      "## Session Brief",
+      "",
+      "This generated local wiki is organized for local review. Start with dashboards, inspect top concepts, then use comparison and synthesis pages before adopting any tool.",
+      "",
+      "## Current Landscape",
+      "",
+      `- high-signal tools listed: ${tools.length}`,
+      `- top concepts listed: ${concepts.length}`,
+      `- comparison pages listed: ${comparisons.length}`,
+      `- synthesis pages listed: ${syntheses.length}`,
+      "",
+      "## Recommended Browsing Path",
+      "",
+      "- [Research / Tool Landscape](dashboards/research-tool-landscape.md)",
+      "- [Decision Support](dashboards/decision-support.md)",
+      "- [Source Coverage](dashboards/source-coverage.md)",
+      "- [Maintenance / Quality](dashboards/maintenance-quality.md)",
+    ],
+    taxonomy: [
+      "## Taxonomy Snapshot",
+      "",
+      taxonomyRows,
+      "",
+      "## Concept Clusters",
+      "",
+      concepts.length > 0
+        ? concepts.map((concept) => `- [${concept.title}](${rootLink(concept.path)}): ${concept.related_count} related tool candidate(s); axes: ${concept.axes.slice(0, 4).join(", ") || "none inferred"}.`).join("\n")
+        : "- None recorded.",
+    ],
+    graph: [
+      "## Navigation Graph",
+      "",
+      graphRows,
+      "",
+      "## Tool Cluster Hubs",
+      "",
+      groupToolsByCategory(tools).slice(0, 8).map(({ category, rows }) =>
+        `- ${category}: ${rows.slice(0, 4).map((tool) => `[${tool.title}](${rootLink(tool.path)})`).join(", ")}`
+      ).join("\n") || "- None recorded.",
+    ],
+    log: [
+      "## Review Trail",
+      "",
+      "- Compile operations were derived from the semantic extraction report.",
+      "- Dashboard and navigation pages are generated from the same local evidence as entity/concept/comparison/synthesis pages.",
+      "- Re-run lint after compile/apply to verify internal links and quality gates.",
+    ],
+    ontology: [
+      "## Ontology Navigation",
+      "",
+      "- source: local file/source registry page.",
+      "- tool_entity: extracted GitHub repository or tool candidate page.",
+      "- concept: local thematic grouping across tools and source evidence.",
+      "- comparison: decision matrix for a concept cluster.",
+      "- synthesis: higher-level review path for a cluster.",
+      "- dashboard: curated generated navigation page for browsing and triage.",
+    ],
+  };
+  const body = [
+    `# ${title}`,
+    "",
+    "## Generation Context",
+    "",
+    `- record_type: ${payload.record_type || "(unknown)"}`,
+    `- generated_at: ${payload.generated_at || "(unknown)"}`,
+    `- sources_scanned: ${extractionCounts.scanned ?? "(unknown)"}`,
+    `- sources_indexed: ${extractionCounts.indexed ?? "(unknown)"}`,
+    `- tool_candidates: ${asArray(payload.tool_entities).length}`,
+    `- concept_candidates: ${asArray(payload.concepts).length}`,
+    "",
+    "## Structure",
+    "",
+    "- sources/",
+    "- entities/tools/",
+    "- concepts/",
+    "- comparisons/",
+    "- syntheses/",
+    "- dashboards/",
+    "- maintenance/",
+    "",
+    ...(pageSpecificSections[name] || []),
+    "",
+    "## Source Coverage",
+    "",
+    sourceLinks,
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: `personal_brain_${name}`,
+    title,
+    type: "root",
+    created_at: payload.generated_at || "",
+    updated_at: payload.generated_at || "",
+    aliases: [name],
+    tags: ["local-wiki", name],
+    related_pages: dashboards.map(([, target]) => target),
+    source_refs: asArray(payload.sources).map((source) => source.source_id).filter(Boolean).slice(0, 50),
+    confidence: "medium",
+    review_status: "needs_review",
+  }, body);
+}
+
+function renderMaintenancePage(payload) {
+  const body = [
+    "# Extraction Quality Review",
+    "",
+    "## Source Quality Findings",
+    "",
+    mdList(asArray(payload.source_quality_findings).map((finding) => `${finding.finding_id || finding.source_id}: ${asArray(finding.quality_flags).join(", ") || "review required"}`)),
+    "",
+    "## Unsupported Items",
+    "",
+    mdList(asArray(payload.unsupported_items).map((item) => `${item.item_id || "unsupported"}: ${item.reason || item.raw_observation_summary || "review required"}`)),
+    "",
+  ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: "maintenance_extraction_quality_review",
+    title: "Extraction Quality Review",
+    type: "maintenance",
+    created_at: payload.generated_at || "",
+    updated_at: payload.generated_at || "",
+    aliases: ["source quality", "extraction quality"],
+    tags: ["maintenance", "quality"],
+    source_refs: asArray(payload.sources).map((source) => source.source_id).filter(Boolean).slice(0, 50),
+    confidence: asArray(payload.unsupported_items).length > 0 ? "low" : "medium",
+    review_status: "needs_review",
+  }, body);
+}
+
+function pushCreatePageOperation(operations, raw) {
+  if (!raw.target_page_path) return;
+  operations.push({
+    operation_id: raw.operation_id,
+    operation_type: "create_page",
+    source_id: raw.source_id || "semantic_extraction_report",
+    source_hash: raw.source_hash || "",
+    target_page_path: raw.target_page_path,
+    content: raw.content || "",
+    proposed_content_summary: raw.proposed_content_summary,
+    source_refs: raw.source_refs || [],
+    provenance_refs: raw.provenance_refs || [],
+    evidence_refs: raw.evidence_refs || [],
+    confidence: raw.confidence || "medium",
+    review_status: raw.review_status || "needs_review",
+  });
+}
+
+function operationsFromSemanticExtraction(payload) {
+  const sourceById = new Map(asArray(payload.sources).map((source) => [String(source.source_id), source]));
+  const operations = [];
+  const reportHash = stableHash(JSON.stringify({
+    generated_at: payload.generated_at,
+    source_counts: payload.source_counts,
+  })).slice(0, 12);
+  const rootSourceId = `semantic_extraction_${reportHash}`;
+  const rootSourceHash = reportHash;
+
+  for (const source of asArray(payload.sources)) {
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-source-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: source.source_id,
+      source_hash: source.source_hash,
+      target_page_path: source.target_page_path,
+      content: renderSourcePage(source, payload.generated_at),
+      proposed_content_summary: `Create local wiki source page for ${source.source_logical_path || source.source_relative_path || source.source_id}.`,
+      source_refs: sourceRefsFor(source),
+      provenance_refs: provenanceRefsFor(source),
+      evidence_refs: refsFor(source),
+      confidence: source.source_quality && source.source_quality.low_confidence_extraction ? "low" : "medium",
+      review_status: source.source_quality && source.source_quality.low_confidence_extraction ? "needs_review" : "ready_for_review",
+    });
+  }
+
+  for (const entity of asArray(payload.tool_entities)) {
+    const sourceId = firstSourceRef(entity);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-tool-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: entity.target_page_path,
+      content: renderToolEntityPage(entity, payload.generated_at),
+      proposed_content_summary: `Create tool entity page for ${entity.name || entity.entity_id}.`,
+      source_refs: sourceRefsFor(entity),
+      provenance_refs: provenanceRefsFor(entity),
+      evidence_refs: refsFor(entity),
+      confidence: entity.confidence_tier || entity.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+    operations.push({
+      operation_id: `pb-tool-source-ref-${String(operations.length + 1).padStart(3, "0")}`,
+      operation_type: "add_source_ref",
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: entity.target_page_path,
+      content_sections: [
+        {
+          title: "Source References",
+          body: mdList(sourceRefsFor(entity)),
+        },
+      ],
+      proposed_content_summary: `Add source references for tool entity ${entity.name || entity.entity_id}.`,
+      source_refs: sourceRefsFor(entity),
+      provenance_refs: provenanceRefsFor(entity),
+      evidence_refs: refsFor(entity),
+      confidence: entity.confidence_tier || entity.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+  }
+
+  for (const concept of asArray(payload.concepts)) {
+    const sourceId = firstSourceRef(concept);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-concept-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: concept.target_page_path,
+      content: renderConceptPage(concept, payload.generated_at),
+      proposed_content_summary: `Create concept page for ${concept.name || concept.concept_id}.`,
+      source_refs: sourceRefsFor(concept),
+      provenance_refs: provenanceRefsFor(concept),
+      evidence_refs: refsFor(concept),
+      confidence: concept.confidence_tier || concept.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+  }
+
+  for (const comparison of asArray(payload.comparisons)) {
+    const sourceId = firstSourceRef(comparison);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-comparison-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: comparison.target_page_path,
+      content: renderComparisonPage(comparison, payload.generated_at),
+      proposed_content_summary: `Create comparison page for ${comparison.topic || comparison.comparison_id}.`,
+      source_refs: sourceRefsFor(comparison),
+      provenance_refs: provenanceRefsFor(comparison),
+      evidence_refs: refsFor(comparison),
+      confidence: comparison.confidence_tier || comparison.confidence || "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  for (const synthesis of asArray(payload.syntheses)) {
+    const sourceId = firstSourceRef(synthesis);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-synthesis-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: synthesis.target_page_path,
+      content: renderSynthesisPage(synthesis, payload.generated_at),
+      proposed_content_summary: `Create synthesis page for ${synthesis.topic || synthesis.synthesis_id}.`,
+      source_refs: sourceRefsFor(synthesis),
+      provenance_refs: provenanceRefsFor(synthesis),
+      evidence_refs: refsFor(synthesis),
+      confidence: synthesis.confidence_tier || synthesis.confidence || "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  const rootPages = [
+    ["index", "wiki/index.md", "Create local wiki index from semantic extraction output."],
+    ["overview", "wiki/overview.md", "Create local wiki overview summarizing extracted local sources."],
+    ["ontology", "wiki/ontology.md", "Create ontology page describing source, tool_entity, concept, claim, relation, comparison, and synthesis records."],
+    ["taxonomy", "wiki/taxonomy.md", "Create taxonomy page for extracted categories and concepts."],
+    ["graph", "wiki/graph.md", "Create semantic graph summary page from extracted relations."],
+    ["log", "wiki/log.md", "Create generation log page for extraction and compile preview evidence."],
+  ];
+  for (const [name, target, summary] of rootPages) {
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-root-${name}`,
+      source_id: rootSourceId,
+      source_hash: rootSourceHash,
+      target_page_path: target,
+      content: renderRootPage(name, payload),
+      proposed_content_summary: summary,
+      evidence_refs: [`record_type:${payload.record_type}`, `generated_at:${payload.generated_at || "(missing)"}`],
+      confidence: "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  const dashboardPages = [
+    ["research-tool-landscape", "wiki/dashboards/research-tool-landscape.md", "Create research/tool landscape dashboard from local semantic extraction output."],
+    ["decision-support", "wiki/dashboards/decision-support.md", "Create decision-support dashboard from local comparison and synthesis evidence."],
+    ["maintenance-quality", "wiki/dashboards/maintenance-quality.md", "Create maintenance/quality dashboard from local extraction findings."],
+    ["source-coverage", "wiki/dashboards/source-coverage.md", "Create source coverage dashboard from local source registry evidence."],
+  ];
+  for (const [name, target, summary] of dashboardPages) {
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-dashboard-${name}`,
+      source_id: rootSourceId,
+      source_hash: rootSourceHash,
+      target_page_path: target,
+      content: renderDashboardPage(name, payload),
+      proposed_content_summary: summary,
+      source_refs: asArray(payload.sources).map((source) => source.source_id).filter(Boolean).slice(0, 50),
+      evidence_refs: [`record_type:${payload.record_type}`, `dashboard:${name}`],
+      confidence: "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  for (const relation of asArray(payload.relations)) {
+    operations.push({
+      operation_id: `pb-relation-${String(operations.length + 1).padStart(3, "0")}`,
+      operation_type: "add_relation",
+      source_id: relation.source_id || rootSourceId,
+      source_hash: rootSourceHash,
+      target_page_path: "wiki/graph.md",
+      content_sections: [
+        {
+          title: `Relation: ${relation.relation_type || relation.relation_id}`,
+          body: [
+            `- source_id: ${relation.source_id || "(missing)"}`,
+            `- target_id: ${relation.target_id || "(missing)"}`,
+            `- relation_type: ${relation.relation_type || "(missing)"}`,
+            `- evidence: ${relation.evidence || "(missing)"}`,
+            `- source_refs: ${sourceRefsFor(relation).join(", ") || "(missing)"}`,
+            `- provenance_refs: ${provenanceRefsFor(relation).join(", ") || "(missing)"}`,
+          ].join("\n"),
+        },
+      ],
+      proposed_content_summary: `Preview semantic relation ${relation.relation_type || relation.relation_id}.`,
+      source_refs: sourceRefsFor(relation),
+      provenance_refs: provenanceRefsFor(relation),
+      evidence_refs: refsFor(relation),
+      confidence: relation.confidence_tier || relation.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+  }
+
+  const qualityFindingCount = asArray(payload.source_quality_findings).length;
+  const unsupportedCount = asArray(payload.unsupported_items).length;
+  if (qualityFindingCount > 0 || unsupportedCount > 0) {
+    pushCreatePageOperation(operations, {
+      operation_id: "pb-maintenance-extraction-quality-review",
+      source_id: rootSourceId,
+      source_hash: rootSourceHash,
+      target_page_path: "wiki/maintenance/extraction-quality-review.md",
+      content: renderMaintenancePage(payload),
+      proposed_content_summary: `Create maintenance review page for ${qualityFindingCount} source-quality finding(s) and ${unsupportedCount} unsupported extraction item(s).`,
+      evidence_refs: [`source_quality_findings:${qualityFindingCount}`, `unsupported_items:${unsupportedCount}`],
+      confidence: unsupportedCount > 0 ? "low" : "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  return operations;
+}
+
+function emptySourceQualitySummary() {
+  return {
+    findings_count: 0,
+    unsupported_count: 0,
+    low_confidence_count: 0,
+    warning_count: 0,
+  };
+}
+
+function sourceQualitySummaryFromExtraction(payload) {
+  const findings = asArray(payload.source_quality_findings);
+  const unsupported = asArray(payload.unsupported_items);
+  const lowConfidence = findings.filter((finding) => ["low", "unsupported"].includes(String(finding.confidence_tier || finding.confidence || "").toLowerCase())).length;
+  return {
+    findings_count: findings.length,
+    unsupported_count: unsupported.length,
+    low_confidence_count: lowConfidence,
+    warning_count: findings.length + unsupported.length,
+  };
+}
+
+function parseJsonPlan(planPath) {
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(planPath, "utf-8"));
+  } catch (error) {
+    throw new ValidationError(`Invalid JSON compile plan: ${error.message}. No project files were changed.`);
+  }
+  if (payload && payload.record_type === APPLY_PLAN_RECORD_TYPE) {
+    return {
+      operations: asArray(payload.operations),
+      sourceQualitySummary: payload.source_quality_summary || emptySourceQualitySummary(),
+    };
+  }
+  if (payload && payload.record_type === "sdtk_wiki_semantic_extraction") {
+    return {
+      operations: operationsFromSemanticExtraction(payload),
+      sourceQualitySummary: sourceQualitySummaryFromExtraction(payload),
+    };
+  }
+  if (!payload || !Array.isArray(payload.operations)) {
+    throw new ValidationError("Invalid compile plan: JSON plan must contain an operations array. No project files were changed.");
+  }
+  return {
+    operations: payload.operations,
+    sourceQualitySummary: payload.source_quality_summary || emptySourceQualitySummary(),
+  };
+}
+
+function parseMarkdownPlan(planPath) {
+  const text = fs.readFileSync(planPath, "utf-8");
+  const lines = text.split(/\r?\n/);
+  const operations = [];
+  let current = null;
+
+  function flush() {
+    if (current && Object.keys(current).length > 1) {
+      operations.push(current);
+    }
+    current = null;
+  }
+
+  for (const line of lines) {
+    const heading = line.match(/^###\s+(.+?)\s*$/);
+    if (heading) {
+      flush();
+      current = { operation_id: heading[1].trim() };
+      continue;
+    }
+    const bullet = line.match(/^\s*-\s*([A-Za-z0-9_]+):\s*(.+?)\s*$/);
+    if (bullet && current) {
+      current[bullet[1]] = bullet[2];
+    }
+  }
+  flush();
+
+  if (operations.length === 0 || operations.every((operation) => !operation.operation_type)) {
+    throw new ValidationError(
+      "Invalid markdown compile plan: expected structured operation blocks with operation_type. No project files were changed."
+    );
+  }
+  return {
+    operations,
+    sourceQualitySummary: emptySourceQualitySummary(),
+  };
+}
+
+function parsePlanOperations(planPath) {
+  const ext = path.extname(planPath).toLowerCase();
+  if (ext === ".json") {
+    return parseJsonPlan(planPath);
+  }
+  if (ext === ".md" || ext === ".markdown") {
+    return parseMarkdownPlan(planPath);
+  }
+  throw new ValidationError(`Unsupported plan format: ${ext || "(none)"}. Use .md, .markdown, or .json. No project files were changed.`);
+}
+
+function splitRefs(value) {
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  return String(value || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function expectedMutationFor(operation) {
+  switch (operation.operation_type) {
+    case "append_section":
+      return `Would append an evidence-backed section to ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    case "create_page":
+      return `Would create managed page ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    case "add_relation":
+      return `Would add a related-page relation for ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    case "add_source_ref":
+      return `Would add source reference metadata for ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    default:
+      return "No mutation would be allowed; operation type is unsupported in BK-126.";
+  }
+}
+
+function renderContentSections(sections) {
+  return asArray(sections)
+    .map((section) => {
+      if (typeof section === "string") return section;
+      const title = section && section.title ? String(section.title) : "Generated Section";
+      const body = section && section.body ? String(section.body) : "";
+      return `## ${title}\n\n${body}`.trimEnd();
+    })
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function fallbackOperationContent(operation) {
+  const title = operation.target_page_id || path.basename(operation.target_page_path || "generated-page.md", path.extname(operation.target_page_path || ""));
+  return [
+    `# ${title}`,
+    "",
+    "## Generated Operation",
+    "",
+    operation.proposed_content_summary || "Generated local wiki content.",
+    "",
+    "## Evidence",
+    "",
+    mdList(operation.evidence_refs),
+    "",
+  ].join("\n");
+}
+
+function normalizeTargetPath(rawTargetPath, projectPath) {
+  const canonicalWikiRoot = getCanonicalWikiPath(projectPath);
+  const legacyPersonalBrainRoot = getLegacyPersonalBrainPath(projectPath);
+  const targetValue = String(rawTargetPath || "");
+  const resolvedTarget = targetValue ? path.resolve(projectPath, targetValue) : "";
+  const withinProject = Boolean(resolvedTarget) && isPathInsideOrEqual(resolvedTarget, projectPath);
+  const withinCanonicalWiki = Boolean(resolvedTarget) && isPathInsideOrEqual(resolvedTarget, canonicalWikiRoot);
+  const withinLegacyPersonalBrain = Boolean(resolvedTarget) && isPathInsideOrEqual(resolvedTarget, legacyPersonalBrainRoot);
+  const withinWikiContent = withinCanonicalWiki || withinLegacyPersonalBrain;
+  return {
+    resolvedTarget,
+    targetPathNormalized: withinProject ? toPosix(path.relative(projectPath, resolvedTarget)) : toPosix(resolvedTarget),
+    withinProject,
+    withinCanonicalWiki,
+    withinLegacyPersonalBrain,
+    withinWikiContent,
+  };
+}
+
+function normalizeOperation(rawOperation, index, projectPath) {
+  const operationType = String(rawOperation.operation_type || rawOperation.operationType || "").trim();
+  const isSupported = ALLOWED_OPERATION_TYPES.has(operationType);
+  const target = normalizeTargetPath(rawOperation.target_page_path || rawOperation.targetPagePath || "", projectPath);
+  const operation = {
+    operation_id: String(rawOperation.operation_id || rawOperation.operationId || `operation-${String(index + 1).padStart(3, "0")}`),
+    source_id: String(rawOperation.source_id || rawOperation.sourceId || "unknown_source"),
+    source_hash: String(rawOperation.source_hash || rawOperation.sourceHash || ""),
+    revision: String(rawOperation.revision || ""),
+    target_page_id: String(rawOperation.target_page_id || rawOperation.targetPageId || ""),
+    target_page_path: String(rawOperation.target_page_path || rawOperation.targetPagePath || ""),
+    target_path_normalized: target.targetPathNormalized,
+    target_path_within_project: target.withinProject,
+    target_path_within_personal_brain: target.withinWikiContent,
+    target_path_within_canonical_wiki: target.withinCanonicalWiki,
+    target_path_within_legacy_personal_brain: target.withinLegacyPersonalBrain,
+    operation_type: operationType || "unsupported_operation",
+    requested_operation_type: operationType || "(missing)",
+    proposed_content_summary: String(rawOperation.proposed_content_summary || rawOperation.proposedContentSummary || ""),
+    content: String(rawOperation.content || ""),
+    content_sections: asArray(rawOperation.content_sections || rawOperation.contentSections),
+    source_refs: splitRefs(rawOperation.source_refs || rawOperation.sourceRefs || rawOperation.source_id || rawOperation.sourceId),
+    provenance_refs: splitRefs(rawOperation.provenance_refs || rawOperation.provenanceRefs),
+    evidence_refs: splitRefs(rawOperation.evidence_refs || rawOperation.evidenceRefs),
+    confidence: String(rawOperation.confidence || "unknown"),
+    review_status: String(rawOperation.review_status || rawOperation.reviewStatus || "needs_review"),
+    validation_status: isSupported ? "supported" : "unsupported_operation",
+    apply_mode: rawOperation.apply_mode || rawOperation.applyMode || APPLY_MODE,
+  };
+  if (!operation.content && operation.content_sections.length > 0) {
+    operation.content = renderContentSections(operation.content_sections);
+  }
+  if (!operation.content) {
+    operation.content = fallbackOperationContent(operation);
+  }
+  operation.expected_mutation_if_applied = expectedMutationFor(operation);
+  if (!isSupported) {
+    operation.operation_type = "unsupported_operation";
+    operation.review_status = "blocked";
+  }
+  return operation;
+}
+
+function summarizeOperations(operations) {
+  const counts = {};
+  for (const operation of operations) {
+    counts[operation.operation_type] = (counts[operation.operation_type] || 0) + 1;
+  }
+  return counts;
+}
+
+function renderReport({ projectPath, workspacePath, planPath, applyPlanPath, generatedAt, operations }) {
+  const summary = summarizeOperations(operations);
+  const sortedTypes = Array.from(new Set([...Array.from(ALLOWED_OPERATION_TYPES), "unsupported_operation"]));
+  const unsupported = operations.filter((operation) => operation.validation_status === "unsupported_operation");
+  const lines = [
+    "# SDTK-BRAIN Compile Dry-Run Preview",
+    "",
+    `Generated: ${generatedAt}`,
+    `Project path: ${projectPath}`,
+    `Workspace path: ${workspacePath}`,
+    `Input plan path: ${planPath}`,
+    `Apply JSON sidecar path: ${applyPlanPath}`,
+    `Operations: ${operations.length}`,
+    "",
+    "No wiki pages, raw sources, provenance, or atlas compatibility files were modified.",
+    "Preview-only: apply, page mutation, raw mutation, provenance mutation, discover, prune, query-history, and release work are outside BK-126.",
+    "",
+    "## Operation Counts",
+    "",
+    "| Operation type | Count |",
+    "|---|---:|",
+    ...sortedTypes.map((type) => `| \`${type}\` | ${summary[type] || 0} |`),
+    "",
+    "## Proposed Operations",
+    "",
+  ];
+
+  if (operations.length === 0) {
+    lines.push("No operations were proposed by the input plan.");
+  } else {
+    for (const operation of operations) {
+      lines.push(`### ${operation.operation_id}`);
+      lines.push("");
+      lines.push(`- operation_type: \`${operation.operation_type}\``);
+      if (operation.operation_type === "unsupported_operation") {
+        lines.push(`- requested_operation_type: \`${operation.requested_operation_type}\``);
+      }
+      lines.push(`- Validation status: ${operation.validation_status}`);
+      lines.push(`- source_id: ${operation.source_id}`);
+      lines.push(`- source_hash_or_revision: ${operation.source_hash || operation.revision || "(missing)"}`);
+      lines.push(`- target_page_id: ${operation.target_page_id || "(missing)"}`);
+      lines.push(`- target_page_path: ${operation.target_page_path || "(missing)"}`);
+      lines.push(`- proposed_content_summary: ${operation.proposed_content_summary || "(missing)"}`);
+      lines.push(`- evidence_refs: ${operation.evidence_refs.length > 0 ? operation.evidence_refs.join(", ") : "(missing)"}`);
+      lines.push(`- confidence: ${operation.confidence}`);
+      lines.push(`- review_status: ${operation.review_status}`);
+      lines.push(`- Expected mutation if applied: ${operation.expected_mutation_if_applied}`);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Unsupported / Blocked Operations");
+  lines.push("");
+  if (unsupported.length === 0) {
+    lines.push("- None.");
+  } else {
+    for (const operation of unsupported) {
+      lines.push(`- ${operation.operation_id}: unsupported_operation for requested type \`${operation.requested_operation_type}\`.`);
+    }
+  }
+  lines.push("");
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function renderApplyPlan({ projectPath, planPath, reportPath, generatedAt, operations, sourceQualitySummary }) {
+  return {
+    schema_version: APPLY_PLAN_SCHEMA_VERSION,
+    record_type: APPLY_PLAN_RECORD_TYPE,
+    generated_at: generatedAt,
+    project_path: projectPath,
+    source_plan_path: planPath,
+    dry_run_report_path: reportPath,
+    operation_counts: summarizeOperations(operations),
+    source_quality_summary: sourceQualitySummary || emptySourceQualitySummary(),
+    operations: operations.map((operation) => ({
+      operation_id: operation.operation_id,
+      operation_type: operation.operation_type,
+      target_page_path: operation.target_page_path,
+      target_path_normalized: operation.target_path_normalized,
+      target_path_within_project: operation.target_path_within_project,
+      target_path_within_personal_brain: operation.target_path_within_personal_brain,
+      target_path_within_canonical_wiki: operation.target_path_within_canonical_wiki,
+      target_path_within_legacy_personal_brain: operation.target_path_within_legacy_personal_brain,
+      content: operation.content,
+      content_sections: operation.content_sections,
+      source_refs: operation.source_refs,
+      provenance_refs: operation.provenance_refs,
+      evidence_refs: operation.evidence_refs,
+      confidence: operation.confidence,
+      review_status: operation.review_status,
+      validation_status: operation.validation_status,
+      expected_mutation_if_applied: operation.expected_mutation_if_applied,
+      apply_mode: APPLY_MODE,
+    })),
+  };
+}
+
+function ensureTrailingNewline(value) {
+  const text = String(value || "").replace(/\r\n/g, "\n").trimEnd();
+  return `${text}\n`;
+}
+
+function loadApplyPlan(planPath) {
+  if (path.extname(planPath).toLowerCase() !== ".json") {
+    throw new ValidationError("Apply requires a compile apply JSON sidecar. Markdown plans are rejected for apply. No project files were changed.");
+  }
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(planPath, "utf-8"));
+  } catch (error) {
+    throw new ValidationError(`Invalid compile apply JSON sidecar: ${error.message}. No project files were changed.`);
+  }
+  if (payload && payload.record_type === "sdtk_wiki_semantic_extraction") {
+    throw new ValidationError("Apply rejects semantic extraction JSON. Run compile --dry-run first and apply the generated compile apply JSON sidecar. No project files were changed.");
+  }
+  if (!payload || payload.record_type !== APPLY_PLAN_RECORD_TYPE) {
+    throw new ValidationError(`Apply requires record_type ${APPLY_PLAN_RECORD_TYPE}. No project files were changed.`);
+  }
+  if (!Array.isArray(payload.operations)) {
+    throw new ValidationError("Compile apply JSON sidecar must contain operations[]. No project files were changed.");
+  }
+  return payload;
+}
+
+function validateApplyOperations(operations) {
+  const blocked = operations.filter((operation) => (
+    operation.validation_status !== "supported" ||
+    operation.operation_type === "unsupported_operation" ||
+    !ALLOWED_OPERATION_TYPES.has(operation.operation_type) ||
+    operation.apply_mode !== APPLY_MODE ||
+    !operation.target_path_within_project ||
+    !operation.target_path_within_personal_brain
+  ));
+  if (blocked.length > 0) {
+    throw new ValidationError(
+      `Compile apply plan contains ${blocked.length} blocked or unsafe operation(s). No project files were changed.`
+    );
+  }
+}
+
+function aggregateApplyTargets(operations, projectPath) {
+  const targets = new Map();
+  for (const operation of operations) {
+    const target = normalizeTargetPath(operation.target_page_path, projectPath);
+    if (!target.withinProject || !target.withinWikiContent) {
+      throw new ValidationError(`Unsafe wiki target path: ${operation.target_page_path}. No project files were changed.`);
+    }
+    const existing = targets.get(target.resolvedTarget) || {
+      path: target.resolvedTarget,
+      normalized: target.targetPathNormalized,
+      withinCanonicalWiki: target.withinCanonicalWiki,
+      withinLegacyPersonalBrain: target.withinLegacyPersonalBrain,
+      sections: [],
+      operationIds: [],
+    };
+    existing.operationIds.push(operation.operation_id);
+    existing.sections.push(ensureTrailingNewline(operation.content));
+    targets.set(target.resolvedTarget, existing);
+  }
+  for (const target of targets.values()) {
+    target.content = ensureTrailingNewline(target.sections.join("\n"));
+  }
+  return [...targets.values()].sort((a, b) => a.normalized.localeCompare(b.normalized));
+}
+
+function scaffoldFileIfMissing(filePath, content, projectPath, rootPath, created, skipped) {
+  if (!isPathInsideOrEqual(filePath, rootPath)) {
+    throw new ValidationError(`Unsafe scaffold target path: ${filePath}. No project files were changed.`);
+  }
+  if (fs.existsSync(filePath)) {
+    skipped.push(toPosix(path.relative(projectPath, filePath)));
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, ensureTrailingNewline(content), "utf-8");
+  created.push(toPosix(path.relative(projectPath, filePath)));
+}
+
+function scaffoldWikiPageFrontmatter(fields, body) {
+  const generatedAt = new Date().toISOString();
+  return withPersonalBrainFrontmatter({
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    ...fields,
+  }, body);
+}
+
+function scaffoldCanonicalWikiStructure(projectPath) {
+  const canonicalRoot = getCanonicalWikiPath(projectPath);
+  const created = [];
+  const skipped = [];
+  const directories = [
+    "timelines",
+    "queries",
+    "decisions",
+    "meeting-notes",
+    "templates",
+    "maintenance",
+  ];
+  fs.mkdirSync(canonicalRoot, { recursive: true });
+  for (const dir of directories) {
+    const dirPath = path.join(canonicalRoot, dir);
+    if (!isPathInsideOrEqual(dirPath, canonicalRoot)) {
+      throw new ValidationError(`Unsafe wiki directory path: ${dirPath}. No project files were changed.`);
+    }
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+      created.push(toPosix(path.relative(projectPath, dirPath)) + "/");
+    }
+  }
+  scaffoldFileIfMissing(
+    path.join(canonicalRoot, "maintenance.md"),
+    scaffoldWikiPageFrontmatter(
+      {
+        id: "root_maintenance",
+        title: "Maintenance",
+        type: "maintenance",
+        aliases: ["Maintenance"],
+        tags: ["maintenance", "local-wiki"],
+        related_pages: ["index.md", "maintenance/extraction-quality-review.md"],
+        source_refs: ["sdtk_wiki_scaffold"],
+        confidence: "medium",
+        review_status: "needs_review",
+      },
+      "# Maintenance\n\n## Purpose\n\nTrack local wiki maintenance tasks, quality checks, and review follow-ups.\n\n## Source Quality Findings\n\n- Review generated lint, discover, compile, and enrichment reports under `.brain/reports`.\n\n## Unsupported Items\n\n- None recorded in the scaffold.\n\n## Open Items\n\n- Promote maintenance notes into dedicated pages under `wiki/maintenance/` when review produces durable decisions."
+    ),
+    projectPath,
+    canonicalRoot,
+    created,
+    skipped
+  );
+  scaffoldFileIfMissing(
+    path.join(canonicalRoot, "inbox.md"),
+    scaffoldWikiPageFrontmatter(
+      {
+        id: "root_inbox",
+        title: "Inbox",
+        type: "root",
+        aliases: ["Inbox"],
+        tags: ["inbox", "local-wiki"],
+        related_pages: ["index.md"],
+        source_refs: [],
+        confidence: "medium",
+        review_status: "needs_review",
+      },
+      "# Inbox\n\n## Purpose\n\nCapture uncategorized local notes before they are promoted into source, decision, query, timeline, or maintenance pages.\n\n## Inbox\n\n- Add local notes here before structured review."
+    ),
+    projectPath,
+    canonicalRoot,
+    created,
+    skipped
+  );
+
+  const rootDocs = [
+    ["README.md", "# Local Wiki\n\nThis project uses `wiki/` as the human-facing SDTK-BRAIN output. Internal state, reports, provenance, raw registry, graph, and logs stay under `.brain`."],
+    ["AGENTS.md", "# Agent Operating Notes\n\nCodex agents should read `wiki/index.md` first, then use `wiki/dashboards/` for navigation. Do not mutate `.brain` internal state by hand."],
+    ["CLAUDE.md", "# Claude Operating Notes\n\nClaude agents should use `wiki/` as the canonical local wiki and treat `.brain` as SDTK-BRAIN internal state."],
+  ];
+  for (const [name, content] of rootDocs) {
+    const filePath = path.join(projectPath, name);
+    if (fs.existsSync(filePath)) {
+      skipped.push(name);
+      continue;
+    }
+    fs.writeFileSync(filePath, ensureTrailingNewline(content), "utf-8");
+    created.push(name);
+  }
+  return { created, skipped };
+}
+
+function runWikiCompileApply({ projectPath, planArg }) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}`);
+  }
+
+  try {
+    ensureExistingWorkspace(resolvedProjectPath);
+    const planPath = resolvePlanPath(planArg, resolvedProjectPath);
+    const payload = loadApplyPlan(planPath);
+    const operations = payload.operations.map((operation, index) => normalizeOperation(operation, index, resolvedProjectPath));
+    validateApplyOperations(operations);
+    const targets = aggregateApplyTargets(operations, resolvedProjectPath);
+    const conflicts = [];
+    const unchanged = [];
+    const toCreate = [];
+
+    for (const target of targets) {
+      if (target.withinCanonicalWiki) {
+        assertCanonicalWikiWritePath(target.path, resolvedProjectPath);
+      } else if (target.withinLegacyPersonalBrain) {
+        assertWikiWorkspaceWritePath(target.path, resolvedProjectPath);
+      } else {
+        throw new ValidationError(`Refusing to write outside project wiki output: ${target.normalized}. No project files were changed.`);
+      }
+      if (!fs.existsSync(target.path)) {
+        toCreate.push(target);
+        continue;
+      }
+      const current = fs.readFileSync(target.path, "utf-8").replace(/\r\n/g, "\n");
+      if (current === target.content) {
+        unchanged.push(target.normalized);
+      } else {
+        conflicts.push(target.normalized);
+      }
+    }
+
+    if (conflicts.length > 0) {
+      throw new ValidationError(`Compile apply would overwrite ${conflicts.length} existing different file(s): ${conflicts.join(", ")}. No project files were changed.`);
+    }
+
+    const created = [];
+    const scaffold = scaffoldCanonicalWikiStructure(resolvedProjectPath);
+    for (const target of toCreate) {
+      fs.mkdirSync(path.dirname(target.path), { recursive: true });
+      fs.writeFileSync(target.path, target.content, "utf-8");
+      created.push(target.normalized);
+    }
+
+    const sourceQualitySummary = payload.source_quality_summary || emptySourceQualitySummary();
+    return {
+      planPath,
+      created,
+      unchanged,
+      scaffoldCreated: scaffold.created,
+      scaffoldSkipped: scaffold.skipped,
+      sourceQualityWarningCount: Number(sourceQualitySummary.warning_count || sourceQualitySummary.findings_count || 0),
+    };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(`Failed to apply SDTK-BRAIN compile plan: ${error.message}`);
+  }
+}
+
+function runWikiCompileDryRun({ projectPath, planArg }) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}`);
+  }
+
+  try {
+    const workspacePath = ensureExistingWorkspace(resolvedProjectPath);
+    const planPath = resolvePlanPath(planArg, resolvedProjectPath);
+    const parsed = parsePlanOperations(planPath);
+    const rawOperations = parsed.operations;
+    const sourceQualitySummary = parsed.sourceQualitySummary || emptySourceQualitySummary();
+    const operations = rawOperations.map((operation, index) => normalizeOperation(operation, index, resolvedProjectPath));
+    const reportsPath = getWikiReportsPath(resolvedProjectPath);
+    assertWikiWorkspaceWritePath(reportsPath, resolvedProjectPath);
+    const generatedAt = new Date().toISOString();
+    const reportPath = path.join(reportsPath, `${REPORT_PREFIX}-${todayStamp(new Date(generatedAt))}.md`);
+    const applyPlanPath = path.join(reportsPath, `${APPLY_PLAN_PREFIX}-${todayStamp(new Date(generatedAt))}.json`);
+    assertWikiWorkspaceWritePath(reportPath, resolvedProjectPath);
+    assertWikiWorkspaceWritePath(applyPlanPath, resolvedProjectPath);
+    fs.mkdirSync(reportsPath, { recursive: true });
+    fs.writeFileSync(
+      reportPath,
+      renderReport({
+        projectPath: resolvedProjectPath,
+        workspacePath,
+        planPath,
+        applyPlanPath,
+        generatedAt,
+        operations,
+      }),
+      "utf-8"
+    );
+    fs.writeFileSync(
+      applyPlanPath,
+      JSON.stringify(renderApplyPlan({
+        projectPath: resolvedProjectPath,
+        planPath,
+        reportPath,
+        generatedAt,
+        operations,
+        sourceQualitySummary,
+      }), null, 2) + "\n",
+      "utf-8"
+    );
+
+    return {
+      reportPath,
+      applyPlanPath,
+      operations,
+      summary: summarizeOperations(operations),
+      unsupportedCount: operations.filter((operation) => operation.validation_status === "unsupported_operation").length,
+    };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(`Failed to write SDTK-BRAIN compile dry-run preview: ${error.message}`);
+  }
+}
+
+module.exports = {
+  APPLY_PLAN_RECORD_TYPE,
+  ALLOWED_OPERATION_TYPES,
+  REPORT_PREFIX,
+  renderReport,
+  runWikiCompileApply,
+  runWikiCompileDryRun,
+};