melchizedek-agents 0.9.0

package/dist/lib/wiki/markdown.js

@@ -0,0 +1,336 @@
+/**
+ * lib/wiki/markdown.ts — structural markdown: one node model, two directions.
+ *
+ * WHY this file exists:
+ *   The wiki needs to READ markdown structurally (frontmatter, headings,
+ *   links, fenced code, edit markers — enough to lint, graph, and navigate)
+ *   and to WRITE it structurally (docs assembled from typed parts, so links
+ *   and frontmatter are correct by construction). Both directions share the
+ *   shapes in this file.
+ *
+ *   Deliberately NOT a CommonMark AST. A full parser (remark/unified) would
+ *   add a dependency tree to a repo that has none for markdown, to answer
+ *   questions we don't ask — inline emphasis, HTML blocks, tables-as-trees.
+ *   The wiki's questions are structural: what does this doc declare, where
+ *   are its sections, what does it link to, which regions are machine-owned.
+ *   ~300 lines answer all of them with zero new dependencies
+ *   (wiki/decisions/0002). Frontmatter YAML goes through the same `yaml`
+ *   package the syndicate loader already uses.
+ *
+ *   Editing is SURGICAL, never a re-serialise of the whole document: the
+ *   parse keeps line positions, and edits splice exact line ranges (a fill
+ *   slot's interior, a generated block's interior, a log insertion point).
+ *   Prose the machine doesn't own is never reflowed.
+ *
+ * Marker grammar (HTML comments — invisible in rendered markdown):
+ *   <!-- wiki:generated section="<id>" source="<path>" -->…<!-- /wiki:generated -->
+ *     Machine-owned region; `wiki:build` rewrites its interior. `source`
+ *     names the repo truth it derives from.
+ *   <!-- wiki:fill slot="<id>" -->…<!-- /wiki:fill -->
+ *     Prose slot. Structural builds leave its interior alone; the LLM pass
+ *     (lib/wiki/fill.ts) replaces it while it still holds a TODO sentinel.
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+/** Sentinel left in an unfilled slot; the fill pass replaces it. */
+export const TODO_SENTINEL = '_TODO(fill):';
+export function slotIsUnfilled(slot) {
+    const text = slot.content.trim();
+    return text === '' || text.startsWith(TODO_SENTINEL);
+}
+// ── Parsing ──────────────────────────────────────────────────────────────────
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})\s*(\S*)/;
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+const MARKER_OPEN_RE = /^<!--\s*wiki:(fill|generated)\s+([^>]*?)\s*-->\s*$/;
+const MARKER_CLOSE_RE = /^<!--\s*\/wiki:(fill|generated)\s*-->\s*$/;
+const ATTR_RE = /([a-zA-Z_]+)="([^"]*)"/g;
+const INLINE_LINK_RE = /(!?)\[([^\]]*)\]\(<?([^()<>\s]+(?:\([^()]*\))?)>?(?:\s+"[^"]*")?\)/g;
+const REF_DEF_RE = /^ {0,3}\[([^\]]+)\]:\s+(\S+)/;
+const REF_USE_RE = /(!?)\[([^\]]+)\]\[([^\]]*)\]/g;
+const WIKILINK_RE = /\[\[([^\]]+)\]\]/g;
+/** GitHub-style anchor slug — for addressing sections by name. */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[`*_~]/g, '')
+        .replace(/[^\p{L}\p{N}\s-]/gu, '')
+        .trim()
+        .replace(/\s+/g, '-');
+}
+/** Mask `inline code` so syntax examples inside backticks never parse as links. */
+function maskInlineCode(line) {
+    return line.replace(/`[^`]*`/g, (m) => ' '.repeat(m.length));
+}
+export function parseDoc(raw) {
+    const lines = raw.split('\n');
+    // Frontmatter block: `---` on line 1, closed by `---` or `...`.
+    let frontmatterRaw = null;
+    let frontmatter = null;
+    let frontmatterError;
+    let bodyStartLine = 1;
+    if (lines[0]?.trim() === '---') {
+        for (let i = 1; i < lines.length; i++) {
+            const t = lines[i].trim();
+            if (t === '---' || t === '...') {
+                frontmatterRaw = lines.slice(1, i).join('\n');
+                bodyStartLine = i + 2;
+                break;
+            }
+        }
+        if (frontmatterRaw !== null) {
+            try {
+                const parsed = parseYaml(frontmatterRaw);
+                if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    frontmatter = parsed;
+                }
+                else if (parsed !== null) {
+                    frontmatterError = 'frontmatter is not a YAML mapping';
+                }
+            }
+            catch (err) {
+                frontmatterError = err instanceof Error ? err.message : String(err);
+            }
+        }
+    }
+    const headings = [];
+    const links = [];
+    const wikilinks = [];
+    const fences = [];
+    const slots = [];
+    const generated = [];
+    const unclosedMarkers = [];
+    const refDefs = new Map();
+    let openFence = null;
+    let openMarker = null;
+    const refUses = [];
+    for (let i = bodyStartLine - 1; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNo = i + 1;
+        // Fences first — nothing inside a fence is structure.
+        const fenceMatch = line.match(FENCE_RE);
+        if (fenceMatch) {
+            const [, marks, lang] = fenceMatch;
+            if (!openFence) {
+                openFence = { char: marks[0], len: marks.length, startLine: lineNo, lang };
+                continue;
+            }
+            if (marks[0] === openFence.char && marks.length >= openFence.len && lang === '') {
+                fences.push({ startLine: openFence.startLine, endLine: lineNo, lang: openFence.lang });
+                openFence = null;
+                continue;
+            }
+        }
+        if (openFence)
+            continue;
+        // Edit markers.
+        const open = line.match(MARKER_OPEN_RE);
+        if (open) {
+            if (openMarker)
+                unclosedMarkers.push({ kind: openMarker.kind, line: openMarker.line });
+            const attrs = {};
+            for (const m of open[2].matchAll(ATTR_RE))
+                attrs[m[1]] = m[2];
+            openMarker = {
+                kind: open[1],
+                id: attrs[open[1] === 'fill' ? 'slot' : 'section'] ?? '',
+                source: attrs.source,
+                line: lineNo,
+            };
+            continue;
+        }
+        const close = line.match(MARKER_CLOSE_RE);
+        if (close && openMarker && close[1] === openMarker.kind) {
+            const content = lines.slice(openMarker.line, lineNo - 1).join('\n');
+            if (openMarker.kind === 'fill') {
+                slots.push({ id: openMarker.id, startLine: openMarker.line, endLine: lineNo, content });
+            }
+            else {
+                generated.push({
+                    id: openMarker.id,
+                    source: openMarker.source,
+                    startLine: openMarker.line,
+                    endLine: lineNo,
+                    content,
+                });
+            }
+            openMarker = null;
+            continue;
+        }
+        const headingMatch = line.match(HEADING_RE);
+        if (headingMatch) {
+            headings.push({
+                depth: headingMatch[1].length,
+                text: headingMatch[2],
+                slug: slugify(headingMatch[2]),
+                line: lineNo,
+            });
+            // Headings can hold links too — fall through.
+        }
+        const refDef = line.match(REF_DEF_RE);
+        if (refDef) {
+            refDefs.set(refDef[1].toLowerCase(), refDef[2]);
+            continue;
+        }
+        const masked = maskInlineCode(line);
+        for (const m of masked.matchAll(WIKILINK_RE)) {
+            wikilinks.push({ target: m[1], line: lineNo });
+        }
+        for (const m of masked.matchAll(INLINE_LINK_RE)) {
+            links.push({ isImage: m[1] === '!', text: m[2], target: m[3], line: lineNo });
+        }
+        // Reference-style uses resolve after all definitions are collected.
+        const noInline = masked.replace(INLINE_LINK_RE, (s) => ' '.repeat(s.length));
+        for (const m of noInline.matchAll(REF_USE_RE)) {
+            refUses.push({
+                isImage: m[1] === '!',
+                text: m[2],
+                label: (m[3] || m[2]).toLowerCase(),
+                line: lineNo,
+            });
+        }
+    }
+    if (openFence) {
+        fences.push({ startLine: openFence.startLine, endLine: lines.length, lang: openFence.lang });
+    }
+    if (openMarker)
+        unclosedMarkers.push({ kind: openMarker.kind, line: openMarker.line });
+    for (const use of refUses) {
+        const target = refDefs.get(use.label);
+        if (target) {
+            links.push({ isImage: use.isImage, text: use.text, target, line: use.line });
+        }
+    }
+    return {
+        raw,
+        frontmatterRaw,
+        frontmatter,
+        ...(frontmatterError !== undefined ? { frontmatterError } : {}),
+        bodyStartLine,
+        headings,
+        links,
+        wikilinks,
+        fences,
+        slots,
+        generated,
+        unclosedMarkers,
+    };
+}
+/** The section under the heading whose slug or text matches (case-insensitive). */
+export function sectionSlice(doc, nameOrSlug) {
+    const want = nameOrSlug.toLowerCase();
+    const idx = doc.headings.findIndex((h) => h.slug === slugify(nameOrSlug) || h.text.toLowerCase() === want);
+    if (idx === -1)
+        return null;
+    const heading = doc.headings[idx];
+    const next = doc.headings.slice(idx + 1).find((h) => h.depth <= heading.depth);
+    const lines = doc.raw.split('\n');
+    const endLine = next ? next.line - 1 : lines.length;
+    return {
+        heading,
+        startLine: heading.line,
+        endLine,
+        text: lines.slice(heading.line - 1, endLine).join('\n'),
+    };
+}
+// ── Building (docs correct by construction) ──────────────────────────────────
+/** Frontmatter key order — spec-reserved fields first, extras after. */
+const FM_KEY_ORDER = [
+    'okf_version',
+    'type',
+    'title',
+    'description',
+    'resource',
+    'tags',
+    'status',
+    'stale_after',
+    'generated',
+    'verified',
+    'sources',
+];
+export function emitFrontmatter(fm) {
+    const ordered = {};
+    for (const key of FM_KEY_ORDER) {
+        if (fm[key] !== undefined)
+            ordered[key] = fm[key];
+    }
+    for (const key of Object.keys(fm)) {
+        if (!(key in ordered) && fm[key] !== undefined)
+            ordered[key] = fm[key];
+    }
+    // lineWidth 0: never fold long descriptions into YAML continuation lines.
+    return `---\n${stringifyYaml(ordered, { lineWidth: 0 }).trimEnd()}\n---\n`;
+}
+export function emitDoc(fm, body) {
+    return `${emitFrontmatter(fm)}\n${body.trim()}\n`;
+}
+export function heading(depth, text) {
+    return `${'#'.repeat(Math.min(6, Math.max(1, depth)))} ${text}`;
+}
+export function mdLink(text, target) {
+    return `[${text}](${target})`;
+}
+function escapeCell(cell) {
+    return cell.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+export function table(headers, rows) {
+    const head = `| ${headers.map(escapeCell).join(' | ')} |`;
+    const rule = `|${headers.map(() => '---').join('|')}|`;
+    const body = rows.map((r) => `| ${r.map(escapeCell).join(' | ')} |`);
+    return [head, rule, ...body].join('\n');
+}
+export function bulletList(items) {
+    return items.map((i) => `- ${i}`).join('\n');
+}
+export function fillSlot(id, content, hint) {
+    const interior = content && content.trim() !== ''
+        ? content.trim()
+        : `${TODO_SENTINEL} ${hint ?? id}_`;
+    return `<!-- wiki:fill slot="${id}" -->\n${interior}\n<!-- /wiki:fill -->`;
+}
+export function generatedBlock(id, source, content) {
+    return `<!-- wiki:generated section="${id}" source="${source}" -->\n${content.trim()}\n<!-- /wiki:generated -->`;
+}
+// ── Surgical edits ───────────────────────────────────────────────────────────
+/** Splice `content` between a slot's markers. Null when the slot is absent. */
+export function setSlotContent(raw, slotId, content) {
+    const doc = parseDoc(raw);
+    const slot = doc.slots.find((s) => s.id === slotId);
+    if (!slot)
+        return null;
+    const lines = raw.split('\n');
+    return [
+        ...lines.slice(0, slot.startLine),
+        content.trim(),
+        ...lines.slice(slot.endLine - 1),
+    ].join('\n');
+}
+/** Splice `content` between a generated block's markers. Null when absent. */
+export function setGeneratedContent(raw, blockId, content) {
+    const doc = parseDoc(raw);
+    const block = doc.generated.find((b) => b.id === blockId);
+    if (!block)
+        return null;
+    const lines = raw.split('\n');
+    return [
+        ...lines.slice(0, block.startLine),
+        content.trim(),
+        ...lines.slice(block.endLine - 1),
+    ].join('\n');
+}
+/**
+ * Insert a log entry newest-first: after the preamble (everything before the
+ * first `## [` entry), before existing entries. log.md stays chronologically
+ * scannable from the top — the profile's reading order for recency.
+ */
+export function insertLogEntry(raw, entry) {
+    const lines = raw.split('\n');
+    let insertAt = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^## \[/.test(lines[i])) {
+            insertAt = i;
+            break;
+        }
+    }
+    const before = lines.slice(0, insertAt).join('\n').trimEnd();
+    const after = lines.slice(insertAt).join('\n').trim();
+    return `${before}\n\n${entry.trim()}\n${after ? `\n${after}` : ''}`;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * lib/wiki/pipeline.ts — the parts of a build every bundle shares.
+ *
+ * WHY this file exists:
+ *   A bundle's build script is supposed to be small and entirely about ONE
+ *   repo: which files are the truth, and what documents derive from them.
+ *   Everything around that is identical wherever the engine runs —
+ *   deriving the entity graph, merging the asserted relations, writing the
+ *   snapshot, linting it, reporting the census, and the document that
+ *   publishes the graph vocabulary. Those live here so a second and third
+ *   bundle cost a page of repo-specific mapping instead of a copied
+ *   pipeline that immediately starts to drift.
+ *
+ *   The repo-specific half arrives as an EntityLayer: nodes and edges the
+ *   caller extracted from its own truth. This module never guesses what a
+ *   repo contains.
+ */
+import { type EntityEdge, type EntityGraph, type EntityNode, type EntityStats, type GraphFinding } from './entities.ts';
+import type { DocSpec } from './builder.ts';
+export interface EntityLayer {
+    nodes: EntityNode[];
+    edges: EntityEdge[];
+    /** Things the extractor noticed but could not resolve (typos, dead names). */
+    warnings: string[];
+}
+export interface EntityPassResult {
+    graph: EntityGraph;
+    stats: EntityStats;
+    findings: GraphFinding[];
+    warnings: string[];
+    inferred: number;
+}
+/**
+ * Merge the derived layer with the asserted relations and (unless this is a
+ * lint-only run) refresh the snapshot the wiki tools read. The snapshot
+ * lives inside the bundle at `.graph/graph.json` — it travels with
+ * WIKI_ROOT, the vault walker ignores dot-directories, and a markdown-only
+ * export cannot ship it by accident.
+ */
+export declare function entityPass(options: {
+    wikiRoot: string;
+    layer: EntityLayer;
+    actor: string;
+    date: string;
+    write: boolean;
+}): EntityPassResult;
+export declare function reportEntityPass(pass: EntityPassResult, log?: (line: string) => void): void;
+export declare function graphErrorCount(pass: EntityPassResult): number;
+/**
+ * The graph's own reference page: what kinds of node exist, what the
+ * relations mean, and how many of each the bundle holds right now. Both
+ * tables are machine-owned, so the vocabulary in the document can never
+ * disagree with the vocabulary in the code. Prose around them belongs to
+ * whoever writes it.
+ */
+export declare function graphDocSpec(options: {
+    bundlePath: string;
+    title: string;
+    description: string;
+    stats: EntityStats;
+    sources: string[];
+    /** Prose written into the document the first time it is created. */
+    intro: string;
+    /** Prose appended after the tables on creation. */
+    outro: string;
+    tags?: string[];
+    /** Node kinds this bundle adds beyond the shared vocabulary, with glosses. */
+    extraKinds?: Record<string, string>;
+}): DocSpec;

