@aotter/mantle 0.2.0-alpha.8 → 0.2.0

package/docs/examples/app-shell/src/routes.ts

@@ -2,10 +2,13 @@ import type { Caller } from "@aotter/mantle/contracts";
 import { signInPage } from "./sign-in.js";
 
 /**
- * App-owned routes, tried before Admin, MCP and REST. Return undefined to fall through.
+ * App-owned routes, tried before REST. Return undefined to fall through. Paths under /admin and /mcp never reach here, and
+ * neither do Better Auth's (/api/auth/*, /oauth/consent*, /.well-known/oauth-*). A root catch-all page (/:slug) must
+ * still return undefined for the paths of the app's own HTTP Triggers (REST), or it shadows them.
  * GET /sign-in: member sign-in (src/sign-in.ts); a member page sends anonymous visitors there with signInRedirect.
- * AGENT: add visitor pages (HTML, SEO, feeds) and callbacks/webhooks here. A callback must verify the raw Request
- * (signature, timestamp) before it reads the body as JSON or calls a generated Procedure.
+ * AGENT: add visitor pages and callbacks/webhooks here. Visitor pages carry everything in `mantle help public-pages`
+ * (canonical, Open Graph, JSON-LD, answer block, .md alternates, sitemap.xml, robots.txt, llms.txt; recipes example).
+ * A callback must verify the raw Request (signature, timestamp) before it reads the body as JSON or calls a generated Procedure.
  */
 export async function appRoutes(request: Request, _env: Env, _context: { caller: () => Promise<Caller>; waitUntil: (task: Promise<unknown>) => void }): Promise<Response | undefined> {
   if (new URL(request.url).pathname === "/sign-in" && request.method === "GET") return signInPage();

package/docs/examples/app-shell/src/service.ts

@@ -43,7 +43,8 @@ export async function fetchService(request: Request, env: Env, context: Executio
     const ownAuth = await withAuthTasks(context.waitUntil.bind(context), () => authRoutes(auth!, { methods: [{ kind: "email-otp" }], resolver: caller })(request));
     if (ownAuth) return respond(ownAuth);
     const url = new URL(request.url);
-    const own = await appRoutes(request, env, { caller, waitUntil: context.waitUntil.bind(context) });
+    // /admin and /mcp belong to Admin and MCP: a root catch-all page in src/routes.ts (/:slug) never shadows them.
+    const own = /^\/(?:admin|mcp)(?:\/|$)/.test(url.pathname) ? undefined : await appRoutes(request, env, { caller, waitUntil: context.waitUntil.bind(context) });
     if (own) return respond(own);
     let response: Response | undefined;
     if (url.pathname === "/admin/api" || url.pathname.startsWith("/admin/api/")) {
@@ -56,8 +57,8 @@ export async function fetchService(request: Request, env: Env, context: Executio
       }
       response = await serveAdmin(request, env);
     } else if (/^\/mcp(?:\/admin)?\/*$/.test(url.pathname)) {
-      // --- MCP (optional): delete this branch with the MCP plugins in auth.ts if the app has no MCP.
-      serveMcpHandler ??= serveMcp(tools, { ...options, apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } });
+      // --- MCP / OAuth (deliberate exception): remove with the auth plugins only for intentional asymmetric exposure.
+      serveMcpHandler ??= serveMcp(tools, { ...options, authorizationScopes: ["offline_access"], apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } });
       response = await serveMcpHandler(request, env);
     } else {
       response = await serveRest(request, env);

package/docs/examples/club-events/README.md

@@ -23,6 +23,9 @@ over MCP. Only members the officers listed in Admin can sign up. Officers see ev
   Schema check; no View or Trigger exposes it). `src/signup.ts` replaces the shell's allow-all `allowSignUp` with a
   Store lookup as a system caller, so any other email gets 403 at sign-in and no account. To invite another officer
   through Admin, list their email in `members` first.
+- **An event with its attendees in one read**: the admin View `event-roster` returns each event with an `attendees`
+  JSON array built by `json_group_array(json_set('{}', ...))` in a correlated subquery, so an event nobody joined has
+  `[]`. PostgreSQL writes it with `jsonb_agg(jsonb_build_object(...))`; see `mantle help sql-patterns`.
 - **Member MCP tool**: the `register-mcp` Trigger (`surface: public`) exposes `register` on `/mcp`, so the member's AI
   registers with the member's own sign-in.
 
@@ -36,9 +39,11 @@ over MCP. Only members the officers listed in Admin can sign up. Officers see ev
 
 ## Run it
 
+This runs the example by itself, to read and try. For your own app, run `mantle init` and take only the patterns you need into its manifests and `src/` (`mantle help examples`).
+
 ```sh
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
-cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/
+npx mantle init my-app
+cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/   # run the example as is
 cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
 cp .dev.vars.example .dev.vars && pnpm db:init && pnpm dev
 pnpm smoke

package/docs/examples/club-events/manifests/club-events.yaml

@@ -86,6 +86,21 @@ spec:
     FROM registrations r JOIN events e ON e.id = r.eventId
     ORDER BY r.created_at DESC, r.id DESC
 ---
+# Officers' roster: each event with its attendees as one JSON array, so one read answers "who is coming".
+# The correlated subquery gives [] for an event nobody registered for (a LEFT JOIN + GROUP BY would give one empty object).
+# SQLite/D1 builds the objects with json_set; on PostgreSQL write jsonb_agg(jsonb_build_object('memberName', r.memberName)).
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: event-roster }
+spec:
+  title: Event roster
+  surface: admin
+  requires: { auth: { all: [ctx.admin] } }
+  sql: |
+    SELECT e.id, e.title, e.startsAt AS "startsAt", e.seats_taken AS "seatsTaken",
+      (SELECT json_group_array(json_set('{}', '$.memberName', r.memberName)) FROM registrations r WHERE r.eventId = e.id) AS attendees
+    FROM events e ORDER BY e.startsAt, e.id
+---
 # The member-facing entry: a ref handler checks the event, then runs register-write.
 apiVersion: cms.mantle.aotter.net/v2
 kind: Procedure
@@ -165,6 +180,13 @@ spec:
   source: { kind: http, method: POST, path: /api/registrations/cancel }
   target: { procedure: cancel-registration }
 ---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: cancel-registration-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: cancel-registration }
+---
 # Officers add records through declared Procedures: operational collections have no generic create in Admin.
 # collectionAction puts the Procedure's button and input form in that collection's list header; the admin MCP
 # Trigger is what makes it an Admin operation (and lets the officers' AI do the same).

package/docs/examples/club-events/smoke.mjs

@@ -105,7 +105,13 @@ await smoke(async ({ call, mcp, signIn, sql, owner, step, logs }) => {
   assert.equal((await call("GET", "/admin/api/entries?collection=registrations", { cookie: bob })).status, 403);
   assert.equal((await call("GET", "/admin/api/me", { cookie: bob })).status, 403);
   assert.ok(all.body.items.every(r => r.data.memberName && r.data.memberName !== r.data.member), JSON.stringify(all.body.items));
-  step("officers see every member's registrations, with names, through Admin's API; a member gets 403 on Admin");
+  const roster = await call("GET", "/admin/api/views/event-roster", { cookie: admin });
+  assert.equal(roster.status, 200, JSON.stringify(roster.body));
+  const attendees = row => (typeof row.attendees === "string" ? JSON.parse(row.attendees) : row.attendees).map(a => a.memberName).sort();
+  for (const row of roster.body.rows) assert.equal(attendees(row).length, row.seatsTaken, JSON.stringify(row));
+  assert.ok(roster.body.rows.some(row => attendees(row).length > 0), JSON.stringify(roster.body.rows));
+  assert.equal((await call("GET", "/admin/api/views/event-roster", { cookie: bob })).status, 403);
+  step("officers see every member's registrations, with names, through Admin's API; and every event with its attendees as one JSON array (event-roster); a member gets 403 on Admin");
 
   const entry = async id => (await call("GET", `/admin/api/entries/${id}?collection=events`, { cookie: admin })).body.entry;
   const before = await seatsOf(hike.id), read = await entry(hike.id);

package/docs/examples/club-events/src/handlers.ts

@@ -17,7 +17,7 @@ export const handlers: Handlers = {
       return await store.procedures["register-write"]({ eventId, member: caller.subject, memberName: user?.name || user?.email || caller.subject });
     } catch (error) {
       // register-write's only Schema check is the capacity one.
-      if (error instanceof ContractError && error.code === "CONFLICT" && error.message.startsWith("A check of the Schema failed"))
+      if (error instanceof ContractError && error.code === "CONFLICT" && error.fields?.kind === "check" && error.fields.schema === "events")
         throw new ContractError("CONFLICT", "The event is full.", "procedures/register");
       throw error;
     }

package/docs/examples/purchasing/README.md

@@ -14,6 +14,13 @@ that have been waiting too long.
   `change-amount`, `mark-ordered`, `confirm-order`). The column is `requestStatus` because `status` is reserved for
   publishing Schemas. `requests` and `ledger` set `readOnly: true`, so Admin's generic editor cannot bypass the state
   machine (for example by moving an ordered request back to `submitted` and approving it again).
+- **A status chosen at submission**: `submit-request` uses `CASE WHEN input.amount <= 100 THEN 'approved' ELSE
+  'submitted' END`. A small request also spends the budget and writes its ledger row in the same program, so
+  `remaining >= 0` refuses all three when it would overspend. Those two statements find the request by
+  `created_at = now()` (the instant of this program) and `NOT EXISTS` a ledger row, so the threshold is written only in
+  the `CASE`. Larger requests wait for an admin. An auto-approved request sends no approval email, and the daily cron
+  orders it from the supplier (it already retries every `approved` request); route small requests through a `ref`
+  handler like `approve-request` if they must be ordered and announced at once.
 - **Admin-only operations**: `approve-request` and `reject-request` declare `requires: ctx.admin` and a `target`, so
   Admin shows them as operations on a request. Their `kind: mcp, surface: admin` Triggers make them
   `approve_request` / `reject_request` tools on `/mcp/admin`. They are not listed on `/mcp`.
@@ -56,11 +63,13 @@ scheme.
 - Need another approval flow? Copy the pattern: a ref Procedure (admin-only, side effects) that wraps a guarded SQL
   write Procedure (one transaction).
 
-## Copy
+## Run it
+
+This runs the example by itself, to read and try. For your own app, run `mantle init` and take only the patterns you need into its manifests and `src/` (`mantle help examples`).
 
 ```sh
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
-cp -R node_modules/@aotter/mantle/docs/examples/purchasing/. my-app/
+npx mantle init my-app
+cp -R node_modules/@aotter/mantle/docs/examples/purchasing/. my-app/   # run the example as is
 cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
 cp .dev.vars.example .dev.vars          # then set SUPPLIER_API_URL and SUPPLIER_WEBHOOK_SECRET
 pnpm db:init && pnpm db:seed && pnpm dev

package/docs/examples/purchasing/manifests/purchasing.yaml

@@ -48,10 +48,12 @@ spec:
   title: Budget ledger
   lifecycle: operational
   indexes: [[createdAt, id]]
+  # One row per spending request.
+  uniqueIndexes: [[requestId]]
   uiSchema: { list: { primaryField: department, columns: [amount, remainingAfter, requestId] } }
   schema:
     type: object
-    readOnly: true # written only by approve-request-write
+    readOnly: true # written only by approve-request-write and submit-request
     additionalProperties: false
     required: [requestId, department, amount, remainingAfter]
     properties:
@@ -117,6 +119,7 @@ kind: Procedure
 metadata: { name: submit-request }
 spec:
   title: Submit a purchase request
+  description: Submit a purchase request against an existing department budget; a request of 100 or less is approved at once and spends the budget.
   requires: { auth: { all: [ctx.user] } }
   input:
     type: object
@@ -127,11 +130,26 @@ spec:
       amount: { type: integer, minimum: 1 }
       department: { type: string }
   output: { type: object }
+  # One program. CASE picks the status: up to 100 is approved now, more waits for an admin. The budget and ledger
+  # statements then act only on "the request this program approved": the caller's, created by this program
+  # (created_at = now(), the same instant Mantle writes into created_at), approved, and with no ledger row yet. So the
+  # threshold lives only in the CASE, and remaining >= 0 refuses all three statements when a small request would
+  # overspend. A pending request matches nothing there, which a set form (IN (SELECT ...), INSERT ... SELECT) allows.
   handler:
     sql: |
       INSERT INTO requests (title, amount, department, requestStatus)
-      SELECT input.title, input.amount, b.department, 'submitted' FROM budgets b WHERE b.department = input.department
-      RETURNING id, version
+      SELECT input.title, input.amount, b.department, CASE WHEN input.amount <= 100 THEN 'approved' ELSE 'submitted' END
+      FROM budgets b WHERE b.department = input.department
+      RETURNING id, version, requestStatus AS "requestStatus";
+      UPDATE budgets SET remaining = remaining - (SELECT SUM(r.amount) FROM requests r WHERE r.department = budgets.department
+          AND r.author_id = auth.uid() AND r.created_at = now() AND r.requestStatus = 'approved'
+          AND NOT EXISTS (SELECT 1 FROM ledger l WHERE l.requestId = r.id))
+      WHERE department IN (SELECT r.department FROM requests r WHERE r.author_id = auth.uid() AND r.created_at = now()
+          AND r.requestStatus = 'approved' AND NOT EXISTS (SELECT 1 FROM ledger l WHERE l.requestId = r.id));
+      INSERT INTO ledger (requestId, department, amount, remainingAfter)
+      SELECT r.id, r.department, r.amount, b.remaining FROM requests r JOIN budgets b ON b.department = r.department
+      WHERE r.author_id = auth.uid() AND r.created_at = now() AND r.requestStatus = 'approved'
+        AND NOT EXISTS (SELECT 1 FROM ledger l WHERE l.requestId = r.id)
 ---
 # The requester may change the amount while the request is still 'submitted'. The version moves on, so an admin
 # approving the version they reviewed before the change gets a 409 and looks again.
@@ -140,6 +158,7 @@ kind: Procedure
 metadata: { name: change-amount }
 spec:
   title: Change the amount of my request
+  description: Change the amount of the signed-in member's submitted purchase request.
   requires: { auth: { all: [ctx.user] } }
   restrict: { requests: "author_id = auth.uid()" }
   input:
@@ -291,11 +310,25 @@ spec:
 ---
 apiVersion: cms.mantle.aotter.net/v2
 kind: Trigger
+metadata: { name: submit-request-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-request }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
 metadata: { name: change-amount-http }
 spec:
   source: { kind: http, method: POST, path: '/api/requests/{id}/amount' }
   target: { procedure: change-amount }
 ---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: change-amount-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: change-amount }
+---
 # Admin MCP tools: an AI agent connected to /mcp/admin can approve or reject.
 apiVersion: cms.mantle.aotter.net/v2
 kind: Trigger

package/docs/examples/purchasing/smoke.mjs

@@ -171,6 +171,20 @@ try {
     assert.deepEqual(received.map(order => order.reference), [laptop, projector]);
     assert.deepEqual(await statusAndOrder(projector), { status: "ordered", supplierOrderId: "SUP-2" });
     step("daily cron retries the failed supplier order (system caller) and emails every admin about requests pending more than 3 days, and only those");
+
+    const small = await call("POST", "/api/requests", { cookie: bob, body: { title: "Pens", amount: 50, department: "Engineering" } });
+    assert.equal(small.status, 200, JSON.stringify(small.body));
+    const pens = small.body.results[0][0];
+    assert.equal(pens.requestStatus, "approved");
+    const spent = await remaining("Engineering");
+    assert.deepEqual((await ledgerRows()).filter(r => r.requestId === pens.id), [{ requestId: pens.id, amount: 50, remainingAfter: spent }]);
+    await query(`UPDATE budgets SET remaining = 20 WHERE department = 'Design'`);
+    const ledgerBefore = (await ledgerRows()).length, requestsBefore = (await query("SELECT count(*) AS n FROM requests"))[0].n;
+    assert.equal((await call("POST", "/api/requests", { cookie: alice, body: { title: "Tape", amount: 30, department: "Design" } })).status, 409);
+    assert.equal(await remaining("Design"), 20);
+    assert.equal((await ledgerRows()).length, ledgerBefore);
+    assert.equal((await query("SELECT count(*) AS n FROM requests"))[0].n, requestsBefore);
+    step("CASE approves a request of 100 or less at submission: the status, the budget and the ledger row commit together, and one that would overspend is refused with nothing written");
   }, { vars: { EMPLOYEE_DOMAIN: "example.test", SUPPLIER_API_URL: `http://127.0.0.1:${supplier.address().port}/orders`, SUPPLIER_WEBHOOK_SECRET: SECRET } });
 } finally {
   supplier.close();

package/docs/examples/purchasing/src/handlers.ts

@@ -14,7 +14,7 @@ export const handlers: Handlers = {
     } catch (error) {
       // The declared budget check is a business refusal, not a server error. Nothing was written.
       // The approval's only Schema check is the budget one.
-      if (error instanceof ContractError && error.code === "CONFLICT" && error.message.startsWith("A check of the Schema failed"))
+      if (error instanceof ContractError && error.code === "CONFLICT" && error.fields?.kind === "check" && error.fields.schema === "budgets")
         throw new ContractError("CONFLICT", "The department budget cannot cover this request.", "procedures/approve-request");
       throw error;
     }

package/docs/examples/recipes/README.md

@@ -25,11 +25,13 @@ Search for `AGENT:` for what an app must still provide: layout and styling, cach
 - Need members to see or edit only their own rows? Add club-events' `restrict: { recipes: "author_id = auth.uid()" }` on a View.
 - Need review before publishing, or an AI that approves? Add purchasing's guarded status transitions and admin MCP.
 
-## Copy
+## Run it
+
+This runs the example by itself, to read and try. For your own app, run `mantle init` and take only the patterns you need into its manifests and `src/` (`mantle help examples`).
 
 ```sh
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
-cp -R node_modules/@aotter/mantle/docs/examples/recipes/. my-app/
+npx mantle init my-app
+cp -R node_modules/@aotter/mantle/docs/examples/recipes/. my-app/   # run the example as is
 cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
 ```
 

package/docs/handbook/cloudflare/authentication.md

@@ -12,6 +12,8 @@ Mantle supplies the database adapter, schema generation and caller resolution:
 
 ## `auth.ts`
 
+> **Verification status:** the GitHub social-provider and magic-link recipes have not yet been exercised end to end against real deployed provider flows.
+
 Copy `src/auth.ts` from the [app shell](../../examples/app-shell/README.md), which CI runs from the packed packages;
 installed, it is `node_modules/@aotter/mantle/docs/examples/app-shell/src/auth.ts`. Its essentials:
 
@@ -78,6 +80,7 @@ after success; invitations still work when email is absent.
 `databaseHooks.user.create.after` (and user.update.after for a later email verification). Only the first matching signup wins (case-insensitive); email matching requires emailVerified=true (required for bootstrap).
 D1 uses one conditional UPDATE; PostgreSQL uses a transaction advisory lock before UPDATE, avoiding concurrent winners.
 A blocked promotion logs a warning. A GitHub rule requires a configured trusted GitHub provider/profile mapper.
+The promotion runs after Better Auth creates the user, so the first sign-in response (and a cached session payload) can still show the previous role, while authorization re-reads the role on every request and `/admin/api/me` and later sessions show the admin role.
 Helpers run no boot queries or DDL.
 
 ## Worker entry
@@ -184,10 +187,24 @@ The default is one instance with `admin` and `user` roles. An app that keeps two
 staff and customers) can run one Better Auth instance per population in the same Worker; every Mantle primitive
 takes the instance it works on:
 
-- Give each instance its own `basePath`, `advanced.cookiePrefix`, `secret` and table names (`user.modelName`,
-  `session.modelName`, ... and plugin `schema` options). Keep each instance's options in its own module and pass
-  one `--auth` per module to `mantle generate`; the tables are merged into one migration, and two instances that
-  define the same table differently are refused. The native adapter follows each instance's mapping.
+- Give each instance its own `basePath`, `advanced.cookiePrefix`, `secret` and core table names (`user.modelName`,
+  `session.modelName`, `account.modelName`, `verification.modelName`). Keep each instance's options in its own
+  module and pass one `--auth` per module to `mantle generate`; the tables are merged into one migration, and two
+  instances that define the same table differently are refused. The native adapter follows each instance's mapping.
+- Better Auth plugin factories share their schema object, so differing plugin field/model mappings across instances
+  in one Worker override each other. Use one of two supported ways:
+  1. Separate the instances by core table names only and leave every plugin mapping at its default.
+  2. When plugin tables must differ (`jwt`'s `jwks`, `@better-auth/oauth-provider`'s `oauth*` tables), map them
+     explicitly in every instance, the default one included, and give each instance its own copy of the plugin's
+     schema right after constructing it:
+     `const keys = jwt({ schema: { jwks: { modelName: "staff_jwks" } } }); const plugin = { ...keys, schema: structuredClone(keys.schema) };`
+
+  `mantle generate` refuses anything else when two or more `--auth` instances use the same plugin (`jwt`, `admin`,
+  `oauth-provider`, `two-factor`, `phone-number`, `anonymous`, `siwe`, `device-authorization`) and a mapping exists
+  while an instance keeps the shared schema object, or two instances resolve a mapping to the same name (generate
+  cannot tell an identical mapping from an inherited one, so mapped names must differ between instances). Build
+  every instance's plugins in the same order in the Worker as in `--auth`; an instance built earlier than a mapped
+  one can still inherit its mapping, which generate cannot see.
 - One `authLoader(load, cookiePrefix)` per instance; call `resolveCaller(request, loader)` with the instance the
   route belongs to, and mount `authRoutes(loader, ...)` per instance (it guards that instance's `/admin/*`). The
   loader takes `cookiePrefix` separately on purpose: it checks the cookie before loading Better Auth, so anonymous

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

@@ -1,9 +1,11 @@
 # Mantle on ChatGPT Sites
 
+> **Verification status:** this guide is experimental and has not yet been exercised end to end on a real ChatGPT Site.
+
 Treat the Site as an existing TypeScript host. Import selected generated Views/Procedures, pass the host's native handle and verified Caller, and compose only the surfaces it supports. Use [partial integration](../../skills/integrate/SKILL.md); Mantle supplies no Sites-specific identity or deployment adapter.
 
 Choose postgres or sqlite according to the host's actual SQL executor. Custom handles are app-owned; a structural match alone does not guarantee driver semantics. [Database boundaries](../concepts/runtime-and-adapters.md) defines the supported drivers.
 
-The runtime never creates, alters or checks tables. Apply initial `schema.sql` and selected auth/site DDL only to an empty database. For later changes the agent diffs regenerated SQL, writes and rehearses a host-native migration on a copy, and applies it before publishing new code. Cloud executes migrations at deploy time. Destructive/type changes require explicit data migration; Mantle drops nothing.
+The runtime never creates, alters or checks tables. Apply initial `schema.sql` and selected auth/site DDL only to an empty database. For later changes the agent diffs regenerated SQL, writes and rehearses a host-native migration on a copy, and applies it before publishing new code. Destructive/type changes require explicit data migration; Mantle drops nothing.
 
-Use the Site's native publication workflow. Configure trusted origin and verified identity there; never construct a system/admin Caller from browser input. Serving Admin also requires its separate assets and shell security contract. Scheduling and storage provisioning belong to the host.
+Use the Site's native publication workflow. Configure trusted origin and verified identity there; never construct a system/admin Caller from browser input. Serving Admin also requires its app-built assets and shell security contract. Scheduling and storage provisioning belong to the host.

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

@@ -32,7 +32,7 @@ The runtime never creates, alters or checks tables. Boot and requests run no DDL
 
 For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code. Cloud executes migrations at deploy time.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code.
 
 Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
@@ -40,6 +40,29 @@ For D1, create a migration with `pnpm exec wrangler d1 migrations create <databa
 
 For PostgreSQL, use the app's migration tool and deployment credentials. Plan lock waits and long index builds there; request credentials need no DDL privileges. Configure session settings on the role/database as described in [native execution](../guides/native-execution.md#postgresql-settings). Hyperdrive query caching must be disabled for authority and mutation visibility.
 
+## Latency placement and D1 read replication
+
+Measure these options against the application's real traffic; neither is a
+default latency guarantee. [Smart Placement](https://developers.cloudflare.com/workers/configuration/placement/)
+can move fetch execution closer to observed back-end services:
+
+```jsonc
+"placement": { "mode": "smart" }
+```
+
+For globally distributed, read-heavy D1 traffic, enable
+[read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/)
+on the database and pass one request-scoped `env.DB.withSession(...)` handle to
+the selected generated Views, Procedures and Store. Those D1 entry points accept
+`D1DatabaseSession`. Without the Sessions API, queries continue to use the primary.
+
+Use `first-unconstrained` only when a replica snapshot is acceptable,
+`first-primary` when the flow must start from the latest primary state, or carry
+a bookmark between logical sessions for sequential consistency. Reuse the same
+session within that logical flow; all writes still go to the primary. Keep fresh
+authentication/authorization checks and mutation/read-after-write paths on their
+required current-authority path rather than weakening them for replica latency.
+
 ## Operate
 
 Enable Workers Logs and traces in production. The top-level `observability.enabled` alone does not enable traces:

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

@@ -20,9 +20,8 @@ Each media purpose in `siteDefaults.media.purposes` lists mime **slots** and a b
 `required` entries use `<input accept>` grammar (full mime, comma list, or a subtype shorthand such as `webp`);
 `maxBytes` must cover every mime the slots allow, keyed by the full mime type.
 
-OSS applications own their R2 binding, public bucket URL and S3 credentials.
-Mantle Cloud supplies that wiring by default; the OSS package has no Cloud API
-or credential management. Import `r2MediaStorage` from `@aotter/mantle/media/r2`:
+Applications own their R2 binding, public bucket URL and S3 credentials; the SDK
+package does not manage them. Import `r2MediaStorage` from `@aotter/mantle/media/r2`:
 
 ```ts
 const storage = r2MediaStorage({

package/docs/handbook/cloudflare/service-entry.md

@@ -81,6 +81,9 @@ export default {
         if (shell) return shell;
         // Your public frontend/web.ts routes can use an anonymous Caller without
         // loading auth; their generated SQL still controls publication visibility.
+        // Mounted here, after every Mantle surface, a root catch-all page (/:slug)
+        // cannot shadow /admin, /mcp or REST. Mount them earlier only behind a
+        // guard that skips those paths, as the app shell does.
         return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
       } catch (error) { return surfaceFailure(error); }
     });
@@ -88,8 +91,11 @@ export default {
 };
 ```
 
-Remove imports and array entries for omitted surfaces. `mcp.ts` exists only when
-the manifest has an MCP surface, and requires the documented optional MCP peer.
+Keep the MCP and REST entries together for the normal symmetric path. For a deliberate
+asymmetric exception, remove the omitted surface's imports and array entry. `mcp.ts`
+exists only when the manifest has an MCP surface and requires the documented optional
+MCP peer. An application that deliberately does not mount MCP need not import generated
+`mcp.ts`; outside the entry import graph, it contributes nothing to the bundle.
 Pass the same handlers to each selected surface that exposes ref Procedures.
 Bind site/media/identity capabilities through the selected Admin/MCP
 options; do not expose native auth administrative routes without `authRoutes` or
@@ -106,12 +112,19 @@ its collection parameter selects only a generated table and visibility policy.
 
 ## Workers assets and secrets
 
+`mantle generate --admin --wrangler wrangler.jsonc` sets the selected assets
+directory. A new assets block defaults to `binding: "ASSETS"`, `run_worker_first: true`
+and `html_handling: "none"`. Existing blocks keep their binding and routing; when
+`run_worker_first` is already true, a missing `html_handling` defaults to `none`.
+A different binding needs a custom Admin HTML loader. Deploy the built assets and
+Worker together.
+
 `mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin`
 updates the split-build Wrangler keys (`main` and `base_dir` under `dist/worker`),
 ensures `nodejs_compat` and defaults to `global_fetch_strictly_public` ([public fetch routing](deploy-and-operate.md#public-fetch-routing))
 and, with `--admin`, `assets.directory`: `mantle bundle` builds Admin into
-`dist/client/admin`, served at `/admin`. Configure the rest explicitly; JSONC
-comments and unrelated settings survive regeneration:
+`dist/client/admin`, served at `/admin`. Configure existing assets blocks explicitly;
+JSONC comments and unrelated settings survive regeneration:
 
 ```jsonc
 {

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -11,7 +11,7 @@ The runtime never creates, alters or checks tables. Boot and requests run no DDL
 
 For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code. Cloud executes migrations at deploy time.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code.
 
 Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 

package/docs/handbook/examples/hub.md

@@ -2,4 +2,4 @@
 
 Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.8/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.0/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/agent-setup.md

@@ -13,21 +13,20 @@ carries.
 The Mantle plugin carries one OSS authoring skill, `mantle`, and local
 acceptance references. It does not configure a hosted-service connection.
 Install from the Git tag matching the exact SDK version you selected (currently
-`v0.2.0-alpha.8`). Alpha releases integrate on `develop`; an unqualified
-`aotter/mantle` source follows `main` and can install older, incompatible
-instructions. A skill install does not upgrade the application's SDK.
+`v0.2.0`). Pin the tag to keep instructions aligned with the application's
+SDK. A skill install does not upgrade the application's SDK.
 
 For Codex, pin the marketplace checkout:
 
 ```sh
-codex plugin marketplace add aotter/mantle --ref v0.2.0-alpha.8
+codex plugin marketplace add aotter/mantle --ref v0.2.0
 codex plugin add mantle@mantle
 ```
 
 For Claude Code, first clone the release into a directory you will keep:
 
 ```sh
-git clone --depth 1 --branch v0.2.0-alpha.8 https://github.com/aotter/mantle.git mantle-plugin
+git clone --depth 1 --branch v0.2.0 https://github.com/aotter/mantle.git mantle-plugin
 ```
 
 Then, in Claude Code, use that checkout's absolute path:
@@ -41,7 +40,7 @@ Cursor and GitHub Copilot use their plugin manifests from the same tagged
 checkout. Without a plugin host, install only the consumer skill by name:
 
 ```sh
-npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.8 --skill mantle
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0 --skill mantle
 ```
 
 When upgrading the SDK, update the marketplace ref or local tagged checkout and
@@ -54,10 +53,16 @@ project and copies no handbook.
 
 ## 2. Install the SDK, then read its own docs
 
-Use the version the project already pins. For a new project, choose a 0.2.x
-version with `npm view @aotter/mantle dist-tags` and install it with an exact
-version; every `@aotter/mantle*` package stays at that same version. Then
-read, from the application:
+Use the version the project already pins. For a new project, install stable
+0.2.0 exactly:
+
+```sh
+pnpm add --save-exact @aotter/mantle@0.2.0
+```
+
+Add optional `@aotter/mantle-ui@0.2.0` and `@aotter/mantle-admin@0.2.0` only
+when the selected surfaces need them. Every selected `@aotter/mantle*` package
+stays at the same exact version. Read, from the application:
 
 ```text
 node_modules/@aotter/mantle/README.md