@aotter/mantle 0.1.3-alpha.6 → 0.1.3

package/README.md

@@ -16,7 +16,7 @@ npx skills add aotter/mantle --skill install
 ```
 
 To depend on this package in an existing project, pin the exact version
-from `package.json` (currently `0.1.3-alpha.6`):
+from `package.json` (currently `0.1.3`):
 
 ```bash
 npm install @aotter/mantle

package/dist/cli/main.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export declare const MANTLE_OVERVIEW = "mantle \u2014 compile manifests into a RuntimePlan and typed binding\n\nOverview\n  Optional surfaces \u2014 take only what you need. Admin is opt-in. You can ship a\n  complete service with no Dev UI, no visitor frontend, and no extra packages.\n\n  Minimal \u2014 Spec + generate\n    validate + generate compile manifests into a sealed plan and typed binding.\n    Embed that binding in an existing host. No Admin, no visitor UI.\n\n  Runtime / adapter\n    Bind Runtime through an adapter (Cloudflare Worker, Bun, Vercel, or yours).\n    HTTP Views, MCP, and Auth work without Admin.\n    See docs/examples/host-minimal-worker or\n    node_modules/@aotter/mantle/docs/examples/host-minimal-worker.\n\n  Opt-in \u2014 Admin / Dev UI\n    Add @aotter/mantle-admin and @aotter/mantle-admin-ui only when humans need\n    a console. Then re-run generate, bind wrangler ASSETS, and open\n    /admin/sign-in (local email OTP via ConsoleEmailSender).\n    See docs/examples/host-local-admin-otp or\n    node_modules/@aotter/mantle/docs/examples/host-local-admin-otp.\n\n  Further (ask the subcommand for details)\n    skills          project version-matched agent instructions\n    emit-openapi    OpenAPI 3.1 from HTTP Triggers and Views\n    mantle-harness  measure indexes and live HTTP (separate binary)\n\nUsage: mantle <subcommand> [options]\n\nSubcommands:\n  generate       Compile manifests into a typed runtime binding\n  validate       Static manifest and handler-source validation\n  skills         Project version-matched Core skills\n  emit-openapi   Emit OpenAPI 3.1 from Triggers and Views\n\nDocumentation:\n  Handbook:      node_modules/@aotter/mantle/docs/handbook/ (or docs/handbook/)\n  Online:        https://mantle.tools/\n  Install skill: npx skills add aotter/mantle --skill install\n";
+export declare const MANTLE_OVERVIEW = "mantle \u2014 compile manifests into a RuntimePlan and typed binding\n\nOverview\n  Optional surfaces \u2014 take only what you need. Admin is opt-in. You can ship a\n  complete service with no Dev UI, no visitor frontend, and no extra packages.\n\n  Minimal \u2014 Spec + generate\n    validate + generate compile manifests into a sealed plan and typed binding.\n    Embed that binding in an existing host. No Admin, no visitor UI.\n\n  Runtime / adapter\n    Bind Runtime through an adapter (Cloudflare Worker, Bun, Vercel, or yours).\n    HTTP Views, MCP, and Auth work without Admin.\n    See docs/examples/host-minimal-worker or\n    node_modules/@aotter/mantle/docs/examples/host-minimal-worker.\n\n  Opt-in \u2014 Admin / Dev UI\n    Add @aotter/mantle-admin and @aotter/mantle-admin-ui only when humans need\n    a console. Then re-run generate, bind wrangler ASSETS, and open\n    /admin/sign-in (local email OTP via ConsoleEmailSender).\n    See docs/examples/host-local-admin-otp or\n    node_modules/@aotter/mantle/docs/examples/host-local-admin-otp.\n\n  Further (ask the subcommand for details)\n    skills          project version-matched agent instructions\n    emit-openapi    OpenAPI 3.1 from HTTP Triggers and Views\n    mantle-harness  measure indexes and live HTTP (separate binary)\n\nUsage: mantle <subcommand> [options]\n\nSubcommands:\n  generate       Compile manifests into a typed runtime binding\n  validate       Static manifest and handler-source validation\n  skills         Project version-matched Core skills\n  emit-openapi   Emit OpenAPI 3.1 from Triggers and Views\n\nDocumentation:\n  Start:         node_modules/@aotter/mantle/docs/handbook/start/overview.md\n  Features:      node_modules/@aotter/mantle/docs/handbook/reference/features.md\n  Admin UI:      node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md\n  Online:        https://mantle.tools/\n  Install skill: npx skills add aotter/mantle --skill install\n";
 //# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAgCA,eAAO,MAAM,eAAe,kxDAwC3B,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAgCA,eAAO,MAAM,eAAe,g7DA0C3B,CAAC"}

package/dist/cli/main.js

@@ -62,7 +62,9 @@ Subcommands:
   emit-openapi   Emit OpenAPI 3.1 from Triggers and Views
 
 Documentation:
