@aotter/mantle 0.1.2-alpha.6 → 0.1.2

package/docs/examples/host-local-admin-otp/README.md

@@ -0,0 +1,70 @@
+# Local Admin OTP
+
+This is the opt-in Dev UI path: a directly authored Cloudflare application
+that opens Mantle Admin locally with email OTP. Admin is not required to
+ship a complete service. It is not a Starter or CLI generator. Business
+Manifests live in the [Examples hub](../README.md). The notes
+Schema is example business data; `mantle generate` never invents it.
+
+Spec + adapter without Admin:
+[`docs/examples/host-minimal-worker`](../host-minimal-worker/README.md).
+
+This reference depends on every `@aotter/mantle*` package via the `latest`
+dist-tag, so a fresh install always resolves the current stable release.
+Core's test runner substitutes its exact candidate in a disposable copy.
+
+## One-shot
+
+Outside the SDK workspace, with Node 22+ and pnpm 9+:
+
+```sh
+pnpm install && pnpm generate && pnpm dev
+```
+
+`predev` copies `.dev.vars.example` to `.dev.vars` when that file is
+missing. `pnpm dev` binds `127.0.0.1:8787` so wrangler's Ready-on origin
+matches `PUBLIC_ORIGIN` (`http://127.0.0.1:8787`). Open that Ready-on
+URL. Browsing `http://localhost:8787` still serves HTML, but the OTP
+Origin header mismatches `PUBLIC_ORIGIN` and Better Auth returns
+`INVALID_ORIGIN`. Then:
+
+1. Open `http://127.0.0.1:8787/admin/sign-in`.
+2. Sign in with the bootstrap owner email from `.dev.vars` (`owner@example.com`
+   in the example).
+3. Read the one-time code from the wrangler log line
+   `[ConsoleEmailSender] auth.email-otp.sign-in → …`.
+4. Land in the Admin / Dev UI as `owner`.
+
+`mantle generate` syncs the prebuilt Admin SPA from `@aotter/mantle-admin-ui`
+into `public/_mantle/admin/`. There is no Vite or frontend build step unless
+you are developing `admin-ui` itself.
+
+## Hard requirements for Admin
+
+Admin is not a Worker route that paints itself. These must all be present:
+
+| Piece | Why |
+|---|---|
+| `@aotter/mantle-admin` and `@aotter/mantle-admin-ui` | Admin API plus the prebuilt SPA |
+| `assets.directory = ./public` and `binding = ASSETS` | Serves `/_mantle/admin/assets/*` |
+| `createAuth` `email-otp` + `ConsoleEmailSender` | Local human sign-in; code is in wrangler logs |
+| `bootstrapOwner.match: email` | First matching sign-in becomes `owner` |
+| `PUBLIC_ORIGIN` and `BETTER_AUTH_SECRET` | Auth construction; copied from `.dev.vars.example` |
+
+If `/admin` returns HTML `200` while `/_mantle/admin/assets/*` is `404`, the
+SPA white-screens. That is a missing or misconfigured `ASSETS` binding, not a
+failed frontend build. Do not put `/_mantle` in `run_worker_first`; asset
+paths must fall through to Static Assets.
+
+`ConsoleEmailSender` is the local path only. Do not wire it in production.
+
+## What this project does not do
+
+`/` is `404`: no visitor frontend is installed. Public GET
+`/api/views/published-notes` still works against fresh local D1. Conventional
+GitHub Auth (`MANTLE_AUTH_MODE`) is not used; the Worker replaces construction
+with `createAuth` while Core still owns `/admin` and `/api/auth/*`.
+
+Commit the resolved lockfile in a real application and use frozen installs
+afterwards. Configure a real D1 `database_id`, a production email sender, and
+secrets before any remote deploy. Never commit `.dev.vars`.

package/docs/examples/host-local-admin-otp/ensure-dev-vars.mjs

@@ -0,0 +1,5 @@
+import { copyFileSync, existsSync } from "node:fs";
+
+if (!existsSync(".dev.vars")) {
+  copyFileSync(".dev.vars.example", ".dev.vars");
+}

