melchizedek-agents 0.9.0

package/dist/lib/wiki/extract.d.ts

@@ -0,0 +1,97 @@
+/**
+ * lib/wiki/extract.ts — zero-dependency scanners that read structure out of source.
+ *
+ * WHY this file exists:
+ *   The entity graph (lib/wiki/entities.ts) is only worth having if its
+ *   extracted tier is cheap and honest. These are the readers that make it
+ *   so: import edges, environment reads, table definitions and mentions,
+ *   pulled straight out of file text with regexes and no parser
+ *   dependency — the same judgment as the markdown engine
+ *   (wiki/decisions/0002): at this scale a careful scanner beats a
+ *   toolchain, and rebuild-from-source beats a cached index.
+ *
+ *   They are deliberately CONSERVATIVE. A regex cannot see a dynamic
+ *   import built from a variable, or a table name assembled at runtime;
+ *   what it does report, it read verbatim. Nothing here guesses, so an
+ *   extracted edge always has a literal line of source behind it.
+ *
+ *   Bundle-agnostic and repo-agnostic: callers hand in text and paths.
+ */
+export interface WalkOptions {
+    /** Only files whose name ends with one of these. */
+    extensions?: string[];
+    /** Directory names skipped wherever they appear. */
+    skipDirs?: string[];
+}
+/** Repo-relative POSIX paths under `dir`, sorted, dotfiles skipped. */
+export declare function walkFiles(root: string, dir: string, options?: WalkOptions): string[];
+export interface ModuleScan {
+    /** Import specifiers exactly as written. */
+    specifiers: string[];
+    /** Repo-relative paths of the local modules imported. */
+    localImports: string[];
+    /** Bare package names imported (first path segment, scope-aware). */
+    packages: string[];
+    /** Environment variables the module reads. */
+    envVars: string[];
+}
+/** Resolve a relative specifier against the importing file's repo path. */
+export declare function resolveLocalImport(fromRelPath: string, specifier: string): string | null;
+export declare function scanModule(text: string, relPath: string): ModuleScan;
+export interface SqlScan {
+    /** Tables this DDL creates. */
+    defined: string[];
+    /** Tables it alters or references without creating. */
+    referenced: string[];
+}
+export declare function scanSql(sql: string): SqlScan;
+/**
+ * Which known tables a source file ADDRESSES — matched only as a quoted
+ * literal, which is how every client library names a table:
+ * `.from(<quoted name>)`. A bare word is deliberately not enough, because
+ * prose in a comment mentions table names constantly, and an edge saying
+ * "this module touches that table" must mean it.
+ */
+export declare function tableMentions(text: string, tables: readonly string[]): string[];
+export interface ScriptScan {
+    name: string;
+    command: string;
+    /** Repo-relative source file the script executes, when one is named. */
+    entry: string | null;
+    /** Long-form flag values, e.g. { syndicate: 'critic' }. */
+    flags: Record<string, string>;
+}
+export declare function scanNpmScripts(scripts: Record<string, string>): ScriptScan[];
+/**
+ * Keys of a named top-level object literal, read from source text —
+ * `const TOOL_MAP: Record<string, unknown> = { web_search: …, … }` yields
+ * ['web_search', …]. Spread entries are skipped: they name no key here.
+ * Reading the registry as text keeps a build offline that importing it
+ * would not (module side effects, provider clients, credentials).
+ */
+export declare function scanObjectKeys(text: string, declName: string): string[];
+export interface PythonScan {
+    /** Repo-relative paths of local modules this file imports. */
+    localImports: string[];
+    /** Third-party / stdlib top-level package names. */
+    packages: string[];
+    /** Environment variables the module reads. */
+    envVars: string[];
+}
+/**
+ * Resolve a Python module path against the files a repo actually has.
+ * `services.market_data` → `services/market_data.py`; a leading dot is
+ * package-relative to the importing file's directory. Anything that does
+ * not land on a known file is treated as a third-party package, which is
+ * the conservative reading — a wrong local edge is worse than a missing one.
+ */
+export declare function resolvePythonImport(fromRelPath: string, moduleName: string, known: ReadonlySet<string>): string | null;
+export declare function scanPython(text: string, relPath: string, knownFiles: ReadonlySet<string>): PythonScan;
+export interface ProcfileEntry {
+    /** Process type — the dyno name. */
+    name: string;
+    command: string;
+    /** The script the process runs, when the command names one. */
+    entry: string | null;
+}
+export declare function scanProcfile(text: string): ProcfileEntry[];

