@lepsto/sdk-app 84.0.0

package/docs/rules.md

@@ -0,0 +1,522 @@
+# App Rules
+
+Normative rules for building a Lessly App on `@lessly/sdk-app`. Read this
+before writing code; see `README.md` for the map of the rest of the guide.
+
+Severity (RFC 2119): **MUST** blocks merge, **SHOULD** is a strong
+recommendation, **MAY** is an allowed option.
+
+Rule IDs (`APP-NNN`) are immutable once merged: a rule's ID and meaning never
+change, even if its wording is later clarified. Some of these rules cover
+ground shared with extensions and the platform's Module Federation host; where
+that's true, this file references the existing `FED-*` rule ID from the
+toolkit-guide instead of restating it — go there for the full rule text,
+rationale, and examples.
+
+---
+
+### APP-001 (MUST) — All platform data access goes through `@lessly/sdk-app`
+
+Every read or write to a Lessly platform API MUST go through a
+`@lessly/sdk-app` client created with `createLesslyApp`, or through the
+generated `*QueryOptions`/`*MutationOptions` factories built on top of it. An
+App MUST NOT `fetch` a platform host directly, and MUST NOT use any other HTTP
+client to reach platform data.
+
+**Streaming.** The same rule covers WebSockets. Platform streaming MUST go
+through the generated `*Connect` factories (`<toolId>Connect(sdk, params)`,
+imported from the tool's namespace subpath), which are emitted for every
+catalog tool that carries a `ws` binding and are backed by the SDK's
+`connectStream` runtime. An App MUST NOT construct `new WebSocket(...)` against
+a platform host, exactly as it must not `fetch` one — and MUST NOT hand-build a
+`ws(s)://` URL from `baseUrl`. A tool with no `ws` binding has no sanctioned
+stream: there is nothing to open, and reaching for a raw socket is a violation,
+not a workaround.
+
+`new WebSocket(...)` against an App's OWN non-platform host (a third-party
+service the App integrates) is outside this rule.
+
+### APP-002 (MUST) — Frontend-only
+
+An App MUST NOT ship a backend service, a database, or an MCP endpoint. All
+of its logic runs in the browser, built on `@lessly/sdk-app` and the Module
+Federation contract below. If a feature needs server-side state or a
+service-to-service call, it belongs in an extension, not an App.
+
+### APP-003 (MUST) — Manifest is `lessly.app.yaml`, schema v1
+
+The manifest file is `lessly.app.yaml`, and its top-level surface is exactly:
+`app_schema_version: 1`, `id`, `title`, `version`, `nav`. No other top-level
+field is valid — in particular, no extension/backend manifest field (`s2s`,
+`webhooks`, `billing`, `analytics`, `routing`, `public`, ...) belongs in an App
+manifest.
+
+`nav` has exactly two keys: `nav.icon` (**required**, the rail icon) and
+`nav.sections` (**optional**, the App's own rail menu — APP-011). Any other key
+under `nav` is rejected, and rejection is fatal: registration validation is
+whitelist-strict, so an unknown key fails the whole registration rather than
+being stripped.
+
+### APP-004 (MUST) — Module Federation contract
+
+An App exposes `./App` as its Module Federation remote entry, implementing
+the shell's remote contract (FED-001). The Module Federation `name` MUST equal
+the manifest `id` (FED-004). React, React DOM, React Router, and `@lessly/ui`
+MUST be declared as shared singletons, never bundled (FED-005), using
+`@module-federation/vite` pinned at exactly `1.16.12` (FED-006). The asset
+base in federation mode is the absolute path `/~/<id>/`. The build MUST
+produce one merged dual-mode `dist/` covering both standalone and federation
+artifacts (FED-007).
+
+`./App` is the **only** module an App exposes. There is no `./navigation`
+contract: the shell no longer loads such a module, there is no
+`subscribeNavItems` and no `navContractVersion` negotiation, and the menu the
+shell renders comes from **your own** `lessly.app.yaml` — the `nav.sections`
+block (APP-011) — not from your App code, and not from a toolkit manifest.
+FED-011 is **RETIRED (2026-08)**. Still mapping the expose is inert rather than
+an error — it just ships a chunk nobody fetches — but a new App MUST NOT add
+it, and an existing one SHOULD delete `src/federation/navigation.ts`, drop the expose, and move
+whatever that module fed the menu (environment lists, tool groups, badges,
+status dots, a settings gear) into its own pages under `./App`'s relative
+routes (FED-003).
+
+This rule states the contract; it does not restate FED-001, FED-004, FED-005,
+FED-006, or FED-007 — see those rules for exact wording, rationale, and
+examples.
+
+### APP-005 (MUST) — Auth is ambient; an App does not own it
+
+Authentication is ambient: the hosting shell owns cookies in production and a
+bearer proxy in local dev. An App MUST NOT implement login, token handling,
+refresh, or product switching — those belong to the shell. An App MUST read
+the active product from its props or the `X-Product-Id` header, never by
+decoding a token.
+
+An App MUST NOT rely on the `user` prop for anything beyond display. In
+dev-standalone mode, `user` is a stub (`{ id }` sourced from the local dev
+JWT, `displayName: 'Dev User'`) — it is not a real session. The real,
+shell-authenticated user only arrives once the app is composed via
+federation, through the `./App` props.
+
+### APP-006 (SHOULD) — Use the generated query/mutation option factories
+
+Prefer the generated `*QueryOptions`/`*MutationOptions` factories
+(`@lessly/sdk-app/<namespace>`) over hand-rolling request paths against the
+SDK client directly. They keep query keys, request shapes, and cache
+invalidation consistent with the published API surface, and stay in sync with
+it automatically on upgrade.
+
+### APP-007 (MUST) — Versioning hygiene
+
+Bump the manifest `version` on every release. Keep the SDK and this guide
+current with:
+
+```sh
+npm i @lessly/sdk-app@latest
+```
+
+Use this exact `@latest` form — not `npm update`. `@lessly/sdk-app` is
+pre-1.0 and pinned with a caret range, so `npm update` never crosses a minor
+version; since this SDK also bumps its minor version whenever the platform
+ships a new tool, `npm update` would never actually deliver those updates.
+
+### APP-008 (MUST) — The federation CSS entry is slim and global-free
+
+An App has two CSS entries: the **federation** entry (imported by the `./App`
+remote module) and the **standalone** entry (imported by the SPA entry). The
+federation entry's whole transitive graph — that stylesheet, everything it
+`@import`s, and every `@layer base { … }` block the App writes itself — MUST
+NOT contain:
+
+- `@font-face`;
+- a `@layer base { … }` block;
+- any rule declaring an inherited or visual property — `font-family`,
+  `font-size`, `line-height`, `color`, `background`, `margin`, `padding`,
+  `border-*`, `box-sizing`, `-webkit-text-size-adjust` — on `html`, `body`,
+  `:root` or `*`;
+- an `@import` of a web font, of `@lessly/ui/styles.css`, or of the full
+  `tailwindcss` entry (which bundles **preflight**).
+
+The prohibition holds wherever the rule comes from, `@apply` included:
+`body { @apply bg-bg-primary … }` in the App's own base layer is exactly as
+forbidden as an imported reset. The App's base layer belongs in a separate
+`src/base.css` that only the **standalone** entry imports. The standalone entry
+is unconstrained by this rule: it keeps the fonts, `@lessly/ui/styles.css`, the
+full `tailwindcss` import and the base layer, because there the App owns the
+page.
+
+**Custom properties are the boundary.** Declarations of `--*` on `html`,
+`body`, `:root` or `*` are fine — they paint nothing until something inside the
+App's own subtree reads them. Inherited and visual properties are what is
+forbidden, because the App is composed inside the shell's already-painted page
+and a `body` or `*` rule addresses the whole live document, shell chrome
+included. This line is load-bearing: `@lessly/ui/styles-federated.css`
+legitimately ships a `*, ::before, ::after, ::backdrop { --tw-*: … }` block
+(Tailwind v4's internal variable shim), and a guard written against selectors
+instead of declarations fails on the very import this rule prescribes.
+
+**Kit tokens.** An App that needs the design-system variables MUST import
+`@lessly/ui/styles-federated.css` — `styles.css` minus the `@font-face` blocks
+and the `@layer base`, keeping the token variables, the `--color-*` aliases,
+`.link`, the `.motion-*` helpers and the compiled tw-animate-css layer. Depend
+on `@lessly/ui` at `^4.0.0`, the range the shell itself runs. An App MUST NOT
+hand-copy the kit's tokens into a local `theme.css` (it silently drifts from
+the kit), and MUST NOT hand-filter `@lessly/ui/styles.css` with a prebuild
+script (it breaks on any restructure of a file the App does not own).
+
+**Scanning.** Tailwind generates only the classes it finds, and it scans the
+project, not `node_modules`. The federation entry MUST therefore
+`@source` the kit's compiled output
+(`@source '../node_modules/@lessly/ui/dist/index.js';`) or the classes
+`@lessly/ui` components use are never emitted — and it SHOULD exclude test
+files (`@source not '../src/**/*.test.tsx';`), since a utility class named as a
+test fixture is just a string to Tailwind and would otherwise be compiled into
+the shipped stylesheet.
+
+**Gate test.** The repository MUST carry a test asserting all of the above over
+the **built** federation CSS, not over the entry file's import list: the source
+imports can read clean while an imported stylesheet carries the base layer. Two
+shapes must not be confused — `@layer base, components;` (semicolon) only
+declares layer order and is harmless; the forbidden shape is the block,
+`@layer\s+base\s*\{`. And a universal rule is a violation only if it declares
+more than custom properties.
+
+For the production defect this comes from — a remote's late-loading `body`
+rule re-fonting the shell's chrome — see FED-008 in the toolkit-guide.
+`recipes/federation.md` has the canonical stylesheets.
+
+### APP-009 (MUST) — One source of scale vocabulary: `lesslyPreset`
+
+An App takes its **scale vocabulary** — type, spacing, radii, font weight,
+line height, letter spacing — from the design-system preset the shell is built
+on: `lesslyPreset`, exported by `@lessly/ui/tailwind-preset`. Concretely:
+
+- `tailwind.config.ts` sets `presets: [lesslyPreset]`;
+- **both** CSS entries carry `@config '../tailwind.config.ts'`;
+- the App declares no scales of its own and keeps no `@theme` block bridging
+  to them;
+- the federation graph MUST NOT import `tailwindcss/theme.css` at all — not in
+  `layer(theme)`, and not with `theme(reference)`.
+
+**`theme(reference)` does not solve this.** It removes the `:root` emission,
+but Tailwind still inlines the literal as the utility's fallback
+(`var(--text-sm,.875rem)`), so the utility keeps its own value and keeps
+landing on the shell's markup. Measured: the emission went away and the page
+stayed broken.
+
+**The norm is "one source of vocabulary", not "no variables on `:root`".**
+Variables that coincide on `:root` between the App and the shell are expected
+and harmless — that is one source reaching the page twice. The absence
+criterion measures **green on a broken page**: the shell declares no `--text-*`
+variable at all (its preset compiles literals into the utilities), so three
+repositories passed that check while the shell's sidebar type was being resized
+by their sheets. Do not write a guard that way.
+
+When both sides build on the same preset, rules that share a class name compile
+identically and the collision stops existing. See FED-013 in the
+toolkit-guide for the measurements (13px → 14px, line-height 19.5 → 20) and
+for the three wrong fixes it rules out.
+
+### APP-010 (MUST) — Federation utilities land in `layer(remote-utilities)`
+
+The **federation** entry MUST import Tailwind's utilities into a dedicated
+layer:
+
+```css
+@import 'tailwindcss/utilities.css' layer(remote-utilities);
+```
+
+never `layer(utilities)`. The **standalone** entry is exempt — it keeps the
+full `tailwindcss` import (APP-008), where the App owns the page and there is
+nothing to rank against.
+
+This works because the shell pre-declares the layer order in
+`lessly-workspace:apps/web/src/index.css`:
+
+```css
+@layer theme, base, components, remote-utilities, utilities;
+```
+
+so every App utility ranks below every shell utility whatever order the sheets
+happen to load in. The App's federation entry SHOULD repeat that same order
+declaration as its first line, so the layer positions are fixed before Tailwind
+emits its own.
+
+**Rollout order is strict and asymmetric.** That shell-side declaration MUST be
+in production before an App adopts the layer. Against a shell that has not
+declared the order, `remote-utilities` becomes the last-declared — and
+therefore **highest**-priority — layer, so every App utility beats every shell
+utility: strictly worse than the defect. Verify the shell first; adopting early
+is a regression, not a head start.
+
+See FED-014 in the toolkit-guide for the measurement (App `.px-2` against
+shell `.sm:px-2.5` — different rule names, so no shared preset can reach them;
+5 of 283 shell chrome nodes affected) and for the accepted symmetric risk on
+the App's own nodes.
+
+### APP-011 (SHOULD) — Declare the rail menu in your own manifest
+
+The rail menu the shell draws while your App is open comes from your App's own
+`lessly.app.yaml`, in an optional `nav.sections` block. An App with more than
+one page SHOULD declare it; without it the shell has nothing of yours to draw
+(see *No block* below).
+
+```yaml
+app_schema_version: 1
+id: my-app
+title: My App
+version: 0.2.0
+nav:
+  icon: flask-conical
+  sections:
+    - id: overview
+      items:
+        - label: Dashboard
+          path: ''
+          match: exact
+          icon: gauge
+        - label: Activity
+          path: activity
+          icon: activity
+    - id: settings
+      header: Settings
+      items:
+        - label: Members
+          path: settings/members
+          icon: users-round
+        - label: API keys
+          path: settings/api-keys
+          icon: key
+```
+
+**Field constraints.** These are validated on registration by the platform's
+shared `NavSectionDto`/`NavItemDto` — literally the same DTO classes the
+toolkit manifest validates against (MFST-022 in the toolkit-guide), so the two
+manifests speak exactly one menu language. A violation is a hard reject of the
+registration, not a silent strip.
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `nav.sections` | no | array, 1–20 sections; `id` unique across the array |
+| `sections[].id` | yes | 1–50 chars, lowercase-kebab `^[a-z0-9-]+$` |
+| `sections[].header` | no | 1–50 chars; absent → the group renders with no header line |
+| `sections[].items` | yes | array, 1–50 items |
+| `items[].label` | yes | 1–50 chars, non-empty |
+| `items[].path` | yes | 0–200 chars, `^[a-z0-9-_/]*$`, **no leading slash**, no `..` segment; `''` = your tool root |
+| `items[].icon` | no | 1–50 chars, kebab-case Lucide icon name (e.g. `rocket`) |
+| `items[].match` | no | `exact` or `prefix`; default `prefix` |
+
+`path` is relative to your App's own base path (`/<productSlug>/~/<id>`), so a
+manifest can name a page **inside** your App and nothing else — no absolute
+paths, no external URLs, no traversal. Use `match: exact` on a row whose path
+is a prefix of a sibling's (typically the `''` root row), or it stays lit while
+the sibling is open.
+
+**No block.** `nav.sections` absent is legal. The shell then falls back to its
+transitional table (`extension-menus.ts`, keyed by slug, entity-agnostic) if
+your slug is listed there; if it is not, your rail row stays a **single plain
+link** into the App, with no disclosure mark promising rows that do not exist.
+The fallback is transitional: an App leaves that table the moment its manifest
+ships the menu, and the entry there should be deleted by the same PR. Narrowing
+of the served block is **all-or-nothing** — a half-valid menu falls back to the
+table rather than drawing a partial disclosure.
+
+**Shipping a change.** The menu is picked up on re-registration, including a
+**same-version** one: the registration overlay replaces the whole `nav` blob,
+so adding, editing and removing sections all land without a `version` bump.
+Bumping `version` on release remains APP-007.
+
+**The scaffold's linter does not check this block.** `create-lessly-app lint`
+validates the top-level surface and `nav.icon` only; it neither rejects nor
+warns on `nav.sections`, and it will not catch a malformed one. The platform's
+registration validation is the authority — a menu that lints clean locally can
+still fail registration.
+
+### APP-012 (SHOULD) — Reflect access in the UI, but never enforce it there
+
+An App SHOULD reflect the caller's access in its UI: **disable, with a reason**
+(not hide) a primary action the caller cannot perform, using `useCan` from
+`@lessly/sdk-app/react` or `app.access.can()` directly, and render a 403 that
+`isAccessDenied()` recognises as a **neutral empty state** rather than an error.
+That reason MUST live on a `Tooltip` wrapper around the disabled control, never
+on a native `title=` of the control itself: the base `buttonVariants` carry
+`disabled:pointer-events-none`, so a disabled control fires no hover for the
+browser to render a `title` from, and a native tooltip is unreachable by
+keyboard and by touch in any case. An App that draws such a tooltip MUST mount
+its own `TooltipProvider` once at the root of its remote — `Tooltip.Root` throws
+without one, and the standalone build, the dev entry and the tests all render
+outside the shell.
+
+That reason MUST be exactly one sentence, the same in every App:
+
+> `Requires level:<op.level> (<op.operationKey>). Ask an admin of this product.`
+
+— e.g. `Requires level:admin (mail_domain_create). Ask an admin of this product.`
+Both values MUST be read from the generated method, never written as literals.
+`@lessly/sdk-app` exports `accessReason(op)`, which is that sentence; an App
+SHOULD use it rather than assembling the text itself.
+
+Where a control has only an operation key and no generated method to point at,
+the App MUST NOT guess the level or render `level:undefined`; it says instead:
+
+> `Requires access to <operationKey>. Ask an admin of this product.`
+
+That string form is a **degradation** for operations no generated method covers,
+not licence to pass a key where a method exists — the accessor path is a lossy
+view of the key. An App whose every gate holds an `Operation` never uses it, and
+that is the norm rather than an omission. `accessReason` explains ONE operation;
+choosing which one to explain among a button's several is the caller's, not the
+helper's.
+It names what an admin can grant, not the caller's role: a role name gives them
+nothing to act on. It names the operation key as well as the level because a
+level alone does not identify the grant — seventeen controls on one screen can
+all require `level:write` — and an admin grants both by level and by exact key,
+so the user has to be able to pass on both. Building it from the method also
+keeps it from drifting when the catalog re-levels a tool. Whatever renders it MUST be verified reachable **from the keyboard** —
+Tab to the wrapper, the tooltip opens (in tests: `userEvent.tab()` then
+`findByRole('tooltip')`). Asserting only that a hint attribute is present does
+not satisfy this: that assertion is green against a hint no user can reach.
+
+The level MUST come from the generated method itself (`op.level`, on the
+`Operation` the method satisfies) and from nowhere else: not a lookup table in
+the App, not a literal, and never a rule of thumb about verbs — `analytics_*_delete`
+is `write` while `mail_domain_create` is `admin`, and only the catalog knows.
+
+Where there is no method to read from — a test double, a runtime probe over keys
+it was handed — the App MUST NOT hand-type the level either. `@lessly/sdk-app`
+exports `operations`, the catalog's own level map
+(`Readonly<Record<string, ToolLevel>>`, keyed by operation key), regenerated at
+publish time from the live catalog; read the level from it. A key it does not
+carry answers `undefined`, which is exactly the case `accessReason`'s string form
+covers — no level is invented for it.
+
+The gate belongs to the OPERATION, not to a gesture: where a write is reachable
+by several paths (drag and arrow keys, click and Enter, button and hotkey) all of
+them MUST be gated together, or the hole left behind is one only keyboard users
+find. Implicit form submission is such a path: a disabled submit button does not
+reliably stop Enter inside a field, so the `onSubmit` handler MUST be gated (or
+the fields made `readOnly`) rather than the button alone.
+
+A gate that disables a capability across a WHOLE SURFACE — dragging any node on
+a canvas, a bulk action over a list or a grid — MUST attach the reason to the
+control that owns the capability (the toggle, the toolbar, the surface header)
+and MUST NOT attach it to every affected element: thirty identical focusable
+wrappers are thirty extra tab stops and one sentence thirty times, not thirty
+explanations. Keyboard reachability is satisfied on the owning control; the
+elements themselves just go inert.
+
+Where NO control owns the capability — a calendar whose Month/Week toggle owns
+the view and not the move — the App MUST NOT hang the reason on a control that
+owns a DIFFERENT action: the reason names the operation actually gated, and a
+level and key under a week switcher describe a gate that switcher does not hold.
+It MUST instead render ONE `CardNote` with `accessReason(op)` on the surface
+itself, with the elements left in their inactive state (`draggable={false}`) and
+no tooltip among them.
+
+A control that STAGES a change — it writes nothing itself, the write is sent
+later by a Save or an Apply — MUST be gated on the operation the staged change
+will send, UNLESS the upstream control that reaches it is already gated on that
+same operation. Never on nothing (the caller does the work and meets the refusal
+later, somewhere else) and never twice in a row.
+
+A surface `CardNote` carrying `accessReason` of that SAME operation IS such an
+upstream gate: the staging controls under it MUST NOT be gated again — one
+explanation, not N. What drops is the DUPLICATE EXPLANATION, not the disabled
+state: the staging or submit control stays disabled and carries no tooltip of its
+own (the `CardNote` speaks for it), while the draft's fields and switches stay
+editable. An App MUST NOT re-enable that control "because the gateway will
+refuse" — that is the exact scenario this rule exists against.
+
+Anything that sends NOTHING — parsing an upload, rendering a preview, editing a
+local draft — is reading, and the App MUST NOT gate it. This rule reaches only
+the control after which a caller without the right would meet the refusal having
+already done the work and with no explanation before it.
+
+A control that performs SEVERAL operations per click is disabled if ANY of them
+is denied. A DISPATCHER control — one operation per click, selected by a mode or
+a switch — MUST instead be gated on the operation it is about to call, and name
+that operation's level and key; gating it on the union greys out a button the caller can
+in fact use.
+
+An App SHOULD state the constraint once in a card footer (`CardNote`) rather than
+on every control of a form whose save is deferred: the reader meets the sentence
+before editing rather than after, and one line replaces fifteen identical
+tooltips. The fields stay inactive and the save stays disabled either way — the
+note replaces the per-control hints, not the gate. And the `Tooltip` trigger MUST sit outside every element carrying
+`pointer-events-none` — the App's own lists, chips and overlays as much as the
+kit's disabled buttons — since the hint is swallowed by the same mechanics either
+way.
+
+This applies to every gated write, not only the ones with a button. A drag
+handle, an inline-editable cell and a field that autosaves on blur are gated the
+same way: the native inactive state for that control (`draggable={false}`,
+`readOnly`, `disabled`) plus the reason on a keyboard-reachable `Tooltip`
+wrapper. Leaving a write ungated for the gateway to refuse is permitted ONLY
+where the element has no wrapper that can be made focusable, and that exception
+MUST be written into the App's own spec with its reason. A button that performs
+several operations is disabled if ANY of them is denied, and its reason names
+the level and key of the operation that blocked it.
+
+The reason is claimed only when the App actually knows it. With
+`access.state === 'error'` the `/me` call failed and **nothing** is known about
+the caller's role: the App MUST make no prediction — leave the control enabled,
+name no missing operation, and let the gateway answer, rendering any refusal through
+`isAccessDenied`. Disabling on error makes the client the authority and tells
+the user their role forbids something no one has established. (`can()` itself is
+unaffected: it stays `false` unless the state is `ready`.) While the state is
+`idle` or `loading` the control SHOULD start disabled and enable itself, but
+SHOULD NOT name a missing level or operation it does not yet know.
+
+An App MUST NOT treat that prediction as enforcement. `can()` answers from a
+snapshot fetched once from the `organization_product_me` tool; the gateway is
+the only authority, grants can change between the load and the click, and the
+prediction is `false` for a caller whose snapshot simply has not loaded yet.
+Concretely: never skip a call because `can()` returned false, never present
+`can() === true` to the user as authorisation, and never drop the
+`isAccessDenied` branch from a screen because every button on it is gated.
+
+Two failure modes are worth naming, because both ship regularly:
+
+- **Hiding rather than disabling.** A user who cannot see the button cannot ask
+  their admin for the permission; they report the App as broken instead, and
+  the admin who could have granted it in seconds never hears about it.
+- **Painting a denial red.** A permission boundary is a normal, expected
+  condition and not the user's mistake. Rendering it as a crash trains people
+  to ignore the colour reserved for real failures. `isAccessDenied()` is true
+  for exactly the three gateway codes that mean the caller's access was the
+  reason (`role_denied`, `operation_uncatalogued`, `no_tool_permission`) and
+  false for every other 403 — a `tenant_blocked` is not a permission problem.
+
+State MUST keep the error OBJECT, never a string derived from it. A reducer, a
+queue item or a store slice typed `error: string` has thrown away the only thing
+`isAccessDenied` can read, so a refusal by role arrives red out of a file that
+has no render site at all — and a sweep of render sites never finds it. State
+holds `unknown`; ONE shared component classifies it (`isAccessDenied` → the
+neutral sentence, red for everything else). Audit the reducers, queues and
+stores, not the screens.
+
+Pass the generated method rather than a hand-written tool id
+(`app.access.can(app.mail.domain.create)`): the accessor path is a lossy view
+of the tool id, so a literal string can silently drift from the call it gates.
+
+One gap is known and accepted: `@lessly/ui`'s `ConfirmDialog` takes an `onError`
+that returns a string, so the kit picks the tone and a refusal raised inside the
+dialog cannot be painted neutrally yet. An App SHOULD still route that error
+through `isAccessDenied()` for the *words*, and MUST NOT reimplement the confirm
+flow to win the colour — it would forfeit the focus trap, busy state, confirm
+phrase and step-up. Tracked as platform #2915.
+
+The snapshot has no TTL, so staleness is the App's to invalidate:
+
+- The access snapshot lives in the client instance until `invalidate()` or until
+  the client is recreated — there is no expiry and no background refresh.
+- A module-level singleton client survives SPA navigation and bfcache
+  back/forward, so a "reload" that does not remount the remote keeps the old
+  role. After a role change an App MUST call `app.access.invalidate()` and then
+  `load()` (or do a full page reload).
+- Before measuring staleness, compare the role the App's own `/me` request
+  returned (Network tab) with what the API answers now — never assume it from
+  memory. The server sends no `Cache-Control` for `/me` today and the browser
+  only revalidates via `ETag`, so the HTTP cache alone is never the explanation.
+
+See `recipes/access.md` for the load-once pattern and the empty-state shape.