@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

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

@@ -0,0 +1,142 @@
+---
+description: Choose between publishing and operational Schemas, and understand how site locales, localized Schemas and translation children fit together.
+---
+# Lifecycle and locales
+
+Two per-Schema decisions shape how an entry behaves for its whole life: which state machine it follows, and whether it carries a locale. Both are declared on the [Schema](../reference/schema.md); neither is a site-wide setting.
+
+## Publishing versus operational
+
+`spec.lifecycle` is `publishing` (the default) or `operational`. The modes mix freely inside one site.
+
+**`publishing`** is for content a person stages and then releases: posts, pages, announcements, product copy. The point of the mode is that a draft exists and is not readable by the public until someone publishes it.
+
+**`operational`** is for records written as a side effect rather than drafted: submissions, inquiries, orders, inventory snapshots, grant and audit rows. The point of the mode is that the row is real the moment it is created. Declare it on any Schema whose rows a human should inspect and correct, never stage and publish.
+
+| `publishing` — from | To |
+|---|---|
+| `draft` | `published`, `archived` |
+| `published` | `archived`, `draft` |
+| `archived` | `draft` |
+
+| `operational` | Behavior |
+|---|---|
+| On create | `status: published` immediately |
+| Editing | In place, in any status |
+| Transitions | None. Publish, unpublish and archive all reject. |
+
+Any transition the machine does not allow returns `CONFLICT` (HTTP 409). That includes every transition request against an operational Schema, and deleting a `published` entry of a publishing Schema — unpublish it first. Operational entries can be deleted in any status. A builtin `archive` Procedure may only target a publishing Schema.
+
+`status: published` on an operational row is not a grant of public read access. Reads are still authorized by the [View](./views.md) that exposes them.
+
+### What each surface shows
+
+| Surface | `publishing` | `operational` |
+|---|---|---|
+| Admin | Draft and published buckets, publish and unpublish controls, archive | Flat list, no lifecycle chrome; `uiSchema.list` supplies the columns |
+| Staff MCP | `create_draft_<schema>`, `update_draft_<schema>` | `create_record_<schema>`, `update_record_<schema>` |
+| Staff MCP, both modes | `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry` | same generic lifecycle tools |
+
+### Procedure-managed collections
+
+Root `schema.readOnly: true` marks a collection whose authority lives in its declared Procedures, not in generic authoring. Staff MCP emits no `create_*` or `update_*` tool for it, and Admin's generic create, update, status change and delete return `CONFLICT` with a message saying the Schema is read-only on generic authoring surfaces. Declared Views and Procedures keep working. Use it for operational mirrors, projections and audit rows.
+
+## Locales in three layers
+
+Localization is not one switch. Three independent layers have to agree.
+
+| Layer | Where | What it decides |
+|---|---|---|
+| `Schema.spec.localized` | Manifest | Whether rows of this collection may carry `data.locale` |
+| `site_config.locales` | Adapter `siteDefaults.locales`, boot-synced into the `site_config` row | Which locale tags exist for this deployment; the first entry is the canonical locale |
+| `data.locale` | The entry | Which locale this particular row is |
+
+`siteDefaults.locales` is code-owned: Core rewrites the stored row at boot whenever the declared list differs, so the code stays canonical. Brand, title and description seed once and are then edited through site settings. See [Site defaults and site_config](../reference/site-config.md).
+
+### Canonical tags
+
+Mantle accepts a deliberately narrow subset of BCP 47: a two- or three-letter language, plus an optional two-letter region. Mixed spellings are canonicalized, so `zh-tw`, `ZH_TW` and `zhTW` all become `zh-TW`, and the list is deduplicated in place. Anything else fails at boot with `InvalidSiteDefaultsError`.
+
+> **Script subtags are unsupported**
+> `zh-Hant`, `zh-Hans`, `sr-Latn` and `sr-Cyrl` are valid BCP 47 but rejected in this version. Use region tags: `zh-TW` for Traditional Chinese, `zh-CN` for Simplified.
+
+### The write-time gate
+
+Every authoring path — Admin, Staff MCP and builtin Procedures — runs the same guard, per request, against the current site locales.
+
+| Condition | Result |
+|---|---|
+| Non-localized Schema, `data.locale` present | `INPUT_VALIDATION_FAILED` |
+| Localized Schema, `data.locale` missing or empty | `INPUT_VALIDATION_FAILED`, skipped for partial draft saves |
+| Localized Schema, `data.locale` not in the site locales | `INPUT_VALIDATION_FAILED`, with the enabled locales as candidates |
+| Site locales list is empty | Membership is not checked |
+
+`locale` is a reserved data field. A non-localized Schema that declares it is rejected outright; when such a Schema genuinely needs a language value, name it after its domain meaning — `replyLocale` on a support ticket, `orderLocale` on an order — and validate it with an `enum` like any other field.
+
+### Boot checks versus per-request resolution
+
+Boot validates shape only: the locale tags canonicalize, every `translates` reference resolves, and a `localized: true` Schema has at least one site locale (`SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES`). The active locale set is read from `site_config` per request, so changing the list does not require a redeploy of the manifest — but it does require the code-owned `siteDefaults` to agree, because boot resynchronizes the row.
+
+## Versions of one entity versus independent rows
+
+Two shapes are legal, and the choice is about identity, not about language count.
+
+**A standalone localized Schema** treats each locale row as an independent record. Use it when nothing is shared between languages except a naming convention. A blog whose translations are independent posts does this: one localized `posts` Schema with `uniqueIndexes: [[slug, locale]]`.
+
+**A non-localized parent plus a localized `translates` child** treats locale rows as versions of one entity. Use it when several rows describe the same thing and editors need to see which languages are missing. Only this shape powers Admin's translation grouping and completeness; Admin renders the child as locale tabs inside the parent's editor rather than as its own collection.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: products
+spec:
+  title: Products
+  localized: false
+  lifecycle: publishing
+  uniqueIndexes: [[sku]]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [sku, priceMinor]
+    properties:
+      sku: { type: string, pattern: "^[A-Z0-9-]+$" }
+      priceMinor: { type: integer, x-mcp-hint: money-minor }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: product-translations
+spec:
+  title: Product translations
+  localized: true
+  translates: { parent: products, on: sku }
+  lifecycle: publishing
+  uniqueIndexes: [[sku, locale]]
+  indexes: [[locale, sku]]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [sku, name]
+    properties:
+      sku: { type: string, pattern: "^[A-Z0-9-]+$" }
+      locale: { type: string }
+      name: { type: string, minLength: 1 }
+      summary: { type: string, x-mcp-hint: markdown }
+```
+
+The parent holds what every language shares and stays non-localized. The child sets `localized: true`, declares `locale` without listing it in `required` — the write-time gate enforces presence — and owns at least one content field besides the join field and `locale`. A parent that is itself localized, a missing join field on either side, or a child with no content field are all rejected at parse or validate time; the codes are listed in the [Schema reference](../reference/schema.md#translates).
+
+When you keep parallel locale rows in step, translate display strings only. Field names, option values, step identifiers and result keys must stay identical across locales, or the same View and the same MCP tool stop describing the same thing.
+
+The full worked version of this pattern, with a locale-parameterized public View and its REST response, is [Publication](../examples/publication.md).
+
+## Source
+
+- [`packages/mantle-spec/src/domain/service/LifecycleStateMachine.ts`](../../../packages/mantle-spec/src/domain/service/LifecycleStateMachine.ts)
+- [`packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts`](../../../packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts)
+- [`packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts`](../../../packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts)
+- [`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)

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

