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

package/docs/examples/purchasing/wrangler.jsonc

@@ -1,10 +1,11 @@
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "mantle-app",
-  "main": "dist/index.js",
+  "main": "dist/worker/index.js",
   "compatibility_date": "2026-09-01",
   "compatibility_flags": [
-    "nodejs_compat"
+    "nodejs_compat",
+    "global_fetch_strictly_public"
   ],
   "vars": {
     "EMPLOYEE_DOMAIN": "example.com"
@@ -36,7 +37,7 @@
     }
   ],
   "assets": {
-    "directory": "node_modules/@aotter/mantle-admin/dist/admin",
+    "directory": "dist/client",
     "binding": "ASSETS",
     "run_worker_first": true,
     "html_handling": "none"
@@ -48,7 +49,7 @@
   },
   "no_bundle": true,
   "find_additional_modules": true,
-  "base_dir": "dist",
+  "base_dir": "dist/worker",
   "build": {
     "command": "mantle bundle src/index.ts dist",
     "watch_dir": [

package/docs/examples/recipes/wrangler.jsonc

@@ -1,10 +1,11 @@
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "mantle-app",
-  "main": "dist/index.js",
+  "main": "dist/worker/index.js",
   "compatibility_date": "2026-09-01",
   "compatibility_flags": [
-    "nodejs_compat"
+    "nodejs_compat",
+    "global_fetch_strictly_public"
   ],
   "secrets": {
     "required": [
@@ -43,7 +44,7 @@
     "MEDIA_S3_ENDPOINT": "https://mantle-app-media.ACCOUNT_ID.r2.cloudflarestorage.com"
   },
   "assets": {
-    "directory": "node_modules/@aotter/mantle-admin/dist/admin",
+    "directory": "dist/client",
     "binding": "ASSETS",
     "run_worker_first": true,
     "html_handling": "none"
@@ -53,7 +54,7 @@
   },
   "no_bundle": true,
   "find_additional_modules": true,
-  "base_dir": "dist",
+  "base_dir": "dist/worker",
   "build": {
     "command": "mantle bundle src/index.ts dist",
     "watch_dir": [

package/docs/handbook/cloudflare/authentication.md

@@ -12,7 +12,22 @@ Mantle supplies the database adapter, schema generation and caller resolution:
 
 ## `auth.ts`
 
-Copy `src/auth.ts` from the [app shell](../../examples/app-shell/README.md), which CI runs from the packed packages.
+Copy `src/auth.ts` from the [app shell](../../examples/app-shell/README.md), which CI runs from the packed packages;
+installed, it is `node_modules/@aotter/mantle/docs/examples/app-shell/src/auth.ts`. Its essentials:
+
+- Imports: `betterAuth` from `better-auth/minimal`; `admin`, `emailOTP` (and `jwt` for MCP) from `better-auth/plugins`;
+  `createAccessControl` from `better-auth/plugins/access`; `defaultStatements` from `better-auth/plugins/admin/access`;
+  `d1Adapter` from `@aotter/mantle/auth/adapter`; the hardening and bootstrap helpers below. For MCP it also imports `jwt`,
+  `mcp` from `@better-auth/mcp`, `cimd` from `@better-auth/cimd` and `oauthGrantExtension`/`oauthGrantRevocation` from
+  `@aotter/mantle/auth/oauth`; the file marks that block as deletable.
+- `authOptions(env)` returns plain options and is the module's export for `--auth src/auth.ts`. Generation calls it with an
+  empty `env`, so it must not throw: fall back to placeholders for `secret` and origin there.
+- The bootstrap admin: `d1BootstrapAdmin(env.DB, { match: "email", value: env.ADMIN_EMAIL }, () => ({ options: { plugins } }))`
+  is assigned to `databaseHooks.user.create.after` and `.update.after` ([Identity helpers](#identity-helpers)).
+- `createAuth(env)` is the same module's second export: it checks its three variables are set and returns
+  `betterAuth(authOptions(env))`. The Worker's `authLoader(() => import("./auth.js").then(m => m.createAuth(env)))`
+  ([service composition](service-entry.md)) is what calls it.
+
 The application owns Better Auth and its optional plugins. Schema generation reads plain options without constructing
 Better Auth; apply `schema.sql` during deployment, never at boot. OAuth resource
 rows are created on first OAuth use from runtime configuration; they require no
@@ -154,7 +169,12 @@ Better Auth adapter code stays outside the Worker startup graph.
 
 `@aotter/mantle/auth/admin` exports `guardAuthAdminRequest(request, resolveFreshCaller, basePath?)` for selected auth transports. It resolves authority only for raw/encoded admin paths, requires an admin cookie session and checks mutation origin. Both the app-owned template and OAuth routes use this same guard.
 
-`ctx.admin` role names are open and must match `^[a-z][a-zA-Z0-9_]{0,62}$`. Bare `ctx.admin` admits any admin; a list admits admins holding one of its roles. Better Auth’s `adminRoles` decides who is an admin. Member role names alone grant no privilege.
+Bare `ctx.admin` admits any verified admin layer classified by Better Auth's
+`adminRoles` / `adminUserIds`. Role lists in `requires` are refused; decide
+per-target permissions in `authorize(target, caller)`, using `hasAdminRole`
+when appropriate. Verified role names match `^[a-z][a-zA-Z0-9_-]{0,62}$`.
+Member role names alone grant no privilege. See
+[authorization requirements](../reference/authorization.md).
 
 The generated auth DDL adds a native `(createdAt, id)` member-paging index (respecting schema field/table names). Unfiltered forward/backward paging orders native timestamps through that index; PostgreSQL cursors retain all six fractional digits and bind as text before timestamp casting. Member search (`%term%` over id/name/email, casting UUID ids to text only in the search expression) is a full scan; the index does not accelerate it.
 

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -5,6 +5,27 @@ description: Install schema explicitly, migrate before deploying, and operate a
 
 Run the same generation command with `--check`, typecheck the application and test its selected routes before deploying. Keep generated TypeScript, SQL and Wrangler edits committed; keep bundle `dist/` untracked. The app owns the database, auth secrets, trusted origin and assets.
 
+## Public fetch routing
+
+Workers use `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
+The public-fetch flag routes native `fetch` through Cloudflare's public Internet
+boundary. OAuth verification needs it to fetch JWKS on the service's own public
+hostname; CIMD also requires this boundary for client metadata. `nodejs_compat`
+alone does not establish it.
+
+`mantle generate cloudflare-*` adds these flags without replacing other flags,
+including in environments with their own `compatibility_flags` array. The same
+command with `--check` refuses missing flags without writing. JSON/JSONC configs
+are updated; TOML receives manual-edit instructions. Keep both flags in every
+TOML environment override. An explicit `global_fetch_private_origin` is preserved
+for applications without OAuth/CIMD, but conflicts with selected OAuth/CIMD auth
+and with the public-fetch flag: generation refuses that config without rewriting
+it. Such applications must use public routing for their OAuth/CIMD transport.
+
+After deployment, complete a real OAuth sign-in and use the resulting bearer
+for MCP `initialize` and `tools/list`. Local development and cookie-only Admin
+checks do not verify production public-hostname routing.
+
 ## Install and change schemas
 
 The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.

package/docs/handbook/cloudflare/service-entry.md

@@ -31,16 +31,18 @@ import { authLoader, resolveCaller } from '@aotter/mantle/auth';
 import { authRoutes } from '@aotter/mantle/auth/routes';
 import { withAuthTasks } from '@aotter/mantle/auth/hardening';
 import { checkOrigin, surfaceFailure, type Caller } from '@aotter/mantle/contracts';
-import { admin } from '@aotter/mantle-admin/server';
+import { admin, adminShell } from '@aotter/mantle-admin/server';
+import { adminMcpApps } from '@aotter/mantle-admin/mcp';
 import { entries } from '@aotter/mantle-admin/server/entries';
 import { adminBindings } from '../generated/admin-bindings.js';
-import { adminAssets } from './admin-assets.js'; // app-owned SPA shell, assets and CSP
+import { mcpAppCatalogues } from '../generated/admin-descriptors.js';
 import { mcp } from '../generated/mcp.js';
 import { rest } from '../generated/rest.js';
 import { handlers } from './handlers.js'; // omit when there are no ref Procedures
 
 // Env comes from worker-configuration.d.ts: declare DB, ASSETS, the email provider binding
-// and the ORIGIN, AUTH_SECRET and ADMIN_EMAIL secrets in Wrangler.
+// and the PUBLIC_ORIGIN, BETTER_AUTH_SECRET and ADMIN_EMAIL secrets in Wrangler.
+// createAuth(env) is exported by the app's src/auth.ts (see the auth template).
 let auth: import('@aotter/mantle/auth').AuthLoader<ReturnType<typeof import('./auth.js').createAuth>> | undefined;
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
@@ -50,7 +52,7 @@ export default {
       let authority: Promise<Caller> | undefined, readAuthority: Promise<Caller> | undefined;
       const resolve = (readOnly: boolean) => resolveCaller(request, auth!, {
         readOnly,
-        audience: [`${env.ORIGIN}/mcp`, `${env.ORIGIN}/mcp/admin`],
+        audience: [`${env.PUBLIC_ORIGIN}/mcp`, `${env.PUBLIC_ORIGIN}/mcp/admin`],
         responseHeaders: headers,
       }).then(value => { checkOrigin(request, value); return value; });
       const caller = (_request?: Request, _env?: Env, classification = { readOnly: false }) =>
@@ -60,9 +62,9 @@ export default {
       const routes = [
         authRoutes(auth, { methods: [{ kind: 'email-otp' }], resolver: caller }),
         admin(bindings.metadata, bindings.views, bindings.operations, {
-          ...options, routes: entries(bindings.schemas, bindings.adapter),
+          ...options, developerViews: bindings.developerViews, routes: entries(bindings.schemas, bindings.adapter),
         }),
-        mcp(options),
+        mcp({ ...options, apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } }),
         rest(options),
       ];
       try {
@@ -74,8 +76,9 @@ export default {
           for (const cookie of headers.getSetCookie()) result.headers.append('set-cookie', cookie);
           return result;
         }
-        const asset = await adminAssets(request, env);
-        if (asset) return asset;
+        // Serves the built Admin shell for /admin and its client routes; undefined for any other path.
+        const shell = await adminShell(request, path => env.ASSETS.fetch(new Request(new URL('/admin/' + path, request.url), request)));
+        if (shell) return shell;
         // Your public frontend/web.ts routes can use an anonymous Caller without
         // loading auth; their generated SQL still controls publication visibility.
         return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
@@ -88,28 +91,32 @@ export default {
 Remove imports and array entries for omitted surfaces. `mcp.ts` exists only when
 the manifest has an MCP surface, and requires the documented optional MCP peer.
 Pass the same handlers to each selected surface that exposes ref Procedures.
-Bind site/media/identity and extension capabilities through the selected Admin/MCP
+Bind site/media/identity capabilities through the selected Admin/MCP
 options; do not expose native auth administrative routes without `authRoutes` or
 `guardAuthAdminRequest`. `withAuthTasks` retains background callbacks on the
 current request's context; `authHardening` configures the background handler.
 Select `--admin` to emit `admin-bindings.ts`. Admin's API is a separate
 `@aotter/mantle-admin` package; the SDK never imports it. The API handles only
-`/admin/api`. The app-owned asset route serves the built shell for `/admin` and
-client routes, including `/admin/sign-in`, and preserves missing asset 404s.
-Allow its built import map through the exact CSP hash documented by the installed
-Admin package. Collection statistics use the generated shared `statisticsView`:
+`/admin/api`. `adminShell` (in the block above) serves the built shell for `/admin` and
+client routes, including `/admin/sign-in`; it sets `frame-ancestors 'none'`, `X-Frame-Options: DENY`, `no-store` and `nosniff`
+on the shell, answers a missing file under `/admin` with a 404 `Response`, and returns `undefined` for other paths and
+non-GET requests. The app owns the rest of the CSP and the asset cache headers.
+Collection statistics use the generated shared `statisticsView`:
 its collection parameter selects only a generated table and visibility policy.
 
 ## Workers assets and secrets
 
 `mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin`
-updates the split-build Wrangler keys. Configure the rest explicitly; JSONC
+updates the split-build Wrangler keys (`main` and `base_dir` under `dist/worker`),
+ensures `nodejs_compat` and defaults to `global_fetch_strictly_public` ([public fetch routing](deploy-and-operate.md#public-fetch-routing))
+and, with `--admin`, `assets.directory`: `mantle bundle` builds Admin into
+`dist/client/admin`, served at `/admin`. Configure the rest explicitly; JSONC
 comments and unrelated settings survive regeneration:
 
 ```jsonc
 {
   "assets": {
-    "directory": "node_modules/@aotter/mantle-admin/dist/admin",
+    "directory": "dist/client",
     "binding": "ASSETS",
     "run_worker_first": true,
     "html_handling": "none"
@@ -119,16 +126,18 @@ comments and unrelated settings survive regeneration:
 ```
 
 `run_worker_first` lets the application supply shell/security/cache headers;
-`none` keeps `index.html` available by name. Admin assets are not a public database
+`none` keeps `index.html` available by name. `adminShell(request, assets)` passes
+paths relative to the Admin directory, so the app fetches them under `/admin/`:
+`path => env.ASSETS.fetch(new Request(new URL("/admin/" + path, request.url), request))`. Admin assets are not a public database
 API. PostgreSQL uses application-owned Hyperdrive/postgres.js wiring,
 with Hyperdrive query caching disabled for authority and mutation visibility.
 
 Commit `.dev.vars.example` containing variable names and placeholders only:
 
 ```dotenv
-ORIGIN=http://localhost:8787
+PUBLIC_ORIGIN=http://localhost:8787
 ADMIN_EMAIL=you@example.test
-AUTH_SECRET=replace-with-a-random-secret
+BETTER_AUTH_SECRET=replace-with-a-random-secret
 ```
 
 Copy it to ignored `.dev.vars`; use deployment secrets for production. Configure
@@ -137,8 +146,7 @@ an app-owned [`EmailSender`](../guides/email.md#application-wiring) and call its
 callbacks. Adapt the auth template's `MAIL.otp`/`MAIL.link` callbacks to this
 sender; it is an object, not a `.dev.vars` value. The auth
 module wires `ADMIN_EMAIL` to the bootstrap helper, which requires verified email.
-`PUBLIC_ORIGIN` can be your application variable instead of `ORIGIN`; map it
-explicitly when constructing auth and keep the trusted origin consistent.
+Name the variables as your `auth.ts` reads them (the app shell uses these three) and keep the trusted origin consistent.
 
 ## Scheduling and Bun
 
@@ -150,22 +158,42 @@ invocation; see the [TTL contract](../guides/native-execution.md#ttl-maintenance
 larger sweeps' cursors for a later invocation instead of scanning without a bound.
 
 On Bun, reuse a process-owned `Database` or `SQL` pool and call the same generated
-surfaces from `Bun.serve({fetch})`. The optional host reader is independent of
-the query target:
+surfaces from `Bun.serve({fetch})`. Bun runs the server as TypeScript, so
+`mantle bundle` builds only Admin for it: the `bun-*` target that
+`generated/.mantle-inputs.json` records skips the Worker bundle, and Admin goes
+to `dist/client/admin` (`--assets` as on Workers) when the server imports
+`@aotter/mantle-admin/server`. Add it as the build script and run it before
+starting the server:
+
+```json
+{ "scripts": { "build": "mantle bundle src/server.ts dist" } }
+```
+
+The optional host reader is independent of the query target:
 
 ```ts
 import { bunAdminAssets } from '@aotter/mantle/bun/assets';
-const assets = bunAdminAssets('node_modules/@aotter/mantle-admin/dist/admin');
+const assets = bunAdminAssets('dist/client/admin');
 const bindings = adminBindings({ handlers });
 const serveAdmin = admin(bindings.metadata, bindings.views, bindings.operations, {
   db: () => db, caller, handlers, routes: entries(bindings.schemas, bindings.adapter),
 });
-// Call assets(path) from your separate shell/static route.
+// Call assets(path) from your separate shell/static route. adminShell(request, reader) wants
+// paths without a leading slash and a Response (404 when missing), so adapt the reader:
+const reader = async (path: string) => (await assets('/' + path)) ?? new Response(null, { status: 404 });
 ```
 
 The reader returns a native `Response` or `null`, rejects traversal/control
 characters and escaping symlinks; the app owns shell, CSP and cache headers.
-Use ignored `.env` on Bun. Run cron work with your native scheduler; neither
+Use ignored `.env` on Bun.
+
+Admin's build tools and UI packages are dependencies of `@aotter/mantle-admin`,
+so a production install carries them (about 65 MB). For a container image, use a
+multi-stage build: the build stage installs everything and runs `mantle bundle`
+and `bun build src/server.ts --target bun --outdir dist/server`; the runtime stage
+copies only `dist/` (plus any files the server reads at runtime) and starts
+`bun dist/server/server.js`. Neither the Admin assets nor the bundled server read
+`node_modules` once built. Run cron work with your native scheduler; neither
 imports nor ordinary requests execute DDL, migrations or cron work. OAuth resource
 rows are inserted on first OAuth use from runtime configuration, with no deploy
 step; auth initialization and cookie/bearer/MCP/REST requests do no resource work.
@@ -190,13 +218,12 @@ untracked. Deployment uses committed generated source; it does not regenerate.
 # CI, with the project's exact installed SDK and peer versions:
 pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin --check
 pnpm exec tsc --noEmit
-pnpm exec mantle bundle src/worker.ts dist
+pnpm exec mantle bundle src/worker.ts dist   # dist/worker, and dist/client/admin with --admin
 ```
 
 `--check` regenerates in memory, lists missing/changed/obsolete SDK-owned files
 and stale Wrangler build settings, exits nonzero, and writes nothing. Unmarked
 application files are preserved. TOML generation prints manual edits, so an
-exact Wrangler `--check` requires JSON/JSONC. Use all the same `--site`, `--auth`,
-`--admin` and `--admin-extensions` options as normal generation. The check needs no database,
+exact Wrangler `--check` requires JSON/JSONC. Use all the same `--site`, `--auth` and `--admin` options as normal generation. The check needs no database,
 network access, credentials or deployment. Imported configuration modules must
 remain pure: exporting `authOptions(env)` avoids constructing Better Auth at build time.

package/docs/handbook/concepts/authorization.md

@@ -16,4 +16,4 @@ The compiler adds row policy to every Schema relation, including joins and neste
 
 Field `scope` hides rows even from admin callers; use View/Procedure [`restrict`](../reference/view.md#restrict) to limit member access while Admin collection reads see all rows allowed by the Schema's scope.
 
-The app owns custom identity and roles. Better Auth’s admin plugin `adminRoles` (default `["admin"]`) classifies comma-separated `user.role` values. `resolveCaller` carries this layer as `admin`; `isAdmin(caller)` and `hasAdminRole(caller, name)` consult it. Application-owned resolvers mint the original Caller with `userCaller` from `@aotter/mantle/user-fields`, using only a verified user and the identity provider’s adminRoles. Setting `admin: true` on a plain object grants no privilege. Member role names alone do not grant privilege. Optional [Better Auth](../cloudflare/authentication.md) helpers use fresh primary authority by default. Admin additionally requires an admin cookie session. UI visibility never replaces a server authorization check.
+The app owns custom identity and roles. Better Auth’s admin plugin `adminRoles` (default `["admin"]`) classifies comma-separated `user.role` values. `resolveCaller` carries this layer as `admin`; `isAdmin(caller)` and `hasAdminRole(caller, name)` consult it. Callers come from `resolveCaller` over Better Auth; an existing identity provider connects through Better Auth's OAuth or SSO plugins, since no public API builds a Caller from another provider's session (`authenticatedAs` in `@aotter/mantle/testing` is for tests). Setting `admin: true` on a plain object grants no privilege. Member role names alone do not grant privilege. Optional [Better Auth](../cloudflare/authentication.md) helpers use fresh primary authority by default. Admin additionally requires an admin cookie session. UI visibility never replaces a server authorization check.

package/docs/handbook/concepts/mcp-and-agents.md

@@ -16,3 +16,22 @@ The app owns OAuth configuration, discovery and consent; follow [OAuth](../guide
 [MCP Apps](../guides/mcp-apps.md) add static UI resources through the public contributor hook. Admin uses the same hook from its separate package. Credentials never go in App HTML. WebMCP catalogues are generated display/tool metadata for the mounted Admin product; server checks remain authoritative.
 
 See [surface contracts](../reference/surface.md) for tool schemas, challenges and scalar conversion.
+
+## When a host shows old tools
+
+A fresh `tools/list` always returns the deployed tools, but many hosts keep their own copy and do not ask again after a deploy. Mantle sends no list-changed notifications: tools change only at deploy, and the hosts that keep copies do not act on them. Instead each generated tool's description ends with its own version, and the results of a call that reaches the tool carry the deployed version, so a model holding an older definition can see it, correct its call or ask the user to refresh. Failures also state the input schema the tool is listed with now, except authorization refusals. A call naming a tool the catalogue no longer has gets the protocol's unknown-tool error, whose message gives `serverInfo.version`: unless the application sets it, a hash of every tool the endpoint serves, before per-caller filtering. Refusals before a call reaches its tool, such as authentication challenges, carry neither.
+
+In Admin, WebMCP results from the tool route carry the version, and refusals add it with the input schema, except authorization refusals; a tool removed since the page loaded is refused as not found, without a catalogue version. Admin's two navigation tools, `admin_get_context` and `admin_navigate`, carry no version: the page defines and runs them without a server call, so it cannot list one definition and run another, and a reload after a deploy replaces both. The exact shapes are in [surface contracts](../reference/surface.md#tool-versions).
+
+How each client refreshes its copy (as of 2026-10):
+
+| Client | Refresh |
+| --- | --- |
+| claude.ai connectors | A server-side copy keyed by URL, kept about an hour (users report up to 24 hours). Only adding the connector again under a new URL, such as `?v=2`, forces a refresh, and that needs authorization again. |
+| Claude Code | `/mcp` reconnect, or a new session |
+| ChatGPT developer mode | Refresh the connection, then start a new chat |
+| Published ChatGPT apps | A daily scan, or Rescan, followed by review; keep tools compatible meanwhile |
+| Cursor | Quit fully and reopen |
+| VS Code | Run "MCP: Reset Cached Tools", or restart the server |
+| Gemini CLI | `/mcp reload` |
+| MCP Inspector | The refresh button |

package/docs/handbook/examples/hub.md

@@ -2,4 +2,4 @@
 
 Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-The runnable [reference service](https://github.com/aotter/mantle/blob/develop/docs/examples/reference-service/README.md) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.8/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

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

@@ -8,4 +8,110 @@ Admin Views provide custom read lists; their SELECT outputs, column lineage and
 
 Generic publishing edits apply to drafts; publishing transitions retain their atomic guards and OCC. Read-only collections refuse generic edits while declared Procedures can still run. Ref operations receive the caller/transaction-bound Store.
 
-Use [extensions](admin-extensions.md) for app-owned pages, actions, panels or field renderers. Keep exact conflict/uncertain-outcome handling in the shared UI controller.
+Use [`defineAdmin` components](native-admin.md#customising-admin) for app-owned cells, inputs, record asides and actions; server work is a Procedure, a View or an application route. Keep exact conflict/uncertain-outcome handling in the shared UI controller.
+
+## Theme
+
+Admin is themed with CSS variables. Import your own stylesheet from `src/admin.tsx` (`import "./admin.css"`) and override the public tokens on `:root` for light and on `.dark` for dark:
+
+```css
+:root {
+  --primary: #0f766e;
+  --primary-foreground: #ffffff;
+  --radius: 0.5rem;
+}
+.dark {
+  --primary: #2dd4bf;
+  --primary-foreground: #042f2e;
+}
+```
+
+Admin marks the active theme as both the `.dark` class and `data-theme="dark"` (or `"light"`) on the root. Dark tokens and Tailwind's `dark:` variant apply when either is present, so `[data-theme="dark"] {}` is equivalent to `.dark {}`. Your overrides apply in the browser Admin and, because the entry imports your CSS, in the [MCP App](mcp-apps.md#theme) too, where the host's neutral colours are laid over them.
+
+| Token | Meaning |
+| --- | --- |
+| `--background` | Page background |
+| `--foreground` | Default text |
+| `--card` | Card and panel surface |
+| `--card-foreground` | Text on a card |
+| `--popover` | Menu, popover and dialog surface |
+| `--popover-foreground` | Text on a popover |
+| `--primary` | Brand color: primary buttons, active states |
+| `--primary-foreground` | Text on `--primary` |
+| `--secondary` | Secondary button surface |
+| `--secondary-foreground` | Text on `--secondary` |
+| `--muted` | Subtle surface: table stripes, disabled areas |
+| `--muted-foreground` | Secondary text |
+| `--accent` | Hover and selected surface |
+| `--accent-foreground` | Text on `--accent` |
+| `--destructive` | Destructive actions and errors |
+| `--border` | Borders and dividers |
+| `--input` | Form control borders |
+| `--ring` | Focus ring |
+| `--radius` | Base corner radius; the other radii derive from it |
+| `--success` | Success status color |
+| `--warning` | Warning status color |
+| `--info` | Informational status color |
+| `--chart-1` | Chart series 1 |
+| `--chart-2` | Chart series 2 |
+| `--chart-3` | Chart series 3 |
+| `--chart-4` | Chart series 4 |
+| `--chart-5` | Chart series 5 |
+| `--sidebar` | Sidebar surface |
+| `--sidebar-foreground` | Sidebar text |
+| `--sidebar-primary` | Sidebar active item |
+| `--sidebar-primary-foreground` | Text on `--sidebar-primary` |
+| `--sidebar-accent` | Sidebar hover surface |
+| `--sidebar-accent-foreground` | Text on `--sidebar-accent` |
+| `--sidebar-border` | Sidebar borders |
+| `--sidebar-ring` | Sidebar focus ring |
+| `--app-base` | Solid color behind the page |
+| `--app-background` | Page backdrop (any CSS background, such as a gradient) |
+
+Every other variable, including `--mantle-blue-*` and `--chrome-glass`, is internal and may change without notice.
+
+## Eject a component
+
+`@aotter/mantle-admin` ships a [shadcn registry](https://ui.shadcn.com/docs/registry) of starting-point components for the `defineAdmin` slots. Ejecting copies one into your source: you own that file and edit it freely, while the hooks it calls (`@aotter/mantle-admin/hooks`) and the slot prop types (`@aotter/mantle-admin/app`) keep upgrading with the package. The registry is inside the installed package, so the copy matches the version you run and no registry host is involved (the shadcn CLI itself downloads from npm and needs network). Install from the package, in the app's root:
+
+```bash
+npx shadcn@4 add ./node_modules/@aotter/mantle-admin/dist/registry/admin-cell.json
+```
+
+The file lands in `src/admin/<item>.tsx` (the item's `target` ignores aliases). The CLI needs a `tsconfig.json` and a `components.json` in the app's root; this minimal one works, because no alias or stylesheet is used:
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": { "config": "", "css": "", "baseColor": "neutral", "cssVariables": true },
+  "aliases": { "components": "@/components", "utils": "@/lib/utils" }
+}
+```
+
+The CLI removes a comment above a file's first import, so each item keeps its header below the imports. Import it in `src/admin.tsx` and name the slot, replacing the sample collection, field, View and operation with your own:
+
+```tsx
+import { AdminCell } from "./admin/admin-cell";
+
+export default defineAdmin(admin, { components: { "cell:requests.status": AdminCell } });
+```
+
+| Item | Slots | Surface |
+| --- | --- | --- |
+| `admin-cell` | `cell:view:<view>.<column>` | both (also reusable as a browser collection cell) |
+| `admin-input` | `input:<schema>.<field>` | browser |
+| `admin-record-actions` | `record.actions:<schema>` (runs an operation with `useOperation`) | browser |
+| `admin-record-aside` | `record.aside:<schema>` (lists a View's rows with `useView`) | browser |
+| `admin-sidebar` | `Sidebar` (`renderDefault` with a footer link) | browser |
+| `admin-home` | `Home` (`renderDefault` under a section that reads a View) | browser |
+
+Each file starts with a comment naming its surface and rules, and imports only `react`, `@aotter/mantle-admin/app` and `@aotter/mantle-admin/hooks`. A `both` component also renders in the Admin MCP App, inside a host's sandboxed iframe, so keep it to these rules:
+
+- Read data only through `useView` and `useOperation`; `useEntries`, `useEntry`, `useCollectionTotal`, `useMe` and `useBadges` read `unavailable` there. Declare what a card needs as an admin View.
+- Link only with `<AdminLink>` or `useOpenLink()`; never `window.open` or `target="_blank"`.
+- No `fetch`, no `document.cookie` or `localStorage` authentication, no remote origin that the host's CSP does not allow, and no assumed width.
+- Where `useOperation` returns no `run` (a host without server tools), show the control disabled with a note rather than throwing or vanishing.
+- Branch on `useAdminSurface()` (or the `surface` prop) if you must, and render something sensible in both branches.

package/docs/handbook/guides/agent-setup.md

@@ -12,24 +12,42 @@ carries.
 
 The Mantle plugin carries one OSS authoring skill, `mantle`, and local
 acceptance references. It does not configure a hosted-service connection.
+Install from the Git tag matching the exact SDK version you selected (currently
+`v0.2.0-alpha.8`). Alpha releases integrate on `develop`; an unqualified
+`aotter/mantle` source follows `main` and can install older, incompatible
+instructions. A skill install does not upgrade the application's SDK.
 
-```bash
-# Claude Code: two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
+For Codex, pin the marketplace checkout:
 
-# Codex
-codex plugin marketplace add aotter/mantle
+```sh
+codex plugin marketplace add aotter/mantle --ref v0.2.0-alpha.8
 codex plugin add mantle@mantle
 ```
 
-Cursor and GitHub Copilot read the plugin manifests from the repository.
-Without a plugin host, install the skill alone:
+For Claude Code, first clone the release into a directory you will keep:
+
+```sh
+git clone --depth 1 --branch v0.2.0-alpha.8 https://github.com/aotter/mantle.git mantle-plugin
+```
+
+Then, in Claude Code, use that checkout's absolute path:
+
+```text
+/plugin marketplace add /absolute/path/to/mantle-plugin
+/plugin install mantle@mantle
+```
+
+Cursor and GitHub Copilot use their plugin manifests from the same tagged
+checkout. Without a plugin host, install only the consumer skill by name:
 
 ```sh
-npx skills add aotter/mantle
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.8 --skill mantle
 ```
 
+When upgrading the SDK, update the marketplace ref or local tagged checkout and
+refresh/reinstall the plugin using the host's native workflow. Verify the loaded
+manifest version and skill source. Do not reset a checkout containing local edits.
+
 Read the path the installer prints (for project-local Codex,
 `.agents/skills/mantle/SKILL.md`). The skill installs no SDK, creates no
 project and copies no handbook.