@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/docs/upgrade-0.1-to-0.2.md

@@ -1,9 +1,24 @@
 # Upgrading from 0.1.x to 0.2.0 (for AI agents)
 
+For **0.2.0-alpha.7 and later**, use the
+[native SDK migration](handbook/releases/index.md#native-sdk-migration-alpha7),
+[current CLI](handbook/start/project-and-cli.md) and
+[app shell](examples/app-shell/). The application owns routing,
+Auth, native handles and database migrations; the former `createMantle` runtime,
+host presets, boot-time convergence and CLI flags below have been replaced.
+Install the same exact version of `@aotter/mantle`, `@aotter/mantle-ui` and,
+when selecting Admin, `@aotter/mantle-admin`. Start with a new database for a
+0.1.x migration and preserve every authorization, scope and OCC requirement.
+The remainder describes the earlier alpha contract for historical reference.
+
 No codemod, and no in-place upgrade of a 0.1.x database. A coding agent moves
-one project by hand with this guide. When it and ADR-0032 to ADR-0035
-(`docs/adr/`), ADR-0036 (host and dialect) or ADR-0038 (Bun) disagree, the
-ADR wins.
+one project by hand with this guide. When it and
+[ADR-0032](https://github.com/aotter/mantle/blob/develop/docs/adr/0032-store-centric-core-and-service-contract.md),
+[ADR-0033](https://github.com/aotter/mantle/blob/develop/docs/adr/0033-storage-converges-to-the-plan.md),
+[ADR-0034](https://github.com/aotter/mantle/blob/develop/docs/adr/0034-store-is-authored-as-sql.md),
+[ADR-0035](https://github.com/aotter/mantle/blob/develop/docs/adr/0035-sql-dialects.md),
+[ADR-0036](https://github.com/aotter/mantle/blob/develop/docs/adr/0036-host-and-dialect.md) or
+[ADR-0038](https://github.com/aotter/mantle/blob/develop/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
 
 ## Rules
 
@@ -50,7 +65,7 @@ command; it never installs anything.
 - `features` is a subset of `mcp`, `admin`, `web`, in that order. The 0.1.x
   features `spec`, `runtime` and `api` are dropped: REST is always mounted.
 - `dialect` is `sqlite` (alias `d1`, the default, left out) or `postgres`
-  (PostgreSQL through Hyperdrive on `cloudflare`; Bun.SQL on `bun`, where it
+  (PostgreSQL through Hyperdrive on `cloudflare`; node-postgres on `bun`, where it
   is the default). A 0.1.x project was SQLite: keep `sqlite` (with
   `--host bun`, pass `--dialect sqlite`) unless the data also moves to
   PostgreSQL.
@@ -70,10 +85,10 @@ camelCase names.)
 
 | 0.1.x | 0.2.0 |
 |---|---|
-| `scope: { owner: $ctx.user.id }` | `scope: { owner: auth.uid() }`. The field is a required string, the leftmost column of an index (`indexes: [[owner]]`), and the first column of every `uniqueIndexes` entry. Store fills it; a write never sets it |
+| `scope: { owner: $ctx.user.id }` | `scope: "owner = auth.uid()"`. The field is a required string, the leftmost column of an index (`indexes: [[owner]]`), and the first column of every `uniqueIndexes` entry. Store fills it; a write never sets it |
 | `x-mantle-bind: ctx.user` on a field only its owner may see | remove the bind; add `scope` as above |
 | any other `x-mantle-bind: ctx.user` | remove the bind; every write that sets the field sets it to `auth.uid()`, never to an input |
-| `x-mantle-bind: ctx.staff` | remove the bind; set it to `auth.uid()` in writes whose Procedure `requires` `ctx.staff` |
+| `x-mantle-bind: ctx.staff` | remove the bind; set it to `auth.uid()` in writes whose Procedure requires `ctx.admin` |
 | `x-mantle-bind: now` | remove the bind; set it to `now()` in every write that sets it |
 | `searchableFields` | unchanged, now trigram full-text search; date and date-time fields are refused |
 
@@ -158,11 +173,11 @@ The generated types list exactly the plan's refs.
 |---|---|
 | `ctx.user` present | `ctx.caller.kind === "user"`. Never test `!== "anonymous"`: a schedule runs as `system` |
 | `ctx.user.id` | `ctx.caller.subject` (after that check) |
-| `ctx.staff` | `ctx.caller.kind === "user" && ctx.caller.role !== null` |
+| `ctx.staff` | `isAdmin(ctx.caller)` from `@aotter/mantle/contracts` |
 | `ctx.event`, `ctx.schedule` | `ctx.cause` (`kind`: `http`, `mcp`, `internal`, `schedule`, `lifecycle`); `ctx.cause.cron` is POSIX, so shift any cron string the code compares |
 | `ctx.event.entry` | **a loop** over `ctx.cause.rows` (one statement can touch many rows; never `rows[0]`). Rows are flat: `entry.data.x` → `row.x` |
 | `ctx.store.view(name, { params, page, show, search, filters })` | `ctx.store.view(name, { input, limit, cursor, search, filters })`; `search` and `filters` match only the View's `uiSchema.list.searchFields` and `filterFields` |
-| `runtime.entries`, `runtime.executeView`, `ctx.writeAtomically` | `ctx.store.select`, `ctx.store.view`, `ctx.store.write([...ops])` (all or nothing), `ctx.store.id()` |
+| `runtime.entries`, `runtime.executeView`, `ctx.writeAtomically` | `ctx.db.<schema>.get / first / find`, `ctx.store.view`, `ctx.store.write([...ops])` (all or nothing), `ctx.store.id()` |
 | `runtime.store.as(ctx)` | `runtime.store.as(caller)` |
 | calling another Procedure through a `getRuntime` closure | `await ctx.invoke("procedure-name", input)` (keeps the caller, re-checks its auth) |
 
@@ -179,8 +194,9 @@ only in trusted host code.
    old Worker into the new files by hand.
 3. With `identity: mantle`, sign-in uses a console email sender locally;
    replace it with a real `EmailSender` before deploying.
-4. Staff MCP stays at `/mcp/staff`, behind an OAuth token with the `mcp`
-   scope and a staff role; MCP clients keep their URL.
+4. Admin MCP moves from `/mcp/staff` to `/mcp/admin`. Update MCP client URLs.
+   It admits only the admin layer classified by Better Auth’s admin plugin
+   `adminRoles` (default `["admin"]`), and requires the `mcp` scope for tokens.
 5. Import data into the new database through `runtime.store`. A scoped row
    goes through `runtime.store.as(<its owner's caller>)`, so the scope field is
    the owner. `status`, `created_at` and `author_id` cannot be imported:

package/package.json

@@ -1,148 +1,133 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.5",
-  "description": "Mantle: a manifest-driven service core. Store authored as SQL, surfaces as Fetch functions, and the mantle CLI.",
-  "license": "Apache-2.0",
-  "homepage": "https://mantle.tools/",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aotter/mantle.git",
-    "directory": "packages/mantle"
-  },
+  "version": "0.2.0-alpha.7",
   "type": "module",
   "sideEffects": false,
-  "exports": {
-    ".": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js"
-    },
-    "./spec": {
-      "types": "./dist/spec/index.d.ts",
-      "import": "./dist/spec/index.js"
-    },
-    "./d1": {
-      "types": "./dist/d1/index.d.ts",
-      "import": "./dist/d1/index.js"
-    },
-    "./d1/compile": {
-      "types": "./dist/d1/compile/index.d.ts",
-      "import": "./dist/d1/compile/index.js",
-      "default": "./dist/d1/compile/index.js"
-    },
-    "./postgres": {
-      "types": "./dist/postgres/index.d.ts",
-      "import": "./dist/postgres/index.js"
-    },
-    "./postgres/compile": {
-      "types": "./dist/postgres/compile/index.d.ts",
-      "import": "./dist/postgres/compile/index.js",
-      "default": "./dist/postgres/compile/index.js"
-    },
-    "./cloudflare": {
-      "types": "./dist/cloudflare/index.d.ts",
-      "import": "./dist/cloudflare/index.js"
-    },
-    "./auth": {
-      "types": "./dist/auth/index.d.ts",
-      "import": "./dist/auth/index.js"
-    },
-    "./admin": {
-      "types": "./dist/admin/index.d.ts",
-      "import": "./dist/admin/index.js"
-    },
-    "./mcp": {
-      "types": "./dist/mcp/index.d.ts",
-      "import": "./dist/mcp/index.js"
-    },
-    "./web": {
-      "types": "./dist/web/index.d.ts",
-      "import": "./dist/web/index.js"
-    },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js"
-    },
-    "./package.json": "./package.json",
-    "./bun": {
-      "types": "./dist/bun/index.d.ts",
-      "import": "./dist/bun/index.js"
-    }
-  },
-  "bin": {
-    "mantle": "./dist/cli/main.js"
+  "engines": {
+    "node": ">=22.22.0"
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "skills",
+    "README.md"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "alpha",
-    "registry": "https://registry.npmjs.org"
+  "bin": {
+    "mantle": "./dist/infrastructure/cli.js"
   },
   "dependencies": {
+    "esbuild": "0.28.1",
+    "jsonc-parser": "3.3.1",
     "@pgsql/types": "18.0.0",
     "libpg-query": "18.1.5",
     "pgsql-deparser": "18.3.8",
-    "yaml": "^2.9.0",
-    "zod": "^4.5.4",
-    "semver": "^7.8.5"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
-  "devDependencies": {
-    "@better-auth/cimd": "1.7.7",
-    "@better-auth/core": "1.7.7",
-    "@better-auth/mcp": "1.7.7",
-    "@better-auth/oauth-provider": "1.7.7",
-    "@better-auth/utils": "0.4.2",
-    "@modelcontextprotocol/client": "2.1.0",
-    "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.1.0",
-    "@types/node": "^26",
-    "@types/pg": "8.23.1",
-    "better-auth": "1.7.7",
-    "bun-types": "1.3.14",
-    "pg": "8.23.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
-    "wrangler": "4.126.0",
-    "@types/semver": "^7.7.1"
+  "exports": {
+    ".": "./dist/infrastructure/generate.js",
+    "./generate": "./dist/infrastructure/generate.js",
+    "./contracts": "./dist/kernel/contracts.js",
+    "./authorization": "./dist/kernel/authorization.js",
+    "./translations": "./dist/kernel/translations.js",
+    "./driver/transaction-context": "./dist/kernel/driver/transaction-context.js",
+    "./scalars": "./dist/kernel/scalars.js",
+    "./binds": "./dist/kernel/binds.js",
+    "./testing": "./dist/testing/index.js",
+    "./host-access": "./dist/kernel/host-access.js",
+    "./host-caller": "./dist/kernel/host-caller.js",
+    "./user-fields": "./dist/kernel/user-fields.js",
+    "./sweep": "./dist/kernel/sweep.js",
+    "./cron": "./dist/kernel/cron.js",
+    "./store": "./dist/kernel/store.js",
+    "./dialect/sqlite": "./dist/kernel/dialect/sqlite.js",
+    "./dialect/postgres": "./dist/kernel/dialect/postgres.js",
+    "./driver/bun-sqlite": "./dist/kernel/driver/bun-sqlite.js",
+    "./driver/d1": "./dist/kernel/driver/d1.js",
+    "./driver/postgres": "./dist/kernel/driver/postgres.js",
+    "./email": "./dist/kernel/email.js",
+    "./paging": "./dist/kernel/paging.js",
+    "./publishing": "./dist/kernel/publishing.js",
+    "./rest": "./dist/kernel/rest.js",
+    "./mcp": "./dist/kernel/mcp.js",
+    "./mcp-apps": "./dist/kernel/mcp-apps.js",
+    "./web": "./dist/kernel/web.js",
+    "./validation": "./dist/kernel/validation.js",
+    "./site": "./dist/kernel/site.js",
+    "./media": "./dist/kernel/media.js",
+    "./media/r2": "./dist/kernel/r2-media.js",
+    "./auth": "./dist/auth/caller.js",
+    "./auth/adapter": "./dist/auth/adapter.js",
+    "./auth/oauth": "./dist/auth/oauth.js",
+    "./auth/routes": "./dist/auth/routes.js",
+    "./auth/identity": "./dist/auth/identity.js",
+    "./auth/hardening": "./dist/auth/hardening.js",
+    "./auth/admin": "./dist/auth/admin.js",
+    "./bun/assets": "./dist/bun/assets.js",
+    "./surface": "./dist/kernel/surface.js",
+    "./json-body": "./dist/kernel/json-body.js",
+    "./generate/auth": "./dist/infrastructure/generateAuth.js",
+    "./package.json": "./package.json",
+    "./describe": "./dist/domain/describe/index.js",
+    "./target-hash": "./dist/domain/describe/target-hash.js"
   },
   "peerDependencies": {
-    "@better-auth/cimd": "1.7.7",
-    "@better-auth/mcp": "1.7.7",
+    "@modelcontextprotocol/server": "2.2.0",
+    "@better-auth/core": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",
-    "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.1.0",
     "better-auth": "1.7.7"
   },
   "peerDependenciesMeta": {
-    "@better-auth/cimd": {
+    "@modelcontextprotocol/server": {
       "optional": true
     },
-    "@better-auth/mcp": {
+    "@better-auth/core": {
       "optional": true
     },
     "@better-auth/oauth-provider": {
       "optional": true
     },
-    "@modelcontextprotocol/ext-apps": {
-      "optional": true
-    },
-    "@modelcontextprotocol/server": {
-      "optional": true
-    },
     "better-auth": {
       "optional": true
     }
   },
-  "engines": {
-    "node": ">=22"
+  "devDependencies": {
+    "@modelcontextprotocol/server": "2.2.0",
+    "@better-auth/core": "1.7.7",
+    "@better-auth/oauth-provider": "1.7.7",
+    "@better-auth/test-utils": "1.7.7",
+    "@cloudflare/workers-types": "^5.20261008.1",
+    "@types/node": "^26",
+    "better-auth": "1.7.7",
+    "bun-types": "1.4.2",
+    "postgres": "3.4.9",
+    "typescript": "^6.0.3",
+    "wrangler": "4.145.0",
+    "vitest": "^5.0.1"
+  },
+  "description": "Mantle: a manifest-driven service core. Store authored as SQL, surfaces as Fetch functions, and the mantle CLI.",
+  "license": "Apache-2.0",
+  "homepage": "https://mantle.tools/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aotter/mantle.git",
+    "directory": "packages/mantle"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "prebuild": "rm -rf dist .tsbuildinfo",
-    "build": "tsc -b tsconfig.lib.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.lib.json && node scripts/bundle-compiler.mjs && node scripts/prune-declarations.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run",
-    "test:bun": "bun test/bun/native.ts"
+    "test": "bun test tests/*.test.ts && bun run test:compiler",
+    "generate": "bun src/infrastructure/cli.ts",
+    "test:native": "bun scripts/verify-native.ts",
+    "bench": "bun scripts/verify-native.ts --bench",
+    "check:size": "bun run build && bun scripts/check-size.ts",
+    "check:package": "bun run build && bun scripts/check-package.ts",
+    "test:compiler": "tsc --noEmit -p tsconfig.compiler.json && vitest run --config vitest.compiler.config.ts",
+    "check:startup": "bun scripts/check-size.ts --startup-only"
   }
 }

package/skills/README.md

@@ -0,0 +1,72 @@
+# SKILL.md briefs (mantle)
+
+Agent-readable skills for consumers of `@aotter/mantle` 0.2. There are two
+distributions (ADR-0032 decision 13):
+
+- **The plugin** ships one OSS authoring skill, [`mantle`](mantle/SKILL.md),
+  without a hosted-service MCP connection or transport.
+- **The npm package** ships the workflow skills under `docs/skills/`. An agent
+  reads them from `node_modules/@aotter/mantle/docs/skills/`, matched to the
+  installed version. Nothing copies them into a project; 0.2 has no
+  `mantle skills` command.
+
+| Skill | When to invoke |
+|---|---|
+| [`mantle`](mantle/SKILL.md) | Create or continue a Mantle application and deploy to a user-owned host. |
+| [`develop`](../docs/skills/develop/SKILL.md) | Change manifests, SQL, handlers, the service entry or surfaces of an existing project. |
+| [`integrate`](../docs/skills/integrate/SKILL.md) | Add Mantle to an application that has its own code, users or data, or rebuild one and migrate. |
+| [`update`](../docs/skills/update/SKILL.md) | Upgrade `@aotter/mantle`, including from 0.1.x. |
+| [`provision`](../docs/skills/provision/SKILL.md) | Ship to Cloudflare Workers or ChatGPT Sites with production sign-in. |
+| [`media-gc`](../docs/skills/media-gc/SKILL.md) | Audit or remove stale, uncommitted R2 uploads. |
+
+## Install
+
+```bash
+# Claude Code: two separate prompts
+/plugin marketplace add aotter/mantle
+/plugin install mantle@mantle
+
+# Codex
+codex plugin marketplace add aotter/mantle
+codex plugin add mantle@mantle
+```
+
+Cursor and GitHub Copilot read the manifests from the repository
+(`.cursor-plugin/plugin.json`, `.copilot-plugin/plugin.json`). Without a
+plugin host, `npx skills add aotter/mantle` installs the `mantle` skill and its
+references. The manifests are generated by
+`scripts/sync-plugin-manifests.mjs` and checked with `--check`.
+
+Claude Code updates an installed plugin only when its manifest version
+changes, and that version is Core's, so a skill or script update reaches
+Claude Code users with the next Core release.
+
+## Disclosure audit
+
+Every skill is one `SKILL.md`; the plugin skill carries local acceptance references.
+`scripts/check-skills.mjs` holds this table, the front matter and the links to
+each other: `metadata.projection` is `plugin` for `skills/mantle` and
+`package` for `docs/skills/*`, a reason in the last column must equal
+`metadata.projectionReason`, and a relative link must stay inside what ships
+(the skill's own directory for the plugin, `docs/` for the package).
+
+| Skill | Routes on | Entry constraints | Distribution | Restricted because |
+|---|---|---|---|---|
+| `mantle` | new project, existing project, self-host deployment | the installed package's docs win; never use the SDK checkout as the application; no deploy during a cold start | plugin | The plugin's authoring entry skill is installed from the repository; workflow documentation comes from the installed SDK package. |
+| `develop` | manifest, SQL, handler, service or surface work | read the installed version first; never edit generated files; writes through Store/Procedures, richer reads through internal Views | package | — |
+| `integrate` | an application with its own code, users or data | inspect before choosing; the application keeps its users; one writer per table | package | — |
+| `update` | an SDK upgrade | never overwrite application files; 0.1.x moves by the upgrade guide to a new database | package | — |
+| `provision` | ship to production | secrets never in source, chat or logs; a new database for 0.2; self-hosting is always an option | package | Creates remote resources and handles production secrets; opt-in only. |
+| `media-gc` | stale R2 uploads | audit by default; exact keys only, never a prefix delete; re-audit before applying | package | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
+
+## Audience
+
+These are for **AI agents acting for consumers of Mantle**, not for
+contributors to the SDK, who read the repository's `CONTRIBUTING.md`.
+
+## Conventions
+
+Each SKILL.md has front matter (`name`, a trigger-complete `description`,
+`metadata.source`, `sourcePath`, `applies_to`, `projection`), the reads to do
+first, concrete commands, the rules an agent must not break, and what to report
+when done. Commands and prose match the package version that carries the skill.

package/skills/mantle/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: mantle
+description: Create or continue a Mantle application, test it locally and deploy to a user-owned host using the installed SDK docs.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/mantle/SKILL.md
+  applies_to: mantle 0.2
+  projection: plugin
+  projectionReason: The plugin's authoring entry skill is installed from the repository; workflow documentation comes from the installed SDK package.
+---
+
+# Mantle
+
+The Mantle plugin's one skill. It installs no SDK and creates nothing by
+itself. Once a project has `@aotter/mantle`, the installed package is the
+authority: `node_modules/@aotter/mantle/README.md` and
+`node_modules/@aotter/mantle/docs/`. Prefer them over this file, the SDK
+checkout, or any online copy.
+
+## Find the project and its version
+
+Work in the user's application, outside the SDK checkout. Read package.json, the lockfile, installed SDK README and node_modules/@aotter/mantle/docs/. Those files define the exact version's contract. Preserve existing identity, handles, routes and resources.
+
+For a new project, install an exact published SDK version with matching selected Admin/UI packages. Node must be 22.22 or newer. Add TypeScript and target types; Workers also need Wrangler. Optional auth/MCP peers use the installed SDK's package.json versions. Read the installed handbook's start/project-and-cli.md before choosing a target.
+
+For a new Cloudflare app, copy `node_modules/@aotter/mantle/docs/examples/app-shell/` first, then the closest example from `docs/examples/README.md` on top of it, and edit from there: manifests, `src/handlers.ts`, `src/routes.ts`, `src/schedule.ts`, `smoke.mjs`. Search for `AGENT:` to find what the app must fill in; the example pages are unstyled on purpose, so styling them is part of that work. Before reporting done, resolve each `AGENT:` or name the ones you left. Keep the two roles `admin` and `user` unless the user asks for more.
+
+For existing older applications, use their installed docs until the user requests an upgrade. For partial adoption read node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md.
+
+## Generated native applications
+
+Follow the installed (or workspace-linked) package README for generation, Workers
+builds and D1 Sessions; the app owns its entry and routing. Read that
+version's `docs/handbook/reference/features.md` before choosing declarations. Keep auth behind
+`authLoader(() => import(...))` to pass the startup guard. Install only the exact
+released version shown by the installed/target package
+contract. Replacing Core needs explicit app wiring and reviewed deployment
+migrations; never use initial schema.sql as an in-place production upgrade.
+Pass outgoing `responseHeaders` to `resolveCaller` so Better Auth's session cookie
+can slide. Native auth adapters use joins by default; keep the joined primary
+session/user check, including before any refresh from secondary storage.
+Only positively classified View/web reads may pass `readOnly: true`, with official
+cookieCache `{enabled:true,maxAge:60,refreshCache:false,version:"read-60-v1"}` and
+no KV. Bump version when enabling/changing the policy; writes, Admin, consent,
+unknown/ref/media calls stay fresh. Read the installed auth docs before MCP caching.
+
+Use the workflow **generate → typecheck → implement listed handlers**. For example:
+
+```sh
+pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml
+pnpm exec tsc --noEmit
+pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --check
+```
+ Implement every printed `Handlers` key
+and pass the implementations at `store(db, caller, { handlers })` (and selected
+surface options). Run `tsc --noEmit` again before local acceptance.
+Generated Store metadata initializes on its first use, once per module. Bind
+`store(db, caller, options?)` for the current request; never reuse one caller's
+bound Store for another caller.
+
+Use `paged/views/<encoded-name>.ts` for bounded cursor walks, including internal
+Views that satisfy the installed package's generation-time paging proofs.
+Call its default export with `(db, caller, input, { limit?, cursor? })`; it returns
+`{ rows, nextCursor? }`. Internal paging creates no public route/tool. Keep bare
+Views for authored-query row arrays, and inspect native EXPLAIN/source indexes
+when grouping: cursor paging does not eliminate aggregation work.
+Bare Views, Store and SQL Procedure results keep driver-native scalar values.
+Selected REST/MCP/Admin boundaries return target-identical `WireRow` types:
+declared integers become safe numbers or exact decimal strings, SQLite/D1
+JSON/booleans become JSON values/booleans, and compiler-declared decimals become
+strings. Selected SQL reads integer text before driver rounding; it cannot repair
+already-rounded writes. Use exported `WireRow` for clients and `Row` for bare
+queries. Computed/ref results remain app-owned.
+
+Commit everything `mantle generate` writes, including generated TypeScript, SQL and
+Wrangler edits; keep bundle `dist/` untracked. Never hand-edit generated files.
+Resolve conflicts by merging manifests/options and regenerating. Add the printed
+`.gitattributes` line and run the same generate command with `--check` in CI.
+Compose the app-owned `fetch` using `docs/handbook/cloudflare/service-entry.md`: auth/consent, Admin,
+MCP, REST behind one request-local origin-checked resolver; keep heavy auth dynamic.
+
+For selected native Admin, follow the version-matched
+`docs/handbook/guides/native-admin.md`: select `--admin` (or `admin: true`),
+mount `entries(bindings.schemas, bindings.adapter)` and serve the Admin assets
+separately. The three-package preview is one Core SDK, the Admin product and the
+shared UI kit.
+Admin reads share generated whitelisted native View templates, writes use native
+Procedure fragments and generated checks. Ref operations retain typed `ctx.store`
+at request time. Verify member/frontend and admin/Admin OTP, tenant/privacy/TTL,
+publishing, paging, statistics, exact OCC, ref effects and the actual console;
+never retry unknown 503 writes automatically. Read the installed Admin README
+for extensions, raw-body limits, CSP/assets, 22 languages and the developer workspace.
+Use only versions actually published, or the explicitly linked workspace packages.
+
+For generated native applications, optional site settings/media are selected
+with `--site <module>` exporting `siteDefaults`. Apply the emitted deployment DDL;
+wire application-owned object storage as documented in `docs/handbook/cloudflare/media-r2.md`.
+
+For a generated public website, follow [web mounting and acceptance](references/web.md).
+The app renders HTML and inserts `site.head()`; generated `web.ts` serves the
+indexes and Markdown alternates.
+
+## Complete websites
+
+For a requested complete website, apply [website defaults](references/website.md)
+without asking the user to enumerate OTP, media, Admin or SEO. Defaults are
+acceptance requirements, not evidence that a missing renderer is implemented.
+Do not report a complete website with blocked required checks.
+
+Run the [local HTTP acceptance](references/local-testing.md) for handlers and websites; compilation does not execute their behavior.
+
+## Self-hosted deployment
+
+Deploy only when the user requests it. Follow the application's selected host
+and the installed `docs/skills/provision/SKILL.md`; use the platform's native
+workflow. Local project creation alone is not deployment authorization.
+
+## Existing project and handoff
+
+Preserve the user's manifests, `src/` files, identity, package versions and
+provider resources. The app writes its entry (`src/worker.ts` by default;
+`--entry` selects another). Workers generation creates or updates Wrangler's
+split-build settings. Run the same generation command (target, output directory,
+manifests and options) with `--check`, and the project's own tests,
+before and after a change.
+
+To add Mantle to an application that has its own code, users and data, read
+`node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md` first.
+
+Report the project path, the exact Mantle version, what you changed, the checks
+you ran with their results, and anything left for the user.
+
+## Data paths
+
+Writes use Store `insert` / `update` / `delete`, atomic `batch` / supported `transaction`, or declared Procedures. Raw SQL writes bypass row rules. Use internal Views for joins, aggregates, OR and reusable reads; Store `findById` / `find` / `first` are for id lookups and simple AND filters. Ref handlers receive `ctx.store` with the same Caller and transaction.

package/skills/mantle/references/local-testing.md

@@ -0,0 +1,11 @@
+# Local HTTP acceptance
+
+
+Generation with `--check` and typechecking prove compilation, not handler execution. Before reporting local readiness or deploying, run the application's existing dev command with isolated local data and a console/test email sender. Use a small application-owned Node `assert` + `fetch` script; no browser, deployment or helper server runner is required.
+
+Better Auth limits each email-OTP path to 3 requests/minute per IP; `authHardening` stores rate limits in the database. Local tests signing in several users should send a distinct `cf-connecting-ip` header per user (with that header configured in `ipAddressHeaders`), or wait out the window. With the console sender, the OTP appears in the Wrangler log.
+
+- Exercise actual HTTP Triggers for every custom Procedure handler: valid input/output, invalid input, anonymous refusal on protected operations, authorized synthetic caller and expected stored result. A status below 500 alone is not success; assert the expected status and JSON envelope/body. Use only the generated contract's routes, inputs and permissions.
+- For an app-owned `fetch`, exercise its real public routes, not just dist files. Assert HTML content type, visible content and metadata/canonical/JSON-LD with no JavaScript execution, sitemap, robots and an unknown URL returning 404. Create a local synthetic draft and assert it is hidden anonymously; publish, edit and delete it through authorized operations and check the page and sitemap after each change. Reuse the application's existing smoke-test pattern and clean up test rows/server in `finally`.
+- Keep caller authority explicit: use supplied `resolveCaller` and caller-scoped Store/Procedure APIs from the installed service-entry docs. Use the actual local host capabilities; local tests do not prove remote identity/provider wiring.
+- Record commands and passed/failed/blocked cases for the exact commit. Fix failures before source admission; rerun relevant checks after changing source. Packing does not run these checks and an agent's checklist is not server build attestation.

package/skills/mantle/references/web.md

@@ -0,0 +1,41 @@
+# Generated public websites
+
+Use this flow only when the installed package README documents concrete native
+queries and generated `web.ts`.
+Earlier Core versions use their own installed handbook. Read the installed
+`docs/handbook/reference/surface.md` and `docs/examples/generated-web/README.md` before writing
+routes; the installed version is authoritative.
+
+Mount `web()` when the application serves public HTML and needs `llms.txt`, a
+sitemap or Markdown alternates. Import the generated `web.ts`; pass the native
+`db`, a verified Caller (or the app's resolver), the configured public `origin`,
+`title`, `description` and `pages`. Mount generated `rest.ts` for public View and
+HTTP Trigger APIs. Neither module renders the application's HTML.
+
+Each page template's `{parameter}` names exactly match its public View inputs;
+both its View and list View return these parameters. A list View accepts empty
+input. `markdown` names a textual column in the detail View. Supply the same
+SQL-visible data to the HTML renderer through generated Views or the typed Store.
+Never add a frontend status filter: generated SQL owns publishing, scope and TTL.
+
+In the Fetch entry, return a handled REST/web response, then render HTML for the
+remaining page routes. Insert `await site.head(request, env)` inside `<head>`:
+it supplies canonical and Markdown alternate tags from the current View row,
+using the configured origin rather than the request host. Escape all other
+application text. An unavailable page needs an application-owned 404; an empty
+`head()` result alone does not render that response.
+
+Verify locally before deploying:
+
+1. Generate, typecheck, implement every listed ref handler and typecheck again.
+2. Walk the public list's complete cursor chain. Its rows equal the `llms.txt`
+   entries and sitemap detail URLs below the documented index caps.
+3. Request each rendered page and assert its canonical uses the configured
+   origin and its `.md` alternate returns current Markdown. Request hidden
+   drafts, expired/scoped-out rows and malformed paths; they must not leak data.
+4. Check GET/HEAD, 404 `no-store` and escaped HTML. Importing no web entry should
+   keep web rendering code out of the application's bundle.
+
+The current caps are 5,000 scanned rows/10 queries/1 MiB for `llms.txt`, and
+50,000 rows/100 queries/50 MiB for sitemap. Translation-aware indexes and
+hreflang are a documented follow-up; do not claim them from `locales[0]`.

package/skills/mantle/references/website.md

@@ -0,0 +1,47 @@
+# Complete website defaults
+
+These are default generation and acceptance requirements for a complete website,
+unless the user explicitly changes the scope. They do not add Manifest keys or
+change Core's optional composition. Read the installed version's docs and the
+selected host's frontend kit before choosing APIs. Native applications use
+their installed `docs/handbook/guides/native-admin.md` and the
+[web contract](web.md).
+
+- Link to host-provided Mantle Admin UI and configured tenant OTP; do not emit frontend assets under host-owned /admin routes. Add visitor sign-in only where
+  needed. Do not build a second identity store or configure another mail provider
+  when the host already supplies one. Backend permissions enforce roles and data
+  access; Host membership is not application admin access.
+- Integrate image selection/upload into content editing through the existing
+  Admin media library and host storage. Follow the pinned Core upload/PUT/commit
+  contract and `x-mantle-ref: media_assets` plus `x-mcp-hint: media-image`; store committed asset IDs, resolve permanent variants in the frontend, never use an ID as an image URL. Tenant `/mcp/admin` supplies `get_media_upload_policy` → `create_media_upload` → direct HTTP PUT → `commit_media_upload` when its shared media adapter is wired. Follow the pinned media docs for tenant admin authentication (historical Core
+uses admin); host project credentials are not application credentials. Upload capability URLs are temporary,
+  not committed public images; anonymous visitors must not gain admin media access.
+- Generate an accessible, responsive public frontend by reading the installed
+  `@aotter/mantle/web` REST contract; browser code on static hosts uses
+  same-origin fetch, not a server surface imported into the browser. Do not install the historical standalone
+  `@aotter/mantle-web` or claim Core supplies an HTML renderer. Application-owned `service.fetch` may render HTML; follow the selected host's static/template and pairing restrictions.
+- Public content follows the installed `docs/handbook/guides/public-pages.md`
+  (the one list of head tags, JSON-LD, languages, Markdown, sitemap, robots and
+  `llms.txt`). For public content on static hosts disable SPA fallback and check unknown URLs
+  return 404. Follow the selected host's permanent origin contract. Missing
+  final origin blocks origin-dependent checks.
+  Structured data must match visible content; do not fabricate facts or promise
+  ranking or AI citation.
+- Verify that content publication, edits and deletion update the crawlable page
+  and sitemap. If static generation requires a rebuild, explain the publishing
+  dependency; a dynamic blog is blocked until that path exists. Do not silently
+  substitute build-time sample content for live tenant content.
+
+Before upload, follow the [local HTTP acceptance](local-testing.md): native HTTP HTML responses need no browser or deployment. Before reporting completion, inspect HTML without executing JavaScript, check
+metadata/sitemap and anonymous draft/permission refusal, and exercise OTP,
+content editing and media upload/commit with authorized synthetic accounts.
+Read the host's preview capability limits: disabled mail/media checks stay
+pending, not passed. Use candidate preview first, then an existing explicitly authorized live test
+tenant with authorized admin accounts for disabled services. Do not create or
+publish a test tenant without authorization. Live tests require
+explicit authorization for synthetic writes and cleanup. Without a published
+test tenant or that authorization, report them pending.
+Do not weaken preview isolation, fake success or grant admin privileges outside the authorized test scope to make
+checks pass. Provenance/pairing review does not certify website quality; report
+passed, failed and blocked checks separately. Pending required checks also
+block completion.