knodin 0.5.0

package/dist/src/context-export.js

@@ -0,0 +1,422 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { RE2 } from "re2-wasm";
+import { measurePerfPhaseSync } from "./engine/perf.js";
+const DEFAULT_EXCLUDES = [".git/**", ".reckon/**", "node_modules/**", "dist/**", "build/**"];
+const GLOB_CACHE_LIMIT = 256;
+const globCache = new Map();
+function normalizeRelative(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function globRegex(glob) {
+    const normalized = normalizeRelative(glob);
+    const cached = globCache.get(normalized);
+    if (cached)
+        return cached;
+    let source = "^";
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized[i];
+        if (char === "*") {
+            if (normalized[i + 1] === "*") {
+                i++;
+                if (normalized[i + 1] === "/") {
+                    i++;
+                    source += "(?:.*/)?";
+                }
+                else
+                    source += ".*";
+            }
+            else
+                source += "[^/]*";
+        }
+        else if (char === "?")
+            source += "[^/]";
+        else
+            source += char.replace(/[\\^$+?.()|{}[\]]/g, "\\$&");
+    }
+    const compiled = new RegExp(`${source}$`);
+    if (globCache.size >= GLOB_CACHE_LIMIT) {
+        const oldest = globCache.keys().next().value;
+        if (oldest !== undefined)
+            globCache.delete(oldest);
+    }
+    globCache.set(normalized, compiled);
+    return compiled;
+}
+function matches(file, patterns) {
+    return patterns.some((pattern) => globRegex(normalizeRelative(pattern)).test(file));
+}
+function compilePatterns(patterns) {
+    return patterns.map((pattern) => globRegex(normalizeRelative(pattern)));
+}
+function matchesCompiled(file, patterns) {
+    return patterns.some((pattern) => pattern.test(file));
+}
+function walk(root, current = root, result = []) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        const absolute = path.join(current, entry.name);
+        const relative = normalizeRelative(path.relative(root, absolute));
+        if (matches(relative, DEFAULT_EXCLUDES) || matches(`${relative}/`, DEFAULT_EXCLUDES))
+            continue;
+        if (entry.isDirectory())
+            walk(root, absolute, result);
+        else if (entry.isFile())
+            result.push(relative);
+    }
+    return result;
+}
+function policyFor(file, policies) {
+    for (const { pattern, policy } of policies)
+        if (pattern.test(file))
+            return policy;
+    return "full";
+}
+function structureOnly(source, lineNumbers = false) {
+    return source
+        .split(/\r?\n/)
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => /^\s*(export\s+)?(async\s+)?(class|interface|type|enum|function|const|let|var|def|module|namespace)\b/.test(line) || /^\s*(import|export)\b/.test(line))
+        .map(({ line, index }) => (lineNumbers ? `${index + 1}: ${line}` : line))
+        .join("\n");
+}
+function summarize(source, lineNumbers = false) {
+    const lines = source.split(/\r?\n/);
+    const structure = structureOnly(source, lineNumbers);
+    return [`[summary: ${lines.length} lines, ${Buffer.byteLength(source)} bytes]`, structure]
+        .filter(Boolean)
+        .join("\n");
+}
+function numbered(source) {
+    return source
+        .split(/\r?\n/)
+        .map((line, index) => `${index + 1}: ${line}`)
+        .join("\n");
+}
+function xmlEscape(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function serialize(format, files, tree, git) {
+    if (format === "json")
+        return JSON.stringify({ tree, files, git }, null, 2);
+    if (format === "xml") {
+        const treeXml = tree
+            ? `<tree>${tree.map((item) => `<path>${xmlEscape(item)}</path>`).join("")}</tree>`
+            : "";
+        const filesXml = files
+            .map((file) => `<file path="${xmlEscape(file.path)}" policy="${file.policy}"><![CDATA[${file.content.replaceAll("]]>", "]]]]><![CDATA[>")}]]></file>`)
+            .join("");
+        const gitXml = git
+            ? `<git>${git.diff === undefined ? "" : `<diff><![CDATA[${git.diff.replaceAll("]]>", "]]]]><![CDATA[>")}]]></diff>`}${git.log === undefined ? "" : `<log><![CDATA[${git.log.replaceAll("]]>", "]]]]><![CDATA[>")}]]></log>`}</git>`
+            : "";
+        return `<context>${treeXml}<files>${filesXml}</files>${gitXml}</context>`;
+    }
+    const fenced = (content, language = "") => {
+        const longest = Math.max(0, ...[...content.matchAll(/`+/g)].map((match) => match[0].length));
+        const fence = "`".repeat(Math.max(3, longest + 1));
+        return [`${fence}${language}`, content, fence];
+    };
+    const chunks = ["# knodin context export"];
+    if (tree)
+        chunks.push("## Tree", ...fenced(tree.join("\n"), "text"));
+    for (const file of files)
+        chunks.push(`## ${file.path} (${file.policy})`, ...fenced(file.content));
+    if (git?.diff !== undefined)
+        chunks.push("## Git diff", ...fenced(git.diff, "diff"));
+    if (git?.log !== undefined)
+        chunks.push("## Git log", ...fenced(git.log, "text"));
+    return chunks.join("\n");
+}
+/**
+ * Exact serialized-byte contribution for one additional file. Serializing a
+ * single candidate (plus a constant sentinel for non-first entries) keeps pack
+ * selection linear in total source bytes instead of repeatedly serializing the
+ * whole growing artifact.
+ */
+function serializedFileByteDelta(format, file, hasFiles) {
+    if (!hasFiles)
+        return Buffer.byteLength(serialize(format, [file])) - Buffer.byteLength(serialize(format, []));
+    const sentinel = { path: "", policy: "full", content: "" };
+    return (Buffer.byteLength(serialize(format, [sentinel, file])) -
+        Buffer.byteLength(serialize(format, [sentinel])));
+}
+function gitSections(repo, request) {
+    if (!request)
+        return undefined;
+    const run = (args) => execFileSync("git", args, { cwd: repo, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 });
+    const result = {};
+    if (request.diffScope) {
+        const revision = (value) => {
+            const hasControl = [...value].some((character) => {
+                const code = character.charCodeAt(0);
+                return code < 32 || code === 127;
+            });
+            if (!value || value.startsWith("-") || hasControl)
+                throw new Error(`knodin pack: invalid git revision: ${value}`);
+            return value;
+        };
+        const args = request.diffScope === "unstaged"
+            ? ["diff", "--"]
+            : request.diffScope === "staged"
+                ? ["diff", "--cached", "--"]
+                : request.diffScope === "compare"
+                    ? ["diff", revision(request.from ?? "HEAD~1"), revision(request.to ?? "HEAD"), "--"]
+                    : ["diff", revision(request.from ?? "HEAD"), "--"];
+        result.diff = run(args);
+    }
+    if (request.log !== undefined)
+        result.log = run([
+            "log",
+            `-${Math.max(0, Math.min(100, Math.floor(request.log)))}`,
+            "--oneline",
+        ]);
+    return result;
+}
+function safeOutput(repo, output) {
+    const absolute = path.resolve(repo, output);
+    if (absolute !== repo && !absolute.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: outputPath must stay inside the repository");
+    if (fs.existsSync(absolute)) {
+        const realTarget = fs.realpathSync(absolute);
+        if (realTarget !== repo && !realTarget.startsWith(`${repo}${path.sep}`))
+            throw new Error("knodin pack: outputPath may not follow a symlink outside the repository");
+    }
+    let parent = path.dirname(absolute);
+    while (!fs.existsSync(parent) && parent !== repo)
+        parent = path.dirname(parent);
+    const realParent = fs.realpathSync(parent);
+    if (realParent !== repo && !realParent.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: outputPath may not traverse a symlink outside the repository");
+    return absolute;
+}
+export function exportContext(repoPath, request = {}) {
+    const repo = fs.realpathSync(repoPath);
+    const format = request.format ?? "markdown";
+    if (!["markdown", "json", "xml"].includes(format))
+        throw new Error("knodin pack: format must be markdown, json, or xml");
+    if (request.byteBudget !== undefined &&
+        (!Number.isFinite(request.byteBudget) || request.byteBudget < 256))
+        throw new Error("knodin pack: byteBudget must be at least 256");
+    if (request.tokenBudget !== undefined &&
+        (!Number.isFinite(request.tokenBudget) || request.tokenBudget < 64))
+        throw new Error("knodin pack: tokenBudget must be at least 64");
+    if (request.git?.diffScope !== undefined &&
+        !["unstaged", "staged", "all", "compare"].includes(request.git.diffScope))
+        throw new Error("knodin pack: invalid git diff scope");
+    if (request.git?.log !== undefined &&
+        (!Number.isInteger(request.git.log) || request.git.log < 0 || request.git.log > 100))
+        throw new Error("knodin pack: git log must be an integer from 0 to 100");
+    if (Object.values(request.policies ?? {}).some((policy) => !["full", "summary", "structure-only"].includes(policy)))
+        throw new Error("knodin pack: invalid file policy");
+    const byteLimit = Math.floor(request.byteBudget ?? 65_536);
+    const tokenLimit = Math.floor(request.tokenBudget ?? 16_384);
+    const hardLimit = Math.min(byteLimit, tokenLimit * 4);
+    const include = request.include?.length ? request.include : ["**"];
+    const exclude = [...DEFAULT_EXCLUDES, ...(request.exclude ?? [])];
+    const includePatterns = compilePatterns(include);
+    const excludePatterns = compilePatterns(exclude);
+    const policyRules = request.policies ?? {};
+    const policies = Object.keys(policyRules)
+        .sort()
+        .map((pattern) => ({
+        pattern: globRegex(normalizeRelative(pattern)),
+        policy: policyRules[pattern],
+    }));
+    const omitted = new Set([...(request.alreadyPresent ?? []), ...(request.chatFiles ?? [])].map(normalizeRelative));
+    if (request.outputPath)
+        omitted.add(normalizeRelative(request.outputPath));
+    const candidates = measurePerfPhaseSync("pack_walk", () => walk(repo))
+        .filter((file) => matchesCompiled(file, includePatterns) &&
+        !matchesCompiled(file, excludePatterns) &&
+        !omitted.has(file))
+        .sort();
+    let tree = request.includeTree ? [...candidates] : undefined;
+    let git = gitSections(repo, request.git);
+    const files = [];
+    const measuredSerialize = () => measurePerfPhaseSync("pack_serialize", () => serialize(format, files, tree, git));
+    let artifact = measuredSerialize();
+    if (Buffer.byteLength(artifact) > hardLimit) {
+        git = undefined;
+        artifact = measuredSerialize();
+    }
+    if (Buffer.byteLength(artifact) > hardLimit) {
+        tree = undefined;
+        artifact = measuredSerialize();
+    }
+    let serializedSize = Buffer.byteLength(artifact);
+    for (const file of candidates) {
+        const policy = policyFor(file, policies);
+        let content = fs.readFileSync(path.join(repo, file), "utf8");
+        if (policy === "summary")
+            content = summarize(content, request.lineNumbers);
+        else if (policy === "structure-only")
+            content = structureOnly(content, request.lineNumbers);
+        else if (request.lineNumbers)
+            content = numbered(content);
+        const packed = { path: file, policy, content };
+        const delta = measurePerfPhaseSync("pack_serialize", () => serializedFileByteDelta(format, packed, files.length > 0));
+        if (serializedSize + delta > hardLimit)
+            continue;
+        files.push(packed);
+        serializedSize += delta;
+    }
+    artifact = measuredSerialize();
+    const serializedBytes = Buffer.byteLength(artifact);
+    const outputAbsolute = request.outputPath ? safeOutput(repo, request.outputPath) : undefined;
+    const result = {
+        format,
+        artifact,
+        files: files.map(({ path: filePath, policy }) => ({ path: filePath, policy })),
+        telemetry: {
+            byteLimit,
+            tokenLimit,
+            serializedBytes,
+            responseBytes: 0,
+            estimatedTokens: Math.ceil(serializedBytes / 4),
+            tokenizer: "estimate:deterministic-utf8-bytes-divided-by-4",
+            includedFiles: files.length,
+            candidateFiles: candidates.length,
+            truncated: files.length < candidates.length,
+        },
+        ...(outputAbsolute
+            ? { outputPath: normalizeRelative(path.relative(repo, outputAbsolute)) }
+            : {}),
+    };
+    const updateResponseBytes = () => {
+        for (let index = 0; index < 4; index++) {
+            const actual = Buffer.byteLength(JSON.stringify(result));
+            if (actual === result.telemetry.responseBytes)
+                break;
+            result.telemetry.responseBytes = actual;
+        }
+    };
+    updateResponseBytes();
+    while (result.telemetry.responseBytes > hardLimit && files.length > 0) {
+        files.pop();
+        result.files.pop();
+        result.artifact = measuredSerialize();
+        result.telemetry.serializedBytes = Buffer.byteLength(result.artifact);
+        result.telemetry.estimatedTokens = Math.ceil(result.telemetry.serializedBytes / 4);
+        result.telemetry.includedFiles = files.length;
+        result.telemetry.truncated = true;
+        updateResponseBytes();
+    }
+    if (result.telemetry.responseBytes > hardLimit)
+        throw new Error("knodin pack: budget is too small for the requested format and telemetry");
+    if (outputAbsolute) {
+        fs.mkdirSync(path.dirname(outputAbsolute), { recursive: true });
+        fs.writeFileSync(outputAbsolute, result.artifact);
+    }
+    return result;
+}
+function safeArtifact(repoPath, artifactPath) {
+    const repo = fs.realpathSync(repoPath);
+    const absolute = path.resolve(repo, artifactPath);
+    if (absolute !== repo && !absolute.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: artifactPath must stay inside the repository");
+    const real = fs.realpathSync(absolute);
+    if (real !== repo && !real.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin pack: artifactPath may not follow a symlink outside the repository");
+    const stat = fs.statSync(real);
+    if (!stat.isFile() || stat.size > 16 * 1024 * 1024)
+        throw new Error("knodin pack: artifactPath must be a packed file no larger than 16 MiB");
+    return real;
+}
+const ARTIFACT_CACHE_ENTRY_LIMIT = 2;
+const ARTIFACT_CACHE_FILE_LIMIT = 4 * 1024 * 1024;
+const artifactLineCache = new Map();
+function artifactLines(repoPath, artifactPath) {
+    const real = safeArtifact(repoPath, artifactPath);
+    const stat = fs.statSync(real);
+    const cached = artifactLineCache.get(real);
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+        artifactLineCache.delete(real);
+        artifactLineCache.set(real, cached);
+        return cached.lines;
+    }
+    if (cached)
+        artifactLineCache.delete(real);
+    const lines = fs.readFileSync(real, "utf8").split(/\r?\n/);
+    if (stat.size <= ARTIFACT_CACHE_FILE_LIMIT) {
+        while (artifactLineCache.size >= ARTIFACT_CACHE_ENTRY_LIMIT) {
+            const oldest = artifactLineCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            artifactLineCache.delete(oldest);
+        }
+        artifactLineCache.set(real, { mtimeMs: stat.mtimeMs, size: stat.size, lines });
+    }
+    return lines;
+}
+function truncateUtf8(value, byteLimit) {
+    if (Buffer.byteLength(value) <= byteLimit)
+        return value;
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const midpoint = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(value.slice(0, midpoint)) <= byteLimit)
+            low = midpoint;
+        else
+            high = midpoint - 1;
+    }
+    return value.slice(0, low);
+}
+export function readPackedArtifact(repoPath, artifactPath, startLine = 1, endLine = startLine + 199, byteBudget = 16_384) {
+    if (!Number.isFinite(byteBudget) || !Number.isInteger(byteBudget) || byteBudget < 256)
+        throw new Error("knodin pack read: byteBudget must be an integer >= 256");
+    if (!Number.isInteger(startLine) ||
+        !Number.isInteger(endLine) ||
+        startLine < 1 ||
+        endLine < startLine ||
+        endLine - startLine > 999)
+        throw new Error("knodin pack read: invalid or unbounded line range");
+    const lines = measurePerfPhaseSync("artifact_read", () => artifactLines(repoPath, artifactPath).slice(startLine - 1, endLine));
+    let content = lines.join("\n");
+    const limit = Math.max(256, Math.min(65_536, Math.floor(byteBudget)));
+    content = truncateUtf8(content, limit);
+    return {
+        artifactPath: normalizeRelative(artifactPath),
+        startLine,
+        endLine: startLine + content.split(/\r?\n/).length - 1,
+        content,
+        truncated: lines.join("\n") !== content,
+    };
+}
+export function grepPackedArtifact(repoPath, artifactPath, pattern, flags = "", limit = 100) {
+    if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1 || limit > 1000)
+        throw new Error("knodin pack grep: limit must be an integer from 1 to 1000");
+    if (pattern.length === 0 || pattern.length > 1000 || !/^[gimsuy]*$/.test(flags))
+        throw new Error("knodin pack grep: invalid regex or flags");
+    let regex;
+    try {
+        const safeFlags = flags.replace("g", "").includes("u")
+            ? flags.replace("g", "")
+            : `${flags.replace("g", "")}u`;
+        regex = new RE2(pattern, safeFlags);
+    }
+    catch {
+        throw new Error("knodin pack grep: invalid or unsupported linear-time regex");
+    }
+    const matches = [];
+    measurePerfPhaseSync("artifact_grep", () => {
+        for (const [index, text] of artifactLines(repoPath, artifactPath).entries()) {
+            regex.lastIndex = 0;
+            if (regex.test(text))
+                matches.push({ line: index + 1, text });
+            if (matches.length >= Math.max(1, Math.min(1000, Math.floor(limit))))
+                break;
+        }
+    });
+    return {
+        artifactPath: normalizeRelative(artifactPath),
+        pattern,
+        flags,
+        matches,
+        truncated: matches.length >= limit,
+    };
+}

package/dist/src/context.js

@@ -0,0 +1,102 @@
+/**
+ * Logic for the `knodin context` operation — the "call this FIRST" ultra-
+ * compact orientation. Lives in its own neutral module, mirroring
+ * `pr-triage.ts`'s role for the `prs` operation: `bin/cli.ts` and
+ * `src/tools/knodin-tools.ts` both import from here independently, rather
+ * than the CLI reaching into the MCP-gateway module the way it previously did
+ * (code review finding — R23-R28 reuse/altitude pass).
+ */
+import { measurePerfPhase } from "./engine/perf.js";
+/** Keyword heuristic mapping a free-text `task` to a suggested next knodin
+ * operation for the `context` op. This is explicitly a hint, not a claim of
+ * understanding intent — a wrong guess must never stop the caller from reaching
+ * for any operation directly (R26). Order matters: review-shaped tasks win over
+ * map-shaped ones, and a bare single-symbol token routes to `explain`. */
+export function suggestNextOperation(task) {
+    const t = task.toLowerCase();
+    if (/\b(bug|review|diff|pr|pull request|regression|risk|approve|merge)\b/.test(t)) {
+        return "review";
+    }
+    if (/\b(batch outline|file outline|outline files?|project overview|directory overview)\b/.test(t)) {
+        return "query";
+    }
+    if (/\b(how does|how do|architecture|architectural|structure|structured|design|subsystem|boundaries|overview)\b/.test(t)) {
+        return "map";
+    }
+    // A bare identifier-shaped token (a single symbol name) → explain it directly.
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(task.trim())) {
+        return "explain";
+    }
+    // Otherwise no exact symbol is known → fuzzy search to find a starting point.
+    return "search";
+}
+function suggestedStructuralPattern(task) {
+    const normalized = task.toLowerCase();
+    if (/\bbatch outline\b/.test(normalized))
+        return "batch_outline";
+    if (/\b(project|directory) overview\b/.test(normalized))
+        return "project_overview";
+    if (/\bfile outline\b|\boutline (?:the )?file\b/.test(normalized))
+        return "file_summary";
+    return undefined;
+}
+/**
+ * R26 `context` operation — the "call this FIRST" ultra-compact orientation.
+ * Composes EXISTING public engine methods only (`map`, `query stats`,
+ * `query flows`, `review`) so it never touches `src/engine/index.ts` and stays
+ * parallel-safe against the query-dispatch work landing there. Takes an
+ * `engine: KnodinEngine` parameter rather than constructing its own, so the
+ * `knodin-tools.ts` module-level `createEngine()` singleton is never
+ * duplicated or side-effected by this module's existence.
+ */
+export async function buildKnodinContext(eng, task, repo, base, changedFiles) {
+    return measurePerfPhase("context_composition", async () => {
+        // Establish one full graph snapshot first: stats requires that same standard
+        // map, so asking for a separate minimal map would run community analytics
+        // twice. Once initialized, the remaining read-only facets can safely share
+        // the generation and freshness lease.
+        const CONTEXT_TOP = 5;
+        const mapResult = await eng.map(repo, "standard");
+        const shouldReview = changedFiles === undefined || changedFiles.length > 0;
+        const [statsResult, flowsResult, review] = await Promise.all([
+            eng.query("stats", "", repo),
+            eng.query("flows", "", repo, undefined, CONTEXT_TOP),
+            shouldReview ? eng.review(base ?? "HEAD~1", repo, "minimal") : Promise.resolve(undefined),
+        ]);
+        // Risk score: eng.review() always re-derives the diff from `git diff <base>`;
+        // it has no seam for an explicit file list, so `changedFiles`, when supplied,
+        // is only a caller hint — an explicit empty array means "no changes, skip the
+        // diff". When there IS a diff but it touches no indexed symbols, review
+        // returns changedSymbolCount 0 and a meaningless riskScore 0; omit the field
+        // in that case rather than report a misleading 0 (R26 acceptance criterion).
+        let riskScore;
+        if (review && review.changedSymbolCount > 0)
+            riskScore = review.riskScore;
+        // Truncate aggressively — this is a ~100-300 token orientation, not a dump of
+        // map()'s full payload. Sort defensively so "top" holds even if an engine
+        // method's ordering changes; flows already arrive most-critical first (capped
+        // at CONTEXT_TOP via the query limit above).
+        return {
+            repoPath: repo,
+            task,
+            stats: statsResult.totals,
+            communities: [...mapResult.communities]
+                .sort((a, b) => b.size - a.size)
+                .slice(0, CONTEXT_TOP)
+                .map((c) => ({ name: c.name, size: c.size })),
+            hubs: [...mapResult.hubs]
+                .sort((a, b) => b.degree - a.degree)
+                .slice(0, CONTEXT_TOP)
+                .map((h) => ({ symbol: h.symbol, degree: h.degree })),
+            flows: flowsResult.results
+                .slice(0, CONTEXT_TOP)
+                .map((f) => ({ symbol: f.symbol, criticality: f.criticality })),
+            ...(riskScore !== undefined ? { riskScore } : {}),
+            suggestedOperation: suggestNextOperation(task),
+            ...(suggestedStructuralPattern(task)
+                ? { suggestedQueryPattern: suggestedStructuralPattern(task) }
+                : {}),
+            suggestionNote: "Heuristic from keywords in `task`; a hint only — any operation can be called directly regardless.",
+        };
+    });
+}

package/dist/src/docs-sections.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const DOCS_SECTIONS = {
+    quickstart: `# Quickstart Guide
+
+knodin — source-evidenced local code intelligence with known bounds. It builds a semantic and syntactic knowledge graph of your repository and exposes five primary operations through its MCP tool gateway or CLI:
+
+1. **context**: Orient on a repository. Returns high-level statistics, key subsystems/hubs/flows, a heuristic next-operation recommendation, and a diff-based risk score if changes are detected.
+2. **explain**: Understand a specific symbol (function, class, or file). Returns edit-ready source code, inbound/outbound call paths, and blast radius (transitive callers).
+3. **review**: Analyze local modifications. Displays risk-scored changes, affected execution flows, and missing test coverage before you commit or create a PR.
+4. **map**: Visualize subsystem boundaries. Partitions the code into cohesive modular communities using Louvain community detection.
+5. **search**: Fuzzy semantic and keyword lookup to find symbols when you do not know their exact name.
+
+### Command Usage (CLI)
+\`\`\`bash
+knodin context "explore auth"
+knodin explain login
+knodin map
+\`\`\``,
+    "query-patterns": `# Structured Query Patterns
+
+The \`query\` operation lets you ask precise, structured questions about your code using a variety of built-in graph patterns:
+
+- **callers_of <target>**: Who invokes this symbol (transitive/direct).
+- **callees_of <target>**: What other symbols does this symbol invoke.
+- **tests_for <target>**: Find test files that cover this symbol.
+- **file_summary <target>**: Lists all symbols defined in a file.
+- **shortest_path <from> <to>**: Find the call-graph chain connecting two symbols.
+- **impact <symbol>**: Directional, depth-bounded symbol reach with stable selectors, relation/confidence/test filters, edge evidence, and heuristic summaries. Use \`impactMode: "file"\` explicitly for a distinctly labeled changed-file blast radius.
+- **dead_code**: Surface exported or unexported symbols with zero references.
+- **large_functions / large_files**: Spot complex "god" functions and files exceeding size thresholds.
+- **traverse <symbol>**: Perform a bounded BFS neighborhood walk. Use \`direction\` (\`upstream|downstream|both\`), \`relationKinds\`, and optional \`includeDataFlow\`; every discovered hop carries its exact kind, direction, confidence, provenance, source line, and files. Call arguments are labeled heuristic source evidence, never runtime proof.
+- **knowledge_gaps**: Report repo-health weaknesses like thin communities (<3 symbols) and untested hubs/bridges.
+- **surprising_connections**: Score and rank coupling that crosses community, language, or test boundaries.
+- **suggested_questions**: prioritizes human-readable review prompts based on untested hotspots and high-surprise edges.
+- **architecture_overview**: Formats community cohesion and coupling plus independently selectable \`architectureFacets\`: packages, layers, boundaries, hotspots, entryPoints, and languages. \`path\` scopes every facet consistently.`,
+    federation: `# Cross-Repository Composition
+
+Federation is knodin's internal query-composition mechanism, not the primary
+user-facing model. Use \`knodin repos\` for operational checkout management and
+\`knodin system\` with commit-ready \`reckon.yaml\` stable identities for
+cooperating components. Sibling directory placement and shared search matches
+never establish system membership.
+
+Legacy \`.reckon/federation.json\` remains a compatibility input and is not
+silently discarded. Migrate it to \`reckon.yaml\` plus personal XDG checkout
+paths. The \`federated_repos\` query remains available for inspecting the
+engine's currently composed repository paths; it does not prove those
+repositories form one system.`,
+    "rename-safety": `# Rename Safety and Refactoring
+
+knodin provides an AST-backed, type-safe refactoring pipeline for renaming symbols.
+
+### Two-Step Pipeline
+1. **Dry-Run (default)**: Returns every edit site (definitions, references, imports) and generates a unified diff. Refuses to make changes if there's an ambiguity or conflict.
+2. **Apply (\`apply: true\` or \`--apply\`)**: Atomically writes line-scoped word-boundary edits to disk and triggers an automatic reindexing of touched files.
+
+### Safety Guards
+The engine refuses to write to disk and rolls back any changes if:
+- **Ambiguity**: The old symbol name resolves to more than one definition file.
+- **Collision**: The new name already exists as a symbol in any of the edit-site files.
+- **Out of Scope**: The edit targets files outside the repository.
+- **Type Errors**: If verification is enabled (default), it verifies the workspace compiles successfully using \`tsc\` (or equivalent) after applying the edit, and automatically rolls back if compilation fails.`,
+    "language-support": `# Language and Metadata Support
+
+knodin is multi-language, not language-universal.
+
+### Native syntax
+TypeScript (\`.ts/.tsx/.mts/.cts\`), JavaScript (\`.js/.jsx/.mjs/.cjs\`), Python, Java, C#, Salesforce Apex, SQL/PLSQL, Prisma, and XML-backed formats.
+
+### Domain-specific structure
+Salesforce LWC, Aura, Visualforce, Experience Cloud, and selected Salesforce DX metadata/automations; Terraform/HCL; Dockerfiles; dbt manifests; and Workday Studio XML.
+
+### Imported graph
+LSIF can import symbols and relationships produced by a compatible language server. This is not native parsing.
+
+Go, Rust, PHP, Ruby, Kotlin, Swift, Perl, PowerShell, Bash, and MuleSoft/RAML are known native-parser gaps. Coverage differs by language, and static dead-code candidates must be corroborated when runtime or platform configuration can invoke code dynamically. Salesforce candidates should be checked against deployed-org and platform dependency data before deletion.`,
+    troubleshooting: `# Troubleshooting and Recovery
+
+### Index health and surgical repair
+
+Run \`knodin status\` (or MCP \`operation: "status"\`) to inspect the local schema/model/version, file and symbol coverage, orphaned or missing records, and the last successful reconciliation. Its repair steps are actionable. Run \`knodin repair\` (or MCP \`operation: "repair"\`) to rebuild only missing/damaged rows and verify health; healthy indexed files are not deleted or rebuilt.
+
+The MCP \`telemetry\` operation reads process-local metadata-only measurements: actual response bytes and \`gpt-tokenizer@3.4.0:o200k_base\` tokens, executed baselines where available, negative or positive savings, latency, RSS, schema cost, truncation, and detail mode. It never contains source or file paths and does not change existing operation response shapes. Telemetry is not persisted by default. Set MCP \`persistTelemetry: true\` to append metadata-only JSONL to the repo-root \`.reckon-telemetry.jsonl\`; knodin never sends it over the network. Use \`telemetryAction: "report"\` or \`knodin telemetry report\` for a static repository-local HTML report.
+
+Common issues and how to resolve them when using knodin:
+
+### Corrupt Embedding Row
+If you see warnings like \`Skipping corrupt embedding... dimension mismatch\`, your index database contains malformed embeddings.
+- **Fix**: Force a clean re-index of the repository to rebuild the vector store.
+\`\`\`bash
+# Prefer surgical local repair; it preserves healthy state
+knodin repair
+\`\`\`
+
+### Missing 'gh' CLI Dependency
+The \`prs\` triage operation requires the official GitHub CLI (\`gh\`) to be installed, in your PATH, and authenticated.
+- **Fix**: Run \`gh auth login\` to authenticate locally.
+
+### Legacy federation configuration
+If legacy federation configuration fails, validate
+\`.reckon/federation.json\`, then migrate stable identities to \`reckon.yaml\`
+and local paths to XDG configuration. Do not infer membership from siblings.`,
+};
+const DOC_TOPIC_FILES = {
+    installation: "INSTALLATION.md",
+    mcp: "MCP.md",
+    repositories: "REPOSITORIES-AND-WORKTREES.md",
+    systems: "SYSTEMS-AND-RELATIONSHIPS.md",
+    provenance: "INDEXING-POLICY-AND-PROVENANCE.md",
+    "dead-code": "DEAD-CODE-AND-IMPACT.md",
+    doctor: "DOCTOR-AND-UPDATES.md",
+    compression: "COMMAND-OUTPUT-COMPRESSION.md",
+};
+function packageRoot() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (!fs.existsSync(path.join(current, "package.json")) &&
+        current !== path.parse(current).root) {
+        current = path.dirname(current);
+    }
+    return current;
+}
+export function listDocTopics() {
+    return [...new Set([...Object.keys(DOCS_SECTIONS), ...Object.keys(DOC_TOPIC_FILES)])].sort((left, right) => left.localeCompare(right));
+}
+/** Read canonical long-form guides directly so CLI and MCP cannot drift from Markdown. */
+export function getDocSection(topic) {
+    const file = DOC_TOPIC_FILES[topic];
+    if (file) {
+        try {
+            return fs.readFileSync(path.join(packageRoot(), "docs", file), "utf-8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    return DOCS_SECTIONS[topic];
+}