knodin 0.7.4 → 0.7.6

package/dist/src/diagnostics.js

@@ -1,449 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import zlib from "node:zlib";
-const CONFIG_PATH = ".knodin/diagnostics/config.json";
-const JOURNAL_PATH = ".knodin/diagnostics/events.jsonl";
-const JOURNAL_LOCK_PATH = ".knodin/diagnostics/events.lock";
-const DEFAULT_RETENTION_DAYS = 14;
-const MAX_RETENTION_DAYS = 365;
-const MAX_RECORDS = 500;
-const MAX_LOG_BYTES = 64 * 1024;
-const MAX_BUNDLE_BYTES = 20 * 1024 * 1024;
-const MAX_JOURNAL_BYTES = 2 * 1024 * 1024;
-const OPERATIONS = new Set([
-    "init",
-    "configure",
-    "index",
-    "doctor",
-    "status",
-    "wait",
-    "repair",
-    "serve",
-    "context",
-    "explain",
-    "review",
-    "map",
-    "search",
-    "query",
-    "rename",
-    "wiki",
-    "visualize",
-    "pack",
-    "compress",
-    "prs",
-    "worktrees",
-    "telemetry",
-    "diagnostics",
-    "system",
-    "repos",
-    "repositories",
-    "update",
-    "docs",
-    "unknown",
-]);
-function containedPath(repoPath, requested, purpose) {
-    const repo = fs.realpathSync(repoPath);
-    const target = path.resolve(repo, requested);
-    if (target !== repo && !target.startsWith(`${repo}${path.sep}`))
-        throw new Error(`knodin diagnostics ${purpose}: path must stay inside the repository`);
-    let cursor = repo;
-    for (const segment of path.relative(repo, target).split(path.sep).filter(Boolean)) {
-        cursor = path.join(cursor, segment);
-        try {
-            if (fs.lstatSync(cursor).isSymbolicLink())
-                throw new Error(`knodin diagnostics ${purpose}: refusing symlinked path`);
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                break;
-            throw error;
-        }
-    }
-    return { repo, target };
-}
-function atomicPrivateWrite(target, data) {
-    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
-    const temporary = `${target}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString("hex")}.tmp`;
-    fs.writeFileSync(temporary, data, { mode: 0o600, flag: "wx" });
-    fs.renameSync(temporary, target);
-}
-function withJournalLock(repo, run) {
-    const { target: lock } = containedPath(repo, JOURNAL_LOCK_PATH, "record");
-    fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
-    for (let attempt = 0;; attempt++) {
-        try {
-            fs.mkdirSync(lock, { mode: 0o700 });
-            break;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            try {
-                if (Date.now() - fs.statSync(lock).mtimeMs > 30_000) {
-                    fs.rmdirSync(lock);
-                    continue;
-                }
-            }
-            catch (inspectionError) {
-                if (inspectionError.code === "ENOENT")
-                    continue;
-                throw inspectionError;
-            }
-            if (attempt >= 100)
-                throw new Error("knodin diagnostics record: journal is busy");
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
-        }
-    }
-    try {
-        return run();
-    }
-    finally {
-        try {
-            fs.rmdirSync(lock);
-        }
-        catch {
-            // Recording is best-effort; stale-lock recovery handles interrupted cleanup.
-        }
-    }
-}
-function validRetention(days) {
-    if (!Number.isInteger(days) || days < 1 || days > MAX_RETENTION_DAYS)
-        throw new Error(`knodin diagnostics: retention days must be an integer from 1 to ${MAX_RETENTION_DAYS}`);
-    return days;
-}
-function readConfig(repoPath) {
-    const { target } = containedPath(repoPath, CONFIG_PATH, "status");
-    if (!fs.existsSync(target))
-        return null;
-    try {
-        const value = JSON.parse(fs.readFileSync(target, "utf8"));
-        if (value.schemaVersion !== 1 || value.enabled !== true)
-            return null;
-        validRetention(value.retentionDays);
-        if (!Number.isInteger(value.generation) || value.generation < 1)
-            value.generation = 1;
-        if (typeof value.sessionId !== "string" || !/^[a-f0-9]{32}$/.test(value.sessionId))
-            value.sessionId = crypto
-                .createHash("sha256")
-                .update(value.enabledAt)
-                .digest("hex")
-                .slice(0, 32);
-        return value;
-    }
-    catch {
-        return null;
-    }
-}
-function safeLabel(value, fallback) {
-    return value && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,63}$/.test(value) ? value : fallback;
-}
-function errorCode(error) {
-    const code = error?.code;
-    return typeof code === "string" &&
-        /^(?:E[A-Z0-9]+|ERR_[A-Z0-9_]+|SQLITE_[A-Z0-9_]+|KNODIN_[A-Z0-9_]+)$/.test(code)
-        ? code
-        : null;
-}
-function scrubText(raw, repo) {
-    let value = raw;
-    let redactions = 0;
-    const replace = (pattern, replacement) => {
-        value = value.replace(pattern, () => {
-            redactions++;
-            return replacement;
-        });
-    };
-    for (const exact of [repo, os.homedir()].filter(Boolean).sort((a, b) => b.length - a.length))
-        replace(new RegExp(exact.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), "<path>");
-    replace(/\b(?:ghp|github_pat|sk|xox[baprs])-[-A-Za-z0-9_]{10,}\b/g, "<secret>");
-    replace(/\b(?:password|passwd|token|secret|api[_-]?key|authorization)\s*[=:]\s*[^\s,;]+/gi, "$1=<secret>");
-    replace(/\b[A-Z]:\\(?:[^\s<>:"|?*]+\\)*[^\s<>:"|?*]*/g, "<path>");
-    replace(/(?:^|[\s('"`])\/(?:[^\s)'"`]+\/)*[^\s)'"`]*/g, "<path>");
-    replace(/\b(?:[A-Za-z0-9_.-]+\/)+(?:[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,12})\b/g, "<path>");
-    replace(/\b[A-Za-z0-9_.+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, "<email>");
-    return { value: value.slice(0, 2_000), redactions };
-}
-function sanitizeStack(error, repo) {
-    return (error.stack ?? "")
-        .split(/\r?\n/)
-        .slice(1, 9)
-        .map((line) => `at ${line.includes(repo) ? "<repository>" : "<runtime>"}`);
-}
-function sanitizeUnknown(value, repo, state) {
-    if (typeof value === "string") {
-        const scrubbed = scrubText(value, repo);
-        state.redactions += scrubbed.redactions;
-        return scrubbed.value;
-    }
-    if (Array.isArray(value))
-        return value.slice(0, 500).map((item) => sanitizeUnknown(item, repo, state));
-    if (value && typeof value === "object") {
-        const output = {};
-        for (const [key, item] of Object.entries(value).slice(0, 500)) {
-            const safeKey = /[\\/]|\.[A-Za-z0-9]{1,12}$/.test(key) ? "<path-key>" : key;
-            if (safeKey !== key)
-                state.redactions++;
-            if (/^(?:source|content|query|command|arguments?|env(?:ironment)?|remote)$/i.test(key)) {
-                output[safeKey] = "<omitted>";
-                state.redactions++;
-            }
-            else
-                output[safeKey] = sanitizeUnknown(item, repo, state);
-        }
-        return output;
-    }
-    return value;
-}
-function readEvents(repoPath, retentionDays, since) {
-    const { target } = containedPath(repoPath, JOURNAL_PATH, "read");
-    if (!fs.existsSync(target))
-        return [];
-    if (fs.statSync(target).size > MAX_JOURNAL_BYTES)
-        throw new Error("knodin diagnostics read: journal exceeds the 2 MiB safety limit");
-    const cutoff = Math.max(Date.now() - validRetention(retentionDays) * 86_400_000, since?.getTime() ?? Number.NEGATIVE_INFINITY);
-    return fs
-        .readFileSync(target, "utf8")
-        .split(/\r?\n/)
-        .filter(Boolean)
-        .flatMap((line) => {
-        try {
-            const record = JSON.parse(line);
-            return record.schemaVersion === 1 && Date.parse(record.at) >= cutoff ? [record] : [];
-        }
-        catch {
-            return [];
-        }
-    })
-        .slice(-MAX_RECORDS);
-}
-export function enableDiagnostics(repoPath, retentionDays = DEFAULT_RETENTION_DAYS) {
-    const { repo, target } = containedPath(repoPath, CONFIG_PATH, "enable");
-    withJournalLock(repo, () => {
-        const previous = readConfig(repo);
-        const config = {
-            schemaVersion: 1,
-            enabled: true,
-            retentionDays: validRetention(retentionDays),
-            enabledAt: new Date().toISOString(),
-            generation: (previous?.generation ?? 0) + 1,
-            sessionId: crypto.randomBytes(16).toString("hex"),
-        };
-        atomicPrivateWrite(target, `${JSON.stringify(config, null, 2)}\n`);
-    });
-    return { ...diagnosticsStatus(repo), message: "Local diagnostics enabled; nothing is uploaded." };
-}
-export function disableDiagnostics(repoPath) {
-    const { repo, target } = containedPath(repoPath, CONFIG_PATH, "disable");
-    withJournalLock(repo, () => {
-        if (fs.existsSync(target))
-            fs.unlinkSync(target);
-    });
-    return {
-        ...diagnosticsStatus(repo),
-        message: "Local diagnostics disabled; retained events were not deleted.",
-    };
-}
-export function diagnosticsStatus(repoPath) {
-    const config = readConfig(repoPath);
-    const retentionDays = config?.retentionDays ?? DEFAULT_RETENTION_DAYS;
-    let events = [];
-    let journal = {
-        status: "healthy",
-        issue: null,
-    };
-    try {
-        events = readEvents(repoPath, retentionDays);
-    }
-    catch (error) {
-        journal = {
-            status: "unavailable",
-            issue: error instanceof Error ? error.message : "diagnostic journal is unavailable",
-        };
-    }
-    return {
-        schemaVersion: 1,
-        enabled: config !== null,
-        localOnly: true,
-        uploaded: false,
-        retentionDays,
-        records: events.length,
-        oldestAt: events[0]?.at ?? null,
-        newestAt: events.at(-1)?.at ?? null,
-        journal,
-    };
-}
-export function recordDiagnosticFailure(repoPath, input) {
-    try {
-        const repo = fs.realpathSync(repoPath);
-        const observed = readConfig(repo);
-        if (!observed)
-            return { recorded: false, reason: "disabled" };
-        return withJournalLock(repo, () => {
-            const config = readConfig(repo);
-            if (!config)
-                return { recorded: false, reason: "disabled" };
-            if (config.sessionId !== observed.sessionId || config.generation !== observed.generation)
-                return { recorded: false, reason: "state-changed" };
-            const error = input.error instanceof Error ? input.error : new Error(String(input.error));
-            const message = scrubText(error.message, repo).value;
-            const event = {
-                schemaVersion: 1,
-                at: new Date().toISOString(),
-                correlationId: crypto.randomBytes(8).toString("hex"),
-                surface: input.surface,
-                operation: OPERATIONS.has(input.operation) ? input.operation : "unknown",
-                phase: safeLabel(input.phase, "operation"),
-                error: {
-                    name: safeLabel(error.name, "Error"),
-                    code: errorCode(input.error),
-                    messageFingerprint: crypto
-                        .createHash("sha256")
-                        .update(message)
-                        .digest("hex")
-                        .slice(0, 16),
-                    stack: sanitizeStack(error, repo),
-                },
-            };
-            const events = [...readEvents(repo, config.retentionDays), event].slice(-MAX_RECORDS);
-            const { target } = containedPath(repo, JOURNAL_PATH, "record");
-            atomicPrivateWrite(target, `${events.map((record) => JSON.stringify(record)).join("\n")}\n`);
-            return { recorded: true, correlationId: event.correlationId };
-        });
-    }
-    catch {
-        return { recorded: false, reason: "unavailable" };
-    }
-}
-export function clearDiagnostics(repoPath) {
-    const { repo, target } = containedPath(repoPath, JOURNAL_PATH, "clear");
-    return withJournalLock(repo, () => {
-        if (!fs.existsSync(target))
-            return { removed: false, records: 0, bytes: 0 };
-        let records = null;
-        try {
-            records = readEvents(repo, MAX_RETENTION_DAYS).length;
-        }
-        catch {
-            // Deletion must remain the recovery path for an unreadable or oversized journal.
-        }
-        const bytes = fs.statSync(target).size;
-        fs.unlinkSync(target);
-        const config = readConfig(repo);
-        if (config) {
-            atomicPrivateWrite(containedPath(repo, CONFIG_PATH, "clear").target, `${JSON.stringify({ ...config, generation: config.generation + 1 }, null, 2)}\n`);
-        }
-        return { removed: true, records, bytes };
-    });
-}
-function defaultBundlePath() {
-    return `.knodin/diagnostics/knodin-diagnostics-${new Date().toISOString().replace(/[:.]/g, "-")}.json.gz`;
-}
-function lifecycleLog(repo, state) {
-    const target = path.join(repo, ".knodin", "indexer.log");
-    if (!fs.existsSync(target) || fs.lstatSync(target).isSymbolicLink())
-        return [];
-    const size = fs.statSync(target).size;
-    const descriptor = fs.openSync(target, "r");
-    try {
-        const length = Math.min(size, MAX_LOG_BYTES);
-        const buffer = Buffer.alloc(length);
-        fs.readSync(descriptor, buffer, 0, length, Math.max(0, size - length));
-        return buffer
-            .toString("utf8")
-            .split(/\r?\n/)
-            .filter(Boolean)
-            .slice(-200)
-            .map((line) => sanitizeUnknown(line, repo, state));
-    }
-    finally {
-        fs.closeSync(descriptor);
-    }
-}
-export function collectDiagnostics(repoPath, options = {}) {
-    const { repo, target } = containedPath(repoPath, options.outputPath ?? defaultBundlePath(), "collect");
-    if (fs.existsSync(target))
-        throw new Error("knodin diagnostics collect: refusing to overwrite an existing bundle");
-    const sinceHours = options.sinceHours ?? 24;
-    if (!Number.isFinite(sinceHours) || sinceHours <= 0 || sinceHours > 24 * 365)
-        throw new Error("knodin diagnostics collect: --since must be from 1h through 8760h");
-    const state = { redactions: 0 };
-    const status = diagnosticsStatus(repo);
-    const bundle = {
-        manifest: {
-            schemaVersion: 1,
-            generatedAt: new Date().toISOString(),
-            privacy: "redacted-local-only",
-            localOnly: true,
-            uploaded: false,
-            redactions: 0,
-            omissions: [
-                "source",
-                "queries-and-arguments",
-                "environment-values",
-                "git-remotes-diffs-and-messages",
-                "raw-paths",
-            ],
-        },
-        runtime: {
-            ...(options.knodinVersion ? { knodinVersion: options.knodinVersion } : {}),
-            node: process.version,
-            platform: process.platform,
-            arch: process.arch,
-        },
-        diagnostics: status,
-        diagnosticEvents: readEvents(repo, status.retentionDays, new Date(Date.now() - sinceHours * 3_600_000)),
-        telemetry: sanitizeUnknown(options.telemetry ?? [], repo, state),
-        doctor: sanitizeUnknown(options.doctor ?? null, repo, state),
-        graph: sanitizeUnknown(options.graph ?? null, repo, state),
-        lifecycleLog: lifecycleLog(repo, state),
-    };
-    bundle.manifest.redactions = state.redactions;
-    atomicPrivateWrite(target, zlib.gzipSync(`${JSON.stringify(bundle, null, 2)}\n`, { level: 9 }));
-    return {
-        schemaVersion: 1,
-        outputPath: path.relative(repo, target),
-        format: "gzip-json",
-        localOnly: true,
-        uploaded: false,
-        bytes: fs.statSync(target).size,
-        records: bundle.diagnosticEvents.length,
-        redactions: bundle.manifest.redactions,
-        message: "Bundle created locally. Run `knodin diagnostics inspect <bundle>` before sharing it.",
-    };
-}
-export function inspectDiagnosticsBundle(repoPath, bundlePath) {
-    const { target } = containedPath(repoPath, bundlePath, "inspect");
-    if (!fs.existsSync(target))
-        throw new Error("knodin diagnostics inspect: bundle does not exist");
-    if (fs.statSync(target).size > 10 * 1024 * 1024)
-        throw new Error("knodin diagnostics inspect: bundle exceeds the 10 MiB safety limit");
-    let parsed;
-    try {
-        parsed = JSON.parse(zlib
-            .gunzipSync(fs.readFileSync(target), { maxOutputLength: MAX_BUNDLE_BYTES })
-            .toString("utf8"));
-    }
-    catch {
-        throw new Error("knodin diagnostics inspect: invalid gzip JSON bundle");
-    }
-    if (parsed.manifest?.schemaVersion !== 1 || parsed.manifest.privacy !== "redacted-local-only")
-        throw new Error("knodin diagnostics inspect: unsupported or unsafe bundle manifest");
-    if (!Array.isArray(parsed.diagnosticEvents) ||
-        !Array.isArray(parsed.telemetry) ||
-        !Array.isArray(parsed.lifecycleLog))
-        throw new Error("knodin diagnostics inspect: malformed bundle sections");
-    return {
-        manifest: parsed.manifest,
-        runtime: parsed.runtime,
-        diagnostics: parsed.diagnostics,
-        sections: ["diagnosticEvents", "telemetry", "doctor", "graph", "lifecycleLog"],
-        counts: {
-            diagnosticEvents: parsed.diagnosticEvents.length,
-            telemetry: parsed.telemetry.length,
-            lifecycleLogLines: parsed.lifecycleLog.length,
-        },
-        bundle: parsed,
-    };
-}

package/dist/src/docs-sections.js

@@ -1,141 +0,0 @@
-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 \`knodin.yaml\` stable identities for
-cooperating components. Sibling directory placement and shared search matches
-never establish system membership.
-
-Legacy \`.knodin/federation.json\` remains a compatibility input and is not
-silently discarded. Migrate it to \`knodin.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 \`.knodin-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
-\`.knodin/federation.json\`, then migrate stable identities to \`knodin.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];
-}