sdtk-wiki-kit 0.1.3 → 0.2.0

package/src/lib/wiki-compile.js

@@ -4,7 +4,10 @@ const fs = require("fs");
 const path = require("path");
 const { CliError, ValidationError } = require("./errors");
 const {
+  assertCanonicalWikiWritePath,
   assertWikiWorkspaceWritePath,
+  getCanonicalWikiPath,
+  getLegacyPersonalBrainPath,
   getWikiReportsPath,
   getWikiWorkspacePath,
   isPathInsideOrEqual,
@@ -15,7 +18,7 @@ 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 PERSONAL_BRAIN_RELATIVE = path.join(".sdtk", "wiki", "personal-brain");
+const CANONICAL_WIKI_RELATIVE = "wiki";
 const APPLY_MODE = "create_only_or_same_content_noop";
 const ALLOWED_OPERATION_TYPES = new Set([
   "append_section",
@@ -138,6 +141,7 @@ function relatedRepoList(entity) {
 
 function relativePersonalBrainLink(targetPagePath) {
   const text = toPosix(targetPagePath || "");
+  if (text.startsWith("wiki/")) return text.slice("wiki/".length);
   const marker = ".sdtk/wiki/personal-brain/";
   const idx = text.indexOf(marker);
   return idx >= 0 ? text.slice(idx + marker.length) : text;
@@ -204,6 +208,464 @@ function candidateToolList(records) {
   }).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()}"`;
 }
@@ -268,6 +730,10 @@ function renderSourcePage(source, generatedAt) {
     "",
     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)),
@@ -281,6 +747,7 @@ function renderSourcePage(source, 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",
@@ -399,6 +866,10 @@ function renderConceptPage(concept, generatedAt) {
     "",
     summary,
     "",
+    "## Decision Brief",
+    "",
+    conceptDecisionBrief(concept),
+    "",
     "## Key Axes",
     "",
     conceptAxisList(concept),
@@ -464,6 +935,10 @@ function renderComparisonPage(comparison, generatedAt) {
     "",
     comparison.summary || `Local comparison for ${comparison.topic || comparison.comparison_id}.`,
     "",
+    "## Decision Guidance",
+    "",
+    comparisonDecisionGuidance(comparison),
+    "",
     "## Decision Axes",
     "",
     conceptAxisList({ key_axes: comparison.decision_axes }),
@@ -527,6 +1002,10 @@ function renderSynthesisPage(synthesis, generatedAt) {
     "",
     synthesis.summary || `Generated synthesis page for ${synthesis.topic || synthesis.synthesis_id}.`,
     "",
+    "## Decision Narrative",
+    "",
+    synthesisDecisionNarrative(synthesis),
+    "",
     "## Landscape Snapshot",
     "",
     candidateToolList(synthesis.candidate_tools),
@@ -587,15 +1066,133 @@ function renderSynthesisPage(synthesis, generatedAt) {
 
 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: "Personal Brain Index",
-    overview: "Personal Brain Overview",
-    ontology: "Personal Brain Ontology",
-    taxonomy: "Personal Brain Taxonomy",
-    graph: "Personal Brain Graph",
-    log: "Personal Brain Generation Log",
+    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 title = titles[name] || "Personal Brain";
   const body = [
     `# ${title}`,
     "",
@@ -615,8 +1212,15 @@ function renderRootPage(name, payload) {
     "- concepts/",
     "- comparisons/",
     "- syntheses/",
+    "- dashboards/",
     "- maintenance/",
     "",
+    ...(pageSpecificSections[name] || []),
+    "",
+    "## Source Coverage",
+    "",
+    sourceLinks,
+    "",
   ].join("\n");
   return withPersonalBrainFrontmatter({
     id: `personal_brain_${name}`,
@@ -625,7 +1229,8 @@ function renderRootPage(name, payload) {
     created_at: payload.generated_at || "",
     updated_at: payload.generated_at || "",
     aliases: [name],
-    tags: ["personal-brain", 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",
@@ -694,7 +1299,7 @@ function operationsFromSemanticExtraction(payload) {
       source_hash: source.source_hash,
       target_page_path: source.target_page_path,
       content: renderSourcePage(source, payload.generated_at),
-      proposed_content_summary: `Create personal-brain source page for ${source.source_logical_path || source.source_relative_path || source.source_id}.`,
+      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),
@@ -791,12 +1396,12 @@ function operationsFromSemanticExtraction(payload) {
   }
 
   const rootPages = [
-    ["index", ".sdtk/wiki/personal-brain/index.md", "Create personal-brain index from semantic extraction output."],
-    ["overview", ".sdtk/wiki/personal-brain/overview.md", "Create personal-brain overview summarizing extracted local sources."],
-    ["ontology", ".sdtk/wiki/personal-brain/ontology.md", "Create ontology page describing source, tool_entity, concept, claim, relation, comparison, and synthesis records."],
-    ["taxonomy", ".sdtk/wiki/personal-brain/taxonomy.md", "Create taxonomy page for extracted categories and concepts."],
-    ["graph", ".sdtk/wiki/personal-brain/graph.md", "Create semantic graph summary page from extracted relations."],
-    ["log", ".sdtk/wiki/personal-brain/log.md", "Create generation log page for extraction and compile preview evidence."],
+    ["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, {
@@ -812,13 +1417,34 @@ function operationsFromSemanticExtraction(payload) {
     });
   }
 
+  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: ".sdtk/wiki/personal-brain/graph.md",
+      target_page_path: "wiki/graph.md",
       content_sections: [
         {
           title: `Relation: ${relation.relation_type || relation.relation_id}`,
@@ -848,7 +1474,7 @@ function operationsFromSemanticExtraction(payload) {
       operation_id: "pb-maintenance-extraction-quality-review",
       source_id: rootSourceId,
       source_hash: rootSourceHash,
-      target_page_path: ".sdtk/wiki/personal-brain/maintenance/extraction-quality-review.md",
+      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}`],
@@ -1000,7 +1626,7 @@ function fallbackOperationContent(operation) {
     "",
     "## Generated Operation",
     "",
-    operation.proposed_content_summary || "Generated personal-brain content.",
+    operation.proposed_content_summary || "Generated local wiki content.",
     "",
     "## Evidence",
     "",
@@ -1010,16 +1636,21 @@ function fallbackOperationContent(operation) {
 }
 
 function normalizeTargetPath(rawTargetPath, projectPath) {
-  const personalBrainRoot = path.join(getWikiWorkspacePath(projectPath), "personal-brain");
+  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 withinPersonalBrain = Boolean(resolvedTarget) && isPathInsideOrEqual(resolvedTarget, personalBrainRoot);
+  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,
-    withinPersonalBrain,
+    withinCanonicalWiki,
+    withinLegacyPersonalBrain,
+    withinWikiContent,
   };
 }
 
@@ -1036,7 +1667,9 @@ function normalizeOperation(rawOperation, index, projectPath) {
     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.withinPersonalBrain,
+    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 || ""),
@@ -1153,6 +1786,8 @@ function renderApplyPlan({ projectPath, planPath, reportPath, generatedAt, opera
       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,
@@ -1214,12 +1849,14 @@ 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.withinPersonalBrain) {
-      throw new ValidationError(`Unsafe personal-brain target path: ${operation.target_page_path}. No project files were changed.`);
+    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: [],
     };
@@ -1233,6 +1870,111 @@ function aggregateApplyTargets(operations, projectPath) {
   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 `.sdtk/wiki/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-WIKI output. Internal state, reports, provenance, raw registry, graph, and logs stay under `.sdtk/wiki`."],
+    ["AGENTS.md", "# Agent Operating Notes\n\nCodex agents should read `wiki/index.md` first, then use `wiki/dashboards/` for navigation. Do not mutate `.sdtk/wiki` internal state by hand."],
+    ["CLAUDE.md", "# Claude Operating Notes\n\nClaude agents should use `wiki/` as the canonical local wiki and treat `.sdtk/wiki` as SDTK-WIKI 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()) {
@@ -1251,9 +1993,12 @@ function runWikiCompileApply({ projectPath, planArg }) {
     const toCreate = [];
 
     for (const target of targets) {
-      assertWikiWorkspaceWritePath(target.path, resolvedProjectPath);
-      if (!isPathInsideOrEqual(target.path, path.join(getWikiWorkspacePath(resolvedProjectPath), "personal-brain"))) {
-        throw new ValidationError(`Refusing to write outside .sdtk/wiki/personal-brain: ${target.normalized}. No project files were changed.`);
+      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);
@@ -1272,6 +2017,7 @@ function runWikiCompileApply({ projectPath, planArg }) {
     }
 
     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");
@@ -1283,6 +2029,8 @@ function runWikiCompileApply({ projectPath, planArg }) {
       planPath,
       created,
       unchanged,
+      scaffoldCreated: scaffold.created,
+      scaffoldSkipped: scaffold.skipped,
       sourceQualityWarningCount: Number(sourceQualitySummary.warning_count || sourceQualitySummary.findings_count || 0),
     };
   } catch (error) {