@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/handbook/cloudflare/chatgpt-sites.md

@@ -1,29 +1,118 @@
 ---
-description: "Mantle on ChatGPT Sites now has its own integration guide."
+description: Run a Mantle 0.2.0 service on ChatGPT Sites — the Cloudflare preset with a custom identity over Sites sign-in, D1 schema delivery, R2 media, MCP paths, and what to verify after each publish.
 ---
 # Mantle on ChatGPT Sites
 
-ChatGPT Sites has a dedicated section in the Mantle handbook. Start with
-[Mantle on ChatGPT Sites](../chatgpt-sites/index.md) for installation, supported
-capabilities, and your first published article. This page preserves earlier
-links to the host checklist.
+A ChatGPT Site runs a Cloudflare Worker with D1 and R2 bindings, and Sites owns
+sign-in and deployment. Mantle runs there as the ordinary Cloudflare preset
+with `identity: custom`: Sites authenticates the person, and your
+`src/identity.ts` turns that into a Mantle `Caller`. There is no Sites option in
+`mantle generate` and no Sites code in Core.
 
-## First deployment
+This page is a guide, not a runnable example. Inspect the Site's actual
+hosting configuration and bindings before relying on any detail here, and
+verify every claim on the deployed Site.
 
-See [the host deployment checklist](../chatgpt-sites/host-reference.md#first-deployment).
+## Generate
 
-## Media with only an R2 binding
+```sh
+pnpm exec mantle generate --identity custom --features mcp,admin,web
+```
 
-See [R2 media integration](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
+Keep the application outside the Mantle SDK checkout, pin every
+`@aotter/mantle*` package to one exact version, and publish through Sites; do
+not `wrangler deploy` a Site's Worker yourself.
 
-## Remote MCP is a separate gate
+## Identity: Sites sign-in as a `CallerResolver`
 
-See [MCP support and authentication](../chatgpt-sites/host-reference.md#remote-mcp-is-a-separate-gate).
+Sites' ingress authenticates the visitor and forwards the identity in
+`oai-authenticated-user-*` headers. Trust them **only** when every request
+reaches the Worker through that ingress, which strips caller-supplied copies;
+never expose the Worker on another route.
 
-## Capability boundaries
+Staff roles are the application's: keep them in your own table (here
+`sites_users (id, email, role)`, created by your own migration) and read them
+on every request. A Site viewer is not automatically a Mantle editor.
 
-See [host capability boundaries](../chatgpt-sites/host-reference.md#capability-boundaries).
+```ts
+// src/identity.ts
+import type { CallerResolver } from "@aotter/mantle";
 
-## Source
+export function sitesResolver(db: D1Database, ownerEmail: string | undefined): CallerResolver {
+  return async (request) => {
+    const sub = request.headers.get("oai-authenticated-user-id");
+    const email = request.headers.get("oai-authenticated-user-email")?.trim().toLowerCase();
+    if (!sub) return { caller: { kind: "anonymous" } };
+    if (!email || sub.length > 512) return { invalid: true };
+    const subject = `chatgpt:${sub}`; // namespaced: unique across issuers, never the email
+    await db.prepare("INSERT INTO sites_users (id, email, role) VALUES (?1, ?2, ?3) ON CONFLICT (id) DO NOTHING")
+      .bind(subject, email, email === ownerEmail?.trim().toLowerCase() ? "owner" : null).run();
+    const row = await db.prepare("SELECT role FROM sites_users WHERE id = ?1").bind(subject).first<{ role: "owner" | "editor" | "contributor" | null }>();
+    return { caller: { kind: "user", subject, role: row?.role ?? null, scopes: [], credential: "session", credentialId: null, clientId: null } };
+  };
+}
+```
 
-See [integration sources](../chatgpt-sites/host-reference.md#source).
+In `src/service.ts`, use `sitesResolver(env.DB, env.OWNER_EMAIL)` where the
+preset uses `resolveCaller`. The email is used only to recognize the first
+owner. To manage staff from Admin, implement `AdminIdentity`'s `directory` and
+`roles` facets (from `@aotter/mantle/admin`) over `sites_users` and pass it as
+`identity`; without it Admin hides user management.
+
+A Sites session is a browser session. It is not an OAuth bearer token, so it
+does not authenticate a remote MCP client.
+
+## Storage on D1
+
+Boot converges Schema tables to the plan. If the Site applies schema changes
+through migration files instead of letting the Worker run DDL, deliver
+Mantle's SQL that way:
+
+1. Point `mantle generate --check --database <file>` at a local SQLite file
+   in the same state as the Site's database (for example local D1 under
+   `.wrangler/state/v3/d1/`, migrated the same way).
+2. Put the printed SQL into a new migration in the Site's migration directory,
+   together with your own tables (`sites_users`).
+3. Publish; boot then finds the database converged and applies nothing.
+
+Repeat for each plan change. A blocked change is resolved by hand, as in
+[Deploy and operate](./deploy-and-operate.md#resolving-a-blocked-change).
+
+## Media
+
+`r2MediaStorage` presigns uploads with R2's S3 API, which needs an S3
+endpoint and an API key pair. With only an R2 binding, implement the
+`MediaStorage` port yourself (`createUpload`, `commitUpload`, `deleteObject`)
+and add two routes to your service:
+
+- an authenticated, same-origin `PUT` route that checks the pending upload,
+  the declared type and the exact size before `bucket.put`;
+- a public `GET` route that serves only committed variants, with a safe type
+  and `nosniff`.
+
+Pass it as `media` to `createAdminSurface` and declare media purposes in the
+site defaults ([Media uploads with R2](./media-r2.md)).
+
+## MCP paths
+
+Try `/mcp` first. If the Site does not route it to the Worker, mount the
+public surface at another path you own (`createMcpSurface(runtime, { basePath:
+"/agent/mcp", surface: "public" })`) and report the real paths through
+`createAdminSurface`'s `site: { mcpEndpoints }`. Admin and its browser tools
+work with the Sites session. A remote staff MCP client (`/mcp/staff`)
+needs a real OAuth authorization server and bearer verification in your
+resolver; a forwarded identity header is not one.
+
+## Verify after every publish
+
+- Anonymous: a public View, an HTTP Trigger, `/mcp` (or your path)
+  `initialize` and `tools/list` when a public tool may be called anonymously;
+  when every public tool `requires` a caller, they answer 401 with a
+  `WWW-Authenticate` challenge instead.
+- The owner: `GET /admin/api/me` is `owner`; a staff View and an operation.
+- A second account: no Admin access until granted; revoking the role takes
+  effect on the next request.
+- Every binding the service uses, on the deployed Site, not only locally.
+
+Sites lists financial transactions among its unsupported uses; a working
+sandbox flow is not support for live payments.

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

@@ -1,104 +1,110 @@
 ---
-description: Production checklist, the check loop, deploy and post-deploy probes, day-to-day content operations, and version pins.
+description: Deploy a Mantle 0.2.0 service to Cloudflare Workers, change Schemas safely with storage convergence, resolve a blocked change, and operate schedules, expiry and the boot handshake.
 ---
 # Deploy and operate
 
-This page is the production checklist for a Mantle Worker on Cloudflare: what to pin and configure, which checks to run before `wrangler deploy`, how to verify a deployment, how content is operated afterwards, and how to move versions.
+## First deploy
 
-## Before the first deploy
+```sh
+pnpm exec mantle generate --check          # nothing stale
+pnpm exec tsc --noEmit
+pnpm exec wrangler d1 create my-service     # copy database_id into wrangler.jsonc's d1_databases[0]
+pnpm exec wrangler secret put BETTER_AUTH_SECRET   # identity mantle
+pnpm exec wrangler secret put ADMIN_EMAIL
+pnpm exec wrangler deploy
+```
 
-- Pin every `@aotter/mantle*` package to one exact version and commit the lockfile. Install with `pnpm install --frozen-lockfile` (or `npm ci`) from then on. See [Project and CLI](../start/project-and-cli.md).
-- Set `PUBLIC_ORIGIN` to the real HTTPS origin, without a trailing slash. It drives canonical URLs, `.md` mirrors, `llms.txt`, the MCP resource and the OAuth callback. If a static documentation build also emits absolute URLs, give it the same value.
-- Set the production D1 `database_id` (and `account_id` if your deployment needs it) in `wrangler.jsonc`. A local `database_name` is not a production identifier, and local D1 is not production data.
-- Choose production Auth: replace local console email delivery with a real `EmailSender`, or configure `MANTLE_AUTH_MODE` for GitHub OAuth or hosted Auth. Store secrets with `wrangler secret put`. See [Authentication](./authentication.md).
-- Keep `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
-- Enable observability:
+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`.
 
-```jsonc
-"observability": { "enabled": true, "logs": { "head_sampling_rate": 1 } },
-"upload_source_maps": true
-```
+Set `PUBLIC_ORIGIN` in `wrangler.jsonc` `vars` to the deployed origin, and
+replace the console email sender first
+([Authentication](./authentication.md#production)). The first request boots
+the runtime, which creates every table the plan needs on the empty database.
 
-## The check loop
+Deploying anywhere is your choice: Cloudflare and Bun have generated presets,
+`host: none` composes any other, and you may always self-host. Mantle Cloud is one option, never a
+requirement.
 
-Run the project's `check` script before every deploy. The minimal reference chains:
+## Changing Schemas
 
-```sh
-mantle generate && mantle generate --check && mantle validate \
-  && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs
-```
+There are no migration files. Edit the manifests, run `mantle generate`, and
+deploy. The first request after a plan change compares the database with the
+plan:
 
-Add tests and the frontend build where the project has them, then confirm index coverage for every public View:
+- **Applied**: a new Schema table, a new field column, a new index, a new
+  unique index that existing rows satisfy, new `checks` and search triggers.
+- **Blocked** (`STORAGE_CHANGE_BLOCKED`, the service refuses to serve): a
+  unique index that existing rows break, a field whose type changed, an index
+  whose columns changed under the same name, an undeclared unique index.
+- **Kept, with a warning**: a column or non-unique index the plan no longer
+  declares. Nothing is dropped.
+
+Before deploying, see what boot will do against a local SQLite file, such as
+Wrangler's local D1 under `.wrangler/state/v3/d1/` after it has run the
+previous plan:
 
 ```sh
-pnpm exec mantle-harness indexes --require-public --format text
+pnpm exec mantle generate --check --database .wrangler/state/v3/d1/<…>.sqlite
 ```
 
-A required path fails on a required Schema-table scan, a temporary sort or an unindexed data-field predicate. Then dry-run and deploy:
+It prints the SQL boot would run, the undeclared differences as comments, or
+the blocked change (exit 1). It reads the file read-only. The dry run is the
+SQLite dialect's; PostgreSQL has none.
 
-This local SQLite check intentionally runs without planner statistics. Treat it
-as a conservative preflight; use post-deploy D1 metrics for production cost and
-latency claims.
+### Resolving a blocked change
 
-```sh
-wrangler deploy --dry-run
-wrangler deploy
-```
+Mantle verifies; you change. The diagnostic names the change and hints SQL
+that would reach the plan. For example, to make `email` unique when duplicates
+exist: remove the duplicates (with a Procedure run as the system caller, or
+`wrangler d1 execute`), then deploy again; boot creates the index. To rename a
+field: add the new field, copy the data with a Procedure or SQL, then drop the
+old field from the manifest (its column stays, unused). Never edit `_mantle_*`
+tables.
 
-## Post-deploy verification
+### Hosts that refuse DDL from the Worker
 
-Probe the deployed origin, not `wrangler dev`. Run only the probes for surfaces
-the application mounts and configures:
+If a host applies schema changes only through its own migration mechanism,
+take the SQL `mantle generate --check --database` prints and deliver it
+through that mechanism; boot then finds the database converged.
 
-| Probe | Expect |
-|---|---|
-| `GET /api/views/<public-view>` | `200`, `{ "ok": true, "data": { "rows": [...] } }` |
-| `GET /<locale>/<segment>/<slug>` and `GET /<locale>/<segment>/<slug>.md` | `200` HTML and Markdown for a published entry |
-| `GET /llms.txt`, `GET /sitemap.xml`, `GET /robots.txt` | `200` |
-| `GET /<locale>/<segment>/does-not-exist` | `404` from your `notFoundRenderer` |
-| `POST /mcp/staff` without credentials | `401` with `WWW-Authenticate`; `GET /mcp` is `405` |
-| `GET /admin` | Sign-in page; sign in with the `ADMIN_GITHUB_LOGIN` account |
+## Schedules
 
-Then check the cache: a second anonymous `GET` of a public page should show `cf-cache-status: HIT`; publish a change in Admin and the next request should be a `MISS`. Sample latency with:
+`wrangler.jsonc` `triggers.crons` holds the Cloudflare spelling of every
+enabled schedule Trigger. `mantle generate` warns when it drifts from the plan;
+update it by hand (the file is yours). Locally:
 
 ```sh
-pnpm exec mantle-harness http --base-url https://example.com \
-  --route recent=/api/views/recent-posts --route page=/en/posts/hello --rounds 20 --warmup 2
+pnpm exec wrangler dev --local --test-scheduled
+curl 'http://127.0.0.1:8787/__scheduled?cron=0+3+*+*+1'
 ```
 
-## Operating content
-
-Sign in to Admin with a staff account. Publishing collections (`lifecycle: publishing`) follow draft, publish, verify:
+The cron in the URL is the Cloudflare spelling.
 
-1. Create a draft with its title, slug, locale and body.
-2. Publish (`editor` or above). The write purges the deployment-scoped public cache tag.
-3. Open the public URL and its `.md` mirror. Drafts never appear on pages, mirrors, `llms.txt` or the sitemap; use `?preview=1` with a staff session to see one.
-4. Unpublish removes the entry from every public surface; the Admin delete action and the Staff MCP `archive_entry` tool retire it.
+## Expired rows
 
-Operational collections (`lifecycle: operational`) have no publish step; records are edited in place and do not purge the public cache. The same operations are available to agents through Staff MCP; see [MCP and agents](../concepts/mcp-and-agents.md).
+TTL hides expired rows at once. To delete them, call
+`ctx.store.sweepExpired({ collection, limit })` in a schedule Trigger's `ref`
+handler (the system caller's Store has it), or `runtime.store.sweepExpired` from
+your own maintenance route, page with `nextCursor`, and use
+`delete: false` to count first.
 
-Site settings split by owner. Brand, title and description seed once from `siteDefaults` and are then edited in Admin (`owner`); each edit purges the public cache. Origin, icons, locales and media purposes are code-owned and re-sync from `siteDefaults` on every boot, so change them in the Worker and redeploy. Analytics, pixels and search-engine verification are host chrome, not Core settings; see [Site chrome](./site-chrome.md) and [Site config](../reference/site-config.md).
+## The boot handshake
 
-## Changing versions
+`runtime.bootReport()` returns `{ fingerprint, coreVersion }`. Pass
+`expectedFingerprint` to `createMantle` to refuse booting any plan but the one
+you built (`PLAN_FINGERPRINT_MISMATCH`). The fingerprint is in
+`.mantle/generated/plan.json`; reformatting a manifest does not change it.
 
-Pin every selected `@aotter/mantle*` package to one exact version and keep them together. This handbook describes the snapshot in this source tree; use the docs that ship with the version you install.
+## Mantle Cloud
 
-1. Pin the new exact release for every selected package and update the lockfile through the package manager; review peer ranges.
-2. Keep application source, Worker/D1/KV identity, origins, auth mode and secrets.
-3. Run `mantle generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests.
-4. Test local routes and authorization, then deploy.
+Deploying a 0.2.0 service to Mantle Cloud needs Cloud's host protocol 3, which
+uploads the compiled plan and the service entry. Mantle Cloud does not accept
+0.2.0 services yet. The plugin's `mantle` skill and its helper script check
+the plan and the installed Core version so a project is ready when it does.
 
-Each Manifest Schema is a native table. Safe additive storage changes deploy online. Destructive changes — including any `uniqueIndexes` tuple add, remove, reorder or rewrite — are rejected; rebuild the instance and move required data outside Mantle. There is no in-product data-move workflow.
+## Moving data from 0.1.x
 
-## Source
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
-- [`docs/performance-harness.md`](../../../docs/performance-harness.md)
-- [`docs/examples/host-minimal-worker/README.md`](../../../docs/examples/host-minimal-worker/README.md)
-- [`docs/examples/host-minimal-worker/package.json`](../../../docs/examples/host-minimal-worker/package.json)
-- [`docs/examples/host-minimal-worker/wrangler.jsonc`](../../../docs/examples/host-minimal-worker/wrangler.jsonc)
-- [`docs/examples/host-minimal-worker/smoke.mjs`](../../../docs/examples/host-minimal-worker/smoke.mjs)
-- [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
+Give the 0.2.0 service a new database and import through
+`runtime.store`; `docs/upgrade-0.1-to-0.2.md` describes the steps.

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

@@ -1,216 +1,93 @@
 ---
-description: Enable staff media uploads on R2 — presigned PUT flow through Staff MCP, media purposes, wrangler config, commit cost and cleanup.
+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.
 ---
 # Media uploads with R2
 
-R2-backed media is an optional post-launch capability for Workers whose staff or agents need to upload images and files. This page covers the native Cloudflare direct-to-R2 flow, the configuration it needs, how a Schema references an asset, what a commit costs, and how to clean up. For ChatGPT Sites with an R2 binding but no S3 credentials, use [the same-origin Worker flow](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
+Media is optional. It needs three things in `src/service.ts`: site defaults
+with media purposes, an `r2MediaStorage`, and both passed where they belong.
+The bytes go from the uploader straight to R2; the Worker never proxies them.
 
-## When to enable it
+## 1. A public bucket and S3 credentials
 
-Turn this on only after the site already has a working deploy, staff auth configured, and a real need for staff-managed media. R2 setup may require billing, so it is deliberately not part of the first-deploy path. Everything on this page is inert until the bucket, credentials and at least one media purpose all exist.
+- An R2 bucket served publicly, from a custom domain or `pub-<hash>.r2.dev`.
+  That URL is `publicBase`.
+- An R2 API token with write access to the bucket, for presigning PUT URLs:
+  `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY` as Worker secrets.
+- A CORS rule on the bucket that allows `PUT` with `Content-Type` from your
+  Admin's origin, if a browser uploads.
 
-Media maintenance also needs an agent that can read local files, process images and make outbound `PUT` requests to `*.r2.cloudflarestorage.com`. A sandboxed agent without egress cannot finish the flow.
-
-## The upload flow
-
-```txt
-1. create_media_upload   staff MCP  -> purpose, variants, mime types, byte sizes
-2. Mantle                           -> signed upload URLs + required headers
-3. agent or browser                 -> PUT bytes directly to R2
-4. commit_media_upload   staff MCP  -> validate, stamp, save the asset row
-```
-
-Bytes travel from the agent to R2 over a signed URL; the Worker sees policy, not payload. Never pass image bytes or base64 payloads through MCP tool arguments — the tool dispatchers count streamed JSON bytes and return `413` above the 1 MiB control-plane limit. The Worker validates; the agent runtime does the file work.
-
-## Cloudflare setup
-
-```sh
-wrangler r2 bucket create <project>-media
-wrangler r2 bucket dev-url enable <project>-media
-```
-
-Then create an R2 S3 API token in the dashboard: open **R2**, open **Manage R2 API Tokens**, create an **Object Read & Write** token, and copy the Access Key ID and Secret Access Key.
-
-The R2 binding alone cannot issue presigned `PUT` URLs: presigning is an S3-protocol operation, so this **direct-to-R2 adapter** needs these credentials in addition to the binding. This is not a requirement of Mantle's `MediaStorage` port: a host may return an authenticated same-origin Worker `PUT` URL instead. Media tools appear whenever `mediaStorage` and a media purpose are bound, regardless of which transport the adapter uses.
-
-## Wrangler configuration
-
-```toml
-[vars]
-R2_ACCOUNT_ID = "<account-id>"
-MEDIA_PUBLIC_URL_BASE = "https://pub-<hash>.r2.dev"
-
-[[r2_buckets]]
-binding = "MEDIA_BUCKET"
-bucket_name = "<project>-media"
-```
-
-A `wrangler.jsonc` project writes the same binding as an `"r2_buckets"` array; see [Bindings and primitives](./bindings.md#r2-media-bucket-optional) for the JSON form and the matching `Env` fields.
-
-```sh
-wrangler secret put R2_ACCESS_KEY_ID
-wrangler secret put R2_SECRET_ACCESS_KEY
+```jsonc
+// wrangler.jsonc
+"r2_buckets": [{ "binding": "MEDIA", "bucket_name": "my-media" }],
+"vars": { "MEDIA_PUBLIC_BASE": "https://media.example.com", "R2_ENDPOINT": "https://my-media.<account>.r2.cloudflarestorage.com" }
 ```
 
-`MEDIA_PUBLIC_URL_BASE` is the origin public URLs are built from — the `r2.dev` development URL, or a custom domain in production. `R2_ACCOUNT_ID` builds the S3 endpoint, which is a different host from the public one.
-
-## Wiring `R2MediaStorage`
-
-Build the adapter from `env`, returning `undefined` when any part is missing so a half-configured environment degrades to no media rather than failing to boot:
+## 2. Wire it
 
 ```ts
-import { R2MediaStorage } from "@aotter/mantle/cloudflare";
 import { AwsClient } from "aws4fetch";
-
-function buildMediaStorage(env: Env) {
-  if (
-    !env.MEDIA_BUCKET ||
-    !env.R2_ACCOUNT_ID ||
-    !env.R2_ACCESS_KEY_ID ||
-    !env.R2_SECRET_ACCESS_KEY ||
-    !env.MEDIA_PUBLIC_URL_BASE
-  ) {
-    return undefined;
-  }
-
-  const s3 = new AwsClient({
-    accessKeyId: env.R2_ACCESS_KEY_ID,
-    secretAccessKey: env.R2_SECRET_ACCESS_KEY,
-    region: "auto",
-    service: "s3",
-  });
-
-  return new R2MediaStorage(
-    env.MEDIA_BUCKET,
-    s3,
-    `https://<project>-media.${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
-    env.MEDIA_PUBLIC_URL_BASE,
-  );
-}
-```
-
-Pass it through the `bindings` hook, spreading the conventional set:
-
-```ts
-export default createMantleWorker<Env>({
-  plan,
-  bindings: (env, conventional) => ({
-    ...conventional,
-    mediaStorage: buildMediaStorage(env),
-  }),
+import { d1Storage, r2MediaStorage } from "@aotter/mantle/cloudflare";
+
+// storage, with the purposes uploads may use
+export const mantle = createMantle(service, {
+  plan, schedules: true,
+  storage: (env) => d1Storage(env.DB, { site: {
+    title: "My site",
+    media: { purposes: [{ name: "cover", required: ["image/webp", "image/jpeg,image/png"], maxBytes: { "image/webp": 2_000_000, "image/jpeg": 2_000_000, "image/png": 2_000_000 } }] },
+  } }),
 });
-```
-
-`aws4fetch` is an application dependency; the adapter takes the signing client rather than embedding one. See [The conventional Worker](./conventional-worker.md#a-bindings-hook).
-
-## Declaring media purposes
 
-A purpose is the upload policy: which variants an asset must have, and how large each may be.
-
-```ts
-siteDefaults: {
-  media: {
-    purposes: [
-      {
-        name: "page-image",
-        required: ["image/jpeg,image/png", "image/webp", "image/avif"],
-        maxBytes: {
-          "image/jpeg": 5_000_000,
-          "image/png": 5_000_000,
-          "image/webp": 3_000_000,
-          "image/avif": 2_000_000,
-        },
-      },
-    ],
-  },
-},
+// in mount(): the media storage, handed to Admin
+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" }),
+  endpoint: env.R2_ENDPOINT,
+  publicBase: env.MEDIA_PUBLIC_BASE,
+});
+const admin = guard(createAdminSurface(runtime, { basePath: "/admin", media, /* …the generated options… */ }));
 ```
 
-`required` is slot-based, in the grammar of an `<input accept>` list. The example declares three slots: slot 0 takes exactly one fallback mime preserving source semantics (`image/jpeg` for opaque photos, `image/png` when alpha must survive), slot 1 a WebP variant, slot 2 an AVIF variant. That models a multi-variant `<picture>`. A narrower purpose may declare a single slot such as `["image/jpeg,image/png,image/webp,image/gif"]`, in which case the agent picks exactly one mime from that list and must not upload one variant per listed mime.
+`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`.
 
-Purpose names are slugs (`^[a-z0-9]+(-[a-z0-9]+)*$`), every slot must be non-empty, slots may not overlap on a mime, and every `maxBytes` key must be a mime some slot accepts with a positive value. Violations fail at boot. SVG uploads are rejected unless the Worker sets `mediaAllowSvg`. See [Site defaults and site_config](../reference/site-config.md).
+## 3. The upload flow
 
-The runtime emits the policy summary into the `create_media_upload` tool description, so an agent reads the contract straight from `tools/list` without an extra round trip.
+All through Admin's API, `editor` role or higher:
 
-## Tool visibility
+1. `POST /admin/api/media/uploads` with
+   `{ filename, purpose, variants: [{ mimeType, byteSize, role }], alt?, caption? }`.
+   The purpose's MIME slots and per-type byte caps are checked here, and exactly one variant must be `role: "primary"`. The answer is
+   `{ uploadGroupId, capabilities: [{ role, mimeType, method: "PUT", uploadUrl, requiredHeaders }], expiresAt }`.
+2. `PUT` each variant's bytes to its `uploadUrl` with its `requiredHeaders`.
+3. `POST /admin/api/media/uploads/{uploadGroupId}/commit` (optionally with
+   `{ alt, caption }`). Commit checks every stored object's type and size,
+   then copies each to a public key no upload URL can reach. A rejected group
+   publishes nothing and its upload objects are deleted. An expired or unknown
+   group is 410 `MEDIA_UPLOAD_EXPIRED`.
 
-`create_media_upload` and `commit_media_upload` are registered only when **both** hold:
+The committed asset is `{ id, variants: [{ role, mimeType, publicUrl, storageKey, byteSize }], alt?, caption?, createdAt }`.
+`GET /admin/api/media` lists assets (`search`, `limit`, `cursor`); `GET`,
+`PATCH` (`alt`, `caption`) and `DELETE /admin/api/media/{id}` manage one.
+Delete removes the objects first, then the row, so a partial failure can be
+retried.
 
-- `bindings.mediaStorage` is set;
-- `siteDefaults.media.purposes` contains at least one purpose.
+Optimize images where they are made (in the browser or the agent), and upload
+the variants; Mantle does not transform images.
 
-If either is missing the tools never appear in `tools/list`. That is the intended diagnostic: an agent that cannot see the tools is looking at a deployment where media is not configured, not at a permissions problem. A call that reaches a runtime without media storage answers `MEDIA_NOT_CONFIGURED`.
+## Storing media in a Schema
 
-## Referencing an asset from a Schema
-
-Entries store asset ids, not URLs. Mark the field with both existing v0.1 grammar extensions:
+Store the asset's `publicUrl` (or its `id`) in a string field and mark it:
 
 ```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: pages
-spec:
-  title: Pages
-  schema:
-    type: object
-    additionalProperties: false
-    required: [slug, title]
-    properties:
-      slug: { type: string, pattern: "^[a-z0-9-]+$" }
-      title: { type: string, minLength: 1 }
-      coverAssetId:
-        type: string
-        x-mantle-ref: media_assets
-        x-mcp-hint: media-image
+cover: { type: string, x-mcp-hint: media-image }
 ```
 
-`x-mantle-ref: media_assets` marks the string as an id in the media asset collection, which is what makes Admin show a media picker instead of a text box. `x-mcp-hint: media-image` tells an MCP client the field expects an image asset. Neither key is validated as a foreign key; they are informational. At render time, resolve ids to their variants with `runtime.media.resolve(id)` or `resolveMany(ids)`, which batches a render pass into one database round trip. No new manifest keys are involved; see [Schema](../reference/schema.md).
-
-## What a commit costs
-
-R2 has no metadata-only patch. To stamp `committedAt`, `role`, `uploadGroupId` and the filename markers, Mantle streams each uploaded object through a `GET` and a `PUT`. So a successful N-variant commit performs N `GET`s and N `PUT`s and rewrites the sum of the variant sizes.
-
-- Commits validate the bundle shape before any I/O.
-- Variants are processed in batches of at most three; a batch settles before the next starts or an error returns.
-- A mime or size failure cancels the unused `GET` stream; a failed `PUT` also attempts cancellation while preserving the original error.
-- The asset row is saved only after every variant succeeds. All-or-nothing.
-
-Parallelism reduces waiting, not operation count or bytes. Keep variant counts and byte caps deliberate. A partial R2 failure leaves the pending D1 record in place so the commit can be retried before it expires; already stamped objects stay stamped.
-
-## Cleanup
-
-An upload can reach R2 and never be committed — an interrupted agent, a rejected commit. Remove those objects with the version-matched `media-gc` skill. It is opt-in and deliberately not projected into a repository by `mantle skills`, because it deletes remote objects.
-
-Its posture is audit first, delete only what an operator confirmed. It treats an object as a candidate only when it is over 24 hours old, has no `committedAt` custom metadata, and matches the exact key layout `<purpose>/<group>/(primary|alternate|fallback).<ext>` for a purpose this project declares. It reports account, bucket, prefixes, cutoff, counts, bytes and a digest of the candidate set without printing keys or URLs; on confirmation it re-runs the same audit and stops if anything changed.
-
-> **Do not use an R2 lifecycle rule**
-> Committed and uncommitted media share the same purpose prefix, so an age-based rule deletes live assets. After a pending record expires, partially stamped orphans require an operator audit against D1 references: a missing pending record does not mean an object is unused.
-
-## Diagnostics
-
-| Code | HTTP | Raised when |
-|---|---|---|
-| `MEDIA_NOT_CONFIGURED` | 501 | No `mediaStorage` port is bound on this deployment |
-| `MEDIA_PURPOSE_REJECTED` | 400 | The requested purpose is not declared; the declared set is returned so an agent can self-correct |
-| `MEDIA_MIME_REJECTED` | 400 | A mime outside `image/png`, `image/jpeg`, `image/webp`, `image/avif`, `image/gif` |
-| `MEDIA_SIZE_EXCEEDED` | 400 | A declared byte size exceeds its cap |
-| `MEDIA_SVG_REJECTED` | 400 | An SVG was offered while SVG is not allowed; object storage does not sanitize SVG payloads |
-| `MEDIA_VARIANTS_INCOMPLETE` | 400 | The bundle misses a mime the purpose requires; the missing set is returned |
-| `MEDIA_VARIANT_SIZE_EXCEEDED` | 400 | One variant exceeds the cap declared for its mime |
-| `MEDIA_VARIANTS_SUSPICIOUS_SIZE` | 400 | A modern variant is larger than its fallback (AVIF above JPEG), so it looks unoptimized |
-| `MEDIA_ASSET_NOT_FOUND` | 404 | No `media_assets` row matches the id |
-| `MEDIA_UPLOAD_EXPIRED` | 410 | The upload capability's TTL elapsed, or it was never created |
-| `MEDIA_OBJECT_NOT_FOUND` | 409 | A variant's bytes were never PUT before commit |
+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.
 
-The full catalog is in [Diagnostic codes](../reference/diagnostics.md).
+## Stale uploads
 
-## Source
-- [`docs/media-uploads.md`](../../../docs/media-uploads.md)
-- [`docs/adr/0017-media-multi-variant-agent-side-optimization.md`](../../../docs/adr/0017-media-multi-variant-agent-side-optimization.md)
-- [`packages/mantle-runtime/src/domain/port/MediaStorage.ts`](../../../packages/mantle-runtime/src/domain/port/MediaStorage.ts)
-- [`packages/mantle-runtime/src/domain/port/MediaAssetRepository.ts`](../../../packages/mantle-runtime/src/domain/port/MediaAssetRepository.ts)
-- [`packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts`](../../../packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts)
-- [`packages/mantle-spec/src/kernel/diagnostic.ts`](../../../packages/mantle-spec/src/kernel/diagnostic.ts)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`docs/skills/media-gc/SKILL.md`](../../skills/media-gc/SKILL.md)
+A group created but never committed leaves objects under `uploads/` until its
+URLs expire. The package skill `docs/skills/media-gc/SKILL.md` audits and
+removes them.