@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.1-alpha.1",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -20,9 +20,9 @@
     "jsonc-parser": "3.3.1",
     "@pgsql/types": "18.0.0",
     "libpg-query": "18.1.5",
-    "pgsql-deparser": "18.3.8",
+    "pgsql-deparser": "18.3.10",
     "yaml": "^2.9.1",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "exports": {
     ".": "./dist/infrastructure/generate.js",
@@ -72,7 +72,7 @@
     "./target-hash": "./dist/domain/describe/target-hash.js"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/server": "2.3.1",
     "@better-auth/core": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",
     "better-auth": "1.7.7"
@@ -92,21 +92,38 @@
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "2.2.0",
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@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",
+    "@cloudflare/workers-types": "^5.20261027.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"
+    "wrangler": "4.153.0",
+    "vitest": "^5.0.4"
   },
-  "description": "Mantle: a manifest-driven service core. Store authored as SQL, surfaces as Fetch functions, and the mantle CLI.",
+  "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": {
@@ -114,13 +131,16 @@
     "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": {
-    "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",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.lib.json && node ../../scripts/strip-comments.mjs 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",

package/skills/README.md

@@ -18,6 +18,7 @@ distributions (ADR-0032 decision 13):
 | [`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. |
+| [`performance`](../docs/skills/performance/SKILL.md) | Make an accepted app fast: Lighthouse, cold start, backend load, indexes and Views. Runs after acceptance converges. |
 
 ## Install
 
@@ -27,10 +28,12 @@ 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 https://github.com/aotter/mantle/tree/v0.2.0-alpha.9 --skill mantle
+npx skills add aotter/mantle@mantle
 ```
 
-The explicit skill name excludes repository maintainer skills. The manifests
+Without a version it follows `main`, the latest stable release; pin the SDK's
+release tag with `npx skills add aotter/mantle#v0.2.1-alpha.1@mantle`.
+The explicit skill name (`@mantle`) 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
@@ -53,6 +56,7 @@ each other: `metadata.projection` is `plugin` for `skills/mantle` and
 | `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. |
+| `performance` | converged acceptance, a slow page, first request or query | accepted behavior only; never trade scope, authorization, OCC or atomicity for speed; local unless deployment is authorized | package | — |
 
 ## Audience
 

package/skills/mantle/SKILL.md

@@ -17,9 +17,19 @@ 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
 
@@ -28,130 +38,53 @@ Work in the user's application, outside the SDK checkout. Read package.json, the
 - 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.
+- Read `node_modules/@aotter/mantle/docs/skills/performance/SKILL.md` after acceptance converges, or when a page, first request or query is slow.
 
-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. `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the Wrangler, TypeScript and type-package versions this release is tested with. 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.
-
-Before reporting any user-facing work as done, follow the installed
-`node_modules/@aotter/mantle/docs/handbook/guides/agent-workflow-acceptance.md`:
-run independent acceptance with a fresh agent on the surface its user uses.
-This is not limited to MCP; if it was not run, say so explicitly and report the
-work as UNVERIFIED rather than done. For MCP workflows, also run the guide's
-design audit before implementing tools. This workflow practice applies to every
-installed SDK version: if its guide is older or MCP-scoped, apply its fresh-agent
-round loop to the user-facing surface actually built. If an older installed
-version lacks this guide, record the missing guidance and preserve that version's
-contract; do not silently upgrade or substitute checkout/online docs.
-
-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 → implement listed handlers → check**. In an app
-copied from the installed app shell, its scripts are the canonical commands:
-
-```sh
-pnpm generate
-pnpm check
-```
-Implement every printed `Handlers` key
-and pass the implementations at `store(db, caller, { handlers })` (and selected
-surface options).
-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.
-Pair every HTTP Trigger with an MCP Trigger by default; see `docs/handbook/reference/trigger.md` for the generate warning and deliberate asymmetry exception.
-
-For selected native Admin, follow the version-matched
-`docs/handbook/guides/native-admin.md`: select `--admin` (or `admin: true`), then
-build and serve the application-owned Admin with `mantle bundle` as that guide
-describes.
-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 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 selected interfaces; compilation does not execute their behavior. Account for every declared interface as verified, intentionally not exposed, or deferred/unverified with a reason in the existing application handoff. An early preview may defer remote MCP; preserve that pending work. WebMCP, cookie-session discovery and OAuth Bearer/client integration are separate checks.
-
-## 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.
+## New application
 
-## Existing project and handoff
+Node must be 22.22 or newer. Stable 0.2.0 is available as `@aotter/mantle@0.2.0`; pin selected Mantle packages to that exact version. 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`), then the installed `docs/skills/performance/SKILL.md`.
+
+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`).
 
-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 and public-fetch compatibility flags. Run the same generation command (target, output directory,
-manifests and options) with `--check`, and the project's own tests,
-before and after a change.
+## Accept before reporting done
 
-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.
+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. The first
+delivery covers every role and surface; after a repair, the guide's "Re-verify what a repair touches" rule decides what
+re-runs: a page-only repair re-runs the affected UI, while auth, scope, SQL Procedure, unique index or shared-transport changes widen
+to every surface they reach. State the round and revision of any evidence you reuse. If it was
+not run, report the work as UNVERIFIED rather than done; if it could not run, BLOCKED. Report status per layer as that
+guide's "Report done-ness in layers" defines; a block from your environment (approval policy, missing browser,
+network) is BLOCKED on its layer, not a product failure, and does not discard the other layers.
 
-Report the project path, the exact Mantle version, what you changed, the checks
-you ran with their results, the independent acceptance verdict (CONVERGED / NOT
-CONVERGED / BLOCKED / UNVERIFIED), and anything left for the user.
+Once acceptance is CONVERGED, read the installed `docs/skills/performance/SKILL.md`: it decides which of front end,
+cold start and backend load apply, and runs them before you report done. This is the one exception to installed docs
+winning: if the installed package predates that skill, read
+[the 0.2.1 copy](https://github.com/aotter/mantle/blob/v0.2.1/docs/skills/performance/SKILL.md) and the pages it links
+from the installed docs with `mantle help <topic>`.
+
+## 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
 
-## Data paths
+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.
 
-Follow the installed `docs/handbook/guides/typed-queries.md` for Store,
-Procedure and View data paths; the service composition guide owns request-local
-Caller binding.
+Report the project path, the exact Mantle version, what you changed, the four-layer status with each layer's checks
+and results (the independent acceptance verdict, CONVERGED / BLOCKED / UNVERIFIED, is layer 3), the performance verdict
+(PASS / PARTIAL / SKIPPED) with its before and after numbers, and anything left for the user, including what would
+unblock a BLOCKED layer.