sdtk-wiki-kit 0.1.2 → 0.1.4

package/src/lib/wiki-lint.js

@@ -7,6 +7,7 @@ const {
   assertWikiWorkspaceWritePath,
   getWikiGraphPath,
   getWikiPagesPath,
+  getPreferredWikiContentPath,
   getWikiProvenanceSourcesPath,
   getWikiRawSourcesPath,
   getWikiReportsPath,
@@ -27,6 +28,21 @@ const REQUIRED_PAGE_FIELDS = [
   "role",
 ];
 
+const REQUIRED_PERSONAL_BRAIN_FIELDS = [
+  "id",
+  "title",
+  "type",
+  "status",
+  "created_at",
+  "updated_at",
+  "aliases",
+  "tags",
+  "related_pages",
+  "source_refs",
+  "confidence",
+  "review_status",
+];
+
 const CATEGORY_DEFS = [
   ["schema", "Frontmatter and schema"],
   ["duplicates", "Duplicate page IDs"],
@@ -40,8 +56,23 @@ const CATEGORY_DEFS = [
   ["markers", "TODO/Open Questions/Gaps"],
   ["contradictions", "Candidate contradictions"],
   ["sourceQuality", "Source quality"],
+  ["personalBrainQuality", "Local wiki quality gate"],
 ];
 
+const REQUIRED_PERSONAL_BRAIN_SECTIONS = {
+  source: ["Summary", "Source Metadata", "Source Quality", "Provenance"],
+  tool_entity: ["Summary", "Key Facts", "Discovery Source", "Extracted Snippet", "Topic Labels", "Why It Matters", "When To Use", "Related Repos", "Overlaps / Differences", "Open Questions", "Provenance"],
+  concept: ["Summary", "Key Axes", "Implementations / Examples", "Patterns", "Recommendations / Caveats", "Open Questions", "Related Pages", "Source References"],
+  comparison: ["Summary", "Decision Axes", "Comparison Matrix", "Candidate Tools / Repos", "Recommendations", "Caveats", "Source Confidence", "Open Questions", "Source References"],
+  synthesis: ["Summary", "Landscape Snapshot", "Key Patterns", "Decision Axes", "Recommended Review Path", "Caveats", "Source Confidence", "Related Comparisons", "Open Questions", "Source References"],
+  maintenance: ["Source Quality Findings", "Unsupported Items"],
+};
+
+const PERSONAL_BRAIN_STUB_CHAR_LIMIT = 600;
+const PERSONAL_BRAIN_GIANT_PAGE_BYTES = 50000;
+const LINT_CONTEXT_CHAR_LIMIT = 96;
+const STRICT_SEMANTIC_PERSONAL_BRAIN_TYPES = new Set(["tool_entity", "concept", "comparison", "synthesis"]);
+
 function toPosix(value) {
   return String(value || "").replace(/\\/g, "/");
 }
@@ -130,24 +161,68 @@ function listMarkdownPages(rootPath) {
   return files;
 }
 
+function truncateForReport(value, limit = LINT_CONTEXT_CHAR_LIMIT) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (text.length <= limit) return text;
+  return `${text.slice(0, Math.max(0, limit - 3)).trim()}...`;
+}
+
+function isExternalMarkdownTarget(rawTarget) {
+  const target = String(rawTarget || "").trim();
+  return (
+    target.startsWith("#") ||
+    /^(?:https?:|mailto:|tel:)/i.test(target) ||
+    /^(?:h|ht|htt|http|https)\.{3,}(?:\s|$)/i.test(target)
+  );
+}
+
 function extractMarkdownLinks(body) {
   const links = [];
-  const matcher = /\[[^\]]+\]\(([^)]+)\)/g;
+  const matcher = /\[([^\]]+)\]\(([^)]+)\)/g;
   let match;
   while ((match = matcher.exec(body || "")) !== null) {
-    const rawTarget = String(match[1] || "").trim();
+    const rawLabel = String(match[1] || "").trim();
+    const rawTarget = String(match[2] || "").trim();
     if (!rawTarget) continue;
-    if (
-      rawTarget.startsWith("#") ||
-      /^(?:https?:|mailto:|tel:)/i.test(rawTarget)
-    ) {
+    if (isExternalMarkdownTarget(rawTarget)) {
       continue;
     }
-    links.push(rawTarget);
+    links.push({
+      target: rawTarget,
+      label: rawLabel,
+      context: truncateForReport(rawLabel || rawTarget),
+    });
   }
   return links;
 }
 
