@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/package.json

@@ -1,165 +1,154 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.5-alpha.1",
-  "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Auth, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
-  "license": "Apache-2.0",
-  "homepage": "https://mantle.tools/",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aotter/mantle.git",
-    "directory": "packages/mantle"
-  },
+  "version": "0.2.0-alpha.10",
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/spec.js",
-  "types": "./dist/spec.d.ts",
-  "bin": {
-    "mantle": "./dist/cli/main.js",
-    "mantle-harness": "./dist/cli/harness.js"
-  },
-  "publishConfig": {
-    "access": "public",
-    "tag": "alpha",
-    "registry": "https://registry.npmjs.org"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/spec.d.ts",
-      "import": "./dist/spec.js"
-    },
-    "./spec": {
-      "types": "./dist/spec.d.ts",
-      "import": "./dist/spec.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime.d.ts",
-      "import": "./dist/runtime.js"
-    },
-    "./runtime/testing": {
-      "types": "./dist/runtime-testing.d.ts",
-      "import": "./dist/runtime-testing.js"
-    },
-    "./codegen": {
-      "types": "./dist/codegen.d.ts",
-      "import": "./dist/codegen.js"
-    },
-    "./web": {
-      "types": "./dist/web.d.ts",
-      "import": "./dist/web.js"
-    },
-    "./admin": {
-      "types": "./dist/admin.d.ts",
-      "import": "./dist/admin.js"
-    },
-    "./auth": {
-      "types": "./dist/auth.d.ts",
-      "import": "./dist/auth.js"
-    },
-    "./bun": {
-      "types": "./dist/bun.d.ts",
-      "import": "./dist/bun.js"
-    },
-    "./vercel": {
-      "types": "./dist/vercel.d.ts",
-      "import": "./dist/vercel.js"
-    },
-    "./vercel/libsql": {
-      "types": "./dist/vercel-libsql.d.ts",
-      "import": "./dist/vercel-libsql.js"
-    },
-    "./cloudflare": {
-      "types": "./dist/cloudflare.d.ts",
-      "import": "./dist/cloudflare.js"
-    },
-    "./admin-ui": {
-      "types": "./dist/admin-ui.d.ts",
-      "import": "./dist/admin-ui.js"
-    }
+  "engines": {
+    "node": ">=22.22.0"
   },
   "files": [
     "dist",
     "docs",
     "skills",
-    "templates",
     "README.md"
   ],
