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

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

@@ -1,166 +0,0 @@
----
-description: Assemble a Mantle Worker with createMantleWorker, add handlers and routes through extend, and respect Core-owned paths.
----
-# The conventional Worker
-
-New applications can start with `mantle generate --host cf`, which writes a
-blank home, Worker entry and selected Admin/API/MCP wiring. This page covers
-the lower-level `createMantleWorker` facade for applications that author their
-own Worker entry: its options, extension seam, readiness and reserved paths.
-
-## 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`, this manually assembled 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). A newly generated full CF project wires a separate editable blank home. Local Admin with email OTP replaces Auth construction; see [Quickstart: local Admin](../start/quickstart-admin.md). Admin still requires the `ASSETS` binding.
-
-## 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`. The MCP transport is Streamable HTTP, POST-only: no session header, no server-initiated stream (`GET` answers `405`), and `tools/call` answers `401` with an OAuth challenge so a client can authenticate mid-session and retry. Verified against the official TypeScript client SDK `@modelcontextprotocol/client` 2.0.0 in the adapter's conformance test; that pin is the gate when the SDK is upgraded.
-- 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
-worker.scheduled(controller, env, ctx); // declared scheduled Procedure Triggers
-```
-
-Queue handlers call `worker.getRuntime(env)` and then generated `bindMantle(runtime)` so they reuse the assembled runtime. Scheduled Procedure Triggers use `worker.scheduled` with expressions registered in Wrangler. See [Bindings](./bindings.md#cron-triggers), [Trigger](../reference/trigger.md#schedule-source), 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/host-local-admin-otp/src/index.ts`](../../../docs/examples/host-local-admin-otp/src/index.ts)
-- [`docs/examples/host-minimal-worker/src/index.ts`](../../../docs/examples/host-minimal-worker/src/index.ts)

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

@@ -1,170 +0,0 @@
----
-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)

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

@@ -1,169 +0,0 @@
----
-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)

package/docs/handbook/cloudflare/public-web.md

