@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.3

package/docs/handbook/cloudflare/authentication.md

@@ -24,10 +24,14 @@ createMantleAuth({
   methods: [{ kind: "email-otp", sender: new ConsoleEmailSender() }],
   bootstrapOwner: { match: "email", value: env.ADMIN_EMAIL },
   ipAddressHeaders: ["cf-connecting-ip"],
-  oauthProvider: { loginPage: "/admin/sign-in", consentPage: "/oauth/consent", scopes: ["mcp"], mcpResource: `${origin}/mcp` },
+  oauthProvider: { loginPage: "/admin/sign-in", consentPage: "/admin/oauth/consent", scopes: ["mcp"], mcpResource: `${origin}/mcp` },
 });
 ```
 
+`consentPage` is Admin's consent page when the service mounts Admin (the
+preset does); without Admin it is `/oauth/consent`, the plain page
+`createAuthRoutes` serves. Both post the decision to `/oauth/consent`.
+
 then `createCallerResolver(auth, { jwtBearer: { audience: `${origin}/mcp`, scopes: ["mcp"] } })`,
 `createAuthRoutes(auth, { resolver })` and an `AdminIdentity` over the auth's
 own methods. With dialect `postgres` the preset passes `database:
@@ -38,6 +42,54 @@ passes `bunAuthDatabase(sql)` and `bunDatabaseDriver(sql)` (or the bun:sqlite
 
 ### Local sign-in
 
+Install auth and MCP dependencies at the versions declared in the installed
+Core package's `peerDependencies`; the generator prints a versioned install
+command and refuses incompatible installed peers before writing generated files.
+The preset owns convergence; a normal fresh local database needs no manual auth
+migration. `auth.ready` initializes Better Auth's context; auth tables are prepared
+lazily before authenticated operations. Mantle runs Better Auth's explicit schema
+validation after that preparation, including when the schema ledger is current;
+an incompatible existing schema still rejects authentication.
+
+#### Upgrading an existing 1.7.0–1.7.2 auth database
+
+Those Better Auth versions created a required `account.issuer` column that
+1.7.7 no longer writes. Automatic additive convergence preserves that column;
+it cannot make a required unused column safe for future inserts. Before starting
+the upgraded service, the database owner must migrate this legacy constraint.
+Fresh databases need no such step.
+
+For PostgreSQL, first inspect the service's own database/schema and back it up:
+
+```sql
+SELECT table_schema, is_nullable, column_default
+FROM information_schema.columns
+WHERE table_name = 'account' AND column_name = 'issuer';
+```
+
+If the legacy column is required and has no default, apply this in the service's
+auth schema (the example assumes it is selected by `search_path`):
+
+```sql
+BEGIN;
+ALTER TABLE "account" ALTER COLUMN "issuer" DROP NOT NULL;
+COMMIT;
+```
+
+This retains every row and existing issuer value. It changes only the obsolete
+constraint; new accounts may leave that column null. Restart the service after
+the migration so Better Auth checks the repaired schema in a fresh context.
+Verify existing users, roles, sessions and content rows, then sign in again.
+Do not drop auth tables or disable schema validation. This applies to native Bun
+PostgreSQL and Cloudflare/Hyperdrive PostgreSQL alike.
+
+For D1/SQLite, `ALTER COLUMN` is unavailable. Use a database-owner-reviewed table
+rebuild that retains every column/value, index and foreign-key relationship while
+making the legacy issuer nullable; do not run the PostgreSQL statement there.
+See Better Auth's [1.7 upgrade guide](https://www.better-auth.com/docs/guides/1-7-upgrade-guide).
+Mantle's portable auth facade does not silently perform engine-specific table
+rebuilds or remove historical fields.
+
 ```sh
 cp .dev.vars.example .dev.vars   # ADMIN_EMAIL, a random BETTER_AUTH_SECRET, PUBLIC_ORIGIN=http://127.0.0.1:8787
 pnpm exec wrangler dev --local
@@ -53,6 +105,65 @@ origin and both secrets exist. Otherwise it uses
 `createSetupIncompleteAuth`, which refuses sign-in with a message, so a
 deployed service never prints codes to its log.
 
+On Bun, copy `.env.example` to `.env`, set `PUBLIC_ORIGIN=http://127.0.0.1:3000`
+and run `bun src/index.ts`; send the same HTTP requests to port 3000. Codes print
+to the Bun console. Normalize test email addresses to lowercase when matching
+that output. Treat codes and session cookies as secrets in test logs.
+
+Local clients share the loopback socket IP and therefore share sign-in limits.
+Multi-user smoke tests must respect the retry window (HTTP 429) rather than
+spoofing forwarding headers or disabling production limits. `rateLimit: {
+window: 60, max: 100 }` changes the general quota, but plugin-specific OTP limits
+still apply; changing it is not a way to bypass those limits.
+
+### MCP clients for members
+
+`/admin/sign-in` suits staff. When members connect an MCP client to the public
+`/mcp`, set `loginPage` to the service's own sign-in page. That page must
+continue the authorization: Better Auth sends the browser there with the
+request signed, and the sign-in carries it back as `oauth_query`, then follows
+the `url` it answers (consent) instead of the page's own destination:
+
+```ts
+import { signedOAuthQuery } from "@aotter/mantle-ui/kit";
+
+const oauthQuery = signedOAuthQuery(window.location.search);
+const res = await fetch("/api/auth/sign-in/email-otp", { method: "POST", credentials: "include",
+  headers: { "content-type": "application/json" }, body: JSON.stringify({ email, otp, ...(oauthQuery ? { oauth_query: oauthQuery } : {}) }) });
+const { url } = await res.json();
+location.assign(url ?? "/account");
+```
+
+The generated preset does not enable dynamic client registration (DCR).
+An `access_denied` response from `/api/auth/oauth2/register` does not mean
+member OAuth is broken. An owner can register a known local client through
+the public `MantleAuth` API, without opening DCR:
+
+```ts
+const client = await auth.registerOAuthClient({
+  requestHeaders: ownerRequest.headers,
+  clientName: "Local MCP client",
+  redirectUris: ["http://127.0.0.1:3456/callback"],
+  applicationType: "native",
+  tokenEndpointAuthMethod: "none",
+  grantTypes: ["authorization_code", "refresh_token"],
+  responseTypes: ["code"],
+  scope: ["mcp"],
+  requirePKCE: true,
+});
+```
+
+Use a real owner session, keep persisted user consent, and configure the MCP
+client with the returned `clientId`. This belongs in an owner-controlled
+management path, not an anonymous registration handler. Choose DCR separately
+according to the host's registration policy.
+
+When DCR is enabled, registration takes a client that names no `application_type`
+and registers only `http` loopback redirects (`localhost`, `127.0.0.1`,
+`[::1]`) as `native` (RFC 8252), which is how local MCP clients register; any
+other registration is checked as Better Auth checks it (`web` needs `https` on a
+non-loopback host).
+
 ### Production
 
 Replace the local choices in `src/service.ts`:

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

@@ -99,10 +99,21 @@ you built (`PLAN_FINGERPRINT_MISMATCH`). The fingerprint is in
 
 ## Mantle Cloud
 
-Deploying a 0.2.0 service to Mantle Cloud needs Cloud's host protocol 3, which
-uploads the compiled plan and the service entry. Mantle Cloud does not accept
-0.2.0 services yet. The plugin's `mantle` skill and its helper script check
-the plan and the installed Core version so a project is ready when it does.
+Mantle Cloud accepts its pinned 0.2 service contract through host protocol 4. A verified source receipt is required before save.
+Connect Cloud MCP and follow the plugin's `mantle` skill and its
+`references/cloud.md` workflow. Call `cloud_host_contract` for the selected
+project before installing or packing: Cloud returns the exact Core version
+and revision. Do not substitute a moving npm tag or upload a self-hosted
+Worker's platform wiring. Cloud supplies identity and D1 storage; PostgreSQL
+plans are not accepted.
+
+The skill's `scripts/mantle-cloud.mjs` helper orchestrates save, paired
+preview and publish through the connected MCP tools. Follow its literal
+`nextAction`, keeping grants on stdin and preserving the project and operation
+IDs on retry. A saved or paired version is not a serving deployment; publish
+only under the user's authorization and verify Cloud's returned serving state.
+Its offline `check` reports `cloud: "not_checked"`, which proves local
+readiness only. Use Cloud's workflow, not `wrangler deploy`, for that target.
 
 ## Moving data from 0.1.x
 

package/docs/handbook/concepts/authorization.md

@@ -117,7 +117,13 @@ The writer comes from the caller, never from an input. See
 
 Admin's gate admits any staff role, and each Admin route names the least role
 it needs. Admin reads and writes through `runtime.store.as(caller)`, so scope
-and `requires` apply to staff exactly as to anyone. See
+applies to generic entry routes. A View or Procedure's `requires` applies when
+that atom runs, including Admin reports and operations; it does not restrict
+generic entry reads or writes. Root Schema `readOnly: true` blocks generic
+writes, while reads still follow Admin's role gate and Schema scope.
+For an unscoped table shared by members and reviewers, an owner-filtered View
+does not hide its rows from contributors using generic Admin routes. Compose
+a stricter Admin surface in the application when the product requires it. See
 [Customize Admin](../guides/admin-ui.md).
 
 ## Further reading

package/docs/handbook/concepts/mcp-and-agents.md

@@ -50,8 +50,8 @@ again.
 
 `createMantleAuth` runs Better Auth's OAuth provider with `mcpResource:
 {PUBLIC_ORIGIN}/mcp`. An MCP client discovers it from the 401 challenge's
-`resource_metadata` (`/.well-known/oauth-protected-resource/mcp`), registers,
-sends the user through sign-in and consent (`/oauth/consent`), and calls `/mcp`
+`resource_metadata` (`/.well-known/oauth-protected-resource/mcp`), uses a registered client,
+sends the user through sign-in and consent (Admin's `/admin/oauth/consent`, or the plain `/oauth/consent`), and calls `/mcp`
 with the token. The resolver (`createCallerResolver(auth, { jwtBearer: { audience, scopes: ["mcp"] } })`)
 verifies it on every request and reads the user's current role; nothing is
 cached. Every MCP surface also keeps the scope floor (ADR-0014): a credential

package/docs/handbook/guides/admin-ui.md

@@ -121,6 +121,35 @@ and manages media, `owner` manages staff, site settings and the developer
 console. Operations and staff Views are further limited by their own
 `requires`.
 
+Those atom predicates do not restrict generic Schema entry routes. A root
+Schema `readOnly: true` blocks generic writes, not reads. In a service where
+only owner/editor reviewers may read an unscoped table, restrict the Admin
+surface in the application-owned `src/service.ts`:
+
+```ts
+// Replace the preset's Admin composition, keeping its existing options.
+const adminSurface = createAdminSurface(runtime, { /* existing Admin options */ });
+const admin = withCaller(resolver, async (request, caller) => {
+  if (new URL(request.url).pathname.startsWith("/admin/api/") &&
+      caller.kind === "user" && caller.role === "contributor") {
+    return Response.json({ error: {
+      code: "AUTH_DENIED", message: "Admin access requires an owner or editor role.",
+    } }, { status: 403 });
+  }
+  return adminSurface(request, caller);
+});
+```
+
+The preset already imports `withCaller` from `@aotter/mantle`. Reuse its
+resolver so credential validation and the session origin guard run once;
+Admin retains its own gates for members and anonymous callers. Contributors
+can use an application-owned page over an owner-filtered public View. Keep
+sign-in, OAuth consent and UI assets reachable; restricting the whole `/admin`
+prefix would also block member MCP consent at `/admin/oauth/consent`. This is
+host surface composition, not a Procedure `ref` handler or a new Manifest
+permission key. Exercise generic entry reads, reports and operations with
+each role, including after revoking a role in an existing session.
+
 ## Verify a change
 
 1. Run `mantle generate`, then `mantle generate --check`.

package/docs/handbook/reference/surface.md

@@ -34,7 +34,7 @@ origins.
 | `GET /api/auth/methods` | the sign-in methods this service offers |
 | `/api/auth/*` | Better Auth: email OTP (`/email-otp/send-verification-otp`, `/sign-in/email-otp`), magic link, social and generic OAuth sign-in, sessions, sign-out, the OAuth provider |
 | `/.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource[/mcp]` | OAuth metadata, served by Better Auth |
-| `/oauth/consent`, `/oauth/consents` | consent and connected apps, session only |
+| `/oauth/consent`, `/oauth/consents` | consent and connected apps, session only; with Admin, consent renders at `/admin/oauth/consent` and posts here |
 
 ### MCP
 

package/docs/handbook/releases/index.md

@@ -56,8 +56,13 @@ by hand.
   `emit-openapi`, `skills` and `mantle-harness` are removed.
 - **The Admin console** moves to `@aotter/mantle-ui/admin`, served at `/admin`
   by the preset through the service's `ASSETS` binding.
-- **Not yet in 0.2.0:** Mantle-rendered public pages, the MCP interaction App
-  tools, and deploying to Mantle Cloud.
+- **Mantle Cloud** uses its pinned Core contract and host protocol 4 through
+  the plugin's `mantle` Cloud workflow, requiring a verified source receipt
+  before save, with separate preview and publish
+  states. Its host contract decides the accepted version; offline readiness
+  is not a deployed service.
+- **Not yet in 0.2.0:** Mantle-rendered public pages and the MCP interaction
+  App tools.
 
 ## 0.1.4 — 2026-09-24
 

package/docs/handbook/start/overview.md

@@ -43,6 +43,7 @@ After that they are your files.
 | Look up a field | [Feature table](../reference/features.md), then the [Schema](../reference/schema.md), [View](../reference/view.md), [Procedure](../reference/procedure.md) and [Trigger](../reference/trigger.md) references |
 | Wire sign-in, media or deploy | [Authentication](../cloudflare/authentication.md), [Media uploads with R2](../cloudflare/media-r2.md), [Deploy and operate](../cloudflare/deploy-and-operate.md) |
 | Run on ChatGPT Sites | [Mantle on ChatGPT Sites](../cloudflare/chatgpt-sites.md) |
+| Save, preview and publish on Mantle Cloud | [Mantle Cloud](../cloudflare/deploy-and-operate.md#mantle-cloud), then the plugin's `mantle` Cloud workflow |
 | See whole services | [Examples](../examples/hub.md) and the runnable reference service |
 | Move a 0.1.x project | `docs/upgrade-0.1-to-0.2.md` in the installed package |
 
@@ -60,4 +61,3 @@ check the code.
   `createMantle`. The Bun preset has no scheduler.
 - **Site settings and media on PostgreSQL.** Only the `sqlite` dialect's
   storage takes `SiteDefaults`; see [Site defaults](../reference/site-config.md).
-- **Deploying to Mantle Cloud.** See [Deploy and operate](../cloudflare/deploy-and-operate.md).

package/docs/handbook/start/project-and-cli.md

@@ -59,6 +59,13 @@ and stops before writing anything, naming the install command for your
 package manager. It never installs anything. The host and dialect rows, and the
 staff MCP App, are checked only while the preset is still to be written.
 
+Use the versions in the installed Core's `package.json` `peerDependencies`,
+not registry latest, for optional auth and MCP packages. The diagnostic's
+install command includes those versions and incompatible installed peers are
+refused before generation. Keep `@aotter/mantle-ui` at Core's
+exact version. A package manager accepting an incompatible peer does not make
+it a supported combination; inspect peer warnings before starting the service.
+
 | Selection | Packages |
 |---|---|
 | always | `@aotter/mantle` |

package/docs/handbook/start/quickstart-worker.md

@@ -112,12 +112,13 @@ pnpm exec mantle generate
 ```
 
 With no flags the selection is identity `mantle` and every feature. The first
-run names the packages it needs, with the install command, and writes nothing
-until they are installed:
+run names the packages it needs, with versioned install commands from the
+installed Core's `peerDependencies`, and writes nothing until they are installed
+at compatible versions. Copy those commands rather than installing registry
+latest; `@aotter/mantle-ui` must match Core's exact version:
 
 ```sh
-pnpm add better-auth @better-auth/oauth-provider @better-auth/mcp @better-auth/cimd \
-  @modelcontextprotocol/server @modelcontextprotocol/ext-apps @aotter/mantle-ui
+# Run each versioned pnpm add command printed above first.
 pnpm exec mantle generate
 cp .dev.vars.example .dev.vars   # set ADMIN_EMAIL and a random BETTER_AUTH_SECRET
 pnpm exec wrangler dev --local

package/docs/skills/develop/SKILL.md

@@ -66,6 +66,11 @@ Choose in this order, stopping at the first that works:
   published-only into public Views. Never repeat them.
 - `scope` hides rows from staff too. When staff must see every row, store
   `auth.uid()` in a field and filter on it instead.
+- That filter protects the View, not generic Admin Schema reads. Root
+  `schema.readOnly: true` blocks generic writes only. If a contributor must
+  not read other users' rows, restrict the application-owned Admin surface
+  inside its existing `withCaller` boundary; see
+  `docs/handbook/guides/admin-ui.md` (Roles). Keep business transitions in SQL.
 
 ## Handlers
 
@@ -112,6 +117,11 @@ Then exercise what changed over HTTP: the REST View or Trigger, `/mcp`
 sign-in and the Admin route (`docs/handbook/cloudflare/authentication.md`).
 Check the stored rows, not only a 200. Before deploying a Schema change on
 SQLite, run `mantle generate --check --database <file>` to see the storage SQL.
+For a workflow, verify valid and invalid state transitions, ownership on every
+mounted surface (including generic Admin reads and writes), concurrent writes
+with one expected version, and persisted data and sessions after a restart.
+Exercise the actual UI when the product includes one; serving HTML alone does
+not verify its forms or operations.
 
 ## Rules
 

package/docs/skills/develop/mcp-app.md

@@ -19,7 +19,7 @@ decision. Build it case by case from these pieces.
 | `SchemaFields` and the primitives | `@aotter/mantle-ui/kit`, styled by `@aotter/mantle-ui/kit.css` | Admin's form controls |
 
 The App's own build installs what it imports: `@modelcontextprotocol/ext-apps`
-at the exact version `@aotter/mantle` depends on, React and the kit's peers
+at the exact version in the installed Core's `peerDependencies`, React and the kit's peers
 (`@aotter/mantle-ui`'s README lists them). `docs/handbook/concepts/mcp-and-agents.md`
 (MCP Apps) describes the catalog and the staff App these share.
 

package/docs/skills/provision/SKILL.md

@@ -23,7 +23,7 @@ Ask which target, unless the project already shows one.
 |---|---|---|
 | 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 | — | not available for 0.2 services yet; the plugin's `mantle` skill says when it is |
+| 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.
@@ -58,8 +58,9 @@ Confirm the active Cloudflare account with the user before creating anything.
      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 in chat, files or logs. Use a connector, or hidden
-   input:
+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

package/docs/skills/update/SKILL.md

@@ -27,6 +27,12 @@ Upgrade deliberately; never overwrite application-owned code.
    `@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:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.3",
   "description": "Mantle: a manifest-driven service core. Store authored as SQL, surfaces as Fetch functions, and the mantle CLI.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -85,33 +85,35 @@
     "libpg-query": "18.1.5",
     "pgsql-deparser": "18.3.8",
     "yaml": "^2.9.0",
-    "zod": "^4.5.4"
+    "zod": "^4.5.4",
+    "semver": "^7.8.5"
   },
   "devDependencies": {
-    "@better-auth/cimd": "1.7.2",
-    "@better-auth/core": "1.7.2",
-    "@better-auth/mcp": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
+    "@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/client": "2.1.0",
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/server": "2.1.0",
     "@types/node": "^26",
     "@types/pg": "8.23.1",
-    "better-auth": "1.7.2",
+    "better-auth": "1.7.7",
     "bun-types": "1.3.14",
     "pg": "8.23.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
-    "wrangler": "4.126.0"
+    "wrangler": "4.126.0",
+    "@types/semver": "^7.7.1"
   },
   "peerDependencies": {
-    "@better-auth/cimd": "1.7.2",
-    "@better-auth/mcp": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
+    "@better-auth/cimd": "1.7.7",
+    "@better-auth/mcp": "1.7.7",
+    "@better-auth/oauth-provider": "1.7.7",
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/server": "2.1.0",
-    "better-auth": "1.7.2"
+    "better-auth": "1.7.7"
   },
   "peerDependenciesMeta": {
     "@better-auth/cimd": {