@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

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

@@ -1,135 +1,117 @@
----
-description: How Schema, View, Procedure, Trigger and uiSchema become Admin forms, lists, navigation and actions, with a complete customization example.
----
-# Customize the Admin console
-
-Many Admin changes are manifest edits: labels, multiline inputs, operational
-list columns and tabs, reports and action placement. Admin API derives
-metadata from the compiled plan; the prebuilt SPA renders it. The host must
-already mount Admin API, authentication and Admin assets — see the
-[local Admin tutorial](../start/quickstart-admin.md).
-
-## Manifest to rendered UI
-
-| User request | Author this | What Admin renders / constraints |
-|---|---|---|
-| Rename a collection or explain a field | Schema `title` / `description`, property `title` / `description` | Localized labels and help. Property names and stored values stay unchanged. |
-| Make a field required or an option list | JSON Schema `required`, `enum`, `type` | Required marker and type-derived control; enums become selects. These are data contracts, not styling flags. |
-| Make a string multiline | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | Textarea for a top-level string field. `textarea` is the only supported explicit widget. |
-| Edit Markdown or HTML | Property `x-mcp-hint: markdown` or `html` | Rich editor; these hints take precedence over `widget: textarea`. `richtext` currently uses a textarea. |
-| Edit a timestamp or show money | `format: date-time` on a string; `x-mcp-hint: timestamp-ms` or `money-minor` on a number | Date/time controls or number preview. Money uses minor units divided by 100 and a sibling `currency` when present. |
-| Reorder an operational record list | Schema `uiSchema.list.primaryField`, `.columns` | Linked leading data field, then ordered columns. Native columns such as `status` and `createdAt` are allowed in `columns`; `primaryField` must be a scalar data property. |
-| Add business-state tabs | Schema `uiSchema.list.filterField` | Operational-only enum tabs/sidebar links. Field needs a string enum and a left-prefix index. |
-| Search record contents | Schema `searchableFields` | Searches declared string fields plus entry id. This is substring search, not an index declaration. |
-| Show related records | Required property `x-mantle-ref` | Eligible child collections fold into the parent's workbench; translation children use language tabs. |
-| Also show a folded child in navigation | Schema `uiSchema.nav.standalone: true`, optional `parentField` | Adds its own list with parent filter, retaining the folded view. Multiple eligible parent refs require `parentField`; not allowed on translation children. |
-| Add a read-only report and CSV | View `surface: staff`, `title`, `uiSchema.list` | Report navigation; `columns`, `searchFields`, `filterFields` use output names. Server filters before pagination; CSV includes all matches. |
-| Add a list-level action | Eligible Procedure `uiSchema.collectionAction: <schema>` | Collection action with a form generated from Procedure `input`. |
-| Add a row action | Eligible Procedure input property `x-mantle-ref: <schema>` | Row operation with prefilled reference. Selection uses a same-name Schema property, then a sole single-field unique index, otherwise entry `id`. |
-| Make generic content editing read-only | Schema root `schema.readOnly: true` | Generic authoring writes are blocked; declared Procedures remain available. A disabled field is not an authorization rule. |
-
-The data editor also handles booleans, numbers, objects and arrays from JSON
-Schema. Bound fields (`x-mantle-bind`) display read-only because Runtime owns
-the value. Media controls depend on the supported media schema and host media
-policy; `uiSchema` alone cannot enable uploads.
-
-Schema list presentation (`primaryField`, `columns`, `filterField`) is for
-`lifecycle: operational`. Publishing collections keep the built-in publishing
-workflow. For an alternate publishing table, define a staff View report.
-
-## Example: an operational inbox
-
-This complete source configures a collection and a separate staff report.
-The collection filters by `ticketState`, not Mantle's native publishing status.
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: support-tickets
-spec:
-  title: { en: Support tickets, zh-TW: 客服工單 }
-  lifecycle: operational
-  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] }
-  indexes: [[ticketState]]
-  searchableFields: [subject, details]
-  uiSchema:
-    fields:
-      details: { widget: textarea }
-    list:
-      primaryField: subject
-      columns: [ticketState, createdAt]
-      filterField: ticketState
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: support-report
-spec:
-  title: Support report
-  surface: staff
-  from: support-tickets
-  fields: [id, subject, ticketState, createdAt]
-  uiSchema:
-    list:
-      columns: [subject, ticketState, createdAt]
-      searchFields: [subject]
-      filterFields: [ticketState]
+# Customize Admin from manifests
+
+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;
+}
+```
+
+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 collection shows Subject first, State and Created at next, state tabs,
-and a multiline Details editor. The report is a separate navigation entry
-with its own search/filter configuration and CSV export. Schema `.list` and
-View `.list` are different contracts; do not copy their keys between atoms.
-
-## When a Procedure becomes a button
-
-`uiSchema.collectionAction` alone does not expose a Procedure. Admin discovers
-staff operations from either a staff MCP Trigger or an HTTP Trigger whose
-Procedure requires `ctx.staff`. Runtime rechecks Procedure `requires` on
-execution. Use the [Procedure reference](../reference/procedure.md#uischema)
-for a complete action declaration.
-
-An eligible operation with row bindings appears on those records. One with
-`collectionAction` appears on that collection's list. Operations without either
-appear in the standalone Operations screen. Row mutations use the observed
-entry version for optimistic concurrency where the Procedure contract declares
-`expectedVersion`; keep its input contract intact when adjusting presentation.
-
-## Verify a change
-
-1. Edit the application manifests, then run `mantle validate`, `mantle generate`
-   and `mantle generate --check` through the local package manager.
-2. Restart/reload the host so Admin receives the new compiled plan. Check
-   `/admin/api/collections`, `/admin/api/views-manifest` or
-   `/admin/api/operations` in an authenticated session if the UI seems stale.
-3. Open the affected list and editor: check labels, actual columns, filters,
-   form values and keyboard access. Verify a record after saving, and verify
-   report filters in CSV as well as the visible page.
-
-`uiSchema` roots and supported nested keys are closed. Schema accepts `fields`,
-`list`, `nav`; Procedure accepts `collectionAction`, `fields`; staff View accepts
-`list`. They do not accept a custom layout, CSS, React component, arbitrary
-widget name or permission policy. See [Schema](../reference/schema.md#uischema),
-[View](../reference/view.md#uischemalist) and [Procedure](../reference/procedure.md#uischema).
-
-For a new layout or unsupported widget, use application-owned UI against the
-appropriate APIs or propose a change to the Admin UI package. Do not patch
-`public/_mantle/admin/`: generation replaces those prebuilt assets. Visitor
-frontend styles and the `theme` skill's site changes do not style Admin.
-
-## Source
-
-- [Admin UI contract validation](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
-- [Admin metadata and operation discovery](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [Entry form renderer](../../../packages/mantle-admin-ui/src/features/content/entry-edit-view.tsx)
-- [Collection renderer](../../../packages/mantle-admin-ui/src/features/content/collection-view.tsx)
-- [Action renderer](../../../packages/mantle-admin-ui/src/features/content/row-operations.tsx)
-- [Navigation rules](../../../packages/mantle-admin-ui/src/lib/collection-nav.ts)
+| 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

@@ -1,97 +1,87 @@
 ---
-description: Trace what npx skills add installs, hand off to the pinned SDK, project version-matched skills and diagnose missing or stale instructions.
+description: Install the Mantle agent plugin or its one skill, hand off to the installed package's own docs, and diagnose missing or stale instructions.
 ---
 # Install and verify agent instructions
 
-There are two separate installations: an agent's bootstrap skill and the
-application's SDK. Installing one does not install the other.
+Two separate things are installed: the agent's `mantle` skill and the
+application's `@aotter/mantle` package. Installing one does not install the
+other, and the installed package is always the authority for the version it
+carries.
 
-## 1. Install the bootstrap skill
+## 1. Install the `mantle` skill
+
+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.10`). 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.
+
+For Codex, pin the marketplace checkout:
+
+```sh
+codex plugin marketplace add aotter/mantle --ref v0.2.0-alpha.10
+codex plugin add mantle@mantle
+```
+
+For Claude Code, first clone the release into a directory you will keep:
 
 ```sh
-npx skills add aotter/mantle
+git clone --depth 1 --branch v0.2.0-alpha.10 https://github.com/aotter/mantle.git mantle-plugin
 ```
 
