@aotter/mantle 0.1.3-alpha.5 → 0.1.3

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,96 @@
+---
+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 --skill install
+```
+
+The installer selects the repository's `install` skill. Read its printed
+installation path. In a project-local Codex installation that is
+`.agents/skills/install/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.
+
+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/install/`. 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 `install`, `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)

package/docs/handbook/navigation.json

@@ -4,12 +4,21 @@
     {
       "text": "Start here",
       "items": [
+        { "text": "Handbook overview", "link": "/start/overview" },
         { "text": "Project layout and the CLI loop", "link": "/start/project-and-cli" },
         { "text": "Quickstart: a minimal Worker", "link": "/start/quickstart-worker" },
         { "text": "Quickstart: local Admin (opt-in)", "link": "/start/quickstart-admin" },
         { "text": "When the host is ChatGPT Sites", "link": "/sites/index" }
       ]
     },
+    {
+      "text": "Task guides",
+      "items": [
+        { "text": "Agent installation and handoff", "link": "/guides/agent-setup" },
+        { "text": "Typed queries and internal Views", "link": "/guides/typed-queries" },
+        { "text": "Customize Admin from manifests", "link": "/guides/admin-ui" }
+      ]
+    },
     {
       "text": "Concepts",
       "items": [
@@ -22,6 +31,21 @@
         { "text": "Runtime pipeline and adapters", "link": "/concepts/runtime-and-adapters" }
       ]
     },
+    {
+      "text": "Reference",
+      "items": [
+        { "text": "Manifest feature table", "link": "/reference/features" },
+        { "text": "Manifest envelope", "link": "/reference/manifest" },
+        { "text": "Schema", "link": "/reference/schema" },
+        { "text": "View", "link": "/reference/view" },
+        { "text": "Procedure", "link": "/reference/procedure" },
+        { "text": "Trigger", "link": "/reference/trigger" },
+        { "text": "Authorization requirements", "link": "/reference/authorization" },
+        { "text": "Site defaults and site_config", "link": "/reference/site-config" },
+        { "text": "Diagnostic codes", "link": "/reference/diagnostics" },
+        { "text": "HTTP, MCP, CLI and packages", "link": "/reference/surface" }
+      ]
+    },
     {
       "text": "ChatGPT Sites",
       "items": [
@@ -60,20 +84,6 @@
         { "text": "Guarded API access", "link": "/examples/guarded-api" }
       ]
     },
