@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.1

package/docs/handbook/chatgpt-sites/generated-app.md

@@ -1,84 +0,0 @@
----
-description: Generate a blank Mantle app for ChatGPT Sites, apply D1 migrations, and verify local Admin and MCP.
----
-# Generate a ChatGPT Sites app
-
-`mantle generate --host chatgpt-sites` creates a blank home, a D1-backed Runtime,
-public API and MCP, and Mantle Admin. It adds no article Schema, media bucket, or
-demo content. Edit `src/home.ts` and add your own manifests and handlers as needed.
-
-```sh
-mkdir my-site && cd my-site
-npm init -y
-npm pkg set type=module
-npm install --save-exact @aotter/mantle
-npx mantle generate --host chatgpt-sites
-npm install
-npx mantle generate
-npm run build
-npx wrangler d1 migrations apply my-site --local
-```
-
-The first generate declares the exact Mantle package versions it needs; the
-second runs after those packages are installed. Review `drizzle/0000_mantle.sql`
-before applying it. The D1 name comes from `wrangler.jsonc`. Generation does not
-apply a migration, provision a Site, or publish one. `npm run build` removes the
-old `dist` before copying the current migrations and Admin assets.
-
-For local Admin, copy `.dev.vars.example` to `.dev.vars`, set `OWNER_EMAIL` to
-the email of the ChatGPT account that will own this Site, and keep
-`PUBLIC_ORIGIN` equal to the local URL. Run `npm run dev`.
-The plain local browser has no ChatGPT Sites identity, so it will redirect to
-Sites sign-in and cannot prove owner access. To exercise the identity contract
-locally, set `MANTLE_TEST_OWNER_EMAIL` to the same email and run
-`npm run smoke:local`. That script refuses non-loopback
-targets. Its identity headers are a local simulation; the production Worker
-contains no identity-injection path and must run behind Sites' trusted
-identity-stripping dispatcher. The generated Wrangler config disables the
-independent `workers.dev` URL; do not add a direct Worker route. A passing
-local smoke does not verify a deployed ChatGPT sign-in.
-
-Without `OWNER_EMAIL`, sign-in grants no Mantle staff role. If the intended
-owner signed in before configuration, their existing `sites_users` row remains
-unprivileged. Configure the owner email and deliberately assign `role='owner'`
-to that account's exact email and `chatgpt:` ID in D1, or reset a disposable
-local database and sign in again. Mantle never gives ownership to the first
-visitor.
-
-The anonymous public MCP endpoint is `/api/mcp`; it discovers only public
-manifest capabilities. `/api/mcp/staff` uses the current Sites browser session
-and a Mantle staff role. Admin advertises these endpoints, and Admin WebMCP
-works in supporting browsers. The staff endpoint is not a remote OAuth MCP
-connector. A remote agent needs a separately implemented verified OAuth flow.
-
-When a Schema changes, run `npx mantle generate --check` to detect drift, then
-`npx mantle generate`. Review the newly appended SQL and apply pending D1
-migrations before deploying code that expects the new Schema. Previous
-migration files remain untouched; an unapplied migration keeps the old database
-fingerprint, and managed boot refuses to use an older database. Sites owns
-`.openai/hosting.json` project metadata and production D1 migration delivery.
-
-Replacing a Schema's `uniqueIndexes` tuple requires an explicit reviewed
-migration. With the old local D1 migration applied, edit the Manifest and run
-`npx mantle generate --review-unique-indexes --check` to inspect the proposed
-source/target fingerprints, affected tuples and checksum without writing. Then
-run `npx mantle generate --review-unique-indexes`, review the new
-`drizzle/meta/000N_mantle.review.json` and matching SQL, and apply that SQL
-through the normal Sites D1 migration path. The CLI checks **local D1 only**
-for duplicate target tuples and reports a count and sample before writing;
-inspect production data separately before applying there. SQLite also refuses
-to create the new unique index if production has conflicts; do
-not deploy the target Worker until the migration has succeeded. Old Workers
-cannot safely reactivate after the old uniqueness guarantee is removed.
-This option is limited to managed Sites SQLite and unique tuple changes;
-field conversions and runtime-managed CF boot still reject destructive
-changes.
-
-For a complete article, media, and publishing example, use the
-[Sites reference](../../examples/host-chatgpt-sites/README.md).
-
-## Source
-
-- [Sites generator](../../../packages/mantle/src/cli/generate-sites.ts)
-- [Generated Sites templates](../../../packages/mantle/templates/chatgpt-sites)
-- [Runnable Sites reference](../../examples/host-chatgpt-sites/README.md)

