@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.1

package/docs/handbook/cloudflare/conventional-worker.md

@@ -0,0 +1,162 @@
+---
+description: Assemble a Mantle Worker with createMantleWorker, add handlers and routes through extend, and respect Core-owned paths.
+---
+# The conventional Worker
+
+`createMantleWorker` is the normal Cloudflare entry for a Mantle application. This page covers its options, what the facade owns, how to add application handlers and routes, and the readiness and reserved-path rules that keep those extensions safe.
+
+## Minimal entry
+
+```ts
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export default createMantleWorker({ plan, cacheScope: "my-site-production" });
+```
+
+`plan` is the sealed plan that `mantle generate` writes to `.mantle/generated/mantle.ts`. With only `plan`, the Worker serves public View REST, HTTP Triggers, Admin, Auth, OAuth and MCP. It renders no public pages and `/` is a 404; see [Public web](./public-web.md).
+
+## Options
+
+| Option | Type | Purpose |
+|---|---|---|
+| `plan` | `RuntimePlan` | Required. Generated plan; a fingerprint or version mismatch fails immediately and asks you to regenerate. |
+| `handlers` | `Record<string, AnyHandler>` | Implementations for `handler.kind: ref` Procedures. Merged with `extend().handlers`; a name registered twice throws. |
+| `siteDefaults` | `SiteDefaults \| (env) => SiteDefaults` | Brand, title, description, origin, locales, icons, media purposes. Use the function form to read `env.PUBLIC_ORIGIN`. See [Site config](../reference/site-config.md). |
+| `cacheScope` | `string \| (env) => string` | Stable deployment/site identifier for public cache tags and optional `MANTLE_KV` keys. Lowercase letters, digits, `_` and `-`, up to 64 characters. Shared caching is disabled when absent or invalid. |
+| `templates` | `TemplateRegistry` | Entry and list templates for public HTML. |
+| `publicPathResolver` | `PublicPathResolver` | Collection-to-URL mapping used for canonical URLs, sitemap and hreflang. |
+| `mediaAllowSvg` | `boolean \| (env) => boolean` | Accept SVG uploads. Default `false`. |
+| `auth` | `(env) => Auth` | Replace Auth construction only. Core still owns the Auth routes. |
+| `bindings` | `(env, conventional) => MantleWorkerBindings` | Augment the conventional adapters, for example `mediaStorage` or `deferredHookDispatcher`. |
+| `extend` | `(ctx) => MantleWorkerExtension \| void` | The one seam for handlers, credential resolution, JWT bearer verification and new Hono routes. |
+
+`extend` receives `{ env, auth, bindings, getRuntime }` and may return:
+
+```ts
+{
+  handlers?: Record<string, AnyHandler>;
+  credentialResolver?: ConsumerCredentialResolver;   // site-owned API keys and personal tokens
+  jwtBearer?: { audience: string; scopes?: readonly string[] };
+  mount?: ({ app, ref, env, auth, bindings, getRuntime }) => void;
+}
+```
+
+`extend` may run again after a failed initialization. Keep external side effects out of it.
+
+## What the facade owns
+
+Once per isolate, `createMantleWorker` assembles and memoizes:
+
+- Conventional bindings: `DB` becomes the D1 driver, `ASSETS` serves the Admin bundle, `MANTLE_KV` (when bound) becomes the MCP catalog projection. See [Bindings](./bindings.md).
+- Conventional Auth chosen by `MANTLE_AUTH_MODE`, or your `auth` factory. See [Authentication](./authentication.md).
+- Runtime endpoints: manifest HTTP Triggers, `GET /api/views` and `GET /api/views/<name>` for public Views.
+- Admin at `/admin` when Admin assets are present, OAuth consent and discovery, and MCP at `/mcp` and `/mcp/staff`.
+- A `/favicon.ico` route derived from `siteDefaults.icons`. This is a convention, not a reserved path; an existing host route wins.
+- The final cache policy on every response, and best-effort purge of the deployment-scoped public tag after publishing-content and site-setting writes.
+- A redacted error boundary: an unexpected failure returns `500` with `{ "ok": false, "error": "internal_error" }` and `private, no-store`.
+
+If `auth.ready` rejects, the memoized assembly is evicted so the next request rebuilds instead of reusing a poisoned isolate.
+
+## The returned handler
+
+```ts
+const worker = createMantleWorker<Env>({ plan });
+worker.fetch(request, env, ctx);   // HTTP entry
+worker.getRuntime(env);            // the runtime fetch uses, resolved after auth.ready
+```
+
+Queue and scheduled handlers call `worker.getRuntime(env)` and then generated `bindMantle(runtime)` so they reuse the assembled runtime and never write Mantle tables directly. See [Bindings](./bindings.md#cron-triggers) and [Deferred hooks](./deferred-hooks-queues.md).
+
+## Readiness rule
+
+Standard protected routes establish readiness themselves: the facade awaits `getRuntime()` before Auth, `/oauth`, `/mcp`, `/admin/api` and `/.well-known/oauth*` requests. Extension routes do not. Before an extension route reads or writes Mantle data, or relies on database-backed Auth, it must `await ref.get()` (inside `mount`) or `await getRuntime()`.
+
+`getRuntime` rejects when called synchronously inside `extend` before it returns. Retain the function and call it later, for example inside a request handler.
+
+## Reserved paths
+
+Extensions add routes; they never replace Core surfaces. These registrations are rejected:
+
+- `/admin`, `/_mantle`, `/api/auth`, `/api/views`, `/oauth`, `/mcp`, and anything beneath them
+- `/.well-known/oauth*`
+- the custom Auth factory's `basePath`
+- global `*` and `/*` handlers
+- any exact method and path pair that a manifest HTTP Trigger already owns
+
+Static literals fail TypeScript during your build (`MantleExtensionPath`). Computed paths cannot be proven statically, so after `mount` returns the facade inspects Hono's assembled route table and throws before serving any request. There is no override option. The `app` passed to `mount` exposes `get`, `post`, `put`, `patch`, `delete`, `options`, `all`, `on`, `use` and `route`; it omits global error and not-found hooks.
+
+## Handlers and routes
+
+```ts
+import { createMantleWorker, type MantleCloudflareEnv } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+import { notifyIntake } from "./handlers/notifyIntake.js";
+
+interface Env extends MantleCloudflareEnv {
+  readonly PUBLIC_ORIGIN: string;
+}
+
+export default createMantleWorker<Env>({
+  plan,
+  siteDefaults: (env) => ({
+    brand: "Example",
+    title: "Example",
+    description: "Example site.",
+    origin: env.PUBLIC_ORIGIN,
+    locales: ["en"],
+    icons: [
+      { src: "/site-icon.png", mimeType: "image/png", sizes: ["64x64"] },
+      { src: "/site-icon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
+    ],
+  }),
+  extend: () => ({
+    handlers: { "notify-intake": notifyIntake },
+    mount({ app, ref }) {
+      app.get("/api/health", (c) => c.json({ ok: true }));
+      app.get("/api/locales", async (c) => {
+        const runtime = await ref.get();            // readiness before data
+        const site = await runtime.siteConfig.load();
+        return c.json({ locales: site.locales });
+      });
+    },
+  }),
+});
+```
+
+Handler keys match `spec.handler.ref` in Procedure manifests; see [Procedures and Triggers](../concepts/procedures-and-triggers.md).
+
+## A `bindings` hook
+
+`bindings` receives the conventional set and returns the set the runtime uses. Spread the conventional bindings, then add capability adapters:
+
+```ts
+import {
+  createMantleWorker,
+  WorkersQueueHookDispatcher,
+} from "@aotter/mantle/cloudflare";
+
+export default createMantleWorker<Env>({
+  plan,
+  bindings: (env, conventional) => ({
+    ...conventional,
+    mediaStorage: buildMediaStorage(env),          // see media-r2.md
+    deferredHookDispatcher: new WorkersQueueHookDispatcher(env.MANTLE_INTERNAL_QUEUE),
+  }),
+});
+```
+
+The conventional set is `{ db, adminAssets, mcpCatalogKv? }`. Never drop `db`.
+
+## Site identity
+
+`siteDefaults.icons` is one identity reused by browser favicons, Admin chrome and MCP `serverInfo.icons`. Keep the SVG as the editable source and add a PNG rendition for MCP clients that need raster formats. Both files live in `public/`.
+
+## Source
+- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
+- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
+- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+- [`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)
+- [`docs/examples/minimal-worker/src/index.ts`](../../../docs/examples/minimal-worker/src/index.ts)
+- [`docs/migration-0.1.2.md`](../../../docs/migration-0.1.2.md)

package/docs/handbook/cloudflare/deferred-hooks-queues.md

@@ -0,0 +1,171 @@
+---
+description: Move after_* lifecycle Triggers onto Cloudflare Queues with at-least-once delivery, idempotent handlers and a DLQ.
+---
+# Deferred hooks with Queues
+
+`after_create`, `after_update`, `after_delete` and `after_publish` lifecycle Triggers run inline by default. Binding a Cloudflare Queue moves them off the request path. This page covers the guarantees, the setup, the Worker wiring and how to write handlers that survive replay.
+
+## When to defer
+
+Defer hooks that must not add request latency and that tolerate a short delay: notifications, projections, upstream API calls. Keep synchronous `before_*` hooks for validation and abuse prevention; they may read request-only input such as a CAPTCHA token, which deferred envelopes never retain.
+
+## Guarantees
+
+- The entry write commits first. D1 and the Queue do not share a transaction, so a Worker failure between them can lose the enqueue.
+- Delivery is at-least-once. A message can run more than once.
+- A rejected or ambiguous `Queue.send()` falls back to `ctx.waitUntil` (or inline when unavailable) with the same event identity. That fallback is best-effort.
+- A consumer runs every captured Trigger before acknowledging; a later failure can replay an earlier success.
+- Malformed, oversized, removed-Trigger and persistently failing messages are retried and then land in the dead-letter queue. Without a DLQ, Cloudflare discards them after `max_retries`.
+
+Handlers must therefore be idempotent. Mantle does not promise exactly-once execution.
+
+## The v1 envelope
+
+```ts
+interface DeferredHookEnvelope {
+  version: 1;
+  eventId: string;
+  triggerNames: readonly string[];
+  hook: "after_create" | "after_update" | "after_delete" | "after_publish";
+  schema: string;
+  entry: EntryRow;
+  ctxSnapshot: CtxSnapshot | null;
+}
+```
+
+Each handler receives the persisted `entry.data` as input and `ctx.event = { id, trigger, hook, schema, entry }`. Use `${ctx.event.id}:${ctx.event.trigger}` as the idempotency key; it is stable across fallback, retries and replay. `ctxSnapshot` holds normalized actor and credential metadata, never cookies, tokens or API keys.
+
+Cloudflare's 128 KB message limit is decimal and includes platform metadata. The dispatcher rejects non-JSON-safe envelopes and any encoded envelope of 127,000 bytes or more before calling `Queue.send`. Keep entry payloads well below that.
+
+## Setup
+
+```sh
+pnpm wrangler queues create mantle-internal
+pnpm wrangler queues create mantle-internal-dlq
+```
+
+```jsonc
+"queues": {
+  "producers": [{ "binding": "MANTLE_INTERNAL_QUEUE", "queue": "mantle-internal" }],
+  "consumers": [{
+    "queue": "mantle-internal",
+    "max_batch_size": 10,
+    "max_batch_timeout": 5,
+    "max_retries": 5,
+    "retry_delay": 60,
+    "dead_letter_queue": "mantle-internal-dlq"
+  }]
+}
+```
+
+These are adapter settings, not manifest grammar. See [Trigger](../reference/trigger.md) for the `lifecycle` source shape.
+
+## Worker wiring
+
+```ts
+import type { DeferredHookEnvelope } from "@aotter/mantle/runtime";
+import {
+  WorkersQueueHookDispatcher,
+  createMantleWorker,
+  createQueueHandler,
+  type MantleCloudflareEnv,
+} from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+interface Env extends MantleCloudflareEnv {
+  readonly MANTLE_INTERNAL_QUEUE: Queue<DeferredHookEnvelope>;
+}
+
+const worker = createMantleWorker<Env>({
+  plan,
+  handlers,
+  bindings: (env, conventional) => ({
+    ...conventional,
+    deferredHookDispatcher: new WorkersQueueHookDispatcher(env.MANTLE_INTERNAL_QUEUE),
+  }),
+});
+
+export default {
+  fetch: worker.fetch,
+  queue(batch, env) {
+    return createQueueHandler<Env>({ get: () => worker.getRuntime(env) })(batch, env);
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+The same Worker is producer and consumer. Opt-in adds only the dispatcher binding and the `queue` export; Auth, MCP, cache and runtime assembly stay on the standard path.
+
+## Multiplexing application queues
+
+Route on `batch.queue` when the Worker also consumes its own queues:
+
+```ts
+queue(batch, env, ctx) {
+  const mantleQueue = createQueueHandler<Env>({ get: () => worker.getRuntime(env) });
+  switch (batch.queue) {
+    case "mantle-internal": return mantleQueue(batch, env);
+    case "billing-jobs": return consumeBilling(batch, env, ctx);
+    default:
+      batch.retryAll();
+      console.error(`No consumer for queue '${batch.queue}'`);
+  }
+}
+```
+
+Application consumers own their own acknowledgement. A common pattern is to `bindMantle(await worker.getRuntime(env))` and call a Procedure, then `ack()` on success, `retry()` on `INTERNAL_ERROR` or `CONFLICT`, and `ack()` on other diagnostics so a poison message does not loop. See [Bindings](./bindings.md#queues).
+
+## Consumer semantics
+
+- At most five messages run concurrently within a delivered batch, even if `max_batch_size` is higher.
+- Runtime boot failure calls `batch.retryAll()` so per-message attempt counters advance and `max_retries` and the DLQ apply.
+- Each message is acknowledged exactly once after every captured Trigger succeeds; any failure calls `retry()` on that message only.
+
+## An idempotent D1 handler
+
+Make the event key a unique database key:
+
+```sql
+CREATE TABLE notification_jobs (
+  idempotency_key TEXT PRIMARY KEY,
+  entry_id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+```
+
+```ts
+import type { HandlerContext } from "@aotter/mantle/runtime";
+
+export async function enqueueNotification(input: Record<string, unknown>, ctx: HandlerContext) {
+  if (!ctx.event?.entry) throw new Error("lifecycle entry event required");
+  const key = `${ctx.event.id}:${ctx.event.trigger}`;
+  await (ctx.env as Env).DB.prepare(
+    `INSERT OR IGNORE INTO notification_jobs (idempotency_key, entry_id, payload, created_at)
+     VALUES (?, ?, ?, ?)`,
+  ).bind(key, ctx.event.entry.id, JSON.stringify(input), Date.now()).run();
+  return { ok: true };
+}
+```
+
+For an upstream API, send the same key as `Idempotency-Key` and throw on a non-OK response so the Queue retries. Core adds no outbox, job registry or provider retry wrapper; those remain application-owned.
+
+## The removed-Trigger footgun
+
+`triggerNames` is captured when the mutation runs. Renaming or removing a captured Trigger makes every older message fail validation at dispatch and eventually reach the DLQ; it never silently changes meaning. Drain the queue before removing a deferred Trigger, and inspect the DLQ before raising `max_retries`.
+
+## Verify
+
+In the SDK checkout the contract test is:
+
+```sh
+pnpm --filter @aotter/mantle-cloudflare test -- mantle-internal-queue.test.ts
+```
+
+For a site, run `wrangler dev`, submit a mutation that has an `after_*` Trigger, and read the consumer log. Make one handler fail once and confirm the replay carries the same `ctx.event.id` and `ctx.event.trigger`.
+
+## Source
+- [`docs/deferred-lifecycle-queues.md`](../../../docs/deferred-lifecycle-queues.md)
+- [`packages/adapters/cloudflare/src/bindings/WorkersQueueHookDispatcher.ts`](../../../packages/adapters/cloudflare/src/bindings/WorkersQueueHookDispatcher.ts)
+- [`packages/adapters/cloudflare/src/mount/cmsConfig.ts`](../../../packages/adapters/cloudflare/src/mount/cmsConfig.ts)
+- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
+- Retired-starter pattern: [`overlays/transaction/src/index.ts`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/transaction/src/index.ts)

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

@@ -0,0 +1,98 @@
+---
+description: Production checklist, the check loop, deploy and post-deploy probes, day-to-day content operations, and upgrades.
+---
+# 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 upgrade.
+
+## Before the first 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 data is not migrated.
+- Choose `MANTLE_AUTH_MODE` and store the secrets with `wrangler secret put`. See [Authentication](./authentication.md).
+- Keep `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
+- Enable observability:
+
+```jsonc
+"observability": { "enabled": true, "logs": { "head_sampling_rate": 1 } },
+"upload_source_maps": true
+```
+
+## The check loop
+
+Run the project's `check` script before every deploy. The minimal reference chains:
+
+```sh
+mantle generate && mantle generate --check && mantle validate \
+  && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs
+```
+
+Add tests and the frontend build where the project has them, then confirm index coverage for every public View:
+
+```sh
+pnpm exec mantle-harness indexes --require-public --format text
+```
+
+A required path fails on an `entries` table scan, a temporary sort or an unindexed data-field predicate. Then dry-run and deploy:
+
+```sh
+wrangler deploy --dry-run
+wrangler deploy
+```
+
+## Post-deploy verification
+
+Probe the deployed origin, not `wrangler dev`:
+
+| 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` |
+| `GET /mcp` without credentials | `401` with `WWW-Authenticate` |
+| `GET /admin` | Sign-in page; sign in with the `ADMIN_GITHUB_LOGIN` account |
+
+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:
+
+```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
+```
+
+## Operating content
+
+Sign in to Admin with a staff account. Publishing collections (`lifecycle: publishing`) follow draft, publish, verify:
+
+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.
+
+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).
+
+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. See [Site config](../reference/site-config.md).
+
+## Upgrading
+
+Read the migration notes shipped with the target release before changing versions; docs on the development branch do not describe your installed version. The 0.1.2 line removes `mantle create`, the bundle `mantle update` and `@aotter/mantle/provision`; `generate`, `validate`, `emit-openapi` and `skills` remain. To upgrade:
+
+1. Pin the new exact release for every selected package and update the lockfile through the package manager; review peer upgrades.
+2. Remove scripts that call retired commands. 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.
+
+## 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/migration-0.1.2.md`](../../../docs/migration-0.1.2.md)
+- [`docs/performance-harness.md`](../../../docs/performance-harness.md)
+- [`docs/examples/minimal-worker/README.md`](../../../docs/examples/minimal-worker/README.md)
+- [`docs/examples/minimal-worker/package.json`](../../../docs/examples/minimal-worker/package.json)
+- [`docs/examples/minimal-worker/wrangler.jsonc`](../../../docs/examples/minimal-worker/wrangler.jsonc)
+- [`docs/examples/minimal-worker/smoke.mjs`](../../../docs/examples/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)

package/docs/handbook/cloudflare/low-level-composition.md

@@ -0,0 +1,169 @@
+---
+description: Own the top-level Hono assembly with the same public primitives createMantleWorker uses, and the invariants you must keep.
+---
+# Low-level composition
+
+Use `createMantleWorker` unless the deployment must own its top-level Worker lifecycle. This page covers when that is true, what it costs, the exported building blocks, the assembly order, and the invariants a hand-assembled Worker must preserve.
+
+## When you need it
+
+You need low-level composition when the Worker entry must do something the facade's single `extend` seam cannot: run logic around every response (an audit queue, custom telemetry), select bindings or Auth per request, or interleave Mantle with another framework's router. Custom handlers, routes, credential resolvers and capability bindings do not require it; see [The conventional Worker](./conventional-worker.md).
+
+The cost is ownership. The Worker entry, error boundary, readiness handling and cache boundary become application code, and there is no automatic merge path back to `createMantleWorker`. Mantle still owns the imported adapters and standard route behavior; update them through the package version and never copy their source.
+
+## Building blocks
+
+All of these are exported from `@aotter/mantle/cloudflare` unless noted:
+
+| Export | Role |
+|---|---|
+| `createConventionalBindings(env, cacheScope?)` | `DB` to D1 driver, `ASSETS` to Admin assets, optional deployment-scoped `MANTLE_KV` |
+| `createConventionalAuth(env)`, `createAuth(config)` | Mode-driven Auth, or a curated custom factory |
+| `conventionalMcpResource(env)`, `conventionalAuthBaseURL(env)` | `<PUBLIC_ORIGIN>/mcp` and the canonical base URL |
+| `setupIncompleteAuthResponse(request, auth)` | The `503 setup_incomplete` guard for Auth-owned paths |
+| `createMantleRuntimeRef(config)` | Per-isolate runtime singleton with `get()`, `web()`, `auth`, `plan` |
+| `mountRuntimeEndpoints(app, ref)` | HTTP Triggers, `GET /api/views`, `GET /api/views/<name>` |
+| `mountAdmin(app, ref, assets)` | Admin routes and SPA |
+| `mountMantleOAuth(app, { auth, assets })` | OAuth consent and discovery, from `@aotter/mantle/admin` |
+| `createMcpApiHandler({ ref, surface, resource })` | `/mcp` (`"public"`) and `/mcp/staff` (`"staff"`) handlers |
+| `mountPublicRoutes(app, ref, options)` | Public HTML, `.md`, `llms.txt`, sitemap |
+| `applyCachePolicy(request, response, cacheTag?)` | The final cache decision |
+| `runMantleWorkerRequest(fn)` | Redacted `500 internal_error` boundary |
+| `D1DatabaseDriver`, `AssetsAssetServer`, `R2MediaStorage`, `WorkersQueueHookDispatcher`, `createQueueHandler`, `KvSiteConfigRepository`, `cloudflareTurnstileCheck`, `resolveCaller` | Individual adapters and helpers |
+| `MANTLE_RESERVED_PATH_PREFIXES`, `MANTLE_RESERVED_WELL_KNOWN_PREFIX`, `MANTLE_RESERVED_EXACT_PATHS` | Core-owned path constants |
+
+## Assembly
+
+The order is bindings, Auth, runtime ref, Hono app, runtime endpoints, Admin, OAuth, MCP handlers, then the cache policy on every response. This example adds one application-owned audit message after each request:
+
+```ts
+import { Hono } from "hono";
+import {
+  applyCachePolicy,
+  conventionalMcpResource,
+  createMantleRuntimeRef,
+  createConventionalAuth,
+  createConventionalBindings,
+  createMcpApiHandler,
+  mountAdmin,
+  mountRuntimeEndpoints,
+  runMantleWorkerRequest,
+  scopedPublicCacheTag,
+  setupIncompleteAuthResponse,
+  type MantleCloudflareEnv,
+} from "@aotter/mantle/cloudflare";
+import { mountMantleOAuth } from "@aotter/mantle/admin";
+import { plan } from "../.mantle/generated/mantle.js";
+
+interface Env extends MantleCloudflareEnv {
+  readonly AUDIT_QUEUE: Queue<{ kind: "request-complete"; path: string; status: number }>;
+}
+
+let assembled: ReturnType<typeof assemble> | undefined;
+const CACHE_SCOPE = "my-site-production";
+const CACHE_TAG = scopedPublicCacheTag(CACHE_SCOPE)!;
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    return runMantleWorkerRequest(async () => {
+      const worker = assembled ??= assemble(env);
+      if (worker.auth.ready) ctx.waitUntil(worker.auth.ready.catch((error) => {
+        if (assembled === worker) assembled = undefined;   // evict a failed assembly
+        throw error;
+      }));
+      const incomplete = await setupIncompleteAuthResponse(request, worker.auth);
+      const response = incomplete ?? await worker.fetch(request, env, ctx);
+      ctx.waitUntil(env.AUDIT_QUEUE.send({
+        kind: "request-complete",
+        path: new URL(request.url).pathname,
+        status: response.status,
+      }));
+      return response;
+    });
+  },
+} satisfies ExportedHandler<Env>;
+
+function assemble(env: Env) {
+  const bindings = createConventionalBindings(env, CACHE_SCOPE);
+  const auth = createConventionalAuth(env);
+  const ref = createMantleRuntimeRef({
+    plan,
+    bindings,
+    auth,
+    cacheScope: CACHE_SCOPE,
+    onPublicChange: purgePublicCache,
+  });
+  const app = new Hono<{ Bindings: Env }>();
+
+  mountRuntimeEndpoints(app, ref);
+  if (bindings.adminAssets) mountAdmin(app, ref, bindings.adminAssets);
+  mountMantleOAuth(app, { auth, assets: bindings.adminAssets });
+  app.get("/cache-probe", () => new Response("public", {
+    headers: { "cache-control": "public, s-maxage=60" },
+  }));
+
+  const resource = conventionalMcpResource(env);
+  const mcp = new Map([
+    ["/mcp/staff", createMcpApiHandler<Env>({ ref, surface: "staff", resource })],
+    ["/mcp", createMcpApiHandler<Env>({ ref, surface: "public", resource })],
+  ]);
+
+  return {
+    auth,
+    async fetch(request: Request, workerEnv: Env, ctx: ExecutionContext) {
+      // Prepare the canonical D1 schema before Better Auth handles a
+      // token, client, consent or CIMD request.
+      await ref.get();
+      const handler = mcp.get(new URL(request.url).pathname);
+      const response = handler?.fetch
+        ? await handler.fetch(request, workerEnv, ctx)
+        : await app.fetch(request, workerEnv, ctx);
+      return applyCachePolicy(request, response, CACHE_TAG);
+    },
+  };
+}
+
+async function purgePublicCache() {
+  try {
+    const { cache } = await import("cloudflare:workers");
+    const result = await cache.purge({ tags: [CACHE_TAG] });
+    if (!result.success) console.error("public cache purge failed", result.errors);
+  } catch (error) {
+    console.error("public cache purge failed", error);
+  }
+}
+```
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
+  "queues": { "producers": [{ "binding": "AUDIT_QUEUE", "queue": "my-site-audit" }] }
+}
+```
+
+## Invariants to keep
+
+- Await `ref.get()` before Better Auth handles a token, client, consent or CIMD request. The facade does this for Auth, `/oauth`, `/mcp`, `/admin/api` and `/.well-known/oauth*`; the example awaits before every request.
+- Evict the memoized assembly when `auth.ready` rejects, so a transient D1 failure during boot does not poison the isolate.
+- Pass every response through `applyCachePolicy`, after Admin, Auth, API, OAuth, MCP, application routes, redirects and errors. It marks private surfaces `private, no-store`, strips CDN override headers, and keeps only anonymous `200` `GET`/`HEAD` responses with explicit `public` freshness.
+- Return `setupIncompleteAuthResponse` before dispatch so misconfigured Auth fails closed on Auth-owned paths only.
+- Keep the conventional `DB` binding, both compatibility flags, and the optional `MANTLE_KV` binding. Low-level bindings may instead set `mcpCatalogKv: { namespace, scope }` with a stable deployment-owned scope, never one derived from a request.
+- Pass `reservedHttpPathPrefixes` (the exported constants plus `auth.basePath`) to `createMantleRuntimeRef` so a manifest HTTP Trigger cannot claim a Core path.
+- If you mount public routes, provide a stable `cacheScope`, pass `onPublicChange` to `createMantleRuntimeRef`, and purge the resulting scoped tag there with the Workers cache API. The facade wires this purge itself; a bare `createMantleRuntimeRef` does not.
+- Do not replace Auth, MCP or cache handling with local copies.
+
+## Adding an application queue producer
+
+The audit queue above is the pattern: declare the binding in `Env` and `wrangler.jsonc`, send from `ctx.waitUntil` after the response is decided, and keep the message contract application-owned. Consume it in the same Worker by switching on `batch.queue`; see [Deferred hooks with Queues](./deferred-hooks-queues.md#multiplexing-application-queues). For the runtime pipeline these pieces sit on, see [Runtime and adapters](../concepts/runtime-and-adapters.md).
+
+## Source
+- [`docs/cloudflare-low-level-composition.md`](../../../docs/cloudflare-low-level-composition.md)
+- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
+- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+- [`packages/adapters/cloudflare/src/mount/bootRuntimeOnce.ts`](../../../packages/adapters/cloudflare/src/mount/bootRuntimeOnce.ts)
+- [`packages/adapters/cloudflare/src/mount/cmsConfig.ts`](../../../packages/adapters/cloudflare/src/mount/cmsConfig.ts)
+- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
+- [`packages/adapters/cloudflare/src/index.ts`](../../../packages/adapters/cloudflare/src/index.ts)
+- [`packages/adapters/cloudflare/src/bindings/index.ts`](../../../packages/adapters/cloudflare/src/bindings/index.ts)
+- [`packages/adapters/cloudflare/src/mount/index.ts`](../../../packages/adapters/cloudflare/src/mount/index.ts)
+- [`packages/adapters/cloudflare/src/worker/index.ts`](../../../packages/adapters/cloudflare/src/worker/index.ts)