@aotter/mantle 0.1.2-alpha.5 → 0.1.2-rc.1

package/docs/examples/builtin-commerce.md

@@ -0,0 +1,269 @@
+---
+description: A product catalog and guest orders using only builtin create and update. No Durable Object, Queue, payment provider, or ref handlers.
+---
+# Commerce catalog and orders
+
+**Handler class:** builtin · **Builder:** yes · [Examples hub](./README.md). Stock authority, Queue expiry, and a verified payment callback are [Commerce inventory](./cf-primitives-commerce-inventory.md).
+
+This example publishes products, lists them publicly, accepts guest orders with builtin `create`, and lets staff mark orders fulfilled or cancelled with builtin `update`. Every Procedure is `handler.kind: builtin`. It does not re-price lines, reserve stock, or talk to a payment provider.
+
+## Problem
+
+Staff publish products with a price. A guest places an order by sending customer fields, an order number, currency, a total, and line items. Staff see submitted orders and record fulfillment or cancellation. Mantle stores the catalog and the order rows. There is no inventory authority in this Manifest.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: products
+spec:
+  title: Products
+  lifecycle: publishing
+  uniqueIndexes:
+    - [slug]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [slug, title, priceMinor, currency]
+    properties:
+      slug: { type: string, pattern: "^[a-z0-9-]+$" }
+      title: { type: string, minLength: 1, maxLength: 160 }
+      summary: { type: string, maxLength: 500 }
+      priceMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
+      currency: { type: string, pattern: "^[A-Z]{3}$" }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: orders
+spec:
+  title: Orders
+  description: Guest orders created and updated only by declared builtin Procedures.
+  lifecycle: operational
+  uniqueIndexes:
+    - [orderNumber]
+  indexes:
+    - [orderStatus]
+  searchableFields: [orderNumber, customerName, customerEmail]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [orderNumber, orderStatus, currency, totalMinor, customerName, customerEmail, shippingAddress, items, placedAt]
+    properties:
+      orderNumber: { type: string, minLength: 1, maxLength: 40 }
+      orderStatus: { type: string, enum: [submitted, fulfilled, cancelled] }
+      currency: { type: string, pattern: "^[A-Z]{3}$" }
+      totalMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
+      customerName: { type: string, minLength: 1, maxLength: 120 }
+      customerEmail: { type: string, format: email }
+      shippingAddress: { type: string, minLength: 1, maxLength: 500 }
+      items:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          type: object
+          additionalProperties: false
+          required: [productSlug, title, quantity, unitPriceMinor, lineTotalMinor]
+          properties:
+            productSlug: { type: string, pattern: "^[a-z0-9-]+$" }
+            title: { type: string }
+            quantity: { type: integer, minimum: 1, maximum: 99 }
+            unitPriceMinor: { type: integer, minimum: 0 }
+            lineTotalMinor: { type: integer, minimum: 0 }
+      trackingNumber: { type: string, maxLength: 120 }
+      cancelReason: { type: string, maxLength: 500 }
+      placedAt: { type: number, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: public-products
+spec:
+  title: Public products
+  surface: public
+  from: products
+  fields: [id, slug, title, summary, priceMinor, currency, updatedAt]
+  filter:
+    eq: { field: status, value: published }
+  orderBy:
+    - { field: slug, direction: asc }
+  limit: 100
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: submitted-orders
+spec:
+  title: Submitted orders
+  surface: staff
+  from: orders
+  fields: [id, version, orderNumber, orderStatus, customerName, customerEmail, shippingAddress, totalMinor, currency, placedAt]
+  filter:
+    eq: { field: orderStatus, value: submitted }
+  orderBy:
+    - { field: placedAt, direction: asc }
+  limit: 100
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: place-order
+spec:
+  title: Place order
+  input:
+    type: object
+    additionalProperties: false
+    required: [orderNumber, orderStatus, currency, totalMinor, customerName, customerEmail, shippingAddress, items]
+    properties:
+      orderNumber: { type: string, minLength: 1, maxLength: 40 }
+      orderStatus: { type: string, enum: [submitted] }
+      currency: { type: string, pattern: "^[A-Z]{3}$" }
+      totalMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
+      customerName: { type: string, minLength: 1, maxLength: 120 }
+      customerEmail: { type: string, format: email }
+      shippingAddress: { type: string, minLength: 1, maxLength: 500 }
+      items:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          type: object
+          additionalProperties: false
+          required: [productSlug, title, quantity, unitPriceMinor, lineTotalMinor]
+          properties:
+            productSlug: { type: string, pattern: "^[a-z0-9-]+$" }
+            title: { type: string }
+            quantity: { type: integer, minimum: 1, maximum: 99 }
+            unitPriceMinor: { type: integer, minimum: 0 }
+            lineTotalMinor: { type: integer, minimum: 0 }
+  output: { type: object }
+  handler: { kind: builtin, op: create, schema: orders }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: review-order
+spec:
+  title: Review order
+  requires:
+    auth:
+      all:
+        - { "ctx.staff": [owner, editor] }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion, orderStatus]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: number, minimum: 1 }
+      orderStatus: { type: string, enum: [fulfilled, cancelled] }
+      trackingNumber: { type: string, maxLength: 120 }
+      cancelReason: { type: string, maxLength: 500 }
+  output: { type: object }
+  handler: { kind: builtin, op: update, schema: orders }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: place-order-http
+spec:
+  source: { kind: http, method: POST, path: /api/commerce/orders }
+  target: { procedure: place-order }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: place-order-mcp
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: place-order }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: review-order-mcp
+spec:
+  source: { kind: mcp, surface: staff }
+  target: { procedure: review-order }
+```
+
+Points worth noticing:
+
+- `products` is a publishing Schema. Staff draft and publish through Admin or Staff MCP generic lifecycle tools. The public View filters `status: published`.
+- `orders` is operational. `place-order` is builtin `create`; `review-order` is builtin `update` with `id` and `expectedVersion` required. `placedAt` is server-stamped.
+- `orderStatus` on create is narrowed to `submitted`, so this Procedure cannot insert a fulfilled row. Staff `review-order` can only move a row to `fulfilled` or `cancelled`.
+- Line titles, unit prices and `totalMinor` are caller-supplied. This Manifest does not re-price from `products` and does not reserve stock.
+- `review-order` does not set `x-mantle-ref` on `id`. Drive reviews from `submitted-orders` (which exposes `id` and `version`) through Staff MCP or Admin operations. A lone `[orderNumber]` unique index would otherwise make Admin prefill `id` with the order number; see [Procurement approvals](./builtin-procurement.md).
+
+## Worker and handlers
+
+None. Both Procedures are builtin:
+
+```ts
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export default createMantleWorker({ plan });
+```
+
+Sign-in for staff review is the conventional Worker's Auth; see [Authentication](../handbook/cloudflare/authentication.md). The [local Admin OTP host](./host-local-admin-otp/README.md) is the opt-in Dev UI path.
+
+## Try it
+
+Public catalog:
+
+```sh
+curl -sS 'http://localhost:8787/api/views/public-products?show=20'
+```
+
+Place an order (the body is stored as sent; the server does not re-price):
+
+```sh
+curl -sS -X POST http://localhost:8787/api/commerce/orders \
+  -H 'content-type: application/json' \
+  -d '{"orderNumber":"MNT-20260919-1","orderStatus":"submitted","currency":"TWD","totalMinor":2400,"customerName":"Ada","customerEmail":"ada@example.test","shippingAddress":"1 Shell Lane","items":[{"productSlug":"notebook","title":"Notebook","quantity":2,"unitPriceMinor":1200,"lineTotalMinor":2400}]}'
+```
+
+The response is `{ ok: true, data: <EntryRow> }` with `collection: "orders"` and `status: "published"`. A duplicate `orderNumber` is HTTP 409 `CONFLICT`. `orderStatus` other than `submitted` is HTTP 400 `INPUT_VALIDATION_FAILED`.
+
+Staff, on `/mcp/staff`, read `query_view_submitted_orders` then:
+
+```json
+{
+  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+  "params": {
+    "name": "review_order",
+    "arguments": { "id": "ord_01j...", "expectedVersion": 1, "orderStatus": "fulfilled", "trackingNumber": "TEST-1" }
+  }
+}
+```
+
+A second reviewer replaying `expectedVersion: 1` receives `CONFLICT`. A contributor-role session is denied with `AUTH_DENIED`.
+
+| Surface | Tool | Origin |
+|---|---|---|
+| `/mcp` | `query_view_public_products` | public View |
+| `/mcp` | `place_order` | `place-order-mcp` Trigger |
+| `/mcp/staff` | `query_view_submitted_orders` | staff View |
+| `/mcp/staff` | `review_order` | staff MCP Trigger |
+| `/mcp/staff` | `create_draft_products`, `update_draft_products`, `request_publish`, ... | publishing Schema `products` |
+| `/mcp/staff` | `create_record_orders`, `update_record_orders` | operational Schema `orders` |
+
+## What this deliberately leaves out
+
+- **Stock authority.** There is no `inventory` Schema and no Durable Object. Two orders for the last unit both succeed. That story is [Commerce inventory](./cf-primitives-commerce-inventory.md).
+- **Re-pricing.** `totalMinor` and line totals are whatever the caller sent.
+- **Payments.** `submitted` is not `pending_payment`. There is no provider callback and no `pay-order` Procedure.
+- **Queue expiry and cron.** Unpaid reservation release does not apply; there is no reservation.
+- **Picking-list SQL View.** `submitted-orders` is a declared View over `orders`. The `json_each` picking list lives on the cf-primitives page.
+
+Related: [Publication](./builtin-publication.md) for localized product copy; [Procurement approvals](./builtin-procurement.md) for `ctx.user`-owned rows and OCC updates.
+
+## Source
+
+- [Commerce inventory](./cf-primitives-commerce-inventory.md) — DO stock, Queue expiry, payment callback
+- [Schema](../handbook/reference/schema.md), [Procedure](../handbook/reference/procedure.md), and [View](../handbook/reference/view.md) references — publishing vs operational, builtin `create`/`update`
+- [`host-local-admin-otp`](./host-local-admin-otp/README.md) — opt-in Admin host for publishing products

package/docs/examples/builtin-intake.md

@@ -0,0 +1,143 @@
+---
+description: A public intake form that creates operational request rows with a builtin handler. No Turnstile or email ref hooks.
+---
+# Intake form
+
+**Handler class:** builtin · **Builder:** yes · [Examples hub](./README.md). Turnstile verification and staff email are [Intake Turnstile and email hooks](./cf-primitives-intake-hooks.md).
+
+This example collects a public request and lists recent rows for staff. Every Procedure is `handler.kind: builtin`. Read it if you need any form that anonymous visitors submit and you are not wiring bot checks or mailers into the Manifest.
+
+## Problem
+
+Visitors submit a name, an email address and a message. Staff read recent submissions in Admin, over the staff View REST route, or through Staff MCP. Submissions are live records, not authored content, so the Schema is `operational`.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: requests
+spec:
+  title: Requests
+  description: Requests submitted through the public intake flow.
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [name, email, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 2000 }
+      createdAt: { type: number, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: recent-requests
+spec:
+  title: Recent requests
+  surface: staff
+  from: requests
+  fields: [id, name, email, message, createdAt]
+  orderBy:
+    - { field: createdAt, direction: desc }
+  limit: 50
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: submit-request
+spec:
+  title: Submit request
+  description: Create a new public request.
+  input:
+    type: object
+    additionalProperties: false
+    required: [name, email, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 2000 }
+  output: { type: object }
+  handler: { kind: builtin, op: create, schema: requests }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: submit-request-http
+spec:
+  source: { kind: http, method: POST, path: /api/requests }
+  target: { procedure: submit-request }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: submit-request-mcp
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-request }
+```
+
+`createdAt` is stamped by the server (`x-mantle-bind: now`); a caller-supplied value is ignored. The builtin `create` projects `input ∩ Schema.properties`.
+
+## Worker and handlers
+
+None are required. The Manifest above runs on the minimal Worker:
+
+```ts
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export default createMantleWorker({ plan });
+```
+
+## Try it
+
+```sh
+curl -sS -X POST http://localhost:8787/api/requests \
+  -H 'content-type: application/json' \
+  -d '{"name":"Ada","email":"ada@example.test","message":"Please call me back."}'
+```
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "req_01j...",
+    "collection": "requests",
+    "status": "published",
+    "version": 1,
+    "data": { "name": "Ada", "email": "ada@example.test", "message": "Please call me back.", "createdAt": 1788879363492 },
+    "authorId": null,
+    "createdAt": 1788879363492,
+    "updatedAt": 1788879363492
+  }
+}
+```
+
+The builtin `create` returns the `EntryRow`; `status` is `published` immediately because the Schema is operational. A missing `name` is HTTP 400 `INPUT_VALIDATION_FAILED`.
+
+Staff read the queue at `GET /admin/api/views/recent-requests?page=1&show=50` with a staff session; the envelope is `{ ok, data: { rows, page, show, hasMore } }`.
+
+MCP tools:
+
+| Surface | Tool | Origin |
+|---|---|---|
+| `/mcp` | `submit_request` | `submit-request-mcp` Trigger |
+| `/mcp/staff` | `query_view_recent_requests` | `recent-requests` View |
+| `/mcp/staff` | `create_record_requests`, `update_record_requests` | operational Schema `requests` |
+
+## What this deliberately leaves out
+
+- **Bot check and notification.** Those are `ref` lifecycle hooks in [Intake Turnstile and email hooks](./cf-primitives-intake-hooks.md). They are not in this Manifest; Builder must not ingest that page.
+- **Deduplication.** Two identical submissions create two rows.
+- **Rate limiting.** The adapter applies its own request limits to Auth and Admin routes, not a per-form quota.
+
+Related: [Reservation requests](./builtin-reservation.md) uses the same builtin-create shape; [Procurement approvals](./builtin-procurement.md) adds member and staff roles.
+
+## Source
+
+- [Procedure reference](../handbook/reference/procedure.md) — builtin `create`
+- [Intake Turnstile and email hooks](./cf-primitives-intake-hooks.md) — Turnstile and email `ref` hooks on the same Schema

package/docs/examples/builtin-legal-documents.md

@@ -0,0 +1,189 @@
+---
+description: Localized Terms and Privacy documents with immutable revisions, public lookup and signed-in acceptance records.
+---
+# Legal documents and consent
+
+**Handler class:** builtin · **Builder:** yes · [Examples hub](./README.md).
+
+This example gives an application a portable shape for Terms of Use, Privacy Policy and consent receipts. The published Manifest uses only `handler.kind: builtin`. Core does not install it or own the public pages. A live “must be a published revision” check is a `ref` guard; see [Guarded API access](./cf-primitives-guarded-api.md).
+
+Each `(kind, revision, locale)` row is one legal artifact. Immutability here is not a legal-specific Runtime: it is the generic-surface `schema.readOnly: true` pattern (Admin and Staff MCP suppress generic create, update, status and delete), the unique `(kind, revision, locale)` index, and a Procedure-only write path. Host code that calls `updateDraft` (or other mutation use cases) directly can still rewrite a row — do not expose those host mutation APIs for this collection. The English Procedure description is also the MCP and WebMCP authoring instruction.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: legal-documents
+spec:
+  title:
+    en: Legal documents
+    zh-TW: 法律文件
+  description:
+    en: Supply the site's complete, reviewed legal text. Never create empty, placeholder, or agent-invented terms. Create a new revision instead of rewriting a published document accepted by users.
+    zh-TW: 請填入網站已審閱的完整法律正文。不得建立空白、佔位或由 agent 虛構的條款；已有使用者同意的已發佈文件應建立新修訂，不得覆寫。
+  localized: true
+  lifecycle: publishing
+  uniqueIndexes:
+    - [kind, revision, locale]
+  indexes:
+    - [kind, locale, effectiveAt]
+  searchableFields: [title, revision]
+  schema:
+    type: object
+    readOnly: true
+    additionalProperties: false
+    required: [kind, revision, locale, title, body, effectiveAt]
+    properties:
+      kind: { type: string, enum: [terms, privacy] }
+      revision: { type: string, minLength: 1, maxLength: 100 }
+      locale: { type: string }
+      title: { type: string, minLength: 1, maxLength: 200 }
+      body:
+        type: string
+        minLength: 1
+        x-mcp-hint: markdown
+        description:
+          en: Complete reviewed legal text in Markdown; placeholders are not acceptable.
+          zh-TW: 已審閱的完整 Markdown 法律正文，不得使用佔位文字。
+      effectiveAt: { type: integer, minimum: 0, x-mcp-hint: timestamp-ms }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: current-legal-document
+spec:
+  title:
+    en: Current legal document
+    zh-TW: 現行法律文件
+  surface: public
+  from: legal-documents
+  params:
+    type: object
+    additionalProperties: false
+    required: [kind, locale]
+    properties:
+      kind: { type: string, enum: [terms, privacy] }
+      locale: { type: string }
+  fields: [id, kind, revision, locale, title, body, effectiveAt, updatedAt]
+  filter:
+    and:
+      - eq: { field: status, value: published }
+      - eq: { field: kind, value: { $param: kind } }
+      - eq: { field: locale, value: { $param: locale } }
+  orderBy:
+    - { field: effectiveAt, direction: desc }
+  limit: 1
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: create-legal-document
+spec:
+  title:
+    en: Create legal document revision
+    zh-TW: 建立法律文件修訂
+  description:
+    en: Supply the site's complete, reviewed legal text. Never create empty, placeholder, or agent-invented terms. Create a new revision instead of rewriting a published document accepted by users.
+    zh-TW: 請填入網站已審閱的完整法律正文。不得建立空白、佔位或由 agent 虛構的條款；已有使用者同意的已發佈文件應建立新修訂，不得覆寫。
+  input:
+    type: object
+    additionalProperties: false
+    required: [kind, revision, locale, title, body, effectiveAt]
+    properties:
+      kind: { type: string, enum: [terms, privacy] }
+      revision: { type: string, minLength: 1, maxLength: 100 }
+      locale: { type: string }
+      title: { type: string, minLength: 1, maxLength: 200 }
+      body:
+        type: string
+        minLength: 1
+        x-mcp-hint: markdown
+        description:
+          en: Complete reviewed legal text in Markdown; placeholders are not acceptable.
+          zh-TW: 已審閱的完整 Markdown 法律正文，不得使用佔位文字。
+      effectiveAt: { type: integer, minimum: 0, x-mcp-hint: timestamp-ms }
+  output: { type: object }
+  handler: { kind: builtin, op: create, schema: legal-documents }
+  requires:
+    auth:
+      all:
+        - ctx.user
+        - { ctx.staff: [owner, editor] }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: create-legal-document-staff
+spec:
+  source: { kind: mcp, surface: staff }
+  target: { procedure: create-legal-document }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: legal-acceptances
+spec:
+  title:
+    en: Legal acceptances
+    zh-TW: 法律文件同意紀錄
+  description:
+    en: Append-only receipts bound by the server to the signed-in user and acceptance time.
+    zh-TW: 由伺服器綁定登入使用者與同意時間的唯增紀錄。
+  lifecycle: operational
+  uniqueIndexes:
+    - [documentId, userId]
+  indexes:
+    - [userId, acceptedAt]
+  schema:
+    type: object
+    readOnly: true
+    additionalProperties: false
+    required: [documentId, userId, acceptedAt]
+    properties:
+      documentId: { type: string, format: uuid, x-mantle-ref: legal-documents }
+      userId: { type: string, x-mantle-bind: ctx.user }
+      acceptedAt: { type: integer, x-mantle-bind: now, x-mcp-hint: timestamp-ms }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: accept-legal-document
+spec:
+  title:
+    en: Accept legal document
+    zh-TW: 同意法律文件
+  description:
+    en: Record the signed-in user's acceptance of one legal document revision.
+    zh-TW: 記錄登入使用者對一份法律文件修訂的同意。
+  input:
+    type: object
+    additionalProperties: false
+    required: [documentId]
+    properties:
+      documentId: { type: string, format: uuid, x-mantle-ref: legal-documents }
+  output: { type: object }
+  handler: { kind: builtin, op: create, schema: legal-acceptances }
+  requires:
+    auth: { all: [ctx.user] }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: accept-legal-document-http
+spec:
+  source: { kind: http, method: POST, path: /api/legal/acceptances }
+  target: { procedure: accept-legal-document }
+```
+
+The HTTP endpoint records only `documentId`; `userId` and `acceptedAt` are server-bound and cannot be supplied by the caller. This Manifest does not include a live “row is published” guard. Add that as a `ref` Procedure on `requires.guard` when the application owns the lookup; the contract is [Guarded API access](./cf-primitives-guarded-api.md).
+
+Serve `/terms` and `/privacy` in application code by querying `current-legal-document` with the requested locale, falling back to the site's default locale, and rendering Markdown as escaped/sanitized HTML. Return a clear unavailable page when no reviewed document is published. The application also owns the checkbox or other consent UI, authentication, retention and export policy.
+
+Staff MCP and Admin WebMCP expose `create_legal_document` from the explicit staff Trigger. Both use the same Procedure description, so agents are told to collect real reviewed text rather than inventing it. Root `readOnly` deliberately emits no generic update tool on Admin or Staff MCP; that is a generic-surface gate, not a storage lock. Do not add an MCP Trigger for `accept-legal-document`: accepting legal terms is an explicit user-interface action.
+
+## Source
+
+- [Publication](./builtin-publication.md) — localized publishing pattern
+- [Authorization](../handbook/reference/authorization.md) — server-bound identity
+- [Guarded API access](./cf-primitives-guarded-api.md) — optional live published-document `ref` guard
+- [MCP and agents](../handbook/concepts/mcp-and-agents.md) — manifest-derived tool contracts