wiki-formant 0.60.0 → 0.62.0

package/dist/tree.js

@@ -0,0 +1,122 @@
+// tree.ts – a wiki's category tree, and what a URL path means against it.
+//
+// Three wikis declared their tree three ways: radix-wiki's `TAG_HIERARCHY`
+// (slug + children, keys and sort inherited down the trail), caper's
+// `WIKI_CATEGORIES` (each node naming its full `tagPath`, with a `categoryTrail`
+// walk of its own) and acuiq's `WIKI_SECTIONS` (one flat level). Each then
+// re-derived the same answers by hand: is this a real category, which metadata
+// keys apply here, which article is this page "part of a series on", what sort
+// does a listing default to, which paths are back office.
+//
+// The node holds what every wiki reads; anything only one wiki reads (an XRD
+// threshold, a band, an icon set) rides on the node as an extra field, and the
+// app folds it from `trail`. Pure: no data access, so a client component and
+// the server route read paths through the same parser.
+const segmentsOf = (tagPath) => typeof tagPath === 'string' ? tagPath.split('/').filter(Boolean) : tagPath.filter(Boolean);
+export function createTree(nodes, opts = {}) {
+    const globalKeys = [...(opts.globalKeys ?? [])];
+    const cache = new Map();
+    function resolve(tagPath) {
+        const segments = segmentsOf(tagPath);
+        const key = segments.join('/');
+        const hit = cache.get(key);
+        if (hit)
+            return hit;
+        const trail = [];
+        const metadataKeys = [];
+        let level = nodes;
+        let sort = 'title';
+        let mainArticle;
+        let hidden = false;
+        for (const segment of segments) {
+            const node = level.find(n => n.slug === segment);
+            if (!node) {
+                const missing = { node: null, trail: [], valid: false, hidden: false, sort: 'title', metadataKeys: [] };
+                cache.set(key, missing);
+                return missing;
+            }
+            trail.push(node);
+            if (node.metadataKeys)
+                metadataKeys.push(...node.metadataKeys);
+            if (node.sort)
+                sort = node.sort;
+            if (node.mainArticle)
+                mainArticle = node.mainArticle;
+            hidden ||= !!node.hidden;
+            level = node.children ?? [];
+        }
+        metadataKeys.push(...globalKeys);
+        const resolved = { node: trail.at(-1) ?? null, trail, valid: trail.length > 0, hidden, sort, mainArticle, metadataKeys };
+        cache.set(key, resolved);
+        return resolved;
+    }
+    /** Every path in the tree, depth first, parents before children. */
+    function paths(level = nodes, parent = '', inherited = false, depth = 0) {
+        return level.flatMap(node => {
+            const path = parent ? `${parent}/${node.slug}` : node.slug;
+            const hidden = inherited || !!node.hidden;
+            return [{ path, node: node, hidden, depth }, ...paths(node.children ?? [], path, hidden, depth + 1)];
+        });
+    }
+    const all = paths();
+    return {
+        nodes,
+        resolve,
+        paths: () => all,
+        /** Back-office paths, which a listing leaves out unless it names one. Pass to `wikiStore({ hidden })`. */
+        hiddenPaths: all.filter(p => p.hidden && p.path).map(p => p.path),
+        isValid: (tagPath) => resolve(tagPath).valid,
+        node: (tagPath) => resolve(tagPath).node,
+        metadataKeys: (tagPath) => resolve(tagPath).metadataKeys,
+        /** A category's name, or its last segment unslugged when the tree does not know it. */
+        label: (tagPath) => resolve(tagPath).node?.name ?? (segmentsOf(tagPath).at(-1) ?? '').replace(/-/g, ' '),
+        /**
+         * One crumb per segment, so the trail can never be shorter than the URL. A
+         * segment the tree knows is a link to its category; one it does not is text.
+         */
+        crumbs: (tagPath) => {
+            const segments = segmentsOf(tagPath);
+            return segments.map((segment, i) => {
+                const path = segments.slice(0, i + 1).join('/');
+                const node = resolve(path).node;
+                return { path, label: node?.name ?? segment.replace(/-/g, ' '), linked: !!node };
+            });
+        },
+    };
+}
+/** The views a page or a category has beside itself, each a final path segment. */
+export const WIKI_MODES = ['edit', 'history'];
+/**
+ * What a path means: the home page, a category (its hub article is the empty
+ * slug), a page, or nothing, each optionally in one of `modes`. A path that is
+ * itself a category wins over a mode suffix, so a category named `history` is
+ * still reachable; `/<category>/edit` edits the category's hub.
+ *
+ * Static routes are the app's: check them before calling this.
+ */
+export function parseWikiPath(tree, segments = [], { modes = WIKI_MODES } = {}) {
+    const parts = segments.filter(Boolean);
+    const last = parts.at(-1);
+    const mode = last && modes.includes(last) && !tree.isValid(parts) ? last : null;
+    const path = mode ? parts.slice(0, -1) : parts;
+    const invalid = { type: 'invalid', tagPath: '', slug: '', mode: null };
+    if (!path.length)
+        return { type: 'home', tagPath: '', slug: '', mode };
+    if (tree.isValid(path))
+        return { type: 'category', tagPath: path.join('/'), slug: '', mode };
+    if (path.length < 2 || !tree.isValid(path.slice(0, -1)))
+        return invalid;
+    return { type: 'page', tagPath: path.slice(0, -1).join('/'), slug: path.at(-1), mode };
+}
+/**
+ * A slug no page in `tagPath` can hold, because `parseWikiPath` reads that URL
+ * as something else: a mode, or a child category. Creating a page treats it as
+ * taken.
+ */
+export function isReservedSlug(tree, tagPath, slug, modes = WIKI_MODES) {
+    return modes.includes(slug) || tree.isValid([...segmentsOf(tagPath), slug]);
+}
+/** A page's path: the category for its hub, `/` for the home page. */
+export function wikiPath(tagPath, slug) {
+    return `/${[tagPath, slug].filter(Boolean).join('/')}`;
+}