package/dist/lib/wiki/pipeline.js

@@ -0,0 +1,119 @@
+/**
+ * lib/wiki/pipeline.ts — the parts of a build every bundle shares.
+ *
+ * WHY this file exists:
+ *   A bundle's build script is supposed to be small and entirely about ONE
+ *   repo: which files are the truth, and what documents derive from them.
+ *   Everything around that is identical wherever the engine runs —
+ *   deriving the entity graph, merging the asserted relations, writing the
+ *   snapshot, linting it, reporting the census, and the document that
+ *   publishes the graph vocabulary. Those live here so a second and third
+ *   bundle cost a page of repo-specific mapping instead of a copied
+ *   pipeline that immediately starts to drift.
+ *
+ *   The repo-specific half arrives as an EntityLayer: nodes and edges the
+ *   caller extracted from its own truth. This module never guesses what a
+ *   repo contains.
+ */
+import { buildEntityGraph, entityStats, lintEntityGraph, loadRelations, NODE_KINDS, relationEdges, RELATIONS, writeSnapshot, } from "./entities.js";
+import { table } from "./markdown.js";
+/**
+ * Merge the derived layer with the asserted relations and (unless this is a
+ * lint-only run) refresh the snapshot the wiki tools read. The snapshot
+ * lives inside the bundle at `.graph/graph.json` — it travels with
+ * WIKI_ROOT, the vault walker ignores dot-directories, and a markdown-only
+ * export cannot ship it by accident.
+ */
+export function entityPass(options) {
+    const relations = loadRelations(options.wikiRoot);
+    const graph = buildEntityGraph(options.layer.nodes, [
+        ...options.layer.edges,
+        ...relationEdges(relations.records),
+    ]);
+    if (options.write) {
+        writeSnapshot(options.wikiRoot, graph, { by: options.actor, at: options.date });
+    }
+    return {
+        graph,
+        stats: entityStats(graph),
+        findings: lintEntityGraph(graph),
+        warnings: [...options.layer.warnings, ...relations.issues],
+        inferred: relations.records.length,
+    };
+}
+export function reportEntityPass(pass, log = console.log) {
+    const kinds = Object.entries(pass.stats.byKind)
+        .sort((a, b) => b[1] - a[1])
+        .map(([kind, n]) => `${kind}(${n})`)
+        .join(', ');
+    log(`entities: ${pass.stats.nodes} nodes, ${pass.stats.edges} edges (${pass.stats.byTier.extracted} extracted, ${pass.stats.byTier.inferred} inferred), ${pass.stats.isolated} isolated`);
+    log(`  kinds: ${kinds}`);
+    for (const warning of pass.warnings)
+        log(`  warning: ${warning}`);
+    const errors = pass.findings.filter((f) => f.severity === 'error');
+    const others = pass.findings.filter((f) => f.severity !== 'error');
+    for (const finding of [...errors, ...others].slice(0, 12)) {
+        log(`  graph-${finding.severity}: ${finding.rule} — ${finding.message}`);
+    }
+    if (pass.findings.length > 12) {
+        log(`  …and ${pass.findings.length - 12} more graph finding(s)`);
+    }
+}
+export function graphErrorCount(pass) {
+    return pass.findings.filter((f) => f.severity === 'error').length;
+}
+// ── The document that publishes the vocabulary ───────────────────────────────
+/**
+ * The graph's own reference page: what kinds of node exist, what the
+ * relations mean, and how many of each the bundle holds right now. Both
+ * tables are machine-owned, so the vocabulary in the document can never
+ * disagree with the vocabulary in the code. Prose around them belongs to
+ * whoever writes it.
+ */
+export function graphDocSpec(options) {
+    const vocabulary = { ...NODE_KINDS, ...(options.extraKinds ?? {}) };
+    const kindRows = Object.entries(vocabulary)
+        .sort((a, b) => (options.stats.byKind[b[0]] ?? 0) - (options.stats.byKind[a[0]] ?? 0))
+        .map(([kind, gloss]) => [
+        `\`${kind}\``,
+        kind === 'doc' ? '`/dir/doc.md`' : `\`${kind}:<name>\``,
+        String(options.stats.byKind[kind] ?? 0),
+        gloss,
+    ]);
+    const relationRows = Object.entries(RELATIONS)
+        .sort((a, b) => a[1].tier.localeCompare(b[1].tier) ||
+        (options.stats.byRelation[b[0]] ?? 0) - (options.stats.byRelation[a[0]] ?? 0))
+        .map(([id, spec]) => [
+        `\`${id}\``,
+        spec.tier,
+        `A ${spec.phrase} B`,
+        String(options.stats.byRelation[id] ?? 0),
+        spec.gloss,
+    ]);
+    return {
+        bundlePath: options.bundlePath,
+        fm: {
+            type: 'meta',
+            title: options.title,
+            description: options.description,
+            tags: options.tags ?? ['meta', 'graph'],
+            sources: options.sources.map((resource) => ({ resource })),
+        },
+        body: [
+            { kind: 'prose', markdown: options.intro },
+            {
+                kind: 'generated',
+                id: 'node-kinds',
+                source: 'lib/wiki/entities.ts',
+                markdown: `## What the graph knows about\n\n${table(['Kind', 'Id form', 'Now', 'What it is'], kindRows)}\n\nA document keeps its bundle path as its identity, so the two namespaces cannot collide.`,
+            },
+            {
+                kind: 'generated',
+                id: 'relations',
+                source: 'lib/wiki/entities.ts',
+                markdown: `## The relation vocabulary\n\n${table(['Relation', 'Tier', 'Reads as', 'Now', 'Meaning'], relationRows)}`,
+            },
+            { kind: 'prose', markdown: options.outro },
+        ],
+    };
+}

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

