wiki-formant 0.48.0 → 0.49.0

package/README.md

@@ -219,6 +219,8 @@ 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.
+
 `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
@@ -261,9 +263,9 @@ const nextConfig = {
 
 Four configs had restated these by hand on the grounds that a config could not import an ESM-only package. It could not because no subpath had a `default` condition, and Next resolves a config's imports the way `require` does; every subpath has one now, and Node 24 loads the module there unchanged.
 
-`contentSecurityPolicy` starts from `BASE_CSP`, 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.
 
-The default `frame-src` is `frameSources(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 both.
+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`.
 
 ## Pagination and versioning
 
@@ -394,9 +396,9 @@ and a crawler obeys only its most-specific matching group, so an agent with no
 group of its own falls through to `*`. Three wikis were measuring five crawlers
 they had never addressed.
 
-Every agent group also allows `AGENT_SURFACE_PATHS` — `/api/mcp`, the three `llms` exports, `/openapi.json`, `/.well-known/` — without being told. `aiAllow` is what an origin serves beyond that.
+Every agent group also allows the agent surface — `/api/mcp`, the three `llms` exports, `/openapi.json`, `/.well-known/` — without being told. `aiAllow` is what an origin serves beyond that.
 
-`crawlerRules` returns every group robots.txt needs: the wildcard, one per AI crawler, and one each for `SEARCH_ENGINES`. Search engines get the HTML site and none of its twins — `/*.md$` always, plus `searchDisallow` — because the `*` group keeps the machine surface open to agents, and for Google a twin is a page it already has. Two origins wrote that group by hand and the third never did, so Google crawled its twins. `RSC_DISALLOW`, the `<Link>` prefetch payload, is refused in every group.
+`crawlerRules` returns every group robots.txt needs: the wildcard, one per AI crawler, and one for each search engine. Search engines get the HTML site and none of its twins — `/*.md$` always, plus `searchDisallow` — because the `*` group keeps the machine surface open to agents, and for Google a twin is a page it already has. Two origins wrote that group by hand and the third never did, so Google crawled its twins. The `<Link>` prefetch payload (`?_rsc=`) is refused in every group.
 
 `trackAiBot(request, event, load)` counts an `AI Bot Visit` inside `event.waitUntil`. `load` is a dynamic import because the tracker pulls in a database client, which a static import would load for every request the proxy sees.
 
@@ -438,6 +440,12 @@ const faq = faqPageLd(questionPairs(html), url);
 {faq && <JsonLd data={faq} />}
 ```
 
+`describe(text)` is a page's meta description from any prose, HTML, markdown or plain: tags, entities, link targets and bare URLs go, and the rest fits `DESCRIPTION_LIMIT` (160) as whole sentences where they fill half of it, else cut at a word with an ellipsis. Four sites had four rules, one cutting mid-word at 150 and one slicing at 160 with no mark. `openingText(blocks)` (`wiki-formant/text`) is what a page without an excerpt is described by: its first top-level `content` block with prose once the headings are out, since a page that opens with an infobox would otherwise be described by its metadata table.
+
+```ts
+const description = describe(page.metadata?.excerpt || openingText(page.content));
+```
+
 `sitePageMetadata({ siteName, handle })` binds the three fields Next drops from every page that sets its own card, with `locale` defaulting to `en_US`. `siteGraphLd` is the Organization, WebSite (with its `SearchAction`) and `WebAPI` as one `@graph` for the root layout, every node carrying an `@id`, and `siteRefs(url)` hands out the same ids for a page's `publisher` and `isPartOf` — so no page writes an inline copy of the publisher that can disagree with the layout's.
 
 ```ts
@@ -506,7 +514,7 @@ each change on `data-action`; `base.css` only resets the list.
 
 Three repos, four feeds, 47 of 64 significant lines identical — including,
 verbatim in two of them, the comment explaining why the apostrophe escapes
-numerically. `renderFeed` is the union.
+numerically. `feedResponse` is the union.
 
 ```ts
 export const GET = async (request: Request) => feedResponse(request, channel, await items());
@@ -554,11 +562,11 @@ In React, `useArticlePasses(ref, [blocks])` runs the three passes and `useTweetE
 
 `scrollTables(html)` is the one table pass that runs on the string, before render: it wraps each stored table in a `.table-scroll` box, and `base.css` lets that box scroll sideways. A table box ignores `overflow`, so a table with an address or a URL in a cell is as wide as that token whatever its column, and a scroll box added by an effect would arrive after the table had already been laid out too wide. Call it on the render path beside `injectHeadingIds`. A table already in a box keeps it, so it is safe on HTML that has been through it once.
 
-`TWITTER_ORIGIN` is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed.
+The embed's origin is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed.
 
 ## Search
 
-`proseSql`, `searchTsvSql`, `HEADLINE_OPTIONS` and `FTS_RANK_NORMALIZATION` are what a literal tier and a full-text tier must agree on. `searchTsvDdl(table)` is the statements that build the generated `search_tsv` column and its index — dropped and re-added in one transaction every run, because a skip-if-present script is blind to a changed expression.
+`proseSql`, `HEADLINE_OPTIONS` and `FTS_RANK_NORMALIZATION` are what a literal tier and a full-text tier must agree on. `searchTsvDdl(table)` is the statements that build the generated `search_tsv` column and its index — dropped and re-added in one transaction every run, because a skip-if-present script is blind to a changed expression.
 
 ## Block trees
 
@@ -574,7 +582,7 @@ leafBlocks(blocks, BLOCK_SHAPE.containers);
 
 `computeRevisionDiff` defaults to the same shape, path-addressed, so a repo whose containers are the core two passes none.
 
-The dispatch over a repo's own block union stays in that repo; the bodies come from here. `wiki-formant/text` has a prose body for every core leaf — `statsToText`, `linkGridToText` and `pageListToText` joined the originals when two of the three wikis turned out to extract nothing from them, so their MCP `get_page` answered a hub page as nearly empty.
+The dispatch over a repo's own block union stays in that repo; the bodies come from here. `coreAtomicText` has a prose body for every core leaf — the stats, link-grid and page-list bodies joined the originals when two of the three wikis turned out to extract nothing from them, so their MCP `get_page` answered a hub page as nearly empty.
 
 The core leaves — `content`, `codeTabs`, `banner`, `references`, `stats`, `linkGrid`, `recentPages`, `pageList` — had the same case bodies in every wiki's text export, markdown twin, validator and new-block record. A repo's switch hands those cases over and keeps its own, so it stays exhaustive over its union:
 
@@ -620,7 +628,7 @@ A `codeTabs` tab's `code` is source text in every wiki here, and every view trea
 ```ts
 import { createHtmlSanitizer, sanitizeCoreLeaf } from 'wiki-formant/sanitize';
 
-const clean = createHtmlSanitizer({ iframeHosts: FRAME_HOSTS });   // and frameSources(FRAME_HOSTS) in the CSP
+const clean = createHtmlSanitizer({ iframeHosts: FRAME_HOSTS });   // and the same hosts in the CSP's frame-src
 const safe = mapBlockTree(blocks, b => sanitizeCoreLeaf(b, clean), BLOCK_SHAPE);
 ```
 
@@ -628,27 +636,41 @@ The default list is derived from what the editor nodes in `wiki-formant/tiptap`
 
 Classes pass by name only. Limiting `style` to layout and paint is worth nothing while `class` is free, because every site's own stylesheet ships `fixed inset-0 z-50`, and those draw a fake prompt over the chrome as well as `position` does.
 
+## Image uploads
+
+`wiki-formant/upload` is the route an editor's image upload posts to. Two wikis had written it and their limits had drifted: one took 25 MB with no cap on decoded pixels and trusted the Content-Type the client sent, the other 4 MB, 40 megapixels and the file's own leading bytes. These are the second one's defaults.
+
+```ts
+// src/app/api/upload/route.ts
+export const runtime = 'nodejs';
+export const POST = uploadHandler({
+  authorize: async () => (await currentUser())?.id ?? errors.unauthorized('Sign in to upload.'),
+  prefix: 'wiki/',
+});
+```
+
+The bytes say what the file is, never the name or type, and SVG is refused. Every image is re-encoded, upright, so nothing from the source's metadata is kept, a phone's GPS position included; the bytes as sent are never stored. `encode` is the re-encode, the sniffed format by default; a wiki with an image standard resizes and converts there. Each uploader has a budget, keyed on `authorize`'s id and address. `maxBytes`, `maxPixels` and `rateLimit` take other limits, and `store` replaces Vercel Blob. `sharp` and `@vercel/blob` are optional peers.
+
 ## Editor nodes
 
 `wiki-formant/tiptap` carries the custom nodes both wiki editors had written twice: `Iframe`, `YouTube` (the stock extension plus the paste rule it does not ship with), `TwitterEmbed`, `createMapEmbed`, `createCodeBlock` and `createTabs`. The four `@tiptap/*` packages are optional peers, so a consumer taking only the taxonomy still installs a package with no runtime dependencies.
 
 ```ts
 const CodeBlock = createCodeBlock({
-  langs: CODE_LANGS, defaultLang: DEFAULT_LANG,
   classNames: { button: 'lang-btn', option: 'lang-option', optionActive: 'text-accent' },
   icons: { chevron: open => <ChevronDown className={open ? 'rotate-180' : ''} /> },
 });
 ```
 
-The ones that take config take it because that is exactly where the two copies differed — class tokens, the language list, and the API route a shortened map URL has to be resolved through. Injecting them is what lets one wiki keep `text-jupiter` and the other `text-accent` without either forking the node, and it keeps this file from dragging an icon library in behind it.
+The language list defaults to `CODE_LANGS` and `DEFAULT_LANG` from `wiki-formant/blocks`, which two wikis had typed identically; a wiki with its own passes `langs` and `defaultLang`. The ones that take config take it because that is exactly where the two copies differed — class tokens, the language list, and the API route a shortened map URL has to be resolved through. Injecting them is what lets one wiki keep `text-jupiter` and the other `text-accent` without either forking the node, and it keeps this file from dragging an icon library in behind it.
 
 `createTabs` returns `TabGroup` and `TabItem` together: `tabGroup`'s content expression is `tabItem+`, so registering one without the other leaves a node type the schema cannot satisfy. A pasted short map link inserts immediately with `about:blank` and swaps its `src` when the redirect resolves — pasting must not block on a network hop, and the node has to exist for the reader to see anything happen.
 
 `createHeadingIds({ slug })` decorates each heading in the editor with the id its published copy will carry, through `uniqueHeadingId` — the dedupe `injectHeadingIds` uses — so a rail listing headings mid-edit links to the anchors readers will get. `uploadImageTo('/api/upload')` is the `uploadImage` two editors had written identically.
 
-`TOOLBAR_ACTIONS` are the formatting commands with the labels a screen reader announces — two toolbars titled buttons with the internal key, so one said "codeBlock". Pick yours in order with `toolbarActions([...])`, render each through `ToolbarButton` (named, and `aria-pressed`, since these are toggles), and run a table command with `runTableAction`. Upload and embed stay with the caller; they are the parts that differ.
+`toolbarActions([...])` picks the formatting commands, in order, with the labels a screen reader announces — two toolbars titled buttons with the internal key, so one said "codeBlock". Render each through `ToolbarButton` (named, and `aria-pressed`, since these are toggles), and run a table command with `runTableAction`. Upload and embed stay with the caller; they are the parts that differ.
 
-`useUrlPrompt(editor, { resolveMapUrl })` is the link and embed address field under a toolbar, in place of a `window.prompt` that blocks the page and cannot show the link the cursor is in. Three editors had written it and one still used the prompt; only one copy both opened a link field on the current address and unlinked on an emptied one. The hook carries both, closes the field when the editor it serves changes (a toolbar shared between blocks would otherwise apply it to the wrong one), and leaves the markup to you. `applyUrlPrompt` is what it runs, exported for a toolbar that keeps its own state.
+`useUrlPrompt(editor, { resolveMapUrl })` is the link and embed address field under a toolbar, in place of a `window.prompt` that blocks the page and cannot show the link the cursor is in. Three editors had written it and one still used the prompt; only one copy both opened a link field on the current address and unlinked on an emptied one. The hook carries both, closes the field when the editor it serves changes (a toolbar shared between blocks would otherwise apply it to the wrong one), and leaves the markup to you.
 
 ```tsx
 const url = useUrlPrompt(editor, { resolveMapUrl });
@@ -656,7 +678,7 @@ const url = useUrlPrompt(editor, { resolveMapUrl });
 {url.kind && <input autoFocus value={url.value} onChange={e => url.setValue(e.target.value)} onKeyDown={url.onKeyDown} />}
 ```
 
-A link is stored as its `href` and the `link` class, nothing else (`wikiLink`). Stock Tiptap writes `target="_blank" rel="noopener noreferrer nofollow"` onto every link, internal ones included, which on a site throws away its own link equity and opens in-site navigation in new tabs. Whether a link is external depends on the host serving the page, so `normaliseLinks` decides it at render time. A legacy link loses both attributes the next time its page is saved.
+A link is stored as its `href` and the `link` class, nothing else. Stock Tiptap writes `target="_blank" rel="noopener noreferrer nofollow"` onto every link, internal ones included, which on a site throws away its own link equity and opens in-site navigation in new tabs. Whether a link is external depends on the host serving the page, so `normaliseLinks` decides it at render time. A legacy link loses both attributes the next time its page is saved.
 
 The redirect resolves through the wiki's own route, because the editor cannot read it cross-origin. `resolveMapUrl` is the client half and `resolveMapHandler` the whole route: exact shortener hosts, one hop, an allowlisted landing host, a timeout, and your sign-in check as `authorize`. One of the two copies it replaced matched `goo.gl` as a substring and followed every redirect for anyone who asked.
 
@@ -672,8 +694,8 @@ address and browser under a salt that is replaced every UTC day, and the old
 salt is deleted, so a visitor is told apart within a day and never followed
 into the next. Rows are kept 400 days. The package owns the SQL and the app
 owns the connection: `Sql` is one function that runs a statement with `$1, $2…`
-placeholders, and the four tables it needs are stated as Prisma models at the
-top of `src/analytics.ts`. The fourth, `ViewDay`, holds days a site counted
+placeholders, and the four tables it needs ship as Prisma models in
+`prisma/analytics.prisma` (see `prisma-models` below). The fourth, `ViewDay`, holds days a site counted
 elsewhere before it counted its own; `digest` adds them to any window that
 reaches back that far, and a site with no such history leaves it empty.
 
@@ -707,14 +729,12 @@ any other browser event. Underneath the tracker, server code calls
 its zero-dependency guarantee:
 
 ```ts
-const props = searchQueryProps({ query, results: rows.length, surface: 'wiki' });
-// null for an empty field, so a blank search cannot fire an event
-if (props) after(() => recordEvent(sql, { name: 'Search Query', props, url, headers }));
+after(() => recordEvent(sql, { name: 'Signup', props: { plan }, url, headers }));
 ```
 
 `mcpCallProps` reads a tool name out of a JSON-RPC envelope that is untrusted
-and may be a batch; `searchQueryProps` normalises a search box's free text so
-the same question aggregates as one row. Pass the request's headers and the
+and may be a batch; `trackSearch` normalises a search box's free text so
+the same question aggregates as one row, and drops an empty one. Pass the request's headers and the
 event joins whoever sent it, person or agent.
 
 `digest(sql, { days })` reads a site back as one JSON object: visitors, page
@@ -735,8 +755,8 @@ its readers asked for. The queries that return zero rows are the valuable ones
 nothing else, no account, password or email. `createPasskeyGate({ sql, rpName })`
 returns the whole of it. `gate.route` is the sign-in route,
 `gate.signedIn(cookieValue)` is the check a page makes, `gate.open()` is true
-while no passkey is saved, and `gate.cookie` is the cookie's name. The two tables (`Passkey`, `PasskeyToken`) are stated as Prisma
-models at the top of `src/passkey.ts`, and every token is kept only as its hash.
+while no passkey is saved, 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.
 `@simplewebauthn/server` is an optional peer.
 
 There is no sign-up. While no passkey is saved, the page saves the first one
@@ -786,6 +806,22 @@ counted itself, says so, and drops the comparison with the window before. The ch
 axis from zero, so `lightweight-charts` is an optional peer that a stats page
 needs installed.
 
+## ROLA sign-in
+
+`wiki-formant/rola` is the part of a Radix wallet sign-in two sites had each written: a single-use challenge, the wallet's proof of it, and the HS256 token a verified address is handed. How a site keeps the session stays with it, because the two keep it differently: radix-wiki a `Session` row behind a seven-day cookie, caper a stateless token it slides forward, with a short one for agents.
+
+```ts
+const rola = createRola({ expectedOrigin, dAppDefinitionAddress, networkId, applicationName, challenges: prisma.challenge });
+const { challenge } = await rola.generateChallenge();
+const v = await rola.verifySignedChallenge(signed);        // { isValid, error? }
+
+const secret = sessionSecret(process.env.JWT_SECRET);      // throws under 32 characters
+const token = await signSession({ id: signed.address }, secret, 7 * 86400);
+const claims = await verifySession<{ id: string }>(bearerToken(request.headers) ?? cookie, secret);
+```
+
+Where the two copies differed, this takes the stricter. A challenge is spent by one conditional delete, so two requests racing with one signature cannot both pass, and it is spent whatever the outcome; making one purges the expired. Only an account proof signs in. Verification pins HS256. `jose` and `@radixdlt/rola` are optional peers.
+
 ## Charts
 
 `TimeChart` (`wiki-formant/chart`) is every time-series chart on the four sites:
@@ -819,11 +855,11 @@ straight between closes and a count's is curved.
 `aggregate` is how a week or month is made from its days: `last` for a price,
 `mean` for a count, so the week in progress keeps its level instead of reading
 as a collapse. A single range draws no range buttons and shows every point.
-`bucketChart` and `chartSteps` are exported for a chart drawn elsewhere.
+`chartSteps` is exported for a chart drawn elsewhere.
 
 `markers` are events, `{ time, label }`, each drawn as an arrow on the last
 point at or before it, so one mid-week lands on its week and two on one point
-share it (`placeMarkers` does the placing). `step` opens on a step where the
+share it. `step` opens on a step where the
 range can make it, and `onView` hears the range and step on mount and on every
 change, for a page that keeps them in its URL:
 
@@ -837,7 +873,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 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.
+`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.
 
 ```css
 @import "wiki-formant/base.css" layer(components);
@@ -852,7 +888,8 @@ and there is no root export: `import … from 'wiki-formant'` does not resolve.
 barrel loads every module it names for the one symbol a route wanted, and had
 already re-exported one module twice. The emitted `.d.ts` files are the reference.
 There is no hand-maintained symbol list here, because the one that used to be here
-drifted from them.
+drifted from them. A function a module uses only itself is marked `@internal`: the
+package's tests still reach it, and the `.d.ts` leaves it out.
 
 `wiki-formant/tsconfig.base.json` is the compiler floor: an app's `tsconfig.json` extends it and keeps only `paths`, `include`, `exclude` and any licensed extra, since tsconfig resolves those against the file that declares them.
 
@@ -870,6 +907,8 @@ long, across every bucket that names it, rather than letting the refill trickle
 one token through at a time. `clientIp` reads `x-real-ip` first — Vercel sets it
 and overwrites any inbound copy — and the leftmost `x-forwarded-for` only where no
 `x-real-ip` was set, since a proxy that appends hands the client that slot.
+`limitClient(prefix, headers, opts)` is the per-address gate, `rateLimit` over
+`clientKey`, which a dozen call sites had written out.
 
 ## A bin
 
@@ -895,12 +934,31 @@ npx analytics-digest --days 7 --gap "Symptom Miss:term"   # adds an event to the
 npx passkey-invite https://caper.network/stats
 ```
 
+`prisma-models` copies the models the analytics and passkey SQL reads, `prisma/analytics.prisma` and `prisma/passkey.prisma`, into an app's schema folder, and `--check` exits 1 when a copy is missing or has drifted. Prisma reads a schema split across one folder's files, so the app moves `prisma/schema.prisma` into `prisma/schema/`, points `prisma.config.ts`'s `schema` at the folder, and keeps its generator, datasource and own models there beside the shipped files. A generator `output` is relative to the file that declares it, so it gains a `../`.
+
+```sh
+npx prisma-models            # write both into prisma/schema
+npx prisma-models --check    # in the build, before prisma generate
+```
+
 `fts-ddl <table>` rebuilds a table's `search_tsv` generated column and its GIN index from the expression `wiki-formant/search` queries, over `DIRECT_URL` (else `DATABASE_URL` on 5432). Run it before declaring the column in `schema.prisma`; the bin's header says why.
 
 ```sh
 npx fts-ddl pages
 ```
 
+`mark-verified` stamps `last_verified_at` on pages a sweep checked and found current, so `freshnessBanner` stops calling them outdated, and `maintenance-log` is the state I/O of a wiki-sweep routine whose memory lives in one page's `metadata.state`: `read`, `write` (the whole state, or `-` for stdin), `compact` and `backlog-add`, which appends under a row lock so another routine's item cannot be lost to a concurrent `write`. Every write compacts and re-renders the page; a revision is written at most once a day. Two wikis carried both scripts against their own tables, so the tables are arguments. Run them from the app's root, like `passkey-invite`:
+
+```sh
+npx mark-verified contents/tech/radix-engine scrypto       # one page
+npx mark-verified --all ecosystem --invalidate wiki        # a tag path, then the cache tag
+npx maintenance-log read --at contents/tech/operations/wiki-maintenance-log --routine wiki-sweep --author <id>
+npx maintenance-log backlog-add '[{"item": "…"}]' --at operations/wiki-maintenance-log --routine caper-wiki-sweep \
+  --pages wiki_pages --revisions wiki_revisions --page-key wiki_page_id --scope caper_id
+```
+
+`--scope column` keeps to rows where the column is NULL (`=value` for one value), `--table`/`--pages`/`--revisions` default to `pages` and `revisions`, and `--invalidate <tag>` runs `vercel cache invalidate` after a write.
+
 ## A reusable workflow
 
 `.github/workflows/publish-mcp-registry.yml` republishes an origin's server to the MCP registry when the version in its `server.json` moves. Each app keeps its own trigger and calls it with its domain:

package/bin/maintenance-log.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// bin/maintenance-log.mjs – state I/O for a wiki-sweep routine's log page.
+//
+// The routine's memory between runs lives in one wiki page's metadata.state,
+// and the page shows it, re-rendered and capped on every write (the rules are
+// `src/maintenance.ts`). radix-wiki and caper each carried this script with the
+// same rules against a different table, so the tables are arguments. Run it
+// from the app's root, where `pg` is installed and `.env` holds DATABASE_URL.
+//
+//   npx maintenance-log read                    # print the state as JSON
+//   npx maintenance-log write '<json>'          # replace it (or `write -` from stdin)
+//   npx maintenance-log compact [--dry-run]     # re-apply the caps to what is stored
+//   npx maintenance-log backlog-add '<json>'    # append items under a row lock
+//
+// with the page and its tables named every time:
+//
+//   --at <tagPath>/<slug>      the log page, e.g. contents/tech/operations/wiki-maintenance-log
+//   --routine <name>           named on the page and in the revision message
+//   --pages <table>            default pages
+//   --revisions <table>        default revisions
+//   --page-key <column>        the revisions column naming the page, default page_id
+//   --scope <column>[=<value>] only rows where the column is NULL, or equals the value
+//   --author <id>              revisions.author_id, default NULL
+//   --invalidate <tag>         `vercel cache invalidate --tag` after a write
+//
+// `write` takes the whole new state: read, change, write back. A revision is
+// written at most once a day, and on every `compact`; other writes edit the
+// page in place, because a full copy per run is what made radix-wiki's log
+// over half its revisions table. `backlog-add` is how another routine files an
+// item: `write` replaces the whole state, so an append through it could lose a
+// concurrent run's, and the row lock serialises the two. A revision's version
+// is the page's `version` column bumped a minor where the table has one, else
+// the latest revision's.
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { addBacklog, compact, ident, render, scopeSql } from '../dist/maintenance.js';
+import { bump } from '../dist/versioning.js';
+
+const args = process.argv.slice(2);
+const arg = name => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const [mode, payload] = args.filter((a, i) => !a.startsWith('--') && !args[i - 1]?.match(/^--(?!dry-run)/));
+const dry = args.includes('--dry-run');
+const at = arg('--at') ?? '';
+const routine = arg('--routine');
+const slugAt = at.lastIndexOf('/');
+
+if (!['read', 'write', 'compact', 'backlog-add'].includes(mode) || slugAt < 1 || !routine) {
+  console.error('usage: maintenance-log <read|write|compact|backlog-add> [json|-] --at <tagPath>/<slug> --routine <name> [--pages t] [--revisions t] [--page-key c] [--scope c[=v]] [--author id] [--invalidate tag] [--dry-run]');
+  process.exit(2);
+}
+const pages = ident(arg('--pages') ?? 'pages', '--pages');
+const revisions = ident(arg('--revisions') ?? 'revisions', '--revisions');
+const pageKey = ident(arg('--page-key') ?? 'page_id', '--page-key');
+const scope = scopeSql(arg('--scope'), 3);
+const where = `tag_path = $1 AND slug = $2 AND ${scope.sql}`;
+const address = [at.slice(0, slugAt), at.slice(slugAt + 1), ...scope.values];
+
+if (!process.env.DATABASE_URL) {
+  try {
+    process.loadEnvFile('.env');
+  } catch {
+    // reported below
+  }
+}
+if (!process.env.DATABASE_URL) {
+  console.error('no DATABASE_URL in the environment or ./.env');
+  process.exit(1);
+}
+
+const readStdin = async () => {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+};
+
+// Imported once the command is known good: `pg` is the app's, not this package's.
+const { default: pg } = await import('pg');
+const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
+const q = (text, values) => client.query(text, values).then(r => r.rows);
+let wrote = false;
+try {
+  await client.connect();
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (mode === 'read') {
+    const [page] = await q(`SELECT metadata FROM ${pages} WHERE ${where}`, address);
+    if (!page) throw new Error(`no log page at ${at}`);
+    process.stdout.write(`${JSON.stringify(page.metadata?.state ?? {}, null, 2)}\n`);
+  } else if (mode === 'backlog-add') {
+    const items = JSON.parse(payload ?? '[]');
+    if (!Array.isArray(items) || !items.length) throw new Error('backlog-add expects a non-empty JSON array of items');
+    await q('BEGIN');
+    const [page] = await q(`SELECT id, metadata FROM ${pages} WHERE ${where} FOR UPDATE`, address);
+    if (!page) throw new Error(`no log page at ${at}`);
+    const state = page.metadata?.state ?? {};
+    const added = addBacklog(state, items, today);
+    if (!added.length) {
+      await q('ROLLBACK');
+      console.log('  nothing to add (all duplicates)');
+    } else {
+      const next = compact({ ...state, backlog: [...(state.backlog ?? []), ...added] });
+      console.log(`  ${dry ? '[dry] ' : ''}+${added.length} backlog item(s), ${next.backlog.length} open`);
+      for (const a of added) console.log(`     ${a.item}`);
+      if (dry) await q('ROLLBACK');
+      else {
+        await q(`UPDATE ${pages} SET content = $1, metadata = $2, updated_at = now() WHERE id = $3`, [
+          JSON.stringify(render(next, routine)),
+          JSON.stringify({ state: next, lastVerified: today }),
+          page.id,
+        ]);
+        await q('COMMIT');
+        wrote = true;
+      }
+    }
+  } else {
+    const [page] = await q(`SELECT * FROM ${pages} WHERE ${where}`, address);
+    if (!page) throw new Error(`no log page at ${at}`);
+    let input = page.metadata?.state ?? {};
+    if (mode === 'write') {
+      const text = payload === undefined || payload === '-' ? await readStdin() : payload;
+      if (!text.trim()) throw new Error('write needs the state as JSON, as an argument or on stdin with `write -`');
+      input = JSON.parse(text);
+    }
+    const state = compact(input);
+    const content = render(state, routine);
+
+    const [last] = await q(
+      `SELECT version, created_at FROM ${revisions} WHERE ${pageKey} = $1 ORDER BY created_at DESC LIMIT 1`,
+      [page.id],
+    );
+    const revise = mode === 'compact' || !last || last.created_at.toISOString().slice(0, 10) !== today;
+    const was = 'version' in page ? page.version : last?.version;
+    const version = revise ? bump(was, 'minor') : was;
+
+    for (const key of ['backlog', 'runHistory', 'feedback']) {
+      const [before, after] = [(input[key] ?? []).length, state[key].length];
+      if (before !== after) console.log(`  ${key}: ${before} → ${after}`);
+    }
+    console.log(
+      `  ${dry ? '[dry] ' : ''}state ${JSON.stringify(input).length} → ${JSON.stringify(state).length} B, ` +
+        `content ${JSON.stringify(content).length} B${revise ? `, revision v${version}` : ', no revision today'}`,
+    );
+
+    if (!dry) {
+      await q('BEGIN');
+      await q(
+        `UPDATE ${pages} SET content = $1, metadata = $2, updated_at = now()${'version' in page ? ', version = $4' : ''} WHERE id = $3`,
+        [JSON.stringify(content), JSON.stringify({ state, lastVerified: today }), page.id, ...('version' in page ? [version] : [])],
+      );
+      if (revise) {
+        // An id with no database default (a Prisma cuid) is supplied here.
+        const [{ has_default }] = await q(
+          `SELECT column_default IS NOT NULL AS has_default FROM information_schema.columns
+           WHERE table_schema = current_schema() AND table_name = $1 AND column_name = 'id'`,
+          [revisions.slice(1, -1)],
+        );
+        const row = {
+          ...(has_default ? {} : { id: randomUUID() }),
+          [pageKey.slice(1, -1)]: page.id,
+          title: page.title,
+          content: JSON.stringify(content),
+          version,
+          change_type: 'minor',
+          author_id: arg('--author') ?? null,
+          message: mode === 'compact'
+            ? 'Compact the log: drop closed and duplicated backlog items, cap the append-only lists'
+            : `${routine} run ${state.lastRun ?? today}`,
+        };
+        const columns = Object.keys(row);
+        await q(
+          `INSERT INTO ${revisions} (${columns.map(c => `"${c}"`).join(', ')}) VALUES (${columns.map((_, i) => `$${i + 1}`).join(', ')})`,
+          Object.values(row),
+        );
+      }
+      await q('COMMIT');
+      wrote = true;
+      console.log(`log page updated${revise ? ` → v${version}` : ''}`);
+    }
+  }
+} catch (e) {
+  await client.query('ROLLBACK').catch(() => {});
+  console.error(e.message);
+  process.exitCode = 1;
+} finally {
+  await client.end().catch(() => {});
+  const tag = arg('--invalidate');
+  if (wrote && tag) {
+    try {
+      execFileSync('vercel', ['cache', 'invalidate', '--tag', tag, '--yes'], { 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}\``);
+    }
+  }
+}

package/bin/mark-verified.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// bin/mark-verified.mjs – stamp last_verified_at on pages a sweep has checked
+// against their sources and found current, so `freshnessBanner`
+// (`wiki-formant/freshness`) stops calling them outdated. A page that needed an
+// edit gets its revision instead; this is for one that did not.
+//
+// radix-wiki and caper each carried this script against their own table. Run
+// it from the app's root, where `pg` is installed and `.env` holds DATABASE_URL.
+//
+//   npx mark-verified <tagPath> <slug>          one page ('' is a category hub)
+//   npx mark-verified --all <tagPath>           every page at or under a tag path
+//
+//   --table <table>             default pages
+//   --scope <column>[=<value>]  only rows where the column is NULL, or equals the value
+//   --invalidate <tag>          `vercel cache invalidate --tag` after a write
+import { execFileSync } from 'node:child_process';
+import { ident, scopeSql } from '../dist/maintenance.js';
+
+const args = process.argv.slice(2);
+const arg = name => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const all = args.includes('--all');
+const [tagPath, slug] = args.filter((a, i) => !a.startsWith('--') && !['--table', '--scope', '--invalidate'].includes(args[i - 1]));
+
+if (!tagPath || (!all && slug === undefined)) {
+  console.error('usage: mark-verified <tagPath> <slug> | --all <tagPath>  [--table t] [--scope c[=v]] [--invalidate tag]');
+  process.exit(2);
+}
+const table = ident(arg('--table') ?? 'pages', '--table');
+const scope = scopeSql(arg('--scope'), 3);
+
+if (!process.env.DATABASE_URL) {
+  try {
+    process.loadEnvFile('.env');
+  } catch {
+    // reported below
+  }
+}
+if (!process.env.DATABASE_URL) {
+  console.error('no DATABASE_URL in the environment or ./.env');
+  process.exit(1);
+}
+
+// Imported once the command is known good: `pg` is the app's, not this package's.
+const { default: pg } = await import('pg');
+const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
+try {
+  await client.connect();
+  const { rowCount } = all
+    ? await client.query(
+        `UPDATE ${table} SET last_verified_at = now() WHERE (tag_path = $1 OR tag_path LIKE $2) AND ${scope.sql}`,
+        [tagPath, `${tagPath}/%`, ...scope.values],
+      )
+    : await client.query(
+        `UPDATE ${table} SET last_verified_at = now() WHERE tag_path = $1 AND slug = $2 AND ${scope.sql}`,
+        [tagPath, slug, ...scope.values],
+      );
+  console.log(`Stamped last_verified_at on ${rowCount} page(s).`);
+  const tag = arg('--invalidate');
+  if (rowCount && tag) {
+    try {
+      execFileSync('vercel', ['cache', 'invalidate', '--tag', tag, '--yes'], { 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}\``);
+    }
+  }
+} catch (e) {
+  console.error(e.message);
+  process.exitCode = 1;
+} finally {
+  await client.end().catch(() => {});
+}

package/bin/prisma-models.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// bin/prisma-models.mjs – copy the Prisma models wiki-formant's SQL reads into an
+// app's schema folder, or check that the copies there have not drifted.
+//
+// `wiki-formant/analytics` and `wiki-formant/passkey` own their SQL and name
+// their tables as written, so the models are the package's. Three apps carried
+// them byte for byte, and the package kept a fourth copy as a comment.
+//
+// Prisma reads a schema split across the .prisma files of one folder. The app
+// points prisma.config.ts at the folder (`schema: 'prisma/schema'`), keeps its
+// generator, datasource and own models in prisma/schema/schema.prisma, and this
+// writes analytics.prisma and passkey.prisma beside them. Run it from the app's
+// root:
+//
+//   npx prisma-models                   # write both into prisma/schema
+//   npx prisma-models --check           # exit 1 if either is missing or differs
+//   npx prisma-models analytics         # only the ones named
+//   npx prisma-models --dir db/schema   # another folder
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MODELS = ['analytics', 'passkey'];
+const args = process.argv.slice(2);
+const check = args.includes('--check');
+const at = args.indexOf('--dir');
+const dir = at >= 0 ? args[at + 1] : 'prisma/schema';
+const named = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--dir');
+const unknown = named.filter(n => !MODELS.includes(n));
+
+if (unknown.length || !dir) {
+  console.error(`usage: prisma-models [${MODELS.join('|')}…] [--dir <folder>] [--check]`);
+  process.exit(2);
+}
+if (!existsSync(dir)) {
+  console.error(`prisma-models: no ${dir}/ here. Move prisma/schema.prisma into it and point prisma.config.ts's schema at the folder.`);
+  process.exit(2);
+}
+
+let drift = 0;
+for (const name of named.length ? named : MODELS) {
+  const shipped = readFileSync(new URL(`../prisma/${name}.prisma`, import.meta.url), 'utf8');
+  const target = join(dir, `${name}.prisma`);
+  const local = existsSync(target) ? readFileSync(target, 'utf8') : null;
+  if (local === shipped) continue;
+  if (check) {
+    drift++;
+    console.error(`${target} ${local === null ? 'is missing' : 'differs from wiki-formant'}: run npx prisma-models`);
+  } else {
+    writeFileSync(target, shipped);
+    console.log(`wrote ${target}`);
+  }
+}
+process.exit(drift ? 1 : 0);