zz-meridian 0.12.3 → 0.14.0

package/dist/adopt.js

@@ -74,9 +74,13 @@ function routes(root, dir) {
 const label = (route) => (route === '/' ? 'Home' : route.split('/').pop().replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase()));
 function appConfig(pages) {
     const template = readPayload('src/app.config.ts');
-    const items = pages.map((r) => `      { href: ${JSON.stringify(r)}, label: ${JSON.stringify(label(r))}, icon: LayoutGrid },`).join('\n');
+    const items = pages.map((r) => `      { href: ${JSON.stringify(r)}, label: ${JSON.stringify(label(r))}, icon: LayoutGrid, needs: 'public' },`).join('\n');
     return template
         .replace(/^import \{[\s\S]*?\} from 'lucide-react';/m, "import { LayoutGrid, type LucideIcon } from 'lucide-react';")
+        // The project's pages have no feature entry yet, so every item is `public` — the honest default — and step 4 of the
+        // Start guide points each at its own feature once it has one. The template's own `FEATURES` import would name a file
+        // this project's `src/data/` need not have, and a nav item without a `needs` is a type error since 0.13.0.
+        .replace(/^import \{ FEATURES \} from '\.\/data\/features\.ts';\n/m, '')
         .replace(/export const nav: NavGroup\[\] = \[[\s\S]*?\n\];/, `/** Written by zz-meridian adopt from the project's pages: give each its own icon and group them. */\nexport const nav: NavGroup[] = [\n  {\n    items: [\n${items}\n    ],\n  },\n];`);
 }
 function verifyConfig() {

package/dist/migrations.js

@@ -238,7 +238,35 @@ export const RELEASE_MIGRATIONS = [
         instructions: 'Read "A page spec" in references/customize.md. Under `## Agents` in the page\'s README.md, add `### What the agent reads`: what the page\'s shared context tells each agent, with a real line of it, and what the MCP App and the console\'s assistant each receive. `scripts/check.ts` requires it.',
         checks: ['gate'],
     },
+    {
+        id: 'nav-needs',
+        since: '0.13.0',
+        applies: navItemsWithoutNeeds,
+        summary: 'Every item in the project\'s `nav` carries a `needs`, so the rail shows only the destinations a person may reach.',
+        instructions: 'Read "Roles and access" in the Start guide (docs/start-a-dashboard.md). For each item in `src/app.config.ts`\'s `nav`, add `needs: \'public\'` when everyone may open that page, or point it at its feature (`needs: FEATURES.<id>.needs`); step 4 of that guide has the four steps, and `scripts/check.ts` fails the project\'s gate, naming the href, on an item without one. `adopt` writes `needs: \'public\'` for a project it sets up from now on.',
+        checks: ['gate'],
+    },
 ];
