@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/handbook/releases/index.md

@@ -1,80 +1,249 @@
 ---
-description: Every stable Mantle release — what it contains, what it requires, and what changed since the previous stable.
+description: Every Mantle release line — what 0.2.0 changes, and what each stable 0.1.x release contained.
 ---
 # Releases
 
 Mantle publishes to npm under the `@aotter/*` scope. A **stable** release is a
-plain `X.Y.Z` version on the `latest` dist-tag; it is the only kind of release
-covered by this chapter and the only kind intended for production use.
-
-```sh
-npm install @aotter/mantle
-```
-
-Prereleases exist so a stable can be prepared in the open, and they are not
-covered here: `alpha` is cut from `develop` and may break anything, `rc` is a
-stable candidate cut from `main`. Installing a prerelease means opting into an
-exact version, not a channel. [GitHub Releases](https://github.com/aotter/mantle/releases)
-is the canonical, immutable change history; this chapter is the narrative one.
-
-All eleven packages share a single version and are published together, so mixed
-versions across `@aotter/mantle*` are never a supported combination. Pin the
-version you install and upgrade the whole set at once.
-
-## 0.1.5 — in preparation
-
-`mantle generate` now assembles a blank, editable full site by default for
-Cloudflare Workers or ChatGPT Sites. `--features` positively selects a smaller
-composition; Spec-only needs no host. The first run declares exact matching
-dependencies, and a second run after installation completes the project.
-Existing directly authored applications retain their compile path. Saved
-choices and user-owned files survive reruns, while `--check` reports drift
-without writing. On Sites, review and apply append-only D1 migrations before
-running code that expects the new Schema. The new Sites worker trusts identity
-only behind the Sites dispatcher and does not expose a separate `workers.dev`
-URL.
-
-Reviewed Sites unique-index tuple replacement can now generate an immutable
-SQL migration with source/target fingerprints, checksum and an explicit report.
-Local D1 duplicate preflight fails before writing files; production D1 still
-enforces the new constraint when the reviewed migration is applied. Runtime-
-managed CF boot continues to reject uniqueness changes without a reviewed
-artifact path.
-
-The owner-only Developer Console can inspect live Schema entries and run
-declared Views on demand through guarded Admin routes. Its HTTP and MCP lists
-link to the owning declarations. UI action placement is no longer shown as a
-Procedure-to-Schema execution path; custom handlers and native SQL Views state
-when their data relationships cannot be inferred from the Manifest.
-
-Ref Procedures can now group create, update and delete operations across
-Schemas with `ctx.writeAtomically`. D1 and Bun commit the group or roll it
-back, including when the last conditional write finds a stale version. Other
-adapters must explicitly implement the optional capability before using it.
-
-Cloudflare Cron Triggers now target ordinary Procedures through `source.kind:
-schedule`. The generated runtime plan records each schedule, while Wrangler
-registration remains application-owned. Scheduled calls have no user or staff
-authority, carry a stable retry key, and pass through Procedure validation and
-authorization. D1-backed Workers retain owner-only run observations
-for 30 days; the Console distinguishes a declaration from registration and
-observed executions. Managed SQLite hosts must apply the append-only
-`0007-schedule-run-observations` migration before boot. Other hosts do not
-register schedules.
-
-Schemas may declare a `ttl` date-time policy. D1 and Bun hide expired entries
-from semantic reads and declarative Views before any deletion. Physical cleanup
-is an explicit bounded sweep, previewed by default and resumable by cursor;
-there is no automatic bulk deletion when a policy is introduced or shortened.
-Native SQL Views and shared View caches are rejected for TTL Schemas because
-they cannot guarantee the expiry boundary. Cloudflare public routes that can
-include TTL content use `no-store` so a cached page cannot outlive its entries.
-
-Agents installed through `npx skills add aotter/mantle` must still inspect the
-target project's actual SDK version. Published 0.1.4 packages do **not**
-support the new project flags; 0.1.5-alpha.1 does. Use the installed docs and
-upgrade all selected packages together. The bootstrap skill remains a small directory,
-not a repository clone.
+plain `X.Y.Z` version on the `latest` dist-tag and is the only kind intended
+for production. Prereleases (`alpha`, `rc`) let a release be prepared in the
+open; installing one means choosing an exact version, not a channel.
+[GitHub Releases](https://github.com/aotter/mantle/releases) is the canonical
+change history; this page is the narrative one.
+
+From 0.2.0-alpha.7, Mantle publishes three packages together at one version:
+`@aotter/mantle` (native SDK, compiler and CLI), `@aotter/mantle-ui` (pure UI),
+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.10
+
+Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and
+`@aotter/mantle-admin` dependency to `0.2.0-alpha.10`, 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.
+
+1. **Build output and host configuration.** `mantle bundle` writes server
+   modules to `dist/worker` and static files to `dist/client`, including
+   `dist/client/admin`. Rerun `mantle generate` with the application's `--entry`
+   and check the resulting Wrangler `main`, `base_dir`, asset directory and
+   build command. See [CLI and generated ownership](../start/project-and-cli.md).
+2. **Application-owned React.** Install React and React DOM in the application
+   at the same exact version (the examples use `19.3.0`). Admin takes them as
+   peers; a mismatched pair fails its build.
+3. **Replace extensions with application composition.** Move to
+   `defineAdmin(meta, { nav, pages, home, components, plugins, mcp })` in
+   `src/admin.tsx`. Remove `--admin-extensions`, `adminExtensions`,
+   `defineAdminExtension`, extension handlers and removed manifest widget,
+   `list.cells` and panel references. `navGroups` becomes `nav.groups`.
+   Use the [Admin migration table](../guides/native-admin.md#migrating-from-admin-extensions)
+   rather than carrying the former registration layer forward.
+4. **Build the MCP App with the application.** The prebuilt
+   `@aotter/mantle-admin/mcp-app` / `mantleAppHtml` export is gone. Use
+   `adminMcpApps({ catalogue: mcpAppCatalogues.admin })` with the generated
+   catalogue; it reads the built asset. Declare CSP once in `defineAdmin`.
+   The default resource URI hashes the built HTML, catalogue and metadata;
+   custom HTML functions need an explicit immutable URI. Load interactive
+   host HTML through authenticated `resources/read`, which embeds its
+   catalogue. See [MCP Apps](../guides/mcp-apps.md).
+5. **Run the generated compatibility check.** Run
+   `node --test generated/admin-mcp-app.check.mjs` after building. Install
+   the optional `playwright-core` peer and a browser, or set
+   `MANTLE_TEST_CHROMIUM`; a missing browser fails rather than skips. This
+   checks rendering with a synthetic catalogue, not application authorization
+   or completion of a Procedure action.
+6. **Keep the host graph safe.** The MCP build rejects `/admin/api` access,
+   cookies and undeclared remote loads. Its entry must be readable in Node.
+   An optional `src/admin.mcp.tsx` (or `buildAdmin({ mcpEntry })`) isolates
+   browser-only integrations; both roots can reuse one host-safe config,
+   components and CSS. Without it the whole shared entry graph is checked.
+7. **Distinguish total bounds from page sizes.** Authored SQL `LIMIT` now
+   bounds the complete ordered result set across cursor pages, including web
+   indexes. Use paging `options.limit` for page size; remove an authored limit
+   only if it was incorrectly being used as a page-size setting. MCP accepts
+   sizes of 1–500, but a response budget can return fewer rows: append pages
+   until `nextCursor` is absent, not until a short page. See
+   [View paging](../reference/surface.md).
+8. **Install build dependencies where the build runs.** Wrangler dev/deploy
+   runs its configured build command, so that environment needs
+   `node_modules`. The resulting built server/assets do not read
+   `node_modules` when served. See the
+   [application shell](../../examples/app-shell/README.md).
+
+Record/collection cells, inputs, record actions, asides and `RecordView` are
+now truthfully browser-only (`surface: "browser"`); remove unreachable MCP
+branches. View cells remain `both`, and pages opt in through `pages[].mcp`.
+A Procedure action's input is distinct from a collection record input: use a
+Procedure target and MCP Trigger with the View's unchanged `id` and observed
+`version` for native row actions. [Shared custom-page headers](../guides/mcp-apps.md#customising-admin-for-mcp-hosts)
+can compose localized title, description and actions on both surfaces; omit the
+option to keep prior behavior, or use `header: false` for an element-owned heading.
+
+OAuth issuer verification now follows Better Auth's normalized URL while
+preserving explicit issuer/JWKS settings. Cloudflare OAuth configurations need
+`global_fetch_strictly_public` for public JWKS fetches; generated settings and
+the official examples retain it. Native MCP Apps use the official ext-apps
+client. Browser Admin now displays a localized explicit reload action when a
+lazy page fails, rather than going blank; it does not reload automatically or
+replay writes.
+
+### Native SDK migration (alpha.7)
+
+Alpha.7 replaces the previous Core runtime and generated service contract.
+Existing alpha.6 applications require a source migration:
+
+- Replace `createMantle`, `Store.select` and the old host presets with
+  [native generated queries and Store](../guides/typed-queries.md).
+  Generate with an explicit target and output directory, for example
+  `mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin`.
+  See [CLI and generated ownership](../start/project-and-cli.md).
+- The application owns routing, native database handles, verified Caller,
+  Auth configuration and migrations. Runtime no longer converges storage or
+  runs DDL at boot. Apply generated `schema.sql` only to an empty database;
+  migrate existing data explicitly. PostgreSQL uses Bun.SQL on Bun and
+  postgres.js on Workers. See [native execution](../guides/native-execution.md).
+- Install the separate `@aotter/mantle-admin` package when selecting Admin, with `react` and `react-dom` in the application pinned to one identical exact version (Admin no longer installs them).
+  Compose its [native bindings](../guides/native-admin.md) in the application.
+  Bare queries retain driver-native values; selected REST/MCP/Admin boundaries
+  own validation and declared-column wire conversion.
+- Move lifecycle/schedule handlers and dynamic authorization guards into
+  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.10/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.
+
+### Earlier alpha design
+
+0.2.0 replaces 0.1.x's grammar and composition; no stable 0.1.5 was released
+(`0.1.5-alpha.1` was a prerelease). It breaks every consumer, and
+`docs/upgrade-0.1-to-0.2.md` in the package is the guide for moving a project
+by hand.
+
+- **Manifests are `cms.mantle.aotter.net/v2`.** Views are one SQL `SELECT` and
+  Procedures are SQL statements or a `ref`, in PostgreSQL syntax. The builtin
+  handlers, the Filter AST, `params`, `$ctx` references and `x-mantle-bind` are
+  gone; Schemas gain `checks`, and `searchableFields` becomes full-text search.
+- **SQL in the dialect's syntax.** PostgreSQL is the reference dialect
+  (`@aotter/mantle/postgres`); D1 and SQLite run a subset
+  (`@aotter/mantle/d1`). Each dialect is its own target (ADR-0039), and a
+  plan records its dialect.
+- **One Store.** Every read and write goes through Store, which adds caller
+  scope, TTL and published-only to every statement, and an optimistic lock
+  where the caller passes one; a write
+  is all or nothing.
+- **The service is the application's.** `createMantle(service, …)` replaces
+  `createMantleWorker`, and the first `mantle generate` writes the host's
+  preset (`src/service.ts`, `src/index.ts`, ...) once. `--host` is
+  `cloudflare` (D1, or PostgreSQL through Hyperdrive), `bun` (node-postgres
+  or bun:sqlite, `@aotter/mantle/bun`) or `none` (plan and types only), and
+  `--dialect` is `sqlite` or `postgres`; both are chosen once.
+- **Mantle never owns your users.** A `CallerResolver` turns a request into a
+  `Caller`; identity is `mantle` (Better Auth), `custom` or `none`. Core creates
+  no auth tables.
+- **Storage converges to the plan** at boot: additions are applied, unsafe
+  changes are refused with a diagnostic, nothing is dropped, and there are no
+  migration files.
+- **Schedules are POSIX cron**; `toCloudflareCron` translates them for Wrangler.
+- **MCP tools come from Views and Procedures only.** Staff tools are at
+  `/mcp/staff` for an OAuth client, with Mantle's MCP App rendering staff
+  View rows in the chat; Admin's WebMCP runs the same tools on Admin's own
+  routes.
+- **The CLI is `mantle generate`** and `mantle generate --check`. `validate`,
+  `emit-openapi`, `skills` and `mantle-harness` are removed.
+- **The Admin console** moves to `@aotter/mantle-ui/admin`, served at `/admin`
+  by the preset through the service's `ASSETS` binding.
+- **Not yet in 0.2.0:** Mantle-rendered public pages and the MCP interaction
+  App tools.
+
+### Native driver and before-hook cleanup (#1426)
+
+This breaking source migration removes request-scoped PostgreSQL sessions,
+custom write pipelining/retries, SQLite lock polling and before-hook runtime
+policing. Copy the new native preset wiring; existing generated source is not
+overwritten. Authenticated Bun SQLite uses separate Store/Auth handles to the
+same WAL file. Operational before hooks no longer add an implicit version
+lock; explicit OCC, publishing checks and authorization guards remain.
+See [native execution migration](../guides/native-execution.md) and ADR-0041.
+The alpha.6 instructions below describe that release; ADR-0041 supersedes its
+requestScoped/pipeline/shared-SQLite-handle directions after this cleanup.
+
+### Upgrading an existing PostgreSQL service (0.2.0-alpha.6)
+
+PostgreSQL is native from this alpha (ADR-0039): each dialect is its own target,
+PostgreSQL's SQL and ordering are PostgreSQL's, and node-postgres (`pg`) is the
+PostgreSQL driver on every host. D1 and SQLite output is unchanged except where
+noted. Work through these in order before deploying.
+
+1. **Role settings (from #1383, now also checked on Bun).** Boot refuses with
+   `STORAGE_CHANGE_BLOCKED` (path `storage:settings`) unless the role Mantle
+   connects as has a statement limit and UTC:
+   `ALTER ROLE app SET statement_timeout = '10s'; ALTER ROLE app SET TimeZone = 'UTC';`
+   (10s or less). Bun's `Bun.SQL` entry used to pin its own limit and skip this
+   check. A Hyperdrive config must keep `--caching-disabled`: reads, role
+   re-reads and grant revocations run outside a transaction.
+2. **Rewrite SQLite spellings, then run `mantle generate`.** A PostgreSQL
+   manifest that uses `json_each`, `-> '$.a'`, `->> '$.a'`, `json_extract`,
+   `json_set`, `json_insert`, `json_remove` or `hex` fails validation with its
+   position and the PostgreSQL spelling. The
+   [dialect contract](../concepts/runtime-and-adapters.md#drivers-and-dialects)
+   covers the PostgreSQL target: `json_each(t.col) j` becomes
+   `jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)` (a sorted
+   View over a row source needs the alias and `WITH ORDINALITY`, and `j.id`
+   becomes `j.n`), `CAST(n AS bool)` of an integer becomes `n <> 0`, and `||`
+   needs a text operand. The PostgreSQL dialect version is now 2, so a plan
+   compiled earlier fails at boot with `PLAN_FINGERPRINT_MISMATCH`: run
+   `mantle generate` and deploy the regenerated plan.
+3. **NULL order.** Unstated `NULLS` now follows PostgreSQL: NULL last ascending,
+   first descending, for every `ORDER BY` including windows and
+   `json_group_array`. Write `NULLS FIRST` or `NULLS LAST` to keep a specific
+   order. Rows tied on the last sort key are ordered by `id` in that key's
+   direction. A cursor live across the deploy may repeat or skip rows once.
+4. **Bun entry.** Install `pg` and `@types/pg`. Replace
+   `new SQL(url, { prepare: false, ... })` with
+   `new pg.Pool({ connectionString, pipeline: true })`; `Env.SQL` becomes
+   `Env.PG`. The simplest path is to delete `src/service.ts` and `src/index.ts`
+   and re-run `mantle generate --host bun`, or copy the new preset. Removed from
+   `@aotter/mantle/bun`: `bunPostgresStorage`, `bunPgConnect`,
+   `bunDatabaseDriver`, `bunAuthDatabase`, `BunSqlPool`, `BunAuthPool`. The role
+   no longer needs `TEMPORARY`. Custom transports lose `temporaryResultMetadata`,
+   `describeResult` and `readOnly` from `PgClient` / `PgStatement`.
+5. **Generated `src/service.ts` changed.** The `database(env).run` wrapper moved
+   to the exported `mantle`, and the Bun pooled wrapper ends each client once.
+   The preset is never rewritten: re-run `mantle generate` into a scratch
+   directory and copy the difference, or delete and regenerate if unedited.
+6. **First boot does one-time work.** It runs once under the advisory lock:
+   - one `_mantle_ix_<schema>_updated` index on `([scope,] updated_at, id)` per
+     Schema, built without `CONCURRENTLY` inside the convergence transaction, so
+     writes to a large table block while it builds. Pre-create it before
+     deploying, on the schema (`search_path`) Mantle uses, with both names quoted:
+     `CREATE INDEX CONCURRENTLY "_mantle_ix_<schema>_updated" ON "<schema>" (["<scope>",] updated_at, id)`.
+     A matching index is accepted. If a concurrent build fails, drop the invalid
+     index before deploying: boot accepts it by name and columns and never
+     rebuilds it. A Schema name longer than about 43 bytes gets a hashed index
+     name; read it from a fresh database's `pg_indexes` instead;
+   - each `_mantle_chk_*` check is rebuilt once (earlier releases left no
+     marker); later boots leave unchanged checks alone;
+   - the old `_mantle_jget`, `_mantle_bool` and `_mantle_json_each` functions
+     stay in place, unused: a previous release still running during a rolling
+     deploy calls them.
+7. **Boot under contention.** Concurrent boots converge once. A boot that cannot
+   get a lock within about five tries of one second fails with
+   `STORAGE_CHANGE_BLOCKED` naming the lock (another boot still converging, or a
+   long transaction on a table the plan changes), and is not retried for 10
+   seconds. A winner building a very large index can outlast its waiters, which
+   then report the blocked boot; boot again when it has finished (#1408).
+8. **Auth.** `get-session` no longer carries a `set-auth-jwt` response header
+   when the OAuth provider is configured; call the plugin's `/api/auth/token`
+   instead. `d1Driver`'s structural `D1PreparedStatement` now requires `first`
+   and `all`: a hand-rolled fake must add them.
+9. **D1.** A paged View with `json_each` in a `JOIN` arm, or with more than one
+   `json_each`, now pages by every element's `id`: its order among ties changes,
+   no row is skipped, and a cursor issued before the upgrade may need to restart.
 
 ## 0.1.4 — 2026-09-24
 
@@ -178,7 +347,7 @@ See [HTTP, MCP, CLI and packages](../reference/surface.md) for the full list.
 D1 and assets bindings, Better Auth 1.7 (social providers, email OTP, magic
 link, passkey), Admin, MCP, Web and R2 media uploads. The Bun and Vercel
 adapters are experimental, cover public Views and HTTP Triggers only, and leave
-authentication and CSRF to the host. [ChatGPT Sites](../chatgpt-sites/index.md) is a
+authentication and CSRF to the host. ChatGPT Sites is a
 first-class integration with a runnable reference.
 
 **Agents.** `mantle skills` projects the installed package's skills into
@@ -193,7 +362,5 @@ Bun and Vercel adapters may change in a minor release.
 
 ## Source
 
-- [`CHANGELOG.md`](../../../CHANGELOG.md)
-- [`docs/release-process.md`](../../../docs/release-process.md)
-- [`.github/workflows/release.yml`](../../../.github/workflows/release.yml)
-- [`scripts/release-tag-order.mjs`](../../../scripts/release-tag-order.mjs)
+- [GitHub Releases](https://github.com/aotter/mantle/releases)
+- [`CHANGELOG.md`](https://github.com/aotter/mantle/blob/main/CHANGELOG.md)

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

@@ -1,55 +1,16 @@
 ---
-description: Choose a Mantle integration, discover manifest capabilities, and find tutorials, task guides, concepts and field-level reference.
+description: The native 0.2.0 handbook and its three package boundaries.
 ---
 # Mantle handbook
 
-Mantle turns YAML manifests into a validated runtime plan, typed TypeScript
-bindings, and optional HTTP, MCP and Admin surfaces. Your application owns the
-host, storage and frontend. Four atoms describe the contract: **Schema** stores
-data, **View** reads it, **Procedure** acts on it, and **Trigger** binds an action
-to HTTP, MCP or lifecycle events.
+Mantle compiles a closed v2 manifest into native SQL and typed TypeScript. The app owns its database handle, verified Caller, routes, auth, migrations and deployment.
 
-This handbook describes the SDK snapshot that carries it. For an installed
-project, read `node_modules/@aotter/mantle/docs/handbook/`; a website or Git
-branch can describe a different version. The [release index](../releases/index.md)
-links published releases. A prerelease capability is not a promise that the
-current npm `latest` contains it.
+| Package | Responsibility |
+| --- | --- |
+| `@aotter/mantle` | SDK, private compiler, generator and `mantle` CLI |
+| `@aotter/mantle-ui` | Pure UI kit and generic interaction controller; no SDK dependency |
+| `@aotter/mantle-admin` | Admin server, app-built SPA library, preview and MCP App; SDK peer |
 
-## Start with your integration
+Start with [a Worker](quickstart-worker.md) or [CLI and targets](project-and-cli.md). Existing TypeScript/Node apps can import selected generated operations using their own handle and verified Caller; no router or identity replacement is required. See the packaged [integrate skill](../../skills/integrate/SKILL.md).
 
-| Goal | Start here | Result |
-|---|---|---|
-| Understand what manifests can express | [Manifest feature reference](../reference/features.md) | A capability-to-field map across the four atoms. |
-| Validate manifests in an existing tool | [Spec-only adoption](../../spec-only-host-adoption.md) | Parse and link without Runtime, storage or a UI. |
-| Bring Mantle into an existing application | [Integration skill](../../skills/integrate/SKILL.md) | Inspect the app and choose embedding, incremental replacement or rebuilding with data migration. |
-| Embed Runtime in an existing host | [Runtime and adapters](../concepts/runtime-and-adapters.md), then [typed queries](../guides/typed-queries.md) | Bind your storage and call the generated API. |
-| Build a local Cloudflare API | [Minimal Worker tutorial](./quickstart-worker.md) | A running public View and a verified HTTP response. |
-| Add a staff console | [Local Admin tutorial](./quickstart-admin.md) | Email OTP, Admin assets and a local human workflow. |
-| Build on ChatGPT Sites | [Sites integration](../chatgpt-sites/index.md) | Host-owned sign-in and deployment with Mantle content. |
-| Work through a coding agent | [Skill installation and handoff](../guides/agent-setup.md) | Bootstrap skill, pinned package, then project-local instructions. |
-
-Human authors can follow these pages directly; installing an agent skill is
-optional. For a new app, install an exact SDK version and run
-`mantle generate --host cf` or `--host chatgpt-sites`. The CLI assembles a blank
-site by default; add your own Manifests after generation. Use explicit
-`--features` for a smaller composition, including host-free Spec-only.
-
-## Find the right kind of documentation
-
-- **Tutorials** walk through a running minimal service or local Admin.
-- **Task guides** explain typed queries, Admin customization and agent setup.
-- **Concepts** explain the four atoms, runtime, lifecycle, authorization and transports.
-- **Reference** lists accepted fields, defaults, restrictions and diagnostics.
-- **Host guides** cover Cloudflare and Sites wiring and operations.
-- **Examples** supply complete domain manifests and runnable host references.
-
-The [project and CLI guide](./project-and-cli.md) describes file ownership and
-the verification loop. The [examples hub](../examples/hub.md) helps select a
-domain model. Use the [field reference](../reference/manifest.md) when checking
-exact syntax; do not infer grammar from a UI screenshot.
-
-## Source
-
-- [Core package](../../../packages/mantle/README.md)
-- [Handbook navigation](../navigation.json)
-- [Consumer skills](../../../skills/README.md)
+Choose [Store or internal Views](../guides/typed-queries.md), review [database and migration ownership](../concepts/runtime-and-adapters.md), and mount only selected [surfaces](../reference/surface.md). Optional [Admin](../guides/native-admin.md) lives in its own package. Installed SDK docs are the authority for that exact version. [Release notes](../releases/index.md) describe historical releases.