wiki-formant 0.107.0 → 0.111.0

package/README.md

@@ -196,7 +196,7 @@ const { first } = await wikiReadChecks(t, { query: 'radix', address: r => ({ tag
 process.exit(t.summary());
 ```
 
-`standardSuite(t, cfg)` runs the suites every surface runs, in order: `transportChecks` (CORS preflight, `GET`→405, 202 for a notification, `-32700`, the batch cap, honest capabilities, version negotiation), `versionCoherence` over `standardVersionSources`, `agentCardParity`, `annotationChecks`, `manifestParity`, `payloadBudget`, `conditionalGetChecks`, `descriptorChecks` (default `S10_DESCRIPTORS`) and `robotsChecks`. `budget`, `conditionalGet` and `robots` run only when given, for a surface whose fixtures exist only later in its run. It returns the `initialize` response. Each suite is exported for a surface that needs it alone.
+`standardSuite(t, cfg)` runs the suites every surface runs, in order: `transportChecks` (CORS preflight, `GET`→405, 202 for a notification, `-32700`, the batch cap, honest capabilities, version negotiation), `versionCoherence` over `standardVersionSources`, `agentCardChecks`, `annotationChecks`, `manifestParity`, `payloadBudget`, `conditionalGetChecks`, `descriptorChecks` (default `S10_DESCRIPTORS`) and `robotsChecks`. `budget`, `conditionalGet` and `robots` run only when given, for a surface whose fixtures exist only later in its run. It returns the `initialize` response. Each suite is exported for a surface that needs it alone.
 
 `wikiReadChecks(t, opts)` checks the `wiki-tools` read tools: categories, a search and the page it finds (by `address`, default `{ path }`), its twin (given `twin`), a listing, recent changes, a corpus preflight and a slice that is cut and resumes when the corpus exceeds `corpusChars`, and the teaching answers to no hits, a missing argument, an unknown tool and a missing page. `endpoint` and `label` run it against a second server. It returns `{ rows, first, page }`.
 
@@ -260,7 +260,7 @@ export const POST = (req: Request) => handleRoute(async () => {
 - `corpusEtag`, `notModified` and `textHeaders` are the parts; `corpusRoute` skips the build on a 304.
 - A URL answering JSON or markdown by `Accept` asks `wantsMarkdown(request)` and sends `VARY_ACCEPT` on both branches.
 - `descriptorResponse` serves a JSON descriptor with its own ETag and `Access-Control-Allow-Origin: *` (`descriptorHandler` in `wiki-formant/well-known` is the route).
-- Every error body is `{ error, ...extra }`. A thrown `HttpError` answers with its status; anything else is logged and answered with a 500 carrying only the handler's message (`'Search failed'`), so no exception text reaches a caller. `errors.tooManyRequests(sec)` states `Retry-After`.
+- Every error body is `{ error, ...extra }`. A thrown `HttpError` answers with its status, a thrown `Response` (`errors.tooManyRequests(sec)`, say) is the answer as built; anything else is logged and answered with a 500 carrying only the handler's message (`'Search failed'`), so no exception text reaches a caller. `errors.tooManyRequests(sec)` states `Retry-After`.
 
 ## Response headers and the Next config
 
@@ -511,7 +511,7 @@ const block = licenseBlock({ license, scope: 'The protocol compilation and prose
 export const X = xAccount({ siteName: 'AcuiQ', handle: '@acu_iq', posts: "a named trial's prescription with its citation" });
 ```
 
-- One `License` goes to `licenseBlock`, `agentCard({ license, licenseScope })` and `openApiLicense` for `info.license`.
+- One `License` goes to `licenseBlock`, `agentCard({ license, licenseScope })` and `openApiDocument`, which sets `info.license` from it.
 - `X.url` is the `sameAs`, `X.handle` the card's, `followLines(X)` goes into llms.txt and AGENTS.md, `followNote(X)` into the MCP instructions, and `<a {...followLinkProps(X)}>` is the footer link with `rel="me"`.
 
 ## Agent descriptors
@@ -526,7 +526,23 @@ const AGENT_CARD = agentCard({ name, description, url: `${SITE_URL}/api/mcp`, ve
 export const GET = wellKnownHandler({ agentCard: AGENT_CARD, mcpManifest: mcpManifest({ … }), openapi: SPEC });
 ```
 
-The card is served identically at `agent-card.json` and `agent.json`, and its `url` is the MCP endpoint, which answers A2A. `registryAuthHandler` serves `MCP_REGISTRY_PUBLIC_KEY` at `/.well-known/mcp-registry-auth`, 404 when unset.
+The card is served at `agent-card.json`, and its `url` is the MCP endpoint, which answers A2A. `registryAuthHandler` serves `MCP_REGISTRY_PUBLIC_KEY` at `/.well-known/mcp-registry-auth`, 404 when unset.
+
+## OpenAPI
+
+`wiki-formant/openapi`: the frame of the spec `wellKnownHandler` serves, and the paths every site shares. A spec writes only its own paths.
+
+```ts
+import { openApiDocument, jsonBody, jsonResponse, toolBody, llmsTxtPath, mcpPath } from 'wiki-formant/openapi';
+
+export const SPEC = openApiDocument({ title, version, description, license, siteUrl: SITE_URL }, {
+  '/api/wiki/{path}': { put: { requestBody: toolBody(toolInput('edit_page'), { inPath: ['tagPath', 'slug'], refs: { Block: BLOCK_SCHEMA } }), … } },
+  '/llms.txt': llmsTxtPath('Index of every page (plain text)'),
+  '/api/mcp': mcpPath(TOOLS.map(t => t.name)),
+}, { schemas: { Block: BLOCK_SCHEMA } });
+```
+
+`toolBody` is a write tool's input schema as the REST body, so `openapiWriteParity` holds by construction. `mcpPath` states the protocol versions, the batch cap and `MCP_RATE_LIMIT_TEXT`; `llmsTxtPath` the `If-None-Match` and its 304.
 
 ## AI crawlers
 

package/bin/check-pages.mjs

@@ -58,12 +58,12 @@ const get = async url => {
 
 // The sitemap is the URL list.
 async function sitemapUrls(origin) {
-  const seen = (await readSitemap(`${origin}/sitemap.xml`, url => fetch(url, { headers: { 'user-agent': UA } }))).map(e => e.url);
+  const { entries, unread } = await readSitemap(`${origin}/sitemap.xml`, url => fetch(url, { headers: { 'user-agent': UA } }));
   // A sitemap states absolute production URLs by definition, so pointing
   // --site at a dev server would otherwise crawl production and report the
   // build you were trying to replace. The path is what the sitemap contributes;
   // the origin is what you asked for.
-  return seen.map(u => {
+  const urls = entries.map(({ url: u }) => {
     try {
       const { pathname, search } = new URL(u);
       return `${origin}${pathname}${search}`;
@@ -71,6 +71,7 @@ async function sitemapUrls(origin) {
       return u;
     }
   });
+  return { urls, unread };
 }
 
 const titleOf = html => {
@@ -84,17 +85,23 @@ const descriptionOf = html => {
 
 // A sitemap that does not answer is a fault, not an empty site: read as no
 // URLs, a down sitemap passed the gate it exists to hold.
-const urls = await sitemapUrls(site).catch(e => {
+const { urls, unread } = await sitemapUrls(site).catch(e => {
   console.error(`check-pages: ${site}/sitemap.xml could not be read: ${e.message}`);
   process.exit(WARN_ONLY ? 0 : 1);
 });
+// A child sitemap that does not answer hides its pages from every check below,
+// so it is a fault of its own (`sitemapUnread`), never a site with fewer pages.
+if (!urls.length && unread.length) {
+  for (const { url, error } of unread) console.error(`check-pages: ${url} could not be read: ${error}`);
+  process.exit(WARN_ONLY ? 0 : 1);
+}
 if (!urls.length) {
   console.log(`check-pages: no URLs in ${site}/sitemap.xml — nothing to check. Skipping.`);
   process.exit(0);
 }
 
 const checked = urls.slice(0, limit);
-const faults = [];
+const faults = unread.map(({ url, error }) => ({ url, fault: 'sitemapUnread', detail: error }));
 const titles = new Map();
 
 for (const url of checked) {

package/bin/indexnow.mjs

@@ -40,11 +40,12 @@ if (live.trim() !== key) {
   process.exit(1);
 }
 
-const entries = await readSitemap(`${origin}/sitemap.xml`).catch(e => {
+const { entries, unread } = await readSitemap(`${origin}/sitemap.xml`).catch(e => {
   console.error(e.message);
   process.exit(1);
 });
 const urls = args.includes('--all') ? entries.map(e => e.url) : changedUrls(entries, Date.now() - hours * 3_600_000);
 const statuses = await submitIndexNow(key, urls);
-console.log(JSON.stringify({ origin, submitted: urls.length, statuses }));
-if (!statuses.every(s => s === 200 || s === 202)) process.exit(1);
+// What was read is submitted; a child sitemap that did not answer fails the run, since its pages were not.
+console.log(JSON.stringify({ origin, submitted: urls.length, statuses, ...(unread.length && { unread }) }));
+if (unread.length || !statuses.every(s => s === 200 || s === 202)) process.exit(1);

package/dist/base.css

@@ -263,6 +263,10 @@ tbody > tr:nth-child(even) > :is(th, td):not(.chart *) { background-image: linea
 .infobox-series { align-items: center; gap: 0.125rem; padding-bottom: 0.75rem; border-bottom: 1px solid var(--ui-border); text-align: center; font-size: var(--ui-small); color: var(--ui-muted); }
 .page-with-infobox { gap: 1.5rem; }
 
+/* `Cite` in a meta line: the summary reads as a link, the citation as a line of its own. */
+.article-cite summary { cursor: pointer; color: var(--ui-accent); }
+.article-cite code { display: block; margin-top: 0.25rem; white-space: normal; }
+
 .section-card { display: flex; flex-direction: column; gap: 0.5rem; padding: var(--ui-pad); transition: border-color 150ms; }
 .section-card:hover { border-color: var(--ui-accent); }
 
@@ -698,7 +702,7 @@ pre:hover > .code-copy-btn,
   position: absolute;
   inset: 0 auto 0 0;
   width: calc(var(--share) * 100%);
-  background: currentColor;
+  background: var(--ui-accent);
   opacity: 0.08;
   pointer-events: none;
 }

package/dist/chart.js

@@ -167,12 +167,13 @@ const MARGIN_TOP = 0.15;
  */
 export function TimeChart({ series, label, ranges = typeof series === 'function' ? CHART_RANGES : DAILY_RANGES, range: initial = ranges.includes('30d') ? '30d' : ranges[0], aggregate = 'last', fromZero = false, format = formatChartValue, candles: initialCandles = false, height, controls, markers, step: initialStep, onView, className, }) {
     const box = useRef(null);
-    const chart = useRef(null);
     const formatRef = useRef(format);
     formatRef.current = format;
     const onViewRef = useRef(onView);
     onViewRef.current = onView;
-    const [ready, setReady] = useState(false);
+    // The drawn chart once the library has loaded, else null: the handle is the
+    // readiness, so no flag can say ready over a chart that is gone.
+    const [chart, setChart] = useState(null);
     const [range, setRange] = useState(initial);
     const [step, setStep] = useState(initialStep ?? null);
     const [candles, setCandles] = useState(initialCandles);
@@ -186,6 +187,7 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         if (!el)
             return;
         let disposed = false;
+        let built = null;
         import('lightweight-charts').then(({ createChart, createSeriesMarkers, AreaSeries, CandlestickSeries, HistogramSeries, ColorType, CrosshairMode, LineStyle, LineType }) => {
             if (disposed)
                 return;
@@ -258,29 +260,28 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                 api.panes()[1]?.setStretchFactor(1);
                 return volume;
             };
-            chart.current = {
+            built = {
                 api, area, candle, volume: null, addVolume, up, down, ink,
                 curved: LineType.Curved, straight: LineType.Simple,
                 areaMarkers: createSeriesMarkers(area, []),
                 candleMarkers: createSeriesMarkers(candle, []),
             };
-            setReady(true);
+            setChart(built);
         });
         return () => {
             disposed = true;
-            chart.current?.api.remove();
-            chart.current = null;
-            setReady(false);
+            built?.api.remove();
+            setChart(null);
         };
     }, []);
     // Applied to the chart in place: rebuilding it would leave a new chart with nothing drawn on it.
     useEffect(() => {
-        const c = chart.current;
-        if (!ready || !c)
+        const c = chart;
+        if (!c)
             return;
         c.api.priceScale('right').applyOptions({ scaleMargins: { top: MARGIN_TOP, bottom: fromZero ? 0 : 0.1 } });
         c.area.applyOptions({ lineType: aggregate === 'last' ? c.straight : c.curved, autoscaleInfoProvider: fromZero ? fromZeroScale : ownScale });
-    }, [ready, fromZero, aggregate]);
+    }, [chart, fromZero, aggregate]);
     // One request per resolution for the life of the loader: every range from 30D up reads the same days.
     const cache = useRef(new Map());
     useEffect(() => {
@@ -330,8 +331,8 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
     }, [points, range, ranges.length, resolution, step, aggregate]);
     // While a resolution loads, the last one stays under the skeleton; an empty or failed one clears it.
     useEffect(() => {
-        const c = chart.current;
-        if (!ready || !c || !source)
+        const c = chart;
+        if (!c || !source)
             return;
         const shown = view?.shown ?? [];
         const asCandles = candles && !!view?.ohlc;
@@ -364,7 +365,7 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         c.areaMarkers.setMarkers(asCandles ? [] : drawn);
         c.candleMarkers.setMarkers(asCandles ? drawn : []);
         c.api.timeScale().fitContent();
-    }, [ready, source, view, candles, markers]);
+    }, [chart, source, view, candles, markers]);
     // Reported once there are points to step, so a step read from a URL is not cleared while they load.
     const shown = !!view;
     const picked = step && step === view?.step ? step : null;
@@ -382,5 +383,5 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                     top: box.current.offsetTop + tip.y,
                     ...(tip.x < box.current.clientWidth / 2 ? { left: tip.x } : { right: box.current.clientWidth - tip.x }),
                     translate: tip.y < 48 ? '0 1rem' : '0 calc(-100% - 0.75rem)',
-                }, children: tip.label })), (!ready || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (controls || ranges.length > 1 || daily || view?.ohlc) && (_jsxs("div", { className: "chart-controls", children: [controls, ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => setRange(r), children: RANGE[r].label }, r))) })), daily && (_jsx("div", { role: "group", "aria-label": "Step", children: STEPS.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view?.step, disabled: !view?.steps.includes(s), onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) })), view?.ohlc && (_jsx("div", { children: _jsx("button", { type: "button", "aria-pressed": candles, "aria-label": "Candles", title: "Candles", onClick: () => setCandles(c => !c), children: _jsxs("svg", { className: "chart-icon", viewBox: "0 0 12 12", "aria-hidden": true, children: [_jsx("path", { d: "M3.5 1v2M3.5 9v2M8.5 2v3M8.5 9v1", stroke: "currentColor" }), _jsx("rect", { x: "2", y: "3", width: "3", height: "6", rx: "0.5", fill: "currentColor" }), _jsx("rect", { x: "7", y: "5", width: "3", height: "4", rx: "0.5", fill: "currentColor" })] }) }) }))] }))] }));
+                }, children: tip.label })), (!chart || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (controls || ranges.length > 1 || daily || view?.ohlc) && (_jsxs("div", { className: "chart-controls", children: [controls, ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => setRange(r), children: RANGE[r].label }, r))) })), daily && (_jsx("div", { role: "group", "aria-label": "Step", children: STEPS.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view?.step, disabled: !view?.steps.includes(s), onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) })), view?.ohlc && (_jsx("div", { children: _jsx("button", { type: "button", "aria-pressed": candles, "aria-label": "Candles", title: "Candles", onClick: () => setCandles(c => !c), children: _jsxs("svg", { className: "chart-icon", viewBox: "0 0 12 12", "aria-hidden": true, children: [_jsx("path", { d: "M3.5 1v2M3.5 9v2M8.5 2v3M8.5 9v1", stroke: "currentColor" }), _jsx("rect", { x: "2", y: "3", width: "3", height: "6", rx: "0.5", fill: "currentColor" }), _jsx("rect", { x: "7", y: "5", width: "3", height: "4", rx: "0.5", fill: "currentColor" })] }) }) }))] }))] }));
 }

package/dist/conformance.d.ts

@@ -123,13 +123,8 @@ openapi?: readonly string[]): Record<string, {
     url: string;
     at: (json: Record<string, unknown>) => unknown;
 }>;
-/**
- * Both A2A well-known paths must serve the identical card. v0.3 renamed
- * agent.json to agent-card.json and defined no fallback either way, so an origin
- * that lets them drift answers two different questions to two halves of its
- * callers.
- */
-export declare function agentCardParity(t: Tester): Promise<void>;
+/** The A2A card at `agent-card.json`: complete, and its `url` an endpoint that answers. */
+export declare function agentCardChecks(t: Tester): Promise<void>;
 /**
  * Any surface an agent recrawls should answer a conditional GET with a 304.
  *
@@ -140,7 +135,7 @@ export declare function agentCardParity(t: Tester): Promise<void>;
  * will pass is a check that measures nothing.
  */
 export declare function conditionalGetChecks(t: Tester, paths: readonly string[]): Promise<void>;
-/** The JSON descriptors every S10 origin serves: the two agent-card paths, the OpenAPI pair, the MCP manifest and the server card. */
+/** The JSON descriptors every S10 origin serves: the agent card, the OpenAPI pair, the MCP manifest and the server card. */
 export declare const S10_DESCRIPTORS: readonly string[];
 /**
  * A JSON descriptor is revalidatable — an agent card, an OpenAPI document, a

package/dist/conformance.js

@@ -252,7 +252,6 @@ openapi = ['/openapi.json', '/.well-known/openapi.json']) {
     const version = (j) => j.version;
     return {
         card: { url: `${t.base}/.well-known/agent-card.json`, at: version },
-        legacyCard: { url: `${t.base}/.well-known/agent.json`, at: version },
         mcpManifest: { url: `${t.base}/.well-known/mcp.json`, at: version },
         serverCard: { url: `${t.endpoint}/server-card`, at: version },
         ...Object.fromEntries(openapi.map(path => [
@@ -261,20 +260,10 @@ openapi = ['/openapi.json', '/.well-known/openapi.json']) {
         ])),
     };
 }
-/**
- * Both A2A well-known paths must serve the identical card. v0.3 renamed
- * agent.json to agent-card.json and defined no fallback either way, so an origin
- * that lets them drift answers two different questions to two halves of its
- * callers.
- */
-export async function agentCardParity(t) {
-    const [a, b] = await Promise.all([
-        fetch(`${t.base}/.well-known/agent-card.json`).then(r => r.json()),
-        fetch(`${t.base}/.well-known/agent.json`).then(r => r.json()),
-    ]);
-    t.check('agent card parity', JSON.stringify(a) === JSON.stringify(b), 'agent.json === agent-card.json');
-    // A card missing a required field is a card a spec-current client rejects, and
-    // parity alone happily reports two identical unusable ones.
+/** The A2A card at `agent-card.json`: complete, and its `url` an endpoint that answers. */
+export async function agentCardChecks(t) {
+    const a = await fetch(`${t.base}/.well-known/agent-card.json`).then(r => r.json());
+    // A card missing a required field is a card a spec-current client rejects.
     const required = [
         'protocolVersion',
         'name',
@@ -335,10 +324,9 @@ export async function conditionalGetChecks(t, paths) {
         }
     }
 }
-/** The JSON descriptors every S10 origin serves: the two agent-card paths, the OpenAPI pair, the MCP manifest and the server card. */
+/** The JSON descriptors every S10 origin serves: the agent card, the OpenAPI pair, the MCP manifest and the server card. */
 export const S10_DESCRIPTORS = [
     '.well-known/agent-card.json',
-    '.well-known/agent.json',
     '.well-known/openapi.json',
     'openapi.json',
     '.well-known/mcp.json',
@@ -635,7 +623,7 @@ export async function rolaOriginCheck(t, opts = {}) {
 export async function standardSuite(t, cfg) {
     const init = await transportChecks(t, t.clientName, cfg.capabilities);
     await versionCoherence(t, cfg.version, standardVersionSources(t, cfg.openapi), init.result?.serverInfo?.version);
-    await agentCardParity(t);
+    await agentCardChecks(t);
     await annotationChecks(t, { writes: cfg.writes });
     await manifestParity(t, cfg.manifest);
     if (cfg.budget)

package/dist/editor.js

@@ -421,10 +421,10 @@ export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], p
     const uploadAttempt = useRef(0);
     const initialValueRef = useRef(value);
     const onChangeRef = useRef(onChange);
-    const debounceRef = useRef(undefined);
-    // An edit made and not yet reported. `onUpdate` fires for edits only, never
-    // for the `setContent` that loads the stored value.
-    const pendingRef = useRef(false);
+    // The timer of an edit made and not yet reported, or null when every edit
+    // has been. `onUpdate` fires for edits only, never for the `setContent` that
+    // loads the stored value.
+    const pendingRef = useRef(null);
     // Written AFTER render, not during: a ref mutated mid-render can tear under
     // concurrent rendering. Only read from events and timeouts, which run later.
     useEffect(() => {
@@ -441,10 +441,10 @@ export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], p
             transformPastedHTML: cleanPastedHtml,
         },
         onUpdate: ({ editor }) => {
-            clearTimeout(debounceRef.current);
-            pendingRef.current = true;
-            debounceRef.current = setTimeout(() => {
-                pendingRef.current = false;
+            if (pendingRef.current)
+                clearTimeout(pendingRef.current);
+            pendingRef.current = setTimeout(() => {
+                pendingRef.current = null;
                 onChangeRef.current(editor.getHTML());
             }, debounceMs);
         },
@@ -452,10 +452,10 @@ export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], p
         // before the click fires — never drops the final keystroke. A blur with no
         // edit reports nothing.
         onBlur: ({ editor }) => {
-            clearTimeout(debounceRef.current);
             if (!pendingRef.current)
                 return;
-            pendingRef.current = false;
+            clearTimeout(pendingRef.current);
+            pendingRef.current = null;
             onChangeRef.current(editor.getHTML());
         },
         immediatelyRender: false,
@@ -465,7 +465,10 @@ export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], p
             }
         },
     });
-    useEffect(() => () => clearTimeout(debounceRef.current), []);
+    useEffect(() => () => {
+        if (pendingRef.current)
+            clearTimeout(pendingRef.current);
+    }, []);
     // Accept an outside change, but never while the author is typing into it.
     useEffect(() => {
         if (!editor || editor.isFocused)

package/dist/http.d.ts

@@ -188,8 +188,9 @@ export declare class HttpError extends Error {
     constructor(status: number, message: string, extra?: Record<string, unknown> | undefined);
 }
 /**
- * Run a handler; a thrown `HttpError` becomes its own answer, anything else a
- * logged 500 that names nothing internal. One handler here echoed every
+ * Run a handler; a thrown `HttpError` becomes its own answer, a thrown
+ * `Response` is the answer as built (a 429 keeps its `Retry-After`), anything
+ * else a logged 500 that names nothing internal. One handler here echoed every
  * exception's message to the caller, which is how a database error's text
  * becomes public.
  */

package/dist/http.js

@@ -300,8 +300,9 @@ export class HttpError extends Error {
     }
 }
 /**
- * Run a handler; a thrown `HttpError` becomes its own answer, anything else a
- * logged 500 that names nothing internal. One handler here echoed every
+ * Run a handler; a thrown `HttpError` becomes its own answer, a thrown
+ * `Response` is the answer as built (a 429 keeps its `Retry-After`), anything
+ * else a logged 500 that names nothing internal. One handler here echoed every
  * exception's message to the caller, which is how a database error's text
  * becomes public.
  */
@@ -310,6 +311,8 @@ export async function handleRoute(fn, errorMsg = 'Internal server error') {
         return await fn();
     }
     catch (error) {
+        if (error instanceof Response)
+            return error;
         if (error instanceof HttpError)
             return json({ error: error.message, ...error.extra }, error.status);
         console.error(errorMsg, error);

package/dist/indexnow.d.ts

@@ -7,13 +7,23 @@ export interface IndexNowEntry {
 }
 /** The `<loc>` and `<lastmod>` of every `<url>` in a sitemap. */
 export declare function sitemapEntries(xml: string): IndexNowEntry[];
+/** A sitemap read: its entries, and each child sitemap that did not answer and why. */
+export interface SitemapRead {
+    entries: IndexNowEntry[];
+    unread: {
+        url: string;
+        error: string;
+    }[];
+}
 /**
  * Every entry of the sitemap at `url`, following a sitemap index one level down
  * to at most 20 children. The `indexnow` and `check-pages` bins each parsed
  * sitemaps, and only one of them read an index. Throws when `url` itself does
- * not answer 200; a child that fails is skipped.
+ * not answer 200. A child that fails is listed in `unread`, never read as a
+ * sitemap of no pages: skipped silently, a dead child passed `check-pages` with
+ * its pages unchecked.
  */
-export declare function readSitemap(url: string, fetchImpl?: typeof fetch): Promise<IndexNowEntry[]>;
+export declare function readSitemap(url: string, fetchImpl?: typeof fetch): Promise<SitemapRead>;
 /**
  * The URLs modified at or after `since`. An entry with no `lastModified` is
  * left out: nothing says it changed, and the protocol asks for changed pages

package/dist/indexnow.js

@@ -35,7 +35,9 @@ export function sitemapEntries(xml) {
  * Every entry of the sitemap at `url`, following a sitemap index one level down
  * to at most 20 children. The `indexnow` and `check-pages` bins each parsed
  * sitemaps, and only one of them read an index. Throws when `url` itself does
- * not answer 200; a child that fails is skipped.
+ * not answer 200. A child that fails is listed in `unread`, never read as a
+ * sitemap of no pages: skipped silently, a dead child passed `check-pages` with
+ * its pages unchecked.
  */
 export async function readSitemap(url, fetchImpl = fetch) {
     const res = await fetchImpl(url);
@@ -43,12 +45,20 @@ export async function readSitemap(url, fetchImpl = fetch) {
         throw new Error(`${url} answered ${res.status}`);
     const xml = await res.text();
     if (!/<sitemapindex/i.test(xml))
-        return sitemapEntries(xml);
+        return { entries: sitemapEntries(xml), unread: [] };
     const children = [...xml.matchAll(/<loc>([\s\S]*?)<\/loc>/g)].slice(0, 20).map(m => decodeEntities(m[1].trim()));
-    const entries = [];
-    for (const child of children)
-        entries.push(...(await readSitemap(child, fetchImpl).catch(() => [])));
-    return entries;
+    const read = { entries: [], unread: [] };
+    for (const child of children) {
+        try {
+            const sub = await readSitemap(child, fetchImpl);
+            read.entries.push(...sub.entries);
+            read.unread.push(...sub.unread);
+        }
+        catch (e) {
+            read.unread.push({ url: child, error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return read;
 }
 /**
  * The URLs modified at or after `since`. An entry with no `lastModified` is

package/dist/knip.js

@@ -1,6 +1,6 @@
 // knip.ts — the knip configuration every app here shares: what the App
 // Router loads by convention and nothing imports, the scripts the routines
-// run from the command line, and the two dependencies no TS import names.
+// run from the command line, and the dependency no TS import names.
 // An app's `knip.ts` spreads it and adds what is its own:
 //
 //   import base from 'wiki-formant/knip';
@@ -23,8 +23,6 @@ const config = {
     ignoreDependencies: [
         // Reached through `@tailwindcss/postcss` and the `@import` in globals.css.
         'tailwindcss',
-        // Imported by the generated Prisma client.
-        '@prisma/client',
     ],
     // The Vercel CLI the scripts shell out to for a cache tag; a global, never a dependency.
     ignoreBinaries: ['vercel'],

package/dist/link-check.js

@@ -193,6 +193,9 @@ const YOUTUBE_WATCH = /^https?:\/\/(?:(?:www\.)?youtube\.com\/(?:watch\?(?:[^#]*
  * video. oEmbed can:
  *
  *   200 → public and embeddable | 404 → deleted | 401/403 → private or embedding off
+ *
+ * A 429 is YouTube rationing the sweep, walled as `attempt` walls it: read off
+ * its status alone, `verdictOf` called every video in a throttled run dead.
  */
 async function probeYouTube(videoId, opts = {}) {
     const { timeoutMs } = { ...DEFAULTS, ...opts };
@@ -208,7 +211,7 @@ async function probeYouTube(videoId, opts = {}) {
         if (res.status === 401 || res.status === 403) {
             return { status: res.status, ok: false, reason: 'restricted (private or embedding disabled)' };
         }
-        return { status: res.status, ok: res.status < 400 };
+        return { status: res.status, ok: res.status < 400, ...(res.status === 429 && { walled: true }) };
     }
     catch (err) {
         return { status: 0, ok: false, ...describeFailure(err) };

package/dist/openapi.d.ts

@@ -0,0 +1,139 @@
+import { type License } from './license.js';
+import { type ToolSchema } from './mcp.js';
+type Schema = Record<string, unknown>;
+export interface OpenApiInfo {
+    title: string;
+    /** The server version, the number the agent card and MCP `initialize` carry. */
+    version: string;
+    description: string;
+    license: License;
+    siteUrl: string;
+    contact?: {
+        name: string;
+        url: string;
+    };
+}
+/** The document: version, info, the one server, the paths, and components when there are any. */
+export declare function openApiDocument<P extends object, C extends object>(info: OpenApiInfo, paths: P, components?: C): {
+    components?: C | undefined;
+    openapi: "3.1.0";
+    info: {
+        license: {
+            name: string;
+            identifier: string;
+        };
+        contact?: {
+            name: string;
+            url: string;
+        } | undefined;
+        title: string;
+        version: string;
+        description: string;
+    };
+    servers: {
+        url: string;
+    }[];
+    paths: P;
+};
+/** A required JSON request body. */
+export declare const jsonBody: (schema: Schema) => {
+    required: boolean;
+    content: {
+        'application/json': {
+            schema: Schema;
+        };
+    };
+};
+/** A JSON response, its schema left open when none is given. */
+export declare const jsonResponse: (description: string, schema?: Schema) => {
+    description: string;
+    content: {
+        'application/json': {
+            schema: Schema;
+        };
+    };
+};
+/**
+ * A tool's input schema as a REST body, less the fields the path carries. A
+ * property whose `items` is one of `refs` points at its component instead of
+ * inlining it, so a block schema is written once.
+ */
+export declare function toolBody(input: Pick<ToolSchema, 'properties' | 'required'>, { inPath, refs }?: {
+    inPath?: readonly string[];
+    refs?: Record<string, Schema>;
+}): {
+    required: boolean;
+    content: {
+        'application/json': {
+            schema: Schema;
+        };
+    };
+};
+/** The validator a recrawling agent sends: a match costs a 304 rather than the body. */
+export declare const IF_NONE_MATCH: {
+    name: string;
+    in: string;
+    required: boolean;
+    schema: {
+        type: string;
+    };
+    description: string;
+};
+export declare const NOT_MODIFIED: {
+    description: string;
+};
+/** `/llms.txt`, answered from one corpus validator. */
+export declare const llmsTxtPath: (summary: string) => {
+    get: {
+        summary: string;
+        parameters: {
+            name: string;
+            in: string;
+            required: boolean;
+            schema: {
+                type: string;
+            };
+            description: string;
+        }[];
+        responses: {
+            '200': {
+                description: string;
+                content: {
+                    'text/plain': {};
+                };
+            };
+            '304': {
+                description: string;
+            };
+        };
+    };
+};
+/** An MCP endpoint: the tools it serves, and what every endpoint `mcpResponse` serves has in common. */
+export declare function mcpPath(tools: readonly string[], opts?: {
+    summary?: string;
+    note?: string;
+}): {
+    post: {
+        summary: string;
+        description: string;
+        requestBody: {
+            required: boolean;
+            content: {
+                'application/json': {
+                    schema: Schema;
+                };
+            };
+        };
+        responses: {
+            '200': {
+                description: string;
+                content: {
+                    'application/json': {
+                        schema: Schema;
+                    };
+                };
+            };
+        };
+    };
+};
+export {};

package/dist/openapi.js

@@ -0,0 +1,75 @@
+// openapi.ts — the OpenAPI 3.1 frame every agent surface serves at
+// /.well-known/openapi.json.
+//
+// What is per-site is the paths only it has. The frame, the body and response
+// shapes, the conditional GET, the MCP endpoint and /llms.txt read the same on
+// every site, so they are built here and a spec carries only its own paths.
+import { openApiLicense } from './license.js';
+import { DEFAULT_MAX_BATCH, MCP_PROTOCOL_VERSIONS } from './mcp.js';
+import { MCP_RATE_LIMIT_TEXT } from './rate-limit.js';
+/** The document: version, info, the one server, the paths, and components when there are any. */
+export function openApiDocument(info, paths, components) {
+    const { title, version, description, license, siteUrl, contact } = info;
+    return {
+        openapi: '3.1.0',
+        info: { title, version, description, ...(contact ? { contact } : {}), license: openApiLicense(license) },
+        servers: [{ url: siteUrl }],
+        paths,
+        ...(components ? { components } : {}),
+    };
+}
+/** A required JSON request body. */
+export const jsonBody = (schema) => ({ required: true, content: { 'application/json': { schema } } });
+/** A JSON response, its schema left open when none is given. */
+export const jsonResponse = (description, schema = {}) => ({
+    description,
+    content: { 'application/json': { schema } },
+});
+/**
+ * A tool's input schema as a REST body, less the fields the path carries. A
+ * property whose `items` is one of `refs` points at its component instead of
+ * inlining it, so a block schema is written once.
+ */
+export function toolBody(input, { inPath = [], refs = {} } = {}) {
+    const kept = (k) => !inPath.includes(k);
+    const ref = (items) => Object.entries(refs).find(([, s]) => s === items)?.[0];
+    return jsonBody({
+        type: 'object',
+        required: input.required?.filter(kept),
+        properties: Object.fromEntries(Object.entries(input.properties)
+            .filter(([k]) => kept(k))
+            .map(([k, v]) => {
+            const name = ref(v.items);
+            return [k, name ? { ...v, items: { $ref: `#/components/schemas/${name}` } } : v];
+        })),
+    });
+}
+/** The validator a recrawling agent sends: a match costs a 304 rather than the body. */
+export const IF_NONE_MATCH = {
+    name: 'If-None-Match',
+    in: 'header',
+    required: false,
+    schema: { type: 'string' },
+    description: 'ETag from an earlier fetch. A match returns 304 with no body.',
+};
+export const NOT_MODIFIED = { description: 'Unchanged since the supplied validator' };
+/** `/llms.txt`, answered from one corpus validator. */
+export const llmsTxtPath = (summary) => ({
+    get: {
+        summary,
+        parameters: [IF_NONE_MATCH],
+        responses: { '200': { description: 'OK', content: { 'text/plain': {} } }, '304': NOT_MODIFIED },
+    },
+});
+/** An MCP endpoint: the tools it serves, and what every endpoint `mcpResponse` serves has in common. */
+export function mcpPath(tools, opts = {}) {
+    return {
+        post: {
+            summary: opts.summary ?? 'MCP server (JSON-RPC 2.0, Streamable HTTP)',
+            description: `Model Context Protocol ${MCP_PROTOCOL_VERSIONS.join(', ')}. Tools: ${tools.join(', ')}. ` +
+                `${opts.note ? `${opts.note} ` : ''}Batches are capped at ${DEFAULT_MAX_BATCH}; rate limit ${MCP_RATE_LIMIT_TEXT}.`,
+            requestBody: jsonBody({ type: 'object', description: 'JSON-RPC 2.0 request or batch' }),
+            responses: { '200': jsonResponse('JSON-RPC 2.0 response') },
+        },
+    };
+}