package/docs/examples/host-local-admin-otp/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "mantle-local-admin-otp",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "mantle generate",
+    "validate": "mantle validate",
+    "typecheck": "tsc --noEmit",
+    "predev": "node ensure-dev-vars.mjs",
+    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
+    "check": "node ensure-dev-vars.mjs && mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
+  },
+  "dependencies": {
+    "@aotter/mantle": "latest",
+    "@aotter/mantle-admin": "latest",
+    "@aotter/mantle-admin-ui": "latest",
+    "@aotter/mantle-cloudflare": "latest",
+    "better-auth": "1.7.2",
+    "hono": "^4.13.3",
+    "zod": "^4.5.4",
+    "aws4fetch": "^1.0.20"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260907.1",
+    "typescript": "^6.0.3",
+    "wrangler": "^4.125.0"
+  },
+  "packageManager": "pnpm@9.15.0"
+}

package/docs/examples/host-local-admin-otp/public/.gitkeep

@@ -0,0 +1 @@
+# Static Assets root. `mantle generate` writes public/_mantle/admin/ here.

package/docs/examples/host-local-admin-otp/smoke.mjs

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+
+await import("./ensure-dev-vars.mjs");
+
+const ownerEmail = "owner@example.com";
+const port = 18787;
+const origin = `http://127.0.0.1:${port}`;
+writeFileSync(".dev.vars", [
+  `PUBLIC_ORIGIN=${origin}`,
+  "BETTER_AUTH_SECRET=local-admin-otp-dev-secret-do-not-use-in-prod",
+  `ADMIN_EMAIL=${ownerEmail}`,
+  "",
+].join("\n"));
+const logs = [];
+
+const wrangler = spawn("pnpm", [
+  "exec",
+  "wrangler",
+  "dev",
+  "--local",
+  "--ip",
+  "127.0.0.1",
+  "--port",
+  String(port),
+  "--inspector-port",
+  "0",
+  "--persist-to",
+  ".wrangler/smoke",
+], {
+  env: { ...process.env, WRANGLER_SEND_METRICS: "false", CI: "1" },
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+const onLog = (chunk) => {
+  logs.push(String(chunk));
+};
+wrangler.stdout.on("data", onLog);
+wrangler.stderr.on("data", onLog);
+
+try {
+  await waitForReady(origin);
+  const signIn = await fetch(`${origin}/admin/sign-in`);
+  assert.equal(signIn.status, 200, `/admin/sign-in ${signIn.status}`);
+  const html = await signIn.text();
+  assert.match(html, /<!doctype html|<html/i);
+  const assets = [...html.matchAll(/(?:href|src)="(\/_mantle\/admin\/[^"]+)"/g)]
+    .map((match) => match[1])
+    .filter((path, index, all) => all.indexOf(path) === index);
+  assert.ok(assets.length > 0, "Admin HTML must reference /_mantle/admin assets");
+  for (const path of assets) {
+    const asset = await fetch(`${origin}${path}`);
+    assert.equal(asset.status, 200, `${path} ${asset.status}`);
+  }
+
+  const methods = await fetch(`${origin}/api/auth/methods`);
+  assert.equal(methods.status, 200);
+  assert.deepEqual(await methods.json(), { methods: [{ kind: "email-otp" }] });
+
+  const sent = await fetch(`${origin}/api/auth/email-otp/send-verification-otp`, {
+    method: "POST",
+    headers: { origin, "content-type": "application/json" },
+    body: JSON.stringify({ email: ownerEmail, type: "sign-in" }),
+  });
+  assert.equal(sent.status, 200, `send OTP ${sent.status} ${await sent.text()}`);
+  const otp = await waitForOtp();
+  const signedIn = await fetch(`${origin}/api/auth/sign-in/email-otp`, {
+    method: "POST",
+    headers: { origin, "content-type": "application/json" },
+    body: JSON.stringify({ email: ownerEmail, otp }),
+  });
+  assert.equal(signedIn.status, 200, `sign-in ${signedIn.status} ${await signedIn.text()}`);
+  const cookie = cookieHeader(signedIn);
+  assert.ok(cookie, "sign-in must set a session cookie");
+
+  const shell = await fetch(`${origin}/admin`, { headers: { cookie } });
+  assert.equal(shell.status, 200, `/admin ${shell.status}`);
+  const settings = await fetch(`${origin}/admin/api/site-settings`, { headers: { cookie } });
+  assert.equal(settings.status, 200, `/admin/api/site-settings ${settings.status}`);
+  const pkg = JSON.parse(readFileSync("node_modules/@aotter/mantle/package.json", "utf8"));
+  console.log(`Mantle ${pkg.version}: /admin assets 200, OTP ${otp} in wrangler logs, owner Admin shell 200`);
+} finally {
+  wrangler.kill("SIGTERM");
+  await waitForExit(wrangler);
+}
+
+function cookieHeader(response) {
+  const cookies = typeof response.headers.getSetCookie === "function"
+    ? response.headers.getSetCookie()
+    : [response.headers.get("set-cookie")].filter(Boolean);
+  return cookies.map((value) => value.split(";", 1)[0]).join("; ");
+}
+
+async function waitForReady(url) {
+  const deadline = Date.now() + 60_000;
+  while (Date.now() < deadline) {
+    if (wrangler.exitCode !== null) {
+      throw new Error(`wrangler exited ${wrangler.exitCode}\n${logs.join("")}`);
+    }
+    try {
+      const response = await fetch(`${url}/admin/sign-in`);
+      if (response.status === 200) return;
+    } catch {
+      // Worker still booting.
+    }
+    await delay(250);
+  }
+  throw new Error(`wrangler did not become ready\n${logs.join("")}`);
+}
+
+async function waitForOtp() {
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    const match = logs.join("").match(/Your Mantle sign-in code: (\d{6})/);
+    if (match) return match[1];
+    await delay(100);
+  }
+  throw new Error(`OTP log line missing\n${logs.join("")}`);
+}
+
+function waitForExit(child) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve();
+    }, 5_000);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/docs/examples/host-local-admin-otp/src/index.ts

