@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

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

@@ -13,21 +13,20 @@ 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.
+`v0.2.1-alpha.1`). Pin the tag to keep instructions aligned with the application's
+SDK. 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.9
+codex plugin marketplace add aotter/mantle --ref v0.2.1-alpha.1
 codex plugin add mantle@mantle
 ```
 
 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
+git clone --depth 1 --branch v0.2.1-alpha.1 https://github.com/aotter/mantle.git mantle-plugin
 ```
 
 Then, in Claude Code, use that checkout's absolute path:
@@ -41,9 +40,12 @@ 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 https://github.com/aotter/mantle/tree/v0.2.0-alpha.9 --skill mantle
+npx skills add aotter/mantle@mantle
 ```
 
+Without a version it follows `main`, the latest stable release. To match the
+application's SDK exactly, add its release tag: `npx skills add aotter/mantle#v0.2.1-alpha.1@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.
@@ -54,10 +56,17 @@ 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:
+Use the version the project already pins. For a new project, install this
+handbook's version exactly. 0.2.1-alpha.1 is a prerelease; stable 0.2.0 remains the
+production line, and its own tagged handbook describes it.
+
+```sh
+pnpm add --save-exact @aotter/mantle@0.2.1-alpha.1
+```
+
+Add optional `@aotter/mantle-ui@0.2.1-alpha.1` and `@aotter/mantle-admin@0.2.1-alpha.1` only
+when the selected surfaces need them. Every selected `@aotter/mantle*` package
+stays at the same exact version. Read, from the application:
 
 ```text
 node_modules/@aotter/mantle/README.md
@@ -76,6 +85,7 @@ the skill's GitHub copy and over any online handbook.
 | `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 |
+| `docs/skills/performance/SKILL.md` | after acceptance converges, or when a page, first request or query is slow |
 
 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.

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

