melchizedek-agents 0.9.0

package/dist/lib/tools/xSearchTool.d.ts

@@ -0,0 +1,61 @@
+/**
+ * lib/tools/xSearchTool.ts — xAI X (Twitter) search, sentinel-style.
+ *
+ * WHY this file exists:
+ *   xAI's Agent Tools API exposes `x_search` — server-side live search over
+ *   X posts — as a first-class tool alongside `web_search` (verified live
+ *   against api.x.ai/v1/responses, 2026-07-24). It is the one search
+ *   capability no other provider offers, and the reason to route a
+ *   news/social agent to a grok-* model at all.
+ *
+ * HOW IT WORKS (mirrors webSearchTool.ts exactly):
+ *   Declaring `x_search` in an agent's YAML tools list self-registers a
+ *   sentinel in llmRequest.toolsDict. _getDeclaration() returns undefined so
+ *   it is never sent as a client-side function tool; the GptLlm/GrokLlm
+ *   request builder calls wantsXSearch(llmRequest) and appends
+ *   { type: 'x_search' } to the provider tools.
+ *
+ * SCOPE: xAI-only. Declare it ONLY on grok-* agents — other Responses-API
+ *   providers (OpenAI) reject the unknown tool type with a 400, and Gemini/
+ *   Anthropic adapters ignore the sentinel entirely (the tool degrades to a
+ *   no-op there rather than throwing, same non-throwing routing contract as
+ *   web_search).
+ *
+ * WHICH CONSTRAINTS: xAI accepts server-side search constraints on the tool
+ *   object itself (verified against docs.x.ai/developers/tools/x-search,
+ *   2026-08-02): from_date/to_date (YYYY-MM-DD) and allowed_x_handles/
+ *   excluded_x_handles (≤20 each, mutually exclusive). They come from the
+ *   environment, not YAML — XAI_X_SEARCH_FROM_DATE, XAI_X_SEARCH_TO_DATE,
+ *   XAI_X_SEARCH_ALLOWED_HANDLES, XAI_X_SEARCH_EXCLUDED_HANDLES (handle
+ *   lists comma-separated, leading @ tolerated) — the XAI_COLLECTION_IDS
+ *   doctrine: constraints are deployment configuration, the YAML stays
+ *   shareable. Misconfiguration degrades with a warning, never fatally:
+ *   malformed dates are dropped, oversize handle lists truncate, and when
+ *   both lists are set the allowlist wins.
+ */
+import { BaseTool } from '@google/adk';
+import type { LlmRequest } from '@google/adk';
+export declare const X_SEARCH_TOOL_NAME = "x_search";
+export declare class XSearchTool extends BaseTool {
+    constructor();
+    /** Never a client-side function tool — xAI runs the search server-side. */
+    _getDeclaration(): undefined;
+    /** Server-side tool: nothing to execute locally. */
+    runAsync(): Promise<unknown>;
+    processLlmRequest({ llmRequest }: {
+        llmRequest: LlmRequest;
+    }): Promise<void>;
+}
+/** Shared instance, mirroring WEB_SEARCH. */
+export declare const X_SEARCH: XSearchTool;
+/** True when the agent requested X search (xAI sentinel path). */
+export declare function wantsXSearch(llmRequest: LlmRequest): boolean;
+/** Sentinel test used by the request builder to skip function-tool emission. */
+export declare function isXSearchSentinel(tool: unknown): boolean;
+/**
+ * Optional server-side constraints for the x_search tool, read from the
+ * environment at request-build time (see WHICH CONSTRAINTS above). With
+ * nothing configured this returns {} and the tool ships bare, exactly as
+ * it always has.
+ */
+export declare function xSearchParamsFromEnv(): Record<string, unknown>;

package/dist/lib/tools/xSearchTool.js