@@ -0,0 +1,54 @@
+import {
+  ConsoleEmailSender,
+  createAuth,
+  createMantleWorker,
+  type MantleCloudflareEnv,
+} from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export interface Env extends MantleCloudflareEnv {
+  readonly ASSETS: Fetcher;
+  readonly BETTER_AUTH_SECRET: string;
+  readonly ADMIN_EMAIL: string;
+}
+
+const sender = new ConsoleEmailSender();
+
+export default createMantleWorker<Env>({
+  plan,
+  cacheScope: "local-admin-otp",
+  siteDefaults: (env) => ({
+    brand: "Local Admin",
+    title: "Local Admin",
+    origin: originOf(env),
+  }),
+  auth: (env) => {
+    const origin = originOf(env);
+    const secret = required(env.BETTER_AUTH_SECRET, "BETTER_AUTH_SECRET");
+    const ownerEmail = required(env.ADMIN_EMAIL, "ADMIN_EMAIL");
+    return createAuth({
+      database: env.DB,
+      baseURL: origin,
+      secret,
+      methods: [{ kind: "email-otp", sender }],
+      bootstrapOwner: { match: "email", value: ownerEmail },
+      oauthProvider: {
+        loginPage: "/admin/sign-in",
+        consentPage: "/oauth/consent",
+        scopes: ["mcp"],
+        mcpResource: `${origin}/mcp`,
+      },
+    });
+  },
+});
+
+function originOf(env: Env): string {
+  return env.PUBLIC_ORIGIN?.replace(/\/+$/, "") ?? "http://127.0.0.1:8787";
+}
+
+function required(value: string | undefined, name: string): string {
+  if (!value) {
+    throw new Error(`${name} is required. Copy .dev.vars.example to .dev.vars.`);
+  }
+  return value;
+}

package/docs/examples/host-local-admin-otp/wrangler.jsonc

@@ -0,0 +1,23 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-local-admin-otp",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-09-08",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "global_fetch_strictly_public"
+  ],
+  "observability": {
+    "enabled": true
+  },
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS"
+  },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "mantle-local-admin-otp"
+    }
+  ]
+}

package/docs/examples/{minimal-worker → host-minimal-worker}/README.md

@@ -1,14 +1,18 @@
 # Minimal Worker reference
 
 This is a directly authored, API-only application and executable consumer test.
