@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

package/docs/examples/app-shell/accept.mjs

@@ -0,0 +1,91 @@
+// Independent acceptance setup (mantle help agent-workflow-acceptance): hands each role to a fresh evaluator without a credential.
+//   node accept.mjs [--fixtures fixtures.mjs] [--user member@example.test]
+//     Starts the app on a fresh local D1 (schema.sql, then seed.sql), signs the admin in with email OTP, runs the optional
+//     fixtures module (default export async ({ call, mcp, signIn, sql, sessions, user }) => {...}: realistic records through
+//     the app's own REST/MCP as real users, e.g. other members' orders and more than one page), signs the user in, then
+//     serves one local proxy per role that adds that role's session to every request. Give an evaluator only its role's URL
+//     (a visitor gets the app's own origin):
+//     MCP at <proxy>/mcp (user) or <proxy>/mcp/admin (admin), Admin at <proxy>/admin, pages and REST at <proxy>/.
+//     The proxy refuses /api/auth/* so the evaluator cannot sign out, sign in or mint credentials. Ctrl-C stops everything.
+//   node accept.mjs mcp <endpoint> [tool [json-arguments]]
+//     A minimal MCP client for an evaluator without one: lists the tools, or calls one and prints the raw result.
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+if (process.argv[2] === "mcp") await client(process.argv[3], process.argv[4], process.argv[5]).catch(error => { console.error(error.message); process.exitCode = 1; });
+else await setup();
+
+async function setup() {
+  const { values } = parseArgs({ args: process.argv.slice(2).filter(arg => arg !== "--"), options: { fixtures: { type: "string" }, user: { type: "string", default: "member@example.test" } } });
+  const { startApp } = await import("./smoke-kit.mjs");
+  const app = await startApp();
+  const stop = async () => { await app.stop(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  try {
+    // Fixtures run between the two sign-ins, so an invite-only app can admit the user first.
+    const sessions = { admin: await app.signIn(app.owner) };
+    if (values.fixtures) await (await import(pathToFileURL(resolve(values.fixtures)).href)).default({ ...app, sessions, user: values.user });
+    sessions.user = await app.signIn(values.user);
+    const lines = [`visitor (anonymous): ${app.origin}`];
+    for (const [role, cookie] of Object.entries(sessions)) {
+      const url = await proxy(app.origin, cookie);
+      lines.push(`${role} (${role === "admin" ? app.owner : values.user}): ${url}  MCP ${url}/mcp${role === "admin" ? "/admin" : ""}${role === "admin" ? `  Admin ${url}/admin` : ""}`);
+    }
+    console.log(lines.join("\n") + "\nReady. Ctrl-C stops the app and deletes its data.");
+  } catch (error) {
+    console.error(app.logs().slice(-4000));
+    await app.stop();
+    throw error;
+  }
+}
+
+/** A local origin that forwards to the app with one role's session; sliding Set-Cookie updates stay inside the proxy. */
+function proxy(origin, cookie) {
+  const jar = new Map(cookie.split("; ").map(pair => [pair.slice(0, pair.indexOf("=")), pair]));
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, origin);
+    if (url.pathname.startsWith("/api/auth/")) { response.writeHead(403, { "content-type": "text/plain" }).end("Sign-in is handled by setup."); return; }
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) if (!["host", "cookie", "origin", "connection", "content-length"].includes(name)) headers.set(name, [value].flat().join(", "));
+    headers.set("cookie", [...jar.values()].join("; "));
+    headers.set("origin", origin);
+    const upstream = await fetch(url, { method: request.method, headers, redirect: "manual", body: chunks.length ? Buffer.concat(chunks) : undefined });
+    for (const set of upstream.headers.getSetCookie()) { const pair = set.split(";")[0]; jar.set(pair.slice(0, pair.indexOf("=")), pair); }
+    const out = {};
+    upstream.headers.forEach((value, name) => { if (!["set-cookie", "content-encoding", "content-length", "transfer-encoding"].includes(name)) out[name] = value; });
+    if (out.location) out.location = out.location.replace(origin, `http://${request.headers.host}`);
+    response.writeHead(upstream.status, out);
+    if (upstream.body) Readable.fromWeb(upstream.body).pipe(response); else response.end();
+  });
+  return new Promise(done => server.listen(0, "127.0.0.1", () => done(`http://127.0.0.1:${server.address().port}`)));
+}
+
+async function client(endpoint, tool, json) {
+  if (!endpoint) throw new Error("usage: node accept.mjs mcp <endpoint> [tool [json-arguments]]");
+  const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
+  let id = 0;
+  const rpc = async (method, params) => {
+    const response = await fetch(endpoint, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", ...(method.startsWith("notifications/") ? {} : { id: ++id }), method, params }) });
+    const session = response.headers.get("mcp-session-id");
+    if (session) headers["mcp-session-id"] = session;
+    const text = await response.text();
+    if (!response.ok && response.status !== 202) throw new Error(`MCP ${method}: HTTP ${response.status} ${text}`);
+    const data = text.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5)).join("\n") || text;
+    return data ? JSON.parse(data) : null;
+  };
+  const init = await rpc("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "mantle-accept", version: "1" } });
+  headers["mcp-protocol-version"] = init.result?.protocolVersion ?? "2025-11-25";
+  await rpc("notifications/initialized");
+  if (!tool) {
+    const tools = [];
+    let cursor;
+    do { const page = (await rpc("tools/list", cursor ? { cursor } : {})).result; tools.push(...page.tools); cursor = page.nextCursor; } while (cursor);
+    console.log(JSON.stringify(tools, null, 2));
+  } else console.log(JSON.stringify(await rpc("tools/call", { name: tool, arguments: json ? JSON.parse(json) : {} }), null, 2));
+}

