@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

package/docs/handbook/reference/view.md

@@ -0,0 +1,256 @@
+---
+description: View field reference — declarative and SQL forms, filter AST, params, pagination, REST and MCP surfaces, and every diagnostic they raise.
+---
+# 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).
+
+## Fields
+
+| Field | Type | Required | Default | Rules |
+|---|---|---|---|---|
+| `title` | LocalizedText | no | Title-Cased `metadata.name` | Admin report label. Non-empty string or locale map. |
+| `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). |
+| `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). |
+| `fields` | `string[]` | no | every column | `from` form only. Projection. Not shape-validated by the parser. |
+| `orderBy` | `{ field, direction? }[]` | no | `[]` | `from` form only. `direction` defaults to `asc`. |
+| `limit` | number | no | 50 at runtime | `from` and `sql`. Not shape-validated by the parser; clamped at request time. |
+| `params` | JSON Schema | no | — | `type: object` with `properties`. Reserved: `page`, `show`, `cursor`. |
+
+`from` counts as present when it is a non-empty string; `sql` when it is non-empty after trimming. Declaring both, or neither, is `INVALID_MANIFEST_ENVELOPE` at `/spec` with the message *View.spec requires exactly one of from or sql*. Combining `sql` with `filter`, `fields` or `orderBy` is rejected the same way at `/spec/<key>`.
+
+## Declarative example
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: my-support-requests
+spec:
+  title: { en: My support requests, "zh-TW": 我的客服請求 }
+  surface: public
+  from: support-requests
+  requires:
+    auth:
+      all: [ctx.user]
+  fields: [id, ticketNumber, subject, requestStatus, submittedAt]
+  filter:
+    and:
+      - eq: { field: submittedBy, value: { "$ctx.user": "id" } }
+      - eq: { field: requestStatus, value: { $param: requestStatus } }
+  orderBy:
+    - { field: submittedAt, direction: desc }
+  limit: 100
+  params:
+    type: object
+    required: [requestStatus]
+    properties:
+      requestStatus: { type: string, enum: [open, waiting, closed] }
+```
+
+The Schema this reads must index `submittedBy` as the leftmost field of some tuple, otherwise the identity filter is rejected. See [Schema indexes](./schema.md#indexes).
+
+For caller-independent published data, a View may opt its anonymous REST response into the deployment cache:
+
+```yaml
+spec:
+  surface: public
+  from: published-notes
+  cache: { sharedMaxAge: 3600 }
+```
+
+This emits `Cache-Control: public, max-age=0, s-maxage=3600` only when the request has no cookie or authorization header and the Cloudflare Worker has a valid `cacheScope`. MCP, WebMCP, staff, guarded, SQL and operational-schema reads remain uncached. Invalid combinations fail with `VIEW_CACHE_INVALID`.
+
+## SQL example
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: order-lines-by-status
+spec:
+  title: Order lines by status
+  surface: staff
+  sql: |
+    SELECT o._mantle_id AS orderId,
+           o.orderNumber AS orderNumber,
+           json_extract(line.value, '$.sku') AS sku,
+           json_extract(line.value, '$.quantity') AS quantity
+    FROM orders AS o
+    JOIN json_each(o.lines) AS line
+    WHERE o.orderStatus = :orderStatus
+    ORDER BY o.orderNumber ASC
+  params:
+    type: object
+    required: [orderStatus]
+    properties:
+      orderStatus: { type: string, enum: [paid, shipped, cancelled] }
+  limit: 200
+  uiSchema:
+    list:
+      columns: [orderNumber, sku, quantity]
+      searchFields: [orderNumber, sku]
+      filterFields: [sku]
+```
+
+## Filter AST
+
+`filter` is a tree. Every node is an object with **exactly one** key: a comparison operator, or `and` / `or`.
+
+| Key | Shape | Rules |
+|---|---|---|
+| `eq`, `gt`, `gte`, `lt`, `lte` | `{ field, value }` | Only those two keys. `field` is a non-empty string. `value` must be present; `null` is a legal value. |
+| `and`, `or` | array of nodes | Non-empty. Nests to any depth. |
+
+Any other key, a node with zero or several keys, an array node, or an empty `and` / `or` is `INVALID_MANIFEST_ENVELOPE` at the node's pointer.
+
+### Value forms
+
+| Form | Written as | Rules |
+|---|---|---|
+| Literal | `value: published` | Any JSON scalar, including `null`. Compared as written. |
+| Param reference | `value: { $param: locale }` | The name must be declared under `params.properties` (`VIEW_FILTER_PARAM_REF_UNKNOWN`, also raised when no `params` is declared at all or the name is empty) and listed in `params.required` (`VIEW_FILTER_PARAM_REF_NOT_REQUIRED`). |
+| Caller identity | `value: { "$ctx.user": "id" }` | The sentinel is closed: exactly one key, the literal string `id`, and only under `eq`. Anything else is `VIEW_FILTER_CTX_USER_REF_INVALID`. |
+
+The identity sentinel carries two further graph-level obligations, checked once `from` resolves:
+
+| Rule | Diagnostic |
+|---|---|
+| The View declares `ctx.user` in `requires.auth.all`. | `VIEW_FILTER_CTX_USER_REF_REQUIRES_AUTH` at `/spec/requires/auth/all` |
+| The compared field is the leftmost field of some `uniqueIndexes` or `indexes` tuple on the source Schema. | `VIEW_FILTER_CTX_USER_REF_REQUIRES_INDEX` |
+
+Provider claims and platform identities are deliberately out of reach; `id` is the only bindable identity value.
+
+### Graph-level field checks
+
+For a `from` View, the valid field names are the top-level keys of the Schema's `properties` plus the [reserved entry columns](./schema.md#reserved-entry-columns). Unknown names are rejected per site:
+
+| Location | Diagnostic |
+|---|---|
+| `filter.<op>.field` | `VIEW_FILTER_FIELD_NOT_IN_SCHEMA` |
+| `fields[i]`, `orderBy[i].field` | `VIEW_FIELD_NOT_IN_SCHEMA` |
+| `uiSchema.list.<key>[i]` | `VIEW_UI_INVALID` |
+| `from` itself | `VIEW_FROM_UNKNOWN_SCHEMA` (no further field checks run) |
+
+None of these run for a `sql` View — its output columns are whatever the `SELECT` produces.
+
+## `sql`
+
+One statement, read-only, compiled and bound by the runtime.
+
+| Rule | Effect |
+|---|---|
+| The trimmed text matches `/^select\b/i` and contains no `;`. | Otherwise `INVALID_MANIFEST_ENVELOPE` at `/spec/sql`: `View.spec.sql must be one SELECT statement without a semicolon`. |
+| Every `:name` occurrence is declared in `params.properties`. | `VIEW_FILTER_PARAM_REF_UNKNOWN` |
+| Every `:name` occurrence is listed in `params.required`. | `VIEW_FILTER_PARAM_REF_NOT_REQUIRED` |
+| `filter`, `fields` and `orderBy` are absent. | `INVALID_MANIFEST_ENVELOPE` at `/spec/<key>` |
+| Tables are Schema names. | Each Schema is exposed as a logical table reconciled at boot. Names containing `-` must be double-quoted: `FROM "post-translations"`. |
+
+Bound params are passed as positional values; caller input is never interpolated into the statement. SQLite JSON functions are available, so `json_each` and `json_extract` can unnest and project array or object members of `data` — the SQL example above does both.
+
+> **Warning**
+> `sql` Views are native SQLite. Static validation never executes the statement, so a syntax or column error surfaces only when the View runs. On a storage adapter that does not support the native dialect the View fails at prepare time with `VIEW_DIALECT_UNSUPPORTED`, naming the dialects that adapter does support.
+
+## `params`
+
+`params` declares the caller-supplied query shape and is walked by the [JSON Schema subset](./schema.md#json-schema-subset) validator.
+
+| Rule | Diagnostic |
+|---|---|
+| A non-array object. | `VIEW_PARAMS_INVALID_SHAPE` at `/spec/params` |
+| `type: "object"`. | `VIEW_PARAMS_INVALID_SHAPE` at `/spec/params/type` |
+| `properties` is declared and is an object. | `VIEW_PARAMS_INVALID_SHAPE` at `/spec/params/properties` |
+| No property named `page`, `show` or `cursor`. | `VIEW_PARAMS_RESERVED_NAME` |
+
+The runtime owns those three names for pagination, which is why they cannot be redeclared. Rename the domain param (`pageSize`, `showArchived`).
+
+## `orderBy`, `fields` and `limit`
+
+`orderBy` is an array of objects accepting only `field` and `direction`. A non-array value, a non-object entry, a missing or empty `field`, or a `direction` other than `asc` / `desc` is `VIEW_ORDERBY_INVALID` at the offending pointer; an unrecognized key inside an entry is `INVALID_MANIFEST_ENVELOPE`.
+
+`fields` and `limit` receive **no shape validation in the parser**. A `fields` value that is not an array of strings, or a `limit` that is not a number, is not reported as a diagnostic — it fails later, at graph validation or at request time. Declare them as documented.
+
+`limit` is a per-View cap, and the runtime clamps around it on every call:
+
+| Input | Result |
+|---|---|
+| `limit` missing, non-numeric, non-finite or `<= 0` | Cap is 50. |
+| `limit` valid | Cap is `min(floor(limit), 500)`. 500 is the hard ceiling for any single round-trip. |
+| `?show=` missing or not a positive finite number | Page size is the cap. |
+| `?show=` valid | Page size is `min(floor(show), cap)`. |
+| `?page=` missing or below 1 | Page 1. |
+
+## `uiSchema.list`
+
+Admin presentation for `surface: staff` Views. Declaring `uiSchema` on a public View is `VIEW_UI_INVALID`, as is any root key other than `list` or any key inside `list` other than the three below.
+
+| Key | Meaning |
+|---|---|
+| `columns` | Ordered columns for the Admin report table and the default CSV column set. |
+| `searchFields` | Output fields the Admin substring search box covers. |
+| `filterFields` | Output fields offered as exact-match filters (`?filter.<field>=`). |
+
+Each is an array of non-empty strings with no duplicates within the key. The characters `"`, `\` and NUL are rejected in a field name. The names are **View output field names** — SQL aliases for a `sql` View; for a `from` View they are additionally checked against the Schema's properties plus reserved columns.
+
+Admin applies search and filters before pagination, rejecting a search term or filter value longer than 200 characters and any `filter.<field>` key that is not a declared `filterFields` entry. `GET /admin/api/views/<name>/export` streams the same query as CSV covering every matching row, not only the visible page; its columns come from `uiSchema.list.columns`, falling back to `spec.fields` and then to the union of keys in the returned rows.
+
+## Surfaces
+
+| `surface` | REST | MCP tool | Admin |
+|---|---|---|---|
+| `public` | `GET /api/views/<name>`, plus a catalog at `GET /api/views` | `query_view_<segment>` on `/mcp` | Also mounted at `GET /admin/api/views/<name>` and `/export` behind the staff gate |
+| `staff` | `GET /admin/api/views/<name>` and `/admin/api/views/<name>/export` — not mounted publicly | `query_view_<segment>` on `/mcp/staff` | Report sidebar |
+
+`<segment>` is `metadata.name` lower-cased with `-` replaced by `_`. Two Views that mangle to the same segment collide with `MCP_TOOL_NAME_COLLISION`. Admin also serves the manifest listing `GET /admin/api/views-manifest`. Surface choice is visibility, not authorization: `requires` still gates every call on both transports. See [Surfaces](./surface.md) and [MCP and agents](../concepts/mcp-and-agents.md).
+
+The MCP `inputSchema` is `params.properties` plus `page` and `show` as optional numbers, carrying `params.required` through unchanged; the tool is annotated `readOnlyHint: true`.
+
+## REST contract
+
+Pagination uses the two reserved knobs, `?page=` (1-indexed) and `?show=`. The response envelope is:
+
+```json
+{ "ok": true, "data": { "rows": [], "page": 1, "show": 20, "hasMore": true } }
+```
+
+`hasMore` is the lazy form — `rows.length === show`. There is no COUNT query and no `LIMIT n+1` probe, so a final page that exactly fills `show` reports `hasMore: true` and the next page comes back empty.
+
+A failure returns `{ ok: false, diagnostic }` with the diagnostic's mapped status. Static `requires.auth` runs before parameter validation, so an unauthorized caller never learns the parameter shape; a `guard` Procedure runs after validation and authorizes the whole query rather than filtering rows.
+
+### Param coercion
+
+Query strings arrive as text. The runtime coerces each declared param by its `type` before validating against `params`; MCP callers send typed JSON and skip this step.
+
+| Declared `type` | Coercion | Rejected when |
+|---|---|---|
+| `string`, or `type` omitted | Used as-is. | — |
+| `integer` | `parseInt(raw, 10)` | The round-trip does not equal the trimmed input, so `"1.5"` and `"1abc"` fail. |
+| `number` | `Number(raw)` | The result is not finite. |
+| `boolean` | `"true"` / `"false"` | Any other text. |
+| `enum` (with any of the above) | Coerced by `type` first, then checked for membership. | The coerced value is not in `enum`. |
+| anything else | — | Unsupported on the REST surface. |
+
+A missing required param or a failed coercion is `INPUT_VALIDATION_FAILED` (400). Unknown query keys are ignored.
+
+## Source
+
+- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
+- [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
+- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
+- [`packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
+- [`packages/mantle-spec/src/domain/service/McpToolNaming.ts`](../../../packages/mantle-spec/src/domain/service/McpToolNaming.ts)
+- [`packages/mantle-runtime/src/usecase/view/ExecuteViewUseCase.ts`](../../../packages/mantle-runtime/src/usecase/view/ExecuteViewUseCase.ts)
+- [`packages/mantle-runtime/src/domain/service/ViewParamCoercer.ts`](../../../packages/mantle-runtime/src/domain/service/ViewParamCoercer.ts)
+- [`packages/mantle-runtime/src/domain/service/Pagination.ts`](../../../packages/mantle-runtime/src/domain/service/Pagination.ts)
+- [`packages/mantle-runtime/src/domain/service/CallableCapabilityProjector.ts`](../../../packages/mantle-runtime/src/domain/service/CallableCapabilityProjector.ts)
+- [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
+- [`packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts`](../../../packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts)
+- [`packages/mantle-runtime/src/infrastructure/storage/SqliteMantleStorageAdapter.ts`](../../../packages/mantle-runtime/src/infrastructure/storage/SqliteMantleStorageAdapter.ts)
+- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
+- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
+- [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)

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

@@ -0,0 +1,122 @@
+---
+description: The files you own in a Mantle project, every mantle and mantle-harness command with its flags, the generated module, the daily check loop, and upgrade rules.
+---
+# Project layout and the CLI loop
+
+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. It is for engineers and coding agents working in an existing project.
+
+## You own the project
+
+Core supplies a manifest compiler and a runtime, not a project generator. Since [ADR-0021](../../../docs/adr/0021-retire-starter-scaffolding.md) there is no scaffolder: you write `package.json`, the manifests, the Worker entry, handlers, TypeScript and provider configuration. `mantle generate` compiles what exists; it never initializes a missing project or invents a default Schema, frontend or home route.
+
+```txt
+my-service/
+├── package.json              exact-pinned @aotter/mantle* + peers, scripts
+├── tsconfig.json             includes src/ and .mantle/generated/
+├── wrangler.jsonc            Worker name, flags, vars, bindings
+├── .dev.vars                 local secrets for wrangler dev; never committed
+├── manifests/
+│   └── site.yaml             immediate .yaml/.yml files; multi-document with ---
+├── src/
+│   ├── index.ts              createMantleWorker({ plan, extend })
+│   └── mantle/handlers/      handler refs (a convention; any path under src/)
+├── public/                   ASSETS: your frontend; public/_mantle/admin/ when Admin UI is installed
+├── .mantle/generated/
+│   └── mantle.ts             written by mantle generate
+├── .agents/skills/mantle-*/  written by mantle skills
+└── .claude/skills/mantle-*/  same bytes, for Claude compatibility
+```
+
+The minimal Worker reference keeps `.mantle/`, `.agents/`, `.claude/`, `.wrangler/`, `.dev.vars*` and `.env*` out of git and regenerates the first three in its `check` script. Committing the generated files is also workable, because `generate --check` and `skills --check` detect drift either way. Commit the lockfile in a real application and install with `--frozen-lockfile` afterwards.
+
+`mantle validate` greps `./src` for the names of `handler.kind: ref` Procedures; a handler that is not found anywhere under `src/` produces a `HANDLER_NOT_REGISTERED` warning, so keep handlers under that root or pass `--source`.
+
+## The CLI
+
+The umbrella package installs two binaries, `mantle` and `mantle-harness`. Run them through the package manager, for example `pnpm exec mantle generate`. Defaults shown are the pinned ones.
+
+| Command | Flags | Does |
+|---|---|---|
+| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--check` | Validate, link and compile manifests; write `mantle.ts`; sync Admin assets when installed. `--check` exits 1 without writing when output is stale. |
+| `mantle validate` | `--manifests <dir>`, `--source <dir>` (default `./src`), `--no-source`, `--phase preview\|deploy` (default `preview`), `--format json\|text`, `--json` | Static manifest and handler-source validation. Exit 0 with warnings allowed, 1 on any error, 2 on a CLI invocation problem. |
+| `mantle skills` | `--check` | Copy every skill marked `projection: project` into `.agents/skills/mantle-<name>/` and `.claude/skills/mantle-<name>/`. `--check` exits 1 when a projection is stale. |
+| `mantle emit-openapi` | `--manifests <dir>`, `--title <str>` (default `mantle`), `--version <str>` (default `0.1.0`), `--session-cookie-name <str>`, `-o, --output <file>` | Emit OpenAPI 3.1 for HTTP Triggers and `GET /api/views/<name>` routes to stdout or a file. MCP is out of scope. |
+| `mantle-harness indexes` | `--manifests <dir>`, `--rows <n>` (default 2000), `--require <view>` (repeatable), `--require-public`, `--format text\|json` | Execute compiled Views in crowded SQLite and inspect query plans; exit 1 when a required View lacks its access path. |
+| `mantle-harness http` | `--base-url <url>`, `--route <name=path-or-url>` (repeatable, required), `--rounds <n>` (default 20), `--warmup <n>` (default 2), `--format text\|json` | Sample a running Worker and report p50/p95 timings plus query-count and `rows_read` metric headers. |
+
+Advanced manifest primitives live in the `@aotter/mantle-spec` package's own `mantle-spec` binary: `mantle-spec introspect [--manifests <dir>]` dumps the parsed manifest tree as JSON, and `mantle-spec emit-types [--manifests <dir>] [--namespace <name>] [-o <file>]` emits standalone `.d.ts` declarations. Add `@aotter/mantle-spec` as a direct dependency to run them. The full flag reference is in [HTTP, MCP, CLI and packages](../reference/surface.md).
+
+### What `generate` does and does not do
+
+`generate` reads the manifest directory, runs the same validation as `validate` (without the handler-source grep), links the set, and emits one `.mantle/generated/mantle.ts`. When `@aotter/mantle-admin-ui` is installed it also syncs the Admin SPA into `public/_mantle/admin/`, excluding the package's `server.*` exports; Core-only installs skip that copy. Any error diagnostic stops the run with exit 1.
+
+It does not project skills, update packages, change styling, provision providers, or deploy. It does not create manifests: a missing or empty `manifests/` directory is an error, not a prompt.
+
+## The generated module
+
+`.mantle/generated/mantle.ts` exports:
+
+| Export | Purpose |
+|---|---|
+| `plan` | The sealed RuntimePlan with its fingerprint. The conventional Worker imports only this. |
+| `MantleHandlers<Env>` | The handler map type: one typed function per `handler.kind: ref` Procedure, receiving `(input, ctx)`. |
+| `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 })` 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 daily loop
+
+```sh
+pnpm install --frozen-lockfile
+pnpm exec mantle validate
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+pnpm exec tsc --noEmit
+pnpm test                      # only when the project declares a test script
+pnpm exec mantle-harness indexes --require-public --format text
+pnpm exec wrangler dev --local
+```
+
+Run the harness after any change to a Schema index, View filter or ordering, or public route; declare the smallest ordered index the measured path needs and respect SQLite's leftmost-prefix rule. Before a deploy, run `mantle validate --phase deploy`. Probe at least one declared route on the local origin; a `200` from a public View does not prove Admin or MCP login works.
+
+## 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.
+
+Install the version-matched plugin bundle in the agent host, using the exact version from `package.json`:
+
+```sh
+# Claude Code — two separate prompts
+/plugin marketplace add aotter/mantle@v<installed-version>
+/plugin install mantle@mantle
+
+# Codex
+codex plugin marketplace add aotter/mantle --ref v<installed-version>
+codex plugin add mantle@mantle
+```
+
+The projected `develop` skill tells the agent to read `package.json` for the installed version, the manifests and adapter config, and the docs under `node_modules/@aotter/mantle/docs/` before editing. To connect an MCP client to the running Worker, see [MCP and agents](../concepts/mcp-and-agents.md).
+
+## Upgrade rules
+
+- Pin every `@aotter/mantle*` package to one exact version and move them together. Check that release's peer ranges when you move.
+- Read the migration notes of the release you are moving to. Docs for a floating branch do not describe your installed version; use a tag that matches `package.json`.
+- The 0.1.2 line removes `mantle create`, the bundle `mantle update` command and `@aotter/mantle/provision`, with no aliases. `generate`, `validate`, `emit-openapi` and `skills` remain. `0.1.0-alpha.17` stays immutable; staying on it requires no migration.
+- When upgrading an existing application: pin the new exact version and refresh the lockfile; remove scripts that invoked the retired scaffolder; keep the Worker, D1, KV identity, origins, auth mode, secrets and legacy `.mantle` metadata; then run `generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests before deploying.
+
+## Source
+- [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
+- [`docs/adr/0021-retire-starter-scaffolding.md`](../../../docs/adr/0021-retire-starter-scaffolding.md)
+- [`docs/migration-0.1.2.md`](../../../docs/migration-0.1.2.md)
+- [`docs/examples/minimal-worker/.gitignore`](../../../docs/examples/minimal-worker/.gitignore)
+- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
+- [`packages/mantle/src/cli/main.ts`](../../../packages/mantle/src/cli/main.ts)
+- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
+- [`packages/mantle/src/cli/skills.ts`](../../../packages/mantle/src/cli/skills.ts)
+- [`packages/mantle/src/cli/harness.ts`](../../../packages/mantle/src/cli/harness.ts)
+- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
+- [`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)

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

@@ -0,0 +1,193 @@
+---
+description: "Author a minimal Cloudflare Worker from scratch: one Schema, one public View, generate, validate, run locally and probe it with curl."
+---
+# Quickstart: a minimal Worker
+
+This page reproduces Core's minimal Worker reference as a from-scratch walkthrough. It is for engineers who want a running Mantle service on their machine in a few minutes, with no visitor frontend and no Cloudflare account.
+
+> **Version scope**
+> The install below uses the published `0.1.0-alpha.17` packages. That release supports this minimal Worker flow, but still includes `mantle create` and `mantle update` and does not contain this handbook. The rest of this handbook describes a later development snapshot; see [Versions](../reference/surface.md#versions) before applying its CLI and migration guidance to a registry installation.
+
+## Prerequisites
+
+- Node.js 22 or newer.
+- pnpm 9 or newer. The reference is tested with pnpm; see the npm note at the end of this page.
+- `wrangler` is installed as a project devDependency below. No Cloudflare account, D1 database or secret is needed for the local loop.
+
+## 1. `package.json`
+
+Pin every `@aotter/mantle*` package to the same exact release and add the peers the Cloudflare adapter needs.
+
+```json
+{
+  "name": "mantle-minimal-consumer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "mantle generate",
+    "validate": "mantle validate",
+    "typecheck": "tsc --noEmit",
+    "dev": "wrangler dev --local",
+    "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit"
+  },
+  "dependencies": {
+    "@aotter/mantle": "0.1.0-alpha.17",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.17",
+    "better-auth": "1.7.2",
+    "hono": "^4.13.3",
+    "zod": "^4.5.4",
+    "aws4fetch": "^1.0.20"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260907.1",
+    "typescript": "^6.0.3",
+    "wrangler": "^4.125.0"
+  },
+  "packageManager": "pnpm@9.15.0"
+}
+```
+
+The reference's own `check` script ends with `&& node smoke.mjs`, a test that starts the Worker and asserts the three probes in step 6. This walkthrough runs those probes by hand instead.
+
+Add a `tsconfig.json` that includes the generated module:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/**/*.ts", ".mantle/generated/**/*.ts"]
+}
+```
+
+## 2. `manifests/site.yaml`
+
+One publishing Schema and one public View. `mantle generate` never invents a Schema; this notes model is example business data.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: notes
+spec:
+  title: Notes
+  schema:
+    type: object
+    required: [title]
+    properties:
+      title: { type: string }
+  lifecycle: publishing
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: published-notes
+spec:
+  surface: public
+  from: notes
+  fields: [id, title]
+  filter:
+    eq: { field: status, value: published }
+  limit: 20
+```
+
+## 3. `src/index.ts`
+
+The conventional Worker entry hands the sealed plan to the Cloudflare adapter.
+
+```ts
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export default createMantleWorker({ plan });
+```
+
+`createMantleWorker` owns the D1 and assets bindings, Auth, Admin, View REST, HTTP Triggers, OAuth, MCP and cache policy. Application handlers and extra routes go through its `extend` option; see [the conventional Worker](../cloudflare/conventional-worker.md).
+
+## 4. `wrangler.jsonc`
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-reference",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-09-08",
+  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
+  "observability": { "enabled": true },
+  "vars": { "MANTLE_AUTH_MODE": "self-managed" },
+  "d1_databases": [
+    { "binding": "DB", "database_name": "mantle-reference-local" }
+  ]
+}
+```
+
+Both compatibility flags are required by the adapter. `MANTLE_AUTH_MODE` must be explicit; `self-managed` without GitHub credentials is a deliberate partial configuration for this local reference, so Auth-owned routes fail closed while public routes work. Local `wrangler dev` creates the D1 database on demand; configure a real `database_id` and the full auth matrix before any remote deploy ([Authentication](../cloudflare/authentication.md)).
+
+## 5. Install, generate, validate, run
+
+```sh
+pnpm install
+pnpm exec mantle generate
+pnpm exec mantle validate
+pnpm exec wrangler dev --local
+```
+
+`mantle validate` prints `OK  no issues (root: manifests, phase: preview)`. Wrangler prints the local origin, normally `http://localhost:8787`; use whatever it prints in the next step.
+
+## 6. Probe the Worker
+
+```sh
+curl -s http://localhost:8787/api/views/published-notes
+```
+
+```json
+{ "ok": true, "data": { "rows": [], "page": 1, "show": 20, "hasMore": false } }
+```
+
+The View is served with no data because the local D1 is fresh. `show` follows the View's `limit` when the request carries no `?show=`; `?page=` and `?show=` are the reserved pagination params ([Reads: Views, REST and MCP](../concepts/views.md)).
+
+```sh
+curl -i http://localhost:8787/
+```
+
+`GET /` returns `404`. No visitor frontend is installed or rendered; `mantle-web` is optional composition and never owns an implicit home route. Add your own routes or templates when the product needs them ([Public web, SEO and cache](../cloudflare/public-web.md)).
+
+```sh
+curl -i http://localhost:8787/mcp/staff
+```
+
+`GET /mcp/staff` returns `503` with the error code `setup_incomplete` until `MANTLE_AUTH_MODE` is backed by a complete configuration. This is the expected fail-closed state; a working public endpoint is not evidence of a working Admin or MCP login.
+
+## What `mantle generate` wrote
+
+- `.mantle/generated/mantle.ts` — one module with the sealed `plan`, generated types (`MantleHandlers<Env>`), `createMantle` and `bindMantle`. The Worker entry above imports only `plan`.
+- `public/_mantle/admin/` — the Admin SPA, synced only when `@aotter/mantle-admin-ui` is installed. This project did not install it, so nothing is written there and `/admin` has no assets.
+
+`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 `ERESOLVE`**
+> With npm 11.16.0 a cold Cloudflare install can fail with `ERESOLVE`: Better Auth/Drizzle selects optional `@libsql/client@0.18.0` while this release declares the tested `^0.17.4` peer. If that exact conflict occurs, merge `{ "overrides": { "@libsql/client": "0.17.4" } }` into `package.json` and rerun `npm install`. Do not use `--force` or `--legacy-peer-deps`. Commit the lockfile and use `npm ci` afterwards. Recheck the peer range when upgrading; the workaround is specific to these versions.
+
+## Next steps
+
+- [Project layout and the CLI loop](./project-and-cli.md) — the files you own, every CLI flag, the daily check loop.
+- [The four atoms](../concepts/four-atoms.md) — add a Procedure and a Trigger to accept writes.
+- [Authentication](../cloudflare/authentication.md) — complete `MANTLE_AUTH_MODE` so Admin and `/mcp/staff` open.
+- [Public web, SEO and cache](../cloudflare/public-web.md) — give the service a rendered public surface.
+
+## Source
+- [`docs/examples/minimal-worker/README.md`](../../../docs/examples/minimal-worker/README.md)
+- [`docs/examples/minimal-worker/package.json`](../../../docs/examples/minimal-worker/package.json)
+- [`docs/examples/minimal-worker/tsconfig.json`](../../../docs/examples/minimal-worker/tsconfig.json)
+- [`docs/examples/minimal-worker/manifests/site.yaml`](../../../docs/examples/minimal-worker/manifests/site.yaml)
+- [`docs/examples/minimal-worker/src/index.ts`](../../../docs/examples/minimal-worker/src/index.ts)
+- [`docs/examples/minimal-worker/wrangler.jsonc`](../../../docs/examples/minimal-worker/wrangler.jsonc)
+- [`docs/examples/minimal-worker/smoke.mjs`](../../../docs/examples/minimal-worker/smoke.mjs)
+- [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
+- [`packages/mantle-runtime/src/domain/service/Pagination.ts`](../../../packages/mantle-runtime/src/domain/service/Pagination.ts)

package/docs/labels.md

@@ -29,11 +29,12 @@ For package README or package-local docs changes, prefer the package area label
 | `area:runtime` | `packages/mantle-runtime` behavior, ports, use cases, dispatcher, and MCP runtime. |
 | `area:spec` | `packages/mantle-spec`, manifest parsing, validation, diagnostics, CLI, spec types. |
 | `area:cf` | `packages/adapters/cloudflare`, Workers adapter, D1/KV/ASSETS wiring, Cloudflare deploy behavior. |
-| `area:starters` | External `aotter/mantle-starters` integration, release fanout, and the local moved-starter stub. |
+| `area:starters` | Legacy `aotter/mantle-starters` source and retirement migration. |
 | `area:skills` | `skills/*` agent briefs and install/extend/provision workflows. |
 | `area:admin-ui` | `packages/mantle-admin-ui` React admin SPA. |
 | `area:docs` | Repo-wide human docs, governance docs, ADR text, release docs, root README content, and cross-cutting documentation work. |
 | `area:adapter` | Adapter boundary work spanning Cloudflare or future adapters. |
+| `area:ci` | GitHub Actions, dependency automation, and repository checks. |
 
 ## Release and review gates
 
@@ -60,6 +61,7 @@ gh label create "area:skills" --description "Agent Skills and install/extend/pro
 gh label create "area:admin-ui" --description "React admin UI" --color "1d76db"
 gh label create "area:docs" --description "Documentation and governance" --color "1d76db"
 gh label create "area:adapter" --description "Adapter boundary and future adapter work" --color "1d76db"
+gh label create "area:ci" --description "CI, dependency automation, and repository checks" --color "1d76db"
 gh label create "breaking-change" --description "Semver-relevant breaking change" --color "b60205"
 gh label create "skip-release-notes" --description "Release bookkeeping only; omit from generated GitHub notes" --color "ededed"
 gh label create "needs-adr" --description "Requires an ADR or ADR-lite decision before merge" --color "d93f0b"