-It is not a Starter, template catalog or CLI generator. The notes Schema/View
-is example business data; `mantle generate` never invents it.
+It is not a Starter, template catalog or CLI generator. Admin is opt-in; this
+reference has none. When humans need a console, see
+[`docs/examples/host-local-admin-otp`](../host-local-admin-otp/README.md). Business
+Manifests live in the [Examples hub](../README.md). The notes
+Schema/View is example business data; `mantle generate` never invents it.
 
 For your own project, author package.json, manifests, Worker/provider config
 and TypeScript settings for your requirements. Pin all selected `@aotter/mantle*`
-dependencies to the same intended release. This reference records alpha.17 as
-its last published baseline; Core's test runner substitutes its exact candidate
-in a disposable copy, including during a future release.
+dependencies to the same intended release. This reference depends on them via
+the `latest` dist-tag instead, so a fresh install always resolves the current
+stable release; Core's test runner substitutes its exact candidate in a
+disposable copy.
 
 Outside the SDK workspace, with Node 22+ and pnpm 9+:
 

package/docs/examples/host-minimal-worker/manifests/site.yaml

@@ -0,0 +1,25 @@
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: notes
+spec:
+  title: Notes
+  schema:
+    type: object
+    required: [title]
+    properties:
+      title: { type: string }
+  lifecycle: publishing
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: published-notes
+spec:
+  surface: public
+  from: notes
+  cache: { sharedMaxAge: 3600 }
+  fields: [id, title]
+  filter:
+    eq: { field: status, value: published }
+  limit: 20

package/docs/examples/{minimal-worker → host-minimal-worker}/package.json

@@ -6,12 +6,12 @@
     "generate": "mantle generate",
     "validate": "mantle validate",
     "typecheck": "tsc --noEmit",
-    "dev": "wrangler dev --local",
+    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
     "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.0-alpha.17",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.17",
+    "@aotter/mantle": "latest",
+    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",

package/docs/examples/host-minimal-worker/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": [
+      "@cloudflare/workers-types"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    ".mantle/generated/**/*.ts"
+  ]
+}

package/docs/handbook/cloudflare/authentication.md

@@ -5,6 +5,19 @@ description: Configure MANTLE_AUTH_MODE, secrets, the first owner and staff role
 
 Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails closed when its configuration is incomplete. This page covers the two modes, the secrets each needs, first-owner bootstrap, roles, the routes that require a session, and the Better Auth integration surface.
 
+## Local Admin: email OTP
+
+The local human path does not use `MANTLE_AUTH_MODE` or GitHub. Pass `auth` to `createMantleWorker` with `email-otp`, `ConsoleEmailSender`, and `bootstrapOwner.match: "email"`. The one-time code is printed on the wrangler log. See [Quickstart: local Admin](../start/quickstart-admin.md). `ConsoleEmailSender` is for `wrangler dev` only; production needs a real sender. The official example binds `127.0.0.1:8787` and sets `PUBLIC_ORIGIN` to that origin; Better Auth rejects OTP with `INVALID_ORIGIN` when they diverge from the origin wrangler prints.
+
+With `auth` set, the mode matrix below is not read. Core still owns `/admin` and `/api/auth/*`.
+
+For production email OTP, keep the custom `createAuth()` factory, replace
+`ConsoleEmailSender` with the application's production `EmailSender`, and keep
+`bootstrapOwner: { match: "email", value: <owner email> }`. Store the sender
+credentials and `BETTER_AUTH_SECRET` as Worker secrets. If the application has
+no transactional-email provider, use self-managed GitHub OAuth instead; never
+deploy console delivery.
+
 ## Mode matrix
 
 | Mode | Non-secret vars | Worker secrets | Must be absent |
@@ -14,7 +27,7 @@ Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails close
 
 Validation rules:
 
