@redsift/ds-mcp-server 12.5.3-alpha.6 → 12.5.3-alpha.7

package/data/docs/patterns.json

@@ -64,8 +64,16 @@
         "required": true,
         "description": "Client-side pagination with configurable page size (rowsPerPageOptions)"
       },
-      { "name": "Sorting", "required": true, "description": "Client-side column sorting (built into DataGrid)" },
-      { "name": "Filtering", "required": true, "description": "Client-side column filtering (built into DataGrid)" },
+      {
+        "name": "Sorting",
+        "required": true,
+        "description": "Client-side column sorting (built into DataGrid)"
+      },
+      {
+        "name": "Filtering",
+        "required": true,
+        "description": "Client-side column filtering (built into DataGrid)"
+      },
       {
         "name": "Custom cell renderers",
         "required": true,
@@ -149,6 +157,12 @@
         "slug": "crossfiltered-datagrid-page",
         "relationship": "Use when DataCard counts should recalculate as filters change (two-way sync)"
       }
+    ],
+    "keywords": ["data table", "table page", "grid page", "filterable table", "sortable table", "list view"],
+    "commonMistakes": [
+      "❌ Wrapping <DataGrid /> in <Card> → ✅ render <DataGrid /> at the page level. The DataGrid already paints its own surface, padding, and toolbar — nesting it in a Card breaks the toolbar layout and the autoHeight calculation.",
+      "❌ Setting hasPagination={true} thinking pagination is opt-in → ✅ pagination is on by default. Only pass hasPagination={false} when you explicitly want a non-paginated grid (rare).",
+      "❌ Stacking multiple <Pill>s in a status cell with margins or inline styles → ✅ wrap them in <Flexbox gap=\"4px\" alignItems=\"center\">. Renders consistent spacing and inherits cell alignment."
     ]
   },
   {
@@ -219,7 +233,11 @@
         "required": true,
         "description": "filterMode='server' with controlled filterModel + onFilterModelChange"
       },
-      { "name": "Loading overlay", "required": true, "description": "loading prop set to true during fetches" },
+      {
+        "name": "Loading overlay",
+        "required": true,
+        "description": "loading prop set to true during fetches"
+      },
       {
         "name": "Row count",
         "required": true,
@@ -245,7 +263,11 @@
         "required": true,
         "description": "renderCell returning TextCell, Pill, Icon, IconButtonLink"
       },
-      { "name": "Checkbox selection", "required": false, "description": "checkboxSelection + rowSelectionModel" },
+      {
+        "name": "Checkbox selection",
+        "required": false,
+        "description": "checkboxSelection + rowSelectionModel"
+      },
       {
         "name": "Bulk action bar",
         "required": false,
@@ -270,10 +292,30 @@
         "initial": "0",
         "description": "Total matching records (for pagination)"
       },
-      { "name": "loading", "type": "boolean", "initial": "true", "description": "Whether a fetch is in progress" },
-      { "name": "page", "type": "number", "initial": "0", "description": "0-based current page index" },
-      { "name": "pageSize", "type": "number", "initial": "10", "description": "Number of rows per page" },
-      { "name": "sortModel", "type": "GridSortModel", "initial": "[]", "description": "Current sort configuration" },
+      {
+        "name": "loading",
+        "type": "boolean",
+        "initial": "true",
+        "description": "Whether a fetch is in progress"
+      },
+      {
+        "name": "page",
+        "type": "number",
+        "initial": "0",
+        "description": "0-based current page index"
+      },
+      {
+        "name": "pageSize",
+        "type": "number",
+        "initial": "10",
+        "description": "Number of rows per page"
+      },
+      {
+        "name": "sortModel",
+        "type": "GridSortModel",
+        "initial": "[]",
+        "description": "Current sort configuration"
+      },
       {
         "name": "filterModel",
         "type": "GridFilterModel",
@@ -353,7 +395,8 @@
         "slug": "crossfiltered-datagrid-page",
         "relationship": "Use when DataCard counts should recalculate as filters change (two-way sync)"
       }
