@aotter/mantle 0.2.0-alpha.4 → 0.2.0-alpha.6

package/docs/adr/adr-lite-1376-admin-extensions.md

@@ -0,0 +1,330 @@
+# ADR-lite 1376: Admin extensions
+
+**Status:** Accepted (revision 3: the full contract, for hosts and for
+projects; replaces the pages-only draft)
+
+## Context
+
+A project or the host that mounts Admin sometimes needs its own UI next to the generated
+collections, Views and operations. Examples are an operator's
+access-management screen, a record action that calls a host service, or a
+field widget for a host-specific format. Today the Admin SPA has no way to add
+any of these:
+
+- Its routes and navigation are fixed.
+- `createAdminSurface` has no host routes.
+- The UI kit (ADR-lite 909) deliberately does not export the application
+  shell.
+
+Hosts are left with forking the SPA or patching its private DOM.
+
+The first draft of this record added whole pages only. A survey of how other
+products open their admin turns up the same set of extension points in
+almost all of them. The CMS products were Strapi, Directus, Payload, Sanity,
+Contentful, Keystone, Decap, Tina and WordPress. The platforms were Shopify
+Admin UI extensions, VS Code, Grafana, Backstage, Atlassian Forge, Figma and
+the Keycloak admin console. The recurring points are:
+
+- pages with a navigation entry
+- record and list actions
+- record side panels
+- field widgets
+- dashboard widgets
+- settings pages
+- server endpoints
+
+The survey also turns up five lessons that bear on this design:
+
+1. **Only a narrow, typed surface survives major versions.** Every product
+   that exposed its internal context or helper packages broke all its plugins
+   at the next major: Strapi's helper-plugin, Sanity's Parts, Payload 2→3,
+   Decap's React pin. Contentful's location-scoped SDK and Backstage's typed
+   data refs aged well.
+2. **Declare in data, run in code.** The extension says *what* attaches
+   *where* as data. Code supplies only the behavior. Grafana had to retrofit a
+   static mirror of its imperative `addLink` calls before it could index,
+   validate or lazy-load extensions. Declarations can also be validated and
+   diffed before anything runs. That matters here because agents author and
+   deploy Mantle projects.
+3. **Typed contribution points beat free-form injection zones.** Strapi 5 and
+   Sanity steer integrators to typed actions with a position and a dialog
+   kind. Strapi now marks its free zones internal.
+4. **Navigation visibility is not authorization.** Strapi, Payload and
+   Directus all warn about this. Every extension route has to check the
+   caller on the server.
+5. **Same-origin code has no security boundary.** That is acceptable for code
+   the host installs and trusts. Untrusted third-party code needs an iframe
+   (Contentful, Forge Custom UI) or remote rendering (Shopify). The contract
+   should allow such an isolation tier later without changing.
+
+## Decision
+
+### 1. One declaration per extension, from the project or the host
+
+`createAdminSurface` accepts `extensions: AdminExtension[]`. Each extension
+pairs a declaration, which is plain data, with server handlers, which are
+code:
+
+```ts
+{
+  apiVersion: 1,
+  id: 'access',                        // kebab-case, unique, immutable once deployed
+  title: { en: 'Access', 'zh-TW': '存取權限' },
+  source: ACCESS_MODULE,               // the module's code; Admin serves it at {basePath}/extensions/access.js
+  // or, served by the host instead: module: '/assets/access/admin.js', integrity?: 'sha384-…'
+  contributes: {
+    pages:    [{ id, title, role, nav: { group: 'more' | 'settings', order? } }],
+    settings: [{ id, title, role, schema }],          // JSON Schema form, no client code
+    actions:  [{ id, title, role, target, presentation, destructive?, when? }],
+    panels:   [{ id, title, role, target, when? }],
+    fields:   [{ id, target, when?, optionsSchema? }],
+  },
+  handlers: {
+    api?(request, { caller, extension, path }): Promise<Response | null>,
+    settings?: { [id]: { load(caller), save(caller, value) } },
+    actions?:  { [id]: { run(caller, { record?, selection?, schema? }) } },
+  },
+}
+```
+
+### 1a. Projects author extensions; hosts may add their own
+
+Extensions are not a host-only feature. An agent customizing a project's Admin
+is the main author:
+
+- A project exports `adminExtensions: AdminExtension[]`. For a new project the
+  generated preset writes `src/admin-extensions.ts` and passes it to
+  `createAdminSurface`; the preset is written once, so an existing
+  `src/service.ts` wires it by hand. A host that builds Admin itself (for example a hosted
+  platform) reads the same export and appends its own extensions.
+- Extension ids are one namespace per Admin. A host extension whose id
+  collides with a project extension fails construction, so a project can
+  never shadow a host page, and the reverse.
+- A module needs no build step: Admin's import map provides React, the kit and
+  the extension helper (§4), so plain ESM works. `source` lets Admin serve the
+  module itself, so a project needs no static-file setup; Admin computes its
+  integrity. The same project shows the same extensions locally and when
+  deployed; a host only adds.
+
+**Trust.** A project extension's module runs in Admin's origin with the
+viewer's session. That gives it no more power than the project already has:
+whoever can deploy the project already controls its server code, its
+handlers and its storage. Two rules keep that equivalence true:
+
+- Host extension routes reachable from a project's Admin origin must act only
+  on that project. Anything wider (an organization console, other projects)
+  lives on a different origin, so a project module never holds its session.
+- A host that restricts what some staff may do inside a project (fine-grained
+  policies) must treat the right to deploy as full trust in that project, and
+  govern deployment separately.
+
+Contributions and their targets (§1b covers how manifests use them):
+
+| Contribution | Targets (`/v1`) | Client code |
+| --- | --- | --- |
+| page | its own route `/admin/x/{extension}/{page}`; in navigation when it declares `nav` | a renderer |
+| settings | its own route `/admin/x/{extension}/{id}`, always in navigation | none. Admin renders `schema` (the form subset) with its form; `load` and `save` run on the server |
+| action | `record/v1` (record header), `list.selection/v1` (bulk), `list.toolbar/v1` | `presentation: 'run' \| 'confirm'` needs none (the server `run` is called). `'dialog'` mounts client code in an Admin dialog |
+| panel | `record.sidebar/v1`, `home/v1` | a renderer |
+| field | `field.input/v1`, `field.cell/v1` | a renderer |
+
+`when` is a closed predicate over names only: `{ schema?: string[], field?:
+string[], format?: string[] }`. It contains no expressions and no record
+values, so the server can evaluate it.
+
+`role` is the minimum staff role, the same vocabulary as `requires.auth`. It is
+required except on `fields`, where it defaults to `contributor`.
+
+### 1b. Manifests pick contributions through `uiSchema`
+
+There are two ways to attach a contribution. Both stay:
+
+- **From the manifest.** `uiSchema` already chooses Admin presentation
+  (`fields.<name>.widget: textarea`, `list.columns`, `collectionAction`).
+  It may also name a contribution as `<extension>/<contribution>`:
+
+  ```yaml
+  # Schema products
+  uiSchema:
+    fields:
+      color: { widget: brand-kit/color, options: { palette: brand } }
+      notes: { widget: textarea }
+    list:
+      cells: { color: brand-kit/swatch }       # field.cell/v1
+    panels: [brand-kit/usage]                  # record.sidebar/v1
+  # Procedure reassign-order (uiSchema.fields.<name>.widget works the same)
+  # View sales-by-region
+  uiSchema:
+    list: { cells: { region: maps/region-badge } }
+  ```
+
+  - The binding sits next to the field it changes. An agent writes both in
+    one change, and a manifest review shows it.
+  - `options` is passed to the renderer as `ctx.options`. A contribution may
+    declare `optionsSchema` (the settings form subset). `options` is checked
+    against it, and a contribution without one refuses `options`.
+  - The target kind must match the key: `fields.*.widget` names a
+    `field.input/v1` contribution, `list.cells.*` a `field.cell/v1`
+    contribution, and `panels` a `record.sidebar/v1` contribution.
+- **From the extension.** `when: { schema, field, format }` attaches a
+  contribution everywhere it matches without touching manifests, for example
+  every field with `x-mcp-hint: money-minor`. This suits host extensions and
+  cross-cutting widgets.
+
+When both apply to one place, the manifest wins.
+
+**Validation.**
+- The manifest grammar checks the shape: `<extension>/<contribution>` with
+  kebab-case parts. `textarea` stays the one built-in widget.
+- Whether the named contribution exists, has the right target and accepts the
+  `options` is checked where the plan and the extensions meet:
+  - `createAdminSurface` fails construction with `UI_EXTENSION_UNKNOWN`,
+    `UI_EXTENSION_TARGET` or `UI_EXTENSION_OPTIONS`.
+  - `checkPlanUiExtensions(plan, extensions)` is exported, so a deploy step or
+    a test can run the same check before the service starts.
+
+**Who may be named.** A manifest should name only the project's own
+extensions, so the project renders the same locally and when deployed; a host
+attaches its contributions with `when` instead. Core cannot enforce this: the
+extensions reach `createAdminSurface` as one list with no provenance, so it
+checks existence, target and options, not ownership. A host that must keep
+manifests from naming its contributions checks the plan's names
+(`planUiExtensionRefs`) against its own ids before it starts Admin.
+
+**A named widget is a decision.** When `uiSchema.fields.<name>.widget` names
+any widget, `textarea` included, a matching `when` does not replace it; a
+contribution the viewer's role does not reach falls back to Admin's own
+control, not to `when`.
+
+**Effect.** `uiSchema` stays presentation only. It never changes validation,
+MCP schemas or authorization. The field's JSON Schema still validates what a
+widget sends.
+
+### 2. The server decides what a caller sees, and checks again on use
+
+- `GET /admin/api/site` (and bootstrap's `site`) returns the contributions
+  the caller's role reaches, with their declarations only. Handlers and
+  `integrity` are not sent.
+- Every extension route checks a signed-in staff session and the
+  contribution's role before it calls the host:
+  - `{basePath}/api/x/{extension}/settings/{id}`: `GET` → `load`, `PATCH { value }` → `save`
+  - `{basePath}/api/x/{extension}/actions/{id}`: `POST` → `run`, with `{ record }`, `{ selection }` or `{ schema }` for the action's target; `when.schema` is enforced here too
+  - `{basePath}/api/x/{extension}/api/{path}` → `api`, for the extension's lowest contribution role
+  - `GET {basePath}/extensions/{id}.js` → a `source` extension's module, for the same role
+- `save` input is validated against `schema` before the host sees it (400 with
+  `error.fields` otherwise).
+- `null` answers 404. Answers are `no-store` unless the host sets
+  `cache-control`. Cross-site mutation protection is the `withCaller`
+  wrapper's, as for every Admin route.
+- The checks above are the minimum. Finer authorization is the host's, inside
+  its handlers.
+
+### 3. Client modules supply renderers keyed by contribution id
+
+```ts
+import { defineAdminExtension } from '@aotter/mantle-ui/extension'
+
+export default defineAdminExtension({
+  pages:   { overview: (element, ctx) => cleanup },
+  actions: { 'reassign': (element, ctx) => cleanup },   // dialog presentation only
+  panels:  { 'history': (element, ctx) => cleanup },
+  fields:  { 'color': (element, ctx) => ({ update(next) {}, unmount() {} }) },
+})
+```
+
+A renderer returns nothing, a cleanup, or `{ update, unmount }`. With `update`,
+Admin passes later contexts (a new value, a new language) in place instead of
+mounting again; a field value the renderer reported itself never remounts it.
+
+- Admin imports `module` once, when a contribution that needs it is first
+  shown, and calls the renderer for that contribution.
+- A renderer for an undeclared contribution is ignored. A declared
+  contribution without a renderer shows an error in its place.
+- The context is serializable and typed per target. It holds `{ extension,
+  contribution, apiBase, language, theme, caller: { role } }` plus:
+  - `record: { schema, id, version }` for record targets
+  - `selection: { schema, ids }` for list targets
+  - `field: { schema, name, value, readOnly, property }` for field targets,
+    and `options` from `uiSchema`; `field.input/v1` also gets `onChange(value)`
+- A small `host` object offers `navigate(path)`, `notify(message)` and
+  `close()` for dialogs.
+- Admin offers no other SPA API. This is a supported surface, not a sandbox:
+  the module is trusted same-origin code (§5).
+- Each mount gets a fresh element. A renderer that resolves after its mount was
+  replaced writes into a detached node, never over the current one.
+
+### 4. Shared dependencies come from Admin
+
+- Admin's HTML declares an import map for `react`, `react/jsx-runtime`,
+  `react-dom`, `react-dom/client`, `@aotter/mantle-ui/kit` and
+  `@aotter/mantle-ui/extension`, served beside the shell. The React entries
+  re-export Admin's own instance; the kit and the helper are real modules
+  that import React through the same map, and the kit's stylesheet loads with
+  the first extension.
+- Extension modules use these specifiers directly (or mark them external when
+  bundling). They share Admin's single React and keep its look, theme and
+  accessibility.
+- The kit and the extension helper are the whole public UI surface. The shell
+  stays private (ADR-lite 909).
+
+### 5. Trust tier
+
+- Extensions are trusted host code. They run in Admin's origin with Admin's
+  privileges, and Core does not sandbox them.
+- `module` must be a same-origin path, so Admin keeps its existing CSP and
+  framing policy.
+- `integrity` (given for `module`, computed for `source`) goes into the
+  shell's import map, so the browser enforces it on import.
+- An isolated tier for untrusted extensions is reserved and is not part of
+  this decision. Because contexts are serializable and the UI surface is the
+  kit, an iframe or remote-rendering tier can reuse this declaration format
+  unchanged.
+
+### 6. Stability and tooling
+
+- `apiVersion` and the `/v1` target names version the contract. Within a
+  version, changes are additive only. A breaking change adds `/v2`, and both
+  run side by side through a deprecation window.
+- Construction validates every declaration and fails on:
+  - a bad or duplicate id
+  - an unknown target or `apiVersion`
+  - a non-same-origin `module`, or both `module` and `source`
+  - a contribution that needs code when there is neither
+  - a settings `schema` outside the form subset
+- Core exports the declaration's JSON Schema, so tooling and agents can check
+  a declaration without running it.
+- Core also exports `diffAdminExtensions(previous, next)`. It reports added
+  and removed contributions, role changes and module changes, for review
+  screens.
+
+## Non-goals
+
+- Replacing the shell, navigation component or layout.
+- Free-form injection into arbitrary DOM.
+- A marketplace or untrusted third-party extensions (reserved tier, above).
+- Server-side sandboxing of handlers. They are host code in the host's
+  process.
+- Declaring extensions in the YAML manifest. They live in the project's
+  service module (TypeScript), so the four-atom grammar does not change.
+
+## Consequences
+
+- Projects and hosts add pages, settings, actions, panels and field widgets
+  without forking the SPA, and the SPA stays one build. Without
+  `extensions`, nothing changes.
+- An agent can customize a project's Admin with a small module and a
+  declaration that tooling validates and diffs before deploy. A `uiSchema`
+  line in the manifest binds it to a field, a list cell or a record panel.
+- The `uiSchema` vocabulary widens: `fields.<name>.widget` accepts
+  `<extension>/<contribution>` beside `textarea`, with `options`; Schemas gain
+  `list.cells` and `panels`; staff Views gain `list.cells`. This record is the
+  grammar decision CONTRIBUTING requires for new keys: the name's shape is
+  closed and checked at generate time (`SCHEMA_UI_INVALID`,
+  `VIEW_UI_INVALID`), and its existence at construction
+  (`UI_EXTENSION_UNKNOWN`, `UI_EXTENSION_TARGET`, `UI_EXTENSION_OPTIONS`).
+- Settings pages need no client code at all. This covers most host
+  configuration screens and is the easiest kind for an agent to author and
+  review.
+- Admin takes on an import map and the `@aotter/mantle-ui/extension` entry.
+- The first draft's `extensions: { pages, api }` is replaced before any
+  release; it was never published.

package/docs/examples/commerce-inventory.md

@@ -321,7 +321,24 @@ Points worth noticing:
 - **`expired-orders` is `internal`:** callable only through
   `ctx.store.view` or `runtime.store`. SQL compares `expiresAt` with `now()`.
 - **`picking-list`** unnests order lines with `json_each`, the one comma join
-  the dialect allows.
+  the D1 dialect allows. This example's SQL is D1 (SQLite) SQL. On PostgreSQL
+  the same View reads:
+
+  ```sql
+  SELECT o.orderToken, o.customerName, o.shippingAddress,
+         item.value ->> 'productSlug' AS "productSlug",
+         item.value ->> 'title' AS "productTitle",
+         item.value ->> 'quantity' AS quantity
+  FROM orders o, jsonb_array_elements(o.items) WITH ORDINALITY AS item(value, n)
+  WHERE o.orderStatus = 'paid'
+  ORDER BY o.created_at, item.n LIMIT 200
+  ```
+
+  `jsonb_array_elements_text(o.items) WITH ORDINALITY AS j(value, n)` is the
+  form for text elements. A sorted View over a row source needs the alias and
+  `WITH ORDINALITY`; Mantle pages by `n`. The
+  [rewrite table](../handbook/concepts/runtime-and-adapters.md#the-postgresql-dialect)
+  lists the other SQLite spellings PostgreSQL refuses.
 
 ## Handlers
 

package/docs/examples/reference-service/package.json

@@ -8,8 +8,8 @@
     "check": "mantle generate && mantle generate --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.4",
-    "@aotter/mantle-ui": "0.2.0-alpha.4",
+    "@aotter/mantle": "0.2.0-alpha.6",
+    "@aotter/mantle-ui": "0.2.0-alpha.6",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/mcp": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",

package/docs/handbook/cloudflare/authentication.md

@@ -35,9 +35,9 @@ preset does); without Admin it is `/oauth/consent`, the plain page
 then `createCallerResolver(auth, { jwtBearer: { audience: `${origin}/mcp`, scopes: ["mcp"] } })`,
 `createAuthRoutes(auth, { resolver })` and an `AdminIdentity` over the auth's
 own methods. With dialect `postgres` the preset passes `database:
-pgPool(connect), driver: pgDatabaseDriver(connect)` over Hyperdrive; host `bun`
-passes `bunAuthDatabase(sql)` and `bunDatabaseDriver(sql)` (or the bun:sqlite
-`Database` and `bunSqliteDriver(db)`), with `ipAddressHeaders:
+pgPool(connect), driver: pgDatabaseDriver(connect)` on both hosts (Hyperdrive on
+`cloudflare`, a `pg.Pool` on `bun`); host `bun` over SQLite passes the bun:sqlite
+`Database` and `bunSqliteDriver(db)`, with `ipAddressHeaders:
 ["x-mantle-client-ip"]`, which its entry sets from the socket.
 
 ### Local sign-in

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

@@ -16,7 +16,10 @@ pnpm exec wrangler deploy
 
 With dialect `postgres`, create the Hyperdrive config instead of the D1
 database (`pnpm exec wrangler hyperdrive create my-service --caching-disabled
---connection-string=…`) and copy its id into `hyperdrive[0].id`.
+--connection-string=…`) and copy its id into `hyperdrive[0].id`. Give the
+role a statement limit and UTC, which boot checks (`ALTER ROLE app SET
+statement_timeout = '10s'; ALTER ROLE app SET TimeZone = 'UTC'`); the boot
+error names any other setting to change.
 
 Set `PUBLIC_ORIGIN` in `wrangler.jsonc` `vars` to the deployed origin, and
 replace the console email sender first

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

@@ -1,5 +1,5 @@
 ---
-description: Media uploads in Mantle 0.2.0 on Cloudflare R2 — site media purposes, r2MediaStorage, wiring Admin's media routes, the presigned upload flow, and what to store in a Schema.
+description: Media uploads in Mantle 0.2.0 on Cloudflare R2 — site media purposes, r2MediaStorage, wiring Admin and staff MCP media tools, the presigned upload flow, and what to store in a Schema.
 ---
 # Media uploads with R2
 
@@ -37,7 +37,7 @@ export const mantle = createMantle(service, {
   } }),
 });
 
-// in mount(): the media storage, handed to Admin
+// in mount(): one media storage, shared by Admin and staff MCP
 const media = r2MediaStorage({
   bucket: env.MEDIA,
   signer: new AwsClient({ accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY, region: "auto", service: "s3" }),
@@ -45,11 +45,16 @@ const media = r2MediaStorage({
   publicBase: env.MEDIA_PUBLIC_BASE,
 });
 const admin = guard(createAdminSurface(runtime, { basePath: "/admin", media, /* …the generated options… */ }));
+const staffMcp = guard(createMcpSurface(runtime, {
+  basePath: "/mcp/staff", surface: "staff", media, resourceMetadata,
+}), { resourceMetadata });
 ```
 
 `aws4fetch` is the application's dependency; Mantle only calls its `sign`.
-Without both `media` and site defaults, every media route answers 501
-`MEDIA_NOT_CONFIGURED`.
+Without both `media` and site defaults, every Admin media route answers 501
+`MEDIA_NOT_CONFIGURED`, and MCP advertises no media tools. Public MCP never
+advertises media tools. The generated preset does not invent bucket credentials;
+add the same explicit adapter to its application-owned service composition.
 
 ## 3. The upload flow
 
@@ -75,16 +80,62 @@ retried.
 Optimize images where they are made (in the browser or the agent), and upload
 the variants; Mantle does not transform images.
 
+## Staff MCP upload flow
+
+Connect the tenant's `/mcp/staff` using its own identity, with the `mcp` scope
+and `editor` or `owner` role. Cloud project membership is not tenant staff.
+The verified role is checked again on every call, as in Admin.
+
+1. Call `get_media_upload_policy` to read the declared purpose MIME slots and
+   byte caps. Obtain the chat attachment bytes in the agent environment and
+   optimize/encode the required variants there; do not ask the user to run a
+   terminal command.
+2. Call `create_media_upload` with the same body as Admin's create endpoint.
+3. PUT every variant's actual bytes to its capability URL using all returned
+   `requiredHeaders`, before `expiresAt`. Bytes never travel as base64 MCP JSON.
+4. Call `commit_media_upload` with `{ uploadGroupId, alt?, caption? }`.
+   Verify success before using the returned permanent asset `id`.
+5. Pass that ID to the application's content Procedure. Images are content
+   operations, not a new Cloud source build or deploy.
+
+`list_media_assets`, `get_media_asset`, `update_media_asset` (`id`, `alt?`,
+`caption?`) and `delete_media_asset` (`id`) share the same library and editor
+permission as Admin. A create refusal publishes nothing. Expired groups need
+new capabilities; partial delete failures can retry the same ID. Keep upload
+capabilities out of logs and persisted content.
+
 ## Storing media in a Schema
 
-Store the asset's `publicUrl` (or its `id`) in a string field and mark it:
+Store the committed asset ID, not its temporary capability URL:
 
 ```yaml
-cover: { type: string, x-mcp-hint: media-image }
+coverAssetId:
+  type: string
+  x-mantle-ref: media_assets
+  x-mcp-hint: media-image
+```
+
+The string reference defaults to the native library's `id` and enables Admin's
+existing MediaPicker. The hint alone does not enable the picker. Do not author
+a replacement `media_assets` Schema: the site's library owns that table.
+
+An asset ID is not an image URL. Resolve it with the existing site library in
+an application-owned frontend handler, then use a variant's `publicUrl`:
+
+```ts
+// The same media adapter used by Admin and staff MCP.
+const asset = await runtime.site!.media(media).get(post.coverAssetId);
+const primary = asset.variants.find((variant) => variant.role === "primary")!;
+// Render primary.publicUrl as the image src; asset.alt as its alt text.
 ```
 
-The hint tells Admin and agents what the field holds. No MCP tool uploads
-media in 0.2.0; an agent uploads through Admin's API with a staff session.
+A public frontend route must enforce the content's publication and visibility
+before resolving its media. Return only public URLs/alt/variant metadata it
+needs; never expose upload capabilities or a staff MCP credential. Native site
+product tables are not manifest Store tables: do not query `media_assets` in
+View/Procedure SQL or widen the SQL grammar to resolve them. A custom handler
+can use the existing library capability while its content reads remain
+caller-scoped.
 
 ## Stale uploads
 

package/docs/handbook/concepts/mcp-and-agents.md

@@ -17,13 +17,19 @@ Both run behind `withCaller(resolver, …)`, so a tool sees the same
 
 ## Which tools
 
-A surface lists exactly:
+A surface lists these plan tools:
 
 - each Procedure bound by a Trigger `{ kind: mcp, surface: <this surface> }`,
   named after the Procedure in snake case (`place-order` is `place_order`);
 - each View whose `surface` is this one, as a read-only tool with the View's
   `input` plus `limit` and `cursor`.
 
+A configured staff surface also offers optional media product tools (see
+[media upload](../cloudflare/media-r2.md)); these delegate to the same site
+library as Admin. Without site defaults or media storage they are absent;
+public MCP never exposes them. A name collision with a plan tool fails at
+assembly rather than replacing either tool.
+
 A Schema is never a tool: there are no generated create, update or publish
 record tools. To let an agent change rows, declare a Procedure and an `mcp`
 Trigger for it.
@@ -74,13 +80,15 @@ const staffMcp = withCaller(resolver,
   { resourceMetadata });
 ```
 
-`resourceMetadata` is the `/mcp` metadata URL. The staff surface admits only
+`resourceMetadata` is the `/mcp` metadata URL. Pass the same `media` adapter as Admin to enable media tools. They require
+`editor` or `owner`; a contributor can discover them but cannot call them.
+The staff surface admits only
 callers with a staff role, and the role is read on every request.
 
 ## WebMCP in Admin
 
-`GET /admin/api/webmcp` returns `{ tools, routes }`: the staff tools (what
-`/mcp/staff` lists, in its default locale) and, for each tool, the Admin page
+`GET /admin/api/webmcp` returns `{ tools, routes }`: the manifest staff tools (in its default locale; optional native media tools
+use the existing Admin media REST routes) and, for each tool, the Admin page
 it belongs to (a Procedure with a `target` maps to its collection, a View to its
 report). A browser agent in the console registers these tools and calls one
 with `POST /admin/api/webmcp/<tool>` and the input as the JSON body. Admin runs