@aotter/mantle 0.2.0-alpha.2 → 0.2.0-alpha.3

package/docs/handbook/start/overview.md

@@ -43,6 +43,7 @@ After that they are your files.
 | Look up a field | [Feature table](../reference/features.md), then the [Schema](../reference/schema.md), [View](../reference/view.md), [Procedure](../reference/procedure.md) and [Trigger](../reference/trigger.md) references |
 | Wire sign-in, media or deploy | [Authentication](../cloudflare/authentication.md), [Media uploads with R2](../cloudflare/media-r2.md), [Deploy and operate](../cloudflare/deploy-and-operate.md) |
 | Run on ChatGPT Sites | [Mantle on ChatGPT Sites](../cloudflare/chatgpt-sites.md) |
+| Save, preview and publish on Mantle Cloud | [Mantle Cloud](../cloudflare/deploy-and-operate.md#mantle-cloud), then the plugin's `mantle` Cloud workflow |
 | See whole services | [Examples](../examples/hub.md) and the runnable reference service |
 | Move a 0.1.x project | `docs/upgrade-0.1-to-0.2.md` in the installed package |
 
@@ -60,4 +61,3 @@ check the code.
   `createMantle`. The Bun preset has no scheduler.
 - **Site settings and media on PostgreSQL.** Only the `sqlite` dialect's
   storage takes `SiteDefaults`; see [Site defaults](../reference/site-config.md).
-- **Deploying to Mantle Cloud.** See [Deploy and operate](../cloudflare/deploy-and-operate.md).

package/docs/handbook/start/project-and-cli.md

@@ -59,6 +59,13 @@ and stops before writing anything, naming the install command for your
 package manager. It never installs anything. The host and dialect rows, and the
 staff MCP App, are checked only while the preset is still to be written.
 
+Use the versions in the installed Core's `package.json` `peerDependencies`,
+not registry latest, for optional auth and MCP packages. The diagnostic's
+install command includes those versions and incompatible installed peers are
+refused before generation. Keep `@aotter/mantle-ui` at Core's
+exact version. A package manager accepting an incompatible peer does not make
+it a supported combination; inspect peer warnings before starting the service.
+
 | Selection | Packages |
 |---|---|
 | always | `@aotter/mantle` |

package/docs/handbook/start/quickstart-worker.md

@@ -112,12 +112,13 @@ pnpm exec mantle generate
 ```
 
 With no flags the selection is identity `mantle` and every feature. The first
-run names the packages it needs, with the install command, and writes nothing
-until they are installed:
+run names the packages it needs, with versioned install commands from the
+installed Core's `peerDependencies`, and writes nothing until they are installed
+at compatible versions. Copy those commands rather than installing registry
+latest; `@aotter/mantle-ui` must match Core's exact version:
 
 ```sh
-pnpm add better-auth @better-auth/oauth-provider @better-auth/mcp @better-auth/cimd \
-  @modelcontextprotocol/server @modelcontextprotocol/ext-apps @aotter/mantle-ui
+# Run each versioned pnpm add command printed above first.
 pnpm exec mantle generate
 cp .dev.vars.example .dev.vars   # set ADMIN_EMAIL and a random BETTER_AUTH_SECRET
 pnpm exec wrangler dev --local

package/docs/skills/develop/SKILL.md

@@ -66,6 +66,11 @@ Choose in this order, stopping at the first that works:
   published-only into public Views. Never repeat them.
 - `scope` hides rows from staff too. When staff must see every row, store
   `auth.uid()` in a field and filter on it instead.
+- That filter protects the View, not generic Admin Schema reads. Root
+  `schema.readOnly: true` blocks generic writes only. If a contributor must
+  not read other users' rows, restrict the application-owned Admin surface
+  inside its existing `withCaller` boundary; see
+  `docs/handbook/guides/admin-ui.md` (Roles). Keep business transitions in SQL.
 
 ## Handlers
 
@@ -112,6 +117,11 @@ Then exercise what changed over HTTP: the REST View or Trigger, `/mcp`
 sign-in and the Admin route (`docs/handbook/cloudflare/authentication.md`).
 Check the stored rows, not only a 200. Before deploying a Schema change on
 SQLite, run `mantle generate --check --database <file>` to see the storage SQL.
+For a workflow, verify valid and invalid state transitions, ownership on every
+mounted surface (including generic Admin reads and writes), concurrent writes
+with one expected version, and persisted data and sessions after a restart.
+Exercise the actual UI when the product includes one; serving HTML alone does
+not verify its forms or operations.
 
 ## Rules
 

package/docs/skills/develop/mcp-app.md

@@ -19,7 +19,7 @@ decision. Build it case by case from these pieces.
 | `SchemaFields` and the primitives | `@aotter/mantle-ui/kit`, styled by `@aotter/mantle-ui/kit.css` | Admin's form controls |
 
 The App's own build installs what it imports: `@modelcontextprotocol/ext-apps`
-at the exact version `@aotter/mantle` depends on, React and the kit's peers
+at the exact version in the installed Core's `peerDependencies`, React and the kit's peers
 (`@aotter/mantle-ui`'s README lists them). `docs/handbook/concepts/mcp-and-agents.md`
 (MCP Apps) describes the catalog and the staff App these share.
 

package/docs/skills/provision/SKILL.md

@@ -23,7 +23,7 @@ Ask which target, unless the project already shows one.
 |---|---|---|
 | Cloudflare Workers | `wrangler.jsonc` | the rest of this skill |
 | ChatGPT Sites | the Site's hosting config | installed `docs/handbook/cloudflare/chatgpt-sites.md`; publish through Sites, never `wrangler deploy` |
-| Mantle Cloud | — | not available for 0.2 services yet; the plugin's `mantle` skill says when it is |
+| Mantle Cloud | Cloud project link | the plugin's `mantle` skill and its Cloud workflow; connect Cloud MCP and use its exact host contract, not `wrangler deploy` |
 | Bun (host `bun`) | `.env` | self-hosted; installed `docs/handbook/start/project-and-cli.md` (Bun), not this skill |
 
 Self-hosting is always an option; never present a hosted target as required.
@@ -58,8 +58,9 @@ Confirm the active Cloudflare account with the user before creating anything.
      and `bootstrapOwner: { match: "github-login", value }`. The user creates a
      GitHub OAuth App with callback `<PUBLIC_ORIGIN>/api/auth/callback/github`.
    Remove the preset's loopback-only check once the method is real.
-4. **Secrets.** Never in chat, files or logs. Use a connector, or hidden
-   input:
+4. **Secrets.** Never commit them or put them in chat, logs or `wrangler.jsonc`
+   `vars`. Store production values in the deployment's secret store. Use a
+   connector, or hidden input:
 
 ```bash
 openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET

package/docs/skills/update/SKILL.md

@@ -27,6 +27,12 @@ Upgrade deliberately; never overwrite application-owned code.
    `@aotter/mantle-ui/admin`), and update the lockfile with the
    package manager. Review the dependency diff and any peer changes
    `mantle generate` names.
+   With identity `mantle`, inspect auth database upgrade requirements in
+   `docs/handbook/cloudflare/authentication.md` before starting the new service.
+   Better Auth 1.7.0–1.7.2's required legacy `account.issuer` needs a
+   data-preserving host-specific constraint migration when moving to 1.7.7;
+   fresh-database success alone does not verify an upgrade. Back up the service's
+   own database and retain existing users, sessions, roles and content.
 5. Regenerate and check:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.3",
   "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/",
@@ -85,33 +85,35 @@
     "libpg-query": "18.1.5",
     "pgsql-deparser": "18.3.8",
     "yaml": "^2.9.0",
-    "zod": "^4.5.4"
+    "zod": "^4.5.4",
+    "semver": "^7.8.5"
   },
   "devDependencies": {
-    "@better-auth/cimd": "1.7.2",
-    "@better-auth/core": "1.7.2",
-    "@better-auth/mcp": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
+    "@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.2",
+    "better-auth": "1.7.7",
     "bun-types": "1.3.14",
     "pg": "8.23.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
-    "wrangler": "4.126.0"
+    "wrangler": "4.126.0",
+    "@types/semver": "^7.7.1"
   },
   "peerDependencies": {
-    "@better-auth/cimd": "1.7.2",
-    "@better-auth/mcp": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
+    "@better-auth/cimd": "1.7.7",
+    "@better-auth/mcp": "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.2"
+    "better-auth": "1.7.7"
   },
   "peerDependenciesMeta": {
     "@better-auth/cimd": {