@aotter/mantle 0.1.0-alpha.8 → 0.1.2-alpha.1

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

@@ -0,0 +1,216 @@
+---
+description: Enable staff media uploads on R2 — presigned PUT flow through Staff MCP, media purposes, wrangler config, commit cost and cleanup.
+---
+# 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 upload flow, the Cloudflare and Worker configuration it needs, how a Schema references an asset, what a commit costs, and how to clean up.
+
+## When to enable it
+
+Turn this on only after the site already has a working deploy, staff auth configured, and a real need for staff-managed media. R2 setup may require billing, so it is deliberately not part of the first-deploy path. Everything on this page is inert until the bucket, credentials and at least one media purpose all exist.
+
+Media maintenance also needs an agent that can read local files, process images and make outbound `PUT` requests to `*.r2.cloudflarestorage.com`. A sandboxed agent without egress cannot finish the flow.
+
+## The upload flow
+
+```txt
+1. create_media_upload   staff MCP  -> purpose, variants, mime types, byte sizes
+2. Mantle                           -> signed upload URLs + required headers
+3. agent or browser                 -> PUT bytes directly to R2
+4. commit_media_upload   staff MCP  -> validate, stamp, save the asset row
+```
+
+Bytes travel from the agent to R2 over a signed URL; the Worker sees policy, not payload. Never pass image bytes or base64 payloads through MCP tool arguments — the tool dispatchers count streamed JSON bytes and return `413` above the 1 MiB control-plane limit. The Worker validates; the agent runtime does the file work.
+
+## Cloudflare setup
+
+```sh
+wrangler r2 bucket create <project>-media
+wrangler r2 bucket dev-url enable <project>-media
+```
+
+Then create an R2 S3 API token in the dashboard: open **R2**, open **Manage R2 API Tokens**, create an **Object Read & Write** token, and copy the Access Key ID and Secret Access Key.
+
+The R2 binding alone cannot issue presigned `PUT` URLs: presigning is an S3-protocol operation, so Mantle needs these credentials in addition to the binding. A deployment with the bucket bound but no credentials never registers the upload tools.
+
+## Wrangler configuration
+
+```toml
+[vars]
+R2_ACCOUNT_ID = "<account-id>"
+MEDIA_PUBLIC_URL_BASE = "https://pub-<hash>.r2.dev"
+
+[[r2_buckets]]
+binding = "MEDIA_BUCKET"
+bucket_name = "<project>-media"
+```
+
+A `wrangler.jsonc` project writes the same binding as an `"r2_buckets"` array; see [Bindings and primitives](./bindings.md#r2-media-bucket-optional) for the JSON form and the matching `Env` fields.
+
+```sh
+wrangler secret put R2_ACCESS_KEY_ID
+wrangler secret put R2_SECRET_ACCESS_KEY
+```
+
+`MEDIA_PUBLIC_URL_BASE` is the origin public URLs are built from — the `r2.dev` development URL, or a custom domain in production. `R2_ACCOUNT_ID` builds the S3 endpoint, which is a different host from the public one.
+
+## Wiring `R2MediaStorage`
+
+Build the adapter from `env`, returning `undefined` when any part is missing so a half-configured environment degrades to no media rather than failing to boot:
+
+```ts
+import { R2MediaStorage } from "@aotter/mantle/cloudflare";
+import { AwsClient } from "aws4fetch";
+
+function buildMediaStorage(env: Env) {
+  if (
+    !env.MEDIA_BUCKET ||
+    !env.R2_ACCOUNT_ID ||
+    !env.R2_ACCESS_KEY_ID ||
+    !env.R2_SECRET_ACCESS_KEY ||
+    !env.MEDIA_PUBLIC_URL_BASE
+  ) {
+    return undefined;
+  }
+
+  const s3 = new AwsClient({
+    accessKeyId: env.R2_ACCESS_KEY_ID,
+    secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+    region: "auto",
+    service: "s3",
+  });
+
+  return new R2MediaStorage(
+    env.MEDIA_BUCKET,
+    s3,
+    `https://<project>-media.${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+    env.MEDIA_PUBLIC_URL_BASE,
+  );
+}
+```
+
+Pass it through the `bindings` hook, spreading the conventional set:
+
+```ts
+export default createMantleWorker<Env>({
+  plan,
+  bindings: (env, conventional) => ({
+    ...conventional,
+    mediaStorage: buildMediaStorage(env),
+  }),
+});
+```
+
+`aws4fetch` is an application dependency; the adapter takes the signing client rather than embedding one. See [The conventional Worker](./conventional-worker.md#a-bindings-hook).
+
+## Declaring media purposes
+
+A purpose is the upload policy: which variants an asset must have, and how large each may be.
+
+```ts
+siteDefaults: {
+  media: {
+    purposes: [
+      {
+        name: "page-image",
+        required: ["image/jpeg,image/png", "image/webp", "image/avif"],
+        maxBytes: {
+          "image/jpeg": 5_000_000,
+          "image/png": 5_000_000,
+          "image/webp": 3_000_000,
+          "image/avif": 2_000_000,
+        },
+      },
+    ],
+  },
+},
+```
+
+`required` is slot-based, in the grammar of an `<input accept>` list. The example declares three slots: slot 0 takes exactly one fallback mime preserving source semantics (`image/jpeg` for opaque photos, `image/png` when alpha must survive), slot 1 a WebP variant, slot 2 an AVIF variant. That models a multi-variant `<picture>`. A narrower purpose may declare a single slot such as `["image/jpeg,image/png,image/webp,image/gif"]`, in which case the agent picks exactly one mime from that list and must not upload one variant per listed mime.
+
+Purpose names are slugs (`^[a-z0-9]+(-[a-z0-9]+)*$`), every slot must be non-empty, slots may not overlap on a mime, and every `maxBytes` key must be a mime some slot accepts with a positive value. Violations fail at boot. SVG uploads are rejected unless the Worker sets `mediaAllowSvg`. See [Site defaults and site_config](../reference/site-config.md).
+
+The runtime emits the policy summary into the `create_media_upload` tool description, so an agent reads the contract straight from `tools/list` without an extra round trip.
+
+## Tool visibility
+
+`create_media_upload` and `commit_media_upload` are registered only when **both** hold:
+
+- `bindings.mediaStorage` is set;
+- `siteDefaults.media.purposes` contains at least one purpose.
+
+If either is missing the tools never appear in `tools/list`. That is the intended diagnostic: an agent that cannot see the tools is looking at a deployment where media is not configured, not at a permissions problem. A call that reaches a runtime without media storage answers `MEDIA_NOT_CONFIGURED`.
+
+## Referencing an asset from a Schema
+
+Entries store asset ids, not URLs. Mark the field with both existing v0.1 grammar extensions:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: pages
+spec:
+  title: Pages
+  schema:
+    type: object
+    additionalProperties: false
+    required: [slug, title]
+    properties:
+      slug: { type: string, pattern: "^[a-z0-9-]+$" }
+      title: { type: string, minLength: 1 }
+      coverAssetId:
+        type: string
+        x-mantle-ref: media_assets
+        x-mcp-hint: media-image
+```
+
+`x-mantle-ref: media_assets` marks the string as an id in the media asset collection, which is what makes Admin show a media picker instead of a text box. `x-mcp-hint: media-image` tells an MCP client the field expects an image asset. Neither key is validated as a foreign key; they are informational. At render time, resolve ids to their variants with `runtime.media.resolve(id)` or `resolveMany(ids)`, which batches a render pass into one database round trip. No new manifest keys are involved; see [Schema](../reference/schema.md).
+
+## What a commit costs
+
+R2 has no metadata-only patch. To stamp `committedAt`, `role`, `uploadGroupId` and the filename markers, Mantle streams each uploaded object through a `GET` and a `PUT`. So a successful N-variant commit performs N `GET`s and N `PUT`s and rewrites the sum of the variant sizes.
+
+- Commits validate the bundle shape before any I/O.
+- Variants are processed in batches of at most three; a batch settles before the next starts or an error returns.
+- A mime or size failure cancels the unused `GET` stream; a failed `PUT` also attempts cancellation while preserving the original error.
+- The asset row is saved only after every variant succeeds. All-or-nothing.
+
+Parallelism reduces waiting, not operation count or bytes. Keep variant counts and byte caps deliberate. A partial R2 failure leaves the pending D1 record in place so the commit can be retried before it expires; already stamped objects stay stamped.
+
+## Cleanup
+
+An upload can reach R2 and never be committed — an interrupted agent, a rejected commit. Remove those objects with the version-matched `media-gc` skill. It is opt-in and deliberately not projected into a repository by `mantle skills`, because it deletes remote objects.
+
+Its posture is audit first, delete only what an operator confirmed. It treats an object as a candidate only when it is over 24 hours old, has no `committedAt` custom metadata, and matches the exact key layout `<purpose>/<group>/(primary|alternate|fallback).<ext>` for a purpose this project declares. It reports account, bucket, prefixes, cutoff, counts, bytes and a digest of the candidate set without printing keys or URLs; on confirmation it re-runs the same audit and stops if anything changed.
+
+> **Do not use an R2 lifecycle rule**
+> Committed and uncommitted media share the same purpose prefix, so an age-based rule deletes live assets. After a pending record expires, partially stamped orphans require an operator audit against D1 references: a missing pending record does not mean an object is unused.
+
+## Diagnostics
+
+| Code | HTTP | Raised when |
+|---|---|---|
+| `MEDIA_NOT_CONFIGURED` | 501 | No `mediaStorage` port is bound on this deployment |
+| `MEDIA_PURPOSE_REJECTED` | 400 | The requested purpose is not declared; the declared set is returned so an agent can self-correct |
+| `MEDIA_MIME_REJECTED` | 400 | A mime outside `image/png`, `image/jpeg`, `image/webp`, `image/avif`, `image/gif` |
+| `MEDIA_SIZE_EXCEEDED` | 400 | A declared byte size exceeds its cap |
+| `MEDIA_SVG_REJECTED` | 400 | An SVG was offered while SVG is not allowed; object storage does not sanitize SVG payloads |
+| `MEDIA_VARIANTS_INCOMPLETE` | 400 | The bundle misses a mime the purpose requires; the missing set is returned |
+| `MEDIA_VARIANT_SIZE_EXCEEDED` | 400 | One variant exceeds the cap declared for its mime |
+| `MEDIA_VARIANTS_SUSPICIOUS_SIZE` | 400 | A modern variant is larger than its fallback (AVIF above JPEG), so it looks unoptimized |
+| `MEDIA_ASSET_NOT_FOUND` | 404 | No `media_assets` row matches the id |
+| `MEDIA_UPLOAD_EXPIRED` | 410 | The upload capability's TTL elapsed, or it was never created |
+| `MEDIA_OBJECT_NOT_FOUND` | 409 | A variant's bytes were never PUT before commit |
+
+The full catalog is in [Diagnostic codes](../reference/diagnostics.md).
+
+## Source
+- [`docs/media-uploads.md`](../../../docs/media-uploads.md)
+- [`docs/adr/0017-media-multi-variant-agent-side-optimization.md`](../../../docs/adr/0017-media-multi-variant-agent-side-optimization.md)
+- [`packages/mantle-runtime/src/domain/port/MediaStorage.ts`](../../../packages/mantle-runtime/src/domain/port/MediaStorage.ts)
+- [`packages/mantle-runtime/src/domain/port/MediaAssetRepository.ts`](../../../packages/mantle-runtime/src/domain/port/MediaAssetRepository.ts)
+- [`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)

package/docs/handbook/cloudflare/public-web.md

@@ -0,0 +1,144 @@
+---
+description: Opt a Worker into public HTML, Markdown mirrors, llms.txt and sitemap with mountPublicRoutes, templates and a path resolver.
+---
+# Public web, SEO and cache
+
+Public rendering is opt-in. A headless Worker serves Views and Triggers only; this page shows how to add server-rendered pages, their agent-readable mirrors and discovery files, and what the cache contract guarantees.
+
+## Three inputs that must agree
+
+1. `mountPublicRoutes(app, ref, { collectionRoutes, ... })` inside `extend.mount` declares which collections have URLs.
+2. A `TemplateRegistry` with an entry template (and optionally a list template) for each of those collections, passed as `templates`.
+3. A `PublicPathResolver` from `createPublicPathResolver({ collectionRoutes })`, passed as `publicPathResolver`, so canonical URLs, sitemap entries and hreflang siblings match the mounted routes.
+
+Mounting every Schema automatically is not supported: some collections are private even when they carry a slug. Without a `publicPathResolver`, `/sitemap.xml` returns `500`.
+
+## Worked example: a blog
+
+```ts
+// src/web/templates.ts
+import { createPublicPathResolver, TemplateRegistry, renderSeoTagsHtml } from "@aotter/mantle-web";
+
+export const publicPathResolver = createPublicPathResolver({
+  collectionRoutes: { posts: { segment: "posts" } },
+});
+
+export const collectionRoutes = [
+  { collection: "posts", segment: "posts", listRoute: true },
+] as const;
+
+export function createBlogTemplates(): TemplateRegistry {
+  const templates = new TemplateRegistry();
+
+  templates.registerEntryTemplate("posts", ({ entry, site, seo }) => {
+    const title = String(entry.data.title ?? site.title);
+    const meta = seo && {
+      ...seo,
+      jsonLd: { "@context": "https://schema.org", "@type": "BlogPosting", headline: title, url: seo.canonical },
+    };
+    return `<html lang="${entry.locale ?? "en"}"><head><title>${escape(title)}</title>
+      ${meta ? renderSeoTagsHtml(meta) : ""}<link rel="stylesheet" href="/blog.css"></head>
+      <body><article><h1>${escape(title)}</h1>
+      ${seo?.alternateMarkdown ? `<a href="${seo.alternateMarkdown}">Read as Markdown</a>` : ""}
+      ${renderMarkdown(String(entry.data.body ?? ""))}</article></body></html>`;
+  });
+
+  templates.registerListTemplate("posts", ({ entries, locale, site, seo }) => {
+    const items = entries.map((entry) => {
+      const href = publicPathResolver.forEntry(entry) ?? `/${locale}/posts/${entry.id}`;
+      return `<li><a href="${href}">${escape(String(entry.data.title ?? entry.id))}</a></li>`;
+    }).join("");
+    return `<html lang="${locale}"><head><title>Blog · ${escape(site.brand)}</title>
+      ${seo ? renderSeoTagsHtml(seo) : ""}</head><body><ul>${items}</ul></body></html>`;
+  });
+
+  return templates;
+}
+```
+
+```ts
+// worker entry
+export default createMantleWorker<Env>({
+  plan,
+  templates: createBlogTemplates(),
+  publicPathResolver,
+  siteDefaults: (env) => ({ /* ... */ origin: env.PUBLIC_ORIGIN, locales: ["en", "zh-TW"] }),
+  extend: ({ env }) => ({
+    mount({ app, ref }) {
+      mountPublicRoutes(app as never, ref, {
+        collectionRoutes: [...collectionRoutes],
+        notFoundRenderer: async () => htmlNotFound(),
+        liveDev: new URL(env.PUBLIC_ORIGIN).hostname === "localhost",
+      });
+    },
+  }),
+});
+```
+
+Templates return complete HTML strings; the renderer prepends the doctype. Escape every value you interpolate.
+
+## Template signatures
+
+```ts
+templates.registerEntryTemplate(collection, ({ entry, site, mediaAssets?, seo? }) => string);
+templates.registerListTemplate(collection, ({ collection, locale, entries, site, mediaAssets?, seo? }) => string);
+```
+
+`seo` is a composed `SeoMeta`:
+
+| Field | Content |
+|---|---|
+| `canonical` | Absolute canonical URL from `site.origin` and the resolved path |
+| `alternateMarkdown` | Absolute `.md` mirror URL, or `null` when the entry has no Markdown body |
+| `hreflangs` | One row per locale plus `x-default` on multi-locale sites |
+| `description`, `og`, `twitter` | Description, Open Graph and Twitter card blocks |
+| `jsonLd` | A default object; replace it before rendering, as the example does |
+
+`renderSeoTagsHtml(seo)` emits the corresponding tags. Entry pages also get `<link rel="alternate" type="text/markdown">` so crawlers and agents can fetch clean Markdown.
+
+## Routes produced
+
+| Route | Condition |
+|---|---|
+| `GET /` → `302` to `/<canonicalLocale>` | `homeRenderer` set |
+| `GET /:locale`, `GET /:locale.md` | `homeRenderer` set; body from `homeMarkdown` or the `homeSlug` entry |
+| `GET /:locale/<segment>`, `GET /:locale/<segment>.md` | `listRoute: true` |
+| `GET /:locale/<segment>/:slug` | always |
+| `GET /:locale/<segment>/:slug.md` | `markdownMirror` not `false` (default on) |
+| `GET /:locale/<segment>/:slug?preview=1` | staff session; renders live, `private, no-store` |
+| `GET /llms.txt`, `GET /:locale/llms.txt` | always |
+| `GET /sitemap.xml` | always; a urlset, or a sitemap index linking `/sitemap.xml?part=1&cursor=...` parts |
+| `GET /robots.txt` | always; `Allow: /` plus the sitemap URL |
+
+`CollectionRouteConfig` fields: `collection`, `segment` (empty string mounts entries directly under `/:locale/`), `listRoute` (default `false`), `markdownMirror` (default `true`), `homeSlug` (collapse one slug to `/:locale`). `slugOverrides` serve one `(collection, slug)` pair from your own renderer and take precedence over preview and standard rendering. `notFoundRenderer` is required; every miss falls through it. `liveDev` switches entry and list responses to `private, no-store` for local work.
+
+Only entries with `status: published` render. Drafts never appear on pages, mirrors, `llms.txt` or the sitemap; preview needs a staff session and answers `401` or `403` otherwise.
+
+## Pagination
+
+Lists and `llms.txt` return 50 entries per page, ordered `updatedAt DESC, id DESC`, with a forward `cursor`. A continuation adds `Link: <...?cursor=...>; rel="next"`; HTML lists also get a visible `<nav aria-label="Pagination">` Next link, and `llms.txt` appends a `## Continue` section. Sitemap parts hold up to 2,000 URLs divided by the locale count. See [Views](../concepts/views.md) for View-level paging.
+
+## Cache contract
+
+With a valid `cacheScope`, public responses carry `Cache-Control: public, max-age=0, s-maxage=300` and a deployment-scoped cache tag. The facade's final policy keeps that only for anonymous `200` `GET`/`HEAD` responses with no request `Cookie` or `Authorization` and no `Set-Cookie`, and adds `Vary: Cookie, Authorization`. Everything else becomes `private, no-store`, and CDN override headers are removed.
+
+Publishing-content and site-setting writes purge the scoped tag through the native Workers cache API. Purge is best effort after the canonical write. Operational records and static assets are outside that boundary. Enable the cache with `"cache": { "enabled": true }`; see [Bindings](./bindings.md#workers-cache).
+
+> **Warning**
+> The local emulator does not simulate the entrypoint Workers Cache or its purge API. Verify `cf-cache-status` and post-publish invalidation on a deployed environment, not with `wrangler dev`.
+
+## Static assets for templates
+
+Reference CSS, JS and icons by root path (`/blog.css`, `/site-icon.svg`); the `ASSETS` binding serves them from `public/`. Keep public content prefixes in `run_worker_first` so a static file never shadows a rendered route, and leave asset paths out of it so they bypass the Worker.
+
+## Source
+- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
+- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
+- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+- [`packages/mantle-web/README.md`](../../../packages/mantle-web/README.md)
+- [`packages/mantle-web/src/model/TemplateRegistry.ts`](../../../packages/mantle-web/src/model/TemplateRegistry.ts)
+- [`packages/mantle-web/src/model/SeoMeta.ts`](../../../packages/mantle-web/src/model/SeoMeta.ts)
+- [`packages/mantle-web/src/service/SeoMetaComposer.ts`](../../../packages/mantle-web/src/service/SeoMetaComposer.ts)
+- [`packages/mantle-web/src/service/PublicPathResolver.ts`](../../../packages/mantle-web/src/service/PublicPathResolver.ts)
+- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
+- [`docs/performance-harness.md`](../../../docs/performance-harness.md)

package/docs/handbook/concepts/authorization.md

@@ -0,0 +1,116 @@
+---
+description: One authorization pipeline for REST, MCP and Admin — identity kinds, static predicates, the dynamic guard, staff roles and 401/403/402.
+---
+# Authorization
+
+Mantle has one authorization pipeline. A manifest HTTP Trigger, a View over REST, an MCP `tools/call` and an Admin operation all reach the same evaluator, so a rule written once holds on every surface. This page explains the model; the exact `requires` grammar is in the [authorization reference](../reference/authorization.md), and a worked ladder of four access levels is in [Guarded API access](../examples/guarded-api.md).
+
+## The fixed order
+
+Every protected invocation runs the same five steps:
+
+1. Verify and normalize the transport credential.
+2. Evaluate the static predicates in `requires.auth.all`, before any input-schema detail is exposed.
+3. Validate and coerce the target input, or the View params.
+4. Invoke the guard Procedure with that validated value and the same context.
+5. Invoke the target only after the guard succeeds.
+
+Static predicates run before validation so an unauthorized caller cannot probe a schema by reading its error messages. The guard runs after validation so it can decide on the actual arguments. Every stage fails closed.
+
+## Identity kinds
+
+The adapter verifies the transport, then hands the runtime normalized, non-secret metadata. Handlers see this and nothing else:
+
+```ts
+interface HandlerContext {
+  readonly user: { readonly id: string } | null;
+  readonly staff: { readonly id: string; readonly role: StaffRole } | null;
+  readonly auth?: {
+    readonly credential: "session" | "oauth" | "api-key" | "personal-token";
+    readonly credentialId: string | null;
+    readonly clientId: string | null;
+    readonly scopes: readonly string[];
+  };
+}
+```
+
+Three things are distinct:
+
+- **`ctx.user`** is the end-user identity: a row in the site's own Better Auth user table. A service API key may have no user at all.
+- **`ctx.staff`** is a role overlay on top of a user, not a separate account. A user with no overlay is `null` here.
+- **`ctx.auth`** is the verified credential itself, of kind `session`, `oauth`, `api-key` or `personal-token`. Raw keys, refresh tokens and cookies never enter the runtime; `credentialId` is an opaque record id.
+
+The predicate vocabulary is closed and maps onto those three: `ctx.user`, `ctx.auth`, `{ "ctx.auth.scope": "<scope>" }` (repeat it to require several), and `{ "ctx.staff": [roles] }`. There is no credential-kind predicate — a target that must reject browser sessions does so by requiring a scope no session grant carries.
+
+## Predicates versus the guard
+
+| | Static predicates | Guard Procedure |
+|---|---|---|
+| Declared as | `requires.auth.all` | `requires.guard.procedure` |
+| Answers | Is this caller of the right kind, with the right role and scopes? | Is this verified caller allowed to do this business action right now? |
+| Evaluated | Before input validation | After input validation, on every call, never cached |
+| Reads | The compiled plan only | Your tables, your provider state, `ctx.env` |
+| Typical failure | `401` or `403` | `402` |
+
+Anything that changes independently of the credential belongs in the guard: payment state, subscription or membership status, seat counts, per-tenant entitlement. A key stays valid while a subscription lapses, so the fact that a caller paid is not something a token can carry. The guard is an ordinary unguarded `handler.kind: ref` Procedure — not a fifth atom — and it throws a structured diagnostic to deny:
+
+```ts
+throw new DiagnosticError(
+  runtimeDiagnostic({
+    code: "ENTITLEMENT_REQUIRED",
+    severity: "error",
+    path: `site:membership/${ctx.user!.id}`,
+    message: "Active membership is required.",
+  }),
+);
+```
+
+## 401, 403 and 402
+
+| Status | Diagnostic | Meaning |
+|---|---|---|
+| `401` | `UNAUTHENTICATED` | No credential, or a recognized credential that is bad, revoked or expired. |
+| `403` | `AUTH_DENIED` | Verified caller, but a required predicate failed — a missing scope, a missing user subject, an insufficient staff role. |
+| `402` | `ENTITLEMENT_REQUIRED` | Verified and permitted caller whose current business state does not allow the action. |
+
+The split is the point: `401` says *who are you*, `403` says *you may not*, `402` says *not until you settle something*. Only the guard produces `402`, and on `402` the target handler is never invoked. See [Diagnostic codes](../reference/diagnostics.md) for the full mapping.
+
+## Staff roles
+
+Staff roles are `owner`, `editor` and `contributor`. Owners manage staff and site settings; editors publish, approve and manage entries; contributors work on drafts.
+
+A manifest predicate tests **exact membership**, not rank: `{ "ctx.staff": [editor] }` admits editors and nobody else, an owner included. List every role you mean, as in `{ "ctx.staff": [owner, editor] }`. Rank ordering does exist, but only Admin's own route table uses it, which is why an owner passes an Admin route gated at editor. See [Authorization requirements](../reference/authorization.md).
+
+The role is re-read from the database on every protected REST and MCP call. A token snapshot or a consent-time role is not an authorization boundary, so demoting or revoking a user in Admin locks them out on their very next request — no token revocation, no cache flush, no waiting for expiry.
+
+## The credential resolver seam
+
+Sites that issue their own API keys or personal tokens supply one `ConsumerCredentialResolver` through the Worker's `extend` seam. It returns exactly one of three outcomes:
+
+| Outcome | Meaning |
+|---|---|
+| `not-handled` | The request carries none of the site's credential formats. Resolution moves on. |
+| `invalid` | The request carries a recognized format that is bad, revoked or malformed. |
+| `verified` | The site's authoritative record was checked; normalized metadata is returned. |
+
+Resolution precedence is site resolver, then configured OAuth bearer, then cookie session. A recognized-but-invalid credential never falls back to a valid cookie: presenting a revoked key is a failure, not an invitation to be treated as an anonymous browser. Return `not-handled`, never `invalid`, for a request your resolver simply does not recognize.
+
+Scopes are opaque strings the site defines and grants. Mantle compares them; it does not interpret `catalog:read`, publish a scope catalog, or infer a hierarchy. Correspondingly, Mantle issues and stores no API keys or personal tokens, and holds no payment or subscription state. Those tables, their issuance, hashing, rotation and revocation, and whatever fills them from a billing provider, are application code. Mantle owns verification, normalization and enforcement.
+
+## MCP is the same pipeline
+
+An MCP `tools/call` runs the identical evaluator, in the identical order, with the identical diagnostics — surfaced as JSON-RPC errors carrying `error.data.code` instead of an HTTP status. A Trigger's `source.surface` selects which catalog lists a tool, and `tools/list` hides what the caller cannot see. That filtering is discovery UX, not enforcement: a client that guesses a tool name still meets every predicate and the guard. Discovery is never the authorization boundary. See [MCP and agents](./mcp-and-agents.md).
+
+## Related
+
+- [Authorization requirements](../reference/authorization.md) — the `requires` shape, predicate forms, guard rules, OpenAPI projection.
+- [Guarded API access](../examples/guarded-api.md) — a full resolver, guards and the REST/MCP outcome tables.
+- [Reads: Views, REST and MCP](./views.md) — the `$ctx.user` identity-View sentinel.
+- [Authentication](../cloudflare/authentication.md) — sessions, first owner, role management routes.
+
+## Source
+- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
+- [`packages/mantle-runtime/src/domain/model/HandlerContext.ts`](../../../packages/mantle-runtime/src/domain/model/HandlerContext.ts)
+- [`packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts`](../../../packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts)
+- [`packages/adapters/cloudflare/src/mount/resolveCaller.ts`](../../../packages/adapters/cloudflare/src/mount/resolveCaller.ts)
+- [`packages/mantle-spec/src/domain/service/StaffRoleHierarchy.ts`](../../../packages/mantle-spec/src/domain/service/StaffRoleHierarchy.ts)

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

@@ -0,0 +1,173 @@
+---
+description: Schema, View, Procedure and Trigger — what each atom owns, why reads and writes are asymmetric, and how to compose everything else from four kinds.
+---
+# The four atoms
+
+A Mantle Manifest declares exactly four resource kinds under the `cms.mantle.aotter.net/v1` API group. This page explains what each atom owns, how they compose, and how to decide where a new feature belongs. Field-level rules live in the [Reference](../reference/manifest.md) section.
+
+## The four kinds
+
+They map one-to-one onto the primitives Postgres has shipped for thirty years.
+
+| Atom | Postgres equivalent | Externally exposed by itself? | Has user code? |
+|---|---|---|---|
+| `Schema` | `CREATE TABLE` | No. Reached only through a View or a Procedure. | No |
+| `View` | `CREATE VIEW` | Yes. Auto-mounted on its declared `public` or `staff` REST and MCP surface. | No |
+| `Procedure` | `CREATE FUNCTION` | No. Transport-agnostic; needs a Trigger to gain a surface. | Yes — a handler in your project's registry. |
+| `Trigger` | `CREATE TRIGGER` plus route and tool binding | Yes. It is the binding atom. | No |
+
+A four-word gloss covers most questions: Schema is state, View is the read API, Procedure is the write API, Trigger is the binding.
+
+## Reads and writes are asymmetric on purpose
+
+Views mount themselves; Procedures do not. That asymmetry matches HTTP safe-versus-unsafe semantics. A View is a named, read-only query: idempotent, cacheable, and safe to expose the moment its `surface` is declared. A Procedure changes state, so its path, method, tool name and authorization are decisions an author must make explicitly, one Trigger at a time. There is no `Schema.spec.expose.rest` switch and no `/api/<collection>` shortcut; exposing collections directly was considered and rejected, because a Schema stores drafts, server-stamped fields and rows the author never meant to publish.
+
+The consequence for authors: a Procedure that has no Trigger is unreachable from outside the runtime, and calling its name as a URL returns `404`.
+
+## The composition rule
+
+Anything more domain-shaped than these four is not an atom. A Form, Membership, Email, Webhook, Workflow or ScheduledJob is a composition of Schemas, Views, Procedures and Triggers plus your own TypeScript. An earlier iteration of this grammar shipped eleven domain-shaped kinds; authors could not decide whether a contact form was a Form, a Workflow or an Email, and each kind grew to subsume its neighbors.
+
+If you find yourself wanting a fifth kind, sketch the same thing as a composition of the four first. Almost always it works.
+
+## The Manifest envelope
+
+Every document carries the same four top-level keys. Unknown keys at any known level are rejected with `INVALID_MANIFEST_ENVELOPE`.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema | View | Procedure | Trigger
+metadata:
+  name: posts
+spec: {}
+```
+
+There is no `namespace` field. Names are unique within a kind, so a Schema and a View may share a name; two Schemas may not. Multi-tenancy belongs in your application layer, not in manifest metadata.
+
+One feature usually needs several atoms, so YAML's `---` separator keeps the file count down. Core reads every immediate `.yaml` and `.yml` file in the manifest directory and parses each document independently:
+
+```yaml
+# manifests/contact.yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: send-contact-message
+spec:
+  input:
+    type: object
+    additionalProperties: false
+    required: [name, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 80 }
+      message: { type: string, minLength: 1, maxLength: 4000 }
+  output: { type: object }
+  handler: { kind: ref, ref: send-contact-message }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: contact-http
+spec:
+  source: { kind: http, method: POST, path: /api/contact }
+  target: { procedure: send-contact-message }
+```
+
+Parsing is all-or-nothing: one error in one document means no `ParsedManifestSet` at all.
+
+## Schema — the entity
+
+A Schema declares one collection: the JSON Schema for each entry's `data`, its indexes, its Admin presentation and its [lifecycle mode](./lifecycle-and-locales.md). Entries also carry the native columns `id`, `status`, `version`, `createdAt`, `updatedAt` and `authorId` outside `data`.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: notes
+spec:
+  title: Notes
+  lifecycle: publishing
+  schema:
+    type: object
+    additionalProperties: false
+    required: [title, body]
+    properties:
+      title: { type: string, minLength: 1, maxLength: 200 }
+      body: { type: string, x-mcp-hint: markdown }
+  searchableFields: [title]
+```
+
+Full field rules, the JSON Schema subset and the `x-mantle-bind` / `x-mantle-ref` / `x-mcp-hint` keywords are in the [Schema reference](../reference/schema.md).
+
+## View — the read surface
+
+A View is a named read-only query over Schemas, mounted on exactly one surface. No Trigger is involved.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: published-notes
+spec:
+  title: Published notes
+  surface: public
+  from: notes
+  fields: [id, title, updatedAt]
+  filter:
+    eq: { field: status, value: published }
+  orderBy:
+    - { field: updatedAt, direction: desc }
+  limit: 20
+```
+
+`surface: public` serves `GET /api/views/published-notes` and the `query_view_published_notes` MCP tool on `/mcp`; `surface: staff` moves both behind the staff gate. See [Reads: Views, REST and MCP](./views.md) and the [View reference](../reference/view.md).
+
+## Procedure — the typed callable
+
+A Procedure declares typed `input`, typed `output`, optional `requires`, and one `handler`. It is the only atom with a code seam. The handler is either `kind: builtin` — a CRUD shortcut over one Schema — or `kind: ref`, an opaque key into the `handlers` map your project registers.
+
+```yaml
+spec:
+  handler: { kind: builtin, op: create, schema: notes }
+```
+
+Builtin ops are `create`, `update`, `upsert`, `delete` and `archive`. `request_publish` and `publish` are deliberately absent: they are lifecycle operations, not CRUD primitives. See [Writes: Procedures, Triggers and lifecycle hooks](./procedures-and-triggers.md) and the [Procedure reference](../reference/procedure.md).
+
+## Trigger — the binding
+
+A Trigger says "when X happens, run Procedure Y". Its `source` is one of three kinds, and its `target.procedure` names a declared Procedure.
+
+```yaml
+spec:
+  source: { kind: http, method: POST, path: /api/contact }
+  # or: { kind: mcp, surface: public }
+  # or: { kind: lifecycle, schema: notes, on: [before_create] }
+  target: { procedure: send-contact-message }
+```
+
+Several Triggers may target one Procedure, which is how the same handler becomes an HTTP endpoint, an MCP tool and a lifecycle hook without duplicated logic. Adding a transport is additive; the Procedure never changes. See the [Trigger reference](../reference/trigger.md).
+
+## How to think when extending
+
+1. **What entities does the feature need?** One `Schema` each.
+2. **What named queries?** One `View` each. Ad-hoc reads stay inside handler code; only sanctioned queries become Views, because a View is an external read endpoint.
+3. **What operations?** One `Procedure` each. One Procedure equals one typed function call. Compose in handler code, not in YAML.
+4. **What invokes them?** One `Trigger` per declared HTTP, MCP or lifecycle source.
+5. **Who is allowed?** `requires.auth` for static identity and scope, plus one optional `requires.guard.procedure` for a live business check. See [Authorization](./authorization.md).
+
+## The Postgres heuristic
+
+When you are unsure whether something deserves to be an atom, ask what it would be in Postgres.
+
+- If it is a `CREATE X` an **application developer** writes — `TABLE`, `VIEW`, `FUNCTION`, `TRIGGER` — it maps to one of the four.
+- If it is a `CREATE X` Postgres only needs because it is a database engine — `INDEX`, `MATERIALIZED VIEW`, `TABLESPACE`, `STATISTICS`, `EVENT TRIGGER`, `EXTENSION`, `LANGUAGE`, `PUBLICATION`, `FOREIGN TABLE`, `RULE` — it does not map, and it belongs behind the storage adapter.
+- If it is a type-system extension — `TYPE`, `DOMAIN`, `SEQUENCE`, `COLLATION`, `CAST`, `AGGREGATE`, `OPERATOR` — it folds into the JSON Schema inside a `Schema`.
+
+Postgres exposes roughly twenty-five object kinds; an application developer writes four to six of them. That is the same ratio Mantle ships.
+
+## Source
+
+- [`docs/adr/0001-four-atom-manifest-model.md`](../../../docs/adr/0001-four-atom-manifest-model.md)
+- [`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)