diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..167b818
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,157 @@
+# GNexus UI Kit — AI Agent Reference
+
+When working on a Vue project that depends on `gnexus-ui-kit`, **always use the official Vue adapter components** instead of writing raw HTML/CSS markup. This document is the single source of truth for which components exist and when to use them.
+
+## Golden Rule
+
+> Prefer `gnexus-ui-kit/vue` components. Do not recreate modal, drawer, tab, toast, form, button, or table markup manually unless the adapter does not expose the needed component yet.
+
+## Required Setup (once per app)
+
+```js
+import "gnexus-ui-kit/dist/css/kit.css";
+import "gnexus-ui-kit/dist/assets/fonts/phosphor-icons/src/css/icons.css";
+```
+
+## Import Pattern
+
+Named imports (preferred):
+
+```js
+import { GnButton, GnInput, GnModal } from "gnexus-ui-kit/vue";
+```
+
+Global registration:
+
+```js
+import { GnexusUiVue } from "gnexus-ui-kit/vue";
+app.use(GnexusUiVue);
+```
+
+## Icon Naming
+
+All icon props **must** use the `ph-` prefix. Phosphor Icons are the only supported icon set.
+
+```js
+// Correct
+icon="ph-house"
+icon="ph-plus"
+icon="ph-bold ph-spinner" // multiple classes allowed
+
+// Wrong — will trigger a dev warning and may not render
+icon="house"
+icon="plus"
+```
+
+## Component Catalog
+
+| Need | Component | Props you will use |
+|------|-----------|-------------------|
+| Button | `GnButton` | `variant`, `size`, `icon`, `loading`, `disabled` |
+| Icon-only button | `GnIconButton` | `icon`, `label` |
+| Status label | `GnBadge` | `variant`, `outline` |
+| Message block | `GnAlert` | `variant` |
+| Card / panel | `GnCard` | `title` (slot), `footer` (slot) |
+| Page title bar | `GnPageHeader` | `kicker`, `title`, `subtitle`, `meta`, `actions` (slot) |
+| Text field | `GnInput` | `v-model`, `label`, `icon`, `state`, `help` |
+| Textarea | `GnTextarea` | `v-model`, `label`, `state`, `help` |
+| Select dropdown | `GnSelect` | `v-model`, `label`, `options` |
+| Checkbox | `GnCheckbox` | `v-model`, `label`, `disabled` |
+| Toggle switch | `GnSwitch` | `v-model`, `label`, `disabled` |
+| Radio | `GnRadio` / `GnRadioGroup` | `v-model`, `options` |
+| Range slider | `GnRange` | `v-model`, `label`, `min`, `max` |
+| File upload | `GnFileUpload` | `v-model`, `badge`, `multiple`, `accept` |
+| Searchable select | `GnCombobox` | `v-model`, `label`, `options`, `placeholder` |
+| Tabs | `GnTabs` | `v-model`, `items` |
+| Router tabs | `GnRouterTabs` | `items` (with `to`), `activeMatch` |
+| Accordion | `GnAccordion` | `items`, `v-model`, `multiple` |
+| Modal dialog | `GnModal` | `v-model:open`, `title`, `closeOnBackdrop` |
+| Side drawer | `GnDrawer` | `v-model:open`, `title`, `position` |
+| Toasts | `GnToastProvider` + `useToast` | Wrap app once; call `toast.success({ title, text })` |
+| Confirm dialog | `GnConfirmDialog` | `v-model:open`, `title`, `message`, `confirmVariant` |
+| Table | `GnTable` | `columns`, `rows`, `caption`, `emptyText` |
+| Toolbar | `GnToolbar` | `title`, `meta`, `actions` (slot) |
+| Input group | `GnInputGroup` | `addon` (slot), `action` (slot) |
+| Search field | `GnSearchField` | `v-model` |
+| Pagination | `GnPagination` | `page`, `total-pages` |
+| Empty state | `GnEmptyState` | `title`, `text`, `icon`, `actions` (slot) |
+| Skeleton loader | `GnSkeleton` | — |
+| Key-value list | `GnDescriptionList` | `items` |
+| Progress bar | `GnProgress` | `value`, `label`, `animated` |
+| Usage meter card | `GnUsageMeter` | `value`, `label`, `max` |
+| Staged progress | `GnProgressStages` | `items` |
+| Wizard steps | `GnSteps` | `items`, `current` |
+| Chip / tag | `GnChip` | `variant`, `selected`, `removable` |
+| Chip group | `GnChipGroup` | — |
+| Avatar | `GnAvatar` | `initials`, `icon`, `image`, `size`, `status` |
+| Identity row | `GnIdentity` | `title`, `meta`, `avatar` props |
+| Avatar stack | `GnAvatarStack` | `items` |
+| Timeline | `GnTimeline` | `items` |
+| Activity log | `GnActivityLog` | `items` |
+| Basic list | `GnList` | `items` |
+| Definition list | `GnDefinitionList` | `items` |
+| Action list | `GnActionList` | `items` |
+| Loader / spinner | `GnLoader` | — |
+| Status card | `GnStatusCard` | `variant`, `title`, `meta` |
+| Metric card | `GnMetricCard` | `title`, `value`, `trend` |
+| Action card | `GnActionCard` | `title`, `text`, `actions` (slot) |
+| Dropdown menu | `GnDropdown` | `items`, `label`, `variant` |
+| Popover panel | `GnPopover` | `title`, `text`, `label` |
+| Tooltip | `GnTooltip` | `text` |
+| Navigation list | `GnNavList` | `items` |
+| App shell | `GnNavigationShell` | `brand`, `items`, `current`, `footerLeft`, `footerRight` |
+
+## Variants
+
+Use only these variant names:
+
+```
+primary, secondary, accent, success, warning, danger, error, info
+```
+
+`danger` and `error` render the same color in most components.
+
+## What NOT to do
+
+- Do **not** copy raw modal markup from demo partials into Vue apps.
+- Do **not** call `GNexusUIKit.Modals.create()` from Vue components.
+- Do **not** call `GNexusUIKit.Overlays.init()` or `GNexusUIKit.NavigationShell.init()` in Vue projects.
+- Do **not** run `Accordion.init()` or `Tabs.init()` inside Vue components.
+- Do **not** use the legacy `advancedSelect()` helper in Vue; use `GnCombobox`.
+- Do **not** use `InputPatterns.init()` for Vue file upload previews; use `GnFileUpload`.
+- Do **not** invent new variant names.
+- Do **not** duplicate GNexus CSS in scoped `
+
+
+
+
+
+
+
+