@aotter/mantle 0.2.1 → 0.2.2-alpha.1

package/docs/handbook/cloudflare/authentication.md

@@ -46,6 +46,15 @@ Mantle reads the official admin plugin’s `adminRoles` when auth loads (default
 - `withAuthTasks(ctx.waitUntil.bind(ctx), () => auth.handler(request))` retains background sends/cleanup for the current request, with concurrent requests isolated. `authHardening` installs `retainAuthTask` as Better Auth's background handler. Failure logs are generic and contain no OTPs/credentials.
 - `authSetupIncomplete()` returns 503/no-store while secrets/providers are unconfigured; do not authenticate by fallback.
 
+`authRoutes` also gives public OTP validation failures one JSON response (400,
+`INVALID_OTP`, private/no-store), including error headers. Better Auth still enforces
+expiry and attempt limits. Success cookies, HTTP 429 and other protocol errors are
+preserved. This matches error codes rather than URL spelling and does not equalize
+response time or replace rate limiting. An application mounting `auth.handler`
+directly can call `normalizeEmailOtpResponse(await auth.handler(request))` from
+`@aotter/mantle/auth/routes`; apply host CORS and security headers outside this
+normalizer. It does not alter the application's native Better Auth hooks.
+
 Better Auth config is app-owned, so restrict who may sign up (an allowlist, an invitation) with a
 `databaseHooks.user.create.before` hook that throws `APIError("FORBIDDEN")` from `better-auth/api` (the app shell calls
 `src/signup.ts` there; returning `false` instead breaks email-OTP sign-in in Better Auth 1.7.7, which does not expect a refused create).
@@ -62,6 +71,48 @@ or `oauthProvider` for ordinary OAuth. These are optional app dependencies behin
 Use the live grant/session hooks and route wiring in [OAuth](../guides/oauth.md); merge verification hooks with the app shell's
 user hooks. `genericOAuth` is a login plugin, distinct from the OAuth provider.
 
+### Passkeys
+
+`authRoutes` may list `{ kind: "passkey" }` in `methods` when the app adds Better Auth's `@better-auth/passkey` plugin
+in its own `auth.ts`, pinned to the same version as `better-auth`. Admin lists the method to its `SignIn` slot
+([Customising Admin](../guides/native-admin.md#sign-in)) and renders no passkey sign-in of its own; the sign-in
+experience is the application's.
+
+- **`rpID` is the auth host.** Every origin under the `rpID` may ask for assertions with those passkeys, so use a parent
+  domain only when the deployment owns the whole registrable domain.
+- **User verification is not enforced.** The plugin verifies sign-in with `requireUserVerification: false`, so a tap
+  without biometrics or a PIN signs in. Its sign-in endpoint does not prove the person is present; do not use it to
+  approve an action.
+- `mantle generate --auth src/auth.ts` adds the plugin's `passkey` table to `schema.sql`.
+
+### Verifying access tokens on Workers
+
+`resolveCaller` verifies a Bearer or DPoP access token with Better Auth's resource client, which fetches the
+issuer's keys from `<baseURL>/jwks` by URL and caches them per isolate for five minutes. When the issuer is the
+same Worker, each request that lands on an isolate without those keys first makes a public-network request back
+into the Worker, which also reads D1 and passes Better Auth's HTTP rate limiter. Better Auth 1.7 has no supported
+in-process key source for this path yet ([better-auth/better-auth#11604](https://github.com/better-auth/better-auth/issues/11604)).
+
+Until it does, the app shell's `src/jwks.ts` answers exactly that URL in process. `service.ts` installs it once per
+isolate around `globalThis.fetch`, with the URL its `auth.ts` produces (`${PUBLIC_ORIGIN}/api/auth/jwks`):
+
+```ts
+globalThis.fetch = withInProcessJwks(globalThis.fetch, `${env.PUBLIC_ORIGIN}/api/auth/jwks`,
+  async () => (await loader.get()).api.getJwks());
+```
+
+- Only a GET of that exact URL is answered, from `auth.api.getJwks()`: public keys only, under the jwt plugin's own
+  rotation rules. Every other request uses the real `fetch`.
+- Better Auth still verifies the token, its DPoP binding and replay, and Mantle still checks the live grant. Better
+  Auth still caches the keys by that URL, so an isolate reads them once per five minutes.
+- The call does not go through Better Auth's HTTP router, so it shares no rate-limit bucket and needs no
+  `ExecutionContext`.
+- Keep the URL in step with `baseURL`, `basePath` and the jwt plugin's `jwksPath`. A mismatch is not a failure: the
+  request just goes over the network as before. With `jwks.remoteUrl`, keys live elsewhere: do not install it.
+
+This patches `fetch` inside the application's own Worker; Mantle Core does not. Remove `src/jwks.ts` once Better
+Auth's resource client accepts an in-process key source.
+
 ## Identity helpers
 
 `@aotter/mantle/auth/identity` exports `d1Identity(db, auth, caller, request.headers)` and

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -60,6 +60,11 @@ can move fetch execution closer to observed back-end services:
 "placement": { "mode": "smart" }
 ```
 
+A placed Worker runs every request that reaches it in that location, static files
+included. Keep static prefixes out of `assets.run_worker_first` (the generated
+default already excludes `/admin/assets/*` and `/assets/*`) so the edge answers them next to the
+visitor; see [Workers assets](service-entry.md#workers-assets-and-secrets).
+
 For globally distributed, read-heavy D1 traffic, enable
 [read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/)
 on the database and pass one request-scoped `env.DB.withSession(...)` handle to

package/docs/handbook/cloudflare/media-r2.md

@@ -44,7 +44,9 @@ An existing S3 signer (for example an application already using aws4fetch) fits
 this port. This package adds no AWS SDK. The signer must return a SigV4
 query-signed PUT URL and preserve `X-Amz-Expires`; never give its credentials to
 the client. Configure bucket CORS to allow PUT from the application's origins
-and the returned Content-Type header. Uploads go to `uploads/<purpose>/<group>/<role>.<ext>` and each commit copies them
+and the returned Content-Type header (and from each MCP host's App sandbox origin
+when you register the [upload card](../guides/mcp-apps.md#the-upload-card); its
+CSP names the storage's `uploadOrigin`, the origin of `endpoint`). Uploads go to `uploads/<purpose>/<group>/<role>.<ext>` and each commit copies them
 to `committed/<group>/<attempt>/<role>.<ext>`. Serve the `committed/` prefix on the public domain. Keep `uploads/`
 private/unserved on the public domain and add a bucket lifecycle rule for abandoned upload keys. Mantle 0.1.x wrote
 `<purpose>/<group>/<role>.<ext>` keys (`<group>/<role>.<ext>` when the purpose was not a plain slug); an asset reads its keys from the stored `storageKey` and `publicUrl` of each
@@ -52,7 +54,8 @@ variant, so 0.1.x assets keep working while their prefixes stay served.
 
 Commit checks every object's MIME and size, then rechecks the exact GET
 response used for the copy. Public keys cannot be reached by an upload URL. Each commit attempt has a separate
-public-key UUID, while the asset id remains the upload-group UUID. A concurrent
+public-key UUID, while the asset id remains the upload-group id (`<tag>_<uuid>`; the tag is
+this database's `site_config.media_id_tag`, so another server's id is refused as `MEDIA_NOT_OWNED`). A concurrent
 loser can neither overwrite nor remove the winner's objects. After SQL selects
 the durable asset, the losing attempt removes only its own unselected copies.
 Upload sources remain until the database commit succeeds, so an uncertain DB

package/docs/handbook/cloudflare/service-entry.md

@@ -115,9 +115,10 @@ its collection parameter selects only a generated table and visibility policy.
 ## Workers assets and secrets
 
 `mantle generate --admin --wrangler wrangler.jsonc` sets the selected assets
-directory. A new assets block defaults to `binding: "ASSETS"`, `run_worker_first: true`
-and `html_handling: "none"`. Existing blocks keep their binding and routing; when
-`run_worker_first` is already true, a missing `html_handling` defaults to `none`.
+directory. A new assets block defaults to `binding: "ASSETS"`,
+`run_worker_first: ["/*", "!/admin/assets/*", "!/assets/*"]` and `html_handling: "none"`.
+Existing blocks keep their binding and routing; when `run_worker_first` is true or a
+list, a missing `html_handling` defaults to `none`.
 A different binding needs a custom Admin HTML loader. Deploy the built assets and
 Worker together.
 
@@ -133,15 +134,32 @@ JSONC comments and unrelated settings survive regeneration:
   "assets": {
     "directory": "dist/client",
     "binding": "ASSETS",
-    "run_worker_first": true,
+    "run_worker_first": ["/*", "!/admin/assets/*", "!/assets/*"],
     "html_handling": "none"
   },
   "d1_databases": [{ "binding": "DB", "database_name": "your-database", "database_id": "your-id" }]
 }
 ```
 
-`run_worker_first` lets the application supply shell/security/cache headers;
-`none` keeps `index.html` available by name. `adminShell(request, assets)` passes
+The Worker serves HTML shells and APIs; static files are answered by the edge without
+running it. `mantle bundle` writes `<assets>/_headers` with `nosniff` and a one-year
+`immutable` cache for Admin's content-hashed `/admin/assets/*` (an existing `_headers`
+is not edited: the build prints the rule to add). `mantle bundle` also copies the
+working directory's `public/` into the assets directory (removing what it copied last
+time; `public/admin` is refused). `/assets/*` is excluded by default, so
+`public/assets/*` is answered by the edge; other public files reach the Worker first,
+which can serve them with `env.ASSETS.fetch(request)` as the app shell does. Cloudflare
+sends `Cache-Control: public, max-age=0, must-revalidate` and an ETag by default; set
+`immutable` in `public/_headers` only for content-hashed files. `_headers` does not
+apply to responses the Worker builds. A path the Worker must answer stays out of the
+exclusion.
+
+After a deploy the previous version's assets are gone, so an open Admin tab that loads
+a chunk from the old build gets a 404; Admin then offers a reload and warns that unsaved changes may be lost.
+With [gradual deployments](https://developers.cloudflare.com/workers/versions-and-deployments/gradual-deployments/version-affinity/),
+set a version key (`Cloudflare-Workers-Version-Key`) so a page and its chunks come from
+the same version. `none` keeps `index.html`
+available by name. `adminShell(request, assets)` passes
 paths relative to the Admin directory, so the app fetches them under `/admin/`:
 `path => env.ASSETS.fetch(new Request(new URL("/admin/" + path, request.url), request))`. Admin assets are not a public database
 API. PostgreSQL uses application-owned Hyperdrive/postgres.js wiring,
@@ -199,7 +217,10 @@ const reader = async (path: string) => (await assets('/' + path)) ?? new Respons
 ```
 
 The reader returns a native `Response` or `null`, rejects traversal/control
-characters and escaping symlinks; the app owns shell, CSP and cache headers.
+characters and escaping symlinks, sets `nosniff` on every file and caches Admin's
+content-hashed `/assets/` chunks for a year (`immutable`); the app owns shell, CSP
+and any other cache headers. Root it at Admin's directory: it caches every `/assets/` path for a year, so serve `public/` files with your own reader and cache headers. Bun has no edge in front of it: put a CDN or reverse
+proxy before the server to keep static requests off it.
 Use ignored `.env` on Bun.
 
 Admin's build tools and UI packages are dependencies of `@aotter/mantle-admin`,

package/docs/handbook/examples/hub.md

@@ -2,4 +2,4 @@
 
 Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.1/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.2-alpha.1/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/mcp-apps.md

@@ -45,6 +45,11 @@ than `["app"]` on an `appOnly` tool) fails when `mcp()` is constructed.
 from clients that declare no MCP Apps support, as `appOnly` does for Views. It
 is a listing hint only: `tools/call` still runs every identity, scope, `check`
 and `authorize` decision, so an App-only write is authorized like any other.
+It is not an access boundary either: any client holding the same credential can
+call an App-only tool directly. An action that needs the person present is
+enforced on the server, for example by a Procedure that accepts only a
+single-use value which a person-present check in the browser produces and
+which no MCP result ever returns.
 
 A `run` may return `withResultMeta(data, meta)` from `@aotter/mantle/mcp`. The
 result's text and `structuredContent` are built from `data` exactly as before;
@@ -68,6 +73,13 @@ const uploadTarget: Tool<unknown> = {
 };
 ```
 
+`run` also receives `{ apps }` after `handlers`: `apps` is true when the
+`tools/call` request declares MCP Apps support and an App resource renders the
+tool, so a tool can keep a secret in
+the result `_meta` for an App and return it in the data for a client that has
+none (`upload_media` does this with its targets). `callTool` and `callToolLazy`
+take it as an optional last argument (default `{ apps: false }`).
+
 `callTool` and `callToolLazy` return the wrapper itself, `{ data, _meta }`.
 A caller that forwards a result to a model, such as an application's own agent,
 must forward only `data` and drop `_meta`, or the signed URL leaks through that
@@ -135,24 +147,29 @@ file carries the `csp` your `defineAdmin({ mcp: { csp } })` declared; a loader m
 `resources/read`; it replaces the resource's own `csp` rather than merging with it. A loader
 that throws answers the host with a redacted error and logs the message on the server.
 
-Resource URIs are immutable cache identities. By default Admin contributes an async
-resource source: after the request passes the origin/identity/Admin gates, Admin
-reads its built asset and hashes the HTML, full static catalogue and material
-resource metadata into `ui://mantle-admin/admin/<digest>`. A new UI build or catalogue
-gets a new URI, used consistently by tools and resource reads. Workers cache only
-the raw immutable asset/identity per contributor and ASSETS binding; caller-filtered
-catalogues are embedded per read. Bun rereads the file so rebuilding in the same
-process changes the identity. Run `mantle bundle` and deploy its assets with the server;
-missing assets can fail discovery when Admin resolves the build identity.
-
-An explicit `uri` keeps application-owned identity. A custom `html` function must
-supply a build-specific `uri`: Core cannot infer its build or safely memoize its
-request-dependent output. A raw `html` string may use the automatic identity.
+Resource URIs are stable identities. The MCP Apps specification lets a host prefetch
+and cache a UI resource by its URI, so by default Admin links its tools to the fixed
+`ui://mantle-admin/admin`: after a deploy a host keeps the link it saved, and a new read
+returns the new build. After the request passes the origin/identity/Admin gates, Admin
+reads its built asset and also serves it at `ui://mantle-admin/admin/<digest>`, a hash of
+the HTML, full static catalogue and material resource metadata, for conversations that
+hold that URI. Workers cache only the raw asset and its identity per contributor and
+ASSETS binding; caller-filtered catalogues are embedded per read. Bun rereads the file,
+so a rebuild in the same process serves the new build. Run `mantle bundle` and deploy its
+assets with the server; missing assets can fail discovery.
+
+Change the URI only when saved conversations must not load the new App, because its
+contract with its tools changed incompatibly: pass an explicit `uri` such as
+`ui://mantle-admin/admin/v2`. A custom `html` function has no build identity to hash: it
+is served at the fixed URI or an explicit `uri`.
 
 ### Keep old conversations working after an upgrade
 
-A new URI does not invalidate a host's saved tool definitions or old conversation
-cards. Keep previously deployed pages with `adminMcpApps({ catalogue, previous })`.
+With the fixed default, conversations keep rendering across deploys without retention.
+A conversation that holds a content-hash URI from an earlier build (one started before
+this default, or before an explicit `uri` change) needs that page
+retained: a new URI does not invalidate a host's saved tool definitions or old
+conversation cards. Keep previously deployed pages with `adminMcpApps({ catalogue, previous })`.
 `previous` is an array of `AdminMcpSnapshot` from `@aotter/mantle-admin/mcp`:
 `{ uri, html, csp?, domain?, title? }`. Each `html` includes the original `mantle-catalog`
 script (the page returned by `resources/read`, not the raw bundle). The SDK serves
@@ -207,7 +224,9 @@ const previous = JSON.parse(readFileSync(path, 'utf8'));
 const context = { env: {}, request: new Request('https://archive.invalid/mcp') };
 const source = adminMcpApps({ ...appDefinition,
   html: readFileSync('dist/client/admin/mcp-app.html', 'utf8') });
-const { resources: [resource] } = typeof source === 'function' ? await source(context) : source;
+const { resources } = typeof source === 'function' ? await source(context) : source;
+// The build's own content-hash URI (an explicit `uri` contributes only that URI).
+const resource = resources.find(r => /\/admin\/[a-f0-9]{64}$/.test(r.uri)) ?? resources[0];
 const tools = new Set([...Object.keys(appDefinition.catalogue.views),
   ...Object.keys(appDefinition.catalogue.actions)]);
 const loaded = typeof resource.html === 'string' ? resource.html
@@ -295,19 +314,76 @@ full screen, a row action, and a link. Check too that the host advertises
 `hostCapabilities.serverTools`; without it the App is read-only. The automated interoperability test
 uses the official `AppBridge`; your app runs its generated version ([Run the compatibility test](#run-the-compatibility-test)).
 
+## The upload card
+
+`upload_media` on `/mcp/admin` can open an upload card, an MCP App Admin ships
+prebuilt. Register it beside the Admin App, with the same `media` function you
+pass `mcp(...)`:
+
+```ts
+import { adminMcpApps, mediaUploadCard } from '@aotter/mantle-admin/mcp';
+import type { MediaStorage } from '@aotter/mantle/site';
+import { mcp } from './generated/mcp.js';
+import { mcpAppCatalogues } from './generated/admin-descriptors.js';
+
+declare const options: Parameters<typeof mcp>[0];
+declare function storage(env: unknown): MediaStorage; // e.g. r2MediaStorage(...)
+
+const handler = mcp({ ...options, media: storage, apps: { admin: [
+  adminMcpApps({ catalogue: mcpAppCatalogues.admin }),
+  mediaUploadCard({ media: storage }),
+] } });
+```
+
+The card is `ui://mantle-admin/upload` and renders `upload_media`. The person
+picks an image (and may type alt text); the card reads the purposes with
+`upload_media`, calls it with the file's metadata, PUTs the file straight to the
+target with progress, calls `upload_media` again with the `uploadId`, and sends
+`ui/message` with the asset id (or `ui/update-model-context` when the host takes
+no messages). The bytes never pass through MCP or the host. The card uploads the
+original file as the single variant a purpose takes
+([ADR-0017](../../adr/0017-media-multi-variant-agent-side-optimization.md)); a
+purpose with several variant slots needs an agent that prepares them, and the
+card says so. It needs the host's `serverTools`.
+
+The targets reach the card in the result `_meta` (`net.aotter.mantle/upload`)
+when the request declares MCP Apps support and the card is registered;
+otherwise they are in the result,
+for an agent that PUTs them itself. The card reads either.
+
+On `resources/read` the card declares the storage origin as
+`_meta.ui.csp.connectDomains`. It is the storage's `uploadOrigin`:
+`r2MediaStorage` sets it to the origin of its `endpoint`; a custom
+`MediaStorage` sets it to the origin its `uploadUrl`s PUT to. Without it the
+read fails with a logged error.
+
+The bucket must answer the card's CORS preflight. Allow `PUT` with the
+`Content-Type` header from the origin the host serves Apps from, and key the
+rule on `Origin`: the request carries no cookies, and some clients (iOS) send no
+`Referer`. A sandboxed frame without its own origin sends `Origin: null`. For
+example, as R2 CORS JSON:
+
+```json
+[{ "AllowedOrigins": ["https://your-host-sandbox.example"], "AllowedMethods": ["PUT"], "AllowedHeaders": ["content-type"], "MaxAgeSeconds": 3600 }]
+```
+
+Use the sandbox origin each host documents for its Apps (a host that honours
+`_meta.ui.domain` serves the App from that origin; `mediaUploadCard` passes
+`domain` through).
+
 ## Customising Admin for MCP hosts
 
 `mantle bundle` builds the Admin MCP App from the same entry as the browser Admin
 (`src/admin.tsx`, or the built-in one) into one self-contained file,
 `<assets>/admin/mcp-app.html`, which `adminMcpApps` serves as
-`ui://mantle-admin/admin/<digest>` by default. Shared View cells and opted-in pages reach the host, with application plugins,
+`ui://mantle-admin/admin` by default. Shared View cells and opted-in pages reach the host, with application plugins,
 Tailwind classes and CSS. Browser-only record/input overrides do not mount there.
 
 ### Which slots render where
 
 | Slot | Browser | MCP host |
 | --- | --- | --- |
-| `Shell`, `Sidebar`, `Header`, `Brand`, `Home`, `CollectionList`, `list.actions:<schema>` | yes | never: the App has no shell, sidebar or router |
+| `Shell`, `Sidebar`, `Header`, `Brand`, `Home`, `CollectionList`, `SignIn`, `list.actions:<schema>` | yes | never: the App has no shell, sidebar or router |
 | `cell:view:<view>.<column>` | yes | yes: each column of the rows the host's View tool returned |
 | `cell:<schema>.<field>`, `input:<schema>.<field>`, `record.aside:<schema>`, `record.actions:<schema>`, `RecordView` | yes | never: browser-only record/collection slots; their `surface` is `"browser"` (`mantle bundle` reminds you) |
 | `pages[]`, `nav`, `home`, nav badges | yes | only a page that declares `mcp` (below) |

package/docs/handbook/guides/native-admin.md

@@ -227,6 +227,7 @@ collection's name, `<field>` one of its fields and `<column>` a column of an adm
 | `Brand` | browser | `title`, `image?`, `href?` |
 | `Home` | browser | `collections`, `site` (what the page shows; the built-in page loads its own data) |
 | `CollectionList` | browser | `collection` (filters come from the page's location) |
+| `SignIn` | browser | `methods`, `returnTo`, `oauthQuery`, `emailAutoComplete`, `onSignedIn(next)` ([below](#sign-in)) |
 | `RecordView` | browser | `collection`, `entryId`, `surface` |
 | `record.aside:<schema>` | browser | `collection`, `entry`, `surface` |
 | `record.actions:<schema>` | browser | `collection`, `entry`, `surface` |
@@ -404,6 +405,34 @@ View that has an MCP tool (`tsc` checks it against the generated `admin-client.t
 Authorization is unchanged by any of this. A component that shows or hides something grants or denies nothing; the server
 checks every route, View and Procedure.
 
+### Sign-in
+
+`/admin/sign-in` lists the methods `authRoutes` returns from `GET <auth>/methods` (`email-otp`, `magic-link`, `passkey`,
+`social`, `oauth`) through the `SignIn` slot. Admin renders the email code, magic link, social and OAuth methods; it
+renders nothing for `passkey`, which is listed for an application that builds its own. Pass changed props to
+`renderDefault` to reorder or drop `methods`, set the email field's `emailAutoComplete`, or wrap `onSignedIn`; render
+your own elements around it to add a method of your own.
+
+Admin calls `onSignedIn(next)` once the email code has signed in. `next` is where Admin goes by default: Better Auth's
+OAuth authorize continuation when the sign-in came from an OAuth client such as an MCP connector, or the page's return
+path. Run your own step first, then navigate to the same `next`. Redirecting methods (social, OAuth, magic link) leave
+the page and do not call it.
+
+```tsx
+export default defineAdmin(admin, {
+  components: {
+    SignIn: (props) => props.renderDefault({ ...props,
+      onSignedIn: next => { sessionStorage.setItem("after-sign-in", next); window.location.assign("/admin/p/welcome"); } }),
+  },
+  pages: [{ path: "welcome", title: "Welcome", element: <Welcome /> }],
+});
+```
+
+Keep `next` out of the step page's URL: read it back from where your wrapper stored it, then navigate there unchanged.
+A page that follows a `?next=` from its own address is an open redirect, and `next` may be Better Auth's absolute OAuth
+continuation, so a "same-origin only" check would also break connector sign-in. The signed-in method stays locked once
+`onSignedIn` runs, so navigate away (or replace the page) rather than leaving the card in place.
+
 ### Components that also render in an MCP host
 
 Record/collection slots carry `surface: "browser"` and do not mount in an MCP

package/docs/handbook/guides/performance.md

@@ -110,7 +110,11 @@ fast at a realistic volume, and no hot path scans a table that grows.
   the largest tables at 100,000 rows or 10 times the expected first-year volume,
   whichever is larger. Seed with SQL straight into that database, setting the
   native columns as [reserved entry columns](../reference/schema.md#reserved-entry-columns)
-  describes: it is test data, not an application write.
+  describes: it is test data, not an application write. Seed the database the
+  app's local dev server uses, not the one a test harness creates and throws
+  away, and generate the rows inside the database in one short statement rather
+  than sending a long list of values: local D1 refuses a single statement over
+  about 100 KB. [Seed in bulk](../reference/schema.md#seed-in-bulk) shows both.
 - **Load:** call every View and Procedure through the same callers and surfaces
   the application uses, as each role. The app's local test harness already
   starts it on a fresh database, signs each role in and calls routes and MCP

package/docs/handbook/guides/revisions.md

@@ -579,6 +579,6 @@ SEO notes:
 
 The revisions are the content history: who may read them, switch and prune is the Procedures' `requires`. A record of
 who changed what and when, across the whole app, is an observability concern rather than part of this content model;
-it is planned outside the SDK, with Mantle Cloud's observability or the app's own logging when self-hosted, and the
+it is planned outside the SDK, with the hosting platform's observability or the app's own logging when self-hosted, and the
 SDK's part is being discussed as a way to observe writes (aotter/mantle#1796). Until then, a revision's `author_id`
 and `created_at` say who started it and when, and the switch handler is the place to log a switch.

package/docs/handbook/guides/sql-patterns.md

@@ -257,6 +257,39 @@ check is "at least one", so a statement that writes several rows (`json_each(inp
 passes; give an array input `minItems: 1` when an empty one is a mistake. A ref handler throws its own
 `ContractError` instead.
 
+## Change another member's row: inline author_id
+
+A Procedure `restrict` narrows every statement in the program, including the ones after the first. With
+`restrict: { registrations: "author_id = auth.uid()" }`, "cancel my seat and give it to the first person waiting"
+cannot work: the promotion runs as the caller and sees no other member's row, so it changes nothing. Leave the
+Procedure without `restrict` and pin the caller's own row inline, in every statement that reads it, with
+`author_id = auth.uid()`; the statement that acts on other members' rows then runs unrestricted. Decide everything
+that depends on the waiting list before the statement that changes it, and end with the own-row write that must
+change exactly one row (`WHERE id = input.id`), so another member's id is `CONFLICT` and the whole program rolls back.
+
+```sql
+-- 1. Return the seat only if nobody waits for it.
+UPDATE events SET seats_taken = seats_taken - 1
+  WHERE id = (SELECT r.eventId FROM registrations r WHERE r.id = input.id AND r.author_id = auth.uid() AND NOT r.waitlisted)
+    AND NOT EXISTS (SELECT 1 FROM registrations w WHERE w.eventId = events.id AND w.waitlisted)
+  RETURNING capacity - seats_taken AS seats_left;
+-- 2. Otherwise the earliest waiter (another member's row) takes it.
+UPDATE registrations SET waitlisted = false
+  WHERE id = (SELECT w.id FROM registrations w JOIN registrations r ON r.eventId = w.eventId
+      WHERE r.id = input.id AND r.author_id = auth.uid() AND NOT r.waitlisted AND w.waitlisted
+      ORDER BY w.created_at, w.id LIMIT 1)
+  RETURNING id AS promoted;
+-- 3. The caller's own row: exactly one, or CONFLICT and nothing above stays.
+DELETE FROM registrations WHERE id = input.id AND author_id = auth.uid() RETURNING id
+```
+
+A `= auth.uid()` term in the SQL is a filter like any other, not a policy: every statement that must stay on the
+caller's rows needs its own. Rows another member waits with are their own inserts, so `author_id` names them; a
+Procedure never inserts a row on someone else's behalf, since `author_id` is stamped from the caller. D1 runs the
+program serialized. Under PostgreSQL's READ COMMITTED, two cancels for the same event at once can both pick the same
+waiter and leave one seat counted as taken; measure that case before relying on it there.
+[Club events](../../examples/club-events/README.md) has the whole waiting list (`cancel-registration`).
+
 ## A row with its children in one read
 
 An admin, or an AI client, reads each product with its orders in one call instead of one call per product. A

package/docs/handbook/reference/authorization.md

@@ -17,7 +17,7 @@ requires:
 | `ctx.admin` | Caller is in the admin layer |
 | `{ ctx.auth.scope: "scope" }` | User scopes include that scope |
 
-Selected REST, MCP and Admin boundaries accept an optional `authorize(target, caller)` callback. `Target`, exported by `@aotter/mantle/contracts`, contains `kind` (`view`, `procedure` or `schema`) and the manifest `name`; Admin generic entry routes also supply `action` (`read`, `create`, `update` or `delete`). The callback runs after credentials and `requires` pass, before execution and row policy. A false result or rejected promise returns `AUTH_DENIED` (HTTP 403); a synchronous exception is an internal error. MCP tool lists and Admin navigation metadata hide denied targets. Omitting the callback preserves existing behavior; direct generated typed functions do not invoke it.
+Selected REST, MCP and Admin boundaries accept an optional `authorize(target, caller)` callback. `Target`, exported by `@aotter/mantle/contracts`, contains `kind` (`view`, `procedure` or `schema`) and the manifest `name`; Admin generic entry routes also supply `action` (`read`, `create`, `update` or `delete`). The callback runs after credentials and `requires` pass, before execution and row policy. A false result or rejected promise returns `AUTH_DENIED` (HTTP 403); a rejection with an `AUTH_DENIED` `ContractError` keeps its message (for example the role that may call the target), and a synchronous exception is an internal error. MCP tool lists and Admin navigation metadata hide denied targets. Omitting the callback preserves existing behavior; direct generated typed functions do not invoke it.
 
 An impersonated session exposes `caller.impersonatedBy`, the real actor’s subject, only on the original branded Caller; applications decide impersonation policy in `authorize(target, caller)`.
 

package/docs/handbook/reference/describe.md

@@ -91,6 +91,11 @@ and Admin routers for every route of the example apps:
   limit the match to that endpoint's tools. Without a path, a name that the two
   endpoints map to different targets matches nothing.
 
+A host rule keyed on a request (for example "these targets need a step-up")
+must key on the target `matchTarget` returns, or apply the same normalisation
+itself. A rule on the raw pathname can be bypassed by an equivalent spelling
+such as `/api/views/%6Frders` or a trailing slash.
+
 Media tools (`admin:tool:<name>`) and the optional Admin developer and
 statistics routes match even when the application does not mount them; the
 application then answers `NOT_FOUND`. Routes and tools the application adds

package/docs/handbook/reference/schema.md

@@ -168,6 +168,25 @@ their existing values.
 | `published_at` (publishing) | integer microseconds when `status` is `'published'`, otherwise `NULL` | `timestamptz` or `NULL` | `NULL` |
 | scope column (owner or field scope) | the field the `scope` names (`owner` in `owner = auth.uid()`), text, not null | the same | the insert fails |
 
+### Seed in bulk
+
+For a performance pass, seed the local database the dev server uses (`wrangler dev` on D1, your own PostgreSQL), not
+the one a test harness starts and discards. Generate the rows in the database instead of sending each one: local D1
+refuses a statement larger than about 100 KB (`SQLITE_TOOBIG`), so a long `INSERT … VALUES` list fails where one
+generating statement does not. On SQLite and D1, a recursive CTE counts the rows:
+
+```sql
+-- seed.sql: 100,000 events, one hour apart (date-time fields are integer microseconds on SQLite and D1)
+INSERT INTO events (id, version, created_at, updated_at, title, startsAt, capacity, seats_taken, closed)
+WITH RECURSIVE n(i) AS (SELECT 1 UNION ALL SELECT i + 1 FROM n WHERE i < 100000)
+SELECT 'seed-' || i, 1, 1767225600000000 + i, 1767225600000000 + i, 'Event ' || i,
+  (1767225600 + i * 3600) * 1000000, 50, 0, 0 FROM n;
+```
+
+Apply it with `wrangler d1 execute DB --local --file seed.sql` (`DB` is the binding in `wrangler.jsonc`). On
+PostgreSQL write `FROM generate_series(1, 100000) AS i` instead of the CTE, use `now() + i * interval '1 hour'` for the timestamps, and run
+it with `psql -f seed.sql`. Seed related tables the same way, choosing parent ids by `i` (`'seed-' || (i % 5000 + 1)`).
+
 Units differ by table: entry timestamps (`created_at`, `updated_at`, `published_at` and declared `date-time` fields)
 are microseconds on SQLite and D1, while the optional media library's `media_assets.created_at` is epoch
 **milliseconds** on every dialect ([media](../cloudflare/media-r2.md)). A declared `date` field is integer days since

package/docs/handbook/reference/site-config.md

@@ -4,6 +4,8 @@ Select `--site <module>` exporting `siteDefaults`, or pass the same options to p
 
 Generation emits the generated site module, deployment DDL for `site_config`, `media_assets`, `pending_media_uploads`, and `site-seed.sql`. Apply initial schema only to an empty database. Apply seed SQL explicitly: only absent brand/title/description are seeded without overwriting edits. Origin, locales, icons and media purposes come from generated defaults. Runtime construction neither seeds nor migrates.
 
+A media purpose may declare `visibility: "private"`; omitted, it is `"public"`.
+
 Import the generated `site`, then use `site(db, verifiedCaller).read()` and `.updateSettings({ brand, title, description })`. Media is `site(db, caller).media(storage)`. Native SQLite/PostgreSQL are supported. Only selected modules enter the application bundle.
 
 Admin site/media routes are optional capabilities; their additional admin-cookie gate and origin checks remain required. The app owns object storage, signing and upload CORS. See [media wiring](../cloudflare/media-r2.md).

package/docs/handbook/reference/surface.md

@@ -215,6 +215,16 @@ by declared identity, scope and `check` requirements. Without `authorize`, the
 complete endpoint catalogue is not a permission-filtered catalogue. Operation
 validation, guards and credential checks still apply to calls.
 
+With `authorize`, `discovery: "all"` keeps the caller-independent list: every
+caller of the endpoint gets the same `tools/list` and the same tool names in
+resource HTML, and `authorize` (with `requires`, scopes and `check`) decides at
+call time. Prefer it when a caller's grant can change during a conversation, for
+example a role switched in a directory: a host keeps the tool list it saved, and a
+filtered list would leave it naming tools that are gone or missing ones the caller
+now has. An `authorize` that rejects with `new ContractError("AUTH_DENIED", message)`
+returns that message, so a refusal can name the role that may call the tool; a
+plain `false` or any other rejection answers "Target is not authorized."
+
 `toolsPageSize` pages `tools/list`: each page holds at most that many tools and
 carries an opaque `nextCursor` while more remain; pass it back as `cursor`. A
 cursor is valid only for the catalogue version that issued it; an unknown or
@@ -389,16 +399,62 @@ own entry; inherited property names never become titles or descriptions.
 ### Admin media MCP tools
 
 With generated site configuration, `mcp({ db, caller, media: env => storage })`
-loads the media module only on a configured admin MCP request and
-adds `get_media_upload_policy`, `create_media_upload`, `commit_media_upload`,
-`list_media_assets`, `get_media_asset`, `update_media_asset` and
-`delete_media_asset` to `/mcp/admin` only. `storage` is the same `MediaStorage`
-used by the Admin media library. Omitting `media` omits all seven tools.
-Admins can invoke them; cookie writes retain the origin check.
-Generated boundary code checks each input and advertises the 0.2 schemas and
-read-only/destructive/open-world hints. Image bytes are PUT directly to the
-returned short-lived URLs with their required headers, then committed; bytes
-never enter MCP. Store permanent asset ids, never upload URLs.
+loads the media module only on a configured admin MCP request and adds four
+tools to `/mcp/admin` only. `storage` is the same `MediaStorage` used by the
+Admin media library. Omitting `media` omits every media tool. Admins can invoke
+them; cookie writes retain the origin check. Generated boundary code checks each
+input and advertises read-only/destructive/open-world hints.
+
+| Tool | Does |
+|---|---|
+| `upload_media` | Upload one image, in two calls (below). |
+| `find_media` | Committed assets by `ids` (ids not found come back in `missing`), or newest first with `limit`, `cursor` and `search` (the exact id, or text in alt or caption). Read-only. |
+| `update_media` | Set `alt` or `caption` of `id`; an omitted field is unchanged, an empty string clears it. |
+| `delete_media` | Delete `id`'s objects and record (`destructiveHint`, so hosts confirm). A partial failure is retried with the same id. |
+
+`upload_media` takes one mode per call:
+
+1. `{ purpose, filename, variants: [{ mimeType, byteSize, role }], alt?, caption? }`
+   returns `{ uploadId, expiresAt, targets: [{ role, mimeType, method, url, headers }] }`.
+   PUT each variant's bytes to its `url` with its `headers`. Targets expire in
+   15 minutes and serve this one upload. When the request declares MCP Apps
+   support and a resource such as the upload card renders `upload_media`,
+   `targets` is left out of the result and sent only in the result
+   `_meta["net.aotter.mantle/upload"]`, which hosts give the App and not the
+   model; an agent without MCP Apps (a CLI agent such as Claude Code) reads them
+   in the result.
+2. `{ uploadId, purpose?, alt?, caption? }` commits and returns the asset.
+   Store its id in fields that reference `media_assets.id`, never an upload URL.
+   An unknown or expired `uploadId` is `MEDIA_UPLOAD_EXPIRED` (make a new first
+   call); before the commit, a `purpose` other than the upload's is
+   `MEDIA_UPLOAD_MISMATCH`; a committed `uploadId` returns the same asset again
+   (the asset records no purpose).
+
+`{ purpose? }` alone returns the purposes' policy, `{ purposes: [{ name, required, maxBytes }] }`
+(each `required` slot lists its accepted MIME types, comma-separated); the
+generated input schema also names the purposes and their caps, and policy
+failures say what was expected. With the [upload card](../guides/mcp-apps.md#the-upload-card)
+registered, an MCP Apps host shows it for this call.
+
+`{ purpose, sourceUrl }` and `{ purpose, file: { download_url, file_id } }` have the
+server fetch one image and run both steps in one call. `file` is the tool's
+`openai/fileParams` argument, so a host that hands the tool a chat attachment
+passes its download URL. Either takes a purpose with one variant slot. The fetch
+accepts only `https` on the default port, without credentials, to a public host:
+IPv6 literals, private, loopback, link-local, shared, reserved and multicast
+IPv4 addresses, single-label names and names such as `localhost`, `*.local` and
+`*.internal` are `MEDIA_SOURCE_REJECTED`, as is each redirect target (at most
+three). The body is capped at the purpose's byte cap
+(`MEDIA_VARIANT_SIZE_EXCEEDED`) and must sniff as PNG, JPEG, GIF, WebP or AVIF
+(`MEDIA_MIME_REJECTED`); an unreachable source is `MEDIA_SOURCE_FAILED` and a
+storage PUT failure `MEDIA_STORAGE_FAILED`. Names are checked, not resolved:
+Workers cannot reach private addresses, and on another runtime restrict the
+server's egress to the public internet. File content is never accepted as base64.
+
+The 0.1 names `get_media_upload_policy`, `create_media_upload`,
+`commit_media_upload`, `list_media_assets`, `get_media_asset`,
+`update_media_asset` and `delete_media_asset` still work in 0.2, after the four,
+with descriptions marked deprecated; they are removed in 0.3.
 
 Generation always emits a `Handlers` type (empty when no Procedure uses `handler: { ref }`), so every app wires the
 same way: `const handlers: Handlers = {...}`, then `store(db, caller, { handlers })`, `adminBindings({ handlers })`,