@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/skills/provision/SKILL.md

@@ -1,194 +1,100 @@
 ---
 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:
+# Provision a Mantle project
 
-```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`.
+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.
 
-## Self-hosted email OTP
+## Choose the target
 
-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.
+Ask which target, unless the project already shows one.
 
-## Self-hosted GitHub OAuth
+| 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 | — | not available for 0.2 services yet; the plugin's `mantle` skill says when it is |
+| Bun (host `bun`) | `.env` | self-hosted; installed `docs/handbook/start/project-and-cli.md` (Bun), not this skill |
 
-1. Ask the user to create a GitHub OAuth App:
+Self-hosting is always an option; never present a hosted target as required.
 
-- 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:
+## Local gate
 
 ```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
+pnpm install --frozen-lockfile
+pnpm exec mantle generate --check
+pnpm exec tsc --noEmit
+git status --short
 ```
 
-Set `BETTER_AUTH_SECRET` once and preserve it. Rotating it invalidates existing
-sessions.
-
-4. Commit and push only non-secret config, then redeploy:
+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.
+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 in chat, files or logs. Use a connector, or hidden
+   input:
 
 ```bash
-git add wrangler.toml AGENTS.md
-git commit -m "mantle: wire production auth"
-git push
-pnpm deploy
+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
 ```
 
-## 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.
+   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.
 
-Hosted clients use PKCE and have no client secret. Do not write secrets into
-`wrangler.toml`.
+Commit and push only non-secret changes.
 
-Verify that admin sign-in redirects to Mantle Hosted Auth and Staff MCP
-authenticates, then skip the self-hosted flow.
+## Verify the deployed service
 
-## 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`.
+- 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:
-
-- 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.
+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 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`.
+- 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.

package/docs/skills/update/SKILL.md

@@ -1,51 +1,50 @@
 ---
 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.
+Upgrade deliberately; never overwrite application-owned code.
 
-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:
+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.
+5. Regenerate and check:
 
 ```sh
 pnpm exec mantle generate
 pnpm exec mantle generate --check
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-pnpm exec mantle validate
+pnpm exec tsc --noEmit
 ```
 
-Read the refreshed `mantle-develop` skill and the upgraded package's embedded
-docs before continuing application edits.
+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.
 
-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.
+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.

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

@@ -0,0 +1,211 @@
+# Upgrading from 0.1.x to 0.2.0 (for AI agents)
+
+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.
+
+## 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`; Bun.SQL 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.staff` |
+| `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` | `ctx.caller.kind === "user" && ctx.caller.role !== null` |
+| `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.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. Staff MCP stays at `/mcp/staff`, behind an OAuth token with the `mcp`
+   scope and a staff role; MCP clients keep their URL.
+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.