package/dist/lib/wiki/extract.js

@@ -0,0 +1,305 @@
+/**
+ * lib/wiki/extract.ts — zero-dependency scanners that read structure out of source.
+ *
+ * WHY this file exists:
+ *   The entity graph (lib/wiki/entities.ts) is only worth having if its
+ *   extracted tier is cheap and honest. These are the readers that make it
+ *   so: import edges, environment reads, table definitions and mentions,
+ *   pulled straight out of file text with regexes and no parser
+ *   dependency — the same judgment as the markdown engine
+ *   (wiki/decisions/0002): at this scale a careful scanner beats a
+ *   toolchain, and rebuild-from-source beats a cached index.
+ *
+ *   They are deliberately CONSERVATIVE. A regex cannot see a dynamic
+ *   import built from a variable, or a table name assembled at runtime;
+ *   what it does report, it read verbatim. Nothing here guesses, so an
+ *   extracted edge always has a literal line of source behind it.
+ *
+ *   Bundle-agnostic and repo-agnostic: callers hand in text and paths.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, posix, relative, sep } from 'node:path';
+const DEFAULT_SKIP = ['node_modules', 'dist', 'build', 'coverage', 'outputs'];
+/** Repo-relative POSIX paths under `dir`, sorted, dotfiles skipped. */
+export function walkFiles(root, dir, options = {}) {
+    const skip = new Set([...DEFAULT_SKIP, ...(options.skipDirs ?? [])]);
+    const out = [];
+    const visit = (absDir) => {
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                if (skip.has(entry.name))
+                    continue;
+                visit(join(absDir, entry.name));
+            }
+            else if (entry.isFile()) {
+                if (options.extensions &&
+                    !options.extensions.some((ext) => entry.name.endsWith(ext))) {
+                    continue;
+                }
+                out.push(relative(root, join(absDir, entry.name)).split(sep).join('/'));
+            }
+        }
+    };
+    try {
+        if (statSync(dir).isDirectory())
+            visit(dir);
+    }
+    catch {
+        return [];
+    }
+    return out.sort();
+}
+/**
+ * `from '<specifier>'` covers every static import and re-export, however
+ * many lines the binding list spans; a bare side-effect import and a
+ * literal dynamic import are matched separately. Deliberately literal: a
+ * specifier assembled from a variable is invisible here, and stays so.
+ */
+const FROM_RE = /\bfrom\s+['"]([^'"\n]+)['"]/g;
+const BARE_IMPORT_RE = /(?:^|\n)\s*import\s+['"]([^'"\n]+)['"]/g;
+const DYNAMIC_IMPORT_RE = /\bimport\(\s*['"]([^'"\n]+)['"]\s*\)/g;
+const ENV_DOT_RE = /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g;
+const ENV_INDEX_RE = /process\.env\[\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]\s*\]/g;
+/** Resolve a relative specifier against the importing file's repo path. */
+export function resolveLocalImport(fromRelPath, specifier) {
+    if (!specifier.startsWith('.'))
+        return null;
+    const resolved = posix.normalize(posix.join(posix.dirname(fromRelPath), specifier));
+    return resolved.startsWith('..') ? null : resolved;
+}
+function packageName(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('/'))
+        return null;
+    if (specifier.startsWith('node:'))
+        return specifier;
+    const parts = specifier.split('/');
+    return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+export function scanModule(text, relPath) {
+    const specifiers = new Set();
+    for (const re of [FROM_RE, BARE_IMPORT_RE, DYNAMIC_IMPORT_RE]) {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(text)) !== null)
+            specifiers.add(match[1]);
+    }
+    const envVars = new Set();
+    for (const re of [ENV_DOT_RE, ENV_INDEX_RE]) {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(text)) !== null)
+            envVars.add(match[1]);
+    }
+    const localImports = new Set();
+    const packages = new Set();
+    for (const specifier of specifiers) {
+        const local = resolveLocalImport(relPath, specifier);
+        if (local) {
+            // A file cannot import itself; a match on its own path came from a
+            // usage example in a comment, which is documentation, not an edge.
+            if (local !== relPath)
+                localImports.add(local);
+            continue;
+        }
+        const pkg = packageName(specifier);
+        if (pkg)
+            packages.add(pkg);
+    }
+    return {
+        specifiers: [...specifiers].sort(),
+        localImports: [...localImports].sort(),
+        packages: [...packages].sort(),
+        envVars: [...envVars].sort(),
+    };
+}
+const CREATE_TABLE_RE = /create\s+table\s+(?:if\s+not\s+exists\s+)?(?:(?:"[^"]+"|[a-z0-9_]+)\.)?("?[a-z0-9_]+"?)/gi;
+const ALTER_TABLE_RE = /alter\s+table\s+(?:if\s+exists\s+)?(?:(?:"[^"]+"|[a-z0-9_]+)\.)?("?[a-z0-9_]+"?)/gi;
+const REFERENCES_RE = /references\s+(?:(?:"[^"]+"|[a-z0-9_]+)\.)?("?[a-z0-9_]+"?)/gi;
+function unquote(name) {
+    return name.replace(/^"|"$/g, '');
+}
+export function scanSql(sql) {
+    const defined = new Set();
+    const referenced = new Set();
+    const collect = (re, into) => {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(sql)) !== null)
+            into.add(unquote(match[1]));
+    };
+    collect(CREATE_TABLE_RE, defined);
+    collect(ALTER_TABLE_RE, referenced);
+    collect(REFERENCES_RE, referenced);
+    for (const name of defined)
+        referenced.delete(name);
+    return { defined: [...defined].sort(), referenced: [...referenced].sort() };
+}
+/**
+ * Which known tables a source file ADDRESSES — matched only as a quoted
+ * literal, which is how every client library names a table:
+ * `.from(<quoted name>)`. A bare word is deliberately not enough, because
+ * prose in a comment mentions table names constantly, and an edge saying
+ * "this module touches that table" must mean it.
+ */
+export function tableMentions(text, tables) {
+    const found = new Set();
+    for (const table of tables) {
+        if (new RegExp(`['"\`]${table}['"\`]`).test(text))
+            found.add(table);
+    }
+    return [...found].sort();
+}
+const ENTRY_RE = /(?:^|\s)((?:scripts|lib|tests|demo)\/[\w./-]+\.(?:ts|mjs|js))/;
+const FLAG_RE = /--([a-z][\w-]*)\s+([^\s]+)/g;
+export function scanNpmScripts(scripts) {
+    return Object.entries(scripts).map(([name, command]) => {
+        const entry = ENTRY_RE.exec(command)?.[1] ?? null;
+        const flags = {};
+        FLAG_RE.lastIndex = 0;
+        let match;
+        while ((match = FLAG_RE.exec(command)) !== null) {
+            if (!match[2].startsWith('-'))
+                flags[match[1]] = match[2];
+        }
+        return { name, command, entry, flags };
+    });
+}
+// ── Object-literal keys ──────────────────────────────────────────────────────
+/**
+ * Keys of a named top-level object literal, read from source text —
+ * `const TOOL_MAP: Record<string, unknown> = { web_search: …, … }` yields
+ * ['web_search', …]. Spread entries are skipped: they name no key here.
+ * Reading the registry as text keeps a build offline that importing it
+ * would not (module side effects, provider clients, credentials).
+ */
+export function scanObjectKeys(text, declName) {
+    const start = new RegExp(`\\b(?:const|let|var)\\s+${declName}\\b[^=]*=\\s*\\{`).exec(text);
+    if (!start)
+        return [];
+    let depth = 0;
+    let end = -1;
+    const open = start.index + start[0].length - 1;
+    for (let i = open; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+        }
+    }
+    if (end === -1)
+        return [];
+    const body = text.slice(open + 1, end);
+    const keys = new Set();
+    let nesting = 0;
+    for (const line of body.split('\n')) {
+        const trimmed = line.trim();
+        if (nesting === 0) {
+            const match = /^(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$]*))\s*:/.exec(trimmed);
+            if (match)
+                keys.add(match[1] ?? match[2] ?? match[3]);
+        }
+        for (const ch of line) {
+            if (ch === '{' || ch === '[' || ch === '(')
+                nesting++;
+            else if (ch === '}' || ch === ']' || ch === ')')
+                nesting--;
+        }
+        if (nesting < 0)
+            nesting = 0;
+    }
+    return [...keys].sort();
+}
+const PY_IMPORT_RE = /(?:^|\n)\s*import\s+([A-Za-z_][\w.]*(?:\s*,\s*[A-Za-z_][\w.]*)*)/g;
+const PY_FROM_RE = /(?:^|\n)\s*from\s+(\.*[A-Za-z_][\w.]*|\.+)\s+import\s+/g;
+const PY_ENV_RE = /os\.environ(?:\.get)?\(\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]|os\.getenv\(\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]|os\.environ\[\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]\s*\]/g;
+/**
+ * Resolve a Python module path against the files a repo actually has.
+ * `services.market_data` → `services/market_data.py`; a leading dot is
+ * package-relative to the importing file's directory. Anything that does
+ * not land on a known file is treated as a third-party package, which is
+ * the conservative reading — a wrong local edge is worse than a missing one.
+ */
+export function resolvePythonImport(fromRelPath, moduleName, known) {
+    const dots = /^\.*/.exec(moduleName)?.[0].length ?? 0;
+    const bare = moduleName.slice(dots);
+    let baseDir = posix.dirname(fromRelPath);
+    for (let i = 1; i < dots; i++)
+        baseDir = posix.dirname(baseDir);
+    const segments = bare === '' ? [] : bare.split('.');
+    const candidates = [];
+    if (dots > 0) {
+        const joined = [baseDir, ...segments].filter((p) => p && p !== '.').join('/');
+        candidates.push(`${joined}.py`, `${joined}/__init__.py`);
+    }
+    else {
+        const joined = segments.join('/');
+        candidates.push(`${joined}.py`, `${joined}/__init__.py`);
+        // A module imported by bare name from the repo root, e.g. `import advisor`.
+        if (segments.length === 1)
+            candidates.push(`${segments[0]}.py`);
+    }
+    return candidates.find((c) => known.has(c)) ?? null;
+}
+export function scanPython(text, relPath, knownFiles) {
+    const modules = new Set();
+    PY_IMPORT_RE.lastIndex = 0;
+    let match;
+    while ((match = PY_IMPORT_RE.exec(text)) !== null) {
+        for (const name of match[1].split(','))
+            modules.add(name.trim());
+    }
+    PY_FROM_RE.lastIndex = 0;
+    while ((match = PY_FROM_RE.exec(text)) !== null)
+        modules.add(match[1].trim());
+    const localImports = new Set();
+    const packages = new Set();
+    for (const moduleName of modules) {
+        const local = resolvePythonImport(relPath, moduleName, knownFiles);
+        if (local && local !== relPath)
+            localImports.add(local);
+        else if (!moduleName.startsWith('.'))
+            packages.add(moduleName.split('.')[0]);
+    }
+    const envVars = new Set();
+    PY_ENV_RE.lastIndex = 0;
+    while ((match = PY_ENV_RE.exec(text)) !== null) {
+        envVars.add(match[1] ?? match[2] ?? match[3]);
+    }
+    return {
+        localImports: [...localImports].sort(),
+        packages: [...packages].sort(),
+        envVars: [...envVars].sort(),
+    };
+}
+const PROC_ENTRY_RE = /(?:^|\s)([\w./-]+\.(?:py|ts|js|mjs|sh))(?:\s|$)/;
+export function scanProcfile(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const colon = trimmed.indexOf(':');
+        if (colon === -1)
+            continue;
+        const name = trimmed.slice(0, colon).trim();
+        const command = trimmed.slice(colon + 1).trim();
+        if (name === '' || command === '')
+            continue;
+        entries.push({ name, command, entry: PROC_ENTRY_RE.exec(command)?.[1] ?? null });
+    }
+    return entries;
+}

