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

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

@@ -1,10 +1,10 @@
 ---
 name: media-gc
-description: Audit and safely remove stale, uncommitted public media uploads from a Mantle Cloudflare R2 bucket. Use when a Mantle operator asks to inspect or clean orphan media objects left after create_media_upload without commit_media_upload.
+description: Audit and safely remove stale, uncommitted media uploads from a Mantle 0.2 Cloudflare R2 bucket. Use when an operator asks to inspect or clean objects left under uploads/ by an upload that was created but never committed.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/media-gc/SKILL.md
-  applies_to: mantle grammar v0.1
+  applies_to: mantle 0.2
   projection: package
   projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
 ---
@@ -16,26 +16,37 @@ objects approved by the user.
 
 ## Preflight
 
-1. Read the project's Wrangler config and Mantle config. Resolve the R2 bucket
-   binding, bucket name, and declared public media purpose names.
+1. Read `wrangler.jsonc` and `src/service.ts`. Resolve the R2 bucket that
+   `r2MediaStorage` uses and the media purpose names in the site defaults
+   passed to `d1Storage(db, { site })`.
 2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
    ask; never choose by name similarity.
 3. Use the Cloudflare OpenAPI search before execution to resolve the current
    R2 List Objects and Delete Objects endpoints. If the connected account lacks
    access, stop. Do not create, request, or store credentials.
-4. Stop when the project has no public R2 media binding or no declared purpose.
+4. Stop when the service passes no `r2MediaStorage` or declares no purpose.
+
+## How 0.2 lays out media
+
+`POST /admin/api/media/uploads` issues presigned PUT URLs that expire after 15
+minutes, for keys under `uploads/<purpose>/<group>/<role>.<ext>`. Commit
+copies each checked object to `<purpose>/<group>/<role>.<ext>` (with
+`committedAt` metadata) and deletes the upload key; a rejected group's upload
+keys are deleted. So an object still under `uploads/` long after its URL
+expired belongs to an upload that was never committed, and nothing can commit
+it any more. Objects outside `uploads/` are committed media: never candidates.
 
 ## Audit
 
 For each declared purpose, list up to 1,000 objects per page under the exact
-`<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
+`uploads/<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
 
 An object is a deletion candidate only when all conditions hold:
 
 - `last_modified` is more than 24 hours old;
 - `custom_metadata.committedAt` is absent or empty;
-- the key matches the exact Mantle layout
-  `<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|svg)`,
+- the key matches the exact upload layout
+  `uploads/<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|bin)`,
   where `<purpose>` is declared by this project and `<group>` contains only
   letters, digits, `_`, or `-`.
 
@@ -65,8 +76,8 @@ filenames, public URLs, signed URLs, or secrets.
 
 - Don't create a Worker, Cron Trigger, lifecycle rule, D1 table, or local script.
 - Don't use prefix deletion or empty-bucket operations.
-- Don't delete private-media buckets or objects outside declared purpose
-  prefixes.
+- Don't delete objects outside `uploads/<declared purpose>/`, and never
+  committed media.
 - Don't treat missing pagination pages, metadata, or permissions as an empty
   result.
 

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.