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

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

@@ -1,170 +1,117 @@
----
-description: What Admin serves in 0.2.0, how manifests and uiSchema become Admin's collections, reports and operations, and how to verify a change.
----
 # Customize Admin from manifests
 
-`createAdminSurface` serves Admin's API at `/admin/api/*` behind a staff gate.
-Every route reads and writes through `runtime.store.as(caller)` and
-`invokeProcedure`, so Admin sees exactly what the signed-in staff member may
-see. What Admin shows is derived from the compiled plan: labels, forms, list
-columns, reports and operations are manifest edits.
-
-With feature `admin`, the generated preset also serves the console, the
-prebuilt SPA in `@aotter/mantle-ui/admin`, at `/admin`: `wrangler.jsonc` binds
-`node_modules/@aotter/mantle-ui/dist/admin` as the Worker's `ASSETS`
-(`run_worker_first`), and `src/service.ts` passes `createAdminSurface` an
-`assets` function that reads from it. `mantle generate` warns when `admin` is
-selected and `wrangler.jsonc` binds no `ASSETS`. The Bun preset reads the
-same files with `bunAdminAssets` from `@aotter/mantle/bun`. Sign in at
-`/admin/sign-in`.
-
-## Manifest to Admin
-
-| You want | Author this | Effect and limits |
-|---|---|---|
-| Rename a collection or explain a field | Schema `title` / `description`, property `title` / `description` (a string or a locale map) | Labels and help. Stored names do not change |
-| Required fields and option lists | JSON Schema `required`, `enum`, `type` | Data contracts, checked on every write, not styling |
-| Option labels | a string property's `oneOf: [{ const: open, title: { en: Open, zh-TW: 處理中 } }, …]` instead of `enum` | Selects, filter tabs and list cells show the `title` |
-| A multiline string | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | `textarea` is the only built-in explicit widget |
-| Your own control, list cell or record panel | `uiSchema.fields.<name>.widget: <extension>/<contribution>`, `uiSchema.list.cells`, `uiSchema.panels` | Contributions of the project's Admin extensions; see [Extend Admin](admin-extensions.md) |
-| Markdown or HTML | property `x-mcp-hint: markdown` or `html` | A rich editor |
-| A timestamp, a date or money | `format: date-time`, `format: date`; `x-mcp-hint: money-minor` on an integer | Date controls; money in minor units, with a sibling `currency` when present |
-| Columns of an operational list | Schema `uiSchema.list.primaryField`, `.columns` | `primaryField` is a scalar data field; `columns` may name native columns (`createdAt`, `updatedAt`) |
-| Business-state tabs | Schema `uiSchema.list.filterField` | Operational Schemas only; a string enum that leads an index |
-| Search | Schema `searchableFields` | Full-text search over those string fields, plus `id` |
-| Related records | a required property with `x-mantle-ref` | Children fold under their parent |
-| A folded child in navigation too | Schema `uiSchema.nav.standalone: true`, optional `parentField` | Its own list with a parent filter |
-| A read-only report with CSV | a View with `surface: staff`, `title`, `uiSchema.list` | `columns`, `searchFields` and `filterFields` name the View's outputs; the search box and filters become `LIKE` and `=` on them. `GET /admin/api/views/<name>/export` returns every matching row |
-| An operation | a Procedure bound by a Trigger with `source: { kind: mcp, surface: staff }` | Listed at `/admin/api/operations` for staff its `requires` admits, and run with `POST /admin/api/operations/<name>` |
-| A row operation | that Procedure's `target` (declared or inferred from `WHERE id = … AND version = …`) | Bound to the row's `id`, and its version when the target names one |
-| A list-level operation | Procedure `uiSchema.collectionAction: <schema>` | Shown on that collection |
-| No generic edits | Schema root `schema.readOnly: true` | Admin's entry routes refuse writes (`CONFLICT`); declared Procedures still run |
-
-Schema list presentation (`primaryField`, `columns`, `filterField`) is for
-`lifecycle: operational`. Publishing Schemas keep the draft, publish and
-archive workflow (`POST /admin/api/entries/{id}/publish` and `/unpublish`).
-
-## Example: an operational inbox
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: support-tickets }
-spec:
-  title: { en: Support tickets, zh-TW: 客服工單 }
-  lifecycle: operational
-  indexes: [[ticketState]]
-  searchableFields: [subject, details]
-  uiSchema:
-    fields:
-      details: { widget: textarea }
-    list:
-      primaryField: subject
-      columns: [ticketState, createdAt]
-      filterField: ticketState
-  schema:
-    type: object
-    additionalProperties: false
-    required: [subject, ticketState]
-    properties:
-      subject: { type: string, title: Subject }
-      details: { type: string, description: Include the steps to reproduce. }
-      ticketState: { type: string, enum: [open, waiting, closed] }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: support-report }
-spec:
-  title: Support report
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
-  uiSchema:
-    list:
-      columns: [subject, ticketState, created_at]
-      searchFields: [subject]
-      filterFields: [ticketState]
-  sql: SELECT id, subject, ticketState, created_at FROM "support-tickets" ORDER BY created_at DESC
+Select `--admin` and mount [native Admin](native-admin.md) from `@aotter/mantle-admin`. The app serves its assets and owns authentication. UI and SDK are separate packages.
+
+Schema `uiSchema` selects fields, widgets, list columns, enum tabs and child navigation. The compiler derives sortable fields from indexed required/non-null fields; it emits selected system/statistics indexes in initial DDL. Apply those indexes through an explicit migration on existing databases.
+
+Admin Views provide custom read lists; their SELECT outputs, column lineage and `uiSchema.list` define display/search/filter metadata. Procedures and MCP admin Triggers define operations with declared authorization, input checks and optional row targets. A hidden button never authorizes an operation.
+
+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 [`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;
+}
 ```
 
-Schema `uiSchema.list` and View `uiSchema.list` are different contracts; do
-not copy keys between them. The report's search box matches `subject`
-(`LIKE`), its filter is `ticketState` (`=`), and a declared `input` would add
-a form above them; all of them keep cursor paging.
-
-## Developer console
-
-The Developer console's Procedure overview projects the sealed SQL AST into
-a static execution diagram: authorization, validated input, guard, applicable
-lifecycle hooks, ordered atomic statements, commit or rollback, and output
-validation. Statement cards show read/write dependencies, row versus set
-semantics, RETURNING and ordered CASE assignments. CASE chooses a field value;
-WHERE filters rows. A set operation can affect zero rows and still continue.
-Output validation and after-hook failures do not roll back an existing commit.
-Unsupported expression shapes remain explicitly opaque beside authored SQL;
-code handlers' effects and actual run history are not inferred.
-
-The inline business flow uses Schema/property titles and titled enum options
-from the developer snapshot; generic verbs and operators are UI translations.
-It expands direct `UPDATE SET field = CASE … END` assignments only. CASE
-inside arithmetic, casts, functions, SELECT or INSERT remains in the SQL
-detail tree, rather than pretending its intermediate result is the assigned
-value. SQL identifiers match manifest names case-insensitively. The existing
-`money-minor` display convention uses hundredths and a single-valued sibling
-`currency` enum; if numeric conversion or currency formatting would round a
-threshold, the flow shows its exact SQL literal marked as a raw SQL value.
-These display hints do not establish or validate business units.
-
-## Roles
-
-Admin's gate admits any staff role. Inside it, each route names the least role
-it needs: `contributor` reads and edits drafts, `editor` publishes, deletes
-and manages media, `owner` manages staff, site settings and the developer
-console. Operations and staff Views are further limited by their own
-`requires`.
-
-Those atom predicates do not restrict generic Schema entry routes. A root
-Schema `readOnly: true` blocks generic writes, not reads. In a service where
-only owner/editor reviewers may read an unscoped table, restrict the Admin
-surface in the application-owned `src/service.ts`:
-
-```ts
-// Replace the preset's Admin composition, keeping its existing options.
-const adminSurface = createAdminSurface(runtime, { /* existing Admin options */ });
-const admin = withCaller(resolver, async (request, caller) => {
-  if (new URL(request.url).pathname.startsWith("/admin/api/") &&
-      caller.kind === "user" && caller.role === "contributor") {
-    return Response.json({ error: {
-      code: "AUTH_DENIED", message: "Admin access requires an owner or editor role.",
-    } }, { status: 403 });
-  }
-  return adminSurface(request, caller);
-});
+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 } });
 ```
 
-The preset already imports `withCaller` from `@aotter/mantle`. Reuse its
-resolver so credential validation and the session origin guard run once;
-Admin retains its own gates for members and anonymous callers. Contributors
-can use an application-owned page over an owner-filtered public View. Keep
-sign-in, OAuth consent and UI assets reachable; restricting the whole `/admin`
-prefix would also block member MCP consent at `/admin/oauth/consent`. This is
-host surface composition, not a Procedure `ref` handler or a new Manifest
-permission key. Exercise generic entry reads, reports and operations with
-each role, including after revoking a role in an existing session.
-
-## Verify a change
-
-1. Run `mantle generate`, then `mantle generate --check`.
-2. Restart `wrangler dev` (or the Bun process) so the runtime loads the new plan.
-3. Open `/admin` with a staff session and check the affected list, form,
-   report or operation. `GET /admin/api/bootstrap` carries the collections,
-   Views, operations and site the console renders.
-
-`uiSchema` keys are closed. Schema takes `fields`, `list` and `nav`;
-Procedure takes `collectionAction` and `fields`; a staff View takes `list`. No
-layout, CSS, component or permission keys exist; build those in your own UI
-over Admin's API or your own surfaces.
-
-## Source
-
-- [Schema](../reference/schema.md#uischema), [View](../reference/view.md) and [Procedure](../reference/procedure.md) references
-- [HTTP, MCP, CLI and packages](../reference/surface.md): every Admin route
+| 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

@@ -10,28 +10,45 @@ carries.
 
 ## 1. Install the `mantle` skill
 
-The Mantle plugin carries one skill, `mantle`, its helper script, and the
-Mantle Cloud MCP connection (`https://cloud.mantle.tools/mcp`).
+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
 ```
 
-A skill-only install has no Cloud MCP connection; add one by hand if you need
-it. Either way, read the path the installer prints (for project-local Codex,
+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.
 
@@ -65,18 +82,6 @@ An agent reads these files from `node_modules` when the task calls for them.
 
 ## 3. Verify the application
 
-Installing instructions proves only that they were copied. Prove the service:
-
-1. `mantle generate` and `mantle generate --check` exit 0.
-2. The project typechecks against `.mantle/generated/mantle.ts`.
-3. `wrangler dev` (or, on Bun, `bun src/index.ts`) starts, and the routes you depend on answer: a REST View, an
-   HTTP Trigger, `/mcp` `tools/list`, and with identity `mantle` a sign-in and
-   `GET /admin/api/me`.
+Run the app's exact generation command with `--check`, typecheck, implement every printed handler and typecheck again. Test actual routes and persisted state. With selected Admin, mount `entries(bindings.schemas, bindings.adapter)` and serve assets separately. Verify member/admin OTP, row visibility and OCC. Installing a skill proves none of these flows.
 
-| Symptom | Cause and next step |
-|---|---|
-| `docs/...` is missing after installing the skill | The skill carries no docs. Install the SDK and read `node_modules/@aotter/mantle/docs/`. |
-| `mantle` is not found | Install `@aotter/mantle` locally and run it through the package manager (`pnpm exec mantle`). |
-| `mantle skills` is unknown | It is 0.1.x. Follow the installed 0.2.x docs. |
-| A v1 manifest or a `version: 1` config fails | The project is on 0.1.x. Follow `docs/upgrade-0.1-to-0.2.md`. |
-| A documented feature is missing | The installed version is older than the docs you read. Read its own docs, or upgrade deliberately. |
+If packaged docs are missing, reinstall the SDK version pinned by the app. If a feature differs from an online page, read the installed docs rather than assuming compatibility.

package/docs/handbook/guides/email.md

@@ -0,0 +1,86 @@
+# Transactional email
+
+Import the optional email port from `@aotter/mantle/email`. Mantle supplies
+`EmailSender`, `EmailSendArgs`, English `signInCodeEmail`, `signInLinkEmail`
+and `adminInvitationEmail` templates, and `ConsoleEmailSender` for local
+development. Applications select and configure their sender and Better Auth
+plugins.
+
+`send({ to, subject, text, html?, locale, category? })` returns `Promise<void>`.
+The templates return `{ subject, text }`, with the same English text as 0.2;
+they do not translate or consume `locale`. Pass the recipient's locale through
+to the sender, which can select localized templates. Existing categories are
+`auth.email-otp.<type>`, `auth.magic-link.sign-in` and `auth.admin-invitation`.
+
+## Application wiring
+
+```ts
+import { emailOTP } from "better-auth/plugins";
+import { hashEmailOtp } from "@aotter/mantle/auth/hardening";
+import { signInCodeEmail, adminInvitationEmail, type EmailSender } from "@aotter/mantle/email";
+
+const locale = (request?: Request) =>
+  request?.headers.get("accept-language")?.split(",")[0]?.split(";")[0]?.trim() || "en";
+
+// Include this plugin in the app's Better Auth options.
+export const emailPlugin = (sender: EmailSender, secret: string) => emailOTP({
+  storeOTP: { hash: otp => hashEmailOtp(secret, otp) },
+  sendVerificationOTP: ({ email, otp, type }, ctx) => sender.send({
+    to: email, ...signInCodeEmail(otp), locale: locale(ctx?.request),
+    category: `auth.email-otp.${type}`,
+  }),
+});
+
+// Use the configured, trusted application origin, never an incoming Host or
+// Origin header. The application grants the OSS "admin" role before sending.
+export const inviteEmail = (sender: EmailSender, origin: string, to: string, language: string) =>
+  sender.send({
+    to, ...adminInvitationEmail("admin", new URL("/admin/sign-in", origin).href),
+    locale: language, category: "auth.admin-invitation",
+  });
+```
+
+For magic links, pass Better Auth's generated URL to `signInLinkEmail(url)`;
+configure Better Auth's `baseURL` and `trustedOrigins` to prevent untrusted
+callback destinations. Templates preserve their input as plain text and never
+interpret it as HTML. If a sender supplies `html`, it owns escaping untrusted
+text and attributes and validating link destinations. Pass structured fields
+to the provider; do not interpolate them into raw MIME headers.
+
+Use `new ConsoleEmailSender()` only in explicitly selected local development.
+It logs recipients, codes and links and sends nothing; never select it in
+production or log live messages in a production sender. Provider failures
+reject the promise; the application owns error handling and retry policy.
+
+**Never let the response wait for the send.** Better Auth calls
+`sendVerificationOTP` for `email-verification` and `forget-password` only when
+the user exists, so a response that waits for the provider reveals whether an
+account exists. Configure Better Auth's `advanced.backgroundTasks.handler` (on
+Workers, `ctx.waitUntil`) so the send runs after the response, as 0.2 did; the
+app-owned auth template wires it.
+
+## Cloudflare Email Service binding
+
+Use a verified sender and a Cloudflare Email Service `send_email` binding.
+The binding composes the message natively; no mail SDK or MIME builder is needed.
+
+```jsonc
+{ "send_email": [{ "name": "EMAIL" }] }
+```
+
+```ts
+import type { SendEmail } from "@cloudflare/workers-types";
+import type { EmailSender } from "@aotter/mantle/email";
+
+interface Env { EMAIL: SendEmail; EMAIL_FROM: string }
+export const emailSender = (env: Env): EmailSender => ({
+  async send({ to, subject, text, html }) {
+    await env.EMAIL.send({ from: env.EMAIL_FROM, to, subject, text, html });
+  },
+});
+```
+
+The English example ignores `locale` and `category`; a localized provider may
+use both. The binding's verified sender and recipient restrictions still apply.
+This example does not provision a sender, enable an auth method or send mail
+without application wiring.