@aotter/mantle 0.2.0-alpha.8 → 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

@@ -13,7 +13,7 @@
   snake-cased View names on each declared surface, and snake-cased Procedure
   names per MCP Trigger. Its SDK loads only through a request-time dynamic import.
 - HTTP/MCP Triggers declare exposure only. `mantle generate` refuses schedule
-  and lifecycle Triggers; Cloud scheduling is a separate capability.
+  and lifecycle Triggers; host scheduling is a separate capability.
 - Native Admin retains selected 0.2 paths and the console contracts; see
   [Native Admin](../guides/native-admin.md) for app-mounted
   `adminBindings()` and `entries(bindings.schemas, bindings.adapter)`.
@@ -25,6 +25,8 @@ challenges, JSON-RPC, web rendering, keyset paging) lives in the package's
 `rest`, `mcp`, `web`, `paging` and `validation` kernel modules, so a runtime fix
 ships as a package update instead of a regeneration.
 
+Procedure surface selection follows the [HTTP/MCP pairing default and deliberate asymmetry exception](trigger.md); no surface is implied.
+
 The generated `validation/views/<name>.ts` and
 `validation/procedures/<name>.ts` export `validate(unknown)`. View validators
 also export `query(URLSearchParams)` returning `{ input, limit?, cursor? }`.
@@ -219,7 +221,9 @@ must also mount Better Auth's `/.well-known/oauth-protected-resource/mcp`
 metadata route. Auth challenges point to that route. Presented bearer credentials
 need the `mcp` scope; cookie sessions use the same-origin mutation checks.
 
-Generation emits `mcp.ts` only for a non-internal View or MCP Trigger. These
+Generation emits `mcp.ts` only for a non-internal View or MCP Trigger. Omitting
+MCP remains a deliberate asymmetric choice; an HTTP-only Procedure still generates
+successfully with the warning described in [Trigger](trigger.md). These
 surfaces typecheck without the optional `@modelcontextprotocol/server` peer;
 install the exact version declared in the installed SDK's `peerDependencies`.
 The peer loads by dynamic import on the first matching `/mcp` request; if
@@ -229,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.
@@ -348,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/trigger.md

@@ -24,12 +24,21 @@ metadata: { name: close-ticket-http }
 spec:
   source: { kind: http, method: POST, path: '/api/tickets/{id}/close' }
   target: { procedure: close-ticket }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: close-ticket-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: close-ticket }
 ```
 
 The target names a declared Procedure. `http` sources use POST/PUT/PATCH/DELETE and an `/api/` path. Path parameters bind to corresponding declared input fields and override JSON-body values. The generated REST module retains the Procedure's authorization and validates boundary input.
 
 An MCP source is `{ kind: mcp, surface: public }` or admin. The selected MCP module exposes the Procedure as a snake-case tool with its description, [tool hints](procedure.md#mcp-tool-hints) and requires checks.
 
+By default, pair every HTTP Trigger with an MCP Trigger so the same operation is reachable by the user's AI. `mantle generate` warns when a Procedure has HTTP exposure but no MCP exposure, suggesting `surface: admin` for an admin-only Procedure and `public` otherwise. Triggers still decide every Procedure surface: intentional asymmetric exposure is allowed and generation succeeds.
+
 Lifecycle and schedule sources are rejected at generation with `GENERATE_UNSUPPORTED`, including disabled schedules. Use an app-owned handler or scheduler. For signed webhooks, verify the original raw Request in the app and call a generated Procedure with validated input; do not route it through a JSON boundary before signature verification.
 
 ## Input rules

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.8
+## 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.8`, 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.8/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

@@ -12,13 +12,27 @@ description: Generation targets, CLI options and ownership of native application
 | `wrangler.jsonc` | App configuration; generator maintains selected split-build keys |
 | `dist/` | Disposable bundle output (`dist/worker`, `dist/client`); do not commit |
 
+## Accept user-facing work
+
+Before reporting any user-facing deliverable as done, run the installed
+version's [independent acceptance
+flow](../guides/agent-workflow-acceptance.md) with a fresh agent on the surface
+its user uses. For MCP work, also run that guide's design audit before choosing
+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 |
@@ -37,7 +51,7 @@ Other handles may adapt to the same [structural driver contracts](../guides/adap
 | `--wrangler <path>` | Existing JSONC/JSON/TOML config; default finds one or creates `wrangler.jsonc`. TOML receives manual-edit instructions. |
 | `--entry <path>` | Worker source entry; default `src/worker.ts`. |
 | `--outdir <path>` | Bundle output; default `dist`. The Worker goes to `<outdir>/worker`. Keep separate from source/generated files. |
-| `--assets <path>` | With `--admin`: the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`); default `<outdir>/client`. Written to Wrangler's `assets.directory`, and to the build command when not the default. |
+| `--assets <path>` | With `--admin`: the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`); default `<outdir>/client`. Written to Wrangler's `assets.directory`, and to the build command when not the default. New assets blocks default to `ASSETS`, Worker-first routing and no HTML rewriting; existing blocks keep their binding/routing. |
 
 ## Outputs
 

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

