wiki-formant 0.65.1 → 0.69.0

package/README.md

@@ -79,7 +79,7 @@ const view = await categoryView({ tree, taxonomy, pages: store }, 'ecosystem', s
 
 ## Wiki read tools
 
-`wikiReadTools` is the read half of a wiki's MCP server over its store and tree: `search_wiki`, `get_page`, `get_pages`, `list_pages`, `get_categories`, `get_recent_changes` and `get_full_corpus`. `searchWiki` is the same rows for an app's plain-GET `?q=` and its search page, so the three never disagree.
+`wikiReadTools` is the read half of a wiki's MCP server over its store and tree: `search_wiki`, `get_page`, `get_pages`, `list_pages`, `get_categories`, `get_recent_changes`, `get_full_corpus` and `get_page_history`. `searchWiki` is the same rows for an app's plain-GET `?q=` and its search page, so the three never disagree.
 
 ```ts
 import { wikiReadTools, searchWiki } from 'wiki-formant/wiki-tools';
@@ -90,6 +90,7 @@ const { items, total } = await searchWiki(reading, 'validators', { page: 1, size
 ```
 
 - Every row carries `path`, which every read tool takes back, and `chars` where the page's text was read. A pasted URL resolves, with `pathPrefix` stripped; a category's path reads its hub article; a miss names the nearest pages.
+- Every row carries the page `id` too, which a `pageList` block takes. `get_page` with `blocks: true` returns the stored blocks, the page `id`, its whole metadata and `version`: what an edit starts from. `forEdit` adds what the app's write tool takes beside them, and `authors` names each revision's author in `get_page_history`.
 - `privateHidden` closes the back office to every tool; without it a hidden page is unlisted but readable by path, as its URL is.
 - `metadata`, `label`, `corpus`, `noMatch` and `skills` are the app's: what a row adds, how a category is named, the sections its llms-full.txt is made of, what an empty search says, and the A2A skills.
 - Writes stay with each app, because who may write is the one thing no two of them agree on.
@@ -248,6 +249,16 @@ process.exit(t.summary());
 
 What stays in your repo is fixtures: which tools you expect, what a good answer from each looks like, and which text surfaces you publish. `payloadBudget` weighs every listed call **and** every read-only tool that takes no required arguments, because the one tool nobody thought to list is the one that answers with 3.3 MB; pass a per-call `maxBytes` for a bulk-export tool that is deliberately large. It also asserts that a JSON answer arrived with `structuredContent`.
 
+The drift checks hold an MCP server to what its own site does, so a tool cannot describe, accept or return something the site does not:
+
+- `manifestParity(t, { writeAuth? })`: `/.well-known/mcp.json` is `tools/list` tool for tool, names the endpoint under test, and states write auth only where a write tool is listed (both ways, given `writeAuth`).
+- `rowParity(t, label, mcp, rest)`: a tool's answer and the GET API's or `?q=` page's are identical, and not both empty.
+- `twinParity(t, label, twinUrl, text)`: a read tool's text is the page's markdown twin, past its frontmatter and the title line.
+- `editReadChecks(t, { path, rows?, validate?, endpoint? })`: rows carry page ids, `get_page` with `blocks: true` returns blocks the site's own `validate` accepts and a version, and `get_page_history`'s newest revision is that version.
+- `roundTrip(t, label, { read, write })`: what a read tool hands out, the write tool takes back unchanged, and the next read matches.
+- `openapiWriteParity(t, [[path, method, tool], …])`: every field an OpenAPI write documents, the matching tool takes.
+- `rolaOriginCheck(t)`: a challenge tool's ROLA recipe names the origin under test.
+
 `standardVersionSources(t, openapiPaths)` is the `versionCoherence` map every S10 surface serves — both agent-card paths, `mcp.json`, the server card and each path the OpenAPI document answers at — so a suite names only the paths it adds. `t.rpcAt(endpoint, …)` and `t.callAt` drive a second MCP endpoint on the same surface with the same backoff, User-Agent and tally.
 
 ```ts
@@ -542,6 +553,18 @@ export const SITE = siteRefs(SITE_URL);
 <JsonLd data={siteGraphLd({ name, url: SITE_URL, logo, sameAs, searchUrl, api })} />
 ```
 
+## Social cards
+
+`wiki-formant/og` is the card at `/og`, as the element `next/og`'s `ImageResponse` takes. `SocialCard` is the frame: an eyebrow, a title fitted with `describe`, anything under it, then the description and the site's mark along the foot, bottom-aligned on a 1200×630 field. The field and the art are arguments, because they were all that differed: two wikis had each written the same seeded gradient with translucent circles, which is `bubbles(rand, { field, colors })`, and a third draws its own art and passes it as `art`. `cardRandom(...text)` seeds either from the page, so one page always draws the same card. `OG_SIZE` and `OG_HEADERS` (a day at the CDN, a week stale) go on the response.
+
+```tsx
+const rand = cardRandom(title, eyebrow);
+const { background, art } = bubbles(rand, { field: [BG, NAVY], colors: [GREEN, ORANGE] });
+return new ImageResponse(<SocialCard {...{ title, eyebrow, description, background, art }} mark="example.org" colors={{ text, muted, accent }} fontFamily="Inter" />, { ...OG_SIZE, headers: OG_HEADERS, fonts: await fonts });
+```
+
+Fonts stay with the site: Next traces a font file into the function only from a literal path in the app's own code, and satori reads TTF or OTF, never the woff2 `next/font` serves. The frame never sets a style key to `undefined`, which satori throws on rather than skipping; `scrim` darkens the foot for art that is a photograph.
+
 ## Revisions
 
 What changed between two versions of a page, and therefore which semver bump to
@@ -884,7 +907,8 @@ referring host), top and entry pages, countries, devices, visitors and agents by
 day, the agents by name, MCP tool calls, and the searches that found nothing.
 An agent is counted as a visitor is, one address and user agent a day, from its
 `AI Bot Visit` and `MCP Call` events; it runs no page script, so it is never
-among the visitors. `ownAgents` leaves the site's own out. A visit is a run of one
+among the visitors, and `visitors_incl_agents` counts the two at once.
+`ownAgents` leaves the site's own out of both. A visit is a run of one
 visitor's views with no gap over 30 minutes. A multi-tenant app passes a `site`
 key to every call and a `site` resolver to `collect`.
 
