@aotter/mantle 0.1.3-alpha.6 → 0.1.3

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. |

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). |
@@ -207,6 +207,8 @@ Admin applies search and filters before pagination, rejecting a search term or f
 | `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.

package/docs/handbook/releases/index.md

@@ -17,10 +17,54 @@ stable candidate cut from `main`. Installing a prerelease means opting into an
 exact version, not a channel. [GitHub Releases](https://github.com/aotter/mantle/releases)
 is the canonical, immutable change history; this chapter is the narrative one.
 
-All ten packages share a single version and are published together, so mixed
+All eleven packages share a single version and are published together, so mixed
 versions across `@aotter/mantle*` are never a supported combination. Pin the
 version you install and upgrade the whole set at once.
 
+## 0.1.3 — 2026-09-23
+
+0.1.3 tightens the contract between Manifests, generated TypeScript, agent
+skills and the optional Admin surface. To upgrade from 0.1.2, pin every
+selected `@aotter/mantle*` package to `0.1.3`, refresh the lockfile, then run
+`mantle generate`, `mantle skills` and the matching `--check` commands.
+
+**Private and typed reads.** Views may use `surface: internal` to stay out of
+REST, MCP, WebMCP, OpenAPI and Admin while remaining callable from host code.
+Generated bindings type declarative View params and rows, expose typed indexed
+field reads for Schemas, and can be emitted from an already compiled plan. SQL
+Views remain SQLite-native and deliberately return an `unknown` row type.
+
+**Safer View storage and validation.** Public declarative Views over publishing
+Schemas always enforce published status. Native entry columns (`id`, `status`,
+`version`, `createdAt`, `updatedAt`, `authorId`) are reserved consistently and
+may be used in the supported View/index positions. SQL validation is confined
+to declared Schema tables, and the local index harness now uses production-
+shaped planner and fixture state instead of reporting an artificial pass.
+
+**MCP and authorization.** Tool schemas have agent-shaped inputs and standard
+read-only, destructive, open-world and idempotency annotations. Calls carry
+expected-version data through optimistic concurrency checks, enforce the
+caller gate, and can emit audit records keyed by a declared idempotency input.
+OAuth provider extensions, account linking and sign-in-link flows are owned by
+the extracted optional `@aotter/mantle-auth` package. Session cache keys bind
+to the prepared store identity so replacing D1 cannot revive stale sessions.
+
+**Admin and authoring.** Manifest `uiSchema` can select operational collection
+columns/tabs, staff report search/filter/CSV fields and collection or row
+actions. Native columns render correctly in lists, and operation dialogs reset
+their optimistic-concurrency state between actions. The handbook now starts
+with a task-oriented overview, a complete Manifest feature table, typed-query
+and Admin-rendering guides, and an explicit skill-install → pinned SDK →
+project-skill handoff. The CLI points to those installed, version-matched docs.
+
+**Upgrade note.** Regeneration is required because generated bindings and
+projected skills gained APIs and instructions. Applications that declared one
+of the newly reserved native column names as business data must rename that
+field before upgrading. Backend-specific D1/IndexedDB cost inspectors and
+server-side soak budgets remain deferred to
+[#1040](https://github.com/aotter/mantle/issues/1040); the conservative local
+harness is a preflight, not production cost evidence.
+
 ## 0.1.2 — 2026-09-21
 
 The first stable release, and Mantle's first public one. Everything before it

package/docs/handbook/start/overview.md

@@ -0,0 +1,52 @@
+---
+description: Choose a Mantle integration, discover manifest capabilities, and find tutorials, task guides, concepts and field-level reference.
+---
+# Mantle handbook
+
+Mantle turns YAML manifests into a validated runtime plan, typed TypeScript
+bindings, and optional HTTP, MCP and Admin surfaces. Your application owns the
+host, storage and frontend. Four atoms describe the contract: **Schema** stores
+data, **View** reads it, **Procedure** acts on it, and **Trigger** binds an action
+to HTTP, MCP or lifecycle events.
+
+This handbook describes the SDK snapshot that carries it. For an installed
+project, read `node_modules/@aotter/mantle/docs/handbook/`; a website or Git
+branch can describe a different version. The [release index](../releases/index.md)
+links published releases. A prerelease capability is not a promise that the
+current npm `latest` contains it.
+
+## Start with your integration
+
+| Goal | Start here | Result |
+|---|---|---|
+| Understand what manifests can express | [Manifest feature reference](../reference/features.md) | A capability-to-field map across the four atoms. |
+| Validate manifests in an existing tool | [Spec-only adoption](../../spec-only-host-adoption.md) | Parse and link without Runtime, storage or a UI. |
+| Embed Runtime in an existing host | [Runtime and adapters](../concepts/runtime-and-adapters.md), then [typed queries](../guides/typed-queries.md) | Bind your storage and call the generated API. |
+| Build a local Cloudflare API | [Minimal Worker tutorial](./quickstart-worker.md) | A running public View and a verified HTTP response. |
+| Add a staff console | [Local Admin tutorial](./quickstart-admin.md) | Email OTP, Admin assets and a local human workflow. |
+| Build on ChatGPT Sites | [Sites integration](../sites/index.md) | Host-owned sign-in and deployment with Mantle content. |
+| Work through a coding agent | [Skill installation and handoff](../guides/agent-setup.md) | Bootstrap skill, pinned package, then project-local instructions. |
+
+Human authors can follow these pages directly; installing an agent skill is
+optional. Do not start with `mantle generate` in an empty directory: author the
+manifests and host first, then generate and validate.
+
+## Find the right kind of documentation
+
+- **Tutorials** walk through a running minimal service or local Admin.
+- **Task guides** explain typed queries, Admin customization and agent setup.
+- **Concepts** explain the four atoms, runtime, lifecycle, authorization and transports.
+- **Reference** lists accepted fields, defaults, restrictions and diagnostics.
+- **Host guides** cover Cloudflare and Sites wiring and operations.
+- **Examples** supply complete domain manifests and runnable host references.
+
+The [project and CLI guide](./project-and-cli.md) describes file ownership and
+the verification loop. The [examples hub](../examples/hub.md) helps select a
+domain model. Use the [field reference](../reference/manifest.md) when checking
+exact syntax; do not infer grammar from a UI screenshot.
+
+## Source
+
+- [Core package](../../../packages/mantle/README.md)
+- [Handbook navigation](../navigation.json)
+- [Consumer skills](../../../skills/README.md)

package/docs/handbook/start/project-and-cli.md

@@ -5,7 +5,7 @@ description: The files you own in a Mantle project, every mantle and mantle-harn
 
 This page describes a directly authored Mantle project: which files are yours, what the installed CLI does to them, and the loop you run before every commit. Surfaces are optional — take only what you need. [The minimal Worker](./quickstart-worker.md) is Spec + adapter without Admin. [Local Admin](./quickstart-admin.md) is the opt-in Dev UI path when humans need a console.
 
-Cold start from GitHub or a marketplace host is the install skill, not this page:
+Agents can bootstrap with the install skill; human authors can follow this guide directly. For installation paths and the pinned-package handoff, see [Agent setup](../guides/agent-setup.md):
 
 ```sh
 npx skills add aotter/mantle --skill install