package/docs/handbook/chatgpt-sites/host-reference.md

@@ -1,113 +0,0 @@
----
-description: "Mantle on ChatGPT Sites: identity, D1, R2 media, public web, MCP boundaries, and deployment checks."
----
-# ChatGPT Sites host reference
-
-Start with [Mantle on ChatGPT Sites](./index.md) for the supported installation
-path and your first publishing workflow. This reference explains how the
-integration connects Sites hosting and sign-in to Mantle content, staff roles,
-Admin, media, and public web. Keep the application outside the Mantle SDK
-checkout and use matching SDK packages.
-
-Start from the [runnable Sites host reference](../../examples/host-chatgpt-sites/README.md), then replace its **example** manifest with the user's business contract. It contains the matching D1 migrations/fingerprint, R2 upload adapter, local smoke test and build layout. Its browser-backed staff identity is not an OAuth resource-server credential.
-
-## First deployment
-
-1. Inspect the Site's actual hosting manifest and available bindings. Bind D1 before booting Mantle; create and apply the generated immutable D1 migration before publishing. Do not run DDL per request.
-2. Compile the sealed plan (`mantle generate --check`, `mantle validate --phase deploy`) and bind `SqliteMantleStorageAdapter(new D1DatabaseDriver(env.DB), siteDefaults)`. Keep the generated storage fingerprint in sync with the migration.
-3. If Admin is requested, mount `@aotter/mantle-admin` and its prebuilt assets. Use the trusted identity supplied by Sites **only after its ingress has stripped caller-supplied identity headers**. Map the stable per-Site user ID to a Mantle principal; use email only for owner bootstrap/invitation matching, not as a durable ID. Persist staff roles in D1 and re-read them for each privileged request. A Site Viewer is not automatically a Mantle editor.
-4. If public pages are requested, compose `@aotter/mantle-web` over published-only queries. Verify anonymous article HTML, canonical/JSON-LD, Markdown, sitemap and `llms.txt`; a draft must remain 404. Do not assume a successful Admin boot implies a working homepage.
-5. Publish through Sites, then verify the deployed version rather than only a local preview. Test owner, second account, role revocation, public/anonymous reads and every configured binding.
-
-## Media with only an R2 binding
-
-The `MediaStorage` port returns an HTTP `PUT` capability; it does **not** require a presigned S3 URL. An application with `env.MEDIA_BUCKET` can implement the port with `R2Bucket.put/head/get/delete` and return a same-origin upload URL. Bind that implementation as `ports.mediaStorage` **and** declare at least one `siteDefaults.media.purposes` policy; otherwise the Admin library and `create_media_upload` remain disabled.
-
-The application must mount two routes alongside the port:
-
-- `PUT /admin/media-upload/:group/:file`: check an authenticated editor-or-higher session, exact `Origin`, unexpired D1 pending-upload record, server-generated storage key, declared MIME and exact byte size before `R2Bucket.put`. Bound the request body by the policy limit. In Workers, a fixed-length `Uint8Array` is the conservative input to `put` when a streamed request body has unknown length. The port's `createUpload` must return this route as `uploadUrl` and the exact required `Content-Type` header.
-- `GET /media/:purpose/:group/:file`: look up the committed `media_assets` row before `R2Bucket.get`, and serve only a listed variant with a safe MIME, `nosniff` and an intentional public cache policy. This is a **public** URL; it does not make private media safe.
-
-The existing create → `PUT` each `uploadUrl` → commit flow works unchanged in Admin UI. Verify that an anonymous/cross-origin/expired/oversize `PUT` fails, that pre-commit public reads are 404, and that committed media resolves anonymously. A successful R2 binding read/write probe alone does not enable the library.
-
-The browser route above uses the Sites session and therefore does **not** automatically work for a remote MCP client. For remote agent upload, either give the client a separately authenticated Worker `PUT` capability (with its own expiry and pending-record check) or choose the native `R2MediaStorage` direct-to-R2 path. Do not put image bytes in MCP JSON tool arguments. R2 bindings expose object operations, not S3 SigV4 presigning: direct-to-R2 presigned URLs require an R2 S3 endpoint and API key pair. Do not configure those credentials merely to make Admin UI upload work.
-
-## Remote MCP is a separate gate
-
-The reference exposes these separate surfaces:
-
-| Surface | Authentication | Reference support |
-|---|---|---|
-| Admin WebMCP | Current browser Admin session and fresh Mantle staff role | Available within Admin. |
-| Public MCP (reference path: `/api/mcp`) | Anonymous, read-only public Views | Manual HTTPS `initialize`, `tools/list`, and a published View call verified on the deployed integration. |
-| Sites-session staff MCP (reference path: `/api/mcp/staff`) | Sites-injected identity plus a fresh Mantle staff role | Mounted and reported to Admin; not usable as a remote OAuth connector. |
-| Remote staff OAuth MCP | OAuth bearer authorization and fresh Mantle staff role | Requires a separate integration. |
-| Sites-managed connector registration | Sites MCP declaration and connection configuration | Unverified; do not guess a hosting manifest key. |
-
-Try the conventional `/mcp` path first. If ChatGPT Sites does not route that
-path to the application, mount the MCP handler at another application-owned
-path and report the actual path through `mcpEndpoints`. For example:
-
-```ts
-app.all("/agent/read", publicMcpHandler);
-
-mountMantleAdmin(app, {
-  plan,
-  auth,
-  assets,
-  get,
-  mcpEndpoints: { public: "/agent/read", staff: "/agent/staff" },
-});
-```
-
-The reference encountered that condition and chose `/api/mcp` plus
-`/api/mcp/staff`. It mounts both handlers and passes both paths through
-`mcpEndpoints`, so Admin displays the routes that actually exist. These are
-example fallback paths, not Mantle Core routes. Verify each chosen route with
-`initialize`, `tools/list`, and a tool call after every Sites deployment.
-
-The reference smoke test also checks that `/mcp` and `/mcp/staff` return 404.
-The earlier deployment's root `/mcp` response is not evidence of a globally
-reserved Sites path; another Sites deployment may route it differently.
-
-Identity follows the same host-owned design. `@aotter/mantle-admin` exports
-`AdminAuth`; the reference implements it using trusted Sites identity headers
-and a D1 staff table. A host may implement the interface with another identity
-system or wrap Mantle's Better Auth adapter. Core does not contain a ChatGPT
-login implementation or require Better Auth for Sites.
-
-A successful public MCP call verifies that endpoint, not ChatGPT connector
-registration. A manually configured connector targets the HTTPS endpoint;
-Sites-provisioned connection details (`get_site` with `include_mcp_connection`)
-additionally require a deployed MCP declaration.
-
-The reference's staff endpoint trusts only identity injected by the Sites
-ingress, rejects ordinary members, and re-reads the Mantle role on every
-request. Before exposing staff MCP to remote clients, implement a standard
-OAuth authorization server or established provider, bearer verification, and
-a fresh Mantle staff role check on each tool request. Verify OAuth protected-resource and
-authorization metadata as JSON, a standards-compliant unauthenticated `401`
-challenge, and authenticated `tools/list` plus a read-only call. A Sites browser
-session or forwarded identity header is not an OAuth bearer token; a sign-in
-HTML page returned to an OAuth JSON request is a failed integration.
-
-## Capability boundaries
-
-Native Cloudflare deployments can configure R2 public domains, S3 credentials, Queues, Durable Objects, KV and Cron independently. A Sites deployment should claim only the bindings its hosting manifest and deployed tests actually expose. `waitUntil` is not a durable queue. Keep missing primitives as explicit host limitations rather than adding fake Mantle ports.
-
-See [native R2 direct upload](../cloudflare/media-r2.md), [authentication](../cloudflare/authentication.md), and [public web](../cloudflare/public-web.md).
-
-For custom business rules and external API calls, see the
-[equipment checkout guide](./equipment-checkout.md). It keeps transactional
-application state separate from notification delivery and documents the
-deployment experiment's limits. Sites' [unsupported uses](https://learn.chatgpt.com/docs/sites#understand-limits-and-unsupported-uses)
-include financial transactions; a successful sandbox experiment is not support
-for live payments.
-
-## Source
-
-- `MediaStorage` port and the media upload use case in `@aotter/mantle-runtime`
-- [Cloudflare R2 Workers binding API](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/)
-- [Cloudflare R2 presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
-- [OpenAI Sites](https://learn.chatgpt.com/docs/sites)
-- [OpenAI MCP server authentication](https://developers.openai.com/plugins/build/auth)

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

@@ -1,133 +0,0 @@
----
-description: "Build with ChatGPT Sites. Manage content and publishing with Mantle."
----
-# Mantle on ChatGPT Sites
-
-**Build with ChatGPT Sites. Manage content and publishing with Mantle.**
-
-Give your Site an editorial workflow: sign in, invite editors, upload a cover
-image, save a draft, and publish an article. Mantle connects the Admin console,
-public pages, and agent tools to the same content model, so your team can keep
-the site current after the first build.
-
-ChatGPT Sites is a first-class integration in Mantle's official documentation,
-with a runnable reference and a repeatable verification flow maintained in this
-repository. Sites owns hosting, visitor access, and ChatGPT sign-in; Mantle owns
-the content model, staff roles, and publishing workflow. For platform access and
-sharing options, see [OpenAI's Sites documentation](https://learn.chatgpt.com/docs/sites).
-
-For a new project, start with the [blank generated app](./generated-app.md).
-The article reference below demonstrates a complete editorial Site with R2
-media after you choose that content model.
-
-## What you get
-
-| Capability | In the Mantle Sites reference |
-|---|---|
-| Content management | Admin for drafting, editing, publishing, and unpublishing articles stored in D1. |
-| Staff access | ChatGPT sign-in with Mantle owner, editor, and contributor roles. Site visitor access grants no Mantle staff role. |
-| Images | Admin uploads through the Site's R2 binding, with public URLs for committed images. No R2 S3 credentials required. |
-| Public pages | Published article HTML and Markdown, cover images, canonical metadata, JSON-LD, sitemap, and `llms.txt`. |
-| Agent access | Admin WebMCP, anonymous read-only public Views at `/api/mcp`, and Sites-session staff tools at `/api/mcp/staff`. |
-
-Remote staff OAuth MCP and automatic ChatGPT connector registration are outside
-the reference's current scope. Public media URLs are readable by anyone
-who can reach the Site; this integration does not implement private media.
-See the [host reference](./host-reference.md) for the exact trust and transport
-boundaries.
-
-## Start with the supported SDK
-
-You need Node.js 22+ and Sites access with D1. Start with the
-[blank generated app](./generated-app.md) to choose your own content model;
-it requires no R2 bucket. The article reference also needs R2 for cover
-images. Build and smoke-test locally before deployment, and keep your
-application outside the SDK checkout.
-
-## Follow the article reference when it fits
-
-The steps below apply to the optional prebuilt article example. A new blank
-generated Site has no article Schema, media bucket or content; add those only
-when your requirements call for them.
-
-1. **Prepare the application.** Follow the
-   [runnable reference](../../examples/host-chatgpt-sites/README.md#install-and-run).
-   Its local test verifies content, roles, images, public pages, and MCP together.
-2. **Connect Sites.** Follow [Publish with Sites](../../examples/host-chatgpt-sites/README.md#publish-with-sites)
-   to provision D1 and R2, set the production origin and first owner's email,
-   and review the database migrations. Save a version, then deploy it through
-   Sites for the intended audience.
-3. **Sign in as the owner.** Open `/admin/sign-in` and use the configured owner's
-   ChatGPT account. Give a second account an editor role in Mantle when you want
-   someone else to manage content. Sites sharing and Mantle staff roles are
-   separate controls.
-4. **Create a draft.** In Admin, create an article with a title, summary, and
-   Markdown body. Upload an image in the media library and select it as the
-   article's cover. The draft's public article URL should return 404.
-5. **Publish and read.** Publish the article and open `/articles`. Follow its
-   link to check the body and cover, then confirm the page head advertises
-   its `.md` version with `rel="alternate"` and `type="text/markdown"`. For a public
-   Site, repeat this while signed out. A restricted Site still enforces its
-   audience settings before visitors reach these pages.
-6. **Verify control.** Unpublish the article and confirm its detail page returns
-   404. Revoke the second account's staff role and verify it can no longer edit.
-   Published content and staff access should follow your changes immediately.
-
-For later content edits, return to Mantle Admin. Changes to the application's
-schema, code, or deployment settings follow the reference's migration and Sites
-deployment workflow.
-
-## Maintain content with an agent
-
-The owner can use Admin WebMCP in a browser that supports it to let an agent
-discover staff tools for drafts, publishing, and other permitted operations.
-Open `/admin/dev/docs/webmcp` to see that browser surface and
-`/admin/dev/docs/mcp` to see the Site's `/api/mcp` public read-only endpoint and `/api/mcp/staff`
-staff endpoint. The latter uses the current Sites browser session and checks
-the Mantle staff role on each request. It is useful to same-origin browser
-code, but is not a remote OAuth MCP connector for a desktop agent. A remote
-staff connector needs its own verified OAuth flow; see the [host reference](./host-reference.md#remote-mcp-is-a-separate-gate).
-
-## Ask your agent to set it up
-
-Install the Mantle skill and exact SDK version, then describe your audience
-and content requirements:
-
-```text
-Build a content site with ChatGPT Sites and Mantle. Read
-handbook/chatgpt-sites/generated-app.md from the installed Mantle docs, and
-start from the blank generated Site when that CLI supports it. Use the article
-reference only if its content model matches my requirements. Include ChatGPT
-sign-in and Mantle staff roles; add cover uploads only if I request media.
-Run the local checks and show me a draft-to-publish walkthrough before
-deploying through Sites. Keep remote staff OAuth MCP outside this scope.
-```
-
-For business rules beyond content, add: "use custom `ref` handlers and
-application-owned tables as described in handbook/chatgpt-sites/equipment-checkout.md."
-
-## Beyond content: operational workflows
-
-Custom handlers can connect typed Mantle operations to application-owned
-business rules and external services. See [Equipment checkout and external
-notifications](./equipment-checkout.md) for a non-payment scenario: staff
-approve equipment loans, atomically reserve a kit, and notify an equipment desk
-in Slack without making approval depend on notification delivery.
-
-This is an implementation guide and acceptance checklist, not an additional
-feature installed by the article reference. It separates deployed integration
-evidence from the equipment and Slack work still required in your application.
-
-## Integration details
-
-- [Host reference](./host-reference.md): identity, migrations, R2 routes, MCP, and deployment checks.
-- [Generated blank app](./generated-app.md): local composition, D1 migration, Admin, and MCP.
-- [Equipment checkout](./equipment-checkout.md): custom business rules and external API delivery without payments.
-- [Runnable application](../../examples/host-chatgpt-sites/README.md): installation, build artifacts, and smoke tests.
-- [Conventional Cloudflare Worker](../cloudflare/conventional-worker.md): the separate path for a Worker you deploy directly.
-
-## Source
-
-- [Runnable Sites application](../../examples/host-chatgpt-sites/README.md)
-- [Sites host reference](./host-reference.md)
-- [OpenAI Sites documentation](https://learn.chatgpt.com/docs/sites)

package/docs/handbook/cloudflare/bindings.md

@@ -1,291 +0,0 @@
----
-description: Each Cloudflare primitive a Mantle Worker can bind, what Mantle uses it for, the wrangler snippet, and the Env type.
----
-# Bindings and primitives
-
-This page lists every Cloudflare binding a Mantle Worker commonly declares: which are required, what Mantle does with each, the `wrangler.jsonc` snippet, and the matching `Env` field. Read it when you write or review a Worker's configuration.
-
-## Compatibility flags
-
-Every Mantle Worker keeps both flags:
-
-```jsonc
-"compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"]
-```
-
-`nodejs_compat` is required by the adapter and its Auth dependencies. `global_fetch_strictly_public` is required because MCP client metadata (CIMD) is fetched through the public Internet boundary.
-
-## The composition-root rule
-
-Bindings appear in two places only: the Worker entry (`createMantleWorker` options and the `bindings` hook) and `wrangler.jsonc`. Procedure handlers receive them through `ctx.env`. An application may own additional tables behind its own repository, but it never queries Mantle-owned native Schema tables, site settings, media or Auth tables outside the runtime. Use `runtime.entries`, generated `bindMantle(runtime)` and Views instead.
-
-## The Env interface
-
-```ts
-import type { DeferredHookEnvelope } from "@aotter/mantle/runtime";
-import type { MantleCloudflareEnv } from "@aotter/mantle/cloudflare";
-
-interface EmailBinding {
-  send(message: { to: string; from: string; subject: string; text?: string; replyTo?: string }): Promise<unknown>;
-}
-
-export interface Env extends MantleCloudflareEnv {
-  // MantleCloudflareEnv already declares DB, ASSETS?, MANTLE_KV? and the auth vars.
-  readonly DB: D1Database;                                   // required
-  readonly ASSETS: Fetcher;                                  // Admin bundle + your frontend
-  readonly PUBLIC_ORIGIN: string;
-  readonly MANTLE_KV?: KVNamespace;                          // optional MCP catalog cache
-  readonly MEDIA_BUCKET?: R2Bucket;                          // optional media
-  readonly R2_ACCOUNT_ID?: string;
-  readonly R2_ACCESS_KEY_ID?: string;
-  readonly R2_SECRET_ACCESS_KEY?: string;
-  readonly MEDIA_PUBLIC_URL_BASE?: string;
-  readonly AUDIT?: AnalyticsEngineDataset;                 // optional MCP tools/call audit trail
-  readonly MANTLE_INTERNAL_QUEUE?: Queue<DeferredHookEnvelope>;  // optional deferred hooks
-  readonly ORDER_EXPIRY_QUEUE?: Queue<{ type: "expire-order"; orderToken: string }>;  // application queue
-  readonly INVENTORY_COORDINATOR?: DurableObjectNamespace;  // application-owned
-  readonly EMAIL?: EmailBinding;                             // Email Service
-  readonly TURNSTILE_SECRET_KEY?: string;                    // secret
-}
-```
-
-## D1: `DB` (required)
-
-D1 is canonical storage. It holds one native table per Manifest Schema, Mantle's
-`_mantle_*` envelope and migration metadata, site settings, media metadata and
-pending uploads, and the Better Auth tables. `createConventionalBindings`
-throws without `DB`.
-
-```jsonc
-"d1_databases": [
-  { "binding": "DB", "database_name": "my-site", "database_id": "<production-id>" }
-]
-```
-
-Omit `database_id` only for local development. Set the production id before any remote deploy.
-
-## Static Assets: `ASSETS`
-
-```jsonc
-"assets": { "directory": "./public", "binding": "ASSETS" }
-```
-
-`ASSETS` is a hard requirement for Admin. `mantle generate` syncs the **prebuilt** Admin SPA into `public/_mantle/admin/` when `@aotter/mantle-admin-ui` is installed — there is no Vite step unless you are developing `admin-ui` itself. The facade wraps `ASSETS` as the Admin asset server and falls back to `/_mantle/admin/index.html` for client-side Admin routes. The same binding serves your own CSS, JS and icons.
-
-Without this binding, `/admin` can still return SPA HTML (`200`) while `/_mantle/admin/assets/*` is `404`. That white-screens the Dev UI.
-
-When Worker routes and static paths overlap, list Worker-owned paths in `run_worker_first` and keep `not_found_handling` at `"none"` so unmatched requests fall through to the Worker. **Leave `/_mantle` out of `run_worker_first`** so hashed Admin JS/CSS stay on the assets layer. A production configuration lists `/admin`, `/admin/*`, `/mcp`, `/mcp/*`, `/oauth`, `/oauth/*`, `/.well-known/*`, `/api/*`, `/llms.txt`, `/robots.txt`, `/sitemap.xml`, `/*/llms.txt` and every public content prefix there, so a static file can never shadow a Mantle route.
-
-## Workers Cache
-
-```jsonc
-"cache": { "enabled": true }
-```
-
-With a valid `cacheScope`, Mantle marks anonymous `200` `GET`/`HEAD` responses from the public mount (HTML, `.md`, `llms.txt`, sitemap) and eligible Views with a shared lifetime and a deployment-scoped `Cache-Tag`; everything else is `private, no-store`. Supplying a custom `credentialResolver` disables shared responses because Core cannot infer which request headers carry identity. Publishing-content and site-setting writes purge the tag after the canonical write. Purge failure is logged and does not turn a committed write into an error. The local emulator does not simulate the entrypoint cache or its purge API. See [Public web](./public-web.md#cache-contract).
-
-## KV: `MANTLE_KV` (optional)
-
-```jsonc
-"kv_namespaces": [
-  { "binding": "MANTLE_KV", "id": "<production-id>", "preview_id": "<development-id>" }
-]
-```
-
-A deployment-owned namespace that caches the caller-independent MCP catalog projection (brand, description, origin, icons, media-purpose policy) so an authenticated MCP catalog does not read D1 site settings. D1 stays canonical; missing or expired snapshots are repaired from D1 within one hour, and a KV failure never fails a committed write. Never store tokens, sessions or content here. `createMantleWorker` uses this binding only when `cacheScope` is valid, producing keys such as `mantle:my-site-production:site-config:v1:mcp`. KV is eventually consistent across regions, so invalidation is not a global read-after-write guarantee.
-
-## R2: `MEDIA_BUCKET` (optional)
-
-```jsonc
-"r2_buckets": [{ "binding": "MEDIA_BUCKET", "bucket_name": "<project>-media" }]
-```
-
-Staff media uploads through Staff MCP presigned PUT. The binding alone cannot sign URLs; you also need `R2_ACCOUNT_ID`, `MEDIA_PUBLIC_URL_BASE` and the two S3 credential secrets. See [Media uploads with R2](./media-r2.md).
-
-## Analytics Engine: `AUDIT` (optional)
-
-```jsonc
-"analytics_engine_datasets": [{ "binding": "AUDIT", "dataset": "mantle_mcp_audit" }]
-```
-
-An MCP `tools/call` audit trail: who called which tool on which surface, with
-what outcome and how long it took. The runtime's `McpJsonRpcDispatcher` is the
-single write point; it records nothing unless the composition root passes an
-`AuditSink`, and the write happens through `waitUntil`, off the response path.
-Request and response payloads are never recorded.
-
-```ts
-import { analyticsEngineAuditSink, createMantleWorker } from "@aotter/mantle/cloudflare";
-
-export default createMantleWorker<Env>({
-  plan,
-  audit: (env) => env.AUDIT
-    ? analyticsEngineAuditSink(env.AUDIT, { index: env.PUBLIC_ORIGIN })
-    : undefined,
-});
-```
-
-One dataset may hold many deployments: `index` is the deployment's public
-origin, the only column Analytics Engine filters cheaply. Columns, in order:
-
-| Column | Field |
-|---|---|
-| `index1` | the configured `index` |
-| `blob1` … `blob7` | `surface`, `callerId`, `clientId`, `credential`, `tool`, `outcome`, `operationId` |
-| `double1`, `double2` | `at` (epoch ms), `durationMs` |
-
-`outcome` is `ok`, a runtime Diagnostic code such as `UNAUTHENTICATED` or
-`AUTH_DENIED`, `UNKNOWN_TOOL`, `INVALID_PARAMS`, `INTERNAL`, or a transport gate denial
-(`INVALID_TOKEN`, `INSUFFICIENT_SCOPE`, `INSUFFICIENT_ROLE`, `CROSS_ORIGIN`): a
-`tools/call` refused before it reaches the dispatcher is recorded too, with
-whatever identity the gate established. Its body goes through the same 1 MiB
-bounded reader as an admitted call; a denied request whose body is oversized
-or not JSON is still recorded, with `tool` set to `(unreadable)`, so padding a
-body cannot hide a credential probe. `operationId` is the string argument whose
-schema declares `x-mcp-hint: idempotency-key`, falling back to the conventional
-`operationId` argument when the tool declares no hint. It is empty when that
-argument is absent and is resolved the same way on admitted and denied calls.
-Read it with the
-[SQL API](https://developers.cloudflare.com/analytics/analytics-engine/sql-api/):
-
-```sql
-SELECT timestamp, blob2 AS caller, blob5 AS tool, blob6 AS outcome, double2 AS ms
-FROM mantle_mcp_audit
-WHERE index1 IN ('https://site-a.example', 'https://site-b.example')
-  AND timestamp > NOW() - INTERVAL '7' DAY
-ORDER BY timestamp DESC
-```
-
-Analytics Engine keeps data for a bounded window and samples under very high
-write rates. Longer retention or a tamper-evident trail is an export job on top
-of this dataset. Self-hosted runtimes may implement `AuditSink` over any store;
-the interface is one `record(event)` method.
-
-## Queues
-
-```jsonc
-"queues": {
-  "producers": [
-    { "binding": "MANTLE_INTERNAL_QUEUE", "queue": "mantle-internal" },
-    { "binding": "ORDER_EXPIRY_QUEUE", "queue": "my-site-order-expiry" }
-  ],
-  "consumers": [
-    { "queue": "mantle-internal", "max_batch_size": 10, "max_batch_timeout": 5,
-      "max_retries": 5, "retry_delay": 60, "dead_letter_queue": "mantle-internal-dlq" },
-    { "queue": "my-site-order-expiry", "max_concurrency": 1, "max_batch_size": 10,
-      "max_retries": 5, "retry_delay": 30, "dead_letter_queue": "my-site-order-expiry-dlq" }
-  ]
-}
-```
-
-`MANTLE_INTERNAL_QUEUE` carries deferred `after_*` lifecycle hooks. Application queues share the same Worker; the `queue()` export switches on `batch.queue`. See [Deferred hooks with Queues](./deferred-hooks-queues.md).
-
-## Cron Triggers
-
-```jsonc
-"triggers": { "crons": ["*/5 * * * *"] }
-```
-
-A `schedule` Trigger declares the Procedure, and the Worker export reuses the same runtime as `fetch`:
-
-```ts
-const worker = createMantleWorker<Env>({ plan, handlers });
-
-export default {
-  fetch: worker.fetch,
-  scheduled: worker.scheduled,
-} satisfies ExportedHandler<Env>;
-```
-
-Register the exact enabled `cron` expression in `wrangler.jsonc`; Mantle does not create provider triggers. The Procedure takes `{}` input and sees `ctx.schedule.id` for retry-safe idempotency. See [Trigger](../reference/trigger.md#schedule-source).
-
-## Durable Objects (application-owned)
-
-Durable Objects are not a Core primitive. Use one as an application-owned coordinator when a decision must be serialized, for example reserving inventory exactly once. Export the class from the Worker entry, then bind and migrate it:
-
-```jsonc
-"durable_objects": { "bindings": [{ "name": "INVENTORY_COORDINATOR", "class_name": "InventoryCoordinator" }] },
-"migrations": [{ "tag": "inventory-v1", "new_sqlite_classes": ["InventoryCoordinator"] }]
-```
-
-```ts
-export { InventoryCoordinator } from "./commerce/InventoryCoordinator.js";
-```
-
-The coordinator keeps its own state; Mantle entries mirror the result. See [Commerce inventory](../../examples/cf-primitives-commerce-inventory.md).
-
-## Email Service: `[[send_email]]`
-
-```jsonc
-"send_email": [{ "name": "EMAIL" }]
-```
-
-Send from an `after_create` handler with `errorPolicy: continue`, and fail soft when the binding or addresses are absent so submissions still save on a fresh deployment:
-
-```ts
-export async function notifyIntake(input: { name?: string; email?: string }, ctx: HandlerContext) {
-  const env = ctx.env as Env & { INTAKE_NOTIFY_TO?: string; INTAKE_NOTIFY_FROM?: string };
-  if (!env.EMAIL || !env.INTAKE_NOTIFY_TO || !env.INTAKE_NOTIFY_FROM) {
-    console.info("[intake] notification not configured");
-    return { ok: true };
-  }
-  await env.EMAIL.send({
-    to: env.INTAKE_NOTIFY_TO,
-    from: env.INTAKE_NOTIFY_FROM,
-    subject: `New intake response from ${input.name ?? "website"}`,
-    text: `Email: ${input.email ?? ""}`,
-    ...(input.email ? { replyTo: input.email } : {}),
-  });
-  return { ok: true };
-}
-```
-
-## Turnstile
-
-Store the secret with `wrangler secret put TURNSTILE_SECRET_KEY`. Declare the token in the Procedure input, then verify it in a `before_create` lifecycle Trigger that aborts on failure:
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: intake-before-create-verify-turnstile
-spec:
-  source:
-    kind: lifecycle
-    schema: intake-submissions
-    on: [before_create]
-    errorPolicy: abort
-  target:
-    procedure: verify-intake-turnstile
-```
-
-The adapter exports a handler factory for the `siteverify` call:
-
-```ts
-import { cloudflareTurnstileCheck } from "@aotter/mantle/cloudflare";
-
-extend: ({ env }) => ({
-  handlers: {
-    "verify-intake-turnstile": cloudflareTurnstileCheck({
-      secret: env.TURNSTILE_SECRET_KEY ?? "dev-stub",
-      tokenField: "turnstileToken",
-    }),
-  },
-}),
-```
-
-Authenticated callers (`ctx.user` set) bypass the check. The literal secret `"dev-stub"` skips the network and rejects only the token `"fail"`. Rejection throws `AUTH_DENIED`, which maps to HTTP `403`. See [Intake Turnstile and email hooks](../../examples/cf-primitives-intake-hooks.md).
-
-## Source
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`packages/adapters/cloudflare/src/bindings/conventionalBindings.ts`](../../../packages/adapters/cloudflare/src/bindings/conventionalBindings.ts)
-- [`packages/adapters/cloudflare/src/mount/cmsConfig.ts`](../../../packages/adapters/cloudflare/src/mount/cmsConfig.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/adapters/cloudflare/src/handlers/turnstile.ts`](../../../packages/adapters/cloudflare/src/handlers/turnstile.ts)
-- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
-- [`docs/deferred-lifecycle-queues.md`](../../../docs/deferred-lifecycle-queues.md)
-- [`docs/media-uploads.md`](../../../docs/media-uploads.md)
-- [`docs/performance-harness.md`](../../../docs/performance-harness.md)
-- [`docs/cloudflare-low-level-composition.md`](../../../docs/cloudflare-low-level-composition.md)
-- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
-- [`docs/examples/host-minimal-worker/wrangler.jsonc`](../../../docs/examples/host-minimal-worker/wrangler.jsonc)