@aotter/mantle 0.2.0-alpha.9 → 0.2.0

package/docs/handbook/reference/schema.md

@@ -38,7 +38,7 @@ A string `pattern` needs a `maxLength`: generation bounds each regex's backtrack
 | object/array | JSON text | jsonb |
 | geo | lat/lng columns, R*Tree | lat/lng columns |
 
-System columns include id, version, created_at, updated_at and author_id; publishing adds status/published_at. Do not declare reserved fields. Manifest native column names in indexes use camelCase (`createdAt`); generated Store/SQL use storage names (`created_at`). Scope is omitted from returned rows.
+System columns include id, version, created_at, updated_at and author_id; publishing adds status/published_at. Initial DDL declares a field NOT NULL when an `operational` Schema lists it in `required` and it does not allow null; `default` never does, and no column gets a DDL `DEFAULT` ([server-maintained fields](#admin-uischema)). Do not declare reserved fields. Manifest native column names in indexes use camelCase (`createdAt`); generated Store/SQL use storage names (`created_at`). Scope is omitted from returned rows.
 
 Declared date/date-time outputs are SQL-formatted strings (`YYYY-MM-DD`, UTC ISO with six fractional digits). Computed timestamps remain native. Inputs and other output scalars follow [the native contract](../guides/native-execution.md). Date conversion through JS Date loses microseconds.
 
@@ -76,9 +76,11 @@ The runtime never creates, alters or checks tables. Initial DDL is for an empty
 
 ## Admin uiSchema
 
-A property marked `readOnly: true` in the JSON Schema is server-maintained (a counter, a total): Admin's generic create stores its `default` whatever the input says, Admin edits ignore it, and only Procedures (or server code through the Store) change it afterwards. JSON Schema defaults are applied by Admin and the Store, not by the database: a SQL Procedure that inserts the row sets the field itself. A root `readOnly: true` makes the whole Schema read-only in Admin.
+A property marked `readOnly: true` in the JSON Schema is server-maintained (a counter, a total): Admin's generic create stores its `default` whatever the input says, Admin edits ignore it, and only Procedures (or server code through the Store) change it afterwards. JSON Schema defaults are applied by Admin's generic create only, not by the Store or the database: initial DDL emits no `DEFAULT` for a field, so server code through the Store and a SQL Procedure that inserts the row set the field themselves. A root `readOnly: true` makes the whole Schema read-only in Admin: a generic Admin write is refused with 403 `AUTH_DENIED` (not a 409 version conflict).
 
-`fields.<name>.widget` selects a built-in control (`textarea`); `list.primaryField`, `list.columns` and enum `filterField` select list presentation; `nav.parentField` chooses the parent a child folds under (required when two or more required `id` references exist) and `nav.standalone` lists the child in the sidebar; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). `list.columns` must not repeat `list.primaryField` or itself (`SCHEMA_UI_INVALID`). Generation validates these against declared fields/indexes. Components that render a field, cell or record aside are not manifest references: they live in `defineAdmin` ([customising Admin](../guides/native-admin.md#customising-admin)), and a manifest that still names one (`widget: <extension>/<contribution>`, `widget` `options`, `list.cells`, `panels`) is refused. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field.
+`default` does not make a column NOT NULL; `required` does (in an `operational` Schema). For a server-maintained value that is never NULL, list it in both, `required: [name, total]` with `total: {type: integer, readOnly: true, default: 0}`: initial DDL declares `total` NOT NULL, Store and View row types read it as `number` rather than `number | null`, Admin's create still fills the default when the client omits it, and the Store's insert type requires server code to pass it. Without `required` the column stays nullable, and an INSERT that omits it stores NULL. Adding `required` to an existing table is a [migration](../concepts/runtime-and-adapters.md#schema-installation-and-migrations): backfill NULLs, then add NOT NULL.
+
+`fields.<name>.widget` selects a built-in control (`textarea`); `list.primaryField`, `list.columns` and enum `filterField` select list presentation (operational Schemas only; a publishing Schema's list shows its title field and status); `nav.parentField` chooses the parent a child folds under (required when two or more required `id` references exist) and `nav.standalone` lists the child in the sidebar; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). `list.columns` must not repeat `list.primaryField` or itself (`SCHEMA_UI_INVALID`). Generation validates these against declared fields/indexes. Components that render a field, cell or record aside are not manifest references: they live in `defineAdmin` ([customising Admin](../guides/native-admin.md#customising-admin)), and a manifest that still names one (`widget: <extension>/<contribution>`, `widget` `options`, `list.cells`, `panels`) is refused. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field. It is not a foreign key: the database does not check that the referenced row exists, and deleting that row leaves the reference dangling. Check existence in the write (a JOIN or `EXISTS` in the Procedure) and guard deletes with `NOT EXISTS` ([SQL patterns](../guides/sql-patterns.md)).
 
 See [Admin](../guides/admin-ui.md) and [diagnostics](diagnostics.md).
 
@@ -88,7 +90,11 @@ See [Admin](../guides/admin-ui.md) and [diagnostics](diagnostics.md).
 
 A caller whose value for a field is `{ all: true }` drops that field's term only; the other terms still apply. Generated SQL holds one statement per target and selects the form for each caller at run time; values are always bound parameters. Neither roles nor the admin layer widen a field scope or a translation parent's visibility. A Schema whose `x-mantle-ref` points to a field-scoped Schema must carry the same scope terms.
 
-For inserts, one allowed partition autofills a missing value; multiple values require an explicit allowed partition, and missing/empty values fail with `AUTH_DENIED`. Callers holding `{ all: true }` and system callers always provide an explicit partition. Procedure INSERT/upsert is trusted-only; use the scoped Store for user writes. The partition is never writable through SET, including upsert and native Admin patch. An excluded id behaves like a missing row: reads return not found; Store update/delete and row-classified Procedure UPDATE/DELETE affecting zero rows return HTTP 409 (`CONFLICT`). Native Admin's visible-row pre-read returns 404 for either id. SQLite binds a JSON array; PostgreSQL binds a quoted, escaped array. Public Views over field scope warn that anonymous callers are refused.
+For inserts, one allowed partition autofills a missing value; multiple values require an explicit allowed partition, and missing/empty values fail with `AUTH_DENIED`. Callers holding `{ all: true }` and system callers always provide an explicit partition. A Procedure `INSERT … VALUES` follows the same rule for user callers, checked before any SQL runs: leave the partition column out to autofill a caller's single value, or take it from an input declared with the column's own type (`VALUES (input.region, …)`) or a matching literal, which must be inside the caller's set; any other expression there is refused. A Procedure that callers holding several values or `{ all: true }` use, such as an Admin create action, takes the partition as an optional input. `INSERT … SELECT` into a field-scoped Schema, and an insert into a Schema the target `restrict`s, run only for system callers, which this check does not cover: they name the partition themselves; use the scoped Store for user writes there. The partition is never writable through SET, including upsert and native Admin patch. An excluded id behaves like a missing row: reads return not found; Store update/delete and row-classified Procedure UPDATE/DELETE affecting zero rows return HTTP 409 (`CONFLICT`). Native Admin's visible-row pre-read returns 404 for either id. SQLite binds a JSON array; PostgreSQL binds a quoted, escaped array. Public Views over field scope warn that anonymous callers are refused.
+
+#### References to a scoped Schema
+
+A non-null `x-mantle-ref` value that points to a scoped Schema (field or owner scope) must name a row of that Schema the caller can read, matched on `id` or on the object form's `field`, and that row must have the same value as the child for every scope field the two share (`ADR-0034`: a reference between scoped Schemas stays inside one owner or partition). A Store insert or update, a Procedure `INSERT … VALUES`, `UPDATE … SET` or `DO UPDATE SET`, and native Admin's generic create and patch check it in the same statement; a missing, unreadable or other-partition parent behaves like a missing row: a single-row statement returns HTTP 409 (`CONFLICT`), and an `ON CONFLICT` insert or a set update writes nothing for that row. A caller holding several values or `{ all: true }` can still not point a child in one partition at a parent in another. `INSERT … SELECT` that writes such a reference runs only for system callers. A caller's `UPDATE … SET` or `DO UPDATE SET` of such a reference takes no subquery, which could read the parent's columns as its own. Trusted writes (system callers, `runtime.store`) are not checked, like the other row rules. NULL is always allowed; deleting a parent does not touch its children.
 
 ## Reserved entry columns
 

package/docs/handbook/reference/sql.md

@@ -0,0 +1,64 @@
+---
+description: The SQL that Views and Procedures accept on SQLite/D1 and on PostgreSQL, and what each refuses with which diagnostic.
+---
+# SQL accepted by each dialect
+
+Views and Procedures share one allowlist with two profiles. SQLite and D1 run the base profile; PostgreSQL runs the
+base profile plus the additions below. Anything not listed is refused at generation with a code (`SQL_UNSUPPORTED`,
+`SQL_FUNCTION`, `SQL_SHAPE`, `SQL_TYPE`) and a source position, so generation is the authority for each target. For
+worked examples see [SQL patterns](../guides/sql-patterns.md).
+
+## Both dialects
+
+| Area | Accepted |
+| --- | --- |
+| Statements | `SELECT`, `INSERT … VALUES` / `INSERT … SELECT`, `UPDATE … SET … WHERE`, `DELETE … WHERE`, each with `RETURNING`; `WITH` (non-recursive) on a `SELECT` |
+| Upsert | `ON CONFLICT (<unique index columns>) DO NOTHING` / `DO UPDATE SET …`, with `excluded.<column>` |
+| Joins | `INNER JOIN`, `LEFT JOIN`; a comma join only for a row source (`json_each`, or PostgreSQL's below) |
+| Clauses | `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT` |
+| 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 |
+| 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)) |
+
+## SQLite and D1 only
+
+| Accepted | PostgreSQL instead |
+| --- | --- |
+| `json_each(<array>)` as a row source (`FROM json_each(input.items) j`, `j.value ->> 'field'`) | `jsonb_array_elements(…) AS j(value)` |
+| `json_group_array`, `json_group_object` | `jsonb_agg`, `jsonb_object_agg` |
+| `json_extract`, `json_set`, `json_insert`, `json_remove`, `json_array_length`; build an object with `json_set('{}', '$.k', v, …)` (`json_object` is refused) | `jsonb_build_object`, `jsonb_build_array` and the jsonb operators |
+| `typeof`, `hex` | refused (`typeof` is SQLite's; PostgreSQL has `pg_typeof`) |
+
+An integer `CAST` of anything but a literal is refused (`SQL_TYPE`): SQLite truncates where PostgreSQL rounds. Write
+`round(x)`; `->>` already returns a JSON number as a number.
+
+## PostgreSQL additions
+
+| Area | Accepted |
+| --- | --- |
+| Set operations | `UNION [ALL]`, `INTERSECT`, `EXCEPT`, inside a `WITH` or a subquery (the View's own SELECT is the one that pages) |
+| Relations | `LATERAL` subqueries, `WITH RECURSIVE`, `MATERIALIZED` / `NOT MATERIALIZED` CTEs |
+| Row sources | `jsonb_array_elements`, `jsonb_array_elements_text`, `jsonb_each`, `jsonb_each_text`, with `WITH ORDINALITY` |
+| Operators | `ILIKE`, `~`, `~*`, `!~`, `!~*`, jsonb `->`, `#>`, `#>>`, `@>`, `<@`, `?`, `?\|`, `?&` |
+| Aggregates | `string_agg`, `jsonb_agg`, `jsonb_object_agg`, with `FILTER (WHERE …)` and `ORDER BY` inside the call |
+| Windows | also `avg`, `min`, `max`, `lag`, `lead`, `first_value`, `last_value`, `dense_rank`; frames except `GROUPS` and `EXCLUDE` |
+| Functions | `GREATEST`, `LEAST`, `floor`, `ceil`, `sqrt`, `power`, `split_part`, `timezone`, `jsonb_build_object`, `jsonb_build_array`, `jsonb_strip_nulls`, `to_jsonb`, `jsonb_typeof`, `CAST(… AS jsonb)` |
+| Time | `date_trunc` also `'minute'`, `'quarter'`; `extract` also `minute`, `quarter`, `week`, `isoyear`, `isodow`, `doy`, `epoch` |
+
+`jsonb_agg` of no rows is `NULL`: write `COALESCE(jsonb_agg(…), CAST('[]' AS jsonb))` for an empty array.
+
+## Refused on every target
+
+- `OFFSET`: page with the generated cursor (`limit`, `cursor`) instead.
+- `RIGHT` and `FULL` joins, `UPDATE … FROM`, `DELETE … USING`, DDL and any function not listed.
+- `DISTINCT` with `ORDER BY`: the paging key Mantle appends would change what is distinct; use `GROUP BY`.
+- A program of more than 2000 syntax nodes.
+
+Two write rules come from Mantle, not the dialect ([Procedure](procedure.md)). A row-classified `UPDATE`/`DELETE`
+(`WHERE id = input.id …`) must change exactly one row, otherwise `CONFLICT`. A set form (`WHERE id IN (SELECT …)`,
+`INSERT … SELECT`) may change none, so write a conditional write that may do nothing in that form. Scope, version,
+timestamps and author columns are assigned by Mantle, never by your SQL.

package/docs/handbook/reference/surface.md

@@ -233,7 +233,7 @@ surface its generated `publish_<schema>`, `unpublish_<schema>` and
 `archive_<schema>` tools use the same snake-case naming rule, are admin-only
 and take `{ id, expectedVersion }` through the shared generated validation.
 
-`/mcp/admin` admits only admins: `isAdmin(caller)` must hold. Better Auth’s admin plugin `adminRoles` defines this layer (default `["admin"]`); the application supplies its verified Caller. MCP bodies are limited
+`/mcp/admin` admits only admins: `isAdmin(caller)` must hold. It lists only admin-surface tools; public Views and Procedures stay on `/mcp`, and generation never copies them across. An admin's AI that changes records also needs admin Views to find them and read back the committed row and its version (search, detail), declared by the app; the [acceptance design audit](../guides/agent-workflow-acceptance.md#audit-mcp-tool-design-before-implementation) checks this. Better Auth’s admin plugin `adminRoles` defines this layer (default `["admin"]`); the application supplies its verified Caller. MCP bodies are limited
 to 1 MiB (1,048,576 bytes). Resource metadata challenges use the origin of
 `request.url`; behind a proxy, the app must pass a Request with its public
 origin so the audience and metadata URL point to the client-visible service.
@@ -352,7 +352,10 @@ REST and MCP View pages expose declared JSON columns as JSON values and declared
 boolean columns as booleans, including explicitly authored SQL aliases. SQLite
 and D1 conversions are compiled into only the selected boundary pages;
 PostgreSQL already-native JSON/boolean values pass through. SQL NULL stays null and absent
-fields stay absent. Expressions without declared column lineage stay native.
+fields stay absent. A computed output that is a JSON document by construction
+(`json_group_array`, `json_set`, `jsonb_agg`, `jsonb_build_object` and the like, a scalar
+subquery of one, or a `COALESCE` of those) is converted like a declared JSON column, so it
+is a JSON value on every target. Other expressions without declared column lineage stay native.
 Malformed persisted JSON becomes a redacted internal failure. The conversion
 adds no database operations and does not mutate native query rows.
 

package/docs/handbook/reference/view.md

@@ -1,12 +1,14 @@
 # View
 
-A View requires `surface: public | admin | internal` and one `sql` SELECT. Optional keys include title, description, input, requires, restrict, uiSchema (admin only), and cache. The app imports its generated typed function and supplies a native handle, verified Caller and driver-ready input.
+A View requires `surface: public | admin | internal` and one `sql` SELECT. Optional keys include title, description, input, requires, restrict, uiSchema (admin only), and cache. The app imports its generated typed function and supplies a native handle, verified Caller and driver-ready input; a JSON input (an array read by `json_each(input.ids)`) takes its authored array or object, which the generated query serializes.
 
 ## SQL
 
 PostgreSQL syntax is parsed and checked at generation. Reads may reference declared Schemas, CTEs and reusable internal Views; no auth/system tables or arbitrary external relations. The compiler adds scope, TTL, publication and translation-parent visibility at every relation. SQL policy is not injected at request time.
 
-SQLite supports the compiler's subset: scalar expressions, comparisons, AND/OR/NOT, CASE, COALESCE, supported casts, INNER/LEFT JOIN, subqueries, grouping/aggregates, supported windows, ordered LIMIT, date operations and declared Mantle search/geo functions. PostgreSQL additionally supports recursive CTEs, lateral relations, more window/aggregate forms, ILIKE and jsonb operators where the allowlist permits them. Unsupported SQL fails with a source position; generation is the authority for each target.
+The SQL each dialect accepts, for Views and Procedures alike, is listed in [the SQL reference](sql.md); [SQL patterns](../guides/sql-patterns.md) shows the common ones. Unsupported SQL fails with a source position; generation is the authority for each target.
+
+`*` and `t.*` expand to the Schema's declared fields only. Select `id`, `version`, `created_at` and `updated_at` by name when a client needs them (a write's `expectedVersion`, a detail link, keyset paging).
 
 OFFSET, arbitrary functions/relations, DDL and transaction control are not a read escape hatch. Use keyset paging. Select latitude/longitude explicitly instead of native geo projections.
 
@@ -16,6 +18,12 @@ OFFSET, arbitrary functions/relations, DDL and transaction control are not a rea
 
 ## Search and totals
 
+`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).
+
 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:
 
 ```sql
@@ -27,7 +35,7 @@ Store keeps `find`/`first` search and `count`. `count` scans every matching row;
 
 ## Results and paging
 
-Each SELECT output needs a unique static name. Unquoted SQL identifiers fold to lower case; use an explicit quoted alias to preserve case (`r.reqStatus AS "reqStatus"`). Generation warns when an unaliased direct declared field would use its lower-case storage name. Declared-column lineage supplies generated types; computed outputs remain native/unknown. SQL formats declared date-time/date outputs, while computed timestamps retain driver values. See [native execution](../guides/native-execution.md).
+Each SELECT output needs a unique static name. Unquoted SQL identifiers fold to lower case; use an explicit quoted alias to preserve case (`r.reqStatus AS "reqStatus"`). Generation warns when an unaliased direct declared field would use its lower-case storage name. Declared-column lineage supplies generated types; computed outputs remain native/unknown, except a top-level output that is a JSON document by construction (a JSON aggregate or builder, a scalar subquery of one, or a `COALESCE` of those; see [SQL patterns](../guides/sql-patterns.md#a-row-with-its-children-in-one-read)), which is typed JSON. An output is non-null (`string`, not `string | null`) only when it reads unchanged a column its table declares NOT NULL (`id`, `version`, `created_at`, `updated_at`, a publishing `status`, or a [required](schema.md#fields-and-storage) field of an operational Schema) directly or through FROM subqueries; the right side of a LEFT JOIN, an aggregate, a column beside an aggregate without GROUP BY, a CTE and an expression stay nullable. SQL formats declared date-time/date outputs, while computed timestamps retain driver values. See [native execution](../guides/native-execution.md).
 
 Bare `views/<encoded-name>.ts` returns row arrays. Proved pageable exposed/internal Views also receive native `paged/views/*`, returning `{ rows, nextCursor? }`. Selected REST/MCP boundaries use separate `paged/wire/views/*` SQL when declared integers require exact transport projections; bare modules also export `WireRow`. Indexed ordering after fixed equality prefixes ([index prefixes](schema.md#index-prefixes-for-paged-views)), non-null typed keys, complete groups and singleton joins/lookups are checked at generation. Unsupported internal paging retains its bare View; exposure requires a supported page contract. Aggregates still scan/group their sources: inspect EXPLAIN.
 

package/docs/handbook/releases/index.md

@@ -15,15 +15,36 @@ From 0.2.0-alpha.7, Mantle publishes three packages together at one version:
 and `@aotter/mantle-admin` (optional Admin server, SPA and MCP App).
 Pin every package you use to the same exact version and upgrade them together.
 
-## 0.2.0 — in preparation
-
-### Upgrading to 0.2.0-alpha.9
+## 0.2.0 (2026-10-19)
+
+The first stable native 0.2 release compiles closed v2 manifests to SQL and
+TypeScript for Bun SQLite/PostgreSQL and Cloudflare D1/PostgreSQL. It ships
+three matching packages: Core, the pure UI kit and the optional application-built
+Admin. Applications own routing, verified identity, database handles, migrations
+and deployment; selected REST, MCP, public pages, publishing, translations and
+media compose around the generated operations.
+
+This is a breaking upgrade from 0.1.x: follow the [0.1-to-0.2 migration
+guide](../../upgrade-0.1-to-0.2.md), use a new 0.2 database and explicitly move
+data. From alpha.11, pin the three selected packages to 0.2.0, regenerate and
+review owned output; the stable version commit changes release metadata and
+documentation rather than adding another runtime API.
+
+[GitHub release](https://github.com/aotter/mantle/releases/tag/v0.2.0) is the
+complete change history. Known follow-ups remain tracked: [Admin/authoring
+refinements](https://github.com/aotter/mantle/issues/1752), [production social
+and magic-link recipe verification](https://github.com/aotter/mantle/issues/1273)
+and [real Sites guide verification](https://github.com/aotter/mantle/issues/1272).
+Those provider-specific paths are not claimed as verified by local OTP or
+native-host tests.
+
+### Upgrading to 0.2.0
 
 Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and
-`@aotter/mantle-admin` dependency to `0.2.0-alpha.9`, refresh the lockfile,
+`@aotter/mantle-admin` dependency to `0.2.0`, refresh the lockfile,
 then regenerate and check the application's owned artifacts. Keep existing
 production migrations application-owned; generated initial DDL is for an empty
-database. This alpha includes breaking Admin authoring and paging changes.
+database. This release includes breaking Admin authoring and paging changes.
 
 1. **Build output and host configuration.** `mantle bundle` writes server
    modules to `dist/worker` and static files to `dist/client`, including
@@ -112,7 +133,7 @@ Existing alpha.6 applications require a source migration:
   application code. Review [authorization and Caller wiring](../concepts/runtime-and-adapters.md)
   and regenerate all owned artifacts before running `generate --check`.
 
-The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0-alpha.9/docs/examples/reference-service) and
+The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0/docs/examples/reference-service) and
 [app shell](../../examples/app-shell/) demonstrate the current composition.
 The following earlier-alpha notes are historical; the current handbook and
 the native migration above supersede their runtime and CLI instructions.

package/docs/handbook/start/agents.md

@@ -0,0 +1,45 @@
+---
+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
+
+`mantle help` prints this page. `mantle help <topic>` prints one handbook page and ends with the commands for its next page and for every page it links; run those to read further.
+Topics are the handbook paths below (for example `guides/native-admin`) or their last segment when unique (`native-admin`).
+The installed package's `docs/` is the source of every topic, so the text always matches the installed version.
+
+## Choose how much Mantle owns
+
+| You want | Do |
+| --- | --- |
+| A complete application | `mantle init [directory]`, then follow its `README.md`. It writes the app shell once: Better Auth email OTP with `admin` and `user`, the Admin console, MCP for both roles, REST, and a member `/sign-in` page. Existing files stop it; `--dry-run` lists what it would write. |
+| Only typed SQL and bindings inside an app you already have | Skip `init`. Write manifests and run `mantle generate <target> <output-directory> <manifest>...`; see `mantle help project-and-cli` and `mantle help typed-queries`. |
+
+`init` writes the `cloudflare-d1` shell, the default target. `bun-sqlite`, `bun-postgres` and `cloudflare-postgres`
+generate the same bindings; their app entry is yours (`mantle help service-entry`).
+
+`init` writes app code you then own; it never runs again. `generate` writes only `generated/` and Wrangler build keys,
+and overwrites them on every run. When `generate` sees a selected surface (REST, MCP, Admin) whose generated module
+the app entry (`--entry`) never imports, it warns and names the topic that shows the wiring.
+
+## Build from a product brief
+
+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.
+3. For each need, find the pattern in `mantle help examples` (the **Combining** table) and read that example's
+   manifest and source. Examples are references: take the pattern into your own manifests; do not copy an example
+   directory into the app.
+   - Business rules (status transitions, approval thresholds, stock, guards, several rows that commit together)
+     belong in SQL Procedures, not in handler code around separate writes: `mantle help sql-patterns`, and
+     `mantle help sql` for the SQL each dialect accepts.
+   - Visitor pages (anything anonymous and indexable) follow `mantle help public-pages`: server-rendered HTML,
+     canonical and Open Graph tags, JSON-LD and an answer block on detail pages, Markdown alternates, `/sitemap.xml`,
+     `/robots.txt` and `/llms.txt`. A brief that names a site, shop or catalogue for visitors includes all of them.
+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.
+
+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.
+[Authentication](../cloudflare/authentication.md#identity-helpers) documents the same operations as an API.

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

@@ -23,10 +23,16 @@ tool names or writing manifests/handlers.
 ## Commands
 
 ```sh
+mantle help [topic]                  # these docs, one page at a time; start here
+mantle init [directory] [--dry-run]  # write the cloudflare-d1 app shell once; never overwrites
 mantle generate <target> <output-directory> <manifest>... [options]
 mantle bundle <entry> <outdir> [--assets <dir>]
 ```
 
+`init` writes application code the app then owns. `generate` writes only generated output and Wrangler build keys,
+on every run; after writing, it follows the `--entry` file's imports and warns for each selected REST, MCP or Admin
+module the entry never imports.
+
 | Target | Dialect | Handle |
 | --- | --- | --- |
 | `bun-sqlite` | sqlite | bun:sqlite Database |

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 an exact released `@aotter/mantle` version, 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 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.
 
 Save `manifests/tickets.yaml`:
 

package/docs/skills/develop/SKILL.md

@@ -22,11 +22,12 @@ for the generate warning and deliberate asymmetry exception.
 Keep optional modules out of unused entry imports and auth dynamically loaded.
 Run actual public/member/admin HTTP, MCP and UI scenarios; verify stored state,
 visibility, OCC and restart persistence, not just a 200 response.
-Before reporting any user-facing work as done, follow the [independent
-acceptance guide](../../handbook/guides/agent-workflow-acceptance.md): run it
-with a fresh agent on the surface its user uses. 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
+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
+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.
 
 For native Admin, read the [current guide](../../handbook/guides/native-admin.md):

package/docs/skills/update/SKILL.md

@@ -20,6 +20,8 @@ For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md): give the
 against a 0.1.x database. 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.
+
 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
 a package-only update. For 0.2-to-0.2 updates, preserve users, sessions, content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -106,7 +106,24 @@
     "wrangler": "4.145.0",
     "vitest": "^5.0.1"
   },
-  "description": "Mantle: a manifest-driven service core. Store authored as SQL, surfaces as Fetch functions, and the mantle CLI.",
+  "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": [
+    "mantle",
+    "agent-native",
+    "sdk",
+    "backend",
+    "yaml",
+    "code-generation",
+    "sql",
+    "sqlite",
+    "postgresql",
+    "cloudflare-d1",
+    "cloudflare-workers",
+    "bun",
+    "typescript",
+    "mcp",
+    "model-context-protocol"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
   "repository": {
@@ -114,13 +131,16 @@
     "url": "git+https://github.com/aotter/mantle.git",
     "directory": "packages/mantle"
   },
+  "bugs": {
+    "url": "https://github.com/aotter/mantle/issues"
+  },
   "publishConfig": {
     "access": "public",
     "tag": "alpha",
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.lib.json && node scripts/bundle-compiler.mjs && node scripts/prune-declarations.mjs",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.lib.json && node ../../scripts/strip-comments.mjs tsconfig.lib.json && node scripts/bundle-compiler.mjs && node scripts/prune-declarations.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test tests/*.test.ts && bun run test:compiler",
     "generate": "bun src/infrastructure/cli.ts",

package/skills/README.md

@@ -27,7 +27,7 @@ release tag as the application's SDK; alpha releases on `develop` can be newer
 than the default `main` branch. For a skill-only installation:
 
 ```sh
-npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.9 --skill mantle
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0 --skill mantle
 ```
 
 The explicit skill name excludes repository maintainer skills. The manifests

package/skills/mantle/SKILL.md

@@ -17,9 +17,19 @@ authority: `node_modules/@aotter/mantle/README.md` and
 `node_modules/@aotter/mantle/docs/`. Prefer them over this file, the SDK
 checkout, or any online copy.
 
+## Start with `mantle help`
+
+Run `mantle help` first (in a project: `npx mantle help`; before one exists:
+`npx @aotter/mantle@<exact version> help`). It prints the installed version's
+entry page and every topic; `mantle help <topic>` prints one page with the next
+and linked topics as commands. Follow it rather than browsing the SDK checkout
+or an online copy.
+
 ## Find the project and its version
 
 Work in the user's application, outside the SDK checkout. Read package.json, the lockfile, installed SDK README and node_modules/@aotter/mantle/docs/. Those files define the exact version's contract. Preserve existing identity, handles, routes and resources.
+For existing older applications, use their installed docs until the user requests an upgrade; if an older version
+lacks a guide named here, record the missing guidance and keep that version's contract.
 
 ## Choose the installed package skill
 
@@ -29,129 +39,38 @@ Work in the user's application, outside the SDK checkout. Read package.json, the
 - Read `node_modules/@aotter/mantle/docs/skills/provision/SKILL.md` only for an authorized production deployment.
 - Read `node_modules/@aotter/mantle/docs/skills/media-gc/SKILL.md` only to audit or remove stale uncommitted media uploads.
 
-For a new project, install an exact published SDK version with matching selected Admin/UI packages. Node must be 22.22 or newer. Add TypeScript and target types; Workers also need Wrangler. `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the Wrangler, TypeScript and type-package versions this release is tested with. Optional auth/MCP peers use the installed SDK's package.json versions. Read the installed handbook's start/project-and-cli.md before choosing a target.
-
-For a new Cloudflare app, copy `node_modules/@aotter/mantle/docs/examples/app-shell/` first, then the closest example from `docs/examples/README.md` on top of it, and edit from there: manifests, `src/handlers.ts`, `src/routes.ts`, `src/schedule.ts`, `smoke.mjs`. Search for `AGENT:` to find what the app must fill in; the example pages are unstyled on purpose, so styling them is part of that work. Before reporting done, resolve each `AGENT:` or name the ones you left. Keep the two roles `admin` and `user` unless the user asks for more.
-
-Before reporting any user-facing work as done, follow the installed
-`node_modules/@aotter/mantle/docs/handbook/guides/agent-workflow-acceptance.md`:
-run independent acceptance with a fresh agent on the surface its user uses.
-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. This workflow practice applies to every
-installed SDK version: if its guide is older or MCP-scoped, apply its fresh-agent
-round loop to the user-facing surface actually built. If an older installed
-version lacks this guide, record the missing guidance and preserve that version's
-contract; do not silently upgrade or substitute checkout/online docs.
-
-For existing older applications, use their installed docs until the user requests an upgrade. For partial adoption read node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md.
-
-## Generated native applications
-
-Follow the installed (or workspace-linked) package README for generation, Workers
-builds and D1 Sessions; the app owns its entry and routing. Read that
-version's `docs/handbook/reference/features.md` before choosing declarations. Keep auth behind
-`authLoader(() => import(...))` to pass the startup guard. Install only the exact
-released version shown by the installed/target package
-contract. Replacing Core needs explicit app wiring and reviewed deployment
-migrations; never use initial schema.sql as an in-place production upgrade.
-Pass outgoing `responseHeaders` to `resolveCaller` so Better Auth's session cookie
-can slide. Native auth adapters use joins by default; keep the joined primary
-session/user check, including before any refresh from secondary storage.
-Only positively classified View/web reads may pass `readOnly: true`, with official
-cookieCache `{enabled:true,maxAge:60,refreshCache:false,version:"read-60-v1"}` and
-no KV. Bump version when enabling/changing the policy; writes, Admin, consent,
-unknown/ref/media calls stay fresh. Read the installed auth docs before MCP caching.
-
-Use the workflow **generate → implement listed handlers → check**. In an app
-copied from the installed app shell, its scripts are the canonical commands:
-
-```sh
-pnpm generate
-pnpm check
-```
-Implement every printed `Handlers` key
-and pass the implementations at `store(db, caller, { handlers })` (and selected
-surface options).
-Generated Store metadata initializes on its first use, once per module. Bind
-`store(db, caller, options?)` for the current request; never reuse one caller's
-bound Store for another caller.
-
-Use `paged/views/<encoded-name>.ts` for bounded cursor walks, including internal
-Views that satisfy the installed package's generation-time paging proofs.
-Call its default export with `(db, caller, input, { limit?, cursor? })`; it returns
-`{ rows, nextCursor? }`. Internal paging creates no public route/tool. Keep bare
-Views for authored-query row arrays, and inspect native EXPLAIN/source indexes
-when grouping: cursor paging does not eliminate aggregation work.
-Bare Views, Store and SQL Procedure results keep driver-native scalar values.
-Selected REST/MCP/Admin boundaries return target-identical `WireRow` types:
-declared integers become safe numbers or exact decimal strings, SQLite/D1
-JSON/booleans become JSON values/booleans, and compiler-declared decimals become
-strings. Selected SQL reads integer text before driver rounding; it cannot repair
-already-rounded writes. Use exported `WireRow` for clients and `Row` for bare
-queries. Computed/ref results remain app-owned.
-
-Commit everything `mantle generate` writes, including generated TypeScript, SQL and
-Wrangler edits; keep bundle `dist/` untracked. Never hand-edit generated files.
-Resolve conflicts by merging manifests/options and regenerating. Add the printed
-`.gitattributes` line and run the same generate command with `--check` in CI.
-Compose the app-owned `fetch` using `docs/handbook/cloudflare/service-entry.md`: auth/consent, Admin,
-MCP, REST behind one request-local origin-checked resolver; keep heavy auth dynamic.
-Pair every HTTP Trigger with an MCP Trigger by default; see `docs/handbook/reference/trigger.md` for the generate warning and deliberate asymmetry exception.
-
-For selected native Admin, follow the version-matched
-`docs/handbook/guides/native-admin.md`: select `--admin` (or `admin: true`), then
-build and serve the application-owned Admin with `mantle bundle` as that guide
-describes.
-Admin reads share generated whitelisted native View templates, writes use native
-Procedure fragments and generated checks. Ref operations retain typed `ctx.store`
-at request time. Verify member/frontend and admin/Admin OTP, tenant/privacy/TTL,
-publishing, paging, statistics, exact OCC, ref effects and the actual console;
-never retry unknown 503 writes automatically. Read the installed Admin README
-for raw-body limits, CSP/assets, 22 languages and the developer workspace.
-Use only versions actually published, or the explicitly linked workspace packages.
-
-For generated native applications, optional site settings/media are selected
-with `--site <module>` exporting `siteDefaults`. Apply the emitted deployment DDL;
-wire application-owned object storage as documented in `docs/handbook/cloudflare/media-r2.md`.
-
-For a generated public website, follow [web mounting and acceptance](references/web.md).
-The app renders HTML and inserts `site.head()`; generated `web.ts` serves the
-indexes and Markdown alternates.
-
-## Complete websites
-
-For a requested complete website, apply [website defaults](references/website.md)
-without asking the user to enumerate OTP, media, Admin or SEO. Defaults are
-acceptance requirements, not evidence that a missing renderer is implemented.
-Do not report a complete website with blocked required checks.
-
-Run the [local HTTP acceptance](references/local-testing.md) for handlers and selected interfaces; compilation does not execute their behavior. Account for every declared interface as verified, intentionally not exposed, or deferred/unverified with a reason in the existing application handoff. An early preview may defer remote MCP; preserve that pending work. WebMCP, cookie-session discovery and OAuth Bearer/client integration are separate checks.
-
-## Self-hosted deployment
-
-Deploy only when the user requests it. Follow the application's selected host
-and the installed `docs/skills/provision/SKILL.md`; use the platform's native
-workflow. Local project creation alone is not deployment authorization.
+## New application
 
-## Existing project and handoff
+Node must be 22.22 or newer. Stable 0.2.0 is available as `@aotter/mantle@0.2.0`; pin selected Mantle packages to that exact version. Create it with `npx @aotter/mantle@<exact version> init <directory>`, then follow
+`mantle help` ("Build from a product brief") and the app's `README.md`. Without the user listing them, a complete app
+includes:
+
+- Email OTP sign-in, the two roles `admin` and `user`, Admin for `admin`, MCP for both roles (`/mcp`, `/mcp/admin`)
+  and REST: the shell already wires them; keep them.
+- Real business rules in SQL Procedures (`mantle help sql-patterns`), not in handler code around separate writes.
+- For visitor pages, everything in `mantle help public-pages` (SEO, AEO, sitemap, robots, `llms.txt`), styled.
+- Local HTTP checks (`mantle help local-testing`), then independent acceptance with `pnpm accept`
+  (`mantle help agent-workflow-acceptance`).
 
-Preserve the user's manifests, `src/` files, identity, package versions and
-provider resources. The app writes its entry (`src/worker.ts` by default;
-`--entry` selects another). Workers generation creates or updates Wrangler's
-split-build settings and public-fetch compatibility flags. Run the same generation command (target, output directory,
-manifests and options) with `--check`, and the project's own tests,
-before and after a change.
+Take patterns from `mantle help examples` into the app's own manifests and `src/`; do not copy an example directory
+over the app. Resolve each `AGENT:` or name the ones you left. Generation only, inside an app you already have: skip
+`init` and use `mantle generate` (`mantle help project-and-cli`).
 
-To add Mantle to an application that has its own code, users and data, read
-`node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md` first.
+## Accept before reporting done
 
-Report the project path, the exact Mantle version, what you changed, the checks
-you ran with their results, the independent acceptance verdict (CONVERGED / NOT
-CONVERGED / BLOCKED / UNVERIFIED), and anything left for the user.
+Before reporting any new app or feature as done, follow `mantle help agent-workflow-acceptance`: a private rubric,
+then one fresh agent per role given only its role and the URLs `pnpm accept` prints, at most three rounds. If it was
+not run, report the work as UNVERIFIED rather than done; if it could not run, BLOCKED.
+
+## Deployment
+
+Deploy only when the user requests it, following the installed `docs/skills/provision/SKILL.md` and the selected
+host's native workflow. Local project creation alone is not deployment authorization.
+
+## Existing project and handoff
 
-## Data paths
+Preserve the user's manifests, `src/` files, identity, package versions and provider resources. Run the project's
+generate command with `--check` and its own tests before and after a change.
 
-Follow the installed `docs/handbook/guides/typed-queries.md` for Store,
-Procedure and View data paths; the service composition guide owns request-local
-Caller binding.
+Report the project path, the exact Mantle version, what you changed, the checks you ran with their results, the
+independent acceptance verdict (CONVERGED / BLOCKED / UNVERIFIED), and anything left for the user.