melchizedek-agents 0.9.0

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

@@ -0,0 +1,132 @@
+/**
+ * lib/wiki/format.ts — the Open Knowledge Format (OKF) v0.2 profile.
+ *
+ * WHY this file exists:
+ *   The wiki is a directory of markdown "concept" documents with YAML
+ *   frontmatter, per the OKF v0.2 spec
+ *   (github.com/GoogleCloudPlatform/knowledge-catalog, okf/SPEC.md). The spec
+ *   is deliberately minimal — `type` is the only required key — so every
+ *   producer needs a PROFILE: which reserved fields it writes, which concept
+ *   types it recognises, and how actors are named. This file is that profile,
+ *   expressed as zod schemas so the same object validates frontmatter at
+ *   parse time and documents the format in one place.
+ *
+ *   Spec facts this module encodes (OKF v0.2):
+ *     - `type` is the only always-required frontmatter key (§4.1).
+ *     - `index.md` and `log.md` are RESERVED filenames, not concepts (§3.1);
+ *       reserved files are exempt from the `type` requirement (§11).
+ *     - Links are normal markdown links; bundle-absolute (`/dir/doc.md`)
+ *       is the recommended form (§6.1). Consumers MUST tolerate broken
+ *       links — but a producer should still lint them (lib/wiki/lint.ts).
+ *     - Trust/provenance family (§5): `generated {by, at}`, `verified`
+ *       (mapping or list), `sources[]`, `status: draft|stable|deprecated`
+ *       (absent = stable), `stale_after: YYYY-MM-DD`.
+ *     - Actor convention (§7): `<producer>/<version>` for agents,
+ *       `human:<id>` for persons, `process:<id>` for automated processes.
+ *       Trust tiers (§5.3) key off the `human:` prefix.
+ *     - `okf_version` may appear in the bundle-root index.md only (§12).
+ */
+import { z } from 'zod';
+/** OKF spec version this profile targets. Written to the root index.md. */
+export declare const OKF_VERSION = "0.2";
+/** Reserved filenames (§3.1) — never concept documents. */
+export declare const RESERVED_FILENAMES: readonly ["index.md", "log.md"];
+export declare function isReservedFilename(fileName: string): boolean;
+/**
+ * The subtree that never leaves this repo. Path-based visibility: a doc is
+ * private iff its bundle path starts with this prefix. The export pipeline
+ * copies the bundle WITHOUT this subtree, and lint's closure rule forbids
+ * docs outside it from linking into it — so the published bundle is
+ * link-closed by construction (see wiki/decisions/0003.)
+ */
+export declare const PRIVATE_PREFIX = "/private/";
+export declare function isPrivatePath(bundlePath: string): boolean;
+/**
+ * Recommended `type` values for this bundle. OKF requires consumers to
+ * tolerate unknown types (§11), so this list steers authors without
+ * rejecting anything — lint reports an unknown type as INFO, not an error.
+ */
+export declare const CONCEPT_TYPES: readonly ["overview", "subsystem", "syndicate", "tool", "model-provider", "schema", "protocol", "runbook", "guide", "decision", "doctrine", "reference", "meta"];
+export type ConceptType = (typeof CONCEPT_TYPES)[number];
+/** `human:<id>` | `process:<id>` | `<producer>/<version>` */
+export declare const actorSchema: z.ZodString;
+/** Actor id for structural (non-LLM) generation by this module. */
+export declare const BUILD_ACTOR = "process:wiki-build";
+/** Actor id for LLM gap-fill: the producer is the framework, version the model. */
+export declare function llmActor(modelId: string): string;
+/** Trust tiers derived from `verified` (§5.3). */
+export type TrustTier = 'unverified' | 'machine-confirmed' | 'human-reviewed';
+export declare const generatedSchema: z.ZodObject<{
+    by: z.ZodString;
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const verifiedEntrySchema: z.ZodObject<{
+    by: z.ZodString;
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const sourceSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    resource: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    last_modified: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * Concept frontmatter. `.loose*` throughout: OKF conformance forbids
+ * rejecting unknown keys (§11), so extra fields pass through untouched.
+ */
+export declare const conceptFrontmatterSchema: z.ZodObject<{
+    type: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        stable: "stable";
+        deprecated: "deprecated";
+    }>>;
+    stale_after: z.ZodOptional<z.ZodString>;
+    generated: z.ZodOptional<z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    verified: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodArray<z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>]>>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        resource: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        last_modified: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type ConceptFrontmatter = z.infer<typeof conceptFrontmatterSchema>;
+/** Root index.md frontmatter — the only place `okf_version` may live (§12). */
+export declare const rootIndexFrontmatterSchema: z.ZodObject<{
+    okf_version: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    generated: z.ZodOptional<z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** Normalise `verified` to a list (§5.2) — bare mapping = one-element list. */
+export declare function verifiedEntries(fm: ConceptFrontmatter): Array<z.infer<typeof verifiedEntrySchema>>;
+/** Trust tier per §5.3: any `human:` verifier ⇒ human-reviewed. */
+export declare function trustTier(fm: ConceptFrontmatter): TrustTier;
+/** Effective lifecycle status — absent means stable (§5.4). */
+export declare function effectiveStatus(fm: ConceptFrontmatter): 'draft' | 'stable' | 'deprecated';
+/** Stale when today >= stale_after (§5.5). `today` is YYYY-MM-DD. */
+export declare function isStale(fm: ConceptFrontmatter, today: string): boolean;
+/** Operations recorded in log.md, one `## [date] op | summary` entry each. */
+export declare const LOG_OPS: readonly ["init", "build", "fill", "garden", "ingest", "lint", "relate"];
+export type LogOp = (typeof LOG_OPS)[number];
+export declare const LOG_ENTRY_RE: RegExp;
+export declare function formatLogEntry(date: string, op: LogOp, summary: string, detail?: string): string;

package/dist/lib/wiki/format.js

@@ -0,0 +1,177 @@
+/**
+ * lib/wiki/format.ts — the Open Knowledge Format (OKF) v0.2 profile.
+ *
+ * WHY this file exists:
+ *   The wiki is a directory of markdown "concept" documents with YAML
+ *   frontmatter, per the OKF v0.2 spec
+ *   (github.com/GoogleCloudPlatform/knowledge-catalog, okf/SPEC.md). The spec
+ *   is deliberately minimal — `type` is the only required key — so every
+ *   producer needs a PROFILE: which reserved fields it writes, which concept
+ *   types it recognises, and how actors are named. This file is that profile,
+ *   expressed as zod schemas so the same object validates frontmatter at
+ *   parse time and documents the format in one place.
+ *
+ *   Spec facts this module encodes (OKF v0.2):
+ *     - `type` is the only always-required frontmatter key (§4.1).
+ *     - `index.md` and `log.md` are RESERVED filenames, not concepts (§3.1);
+ *       reserved files are exempt from the `type` requirement (§11).
+ *     - Links are normal markdown links; bundle-absolute (`/dir/doc.md`)
+ *       is the recommended form (§6.1). Consumers MUST tolerate broken
+ *       links — but a producer should still lint them (lib/wiki/lint.ts).
+ *     - Trust/provenance family (§5): `generated {by, at}`, `verified`
+ *       (mapping or list), `sources[]`, `status: draft|stable|deprecated`
+ *       (absent = stable), `stale_after: YYYY-MM-DD`.
+ *     - Actor convention (§7): `<producer>/<version>` for agents,
+ *       `human:<id>` for persons, `process:<id>` for automated processes.
+ *       Trust tiers (§5.3) key off the `human:` prefix.
+ *     - `okf_version` may appear in the bundle-root index.md only (§12).
+ */
+import { z } from 'zod';
+// ── Spec constants ───────────────────────────────────────────────────────────
+/** OKF spec version this profile targets. Written to the root index.md. */
+export const OKF_VERSION = '0.2';
+/** Reserved filenames (§3.1) — never concept documents. */
+export const RESERVED_FILENAMES = ['index.md', 'log.md'];
+export function isReservedFilename(fileName) {
+    return RESERVED_FILENAMES.includes(fileName);
+}
+/**
+ * The subtree that never leaves this repo. Path-based visibility: a doc is
+ * private iff its bundle path starts with this prefix. The export pipeline
+ * copies the bundle WITHOUT this subtree, and lint's closure rule forbids
+ * docs outside it from linking into it — so the published bundle is
+ * link-closed by construction (see wiki/decisions/0003.)
+ */
+export const PRIVATE_PREFIX = '/private/';
+export function isPrivatePath(bundlePath) {
+    return bundlePath.startsWith(PRIVATE_PREFIX);
+}
+// ── Concept types (profile vocabulary) ───────────────────────────────────────
+/**
+ * Recommended `type` values for this bundle. OKF requires consumers to
+ * tolerate unknown types (§11), so this list steers authors without
+ * rejecting anything — lint reports an unknown type as INFO, not an error.
+ */
+export const CONCEPT_TYPES = [
+    'overview', // orientation docs: what a thing is, why it exists
+    'subsystem', // a named part of the codebase and its responsibilities
+    'syndicate', // one agent-team YAML, documented
+    'tool', // a tool contract or tool family
+    'model-provider', // an LLM provider adapter and its dialect quirks
+    'schema', // a database or wire schema, canonically stated
+    'protocol', // an interop surface: MCP, A2A
+    'runbook', // step-by-step operational procedure
+    'guide', // task-oriented how-to
+    'decision', // one architecture decision record (ADR)
+    'doctrine', // standing rules that constrain future work
+    'reference', // pointer collection to external resources
+    'meta', // docs about the wiki itself
+];
+// ── Actor convention (§7) ────────────────────────────────────────────────────
+/** `human:<id>` | `process:<id>` | `<producer>/<version>` */
+export const actorSchema = z
+    .string()
+    .min(1)
+    .refine((a) => a.startsWith('human:') ? a.length > 'human:'.length
+    : a.startsWith('process:') ? a.length > 'process:'.length
+        : a.includes('/'), {
+    message: 'actor must be "human:<id>", "process:<id>", or "<producer>/<version>"',
+});
+/** Actor id for structural (non-LLM) generation by this module. */
+export const BUILD_ACTOR = 'process:wiki-build';
+/** Actor id for LLM gap-fill: the producer is the framework, version the model. */
+export function llmActor(modelId) {
+    return `melchizedek/${modelId}`;
+}
+// ── Frontmatter schemas ──────────────────────────────────────────────────────
+const isoDateSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'expected YYYY-MM-DD');
+export const generatedSchema = z.looseObject({
+    by: actorSchema,
+    /** Last meaningful content change (ISO 8601). */
+    at: z.string().optional(),
+});
+export const verifiedEntrySchema = z.looseObject({
+    by: actorSchema,
+    at: z.string().optional(),
+});
+export const sourceSchema = z.looseObject({
+    /** Stable key for citing this source from the body. */
+    id: z.string().optional(),
+    /** URL or bundle path of the material this concept derives from. */
+    resource: z.string().min(1),
+    title: z.string().optional(),
+    author: z.string().optional(),
+    last_modified: isoDateSchema.optional(),
+});
+/**
+ * Concept frontmatter. `.loose*` throughout: OKF conformance forbids
+ * rejecting unknown keys (§11), so extra fields pass through untouched.
+ */
+export const conceptFrontmatterSchema = z.looseObject({
+    /** The ONLY required key (§4.1). */
+    type: z.string().min(1, 'OKF requires a non-empty `type`'),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    /** URL of the live resource this concept describes. */
+    resource: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    /** Absent status means `stable` (§5.4). */
+    status: z.enum(['draft', 'stable', 'deprecated']).optional(),
+    stale_after: isoDateSchema.optional(),
+    generated: generatedSchema.optional(),
+    /** Bare mapping MUST be treated as a one-element list (§5.2). */
+    verified: z
+        .union([verifiedEntrySchema, z.array(verifiedEntrySchema)])
+        .optional(),
+    sources: z.array(sourceSchema).optional(),
+});
+/** Root index.md frontmatter — the only place `okf_version` may live (§12). */
+export const rootIndexFrontmatterSchema = z.looseObject({
+    okf_version: z.string().optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    generated: generatedSchema.optional(),
+});
+// ── Derivations ──────────────────────────────────────────────────────────────
+/** Normalise `verified` to a list (§5.2) — bare mapping = one-element list. */
+export function verifiedEntries(fm) {
+    if (!fm.verified)
+        return [];
+    return Array.isArray(fm.verified) ? fm.verified : [fm.verified];
+}
+/** Trust tier per §5.3: any `human:` verifier ⇒ human-reviewed. */
+export function trustTier(fm) {
+    const entries = verifiedEntries(fm);
+    if (entries.length === 0)
+        return 'unverified';
+    return entries.some((v) => v.by.startsWith('human:'))
+        ? 'human-reviewed'
+        : 'machine-confirmed';
+}
+/** Effective lifecycle status — absent means stable (§5.4). */
+export function effectiveStatus(fm) {
+    return fm.status ?? 'stable';
+}
+/** Stale when today >= stale_after (§5.5). `today` is YYYY-MM-DD. */
+export function isStale(fm, today) {
+    return fm.stale_after !== undefined && today >= fm.stale_after;
+}
+// ── Log format (reserved log.md, §9) ─────────────────────────────────────────
+/** Operations recorded in log.md, one `## [date] op | summary` entry each. */
+export const LOG_OPS = [
+    'init',
+    'build',
+    'fill',
+    'garden',
+    'ingest',
+    'lint',
+    /** One asserted relation added to the entity graph (lib/wiki/entities.ts). */
+    'relate',
+];
+export const LOG_ENTRY_RE = /^## \[(\d{4}-\d{2}-\d{2})\] ([a-z]+) \| (.+)$/;
+export function formatLogEntry(date, op, summary, detail) {
+    const head = `## [${date}] ${op} | ${summary}`;
+    return detail ? `${head}\n\n${detail.trim()}\n` : `${head}\n`;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * lib/wiki/graph.ts — the knowledge graph derived from links.
+ *
+ * WHY this file exists:
+ *   OKF's insight is that a directory of markdown files with links IS a
+ *   graph — no database required. This module makes that graph explicit:
+ *   nodes are documents, edges are resolved markdown links between them.
+ *   Everything downstream that "navigates" (neighbors, repo-dive reading
+ *   paths, orphan detection in lint, the exported graph.json) traverses the
+ *   structure built here.
+ *
+ *   The graph is always DERIVED, never stored: rebuild-from-files is cheap
+ *   at this scale and can't drift from the documents the way a cached
+ *   index could. `wiki:build --graph` merely snapshots this derivation for
+ *   visualisation.
+ */
+import { type TrustTier } from './format.ts';
+import { type Vault, type WikiDoc } from './vault.ts';
+export interface GraphNode {
+    path: string;
+    title: string;
+    /** OKF concept type; index/log files carry their reserved kind instead. */
+    type: string;
+    kind: WikiDoc['kind'];
+    status: 'draft' | 'stable' | 'deprecated';
+    trust: TrustTier;
+    isPrivate: boolean;
+    wordCount: number;
+    tags: string[];
+}
+export interface GraphEdge {
+    /** Bundle path of the linking document. */
+    source: string;
+    /** Normalised bundle path of the target (which may not exist). */
+    target: string;
+    /** False when the target is not a document in the bundle. */
+    resolved: boolean;
+    /** Anchor text of the link. */
+    text: string;
+    line: number;
+}
+export interface WikiGraph {
+    nodes: Map<string, GraphNode>;
+    edges: GraphEdge[];
+    outbound: Map<string, GraphEdge[]>;
+    inbound: Map<string, GraphEdge[]>;
+}
+export declare function buildGraph(vault: Vault): WikiGraph;
+/**
+ * Concepts nothing points to: no inbound link from any OTHER document,
+ * including index listings. The bundle root index and log are exempt.
+ */
+export declare function orphanConcepts(graph: WikiGraph): GraphNode[];
+export declare function brokenEdges(graph: WikiGraph): GraphEdge[];
+export interface Neighbor {
+    node: GraphNode;
+    /** Link hops from the origin. */
+    distance: number;
+    /** How we got here: the linking document. */
+    via: string;
+    direction: 'out' | 'in';
+}
+/** Breadth-first neighborhood of a document along resolved edges. */
+export declare function neighborhood(graph: WikiGraph, originPath: string, depth?: number, direction?: 'out' | 'in' | 'both'): Neighbor[];
+export interface GraphStats {
+    documents: number;
+    concepts: number;
+    edges: number;
+    brokenLinks: number;
+    orphans: number;
+    byType: Record<string, number>;
+    totalWords: number;
+}
+export declare function graphStats(graph: WikiGraph): GraphStats;
+/** JSON-serialisable snapshot (what `wiki:build --graph` writes). */
+export declare function graphToJson(graph: WikiGraph): {
+    stats: GraphStats;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};

package/dist/lib/wiki/graph.js

@@ -0,0 +1,147 @@
+/**
+ * lib/wiki/graph.ts — the knowledge graph derived from links.
+ *
+ * WHY this file exists:
+ *   OKF's insight is that a directory of markdown files with links IS a
+ *   graph — no database required. This module makes that graph explicit:
+ *   nodes are documents, edges are resolved markdown links between them.
+ *   Everything downstream that "navigates" (neighbors, repo-dive reading
+ *   paths, orphan detection in lint, the exported graph.json) traverses the
+ *   structure built here.
+ *
+ *   The graph is always DERIVED, never stored: rebuild-from-files is cheap
+ *   at this scale and can't drift from the documents the way a cached
+ *   index could. `wiki:build --graph` merely snapshots this derivation for
+ *   visualisation.
+ */
+import { effectiveStatus, trustTier } from "./format.js";
+import { lookupTarget, resolveLinkTarget, } from "./vault.js";
+// ── Construction ─────────────────────────────────────────────────────────────
+export function buildGraph(vault) {
+    const nodes = new Map();
+    const edges = [];
+    const outbound = new Map();
+    const inbound = new Map();
+    for (const doc of vault.docs.values()) {
+        nodes.set(doc.bundlePath, {
+            path: doc.bundlePath,
+            title: doc.title,
+            type: doc.kind === 'concept'
+                ? (doc.parsed.frontmatter?.type ?? 'unknown')
+                : doc.kind,
+            kind: doc.kind,
+            status: doc.fm ? effectiveStatus(doc.fm) : 'stable',
+            trust: doc.fm ? trustTier(doc.fm) : 'unverified',
+            isPrivate: doc.isPrivate,
+            wordCount: doc.wordCount,
+            tags: doc.fm?.tags ?? [],
+        });
+    }
+    for (const doc of vault.docs.values()) {
+        for (const link of doc.parsed.links) {
+            if (link.isImage)
+                continue;
+            const resolved = resolveLinkTarget(doc.bundlePath, link.target);
+            if (resolved.kind !== 'internal')
+                continue;
+            const targetDoc = lookupTarget(vault, resolved.bundlePath);
+            const edge = {
+                source: doc.bundlePath,
+                target: targetDoc ? targetDoc.bundlePath : resolved.bundlePath,
+                resolved: targetDoc !== null,
+                text: link.text,
+                line: link.line,
+            };
+            edges.push(edge);
+            const out = outbound.get(edge.source) ?? [];
+            out.push(edge);
+            outbound.set(edge.source, out);
+            if (edge.resolved) {
+                const inn = inbound.get(edge.target) ?? [];
+                inn.push(edge);
+                inbound.set(edge.target, inn);
+            }
+        }
+    }
+    return { nodes, edges, outbound, inbound };
+}
+// ── Queries ──────────────────────────────────────────────────────────────────
+/**
+ * Concepts nothing points to: no inbound link from any OTHER document,
+ * including index listings. The bundle root index and log are exempt.
+ */
+export function orphanConcepts(graph) {
+    return [...graph.nodes.values()].filter((node) => {
+        if (node.kind !== 'concept')
+            return false;
+        const inn = graph.inbound.get(node.path) ?? [];
+        return !inn.some((e) => e.source !== node.path);
+    });
+}
+export function brokenEdges(graph) {
+    return graph.edges.filter((e) => !e.resolved);
+}
+/** Breadth-first neighborhood of a document along resolved edges. */
+export function neighborhood(graph, originPath, depth = 1, direction = 'both') {
+    const seen = new Set([originPath]);
+    const result = [];
+    let frontier = [originPath];
+    for (let d = 1; d <= depth; d++) {
+        const next = [];
+        for (const path of frontier) {
+            const candidates = [];
+            if (direction !== 'in') {
+                for (const e of graph.outbound.get(path) ?? []) {
+                    if (e.resolved)
+                        candidates.push({ target: e.target, dir: 'out' });
+                }
+            }
+            if (direction !== 'out') {
+                for (const e of graph.inbound.get(path) ?? []) {
+                    candidates.push({ target: e.source, dir: 'in' });
+                }
+            }
+            for (const c of candidates) {
+                if (seen.has(c.target))
+                    continue;
+                seen.add(c.target);
+                const node = graph.nodes.get(c.target);
+                if (!node)
+                    continue;
+                result.push({ node, distance: d, via: path, direction: c.dir });
+                next.push(c.target);
+            }
+        }
+        frontier = next;
+    }
+    return result;
+}
+export function graphStats(graph) {
+    const byType = {};
+    let totalWords = 0;
+    let concepts = 0;
+    for (const node of graph.nodes.values()) {
+        totalWords += node.wordCount;
+        if (node.kind !== 'concept')
+            continue;
+        concepts++;
+        byType[node.type] = (byType[node.type] ?? 0) + 1;
+    }
+    return {
+        documents: graph.nodes.size,
+        concepts,
+        edges: graph.edges.length,
+        brokenLinks: brokenEdges(graph).length,
+        orphans: orphanConcepts(graph).length,
+        byType,
+        totalWords,
+    };
+}
+/** JSON-serialisable snapshot (what `wiki:build --graph` writes). */
+export function graphToJson(graph) {
+    return {
+        stats: graphStats(graph),
+        nodes: [...graph.nodes.values()],
+        edges: graph.edges,
+    };
+}

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

@@ -0,0 +1,58 @@
+/**
+ * lib/wiki/lint.ts — producer-side health checks for the bundle.
+ *
+ * WHY this file exists:
+ *   OKF consumers MUST tolerate broken links, missing indexes, unknown
+ *   fields — the spec is forgiving on purpose. A PRODUCER that leans on
+ *   that forgiveness rots: links dangle, pages orphan, indexes lag their
+ *   directories. This is Karpathy's "lint" operation from the LLM-wiki
+ *   pattern, run as code instead of vibes. It is also the gate every write
+ *   passes through: `wiki_save` refuses drafts whose errors would degrade
+ *   the bundle.
+ *
+ *   Severity doctrine:
+ *     error   — violates OKF conformance or the profile's hard rules;
+ *               blocks wiki_save and fails `wiki:build --check`.
+ *     warning — the bundle works but is decaying (broken link, orphan,
+ *               stale doc, index gap). Surfaced, never blocking.
+ *     info    — style guidance (relative links, unknown type).
+ *
+ *   The private-closure rule is the publishing invariant: documents outside
+ *   /private/ must never link into it, so exporting the bundle minus the
+ *   private subtree can never produce a dangling reference the producer
+ *   didn't choose. Extra `forbiddenPatterns` (names that must not appear in
+ *   public docs) are supplied BY THE CALLER — this public module does not
+ *   itself know any private vocabulary.
+ */
+import { type Vault, type WikiDoc } from './vault.ts';
+export type LintSeverity = 'error' | 'warning' | 'info';
+export interface LintFinding {
+    severity: LintSeverity;
+    /** Stable rule id, e.g. 'frontmatter', 'broken-link', 'index-coverage'. */
+    rule: string;
+    docPath: string;
+    line?: number;
+    message: string;
+}
+export interface LintReport {
+    findings: LintFinding[];
+    errors: number;
+    warnings: number;
+    ok: boolean;
+}
+export interface LintOptions {
+    /** YYYY-MM-DD used for staleness; defaults to the current date. */
+    today?: string;
+    /**
+     * Patterns that must not appear in PUBLIC documents (names of private
+     * systems, etc.). Checked against each public doc's full text.
+     */
+    forbiddenPatterns?: RegExp[];
+}
+/**
+ * Rules that need only the document itself (+ the vault for link targets).
+ * Used both by lintVault and by the wiki_save gate on unsaved drafts.
+ */
+export declare function lintDoc(vault: Vault, doc: WikiDoc, options?: LintOptions): LintFinding[];
+export declare function lintVault(vault: Vault, options?: LintOptions): LintReport;
+export declare function formatLintReport(result: LintReport): string;