@@ -1,6 +1,6 @@
 ---
 name: develop
-description: Work on an existing Mantle 0.2 project — manifests, SQL Views and Procedures, ref handlers, the service entry, surfaces, identity and MCP — using the installed package's contract.
+description: Work on an existing Mantle 0.2 project — manifests, SQL Views and Procedures, ref handlers, the service entry, surfaces, identity, MCP tool design and independent acceptance — using the installed package's contract.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/develop/SKILL.md
@@ -12,28 +12,49 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
-
-Use the native Store/query/surface entries and app-owned fetch from the service composition guide.
+Use the native Store/query/surface entries and app-owned fetch from the [service
+composition guide](../../handbook/cloudflare/service-entry.md).
+Pair every HTTP Trigger with an MCP Trigger by default; see [Trigger](../../handbook/reference/trigger.md)
+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 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).
-Select `--admin` / `admin: true`; mount `entries(bindings.schemas, bindings.adapter)`
-from the optional Admin package. Keep one Core SDK, the Admin product and shared
-UI kit at matching versions. Generate → typecheck → implement listed handlers →
-typecheck. Ref handlers retain caller-bound `ctx.store`; generic Admin reads
-use shared generated View templates and writes use native Procedure fragments.
+For native Admin, read the [current guide](../../handbook/guides/native-admin.md):
+the app builds Admin with `mantle bundle`. To customise pages, slots, hooks or
+MCP-host-safe components, follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin).
+Keep matching SDK, Admin and UI versions. Ref handlers retain caller-bound
+`ctx.store`; generic Admin reads use shared generated View templates and writes
+use native Procedure fragments.
 Check actual member/Admin OTP, private scope/TTL/translation visibility, paging,
 statistics, safe/exact OCC and no automatic retry after unknown 503 outcomes.
 
