@aotter/mantle 0.1.3-alpha.5 → 0.1.3

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/performance-harness.md

@@ -55,6 +55,13 @@ data-field predicate/order that does not use a declared Schema index.
 Projection alone does not require an index. `mantle validate` remains a pure
 correctness check; no performance grammar or manifest atom was added.
 
+The fixture follows each Schema lifecycle: operational rows are immediately
+published, while publishing Schemas contain both draft and published rows. The
+harness deliberately does not run `ANALYZE` or `PRAGMA optimize`, so it cannot
+turn an unprepared production plan into a local pass. This is a conservative
+SQLite preflight, not proof of D1 rows-read, Worker CPU, or IndexedDB behavior;
+measure those on the target backend before making a performance claim.
+
 Use the machine report in CI. It includes the compiled SQL and parameters,
 query-plan details, named indexes, scan/sort flags, result count, SQLite
 version, fixture row count, and required-failure summary.

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.5`. 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.5",
+  "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.5",
-    "@aotter/mantle-spec": "0.1.3-alpha.5"
+    "@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.5",
-    "@aotter/mantle-auth": "0.1.3-alpha.5",
-    "@aotter/mantle-bun": "0.1.3-alpha.5",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.5",
-    "@aotter/mantle-vercel": "0.1.3-alpha.5",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.5",
-    "@aotter/mantle-web": "0.1.3-alpha.5"
+    "@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-ui": "0.1.3-alpha.5",
-    "@aotter/mantle-auth": "0.1.3-alpha.5",
-    "@aotter/mantle-bun": "0.1.3-alpha.5",
-    "@aotter/mantle-admin": "0.1.3-alpha.5",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.5",
-    "@aotter/mantle-web": "0.1.3-alpha.5",
-    "@aotter/mantle-vercel": "0.1.3-alpha.5"
+    "@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

package/skills/install/SKILL.md

@@ -16,6 +16,23 @@ provider configuration. There is no Starter/type picker or `mantle create`.
 Do not use the SDK checkout as the application, copy an old Starter tree, or
 turn `generate` into implicit scaffolding.
 
+## Locate the version-matched instructions
+
+`npx skills add aotter/mantle --skill install` installs this brief, not the SDK,
+a project, or the handbook. Read the path printed by the installer (Codex's
+project-local path is `.agents/skills/install/SKILL.md`); `metadata.sourcePath`
+is repository provenance, not a consumer path. A repository install follows
+the selected Git ref and does not pin an npm release.
+
+After selecting the host and exact version, install `@aotter/mantle` locally
+with the selected optional packages. All `docs/...` paths below then mean
+`node_modules/@aotter/mantle/docs/...`; package skills are under
+`node_modules/@aotter/mantle/skills/`. Read that package's
+`skills/install/SKILL.md` before authoring: it supersedes this bootstrap copy.
+If the user requested a prerelease, resolve that channel explicitly; `latest`
+need not contain prerelease features. Never mix versioned npm code with branch
+docs. No local CLI exists until the package is installed.
+
 ## New application
 
 1. Determine the actual host and required surfaces from the request. Reuse an
@@ -30,8 +47,9 @@ turn `generate` into implicit scaffolding.
    version. Install only the adapter/optional packages the application needs.
    If a global scope registry overrides public npmjs, use a project-owned
    `.npmrc` with `@aotter:registry=https://registry.npmjs.org/`.
-3. Interview the human for host and required surfaces. Do not assume Admin,
-   public HTML or Cloudflare. Scale:
+3. Use the host and surfaces already established in step 1; ask only for
+   information still missing. Read `docs/handbook/start/overview.md` and
+   `docs/handbook/reference/features.md`, then select the matching path:
    - Spec + generate / embed Runtime — `docs/handbook/start/project-and-cli.md`.
    - Adapter without Admin — `docs/examples/host-minimal-worker/`.
    - Opt-in Admin / Dev UI — only when a human needs a console: interview
@@ -108,7 +126,9 @@ a bundle comparison command.
 
 ## Ship and report
 
-When deployment is requested, follow the installed provision skill and the
+When deployment is requested, read
+`node_modules/@aotter/mantle/skills/provision/SKILL.md` (not projected by
+`mantle skills`) and follow that version-matched skill and the
 observed host configuration. Legacy Landing remains a pre-stable product; it
 is not a launch dependency for new Core projects.
 