@@ -918,7 +942,7 @@ export const POST = gate.route;
 export const DELETE = gate.signOut;
 
 // src/app/stats/page.tsx
-const q = statsQuery(params); // ?days= (1, 7, 30, 90, 365 or all, else 30) and the filters
+const q = statsQuery(params); // ?days= (1, 7, 30, 90, 365 or all, else 30), ?agents=apart and the filters
 return (
   <StatsGate gate={gate} session={(await cookies()).get(gate.cookie)?.value} invite={params.invite} host="caper.network">
     {async () => <Stats digest={await digest(sql, q)} {...q} />}
@@ -935,8 +959,10 @@ site's stylesheet to colour), one of them by day, week or month (a count's
 total, a rate's mean), every non-empty
 ranked list, and `?days=` links between windows, all time among them, pinned in
 the chart's frame as its own buttons are (`TimeChart`'s `controls`). Each
-figure is a button that charts it: visitors, agents, page views, bounce rate,
-visit length and clicks to X. `digest`'s `by_day` carries every
+figure is a button that charts it: visitors, page views, bounce rate,
+visit length and clicks to X. Visitors count agents; `?agents=apart`, a pair
+of links beside the windows, splits them into people and agents, and every
+other link on the page keeps the choice. `digest`'s `by_day` carries every
 one of those per UTC day, a visit on the day it began, so the days add up to the
 totals. A day with no visits has no bounce rate or visit length and is left out
 of those charts rather than drawn as zero. Everything but the figures and the

package/dist/analytics.d.ts

@@ -112,7 +112,7 @@ export interface Digest {
      * never among `visitors`.
      */
     agents: number;
-    /** Visitors plus every agent that sent an event, such as an MCP call. */
+    /** Visitors and `agents` as one count, which a stats page shows unless asked to keep them apart. */
     visitors_incl_agents: number;
     /**
      * The headline figures over the same number of days before, narrowed alike.

package/dist/analytics.js

@@ -240,7 +240,7 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       'bounce_rate', (SELECT round(100.0 * bounces / nullif(visits, 0)) FROM sessions${s}),
       'visit_duration', (SELECT round(seconds / nullif(visits, 0)) FROM sessions${s}),
       'agents', (SELECT count(DISTINCT visitor) FROM ag${s}),
-      'visitors_incl_agents', (SELECT count(DISTINCT visitor) FROM (SELECT visitor FROM v${s} UNION SELECT visitor FROM e${s}) u) + (SELECT visitors FROM archived${s})`;
+      'visitors_incl_agents', (SELECT count(DISTINCT visitor) FROM (SELECT visitor FROM v${s} UNION SELECT visitor FROM ag${s}) u) + (SELECT visitors FROM archived${s})`;
     const [row] = (await sql(`WITH ${chain('', 0)}, ${chain('_p', 1)}, src AS (
       SELECT coalesce(source, '(none)') AS source, count(DISTINCT visitor) AS visitors FROM visits GROUP BY 1
       UNION ALL SELECT key, value::int FROM a, jsonb_each_text(a.sources)
@@ -261,7 +261,7 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
           SELECT ${day('at')}, count(DISTINCT visitor), count(*), 0, 0, 0, 0, 0, 0 FROM v GROUP BY 1
           UNION ALL SELECT ${day('at')}, 0, 0, count(*), count(*) FILTER (WHERE views = 1), coalesce(sum(seconds), 0), 0, 0, 0 FROM visits GROUP BY 1
           UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, count(DISTINCT visitor), 0, 0 FROM ag GROUP BY 1
-          UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, 0, count(DISTINCT visitor), 0 FROM (SELECT at, visitor FROM v UNION ALL SELECT at, visitor FROM e) u GROUP BY 1
+          UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, 0, count(DISTINCT visitor), 0 FROM (SELECT at, visitor FROM v UNION ALL SELECT at, visitor FROM ag) u GROUP BY 1
           ${follows ? `UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, 0, 0, count(*) FROM e WHERE ${follows} GROUP BY 1` : ''}
           UNION ALL SELECT to_char(day, 'YYYY-MM-DD'), visitors, pageviews, visits, bounces, seconds, 0, visitors, 0 FROM a
         ) t(date, visitors, pageviews, visits, bounces, seconds, agents, everyone, follows) GROUP BY 1`, undefined, '1')},

package/dist/conformance.d.ts

@@ -193,3 +193,70 @@ export declare function payloadBudget(t: Tester, calls: ReadonlyArray<{
  * every unnamed crawler is telling two different stories to the same caller.
  */
 export declare function robotsChecks(t: Tester, paths: readonly string[]): Promise<void>;
+/**
+ * `/.well-known/mcp.json` is `tools/list`, tool for tool, names the endpoint
+ * under test, and states write auth only where the server lists a write tool.
+ *
+ * Both lists are `toolCard` projections, so anything short of equality is a
+ * manifest built from something other than the server's own tools. Pass
+ * `writeAuth` where the server's writes take a credential the manifest should
+ * describe, and the check runs both ways.
+ */
+export declare function manifestParity(t: Tester, opts?: {
+    url?: string;
+    writeAuth?: boolean;
+}): Promise<void>;
+/**
+ * Two surfaces answering one question answer it identically: a tool's rows and
+ * the GET API's, a tool's search and the `?q=` page's. Two empty answers are
+ * not agreement, so an empty one fails.
+ */
+export declare function rowParity(t: Tester, label: string, mcp: unknown, rest: unknown): void;
+/**
+ * A page reads the same over MCP as at its markdown twin: the tool's text is
+ * the twin's body, after the frontmatter, and after the `# Title` line the twin
+ * adds where the page's own blocks open with no h1.
+ */
+export declare function twinParity(t: Tester, label: string, twinUrl: string, content: string): Promise<void>;
+/**
+ * What an edit starts from, on any server built on the wiki read tools: rows
+ * carry the id a pageList block takes, `get_page` with `blocks: true` returns
+ * the stored blocks and the version a save takes as its base, and the history's
+ * newest revision is that version. `validate` is the site's own block check,
+ * so blocks the tool hands out are blocks the site's write takes back.
+ */
+export declare function editReadChecks(t: Tester, opts: {
+    path: string;
+    endpoint?: string;
+    rows?: ReadonlyArray<{
+        id?: unknown;
+    }>;
+    validate?: (blocks: unknown[]) => true | string;
+    label?: string;
+}): Promise<void>;
+/**
+ * What a read tool hands out, a write tool takes back unchanged, and the page
+ * reads the same after: the read's shape is the write's. `write` gets the read
+ * as it came; `read` is called again after.
+ */
+export declare function roundTrip(t: Tester, label: string, io: {
+    read: () => Promise<unknown>;
+    write: (value: unknown) => Promise<Rpc>;
+}): Promise<void>;
+/**
+ * Every field a REST write documents, the matching tool takes. An edit tool
+ * missing the version field the editor sends overwrites whatever landed between
+ * an agent's read and its write. `ops` pairs an OpenAPI path and method with
+ * the tool that does the same write.
+ */
+export declare function openapiWriteParity(t: Tester, ops: ReadonlyArray<readonly [path: string, method: string, tool: string]>, specUrl?: string): Promise<void>;
+/**
+ * The ROLA recipe a challenge tool hands out names the origin the verifier
+ * checks: the origin under test. One that named the canonical site while the
+ * verifier read another variable failed every signature off that site.
+ */
+export declare function rolaOriginCheck(t: Tester, opts?: {
+    origin?: string;
+    endpoint?: string;
+    tool?: string;
+}): Promise<void>;

package/dist/conformance.js

@@ -468,3 +468,128 @@ export async function robotsChecks(t, paths) {
         t.check(`robots allows ${path}`, !match || match.allow, match ? `${match.allow ? 'Allow' : 'Disallow'}: ${match.path}` : 'no matching rule');
     }
 }
