@northtek/overstory 0.1.0

package/dist/fix/scan.js

@@ -0,0 +1,197 @@
+const CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|rs|go|java|rb|c|cc|cpp|h|hpp|cs|swift|kt)$/iu;
+const TEST_PATH = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[jt]sx?$|_test\.(py|go)$|test_[^/]*\.py$/iu;
+/** True when the match position on this line sits inside a string literal (odd number of
+ * quote characters before it) — kills the scanner-reads-its-own-example false positives. */
+const insideString = (line, index) => {
+    const prefix = line.slice(0, index);
+    for (const q of ["'", '"', '`']) {
+        if ((prefix.split(q).length - 1) % 2 === 1)
+            return true;
+    }
+    return false;
+};
+const receipt = (file, lines, line, span = 0) => ({
+    file,
+    startLine: line,
+    endLine: Math.min(line + span, lines.length),
+    text: lines.slice(line - 1, Math.min(line + span, lines.length)).join('\n'),
+});
+/** Deterministic issue scanner — no LLM anywhere. Every finding carries receipts (the
+ * exact lines), so the generated prompts are grounded, not vibes. Caps keep output usable. */
+export const scanFindings = (corpus, tree, verification) => {
+    const findings = [];
+    const perKindCap = 8;
+    const count = (kind) => findings.filter((f) => f.kind === kind).length;
+    const files = [...corpus.files.entries()];
+    const codeFiles = files.filter(([f]) => CODE_EXT.test(f) && !TEST_PATH.test(f));
+    // 1. TODO / FIXME / HACK comments — each one is a spec the author already wrote.
+    for (const [file, { lines }] of files) {
+        if (count('todo-comment') >= perKindCap)
+            break;
+        for (let i = 0; i < lines.length && count('todo-comment') < perKindCap; i++) {
+            const m = /(?:\/\/|#|\/\*|<!--)\s*(TODO|FIXME|HACK|XXX)\b[:\s-]*(.*)/u.exec(lines[i]);
+            if (m && !insideString(lines[i], m.index)) {
+                findings.push({
+                    kind: 'todo-comment',
+                    severity: 2,
+                    title: `${m[1]} in ${file}:${i + 1}`,
+                    detail: m[2].trim().replace(/\*\/\s*$|-->\s*$/u, '').trim() || 'unspecified',
+                    receipts: [receipt(file, lines, Math.max(1, i - 1), 4)],
+                });
+            }
+        }
+    }
+    // 2. Stale claims that live in DOC leaves — the doc now lies about the code.
+    for (const node of Object.values(tree.nodes)) {
+        if (node.kind !== 'leaf' || !/\.(md|mdx|markdown|rst|txt)$/iu.test(node.path))
+            continue;
+        for (const claim of node.claims) {
+            if (count('stale-doc-claim') >= perKindCap)
+                break;
+            const verdict = verification.verdicts.get(claim.id);
+            if (verdict === 'STALE' || verdict === 'OUT_OF_CORPUS') {
+                const spans = claim.citations.filter((c) => c.kind === 'span');
+                findings.push({
+                    kind: 'stale-doc-claim',
+                    severity: 1,
+                    title: `Documentation drifted: ${node.path}`,
+                    detail: `The claim "${claim.text.slice(0, 140)}" no longer verifies (${verdict}).`,
+                    receipts: spans.map((s) => ({ file: s.span.file, startLine: s.span.startLine, endLine: s.span.endLine, text: s.span.text.slice(0, 600) })),
+                });
+            }
+        }
+    }
+    // 3. Oversized files.
+    for (const [file, { lines }] of codeFiles) {
+        if (count('oversized-file') >= 5)
+            break;
+        if (lines.length > 500) {
+            findings.push({
+                kind: 'oversized-file',
+                severity: 3,
+                title: `${file} is ${lines.length} lines`,
+                detail: 'Large files hide structure and resist review; split along its natural seams.',
+                receipts: [receipt(file, lines, 1, 0)],
+            });
+        }
+    }
+    // 4. Empty catch blocks — swallowed errors.
+    for (const [file, { lines }] of codeFiles) {
+        if (count('empty-catch') >= perKindCap)
+            break;
+        const joined = lines.join('\n');
+        const re = /catch\s*(?:\([^)]*\))?\s*\{\s*\}/gu;
+        let m;
+        while ((m = re.exec(joined)) && count('empty-catch') < perKindCap) {
+            const line = joined.slice(0, m.index).split('\n').length;
+            const lineStart = joined.lastIndexOf('\n', m.index) + 1;
+            if (insideString(joined.slice(lineStart, m.index + 1), m.index - lineStart))
+                continue;
+            findings.push({
+                kind: 'empty-catch',
+                severity: 1,
+                title: `Swallowed error in ${file}:${line}`,
+                detail: 'An empty catch hides failures from users and operators alike.',
+                receipts: [receipt(file, lines, Math.max(1, line - 2), 5)],
+            });
+        }
+    }
+    // 5. Debug leftovers in non-test code.
+    for (const [file, { lines }] of codeFiles) {
+        if (count('debug-leftover') >= perKindCap)
+            break;
+        for (let i = 0; i < lines.length && count('debug-leftover') < perKindCap; i++) {
+            if (/^\s*console\.(log|debug)\(/u.test(lines[i]) || (/\.py$/iu.test(file) && /^\s*print\(/u.test(lines[i]))) {
+                findings.push({
+                    kind: 'debug-leftover',
+                    severity: 3,
+                    title: `Debug output in ${file}:${i + 1}`,
+                    detail: 'Leftover debug logging in non-test code.',
+                    receipts: [receipt(file, lines, i + 1, 0)],
+                });
+            }
+        }
+    }
+    // 6. TypeScript escape hatches.
+    for (const [file, { lines }] of codeFiles.filter(([f]) => /\.tsx?$/iu.test(f))) {
+        if (count('ts-escape-hatch') >= perKindCap)
+            break;
+        for (let i = 0; i < lines.length && count('ts-escape-hatch') < perKindCap; i++) {
+            const m = /@ts-ignore|@ts-expect-error|\bas any\b|eslint-disable(?!-next-line \S)/u.exec(lines[i]);
+            if (m && !insideString(lines[i], m.index)) {
+                findings.push({
+                    kind: 'ts-escape-hatch',
+                    severity: 2,
+                    title: `Type-safety escape hatch in ${file}:${i + 1}`,
+                    detail: 'Each escape hatch is a place the compiler can no longer help.',
+                    receipts: [receipt(file, lines, Math.max(1, i - 1), 3)],
+                });
+            }
+        }
+    }
+    // 7. Modules with exports but no matching test file.
+    const testBasenames = files.filter(([f]) => TEST_PATH.test(f)).map(([f]) => f.toLowerCase());
+    for (const [file, { lines }] of codeFiles) {
+        if (count('untested-module') >= 6)
+            break;
+        const base = (file.split('/').pop() ?? '').replace(/\.[^.]+$/u, '').toLowerCase();
+        if (base.length < 3)
+            continue;
+        const exportLines = [];
+        let runtimeExports = 0;
+        lines.forEach((l, i) => {
+            if (/^export\s|^module\.exports|^def [a-z_]+|^class [A-Z]/u.test(l)) {
+                exportLines.push(i + 1);
+                // Types and barrel re-exports carry no runtime behavior of their own.
+                if (!/^export\s+(type|interface|\{|\*)/u.test(l))
+                    runtimeExports += 1;
+            }
+        });
+        if (exportLines.length >= 2 && runtimeExports >= 2 && !testBasenames.some((t) => t.includes(base))) {
+            findings.push({
+                kind: 'untested-module',
+                severity: 2,
+                title: `${file} has ${exportLines.length} exports and no matching test file`,
+                detail: 'Logic-bearing exports without tests regress silently.',
+                receipts: exportLines.slice(0, 5).map((l) => receipt(file, lines, l, 0)),
+            });
+        }
+    }
+    // 8. Dirs with several code files and no README — grounded in the tree's own claims.
+    for (const node of Object.values(tree.nodes)) {
+        if (count('undocumented-dir') >= 5)
+            break;
+        if (node.kind !== 'dir')
+            continue;
+        const kids = node.childIds.filter((id) => tree.nodes[id]?.kind === 'leaf');
+        const codeKids = kids.filter((id) => CODE_EXT.test(tree.nodes[id].path));
+        const hasReadme = kids.some((id) => /readme\.md$/iu.test(tree.nodes[id].path));
+        if (codeKids.length >= 3 && !hasReadme) {
+            findings.push({
+                kind: 'undocumented-dir',
+                severity: 3,
+                title: `${node.path}/ has ${codeKids.length} code files and no README`,
+                detail: `What the tree already knows about it: ${node.claims.slice(0, 2).map((c) => c.text).join(' ')}`.slice(0, 240),
+                receipts: [],
+            });
+        }
+    }
+    // 9. Claims the semantic critique flagged — the code confused its own summarizer.
+    for (const node of Object.values(tree.nodes)) {
+        if (count('unsupported-claim') >= perKindCap)
+            break;
+        for (const claim of node.claims) {
+            if (claim.faithfulness === 'unsupported' && count('unsupported-claim') < perKindCap) {
+                const spans = claim.citations.filter((c) => c.kind === 'span');
+                findings.push({
+                    kind: 'unsupported-claim',
+                    severity: 2,
+                    title: `Code and its own summary disagree: ${node.path}`,
+                    detail: `The critique judged "${claim.text.slice(0, 120)}" unsupported by the cited lines — the code is unclear or the behavior surprising.`,
+                    receipts: spans.map((s) => ({ file: s.span.file, startLine: s.span.startLine, endLine: s.span.endLine, text: s.span.text.slice(0, 600) })),
+                });
+            }
+        }
+    }
+    return findings.sort((a, b) => a.severity - b.severity).slice(0, 30);
+};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export * from './core/types.js';
+export { normalizeText, sha256, splitLines } from './core/hash.js';
+export { chunkFile } from './core/chunk.js';
+export { loadCorpus } from './core/corpus.js';
+export type { LoadOptions, LoadedCorpus, SkippedFile } from './core/corpus.js';
+export { makeSpan, verifySpan, verifyClaim, verifyTree, applyVerification } from './core/gate.js';
+export { loadTree, saveTree, treePath } from './core/store.js';
+export { Bm25Index, tokenize } from './core/bm25.js';
+export { buildTree, verifyExisting } from './build/builder.js';
+export type { BuildOptions, BuildResult, ProgressEvent, VerifyResult } from './build/builder.js';
+export { refineClaims } from './build/reflexion.js';
+export { summarizeFile, extractiveClaims, parseClaimDrafts } from './build/summarize.js';
+export { ask } from './query/ask.js';
+export type { AskResult, AnswerSentence, EvidenceItem } from './query/ask.js';
+export { ollamaProvider, ollamaReachable } from './llm/ollama.js';
+export { anthropicProvider } from './llm/anthropic.js';
+export { mockProvider } from './llm/mock.js';
+export type { ChatProvider, ChatOptions } from './llm/provider.js';
+export { createOverstoryServer, runStdioServer } from './mcp/server.js';
+export { buildSiteData } from './site/data.js';
+export { generateSiteHtml } from './site/generate.js';
+export { buildTreeFromCorpus } from './build/inmemory.js';
+export { fetchGithubSnapshot, snapshotFromTarball, readTar } from './registry/github.js';
+export type { GithubSnapshot, FetchOptions } from './registry/github.js';
+export { instantTree, adjudicatePublish, reverify } from './registry/registry.js';
+export type { PublishVerdict } from './registry/registry.js';
+export { parseGithubRemote, checkPublished, DEFAULT_REGISTRY } from './registry/publishClient.js';
+export { fetchRepoTree } from './registry/repoTree.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+export * from './core/types.js';
+export { normalizeText, sha256, splitLines } from './core/hash.js';
+export { chunkFile } from './core/chunk.js';
+export { loadCorpus } from './core/corpus.js';
+export { makeSpan, verifySpan, verifyClaim, verifyTree, applyVerification } from './core/gate.js';
+export { loadTree, saveTree, treePath } from './core/store.js';
+export { Bm25Index, tokenize } from './core/bm25.js';
+export { buildTree, verifyExisting } from './build/builder.js';
+export { refineClaims } from './build/reflexion.js';
+export { summarizeFile, extractiveClaims, parseClaimDrafts } from './build/summarize.js';
+export { ask } from './query/ask.js';
+export { ollamaProvider, ollamaReachable } from './llm/ollama.js';
+export { anthropicProvider } from './llm/anthropic.js';
+export { mockProvider } from './llm/mock.js';
+export { createOverstoryServer, runStdioServer } from './mcp/server.js';
+export { buildSiteData } from './site/data.js';
+export { generateSiteHtml } from './site/generate.js';
+export { buildTreeFromCorpus } from './build/inmemory.js';
+export { fetchGithubSnapshot, snapshotFromTarball, readTar } from './registry/github.js';
+export { instantTree, adjudicatePublish, reverify } from './registry/registry.js';
+export { parseGithubRemote, checkPublished, DEFAULT_REGISTRY } from './registry/publishClient.js';
+export { fetchRepoTree } from './registry/repoTree.js';

package/dist/llm/anthropic.d.ts

@@ -0,0 +1,11 @@
+import { ChatProvider } from './provider.js';
+export interface AnthropicConfig {
+    apiKey?: string;
+    model?: string;
+    concurrency?: number;
+    timeoutMs?: number;
+    baseUrl?: string;
+}
+/** Direct Messages API via fetch — no SDK dependency. Default model is the cheap tier;
+ * the Reflexion critique step passes its own stronger model ("generate cheap, judge dear"). */
+export declare const anthropicProvider: (config?: AnthropicConfig) => ChatProvider;

package/dist/llm/anthropic.js

@@ -0,0 +1,46 @@
+import { ProviderError } from './provider.js';
+/** Direct Messages API via fetch — no SDK dependency. Default model is the cheap tier;
+ * the Reflexion critique step passes its own stronger model ("generate cheap, judge dear"). */
+export const anthropicProvider = (config = {}) => {
+    const apiKey = config.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    const model = config.model ?? process.env.OVERSTORY_ANTHROPIC_MODEL ?? 'claude-haiku-4-5-20251001';
+    const baseUrl = config.baseUrl ?? 'https://api.anthropic.com';
+    if (!apiKey)
+        throw new ProviderError('anthropic', 'ANTHROPIC_API_KEY is not set');
+    return {
+        name: `anthropic:${model}`,
+        concurrency: config.concurrency ?? 6,
+        async chat(prompt, opts = {}) {
+            let res;
+            try {
+                res = await fetch(`${baseUrl}/v1/messages`, {
+                    method: 'POST',
+                    signal: AbortSignal.timeout(config.timeoutMs ?? 120_000),
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-api-key': apiKey,
+                        'anthropic-version': '2023-06-01',
+                    },
+                    body: JSON.stringify({
+                        model,
+                        max_tokens: opts.maxTokens ?? 2000,
+                        ...(opts.system ? { system: opts.system } : {}),
+                        messages: [{ role: 'user', content: prompt }],
+                    }),
+                });
+            }
+            catch (cause) {
+                throw new ProviderError(`anthropic:${model}`, 'request failed', cause);
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new ProviderError(`anthropic:${model}`, `HTTP ${res.status}: ${text.slice(0, 300)}`);
+            }
+            const body = (await res.json());
+            const text = body.content?.find((b) => b.type === 'text')?.text;
+            if (typeof text !== 'string')
+                throw new ProviderError(`anthropic:${model}`, 'empty response');
+            return text;
+        },
+    };
+};

package/dist/llm/mock.d.ts

@@ -0,0 +1,5 @@
+import { ChatOptions, ChatProvider } from './provider.js';
+/** Test double: answers from a queue or a handler. Records every prompt. */
+export declare const mockProvider: (responses: string[] | ((prompt: string, opts?: ChatOptions) => string)) => ChatProvider & {
+    prompts: string[];
+};

package/dist/llm/mock.js

@@ -0,0 +1,20 @@
+/** Test double: answers from a queue or a handler. Records every prompt. */
+export const mockProvider = (responses) => {
+    const queue = Array.isArray(responses) ? [...responses] : null;
+    const prompts = [];
+    return {
+        name: 'mock',
+        concurrency: 8,
+        prompts,
+        async chat(prompt, opts) {
+            prompts.push(prompt);
+            if (queue) {
+                const next = queue.shift();
+                if (next === undefined)
+                    throw new Error('mockProvider: response queue exhausted');
+                return next;
+            }
+            return responses(prompt, opts);
+        },
+    };
+};

package/dist/llm/ollama.d.ts

@@ -0,0 +1,11 @@
+import { ChatProvider } from './provider.js';
+export interface OllamaConfig {
+    baseUrl?: string;
+    model?: string;
+    /** Single-GPU hosts queue anyway; 2 keeps the pipe full without thrash. */
+    concurrency?: number;
+    timeoutMs?: number;
+    numCtx?: number;
+}
+export declare const ollamaProvider: (config?: OllamaConfig) => ChatProvider;
+export declare const ollamaReachable: (baseUrl?: string) => Promise<boolean>;

package/dist/llm/ollama.js

@@ -0,0 +1,49 @@
+import { ProviderError } from './provider.js';
+export const ollamaProvider = (config = {}) => {
+    const baseUrl = config.baseUrl ?? process.env.OVERSTORY_OLLAMA_URL ?? 'http://localhost:11434';
+    const model = config.model ?? process.env.OVERSTORY_OLLAMA_MODEL ?? 'qwen2.5:14b';
+    const timeoutMs = config.timeoutMs ?? 240_000;
+    return {
+        name: `ollama:${model}`,
+        concurrency: config.concurrency ?? 2,
+        async chat(prompt, opts = {}) {
+            const messages = [];
+            if (opts.system)
+                messages.push({ role: 'system', content: opts.system });
+            messages.push({ role: 'user', content: prompt });
+            let res;
+            try {
+                res = await fetch(`${baseUrl}/api/chat`, {
+                    method: 'POST',
+                    signal: AbortSignal.timeout(timeoutMs),
+                    body: JSON.stringify({
+                        model,
+                        stream: false,
+                        ...(opts.json ? { format: 'json' } : {}),
+                        options: { num_ctx: config.numCtx ?? 8192, temperature: 0.2 },
+                        messages,
+                    }),
+                });
+            }
+            catch (cause) {
+                throw new ProviderError(`ollama:${model}`, 'request failed (is Ollama running?)', cause);
+            }
+            if (!res.ok)
+                throw new ProviderError(`ollama:${model}`, `HTTP ${res.status}`);
+            const body = (await res.json());
+            const content = body.message?.content;
+            if (typeof content !== 'string')
+                throw new ProviderError(`ollama:${model}`, 'empty response');
+            return content;
+        },
+    };
+};
+export const ollamaReachable = async (baseUrl = 'http://localhost:11434') => {
+    try {
+        const res = await fetch(`${baseUrl}/api/tags`, { signal: AbortSignal.timeout(3_000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+};

package/dist/llm/provider.d.ts

@@ -0,0 +1,16 @@
+export interface ChatOptions {
+    /** Ask the provider to emit strict JSON (native JSON mode where supported). */
+    json?: boolean;
+    system?: string;
+    maxTokens?: number;
+}
+export interface ChatProvider {
+    name: string;
+    /** How many concurrent requests this provider handles well. */
+    concurrency: number;
+    chat(prompt: string, opts?: ChatOptions): Promise<string>;
+}
+export declare class ProviderError extends Error {
+    readonly cause?: unknown;
+    constructor(provider: string, message: string, cause?: unknown);
+}

package/dist/llm/provider.js

@@ -0,0 +1,7 @@
+export class ProviderError extends Error {
+    cause;
+    constructor(provider, message, cause) {
+        super(`[${provider}] ${message}`);
+        this.cause = cause;
+    }
+}

package/dist/llm/resolve.d.ts

@@ -0,0 +1,14 @@
+import type { ChatProvider } from './provider.js';
+export interface ResolveOptions {
+    /** 'auto' | 'ollama' | 'anthropic' | 'none' */
+    provider?: string;
+    model?: string;
+    onNotice?: (message: string) => void;
+}
+export interface ResolvedProviders {
+    provider: ChatProvider | null;
+    critic: ChatProvider | null;
+}
+/** Shared provider resolution for CLI + serve: explicit choice wins; auto prefers the
+ * Anthropic key, then local Ollama, then honest extractive. */
+export declare const resolveProviders: (opts?: ResolveOptions) => Promise<ResolvedProviders>;

package/dist/llm/resolve.js

@@ -0,0 +1,24 @@
+import { anthropicProvider } from './anthropic.js';
+import { ollamaProvider, ollamaReachable } from './ollama.js';
+/** Shared provider resolution for CLI + serve: explicit choice wins; auto prefers the
+ * Anthropic key, then local Ollama, then honest extractive. */
+export const resolveProviders = async (opts = {}) => {
+    const wanted = opts.provider ?? 'auto';
+    if (wanted === 'none')
+        return { provider: null, critic: null };
+    if (wanted === 'anthropic' || (wanted === 'auto' && process.env.ANTHROPIC_API_KEY)) {
+        const provider = anthropicProvider({ model: opts.model });
+        const critic = anthropicProvider({ model: process.env.OVERSTORY_CRITIC_MODEL ?? 'claude-sonnet-5' });
+        return { provider, critic };
+    }
+    if (wanted === 'ollama' || wanted === 'auto') {
+        if (await ollamaReachable()) {
+            const provider = ollamaProvider({ model: opts.model });
+            return { provider, critic: provider };
+        }
+        if (wanted === 'ollama')
+            throw new Error('Ollama is not reachable at localhost:11434. Start it, or use --provider none.');
+        opts.onNotice?.('No LLM available (no ANTHROPIC_API_KEY, Ollama unreachable) — answers fall back to verified evidence claims.');
+    }
+    return { provider: null, critic: null };
+};

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** MCP server over a built tree. The host agent (Claude Code, Cursor, ...) does the
+ * thinking; these tools return evidence with receipts and mechanically check the host's
+ * own citations. Verification here is provenance + freshness — deliberately never a
+ * claim of semantic truth. */
+export declare const createOverstoryServer: (root: string) => McpServer;
+export declare const runStdioServer: (root: string) => Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,136 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { loadCorpus } from '../core/corpus.js';
+import { verifyTree } from '../core/gate.js';
+import { loadTree, treePath } from '../core/store.js';
+import { buildClaimIndex } from '../query/ask.js';
+import { notarizeClaims } from '../query/notarize.js';
+const json = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+const jsonError = (message) => ({ ...json({ error: message }), isError: true });
+const NEEDS_BUILD = 'No knowledge tree found. Run `npx @northtek/overstory build` in the project first.';
+/** MCP server over a built tree. The host agent (Claude Code, Cursor, ...) does the
+ * thinking; these tools return evidence with receipts and mechanically check the host's
+ * own citations. Verification here is provenance + freshness — deliberately never a
+ * claim of semantic truth. */
+export const createOverstoryServer = (root) => {
+    const server = new McpServer({ name: 'overstory', version: '0.1.0' });
+    const load = async () => {
+        const tree = await loadTree(treePath(root));
+        if (!tree)
+            return null;
+        // Verify against the corpus the tree was BUILT with — a differently-scoped corpus
+        // produces wrong verdicts (files outside the default caps would read OUT_OF_CORPUS).
+        const corpus = await loadCorpus(root, tree.corpusOptions ?? {});
+        return { tree, corpus };
+    };
+    server.registerTool('overstory_map', {
+        description: 'Overview of the knowledge tree for this repo: root claims, top-level structure, and live freshness (fraction of claims whose receipts still verify against the current code).',
+        inputSchema: {},
+    }, async () => {
+        const loaded = await load();
+        if (!loaded)
+            return jsonError(NEEDS_BUILD);
+        const { tree, corpus } = loaded;
+        const verification = verifyTree(tree, corpus);
+        const rootNode = tree.nodes[tree.root];
+        return json({
+            name: tree.name,
+            builtAt: tree.builtAt,
+            freshness: Number(verification.freshness.toFixed(3)),
+            rootClaims: rootNode.claims.map((c) => ({ id: c.id, text: c.text, verdict: verification.verdicts.get(c.id), faithfulness: c.faithfulness })),
+            children: rootNode.childIds.map((id) => {
+                const n = tree.nodes[id];
+                const counts = verification.byNode.get(id);
+                return { id, path: n.path, kind: n.kind, summary: n.summary, claims: counts?.total ?? 0, verified: counts?.verified ?? 0 };
+            }),
+        });
+    });
+    server.registerTool('overstory_node', {
+        description: 'One tree node (by node id like "leaf:src/gate.ts" / "dir:src", or by file/dir path) with all its claims, verdicts, faithfulness tiers, and source receipts (file:line spans).',
+        inputSchema: { idOrPath: z.string().describe('Node id or repo-relative path') },
+    }, async ({ idOrPath }) => {
+        const loaded = await load();
+        if (!loaded)
+            return jsonError(NEEDS_BUILD);
+        const { tree, corpus } = loaded;
+        const node = (Object.hasOwn(tree.nodes, idOrPath) ? tree.nodes[idOrPath] : undefined) ??
+            Object.values(tree.nodes).find((n) => n.path === idOrPath || n.path === idOrPath.replace(/\\/gu, '/'));
+        if (!node)
+            return jsonError(`No node "${idOrPath}". Try overstory_map or overstory_search first.`);
+        const verification = verifyTree(tree, corpus);
+        return json({
+            id: node.id,
+            kind: node.kind,
+            path: node.path,
+            builtWith: node.builtWith,
+            childIds: node.childIds,
+            claims: node.claims.map((c) => ({
+                id: c.id,
+                text: c.text,
+                verdict: verification.verdicts.get(c.id),
+                faithfulness: c.faithfulness,
+                receipts: c.citations.map((cit) => cit.kind === 'span'
+                    ? { file: cit.span.file, lines: `${cit.span.startLine}-${cit.span.endLine}`, text: cit.span.text.slice(0, 500) }
+                    : { claimRef: `${cit.ref.nodeId} :: ${cit.ref.claimId}` }),
+            })),
+        });
+    });
+    server.registerTool('overstory_search', {
+        description: 'Search the tree claims (BM25) for evidence relevant to a question. Returns claims with ids, verdicts, and source spans — cite these ids in answers, then check yourself with overstory_verify.',
+        inputSchema: {
+            query: z.string().describe('Search query'),
+            k: z.number().int().min(1).max(25).optional().describe('Max results, default 8'),
+        },
+    }, async ({ query, k }) => {
+        const loaded = await load();
+        if (!loaded)
+            return jsonError(NEEDS_BUILD);
+        const { tree, corpus } = loaded;
+        const verification = verifyTree(tree, corpus);
+        const { index, byId } = buildClaimIndex(tree);
+        const hits = index.search(query, k ?? 8);
+        return json(hits.map(({ id, score }) => {
+            const { claim, nodeId } = byId.get(id);
+            return {
+                claimId: id,
+                node: nodeId,
+                path: tree.nodes[nodeId].path,
+                text: claim.text,
+                verdict: verification.verdicts.get(id),
+                faithfulness: claim.faithfulness,
+                score: Number(score.toFixed(3)),
+                spans: claim.citations
+                    .filter((c) => c.kind === 'span')
+                    .map((c) => `${c.span.file}:${c.span.startLine}-${c.span.endLine}`),
+            };
+        }));
+    });
+    server.registerTool('overstory_verify', {
+        description: 'Notarize YOUR drafted answer about this repo. Submit each claim with its file:line citations; returns per-claim verdicts — RESOLVED (citation exists; receipt text returned so you can self-check it truly supports your claim), OUT_OF_CORPUS (file/lines do not exist — fix before answering), UNGROUNDED (no citations) — plus corroborating verified tree claims when found. This checks provenance mechanically; it does not certify truth.',
+        inputSchema: {
+            claims: z
+                .array(z.object({
+                text: z.string().describe('One atomic claim from your draft'),
+                citations: z
+                    .array(z.object({ file: z.string(), startLine: z.number().int().min(1), endLine: z.number().int().min(1) }))
+                    .describe('file:line evidence for this claim'),
+            }))
+                .min(1)
+                .max(30),
+        },
+    }, async ({ claims }) => {
+        const loaded = await load();
+        if (!loaded)
+            return jsonError(NEEDS_BUILD);
+        const { tree, corpus } = loaded;
+        const verification = verifyTree(tree, corpus);
+        const { index, byId } = buildClaimIndex(tree);
+        return json(notarizeClaims(claims, tree, corpus, verification, index, byId));
+    });
+    return server;
+};
+export const runStdioServer = async (root) => {
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const server = createOverstoryServer(root);
+    await server.connect(new StdioServerTransport());
+};