@aotter/mantle 0.1.4 → 0.1.5-alpha.1

package/docs/handbook/chatgpt-sites/generated-app.md

@@ -0,0 +1,84 @@
+---
+description: Generate a blank Mantle app for ChatGPT Sites, apply D1 migrations, and verify local Admin and MCP.
+---
+# Generate a ChatGPT Sites app
+
+`mantle generate --host chatgpt-sites` creates a blank home, a D1-backed Runtime,
+public API and MCP, and Mantle Admin. It adds no article Schema, media bucket, or
+demo content. Edit `src/home.ts` and add your own manifests and handlers as needed.
+
+```sh
+mkdir my-site && cd my-site
+npm init -y
+npm pkg set type=module
+npm install --save-exact @aotter/mantle
+npx mantle generate --host chatgpt-sites
+npm install
+npx mantle generate
+npm run build
+npx wrangler d1 migrations apply my-site --local
+```
+
+The first generate declares the exact Mantle package versions it needs; the
+second runs after those packages are installed. Review `drizzle/0000_mantle.sql`
+before applying it. The D1 name comes from `wrangler.jsonc`. Generation does not
+apply a migration, provision a Site, or publish one. `npm run build` removes the
+old `dist` before copying the current migrations and Admin assets.
+
+For local Admin, copy `.dev.vars.example` to `.dev.vars`, set `OWNER_EMAIL` to
+the email of the ChatGPT account that will own this Site, and keep
+`PUBLIC_ORIGIN` equal to the local URL. Run `npm run dev`.
+The plain local browser has no ChatGPT Sites identity, so it will redirect to
+Sites sign-in and cannot prove owner access. To exercise the identity contract
+locally, set `MANTLE_TEST_OWNER_EMAIL` to the same email and run
+`npm run smoke:local`. That script refuses non-loopback
+targets. Its identity headers are a local simulation; the production Worker
+contains no identity-injection path and must run behind Sites' trusted
+identity-stripping dispatcher. The generated Wrangler config disables the
+independent `workers.dev` URL; do not add a direct Worker route. A passing
+local smoke does not verify a deployed ChatGPT sign-in.
+
+Without `OWNER_EMAIL`, sign-in grants no Mantle staff role. If the intended
+owner signed in before configuration, their existing `sites_users` row remains
+unprivileged. Configure the owner email and deliberately assign `role='owner'`
+to that account's exact email and `chatgpt:` ID in D1, or reset a disposable
+local database and sign in again. Mantle never gives ownership to the first
+visitor.
+
+The anonymous public MCP endpoint is `/api/mcp`; it discovers only public
+manifest capabilities. `/api/mcp/staff` uses the current Sites browser session
+and a Mantle staff role. Admin advertises these endpoints, and Admin WebMCP
+works in supporting browsers. The staff endpoint is not a remote OAuth MCP
+connector. A remote agent needs a separately implemented verified OAuth flow.
+
+When a Schema changes, run `npx mantle generate --check` to detect drift, then
+`npx mantle generate`. Review the newly appended SQL and apply pending D1
+migrations before deploying code that expects the new Schema. Previous
+migration files remain untouched; an unapplied migration keeps the old database
+fingerprint, and managed boot refuses to use an older database. Sites owns
+`.openai/hosting.json` project metadata and production D1 migration delivery.
+
+Replacing a Schema's `uniqueIndexes` tuple requires an explicit reviewed
+migration. With the old local D1 migration applied, edit the Manifest and run
+`npx mantle generate --review-unique-indexes --check` to inspect the proposed
+source/target fingerprints, affected tuples and checksum without writing. Then
+run `npx mantle generate --review-unique-indexes`, review the new
+`drizzle/meta/000N_mantle.review.json` and matching SQL, and apply that SQL
+through the normal Sites D1 migration path. The CLI checks **local D1 only**
+for duplicate target tuples and reports a count and sample before writing;
+inspect production data separately before applying there. SQLite also refuses
+to create the new unique index if production has conflicts; do
+not deploy the target Worker until the migration has succeeded. Old Workers
+cannot safely reactivate after the old uniqueness guarantee is removed.
+This option is limited to managed Sites SQLite and unique tuple changes;
+field conversions and runtime-managed CF boot still reject destructive
+changes.
+
+For a complete article, media, and publishing example, use the
+[Sites reference](../../examples/host-chatgpt-sites/README.md).
+
+## Source
+
+- [Sites generator](../../../packages/mantle/src/cli/generate-sites.ts)
+- [Generated Sites templates](../../../packages/mantle/templates/chatgpt-sites)
+- [Runnable Sites reference](../../examples/host-chatgpt-sites/README.md)

package/docs/handbook/chatgpt-sites/index.md

