docs(frontend): dashboard permissions are fetched from the API, not the JWT

The dashboard JWT carries only role names; auth-context.tsx fetches the
effective permission list from GET /api/v1/identity/permissions, caches it, and
exposes permissionsHydrated. Update the agent rules/skills to match the shipped
behavior, and align the Playwright auth-seed helper: permissions in the fake JWT
are inert (gated specs mock GET /identity/permissions instead).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: iammukeshm

.agents/rules/frontend/dashboard.md

@@ -10,9 +10,9 @@ Tenant-facing application. Read `frontend/shared.md` first; this file is only th
 
 The dashboard does **not** depend on react-hook-form or zod. Use controlled inputs + local state. Don't add those deps to match admin.
 
-## Permissions — straight from the JWT
+## Permissions — fetched, not in the JWT
 
-`auth-context.tsx` reads `claims.permissions` off the decoded JWT — no separate fetch, no `permissionsHydrated`, no permissions cache key. `ProtectedRoute` is **auth-only** (no permission gating). Don't add `RouteGuard`-style gating here.
+The JWT carries **only role names**. `auth-context.tsx` fetches the effective permission list from `GET /api/v1/identity/permissions` (`getMyPermissions()` in `src/api/identity.ts`), caches it in `tokenStore` under `fsh.dashboard.permissions`, and exposes a `permissionsHydrated` flag so gated UI doesn't flash while the fetch is in flight (re-fetched on login/impersonation swaps; `refreshPermissions()` for role changes). Nav items are gated via `perm`/`anyPerm` in `src/components/layout/nav-data.ts`. `ProtectedRoute` is still **auth-only** (no per-route permission gating) — don't add `RouteGuard`-style gating here.
 
 ## Routing & realtime/SSE
 

.agents/skills/add-permission/SKILL.md

@@ -61,7 +61,7 @@ So `RouteGuard` passes on first paint, add the new permission to the test seed s
 
 ## Dashboard
 
-No mirror, no `RouteGuard`. The permission rides in the JWT (`claims.permissions`) and the server enforces it; a missing permission yields a 403 the UI surfaces. Nothing to add client-side beyond consuming the gated endpoint.
+No mirror, no `RouteGuard`. The JWT carries only role names — the app fetches the permission list from `GET /api/v1/identity/permissions` at hydration and the server enforces access; a missing permission yields a 403 the UI surfaces. Routes aren't permission-gated; to hide a nav entry, set `perm`/`anyPerm` on the item in `src/components/layout/nav-data.ts`. Permission-gated specs mock `GET /identity/permissions` with the grants they need (shell mocks stub it to `[]`).
 
 ## Checklist
 

.agents/skills/add-react-page/SKILL.md

@@ -17,7 +17,7 @@ The frontend slice. Read `.agents/rules/frontend/shared.md` plus the app file (`
 | Forms | **react-hook-form + zod** | **hand-rolled** controlled inputs (no RHF/zod) |
 | List + create | separate routed pages (`list.tsx`, `create.tsx`) | one file with `<Dialog>` editors |
 | Route wrapper | `<RouteGuard perms={[…]}>` | `withSuspense(<X/>)` (no permission gate) |
-| Permissions | mirror in `src/lib/permissions.ts` | none — JWT claims + server 403 |
+| Permissions | mirror in `src/lib/permissions.ts` | fetched from `GET /identity/permissions` (not JWT); nav gating via `perm`/`anyPerm` in `nav-data.ts`; no route guard — server 403 backstops |
 
 Shared everywhere: types are **hand-written** (no codegen); `apiFetch<T>` from `@/lib/api-client`; `cn()` from `@/lib/cn`; `env.apiBase` from runtime `/config.json`; CVA `components/ui` + `components/list` primitives; Tailwind v4 CSS-first (tokens in `src/styles/globals.css`); `toast` from `sonner`; pages are **named exports**; `placeholderData: keepPreviousData` (v5).
 

clients/dashboard/tests/helpers/auth-seed.ts

@@ -7,15 +7,23 @@ import type { Page } from "@playwright/test";
  * We populate the same localStorage keys the runtime tokenStore writes
  * (see clients/dashboard/src/auth/token-store.ts). The token value is
  * a JWT-shaped string that decodes to the supplied user — useAuth's
- * decoder reads sub/email/given_name/family_name/tenant/permissions
- * out of the payload.
+ * decoder reads sub/email/given_name/family_name/tenant out of the
+ * payload. Permissions are NOT read from the JWT: at runtime the app
+ * fetches them from GET /api/v1/identity/permissions (installShellMocks
+ * stubs that route to []; permission-gated specs re-mock it with the
+ * grants they need — see tests/system/trash.spec.ts).
  */
 export type SeededUser = {
   sub: string;
   email: string;
   firstName: string;
   lastName: string;
   tenant: string;
+  /**
+   * Inert — written into the fake JWT payload but ignored by the app.
+   * To grant permissions in a spec, mock GET /identity/permissions
+   * instead.
+   */
   permissions?: string[];
 };
 
@@ -36,7 +44,7 @@ function fakeJwt(payload: Record<string, unknown>): string {
 
 export async function seedAuthedSession(page: Page, user: SeededUser) {
   // Build the JWT-shaped payload. Claim names match what useAuth's decoder
-  // looks for in the runtime path.
+  // looks for in the runtime path (permissions excepted — inert, see SeededUser).
   const payload = {
     sub: user.sub,
     email: user.email,