@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/skills/provision/SKILL.md

@@ -1,194 +1,44 @@
 ---
 name: provision
-description: Ship a Mantle project through its selected host, routing ChatGPT Sites to its integration guide and conventional Cloudflare Workers to production auth and provisioning.
+description: Ship a Mantle 0.2 project to production — Cloudflare Workers with D1, production sign-in and secrets, or ChatGPT Sites through its guide — and verify the deployed service.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/provision/SKILL.md
-  applies_to: mantle grammar v0.1
+  applies_to: mantle 0.2
   projection: package
-  projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
+  projectionReason: Creates remote resources and handles production secrets; opt-in only.
 ---
 
-# Provision a Mantle Project
-
-Local cold start deliberately stops before this skill. Provision only after the
-user asks to create remote resources or ship production. This flow is for
-consumer-owned Cloudflare Workers. New direct-authored apps do not need Landing
-artifacts (`.mantle/launch-state.json`, `.mantle/handoff.md`, or a hosted-auth
-allocation). Treat any Landing handoff as **legacy/optional**. For a ChatGPT
-Site, use the installed `docs/handbook/chatgpt-sites/index.md` integration guide and
-the "Publish with Sites" steps in `docs/examples/host-chatgpt-sites/README.md`:
-request D1 and R2 on the Site, set `PUBLIC_ORIGIN` and `OWNER_EMAIL` in Sites
-settings, review the migration, then save and deploy a Sites version. Do not
-run `wrangler deploy` or require R2 S3 credentials merely because Sites exposes
-an R2 binding.
-
-## Source of Truth
-
-1. Read the actual provider config (`wrangler.jsonc` or `wrangler.toml`),
-   application entry and git remotes. Read legacy `.mantle/launch-state.json`
-   and `.mantle/handoff.md` only when present; they are optional leftovers from
-   Landing and must not be created as prerequisites for a new app.
-2. Read installed `@aotter/mantle*` versions from `package.json`.
-3. Use matching embedded docs under `node_modules/@aotter/mantle/docs/`.
-4. Never infer provider authority from launch state. Confirm the active GitHub
-   and Cloudflare accounts before changing them.
-
-Run the local gate first:
-
-```bash
-pnpm install --frozen-lockfile
-pnpm validate
-pnpm typecheck
-git status --short
-```
-
-## Resume From Observed State
-
-Do not branch on how the project was created. Verify these facts and skip
-completed work:
-
-1. `git remote get-url origin` confirms the GitHub repo.
-2. An HTTPS `PUBLIC_ORIGIN` that responds confirms the Cloudflare deploy.
-3. `/admin/sign-in` returning `503 setup_incomplete` means auth is not bound.
-   Use the recorded auth intent only to choose hosted or self-hosted setup;
-   live behavior is authoritative.
-
-If there is no remote, confirm the target account, create a private repo,
-commit, and push `main`. If there is no live Worker, confirm the Cloudflare
-account, prefer an available connector, or use `pnpm exec wrangler login` with
-the user's agreement, then run `pnpm deploy`.
-
-Capture the live URL in `PUBLIC_ORIGIN` and `Public site:` in `AGENTS.md`, then
-commit and push non-secret changes. Reuse any repo or Worker already created.
-Do not recreate Landing artifacts for a new direct-authored app. Workers Builds
-is optional after a direct deploy.
-
-When the owner later adopts a custom domain, update `PUBLIC_ORIGIN` and the
-provider's OAuth callback together, then redeploy. Do not patch `site_config`
-directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
-
-## Choose Auth
-
-- **Self-hosted email OTP:** use the application's production transactional-email sender. Replace `ConsoleEmailSender`; never deploy it.
-- **Self-hosted GitHub OAuth — free fallback:** use when the application has no email provider. Configure the owner's per-site GitHub OAuth App and Worker secrets using the steps below.
-- **Mantle hosted auth — paid, legacy/optional:** use only when a **legacy
-  Landing handoff** already records a hosted allocation and client
-  configuration. New direct-authored apps do not get this from Core. Mantle
-  Platform operates the identity provider; do not ask the user for a per-site
-  GitHub OAuth App.
-
-Configure only the selected mode. Core deliberately rejects partial or mixed
-hosted/self-managed bindings with `503 setup_incomplete`.
-
-Do not claim that hosted auth can attach to an arbitrary local repo unless a
-legacy Landing handoff already supplies that configuration.
-
-For the exact boundary, read
-`node_modules/@aotter/mantle/docs/auth-hosting-model.md`.
-
-## Self-hosted email OTP
-
-Keep the application's custom `createAuth()` factory, replace
-`ConsoleEmailSender` with its production `EmailSender`, and retain
-`bootstrapOwner: { match: "email", value: <owner email> }`. Store sender
-credentials and `BETTER_AUTH_SECRET` as Worker secrets, put `PUBLIC_ORIGIN` in
-non-secret vars, deploy, then verify that the owner receives an OTP at
-`/admin/sign-in`. If there is no production email provider, use GitHub OAuth
-below instead of deploying console delivery.
-
-## Self-hosted GitHub OAuth
-
-1. Ask the user to create a GitHub OAuth App:
-
-- Homepage URL: `<worker-url>`
-- Authorization callback URL: `<worker-url>/api/auth/callback/github`
-- Device Flow: unchecked
-
-2. Put non-secret values in `wrangler.toml`:
-
-- `MANTLE_AUTH_MODE = "self-managed"`
-- `PUBLIC_ORIGIN`
-- `GITHUB_CLIENT_ID`
-- `ADMIN_GITHUB_LOGIN`
-- correct Worker `name`
-
-Remove `MANTLE_HOSTED_AUTH_ISSUER` and `MANTLE_HOSTED_AUTH_CLIENT_ID` if they
-were present for a hosted allocation.
-
-3. Keep the Client Secret out of chat. Prefer a Cloudflare connector for
-   secrets; otherwise use hidden shell input:
-
-```bash
-read -rsp "GitHub OAuth client secret: " MANTLE_GITHUB_CLIENT_SECRET && printf "\n"
-printf '%s' "$MANTLE_GITHUB_CLIENT_SECRET" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET
-openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET
-unset MANTLE_GITHUB_CLIENT_SECRET
-```
-
-Set `BETTER_AUTH_SECRET` once and preserve it. Rotating it invalidates existing
-sessions.
-
-4. Commit and push only non-secret config, then redeploy:
-
-```bash
-git add wrangler.toml AGENTS.md
-git commit -m "mantle: wire production auth"
-git push
-pnpm deploy
-```
-
-## Hosted Auth (legacy Landing)
-
-Skip this section unless a legacy Landing handoff is already present. New
-direct-authored apps use self-hosted email OTP or GitHub OAuth above.
-
-Follow that handoff and its client configuration. Hosted configuration remains
-in landing-managed Cloudflare Worker bindings. Verify:
-
-- `MANTLE_AUTH_MODE = "hosted"`;
-- `MANTLE_HOSTED_AUTH_ISSUER` is the HTTPS root issuer;
-- `MANTLE_HOSTED_AUTH_CLIENT_ID` is the same-origin `/clients/<id>` URL;
-- `PUBLIC_ORIGIN` and `ADMIN_GITHUB_LOGIN` are set;
-- `BETTER_AUTH_SECRET` exists as a Worker secret;
-- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are absent.
-
-Hosted clients use PKCE and have no client secret. Do not write secrets into
-`wrangler.toml`.
-
-Verify that admin sign-in redirects to Mantle Hosted Auth and Staff MCP
-authenticates, then skip the self-hosted flow.
-
-## Smoke Test
-
-- public home route;
-- `/admin/sign-in`;
-- selected admin sign-in path;
-- `/mcp/staff` with an agent client when available;
-- one type-specific core workflow.
-
-Media uploads are optional. Configure R2 only when the owner asks for
-staff-managed files; then read
-`node_modules/@aotter/mantle/docs/handbook/cloudflare/media-r2.md`.
-
-## Handoff
-
-Return:
-
-- public URL;
-- admin sign-in URL;
-- Staff MCP URL;
-- operator setup URL:
-  `https://mantle.tools/connect?site=<url-encoded-worker-url>`;
-- remote resources created or reused;
-- auth mode and any intentionally deferred setup.
-
-## Don't
-
-- Don't create remote resources before the user asks to ship.
-- Don't ask for a Cloudflare API token in the base flow.
-- Don't commit provider secrets.
-- Don't require R2 for first production.
-- Don't invent a second provision orchestrator.
-- Don't use `/admin/auth/github/callback`; the callback is
-  `/api/auth/callback/github`.
+# Provision a Mantle project
+
+## Workflow
+
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
+
+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.
+Keep the Workers [public-fetch flags](../../handbook/cloudflare/deploy-and-operate.md#public-fetch-routing),
+including environment overrides; verify deployed MCP with a real OAuth bearer
+(`initialize` and `tools/list`), not only a browser session cookie.
+For MCP Apps, also follow [deployed host acceptance](../../handbook/guides/mcp-apps.md#verify-a-deployed-app-in-chatgpt):
+compare the current resource URI and visibly verify a newly invoked render tool.
+Archive deployed Admin pages using the guide's `previous` recipe and carry them
+through clean builds. Test the same old conversation after changing the UI build,
+without reconnecting, refreshing host tools or clearing caches. A deliberate tool
+contract change has its own migration/host rediscovery step. OAuth renewal, `tools/call` success and a
+local official-host replay do not establish that the deployed App rendered.
+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.
+
+For ChatGPT Sites, follow [Mantle on ChatGPT Sites](../../handbook/cloudflare/chatgpt-sites.md).
+
+The app builds Admin with `mantle bundle`; serve it as [Native
+Admin](../../handbook/guides/native-admin.md) describes. 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

@@ -1,51 +1,36 @@
 ---
 name: update
-description: Review and upgrade Mantle SDK dependencies and project-local skills while preserving application source, provider identities and plugin lockfiles.
+description: Upgrade a Mantle project's @aotter/mantle packages to a new exact version, including the move from 0.1.x to 0.2, without overwriting application-owned code.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/update/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: project
+  applies_to: mantle 0.2
+  projection: package
 ---
 
 # Mantle Update
 
-Upgrade SDK dependencies deliberately; never overwrite application-owned code.
-The old Starter bundle comparison command `mantle update` is removed. This
-skill remains the version-matched upgrade workflow, not a replacement CLI.
+## Workflow
 
-1. Inspect git status, package.json, lockfile, actual project scripts and
-   installed versions. Preserve unrelated local changes. Read plugin locks
-   and legacy `.mantle` metadata if present; they are context, not required.
-2. Select an explicit target release and read that version's GitHub release
-   notes. Installed docs live under `node_modules/@aotter/mantle/docs/`;
-   `handbook/releases/index.md` is a stable-release index, so a prerelease
-   need not appear there. Do not use the old package's docs as the new API contract.
-   Do not resolve new Starter refs or compare the project to a baseline
-   template.
-3. Update only selected `@aotter/mantle*` dependencies to the same exact target
-   version, preserving dependency sections. Use the package manager to update
-   the lockfile; inspect the dependency diff and required peer changes.
-4. Remove scripts that invoke retired create/bundle-update commands. Keep all
-   application manifests, handlers, routes, theme, Worker/D1/KV names, origins,
-   provider bindings, secrets, and legacy metadata. Apply API migration edits
-   individually; do not copy the reference consumer over a real application.
-5. Use the upgraded package to regenerate machine-owned bindings and project
-   its skills, then run the application's validation, types and tests:
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
-```sh
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-pnpm exec mantle validate
-```
+For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md): give the
+0.2 service a new database and move data by export and import; never boot 0.2
+against a 0.1.x database. Between 0.2 versions, apply reviewed migrations
+rehearsed on a copy.
 
-Read the refreshed `mantle-develop` skill and the upgraded package's embedded
-docs before continuing application edits.
+Pin exact target SDK/peer versions and read its release notes and Admin build
+instructions. Core-to-native replaces app imports/wiring; it is not
+a package-only update. For 0.2-to-0.2 updates, 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.
 
-Start the local application and test its actual routes, including configured
-auth behavior. Review the final source/lockfile/generated diff; unexpected
-provider or user-source changes block completion. Provider credentials must
-never enter git or logs. Report exact old/new versions, checks, and remaining
-migration work. A dependency update does not authorize a production deploy.
+Follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin)
+for the current application-built Admin; 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

