wicked-brain 0.9.2 → 0.11.0

package/server/lib/gen-contract-schema.mjs

@@ -0,0 +1,200 @@
+/**
+ * Contract schema generator.
+ *
+ * Reads `sqlite-search.mjs` and extracts:
+ *   - Every `CREATE TABLE IF NOT EXISTS <name>(...)` → tables + columns.
+ *   - The migration ladder from `#migrate()` — each `if (currentVersion < N)`
+ *     block becomes a migration entry with its notes and the columns/tables
+ *     it adds.
+ *
+ * Pure functions — no I/O. CLI glue writes the outputs.
+ */
+
+// "IF NOT EXISTS" is optional so we match CREATE TABLEs in migrations too.
+const CREATE_TABLE_RE =
+  /CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+(\w+)\s*\(([\s\S]*?)\)\s*;/g;
+
+const ALTER_ADD_COLUMN_RE =
+  /ALTER\s+TABLE\s+(\w+)\s+ADD\s+COLUMN\s+(\w+)\s+([A-Z]+(?:\s+[A-Z]+)*)/gi;
+
+// Match `if (currentVersion < N) { ... }`. Body is balanced-brace-captured
+// heuristically by scanning outward from the match until depth zero.
+const MIGRATION_OPEN_RE = /if\s*\(\s*currentVersion\s*<\s*(\d+)\s*\)\s*\{/g;
+
+/**
+ * Extract schema + migrations from sqlite-search.mjs source.
+ */
+export function extractSchema(source) {
+  const tables = extractTables(source);
+  const migrations = extractMigrations(source);
+  return { tables, migrations };
+}
+
+/**
+ * Render contract-schema.md.
+ */
+export function renderContractSchema({ tables, migrations, generatedAt, sourcePath }) {
+  const lines = [];
+  lines.push("---");
+  lines.push("status: published");
+  lines.push("canonical_for: [CONTRACT-SCHEMA]");
+  lines.push("references: [INV-MIGRATION-REQUIRED]");
+  lines.push("owner: core");
+  lines.push(`last_reviewed: ${generatedAt}`);
+  lines.push("generated: true");
+  lines.push(`source: ${sourcePath}`);
+  lines.push("---");
+  lines.push("");
+  lines.push("# Contract: SQLite schema");
+  lines.push("");
+  lines.push(
+    "Generated from `" + sourcePath + "`. Do not hand-edit — regenerate with "
+    + "`npm run gen:wiki`. Changes to the schema require a numbered migration "
+    + "per `INV-MIGRATION-REQUIRED`.",
+  );
+  lines.push("");
+  lines.push("## Tables");
+  lines.push("");
+  for (const t of tables) {
+    lines.push(`### \`${t.name}\``);
+    lines.push("");
+    lines.push("| Column | Type | Notes |");
+    lines.push("|---|---|---|");
+    for (const c of t.columns) {
+      lines.push(`| \`${c.name}\` | \`${c.type}\` | ${c.notes || ""} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Migration ladder");
+  lines.push("");
+  lines.push("| Version | Summary | Operations |");
+  lines.push("|---|---|---|");
+  for (const m of migrations) {
+    const ops = m.ops.length ? m.ops.map((o) => `\`${o}\``).join(", ") : "—";
+    lines.push(`| ${m.version} | ${m.summary || "—"} | ${ops} |`);
+  }
+  lines.push("");
+  lines.push("Current head: **v" + (migrations.at(-1)?.version ?? "?") + "**.");
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+export function renderSchemaJson({ tables, migrations, generatedAt, sourcePath }) {
+  return {
+    generated_at: generatedAt,
+    source: sourcePath,
+    canonical_id: "CONTRACT-SCHEMA",
+    head_version: migrations.at(-1)?.version ?? null,
+    tables,
+    migrations,
+  };
+}
+
+// --- internals ---
+
+function extractTables(source) {
+  const tables = new Map();
+  CREATE_TABLE_RE.lastIndex = 0;
+  let m;
+  while ((m = CREATE_TABLE_RE.exec(source)) !== null) {
+    const name = m[1];
+    // Skip FTS virtual tables from CREATE VIRTUAL TABLE (different grammar);
+    // our regex is CREATE TABLE, which won't match those — but also skip
+    // `_schema_version` noise duplicates.
+    const cols = parseColumns(m[2]);
+    if (!cols.length) continue;
+    // Prefer first-seen to keep the column list from #initSchema (fuller)
+    // rather than a stripped migration copy.
+    if (!tables.has(name)) tables.set(name, { name, columns: cols });
+  }
+  return [...tables.values()];
+}
+
+function parseColumns(body) {
+  // Split on commas at depth zero so `DEFAULT 0.5` etc. survive.
+  const parts = [];
+  let depth = 0, buf = "";
+  for (const ch of body) {
+    if (ch === "(") { depth++; buf += ch; continue; }
+    if (ch === ")") { depth--; buf += ch; continue; }
+    if (ch === "," && depth === 0) { parts.push(buf); buf = ""; continue; }
+    buf += ch;
+  }
+  if (buf.trim().length > 0) parts.push(buf);
+
+  const out = [];
+  for (const p of parts) {
+    const trimmed = p.trim();
+    if (!trimmed) continue;
+    // Skip table-level constraints like PRIMARY KEY(a, b).
+    if (/^(PRIMARY|FOREIGN|UNIQUE|CHECK)\b/i.test(trimmed)) continue;
+    const m2 = trimmed.match(/^(\w+)\s+([A-Z]+(?:\s+[A-Z0-9_]+)*)?(.*)$/i);
+    if (!m2) continue;
+    const name = m2[1];
+    const type = (m2[2] || "").trim() || "TEXT";
+    const rest = (m2[3] || "").trim();
+    out.push({
+      name,
+      type,
+      notes: rest.replace(/\s+/g, " "),
+    });
+  }
+  return out;
+}
+
+function extractMigrations(source) {
+  const migrations = [];
+  MIGRATION_OPEN_RE.lastIndex = 0;
+  let m;
+  while ((m = MIGRATION_OPEN_RE.exec(source)) !== null) {
+    const version = Number(m[1]);
+    const blockStart = m.index + m[0].length; // inside `{`
+    const blockEnd = findMatchingBrace(source, blockStart - 1);
+    if (blockEnd < 0) continue;
+    const body = source.slice(blockStart, blockEnd);
+    // Find the preceding comment for the summary.
+    const preamble = source.slice(Math.max(0, m.index - 400), m.index);
+    const commentMatch = preamble.match(new RegExp(`//\\s*Migration\\s+${version}:\\s*(.+)`));
+    const summary = commentMatch ? commentMatch[1].trim() : "";
+    migrations.push({
+      version,
+      summary,
+      ops: extractMigrationOps(body),
+    });
+  }
+  migrations.sort((a, b) => a.version - b.version);
+  return migrations;
+}
+
+function extractMigrationOps(body) {
+  const ops = new Set();
+  ALTER_ADD_COLUMN_RE.lastIndex = 0;
+  let m;
+  while ((m = ALTER_ADD_COLUMN_RE.exec(body)) !== null) {
+    ops.add(`ADD COLUMN ${m[1]}.${m[2]}`);
+  }
+  const createRe = /CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+(\w+)\s*\(/gi;
+  while ((m = createRe.exec(body)) !== null) {
+    ops.add(`CREATE TABLE ${m[1]}`);
+  }
+  const idxRe = /CREATE\s+INDEX(?:\s+IF\s+NOT\s+EXISTS)?\s+(\w+)\s+ON\s+(\w+)/gi;
+  while ((m = idxRe.exec(body)) !== null) {
+    ops.add(`CREATE INDEX ${m[1]} ON ${m[2]}`);
+  }
+  return [...ops];
+}
+
+function findMatchingBrace(source, openIdx) {
+  // openIdx points at '{'
+  let depth = 0;
+  for (let i = openIdx; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}

package/server/lib/gen-file-map.mjs

@@ -0,0 +1,121 @@
+/**
+ * File-map generator.
+ *
+ * Walks `server/lib/` and `server/bin/`, produces a per-file record with:
+ *   - Purpose (first paragraph of the earliest JSDoc block, if any)
+ *   - Exports (`export function/class/const` plus named re-exports)
+ *   - Local imports (relative `./...` imports — other server modules)
+ *
+ * Output is a markdown page (`map-files.md`) plus a JSON manifest
+ * (`_generated/files.json`). Pure functions — CLI glue walks the disk.
+ */
+
+const JSDOC_RE = /\/\*\*([\s\S]*?)\*\//;
+const EXPORT_NAMED_RE =
+  /^\s*export\s+(?:async\s+)?(function|class|const|let|var)\s+([a-zA-Z_][a-zA-Z0-9_]*)/gm;
+const EXPORT_LIST_RE = /^\s*export\s*\{\s*([^}]+)\}\s*(?:from\s*['"][^'"]+['"])?/gm;
+const IMPORT_LOCAL_RE =
+  /^\s*import\s+[^'"]*?from\s+['"](\.\.?\/[^'"]+)['"]/gm;
+
+/**
+ * Build a file-map record from a file's source text.
+ */
+export function buildFileRecord({ relPath, source }) {
+  return {
+    path: relPath,
+    purpose: extractPurpose(source),
+    exports: extractExports(source),
+    imports: extractLocalImports(source),
+  };
+}
+
+/**
+ * Render map-files.md from a list of file records (already ordered).
+ */
+export function renderFileMap({ files, generatedAt, sourceRoots }) {
+  const lines = [];
+  lines.push("---");
+  lines.push("status: published");
+  lines.push("canonical_for: [MAP-FILES]");
+  lines.push("references: []");
+  lines.push("owner: core");
+  lines.push(`last_reviewed: ${generatedAt}`);
+  lines.push("generated: true");
+  lines.push(`source_roots: [${sourceRoots.join(", ")}]`);
+  lines.push("---");
+  lines.push("");
+  lines.push("# Map: files");
+  lines.push("");
+  lines.push(
+    "Generated walk of `" + sourceRoots.join("`, `") + "`. Do not hand-edit — "
+    + "regenerate with `npm run gen:wiki`. Purpose strings come from the "
+    + "first JSDoc block in each file; files without a JSDoc header have "
+    + "empty purpose and are candidates for docstring work.",
+  );
+  lines.push("");
+  lines.push("## Files");
+  lines.push("");
+  lines.push("| Path | Purpose | Exports | Local imports |");
+  lines.push("|---|---|---|---|");
+  for (const f of files) {
+    const exports = f.exports.length ? f.exports.map((e) => `\`${e}\``).join(", ") : "—";
+    const imports = f.imports.length ? f.imports.map((i) => `\`${i}\``).join(", ") : "—";
+    const purpose = (f.purpose || "").replace(/\|/g, "\\|");
+    lines.push(`| \`${f.path}\` | ${purpose || "—"} | ${exports} | ${imports} |`);
+  }
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+export function renderFileMapJson({ files, generatedAt, sourceRoots }) {
+  return {
+    generated_at: generatedAt,
+    source_roots: sourceRoots,
+    canonical_id: "MAP-FILES",
+    count: files.length,
+    files,
+  };
+}
+
+// --- internals ---
+
+function extractPurpose(source) {
+  const m = source.match(JSDOC_RE);
+  if (!m) return "";
+  // Strip leading `*` prefixes, split into blank-line paragraphs, take first.
+  const cleaned = m[1]
+    .split("\n")
+    .map((line) => line.replace(/^\s*\*\s?/, "").trimEnd())
+    .join("\n")
+    .trim();
+  const firstPara = cleaned.split(/\n\s*\n/)[0] || "";
+  return firstPara.replace(/\s+/g, " ").trim();
+}
+
+function extractExports(source) {
+  const out = new Set();
+  EXPORT_NAMED_RE.lastIndex = 0;
+  let m;
+  while ((m = EXPORT_NAMED_RE.exec(source)) !== null) {
+    out.add(m[2]);
+  }
+  EXPORT_LIST_RE.lastIndex = 0;
+  while ((m = EXPORT_LIST_RE.exec(source)) !== null) {
+    const names = m[1]
+      .split(",")
+      .map((s) => s.trim().replace(/\s+as\s+.+$/, "").trim())
+      .filter(Boolean);
+    for (const n of names) out.add(n);
+  }
+  return [...out].sort();
+}
+
+function extractLocalImports(source) {
+  const out = new Set();
+  IMPORT_LOCAL_RE.lastIndex = 0;
+  let m;
+  while ((m = IMPORT_LOCAL_RE.exec(source)) !== null) {
+    out.add(m[1]);
+  }
+  return [...out].sort();
+}

package/server/lib/lint-wiki.mjs

@@ -0,0 +1,168 @@
+/**
+ * Wiki linter.
+ *
+ * Pure functions that run rules against a built canonical registry plus the
+ * raw file contents of each page. I/O (walking the disk, stat'ing referenced
+ * paths) lives in the CLI wrapper — this module is testable with synthetic
+ * inputs.
+ *
+ * Rule levels are "error" (fails the lint) or "warn" (informational, but
+ * `--strict` mode promotes to error).
+ */
+
+const DEFAULT_LONG_PAGE_LINES = 80;
+const DEFAULT_LONG_PAGE_MIN_REFS = 3;
+// Pages that own multiple canonical IDs are foundational (e.g. invariants,
+// glossary) — their line count reflects the content they own, not a
+// pointer-page that grew. Skip the restating heuristic for them.
+const CANONICAL_ANCHOR_THRESHOLD = 2;
+
+/**
+ * Run every rule and return a flat list of findings.
+ *
+ * Inputs:
+ *   registry      — output of buildRegistry
+ *   pages         — [{ path, data, body, lineCount }]
+ *   knownPaths    — Set of repo-relative paths that exist (for ref resolution)
+ *
+ * Returns: [{ rule, level, page, message, extra }]
+ */
+export function runLintRules({ registry, pages, knownPaths = new Set(), options = {} }) {
+  const findings = [];
+  findings.push(...ruleDuplicateCanonicalFor(registry));
+  findings.push(...ruleBrokenReference(registry, knownPaths));
+  findings.push(...ruleLongPageLowRefs(pages, options));
+  findings.push(...ruleMissingCanonicalPurpose(pages));
+  return findings;
+}
+
+/**
+ * ERROR if any canonical_for ID is claimed by two or more pages.
+ */
+export function ruleDuplicateCanonicalFor(registry) {
+  const out = [];
+  for (const dup of registry.duplicates) {
+    out.push({
+      rule: "duplicate_canonical_for",
+      level: "error",
+      page: dup.paths[0],
+      message: `canonical_for: ${dup.id} claimed by multiple pages`,
+      extra: { id: dup.id, paths: dup.paths },
+    });
+  }
+  return out;
+}
+
+/**
+ * ERROR if a `references` entry doesn't resolve to a canonical ID or a
+ * known path. External URLs (http/https) are skipped.
+ */
+export function ruleBrokenReference(registry, knownPaths) {
+  const out = [];
+  const canonicalIds = new Set(registry.byId.keys());
+  for (const page of registry.pages) {
+    for (const ref of page.references) {
+      if (/^https?:/i.test(ref)) continue;
+      if (isResolvable(ref, canonicalIds, knownPaths)) continue;
+      out.push({
+        rule: "broken_reference",
+        level: "error",
+        page: page.path,
+        message: `unresolved reference: ${ref}`,
+        extra: { ref },
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * WARN if a non-generated page has a body over N lines and fewer than M
+ * outbound references. Heuristic for "probably restating instead of linking."
+ */
+export function ruleLongPageLowRefs(pages, options = {}) {
+  const linesThreshold = options.longPageLines ?? DEFAULT_LONG_PAGE_LINES;
+  const minRefs = options.longPageMinRefs ?? DEFAULT_LONG_PAGE_MIN_REFS;
+  const out = [];
+  for (const p of pages) {
+    if (p.data?.generated === true) continue;
+    const canonicalCount = normalizeList(p.data?.canonical_for).length;
+    if (canonicalCount >= CANONICAL_ANCHOR_THRESHOLD) continue;
+    const refCount = normalizeList(p.data?.references).length;
+    if (p.lineCount > linesThreshold && refCount < minRefs) {
+      out.push({
+        rule: "long_page_low_refs",
+        level: "warn",
+        page: p.path,
+        message: `${p.lineCount} lines with only ${refCount} references — probably restating`,
+        extra: { lines: p.lineCount, refs: refCount },
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * WARN if a page declares neither canonical_for nor references. Such a page
+ * owns nothing and cites nothing — it's probably an orphan or a restated copy.
+ */
+export function ruleMissingCanonicalPurpose(pages) {
+  const out = [];
+  for (const p of pages) {
+    if (p.data?.generated === true) continue;
+    const canon = normalizeList(p.data?.canonical_for);
+    const refs = normalizeList(p.data?.references);
+    if (canon.length === 0 && refs.length === 0) {
+      out.push({
+        rule: "missing_canonical_purpose",
+        level: "warn",
+        page: p.path,
+        message: "page has no canonical_for and no references",
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Exit-code mapping. Non-strict: any error → 1. Strict: any finding → 1.
+ */
+export function lintExitCode(findings, { strict = false } = {}) {
+  if (findings.length === 0) return 0;
+  if (strict) return 1;
+  return findings.some((f) => f.level === "error") ? 1 : 0;
+}
+
+/**
+ * Human-readable text report.
+ */
+export function formatFindings(findings) {
+  if (findings.length === 0) return "wiki lint: clean.";
+  const lines = [];
+  for (const f of findings) {
+    lines.push(`[${f.level}] ${f.page}: ${f.rule} — ${f.message}`);
+  }
+  return lines.join("\n");
+}
+
+// --- internals ---
+
+function normalizeList(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  if (typeof value === "string" && value.length > 0) return [value];
+  return [];
+}
+
+function isResolvable(ref, canonicalIds, knownPaths) {
+  if (canonicalIds.has(ref)) return true;
+  const hashIdx = ref.indexOf("#");
+  if (hashIdx >= 0) {
+    const anchor = ref.slice(hashIdx + 1);
+    if (canonicalIds.has(anchor)) return true;
+    const pathPart = ref.slice(0, hashIdx);
+    if (pathPart.length > 0 && knownPaths.has(pathPart)) return true;
+  }
+  if (knownPaths.has(ref)) return true;
+  return false;
+}

package/server/lib/mode-config.mjs

@@ -0,0 +1,120 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const MODE_FILE_REL = ".wicked-brain/mode.json";
+const SCHEMA_VERSION = 1;
+const VALID_MODES = new Set(["code", "content", "mixed", "unknown"]);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Validate a mode.json body. Returns { ok, errors } — does not throw.
+ * Kept in lockstep with mode.schema.json. The schema is the canonical
+ * documentation; this is the runtime enforcement.
+ */
+export function validateMode(body) {
+  const errors = [];
+  if (!body || typeof body !== "object") {
+    return { ok: false, errors: ["body is not an object"] };
+  }
+  if (body.schema_version !== SCHEMA_VERSION) {
+    errors.push(`schema_version must be ${SCHEMA_VERSION}, got ${body.schema_version}`);
+  }
+  if (!VALID_MODES.has(body.mode)) {
+    errors.push(`mode must be one of ${[...VALID_MODES].join(", ")}, got ${body.mode}`);
+  }
+  if (typeof body.wiki_root !== "string" || body.wiki_root.length === 0) {
+    errors.push("wiki_root must be a non-empty string");
+  }
+  if (body.content_root !== null && typeof body.content_root !== "string") {
+    errors.push("content_root must be string or null");
+  }
+  if (typeof body.detected_at !== "string" || !DATE_RE.test(body.detected_at)) {
+    errors.push("detected_at must be YYYY-MM-DD");
+  }
+  if (typeof body.override !== "boolean") {
+    errors.push("override must be boolean");
+  }
+  if (body.score !== undefined) {
+    if (!body.score || typeof body.score !== "object") errors.push("score must be an object");
+    else {
+      if (typeof body.score.code !== "number") errors.push("score.code must be a number");
+      if (typeof body.score.content !== "number") errors.push("score.content must be a number");
+    }
+  }
+  if (body.reasons !== undefined && !Array.isArray(body.reasons)) {
+    errors.push("reasons must be an array");
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Read .wicked-brain/mode.json for a repo. Returns null if missing.
+ * Throws on malformed JSON so callers can surface the issue rather than
+ * silently re-detecting over a corrupt file.
+ */
+export async function readModeFile(repoRoot) {
+  const p = path.join(repoRoot, MODE_FILE_REL);
+  let raw;
+  try {
+    raw = await fs.readFile(p, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  return JSON.parse(raw);
+}
+
+/**
+ * Write .wicked-brain/mode.json for a repo.
+ *
+ * Honors override:true on any existing file — will not overwrite a
+ * human-managed mode.json. Detection-managed writes pass through.
+ *
+ * Returns { written: boolean, reason?: string, path: string }.
+ */
+export async function writeModeFile(repoRoot, detection, { override = false } = {}) {
+  const p = path.join(repoRoot, MODE_FILE_REL);
+  const existing = await readModeFile(repoRoot);
+  if (existing && existing.override === true && override === false) {
+    return { written: false, reason: "override:true present — not overwriting", path: p };
+  }
+
+  const now = new Date().toISOString().slice(0, 10);
+  const body = {
+    schema_version: SCHEMA_VERSION,
+    mode: detection.mode,
+    wiki_root: detection.wiki_root,
+    content_root: detection.content_root ?? null,
+    detected_at: now,
+    override,
+    score: detection.score,
+    reasons: detection.reasons,
+  };
+
+  const { ok, errors } = validateMode(body);
+  if (!ok) {
+    throw new Error(`invalid mode.json body: ${errors.join("; ")}`);
+  }
+
+  await fs.mkdir(path.dirname(p), { recursive: true });
+  await fs.writeFile(p, JSON.stringify(body, null, 2) + "\n", "utf8");
+  return { written: true, path: p };
+}
+
+/**
+ * Compare an existing mode.json against a fresh detection.
+ * Returns { changed: boolean, fields: string[] } — callers decide whether
+ * to warn the user before writing.
+ */
+export function diffMode(existing, detection) {
+  if (!existing) return { changed: true, fields: ["(no prior mode.json)"] };
+  const fields = [];
+  if (existing.mode !== detection.mode) fields.push("mode");
+  if (existing.wiki_root !== detection.wiki_root) fields.push("wiki_root");
+  if ((existing.content_root ?? null) !== (detection.content_root ?? null)) {
+    fields.push("content_root");
+  }
+  return { changed: fields.length > 0, fields };
+}
+
+export const MODE_FILE_PATH = MODE_FILE_REL;

package/server/lib/mode.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wicked-brain.dev/schemas/mode.schema.json",
+  "title": "wicked-brain mode.json",
+  "description": "Repo-mode detection result. Written to .wicked-brain/mode.json at the repo root. Drives wiki location, lint rules, and ingest scoring.",
+  "type": "object",
+  "required": ["schema_version", "mode", "wiki_root", "detected_at", "override"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Bumped when incompatible fields change."
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["code", "content", "mixed", "unknown"],
+      "description": "Repo classification. Drives which page set, lint rules, and ingest scoring apply."
+    },
+    "wiki_root": {
+      "type": "string",
+      "description": "Repo-relative path to the contributor wiki (default: 'wiki'). Always set, even in content mode — meta pages like taxonomy.md live here."
+    },
+    "content_root": {
+      "type": ["string", "null"],
+      "description": "Repo-relative path to the content corpus. Null in code/unknown modes. Defaults to 'docs' if present, else 'content'."
+    },
+    "detected_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) the mode was last written."
+    },
+    "override": {
+      "type": "boolean",
+      "description": "If true, the file was set by a human. Detection must not overwrite without an explicit override:true write."
+    },
+    "score": {
+      "type": "object",
+      "required": ["code", "content"],
+      "additionalProperties": false,
+      "properties": {
+        "code": { "type": "number" },
+        "content": { "type": "number" }
+      },
+      "description": "Scores that led to the classification. Informational; inspectable by agents."
+    },
+    "reasons": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Human-readable list of signals that produced the score. Informational."
+    }
+  }
+}