package/dist/react.d.ts

@@ -385,7 +385,8 @@ export declare function restoreViaPost<Id>(endpoint: string): RestoreRevision<Id
  * Confirm, restore, report. Of the three copies one asked no confirmation, one
  * dropped a failure silently, and one reported it through `alert`. A restore
  * writes the old state forward as a new revision in all three, which is what
- * the default question says.
+ * the default question says. A `restore` that throws is a failure like one
+ * that answers with its reason: it shows as `error`, never as nothing.
  */
 export declare function useRevisionRestore<Id>(restore: RestoreRevision<Id>, options: {
     onRestored: () => void;
@@ -433,6 +434,13 @@ export interface SnapRow<T extends HTMLElement> {
  * there reads as broken. Motion honours `prefers-reduced-motion`.
  */
 export declare function useSnapRow<T extends HTMLElement = HTMLDivElement>(): SnapRow<T>;
+/** The boundary's children render, or what they threw does: a thrown `null` is still a failure. */
+type BoundaryState = {
+    status: 'ok';
+} | {
+    status: 'failed';
+    error: unknown;
+};
 /**
  * The one thing hooks cannot express, so it is worth owning once.
  *
@@ -449,18 +457,9 @@ export declare class ErrorBoundary extends Component<{
      */
     fallback: (retry: () => void, error: unknown) => ReactNode;
     onError?: (error: unknown) => void;
-}, {
-    failed: boolean;
-    error: unknown;
-}> {
-    state: {
-        failed: boolean;
-        error: unknown;
-    };
-    static getDerivedStateFromError(error: unknown): {
-        failed: boolean;
-        error: unknown;
-    };
+}, BoundaryState> {
+    state: BoundaryState;
+    static getDerivedStateFromError(error: unknown): BoundaryState;
     componentDidCatch(error: unknown): void;
     render(): ReactNode;
 }

package/dist/react.js

@@ -52,8 +52,10 @@ function useCollapsibleSidebar(options = {}) {
     // Start open on the server and on the first client paint. SSR has no viewport
     // and no storage, so any other guess is a guaranteed mismatch on some loads.
     const [open, setOpenState] = useState(true);
-    const [isMobile, setIsMobile] = useState(false);
-    const [ready, setReady] = useState(false);
+    // Unknown until the effect has read matchMedia: one value, so the rail is
+    // never mobile before it is ready, and `ready` is never set apart from it.
+    const [viewport, setViewport] = useState('unknown');
+    const ready = viewport !== 'unknown';
     // Set as soon as the reader touches the control, so a later viewport change
     // cannot overwrite what they asked for.
     const chosen = useRef(false);
@@ -61,7 +63,7 @@ function useCollapsibleSidebar(options = {}) {
         const mql = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
         const stored = readStored(storageKey);
         const apply = (matches) => {
-            setIsMobile(matches);
+            setViewport(matches ? 'mobile' : 'desktop');
             // The breakpoint supplies a default, never an override. This is bug 1.
             setOpenState(current => resolveSidebarOpen({ chosen: chosen.current, current, stored, isMobile: matches }));
             // The same number lives in the stylesheet, and must. Say so out loud the
@@ -79,7 +81,6 @@ function useCollapsibleSidebar(options = {}) {
             }
         };
         apply(mql.matches);
-        setReady(true);
         const handler = (e) => apply(e.matches);
         mql.addEventListener('change', handler);
         return () => mql.removeEventListener('change', handler);
@@ -106,7 +107,7 @@ function useCollapsibleSidebar(options = {}) {
             return;
         document.documentElement.setAttribute(SIDEBAR_ATTRIBUTE, open ? 'open' : 'closed');
     }, [open, ready]);
-    return { open, setOpen, toggle, isMobile, ready };
+    return { open, setOpen, toggle, isMobile: viewport === 'mobile', ready };
 }
 // ---- sharing that state across the layout -----------------------------------
 // The rail and the button that toggles it are rarely siblings — the button
@@ -756,11 +757,11 @@ export function restoreViaPost(endpoint) {
  * Confirm, restore, report. Of the three copies one asked no confirmation, one
  * dropped a failure silently, and one reported it through `alert`. A restore
  * writes the old state forward as a new revision in all three, which is what
- * the default question says.
+ * the default question says. A `restore` that throws is a failure like one
+ * that answers with its reason: it shows as `error`, never as nothing.
  */
 export function useRevisionRestore(restore, options) {
-    const [busyId, setBusyId] = useState(null);
-    const [error, setError] = useState(null);
+    const [state, setState] = useState({ status: 'idle' });
     // One restore at a time: a second, started while the first is in flight,
     // would have its "Restoring…" cleared by the first one finishing.
     const inFlight = useRef(false);
@@ -772,21 +773,26 @@ export function useRevisionRestore(restore, options) {
         if (question && !window.confirm(question))
             return;
         inFlight.current = true;
-        setBusyId(id);
-        setError(null);
+        setState({ status: 'restoring', id });
+        let failure;
         try {
-            const failure = await restore(id);
-            if (failure)
-                setError(failure);
-            else
-                onRestored();
+            failure = await restore(id);
+        }
+        catch (err) {
+            failure = err instanceof Error && err.message ? err.message : 'Restore failed.';
         }
         finally {
             inFlight.current = false;
-            setBusyId(null);
         }
+        setState(failure ? { status: 'failed', error: failure } : { status: 'idle' });
+        if (!failure)
+            onRestored();
     }, [restore, onRestored, confirm]);
-    return { restore: run, busyId, error };
+    return {
+        restore: run,
+        busyId: state.status === 'restoring' ? state.id : null,
+        error: state.status === 'failed' ? state.error : null,
+    };
 }
 // ---- copy to clipboard ------------------------------------------------------
 /**
@@ -866,7 +872,6 @@ export function useSnapRow() {
 }
 const snapEnd = (row) => row.scrollWidth - row.clientWidth;
 const snapTo = (row, left, smooth = true) => row.scrollTo({ left, behavior: smooth && !matchMedia('(prefers-reduced-motion: reduce)').matches ? 'smooth' : 'auto' });
-// ---- error boundary ---------------------------------------------------------
 /**
  * The one thing hooks cannot express, so it is worth owning once.
  *
@@ -876,16 +881,16 @@ const snapTo = (row, left, smooth = true) => row.scrollTo({ left, behavior: smoo
  * caller's, and the boundary only decides when to offer it.
  */
 export class ErrorBoundary extends Component {
-    state = { failed: false, error: null };
+    state = { status: 'ok' };
     static getDerivedStateFromError(error) {
-        return { failed: true, error };
+        return { status: 'failed', error };
     }
     componentDidCatch(error) {
         this.props.onError?.(error);
     }
     render() {
-        if (this.state.failed) {
-            return this.props.fallback(() => this.setState({ failed: false, error: null }), this.state.error);
+        if (this.state.status === 'failed') {
+            return this.props.fallback(() => this.setState({ status: 'ok' }), this.state.error);
         }
         return this.props.children;
     }

package/dist/stats-figures.d.ts

@@ -20,8 +20,13 @@ export interface PasskeyButtonProps {
     errorClassName?: string;
 }
 export declare function PasskeyButton({ endpoint, invite, className, errorClassName }: PasskeyButtonProps): import("react").JSX.Element;
-/** Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the page. */
-export declare function PasskeySignOut({ endpoint, className }: {
+/**
+ * Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the
+ * page. A sign-out the server did not take says so: reloaded, it showed the
+ * stats again with no word of why.
+ */
+export declare function PasskeySignOut({ endpoint, className, errorClassName }: {
     endpoint: string;
     className?: string;
+    errorClassName?: string;
 }): import("react").JSX.Element;

package/dist/stats-figures.js

@@ -96,13 +96,12 @@ async function post(endpoint, body) {
         throw new Error((await res.json().catch(() => null))?.error ?? 'Sign-in failed.');
     return res.status === 204 ? null : res.json();
 }
+const IDLE = { status: 'idle' };
 export function PasskeyButton({ endpoint, invite, className, errorClassName }) {
     const saving = !!invite;
-    const [busy, setBusy] = useState(false);
-    const [error, setError] = useState(null);
+    const [attempt, setAttempt] = useState(IDLE);
     async function go() {
-        setBusy(true);
-        setError(null);
+        setAttempt({ status: 'busy' });
         try {
             const optionsJSON = await post(endpoint, { invite });
             const response = saving ? await startRegistration({ optionsJSON }) : await startAuthentication({ optionsJSON });
@@ -111,16 +110,24 @@ export function PasskeyButton({ endpoint, invite, className, errorClassName }) {
         }
         catch (e) {
             // A prompt the person closed throws NotAllowedError, which needs no message.
-            setError(e instanceof Error && e.name !== 'NotAllowedError' ? e.message : null);
-            setBusy(false);
+            setAttempt(e instanceof Error && e.name !== 'NotAllowedError' ? { status: 'failed', error: e.message } : IDLE);
         }
     }
-    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, onClick: go, disabled: busy, children: saving ? 'Save a passkey' : 'Sign in with a passkey' }), error && (_jsx("p", { role: "alert", className: errorClassName, children: error }))] }));
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, onClick: go, disabled: attempt.status === 'busy', children: saving ? 'Save a passkey' : 'Sign in with a passkey' }), attempt.status === 'failed' && (_jsx("p", { role: "alert", className: errorClassName, children: attempt.error }))] }));
 }