@@ -0,0 +1,227 @@
+# 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](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0032-store-centric-core-and-service-contract.md),
+[ADR-0033](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0033-storage-converges-to-the-plan.md),
+[ADR-0034](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0034-store-is-authored-as-sql.md),
+[ADR-0035](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0035-sql-dialects.md),
+[ADR-0036](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0036-host-and-dialect.md) or
+[ADR-0038](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
+
+## Rules
+
+- Work on a branch. Keep the 0.1.x project running until the 0.2.0 one passes
+  its checks.
+- Move meaning, not text. If a manifest does something no row below covers,
+  stop and ask. Vercel projects have no 0.2.0 preset: stop and ask. A Bun
+  project moves to `host: bun` (section 2).
+- Never loosen access. Every 0.1.x `requires`, guard, `scope` and
+  `x-mantle-bind` must come out at least as strict. `x-mantle-bind` is
+  refused in 0.2.0 and stamps nothing, so each one becomes `scope` or an
+  explicit value in the write (section 3).
+- Give the 0.2.0 service a new database; never boot it against the 0.1.x
+  one. Move data by export and import (section 5).
+- `mantle generate --check` is the gate. Never hand-edit `.mantle/generated/`.
+
+## 1. Packages
+
+| 0.1.x | 0.2.0 |
+|---|---|
+| `@aotter/mantle` and `@aotter/mantle-spec`, `-runtime`, `-cloudflare`, `-auth`, `-admin`, `-web`, `-bun`, `-vercel`, `-indexeddb` | `@aotter/mantle` (subpaths `/spec`, `/d1`, `/postgres`, `/cloudflare`, `/bun`, `/auth`, `/admin`, `/mcp`, `/web`, `/testing`) |
+| `@aotter/mantle-admin-ui` | `@aotter/mantle-ui` at the same version as `@aotter/mantle`: the preset serves the console at `/admin` from its `dist/admin` files; nothing to import. Its `/kit` re-export is gone: import `@aotter/mantle-ui/kit` |
+
+Remove every old package and install `@aotter/mantle` at the exact target
+version. `mantle generate` names any other package it needs, with the install
+command; it never installs anything.
+
+## 2. `mantle.config.json`
+
+0.1.4 had none; 0.1.5-alpha.1 wrote a `version: 1` one. Write version 2:
+
+```json
+{ "version": 2, "identity": "mantle", "features": ["mcp", "admin", "web"] }
+```
+
+- `version: 1` is refused.
+- `host` is `cloudflare` (the default, left out), `bun` or `none`; `none`
+  writes the plan and types only, for a platform with no preset. `host: bun`
+  refuses an enabled schedule Trigger: Bun has no cron dispatcher in the
+  preset.
+- `identity`: `mantle` if the project used Mantle auth (Better Auth sign-in,
+  Admin users, OAuth for MCP), `custom` if it resolved callers itself, `none`
+  if it had no signed-in callers. `admin` needs an identity.
+- `features` is a subset of `mcp`, `admin`, `web`, in that order. The 0.1.x
+  features `spec`, `runtime` and `api` are dropped: REST is always mounted.
+- `dialect` is `sqlite` (alias `d1`, the default, left out) or `postgres`
+  (PostgreSQL through Hyperdrive on `cloudflare`; node-postgres on `bun`, where it
+  is the default). A 0.1.x project was SQLite: keep `sqlite` (with
+  `--host bun`, pass `--dialect sqlite`) unless the data also moves to
+  PostgreSQL.
+- `host` and `dialect` are chosen on the first `mantle generate` (`--host`,
+  `--dialect`); a rerun that asks for another is refused.
+
+## 3. Manifests
+
+Set `apiVersion: cms.mantle.aotter.net/v2` on every document; a v1 document
+is refused.
+
+**Native columns are snake_case in SQL**: `id`, `status`, `version`,
+`created_at`, `updated_at`, `author_id`. (`ctx.store` JSON keeps the
+camelCase names.)
+
+### Schema
+
+| 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 |
+| `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.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 |
+
+`checks` (boolean SQL over the row's own columns) is new and optional.
+
+A JSON Schema `pattern` (in a Schema, a View input or a Procedure input/output)
+is now refused with `INVALID_PATTERN` when it could backtrack without bound on
+a caller's string:
+
+- a repeated group whose body repeats or alternates, such as the 0.1.x slug
+  `^[a-z0-9]+(-[a-z0-9]+)*$` or `(a|b)+`, and any backreference;
+- a pattern whose backtracking, branches × maxLength^e, could exceed
+  10,000,000 — e is its variable quantifiers (`*`, `+`, `?`, `{m,}`,
+  `{m,n}`) plus 1 unless it starts with `^`, branches the product of its
+  alternations' alternatives — or one with e > 0 whose string has no
+  `maxLength`: `^[a-z0-9-]+$` (e = 1) allows any maxLength up to
+  10,000,000, an email `^[^@]+@[^@]+$` (e = 2) up to 3162, the unanchored
+  `[^@]+@` (e = 2) also 3162, `^a*a*a*…$` almost none.
+
+Rewrite a slug as `{ type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }`,
+which also accepts leading, trailing and doubled hyphens. On a Schema field
+that must not have them, add a `checks` entry:
+`"slug NOT LIKE '-%' AND slug NOT LIKE '%-' AND slug NOT LIKE '%--%'"`.
+
+### View
+
+A View is one SQL `SELECT` in `spec.sql`, with `input` for its parameters.
+The SQL is PostgreSQL syntax: it names declared Schemas (never
+schema-qualified), `input.<name>`, `auth.uid()`, `auth.role()`, `now()` and
+`mantle.*` functions. The runtime adds scope, TTL and published-only to every
+Schema reference; do not repeat them.
+
+| 0.1.x | 0.2.0 |
+|---|---|
+| `from: posts`, `fields: [id, title]` | `SELECT id, title FROM posts` |
+| `filter: { eq: { field: status, value: published } }`, with `and` / `or` | `WHERE status = 'published'`, with `AND` / `OR` |
+| `value: { "$ctx.user": id }` | `auth.uid()`, or `scope` on the Schema |
+| `params` and `{ "$param": q }` | `input: { type: object, properties: { q: … } }` and `input.q` |
+| `orderBy: [{ field: createdAt, direction: desc }]` | `ORDER BY created_at DESC` |
+| `limit: 20` | `LIMIT 20` (a `LIMIT` needs an `ORDER BY`) |
+| `select:` (`columns`, `where`, `$input.x`, `$ctx.user.id`, `$now`) | the same query as SQL: `input.x`, `auth.uid()`, `now()` |
+| `sql:` (SQLite, `:name` parameters) | the same `sql:`, `:name` → `input.name`, rewritten to PostgreSQL syntax where it differs |
+| free-text search over `searchableFields` | `WHERE mantle.search(p, input.q) ORDER BY mantle.search_rank(p)`; an unqualified `search` is refused |
+| `page` / `show` on the wire | `limit` / `cursor`, `nextCursor` in the response |
+
+### Procedure
+
+0.1.x builtin ops are `create`, `update`, `upsert`, `delete` and `archive`.
+
+| 0.1.x | 0.2.0 |
+|---|---|
+| builtin `create` | `handler: { sql: "INSERT INTO s (a, b) VALUES (input.a, input.b) RETURNING id" }` (on a `publishing` Schema the row starts as a draft, as before) |
+| builtin `update` (always version-checked, merges over the stored row) | `UPDATE s SET a = COALESCE(input.a, a), … WHERE id = input.id AND version = input.expectedVersion`. Keep both: without the version the lock is lost; without `COALESCE` an omitted optional field is cleared |
+| builtin `upsert` with `match` | `INSERT … ON CONFLICT (<match columns>) DO UPDATE SET x = EXCLUDED.x`; the conflict columns are a unique index; on a scoped Schema the scope field may be named or left out, Store adds it |
+| builtin `delete` | `DELETE FROM s WHERE id = input.id AND version = input.expectedVersion` |
+| builtin `archive` | a `ref` handler: `ctx.store.write([{ update: "s", set: { status: "archived" }, where: { id }, lock: expectedVersion }])` (SQL cannot set `status`) |
+| `handler: { kind: ref, ref: fn }` | `handler: { ref: fn }`; the function's signature changes (section 4) |
+| `target: { schema, id, version }` | optional: inferred from `WHERE id = input.… AND version = input.…` |
+
+A write never sets the scope field, `version`, `status`, `author_id` or the
+timestamps. On a scoped Schema an `INSERT` names no `id`. Several statements
+in one `sql` apply together or not at all. `requires.auth` and
+`requires.guard` are unchanged.
+
+### Trigger
+
+- `schedule` cron is POSIX: weekday 0 = Sunday. 0.1.x used Cloudflare's
+  numbering (1 = Sunday), so subtract 1 from every weekday number, in ranges
+  and lists too (`1` → `0`, `2-6` → `1-5`, `7` → `6`); `*` and `*/n` stay.
+  On host `cloudflare`, a cron that sets both a day of month and a weekday
+  is refused.
+- `lifecycle` `errorPolicy` is removed: a before hook fails closed (a 0.1.x
+  `continue` now blocks the write), an after hook is best effort.
+- `http`, `mcp` and other `lifecycle` fields keep their shape.
+
+## 4. Handler code
+
+A `ref` handler is `(input, ctx) => output` in the service's `handlers` map.
+The generated types list exactly the plan's refs.
+
+| 0.1.x | 0.2.0 |
+|---|---|
+| `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` | `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.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) |
+
+`ctx.store` is scoped to the caller. `runtime.store` is not scoped; use it
+only in trusted host code.
+
+## 5. The Worker and the data
+
+1. Move the old `src/`, `wrangler.jsonc` (or `.toml`) and `tsconfig.json`
+   aside. `mantle generate` writes the preset (`src/*.ts`, `tsconfig.json`,
+   and `wrangler.jsonc` on `cloudflare` or `.env.example` on `bun`) only
+   where no such file exists, and only while `src/service.ts` is missing.
+2. Run `mantle generate`, then move custom routes, bindings and env from the
+   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. 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:
+   publish with a second update that sets `status`, and accept new
+   timestamps and author.
+
+## 6. CLI
+
+| 0.1.x | 0.2.0 |
+|---|---|
+| `mantle validate`, `mantle emit-openapi` | `mantle generate --check` (fails if anything is stale; `--database <file>` also prints the storage SQL) |
+| `mantle generate --host …` (0.1.5-alpha.1) | `mantle generate --host cloudflare\|bun\|none` on the first run only |
+| `mantle generate --output`, `--namespace` | removed: output is always `.mantle/generated/` |
+| `mantle skills`, the `mantle-harness` bin | removed |
+
+## 7. Verify
+
+1. `mantle generate` and `mantle generate --check` exit 0.
+2. The project typechecks against the generated `mantle.ts`.
+3. Each 0.1.x View and Procedure returns the same rows for the same caller,
+   including a caller who must see nothing (scope) and an anonymous request.
+4. A write cannot set an owner, author or timestamp field from its input.
+5. Every schedule fires on the intended weekday.
+6. `wrangler dev` (or `bun src/index.ts`) starts, sign-in works if
+   `identity` is `mantle`, and Admin, MCP and REST answer on their paths.
+
+Report what changed per manifest, every place where access got stricter, and
+anything you could not map.