@wangs-ui/skills 1.3.0-alpha.2 → 1.3.0-alpha.21

package/dist/rules/wangs-ui/typescript-checklist-and-reference.md

@@ -0,0 +1,33 @@
+---
+trigger: model_decision
+description: "Apply when doing a final TypeScript review pass on a file."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Review Checklist & Quick Reference
+
+## Review Checklist
+
+Before considering TypeScript code "done," verify:
+
+- [ ] No `any` anywhere (including implicit `any` from missing annotations)
+- [ ] External/uncertain data enters as `unknown` and is narrowed before use
+- [ ] Variant state is a discriminated union, not optional fields + booleans
+- [ ] `interface` used for object/entity shapes; `type` used for unions/aliases/intersections
+- [ ] No stray `I` prefixes on interfaces
+- [ ] Naming follows casing conventions consistently
+- [ ] `as` / `!` are rare, justified, and can't be replaced by a guard or null check
+- [ ] Exported functions/methods have explicit return types
+- [ ] Switch statements over unions have an exhaustiveness (`never`) check
+- [ ] `tsconfig.json` includes the strictness baseline
+
+## Quick Reference
+
+| Situation                                      | Use                                                           |
+| ---------------------------------------------- | ------------------------------------------------------------- |
+| External/uncertain data                        | `unknown` + narrowing                                         |
+| "This value is definitely one of these shapes" | Discriminated union (`type`)                                  |
+| Object with identity, may be extended          | `interface`                                                   |
+| Union, intersection, tuple, mapped type        | `type`                                                        |
+| Need to prove a type through logic             | Type guard / narrowing                                        |
+| Tempted to write `any`                         | Stop — use `unknown`, a generic, or a local interface instead |

package/dist/rules/wangs-ui/typescript-discriminated-unions.md

@@ -0,0 +1,39 @@
+---
+trigger: model_decision
+description: "Apply when modeling a variant or multi-shape state in TypeScript."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Discriminated Unions for Variant State
+
+Whenever a value can be one of several distinct "shapes" (loading/success/error states, event types, API response variants), model it as a **discriminated union** with a literal tag field — never as a loose object with optional fields or boolean flags.
+
+```ts
+// ❌ Bad — booleans can contradict each other; unclear which fields are valid together
+interface FetchState {
+  isLoading: boolean;
+  isError: boolean;
+  data?: User;
+  error?: string;
+}
+
+// ✅ Good — only one shape is possible at a time, and the compiler enforces it
+type FetchState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User }
+  | { status: 'error'; error: string };
+
+function render(state: FetchState) {
+  switch (state.status) {
+    case 'success':
+      return state.data.name; // `data` is guaranteed to exist here
+    case 'error':
+      return state.error; // `error` is guaranteed to exist here
+    default:
+      return null;
+  }
+}
+```
+
+Use a consistent tag field name across a codebase (`kind`, `type`, or `status` — pick one and stick with it) so narrowing patterns stay predictable.

package/dist/rules/wangs-ui/typescript-explicit-return-types.md

@@ -0,0 +1,21 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing an exported function, class method, or public API surface in TypeScript."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Explicit Return Types on Exported Functions
+
+Inference is fine for local, private helpers, but exported functions, class methods, and anything forming a public API should declare an explicit return type. This prevents an internal implementation change from silently widening/narrowing the public contract.
+
+```ts
+// ❌ Return type is inferred and can silently drift
+export function getActiveUsers(users: User[]) {
+  return users.filter((u) => u.active);
+}
+
+// ✅ Explicit, intentional contract
+export function getActiveUsers(users: User[]): User[] {
+  return users.filter((u) => u.active);
+}
+```

package/dist/rules/wangs-ui/typescript-interface-vs-type.md