-- `PUBLIC_ORIGIN` is the site's HTTPS origin without a trailing slash. When unset, the adapter falls back to `http://localhost:8787`.
+- `PUBLIC_ORIGIN` is the site's HTTPS origin without a trailing slash. When unset, the adapter falls back to `http://localhost:8787`. That fallback string is not the preferred local Admin pin. The origin wrangler prints is authoritative; the Admin OTP reference binds `127.0.0.1:8787` and sets `PUBLIC_ORIGIN` to the same origin.
 - Self-managed uses the site's own GitHub OAuth app. Register its callback URL as `<PUBLIC_ORIGIN>/api/auth/callback/github`.
 - Hosted is a public PKCE client with no client secret. `MANTLE_HOSTED_AUTH_ISSUER` must be an HTTPS root origin (no path, query or fragment; `http` only for loopback). `MANTLE_HOSTED_AUTH_CLIENT_ID` must be a URL on that same origin shaped `/clients/<id>`.
 - `ADMIN_GITHUB_LOGIN` must be a valid GitHub login.
@@ -218,4 +231,6 @@ rejected; there is no introspection fallback.
 - [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
 - [`docs/auth-hosting-model.md`](../../../docs/auth-hosting-model.md)
 - [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
-- [`docs/examples/minimal-worker/.gitignore`](../../../docs/examples/minimal-worker/.gitignore)
+- [`docs/examples/host-local-admin-otp/src/index.ts`](../../../docs/examples/host-local-admin-otp/src/index.ts)
+- [`docs/examples/host-local-admin-otp/.dev.vars.example`](../../../docs/examples/host-local-admin-otp/.dev.vars.example)
+- [`docs/examples/host-minimal-worker/.gitignore`](../../../docs/examples/host-minimal-worker/.gitignore)

package/docs/handbook/cloudflare/bindings.md

@@ -17,7 +17,7 @@ Every Mantle Worker keeps both flags:
 
 ## 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 tables (`entries`, site settings, media, Auth) outside the runtime. Use `runtime.entries`, generated `bindMantle(runtime)` and Views instead.
+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
 
@@ -69,9 +69,11 @@ Omit `database_id` only for local development. Set the production id before any
 "assets": { "directory": "./public", "binding": "ASSETS" }
 ```
 
-`mantle generate` syncs the Admin SPA into `public/_mantle/admin/` when `@aotter/mantle-admin-ui` is installed. 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.
+`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.
 
-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. 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.
+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
 
@@ -157,7 +159,7 @@ Durable Objects are not a Core primitive. Use one as an application-owned coordi
 export { InventoryCoordinator } from "./commerce/InventoryCoordinator.js";
 ```
 
-The coordinator keeps its own state; Mantle entries mirror the result. See [Commerce transaction](../examples/commerce-transaction.md).
+The coordinator keeps its own state; Mantle entries mirror the result. See [Commerce inventory](../../examples/cf-primitives-commerce-inventory.md).
 
 ## Email Service: `[[send_email]]`
 
@@ -219,7 +221,7 @@ extend: ({ env }) => ({
 }),
 ```
 
-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 form](../examples/intake-form.md).
+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)
@@ -232,5 +234,5 @@ Authenticated callers (`ctx.user` set) bypass the check. The literal secret `"de
 - [`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/minimal-worker/wrangler.jsonc`](../../../docs/examples/minimal-worker/wrangler.jsonc)
-- Retired-starter patterns: [`blank/wrangler.toml`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/blank/wrangler.toml), [`overlays/transaction/wrangler.append.toml`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/transaction/wrangler.append.toml), [`overlays/transaction/src/index.ts`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/transaction/src/index.ts), [`overlays/transaction/src/mantle/config.ts`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/transaction/src/mantle/config.ts), [`overlays/intake/src/worker/features/intake/notifyIntake.ts`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/intake/src/worker/features/intake/notifyIntake.ts), [`overlays/intake/manifests/site.yaml`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/intake/manifests/site.yaml)
+- [`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)

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

