@aotter/mantle 0.2.1-alpha.2 → 0.2.1-alpha.4

package/dist/infrastructure/help.js

@@ -15,11 +15,9 @@ export function topics(root = docsRoot()) {
     const unlisted = readdirSync(resolve(root, "handbook"), { recursive: true }).filter(path => path.endsWith(".md")).sort()
         .map(path => resolve(root, "handbook", path)).filter(file => !listed.has(file))
         .map(file => ({ name: relative(resolve(root, "handbook"), file).replaceAll("\\", "/").slice(0, -3), title: readFileSync(file, "utf8").match(/^# (.+)$/m)?.[1] ?? basename(file), file, group: "More pages" }));
-    const skills = (existsSync(resolve(root, "skills")) ? readdirSync(resolve(root, "skills")) : []).filter(name => existsSync(resolve(root, "skills", name, "SKILL.md")))
-        .map(name => ({ name: `skills/${name}`, title: `Package skill: ${name}`, file: resolve(root, "skills", name, "SKILL.md"), group: "Package skills" }));
     const examples = resolve(root, "examples");
     const shipped = readdirSync(examples, { withFileTypes: true }).filter(entry => entry.isDirectory() && existsSync(resolve(examples, entry.name, "README.md")));
-    return [...pages, ...unlisted, ...skills, { name: "examples", title: "Examples and how to combine them", file: resolve(examples, "README.md"), group: "Examples" },
+    return [...pages, ...unlisted, { name: "examples", title: "Examples and how to combine them", file: resolve(examples, "README.md"), group: "Examples" },
         ...shipped.map(entry => ({ name: `examples/${entry.name}`, title: `Example: ${entry.name}`, file: resolve(examples, entry.name, "README.md"), group: "Examples" }))];
 }
 function find(all, name) {

package/dist/usecase/adminDescriptors.js

@@ -7,7 +7,7 @@ export function emitAdminDescriptors({ plan, admin = false }, diagnostics) {
     const schemaList = Object.values(plan.schemas);
     const placed = [...schemaList.map(s => ["schemas/" + s.name, s.uiSchema, s]), ...Object.entries(plan.views).map(([name, v]) => ["views/" + name, v.uiSchema, null])];
     for (const [path, ui, s] of placed) {
-        const nav = (ui?.["nav"] ?? {}), group = nav["group"];
+        const nav = (ui?.["nav"] ?? {});
         if (s && !isPrimaryCollection(s, schemaList))
             for (const key of ["group", "order", "hidden"])
                 if (nav[key] !== undefined)

package/dist/usecase/generate.js

@@ -76,6 +76,9 @@ export function generate(input) {
         return fields;
     };
     const values = new Set();
+    const pool = new Map();
+    const pooled = (text) => { let id = pool.get(text); if (!id)
+        pool.set(text, id = `\u0000_p${pool.size}\u0000`); return id; };
     const step = (s, path, fields, row = false) => {
         const recipes = recipesOf(s, fields, message => refuse(path, message)), probe = row && s.probe ? recipesOf(s.probe, fields, message => refuse(path, message)) : [];
         for (const r of [...recipes, ...probe]) {
@@ -86,7 +89,7 @@ export function generate(input) {
         }
         const locks = Object.fromEntries((plan.schemas[s.schema ?? ""]?.locks ?? []).filter(l => l.on.includes(s.verb)).map(l => [l.name, l.message]));
         const lock = row && s.probe ? `, lock: ${q({ sql: s.probe.sql, binds: probe, schema: plan.schemas[s.schema].name, verb: s.verb, locks })}` : "";
-        return `{ sql: ${q(s.sql)}, binds: ${q(recipes)}${row ? ", row: true" : s.onNoRows ? ', row: "some"' : ""}${lock} }`;
+        return `{ sql: ${pooled(q(s.sql))}, binds: ${pooled(q(recipes))}${row ? ", row: true" : s.onNoRows ? ', row: "some"' : ""}${lock} }`;
     };
     const declarations = [], views = [], procedures = [], refProcedures = [];
     const entries = {};
@@ -133,7 +136,7 @@ export function generate(input) {
         const fieldNames = inputFields(procedure.input, path + "/input");
         const steps = (statements) => `[${statements.map(s => step(s, path, fieldNames, s.kind === "row")).join(", ")}] as const`;
         const same = steps(modes.caller) === steps(modes.trusted);
-        declarations.push(`export type Procedure${index}Input = ${queryInputType(procedure.input, [...modes.caller, ...modes.trusted])};`, `const ${fn}Caller = ${steps(modes.caller)};`, ...(same ? [] : [`const ${fn}Trusted = ${steps(modes.trusted)};`]), `async function ${fn}(db: Database, caller: Caller, raw: Procedure${index}Input): Promise<Output> {`, ...(modes.caller.some(s => s.kind !== "read") ? [`  if ("authenticatedAs" in caller && caller.authenticatedAs === "snapshot") (await import("@aotter/mantle/host-caller")).checkFresh(caller, false, ${q(path)});`] : []), ...auth(procedure.requires, path), ...(user.used ? ['  USER.modeOf(caller);'] : []), ...(procedure.trustedOnly ? [`  deny(caller, USER.modeOf(caller) === "trusted", ${q(path)});`] : []), `  return { results: await DRIVER.procedure(db, bound(D, ${user.used ? "USER.scopedAll(" : ""}${same ? "" : `${user.used ? 'USER.modeOf(caller) === "trusted"' : 'caller.kind === "system"'} ? ${fn}Trusted : `}${fn}Caller${user.used ? ", caller)" : ""}, caller, raw), ${q(path)}) };`, "}");
+        declarations.push(`export type Procedure${index}Input = ${queryInputType(procedure.input, [...modes.caller, ...modes.trusted])};`, `const ${fn}Caller = ${steps(modes.caller)};`, ...(same ? [] : [`const ${fn}Trusted = ${steps(modes.trusted)};`]), `async function ${fn}(db: Database, caller: Caller, raw: Procedure${index}Input): Promise<Output> {`, ...(modes.caller.some(s => s.kind !== "read") ? [`  await _fresh(caller, ${q(path)});`] : []), ...auth(procedure.requires, path), ...(user.used ? ['  USER.modeOf(caller);'] : []), ...(procedure.trustedOnly ? [`  deny(caller, USER.modeOf(caller) === "trusted", ${q(path)});`] : []), `  return { results: await DRIVER.procedure(db, bound(D, ${user.used ? "USER.scopedAll(" : ""}${same ? "" : `${user.used ? 'USER.modeOf(caller) === "trusted"' : 'caller.kind === "system"'} ? ${fn}Trusted : `}${fn}Caller${user.used ? ", caller)" : ""}, caller, raw), ${q(path)}) };`, "}");
         procedures.push(`[${q(name)}]: ${fn}`);
         declarations.push(`export { ${fn} as ${exportName("procedure", name)} };`);
         entries[`procedures/${encodeURIComponent(name)}.ts`] = entry("procedure", name, `Procedure${index}Input as Input`, `export type { Output } from "${base}contracts";\n`);
@@ -145,18 +148,31 @@ export function generate(input) {
     if (diagnostics.length)
         return { ok: false, diagnostics };
     const storeProcedures = hasHandlers ? "storeProcedures" : "procedures";
-    const code = [...(Object.keys(plan.access?.userFields ?? {}).length ? [`export const userFields = ${q(plan.access.userFields)} as const;`] : []), ...declarations, `export const views = { ${views.join(", ")} };`, `export const procedures = { ${procedures.join(", ")} };`, ...(stores ? [
+    const code = [...(declarations.some(d => d.includes("  await _fresh(caller, ")) ? ['const _fresh = (caller: Caller, path: string) => "authenticatedAs" in caller && caller.authenticatedAs === "snapshot" ? import("@aotter/mantle/host-caller").then(m => m.checkFresh(caller, false, path)) : undefined;'] : []), ...(Object.keys(plan.access?.userFields ?? {}).length ? [`export const userFields = ${q(plan.access.userFields)} as const;`] : []), ...declarations, `export const views = { ${views.join(", ")} };`, `export const procedures = { ${procedures.join(", ")} };`, ...(stores ? [
             `export type Tables = ${stores.tables};`, `const RULES = ${stores.rules} as const;`,
             ...(hasHandlers ? [`const storeProcedures = { ${[...procedures, ...refProcedures].join(", ")} };`] : []),
             `const initStore = () => createStore<Database, Tables, typeof DRIVER, { views: typeof views; procedures: typeof ${storeProcedures} }${hasHandlers ? ", { handlers: Handlers }" : ""}>(${user.used ? "{...DIALECT.dialect, ...USER_VALUES}" : "DIALECT.dialect"}, DRIVER, RULES, ${stores.facts}, { views, procedures: ${storeProcedures} });`,
             `let makeStore: ReturnType<typeof initStore>;`,
             `export function store${hasHandlers ? "<const H extends Handlers>" : ""}(db: Database, caller: Caller${hasHandlers ? ", options: { handlers: H & Record<Exclude<keyof H, keyof Handlers>, never> }" : ", _options?: { handlers?: Handlers }"}): ReturnType<typeof makeStore> { return (makeStore ??= initStore())(db, caller${hasHandlers ? ", options" : ""}); }`,
         ] : [])].join("\n");
+    function unpool(text) {
+        const shared = [];
+        for (const [value, token] of pool) {
+            if (text.split(token).length > 2) {
+                const id = token.slice(1, -1);
+                shared.push(`const ${id} = ${value} as const;`);
+                text = text.replaceAll(token, id);
+            }
+            else
+                text = text.replace(token, () => value);
+        }
+        return [...shared, text];
+    }
     const dialect = `${base}dialect/${isSqlite ? "sqlite" : "postgres"}`;
     const contracts = [...(target.endsWith("postgres") ? ["type Postgres as Database", ...(views.length ? ["type Unsafe"] : [])] : []), "type Caller", ...(hasHandlers ? ["ContractError"] : []), ...(/^  deny\(/m.test(code) ? ["deny", ...(/\bisAdmin\(/.test(code) ? ["isAdmin"] : []), ...(/\bisUser\(/.test(code) ? ["isUser"] : [])] : []), ...(procedures.length ? ["type Output"] : [])];
     const dbType = isSqlite ? databaseImport(target) : "";
     return { ok: true, refProcedures: refNames, files: generatedFiles({ ...surfaces, ...entries, "generated.ts": ["// Generated native application SQL. No runtime plan or interpreter.", user.code, dbType, `import { ${contracts.join(", ")} } from "${base}contracts";`,
                 ...(values.size || stores ? [`import * as DIALECT from "${dialect}";`] : []), `import * as DRIVER from "${base}driver/${driver}";`, ...((names => names.length ? [`import { ${names.join(", ")} } from "${base}store";`] : [])([...(stores ? ["createStore"] : []), ...(hasHandlers && target !== "cloudflare-d1" ? ["handlerTransaction"] : [])])),
                 `import { ${procedures.length ? "binds, bound" : "binds"} } from "${base}binds";`,
-                `const D = { ${[...values].sort().map(v => `${v}: DIALECT.${v}`).concat(user.values ? [user.values] : []).join(", ")} };`, code].filter(Boolean).join("\n") + "\n" }) };
+                `const D = { ${[...values].sort().map(v => `${v}: DIALECT.${v}`).concat(user.values ? [user.values] : []).join(", ")} };`, ...unpool(code)].filter(Boolean).join("\n") + "\n" }) };
 }

package/dist/usecase/rest.js

@@ -22,7 +22,7 @@ export function emitRest(plan, lowered, target, description) {
     for (const [name, view] of Object.entries(plan.views)) {
         if (view.surface !== "public")
             continue;
-        const id = views.length, encoded = encodeURIComponent(name);
+        const id = views.length;
         const wire = outputConversions(plan, name, target);
         imports.push(...viewImports(name, id).map(line => wire.some(([, type]) => type === "int") ? line.replaceAll("./paged/views/", "./paged/wire/views/") : line));
         hasWire ||= wire.length > 0;
@@ -33,14 +33,12 @@ export function emitRest(plan, lowered, target, description) {
         if (trigger.source.kind !== "http")
             continue;
         const { method, path } = trigger.source, name = trigger.procedure, procedure = plan.procedures[name], id = procedures.length, ref = "ref" in procedure.handler;
-        if (!ref)
-            imports.push(`import procedure${id} from "./procedures/${encodeURIComponent(name)}.js";`);
         imports.push(`import { validate as validate${id} } from "./validation/procedures/${encodeURIComponent(name)}.js";`);
         const params = Object.fromEntries([...path.matchAll(/\{([^}]+)\}/g)].flatMap(([, key]) => {
             const type = [procedure.input?.properties?.[key]?.type].flat().find(t => t && t !== "null");
             return type === "integer" || type === "number" ? [[key, "number"]] : type === "boolean" ? [[key, "boolean"]] : [];
         }));
-        procedures.push(`{ ${route(method, path)}, id: ${q(`rest:${method} ${template(path)}`)}, target: ${q({ kind: "procedure", name })}${description.targets.find(t => t._meta.id === `procedure:${name}`)?._meta.readOnly ? ", readOnly: true" : ""}${guard(procedure.requires, `procedures/${name}`, lowered.procedures[name]?.caller?.flatMap(s => s.binds), procedure.trustedOnly)}${Object.keys(params).length ? `, params: ${q(params)}` : ""}, validate: validate${id}${convert(conversions(procedure.input?.properties, lowered.procedures[name]?.caller?.flatMap(s => s.binds) ?? [], target))}, run: ${ref ? `(db, caller, input, handlers) => store(db, caller, { handlers }).procedures[${q(name)}](input)` : `procedure${id}`} }`);
+        procedures.push(`{ ${route(method, path)}, id: ${q(`rest:${method} ${template(path)}`)}, target: ${q({ kind: "procedure", name })}${description.targets.find(t => t._meta.id === `procedure:${name}`)?._meta.readOnly ? ", readOnly: true" : ""}${guard(procedure.requires, `procedures/${name}`, lowered.procedures[name]?.caller?.flatMap(s => s.binds), procedure.trustedOnly)}${Object.keys(params).length ? `, params: ${q(params)}` : ""}, validate: validate${id}${convert(conversions(procedure.input?.properties, lowered.procedures[name]?.caller?.flatMap(s => s.binds) ?? [], target))}, run: ${ref ? `(db, caller, input, handlers) => store(db, caller, { handlers }).procedures[${q(name)}](input)` : `async (db, caller, input) => (await import("./procedures/${encodeURIComponent(name)}.js")).default(db, caller, input)`} }`);
     }
     if (hasWire)
         imports.push('import { wireRows } from "@aotter/mantle/contracts";');

package/docs/examples/README.md

@@ -39,5 +39,5 @@ shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchas
 
 Every example uses two roles: `admin` (the admin layer) and `user`.
 
-[Reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.2/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
-Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).
+[Reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.4/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
+Projects on 0.1.x move with [the upgrade guide](../handbook/releases/upgrade-0.1-to-0.2.md).

package/docs/examples/app-shell/README.md

@@ -112,7 +112,7 @@ its layered report ("Report done-ness in layers"): smoke and `pnpm test` are lay
 
 ### Independent acceptance
 
-`pnpm accept` (optionally `pnpm accept --fixtures fixtures.mjs --user member@example.test`; with npm, `npm run accept -- --fixtures …`) starts the app on a fresh local D1,
+`pnpm accept` (optionally `pnpm accept --fixtures fixtures.mjs --user member@example.test`, and `--open` to open the signed-in admin's Developer UI in your browser; with npm, `npm run accept -- --fixtures …`) starts the app on a fresh local D1,
 signs the admin in, runs your fixtures module, signs the user in and prints one local URL per role:
 
 ```text

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

@@ -1,5 +1,5 @@
 // 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]
+//   node accept.mjs [--fixtures fixtures.mjs] [--user member@example.test] [--open]
 //     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
@@ -7,8 +7,11 @@
 //     (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.
+//     --open also opens the signed-in admin's Developer UI (<admin proxy>/admin/dev) in the default browser, so a person
+//     sees the app's wiring without a one-time code; the app keeps rebuilding on every change under src/ and generated/.
 //   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 { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
 import { parseArgs } from "node:util";
@@ -19,7 +22,7 @@ if (process.argv[2] === "mcp") await client(process.argv[3], process.argv[4], pr
 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 { values } = parseArgs({ args: process.argv.slice(2).filter(arg => arg !== "--"), options: { fixtures: { type: "string" }, user: { type: "string", default: "member@example.test" }, open: { type: "boolean" } } });
   const { startApp } = await import("./smoke-kit.mjs");
   const app = await startApp();
   const stop = async () => { await app.stop(); process.exit(0); };
@@ -33,6 +36,7 @@ async function setup() {
     const lines = [`visitor (anonymous): ${app.origin}`];
     for (const [role, cookie] of Object.entries(sessions)) {
       const url = await proxy(app.origin, cookie);
+      if (role === "admin" && values.open) browse(`${url}/admin/dev`);
       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.");
@@ -43,6 +47,12 @@ async function setup() {
   }
 }
 
+/** Opens a URL in the default browser; without one (CI, a container) the printed URL is all there is. */
+function browse(url) {
+  const [command, ...args] = process.platform === "darwin" ? ["open"] : process.platform === "win32" ? ["cmd", "/c", "start", ""] : ["xdg-open"];
+  spawn(command, [...args, url], { stdio: "ignore", detached: true }).on("error", () => console.log(`Open ${url} in a browser.`)).unref();
+}
+
 /** 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]));

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

@@ -15,8 +15,8 @@
     "accept": "node accept.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.1-alpha.2",
-    "@aotter/mantle-ui": "0.2.1-alpha.2",
+    "@aotter/mantle": "0.2.1-alpha.4",
+    "@aotter/mantle-ui": "0.2.1-alpha.4",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/core": "1.7.7",
     "@better-auth/mcp": "1.7.7",
@@ -25,7 +25,7 @@
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/server": "2.3.1",
     "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.1-alpha.2",
+    "@aotter/mantle-admin": "0.2.1-alpha.4",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },

package/docs/handbook/cloudflare/authentication.md

@@ -91,7 +91,7 @@ Invalid presented bearer credentials fail rather than becoming anonymous. Fresh
 
 ## Build: keep Better Auth out of startup
 
-Use the [Workers build instructions](../../../README.md#workers-build).
+Generation configures `mantle bundle` as the Workers build ([outputs](../start/project-and-cli.md#outputs)).
 The metafile startup guard rejects static Better Auth imports; keep auth behind
 `authLoader(() => import(...))`.
 

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

@@ -5,6 +5,22 @@ description: Install schema explicitly, migrate before deploying, and operate a
 
 Run the same generation command with `--check`, typecheck the application and test its selected routes before deploying. Keep generated TypeScript, SQL and Wrangler edits committed; keep bundle `dist/` untracked. The app owns the database, auth secrets, trusted origin and assets.
 
+Deploy only when the user asks; creating a project locally is not authorization. Confirm the exact account and reuse the
+resources it already has before creating any. For ChatGPT Sites, follow [Mantle on ChatGPT Sites](chatgpt-sites.md).
+
+## Production checklist
+
+1. Migrations are reviewed, rehearsed on a copy and applied before traffic reaches the new code
+   ([install and change schemas](#install-and-change-schemas)).
+2. Secrets live in the host's secret store, never in source, chat or logs: the auth secret, the trusted HTTPS
+   `PUBLIC_ORIGIN`, the `ADMIN_EMAIL` bootstrap rule and the production email sender ([authentication](authentication.md)).
+3. Admin assets are served Worker-first ([Workers assets and secrets](service-entry.md#workers-assets-and-secrets)) and
+   both [public-fetch flags](#public-fetch-routing) stay in every environment.
+4. After deploying, verify on the deployed host: admin sign-in gets role `admin`, a member is denied Admin, public and
+   protected reads, a persisted write, a stale OCC write refused, and MCP `initialize` and `tools/list` with a real OAuth
+   bearer.
+5. Keep the previous build and the migration rollback until the release is verified.
+
 ## Public fetch routing
 
 Workers use `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
@@ -28,13 +44,7 @@ checks do not verify production public-hostname routing.
 
 ## Install and change schemas
 
-The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
-
-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.
-
-Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
+The rules are in [schema installation and migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations): the runtime runs no DDL, the initial `schema.sql` is only for an empty database, and every later change is a reviewed migration rehearsed on a copy and applied before the new code deploys.
 
 For D1, create a migration with `pnpm exec wrangler d1 migrations create <database> <name>`, review its SQL, then rehearse `pnpm exec wrangler d1 migrations apply <database> --local` against copied data. Apply the reviewed migrations to the target before `wrangler deploy`. Initial DDL may be placed in the first migration for a new database.
 
@@ -79,4 +89,6 @@ Auth configuration and production email delivery are app-owned; follow [authenti
 
 Scheduling is app-owned. Wire generated system-only TTL sweeps into `scheduled()` and configure Wrangler crons explicitly. Bound each invocation and retain a cursor if work remains; see [TTL maintenance](../guides/native-execution.md#ttl-maintenance). Expired rows remain stored and hold unique keys until removed.
 
-After deployment, verify public and protected reads, member/admin sign-in, a persisted write, stale OCC and selected MCP/Admin/web routes. An `OUTCOME_UNKNOWN` write may have committed; reconcile before deciding what to do next and never retry automatically.
+An `OUTCOME_UNKNOWN` write may have committed; reconcile before deciding what to do next and never retry automatically. For MCP Apps, verify a newly invoked render tool on the deployed host and keep old
+conversations working with the [retained-page recipe](../guides/mcp-apps.md#keep-old-conversations-working-after-an-upgrade).
+Deploying an application never publishes or bumps the SDK.

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

@@ -73,3 +73,34 @@ reconciliation and retry id.
 Admin's `media` option takes a `MediaStorage` value, so build it where `env` is available (for example once per
 Worker in the fetch handler). Uploads use presigned S3 PUT URLs: `wrangler dev --local` has an R2 binding but no S3
 endpoint, so test the upload flow against a real bucket; local tests can cover everything up to the signed URL.
+
+## Clean up stale uploads
+
+An upload that was created but never committed leaves objects under `uploads/`. Cleaning them up is an operator task:
+audit by default, and delete only the exact objects the user approves for that exact account and bucket. Create no
+Worker, Cron Trigger, lifecycle rule, table or script for it, and never create, request or store credentials.
+
+**Layout.** `POST /admin/api/media/uploads` issues presigned PUT URLs (15 minutes) for
+`uploads/<purpose>/<group>/<role>.<ext>`. Commit copies each checked object to `committed/<group>/<attempt>/<role>.<ext>`
+with `committedAt` metadata and removes the upload keys after the database commit; a rejected group also removes them.
+An old upload key may be leftover cleanup from a successful or uncertain commit, so it is not evidence that the media row
+is absent. Objects outside `uploads/` are never candidates; attempt copies under `committed/` are reconciled with live
+database references separately, under their own authorization.
+
+**Preflight.** Resolve the bucket `r2MediaStorage` uses and the purposes in `siteDefaults.media.purposes` from
+`wrangler.jsonc` and the app entry. Confirm the exact account and bucket with the user; when either is ambiguous, ask,
+never match by name. Stop when the app passes no `r2MediaStorage`, declares no purpose, or the connected account lacks
+List/Delete Objects access.
+
+**Audit.** For each declared purpose, page through `uploads/<purpose>/` until the listing is not truncated. A candidate
+is more than 24 hours old, has no `committedAt`, and matches
+`uploads/<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|bin)` with a declared purpose and a
+`<group>` of letters, digits, `_` or `-`. Skip everything else (committed, unknown prefix, malformed, ambiguous) and
+delete single variants, never a whole group. Report the account, bucket, prefixes, UTC cutoff, candidate object and
+group counts, bytes, skipped count, and a SHA-256 digest of the sorted `key + etag` set; print no keys, group ids,
+filenames, URLs or secrets. A page truncated without a cursor stops the run: never delete from a partial audit.
+
+**Apply.** After explicit confirmation of the account, bucket, cutoff, count, bytes and digest, re-run the audit with the
+same cutoff and stop if anything changed. Delete exact keys, at most 1,000 per request, and never send a `prefix`: an
+empty prefix can empty the bucket. Do not retry failed keys automatically. Re-list each prefix and report whether the run
+was audit-only or applied, the before/after counts and bytes, and redacted error codes.

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.1-alpha.2/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.4/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

@@ -1,97 +1,55 @@
 ---
-description: Install the Mantle agent plugin or its one skill, hand off to the installed package's own docs, and diagnose missing or stale instructions.
+description: Install the Mantle agent skill, hand off to the installed package's `mantle help`, and diagnose missing or stale instructions.
 ---
 # Install and verify agent instructions
 
-Two separate things are installed: the agent's `mantle` skill and the
-application's `@aotter/mantle` package. Installing one does not install the
-other, and the installed package is always the authority for the version it
-carries.
+Two separate things are installed: the agent's `mantle` skill and the application's `@aotter/mantle` package. The skill
+holds no contract and does not depend on the SDK version: it sends the agent to `mantle help`, which prints the docs
+shipped inside the installed package. So the skill can come from the latest repository while the application pins any
+version.
 
 ## 1. Install the `mantle` skill
 
-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.1-alpha.2`). 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:
+Any agent that reads skills:
 
 ```sh
-codex plugin marketplace add aotter/mantle --ref v0.2.1-alpha.2
-codex plugin add mantle@mantle
+npx skills add aotter/mantle@mantle
 ```
 
-For Claude Code, first clone the release into a directory you will keep:
+The explicit name excludes the repository's maintainer skills. As a plugin, which carries the same one skill and no
+hosted-service connection:
 
 ```sh
-git clone --depth 1 --branch v0.2.1-alpha.2 https://github.com/aotter/mantle.git mantle-plugin
+codex plugin marketplace add aotter/mantle
+codex plugin add mantle@mantle
 ```
 
-Then, in Claude Code, use that checkout's absolute path:
-
 ```text
-/plugin marketplace add /absolute/path/to/mantle-plugin
+/plugin marketplace add aotter/mantle
 /plugin install mantle@mantle
 ```
 
-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 aotter/mantle@mantle
-```
-
-Without a version it follows `main`, the latest stable release. To match the
-application's SDK exactly, add its release tag: `npx skills add aotter/mantle#v0.2.1-alpha.2@mantle`.
-
-When upgrading the SDK, update the marketplace ref or local tagged checkout and
-refresh/reinstall the plugin using the host's native workflow. Verify the loaded
-manifest version and skill source. Do not reset a checkout containing local edits.
-
-Read the path the installer prints (for project-local Codex,
-`.agents/skills/mantle/SKILL.md`). The skill installs no SDK, creates no
+Cursor and GitHub Copilot read their plugin manifests from the same repository. The skill installs no SDK, creates no
 project and copies no handbook.
 
-## 2. Install the SDK, then read its own docs
+## 2. Install the SDK and read its docs
 
-Use the version the project already pins. For a new project, install this
-handbook's version exactly. 0.2.1-alpha.2 is a prerelease; stable 0.2.0 remains the
-production line, and its own tagged handbook describes it.
+Use the version the project already pins. For a new project, pick one exact version from
+[Releases](../releases/index.md) (only plain `X.Y.Z` versions are for production) and pin every selected
+`@aotter/mantle*` package to it:
 
 ```sh
-pnpm add --save-exact @aotter/mantle@0.2.1-alpha.2
+pnpm add --save-exact @aotter/mantle@<version>
+npx mantle help
 ```
 
-Add optional `@aotter/mantle-ui@0.2.1-alpha.2` and `@aotter/mantle-admin@0.2.1-alpha.2` 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
-node_modules/@aotter/mantle/docs/handbook/start/overview.md
-node_modules/@aotter/mantle/docs/handbook/reference/features.md
-node_modules/@aotter/mantle/docs/skills/<workflow>/SKILL.md
-```
-
-These ship in the npm tarball and match the installed code. Prefer them over
-the skill's GitHub copy and over any online handbook.
-
-| Package skill | Read it when |
-|---|---|
-| `docs/skills/develop/SKILL.md` | changing manifests, handlers, the service or its surfaces |
-| `docs/skills/integrate/SKILL.md` | adding Mantle to an existing application |
-| `docs/skills/update/SKILL.md` | upgrading `@aotter/mantle`, including from 0.1.x |
-| `docs/skills/provision/SKILL.md` | deploying, with production sign-in |
-| `docs/skills/media-gc/SKILL.md` | auditing or removing stale R2 uploads |
-| `docs/skills/performance/SKILL.md` | after acceptance converges, or when a page, first request or query is slow |
-
-0.2.0 has no `mantle skills` command: nothing is copied into the project.
-An agent reads these files from `node_modules` when the task calls for them.
+`mantle help` prints the installed version's entry page; prefer it over any online copy of this handbook.
 
 ## 3. Verify the application
 
-Run the app's exact generation command with `--check`, typecheck, implement every printed handler and typecheck again. Test actual routes and persisted state. With selected Admin, mount `entries(bindings.schemas, bindings.adapter)` and serve assets separately. Verify member/admin OTP, row visibility and OCC. Installing a skill proves none of these flows.
+Run the app's exact generation command with `--check`, typecheck, implement every printed handler and typecheck again.
+Test actual routes and persisted state, then run acceptance as the entry page describes. Installing a skill proves none
+of these flows.
 
-If packaged docs are missing, reinstall the SDK version pinned by the app. If a feature differs from an online page, read the installed docs rather than assuming compatibility.
+If `mantle help` reports missing docs, reinstall the SDK version the app pins. If a feature differs from an online page,
+the installed docs win.

package/docs/handbook/guides/agent-workflow-acceptance.md

@@ -85,6 +85,20 @@ rounds below before claiming the user-facing work is done. Keep the author's
 capability map and worked call sequence out of the fresh agent's prompt: an MCP
 evaluator must discover the workflow from public tool descriptions and results.
 
+## Plan the run
+
+The plan the user approves before the build ([Build from a product brief](../start/agents.md#build-from-a-product-brief))
+says in plain words who tries the app and what they try to get done. Behind it, the run
+fixes:
+
+- each evaluator you will start: its role (`admin`, `user`, a visitor), the surfaces it uses (Admin, member pages,
+  REST, MCP, visitor pages) and the goals it is asked to finish, in the user's words;
+- the round limit (at most three) and what triggers a re-run;
+- what the environment needs, such as a browser for a visitor or member page. Provide it yourself (install a headless
+  browser if none is there); only what you cannot provide goes to the user now, rather than reported as BLOCKED later.
+
+Keep the rubric itself private: the plan names goals, never the checks an evaluator is graded on.
+
 ## Run role-only acceptance rounds until they converge
 
 The evaluator gets a role, not a task list. It works out what that role needs
@@ -154,10 +168,11 @@ acceptance as BLOCKED and report the scripted checks on their own
 [layers](#report-done-ness-in-layers). Do not invent
 an independent result. Do not deploy or publish merely to obtain acceptance.
 
-Acceptance proves the behavior, not its speed. Once a round converges, the
-[performance skill](../../skills/performance/SKILL.md) decides which performance
-checks apply and holds them to their targets; a performance repair that changes
-what a role sees or can do returns here, scoped by the
+Acceptance proves the behavior, not its speed. For every role and surface a
+round reports CONVERGED, the [performance pass](performance.md)
+decides which performance checks apply and holds them to their targets. BLOCKED
+or UNVERIFIED parts are reported as they are, never optimized. A performance
+repair that changes what a role sees or can do returns here, scoped by the
 [re-verification rule](#re-verify-what-a-repair-touches).
 
 ## Re-verify what a repair touches
@@ -300,6 +315,20 @@ reported, layer by layer; it is not done:
 | 4. External platform | not applicable: no deployment or external host requested | |
 ```
 
+## Summarise for the user
+
+Lead the handoff with what acceptance found and fixed, so the user sees the value of the rounds:
+
+```markdown
+| Evaluator (role, surfaces) | Rounds | Found | Fixed in | Final |
+| --- | --- | --- | --- | --- |
+| admin: Admin, admin MCP | 2 | P1: approving a stale event overwrote a newer edit | `approve-event` checks the version | CONVERGED |
+| user: member pages, MCP | 1 | none | | CONVERGED |
+| visitor: public pages | 1 | P2: no link back from an event to the list | `src/routes.ts` | CONVERGED |
+```
+
+Name each finding by its effect on the user, not the code, then give the layered status below.
+
 ## Record evidence in the existing issue or handoff
 
 Use ordinary Markdown; no new receipt schema or framework is required:

package/docs/handbook/guides/mcp-apps.md

@@ -86,7 +86,9 @@ source/origin guard is not a protocol implementation.
 
 Applications own domain components and build entries. A frontend MCP App uses its
 own React entry, official ext-apps and optionally mantle-ui, registered through
-Core's generic resources. It needs no Admin package or Admin session. See the
+Core's generic resources. It needs no Admin package or Admin session. Build it
+with `App` from `@modelcontextprotocol/ext-apps`: register `ontoolinput`/`ontoolresult` before `connect()` and use
+`callServerTool` for host-proxied calls; never write a second `postMessage` bridge beside the official client. See the
 [standalone frontend example](../../examples/frontend-mcp-app/README.md) for a
 small owner-scoped example. `public` names the frontend endpoint, not anonymous
 access: use the application's verified Caller and generated authorization rules.