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

package/package.json

@@ -1,149 +1,133 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.6",
-  "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.1",
-    "zod": "^4.6.5",
-    "semver": "^7.8.5"
+    "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": "^5.0.1",
-    "@cloudflare/workers-types": "^5.20261008.1",
-    "wrangler": "4.137.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.

package/dist/admin/consent.d.ts

@@ -1,17 +0,0 @@
-/** What the consent screen and the connected-apps list need of an OAuth provider, and the member list's cursor (Admin's, used by the identity provider). */
-export interface OAuthConsentRequest {
-    readonly clientName: string;
-    readonly redirectUri: string;
-    readonly scopes: readonly string[];
-    /** Signed provider query returned unchanged with the consent decision. */
-    readonly oauthQuery: string;
-}
-export interface OAuthConsentInfo {
-    readonly id: string;
-    readonly clientId: string;
-    readonly clientName: string;
-    readonly scopes: readonly string[];
-}
-export declare function encodeMemberCursor(createdAt: string, id: string): string;
-export declare function decodeMemberCursor(cursor: string): readonly [string, string] | null;
-//# sourceMappingURL=consent.d.ts.map

package/dist/admin/consent.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/admin/consent.ts"],"names":[],"mappings":"AAAA,4JAA4J;AAE5J,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAID,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQnF"}

package/dist/admin/consent.js

@@ -1,17 +0,0 @@
-/** What the consent screen and the connected-apps list need of an OAuth provider, and the member list's cursor (Admin's, used by the identity provider). */
-const PREFIX = "m:";
-export function encodeMemberCursor(createdAt, id) {
-    return `${PREFIX}${encodeURIComponent(JSON.stringify([createdAt, id]))}`;
-}
-export function decodeMemberCursor(cursor) {
-    if (!cursor.startsWith(PREFIX))
-        return null;
-    try {
-        const v = JSON.parse(decodeURIComponent(cursor.slice(PREFIX.length)));
-        return Array.isArray(v) && v.length === 2 && typeof v[0] === "string" && !Number.isNaN(Date.parse(v[0])) && typeof v[1] === "string" && v[1] ? [v[0], v[1]] : null;
-    }
-    catch {
-        return null;
-    }
-}
-//# sourceMappingURL=consent.js.map

package/dist/admin/consent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"consent.js","sourceRoot":"","sources":["../../src/admin/consent.ts"],"names":[],"mappings":"AAAA,4JAA4J;AAiB5J,MAAM,MAAM,GAAG,IAAI,CAAC;AAEpB,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,EAAU;IAC9D,OAAO,GAAG,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAY,CAAC;QACjF,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrK,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/admin/createAdminSurface.d.ts

@@ -1,25 +0,0 @@
-import { type MantleRuntime, type MediaStorage, type Surface } from "../core/index.js";
-import type { AdminIdentity } from "./identity.js";
-import { type AdminExtension } from "./extensions.js";
-/** The built SPA: `path` is relative to the base path (`index.html` is the shell). `null` is a missing file. */
-export type AdminAssets = (path: string) => Response | null | Promise<Response | null>;
-export interface AdminSurfaceOptions {
-    /** Where Admin answers, e.g. `/admin`; the API is `{basePath}/api`. */
-    readonly basePath: string;
-    readonly identity?: AdminIdentity;
-    /** The Admin SPA's files (`@aotter/mantle-ui/admin`), which are built for `basePath: "/admin"` only. */
-    readonly assets?: AdminAssets;
-    /** The MCP surfaces the service mounted, as paths or URLs; `/site` resolves them against the public URL. */
-    readonly site?: {
-        readonly mcpEndpoints?: {
-            readonly public: string | null;
-            readonly staff: string | null;
-        };
-    };
-    /** Media objects; the media routes also need `runtime.site`, which owns the tables, and answer 501 without either. */
-    readonly media?: MediaStorage;
-    /** Admin extensions (ADR-lite 1376): the project's `adminExtensions`, then any the host adds. */
-    readonly extensions?: readonly AdminExtension[];
-}
-export declare function createAdminSurface(runtime: MantleRuntime, options: AdminSurfaceOptions): Surface;
-//# sourceMappingURL=createAdminSurface.d.ts.map

package/dist/admin/createAdminSurface.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"createAdminSurface.d.ts","sourceRoot":"","sources":["../../src/admin/createAdminSurface.ts"],"names":[],"mappings":"AAQA,OAAO,EAAkD,KAAK,aAAa,EAAmB,KAAK,YAAY,EAAiH,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAKvQ,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,eAAe,CAAC;AAElF,OAAO,EAAuJ,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3M,gHAAgH;AAChH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AAEvF,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,wGAAwG;IACxG,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,YAAY,CAAC,EAAE;YAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAA;KAAE,CAAC;IAC9G,sHAAsH;IACtH,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,iGAAiG;IACjG,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAmHD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAoehG"}