@wangs-ui/skills 1.3.0-alpha.13 → 1.3.0-alpha.15

package/dist/bin.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-DChgYbFi.js";
+import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-jN6qaZYo.js";
 import path from "node:path";
 import { parseArgs } from "node:util";
 //#region bin.ts
-var VERSION = "1.3.0-alpha.13";
+var VERSION = "1.3.0-alpha.14";
 var HELP_TEXT = `
 \x1b[1m\x1b[36m🚀 Wangs UI Skills & Rules CLI\x1b[0m
 Install, update, and manage modular AI agent skills and rules for Wangs UI React applications.

package/dist/index.js

@@ -1,2 +1,2 @@
-import { _ as loadAllRules, a as getAgentRuleDirs, c as getInstalledSkills, d as isRuleInstalled, f as isSkillInstalled, g as getSkill, h as getRule, i as listSkills, l as installRule, m as removeSkill, n as updateSkills, o as getAgentSkillDirs, p as removeRule, r as addSkills, s as getInstalledRules, t as removeSkills, u as installSkill, v as loadAllSkills } from "./src-DChgYbFi.js";
+import { _ as loadAllRules, a as getAgentRuleDirs, c as getInstalledSkills, d as isRuleInstalled, f as isSkillInstalled, g as getSkill, h as getRule, i as listSkills, l as installRule, m as removeSkill, n as updateSkills, o as getAgentSkillDirs, p as removeRule, r as addSkills, s as getInstalledRules, t as removeSkills, u as installSkill, v as loadAllSkills } from "./src-jN6qaZYo.js";
 export { addSkills, getAgentRuleDirs, getAgentSkillDirs, getInstalledRules, getInstalledSkills, getRule, getSkill, installRule, installSkill, isRuleInstalled, isSkillInstalled, listSkills, loadAllRules, loadAllSkills, removeRule, removeSkill, removeSkills, updateSkills };

package/dist/skills/{craft-theme → wangs-ui/craft-theme}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: craft-theme
-description: Generate a brand-color theme (13-shade tonal palette + M3-style semantic tokens) for a Wangs UI app via the `wangs-ui-generate-palette` CLI — never hand-write hex shade ramps.
+description: Generate a brand-color theme (13-shade tonal palette + semantic tokens) for a Wangs UI app via the `wangs-ui-generate-palette` CLI — never hand-write hex shade ramps.
 metadata:
   owner: wangs-ui
 ---

package/dist/skills/{create-form → wangs-ui/create-form}/SKILL.md

@@ -17,15 +17,15 @@ Do **NOT** hardcode or guess prop names, component options, preset variations, o
 ### Component & Form API Protocol:
 
 ```json
-get_component_api({ "id": "form" })
-get_component_api({ "id": "field" })
-get_component_api({ "id": "dialogform" })
-get_component_api({ "id": "input" })
-get_component_api({ "id": "numberinput" })
-get_component_api({ "id": "select" })
-get_component_api({ "id": "multiselect" })
-get_component_api({ "id": "datepicker" })
-get_component_api({ "id": "fileupload" })
+get_component_api({ "component": "form" })
+get_component_api({ "component": "field" })
+get_component_api({ "component": "dialogform" })
+get_component_api({ "component": "input" })
+get_component_api({ "component": "numberinput" })
+get_component_api({ "component": "select" })
+get_component_api({ "component": "multiselect" })
+get_component_api({ "component": "datepicker" })
+get_component_api({ "component": "fileupload" })
 ```
 
 ### Curated Form Documentation:
@@ -83,6 +83,8 @@ query_graph({ "query": "useWatchField" })
 - **Children Render Callback**: `Field` yields `{ fieldProps, fieldState }`.
 - **`fieldProps`**: Pass directly to primitive inputs (`<Input {...fieldProps} />`). Contains `name`, `value`, `ref`, `onChange`.
 - **`fieldState`**: Provides `invalid`, `error`, `isDirty`, `isPending`. Pass `invalid={fieldState.invalid}` to primitive components for accessibility and validation styling.
+- **⚠️ Mandatory Destructuring (Never `(field) => ...`)**: `<Field>`'s callback render prop must destructure as `{({ fieldProps, fieldState })}`. Passing a single parameter instead (`{(field) => ...}`) produces `undefined` `value`/`onChange` and permanently locks the input.
+- **Pass `fieldProps.onChange` directly**: `<Field>` is generic and `fieldProps.onChange` is already typed to the field's value type. Do not wrap it in unnecessary `e?.target?.value` extractions.
 
 ---
 

package/dist/skills/{data-table → wangs-ui/data-table}/SKILL.md

@@ -14,13 +14,13 @@ Use this skill when implementing data grids, server-paginated tables, filterable
 
 Do **NOT** guess table prop names or hardcode table structures. Query the MCP server dynamically to inspect exact TypeScript signatures, live story implementations, and companion controls:
 
-### Inspect Component Contracts:
+### Inspect Component Contracts (`component` parameter):
 
 ```json
