@parall/cli 1.12.0

package/dist/lib/wiki.js

@@ -0,0 +1,1800 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ApiError, } from '@parall/sdk';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MARKDOWN_HEADING_RE = /^\s{0,3}(#{1,6})[ \t]+(.+?)\s*$/;
+const TRAILING_FENCE_RE = /\s+#+\s*$/;
+const LOCAL_NODE_SECTION_ARTIFACT_VERSION = 2;
+const LOCAL_MANIFEST_FILE = 'manifest.json';
+const PRLL_WIKI_DIR = '.parall-wiki';
+// ---------------------------------------------------------------------------
+// Wiki resolution helpers
+// ---------------------------------------------------------------------------
+export async function listWikis(ctx) {
+    return ctx.client.getWikis(ctx.orgId);
+}
+export async function resolveWikiRef(ctx, wikiRef) {
+    const normalized = wikiRef?.trim() ?? '';
+    if (!normalized) {
+        return resolveWikiRefOrDefault(ctx);
+    }
+    const wikis = await listWikis(ctx);
+    const exact = wikis.find((wiki) => wiki.id === normalized || wiki.slug === normalized);
+    if (exact) {
+        return exact;
+    }
+    const lower = normalized.toLowerCase();
+    const fuzzy = wikis.find((wiki) => wiki.slug.toLowerCase() === lower || wiki.name.toLowerCase() === lower);
+    if (fuzzy) {
+        return fuzzy;
+    }
+    throw new Error(`wiki not found: ${wikiRef}`);
+}
+/**
+ * Resolve wiki reference. If wikiRef is omitted or empty, auto-resolves to
+ * the org's single wiki. Errors if the org has zero or multiple wikis without
+ * a ref specified.
+ */
+export async function resolveWikiRefOrDefault(ctx, wikiRef) {
+    if (wikiRef?.trim()) {
+        return resolveWikiRef(ctx, wikiRef);
+    }
+    const wikis = await listWikis(ctx);
+    if (wikis.length === 1) {
+        return wikis[0];
+    }
+    if (wikis.length === 0) {
+        throw new Error('No wikis found in this organization. Create one first.');
+    }
+    throw new Error(`Multiple wikis found. Specify which one:\n${wikis.map((w) => `  ${w.slug} (${w.name})`).join('\n')}`);
+}
+// ---------------------------------------------------------------------------
+// Wiki tree / blob (API fallback for non-mounted content)
+// ---------------------------------------------------------------------------
+export async function getWikiTree(ctx, wikiRef, options = {}) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const response = await ctx.client.getWikiTree(ctx.orgId, wiki.id, {
+        path: normalizeWikiPath(options.path),
+    });
+    return {
+        wiki,
+        path: response.path,
+        entries: response.data,
+    };
+}
+export async function getWikiBlob(ctx, wikiRef, options) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const blob = await ctx.client.getWikiBlob(ctx.orgId, wiki.id, {
+        path: normalizeRequiredWikiPath(options.path),
+    });
+    return {
+        wiki,
+        content: blob.content,
+        size: blob.size,
+    };
+}
+// ---------------------------------------------------------------------------
+// Content browsing: outline, search, query, section
+// ---------------------------------------------------------------------------
+export async function getWikiOutline(ctx, wikiRef, options = {}) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const normalizedPrefix = normalizeWikiPath(options.pathPrefix);
+    const source = await loadWikiNodeSections(ctx, wiki, {
+        ref: options.ref,
+        pathPrefix: normalizedPrefix,
+    });
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        ref: normalizeRef(options.ref),
+        path_prefix: normalizedPrefix || undefined,
+        generated_at: source.generatedAt,
+        file_count: source.fileCount,
+        nodes: source.sections.map(stripNodeSectionContent),
+        source: source.kind,
+    };
+}
+export async function searchWiki(ctx, wikiRef, query, options = {}) {
+    const trimmedQuery = query.trim();
+    if (!trimmedQuery) {
+        throw new Error('query is required');
+    }
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const normalizedPrefix = normalizeWikiPath(options.pathPrefix);
+    const source = await loadWikiNodeSections(ctx, wiki, {
+        ref: options.ref,
+        pathPrefix: normalizedPrefix,
+    });
+    const nodes = buildIndexNodes(source.sections);
+    return scoreNodes(nodes, trimmedQuery, {
+        limit: options.limit,
+        includeContent: options.includeContent,
+        source: source.kind,
+    });
+}
+export async function queryWiki(ctx, wikiRef, query, options = {}) {
+    const trimmedQuery = query.trim();
+    if (!trimmedQuery) {
+        throw new Error('query is required');
+    }
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const normalizedPrefix = normalizeWikiPath(options.pathPrefix);
+    const source = await loadWikiNodeSections(ctx, wiki, {
+        ref: options.ref,
+        pathPrefix: normalizedPrefix,
+    });
+    const planned = planWikiQuery(source.sections, trimmedQuery, {
+        limit: options.limit,
+        includeContent: options.includeContent,
+        source: source.kind,
+    });
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        query: trimmedQuery,
+        ref: normalizeRef(options.ref),
+        path_prefix: normalizedPrefix || undefined,
+        generated_at: source.generatedAt,
+        file_count: source.fileCount,
+        source: source.kind,
+        documents: planned.documents,
+        sections: planned.sections,
+    };
+}
+export async function getWikiSection(ctx, wikiRef, options) {
+    const nodeId = options.nodeId.trim();
+    if (!nodeId) {
+        throw new Error('nodeId is required');
+    }
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const normalizedRef = normalizeRef(options.ref);
+    if (!normalizedRef) {
+        const local = await tryLoadLocalNodeSections(ctx, wiki);
+        const localNode = local ? findLocalNodeSection(local, nodeId) : undefined;
+        if (localNode) {
+            return {
+                ...stripNodeSectionContent(localNode),
+                content: localNode.content,
+                source: 'local_mount',
+            };
+        }
+    }
+    const parsedNode = parseNodeId(nodeId);
+    const source = await loadWikiMarkdownFile(ctx, wiki, parsedNode.path, normalizedRef);
+    const node = parseMarkdownFile(wiki, source.file).find((entry) => entry.node_id === nodeId);
+    if (!node) {
+        throw new Error(`wiki section not found: ${nodeId}`);
+    }
+    return {
+        ...stripNodeSectionContent(node),
+        content: node.content,
+        source: source.kind,
+    };
+}
+// ---------------------------------------------------------------------------
+// Changeset browsing (API-only)
+// ---------------------------------------------------------------------------
+export async function getWikiChangesetDiff(ctx, wikiRef, changesetId) {
+    const normalizedChangesetId = changesetId.trim();
+    if (!normalizedChangesetId) {
+        throw new Error('changesetId is required');
+    }
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const diff = await ctx.client.getWikiChangesetDiff(ctx.orgId, wiki.id, normalizedChangesetId);
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        changeset_id: normalizedChangesetId,
+        diff,
+    };
+}
+// ---------------------------------------------------------------------------
+// Workspace status / diff (MCP-compatible wrappers)
+// ---------------------------------------------------------------------------
+export async function getWikiWorkspaceStatus(ctx, wikiRef) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const mount = await requireLocalWikiMount(ctx, wiki);
+    const localChanges = await computeLocalChanges(mount);
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        mount_path: mount.root,
+        mode: 'read_write',
+        default_ref: wiki.default_branch,
+        changed_paths: localChanges.map((f) => f.path),
+        diff_files: localChanges,
+        dirty: localChanges.length > 0,
+        source: 'local_mount',
+    };
+}
+export async function getWikiWorkspaceDiff(ctx, wikiRef) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const mount = await requireLocalWikiMount(ctx, wiki);
+    const manifest = await readLocalManifest(mount.root);
+    const diff = await computeLocalDiff(mount, manifest);
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        mount_path: mount.root,
+        changed_paths: diff.changedPaths,
+        diff_files: diff.diffFiles,
+        patch: diff.patch,
+        source: 'local_mount',
+    };
+}
+export async function getAfcsStatus(ctx, wikiRef) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const mount = await requireLocalWikiMount(ctx, wiki);
+    const localChanges = await computeLocalChanges(mount);
+    // Fetch changesets by this agent
+    let changesets = [];
+    try {
+        const allChangesets = await ctx.client.getWikiChangesets(ctx.orgId, wiki.id);
+        const agentId = resolveAgentId(ctx.agentId);
+        const relevant = agentId
+            ? allChangesets.filter((cs) => cs.created_by === agentId)
+            : allChangesets;
+        changesets = relevant.map(toChangesetSummary);
+    }
+    catch {
+        // Changesets API may fail — non-fatal for status
+    }
+    const permissions = {
+        readable_prefixes: ['(all — server ACL)'],
+        writable_prefixes: ['(server ACL)'],
+    };
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        mount_path: mount.root,
+        mode: 'read_write',
+        default_ref: wiki.default_branch,
+        local_changes: localChanges,
+        changesets,
+        permissions,
+    };
+}
+export async function getAfcsDiff(ctx, wikiRef) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const mount = await requireLocalWikiMount(ctx, wiki);
+    const manifest = await readLocalManifest(mount.root);
+    const diff = await computeLocalDiff(mount, manifest);
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        mount_path: mount.root,
+        changed_paths: diff.changedPaths,
+        diff_files: diff.diffFiles,
+        patch: diff.patch,
+    };
+}
+// ---------------------------------------------------------------------------
+// AFCS: propose changeset (REST-based)
+// ---------------------------------------------------------------------------
+export async function proposeWikiChangeset(ctx, wikiRef, options) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const mount = await requireLocalWikiMount(ctx, wiki, { requireWrite: true });
+    const title = options.title.trim();
+    if (!title) {
+        throw new Error('title is required');
+    }
+    const manifest = await readLocalManifest(mount.root);
+    const diff = await computeLocalDiff(mount, manifest);
+    if (diff.changedPaths.length === 0) {
+        throw new Error(`no changes to propose for wiki ${wiki.slug}`);
+    }
+    // Build file_changes for the changeset API
+    const fileChanges = [];
+    for (const filePath of diff.changedPaths) {
+        const localPath = resolvePathInsideRoot(mount.root, filePath);
+        const existsLocally = await pathExists(localPath);
+        const baseEntry = manifest.files[filePath];
+        if (!existsLocally) {
+            // Deleted
+            fileChanges.push({
+                path: filePath,
+                action: 'delete',
+            });
+        }
+        else {
+            const content = await fs.readFile(localPath);
+            fileChanges.push({
+                path: filePath,
+                action: baseEntry ? 'update' : 'create',
+                content_base64: content.toString('base64'),
+            });
+        }
+    }
+    let changeset;
+    const existingChangesetId = normalizeOptionalString(options.changesetId);
+    if (existingChangesetId) {
+        // Re-propose existing changeset with updated file_changes
+        changeset = await ctx.client.updateWikiChangeset(ctx.orgId, wiki.id, existingChangesetId, {
+            title,
+            message: normalizeOptionalString(options.message),
+            file_changes: fileChanges,
+        });
+    }
+    else {
+        // Create new changeset via API
+        changeset = await ctx.client.createWikiChangeset(ctx.orgId, wiki.id, {
+            title,
+            message: normalizeOptionalString(options.message),
+            file_changes: fileChanges,
+            source_chat_id: normalizeOptionalString(options.sourceChatId),
+            source_message_id: normalizeOptionalString(options.sourceMessageId),
+            source_run_id: normalizeOptionalString(options.sourceRunId),
+        });
+    }
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        mount_path: mount.root,
+        changed_paths: diff.changedPaths,
+        diff_files: diff.diffFiles,
+        changeset,
+        source: 'local_mount',
+    };
+}
+// ---------------------------------------------------------------------------
+// AFCS: reset workspace
+// ---------------------------------------------------------------------------
+/**
+ * Discard all local changes and restore files to the last synced state.
+ * Reads the local manifest and restores all files from the server.
+ */
+export async function resetWikiWorkspace(ctx, wikiRef) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const mount = await requireLocalWikiMount(ctx, wiki);
+    const manifest = await readLocalManifest(mount.root);
+    // Count changes before reset
+    const changes = await computeLocalChanges(mount);
+    const changedCount = changes.length;
+    if (changedCount === 0) {
+        return { wiki_id: wiki.id, wiki_slug: wiki.slug, files_restored: 0 };
+    }
+    // Re-download all manifest files and overwrite local state
+    const token = resolveApiToken();
+    const manifestPaths = Object.keys(manifest.files);
+    if (manifestPaths.length > 0) {
+        const downloaded = await bulkDownloadFiles(mount.bulkDownloadUrl, token, manifestPaths);
+        for (const entry of downloaded) {
+            const fullPath = resolvePathInsideRoot(mount.root, entry.path);
+            await fs.mkdir(path.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, Buffer.from(entry.content_base64, 'base64'));
+        }
+    }
+    // Remove any local file not in manifest
+    await removeFilesNotInManifest(mount.root, manifest);
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        files_restored: changedCount,
+    };
+}
+export async function listWikiChangesets(ctx, wikiRef) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const allChangesets = await ctx.client.getWikiChangesets(ctx.orgId, wiki.id);
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        changesets: allChangesets.map(toChangesetSummary),
+    };
+}
+export async function getWikiChangesetDetail(ctx, wikiRef, changesetId) {
+    const normalizedId = changesetId.trim();
+    if (!normalizedId) {
+        throw new Error('changeset ID is required. Run `parall wiki changesets <wiki>` to list available changesets.');
+    }
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const changeset = await ctx.client.getWikiChangeset(ctx.orgId, wiki.id, normalizedId);
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        changeset,
+    };
+}
+export async function requestWikiAccess(ctx, wikiRef, targetPath, reason) {
+    const normalizedPath = normalizeRequiredWikiPath(targetPath);
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    try {
+        await ctx.client.request('POST', `/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}/access-requests`, {
+            path: normalizedPath,
+            reason: reason?.trim() || undefined,
+        });
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 404) {
+            return {
+                wiki_id: wiki.id,
+                wiki_slug: wiki.slug,
+                wiki_name: wiki.name,
+                path: normalizedPath,
+                reason: reason?.trim() || undefined,
+                status: 'submitted',
+                message: 'Access request noted. The server access-request endpoint is not yet implemented. '
+                    + 'Ask a wiki admin to grant access manually.',
+            };
+        }
+        throw error;
+    }
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        path: normalizedPath,
+        reason: reason?.trim() || undefined,
+        status: 'submitted',
+        message: 'Access request submitted. Waiting for approval.',
+    };
+}
+export async function getWikiLog(ctx, wikiRef, filePath) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    if (filePath?.trim()) {
+        throw new Error('Per-file wiki history is not implemented yet. Omit the path to see org-wide operations.');
+    }
+    const ops = await ctx.client.getWikiOperations(ctx.orgId, wiki.id);
+    const entries = ops.data.map((op) => ({
+        type: 'operation',
+        id: op.id,
+        action: op.op_type,
+        actor_id: op.actor_id,
+        created_at: op.created_at,
+    }));
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        entries,
+    };
+}
+/**
+ * List accessible wikis for this org, sync each via REST
+ * (manifest comparison + bulk download), and remove stale directories.
+ * Mount path is determined client-side: {mountRoot}/{slug}/
+ */
+export async function syncAllMounts(ctx) {
+    const wikis = await ctx.client.getWikis(ctx.orgId);
+    const mountRoot = ctx.mountRoot?.trim() || process.env.PRLL_WIKI_MOUNT_ROOT?.trim();
+    const activeMountPaths = new Set();
+    const synced = [];
+    for (const wiki of wikis) {
+        const mountPath = resolveMountPath(wiki.slug, mountRoot);
+        activeMountPaths.add(mountPath);
+        await syncSingleWiki(ctx, wiki, mountPath);
+        synced.push({ slug: wiki.slug, path: mountPath });
+    }
+    await pruneStaleMounts(mountRoot, activeMountPaths);
+    return { ok: true, mounts: wikis.length, synced };
+}
+/**
+ * Run {@link syncAllMounts} in a loop, sleeping `intervalSec` between
+ * iterations. Returns a `stop` callback to break the loop.
+ */
+export function watchMounts(ctx, intervalSec) {
+    requireAgentId(ctx); // fail fast if agentId missing
+    let stopped = false;
+    const doSync = async () => {
+        try {
+            await syncAllMounts(ctx);
+        }
+        catch (err) {
+            process.stderr.write(`wiki refresh failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    };
+    const timer = setInterval(doSync, intervalSec * 1000);
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    return { stop };
+}
+// ---------------------------------------------------------------------------
+// Sync internals (REST-based)
+// ---------------------------------------------------------------------------
+/**
+ * Sync a single wiki:
+ * 1. Fetch server manifest (file listing with SHAs)
+ * 2. Compare with local manifest
+ * 3. Download new/modified files via bulk download
+ * 4. Delete removed files
+ * 5. Save updated local manifest
+ */
+async function syncSingleWiki(ctx, wiki, mountPath) {
+    await fs.mkdir(mountPath, { recursive: true });
+    const metaDir = path.join(mountPath, PRLL_WIKI_DIR);
+    await fs.mkdir(metaDir, { recursive: true });
+    const token = resolveApiToken();
+    const baseUrl = (ctx.baseUrl ?? process.env.PRLL_WIKI_URL ?? process.env.PRLL_API_URL ?? '').replace(/\/+$/, '');
+    const manifestUrl = `${baseUrl}/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}/manifest`;
+    const bulkDownloadUrl = `${baseUrl}/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}/files/bulk-download`;
+    // 1. Fetch server manifest
+    const manifestResp = await wikiServiceFetch(manifestUrl, token);
+    const serverEntries = manifestResp.data;
+    // 2. Read local manifest
+    const localManifest = await readLocalManifest(mountPath);
+    // 3. Compare: find new, modified, deleted files
+    const serverByPath = new Map(serverEntries.map((e) => [e.path, e]));
+    const toDownload = [];
+    const toDelete = [];
+    for (const entry of serverEntries) {
+        const local = localManifest.files[entry.path];
+        if (!local || local.sha !== entry.sha) {
+            toDownload.push(entry.path);
+        }
+    }
+    for (const localPath of Object.keys(localManifest.files)) {
+        if (!serverByPath.has(localPath)) {
+            toDelete.push(localPath);
+        }
+    }
+    // 4. Bulk download changed files
+    if (toDownload.length > 0) {
+        const downloaded = await bulkDownloadFiles(bulkDownloadUrl, token, toDownload);
+        for (const entry of downloaded) {
+            const fullPath = resolvePathInsideRoot(mountPath, entry.path);
+            await fs.mkdir(path.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, Buffer.from(entry.content_base64, 'base64'));
+        }
+    }
+    // 5. Delete removed files
+    for (const deletePath of toDelete) {
+        const fullPath = resolvePathInsideRoot(mountPath, deletePath);
+        await fs.rm(fullPath, { force: true });
+        await removeEmptyParents(mountPath, path.dirname(fullPath));
+    }
+    // 6. Save updated local manifest
+    const newManifest = {
+        wiki_id: wiki.id,
+        synced_at: new Date().toISOString(),
+        files: {},
+    };
+    for (const entry of serverEntries) {
+        newManifest.files[entry.path] = {
+            sha: entry.sha,
+            size: entry.size,
+        };
+    }
+    await writeLocalManifest(mountPath, newManifest);
+}
+// ---------------------------------------------------------------------------
+// Local manifest I/O
+// ---------------------------------------------------------------------------
+async function readLocalManifest(mountRoot) {
+    const manifestPath = path.join(mountRoot, PRLL_WIKI_DIR, LOCAL_MANIFEST_FILE);
+    try {
+        const raw = await fs.readFile(manifestPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { wiki_id: '', synced_at: '', files: {} };
+    }
+}
+async function writeLocalManifest(mountRoot, manifest) {
+    const metaDir = path.join(mountRoot, PRLL_WIKI_DIR);
+    await fs.mkdir(metaDir, { recursive: true });
+    await fs.writeFile(path.join(metaDir, LOCAL_MANIFEST_FILE), JSON.stringify(manifest, null, 2), 'utf8');
+}
+// ---------------------------------------------------------------------------
+// REST helpers for wiki-service
+// ---------------------------------------------------------------------------
+function resolveApiToken() {
+    const token = process.env.PRLL_API_KEY?.trim();
+    if (!token) {
+        throw new Error('PRLL_API_KEY is required for wiki operations');
+    }
+    return token;
+}
+async function wikiServiceFetch(url, token, options = {}) {
+    const method = options.method ?? 'GET';
+    const headers = {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+    };
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: options.body,
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`wiki-service ${method} ${url}: ${response.status} ${response.statusText}${text ? ` — ${text}` : ''}`);
+    }
+    return response.json();
+}
+async function bulkDownloadFiles(bulkDownloadUrl, token, paths) {
+    // Batch in chunks to avoid overly large requests
+    const BATCH_SIZE = 100;
+    const results = [];
+    for (let i = 0; i < paths.length; i += BATCH_SIZE) {
+        const batch = paths.slice(i, i + BATCH_SIZE);
+        const raw = await wikiServiceFetch(bulkDownloadUrl, token, {
+            method: 'POST',
+            body: JSON.stringify({ paths: batch }),
+        });
+        results.push(...raw.data);
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Local change detection (manifest-based)
+// ---------------------------------------------------------------------------
+function computeSHA256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Compute list of changed files by comparing local disk to local manifest. */
+async function computeLocalChanges(mount) {
+    const manifest = await readLocalManifest(mount.root);
+    const diffFiles = [];
+    const visited = new Set();
+    // Walk local files to find modified/added
+    await walkLocalFiles(mount.root, mount.root, async (fullPath, relativePath) => {
+        if (!matchesAllowedPrefix(relativePath, [])) {
+            return;
+        }
+        visited.add(relativePath);
+        const localContent = await fs.readFile(fullPath);
+        const localSha = computeSHA256(localContent);
+        const manifestEntry = manifest.files[relativePath];
+        if (!manifestEntry) {
+            // New file
+            const lines = localContent.toString('utf8').split('\n').length;
+            diffFiles.push({ path: relativePath, additions: lines, deletions: 0 });
+        }
+        else if (localSha !== manifestEntry.sha) {
+            // Modified file — compute line diff estimate
+            const localLines = localContent.toString('utf8').split('\n');
+            const additions = localLines.length;
+            const deletions = estimateLines(manifestEntry.size);
+            diffFiles.push({ path: relativePath, additions, deletions });
+        }
+    });
+    // Find deleted files (in manifest but not on disk)
+    for (const [filePath, entry] of Object.entries(manifest.files)) {
+        if (!visited.has(filePath)) {
+            const deletions = estimateLines(entry.size);
+            diffFiles.push({ path: filePath, additions: 0, deletions });
+        }
+    }
+    diffFiles.sort((a, b) => a.path.localeCompare(b.path));
+    return diffFiles;
+}
+/** Compute diff including unified patch by comparing local files vs manifest base content. */
+async function computeLocalDiff(mount, manifest) {
+    const diffFiles = [];
+    const patchParts = [];
+    const visited = new Set();
+    const token = resolveApiToken();
+    // Walk local files to find modified/added
+    await walkLocalFiles(mount.root, mount.root, async (fullPath, relativePath) => {
+        if (!matchesAllowedPrefix(relativePath, [])) {
+            return;
+        }
+        visited.add(relativePath);
+        const localContent = await fs.readFile(fullPath);
+        const localSha = computeSHA256(localContent);
+        const manifestEntry = manifest.files[relativePath];
+        if (!manifestEntry) {
+            // New file
+            const localText = localContent.toString('utf8');
+            const localLines = localText.split('\n');
+            diffFiles.push({ path: relativePath, additions: localLines.length, deletions: 0 });
+            patchParts.push(buildUnifiedDiff(relativePath, '', localText));
+        }
+        else if (localSha !== manifestEntry.sha) {
+            // Modified file — fetch base content from server for diff
+            const localText = localContent.toString('utf8');
+            let baseText = '';
+            try {
+                const baseEntries = await bulkDownloadFiles(mount.bulkDownloadUrl, token, [relativePath]);
+                if (baseEntries.length > 0) {
+                    baseText = Buffer.from(baseEntries[0].content_base64, 'base64').toString('utf8');
+                }
+            }
+            catch {
+                // If we can't fetch base, treat as full addition
+            }
+            const localLines = localText.split('\n');
+            const baseLines = baseText.split('\n');
+            diffFiles.push({
+                path: relativePath,
+                additions: localLines.length,
+                deletions: baseLines.length,
+            });
+            patchParts.push(buildUnifiedDiff(relativePath, baseText, localText));
+        }
+    });
+    // Find deleted files
+    for (const [filePath, entry] of Object.entries(manifest.files)) {
+        if (!visited.has(filePath)) {
+            let baseText = '';
+            try {
+                const baseEntries = await bulkDownloadFiles(mount.bulkDownloadUrl, token, [filePath]);
+                if (baseEntries.length > 0) {
+                    baseText = Buffer.from(baseEntries[0].content_base64, 'base64').toString('utf8');
+                }
+            }
+            catch {
+                // Estimate
+            }
+            const baseLines = baseText.split('\n');
+            diffFiles.push({ path: filePath, additions: 0, deletions: baseLines.length });
+            patchParts.push(buildUnifiedDiff(filePath, baseText, ''));
+        }
+    }
+    diffFiles.sort((a, b) => a.path.localeCompare(b.path));
+    const changedPaths = diffFiles.map((f) => f.path);
+    const patch = patchParts.join('');
+    return { changedPaths, diffFiles, patch };
+}
+/** Build a minimal unified diff between two text strings. */
+function buildUnifiedDiff(filePath, oldText, newText) {
+    const oldLines = oldText ? oldText.split('\n') : [];
+    const newLines = newText ? newText.split('\n') : [];
+    const aPath = oldText ? `a/${filePath}` : '/dev/null';
+    const bPath = newText ? `b/${filePath}` : '/dev/null';
+    const parts = [
+        `diff --git a/${filePath} b/${filePath}\n`,
+    ];
+    if (!oldText) {
+        parts.push('new file mode 100644\n');
+    }
+    else if (!newText) {
+        parts.push('deleted file mode 100644\n');
+    }
+    parts.push(`--- ${aPath}\n`);
+    parts.push(`+++ ${bPath}\n`);
+    parts.push(`@@ -1,${oldLines.length} +1,${newLines.length} @@\n`);
+    for (const line of oldLines) {
+        parts.push(`-${line}\n`);
+    }
+    for (const line of newLines) {
+        parts.push(`+${line}\n`);
+    }
+    return parts.join('');
+}
+/** Estimate number of lines from file size (rough: ~40 bytes per line). */
+function estimateLines(sizeBytes) {
+    return Math.max(1, Math.round(sizeBytes / 40));
+}
+// ---------------------------------------------------------------------------
+// File system helpers
+// ---------------------------------------------------------------------------
+/** Walk all files (not just markdown) under a root, excluding .parall-wiki. */
+async function walkLocalFiles(root, dir, visitor) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (entry.name === PRLL_WIKI_DIR) {
+                continue;
+            }
+            await walkLocalFiles(root, path.join(dir, entry.name), visitor);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = toPosix(path.relative(root, fullPath));
+        await visitor(fullPath, relativePath);
+    }
+}
+/** Walk only markdown files under a root. */
+async function walkLocalMarkdownFiles(root, dir, visitor) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (entry.name === PRLL_WIKI_DIR) {
+                continue;
+            }
+            await walkLocalMarkdownFiles(root, path.join(dir, entry.name), visitor);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = toPosix(path.relative(root, fullPath));
+        if (!isMarkdownFile(relativePath)) {
+            continue;
+        }
+        await visitor(fullPath, relativePath);
+    }
+}
+/** Remove files not present in manifest. */
+async function removeFilesNotInManifest(root, manifest) {
+    await walkLocalFiles(root, root, async (fullPath, relativePath) => {
+        if (!(relativePath in manifest.files)) {
+            await fs.rm(fullPath, { force: true });
+            await removeEmptyParents(root, path.dirname(fullPath));
+        }
+    });
+}
+/** Remove empty parent directories up to (but not including) root. */
+async function removeEmptyParents(root, dir) {
+    const absRoot = path.resolve(root);
+    let current = path.resolve(dir);
+    while (current !== absRoot && current.startsWith(absRoot)) {
+        try {
+            const entries = await fs.readdir(current);
+            if (entries.length > 0)
+                break;
+            await fs.rmdir(current);
+            current = path.dirname(current);
+        }
+        catch {
+            break;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Mount resolution
+// ---------------------------------------------------------------------------
+async function resolveLocalWikiMount(ctx, wiki) {
+    const mountRoot = ctx.mountRoot ?? process.env.PRLL_WIKI_MOUNT_ROOT;
+    let root;
+    try {
+        root = resolveMountPath(wiki.slug, mountRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!(await pathExists(root))) {
+        return null;
+    }
+    const baseUrl = (ctx.baseUrl ?? process.env.PRLL_WIKI_URL ?? process.env.PRLL_API_URL ?? '').replace(/\/+$/, '');
+    const wikiBase = `${baseUrl}/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}`;
+    return {
+        root,
+        wikiId: wiki.id,
+        manifestUrl: `${wikiBase}/manifest`,
+        blobUrl: `${wikiBase}/files`,
+        bulkDownloadUrl: `${wikiBase}/files/bulk-download`,
+        changesetsUrl: `${wikiBase}/changesets`,
+    };
+}
+async function requireLocalWikiMount(ctx, wiki, options = {}) {
+    const mount = await resolveLocalWikiMount(ctx, wiki);
+    if (!mount) {
+        throw new Error(`wiki ${wiki.slug} is not available in a local agent mount`);
+    }
+    if (options.requireWrite && 'read_write' !== 'read_write') {
+        throw new Error(`wiki ${wiki.slug} mount is read-only`);
+    }
+    return mount;
+}
+// ---------------------------------------------------------------------------
+// Node section loading (unchanged logic, adapts to REST mount)
+// ---------------------------------------------------------------------------
+async function loadWikiNodeSections(ctx, wiki, options = {}) {
+    const normalizedRef = normalizeRef(options.ref);
+    const normalizedPrefix = normalizeWikiPath(options.pathPrefix);
+    if (!normalizedRef) {
+        const local = await tryLoadLocalNodeSections(ctx, wiki, normalizedPrefix);
+        if (local) {
+            const sections = filterNodeSectionsByPathPrefix(flattenLocalNodeSectionFiles(local.files), normalizedPrefix);
+            return {
+                kind: 'local_mount',
+                generatedAt: local.generated_at,
+                fileCount: countMatchingMarkdownFiles(local.files, normalizedPrefix),
+                sections,
+            };
+        }
+    }
+    const artifact = await ctx.client.getWikiNodeSections(ctx.orgId, wiki.id, { ref: normalizedRef });
+    const sections = filterNodeSectionsByPathPrefix(artifact.nodes, normalizedPrefix);
+    return {
+        kind: 'api',
+        generatedAt: artifact.generated_at,
+        fileCount: countMatchingSectionFiles(artifact.nodes, normalizedPrefix),
+        sections,
+    };
+}
+async function loadWikiMarkdownFile(ctx, wiki, filePath, ref) {
+    const normalizedRef = normalizeRef(ref);
+    const normalizedPath = normalizeRequiredWikiPath(filePath);
+    if (!normalizedRef) {
+        const local = await tryLoadLocalMarkdownFile(ctx, wiki, normalizedPath);
+        if (local) {
+            return { kind: 'local_mount', file: local };
+        }
+    }
+    return {
+        kind: 'api',
+        file: await loadRemoteMarkdownFile(ctx, wiki, normalizedRef, normalizedPath),
+    };
+}
+async function tryLoadLocalMarkdownFile(ctx, wiki, filePath) {
+    const mount = await resolveLocalWikiMount(ctx, wiki);
+    if (!mount) {
+        return null;
+    }
+    enforceAllowedPrefix(filePath, []);
+    const target = resolvePathInsideRoot(mount.root, filePath);
+    const stat = await fs.stat(target).catch(() => null);
+    if (!stat) {
+        throw new Error(`wiki file not found in local mount: ${filePath}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`wiki path is not a file: ${filePath}`);
+    }
+    if (!isMarkdownFile(filePath)) {
+        throw new Error(`wiki section requires a Markdown file: ${filePath}`);
+    }
+    return {
+        path: toPosix(filePath),
+        content: await fs.readFile(target, 'utf8'),
+    };
+}
+async function loadRemoteMarkdownFile(ctx, wiki, ref, filePath) {
+    if (!isMarkdownFile(filePath)) {
+        throw new Error(`wiki section requires a Markdown file: ${filePath}`);
+    }
+    const blob = await ctx.client.getWikiBlob(ctx.orgId, wiki.id, {
+        path: filePath,
+    });
+    return {
+        path: filePath,
+        content: blob.content,
+    };
+}
+async function tryLoadLocalNodeSections(ctx, wiki, pathPrefix) {
+    const mount = await resolveLocalWikiMount(ctx, wiki);
+    if (!mount) {
+        return null;
+    }
+    if (pathPrefix) {
+        enforceAllowedPrefix(pathPrefix, []);
+    }
+    return loadOrBuildLocalNodeSectionArtifact(wiki, mount);
+}
+async function loadOrBuildLocalNodeSectionArtifact(wiki, mount) {
+    const artifactPath = path.join(mount.root, PRLL_WIKI_DIR, 'node-sections.json');
+    const descriptors = await collectLocalMarkdownDescriptors(mount.root, []);
+    const cached = await readLocalNodeSectionArtifact(artifactPath);
+    const artifact = {
+        version: LOCAL_NODE_SECTION_ARTIFACT_VERSION,
+        generated_at: new Date().toISOString(),
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        file_count: descriptors.length,
+        files: await buildLocalNodeSectionFiles(wiki, mount.root, descriptors, cached),
+    };
+    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
+    await fs.writeFile(artifactPath, JSON.stringify(artifact, null, 2), 'utf8');
+    return artifact;
+}
+async function readLocalNodeSectionArtifact(artifactPath) {
+    try {
+        const raw = await fs.readFile(artifactPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function collectLocalMarkdownDescriptors(root, allowedPrefixes) {
+    const descriptors = [];
+    await walkLocalMarkdownFiles(root, root, async (fullPath, relativePath) => {
+        if (!matchesAllowedPrefix(relativePath, allowedPrefixes)) {
+            return;
+        }
+        const stat = await fs.stat(fullPath);
+        descriptors.push({
+            path: relativePath,
+            size: stat.size,
+            mtime_ms: stat.mtimeMs,
+        });
+    });
+    return descriptors.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function buildLocalNodeSectionFiles(wiki, root, descriptors, cached) {
+    const cachedByPath = new Map();
+    if (cached
+        && cached.version === LOCAL_NODE_SECTION_ARTIFACT_VERSION
+        && cached.wiki_id === wiki.id
+        && cached.wiki_slug === wiki.slug
+        && cached.wiki_name === wiki.name) {
+        for (const file of cached.files) {
+            cachedByPath.set(file.path, file);
+        }
+    }
+    const files = [];
+    for (const descriptor of descriptors) {
+        const existing = cachedByPath.get(descriptor.path);
+        if (existing
+            && existing.size === descriptor.size
+            && existing.mtime_ms === descriptor.mtime_ms) {
+            files.push(existing);
+            continue;
+        }
+        const content = await fs.readFile(resolvePathInsideRoot(root, descriptor.path), 'utf8');
+        files.push({
+            ...descriptor,
+            nodes: parseMarkdownFile(wiki, {
+                path: descriptor.path,
+                content,
+            }),
+        });
+    }
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+function flattenLocalNodeSectionFiles(files) {
+    const sections = [];
+    for (const file of files) {
+        sections.push(...file.nodes);
+    }
+    sections.sort((a, b) => {
+        if (a.path === b.path) {
+            return a.start_line - b.start_line;
+        }
+        return a.path.localeCompare(b.path);
+    });
+    return sections;
+}
+function findLocalNodeSection(artifact, nodeId) {
+    for (const file of artifact.files) {
+        const node = file.nodes.find((entry) => entry.node_id === nodeId);
+        if (node) {
+            return node;
+        }
+    }
+    return undefined;
+}
+function filterNodeSectionsByPathPrefix(sections, pathPrefix) {
+    if (!pathPrefix) {
+        return sections;
+    }
+    return sections.filter((section) => (section.path === pathPrefix || section.path.startsWith(`${pathPrefix}/`)));
+}
+function countMatchingMarkdownFiles(files, pathPrefix) {
+    if (!pathPrefix) {
+        return files.length;
+    }
+    return files.filter((file) => (file.path === pathPrefix || file.path.startsWith(`${pathPrefix}/`))).length;
+}
+function countMatchingSectionFiles(sections, pathPrefix) {
+    const paths = new Set();
+    for (const section of sections) {
+        if (!pathPrefix || section.path === pathPrefix || section.path.startsWith(`${pathPrefix}/`)) {
+            paths.add(section.path);
+        }
+    }
+    return paths.size;
+}
+// ---------------------------------------------------------------------------
+// Stale mount cleanup
+// ---------------------------------------------------------------------------
+async function pruneStaleMounts(mountRoot, activePaths) {
+    const root = mountRoot?.trim();
+    if (!root)
+        return;
+    const absRoot = path.resolve(root);
+    if (!(await pathExists(absRoot)))
+        return;
+    const stat = await fs.stat(absRoot);
+    if (!stat.isDirectory()) {
+        throw new Error(`mount root "${absRoot}" is not a directory`);
+    }
+    const activeArr = Array.from(activePaths);
+    const staleDirs = [];
+    await findStaleMountDirs(absRoot, absRoot, activePaths, activeArr, staleDirs);
+    // Remove deepest first to avoid partial-tree issues
+    staleDirs.sort((a, b) => b.length - a.length);
+    for (const staleDir of staleDirs) {
+        await fs.rm(staleDir, { recursive: true, force: true });
+    }
+}
+async function findStaleMountDirs(absRoot, dir, activePaths, activeArr, staleDirs) {
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const fullPath = path.join(dir, name);
+        const stat = await fs.lstat(fullPath).catch(() => null);
+        if (!stat?.isDirectory() || stat.isSymbolicLink())
+            continue;
+        if (name === PRLL_WIKI_DIR) {
+            const mountDir = path.dirname(fullPath);
+            if (mountDir === absRoot)
+                continue;
+            if (activePaths.has(mountDir))
+                continue;
+            const prefix = mountDir + path.sep;
+            if (activeArr.some((ap) => ap.startsWith(prefix)))
+                continue;
+            if (await pathExists(path.join(fullPath, LOCAL_MANIFEST_FILE))) {
+                staleDirs.push(mountDir);
+            }
+            continue;
+        }
+        await findStaleMountDirs(absRoot, fullPath, activePaths, activeArr, staleDirs);
+    }
+}
+// ---------------------------------------------------------------------------
+// Changeset summary helper
+// ---------------------------------------------------------------------------
+function toChangesetSummary(cs) {
+    return {
+        id: cs.id,
+        status: cs.status,
+        title: cs.title,
+        changed_paths: cs.changed_paths,
+        feedback: cs.last_error ?? null,
+        created_at: cs.created_at,
+        updated_at: cs.updated_at,
+    };
+}
+// ---------------------------------------------------------------------------
+// Search & index engine (unchanged)
+// ---------------------------------------------------------------------------
+function stripNodeSectionContent(section) {
+    const { content: _content, ...node } = section;
+    return node;
+}
+function buildIndexNodes(sections) {
+    const nodes = [];
+    for (const section of sections) {
+        nodes.push(buildIndexedNode(section));
+    }
+    return nodes;
+}
+function parseMarkdownFile(wiki, file) {
+    const lines = file.content.split('\n');
+    const frontMatterEnd = detectFrontMatterEnd(lines);
+    const headings = extractMarkdownHeadings(lines, frontMatterEnd);
+    const fileTitle = defaultFileTitle(file.path);
+    if (headings.length === 0) {
+        const docNode = buildNodeSection(wiki, {
+            nodeId: `${file.path}:doc`,
+            path: file.path,
+            title: fileTitle,
+            headingPath: [],
+            level: 0,
+            startLine: findFirstNonEmptyLine(lines, frontMatterEnd + 1, lines.length),
+            endLine: lines.length,
+            content: lines.slice(frontMatterEnd).join('\n').trim(),
+        });
+        return !docNode.content ? [] : [docNode];
+    }
+    const nodes = [];
+    const firstHeadingLine = headings[0].line;
+    const preface = lines.slice(frontMatterEnd, firstHeadingLine - 1).join('\n').trim();
+    if (preface) {
+        nodes.push(buildNodeSection(wiki, {
+            nodeId: `${file.path}:preface`,
+            path: file.path,
+            title: fileTitle,
+            headingPath: [],
+            level: 0,
+            startLine: findFirstNonEmptyLine(lines, frontMatterEnd + 1, firstHeadingLine - 1),
+            endLine: firstHeadingLine - 1,
+            content: preface,
+        }));
+    }
+    for (let i = 0; i < headings.length; i += 1) {
+        const current = headings[i];
+        const nextLine = i + 1 < headings.length ? headings[i + 1].line : lines.length + 1;
+        nodes.push(buildNodeSection(wiki, {
+            nodeId: `${file.path}:L${current.line}`,
+            path: file.path,
+            title: current.title,
+            headingPath: current.path,
+            level: current.level,
+            startLine: current.line,
+            endLine: nextLine - 1,
+            content: lines.slice(current.line, nextLine - 1).join('\n').trim(),
+        }));
+    }
+    return nodes;
+}
+function buildNodeSection(wiki, input) {
+    const content = input.content.trim();
+    const sectionPath = input.headingPath.length > 0
+        ? `${input.path} > ${input.headingPath.join(' > ')}`
+        : input.path;
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        node_id: input.nodeId,
+        path: input.path,
+        title: input.title,
+        heading_path: input.headingPath.length > 0 ? [...input.headingPath] : undefined,
+        section_path: sectionPath,
+        level: input.level,
+        start_line: input.startLine,
+        end_line: input.endLine,
+        content,
+    };
+}
+function buildIndexedNode(section) {
+    const searchText = [
+        section.path,
+        section.title,
+        section.heading_path?.join(' ') ?? '',
+        section.content,
+    ].join('\n').trim();
+    const termFreq = new Map();
+    const tokens = tokenize(searchText);
+    for (const token of tokens) {
+        termFreq.set(token, (termFreq.get(token) ?? 0) + 1);
+    }
+    return {
+        section,
+        content: section.content,
+        lowerPath: section.path.toLowerCase(),
+        lowerTitle: section.title.toLowerCase(),
+        lowerBody: section.content.toLowerCase(),
+        lowerJoined: section.section_path.toLowerCase(),
+        termFreq,
+        docLen: tokens.length,
+    };
+}
+function scoreNodes(nodes, query, options) {
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0) {
+        throw new Error('query did not contain searchable terms');
+    }
+    const docFreq = new Map();
+    let totalDocLen = 0;
+    for (const node of nodes) {
+        totalDocLen += node.docLen;
+        for (const token of node.termFreq.keys()) {
+            docFreq.set(token, (docFreq.get(token) ?? 0) + 1);
+        }
+    }
+    const avgDocLen = nodes.length > 0 ? Math.max(totalDocLen / nodes.length, 1) : 1;
+    const lowerQuery = query.toLowerCase();
+    const limit = options.limit && options.limit > 0 ? options.limit : 5;
+    const results = [];
+    for (const node of nodes) {
+        const score = scoreNode(node, queryTokens, lowerQuery, docFreq, nodes.length, avgDocLen);
+        if (score <= 0) {
+            continue;
+        }
+        results.push({
+            ...stripNodeSectionContent(node.section),
+            score,
+            snippet: buildSnippet(node, lowerQuery, queryTokens),
+            content: options.includeContent ? node.content : undefined,
+            source: options.source,
+        });
+    }
+    results.sort((a, b) => {
+        if (b.score === a.score) {
+            if (a.path === b.path) {
+                return a.start_line - b.start_line;
+            }
+            return a.path.localeCompare(b.path);
+        }
+        return b.score - a.score;
+    });
+    return results.slice(0, limit);
+}
+function planWikiQuery(sections, query, options) {
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0) {
+        throw new Error('query did not contain searchable terms');
+    }
+    const lowerQuery = query.toLowerCase();
+    const limit = options.limit && options.limit > 0 ? options.limit : 5;
+    const documents = buildIndexedDocuments(sections);
+    const rankedDocuments = scoreDocuments(documents, queryTokens, lowerQuery)
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => {
+        if (b.score === a.score) {
+            return a.document.path.localeCompare(b.document.path);
+        }
+        return b.score - a.score;
+    });
+    const shortlistedDocuments = rankedDocuments.slice(0, Math.max(limit * 2, 3));
+    const shortlistedNodes = buildIndexNodes(shortlistedDocuments.flatMap((entry) => entry.document.sections));
+    const docScoreByPath = new Map(shortlistedDocuments.map((entry) => [entry.document.path, entry.score]));
+    const results = [];
+    for (const node of shortlistedNodes) {
+        const documentScore = docScoreByPath.get(node.section.path) ?? 0;
+        const plan = scoreTreeAwareNode(node, queryTokens, lowerQuery, documentScore, shortlistedNodes);
+        if (plan.score <= 0) {
+            continue;
+        }
+        results.push({
+            ...stripNodeSectionContent(node.section),
+            score: plan.score,
+            document_score: documentScore,
+            snippet: buildSnippet(node, lowerQuery, queryTokens),
+            content: options.includeContent ? node.content : undefined,
+            source: options.source,
+            reasoning: plan.reasoning,
+        });
+    }
+    results.sort((a, b) => {
+        if (b.score === a.score) {
+            if (a.path === b.path) {
+                return a.start_line - b.start_line;
+            }
+            return a.path.localeCompare(b.path);
+        }
+        return b.score - a.score;
+    });
+    return {
+        documents: shortlistedDocuments.map(({ document, score }) => ({
+            path: document.path,
+            title: document.title,
+            score,
+            matched_headings: findMatchedHeadings(document, lowerQuery, queryTokens),
+            node_count: document.sections.length,
+        })),
+        sections: results.slice(0, limit),
+    };
+}
+function buildIndexedDocuments(sections) {
+    const byPath = new Map();
+    for (const section of sections) {
+        const bucket = byPath.get(section.path);
+        if (bucket) {
+            bucket.push(section);
+        }
+        else {
+            byPath.set(section.path, [section]);
+        }
+    }
+    const documents = [];
+    for (const [filePath, fileSections] of byPath.entries()) {
+        fileSections.sort((a, b) => a.start_line - b.start_line);
+        const headings = Array.from(new Set(fileSections
+            .flatMap((section) => section.heading_path ?? [])
+            .filter(Boolean)));
+        const title = fileSections.find((section) => section.level === 0)?.title ?? defaultFileTitle(filePath);
+        const searchText = [
+            filePath,
+            title,
+            headings.join(' '),
+        ].join('\n').trim();
+        const tokens = tokenize(searchText);
+        const termFreq = new Map();
+        for (const token of tokens) {
+            termFreq.set(token, (termFreq.get(token) ?? 0) + 1);
+        }
+        documents.push({
+            path: filePath,
+            title,
+            sections: fileSections,
+            lowerPath: filePath.toLowerCase(),
+            lowerTitle: title.toLowerCase(),
+            lowerJoined: `${filePath} ${title} ${headings.join(' ')}`.toLowerCase(),
+            headings,
+            termFreq,
+            docLen: tokens.length,
+        });
+    }
+    documents.sort((a, b) => a.path.localeCompare(b.path));
+    return documents;
+}
+function scoreDocuments(documents, queryTokens, lowerQuery) {
+    const docFreq = new Map();
+    let totalDocLen = 0;
+    for (const document of documents) {
+        totalDocLen += document.docLen;
+        for (const token of document.termFreq.keys()) {
+            docFreq.set(token, (docFreq.get(token) ?? 0) + 1);
+        }
+    }
+    const avgDocLen = documents.length > 0 ? Math.max(totalDocLen / documents.length, 1) : 1;
+    return documents.map((document) => {
+        const pseudoNode = {
+            section: {
+                wiki_id: document.sections[0]?.wiki_id ?? '',
+                wiki_slug: document.sections[0]?.wiki_slug ?? '',
+                wiki_name: document.sections[0]?.wiki_name ?? '',
+                node_id: `${document.path}:doc`,
+                path: document.path,
+                title: document.title,
+                heading_path: document.headings,
+                section_path: document.path,
+                level: 0,
+                start_line: 1,
+                end_line: 1,
+                content: '',
+            },
+            content: '',
+            lowerPath: document.lowerPath,
+            lowerTitle: document.lowerTitle,
+            lowerBody: '',
+            lowerJoined: document.lowerJoined,
+            termFreq: document.termFreq,
+            docLen: document.docLen,
+        };
+        return {
+            document,
+            score: scoreNode(pseudoNode, queryTokens, lowerQuery, docFreq, documents.length, avgDocLen),
+        };
+    });
+}
+function scoreTreeAwareNode(node, queryTokens, lowerQuery, documentScore, scope) {
+    const docFreq = new Map();
+    let totalDocLen = 0;
+    for (const entry of scope) {
+        totalDocLen += entry.docLen;
+        for (const token of entry.termFreq.keys()) {
+            docFreq.set(token, (docFreq.get(token) ?? 0) + 1);
+        }
+    }
+    const avgDocLen = scope.length > 0 ? Math.max(totalDocLen / scope.length, 1) : 1;
+    let score = scoreNode(node, queryTokens, lowerQuery, docFreq, scope.length, avgDocLen);
+    const reasoning = [];
+    if (documentScore > 0) {
+        score += documentScore * 0.35;
+        reasoning.push('selected from a high-scoring document');
+    }
+    if (lowerQuery && node.lowerTitle.includes(lowerQuery)) {
+        score += 2.5;
+        reasoning.push('section title directly matches the query');
+    }
+    const matchedAncestors = (node.section.heading_path ?? [])
+        .slice(0, -1)
+        .filter((heading) => heading.toLowerCase().includes(lowerQuery)
+        || queryTokens.some((token) => heading.toLowerCase().includes(token)));
+    if (matchedAncestors.length > 0) {
+        score += matchedAncestors.length * 1.25;
+        reasoning.push('ancestor headings match the query context');
+    }
+    const headingTokenHits = queryTokens.filter((token) => ((node.section.heading_path ?? []).some((heading) => heading.toLowerCase().includes(token)))).length;
+    if (headingTokenHits > 0) {
+        score += headingTokenHits * 0.6;
+        reasoning.push('heading path overlaps with query terms');
+    }
+    if (node.section.level > 0 && node.section.level <= 2) {
+        score += 0.2;
+    }
+    return { score, reasoning };
+}
+function findMatchedHeadings(document, lowerQuery, queryTokens) {
+    return document.headings.filter((heading) => {
+        const lower = heading.toLowerCase();
+        return (lowerQuery && lower.includes(lowerQuery))
+            || queryTokens.some((token) => lower.includes(token));
+    }).slice(0, 5);
+}
+function scoreNode(node, queryTokens, lowerQuery, docFreq, totalDocs, avgDocLen) {
+    const k1 = 1.5;
+    const b = 0.75;
+    const docLen = Math.max(node.docLen, 1);
+    let score = 0;
+    for (const token of queryTokens) {
+        const tf = node.termFreq.get(token) ?? 0;
+        if (tf === 0) {
+            continue;
+        }
+        const df = docFreq.get(token) ?? 0;
+        if (df === 0) {
+            continue;
+        }
+        const idf = Math.log(1 + ((totalDocs - df + 0.5) / (df + 0.5)));
+        score += idf * ((tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLen / avgDocLen))));
+    }
+    if (lowerQuery) {
+        if (node.lowerTitle.includes(lowerQuery)) {
+            score += 3;
+        }
+        else if (node.lowerJoined.includes(lowerQuery)) {
+            score += 2;
+        }
+        else if (node.lowerPath.includes(lowerQuery)) {
+            score += 1.5;
+        }
+        if (node.lowerBody.includes(lowerQuery)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+function buildSnippet(node, lowerQuery, queryTokens) {
+    const lines = [node.section.title, ...node.content.split('\n')];
+    for (const line of lines) {
+        const compact = compactWhitespace(line);
+        if (!compact) {
+            continue;
+        }
+        const lower = compact.toLowerCase();
+        if (lowerQuery && lower.includes(lowerQuery)) {
+            return truncateSnippet(compact, 220);
+        }
+    }
+    for (const line of lines) {
+        const compact = compactWhitespace(line);
+        if (!compact) {
+            continue;
+        }
+        const lower = compact.toLowerCase();
+        if (queryTokens.some((token) => lower.includes(token))) {
+            return truncateSnippet(compact, 220);
+        }
+    }
+    return truncateSnippet(compactWhitespace(node.content || node.section.section_path), 220);
+}
+// ---------------------------------------------------------------------------
+// Markdown parsing helpers
+// ---------------------------------------------------------------------------
+function extractMarkdownHeadings(lines, startIndex) {
+    const headings = [];
+    const stack = [];
+    let fenceMarker = '';
+    for (let i = startIndex; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim();
+        const marker = parseFenceMarker(trimmed);
+        if (marker) {
+            if (!fenceMarker) {
+                fenceMarker = marker;
+            }
+            else if (trimmed.startsWith(fenceMarker)) {
+                fenceMarker = '';
+            }
+            continue;
+        }
+        if (fenceMarker) {
+            continue;
+        }
+        const match = lines[i].match(MARKDOWN_HEADING_RE);
+        if (!match) {
+            continue;
+        }
+        const level = match[1].length;
+        const title = normalizeHeadingTitle(match[2]);
+        if (!title) {
+            continue;
+        }
+        while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+            stack.pop();
+        }
+        const headingPath = [...stack.map((entry) => entry.title), title];
+        headings.push({
+            title,
+            level,
+            line: i + 1,
+            path: headingPath,
+        });
+        stack.push({ title, level });
+    }
+    return headings;
+}
+function detectFrontMatterEnd(lines) {
+    if (lines.length === 0) {
+        return 0;
+    }
+    const first = lines[0].trim();
+    if (first !== '---' && first !== '+++') {
+        return 0;
+    }
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === first) {
+            return i + 1;
+        }
+    }
+    return 0;
+}
+function normalizeHeadingTitle(raw) {
+    return raw.replace(TRAILING_FENCE_RE, '').trim().replace(/^`+|`+$/g, '');
+}
+function parseNodeId(nodeId) {
+    const match = nodeId.match(/^(.*):(doc|preface|L(\d+))$/);
+    if (!match || !match[1]) {
+        throw new Error(`invalid wiki node_id: ${nodeId}`);
+    }
+    const filePath = normalizeRequiredWikiPath(match[1]);
+    if (match[2] === 'doc') {
+        return { path: filePath, kind: 'doc' };
+    }
+    if (match[2] === 'preface') {
+        return { path: filePath, kind: 'preface' };
+    }
+    return {
+        path: filePath,
+        kind: 'line',
+        line: Number.parseInt(match[3], 10),
+    };
+}
+function parseFenceMarker(line) {
+    if (line.startsWith('```')) {
+        return '```';
+    }
+    if (line.startsWith('~~~')) {
+        return '~~~';
+    }
+    return '';
+}
+function defaultFileTitle(filePath) {
+    const base = path.posix.basename(filePath, path.posix.extname(filePath));
+    return base.replaceAll('-', ' ').replaceAll('_', ' ').trim() || filePath;
+}
+function findFirstNonEmptyLine(lines, startLine, endLine) {
+    const start = Math.max(startLine, 1);
+    const end = Math.min(endLine, lines.length);
+    for (let i = start; i <= end; i += 1) {
+        if (lines[i - 1]?.trim()) {
+            return i;
+        }
+    }
+    return start;
+}
+// ---------------------------------------------------------------------------
+// Path & string utilities
+// ---------------------------------------------------------------------------
+function normalizeRef(ref) {
+    const value = ref?.trim();
+    return value ? value : undefined;
+}
+function normalizeWikiPath(value) {
+    if (!value) {
+        return '';
+    }
+    const normalized = toPosix(value.trim()).replace(/^\.?\//, '').replace(/^\/+/, '');
+    return normalized === '.' ? '' : normalized.replace(/\/+$/, '');
+}
+function normalizeRequiredWikiPath(value) {
+    const normalized = normalizeWikiPath(value);
+    if (!normalized) {
+        throw new Error('path is required');
+    }
+    return normalized;
+}
+function resolveAgentId(explicit) {
+    const value = explicit?.trim() || process.env.PRLL_AGENT_ID?.trim() || process.env.AGENT_ID?.trim();
+    return value || undefined;
+}
+function resolveMountPath(mountPath, mountRoot) {
+    const trimmedMountPath = mountPath.trim();
+    if (!trimmedMountPath) {
+        throw new Error('mount path is required');
+    }
+    if (mountRoot?.trim()) {
+        const absoluteRoot = path.resolve(mountRoot.trim());
+        const candidate = path.isAbsolute(trimmedMountPath)
+            ? path.resolve(trimmedMountPath)
+            : path.resolve(absoluteRoot, trimmedMountPath);
+        const relative = path.relative(absoluteRoot, candidate);
+        if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`)) {
+            throw new Error(`mount path "${mountPath}" escapes PRLL_WIKI_MOUNT_ROOT`);
+        }
+        return candidate;
+    }
+    if (path.isAbsolute(trimmedMountPath)) {
+        throw new Error('absolute mount path requires PRLL_WIKI_MOUNT_ROOT');
+    }
+    return path.resolve(trimmedMountPath);
+}
+function resolvePathInsideRoot(root, relativePath) {
+    const normalized = normalizeWikiPath(relativePath);
+    const candidate = path.resolve(root, normalized);
+    const relative = path.relative(root, candidate);
+    if (relative === '' || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`)) {
+        throw new Error(`path "${relativePath}" escapes wiki root`);
+    }
+    return candidate;
+}
+// ACL is now enforced server-side via path_scopes. These helpers are no-ops.
+function enforceAllowedPrefix(_pathPrefix, _allowedPrefixes) {
+    // No-op: server handles ACL via path_scopes.
+}
+function matchesAllowedPrefix(_filePath, _allowedPrefixes) {
+    // Server manifest already filters by ACL — all returned files are readable.
+    return true;
+}
+function isMarkdownFile(filePath) {
+    const ext = path.posix.extname(toPosix(filePath)).toLowerCase();
+    return ext === '.md' || ext === '.markdown' || ext === '.mdx';
+}
+function compactWhitespace(value) {
+    return value.trim().split(/\s+/).filter(Boolean).join(' ');
+}
+function truncateSnippet(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    if (limit <= 3) {
+        return value.slice(0, limit);
+    }
+    return `${value.slice(0, limit - 3)}...`;
+}
+function toPosix(value) {
+    return value.split(path.sep).join(path.posix.sep);
+}
+function normalizeOptionalString(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}
+async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function requireAgentId(ctx) {
+    const agentId = resolveAgentId(ctx.agentId);
+    if (!agentId) {
+        throw new Error('wiki write tools require PRLL_AGENT_ID or an explicit agentId');
+    }
+    return agentId;
+}
+// ---------------------------------------------------------------------------
+// Tokenizer (CJK-aware, for search/query)
+// ---------------------------------------------------------------------------
+function tokenize(text) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return [];
+    }
+    const tokens = [];
+    let word = '';
+    let cjkRun = '';
+    const flushWord = () => {
+        if (!word) {
+            return;
+        }
+        tokens.push(word.toLowerCase());
+        word = '';
+    };
+    const flushCjk = () => {
+        if (!cjkRun) {
+            return;
+        }
+        const chars = Array.from(cjkRun.toLowerCase());
+        tokens.push(...chars);
+        if (chars.length > 1) {
+            for (let i = 0; i < chars.length - 1; i += 1) {
+                tokens.push(chars[i] + chars[i + 1]);
+            }
+        }
+        cjkRun = '';
+    };
+    for (const char of Array.from(trimmed)) {
+        if (isCjkChar(char)) {
+            flushWord();
+            cjkRun += char;
+            continue;
+        }
+        if (/[0-9\p{L}]/u.test(char)) {
+            flushCjk();
+            word += char.toLowerCase();
+            continue;
+        }
+        flushWord();
+        flushCjk();
+    }
+    flushWord();
+    flushCjk();
+    return tokens;
+}
+function isCjkChar(char) {
+    const codePoint = char.codePointAt(0) ?? 0;
+    return ((codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+        (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x3040 && codePoint <= 0x309f) ||
+        (codePoint >= 0x30a0 && codePoint <= 0x30ff) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7af));
+}