+function formatBrokenLinkFinding(pageRelPath, link) {
+  const target = typeof link === "string" ? link : link.target;
+  const context = typeof link === "string" ? "" : link.context;
+  const parts = [
+    `page: \`${pageRelPath}\``,
+    `missing target: \`${truncateForReport(target)}\``,
+  ];
+  if (context) {
+    parts.push(`context: \`${context}\``);
+  }
+  return parts.join("; ") + ".";
+}
+
+function hasHeading(body, heading) {
+  const escaped = String(heading).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^##\\s+${escaped}\\s*$`, "im").test(String(body || ""));
+}
+
+function hasSourceRefs(fields) {
+  const raw = String(fields.source_refs || "").trim();
+  return Boolean(raw && raw !== "[]" && raw !== "[\"\"]");
+}
+
+function formatPercent(value) {
+  return `${Math.round(value * 100)}%`;
+}
+
 function createFindings() {
   return Object.fromEntries(CATEGORY_DEFS.map(([key]) => [key, []]));
 }
@@ -426,11 +501,12 @@ function analyzePages(projectPath) {
   const pagesByRelPath = new Map(pages.map((page) => [toPosix(path.normalize(page.relPath)), page]));
   for (const page of pages) {
     for (const link of page.links) {
-      const rawPath = link.split("#")[0].trim();
+      const target = typeof link === "string" ? link : link.target;
+      const rawPath = target.split("#")[0].trim();
       if (!rawPath) continue;
       const resolved = path.resolve(path.dirname(page.filePath), rawPath);
       if (!isPathInsideOrEqual(resolved, inputs.pagesRoot) || !fs.existsSync(resolved)) {
-        appendFinding(findings, "brokenLinks", `\`${page.relPath}\` links to missing \`${link}\`.`);
+        appendFinding(findings, "brokenLinks", formatBrokenLinkFinding(page.relPath, link));
         continue;
       }
       const targetRel = toPosix(path.relative(inputs.pagesRoot, resolved));
@@ -550,7 +626,173 @@ function analyzePages(projectPath) {
 
   analyzeSourceQuality(projectPath, inputs, findings);
 
-  return { findings, pageCount: pages.length };
+  const personalBrainAnalysis = analyzePersonalBrainPages(projectPath, findings);
+
+  return {
+    findings,
+    pageCount: pages.length + personalBrainAnalysis.count,
+    personalBrainMetrics: personalBrainAnalysis.metrics,
+  };
+}
+
+function analyzePersonalBrainPages(projectPath, findings) {
+  const contentRoot = getPreferredWikiContentPath(projectPath);
+  const personalBrainRoot = contentRoot.path;
+  const contentRelative = toPosix(contentRoot.relative);
+  const pageFiles = listMarkdownPages(personalBrainRoot);
+  const pages = [];
+  const metrics = {
+    pageCount: pageFiles.length,
+    contentRoot: personalBrainRoot,
+    contentMode: contentRoot.mode,
+    contentRelative,
+    byType: {},
+    frontmatterCoverage: 0,
+    requiredSectionCoverage: 0,
+    sourceRefsCoverage: 0,
+    stubRatio: 0,
+    sourcePageCount: 0,
+    sourceThinAnchorCount: 0,
+    sourceThinAnchorRatio: 0,
+    semanticPageCount: 0,
+    semanticStubCount: 0,
+    semanticStubRatio: 0,
+    giantPageCount: 0,
+    brokenInternalLinks: 0,
+    conceptCount: 0,
+    entityCount: 0,
+    comparisonCount: 0,
+    synthesisCount: 0,
+    sourceEvidenceCoverage: 0,
+  };
+  let frontmatterCount = 0;
+  let sectionRequiredTotal = 0;
+  let sectionPresentTotal = 0;
+  let sourceRefsEligible = 0;
+  let sourceRefsPresent = 0;
+  let sourceEvidenceEligible = 0;
+  let sourceEvidencePresent = 0;
+  let stubCount = 0;
+
+  for (const filePath of pageFiles) {
+    const relPath = toPosix(path.relative(personalBrainRoot, filePath));
+    const parsed = parseFrontmatter(fs.readFileSync(filePath, "utf-8"));
+    const fields = parsed.fields;
+    const type = String(fields.type || "unknown");
+    pages.push({ filePath, relPath, fields, body: parsed.body, hasFrontmatter: parsed.hasFrontmatter, type });
+    metrics.byType[type] = (metrics.byType[type] || 0) + 1;
+    if (type === "source") metrics.sourcePageCount += 1;
+    if (STRICT_SEMANTIC_PERSONAL_BRAIN_TYPES.has(type)) metrics.semanticPageCount += 1;
+    if (type === "concept") metrics.conceptCount += 1;
+    if (type === "tool_entity") metrics.entityCount += 1;
+    if (type === "comparison") metrics.comparisonCount += 1;
+    if (type === "synthesis") metrics.synthesisCount += 1;
+
+    if (!parsed.hasFrontmatter) {
+      appendFinding(findings, "schema", `${contentRelative}/${relPath} is missing parseable frontmatter.`);
+      continue;
+    }
+    frontmatterCount += 1;
+
+    const missingFields = REQUIRED_PERSONAL_BRAIN_FIELDS.filter((field) => !fields[field]);
+    if (missingFields.length > 0) {
+      appendFinding(
+        findings,
+        "schema",
+        `${contentRelative}/${relPath} is missing required local wiki fields: ${missingFields.join(", ")}.`
+      );
+    }
+
+    const requiredSections = REQUIRED_PERSONAL_BRAIN_SECTIONS[type] || [];
+    sectionRequiredTotal += requiredSections.length;
+    const missingSections = requiredSections.filter((section) => !hasHeading(parsed.body, section));
+    sectionPresentTotal += requiredSections.length - missingSections.length;
+    if (missingSections.length > 0) {
+      appendFinding(
+        findings,
+        "personalBrainQuality",
+        `${contentRelative}/${relPath} is missing required sections for ${type}: ${missingSections.join(", ")}.`
+      );
+    }
+
+    if (!["root"].includes(type)) {
+      sourceRefsEligible += 1;
+      if (hasSourceRefs(fields)) sourceRefsPresent += 1;
+      else appendFinding(findings, "personalBrainQuality", `${contentRelative}/${relPath} has no source_refs coverage.`);
+    }
+
+    if (["tool_entity", "concept", "comparison", "synthesis"].includes(type)) {
+      sourceEvidenceEligible += 1;
+      if (hasSourceRefs(fields) && /(?:source|provenance|evidence)/i.test(parsed.body)) {
+        sourceEvidencePresent += 1;
+      } else {
+        appendFinding(findings, "personalBrainQuality", `${contentRelative}/${relPath} lacks source evidence coverage in body/frontmatter.`);
+      }
+    }
+
+    const compactBody = parsed.body.replace(/\s+/g, " ").trim();
+    if (type === "source") {
+      metrics.sourceThinAnchorCount += 1;
+    } else if (compactBody.length < PERSONAL_BRAIN_STUB_CHAR_LIMIT && STRICT_SEMANTIC_PERSONAL_BRAIN_TYPES.has(type)) {
+      stubCount += 1;
+      metrics.semanticStubCount += 1;
+      appendFinding(findings, "personalBrainQuality", `${contentRelative}/${relPath} appears stub-like (${compactBody.length} normalized characters).`);
+    }
+
+    const byteSize = fs.statSync(filePath).size;
+    if (byteSize > PERSONAL_BRAIN_GIANT_PAGE_BYTES) {
+      metrics.giantPageCount += 1;
+      appendFinding(findings, "personalBrainQuality", `${contentRelative}/${relPath} is very large (${byteSize} bytes) and may need splitting.`);
+    }
+  }
+
+  for (const page of pages) {
+    for (const link of extractMarkdownLinks(page.body)) {
+      const target = typeof link === "string" ? link : link.target;
+      const rawPath = target.split("#")[0].trim();
+      if (!rawPath) continue;
+      const resolved = path.resolve(path.dirname(page.filePath), rawPath);
+      if (!isPathInsideOrEqual(resolved, personalBrainRoot) || !fs.existsSync(resolved)) {
+        appendFinding(findings, "brokenLinks", formatBrokenLinkFinding(`${contentRelative}/${page.relPath}`, link));
+        metrics.brokenInternalLinks += 1;
+      }
+    }
+  }
+
+  metrics.frontmatterCoverage = pageFiles.length > 0 ? frontmatterCount / pageFiles.length : 1;
+  metrics.requiredSectionCoverage = sectionRequiredTotal > 0 ? sectionPresentTotal / sectionRequiredTotal : 1;
+  metrics.sourceRefsCoverage = sourceRefsEligible > 0 ? sourceRefsPresent / sourceRefsEligible : 1;
+  metrics.stubRatio = pageFiles.length > 0 ? stubCount / pageFiles.length : 0;
+  metrics.sourceThinAnchorRatio = metrics.sourcePageCount > 0 ? metrics.sourceThinAnchorCount / metrics.sourcePageCount : 0;
+  metrics.semanticStubRatio = metrics.semanticPageCount > 0 ? metrics.semanticStubCount / metrics.semanticPageCount : 0;
+  metrics.sourceEvidenceCoverage = sourceEvidenceEligible > 0 ? sourceEvidencePresent / sourceEvidenceEligible : 1;
+
+  if (pageFiles.length === 0) {
+    appendFinding(findings, "personalBrainQuality", "No local wiki pages were found under wiki/ or legacy .sdtk/wiki/personal-brain.");
+  }
+  if (metrics.frontmatterCoverage < 1) {
+    appendFinding(findings, "personalBrainQuality", `Frontmatter coverage is ${formatPercent(metrics.frontmatterCoverage)}; expected 100%.`);
+  }
+  if (metrics.requiredSectionCoverage < 0.95) {
+    appendFinding(findings, "personalBrainQuality", `Required section coverage is ${formatPercent(metrics.requiredSectionCoverage)}; expected at least 95%.`);
+  }
+  if (metrics.sourceRefsCoverage < 0.9) {
+    appendFinding(findings, "personalBrainQuality", `Source refs coverage is ${formatPercent(metrics.sourceRefsCoverage)}; expected at least 90%.`);
+  }
+  if (metrics.semanticStubRatio > 0.1) {
+    appendFinding(findings, "personalBrainQuality", `Semantic stub ratio is ${formatPercent(metrics.semanticStubRatio)}; expected at most 10% for tool/concept/comparison/synthesis pages.`);
+  }
+  if (metrics.entityCount > 0 && metrics.conceptCount === 0) {
+    appendFinding(findings, "personalBrainQuality", "Tool/entity pages exist but no concept pages were generated.");
+  }
+  if (metrics.conceptCount > 0 && metrics.comparisonCount === 0) {
+    appendFinding(findings, "personalBrainQuality", "Concept pages exist but no comparison pages were generated.");
+  }
+  if (metrics.comparisonCount > 0 && metrics.synthesisCount === 0) {
+    appendFinding(findings, "personalBrainQuality", "Comparison pages exist but no synthesis pages were generated.");
+  }
+
+  return { count: pageFiles.length, metrics };
 }
 
 function todayStamp() {
@@ -561,7 +803,43 @@ function totalFindings(findings) {
   return CATEGORY_DEFS.reduce((sum, [key]) => sum + findings[key].length, 0);
 }
 
-function renderReport({ projectPath, workspaceRoot, findings, pageCount }) {
+function renderPersonalBrainMetrics(metrics) {
+  if (!metrics) return ["## Local Wiki Quality Metrics", "", "- No local wiki metrics available.", ""];
+  const typeRows = Object.entries(metrics.byType || {})
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([type, count]) => `| ${type} | ${count} |`);
+  return [
+    "## Local Wiki Quality Metrics",
+    "",
+    `- wiki content root: ${metrics.contentRoot}`,
+    `- wiki content mode: ${metrics.contentMode}`,
+    `- local wiki pages: ${metrics.pageCount}`,
+    `- frontmatter coverage: ${formatPercent(metrics.frontmatterCoverage)}`,
+    `- required section coverage: ${formatPercent(metrics.requiredSectionCoverage)}`,
+    `- source refs coverage: ${formatPercent(metrics.sourceRefsCoverage)}`,
+    `- source evidence coverage: ${formatPercent(metrics.sourceEvidenceCoverage)}`,
+    `- source pages: ${metrics.sourcePageCount}`,
+    `- source pages accepted as provenance anchors: ${metrics.sourceThinAnchorCount}`,
+    `- source-page thin-anchor ratio: ${formatPercent(metrics.sourceThinAnchorRatio)}`,
+    `- strict semantic pages: ${metrics.semanticPageCount}`,
+    `- strict semantic stub pages: ${metrics.semanticStubCount}`,
+    `- semantic stub ratio: ${formatPercent(metrics.semanticStubRatio)}`,
+    `- stub ratio policy: source pages are measured separately; strict stub findings apply to tool_entity, concept, comparison, and synthesis pages.`,
+    `- giant page warnings: ${metrics.giantPageCount}`,
+    `- broken local wiki internal links: ${metrics.brokenInternalLinks}`,
+    `- entity pages: ${metrics.entityCount}`,
+    `- concept pages: ${metrics.conceptCount}`,
+    `- comparison pages: ${metrics.comparisonCount}`,
+    `- synthesis pages: ${metrics.synthesisCount}`,
+    "",
+    "| Page type | Count |",
+    "|---|---:|",
+    ...(typeRows.length > 0 ? typeRows : ["| none | 0 |"]),
+    "",
+  ];
+}
+
+function renderReport({ projectPath, workspaceRoot, findings, pageCount, personalBrainMetrics }) {
   const summaryRows = CATEGORY_DEFS.map(
     ([key, label]) => `| ${label} | ${findings[key].length} |`
   );
@@ -593,6 +871,7 @@ function renderReport({ projectPath, workspaceRoot, findings, pageCount }) {
     "|---|---:|",
     ...summaryRows,
     "",
+    ...renderPersonalBrainMetrics(personalBrainMetrics),
     ...detailSections,
   ].join("\n");
 }
@@ -622,12 +901,14 @@ function runWikiLint(options = {}) {
       workspaceRoot,
       findings: analysis.findings,
       pageCount: analysis.pageCount,
+      personalBrainMetrics: analysis.personalBrainMetrics,
     });
     fs.writeFileSync(reportPath, report + "\n", "utf-8");
     return {
       reportPath,
       totalFindings: totalFindings(analysis.findings),
       findings: analysis.findings,
+      personalBrainMetrics: analysis.personalBrainMetrics,
     };
   } catch (error) {
     if (error instanceof CliError) throw error;
@@ -637,6 +918,7 @@ function runWikiLint(options = {}) {
 
 module.exports = {
   CATEGORY_DEFS,
+  REQUIRED_PERSONAL_BRAIN_FIELDS,
   REQUIRED_PAGE_FIELDS,
   analyzePages,
   parseFrontmatter,

package/src/lib/wiki-paths.js

@@ -15,6 +15,8 @@ const WIKI_PROVENANCE_SOURCES_RELATIVE = path.join(".sdtk", "wiki", "provenance"
 const WIKI_QUERIES_RELATIVE = path.join(".sdtk", "wiki", "queries");
 const WIKI_REPORTS_RELATIVE = path.join(".sdtk", "wiki", "reports");
 const WIKI_LOGS_RELATIVE = path.join(".sdtk", "wiki", "logs");
+const CANONICAL_WIKI_RELATIVE = "wiki";
+const LEGACY_PERSONAL_BRAIN_RELATIVE = path.join(".sdtk", "wiki", "personal-brain");
 const LEGACY_ATLAS_RELATIVE = path.join(".sdtk", "atlas");
 
 function resolveProjectPath(projectPath) {
@@ -51,6 +53,43 @@ function getWikiWorkspacePath(projectPath) {
   return path.join(resolveProjectPath(projectPath), WIKI_WORKSPACE_RELATIVE);
 }
 
+function getCanonicalWikiPath(projectPath) {
+  return path.join(resolveProjectPath(projectPath), CANONICAL_WIKI_RELATIVE);
+}
+
+function getLegacyPersonalBrainPath(projectPath) {
+  return path.join(resolveProjectPath(projectPath), LEGACY_PERSONAL_BRAIN_RELATIVE);
+}
+
+function getPreferredWikiContentPath(projectPath) {
+  const canonical = getCanonicalWikiPath(projectPath);
+  const legacy = getLegacyPersonalBrainPath(projectPath);
+  try {
+    const fs = require("fs");
+    if (fs.existsSync(canonical) && fs.statSync(canonical).isDirectory()) {
+      return {
+        path: canonical,
+        mode: "canonical_project_wiki",
+        relative: CANONICAL_WIKI_RELATIVE,
+      };
+    }
+    if (fs.existsSync(legacy) && fs.statSync(legacy).isDirectory()) {
+      return {
+        path: legacy,
+        mode: "legacy_personal_brain_fallback",
+        relative: LEGACY_PERSONAL_BRAIN_RELATIVE,
+      };
+    }
+  } catch (_) {
+    // Callers perform their own existence validation and error reporting.
+  }
+  return {
+    path: canonical,
+    mode: "canonical_project_wiki",
+    relative: CANONICAL_WIKI_RELATIVE,
+  };
+}
+
 function getWikiGraphPath(projectPath) {
   return path.join(resolveProjectPath(projectPath), WIKI_GRAPH_RELATIVE);
 }
@@ -111,9 +150,19 @@ function assertWikiWorkspaceWritePath(targetPath, projectPath) {
   );
 }
 
+function assertCanonicalWikiWritePath(targetPath, projectPath) {
+  return assertPathInsideOrEqual(
+    targetPath,
+    getCanonicalWikiPath(projectPath),
+    "Refusing to write outside project-local wiki output"
+  );
+}
+
 function describeWikiPaths(projectPath) {
   return {
     projectPath: resolveProjectPath(projectPath),
+    canonicalWikiPath: getCanonicalWikiPath(projectPath),
+    legacyPersonalBrainPath: getLegacyPersonalBrainPath(projectPath),
     wikiWorkspacePath: getWikiWorkspacePath(projectPath),
     wikiGraphPath: getWikiGraphPath(projectPath),
     wikiManifestPath: getWikiManifestPath(projectPath),
@@ -132,7 +181,9 @@ function describeWikiPaths(projectPath) {
 }
 
 module.exports = {
+  CANONICAL_WIKI_RELATIVE,
   LEGACY_ATLAS_RELATIVE,
+  LEGACY_PERSONAL_BRAIN_RELATIVE,
   WIKI_GRAPH_RELATIVE,
   WIKI_LOGS_RELATIVE,
   WIKI_MANIFEST_RELATIVE,
@@ -147,9 +198,13 @@ module.exports = {
   WIKI_REPORTS_RELATIVE,
   WIKI_WORKSPACE_RELATIVE,
   assertPathInsideOrEqual,
+  assertCanonicalWikiWritePath,
   assertWikiWorkspaceWritePath,
   describeWikiPaths,
+  getCanonicalWikiPath,
+  getLegacyPersonalBrainPath,
   getLegacyAtlasPath,
+  getPreferredWikiContentPath,
   getWikiGraphPath,
   getWikiLogsPath,
   getWikiManifestPath,

package/src/lib/wiki-search.js

@@ -4,13 +4,14 @@ const fs = require("fs");
 const path = require("path");
 const { ValidationError } = require("./errors");
 const {
-  getWikiWorkspacePath,
+  getPreferredWikiContentPath,
   isPathInsideOrEqual,
   resolveProjectPath,
 } = require("./wiki-paths");
 
 const DEFAULT_LIMIT = 10;
-const PERSONAL_BRAIN_RELATIVE = path.join(".sdtk", "wiki", "personal-brain");
+const CANONICAL_WIKI_RELATIVE = "wiki";
+const LEGACY_PERSONAL_BRAIN_RELATIVE = path.join(".sdtk", "wiki", "personal-brain");
 
 function toPosix(value) {
   return String(value || "").replace(/\\/g, "/");
@@ -120,18 +121,19 @@ function runWikiSearch({ projectPath, query, limit = DEFAULT_LIMIT }) {
 
   const parsedLimit = Number.parseInt(limit, 10);
   const safeLimit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? Math.min(parsedLimit, 50) : DEFAULT_LIMIT;
-  const personalBrainPath = path.join(getWikiWorkspacePath(resolvedProjectPath), "personal-brain");
-  if (!isPathInsideOrEqual(personalBrainPath, resolvedProjectPath)) {
+  const contentRoot = getPreferredWikiContentPath(resolvedProjectPath);
+  const wikiContentPath = contentRoot.path;
+  if (!isPathInsideOrEqual(wikiContentPath, resolvedProjectPath)) {
     throw new ValidationError("Refusing to search outside the project root.");
   }
-  if (!fs.existsSync(personalBrainPath) || !fs.statSync(personalBrainPath).isDirectory()) {
+  if (!fs.existsSync(wikiContentPath) || !fs.statSync(wikiContentPath).isDirectory()) {
     throw new ValidationError(
-      `No SDTK-WIKI personal brain found at ${personalBrainPath}. Run "sdtk-wiki ingest <source-root>" and "sdtk-wiki compile --mode safe --apply" first. Advanced users can still use wiki extract/compile sidecar commands.`
+      `No SDTK-WIKI local wiki found at ${wikiContentPath}. Run "sdtk-wiki ingest <source-root>" and "sdtk-wiki compile --mode safe --apply" first. Legacy .sdtk/wiki/personal-brain workspaces are still readable when present.`
     );
   }
 
   const tokens = tokenize(normalizedQuery);
-  const files = collectMarkdownFiles(personalBrainPath);
+  const files = collectMarkdownFiles(wikiContentPath);
   const matches = [];
 
   for (const filePath of files) {
@@ -157,19 +159,24 @@ function runWikiSearch({ projectPath, query, limit = DEFAULT_LIMIT }) {
   return {
     query: normalizedQuery,
     projectPath: resolvedProjectPath,
-    personalBrainPath,
+    wikiContentPath,
+    wikiContentMode: contentRoot.mode,
+    personalBrainPath: wikiContentPath,
     scannedFiles: files.length,
     matches: matches.slice(0, safeLimit),
     totalMatches: matches.length,
     limit: safeLimit,
-    searchMode: "local_deterministic_personal_brain_markdown",
+    searchMode: contentRoot.mode === "canonical_project_wiki"
+      ? "local_deterministic_project_wiki_markdown"
+      : "local_deterministic_legacy_personal_brain_markdown",
     premiumRequired: false,
     mutated: false,
   };
 }
 
 module.exports = {
-  PERSONAL_BRAIN_RELATIVE,
+  CANONICAL_WIKI_RELATIVE,
+  LEGACY_PERSONAL_BRAIN_RELATIVE,
   runWikiSearch,
   tokenize,
 };