@@ -0,0 +1,84 @@
+/**
+ * lib/wiki/vault.ts — load an OKF bundle from disk and resolve its links.
+ *
+ * WHY this file exists:
+ *   Every wiki operation (lint, graph, search, dive, garden) starts from the
+ *   same picture: all documents of one bundle, parsed, with frontmatter
+ *   validated against the profile and every link resolved to a
+ *   bundle-absolute path. This module builds that picture once, so the
+ *   layers above never touch the filesystem or path arithmetic themselves.
+ *
+ *   Identity: a document IS its bundle-absolute path ('/memory/schema.md') —
+ *   the OKF rule that "the file path is the concept's identity." All link
+ *   resolution normalises to that form.
+ *
+ *   The bundle root is configurable (WIKI_ROOT) so the same tooling serves
+ *   any OKF bundle — this repo's wiki/ is merely the default. Writes are
+ *   jailed to the bundle root: a resolved path escaping it is refused, since
+ *   garden instructions and MCP callers are untrusted input.
+ */
+import { type ConceptFrontmatter } from './format.ts';
+import { type ParsedDoc } from './markdown.ts';
+export type DocKind = 'concept' | 'index' | 'log';
+export interface WikiDoc {
+    /** Bundle-absolute identity, e.g. '/memory/schema.md'. */
+    bundlePath: string;
+    /** Absolute filesystem path. */
+    absPath: string;
+    kind: DocKind;
+    parsed: ParsedDoc;
+    /** Profile-validated frontmatter — null for reserved files or when invalid. */
+    fm: ConceptFrontmatter | null;
+    /** Validation issues (consumed by lint; empty when fm parsed clean). */
+    fmIssues: string[];
+    title: string;
+    wordCount: number;
+    isPrivate: boolean;
+}
+export interface Vault {
+    /** Absolute filesystem path of the bundle root. */
+    root: string;
+    /** Keyed by bundlePath. */
+    docs: Map<string, WikiDoc>;
+}
+export type ResolvedLink = {
+    kind: 'internal';
+    bundlePath: string;
+} | {
+    kind: 'external';
+} | {
+    kind: 'anchor';
+} | {
+    kind: 'escapes-bundle';
+};
+/**
+ * WIKI_ROOT env var wins; default is `<cwd>/wiki`. The default used to be
+ * derived from this module's location (lib/wiki/ → repo root), which is
+ * wrong the moment the engine ships as a package (node_modules/<pkg>/wiki
+ * exists for no one) — and every real caller either sets WIKI_ROOT or runs
+ * from the repo root via npm scripts, where cwd IS the repo root.
+ */
+export declare function resolveWikiRoot(): string;
+export declare function classifyDoc(bundlePath: string): DocKind;
+export declare function loadDoc(root: string, absPath: string): WikiDoc;
+/** Build a WikiDoc from raw text — also used to evaluate an unsaved draft. */
+export declare function makeWikiDoc(bundlePath: string, absPath: string, raw: string): WikiDoc;
+export declare function loadVault(root?: string): Vault;
+/**
+ * Resolve a link target as written to bundle-absolute form. Directory links
+ * ('/agents/' or '/agents') resolve to that directory's index.md — the OKF
+ * progressive-disclosure convention.
+ */
+export declare function resolveLinkTarget(fromBundlePath: string, target: string): ResolvedLink;
+/** Existing doc for an internal target, trying `/dir` → `/dir/index.md`. */
+export declare function lookupTarget(vault: Vault, bundlePath: string): WikiDoc | null;
+/**
+ * Absolute filesystem path for a bundle path, refusing anything that
+ * resolves outside the bundle root. Callers pass user/agent-supplied paths.
+ */
+export declare function jailedAbsPath(root: string, bundlePath: string): string;
+export declare function writeDocFile(root: string, bundlePath: string, raw: string): void;
+export declare function conceptDocs(vault: Vault): WikiDoc[];
+export declare function indexDocs(vault: Vault): WikiDoc[];
+export declare function docsInDirectory(vault: Vault, dirBundlePath: string): WikiDoc[];
+export declare function isReservedDoc(doc: WikiDoc): boolean;