@aotter/mantle 0.2.0 → 0.2.1-alpha.1

package/docs/handbook/start/agents.md

@@ -1,5 +1,5 @@
 ---
-description: The entry point `mantle help` prints first: choose a complete app or generation only, use examples as references, accept before done.
+description: "The entry point `mantle help` prints first: choose a complete app or generation only, use examples as references, accept before done."
 ---
 # Build with an agent
 
@@ -38,7 +38,11 @@ the app entry (`--entry`) never imports, it warns and names the topic that shows
 4. `pnpm generate`, implement every handler it lists, `pnpm check`, then `pnpm smoke`.
 5. Before reporting the app or a feature done, run [role-only acceptance](../guides/agent-workflow-acceptance.md)
    (`mantle help agent-workflow-acceptance`). Scripted smoke is not acceptance. `pnpm accept` starts the app and hands
-   each role to a fresh evaluator as a URL that carries that role's session.
+   each role to a fresh evaluator as a URL that carries that role's session. After a repair, the guide's
+   [re-verification rule](../guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches) decides which roles
+   and surfaces run again.
+6. Once acceptance converges, follow the [performance skill](../../skills/performance/SKILL.md): it decides which of
+   front end (Lighthouse), cold start and backend load apply, and holds each to a target before you report done.
 
 The first verified sign-in with `ADMIN_EMAIL` becomes the admin. Further administrators are added in Admin:
 **More → Administrators** invites by email, and **More → Members** grants Admin to an existing member.

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

@@ -59,6 +59,10 @@ Other handles may adapt to the same [structural driver contracts](../guides/adap
 `--auth` and `--site` modules). `mantle bundle`, which Wrangler runs for `wrangler dev` and every
 deploy, refuses to build when an input changed since, so stale generated code cannot run; regenerate and rebuild.
 Commit it with the other generated files.
+Under `wrangler dev` (Wrangler sets `WRANGLER_COMMAND=dev`) the refusal is one line per change instead of a failed
+build: `mantle bundle` removes `<outdir>/worker` and exits 0, so Wrangler reports the entry missing and holds requests.
+Writing `generated/` rebuilds. Other commands, other errors and a build by hand still fail with a nonzero exit.
+To see that form while `wrangler dev` runs, run `pnpm build` (or `mantle bundle` by hand).
 The bundle also prints notes, never errors, for SQL in the app's own code against Better Auth's tables (read users
 through `userOf(caller)` or `readIdentity(auth)` instead) and for Better Auth roles beyond `admin` and `user`.
 

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

@@ -3,7 +3,7 @@ description: Generate a small native D1 service and mount an application-owned W
 ---
 # Quickstart: a service on Workers
 
-Create an application outside the SDK checkout. Install stable `@aotter/mantle@0.2.0` exactly, TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2.0 contract.
+Create an application outside the SDK checkout. Install `@aotter/mantle@0.2.1-alpha.1` exactly (a prerelease; stable 0.2.0 has its own tagged handbook), TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2 contract.
 
 Save `manifests/tickets.yaml`:
 

package/docs/skills/develop/SKILL.md

@@ -25,14 +25,23 @@ visibility, OCC and restart persistence, not just a 200 response.
 Before reporting any new app or feature as done, follow the [independent
 acceptance guide](../../handbook/guides/agent-workflow-acceptance.md): write a
 private rubric, then give one fresh agent per role (`admin`, `user`) only its
-role and entry points, across every surface it uses. This is not limited to
+role and entry points, across every surface it uses. After a repair, re-run
+the scope its [re-verification
+rule](../../handbook/guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches)
+names and state which evidence you reused. This is not limited to
 MCP; if it was not run, say so explicitly and report the work as UNVERIFIED
-rather than done. For MCP workflows, also run the guide's design audit before implementing
-tools.
+rather than done. Hand off with the guide's [layered
+report](../../handbook/guides/agent-workflow-acceptance.md#report-done-ness-in-layers):
+an environment block is BLOCKED on its layer, never a product failure. For MCP workflows, also run the guide's design audit before implementing
+tools. Once acceptance converges, follow the [performance skill](../performance/SKILL.md) before reporting done.
 
 For native Admin, read the [current guide](../../handbook/guides/native-admin.md):
 the app builds Admin with `mantle bundle`. To customise pages, slots, hooks or
 MCP-host-safe components, follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin).
