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

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.9`). 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.9
 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.9 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.9 --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.

package/docs/handbook/guides/agent-workflow-acceptance.md

@@ -0,0 +1,222 @@
+# Independently accept a user-facing workflow
+
+Before reporting any user-facing deliverable as done, exercise it from the
+user's position with a fresh end-user agent. This applies to Admin pages and
+customisations, application pages and web routes, REST APIs used by clients,
+MCP tools and MCP Apps. Generation, typechecking, scripted smoke tests and an
+author's replay remain useful; they do not establish independent acceptance. A
+fresh context is not enough if the author still chooses a workflow that mirrors
+the implementation. Every acceptance round gives the evaluator responsibility
+for choosing realistic tasks and judging the result, not just following a
+prescribed sequence.
+If independent acceptance is not run, report `UNVERIFIED`; if a fresh evaluator
+or authorized test transport is unavailable, report `BLOCKED`; neither outcome
+is done.
+
+Use the surface the intended user actually uses: a real browser session for
+Admin and application pages; for REST, an HTTP client plus the public API
+reference and base URL a real client developer receives; an MCP client for
+tools; and the real MCP App host/AppBridge flow for Apps. This is an
+application-authoring practice, not an SDK runtime service or a new test runner.
+Use the project's existing local setup, normal authorized sign-in and isolated
+fixtures. Setup hands over the role's established browser session or client
+token; the evaluator never acquires or widens credentials. Give it only its
+authorized surface. Do not enable extra routes, roles or generic writes to make
+the exercise pass.
+
+## Audit MCP tool design before implementation
+
+Start with the original user brief, business role and explicit requirements,
+not a list of CRUD endpoints or a task derived from what you implemented.
+Before writing manifests or handlers, record the intended jobs and assumptions
+in the existing design note. Keep the author's capability map separate from
+the brief an evaluator receives: the evaluator chooses its own tasks and
+observable success criteria. Do not expand application scope or authority
+merely to satisfy an evaluator's newly inferred product wish.
+
+In the application's existing design note or issue, map each goal step to its
+proposed public capability: discovery inputs, returned IDs and evidence, allowed
+caller, write/transaction boundary and recovery. Mark missing capabilities or
+unresolved contracts as gaps before writing manifests or handlers. Review the
+following rubric against that map:
+
+| Design question | Required contract or explicit gap |
+| --- | --- |
+| Can the agent locate the right record? | Bounded search/filter inputs, stable IDs, deterministic cursor paging and sensible limits. It must not scan every list or guess an ID from a display label. |
+| Can it choose an eligible relation? | Finding an ID is not proof of business eligibility: verify the role, state and ownership required by the relationship. Return enough labels to distinguish same-name choices before writing. |
+| Can it correct an ordinary mistake? | State how to amend, clear or replace optional fields and relations, and how duplicate records are detected or reconciled. Test omitted, null and empty inputs against that contract; existence and type checks alone do not establish business validity. Express conditional-required inputs with the supported [input rules](../reference/surface.md) before writing handler checks. |
+| Can it read a complete business result? | ID-based detail/readback under the intended caller, including every relation the goal creates or changes. A parent list is not proof of its child/contact/state details. Distinguish absent/inaccessible from incomplete evidence. |
+| Can it verify a create or update? | Return the backend entity ID, actual committed version where applicable, and a safe result summary or a documented authorized readback. State the exact result nesting. Echoed input or the submitted `expectedVersion` is not proof of committed state. Specify PATCH versus full replacement and omitted/null-field semantics so an update cannot erase unseen fields. |
+| What does a version protect? | Name its entity/snapshot scope; a parent version does not imply child rows or aggregates are unchanged. Use the reviewed observed version for OCC, define conflict behavior and preserve the user's proposed changes without silently rebinding/retrying. |
+| Can it complete a business transition? | Name permitted source/destination states, preconditions, related effects and final readback. Prefer an outcome-oriented operation when arbitrary field updates would leave the workflow unfinished. |
+| What commits together? | Define the native Procedure/Store atomic boundary. Separate tool calls are independent; describe partial success and deliberate compensation. Do not imply that an agent can roll back earlier calls or that compensation is always possible. |
+| Can it interpret refusal and failure? | Document success and structured diagnostic/error envelopes, including MCP `isError`; HTTP 200 or a wrapper's transport success is insufficient. Inspect raw MCP diagnostics separately from host-visible wrapper errors; a wrapper label alone does not locate a runtime defect or require global error normalization. Missing relations, stale versions and denied callers need meaningful refusals without leaking another caller's records or native internals. |
+| What happens after a duplicate or uncertain write? | State whether idempotency exists, its key/scope/lifetime when supported, or that repeated successful calls may repeat effects. Provide an authorized reconciliation route for timeout/unknown outcomes; never automatically retry an uncertain write. |
+| Can it explain amounts correctly? | Declare currency, stored/wire units, exact-value representation, rounding and whether null means unknown. Label every ratio's numerator and denominator: cost/budget, sales/budget and gross/sales are different measures. |
+| Does data remain usable without an App? | Keep ordinary reads data-only; attach a renderer deliberately for interactive inspection, with structured/text fallback. Rendering must not write or imply approval. Host catalog refresh, OAuth and real client/UI behavior have separate acceptance; descriptions cannot force generative UI layout. |
+| Does every step respect the user's authority? | Verify least privilege, tenant/owner scope, allowed fields, relation access and negative cases on the server. Tool visibility, annotations, descriptions and UI confirmation never grant permission. Use authorized disposable fixtures and a cleanup owner without widening production writes/deletes. |
+
+A design passes this audit only when each required goal step has a supported
+capability and verifiable output/recovery; preserve unresolved gaps and owners.
+The audit is a design review, not execution evidence. Record intentional
+exclusions, but keep an unmet explicit user requirement unresolved until the
+user changes its scope; do not redefine it as optional to make a round pass.
+Reuse the installed version's Views,
+Procedures, Store and surface contracts; a missing business tool is not by
+itself an SDK runtime defect.
+
+For simple creates/partial updates, prefer a declared Store-backed `ref`
+Procedure: await the caller-bound Store write, return a safe allowlist with its
+actual returned ID/version, and keep `requires` plus generated input validation
+at invocation. A transaction-bound write result remains provisional until the
+outer transaction commits; publish success only after that boundary completes. Store row policy alone is not Procedure authorization. Define
+omitted versus null patch semantics; never fill unseen fields with defaults.
+Keep SQL Procedures for atomic stock changes, conditional state transitions and
+related writes. A TypeScript pre-read does not replace an atomic WHERE/CHECK;
+D1 supports batch, not an interactive transaction or consuming an earlier batch
+result. See the [Store write guide](typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).
+
+Then implement the minimum contract and run generated/type, authorization,
+atomicity and other relevant regressions. Follow the independent acceptance
+rounds below before claiming the user-facing work is done. Keep the author's
+capability map and worked call sequence out of the fresh agent's prompt: an MCP
+evaluator must discover the workflow from public tool descriptions and results.
+
+## Run independent acceptance rounds until they converge
+
+1. **Freeze scope and revision, not the evaluator's itinerary.** Supply the
+   original user brief, business role, explicit requirements and exclusions,
+   exact application/SDK revision, authorized transport, permitted fake-data
+   actions, per-round interaction/time/write budgets, a user-set total round cap of at
+   least three (default four) and a fixture cleanup owner. Seed fixtures with
+   realistic volume and variety: other owners' records, several states and more
+   than one page of results, so evaluators' own goals reach discovery, paging
+   and authority. Explicitly authorize synthetic writes only where the user has
+   authorized testing. Production writes and external side effects need their
+   own authorization.
+2. **Use a new end-user subagent in every round.** Start without inherited
+   implementation history. Withhold source, SQL, internal docs, capability maps,
+   precomputed IDs, hidden routes or tool names, prescribed interaction order
+   and previous reports or fixes. Ask
+   the agent to state its own realistic goals and observable success criteria
+   before execution, use or discover the user-facing surface and assess whether
+   it supports the work. Ask whether it can make the decisions needed for its
+   goals, not merely issue successful calls. Do not prescribe the author's
+   happy path or require a minimum number of defects. Zero findings is a valid
+   observation. Run the evaluator outside the project directory, without Mantle
+   skills or project instruction files, with only the intended browser, HTTP
+   client, MCP client or MCP App host/AppBridge available, and record that
+   isolation in the evidence. For a multi-role workflow, run one
+   fresh agent per role in the same round on shared live data in the brief's
+   natural order; the later role finds earlier records through the service, and
+   the first agent may take a resumed turn to observe the outcome. Each agent
+   still chooses its own goals.
+3. **Keep evidence and scope judgments.** Require PASS/FAIL/BLOCKED per chosen
+   goal, actual readbacks, rejected writes, recovery, interaction costs and
+   design findings with materiality, evidence and the smallest suggested repair.
+   Separate a violated explicit requirement, a demonstrated defect and a newly
+   inferred product need. Missing capability is a finding, not permission to
+   invent interfaces or automatically expand the product. A rendered page,
+   HTTP 200, successful tool result or creation ID alone does not prove a
+   complete business result. Preserve setup assistance
+   and label any coached attempt; do not count it as a clean independent round.
+4. **Repair outside the evaluator's context.** The author retains the full
+   findings ledger, classifies application design, SDK/runtime, docs, transport
+   setup and host issues separately, then makes the smallest in-scope repair.
+   Turn reproduced failures into focused regression checks and run them with
+   relevant authorization, OCC and atomicity checks. Keep native guards; do not
+   shim away errors or retry uncertain writes. A runtime change needs a minimal
+   supported-contract reproduction. Record optional product suggestions and
+   unresolved scope questions rather than silently dropping findings.
+5. **Repeat the whole evaluation with a fresh agent.** Freeze the new revision
+   and supply the same original brief and authority, with new fixtures. Let
+   this evaluator choose its own goals again; do not pass the ledger or steer
+   it toward the previous repair. Replaying a known failure remains an author's
+   regression check and does not replace independent design evaluation.
+6. **Judge convergence across rounds.** Converge only after two consecutive
+   unassisted fresh rounds on the same revision with no new material in-scope
+   finding and no unresolved material defect. A finding is material when it
+   violates an explicit requirement, makes an evaluator's goal FAIL or BLOCKED,
+   or exposes an authority, data-integrity or uncertain-write defect; record
+   why any finding was judged non-material. Every repair creates a new revision
+   and resets the streak, so hold non-material repairs until after the verdict.
+   Each explicit requirement observable from the evaluator's role needs
+   evaluator-observed evidence; requirements outside that role's view (another
+   caller's isolation or hidden state) are verified by author regressions and
+   reported under that label. A role-observable requirement no evaluator reached
+   is UNVERIFIED and blocks CONVERGED. If fresh evaluators never reach a required
+   path, vary the fixtures, not the brief or the steps, or report that path as
+   UNVERIFIED. Repeated success on one narrow path cannot establish broader
+   readiness. Keep optional wishes, non-material suggestions and external
+   BLOCKED gates visible; no finding count proves absence of defects. When the
+   round cap or an external blocker stops the loop, report NOT CONVERGED or
+   BLOCKED with the remaining work, not acceptance. Setup cleans isolated
+   fixtures in `finally` after every round, including failed/aborted rounds.
+
+If a fresh agent or authorized test transport is unavailable, record independent
+acceptance as BLOCKED and report the scripted checks separately. Do not invent
+an independent result. Do not deploy or publish merely to obtain acceptance.
+
+## Give the agent a role and the user's brief
+
+Fill in a brief like this using the actual user's request and authorized
+scope. Do not replace it with a sequence tailored to existing tools:
+
+> You are a [business role] working in [business context]. The user requested:
+> [original brief, explicit requirements and exclusions]. You are authorized
+> to test with fictional data through [user-facing surface and entry point]
+> within [allowed actions and interaction/time/write budgets]; [owner] will clean up
+> the fixtures.
+> Independently define realistic acceptance goals and observable success
+> criteria before testing. Use or discover the supplied interface and assess
+> whether it lets you make the decisions your goals require, not merely perform
+> successful interactions. Report per-goal PASS/FAIL/BLOCKED with readback
+> evidence, design shortcomings, interaction costs and minimal improvements.
+> Distinguish failures within the requested scope from newly inferred product
+> needs; do not invent unsupported interfaces or change the product. Do not inspect
+> source, internal docs or a database, blindly retry uncertain writes, or act
+> outside the supplied authority. Finding no defects is acceptable; report
+> what you actually covered and what remains unverified.
+
+The author separately verifies isolation between callers, stale-version
+refusal, unknown-outcome handling and effects hidden from the evaluator's role
+through authorized test fixtures. Do not grant the evaluator extra authority
+just to observe hidden state. Keep author regressions distinct from what the
+fresh agent actually observed.
+
+## Record evidence in the existing issue or handoff
+
+Use ordinary Markdown; no new receipt schema or framework is required:
+
+- Original brief, explicit requirements and exclusions, role, environment,
+  per-round budgets and round cap.
+- Setup assistance and what each agent could access; identify distinct rounds.
+- Per round: revision, the evaluator's own goals and criteria, per-goal
+  PASS/FAIL/BLOCKED, actual readbacks and interaction references,
+  request/page/tool counts
+  and negative/recovery attempts, with their differing scope stated.
+- Findings ledger with materiality, owner, disposition, minimal repair and
+  regression commands/results.
+- Streak and reset history; coverage of each explicit requirement
+  (evaluator-observed, author regression only, or UNVERIFIED); the final
+  CONVERGED / NOT CONVERGED / BLOCKED / UNVERIFIED verdict and rounds used. Retain every
+  failed report.
+- Fixture cleanup result and every remaining limitation.
+
+Keep credentials, raw auth logs, full resource HTML and private operational
+details local/private; publish only sanitized contract evidence. Do not claim a
+call-cost improvement when rounds exercise different negative/discovery cases.
+Version fields usually describe an entity row, not all related aggregates;
+state money units and the denominator of any budget or margin calculation.
+
+## Keep surface evidence distinct
+
+Evidence from one surface does not prove another. Tool metadata and protocol
+discovery do not prove that an MCP App rendered in its real host through
+AppBridge; a REST response does not prove the Admin or application page; and a
+browser rendering does not prove an external client can use the REST contract.
+Record the actual browser, client or host version, identity, observed interface
+and behavior for the deliverable under acceptance. Keep data results available
+without Apps; descriptions cannot force a host's generative UI layout. Local
+cookie-session acceptance, OAuth client integration and long-term renewal
+likewise require their own evidence when they are part of the requested work.