@@ -1,144 +0,0 @@
----
-description: Opt a Worker into public HTML, Markdown mirrors, llms.txt and sitemap with mountPublicRoutes, templates and a path resolver.
----
-# Public web, SEO and cache
-
-Public rendering is opt-in. A headless Worker serves Views and Triggers only; this page shows how to add server-rendered pages, their agent-readable mirrors and discovery files, and what the cache contract guarantees.
-
-## Three inputs that must agree
-
-1. `mountPublicRoutes(app, ref, { collectionRoutes, ... })` inside `extend.mount` declares which collections have URLs.
-2. A `TemplateRegistry` with an entry template (and optionally a list template) for each of those collections, passed as `templates`.
-3. A `PublicPathResolver` from `createPublicPathResolver({ collectionRoutes })`, passed as `publicPathResolver`, so canonical URLs, sitemap entries and hreflang siblings match the mounted routes.
-
-Mounting every Schema automatically is not supported: some collections are private even when they carry a slug. Without a `publicPathResolver`, `/sitemap.xml` returns `500`.
-
-## Worked example: a blog
-
-```ts
-// src/web/templates.ts
-import { createPublicPathResolver, TemplateRegistry, renderSeoTagsHtml } from "@aotter/mantle-web";
-
-export const publicPathResolver = createPublicPathResolver({
-  collectionRoutes: { posts: { segment: "posts" } },
-});
-
-export const collectionRoutes = [
-  { collection: "posts", segment: "posts", listRoute: true },
-] as const;
-
-export function createBlogTemplates(): TemplateRegistry {
-  const templates = new TemplateRegistry();
-
-  templates.registerEntryTemplate("posts", ({ entry, site, seo }) => {
-    const title = String(entry.data.title ?? site.title);
-    const meta = seo && {
-      ...seo,
-      jsonLd: { "@context": "https://schema.org", "@type": "BlogPosting", headline: title, url: seo.canonical },
-    };
-    return `<html lang="${entry.locale ?? "en"}"><head><title>${escape(title)}</title>
-      ${meta ? renderSeoTagsHtml(meta) : ""}<link rel="stylesheet" href="/blog.css"></head>
-      <body><article><h1>${escape(title)}</h1>
-      ${seo?.alternateMarkdown ? `<a href="${seo.alternateMarkdown}">Read as Markdown</a>` : ""}
-      ${renderMarkdown(String(entry.data.body ?? ""))}</article></body></html>`;
-  });
-
-  templates.registerListTemplate("posts", ({ entries, locale, site, seo }) => {
-    const items = entries.map((entry) => {
-      const href = publicPathResolver.forEntry(entry) ?? `/${locale}/posts/${entry.id}`;
-      return `<li><a href="${href}">${escape(String(entry.data.title ?? entry.id))}</a></li>`;
-    }).join("");
-    return `<html lang="${locale}"><head><title>Blog · ${escape(site.brand)}</title>
-      ${seo ? renderSeoTagsHtml(seo) : ""}</head><body><ul>${items}</ul></body></html>`;
-  });
-
-  return templates;
-}
-```
-
-```ts
-// worker entry
-export default createMantleWorker<Env>({
-  plan,
-  templates: createBlogTemplates(),
-  publicPathResolver,
-  siteDefaults: (env) => ({ /* ... */ origin: env.PUBLIC_ORIGIN, locales: ["en", "zh-TW"] }),
-  extend: ({ env }) => ({
-    mount({ app, ref }) {
-      mountPublicRoutes(app as never, ref, {
-        collectionRoutes: [...collectionRoutes],
-        notFoundRenderer: async () => htmlNotFound(),
-        liveDev: new URL(env.PUBLIC_ORIGIN).hostname === "localhost",
-      });
-    },
-  }),
-});
-```
-
-Templates return complete HTML strings; the renderer prepends the doctype. Escape every value you interpolate. Analytics, pixels and verification tags are host chrome — add them in the template or on Cloudflare. See [Site chrome](./site-chrome.md).
-
-## Template signatures
-
-```ts
-templates.registerEntryTemplate(collection, ({ entry, site, mediaAssets?, seo? }) => string);
-templates.registerListTemplate(collection, ({ collection, locale, entries, site, mediaAssets?, seo? }) => string);
-```
-
-`seo` is a composed `SeoMeta`:
-
-| Field | Content |
-|---|---|
-| `canonical` | Absolute canonical URL from `site.origin` and the resolved path |
-| `alternateMarkdown` | Absolute `.md` mirror URL, or `null` when the entry has no Markdown body |
-| `hreflangs` | One row per locale plus `x-default` on multi-locale sites |
-| `description`, `og`, `twitter` | Description, Open Graph and Twitter card blocks |
-| `jsonLd` | A default object; replace it before rendering, as the example does |
-
-`renderSeoTagsHtml(seo)` emits the corresponding tags. Entry pages also get `<link rel="alternate" type="text/markdown">` so crawlers and agents can fetch clean Markdown.
-
-## Routes produced
-
-| Route | Condition |
-|---|---|
-| `GET /` → `302` to `/<canonicalLocale>` | `homeRenderer` set |
-| `GET /:locale`, `GET /:locale.md` | `homeRenderer` set; body from `homeMarkdown` or the `homeSlug` entry |
-| `GET /:locale/<segment>`, `GET /:locale/<segment>.md` | `listRoute: true` |
-| `GET /:locale/<segment>/:slug` | always |
-| `GET /:locale/<segment>/:slug.md` | `markdownMirror` not `false` (default on) |
-| `GET /:locale/<segment>/:slug?preview=1` | staff session; renders live, `private, no-store` |
-| `GET /llms.txt`, `GET /:locale/llms.txt` | always |
-| `GET /sitemap.xml` | always; a urlset, or a sitemap index linking `/sitemap.xml?part=1&cursor=...` parts |
-| `GET /robots.txt` | always; `Allow: /` plus the sitemap URL |
-
-`CollectionRouteConfig` fields: `collection`, `segment` (empty string mounts entries directly under `/:locale/`), `listRoute` (default `false`), `markdownMirror` (default `true`), `homeSlug` (collapse one slug to `/:locale`). `slugOverrides` serve one `(collection, slug)` pair from your own renderer and take precedence over preview and standard rendering. `notFoundRenderer` is required; every miss falls through it. `liveDev` switches entry and list responses to `private, no-store` for local work.
-
-Only entries with `status: published` render. Drafts never appear on pages, mirrors, `llms.txt` or the sitemap; preview needs a staff session and answers `401` or `403` otherwise.
-
-## Pagination
-
-Lists and `llms.txt` return 50 entries per page, ordered `updatedAt DESC, id DESC`, with a forward `cursor`. A continuation adds `Link: <...?cursor=...>; rel="next"`; HTML lists also get a visible `<nav aria-label="Pagination">` Next link, and `llms.txt` appends a `## Continue` section. Sitemap parts hold up to 2,000 URLs divided by the locale count. See [Views](../concepts/views.md) for View-level paging.
-
-## Cache contract
-
-With a valid `cacheScope`, public responses carry `Cache-Control: public, max-age=0, s-maxage=300` and a deployment-scoped cache tag. The facade's final policy keeps that only for anonymous `200` `GET`/`HEAD` responses with no request `Cookie` or `Authorization` and no `Set-Cookie`, and adds `Vary: Cookie, Authorization`. Everything else becomes `private, no-store`, and CDN override headers are removed.
-
-Publishing-content and site-setting writes purge the scoped tag through the native Workers cache API. Purge is best effort after the canonical write. Operational records and static assets are outside that boundary. Enable the cache with `"cache": { "enabled": true }`; see [Bindings](./bindings.md#workers-cache).
-
-> **Warning**
-> The local emulator does not simulate the entrypoint Workers Cache or its purge API. Verify `cf-cache-status` and post-publish invalidation on a deployed environment, not with `wrangler dev`.
-
-## Static assets for templates
-
-Reference CSS, JS and icons by root path (`/blog.css`, `/site-icon.svg`); the `ASSETS` binding serves them from `public/`. Keep public content prefixes in `run_worker_first` so a static file never shadows a rendered route, and leave asset paths out of it so they bypass the Worker.
-
-## Source
-- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
-- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/mantle-web/README.md`](../../../packages/mantle-web/README.md)
-- [`packages/mantle-web/src/model/TemplateRegistry.ts`](../../../packages/mantle-web/src/model/TemplateRegistry.ts)
-- [`packages/mantle-web/src/model/SeoMeta.ts`](../../../packages/mantle-web/src/model/SeoMeta.ts)
-- [`packages/mantle-web/src/service/SeoMetaComposer.ts`](../../../packages/mantle-web/src/service/SeoMetaComposer.ts)
-- [`packages/mantle-web/src/service/PublicPathResolver.ts`](../../../packages/mantle-web/src/service/PublicPathResolver.ts)
-- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
-- [`docs/performance-harness.md`](../../../docs/performance-harness.md)