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

package/skills/README.md

@@ -21,25 +21,20 @@ distributions (ADR-0032 decision 13):
 
 ## Install
 
-```bash
-# Claude Code: two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
+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:
 
-# Codex
-codex plugin marketplace add aotter/mantle
-codex plugin add mantle@mantle
+```sh
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.8 --skill 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.
+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.
 
 ## Disclosure audit
 

package/skills/mantle/SKILL.md

@@ -21,7 +21,7 @@ checkout, or any online copy.
 
 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 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.
 
@@ -89,7 +89,7 @@ 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.
+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
@@ -107,7 +107,7 @@ 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.
+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
 
@@ -120,7 +120,7 @@ workflow. Local project creation alone is not deployment authorization.
 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,
+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.
 

package/skills/mantle/references/local-testing.md

@@ -7,5 +7,9 @@ Better Auth limits each email-OTP path to 3 requests/minute per IP; `authHardeni
 
 - 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`.
+- If the app serves Admin, run `npm run build` and then `node --test generated/admin-mcp-app.check.mjs` (the examples name it `npm test`): the generated `generated/admin-mcp-app.check.mjs` loads the Admin MCP App in an MCP host and fails on a network request, console error or exception. It needs `playwright-core` (a devDependency) and Chrome (`npx playwright-core install chromium` or `MANTLE_TEST_CHROMIUM`); with no browser it fails, so report it as blocked rather than skipped. See `docs/handbook/guides/mcp-apps.md`.
 - 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.
+- Account for each declared interface separately: verified with the command/identity/result, intentionally not exposed, or deferred/unverified with a reason. Generation proves declaration and artifacts, not route mounting. An early Admin preview or a WebMCP-only application may defer remote MCP; preserve that pending item in the application's existing README, handoff or test report, without a new status/configuration format.
+- For selected remote MCP, use the installed `docs/examples/app-shell/smoke-kit.mjs` `assertMcpDiscovery(endpoint, { tools, headers })` in the application's smoke scenario. Derive `tools` from the generated `mcp.ts` exports, or the pure static `developerConsole.interfaces.callable` in generated `admin-descriptors.ts`; filter to the selected surface and explicitly select the expected permitted subset when application authorization narrows it. Include app-composed tools when present. Do not count `describe.targets` or reconstruct authorization rules in the harness. Assert initialized discovery and all `tools/list` pages; a 404, HTML 200, protocol error or missing expected tools must fail. Keep anonymous/member denial assertions separate. Discovery never needs a business-write `tools/call`.
+- Supply test credentials from the application's normal authorized sign-in/test setup (the smoke kit's console OTP sign-in is valid). The discovery assertion only receives credentials: it must not acquire credentials itself, scrape other sessions or manufacture authority. Report local cookie-session discovery, OAuth Bearer/client integration and browser WebMCP as separate evidence. Cookie or WebMCP success does not prove remote OAuth/ChatGPT wiring; missing credentials leave that case unverified, not passed. Do not enable remote routes or OAuth merely to make acceptance pass.
 - 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

@@ -3,7 +3,7 @@
 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
+`docs/handbook/reference/surface.md` and `docs/examples/generated-web/README.md` under `node_modules/@aotter/mantle/` before writing
 routes; the installed version is authoritative.
 
 Mount `web()` when the application serves public HTML and needs `llms.txt`, a

package/skills/mantle/references/website.md

@@ -7,19 +7,21 @@ 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.
+- For self-hosted applications, mount the selected Admin API and serve the
+  separate Admin package's assets with its shell/CSP contract. The application
+  owns auth, OTP delivery and verified Caller wiring; use a console/test sender
+  locally and configure production email for deployment. If a host already
+  supplies identity/Admin, reuse its explicit contract and reserved routes.
+  Add visitor sign-in where needed. Backend permissions enforce roles and data
+  access; host membership alone is not application admin authority.
 - 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,
