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

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, build Admin with `mantle bundle` and serve it as
+  the installed `docs/handbook/guides/native-admin.md` describes. 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,18 @@ 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. Scripted local acceptance does not replace the installed
+independent acceptance guide, which is required before reporting the pages done.
+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.

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

@@ -1,39 +0,0 @@
-# Recipe: an MCP App for members
-
-## Native applications
-
-Read the installed MCP App contract. The SDK's generic hook attaches only the resources the app selects;
-only selected modules enter the service.
-
-```ts
-import type { McpApps } from '@aotter/mantle/mcp';
-import { mcp } from '../generated/mcp.js';
-const memberApp: McpApps = { resources: [{
-  uri: 'ui://shop/my-orders',
-  name: 'my-orders-app',
-  renders: ['my_orders'], // the tool for the declared public View my-orders
-  html: async () => (await import('./member-app.js')).memberHtml,
-}] };
-const tools = mcp({ db, caller, handlers, apps: { public: memberApp } });
-```
-
-Each endpoint accepts one contributor or an array. The separate
-`@aotter/mantle-admin` package contributes its admin App through this same
-`apps.admin` hook; it owns `ui://mantle-admin/…`. App resources use their own
-`ui://<app>/…` namespace. Duplicate resource URI/name, conflicting `renders`,
-or `renders`/`appOnly` naming an unavailable endpoint tool (or a Procedure for
-`appOnly`) fail when `mcp(...)` is built; with a request-bound tool table, the
-tool names are checked on the first matching request. Only clients that
-declare no MCP Apps support see no UI resources; a request that advertises no
-capabilities at all is treated as supported.
-
-Use `renders` for a declared tool; `appOnly` optionally hides it from non-UI
-clients. Import HTML lazily; it carries no secrets or caller data. Tool results
-use the caller's SQL policy, and an App cannot authorize a hidden admin tool.
-Generic interaction components and controllers remain in `@aotter/mantle-ui`;
-Admin-specific controllers/catalogues belong to `@aotter/mantle-admin`.
-
-Verify tools/list metadata, resources/read, actual tool calls and a host-rendered
-member App. Test anonymous/member isolation and resource conflicts. Never retry
-unknown writes blindly; retain OCC and re-read state after an uncertain outcome.
-Commit generated output and run generation with `--check` before deployment.