package/docs/examples/app-shell/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.wrangler/
+.dev.vars
+.env
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal

package/docs/examples/app-shell/package.json

@@ -5,36 +5,37 @@
   "scripts": {
     "generate": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin",
     "types": "wrangler types --include-runtime=false",
-    "db:init": "wrangler d1 execute mantle-app --local --file generated/schema.sql",
-    "db:seed": "wrangler d1 execute mantle-app --local --file seed.sql",
+    "db:init": "wrangler d1 execute DB --local --file generated/schema.sql",
+    "db:seed": "wrangler d1 execute DB --local --file seed.sql",
     "build": "mantle bundle src/index.ts dist",
     "test": "node --test generated/admin-mcp-app.check.mjs",
     "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
     "check": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --check && wrangler types --include-runtime=false --check && tsc --noEmit",
-    "smoke": "node smoke.mjs"
+    "smoke": "node smoke.mjs",
+    "accept": "node accept.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.9",
-    "@aotter/mantle-ui": "0.2.0-alpha.9",
+    "@aotter/mantle": "0.2.1-alpha.1",
+    "@aotter/mantle-ui": "0.2.1-alpha.1",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/core": "1.7.7",
     "@better-auth/mcp": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",
     "@better-auth/utils": "0.4.2",
     "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/server": "2.3.1",
     "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.0-alpha.9",
+    "@aotter/mantle-admin": "0.2.1-alpha.1",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "5.20260904.1",
+    "@cloudflare/workers-types": "5.20261027.1",
     "@types/node": "^26",
     "@types/react": "^19.3.0",
     "playwright-core": "1.62.1",
     "typescript": "^6.0.3",
-    "wrangler": "4.129.0"
+    "wrangler": "4.153.0"
   },
   "engines": {
     "node": ">=22.22"

package/docs/examples/app-shell/smoke-kit.mjs

@@ -3,6 +3,7 @@
 //   import { smoke } from "./smoke-kit.mjs";
 //   await smoke(async ({ call, mcp, signIn, owner, step }) => { const admin = await signIn(owner); ... step("..."); });
 //   Extra Worker variables: await smoke(scenario, { vars: { SUPPLIER_API_URL: "http://127.0.0.1:9999" } });
+// accept.mjs uses startApp() to keep the app running for fresh evaluators.
 import assert from "node:assert/strict";
 import { execFile, spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
@@ -64,11 +65,23 @@ export async function assertMcpDiscovery(endpoint, { tools, headers = {} }) {
   return names;
 }
 
-const database = "mantle-app"; // wrangler.jsonc d1_databases[0].database_name
+const database = "DB"; // the D1 binding (wrangler.jsonc d1_databases[0].binding), so renaming the database changes nothing here
 const env = { ...process.env, WRANGLER_SEND_METRICS: "false" };
 
-export async function smoke(scenario, { vars = {} } = {}) {
-  const port = 18000 + Math.floor(Math.random() * 1000), origin = `http://127.0.0.1:${port}`, owner = "owner@example.test";
+export async function smoke(scenario, options) {
+  const app = await startApp(options);
+  try {
+    await scenario(app);
+    console.log("smoke passed");
+  } catch (error) {
+    console.error(app.logs().slice(-4000));
+    throw error;
+  } finally { await app.stop(); }
+}
+
+/** Start the app on a fresh local D1 (schema.sql, then seed.sql when present); stop() ends wrangler and deletes the state. */
+export async function startApp({ vars = {}, port = 18000 + Math.floor(Math.random() * 1000) } = {}) {
+  const origin = `http://127.0.0.1:${port}`, owner = "owner@example.test";
   const state = mkdtempSync(join(tmpdir(), "mantle-smoke-"));
   // Deployment DDL is explicit: nothing at runtime creates tables.
   for (const file of ["generated/schema.sql", ...(existsSync("seed.sql") ? ["seed.sql"] : [])]) {
@@ -128,6 +141,17 @@ export async function smoke(scenario, { vars = {} } = {}) {
     assert.fail(`no log line matching ${pattern}`);
   };
   const step = name => console.log(`ok - ${name}`);
+  const stop = async () => {
+    const kill = signal => { try { process.kill(-wrangler.pid, signal); } catch { /* already gone */ } };
+    kill("SIGTERM");
+    await new Promise(resolve => {
+      if (wrangler.exitCode !== null) return resolve();
+      const timer = setTimeout(() => { kill("SIGKILL"); resolve(); }, 5_000);
+      wrangler.once("exit", () => { clearTimeout(timer); resolve(); });
+    });
+    kill("SIGKILL");
+    rmSync(state, { recursive: true, force: true });
+  };
   try {
     for (let attempt = 0; ; attempt++) {
       if (wrangler.exitCode !== null) throw new Error(`wrangler exited ${wrangler.exitCode}`);
@@ -135,20 +159,10 @@ export async function smoke(scenario, { vars = {} } = {}) {
       if (attempt > 240) throw new Error("the Worker did not start");
       await new Promise(resolve => setTimeout(resolve, 250));
     }
-    await scenario({ origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs: () => logs });
-    console.log("smoke passed");
   } catch (error) {
     console.error(logs.slice(-4000));
+    await stop();
     throw error;
-  } finally {
-    const stop = signal => { try { process.kill(-wrangler.pid, signal); } catch { /* already gone */ } };
-    stop("SIGTERM");
-    await new Promise(resolve => {
-      if (wrangler.exitCode !== null) return resolve();
-      const timer = setTimeout(() => { stop("SIGKILL"); resolve(); }, 5_000);
-      wrangler.once("exit", () => { clearTimeout(timer); resolve(); });
-    });
-    stop("SIGKILL");
-    rmSync(state, { recursive: true, force: true });
   }
+  return { origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs: () => logs, stop };
 }

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/")) {

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

@@ -9,6 +9,7 @@ spec:
   # It also refuses an officer lowering capacity below the seats already taken.
   checks: ["seats_taken <= capacity"]
   indexes: [[startsAt, id]]
+  searchableFields: [title]
   uiSchema: { list: { primaryField: title, columns: [startsAt, capacity, seats_taken, closed] } }
   schema:
     type: object
@@ -54,6 +55,7 @@ spec:
   uniqueIndexes: [[email]]
   # Better Auth lowercases emails; the check refuses a mixed-case entry that would never match.
   checks: ["email = lower(email)"]
+  searchableFields: [email, name]
   uiSchema: { list: { primaryField: email, columns: [name] } }
   schema:
     type: object
@@ -86,6 +88,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

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/generated-web/seed.sql

@@ -1,6 +1,7 @@
 -- Local fixture only. Production publishing goes through the generated Procedures.
+-- Every system column is set: timestamps are microseconds since the Unix epoch (2026-01-01T00:00:00Z); 0 would show as 1970.
 INSERT INTO posts (id, version, created_at, updated_at, title, body, status, published_at) VALUES
-('home', 1, 0, 0, 'Posts', '# Posts — browse the HTML index for articles.', 'published', 0),
-('hello', 1, 0, 0, 'Hello <world>', '# Hello world', 'published', 0),
-('second', 1, 0, 0, 'Second post', '# Second post', 'published', 0),
-('draft', 1, 0, 0, 'Hidden draft', '# Draft', 'draft', NULL);
+('home', 1, 1767225600000000, 1767225600000000, 'Posts', '# Posts — browse the HTML index for articles.', 'published', 1767225600000000),
+('hello', 1, 1767225600000000, 1767225600000000, 'Hello <world>', '# Hello world', 'published', 1767225600000000),
+('second', 1, 1767225600000000, 1767225600000000, 'Second post', '# Second post', 'published', 1767225600000000),
+('draft', 1, 1767225600000000, 1767225600000000, 'Hidden draft', '# Draft', 'draft', NULL);

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

@@ -9,6 +9,7 @@ spec:
   uniqueIndexes: [[department]]
   # An approval that would overspend fails this check and the whole approval rolls back.
   checks: ["remaining >= 0"]
+  searchableFields: [department]
   uiSchema: { list: { primaryField: department, columns: [remaining] } }
   schema:
     type: object
@@ -25,6 +26,7 @@ spec:
   title: Purchase requests
   lifecycle: operational
   indexes: [[authorId, createdAt, id], [requestStatus, createdAt, id]]
+  searchableFields: [title, department]
   # Sidebar: in the Approvals group (src/admin.tsx), after the queue of requests waiting for a decision.
   uiSchema: { list: { primaryField: title, columns: [department, amount, requestStatus], filterField: requestStatus }, nav: { group: approvals, order: 2 } }
   schema:
@@ -48,10 +50,13 @@ spec:
   title: Budget ledger
   lifecycle: operational
   indexes: [[createdAt, id]]
+  # One row per spending request.
+  uniqueIndexes: [[requestId]]
+  searchableFields: [department]
   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,7 +122,7 @@ kind: Procedure
 metadata: { name: submit-request }
 spec:
   title: Submit a purchase request
-  description: Submit a purchase request against an existing department budget.
+  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
@@ -128,11 +133,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.

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/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/media-r2.md

@@ -44,8 +44,11 @@ An existing S3 signer (for example an application already using aws4fetch) fits
 this port. This package adds no AWS SDK. The signer must return a SigV4
 query-signed PUT URL and preserve `X-Amz-Expires`; never give its credentials to
 the client. Configure bucket CORS to allow PUT from the application's origins
-and the returned Content-Type header. Serve the `committed/` prefix on the public domain; these keys differ from 0.2's `{purpose}/{group}/{role}` keys. Keep `uploads/` private/unserved on the
-public domain and add a bucket lifecycle rule for abandoned upload keys.
+and the returned Content-Type header. Uploads go to `uploads/<purpose>/<group>/<role>.<ext>` and each commit copies them
+to `committed/<group>/<attempt>/<role>.<ext>`. Serve the `committed/` prefix on the public domain. Keep `uploads/`
+private/unserved on the public domain and add a bucket lifecycle rule for abandoned upload keys. Mantle 0.1.x wrote
+`<purpose>/<group>/<role>.<ext>` keys (`<group>/<role>.<ext>` when the purpose was not a plain slug); an asset reads its keys from the stored `storageKey` and `publicUrl` of each
+variant, so 0.1.x assets keep working while their prefixes stay served.
 
 Commit checks every object's MIME and size, then rechecks the exact GET
 response used for the copy. Public keys cannot be reached by an upload URL. Each commit attempt has a separate
@@ -54,7 +57,7 @@ loser can neither overwrite nor remove the winner's objects. After SQL selects
 the durable asset, the losing attempt removes only its own unselected copies.
 Upload sources remain until the database commit succeeds, so an uncertain DB
 write can be reconciled/retried with the same UUID. Failed object deletion keeps
-the media row; retry the same id. An upload group expires after 15 minutes. Asset `createdAt` is the upload-group creation time (epoch milliseconds), not the later commit time.
+the media row; retry the same id. An upload group expires after 15 minutes. Asset `createdAt` (`media_assets.created_at`) is the upload-group creation time in epoch milliseconds, not the later commit time; entry timestamps on D1 are microseconds ([reserved entry columns](../reference/schema.md#reserved-entry-columns)).
 No R2 upload or deployment is performed by generation.
 
 A positively identified native rollback deletes only that attempt's copied

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

@@ -22,6 +22,8 @@ under `secrets.required`, run `pnpm exec wrangler types --include-runtime=false`
 add `worker-configuration.d.ts` to `tsconfig.json` and commit it.
 `@cloudflare/workers-types` still supplies runtime types. Rerun after every binding
 change; `wrangler types --include-runtime=false --check` fails on drift.
+Both run the custom build (`mantle bundle`), because Wrangler reads the built entry's exports
+for Durable Object and service binding types; Wrangler has no option to skip it.
 Once `secrets.required` is set, `wrangler dev` loads only those keys from
 `.dev.vars`/`.env`, so declare every secret the app reads.
 
@@ -81,6 +83,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); }
     });

package/docs/handbook/concepts/lifecycle-and-locales.md

@@ -2,7 +2,27 @@
 
 Schemas default to `operational`: rows are live immediately and edit in place. Opt-in `publishing` adds `status` (draft/published/archived), nullable `published_at` and a scope-aware `(published_at, id)` index.
 
-Generated `<table>.publish`, `.unpublish` and `.archive` Procedures take `{ id, expectedVersion }`, require admin/system and perform one atomic UPDATE. Publish checks required fields, visibility, TTL, source state and OCC. A failed guard is `CONFLICT`. Store cannot write status/published_at directly. Admin permits generic publishing edits only on drafts; Store does not add that separate Admin editing rule.
+Generated `<table>.publish`, `.unpublish` and `.archive` Procedures take `{ id, expectedVersion }`, require admin/system and perform one atomic UPDATE. Publish checks required fields, visibility, TTL, source state and OCC. A failed guard is `CONFLICT`. Store cannot write status/published_at directly. By default Admin's generic patch edits drafts only (published and archived entries are unpublished first), and a published entry is unpublished before it is deleted; both are an implicit lock named `publishing` that Admin shows before the edit, and neither applies to the transitions. A Store update may edit a published row in place but cannot clear a field `publish` requires: setting one to null is `INPUT_VALIDATION_FAILED` for every caller. Fields it leaves alone are not re-checked, so adding a field to `required` later does not block updates of posts published before it.
+
+To let admins correct a published entry in place, opt in with `publishing: { liveEdits: true }`. A personal blog needs nothing more than one Schema:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: posts }
+spec:
+  title: Posts
+  lifecycle: publishing
+  publishing: { liveEdits: true }
+  schema:
+    type: object
+    required: [title, body]
+    properties:
+      title: { type: string }
+      body: { type: string }
+```
+
+Admin then edits a published post with a "changes go live on save" notice. The save goes live on commit, `published_at` is kept and `updated_at` moves. The merged post must still pass `publish`'s checks, so emptying its title is refused with `INPUT_VALIDATION_FAILED`. An archived post stays draft-only: restore it to edit it. Deleting a published post still requires unpublishing, and [declared locks](../reference/schema.md#locks) still apply. `publishing` is refused on an operational Schema, which already edits in place. To prepare changes to published content without exposing them, split it into a publishing parent and operational revisions instead ([edit published content without downtime](../guides/revisions.md)).
 
 Public Views see published rows only. Other reads expose drafts only to admin/system. This policy applies to joins and nested queries too.
 

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.9/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.1-alpha.1/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/admin-ui.md

@@ -6,7 +6,7 @@ Schema `uiSchema` selects fields, widgets, list columns, enum tabs and child nav
 
 Admin Views provide custom read lists; their SELECT outputs, column lineage and `uiSchema.list` define display/search/filter metadata. Procedures and MCP admin Triggers define operations with declared authorization, input checks and optional row targets. A hidden button never authorizes an operation.
 
-Generic publishing edits apply to drafts; publishing transitions retain their atomic guards and OCC. Read-only collections refuse generic edits while declared Procedures can still run. Ref operations receive the caller/transaction-bound Store.
+Generic publishing edits apply to drafts unless the Schema sets `publishing: { liveEdits: true }` ([lifecycle](../concepts/lifecycle-and-locales.md)); publishing transitions retain their atomic guards and OCC. Read-only collections refuse generic edits while declared Procedures can still run. Ref operations receive the caller/transaction-bound Store.
 
 Use [`defineAdmin` components](native-admin.md#customising-admin) for app-owned cells, inputs, record asides and actions; server work is a Procedure, a View or an application route. Keep exact conflict/uncertain-outcome handling in the shared UI controller.