-/** Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the page. */
-export function PasskeySignOut({ endpoint, className }) {
-    return (_jsx("button", { type: "button", className: className, onClick: async () => {
-            await fetch(endpoint, { method: 'DELETE' }).catch(() => null);
-            location.reload();
-        }, children: "Sign out" }));
+/**
+ * Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the
+ * page. A sign-out the server did not take says so: reloaded, it showed the
+ * stats again with no word of why.
+ */
+export function PasskeySignOut({ endpoint, className, errorClassName }) {
+    const [attempt, setAttempt] = useState(IDLE);
+    async function go() {
+        setAttempt({ status: 'busy' });
+        const res = await fetch(endpoint, { method: 'DELETE' }).catch(() => null);
+        if (res?.ok)
+            return location.reload();
+        setAttempt({ status: 'failed', error: res ? `Sign-out failed (${res.status}). Try again.` : 'Sign-out did not reach the server. Try again.' });
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, onClick: go, disabled: attempt.status === 'busy', children: "Sign out" }), attempt.status === 'failed' && (_jsx("p", { role: "alert", className: errorClassName, children: attempt.error }))] }));
 }

package/dist/stats.js

@@ -83,7 +83,7 @@ export function Stats({ digest: d, days, filter = {}, ranges = STATS_RANGES, lin
  */
 export async function StatsGate({ gate, session, invite, host, endpoint = '/api/passkey', children, classNames: c = {} }) {
     if (!invite && (await gate.signedIn(session))) {
-        return (_jsxs(_Fragment, { children: [await children(), _jsx("div", { className: c.actions, children: _jsx(PasskeySignOut, { endpoint: endpoint, className: c.button }) })] }));
+        return (_jsxs(_Fragment, { children: [await children(), _jsx("div", { className: c.actions, children: _jsx(PasskeySignOut, { endpoint: endpoint, className: c.button, errorClassName: c.error }) })] }));
     }
     return (_jsxs(_Fragment, { children: [_jsx("p", { className: c.text, children: invite ? `Save a passkey on this device to open ${host}'s stats.` : 'Sign in with a passkey saved for this site.' }), _jsx("div", { className: c.actions, children: _jsx(PasskeyButton, { endpoint: endpoint, invite: invite, className: c.button, errorClassName: c.error }) })] }));
 }

package/dist/well-known.d.ts

@@ -50,13 +50,7 @@ export interface AgentCardConfig {
     /** Anything this origin advertises that the others do not. */
     extra?: Record<string, unknown>;
 }
-/**
- * An A2A Agent Card. Serve the same object at both `/.well-known/agent.json`
- * and `/.well-known/agent-card.json`: v0.3 renamed the path and defined no
- * fallback in either direction, so a spec-current client probes only the new
- * one and a client on an older SDK probes only the old one. Serving one path
- * means half the callers conclude the origin has no agent at all.
- */
+/** An A2A Agent Card, served at `/.well-known/agent-card.json`, the path A2A v0.3 names. */
 export declare function agentCard(config: AgentCardConfig): Record<string, unknown>;
 /** The registry manifest (`server.json`) fields a card projects. */
 export interface ServerManifest {
@@ -150,7 +144,7 @@ export declare function descriptorHandler(body: unknown, opts?: {
 /** The whole `<mcp-url>/server-card` route, projected from server.json. */
 export declare const serverCardHandler: (manifest: ServerManifest) => ((request: Request) => Response);
 export interface WellKnownDocs {
-    /** Served at both `agent.json` and `agent-card.json`. */
+    /** `agent-card.json`. */
     agentCard?: unknown;
     /** `mcp.json`. */
     mcpManifest?: unknown;

package/dist/well-known.js

@@ -67,13 +67,7 @@ export function skillsFromTools(tools) {
  * origins here were serving one.
  */
 const A2A_PROTOCOL_VERSION = '0.3.0';
-/**
- * An A2A Agent Card. Serve the same object at both `/.well-known/agent.json`
- * and `/.well-known/agent-card.json`: v0.3 renamed the path and defined no
- * fallback in either direction, so a spec-current client probes only the new
- * one and a client on an older SDK probes only the old one. Serving one path
- * means half the callers conclude the origin has no agent at all.
- */
+/** An A2A Agent Card, served at `/.well-known/agent-card.json`, the path A2A v0.3 names. */
 export function agentCard(config) {
     const { name, description, url, version, skills, license, licenseScope, organization, documentationUrl, mcpEndpoint, extra } = config;
     const endpoint = mcpEndpoint === null ? url : (mcpEndpoint ?? `${url}/api/mcp`);
@@ -234,7 +228,6 @@ export function wellKnownHandler(docs) {
         : typeof auth === 'function' ? auth
             : registryAuthHandler(auth?.publicKey ?? process.env.MCP_REGISTRY_PUBLIC_KEY, auth?.keyType ?? process.env.MCP_REGISTRY_KEY_TYPE);
     const served = {
-        'agent.json': docs.agentCard === undefined ? undefined : descriptorHandler(docs.agentCard),
         'agent-card.json': docs.agentCard === undefined ? undefined : descriptorHandler(docs.agentCard),
         'mcp.json': docs.mcpManifest === undefined ? undefined : descriptorHandler(docs.mcpManifest),
         'openapi.json': docs.openapi === undefined ? undefined : descriptorHandler(docs.openapi),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.107.0",
+  "version": "0.111.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",
@@ -258,6 +258,11 @@
       "import": "./dist/og.js",
       "default": "./dist/og.js"
     },
+    "./openapi": {
+      "types": "./dist/openapi.d.ts",
+      "import": "./dist/openapi.js",
+      "default": "./dist/openapi.js"
+    },
     "./sanitize": {
       "types": "./dist/sanitize.d.ts",
       "import": "./dist/sanitize.js",