@@ -16,6 +16,10 @@ repository. Sites owns hosting, visitor access, and ChatGPT sign-in; Mantle owns
 the content model, staff roles, and publishing workflow. For platform access and
 sharing options, see [OpenAI's Sites documentation](https://learn.chatgpt.com/docs/sites).
 
+For a new project, start with the [blank generated app](./generated-app.md).
+The article reference below demonstrates a complete editorial Site with R2
+media after you choose that content model.
+
 ## What you get
 
 | Capability | In the Mantle Sites reference |
@@ -34,12 +38,17 @@ boundaries.
 
 ## Start with the supported SDK
 
-You need Node.js 22+, pnpm 9+, and Sites access with D1 and R2 available for your
-project. Follow the reference's local build and smoke test before deployment.
-Keep your application outside the SDK checkout. The included article schema is
-a working example; adapt its fields and lifecycle to your team's content.
+You need Node.js 22+ and Sites access with D1. Start with the
+[blank generated app](./generated-app.md) to choose your own content model;
+it requires no R2 bucket. The article reference also needs R2 for cover
+images. Build and smoke-test locally before deployment, and keep your
+application outside the SDK checkout.
+
+## Follow the article reference when it fits
 
-## Publish your first article
+The steps below apply to the optional prebuilt article example. A new blank
+generated Site has no article Schema, media bucket or content; add those only
+when your requirements call for them.
 
 1. **Prepare the application.** Follow the
    [runnable reference](../../examples/host-chatgpt-sites/README.md#install-and-run).
@@ -81,15 +90,15 @@ staff connector needs its own verified OAuth flow; see the [host reference](./ho
 
 ## Ask your agent to set it up
 
-Install the Mantle agent plugin, or `@aotter/mantle` itself, then describe your
-audience and content requirements:
+Install the Mantle skill and exact SDK version, then describe your audience
+and content requirements:
 
 ```text
 Build a content site with ChatGPT Sites and Mantle. Read
-handbook/chatgpt-sites/index.md and examples/host-chatgpt-sites/README.md from the
-installed Mantle docs, and follow that reference's install and run steps.
-Adapt the article example to my content requirements. Include ChatGPT
-sign-in, Mantle staff roles, cover uploads, and published article pages.
+handbook/chatgpt-sites/generated-app.md from the installed Mantle docs, and
+start from the blank generated Site when that CLI supports it. Use the article
+reference only if its content model matches my requirements. Include ChatGPT
+sign-in and Mantle staff roles; add cover uploads only if I request media.
 Run the local checks and show me a draft-to-publish walkthrough before
 deploying through Sites. Keep remote staff OAuth MCP outside this scope.
 ```
@@ -112,6 +121,7 @@ evidence from the equipment and Slack work still required in your application.
 ## Integration details
 
 - [Host reference](./host-reference.md): identity, migrations, R2 routes, MCP, and deployment checks.
+- [Generated blank app](./generated-app.md): local composition, D1 migration, Admin, and MCP.
 - [Equipment checkout](./equipment-checkout.md): custom business rules and external API delivery without payments.
 - [Runnable application](../../examples/host-chatgpt-sites/README.md): installation, build artifacts, and smoke tests.
 - [Conventional Cloudflare Worker](../cloudflare/conventional-worker.md): the separate path for a Worker you deploy directly.

package/docs/handbook/cloudflare/authentication.md

@@ -7,11 +7,28 @@ Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails close
 
 ## Local Admin: email OTP
 
-The local human path does not use `MANTLE_AUTH_MODE` or GitHub. Pass `auth` to `createMantleWorker` with `email-otp`, `ConsoleEmailSender`, and `bootstrapOwner.match: "email"`. The one-time code is printed on the wrangler log. See [Quickstart: local Admin](../start/quickstart-admin.md). `ConsoleEmailSender` is for `wrangler dev` only; production needs a real sender. The official example binds `127.0.0.1:8787` and sets `PUBLIC_ORIGIN` to that origin; Better Auth rejects OTP with `INVALID_ORIGIN` when they diverge from the origin wrangler prints.
+The generated CF app writes `.dev.vars.example`. Copy it to `.dev.vars` for
+local use, then set `MANTLE_AUTH_MODE=local-otp`, the real `ADMIN_EMAIL`, a
+random `BETTER_AUTH_SECRET`, and the exact loopback `PUBLIC_ORIGIN`. It configures
+its email-OTP auth factory only for a
+loopback origin. If you author the Worker yourself, pass `auth` to
+`createMantleWorker` with `email-otp`, `ConsoleEmailSender`, and
+`bootstrapOwner.match: "email"`; that factory does not read the conventional
+mode matrix. The one-time code is printed in wrangler logs. See
+[Quickstart: local Admin](../start/quickstart-admin.md). `ConsoleEmailSender`
+is for `wrangler dev` only; production needs a real sender. Match
+`PUBLIC_ORIGIN` to wrangler's actual `127.0.0.1:8787` origin or Better Auth
+will reject OTP with `INVALID_ORIGIN`.
+
+For production, the generated Worker's local OTP branch is disabled outside
+loopback. Configure the conventional `self-managed` or `hosted` Auth mode,
+including its required provider credentials and `ADMIN_GITHUB_LOGIN`, instead
+of editing the CLI-owned Worker. An application that needs production email
+delivery should author its own Worker Auth factory and real `EmailSender`.
 
 With `auth` set, the mode matrix below is not read. Core still owns `/admin` and `/api/auth/*`.
 
-For production email OTP, keep the custom `createAuth()` factory, replace
+For production email OTP in a manually authored Worker, keep the custom `createAuth()` factory, replace
 `ConsoleEmailSender` with the application's production `EmailSender`, and keep
 `bootstrapOwner: { match: "email", value: <owner email> }`. Store the sender
 credentials and `BETTER_AUTH_SECRET` as Worker secrets. If the application has

package/docs/handbook/cloudflare/bindings.md

@@ -186,26 +186,19 @@ the interface is one `record(event)` method.
 "triggers": { "crons": ["*/5 * * * *"] }
 ```
 
-A `scheduled()` handler reuses the fetch path's runtime and invokes a Procedure that has no Trigger of its own:
+A `schedule` Trigger declares the Procedure, and the Worker export reuses the same runtime as `fetch`:
 
 ```ts
-import { bindMantle } from "../.mantle/generated/mantle.js";
-
 const worker = createMantleWorker<Env>({ plan, handlers });
 
 export default {
   fetch: worker.fetch,
-  async scheduled(_controller, env, ctx) {
-    const mantle = bindMantle(await worker.getRuntime(env));
-    const result = await mantle.procedures.sweepExpiredOrders(
-      { now: Date.now() },
-      { user: null, staff: null, env, waitUntil: (p) => ctx.waitUntil(p) },
-    );
-    if (!result.ok) throw new Error(`sweep failed: ${result.diagnostic.code}`);
-  },
+  scheduled: worker.scheduled,
 } satisfies ExportedHandler<Env>;
 ```
 
+Register the exact enabled `cron` expression in `wrangler.jsonc`; Mantle does not create provider triggers. The Procedure takes `{}` input and sees `ctx.schedule.id` for retry-safe idempotency. See [Trigger](../reference/trigger.md#schedule-source).
+
 ## Durable Objects (application-owned)
 
 Durable Objects are not a Core primitive. Use one as an application-owned coordinator when a decision must be serialized, for example reserving inventory exactly once. Export the class from the Worker entry, then bind and migrate it:

package/docs/handbook/cloudflare/conventional-worker.md

@@ -3,7 +3,10 @@ description: Assemble a Mantle Worker with createMantleWorker, add handlers and
 ---
 # The conventional Worker
 
-`createMantleWorker` is the normal Cloudflare entry for a Mantle application. This page covers its options, what the facade owns, how to add application handlers and routes, and the readiness and reserved-path rules that keep those extensions safe.
+New applications can start with `mantle generate --host cf`, which writes a
+blank home, Worker entry and selected Admin/API/MCP wiring. This page covers
+the lower-level `createMantleWorker` facade for applications that author their
+own Worker entry: its options, extension seam, readiness and reserved paths.
 
 ## Minimal entry
 
@@ -14,7 +17,7 @@ import { plan } from "../.mantle/generated/mantle.js";
 export default createMantleWorker({ plan, cacheScope: "my-site-production" });
 ```
 
-`plan` is the sealed plan that `mantle generate` writes to `.mantle/generated/mantle.ts`. With only `plan`, the Worker serves public View REST, HTTP Triggers, Admin, Auth, OAuth and MCP. It renders no public pages and `/` is a 404; see [Public web](./public-web.md). Local Admin with email OTP replaces Auth construction; see [Quickstart: local Admin](../start/quickstart-admin.md). Admin still requires the `ASSETS` binding.
+`plan` is the sealed plan that `mantle generate` writes to `.mantle/generated/mantle.ts`. With only `plan`, this manually assembled Worker serves public View REST, HTTP Triggers, Admin, Auth, OAuth and MCP. It renders no public pages and `/` is a 404; see [Public web](./public-web.md). A newly generated full CF project wires a separate editable blank home. Local Admin with email OTP replaces Auth construction; see [Quickstart: local Admin](../start/quickstart-admin.md). Admin still requires the `ASSETS` binding.
 
 ## Options
 
@@ -64,9 +67,10 @@ If `auth.ready` rejects, the memoized assembly is evicted so the next request re
 const worker = createMantleWorker<Env>({ plan });
 worker.fetch(request, env, ctx);   // HTTP entry
 worker.getRuntime(env);            // the runtime fetch uses, resolved after auth.ready
+worker.scheduled(controller, env, ctx); // declared scheduled Procedure Triggers
 ```
 
-Queue and scheduled handlers call `worker.getRuntime(env)` and then generated `bindMantle(runtime)` so they reuse the assembled runtime and never write Mantle tables directly. See [Bindings](./bindings.md#cron-triggers) and [Deferred hooks](./deferred-hooks-queues.md).
+Queue handlers call `worker.getRuntime(env)` and then generated `bindMantle(runtime)` so they reuse the assembled runtime. Scheduled Procedure Triggers use `worker.scheduled` with expressions registered in Wrangler. See [Bindings](./bindings.md#cron-triggers), [Trigger](../reference/trigger.md#schedule-source), and [Deferred hooks](./deferred-hooks-queues.md).
 
 ## Readiness rule
 

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -10,7 +10,7 @@ This page is the production checklist for a Mantle Worker on Cloudflare: what to
 - Pin every `@aotter/mantle*` package to one exact version and commit the lockfile. Install with `pnpm install --frozen-lockfile` (or `npm ci`) from then on. See [Project and CLI](../start/project-and-cli.md).
 - Set `PUBLIC_ORIGIN` to the real HTTPS origin, without a trailing slash. It drives canonical URLs, `.md` mirrors, `llms.txt`, the MCP resource and the OAuth callback. If a static documentation build also emits absolute URLs, give it the same value.
 - Set the production D1 `database_id` (and `account_id` if your deployment needs it) in `wrangler.jsonc`. A local `database_name` is not a production identifier, and local D1 is not production data.
-- Choose production Auth: replace local console email delivery with a real `EmailSender`, or configure `MANTLE_AUTH_MODE` for GitHub OAuth or hosted Auth. Store secrets with `wrangler secret put`. See [Authentication](./authentication.md).
+- Choose production Auth: a generated CF app uses `MANTLE_AUTH_MODE=self-managed` or `hosted` with `ADMIN_GITHUB_LOGIN` and the matching provider credentials. Local `local-otp` works only on loopback. If you author your own Worker Auth factory, replace console email delivery with a real `EmailSender`. Store secrets with `wrangler secret put`. See [Authentication](./authentication.md).
 - Keep `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
 - Enable observability:
 

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -95,6 +95,13 @@ A storage adapter prepares one `RuntimePlan` into semantic ports. Three are requ
 
 Two are optional and only when a feature needs them: `MediaStorage` for upload flows, and `DeferredHookDispatcher` for at-least-once `after_*` delivery. `DatabaseDriver` is not a portability contract — it is the reusable SQLite/D1 seam. A PostgreSQL, MongoDB or application-owned-table adapter implements the semantic ports directly rather than emulating D1.
 
+`PreparedMantleStorage.atomicEntries` is an optional semantic write capability.
+An adapter exposes it only when it can commit an ordered group of entry
+mutations all-or-nothing, including zero-row version/status failures. The
+SQLite implementation covers Cloudflare D1 and Bun; IndexedDB and custom
+adapters without that guarantee leave it absent. Ref Procedures use
+`ctx.writeAtomically` as described in [Procedure](../reference/procedure.md#atomic-entry-writes-in-a-ref-handler).
+
 Declarative Views compile to logical plans once, and preparation lowers those plans to native queries. `View.spec.sql` is the exception: it is explicitly SQLite-only in v0.1. Storage that does not declare that dialect rejects such a View at preparation with `VIEW_DIALECT_UNSUPPORTED`, before mutating any state. Mantle does not guess a translation and ships no universal query driver. A View that must run everywhere uses `from` with a filter AST; see [View](../reference/view.md).
 
 ## Embedding each adapter

package/docs/handbook/guides/agent-setup.md

@@ -62,7 +62,7 @@ pnpm exec mantle skills --check
 |---|---|
 | `.agents/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | The installed package's four project-scoped workflows. |
 | `.claude/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | Identical bytes for Claude compatibility. |
-| `node_modules/@aotter/mantle/skills/` | All seven shipped skills, including opt-in `mantle`, `provision` and `media-gc`. |
+| `node_modules/@aotter/mantle/skills/` | All eight shipped skills, including opt-in `mantle`, `integrate`, `provision` and `media-gc`. |
 | `node_modules/@aotter/mantle/docs/` | Handbook and examples matched to the package. |
 
 `mantle skills` overwrites these four generated projections. Keep project-specific
@@ -84,9 +84,9 @@ It does not prove a server, login, Admin assets or MCP connection works.
 | `skills/install/SKILL.md` is missing | That is source provenance. Read the installer's destination instead. |
 | `docs/...` is missing after `skills add` | The skill does not carry the handbook. Install the pinned SDK and read its embedded docs. |
 | `mantle` is missing | Install local `@aotter/mantle`; run its binary through the project package manager. |
-| `MANIFEST_ROOT_NOT_FOUND` | Author manifests in the configured directory; `generate` is not a scaffold command. |
+| `MANIFEST_ROOT_NOT_FOUND` | Check the installed CLI and saved project selection. New generated projects may start with an empty manifest set; legacy compile mode still needs the configured source. |
 | `mantle skills --check` exits 1 | Run `mantle skills`, then read the refreshed project skill. |
-| No projected provision/media-gc skill | These are intentionally opt-in. Read their installed package files when the task calls for them. |
+| No projected integrate/provision/media-gc skill | These are intentionally opt-in. Read their installed package files when the task calls for them. |
 | A documented feature fails on an older release | Use that release's docs or explicitly upgrade; changing a skill does not change Runtime. |
 
 ## Source

package/docs/handbook/navigation.json

@@ -5,9 +5,9 @@
       "text": "Start here",
       "items": [
         { "text": "Handbook overview", "link": "/start/overview" },
-        { "text": "Project layout and the CLI loop", "link": "/start/project-and-cli" },
+        { "text": "Generate a project and use the CLI", "link": "/start/project-and-cli" },
         { "text": "Quickstart: a minimal Worker", "link": "/start/quickstart-worker" },
-        { "text": "Quickstart: local Admin (opt-in)", "link": "/start/quickstart-admin" },
+        { "text": "Quickstart: authored Worker Admin", "link": "/start/quickstart-admin" },
         { "text": "When the host is ChatGPT Sites", "link": "/chatgpt-sites/index" }
       ]
     },
@@ -50,6 +50,7 @@
       "text": "ChatGPT Sites",
       "items": [
         { "text": "Get started", "link": "/chatgpt-sites/index" },
+        { "text": "Generate a blank app", "link": "/chatgpt-sites/generated-app" },
         { "text": "Host reference", "link": "/chatgpt-sites/host-reference" },
         { "text": "Equipment checkout and external APIs", "link": "/chatgpt-sites/equipment-checkout" },
         { "text": "Earlier guide URL", "link": "/cloudflare/chatgpt-sites" }

package/docs/handbook/reference/diagnostics.md

@@ -81,11 +81,16 @@ Raised by the parser, the graph validator and the code generator. `mantle valida
 | `UNIQUE_INDEX_FIELD_UNKNOWN` | A `uniqueIndexes` field is not a top-level Schema property. | — |
 | `SCHEMA_SEARCH_INVALID` | `searchableFields` repeats an entry or names a non-string property. | — |
 | `SCHEMA_SEARCH_FIELD_UNKNOWN` | A `searchableFields` entry is not a Schema property. | — |
+| `SCHEMA_TTL_INVALID` | TTL must name a top-level date-time field and a finite nonnegative duration. | — |
+| `SCHEMA_TTL_TRANSLATION_UNSUPPORTED` | TTL on either side of a translation join cannot guarantee the joined content's expiry. | — |
+| `VIEW_TTL_NATIVE_UNSAFE` | A native SQL View cannot guarantee logical expiry while a Schema has TTL. | — |
 | `SCHEMA_UI_INVALID` | A Schema or Procedure `uiSchema` rule is broken, including unknown roots, invalid `nav.standalone`, or a Schema declaring `uiSchema.collectionAction`. | — |
 | `HANDLER_BUILTIN_NOT_IN_V010` | A builtin Procedure was invoked on a runtime assembled without the builtin collaborator. | — |
 | `MANIFEST_ROOT_NOT_FOUND` | The manifests directory is missing, unreadable, or contains no `.yaml` or `.yml` file. | — |
 | `MANIFEST_READ_FAILED` | A manifest source could not be read. | — |
 | `CODEGEN_IDENTIFIER_COLLISION` | Two names in one group collapse to the same generated lower-camel identifier. | — |
+| `SCHEDULE_INPUT_INVALID` | A scheduled Procedure cannot accept the empty object supplied by its system Trigger. | — |
+| `SCHEDULE_AUTH_INVALID` | A scheduled Procedure requires user or staff authority that the system caller never has. | — |
 | `FIXTURE_SCHEMA_VIOLATION` | Reserved for consumer-authored test diagnostics on the `test` phase. Core emits purpose-shaped harness reports instead. | — |
 
 ## Cross-phase

package/docs/handbook/reference/procedure.md

@@ -207,7 +207,7 @@ An HTTP Trigger wraps a success as `{ "ok": true, "data": <EntryRow> }` with sta
 
 ## Conflicts and idempotency
 
-A unique-index preflight runs before every write, and the database's own constraints catch the races the preflight misses. Both surface as `CONFLICT` (409), as do a stale `expectedVersion` and an illegal lifecycle transition. **There is no automatic retry** — the caller decides whether to re-read and try again.
+A unique-index preflight runs before individual writes, and the database's own constraints catch the races the preflight misses. Atomic groups rely on the transaction's database constraints so an earlier operation may free a unique value for a later one. Both paths surface collisions as `CONFLICT` (409), as do a stale `expectedVersion` and an illegal lifecycle transition. **There is no automatic retry** — the caller decides whether to re-read and try again.
 
 Idempotency has no grammar key. The convention is an `input` property marked `x-mcp-hint: idempotency-key`: Admin generates and hides one UUID per form submission, and other callers generate one and reuse it across retries of the same logical request. The handler is responsible for acting on it.
 
@@ -215,6 +215,57 @@ Optimistic concurrency uses the reserved input name `expectedVersion` — the ve
 
 Deferred lifecycle hooks have a stronger guarantee to work with: delivery is at-least-once, and handlers key on `${ctx.event.id}:${ctx.event.trigger}` — stable across enqueue fallback, queue retries and replay. See [Deferred hooks on Queues](../cloudflare/deferred-hooks-queues.md).
 
+## Atomic entry writes in a ref handler
+
+When one request must change several Schemas together, a `ref` handler can call
+`ctx.writeAtomically(operations)`. Cloudflare D1 and Bun SQLite support it; an
+adapter without the optional `atomicEntries` capability returns
+`RESOURCE_UNAVAILABLE` (503)
+instead of committing part of the group. Operations use the `createDraft`,
+`updateDraft`, or `deleteEntry` request shape; atomic deletes additionally
+require `expectedVersion`. Operational Schemas become live on create;
+publishing Schemas create drafts. Updates and deletes require the version the
+caller read.
+
+```ts
+const sessionId = crypto.randomUUID();
+const rows = await ctx.writeAtomically!([
+  { kind: "create", id: sessionId, request: {
+    collection: "sessions", data: { name: input.name }, authorId: ctx.user?.id ?? null, ctx,
+  } },
+  { kind: "create", request: {
+    collection: "exercise-blocks", data: { sessionId, exercise: input.exercise },
+    authorId: ctx.user?.id ?? null, ctx,
+  } },
+  { kind: "create", request: {
+    collection: "receipts", data: { token: input.requestId }, authorId: ctx.user?.id ?? null, ctx,
+  } },
+]);
+return { sessionId: rows[0]!.id };
+```
+
+Declare `receipts.token` as a Schema `uniqueIndexes: [[token]]`. A duplicate
+receipt rejects the whole group, including the session and block. The handler
+can then read the existing receipt **after** the failed transaction to answer
+an idempotent retry. A stale update or delete rejects the whole group even
+when it is the final operation. The group may touch each entry only once;
+read and authorization decisions happen before the batch, and the expected
+version/status is checked again by the conditional database write.
+
+All Schema projection, stamping, validation, uniqueness, and lifecycle rules
+still apply. `before_*` hooks run in operation order before the batch and can
+veto it; their external effects cannot be rolled back. `after_*` hooks run
+only after commit, in operation order. Publishing-content invalidation runs
+once for the group. Deferred Queue delivery is separate from the database
+transaction. Application-owned tables can use their host's transaction
+facility inside a ref handler, but that does not give those tables Mantle
+entry semantics. Direct SQL writes to Mantle Schema tables are unsupported.
+Authorization guard Procedures do not receive `ctx.writeAtomically`.
+
+## TTL sweep in a ref handler
+
+`ctx.sweepExpired({ collection, limit })` previews a bounded page of expired rows; `delete: true` explicitly removes it. The result contains `scanned`, `removed` and an optional `nextCursor`. Continue with that cursor until absent. D1 and Bun SQLite implement this semantic capability; unsupported storage returns `RESOURCE_UNAVAILABLE`. Authorization guard Procedures do not receive the sweep function. For a scheduled cleanup, declare a [schedule Trigger](./trigger.md#schedule-source) targeting a no-input ref Procedure. No sweep is scheduled automatically. See [Schema TTL](./schema.md#ttl).
+
 ## `uiSchema`
 
 Admin presentation only. It never affects input validation, the MCP tool schema or the OpenAPI document. Roots are closed: `collectionAction` and `fields`.

package/docs/handbook/reference/schema.md

@@ -1,5 +1,5 @@
 ---
-description: Schema field reference — JSON Schema subset, extension keywords, uiSchema, indexes, searchable fields, translates and lifecycle rules.
+description: Schema field reference — JSON Schema subset, uiSchema, indexes, translates, lifecycle and TTL rules.
 ---
 # Schema
 
@@ -19,6 +19,7 @@ A Schema declares one collection: the JSON Schema for each entry's `data`, its i
 | `localized` | boolean | no | `false` | When `false`, a `locale` property is rejected. Must be a boolean. |
 | `translates` | `{ parent, on }` | no | — | Marks a translation child. Requires `localized: true`. |
 | `lifecycle` | `publishing` \| `operational` | no | `publishing` | Selects the [state machine](#lifecycle). |
+| `ttl` | `{ field, expireAfterSeconds }` | no | — | Logical expiry over one top-level date-time property. See [TTL](#ttl). |
 
 ### Reserved entry columns
 
@@ -242,6 +243,31 @@ Every authoring path (Admin, Staff MCP, builtin Procedures) runs the same guard
 
 Site locales are configured in [Site config](./site-config.md).
 
+## TTL
+
+```yaml
+spec:
+  ttl: { field: expiresAt, expireAfterSeconds: 0 }
+  schema:
+    type: object
+    properties:
+      expiresAt: { type: string, format: date-time, nullable: true }
+```
+
+`field` must name one top-level `date-time` string property; `expireAfterSeconds` is finite and nonnegative. An entry expires when its timestamp plus the duration is **at or before** the current instant. Missing or null dates never expire. `SCHEMA_TTL_INVALID` rejects invalid policies.
+
+Legacy values that SQLite cannot parse as dates also remain visible and are not swept; correct those rows before relying on TTL. New writes must pass the Schema's date-time validation.
+
+Expiry is logical first: Entry, declarative View, Admin, MCP and Web reads stop returning the row at the boundary, even before a sweep deletes it. A native SQL View cannot guarantee that filter and is rejected (`VIEW_TTL_NATIVE_UNSAFE`) while any Schema has TTL. A View over a TTL Schema cannot use shared caching (`VIEW_CACHE_INVALID`). Bun and D1 use the same SQLite predicate; other storage adapters must supply equivalent read filtering or reject the plan.
+
+TTL is currently rejected on either side of a `translates` relationship (`SCHEMA_TTL_TRANSLATION_UNSUPPORTED`), because a translation child could otherwise remain visible after its parent expires.
+
+Physical cleanup is **explicit**. `runtime.sweepExpired({ collection: "events", limit: 50 })` previews one page; add `delete: true` to remove it. Follow `nextCursor` until absent. The limit is 1–100, `scanned` counts expired candidates and `removed` counts successful deletes. A failure throws and the previous cursor is safe to retry. Ref Procedures can call `ctx.sweepExpired`; a Cloudflare schedule may invoke such a Procedure. The sweep does not fire entry lifecycle hooks: expiration already changed logical visibility, and the sweep only reclaims storage (ADR-0028).
+
+The Developer Console shows declared TTL policies. It does not infer sweep history from a policy; a scheduled Procedure can return `scanned` and `removed` counts to include them in its run observation.
+
+Adding or shortening TTL on an existing Schema immediately changes **read visibility**, but never starts a deletion job. Preview a sweep and review its counts before requesting `delete: true`. Keep a backup when changing the policy on populated data. Physical unique constraints still see expired rows until cleanup, so a reused unique value may conflict before the sweep.
+
 ## Source
 
 - [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)

package/docs/handbook/reference/surface.md

@@ -116,14 +116,14 @@ The `@aotter/mantle` package installs two binaries, `mantle` and `mantle-harness
 
 | Command | Flags |
 |---|---|
-| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--check`, `-h, --help` |
+| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--host cf\|chatgpt-sites`, `--features <list>`, `--review-unique-indexes` (managed Sites only), `--check`, `-h, --help` |
 | `mantle skills` | `--check`, `-h, --help` |
 | `mantle validate` | `--manifests <dir>` (default `./manifests`), `--source <dir>` (default `./src`), `--no-source`, `--phase preview\|deploy` (default `preview`), `--format json\|text` (default by TTY), `--json`, `-h, --help` |
 | `mantle emit-openapi` | `--manifests <dir>`, `--title <str>` (default `mantle`), `--version <str>` (default `0.1.0`), `--session-cookie-name <str>`, `-o, --output <file>`, `-h, --help` |
 | `mantle-harness indexes` | `--manifests <dir>`, `--rows <n>`, `--require <view>` (repeatable), `--require-public`, `--format json\|text`, `-h, --help` |
 | `mantle-harness http` | `--route <name=url>` (repeatable, required), `--base-url <url>`, `--rounds <n>`, `--warmup <n>`, `--format json\|text`, `-h, --help` |
 
-`generate` validates and compiles the manifest directory, writes the typed module, and — when `@aotter/mantle-admin-ui` is installed — syncs the Admin SPA into `public/_mantle/admin/`, excluding `server.*` files. `--check` fails without writing when either output is stale. `skills` copies every skill the installed package marks `projection: project` into `.agents/skills/mantle-*` and `.claude/skills/mantle-*`; both layouts receive identical bytes. `validate --phase deploy` adds the pre-deploy-only gates on top of the grammar and cross-Schema checks. `emit-openapi` covers HTTP Triggers and View REST routes; MCP is out of scope. `mantle-harness indexes` executes compiled Views against crowded SQLite and inspects query plans; `http` samples a running Worker for p50 and p95. Day-to-day use is in [Project and CLI](../start/project-and-cli.md).
+`generate` assembles new hosted projects with full Spec/Runtime/API/MCP/Admin/Web by default, or a smaller positive `--features` selection, then validates and compiles manifests into a typed module. Saved selections rerun safely; legacy authored projects keep compile mode. Selected Admin syncs its prebuilt SPA into `public/_mantle/admin/`. `--check` fails without writing on drift. `skills` copies project-scoped skills into `.agents/skills/mantle-*` and `.claude/skills/mantle-*`. `validate --phase deploy` adds pre-deploy checks; `emit-openapi` covers HTTP Triggers and View REST routes. `mantle-harness indexes` checks SQLite plans, while `http` samples a running Worker. [Project and CLI](../start/project-and-cli.md) has the install and ownership sequence.
 
 ## The generated module
 
@@ -182,7 +182,7 @@ This handbook describes the snapshot in this source tree. Pin every `@aotter/man
 
 The documentation site pins its handbook commit in `docs/handbook.json` and records its vendored SDK source in `vendor/mantle/SOURCE.txt`. Those commits may differ when the intervening changes are behavior-neutral; the site verifies that condition during the build.
 
-Projects are authored directly: write the manifests, run `generate`, `skills`, `validate` and `emit-openapi`, and wire the Worker. There is no project generator. Prerelease packages take their exact version from their own `package.json`; APIs may change between prereleases until a stable line ships.
+New projects can use `generate` to assemble a blank hosted app. Existing authored Workers can keep their own entry and use the same CLI for typed compilation. Pin all selected packages to one exact SDK version; prerelease APIs can change until stable publication.
 
 ## Source
 

package/docs/handbook/reference/trigger.md

@@ -1,5 +1,5 @@
 ---
-description: Trigger field reference — http, mcp and lifecycle sources, path and tool-name rules, the eight lifecycle hooks and their timing and error policy.
+description: Trigger field reference — http, mcp, lifecycle and schedule sources, routing rules, and delivery semantics.
 ---
 # Trigger
 
@@ -19,9 +19,29 @@ A Trigger binds one source to one [Procedure](./procedure.md). Every external su
 | `http` | `method`, `path` | One REST endpoint under `/api/`. |
 | `mcp` | `surface` | One tool on `/mcp` or `/mcp/staff`. |
 | `lifecycle` | `schema`, `on`, `errorPolicy` | Entry-writer hooks on one Schema. |
+| `schedule` | `cron`, optional `enabled` | A Cloudflare Cron Trigger calling one Procedure. |
 
 An unknown `kind`, a missing `kind`, or a key that does not belong to the chosen kind is `INVALID_MANIFEST_ENVELOPE`. One Procedure may carry several Triggers — that is how the same handler becomes an HTTP endpoint and an MCP tool without duplicating logic.
 
+## `schedule` source
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata: { name: nightly-cleanup }
+spec:
+  source: { kind: schedule, cron: "0 2 * * *" }
+  target: { procedure: clean-expired-records }
+```
+
+`cron` is a five-field Cloudflare UTC expression (minute, hour, day, month, weekday). Each field accepts `*`, a number, a range, comma-separated values, or `*/step` / `start-end/step`. Weekdays are **1 = Sunday through 7 = Saturday**; use `2-6` for Monday–Friday. Month and weekday names and provider-specific extensions are outside this subset. `enabled` defaults to `true`; a disabled schedule remains in the compiled plan but never invokes its Procedure. The target Procedure must accept `{}` as input (`SCHEDULE_INPUT_INVALID`) and have no user/staff authorization requirements (`SCHEDULE_AUTH_INVALID`). The schedule creates no public HTTP or MCP route.
+
+On Cloudflare, add each enabled expression to `wrangler.jsonc` under `triggers.crons` and export the `scheduled` method returned by `createMantleWorker`. Mantle does not provision the provider trigger. A disabled expression still registered in Wrangler is ignored; an expression absent from the Mantle plan fails visibly. If the Worker also owns unrelated cron tasks, route those expressions in the application's `scheduled` export. Multiple Mantle Triggers may share one expression and run in Trigger-name order; all run even if an earlier one fails, then the event reports failure.
+
+Handlers receive `ctx.schedule` with `id`, `trigger`, `cron`, and `scheduledTime` (Unix milliseconds). The stable ID is `${trigger}:${scheduledTime}`. The caller is always `user: null`, `staff: null`, with no credential metadata; normal Procedure guards still apply. Cloudflare executes cron events in UTC, but its Cron Trigger documentation does not promise automatic retries. Duplicate/manual replay is still possible, so use `ctx.schedule.id` as an idempotency key for writes. A failure rejects the scheduled event; exactly-once execution is not promised. Bun, Vercel, and ChatGPT Sites do not register schedules and reject enabled schedules at boot or generation.
+
+Cloudflare's default D1 composition records each attempt under that stable run ID. The owner-only Developer Console shows declared schedules even before the first run, separately from recent observations; Wrangler registration is **not observed** by Core. Records include scheduled/start/finish times, status, attempt, duration, a diagnostic code or generic handler-error summary, and optional sweep counts. A started attempt with no finish record says **Completion not observed**, not success. Inputs, outputs, exception text, credentials and secrets are not stored. The default history retains 30 days, hides older rows on reads, and prunes them during later runs (at most once per day per runtime instance). If observation start fails, the Procedure is skipped and the scheduled event rejects; if recording completion fails, the event also rejects. Use the stable ID to make replay safe. If the host supplies custom storage without a durable observation store, the Console says **Unavailable**; it never reports a missing record as success.
+
 ## `http` source
 
 ```yaml

package/docs/handbook/releases/index.md

@@ -21,6 +21,61 @@ 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.
+
 ## 0.1.4 — 2026-09-24
 
 0.1.4 repairs the published consumer path without changing the Manifest

package/docs/handbook/start/overview.md

@@ -21,6 +21,7 @@ current npm `latest` contains it.
 |---|---|---|
 | 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. |
@@ -28,8 +29,10 @@ current npm `latest` contains it.
 | 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.
+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