+/** The project's own nav, with any item still missing the `needs` that 0.13.0 requires of it. */
+function navItemsWithoutNeeds(root) {
+    const rel = 'src/app.config.ts';
+    const body = text(root, rel);
+    if (body === null)
+        return null;
+    const nav = /export const nav\b[^=]*=\s*\[([\s\S]*?)\n\];/.exec(body)?.[1];
+    if (nav === undefined)
+        return null;
+    // One item per line, as `adopt` writes them and as a hand-kept nav keeps them, so the item is the line naming its
+    // `href`: a group's opening line — every project groups its nav — names no `href` and carries no `needs` of its own,
+    // so counting it as an item would report a change no edit can settle. Anything the file does beyond that is the
+    // team's own shape, and none of it is read.
+    const items = nav.split('\n').filter((l) => /\bhref\s*:/.test(l));
+    // A project of 0.12.3's vintage also declares `NavItem` itself, without the property: an item that names a `needs` its
+    // own type does not have is the type error the gate prints next, so the change is not done until the type carries it.
+    const declaredType = /export type NavItem[^;]*\};/.test(body);
+    const typeHasNeeds = /export type NavItem[^;]*\bneeds\s*:/.test(body);
+    return items.some((l) => !/\bneeds\s*:/.test(l)) || (declaredType && !typeHasNeeds) ? [rel] : null;
+}
 /** The page specifications under the console and embed folders that lack the part the 0.9.0 check requires. */
 function pagesWithoutAgentReads(root) {
     const files = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.12.3",
+  "version": "0.14.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,7 +2,89 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
-## [Unreleased]
+## [0.14.0] · 2026-10-11
+
+### Added
+
+- **A form page has a width of its own, and the token layer documents the layout.** `tokens/core.tokens.json` gains `field-width` (64rem: the widest a form's card may be, in rem so the measure grows with the reader's text size) and `form-width` (a form page: its head column, the column gap, a `field-width` card and the page's gutter — written as `calc()` over the parts, so it holds at any root size). `PageFrame` gains `width="form"` and Settings is the page that uses it: the page fills the canvas until the canvas is wider than a form needs, then centres, so the remainder splits evenly instead of leaving the canvas's right side empty — visible on a window wider than about 1470px (with the card capped at 896px, the empty band beside it was about 430px at 1920px and about 1050px at 2560px, measured from the card's right edge to the page's content edge), invisible at 1440px and below. The card's own measure is unchanged (`FormSection`'s `64rem` is now `var(--field-width)`), and a field still never stretches across a wide screen. `LoadingPage` takes the same `width`, and Settings' `loading.tsx` passes it, so the skeleton stands where the page will be instead of moving it when the page arrives. `reading-width`'s description said it was for "forms, documents and settings", which nothing did; it now says what it is — one long document — and the Atlas has a seventh token view, **Layout**, drawing every width role to scale in one place. Additive apart from that description: a product that passes no `width` renders exactly as before.
+
+- **The token layer documents the groups it never showed, and the specs stop contradicting it.** Three of the eight core groups had no view in the Atlas at all, so a reader looking for how high a dialog sits or what the rail's glass does found nothing: `Elevation` now carries **Stacking** (the six `layer-*` tokens in order, drawn) and **Glass** (both blurs, over something moving), and the token layer's own prose is corrected — `motion`'s opening said "four durations" where the file has six plus three loops, `float-in` said it leaves over 120ms where the CSS uses `dur-exit` 140ms (the same claim stood in Popover, Menu, Select and Tooltip), and three cards said the system allows two loops where a Spinner's ring is a third. Nothing a product renders changes: every one of these is a description, a spec or an Atlas view.
+
+### Fixed
+
+- **`audit.ts --atlas` also measures the Atlas's other entries.** The token views, the page specs and the guides live under `[section]/[id]`, so `discover()` skips them as dynamic segments and `--atlas` read only the card registry: a defect in a token view or a guide failed no suite at all. It now reads the entries through the module the Atlas renders from, so a new one is measured without being listed. Measured: 0 issues across the seven entries checked (the token views, two page specs, a guide and the changelog) at five widths in both themes.
+- **The Members table fits its frame again, and the assistant walk-through passes every step.** `Joined` dropped a column too late (the table's own 672px, not 896): under it the table measured 759px in a 713px frame, so the audit failed `/members` at two widths in both themes — a table wider than its card is clipped, not scrolled — and with the assistant panel open the actions column sat outside the card, where a real click cannot reach it and the walk-through's row-menu step timed out. Found by `pnpm verify --full` (four audit issues) and by the walk-through, one cause behind both.
+- **`scripts/assistant.ts` says when a control has no box.** A control hidden by a container query answers `getBoundingClientRect()` with 0x0, so the harness clicked the page's top-left corner and reported a timeout somewhere else; it now fails with "the control is in the DOM but has no box at 0x0 — hidden at this width?", which is what another session needed twenty minutes to work out.
+- **An agent's approved change to a member no longer fails in a built app.** `src/data/member-mutations.ts` invalidated its tags with `updateTag`, which Next allows **only in a Server Action** — so the assistant's route handler and an adopter's MCP server, the two callers the module's own doc names, threw `updateTag can only be called from within a Server Action` the moment a change was applied: the Proposal was approved, the rows never moved, and the app answered with an error. The boundary now invalidates with `updateTag` where it is legal and `revalidateTag` where it is not, so a page action keeps its read-your-writes and an agent's write reaches the page. Found by the assistant walk-through, which timed out waiting for the rows to read Suspended — a suite that had not run since the member boundary landed (`585349a`, after the last full run).
+- **A busy button is drawn as working, at the size of its own icon.** It was drawn at the same 45% opacity as one nobody may press, so it read as unavailable while it was working — the spec said only a disabled button greys out, and the code did not agree. It keeps its colour and its shadow now, with the spinner as the answer. The spinner was also always 14px, so a `lg` or `md` button that carries an icon moved by 4px or 2px the moment it went busy — the one case `busy` exists to make steady (Replay on a failed request, for instance). The Button now composes `Spinner` instead of drawing a second ring of its own, and the Spinner's third step is 18px rather than 20px, so its three steps are the icon scale's (14, 16, 18) and one stands in for the other exactly. `Spinner` gains a decorative form (`label={null}`) for the case where the control announces itself — a busy button's accessible name is unchanged, which a check confirmed — and the spec says plainly that a button with no icon gains the slot and widens by it.
+
+- **Specimens and specs were sizing controls from the retired scale, and three page specs quoted the window's breakpoints for a table rule.** Five files still drew controls at 30/36/44 and 26/30/36 where the tokens are 32/38/46 and 28/32/38, and Members, Customers and API keys said their columns drop at 768/1024/1280 — the window's breakpoints — where `hideBelow` reads the table's own 672/896/1152; the four thresholds are now stated once, in the Table card. A suspended persona in the rail's specimen used the disabled ink without saying it was disabled, which the audit measured at 1.38:1 in dark and 2.31:1 in light; it is now a row with `aria-disabled` and the words "Not active", as the product draws one.
+
+### Changed
+
+- **With one workspace or none, the rail's row is the account menu, not a switcher.** A product that passes no `scopes` still opened a menu headed `Workspace` holding a single disabled, checked row — a chevron that promises a choice, opening a list with no choice in it (#20). The row now says `account menu` to a screen reader and carries a plain `ChevronDown` unless more than one scope is passed, and the menu renders no `Show` group and no checked row of its own unless there is something to switch between. A product passing several scopes is unchanged: the `Show` group, the radio items and the switcher glyph are as they were. The card's preview draws both states, and `README.md` states the rule.
+
+## [0.13.0] · 2026-10-11
+
+### Added
+
+- **A navigation check may carry its own budget.** An entry in `scripts/verify.config.ts`'s `navigationChecks` gains an optional `budget` — `{ shellMs: { phone: 300 } }` — which stands in for the shared `budgets.navigation` figure on that one metric and device for that one route; every figure it does not name, and every other route, keeps the shared one, and the shared figure itself is unchanged. The template uses it once: `/system/start/start-a-dashboard`, the longest reading page in the repository, whose phone shell measures 243-282 ms on the 4x-throttled profile against the shared 250. Beside it in the config is what that cost is not — this route's payload is smaller than the commit before the access work (152,388 bytes against 157,080), and `585349a` measures the same with byte-identical HTML — and the measurement lives in the initiative's review Backlog. Additive: a config with no `budget` behaves exactly as before.
+- **The consistency gate fails a nav item whose `needs` is not a need.** `node scripts/check.ts` reads `nav` from `src/app.config.ts` and fails, naming the href, when an item's `needs` is neither `'public'`, nor a grant (`object:read|create|update|remove`), nor `{ allOf: [...] }` of grants — including the empty and the nested `allOf`. It checks the shape of a need and never the role table, so it passes whatever grants a project declares, and it holds in a product as well as in the template because `src/app.config.ts` is every project's own file.
+- **`pnpm verify --as <persona>` signs the browser in as someone else, and is opt-in.** `scripts/verify.config.ts` declares five personas (`owner`, `admin`, `member`, `key-manager`, `viewer`) with the member id each stands for, its hand-written `expectedRoutes` and the protected string each of its denied routes must not leak. The run compares the rail with those routes, presses the role-dependent controls (`/keys`, `/members`, `/settings`) at 1440px, and opens every other rail route expecting NoAccess. An unknown persona exits non-zero naming the declared ones and `--as` cannot combine with `--perf`, both before anything is built. Without `--as`, `pnpm verify` is unchanged. `scripts/lib/chrome.ts`'s `Page.open` gains an optional `cookie` (set before the first request), `scripts/rail.ts` is new (it prints the rail's links as the browser drew them), and `scripts/audit.ts`, `scripts/interactions.ts` and `scripts/keyboard.ts` gain `--as`; `interactions.ts` also gains `--width`. All additive.
+- **The Members page shows a Roles & access matrix, generated from the tables.** `src/views/roles-matrix.tsx` is new: `matrixRows()` and `RolesMatrix()` build a card whose columns are `MAIN_ROLES` then `ADD_ONS` and whose rows are the non-public features (their `title`) then the actions (their `label`), each ticked where `whoCan(need)` says that role's own grants satisfy the whole need, with a legend saying that an add-on adds to a main role and that the member rules still apply. It renders on `/members` inside the page's own stack, so the page's gate is its gate, and the table scrolls inside its own frame at a phone's width. Nothing is listed by hand — editing `src/data/roles.ts` or `src/data/features.ts` edits the section.
+- **Every member write passes one boundary.** `src/data/member-mutations.ts` is new: `membersFor(scope)` binds the members collection so its `create`, `update` and `remove` all pass the boundary; `assignMemberRole({ id, role, addOns })` is the one assignment path; `memberAccess(id)` answers a row's capabilities, its role and add-on choices and its target-only reason; `invitableRoles()` is the invite choices. It re-resolves the caller from the request's own scope, enforces the Owner, self, give-Owner and last-active-Owner rules with the fixed messages, and runs every write in one promise queue per workspace.
+- **The gate is one idiom.** `src/data/access.ts` gains `gate(feature)` and `requireNeed(need)`: a dashboard page opens with the gate — a person who may not open it gets the NoAccess view as a normal 200, and a request with no session is sent to `/sign-in` — and a view tool calls `requireNeed` before it reads. Both ask `may`, and `may` answers from `effective(role, addOns)`, the one union rule, so the policy and the role table cannot drift.
+- **The empty state has a no-access kind.** `EmptyState` gains `kind="no-access"`: a lock mark on the neutral disc (`fill-track`, `ink-3`), `data-no-access` on its root, and no `role="alert"` (only `error` is an alert). `src/views/no-access.tsx` generates its copy from the role table — `noAccessCopy(need, title)` names the feature and the roles whose own grants satisfy the whole need, and says a main role plus an add-on is needed when no single role does.
+- **A member's role and add-ons are data, not a fixture list.** The role table moved into a new `src/data/roles.ts` (`MAIN_ROLES`, `ADD_ONS`, `GRANTS`, `effective(role, addOns)`, `whoCan(need)`), and `ROLES` left the member fixture and `src/data/sample.ts`. A member record now carries `role` (a main role, default `Member`) and `addOns` (default `[]`, duplicates removed), so the members collection refuses an unknown role or add-on and an update that does not name either leaves it as it was. Anything importing `ROLES` from `@/data/sample` takes `MAIN_ROLES` from `@/data/roles` instead.
+- **The demo signs in as whoever the View as cookie names.** `src/data/access.ts` reads the `zz_meridian_view_as` cookie on every request and answers grants from the member's own record: no cookie signs in as Maya Chen (`members_1`), the five frozen personas are `PERSONAS`, and an unknown or non-Active id gives no session — never the Owner. The scope keeps its three fields but its values change: `subjectId` is a member id and `authorizationKey` is `demo:<id>:<role>:<add-ons deduped and sorted>`, so code that hard-coded `subjectId: 'owner'` or `demo:1` must read the scope instead. `src/data/view-as.ts` (`'use server'`) adds `chooseViewAs(id)`, which sets the cookie for an Active persona and throws a readable message otherwise.
+- **The demo sign-in offers the personas.** Without `DEMO_PASSWORD`, the sign-in page lists the five personas above the product's sign-in panel — each with their name and role, a non-Active one disabled — and a click opens the console as that person through the View as cookie; with `DEMO_PASSWORD`, "Open the demo" gains an "Open as" select (default Maya Chen) beside the password and sets both the gate and the View as cookie. A persona outside the list, or one whose record is not Active, sets nothing, and the choice never bypasses the password.
+
+### Changed
+
+- **The Members page offers each row only what that person may do.** A row's menu is drawn from the boundary's answer for that row and that target: withheld controls are not rendered at all, a row that offers nothing says why, and a caller without the member grants sees no row menu, no Invite member control and one line saying who can (`Owners and Admins manage members.`). New: a `Change role` row action opening a sheet whose role select and add-on choices are exactly what that row allows, submitting through `assignRole`; the Activity line is written by the boundary, not the page. The phone card now carries the role with its add-ons (`Member + Key manager`) — and since Meridian's card shows three facts, Joined moved to the table only and the card keeps Last active.
+- **The assistant never exceeds the person it acts for.** `src/lib/collection.ts` gains `pageOnlyFields` (fields an agent reads and never writes) and `writableFields(c)`; the members collection declares `pageOnlyFields: ['role', 'addOns']`, so `create_members` and `update_members` leave them out of their schemas and refuse them if sent anyway. `app/api/assistant/route.ts` registers a `view_<name>` tool only where the person satisfies that view's need, hands `members` in through the boundary, and forces an agent's member create to `role: 'Member'` with no add-ons (FR-12). `src/lib/assistant/scoped.ts` is new: `scopedQuery(collection, scope, name)` re-checks the same tenant and subject and the read grant at the moment a query runs, so a tool listed before a demotion refuses after it. Nothing to do for an adopter unless they declare their own `pageOnlyFields`.
+- **The demo policy binds `members` through the boundary.** `src/data/access.ts`'s `bind(scope, 'members')` returns `membersFor(scope)`, and `app/(dashboard)/members/actions.ts` routes `inviteMember`, `setMemberStatus` and `removeMember` through it, exports `assignRole`, and no longer invalidates the tag itself. A person may no longer suspend or remove themselves, and a change that would leave the workspace with no active Owner is refused — including a status change through `update`, which is new.
+- **The three paths that skipped the permission read go through the data layer.** `src/data/collections.ts` gains `customers` (the twelve sample rows, read-only) and `workspace` (one record: the name, address and time zone the Settings form shows), `/customers` and the customers view tool reach them through `read()`, so `customers:read` is asked on the same path as every other collection, and Settings saves through a new server action (`saveWorkspace`) that asks `ACTIONS['save-workspace'].needs`. The Analytics heatmap, hours and regions come from `analyticsFigures()` in `src/data/analytics.ts`, which refuses a scope without `requests:read`. `CUSTOMERS` is no longer re-exported by `src/data/sample.ts` — take it from `@/system/fixtures/sample-records`, or read the `customers` collection; `SettingsBody` gains optional `workspace` and `save` props.
+- **A general action is shown only where the person may perform it.** `KeysView` takes `may: { create; revoke }` and `line`, and `RequestView` takes `mayReplay` and `replayLine`: each control is hidden — never drawn disabled, never left to fail on submit — when the person may not use it, and the page shows one line saying who can. `ACTIONS` in `src/data/features.ts` gains an optional `line`, and `src/views/no-access.tsx` exports `actionLine(id)`. Both view props are optional, so an existing direct caller of a view is unaffected.
+- **Settings shows each section by what a person may do.** `SettingsBody` takes a required `may: { workspaceRead; workspaceUpdate; workspaceRemove }`, computed on the server page from the grant table. The Workspace section appears only to someone who may read it — read-only, with the line "Only an Owner can change the workspace." and no save bar, when they may not change it — and the Danger zone only to someone who may remove the workspace; a Member or Viewer no longer sees the Workspace section at all. Notifications, Appearance, Assistant and Agents and MCP stay for everyone.
+- **A view tool carries its feature's need and asks it before it reads.** `ViewTool` gains a required `needs: Need`, so an adopter's own view tools must declare one (`needs: FEATURES.<id>.needs`) and call `await requireNeed(FEATURES.<id>.needs)` as the first statement of their `read`. Tool filtering by need is what keeps the assistant's `view_*` tools matching the person it acts for.
+- **Every dashboard page asks its feature before it reads.** Each page opens with its gate, `/keys` drops its hand-written check, and `/requests/[id]`'s `generateMetadata` answers the feature title `Request` for a person who may not open it without reading the record. A page that awaits its gate is an async page, so `/`, `/analytics`, `/customers` and `/requests` stream their masthead with the gate rather than in the static shell, and `OverviewPage`/`AnalyticsPage` accept a defaulted props object.
+- **`NoAccess` takes a feature, not a title, and is async.** `src/views/no-access.tsx` exports `NoAccess({ feature }: { feature: FeatureId })` — awaited — in place of `NoAccess({ title })`; a caller that passed `title` passes a `FeatureId` and awaits it.
+- **A nav item carries its feature's need, so the rail asks one table.** `src/data/features.ts` is new: `FEATURES` (what each page needs), `ACTIONS` (what each control needs), and the `FeatureId` and `ActionId` types. Every item in `src/app.config.ts`'s `nav` now writes `needs: FEATURES.<id>.needs` by reference, and `NavItem` gains a required `needs: Need` — so every adopter's nav item must add one: import `FEATURES` and point each item at its feature, or write a `Need` (`'keys:read'`, `{ allOf: [...] }`, `'public'`) directly. The rail and the palette then show only the destinations the current person may reach: a Viewer sees eight of the ten (`/keys` and `/members` are gone) and every other role sees all ten. This is presentation only — a destination kept out of the rail is still reachable by its address, and every page keeps its own check.
+- **The console's chrome takes the request as a promise.** `ConsoleRail` no longer takes `user`, and neither it nor `ConsolePalette` takes `only`; both take `access?: Promise<ChromeAccess | null>` — `chromeAccess()` from `src/data/access.ts` — which the layout passes without awaiting. Each piece of chrome waits for it in its own `<Suspense>` boundary, so the frame stays in the static shell and the person's own rail streams in the same response: nothing about the identity is drawn and then taken away. A product that passed `only` or `user` passes `access={chromeAccess()}` instead, or its own promise of the same shape — a console with no sign-in passes no `access` at all. `skills/zz-meridian/references/existing-project.md` shows the new call.
+
+### Fixed
+
+- **The demo policy binds the customers and the workspace.** `DEMO_COLLECTIONS` in `src/data/access.ts` gains `customers` and `workspace`, so the `customers:read` and `workspace:*` grants the role table freezes are reachable through `read()` — without them `/customers` refused everybody, the Owner included.
+- **`/keys` asks `keys:read` before it reads.** The keys page checks the caller's grant first: a Viewer gets a minimal NoAccess view (a normal 200 holding none of the keys' records) and a request with no session is redirected to `/sign-in`, both before any read. The new `src/views/no-access.tsx` holds that view.
+- **A key records the person who made it.** Creating an API key stored the sample's own person as the owner, so a key Lucas Meyer created said Maya Chen made it. The owner is now the caller the policy names.
+- **A closed browser check leaves no Chrome profile behind**: `scripts/lib/chrome.ts` removed a closed browser's profile from a timer that never ran when the script exited at once, so every `verify`, audit or shot left one in the temp folder. It now removes it as soon as the browser is closed — in the background, never on the caller's path. A suite closes its browser inside a hook, a hook has a ten-second ceiling, and a profile that has loaded many pages runs to tens of megabytes, so removing one synchronously timed a hook out on a runner (`Hook timed out in 10000ms`, `tests/deep-dom.test.ts`'s `afterAll`) after first failing with `ENOTEMPTY: directory not empty` when Chrome was still writing into it. That test now asserts the close does not do that work on the caller's path. A project brought in with `adopt` gets the fix with `update`.
+- **A card is one class**: Card's look moved from a dozen utilities to `.card` in `base.css`, and the Data table's wrapper uses it too, so every page carries less HTML (`/health` from 102,225 to 98,154 bytes, `/requests` from 148,614 to 141,568). A utility on a card still overrides it.
+- **Removing a member is undone, not confirmed.** Remove takes the person off the table at once with a toast offering Undo; the removal is sent when the toast closes (`UNDO_MS`, 8 s, now exported by the Toast) or at once if the page goes away first, and a refusal brings them back with its reason. Revoking an API key keeps its confirmation.
+- **A page reached by a click no longer replays its arrival** (#19). On a client navigation, or when the router shows a page it kept, the shell marks its main area `data-still`: arrivals end at once in their final state, and the mark lifts after `dur-grow` + `dur-enter`, so a later change on the page (a new period) still animates. The first load of a visit arrives as before.
+- **`navigate.ts` times real content** (#18): its `data` time no longer counts a skeleton's rows or the rows of a page the router keeps hidden, so a `loading.tsx` that holds a click for 300 ms or more now shows in `data`, where it read as the skeleton's 30 ms before.
+- **A rail link answers a click before its page arrives** (#18): its icon becomes a Spinner while a page that is not prefetched is on the way (`useLinkStatus`). `cache.md`, `customize.md` and `standard.md` now say what a request-time read costs a navigation (React holds a shown fallback 300 ms or more) and to read through `read()` wherever the data allows.
+- **The rail's marker measures after paint**, so opening the phone drawer costs one render and no forced layout; the current link draws the same pill until it has.
+- **A trend chart's readout stays inside its chart**: it measures its own width, wraps a long label and keeps an extreme value whole; on a phone it pins to the plot's leading edge. Money axis ticks from $10,000 read at a glance (`$25K`, `$5.0B`). `scripts/shot.ts --point "<chart>" --at 0.6` captures a readout.
+- **A sort or a page press is answered before the server is.** `useQueryState` returns a third value, `pending`, and shows the asked-for state at once (`useOptimistic` inside the navigation's transition); the DataTable takes `busy` (rows at 60% opacity, `aria-busy`) until the new rows land. A caller that destructures two values is unaffected.
+- **Dates and figures reuse their Intl formatters**: `formatDate` and the money and count formatters build their `Intl` formatter once instead of on every call (200 dates: 209 ms to 2.5 ms), which shortens the first tap on Alerts or the drawer on a phone.
+
+### Breaking
+
+Ten changes need a line from anyone updating a project. Each says what to do instead.
+
+- **A nav item carries a required `needs`.** Every item in `src/app.config.ts`'s `nav` writes one: import `FEATURES` and point the item at its feature (`needs: FEATURES.<id>.needs`), or write the `Need` yourself (`'keys:read'`, `{ allOf: [...] }`, `'public'`). `node scripts/check.ts` now fails a malformed one, naming the href.
+- **A view tool carries a required `needs`.** An adopter's own view tools declare `needs: FEATURES.<id>.needs` and call `await requireNeed(FEATURES.<id>.needs)` as the first statement of their `read`.
+- **A dashboard page that awaits its gate is an async page.** `/`, `/analytics`, `/customers` and `/requests` stream their masthead with the gate rather than in the static shell, and `OverviewPage`/`AnalyticsPage` accept a defaulted props object. A test that asserted the static shell on one of those routes, or code calling a page component synchronously, updates the assertion or the call.
+- **`NoAccess` takes a feature, not a title, and is awaited.** `NoAccess({ feature }: { feature: FeatureId })` replaces `NoAccess({ title })`: a caller that passed a title passes a `FeatureId` and awaits it.
+- **`SettingsBody` takes a required `may`.** `{ workspaceRead, workspaceUpdate, workspaceRemove }`, computed on the server page from the grant table. A direct caller that passed nothing computes and passes it. A Member or Viewer no longer sees the Workspace section at all.
+- **`ConsoleRail` and `ConsolePalette` take the request as a promise.** Both drop `user` and `only` for `access?: Promise<ChromeAccess | null>` — `chromeAccess()` from `src/data/access.ts` — which the layout passes without awaiting and each piece of chrome waits for in its own `<Suspense>` boundary. Pass `access={chromeAccess()}`, or your own promise of the same shape; a console with no sign-in passes none.
+- **The demo policy's scope values change.** `subjectId` is a member id, not `'owner'`, and `authorizationKey` is `demo:<id>:<role>:<add-ons deduped and sorted>`, not `demo:1`. Code that hard-coded either reads the scope instead.
+- **`ROLES` left `src/data/sample.ts`.** The role table is `src/data/roles.ts` (`MAIN_ROLES`, `ADD_ONS`, `GRANTS`, `whoCan`): an importer takes `MAIN_ROLES` from `@/data/roles`, and a member record now carries `role` and `addOns`.
+- **`CUSTOMERS` is no longer re-exported by `src/data/sample.ts`.** Take the twelve rows from `@/system/fixtures/sample-records`, or read the `customers` collection through `read()`.
+- **A person may no longer suspend or remove themselves, and the workspace always keeps one active Owner.** The member boundary refuses both — including a status change through `update`, which is new — with its frozen messages. A UI that offered either gets the refusal, and `memberAccess(id).reason` answers the row's own reason.
+
+**An update to 0.13.0 reports one migration.** `nav-needs`: every item in a project's `nav` needs a `needs`, which the rail asks before it draws a destination. `update` names the change and the file it is in, and `--finalize` runs the project's gate, which fails, naming the href, until the change is made — `needs: 'public'` for a page everyone may open, or the page's own feature (`needs: FEATURES.<id>.needs`), as step 4 of the Start guide has it. A project whose `NavItem` type predates this release has to carry the property too. `adopt` writes `needs: 'public'` into the projects it sets up from now on, so only a project that predates this release makes the change by hand.
 
 ## [0.12.3] · 2026-10-10
 
@@ -22,7 +104,7 @@ Every release of ZZ Meridian, newest first. Versions follow semver: a removed or
 - **The search pill folds by the top bar's own width** (under 40rem), so a canvas narrowed by the assistant folds it too. The top bar is now a container.
 - **A read-only form section keeps its values legible** in `ink-2` instead of `ink-disabled`.
 - **A phone's record card reads its facts as one sentence**: the DataTable card is a wrapping row instead of a six-column grid, so a separator dot never lands alone on a line and a fact is never cut to fit a third.
-- **Members shows the date its order follows**: Joined appears from 768px of table (Role now drops below 1024px and Team below 1152px), so the newest-first order is explained wherever the table has columns; on a phone the card reads "Joined 1 Oct".
+- **Members shows the date its order follows**: Joined appears from 768px of table (Role now drops below 1024px and Team below 1152px), so the newest-first order is explained wherever the table has columns; on a phone the card reads "Joined 01 Oct 2026", in the same form as its "Active 07 Jul 2026" and as API keys' "Created 05 Mar 2026": members joined across two years, so a day without its year would be misread.
 - **The Atlas home drops its numbered section labels** (01 to 05), a default Meridian's own register rules out.
 - **A figure is never cut.** In a Metric tile or a Featured metric a number longer than nine characters is set at a glance with `fitFigure` ("9.9B", "$1.2M") instead of being clipped by its card; `splitFigure` keeps a compact amount's decimal in the number ("$1.2M", not "$1" and ".2M").
 - **A day inside a sentence reads "1 Oct"**: `formatDay` in `src/lib/format-date.ts`; tables and axes keep `formatDate`'s "01 Oct".

package/payload/CONTRIBUTING.md

@@ -85,6 +85,7 @@ Write the status on the line under the title: `Status: beta`.
 | `pnpm tokens` | Generates the token CSS and the Tailwind bridge from `tokens/` (`--check` only compares) | After any token change |
 | `node scripts/contrast.ts [--all]` | Every specified foreground on its background, in every theme and accent, and the chart palette's colour-vision checks | Gate |
 | `node scripts/registry.ts` | Regenerates the Atlas registry from the card folders (`--check` only compares) | After adding or renaming a card |
+| `rm -rf .next` before the next build, after editing a card's `README.md` | A production build in a working `.next` can serve the prerendered copy of the old text while the client hydrates the new one, which React reports as error #418 on that Atlas page. `pnpm dev` has no such copy, and a fresh clone (CI, a deployment) has none either | After changing what a card's page says |
 | `node scripts/check.ts` | Every card has its README and preview, every README follows the anatomy, no literal colour in components, every token a spec names exists and is written with its own value, every embed view a document offers is a route, and an element that claims a control's role has a key handler | Gate |
 | `pnpm typecheck`, `pnpm test` | TypeScript and the behaviour tests | Gate |
 | `node scripts/audit.ts` | With the app running: every page and embed view at 2560, 1440, 1024, 768 and 390px in both themes (embeds at 720 and 420 on a simulated host ground). It measures inside open shadow roots too. Fails on sideways scroll, text clipped without an ellipsis, a control with no accessible name, more than one page scroller, rendered text under its WCAG minimum, a Tab stop with no focus ring (a change of outline, shadow or border when focus arrives), a custom element it cannot look inside (`unmeasured:`), and any uncaught exception or console error. Prints the design metrics: type sizes, weights, radii and the hierarchy ratio | Before release |

package/payload/README.md

@@ -16,7 +16,7 @@ These govern every layer. When two choices both fit the specs, pick the one that
 
 **Numbers are exact and honest.** A missing value reads as a dash, never as zero. Every figure says its period and its unit; every chart has a table behind it; a stale feed says it is stale. Large figures are set tight, with the unit and the fraction stepped down so the number reads first.
 
-**Calm, then precise.** The ground is quiet and lit; motion explains a change and stops. Data arrives once, in reading order; nothing loops but a live dot and a skeleton; reduced motion shows the final state.
+**Calm, then precise.** The ground is quiet and lit; motion explains a change and stops. Data arrives once, in reading order; nothing loops but a spinner, a skeleton and a live dot; reduced motion shows the final state.
 
 **Every surface, every operator.** A view holds on the console, on a phone and as an MCP App in a host. It is addressable, legible to a model, and safe to share with an agent: the agent reads anything, changes nothing without a person, and leaves its name on what it did.
 

package/payload/app/(dashboard)/(overview)/page.tsx

@@ -5,6 +5,7 @@ import { Freshness } from '@/components/patterns/freshness';
 import { PeriodSelect } from '@/components/patterns/period-select';
 import { Skeleton } from '@/components/ui/skeleton';
 import { OverviewBody } from '@/views/overview';
+import { gate } from '@/data/access';
 import { DEMO_NOW, DEMO_UPDATED_AT } from '@/data/sample';
 import { overviewTool } from '@/views/tools';
 import { cache } from 'react';
@@ -20,8 +21,10 @@ type SearchParams = Promise<{ period?: string; day?: string }>;
 /** The page's one read, through the Overview tool (`src/views/tools.ts`), shared by the export and the body. */
 const readPeriod = cache((period: ReturnType<typeof parsePeriod>, day?: string) => overviewTool.read({ period, day: /^\d{4}-\d{2}-\d{2}$/.test(day ?? '') ? day : undefined }));
 
-/** The masthead renders at once; the period select, the export and the body read the address inside their own boundaries. */
-export default function OverviewPage({ searchParams }: { searchParams: SearchParams }) {
+/** The page asks its feature before it renders — the rail hiding `/` is presentation, not this gate — then the masthead renders and the period select, the export and the body read the address inside their own boundaries. Next always passes the address; the default keeps the component callable with none, which a check that renders it bare relies on. */
+export default async function OverviewPage({ searchParams }: { searchParams: SearchParams } = { searchParams: Promise.resolve({}) }) {
+  const denied = await gate('overview');
+  if (denied) return denied;
   return (
     <PageFrame
       kicker={<>{app.name} · {app.workspace}</>}

package/payload/app/(dashboard)/_loading.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import { PageFrame, Row, Stack } from '@/components/base/shell';
+import { PageFrame, Row, Stack, type PageWidth } from '@/components/base/shell';
 import { Card } from '@/components/ui/card';
 import { Skeleton } from '@/components/ui/skeleton';
 
@@ -7,11 +7,12 @@ import { Skeleton } from '@/components/ui/skeleton';
  * The frame every console route's loading state shares: one masthead skeleton, then the page's own body, announced once
  * as busy under the page's name. Each route's `loading.tsx` composes its body from these rows, in the shape of its page.
  * The title is the page's own heading, so the shell is acknowledged the moment this state commits; a detail page whose
- * title depends on the record leaves it out and keeps a skeleton.
+ * title depends on the record leaves it out and keeps a skeleton. `width` follows the page it stands in for: a
+ * skeleton at another width would move the content when the page arrives.
  */
-export function LoadingPage({ name, title, children }: { name: string; title?: string; children: ReactNode }) {
+export function LoadingPage({ name, title, width, children }: { name: string; title?: string; width?: PageWidth; children: ReactNode }) {
   return (
-    <PageFrame kicker={<Skeleton className="h-2.5 w-32" />} title={title ?? <Skeleton className="mt-3 h-10 w-64 rounded-md" />} description={<Skeleton className="mt-2 h-3.5 w-96 max-w-full" />}>
+    <PageFrame width={width} kicker={<Skeleton className="h-2.5 w-32" />} title={title ?? <Skeleton className="mt-3 h-10 w-64 rounded-md" />} description={<Skeleton className="mt-2 h-3.5 w-96 max-w-full" />}>
       <Busy name={name}>{children}</Busy>
     </PageFrame>
   );

package/payload/app/(dashboard)/analytics/page.tsx

@@ -6,6 +6,7 @@ import { Freshness } from '@/components/patterns/freshness';
 import { PeriodSelect } from '@/components/patterns/period-select';
 import { Skeleton } from '@/components/ui/skeleton';
 import { AnalyticsBody } from '@/views/analytics';
+import { gate } from '@/data/access';
 import { DEMO_NOW, DEMO_UPDATED_AT } from '@/data/sample';
 import { analyticsTool } from '@/views/tools';
 import { cache } from 'react';
@@ -17,8 +18,10 @@ export const metadata = { title: 'Analytics' };
 
 type SearchParams = Promise<{ period?: string }>;
 
-/** The masthead renders at once; the period select, the export and the body read the address inside their own boundaries. */
-export default function AnalyticsPage({ searchParams }: { searchParams: SearchParams }) {
+/** The page asks its feature before it renders — the rail hiding `/analytics` is presentation, not this gate — then the masthead renders and the period select, the export and the body read the address inside their own boundaries. Next always passes the address; the default keeps the component callable with none, which a check that renders it bare relies on. */
+export default async function AnalyticsPage({ searchParams }: { searchParams: SearchParams } = { searchParams: Promise.resolve({}) }) {
+  const denied = await gate('analytics');
+  if (denied) return denied;
   return (
     <PageFrame
       kicker={<>{app.name} · {app.workspace}</>}

package/payload/app/(dashboard)/customers/README.md

@@ -10,7 +10,7 @@ Status: beta
 |---|---|---|---|
 | Masthead | PageFrame: kicker, "Customers", one sentence, Invite customer (primary) | One band | Stacked |
 | 1 | Row `tiles`: Customers (with combined requests over 14 days), Spend, last 30 days (emphasis, with its 14-day shape), Past due | Three across | One column |
-| 2 | Data table: search and Status in the Filter bar, the plan as a Segmented view; columns Customer (avatar and name, grow), Plan, Status, Requests, Last 14 days (sparkline, from 1024px), Error rate (from 1280px), Spend, Customer since (from 1280px) | Columns | Cards: name and status, then plan, requests and spend |
+| 2 | Data table: search and Status in the Filter bar, the plan as a Segmented view; columns Customer (avatar and name, grow), Plan, Status, Requests, Last 14 days (sparkline, from 896px), Error rate (from 1152px), Spend, Customer since (from 1152px) | Columns | Cards: name and status, then plan, requests and spend |
 
 ## States
 

package/payload/app/(dashboard)/customers/page.tsx

@@ -1,14 +1,22 @@
 import { Suspense } from 'react';
 import { app } from '@/app.config';
 import { PageFrame } from '@/components/base/shell';
-import { CUSTOMERS } from '@/data/sample';
+import { gate } from '@/data/access';
+import { read } from '@/data/read';
+import type { CustomerRecord } from '@/data/sample';
 import { CustomersView, InviteCustomer } from '@/views/customers';
 import { Busy, TableSkeleton, TilesSkeleton } from '../_loading';
 
 export const metadata = { title: 'Customers' };
 
-/** The masthead sits outside the boundary that reads the address (the table's filters), so a cold load has its title in the first HTML. */
-export default function CustomersPage() {
+/**
+ * The page asks its feature before it renders; the rail hiding `/customers` is presentation, never this gate. The
+ * masthead then sits outside the boundary that reads the address (the table's filters), and the boundary is where the
+ * page reads its records.
+ */
+export default async function CustomersPage() {
+  const denied = await gate('customers');
+  if (denied) return denied;
   return (
     <PageFrame
       kicker={<>{app.name} · {app.workspace}</>}
@@ -24,8 +32,18 @@ export default function CustomersPage() {
           </Busy>
         }
       >
-        <CustomersView rows={CUSTOMERS} />
+        <Customers />
       </Suspense>
     </PageFrame>
   );
 }
+
+/**
+ * The page's one read of the customers, through `read()`: `customers:read` is asked on the same path as every other
+ * collection, so a policy that does not bind the collection (or a person who does not hold the grant) refuses here before
+ * a row is drawn, exactly as it does for the members, the keys and the request log.
+ */
+async function Customers() {
+  const { rows } = await read('customers');
+  return <CustomersView rows={rows as CustomerRecord[]} />;
+}

package/payload/app/(dashboard)/health/page.tsx

@@ -1,4 +1,5 @@
 import { app } from '@/app.config';
+import { gate } from '@/data/access';
 import { PageFrame } from '@/components/base/shell';
 import { Freshness } from '@/components/patterns/freshness';
 import { PackedHealthBody, SubscribeButton } from '@/views/health';
@@ -7,8 +8,10 @@ import { packServices } from '@/components/patterns/status-list/summarise';
 
 export const metadata = { title: 'Health' };
 
-/** Rendered from the Health tool's own read (`src/views/tools.ts`): the services and incidents the caller may read. */
+/** Rendered from the Health tool's own read (`src/views/tools.ts`), once the page's feature is held: the rail's hiding is presentation, not this gate. */
 export default async function HealthPage() {
+  const denied = await gate('health');
+  if (denied) return denied;
   const { data } = await healthTool.read({});
   return (
     <PageFrame

package/payload/app/(dashboard)/keys/README.md

@@ -10,7 +10,7 @@ Status: beta
 |---|---|---|---|
 | Masthead | PageFrame: kicker, "API keys", one sentence, Create key (primary) | One band | Stacked |
 | 1 | Banner (accent), only right after a key is created: "Copy {name} now", the full key in a Copy field, dismissable | Full width | Full width |
-| 2 | Data table: Name with its environment, Key (its hint, `zzm_live_…f601`, in mono, from 768px), Scopes (two and "+N", from 1280px), Created by (from 1024px), Created, Last used, and Revoke | Columns | Cards: name and environment, "Created …" and "Used …", Revoke |
+| 2 | Data table: Name with its environment, Key (its hint, `zzm_live_…f601`, in mono, from 672px), Scopes (two and "+N", from 1152px), Created by (from 896px), Created, Last used, and Revoke | Columns | Cards: name and environment, "Created …" and "Used …", Revoke |
 | Sheet | Create a key: Name (required), Environment (Live or Test), Scopes (checkboxes); Cancel and Create key | From the right, 440px | From the bottom |
 | Dialog | Revoke: "Revoke {name}?", what fails and that it cannot be undone, when it was last used; Cancel and Revoke key (danger) | Centred | Bottom sheet |
 

package/payload/app/(dashboard)/keys/actions.ts

@@ -3,9 +3,8 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { updateTag } from 'next/cache';
 import { z } from 'zod';
-import { app } from '@/app.config';
 import { clock } from '@/data/collections';
-import { AccessDenied, can, collectionFor, resolveAccess } from '@/data/access';
+import { AccessDenied, can, collectionFor, nameOf, resolveAccess } from '@/data/access';
 import { collectionTag } from '@/data/read';
 import { SCOPES } from '@/views/key-scopes';
 import type { ApiKey } from '@/data/sample';
@@ -19,6 +18,8 @@ const draft = z.object({
 /**
  * Creates a key and returns it with its full secret: the only moment the secret exists outside the caller's own copy.
  * What is stored is the key's hint (its prefix and last four characters) and the secret's SHA-256, never the secret.
+ * The key's owner is the caller — the person the policy names — so a key Lucas makes records Lucas, never the sample's
+ * own person; `subjectId` is the honest fallback when the policy names nobody.
  */
 export async function createKey(input: z.input<typeof draft>): Promise<ApiKey & { secret: string }> {
   const { name, env, scopes } = draft.parse(input);
@@ -27,7 +28,8 @@ export async function createKey(input: z.input<typeof draft>): Promise<ApiKey &
   const secret = `zzm_${env}_${randomBytes(16).toString('hex')}`;
   const hint = `zzm_${env}_…${secret.slice(-4)}`;
   const secretHash = createHash('sha256').update(secret).digest('hex');
-  const key = await collectionFor(scope, 'keys').create!({ name, env, scopes, owner: app.user.name, created: clock().toISOString(), lastUsed: null, hint, secretHash });
+  const owner = (await nameOf(scope)) ?? scope.subjectId;
+  const key = await collectionFor(scope, 'keys').create!({ name, env, scopes, owner, created: clock().toISOString(), lastUsed: null, hint, secretHash });
   updateTag(collectionTag(scope.tenantId, 'keys'));
   return { ...(key as ApiKey), secret };
 }

package/payload/app/(dashboard)/keys/page.tsx

@@ -1,11 +1,36 @@
+import { gate, may } from '@/data/access';
+import { ACTIONS } from '@/data/features';
 import { read } from '@/data/read';
 import { KeysView } from '@/views/keys';
+import { actionLine } from '@/views/no-access';
 import type { ApiKey } from '@/data/sample';
 import { createKey, revokeKey } from './actions';
 
 export const metadata = { title: 'API keys' };
 
+/**
+ * The keys page asks its feature first, before it reads anything: a person who may not see the keys gets the NoAccess
+ * view and no record of theirs, and a request with no session is sent to sign-in. The rail hides `/keys` from that
+ * person too, but hiding is presentation only — this check is the gate, and it runs before the read either way.
+ *
+ * After the gate it asks the action table what this person may do here, so the view draws Create key and Revoke only
+ * where they may be used. A Member opens this page (they may read keys) but may not create or revoke one, and the line
+ * says who can. The authority is a snapshot: a control shown here is still refused by the server action if it changed.
+ */
 export default async function KeysPage() {
+  const denied = await gate('keys');
+  if (denied) return denied;
   const { rows, observedAt } = await read('keys');
-  return <KeysView rows={rows as ApiKey[]} now={observedAt} createKey={createKey} revokeKey={revokeKey} />;
+  const mayCreate = await may(ACTIONS['create-key'].needs);
+  const mayRevoke = await may(ACTIONS['revoke-key'].needs);
+  return (
+    <KeysView
+      rows={rows as ApiKey[]}
+      now={observedAt}
+      may={{ create: mayCreate, revoke: mayRevoke }}
+      line={mayCreate ? undefined : actionLine('create-key')}
+      createKey={createKey}
+      revokeKey={revokeKey}
+    />
+  );
 }

package/payload/app/(dashboard)/layout.tsx

@@ -4,7 +4,7 @@ import { ConsolePalette, ConsoleRail } from '@/views/console-chrome';
 import { ShellTools } from '@/components/patterns/shell-tools';
 import { assistantConfig } from '@/lib/assistant/config';
 import { DEMO_NOW, ALERTS } from '@/data/sample';
-import { resolveAccess } from '@/data/access';
+import { chromeAccess, resolveAccess } from '@/data/access';
 import { ConsoleLive } from '@/views/console-live';
 
 /** Every console page: the rail on the frame, the page on the canvas. Put your sign-in gate here. */
@@ -15,10 +15,14 @@ export default function DashboardLayout({ children }: { children: React.ReactNod
   const assistant = connection().then(() => assistantConfig(process.env) !== null);
   // The scope key reaches the live provider the same way, as a promise it resolves behind its own boundary.
   const scope = resolveAccess().then((s) => `${s.tenantId}/${s.subjectId}`);
+  // The rail's destinations, the signed-in person and the View as group, one promise for both pieces of chrome: not
+  // awaited, so the frame is still the first thing streamed. An identity nobody can resolve settles on null, which the
+  // chrome draws as the placeholder person and no destination — never the sample person.
+  const access = chromeAccess().catch(() => null);
   return (
-    <AppShell rail={<ConsoleRail />} tools={<ShellTools alerts={ALERTS} now={DEMO_NOW} />} assistant={assistant}>
+    <AppShell rail={<ConsoleRail access={access} />} tools={<ShellTools alerts={ALERTS} now={DEMO_NOW} />} assistant={assistant}>
       <ConsoleLive scope={scope}>{children}</ConsoleLive>
-      <ConsolePalette />
+      <ConsolePalette access={access} />
     </AppShell>
   );
 }

package/payload/app/(dashboard)/members/README.md

@@ -1,6 +1,6 @@
 # Members page
 
-Who is in the workspace, what role and team they hold, and when they last used it: invite someone, suspend or reactivate them, or remove them.
+Who is in the workspace, what role and team they hold, and when they last used it: invite someone, change their role and add-ons, suspend or reactivate them, or remove them.
 
 Status: beta
 
@@ -8,12 +8,14 @@ Status: beta
 
 | Row | Pattern | Console | Mobile |
 |---|---|---|---|
-| Masthead | PageFrame: kicker, "Members", one sentence, Invite member (primary) | One band | Stacked |
-| 1 | Data table: Name (avatar and name, grow), Email (from 1024px), Role (from 1024px), Team (from 1440px), Status, Joined (from 768px, so the order the table opens in is on screen wherever it has columns), Last active, and a row action menu | Columns | Cards: name and the menu, then status, when they joined (the order the list follows) and last active; a card holds three facts, so team is left to the record |
+| Masthead | PageFrame: kicker, "Members", one sentence, Invite member (primary), shown only to a person who may invite (`invitableRoles()` is not empty) | One band | Stacked |
+| 1 | Data table: Name (avatar and name, grow), Email (from 896px), Role as a person reads it, add-ons and all (as a column from 512px, and on the card at every width below), Team (from 1152px), Status, Joined (from 896px), Last active, and a row action menu | Columns | Cards: name and the menu, then the role with its add-ons, status and last active |
+| 2 | Roles & access matrix: a card whose table ticks each role, main roles first and add-ons after, against every non-public feature and then every action; a legend under it says that an add-on adds to a main role and that the member rules still apply. Generated from `GRANTS`, `FEATURES` and `ACTIONS`, never written by hand; at a phone's width the table scrolls inside its own frame | Columns, scrolling inside the card | The same table, scrolling inside the card |
 | Sheet | Invite a member: Name and Email (required), Role, Team; Cancel and Send invitation | From the right, 440px | From the bottom |
-| Dialog | Remove: "Remove {name}?", the consequence, and the suspend alternative; Cancel and Remove member (danger) | Centred | Bottom sheet |
+| Sheet | Change {name}'s role: Role and Add-ons, offering only the choices the row's boundary allowed; a refusal reopens it with the reason in a critical Banner; Cancel and Save role | From the right, 440px | From the bottom |
+| Toast | Remove: the person leaves the table at once and a toast says "{name} removed · They lose access when this closes" with Undo. The removal is sent when the toast closes (8 s, `UNDO_MS`), or at once if the page goes away first; Undo brings them back and sends nothing; a refusal brings them back with its reason | Bottom right | Top, full width |
 
-The row menu holds Suspend (Reactivate on a suspended member) and Remove.
+A row the caller may not change draws no menu at all: its own reason where the restriction is the target's — the first rule in the boundary's frozen order that hides the action, such as "Only an Owner can change or remove an Owner." on an Owner's row read by an Admin — and nothing where the caller simply lacks the grant, which the page's one line above the table already says ("Owners and Admins manage members."). The row menu holds Change role, Suspend (Reactivate on a suspended member) and Remove, each shown only where the boundary allowed it; an invited row offers none until the server gives it a capability.
 
 ## States
 
@@ -21,16 +23,19 @@ The row menu holds Suspend (Reactivate on a suspended member) and Remove.
 |---|---|
 | Loading | `loading.tsx`: skeleton table rows; the members are read per request, so the prerendered shell holds none |
 | Default | Newest members first, as the Joined column beside them shows |
-| Invited | The status Badge in `accent`; Last active reads "Never" in `ink-3` |
+| Invited | The status Badge in `accent`; Last active reads "Never" in `ink-3`; no row actions |
 | Suspended | The status Badge in `warning` |
 | Name or email missing | The field's error under it; nothing is sent |
-| Changed | The page refreshes from the collection and a toast confirms: "Member suspended", "Member reactivated", "Member removed", "Invitation sent to {email}" |
-| Rejected | The table goes back to what it was. A refused invitation reopens the sheet with what was typed and a critical Banner, "Invitation not sent", with the reason; a refused status change or removal shows a critical toast with the reason |
+| Changed | The page refreshes from the collection and a toast confirms: "Role changed", "Member suspended", "Member reactivated", "Invitation sent to {email}"; a removal's toast is its Undo, "{name} removed" |
+| Rejected | The table goes back to what it was. A refused invitation reopens the sheet with what was typed and a critical Banner, "Invitation not sent", with the reason; a refused role change reopens the Change role sheet with the draft it was sent from and a critical Banner, "Role not changed", with the reason; a refused status change or removal shows a critical toast with the reason |
 | No members | The first-run empty state with Invite member |
+| May not invite | No Invite member in the masthead and none in the empty state, because the boundary offers no invitable role |
 
 ## Data
 
-The `members` collection in `src/data/collections.ts`, read with `members.query({})` at request time. Server actions in `actions.ts` call `members.create` (status `Invited`, joined today by the data's clock, never active), `members.update` (status) and `members.remove`; the view refreshes the page after each and keeps no copy of the rows. Last active is relative to the data's clock.
+The `members` collection in `src/data/collections.ts`, read with `members.query({})` at request time. Server actions in `actions.ts` call `members.create` (status `Invited`, joined today by the data's clock, never active), `members.update` (status), `members.remove` and `assignRole`; the view refreshes the page after each and keeps no copy of the rows. Last active is relative to the data's clock.
+
+Every one of those writes passes `src/data/member-mutations.ts`, which re-resolves the caller, checks the operation's grant and refuses a change or removal of an Owner without `workspace:update`, one's own role or add-ons, suspending or removing oneself, and any change that would leave no active Owner. The page reads that boundary per row, once, and is handed only what it allows: `memberAccess(id)` gives the row's booleans, its role choices, its add-on choices and its reason, and `invitableRoles()` gives the roles an invitation may carry. The page decides nothing from a role of its own. A role or add-on change is one `assignRole` write, with its Activity line in the same step; the matrix in row 2 asks `whoCan` over the same `GRANTS` the boundary uses.
 
 ## Embed view
 
@@ -38,7 +43,7 @@ Not offered. Inviting and removing people are decisions for the console, not a c
 
 ## Surfaces
 
-- **Console**: as above. **Mobile**: cards, the sheet and the dialog rise from the bottom. **Embed**: not offered.
+- **Console**: as above. **Mobile**: cards, the sheets rise from the bottom. **Embed**: not offered.
 
 ## Agents
 
@@ -46,7 +51,7 @@ The assistant reads and proposes changes here through Proposals: it adds, change
 
 ### What the agent reads
 
-Counts by status, role (with what each role may do) and team, everyone with their role, team, status and when they were last seen (25 at most; `query_members` finds the rest), and what code found: active members unseen for 60 days or more, unanswered invitations, and who can change the workspace. It says that "last active" is a console sign-in, not use of the API.
+Counts by status, role (with what each role may do) and team, everyone with their role, add-ons, team, status and when they were last seen (25 at most; `query_members` finds the rest), and what code found: active members unseen for 60 days or more, unanswered invitations, and who can change the workspace. It says that "last active" is a console sign-in, not use of the API.
 
 ```text
 - 3 active members have not been seen for 60 days or more: Alice Moreno (Viewer, Support, 94 days), Felix Andersson (Viewer, Engineering, 75 days), Ravi Patel (Viewer, Support, 71 days).
@@ -57,5 +62,7 @@ Counts by status, role (with what each role may do) and team, everyone with thei
 
 ## Content
 
-- One verb through each flow: "Remove member", "Remove {name}?", "Member removed".
+- One verb through each flow: "Remove", then "{name} removed" with Undo. A removal is undone, not confirmed: it is the change a person makes on purpose and regrets by accident. Revoking an API key stays a confirmation, because requests using the key fail the moment it is sent.
 - Statuses are words ("Invited", "Suspended"), never colour alone.
+- A role reads the way a person holds it: "Member + Key manager", never "Member" with the add-on left to be inferred.
+- The matrix names roles, not grants: the grant table stays in `src/data/roles.ts`, and a reader who wants it reads the page's own section instead of a list of permissions here.