-get_component_api({ "id": "datatable" })
-get_component_api({ "id": "exportbutton" })
-get_component_api({ "id": "filtercontainer" })
-get_component_api({ "id": "bulkactionbutton" })
+get_component_api({ "component": "datatable" })
+get_component_api({ "component": "exportbutton" })
+get_component_api({ "component": "filtercontainer" })
+get_component_api({ "component": "bulkactionbutton" })
 ```
 
 ### Read Curated Documentation:
@@ -55,7 +55,7 @@ query_graph({ "query": "useDataTableFetch" })
 The Wangs UI `DataTable` is built on a modular, headless-first architecture:
 
 1. **Declarative Column Definitions (`TableColumn<T>[]`)**:
-   Columns are configured as typed array objects, not as JSX children. Check `get_component_api({ "id": "datatable" })` for column field types.
+   Columns are configured as typed array objects, not as JSX children. Check `get_component_api({ "component": "datatable" })` for column field types.
 2. **Table Instance Hook (`useDataTable`)**:
    Coordinates table state (sorting, pagination, selection, column ordering, pinning, visibility).
 3. **Data Fetching Hook (`useDataTableFetch`)**:
@@ -73,4 +73,5 @@ The Wangs UI `DataTable` is built on a modular, headless-first architecture:
 1. **Query MCP for Current Code Patterns**: Always run `get_component_examples` for `datatable` before drafting code.
 2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/datatable` and companion primitive paths.
 3. **Always Translate Visible Copy**: All column header labels, empty state messages, and action button labels must be wrapped in `t('...')` from `@wangs-ui/react-i18n`.
-4. **Stable Row Identity**: Always configure a unique key identifier for stable selection and row identity.
+4. **Stable Row Identity**: Always configure a unique key identifier (`dataKey` / `rowId`) for stable selection and row identity.
+5. **Zero Redundant Table Wrappers**: Never wrap `<DataTable />` in an isolated `<div>` or `<Box>` solely to set width or margin. Wangs UI DataTable manages its own container scroll and layout dimensions out of the box.

package/dist/skills/{dialog-modal → wangs-ui/dialog-modal}/SKILL.md

@@ -14,13 +14,13 @@ Use this skill when building interactive modals, create/edit dialog forms, destr
 
 Do **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:
 
-### Inspect Overlay Contracts:
+### Inspect Overlay Contracts (`component` parameter):
 
 ```json
-get_component_api({ "id": "dialog" })
-get_component_api({ "id": "dialogform" })
-get_component_api({ "id": "modal" })
-get_component_api({ "id": "toast" })
+get_component_api({ "component": "dialog" })
+get_component_api({ "component": "dialogform" })
+get_component_api({ "component": "modal" })
+get_component_api({ "component": "toast" })
 ```
 
 ### Read Curated Overlay Documentation:

package/dist/skills/{i18n-usage → wangs-ui/i18n-usage}/SKILL.md

@@ -14,14 +14,14 @@ Use this skill when implementing multi-language interfaces, translating user-fac
 
 Do **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:
 