-  Handbook:      node_modules/@aotter/mantle/docs/handbook/ (or docs/handbook/)
+  Start:         node_modules/@aotter/mantle/docs/handbook/start/overview.md
+  Features:      node_modules/@aotter/mantle/docs/handbook/reference/features.md
+  Admin UI:      node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md
   Online:        https://mantle.tools/
   Install skill: npx skills add aotter/mantle --skill install
 `;

package/dist/cli/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe;CAClC,CAAC,CAAC;QACC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9B;YACE,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;YACjD,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwC9B,CAAC;AAEF,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,KAAK,CAAC,mBAAmB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3G,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe;CAClC,CAAC,CAAC;QACC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9B;YACE,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;YACjD,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C9B,CAAC;AAEF,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,KAAK,CAAC,mBAAmB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3G,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/cli/skills.js

@@ -59,7 +59,7 @@ export async function runSkills(rawArgs) {
             return 1;
         }
         if (!check)
-            stdout.write(`Mantle skills projected: ${skills.join(", ")}.\n`);
+            stdout.write(`Mantle skills projected: ${skills.join(", ")}.\nRead .agents/skills/mantle-develop/SKILL.md and node_modules/@aotter/mantle/docs/handbook/start/overview.md.\n`);
         return 0;
     }
     catch (error) {

package/dist/cli/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"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"}

package/docs/agent-prompts.md

@@ -8,11 +8,11 @@ npx skills add aotter/mantle --skill install
 
 Copy one block into a coding agent after that skill is present. Paths below
 are relative to the Mantle docs root: `node_modules/@aotter/mantle/docs/`
-after `@aotter/mantle` is installed, or `docs/` in the installed agent plugin.
+after `@aotter/mantle` is installed. A standalone `skills add` installation
+contains only the selected skill, not these docs.
 `npx --no-install mantle --help` is the layered CLI overview; it mirrors the
 authoring docs. A live `/mcp` catalog mirrors the Manifest → RuntimePlan, not
-the CLI. Interview first. Worker is the default host unless the user names
-ChatGPT Sites. There is no `mantle create`. Empty `generate` fails until
+the CLI. Resolve only missing requirements first; do not assume a host. There is no `mantle create`. Empty `generate` fails until
 manifests exist. Admin is opt-in.
 
 ### Interview then build
@@ -21,8 +21,9 @@ manifests exist. Admin is opt-in.
 Interview me about the service: host, who uses it, whether humans need a
 Dev UI, and whether we only embed Spec/Runtime. If the install skill is
 missing, run npx skills add aotter/mantle --skill install. Read the
-install skill and npx --no-install mantle --help, then
-handbook/start/project-and-cli.md.
+installer-reported skill, choose and install an exact SDK version, then read
+its embedded skills/install/SKILL.md, run npx --no-install mantle --help, and
+read handbook/start/overview.md.
 Use examples/README.md as the examples index; copy builtin-* Manifests only
 (not cf-primitives-*). Implement locally first. Take only the surfaces we
 chose. For Spec-only use, skip Runtime and code generation. For a Worker

package/docs/consumer-onboarding-audit.md

@@ -0,0 +1,65 @@
+# Consumer onboarding audit for 0.1.3
+
+Scope: source skill install → pinned npm package → CLI → generated skills and
+handbook → application manifest and Admin customization. This is maintainer
+evidence, not a release announcement. Baseline: develop `b90cebbd`, package
+version `0.1.3-alpha.5`; the package version alone does not identify unreleased
+commits on develop. Tracking: [#1042](https://github.com/aotter/mantle/issues/1042).
+
+## Clean source install
+
+Executed in an empty temporary directory:
+
+```sh
+npx --yes skills add aotter/mantle --skill install --agent codex --yes
+```
+
+Observed output: repository cloned, **7 skills found**, **1 selected**, copied
+to `./.agents/skills/install`. `skills-lock.json` records source `aotter/mantle`,
+source type `github`, and source path `skills/install/SKILL.md`. The installed
+file's hash in that lock was
+`8a6fd26aea97ae8bdf3e05fef22196c247b3f95aa049204a6ac51259d87e4e29`.
+No SDK, handbook or application is installed by that command. The explicit
+Codex and noninteractive flags make the audited destination reproducible;
+other selected agents/global scope can use another destination.
+
+This source install follows the repository's default ref. It does not test the
+unreleased edits in this PR or establish an npm version. The packed-consumer
+check below tests this branch's shipped instructions separately.
+
+## White-box path and fixes
+
+| Stage / owner | Finding before this change | Correction |
+|---|---|---|
+| README → external skills installer | Prompt told the agent to read `skills/install/SKILL.md` and `docs/agent-prompts.md`, neither installed there. | Read the installer-reported destination, then the installed SDK's embedded docs. |
+| `skills/install/SKILL.md` | Bootstrap Git instructions did not explicitly hand off to the installed package's own install skill; `docs/...` root was implicit. Host interview was repeated. | Explicit package-root resolution and version authority; ask only for missing requirements. |
+| Install → CLI | It was possible to try the local CLI before installing Core; `generate` in an empty directory fails rather than creating a project. | Spell out package installation before CLI and manifest authoring before generation. |
+| Quickstart versions | Floating `latest` dependency examples contradicted exact-pin advice. | Resolve the requested channel once and save exact Mantle versions before the first build. |
+| `mantle skills` | Correctly projected four project skills, but success output did not tell the agent what to read next. | Print the projected develop skill and installed handbook entry. Document overwrite, drift and opt-in behavior. |
+| `sync-package-docs.mjs` → npm `files` | Docs and all seven skills already shipped; presence checks did not protect the new entry paths or exercise projection from the tarball. | Assert handbook/skill files and byte-identical `.agents`/`.claude` projection in the existing packed-consumer check. |
+| View concepts → grammar/runtime | Concepts denied internal Views and recommended SQL for every new View; reference `surface` table omitted `internal`. SQL admission text was stale. | Match implemented surfaces, typed declarative reads, SQLite admission sandbox and native-dialect limits. |
+| Manifest reference | View's allowed spec keys omitted `cache`; Schema list-column prose omitted native columns. | Reconcile with parser and Admin UI checker. |
+| Plugin/update skills | Assumed conventional source paths, missed regeneration after plugin manifest edits, and treated every View as publicly callable. | Use actual project paths, regenerate the plan, verify the declared surface and distinguish stable index from target prerelease docs. |
+| Feature discovery | No task-to-manifest capability map or usable human entry; reference was buried after host-specific sections. | Add overview, capability table and task guides; move reference before host guides without breaking existing URLs. |
+| Typed query discovery | APIs existed but lacked a complete internal-View calling example or clear reader authorization distinction. | Explain generated params/results, runtime `result` versus REST `data`, SQL `unknown`, indexed reader limits and plan-based emission. |
+| Admin requests → theme/develop skills | Theme skill targeted visitor source; no routing from an Admin request to manifest-controlled presentation. | Route to Admin guide, with Schema/View/Procedure rendering table and supported customization ceiling. |
+| Auth operations | Store-bound session cache behavior existed in code/ADR but was missing from the handbook. | Explain store identity, preparation order and KV propagation limits. |
+
+## Verification and regression coverage
+
+- `packages/mantle-spec/test/handbook-contract.test.ts`: complete handbook YAML
+  examples parse and validate; navigation covers pages; relative links resolve.
+- `packages/mantle/test/cli/generate.test.ts`: extracts the new internal-View
+  YAML and TypeScript directly from the handbook, generates bindings and runs
+  strict TypeScript checking on the real example.
+- CLI surface/projection tests assert the concrete next-read destinations;
+  existing drift checks verify `--check` is read-only.
+- `scripts/check-optional-packages.mjs`: packs and installs the actual Core
+  tarball, checks embedded entry pages/skills, runs `skills` and `skills --check`,
+  and compares each project projection byte-for-byte with the installed package.
+- Repository gate: `pnpm check`. Exact execution results and any environment
+  limitations are recorded in the PR, rather than frozen as a future guarantee.
+
+No npm publish, tag, deployment or grammar change is part of this audit. Source
+skill consumers receive the corrections only once they reach the installed Git
+ref; npm consumers receive them only in a package built from the corrected tree.

package/docs/handbook/cloudflare/authentication.md

@@ -84,6 +84,22 @@ The staff role is re-read from D1 on every protected REST and MCP call; a revoke
 
 MCP tokens are session-bound: signing out of Admin ends MCP access. See [MCP and agents](../concepts/mcp-and-agents.md).
 
+## Session cache and database replacement
+
+When optional session caching is enabled, the cache is derived from the
+canonical store, not a second identity authority. Auth prefixes keys with
+`better-auth:<store-instance-id>:`. Preparing a new store gives it a distinct
+identity, so reusing the same KV namespace after replacing D1 cannot resurrect
+the previous store's cached sessions. Ordinary preparation of the same store
+preserves its identity.
+
+Custom low-level Auth composition must prepare the Mantle store before cached
+Auth operations; do not construct cache keys or seed the identity yourself.
+OTP verification remains in the primary database and rate limiting remains
+isolate-local. Revocation/user-update cache invalidation still follows KV
+propagation; the namespace change is isolation across stores, not a promise of
+instant global invalidation. See the [Auth decision](../../adr/0014-auth-better-auth-and-multi-tenant-mcp.md).
+
 ## Better Auth configuration
 
 `createAuth()` owns the Worker lifecycle, Admin metadata, sender integration,

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

@@ -20,7 +20,7 @@ A tool name is derived from a manifest name by `mcpToolNameSegment`: lowercased,
 
 | Tool | Produced by | Surface |
 |---|---|---|
-| `query_view_<segment>` | Any View | The View's own `surface` |
+| `query_view_<segment>` | Public or staff View (never internal) | The View's own `surface` |
 | `create_draft_<schema>`, `update_draft_<schema>` | A Schema with `lifecycle: publishing` | Staff |
 | `create_record_<schema>`, `update_record_<schema>` | A Schema with `lifecycle: operational` | Staff |
 | `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry` | Present when an applicable Schema exists | Staff |

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

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

package/docs/handbook/concepts/views.md

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

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

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

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

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