+// ---- drift: what the MCP server says against what the site does -----------
+//
+// Each app had written these against its own surfaces after an audit found its
+// MCP server describing, accepting or returning something its site did not:
+// an edit tool without the version guard the editor sends, page reads that
+// flattened what the markdown twin kept, a manifest stating write auth on a
+// deployment with no writes. The same check, once per app, is how the checks
+// themselves drift, so they live here beside the transport they test.
+/** A JSON value that says nothing: comparing two of them proves nothing. */
+const vacuous = (v) => v == null || (Array.isArray(v) ? v.length === 0 : typeof v === 'object' && Object.keys(v).length === 0);
+/** Where two JSON values first part, for a check's note. */
+const firstDifference = (a, b) => {
+    const [x, y] = [JSON.stringify(a) ?? 'undefined', JSON.stringify(b) ?? 'undefined'];
+    let i = 0;
+    while (i < x.length && x[i] === y[i])
+        i++;
+    return `at char ${i}: MCP …${x.slice(Math.max(0, i - 20), i + 40)}… vs …${y.slice(Math.max(0, i - 20), i + 40)}…`;
+};
+/**
+ * `/.well-known/mcp.json` is `tools/list`, tool for tool, names the endpoint
+ * under test, and states write auth only where the server lists a write tool.
+ *
+ * Both lists are `toolCard` projections, so anything short of equality is a
+ * manifest built from something other than the server's own tools. Pass
+ * `writeAuth` where the server's writes take a credential the manifest should
+ * describe, and the check runs both ways.
+ */
+export async function manifestParity(t, opts = {}) {
+    const manifest = (await (await fetch(opts.url ?? `${t.base}/.well-known/mcp.json`)).json());
+    const listed = (await t.rpc('tools/list')).result?.tools ?? [];
+    const names = (xs) => xs.map(x => x.name).sort().join(' ');
+    const same = JSON.stringify(manifest.tools) === JSON.stringify(listed);
+    t.check('mcp.json is tools/list', same && listed.length > 0, same ? `${listed.length} tools` : names(manifest.tools ?? []) === names(listed) ? firstDifference(manifest.tools, listed) : `mcp.json: ${names(manifest.tools ?? [])} | tools/list: ${names(listed)}`);
+    // By path: the manifest names the canonical origin, and a run against a dev server is not it.
+    const path = (u) => (u ? new URL(u, t.base).pathname : '');
+    t.check('mcp.json names the endpoint', path(manifest.mcp?.endpoint) === path(t.endpoint), `${manifest.mcp?.endpoint}`);
+    const writes = listed.filter(x => x.annotations?.readOnlyHint === false).length;
+    const states = !!manifest.auth?.writes;
+    t.check('mcp.json write auth', (!states || writes > 0) && (opts.writeAuth === undefined || states === opts.writeAuth), `auth.writes ${states ? 'stated' : 'absent'}, ${writes} write tools listed${opts.writeAuth === undefined ? '' : `, expected ${opts.writeAuth ? 'stated' : 'absent'}`}`);
+}
+/**
+ * Two surfaces answering one question answer it identically: a tool's rows and
+ * the GET API's, a tool's search and the `?q=` page's. Two empty answers are
+ * not agreement, so an empty one fails.
+ */
+export function rowParity(t, label, mcp, rest) {
+    const same = JSON.stringify(mcp) === JSON.stringify(rest);
+    t.check(label, same && !vacuous(mcp), vacuous(mcp) ? 'nothing to compare: the MCP answer is empty' : same ? 'identical' : firstDifference(mcp, rest));
+}
+/**
+ * A page reads the same over MCP as at its markdown twin: the tool's text is
+ * the twin's body, after the frontmatter, and after the `# Title` line the twin
+ * adds where the page's own blocks open with no h1.
+ */
+export async function twinParity(t, label, twinUrl, content) {
+    const url = twinUrl.startsWith('http') ? twinUrl : `${t.base}/${twinUrl.replace(/^\//, '')}`;
+    const res = await fetch(url);
+    let body = (await res.text()).replace(/^---\n[\s\S]*?\n---\n+/, '').trim();
+    const text = content.trim();
+    if (!text.startsWith('# '))
+        body = body.replace(/^# [^\n]*\n+/, '');
+    t.check(label, res.ok && !!text && body === text, !res.ok ? `${res.status} ${url}` : !text ? 'nothing to compare: the MCP text is empty' : body === text ? `${text.length} chars` : firstDifference(text, body));
+}
+/**
+ * What an edit starts from, on any server built on the wiki read tools: rows
+ * carry the id a pageList block takes, `get_page` with `blocks: true` returns
+ * the stored blocks and the version a save takes as its base, and the history's
+ * newest revision is that version. `validate` is the site's own block check,
+ * so blocks the tool hands out are blocks the site's write takes back.
+ */
+export async function editReadChecks(t, opts) {
+    const endpoint = opts.endpoint ?? t.endpoint;
+    const label = (s) => (opts.label ? `[${opts.label}] ${s}` : s);
+    if (opts.rows) {
+        const rows = opts.rows;
+        t.check(label('rows carry the page id'), rows.length > 0 && rows.every(r => typeof r.id === 'string' && r.id.length > 0), `${rows.length} rows, first id=${String(rows[0]?.id)}`);
+    }
+    const page = t.payload(await t.callAt(endpoint, 'get_page', { path: opts.path, blocks: true }));
+    const blocks = Array.isArray(page?.content) ? page.content : null;
+    const verdict = blocks && opts.validate ? opts.validate(blocks) : true;
+    t.check(label('get_page(blocks)'), !!page?.id && !!page.version && !!blocks && typeof page.metadata === 'object' && verdict === true, !blocks ? `no block array: ${JSON.stringify(page).slice(0, 80)}` : verdict !== true ? `the site's block check refuses them: ${verdict}` : `${blocks.length} blocks, v${page.version}`);
+    const history = t.payload(await t.callAt(endpoint, 'get_page_history', { path: opts.path, limit: 3 }));
+    const newest = history?.revisions?.[0];
+    t.check(label('get_page_history'), !!newest?.id && newest.version === history.currentVersion && newest.version === page?.version && 'author' in newest, `${history?.revisions?.length ?? 0} revisions, newest v${newest?.version} of v${history?.currentVersion}, page v${page?.version}`);
+}
+/**
+ * What a read tool hands out, a write tool takes back unchanged, and the page
+ * reads the same after: the read's shape is the write's. `write` gets the read
+ * as it came; `read` is called again after.
+ */
+export async function roundTrip(t, label, io) {
+    const before = await io.read();
+    const wrote = await io.write(before);
+    const after = await io.read();
+    const failed = wrote.error ? `-${wrote.error.code} ${wrote.error.message}` : wrote.result?.isError ? String(t.payload(wrote)).slice(0, 100) : '';
+    t.check(label, !vacuous(before) && !failed && JSON.stringify(after) === JSON.stringify(before), vacuous(before) ? 'nothing to compare: the read is empty' : failed ? `the write refused its own read: ${failed}` : JSON.stringify(after) === JSON.stringify(before) ? 'unchanged' : firstDifference(after, before));
+}
+/**
+ * Every field a REST write documents, the matching tool takes. An edit tool
+ * missing the version field the editor sends overwrites whatever landed between
+ * an agent's read and its write. `ops` pairs an OpenAPI path and method with
+ * the tool that does the same write.
+ */
+export async function openapiWriteParity(t, ops, specUrl = `${t.base}/.well-known/openapi.json`) {
+    const spec = (await (await fetch(specUrl)).json());
+    const tools = (await t.rpc('tools/list')).result?.tools ?? [];
+    for (const [path, method, tool] of ops) {
+        const content = spec.paths?.[path]?.[method.toLowerCase()]?.requestBody?.content ?? {};
+        const fields = [...new Set(Object.values(content).flatMap(c => Object.keys(c.schema?.properties ?? {})))];
+        const props = Object.keys(tools.find(x => x.name === tool)?.inputSchema?.properties ?? {});
+        const missing = fields.filter(f => !props.includes(f));
+        t.check(`${tool} takes ${method.toUpperCase()} ${path}`, fields.length > 0 && missing.length === 0, !fields.length ? `the spec documents no body for ${method.toUpperCase()} ${path}` : missing.length ? `missing: ${missing.join(', ')}` : `${fields.length} fields`);
+    }
+}
+/**
+ * The ROLA recipe a challenge tool hands out names the origin the verifier
+ * checks: the origin under test. One that named the canonical site while the
+ * verifier read another variable failed every signature off that site.
+ */
+export async function rolaOriginCheck(t, opts = {}) {
+    const origin = opts.origin ?? new URL(t.base).origin;
+    const answer = t.payload(await t.callAt(opts.endpoint ?? t.endpoint, opts.tool ?? 'get_challenge'));
+    const message = answer?.sign?.message ?? '';
+    t.check('ROLA recipe names this origin', message.includes(`"${origin}"`), `expects "${origin}" in: …${message.slice(-90)}`);
+}

package/dist/mcp.d.ts

@@ -34,13 +34,34 @@ export declare const MCP_META: {
     readonly serverInfo: "io.modelcontextprotocol/serverInfo";
 };
 import { type RateLimitOptions } from './rate-limit.js';
+/**
+ * JSON Schema as far as a tool's parameters go. Open past the named keywords,
+ * because an array's items may be a whole block type, which a narrower shape
+ * made every app type as `{ type: 'object' }` and leave the rest unsaid.
+ */
+export type JsonSchema = {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    description?: string;
+    enum?: readonly (string | number)[];
+    items?: JsonSchema;
+    properties?: Record<string, JsonSchema>;
+    required?: readonly string[];
+    minimum?: number;
+    maximum?: number;
+    [keyword: string]: unknown;
+};
 export type ToolParam = {
     type: 'string' | 'number' | 'boolean' | 'array' | 'object';
     description: string;
     enum?: string[];
-    items?: {
-        type?: 'string' | 'number' | 'object';
-    };
+    items?: JsonSchema;
+    /**
+     * Bounds a client can read before it calls. The handler still clamps (an
+     * argument out of range comes back adjusted, not refused), so these state the
+     * clamp rather than enforce it.
+     */
+    minimum?: number;
+    maximum?: number;
 };
 export type ToolSchema = {
     type: 'object';

package/dist/mcp.js

@@ -233,7 +233,7 @@ function validateArgs(tool, args) {
             // No `items` means strings. Items with no one type (a `oneOf` of shapes,
             // as a zod union emits) are the tool's own to check: read as strings, every
             // well-formed call was refused.
-            const itemType = spec.items ? spec.items.type : 'string';
+            const itemType = spec.items ? (spec.items.type === 'integer' ? 'number' : spec.items.type) : 'string';
             if (actual !== 'array') {
                 problems.push(`Parameter "${key}" must be an array${itemType ? ` of ${itemType}s` : ''}; received ${actual} (${JSON.stringify(value)}).`);
             }

package/dist/og.d.ts

@@ -0,0 +1,54 @@
+import type { ReactElement, ReactNode } from 'react';
+export declare const OG_SIZE: {
+    readonly width: 1200;
+    readonly height: 630;
+};
+/** A day at the CDN, a week stale: a card changes when its page's title does, and crawlers cache it for longer anyway. */
+export declare const OG_HEADERS: {
+    readonly 'Cache-Control': "public, max-age=86400, s-maxage=86400, stale-while-revalidate=604800";
+};
+/** The card's generator, seeded from its text, so one page always draws the same card. */
+export declare function cardRandom(...parts: string[]): () => number;
+export interface BubbleOptions {
+    /** The two ends of the field's gradient; its angle is seeded. */
+    field: readonly [string, string];
+    /** Circle colours, picked at random per circle. */
+    colors: readonly string[];
+    count?: number;
+    /** Smallest radius and the spread above it, in px. */
+    radius?: readonly [number, number];
+    /** Lowest opacity and the spread above it. */
+    opacity?: readonly [number, number];
+}
+/** The seeded gradient and translucent circles: a field and its art, for `SocialCard`. */
+export declare function bubbles(rand: () => number, o: BubbleOptions): {
+    background: string;
+    art: ReactNode;
+};
+export interface SocialCardProps {
+    title: string;
+    /** The line above the title: a section, a code, a handle. */
+    eyebrow?: string;
+    /** The line along the foot. */
+    description?: string;
+    /** The site's name, at the foot's right. */
+    mark?: string;
+    colors: {
+        text: string;
+        /** The description. */
+        muted: string;
+        /** The eyebrow and the mark. */
+        accent: string;
+    };
+    /** The field: any CSS background satori draws, a gradient from `bubbles` or a flat colour. */
+    background: string;
+    /** Absolutely positioned layers between the field and the text. */
+    art?: ReactNode;
+    /** A dark gradient up from the foot, for art that is a photograph. */
+    scrim?: boolean;
+    fontFamily?: string;
+    /** Anything that belongs under the title: chips, a figure. */
+    children?: ReactNode;
+}
+/** One card, 1200×630: the eyebrow, title and anything under it, then the description and the mark along the foot. */
+export declare function SocialCard(p: SocialCardProps): ReactElement;

package/dist/og.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { describe } from './metadata.js';
+import { hashStr, seededRandom } from './seeded.js';
+export const OG_SIZE = { width: 1200, height: 630 };
+/** A day at the CDN, a week stale: a card changes when its page's title does, and crawlers cache it for longer anyway. */
+export const OG_HEADERS = { 'Cache-Control': 'public, max-age=86400, s-maxage=86400, stale-while-revalidate=604800' };
+/** The card's generator, seeded from its text, so one page always draws the same card. */
+export function cardRandom(...parts) {
+    return seededRandom(hashStr(parts.join('')));
+}
+/** The seeded gradient and translucent circles: a field and its art, for `SocialCard`. */
+export function bubbles(rand, o) {
+    const [r0, rSpan] = o.radius ?? [60, 180];
+    const [a0, aSpan] = o.opacity ?? [0.12, 0.2];
+    const background = `linear-gradient(${Math.floor(rand() * 360)}deg, ${o.field[0]}, ${o.field[1]})`;
+    const art = Array.from({ length: o.count ?? 7 }, (_, i) => {
+        const cx = rand() * OG_SIZE.width;
+        const cy = rand() * OG_SIZE.height;
+        const r = r0 + rand() * rSpan;
+        const color = o.colors[Math.floor(rand() * o.colors.length)] ?? o.field[1];
+        return (_jsx("div", { style: { position: 'absolute', left: cx - r, top: cy - r, width: r * 2, height: r * 2, borderRadius: '50%', background: color, opacity: a0 + rand() * aSpan } }, i));
+    });
+    return { background, art };
+}
+const SCRIM = 'linear-gradient(to top, rgba(0,0,0,0.8) 0%, rgba(0,0,0,0.3) 50%, transparent 100%)';
+/** One card, 1200×630: the eyebrow, title and anything under it, then the description and the mark along the foot. */
+export function SocialCard(p) {
+    const title = describe(p.title, 90);
+    // Three lines at most at either size; the step is where 68px would wrap a fourth.
+    const titleSize = title.length > 48 ? 56 : 72;
+    return (_jsxs("div", { style: { display: 'flex', width: '100%', height: '100%', position: 'relative', background: p.background, ...(p.fontFamily ? { fontFamily: p.fontFamily } : {}) }, children: [p.art, _jsxs("div", { style: {
+                    display: 'flex', flexDirection: 'column', justifyContent: 'flex-end',
+                    width: '100%', height: '100%', padding: '56px 64px', position: 'relative',
+                    ...(p.scrim ? { background: SCRIM } : {}),
+                }, children: [p.eyebrow ? _jsx("div", { style: { display: 'flex', fontSize: 30, fontWeight: 700, color: p.colors.accent, marginBottom: 14 }, children: describe(p.eyebrow, 48) }) : null, _jsx("div", { style: { display: 'flex', fontSize: titleSize, fontWeight: 700, color: p.colors.text, lineHeight: 1.08, letterSpacing: '-0.02em' }, children: title }), p.children ? _jsx("div", { style: { display: 'flex', marginTop: 28 }, children: p.children }) : null, p.description || p.mark ? (_jsxs("div", { style: { display: 'flex', alignItems: 'flex-end', justifyContent: 'space-between', gap: 40, marginTop: 28 }, children: [_jsx("div", { style: { display: 'flex', flex: 1, fontSize: 26, lineHeight: 1.35, color: p.colors.muted }, children: p.description ? describe(p.description, 110) : '' }), p.mark ? _jsx("div", { style: { display: 'flex', fontSize: 28, fontWeight: 700, color: p.colors.accent }, children: p.mark }) : null] })) : null] })] }));
+}

package/dist/stats-figures.d.ts

@@ -6,10 +6,11 @@ import { type Digest } from './analytics.js';
  * day from `first` (a UTC day number) to today. A count's empty day is a zero;
  * a rate's is left out, since no visits is not a bounce rate of nothing.
  */
-export declare function StatsFigures({ digest, first, windows }: {
+export declare function StatsFigures({ digest, first, apart, controls }: {
     digest: Digest;
     first: number;
-    windows: ReactNode;
+    apart: boolean;
+    controls: ReactNode;
 }): import("react").JSX.Element;
 export interface PasskeyButtonProps {
     /** The route that serves `gate.route`. */

package/dist/stats-figures.js

@@ -26,9 +26,21 @@ function change(now, before, { points = false, lowerIsBetter = false } = {}) {
     const text = `${n > 0 ? '+' : ''}${n}${points ? ' pp' : '%'}`;
     return n ? { text, better: n > 0 !== lowerIsBetter } : { text };
 }
-const figuresOf = ({ previous: p, ...d }) => [
-    { label: 'Visitors', value: count(d.visitors), delta: change(d.visitors, p.visitors), day: r => r.visitors },
-    { label: 'Agents', value: count(d.agents), delta: change(d.agents, p.agents), day: r => r.agents },
+/** Visitors are one figure counting agents too, or `apart` two: people, and agents. */
+const figuresOf = ({ previous: p, ...d }, apart) => [
+    ...(apart
+        ? [
+            { label: 'People', value: count(d.visitors), delta: change(d.visitors, p.visitors), day: (r) => r.visitors },
+            { label: 'Agents', value: count(d.agents), delta: change(d.agents, p.agents), day: (r) => r.agents },
+        ]
+        : [
+            {
+                label: 'Visitors',
+                value: count(d.visitors_incl_agents),
+                delta: change(d.visitors_incl_agents, p.visitors_incl_agents),
+                day: (r) => r.visitors_incl_agents,
+            },
+        ]),
     { label: 'Page views', value: count(d.pageviews), delta: change(d.pageviews, p.pageviews), day: r => r.pageviews },
     {
         label: 'Bounce rate',
@@ -65,8 +77,8 @@ const EMPTY = { date: '', visitors: 0, pageviews: 0, visits: 0, bounces: 0, seco
  * day from `first` (a UTC day number) to today. A count's empty day is a zero;
  * a rate's is left out, since no visits is not a bounce rate of nothing.
  */
-export function StatsFigures({ digest, first, windows }) {
-    const figures = useMemo(() => figuresOf(digest), [digest]);
+export function StatsFigures({ digest, first, apart, controls }) {
+    const figures = useMemo(() => figuresOf(digest, apart), [digest, apart]);
     const [chosen, choose] = useState(0);
     const figure = figures[chosen] ?? figures[0];
     const byDay = useMemo(() => new Map(digest.by_day.map(r => [r.date, r])), [digest.by_day]);
@@ -78,7 +90,7 @@ export function StatsFigures({ digest, first, windows }) {
             return value == null ? null : { time, value };
         }).filter(p => p !== null);
     }, [byDay, first, figure]);
-    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "stats-figures", role: "group", "aria-label": "Chart", children: figures.map((f, i) => (_jsxs("button", { type: "button", "aria-pressed": i === chosen, onClick: () => choose(i), children: [_jsx("span", { children: f.label }), _jsxs("strong", { children: [f.value, f.delta && (_jsx("small", { className: "stats-delta", "data-better": f.delta.better, children: f.delta.text }))] })] }, f.label))) }), _jsx(TimeChart, { series: series, label: figure.label, ranges: ['all'], aggregate: figure.aggregate ?? 'sum', fromZero: true, format: figure.format, controls: windows, className: "stats-chart" })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "stats-figures", role: "group", "aria-label": "Chart", children: figures.map((f, i) => (_jsxs("button", { type: "button", "aria-pressed": i === chosen, onClick: () => choose(i), children: [_jsx("span", { children: f.label }), _jsxs("strong", { children: [f.value, f.delta && (_jsx("small", { className: "stats-delta", "data-better": f.delta.better, children: f.delta.text }))] })] }, f.label))) }), _jsx(TimeChart, { series: series, label: figure.label, ranges: ['all'], aggregate: figure.aggregate ?? 'sum', fromZero: true, format: figure.format, controls: controls, className: "stats-chart" })] }));
 }
 async function post(endpoint, body) {
     const res = await fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });

package/dist/stats.d.ts

@@ -8,6 +8,8 @@ export interface StatsProps {
     days: number;
     /** What the digest was narrowed to, as `digest` was given it. */
     filter?: StatsFilter;
+    /** Visitors as people and agents, two figures, rather than one that counts both. */
+    apart?: boolean;
     /** The windows offered as `?days=` links on the same page. */
     ranges?: readonly number[];
 }
@@ -19,15 +21,16 @@ export interface StatsProps {
 export declare function statsQuery(params: Record<string, string | string[] | undefined>, ranges?: readonly number[]): {
     days: number;
     filter: Partial<Record<"page" | "entry" | "source" | "country" | "device", string>>;
+    apart: boolean;
 };
 /**
  * A site's own analytics on one page: the headline figures against the window
- * before, whichever of them is chosen per day, and every ranked list the
+ * before, visitors counting agents unless `apart`, whichever of them is chosen per day, and every ranked list the
  * digest carries, each row a link that narrows the page to it. Lists with
  * nothing in them are left out. The chart and the bars are `currentColor`
  * until the importing stylesheet gives them a colour.
  */
-export declare function Stats({ digest: d, days, filter, ranges }: StatsProps): import("react").JSX.Element;
+export declare function Stats({ digest: d, days, filter, apart, ranges }: StatsProps): import("react").JSX.Element;
 export interface StatsGateProps {
     gate: PasskeyGate;
     /** The gate's cookie from the request: `(await cookies()).get(gate.cookie)?.value`. */

package/dist/stats.js

@@ -21,11 +21,13 @@ export function statsQuery(params, ranges = STATS_RANGES) {
         if (typeof v === 'string' && v)
             filter[k] = v.slice(0, 500);
     }
-    return { days: statsDays(params.days, ranges), filter };
+    return { days: statsDays(params.days, ranges), filter, apart: params.agents === 'apart' };
 }
-/** The page at a window and a filter, as a query string. */
-const href = (days, filter) => {
+/** The page at a window, a filter and a count of agents, as a query string. */
+const href = (days, filter, apart) => {
     const q = new URLSearchParams({ days: daysParam(days) });
+    if (apart)
+        q.set('agents', 'apart');
     for (const k of STATS_FILTERS)
         if (filter[k])
             q.set(k, filter[k]);
@@ -50,12 +52,12 @@ function StatsList({ title, rows, label = v => v, to, }) {
 }
 /**
  * A site's own analytics on one page: the headline figures against the window
- * before, whichever of them is chosen per day, and every ranked list the
+ * before, visitors counting agents unless `apart`, whichever of them is chosen per day, and every ranked list the
  * digest carries, each row a link that narrows the page to it. Lists with
  * nothing in them are left out. The chart and the bars are `currentColor`
  * until the importing stylesheet gives them a colour.
  */
-export function Stats({ digest: d, days, filter = {}, ranges = STATS_RANGES }) {
+export function Stats({ digest: d, days, filter = {}, apart = false, ranges = STATS_RANGES }) {
     const today = Math.floor(Date.now() / DAY_MS);
     const counted = d.counted_from ? Date.parse(d.counted_from) / DAY_MS : today;
     const narrowed = STATS_FILTERS.filter(k => filter[k]);
@@ -67,11 +69,12 @@ export function Stats({ digest: d, days, filter = {}, ranges = STATS_RANGES }) {
         ? Math.max(start, counted)
         : Number.isFinite(start) ? start : Math.min(today, ...d.by_day.map(r => Date.parse(r.date) / DAY_MS));
     const rows = (list, k, m) => list.map(r => [r[k], r[m]]);
-    const to = (k) => (v) => href(days, { ...filter, [k]: v });
+    const at = (f, n = days, a = apart) => href(n, f, a);
+    const to = (k) => (v) => at({ ...filter, [k]: v });
     // Each window is another digest, so a link rather than a button, pinned
-    // with the chart's own controls.
-    const windows = (_jsx("div", { role: "group", "aria-label": "Window", children: ranges.map(n => (_jsx("a", { href: href(n, filter), "aria-current": n === days ? 'page' : undefined, children: windowLabel(n) }, n))) }));
-    return (_jsxs("div", { className: "stats", children: [narrowed.length > 0 && (_jsxs("div", { className: "stats-filters", children: [_jsx("ul", { "aria-label": "Narrowed to", children: narrowed.map(k => (_jsx("li", { children: _jsxs("a", { href: href(days, { ...filter, [k]: undefined }), title: "Remove", children: [NAMES[k], ": ", k === 'country' ? country(filter[k]) : filter[k], " \u00D7"] }) }, k))) }), start < counted && d.counted_from && (_jsxs("p", { children: ["Narrowed figures start on ", d.counted_from, ", the first day this site counted its own visits."] }))] })), _jsx(StatsFigures, { digest: d, first: first, windows: windows }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { title: "Pages", rows: rows(d.top_pages, 'page', 'visitors'), to: to('page') }), _jsx(StatsList, { title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors'), to: to('entry') }), _jsx(StatsList, { title: "Sources", rows: rows(d.top_sources, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors'), to: v => href(days, { ...filter, source: 'x', entry: v }) }), _jsx(StatsList, { title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country, to: to('country') }), _jsx(StatsList, { title: "Devices", rows: rows(d.devices, 'device', 'visitors'), to: to('device') }), _jsx(StatsList, { title: "Agents", rows: rows(d.top_agents, 'agent', 'visitors') }), _jsx(StatsList, { title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events') })] })] }));
+    // with the chart's own controls, and so is whether agents count apart.
+    const controls = (_jsxs(_Fragment, { children: [_jsx("div", { role: "group", "aria-label": "Window", children: ranges.map(n => (_jsx("a", { href: at(filter, n), "aria-current": n === days ? 'page' : undefined, children: windowLabel(n) }, n))) }), _jsxs("div", { role: "group", "aria-label": "Agents", children: [_jsx("a", { href: at(filter, days, false), "aria-current": apart ? undefined : 'page', title: "Visitors count agents", children: "With agents" }), _jsx("a", { href: at(filter, days, true), "aria-current": apart ? 'page' : undefined, title: "People and agents counted apart", children: "Apart" })] })] }));
+    return (_jsxs("div", { className: "stats", children: [narrowed.length > 0 && (_jsxs("div", { className: "stats-filters", children: [_jsx("ul", { "aria-label": "Narrowed to", children: narrowed.map(k => (_jsx("li", { children: _jsxs("a", { href: at({ ...filter, [k]: undefined }), title: "Remove", children: [NAMES[k], ": ", k === 'country' ? country(filter[k]) : filter[k], " \u00D7"] }) }, k))) }), start < counted && d.counted_from && (_jsxs("p", { children: ["Narrowed figures start on ", d.counted_from, ", the first day this site counted its own visits."] }))] })), _jsx(StatsFigures, { digest: d, first: first, apart: apart, controls: controls }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { title: "Pages", rows: rows(d.top_pages, 'page', 'visitors'), to: to('page') }), _jsx(StatsList, { title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors'), to: to('entry') }), _jsx(StatsList, { title: "Sources", rows: rows(d.top_sources, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors'), to: v => at({ ...filter, source: 'x', entry: v }) }), _jsx(StatsList, { title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country, to: to('country') }), _jsx(StatsList, { title: "Devices", rows: rows(d.devices, 'device', 'visitors'), to: to('device') }), _jsx(StatsList, { title: "Agents", rows: rows(d.top_agents, 'agent', 'visitors') }), _jsx(StatsList, { title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events') })] })] }));
 }
 /**
  * A stats page's door: `children` and a sign-out button for a signed-in

package/dist/wiki-tools.d.ts

@@ -1,9 +1,9 @@
 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 { WikiStore, WikiPageListing, WikiPageRow, 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';
+type ToolName = 'search_wiki' | 'get_page' | 'get_pages' | 'list_pages' | 'get_categories' | 'get_recent_changes' | 'get_full_corpus' | 'get_page_history';
 export interface WikiToolsOptions<B extends DiffBlock> {
     store: WikiStore<B>;
     tree: WikiTree<WikiNode>;
@@ -19,6 +19,10 @@ export interface WikiToolsOptions<B extends DiffBlock> {
     pathPrefix?: string;
     /** Back-office pages are private here, not merely unlisted: no tool reads one. */
     privateHidden?: boolean;
+    /** What `get_page` with `blocks: true` adds for the app's write tool, such as fields it keeps inside metadata. */
+    forEdit?: (page: WikiPageRow<B>) => Record<string, unknown>;
+    /** Display names by user id, for `get_page_history`. Without it a revision names no author. */
+    authors?: (ids: string[]) => Promise<Map<string, string>>;
     /** 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`. */
@@ -32,7 +36,7 @@ export interface WikiToolsOptions<B extends DiffBlock> {
 }
 /** 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'> & {
+type Rowable<B> = Pick<WikiPageListing, 'id' | '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. */
@@ -42,6 +46,7 @@ declare const rowFor: <B extends DiffBlock>(o: Pick<WikiToolsOptions<B>, "url" |
     snippet: string;
     updatedAt: string;
     chars?: number | undefined;
+    id: string;
     title: string;
     path: string;
     url: string;

package/dist/wiki-tools.js

@@ -21,12 +21,19 @@ 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);
+/** How a single-page tool takes its page. */
+const ADDRESS = {
+    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.' },
+};
 /** 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 {
+        id: p.id,
         title: p.title,
         path: pathOf(p.tagPath, p.slug),
         url: o.url(p.tagPath, p.slug),
@@ -68,6 +75,21 @@ export function wikiReadTools(o) {
         const page = (await store.get(t.tagPath, t.slug)) ?? (await store.get(pathOf(t.tagPath, t.slug), ''));
         return page && !off(page.tagPath) ? page : null;
     };
+    /** The page a call names by `path` or `tagPath` + `slug`; a miss names the nearest pages, so a wrong guess is fixed in one retry. */
+    const named = async (r) => {
+        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)
+            return 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.',
+        });
+    };
     const full = (page) => ({
         ...summary({ ...page, snippet: describe(openingText(page.content)) }),
         version: page.version,
@@ -100,8 +122,8 @@ export function wikiReadTools(o) {
                 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)' },
+                    page: { type: 'number', description: '1-based page number (default 1)', minimum: 1 },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 50)', minimum: 1, maximum: 50 },
                 },
                 required: ['query'],
             },
@@ -129,31 +151,22 @@ export function wikiReadTools(o) {
             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.',
+                'A page\'s URL with `.md` appended is its markdown. ' +
+                'With `blocks: true`, `content` is the stored block array, ids and all, beside the page `id` and its whole `metadata`: read a page this way before editing it, and send its `version` back as the edit\'s baseVersion.',
             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.' },
+                    ...ADDRESS,
+                    blocks: { type: 'boolean', description: 'Return the stored blocks rather than prose, for an edit' },
                 },
                 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));
+                const page = await named(r);
+                if (!r.bool('blocks'))
+                    return withAdjustments(r, full(page));
+                return withAdjustments(r, { ...full(page), id: page.id, content: page.content, metadata: page.metadata, ...o.forEdit?.(page) });
             },
         },
         {
@@ -167,7 +180,7 @@ export function wikiReadTools(o) {
                 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)' },
+                    maxChars: { type: 'number', description: 'Total characters across the pages returned (default 250000, max 1000000)', minimum: 1_000, maximum: 1_000_000 },
                 },
                 required: ['paths'],
             },
@@ -228,8 +241,8 @@ export function wikiReadTools(o) {
                 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)' },
+                    page: { type: 'number', description: '1-based page number (default 1)', minimum: 1 },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 100)', minimum: 1, maximum: 100 },
                 },
             },
             handler: async (args) => {
@@ -285,8 +298,8 @@ export function wikiReadTools(o) {
             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)' },
+                    days: { type: 'number', description: 'Look back this many days (default 7, max 30)', minimum: 1, maximum: 30 },
+                    limit: { type: 'number', description: 'Most pages returned (default 20, max 50)', minimum: 1, maximum: 50 },
                 },
             },
             handler: async (args) => {
@@ -320,8 +333,8 @@ export function wikiReadTools(o) {
                 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)' },
+                    maxChars: { type: 'number', description: `Character budget for \`document\` (default ${CORPUS_BUDGET.default}, max ${CORPUS_BUDGET.max})`, minimum: CORPUS_BUDGET.min, maximum: CORPUS_BUDGET.max },
+                    skip: { type: 'number', description: 'Resume from this page index: the `nextSkip` of the previous truncated call (default 0)', minimum: 0 },
                 },
             },
             handler: async (args) => {
@@ -337,6 +350,33 @@ export function wikiReadTools(o) {
                 return withAdjustments(r, { scope: o.corpusTitle, ...(tagPath ? { tagPath } : {}), ...slice });
             },
         },
+        {
+            name: 'get_page_history',
+            title: 'Page history',
+            annotations: READ,
+            description: `A page's revisions in ${noun}, newest first: each one's \`id\`, version, change type, message, date and the blocks it changed. ` +
+                'Address the page as get_page does. A revision `id` is what a restore takes, where this server has one. Defaults: limit 20 (max 100).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...ADDRESS,
+                    limit: { type: 'number', description: 'Most revisions returned (default 20, max 100)', minimum: 1, maximum: 100 },
+                },
+                requireOneOf: ['path', 'slug'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const page = await named(r);
+                const revisions = await store.history(page.id, { limit: r.num('limit', 20, 1, 100) });
+                const names = o.authors && await o.authors([...new Set(revisions.flatMap(v => v.authorId ? [v.authorId] : []))]);
+                return withAdjustments(r, {
+                    path: pathOf(page.tagPath, page.slug),
+                    url: o.url(page.tagPath, page.slug),
+                    currentVersion: page.version,
+                    revisions: revisions.map(({ pageId: _, authorId, ...v }) => ({ ...v, ...(names ? { author: (authorId && names.get(authorId)) || null } : {}) })),
+                });
+            },
+        },
     ];
     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.65.1",
+  "version": "0.69.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",
@@ -243,6 +243,11 @@
       "import": "./dist/seeded.js",
       "default": "./dist/seeded.js"
     },
+    "./og": {
+      "types": "./dist/og.d.ts",
+      "import": "./dist/og.js",
+      "default": "./dist/og.js"
+    },
     "./sanitize": {
       "types": "./dist/sanitize.d.ts",
       "import": "./dist/sanitize.js",