+For application-owned MCP App entries and host checks, follow the [MCP Apps
+guide](../../handbook/guides/mcp-apps.md).
+
+Build a custom frontend with `App` from `@modelcontextprotocol/ext-apps`: register
+`ontoolinput`/`ontoolresult` before `connect()`, and use `callServerTool` for
+host-proxied calls. Keep protocol negotiation and message routing in the official
+client; importing its types while writing a second `postMessage` bridge is
+insufficient.
+
+For Admin UI upgrades, follow the installed handbook's
+[retained-page recipe](../../handbook/guides/mcp-apps.md#keep-old-conversations-working-after-an-upgrade).
+Keep deployed snapshots in source/artifact storage and pass `previous` to
+`adminMcpApps`; verify old conversations after a changed UI build without host
+tool refresh, reconnection or cache clearing. Keep tool contracts compatible
+through the declared retention window.
+
 
 Place admin MCP Procedures in Admin deliberately: `spec.uiSchema.collectionAction:
 <schema-name>` adds a collection-header action; `spec.target: { schema, id,
@@ -51,10 +72,17 @@ The runtime never creates, alters or checks tables. Boot and requests run no DDL
 
 For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code. Cloud executes migrations at deploy time.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code.
 
 Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
 ## Data paths
 
 Writes use Store `insert` / `update` / `delete`, `batch`, `transaction`, or declared Procedures. Never use raw SQL writes: they bypass scope, TTL, publishing and system-column rules. For reads beyond an id lookup or simple AND filter (joins, aggregates, OR, reuse), declare an internal View so the SQL is reviewable and typed. Store `findById`, `find` and `first` remain suitable for handler lookups and embedding in an existing app. Ref handlers receive `ctx.store` bound to the same Caller and transaction.
+
+For simple creates/partial updates, prefer Store-backed ref Procedures; keep
+Procedure `requires`/generated input checks, use only allowed patch fields and
+return safe business fields with the actual returned ID/version. Preserve
+omitted fields and document null semantics. Retain SQL for atomic conditional
+or related writes; D1 batches cannot consume an earlier result. Follow the
+[Store write guidance](../../handbook/guides/typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).

package/docs/skills/integrate/SKILL.md

@@ -12,13 +12,8 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
-
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
 Keep the application router, database/pool, identity and frontend. Replace
 Core consumers explicitly and compose only selected generated entries. Resolve
@@ -30,8 +25,8 @@ the configured OAuth resource row (see [OAuth](../../handbook/guides/oauth.md)).
 Verify cutover with actual app tests.
 
 Preserve the app router, verified identity and native resources. For selected
-Admin use the [native guide](../../handbook/guides/native-admin.md): three matching
-packages, generated checks and `entries(bindings.schemas, bindings.adapter)`.
+Admin, follow the [native guide](../../handbook/guides/native-admin.md) for its
+application-built bundle and service composition.
 Do not import old `/spec`, `/core` or runtime surface APIs. Review data/role
 migrations explicitly; full cross-target int64 parity and automated transfer
 are not this release's upgrade contract.

package/docs/skills/provision/SKILL.md

@@ -13,13 +13,8 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
-
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
 Deploy/create resources only within the user's authorization; reuse configured
 host resources. Apply reviewed and rehearsed migrations before routing traffic;
@@ -30,12 +25,20 @@ as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#wo
 Keep the Workers [public-fetch flags](../../handbook/cloudflare/deploy-and-operate.md#public-fetch-routing),
 including environment overrides; verify deployed MCP with a real OAuth bearer
 (`initialize` and `tools/list`), not only a browser session cookie.
+For MCP Apps, also follow [deployed host acceptance](../../handbook/guides/mcp-apps.md#verify-a-deployed-app-in-chatgpt):
+compare the current resource URI and visibly verify a newly invoked render tool.
+Archive deployed Admin pages using the guide's `previous` recipe and carry them
+through clean builds. Test the same old conversation after changing the UI build,
+without reconnecting, refreshing host tools or clearing caches. A deliberate tool
+contract change has its own migration/host rediscovery step. OAuth renewal, `tools/call` success and a
+local official-host replay do not establish that the deployed App rendered.
 Bun uses native Database/SQL, an app server and scheduler. Verify admin sign-in
 (role admin), denied access, public reads, a persisted write, MCP and selected UI.
 Report artifact/resources/checks and keep rollback artifacts.
 
-Use the installed [Native Admin](../../handbook/guides/native-admin.md) asset
-contract and `entries(bindings.schemas, bindings.adapter)`. Admin SPA assets
-belong to `@aotter/mantle-admin`, while UI supplies the shared kit. Verify both
-member and admin OTP/UI flows. Deployment of an authorized application does
-not authorize SDK publication; a workspace preview remains a preview.
+For ChatGPT Sites, follow [Mantle on ChatGPT Sites](../../handbook/cloudflare/chatgpt-sites.md).
+
+The app builds Admin with `mantle bundle`; serve it as [Native
+Admin](../../handbook/guides/native-admin.md) describes. Verify both member and
+admin OTP/UI flows. Deployment of an authorized application does not authorize
+SDK publication; a workspace preview remains a preview.

package/docs/skills/update/SKILL.md

@@ -12,24 +12,27 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
+For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md): give the
+0.2 service a new database and move data by export and import; never boot 0.2
+against a 0.1.x database. Between 0.2 versions, apply reviewed migrations
+rehearsed on a copy.
 
-Pin exact target SDK/peer versions and read its release notes and Admin asset
-installation instructions. Core-to-native replaces app imports/wiring; it is not
-a package-only update. Preserve users, sessions, content and application code.
-Review emitted SQL/policy diffs and rehearse explicit data-preserving schema/auth/role
-migrations on a copy. Initial schema.sql never authorizes rebuilding production
-tables. Verify auth/Admin/MCP/REST, locks and persistence before authorized cutover.
+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.
 
-Follow [Native Admin](../../handbook/guides/native-admin.md) for the three-package
-SDK/Admin/shared-kit split and asset/extension/MCP App subpath moves; old UI
-subpaths have no compatibility aliases. Pin only actually published versions,
-or explicitly use a matching workspace preview. Recheck member and Admin OTP,
-all affected native routes, private field visibility, OCC and unknown outcomes.
-Do not publish a package as part of an application dependency update.
+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
+and application code; review emitted SQL/policy diffs and rehearse explicit
+data-preserving schema/auth/role migrations on a copy. Initial schema.sql never
+authorizes rebuilding production tables. Verify auth/Admin/MCP/REST, locks and
+persistence before authorized cutover.
+
+Follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin)
+for the current application-built Admin; old UI subpaths have no compatibility
+aliases. Pin only actually published versions, or explicitly use a matching
+workspace preview. Recheck member and Admin OTP, all affected native routes,
+private field visibility, OCC and unknown outcomes. Do not publish a package as
+part of an application dependency update.