@@ -0,0 +1,125 @@
+/**
+ * lib/tools/xSearchTool.ts — xAI X (Twitter) search, sentinel-style.
+ *
+ * WHY this file exists:
+ *   xAI's Agent Tools API exposes `x_search` — server-side live search over
+ *   X posts — as a first-class tool alongside `web_search` (verified live
+ *   against api.x.ai/v1/responses, 2026-07-24). It is the one search
+ *   capability no other provider offers, and the reason to route a
+ *   news/social agent to a grok-* model at all.
+ *
+ * HOW IT WORKS (mirrors webSearchTool.ts exactly):
+ *   Declaring `x_search` in an agent's YAML tools list self-registers a
+ *   sentinel in llmRequest.toolsDict. _getDeclaration() returns undefined so
+ *   it is never sent as a client-side function tool; the GptLlm/GrokLlm
+ *   request builder calls wantsXSearch(llmRequest) and appends
+ *   { type: 'x_search' } to the provider tools.
+ *
+ * SCOPE: xAI-only. Declare it ONLY on grok-* agents — other Responses-API
+ *   providers (OpenAI) reject the unknown tool type with a 400, and Gemini/
+ *   Anthropic adapters ignore the sentinel entirely (the tool degrades to a
+ *   no-op there rather than throwing, same non-throwing routing contract as
+ *   web_search).
+ *
+ * WHICH CONSTRAINTS: xAI accepts server-side search constraints on the tool
+ *   object itself (verified against docs.x.ai/developers/tools/x-search,
+ *   2026-08-02): from_date/to_date (YYYY-MM-DD) and allowed_x_handles/
+ *   excluded_x_handles (≤20 each, mutually exclusive). They come from the
+ *   environment, not YAML — XAI_X_SEARCH_FROM_DATE, XAI_X_SEARCH_TO_DATE,
+ *   XAI_X_SEARCH_ALLOWED_HANDLES, XAI_X_SEARCH_EXCLUDED_HANDLES (handle
+ *   lists comma-separated, leading @ tolerated) — the XAI_COLLECTION_IDS
+ *   doctrine: constraints are deployment configuration, the YAML stays
+ *   shareable. Misconfiguration degrades with a warning, never fatally:
+ *   malformed dates are dropped, oversize handle lists truncate, and when
+ *   both lists are set the allowlist wins.
+ */
+import { BaseTool } from '@google/adk';
+import { providerForModel } from "../models/providerMap.js";
+export const X_SEARCH_TOOL_NAME = 'x_search';
+export class XSearchTool extends BaseTool {
+    constructor() {
+        super({
+            name: X_SEARCH_TOOL_NAME,
+            description: 'Live search over X (Twitter) posts via xAI Agent Tools — ' +
+                'grok-* models only; a no-op sentinel on every other provider.',
+        });
+    }
+    /** Never a client-side function tool — xAI runs the search server-side. */
+    _getDeclaration() {
+        return undefined;
+    }
+    /** Server-side tool: nothing to execute locally. */
+    async runAsync() {
+        return Promise.resolve();
+    }
+    async processLlmRequest({ llmRequest }) {
+        if (!llmRequest.model)
+            return;
+        if (providerForModel(llmRequest.model) !== 'xai')
+            return; // no-op elsewhere
+        llmRequest.toolsDict[X_SEARCH_TOOL_NAME] = this;
+    }
+}
+/** Shared instance, mirroring WEB_SEARCH. */
+export const X_SEARCH = new XSearchTool();
+/** True when the agent requested X search (xAI sentinel path). */
+export function wantsXSearch(llmRequest) {
+    return llmRequest.toolsDict?.[X_SEARCH_TOOL_NAME] instanceof XSearchTool;
+}
+/** Sentinel test used by the request builder to skip function-tool emission. */
+export function isXSearchSentinel(tool) {
+    return tool instanceof XSearchTool;
+}
+/** xAI's documented ceiling on allowed_x_handles / excluded_x_handles. */
+const X_SEARCH_MAX_HANDLES = 20;
+/** ISO date (YYYY-MM-DD) from an env var; malformed values warn and drop. */
+function isoDateFromEnv(name) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return undefined;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        console.warn(`[x_search] ${name}="${raw}" is not YYYY-MM-DD — ignored.`);
+        return undefined;
+    }
+    return raw;
+}
+/** Comma-separated handles from an env var; trimmed, @-stripped, capped. */
+function handlesFromEnv(name) {
+    const handles = (process.env[name] ?? '')
+        .split(',')
+        .map((h) => h.trim().replace(/^@/, ''))
+        .filter(Boolean);
+    if (handles.length > X_SEARCH_MAX_HANDLES) {
+        console.warn(`[x_search] ${name} lists ${handles.length} handles — xAI caps the ` +
+            `list at ${X_SEARCH_MAX_HANDLES}; keeping the first ${X_SEARCH_MAX_HANDLES}.`);
+        return handles.slice(0, X_SEARCH_MAX_HANDLES);
+    }
+    return handles;
+}
+/**
+ * Optional server-side constraints for the x_search tool, read from the
+ * environment at request-build time (see WHICH CONSTRAINTS above). With
+ * nothing configured this returns {} and the tool ships bare, exactly as
+ * it always has.
+ */
+export function xSearchParamsFromEnv() {
+    const params = {};
+    const from = isoDateFromEnv('XAI_X_SEARCH_FROM_DATE');
+    const to = isoDateFromEnv('XAI_X_SEARCH_TO_DATE');
+    if (from)
+        params.from_date = from;
+    if (to)
+        params.to_date = to;
+    const allowed = handlesFromEnv('XAI_X_SEARCH_ALLOWED_HANDLES');
+    const excluded = handlesFromEnv('XAI_X_SEARCH_EXCLUDED_HANDLES');
+    if (allowed.length > 0 && excluded.length > 0) {
+        console.warn('[x_search] XAI_X_SEARCH_ALLOWED_HANDLES and _EXCLUDED_HANDLES are ' +
+            'mutually exclusive (xAI rejects both together) — keeping the ' +
+            'allowlist, dropping the exclusions.');
+    }
+    if (allowed.length > 0)
+        params.allowed_x_handles = allowed;
+    else if (excluded.length > 0)
+        params.excluded_x_handles = excluded;
+    return params;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * lib/wiki/agentRun.ts — one-shot agent execution for wiki operations.
+ *
+ * WHY this file exists:
+ *   Three wiki operations need a model in the loop — gap-fill (write the
+ *   prose a structural build can't), wiki_query (answer a question over the
+ *   bundle), wiki_garden (author or revise a document). Each is a single
+ *   agent run: build an ADK LlmAgent, hand it the wiki FunctionTools it
+ *   needs, stream one exchange, return the text. This helper is that idiom
+ *   (the same one scripts/demo_model_optionality.ts uses), shared so the
+ *   three call sites can't drift.
+ *
+ *   Model routing goes through lib/models/registry.ts, so the YAML-style
+ *   model string ('gemini-3.7-flash', 'claude-*', 'ollama/*'…) picks the
+ *   provider — wiki operations inherit the framework's full model
+ *   optionality. A missing provider key degrades to a clear error string;
+ *   nothing here throws for want of credentials.
+ */
+import type { FunctionTool } from '@google/adk';
+export interface WikiAgentRun {
+    name: string;
+    description: string;
+    model: string;
+    instruction: string;
+    userText: string;
+    tools?: FunctionTool[];
+    temperature?: number;
+    maxOutputTokens?: number;
+}
+export interface WikiAgentResult {
+    text: string;
+    error?: string;
+}
+/** True when the model's provider has credentials (Ollama needs none). */
+export declare function modelAvailable(model: string): {
+    ok: boolean;
+    reason?: string;
+};
+export declare function runWikiAgent(run: WikiAgentRun): Promise<WikiAgentResult>;

package/dist/lib/wiki/agentRun.js

@@ -0,0 +1,79 @@
+/**
+ * lib/wiki/agentRun.ts — one-shot agent execution for wiki operations.
+ *
+ * WHY this file exists:
+ *   Three wiki operations need a model in the loop — gap-fill (write the
+ *   prose a structural build can't), wiki_query (answer a question over the
+ *   bundle), wiki_garden (author or revise a document). Each is a single
+ *   agent run: build an ADK LlmAgent, hand it the wiki FunctionTools it
+ *   needs, stream one exchange, return the text. This helper is that idiom
+ *   (the same one scripts/demo_model_optionality.ts uses), shared so the
+ *   three call sites can't drift.
+ *
+ *   Model routing goes through lib/models/registry.ts, so the YAML-style
+ *   model string ('gemini-3.7-flash', 'claude-*', 'ollama/*'…) picks the
+ *   provider — wiki operations inherit the framework's full model
+ *   optionality. A missing provider key degrades to a clear error string;
+ *   nothing here throws for want of credentials.
+ */
+import { randomUUID } from 'node:crypto';
+import { InMemorySessionService, LlmAgent, Runner } from '@google/adk';
+import { providerForModel, providerKeyPresent, registerAvailableProviders, } from "../models/registry.js";
+/** True when the model's provider has credentials (Ollama needs none). */
+export function modelAvailable(model) {
+    const provider = providerForModel(model);
+    if (provider === 'ollama' || providerKeyPresent(provider))
+        return { ok: true };
+    return { ok: false, reason: `provider "${provider}" has no API key configured` };
+}
+export async function runWikiAgent(run) {
+    const availability = modelAvailable(run.model);
+    if (!availability.ok) {
+        return { text: '', error: availability.reason };
+    }
+    registerAvailableProviders();
+    const agent = new LlmAgent({
+        name: run.name,
+        description: run.description,
+        model: run.model,
+        instruction: run.instruction,
+        generateContentConfig: {
+            temperature: run.temperature ?? 0.3,
+            maxOutputTokens: run.maxOutputTokens ?? 4096,
+        },
+        ...(run.tools && run.tools.length > 0 ? { tools: run.tools } : {}),
+    });
+    const appName = 'melchizedek-wiki';
+    const userId = 'wiki';
+    const sessionId = randomUUID();
+    const sessionService = new InMemorySessionService();
+    const runner = new Runner({ agent, appName, sessionService });
+    await sessionService.createSession({ appName, userId, sessionId, state: {} });
+    let outputText = '';
+    let errorText = '';
+    try {
+        const stream = runner.runAsync({
+            userId,
+            sessionId,
+            newMessage: { role: 'user', parts: [{ text: run.userText }] },
+        });
+        for await (const event of stream) {
+            const evAny = event;
+            if ((evAny.errorCode || evAny.errorMessage) && evAny.errorCode !== 'STOP') {
+                errorText = `[${evAny.errorCode ?? 'ERROR'}] ${evAny.errorMessage ?? ''}`;
+            }
+            for (const part of event.content?.parts ?? []) {
+                const p = part;
+                if (!p.thought && p.text)
+                    outputText += p.text;
+            }
+        }
+    }
+    catch (err) {
+        errorText = err instanceof Error ? err.message : String(err);
+    }
+    return {
+        text: outputText.trim(),
+        ...(errorText ? { error: errorText } : {}),
+    };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * lib/wiki/builder.ts — docs assembled from typed parts, refreshed in place.
+ *
+ * WHY this file exists:
+ *   "Build the docs structurally" means a document's skeleton — frontmatter,
+ *   generated sections, prose slots — is code output, not typing. A DocSpec
+ *   declares the parts; this engine renders a new file or REFRESHES an
+ *   existing one, and the refresh contract is the whole point:
+ *
+ *     - machine-owned regions (wiki:generated markers) are rewritten from
+ *       the current spec — repo truth can never drift from the doc;
+ *     - prose (everything outside markers, and filled wiki:fill slots) is
+ *       preserved verbatim — a rebuild never destroys writing, human or LLM;
+ *     - `generated {by, at}` is bumped only when content actually changed,
+ *       so rebuilds are idempotent and diffs stay honest.
+ *
+ *   The engine is bundle-agnostic: what to generate FROM (agent YAMLs, tool
+ *   contracts, SQL) is the caller's business (scripts/wiki/build.ts here);
+ *   this module only guarantees the mechanics.
+ */
+import { type LogOp } from './format.ts';
+export type BodyPart = {
+    kind: 'prose';
+    markdown: string;
+} | {
+    kind: 'generated';
+    id: string;
+    source: string;
+    markdown: string;
+} | {
+    kind: 'fill';
+    id: string;
+    hint: string;
+};
+export interface DocSpec {
+    bundlePath: string;
+    /** Spec-owned frontmatter. Omit entirely for reserved files (indexes). */
+    fm?: Record<string, unknown>;
+    body: BodyPart[];
+}
+export interface BuildContext {
+    /** Actor recorded in `generated.by` for structural output. */
+    actor: string;
+    /** ISO date stamped into `generated.at` when content changes. */
+    date: string;
+}
+export type UpsertAction = 'created' | 'updated' | 'unchanged';
+export declare function renderDoc(spec: DocSpec, ctx: BuildContext): string;
+export declare function refreshDoc(existingRaw: string, spec: DocSpec, ctx: BuildContext): {
+    raw: string;
+    changed: boolean;
+};
+export declare function upsertDoc(root: string, spec: DocSpec, ctx: BuildContext): UpsertAction;
+export interface IndexEntry {
+    bundlePath: string;
+    title: string;
+    description: string;
+}
+/**
+ * A directory's index.md: optional hand prose survives around one generated
+ * listing. Root index carries okf_version frontmatter; others none (reserved
+ * files are exempt from the `type` requirement).
+ */
+export declare function indexSpec(dirBundlePath: string, heading: string, entries: IndexEntry[], subdirs?: IndexEntry[], rootFm?: Record<string, unknown>): DocSpec;
+/**
+ * Append one entry to a bundle log. `logPath` defaults to the root log; a
+ * caller whose entry would NAME private knowledge must pass the private
+ * annex's own log instead ('/private/log.md'), because the root log is a
+ * published file and a summary is text like any other (wiki/decisions/0003).
+ */
+export declare function appendLog(root: string, date: string, op: LogOp, summary: string, detail?: string, logPath?: string): void;

package/dist/lib/wiki/builder.js

@@ -0,0 +1,165 @@
+/**
+ * lib/wiki/builder.ts — docs assembled from typed parts, refreshed in place.
+ *
+ * WHY this file exists:
+ *   "Build the docs structurally" means a document's skeleton — frontmatter,
+ *   generated sections, prose slots — is code output, not typing. A DocSpec
+ *   declares the parts; this engine renders a new file or REFRESHES an
+ *   existing one, and the refresh contract is the whole point:
+ *
+ *     - machine-owned regions (wiki:generated markers) are rewritten from
+ *       the current spec — repo truth can never drift from the doc;
+ *     - prose (everything outside markers, and filled wiki:fill slots) is
+ *       preserved verbatim — a rebuild never destroys writing, human or LLM;
+ *     - `generated {by, at}` is bumped only when content actually changed,
+ *       so rebuilds are idempotent and diffs stay honest.
+ *
+ *   The engine is bundle-agnostic: what to generate FROM (agent YAMLs, tool
+ *   contracts, SQL) is the caller's business (scripts/wiki/build.ts here);
+ *   this module only guarantees the mechanics.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { posix } from 'node:path';
+import { formatLogEntry } from "./format.js";
+import { emitDoc, emitFrontmatter, fillSlot, generatedBlock, insertLogEntry, mdLink, parseDoc, setGeneratedContent, setSlotContent, slotIsUnfilled, } from "./markdown.js";
+import { jailedAbsPath, writeDocFile } from "./vault.js";
+// ── Rendering (fresh documents) ──────────────────────────────────────────────
+function renderPart(part) {
+    switch (part.kind) {
+        case 'prose':
+            return part.markdown.trim();
+        case 'generated':
+            return generatedBlock(part.id, part.source, part.markdown);
+        case 'fill':
+            return fillSlot(part.id, undefined, part.hint);
+    }
+}
+export function renderDoc(spec, ctx) {
+    const body = spec.body.map(renderPart).join('\n\n');
+    if (!spec.fm)
+        return `${body.trim()}\n`;
+    const fm = {
+        ...spec.fm,
+        generated: { by: ctx.actor, at: ctx.date },
+    };
+    return emitDoc(fm, body);
+}
+// ── Refreshing (existing documents) ──────────────────────────────────────────
+function replaceFrontmatterBlock(raw, fm) {
+    const parsed = parseDoc(raw);
+    const lines = raw.split('\n');
+    const body = lines.slice(parsed.bodyStartLine - 1).join('\n');
+    return `${emitFrontmatter(fm)}\n${body.replace(/^\n+/, '')}`;
+}
+/** Raw text with the volatile `generated:` stamp neutralised, for comparison. */
+function comparable(raw) {
+    const parsed = parseDoc(raw);
+    if (parsed.frontmatter === null)
+        return raw;
+    const { generated: _drop, ...rest } = parsed.frontmatter;
+    return replaceFrontmatterBlock(raw, rest);
+}
+export function refreshDoc(existingRaw, spec, ctx) {
+    const existing = parseDoc(existingRaw);
+    // Harvest prose already written into fill slots, keyed by slot id.
+    const harvested = new Map();
+    for (const slot of existing.slots) {
+        if (!slotIsUnfilled(slot))
+            harvested.set(slot.id, slot.content);
+    }
+    let raw = existingRaw;
+    // Frontmatter: spec keys win; human-added keys (status, verified, tags…)
+    // survive because the merge starts from what is on disk.
+    if (spec.fm) {
+        const merged = { ...(existing.frontmatter ?? {}), ...spec.fm };
+        raw = replaceFrontmatterBlock(raw, merged);
+    }
+    // Machine-owned regions: rewrite interiors; append blocks the doc lacks.
+    for (const part of spec.body) {
+        if (part.kind === 'generated') {
+            const next = setGeneratedContent(raw, part.id, part.markdown);
+            raw = next ?? `${raw.trimEnd()}\n\n${generatedBlock(part.id, part.source, part.markdown)}\n`;
+        }
+        if (part.kind === 'fill') {
+            const present = parseDoc(raw).slots.some((s) => s.id === part.id);
+            if (!present) {
+                raw = `${raw.trimEnd()}\n\n${fillSlot(part.id, undefined, part.hint)}\n`;
+            }
+        }
+    }
+    // Re-inject harvested prose into any slot the regeneration re-emitted.
+    for (const [id, content] of harvested) {
+        const current = parseDoc(raw).slots.find((s) => s.id === id);
+        if (current && slotIsUnfilled(current)) {
+            raw = setSlotContent(raw, id, content) ?? raw;
+        }
+    }
+    const changed = comparable(raw) !== comparable(existingRaw);
+    if (changed && spec.fm) {
+        const merged = {
+            ...(parseDoc(raw).frontmatter ?? {}),
+            generated: { by: ctx.actor, at: ctx.date },
+        };
+        raw = replaceFrontmatterBlock(raw, merged);
+    }
+    return { raw, changed };
+}
+// ── Upsert ───────────────────────────────────────────────────────────────────
+export function upsertDoc(root, spec, ctx) {
+    const abs = jailedAbsPath(root, spec.bundlePath);
+    if (!existsSync(abs)) {
+        writeDocFile(root, spec.bundlePath, renderDoc(spec, ctx));
+        return 'created';
+    }
+    const existingRaw = readFileSync(abs, 'utf-8');
+    const { raw, changed } = refreshDoc(existingRaw, spec, ctx);
+    if (!changed)
+        return 'unchanged';
+    writeDocFile(root, spec.bundlePath, raw);
+    return 'updated';
+}
+/**
+ * A directory's index.md: optional hand prose survives around one generated
+ * listing. Root index carries okf_version frontmatter; others none (reserved
+ * files are exempt from the `type` requirement).
+ */
+export function indexSpec(dirBundlePath, heading, entries, subdirs = [], rootFm) {
+    const dir = dirBundlePath.endsWith('/') ? dirBundlePath : `${dirBundlePath}/`;
+    const listing = [];
+    for (const sub of subdirs) {
+        listing.push(`- ${mdLink(sub.title, sub.bundlePath)} — ${sub.description}`);
+    }
+    for (const entry of entries) {
+        listing.push(`- ${mdLink(entry.title, entry.bundlePath)} — ${entry.description}`);
+    }
+    return {
+        bundlePath: posix.join(dir, 'index.md'),
+        ...(rootFm ? { fm: rootFm } : {}),
+        body: [
+            { kind: 'prose', markdown: `# ${heading}` },
+            {
+                kind: 'generated',
+                id: 'listing',
+                source: 'directory contents',
+                markdown: listing.join('\n'),
+            },
+        ],
+    };
+}
+// ── Log (reserved log.md, §9) ────────────────────────────────────────────────
+const LOG_PREAMBLE = `# Log
+
+Chronological record of changes to this bundle, newest first. Entries are
+machine-parseable: \`## [YYYY-MM-DD] <op> | <summary>\`.`;
+/**
+ * Append one entry to a bundle log. `logPath` defaults to the root log; a
+ * caller whose entry would NAME private knowledge must pass the private
+ * annex's own log instead ('/private/log.md'), because the root log is a
+ * published file and a summary is text like any other (wiki/decisions/0003).
+ */
+export function appendLog(root, date, op, summary, detail, logPath = '/log.md') {
+    const abs = jailedAbsPath(root, logPath);
+    const entry = formatLogEntry(date, op, summary, detail);
+    const raw = existsSync(abs) ? readFileSync(abs, 'utf-8') : `${LOG_PREAMBLE}\n`;
+    writeDocFile(root, logPath, insertLogEntry(raw, entry));
+}

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

@@ -0,0 +1,56 @@
+/**
+ * lib/wiki/dive.ts — search scoring and "repo dive" reading paths.
+ *
+ * WHY this file exists:
+ *   The two navigation questions an agent asks a wiki are "which documents
+ *   mention X?" (search) and "I have a TASK — what should I read, in what
+ *   order, within a budget?" (dive). Both are answered here with plain
+ *   lexical scoring plus graph propagation — deliberately NO model call and
+ *   NO embeddings: navigation must be instant, deterministic, and free, so
+ *   an agent can call it dozens of times while working. Semantic answering
+ *   belongs to wiki_query (an agent using these primitives), not here.
+ *
+ *   Dive = scored seeds + link expansion. Seeds are the best lexical
+ *   matches; the knowledge graph then pulls in what the seeds are wired to
+ *   (score decaying with link distance), because in a well-gardened bundle
+ *   PROXIMITY IN THE GRAPH IS RELEVANCE. The result is an ordered reading
+ *   plan — orientation first (indexes), then matched concepts, then linked
+ *   context — trimmed to a word budget.
+ */
+import { type WikiGraph } from './graph.ts';
+import { type Vault, type WikiDoc } from './vault.ts';
+export declare function tokenize(text: string): string[];
+export interface ScoredDoc {
+    doc: WikiDoc;
+    score: number;
+    /** Which query tokens hit, and where — the explanation for the ranking. */
+    matched: string[];
+    snippet: string;
+}
+export declare function scoreDocs(vault: Vault, query: string): ScoredDoc[];
+export interface DiveStop {
+    order: number;
+    path: string;
+    title: string;
+    wordCount: number;
+    /** Why this document is on the path. */
+    reason: string;
+    /** 'orient' (indexes) | 'core' (matched) | 'context' (graph-linked). */
+    role: 'orient' | 'core' | 'context';
+}
+export interface DivePlan {
+    task: string;
+    stops: DiveStop[];
+    totalWords: number;
+    budgetWords: number;
+    /** Documents that scored but did not fit the budget. */
+    overflow: Array<{
+        path: string;
+        title: string;
+    }>;
+}
+/**
+ * Assemble an ordered reading plan for a task. Deterministic and
+ * model-free; the caller (an agent on a knowledge task) does the reading.
+ */
+export declare function repoDive(vault: Vault, task: string, budgetWords?: number, graph?: WikiGraph): DivePlan;