@exxatdesignux/ui 0.3.0 → 0.4.1

package/README.md

@@ -0,0 +1,138 @@
+# @exxatdesignux/ui
+
+The Exxat Design System — a Next.js + React 19 + Tailwind v4 component
+library plus the full hub-page stack (`ListPageTemplate`, `DataTable`,
+`HubTable`, `TablePropertiesDrawer`, `KeyMetrics`, `PageHeader`, board
+cards, charts, …) wrapped in one publishable package.
+
+## 60-second start
+
+Spin up a brand-new app pre-wired with the DS:
+
+```bash
+pnpm create exxat-app my-app
+cd my-app
+pnpm dev
+```
+
+Works with every modern package manager — the scaffolder auto-detects
+the runner and uses the matching install:
+
+```bash
+npm  create exxat-app my-app
+yarn create exxat-app my-app
+bun  create exxat-app my-app
+```
+
+The scaffolder ships a complete Next.js 16 starter: the reference
+**Library** hub at `/library/all`, the `/columns` cell-catalog showcase,
+typed mock data, the full Cursor skill + pattern doc set under
+`cursor-rules/`, `cursor-skills/`, `patterns/`, and `handbook/`.
+
+## Adding to an existing Next.js app
+
+If you already have a Next 15/16 app and just want the components:
+
+```bash
+pnpm add @exxatdesignux/ui
+```
+
+Then in your global CSS (e.g. `app/globals.css`):
+
+```css
+@import "@exxatdesignux/ui/globals.css";
+```
+
+And import primitives or full patterns from the umbrella or a subpath:
+
+```tsx
+import { DataTable, HubTable, ListPageTemplate, KeyMetrics } from "@exxatdesignux/ui"
+import { Button } from "@exxatdesignux/ui/components/button"
+import { useTableState } from "@exxatdesignux/ui/components/data-table/use-table-state"
+```
+
+Mount `KeyMetricsProvider` near the root if you want the "Ask Leo about
+these metrics" CTA wired to your AI surface (otherwise the strip just
+hides that button automatically).
+
+## Refresh Cursor skills + pattern docs in any consumer
+
+The package ships a parallel set of binding rules, skills, and pattern
+docs so AI agents in your own repo can read the same guidance the source
+repo uses. To install or refresh them in your repo:
+
+```bash
+pnpm dlx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+```
+
+This copies `cursor-rules/`, `cursor-skills/`, `patterns/`, and
+`handbook/` into your repo root. The next time Cursor opens, every
+binding rule + skill is live.
+
+## What's inside
+
+- **Primitives** (`@exxatdesignux/ui/components/<name>`) — Button, Input,
+  Select, Dialog, AlertDialog, Sheet, Drawer, Popover, DropdownMenu,
+  ContextMenu, Tabs, Accordion, Tooltip, Toast-free Banner, ScrollArea,
+  Slider, HoverCard, Avatar, Badge, StatusBadge, Calendar, Kbd, …
+- **Hub stack** — `DataTable<TRow>`, `useTableState<TRow>`,
+  `TablePropertiesDrawer`, `HubTable<TRow>`, `ListPageTemplate`,
+  `PageHeader`, `KeyMetrics`, `ListPageBoardCard`,
+  `ListPageBoardTemplate`, `DataRowList`, `FinderPanelView`,
+  `FolderGridView`, `OutlineTreeMenu`.
+- **Data-list registry** — `DataListViewType`, `DATA_LIST_VIEW_TILES`,
+  `dataListViewIcon`, `dataListViewAddShortcut`, `usesDataTableComponent`,
+  `usesDashboardSurface`.
+- **Templates** — `ListPageTemplate`, `NestedSecondaryPanelShell`,
+  `DedicatedSearchLandingTemplate`, `DedicatedSearchResultsTemplate`.
+- **Tokens** — `tokens/hooks-index.json` (197 tokens · 42 namespaces)
+  feeds the workspace ESLint plugin's `no-deprecated-tokens` rule.
+- **Tailwind v4 token bridge** — `globals.css` imports the L0
+  `--exxat-color-*` / `--exxat-radius-*` / `--exxat-spacing-*` family
+  and wires Tailwind shorthand (`bg-surface-1`, `text-ink-1`,
+  `rounded-2`, …) via `@theme inline`.
+
+## CLI commands
+
+After `pnpm add @exxatdesignux/ui` (or globally `npm i -g @exxatdesignux/ui`):
+
+```bash
+# In an empty directory (or new sub-folder), scaffold an app:
+npx --package=@exxatdesignux/ui create-exxat-app my-app
+
+# Sync Cursor skills + binding rules + pattern docs into your repo:
+npx --package=@exxatdesignux/ui exxat-ui sync-extras
+```
+
+The standalone [`create-exxat-app`](https://www.npmjs.com/package/create-exxat-app)
+package wraps the first command so `<pm> create exxat-app …` resolves
+natively.
+
+## Docs
+
+- Design-system **HANDBOOK** — read-this-first orientation, the 6-step
+  "how to build a hub" walkthrough, the §13 PR checklist.
+- **Blueprints** — framework-agnostic specs for each major composition
+  (`PageHeader`, `DataTable`, `ListPageTemplate`, `BoardCard`,
+  `KeyMetrics`, …).
+- **Component selection guide** — top-of-funnel decision tree for
+  picking the right composition.
+- **Token taxonomy** — naming + deprecation policy for every CSS
+  custom property the DS ships.
+
+The full doc set is mirrored under `handbook/` and `patterns/` in this
+package; `exxat-ui sync-extras` drops them into your repo so they sit
+alongside your source.
+
+## Compatibility
+
+| Peer | Range |
+| --- | --- |
+| React | `>=19.0.0` |
+| Next.js | `>=15.0.0` (App Router) |
+| Tailwind CSS | `>=4.0.0` |
+| Node | `>=22.0.0` (build / dev) |
+
+## License
+
+UNLICENSED — proprietary to Exxat Design.

package/bin/init.mjs

@@ -1,43 +1,146 @@
 #!/usr/bin/env node
-import { cpSync, readFileSync, readdirSync, writeFileSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-import { execSync } from 'child_process'
+/**
+ * Scaffold a new Exxat DS app from the bundled template.
+ *
+ * Usage:
+ *   npx create-exxat-app                 # scaffold into current directory
+ *   npx create-exxat-app my-app          # scaffold into ./my-app (created if missing)
+ *   npx create-exxat-app . --force       # overwrite-merge into current directory
+ *   npx create-exxat-app my-app --no-install   # skip the package install step
+ *
+ * Also runs as `npx --package=@exxatdesignux/ui create-exxat-app …` and as
+ * `pnpm create exxat-app …` when invoked via the standalone create-exxat-app
+ * discovery shim.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { resolve, dirname, basename, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { execSync } from "node:child_process"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const templateDir = resolve(__dirname, '../template')
-const selfPkgPath = resolve(__dirname, '../package.json')
-const targetDir = process.cwd()
+const templateDir = resolve(__dirname, "../template")
+const selfPkgPath = resolve(__dirname, "../package.json")
+const selfPkg = JSON.parse(readFileSync(selfPkgPath, "utf8"))
 
-const files = readdirSync(targetDir)
-const isEmpty = files.length === 0 || (files.length === 1 && files[0] === '.git')
+const args = process.argv.slice(2)
+const flags = new Set(args.filter((a) => a.startsWith("--")))
+const positional = args.filter((a) => !a.startsWith("--"))
+const targetArg = positional[0] ?? "."
+const targetDir = resolve(process.cwd(), targetArg)
+const projectName = targetArg === "." ? basename(targetDir) : targetArg
+const force = flags.has("--force")
+const skipInstall = flags.has("--no-install") || flags.has("--skip-install")
 
-if (!isEmpty) {
-  console.error('❌  Target directory is not empty. Run this in a new empty folder.')
+if (flags.has("--help") || flags.has("-h")) {
+  console.log(`
+create-exxat-app — scaffold a Next.js app on @exxatdesignux/ui
+
+Usage:
+  create-exxat-app [target-directory] [options]
+
+Arguments:
+  target-directory    Where to create the app (default: ".")
+                      A relative or absolute path. Created if it does not exist.
+
+Options:
+  --force             Allow scaffolding into a non-empty directory (existing
+                      files are NOT overwritten unless template ships the
+                      same path).
+  --no-install        Skip the dependency install step.
+  -h, --help          Show this message.
+
+Examples:
+  create-exxat-app my-app
+  create-exxat-app .
+  create-exxat-app ../sandbox --force --no-install
+`)
+  process.exit(0)
+}
+
+if (!existsSync(targetDir)) {
+  mkdirSync(targetDir, { recursive: true })
+  console.log(`📁  Created ${projectName}/`)
+}
+
+const targetStat = statSync(targetDir)
+if (!targetStat.isDirectory()) {
+  console.error(`❌  Target ${targetDir} exists but is not a directory.`)
   process.exit(1)
 }
 
-console.log('📦  Copying Exxat DS starter app...')
+const existing = readdirSync(targetDir)
+const ignorable = new Set([".git", ".gitignore", ".DS_Store"])
+const blockers = existing.filter((name) => !ignorable.has(name))
+
+if (blockers.length > 0 && !force) {
+  console.error(`❌  Target directory is not empty (${targetDir}).`)
+  console.error("")
+  console.error("    Found:")
+  for (const name of blockers.slice(0, 8)) console.error(`      - ${name}`)
+  if (blockers.length > 8) console.error(`      … and ${blockers.length - 8} more`)
+  console.error("")
+  console.error("    Options:")
+  console.error(`      1. Scaffold into a new folder:   create-exxat-app my-app`)
+  console.error(`      2. Allow merging existing files: create-exxat-app . --force`)
+  console.error("")
+  process.exit(1)
+}
+
+console.log(`📦  Copying Exxat DS starter app into ${projectName}/ …`)
 cpSync(templateDir, targetDir, { recursive: true })
 
-/** Pin DS to this CLI tarball version so `npm install` does not resolve a stale `latest` from cache. */
-const selfVersion = JSON.parse(readFileSync(selfPkgPath, 'utf8')).version
-const targetPkgPath = resolve(targetDir, 'package.json')
-const targetPkg = JSON.parse(readFileSync(targetPkgPath, 'utf8'))
-if (targetPkg.dependencies?.['@exxatdesignux/ui']) {
-  targetPkg.dependencies['@exxatdesignux/ui'] = `^${selfVersion}`
-  writeFileSync(targetPkgPath, `${JSON.stringify(targetPkg, null, 2)}\n`)
-  console.log(`📌  Pinned @exxatdesignux/ui to ^${selfVersion} (matches this scaffold).`)
+// Pin DS to this CLI's published version so `latest` cache drift cannot
+// trick the consumer into installing an older dist.
+const targetPkgPath = resolve(targetDir, "package.json")
+const targetPkg = JSON.parse(readFileSync(targetPkgPath, "utf8"))
+if (targetPkg.dependencies?.["@exxatdesignux/ui"]) {
+  targetPkg.dependencies["@exxatdesignux/ui"] = `^${selfPkg.version}`
 }
+// Name the project after the target dir for nicer dev-server / process titles.
+targetPkg.name = projectName.replace(/[^a-z0-9-_]/gi, "-").toLowerCase() || "my-exxat-app"
+writeFileSync(targetPkgPath, `${JSON.stringify(targetPkg, null, 2)}\n`)
+console.log(`📌  Pinned @exxatdesignux/ui to ^${selfPkg.version} and named the project "${targetPkg.name}".`)
 
-console.log('📥  Installing dependencies...')
-execSync('npm install', { stdio: 'inherit', cwd: targetDir })
-
-console.log('')
-console.log('✅  Done! Your Exxat DS app is ready.')
-console.log('')
-console.log('   npm run dev   → start dev server')
-console.log('')
-console.log('   Optional — refresh Cursor skills + pattern docs from the same package:')
-console.log(`   npx --package=@exxatdesignux/ui@${selfVersion} exxat-ui sync-extras`)
-console.log('')
+const pm = detectPackageManager()
+if (skipInstall) {
+  console.log(`⏭   Skipped install (--no-install).`)
+} else {
+  console.log(`📥  Installing dependencies with ${pm.label} …`)
+  try {
+    execSync(pm.installCmd, { stdio: "inherit", cwd: targetDir })
+  } catch (err) {
+    console.error("")
+    console.error(`❌  ${pm.label} install failed. You can retry manually:`)
+    console.error(`     cd ${projectName} && ${pm.installCmd}`)
+    process.exit(1)
+  }
+}
+
+console.log("")
+console.log(`✅  Done! Your Exxat DS app is ready in ./${projectName}/`)
+console.log("")
+console.log(`   cd ${projectName}`)
+console.log(`   ${pm.runCmd} dev     # start dev server`)
+console.log("")
+console.log("   Optional — refresh Cursor skills + pattern docs:")
+console.log(`     ${pm.dlxCmd} --package=@exxatdesignux/ui@${selfPkg.version} exxat-ui sync-extras`)
+console.log("")
+
+/**
+ * Detect the package manager that invoked us — npm_config_user_agent is set
+ * by every modern package-runner (npm, pnpm, yarn, bun) and looks like
+ * "pnpm/10.33.0 npm/? node/v22.0.0 darwin arm64". We fall back to npm.
+ */
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? ""
+  if (ua.startsWith("pnpm")) {
+    return { label: "pnpm", installCmd: "pnpm install", runCmd: "pnpm", dlxCmd: "pnpm dlx" }
+  }
+  if (ua.startsWith("yarn")) {
+    return { label: "yarn", installCmd: "yarn install", runCmd: "yarn", dlxCmd: "yarn dlx" }
+  }
+  if (ua.startsWith("bun")) {
+    return { label: "bun", installCmd: "bun install", runCmd: "bun", dlxCmd: "bunx" }
+  }
+  return { label: "npm", installCmd: "npm install", runCmd: "npm run", dlxCmd: "npx" }
+}

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

@@ -11,7 +11,7 @@ alwaysApply: true
 
 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.
+3. **Status** — **Placements** (**`PLACEMENT_STATUS_*`** + **`StatusBadge`** in **`placements-table-cells.tsx`**), **Team / Compliance / Library** (**`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

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

@@ -27,14 +27,14 @@ alwaysApply: true
 
 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**).
+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`** / **`LibraryTable`** **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**.
+- Duplicate entity fields in inspector-only types that contradict **`LibraryItem`** / **`Placement`** / etc.; extend the shared interface **once**.
 
 ## See also
 

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

@@ -29,4 +29,4 @@ alwaysApply: false
 
 - **`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`**).
+- **`exxat-library-hub-header.mdc`** — Library library: when URL is **folder-scoped**, **⋯ More** also includes **Customize folder** (hub client hosts **`LibraryNewFolderSheet`**).

package/consumer-extras/cursor-rules/exxat-data-tables.mdc

@@ -16,6 +16,7 @@ For **any app screen that shows a browsable, filterable grid of records** (lists
 5. **Filters:** Configure per-column `filter:` blocks in `ColumnDef` (text / select / date / number) — `HubTable` turns those into chips automatically via `columnsToFilterFields`. **MUST NOT** ship one-off filter inputs above the table that duplicate this.
 6. **Table properties:** Always reachable. `HubTable` mounts `TablePropertiesDrawerButton` in `toolbarSlot`; on **`ListPageTemplate`** pages with **table / list / board / dashboard** tabs it **MUST** also receive **`currentView`** and **`onViewChange`** (see **`apps/web/AGENTS.md` §4.2** and **`.cursor/rules/exxat-table-properties-drawer.mdc`**) so Properties matches the selected view.
 7. **Dropdown menus:** `DropdownMenuContent` uses the shared **`@exxatdesignux/ui`** default (**intrinsic `w-max`**, **`min-w-52`**, capped **`max-w`**) for view settings, row ⋯, column menus, and filter pickers — **pure CSS**, no **`ResizeObserver`**. Override only for deliberate narrow/wide rails (e.g. pagination **`w-20`**, account trigger-width, school switcher **`!w-max min-w-72 …`**). See **`docs/data-views-pattern.md`** (“Dropdown menus”).
+8. **Cell renderers MUST come from `@/components/data-views` (`table-cells.tsx`).** The DS ships **`ProgressCell`**, **`CurrencyCell`**, **`NumericCell`**, **`RatingCell`**, **`SignalBarsCell`**, **`BooleanToggleCell`**, **`AttachmentCountCell`**, **`ExternalLinkCell`**, **`RelativeTimeCell`**, **`PeopleAvatarRailCell`**, **`PillCell`**, **`TagListCell`**, and a generic **`RowActionsCell<TRow>`**. A `ColumnDef['cell']` for these patterns is a **one-liner** that calls the named cell. **MUST NOT** inline `Intl.NumberFormat`, raw `<a target="_blank">`, `[1,2,3,4,5].map(s => …)` star loops, paperclip + count chips, custom face-rail `AvatarGroup`s, or per-hub `DropdownMenu` overflow menus inside `cell:` — those are signals you're re-deriving a shipped primitive. Catalog: `apps/web/components/columns-showcase.tsx` (`/columns`). Skill: `.cursor/skills/exxat-token-economy/SKILL.md` §3.
 
 **Reference implementations:**
 
@@ -30,6 +31,7 @@ For **any app screen that shows a browsable, filterable grid of records** (lists
 - Do **not** build product list pages with `@/components/ui/table` alone, raw `<table>` markup, or third-party data grids.
 - Do **not** mount raw `<DataTable>` inside `ListPageTemplate.renderContent` — use `HubTable`. Raw `<DataTable>` does not ship the Properties drawer or filter chips; users lose discoverability.
 - Do **not** introduce a second “table component” pattern for the same product surfaces (splitting search/filters/properties across incompatible implementations).
+- Do **not** inline-implement progress bars, currency formatters, rating stars, relative-time helpers, attachment chips, external-link wrappers, face rails, type pills, tag lists, or row-action dropdowns inside a `ColumnDef['cell']`. Import the named cell from `@/components/data-views` instead. New hub with novel cell needs MUST extend `table-cells.tsx` (and ship the catalog entry in `columns-showcase.tsx`), not fork inline JSX.
 
 ## Exceptions
 

package/consumer-extras/cursor-rules/exxat-dedicated-search-surfaces.mdc

@@ -18,7 +18,7 @@ Shared building blocks use **generic** `DedicatedSearch*` names under `component
 
 ## MUST NOT
 
-- Introduce parallel `*QuestionBankSearchLanding*` (or similar) components for another entity — extend the generic layer and compose in the hub client.
+- Introduce parallel `*LibrarySearchLanding*` (or similar) components for another entity — extend the generic layer and compose in the hub client.
 
 ## See also
 

package/consumer-extras/cursor-rules/exxat-ds-agents.mdc

@@ -26,7 +26,7 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 11. **Centralized hub dataset + presentation** — **`apps/web/AGENTS.md` §4.1** / **§4.5** + **`.cursor/rules/exxat-centralized-list-dataset.mdc`** + **`.cursor/skills/exxat-centralized-list-dataset/SKILL.md`** — one **`useTableState`** row bag for **all** views + **`TablePropertiesDrawer`**; **`ListPageViewFrame`** + **`data-views/`** for shared chrome; **no** parallel mock arrays per **`DataListViewType`**.
 12. **Font Awesome (product icons)** — **`.cursor/rules/exxat-fontawesome-icons.mdc`** — Kit in **`app/layout.tsx`**, **`fa-light` / `fa-solid`**, subset audit, **`aria-hidden`** on decorative **`<i>`**; pair with **`exxat-accessibility.mdc`** for icon-only controls.
 13. **Monospace system IDs** — **`apps/web/AGENTS.md` §1 (item 9)** + **`.cursor/rules/exxat-mono-ids.mdc`** + **`.cursor/skills/exxat-mono-ids/SKILL.md`** — **`font-mono tabular-nums`** on question/record keys; mono **only** the ID token in mixed lines.
-14. **Primary nav → secondary panel** (Question bank) — **`apps/web/AGENTS.md` §4.6** + **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`** — **`secondaryPanel`** + **`PANELS`** + **`useAutoPanel`**; **`--secondary-panel-bg`** brand elevation (**`apps/web/docs/shell-surface-elevation-pattern.md`**); **folder URL scope** → **`exxat-question-bank-hub-header.mdc`** + **`apps/web/docs/question-bank-hub-header-pattern.md`**.
+14. **Primary nav → secondary panel** (Library) — **`apps/web/AGENTS.md` §4.6** + **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`** — **`secondaryPanel`** + **`PANELS`** + **`useAutoPanel`**; **`--secondary-panel-bg`** brand elevation (**`apps/web/docs/shell-surface-elevation-pattern.md`**); **folder URL scope** → **`exxat-library-hub-header.mdc`** + **`apps/web/docs/library-hub-header-pattern.md`**.
 15. **Collaboration & access** (shared hubs) — **`apps/web/AGENTS.md` §4.7** + **`.cursor/rules/exxat-collaboration-access.mdc`** + **`.cursor/skills/exxat-collaboration-access/SKILL.md`** — face rail, **`InviteCollaboratorsDrawer`**, **`lib/collaborator-access.ts`**.
 16. **Dedicated search** (landing vs results, `DedicatedSearch*`) — **`apps/web/AGENTS.md` §4.8** + **`.cursor/rules/exxat-dedicated-search-surfaces.mdc`** + **`.cursor/skills/exxat-dedicated-search-surfaces/SKILL.md`**.
 17. **No toast** → **`apps/web/AGENTS.md` §6.5** + **`exxat-no-toast.mdc`** — do not use **`toast()`** / Sonner / snackbars for product messaging; use banners, inline status, or dialogs.
@@ -50,7 +50,7 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 - **`apps/web/docs/blueprints/`** — framework-agnostic specs (start: `page-header.md`, `data-table.md`).
 - **`apps/web/docs/migrations/`** — token rename + removal history.
 - **`packages/ui/tokens/hooks-index.json`** — machine-readable token index (regenerate via `pnpm --filter @exxatdesignux/ui tokens:index`).
-- `.cursor/rules/exxat-data-tables.mdc`, `exxat-list-page-connected-views.mdc`, **`exxat-centralized-list-dataset.mdc`**, **`exxat-list-page-view-shells.mdc`**, **`exxat-fontawesome-icons.mdc`**, **`exxat-mono-ids.mdc`**, **`exxat-primary-nav-secondary-panel.mdc`**, **`exxat-question-bank-hub-header.mdc`**, **`exxat-collaboration-access.mdc`**, **`exxat-dedicated-search-surfaces.mdc`**, **`exxat-kpi-trends.mdc`**, **`exxat-kpi-flat-band.mdc`**, **`exxat-drawer-vs-dialog.mdc`**, **`exxat-card-vs-list-rows.mdc`**, **`exxat-kpi-max-four.mdc`**, **`exxat-reuse-before-custom.mdc`**, `exxat-table-properties-drawer.mdc`, **`exxat-board-cards.mdc`**, **`exxat-page-vs-drawer.mdc`**, **`exxat-no-toast.mdc`**, **`exxat-command-menu.mdc`**, `exxat-kbd-shortcuts.mdc`, `exxat-accessibility.mdc` at repo root; **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** for Data tab charts.
+- `.cursor/rules/exxat-data-tables.mdc`, `exxat-list-page-connected-views.mdc`, **`exxat-centralized-list-dataset.mdc`**, **`exxat-list-page-view-shells.mdc`**, **`exxat-fontawesome-icons.mdc`**, **`exxat-mono-ids.mdc`**, **`exxat-primary-nav-secondary-panel.mdc`**, **`exxat-library-hub-header.mdc`**, **`exxat-collaboration-access.mdc`**, **`exxat-dedicated-search-surfaces.mdc`**, **`exxat-kpi-trends.mdc`**, **`exxat-kpi-flat-band.mdc`**, **`exxat-drawer-vs-dialog.mdc`**, **`exxat-card-vs-list-rows.mdc`**, **`exxat-kpi-max-four.mdc`**, **`exxat-reuse-before-custom.mdc`**, `exxat-table-properties-drawer.mdc`, **`exxat-board-cards.mdc`**, **`exxat-page-vs-drawer.mdc`**, **`exxat-no-toast.mdc`**, **`exxat-command-menu.mdc`**, `exxat-kbd-shortcuts.mdc`, `exxat-accessibility.mdc` at repo root; **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** for Data tab charts.
 - **`apps/web/docs/kpi-flat-band-pattern.md`**, **`apps/web/docs/shell-surface-elevation-pattern.md`** — flat KPI strip + sidebar/secondary/page OKLCH stack.
-- **`apps/web/docs/question-bank-hub-header-pattern.md`** — folder-scoped question bank header **Customize folder**.
+- **`apps/web/docs/library-hub-header-pattern.md`** — folder-scoped library header **Customize folder**.
 - **`apps/web/docs/collaboration-access-pattern.md`** — shared hub face rail + invite sheet.

package/consumer-extras/cursor-rules/exxat-library-hub-header.mdc

@@ -0,0 +1,28 @@
+---
+description: Library library — folder-scoped hub header More menu must expose Customize folder; sheet on hub client
+globs: apps/web/components/library-*.tsx, packages/ui/template/components/library-*.tsx
+alwaysApply: false
+---
+
+# Exxat DS — Library hub header (folder scope)
+
+When the library library URL is **scoped to a folder** (`parseLibraryNav` → **`scope === "folder"`** and **`folderId`** set), users are effectively on a **“folder page”**: the hub title matches that folder, and **global** actions belong in the **`LibraryPageHeader`** **⋯ More** menu — not only on per-row or per-tile overflow menus inside a single view tab.
+
+**Pattern doc:** **`apps/web/docs/library-hub-header-pattern.md`**. **Handbook:** **`apps/web/AGENTS.md` §4.6** (folder-scoped hub chrome).
+
+## MUST
+
+1. **`LibraryPageHeader`** — When **`navState.scope === "folder"`** and **`navState.folderId`** resolves to a row in **`folders`**, pass **`onCustomizeFolder`** so **⋯ More** includes **Customize folder** ( **`fa-wand-magic-sparkles`** + label **Customize folder** ), placed after **Invite people** (collaboration variant) and before **Export**.
+2. **Hub client** — Mount **`LibraryNewFolderSheet`** on the **hub client** (e.g. **`LibraryClient`**) next to **`ListPageTemplate`**, driven by local **`open` / `customizingFolder`** state opened from **`onCustomizeFolder`**. **MUST NOT** rely on **`LibraryTable`** alone to host the sheet when some view branches (**table**, **list**, **board**, **dashboard**) do not render that sheet — users would lose **Customize folder** on those tabs.
+3. **`onCreated`** — On save, **`setFolders`** (or equivalent) **maps** the scoped folder **`id`** to updated **`name`**, **`icon`**, **`colorKey`** — same contract as **`LibraryTable`** panel/tree customize handlers.
+
+## MUST NOT
+
+- Omit **Customize folder** from the header **⋯** when the URL is folder-scoped, expecting users to find it only on secondary-nav tree rows or OS-folder tiles.
+- Mount **only** one customize sheet inside **`LibraryTable`** without a **client-level** sheet when the hub uses **`ListPageTemplate`** view tabs that omit that table subtree.
+
+## See also
+
+- **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`** — URL scope + secondary panel.
+- **`.cursor/rules/exxat-collaboration-access.mdc`** — **`variant="collaboration"`** header + **⋯** invite pattern.
+- **`lib/library-nav.ts`** — **`parseLibraryNav`**, **`LibraryNavState`**.

package/consumer-extras/cursor-rules/exxat-mono-ids.mdc

@@ -16,7 +16,7 @@ Use this when rendering **system identifiers** — values a user copies, searche
 
 ## SHOULD
 
-- Match existing hubs: **`question-bank-table.tsx`**, **`question-bank-list-view.tsx`**, **`new-question-composer.tsx`** (header subtitle), **`sites-table.tsx`** (`row.id`).
+- Match existing hubs: **`library-table.tsx`**, **`library-list-view.tsx`**, **`new-library-item-form.tsx`** (header subtitle), **`sites-table.tsx`** (`row.id`).
 - Prefer **`truncate`** / **`min-w-0`** on mono IDs in tight layouts so long tokens do not blow out columns.
 
 ## MUST NOT

package/consumer-extras/cursor-rules/exxat-person-identity-display.mdc

@@ -24,7 +24,7 @@ Dense or width-constrained surfaces **MUST NOT** squeeze email if it harms scana
 ## Table / list / drawer / inspector
 
 - **Dedicated person column** or **profile / invite / access** surfaces — show **avatar + name + email** (stacked or name with email below), consistent with **`InviteCollaboratorsDrawer`** and **`PageHeader`** collaboration variant.
-- **Example:** `QuestionBankTable` **Author** — `AvatarInitials`, **primary name** (`text-sm font-medium`), **muted `text-xs` email** with optional `mailto:` (row click does not navigate when the link is used).
+- **Example:** `LibraryTable` **Author** — `AvatarInitials`, **primary name** (`text-sm font-medium`), **muted `text-xs` email** with optional `mailto:` (row click does not navigate when the link is used).
 
 ## Avatar rows — **never overlapping**
 

package/consumer-extras/cursor-rules/exxat-primary-nav-secondary-panel.mdc

@@ -1,5 +1,5 @@
 ---
-description: Primary sidebar item opens nested SecondaryPanel (Question bank pattern)
+description: Primary sidebar item opens nested SecondaryPanel (Library pattern)
 globs: apps/web/components/**/*.tsx
 alwaysApply: false
 ---
@@ -8,13 +8,13 @@ alwaysApply: false
 
 Some hubs expose **scoped navigation** (All / My / tree / filters) in a **nested panel** between the **icon rail** and **main content** — not as **primary nav child rows**.
 
-**Reference:** **Question bank** — **`lib/mock/navigation.tsx`** (`secondaryPanel: "question-bank"`), **`components/app-sidebar.tsx`**, **`components/secondary-panel.tsx`**, **`components/question-bank-panel-activator.tsx`**, **`components/question-bank-secondary-nav.tsx`**, **`lib/question-bank-nav.ts`** (URL scope).
+**Reference:** **Library** — **`lib/mock/navigation.tsx`** (`secondaryPanel: "library"`), **`components/app-sidebar.tsx`**, **`components/secondary-panel.tsx`**, **`components/library-panel-activator.tsx`**, **`components/library-secondary-nav.tsx`**, **`lib/library-nav.ts`** (URL scope).
 
 ## MUST (wiring)
 
-1. **`NavLinkItem`** — On the **primary** row that should drive the panel, set **`secondaryPanel`** to a **stable string id** (e.g. **`"question-bank"`**). Keep **`url`** pointing at the **hub route**.
+1. **`NavLinkItem`** — On the **primary** row that should drive the panel, set **`secondaryPanel`** to a **stable string id** (e.g. **`"library"`**). Keep **`url`** pointing at the **hub route**.
 2. **`SecondaryPanel` registry** — In **`components/secondary-panel.tsx`**, add **`PANELS[id]`** → component that renders **panel chrome** (title, optional search) + **your secondary nav** list. **MUST** keep ids in sync with **`NAV_PRIMARY`**.
-3. **Auto-open on route** — The hub **`client`** (or layout slot) **MUST** mount **`*PanelActivator`** that calls **`useAutoPanel(id)`** with the **same id**, so deep links and first visit open the panel while the route is mounted (e.g. **`QuestionBankPanelActivator`** + **`beforeSiteHeader`** on **`QuestionBankClient`**).
+3. **Auto-open on route** — The hub **`client`** (or layout slot) **MUST** mount **`*PanelActivator`** that calls **`useAutoPanel(id)`** with the **same id**, so deep links and first visit open the panel while the route is mounted (e.g. **`LibraryPanelActivator`** + **`beforeSiteHeader`** on **`LibraryClient`**).
 4. **Same-route reopen** — **`AppSidebar`** already calls **`openPanel(secondaryPanel)`** when the user clicks the primary item **again** while already on that **`url`** (prevents no-op navigation). Secondary nav rows that stay on the same path **SHOULD** call **`openPanel`** on click where **Next.js `Link`** would not fire (same **`href`**).
 
 ## Surface elevation (brand chrome)
@@ -35,7 +35,7 @@ The nested panel sits **between** the icon rail and main content. **MUST** use t
 
 ## SHOULD
 
-- Drive **hub scope** from the **URL** (**`useSearchParams`** + helpers like **`parseQuestionBankNav`**) so **refresh**, **share link**, and **breadcrumbs** match the secondary list.
+- Drive **hub scope** from the **URL** (**`useSearchParams`** + helpers like **`parseLibraryNav`**) so **refresh**, **share link**, and **breadcrumbs** match the secondary list.
 - Keep **panel content** **Font Awesome**-aligned with the rest of the app (**`.cursor/rules/exxat-fontawesome-icons.mdc`**).
 
 ## MUST NOT
@@ -47,6 +47,6 @@ The nested panel sits **between** the icon rail and main content. **MUST** use t
 
 - **`apps/web/AGENTS.md` §4.6** — handbook summary.
 - **`apps/web/docs/shell-surface-elevation-pattern.md`** — OKLCH tokens + product theme.
-- **`.cursor/rules/exxat-question-bank-hub-header.mdc`** — folder-scoped library header **⋯** → **Customize folder** + client-mounted sheet.
+- **`.cursor/rules/exxat-library-hub-header.mdc`** — folder-scoped library header **⋯** → **Customize folder** + client-mounted sheet.
 - **`.cursor/rules/exxat-page-vs-drawer.mdc`** — when **drawer** vs **route**; secondary panel is **nav chrome**, not a workflow drawer.
 - **`.cursor/rules/exxat-kpi-flat-band.mdc`** — flat KPI strip (separate from panel fill).

package/consumer-extras/cursor-rules/exxat-reuse-before-custom.mdc

@@ -8,7 +8,7 @@ alwaysApply: true
 ## MUST
 
 1. **Compose first** — Use existing **`components/ui/`**, **`components/data-views/`**, **`components/templates/`**, **`PageHeader`**, **`ListPageTemplate`**, **`DataTable`**, **`KeyMetrics`**, and patterns in **`AGENTS.md` §9** before writing new layout or interaction chrome.
-2. **Search the codebase** — Grep or open the nearest hub (Placements, Team, Question bank) for the same UX (toolbar, drawer, metrics, board card, `ListPageViewFrame`, etc.).
+2. **Search the codebase** — Grep or open the nearest hub (Placements, Team, Library) for the same UX (toolbar, drawer, metrics, board card, `ListPageViewFrame`, etc.).
 3. **Extend in place** — Prefer adding a variant, slot, or prop to a shared component over a one-off duplicate under a single route.
 
 ## When the tool must ask the user

package/consumer-extras/cursor-skills/exxat-board-cards/SKILL.md

@@ -39,13 +39,13 @@ Import from **`@/components/data-views/list-page-board-card`**:
 
 Prefer **two-line blocks** for stacked **primary / secondary** facts so cards match Placements’ visual rhythm.
 
-## Status badges (list hubs: Team, Compliance, Question bank, …)
+## Status badges (list hubs: Team, Compliance, Library, …)
 
 - **Maps (single source):** **`lib/list-status-badges.ts`** — per-entity `*_STATUS_LABEL`, `*_STATUS_BADGE_CLASS`, `*_STATUS_ICON`, plus semantic **`LIST_HUB_STATUS_TINT_*`** (success / warning / neutral / danger) for new domains.
 - **Component:** **`ListHubStatusBadge`** from **`@/components/list-hub-status-badge`** — **`surface="table"`** for **DataTable** cells and **list** rows; **`surface="board"`** inside **`ListPageBoardCardBadgeRow`**. Do not duplicate the shell classes on each page.
 - Use the **same** maps everywhere for that entity so copy and colors never drift.
 - **Do not** add **`uppercase`** or **`tracking-wide`** — **sentence / title case**, consistent with **`BoardStatusBadge`** on Placements (`placement-board-card.tsx`).
-- **Placements** lifecycle uses **`StatusBadge`** in **`placements-table-cells.tsx`** — thin wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** in **`list-status-badges.ts`** (same visuals as Team / Question bank).
+- **Placements** lifecycle uses **`StatusBadge`** in **`placements-table-cells.tsx`** — thin wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** in **`list-status-badges.ts`** (same visuals as Team / Library).
 
 ## Avatar when mock has no `initials`
 

package/consumer-extras/cursor-skills/exxat-centralized-list-dataset/SKILL.md

@@ -76,7 +76,7 @@ Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place f
 
 - **`components/placements-client.tsx`** + **`placements-table.tsx`** — Placements pattern.
 - **`components/team-client.tsx`** + **`team-table.tsx`**.
-- **`components/question-bank-table.tsx`** — multiple **`DataListViewType`** branches sharing **`tableState`** / **`folders`** / **`items`**.
+- **`components/library-table.tsx`** — multiple **`DataListViewType`** branches sharing **`tableState`** / **`folders`** / **`items`**.
 
 ---
 

package/consumer-extras/cursor-skills/exxat-collaboration-access/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: true
 **Handbook:** `apps/web/AGENTS.md` §4.7  
 **Narrative:** `apps/web/docs/collaboration-access-pattern.md`  
 **Cursor rule:** `.cursor/rules/exxat-collaboration-access.mdc`  
-**Related (Question bank folder scope + ⋯ Customize folder):** `.cursor/rules/exxat-question-bank-hub-header.mdc` · `docs/question-bank-hub-header-pattern.md`
+**Related (Library folder scope + ⋯ Customize folder):** `.cursor/rules/exxat-library-hub-header.mdc` · `docs/library-hub-header-pattern.md`
 
 ## Wiring checklist
 
@@ -20,7 +20,7 @@ user-invocable: true
 5. **Access maps** — `lib/collaborator-access.ts` for Owner / Editor / Commenter / Viewer, invite options, and **`COLLABORATION_HEADER_ADD_LABEL`**.
 6. **Header** — empty roster → outline **Add collaborator**; non-empty → face rail; both open the invite sheet.
 7. **Invite sheet** — `InviteCollaboratorsDrawer`: export-style **`Sheet`**, combined email + access menu, grouped roster (name → email → role tags → access badge).
-8. **Question bank — folder URL scope** — When **`?scope=folder`**, **`QuestionBankPageHeader`** **⋯** also lists **Customize folder**; **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** — **`.cursor/rules/exxat-question-bank-hub-header.mdc`**, **`docs/question-bank-hub-header-pattern.md`**.
+8. **Library — folder URL scope** — When **`?scope=folder`**, **`LibraryPageHeader`** **⋯** also lists **Customize folder**; **`LibraryNewFolderSheet`** on **`LibraryClient`** — **`.cursor/rules/exxat-library-hub-header.mdc`**, **`docs/library-hub-header-pattern.md`**.
 
 ## MUST NOT
 
@@ -31,5 +31,5 @@ user-invocable: true
 
 ## Reference
 
-- `components/collaboration-access-flow.tsx`, `components/question-bank-page-header.tsx`, `components/question-bank-client.tsx`
+- `components/collaboration-access-flow.tsx`, `components/library-page-header.tsx`, `components/library-client.tsx`
 - `components/invite-collaborators-drawer.tsx`, `components/export-drawer.tsx`

package/consumer-extras/cursor-skills/exxat-dedicated-search-surfaces/SKILL.md

@@ -37,8 +37,8 @@ description: >-
 | Recents list | `components/dedicated-search-recents.tsx` |
 | Recents storage factory | `lib/dedicated-search-recents.ts` |
 | Optional default `q` patcher | `lib/dedicated-search-url.ts` |
-| Question bank adapter (placeholders + patch) | `lib/question-bank-dedicated-search.ts` |
-| Question bank wiring | `components/question-bank-client.tsx` |
+| Library adapter (placeholders + patch) | `lib/library-dedicated-search.ts` |
+| Library wiring | `components/library-client.tsx` |
 
 ## Cursor rule