@aotter/mantle 0.1.2-alpha.6 → 0.1.2

package/docs/handbook/examples/procurement-approvals.md

@@ -1,240 +1,10 @@
 ---
-description: Members submit purchase requisitions they can only see themselves; staff review them with optimistic concurrency.
+description: Redirects to the builtin procurement example in the Examples hub.
 ---
 # Procurement approvals with member and staff roles
 
-This example separates two audiences: signed-in members who submit and track their own requisitions, and staff who approve or reject them. It is the Builder `procurement` preset converted to YAML and is fully declarative. Read it if you need per-user rows and a staff decision step.
-
-## Problem
-
-A signed-in member submits a purchase requisition: a request number, an item, a quantity, a need-by date and a justification. The member sees only their own requisitions and their current status. Staff with the `owner` or `editor` role see the queue of `submitted` requisitions ordered by need-by date and mark each `approved` or `rejected` with a note. Two reviewers must not silently overwrite each other's decision. Requisitions are live operational records.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: purchase-requisitions
-spec:
-  title: Purchase requisitions
-  description: Member-submitted purchase needs waiting for staff review.
-  lifecycle: operational
-  uniqueIndexes:
-    - [requestNumber]
-  indexes:
-    - [requestedBy, requestedAt]
-    - [requestStatus, needBy]
-  schema:
-    type: object
-    additionalProperties: false
-    required: [requestNumber, requestedBy, item, quantity, needBy, justification, requestStatus, requestedAt]
-    properties:
-      requestNumber: { type: string, pattern: "^REQ-[A-Z0-9-]+$" }
-      requestedBy: { type: string, x-mantle-bind: ctx.user }
-      item: { type: string, minLength: 1, maxLength: 160 }
-      quantity: { type: integer, minimum: 1 }
-      needBy: { type: number, x-mcp-hint: timestamp-ms }
-      justification: { type: string, minLength: 1, maxLength: 1000 }
-      requestStatus: { type: string, enum: [submitted, approved, rejected] }
-      reviewerNote: { type: string, maxLength: 1000 }
-      requestedAt: { type: number, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: my-requisitions
-spec:
-  title: My requisitions
-  surface: public
-  from: purchase-requisitions
-  requires:
-    auth:
-      all: [ctx.user]
-  fields: [id, requestNumber, item, quantity, needBy, justification, requestStatus, reviewerNote, requestedAt]
-  filter:
-    eq: { field: requestedBy, value: { "$ctx.user": id } }
-  orderBy:
-    - { field: requestedAt, direction: desc }
-  limit: 100
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: pending-approvals
-spec:
-  title: Pending approvals
-  surface: staff
-  from: purchase-requisitions
-  requires:
-    auth:
-      all:
-        - { "ctx.staff": [owner, editor] }
-  fields: [id, version, requestNumber, requestedBy, item, quantity, needBy, justification, requestedAt]
-  filter:
-    eq: { field: requestStatus, value: submitted }
-  orderBy:
-    - { field: needBy, direction: asc }
-  limit: 100
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: submit-requisition
-spec:
-  title: Submit requisition
-  requires:
-    auth:
-      all: [ctx.user]
-  input:
-    type: object
-    additionalProperties: false
-    required: [requestNumber, item, quantity, needBy, justification, requestStatus]
-    properties:
-      requestNumber: { type: string, pattern: "^REQ-[A-Z0-9-]+$" }
-      item: { type: string, minLength: 1, maxLength: 160 }
-      quantity: { type: integer, minimum: 1 }
-      needBy: { type: number, x-mcp-hint: timestamp-ms }
-      justification: { type: string, minLength: 1, maxLength: 1000 }
-      requestStatus: { type: string, enum: [submitted] }
-  output: { type: object }
-  handler: { kind: builtin, op: create, schema: purchase-requisitions }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: review-requisition
-spec:
-  title: Review requisition
-  requires:
-    auth:
-      all:
-        - { "ctx.staff": [owner, editor] }
-  input:
-    type: object
-    additionalProperties: false
-    required: [id, expectedVersion, requestStatus]
-    properties:
-      id: { type: string, x-mantle-ref: purchase-requisitions }
-      expectedVersion: { type: number, minimum: 1 }
-      requestStatus: { type: string, enum: [approved, rejected] }
-      reviewerNote: { type: string, maxLength: 1000 }
-  output: { type: object }
-  handler: { kind: builtin, op: update, schema: purchase-requisitions }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: submit-requisition-http
-spec:
-  source: { kind: http, method: POST, path: /api/requisitions }
-  target: { procedure: submit-requisition }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: submit-requisition-mcp
-spec:
-  source: { kind: mcp, surface: public }
-  target: { procedure: submit-requisition }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: review-requisition-mcp
-spec:
-  source: { kind: mcp, surface: staff }
-  target: { procedure: review-requisition }
-```
-
-### Ownership without trusting the caller
-
-`requestedBy` carries `x-mantle-bind: ctx.user`. On create the server stamps the signed-in user's id and ignores any caller value; on update the stamp is preserved. `requestedAt` is stamped the same way with `now`. Because both are in `required`, and because `submit-requisition` requires `ctx.user`, an anonymous caller is rejected with `UNAUTHENTICATED` before the row is even projected.
-
-`my-requisitions` filters with the closed sentinel `{ "$ctx.user": id }`. The caller never supplies this value, so the same View is safe over REST and public MCP. Three rules make the sentinel legal, and the parser enforces each:
-
-| Rule | Diagnostic when violated |
-|---|---|
-| The View's `requires.auth.all` includes `ctx.user` | `VIEW_FILTER_CTX_USER_REF_REQUIRES_AUTH` |
-| The sentinel appears only under `eq`, as a single-key object whose value is the literal `id` | `VIEW_FILTER_CTX_USER_REF_INVALID` |
-| The filtered field is the leftmost field of a declared index (`[requestedBy, requestedAt]` here) | `VIEW_FILTER_CTX_USER_REF_REQUIRES_INDEX` |
-
-A missing identity fails with 401; the runtime never drops the filter and never falls back to all rows.
-
-`pending-approvals` uses the staff predicate `{ "ctx.staff": [owner, editor] }`. It includes `version` in `fields` so a reviewer can pass it back as `expectedVersion`.
-
-### Optimistic concurrency
-
-`review-requisition` is a builtin `update`. Its input must declare `id` (string) and `expectedVersion` (number) in `required`; the parser rejects the Manifest otherwise. `expectedVersion` is the version the reviewer **read**, not that value plus one. At runtime the row is loaded, the patch is merged over existing data (omitted fields and server stamps survive), and the write is applied only if the stored version equals `expectedVersion`. A stale version fails with `CONFLICT` (HTTP 409) and nothing changes; the reviewer re-reads and decides again. Admin binds and hides `expectedVersion` on row-bound forms. `requestStatus` is narrowed to `approved | rejected`, so this Procedure cannot move a row back to `submitted`.
-
-### Admin row action
-
-`id` carries `x-mantle-ref: purchase-requisitions`, so Admin lists `review-requisition` in the ⋯ menu of each `purchase-requisitions` row and prefills the referenced field. Admin derives the prefilled value from a same-named Schema property first, then from the Schema's lone single-field unique index, and finally from the entry id.
-
-> **Warning**
-> This Schema declares exactly one single-field unique index, `[requestNumber]`, and no property named `id`, so Admin prefills `id` with the row's `requestNumber`. A builtin `update` expects the entry id there and would answer `NOT_FOUND`. Until that binding is adjusted, drive reviews from the `pending-approvals` View (which exposes `id` and `version`) through Staff MCP or `POST /admin/api/operations/review-requisition`. Declaring a second `uniqueIndexes` tuple or no unique index changes the derivation to the entry id, at the cost of that uniqueness guarantee.
-
-See [Authorization](../concepts/authorization.md) and the [Procedure reference](../reference/procedure.md).
-
-## Worker and handlers
-
-None. Both Procedures are builtin and the Worker is `export default createMantleWorker({ plan })`. Sign-in is provided by the conventional Worker's Auth; see [Authentication](../cloudflare/authentication.md).
-
-## Try it
-
-Anonymous read of the member View:
-
-```sh
-curl -i http://localhost:8787/api/views/my-requisitions
-```
-
-```txt
-HTTP/1.1 401 Unauthorized
-{"ok":false,"diagnostic":{"code":"UNAUTHENTICATED","phase":"runtime","severity":"error","path":"...#/requires/auth/all/0", ...}}
-```
-
-Signed in (session cookie), the same request returns only rows whose `requestedBy` equals the caller's id:
-
-```sh
-curl -sS http://localhost:8787/api/views/my-requisitions \
-  -H "cookie: $SESSION_COOKIE"
-# {"ok":true,"data":{"rows":[{"id":"pr_01j...","requestNumber":"REQ-2026-0001","item":"Standing desk","quantity":1,"needBy":1791475200000,"justification":"...","requestStatus":"submitted","requestedAt":1788879363492}],"page":1,"show":100,"hasMore":false}}
-```
-
-Submit as a member (mutations authenticated by a session cookie also pass a same-origin check):
-
-```sh
-curl -sS -X POST http://localhost:8787/api/requisitions \
-  -H 'content-type: application/json' -H "cookie: $SESSION_COOKIE" \
-  -d '{"requestNumber":"REQ-2026-0002","item":"Monitor arm","quantity":2,"needBy":1791475200000,"justification":"Second screen for review work.","requestStatus":"submitted"}'
-```
-
-The response is `{ ok: true, data: <EntryRow> }`; `data.requestedBy` is the caller's id even if the body tried to set it. A duplicate `requestNumber` is HTTP 409 `CONFLICT`.
-
-Staff review through Staff MCP on `/mcp/staff`. First `query_view_pending_approvals` returns `id` and `version`; then:
-
-```json
-{
-  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
-  "params": {
-    "name": "review_requisition",
-    "arguments": { "id": "pr_01j...", "expectedVersion": 1, "requestStatus": "approved", "reviewerNote": "Within budget." }
-  }
-}
-```
-
-A second reviewer replaying `expectedVersion: 1` after that succeeds receives a JSON-RPC error whose `error.data.code` is `CONFLICT`. A contributor-role session is denied with `AUTH_DENIED`. `review_requisition` appears only in `tools/list` on `/mcp/staff`; the public surface lists `submit_requisition` and `query_view_my_requisitions`.
-
-## What this deliberately leaves out
-
-- **Multi-step approval chains.** One decision by one staff member. Sequential approvers would add a step field, more enum states and a `before_update` hook that validates the transition.
-- **Budgets.** No cost field and no per-department limit; add a `ref` guard Procedure when a live check is needed.
-- **Notifications.** Neither the submitter nor the reviewer is emailed. The [intake form](./intake-form.md) shows the `after_create` pattern.
-
-Related: [Guarded API access](./guarded-api.md) covers credentials and scopes for non-browser callers.
+This example lives in the Examples hub: [`docs/examples/builtin-procurement.md`](../../examples/builtin-procurement.md).
 
 ## Source
 
-- [Procedure reference](../reference/procedure.md) — `x-mantle-bind`, `x-mantle-ref`, builtin `update` contract, RBAC
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts) — `discoverRowBindings` and `rowField` derivation
-- [`packages/mantle-runtime/src/domain/service/AuthPredicateEvaluator.ts`](../../../packages/mantle-runtime/src/domain/service/AuthPredicateEvaluator.ts) — `UNAUTHENTICATED` versus `AUTH_DENIED`
+- [`docs/examples/builtin-procurement.md`](../../examples/builtin-procurement.md)

package/docs/handbook/examples/publication.md

@@ -1,240 +1,10 @@
 ---
-description: Localized blog posts with a stable parent identity, a public per-locale list and an optional reader suggestion box.
+description: Redirects to the builtin publication example in the Examples hub.
 ---
 # Publication: localized posts with a public list
 
-This example publishes posts in several languages, serves a public list per locale, and accepts reader suggestions. It is fully declarative: no handler code is needed. Read it if you run a blog, a news section or any authored, translated content.
-
-## Problem
-
-Editors draft posts in one or more locales, review them in Admin, and publish each language version independently. Every language version of a post shares one stable identity (its slug) so the site can link translations together and Admin can show translation completeness. Visitors read a per-locale list of published posts, newest first, over REST and public MCP. Readers may suggest topics; those suggestions are live records staff read in Admin, not content that is published.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: posts
-spec:
-  title: Posts
-  description: Stable post identities shared by every language version.
-  localized: false
-  lifecycle: publishing
-  uniqueIndexes:
-    - [slug]
-  schema:
-    type: object
-    required: [slug]
-    properties:
-      slug: { type: string, pattern: "^[a-z0-9-]+$" }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: post-translations
-spec:
-  title: Post translations
-  description: Localized titles and bodies for each post.
-  localized: true
-  translates:
-    parent: posts
-    on: slug
-  lifecycle: publishing
-  uniqueIndexes:
-    - [slug, locale]
-  indexes:
-    - [locale, publishedAt]
-  schema:
-    type: object
-    required: [slug, locale, title, publishedAt]
-    properties:
-      slug: { type: string, pattern: "^[a-z0-9-]+$" }
-      locale: { type: string }
-      title: { type: string }
-      excerpt: { type: string }
-      body: { type: string, x-mcp-hint: markdown }
-      publishedAt: { type: number, x-mcp-hint: timestamp-ms }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: published-posts
-spec:
-  title: Published posts
-  surface: public
-  from: post-translations
-  params:
-    type: object
-    additionalProperties: false
-    required: [locale]
-    properties:
-      locale: { type: string }
-  fields: [id, slug, locale, title, excerpt, body, publishedAt, updatedAt]
-  filter:
-    and:
-      - eq: { field: status, value: published }
-      - eq: { field: locale, value: { $param: locale } }
-      - gte: { field: publishedAt, value: 0 }
-  orderBy:
-    - { field: publishedAt, direction: desc }
-  limit: 50
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: post-suggestions
-spec:
-  title: Post suggestions
-  description: Reader suggestions for future posts.
-  lifecycle: operational
-  schema:
-    type: object
-    required: [title, email]
-    properties:
-      title: { type: string }
-      email: { type: string, format: email }
-      note: { type: string }
-      createdAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: submit-post-suggestion
-spec:
-  input:
-    type: object
-    additionalProperties: false
-    required: [title, email]
-    properties:
-      title: { type: string }
-      email: { type: string, format: email }
-      note: { type: string }
-  output: { type: object }
-  handler: { kind: builtin, op: create, schema: post-suggestions }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: submit-post-suggestion-http
-spec:
-  source: { kind: http, method: POST, path: /api/post-suggestions }
-  target: { procedure: submit-post-suggestion }
-```
-
-How the pieces fit:
-
-- `posts` is the non-localized parent. It holds only what every language shares; here that is the slug.
-- `post-translations` is the localized child. `translates: { parent: posts, on: slug }` requires `localized: true`, at least one content field besides `slug` and `locale`, and a parent that exists and is not itself localized. Admin renders the child as locale tabs inside the parent's editor.
-- `published-posts` takes a required `locale` parameter. `{ $param: locale }` must name a property in `params.properties` that is also in `params.required`. The `gte publishedAt 0` clause keeps the filter aligned with the declared `[locale, publishedAt]` index; confirm the plan with `mantle-harness indexes`.
-- Site locales must be configured. A localized Schema with zero `siteDefaults.locales` fails at boot with `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES`, and a write whose `locale` is not in the site list fails with `INPUT_VALIDATION_FAILED`.
-
-See [Lifecycle and locales](../concepts/lifecycle-and-locales.md) and the [Schema reference](../reference/schema.md).
-
-## Worker and handlers
-
-There are none. Every Procedure here is `builtin`, and Views need no Trigger. The Worker is the minimal one:
-
-```ts
-import { createMantleWorker } from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-
-export default createMantleWorker({ plan });
-```
-
-### Rendering
-
-Public HTML pages are optional and separate from the data contract. If you want `/en/posts/<slug>` rendered by the Worker, register a template for the translations collection and pass it to `createMantleWorker({ templates, publicPathResolver })`. A trimmed entry template:
-
-```ts
-import { TemplateRegistry } from "@aotter/mantle/web";
-import MarkdownIt from "markdown-it";
-
-const markdown = new MarkdownIt({ html: false, linkify: true });
-
-export function createTemplates(): TemplateRegistry {
-  const templates = new TemplateRegistry();
-  templates.registerEntryTemplate("post-translations", ({ entry, site, seo }) => {
-    const title = typeof entry.data.title === "string" ? entry.data.title : site.title;
-    const body = typeof entry.data.body === "string" ? entry.data.body : "";
-    return `<html lang="${entry.locale ?? "en"}"><head><title>${escapeHtml(title)}</title></head>
-<body><main><h1>${escapeHtml(title)}</h1><div>${markdown.render(body)}</div></main></body></html>`;
-  });
-  return templates;
-}
-```
-
-The template receives `{ entry, site, seo, mediaAssets }` and returns a complete HTML string. Escape every field you interpolate; `body` is rendered from Markdown because the Schema marks it `x-mcp-hint: markdown`. Paths, Markdown mirrors, `llms.txt`, sitemap and cache headers are covered in [Public web, SEO and cache](../cloudflare/public-web.md).
-
-### The single-Schema alternative
-
-The simpler alternative is one localized `posts` Schema with `uniqueIndexes: [[slug, locale]]` and no parent. Each locale row is an independent record; nothing is shared except the slug convention. Choose that shape when translations do not need shared fields or Admin translation grouping. Choose the parent/child shape above when several locale rows are versions of one entity and editors need to see which languages are missing. Both shapes serve the same `published-posts` View contract.
-
-## Try it
-
-Public list for one locale:
-
-```sh
-curl -sS 'http://localhost:8787/api/views/published-posts?locale=en&show=10'
-```
-
-```json
-{
-  "ok": true,
-  "data": {
-    "rows": [
-      {
-        "id": "tr_01j...",
-        "slug": "hello-world",
-        "locale": "en",
-        "title": "Hello, world",
-        "excerpt": "First post.",
-        "body": "# Hello\n\nFirst post.",
-        "publishedAt": 1788879363492,
-        "updatedAt": 1788879400000
-      }
-    ],
-    "page": 1,
-    "show": 10,
-    "hasMore": false
-  }
-}
-```
-
-Omitting `locale` returns HTTP 400 `INPUT_VALIDATION_FAILED`. `show` is capped at the View's `limit` (50); `hasMore` is `rows.length === show`. A View may declare `cache.sharedMaxAge` to cache eligible anonymous REST responses under the Worker's deployment-scoped tag; publishing content changes purge that tag.
-
-Submit a suggestion:
-
-```sh
-curl -sS -X POST http://localhost:8787/api/post-suggestions \
-  -H 'content-type: application/json' \
-  -d '{"title":"Write about indexes","email":"reader@example.test"}'
-```
-
-The response is `{ ok: true, data: <EntryRow> }` with `collection: "post-suggestions"` and `status: "published"`.
-
-MCP tools:
-
-| Surface | Tool | Origin |
-|---|---|---|
-| `/mcp` | `query_view_published_posts` (arguments `locale`, `page`, `show`) | public View |
-| `/mcp/staff` | `create_draft_posts`, `update_draft_posts` | publishing Schema `posts` |
-| `/mcp/staff` | `create_draft_post_translations`, `update_draft_post_translations` | publishing Schema `post-translations` |
-| `/mcp/staff` | `create_record_post_suggestions`, `update_record_post_suggestions` | operational Schema `post-suggestions` |
-| `/mcp/staff` | `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry` | generic lifecycle tools |
-
-There is no `submit_post_suggestion` tool because no MCP Trigger targets that Procedure. See [MCP and agents](../concepts/mcp-and-agents.md).
-
-## What this deliberately leaves out
-
-- **Comments.** Reader comments would be another operational Schema with its own moderation Procedures.
-- **Search.** `searchableFields` powers Admin and Staff MCP substring search only; public full-text search is application code.
-- **Scheduling.** `publishedAt` is a display timestamp set by editors. Nothing publishes a draft at that time; publishing remains an explicit `request_publish` or Admin action.
-
-Related: [Intake form](./intake-form.md) hardens the suggestion box with a bot check.
+This example lives in the Examples hub: [`docs/examples/builtin-publication.md`](../../examples/builtin-publication.md).
 
 ## Source
 
-- [Schema reference](../reference/schema.md) and [View reference](../reference/view.md) — `localized`, `translates`, param-driven Views
-- [`packages/mantle-web/src/model/TemplateRegistry.ts`](../../../packages/mantle-web/src/model/TemplateRegistry.ts) — `registerEntryTemplate` and `EntryContext`
-- [`overlays/publication/manifests/site.yaml`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/publication/manifests/site.yaml) — retired parent/child publication pattern
+- [`docs/examples/builtin-publication.md`](../../examples/builtin-publication.md)