@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/handbook/start/overview.md

@@ -1,52 +1,63 @@
 ---
-description: Choose a Mantle integration, discover manifest capabilities, and find tutorials, task guides, concepts and field-level reference.
+description: What Mantle 0.2.0 is, how a service is put together, and where to read next.
 ---
 # 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.
-
-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.
-
-## Start with your integration
-
-| 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. |
-| 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. Do not start with `mantle generate` in an empty directory: author the
-manifests and host first, then generate and validate.
-
-## 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)
+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 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.
+
+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.
+
+## 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).

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

@@ -1,140 +1,151 @@
 ---
-description: The files you own in a Mantle project, every mantle and mantle-harness command with its flags, the generated module, the daily check loop, and version pins.
+description: The files of a Mantle 0.2.0 project, who owns each, mantle.config.json, and every option of mantle generate.
 ---
-# Project layout and the CLI loop
+# Project layout and CLI
 
-This page describes a directly authored Mantle project: which files are yours, what the installed CLI does to them, and the loop you run before every commit. Surfaces are optional — take only what you need. [The minimal Worker](./quickstart-worker.md) is Spec + adapter without Admin. [Local Admin](./quickstart-admin.md) is the opt-in Dev UI path when humans need a console.
+## Files
 
-Agents can bootstrap with the install skill; human authors can follow this guide directly. For installation paths and the pinned-package handoff, see [Agent setup](../guides/agent-setup.md):
-
-```sh
-npx skills add aotter/mantle
-```
-
-## You own the project
-
-Core is a manifest compiler and a runtime, not a project generator. You write `package.json`, the manifests, the Worker entry, handlers, TypeScript and provider configuration. `mantle generate` compiles what exists; it never initializes a missing project or invents a default Schema, frontend or home route.
-
-```txt
-my-service/
-├── package.json              exact-pinned @aotter/mantle* + peers, scripts
-├── tsconfig.json             includes src/ and .mantle/generated/
-├── wrangler.jsonc            Worker name, flags, vars, bindings
-├── .dev.vars                 local secrets for wrangler dev; never committed
-├── manifests/
-│   └── site.yaml             immediate .yaml/.yml files; multi-document with ---
-├── src/
-│   ├── index.ts              createMantleWorker({ plan, extend })
-│   └── mantle/handlers/      handler refs (a convention; any path under src/)
-├── public/                   required ASSETS root when Admin is installed; generate writes public/_mantle/admin/
-├── .mantle/generated/
-│   └── mantle.ts             written by mantle generate
-├── .agents/skills/mantle-*/  written by mantle skills
-└── .claude/skills/mantle-*/  same bytes, for Claude compatibility
+| 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 |
+
+`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.
+
+- `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"] }
 ```
 
-The minimal Worker reference keeps `.mantle/`, `.agents/`, `.claude/`, `.wrangler/`, `.dev.vars*` and `.env*` out of git and regenerates the first three in its `check` script. Committing the generated files is also workable, because `generate --check` and `skills --check` detect drift either way. Commit the lockfile in a real application and install with `--frozen-lockfile` afterwards.
-
-`mantle validate` greps `./src` for the names of `handler.kind: ref` Procedures; a handler that is not found anywhere under `src/` produces a `HANDLER_NOT_REGISTERED` warning, so keep handlers under that root or pass `--source`.
-
-## The CLI
-
-The umbrella package installs two binaries, `mantle` and `mantle-harness`. Run them through the package manager, for example `pnpm exec mantle generate`. Defaults shown are the pinned ones. Bare `mantle` / `mantle --help` prints a layered overview of optional surfaces (Minimal Spec + generate, Runtime / adapter, opt-in Admin). `generate --help` and `validate --help` stay on the compile path. After a successful `generate`, the CLI says Admin is opt-in: next steps when `@aotter/mantle-admin-ui` is installed, otherwise an API-only tip.
-
-| Command | Flags | Does |
+| Key | Values | Meaning |
 |---|---|---|
-| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--check` | Validate, link and compile manifests; write `mantle.ts`; sync Admin assets when installed. `--check` exits 1 without writing when output is stale. |
-| `mantle validate` | `--manifests <dir>`, `--source <dir>` (default `./src`), `--no-source`, `--phase preview\|deploy` (default `preview`), `--format json\|text`, `--json` | Static manifest and handler-source validation. Exit 0 with warnings allowed, 1 on any error, 2 on a CLI invocation problem. |
-| `mantle skills` | `--check` | Copy every skill marked `projection: project` into `.agents/skills/mantle-<name>/` and `.claude/skills/mantle-<name>/`. `--check` exits 1 when a projection is stale. |
-| `mantle emit-openapi` | `--manifests <dir>`, `--title <str>` (default `mantle`), `--version <str>` (default `0.1.0`), `--session-cookie-name <str>`, `-o, --output <file>` | Emit OpenAPI 3.1 for HTTP Triggers and `GET /api/views/<name>` routes to stdout or a file. MCP is out of scope. |
-| `mantle-harness indexes` | `--manifests <dir>`, `--rows <n>` (default 2000), `--require <view>` (repeatable), `--require-public`, `--format text\|json` | Execute compiled Views in crowded SQLite and inspect query plans; exit 1 when a required View lacks its access path. |
-| `mantle-harness http` | `--base-url <url>`, `--route <name=path-or-url>` (repeatable, required), `--rounds <n>` (default 20), `--warmup <n>` (default 2), `--format text\|json` | Sample a running Worker and report p50/p95 timings plus query-count and `rows_read` metric headers. |
-
-Advanced manifest primitives live in the `@aotter/mantle-spec` package's own `mantle-spec` binary: `mantle-spec introspect [--manifests <dir>]` dumps the parsed manifest tree as JSON, and `mantle-spec emit-types [--manifests <dir>] [--namespace <name>] [-o <file>]` emits standalone `.d.ts` declarations. Add `@aotter/mantle-spec` as a direct dependency to run them. The full flag reference is in [HTTP, MCP, CLI and packages](../reference/surface.md).
-
-### What `generate` does and does not do
+| `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) |
 
-`generate` reads the manifest directory, runs the same validation as `validate` (without the handler-source grep), links the set, and emits one `.mantle/generated/mantle.ts`. When `@aotter/mantle-admin-ui` is installed it also syncs the **prebuilt** Admin SPA into `public/_mantle/admin/`, excluding the package's `server.*` exports; Core-only installs skip that copy. Any error diagnostic stops the run with exit 1.
+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.
 
-Do not Vite-build Admin unless you are developing `@aotter/mantle-admin-ui` itself. A Cloudflare project that serves Admin must declare Static Assets:
+## `mantle generate`
 