+Custom structured inputs and browser pages can use the optional
+`@aotter/mantle-admin/media` controlled `MediaPicker`: pass `readOnly` and an exact
+`uploadPurpose` (omit for selection only), apply `onSelect` to the local draft,
+and keep its import out of the MCP App entry. See the native Admin media example.
 Keep matching SDK, Admin and UI versions. Ref handlers retain caller-bound
 `ctx.store`; generic Admin reads use shared generated View templates and writes
 use native Procedure fragments.
@@ -80,6 +89,9 @@ Destructive changes and type changes need explicit data migration. Mantle drops
 
 Writes use Store `insert` / `update` / `delete`, `batch`, `transaction`, or declared Procedures. Never use raw SQL writes: they bypass scope, TTL, publishing and system-column rules. For reads beyond an id lookup or simple AND filter (joins, aggregates, OR, reuse), declare an internal View so the SQL is reviewable and typed. Store `findById`, `find` and `first` remain suitable for handler lookups and embedding in an existing app. Ref handlers receive `ctx.store` bound to the same Caller and transaction.
 
+For published-content replacement with preview and rollback, follow `mantle help revisions`: Core supplies OCC, Schema locks and atomic `store.batch`; the recipe binds the previewed revision ID/version and atomically seals it while switching the parent. Applications own retention and review policy; Core does not mandate a preparation step. Keep the previewed version on submit and require another preview after a revision conflict.
+Use its custom Native Admin preview/switch page: freeze the reviewed content and both row versions, then submit them through the authorized operation. Do not make editors copy version numbers or silently replace the reviewed snapshot after a refresh; conflicts require another explicit preview.
+
 For simple creates/partial updates, prefer Store-backed ref Procedures; keep
 Procedure `requires`/generated input checks, use only allowed patch fields and
 return safe business fields with the actual returned ID/version. Preserve

package/docs/skills/integrate/SKILL.md

@@ -22,7 +22,9 @@ data-preserving schema/auth/role migrations on a copy and retain rollback artifa
 Initial schema.sql is for an empty database, not an in-place upgrade. Requests run
 no DDL or storage checks; the only request-time write outside app operations is
 the configured OAuth resource row (see [OAuth](../../handbook/guides/oauth.md)).
-Verify cutover with actual app tests.
+Verify cutover with actual app tests. Before reporting user-facing work done, run
+[independent acceptance](../../handbook/guides/agent-workflow-acceptance.md), then the
+[performance skill](../performance/SKILL.md).
 
 Preserve the app router, verified identity and native resources. For selected
 Admin, follow the [native guide](../../handbook/guides/native-admin.md) for its

