@aotter/mantle 0.2.1-alpha.4 → 0.2.1

package/docs/examples/README.md

@@ -39,5 +39,5 @@ shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchas
 
 Every example uses two roles: `admin` (the admin layer) and `user`.
 
-[Reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.4/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
+[Reference service](https://github.com/aotter/mantle/tree/v0.2.1/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
 Projects on 0.1.x move with [the upgrade guide](../handbook/releases/upgrade-0.1-to-0.2.md).

package/docs/examples/app-shell/README.md

@@ -16,8 +16,8 @@ pnpm types && pnpm check       # each builds once (see Which steps build)
 cp .dev.vars.example .dev.vars
 pnpm db:init                   # optional seed.sql for static reference data, then pnpm db:seed (see Seed data)
 pnpm dev                       # builds, rebuilds on change; one-time codes print to this log
-pnpm smoke                     # builds; your smoke.mjs on smoke-kit.mjs (see Files you edit)
-pnpm accept                    # builds; hands each role to a fresh evaluator (see Independent acceptance)
+pnpm smoke                     # builds; runs smoke.mjs, which you write on smoke-kit.mjs (init does not create it)
+pnpm accept                    # builds; prints a signed-in URL per role for fresh evaluators (see Independent acceptance)
 pnpm test                      # Admin MCP App check of the last build: needs Chrome (npx playwright-core install chromium, or MANTLE_TEST_CHROMIUM=<executable>)
 ```
 

package/docs/examples/app-shell/package.json

@@ -15,8 +15,8 @@
     "accept": "node accept.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.1-alpha.4",
-    "@aotter/mantle-ui": "0.2.1-alpha.4",
+    "@aotter/mantle": "0.2.1",
+    "@aotter/mantle-ui": "0.2.1",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/core": "1.7.7",
     "@better-auth/mcp": "1.7.7",
@@ -25,7 +25,7 @@
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/server": "2.3.1",
     "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.1-alpha.4",
+    "@aotter/mantle-admin": "0.2.1",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -21,7 +21,7 @@ The driver layer is open: handles are structural contracts, not a registration A
 
 Users may supply anything that executes the emitted SQL, including WASM SQLite persisted to IndexedDB, at their own risk. Mantle promises behavior only on supported drivers: bun:sqlite, D1, Bun.SQL and postgres.js. A structural match alone does not prove transaction, result or error semantics.
 
-The dialect layer is closed in 0.2.0: exactly `postgres` and `sqlite`, selected by the generation target. SQL is rendered at generation time. A third engine requires forking the compiler and Store runtime; it is not a dialect plugin.
+The dialect layer is closed in 0.2: exactly `postgres` and `sqlite`, selected by the generation target. SQL is rendered at generation time. A third engine requires forking the compiler and Store runtime; it is not a dialect plugin.
 
 ## Store and queries
 

package/docs/handbook/examples/hub.md

@@ -2,4 +2,4 @@
 
 Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.4/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.1/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/adapter-guide.md

@@ -1,6 +1,6 @@
 # Another host or database handle
 
-Mantle has an open driver boundary and exactly two closed dialects in 0.2.0, postgres and sqlite. Choose the generation target whose emitted SQL and handle calls match your host. The app owns its router, resources, lifetime and scheduler.
+Mantle has an open driver boundary and exactly two closed dialects in 0.2, postgres and sqlite. Choose the generation target whose emitted SQL and handle calls match your host. The app owns its router, resources, lifetime and scheduler.
 
 PostgreSQL's `Postgres` in `kernel/contracts.ts` needs `unsafe(text, values)` and `begin(options, fn)`. Bun.SQL and postgres.js fit without wrappers. [The node-postgres example](postgres-adapters.md) shows the transaction and result-count contract. SQLite handle contracts are exported by `@aotter/mantle/driver/d1` and `/driver/bun-sqlite`: D1 prepare/bind/all/batch, or SQLite query/exec/transaction. Reads may need only the narrower reader shape.
 

package/docs/handbook/guides/native-admin.md

@@ -614,7 +614,7 @@ key's path. The `UI_EXTENSION_*` diagnostics no longer exist.
 
 The compiler derives display/filter metadata from Schema `uiSchema`, searchable fields from `searchableFields`, and sortable fields from indexes plus required/non-null fields and selected system columns. It emits per-collection quoted fragments, row policies and bind recipes; Admin uses one shared `nativeEntryPage` implementation, not Store `find`, `search` or `count` for these lists.
 
-Requests select only generated fields and append only supplied predicates. Absent filters are omitted, rather than expressed as `(? IS NULL OR …)`. Sorts and scalar values are checked before the route acquires its DB handle. In 0.2.0 there is no generated Cartesian set of filter variants or variant cap: runtime SQL shapes depend on selected filters, bounded IN lists, search, cursor and order. Only sortable fields are checked for indexes; there is no per-filter-combination index proof. Inspect EXPLAIN for the actual workload.
+Requests select only generated fields and append only supplied predicates. Absent filters are omitted, rather than expressed as `(? IS NULL OR …)`. Sorts and scalar values are checked before the route acquires its DB handle. In 0.2 there is no generated Cartesian set of filter variants or variant cap: runtime SQL shapes depend on selected filters, bounded IN lists, search, cursor and order. Only sortable fields are checked for indexes; there is no per-filter-combination index proof. Inspect EXPLAIN for the actual workload.
 
 Store keeps `find({ search })`, `first({ search })` and `count(where?)`. See [Store search and count costs](typed-queries.md#store-reads-and-writes): Admin shares the dialect search, and a View does not make PostgreSQL ILIKE faster.
 

package/docs/handbook/guides/size-and-startup.md

@@ -23,7 +23,7 @@ report it.
 |---|---|---|
 | First-load JavaScript | Every script a page's HTML loads: `<script src>` files and inline `<script>` text, classic or `type="module"`, plus every file they import statically, recursively. A dynamic `import()` is not followed. CSS, fonts, images and scripts from another origin do not count. | gzip per file |
 | MCP App HTML document | The whole built App document as served: its inline JavaScript, CSS and markup in one file. | raw bytes and gzip of the file |
-| Worker entry static graph | The Worker entry (Wrangler's `main`, such as `dist/worker/worker.js`) plus every chunk it imports statically, recursively. A dynamic `import()` is not followed. | gzip per file; raw bytes beside it |
+| Worker entry static graph | The Worker entry (Wrangler's `main`, `dist/worker/index.js` in an app from `mantle init`) plus every chunk it imports statically, recursively. A dynamic `import()` is not followed. | gzip per file; raw bytes beside it |
 
 The 100 KB budget in the [performance pass](performance.md) is first-load JavaScript. It applies to
 an MCP App too: `mantle bundle` builds the App as one HTML file with its
@@ -91,7 +91,7 @@ node first-load.mjs dist/client/admin/mcp-app.html
 Worker entry static graph: pass Wrangler's `main`.
 
 ```sh
-node first-load.mjs dist/worker/worker.js
+node first-load.mjs dist/worker/index.js
 ```
 
 MCP App HTML document:
@@ -128,7 +128,7 @@ dependencies, so they hold only for the version and commit named.
 
 | SDK | Source | Admin page first-load JavaScript | MCP App first-load JavaScript | MCP App HTML document |
 |---|---|---|---|---|
-| 0.2.1 | `develop` at `6dafb812`, before the release | 212,102 B gzip in 5 files (211,338 B without `theme.js`) | 193,535 B gzip, inline | 694,170 B raw / 200,457 B gzip |
+| 0.2.1 | `develop` at `1294c672` | 195,827 B gzip in 13 files (195,069 B without `theme.js`) | 167,516 B gzip, inline | 612,324 B raw / 174,501 B gzip |
 
 Neither the built-in Admin page nor its MCP App meets the 100 KB first-load
 budget. Both misses are SDK cost, not your application's: report them as

package/docs/handbook/guides/sql-patterns.md

@@ -4,7 +4,7 @@ description: Eight SQL patterns most apps need, each a complete manifest that co
 # SQL patterns
 
 Each section is a business need, the manifest that meets it, and what the database refuses. Every block here is
-generated by the docs check, and `packages/mantle/tests/sql-patterns.test.ts` runs the same manifest on bun:sqlite,
+generated by the docs check, and the SDK's tests run the same manifest on bun:sqlite,
 local D1 and PostgreSQL through the generated REST boundary. The SQL is the SQLite and D1 spelling; where PostgreSQL
 differs, the section says so. What each dialect accepts is listed in [the SQL reference](../reference/sql.md).
 

package/docs/handbook/reference/features.md

@@ -1,6 +1,6 @@
 # Supported declarations
 
-The native 0.2.0 SDK compiles the closed v2 grammar for four targets. Generation diagnostics, rather than historical APIs or release plans, define the checked-out implementation. Existing integrations require explicit app wiring and data migration; initial schema.sql is for an empty database.
+The native 0.2 SDK compiles the closed v2 grammar for four targets. Generation diagnostics, rather than historical APIs or release plans, define the checked-out implementation. Existing integrations require explicit app wiring and data migration; initial schema.sql is for an empty database.
 
 ## Supported
 

package/docs/handbook/reference/sql.md

@@ -19,7 +19,7 @@ worked examples see [SQL patterns](../guides/sql-patterns.md).
 | Predicates | `=`, `<>`, `!=`, `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT`, `IS [NOT] NULL`, `IS [NOT] DISTINCT FROM`, `[NOT] BETWEEN`, `IN (list)`, `IN (subquery)`, `LIKE`, `[NOT] EXISTS (subquery)` |
 | Expressions | `+ - * / %`, `\|\|`, `->>` (JSON field), `CASE`, `COALESCE`, `NULLIF`, scalar subqueries, `CAST(… AS text \| int4 \| int8 \| float8 \| bool \| timestamptz \| date \| numeric \| interval)` |
 | Aggregates | `count`, `sum`, `min`, `max`, `avg` |
-| Windows | `row_number()`, `rank()`, `sum()`, `count()` with `OVER (PARTITION BY … ORDER BY …)` and the default frame |
+| Windows (Views only) | `row_number()`, `rank()`, `sum()`, `count()` with `OVER (PARTITION BY … ORDER BY …)` and the default frame. A Procedure refuses them; rank there with a correlated `count(*)` subquery |
 | Scalar functions | `lower`, `upper`, `length`, `abs`, `round`, `substr`, `replace`, `trim`, `ltrim`, `rtrim`, `instr` |
 | Time | `now()`, `date_trunc('hour' \| 'day' \| 'week' \| 'month' \| 'year', …)`, `extract(year \| month \| day \| dow \| hour FROM …)` |
 | Mantle | `auth.uid()`, `input.<name>`, `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance` ([features](features.md)) |

package/docs/handbook/reference/view.md

@@ -21,8 +21,7 @@ OFFSET, arbitrary functions/relations, DDL and transaction control are not a rea
 `mantle.search(<alias>, <text>)` matches the Schema's declared `searchableFields`, and `mantle.search_rank(<alias>)`
 orders by relevance; qualify both with `mantle.`. An optional search reads
 `WHERE p.active AND (input.q IS NULL OR mantle.search(p, input.q))`, and a ranked one
-`WHERE mantle.search(p, input.q) ORDER BY mantle.search_rank(p), p.id` (see `examples/reference-service` `catalog.yaml`
-for cursor paging over the rank).
+`WHERE mantle.search(p, input.q) ORDER BY mantle.search_rank(p), p.id`; page it with a cursor over the rank and the id.
 
 Views using `mantle.search`, Store search and Admin list search share the dialect search: SQLite/D1 use FTS for queries of 3 or more characters (shorter queries use LIKE); PostgreSQL uses ILIKE over the declared fields and scans by default. A View does not make PostgreSQL search faster. For large PostgreSQL tables, the application's agent adds trigram indexes in a migration, which ILIKE then uses with no code change:
 

package/docs/handbook/releases/index.md

@@ -32,123 +32,116 @@ Pin every package you use to the same exact version and upgrade them together.
 From 0.1.x, follow [Upgrade 0.1 to 0.2](upgrade-0.1-to-0.2.md) instead: a new database, a reviewed and rehearsed data
 move, and never booting 0.2 against a 0.1.x database.
 
-## 0.2.1 — in preparation
-
-0.2.1 adds Schema locks: a manifest rule that refuses a row's update or delete
-for every caller path (REST, MCP, Admin and Procedures), with Admin showing the
-lock before an edit. `spec.publishing.liveEdits` lets an application edit a
-published row in place, and the [revisions guide](../guides/revisions.md) now
-freezes the live revision with a lock and switches it atomically. It also brings
-Admin form and refresh fixes, the media picker for custom inputs and pages
-(`@aotter/mantle-admin/media`), `matchTarget` in `@aotter/mantle/describe`, and
-dependency updates for current advisories.
-
-Procedures gain `handler.steps`: a program written one statement per step, where
-`onNoRows: conflict` makes a set-op write that writes nothing a `CONFLICT` and
-rolls the whole program back ("create only if the parent exists"). Ref handlers
-and interactive transactions can use `store.batch` for atomic multi-writes, and
-`mantle bundle` under `wrangler dev` reports stale generated output in one line
-instead of a failed build.
-
-### Upgrading to 0.2.1-alpha.4
-
-- **The agent asks once, up front.** The two stops of alpha.3 are gone: users read a stop in the middle of the run as
-  its end. After the first brief, the agent replies with one plan in the user's language and business terms. The plan
-  covers what each kind of user can do and the rules the app enforces, who will try the app, how much sample data and
-  what counts as fast enough, and the questions the brief leaves open, each with a default answer. After one go-ahead
-  the agent builds, opens the Developer UI and the browser itself, runs acceptance and the performance pass, and
-  reports at the end ([Build from a product brief](../start/agents.md#build-from-a-product-brief)). No code changes.
-
-### Upgrading to 0.2.1-alpha.3
-
-- **Agent guidance has one home, the handbook.** The package no longer ships `docs/skills/`, so the `mantle help
-  skills/<name>` topics are gone. Their guidance is now in handbook pages:
-  [performance pass](../guides/performance.md),
-  [deploy and operate](../cloudflare/deploy-and-operate.md),
-  [cleaning up stale uploads](../cloudflare/media-r2.md#clean-up-stale-uploads),
-  [upgrading an application](#upgrade-an-application) and
-  [adoption in an existing app](../guides/typed-queries.md#adopt-mantle-in-an-existing-application).
-  `mantle help` reaches all of them from the entry page.
-- **The `mantle` skill no longer depends on the SDK version.** It routes to `mantle help`, so
-  `npx skills add aotter/mantle@mantle` no longer needs a release tag. A skill installed from an earlier tag still
-  names `docs/skills/` paths; reinstall it.
-- **Docs moves.** The 0.1 → 0.2 upgrade guide is now the topic `mantle help upgrade-0.1-to-0.2`. The package README is
-  an index of topics.
-- **The agent workflow checks in with the user.** Once the manifests generate, `pnpm accept --open` opens the Developer
-  UI (`/admin/dev`) so the user can see the wiring. The agent then stops twice with a plan: before acceptance and
-  before the performance pass. It finishes with an acceptance summary and a before → after performance summary
-  ([agents](../start/agents.md)).
-
-Regenerate to pick up the rest of this release. No manifest or API changes:
-
-- **Developer UI diagrams.**
-  - The data model is a real ER diagram: keys, types and crow's-foot cardinality, with three display modes.
-  - System wiring is laid out in columns, with a minimap.
+## 0.2.1 (2026-10-30)
+
+0.2.1 adds **Schema locks**: a manifest rule that refuses a row's update or delete on every caller path (REST, MCP,
+Admin and Procedures), and Admin shows the lock before an edit. `spec.publishing.liveEdits` lets an application edit a
+published row in place. The [revisions guide](../guides/revisions.md) now freezes the live revision with a lock and
+switches it atomically.
+
+Procedures gain `handler.steps`, a program written one statement per step. With `onNoRows: conflict`, a set-op write
+that writes nothing becomes a `CONFLICT` and rolls the whole program back ("create only if the parent exists"). Ref
+handlers and interactive transactions can use `store.batch` for atomic multi-writes. Hand-built MCP tools can attach
+listing and result metadata and page `tools/list`.
+
+For agents and for the people working with them:
+
+- `mantle help` is the single source of guidance, and the `mantle` skill no longer depends on the SDK version.
+- An agent building from a brief first replies with one plan, written in business terms, and asks what the brief
+  leaves open. After one go-ahead, it builds, shows the Developer UI, runs acceptance and a performance pass, and
+  reports what each found and changed.
+- The Developer UI draws a real ER diagram, a columned system wiring graph and one Procedure logic graph.
+
+Generated Workers and the Admin start smaller.
+
+[GitHub release](https://github.com/aotter/mantle/releases/tag/v0.2.1) is the complete change history. Known
+follow-ups:
+
+- mounting an adopter MCP server behind Mantle's caller gate ([#1843](https://github.com/aotter/mantle/issues/1843));
+- tool-catalogue change notifications ([#1810](https://github.com/aotter/mantle/issues/1810));
+- the Admin MCP App, which is still above its 480 KB size reference. About 40% of it is the official MCP SDK and zod,
+  which ADR-0029 requires.
+
+### Upgrading from 0.2.0
+
+Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and `@aotter/mantle-admin` dependency to `0.2.1`, refresh the
+lockfile, regenerate, and review the owned output. No DDL changes are required.
+
+Breaking changes:
+
+- **`@aotter/mantle/describe`** keeps only `matchTarget` and the `AppDescription`, `DescribeTarget` and
+  `TargetRequest` types. `describeApp`, `diffApp` and the `@aotter/mantle/target-hash` subpath are removed.
+  - Get a description outside the CLI with `mantle describe <target> manifests/*.yaml > describe.json`, run in Node.js
+    or Bun (for example in a deploy step), and give the JSON to `matchTarget`. Do not import compiler files from
+    `dist`: a Worker cannot compile manifests that contain SQL ([describe](../reference/describe.md)).
+  - Use `mantle describe --diff` instead of `diffApp`, and `_meta.targetHash` instead of `targetHash()`.
+- **PostgreSQL `version`:** Store results return `version` as a number, as on SQLite and D1. Procedure results stay
+  driver-native.
+- **PostgreSQL serialization failures:** SQLSTATE `40001` and `40P01` from a definitive server refusal are now
+  `CONFLICT` with `kind: "serialization"` (409), instead of an unclassified driver error. Nothing is retried
+  automatically; read again before deciding to retry.
+- **Admin record form:** clearing an optional field sends `null`, and generated form types for optional fields are
+  `T | null`.
+- **REST route precedence** is fixed and most-specific-first. Only overlapping same-method http Triggers with the same
+  parameter count can change which one wins. `TRIGGER_PATH_INVALID` and `TRIGGER_PATH_COLLISION` refuse ambiguous
+  paths at generation; see [route precedence](../reference/trigger.md#route-precedence).
+- **Agent guidance moved into the handbook.** The package no longer ships `docs/skills/`, so the `mantle help
+  skills/<name>` topics are gone. Their guidance now lives in these pages, and `mantle help` reaches all of them from
+  its entry page:
+  - [performance pass](../guides/performance.md);
+  - [deploy and operate](../cloudflare/deploy-and-operate.md);
+  - [cleaning up stale uploads](../cloudflare/media-r2.md#clean-up-stale-uploads);
+  - [upgrading an application](#upgrade-an-application);
+  - [adoption in an existing app](../guides/typed-queries.md#adopt-mantle-in-an-existing-application).
+
+  The 0.1 → 0.2 upgrade guide is the topic `mantle help upgrade-0.1-to-0.2`. A `mantle` skill installed from an
+  earlier tag still names `docs/skills/` paths; reinstall it with `npx skills add aotter/mantle@mantle`.
+- **Revisions recipe:** an application that copied the guide's `switch-revision` handler should adopt the new version.
+  It requires `expectedRevisionVersion` from the preview, and seals and switches in one `ctx.store.batch`.
+- **Tooling:** the templates move to Wrangler 4.153.0 and `@cloudflare/workers-types` 5.20261027.1.
+
+New, opt-in:
+
+- **Schema locks and live edits:** see [revisions](../guides/revisions.md).
+- **`handler.steps` and `onNoRows: conflict`.** Ref handlers and interactive transactions can also use
+  `store.batch` for atomic multi-writes.
+- **Hand-built MCP tools** ([MCP Apps](../guides/mcp-apps.md), [surface](../reference/surface.md)):
+  - `Tool.meta` merges into the tool's listed `_meta`. `ui.visibility: ["app"]` can hide a Procedure from clients
+    without MCP Apps; it is a listing hint, and calls are authorized as before.
+  - `withResultMeta(data, meta)` returns `meta` only in the result `_meta`, so a value such as a signed upload URL stays
+    out of `content`. `callTool` returns `{ data, _meta }`; drop `_meta` before forwarding a result to a model.
+  - `toolsPageSize` pages `tools/list` with an opaque `nextCursor`.
+- **Admin media picker** for custom inputs and pages: `@aotter/mantle-admin/media`.
+
+Picked up by regenerating, with no manifest or API change:
+
+- **Agent workflow** ([Build from a product brief](../start/agents.md#build-from-a-product-brief)). The agent works
+  in four phases:
+  1. Before anything else, it replies with one plain-language plan: what each kind of user can do, the rules the app
+     enforces, who will try it, how much sample data, and what counts as fast enough. The plan ends with the open
+     questions, each with a default answer.
+  2. After one go-ahead, it builds and opens the Developer UI (`pnpm accept --open`) in the user's browser.
+  3. It runs role-only acceptance and the performance pass without stopping.
+  4. It ends with an acceptance summary and a before → after performance summary.
+- **Developer UI diagrams:**
+  - The data model is an ER diagram with keys, types and crow's-foot cardinality, in three display modes, with a
+    minimap.
+  - System wiring is laid out in columns, also with a minimap.
   - A Procedure's logic is one graph, the same in the wiring side panel and on the Procedure page: a transaction box,
     CASE as ordered branch rows, and COMMIT and ROLLBACK ends. The SQL syntax trees stay available, folded, on the
     Procedure page.
-  - Their wording is translated in every Admin language that has translations.
-- **Smaller startup.**
-  - Generated Workers emit a repeated SQL statement once. REST loads a Procedure on its first request, the way views and
-    MCP already did. The reference D1 Worker's startup is about 20% smaller.
-  - Admin loads sign-in, OAuth consent and the collection list on demand.
-  - The Admin MCP App uses native select and popover controls.
-
-### Upgrading to 0.2.1-alpha.2
-
-Pin the selected packages to `0.2.1-alpha.2` and regenerate. Breaking change:
-
-- **`@aotter/mantle/describe`** keeps only `matchTarget` and the
-  `AppDescription`, `DescribeTarget` and `TargetRequest` types. `describeApp`,
-  `diffApp` and the `@aotter/mantle/target-hash` subpath are removed.
-  **`mantle describe` output is the supported way to get a description outside
-  the CLI:** run `mantle describe <target> manifests/*.yaml > describe.json` in
-  Node.js or Bun (for example in a deploy step) and give the JSON to
-  `matchTarget`. Do not import compiler files from `dist`; a Worker cannot
-  compile manifests that contain SQL ([describe](../reference/describe.md)).
-  Use `mantle describe --diff` instead of `diffApp`, and `_meta.targetHash`
-  instead of `targetHash()`.
-
-Hand-built MCP tools gain three opt-in capabilities; without them the output
-is unchanged ([MCP Apps](../guides/mcp-apps.md), [surface](../reference/surface.md)):
-
-- `Tool.meta` merges into the tool's listed `_meta`. `ui.visibility: ["app"]`
-  can now hide a Procedure from clients without MCP Apps; it is a listing hint,
-  and calls are authorized as before.
-- `withResultMeta(data, meta)` returns `meta` only in the result `_meta`, so a
-  value such as a signed upload URL stays out of `content`. `callTool` returns
-  `{ data, _meta }`; drop `_meta` before forwarding a result to a model.
-- `toolsPageSize` pages `tools/list` with an opaque `nextCursor`.
-
-Also: generation reports a SQL parser that cannot load in the current runtime
-as such, instead of `SQL_SYNTAX`, and the handbook renders under Vue-based
-site generators (bare `<placeholder>` text is now quoted, and `pnpm check`
-fails on any that return).
-
-### Upgrading to 0.2.1-alpha.1
-
-Pin `@aotter/mantle`, and any selected `@aotter/mantle-ui` and
-`@aotter/mantle-admin`, to `0.2.1-alpha.1`, refresh the lockfile, regenerate and
-review owned output. No DDL changes are required. Breaking changes:
-
-- **PostgreSQL `version`:** Store results return `version` as a number, as on
-  SQLite and D1. Procedure results stay driver-native.
-- **Admin record form:** clearing an optional field sends `null`; generated
-  form types for optional fields are `T | null`.
-- **REST route precedence** is fixed and most-specific-first. Only overlapping
-  same-method http Triggers with the same parameter count can change winner.
-  `TRIGGER_PATH_INVALID` and `TRIGGER_PATH_COLLISION` refuse ambiguous paths
-  at generation; see [route precedence](../reference/trigger.md#route-precedence).
-- **Tooling:** the templates move to Wrangler 4.153.0 and
-  `@cloudflare/workers-types` 5.20261027.1.
-- **PostgreSQL serialization failures:** SQLSTATE `40001` and `40P01` from a
-  definitive server refusal are now `CONFLICT` with `kind: "serialization"`
-  (409), instead of an unclassified driver error. Nothing is retried
-  automatically; read again before deciding to retry.
-- **Revisions recipe:** an application that copied the guide's
-  `switch-revision` handler should adopt the new version. It requires
-  `expectedRevisionVersion` from the preview and seals and switches in one
-  `ctx.store.batch`.
+  - All of their wording is translated in every Admin language that has translations.
+- **Smaller startup:**
+  - Generated Workers emit a repeated SQL statement once, and REST loads a Procedure on its first request. A generated
+    D1 Worker's startup is about 20% smaller.
+  - Admin loads sign-in, OAuth consent and the collection list on demand, and the Admin MCP App uses native select and
+    popover controls.
+- **Fixes:**
+  - Admin forms and refresh;
+  - `mantle bundle` under `wrangler dev` reports stale generated output in one line, instead of a failed build;
+  - generation reports a SQL parser that cannot load in the current runtime as such, instead of `SQL_SYNTAX`;
+  - the handbook renders under Vue-based site generators;
+  - dependency updates for current advisories.
 
 ## 0.2.0 (2026-10-19)
 

package/docs/handbook/start/agents.md

@@ -62,8 +62,8 @@ scope.
    what they are looking at. Keep building while they look; the app rebuilds on every change. Without a browser on the
    machine, give the user the admin URL it prints.
 6. **Run [role-only acceptance](../guides/agent-workflow-acceptance.md)** (`mantle help agent-workflow-acceptance`) as
-   planned. 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. After a repair, the guide's
+   planned. Scripted smoke is not acceptance. `pnpm accept` starts the app and prints, for each role, a URL that carries
+   that role's session; give each URL to a fresh evaluator. 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.
 7. **Run the [performance pass](../guides/performance.md)** as planned, for every role and surface acceptance reports

package/docs/handbook/start/overview.md

@@ -1,5 +1,5 @@
 ---
-description: The native 0.2.0 handbook and its three package boundaries.
+description: The native 0.2 handbook and its three package boundaries.
 ---
 # Mantle handbook
 

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

@@ -40,7 +40,7 @@ module the entry never imports.
 | `cloudflare-d1` | sqlite | D1 binding/session |
 | `cloudflare-postgres` | postgres | postgres.js, usually with Hyperdrive |
 
-Other handles may adapt to the same [structural driver contracts](../guides/adapter-guide.md). Dialects are exactly postgres and sqlite in 0.2.0.
+Other handles may adapt to the same [structural driver contracts](../guides/adapter-guide.md). Dialects are exactly postgres and sqlite in 0.2.
 
 | Option | Meaning |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.1-alpha.4",
+  "version": "0.2.1",
   "type": "module",
   "sideEffects": false,
   "engines": {