-    {
-      "text": "Reference",
-      "items": [
-        { "text": "Manifest envelope", "link": "/reference/manifest" },
-        { "text": "Schema", "link": "/reference/schema" },
-        { "text": "View", "link": "/reference/view" },
-        { "text": "Procedure", "link": "/reference/procedure" },
-        { "text": "Trigger", "link": "/reference/trigger" },
-        { "text": "Authorization requirements", "link": "/reference/authorization" },
-        { "text": "Site defaults and site_config", "link": "/reference/site-config" },
-        { "text": "Diagnostic codes", "link": "/reference/diagnostics" },
-        { "text": "HTTP, MCP, CLI and packages", "link": "/reference/surface" }
-      ]
-    },
     {
       "text": "Releases",
       "items": [

package/docs/handbook/reference/features.md

@@ -0,0 +1,55 @@
+---
+description: Manifest capability table mapping authoring goals to Schema, View, Procedure and Trigger fields, generated APIs and Admin behavior.
+---
+# Manifest feature reference
+
+All paths below are relative to the atom's `spec`. The envelope is always
+`apiVersion`, `kind`, `metadata.name`, `spec`. Features compose from these four
+atoms; there is no separate Form, Workflow or UI manifest kind. See the
+[envelope reference](./manifest.md) for naming and unknown-key rules.
+
+## Capability table
+
+| Goal | Atom and fields | Runtime / surface effect | Contract |
+|---|---|---|---|
+| Define stored business data | Schema `schema` | Validated fields; storage adapter prepares the Schema. Generated entry types follow the JSON Schema subset. | [Schema](./schema.md) |
+| Choose draft publishing or live records | Schema `lifecycle` | `publishing` has draft/publish transitions; `operational` creates live records. Admin workflow follows this choice. | [Lifecycle](../concepts/lifecycle-and-locales.md) |
+| Label fields and collections | Schema `title`, `description`, property `title`, `description` | Localized Admin labels/help. Does not rename data keys. | [LocalizedText](./manifest.md#localizedtext) |
+| Make Procedure-managed records | Schema `schema.readOnly` | Disables generic authoring writes; declared Procedures still work. | [Read-only collections](./schema.md#root-readonly-true) |
+| Find and constrain records | Schema `indexes`, `uniqueIndexes`, `searchableFields` | Native access paths, uniqueness and declared substring-search fields. Search fields do not create indexes. | [Indexes](./schema.md#indexes) |
+| Translate or relate records | Schema `localized`, `translates`; property `x-mantle-ref` | Locale rows, joined translations, relation controls and folded child collections. | [Schema](./schema.md), [Admin guide](../guides/admin-ui.md) |
+| Stamp trusted values | Property `x-mantle-bind` | Runtime stamps identity/time; generic agent inputs exclude bound fields and Admin shows them read-only. | [Binding](./schema.md#x-mantle-bind) |
+| Adjust collection inputs and list | Schema `uiSchema.fields`, `.list`, `.nav` | Textareas, operational columns/tabs, standalone child navigation. No CSS or component injection. | [Admin guide](../guides/admin-ui.md) |
+| Query one Schema portably | View `from`, `fields`, `filter`, `orderBy`, `limit`, `params` | Named query with generated typed params and projected rows. | [View](./view.md), [typed queries](../guides/typed-queries.md) |
+| Join or aggregate in SQLite | View `sql`, `params`, `limit` | One bound SELECT; requires a SQLite-capable adapter. Generated row type is `unknown`. | [SQL Views](./view.md#sql) |
+| Choose read visibility | View `surface` | `public`: public REST/MCP; `staff`: Admin reports/staff MCP; `internal`: host binding only. Transports require host composition. | [Surfaces](./view.md#surfaces) |
+| Authorize a query or action | View / Procedure `requires.auth`, `requires.guard` | Runtime checks verified caller context and optional guard. Visibility and UI metadata do not grant access. | [Authorization](./authorization.md) |
+| Filter by caller identity | View `filter` with `$ctx.user: id` | Declarative equality filter; requires user auth and a left-prefix index. | [Identity filters](./view.md#value-forms) |
+| Cache anonymous published reads | View `cache.sharedMaxAge` | Eligible public declarative publishing reads receive shared HTTP cache policy when the host configures cache scope. | [View cache](../concepts/views.md#shared-response-cache) |
+| Configure a report | Staff View `title`, `uiSchema.list` | Ordered report/CSV columns, server-side search and exact filters. | [View list](./view.md#uischemalist) |
+| Define an action | Procedure `input`, `output`, `handler` | Typed input/output; builtin mutation or registered host handler. A Procedure does not create an HTTP route by itself. | [Procedure](./procedure.md) |
+| Put an action in Admin | Procedure `uiSchema.collectionAction`, `.fields`; input `x-mantle-ref`; qualifying Trigger | Collection/row actions and forms; eligible standalone operations appear under Operations. | [Admin guide](../guides/admin-ui.md) |
+| Describe an agent action | Procedure `title`, `description`, `mcp` | Tool descriptions and behavior annotations; enforcement remains in runtime authorization/validation. | [Procedure](./procedure.md) |
+| Expose an HTTP action | Trigger `source: { kind: http, method, path }`, `target.procedure` | Handler on the declared `/api/` path through supporting host adapters. | [HTTP Trigger](./trigger.md#http-source) |
+| Expose an agent action | Trigger `source: { kind: mcp, surface }`, `target.procedure` | Public or staff MCP tool; Procedure authorization still applies. | [Trigger](./trigger.md) |
+| React to content lifecycle | Trigger `source: { kind: lifecycle, schema, on, errorPolicy }`, `target.procedure` | Invokes the action on selected lifecycle events. Deferred execution needs host support. | [Hooks](../concepts/procedures-and-triggers.md) |
+
+## Where manifest control ends
+
+Manifests describe data, callable behavior and supported presentation metadata.
+They do not declare arbitrary React components, visitor routes, page layouts,
+CSS, provider credentials or deployment resources. Those belong to application
+source and optional host packages. For an Admin change, consult the
+[rendering map](../guides/admin-ui.md) before deciding that custom UI is needed.
+
+The pipeline is source → parse → link → compile → prepare storage → bind
+runtime. `mantle generate` projects the plan and types; it does not start a
+server. Programmatic `emitMantleModule({ plan })` also accepts an already
+compiled plan; see [typed queries](../guides/typed-queries.md).
+
+## Source
+
+- [Manifest grammar](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
+- [Admin UI validation](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
+- [Type generation](../../../packages/mantle-spec/src/usecase/EmitTypesUseCase.ts)
+- [Runtime binding generation](../../../packages/mantle/src/codegen/emitMantleModule.ts)

package/docs/handbook/reference/manifest.md

@@ -5,6 +5,8 @@ description: Envelope fields, unknown-key policy, multi-document YAML, Localized
 
 This page covers the rules that apply to every Manifest document before kind-specific validation runs. Read it once; the four atom pages ([Schema](./schema.md), [View](./view.md), [Procedure](./procedure.md), [Trigger](./trigger.md)) assume it. Diagnostic codes named here are catalogued in [Diagnostics](./diagnostics.md).
 
+For a task-to-field table covering all four atoms, see the [Manifest feature reference](./features.md). For the resulting console, see [Customize Admin](../guides/admin-ui.md).
+
 ## Envelope
 
 Every document is a YAML mapping with exactly four top-level keys.
@@ -37,7 +39,7 @@ The parser rejects keys outside the shipped grammar at every level it knows. The
 | `/` | `apiVersion`, `kind`, `metadata`, `spec` |
 | `/metadata` | `name` |
 | `/spec` (Schema) | `title`, `description`, `schema`, `uiSchema`, `uniqueIndexes`, `indexes`, `searchableFields`, `localized`, `translates`, `lifecycle` |
-| `/spec` (View) | `title`, `uiSchema`, `from`, `sql`, `surface`, `requires`, `filter`, `fields`, `orderBy`, `limit`, `params` |
+| `/spec` (View) | `title`, `uiSchema`, `from`, `sql`, `surface`, `cache`, `requires`, `filter`, `fields`, `orderBy`, `limit`, `params` |
 | `/spec` (Procedure) | `title`, `description`, `requires`, `input`, `uiSchema`, `output`, `handler`, `mcp` |
 | `/spec` (Trigger) | `source`, `target` |
 | `/spec/translates` | `parent`, `on` |

package/docs/handbook/reference/schema.md

@@ -164,7 +164,7 @@ Closed Admin-only roots: `fields`, `list`, `nav`. Nested keys are closed too. Un
 | `fields.<field>.widget` | Only `textarea`. The field must be a top-level property with a string type (`string` or `[string, null]`). |
 | `list.filterField` | Operational Schemas only. A declared property with a non-empty string `enum` that is the first field of some `indexes` or `uniqueIndexes` tuple. Admin renders the enum as sidebar links and list tabs. |
 | `list.primaryField` | Operational Schemas only. A non-empty top-level scalar property; rendered as the linked leading column. |
-| `list.columns` | Operational Schemas only. Top-level properties, no repeats and not repeating `primaryField`; structured values render as compact JSON. |
+| `list.columns` | Operational Schemas only. Top-level properties or native entry columns, no repeats and not repeating `primaryField`; structured values render as compact JSON. |
 | `nav.standalone` | Boolean. `true` also emits a main Admin Nav list entry with a **parent autocomplete filter**. It does not unfold: required `x-mantle-ref` children still compose under the parent. Omit or `false` means fold-only (discover via the parent-entry workbench). Rejected on top-level Schemas, `translates` children, and Schemas with no eligible required-ref parent. |
 | `nav.parentField` | Allowed only with `standalone: true`. Names a required `x-mantle-ref` field used as the parent filter. One eligible required ref is inferred; more than one requires an explicit `parentField`. Do not rely on property-order heuristics when multiple refs exist. |
 

package/docs/handbook/reference/surface.md

@@ -97,7 +97,7 @@ Tool names are the mangled `metadata.name`: lower-cased, with `-` replaced by `_
 
 | Tool | Surface | Registered when |
 |---|---|---|
-| `query_view_<segment>` | The View's own `surface` | One per declared View. `annotations.readOnlyHint` is `true`; the input schema is the View's `params.properties` plus `page` and `show`. |
+| `query_view_<segment>` | The View's own `surface` | One per public or staff View; internal Views have no tool. `annotations.readOnlyHint` is `true`; the input schema is the View's `params.properties` plus `page` and `show`. |
 | `<procedure_segment>` | The MCP Trigger's `surface` | One per `mcp` Trigger. `annotations` carry what Core can prove (`readOnlyHint: false` for every builtin handler, `destructiveHint: true` for `op: delete`, `idempotentHint: true` when an input carries `x-mcp-hint: idempotency-key`) plus whatever the Procedure declares under `spec.mcp`; `ref` handlers get nothing inferred beyond the idempotency key. Generic authoring, lifecycle and media tools are `readOnlyHint: false`; `delete_entry` is also `destructiveHint: true`. |
 | `<procedure segment>` | The Trigger's `surface` | One per `Trigger.source.kind: mcp`. A Procedure with no MCP Trigger is not exposed. |
 | `request_publish` | staff | Always. Rejected at call time for an operational Schema. |
@@ -165,7 +165,7 @@ The umbrella installs Spec and Runtime only. Web, Admin, Auth, Admin UI, Bun, Ve
 | `@aotter/mantle-spec` | `/spec` | Manifest grammar, parser, validators, JSON Schema to zod, site-config contract, diagnostic catalog. No environment, no IO. |
 | `@aotter/mantle-runtime` | `/runtime` | Hexagonal runtime: domain ports, use cases, MCP catalog, storage helpers. No adapter dependencies. |
 | — | `/runtime/testing` | Node-only crowded-SQLite planner and HTTP sampling helpers used by `mantle-harness`. |
-| — | `/codegen` | The pure linked-manifests to typed-module emitter, with no IO. |
+| — | `/codegen` | The pure linked-manifests or compiled-plan to typed-module emitter, with no IO. |
 | `@aotter/mantle-web` | `/web` | HTML, Markdown, `llms.txt`, sitemap, SEO and preview composition. No routes, no platform dependencies. |
 | `@aotter/mantle-admin` | `/admin` | Admin API, auth route mounting, OAuth pages, static-asset composition. |
 | `@aotter/mantle-auth` | `/auth` | Host-neutral Better Auth identity, staff roles, and OAuth 2.1 / MCP authorization. Adapters own IP headers and storage bindings. |

package/docs/handbook/reference/view.md

@@ -3,7 +3,7 @@ description: View field reference — declarative and SQL forms, filter AST, par
 ---
 # View
 
-A View is a named read-only query over Schemas. It is the only atom that needs no [Trigger](./trigger.md): declaring `surface` mounts it. This page is the field-level contract; the concepts are in [Views](../concepts/views.md) and [The four atoms](../concepts/four-atoms.md). Envelope rules are in [Manifest envelope and conventions](./manifest.md), and every diagnostic code named here is catalogued in [Diagnostics](./diagnostics.md).
+A View is a named read-only query over Schemas. It is the only atom that needs no [Trigger](./trigger.md): `surface: public` or `staff` exposes it on supported transports; `internal` keeps it host-only. This page is the field-level contract; the concepts are in [Views](../concepts/views.md) and [The four atoms](../concepts/four-atoms.md). Envelope rules are in [Manifest envelope and conventions](./manifest.md), and every diagnostic code named here is catalogued in [Diagnostics](./diagnostics.md).
 
 ## Fields
 
@@ -13,7 +13,7 @@ A View is a named read-only query over Schemas. It is the only atom that needs n
 | `uiSchema` | object | no | — | Only on `surface: staff`; only the key `list`. Violations are `VIEW_UI_INVALID`. |
 | `from` | string | exactly one of `from` / `sql` | — | Name of a declared Schema (`VIEW_FROM_UNKNOWN_SCHEMA`). The declarative form. |
 | `sql` | string | exactly one of `from` / `sql` | — | One SQLite `SELECT`. See [`sql`](#sql). |
-| `surface` | `public` \| `staff` | yes | — | Decides where the View mounts. See [Surfaces](#surfaces). |
+| `surface` | `public` \| `staff` \| `internal` | yes | — | Decides where the View mounts. See [Surfaces](#surfaces). |
 | `cache` | `{ sharedMaxAge }` | no | — | Anonymous REST shared-cache hint. `sharedMaxAge` is an integer from 1 to 86400. Only an unguarded, declarative public View over a publishing Schema may declare it. |
 | `requires` | AuthorizationRequirements | no | — | `auth.all` predicates plus one optional `guard.procedure`. See [Authorization](./authorization.md). |
 | `filter` | FilterAst | no | — | `from` form only. See [Filter AST](#filter-ast). |
@@ -154,7 +154,7 @@ One statement, read-only, compiled and bound by the runtime.
 Bound params are passed as positional values; caller input is never interpolated into the statement. SQLite JSON functions are available, so `json_each` and `json_extract` can unnest and project array or object members of `data` — the SQL example above does both.
 
 > **Warning**
-> `sql` Views are native SQLite. Static validation never executes the statement, so a syntax or column error surfaces only when the View runs. On a storage adapter that does not support the native dialect the View fails at prepare time with `VIEW_DIALECT_UNSUPPORTED`, naming the dialects that adapter does support.
+> `sql` Views are native SQLite. `mantle validate` prepares each statement against an empty SQLite database containing only the declared Schema tables; an undeclared table, syntax error or unknown column is `INVALID_MANIFEST_ENVELOPE` at `/spec/sql`. Programmatic validation runs the same check when the host supplies `sqlViewSandbox`; without that port it is deferred to the host's admission gate. On a storage adapter that does not support the native dialect the View fails at prepare time with `VIEW_DIALECT_UNSUPPORTED`, naming the dialects that adapter does support.
 
 ## `params`
 
@@ -205,6 +205,11 @@ Admin applies search and filters before pagination, rejecting a search term or f
 |---|---|---|---|
 | `public` | `GET /api/views/<name>`, plus a catalog at `GET /api/views` | `query_view_<segment>` on `/mcp` | Also mounted at `GET /admin/api/views/<name>` and `/export` behind the staff gate |
 | `staff` | `GET /admin/api/views/<name>` and `/admin/api/views/<name>/export` — not mounted publicly | `query_view_<segment>` on `/mcp/staff` | Report sidebar |
+| `internal` | Not mounted | Not mounted | Not listed or mounted |
+
+For a complete generated-binding example, see [Typed queries](../guides/typed-queries.md).
+
+An `internal` View remains in the compiled plan for host code to call through `MantleRuntime.executeView`. It is an exposure policy, not an authorization bypass: `requires` and guards still evaluate against the `ctx` supplied by the host. Shared HTTP caching is invalid because no adapter owns an HTTP response for the View.
 
 A `public` declarative View over a `publishing` Schema reads **published rows only**, on every transport. The runtime adds `status = published` to the compiled query whether or not the filter spells it out; writing it is allowed and redundant, and comparing `status` to any other value is rejected at validate time (`VIEW_PUBLIC_STATUS_INVALID`). Staff Views see every status. `operational` Schemas create rows as `published`, so nothing is added. SQL Views (`spec.sql`) are the author's own statement and receive no injected predicate. Decision record: ADR-0025.