package/docs/skills/performance/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: performance
+description: Make an accepted Mantle 0.2 application fast — Lighthouse for app-authored pages, Worker cold start and first-load budgets, and backend reads and writes under realistic data volume with indexes and internal Views. Use right after independent acceptance converges, or when a user reports a slow page, first request or query.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/performance/SKILL.md
+  applies_to: mantle 0.2
+  projection: package
+---
+
+# Mantle Performance
+
+This skill sets direction: when to run, what to aim for, in what order and when
+to stop. It names no tools or commands. Choose the measurement and repair
+methods that fit the application, its host and the tools available to you; the
+targets and rules below are what stay fixed.
+
+## When to run
+
+- **After acceptance.** Once [independent acceptance](../../handbook/guides/agent-workflow-acceptance.md)
+  reports CONVERGED for a new application or a feature, continue here before
+  reporting done. Never optimize behavior that has not been accepted: after
+  BLOCKED or UNVERIFIED, report that and stop.
+- **On request.** When a user reports a slow page, slow first request or slow
+  query, run only the part that covers it, then check the others it could affect.
+
+## Choose what to run
+
+Decide from the manifests, the service entry and the changed files, not from
+guesses about future use. Run every part whose condition holds; record each
+skipped part with its reason.
+
+| Run | When the application or change has | Skip when |
+|---|---|---|
+| Front end | Pages a browser opens directly that the application authors: public pages, member pages, a custom frontend, Admin customisations | The only browser UI is SDK-built Admin, unchanged; MCP and REST alone have no page to measure |
+| Cold start | A deployed Worker or service entry: always for a new application; for a change, any added or moved import in the entry, its startup graph, a page's or an MCP App entry's first-load code | The change touched no import, entry, page or MCP App bundle |
+| Backend reads | Views, or Store reads in handlers, whose rows grow with data: lists, search, paging, joins, aggregates, totals, reports | Only id lookups and small, bounded configuration tables |
+| Backend writes | Procedures or Store writes that run often or concurrently: stock, counters, approvals, checkout, imports | Rare single-row administrative writes |
+
+A change in one part can move another: an added index slows writes, a shared
+stylesheet or entry import affects every page. Re-measure what a repair can reach.
+
+## Front end
+
+**Target:** the highest Lighthouse performance score the page allows, with a
+floor of 90 on mobile and 95 on desktop for every distinct page template, and
+no regression in accessibility, SEO or best practices.
+
+- Measure a production build, several runs on mobile and desktop, and report the
+  range. Separate what is real from what only the local environment causes
+  (no compression or HTTP/2, a cold cache) and say which is which.
+- Measure pages behind sign-in (member pages, Admin) through the role's session
+  URL that `pnpm accept` prints
+  ([hand each role](../../handbook/guides/agent-workflow-acceptance.md#hand-each-role-to-its-evaluator)),
+  never by weakening sign-in.
+- Find the actual bottleneck before changing anything; a trace beats a guess.
+- Repair in this order: what blocks the first paint (render-blocking styles and
+  font stylesheets, request chains, unused bytes), then main-thread work (heavy
+  scripts, animations, layout of off-screen content), then repeat visits
+  (content-hashed assets cached long, HTML revalidated).
+- When a bottleneck appears only because the measuring environment lacks
+  something (a GPU, a fast CPU), fix it only in a way that also helps real users
+  without it. Never detect the measuring tool to serve it a different page.
+- After every change, prove nothing else moved: the page looks the same, links,
+  forms and in-page anchors still work, and the
+  [public-page checks](../../handbook/guides/public-pages.md#check-before-you-report-done)
+  still pass without JavaScript.
+
+## Cold start
+
+**Target:** budgets that force code to load when it is needed, not before.
+
+- **Worker:** its startup graph imports only what every request needs; auth, MCP,
+  Admin and rarely used routes load on the request that uses them
+  ([size and startup](../../handbook/guides/size-and-startup.md)). On Workers the
+  startup graph is the entry chunk `mantle bundle` writes under `<outdir>/worker`
+  plus the chunks it imports statically ([outputs](../../handbook/start/project-and-cli.md#outputs));
+  anything behind a dynamic import is outside it. Report its size locally as the
+  *Worker entry static graph*; measure the host's startup time only on
+  a deployment the user has authorized, and keep it well under the host's limit
+  (aim below 50 ms on Cloudflare).
+- **Pages:** each page's *first-load JavaScript* is at most 100 KB, and only
+  what the first paint and first interaction need. Move the rest behind dynamic
+  imports, on use or when the browser is idle. An MCP App the application
+  authors holds its first-load JavaScript, the inline script text of its one
+  HTML file, to the same budget; it renders inside a host, so Lighthouse does
+  not measure it. Report the whole *MCP App HTML document* as its own number: it
+  also holds CSS and markup, so never compare it with this budget.
+- Use the one definition of each metric in
+  [size metrics](../../handbook/guides/size-and-startup.md#size-metrics), with
+  its measurement. Where the SDK's own checks measure differently, that page says how.
+- An overrun is a finding to repair by splitting, not a budget to raise. Raise a
+  budget only with the user's agreement and record why.
+
+## Backend
+
+**Target:** every read and write the application's surfaces actually make stays
+fast at a realistic volume, and no hot path scans a table that grows.
+
+- **Data:** seed an isolated local database, never a shared or production one,
+  with data shaped like real use: several owners and roles, every state, long
+  text where fields allow it, and more than one page of results everywhere. Size
+  the largest tables at 100,000 rows or 10 times the expected first-year volume,
+  whichever is larger. Seed with SQL straight into that database, setting the
+  native columns as [reserved entry columns](../../handbook/reference/schema.md#reserved-entry-columns)
+  describes: it is test data, not an application write.
+- **Load:** call every View and Procedure through the same callers and surfaces
+  the application uses, as each role. The app's local test harness already
+  starts it on a fresh database, signs each role in and calls routes and MCP
+  tools as that role ([local HTTP checks](../../handbook/guides/local-testing.md#what-smoke-covers)).
+  Record typical and slow-tail latency and
+  rows read, then run concurrent writers wherever contention matters. A business
+  rule that breaks under concurrency (oversell, double approval, lost update) is
+  a correctness defect, not a performance finding: fix it first.
+- **Aim:** hot reads stay in the tens of milliseconds locally at seeded volume,
+  and their cost does not grow with table size.
+- **Repair in this order:**
+  1. Read the native query plan of each hot path, using the SQL in its generated
+     query module under `generated/` against the seeded database; a full scan of a
+     growing table is a finding.
+  2. Add the index that serves it in the Schema's `indexes`
+     ([indexes](../../handbook/reference/schema.md#indexes-checks-and-search))
+     together with a native migration ([database changes](../develop/SKILL.md#database-changes)).
+     Index only what a measured query uses; every index costs writes. Paged Views
+     and [Schema locks](../../handbook/reference/schema.md#locks) are index-proven
+     already: generation refuses one no index serves.
+  3. Move complex reads (joins, aggregates, OR, reuse) into an
+     [internal View](../../handbook/guides/typed-queries.md#declare-an-internal-view),
+     page with keysets ([results and paging](../../handbook/reference/view.md#results-and-paging)),
+     and replace exact totals on hot paths ([search and totals](../../handbook/reference/view.md#search-and-totals)).
+  4. Re-measure reads and writes after each repair.
+
+## Rules
+
+- Speed never buys a lower standard: scope, authorization, OCC, atomicity,
+  accessibility, the public-page requirements and every explicit user
+  requirement stay intact. The application's writes still go through Store and
+  Procedures; only seed data for the isolated test database is inserted directly.
+- Do not lower a target, shrink the seeded data or drop a slow case to pass.
+  Report what is left instead.
+- Work locally. Deploying or measuring a deployment follows the
+  [provision skill](../provision/SKILL.md) and needs the user's authorization.
+- After any repair, rerun the [local HTTP checks](../../handbook/guides/local-testing.md).
+  A repair that changes what a user sees or can do is no longer only a
+  performance change: re-run acceptance for the scope the
+  [re-verification rule](../../handbook/guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches)
+  names. A changed View or Procedure widens it to every surface that reads or
+  writes that data, and so does a `uniqueIndexes` entry. A non-unique
+  `indexes` entry and its migration keep the business rules: run `pnpm check`,
+  the local HTTP checks and your focused regressions, not acceptance.
+- Report app-added cost and SDK-existing cost separately. Built-in Admin has a
+  recorded [baseline](../../handbook/guides/size-and-startup.md#native-admin-baselines)
+  per SDK version; while the installed version and Admin entry are unchanged,
+  reuse it instead of repeating that experiment each round. Built-in Admin's
+  page and MCP App both miss the first-load budget; that is SDK-existing cost,
+  not the application's. A target the SDK's cost misses is still PARTIAL, with
+  its owner named. Never relabel it PASS.
+- Do not patch vendor or SDK code, remove native Admin features or build a
+  general benchmark framework to meet a target.
+- Stop when every target is met, after three rounds, or when two rounds in a row
+  bring no measurable gain.
+
+## Report
+
+For each part: run or skipped (with the reason), the environment, before and
+after numbers as ranges, what changed and what is left. Close with one verdict
+beside the acceptance verdict: **PASS** (every target that applies is met),
+**PARTIAL** (improved, with the targets still missed and why) or **SKIPPED**
+(nothing applied).

package/docs/skills/update/SKILL.md

@@ -15,12 +15,16 @@ metadata:
 Read the installed SDK README, then follow the version-matched [project and CLI
 workflow](../../handbook/start/project-and-cli.md) before editing.
 
-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.
+For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md). Mantle
+ships no migration tool: plan the data move from
+[Moving data from 0.1.x](../../upgrade-0.1-to-0.2.md#moving-data-from-01x),
+verify each fact against the generated `schema.sql` and the 0.1.4 export, and
+have the plan reviewed. Give the 0.2 service a new database, rehearse the load
+on a copy, never boot 0.2 against a 0.1.x database, and keep exports out of the
+repository. The guide's appendix is historical; do not follow it. Between 0.2
+versions, apply reviewed migrations rehearsed on a copy.
 
-For the stable 0.2 line, pin every selected Mantle package to `0.2.0`; do not upgrade an existing application by following a moving dist-tag.
+For the stable 0.2 line, pin every selected Mantle package to `0.2.0`; to try the 0.2.1 prerelease, pin all of them to `0.2.1-alpha.1` and read its release notes. Do not upgrade an existing application by following a moving dist-tag.
 
 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

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

@@ -1,26 +1,141 @@
 # 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
+0.2.0 replaces 0.1.x's grammar, runtime and storage. There is no codemod, no
+migration tool and no in-place upgrade of a 0.1.x database: a coding agent
+rebuilds the project on 0.2.0 and plans a reviewed data move for it.
+
+1. **Rebuild the project on 0.2.0** with the current handbook: the
+   [0.2.0 release notes](handbook/releases/index.md#upgrading-to-020) and the
+   [native SDK migration](handbook/releases/index.md#native-sdk-migration-alpha7),
+   the [CLI and generated ownership](handbook/start/project-and-cli.md), the
+   [app shell](examples/app-shell/) and the [Schema](handbook/reference/schema.md),
+   [View](handbook/reference/view.md) and [Procedure](handbook/reference/procedure.md)
+   references. The application owns routing, Auth, native handles and database
+   migrations. Install the same exact version of `@aotter/mantle`,
+   `@aotter/mantle-ui` and, when selecting Admin, `@aotter/mantle-admin`.
+   Preserve every authorization, scope and OCC requirement.
+2. **Move the data** into a new 0.2 database, as
+   [Moving data from 0.1.x](#moving-data-from-01x) describes.
+
+The [appendix](#appendix-earlier-02-alpha-contract-historical) maps 0.1.x
+manifests to an earlier 0.2 alpha. Its runtime, CLI, handler and data
+instructions are out of date; use it only to recognise what a 0.1.x construct
+meant, never as instructions.
+
+## Moving data from 0.1.x
+
+These facts come from the 0.1.4 and 0.2.0 sources. Before relying on one,
+check it against the application's own generated `schema.sql` and its 0.1.4
+export; where they disagree, trust them and stop to ask. Write the plan down
+for human review before it touches production data.
+
+- **Rehearse on a copy.** Load a copy of the export into a scratch 0.2
+  database, check the result through the app (Views, Admin, sign-in), and only
+  then run the reviewed load once into the fresh production database, before
+  it takes traffic.
+- **Never boot 0.2 against a 0.1.x database.** Apply the generated `schema.sql`
+  (it includes the site tables when the site module is selected) to an empty
+  database, then load rows into it.
+- **Keep data files out of the repository.** Exports, dumps and copies hold
+  user emails and content: keep them outside the working tree or ignored, and
+  never commit them.
+
+### Writing entries: the Store or SQL
+
+- **Through the SDK.** The generated `store(db, caller)`, or `ctx.store` in a
+  `ref` handler, with a trusted caller such as `{ kind: "system", reason }`
+  ([authorization](handbook/concepts/authorization.md)). It accepts no value
+  for `id`, `version`, `created_at`, `updated_at`, `author_id`, `status`,
+  `published_at` or the scope column, for any caller: it sets them itself, so new IDs, versions,
+  timestamps and authors replace the old ones. Publishing goes through the
+  generated `<schema>.publish` Procedure, which sets `published_at` to now
+  ([lifecycle](handbook/concepts/lifecycle-and-locales.md)). With new IDs,
+  remap every `x-mantle-ref`, every `translates.on` key and any ID embedded
+  in JSON; `x-mantle-ref` is not a foreign key, so a missed one dangles
+  quietly.
+- **Through SQL**, to keep IDs, history and authors: `INSERT` the rows with
+  every native column set, as
+  [reserved entry columns](handbook/reference/schema.md#reserved-entry-columns)
+  lists. This bypasses row policy, so review it like a migration.
+
+### Entry columns on D1
+
+| 0.1.4 | 0.2.0 |
+|---|---|
+| `_mantle_id` (UUID text) | `id` (text, unique) |
+| `_mantle_version` (an OCC counter) | `version` |
+| `_mantle_created_at`, `_mantle_updated_at` (epoch **milliseconds**) | `created_at`, `updated_at` (epoch **microseconds**: multiply by 1000). Set `updated_at`: it defaults to `0`, which Admin shows as 1970 |
+| `_mantle_author_id` | `author_id`, the Better Auth `user.id` |
+| `_mantle_status` (on every table) | `status` (`draft`, `published`, `archived`) on publishing Schemas only |
+| none | `published_at` (publishing Schemas): 0.1.4 has no source; choose a value for each published row, `NULL` otherwise |
+| the `scope` field | the same column, text, not null |
+| `date-time` field, ISO text | integer microseconds since the epoch |
+| `date` field, text | integer days since 1970-01-01 |
+| object field (JSON text) | 0.1.4 had no geo type; if you remodel a position as a `format: geo` field, it is two columns, `<field>_lat` and `<field>_lng` |
+
+- 0.2 tables on D1 are `STRICT`: a value of the wrong type fails the insert
+  instead of being stored.
+- A `numeric(p,s)` field is an integer scaled by 10^s on D1: rescale a 0.1.4
+  REAL value before loading it.
+- Schema `checks` run as `BEFORE INSERT` and `BEFORE UPDATE` triggers, so
+  loaded rows are checked.
+- Full-text search and geo index tables are maintained by triggers: insert
+  only into the Schema tables.
+
+### Better Auth
+
+0.1.4 used Better Auth 1.7.2 with hand-written DDL; 0.2.0 uses 1.7.7, with the
+tables `mantle generate --auth src/auth.ts` adds to `schema.sql`
+([auth](handbook/cloudflare/authentication.md)).
+
+- The 0.2 caller subject is the Better Auth `user.id`. Keep user IDs, so that
+  `author_id` and owner scopes still name the right people.
+- Copy `user` and `account` with explicit column lists on both sides; both
+  versions store dates as ISO text and booleans as 0/1 on D1. 0.1.4's
+  `account` has an `issuer` column and `UNIQUE(issuer, accountId)` that the
+  0.2 table may not have; compare the two DDLs before copying.
+- 0.1.4 roles `owner`, `editor` and `contributor` have no 0.2 meaning. The
+  admin layer is Better Auth's admin plugin `adminRoles` (default
+  `["admin"]`) and `adminUserIds`
+  ([authorization](handbook/reference/authorization.md)); decide each mapping
+  deliberately.
+- A 0.1.4 `githubLogin` column must be declared in `user.additionalFields`
+  to keep it.
+- Leave sessions, verification rows and OAuth tokens behind; users sign in
+  again. Mantle re-creates its OAuth resource rows from configuration
+  ([OAuth](handbook/guides/oauth.md)). Check `jwks`, OAuth clients and
+  consents against Better Auth 1.7.7 and your secrets and URLs before copying
+  any.
+- The admin MCP endpoint moved from `/mcp/staff` to `/mcp/admin`; update MCP
+  client URLs.
+
+### Media
+
+- `media_assets` has the same columns in 0.2, and its `created_at` stays in
+  epoch **milliseconds**. Copy the rows as they are.
+- Each variant keeps its stored `storageKey` and `publicUrl`, so 0.1.x objects
+  in the same bucket keep working while their prefixes stay served
+  ([media](handbook/cloudflare/media-r2.md)).
+- Do not carry over `pending_media_uploads`; an upload expires after 15
+  minutes.
+- `site_config` keeps its `key`/`value` columns; compare its keys with the
+  generated `site-seed.sql` before copying.
+
+## Appendix: earlier 0.2 alpha contract (historical)
+
+> **Historical, do not follow.** This appendix describes an earlier 0.2
+> alpha: `createMantle`, `runtime.store`, host presets, boot-time convergence
+> and CLI flags that 0.2.0 does not have. The current handbook and
+> [Moving data from 0.1.x](#moving-data-from-01x) replace it. Where 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)
+> disagreed, the ADR won.
+
+### Rules
 
 - Work on a branch. Keep the 0.1.x project running until the 0.2.0 one passes
   its checks.
@@ -32,10 +147,10 @@ one project by hand with this guide. When it and
   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).
+  one. Move data as [Moving data from 0.1.x](#moving-data-from-01x) says.
 - `mantle generate --check` is the gate. Never hand-edit `.mantle/generated/`.
 
-## 1. Packages
+### 1. Packages
 
 | 0.1.x | 0.2.0 |
 |---|---|
@@ -46,7 +161,7 @@ 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`
+### 2. `mantle.config.json`
 
 0.1.4 had none; 0.1.5-alpha.1 wrote a `version: 1` one. Write version 2:
 
@@ -72,7 +187,7 @@ command; it never installs anything.
 - `host` and `dialect` are chosen on the first `mantle generate` (`--host`,
   `--dialect`); a rerun that asks for another is refused.
 
-## 3. Manifests
+### 3. Manifests
 
 Set `apiVersion: cms.mantle.aotter.net/v2` on every document; a v1 document
 is refused.
@@ -81,7 +196,7 @@ is refused.
 `created_at`, `updated_at`, `author_id`. (`ctx.store` JSON keeps the
 camelCase names.)
 
-### Schema
+#### Schema
 
 | 0.1.x | 0.2.0 |
 |---|---|
@@ -113,7 +228,7 @@ 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
+#### 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
@@ -134,14 +249,14 @@ Schema reference; do not repeat them.
 | 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
+#### 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 `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. `COALESCE` also means `null` cannot clear a field; give clearing its own flag input ([clear flag](handbook/guides/sql-patterns.md#change-only-the-fields-given-coalesce), [leave out, replace or clear](handbook/guides/native-admin.md#leave-out-replace-or-clear)) |
 | 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`) |
@@ -153,7 +268,7 @@ 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
+#### 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
@@ -164,7 +279,7 @@ in one `sql` apply together or not at all. `requires.auth` and
   `continue` now blocks the write), an after hook is best effort.
 - `http`, `mcp` and other `lifecycle` fields keep their shape.
 
-## 4. Handler code
+### 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.
@@ -184,7 +299,7 @@ The generated types list exactly the plan's refs.
 `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
+### 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`,
@@ -197,13 +312,10 @@ only in trusted host code.
 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.
+5. Data: this step described an alpha API that 0.2.0 does not have. Follow
+   [Moving data from 0.1.x](#moving-data-from-01x) instead.
 
-## 6. CLI
+### 6. CLI
 
 | 0.1.x | 0.2.0 |
 |---|---|
@@ -212,7 +324,7 @@ only in trusted host code.
 | `mantle generate --output`, `--namespace` | removed: output is always `.mantle/generated/` |
 | `mantle skills`, the `mantle-harness` bin | removed |
 
-## 7. Verify
+### 7. Verify
 
 1. `mantle generate` and `mantle generate --check` exit 0.
 2. The project typechecks against the generated `mantle.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0",
+  "version": "0.2.1-alpha.1",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -20,9 +20,9 @@
     "jsonc-parser": "3.3.1",
     "@pgsql/types": "18.0.0",
     "libpg-query": "18.1.5",
-    "pgsql-deparser": "18.3.8",
+    "pgsql-deparser": "18.3.10",
     "yaml": "^2.9.1",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "exports": {
     ".": "./dist/infrastructure/generate.js",
@@ -72,7 +72,7 @@
     "./target-hash": "./dist/domain/describe/target-hash.js"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/server": "2.3.1",
     "@better-auth/core": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",
     "better-auth": "1.7.7"
@@ -92,19 +92,19 @@
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "2.2.0",
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@better-auth/core": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",
     "@better-auth/test-utils": "1.7.7",
-    "@cloudflare/workers-types": "^5.20261008.1",
+    "@cloudflare/workers-types": "^5.20261027.1",
     "@types/node": "^26",
     "better-auth": "1.7.7",
     "bun-types": "1.4.2",
     "postgres": "3.4.9",
     "typescript": "^6.0.3",
-    "wrangler": "4.145.0",
-    "vitest": "^5.0.1"
+    "wrangler": "4.153.0",
+    "vitest": "^5.0.4"
   },
   "description": "Agent-native app SDK and backend compiler: YAML manifests to native SQL (SQLite, Cloudflare D1, PostgreSQL) and typed TypeScript; optional REST and MCP.",
   "keywords": [