-    ]
+    ],
+    "keywords": ["server table", "paginated table", "api table", "remote data grid", "lazy table"]
   },
   {
     "name": "Stateful Datagrid Page (Client)",
@@ -390,7 +433,8 @@
         "slug": "stateful-single-datagrid-server-side",
         "relationship": "Use when the dataset is too large to load entirely, with URL state persistence"
       }
-    ]
+    ],
+    "keywords": ["persistent table", "url state table", "bookmarkable table"]
   },
   {
     "name": "Stateful Datagrid Page (Server)",
@@ -427,7 +471,8 @@
         "slug": "stateful-single-datagrid-client-side",
         "relationship": "Use when the dataset fits in the browser, with URL state persistence"
       }
-    ]
+    ],
+    "keywords": ["persistent server table", "url state server table"]
   },
   {
     "name": "Drilldown Datagrid Page",
@@ -595,7 +640,8 @@
         "slug": "server-datagrid-page",
         "relationship": "Use when the dataset is too large to load entirely"
       }
-    ]
+    ],
+    "keywords": ["kpi cards above table", "summary cards", "drilldown", "detail drill", "card-to-table"]
   },
   {
     "name": "Cross-filtered Datagrid Page",
@@ -781,6 +827,13 @@
         "slug": "server-datagrid-page",
         "relationship": "Use when the dataset is too large to load entirely"
       }