package/dist/wiki-tools.d.ts

@@ -0,0 +1,66 @@
+import { type McpTool } from './mcp.js';
+import { type CorpusSection } from './corpus.js';
+import { type WikiNode, type WikiTree } from './tree.js';
+import type { WikiStore, WikiPageListing, PageMetadata } from './store.js';
+import type { DiffBlock } from './revisions.js';
+type ToolName = 'search_wiki' | 'get_page' | 'get_pages' | 'list_pages' | 'get_categories' | 'get_recent_changes' | 'get_full_corpus';
+export interface WikiToolsOptions<B extends DiffBlock> {
+    store: WikiStore<B>;
+    tree: WikiTree<WikiNode>;
+    /** A page's absolute, canonical address. */
+    url: (tagPath: string, slug: string) => string;
+    /** A page's blocks as plain prose: what `get_page` returns and `chars` counts. */
+    text: (blocks: B[]) => string;
+    /** The wiki as the descriptions name it: "the Radix Wiki", "this DAO's wiki". */
+    noun: string;
+    /** The corpus document's heading. */
+    corpusTitle: string;
+    /** A prefix a pasted page URL may carry before the page's path, such as "/wiki". */
+    pathPrefix?: string;
+    /** Back-office pages are private here, not merely unlisted: no tool reads one. */
+    privateHidden?: boolean;
+    /** What a listing row adds from the page's metadata, or null for nothing. */
+    metadata?: (tagPath: string, metadata: PageMetadata) => Record<string, unknown> | null;
+    /** A category's name as the tree lists it. Defaults to the node's `name`. */
+    label?: (node: WikiNode) => string;
+    /** The corpus as sections, when the app's llms-full.txt sets their form. Defaults to one per page from the store. */
+    corpus?: (tagPath?: string) => Promise<CorpusSection[]>;
+    /** What an empty search says. */
+    noMatch?: (query: string, tagPath?: string) => string;
+    /** A2A skills by tool, beside the defaults. */
+    skills?: Partial<Record<ToolName, McpTool['skill']>>;
+}
+/** A read tool: the package's always say whether they write. */
+export type WikiTool = McpTool & Required<Pick<McpTool, 'title' | 'annotations'>>;
+type Rowable<B> = Pick<WikiPageListing, 'title' | 'tagPath' | 'slug' | 'snippet' | 'metadata' | 'updatedAt' | 'lastVerifiedAt'> & {
+    content?: B[];
+};
+/** The row every listing returns: search, list, recent changes, and the app's own `?q=` twin. */
+declare const rowFor: <B extends DiffBlock>(o: Pick<WikiToolsOptions<B>, "url" | "text" | "metadata">) => (p: Rowable<B>) => {
+    metadata?: Record<string, unknown> | undefined;
+    lastVerified?: string | undefined;
+    snippet: string;
+    updatedAt: string;
+    chars?: number | undefined;
+    title: string;
+    path: string;
+    url: string;
+    tagPath: string;
+    slug: string;
+};
+export type WikiRow = ReturnType<ReturnType<typeof rowFor>>;
+/**
+ * A page of ranked search rows, as `search_wiki` returns them. An app's plain
+ * GET `?q=` and its search page call this too, so the three stay row for row
+ * the same.
+ */
+export declare function searchWiki<B extends DiffBlock>(o: Pick<WikiToolsOptions<B>, 'store' | 'privateHidden' | 'url' | 'text' | 'metadata'>, query: string, { tagPath, page, size }?: {
+    tagPath?: string;
+    page?: number;
+    size?: number;
+}): Promise<{
+    items: WikiRow[];
+    total: number;
+}>;
+export declare function wikiReadTools<B extends DiffBlock>(o: WikiToolsOptions<B>): WikiTool[];
+export {};

