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

package/docs/examples/procurement.md

@@ -33,6 +33,7 @@ spec:
   schema:
     type: object
     additionalProperties: false
+    readOnly: true
     required: [requestNumber, requestedBy, item, quantity, needBy, justification, requestStatus]
     properties:
       requestNumber: { type: string, maxLength: 40, pattern: "^REQ-[A-Z0-9-]+$" }
@@ -154,6 +155,15 @@ spec:
   could not see the queue. Scope is for rows only their owner may ever see.
   Here the member View filters on `requestedBy = auth.uid()` instead, and
   `requires: ctx.user` means an anonymous caller is 401 before the query runs.
+- **Generic Admin access is a separate entrance.** The View's SQL filter and
+  `requires` protect that View, not generic Schema entry routes. Root
+  `schema.readOnly: true` blocks generic Admin create, patch and delete, so
+  every write goes through the declared Procedures. It does not block reads:
+  Admin admits contributors by default, and this Schema is not scoped. If
+  only owner/editor reviewers may read everyone's requisitions, restrict the
+  Admin surface in the application; see [Roles](../handbook/guides/admin-ui.md#roles).
+  Keep that restriction inside the existing `withCaller` boundary. Members
+  and contributors use the owner-filtered public View instead.
 - **A Schema whose name is not a plain identifier is quoted in SQL**:
   `"purchase-requisitions"`.
 
@@ -204,7 +214,8 @@ staff surface.
 ## What this leaves out
 
 - **Approval chains.** One decision by one staff member. Sequential approvers
-  need a step field and a `before_update` hook that checks the transition.
+  need a step field and SQL conditions on the current step and caller. Use a
+  hook or guard only for a check SQL cannot express.
 - **Budgets.** A live budget check belongs in a `requires.guard` handler.
 - **Notifications.** See the `after_create` hook in
   [Intake with bot check and notification](./intake-hooks.md).

package/docs/examples/reference-service/package.json

@@ -8,14 +8,14 @@
     "check": "mantle generate && mantle generate --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.2",
-    "@aotter/mantle-ui": "0.2.0-alpha.2",
-    "@better-auth/cimd": "1.7.2",
-    "@better-auth/mcp": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
+    "@aotter/mantle": "0.2.0-alpha.4",
+    "@aotter/mantle-ui": "0.2.0-alpha.4",
+    "@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"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "5.20260904.1",

package/docs/examples/reference-service/smoke.mjs

@@ -113,10 +113,14 @@ try {
   // the console: @aotter/mantle-ui/admin served by Admin at /admin, its assets by name, any other path its client-side route
   const shell = await fetch(`${origin}/admin/c/items`);
   const html = await shell.text();
-  const script = /src="(\/admin\/assets\/[^"]+\.js)"/.exec(html)?.[1];
+  const script = /src="((?:\/admin\/|\.\/)assets\/[^"]+\.js)"/.exec(html)?.[1];
+  const base = /<base href="([^"]+)"/.exec(html)?.[1] ?? "/admin/";
   assert.equal(shell.headers.get("x-frame-options"), "DENY");
   assert.ok(script, html.slice(0, 300));
-  assert.equal((await fetch(`${origin}${script}`)).status, 200);
+  const scriptUrl = new URL(script, new URL(base, origin));
+  assert.equal(scriptUrl.origin, origin);
+  assert.ok(scriptUrl.pathname.startsWith("/admin/assets/"));
+  assert.equal((await fetch(scriptUrl)).status, 200);
   assert.equal((await fetch(`${origin}/admin/assets/missing.js`)).status, 404);
   // the editor's round trip: it reads the whole entry and writes it back, an unset optional field included as null
   const [tea] = (await call("GET", "/admin/api/entries?collection=items", { cookie: staff })).body.items;

package/docs/handbook/cloudflare/authentication.md

@@ -42,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
@@ -57,6 +105,17 @@ 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
@@ -75,7 +134,31 @@ const { url } = await res.json();
 location.assign(url ?? "/account");
 ```
 
-Dynamic client registration takes a client that names no `application_type`
+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

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,7 +50,7 @@ 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,
+`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
@@ -123,6 +123,18 @@ On the public surface, a member-facing App is the application's to build; the
 SDK attaches none. The `develop` skill's
 [MCP App recipe](../../skills/develop/mcp-app.md) lists the pieces.
 
+## Native metadata observations
+
+`createMcpSurface` optionally takes `onObservation(event)`. Registered tool dispatch emits `kind: "invocation"` with `phase: "attempt"` then `phase: "completion"`, sharing `invocationId` with the runtime's MCP cause. Metadata includes time, surface, MCP tool name and a frozen copy of the resolved Caller; completion adds monotonic `durationMs`, `outcome` (`succeeded`, `failed`, `denied`) and an optional diagnostic code. Runtime auth, guard or input-validation refusal is a dispatched invocation with a failed/denied completion; it does not assert that a business handler executed or committed. The Caller contract uses opaque subject/credential record IDs, never emails or raw tokens. Input, output and diagnostic messages are absent. A host must still allowlist what it exports.
+
+The surface's existing authorization gates emit `kind: "request-refused"` with time, surface and HTTP status. A refused batch emits one request refusal and no invocation observations. Unknown/client-hidden tools and protocol validation errors do not fabricate executed invocations. These are separate measurements: request rejections must not be added to executed-call totals.
+
+`withCaller` optionally takes `onRefusal(event)` for identity or session-origin rejection before a surface runs. It emits only time, status and `reason: "credential" | "origin"`; it cannot identify a tool in a body it has not parsed. A host registers both hooks to cover the two boundaries without resolving identity twice.
+
+Callbacks can return `void` or a delivery promise. Delivery promises are not awaited; throws/rejections are contained and never change a response. Synchronous listener work still runs inline: keep it short. The host owns request-scoped background scheduling, transport, failure reporting and retention. The simplest request binding is to construct `createMcpSurface` and `withCaller` inside the host's request handler, with callbacks closing over that request's background-task function; reuse the already-created runtime, not a new runtime/Auth. Surface construction traverses its plan's tool catalog. A host that reuses surfaces can instead use its existing request-local context facility, such as AsyncLocalStorage, to retrieve the current execution context. Never close over the first request's context or share its delivery promise with another request. With Streamable HTTP, tool execution and completion observations may happen after `fetch` returns its Response, while its body is consumed; keep the request-bound context available through that lifetime.
+
+Attempt/completion can arrive out of order, a completion may be absent, and capture is best-effort. `succeeded` describes native execution/serialization, not successful transport delivery afterward. `durationMs` uses the host's `performance.now()` clock; its precision and advancement depend on the host. This is observability, not a billing or transactional audit guarantee. Omitting both callbacks preserves current dispatch/auth behavior and adds no provider dependency or storage statement. These callbacks cover this native MCP surface, not Admin WebMCP or every runtime source. The two refusal hooks have different shapes because caller rejection occurs before a surface has identified a tool; the adopter may project them into its own request-rejection metadata.
+
 ## Further reading
 
 - [Reads: Views, REST and MCP](./views.md)

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/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.2",
+  "version": "0.2.0-alpha.4",
   "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": {