package/dist/lib/wiki/fill.d.ts

@@ -0,0 +1,37 @@
+/**
+ * lib/wiki/fill.ts — the LLM pass: write the prose a structural build can't.
+ *
+ * WHY this file exists:
+ *   A structural build produces true-but-mute documents: tables, listings,
+ *   links, and empty wiki:fill slots. This pass walks the bundle for slots
+ *   still holding the TODO sentinel and asks a model to write ONLY that
+ *   missing prose — one slot at a time, grounded in the document itself,
+ *   its graph neighbors (the only links it may use), and excerpts of the
+ *   repo files named in `sources`. The model never touches structure: the
+ *   slot interior is the entire blast radius, enforced by the marker
+ *   splice, and lint gates the result like any other write.
+ *
+ *   Provenance is honest: a filled document's `generated.by` becomes
+ *   `melchizedek/<model>` — the §5.3 trust derivation then reports it as
+ *   machine-confirmed at best, never human-reviewed, until a person adds
+ *   a `verified` entry. No key configured → the pass reports itself
+ *   skipped and the skeleton keeps its TODO sentinels; nothing breaks.
+ */
+import { type Vault } from './vault.ts';
+export interface FillOptions {
+    /** Model string routed via lib/models/registry.ts. */
+    model: string;
+    /** Cap on documents touched in one pass. */
+    maxDocs?: number;
+    /** YYYY-MM-DD stamped into generated.at. */
+    date: string;
+    log?: (message: string) => void;
+}
+export interface FillOutcome {
+    docsTouched: number;
+    slotsFilled: number;
+    slotsFailed: number;
+    /** Why nothing ran, when nothing ran. */
+    skippedReason?: string;
+}
+export declare function fillVault(vault: Vault, options: FillOptions): Promise<FillOutcome>;

