@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/adr/0037-postgresql-is-the-reference-dialect.md

@@ -0,0 +1,124 @@
+# ADR-0037: PostgreSQL is the reference dialect; D1 runs a subset
+
+**Status:** Accepted for 0.2.0. Amends ADR-0034 decisions 2 and 8 and ADR-0035 decisions 1, 4 and 6, and replaces the
+PostgreSQL dialect amendment's "What it accepts".
+
+**Date:** 2026-10-02
+
+**Related:** ADR-0014 (Cloud and tenants), ADR-0034, ADR-0035, ADR-0036, #1293
+
+## Context
+
+ADR-0035 decision 1 made Mantle SQL PostgreSQL's syntax and meaning, and said a PostgreSQL dialect "can accept nearly all of
+PostgreSQL". The PostgreSQL dialect shipped as D1's subset less SQLite's functions, so a PostgreSQL manifest also compiled for
+D1. That kept engines interchangeable, but it held services that chose PostgreSQL to SQLite's limits: no `WITH`, no window
+frames, no `FILTER`, no jsonb operators. A View that needed one rule in many places (a plan's visible window, for example)
+had to repeat it.
+
+Services that pick PostgreSQL pick it for good (Swolhalla runs on PostgreSQL from day one). The subset should be D1's
+limitation, not every dialect's.
+
+Two kinds of author write Mantle SQL, and the allowlist means something different to each:
+- **A self-hosted service** (enterprise, Swolhalla): the author also operates the database and can reach it directly. The
+  allowlist does not stop malice there; it stops mistakes, above all SQL (often written by an AI) that would read another
+  member's rows.
+- **Mantle Cloud:** tenants are third parties. Today each tenant has its own D1 and its own Workers for Platforms script, and
+  the tenant's `ref` handlers run in that script with the raw `DB` binding (aotter/mantle-home `apps/control/src/deploy/provider.ts`).
+  Isolation between tenants is the separate database, not the allowlist. A PostgreSQL cell shared by thousands of tenants
+  behind one Hyperdrive config (one connection string, one role) cannot isolate tenants that way.
+
+## Decision
+
+### 1. One reference allowlist, PostgreSQL's
+
+- Mantle SQL's allowlist lives in Core (`src/core/sql/allowlist.ts`): the walker and two profiles, **base** (what every
+  dialect runs, ADR-0034's subset) and **reference** (base plus decision 2). The PostgreSQL dialect accepts the reference
+  profile. The D1 dialect accepts base.
+- A construct D1 refuses but the reference accepts is refused with the reason "needs the PostgreSQL dialect", so an author
+  knows it is an engine limit, not a mistake.
+- The allowlist stays closed on every dialect. "PostgreSQL first" means a larger closed list, never "anything PostgreSQL
+  parses": PostgreSQL's catalog has thousands of functions, and one that runs SQL text (`query_to_xml`) or reads files
+  bypasses every policy.
+- Each construct added to the reference profile lands with: the walker's rule, the policy rewriter's handling (a new relation
+  position has a probe in the compliance suite, ADR-0034 decision 8), a compliance case on PostgreSQL, and a D1 refusal test.
+
+### 2. The reference profile, first wave
+
+| Construct | Rule |
+|---|---|
+| `WITH` and `WITH RECURSIVE` | Every CTE body is a `SELECT`. A data-modifying CTE (`WITH x AS (DELETE …)`) is refused. Each Schema read inside a body is wrapped like any other (relation position `cte`); a reference to the CTE is not. A reference is a CTE only by PostgreSQL's scope (a body sees its earlier siblings, every sibling under `RECURSIVE`); the allowlist and the rewriter both check that scope at runtime, because a `cte` tag on any other name would make PostgreSQL read the table, or the catalog view, of that name unwrapped. |
+| `UNION`, `UNION ALL`, `INTERSECT`, `EXCEPT` | Inside a CTE body or a subquery only, never a View's own top-level `SELECT`, because Core's paging and deterministic order act on that `SELECT`. Each branch is wrapped (position `setop`). |
+| `DISTINCT ON` | Inside a CTE body or a subquery only, for the same reason: Core's paging rewrites the top-level order, which decides which row `DISTINCT ON` keeps. |
+| `LATERAL` subqueries | `JOIN LATERAL (…) x ON …` or `, LATERAL (…) x`. The subquery is wrapped as any FROM subquery. |
+| Window frames | `ROWS` and `RANGE` with literal offsets; functions `avg`, `min`, `max`, `lag`, `lead`, `first_value`, `last_value` and `dense_rank` gain `OVER`. |
+| Aggregates | `FILTER (WHERE …)`, `ORDER BY` inside an aggregate, `string_agg`. |
+| jsonb | Operators `->`, `#>`, `#>>`, `@>`, `<@`, `?`, `?|`, `?&`; `jsonb_build_object`, `jsonb_build_array`, `jsonb_strip_nulls`, `jsonb_agg`, `jsonb_object_agg`, `to_jsonb`, `jsonb_typeof`; casts to `jsonb`. |
+| Text | `ILIKE`, `NOT ILIKE`, and the regular-expression operators `~`, `~*`, `!~`, `!~*`; `split_part`. |
+| Numbers | `greatest`, `least`, `floor`, `ceil`, `sqrt`, `power`. |
+| Time | `AT TIME ZONE`; `date_trunc` adds `minute` and `quarter`; `extract` adds `minute`, `quarter`, `week`, `isoyear`, `isodow`, `doy` and `epoch`. |
+| Casts | A cast of any expression to `int4`, `int8`, `numeric(p, s)`, `date` or `timestamptz` (D1 keeps its literal-only rule, which exists because SQLite truncates and stores time as integers). A bare text literal compared with a date-time, date or boolean column is PostgreSQL's cast, so the D1 refusal of it does not apply. |
+
+Still refused everywhere: data-modifying CTEs, set-returning functions in FROM other than `json_each`, `generate_series`,
+`FOR UPDATE`, `OFFSET`, `RIGHT` and `FULL` joins, and every function in ADR-0035 decision 4's list. Each needs its own
+amendment.
+
+### 3. A View may read another View
+
+- A View's or a Procedure's `FROM` may name an **internal** View (`surface: internal`) that declares no `input` and no `requires`, by its name
+  with `-` written `_` (`free-window` is `free_window`). A Schema of the same name keeps it: the name reads the Schema.
+- The compiler inlines the referenced View's compiled `SELECT` as a `FROM` subquery before the dialect sees the tree. Policy
+  and every check then apply to it as to any subquery. Nothing reaches the runtime that a hand-written subquery could not.
+- References are resolved in dependency order; a cycle is a compile error.
+- On every dialect. This is how a rule used by many Views is written once.
+
+### 4. A narrowing hook
+
+- `postgresStorage` and `sqliteStorage` take `restrict?: (plan, context) => readonly SqlDiagnostic[]`. Core runs it on every
+  program's IR after the dialect's own check, at runtime (ADR-0035: the runtime never trusts an IR). It can only refuse.
+- It is for an operator that runs other people's plans. A self-hosted service does not set it.
+
+### 5. Every PostgreSQL transaction has a statement timeout
+
+- The PostgreSQL driver pins `statement_timeout` with `SET LOCAL` in every transaction, as it pins `DateStyle` and `TimeZone`:
+  10 seconds unless `postgresStorage({ statementTimeoutMs })` says otherwise. A recursive CTE or a regular expression that runs
+  away ends there.
+- A database role used by Mantle is not a superuser and holds no file or server privilege (`pg_read_server_files`,
+  `pg_execute_server_program`). The handbook says so; Mantle does not check.
+
+### 6. Mantle Cloud's boundary
+
+- **D1 (today):** the tenant's database is the isolation unit, so the tenant's code may hold its binding, as it does.
+- **PostgreSQL (when Cloud adds it):** the cell's connection never enters a tenant script. The platform owns the Hyperdrive
+  binding and runs a Store service the tenant script calls (as it calls `MAIL` and `MEDIA`). The service validates every IR
+  with the dialect, then a Cloud `restrict` profile, then the policy rewriter, and runs each transaction as the tenant with
+  `SET LOCAL ROLE` and the tenant's `search_path`. The cell role is a member of every tenant role; a tenant role holds only its
+  schema. The allowlist is then a real boundary, and PostgreSQL's privileges are the second one.
+- The Cloud profile and the Store service are aotter/mantle-home's to build; Core provides decision 4.
+
+## Consequences
+
+- A PostgreSQL manifest may no longer compile for D1. Moving from PostgreSQL to D1 can need a rewrite; moving from D1 to
+  PostgreSQL still needs none.
+- The reference profile grows by amendment, one construct at a time, each with its probe.
+- Swolhalla's free-plan window is one internal View every other View reads.
+
+## Alternatives
+
+- **Accept everything PostgreSQL parses and deny a list of dangerous functions.** A denylist is never complete: an extension,
+  a new catalog function or a server upgrade adds one. Rejected.
+- **A Schema-level visibility predicate** (a second `scope`, injected by the rewriter). It solves the repeated window, but only
+  for row filters; View references solve it and every other shared rule.
+- **Native row-level security on PostgreSQL** (ADR-0035 decision 3's `policy: "native"`). The right second layer for Cloud
+  (decision 6); a larger change than this ADR needs.
+
+## Conformance cases
+
+1. Each decision 2 construct gives PostgreSQL's result on the PostgreSQL dialect, and D1 refuses it with "needs the
+   PostgreSQL dialect".
+2. The relation-position probe covers `cte` and `setop`, and a Schema read inside a recursive CTE, a `UNION` branch and a
+   `LATERAL` subquery never shows another owner's rows. An IR whose `cte` tag names a relation outside PostgreSQL's CTE
+   scope (the CTE's own body, a later sibling, a catalog view) is refused at runtime.
+3. A View's top-level `UNION` or `DISTINCT ON`, and a data-modifying CTE, are refused with a position.
+4. A View reads an internal View; the reference to a View with an input, a public View or a cycle is refused.
+5. A `restrict` that refuses a program stops it at runtime with its diagnostic.
+6. A statement past `statement_timeout` fails with `RESOURCE_UNAVAILABLE`, and nothing is written.

package/docs/adr/0038-bun-native-host.md

@@ -0,0 +1,63 @@
+# ADR-0038: Bun is a native host
+
+**Status:** Accepted for 0.2.0. Amends ADR-0036's reserved Bun host.
+
+## Decision
+
+`@aotter/mantle/bun` owns native drivers and Admin files. Core remains host-neutral;
+PostgreSQL retains policy, convergence, SQL printing, SERIALIZABLE retries, timeout
+and error mapping. `host: bun` defaults to `dialect: postgres` on first selection.
+The CLI writes an application-owned Bun.serve entry and service once. Both native
+PostgreSQL and bun:sqlite presets exist; neither imports Cloudflare or pg.
+
+The PostgreSQL host takes a Bun.SQL pool configured with `prepare: false`.
+Bun's prepared JSON parameter encoding serializes an already encoded JSON string
+again. Refuse another configuration rather than silently changing stored values.
+Pool reserve/release binds every operation to one connection. The host closes
+its pool after the server and retained background work stop.
+
+Bun exposes raw results without OIDs/typmods. Obtain exact result metadata from
+`CREATE TEMP TABLE ... AS <query> WITH NO DATA`, read pg_attribute and drop the
+temporary table, then execute the original statement once with raw text results.
+A DML description is a data-modifying CTE under WITH NO DATA, which does not
+execute its body. PostgreSQL owns all type inference, including numeric scale,
+CASE, COALESCE and CTEs. Each descriptor runs in the statement's existing pinned
+transaction. Views use a regular transaction because temporary DDL is forbidden
+in READ ONLY: a read describes first, then runs `SET TRANSACTION READ ONLY` before
+the statement, so the engine still refuses a write as it does on every other
+PostgreSQL host. Creating the temporary table needs the TEMPORARY privilege on the
+database (`GRANT TEMPORARY ON DATABASE ... TO <role>`); without it every read fails
+with 42501 naming this requirement, and a read replica cannot serve this host.
+Every transaction appends `pg_temp` to its search_path, on every PostgreSQL host,
+so a temporary table on a pooled session never stands in for a Schema table (unless
+the role's own search_path already names pg_temp earlier, which it should not).
+A connection whose ROLLBACK failed is closed, never released to the pool.
+This costs three metadata round trips per result. Replace it only when Bun
+provides public RowDescription metadata; do not approximate money or time values.
+
+The entry overwrites the trusted IP header from the socket; behind a reverse proxy
+listed in TRUSTED_PROXIES, the client is the address that proxy appended last to
+X-Forwarded-For (one trusted hop; an IPv4-mapped socket address is matched as
+IPv4), so each client keeps its own sign-in rate limit. Bun.serve runs
+with `development: false` and an error handler that answers Core's 500 envelope: Bun's
+development page would show the exception, stack and paths. Admin assets reject
+traversal, control characters and symlinks outside the installed bundle.
+bun:sqlite runs with foreign keys on, as D1 does, and a Mantle batch waits for a
+Better Auth transaction open on the same handle instead of becoming its savepoint.
+Local OTP requires an explicit loopback PUBLIC_ORIGIN, a secret and bootstrap
+email, as Cloudflare does.
+
+Bun has no built-in cron scheduler in this preset. Enabled schedule Triggers are
+refused before files are written; an application that supplies a scheduler uses
+host none and invokes Mantle's schedule ingress explicitly. No polling scheduler,
+workflow engine or new manifest grammar is introduced.
+
+## Verification
+
+Native PostgreSQL and SQLite run the same storage conformance suite. Native
+regressions cover result names, JSON scalar/array values, exact numeric typmods,
+microsecond timestamps, CTE/comment queries, star targets, connection
+reservation, read-only reads, statement_timeout, pg_temp ordering, foreign keys,
+transactions on a shared bun:sqlite handle and actual Better Auth
+OTP/bootstrap-owner login on both engines. Both generated presets typecheck
+against bun-types. CI installs pinned Bun and runs these on every PR.

package/docs/adr/README.md

@@ -2,7 +2,7 @@
 
 Records of *why* mantle ended up shaped this way. The numbering preserves POC ADR numbers where carried over (so cross-references in code comments and external docs stay valid); new ADRs continue from the highest used number.
 
-## v0.1.0 ADRs
+## ADRs
 
 | # | Title | Status |
 |---|---|---|
@@ -12,19 +12,33 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0008](0008-structured-diagnostic-shape.md) | Diagnostic shape for validate/boot/runtime failures, with a reserved consumer-test phase; measured harnesses keep purpose-shaped reports. | Accepted + amended |
 | [0009](0009-consumer-supplied-manifests.md) | Historical generated-array workflow; consumer source ownership continues in ADR-0019. | Superseded by 0019 |
 | [0010](0010-locale-and-translates.md) | Locale 3-layer (manifest / D1 site_config / data field) + translates pattern. Boot decoupled from `site_config` (issue #60 fix). | Accepted (refreshed) |
-| [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. | Accepted (new) |
+| [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. | Superseded by 0019 (Core storage, Admin composition) and 0024 (SQLite/D1 storage); retained as the alpha.7 Cloudflare adapter record |
 | [0012](0012-views-as-public-rest.md) | Views auto-expose matching REST and `query_view_*` MCP reads on their declared `public` or `staff` surface. Schemas never get a public REST endpoint. | Accepted + amended |
 | [0013](0013-agent-provisioned-consumer-projects.md) | Historical agent-provisioned consumer projects path. | Superseded by 0021 |
-| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one Better Auth 1.7 identity/OAuth/MCP authority with native method options and CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
+| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one Better Auth 1.7 identity/OAuth/MCP authority with native method options and CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended; auth ownership amended by 0032 |
 | [0016](0016-site-semantic-layer.md) | Historical Starter/Landing `AGENTS.md` and launch-state contract. | Superseded by 0021 |
 | [0017](0017-media-multi-variant-agent-side-optimization.md) | Multi-variant media assets with agent-side optimization and asset-id entry references. | Accepted |
 | [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |
-| [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted |
+| [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted; optional boundaries become subpaths of two packages per 0032 |
 | [0020](0020-builtin-handler-contracts-and-matched-upsert.md) | Static builtin handler contracts and natural-key matched upsert (`handler.match`). | Accepted + amended by 0022 |
-| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; supersedes 0018 |
-| [0022](0022-caller-observed-version-occ.md) | Caller-observed `expectedVersion` for Admin bind and builtin upsert OCC. | Accepted |
-| [0024](0024-manifest-native-schema-tables.md) | Materialize each Schema as a native storage table and deploy reviewed migration artifacts. | Accepted; authored-native-name clauses superseded by 0025 |
+| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; no-initialization clause superseded by 0026 |
+| [0022](0022-caller-observed-version-occ.md) | Caller-observed `expectedVersion` for Admin bind and builtin upsert OCC. | Accepted; Admin binding rules superseded by 0029 |
+| [0023](0023-port-failure-contract.md) | Storage and service failure contracts: resource, rate, outcome-unknown, partial-failure and precondition diagnostics with safe `failure` facts. | Accepted for alpha.17 (#857); amends 0008 |
+| [0024](0024-manifest-native-schema-tables.md) | Materialize each Schema as a native storage table and deploy reviewed migration artifacts. | Accepted; authored-native-name clauses superseded by 0025; migration workflow superseded by 0033 |
 | [0025](0025-reserved-native-columns-and-published-only-public-views.md) | Reserve the six native column names, let `indexes` reference them, and compile public publishing Views published-only. | Accepted |
+| [0026](0026-progressive-generate.md) | Progressive `mantle generate` with a full default, positive features, saved host selection, and user-owned source. | Accepted; supersedes part of 0021; dependency closure, identity and `--host` amended by 0032 |
+| [0027](0027-scheduled-procedure-triggers.md) | Schedule Triggers in the sealed plan with Cloudflare-hosted invocation and system identity. | Accepted for 0.1.5; cron dialect and host requirement amended by 0032 |
+| [0028](0028-schema-ttl-expiry.md) | Logical TTL on Schema reads with preview-first, explicit bounded cleanup. | Accepted for 0.1.5 |
+| [0029](0029-mcp-apps-interaction-contracts.md) | Official MCP SDK for all MCP wire handling; transport-neutral capability catalog with validate-once invocation; `@aotter/mantle-mcp` and `@aotter/mantle-ui`; Manifest-declared interaction contracts and MCP Apps (#1110). | Accepted; amends ADR-lite 909 |
+| [0030](0030-store.md) | Store: one persistence object (`ctx.store` / `runtime.store`) over one relational JSON query AST compiled by each adapter; first slice `select`, `view`, `id`, then `write`, then manifest grammar (#1151). | Accepted; completed for 0.2.0 by 0032; authoring amended by 0034 |
+| [0031](0031-host-cloud-core-contract.md) | Cloud supplies the Core pin before host artifact hashing; protocol 2 checks the same pin through grants and the frontend kit. | Accepted |
+| [0032](0032-store-centric-core-and-service-contract.md) | 0.2.0: Store is the only entry persistence path; an application-owned service behind one host-neutral `createMantle`; one `Caller` identity and no Core-owned user or auth; `_mantle_` marks system tables only; two npm packages and one plugin. | Accepted for 0.2.0; decisions 1–5, 10 and 13 amended by 0034; decisions 6 and 12 by 0035 |
+| [0033](0033-storage-converges-to-the-plan.md) | Schema storage converges to the plan by introspection: Mantle applies safe additions, blocks the rest, and verifies author-made changes; no Mantle-written migration files. | Accepted for 0.2.0; amended by 0034 and 0035 |
+| [0034](0034-store-is-authored-as-sql.md) | Store is authored as SQL in the D1 dialect and compiled to IR by the CLI with `libpg-query`; no Worker parses SQL. The IR is the parser's AST under an exact allowlist, printed by `pgsql-deparser`; a chosen SQL subset with policy wrapped around every Schema reference; FTS5 search and R*Tree places; after hooks take row arrays; one SQLite executor; exact encodings for time and decimals. | Accepted for 0.2.0 (spike #1203); amended by 0035 and 0037 |
+| [0035](0035-sql-dialects.md) | Mantle SQL is PostgreSQL syntax and meaning; a dialect module runs it on one engine. D1 and PostgreSQL ship built in, and both pass the compliance suite. | Accepted for 0.2.0; amended by the PostgreSQL dialect (#1293), 0036 and 0037 |
+| [0036](0036-host-and-dialect.md) | A project picks a host (`cloudflare`, `none`) and a dialect (`sqlite`, `postgres`, a package) once; `mantle generate` writes the pair's preset; the host never enters the plan. | Accepted for 0.2.0; reserved Bun host amended by 0038 |
+| [0037](0037-postgresql-is-the-reference-dialect.md) | PostgreSQL is the reference dialect: one closed allowlist in Core (base and reference profiles), D1 runs the base subset; a View reads an internal View; `restrict` narrows at runtime; a statement timeout on PostgreSQL; Cloud's PostgreSQL connection stays with the platform. | Accepted for 0.2.0 |
+| [0038](0038-bun-native-host.md) | Bun is a native host: `@aotter/mantle/bun` owns the native SQLite and PostgreSQL drivers and Admin files; `host: bun` defaults to `dialect: postgres`; the CLI writes a `Bun.serve` entry once. | Accepted for 0.2.0 |
 
 ## Reading order
 
@@ -36,7 +50,7 @@ If you're new to the codebase:
 4. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
 5. **0011** — the boundary between the runtime and the adapter.
 6. **0010** — how locale flows through the system.
-7. **0021** — current direct-authoring boundary; **0013** is historical install-session context.
+7. **0026** — current progressive generation boundary; **0021** retains the direct-authoring history and **0013** is historical install-session context.
 8. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
 
 ## What's NOT here (and why)
@@ -76,3 +90,7 @@ These retain their issue-based filenames and original decision status.
 | [#809 Bounded public content](adr-lite-809-bounded-public-content.md) | Implemented |
 | [#812 Native parity](adr-lite-812-native-parity.md) | Implemented; deployment evidence linked in record |
 | [#823 Home statistics](adr-lite-823-home-statistics.md) | Proposed; unmerged demo |
+| [#842 MCP authoring](adr-lite-842-mcp-authoring.md) | Accepted |
+| [#845 Frontend client](adr-lite-845-frontend-client.md) | Accepted |
+| [#861 Admin WebMCP](adr-lite-861-admin-webmcp.md) | Accepted |
+| [909 Admin UI kit](adr-lite-909-admin-ui-kit.md) | Accepted; amended by 0029 |

package/docs/adr/adr-lite-861-admin-webmcp.md

@@ -2,6 +2,12 @@
 
 Status: Accepted for implementation following maintainer approval.
 
+> **Amendment (0.2.0):** Admin answers no MCP. `POST /admin/api/mcp` is
+> removed; the browser calls a staff tool with `POST /admin/api/webmcp/<tool>`
+> and its input as JSON, which Admin runs as the staff MCP surface does, with
+> the session. The catalog is still the staff MCP surface's; an MCP client
+> with a token uses `/mcp/staff`.
+
 Admin WebMCP uses the canonical staff MCP catalog and JSON-RPC dispatcher.
 `GET /admin/api/webmcp` supplies the same tool definitions plus UI route hints;
 `POST /admin/api/mcp` carries MCP requests using the current Admin session.

package/docs/adr/adr-lite-909-admin-ui-kit.md

@@ -1,6 +1,6 @@
 # ADR-lite 909: Mantle Admin UI kit export
 
-**Status:** Accepted
+**Status:** Accepted; amended by [ADR-0029](0029-mcp-apps-interaction-contracts.md) (the kit moves to `@aotter/mantle-ui`, with a one-minor re-export from `@aotter/mantle-admin-ui/kit`)
 
 ## Context
 

package/docs/examples/README.md

@@ -1,22 +1,20 @@
 # Examples hub
 
-This folder is the only official examples tree. Filenames carry the handler class. There is no second Manifest body under `docs/handbook/examples/` — those pages redirect here.
+Every page is a whole service in the 0.2.0 grammar: its manifests compile with
+`mantle generate` (the SDK repository compiles each one in its checks). Copy the shape you need into
+your project's `manifests/`; none is a template to copy wholesale.
 
-**Builder** may ingest a Manifest only when every Procedure is `handler.kind: builtin` (or the example has no Procedures). That is the `builtin-*` prefix. `cf-primitives-*` documents Durable Objects, Queues, cron, R2, and/or `handler.kind: ref`. `host-*` directories are runnable consumer projects, not business presets.
+| Example | What it shows | Handler code |
+|---|---|---|
+| [`reference-service/`](./reference-service/README.md) | A runnable service with its smoke test: scoped orders, SQL Views and Procedures, hooks, a cron, REST, both MCP surfaces, Admin's API and console email-OTP sign-in. The release gate runs it. | yes |
+| [Intake form](./intake.md) | An anonymous form: one SQL `INSERT` and a staff View. | none |
+| [Intake with bot check and notification](./intake-hooks.md) | A Turnstile check as the Procedure's guard, an email from an after hook. | 2 handlers |
+| [Reservation requests](./reservation.md) | A request queue with a Schema `check`. | none |
+| [Publication](./publication.md) | Localized posts with a parent identity, per-locale lists and `mantle.search`. | none |
+| [Legal documents and consent](./legal-documents.md) | Immutable revisions, and an acceptance written only for a published revision. | none |
+| [Procurement approvals](./procurement.md) | Members see their own rows through `auth.uid()`; staff review with an optimistic lock. | none |
+| [Commerce catalog and orders](./commerce.md) | A published catalog, guest orders and a locked staff review. | none |
+| [Commerce inventory](./commerce-inventory.md) | Server-side pricing, atomic stock reservation with `checks` and locks, a scheduled expiry and a verified payment callback. | 3 handlers |
+| [Guarded API access](./guarded-api.md) | API keys through a custom `CallerResolver`, scopes and a live entitlement guard. | 2 handlers |
 
-Drop a `builtin-*` YAML block into `host-local-admin-otp/manifests/` (or `host-minimal-worker/manifests/`) and run `mantle validate`.
-
-| Id / filename | Meaning | Class | Builder | Admin | Related host |
-|---|---|---|---|---|---|
-| [`builtin-intake.md`](./builtin-intake.md) | Public request form; builtin create; staff list | builtin | yes | optional (staff View / Staff MCP) | `host-minimal-worker` or `host-local-admin-otp` |
-| [`builtin-reservation.md`](./builtin-reservation.md) | Public reservation queue; builtin create; staff list | builtin | yes | optional | `host-minimal-worker` or `host-local-admin-otp` |
-| [`builtin-publication.md`](./builtin-publication.md) | Localized posts, public list, reader suggestions | builtin | yes | optional (Admin or Staff MCP to draft/publish) | `host-local-admin-otp` |
-| [`builtin-procurement.md`](./builtin-procurement.md) | Member requisitions and staff approve/reject with OCC | builtin | yes | optional (Admin or Staff MCP) | `host-local-admin-otp` |
-| [`builtin-legal-documents.md`](./builtin-legal-documents.md) | Localized Terms/Privacy revisions and signed-in acceptances | builtin | yes | optional (staff create via MCP; Admin for review) | `host-local-admin-otp` |
-| [`builtin-commerce.md`](./builtin-commerce.md) | Product catalog, guest orders, staff fulfill/cancel; builtin create/update only | builtin | yes | optional (Admin or Staff MCP to publish products) | `host-local-admin-otp` |
-| [`cf-primitives-intake-hooks.md`](./cf-primitives-intake-hooks.md) | Same intake Schema with Turnstile `before_create` and email `after_create` `ref` hooks | cf-primitives | no | optional | `host-minimal-worker` plus handlers |
-| [`cf-primitives-commerce-inventory.md`](./cf-primitives-commerce-inventory.md) | Catalog plus Durable Object stock authority, Queue expiry, payment callback, `ref` handlers | cf-primitives | no | optional | `host-minimal-worker` plus DO/Queue/cron |
-| [`cf-primitives-guarded-api.md`](./cf-primitives-guarded-api.md) | API keys, scopes, live entitlement `ref` guards over REST and MCP | cf-primitives | no | none | `host-minimal-worker` plus credential resolver |
-| [`host-minimal-worker/`](./host-minimal-worker/README.md) | Executable Spec + adapter without Admin | host | no | none | itself |
-| [`host-local-admin-otp/`](./host-local-admin-otp/README.md) | Executable opt-in Admin / Dev UI with email OTP | host | no | required | itself |
-| [Mantle on ChatGPT Sites](../handbook/chatgpt-sites/index.md) · [runnable reference](./host-chatgpt-sites/README.md) | Runnable Sites D1/R2, ChatGPT identity, Admin media, published web and public read-only MCP | host | no | required | itself |
+Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).