wiki-formant 0.85.0 → 0.86.0

package/README.md

@@ -321,6 +321,13 @@ export async function GET(request: Request) {
 
 `descriptorResponse` and `descriptorHandler` serve a JSON descriptor (an agent card, a manifest, an OpenAPI document) with its own ETag and `Access-Control-Allow-Origin: *`, since every descriptor is public and browser agents read them; six of nine routes had passed the header by hand.
 
+`wellKnownHandler({ agentCard, mcpManifest, openapi, registryAuth? })` is the whole `/.well-known/[doc]` route: the card at `agent.json` and `agent-card.json`, the manifest at `mcp.json`, the spec at `openapi.json` and the registry's proof at `mcp-registry-auth`, each through `descriptorResponse`, and a 404 for any other name. A rewrite puts `/openapi.json` on it. `registryAuth: null` serves no proof, for a tenant of a host whose namespace is the host's.
+
+```ts
+// src/app/.well-known/[doc]/route.ts
+export const GET = wellKnownHandler({ agentCard: AGENT_CARD, mcpManifest: MCP_MANIFEST, openapi: SPEC });
+```
+
 `corpusValidatorsFrom(seed, stamps)` is that pair from an aggregate: the newest of `stamps` (the epoch when every one is null), appended to `seed` for the tag. `corpusRoute(validators, build)` is the whole handler, and skips the build on a 304.
 
 ```ts
@@ -369,7 +376,7 @@ Four configs had restated these by hand on the grounds that a config could not i
 export default withWikiDefaults<NextConfig>({ async redirects() { /* … */ } }, { csp });
 ```
 
-`contentSecurityPolicy` starts from the policy all four origins shared line for line, and each directive passed replaces its default rather than appending, so the call site reads as the whole list. An empty list drops a directive.
+`contentSecurityPolicy` starts from the policy all four origins shared line for line, and each directive passed replaces its default rather than appending, so the call site reads as the whole list. An empty list drops a directive. A second argument, `{ nonce, inlineScripts }`, makes `script-src` strict where there is a nonce: `'self'`, the nonce and `scriptHash` of each inline script, with no `'unsafe-inline'`. The hash admits a static boot script without the layout reading the nonce, and moves with the script when a bump changes it.
 
 The default `frame-src` is `DEFAULT_IFRAME_HOSTS`, the same list the sanitiser's `iframeHosts` defaults to. The sanitiser's comment had asked every config to keep the two matched by hand, and one did not: its policy lacked the bare `youtube.com` and `youtube-nocookie.com` its sanitiser kept, so those embeds survived cleaning and then rendered blank. A site with its own host list passes it to the sanitiser and states the same hosts in its `frame-src`.
 
@@ -757,6 +764,15 @@ if (issues.length) return badRequest(`Invalid content: ${describeBlockIssues(iss
 // Invalid content: [2].columns[0].blocks[1]: malformed linkGrid block
 ```
 
+`defineBlocks<Block>({ defaults, checks?, pageId? })` is a wiki's whole block model from its type set. `defaults` is what inserting each type makes, and its keys are the types the wiki knows; `checks` is the leaf check for each native type, and for a core type the wiki narrows, which gets the core check as its second argument. It returns `types`, `atomicTypes` (all but the two containers), `shape`, `createBlock`, `duplicateBlock`, `validateBlocks` and `blockIssues`. `BlockTree<AtomicBlock>` from `wiki-formant/blocks` is the union it models.
+
+```ts
+export const { shape: BLOCK_SHAPE, createBlock, duplicateBlock, validateBlocks, blockIssues } = defineBlocks<Block>({
+  defaults: { ...coreBlockDefaults({ stats }), corpusStats: () => ({ type: 'corpusStats', view: 'sourceTiers' }) },
+  checks: { corpusStats: b => isCorpusView(b.view), list: (b, core) => core(b) && isSection(b.under) },
+});
+```
+
 A `codeTabs` tab's `code` is source text in every wiki here, and every view treats it that way: `CodeTabsView` escapes it into a `<pre><code>`, the sanitiser leaves it alone, the markdown twin fences it verbatim. A wiki that escapes and highlights on the server passes `highlighted` to the view. The package used to assume editors stored highlighted markup; none ever had, and every twin printed `Vec<u8>` as `Vec`.
 
 `recentPages`, `pageList` and a `list` resolve to `ResolvedPageRef`s — build each with `pageRef(page, now)`, which carries the ISO date a `<time>` needs — and `PageRefsView` renders them as a list, with a `renderItem` slot for a wiki that has its own row.
@@ -960,7 +976,7 @@ its readers asked for. The queries that return zero rows are the valuable ones
 `wiki-formant/passkey` is the door to a site's own admin pages: a passkey and
 nothing else, no account, password or email. `createPasskeyGate({ sql, rpName })`
 returns the whole of it. `gate.route` is the sign-in route, `gate.signOut` the
-sign-out route, `gate.signedIn(cookieValue)` is the check a page makes, and
+sign-out route, `gate.signedIn(cookieValue)` is the check a page makes, `gate.allows(request)` the same check over a write route's request, and
 `gate.cookie` is the cookie's name. The two tables (`Passkey`, `PasskeyToken`) ship as Prisma
 models in `prisma/passkey.prisma`, and every token is kept only as its hash.
 
@@ -1092,7 +1108,7 @@ the site's stylesheet gives them and the box a look.
 
 ## Base stylesheet
 
-`wiki-formant/base.css` is the layout the package's markup does not work without, and nothing else: columns that stack until there is room, stored tab panels that show one at a time, a copy button pinned to its block's corner and visible on focus and on touch, a table's scroll box, the stats block's grid, the code-tab strip, the banner's row and the infobox's wrapping, the breadcrumb row, the `aria-sort` arrow as a mask over `currentColor`, the stats page's grid and bars, and the chart's height and pinned buttons. It also carries the shape and motion of the primitives every site re-implemented and forked — `.spinner` (a `currentColor` ring sized by `--spinner-size`), `.skeleton`'s pulse, `.empty-state`, the wrap rule for long tokens in inline `code` — and the reduced-motion guard none of them had. No colour and no scale, so a design system's own rules override it at equal specificity. The one set of tokens it declares is the page frame every site lays out by: `--content-width` (72rem, gutters inside), `--sidebar-width` (18rem) and `--page-pad` (16 / 24 / 32px at base / 640 / 1024). They sit in the components layer, so a site never restates them in `@theme`, which would lose; an element that must differ sets its own.
+`wiki-formant/base.css` is first the layout the package's markup does not work without: columns that stack until there is room, stored tab panels that show one at a time, a copy button pinned to its block's corner and visible on focus and on touch, a table's scroll box, the stats block's grid, the code-tab strip, the banner's row and the infobox's wrapping, the breadcrumb row, the `aria-sort` arrow as a mask over `currentColor`, the stats page's grid and bars, and the chart's height and pinned buttons. It also carries the shape and motion of the primitives every site re-implemented and forked — `.spinner` (a `currentColor` ring sized by `--spinner-size`), `.skeleton`'s pulse, `.empty-state`, the wrap rule for long tokens in inline `code` — and the reduced-motion guard none of them had. That part has no colour and no scale, so a design system's own rules override it at equal specificity. The one set of tokens it declares is the page frame every site lays out by: `--content-width` (72rem, gutters inside), `--sidebar-width` (18rem) and `--page-pad` (16 / 24 / 32px at base / 640 / 1024). They sit in the components layer, so a site never restates them in `@theme`, which would lose; an element that must differ sets its own.
 
 ```css
 @import "wiki-formant/base.css" layer(components);
@@ -1100,6 +1116,19 @@ the site's stylesheet gives them and the box a look.
 
 No view emits a Tailwind utility any more — `ColumnsView` states its gap and alignment as data attributes, and an inactive code tab is `hidden` — so a site no longer needs its Tailwind to scan this package for the markup to work.
 
+After the structure comes the look: every component the package's markup names (heading anchors, code tabs and the copy button, notices, references, the infobox, stats cards and deltas, link grids, see-also cards, section cards, the link preview, the rail's table of contents, the work queues, revision diffs, sortable headers, charts) drawn from twelve tokens a site maps once, unlayered, from its own palette. Four sites had each drawn the same components in their own tokens. A site's own rule after the import still wins.
+
+```css
+:root {
+  --ui-surface: var(--color-surface-1);   --ui-muted: var(--color-text-muted);
+  --ui-surface-2: var(--color-surface-2); --ui-accent: var(--color-accent);
+  --ui-border: var(--color-border);       --ui-on-accent: var(--color-surface-0);
+  --ui-radius: var(--radius);             --ui-up: var(--color-success);
+  --ui-pad: 1rem;                         --ui-down: var(--color-error);
+  --ui-small: var(--text-small);          --ui-shadow: var(--shadow);
+}
+```
+
 ## API
 
 Every module has a subpath — `wiki-formant/taxonomy`, `wiki-formant/mcp`, and so on —
@@ -1141,6 +1170,12 @@ and overwrites any inbound copy — and the leftmost `x-forwarded-for` only wher
 `limitClient(prefix, headers, opts)` is the per-address gate, `rateLimit` over
 `clientKey`, which a dozen call sites had written out.
 
+`wiki-formant/scripts` is what a wiki's direct-database scripts share: `withClient(fn, { tag })` (a pg client that rolls back and fails the run on a throw, and invalidates the cache `tag` through the Vercel CLI when it wrote), `storeFor(client)` and `readPage` over the app's own store, `writeRevision(client, page, blocks, opts)` (one revision, refused if the page moved since it was read), `upsertWikiPage(client, page)` (a revision only when something changed), the block builders `uid`, `content`, `banner` and `infobox`, and `assertLinkShapes`, which throws on the mis-shaped link a script would otherwise store unseen. Its `ScriptClient` is the slice of a pg client they take; Prisma fits it with `$queryRawUnsafe`.
+
+`wiki-formant/link-check`'s `auditLinks(pages, { livePaths, probe?, internal? })` is a checker's whole walk: every link on every page probed once, internals checked against `livePaths` (a page's `/history` and `/edit` resolve with it, and a query rides on its path), metadata facts included, embeds collected for the caller to probe. `printLinkAudit(audit, { scope, pagesScanned })` prints what broke.
+
+`wiki-formant/knip` is the dead-code config every app spreads into its own `knip.ts`: `export default { ...base, ignoreBinaries: [...base.ignoreBinaries, 'ffmpeg'] }`.
+
 ## A bin
 
 `check-classes` fails a build on a `className` token that resolves to nothing, and counts the inverse fault — 3+ Tailwind utilities inline, which is a component class that was never named. Both sets are derived from the emitted stylesheets rather than listed, so nothing has to be maintained per project. Run it from a repo root after a build:

package/dist/base.css

@@ -1,7 +1,8 @@
 /* wiki-formant/base.css — the layout the package's markup does not work without.
 
-   Structure only: no colour, no type scale, no design token. Every value that
-   is a look rather than a mechanism is left to the importing stylesheet, which
+   Structure first: the layout the markup needs, no colour and no type scale.
+   Then, at the end, the look: every component drawn from twelve `--ui-*`
+   tokens the importing stylesheet maps from its own palette. That stylesheet
    loads this first and overrides anything here with an equally specific rule.
 
      @import "wiki-formant/base.css" layer(components);
@@ -488,3 +489,141 @@ pre:hover > .code-copy-btn,
   max-width: 100%;
   min-height: 200px;
 }
+
+/* ==== the look ================================================================
+   What the components above look like, drawn from twelve tokens a site maps
+   once from its own palette, unlayered so the mapping wins:
+
+     --ui-surface    a card's ground         --ui-muted     secondary text
+     --ui-surface-2  a strip, a label cell   --ui-accent    links, the current item
+     --ui-border     every rule and outline  --ui-on-accent text on the accent
+     --ui-radius     every corner            --ui-up        a good change, an insertion
+     --ui-pad        a card's padding        --ui-down      a bad change, a deletion
+     --ui-small      the small type size     --ui-shadow    a floating card's shadow
+
+   Four sites had each drawn these same components in their own tokens, the
+   same rules restated four ways, and the one that forgot a rule shipped it
+   unstyled. A site still overrides any of it with its own rule after this. */
+
+/* Permalink beside a heading: the glyph comes from here, so a table of contents
+   reading the heading's text never picks it up. */
+:is(h2, h3, h4, h5, h6):has(> .heading-anchor) { position: relative; }
+.heading-anchor { position: absolute; top: 0; left: -1.25rem; font-weight: 400; color: var(--ui-muted); opacity: 0; transition: opacity 0.15s; }
+.heading-anchor::before { content: '#'; }
+.heading-anchor:hover { color: var(--ui-accent); }
+:is(h2, h3, h4, h5, h6):hover > .heading-anchor,
+.heading-anchor:focus-visible { opacity: 1; }
+.link { color: var(--ui-accent); text-decoration: none; cursor: pointer; }
+.link:hover { text-decoration: underline; }
+
+/* Code tabs and the copy button. */
+.code-tabs { margin-block: 1rem; border: 1px solid var(--ui-border); border-radius: var(--ui-radius); }
+.code-tabs-list { overflow-x: auto; background: var(--ui-surface-2); border-bottom: 1px solid var(--ui-border); }
+.code-tabs-btn { padding: 0.5rem 1rem; font: inherit; font-size: var(--ui-small); color: var(--ui-muted); background: transparent; border: 0; border-bottom: 2px solid transparent; transition: color 0.15s; }
+.code-tabs-btn:hover { color: inherit; }
+/* The box clips, so the focus ring goes inside the button. */
+.code-tabs-btn:focus-visible { outline-offset: -2px; }
+.code-tabs-btn-active { color: var(--ui-accent); border-bottom-color: var(--ui-accent); }
+.code-tabs pre { margin: 0; border: 0; border-radius: 0; }
+.code-copy-btn { padding: 0.375rem; color: var(--ui-muted); background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); z-index: 1; }
+.code-copy-btn:hover { color: var(--ui-accent); }
+
+/* Notices. A notice is a claim about the page, so it reads as an aside. */
+.editorial-banner { align-items: flex-start; gap: 0.75rem; margin-block: 0.75rem; padding: 0.75rem; font-size: var(--ui-small); background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); }
+.editorial-banner-icon { flex-shrink: 0; margin-top: 0.125rem; }
+.editorial-banner-body { flex: 1; min-width: 0; margin: 0; }
+:is(.editorial-banner-unsourced, .editorial-banner-outdated, .editorial-banner-promotional, .editorial-banner-coi) { border-color: color-mix(in srgb, var(--ui-down) 35%, transparent); background: color-mix(in srgb, var(--ui-down) 8%, var(--ui-surface)); }
+:is(.editorial-banner-unsourced, .editorial-banner-outdated, .editorial-banner-promotional, .editorial-banner-coi) .editorial-banner-icon { color: var(--ui-down); }
+
+/* References. */
+.references-block { margin-top: 1.5rem; padding-top: 1rem; border-top: 1px solid var(--ui-border); }
+.references-block h2 { margin: 0 0 0.5rem; }
+.references-list { margin: 0; padding-left: 1.5rem; list-style: decimal; font-size: var(--ui-small); color: var(--ui-muted); }
+.reference-item { margin-block: 0.25rem; padding-left: 0.25rem; scroll-margin-top: 5rem; }
+.reference-item:target { background: color-mix(in srgb, var(--ui-accent) 12%, transparent); border-radius: var(--ui-radius); }
+:is(.reference-item a, .ref-backlink, .reference-link) { color: var(--ui-accent); }
+:is(.reference-item a, .ref-backlink, .reference-link):hover { text-decoration: underline; }
+
+/* The infobox and its facts. Labels are short and values are the reading, so
+   the label column takes 42%, the floor that still fits "Published:". */
+.page-with-infobox { gap: 1.5rem; }
+.infobox { padding: var(--ui-pad); background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); }
+.infobox table { table-layout: fixed; width: 100%; border-collapse: collapse; }
+.infobox :is(th, td) { padding: 0.375rem 0.5rem; font-size: var(--ui-small); text-align: left; vertical-align: top; border: 0; border-bottom: 1px solid var(--ui-border); }
+.infobox th { width: 42%; font-weight: 600; color: var(--ui-muted); }
+.infobox tr:last-child > :is(th, td) { border-bottom: 0; }
+.infobox-facts { margin: 0; }
+.infobox-series { align-items: center; gap: 0.125rem; margin-bottom: 0.75rem; padding-bottom: 0.75rem; text-align: center; font-size: var(--ui-small); color: var(--ui-muted); border-bottom: 1px solid var(--ui-border); }
+
+/* Stats blocks and the figures' change from the window before. */
+.stat-grid { gap: 0.75rem; }
+.stat-card { gap: 0.25rem; padding: var(--ui-pad); background: var(--ui-surface); border-radius: var(--ui-radius); }
+.stat-value { font-weight: 700; line-height: 1.15; }
+.stat-label { font-size: var(--ui-small); color: var(--ui-muted); }
+.stats-delta { font-size: 0.6em; font-weight: 600; }
+.stats-delta[data-better='true'] { color: var(--ui-up); }
+.stats-delta[data-better='false'] { color: var(--ui-down); }
+
+/* Columns, link grids, related pages. */
+.column-view { gap: 1rem; }
+.link-grid { display: flex; flex-direction: column; gap: 1rem; margin-block: 1rem; }
+.link-grid-group-description { margin: 0 0 0.75rem; color: var(--ui-muted); }
+.link-grid-group-description p { margin: 0; }
+.link-grid-pills { display: grid; grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr)); gap: 0.5rem; }
+.link-grid-pills > a { display: block; padding: 0.625rem 0.875rem; font-size: var(--ui-small); text-align: center; text-decoration: none; color: inherit; background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); transition: background 0.15s, border-color 0.15s, color 0.15s; }
+.link-grid-pills > a:hover { color: var(--ui-accent); background: var(--ui-surface-2); border-color: var(--ui-accent); }
+.see-also-list { display: grid; grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr)); gap: 0.75rem; margin: 0; padding: 0; list-style: none; }
+.see-also-item { display: flex; flex-direction: column; gap: 0.25rem; min-width: 0; padding: 0.75rem; color: inherit; text-decoration: none; background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); transition: border-color 0.15s; }
+.see-also-item:hover { border-color: var(--ui-accent); }
+.see-also-title { font-weight: 600; }
+.see-also-item:hover .see-also-title { color: var(--ui-accent); }
+.see-also-detail { font-size: var(--ui-small); color: var(--ui-muted); display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+.section-card { display: flex; flex-direction: column; gap: 0.5rem; padding: var(--ui-pad); background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); transition: border-color 0.15s; }
+.section-card:hover { border-color: var(--ui-accent); }
+.facet-summary { margin: 0; font-size: var(--ui-small); color: var(--ui-muted); }
+
+/* The hover card over a link to another page (useLinkPreview). */
+.link-preview-card { position: fixed; z-index: 50; width: 20rem; max-width: calc(100vw - 1rem); overflow: hidden; background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); box-shadow: var(--ui-shadow); }
+.link-preview-body { display: flex; flex-direction: column; gap: 0.25rem; padding: 0.75rem; }
+.link-preview-title { font-weight: 600; }
+.link-preview-excerpt { margin: 0; font-size: var(--ui-small); color: var(--ui-muted); display: -webkit-box; -webkit-line-clamp: 4; -webkit-box-orient: vertical; overflow: hidden; }
+
+/* The rail's frame and its table of contents. */
+.wiki-sidebar { --rail-border: 1px solid var(--ui-border); }
+.wiki-rail__group, .wiki-rail__toc-list { display: flex; flex-direction: column; gap: 1px; }
+.wiki-rail__label { padding: 0 0.5rem 0.25rem; font-size: var(--ui-small); font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; color: var(--ui-muted); }
+:is(.wiki-rail__toc-btn, .wiki-rail__toc-item) { display: flex; align-items: center; gap: 0.25rem; width: 100%; font: inherit; text-align: left; color: var(--ui-muted); background: none; border: 0; cursor: pointer; }
+.wiki-rail__toc-btn { padding: 0 0.5rem 0.25rem; }
+.wiki-rail__toc-item { padding: 0.25rem 0.75rem; font-size: var(--ui-small); line-height: 1.4; text-decoration: none; border-inline-start: 2px solid var(--ui-border); transition: color 0.15s, border-color 0.15s; }
+.wiki-rail__toc-item:hover, .wiki-rail__toc-item--active { color: var(--ui-accent); border-inline-start-color: var(--ui-accent); }
+.wiki-rail__toc-item--active { font-weight: 600; }
+
+/* Work queues (MaintenanceQueues). */
+.maintenance-queue { display: flex; flex-direction: column; gap: 0.5rem; padding-top: 1.5rem; border-top: 1px solid var(--ui-border); }
+.maintenance-count { margin-left: 0.5rem; font-weight: 400; font-variant-numeric: tabular-nums; color: var(--ui-muted); }
+.maintenance-description, .maintenance-detail { color: var(--ui-muted); }
+.maintenance-detail { font-size: var(--ui-small); }
+.maintenance-list { display: grid; gap: 0.375rem; margin: 0; padding: 0; list-style: none; }
+.maintenance-item { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.25rem 0.5rem; }
+.maintenance-item > a { color: var(--ui-accent); }
+
+/* A revision's changes and its inline diff. */
+.revision-change-action { font-weight: 600; color: var(--ui-muted); }
+.revision-change[data-action='added'] .revision-change-action { color: var(--ui-up); }
+.revision-change[data-action='removed'] .revision-change-action { color: var(--ui-down); }
+.revision-diff { line-height: 1.6; color: var(--ui-muted); }
+.revision-diff del { color: var(--ui-down); }
+.revision-diff ins { color: var(--ui-up); text-decoration: none; background: color-mix(in srgb, var(--ui-up) 12%, transparent); border-radius: 2px; }
+
+/* Sortable headers: muted until hovered or sorted by. */
+.sort-header { color: var(--ui-muted); transition: color 0.15s; }
+.sort-header:hover,
+:is([aria-sort='ascending'], [aria-sort='descending']) > .sort-header { color: inherit; }
+
+/* Charts. */
+.chart { background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius); }
+.chart-canvas { font-size: 0.6875rem; color: var(--ui-accent); --chart-axis: var(--ui-muted); --chart-up: var(--ui-up); --chart-down: var(--ui-down); }
+.chart-status { font-size: var(--ui-small); color: var(--ui-muted); }
+.chart-controls :is(button, a) { font-size: 0.6875rem; border: 1px solid var(--ui-border); border-radius: var(--ui-radius); opacity: 1; }
+.chart-controls :is(button, a):hover { background: var(--ui-surface-2); }
+.chart-controls :is(button, a):is([aria-pressed='true'], [aria-current]) { color: var(--ui-on-accent); background: var(--ui-accent); border-color: var(--ui-accent); }

package/dist/blocks.d.ts

@@ -126,6 +126,8 @@ export interface InfoboxBlock<A> {
     type: 'infobox';
     blocks: A[];
 }
+/** A wiki's whole block union from its atomic one: the leaves and the two containers holding them. */
+export type BlockTree<A> = A | InfoboxBlock<A> | ColumnsBlock<A>;
 /** Where a list's pages come from: those in a section, the newest, or ones picked by hand. */
 export declare const LIST_SOURCES: readonly ["under", "newest", "chosen"];
 export type ListSource = (typeof LIST_SOURCES)[number];

package/dist/headers.d.ts

@@ -11,11 +11,23 @@ export interface HeaderEntry {
 export declare const DEFAULT_IFRAME_HOSTS: readonly string[];
 /** CSP directive names this builder writes, in the order it writes them. */
 export type CspDirective = 'default-src' | 'base-uri' | 'object-src' | 'frame-ancestors' | 'form-action' | 'script-src' | 'style-src' | 'font-src' | 'img-src' | 'media-src' | 'connect-src' | 'frame-src' | 'worker-src' | 'manifest-src';
+/** A `script-src` source admitting exactly this inline script body. */
+export declare const scriptHash: (body: string) => string;
 /**
  * The policy string: `BASE_CSP` with each directive in `directives` replacing
  * its default. An empty list drops the directive.
+ *
+ * A `nonce` swaps `script-src` for the strict form, `'self'`, the nonce and a
+ * hash of each of `inlineScripts`, with no `'unsafe-inline'`. The hashes admit
+ * a static boot script without the layout reading the nonce, which would make
+ * every route render per request; hashing here means a package bump that
+ * changes the script moves its hash too, where a hand-copied one went stale
+ * and blanked every nonce route. Without a nonce the baseline stands.
  */
-export declare function contentSecurityPolicy(directives?: Partial<Record<CspDirective, readonly string[]>>): string;
+export declare function contentSecurityPolicy(directives?: Partial<Record<CspDirective, readonly string[]>>, { nonce, inlineScripts }?: {
+    nonce?: string | null;
+    inlineScripts?: readonly string[];
+}): string;
 /**
  * The six headers every route sends, plus the policy when one is given.
  *

package/dist/headers.js

@@ -11,8 +11,10 @@
 // `youtube-nocookie.com` its sanitiser kept, so those embeds survived cleaning
 // and then rendered blank.
 //
-// Zero imports, so a config pays for nothing it does not use. `withWikiDefaults`
-// is here for the same reason: next.config.ts is its only caller.
+// One import, node:crypto for a script's hash, so a config pays for nothing
+// else. `withWikiDefaults` is here for the same reason: next.config.ts is its
+// only caller.
+import { createHash } from 'node:crypto';
 /**
  * The embed hosts the editor's iframe, YouTube, tweet and map nodes produce:
  * the sanitiser's default `iframeHosts` and the default `frame-src`, so an
@@ -50,12 +52,22 @@ export const BASE_CSP = {
     'connect-src': ["'self'"],
     'frame-src': frameSources(),
 };
+/** A `script-src` source admitting exactly this inline script body. */
+export const scriptHash = (body) => `'sha256-${createHash('sha256').update(body, 'utf8').digest('base64')}'`;
 /**
  * The policy string: `BASE_CSP` with each directive in `directives` replacing
  * its default. An empty list drops the directive.
+ *
+ * A `nonce` swaps `script-src` for the strict form, `'self'`, the nonce and a
+ * hash of each of `inlineScripts`, with no `'unsafe-inline'`. The hashes admit
+ * a static boot script without the layout reading the nonce, which would make
+ * every route render per request; hashing here means a package bump that
+ * changes the script moves its hash too, where a hand-copied one went stale
+ * and blanked every nonce route. Without a nonce the baseline stands.
  */
-export function contentSecurityPolicy(directives = {}) {
-    return Object.entries({ ...BASE_CSP, ...directives })
+export function contentSecurityPolicy(directives = {}, { nonce = null, inlineScripts = [] } = {}) {
+    const strict = nonce ? { 'script-src': ["'self'", `'nonce-${nonce}'`, ...inlineScripts.map(scriptHash)] } : {};
+    return Object.entries({ ...BASE_CSP, ...directives, ...strict })
         .filter(([, sources]) => sources?.length)
         .map(([name, sources]) => `${name} ${sources.join(' ')}`)
         .join('; ');

package/dist/knip.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    entry: string[];
+    project: string[];
+    ignore: string[];
+    ignoreDependencies: string[];
+    ignoreBinaries: string[];
+};
+export default _default;

package/dist/knip.js

@@ -0,0 +1,31 @@
+// knip.ts — the dead-code config every app here shares. An app's own knip.ts
+// spreads it and appends what only it has: `{ ...base, ignoreBinaries:
+// [...base.ignoreBinaries, 'ffmpeg'] }`. Each had kept a copy, and the copies
+// drifted on the one line that matters most: a glob that does not name
+// `.well-known` skips a dotted directory and every agent-surface route in it.
+const entry = [
+    // What the App Router loads by convention and nothing imports.
+    'src/app/**/page.tsx',
+    'src/app/**/layout.tsx',
+    'src/app/**/route.{ts,tsx}',
+    'src/app/**/{error,not-found,loading,global-error}.tsx',
+    'src/app/.well-known/**/route.ts',
+    'src/app/**/{sitemap,robots,manifest,opengraph-image,icon,apple-icon}.{ts,tsx}',
+    'src/proxy.ts',
+    // A module exporting for its test alone reads as dead without the test.
+    'src/**/*.test.ts',
+    // The routines run these from the command line, and they reach into `src`.
+    'scripts/**/*.{ts,mts,mjs}',
+    'studio/**/*.mjs',
+];
+export default {
+    entry,
+    project: ['src/**/*.{ts,tsx}', 'scripts/**/*.{ts,mts,mjs}', 'studio/**/*.mjs'],
+    ignore: ['src/generated/**'],
+    // The generated Prisma client imports the first; the second is reached through
+    // `@tailwindcss/postcss` and a stylesheet `@import`, neither an import edge.
+    ignoreDependencies: ['@prisma/client', 'tailwindcss'],
+    // The global CLI the scripts' cache invalidation shells out to, kept out of the
+    // dependencies because it put ~330 packages into every build.
+    ignoreBinaries: ['vercel'],
+};

package/dist/link-check.d.ts

@@ -76,3 +76,51 @@ export declare function collectBlockLinks<B extends {
 }>(blocks: readonly B[], containers?: (block: B) => B[][] | null): BlockLinks;
 /** `Promise.all` with a ceiling, preserving input order in the results. */
 export declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** A page as `auditLinks` reads it: where it lives, its blocks, its metadata. */
+export interface AuditPage {
+    path: string;
+    content: unknown;
+    metadata?: unknown;
+}
+export interface AuditOptions {
+    /** Every internal path that resolves: pages, category hubs, routes, assets. */
+    livePaths: ReadonlySet<string>;
+    /** Default `probeExternal`. A wiki with its own special cases wraps it. */
+    probe?: (url: string) => Promise<Probe>;
+    /**
+     * Whether an internal path is the wiki's to check. One it is not (an app
+     * route, say) is kept in `skipped` and never reported broken. Default all.
+     */
+    internal?: (path: string) => boolean;
+    /** Default 12. */
+    concurrency?: number;
+}
+export type Referenced<T> = T & {
+    pages: string[];
+};
+export interface LinkAudit {
+    externalChecked: number;
+    brokenExternal: Referenced<Probe>[];
+    brokenInternal: Referenced<{
+        url: string;
+    }>[];
+    /** Internal paths `internal` turned away, each with the pages citing it. */
+    skipped: Map<string, string[]>;
+    /** Every embed, unprobed: a status check on one proves little on its own. */
+    embeds: Map<string, {
+        kind: string;
+        pages: string[];
+    }>;
+}
+/**
+ * Every link on every page, probed once per URL: externals by `probe`,
+ * internals against `livePaths`. A page's own `/history` and `/edit` resolve
+ * with it, and a query is a view of the path it rides on. The two checkers had
+ * each written this walk, and each had one of those rules and not the other.
+ */
+export declare function auditLinks(pages: readonly AuditPage[], opts: AuditOptions): Promise<LinkAudit>;
+/** The human summary of an audit's broken links, under the scope it covered. */
+export declare function printLinkAudit(audit: Pick<LinkAudit, 'externalChecked' | 'brokenExternal' | 'brokenInternal'>, { scope, pagesScanned }: {
+    scope: string;
+    pagesScanned: number;
+}): void;

package/dist/link-check.js

@@ -1,9 +1,9 @@
 // link-check.ts — the dead-link probe wiki sweep scripts share.
 //
-// Node-only (fetch, AbortSignal, URL). No framework, no database: what a
-// checker does with the verdicts — which pages to walk, what counts as an
-// internal path, how to report — stays with the caller, because that is the
-// half that is genuinely per-wiki.
+// Node-only (fetch, AbortSignal, URL). No framework, no database: which pages
+// to walk, which paths are live and what else to report stay with the caller,
+// because that is the half that is genuinely per-wiki. The walk over them and
+// the summary of what broke are `auditLinks` and `printLinkAudit`.
 //
 // EVERY GUARD BELOW WAS PAID FOR BY A FALSE POSITIVE. npmjs.com 403s scripted
 // requests, an expired certificate is not a dead host, a YouTube /embed/ URL
@@ -321,3 +321,68 @@ export async function mapLimit(items, limit, fn) {
     await Promise.all(workers);
     return results;
 }
+// A metadata fact (a website, an X handle's URL) renders as a live link and
+// rots like a citation, but lives outside the blocks; a bare domain counts.
+const metadataUrl = (v) => {
+    const s = typeof v === 'string' ? v.trim() : '';
+    if (/^https?:\/\//i.test(s))
+        return s;
+    return /^www\./i.test(s) || /^[a-z0-9.-]+\.[a-z]{2,}(\/|$)/i.test(s) ? `https://${s}` : null;
+};
+/**
+ * Every link on every page, probed once per URL: externals by `probe`,
+ * internals against `livePaths`. A page's own `/history` and `/edit` resolve
+ * with it, and a query is a view of the path it rides on. The two checkers had
+ * each written this walk, and each had one of those rules and not the other.
+ */
+export async function auditLinks(pages, opts) {
+    const { livePaths, probe = probeExternal, internal = () => true, concurrency = 12 } = opts;
+    const external = new Map();
+    const internals = new Map();
+    const skipped = new Map();
+    const embeds = new Map();
+    const cite = (map, key, page) => {
+        const refs = map.get(key);
+        if (!refs)
+            map.set(key, [page]);
+        else if (!refs.includes(page))
+            refs.push(page);
+    };
+    for (const page of pages) {
+        const links = collectBlockLinks(Array.isArray(page.content) ? page.content : []);
+        const meta = page.metadata && typeof page.metadata === 'object' ? Object.values(page.metadata) : [];
+        for (const url of [...links.external, ...meta.map(metadataUrl).filter((u) => !!u)])
+            cite(external, url, page.path);
+        for (const path of links.internal)
+            cite(internal(path) ? internals : skipped, path, page.path);
+        for (const { kind, url } of links.embeds) {
+            const entry = embeds.get(url) ?? { kind, pages: [] };
+            if (!entry.pages.includes(page.path))
+                entry.pages.push(page.path);
+            embeds.set(url, entry);
+        }
+    }
+    const results = await mapLimit([...external.keys()], concurrency, url => probe(url));
+    const resolves = (url) => {
+        const path = url.split('?')[0];
+        return livePaths.has(path) || livePaths.has(path.replace(/\/(history|edit)$/, ''));
+    };
+    return {
+        externalChecked: external.size,
+        brokenExternal: results.filter(r => !r.ok).map(r => ({ ...r, pages: external.get(r.url) })),
+        brokenInternal: [...internals].filter(([url]) => !resolves(url)).map(([url, refs]) => ({ url, pages: refs })),
+        skipped,
+        embeds,
+    };
+}
+/** The human summary of an audit's broken links, under the scope it covered. */
+export function printLinkAudit(audit, { scope, pagesScanned }) {
+    console.log(`\nLink check — scope: ${scope}`);
+    console.log(`Pages scanned: ${pagesScanned} | external links checked: ${audit.externalChecked}`);
+    console.log(`\nBroken external (${audit.brokenExternal.length}):`);
+    for (const b of audit.brokenExternal)
+        console.log(`  [${b.status || b.code || b.error}] ${b.url}\n      ← ${b.pages.join(', ')}`);
+    console.log(`\nBroken internal (${audit.brokenInternal.length}):`);
+    for (const b of audit.brokenInternal)
+        console.log(`  ${b.url}\n      ← ${b.pages.join(', ')}`);
+}

package/dist/passkey.d.ts

@@ -14,6 +14,8 @@ export interface PasskeyGate {
     cookie: string;
     /** Whether a session cookie's value is a live session whose passkey is still saved. */
     signedIn(session: string | undefined): Promise<boolean>;
+    /** Whether a request carries a live session: `signedIn` over its cookie, for a write route. */
+    allows(request: Request): Promise<boolean>;
     /** A single-use invite token, good for `days`. The bin turns it into a link. */
     invite(days?: number): Promise<string>;
     /**

package/dist/passkey.js

@@ -54,18 +54,17 @@ export function createPasskeyGate({ sql, rpName, cookie = 'passkey_session', ses
         const value = await issue(sql, 'session', sessionDays * DAY, undefined, passkeyId);
         return setCookie(value, sessionDays * 86_400, secure);
     }
+    const sessionOf = (request) => request.headers.get('cookie')?.split(/;\s*/).find(c => c.startsWith(`${cookie}=`))?.slice(cookie.length + 1);
+    const signedIn = async (value) => !!value &&
+        (await sql(`SELECT 1 FROM "PasskeyToken" t JOIN "Passkey" p ON p.id = t."passkeyId"
+       WHERE t.hash = $1 AND t.kind = 'session' AND t."expiresAt" > now()`, await hash(value))).length > 0;
     return {
         cookie,
-        signedIn: async (value) => !!value &&
-            (await sql(`SELECT 1 FROM "PasskeyToken" t JOIN "Passkey" p ON p.id = t."passkeyId"
-         WHERE t.hash = $1 AND t.kind = 'session' AND t."expiresAt" > now()`, await hash(value))).length > 0,
+        signedIn,
+        allows: request => signedIn(sessionOf(request)),
         invite: (days = 1) => issue(sql, 'invite', days * DAY),
         async signOut(request) {
-            const value = request.headers
-                .get('cookie')
-                ?.split(/;\s*/)
-                .find(c => c.startsWith(`${cookie}=`))
-                ?.slice(cookie.length + 1);
+            const value = sessionOf(request);
             if (value)
                 await spend(sql, 'session', value);
             return setCookie('', 0, new URL(request.url).protocol === 'https:');

package/dist/revisions.js

@@ -33,8 +33,14 @@ export function extractBlocks(blocks, containers, basePath = 'root') {
     });
     return out;
 }
+/** A value with every object's keys in one order: jsonb hands a stored block's keys back in its own. */
+const canonical = (v) => Array.isArray(v)
+    ? v.map(canonical)
+    : v && typeof v === 'object'
+        ? Object.fromEntries(Object.keys(v).sort().map(k => [k, canonical(v[k])]))
+        : v;
 /**
- * Which scalar fields differ. Nested block arrays are skipped: they are walked
+ * Which scalar fields differ, whatever order their keys are in. Nested block arrays are skipped: they are walked
  * as their own entries, and comparing them here would report a container as
  * modified every time anything inside it moved.
  */
@@ -57,7 +63,7 @@ function diffAttributes(oldBlock, newBlock, containers) {
             continue;
         const from = oldBlock[key];
         const to = newBlock[key];
-        if (JSON.stringify(from) !== JSON.stringify(to))
+        if (JSON.stringify(canonical(from)) !== JSON.stringify(canonical(to)))
             diffs[key] = { from, to };
     }
     return Object.keys(diffs).length > 0 ? diffs : undefined;

package/dist/scripts.d.ts

@@ -0,0 +1,189 @@
+import type { BannerVariant } from './text.js';
+import { type ChangeType } from './versioning.js';
+import { type PageMetadata, type WikiPageRow } from './store.js';
+/** The slice of a `pg` client every helper here takes. Prisma fits it with `$queryRawUnsafe`. */
+export interface ScriptClient {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+}
+type Block = {
+    id: string;
+    type: string;
+};
+export declare const uid: () => string;
+export declare const content: (html: string) => {
+    id: string;
+    type: "content";
+    text: string;
+};
+/**
+ * A notice. Always pass `text`: the variant's standard message lives in the
+ * renderer, not the row, so a banner without it is invisible to search.
+ */
+export declare const banner: (variant: BannerVariant, text: string) => {
+    id: string;
+    type: "banner";
+    variant: BannerVariant;
+    text: string;
+};
+/** A facts panel leading an article: `table` is the inner `<table>` HTML. */
+export declare const infobox: (table: string) => {
+    id: string;
+    type: "infobox";
+    blocks: {
+        id: string;
+        type: "content";
+        text: string;
+    }[];
+};
+/**
+ * Throw on a link-grid link or reference list whose URL fields are mis-shaped.
+ *
+ * The app's validator rejects these, and scripts never reach it. The views drop
+ * an entry whose URL fails rather than rendering it inert, so a `{ label, url }`
+ * link (the shape is `{ label, href }`) shows as a heading with no pills and
+ * nothing reports it. A throw inside `withClient` is a rollback and a failed run.
+ */
+export declare function assertLinkShapes(blocks: unknown, where?: string): void;
+/**
+ * Mark everything cached under `tag` stale on the project `cwd` is linked to.
+ * A script's write reaches no route that would bust it, and pages hold a day.
+ */
+export declare function invalidate(tag: string, cwd?: string): void;
+/**
+ * Run `fn` on a connected client, then release it and its pool. A throw rolls
+ * back the open transaction and fails the process: every script writes to the
+ * live database, and a half-applied edit must never pass for a success. A run
+ * that wrote anything ends by invalidating `tag`.
+ */
+export declare function withClient<T>(fn: (client: ScriptClient) => Promise<T>, { tag, cwd }?: {
+    tag?: string;
+    cwd?: string;
+}): Promise<T | undefined>;
+/** The app's own store over a script's client, so a script writes what the editor writes. */
+export declare const storeFor: (client: ScriptClient, siteId?: string) => {
+    siteId: string;
+    hidden: string[];
+    isHidden: (tagPath: string) => boolean;
+    get: (tagPath: string, slug: string) => Promise<NonNullable<WikiPageRow<Block> & {
+        revisionCount: number;
+    }> | null>;
+    getById: (id: string) => Promise<NonNullable<WikiPageRow<Block> & {
+        revisionCount: number;
+    }> | null>;
+    list: (tagPath: string, { sort, limit, offset }?: {
+        sort?: import("./store.js").ListSort;
+        limit?: number;
+        offset?: number;
+    }) => Promise<import("./store.js").WikiPageListing[]>;
+    articles: (tagPath: string, { sort, limit, offset }?: {
+        sort?: import("./store.js").ListSort;
+        limit?: number;
+        offset?: number;
+    }) => Promise<WikiPageRow<Block>[]>;
+    subtree: (tagPath: string) => Promise<import("./store.js").WikiPageRef[]>;
+    recent: ({ tagPath, limit }?: {
+        tagPath?: string;
+        limit?: number;
+    }) => Promise<import("./store.js").WikiPageListing[]>;
+    byIds: (ids: readonly string[]) => Promise<import("./store.js").WikiPageListing[]>;
+    refs: () => Promise<Omit<WikiPageRow<unknown>, "content">[]>;
+    corpus: () => Promise<WikiPageRow<Block>[]>;
+    branch: ({ tagPath, sort, limit, offset, since }?: {
+        tagPath?: string;
+        sort?: import("./store.js").ListSort;
+        limit?: number;
+        offset?: number;
+        since?: Date;
+    }) => Promise<{
+        items: {
+            content: Block[];
+            title: string;
+            id: string;
+            metadata: PageMetadata;
+            tagPath: string;
+            slug: string;
+            siteId: string;
+            version: string;
+            authorId: string | null;
+            lastVerifiedAt: Date | null;
+            createdAt: Date;
+            updatedAt: Date;
+            snippet: string;
+        }[];
+        total: number;
+    }>;
+    counts: () => Promise<{
+        tagPath: string;
+        pages: number;
+    }[]>;
+    stats: () => Promise<{
+        pages: number;
+        updated: Date | null;
+    }>;
+    search: (query: string, { tagPath, skip, take, content: withContent }?: {
+        tagPath?: string | null;
+        skip?: number;
+        take?: number;
+        content?: boolean;
+    }) => Promise<{
+        items: (Omit<WikiPageRow<unknown>, "content"> & {
+            snippet: string;
+        } & {
+            score: number;
+            content?: Block[] | undefined;
+        })[];
+        total: number;
+    }>;
+    history: (pageId: string, { limit, offset }?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<import("./store.js").WikiRevisionEntry[]>;
+    revision: (pageId: string, revisionId: string) => Promise<import("./store.js").WikiRevisionRow<Block> | null>;
+    save: (input: import("./store.js").SaveInput<Block>) => Promise<import("./store.js").SaveResult<Block>>;
+    restore: (tagPath: string, slug: string, revisionId: string, by?: {
+        authorId?: string | null;
+    }) => Promise<import("./store.js").SaveResult<Block>>;
+    remove: (tagPath: string, slug: string) => Promise<boolean>;
+    verify: (tagPath: string, slug: string) => Promise<boolean>;
+};
+/** A page row by path, every column: what `writeRevision` takes. Null when there is none. */
+export declare const readPage: (client: ScriptClient, tagPath: string, slug: string, siteId?: string) => Promise<NonNullable<WikiPageRow<Block> & {
+    revisionCount: number;
+}> | null>;
+export interface RevisionOptions {
+    /** The bump, and the revision's change type. Default minor. */
+    change?: Exclude<ChangeType, 'none'>;
+    message?: string;
+    /** Stamp `lastVerifiedAt`: the edit re-checked the page's facts. */
+    verified?: boolean;
+    /** Write nothing; return the version it would have been. */
+    dry?: boolean;
+    metadata?: PageMetadata;
+    authorId?: string | null;
+}
+/**
+ * Write edited blocks back to a page row from `readPage` as one revision. The
+ * save names the version it read, so an edit landing in between is refused
+ * (409) rather than overwritten. Returns the new version.
+ */
+export declare function writeRevision(client: ScriptClient, page: Pick<WikiPageRow, 'tagPath' | 'slug' | 'title' | 'version' | 'siteId'>, blocks: Block[], { change, message, verified, dry, metadata, authorId }?: RevisionOptions): Promise<string>;
+/**
+ * Create a page or update it in place, keyed by site, tag path and slug. A
+ * change to its title or blocks writes a revision; a re-run that changes
+ * nothing writes none. `change` records that bump instead of the diff's, and
+ * always writes one.
+ */
+export declare function upsertWikiPage(client: ScriptClient, input: {
+    tagPath: string;
+    slug: string;
+    title: string;
+    content: Block[];
+    metadata?: PageMetadata;
+    message?: string;
+    change?: Exclude<ChangeType, 'none'>;
+    authorId?: string | null;
+    siteId?: string;
+}): Promise<'created' | 'updated'>;
+export {};

package/dist/scripts.js

@@ -0,0 +1,138 @@
+// scripts.ts — what a wiki's direct-database scripts share: the client, the
+// store over it, the block builders, the shape check and the revision write.
+//
+// Node-only. A script bypasses the app's write routes, so it bypasses their
+// validation and their cache busting too; both are here so no script can skip
+// them. radix-wiki's seed-utils.mjs and caper's wiki-utils.ts had each written
+// this half, and each had a piece the other lacked: the shape check, the
+// write-tracking pool and the rollback on one side, the upsert that records a
+// revision only when something changed on the other.
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { bump } from './versioning.js';
+import { wikiStore } from './store.js';
+import { validateLinkGroups, validateReferenceItems } from './validation.js';
+// ---- block builders ---------------------------------------------------------
+export const uid = () => randomUUID();
+export const content = (html) => ({ id: uid(), type: 'content', text: html });
+/**
+ * A notice. Always pass `text`: the variant's standard message lives in the
+ * renderer, not the row, so a banner without it is invisible to search.
+ */
+export const banner = (variant, text) => ({ id: uid(), type: 'banner', variant, text });
+/** A facts panel leading an article: `table` is the inner `<table>` HTML. */
+export const infobox = (table) => ({ id: uid(), type: 'infobox', blocks: [content(table)] });
+// ---- the shape check --------------------------------------------------------
+/**
+ * Throw on a link-grid link or reference list whose URL fields are mis-shaped.
+ *
+ * The app's validator rejects these, and scripts never reach it. The views drop
+ * an entry whose URL fails rather than rendering it inert, so a `{ label, url }`
+ * link (the shape is `{ label, href }`) shows as a heading with no pills and
+ * nothing reports it. A throw inside `withClient` is a rollback and a failed run.
+ */
+export function assertLinkShapes(blocks, where = 'content') {
+    const bad = [];
+    const leaf = (b, path) => {
+        if (!b || typeof b !== 'object')
+            return;
+        if (b.type === 'linkGrid')
+            for (const [gi, g] of (b.groups ?? []).entries())
+                for (const [li, l] of (g?.links ?? []).entries())
+                    if (!validateLinkGroups([{ id: '', heading: '', links: [l] }]))
+                        bad.push(`${path}.groups[${gi}].links[${li}] "${l?.label ?? '(no label)'}" has fields {${Object.keys(l ?? {}).sort().join(', ')}} -- LinkGridLink is { label, href }`);
+        if (b.type === 'references' && !validateReferenceItems(b.items))
+            bad.push(`${path}.items -- ReferenceItem is { id, text, url? }`);
+    };
+    (Array.isArray(blocks) ? blocks : []).forEach((b, i) => {
+        leaf(b, `[${i}]`);
+        if (b?.type === 'infobox')
+            (b.blocks ?? []).forEach((n, j) => leaf(n, `[${i}].blocks[${j}]`));
+        if (b?.type === 'columns')
+            (b.columns ?? []).forEach((c, ci) => (c?.blocks ?? []).forEach((n, j) => leaf(n, `[${i}].columns[${ci}].blocks[${j}]`)));
+    });
+    if (bad.length)
+        throw new Error(`${where}: ${bad.length} mis-shaped link(s)\n  ${bad.join('\n  ')}`);
+}
+// ---- the client and the cache -----------------------------------------------
+/**
+ * Mark everything cached under `tag` stale on the project `cwd` is linked to.
+ * A script's write reaches no route that would bust it, and pages hold a day.
+ */
+export function invalidate(tag, cwd = process.cwd()) {
+    try {
+        execFileSync('vercel', ['cache', 'invalidate', '--tag', tag, '--yes'], { cwd, stdio: 'ignore' });
+        console.log(`cache: ${tag} tag invalidated`);
+    }
+    catch (e) {
+        console.warn(`cache: ${tag} tag NOT invalidated (${e.message}); run \`vercel cache invalidate --tag ${tag}\` from ${cwd}`);
+    }
+}
+/**
+ * Run `fn` on a connected client, then release it and its pool. A throw rolls
+ * back the open transaction and fails the process: every script writes to the
+ * live database, and a half-applied edit must never pass for a success. A run
+ * that wrote anything ends by invalidating `tag`.
+ */
+export async function withClient(fn, { tag = 'wiki', cwd = process.cwd() } = {}) {
+    const { default: pg } = await import('pg');
+    const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 1, ssl: { rejectUnauthorized: false } });
+    const conn = await pool.connect();
+    let wrote = false;
+    const client = {
+        query: (text, values) => {
+            // Anywhere in the text: the store's writes are data-modifying CTEs.
+            if (/\b(insert\s+into|update\s+\S+\s+set|delete\s+from)\b/i.test(text))
+                wrote = true;
+            return conn.query(text, values);
+        },
+    };
+    try {
+        return await fn(client);
+    }
+    catch (e) {
+        await conn.query('ROLLBACK').catch(() => { });
+        console.error('ERROR:', e.message);
+        process.exitCode = 1;
+        return undefined;
+    }
+    finally {
+        conn.release();
+        await pool.end();
+        // A run that throws part-way may have committed earlier writes.
+        if (wrote)
+            invalidate(tag, cwd);
+    }
+}
+// ---- reads and writes through the app's store ---------------------------------
+/** The app's own store over a script's client, so a script writes what the editor writes. */
+export const storeFor = (client, siteId = '') => wikiStore({ sql: async (q, ...v) => (await client.query(q, v)).rows, siteId });
+/** A page row by path, every column: what `writeRevision` takes. Null when there is none. */
+export const readPage = (client, tagPath, slug, siteId = '') => storeFor(client, siteId).get(tagPath, slug);
+/**
+ * Write edited blocks back to a page row from `readPage` as one revision. The
+ * save names the version it read, so an edit landing in between is refused
+ * (409) rather than overwritten. Returns the new version.
+ */
+export async function writeRevision(client, page, blocks, { change = 'minor', message, verified = false, dry = false, metadata, authorId = null } = {}) {
+    if (dry)
+        return bump(page.version, change);
+    assertLinkShapes(blocks, page.title);
+    const { page: saved } = await storeFor(client, page.siteId).save({
+        tagPath: page.tagPath, slug: page.slug, content: blocks, metadata,
+        change, message, verified, authorId, baseVersion: page.version,
+    });
+    return saved.version;
+}
+/**
+ * Create a page or update it in place, keyed by site, tag path and slug. A
+ * change to its title or blocks writes a revision; a re-run that changes
+ * nothing writes none. `change` records that bump instead of the diff's, and
+ * always writes one.
+ */
+export async function upsertWikiPage(client, input) {
+    const { siteId = '', ...save } = input;
+    assertLinkShapes(save.content, `${save.tagPath}/${save.slug}`);
+    const { created } = await storeFor(client, siteId).save(save);
+    return created ? 'created' : 'updated';
+}

package/dist/validation.d.ts

@@ -1,5 +1,6 @@
+import { type BlockTreeShape } from './blocks.js';
 /**
- * An href acceptable to persist: http, https, mailto, or a relative path or
+ * An href acceptable to persist: http, https, mailto, tel, or a relative path or
  * fragment. Everything else — `javascript:`, `data:`, `vbscript:`, a
  * protocol-relative `//host` — comes back null.
  *
@@ -86,3 +87,45 @@ export declare function duplicateBlockIds<B extends {
     type: string;
     id: string;
 }>(block: B, newId?: () => string): B;
+type Checked = Record<string, unknown>;
+export interface BlockModelOptions<B extends {
+    id: string;
+    type: string;
+}> {
+    /** What inserting each type makes. Its keys are the types this wiki knows. */
+    defaults: Record<B['type'], () => Omit<B, 'id'>>;
+    /**
+     * The leaf check for each native type, and for a core type the wiki narrows.
+     * `core` is the core check, for a narrowing that adds to it rather than
+     * replacing it. A type with no entry gets the core check.
+     */
+    checks?: Partial<Record<B['type'], (block: Checked, core: (block: Checked) => boolean) => boolean>>;
+    /** As `coreAtomicValidator`'s. */
+    pageId?: (id: string) => boolean;
+    maxRows?: number;
+}
+export interface BlockModel<B extends {
+    id: string;
+    type: string;
+}> {
+    /** Every type, in the order `defaults` lists them. */
+    types: B['type'][];
+    /** Every type but the two containers: what may nest inside one. */
+    atomicTypes: B['type'][];
+    shape: BlockTreeShape<B>;
+    createBlock: (type: B['type']) => B;
+    duplicateBlock: (block: B) => B;
+    validateBlocks: (content: unknown) => content is B[];
+    blockIssues: (content: unknown) => BlockIssue[];
+}
+/**
+ * A wiki's block model from its type set: the new-block factories and the leaf
+ * checks are its own, and everything derived from them is this. Each wiki had
+ * derived the same seven things by hand, and two kept a list of nestable types
+ * that drifted from the types the write path accepted.
+ */
+export declare function defineBlocks<B extends {
+    id: string;
+    type: string;
+}>(opts: BlockModelOptions<B>): BlockModel<B>;
+export {};

package/dist/validation.js

@@ -8,9 +8,9 @@
 //
 // As elsewhere in this package, the dispatch stays with the caller so a new
 // block type is a compile error there until it is handled.
-import { LIST_SOURCES } from './blocks.js';
+import { coreBlockShape, LIST_SOURCES } from './blocks.js';
 /**
- * An href acceptable to persist: http, https, mailto, or a relative path or
+ * An href acceptable to persist: http, https, mailto, tel, or a relative path or
  * fragment. Everything else — `javascript:`, `data:`, `vbscript:`, a
  * protocol-relative `//host` — comes back null.
  *
@@ -36,7 +36,7 @@ export function safeLinkHref(raw) {
     const scheme = href.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
     if (scheme) {
         const s = scheme[1].toLowerCase();
-        if (s !== 'http' && s !== 'https' && s !== 'mailto')
+        if (s !== 'http' && s !== 'https' && s !== 'mailto' && s !== 'tel')
             return null;
     }
     return href;
@@ -241,3 +241,30 @@ export function duplicateBlockIds(block, newId = () => crypto.randomUUID()) {
     }
     return { ...block, id: newId() };
 }
+/**
+ * A wiki's block model from its type set: the new-block factories and the leaf
+ * checks are its own, and everything derived from them is this. Each wiki had
+ * derived the same seven things by hand, and two kept a list of nestable types
+ * that drifted from the types the write path accepted.
+ */
+export function defineBlocks(opts) {
+    const { defaults, checks = {}, pageId, maxRows } = opts;
+    const types = Object.keys(defaults);
+    const atomicTypes = types.filter(t => t !== 'columns' && t !== 'infobox');
+    const core = coreAtomicValidator({ pageId, maxRows });
+    const own = checks;
+    const { validateBlocks, blockIssues } = createBlockValidator({
+        isKnownType: t => Object.hasOwn(defaults, t),
+        isAtomicType: t => atomicTypes.includes(t),
+        validateAtomic: b => (own[b.type] ?? core)(b, core),
+    });
+    return {
+        types,
+        atomicTypes,
+        shape: coreBlockShape(),
+        createBlock: type => ({ id: crypto.randomUUID(), ...defaults[type]() }),
+        duplicateBlock: block => duplicateBlockIds(block),
+        validateBlocks: (content) => validateBlocks(content),
+        blockIssues,
+    };
+}

package/dist/well-known.d.ts

@@ -149,3 +149,30 @@ export declare function descriptorHandler(body: unknown, opts?: {
 }): (request: Request) => Response;
 /** The whole `<mcp-url>/server-card` route, projected from server.json. */
 export declare const serverCardHandler: (manifest: ServerManifest) => ((request: Request) => Response);
+export interface WellKnownDocs {
+    agentCard: unknown;
+    mcpManifest: unknown;
+    openapi: unknown;
+    /**
+     * The registry's key material, read from the environment by default. `null`
+     * serves no proof: a tenant of a host whose namespace is the host's own.
+     */
+    registryAuth?: {
+        publicKey?: string;
+        keyType?: string;
+    } | null;
+}
+/**
+ * The `/.well-known/[doc]` route: the agent card at `agent.json` and
+ * `agent-card.json` (A2A v0.3 renamed it; older clients ask for the first), the
+ * MCP manifest at `mcp.json`, the OpenAPI spec at `openapi.json` and the
+ * registry's domain proof at `mcp-registry-auth`. Every other name is a 404.
+ *
+ * Each app served these as five or six one-line routes re-exporting each other;
+ * one dynamic segment holds them all, and a rewrite puts `/openapi.json` on it.
+ */
+export declare function wellKnownHandler(docs: WellKnownDocs): (request: Request, context: {
+    params: Promise<{
+        doc: string;
+    }>;
+}) => Promise<Response>;

package/dist/well-known.js

@@ -1,5 +1,6 @@
 // well-known.ts — the descriptors an agent finds before it knows anything else
-// about an origin: the A2A Agent Card and the MCP registry's domain proof.
+// about an origin: the A2A Agent Card, the MCP manifest and the registry's
+// domain proof, and the one route that serves them.
 //
 // All three apps here serve both, and all three had written them out. The
 // registry-auth handler was identical bar a domain named in a comment; the
@@ -218,3 +219,28 @@ export function descriptorHandler(body, opts = {}) {
 }
 /** The whole `<mcp-url>/server-card` route, projected from server.json. */
 export const serverCardHandler = (manifest) => descriptorHandler(serverCard(manifest, MCP_PROTOCOL_VERSIONS));
+/**
+ * The `/.well-known/[doc]` route: the agent card at `agent.json` and
+ * `agent-card.json` (A2A v0.3 renamed it; older clients ask for the first), the
+ * MCP manifest at `mcp.json`, the OpenAPI spec at `openapi.json` and the
+ * registry's domain proof at `mcp-registry-auth`. Every other name is a 404.
+ *
+ * Each app served these as five or six one-line routes re-exporting each other;
+ * one dynamic segment holds them all, and a rewrite puts `/openapi.json` on it.
+ */
+export function wellKnownHandler(docs) {
+    const { registryAuth = {} } = docs;
+    const bodies = {
+        'agent.json': docs.agentCard,
+        'agent-card.json': docs.agentCard,
+        'mcp.json': docs.mcpManifest,
+        'openapi.json': docs.openapi,
+    };
+    return async (request, { params }) => {
+        const { doc } = await params;
+        if (doc === 'mcp-registry-auth' && registryAuth) {
+            return registryAuthHandler(registryAuth.publicKey ?? process.env.MCP_REGISTRY_PUBLIC_KEY, registryAuth.keyType ?? process.env.MCP_REGISTRY_KEY_TYPE)();
+        }
+        return Object.hasOwn(bodies, doc) ? descriptorResponse(request, bodies[doc]) : new Response('Not found', { status: 404 });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.85.0",
+  "version": "0.86.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",
@@ -283,6 +283,16 @@
       "import": "./dist/headers.js",
       "default": "./dist/headers.js"
     },
+    "./scripts": {
+      "types": "./dist/scripts.d.ts",
+      "import": "./dist/scripts.js",
+      "default": "./dist/scripts.js"
+    },
+    "./knip": {
+      "types": "./dist/knip.d.ts",
+      "import": "./dist/knip.js",
+      "default": "./dist/knip.js"
+    },
     "./tsconfig.base.json": "./tsconfig.base.json"
   },
   "bin": {
@@ -327,6 +337,7 @@
     "@tiptap/react": "^2.27.3",
     "@tiptap/starter-kit": "^2.27.3",
     "fast-diff": "^1.3.0",
+    "katex": "^0.16.47",
     "lightweight-charts": "^5.2.1",
     "sanitize-html": "^2.17.7"
   },
@@ -335,12 +346,13 @@
     "@radixdlt/rola": "^2.1.0",
     "@types/katex": "^0.16.8",
     "@types/node": "^22.0.0",
+    "@types/pg": "^8.23.1",
     "@types/react": "^19.0.0",
     "@types/sanitize-html": "^2.16.1",
     "@vercel/blob": "^2.8.2",
     "jose": "^6.2.12",
     "jsdom": "^30.1.0",
-    "katex": "^0.16.47",
+    "pg": "^8.23.1",
     "react": "^19.2.4",
     "sharp": "^0.35.5",
     "typescript": "^5.9.0"
@@ -351,8 +363,7 @@
     "jose": ">=6",
     "pg": ">=8",
     "react": ">=18",
-    "sharp": ">=0.33",
-    "katex": "^0.16.0"
+    "sharp": ">=0.33"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -372,9 +383,6 @@
     },
     "@vercel/blob": {
       "optional": true
-    },
-    "katex": {
-      "optional": true
     }
   }
 }