-The installer selects the repository's `mantle` skill. Read its printed
-installation path. In a project-local Codex installation that is
-`.agents/skills/mantle/SKILL.md`, not `skills/install/SKILL.md` (the latter is
-its source-repository path). Other agent selections and global installation
-can use different locations.
+Then, in Claude Code, use that checkout's absolute path:
 
-The command installs the selected brief; it does not materialize a Mantle
-application, install `@aotter/mantle`, or copy `docs/`. The unqualified GitHub
-source follows its default branch, not necessarily `develop` or the npm
-version you intend to use. The skills installer's lock identifies the source
-skill; it is not the application's dependency lockfile.
+```text
+/plugin marketplace add /absolute/path/to/mantle-plugin
+/plugin install mantle@mantle
+```
 
-## 2. Select the SDK version, then read its own instructions
+Cursor and GitHub Copilot use their plugin manifests from the same tagged
+checkout. Without a plugin host, install only the consumer skill by name:
 
-Use the version the project already pins, or resolve the requested npm channel
-once and pin every selected `@aotter/mantle*` dependency to the same exact
-version. `latest` and `alpha` can describe different capabilities. Resolve only
-requirements the user has not provided: host, storage, public API/HTML, and
-whether staff need Admin. Follow the bootstrap skill to install the selected
-packages locally.
-No matching `mantle-starters` tag or bundle is needed to create a project.
+```sh
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.10 --skill mantle
+```
 
