@aotter/mantle 0.2.0-alpha.8 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "2.1.0",
+    "@modelcontextprotocol/client": "2.2.0",
     "@modelcontextprotocol/server": "2.2.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",
@@ -106,7 +106,24 @@
     "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.",
+  "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

@@ -27,7 +27,7 @@ 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.8 --skill mantle
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0 --skill mantle
 ```
 
 The explicit skill name excludes repository maintainer skills. The manifests

package/skills/mantle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mantle
-description: Create or continue a Mantle application, test it locally and deploy to a user-owned host using the installed SDK docs.
+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
@@ -17,119 +17,60 @@ 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.
 
-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.
-
-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 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.
+## Choose the installed package skill
 
-## Existing project and handoff
+- 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. 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:
 
-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.
+- 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`).
 
-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.
+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`).
 
-Report the project path, the exact Mantle version, what you changed, the checks
-you ran with their results, and anything left for the user.
+## 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
 
-## 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.
 
-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.
+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.