@aotter/mantle 0.2.1-alpha.3 → 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.3/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.3",
-    "@aotter/mantle-ui": "0.2.1-alpha.3",
+    "@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.3",
+    "@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.3/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/agent-workflow-acceptance.md

@@ -85,15 +85,17 @@ rounds below before claiming the user-facing work is done. Keep the author's
 capability map and worked call sequence out of the fresh agent's prompt: an MCP
 evaluator must discover the workflow from public tool descriptions and results.
 
-## Propose the run first
+## Plan the run
 
-Before the first round, stop and give the user the plan, then wait for a go-ahead:
+The plan the user approves before the build ([Build from a product brief](../start/agents.md#build-from-a-product-brief))
+says in plain words who tries the app and what they try to get done. Behind it, the run
+fixes:
 
 - each evaluator you will start: its role (`admin`, `user`, a visitor), the surfaces it uses (Admin, member pages,
   REST, MCP, visitor pages) and the goals it is asked to finish, in the user's words;
 - the round limit (at most three) and what triggers a re-run;
-- anything the environment needs, such as a browser for a visitor or member page, so a missing one is settled now
-  rather than reported as BLOCKED later.
+- what the environment needs, such as a browser for a visitor or member page. Provide it yourself (install a headless
+  browser if none is there); only what you cannot provide goes to the user now, rather than reported as BLOCKED later.
 
 Keep the rubric itself private: the plan names goals, never the checks an evaluator is graded on.
 

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/performance.md

@@ -35,9 +35,11 @@ skipped part with its reason.
 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.
 
-## Propose the pass first
+## Plan the pass
 
-Before measuring, stop and give the user the plan, then wait for a go-ahead:
+The plan the user approves before the build ([Build from a product brief](../start/agents.md#build-from-a-product-brief))
+says in plain words how much sample data there is and what "fast enough" means for each page.
+Behind it, the pass fixes:
 
 - the parts that run and the parts skipped, each with its reason (the table above);
 - the test data for backend parts: rows per table (for example 1,000,000 RSVPs across 5,000 events and 20,000

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,114 +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.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

@@ -25,6 +25,24 @@ the app entry (`--entry`) never imports, it warns and names the topic that shows
 
 ## Build from a product brief
 
+**Plan once, then run to the end.** Before writing anything, reply with one plan and wait for the user's go-ahead.
+Write it in the user's language and in business terms: no Schema, SQL, route, tool or package names.
+
+- **What the app does:** what each kind of user can do, and the business rules it enforces. For example: "a full event
+  puts new sign-ups on a waiting list, and a cancellation moves the first person on it in".
+- **How you will check it works:** who will try the app and what each of them tries to get done
+  ([acceptance](../guides/agent-workflow-acceptance.md#plan-the-run)).
+- **How you will check it is fast:** how much sample data, and what "fast enough" means for each page
+  ([performance](../guides/performance.md#plan-the-pass)).
+- **What you will do on the user's machine,** such as starting the app and opening the browser for them and for the
+  testers. Say it; do not ask. Ask only for what you cannot do yourself, such as a deployment or a credential.
+- **Questions:** every rule the brief leaves open, such as limits, deadlines, who may see or change what, and what
+  happens on a cancellation. Give each one the answer you will assume if the user does not reply.
+
+After the go-ahead, do every step below without stopping, and end with the report in the last step. Stop again only
+for what the plan did not cover and needs the user: a credential, a deployment, a destructive action or a change of
+scope.
+
 1. `mantle init`, install, then read the app's `README.md` and search for `AGENT:`.
 2. Map the brief to the [four atoms](../concepts/four-atoms.md): Schemas, Views, Procedures, Triggers.
    Decide what each role (`admin`, `user`) does on each surface: Admin, MCP, REST and any visitor pages.
@@ -43,16 +61,14 @@ the app entry (`--entry`) never imports, it warns and names the topic that shows
    the Schemas, Views, Procedures and Triggers and how they connect, with each surface's routes and tools. Tell the user
    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. **Stop and ask before acceptance.** Propose the [acceptance plan](../guides/agent-workflow-acceptance.md#propose-the-run-first)
-   and wait for the user's go-ahead. Then 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. After a repair, the guide's
+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 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. **Stop and ask before the performance pass.** For every role and surface acceptance reports CONVERGED, propose the
-   [performance plan](../guides/performance.md#propose-the-pass-first) (which parts run, how much test data, which
-   targets) and wait for the go-ahead; then run the [performance pass](../guides/performance.md). BLOCKED or UNVERIFIED
-   parts are reported as they are, never optimized. A declined step is reported as not run, never as done.
+7. **Run the [performance pass](../guides/performance.md)** as planned, for every role and surface acceptance reports
+   CONVERGED. BLOCKED or UNVERIFIED parts are reported as they are, never optimized. A step the user declined in the
+   plan is reported as not run, never as done.
 8. **Report what changed, not only that it passed:** the [acceptance summary](../guides/agent-workflow-acceptance.md#summarise-for-the-user)
    and the [performance summary](../guides/performance.md#summarise-for-the-user), then the layered status.
 

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.3",
+  "version": "0.2.1",
   "type": "module",
   "sideEffects": false,
   "engines": {

package/skills/mantle/SKILL.md

@@ -18,7 +18,8 @@ its docs one topic at a time.
 2. **Work in the user's application.** Read its `package.json` and lockfile for the exact Mantle version and keep using
    that version's docs until the user asks to upgrade (`mantle help releases/index`). Preserve existing code, identity,
    versions and resources.
-3. **Stop for the user at the entry page's checkpoints:** show the running Admin and its Developer UI once the manifests
-   generate, and ask before acceptance and before the performance pass. Never report done without them; end with what
-   each one found and changed, and each layer as CONVERGED, BLOCKED or UNVERIFIED.
+3. **Plan once, then run to the end.** For a new app, first reply with the entry page's plan, in plain business terms
+   and with the questions the brief leaves open, and wait for one go-ahead. Then build, show the Developer UI, accept
+   and measure without stopping. Never report done without acceptance and performance; end with what each found and
+   changed, and each layer as CONVERGED, BLOCKED or UNVERIFIED.
 4. **Deploy, delete remote data or publish nothing unless the user asks for that exact action.**