@@ -6,12 +6,15 @@ 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.
+the implementation. Every acceptance round gives the evaluator only a
+role and the entry points that role uses; it derives realistic tasks itself
+and the author scores them against a private rubric. The first delivery gets
+full acceptance; after a repair, the change decides what
+[re-runs](#re-verify-what-a-repair-touches).
 If independent acceptance is not run, report `UNVERIFIED`; if a fresh evaluator
 or authorized test transport is unavailable, report `BLOCKED`; neither outcome
-is done.
+is done. Either way, report the evidence you do have in the
+[layered handoff](#report-done-ness-in-layers).
 
 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
@@ -29,8 +32,8 @@ the exercise pass.
 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
+in the existing design note. The capability map feeds the private rubric
+(below); an evaluator receives only its role and 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.
 
@@ -82,101 +85,170 @@ 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.
+## Run role-only acceptance rounds until they converge
+
+The evaluator gets a role, not a task list. It works out what that role needs
+to get done from the interface itself; what it derives, and what it misses, is
+the evidence.
+
+1. **Write a private rubric first.** From the original brief, the author lists
+   what each role must be able to do on each surface (Admin, application
+   pages, REST, MCP), with observable success criteria, explicit exclusions
+   and the authority each role must not have. The rubric stays with the author;
+   no evaluator ever sees it, its wording or its order.
+2. **Hand each evaluator only its role.** Supply the business role and context
+   in one or two sentences, the entry points that role really uses (Admin URL,
+   site URL, REST base URL and API reference, MCP endpoint), a signed-in browser
+   session or client token from setup, the interaction/time/write budget,
+   permitted fake-data actions and what is forbidden (source, SQL, internal
+   docs, the database, other roles' credentials, blind retries of uncertain
+   writes). Withhold the brief's requirement list, capability maps, tool names,
+   precomputed IDs and earlier reports. Seed realistic fixtures: other owners'
+   records, several states and more than one page of results. Run the evaluator
+   outside the project directory, without Mantle skills or project instruction
+   files, and record that isolation.
+3. **Let it derive the work, then do it.** Before any interaction the evaluator
+   writes down what this role would need to accomplish and how it would know
+   each one succeeded. It then refines that list as it discovers the interface
+   (at least once after a first look, again after its first attempts), executes
+   it, and reports PASS/FAIL/BLOCKED per goal with readbacks, rejected writes,
+   recovery attempts and interaction counts. Zero findings is a valid result.
+4. **One fresh agent per role, every surface.** In the first round, and in any
+   round the [re-verification rule](#re-verify-what-a-repair-touches) widens
+   to all of them, cover every role and surface. For the default two roles, run
+   an `admin` evaluator and a `user` evaluator in the same round on shared live
+   data, in the brief's natural order. Between them they cover every surface
+   the app exposes to each role: Admin for `admin`, pages for visitors and
+   members, REST for client developers, MCP for both roles' AI clients. A
+   surface no evaluator reached stays UNVERIFIED.
+5. **Score against the rubric outside the evaluator.** The author compares the
+   evaluator's derived goals and results with the rubric. A rubric item the
+   evaluator never thought of is itself a finding: the interface did not make
+   that job discoverable. Classify every finding P0 (data loss, authority or
+   integrity defect, uncertain write), P1 (a rubric item FAIL, BLOCKED or not
+   discoverable), P2 (friction) or P3 (suggestion), with evidence and the
+   smallest repair. Separate a violated explicit requirement, a demonstrated
+   defect and a newly inferred product wish; a wish is not permission to grow
+   the product. A goal the evaluator's own environment stopped (its tool
+   approval, sandbox or network, not an app refusal) is not a finding: record
+   it as an [environment block](#report-done-ness-in-layers) and rerun that
+   role once it is lifted.
+6. **Repair outside the evaluator's context, then re-verify what it touches.**
+   The author keeps the findings ledger, makes the smallest in-scope repair,
+   adds focused regressions (authorization, OCC, atomicity), and freezes a new
+   revision. The next round re-runs the roles and surfaces the
+   [re-verification rule](#re-verify-what-a-repair-touches) names, with new
+   agents and new fixtures, and passes them nothing from earlier rounds.
+7. **Converge or stop.** A round converges when it has no P0 or P1 and
+   evaluator-observed results cover every rubric item visible to their roles:
+   from this round, or reused from an earlier round under the
+   re-verification rule. Items outside any role's view (another caller's
+   isolation, hidden state) need author regressions, reported under that
+   label. Run at most three
+   rounds. If the third still has a P0 or P1 or an uncovered rubric item, report
+   BLOCKED with the remaining ledger, not acceptance. Setup cleans fixtures in
+   `finally` after every round, including aborted ones.
 
 If a fresh agent or authorized test transport is unavailable, record independent
-acceptance as BLOCKED and report the scripted checks separately. Do not invent
+acceptance as BLOCKED and report the scripted checks on their own
+[layers](#report-done-ness-in-layers). 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.
+Acceptance proves the behavior, not its speed. Once a round converges, the
+[performance skill](../../skills/performance/SKILL.md) decides which performance
+checks apply and holds them to their targets; a performance repair that changes
+what a role sees or can do returns here, scoped by the
+[re-verification rule](#re-verify-what-a-repair-touches).
+
+## Re-verify what a repair touches
+
+The first delivery always gets full acceptance: every role, every surface.
+After a repair, the change itself decides what runs again, not the finding
+that prompted it. Rounds before convergence are not accepted, so diff against
+evidence, not rounds: for each item you want to reuse, diff the current
+revision against the revision it was observed at, and pick the widest row that
+diff matches. A chain of repairs adds up; a page-only repair followed by a
+handler repair has to re-run what the handler repair reaches.
+
+| The repair changes | Re-run with fresh evaluators | May reuse |
+| --- | --- | --- |
+| Only presentation: page or Admin layout, CSS, copy, client-side display | Blind acceptance of the affected UI, for each role that uses it. A shared component or layout affects every page that renders it. | REST and MCP evidence from the same business-rule version |
+| A public contract: a tool or route description, input, output or error shape; the generated client or other `generated/` output it changes | That surface for each role that uses it, plus every UI that consumes it | Other surfaces at the same business-rule version |
+| Authentication, sessions, roles, `requires`, row or tenant scope | Every surface that the changed rule guards, for every affected role | Nothing those surfaces depend on |
+| A SQL Procedure or View, a `uniqueIndexes` entry, a check or lock, a migration that changes results, a handler's business rule | Every surface that reads or writes that data | Nothing those surfaces depend on |
+| A shared transport: the service entry, routing, the HTTP or MCP mount, a shared error envelope | Every surface on that transport | Nothing on that transport |
+
+The business-rule version is the revision of the manifests, SQL, migrations,
+handlers, authorization and service entry. A repair that changes none of
+them keeps that version, so evidence collected at it still stands for
+surfaces the repair did not reach. A repair that changes any of them
+starts a new business-rule version, and looking at the UI alone is not
+enough. One exception: a repair that only adds or drops a non-unique Schema
+`indexes` entry and its migration keeps the version. It changes speed, not
+which rows a read returns or which writes are refused. A `uniqueIndexes`
+entry, a check or a lock does change which writes succeed, so it falls in the
+SQL row. When the diff is unclear, widen.
+
+Every row still runs the author's regressions on the new revision (layers 1
+and 2 of the [layered report](#report-done-ness-in-layers)): `pnpm check`,
+`pnpm smoke`, `pnpm test` and the focused regressions for the repair.
+
+A re-run evaluator is as fresh as the first: a new agent, new fixtures, only
+its role and the entry points under re-test. Do not tell it what was
+repaired, what to check or what an earlier evaluator did. No previous
+answers, rubric or precomputed steps.
+
+For every rubric item that was not re-run, record the round and revision its
+evidence comes from and why the changes since that revision could not affect
+it. Never report a
+reused item as observed in a later round.
+
+## Hand each role to its evaluator
+
+Setup signs each role in; the evaluator receives the role's access, never a credential it could reuse or widen.
+This is the authorized test transport the BLOCKED rule above refers to.
+
+- **Local session URL (the app shell's default).** `pnpm accept` in an app written by `mantle init` starts the app
+  on a fresh local D1, signs the admin in, runs an optional fixtures module, signs the user in and prints one local
+  URL per role. Each URL forwards every request with that role's session and refuses `/api/auth/*`. Give the
+  evaluator only its URL: MCP at `<url>/mcp` (user) or `<url>/mcp/admin` (admin) for any streamable HTTP MCP client,
+  Admin at `<url>/admin` and member pages at `<url>/` in a browser, REST at `<url>/` with no credential. An evaluator
+  without an MCP client uses `node accept.mjs mcp <endpoint> [tool [json]]`, which prints the raw result including
+  `isError`. The app README's "Independent acceptance" section shows the fixtures module.
+- **An external MCP host over OAuth.** To accept the connection a real client uses (Claude, ChatGPT or another host
+  that supports MCP OAuth), deploy or tunnel the app as you would for that host, add `<origin>/mcp` or
+  `<origin>/mcp/admin` to the host in setup, and complete sign-in and consent as the role's fictional identity. The
+  evaluator then works in that already-connected host. Its token stays in the host; the evaluator neither sees nor
+  requests it. Record this as OAuth evidence, separate from the local session URL (see
+  [OAuth](oauth.md)).
+
+Either way, the evaluator's prompt names the URL or the connected host, never a cookie, token or sign-in step.
+
+If you cannot start a fresh agent yourself (for example, you are a subagent without that tool), prepare everything
+else: the rubric, the fixtures module, `pnpm accept` running, and one filled-in role prompt per role (below) naming
+its URL. Hand the prompts to whoever can start agents (the person or the orchestrating agent), keep the app running,
+and report acceptance as BLOCKED with the prompts attached until their reports come back. Score those reports as
+usual.
+
+## Give the agent a role
+
+Fill this in per role. It names the role and the doors, never the jobs:
+
+> You are [role, for example "a purchasing manager"] at [business context in
+> one sentence]. You use [entry points for this role from `pnpm accept`: Admin
+> URL, site URL, REST base URL and reference, MCP endpoint]; setup has already
+> signed you in as [fictional identity]. Budget: [interactions/time/writes]. You may create and
+> change fictional records; [owner] cleans up. Do not read source, internal docs
+> or a database, use anyone else's access, or retry a write whose outcome you
+> do not know.
+> First, write down what someone in this role needs to get done with this
+> service and how you would tell each one worked. Refine that list after a
+> first look at the interface and again after your first attempts. Then do the
+> work and report each goal as PASS/FAIL/BLOCKED with what you read back,
+> what was refused, what it cost you, and the smallest change that would have
+> helped. For BLOCKED, say whether the service refused you or your own tools
+> or permissions stopped you. Report what you covered and what you could not reach; finding nothing
+> wrong is acceptable.
 
 The author separately verifies isolation between callers, stale-version
 refusal, unknown-outcome handling and effects hidden from the evaluator's role
@@ -184,23 +256,71 @@ 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.
 
+## Report done-ness in layers
+
+Report a handoff in four layers, in this order, each for the exact commit. Each
+layer proves something the others do not; a passing layer neither replaces nor
+is invalidated by another layer's result.
+
+| Layer | What it proves | Evidence |
+| --- | --- | --- |
+| 1. Generation and types | Manifests compile, `generated/` is current, the app typechecks and builds. No handler runs. | `pnpm check` (includes `generate --check`), `pnpm build` |
+| 2. Business rules and permissions | Handlers on a fresh local D1 over HTTP: each operation at its edges, refusals, caller isolation, visitor pages, MCP discovery, the Admin MCP App loading. Author's evidence. | `pnpm smoke`, `pnpm test`; [Local HTTP checks](local-testing.md) |
+| 3. Independent acceptance, per role | A fresh agent given only its role and entry points finds and finishes that role's work on each surface it uses. | Per role: the [rounds](#run-role-only-acceptance-rounds-until-they-converge) verdict and surfaces covered, naming the round and revision of any [reused](#re-verify-what-a-repair-touches) evidence |
+| 4. External platform | A real MCP host connects over OAuth; the production origin serves the deployed app. Local cookie sessions prove neither. | Host and version, identity, origin, observed result |
+
+Give each layer, and each role on layer 3, one status:
+
+- **verified**: the evidence above, with its command or host and result.
+- **failed**: the product is wrong. Name the failing check or finding.
+- **BLOCKED**: the layer could not run. Give the reason, what refused or is
+  missing, and what would unblock it.
+- **not applicable**: with the reason. Layer 4 is not applicable unless the
+  requested work includes an external host connection or a deployment.
+
+A layer nobody attempted is UNVERIFIED, as above. A block from the execution
+environment (an agent's approval policy refusing fictional writes, no browser,
+no network, a sandbox) is BLOCKED on that layer only. It is never a failed
+layer or a product finding, and it does not invalidate the evidence on other
+layers. Do not work around it by widening the evaluator's authority, faking a
+result or deploying; ask whoever controls the environment and rerun only that
+layer on the same revision.
+
+The work is done only when layers 1 to 3 are verified for every role and
+surface, and layer 4 is verified or not applicable. Partial evidence is still
+reported, layer by layer; it is not done:
+
+```markdown
+| Layer | Status | Evidence |
+| --- | --- | --- |
+| 1. Generation and types | verified | `pnpm check`, `pnpm build` at <commit> |
+| 2. Business rules and permissions | verified | `pnpm smoke` (<n> checks), `pnpm test` |
+| 3. Acceptance: admin | BLOCKED: evaluator's approval policy refused to create fictional records; needs <permission> | round 1 stopped at goal <n> |
+| 3. Acceptance: user | verified: CONVERGED in round <n> | member pages in round <n>; MCP reused from round <m> at <revision> (page-only repair) |
+| 4. External platform | not applicable: no deployment or external host requested | |
+```
+
 ## 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.
+- Original brief, the private rubric, roles, 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
+- Per round: revision, business-rule version, the roles and surfaces re-run
+  and why (the [re-verification rule](#re-verify-what-a-repair-touches) row),
+  each evaluator's derived goals (first list and
+  refinements) and criteria, the gaps between them and the rubric, 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
+- Findings ledger with P0–P3, 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.
+- Coverage of each rubric item (evaluator-observed in this round,
+  evaluator-observed and reused from round <n> at <revision> with the reason,
+  author regression only, or UNVERIFIED); the final CONVERGED / BLOCKED / UNVERIFIED verdict and rounds
+  used, which is layer 3 of the [layered report](#report-done-ness-in-layers).
+  Retain every failed report.
 - Fixture cleanup result and every remaining limitation.
 
 Keep credentials, raw auth logs, full resource HTML and private operational

package/docs/handbook/guides/local-testing.md

@@ -0,0 +1,85 @@
+---
+description: Scripted local checks before acceptance - handlers over real HTTP, public pages without JavaScript, MCP discovery, Admin's MCP App, and how to account for every surface.
+---
+# Local HTTP checks
+
+`pnpm check` proves that the manifests compile and the app typechecks; it runs no handler. Before you report an app
+or a feature ready, run it on a fresh local D1 and drive it over HTTP. In an app written by `mantle init`, that is
+`smoke.mjs` on the shell's `smoke-kit.mjs` (`pnpm smoke`): it applies `generated/schema.sql` and `seed.sql`, starts
+`wrangler dev --local`, signs users in with the console email code and deletes everything afterwards.
+These checks are the author's evidence: layers 1 and 2 of the
+[layered handoff report](agent-workflow-acceptance.md#report-done-ness-in-layers). [Independent
+acceptance](agent-workflow-acceptance.md) comes after them and does not replace them, nor they it.
+
+## What smoke covers
+
+- **Every Procedure and HTTP Trigger the app declares:** valid input with the expected status and body (a status
+  below 500 is not success), invalid input, an anonymous call to a protected operation, the other role, and the
+  stored result read back. Use only the generated routes, inputs and permissions.
+- **Business rules at their edges:** the oversell, the stale `expectedVersion`, the second approval, a refusal that
+  must leave nothing behind (check the rows with the kit's `sql`), and two concurrent calls where a race matters.
+- **Each caller sees only its own rows:** a second member's records are absent from lists and refused by id.
+- **Visitor pages:** the checks in [public pages](public-pages.md#check-before-you-report-done), requested without
+  JavaScript.
+- **MCP:** `assertMcpDiscovery(endpoint, { tools, headers })` from `smoke-kit.mjs` for `/mcp` and `/mcp/admin`, with
+  the expected tools taken from generated code (the app-shell README shows it), plus a separate assertion that an
+  anonymous call and a member calling `/mcp/admin` are refused. Discovery needs no business `tools/call`.
+- **Admin:** `pnpm build`, then `pnpm test` (`generated/admin-mcp-app.check.mjs`) loads the Admin MCP App in an MCP
+  host and fails on a network error, console error or exception. It needs `playwright-core` and Chrome
+  (`npx playwright-core install chromium`, or `MANTLE_TEST_CHROMIUM=<executable>`). With no browser it fails: report
+  that check as BLOCKED on layer 2, not skipped and not as a product failure.
+
+Better Auth allows 3 one-time-code requests per minute per client IP; the kit gives each user its own
+`cf-connecting-ip`. Credentials come only from the kit's sign-in: a check never scrapes another session or builds a
+Caller by hand.
+
+## Seed data
+
+Create test records through the app itself: in `smoke.mjs` or the `pnpm accept` fixtures module, call the app's own
+REST, MCP or Admin operations as a signed-in user (`call("POST", "/admin/api/operations/create-event", { cookie: admin,
+body })`), or insert through the Store (`store(db, caller).collection("events").insert(...)`). Mantle then fills every
+system column (`id`, `version`, `created_at`, `updated_at`, `author_id`, and on a publishing Schema `status` and
+`published_at` through its publish Procedure) and enforces the Schema's checks, scope and references, exactly as for
+real data.
+
+Keep `seed.sql` for static reference data that no surface writes, such as categories or department budgets.
+`pnpm db:seed` and `smoke-kit.mjs` apply it as native SQL, which bypasses all of the above, so the seed sets each
+system column itself:
+
+| Column | SQLite and D1 (`cloudflare-d1`, `bun-sqlite`) | PostgreSQL | If the seed omits it |
+|---|---|---|---|
+| `id` | text, unique | text, unique | the insert fails |
+| `version` | `1` | `1` | `1` |
+| `created_at` | integer microseconds since the Unix epoch | `timestamptz` | the insert fails |
+| `updated_at` | integer microseconds; the same as `created_at` | `timestamptz` | SQLite and D1 store `0`: Admin shows 1970-01-01. PostgreSQL stores `now()` |
+| `author_id` | the creator's user id, or `NULL` for system rows | the same | `NULL`: under `restrict: { <schema>: "author_id = auth.uid()" }` no member sees the row |
+| `status` (publishing) | `'draft'`, `'published'` or `'archived'` | the same | `'draft'` |
+| `published_at` (publishing) | microseconds when `status` is `'published'`, otherwise `NULL` | `timestamptz`, otherwise `NULL` | `NULL` |
+
+A field- or owner-scoped Schema also needs its scope column. Use fixed instants for repeatable fixtures
+(`1767225600000000` is 2026-01-01T00:00:00Z), or the moment the seed runs (`unixepoch() * 1000000` on SQLite and
+D1, `now()` on PostgreSQL). For a publishing `posts` Schema on D1:
+
+```sql
+INSERT INTO posts (id, version, created_at, updated_at, author_id, status, published_at, title, body) VALUES
+  ('welcome', 1, 1767225600000000, 1767225600000000, NULL, 'published', 1767225600000000, 'Welcome', '# Welcome'),
+  ('draft-note', 1, unixepoch() * 1000000, unixepoch() * 1000000, NULL, 'draft', NULL, 'Draft', '# Draft');
+```
+
+The same rows on PostgreSQL:
+
+```sql
+INSERT INTO posts (id, version, created_at, updated_at, author_id, status, published_at, title, body) VALUES
+  ('welcome', 1, '2026-01-01T00:00:00Z', '2026-01-01T00:00:00Z', NULL, 'published', '2026-01-01T00:00:00Z', 'Welcome', '# Welcome'),
+  ('draft-note', 1, now(), now(), NULL, 'draft', NULL, 'Draft', '# Draft');
+```
+
+A seed is local test data; never apply it to an existing production database.
+
+## Account for every surface
+
+In the app's README or handoff, list each declared surface (Admin, each MCP endpoint, REST, each visitor page type)
+as verified (command, identity and result), intentionally not exposed, or UNVERIFIED with a reason. Local cookie
+sessions do not prove an external MCP host's OAuth connection or a production origin; those are layer 4. Record the
+commands and their results for the exact commit in the layered report, fix failures and rerun the affected checks. A
+check the environment prevented (no browser, no network, a refused approval) is BLOCKED with its reason, not failed.