@@ -0,0 +1,39 @@
+---
+trigger: model_decision
+description: "Apply when deciding between `interface` and `type` for a new TypeScript declaration."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — `interface` vs `type`
+
+Both can describe object shapes, but they signal different intent. Default rule:
+
+| Use `interface` for...                                                     | Use `type` for...                                                          |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Object / entity shapes (a `User`, a `Product`, a component's `Props`)      | Unions (`"a" \| "b"`) and discriminated unions                             |
+| Public API contracts meant to be `implements`-ed by classes                | Intersections (`A & B`)                                                    |
+| Shapes that consumers may want to **extend/augment** (declaration merging) | Tuples (`[string, number]`)                                                |
+|                                                                            | Function types / callback signatures                                       |
+|                                                                            | Mapped, conditional, or utility-derived types (`Partial<T>`, `Pick<T, K>`) |
+|                                                                            | Aliasing a primitive or another type for readability                       |
+
+```ts
+// ✅ interface — an entity with identity, extendable
+interface User {
+  id: string;
+  email: string;
+  role: UserRole;
+}
+
+interface AdminUser extends User {
+  permissions: Permission[];
+}
+
+// ✅ type — union, alias, derived shape
+type UserRole = 'admin' | 'editor' | 'viewer';
+type UserId = User['id'];
+type PartialUser = Partial<User>;
+type Callback<T> = (value: T) => void;
+```
+
+Don't mix conventions arbitrarily within one file — if a shape is a plain data object that will never need a union/intersection, `interface` is the default; the moment it needs to express "one of several shapes," reach for `type`.

package/dist/rules/wangs-ui/typescript-literal-unions-vs-enums.md

@@ -0,0 +1,21 @@
+---
+trigger: model_decision
+description: "Apply when modeling a fixed set of string or numeric variants in TypeScript."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Prefer Literal Unions Over Numeric Enums
+
+String literal unions are simpler, tree-shake better, and produce clearer error messages than TypeScript `enum`. Reserve `enum` (or `as const` object maps) for cases that need reverse lookup or genuinely benefit from a namespaced runtime value.
+
+```ts
+// ✅ Preferred
+type OrderStatus = 'pending' | 'shipped' | 'delivered' | 'cancelled';
+
+// Acceptable when a namespaced runtime object is actually needed
+const OrderStatus = {
+  Pending: 'pending',
+  Shipped: 'shipped',
+} as const;
+type OrderStatus = (typeof OrderStatus)[keyof typeof OrderStatus];
+```

package/dist/rules/wangs-ui/typescript-naming-conventions.md

@@ -0,0 +1,23 @@
+---
+trigger: model_decision
+description: "Apply when naming a TypeScript type, variable, or constant."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Naming Conventions
+
+| Kind                                                       | Convention                                  | Example                             |
+| ---------------------------------------------------------- | ------------------------------------------- | ----------------------------------- |
+| Types, interfaces, classes, enums                          | `PascalCase`                                | `UserProfile`, `OrderStatus`        |
+| Interfaces                                                 | `PascalCase`, **no `I` prefix**             | `User`, not `IUser`                 |
+| Type aliases                                               | `PascalCase`                                | `type ApiResponse<T> = ...`         |
+| Variables, functions, methods, properties                  | `camelCase`                                 | `getUserById`, `isValid`            |
+| Booleans                                                   | `camelCase` with `is/has/should/can` prefix | `isLoading`, `hasPermission`        |
+| True constants (module-level, never reassigned, primitive) | `UPPER_SNAKE_CASE`                          | `MAX_RETRIES`, `DEFAULT_TIMEOUT_MS` |
+| Enum members                                               | `PascalCase`                                | `enum Status { Active, Archived }`  |
+| Generic type parameters (simple, single-purpose)           | Single uppercase letter                     | `T`, `K`, `V`, `E` for errors       |
+| Generic type parameters (multiple / non-obvious)           | Descriptive, prefixed with `T`              | `TInput`, `TOutput`, `TContext`     |
+| Discriminated union tag field                              | Consistent across the codebase              | `kind`, `type`, or `status`         |
+| Files with a single exported entity                        | Match the entity name                       | `UserProfile.ts`, `useAuth.ts`      |
+
+Naming should describe **intent**, not implementation — `fetchUser` not `getUserFromApiEndpoint`; `retryCount` not `numRetries2`.

package/dist/rules/wangs-ui/typescript-narrowing-over-casting.md

@@ -0,0 +1,43 @@
+---
+trigger: model_decision
+description: "Apply when narrowing an `unknown` or union-typed value in TypeScript."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — `unknown` + Narrowing, Not Casting
+
+Prefer proving a type through control flow over asserting it with `as`.
+
+## Narrowing techniques, in order of preference:
+
+1. **`typeof`** — primitives (`string`, `number`, `boolean`, `undefined`, `function`)
+2. **`instanceof`** — class instances, `Error`, `Date`, custom classes
+3. **`in`** — checking a property exists before accessing it on a union/unknown
+4. **User-defined type guards** — `function isUser(x: unknown): x is User`
+5. **Discriminated union tag checks** — `switch (value.kind) { ... }`
+6. **Exhaustiveness checks** — a `never`-typed default branch so adding a new variant is a compile error until every switch/if-chain handles it
+
+```ts
+// ✅ Type guard
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'email' in value;
+}
+
+// ✅ Exhaustiveness check
+function assertNever(x: never): never {
+  throw new Error(`Unhandled case: ${JSON.stringify(x)}`);
+}
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'square':
+      return shape.side ** 2;
+    default:
+      return assertNever(shape); // compile error if a variant is missed
+  }
+}
+```
+
+Type assertions (`as X`) and the non-null assertion (`!`) bypass this entirely — treat them as a last resort, not a shortcut.

package/dist/rules/wangs-ui/typescript-readonly-by-default.md

@@ -0,0 +1,23 @@
+---
+trigger: model_decision
+description: "Apply when declaring a TypeScript collection or object shape."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Readonly by Default
+
+Prefer immutable shapes unless mutation is intentional and localized.
+
+```ts
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+function config(values: readonly string[]) {
+  /* ... */
+}
+
+const ROLES = ['admin', 'editor', 'viewer'] as const;
+type UserRole = (typeof ROLES)[number];
+```

package/dist/rules/wangs-ui/typescript-tsconfig-strictness.md

@@ -0,0 +1,30 @@
+---
+trigger: model_decision
+description: "Apply when configuring or reviewing tsconfig.json compiler strictness options."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Baseline `tsconfig.json` Strictness
+
+Treat these as the non-negotiable floor for any project this rule touches:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictPropertyInitialization": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+`strict: true` alone enables the core group (`noImplicitAny`, `strictNullChecks`, etc.), but `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are commonly missed and close real gaps (array/object index access returning `T` instead of `T | undefined`; optional properties silently accepting `undefined` as an explicit value).

package/dist/rules/wangs-ui/typescript-zero-any.md

@@ -0,0 +1,36 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing any TypeScript type annotation."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Never Use `any`
+
+`any` is not "unknown type," it's "type checking off." It's contagious — once a value is `any`, everything it touches becomes unchecked too.
+
+- Never write `any` for parameters, return types, variables, or generics.
+- Use `unknown` for genuinely unknown external data (API responses, `JSON.parse`, catch clauses, third-party callbacks) and narrow it before use.
+- Use generics (`<T>`) when a function needs to work across types but preserve the relationship between input and output.
+- If a library ships untyped, write a minimal local type/interface for the surface area you actually use instead of reaching for `any`.
+
+```ts
+// ❌ Bad
+function parseConfig(json: any) {
+  return json.settings.theme; // no safety, no autocomplete, silent runtime crash
+}
+
+// ✅ Good
+function parseConfig(json: unknown): string {
+  if (
+    typeof json === 'object' &&
+    json !== null &&
+    'settings' in json &&
+    typeof (json as { settings: unknown }).settings === 'object'
+  ) {
+    // still narrow further or validate with a schema library (zod, valibot, etc.)
+  }
+  throw new Error('Invalid config shape');
+}
+```
+
+The only acceptable `any` is a well-justified, isolated, and commented one (e.g. interfacing with a genuinely untyped legacy module) — never a default.

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

@@ -0,0 +1,63 @@
+---
+name: craft-theme
+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
+---
+# Skill: Craft Theme
+
+Use this skill whenever the user asks to create, customize, or rebrand the color theme of an app built on `@wangs-ui/react-core` / `@wangs-ui/foundation` — "make the app's theme orange", "use our brand color #ff6b35", "add a new palette called sunset", etc.
+
+## The rule this skill exists to enforce
+
+**Never hand-write a 13-shade tonal ramp, and never hand-pick which shade pairs with which as a text/foreground color.** Wangs UI's own design system shipped with exactly that mistake for a while: hand-tuned palette files drifted from what the perceptual (OKLCH) generator would produce, which caused white text to render at 2.54:1 contrast on one brand's primary color — invisible-adjacent, and only caught by a dedicated audit. The generator and the contrast math it's paired with exist specifically so this class of bug can't happen again. Always reach for the CLI below instead of writing hex values yourself.
+
+## 1. Generate the palette
+
+```bash
+pnpm exec wangs-ui-generate-palette --name=<id> --primary=<#hex> [options] --out=<path>
+```
+
+- `--name` (required): identifier for the palette, e.g. `sunset`. Used for the exported const name (`sunsetPalette`) and, unless `--out` is given, the output filename (`sunset.ts`).
+- `--primary` (required): the brand/key hex color, e.g. `#ff6b35`.
+- Optional per-family overrides — omit any of these to let the generator harmoniously auto-derive it from `--primary` (secondary: boosted-lightness variant of primary's hue; tertiary: +60° hue rotation; general: near-neutral variant of primary's hue) or fall back to the generator's calibrated defaults (success/danger/warning/info):
+  `--secondary=#hex --tertiary=#hex --general=#hex --success=#hex --danger=#hex --warning=#hex --info=#hex`
+- `--out=<path>` (optional): where to write the file. Defaults to `./<name>.ts` in the current working directory — always pass an explicit `--out` pointing into the consumer app's own theme directory (e.g. `src/theme/sunset.ts`), don't rely on the default.
+
+If `@wangs-ui/foundation` isn't already a dependency of the project you're working in, install it first (`pnpm add @wangs-ui/foundation` or the project's equivalent) — the CLI ships as its `bin`.
+
+**The written file is chmod'd read-only (0o444) and headed with an AUTO-GENERATED / DO NOT EDIT BY HAND comment.** If a color needs to change, re-run the command (it clears the read-only bit, rewrites, and re-locks it) — never hand-edit a shade in the output, and never `chmod` it writable to bypass this. Note the read-only bit is a local filesystem attribute only; it is not preserved by git across clones, so it is a deterrent for the person/agent working in this checkout right now, not a hard guarantee for every future contributor.
+
+## 2. Wire it into the app
+
+The generated file exports a plain `Palette` object — pass it directly to `WangsUiProvider`'s `theme.palette` (or `theme.defaultPalette` for uncontrolled mode):
+
+```tsx
+import { WangsUiProvider } from '@wangs-ui/react-core/api';
+import preset from '@wangs-ui/react-presets/fixedasset'; // or whichever preset the app uses
+import { sunsetPalette } from './theme/sunset';
+
+const App = () => (
+  <WangsUiProvider configOptions={{ preset }} theme={{ palette: sunsetPalette, mode: 'light' }}>
+    <YourApp />
+  </WangsUiProvider>
+);
+```
+
+`theme.palette` also accepts a built-in palette name (`'blue' | 'emerald' | 'crimson' | 'carbon' | 'gold'`) or a raw hex string — a generated `Palette` object is the right choice once you have brand-specific secondary/tertiary/status colors to preserve, not just a single key color.
+
+## 3. Regenerating / evolving an existing custom palette
+
+To change a color, re-run the same command with a new hex for the family that changed — **always pass every family you want to keep**, not just the one changing, since each run is a full regeneration from the anchors you give it:
+
+```bash
+pnpm exec wangs-ui-generate-palette --name=sunset --primary=#ff6b35 --tertiary=#2a9d8f --out=src/theme/sunset.ts
+```
+
+## 4. If you're extending Wangs UI itself (contributing a new official palette)
+
+This is a different, rarer case than theming a consumer app — only relevant if you're working inside the `wangs-ui-react` monorepo itself and adding a 6th built-in palette alongside blue/emerald/crimson/carbon/gold:
+
+1. Run the generator with `--out` pointing at `packages/foundation/theme/tokens/palettes/<name>.ts`.
+2. Register it: add `'<name>'` to the `PaletteName` union and `paletteLoaders` map in `packages/foundation/theme/context/ThemeContext.tsx`, and re-export it from `packages/foundation/theme/tokens/palettes/index.ts`.
+3. Run the contrast regression suite before considering it done: `pnpm exec vitest run --config packages/foundation/vitest.config.ts` — it checks every semantic token pairing (including the new palette) against WCAG AA across both light and dark mode. See `packages/foundation/theme/tokens/COLOR_TOKEN_CONTRACT.md` for the full rule set this is checked against.

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

@@ -1,8 +1,9 @@
 ---
 name: create-form
 description: Form architecture, validation workflows, strongly-typed forms (useForm, useDialogForm, useWatchField), initialValues/reset lifecycle, and MCP discovery protocol for building forms and input controls with @wangs-ui/react-core.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Form Architecture & Validation Workflows
 
 Use this skill when building forms, data entry panels, modal forms, settings pages, or multipart forms in Wangs UI applications.
@@ -13,28 +14,36 @@ Use this skill when building forms, data entry panels, modal forms, settings pag
 
 Do **NOT** hardcode or guess prop names, component options, preset variations, or Storybook patterns in this document. Always retrieve component definitions, active props, and live Storybook implementations directly via MCP:
 
-### Component & Form Documentation Protocol:
+### Component & Form API Protocol:
+
+```json
+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:
 
 ```json
-get-documentation({ "id": "form" })
-get-documentation({ "id": "field" })
-get-documentation({ "id": "dialogform" })
-get-documentation({ "id": "input" })
-get-documentation({ "id": "numberinput" })
-get-documentation({ "id": "select" })
-get-documentation({ "id": "multiselect" })
-get-documentation({ "id": "datepicker" })
-get-documentation({ "id": "fileupload" })
+get_documentation({ "id": "form" })
+get_documentation({ "id": "dialogform" })
+get_documentation({ "id": "field" })
 ```
 
 ### Live Storybook & Interactive Behavior Protocol:
 
 ```json
-get-documentation-for-story({ "id": "form", "storyName": "Default" })
-get-documentation-for-story({ "id": "form", "storyName": "AsyncInitialValues" })
-get-documentation-for-story({ "id": "form", "storyName": "ConditionalFields" })
-get-documentation-for-story({ "id": "form", "storyName": "CascadingOptions" })
-get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
+get_component_examples({ "component": "form", "variant": "Default" })
+get_component_examples({ "component": "form", "variant": "AsyncInitialValues" })
+get_component_examples({ "component": "form", "variant": "ConditionalFields" })
+get_component_examples({ "component": "form", "variant": "CascadingOptions" })
+get_component_examples({ "component": "dialogform", "variant": "Default" })
 ```
 
 ### Knowledge Graph & Symbol Usages:
@@ -74,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/{skills → dist/skills/wangs-ui}/data-table/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: data-table
 description: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: DataTable Architecture & Integration Workflows
 
 Use this skill when implementing data grids, server-paginated tables, filterable listing views, or batch management interfaces with `@wangs-ui/react-core`.
@@ -13,24 +14,31 @@ 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({ "component": "datatable" })
+get_component_api({ "component": "exportbutton" })
+get_component_api({ "component": "filtercontainer" })
+get_component_api({ "component": "bulkactionbutton" })
+```
+
+### Read Curated Documentation:
 
 ```json
-get-documentation({ "id": "datatable" })
-get-documentation({ "id": "exportbutton" })
-get-documentation({ "id": "filtercontainer" })
-get-documentation({ "id": "bulkactionbutton" })
+get_documentation({ "id": "datatable" })
+get_documentation({ "id": "exportbutton" })
 ```
 
 ### Inspect Live Story Implementations:
 
 ```json
-get-documentation-for-story({ "id": "datatable", "storyName": "Basic" })
-get-documentation-for-story({ "id": "datatable", "storyName": "ServerPagination" })
-get-documentation-for-story({ "id": "datatable", "storyName": "Sortable" })
-get-documentation-for-story({ "id": "datatable", "storyName": "MultipleSelection" })
-get-documentation-for-story({ "id": "datatable", "storyName": "CustomColumn" })
-get-documentation-for-story({ "id": "exportbutton", "storyName": "WithTable" })
+get_component_examples({ "component": "datatable", "variant": "Basic" })
+get_component_examples({ "component": "datatable", "variant": "CursorPagination" })
+get_component_examples({ "component": "datatable", "variant": "Sortable" })
+get_component_examples({ "component": "datatable", "variant": "MultipleSelection" })
+get_component_examples({ "component": "datatable", "variant": "CustomColumn" })
+get_component_examples({ "component": "exportbutton", "variant": "WithTable" })
 ```
 
 ### Inspect Knowledge Graph & Usages:
@@ -47,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-documentation({ "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`)**:
@@ -62,7 +70,8 @@ The Wangs UI `DataTable` is built on a modular, headless-first architecture:
 
 ## 3. Mandatory Implementation Rules
 
-1. **Query MCP for Current Code Patterns**: Always run `get-documentation-for-story` for `datatable` before drafting code.
+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/{skills → dist/skills/wangs-ui}/dialog-modal/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: dialog-modal
 description: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Dialog, Modal & Overlay Workflows
 
 Use this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.
@@ -13,21 +14,29 @@ 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({ "component": "dialog" })
+get_component_api({ "component": "dialogform" })
+get_component_api({ "component": "modal" })
+get_component_api({ "component": "toast" })
+```
+
+### Read Curated Overlay Documentation:
 
 ```json
-get-documentation({ "id": "dialog" })
-get-documentation({ "id": "dialogform" })
-get-documentation({ "id": "modal" })
-get-documentation({ "id": "toast" })
+get_documentation({ "id": "dialog" })
+get_documentation({ "id": "dialogform" })
+get_documentation({ "id": "modal" })
 ```
 
 ### Inspect Live Story Implementations:
 
 ```json
-get-documentation-for-story({ "id": "dialog", "storyName": "Confirmation" })
-get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
-get-documentation-for-story({ "id": "modal", "storyName": "Default" })
+get_component_examples({ "component": "dialog", "variant": "RichHeaderFooter" })
+get_component_examples({ "component": "dialogform", "variant": "Default" })
+get_component_examples({ "component": "modal", "variant": "Default" })
 ```
 
 ### Inspect Knowledge Graph & Usages:

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

@@ -1,8 +1,9 @@
 ---
 name: i18n-usage
 description: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Application Internationalization & Formatting Protocol
 
 Use this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.
@@ -13,22 +14,29 @@ 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({ "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:
 
 ```json
-get-documentation({ "id": "languageswitcher" })
-get-documentation({ "id": "currencyinput" })
-get-documentation({ "id": "datepicker" })
-get-documentation({ "id": "select" })
-get-documentation({ "id": "datatable" })
+get_documentation({ "id": "languageswitcher" })
+get_documentation({ "id": "currencyinput" })
 ```
 
 ### Inspect Live Story Implementations:
 
 ```json
-get-documentation-for-story({ "id": "languageswitcher", "storyName": "Basic" })
-get-documentation-for-story({ "id": "currencyinput", "storyName": "Basic" })
-get-documentation-for-story({ "id": "datepicker", "storyName": "Default" })
+get_component_examples({ "component": "languageswitcher", "variant": "Default" })
+get_component_examples({ "component": "currencyinput", "variant": "Default" })
+get_component_examples({ "component": "datepicker", "variant": "Default" })
 ```
 
 ---
@@ -132,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,