@@ -0,0 +1,109 @@
+---
+description: Mantle serves /mcp and /mcp/staff from the same Manifest — tool naming, the OAuth model, connecting a client, llms.txt, WebMCP and skills.
+---
+# MCP and agents
+
+Mantle is an MCP server out of the box. Nothing is registered, exported or annotated to make it one: the same compiled plan that produces REST and Admin also produces the tool catalog, so an agent and a browser reach identical behavior through different transports. This page covers the two surfaces, how tools are named, how a client authenticates, and the rest of the agent-facing surface area.
+
+## Two surfaces
+
+| Mount | Caller | Exposes |
+|---|---|---|
+| `/mcp` | Any authenticated OAuth caller; anonymous requests get `401` | Views with `surface: public`, and Procedures reached by an MCP Trigger with `surface: public` |
+| `/mcp/staff` | Authenticated caller holding a staff role | Views with `surface: staff`, the generic authoring tools (rank-gated at `tools/call`), Procedures reached by an MCP Trigger with `surface: staff` |
+
+Both accept tokens for one canonical protected resource, `${PUBLIC_ORIGIN}/mcp`. `/mcp/staff` is a stricter server-side role projection, not a second OAuth audience.
+
+## Tool naming
+
+A tool name is derived from a manifest name by `mcpToolNameSegment`: lowercased, with `-` replaced by `_`.
+
+| Tool | Produced by | Surface |
+|---|---|---|
+| `query_view_<segment>` | Any View | The View's own `surface` |
+| `create_draft_<schema>`, `update_draft_<schema>` | A Schema with `lifecycle: publishing` | Staff |
+| `create_record_<schema>`, `update_record_<schema>` | A Schema with `lifecycle: operational` | Staff |
+| `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry` | Present when an applicable Schema exists | Staff |
+| `create_media_upload`, `commit_media_upload` | Media storage bound and at least one purpose declared | Staff |
+| `<procedure segment>` | A Trigger with `source.kind: mcp` | The Trigger's `source.surface` |
+
+A Schema whose root `schema` sets `readOnly: true` gets no authoring tools; its declared Procedures still work. Update tools add required `id` and `expected_version` arguments, and fields carrying `x-mantle-bind` are stripped from authoring tool schemas because the runtime stamps them. Those generic names and the `create_draft_`, `update_draft_`, `create_record_`, `update_record_` and `query_view_` prefixes are reserved; a collision is rejected at validation with `MCP_TOOL_NAME_COLLISION`.
+
+Procedures are never exposed on their own. A Procedure becomes a tool only through a Trigger of `kind: mcp`, exactly as it becomes a route only through a Trigger of `kind: http`. Writing a Procedure with no Trigger gives you typed logic that nothing can call from outside — which is what a guard Procedure or a cron-invoked Procedure wants. See [Writes: Procedures, Triggers and hooks](./procedures-and-triggers.md).
+
+## The OAuth model
+
+The Cloudflare adapter runs one Better Auth 1.7 instance for staff identity, authorization, consent, client registration and MCP resource verification. Client identity is CIMD-first — the MCP 2026-07-28 Client ID Metadata Document profile, which is why the Worker needs the `global_fetch_strictly_public` flag to fetch client metadata across the public Internet boundary — with unauthenticated legacy DCR kept only as a bounded compatibility path for older clients, on the previous provider's 90-day default lifetime. One non-colon scope, `mcp`, is advertised in `scopes_supported`, because clients such as claude.ai reject colon-shaped scopes; per-surface enforcement then happens server-side, not through scope strings. Authorization is session-bound: the JWT's originating Better Auth session must still exist and be unexpired, so signing out of Admin also ends that session's MCP access, and a refresh token is not an independent authorization. Unauthenticated requests to either mount answer `401` with a `WWW-Authenticate` challenge pointing at the RFC 9728 protected-resource metadata document served under the auth mount. Authorization endpoints live under `/api/auth/oauth2/*` and are discovered from the advertised metadata, never hard-coded.
+
+## Connecting a local client
+
+Start the dev server and use the exact origin it prints. Before touching client configuration, confirm the endpoint is reachable and protected:
+
+```sh
+curl -i http://localhost:8787/mcp
+```
+
+An OAuth-protected endpoint answers `401` with a `WWW-Authenticate` resource-metadata challenge before sign-in. A `503 setup_incomplete` instead means Auth configuration is missing; see [Authentication](../cloudflare/authentication.md).
+
+Prefer the client's native remote HTTP and OAuth support. Use a standard HTTP-to-stdio bridge only when the client accepts stdio MCP servers and cannot connect to remote HTTP directly:
+
+```sh
+npx -y mcp-remote http://localhost:8787/mcp
+```
+
+Mantle owns no local proxy and no auth-bypass mode. After connecting, inspect `tools/list`, then make one read-only `query_view_*` call before invoking any mutation — it proves the credential, the surface and the data path in one step that cannot damage anything. Use project-scoped client configuration where the client offers it, and never commit OAuth tokens or the bridge's token cache.
+
+> **Discovery is not enforcement**
+> `tools/list` filtering is UX. Every `tools/call` re-evaluates the manifest predicates and the guard through the same evaluator REST uses, so a guessed tool name gains nothing. See [Authorization](./authorization.md).
+
+## The agent-readable web surface
+
+When a Worker mounts public pages, the same content is served in a form agents can read without parsing HTML:
+
+- **Markdown mirrors.** Every entry page has a `.md` twin at the same path, and entry pages advertise it with `<link rel="alternate" type="text/markdown">`.
+- **`llms.txt` indexes.** `GET /llms.txt` lists the site; `GET /:locale/llms.txt` lists one locale. Pages hold 50 entries, ordered `updatedAt DESC, id DESC`, with a forward `cursor`, a `Link: ...; rel="next"` header and a `## Continue` section.
+- **Sitemap.** `GET /sitemap.xml` returns a urlset, or an index linking `/sitemap.xml?part=1&cursor=...` parts of up to 2,000 URLs each.
+
+Only `status: published` entries appear anywhere in that set. Details are in [Public web, SEO and cache](../cloudflare/public-web.md).
+
+## WebMCP in the browser
+
+`@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
+import { bindWebMcp } from "@aotter/mantle-web/webmcp";
+
+const binding = await bindWebMcp();
+// later, when the page or app scope ends
+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).
+
+## Skills for your coding agent
+
+The installed SDK ships version-matched instructions for agents working on a Mantle project. Project them into the repository:
+
+```sh
+pnpm exec mantle skills
+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.
+
+For Claude Code, the same bundle is installable from the plugin marketplace at the exact installed version:
+
+```sh
+/plugin marketplace add aotter/mantle@v<installed-version>
+```
+
+Never point a versioned project at a mutable branch. See [Project layout and the CLI loop](../start/project-and-cli.md).
+
+## Source
+- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
+- [`docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md`](../../../docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md)
+- [`packages/mantle-spec/src/domain/service/McpToolNaming.ts`](../../../packages/mantle-spec/src/domain/service/McpToolNaming.ts)
+- [`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)

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

@@ -0,0 +1,221 @@
+---
+description: How writes work — typed Procedures with a code seam, the three Trigger kinds that bind them, builtin ops, lifecycle hooks and the HTTP envelope.
+---
+# Writes: Procedures, Triggers and lifecycle hooks
+
+Every write goes through a Procedure, and every Procedure that anything outside the runtime can reach has a Trigger. This page explains the split and the lifecycle hook contract. Field-level rules are in the [Procedure](../reference/procedure.md) and [Trigger](../reference/trigger.md) references.
+
+## A Procedure is a callable, not an endpoint
+
+A Procedure declares typed `input`, typed `output`, optional `requires`, and one `handler`. It contains no path, no method and no tool name; it is transport-agnostic on purpose, so calling a Procedure name as a URL returns `404`. Exposing a write is a separate, explicit decision.
+
+Invocation runs in a fixed order: static auth predicates, input validation, the optional guard Procedure, the handler, then output validation — which checks the returned value but does not strip extra fields.
+
+The Procedure is also the only atom with a code seam. `handler: { kind: ref, ref: <key> }` names an opaque registration key — not a file path — that your project maps to a function in its `handlers` object. A key with no registered function fails at boot with `HANDLER_NOT_REGISTERED`.
+
+## A Trigger is the only binding
+
+`Trigger.spec.target.procedure` names a declared Procedure; `spec.source` says what reaches it. There are three source kinds.
+
+| `source.kind` | Binds to | Notes |
+|---|---|---|
+| `http` | `method` and `path` | `POST`, `PUT`, `PATCH`, `DELETE` only. `GET` is absent because reads belong to [Views](./views.md). The path must start `/api/`, must not collide with another Trigger or an adapter-reserved prefix, and may use OpenAPI `{param}` segments that auto-bind to same-named input fields. |
+| `mcp` | `surface: public` or `staff` | The tool is named after the Procedure, lowercased with hyphens replaced by underscores. Surface controls discovery only; `requires` is re-evaluated on every `tools/call`. |
+| `lifecycle` | `schema`, `on: [<hook>]`, optional `errorPolicy` | Fires around entry mutations. See [Lifecycle hooks](#lifecycle-hooks). |
+
+One Procedure may carry several Triggers, and that is how the same handler becomes an HTTP endpoint, an MCP tool and a hook without duplicated logic. Adding a transport is additive: write another Trigger, leave the Procedure alone.
+
+## Builtin or `ref`
+
+`handler.kind: builtin` is a thin shortcut over the storage adapter. The rule is simple: **use `builtin` when the body of the operation is "insert a row", "update a row" or "delete a row"; reach for `ref` when there is real business logic.** A guard Procedure can never be builtin.
+
+| `op` | What it does | Input contract |
+|---|---|---|
+| `create` | Projects `input ∩ Schema.properties`, stamps `x-mantle-bind` fields, inserts. Status is `draft`, or `published` for an operational Schema. Returns the created `EntryRow`. | An object schema |
+| `update` | Loads, merges the patch, bumps `version` under optimistic concurrency using the caller's observed `expectedVersion` (not `version+1`) | `id` (strict string) and `expectedVersion` (strict number), both required |
+| `upsert` | With `match`, looks the row up by natural key: update with the caller token, or create when no row exists and no version was sent | `match` equals one `uniqueIndexes` tuple exactly, in order; no `id`; `expectedVersion` declared as strict number but not globally required |
+| `delete` | Hard delete by id | `id` (strict string) required |
+| `archive` | Transitions to `archived`, or `CONFLICT` if the machine disallows it | `id` required; publishing Schemas only |
+
+`request_publish` and `publish` are deliberately not builtin ops. They are lifecycle operations, not CRUD primitives.
+
+Every builtin write runs the same guards: locale gate, then a unique-index preflight. A race that slips past the preflight is caught by the database constraint and surfaces as `CONFLICT` (409) with no automatic retry.
+
+### Side-channel input fields
+
+A Procedure's `input` is the contract with the caller, not with the Schema. It may declare fields the Schema does not — a Turnstile token, a honeypot value, a referrer. The builtin op projects `input ∩ Schema.properties` and silently drops the rest, so nothing extra is stored.
+
+Those fields are still readable where it matters: a `before_create` or `before_update` hook receives the **original, pre-projection** input. Every `after_*` hook receives only the persisted `entry.data`. That asymmetry is why bot checks are `before_*` hooks and notifications are `after_*` hooks.
+
+## Lifecycle hooks
+
+| Hook | Fires | Default `errorPolicy` |
+|---|---|---|
+| `before_create` | Before insert | `abort` |
+| `after_create` | After insert | `continue` |
+| `before_update` | Before an update, or a status transition whose target is not `published` | `abort` |
+| `after_update` | After an update, or a status transition whose target is not `published` | `continue` |
+| `before_delete` | Before delete | `abort` |
+| `after_delete` | After delete | `continue` |
+| `before_publish` | Before a transition to `published` | `abort` |
+| `after_publish` | After a transition to `published` | `continue` |
+
+> **Update hooks are not edit-only**
+> There are no unpublish-specific or archive-specific hooks. `before_update` and `after_update` also fire for unpublish, archive and every other transition whose target is not `published`. A hook that assumes "the row was edited" will run on state changes you did not intend.
+
+`abort` means a throwing handler cancels the surrounding mutation and the caller receives `LIFECYCLE_HOOK_REJECTED` (409). `continue` means the committed mutation stands: on the inline or `waitUntil` path the failure is logged and swallowed. Authors may set `errorPolicy` explicitly, but `abort` is rejected on a Trigger whose `on` list contains any `after_*` hook — a committed write cannot be un-committed.
+
+Hooks are wired through the entry repository, so Admin, Staff MCP and builtin Procedures all fire the same hooks. When several lifecycle Triggers bind the same schema and hook, they fire **alphabetically by `Trigger.metadata.name`**; number them (`010-bot-check`, `020-rate-limit`) so the order is visible.
+
+Handlers receive `ctx.event = { id, trigger, hook, schema, entry }`. `id` is stable across retries, `trigger` is the current Trigger name, and `entry` is `null` only for `before_create`; otherwise it is the pre-mutation row for `before_*` and the persisted row for `after_*`.
+
+### Deferred `after_*` delivery
+
+With an optional `DeferredHookDispatcher`, `after_*` hooks leave the request path and run under the delivery adapter's at-least-once retry and dead-letter policy instead of being swallowed. Delivery is not transactional with the database and exactly-once is not promised, so handlers must be idempotent; the conventional key is `${ctx.event.id}:${ctx.event.trigger}`. Cloudflare wiring, the envelope and DLQ configuration are in [Deferred hooks with Queues](../cloudflare/deferred-hooks-queues.md).
+
+## The HTTP envelope
+
+An HTTP Trigger wraps the handler's result as `{ "ok": true, "data": <result> }`, or returns the redacted diagnostic with the code's mapped status:
+
+```json
+{ "ok": false, "diagnostic": { "code": "INPUT_VALIDATION_FAILED", "path": "POST /api/contact#/name" } }
+```
+
+For a builtin `create`, `data` is the whole `EntryRow`: `id`, `collection`, `status`, `version`, `data`, nullable `authorId`, millisecond `createdAt` and `updatedAt`, and `locale` on localized rows. Declare `spec.output` against that row, not against the envelope. The request body must be a JSON object; anything else is a 400, and an oversize body is a 413.
+
+| Code | HTTP | When |
+|---|---|---|
+| `INPUT_VALIDATION_FAILED` | 400 | Input fails the converted schema, or the body is not a JSON object |
+| `UNAUTHENTICATED` | 401 | No verified credential at all |
+| `ENTITLEMENT_REQUIRED` | 402 | A guard Procedure denied the current business entitlement |
+| `AUTH_DENIED` | 403 | Authenticated, but a `requires.auth` predicate was false |
+| `NOT_FOUND` | 404 | Unknown entry id or View name |
+| `CONFLICT` | 409 | Illegal lifecycle transition, or a unique-index collision |
+| `LIFECYCLE_HOOK_REJECTED` | 409 | A `before_*` hook aborted the mutation |
+| `OUTPUT_VALIDATION_FAILED` | 500 | The handler returned a value its `output` schema rejects |
+| `HANDLER_NOT_REGISTERED` | 500 | A `ref` key has no registered function |
+| `INTERNAL_ERROR` | 500 | Uncaught handler exception |
+
+The full catalog is in [Diagnostic codes](../reference/diagnostics.md).
+
+## Worked example: a contact form
+
+One builtin write, one `before_create` check that can abort it, one `after_create` notification that cannot.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: contact-messages
+spec:
+  title: Contact messages
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [name, email, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 80 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 4000 }
+      submittedAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: send-contact-message
+spec:
+  title: Send contact message
+  input:
+    type: object
+    additionalProperties: false
+    required: [name, email, message, botToken]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 80 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 4000 }
+      botToken: { type: string, minLength: 1 }
+  output:
+    type: object
+    required: [id]
+    properties:
+      id: { type: string }
+  handler: { kind: builtin, op: create, schema: contact-messages }
+---
+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 }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: check-contact-bot
+spec:
+  input:
+    type: object
+    properties:
+      botToken: { type: string }
+  output: { type: object }
+  handler: { kind: ref, ref: check-contact-bot }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: 010-contact-bot-check
+spec:
+  source:
+    kind: lifecycle
+    schema: contact-messages
+    on: [before_create]
+    errorPolicy: abort
+  target: { procedure: check-contact-bot }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: notify-contact-message
+spec:
+  input:
+    type: object
+    properties:
+      name: { type: string }
+      email: { type: string }
+      message: { type: string }
+  output: { type: object }
+  handler: { kind: ref, ref: notify-contact-message }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: 020-contact-notify
+spec:
+  source:
+    kind: lifecycle
+    schema: contact-messages
+    on: [after_create]
+    errorPolicy: continue
+  target: { procedure: notify-contact-message }
+```
+
+What each piece is doing:
+
+- `botToken` is declared on the Procedure input but not on the Schema, so it is validated, read by the hook, and never stored.
+- `010-contact-bot-check` runs first because Triggers on the same hook fire alphabetically. Throwing from its handler cancels the insert and the caller receives 409 `LIFECYCLE_HOOK_REJECTED`; nothing is written.
+- `020-contact-notify` runs after the row exists and receives only `entry.data`. A failing mailer is logged, not fatal — the visitor's message is already saved.
+- `submittedAt` is stamped by the runtime, so it is absent from the Procedure input and from Staff MCP authoring tools.
+- Adding `{ kind: mcp, surface: public }` as a fourth Trigger would publish the same Procedure as an agent tool without touching a handler.
+
+Register the two `ref` keys in the project's handlers map, then run the check loop from [Project layout and the CLI loop](../start/project-and-cli.md). The complete version with real Turnstile and email handlers is [Intake form](../examples/intake-form.md).
+
+## Source
+
+- [`docs/adr/0001-four-atom-manifest-model.md`](../../../docs/adr/0001-four-atom-manifest-model.md)
+- [`docs/deferred-lifecycle-queues.md`](../../../docs/deferred-lifecycle-queues.md)
+- [`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)