+  "bin": {
+    "mantle": "./dist/infrastructure/cli.js"
+  },
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.5-alpha.1",
-    "@aotter/mantle-spec": "0.1.5-alpha.1"
+    "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"
+  },
+  "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": {
-    "aws4fetch": "^1.0.20",
-    "better-auth": "1.7.2",
-    "hono": "^4.12.0",
-    "@libsql/client": "^0.17.4",
-    "zod": "^4.5.0",
-    "@aotter/mantle-admin": "0.1.5-alpha.1",
-    "@aotter/mantle-admin-ui": "0.1.5-alpha.1",
-    "@aotter/mantle-auth": "0.1.5-alpha.1",
-    "@aotter/mantle-bun": "0.1.5-alpha.1",
-    "@aotter/mantle-cloudflare": "0.1.5-alpha.1",
-    "@aotter/mantle-vercel": "0.1.5-alpha.1",
-    "@aotter/mantle-web": "0.1.5-alpha.1"
+    "@modelcontextprotocol/server": "2.2.0",
+    "@better-auth/core": "1.7.7",
+    "@better-auth/oauth-provider": "1.7.7",
+    "better-auth": "1.7.7"
   },
   "peerDependenciesMeta": {
-    "@aotter/mantle-admin": {
-      "optional": true
-    },
-    "@aotter/mantle-admin-ui": {
-      "optional": true
-    },
-    "@aotter/mantle-auth": {
-      "optional": true
-    },
-    "@aotter/mantle-bun": {
+    "@modelcontextprotocol/server": {
       "optional": true
     },
-    "@aotter/mantle-cloudflare": {
+    "@better-auth/core": {
       "optional": true
     },
-    "@aotter/mantle-vercel": {
-      "optional": true
-    },
-    "@aotter/mantle-web": {
-      "optional": true
-    },
-    "aws4fetch": {
+    "@better-auth/oauth-provider": {
       "optional": true
     },
     "better-auth": {
       "optional": true
-    },
-    "hono": {
-      "optional": true
-    },
-    "@libsql/client": {
-      "optional": true
     }
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.2.0",
+    "@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",
-    "aws4fetch": "^1.0.20",
-    "better-auth": "1.7.2",
-    "hono": "^4.13.7",
-    "@libsql/client": "^0.17.4",
+    "better-auth": "1.7.7",
+    "bun-types": "1.4.2",
+    "postgres": "3.4.9",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
-    "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.5-alpha.1",
-    "@aotter/mantle-admin-ui": "0.1.5-alpha.1",
-    "@aotter/mantle-auth": "0.1.5-alpha.1",
-    "@aotter/mantle-bun": "0.1.5-alpha.1",
-    "@aotter/mantle-cloudflare": "0.1.5-alpha.1",
-    "@aotter/mantle-vercel": "0.1.5-alpha.1",
-    "@aotter/mantle-web": "0.1.5-alpha.1"
+    "wrangler": "4.145.0",
+    "vitest": "^5.0.1"
   },
-  "engines": {
-    "node": ">=22"
+  "description": "Agent-native app SDK and backend compiler: YAML manifests to native SQL (SQLite, Cloudflare D1, PostgreSQL) and typed TypeScript; optional REST and MCP.",
+  "keywords": [
+    "mantle",
+    "agent-native",
+    "sdk",
+    "backend",
+    "yaml",
+    "code-generation",
+    "sql",
+    "sqlite",
+    "postgresql",
+    "cloudflare-d1",
+    "cloudflare-workers",
+    "bun",
+    "typescript",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://mantle.tools/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aotter/mantle.git",
+    "directory": "packages/mantle"
+  },
+  "bugs": {
+    "url": "https://github.com/aotter/mantle/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "prebuild": "rm -rf dist .tsbuildinfo",
-    "build": "tsc -b tsconfig.lib.json",
-    "typecheck": "tsc --noEmit -p tsconfig.lib.json",
-    "test": "vitest run"
+    "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": "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

@@ -1,127 +1,67 @@
 # SKILL.md briefs (mantle)
 
-Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by URL — no plugin install needed.
+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 |
 |---|---|
-| [`develop`](../docs/skills/develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
-| [`integrate`](../docs/skills/integrate/SKILL.md) | `mantle:integrate`: choose and carry out an existing application's Mantle integration or rebuild and data migration. |
-| [`media-gc`](../docs/skills/media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
-| [`plugin`](../docs/skills/plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across applications and adapters. |
-| [`theme`](../docs/skills/theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project-owned theme and UI contracts. |
-| [`update`](../docs/skills/update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK dependencies, local skills, and plugin lockfiles. |
-| [`mantle`](install/SKILL.md) | User wants to author a local Mantle application or continue an existing project. |
-| [`provision`](../docs/skills/provision/SKILL.md) | User wants a local project shipped to Cloudflare with production auth and operator handoff. |
-
-The skills target Mantle's v0.1 grammar. The installed package version, not
-duplicated skill prose, selects the exact runtime and embedded docs.
-
-## Disclosure audit
-
-Every skill ships as one `SKILL.md` with no reference files, scripts, or
-assets, so nothing is deferred behind a second load. Progressive disclosure
-here is section routing inside one file: the agent reads the entry constraints,
-then only the section its selected path names. `scripts/check-skills.mjs`
-enforces the columns below.
-
-| Skill | Routes on | Entry-path constraints (read before acting) | Path-gated sections | Projection | Restricted because |
-|---|---|---|---|---|---|
-| `develop` | existing project; manifest, runtime, handler, adapter, or MCP work | four-atom model; adapter neutrality; no direct D1/KV/Postgres writes; no committed secrets | performance harness; local MCP client; locale rules | project | — |
-| `integrate` | independently authored application; add Mantle or rebuild with migration | inspect application before strategy; version-matched SDK; protect live data | embed; incrementally replace; rebuild and migrate | package | Existing-project migration is opt-in; a fresh generated app does not need this brief. |
-| `plugin` | user wants an installable capability | plan before apply; lock entry is the removal manifest; delete only plugin-owned files and atoms | apply; remove | project | — |
-| `theme` | brand or visual direction in a project | repo-owned theme and UI contracts | — | project | — |
-| `update` | SDK upgrade or plugin lock review | never blindly overwrite user-owned code | — | project | — |
-| `mantle` | new application, or opening an existing project | do not use the SDK checkout as the application; no push/deploy/provider config during cold start | author local project; continue existing project | plugin | Creates a new project; nothing to project into an existing one. |
-| `provision` | ship to Cloudflare and finish production auth | secrets never enter source or logs; explicit auth mode | hosted auth; self-managed auth | package | Platform-specific deploy that handles production secrets; opt-in only. |
-| `media-gc` | audit or remove stale uncommitted media objects | audit by default; confirm exact account, bucket, cutoff, and candidate digest; re-audit before applying; never prefix-delete; never print keys | apply | package | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
-
-Deliberately monolithic:
-
-- `develop` is the widest file, but its adapter, auth, and data-ownership rules
-  constrain every path through it. Splitting them behind routing would let an
-  agent reach a write path without them, which is the failure this audit
-  exists to prevent.
-- `media-gc` keeps its full audit-confirm-reapply sequence inline for the same
-  reason: each safeguard is a precondition of the delete that follows it.
-
-## Skill authority
-
-The `mantle:*` namespace is owned by `@aotter/mantle`. Every skill declares its
-own distribution scope in front matter: `metadata.projection: project` marks a
-skill `mantle skills` should place in a consumer project, and a skill that
-withholds `project` must say why. `plugin` is the bootstrap skill and `package`
-is an opt-in brief in the installed SDK. `scripts/check-skills.mjs` holds that
-declaration and the audit table below to each other.
+| [`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. |
 
-Run `mantle skills` to project the installed package's skills into a project;
-use `mantle skills --check` to fail closed on drift. The installed package and
-`node_modules/@aotter/mantle/docs/` are the single version-matched authority.
-Application files and plugin recipes are project context, not competing
-contracts.
+## Install
 
-## Source-repository marketplace install
-
-`skills/install/SKILL.md` declares `name: mantle`. It is the only repository
-skill discovered by the no-flag command and copied as a small directory.
-The other seven skills live in `docs/skills/` and ship with the npm package.
-`mantle skills` projects the four ongoing workflows after package installation.
-
-Other marketplace hosts point to the same entry:
+Use the [agent setup guide](../docs/handbook/guides/agent-setup.md) for Codex,
+Claude Code, Cursor and GitHub Copilot. Pin the plugin checkout to the same
+release tag as the application's SDK; alpha releases on `develop` can be newer
+than the default `main` branch. For a skill-only installation:
 
 ```sh
-npx skills add aotter/mantle
-```
-
-```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
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.10 --skill mantle
 ```
 
-Read the path printed by the installer (for project-local Codex,
-`.agents/skills/mantle/SKILL.md`). Only the selected brief is installed, not
-the SDK or handbook. After choosing and installing an exact SDK version, read
-`node_modules/@aotter/mantle/skills/install/SKILL.md` and its embedded docs;
-that package supersedes the bootstrap Git-ref instructions. After packages are
-installed, `mantle skills` projects the installed package's own skills into the
-project, and `mantle skills --check` fails on drift.
+The explicit skill name excludes repository maintainer skills. The manifests
+are generated by `scripts/sync-plugin-manifests.mjs` and checked with `--check`.
+When upgrading, update the marketplace ref or local tagged checkout and refresh
+the plugin. Verify the loaded manifest version; Claude Code's plugin version
+is Core's, so packaged skill changes reach users through the next Core release.
 
-Cursor and GitHub Copilot read their manifests from the repository directly.
-These manifests are not duplicated into the npm package:
+## Disclosure audit
 
-- Claude Code: `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json`.
-- Codex: `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json`.
-- Cursor: `.cursor-plugin/plugin.json`.
-- VS Code + GitHub Copilot: `.copilot-plugin/plugin.json`.
+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 written for **AI agents acting on behalf of consumers of mantle**,
-not for contributors maintaining the Mantle SDK itself. SDK contributors use
-the repo-root `CONTRIBUTING.md`; it is intentionally not shipped inside the npm
-package. Two audiences, two artifacts.
-
-## Discoverability
-
-The skills target ADR-0007's "AI as primary author" thesis: agents reach these files by URL when the user invokes them by intent ("install mantle", "develop my Mantle site", "deploy"). Official cold start is `npx skills add aotter/mantle`. Point the agent at the repository or pass the version-matched markdown content directly.
+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 ships:
-
-- **Front-matter** with a stable `name`, trigger-complete
-  `description`, and optional source/version `metadata`. Plugin hosts add the
-  external `mantle:` namespace.
-- **Preflight** section — environment + user-confirmation gates.
-- **Step-by-step** — concrete commands (`pnpm validate`, `mantle emit-openapi`, etc.).
-- **Diagnostic recipes** — `Symptom → Cause → Fix` table for the common failure modes.
-- **Don't** — reviewer-style list of patterns the agent must reject (often citing ADRs).
-- **When you're done** — what to report back to the user.
-
-If you're writing a new SKILL, follow the same structure. Commands and prose
-must match the package version that carries the skill; later prereleases may
-revise both together.
+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,76 @@
+---
+name: mantle
+description: Create, continue, test or deploy a Mantle application using installed @aotter/mantle docs, including manifests, SQL Views and Procedures, MCP tools, app-built Admin, mantle generate and Mantle upgrades.
+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.
+
+## Start with `mantle help`
+
+Run `mantle help` first (in a project: `npx mantle help`; before one exists:
+`npx @aotter/mantle@<exact version> help`). It prints the installed version's
+entry page and every topic; `mantle help <topic>` prints one page with the next
+and linked topics as commands. Follow it rather than browsing the SDK checkout
+or an 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 existing older applications, use their installed docs until the user requests an upgrade; if an older version
+lacks a guide named here, record the missing guidance and keep that version's contract.
+
+## Choose the installed package skill
+
+- Read `node_modules/@aotter/mantle/docs/skills/develop/SKILL.md` to change an existing project's manifests, SQL, handlers, service entry or surfaces.
+- Read `node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md` to add Mantle to an application with existing code, users or data.
+- Read `node_modules/@aotter/mantle/docs/skills/update/SKILL.md` to upgrade Mantle, including from 0.1.x.
+- Read `node_modules/@aotter/mantle/docs/skills/provision/SKILL.md` only for an authorized production deployment.
+- Read `node_modules/@aotter/mantle/docs/skills/media-gc/SKILL.md` only to audit or remove stale uncommitted media uploads.
+
+## New application
+
+Node must be 22.22 or newer. Create it with `npx @aotter/mantle@<exact version> init <directory>`, then follow
+`mantle help` ("Build from a product brief") and the app's `README.md`. Without the user listing them, a complete app
+includes:
+
+- Email OTP sign-in, the two roles `admin` and `user`, Admin for `admin`, MCP for both roles (`/mcp`, `/mcp/admin`)
+  and REST: the shell already wires them; keep them.
+- Real business rules in SQL Procedures (`mantle help sql-patterns`), not in handler code around separate writes.
+- For visitor pages, everything in `mantle help public-pages` (SEO, AEO, sitemap, robots, `llms.txt`), styled.
+- Local HTTP checks (`mantle help local-testing`), then independent acceptance with `pnpm accept`
+  (`mantle help agent-workflow-acceptance`).
+
+Take patterns from `mantle help examples` into the app's own manifests and `src/`; do not copy an example directory
+over the app. Resolve each `AGENT:` or name the ones you left. Generation only, inside an app you already have: skip
+`init` and use `mantle generate` (`mantle help project-and-cli`).
+
+## Accept before reporting done
+
+Before reporting any new app or feature as done, follow `mantle help agent-workflow-acceptance`: a private rubric,
+then one fresh agent per role given only its role and the URLs `pnpm accept` prints, at most three rounds. If it was
+not run, report the work as UNVERIFIED rather than done; if it could not run, BLOCKED.
+
+## Deployment
+
+Deploy only when the user requests it, following the installed `docs/skills/provision/SKILL.md` and the selected
+host'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. Run the project's
+generate command with `--check` and its own tests before and after a change.
+
+Report the project path, the exact Mantle version, what you changed, the checks you ran with their results, the
+independent acceptance verdict (CONVERGED / BLOCKED / UNVERIFIED), and anything left for the user.

package/dist/admin-ui.d.ts

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-admin-ui";
-//# sourceMappingURL=admin-ui.d.ts.map

package/dist/admin-ui.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"admin-ui.d.ts","sourceRoot":"","sources":["../src/admin-ui.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/admin-ui.js

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-admin-ui";
-//# sourceMappingURL=admin-ui.js.map

package/dist/admin-ui.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"admin-ui.js","sourceRoot":"","sources":["../src/admin-ui.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/admin.d.ts

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-admin";
-//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/admin.js

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-admin";
-//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/auth.d.ts

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-auth";
-//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}

package/dist/auth.js

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-auth";
-//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}

package/dist/bun.d.ts

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-bun";
-//# sourceMappingURL=bun.d.ts.map

package/dist/bun.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/bun.js

@@ -1,2 +0,0 @@
-export * from "@aotter/mantle-bun";
-//# sourceMappingURL=bun.js.map

package/dist/bun.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"bun.js","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/cli/generate-cloudflare.d.ts

@@ -1,7 +0,0 @@
-import { type ProjectSelection } from "./generate-project.js";
-/** Prepare all paths before the caller commits any project files. */
-export declare function prepareCloudflare(root: string, output: string, selection: ProjectSelection, fresh: boolean): Promise<{
-    readonly stale: boolean;
-    readonly commit: () => Promise<void>;
-}>;
-//# sourceMappingURL=generate-cloudflare.d.ts.map

package/dist/cli/generate-cloudflare.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate-cloudflare.d.ts","sourceRoot":"","sources":["../../src/cli/generate-cloudflare.ts"],"names":[],"mappings":"AAEA,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAInF,qEAAqE;AACrE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAC1H,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC,CAAC,CAuFD"}