-```jsonc
-"assets": { "directory": "./public", "binding": "ASSETS" }
+```sh
+mantle generate [--manifests <dir>] [--features <list>] [--identity <kind>] [--host <host>] [--dialect <name>]
+mantle generate --check [--database <file>]
 ```
 
-That binding is a hard requirement. If `/admin` returns SPA `index.html` (`200`) while `/_mantle/admin/assets/*` is `404`, the page white-screens. Leave `/_mantle` out of `run_worker_first` so those files stay on the assets layer. `generate` warns when it syncs Admin and the local wrangler config has no `ASSETS` binding.
-
-It does not project skills, update packages, change styling, provision providers, or deploy. It does not create manifests: a missing or empty `manifests/` directory is an error, not a prompt.
-
-## The generated module
-
-`.mantle/generated/mantle.ts` exports:
-
-| Export | Purpose |
+| Option | Meaning |
 |---|---|
-| `plan` | The sealed RuntimePlan with its fingerprint. The conventional Worker imports only this. |
-| `MantleHandlers<Env>` | The handler map type: one typed function per `handler.kind: ref` Procedure, receiving `(input, ctx)`. |
-| `createMantle({ storage, handlers, ports })` | Prepares storage eagerly once and returns the typed binding. No caching or retry. |
-| `bindMantle(runtime)` | The same typed binding over a runtime whose lifecycle the host already owns. |
+| `--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 |
 
-The binding exposes `mantle.views.<lowerCamelName>()`, `mantle.procedures.<name>(input, ctx)`, `mantle.entries.<collection>.createDraft({ data, authorId })`, typed indexed field reads such as `mantle.entries.<collection>.findManyByDataField({ field, value, limit })`, and the underlying `mantle.runtime`. Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally. See [Typed queries](../guides/typed-queries.md) for internal Views and entry-reader examples. Details are in [HTTP, MCP, CLI and packages](../reference/surface.md).
+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.
 
-## The daily loop
+`--check` is the gate for CI and for agents: run `mantle generate`, then
+`mantle generate --check`, then your typecheck.
 
-```sh
-pnpm install --frozen-lockfile
-pnpm exec mantle validate
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-pnpm test                      # only when the project declares a test script
-pnpm exec mantle-harness indexes --require-public --format text
-pnpm exec wrangler dev --local
-```
+### Schedules and Cloudflare crons
 
-Run the harness after any change to a Schema index, View filter or ordering, or public route; declare the smallest ordered index the measured path needs and respect SQLite's leftmost-prefix rule. Before a deploy, run `mantle validate --phase deploy`. Probe at least one declared route on the local origin; a `200` from a public View does not prove Admin or MCP login works. When Admin is installed, also probe `/admin/sign-in` and one `/_mantle/admin/assets/*` URL — both must be `200`. HTML 200 with asset 404 is the white-screen class of bug.
+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.
 
-## Connecting an agent
+### Storage SQL
 
-`mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `mantle`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
+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).
 
-Install the bootstrap skill in the agent host. Cold start uses
-the install skill; an already-installed project pins packages from `package.json`:
+### PostgreSQL on Cloudflare
 
-```sh
-# Canonical
-npx skills add aotter/mantle
+`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:
 
-# Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
-
-# Codex
-codex plugin marketplace add aotter/mantle
-codex plugin add mantle@mantle
+```sh
+wrangler hyperdrive create my-app --caching-disabled --connection-string="postgres://user:pass@host:5432/db"
 ```
 
-The projected `develop` skill tells the agent to read `package.json` for the installed version, the manifests and adapter config, and the docs under `node_modules/@aotter/mantle/docs/` before editing. To connect an MCP client to the running Worker, see [MCP and agents](../concepts/mcp-and-agents.md).
-
-## Version pins
-
-- Pin every `@aotter/mantle*` package to one exact version and move them together. Check that release's peer ranges when you move.
-- This handbook describes the snapshot in this source tree. Use the docs that ship with the version in `package.json`, not a floating branch.
-- The authoring CLI is `generate`, `validate`, `emit-openapi` and `skills`. `mantle-harness` is the measurement binary. There is no `create` / `update` happy path.
-- When you change versions: pin the new exact version and refresh the lockfile; keep the Worker, D1, KV identity, origins, auth mode and secrets; then run `generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests before deploying.
-
-## Source
-- [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
-- [`docs/examples/host-local-admin-otp/README.md`](../../../docs/examples/host-local-admin-otp/README.md)
-- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
-- [`docs/examples/host-minimal-worker/.gitignore`](../../../docs/examples/host-minimal-worker/.gitignore)
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/mantle/src/cli/main.ts`](../../../packages/mantle/src/cli/main.ts)
-- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
-- [`packages/mantle/src/cli/skills.ts`](../../../packages/mantle/src/cli/skills.ts)
-- [`packages/mantle/src/cli/harness.ts`](../../../packages/mantle/src/cli/harness.ts)
-- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/MantleCli.ts`](../../../packages/mantle-spec/src/infrastructure/cli/MantleCli.ts)
-- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)
+## 0.1.x projects
+
+`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.
+
+## Bun
+
+`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.
+
+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.