+    ],
+    "keywords": [
+      "interactive dashboard",
+      "filterable dashboard",
+      "crossfilter",
+      "bi-directional filter",
+      "dashboard with table"
     ]
   },
   {
@@ -807,10 +860,20 @@
       "DataGrid — server-side table with paginationMode='server', sortingMode='server', filterMode='server'"
     ],
     "relatedPatterns": [
-      { "slug": "server-crossfiltered-datagrid-page", "relationship": "Use when card counts should recalculate" },
-      { "slug": "drilldown-datagrid-page", "relationship": "Client-side version with the same UX" },
-      { "slug": "server-datagrid-page", "relationship": "Use when no summary cards are needed" }
-    ]
+      {
+        "slug": "server-crossfiltered-datagrid-page",
+        "relationship": "Use when card counts should recalculate"
+      },
+      {
+        "slug": "drilldown-datagrid-page",
+        "relationship": "Client-side version with the same UX"
+      },
+      {
+        "slug": "server-datagrid-page",
+        "relationship": "Use when no summary cards are needed"
+      }
+    ],
+    "keywords": ["server drilldown", "server kpi cards", "aggregated drill"]
   },
   {
     "name": "Server Cross-filtered Datagrid Page",
@@ -836,10 +899,20 @@
       "DataGrid — server-side table with controlled filterModel"
     ],
     "relatedPatterns": [
-      { "slug": "server-drilldown-datagrid-page", "relationship": "Use when card counts should stay fixed" },
-      { "slug": "crossfiltered-datagrid-page", "relationship": "Client-side version using crossfilter.js" },
-      { "slug": "server-datagrid-page", "relationship": "Use when no summary cards are needed" }
-    ]
+      {
+        "slug": "server-drilldown-datagrid-page",
+        "relationship": "Use when card counts should stay fixed"
+      },
+      {
+        "slug": "crossfiltered-datagrid-page",
+        "relationship": "Client-side version using crossfilter.js"
+      },
+      {
+        "slug": "server-datagrid-page",
+        "relationship": "Use when no summary cards are needed"
+      }
+    ],
+    "keywords": ["server crossfilter", "server interactive dashboard"]
   },
   {
     "name": "Tabbed Datagrid Page",
@@ -864,9 +937,16 @@
       "DataGrid — client-side table filtered to the active tab's category"
     ],
     "relatedPatterns": [
-      { "slug": "server-tabbed-datagrid-page", "relationship": "Server-side version for large datasets" },
-      { "slug": "drilldown-datagrid-page", "relationship": "Use DataCards instead of Tabs for multi-value filtering" }
-    ]
+      {
+        "slug": "server-tabbed-datagrid-page",
+        "relationship": "Server-side version for large datasets"
+      },
+      {
+        "slug": "drilldown-datagrid-page",
+        "relationship": "Use DataCards instead of Tabs for multi-value filtering"
+      }
+    ],
+    "keywords": ["category tabs", "segmented table", "tab bar above table", "tabbed list"]
   },
   {
     "name": "Server Tabbed Datagrid Page",
@@ -890,7 +970,10 @@
       "DataGrid — server-side table with paginationMode='server', sortingMode='server', filterMode='server'"
     ],
     "relatedPatterns": [
-      { "slug": "tabbed-datagrid-page", "relationship": "Client-side version for smaller datasets" },
+      {
+        "slug": "tabbed-datagrid-page",
+        "relationship": "Client-side version for smaller datasets"
+      },
       {
         "slug": "server-drilldown-datagrid-page",
         "relationship": "Use DataCards instead of Tabs for multi-value filtering"
@@ -899,7 +982,8 @@
         "slug": "server-crossfiltered-datagrid-page",
         "relationship": "Multi-dimensional cross-filtering with DataCards"
       }
-    ]
+    ],
+    "keywords": ["server tabbed table", "server category tabs"]
   },
   {
     "name": "Summary Dashboard",
@@ -953,12 +1037,266 @@
       }
     },
     "relatedPatterns": [
-      { "slug": "drilldown-datagrid-page", "relationship": "The detail page a summary dashboard typically links to" },
+      {
+        "slug": "drilldown-datagrid-page",
+        "relationship": "The detail page a summary dashboard typically links to"
+      },
       {
         "slug": "crossfiltered-datagrid-page",
         "relationship": "Interactive version with cross-filtering and a DataGrid"
       },
-      { "slug": "server-crossfiltered-datagrid-page", "relationship": "Server-driven interactive dashboard" }
+      {
+        "slug": "server-crossfiltered-datagrid-page",
+        "relationship": "Server-driven interactive dashboard"
+      }
+    ],
+    "keywords": [
+      "overview page",
+      "kpi dashboard",
+      "landing page",
+      "metric tiles",
+      "summary tiles",
+      "kpi cards above charts",
+      "dashboard overview",
+      "executive summary"
+    ]
+  },
+  {
+    "name": "KPI Cards Above Charts",
+    "slug": "kpi-cards-above-charts",
+    "description": "A row of metric tiles (DataCards) followed by one or two chart tiles, forming a dashboard overview page. Each DataCard shows a key metric; charts visualize trends or distributions. Users scan KPIs then drill into charts. This is the standard layout for 'Overview' pages across Red Sift products.",
+    "components": [
+      "DataCard",
+      "DataCardHeader",
+      "DataCardBody",
+      "DataRow",
+      "BarChart",
+      "PieChart",
+      "ChartContainer",
+      "Flexbox",
+      "Heading",
+      "Text",
+      "Skeleton"
+    ],
+    "packages": ["@redsift/dashboard", "@redsift/charts", "@redsift/design-system"],
+    "layout": "Flexbox column: top row = Flexbox row wrapping DataCards (flex: 1 each), bottom row = Flexbox row with one or two chart containers. Each DataCard has DataCardHeader + DataCardBody with DataRow children.",
+    "tags": ["dashboard", "kpi", "metric", "chart", "overview", "summary", "tiles", "landing-page"],
+    "keywords": [
+      "kpi cards above charts",
+      "overview page",
+      "metric tiles with charts",
+      "summary dashboard",
+      "executive dashboard",
+      "kpi row",
+      "stat cards",
+      "dashboard landing"
+    ],
+    "whenToUse": [
+      "Building an overview or landing page that shows key metrics at a glance",
+      "Users need to see aggregate KPIs and trend charts without interactive filtering",
+      "The page is read-only — clicking a DataRow navigates to a detail page",
+      "You want a standard two-row layout: metrics on top, charts below"
+    ],
+    "whenNotToUse": [
+      "Users need to cross-filter between cards and a DataGrid — use Crossfiltered Datagrid Page instead",
+      "The page is primarily a table with summary KPIs — use Drilldown Datagrid Page instead",
+      "Only charts, no KPI tiles — use a simple Flexbox of ChartContainers"
+    ],
+    "anatomy": [
+      "Heading — Page title",
+      "KPI Row — Flexbox row of DataCards, each with DataCardHeader and DataCardBody containing DataRow items",
+      "Chart Row — Flexbox row of chart containers (BarChart, PieChart, etc.) wrapped in styled containers with titles"
+    ]
+  },
+  {
+    "name": "Chart Empty State",
+    "slug": "chart-empty-state",
+    "description": "How to render loading, empty, and error states inside a DataCard or ChartContainer. Uses ChartEmptyState from @redsift/dashboard for consistent empty/error messaging, Skeleton for loading shimmer, and Alert + Button for error-with-retry.",
+    "components": [
+      "ChartEmptyState",
+      "DataCard",
+      "DataCardHeader",
+      "DataCardBody",
+      "Skeleton",
+      "Alert",
+      "Button",
+      "Text"
+    ],
+    "packages": ["@redsift/dashboard", "@redsift/design-system"],
+    "layout": "DataCard with conditional content: loading (Skeleton), empty (ChartEmptyState), error (Alert + Button), or success (chart content).",
+    "tags": ["empty-state", "loading", "error", "skeleton", "chart", "dashboard", "retry"],
+    "keywords": [
+      "chart loading",
+      "chart empty",
+      "chart error",
+      "no data chart",
+      "loading state",
+      "empty chart state",
+      "error banner",
+      "retry button",
+      "chart placeholder"
+    ],
+    "whenToUse": [
+      "A chart or DataCard needs to show loading, empty, or error states",
+      "You want a consistent look across all chart tiles for non-happy-path states",
+      "The error state should include a retry action"
+    ],
+    "whenNotToUse": [
+      "The component is a DataGrid — DataGrid has its own built-in loading/empty/error overlays",
+      "You only need a full-page loading spinner — use Spinner instead"
+    ],
+    "anatomy": [
+      "DataCard — Container for the chart tile",
+      "DataCardHeader — Title of the chart",
+      "DataCardBody — Conditional content based on state",
+      "Loading: Skeleton components matching the chart shape",
+      "Empty: ChartEmptyState with a message and optional illustration",
+      "Error: Alert variant='error' + Button variant='secondary' for retry"
+    ]
+  },
+  {
+    "name": "Error Banner with Retry",
+    "slug": "error-banner-with-retry",
+    "description": "A section-level error display with a retry button, replacing hand-rolled styled.button and hex colors. Uses Alert from @redsift/design-system for the error message and Button variant='secondary' for the retry action. Never use styled.button or hardcoded rgba() values for this pattern.",
+    "components": ["Alert", "Button", "Flexbox", "Text"],
+    "packages": ["@redsift/design-system"],
+    "layout": "Flexbox column with Alert at top and optional Button below, or Alert with action prop containing the retry Button.",
+    "tags": ["error", "retry", "alert", "banner", "notification", "failure"],
+    "keywords": [
+      "error banner",
+      "retry button",
+      "error message",
+      "section error",
+      "failed to load",
+      "try again",
+      "error state"
+    ],
+    "whenToUse": [
+      "A section of the page failed to load and the user can retry",
+      "You need an inline error message with an action",
+      "Replacing a hand-rolled error banner with hardcoded styles"
+    ],
+    "whenNotToUse": [
+      "The entire page failed — use a full-page error boundary instead",
+      "The error is inside a chart tile — use Chart Empty State pattern instead"
+    ],
+    "anatomy": [
+      "Alert — Displays the error message with severity='error'",
+      "Button — 'Retry' button with variant='secondary' and onClick handler"
+    ]
+  },
+  {
+    "name": "Host App Page Registration",
+    "slug": "host-app-page-registration",
+    "description": "Abstract contract for adding a new page to a Red Sift host application. Every new page requires a routing entry, a navigation entry in the sidebar, and a page title registered as an i18n key in ALL supported locales. Missing any locale mirror causes the page title to show as a raw key string. This is a framework pattern — concrete implementation depends on the host app's router and i18n system.",
+    "components": ["AppContainer", "AppSidePanel", "AppBar", "AppContent"],
+    "packages": ["@redsift/design-system"],
+    "layout": "AppContainer > AppSidePanel (nav entry) + AppContent (routed page component). AppBar displays the page title from i18n.",
+    "tags": ["host-app", "page", "routing", "navigation", "i18n", "locale", "title", "setup"],
+    "keywords": [
+      "page registration",
+      "add page",
+      "new page",
+      "route setup",
+      "navigation entry",
+      "page title",
+      "i18n key",
+      "locale mirror",
+      "host app contract",
+      "app shell setup"
+    ],
+    "whenToUse": [
+      "Adding a new page or view to a Red Sift application",
+      "The page needs a sidebar navigation entry",
+      "The page title must be translated across all supported locales"
+    ],
+    "whenNotToUse": [
+      "Rendering a modal or dialog — no route needed",
+      "A sub-tab within an existing page — handled by the page's Tabs component"
+    ],
+    "anatomy": [
+      "Route definition — maps a URL path to a page component",
+      "Navigation entry — adds an item to AppSidePanel with icon, label i18n key, and route path",
+      "Page title i18n key — registered in EVERY locale file (e.g. en-US.json, fr-FR.json). If any locale is missing the key, the title renders as the raw key string.",
+      "Page component — wrapped in AppContent, receives route params"
+    ],
+    "implementationSteps": [
+      "Define the route path and page component in the app's router configuration",
+      "Add a navigation entry to AppSidePanel with the route path and an i18n label key",
+      "Register the page title i18n key in ALL locale files (en-US, fr-FR, etc.)",
+      "Verify the title renders correctly by switching locales",
+      "Import @redsift/design-system/style/index.css at the app entry if not already done"
+    ]
+  },
+  {
+    "name": "Category Tabs Above Table",
+    "slug": "category-tabs-above-table",
+    "description": "A row of Tabs above a DataGrid that filter the grid's rows by a category (e.g. All / Active / Expired / Critical). The selected tab becomes part of the grid's filterModel. Use this pattern when you have a small, well-known set of mutually exclusive row categories — it is a UX shortcut for the most common filter on the page. For arbitrary or many-valued filters, use the DataGrid's built-in column filter UI instead.",
+    "components": ["Tabs", "Tab", "TabPanel", "DataGrid", "Pill", "Flexbox"],
+    "packages": ["@redsift/design-system", "@redsift/table"],
+    "layout": "Flexbox column: Tabs row + DataGrid below. Tabs are sticky-positioned above the grid; the active Tab drives a filterModel applied to the DataGrid.",
+    "tags": ["tabs", "datagrid", "filter", "category", "status-filter", "segmented-control"],
+    "keywords": [
+      "category tabs above table",
+      "tabs above grid",
+      "status tabs",
+      "tabbed datagrid",
+      "filter tabs",
+      "segmented filter"
+    ],
+    "whenToUse": [
+      "You have a fixed, small set of mutually exclusive row categories (typically 2–6 tabs)",
+      "The category filter is the dominant user action on the page",
+      "Tabs should mirror an enum field on the row (e.g. status, severity)"
+    ],
+    "whenNotToUse": [
+      "The filter values are dynamic or numerous — use the DataGrid's built-in column filter instead",
+      "Multiple simultaneous filters are required — Tabs are mutually exclusive by design",
+      "The categories themselves are not orthogonal (overlapping memberships)"
+    ],
+    "anatomy": [
+      "Tabs — DS Tabs from @redsift/design-system, one Tab per category plus an 'All' tab",
+      "Optional Pill — count badge inside each Tab label (e.g. 'Active (12)')",
+      "DataGrid — receives filterModel derived from the active tab"
+    ],
+    "stateHooks": [
+      {
+        "name": "activeTab",
+        "type": "string",
+        "initial": "'all'",
+        "description": "Slug of the currently selected tab; drives the DataGrid filterModel."
+      }
+    ],
+    "dataContract": "type Row = {\n  id: string;\n  status: 'active' | 'warning' | 'critical' | 'expired';\n  // …other fields\n};\n\n// activeTab → filterModel mapping\nconst filterModelForTab = (tab: string): GridFilterModel =>\n  tab === 'all'\n    ? { items: [] }\n    : { items: [{ columnField: 'status', operatorValue: 'equals', value: tab }] };",
+    "implementationSteps": [
+      "Define the tab list as a const array of { slug, label, filterValue } entries — one per category plus 'all'.",
+      "Add useState<string>('all') for activeTab.",
+      "Render <Tabs value={activeTab} onChange={setActiveTab}> with one <Tab> per entry. Inside the label, optionally show a count <Pill>.",
+      "Compute filterModel from activeTab via a pure helper.",
+      "Pass filterModel into <DataGrid filterModel={...} onFilterModelChange={...}>. Keep the DataGrid's own filter UI enabled so users can layer column filters on top.",
+      "Sync activeTab to the URL query string (?status=active) for shareable links."
+    ],
+    "accessibility": [
+      "Tabs and Tab from @redsift/design-system already wire role=\"tablist\" / role=\"tab\" and arrow-key navigation",
+      "Use aria-controls to associate each Tab with the DataGrid id",
+      "Do not hide the DataGrid's built-in column filter — tab filters are a shortcut, not a replacement"
+    ],
+    "commonMistakes": [
+      "❌ Using @mui/material Tabs → ✅ import { Tabs, Tab } from '@redsift/design-system'.",
+      "❌ Wrapping each tab's grid in a separate <Card> → ✅ render a single DataGrid and switch its filterModel based on activeTab.",
+      "❌ styled(Tab) to restyle for 'segmented control' look → ✅ DS Tabs already supports the visual variant; check get_component_props('Tabs').",
+      "❌ Hard-coded status counts in Tab labels → ✅ derive counts from rows so they stay in sync with data.",
+      "❌ Hiding the DataGrid's built-in filters once Tabs are added → ✅ Tab filters and column filters compose; keep both."
+    ],
+    "relatedPatterns": [
+      {
+        "slug": "datagrid-page",
+        "relationship": "The underlying full-page grid. Add tabs on top when one enum field dominates filtering."
+      },
+      {
+        "slug": "tabbed-datagrid-client-side",
+        "relationship": "Closely related; this pattern is specifically the 'category filter' variant."
+      }
     ]
   }
 ]

