@exxatdesignux/ui 0.2.18 → 0.3.0

package/CHANGELOG.md

@@ -15,10 +15,78 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ---
 
+## [Unreleased]
+
+## [0.3.0] – 2026-05-21
+
+### Added
+
+- **`exxat-ui sync-extras` now installs the full AI bundle in one command.** Previously the CLI shipped only Cursor skills + pattern docs; consumers had to `degit` Cursor rules and handbook tier docs separately. The CLI now writes, in one pass:
+  1. **Skills to both clients** — `.cursor/skills/exxat-*/` **and** `.claude/skills/exxat-*/` (same `SKILL.md` shape, two readers, one source of truth — no more `ln -s` step).
+  2. **Cursor rules** — `.cursor/rules/exxat-*.mdc` (29 binding `MUST` / `MUST NOT` files: data-tables, accessibility, kbd shortcuts, KPI trends/flat-band/max-four, board cards, list-page-view-shells, centralized-list-dataset, reuse-before-custom, no-toast, drawer-vs-dialog, page-vs-drawer, no-slds-leakage, token-discipline, mono-ids, fontawesome-icons, dashboard-view-charts, …).
+  3. **Handbook tier** — `docs/exxat-ds/handbook/{HANDBOOK,glossary,voice-and-tone,reference-implementations}.md`. These are stage-rewritten copies of `apps/web/docs/*.md` — links to shipped patterns use `../`, links to unshipped neighbours (blueprints, token-taxonomy, root `AGENTS.md`, `lib/*`) are rewritten to absolute GitHub URLs at bundle time so every link in the consumer's repo resolves.
+  4. **Patterns + checklist** — unchanged from prior releases (`docs/exxat-ds/*-pattern.md`, `consumer-upgrade-checklist.md`).
+
+  The CLI is **namespaced** — it only writes files starting with `exxat-` (skills + rules), so a consumer's own non-Exxat rules / skills survive an upgrade untouched. Product code under `app/`, `pages/`, `src/`, plus the consumer's own `AGENTS.md`, are never modified. Bundle source lives at `packages/ui/consumer-extras/{cursor-skills,cursor-rules,patterns,handbook}/`.
+
+- **Single centralized `<HubTable<TRow>>`** — `components/data-views/hub-table.tsx` is now the one table surface every list-page hub renders. It owns the previously per-hub scaffolding that drifted across five files: `useTableState`, `displayOptions` (controlled or internal), `conditionalRules` add/remove/update, `filterFields` + `fieldDefinitions` + `resolveColumnLabel` memos, `TablePropertiesDrawerButton` wiring with `supportedViewTypes`, the imperative `openPropertiesDrawer()` handle (`HubTableHandle`), the default `DataTable` for `view === "table"`, and `ListPageConnectedViewBody` routing for every other view. Hubs now pass only **what's different**: column defs, a typed `renderers: HubTableRenderers<TRow>` map for non-table views, and entity-specific labels/sorts/empties. The renderer args (`state`, `toolbar`, `toolbarShell`, `drawerToolbarProps`, `displayOptions`, `patchDisplay`) cover both the common "wrap a body in the shared toolbar" case (`toolbarShell(<MyView rows={state.rows} />)`) and the escape-hatch case (dashboards that own their own toolbar with extra layout-edit actions splat `drawerToolbarProps` back into a custom `<TablePropertiesDrawerButton>`). Hub-specific helpers (`columnsToFilterFields`, `columnsToFieldDefinitions`) are exported from the same module so column defs become the single source of truth for filters + drawer field options. Mirrored to `packages/ui/template/components/data-views/hub-table.tsx`.
+- **Per-hub `supportedViewTypes` allowlists** — `lib/team-supported-views.ts`, `lib/compliance-supported-views.ts`, `lib/placements-supported-views.ts`, `lib/sites-supported-views.ts` (matching the existing `question-bank-supported-views.ts` and `list-hub-supported-views.ts`). Each hub passes its allowlist into `<HubTable>` so `TablePropertiesDrawerButton` filters the view-type tile grid to the hub's implemented views — Sites cannot pick Calendar, Placements cannot pick Calendar, Team cannot pick Folder/Tree, etc. Pair these with `ListPageTemplate.supportedViewTypes` on the hub client to filter the Add-view menu + ⌘1–9 shortcuts in tandem.
+
+### Changed
+
+- **Every hub table migrated to `<HubTable>` + `ListPageConnectedViewBody`** — the previous "single centralized list dataset" rule is now structurally enforced (one `useTableState` per hub, one row bag every view body reads). Net code: hub `*-table.tsx` files dropped from **4,402** → **2,984** lines (-32%) by removing duplicated scaffolding; the new `hub-table.tsx` adds ~350 lines once. Per-hub deltas:
+  1. **`placements-table.tsx`** 1,642 → 955 (-42%). Six bespoke `DataList*Shell` sub-components (board / list / dashboard / folder / tree-panel / panel) deleted — each one was a separate copy of `<DataTableToolbar … toolbarSlot={s => <TablePropertiesDrawerButton …/>}>` wrapped around a different view body. Replaced by per-view renderer entries that call `toolbarShell(<body />)`. Pagination chrome (`CountSyncer` + `PaginationBar`) moves into a custom `tableRenderer` + the `list-with-toolbar` renderer; `HubTable.paginationOverride` is forwarded into `useTableState`. The dashboard's layout-edit + coach-mark + persistence state lives in an internal `<PlacementsDashboardBody>` component (renderers can't host hooks — `ListPageConnectedViewBody` calls them inline).
+  2. **`question-bank-table.tsx`** 1,073 → 823 (-23%). The custom `<HubFolderColumnsPanel>` miller-view + `<HubTreePanelView>` stay (genuinely entity-specific); every shell/toolbar wrapper around them is gone. The `QuestionBankNewFolderSheet` modal state (shared by panel + tree-panel) moves to the hub's top scope, so both renderers share one sheet instance instead of duplicating it. URL search sync is now `HubTable.syncedSearchFromUrl={searchLanding ? undefined : urlListSearch}` (was a 5th positional argument to `useTableState`).
+  3. **`team-table.tsx`** 693 → 534 (-23%). Dashboard layout + coach-mark + persistence state extracted into a `<TeamDashboardBody>` internal component, same pattern as Placements. `TeamFinderListRow` + `TeamFinderDetail` panel helpers unchanged.
+  4. **`compliance-table.tsx`** 612 → 448 (-27%). Same dashboard-body extraction; panel groups builder unchanged.
+  5. **`sites-table.tsx`** 382 → 224 (-41%). Inline panel + dashboard renderers; sites has no custom dashboard-layout state.
+- **`HubTable` API additions** (back-compat — all new props optional) — `displayOptions` + `onDisplayOptionsChange` (controlled mode for hubs that persist display state at the page level, e.g. Placements; otherwise `HubTable` owns the state internally), `pagination` + `onPaginationChange` (forwarded to `TablePropertiesDrawerButton` so the drawer's Display panel can offer "Show pagination"), `paginationOverride` (forwarded to `useTableState` for server-style paged tables), `syncedSearchFromUrl` (forwarded to `useTableState` for `?q=`-bound toolbar search), `onRowClick`, and `tableRenderer` (override for the `data-table` view when the hub needs pagination chrome or a custom wrapper around `<DataTable>`).
+- **`OpenTablePropertiesHandle` aliases** — each `*-table.tsx` now exports `*TableHandle = HubTableHandle` instead of `= OpenTablePropertiesHandle` directly. Both resolve to the same shape (`{ openPropertiesDrawer(): void }`), so existing `tablePropertiesRef` consumers continue to work without changes.
+
+### Added (continued, from earlier in this Unreleased section)
+
+- **View registry + per-hub `supportedViewTypes` plumbing** — single source of truth for list-page view types and their render kinds, with per-hub allowlists so Properties, Add view, and ⌘1–9 shortcuts never offer a view the hub does not render.
+  1. **`lib/data-list-view-registry.ts`** — `DATA_LIST_VIEW_REGISTRY` (one `DataListViewDefinition` per `DataListViewType`), `dataListViewDefinition`, `dataListViewTilesForHub` / `dataListViewSelectionTilesForHub` (filtered tiles for a hub's `supportedViewTypes`), `isDataListSurfaceViewType` (now derived from the registry — the previous local `SURFACE_VIEW_TYPES` literal in `lib/list-page-table-properties.ts` is gone), `showsListPageHubMetricsStrip` (false for `calendar` and `dashboard`).
+  2. **`components/data-views/list-page-connected-view-body.tsx`** — `<ListPageConnectedViewBody view renderers hubLabel />` switches list-hub view bodies by render kind. Missing kinds render a clear `<ListPageViewNotConfigured>` empty state — never silently fall through to dashboard. Renderers can be `React.ReactNode` or `() => ReactNode` (the latter for lazy / heavy bodies).
+  3. **`lib/hub-connected-view-renderers.ts`** — typed `defineHubViewRenderers(supported, renderers)` builder; the `Supported` generic constrains the renderer keys to the hub's actual render kinds, and dev builds emit a console warning when a supported view has no body.
+  4. **`lib/question-bank-supported-views.ts`** + **`lib/list-hub-supported-views.ts`** — per-hub allowlists (e.g. Question bank supports `table | list | board | dashboard | folder | panel | tree-panel`; List hub supports `table | list | board | calendar | panel`). Hubs pass these into `ListPageTemplate.supportedViewTypes` and `TablePropertiesDrawerButton.supportedViewTypes`.
+  5. **`DataListViewType` gains `"calendar"`** — and `data-list-view-surface.ts` adds the matching `calendar-with-toolbar` render kind. Existing hubs are unaffected (no hub claims `calendar` in its supported set yet); the type is now forward-compatible with a calendar body.
+
+### Changed
+
+- **`TablePropertiesDrawer` + `TablePropertiesDrawerButton`** accept optional `supportedViewTypes?: readonly DataListViewType[]`. When set, the view-type tile grid in Properties is filtered to that hub's implemented views (via `dataListViewTilesForHub`) so users cannot switch a hub into a view it does not render. Default behavior (omitting the prop) is unchanged — all registered tiles are shown.
+- **`ListPageTemplate`** accepts the same `supportedViewTypes` prop and filters **both** the Add view dropdown menu and the ⌘1–9 shortcut bindings to the hub's actual views. Previously, `VIEW_TYPES.slice(0, 9)` bound every registered view globally even on hubs that only implement a subset, so a user could ⌘4 → Dashboard into a hub that had no dashboard renderer (it would fall through to the not-configured empty state).
+- **Question bank** (`question-bank-client.tsx`, `question-bank-table.tsx`) now passes `QUESTION_BANK_SUPPORTED_VIEWS` into `ListPageTemplate.supportedViewTypes` and `TablePropertiesDrawerButton.supportedViewTypes` end-to-end. Other hubs (Placements, Team, Compliance, Sites) are unchanged for this release — they still expose every registered view; their `supportedViewTypes` props are opt-in.
+- **`lib/list-page-table-properties.ts`** no longer maintains its own `SURFACE_VIEW_TYPES` literal. `isDataListSurfaceViewType` is re-exported from `lib/data-list-view-registry.ts` so adding a new `DataListViewType` no longer requires editing three files.
+
+### Promoted into `@exxatdesignux/ui` (shared primitives)
+
+- **`components/resizable`** + **`components/dot-pattern`** moved from `apps/web/components/ui/` to `packages/ui/src/components/ui/`. App imports continue to work through `apps/web/components/ui/{resizable,dot-pattern}.tsx`, which are now one-line re-exports from `@exxatdesignux/ui/components/{resizable,dot-pattern}`. Added `motion@^12.38.0` and `react-resizable-panels@^4.10.0` to `packages/ui/package.json` `dependencies`.
+
+### Removed
+
+- **`components/section-cards.tsx`** (dead since the shadcn starter — zero imports across `apps/web` and `packages/ui/template/`).
+
+### Renamed
+
+- **`components/sites-all-client.tsx`** → **`components/sites-client.tsx`**; `SitesAllClient` export → `SitesClient`. The hub is currently unmounted (no `app/(app)/sites/` route), but the file is kept as a reference Sites hub composition and renamed for consistency with `placements-client`, `team-client`, `compliance-client`. Mirrored in `packages/ui/template/`.
+
 ## [0.2.18] - 2026-05-19
 
 ### Fixed
 
+- **Dark mode surface elevation ladder — popover / card split, secondary panel nestled** (`globals.css`):
+  1. **`--popover` lifted to L=0.275** (was 0.225). Sharing the card's subtle 0.225 value made floating dropdowns blend straight into the canvas (only +0.025 above L=0.20) — the dropdown chrome lost its boundary. Popover now sits +0.075 above canvas with a slightly elevated chroma (built-ins 0.022 / custom `max(0.018, c·0.16)`), giving dropdowns and menus the visible lift they need over content. `--card` stays at 0.225 — it's an *inline* surface, not a floating one, and the earlier "subtle wash" reading was correct for it.
+  2. **`--secondary-panel-bg` rewired** from `var(--brand-tint)` (which resolved to L=0.30) down to **L=0.22**. The old value made the secondary nav panel *brighter* than the surrounding sidebar (L=0.245), so the Library / question-bank rail popped out as a bright tile instead of nesting in. The new value wedges it between sidebar (0.245) and canvas (0.20). Per-theme overrides carry the brand hue + chroma (Exxat One 0.025, Prism 0.030, Assessment 0.025, custom `max(0.020, c·0.20)`).
+  3. **Dark surface ladder is now** `--background` 0.20 → `--secondary-panel-bg` 0.22 → `--card` 0.225 → `--sidebar` / `--input-background` 0.245 → `--popover` 0.275 — clear, monotonic stepping with floating elements lifting further than inline ones.
+- **Dark mode card / popover / input-background — softened to a subtle brand wash, not a tinted panel** (`globals.css`): The previous pass at `L=0.255 C=0.030` made cards read as a *separate tinted surface* floating above canvas. Pulled lightness down to `L=0.225` (only 0.025 above `--background` at L=0.20) and chroma down to `C=0.017` (built-ins) / `max(0.015, calc(c*0.13))` (custom). Cards now read as the same surface family as canvas with a small elevation step and a whisper of brand hue — the saturated brand expression remains on `--brand-tint` and `--sidebar` where it belongs. Input background follows the same shift (L 0.245 / C 0.010). Foreground contrast unchanged (≥ 12:1).
+- **Hydration warnings from the Cursor IDE browser preview** (`app/(app)/layout.tsx`, `components/templates/nested-secondary-panel-shell.tsx`, `components/ask-leo-sidebar.tsx`): The in-IDE browser MCP injects a `data-cursor-ref` attribute on top-level layout chrome *before* React hydrates so it can target those nodes for click automation. React then warned about an attribute it didn't render. Added `suppressHydrationWarning` on just the three SSR-rendered shell roots that the MCP tags. The flag is scoped to *each element's own attributes only* — children still hydrate normally and any real mismatch inside the panel still surfaces. Has zero effect outside the Cursor IDE preview.
+- **Dark mode brand surfaces — every product chrome surface now reads as the brand per product** (`globals.css`):
+  1. **`--brand-tint`** was never overridden in `.dark` or any `.theme-*.dark` block, so it cascaded down from the light-mode pale value (e.g. `oklch(0.97 0.02 343)` for Prism). Because the dark `--secondary-panel-bg` formula derived it as `color-mix(--card 32%, --brand-tint 68%)`, the question-bank Library secondary panel rendered as a pale rose / lavender pastel on dark canvas. Fixed by adding `--brand-tint` / `--brand-tint-light` / `--brand-tint-subtle` overrides at dark-mode lightness inside `.dark`, `.theme-one.dark`, `.theme-prism.dark`, `.theme-assessment.dark`, and `.theme-custom.dark`.
+  2. **`--secondary-panel-bg` formula in `.dark`** rewritten from `color-mix(--card 32%, --brand-tint 68%)` to plain `var(--brand-tint)`. The old mix folded in `--card`'s neutral hue 270 — never overridden per theme in dark mode — so every product's secondary panel was pulled toward the same purple-neutral. Now the panel renders as a fully brand-tinted dark surface that varies clearly per product: Exxat One `#2c2a46` (navy-lavender), Prism `#402235` (wine), Assessment `#143525` (forest green).
+  3. **`--brand-tint` / `--sidebar` chroma** raised from `0.014–0.015` to `0.04–0.055` at their dark-mode lightnesses. At L≈0.245–0.30 the OKLCH hue-perception threshold is much higher than at L≈0.97 (Helmholtz–Kohlrausch effect), so the previous chroma was below the perception floor — products looked identical even though their hues were set correctly. The new chroma is well within WCAG contrast bounds (foreground stays ≥ 11:1 on every variant).
+  4. **`--card` / `--popover` / `--input-background`** were only set in base `.dark` at neutral hue 270, never overridden per theme. KPI tiles, popovers, and outlined surfaces therefore stayed dead grey no matter which product was active — directly visible on the dashboard's six KPI tiles in the custom-orange theme. Added per-theme overrides at L≈0.255 with chroma 0.03 (built-ins) or `max(0.022, calc(c * 0.22))` (custom) at brand hue. Cards now render as a "darker version of the brand color" per product: Exxat One `#212131`, Prism `#2d1d27`, Assessment `#15271e`, custom-orange `#2f1e16`.
+- **Dark canvas brand cohesion** (`globals.css`): `--background` chroma in every `.theme-*.dark` block bumped from `0.008` to `0.014`. At L 0.20 the previous chroma sat below the OKLCH hue-perception threshold, so the canvas read as dead-neutral grey regardless of the brand hue. The new value gives the canvas a perceptible whisper of brand chroma without affecting text contrast (foreground stays ≥ 12:1 against background).
 - **`Sidebar`**: Read `sidebar_state` on the server for `defaultOpen` so the documents **Resources** heading and rail chrome match the first client paint (fixes hydration warnings). Skip redundant cookie restore when state already matches.
 - **`TablePropertiesDrawer`**: Portaled **Add filter / sort / rule** menus use `z-[90]` above the properties sheet (`z-[80]`); `Sheet` and dropdowns use `modal={false}`; filter updates apply synchronously (no `startTransition` deferral). Drawer button routes column/display handlers through refs for the portaled sheet.
 
@@ -45,7 +113,7 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ### Changed
 
-- **Tokens**: `globals.css` / `theme.css` refinements and starter **`template/`** parity with the web app (layout, Question bank hub chrome, navigation).
+- **Tokens**: `globals.css` refinements and starter **`template/`** parity with the web app (layout, Question bank hub chrome, navigation). *(Note: `theme.css` was a duplicate of `globals.css` and has been removed — see [`0003-globals-css-canonical.md`](../../apps/web/docs/migrations/0003-globals-css-canonical.md).)*
 - **Consumer extras**: Cursor skills + pattern docs refreshed for collaboration / Question bank hub header.
 
 ### Chore (monorepo)

package/bin/sync-extras.mjs

@@ -2,12 +2,20 @@
 /**
  * Consumer: copy packaged design-system extras into the app repo.
  *
- * Overwrites ONLY:
+ * Writes (and overwrites) ONLY:
  *   - `.cursor/skills/<bundled exxat-* skill folders>/`
- *   - `docs/exxat-ds/*.md` (pattern reference docs + **consumer-upgrade-checklist.md**)
+ *   - `.claude/skills/<bundled exxat-* skill folders>/`  (same SKILL.md shape;
+ *       Claude Code reads from `.claude/skills/` instead of `.cursor/skills/`)
+ *   - `.cursor/rules/<bundled exxat-*.mdc rule files>`
+ *   - `docs/exxat-ds/*.md`             (pattern reference docs + consumer-upgrade-checklist.md)
+ *   - `docs/exxat-ds/handbook/*.md`    (HANDBOOK, glossary, voice-and-tone, reference-implementations)
  *
- * Does NOT touch `app/`, `pages/`, `src/` product code, or npm dependencies.
- * Run after `npm install @exxatdesignux/ui@…` / `pnpm update @exxatdesignux/ui`.
+ * The CLI is **namespaced** — it only touches files starting with `exxat-`
+ * (skills + rules) so a consumer's own non-Exxat rules/skills are preserved.
+ * Product code under `app/`, `pages/`, `src/`, plus the consumer's `AGENTS.md`
+ * and any of their own docs are never modified.
+ *
+ * Run after every `npm install @exxatdesignux/ui@…` / `pnpm update @exxatdesignux/ui`.
  *
  *   npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
  */
@@ -20,46 +28,125 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkgRoot = resolve(__dirname, "..")
 const cwd = process.cwd()
 
-const skillsSrc = join(pkgRoot, "consumer-extras", "cursor-skills")
-const skillsDest = join(cwd, ".cursor", "skills")
+const SOURCES = {
+  skills:   join(pkgRoot, "consumer-extras", "cursor-skills"),
+  rules:    join(pkgRoot, "consumer-extras", "cursor-rules"),
+  patterns: join(pkgRoot, "consumer-extras", "patterns"),
+  handbook: join(pkgRoot, "consumer-extras", "handbook"),
+}
+
+const DESTINATIONS = {
+  cursorSkills:  join(cwd, ".cursor", "skills"),
+  claudeSkills:  join(cwd, ".claude", "skills"),
+  cursorRules:   join(cwd, ".cursor", "rules"),
+  patterns:      join(cwd, "docs", "exxat-ds"),
+  handbook:      join(cwd, "docs", "exxat-ds", "handbook"),
+}
 
-const patternsSrc = join(pkgRoot, "consumer-extras", "patterns")
-const patternsDest = join(cwd, "docs", "exxat-ds")
+let wrote = 0
+let skipped = 0
 
-function syncSkills() {
-  if (!existsSync(skillsSrc)) {
-    console.error(
-      "[sync-extras] Missing packaged skills. Is @exxatdesignux/ui installed? Expected:",
-      skillsSrc,
-    )
+/** Replace `dest` with `src` (directory) — preserves only what we own. */
+function replaceDir(src, dest) {
+  if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
+  cpSync(src, dest, { recursive: true })
+}
+
+/**
+ * Skills are bundled as directories like `cursor-skills/exxat-board-cards/SKILL.md`.
+ * Copy every `exxat-*` directory into the destination, replacing any prior copy.
+ * The same source tree is written to BOTH Cursor and Claude (identical SKILL.md
+ * shape, two readers) so one upgrade lights up both clients.
+ */
+function syncSkillsTo(label, dest) {
+  if (!existsSync(SOURCES.skills)) {
+    console.error("[sync-extras] missing packaged skills:", SOURCES.skills)
     process.exit(1)
   }
-  mkdirSync(skillsDest, { recursive: true })
-  for (const name of readdirSync(skillsSrc)) {
-    const src = join(skillsSrc, name)
+  mkdirSync(dest, { recursive: true })
+  for (const name of readdirSync(SOURCES.skills)) {
+    const src = join(SOURCES.skills, name)
     if (!statSync(src).isDirectory()) continue
     if (!name.startsWith("exxat-")) continue
-    const dest = join(skillsDest, name)
-    if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
-    cpSync(src, dest, { recursive: true })
-    console.log(`[sync-extras] wrote .cursor/skills/${name}/`)
+    replaceDir(src, join(dest, name))
+    console.log(`[sync-extras] wrote ${label}/${name}/`)
+    wrote++
+  }
+}
+
+/**
+ * Rules ship as flat `.mdc` files under `consumer-extras/cursor-rules/`.
+ * Only files starting with `exxat-` are copied so the consumer's own rules
+ * (and any other vendor's rules) survive an upgrade untouched.
+ */
+function syncRules() {
+  if (!existsSync(SOURCES.rules)) {
+    console.warn("[sync-extras] no packaged cursor-rules (optional)")
+    skipped++
+    return
+  }
+  mkdirSync(DESTINATIONS.cursorRules, { recursive: true })
+  for (const name of readdirSync(SOURCES.rules)) {
+    const src = join(SOURCES.rules, name)
+    if (!statSync(src).isFile()) continue
+    if (!name.startsWith("exxat-") || !name.endsWith(".mdc")) continue
+    cpSync(src, join(DESTINATIONS.cursorRules, name))
+    console.log(`[sync-extras] wrote .cursor/rules/${name}`)
+    wrote++
   }
 }
 
+/**
+ * Pattern docs (data-views-pattern, command-menu-pattern, …) + the
+ * `consumer-upgrade-checklist.md` land flat in `docs/exxat-ds/`.
+ */
 function syncPatterns() {
-  if (!existsSync(patternsSrc)) {
-    console.warn("[sync-extras] no packaged patterns (optional).")
+  if (!existsSync(SOURCES.patterns)) {
+    console.warn("[sync-extras] no packaged patterns (optional)")
+    skipped++
     return
   }
-  mkdirSync(patternsDest, { recursive: true })
-  for (const name of readdirSync(patternsSrc)) {
-    const src = join(patternsSrc, name)
+  mkdirSync(DESTINATIONS.patterns, { recursive: true })
+  for (const name of readdirSync(SOURCES.patterns)) {
+    const src = join(SOURCES.patterns, name)
     if (!statSync(src).isFile()) continue
-    cpSync(src, join(patternsDest, name))
+    cpSync(src, join(DESTINATIONS.patterns, name))
     console.log(`[sync-extras] wrote docs/exxat-ds/${name}`)
+    wrote++
+  }
+}
+
+/**
+ * Handbook tier (HANDBOOK · glossary · voice-and-tone · reference-implementations)
+ * lands in a nested `docs/exxat-ds/handbook/` so the patterns dir stays flat
+ * and the handbook's internal cross-links resolve.
+ *
+ * The bundled handbook files are stage-rewritten copies of the workspace
+ * source (`apps/web/docs/*.md`) — links to shipped patterns use `../`, links
+ * to unshipped neighbours (blueprints, token-taxonomy, etc.) are absolute
+ * GitHub URLs so they continue to work in the consumer's repo.
+ */
+function syncHandbook() {
+  if (!existsSync(SOURCES.handbook)) {
+    console.warn("[sync-extras] no packaged handbook (optional)")
+    skipped++
+    return
+  }
+  mkdirSync(DESTINATIONS.handbook, { recursive: true })
+  for (const name of readdirSync(SOURCES.handbook)) {
+    const src = join(SOURCES.handbook, name)
+    if (!statSync(src).isFile()) continue
+    cpSync(src, join(DESTINATIONS.handbook, name))
+    console.log(`[sync-extras] wrote docs/exxat-ds/handbook/${name}`)
+    wrote++
   }
 }
 
-syncSkills()
+syncSkillsTo(".cursor/skills", DESTINATIONS.cursorSkills)
+syncSkillsTo(".claude/skills", DESTINATIONS.claudeSkills)
+syncRules()
 syncPatterns()
-console.log("[sync-extras] Done. Product routes and app content were not modified.")
+syncHandbook()
+
+console.log(`[sync-extras] Done. ${wrote} files / dirs written; ${skipped} optional sources missing.`)
+console.log("[sync-extras] Product routes and app content were not modified.")

package/consumer-extras/README.md

@@ -6,17 +6,56 @@ touching product routes or pages.
 
 | Path in this tarball | After `exxat-ui sync-extras` in your repo |
 |----------------------|-------------------------------------------|
-| `CHANGELOG.md` (package root) | Stay in `node_modules/…` — read for release notes; **`exxat-ui changelog`** prints it |
-| `cursor-skills/exxat-*` | `.cursor/skills/exxat-*` (replaced) |
-| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) — includes **`consumer-upgrade-checklist.md`** for upgrades + AI handoff |
+| `CHANGELOG.md` (package root) | Stays in `node_modules/…` — read for release notes; **`exxat-ui changelog`** prints it |
+| `cursor-skills/exxat-*` | `.cursor/skills/exxat-*` **and** `.claude/skills/exxat-*` (replaced; same `SKILL.md` shape, two readers) |
+| `cursor-rules/exxat-*.mdc` | `.cursor/rules/exxat-*.mdc` (replaced) — binding **MUST / MUST NOT** files |
+| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) — pattern docs + **`consumer-upgrade-checklist.md`** |
+| `handbook/*.md` | `docs/exxat-ds/handbook/*.md` (replaced) — `HANDBOOK`, `glossary`, `voice-and-tone`, `reference-implementations` |
+
+The CLI is **namespaced**: it only touches files starting with `exxat-` (skills + rules)
+so a consumer's own non-Exxat rules / skills are preserved. Product code under `app/`,
+`pages/`, `src/`, plus the consumer's `AGENTS.md` and any of their own docs are never
+modified.
 
 **Components and hooks** still come only from `node_modules/@exxatdesignux/ui`
 via normal semver installs — `sync-extras` does not copy TS source into your app.
 
-**Maintainers** (this monorepo): when skills or web docs change, run:
+**Maintainers** (this monorepo): when skills, rules, or web docs change, run:
 
 ```bash
 pnpm --filter @exxatdesignux/ui vendor:consumer-extras
 ```
 
 …then bump `packages/ui` version and publish so consumers get the new bundle.
+
+## What lands where (full install map)
+
+```
+<consumer-repo>/
+├── .cursor/
+│   ├── rules/exxat-*.mdc         ← binding MUST / MUST NOT (cursor-rules/)
+│   └── skills/exxat-*/SKILL.md   ← agent workflows + checklists (cursor-skills/)
+├── .claude/
+│   └── skills/exxat-*/SKILL.md   ← Claude mirror of the same skills (cursor-skills/)
+└── docs/
+    └── exxat-ds/
+        ├── *-pattern.md          ← narrative pattern docs (patterns/)
+        ├── consumer-upgrade-checklist.md
+        └── handbook/
+            ├── HANDBOOK.md
+            ├── glossary.md
+            ├── voice-and-tone.md
+            └── reference-implementations.md
+```
+
+## Note on handbook link rewriting
+
+The bundled handbook files (`handbook/*.md`) are stage-rewritten copies of the
+workspace source (`apps/web/docs/*.md`). Inter-doc links are normalised at
+bundle time:
+
+- Links to files we ship → relative (`./glossary.md`, `../data-views-pattern.md`)
+- Links to files we don't ship (blueprints, `token-taxonomy.md`, `component-selection-guide.md`, `lib/*`, root `AGENTS.md`) → absolute GitHub URLs
+
+This keeps every link clickable from the consumer's `docs/exxat-ds/handbook/`
+directory without requiring them to clone the workspace.

package/consumer-extras/cursor-rules/exxat-accessibility.mdc

@@ -0,0 +1,39 @@
+---
+description: Exxat DS — WCAG 2.1 AA, ARIA tablists, 24px targets, contrast; see AGENTS.md §8 and exxat-accessibility skill
+alwaysApply: true
+---
+
+# Exxat DS — accessibility (binding summary)
+
+**Full checklist (ARIA, touch targets, color, sidebar badges, audit follow-ups):** repo **`.cursor/skills/exxat-accessibility/SKILL.md`**.
+
+**Product rules in prose + checklist:** **`apps/web/AGENTS.md` §8**.
+
+## Non‑negotiables
+
+1. **Target:** **WCAG 2.1 Level AA** (2.2 where noted — e.g. target size).
+2. **`role="tablist"`** — only **`role="tab"`** (or equivalent) as direct tab semantics. **MUST NOT** put `role="button"`, menus (`aria-haspopup`), or other controls **inside** the same `tablist` container.
+3. **Composite view switchers** (tabs + per-tab menu + remove): use **`role="toolbar"`** + **`aria-label`**; **`aria-pressed`** on toggles — **MUST NOT** misuse `tab`/`tablist` for those controls.
+4. **Touch targets (2.5.8):** interactive controls **≥ 24×24 CSS px** or **24px** spacing so hit areas do not overlap — use **`min-h-6 min-w-6` / `size-6`** for icon-only targets; avoid **`size-4`** as the sole target.
+5. **Contrast:** normal text **≥ 4.5:1**; UI components / focus where required **≥ 3:1**; muted text on tinted surfaces use tokens against the correct surface (e.g. sidebar), not only `--background`.
+6. **Minimum text size:** visible product copy **≥ 11px** — use **`text-xs`** or larger; **MUST NOT** use arbitrary Tailwind font sizes below that (see **`apps/web/AGENTS.md` §8.3**, **`apps/web/app/globals.css`** `--text-xs`).
+7. **Dialogs / sheets / drawers:** must expose a **Title** (`DialogTitle` / `SheetTitle` / `DrawerTitle`); use **`sr-only`** if visually hidden (shadcn pattern).
+8. **Format hints are persistent, not placeholders (SC 3.3.2 Labels or Instructions, 1.3.1).** Any field that expects a specific format — **date, time, phone, currency, ID pattern, GPA scale, URL, hours, unit-bearing numbers** — MUST show the format as **persistent helper text** via **`FormDescription`** (or the field's description slot). Placeholders disappear on focus and are unreliable for AT, so **MUST NOT** be the sole carrier of the format. Example: GPA → "Out of 4.0"; Date → "MM/DD/YYYY"; Phone → "+1 (555) 555-0100"; Student ID → "STU-YYYY-####". Pair with `inputMode`, `pattern`, or a picker primitive (e.g. `DatePickerField`) where applicable; never rely on a free-text date input.
+9. **Every icon that communicates information MUST have a text alternative** — not just icon-only buttons. Three cases (SC 1.1.1 Non-text Content, 3.3.2 Labels or Instructions, 2.4.6 Headings and Labels):
+
+   - **A. Decorative icon next to text that already names it** (e.g. `<i class="fa-light fa-calendar-days" aria-hidden /> 12/14/2025 – 12/20/2025`) → icon MUST be **`aria-hidden`**; MUST NOT add `aria-label` (screen readers would announce the meaning twice). No tooltip needed.
+   - **B. Informational icon standing alone** — a calendar glyph used to mean "date range", clock for "updated at", pin for "site", graduation cap for "student", trending arrow for direction, status dot, icon-only chart legend — MUST pair **`role="img"` + `aria-label`** (or `aria-labelledby` on a wrapping element) with a visible **`Tooltip`** so sighted users who don't recognise the glyph learn the meaning. The icon wrapper MUST be keyboard-focusable (`tabIndex={0}` on the `span[role="img"]`) so the tooltip opens on focus.
+   - **C. Interactive icon-only button/link** (close `×`, chevron, overflow `⋯`, sort direction, filter chip dismiss, copy, Ask Leo toggle, row actions) → MUST pair **`aria-label`** on the `<button>` with a wrapping **`Tooltip`**. `aria-label` alone is NOT enough — sighted mouse users and keyboard users rely on the tooltip to discover what a bare icon does.
+
+   In all three cases, the inner `<i>` / `<svg>` MUST be `aria-hidden`; the accessible name lives on the wrapping element. Tooltip text MUST match the accessible name. Narrow exception: a chevron inside a labelled composite (`Select`, `Combobox`) where the parent control already names the whole thing. See **§8.6 (Case A/B/C)** in `AGENTS.md` and the accessibility skill.
+10. **Keyboard shortcut hints inside buttons** MUST use **`<Kbd variant="bare">`** (no background, no border, inherits `currentColor` at 70%). The default `tile` variant is reserved for **tooltips** and **menu `shortcut=` slots**. Glue multi-key chords into one bare kbd (e.g. `<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. Reference: `Next` / `Back` buttons in `new-placement-form.tsx`; see `.cursor/rules/exxat-kbd-shortcuts.mdc`.
+
+After changing **views toolbar** or **tab** UIs, re-run **axe** (or equivalent) on **Placements** (or the affected page).
+
+**Charts:** Keyboard exploration uses **`ChartFigure`**; selected data points should have **visible** focus feedback — see skill **§ Charts (keyboard exploration)** and **`AGENTS.md` §4.3** (`chart-keyboard-selection`).
+
+## See also
+
+- **`apps/web/AGENTS.md`** §8 — accessibility in project context.
+- **`.cursor/rules/exxat-kbd-shortcuts.mdc`** — shortcuts paired with `Kbd` hints.
+- **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** — Data view chart keyboard parity.

package/consumer-extras/cursor-rules/exxat-board-cards.mdc

@@ -0,0 +1,26 @@
+---
+description: Exxat DS — board (kanban) cards; ListPageBoardCard, badges, primitives
+alwaysApply: true
+---
+
+# Exxat DS — board cards
+
+**Authoritative detail:** **`apps/web/AGENTS.md` §4.4** and **`.cursor/skills/exxat-board-cards/SKILL.md`**.
+
+## MUST
+
+1. **Shell** — Use **`ListPageBoardCard`** from **`components/data-views/list-page-board-card.tsx`** for product board cards (same **`Card` `size="sm"`** treatment as Placements).
+2. **Hierarchy** — **Title** (`ListPageBoardCardTitleRow`) → optional **avatar** (`ListPageBoardCardAvatar` on `trailing`) → **status row** (`ListPageBoardCardBadgeRow` + **`ListHubStatusBadge`** **`surface="board"`**) when the entity has status → **body** (`ListPageBoardCardBody`) with **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** (**`components/data-views/board-card-primitives.tsx`**).
+3. **Status** — **Placements** (**`PLACEMENT_STATUS_*`** + **`StatusBadge`** in **`placements-table-cells.tsx`**), **Team / Compliance / Question bank** (**`ListHubStatusBadge`** + entity maps): all labels/tints/icons live in **`lib/list-status-badges.ts`**. **`surface="table"`** in grid/list rows, **`surface="board"`** on kanban cards. Prefer semantic **`LIST_HUB_STATUS_TINT_*`**. **MUST NOT** use **`uppercase`** on those chips.
+4. **Simple column boards** — **`ListPageBoardTemplate`** + **`renderCard`**; compose **`ListPageBoardCard`** inside **`renderCard`**.
+
+## MUST NOT
+
+- Duplicate **`ListPageBoardCard`** with ad-hoc **`<button>`** + border/padding classes for the same hub pattern.
+- Show **status** only as plain text in the **body** when the hub uses **status** elsewhere — use the **badge row** + shared maps.
+
+## See also
+
+- **`apps/web/AGENTS.md` §4.4**, **§13** checklist
+- **`apps/web/docs/data-views-pattern.md`** — Board UI reuse
+- **`lib/initials-from-name.ts`** — owner initials when mock has no `initials` field

package/consumer-extras/cursor-rules/exxat-breadcrumbs-no-back.mdc

@@ -0,0 +1,21 @@
+---
+description: Do not duplicate parent navigation with a Back control when breadcrumbs exist
+globs: apps/web/**/*.tsx
+alwaysApply: false
+---
+
+# Exxat DS — breadcrumbs and back navigation
+
+## MUST NOT
+
+When a page uses **`SiteHeader`** with **`breadcrumbs`** (a visible trail such as Patterns → Library → current title), **do not** add a **“Back to …”** link or button in the page body that goes to the same parent as the breadcrumb segment. Breadcrumbs already provide hierarchy and one-click navigation up the tree.
+
+## MAY
+
+- Rely on **`SiteHeader`** breadcrumbs only for returning to parent routes.
+- Use a **single** explicit back affordance on flows that **omit** breadcrumbs by design (e.g. full-screen step, modal route) where product copy requires it.
+
+## See also
+
+- `components/site-header.tsx`
+- `components/templates/primary-page-template.tsx`

package/consumer-extras/cursor-rules/exxat-card-vs-list-rows.mdc

@@ -0,0 +1,21 @@
+---
+description: Exxat DS — when to use cards vs DataTable rows vs simple list rows.
+alwaysApply: true
+---
+
+# Exxat DS — cards vs rows vs lists
+
+## MUST
+
+1. **Dense, comparable records (10+)** — **`DataTable`** + **`ListPageTemplate`** + **`useTableState`** for primary hubs (**`exxat-data-tables.mdc`**).
+2. **Board / tiles / visual browse** — **`ListPageBoardCard`** (and related shells), **`ListPageViewFrame`** for non-table bodies (**`exxat-board-cards.mdc`**, **`exxat-list-page-view-shells.mdc`**).
+3. **One dataset** — Cards and tables read the **same** **`tableState.rows`**; no forked mock arrays (**`exxat-centralized-list-dataset.mdc`**).
+
+## MUST NOT
+
+- Replace a **primary data hub grid** with a **card wall** when users need column sort, filter chips, and export parity.
+- Introduce a **second table stack** for the same entity.
+
+## See also
+
+- **`docs/card-vs-rows-pattern.md`** · **`.cursor/skills/exxat-card-vs-list-rows/SKILL.md`**

package/consumer-extras/cursor-rules/exxat-centralized-list-dataset.mdc

@@ -0,0 +1,44 @@
+---
+description: Single source of truth for hub rows, KPIs, table properties, detail views, and shared view chrome — dataset + presentation consistency across DataListViewType surfaces
+alwaysApply: true
+---
+
+# Exxat DS — centralized list hub dataset + presentation
+
+**Authoritative detail:** **`apps/web/AGENTS.md` §4.1** and **§4.5** (connected views + view shells), **`docs/data-views-pattern.md`**, **`.cursor/rules/exxat-list-page-connected-views.mdc`**, and **`.cursor/rules/exxat-list-page-view-shells.mdc`**. This rule tightens **where data lives** and **where reusable view chrome lives** so **table, list, board, dashboard, folder, panel, tree, and inspectors** never drift.
+
+## Single dataset
+
+1. **Rows** — One typed collection per entity (**`lib/mock/<entity>.ts`** until API wiring). **MUST NOT** maintain a second parallel array (e.g. “tree only” or “panel only”) with overlapping IDs unless it is a **derived view** (computed from the same source via selectors).
+
+2. **`useTableState`** — One instance per tab table; **`tableState.rows`** is the **only** filtered/sorted row bag that **list / board / dashboard / folder / panel / tree** surfaces read. **MUST NOT** bypass filters by importing raw mock arrays into alternate views.
+
+3. **Detail / inspector / finder / split-panel bodies** — Resolve the active record by **`id`** (or stable key) against **`tableState.rows`** (or the same upstream state that feeds **`useTableState`**). **MUST NOT** hydrate inspector fields from ad-hoc literals when the row already exists on the dataset.
+
+4. **Columns & table “properties”** — Column defs **`accessorKey` / cell renderers** map to the **same** row interface as KPI helpers and board cards. **MUST NOT** introduce incompatible duplicate TypeScript shapes per view.
+
+5. **`TablePropertiesDrawer`** — Stays wired to the **`DataTable`** that owns **`useTableState`** (**§4.2**): **`currentView`**, **`onViewChange`**, column visibility/density — all reflect manipulation of the **same** underlying rows.
+
+6. **Labels / status / chips** — Prefer shared maps (**`lib/list-status-badges.ts`**, **`lib/data-list-view.ts`** tiles, entity-specific maps **next to** **`lib/mock/<entity>.ts`**). **MUST NOT** fork label strings or badge colors per view file.
+
+7. **KPIs & charts** — **`MetricItem`** / **`MetricInsight`** builders take **`tableState.rows`** (or equivalent filtered list). Same inputs as the grid after search/filters.
+
+## Centralized presentation (layout + components)
+
+8. **`ListPageViewFrame`** — Non-**`DataTable`** view bodies (**folder**, **panel**, icon grids, comparable dashboard sections) **MUST** use **`ListPageViewFrame`** (and exported max-width constants) instead of copy-pasted **`mx-*` / `max-w-*`** per hub (**`exxat-list-page-view-shells.mdc`**).
+
+9. **`components/data-views/`** — New **record-bearing** view layouts (**grids**, **OS folder**, **finder split**) **MUST** land as **generic** building blocks under **`data-views/`** with **`rows`**, **`getRowId`**, render props — hub **`TeamTable`** / **`QuestionBankTable`** **only** wires props and branch logic (**`AGENTS.md` §4.5**).
+
+10. **Hub client composition** — One **`*-client.tsx`** owns **`useTableState`**, passes **`tableState.rows`** into every **`viewType`** branch, and mounts **template** slots (**metrics**, **export**, **`beforeSiteHeader`**) — **MUST NOT** split the same hub across multiple clients with different row sources.
+
+## MUST NOT
+
+- Ship alternate mock datasets per **`DataListViewType`** for the same hub without documenting them as **computed derivatives** of one canonical list.
+- Duplicate entity fields in inspector-only types that contradict **`QuestionBankItem`** / **`Placement`** / etc.; extend the shared interface **once**.
+
+## See also
+
+- **`.cursor/skills/exxat-centralized-list-dataset/SKILL.md`** — workflow + checklist.
+- **`.cursor/rules/exxat-table-properties-drawer.mdc`** — **`currentView`** / **`onViewChange`**.
+- **`exxat-list-page-connected-views.mdc`** — toolbar + **`tableState.rows`**.
+- **`exxat-list-page-view-shells.mdc`** — **`ListPageViewFrame`** + **`data-views/`** extraction.

package/consumer-extras/cursor-rules/exxat-collaboration-access.mdc

@@ -0,0 +1,32 @@
+---
+description: Shared hubs — collaboration header, invite sheet, library access vs directory roles
+globs: apps/web/components/**/*.{tsx,ts},apps/web/lib/**/*.{tsx,ts}
+alwaysApply: false
+---
+
+# Exxat DS — collaboration & access
+
+**Authoritative detail:** **`apps/web/AGENTS.md` §4.7** and **`apps/web/docs/collaboration-access-pattern.md`**.
+
+## MUST
+
+1. **Shared hubs** — Use **`PageHeader`** **`variant="collaboration"`** with **`collaborators`** (`PageHeaderCollaborator[]`) and optional **`accessInfo`**.
+2. **Header chrome** — **Empty roster:** outline **Add collaborator** (`COLLABORATION_HEADER_ADD_LABEL` / **`addCollaboratorLabel`**) opens the invite sheet. **Non-empty roster:** face rail only; faces and **`+N`** open the same sheet via **`onCollaboratorsOpen`**.
+3. **Invite entry** — **⋯ More** → **Invite people** on the entity page header; opens **`InviteCollaboratorsDrawer`** (floating sheet, same family as **`ExportDrawer`**).
+4. **State** — Prefer **`CollaborationAccessFlow`** on hub **`*-client.tsx`**; otherwise own **`collaborators`** + **`inviteOpen`**. Successful invite updates **`collaborators`** so the header and sheet roster match.
+5. **Library access** — Labels and invite options from **`lib/collaborator-access.ts`**; trailing roster badge = access (Owner / Editor / Commenter / Viewer).
+6. **Directory roles** — Optional **`roles`** on **`PageHeaderCollaborator`** as **`Badge variant="outline"`** chips (Faculty, Program coordinator, Director) — **not** library access.
+7. **Roster layout** — One bordered list with row dividers; per row: **name**, **email**, role tags, access badge — **not** one card per person.
+8. **Invite field** — **`FieldGroup`** + **`Field`**; combined email + access row uses **`InputGroup`** + **`InputGroupInput`** + **`InputGroupAddon`** with shadcn **`Select`** (**`SelectGroup`** / **`SelectItem`**, **`position="popper"`**); persistent **`FieldDescription`** for email format; **no** **`toast()`** (**`exxat-no-toast.mdc`**).
+
+## MUST NOT
+
+- A second invite control **beside** a populated face rail.
+- Fork access enums/labels per hub — extend **`collaborator-access.ts`** once.
+- Use **`Select`** inside **`InputGroupAddon`** without **`InputGroupInput`** / **`SelectGroup`**; put email above name in the roster (order is **name → email → role tags**).
+
+## See also
+
+- **`exxat-page-vs-drawer.mdc`** — invite is a **sheet**, not a new route.
+- **`exxat-kbd-shortcuts.mdc`** — workflow **Cancel** / **Send invite** shortcuts on the sheet.
+- **`exxat-question-bank-hub-header.mdc`** — Question bank library: when URL is **folder-scoped**, **⋯ More** also includes **Customize folder** (hub client hosts **`QuestionBankNewFolderSheet`**).

package/consumer-extras/cursor-rules/exxat-command-menu.mdc

@@ -0,0 +1,22 @@
+---
+description: Exxat DS — global command palette (⌘K) as search + quick AI vs Ask Leo for long answers.
+alwaysApply: true
+---
+
+# Exxat DS — global command palette (`CommandMenu`)
+
+## Intent
+
+- **`CommandMenu`** (**⌘K** / **Ctrl+K**) is **global search** (routes, library, patterns, AI starters, optional row data such as placements / student names) — see **`apps/web/AGENTS.md` §7.1** and **`apps/web/docs/command-menu-pattern.md`**.
+- **Quick / lookup / short AI:** Prefer **results inside the palette** when the product can return compact answers or lightweight “research” without leaving the flow.
+- **Long or complex answers:** **Ask Leo** side panel (**⌘⌥K** / **Ctrl+Alt+K**)—not forced into the palette.
+
+## Implementation pointers
+
+- Shell: `apps/web/components/command-menu.tsx`; config **`buildCommandMenuConfig()`** in **`apps/web/lib/command-menu-config.ts`**; optional **`dataGroups`** from **`apps/web/lib/command-menu-search-data.ts`** (e.g. **`getCommandMenuSearchDataGroups()`**), wired in **`apps/web/app/(app)/layout.tsx`**. Keep domain mapping out of the shell.
+- Large indexes: set **`searchOnly: true`** on **`CommandMenuGroup`** so **`command-menu.tsx`** skips the group until the user types (avoids listing every row on open; cmdk shows all items when the search string is empty).
+
+## See also
+
+- **`apps/web/AGENTS.md` §7.1**
+- **`exxat-kbd-shortcuts.mdc`** (⌘K vs ⌘⌥K)

package/consumer-extras/cursor-rules/exxat-dashboard-view-charts.mdc

@@ -0,0 +1,53 @@
+---
+description: Data view dashboard — centralized charts, storage, keyboard parity with gallery, edit layout, coach marks
+alwaysApply: true
+---
+
+# Exxat DS — Data view dashboard (list hubs)
+
+**Authoritative detail:** **`apps/web/AGENTS.md` §4.3** and **`exxat-dashboard-view-charts`** (this rule).
+
+## Two dashboard surfaces (do not fork chart engines)
+
+| Surface | Entry | Shared building blocks |
+|--------|--------|-------------------------|
+| **Full-page dashboard** | `app/(app)/dashboard/page.tsx` | `DashboardTabs`, `ChartsOverview` / gallery demos in `charts-overview.tsx` |
+| **Data tab** on Placements / Team / Compliance | `PlacementsTable`, `TeamTable`, `ComplianceTable` → `*DashboardChartsSection` | `ChartFigure`, `ChartCard`, `useChartVariant()`, `data-view-dashboard-charts*.tsx` |
+
+**MUST NOT** duplicate “another” chart system for Data view — extend **`charts-overview`** patterns and **`lib/chart-keyboard-selection`**.
+
+## MUST — accessibility & data
+
+1. **`ChartFigure`** + **`ChartDataTable`** (`sr-only`) for every chart on the Data dashboard — same as **`charts-overview.tsx`**.
+2. **`ChartCard`** wraps chart content; **`KeyMetrics`** **`variant="card"`** for the **`key-metrics`** tile; KPI count **1–4** persisted in layout.
+
+## MUST — keyboard selection (parity with `/dashboard` gallery)
+
+- Import **`CHART_KBD_ACTIVE_BAR`** and **`CHART_KBD_ACTIVE_PIE_SHAPE`** from **`@/lib/chart-keyboard-selection`**.
+- **Bar** series: **`activeBar={CHART_KBD_ACTIVE_BAR}`** + **`activeIndex={activeIndex ?? undefined}`** (and **`Cell`** only for per-bar **fill**, not opacity-only selection).
+- **Pie / donut:** **`activeShape={CHART_KBD_ACTIVE_PIE_SHAPE}`** + **`activeIndex`** + slice **`stroke`** / **`strokeWidth`** consistent with gallery donuts.
+- **MUST NOT** use **`fillOpacity` dimming alone** on **`Cell`** as the sole “selected” state for keyboard exploration.
+
+## MUST — customisation UX
+
+- **Edit layout** control: **`aria-label="Edit dashboard layout"`** (toolbar pen-ruler). Coach marks may target **`[aria-label='Edit dashboard layout']`**.
+- On-canvas: drag reorder, remove, width (half / full), chart type, add/remove cards, reset. **No** separate Sheet for layout.
+- While **`layoutEditMode`**: hide **`DataTableToolbar`** (search / filters / Properties row); **Done** / **Cancel** on canvas.
+
+## MUST — persistence (centralized)
+
+- **One bundle:** **`lib/data-view-dashboard-storage.ts`** — key **`exxat-ds:data-view-dashboards:v1`**, scopes **`placements` | `team` | `compliance`**.
+- Placements helpers: **`loadDashboardLayout`** / **`saveDashboardLayout`** in **`data-view-dashboard-charts.tsx`** (wrap storage API).
+- **MUST NOT** introduce parallel **`localStorage`** keys for the same **`DashboardLayout`** shape without updating the storage module.
+
+## SHOULD — coach marks
+
+- Register **customize dashboard** flows in **`lib/coach-mark-registry.ts`**; shared copy in **`lib/dashboard-customize-coach-mark.ts`**.
+- Use **`useCoachMark`** **`enabled`** / **`dependsOnDismissedFlowId`** when a tour only applies on **dashboard** view or after another flow (**`COACH_MARK_FLOW_COMPLETED_EVENT`**).
+
+## Reference files
+
+- `components/data-view-dashboard-charts.tsx` (Placements)
+- `components/data-view-dashboard-charts-team.tsx`, `data-view-dashboard-charts-compliance.tsx`
+- `components/placements-table.tsx` — dashboard tab body wires `PlacementsDashboardChartsSection` + layout-edit toolbar inline (no separate `DashboardShell` component)
+- `lib/chart-keyboard-selection.ts`, `lib/data-view-dashboard-storage.ts`, `lib/dashboard-customize-coach-mark.ts`