@aotter/mantle 0.1.3 → 0.1.5-alpha.1

package/docs/handbook/cloudflare/media-r2.md

@@ -3,7 +3,7 @@ description: Enable staff media uploads on R2 — presigned PUT flow through Sta
 ---
 # Media uploads with R2
 
-R2-backed media is an optional post-launch capability for Workers whose staff or agents need to upload images and files. This page covers the native Cloudflare direct-to-R2 flow, the configuration it needs, how a Schema references an asset, what a commit costs, and how to clean up. For ChatGPT Sites with an R2 binding but no S3 credentials, use [the same-origin Worker flow](../sites/host-reference.md#media-with-only-an-r2-binding).
+R2-backed media is an optional post-launch capability for Workers whose staff or agents need to upload images and files. This page covers the native Cloudflare direct-to-R2 flow, the configuration it needs, how a Schema references an asset, what a commit costs, and how to clean up. For ChatGPT Sites with an R2 binding but no S3 credentials, use [the same-origin Worker flow](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
 
 ## When to enable it
 
@@ -213,4 +213,4 @@ The full catalog is in [Diagnostic codes](../reference/diagnostics.md).
 - [`packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts`](../../../packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts)
 - [`packages/mantle-spec/src/kernel/diagnostic.ts`](../../../packages/mantle-spec/src/kernel/diagnostic.ts)
 - [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`skills/media-gc/SKILL.md`](../../../skills/media-gc/SKILL.md)
+- [`docs/skills/media-gc/SKILL.md`](../../skills/media-gc/SKILL.md)

package/docs/handbook/concepts/four-atoms.md

@@ -170,4 +170,4 @@ Postgres exposes roughly twenty-five object kinds; an application developer writ
 - [`docs/adr/0012-views-as-public-rest.md`](../../../docs/adr/0012-views-as-public-rest.md)
 - [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
 - [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/lifecycle-and-locales.md

@@ -139,4 +139,4 @@ The full worked version of this pattern, with a locale-parameterized public View
 - [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
 - [`packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts`](../../../packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts)
 - [`packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts`](../../../packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/mcp-and-agents.md

@@ -68,6 +68,25 @@ Only `status: published` entries appear anywhere in that set. Details are in [Pu
 
 ## WebMCP in the browser
 
+### Admin: tools for the signed-in staff member
+
+Admin UI registers staff tools in browsers supporting `document.modelContext`.
+The catalog comes from `GET /admin/api/webmcp`; calls use
+`POST /admin/api/mcp` with the current staff session. Server-side role checks,
+Procedure authorization, and optimistic concurrency remain in force.
+`admin_get_context` and `admin_navigate` add page context and navigation.
+The WebMCP control appears after registration succeeds; unsupported browsers
+can continue using the regular Admin UI.
+
+Owners can explore application API documentation in Developer UI:
+`/admin/dev/docs/api` for HTTP, `/admin/dev/docs/mcp` for remote MCP, and
+`/admin/dev/docs/webmcp` for the Admin catalog and public-page capabilities.
+These pages show projected definitions. Remote clients connect to the host's
+advertised MCP endpoints using the authentication described above.
+See the [Admin API guide](../../../packages/mantle-admin/README.md#admin-webmcp).
+
+### Public pages: opt-in registration
+
 `@aotter/mantle-web/webmcp` exposes public capabilities as tools inside a page, for browsers implementing the draft imperative WebMCP API. Importing the subpath has no side effect; registration starts only when `bindWebMcp()` is called.
 
 ```ts
@@ -78,7 +97,7 @@ const binding = await bindWebMcp();
 binding.dispose();
 ```
 
-It feature-detects `document.modelContext` and returns `{ supported: false }` on browsers without it. Only public capabilities are registered — staff capabilities never leave the server. Existing host tool names are inspected and skipped, never replaced. A server-backed page discovers the safe descriptors published at `GET /api/views` and calls the same-origin `GET /api/views/<name>` routes; a browser-local SPA passes `projectCallableCapabilities(plan, { surface: "public" })` and its own invoker. Procedure tools must still originate from an explicit public MCP Trigger, and invocation enters the runtime through that Trigger, so browser tools cannot bypass validation or authorization. See [Runtime pipeline and adapters](./runtime-and-adapters.md).
+It feature-detects `document.modelContext` and returns `{ supported: false }` on browsers without it. This public-page binding registers only public capabilities. Staff tools use the separate authenticated Admin integration above. Existing host tool names are inspected and skipped, never replaced. A server-backed page discovers the safe descriptors published at `GET /api/views` and calls the same-origin `GET /api/views/<name>` routes; a browser-local SPA passes `projectCallableCapabilities(plan, { surface: "public" })` and its own invoker. Procedure tools must still originate from an explicit public MCP Trigger, and invocation enters the runtime through that Trigger, so browser tools cannot bypass validation or authorization. See [Runtime pipeline and adapters](./runtime-and-adapters.md).
 
 ## Skills for your coding agent
 
@@ -91,11 +110,12 @@ pnpm exec mantle skills --check
 
 This copies every skill the installed package marks `projection: project` — the develop skill among them — into matching `.agents/skills/mantle-*` and `.claude/skills/mantle-*` paths. Both layouts receive identical bytes; `--check` detects drift without writing. Skills that act destructively or target one platform stay out of that set and are opt-in. Manifest generation never rewrites agent instructions.
 
-The same bundle is installable from the plugin marketplace:
+The bootstrap `mantle` skill is also available from the plugin marketplace.
+The ongoing workflows come from the installed SDK through `mantle skills`:
 
 ```sh
 # Canonical
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 
 # Claude Code — two separate prompts
 /plugin marketplace add aotter/mantle
@@ -111,4 +131,4 @@ Never point a versioned project at a mutable branch. See [Project layout and the
 - [`packages/mantle-web/README.md`](../../../packages/mantle-web/README.md)
 - [`packages/mantle/README.md`](../../../packages/mantle/README.md)
 - [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/procedures-and-triggers.md

@@ -218,4 +218,4 @@ Register the two `ref` keys in the project's handlers map, then run the check lo
 - [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
 - [`packages/mantle-runtime/src/domain/service/BuiltinProjector.ts`](../../../packages/mantle-runtime/src/domain/service/BuiltinProjector.ts)
 - [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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
@@ -174,4 +181,4 @@ If a normal feature cannot be expressed through a purpose-shaped surface, treat
 - [`packages/adapters/bun/README.md`](../../../packages/adapters/bun/README.md)
 - [`packages/adapters/vercel/README.md`](../../../packages/adapters/vercel/README.md)
 - [`packages/adapters/indexeddb/README.md`](../../../packages/adapters/indexeddb/README.md)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/views.md

@@ -189,4 +189,4 @@ spec:
 - [`packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts`](../../../packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts)
 - [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
 - [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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

@@ -9,12 +9,12 @@ application's SDK. Installing one does not install the other.
 ## 1. Install the bootstrap skill
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
-The installer selects the repository's `install` skill. Read its printed
+The installer selects the repository's `mantle` skill. Read its printed
 installation path. In a project-local Codex installation that is
-`.agents/skills/install/SKILL.md`, not `skills/install/SKILL.md` (the latter is
+`.agents/skills/mantle/SKILL.md`, not `skills/install/SKILL.md` (the latter is
 its source-repository path). Other agent selections and global installation
 can use different locations.
 
@@ -32,6 +32,7 @@ version. `latest` and `alpha` can describe different capabilities. Resolve only
 requirements the user has not provided: host, storage, public API/HTML, and
 whether staff need Admin. Follow the bootstrap skill to install the selected
 packages locally.
+No matching `mantle-starters` tag or bundle is needed to create a project.
 
 Then read:
 
@@ -44,7 +45,7 @@ node_modules/@aotter/mantle/docs/handbook/reference/features.md
 These files are in the npm tarball. They are the version-matched authority,
 including when the bootstrap skill came from a different Git ref. Every
 `docs/...` path in the skill resolves under the installed package, not under
-`.agents/skills/install/`. Keep using that SDK's docs for host examples and CLI
+`.agents/skills/mantle/`. Keep using that SDK's docs for host examples and CLI
 behavior. No local `mantle` binary is available before package installation.
 
 ## 3. Project the ongoing workflows
@@ -61,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 `install`, `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
@@ -83,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,10 +5,10 @@
       "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": "When the host is ChatGPT Sites", "link": "/sites/index" }
+        { "text": "Quickstart: authored Worker Admin", "link": "/start/quickstart-admin" },
+        { "text": "When the host is ChatGPT Sites", "link": "/chatgpt-sites/index" }
       ]
     },
     {
@@ -49,9 +49,10 @@
     {
       "text": "ChatGPT Sites",
       "items": [
-        { "text": "Get started", "link": "/sites/index" },
-        { "text": "Host reference", "link": "/sites/host-reference" },
-        { "text": "Equipment checkout and external APIs", "link": "/sites/equipment-checkout" },
+        { "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,86 @@ 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
+grammar. Pin every selected `@aotter/mantle*` package to `0.1.4`, refresh the
+lockfile, then rerun `mantle generate` and `mantle skills` with their `--check`
+commands. Read the handbook and skills from that installed version.
+
+**ChatGPT Sites reference.** The 0.1.3 reference omitted the
+`_mantle_boot_state.store_instance_id` column required by the runtime, which
+could make deployed runtime routes return 500. The reference now adds the
+append-only `drizzle/0003_store_instance_id.sql` migration. If your project
+was copied from that reference, carry the new migration forward and apply
+pending D1 migrations **before** deploying updated code; do not edit a
+migration already applied. Repeated builds now clear `dist` so removed SQL
+files cannot remain in the deployment artifact. The Sites guide also shows
+how to mount an HTTP Trigger, identifies the browser and MCP owner workflows,
+and names its integration chapter `docs/handbook/chatgpt-sites/`.
+
+**Agent installation.** `npx skills add aotter/mantle` installs the small
+`mantle` bootstrap skill; the installed npm package supplies version-matched
+instructions and docs. The skill now checks the application's installed
+version before reading them. Superseded Starter decisions are marked as
+history: no `mantle-starters/v0.1.4` tag or `mantle create` command is needed
+to author a new application.
+
 ## 0.1.3 — 2026-09-23
 
 0.1.3 tightens the contract between Manifests, generated TypeScript, agent
@@ -98,7 +178,7 @@ See [HTTP, MCP, CLI and packages](../reference/surface.md) for the full list.
 D1 and assets bindings, Better Auth 1.7 (social providers, email OTP, magic
 link, passkey), Admin, MCP, Web and R2 media uploads. The Bun and Vercel
 adapters are experimental, cover public Views and HTTP Triggers only, and leave
-authentication and CSRF to the host. [ChatGPT Sites](../sites/index.md) is a
+authentication and CSRF to the host. [ChatGPT Sites](../chatgpt-sites/index.md) is a
 first-class integration with a runnable reference.
 
 **Agents.** `mantle skills` projects the installed package's skills into

package/docs/handbook/start/overview.md

@@ -21,15 +21,18 @@ 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. |
-| Build on ChatGPT Sites | [Sites integration](../sites/index.md) | Host-owned sign-in and deployment with Mantle content. |
+| 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.
+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