-Then read:
+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.
+
+## 2. Install the SDK, then read its own docs
+
+Use the version the project already pins. For a new project, choose a 0.2.x
+version with `npm view @aotter/mantle dist-tags` and install it with an exact
+version; every `@aotter/mantle*` package stays at that same version. Then
+read, from the application:
 
 ```text
-node_modules/@aotter/mantle/skills/install/SKILL.md
+node_modules/@aotter/mantle/README.md
 node_modules/@aotter/mantle/docs/handbook/start/overview.md
 node_modules/@aotter/mantle/docs/handbook/reference/features.md
+node_modules/@aotter/mantle/docs/skills/<workflow>/SKILL.md
 ```
 
-These files are in the npm tarball. They are the version-matched authority,
-including when the bootstrap skill came from a different Git ref. Every
-`docs/...` path in the skill resolves under the installed package, not under
-`.agents/skills/mantle/`. Keep using that SDK's docs for host examples and CLI
-behavior. No local `mantle` binary is available before package installation.
+These ship in the npm tarball and match the installed code. Prefer them over
+the skill's GitHub copy and over any online handbook.
 
-## 3. Project the ongoing workflows
+| Package skill | Read it when |
+|---|---|
+| `docs/skills/develop/SKILL.md` | changing manifests, handlers, the service or its surfaces |
+| `docs/skills/integrate/SKILL.md` | adding Mantle to an existing application |
+| `docs/skills/update/SKILL.md` | upgrading `@aotter/mantle`, including from 0.1.x |
+| `docs/skills/provision/SKILL.md` | deploying, with production sign-in |
+| `docs/skills/media-gc/SKILL.md` | auditing or removing stale R2 uploads |
 
-From the application root, after installing the SDK:
+0.2.0 has no `mantle skills` command: nothing is copied into the project.
+An agent reads these files from `node_modules` when the task calls for them.
 
-```sh
-pnpm exec mantle --help
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-```
+## 3. Verify the application
 
-| Artifact | What you get |
-|---|---|
-| `.agents/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | The installed package's four project-scoped workflows. |
-| `.claude/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | Identical bytes for Claude compatibility. |
-| `node_modules/@aotter/mantle/skills/` | All eight shipped skills, including opt-in `mantle`, `integrate`, `provision` and `media-gc`. |
-| `node_modules/@aotter/mantle/docs/` | Handbook and examples matched to the package. |
-
-`mantle skills` overwrites these four generated projections. Keep project-specific
-instructions elsewhere. `--check` does not write: exit 0 means they match,
-1 means missing/stale projections, and 2 means a command/package error.
-`mantle generate` does not project skills. Projection does not remove an older
-bootstrap `install` or legacy `.agent/skills` copy; use the version-matched
-project skills for ongoing work.
-
-## 4. Complete and verify the application
-
-Follow a [tutorial](../start/overview.md#start-with-your-integration), then run
-its generation, validation, TypeScript checks and actual local route probes.
-Successful skill installation proves only that the instructions were copied.
-It does not prove a server, login, Admin assets or MCP connection works.
-
-| Symptom | Cause and next step |
-|---|---|
-| `skills/install/SKILL.md` is missing | That is source provenance. Read the installer's destination instead. |
-| `docs/...` is missing after `skills add` | The skill does not carry the handbook. Install the pinned SDK and read its embedded docs. |
-| `mantle` is missing | Install local `@aotter/mantle`; run its binary through the project package manager. |
-| `MANIFEST_ROOT_NOT_FOUND` | Check the installed CLI and saved project selection. New generated projects may start with an empty manifest set; legacy compile mode still needs the configured source. |
-| `mantle skills --check` exits 1 | Run `mantle skills`, then read the refreshed project skill. |
-| No projected integrate/provision/media-gc skill | These are intentionally opt-in. Read their installed package files when the task calls for them. |
-| A documented feature fails on an older release | Use that release's docs or explicitly upgrade; changing a skill does not change Runtime. |
-
-## Source
-
-- [Bootstrap install skill](../../../skills/install/SKILL.md)
-- [Projection implementation](../../../packages/mantle/src/cli/skills.ts)
-- [Package file list](../../../packages/mantle/package.json)
-- [Package docs and skills copying](../../../scripts/sync-package-docs.mjs)
+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.
+
+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.