package/data/metadata.json

@@ -1,4 +1,4 @@
 {
-  "generatedAt": "2026-05-11T11:23:12.230Z",
-  "commitSha": "95c1f792fd599240c067448455dc883acb48db6a"
+  "generatedAt": "2026-05-12T09:47:51.251Z",
+  "commitSha": "d6bbaa5082b6d63d000834a362238a0618680d60"
 }

package/data/prompts/ds-advisor.md

@@ -0,0 +1,103 @@
+# Red Sift Design System Advisor
+
+> Inject this prompt into the system prompt of any AI assistant that generates code against the `@redsift/*` design system. It encodes component selection, disambiguation, and the most common anti-patterns. Pair it with live MCP lookups via `get_component_props` and `get_component_usage`.
+
+## Required 4-Step Output Format
+
+Every code-generation answer MUST follow these four steps in order.
+
+### Step 1 — Pattern Match
+
+Identify the UI intent in one sentence (e.g. "KPI tile", "status badge", "data table with filters", "loading placeholder"). State which DS pattern(s) match, or "none — composing from primitives" with the primitive list.
+
+### Step 2 — Canonical Components
+
+For every component you intend to use:
+
+1. Call `get_component_props` to verify the exact prop names. Do NOT answer from memory.
+2. State the exact import: `import { DataCard, DataRow } from '@redsift/dashboard';`
+3. Cite the source (e.g. "verified via `get_component_props('DataCard')`").
+
+### Step 3 — Code
+
+Output a complete, compilable implementation. Mandatory rules:
+
+- Semantic colors only: `"success" | "warning" | "error" | "info"` — never hex/rgb literals or `var(--rs-color-*)` fallbacks.
+- Icons from `@redsift/icons`: `mdiCheck`, `mdiClose`, etc. — never unicode glyphs (`✓`, `✕`, `⚠`, `›`, `•`).
+- Flexbox props are strings: `gap="4px"` not `gap={4}`.
+- Pill content via `children`: `<Pill color="success">Active</Pill>` not `<Pill label="Active" />`.
+- DS Skeleton only: never `import { Skeleton } from '@mui/material'`.
+- No inline flex styles: use `<Flexbox>` instead of `style={{ display: 'flex' }}`.
+
+### Step 4 — Anti-Patterns Rejected
+
+List every anti-pattern you avoided and why.
+
+## Component Selection Cheat Sheet
+
+| UI Intent           | Component(s)                                                   | Package                  |
+| ------------------- | -------------------------------------------------------------- | ------------------------ |
+| KPI / metric tile   | `DataCard` + `DataCard.Header` + `DataRow`                     | `@redsift/dashboard`     |
+| Status badge / chip | `<Pill color="success">Label</Pill>`                           | `@redsift/design-system` |
+| Data grid / table   | `DataGrid` (or `StatefulDataGrid` when state is server-driven) | `@redsift/table`         |
+| Loading placeholder | `Skeleton` / `SkeletonText` / `SkeletonCircle`                 | `@redsift/design-system` |
+| Collapsible section | `DetailedCard` + `DetailedCardSection`                         | `@redsift/design-system` |
+| Generic container   | `Card` (NOT for KPI tiles — use `DataCard`)                    | `@redsift/design-system` |
+| Modal / dialog      | `Dialog` compound component                                    | `@redsift/popovers`      |
+| Tooltip             | `Tooltip` / `Toggletip` (click)                                | `@redsift/popovers`      |
+| Dropdown / picker   | `Select` / `Combobox` (autocomplete)                           | `@redsift/pickers`       |
+| Tabs                | `Tabs` + `Tab` + `TabPanel`                                    | `@redsift/design-system` |
+| Empty / error chart | `ChartEmptyState`                                              | `@redsift/dashboard`     |
+
+## MUI → DS Migration Map
+
+Do NOT import from `@mui/material`, `@mui/icons-material`, or `@mui/x-data-grid*` directly. The DS wraps or replaces every MUI component you need.
+
+| MUI component                                  | DS equivalent                             | Package                                         |
+| ---------------------------------------------- | ----------------------------------------- | ----------------------------------------------- |
+| `Chip`                                         | `Pill`                                    | `@redsift/design-system`                        |
+| `Tabs` / `Tab`                                 | `Tabs` / `Tab`                            | `@redsift/design-system`                        |
+| `Skeleton`                                     | `Skeleton`                                | `@redsift/design-system`                        |
+| `Box` / `Stack`                                | `Flexbox`                                 | `@redsift/design-system`                        |
+| `Typography`                                   | `Heading` / `Text`                        | `@redsift/design-system`                        |
+| `Button`                                       | `Button`                                  | `@redsift/design-system`                        |
+| `Alert`                                        | `Alert`                                   | `@redsift/design-system`                        |
+| `Dialog`                                       | `Dialog`                                  | `@redsift/popovers`                             |
+| `Tooltip`                                      | `Tooltip`                                 | `@redsift/popovers`                             |
+| `Select` / `Autocomplete`                      | `Select` / `Combobox`                     | `@redsift/pickers`                              |
+| `Card`                                         | `Card` (or `DataCard` for KPI tiles)      | `@redsift/design-system` / `@redsift/dashboard` |
+| `DataGrid` / `DataGridPro` / `DataGridPremium` | `DataGrid` / `StatefulDataGrid`           | `@redsift/table`                                |
+| `@mdi/js` icons                                | same `mdi*` exports from `@redsift/icons` | `@redsift/icons`                                |
+
+Special-cases:
+
+- `DataGrid` already paginates by default — do NOT wrap it in `<Card>` and do NOT set `hasPagination` unless you also explicitly want to disable it (`hasPagination={false}`).
+- For a status cell with multiple labels, wrap `<Pill>`s in a `<Flexbox gap="4px">` — never roll your own.
+
+## Disambiguation Rules
+
+- **`Card` vs `DataCard` vs `DetailedCard`** — `Card` is a generic container; `DataCard` is the KPI/metric tile from `@redsift/dashboard` (this is the right answer 9 times out of 10 when the prompt mentions "tile", "metric", "summary card", or "card with a big number"); `DetailedCard` is for rich, collapsible detail panels.
+- **`Skeleton`** — always from `@redsift/design-system`. Never from `@mui/material`.
+- **`Icon`** — renders an SVG path. Always import `mdi*` icons from `@redsift/icons`, never from `@mdi/js`, never as a unicode character.
+- **`Tabs`** — always the DS `Tabs` from `@redsift/design-system`. For a "segmented control" or "tab bar above a grid", this is the correct primitive.
+
+## Anti-Pattern Catalog
+
+| Anti-Pattern                                        | Correction                                                    |
+| --------------------------------------------------- | ------------------------------------------------------------- |
+| `<Card style={{ borderLeft: '4px solid green' }}>`  | `<DataCard color="success">`                                  |
+| `color: 'var(--rs-color-green-500)'` on a DS prop   | semantic color prop: `color="success"`                        |
+| Unicode glyphs (`✓`, `⚠`, `›`)                      | `<Icon path={mdiCheck} />` from `@redsift/icons`              |
+| Hex / RGB literals on DS color props                | semantic color prop                                           |
+| `<Pill label="Active" />`                           | `<Pill>Active</Pill>` (uses children)                         |
+| `gap={4}` (number)                                  | `gap="4px"` (string)                                          |
+| `import { Skeleton } from '@mui/material'`          | `import { Skeleton } from '@redsift/design-system'`           |
+| `import { mdiPlus } from '@mdi/js'`                 | `import { mdiPlus } from '@redsift/icons'`                    |
+| `<Card><DataGrid /></Card>`                         | render `<DataGrid />` at the page level                       |
+| Wrapping a DS component in `styled(...)` to restyle | use built-in props, composition, or file a DS feature request |
+
+## Refusal Rules
+
+1. If asked for a hex color to apply to a DS component, refuse and return the semantic token name.
+2. If asked to wrap a DS component in `styled-components` to change its appearance, refuse and propose props / composition / a DS feature request.
+3. If the requested component does not exist in any `@redsift/*` package, say so and propose the closest existing primitive or composition — do not fall back to MUI.