@@ -77,7 +77,7 @@ It does not project skills, update packages, change styling, provision providers
 | `createMantle({ storage, handlers, ports })` | Prepares storage eagerly once and returns the typed binding. No caching or retry. |
 | `bindMantle(runtime)` | The same typed binding over a runtime whose lifecycle the host already owns. |
 
-The binding exposes `mantle.views.<lowerCamelName>()`, `mantle.procedures.<name>(input, ctx)`, `mantle.entries.<collection>.createDraft({ data, authorId })`, typed indexed field reads such as `mantle.entries.<collection>.findManyByDataField({ field, value, limit })`, and the underlying `mantle.runtime`. Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally. Details are in [HTTP, MCP, CLI and packages](../reference/surface.md).
+The binding exposes `mantle.views.<lowerCamelName>()`, `mantle.procedures.<name>(input, ctx)`, `mantle.entries.<collection>.createDraft({ data, authorId })`, typed indexed field reads such as `mantle.entries.<collection>.findManyByDataField({ field, value, limit })`, and the underlying `mantle.runtime`. Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally. See [Typed queries](../guides/typed-queries.md) for internal Views and entry-reader examples. Details are in [HTTP, MCP, CLI and packages](../reference/surface.md).
 
 ## The daily loop
 

package/docs/handbook/start/quickstart-worker.md

@@ -3,7 +3,7 @@ description: "Author a minimal Cloudflare Worker from scratch: one Schema, one p
 ---
 # Quickstart: a minimal Worker
 
-This page reproduces Core's API-only Worker reference as a from-scratch walkthrough. It is the embed / adapter path: View REST without Admin, Auth or a visitor frontend. Admin is opt-in when humans need a console — [Quickstart: local Admin](./quickstart-admin.md). Install every `@aotter/mantle*` package from the `latest` dist-tag; see [Versions](../reference/surface.md#versions).
+This page reproduces Core's API-only Worker reference as a from-scratch walkthrough. It is the embed / adapter path: View REST without Admin, Auth or a visitor frontend. Admin is opt-in when humans need a console — [Quickstart: local Admin](./quickstart-admin.md). Resolve the intended release once and pin every `@aotter/mantle*` package to it; see [Versions](../reference/surface.md#versions).
 
 ## Prerequisites
 
@@ -13,7 +13,10 @@ This page reproduces Core's API-only Worker reference as a from-scratch walkthro
 
 ## 1. `package.json`
 
-Install every `@aotter/mantle*` package from the `latest` dist-tag and add the peers the Cloudflare adapter needs.
+The `latest` entries below are bootstrap placeholders. Step 5 replaces both
+with one exact version before the first build. For a prerelease evaluation,
+select its exact version explicitly rather than mixing channels. The other
+entries are the peers and tools used by this reference.
 
 ```json
 {
@@ -130,7 +133,9 @@ Both compatibility flags are required by the adapter. `MANTLE_AUTH_MODE` must be
 ## 5. Install, generate, validate, run
 
 ```sh
-pnpm install
+# Resolve once; for a requested prerelease, set its exact version instead.
+MANTLE_VERSION=$(pnpm view @aotter/mantle@latest version)
+pnpm add --save-exact "@aotter/mantle@$MANTLE_VERSION" "@aotter/mantle-cloudflare@$MANTLE_VERSION"
 pnpm exec mantle generate
 pnpm exec mantle validate
 pnpm exec wrangler dev --local --ip 127.0.0.1 --port 8787

package/docs/spec-only-host-adoption.md

@@ -6,7 +6,7 @@ Runtime. This Spec-only path is allowed by
 [ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md), not a new adapter,
 manifest grammar, or fork of Core.
 
-This recipe targets `0.1.3-alpha.6`. Pin the package, record the tested version, and
+This recipe targets `0.1.3`. Pin the package, record the tested version, and
 rerun compatibility checks when upgrading.
 
 ## What stays with the host

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.3-alpha.6",
+  "version": "0.1.3",
   "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Auth, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -83,8 +83,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.3-alpha.6",
-    "@aotter/mantle-spec": "0.1.3-alpha.6"
+    "@aotter/mantle-runtime": "0.1.3",
+    "@aotter/mantle-spec": "0.1.3"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
@@ -92,13 +92,13 @@
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-admin": "0.1.3-alpha.6",
-    "@aotter/mantle-auth": "0.1.3-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.6",
-    "@aotter/mantle-bun": "0.1.3-alpha.6",
-    "@aotter/mantle-vercel": "0.1.3-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.6",
-    "@aotter/mantle-web": "0.1.3-alpha.6"
+    "@aotter/mantle-admin": "0.1.3",
+    "@aotter/mantle-admin-ui": "0.1.3",
+    "@aotter/mantle-bun": "0.1.3",
+    "@aotter/mantle-auth": "0.1.3",
+    "@aotter/mantle-web": "0.1.3",
+    "@aotter/mantle-cloudflare": "0.1.3",
+    "@aotter/mantle-vercel": "0.1.3"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -144,13 +144,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.3-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.6",
-    "@aotter/mantle-auth": "0.1.3-alpha.6",
-    "@aotter/mantle-bun": "0.1.3-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.6",
-    "@aotter/mantle-web": "0.1.3-alpha.6",
-    "@aotter/mantle-vercel": "0.1.3-alpha.6"
+    "@aotter/mantle-admin-ui": "0.1.3",
+    "@aotter/mantle-admin": "0.1.3",
+    "@aotter/mantle-auth": "0.1.3",
+    "@aotter/mantle-bun": "0.1.3",
+    "@aotter/mantle-cloudflare": "0.1.3",
+    "@aotter/mantle-vercel": "0.1.3",
+    "@aotter/mantle-web": "0.1.3"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -75,7 +75,11 @@ codex plugin marketplace add aotter/mantle
 codex plugin add mantle@mantle
 ```
 
-Then follow the install skill to the CLI and handbook. After packages are
+Read the path printed by the installer (for project-local Codex,
+`.agents/skills/install/SKILL.md`). Only the selected brief is installed, not
+the SDK or handbook. After choosing and installing an exact SDK version, read
+`node_modules/@aotter/mantle/skills/install/SKILL.md` and its embedded docs;
+that package supersedes the bootstrap Git-ref instructions. After packages are
 installed, `mantle skills` projects the installed package's own skills into the
 project, and `mantle skills --check` fails on drift.
 

package/skills/develop/SKILL.md

@@ -17,8 +17,9 @@ docs govern runtime/API behavior.
 ## First Read
 
 1. `package.json` for the installed `@aotter/mantle*` versions.
-2. `manifests/site.yaml`, the active adapter config (`wrangler.jsonc`), and
-   the Worker entry. Custom Auth lives in that entry's `createAuth` factory.
+2. The manifest directory selected by the project scripts, the actual host
+   entry and adapter config (for example `wrangler.jsonc` on Cloudflare).
+   Read custom Auth construction there when present.
 3. Optional local context: `.mantle/plugins.json`, `.mantle/plugins.lock.json`,
    and `.mantle/recipes/`. Legacy launch/handoff files are context only.
 4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
@@ -75,6 +76,22 @@ Do not invent manifest kinds such as `Form`, `Feature`, `Workflow`, or
 `Membership`. Compose those from the four atoms plus TypeScript only where
 the atoms cannot express the behavior.
 
+## Choose the manifest feature first
+
+Read installed `docs/handbook/reference/features.md` to map the requested
+behavior to fields before adding handlers or a custom UI. For host-only reads,
+`surface: internal` keeps a View out of REST/MCP/Admin while preserving its
+`requires` checks. Read `docs/handbook/guides/typed-queries.md` for generated
+View params/results, indexed entry reads, and their authorization boundary.
+Use `from` for portable typed projections; SQL is for queries needing native
+SQLite and produces `unknown` row types.
+
+For Admin labels, inputs, collection columns/tabs, reports or action buttons,
+read `docs/handbook/guides/admin-ui.md`. Prefer supported Schema/Procedure/View
+metadata and `uiSchema` before custom frontend code. These control the Admin
+console, not the visitor frontend. Regenerate and verify the actual console;
+never edit generated `public/_mantle/admin/` assets.
+
 ## Content Edits
 
 - Follow the actual frontend content source. Use Admin or Staff MCP for