+  Admin media library and the application's selected 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. The application's `/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 installed media authentication contract; 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
+  generated `web.ts` and REST contracts; 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.
+  `@aotter/mantle-web` or claim Core supplies an HTML renderer. The application-owned Fetch entry renders HTML; follow the selected host's static/template 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
@@ -32,16 +34,16 @@ uses admin); host project credentials are not application credentials. Upload ca
   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.
+Follow the [local HTTP acceptance](local-testing.md) before reporting local
+readiness: inspect HTML without JavaScript, check metadata/sitemap and anonymous
+draft/permission refusal, and exercise OTP and editing with isolated synthetic
+accounts. Local readiness does not require publication, a hosted tenant or a
+candidate preview. Report production email, public origin and real object-store
+upload/commit checks separately when local capabilities cannot exercise them.
+
+For an explicitly requested deployment, use the selected host's native workflow
+and any preview it provides. Verify disabled preview capabilities on an already
+authorized live target; synthetic writes and cleanup stay within that scope.
+Pending production checks block a production-readiness claim, not an otherwise
+passing local-development handoff. Preserve preview isolation and permissions;
+report passed, failed and blocked checks for each environment separately.

package/docs/examples/app-shell/src/admin.ts

@@ -1,10 +0,0 @@
-import type { AdminExtension, AdminNavGroup } from "@aotter/mantle-admin/server/extensions";
-
-/**
- * Admin presentation, read by `mantle generate --admin-extensions src/admin.ts` (no runtime code).
- * AGENT: to group the sidebar for how staff work, declare groups here and place Schemas and admin Views in them with
- * `uiSchema.nav: { group, order, hidden }` (docs/handbook/guides/native-admin.md, "Sidebar"). Built-in groups need no
- * declaration: content, operations, reports, more. Admin extensions also go here.
- */
-export const navGroups: AdminNavGroup[] = [];
-export const adminExtensions: AdminExtension[] = [];

package/docs/examples/purchasing/src/admin.ts

@@ -1,12 +0,0 @@
-import type { AdminExtension, AdminNavGroup } from "@aotter/mantle-admin/server/extensions";
-
-/**
- * Admin presentation, read by `mantle generate --admin-extensions src/admin.ts` (no runtime code).
- * The approver's daily work gets its own sidebar group above Admin's built-in ones (content 10, operations 20,
- * reports 30; More stays last); manifests place `pending-requests` and `requests` in it with `uiSchema.nav`.
- * AGENT: add groups for how the staff work; titles take one string or a { locale: text } map.
- */
-export const navGroups: AdminNavGroup[] = [
-  { id: "approvals", title: { en: "Approvals", "zh-TW": "簽核" }, order: 5 },
-];
-export const adminExtensions: AdminExtension[] = [];

package/docs/handbook/guides/admin-extensions.md

@@ -1,20 +0,0 @@
-# Extend Admin
-
-Native Admin accepts app-owned extension declarations, executable server handlers and optional same-origin client modules. Import client `defineAdminExtension` from `@aotter/mantle-admin/extension` and UI primitives from `@aotter/mantle-ui/kit`. Server types live in `@aotter/mantle-admin/server`.
-
-| Contribution | Placement |
-| --- | --- |
-| pages/settings | Extension page; settings forms are generated from the supported form subset |
-| actions | record, list selection or list toolbar |
-| panels | record sidebar or home |
-| fields | field input or cell |
-
-Admin contributions sit behind the admin-layer gate; optional field roles default to `admin`. Server authorization is checked on every route. Handlers own finer business permissions.
-
-Pass full declarations to `mantle generate … --admin --admin-extensions <module>` (named/default `adminExtensions` array). Generation checks contributions, manifest uiSchema references and settings schemas, then emits `extensionMetadata` and compiled `extensionBindings` in `admin-extensions.ts`. Bind the same runtime definitions with `extensionBindings(adminExtensions)` and merge its extensions/routes into `admin()` options. Drift is refused before execution.
-
-Serve each `module` at a same-origin absolute path and install its integrity in the host shell's import map. Native Admin does not serve `source` modules or inject integrity; generation rejects source. Share React and the UI kit via the built import map, rather than bundling a second React. Canonical Admin refuses framing; use its separate same-origin preview contract.
-
-Raw API handlers receive the original Request. Declared `bodyLimit` checks Content-Length before DB access, but the app must bound unknown-length streams. Built-in JSON routes use the shared bounded reader after caller/origin checks. Do not lose exact OCC or uncertain-outcome handling in custom actions.
-
-See [native Admin](native-admin.md) for mounting and acceptance and [generated descriptors](../reference/admin-descriptors.md) for build-time metadata.