package/skills/plugin/SKILL.md

@@ -50,11 +50,17 @@ stop and ask for the recipe instead of guessing.
 ## First Read
 
 1. `package.json` for Mantle version and adapter package.
-2. `manifests/site.yaml` for current atom names and route/tool collisions.
-3. `src/mantle/config.ts` and `src/mantle/handlers/` for registered handlers, templates, and optional ports. Older projects may use `src/mantleConfig.ts`.
+2. The manifest directory selected by project scripts for current atom names
+   and route/tool collisions.
+3. The actual host entry and its handler, template and port registrations;
+   `src/mantle/config.ts` and `src/mantle/handlers/` are conventions, not required paths.
 4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
 5. `.mantle/launch-state.json` only as context, not as plugin authority.
 
+Read version-matched contracts under `node_modules/@aotter/mantle/docs/`,
+starting with `handbook/reference/features.md`. Plugin recipes cannot override
+the installed grammar.
+
 ## Plan First
 
 Before applying any plugin, produce a plan:
@@ -100,14 +106,20 @@ and report the dependency instead of deleting through it.
 
 ## Verify
 
+Use the project's validation and typecheck scripts when present. Regenerate
+the plan after manifest changes before probing the running host:
+
 ```bash
-pnpm validate
-pnpm typecheck
+pnpm exec mantle validate
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+# Run the project's TypeScript check and restart its local server.
 ```
 
 Then verify the plugin's declared surfaces:
 
-- `GET /api/views/<name>` for View reads;
+- public Views via `GET /api/views/<name>`, staff Views via authenticated
+  Admin/staff MCP, and internal Views through the host binding;
 - HTTP Trigger path for public writes;
 - Staff/Public MCP `tools/list` for MCP Trigger or Schema-derived tools;
 - adapter resource presence when the plugin requires optional ports.

package/skills/theme/SKILL.md

@@ -13,13 +13,20 @@ metadata:
 Theme work is project-owned source editing. Use the actual frontend and its
 tokens/recipes; Core does not install a default home page or UI tree.
 
+For requests to change the Admin console, first read installed
+`node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md` and use the
+develop skill. Labels, widgets, list columns, filters and actions may already
+be manifest-driven. Visitor CSS does not style the prebuilt Admin SPA, and
+`uiSchema` does not accept arbitrary CSS, components or layout keys.
+
 ## First Read
 
 1. `.mantle/handoff.md` and `.mantle/recipes/` if present.
 2. `styles/`, `components/`, `src/web/`, `src/theme*`, and UI-library config
    if present.
 3. A vendored UI palette's manifest and license, if present.
-4. `manifests/site.yaml` to understand which content shape drives the public UI.
+4. The manifest directory selected by project scripts to understand which
+   content shape drives the public UI.
 
 ## Ownership
 

package/skills/update/SKILL.md

@@ -17,8 +17,10 @@ skill remains the version-matched upgrade workflow, not a replacement CLI.
 1. Inspect git status, package.json, lockfile, actual project scripts and
    installed versions. Preserve unrelated local changes. Read plugin locks
    and legacy `.mantle` metadata if present; they are context, not required.
-2. Select an explicit target release and read its entry in
-   `docs/handbook/releases/index.md` plus that version's GitHub release notes.
+2. Select an explicit target release and read that version's GitHub release
+   notes. Installed docs live under `node_modules/@aotter/mantle/docs/`;
+   `handbook/releases/index.md` is a stable-release index, so a prerelease
+   need not appear there. Do not use the old package's docs as the new API contract.
    Do not resolve new Starter refs or compare the project to a baseline
    template.
 3. Update only selected `@aotter/mantle*` dependencies to the same exact target
@@ -39,6 +41,9 @@ pnpm exec mantle skills --check
 pnpm exec mantle validate
 ```
 
+Read the refreshed `mantle-develop` skill and the upgraded package's embedded
+docs before continuing application edits.
+
 Start the local application and test its actual routes, including configured
 auth behavior. Review the final source/lockfile/generated diff; unexpected
 provider or user-source changes block completion. Provider credentials must