package/dist/wiki-tools.js

@@ -0,0 +1,342 @@
+// wiki-tools.ts – the read half of a wiki's MCP server, over its store and tree.
+//
+// radix-wiki wrote these seven tools first; caper copied them, kept the names
+// and defaults, and added a batch read, a `path` on every row, a size and a miss
+// that names the nearest pages. Both then ran them over Prisma queries of their
+// own beside the store. miow had none, so a wiki it hosted answered no agent.
+// One set now, the union of the two, over `wiki-formant/store`: every wiki that
+// lists a page here lists it the way its HTML route does, hidden paths included.
+//
+// What is the app's: where a page lives (`url`), how blocks read as text,
+// what a row adds (`metadata`), and how its corpus reads when it has an
+// llms-full.txt to match. Writes stay with each app, because who may write
+// is the one thing no two of them agree on.
+import { McpToolError, readArgs, withAdjustments } from './mcp.js';
+import { listEnvelope } from './pagination.js';
+import { CORPUS_BUDGET, sliceCorpus } from './corpus.js';
+import { isoDate } from './freshness.js';
+import { wikiPath } from './tree.js';
+import { describe } from './metadata.js';
+import { openingText } from './text.js';
+const MAX_BATCH_PATHS = 20;
+const READ = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+const pathOf = (tagPath, slug) => wikiPath(tagPath, slug).slice(1);
+/** Whether a tag path is closed to these tools: a back office the wiki keeps private. */
+const offFor = (o) => (tagPath) => !!tagPath && !!o.privateHidden && o.store.isHidden(tagPath);
+/** The row every listing returns: search, list, recent changes, and the app's own `?q=` twin. */
+const rowFor = (o) => (p) => {
+    const meta = o.metadata?.(p.tagPath, (p.metadata ?? {}));
+    return {
+        title: p.title,
+        path: pathOf(p.tagPath, p.slug),
+        url: o.url(p.tagPath, p.slug),
+        tagPath: p.tagPath,
+        slug: p.slug,
+        ...(p.content ? { chars: o.text(p.content).length } : {}),
+        snippet: p.snippet,
+        updatedAt: isoDate(p.updatedAt),
+        ...(p.lastVerifiedAt ? { lastVerified: isoDate(p.lastVerifiedAt) } : {}),
+        ...(meta ? { metadata: meta } : {}),
+    };
+};
+/**
+ * A page of ranked search rows, as `search_wiki` returns them. An app's plain
+ * GET `?q=` and its search page call this too, so the three stay row for row
+ * the same.
+ */
+export async function searchWiki(o, query, { tagPath, page = 1, size = 20 } = {}) {
+    if (offFor(o)(tagPath))
+        return { items: [], total: 0 };
+    const { items, total } = await o.store.search(query, { tagPath, skip: (page - 1) * size, take: size, content: true });
+    return { items: items.map(rowFor(o)), total };
+}
+export function wikiReadTools(o) {
+    const { store, tree, noun } = o;
+    const off = offFor(o);
+    const summary = rowFor(o);
+    /** "tag/path/slug", from the path itself or a pasted URL of it. */
+    const target = (input) => {
+        let clean = input.trim().replace(/^https?:\/\/[^/]+/, '');
+        if (o.pathPrefix && (clean === o.pathPrefix || clean.startsWith(`${o.pathPrefix}/`)))
+            clean = clean.slice(o.pathPrefix.length);
+        const parts = clean.split(/[?#]/)[0].split('/').filter(Boolean);
+        const slug = parts.pop();
+        return slug ? { tagPath: parts.join('/'), slug } : null;
+    };
+    /** The article at a path, else the hub of the category the whole path is. The article wins where both exist. */
+    const read = async (t) => {
+        const page = (await store.get(t.tagPath, t.slug)) ?? (await store.get(pathOf(t.tagPath, t.slug), ''));
+        return page && !off(page.tagPath) ? page : null;
+    };
+    const full = (page) => ({
+        ...summary({ ...page, snippet: describe(openingText(page.content)) }),
+        version: page.version,
+        content: o.text(page.content),
+    });
+    const sections = async (tagPath) => {
+        if (o.corpus)
+            return o.corpus(tagPath);
+        const pages = (await store.corpus())
+            .filter(p => !(p.tagPath === '' && p.slug === '') && (!tagPath || p.tagPath === tagPath || p.tagPath.startsWith(`${tagPath}/`)))
+            .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+        return pages.map(p => {
+            const path = pathOf(p.tagPath, p.slug);
+            return { path, tagPath: p.tagPath, section: `## ${p.title}\n\nPath: ${path}\nURL: ${o.url(p.tagPath, p.slug)}\nUpdated: ${isoDate(p.updatedAt)}\n\n${o.text(p.content)}` };
+        });
+    };
+    const tools = [
+        {
+            name: 'search_wiki',
+            title: 'Search the wiki',
+            annotations: READ,
+            skill: { id: 'search', tags: ['search', 'wiki'] },
+            description: `Keyword search across ${noun}: the first call when you know what you are looking for but not where it lives. ` +
+                'Matches titles and body prose, ranked in four tiers: titles starting with the term, titles containing it, literal body hits, then English full-text hits by relevance, which stem words and drop stopwords. ' +
+                'Not semantic: one distinctive word beats a sentence. ' +
+                'Each row carries a `path`, its size in `chars` and a snippet windowed on the match. Feed the paths to get_pages in one call rather than looping get_page. ' +
+                'Narrow with tagPath when a term is common. Defaults: page 1, pageSize 20 (max 50); keep paging while `hasMore` is true.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search term, matched against page titles and body text' },
+                    tagPath: { type: 'string', description: 'Only pages at this tag path, e.g. a path from get_categories' },
+                    page: { type: 'number', description: '1-based page number (default 1)' },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 50)' },
+                },
+                required: ['query'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const query = r.str('query');
+                const tagPath = r.str('tagPath') || undefined;
+                const page = r.num('page', 1, 1, 100_000);
+                const size = r.num('pageSize', 20, 1, 50);
+                if (!query)
+                    throw new McpToolError('`query` is empty. Pass a keyword to search for, or call list_pages to enumerate a branch instead.');
+                const { items, total } = await searchWiki(o, query, { tagPath, page, size });
+                return withAdjustments(r, {
+                    query,
+                    ...listEnvelope(items, total, page, size, o.noMatch?.(query, tagPath)
+                        ?? `Nothing matches "${query}"${tagPath ? ` under "${tagPath}"` : ''}. Search is keyword, not semantic: try one distinctive word${tagPath ? ', or drop the tagPath filter' : ''}, or call get_categories to see what ${noun} covers.`),
+                });
+            },
+        },
+        {
+            name: 'get_page',
+            title: 'Read a page',
+            annotations: READ,
+            skill: { id: 'read', tags: ['read', 'content', 'article'] },
+            description: `One page of ${noun} in full: its text, version, update date and metadata. ` +
+                'Address it by `path` ("tag/path/slug", exactly the `path` or `url` a listing returns), or by `tagPath` + `slug`; a category\'s own path reads its hub article. Not a title. ' +
+                'For 2 to 20 pages call get_pages, one round trip rather than N. A miss names the nearest pages, so a wrong guess is fixed in one retry. ' +
+                'A page\'s URL with `.md` appended is its markdown.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'The page\'s whole path, e.g. "developers/scrypto/blueprints". Preferred over tagPath + slug.' },
+                    tagPath: { type: 'string', description: 'Tag path only ("" for a top-level page). Ignored when `path` is set.' },
+                    slug: { type: 'string', description: 'Page slug. Ignored when `path` is set.' },
+                },
+                requireOneOf: ['path', 'slug'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const raw = r.str('path');
+                const t = raw ? target(raw) : { tagPath: r.str('tagPath'), slug: r.str('slug') };
+                if (!t?.slug)
+                    throw new McpToolError('Pass either `path` ("tag/path/slug") or `slug` (with optional `tagPath`).');
+                const page = await read(t);
+                if (!page) {
+                    const near = await store.search(t.slug.replace(/-/g, ' '), { take: 5 });
+                    throw new McpToolError(`No page at path "${pathOf(t.tagPath, t.slug)}".`, {
+                        didYouMean: near.items.filter(p => !off(p.tagPath)).map(p => ({ path: pathOf(p.tagPath, p.slug), title: p.title })),
+                        hint: 'Paths are exact. Use search_wiki for a keyword, or list_pages with the tagPath to enumerate the branch.',
+                    });
+                }
+                return withAdjustments(r, full(page));
+            },
+        },
+        {
+            name: 'get_pages',
+            title: `Read up to ${MAX_BATCH_PATHS} pages`,
+            annotations: READ,
+            description: `Batch read: 1 to ${MAX_BATCH_PATHS} pages of ${noun} in full in one call, which is how to read search or listing results. ` +
+                'Pass `paths` as the listings return them. Paths that do not exist come back in `missing` rather than failing the call, ' +
+                `anything past ${MAX_BATCH_PATHS} in \`remaining\`, and pages past \`maxChars\` (default 250000) in \`omitted\` with their sizes.`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    paths: { type: 'array', items: { type: 'string' }, description: `Page paths, 1 to ${MAX_BATCH_PATHS} per call` },
+                    maxChars: { type: 'number', description: 'Total characters across the pages returned (default 250000, max 1000000)' },
+                },
+                required: ['paths'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const maxChars = r.num('maxChars', 250_000, 1_000, 1_000_000);
+                const requested = [...new Set(r.list('paths').map(s => String(s).trim()).filter(Boolean))];
+                if (!requested.length)
+                    throw new McpToolError('`paths` is empty. Pass at least one page path.', { hint: 'search_wiki and list_pages return a `path` for every result.' });
+                const taken = requested.slice(0, MAX_BATCH_PATHS);
+                const remaining = requested.slice(MAX_BATCH_PATHS);
+                if (remaining.length)
+                    r.note({ param: 'paths', requested: requested.length, used: taken.length, reason: `max ${MAX_BATCH_PATHS} paths per call; the rest are listed in \`remaining\`` });
+                const found = await Promise.all(taken.map(async (input) => {
+                    const t = target(input);
+                    return { input, page: t && (await read(t)) };
+                }));
+                const pages = [];
+                const missing = [];
+                const omitted = [];
+                let used = 0;
+                for (const { input, page } of found) {
+                    if (!page) {
+                        missing.push(input);
+                        continue;
+                    }
+                    const row = full(page);
+                    // At least one page always comes back, so one oversized page can still be read.
+                    if (pages.length && used + row.content.length > maxChars) {
+                        omitted.push({ path: row.path, chars: row.content.length });
+                        continue;
+                    }
+                    used += row.content.length;
+                    pages.push(row);
+                }
+                return withAdjustments(r, {
+                    requested: requested.length,
+                    returned: pages.length,
+                    characters: used,
+                    maxChars,
+                    pages,
+                    ...(missing.length ? { missing, missingHint: 'Not found. Re-check the path with search_wiki or list_pages.' } : {}),
+                    ...(omitted.length ? { omitted, omittedHint: 'Skipped to stay inside maxChars. Ask for these on their own or raise maxChars.' } : {}),
+                    ...(remaining.length ? { remaining } : {}),
+                });
+            },
+        },
+        {
+            name: 'list_pages',
+            title: 'List pages',
+            annotations: READ,
+            skill: { id: 'list', tags: ['list', 'browse', 'categories'] },
+            description: `Browse ${noun} by tag path rather than by keyword: every page under a branch, newest first by default. ` +
+                '`tagPath` matches the branch and everything beneath it; omit it to walk the whole wiki. Sort by title for an A–Z pass. ' +
+                'Same rows as search_wiki, with `totalPages`, `hasMore` and `nextPage`. Defaults: page 1, pageSize 20 (max 100).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tagPath: { type: 'string', description: 'The branch to list, e.g. a path from get_categories. Includes its descendants.' },
+                    sort: { type: 'string', enum: ['title', 'updatedAt'], description: 'Sort order (default "updatedAt", newest first)' },
+                    page: { type: 'number', description: '1-based page number (default 1)' },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 100)' },
+                },
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const tagPath = r.str('tagPath') || undefined;
+                const page = r.num('page', 1, 1, 100_000);
+                const size = r.num('pageSize', 20, 1, 100);
+                const sort = r.str('sort') === 'title' ? 'title' : 'recent';
+                const { items, total } = off(tagPath) ? { items: [], total: 0 } : await store.branch({ tagPath, sort, limit: size, offset: (page - 1) * size });
+                return withAdjustments(r, {
+                    ...(tagPath ? { tagPath } : {}),
+                    ...listEnvelope(items.map(summary), total, page, size, tagPath ? `No pages at tagPath "${tagPath}". Call get_categories for the tag paths that exist.` : `${noun} has no pages yet.`),
+                });
+            },
+        },
+        {
+            name: 'get_categories',
+            title: 'List categories',
+            annotations: READ,
+            description: `The category tree of ${noun}, the cheapest way to orient before searching. ` +
+                'Each node carries its `path` (a tagPath list_pages and search_wiki take), name, description, `pageCount` (pages filed at that path) and `pageCountDeep` (with every descendant). ' +
+                '`tagPaths` lists every tag path that holds pages, including any the tree does not name.',
+            inputSchema: { type: 'object', properties: {} },
+            handler: async () => {
+                const rows = await store.counts();
+                const exact = (path) => rows.find(c => c.tagPath === path)?.pages ?? 0;
+                const deep = (path) => rows.filter(c => c.tagPath === path || c.tagPath.startsWith(`${path}/`)).reduce((n, c) => n + c.pages, 0);
+                const build = (nodes, parent) => nodes.filter(n => !n.hidden && n.slug).map(n => {
+                    const path = parent ? `${parent}/${n.slug}` : n.slug;
+                    const children = n.children?.length ? build(n.children, path) : [];
+                    return {
+                        path,
+                        name: o.label?.(n) ?? n.name,
+                        ...(n.description ? { description: n.description } : {}),
+                        pageCount: exact(path),
+                        pageCountDeep: deep(path),
+                        ...(children.length ? { children } : {}),
+                    };
+                });
+                return {
+                    totalPages: rows.reduce((n, c) => n + c.pages, 0),
+                    categories: build(tree.nodes, ''),
+                    tagPaths: [...rows].sort((a, b) => b.pages - a.pages).map(c => ({ path: c.tagPath, pageCount: c.pages })),
+                };
+            },
+        },
+        {
+            name: 'get_recent_changes',
+            title: 'Recent changes',
+            annotations: READ,
+            description: `Pages of ${noun} edited within the last N days, newest first: what to poll when you are watching the wiki rather than reading it. ` +
+                'Same rows as list_pages. Defaults: days 7 (max 30), limit 20 (max 50). `truncated: true` means the limit cut the list; raise it, or page through list_pages.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    days: { type: 'number', description: 'Look back this many days (default 7, max 30)' },
+                    limit: { type: 'number', description: 'Most pages returned (default 20, max 50)' },
+                },
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const days = r.num('days', 7, 1, 30);
+                const limit = r.num('limit', 20, 1, 50);
+                // N × 24h back, not N calendar days: a DST change would move the window by an hour.
+                const since = new Date(Date.now() - days * 86_400_000);
+                const { items, total } = await store.branch({ sort: 'recent', limit, since });
+                return withAdjustments(r, {
+                    days,
+                    since: since.toISOString(),
+                    limit,
+                    total,
+                    count: items.length,
+                    truncated: total > items.length,
+                    pages: items.map(summary),
+                });
+            },
+        },
+        {
+            name: 'get_full_corpus',
+            title: 'Whole corpus',
+            annotations: READ,
+            description: `The whole of ${noun} as one text document, for bulk ingestion. ` +
+                'Preflight first: sizeOnly=true returns the character count, a token estimate, the per-branch breakdown and the largest pages. ' +
+                `Then pull it with \`maxChars\` (default ${CORPUS_BUDGET.default}, max ${CORPUS_BUDGET.max}), or one branch at a time with \`tagPath\`. ` +
+                'Truncation is page-aligned: `truncated`, `omittedPages` and `nextSkip` say where to resume (pass skip=nextSkip). For a handful of pages get_pages is cheaper.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sizeOnly: { type: 'boolean', description: 'Sizes and breakdowns only, no document. Do this before the first real pull.' },
+                    tagPath: { type: 'string', description: 'One branch and its descendants. Omit for everything.' },
+                    maxChars: { type: 'number', description: `Character budget for \`document\` (default ${CORPUS_BUDGET.default}, max ${CORPUS_BUDGET.max})` },
+                    skip: { type: 'number', description: 'Resume from this page index: the `nextSkip` of the previous truncated call (default 0)' },
+                },
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const tagPath = r.str('tagPath') || undefined;
+                const slice = sliceCorpus(off(tagPath) ? [] : await sections(tagPath), {
+                    title: o.corpusTitle,
+                    sizeOnly: r.bool('sizeOnly'),
+                    maxChars: r.num('maxChars', CORPUS_BUDGET.default, CORPUS_BUDGET.min, CORPUS_BUDGET.max),
+                    skip: r.num('skip', 0, 0, 1_000_000),
+                    hint: 'Pull with maxChars, or one branch at a time with tagPath. get_pages is cheaper for a handful of pages.',
+                });
+                return withAdjustments(r, { scope: o.corpusTitle, ...(tagPath ? { tagPath } : {}), ...slice });
+            },
+        },
+    ];
+    return tools.map(t => (o.skills?.[t.name] ? { ...t, skill: o.skills[t.name] } : t));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",
@@ -117,6 +117,26 @@
       "import": "./dist/search.js",
       "default": "./dist/search.js"
     },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js",