package/dist/data-store.d.ts

@@ -23,10 +23,30 @@ export declare class DataStore {
     /** Get the host app setup guide */
     getHostAppSetup(): string;
     /**
-     * Search components by name or description.
+     * Search components by name, description, keyword, or anti-pattern text.
      * Returns matches sorted by relevance.
+     *
+     * Scoring rules (plan §1.4):
+     * - Tokens: deduped union of {joined-no-space, ...split-on-space}.
+     * - Per split term: exact name +100, starts-with +50, contains +30;
+     *   exact keyword +80, keyword starts-with +40, keyword contains +20;
+     *   description contains +10.
+     * - Joined form is scored against NAME and KEYWORDS only (not description),
+     *   at the same tiers as a term. The dedupe guarantees that when a single-word
+     *   query produces joined === split[0] the bonus is awarded only once.
+     * - Original lowercase phrase vs description: +15 (catches "data grid
+     *   displays tabular data" without re-tokenising).
+     * - Original lowercase phrase exactly equals a keyword: +80 (routes
+     *   multi-word UI intents like "kpi card" → DataCard via its keyword).
+     * - Original lowercase phrase vs antiPatterns text: +10 (auto-routes MUI
+     *   queries to DS, e.g. "skeleton from @mui/material" matches Skeleton).
      */
     searchComponents(query: string, packageFilter?: string): ComponentIndexEntry[];
+    /**
+     * Pure scoring helper. Exported as a static so it can be unit-tested without
+     * touching the filesystem. See {@link searchComponents} JSDoc for the rules.
+     */
+    static rankComponents(index: ComponentIndexEntry[], query: string): ComponentIndexEntry[];
     /**
      * Get full component documentation by name.
      * Optionally filter by package for disambiguation.