package/dist/lib/wiki/fill.js

@@ -0,0 +1,175 @@
+/**
+ * lib/wiki/fill.ts — the LLM pass: write the prose a structural build can't.
+ *
+ * WHY this file exists:
+ *   A structural build produces true-but-mute documents: tables, listings,
+ *   links, and empty wiki:fill slots. This pass walks the bundle for slots
+ *   still holding the TODO sentinel and asks a model to write ONLY that
+ *   missing prose — one slot at a time, grounded in the document itself,
+ *   its graph neighbors (the only links it may use), and excerpts of the
+ *   repo files named in `sources`. The model never touches structure: the
+ *   slot interior is the entire blast radius, enforced by the marker
+ *   splice, and lint gates the result like any other write.
+ *
+ *   Provenance is honest: a filled document's `generated.by` becomes
+ *   `melchizedek/<model>` — the §5.3 trust derivation then reports it as
+ *   machine-confirmed at best, never human-reviewed, until a person adds
+ *   a `verified` entry. No key configured → the pass reports itself
+ *   skipped and the skeleton keeps its TODO sentinels; nothing breaks.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runWikiAgent, modelAvailable } from "./agentRun.js";
+import { llmActor } from "./format.js";
+import { buildGraph } from "./graph.js";
+import { emitFrontmatter, parseDoc, setSlotContent, slotIsUnfilled, TODO_SENTINEL, } from "./markdown.js";
+import { loadDoc, writeDocFile } from "./vault.js";
+// ── Prompt assembly ──────────────────────────────────────────────────────────
+const WRITER_INSTRUCTION = `You write missing prose for knowledge-base documents about a software system.
+You receive one document, the id of one empty slot in it, a hint describing what belongs there, link candidates, and source excerpts.
+Rules:
+- Write ONLY the slot's prose: no preamble, no code fences around the reply, no headings unless the hint asks.
+- 60–140 words unless the hint says otherwise. Plain, concrete, present tense. No marketing language, no hedging.
+- Every claim must come from the provided document, excerpts, or link candidates. If the context does not support a claim, leave it out.
+- Markdown links are allowed ONLY to the exact paths listed under LINK CANDIDATES. Never invent a path or URL.
+- If the context is insufficient to write anything true, reply with exactly: INSUFFICIENT_CONTEXT`;
+function neighborCandidates(vault, graph, doc) {
+    const paths = new Set();
+    for (const e of graph.outbound.get(doc.bundlePath) ?? []) {
+        if (e.resolved)
+            paths.add(e.target);
+    }
+    for (const e of graph.inbound.get(doc.bundlePath) ?? [])
+        paths.add(e.source);
+    const lines = [];
+    for (const path of [...paths].slice(0, 14)) {
+        const neighbor = vault.docs.get(path);
+        if (!neighbor)
+            continue;
+        const desc = neighbor.fm?.description ?? '';
+        lines.push(`- ${path} — ${neighbor.title}${desc ? `: ${desc}` : ''}`);
+    }
+    return lines.length > 0 ? lines.join('\n') : '(none)';
+}
+function sourceExcerpts(vault, doc) {
+    const repoRoot = resolve(vault.root, '..');
+    const chunks = [];
+    for (const source of doc.fm?.sources ?? []) {
+        const resource = source.resource;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(resource))
+            continue; // URLs: not readable here
+        const abs = resource.startsWith('/')
+            ? resolve(vault.root, `.${resource}`)
+            : resolve(repoRoot, resource);
+        if (!abs.startsWith(repoRoot) || !existsSync(abs))
+            continue;
+        try {
+            const text = readFileSync(abs, 'utf-8').split('\n').slice(0, 120).join('\n');
+            chunks.push(`--- ${resource} (first 120 lines) ---\n${text}`);
+        }
+        catch {
+            // unreadable source: the slot simply gets less context
+        }
+    }
+    return chunks.length > 0 ? chunks.join('\n\n') : '(none)';
+}
+function buildUserText(vault, graph, doc, slotId, hint) {
+    return [
+        `DOCUMENT (${doc.bundlePath}):`,
+        doc.parsed.raw,
+        `\nSLOT TO FILL: "${slotId}"`,
+        `HINT: ${hint}`,
+        `\nLINK CANDIDATES (the only linkable paths):`,
+        neighborCandidates(vault, graph, doc),
+        `\nSOURCE EXCERPTS:`,
+        sourceExcerpts(vault, doc),
+    ].join('\n');
+}
+function slotHint(slot) {
+    const text = slot.content.trim();
+    if (text.startsWith(TODO_SENTINEL)) {
+        return text.slice(TODO_SENTINEL.length).replace(/_$/, '').trim();
+    }
+    return slot.id;
+}
+/** Strip a whole-reply code fence if the model added one despite the rules. */
+function cleanReply(reply) {
+    const trimmed = reply.trim();
+    const fenced = trimmed.match(/^```[a-z]*\n([\s\S]*?)\n```$/);
+    return (fenced ? fenced[1] : trimmed).trim();
+}
+// ── The pass ─────────────────────────────────────────────────────────────────
+export async function fillVault(vault, options) {
+    const log = options.log ?? (() => { });
+    const availability = modelAvailable(options.model);
+    if (!availability.ok) {
+        return {
+            docsTouched: 0,
+            slotsFilled: 0,
+            slotsFailed: 0,
+            skippedReason: `fill skipped: ${availability.reason}`,
+        };
+    }
+    const graph = buildGraph(vault);
+    const candidates = [...vault.docs.values()].filter((doc) => doc.kind !== 'log' && doc.parsed.slots.some(slotIsUnfilled));
+    const limit = options.maxDocs ?? 50;
+    let docsTouched = 0;
+    let slotsFilled = 0;
+    let slotsFailed = 0;
+    for (const doc of candidates.slice(0, limit)) {
+        let raw = doc.parsed.raw;
+        let docChanged = false;
+        for (const slot of doc.parsed.slots.filter(slotIsUnfilled)) {
+            const hint = slotHint(slot);
+            log(`fill ${doc.bundlePath} · slot "${slot.id}"`);
+            const result = await runWikiAgent({
+                name: 'wiki_scribe',
+                description: 'Writes one missing prose passage for a wiki document.',
+                model: options.model,
+                instruction: WRITER_INSTRUCTION,
+                userText: buildUserText(vault, graph, doc, slot.id, hint),
+                temperature: 0.3,
+                // Reasoning models spend thought tokens from the same budget; a
+                // tight cap truncates the visible prose mid-sentence.
+                maxOutputTokens: 4096,
+            });
+            if (result.error || result.text === '' || result.text === 'INSUFFICIENT_CONTEXT') {
+                slotsFailed++;
+                log(`  ✗ ${slot.id}: ${result.error ?? (result.text || 'empty reply')}`);
+                continue;
+            }
+            const prose = cleanReply(result.text);
+            const truncated = !/[.!?)`\]]$/.test(prose.trimEnd());
+            if (prose.includes(TODO_SENTINEL) || prose === '' || truncated) {
+                if (truncated)
+                    log(`  ✗ ${slot.id}: reply looks truncated, slot left unfilled`);
+                slotsFailed += truncated || prose === '' ? 1 : 0;
+                continue;
+            }
+            const next = setSlotContent(raw, slot.id, prose);
+            if (next) {
+                raw = next;
+                docChanged = true;
+                slotsFilled++;
+            }
+        }
+        if (docChanged) {
+            // Stamp provenance: the model made the last meaningful change.
+            const parsed = parseDoc(raw);
+            if (parsed.frontmatter) {
+                const fm = {
+                    ...parsed.frontmatter,
+                    generated: { by: llmActor(options.model), at: options.date },
+                };
+                const lines = raw.split('\n');
+                const body = lines.slice(parsed.bodyStartLine - 1).join('\n');
+                raw = `${emitFrontmatter(fm)}\n${body.replace(/^\n+/, '')}`;
+            }
+            writeDocFile(vault.root, doc.bundlePath, raw);
+            // Refresh the in-memory doc so later passes see current content.
+            vault.docs.set(doc.bundlePath, loadDoc(vault.root, doc.absPath));
+            docsTouched++;
+        }
+    }
+    return { docsTouched, slotsFilled, slotsFailed };
+}