@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.7

package/docs/skills/media-gc/SKILL.md

@@ -11,14 +11,25 @@ metadata:
 
 # Mantle Media GC
 
+## Generated native applications (alpha.7 and later)
+
+If the installed README describes generated native queries, read
+`docs/handbook/cloudflare/media-r2.md` and app-owned site/media wiring instead of Core storage
+options. Resolve the exact configured bucket and declared purposes. The
+`uploads/` candidate audit below still applies. Committed copies live under
+`committed/` and must never be candidates. Attempt-isolated committed copies
+retained after an uncertain DB outcome require reconciliation with live DB
+references before any separately authorized cleanup.
+
 Use the connected Cloudflare API. Audit by default; delete only the exact
 objects approved by the user.
 
 ## Preflight
 
-1. Read `wrangler.jsonc` and `src/service.ts`. Resolve the R2 bucket that
-   `r2MediaStorage` uses and the media purpose names in the site defaults
-   passed to `d1Storage(db, { site })`.
+1. Read `wrangler.jsonc`, the app-owned entry (`src/worker.ts` by default,
+   or the generation command's `--entry`) and its media wiring. Resolve the R2
+   bucket that `r2MediaStorage` uses and the media purpose names in
+   `siteDefaults.media.purposes` selected by `--site`.
 2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
    ask; never choose by name similarity.
 3. Use the Cloudflare OpenAPI search before execution to resolve the current

package/docs/skills/provision/SKILL.md

@@ -11,94 +11,28 @@ metadata:
 
 # Provision a Mantle project
 
-Provision only after the user asks to create remote resources or ship. Read the
-installed `docs/handbook/cloudflare/deploy-and-operate.md` and
-`docs/handbook/cloudflare/authentication.md` first.
-
-## Choose the target
-
-Ask which target, unless the project already shows one.
-
-| Target | Config | Follow |
-|---|---|---|
-| Cloudflare Workers | `wrangler.jsonc` | the rest of this skill |
-| ChatGPT Sites | the Site's hosting config | installed `docs/handbook/cloudflare/chatgpt-sites.md`; publish through Sites, never `wrangler deploy` |
-| Mantle Cloud | Cloud project link | the plugin's `mantle` skill and its Cloud workflow; connect Cloud MCP and use its exact host contract, not `wrangler deploy` |
-| Bun (host `bun`) | `.env` | self-hosted; installed `docs/handbook/start/project-and-cli.md` (Bun), not this skill |
-
-Self-hosting is always an option; never present a hosted target as required.
-
-## Local gate
-
-```bash
-pnpm install --frozen-lockfile
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-git status --short
-```
-
-Confirm the active Cloudflare account with the user before creating anything.
-
-## Cloudflare
-
-1. **Database.** `pnpm exec wrangler d1 create <name>` and put the
-   `database_id` into `wrangler.jsonc`'s `d1_databases[0]`, keeping the
-   binding `DB`. With dialect `postgres`, instead run
-   `pnpm exec wrangler hyperdrive create <name> --caching-disabled --connection-string=...`
-   (the connection string by hidden input) and replace the placeholder id in
-   `hyperdrive[0]`, keeping the binding `HYPERDRIVE`. An existing 0.1.x
-   database is never reused: 0.2 starts on a new one. PostgreSQL uses
-   node-postgres on every host (Hyperdrive on Cloudflare, a `pg.Pool` on Bun);
-   set `statement_timeout` (10s or less) and `TimeZone` `UTC` on the database
-   role, which boot checks on both.
-2. **Origin.** Set `PUBLIC_ORIGIN` in `vars` to the deployed HTTPS origin.
-   Update it together with any OAuth callback when a custom domain is added.
-3. **Sign-in (identity `mantle`).** Choose one production method and edit
-   `src/service.ts`; never deploy `ConsoleEmailSender`:
-   - **Email OTP or magic link** with the application's own `EmailSender`
-     over its email provider, `bootstrapOwner: { match: "email", value }`.
-   - **GitHub**: `{ kind: "social", provider: "github", options: { clientId, clientSecret } }`
-     and `bootstrapOwner: { match: "github-login", value }`. The user creates a
-     GitHub OAuth App with callback `<PUBLIC_ORIGIN>/api/auth/callback/github`.
-   Remove the preset's loopback-only check once the method is real.
-4. **Secrets.** Never commit them or put them in chat, logs or `wrangler.jsonc`
-   `vars`. Store production values in the deployment's secret store. Use a
-   connector, or hidden input:
-
-```bash
-openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET
-read -rsp "GitHub client secret: " S && printf '%s' "$S" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET; unset S
-```
-
-   Set `BETTER_AUTH_SECRET` once; rotating it signs everyone out.
-5. **Optional bindings.** R2 for media only when asked
-   (`docs/handbook/cloudflare/media-r2.md`).
-6. **Deploy.** `pnpm exec wrangler deploy`. The first request creates the
-   tables. Later Schema changes on D1: run
-   `mantle generate --check --database <local SQLite file>` (local D1 under
-   `.wrangler/state/v3/d1/`, which must have run the plan now deployed) before
-   each deploy and resolve any blocked change by hand.
-
-Commit and push only non-secret changes.
-
-## Verify the deployed service
-
-- A public View and an HTTP Trigger answer.
-- Sign-in works with the production method; the owner gets
-  `GET /admin/api/me` → `owner`, a second account gets 403.
-- `/mcp` answers `tools/list`, and an anonymous call to a protected tool is
-  401 with a `WWW-Authenticate` challenge. When every public tool `requires` a
-  caller, anonymous `initialize` and `tools/list` are already that 401.
-- Every enabled schedule appears in the Worker's cron triggers.
-
-## Handoff
-
-Return the public origin, the sign-in method and who the owner is, the MCP
-URL (`<origin>/mcp`), the resources created or reused, and anything deferred.
-
-## Don't
-
-- Don't create remote resources before the user asks to ship.
-- Don't commit secrets or put them in `wrangler.jsonc` `vars`.
-- Don't point a 0.2 service at a 0.1.x database.
-- Don't patch `site_config` or `_mantle_*` tables; boot owns them.
+## Workflow
+
+Read the installed SDK README and version-matched handbook before editing.
+
+Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
+with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
+all generated output, run the same generation command with `--check`, and keep
+bundle `dist/` untracked. The app owns its verified Caller, handlers and native
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
+
+Deploy/create resources only within the user's authorization; reuse configured
+host resources. Apply reviewed and rehearsed migrations before routing traffic;
+imports/first requests perform no DDL or schema checks. Keep auth dynamic, production
+secrets in the host store, trusted HTTPS origin and verified bootstrap rule,
+production email and selected media wiring. Configure Admin ASSETS worker-first
+as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#workers-assets-and-secrets). Hyperdrive caching stays off; PG settings are deployment-owned.
+Bun uses native Database/SQL, an app server and scheduler. Verify admin sign-in
+(role admin), denied access, public reads, a persisted write, MCP and selected UI.
+Report artifact/resources/checks and keep rollback artifacts.
+
+Use the installed [Native Admin](../../handbook/guides/native-admin.md) asset
+contract and `entries(bindings.schemas, bindings.adapter)`. Admin SPA assets
+belong to `@aotter/mantle-admin`, while UI supplies the shared kit. Verify both
+member and admin OTP/UI flows. Deployment of an authorized application does
+not authorize SDK publication; a workspace preview remains a preview.

package/docs/skills/update/SKILL.md

@@ -10,50 +10,26 @@ metadata:
 
 # Mantle Update
 
-Upgrade deliberately; never overwrite application-owned code.
+## Workflow
 
-1. Inspect `git status`, `package.json`, the lockfile and the installed
-   `@aotter/mantle` version. Keep unrelated local changes. Work on a branch.
-2. Choose an explicit target version (`npm view @aotter/mantle dist-tags`).
-   Read its release notes on GitHub and, after installing, its own
-   `node_modules/@aotter/mantle/docs/`. The old version's docs are not the new
-   contract.
-3. **From 0.1.x to 0.2:** stop here and follow
-   `node_modules/@aotter/mantle/docs/upgrade-0.1-to-0.2.md` after installing
-   the target. There is no codemod and no in-place database upgrade: the
-   project moves by hand, to a new database.
-4. Set `@aotter/mantle`, and `@aotter/mantle-ui` where present, to the same
-   exact version (`@aotter/mantle-admin-ui` is gone: the console is
-   `@aotter/mantle-ui/admin`), and update the lockfile with the
-   package manager. Review the dependency diff and any peer changes
-   `mantle generate` names.
-   With identity `mantle`, inspect auth database upgrade requirements in
-   `docs/handbook/cloudflare/authentication.md` before starting the new service.
-   Better Auth 1.7.0–1.7.2's required legacy `account.issuer` needs a
-   data-preserving host-specific constraint migration when moving to 1.7.7;
-   fresh-database success alone does not verify an upgrade. Back up the service's
-   own database and retain existing users, sessions, roles and content.
-5. Regenerate and check:
+Read the installed SDK README and version-matched handbook before editing.
 
-```sh
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-```
+Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
+with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
+all generated output, run the same generation command with `--check`, and keep
+bundle `dist/` untracked. The app owns its verified Caller, handlers and native
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
 
-   An existing PostgreSQL service also follows the upgrade notes in
-   `docs/handbook/releases/index.md` (SQL rewrites, `mantle generate` for the
-   new dialect version, the regenerated `src/service.ts`).
-6. The preset (`src/service.ts`, `src/index.ts`, `src/handlers.ts`,
-   `wrangler.jsonc`) is never
-   rewritten. Generate into a scratch directory with the same manifests and
-   `mantle.config.json`, diff it against the project's files, and apply the
-   changes that matter by hand.
-7. Run the service locally and test its real routes and sign-in. Before
-   deploying a SQLite project, run
-   `mantle generate --check --database <local SQLite file>` to see what boot
-   will change.
+Pin exact target SDK/peer versions and read its release notes and Admin asset
+installation instructions. Core-to-native replaces app imports/wiring; it is not
+a package-only update. Preserve users, sessions, content and application code.
+Review emitted SQL/policy diffs and rehearse explicit data-preserving schema/auth/role
+migrations on a copy. Initial schema.sql never authorizes rebuilding production
+tables. Verify auth/Admin/MCP/REST, locks and persistence before authorized cutover.
 
-Report the old and new versions, the checks and their results, what changed
-in the service files, and what remains. A dependency update does not
-authorize a deploy. Never commit secrets.
+Follow [Native Admin](../../handbook/guides/native-admin.md) for the three-package
+SDK/Admin/shared-kit split and asset/extension/MCP App subpath moves; old UI
+subpaths have no compatibility aliases. Pin only actually published versions,
+or explicitly use a matching workspace preview. Recheck member and Admin OTP,
+all affected native routes, private field visibility, OCC and unknown outcomes.
+Do not publish a package as part of an application dependency update.

package/docs/source/scripts/postgres-adapter.ts

@@ -0,0 +1,101 @@
+/** Reusable application-owned adapter check. The factory must open an isolated, disposable database/schema. */
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { unstable_splitSqlQuery } from "wrangler";
+import type { Postgres } from "../src/kernel/contracts.js";
+import { procedure, transaction } from "../src/kernel/driver/postgres.js";
+import { generateOrThrow, writeGenerated } from "../tests/apps/link.js";
+
+export type PostgresAdapterFactory = () => Promise<{ db: Postgres; close(): Promise<void>; interactive?: boolean }>;
+
+const atom = (kind: string, name: string, spec: object) => JSON.stringify({ apiVersion: "cms.mantle.aotter.net/v2", kind, metadata: { name }, spec });
+const properties = { key: { type: "string" }, at: { type: "string", format: "date-time" }, day: { type: "string", format: "date" }, payload: { type: "object" }, units: { type: "integer" }, enabled: { type: "boolean" }, amount: { type: "number" } };
+const source = [
+  atom("Schema", "adapter_items", { title: "Adapter conformance", schema: { type: "object", properties, required: Object.keys(properties) }, uniqueIndexes: [["key"]] }),
+  atom("View", "adapter-items", { surface: "internal", sql: "SELECT id, key, at, day, payload, units, enabled, amount, created_at, CAST(at AS timestamptz) AS computed_at FROM adapter_items ORDER BY id" }),
+  atom("View", "adapter-wire", { surface: "public", sql: `SELECT units AS "quantityAlias", enabled, amount, version AS "versionAlias" FROM adapter_items ORDER BY id` }),
+  atom("Procedure", "adapter-create", { input: { type: "object", properties, required: Object.keys(properties) }, output: { type: "object" }, handler: { sql: "INSERT INTO adapter_items(key, at, day, payload, units, enabled, amount) VALUES(input.key, input.at, input.day, input.payload, input.units, input.enabled, input.amount) RETURNING id, at, day, payload, units, enabled, amount" } }),
+].join("\n---\n");
+
+/** Returns only a check count; assertions retain the exact failing contract. No latency or benchmark data. */
+export async function verifyPostgresAdapter(factory: PostgresAdapterFactory): Promise<{ checks: number }> {
+  const files = await generateOrThrow("bun-postgres", [{ sourceId: "adapter-conformance.yaml", text: source }]);
+  await mkdir(resolve(import.meta.dir, "../tests/apps/.generated"), { recursive: true });
+  const directory = await mkdtemp(resolve(import.meta.dir, "../tests/apps/.generated/adapter-"));
+  let client: Awaited<ReturnType<PostgresAdapterFactory>> | undefined;
+  let checks = 0;
+  try {
+    await writeGenerated(directory, files);
+    const app = await import(pathToFileURL(resolve(directory, "generated.ts")).href);
+    client = await factory();
+    const { db, interactive = true } = client;
+    for (const sql of unstable_splitSqlQuery(files["schema.sql"]!)) await db.unsafe(sql, []);
+    const caller = { kind: "system", reason: "adapter conformance" } as const;
+    const input = { key: "first", at: "2026-10-12T08:00:00.123456+08:00", day: "2024-02-29", payload: JSON.stringify({ text: "'\\", nested: [false, null] }), units: Number.MAX_SAFE_INTEGER, enabled: true, amount: 0.1 };
+    const output = await app.procedures["adapter-create"](db, caller, input);
+    const created = output.results[0][0];
+    assert.equal(created.at, "2026-10-12T00:00:00.123456Z", "declared RETURNING date-time retains microseconds");
+    assert.equal(created.day, input.day, "declared RETURNING date retains calendar day");
+    assert.deepEqual(created.payload, JSON.parse(input.payload), "JSON text is bound verbatim, not JSON-encoded twice");
+    assert.equal(String(created.units), String(input.units), "int8 retains a safe integer exactly");
+    assert.equal(created.enabled, true, "PostgreSQL boolean native output"); assert.equal(created.amount, input.amount, "declared number native output"); checks += 6;
+    const rows = await app.views["adapter-items"](db, caller, {});
+    const count = rows.count;
+    assert.ok(Array.isArray(rows), "unsafe returns a row array");
+    assert.equal(count, 1, "unsafe array carries affected count");
+    assert.equal(rows[0].at, created.at, "declared SELECT date-time retains microseconds");
+    assert.equal(rows[0].day, input.day);
+    assert.match(rows[0].created_at, /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{6}Z$/, "system timestamps have the same wire form");
+    // Computed outputs are native: the driver may return Date (milliseconds) or text (microseconds).
+    assert.ok(rows[0].computed_at instanceof Date || typeof rows[0].computed_at === "string"); checks += 6;
+    await assert.rejects(() => app.procedures["adapter-create"](db, caller, input), { code: "CONFLICT" }); checks++;
+    const step = { sql: "UPDATE adapter_items SET key = $1 WHERE id = $2 RETURNING id", binds: ["changed", "missing"], row: true };
+    await assert.rejects(() => procedure(db, [step], "adapter/zero"), { code: "CONFLICT" }); checks++;
+    const integer = await db.unsafe("SELECT CAST($1 AS bigint) AS positive, CAST($2 AS bigint) AS negative, CAST($3 AS numeric(15,2)) AS decimal", ["9007199254740993", "-9007199254740993", "1234567890123.45"]);
+    assert.equal(String(integer[0].positive), "9007199254740993", "unsafe int8 must not be rounded by an adapter");
+    assert.equal(String(integer[0].negative), "-9007199254740993");
+    assert.equal(integer[0].decimal, "1234567890123.45", "numeric text retains declared scale and precision"); checks += 3;
+    const { default: page } = await import(pathToFileURL(resolve(directory, "paged/wire/views/adapter-wire.ts")).href);
+    for (const value of ["9007199254740991", "9007199254740993", "-9007199254740993", "9223372036854775807", "-9223372036854775808"]) {
+      await db.unsafe("UPDATE adapter_items SET units=CAST($1 AS bigint), version=CAST($1 AS bigint)", [value]);
+      const wire = (await page(db, caller, {})).rows[0];
+      // The selected-boundary module returns exact integer text; REST/MCP turn safe values into numbers.
+      assert.equal(String(wire.quantityAlias), value); assert.equal(String(wire.versionAlias), value);
+      assert.equal(wire.enabled, true); assert.equal(wire.amount, input.amount); checks += 4;
+    }
+    await db.unsafe("UPDATE adapter_items SET version=1", []);
+    const store = app.store(db, caller), collection = store.collection("adapter_items");
+    const changed = { sql: "UPDATE adapter_items SET key = $1 WHERE id = $2 RETURNING id", binds: ["transaction", created.id], row: true };
+    if (!interactive) {
+      let calls = 0;
+      const tapped = { unsafe: (sql: string, values: any[]) => { calls++; return db.unsafe(sql, values); }, begin: db.begin.bind(db) };
+      const limitedStore = app.store(tapped, caller);
+      for (const run of [() => procedure(tapped, [changed, changed], "adapter/multi"), () => limitedStore.transaction(async () => { throw Error("callback must not run"); }), () => limitedStore.batch([limitedStore.collection("adapter_items").update(created.id, { key: "no-write" }, { lock: 1 }), limitedStore.collection("adapter_items").update(created.id, { key: "also-no-write" }, { lock: 1 })])]) {
+        await assert.rejects(run, (error: unknown) => {
+          const e = error as Error & { code?: string; status?: number };
+          return e instanceof Error && e.name === "ContractError" && e.code === "TRANSACTION_UNSUPPORTED" && e.status === 400 && /transaction/i.test(e.message);
+        });
+        assert.equal(calls, 0, "unsupported interactive transaction refuses before any statement"); checks += 2;
+      }
+    } else {
+      await transaction(db, async tx => {
+        await procedure(tx, [changed, changed], "adapter/nested-handle");
+        assert.equal((await tx.unsafe("SELECT key FROM adapter_items WHERE id = $1", [created.id]))[0].key, "transaction");
+        await assert.rejects(() => transaction(tx, async () => {}), /Nested transactions/);
+      }); checks += 2;
+      assert.equal((await db.unsafe("SELECT key FROM adapter_items WHERE id = $1", [created.id]))[0].key, "transaction", "begin commits after callback"); checks++;
+      const rollback = new Error("rollback sentinel");
+      await assert.rejects(() => transaction(db, async tx => { await tx.unsafe("UPDATE adapter_items SET key = $1 WHERE id = $2", ["rolled-back", created.id]); throw rollback; }), error => error === rollback);
+      assert.equal((await db.unsafe("SELECT key FROM adapter_items WHERE id = $1", [created.id]))[0].key, "transaction", "begin rolls back callback failure"); checks += 2;
+      await store.batch([collection.update(created.id, { key: "batch" }, { lock: 1 })]); checks++;
+    }
+    const uncertain = { unsafe: db.unsafe.bind(db), begin: async <T>(_options: string, callback: (tx: Postgres) => Promise<T>) => { await callback(db); throw new Error("socket lost at COMMIT"); } };
+    await assert.rejects(() => transaction(uncertain, async () => {}), { code: "OUTCOME_UNKNOWN" }); checks++;
+    return { checks };
+  } finally {
+    try { if (client) await client.close(); }
+    finally { await rm(directory, { recursive: true, force: true }); }
+  }
+}

package/docs/upgrade-0.1-to-0.2.md

@@ -1,9 +1,24 @@
 # Upgrading from 0.1.x to 0.2.0 (for AI agents)
 
+For **0.2.0-alpha.7 and later**, use the
+[native SDK migration](handbook/releases/index.md#native-sdk-migration-alpha7),
+[current CLI](handbook/start/project-and-cli.md) and
+[app shell](examples/app-shell/). The application owns routing,
+Auth, native handles and database migrations; the former `createMantle` runtime,
+host presets, boot-time convergence and CLI flags below have been replaced.
+Install the same exact version of `@aotter/mantle`, `@aotter/mantle-ui` and,
+when selecting Admin, `@aotter/mantle-admin`. Start with a new database for a
+0.1.x migration and preserve every authorization, scope and OCC requirement.
+The remainder describes the earlier alpha contract for historical reference.
+
 No codemod, and no in-place upgrade of a 0.1.x database. A coding agent moves
-one project by hand with this guide. When it and ADR-0032 to ADR-0035
-(`docs/adr/`), ADR-0036 (host and dialect) or ADR-0038 (Bun) disagree, the
-ADR wins.
+one project by hand with this guide. When it and
+[ADR-0032](https://github.com/aotter/mantle/blob/develop/docs/adr/0032-store-centric-core-and-service-contract.md),
+[ADR-0033](https://github.com/aotter/mantle/blob/develop/docs/adr/0033-storage-converges-to-the-plan.md),
+[ADR-0034](https://github.com/aotter/mantle/blob/develop/docs/adr/0034-store-is-authored-as-sql.md),
+[ADR-0035](https://github.com/aotter/mantle/blob/develop/docs/adr/0035-sql-dialects.md),
+[ADR-0036](https://github.com/aotter/mantle/blob/develop/docs/adr/0036-host-and-dialect.md) or
+[ADR-0038](https://github.com/aotter/mantle/blob/develop/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
 
 ## Rules
 
@@ -70,10 +85,10 @@ camelCase names.)
 
 | 0.1.x | 0.2.0 |
 |---|---|
-| `scope: { owner: $ctx.user.id }` | `scope: { owner: auth.uid() }`. The field is a required string, the leftmost column of an index (`indexes: [[owner]]`), and the first column of every `uniqueIndexes` entry. Store fills it; a write never sets it |
+| `scope: { owner: $ctx.user.id }` | `scope: "owner = auth.uid()"`. The field is a required string, the leftmost column of an index (`indexes: [[owner]]`), and the first column of every `uniqueIndexes` entry. Store fills it; a write never sets it |
 | `x-mantle-bind: ctx.user` on a field only its owner may see | remove the bind; add `scope` as above |
 | any other `x-mantle-bind: ctx.user` | remove the bind; every write that sets the field sets it to `auth.uid()`, never to an input |
-| `x-mantle-bind: ctx.staff` | remove the bind; set it to `auth.uid()` in writes whose Procedure `requires` `ctx.staff` |
+| `x-mantle-bind: ctx.staff` | remove the bind; set it to `auth.uid()` in writes whose Procedure requires `ctx.admin` |
 | `x-mantle-bind: now` | remove the bind; set it to `now()` in every write that sets it |
 | `searchableFields` | unchanged, now trigram full-text search; date and date-time fields are refused |
 
@@ -158,11 +173,11 @@ The generated types list exactly the plan's refs.
 |---|---|
 | `ctx.user` present | `ctx.caller.kind === "user"`. Never test `!== "anonymous"`: a schedule runs as `system` |
 | `ctx.user.id` | `ctx.caller.subject` (after that check) |
-| `ctx.staff` | `ctx.caller.kind === "user" && ctx.caller.role !== null` |
+| `ctx.staff` | `isAdmin(ctx.caller)` from `@aotter/mantle/contracts` |
 | `ctx.event`, `ctx.schedule` | `ctx.cause` (`kind`: `http`, `mcp`, `internal`, `schedule`, `lifecycle`); `ctx.cause.cron` is POSIX, so shift any cron string the code compares |
 | `ctx.event.entry` | **a loop** over `ctx.cause.rows` (one statement can touch many rows; never `rows[0]`). Rows are flat: `entry.data.x` → `row.x` |
 | `ctx.store.view(name, { params, page, show, search, filters })` | `ctx.store.view(name, { input, limit, cursor, search, filters })`; `search` and `filters` match only the View's `uiSchema.list.searchFields` and `filterFields` |
-| `runtime.entries`, `runtime.executeView`, `ctx.writeAtomically` | `ctx.store.select`, `ctx.store.view`, `ctx.store.write([...ops])` (all or nothing), `ctx.store.id()` |
+| `runtime.entries`, `runtime.executeView`, `ctx.writeAtomically` | `ctx.db.<schema>.get / first / find`, `ctx.store.view`, `ctx.store.write([...ops])` (all or nothing), `ctx.store.id()` |
 | `runtime.store.as(ctx)` | `runtime.store.as(caller)` |
 | calling another Procedure through a `getRuntime` closure | `await ctx.invoke("procedure-name", input)` (keeps the caller, re-checks its auth) |
 
@@ -179,8 +194,9 @@ only in trusted host code.
    old Worker into the new files by hand.
 3. With `identity: mantle`, sign-in uses a console email sender locally;
    replace it with a real `EmailSender` before deploying.
-4. Staff MCP stays at `/mcp/staff`, behind an OAuth token with the `mcp`
-   scope and a staff role; MCP clients keep their URL.
+4. Admin MCP moves from `/mcp/staff` to `/mcp/admin`. Update MCP client URLs.
+   It admits only the admin layer classified by Better Auth’s admin plugin
+   `adminRoles` (default `["admin"]`), and requires the `mcp` scope for tokens.
 5. Import data into the new database through `runtime.store`. A scoped row
    goes through `runtime.store.as(<its owner's caller>)`, so the scope field is
    the owner. `status`, `created_at` and `author_id` cannot be imported: