@aotter/mantle 0.1.3-alpha.6 → 0.1.4

package/docs/handbook/navigation.json

@@ -4,10 +4,19 @@
     {
       "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": "When the host is ChatGPT Sites", "link": "/chatgpt-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" }
       ]
     },
     {
@@ -22,12 +31,27 @@
         { "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": [
-        { "text": "Get started", "link": "/sites/index" },
-        { "text": "Host reference", "link": "/sites/host-reference" },
-        { "text": "Equipment checkout and external APIs", "link": "/sites/equipment-checkout" },
+        { "text": "Get started", "link": "/chatgpt-sites/index" },
+        { "text": "Host reference", "link": "/chatgpt-sites/host-reference" },
+        { "text": "Equipment checkout and external APIs", "link": "/chatgpt-sites/equipment-checkout" },
         { "text": "Earlier guide URL", "link": "/cloudflare/chatgpt-sites" }
       ]
     },
@@ -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,79 @@ 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.4 — 2026-09-24
+
+0.1.4 repairs the published consumer path without changing the Manifest
+grammar. Pin every selected `@aotter/mantle*` package to `0.1.4`, refresh the
+lockfile, then rerun `mantle generate` and `mantle skills` with their `--check`
+commands. Read the handbook and skills from that installed version.
+
+**ChatGPT Sites reference.** The 0.1.3 reference omitted the
+`_mantle_boot_state.store_instance_id` column required by the runtime, which
+could make deployed runtime routes return 500. The reference now adds the
+append-only `drizzle/0003_store_instance_id.sql` migration. If your project
+was copied from that reference, carry the new migration forward and apply
+pending D1 migrations **before** deploying updated code; do not edit a
+migration already applied. Repeated builds now clear `dist` so removed SQL
+files cannot remain in the deployment artifact. The Sites guide also shows
+how to mount an HTTP Trigger, identifies the browser and MCP owner workflows,
+and names its integration chapter `docs/handbook/chatgpt-sites/`.
+
+**Agent installation.** `npx skills add aotter/mantle` installs the small
+`mantle` bootstrap skill; the installed npm package supplies version-matched
+instructions and docs. The skill now checks the application's installed
+version before reading them. Superseded Starter decisions are marked as
+history: no `mantle-starters/v0.1.4` tag or `mantle create` command is needed
+to author a new application.
+
+## 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
@@ -54,7 +123,7 @@ See [HTTP, MCP, CLI and packages](../reference/surface.md) for the full list.
 D1 and assets bindings, Better Auth 1.7 (social providers, email OTP, magic
 link, passkey), Admin, MCP, Web and R2 media uploads. The Bun and Vercel
 adapters are experimental, cover public Views and HTTP Triggers only, and leave
-authentication and CSRF to the host. [ChatGPT Sites](../sites/index.md) is a
+authentication and CSRF to the host. [ChatGPT Sites](../chatgpt-sites/index.md) is a
 first-class integration with a runnable reference.
 
 **Agents.** `mantle skills` projects the installed package's skills into

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](../chatgpt-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,10 +5,10 @@ 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
+npx skills add aotter/mantle
 ```
 
 ## You own the project
@@ -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
 
@@ -96,14 +96,14 @@ Run the harness after any change to a Schema index, View filter or ordering, or
 
 ## Connecting an agent
 
-`mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `install`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
+`mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `mantle`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
 
-Install the plugin bundle in the agent host. Cold start uses
+Install the bootstrap skill in the agent host. Cold start uses
 the install skill; an already-installed project pins packages from `package.json`:
 
 ```sh
 # Canonical
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 
 # Claude Code — two separate prompts
 /plugin marketplace add aotter/mantle
@@ -137,4 +137,4 @@ The projected `develop` skill tells the agent to read `package.json` for the ins
 - [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
 - [`packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts)
 - [`packages/mantle-spec/src/infrastructure/cli/MantleCli.ts`](../../../packages/mantle-spec/src/infrastructure/cli/MantleCli.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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
@@ -169,9 +174,6 @@ curl -i http://127.0.0.1:8787/mcp/staff
 
 `generate` fails on missing or invalid manifests and never creates a project, a default Schema or a home route. `mantle generate --check` reports stale output without writing. The reference keeps `.mantle/`, `.agents/` and `.claude/` out of git and regenerates them in `check`; see [Project layout and the CLI loop](./project-and-cli.md).
 
-> **npm and optional peers**
-> A cold npm install can fail with `ERESOLVE` when an Auth peer selects a different optional `@libsql/client` than this snapshot declares. If that happens, pin `@libsql/client` in `overrides` to the range in this checkout's `package.json` and rerun `npm install`. Do not use `--force`. Commit the lockfile and use `npm ci` afterwards.
-
 ## Next steps
 
 - [Quickstart: local Admin](./quickstart-admin.md) — opt-in Dev UI: ASSETS, prebuilt Admin, email OTP.

package/docs/release-process.md

@@ -110,10 +110,11 @@ dist-tag DELETE only added failure and re-run state, and Actions
    ```
 
    Leave the consumer cold-start entry **untagged**: `npx skills add
-   aotter/mantle --skill install`, `/plugin marketplace add aotter/mantle`,
+   aotter/mantle`, `/plugin marketplace add aotter/mantle`,
    `codex plugin marketplace add aotter/mantle` and the plugin-manifest
    descriptions carry no `@v…` / `--ref`. Untagged resolves to `main`, which
-   only moves at a release, so it is always the latest published version
+   normally moves at a release but may contain a source-only hotfix; the
+   installed npm package remains the version authority
    (#995, #998). Only "installed version" statements such as
    `(currently \`X.Y.Z\`)` are bumped.
 

package/docs/sealed-pipeline-ownership.md

@@ -65,7 +65,7 @@ release use `docs/examples/host-minimal-worker` from the same reviewed commit.
 Private consumers can still run the exact-tarball checker in their own repos;
 public Core PRs receive no cross-repository credentials:
 
-| Consumer | Revision | Gate authority | Manifest paths |
+| Historical consumer | Revision | Gate at the time | Manifest paths |
 |---|---|---|---|
 | `aotter/mantle-starters` | `157e8f49e1e25ae1c52c0115f0dd9e8b6017ef0e` | Core CI + release | `blank/manifests/site.yaml`; `overlays/{community,intake,presence,publication,reservation,transaction}/manifests/site.yaml`; `recipes/typed-web/manifests/site.yaml` |
 | `aotter/mantle-landing` | `4381354dd25d5d94f4096cf3e55a4cb9eecbf3ad` | Landing CI + Core release | `manifests/site.yaml` |