@aotter/mantle 0.1.3-alpha.6 → 0.1.4

package/docs/handbook/cloudflare/chatgpt-sites.md

@@ -4,26 +4,26 @@ description: "Mantle on ChatGPT Sites now has its own integration guide."
 # Mantle on ChatGPT Sites
 
 ChatGPT Sites has a dedicated section in the Mantle handbook. Start with
-[Mantle on ChatGPT Sites](../sites/index.md) for installation, supported
+[Mantle on ChatGPT Sites](../chatgpt-sites/index.md) for installation, supported
 capabilities, and your first published article. This page preserves earlier
 links to the host checklist.
 
 ## First deployment
 
-See [the host deployment checklist](../sites/host-reference.md#first-deployment).
+See [the host deployment checklist](../chatgpt-sites/host-reference.md#first-deployment).
 
 ## Media with only an R2 binding
 
-See [R2 media integration](../sites/host-reference.md#media-with-only-an-r2-binding).
+See [R2 media integration](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
 
 ## Remote MCP is a separate gate
 
-See [MCP support and authentication](../sites/host-reference.md#remote-mcp-is-a-separate-gate).
+See [MCP support and authentication](../chatgpt-sites/host-reference.md#remote-mcp-is-a-separate-gate).
 
 ## Capability boundaries
 
-See [host capability boundaries](../sites/host-reference.md#capability-boundaries).
+See [host capability boundaries](../chatgpt-sites/host-reference.md#capability-boundaries).
 
 ## Source
 
-See [integration sources](../sites/host-reference.md#source).
+See [integration sources](../chatgpt-sites/host-reference.md#source).

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -47,7 +47,8 @@ wrangler deploy
 
 ## Post-deploy verification
 
-Probe the deployed origin, not `wrangler dev`:
+Probe the deployed origin, not `wrangler dev`. Run only the probes for surfaces
+the application mounts and configures:
 
 | Probe | Expect |
 |---|---|
@@ -55,7 +56,7 @@ Probe the deployed origin, not `wrangler dev`:
 | `GET /<locale>/<segment>/<slug>` and `GET /<locale>/<segment>/<slug>.md` | `200` HTML and Markdown for a published entry |
 | `GET /llms.txt`, `GET /sitemap.xml`, `GET /robots.txt` | `200` |
 | `GET /<locale>/<segment>/does-not-exist` | `404` from your `notFoundRenderer` |
-| `GET /mcp` without credentials | `401` with `WWW-Authenticate` |
+| `POST /mcp/staff` without credentials | `401` with `WWW-Authenticate`; `GET /mcp` is `405` |
 | `GET /admin` | Sign-in page; sign in with the `ADMIN_GITHUB_LOGIN` account |
 
 Then check the cache: a second anonymous `GET` of a public page should show `cf-cache-status: HIT`; publish a change in Admin and the next request should be a `MISS`. Sample latency with:

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

@@ -3,7 +3,7 @@ description: Enable staff media uploads on R2 — presigned PUT flow through Sta
 ---
 # 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 native Cloudflare direct-to-R2 flow, the configuration it needs, how a Schema references an asset, what a commit costs, and how to clean up. For ChatGPT Sites with an R2 binding but no S3 credentials, use [the same-origin Worker flow](../sites/host-reference.md#media-with-only-an-r2-binding).
+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 native Cloudflare direct-to-R2 flow, the configuration it needs, how a Schema references an asset, what a commit costs, and how to clean up. For ChatGPT Sites with an R2 binding but no S3 credentials, use [the same-origin Worker flow](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
 
 ## When to enable it
 
@@ -213,4 +213,4 @@ The full catalog is in [Diagnostic codes](../reference/diagnostics.md).
 - [`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)
+- [`docs/skills/media-gc/SKILL.md`](../../skills/media-gc/SKILL.md)

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

@@ -170,4 +170,4 @@ Postgres exposes roughly twenty-five object kinds; an application developer writ
 - [`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)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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

@@ -139,4 +139,4 @@ The full worked version of this pattern, with a locale-parameterized public View
 - [`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)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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

@@ -20,7 +20,7 @@ A tool name is derived from a manifest name by `mcpToolNameSegment`: lowercased,
 
 | Tool | Produced by | Surface |
 |---|---|---|
-| `query_view_<segment>` | Any View | The View's own `surface` |
+| `query_view_<segment>` | Public or staff View (never internal) | 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 |
@@ -68,6 +68,25 @@ Only `status: published` entries appear anywhere in that set. Details are in [Pu
 
 ## WebMCP in the browser
 
+### Admin: tools for the signed-in staff member
+
+Admin UI registers staff tools in browsers supporting `document.modelContext`.
+The catalog comes from `GET /admin/api/webmcp`; calls use
+`POST /admin/api/mcp` with the current staff session. Server-side role checks,
+Procedure authorization, and optimistic concurrency remain in force.
+`admin_get_context` and `admin_navigate` add page context and navigation.
+The WebMCP control appears after registration succeeds; unsupported browsers
+can continue using the regular Admin UI.
+
+Owners can explore application API documentation in Developer UI:
+`/admin/dev/docs/api` for HTTP, `/admin/dev/docs/mcp` for remote MCP, and
+`/admin/dev/docs/webmcp` for the Admin catalog and public-page capabilities.
+These pages show projected definitions. Remote clients connect to the host's
+advertised MCP endpoints using the authentication described above.
+See the [Admin API guide](../../../packages/mantle-admin/README.md#admin-webmcp).
+
+### Public pages: opt-in registration
+
 `@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
@@ -78,7 +97,7 @@ const binding = await bindWebMcp();
 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).
+It feature-detects `document.modelContext` and returns `{ supported: false }` on browsers without it. This public-page binding registers only public capabilities. Staff tools use the separate authenticated Admin integration above. 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
 
@@ -91,11 +110,12 @@ 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.
 
-The same bundle is installable from the plugin marketplace:
+The bootstrap `mantle` skill is also available from the plugin marketplace.
+The ongoing workflows come from the installed SDK through `mantle skills`:
 
 ```sh
 # Canonical
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 
 # Claude Code — two separate prompts
 /plugin marketplace add aotter/mantle
@@ -111,4 +131,4 @@ Never point a versioned project at a mutable branch. See [Project layout and the
 - [`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)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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

@@ -218,4 +218,4 @@ Register the two `ref` keys in the project's handlers map, then run the check lo
 - [`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)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -51,7 +51,7 @@ const bound = bindMantle(runtime);
 await bound.runtime.archive.execute({ id, ctx });
 ```
 
-Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally, and a collision is an error (`CODEGEN_IDENTIFIER_COLLISION`). Code generation is a pure projection: it never caches, retries, mounts routes or owns host lifecycle, and the typed API keeps its raw `runtime` so it hides nothing. Skipping generation is valid — call `runtime.executeView({ view: "published-notes" })` by name.
+Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally, and a collision is an error (`CODEGEN_IDENTIFIER_COLLISION`). The emitter accepts either `emitMantleModule({ linked })` or `emitMantleModule({ plan })` for hosts that already compiled the plan; see [Typed queries](../guides/typed-queries.md). Code generation is a pure projection: it never caches, retries, mounts routes or owns host lifecycle, and the typed API keeps its raw `runtime` so it hides nothing. Skipping generation is valid — call `runtime.executeView({ view: "published-notes" })` by name.
 
 ## Core, optional products, adapters
 
@@ -174,4 +174,4 @@ If a normal feature cannot be expressed through a purpose-shaped surface, treat
 - [`packages/adapters/bun/README.md`](../../../packages/adapters/bun/README.md)
 - [`packages/adapters/vercel/README.md`](../../../packages/adapters/vercel/README.md)
 - [`packages/adapters/indexeddb/README.md`](../../../packages/adapters/indexeddb/README.md)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/views.md

@@ -3,24 +3,25 @@ description: Views are the only public read surface — surfaces, declarative ve
 ---
 # Reads: Views, REST and MCP
 
-Every read that leaves the runtime goes through a View. This page explains why, how a View is shaped, and what it costs at query time. Field-level rules are in the [View reference](../reference/view.md).
+Views declare reusable queries and their transport visibility. This page explains why, how a View is shaped, and what it costs at query time. Field-level rules are in the [View reference](../reference/view.md).
 
 ## One read surface, not two
 
-A View is a named, read-only query over Schemas. Declaring one is enough: it mounts on its surface with no [Trigger](./procedures-and-triggers.md) involved. Schemas are never publicly readable on their own.
+A View is a named, read-only query over Schemas. Public and staff Views mount on supported transports with no [Trigger](./procedures-and-triggers.md) involved. Schemas are never publicly readable on their own.
 
 Exposing collections directly — a `Schema.spec.expose.rest` flag, or a `GET /api/<collection>` shortcut — was considered and rejected. A Schema declares the storage shape. Its entries carry drafts, internal status, server-stamped fields and per-row data the author never intended to publish; `contact-messages` is the canonical example, where a direct collection route would be a privacy bug by default. A View already has the right semantics — a named query with explicit fields, filter, ordering and limit — so auto-exposing it only ratifies what the manifest already says.
 
-There is no internal-only View surface either. A query that should not be externally callable stays a TypeScript helper.
+Use `surface: internal` for a named query callable only by host code. It remains in the plan and generated bindings, but is absent from REST, MCP, WebMCP and Admin reports. Its `requires` and guards still run. See [Typed queries](../guides/typed-queries.md).
 
 ## Surfaces
 
-`spec.surface` is required and closed to two values.
+`spec.surface` is required and closed to three values.
 
 | `surface` | REST | MCP | Extra |
 |---|---|---|---|
 | `public` | `GET /api/views/<name>` | `query_view_<segment>` on `/mcp` | Listed by `GET /api/views` |
 | `staff` | `GET /admin/api/views/<name>` | `query_view_<segment>` on `/mcp/staff` | `GET /admin/api/views/<name>/export`, Admin report sidebar |
+| `internal` | None | None | Host calls through `executeView` or generated `views` bindings |
 
 The adapter filters the View set before building each MCP dispatcher, so a guessed public tool call cannot reach a staff View. Surface decides transport visibility; `spec.requires` decides whether the verified caller may execute the View, on REST and MCP alike. See [Authorization](./authorization.md).
 
@@ -31,7 +32,7 @@ A View declares exactly one of `from` or `sql`; declaring both or neither is rej
 - **`from`** names a Schema and pairs with `fields`, `filter`, `orderBy` and `limit`. The filter is a closed AST: `eq`, `gt`, `gte`, `lt`, `lte`, combined with `and` and `or`. Field-to-field comparison and arithmetic are not expressible.
 - **`sql`** is a single `SELECT` with no semicolon. Every Schema is available as a logical table named after its `metadata.name`, with data properties projected as columns; quote names containing hyphens (`"post-translations"`). Combining `sql` with `fields`, `filter` or `orderBy` is rejected.
 
-**New Views should use one `SELECT`.** The declarative form remains accepted for existing manifests. SQL Views compile to native SQLite; a storage adapter that cannot run them fails at boot with `VIEW_DIALECT_UNSUPPORTED`, and static validation never executes the statement — run it against the selected adapter or through `mantle-harness indexes`.
+Use `from` for portable single-Schema queries, typed result rows and eligible public caching. Use `sql` for joins, aggregation or JSON expansion that the declarative form cannot express. SQL Views require a SQLite-capable adapter (`VIEW_DIALECT_UNSUPPORTED` otherwise), and generated SQL row types are `unknown`. The CLI validates SQL against an empty database of declared Schema tables; programmatic validation needs the `sqlViewSandbox` port for the same check. Exercise data-dependent behavior on your adapter or with `mantle-harness indexes`.
 
 ## Params
 
@@ -88,7 +89,7 @@ These names are output field names — SQL aliases for a `sql` View, Schema prop
 
 ## The MCP mirror
 
-Every View is also a tool. The name is the View name lowercased with hyphens replaced by underscores, prefixed `query_view_`. Its input schema is `params.properties` plus `page` and `show`, and it is annotated `readOnlyHint: true`. One executor and one response shape serve REST and MCP, so an agent and a downstream service read exactly the same rows. See [MCP and agents](./mcp-and-agents.md).
+Every public or staff View is also a tool on its matching MCP surface; internal Views are never tools. The name is the View name lowercased with hyphens replaced by underscores, prefixed `query_view_`. Its input schema is `params.properties` plus `page` and `show`, and it is annotated `readOnlyHint: true`. One executor and one response shape serve REST and MCP, so an agent and a downstream service read exactly the same rows. See [MCP and agents](./mcp-and-agents.md).
 
 ## Performance: declare the index the query needs
 
@@ -97,7 +98,7 @@ a native column. Declared `indexes` and `uniqueIndexes` become B-tree indexes
 over those columns; Core-compiled projections, filters and ordering reference
 the same columns directly.
 
-Declare the **smallest ordered index justified by the measured path**, and respect SQLite's leftmost-prefix rule. Equality columns go first, the ordered column last. A public View over a publishing Schema always carries `status = published`, so its index leads with `status`: `[status, locale, publishedAt]` serves `WHERE status = ? AND locale = ?`, `… AND publishedAt > ?`, and `… ORDER BY publishedAt`. It does not serve `WHERE publishedAt > ?` alone, and `[publishedAt]` alone does not serve the published list — without planner statistics SQLite prefers the status equality and sorts in a temporary B-tree. If a second hot path needs a different leading field, that is a second index — not a reason to enumerate every permutation, since each index costs storage and slows every write.
+Declare the **smallest ordered index justified by the measured path**, and respect SQLite's leftmost-prefix rule. Equality columns go first, the ordered column last. A public declarative View over a publishing Schema always carries `status = published`, so its index leads with `status`: `[status, locale, publishedAt]` serves `WHERE status = ? AND locale = ?`, `… AND publishedAt > ?`, and `… ORDER BY publishedAt`. It does not serve `WHERE publishedAt > ?` alone, and `[publishedAt]` alone does not serve the published list — without planner statistics SQLite prefers the status equality and sorts in a temporary B-tree. If a second hot path needs a different leading field, that is a second index — not a reason to enumerate every permutation, since each index costs storage and slows every write.
 
 ```sh
 pnpm exec mantle-harness indexes --require-public --format text
@@ -188,4 +189,4 @@ spec:
 - [`packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts`](../../../packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts)
 - [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
 - [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/guides/admin-ui.md

@@ -0,0 +1,135 @@
+---
+description: How Schema, View, Procedure, Trigger and uiSchema become Admin forms, lists, navigation and actions, with a complete customization example.
+---
+# Customize the Admin console
+
+Many Admin changes are manifest edits: labels, multiline inputs, operational
+list columns and tabs, reports and action placement. Admin API derives
+metadata from the compiled plan; the prebuilt SPA renders it. The host must
+already mount Admin API, authentication and Admin assets — see the
+[local Admin tutorial](../start/quickstart-admin.md).
+
+## Manifest to rendered UI
+
+| User request | Author this | What Admin renders / constraints |
+|---|---|---|
+| Rename a collection or explain a field | Schema `title` / `description`, property `title` / `description` | Localized labels and help. Property names and stored values stay unchanged. |
+| Make a field required or an option list | JSON Schema `required`, `enum`, `type` | Required marker and type-derived control; enums become selects. These are data contracts, not styling flags. |
+| Make a string multiline | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | Textarea for a top-level string field. `textarea` is the only supported explicit widget. |
+| Edit Markdown or HTML | Property `x-mcp-hint: markdown` or `html` | Rich editor; these hints take precedence over `widget: textarea`. `richtext` currently uses a textarea. |
+| Edit a timestamp or show money | `format: date-time` on a string; `x-mcp-hint: timestamp-ms` or `money-minor` on a number | Date/time controls or number preview. Money uses minor units divided by 100 and a sibling `currency` when present. |
+| Reorder an operational record list | Schema `uiSchema.list.primaryField`, `.columns` | Linked leading data field, then ordered columns. Native columns such as `status` and `createdAt` are allowed in `columns`; `primaryField` must be a scalar data property. |
+| Add business-state tabs | Schema `uiSchema.list.filterField` | Operational-only enum tabs/sidebar links. Field needs a string enum and a left-prefix index. |
+| Search record contents | Schema `searchableFields` | Searches declared string fields plus entry id. This is substring search, not an index declaration. |
+| Show related records | Required property `x-mantle-ref` | Eligible child collections fold into the parent's workbench; translation children use language tabs. |
+| Also show a folded child in navigation | Schema `uiSchema.nav.standalone: true`, optional `parentField` | Adds its own list with parent filter, retaining the folded view. Multiple eligible parent refs require `parentField`; not allowed on translation children. |
+| Add a read-only report and CSV | View `surface: staff`, `title`, `uiSchema.list` | Report navigation; `columns`, `searchFields`, `filterFields` use output names. Server filters before pagination; CSV includes all matches. |
+| Add a list-level action | Eligible Procedure `uiSchema.collectionAction: <schema>` | Collection action with a form generated from Procedure `input`. |
+| Add a row action | Eligible Procedure input property `x-mantle-ref: <schema>` | Row operation with prefilled reference. Selection uses a same-name Schema property, then a sole single-field unique index, otherwise entry `id`. |
+| Make generic content editing read-only | Schema root `schema.readOnly: true` | Generic authoring writes are blocked; declared Procedures remain available. A disabled field is not an authorization rule. |
+
+The data editor also handles booleans, numbers, objects and arrays from JSON
+Schema. Bound fields (`x-mantle-bind`) display read-only because Runtime owns
+the value. Media controls depend on the supported media schema and host media
+policy; `uiSchema` alone cannot enable uploads.
+
+Schema list presentation (`primaryField`, `columns`, `filterField`) is for
+`lifecycle: operational`. Publishing collections keep the built-in publishing
+workflow. For an alternate publishing table, define a staff View report.
+
+## Example: an operational inbox
+
+This complete source configures a collection and a separate staff report.
+The collection filters by `ticketState`, not Mantle's native publishing status.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: support-tickets
+spec:
+  title: { en: Support tickets, zh-TW: 客服工單 }
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [subject, ticketState]
+    properties:
+      subject: { type: string, title: Subject }
+      details: { type: string, description: Include the steps to reproduce. }
+      ticketState: { type: string, enum: [open, waiting, closed] }
+  indexes: [[ticketState]]
+  searchableFields: [subject, details]
+  uiSchema:
+    fields:
+      details: { widget: textarea }
+    list:
+      primaryField: subject
+      columns: [ticketState, createdAt]
+      filterField: ticketState
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: support-report
+spec:
+  title: Support report
+  surface: staff
+  from: support-tickets
+  fields: [id, subject, ticketState, createdAt]
+  uiSchema:
+    list:
+      columns: [subject, ticketState, createdAt]
+      searchFields: [subject]
+      filterFields: [ticketState]
+```
+
+The collection shows Subject first, State and Created at next, state tabs,
+and a multiline Details editor. The report is a separate navigation entry
+with its own search/filter configuration and CSV export. Schema `.list` and
+View `.list` are different contracts; do not copy their keys between atoms.
+
+## When a Procedure becomes a button
+
+`uiSchema.collectionAction` alone does not expose a Procedure. Admin discovers
+staff operations from either a staff MCP Trigger or an HTTP Trigger whose
+Procedure requires `ctx.staff`. Runtime rechecks Procedure `requires` on
+execution. Use the [Procedure reference](../reference/procedure.md#uischema)
+for a complete action declaration.
+
+An eligible operation with row bindings appears on those records. One with
+`collectionAction` appears on that collection's list. Operations without either
+appear in the standalone Operations screen. Row mutations use the observed
+entry version for optimistic concurrency where the Procedure contract declares
+`expectedVersion`; keep its input contract intact when adjusting presentation.
+
+## Verify a change
+
+1. Edit the application manifests, then run `mantle validate`, `mantle generate`
+   and `mantle generate --check` through the local package manager.
+2. Restart/reload the host so Admin receives the new compiled plan. Check
+   `/admin/api/collections`, `/admin/api/views-manifest` or
+   `/admin/api/operations` in an authenticated session if the UI seems stale.
+3. Open the affected list and editor: check labels, actual columns, filters,
+   form values and keyboard access. Verify a record after saving, and verify
+   report filters in CSV as well as the visible page.
+
+`uiSchema` roots and supported nested keys are closed. Schema accepts `fields`,
+`list`, `nav`; Procedure accepts `collectionAction`, `fields`; staff View accepts
+`list`. They do not accept a custom layout, CSS, React component, arbitrary
+widget name or permission policy. See [Schema](../reference/schema.md#uischema),
+[View](../reference/view.md#uischemalist) and [Procedure](../reference/procedure.md#uischema).
+
+For a new layout or unsupported widget, use application-owned UI against the
+appropriate APIs or propose a change to the Admin UI package. Do not patch
+`public/_mantle/admin/`: generation replaces those prebuilt assets. Visitor
+frontend styles and the `theme` skill's site changes do not style Admin.
+
+## Source
+
+- [Admin UI contract validation](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
+- [Admin metadata and operation discovery](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
+- [Entry form renderer](../../../packages/mantle-admin-ui/src/features/content/entry-edit-view.tsx)
+- [Collection renderer](../../../packages/mantle-admin-ui/src/features/content/collection-view.tsx)
+- [Action renderer](../../../packages/mantle-admin-ui/src/features/content/row-operations.tsx)
+- [Navigation rules](../../../packages/mantle-admin-ui/src/lib/collection-nav.ts)

package/docs/handbook/guides/agent-setup.md

@@ -0,0 +1,97 @@
+---
+description: Trace what npx skills add installs, hand off to the pinned SDK, project version-matched skills and diagnose missing or stale instructions.
+---
+# Install and verify agent instructions
+
+There are two separate installations: an agent's bootstrap skill and the
+application's SDK. Installing one does not install the other.
+
+## 1. Install the bootstrap skill
+
+```sh
+npx skills add aotter/mantle
+```
+
+The installer selects the repository's `mantle` skill. Read its printed
+installation path. In a project-local Codex installation that is
+`.agents/skills/mantle/SKILL.md`, not `skills/install/SKILL.md` (the latter is
+its source-repository path). Other agent selections and global installation
+can use different locations.
+
+The command installs the selected brief; it does not materialize a Mantle
+application, install `@aotter/mantle`, or copy `docs/`. The unqualified GitHub
+source follows its default branch, not necessarily `develop` or the npm
+version you intend to use. The skills installer's lock identifies the source
+skill; it is not the application's dependency lockfile.
+
+## 2. Select the SDK version, then read its own instructions
+
+Use the version the project already pins, or resolve the requested npm channel
+once and pin every selected `@aotter/mantle*` dependency to the same exact
+version. `latest` and `alpha` can describe different capabilities. Resolve only
+requirements the user has not provided: host, storage, public API/HTML, and
+whether staff need Admin. Follow the bootstrap skill to install the selected
+packages locally.
+No matching `mantle-starters` tag or bundle is needed to create a project.
+
+Then read:
+
+```text
+node_modules/@aotter/mantle/skills/install/SKILL.md
+node_modules/@aotter/mantle/docs/handbook/start/overview.md
+node_modules/@aotter/mantle/docs/handbook/reference/features.md
+```
+
+These files are in the npm tarball. They are the version-matched authority,
+including when the bootstrap skill came from a different Git ref. Every
+`docs/...` path in the skill resolves under the installed package, not under
+`.agents/skills/mantle/`. Keep using that SDK's docs for host examples and CLI
+behavior. No local `mantle` binary is available before package installation.
+
+## 3. Project the ongoing workflows
+
+From the application root, after installing the SDK:
+
+```sh
+pnpm exec mantle --help
+pnpm exec mantle skills
+pnpm exec mantle skills --check
+```
+
+| Artifact | What you get |
+|---|---|
+| `.agents/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | The installed package's four project-scoped workflows. |
+| `.claude/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | Identical bytes for Claude compatibility. |
+| `node_modules/@aotter/mantle/skills/` | All seven shipped skills, including opt-in `mantle`, `provision` and `media-gc`. |
+| `node_modules/@aotter/mantle/docs/` | Handbook and examples matched to the package. |
+
+`mantle skills` overwrites these four generated projections. Keep project-specific
+instructions elsewhere. `--check` does not write: exit 0 means they match,
+1 means missing/stale projections, and 2 means a command/package error.
+`mantle generate` does not project skills. Projection does not remove an older
+bootstrap `install` or legacy `.agent/skills` copy; use the version-matched
+project skills for ongoing work.
+
+## 4. Complete and verify the application
+
+Follow a [tutorial](../start/overview.md#start-with-your-integration), then run
+its generation, validation, TypeScript checks and actual local route probes.
+Successful skill installation proves only that the instructions were copied.
+It does not prove a server, login, Admin assets or MCP connection works.
+
+| Symptom | Cause and next step |
+|---|---|
+| `skills/install/SKILL.md` is missing | That is source provenance. Read the installer's destination instead. |
+| `docs/...` is missing after `skills add` | The skill does not carry the handbook. Install the pinned SDK and read its embedded docs. |
+| `mantle` is missing | Install local `@aotter/mantle`; run its binary through the project package manager. |
+| `MANIFEST_ROOT_NOT_FOUND` | Author manifests in the configured directory; `generate` is not a scaffold command. |
+| `mantle skills --check` exits 1 | Run `mantle skills`, then read the refreshed project skill. |
+| No projected provision/media-gc skill | These are intentionally opt-in. Read their installed package files when the task calls for them. |
+| A documented feature fails on an older release | Use that release's docs or explicitly upgrade; changing a skill does not change Runtime. |
+
+## Source
+
+- [Bootstrap install skill](../../../skills/install/SKILL.md)
+- [Projection implementation](../../../packages/mantle/src/cli/skills.ts)
+- [Package file list](../../../packages/mantle/package.json)
+- [Package docs and skills copying](../../../scripts/sync-package-docs.mjs)

package/docs/handbook/guides/typed-queries.md

@@ -0,0 +1,161 @@
+---
+description: Generate and call typed Views, including internal-only queries, and choose indexed entry readers without confusing them with authorized public reads.
+---
+# Query from TypeScript
+
+Use a **View** when a read needs declared params, projection, pagination or
+`requires` authorization. Use an **entry reader** for trusted host code that
+needs stored entries by a data field. Both are exposed by generated bindings;
+only the View executes the declared View authorization contract.
+
+## Declare an internal query
+
+Save this complete source as `manifests/tickets.yaml`. The operational Schema
+uses a business status field distinct from Mantle's native `status`.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: tickets
+spec:
+  title: Tickets
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [subject, ticketState]
+    properties:
+      subject: { type: string }
+      ticketState: { type: string, enum: [open, closed] }
+  indexes: [[ticketState]]
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: tickets-by-state
+spec:
+  surface: internal
+  from: tickets
+  fields: [id, subject, ticketState]
+  filter:
+    eq: { field: ticketState, value: { $param: ticketState } }
+  params:
+    type: object
+    additionalProperties: false
+    required: [ticketState]
+    properties:
+      ticketState: { type: string, enum: [open, closed] }
+  limit: 50
+```
+
+```sh
+pnpm exec mantle validate --no-source
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+```
+
+`internal` keeps this query out of REST routes, OpenAPI, MCP/WebMCP catalogs and
+Admin reports. It remains in the plan and generated binding. It is not a
+security bypass: adding `requires` evaluates the same authorization and guards
+against the host-supplied `ctx` on every call. No `uiSchema` or shared HTTP
+cache is allowed for an internal View.
+
+## Bind and call
+
+When the host already owns a prepared Runtime, bind it once where you need the
+typed API. This function can live in `src/queries.ts`:
+
+```ts
+import type { MantleRuntime } from "@aotter/mantle/runtime";
+import { bindMantle } from "../.mantle/generated/mantle.js";
+
+export async function openTickets(runtime: MantleRuntime) {
+  const mantle = bindMantle(runtime);
+  const result = await mantle.views.ticketsByState({
+    params: { ticketState: "open" },
+    page: 1,
+    show: 20,
+  });
+  if (!result.ok) throw new Error(result.diagnostic.message);
+  return result.result.rows;
+}
+```
+
+The runtime response uses `result` on success (`result.result.rows` above);
+REST wraps those rows under `data` instead.
+
+The wire name `tickets-by-state` becomes `ticketsByState`. Required params
+make the request and `params` mandatory; invalid enum values are TypeScript
+errors, and Runtime also validates actual inputs. `show` remains capped by
+`limit`. For an authorized View, pass the verified caller context as `ctx`;
+do not fabricate staff/user identities from request input.
+
+A host without a Runtime can use generated `createMantle({ storage, handlers,
+ports })`, which delegates one eager boot attempt and returns the typed
+binding. Host code still owns connection lifetime and retries. See
+[Runtime and adapters](../concepts/runtime-and-adapters.md).
+
+## What is typed
+
+| Query form | Generated shape | Limit |
+|---|---|---|
+| Declarative View | `Mantle.ViewParams_<name>` and `Mantle.ViewRow_<name>` | Projection follows `fields`; native columns have their native types. Data properties remain optional in the row type. |
+| SQL View | Typed params; row type `unknown` | The generator does not infer SQL expressions or aliases. Narrow/validate rows in host code. |
+| Entry field reader | `MantleEntry<Mantle.Entry_<schema>>` | The field must be a declared data property and the value a compatible string, number or boolean. Types do not prove an index exists. |
+| Dynamic Runtime call | `runtime.executeView({ view, ctx, options })` | Useful without codegen; supplying a generic row type is the caller's assertion, not SQL validation. |
+
+Without `fields`, a declarative View includes native entry columns and Schema
+properties. Use explicit projections on exposed reads. Public declarative
+Views over publishing Schemas inject `status = published`; internal/staff
+Views and SQL statements do not. See [View reference](../reference/view.md).
+
+## Indexed entry reads
+
+For the Schema above:
+
+```ts
+const rows = await mantle.entries.tickets.findManyByDataField({
+  field: "ticketState",
+  value: "open",
+  limit: 20,
+});
+// rows[n].data is the generated tickets data shape.
+```
+
+| Method | Returns | Options worth knowing |
+|---|---|---|
+| `readBySlug({ slug, locale?, status? })` | One entry or `null` | Use on a Schema with a slug field and an appropriate index. |
+| `readByDataField({ field, value, locale?, status? })` | One entry or `null` | Equality on one data property. |
+| `readByDataFieldIn({ field, values, latestPerValue?, locale?, status? })` | Entry array | Batch equality lookups; `latestPerValue` selects the newest match per value. |
+| `findManyByDataField({ field, value, limit })` | Entry array | Bounded equality lookup across statuses; no `ctx`, `status` or `locale` option. |
+
+These readers do not evaluate View `requires`, inject public visibility or
+fire mutation hooks. In particular, `findManyByDataField` can return drafts.
+Use a public View for untrusted callers; do not expose a raw reader as a public
+route and assume the generated type authorizes it. Declare a measured index
+whose leftmost field matches the lookup; do not scan an entire collection in
+TypeScript to replace a field query.
+
+## Generate from an existing plan
+
+A build tool that already compiled a sealed plan can use the pure emitter:
+
+```ts
+import { emitMantleModule } from "@aotter/mantle/codegen";
+
+const emitted = emitMantleModule({ plan });
+if (!emitted.ok) throw new Error(emitted.diagnostics.map(d => d.message).join("\n"));
+// Write emitted.source to your generated module in the build step.
+```
+
+Pass either `{ plan }` or `{ linked }`, never both. The plan form avoids
+reparsing YAML and preserves the same generated types and entry/View/Procedure
+bindings. The emitter does no I/O, asset copying, storage preparation or caching.
+
+## Source
+
+- [Binding generator](../../../packages/mantle/src/codegen/emitMantleModule.ts)
+- [Type generator](../../../packages/mantle-spec/src/usecase/EmitTypesUseCase.ts)
+- [Entry reader contract](../../../packages/mantle-runtime/src/domain/port/EntryReader.ts)
+- [View execution](../../../packages/mantle-runtime/src/usecase/view/ExecuteViewUseCase.ts)