@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.11

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,63 +1,16 @@
 ---
-description: What Mantle 0.2.0 is, how a service is put together, and where to read next.
+description: The native 0.2.0 handbook and its three package boundaries.
 ---
 # Mantle handbook
 
-Mantle is a manifest-driven service core. A service declares four atoms in
-YAML: a **Schema** stores rows, a **View** reads them, a **Procedure** writes
-them, and a **Trigger** binds a Procedure to HTTP, MCP, a lifecycle event or a
-schedule. Views and Procedures are SQL in PostgreSQL syntax.
+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.
 
-`mantle generate` compiles the manifests into a sealed plan and a typed module.
-The runtime serves the plan through one **Store**, which adds each caller's
-scope, TTL visibility and publishing state to every statement, and an
-optimistic lock where the caller passes one. Your service owns its entry, its users and its frontend; Mantle
-adds tables, surfaces and typed access to them.
+| 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 |
 
-This handbook ships inside `@aotter/mantle` at
-`node_modules/@aotter/mantle/docs/handbook/`. The installed copy matches the
-installed package; prefer it over any online copy.
+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).
 
-## How a service fits together
-
-```
-manifests/*.yaml ──mantle generate──▶ .mantle/generated/plan.json + mantle.ts
-                                          │
-src/service.ts   createMantle(service, { plan, storage, schedules })
-  ├─ handlers    the `ref` Procedures, typed by mantle.ts
-  └─ fetch       your routes, then Mantle's surfaces behind withCaller(resolver, …):
-                 auth routes · Admin at /admin · MCP at /mcp · REST at /api
-src/index.ts     the host entry: Cloudflare's fetch and scheduled, or Bun.serve
-```
-
-The first `mantle generate` writes `src/service.ts`, `src/index.ts`,
-`src/handlers.ts`, `tsconfig.json` and, on Cloudflare, `wrangler.jsonc` once.
-After that they are your files.
-
-## Read next
-
-| You want to | Read |
-|---|---|
-| Start a service | [Quickstart](./quickstart-worker.md), then [Project layout and CLI](./project-and-cli.md) |
-| Learn the model | [The four atoms](../concepts/four-atoms.md), [Reads](../concepts/views.md), [Writes](../concepts/procedures-and-triggers.md), [Authorization](../concepts/authorization.md) |
-| Look up a field | [Feature table](../reference/features.md), then the [Schema](../reference/schema.md), [View](../reference/view.md), [Procedure](../reference/procedure.md) and [Trigger](../reference/trigger.md) references |
-| Wire sign-in, media or deploy | [Authentication](../cloudflare/authentication.md), [Media uploads with R2](../cloudflare/media-r2.md), [Deploy and operate](../cloudflare/deploy-and-operate.md) |
-| Run on ChatGPT Sites | [Mantle on ChatGPT Sites](../cloudflare/chatgpt-sites.md) |
-| See whole services | [Examples](../examples/hub.md) and the runnable reference service |
-| Move a 0.1.x project | `docs/upgrade-0.1-to-0.2.md` in the installed package |
-
-The decisions behind 0.2.0 are ADR-0032 to ADR-0038 in `docs/adr/`. The ADRs
-record decisions and may describe work not built yet; the installed code is the
-authority. When an ADR and this handbook disagree, follow this handbook and
-check the code.
-
-## What 0.2.0 does not have yet
-
-- **Mantle-rendered public pages.** `createWebSurface` is not ported. Render
-  pages from your own `fetch` or frontend over the REST surface.
-- **A preset for any host but Cloudflare and Bun.** With `--host none`,
-  `mantle generate` writes the plan and its types only, and your code calls
-  `createMantle`. The Bun preset has no scheduler.
-- **Site settings and media on PostgreSQL.** Only the `sqlite` dialect's
-  storage takes `SiteDefaults`; see [Site defaults](../reference/site-config.md).
-- **Deploying to Mantle Cloud.** See [Deploy and operate](../cloudflare/deploy-and-operate.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.

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

@@ -1,151 +1,71 @@
 ---
-description: The files of a Mantle 0.2.0 project, who owns each, mantle.config.json, and every option of mantle generate.
+description: Generation targets, CLI options and ownership of native application files.
 ---
 # Project layout and CLI
 
-## Files
+| File | Owner |
+| --- | --- |
+| `manifests/*.yaml` | App: closed v2 declarations and SQL |
+| `src/worker.ts`, auth, handlers, frontend | App: routing, Caller verification and side effects |
+| `generated/` | Generator: TypeScript, native SQL and selected bindings |
+| `migrations/` | App's agent and native migration tool |
+| `wrangler.jsonc` | App configuration; generator maintains selected split-build keys |
+| `dist/` | Disposable bundle output (`dist/worker`, `dist/client`); do not commit |
 
-| Path | Written by | Owner |
-|---|---|---|
-| `manifests/*.yaml` | you | you |
-| `mantle.config.json` | `mantle generate`, when the selection changes | you may edit it; generate keeps keys it does not know |
-| `.mantle/generated/plan.json` | every `mantle generate` | generated: never edit, commit it |
-| `.mantle/generated/mantle.ts` | every `mantle generate` | generated: never edit, commit it |
-| `src/service.ts`, `src/index.ts`, `src/handlers.ts`, `src/identity.ts` (identity `custom`) | the first `mantle generate` | yours from then on |
-| `wrangler.jsonc` (Cloudflare, unless a `wrangler.json` or `wrangler.toml` exists), `tsconfig.json`, `.dev.vars.example` (Cloudflare, identity `mantle`) or `.env.example` (Bun), `.gitignore` | the first `mantle generate`, each only if missing | yours |
+## Accept user-facing work
 
-`mantle generate` writes each preset file only when it does not exist, and
-writes none once `src/service.ts` exists: from then on the application owns
-its composition. To get a fresh preset, move the old file aside and rerun.
+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.
 
-- `plan.json` is `{ "sourceHash": …, "plan": … }`: the sealed `RuntimePlan`
-  and the SHA-256 of the manifest sources. The plan's `fingerprint` is what
-  boot checks; reformatting a manifest changes `sourceHash` but not the
-  fingerprint.
-- `mantle.ts` exports `plan`, `sourceHash`, the `Mantle` namespace of row, input and output
-  types, `Store` and `CallerStore` typed over your Schemas and
-  Views, and `MantleHandlers`, which lists exactly the plan's `ref` handlers. A
-  missing or extra handler is a type error. See
-  [Query from TypeScript](../guides/typed-queries.md).
-
-## `mantle.config.json`
-
-```json
-{ "version": 2, "identity": "mantle", "features": ["mcp", "admin", "web"] }
-```
-
-| Key | Values | Meaning |
-|---|---|---|
-| `version` | `2` | `1` (a 0.1.x config) fails with exit 2 |
-| `identity` | `mantle`, `custom`, `none` | who the callers are. `mantle`: `@aotter/mantle/auth` (Better Auth sign-in, staff roles, OAuth for MCP). `custom`: your `src/identity.ts` maps your own sessions to callers. `none`: every caller is anonymous |
-| `features` | a subset of `mcp`, `admin`, `web`, in that order | `mcp`: the public MCP surface at `/mcp` (and staff MCP inside Admin). `admin`: the Admin console and its API at `/admin`, which needs an identity. `web`: reserved for public pages; REST at `/api` is always mounted |
-| `host` | `cloudflare`, `bun`, `none`, optional | where the service runs (ADR-0036); absent is `cloudflare`. `none` writes no preset: only the plan and its types, and your code calls `createMantle`. The host never enters the plan |
-| `dialect` | `sqlite` (alias `d1`), `postgres`, or a dialect package name, optional | the SQL engine; absent is `sqlite`, which runs on D1. `postgres` runs on PostgreSQL, through Hyperdrive on Cloudflare. The plan records the dialect (the SQLite dialect as `@aotter/mantle/d1`) |
-
-Without a config or flags, the selection is identity `mantle` and every
-feature. An explicit `--features` without `--identity` means identity `none`.
-A rerun keeps the saved identity, host and dialect; asking for another one is
-refused (exit 2), so switching never drops tables or orphans data. Change
-`mantle.config.json` deliberately once the data is moved.
-
-| | `cloudflare` | `bun` | `none` |
-|---|---|---|---|
-| `sqlite` | preset over D1 (the default) | native bun:sqlite | plan and types only |
-| `postgres` | preset over Hyperdrive and `pg` | native Bun.SQL PostgreSQL pool | plan and types only |
-| a dialect package | plan and types only; compose `src/service.ts` with its storage adapter | plan and types only | plan and types only |
-
-Each selection needs packages in the project. `mantle generate` checks them
-and stops before writing anything, naming the install command for your
-package manager. It never installs anything. The host and dialect rows, and the
-staff MCP App, are checked only while the preset is still to be written.
-
-| Selection | Packages |
-|---|---|
-| always | `@aotter/mantle` |
-| identity `mantle` | `better-auth`, `@better-auth/oauth-provider`, `@better-auth/mcp`, `@better-auth/cimd` |
-| feature `mcp` | `@modelcontextprotocol/server`, `@modelcontextprotocol/ext-apps` |
-| feature `admin` | `@aotter/mantle-ui` (its `dist/admin` is the console, bound as `ASSETS` in `wrangler.jsonc`) |
-| dialect `postgres` on `cloudflare` | `pg` |
-| host `bun` | `bun-types` |
-| feature `mcp` with an identity, without `admin` | `@aotter/mantle-ui` (the staff MCP App) |
-
-On Cloudflare the project also installs `wrangler`, `@cloudflare/workers-types` and
-`@types/node` itself. A TypeScript Cloudflare/PostgreSQL project also installs
-`@types/pg` as a dev dependency for the generated `pg` import.
-
-## `mantle generate`
+## Commands
 
 ```sh
-mantle generate [--manifests <dir>] [--features <list>] [--identity <kind>] [--host <host>] [--dialect <name>]
-mantle generate --check [--database <file>]
+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>]
 ```
 
-| Option | Meaning |
-|---|---|
-| `--manifests <dir>` | the manifest directory, default `./manifests`. Every `.yaml` and `.yml` file directly in it is read |
-| `--features <list>` | comma-separated, a positive list. A missing dependency fails with `GENERATE_FEATURE_DEPENDENCY_MISSING`; an omitted feature is never added back |
-| `--identity <kind>` | `mantle`, `custom` or `none` |
-| `--host <host>` | `cloudflare`, `bun` or `none`, chosen on the first run. `bun` defaults the dialect to `postgres` |
-| `--dialect <name>` | `sqlite` (alias `d1`), `postgres` or a dialect package, chosen on the first run |
-| `--check` | writes nothing. Exits 1 when `plan.json`, `mantle.ts` or `mantle.config.json` differs from what generate would write, or a package is missing |
-| `--database <file>` | with `--check`: also read a local SQLite file (Wrangler's local D1 is under `.wrangler/state/v3/d1/`) read-only, and print the SQL storage convergence would run |
-
-Exit codes: 0 success, 1 a diagnostic or a stale file, 2 a usage or file
-error. Diagnostics name the manifest file, the path in it and, for SQL, the
-position in the statement.
-
-`--check` is the gate for CI and for agents: run `mantle generate`, then
-`mantle generate --check`, then your typecheck.
-
-### Schedules and Cloudflare crons
-
-On host `cloudflare`, schedule Triggers use POSIX cron. `mantle generate` translates each enabled
-one with `toCloudflareCron` and refuses (exit 1, before writing) one that
-Cloudflare cannot run the same way. It writes `triggers.crons` into a new
-`wrangler.jsonc`; once the file is yours it only warns when the crons differ
-from the plan, and you update them.
+`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.
 
-### Storage SQL
+| Target | Dialect | Handle |
+| --- | --- | --- |
+| `bun-sqlite` | sqlite | bun:sqlite Database |
+| `bun-postgres` | postgres | Bun.SQL |
+| `cloudflare-d1` | sqlite | D1 binding/session |
+| `cloudflare-postgres` | postgres | postgres.js, usually with Hyperdrive |
 
-Boot creates what the plan adds (tables, columns, indexes, check triggers) and
-refuses what it cannot change safely. `--check --database` prints the same
-diff without applying it, for the `sqlite` dialect; see [Deploy and operate](../cloudflare/deploy-and-operate.md).
+Other handles may adapt to the same [structural driver contracts](../guides/adapter-guide.md). Dialects are exactly postgres and sqlite in 0.2.0.
 
-### PostgreSQL on Cloudflare
-
-`mantle generate --dialect postgres` writes the same preset over Hyperdrive:
-`src/service.ts` opens a `pg` client per operation from `env.HYPERDRIVE`, and
-`wrangler.jsonc` binds `HYPERDRIVE` with a placeholder id and a
-`localConnectionString` for `wrangler dev`. Before deploying, create the config
-with caching off and put its id in place of the placeholder; generate warns
-until you do:
+| Option | Meaning |
+| --- | --- |
+| `--check` | Compare generated owned files and Wrangler build keys without writing; stale output exits nonzero. No database or credentials are needed. |
+| `--admin` | Emit native Admin bindings and `admin/*` modules; install the separate Admin package. |
+| `--auth <module>` | Read plain `authOptions(env)` (or an exported auth instance's options) and append selected Better Auth DDL. Repeat it once per Better Auth instance. Prefer plain options without initialization side effects. |
+| `--site <module>` | Read `siteDefaults`; emit site/media bindings and deployment SQL. |
+| `--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. New assets blocks default to `ASSETS`, Worker-first routing and no HTML rewriting; existing blocks keep their binding/routing. |
 
-```sh
-wrangler hyperdrive create my-app --caching-disabled --connection-string="postgres://user:pass@host:5432/db"
-```
+## Outputs
 
-## 0.1.x projects
+`generated/.mantle-inputs.json` records the Mantle version, the target, and a hash of every input the run read (manifests and the
+`--auth` and `--site` modules). `mantle bundle`, which Wrangler runs for `wrangler dev` and every
+deploy, refuses to build when an input changed since, so stale generated code cannot run; regenerate and rebuild.
+Commit it with the other generated files.
+The bundle also prints notes, never errors, for SQL in the app's own code against Better Auth's tables (read users
+through `userOf(caller)` or `readIdentity(auth)` instead) and for Better Auth roles beyond `admin` and `user`.
 
-`apiVersion: cms.mantle.aotter.net/v1` manifests, a `version: 1` config, `mantle validate`,
-`mantle emit-openapi`, `mantle skills` and the `mantle-harness` bin are gone.
-`docs/upgrade-0.1-to-0.2.md` in the installed package is the guide.
+`generated.ts` exports typed queries and Store. Direct `views/<encoded-name>.ts` and `procedures/<encoded-name>.ts` entries export an operation and its types. Proved pageable Views also have `paged/views/*`; boundary checks live in `validation/*`. `admin-descriptors.ts`, `rest.ts` and `web.ts` are always emitted. Manifest exposure selects `mcp.ts`; `admin-bindings.ts`, `admin-client.ts` (browser-side types and hooks for `admin.tsx`) and `admin/*` require `--admin`. Auth and site are explicit options.
 
-## Bun
+Apply `schema.sql` only to an empty database. Later changes require [explicit migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations); generation and runtime do not inspect the database. Ref declarations print the `Handlers` keys to implement.
 
-`mantle generate --host bun` selects PostgreSQL on first run. Install `bun-types`
-for the generated project's typecheck, the selected feature/identity packages,
-then set DATABASE_URL in `.env` and run `bun src/index.ts`. For SQLite pass
-`--dialect sqlite` and optionally DATABASE_FILE (default mantle.sqlite).
-The preset is written once, uses native drivers from `@aotter/mantle/bun`, and
-owns Bun.serve, trusted socket IP and shutdown/background work. Admin binds the
-installed UI bundle. Enabled schedule Triggers fail generation; use `host: none`
-with an explicit scheduler when schedules are required. Behind a reverse proxy,
-set TRUSTED_PROXIES to its addresses: otherwise every client shares the proxy's
-address, and with it one sign-in rate limit.
+Never edit generated output by hand. Merge manifests/options, regenerate with the same command, then review TypeScript and SQL diffs. Use that exact command with `--check` in CI. Unmarked app files are preserved. Imported option modules must be pure; generation does not make their side effects safe.
 
-PostgreSQL pools must set `prepare: false`: Bun otherwise re-encodes JSON strings,
-and the role needs TEMPORARY on the database (`GRANT TEMPORARY ON DATABASE app TO
-app_role`), which describing a result takes.
-Mantle refuses another setting. Native raw result metadata comes from PostgreSQL
-with three extra round trips per result, preserving microseconds and exact numeric
-scale. No pg dependency or PostgreSQL clone is added. See ADR-0038.
+On Workers, generation configures `mantle bundle` as Wrangler's build command. It emits minified split ESM into `<outdir>/worker` with a startup guard for eager Better Auth imports and for Admin's browser code (`@aotter/mantle-admin/app` and `/hooks`, which `generated/admin-client.ts` imports; they belong to `admin.tsx`). When the Worker imports `@aotter/mantle-admin/server`, it also builds Admin with Vite into `<assets>/admin` (`--assets`, default `<outdir>/client`), from `admin.tsx` beside the Worker entry or Admin's built-in entry; `src/admin.ts` is not an entry. The assets directory must not overlap the Worker directory, and neither the outdir nor the assets directory may be the working directory or contain the Worker entry. The built-in entry is not rebuilt while the installed `@aotter/mantle-admin` keeps its path and version and its direct dependencies and its `react`/`react-dom` peers keep theirs; an `admin.tsx` entry builds every time. The build needs no install scripts (`npm ci --ignore-scripts` works). A `package-lock.json` made on one OS can lack the native build binaries (rolldown, `@tailwindcss/oxide`, lightningcss) that npm installs per platform from `optionalDependencies`, so a lockfile made on macOS can fail the build on a Linux host; create the lockfile on the build platform or use pnpm. `wrangler dev` and `wrangler deploy` run that build command, so they need `node_modules`. The built output (`<outdir>/worker`, `<assets>`) never reads it, so a pipeline that deletes `node_modules` must run `wrangler deploy` first. On Bun, the app owns `Bun.serve`, its Database/SQL pool and scheduler; Bun runs the server as TypeScript, so for a `bun-*` target recorded in `.mantle-inputs.json`, `mantle bundle src/server.ts dist` skips the Worker bundle and builds only Admin, into `dist/client/admin` (read with `bunAdminAssets("dist/client/admin")`, adapted for `adminShell` as in service composition). See [service composition](../cloudflare/service-entry.md).

package/docs/handbook/start/quickstart-worker.md

@@ -1,145 +1,68 @@
 ---
-description: Create a Mantle 0.2.0 service on Cloudflare Workers from an empty directory, run it locally, then add sign-in, Admin and MCP.
+description: Generate a small native D1 service and mount an application-owned Worker.
 ---
-# Quickstart: a service on Cloudflare Workers
+# Quickstart: a service on Workers
 
-From an empty directory to a running service with a public View and a write.
-You need Node 22 or later and a package manager (pnpm is used below).
+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.
 
-## 1. Create the project
-
-```sh
-mkdir notes && cd notes
-pnpm init
-npm pkg set type=module
-npm view @aotter/mantle dist-tags
-```
-
-Pick a `0.2.x` version from the output. While 0.2.0 is in prerelease it is
-on the `alpha` tag, and `latest` still names 0.1.x. Install it with an exact
-version:
-
-```sh
-pnpm add --save-exact @aotter/mantle@<0.2.x version>
-pnpm add -D wrangler @cloudflare/workers-types @types/node typescript
-```
-
-## 2. Write a manifest
-
-`manifests/notes.yaml`:
+Save `manifests/tickets.yaml`:
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
-metadata: { name: notes }
+metadata: { name: tickets }
 spec:
-  title: Notes
+  title: Tickets
   lifecycle: operational
+  indexes: [[ticketState]]
   schema:
     type: object
-    required: [text]
+    additionalProperties: false
+    required: [subject, ticketState]
     properties:
-      text: { type: string, minLength: 1, maxLength: 500 }
+      subject: { type: string }
+      ticketState: { type: string, enum: [open, closed] }
 ---
 apiVersion: cms.mantle.aotter.net/v2
 kind: View
-metadata: { name: latest-notes }
+metadata: { name: tickets-by-state }
 spec:
   surface: public
-  sql: SELECT id, text, created_at FROM notes ORDER BY created_at DESC LIMIT 20
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: add-note }
-spec:
   input:
     type: object
-    required: [text]
+    additionalProperties: false
+    required: [ticketState]
     properties:
-      text: { type: string, minLength: 1, maxLength: 500 }
-  output: { type: object }
-  handler:
-    sql: INSERT INTO notes (text) VALUES (input.text) RETURNING id
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: add-note-http }
-spec:
-  source: { kind: http, method: POST, path: /api/notes }
-  target: { procedure: add-note }
+      ticketState: { type: string, enum: [open, closed] }
+  sql: |
+    SELECT id, subject, ticketState AS "ticketState" FROM tickets
+    WHERE ticketState = input.ticketState
+    ORDER BY id ASC
 ```
 
-## 3. Generate
-
-Start with the smallest selection: no identity (every caller is anonymous)
-and only the REST surface.
-
 ```sh
-pnpm exec mantle generate --identity none --features web
+pnpm exec mantle generate cloudflare-d1 generated manifests/tickets.yaml
+pnpm exec mantle generate cloudflare-d1 generated manifests/tickets.yaml --check
 ```
 
-It writes `.mantle/generated/plan.json` and `mantle.ts`, `mantle.config.json`,
-and once, the preset: `src/service.ts`, `src/index.ts`, `src/handlers.ts`,
-`wrangler.jsonc`, `tsconfig.json` and `.gitignore`. Commit all of them,
-`.mantle/generated` included.
-
-## 4. Run it
-
-```sh
-pnpm exec wrangler dev --local
+Write `src/worker.ts`:
+
+```ts
+import { rest } from '../generated/rest.js';
+interface Env { DB: D1Database }
+const api = rest<Env>({
+  db: env => env.DB,
+  caller: () => ({ kind: 'anonymous' }),
+});
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return await api(request, env) ?? new Response('Not found', { status: 404 });
+  },
+};
 ```
 
-On the first request the runtime creates the tables on the local D1 database.
-Then:
-
-```sh
-curl -sS -X POST http://127.0.0.1:8787/api/notes -H 'content-type: application/json' -d '{"text":"hello"}'
-curl -sS http://127.0.0.1:8787/api/views/latest-notes
-```
-
-The write answers `{ "results": [[{ "id": "…" }]] }` and the View
-`{ "rows": [{ "id": "…", "text": "hello", "created_at": … }] }`.
-
-## 5. Add sign-in, Admin and MCP
-
-The full selection is identity `mantle` (Better Auth sign-in, staff roles,
-OAuth for MCP) and the features `mcp`, `admin` and `web`. A rerun cannot
-switch identity, and the preset is never rewritten, so start a project that
-needs them with the full selection instead:
-
-```sh
-pnpm exec mantle generate
-```
-
-With no flags the selection is identity `mantle` and every feature. The first
-run names the packages it needs, with the install command, and writes nothing
-until they are installed:
-
-```sh
-pnpm add better-auth @better-auth/oauth-provider @better-auth/mcp @better-auth/cimd \
-  @modelcontextprotocol/server @modelcontextprotocol/ext-apps @aotter/mantle-ui
-pnpm exec mantle generate
-cp .dev.vars.example .dev.vars   # set ADMIN_EMAIL and a random BETTER_AUTH_SECRET
-pnpm exec wrangler dev --local
-```
-
-Request a code for `ADMIN_EMAIL` (`POST /api/auth/email-otp/send-verification-otp`
-with `{ "email": …, "type": "sign-in" }`). The code is printed to the wrangler
-log, and that email becomes the owner. Codes in the log are for local
-development only; [Authentication](../cloudflare/authentication.md) covers
-production sign-in.
-
-Or open `/admin/sign-in` in a browser: the console is served at `/admin` from
-`@aotter/mantle-ui/admin`, which the generated `wrangler.jsonc` binds as the
-Worker's `ASSETS`. Admin's API answers at `/admin/api/*`, the public MCP
-surface at `/mcp`, and the staff MCP surface at `/mcp/staff`. The
-[reference service](../../examples/reference-service/README.md) is this
-selection with a smoke test that signs in and drives every surface.
+Set the database binding `DB`, Worker name and compatibility date in `wrangler.jsonc`. Generation adds the split build configuration. Apply `generated/schema.sql` explicitly to an empty local database, for example `pnpm exec wrangler d1 execute <database> --local --file generated/schema.sql`. The first request creates nothing.
 
-## Next
+Typecheck, then run `pnpm exec wrangler dev --local`. Query `/api/views/tickets-by-state?ticketState=open`; the response is `{ rows, nextCursor? }`. The empty database returns no rows. Use Store or a declared Procedure for writes.
 
-- [Project layout and CLI](./project-and-cli.md): what each generated file is,
-  and `mantle generate --check`.
-- [Writes: Procedures, Triggers and hooks](../concepts/procedures-and-triggers.md)
-  and [Reads: Views, REST and MCP](../concepts/views.md).
-- [Deploy and operate](../cloudflare/deploy-and-operate.md).
+Commit generated files and Wrangler edits; keep bundle `dist/` untracked. Follow [service composition](../cloudflare/service-entry.md) to add auth, Admin or MCP and [deploy and operate](../cloudflare/deploy-and-operate.md) before changing schema or deploying.