@@ -0,0 +1,29 @@
+---
+description: "Mantle on ChatGPT Sites now has its own integration guide."
+---
+# Mantle on ChatGPT Sites
+
+ChatGPT Sites has a dedicated section in the Mantle handbook. Start with
+[Mantle on ChatGPT Sites](../sites/index.md) for installation, supported
+capabilities, and your first published article. This page preserves earlier
+links to the host checklist.
+
+## First deployment
+
+See [the host deployment checklist](../sites/host-reference.md#first-deployment).
+
+## Media with only an R2 binding
+
+See [R2 media integration](../sites/host-reference.md#media-with-only-an-r2-binding).
+
+## Remote MCP is a separate gate
+
+See [MCP support and authentication](../sites/host-reference.md#remote-mcp-is-a-separate-gate).
+
+## Capability boundaries
+
+See [host capability boundaries](../sites/host-reference.md#capability-boundaries).
+
+## Source
+
+See [integration sources](../sites/host-reference.md#source).

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

@@ -14,7 +14,7 @@ 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).
+`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). Local Admin with email OTP replaces Auth construction; see [Quickstart: local Admin](../start/quickstart-admin.md). Admin still requires the `ASSETS` binding.
 
 ## Options
 
@@ -158,5 +158,5 @@ The conventional set is `{ db, adminAssets, mcpCatalogKv? }`. Never drop `db`.
 - [`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)
+- [`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

@@ -168,4 +168,3 @@ For a site, run `wrangler dev`, submit a mutation that has an `after_*` Trigger,
 - [`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

@@ -1,16 +1,16 @@
 ---
-description: Production checklist, the check loop, deploy and post-deploy probes, day-to-day content operations, and upgrades.
+description: Production checklist, the check loop, deploy and post-deploy probes, day-to-day content operations, and version pins.
 ---
 # 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.
+This page is the production checklist for a Mantle Worker on Cloudflare: what to pin and configure, which checks to run before `wrangler deploy`, how to verify a deployment, how content is operated afterwards, and how to move versions.
 
 ## 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).
+- Set the production D1 `database_id` (and `account_id` if your deployment needs it) in `wrangler.jsonc`. A local `database_name` is not a production identifier, and local D1 is not production data.
+- Choose production Auth: replace local console email delivery with a real `EmailSender`, or configure `MANTLE_AUTH_MODE` for GitHub OAuth or hosted Auth. Store secrets with `wrangler secret put`. See [Authentication](./authentication.md).
 - Keep `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
 - Enable observability:
 
@@ -72,34 +72,28 @@ Sign in to Admin with a staff account. Publishing collections (`lifecycle: publi
 
 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).
+Site settings split by owner. Brand, title and description seed once from `siteDefaults` and are then edited in Admin (`owner`); each edit purges the public cache. Origin, icons, locales and media purposes are code-owned and re-sync from `siteDefaults` on every boot, so change them in the Worker and redeploy. Analytics, pixels and search-engine verification are host chrome, not Core settings; see [Site chrome](./site-chrome.md) and [Site config](../reference/site-config.md).
 
-## Upgrading
+## Changing versions
 
-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:
+Pin every selected `@aotter/mantle*` package to one exact version and keep them together. This handbook describes the snapshot in this source tree; use the docs that ship with the version you install.
 
-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.
+1. Pin the new exact release for every selected package and update the lockfile through the package manager; review peer ranges.
+2. Keep application source, Worker/D1/KV identity, origins, auth mode and secrets.
 3. Run `mantle generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests.
 4. Test local routes and authorization, then deploy.
 
-The native-table storage contract is a pre-beta breaking change. Existing
-generic-`entries` databases are unsupported: rebuild the instance and move any
-required data manually outside Mantle. New native-table instances deploy safe
-additive changes online; destructive changes are rejected and require another
-manual rebuild. Any `uniqueIndexes` tuple change is destructive. Mantle does not
-ship an in-product migration workflow for this unreleased storage format.
+Each Manifest Schema is a native table. Safe additive storage changes deploy online. Destructive changes — including any `uniqueIndexes` tuple add, remove, reorder or rewrite — are rejected; rebuild the instance and move required data outside Mantle. There is no in-product data-move workflow.
 
 ## 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)
+- [`docs/examples/host-minimal-worker/README.md`](../../../docs/examples/host-minimal-worker/README.md)
+- [`docs/examples/host-minimal-worker/package.json`](../../../docs/examples/host-minimal-worker/package.json)
+- [`docs/examples/host-minimal-worker/wrangler.jsonc`](../../../docs/examples/host-minimal-worker/wrangler.jsonc)
+- [`docs/examples/host-minimal-worker/smoke.mjs`](../../../docs/examples/host-minimal-worker/smoke.mjs)
 - [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
 - [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
 - [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)