-### Inspect Localized Component Contracts:
+### Inspect Localized Component Contracts (`component` parameter):
 
 ```json
-get_component_api({ "id": "languageswitcher" })
-get_component_api({ "id": "currencyinput" })
-get_component_api({ "id": "datepicker" })
-get_component_api({ "id": "select" })
-get_component_api({ "id": "datatable" })
+get_component_api({ "component": "languageswitcher" })
+get_component_api({ "component": "currencyinput" })
+get_component_api({ "component": "datepicker" })
+get_component_api({ "component": "select" })
+get_component_api({ "component": "datatable" })
 ```
 
 ### Read Curated Localization Documentation:
@@ -140,7 +140,7 @@ selectedCount === 0
 Use standard supported HTML tags (`<a>`, `<b>`, `<i>`, `<u>`, `<s>`, `<br/>`, `<sub>`, `<sup>`, `<code>`, `<mark>`) for inline styling. Tags are automatically parsed into React elements without custom regex or string manipulation:
 
 ```tsx
-import Link from '@wangs-ui/foundation/theme/Link';
+import { Link } from '@wangs-ui/foundation/theme';
 
 t('You have selected <b>{count} items</b>. Click <a>here</a> to review.', {
   count: selectedCount,

package/dist/skills/wangs-ui/layout-navigation/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: layout-navigation
+description: Architecture, navigation hierarchies, and MCP discovery protocol for AppLayout, Sidebar, Breadcrumb, and Tabs in Wangs UI.
+metadata:
+  owner: wangs-ui
+---
+
+# Skill: Application Layout & Navigation Hierarchy
+
+Use this skill when constructing application shells, multi-level sidebars, page headers, breadcrumbs, tabbed views, or feature routing with `@wangs-ui/react-core`, `@wangs-ui/foundation`, and `@wangs-ui/react-navigation`.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess layout block slots, sidebar item interfaces, or breadcrumb props. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+
+### Inspect Layout & Navigation Contracts (`component` parameter):
+
+```json
+get_component_api({ "component": "applayout" })
+get_component_api({ "component": "sidebar" })
+get_component_api({ "component": "tabletoolbar" })
+get_component_api({ "component": "breadcrumb" })
+get_component_api({ "component": "tabs" })
+```
+
+
+### Read Curated Layout Documentation (`id` parameter):
+
+```json
+get_documentation({ "id": "applayout" })
+get_documentation({ "id": "sidebar" })
+get_documentation({ "id": "react-navigation" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get_component_examples({ "component": "applayout", "variant": "TopNavbar" })
+get_component_examples({ "component": "sidebar", "variant": "WithSubMenu" })
+get_component_examples({ "component": "breadcrumb", "variant": "Default" })
+get_component_examples({ "component": "tabs", "variant": "Default" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "AppLayout" })
+query_graph({ "query": "Sidebar" })
+```
+
+---
+
+## 2. Layout Architecture & Mental Model
+
+1. **Top-Level App Shell (`AppLayout`)**:
+   - Subpath: `@wangs-ui/react-core/blocks/applayout`
+   - Outer responsive shell arranging navigation, navbar, sidebars, main viewport, and footer. Inspect slots and layout variants via `get_component_api({ "component": "applayout" })`.
+2. **Hierarchical Menu (`Sidebar`)**:
+   - Subpath: `@wangs-ui/react-core/blocks/sidebar`
+   - Primary app navigation drawer/rail supporting nested menus, badges, and collapse states. Inspect items and events via `get_component_api({ "component": "sidebar" })`.
+3. **Breadcrumb Trail (`Breadcrumb`)**:
+   - Subpath: `@wangs-ui/react-core/primitive/breadcrumb`
+   - Secondary hierarchy navigation displaying screen depth. Inspect item structure via `get_component_api({ "component": "breadcrumb" })`.
+4. **Tabbed Sub-Views (`Tabs`)**:
+   - Subpath: `@wangs-ui/react-core/primitive/tabs`
+   - In-page view switcher for partitioning entity details into distinct panels. Inspect via `get_component_api({ "component": "tabs" })`.
+5. **Universal Routing (`@wangs-ui/react-navigation`)**:
+   - Platform-agnostic route graph abstraction (`buildGraph`, `paramRoute`).
+   - Web router bridge: `@wangs-ui/react-navigation/web` (React Router).
+   - Native router bridge: `@wangs-ui/react-navigation/native` (React Navigation / Expo).
+
+---
+
+## 3. Structural Page Blueprint (Standard Pattern)
+
+```tsx
+import AppLayout from '@wangs-ui/react-core/blocks/applayout';
+import Sidebar from '@wangs-ui/react-core/blocks/sidebar';
+import Breadcrumb from '@wangs-ui/react-core/primitive/breadcrumb';
+import { Container, Section, Stack, HStack } from '@wangs-ui/foundation/layout';
+import { Text } from '@wangs-ui/foundation/theme';
+import { useI18n } from '@wangs-ui/react-i18n';
+import { HomeLine, Settings4Line } from '@wangs-ui/react-icons';
+import { useState } from 'react';
+
+export function ApplicationShell({ children }: { children: React.ReactNode }) {
+  const { t } = useI18n();
+  const [activeRoute, setActiveRoute] = useState('dashboard');
+  const [collapsed, setCollapsed] = useState(false);
+
+  const sidebarItems = [
+    { value: 'dashboard', label: t('Dashboard'), icon: HomeLine, to: '/' },
+    { value: 'settings', label: t('Settings'), icon: Settings4Line, to: '/settings' },
+  ];
+
+  return (
+    <AppLayout
+      variant="full-sidebar"
+      sidebar={
+        <Sidebar
+          items={sidebarItems}
+          value={activeRoute}
+          onValueChange={setActiveRoute}
+          collapsed={collapsed}
+          onCollapsedChange={setCollapsed}
+          collapseMode="rail"
+        />
+      }
+    >
+      <Container size="xl">
+        <Section space="md">
+          <Stack gap="4">
+            <Breadcrumb
+              items={[
+                { label: t('Home'), href: '/' },
+                { label: t('Dashboard') },
+              ]}
+            />
+            <Text variant="headlineLarge">{t('Overview')}</Text>
+            {children}
+          </Stack>
+        </Section>
+      </Container>
+    </AppLayout>
+  );
+}
+```
+
+---
+
+## 4. Mandatory Implementation Rules
+
+1. **Query MCP First**: Always inspect `applayout` and `sidebar` stories via MCP before assembling the layout.
+2. **Strict Subpath Imports**:
+   - Blocks: `@wangs-ui/react-core/blocks/*` (`applayout`, `sidebar`, `tabletoolbar`)
+   - Primitives: `@wangs-ui/react-core/primitive/*` (`breadcrumb`, `tabs`)
+   - Layout Primitives: `@wangs-ui/foundation/layout` (`Container`, `Section`, `Stack`, `HStack`, `Box`, `Grid`)
+   - Typography: `@wangs-ui/foundation/theme` (`Text`)
+3. **Standard Layout Containers & Spacing**:
+   - Use `Container` (max-width rhythm) and `Section` (vertical rhythm) for page boundaries.
+   - Use flat numeric Tailwind spacing (`gap="4"`, `p="6"`). Never use legacy named tokens like `p-3xl` or `gap-md`.
+4. **Typography Scale**:
+   - Use `<Text variant="headlineLarge">` or `display*` / `title*` for page headers. Never use obsolete `.heading-*` helper classes or raw HTML heading tags without primitives.
+5. **No Redundant Layout Wrappers**:
+   - Do NOT insert intermediate pass-through `<div>` or `<Box>` wrappers between `<Card>`/`<Tabs>` and tab contents.
+   - Render active tab content directly as a child of the container:
+     ```tsx
+     // ✅ Good
+     <Card>
+       <Tabs items={tabItems} value={activeTab} onValueChange={setActiveTab} />
+       {activeTab === 'general' ? <GeneralTab /> : <SecurityTab />}
+     </Card>
+     ```
+6. **Translate Navigation Labels**: Wrap all sidebar item labels, breadcrumb text, and page headings in `t('...')` from `@wangs-ui/react-i18n`.

package/{skills → dist/skills/wangs-ui}/responsive-design/SKILL.md

@@ -10,7 +10,17 @@ Use this skill when building responsive pages, layouts, or screen adaptations wi
 
 ---
 
-## 1. Breakpoint Reference
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess responsive prop types or breakpoint keys. Query the MCP server dynamically:
+
+```json
+resolve_type_definition({ "types": ["ResponsiveValue", "Breakpoint", "SpacingKey"] })
+```
+
+---
+
+## 2. Breakpoint Reference
 
 Wangs UI uses three standardized breakpoints:
 
@@ -30,14 +40,17 @@ const { breakpoint } = useTheme(); // 'compact' | 'medium' | 'expanded'
 
 ---
 
-## 2. Responsive Props (`ResponsiveValue`)
+## 3. Responsive Props (`ResponsiveValue`)
 
 Visual scale props (`size`, layout `gap`, `columns`, `p`, `m`) accept either a single value or an object mapped by breakpoint:
 
 ```tsx
+import { Button } from '@wangs-ui/react-core/components/button';
+import { Grid, Stack } from '@wangs-ui/foundation/layout';
+
 // Static (identical across all devices)
 <Button size="md" />
-<Stack gap={4} />
+<Stack gap="4" />
 
 // Adaptive (changes across breakpoints)
 <Button size={{ compact: 'lg', expanded: 'sm' }} />
@@ -48,7 +61,7 @@ Visual scale props (`size`, layout `gap`, `columns`, `p`, `m`) accept either a s
 
 ---
 
-## 3. Conditional Rendering (`<Show>`)
+## 4. Conditional Rendering (`<Show>`)
 
 Use `<Show>` when a component should be mounted or unmounted based on the active breakpoint:
 
@@ -78,7 +91,7 @@ import { Show } from '@wangs-ui/foundation/theme';
 
 ---
 
-## 4. Spacing Conventions
+## 5. Spacing Conventions
 
 Spacing tokens are **flat and fixed** (1 unit = 4px):
 
@@ -87,7 +100,7 @@ Spacing tokens are **flat and fixed** (1 unit = 4px):
 
 ---
 
-## 5. Anti-Patterns to Avoid
+## 6. Anti-Patterns to Avoid
 
 1. **Avoid `hidden md:block` for stateful/heavy trees**: Always prefer `<Show>` so unused components cleanly unmount.
 2. **Never pass responsive objects to behavioral props**: `<Button disabled={{ compact: true }} />` is invalid.

package/{skills → dist/skills/wangs-ui}/universal-layout/SKILL.md

@@ -18,24 +18,15 @@ Do **NOT** guess layout prop names, spacing scales, or breakpoint keys. Query th
 server dynamically:
 
 ```json
-list_catalog({ "category": "layout" })
-get_component_api({ "id": "layout:box" })
-get_component_api({ "id": "layout:grid" })
-get_documentation({ "id": "layout-stack" })
-```
-
-Resolve shared types before writing responsive props:
-
-```json
-resolve_type_definition({ "name": "ResponsiveValue" })
-resolve_type_definition({ "name": "SpacingKey" })
+list_catalog({ "query": "layout" })
+resolve_type_definition({ "types": ["ResponsiveValue", "SpacingKey", "StackProps", "GridProps", "BoxProps", "ScrollAreaProps"] })
 ```
 
 ---
 
 ## 2. Choosing the Right Primitive
 
-1. **Stack (VStack)** — default for vertical flows (forms, cards, page sections).
+1. **Stack (Vertical)** — default for vertical flows (forms, cards, page sections).
    Fixed `column` direction, uniform `gap`, optional auto-`separator`.
 2. **HStack** — horizontal rows with vertical centering (avatar + label + action,
    toolbar clusters). Fixed `row` direction.
@@ -52,25 +43,26 @@ resolve_type_definition({ "name": "SpacingKey" })
    vertical rhythm (`space: 'sm' | 'md' | 'lg'`, default `'md'`). Never nest
    `Container` inside `Container`.
 7. **ZStack** — overlays (badge on card, status dot on avatar, hero overlay).
-8. **AspectRatio / Bleed / Spacer** — media frames (`ratio`), full-bleed breakouts
+8. **ScrollArea** — styled, accessible scrollable viewports (`orientation: 'vertical' | 'horizontal' | 'both'`, `variant: 'hover' | 'always' | 'scroll'`).
+9. **AspectRatio / Bleed / Spacer** — media frames (`ratio`), full-bleed breakouts
    inside padded containers (`Bleed`), and flexible fillers in stacks (`Spacer`).
 
 ---
 
 ## 3. Mandatory Implementation Rules
 
-1. **ResponsiveValue everywhere**: scalar for static (`gap={4}`), object for
-   adaptive (`gap={{ compact: 2, medium: 4, expanded: 6 }}`,
+1. **ResponsiveValue everywhere**: scalar for static (`gap="4"`), object for
+   adaptive (`gap={{ compact: '2', medium: '4', expanded: '6' }}`,
    `columns={{ compact: 1, medium: 2, expanded: 4 }}`). Breakpoints are
    `compact` (mobile-first base), `medium` (`md:`), `expanded` (`lg:`).
 2. **Separators, not manual dividers**: `<Stack separator={<Divider />}>` inserts
    dividers between children with no trailing element. Never hand-place a divider
    after every child.
-3. **Spacing scale**: `gap`/`p`/`m` use `SpacingKey` (Tailwind numeric scale,
-   1 unit = 4px). Never pass raw pixel strings to spacing props.
+3. **Spacing scale**: `gap`/`p`/`m` use `SpacingKey` (Tailwind numeric scale strings,
+   e.g. `'0'`, `'1'`, `'2'`, `'4'`, `'6'`, `'8'`, `'12'`, `'16'`). Never pass raw pixel strings to spacing props.
 4. **Strict subpath imports**:
    ```tsx
-   import { Stack, HStack, Grid, Container } from '@wangs-ui/foundation/layout';
+   import { Stack, HStack, Grid, Container, Box, Flex, ScrollArea } from '@wangs-ui/foundation/layout';
    ```
 5. **Translate visible labels** inside layout children via `t('...')` from
    `@wangs-ui/react-i18n` (layout props themselves are never translated).

package/dist/skills/wangs-ui/wangs-ui-components/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: wangs-ui-components
+description: MCP Discovery Protocol, modular subpath import map, and primitive substitution map for Wangs UI applications.
+metadata:
+  owner: wangs-ui
+---
+
+# Skill: Wangs UI Component Fundamentals & MCP Protocol
+
+Use this skill to navigate the Wangs UI ecosystem. **MCP is the single source of truth** for all component APIs, props, variants, slots, and examples. Do not hardcode or assume props — always query MCP dynamically.
+
+---
+
+## 1. The MCP Discovery Protocol (Single Source of Truth)
+
+Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Always query the MCP server dynamically:
+
+```mermaid
+graph TD
+    A[Identify Component / Primitive Needed] --> B[list_catalog to confirm name/id]
+    B --> C[get_component_api for typed contract]
+    B --> D[get_documentation for curated guidance]
+    C --> E{Need live story / variant code?}
+    D --> E
+    E -->|Yes| F[get_component_examples]
+    E -->|No| G[Implement with Subpath Import Map]
+    F --> G
+```
+
+### Discovery Steps:
+
+1. **Discover Catalog Entries**:
+   ```json
+   list_catalog({ "query": "button" })
+   list_catalog({ "category": "component" })
+   ```
+2. **Inspect Typed Contracts & Props** (`component` parameter):
+   ```json
+   get_component_api({ "component": "button" })
+   get_component_api({ "component": "datatable" })
+   get_component_api({ "component": "field" })
+   ```
+3. **Read Curated Narrative Documentation** (`id` parameter):
+   ```json
+   get_documentation({ "id": "button" })
+   get_documentation({ "id": "foundation" })
+   get_documentation({ "id": "form" })
+   ```
+4. **Fetch Live Storybook TSX Examples**:
+   ```json
+   get_component_examples({ "component": "button", "variant": "Sizes" })
+   get_component_examples({ "component": "datatable", "variant": "Basic" })
+   ```
+5. **Explore Knowledge Graph Relationships**:
+   ```json
+   query_graph({ "query": "DataTable" })
+   query_graph({ "query": "useForm" })
+   ```
+
+---
+
+## 2. Modular Subpath Import Map
+
+Always import via specific subpath modules to guarantee tree-shaking and avoid bundling entire packages:
+
+| Ecosystem Layer | Subpath Pattern | Example Imports |
+| :--- | :--- | :--- |
+| **Core Primitives** | `@wangs-ui/react-core/primitive/<name>` | `Button`, `Input`, `Select`, `DataTable`, `Dialog`, `Modal`, `Field`, `Form`, `Card`, `Badge` |
+| **Layout Primitives** | `@wangs-ui/foundation/layout` | `Stack`, `HStack`, `VStack`, `Flex`, `Grid`, `Box`, `Container`, `Section`, `ScrollArea` |
+| **Typography Primitives** | `@wangs-ui/foundation/theme` | `Text`, `Code`, `Kbd`, `Link`, `Blockquote`, `List`, `Mark` |
+| **Blocks & Shells** | `@wangs-ui/react-core/blocks/<name>` | `AppLayout`, `Sidebar`, `TableToolbar` |
+| **Form Engine** | `@wangs-ui/form/core`, `@wangs-ui/form/react` | Headless form state, hooks, validation adapters |
+| **Universal Navigation** | `@wangs-ui/react-navigation/web`, `@wangs-ui/react-navigation/native` | `buildGraph`, `paramRoute`, platform router bridges |
+| **Theme & Providers** | `@wangs-ui/react-core/api`, `@wangs-ui/foundation/theme` | `WangsUiProvider`, `ThemeProvider`, `useTheme` |
+| **Vector Icons** | `@wangs-ui/react-icons` | `SearchLine`, `AddLine`, `DeleteBin6Line`, `CheckLine` |
+| **i18n & Localization** | `@wangs-ui/react-i18n` | `useI18n`, `t`, `WangsUiI18nProvider` |
+
+---
+
+## 3. Primitive Substitution Map
+
+Zero raw HTML elements. Never write raw HTML tags when a Wangs UI primitive exists:
+
+| Forbidden Raw HTML | Mandatory Wangs UI Primitive | Import Path | MCP Catalog / Doc ID |
+| :--- | :--- | :--- | :--- |
+| `<button>` | `Button` | `@wangs-ui/react-core/primitive/button` | `button` |
+| `<input type="text">` | `Input` | `@wangs-ui/react-core/primitive/input` | `input` |
+| `<input type="number">` | `NumberInput` | `@wangs-ui/react-core/primitive/numberinput` | `numberinput` |
+| `<input type="checkbox">` | `Checkbox` | `@wangs-ui/react-core/primitive/checkbox` | `checkbox` |
+| `<select>` | `Select` / `MultiSelect` | `@wangs-ui/react-core/primitive/select` | `select`, `multiselect` |
+| `<textarea>` | `Textarea` | `@wangs-ui/react-core/primitive/textarea` | `textarea` |
+| `<form>` | `Form` / `DialogForm` | `@wangs-ui/react-core/primitive/form` | `form`, `dialogform` |
+| `<dialog>` / alert modal | `Modal` / `Dialog` | `@wangs-ui/react-core/primitive/modal` | `modal`, `dialog` |
+| `<table>` | `DataTable` | `@wangs-ui/react-core/primitive/datatable` | `datatable` |
+| `<div>` (layout / flex / grid) | `Stack`, `HStack`, `Flex`, `Grid`, `Box` | `@wangs-ui/foundation/layout` | `universal-layout` |
+| `<div>` (surface card) | `Card` | `@wangs-ui/react-core/primitive/card` | `card` |
+| Pill / status chip | `Badge` | `@wangs-ui/react-core/primitive/badge` | `badge` |
+| `<h1>` - `<h6>` | `<Text variant="...">` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<p>`, `<span>` (body text) | `<Text variant="...">` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<a>` | `Link` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<code>` | `Code` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<kbd>` | `Kbd` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<blockquote>` | `Blockquote` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<ul>`, `<ol>` | `List` | `@wangs-ui/foundation/theme` | `foundation` |