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

package/docs/handbook/reference/site-config.md

@@ -1,222 +1,69 @@
 ---
-description: siteDefaults reference — locales, brand, icons, media purposes, the runtime SiteConfig read shape, site_config row ownership and what boot validates.
+description: The optional site capability in Mantle 0.2.0 — SiteDefaults passed to the storage adapter, the site_config table, which fields are seeded or synced, Admin's site routes and media purposes.
 ---
-# Site config
+# Site defaults and `site_config`
 
-Site config is a sibling of the Manifest grammar, not part of it. The four atoms describe content; `siteDefaults` describes the deployment: the locales the site publishes in, its brand and title, its canonical origin, its icons and its media taxonomy. Tracking pixels, search-engine verification tokens and similar chrome are host-owned — consumers ship SSR documents, SPAs, Workers plus assets, Pages and custom wrappers, so Core does not rewrite `</head>` after the fact. See [Why Core does not inject](../cloudflare/site-chrome.md#why-core-does-not-inject). The deployment declares `siteDefaults` as a TypeScript object and passes it to the adapter; the runtime seeds it into the `site_config` table and every render, MCP catalog build and Admin page reads it back from there.
-
-## `siteDefaults`
-
-| Key | Type | Required | Rules |
-|---|---|---|---|
-| `locales` | `string[]` | no | Ordered. `locales[0]` is the canonical locale. Empty or omitted turns the locale subsystem off site-wide. Every entry must canonicalize; see [Boot validation](#validated-at-boot). |
-| `brand` | string | no | Operator-facing label for Admin chrome and MCP `serverInfo.title`. Distinct from `title`. |
-| `title` | string | no | Site title — `<title>` suffix and `og:site_name`. |
-| `description` | string | no | Default `<meta name="description">` and `og:description` for entries with none. |
-| `origin` | string | no | Canonical absolute origin, no trailing slash, for example `https://example.com`. Used to build absolute URLs in `/llms.txt`, the `.md` mirrors and `/sitemap.xml`. An empty origin yields relative URLs. |
-| `icons` | `SiteIcon[]` | no | One site identity reused by browser favicons, Admin chrome and MCP `serverInfo.icons`. Declaring an empty array is an error. |
-| `media.purposes` | `MediaPurposePolicy[]` | no | The upload taxonomy. Omitting the key, or declaring an empty array, keeps first-party media uploads disabled. |
-
-Nothing in this object is validated for length or content beyond the rules above: `brand`, `title`, `description` and `origin` are free strings.
-
-## `SiteIcon`
-
-```ts
-interface SiteIcon {
-  readonly src: string;
-  readonly mimeType?: "image/png" | "image/jpeg" | "image/svg+xml" | "image/webp";
-  readonly sizes?: readonly string[];
-  readonly theme?: "light" | "dark";
-}
-```
-
-| Field | Rules |
-|---|---|
-| `src` | Either root-relative (starts with a single `/`, no whitespace, no backslash) or an absolute `https:` URL. Anything else is rejected. |
-| `mimeType` | Optional. One of the four listed types. |
-| `sizes` | Optional. When present, a non-empty array whose entries are `any` or `<width>x<height>` with non-zero decimal dimensions, for example `64x64`. |
-| `theme` | Optional. `light` or `dark`. |
-
-When the deployment declares no icons, the runtime stores `DEFAULT_SITE_ICONS`:
-
-```ts
-const DEFAULT_SITE_ICONS = [
-  { src: "/_mantle/admin/favicon.png", mimeType: "image/png", sizes: ["64x64"] },
-  { src: "/_mantle/admin/favicon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
-];
-```
-
-Multiple renditions are allowed. Keep SVG as the source and add a PNG rendition when a target MCP client needs a baseline raster format. `GET /favicon.ico` resolves against this list; see [Surface](./surface.md).
-
-## `MediaPurposePolicy`
-
-```ts
-interface MediaPurposePolicy {
-  readonly name: string;
-  readonly required: readonly string[];
-  readonly maxBytes: Readonly<Record<string, number>>;
-}
-```
-
-| Field | Rules |
-|---|---|
-| `name` | The slug callers pass as `purpose`. Must match `^[a-z0-9]+(-[a-z0-9]+)*$`: lowercase alphanumerics, dash-separated, no leading, trailing or repeated dashes. |
-| `required` | Ordered list of acceptable mime **slots**, at least one. Each entry uses the HTML `<input accept>` grammar. |
-| `maxBytes` | Per-mime byte cap keyed by fully expanded mime type. Must name every mime that appears in any slot after expansion, and every value must be a positive number. |
-
-A slot entry is one of a full mime (`image/jpeg`), a comma-list of full mimes (`image/jpg,image/png`, meaning either is acceptable for that slot), or a shorthand subtype (`webp` expands to `image/webp`, `jpg` and `image/jpg` both expand to `image/jpeg`). Whitespace around commas is tolerated.
-
-Slot position does not determine variant role. Per asset the uploading agent picks one mime per slot and independently declares exactly one supplied variant as `primary` — the format `<img>` falls back to — with the rest `alternate`, preferred through `<picture><source>`. Because a variant maps to a slot by its mime alone, mime sets across slots must not overlap; an overlap is rejected at boot rather than per upload.
-
-## Runtime `SiteConfig`
-
-`siteDefaults` is the author-time declaration. `SiteConfig` is the read shape that templates, the MCP catalog and Admin see after the seed has run and an operator has had a chance to edit.
-
-| Field | Type | Value when the row is absent |
-|---|---|---|
-| `title` | string | `"CMS"` |
-| `description` | string | `""` |
-| `origin` | string | `""` |
-| `brand` | string | `"AotterMantle"` |
-| `locales` | `readonly string[]` | `[]` |
-| `canonicalLocale` | `string \| null` | `locales[0]` or `null` when the list is empty |
-| `icons` | `readonly SiteIcon[]` | `DEFAULT_SITE_ICONS` |
-| `media.purposes` | `readonly MediaPurposePolicy[]` | `[]` |
-
-`canonicalLocale` is computed, never stored. Templates emit `<html lang>` only when it is non-null; silent omission is the correct behaviour for a zero-locale site, not a fabricated default.
-
-## `site_config` rows
-
-The table is a flat key/value store. Keys fall into two ownership classes, and the seed treats them differently.
-
-| Key | Ownership | Written by seed | Source of truth |
-|---|---|---|---|
-| `brand` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
-| `title` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
-| `description` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
-| `origin` | Code-canonical, boot-synced | Upsert when the stored value differs | The declaration |
-| `faviconUrl` | Code-canonical, boot-synced | Upsert when the stored value differs; holds the `icons` array as JSON | The declaration |
-| `locales` | Code-canonical, boot-synced | Upsert when the stored value differs; holds the declared list as a comma-separated string | The declaration |
-| `mediaPurposes` | Code-canonical, boot-synced | Upsert when the stored value differs; holds the purposes array as JSON | The declaration |
-
-Blank values are skipped in both classes: an absent, empty or empty-array field never writes and never clears an existing row, so a partial declaration cannot clobber stored values. The boot-synced keys are read-compared before writing, so an unchanged deployment issues no write.
-
-The seed-once keys have an Admin edit path at `PATCH /admin/api/site-settings` (owner only); the boot-synced keys do not, which is why the declaration wins on every boot. A custom-domain change therefore becomes canonical by editing the code and redeploying, with no manual database edit.
-
-## Validated at boot
-
-Storage preparation calls `assertSiteDefaultsCanonical(siteDefaults)` synchronously, before the runtime accepts traffic. It throws — it does not return diagnostics — so a typo rejects the deployment rather than corrupting the seed.
-
-| Error | Thrown when |
-|---|---|
-| `InvalidSiteDefaultsError` | Any declared locale fails canonicalization. Carries `invalidLocales`; the message adds script-subtag guidance when one is present. |
-| `InvalidSiteIconsError` | `icons` is declared as an empty array, or any icon fails the [`SiteIcon`](#siteicon) rules. Carries the offending icons. |
-| `InvalidMediaPurposesError` | Any declared purpose fails a policy rule. Carries one issue per purpose. |
-
-`InvalidMediaPurposesError` reports exactly one reason per purpose, checked in this order and stopping at the first hit:
-
-| Reason | Meaning |
-|---|---|
-| `invalid-slug` | `name` does not match the slug pattern. |
-| `empty-required` | `required` is an empty array. |
-| `empty-required-slot` | A `required` entry parses to zero mimes. |
-| `overlapping-slot-mimes` | Two slots accept the same mime, so a variant cannot be mapped to one slot. |
-| `maxBytes-missing-mime` | `maxBytes` has no entry for a mime that some slot accepts. |
-| `maxBytes-non-positive` | A `maxBytes` entry is not a positive number. |
-
-Locale canonicalization accepts a 2- or 3-letter ISO 639 language plus an optional 2-letter ISO 3166 region, separated by `-` or `_`, or run together in the 2+2 form. Case is irrelevant: `zh-tw`, `ZH_TW` and `zhTW` all canonicalize to `zh-TW`. The canonicalized list is deduplicated, so `["zh-tw", "zh-TW"]` collapses to one entry. Script subtags are valid BCP 47 but deliberately unsupported in v0.1 — `zh-Hant`, `zh-Hans`, `sr-Latn` and `sr-Cyrl` are all rejected; use region tags such as `zh-TW` and `zh-CN`. Variants such as `de-1996` are likewise rejected. The `locales` row stores the declared list verbatim once it validates.
-
-Deployment readiness runs alongside the seed and collects boot-phase diagnostics, throwing `BootValidationError` when any is an error.
-
-| Check | Diagnostic |
-|---|---|
-| `checkSiteLocales`: the site locale list canonicalizes. | `INVALID_LOCALE` at `site_config/locales`, listing the invalid entries |
-| `checkSiteLocales`: no Schema declares `localized: true` while the site has zero valid locales. | `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES` |
-| `translates` references resolve: the parent exists, is not itself localized, and declares the join field. | `TRANSLATES_PARENT_UNKNOWN`, `TRANSLATES_PARENT_IS_LOCALIZED`, `TRANSLATES_FIELD_NOT_IN_PARENT` |
-| Every `handler.kind: ref` key is registered in the `handlers` map. The registered keys are attached as `candidates`. | `HANDLER_NOT_REGISTERED` |
-| No HTTP Trigger path falls under an adapter-reserved prefix. | `TRIGGER_PATH_INVALID` |
-| Every `sql` View's dialect is supported by the bound storage adapter. | `VIEW_DIALECT_UNSUPPORTED` |
-
-## Checked per request
-
-| Read | When |
-|---|---|
-| `siteConfig.load()` | Every public render, every `/llms.txt`, `.md` mirror and sitemap response, every MCP catalog build, the Admin site payload. Reads all rows and applies the fallbacks above. |
-| `siteConfig.readLocales()` | Locale resolution on public routes and the write-time locale gate. Reads only the `locales` row; the value is memoized per repository instance once a prepared revision proves the code-owned locale policy is current. |
-| `siteConfig.readMediaPurposes()` | Upload authorization. Always reads the canonical row, never a cached catalog snapshot. |
-
-The `data.locale` write gate runs on every authoring path — Admin, Staff MCP and builtin Procedures — after stamping, against the locales read for that request. Its Schema-side rules are in [Schema](./schema.md#write-time-locale-gate).
-
-| Condition | Result |
-|---|---|
-| Non-localized Schema and `data.locale` is present. | `INPUT_VALIDATION_FAILED` |
-| Localized Schema and `data.locale` is missing or empty. | `INPUT_VALIDATION_FAILED`, skipped for partial draft saves; publish re-checks. |
-| Localized Schema and `data.locale` is not in the site locales. | `INPUT_VALIDATION_FAILED` with the enabled locales as `candidates` |
-| The site locale list is empty. | Membership is not checked. |
-
-Media checks run per upload. `create_media_upload` and `commit_media_upload` are registered only when the runtime has a `mediaStorage` port bound **and** at least one purpose is declared; without both, the tools do not appear in `tools/list` at all.
-
-| Condition | Diagnostic |
-|---|---|
-| `purpose` is not one of the declared slugs. The declared set is returned in `expected`. | `MEDIA_PURPOSE_REJECTED` |
-| The variants manifest does not cover every required mime for the purpose. | `MEDIA_VARIANTS_INCOMPLETE` |
-| A variant's declared `byteSize` exceeds its mime's `maxBytes`. | `MEDIA_VARIANT_SIZE_EXCEEDED` |
-| A single upload exceeds its cap. | `MEDIA_SIZE_EXCEEDED` |
-| A modern format is larger than its fallback, which means the uploader skipped optimization. | `MEDIA_VARIANTS_SUSPICIOUS_SIZE` |
-
-The Cloudflare recipe for binding R2 is in [Media on R2](../cloudflare/media-r2.md).
-
-## Example
+Site settings and the media library are one optional capability. A service
+turns it on by passing `SiteDefaults` to its storage adapter:
 
 ```ts
-import { createMantleWorker } from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-import { handlers } from "./handlers.js";
-
-export default createMantleWorker({
-  plan,
-  handlers,
-  siteDefaults: {
+storage: (env) => d1Storage(env.DB, {
+  site: {
+    title: "Notes",
+    brand: "Notes",
+    description: "A small notebook.",
+    origin: "https://notes.example.com",
     locales: ["en", "zh-TW"],
-    brand: "Northwind",
-    title: "Northwind Supply",
-    description: "Industrial parts, shipped the same day.",
-    origin: "https://northwind.example.com",
-    icons: [
-      { src: "/site-icon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
-      { src: "/site-icon.png", mimeType: "image/png", sizes: ["64x64"] },
-    ],
-    media: {
-      purposes: [
-        {
-          name: "product-cover",
-          required: ["image/jpg,image/png", "webp", "avif"],
-          maxBytes: {
-            "image/jpeg": 5_000_000,
-            "image/png": 5_000_000,
-            "image/webp": 3_000_000,
-            "image/avif": 2_000_000,
-          },
-        },
-      ],
-    },
+    icons: [{ src: "/favicon.svg", mimeType: "image/svg+xml", sizes: ["any"] }],
+    media: { purposes: [{ name: "cover", required: ["image/webp", "image/jpeg,image/png"], maxBytes: { "image/webp": 2_000_000, "image/jpeg": 2_000_000, "image/png": 2_000_000 } }] },
   },
-});
+}),
 ```
 
-`en` is canonical, so `/` redirects to `/en` and `zh-TW` is served at `/zh-tw`. Both icon files live in the project's `public/` directory. The one purpose declares three slots: the first accepts a JPEG or a PNG primary, the other two carry the modern alternates. See [Conventional Worker](../cloudflare/conventional-worker.md) for the surrounding bindings and [Public web](../cloudflare/public-web.md) for what the locale list turns on.
+With `site`, boot creates Mantle's product tables (`site_config`,
+`media_assets`, `pending_media_uploads`), writes the defaults, and the runtime
+carries `runtime.site`. Without it those tables are not created,
+`runtime.site` is absent, Admin's `/site-settings` answers 501
+`SITE_NOT_CONFIGURED` and its media routes 501 `MEDIA_NOT_CONFIGURED`, and the
+console leaves Settings and Media out of its navigation. The generated preset
+does not pass `site`; add it in `src/service.ts`. In 0.2.0 only the `sqlite`
+dialect's storage takes `site` (`d1Storage`, `sqliteStorage`,
+`bunSqliteStorage`); PostgreSQL storage has no site settings or media.
 
-## Source
+## `SiteDefaults`
 
-- [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
-- [`packages/mantle-spec/src/domain/model/MediaMimeAccept.ts`](../../../packages/mantle-spec/src/domain/model/MediaMimeAccept.ts)
-- [`packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts`](../../../packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts)
-- [`packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts`](../../../packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts)
-- [`packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts`](../../../packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts)
-- [`packages/mantle-runtime/src/infrastructure/persistence/DatabaseSiteConfigRepository.ts`](../../../packages/mantle-runtime/src/infrastructure/persistence/DatabaseSiteConfigRepository.ts)
-- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
-- [`packages/mantle-runtime/src/usecase/media/diagnostics.ts`](../../../packages/mantle-runtime/src/usecase/media/diagnostics.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)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`docs/media-uploads.md`](../../../docs/media-uploads.md)
+| Field | Kind | At boot |
+|---|---|---|
+| `title`, `brand`, `description` | operator | written once if the row is missing; after that the database wins, so an owner's edit in Admin is never overwritten by code |
+| `origin` | deployment | synced every boot: the canonical absolute origin, no trailing slash |
+| `locales` | deployment | synced every boot; the first is the canonical locale |
+| `icons` | deployment | synced every boot: `[{ src, mimeType?, sizes?, theme? }]`, root-relative or absolute HTTPS. Without it the defaults are `/admin/favicon.png` and `/admin/favicon.svg`, served with the Admin console |
+| `media.purposes` | deployment | synced every boot: `[{ name, required: [mime slots], maxBytes: { mime: bytes } }]`; `name` is a lowercase slug |
+
+A blank value is skipped, so it never clears a stored one. Boot validates the
+defaults and refuses a malformed purpose or locale.
+
+## Reading and editing
+
+- `runtime.site.read()` returns `{ title, description, origin, locales,
+  canonicalLocale, brand, icons, media: { purposes } }`.
+- `runtime.site.updateSettings({ brand?, title?, description? })` edits the
+  operator fields; an empty string clears one.
+- Admin: `GET /admin/api/site` (any staff role) answers the site for the
+  console, with `mcpEndpoints` from `createAdminSurface`'s
+  `site: { mcpEndpoints }` (with feature `mcp` the preset passes
+  `{ public: "/mcp", staff: "/mcp/staff" }`; default `null`). `GET` and `PATCH /admin/api/site-settings` (owner) read and
+  edit the operator fields.
+
+## Media purposes
+
+A purpose names a kind of upload and the variants it needs. Each `required`
+entry is one MIME slot in `<input accept>` grammar (`"image/webp"`,
+`"image/jpeg,image/png"` for either, `"webp"` for short), and an upload supplies
+one variant per slot; slots must not overlap. `maxBytes` caps each full MIME
+type and must cover every type a slot accepts. Separately, exactly one variant
+of an upload says `role: "primary"` (what `<img>` falls back to); the others are
+`alternate` or `fallback`. The accepted types are PNG, JPEG, WebP, AVIF and GIF
+(SVG is refused). An upload request names its purpose; a missing slot or a
+byte size over the cap is refused before any upload URL is issued. See
+[Media uploads with R2](../cloudflare/media-r2.md).

package/docs/handbook/reference/surface.md

@@ -1,205 +1,93 @@
 ---
-description: Every surface Mantle exposes — Worker HTTP routes and their cache class, the MCP tool catalog, CLI flags, the generated module, packages and versions.
+description: Every HTTP route the generated Mantle 0.2.0 service mounts (REST, auth, MCP, Admin), the package subpaths and their exports, and the CLI.
 ---
-# HTTP, MCP, CLI and package surface
+# HTTP, MCP, CLI and packages
 
-What a Mantle deployment exposes, in one place: the routes the conventional Cloudflare Worker owns, the MCP tools it advertises, the commands the package installs, the module `mantle generate` writes, and which package holds what. Route behaviour follows [Conventional Worker](../cloudflare/conventional-worker.md); this page is the index.
+## Routes of the generated service
 
-## HTTP routes
+`src/service.ts` mounts, in this order. Each surface runs behind
+`withCaller(resolver, …)`; with identity `none`, every caller is anonymous.
 
-Every table below describes the conventional Cloudflare Worker assembled by `createMantleWorker`. The **cache** column is the class the final `applyCachePolicy` boundary assigns. Only an anonymous `200` `GET`/`HEAD` response that explicitly declares `public` plus a shared freshness lifetime stays cacheable, and it then varies on `Cookie` and `Authorization`; the request must carry neither header and the response must set no cookie. Everything else becomes `private, no-store` with any CDN cache override stripped.
-
-### Manifest routes
-
-| Route | Response | Cache |
+| Path | Surface | Mounted when |
 |---|---|---|
-| `GET /api/views` | `{ ok: true, data: [ { name, title?, description, inputSchema } ] }` — one descriptor per public View. | `private, no-store` |
-| `GET /api/views/<name>?page=&show=` | `{ ok: true, data: { rows, page, show, hasMore } }`. One route per View declaring `surface: public`. Query values are coerced against `params`; a bad value is `400`. | `private, no-store`, or the View's `cache.sharedMaxAge` for an anonymous eligible response |
-| `<METHOD> <path>` | Every manifest HTTP Trigger, at its declared `POST`, `PUT`, `PATCH` or `DELETE` and path under `/api/`. The JSON body must be an object. Success is `{ ok: true, data: … }`. | `private, no-store` |
-
-Staff Views are not mounted here; they live under `/admin/api/views/<name>`.
+| `/api/auth/*`, `/.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource[/*]`, `/oauth/consent[/data]`, `/oauth/consents[/data\|/revoke]` | `createAuthRoutes` | identity `mantle` |
+| `/admin/*` | `createAdminSurface`: the console (from `ASSETS`) and `/admin/api/*` | feature `admin` |
+| `/mcp/staff` | `createMcpSurface`, `surface: staff`, with `planApp`'s MCP App | feature `mcp` and an identity |
+| `/mcp` | `createMcpSurface`, `surface: public` | feature `mcp` |
+| everything else | `createRestSurface` at `/api` | always |
 
-### Admin
+### REST
 
-All `/admin/api/*` routes require a staff session, carry a 1 MiB JSON body limit, and are `private, no-store`.
-
-| Route | Response |
+| Route | |
 |---|---|
-| `GET /admin`, `/admin/`, `/admin/sign-in`, `/admin/c/:collection`, `/admin/c/:collection/:id`, `/admin/media`, `/admin/preferences`, `/admin/connected-apps`, `/admin/settings`, `/admin/staff`, `/admin/members`, `/admin/ops`, `/admin/dev`, `/admin/dev/model`, `/admin/dev/logic`, `/admin/dev/docs`, `/admin/views/:name` | The Admin SPA shell, read from `/_mantle/admin/index.html` through the assets binding. `503` with an explanatory body when the bundle is missing. |
-| `GET /admin/api/views/<name>` | Staff execution of any declared View, public or staff, with Admin search and filtering applied before pagination. |
-| `GET /admin/api/views/<name>/export` | The same query as CSV, covering every matching row rather than one page. |
-| `GET /admin/api/views-manifest` | `{ views: … }` — the View manifest projection the SPA renders from. |
-| `GET /admin/api/operations` | `{ operations: [ { name, title, description, input, uiSchema, triggers, rowBindings } ] }`, filtered per caller by re-evaluating each Procedure's `requires.auth.all`. |
-| `POST /admin/api/operations/:name` | Invokes a staff-operable Procedure through the same use case the staff MCP surface uses. `404` when the name is not staff-operable or when the caller's `requires.auth.all` predicates exclude it — the same filter the listing applies, so names cannot be probed. |
-| `GET /admin/api/me`, `/collections`, `/collections/:name/statistics`, `/entries`, `/entries/export`, `/entries/:id`, `/site` | Session, catalog and entry reads. Entry detail requires `?collection=<schema>`. |
-| `POST /admin/api/entries`, `PATCH /admin/api/entries/:id` | Create and edit. Entry mutation routes require `?collection=<schema>`; contributors are limited to drafts on publishing Schemas. |
-| `POST /admin/api/entries/:id/publish`, `/unpublish`, `DELETE /admin/api/entries/:id` | Lifecycle. Requires `?collection=<schema>` and editor or above. |
-| `POST /admin/api/media/uploads`, `POST /admin/api/media/uploads/:uploadGroupId/commit`, `GET /admin/api/media`, `GET`, `PATCH` and `DELETE /admin/api/media/:id` | Media lifecycle. Editor or above. |
-| `GET /admin/api/staff`, `PATCH /admin/api/staff/:id/role`, `POST /admin/api/staff/invitations`, `DELETE /admin/api/staff/invitations/:id`, `GET /admin/api/developer-console`, `GET` and `PATCH /admin/api/site-settings` | Owner only. |
-| `GET /admin/api/members` | Editor or above. |
-
-`/_mantle/*` holds the static Admin bundle. It is served by the Worker's static-assets layer from `public/_mantle/admin/`, which `mantle generate` syncs when `@aotter/mantle-admin-ui` is installed. The Worker registers no route there; the prefix is reserved so extensions cannot claim it.
-
-### Auth, OAuth and MCP
-
-| Route | Response | Cache |
-|---|---|---|
-| `GET /api/auth/methods` | `{ methods }` — the registered sign-in method kinds, no secrets. Explicitly `no-store` so a method change cannot be served stale. | `private, no-store` |
-| `ALL /api/auth/*` | Better Auth: sign-in, callback, session, magic link, OTP. `/api/auth` is the default base path. | `private, no-store` |
-| `ALL /api/auth/oauth2/*` | The site's OAuth provider endpoints, including consent. | `private, no-store` |
-| `ALL /.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource`, `/.well-known/oauth-protected-resource/*` | RFC 8414 and RFC 9728 discovery metadata, registered explicitly so no catch-all can swallow them. `/.well-known/oauth-protected-resource/mcp` is the resource metadata the MCP `WWW-Authenticate` challenge points at. | `private, no-store` |
-| `ALL /oauth/*` | Consent and connected-apps pages: `/oauth/consent`, `/oauth/consent/data`, `/oauth/consents`, `/oauth/consents/data`, `/oauth/consents/revoke`. | `private, no-store` |
-| `ALL /mcp` | Public MCP surface. JSON-RPC. | `private, no-store` |
-| `ALL /mcp/staff` | Staff MCP surface. Rejects a verified caller with no staff row using `403` and `insufficient_scope`. | `private, no-store` |
-
-Both MCP surfaces resolve the caller exactly as the HTTP routes do — consumer credential, then an OAuth access token against one canonical resource, `${PUBLIC_ORIGIN}/mcp`, and one scope, `mcp`, then a same-origin cookie session, then anonymous. The surface adds one rule: `/mcp/staff` requires a staff caller. An invalid token, or an anonymous caller on the staff surface, is `401` with a `Bearer` challenge naming the resource metadata URL; DPoP failures answer with a `DPoP` challenge; on `/mcp` an anonymous `tools/call` whose target requires identity answers the same `401` challenge. Misconfigured or partial auth environment variables keep public routes serving and return `503 setup_incomplete` from every Auth-owned route above — see [Authentication](../cloudflare/authentication.md).
-
-### Public pages
-
-These are opt-in and application-declared. Public rendering needs three matching inputs: a `mountPublicRoutes(...)` call declaring the collection routes, a `TemplateRegistry` passed as `templates`, and a `publicPathResolver`. A headless deployment declares none of them and serves none of these routes; mounting every Schema automatically is deliberately not offered, because a collection can hold a slug and still be private. Bodies render from canonical database state.
-
-| Route | Response | Cache |
-|---|---|---|
-| `GET /` | `302` to `/{canonical locale}`. | `private, no-store` |
-| `GET /:locale` | Composed home page. | `public, max-age=0, s-maxage=300` + a deployment-scoped cache tag |
-| `GET /:locale.md` | Markdown mirror of the home page. | public |
-| `GET /:locale/:segment` | Collection list page. Opt-in per collection route. Paginates by `?cursor=` and adds `Link: <…>; rel="next"` plus an in-page next link. | public |
-| `GET /:locale/:segment.md` | Markdown mirror of the list. | public |
-| `GET /:locale/:segment/:slug` | Entry page. | public |
-| `GET /:locale/:segment/:slug.md` | Markdown mirror of one entry. Registered before the bare slug route, and the slug group stays single-segment. | public |
-| `GET /:locale/:segment/:slug?preview=1` | Live render of unpublished content. Gated on a staff session: `401` with no session, `403` for a non-staff user. | `private, no-store` |
-| `GET /llms.txt` | Composed agent index across every locale, with `?cursor=` continuation and `Link: rel="next"`. | public |
-| `GET /:locale/llms.txt` | The same, scoped to one locale. | public |
-| `GET /sitemap.xml` | Sitemap. `?part=1` returns a single part; otherwise a sitemap index is returned whenever a continuation exists, and `?cursor=` fetches the next part. Part size is `min(2000, floor(40000 / locale count))`, at least 1. | public |
-| `GET /robots.txt` | `User-agent: *`, `Allow: /`, and a `Sitemap:` pointer built from `siteDefaults.origin`. | public |
-| `GET /favicon.ico` | A convention, not a reserved path: an existing host route wins. Picks the first themeless PNG icon, else the first themeless icon, else the first icon; serves it from the assets binding when it resolves to `/favicon.ico` on this origin, and otherwise redirects to the icon `src`. | `private, no-store` |
-
-The first three rows register only when a home renderer is supplied; without one, `/` and `/{locale}` are not mounted at all. Unmatched paths fall through to the supplied not-found renderer. Setting `liveDev` switches entry and list HTML to `private, no-store`. `cacheScope` isolates each deployment's tag and optional KV key; without it the facade disables shared caching. Publishing-content and site-setting writes purge that scoped tag. Purge is best effort after the canonical write, and Cloudflare KV remains eventually consistent. Immutable assets and operational records stay outside that boundary. More in [Public web](../cloudflare/public-web.md).
-
-### Reserved paths
-
-Extensions may add routes but may not replace Core surfaces. These are reserved:
-
-- `/admin` and `/admin/*`
-- `/_mantle` and `/_mantle/*`
-- `/api/auth` and `/api/auth/*`
-- `/api/views` and `/api/views/*`
-- `/oauth` and `/oauth/*`
-- `/mcp` and `/mcp/*`
-- `/.well-known/oauth*`
-- the global `*` and `/*` registrations
-
-A custom Auth factory's `basePath` and every manifest-owned `(method, path)` pair are reserved as well. Static literal conflicts fail the consumer's TypeScript build; computed paths cannot be proven statically, so the facade inspects the assembled route table and fails closed before serving. A manifest HTTP Trigger under one of these prefixes is `TRIGGER_PATH_INVALID` at boot.
-
-## MCP tools
-
-Tool names are the mangled `metadata.name`: lower-cased, with `-` replaced by `_`. Discovery is filtered per caller, but discovery is never the enforcement boundary — every `tools/call` re-evaluates the target's `requires.auth.all` and its guard.
-
-| Tool | Surface | Registered when |
-|---|---|---|
-| `query_view_<segment>` | The View's own `surface` | One per public or staff View; internal Views have no tool. `annotations.readOnlyHint` is `true`; the input schema is the View's `params.properties` plus `page` and `show`. |
-| `<procedure_segment>` | The MCP Trigger's `surface` | One per `mcp` Trigger. `annotations` carry what Core can prove (`readOnlyHint: false` for every builtin handler, `destructiveHint: true` for `op: delete`, `idempotentHint: true` when an input carries `x-mcp-hint: idempotency-key`) plus whatever the Procedure declares under `spec.mcp`; `ref` handlers get nothing inferred beyond the idempotency key. Generic authoring, lifecycle and media tools are `readOnlyHint: false`; `delete_entry` is also `destructiveHint: true`. |
-| `<procedure segment>` | The Trigger's `surface` | One per `Trigger.source.kind: mcp`. A Procedure with no MCP Trigger is not exposed. |
-| `request_publish` | staff | Always. Rejected at call time for an operational Schema. |
-| `unpublish_entry` | staff | Always. Same restriction. |
-| `archive_entry` | staff | Always. Same restriction. |
-| `delete_entry` | staff | Always. |
-| `create_draft_<segment>`, `update_draft_<segment>` | staff | Per publishing Schema whose `schema.readOnly` is not `true`. |
-| `create_record_<segment>`, `update_record_<segment>` | staff | Per operational Schema whose `schema.readOnly` is not `true`. |
-| `create_media_upload`, `commit_media_upload` | staff | Only when a `mediaStorage` port is bound **and** at least one `media.purposes` entry is declared. |
-
-The public surface carries callable capabilities only — public Views and Procedures with a public MCP Trigger. No generic entry tool and no authoring tool is ever advertised there. Update tools add `id` and `expected_version` as required fields, and `x-mantle-bind` properties are stripped from authoring tool schemas because the server stamps them. Localized `title` and `description` collapse to their `en` value in tool schemas. Concepts are in [MCP and agents](../concepts/mcp-and-agents.md).
+| `GET /api/views/<name>` | a `public` View; query parameters are its `input` plus `limit` and `cursor`. Answers `{ rows, nextCursor? }` |
+| `<METHOD> <path>` | each `http` Trigger; the JSON body and path parameters are the input. Answers the Procedure's output |
 
-## CLI
+A failure is `{ "error": <diagnostic> }` with the code's status
+([Diagnostics](./diagnostics.md)). A cookie session cannot mutate across
+origins.
 
-The `@aotter/mantle` package installs two binaries, `mantle` and `mantle-harness`. Exit codes are `0` for success, `1` for a diagnostic failure and `2` for an invocation problem.
+### Auth (identity `mantle`)
 
-| Command | Flags |
+| Route | |
 |---|---|
-| `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` 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.
+| `GET /api/auth/methods` | the sign-in methods this service offers |
+| `/api/auth/*` | Better Auth: email OTP (`/email-otp/send-verification-otp`, `/sign-in/email-otp`), magic link, social and generic OAuth sign-in, sessions, sign-out, the OAuth provider |
+| `/.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource[/mcp]` | OAuth metadata, served by Better Auth |
+| `/oauth/consent`, `/oauth/consents` | consent and connected apps, session only |
 
-## The generated module
+### MCP
 
-`mantle generate` writes one file, `.mantle/generated/mantle.ts`. It is generated code: do not edit it, and regenerate after any manifest change.
-
-| Export | Shape |
+| Route | |
 |---|---|
-| `plan` | The sealed `RuntimePlan`, carrying a semantic fingerprint. |
-| `Mantle` (or `--namespace`) | Type namespace holding `Entry_*`, `ViewRow_*`, `ViewParams_*`, `ProcInput_*` and `ProcOutput_*` for every atom. |
-| `MantleViewOptions` | `{ page?, show?, ctx? }`. |
-| `MantleHandlers<Env>` | Typed map of every `handler.kind: ref` key the manifests declare. |
-| `CreateMantleOptions<Env>` | `BootMantleRuntimeArgs` without `plan` and `handlers`, plus the typed `handlers` map. |
-| `createMantle(options)` | Boots the runtime and returns the bound facade. Eager: it prepares once and neither caches nor retries. |
-| `bindMantle(runtime)` | Binds an already-booted runtime. Throws when `runtime.revision` does not equal the generated plan's fingerprint. |
+| `POST /mcp` | the public surface (Streamable HTTP, JSON-RPC) |
+| `POST /mcp/staff` | the staff surface: staff only, the same token as `/mcp`; see [MCP and agents](../concepts/mcp-and-agents.md) |
 
-The bound object is deterministic lower-camel property names over the authored wire names:
+### Admin API
 
-```ts
-import { createMantle } from "../.mantle/generated/mantle.js";
+Every route needs a staff caller; the column names the least role.
 
-const mantle = await createMantle({ storage, handlers });
+| Route | Role | |
+|---|---|---|
+| `GET /admin/api/me`, `GET /admin/api/bootstrap` | contributor | the caller; the console's first load |
+| `GET /admin/api/collections`, `GET …/collections/{name}/statistics` | contributor | Schemas; statistics answer 501 in 0.2.0 |
+| `GET /admin/api/entries?collection=`, `GET …/entries/export`, `GET …/entries/{id}` | contributor | list (with `search`, `limit`, `cursor`), CSV, one row |
+| `POST /admin/api/entries`, `PATCH …/entries/{id}` (with `expectedVersion`) | contributor | create, edit (contributors: drafts only) |
+| `POST …/entries/{id}/publish`, `…/unpublish`, `DELETE …/entries/{id}` | editor | |
+| `GET /admin/api/views-manifest`, `GET …/views/{name}`, `GET …/views/{name}/export` | contributor | staff Views (`{ name, title, description, input, list: { columns, searchFields, filterFields }, columns }`); rows by `limit`/`cursor` with `search` and `filter.<output>`; CSV |
+| `GET /admin/api/operations`, `POST …/operations/{name}` | contributor | Procedures bound to the staff MCP surface |
+| `GET /admin/api/site` | contributor | site metadata, `mcpEndpoints`, and `capabilities: { siteSettings, media, invitationEmail, statistics }` (what this deployment turned on; the console hides what is off) |
+| `GET`, `PATCH /admin/api/site-settings` | owner | 501 `SITE_NOT_CONFIGURED` without `runtime.site` |
+| `POST /admin/api/media/uploads`, `POST …/media/uploads/{groupId}/commit`, `GET …/media`, `GET`, `PATCH`, `DELETE …/media/{id}` | editor | with `media` and `runtime.site` |
+| `GET /admin/api/webmcp`, `POST …/webmcp/{tool}` | contributor | the staff tools for a browser agent (`{ tools, routes }`); a call runs one as `/mcp/staff` does and answers `{ output }` |
+| `GET /admin/api/staff`, `PATCH …/staff/{id}/role`, `POST …/staff/invitations`, `DELETE …/staff/invitations/{id}` | owner | with an `AdminIdentity` that has `directory` / `roles` |
+| `GET /admin/api/members` | editor | with `directory` |
+| `GET /admin/api/developer-console` | owner | the plan's data model, logic and schedules |
 
-await mantle.views.publishedNotes({ page: 1, show: 20 });
-await mantle.procedures.expireOrder({ orderId }, { user: null, staff: null, env });
-await mantle.entries.orders.createDraft({ data, authorId: user.id });
-mantle.triggers.expireOrderHttp;   // { name, source, target }
-await mantle.runtime.archive.execute({ id, ctx });
-```
+## Packages
 
-`entries.<collection>` exposes `createDraft`, `get`, `list`, `delete`, and the indexed field reads `readBySlug`, `readByDataField`, `readByDataFieldIn` and `findManyByDataField`, supplying the required collection identity to Core. The field reads accept only declared Schema fields and their scalar types, and return entries whose `data` is the generated Schema shape, so an author never has to drop to an untyped `runtime.entries` call or scan `list` to find rows by an indexed field. Generic MCP entry tools require a `collection` argument. `runtime` is the underlying Core runtime, so the typed projection never hides it. A host that owns its own lifecycle can skip generation entirely and call `runtime.executeView({ view: "published-notes" })` directly.
+Two npm packages, always published together at one version.
 
-## Packages
+| Import | Exports |
+|---|---|
+| `@aotter/mantle` | `createMantle`, `createMantleRuntime`, `verifyPlan` and its `PLAN_LIMITS`, `withCaller`, `systemCaller`, the `Caller`, `CallerResolver`, `MantleService`, `HandlerContext`, `Invocation` and Store types, `EmailSender`, `DiagnosticError`, `makeDiagnostic`, `runtimeDiagnostic`, `STAFF_ROLES`, `isStaffRole` |
+| `@aotter/mantle/spec` | the grammar types, `compilePlan`, `mcpTools` (the CLI side; it bundles the SQL parser, so a Worker or handler imports `DiagnosticError` from the root) |
+| `@aotter/mantle/d1`, `/d1/compile` | the `sqlite` dialect: `sqliteStorage` over any `DatabaseDriver`; its compile side |
+| `@aotter/mantle/postgres`, `/postgres/compile` | the `postgres` dialect: `postgresStorage`, `postgresDialect`, `pgDatabaseDriver`, `pgPool`, the `PgClient` and `PgConnect` types; its compile side |
+| `@aotter/mantle/cloudflare` | `d1Storage`, `d1Driver`, `r2MediaStorage`, `toCloudflareCron` |
+| `@aotter/mantle/auth` | `createMantleAuth`, `createSetupIncompleteAuth`, `createCallerResolver`, `createAuthRoutes`, `ConsoleEmailSender`, `appleClientSecret` |
+| `@aotter/mantle/admin` | `createAdminSurface`, `AdminIdentity` |
+| `@aotter/mantle/mcp` | `createMcpSurface`, `planApp` and `appCatalog` (the MCP App's catalog) |
+| `@aotter/mantle/web` | `createRestSurface` |
+| `@aotter/mantle/bun` | `bunPostgresStorage`, `bunSqliteStorage`, `bunPgConnect`, `bunDatabaseDriver`, `bunSqliteDriver`, `bunAuthDatabase`, `bunAdminAssets` |
+| `@aotter/mantle/testing` | `runStorageConformance`, the dialect compliance suite |
+| `@aotter/mantle-ui` | the root (React operation components and the controller), `/controller`, `/kit`, `/kit.css`, `/tokens.css`, `/mcp-app` (`mantleAppHtml`, the App `planApp` serves), and the prebuilt Admin console in `dist/admin` (exported as `./admin/index.html`), which the preset serves at `/admin` |
+
+A subpath that is not imported is never loaded: a service with identity
+`none` bundles no Better Auth, and no Worker bundles the SQL parser.
 
-The umbrella installs Spec and Runtime only. Web, Admin, Auth, Admin UI, Bun, Vercel and Cloudflare are optional peers; install one before importing its subpath. Every sub-package is also directly installable.
+## CLI
 
-| Package | Umbrella subpath | Holds |
-|---|---|---|
-| `@aotter/mantle` | root | Umbrella plus the `mantle` and `mantle-harness` binaries. |
-| `@aotter/mantle-spec` | `/spec` | Manifest grammar, parser, validators, JSON Schema to zod, site-config contract, diagnostic catalog. No environment, no IO. |
-| `@aotter/mantle-runtime` | `/runtime` | Hexagonal runtime: domain ports, use cases, MCP catalog, storage helpers. No adapter dependencies. |
-| — | `/runtime/testing` | Node-only crowded-SQLite planner and HTTP sampling helpers used by `mantle-harness`. |
-| — | `/codegen` | The pure linked-manifests or compiled-plan to typed-module emitter, with no IO. |
-| `@aotter/mantle-web` | `/web` | HTML, Markdown, `llms.txt`, sitemap, SEO and preview composition. No routes, no platform dependencies. |
-| `@aotter/mantle-admin` | `/admin` | Admin API, auth route mounting, OAuth pages, static-asset composition. |
-| `@aotter/mantle-auth` | `/auth` | Host-neutral Better Auth identity, staff roles, and OAuth 2.1 / MCP authorization. Adapters own IP headers and storage bindings. |
-| `@aotter/mantle-admin-ui` | `/admin-ui` | Pre-built React 19 Admin SPA bundle. |
-| `@aotter/mantle-bun` | `/bun` | Bun adapter over a caller-owned `bun:sqlite` database. |
-| `@aotter/mantle-vercel` | `/vercel` | Vercel Functions adapter with injected durable storage and platform `waitUntil`. |
-| — | `/vercel/libsql` | Optional application-owned Turso/libSQL driver. |
-| `@aotter/mantle-cloudflare` | `/cloudflare` | Cloudflare Workers adapter: D1, Workers Cache, R2, Queues, Better Auth 1.7 MCP and CIMD. |
-| `@aotter/mantle-indexeddb` | — | Browser IndexedDB adapter. Directly installable; no umbrella subpath. |
-
-## Versions
-
-This handbook describes the snapshot in this source tree. Pin every `@aotter/mantle*` package to one exact version and keep them together. For a registry installation, use the documentation at the matching release tag. For a source-built package, record the source commit as well as the package version.
-
-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.
-
-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
-
-- [`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-runtime/src/infrastructure/mcp/McpToolCatalog.ts`](../../../packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts)
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [`packages/mantle-admin/src/mountMantleOAuth.ts`](../../../packages/mantle-admin/src/mountMantleOAuth.ts)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)
-- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
-- [`packages/adapters/cloudflare/src/mount/mountMcp.ts`](../../../packages/adapters/cloudflare/src/mount/mountMcp.ts)
-- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
+`mantle generate [--manifests <dir>] [--features <list>] [--identity <kind>] [--host <host>] [--dialect <name>]`
+and `mantle generate --check [--database <file>]`. See
+[Project layout and CLI](../start/project-and-cli.md).