+      "default": "./dist/store.js"
+    },
+    "./tree": {
+      "types": "./dist/tree.d.ts",
+      "import": "./dist/tree.js",
+      "default": "./dist/tree.js"
+    },
+    "./category": {
+      "types": "./dist/category.d.ts",
+      "import": "./dist/category.js",
+      "default": "./dist/category.js"
+    },
+    "./wiki-tools": {
+      "types": "./dist/wiki-tools.d.ts",
+      "import": "./dist/wiki-tools.js",
+      "default": "./dist/wiki-tools.js"
+    },
     "./feed": {
       "types": "./dist/feed.d.ts",
       "import": "./dist/feed.js",
@@ -296,6 +316,7 @@
     "sanitize-html": "^2.17.7"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.3.9",
     "@radixdlt/rola": "^2.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
@@ -308,12 +329,12 @@
     "typescript": "^5.9.0"
   },
   "peerDependencies": {
+    "@radixdlt/rola": ">=2",
+    "@vercel/blob": ">=2",
+    "jose": ">=6",
     "pg": ">=8",
     "react": ">=18",
-    "jose": ">=6",
-    "@radixdlt/rola": ">=2",
-    "sharp": ">=0.33",
-    "@vercel/blob": ">=2"
+    "sharp": ">=0.33"
   },
   "peerDependenciesMeta": {
     "react": {

package/prisma/wiki.prisma

@@ -0,0 +1,62 @@
+// Shipped by wiki-formant (`npx prisma-models`). Edit it there, not here:
+// `prisma-models --check` fails on a copy that has drifted.
+//
+// A wiki's pages and their revisions, read and written by wiki-formant/store.
+// Its SQL names these tables and columns as written, so they carry no @@map.
+// `siteId` is "" in an app that serves one wiki; a multi-tenant app keys every
+// row to its site, and caper keys a DAO's own layer to the DAO.
+//
+// A page lives at `tagPath` + `slug`. The empty slug is the category's own hub
+// article, and `''/''` the home page. Everything a page says beyond its blocks
+// and title is `metadata`: facet keys, an excerpt, a banner, a subtitle. Which
+// keys a listing may carry is the tree's answer, not the column's.
+//
+// Ids and timestamps default in the database, so the store's raw SQL and a
+// Prisma client write the same rows. `authorId` is the app's own user key, as
+// text; it has no relation because no two apps key their users alike.
+
+model WikiPage {
+  id             String         @id @default(dbgenerated("(gen_random_uuid())::text"))
+  siteId         String         @default("")
+  tagPath        String         @default("")
+  slug           String
+  title          String
+  content        Json           @default("[]")
+  metadata       Json           @default("{}")
+  version        String         @default("1.0.0")
+  authorId       String?
+  lastVerifiedAt DateTime?      @db.Timestamptz(3)
+  createdAt      DateTime       @default(now()) @db.Timestamptz(3)
+  updatedAt      DateTime       @default(now()) @db.Timestamptz(3)
+  // Title at weight A, block prose at B, GENERATED ALWAYS ... STORED by
+  // `npx fts-ddl '"WikiPage"'`. Declared only so `db push` leaves it alone:
+  // push must never create it, since Prisma would write a plain column that
+  // stays empty. Read only through raw SQL.
+  searchTsv      Unsupported("tsvector")? @map("search_tsv")
+  revisions      WikiRevision[]
+
+  @@unique([siteId, tagPath, slug])
+  @@index([siteId, tagPath, updatedAt])
+  @@index([siteId, updatedAt])
+  // Declared for the same reason: undeclared, push drops it.
+  @@index([searchTsv], type: Gin, map: "WikiPage_search_tsv_idx")
+}
+
+// One row per saved version, newest last. A revision holds the whole page as
+// it was saved; what changed is diffed from consecutive rows when it is read,
+// so a script's revision and the editor's carry the same history.
+model WikiRevision {
+  id         String   @id @default(dbgenerated("(gen_random_uuid())::text"))
+  pageId     String
+  title      String
+  content    Json
+  version    String
+  changeType String
+  message    String?
+  authorId   String?
+  createdAt  DateTime @default(now()) @db.Timestamptz(3)
+  page       WikiPage @relation(fields: [pageId], references: [id], onDelete: Cascade)
+
+  @@index([pageId, createdAt])
+  @@index([authorId, createdAt])
+}