@geomak/ui 7.19.0 → 7.20.0

package/.claude/commands/ui-auth-shell.md

@@ -0,0 +1,48 @@
+---
+description: Generate a complete authenticated app shell with SecureLayout, sidebar, routing, and optional Wizard tour
+---
+
+Generate an authenticated app shell for: **$ARGUMENTS**
+
+Parse the argument as `[AppName] [route1,route2,...]`. Examples:
+```
+VesOPS dashboard,vessels,settings,reports
+MyApp dashboard,users
+```
+
+AppName defaults to `App`. Routes default to `dashboard,settings`.
+
+## What this generates
+
+A single `AppRoutes.tsx` file (or updates an existing one) with:
+
+- `AppShell` with `TopBar` (brand + `ThemeSwitch`) and `sidebarSections`
+- `SecureLayout` parent route guarding all provided routes
+- Lazy-loaded placeholder pages for each route
+- `useRef` arrays + icon wrapper spans for a `Wizard` onboarding tour
+- A `Wizard` wrapping `AppShell` with `storageKey` based on the app name
+
+## Steps
+
+1. **Fetch the bootstrap code**: Call `get_app_bootstrap` with `router: true`
+   and the app name to get the reference implementation.
+
+2. **Call `get_component` for `secure-layout`** to confirm current prop names
+   (isAuthenticated, fallback, loadingFallback).
+
+3. **Generate `AppRoutes.tsx`** with:
+   - One `useRef<HTMLSpanElement>` per route for the Wizard tour
+   - `sidebarSections` array with one item per route; icon is a `<span ref={...}>` wrapping
+     an appropriate `<Icon.*>` (pick the most relevant icon per route name)
+   - `wizardSteps` array with title + description for each route
+   - `SecureLayout` wrapping all provided routes as child routes
+   - Each route uses `lazy(() => import('../pages/RouteNamePage'))` with a `Suspense` fallback
+   - `Wizard` wrapping `AppShell` with `steps={wizardSteps}` and `storageKey="{appName}-tour"`
+
+4. **Generate stub page files** for each route under `src/pages/` (e.g. `DashboardPage.tsx`)
+   if they do not already exist. Each stub is a minimal component with a heading.
+
+5. **Report** what was created and list:
+   - Which icons were guessed (developer may want to swap them)
+   - How to wire real authentication (what to replace the placeholder check with)
+   - How to add a route: duplicate an entry in `sidebarSections`, add a `useRef`, add a `wizardStep`, add a `<Route>`

package/.claude/commands/ui-bootstrap.md

@@ -0,0 +1,36 @@
+---
+description: Generate the full app bootstrap for a new project using OxygenUI
+---
+
+Bootstrap a new app using OxygenUI: **$ARGUMENTS**
+
+Parse the argument as an optional app name (e.g. `MyApp`, `VesOPS`). Defaults to `App`.
+
+## What this generates
+
+Four files that give a new project a working, production-ready shell:
+
+| File | Purpose |
+|---|---|
+| `src/main.tsx` | Entry point, mounts Bootstrap into the DOM |
+| `src/Bootstrap.tsx` | Full provider stack in the correct nesting order |
+| `src/approutes/AppRoutes.tsx` | AppShell + SecureLayout + lazy routes skeleton |
+| `src/utils/brandTokens.ts` | Token override object for custom branding |
+
+## Steps
+
+1. **Fetch the bootstrap code**: Call the `oxygen-ui` MCP tool `get_app_bootstrap`
+   with `router: true`, `reactQuery: true`, `customTheme: true`, and the app name.
+
+2. **Check what exists**: Before writing, check if any of the four target files
+   already exist. If they do, report the conflict and ask the user how to proceed
+   rather than overwriting.
+
+3. **Write the four files** with the content from the tool, substituting the app name
+   throughout (component names, display strings, localStorage keys).
+
+4. **Report** what was created and list the next steps:
+   - Add real routes to `AppRoutes.tsx`
+   - Wire real authentication (replace the `localStorage.getItem('token')` check)
+   - Populate `BRAND_TOKENS` if custom branding is needed
+   - Run `yarn add @tanstack/react-query react-router-dom` if not already installed

package/.claude/commands/ui-find.md

@@ -0,0 +1,12 @@
+---
+description: Search OxygenUI for components matching a description or use-case
+---
+
+Search OxygenUI for components that match: **$ARGUMENTS**
+
+1. Call the `oxygen-ui` MCP tool `find_component` with the argument as the query.
+2. Present the results as a concise table: **Name** · slug · category · description.
+3. For the top 1-2 results, briefly describe why they match and what the user
+   should look for in the docs (e.g. key props, integration patterns).
+4. If the search finds nothing, suggest alternative queries and offer to call
+   `list_components` to browse all available entries.

package/.claude/commands/ui-form.md

@@ -0,0 +1,38 @@
+---
+description: Generate a fully-wired OxygenUI Form from a field specification
+---
+
+Generate a wired OxygenUI form for: **$ARGUMENTS**
+
+Parse the argument as a space-separated list of `field-name:input-type` pairs.
+Append `?` to mark a field as optional (no required rule). Examples:
+
+```
+email:text name:text role:dropdown notify:switch terms:checkbox
+start:date end:date priority:slider tags:tags
+```
+
+Supported input types: `text`, `textarea`, `password`, `number`, `email`,
+`dropdown`, `switch`, `checkbox`, `radio`, `slider`, `date`, `daterange`,
+`time`, `tags`, `color`, `rating`, `autocomplete`, `treeselect`
+
+## Steps
+
+1. **Resolve binders**: For each field, call the `oxygen-ui` MCP tool
+   `get_form_binding` with the input type. This returns the correct binder
+   method, value type, and a paste-ready snippet.
+
+2. **Generate the form component**: Produce a self-contained React component:
+   - `useForm` with `defaultValues` typed to match each field
+   - One `FormField` per field with the correct binder
+   - Required rules on all non-optional (`?`) fields
+   - Email pattern rule if the type is `email`
+   - A submit `Button`
+   - `onFinish` stub with a `TODO` comment
+
+3. **Output inline**: Deliver the component as a code block. Do not write to a
+   file unless the user explicitly asks to save it.
+
+4. **Offer next steps**: After the form, suggest:
+   - Adding the form inside a Modal (`/ui-modal form-in-modal`)
+   - Making it part of a full page (`/ui-page crud EntityName`)

package/.claude/commands/ui-lookup.md

@@ -0,0 +1,13 @@
+---
+description: Look up a specific OxygenUI component, full props API and usage examples
+---
+
+Look up the OxygenUI component or hook: **$ARGUMENTS**
+
+1. Call the `oxygen-ui` MCP tool `get_component` with the appropriate slug.
+   If the slug is not obvious, call `find_component` first with the argument as
+   the query, then call `get_component` with the best-matching slug.
+2. Return the full documentation clearly formatted, props table, usage examples,
+   and any caveats or recipes that are relevant.
+3. If the component accepts children or sub-components (e.g. `Modal.Body`),
+   highlight the composition pattern.

package/.claude/commands/ui-modal.md

@@ -0,0 +1,50 @@
+---
+description: Generate the complete state + Modal setup for a named OxygenUI modal pattern
+---
+
+Generate a Modal pattern for: **$ARGUMENTS**
+
+Parse the argument as one of: `confirm-delete`, `form-in-modal`, `detail-view`, `alert`
+
+## Patterns
+
+### confirm-delete
+State + PopConfirm-style Modal for deleting a named item. Includes:
+- `open` + `target` state
+- `onDelete(item)` setter
+- `onConfirm` async handler with `useNotification` feedback
+- Full Modal JSX with cancel/confirm buttons
+
+### form-in-modal
+State + Modal containing a Form. Includes:
+- `open` + `selected` state (null = create, item = edit)
+- `openCreate` / `openEdit(item)` / `closeModal` helpers
+- `useEffect` to reset the form when `open` changes
+- Form with two example fields (developer fills in actual fields)
+- Modal with `onOk={form.submit}` wiring
+
+### detail-view
+Read-only Modal that displays a selected item's details. Includes:
+- `open` + `item` state
+- Trigger pattern
+- Modal with a descriptive layout (label/value pairs using Typography)
+
+### alert
+Simple informational Modal with a single confirm button and an optional icon.
+
+## Steps
+
+1. **Fetch component API**: Call `get_component` with slug `modal` to confirm
+   the current prop names (onClose vs onOpenChange may differ across versions).
+
+2. **Generate the pattern**: Produce the complete code block:
+   - State declarations (paste above the return statement)
+   - Helper functions
+   - The Modal JSX (paste into the render tree)
+   - Any supporting imports
+
+3. **Output inline** as a clearly labelled code block with sections:
+   `// --- STATE ---`, `// --- HANDLERS ---`, `// --- JSX ---`
+
+4. **Offer next steps**: Suggest wrapping the form-in-modal inside a full
+   CRUD page with `/ui-page crud EntityName`.

package/.claude/commands/ui-page.md

@@ -0,0 +1,36 @@
+---
+description: Scaffold a complete page component using OxygenUI patterns
+---
+
+Scaffold a complete page for: **$ARGUMENTS**
+
+Parse the argument as `<type> [EntityName]` where type is one of:
+`crud`, `dashboard`, `settings`, `detail`, `multi-step-form`
+
+EntityName is optional (e.g. `crud Vessel`, `detail Order`, `dashboard`).
+
+## Steps
+
+1. **Look up the pattern**: Call the `oxygen-ui` MCP tool `get_pattern` with the type
+   and entity name. This returns the full recipe: components needed, state to declare,
+   wiring steps, and a complete code example.
+
+2. **Resolve any unfamiliar props**: If the pattern uses a component whose API you are
+   not certain about, call `get_component` with the slug before writing code.
+
+3. **Determine the output path**
+   - Check if `src/pages/` exists; if not, check `src/views/` or `src/screens/`
+   - File name: `{EntityName}Page.tsx` (e.g. `VesselsPage.tsx`, `DashboardPage.tsx`)
+
+4. **Write the file**: Generate the complete, self-contained page component:
+   - TypeScript interface for the entity (if applicable)
+   - All imports from `@geomak/ui`
+   - All state declarations
+   - All event handlers wired up (create, edit, delete, save, etc.)
+   - Full JSX tree matching the pattern
+   - Replace all `api.*` calls with `TODO: replace with your API call`
+
+5. **Report** what was created and list:
+   - Which `api.*` calls need to be wired to real endpoints
+   - Which types/interfaces need to be expanded
+   - Any optional enhancements (e.g. "add Drawer instead of Modal for more context")

package/.claude/commands/ui-scaffold.md

@@ -0,0 +1,73 @@
+---
+description: Scaffold a new OxygenUI component, implementation + story + MDX guide
+---
+
+Scaffold a new OxygenUI component named: **$ARGUMENTS**
+
+Parse the argument as `ComponentName [category]` where category is optional
+(defaults to the most appropriate one based on the component name).
+
+## Steps
+
+1. **Plan**: Determine:
+   - Target directory: `src/components/{core|inputs|forms|layout|marketing}/`
+   - Story title: `"Category/ComponentName"`
+   - Whether the component wraps a Radix primitive or is fully custom
+
+2. **Check for overlap**, Call `find_component` to confirm no existing component
+   already covers this use case before creating anything.
+
+3. **Scaffold files**: Create the following three files:
+
+### `ComponentName.tsx`
+
+```tsx
+import React from 'react'
+
+export interface ComponentNameProps {
+  // props here
+  className?: string
+}
+
+export function ComponentName({ className, ...props }: ComponentNameProps) {
+  return (
+    <div className={className}>
+      {/* implementation */}
+    </div>
+  )
+}
+
+export default ComponentName
+```
+
+### `ComponentName.stories.tsx`
+
+```tsx
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import ComponentName from './ComponentName'
+
+const meta: Meta<typeof ComponentName> = {
+  title: 'Category/ComponentName',
+  component: ComponentName,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+}
+export default meta
+type Story = StoryObj<typeof ComponentName>
+
+export const Default: Story = {
+  args: {},
+}
+```
+
+### `src/docs/ComponentName.mdx`
+
+Use the MDX guide structure with HTML tables (not GFM markdown tables).
+Use the exported `th / td / td0 / tbl` style constants from Accordion.mdx as a template.
+
+4. **Export**, Add the new component to `src/index.ts` in the correct section
+   (Core components, Input components, etc.).
+
+5. **Report** what was created and what the developer should fill in next
+   (implementation logic, additional stories, tests).

package/.claude/commands/ui-story.md

@@ -0,0 +1,30 @@
+---
+description: Add or improve Storybook stories for an existing OxygenUI component
+---
+
+Add or improve Storybook stories for the OxygenUI component: **$ARGUMENTS**
+
+## Steps
+
+1. **Read the component**: Find and read:
+   - The component source file (`src/components/**/$ARGUMENTS.tsx` or similar)
+   - The existing story file if one exists
+   - The MDX guide if one exists in `src/docs/`
+
+2. **Identify gaps**: Look for:
+   - Props that have no story coverage
+   - State combinations (loading, error, empty, disabled)
+   - Controlled vs uncontrolled usage
+   - Composition patterns (compound components with sub-components)
+   - Responsive or theme-sensitive behaviour
+
+3. **Write stories** following the CSF3 format used throughout the codebase:
+   - `Default`: the simplest working example with sensible args
+   - One story per major variant or visual state
+   - Use `render` functions for complex compositions
+   - Use `play` functions only when testing interactions (focus, type, click)
+   - Prefer realistic content that reflects actual usage in the VesOPS portal
+
+4. **Verify** that story `title` matches the existing Storybook sidebar path.
+
+5. **Report** which stories were added and what each one demonstrates.

package/.claude/commands/ui-table.md

@@ -0,0 +1,38 @@
+---
+description: Generate a typed OxygenUI Table component with columns, actions, and optional CRUD wiring
+---
+
+Generate a typed Table for: **$ARGUMENTS**
+
+Parse the argument as `EntityName [col:type ...]`. Column type hints are optional.
+Examples:
+
+```
+Vessel name:string flag:string dwt:number status:badge actions:menu
+Order id:number customer:string total:number status:badge
+User
+```
+
+Column types: `string`, `number`, `boolean`, `badge`, `date`, `link`, `menu`
+- `badge` renders a `<Badge>` with tone based on the value
+- `menu` adds an actions column with Edit and Delete buttons + PopConfirm on delete
+- Any unlisted type defaults to a plain text renderer
+
+## Steps
+
+1. **Fetch Table API**: Call `get_component` with slug `table` to confirm the
+   exact `TableColumn<T>` shape and any props that have changed.
+
+2. **Generate the component**: Produce:
+   - TypeScript interface for the entity with all specified columns
+   - `TableColumn<Entity>[]` array with correct renderers for typed columns
+   - For `badge` columns: a `<Badge>` renderer with a sensible tone map
+   - For `menu` columns: Edit button + PopConfirm-wrapped Delete button, wired to
+     `onEdit` and `onDelete` callback props
+   - Table component with `hasSearch`, `pagination`, and `getRowKey={r => r.id}`
+
+3. **Output inline** as a complete, importable component.
+
+4. **Offer extensions**: After the output, offer to:
+   - Add a create/edit Modal + Form (`/ui-modal form-in-modal` or `/ui-page crud EntityName`)
+   - Wrap it in a full CRUD page (`/ui-page crud EntityName`)

package/.claude/skills/oxygen-ui/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: oxygen-ui
+description: >
+  Context skill for working with the OxygenUI (@geomak/ui) design system.
+  Equips Claude Code with knowledge about available components, tokens, import
+  patterns, and how to use the MCP server for real-time docs lookup.
+---
+
+# OxygenUI Design System
+
+You are working inside the `@geomak/ui` repository, a React component library
+built with Radix UI primitives, Tailwind CSS utilities, and a three-layer token
+system. Everything ships as tree-shakeable ESM.
+
+---
+
+## MCP server
+
+An `oxygen-ui` MCP server is configured in `.mcp.json`. Use its tools whenever
+you need to look up component APIs, prop tables, or design tokens.
+
+| Tool | When to call |
+|---|---|
+| `find_component` | Before writing any UI, check what the design system already has |
+| `get_component` | Get full props + examples for a specific component (use the slug) |
+| `list_components` | Browse all 100+ entries when unsure what exists |
+| `get_token` | Look up CSS custom properties by name or category prefix |
+| `get_pattern` | Get a full wired recipe for a page-level pattern (crud-list, dashboard, etc.) |
+| `get_form_binding` | Look up the correct `useForm` binder for any input component |
+| `compare_components` | Get a decision guide when choosing between similar components |
+| `get_app_bootstrap` | Get the full provider stack + app shell bootstrap code |
+
+**Always call `find_component` first.** OxygenUI ships 100+ components. Writing
+from scratch without checking is almost always redundant.
+
+---
+
+## Import pattern
+
+```tsx
+// Named imports from the main entry (tree-shakeable)
+import { Button, Modal, DataGrid, useExcel } from '@geomak/ui'
+
+// Styles: include once at app root
+import '@geomak/ui/styles'
+
+// Token values for JS/TS code
+import { vars, semanticTokens, palette } from '@geomak/ui/tokens'
+
+// Icons
+import { Icon } from '@geomak/ui'
+<Icon.Search size={20} />
+```
+
+---
+
+## Token system
+
+Three layers:
+
+| Layer | Use case |
+|---|---|
+| `palette` | Raw brand hex values |
+| `semanticTokens` | Resolved hex/px values in `{ light, dark, shared }` objects |
+| `vars` | CSS custom-property strings: `vars.color.accent`, `vars.radius.md` |
+
+### CSS custom properties (use in inline styles or SCSS)
+
+```tsx
+<div style={{
+  background: 'var(--color-surface)',
+  border: '1px solid var(--color-border)',
+  borderRadius: 'var(--radius-md)',
+  color: 'var(--color-foreground)',
+}}>
+```
+
+### Tailwind utilities
+
+| Utility | Token |
+|---|---|
+| `bg-surface` | `--color-surface` |
+| `bg-surface-raised` | `--color-surface-raised` |
+| `border-border` | `--color-border` |
+| `text-foreground` | `--color-foreground` |
+| `text-foreground-muted` | `--color-foreground-muted` |
+| `bg-accent` | `--color-accent` |
+| `text-accent-fg` | `--color-accent-foreground` |
+
+---
+
+## Form binder cheat sheet
+
+**This is the most common source of silent bugs.** Every `useForm` field must use
+the correct binder for its input type or values will not update.
+
+| Input component | Binder method | Value type stored |
+|---|---|---|
+| `TextInput`, `TextArea`, `Password`, `SearchInput` | `fieldNative` | `string` |
+| `NumberInput` | `fieldNative` | `number` |
+| `Switch`, `Checkbox` | `fieldChecked` | `boolean` |
+| `Dropdown`, `TreeSelect`, `AutoComplete` | `fieldTarget` | `key` or `key[]` |
+| `RadioGroup` | `field` | option value |
+| `Slider` | `field` | `number` or `[number, number]` |
+| `DatePicker`, `TimePicker` | `field` | `Date \| null` |
+| `DateRangePicker` | `field` | `{ from: Date; to: Date } \| null` |
+| `TagsInput` | `field` | `string[]` |
+| `ColorPicker` | `field` | `string` (hex) |
+| `Rating` | `field` | `number` |
+
+```tsx
+// Example: mixed form with correct binders
+const form = useForm({ defaultValues: { name: '', role: '', active: false, joined: null } })
+
+<Form form={form} onFinish={handleSubmit}>
+  <FormField name="name"><TextInput label="Name" {...form.fieldNative('name')} /></FormField>
+  <FormField name="role"><Dropdown label="Role" items={roles} {...form.fieldTarget('role')} /></FormField>
+  <FormField name="active"><Switch label="Active" {...form.fieldChecked('active')} /></FormField>
+  <FormField name="joined"><DatePicker label="Joined" {...form.field('joined')} /></FormField>
+</Form>
+```
+
+Call `get_form_binding` MCP tool when unsure which binder to use for a specific input.
+
+---
+
+## Component decision guide
+
+### Modal vs Drawer vs PopConfirm
+
+| Component | Use when |
+|---|---|
+| `Modal` | The action needs full attention; no background context helps (confirm, form submit) |
+| `Drawer` | User benefits from seeing the page behind (filter panel, row inspector, quick edit) |
+| `PopConfirm` | Inline destructive confirmation on a specific row/button; no overlay needed |
+
+Both Modal and Drawer share the same controlled API: `open` + `onClose` + `hasFooter` + `onOk` + `onCancel`.
+
+### Table vs DataGrid vs VirtualList vs List
+
+| Component | Use when |
+|---|---|
+| `Table` | Standard paginated, sortable, searchable data; editable cells optional |
+| `DataGrid` | Excel-like: column reorder/resize, bulk edits, copy-paste cell behaviour |
+| `VirtualList` | 10k+ rows where DOM count is the bottleneck; no built-in sort/filter |
+| List (custom) | Single-column items, icon + label, no comparison between columns |
+
+### Tabs vs SegmentedControl
+
+| Component | Use when |
+|---|---|
+| `Tabs` | Three or more sibling content panes; content is substantial |
+| `SegmentedControl` | Two to four compact mutually exclusive filter-style options |
+
+---
+
+## App bootstrap (provider nesting order)
+
+This order is required. Getting it wrong causes token overrides, notification
+portals, or dark mode to break silently.
+
+```tsx
+// main.tsx or Bootstrap.tsx
+import { ThemeProvider, NotificationProvider } from '@geomak/ui'
+import { QueryClientProvider, QueryClient } from '@tanstack/react-query'
+import { BrowserRouter } from 'react-router-dom'
+
+const queryClient = new QueryClient()
+
+export function Bootstrap() {
+  return (
+    <ThemeProvider colorScheme={colorScheme}>        {/* always outermost */}
+      <BrowserRouter>
+        <QueryClientProvider client={queryClient}>
+          <NotificationProvider>                     {/* must be inside ThemeProvider */}
+            <AppRoutes />
+          </NotificationProvider>
+        </QueryClientProvider>
+      </BrowserRouter>
+    </ThemeProvider>
+  )
+}
+```
+
+Dark mode toggle: maintain `colorScheme` state in Bootstrap, pass it to `ThemeProvider`,
+and also toggle `document.documentElement.classList.toggle('dark', isDark)` so that
+Tailwind dark utilities work inside portals that render outside the ThemeProvider div.
+
+Custom brand tokens (optional):
+
+```tsx
+const BRAND_TOKENS = {
+  '--color-accent': '#1A56DB',
+  '--color-accent-hover': '#1e429f',
+}
+
+<ThemeProvider colorScheme={colorScheme} theme={BRAND_TOKENS} darkTheme={BRAND_TOKENS}>
+```
+
+---
+
+## useNotification
+
+Must be used inside a component that is a descendant of `NotificationProvider`.
+
+```tsx
+import { useNotification } from '@geomak/ui'
+
+function MyPage() {
+  const notification = useNotification()
+
+  const onSave = async () => {
+    try {
+      await api.save(data)
+      notification.success({ title: 'Saved', description: 'Changes applied.', duration: 3000 })
+    } catch (err) {
+      notification.error({ title: 'Save failed', description: err.message, duration: 5000 })
+    }
+  }
+}
+```
+
+Methods: `notification.success`, `notification.info`, `notification.warning`, `notification.error`.
+All accept `{ title, description?, duration? }`.
+
+---
+
+## React Query integration
+
+Map React Query state to OxygenUI component props:
+
+```tsx
+const { data, isPending, isFetching, isError, refetch } = useQuery({ queryKey, queryFn })
+
+// First load: full skeleton
+if (isPending) return <SkeletonBox className="h-96 w-full" />
+
+// Error state
+if (isError) return <ErrorState onRetry={refetch} />
+
+// Background refetch: show spinner overlay on existing content (not a full skeleton)
+// isPending=false, isFetching=true means data is already on screen
+return (
+  <Table
+    data={data}
+    loading={isFetching && !isPending}  // subtle refetch indicator
+    columns={columns}
+  />
+)
+```
+
+For mutations:
+
+```tsx
+const mutation = useMutation({
+  mutationFn: api.create,
+  onSuccess: () => {
+    notification.success({ title: 'Created' })
+    queryClient.invalidateQueries({ queryKey })
+  },
+  onError: (err) => notification.error({ title: 'Failed', description: err.message }),
+})
+
+<Button loading={mutation.isPending} onClick={() => mutation.mutate(formData)}>
+  Save
+</Button>
+```
+
+---
+
+## SecureLayout + route guard pattern
+
+```tsx
+// AppRoutes.tsx
+import { AppShell, SecureLayout } from '@geomak/ui'
+import { Routes, Route, Navigate } from 'react-router-dom'
+
+function AppRoutes() {
+  return (
+    <AppShell topBar={<TopBar />} sidebarSections={sidebarSections}>
+      <Routes>
+        {/* Auth-gated routes: wrap parent Route with SecureLayout */}
+        <Route
+          element={
+            <SecureLayout
+              isAuthenticated={isAuthenticated}
+              fallback={<Navigate to="/login" replace />}
+              loadingFallback={null}
+            />
+          }
+        >
+          <Route path="/dashboard" element={<DashboardPage />} />
+          <Route path="/settings" element={<SettingsPage />} />
+        </Route>
+
+        <Route path="/login" element={<LoginPage />} />
+        <Route path="/" element={<Navigate to="/dashboard" replace />} />
+      </Routes>
+    </AppShell>
+  )
+}
+```
+
+---
+
+## Wizard + AppShell onboarding tour
+
+Wizard must WRAP AppShell (not be inside it) so it can overlay the full viewport.
+Refs for Wizard steps go on wrapper `<span>` elements inside the `icon` prop of each
+`SidebarItem`, because `SidebarItem` has no `ref` prop.
+
+```tsx
+const dashboardRef = useRef<HTMLSpanElement>(null)
+const settingsRef  = useRef<HTMLSpanElement>(null)
+
+const sidebarSections = [{
+  items: [
+    {
+      label: 'Dashboard',
+      href: '/dashboard',
+      icon: <span ref={dashboardRef}><Icon.Home size={18} /></span>,
+    },
+    {
+      label: 'Settings',
+      href: '/settings',
+      icon: <span ref={settingsRef}><Icon.Settings size={18} /></span>,
+    },
+  ],
+}]
+
+const wizardSteps = [
+  { target: dashboardRef, title: 'Dashboard', description: 'Your overview at a glance.' },
+  { target: settingsRef,  title: 'Settings',  description: 'Configure your preferences.' },
+]
+
+<Wizard steps={wizardSteps} storageKey="my-app-tour">
+  <AppShell topBar={...} sidebarSections={sidebarSections}>
+    <Routes>...</Routes>
+  </AppShell>
+</Wizard>
+```
+
+---
+
+## Page patterns reference
+
+| Pattern | Key components |
+|---|---|
+| **CRUD list** | Table + Modal (create/edit) + Form + useForm + PopConfirm + useNotification |
+| **Dashboard overview** | Statistic cards + Skeleton + Dropdown (filter) + optional chart cards |
+| **Settings / admin tabs** | Tabs + Form per panel + Switch/Dropdown + useNotification on save |
+| **Multi-step wizard form** | Stepper + Form (per step or sectioned) + validation before advancing |
+| **Detail / inspection page** | Tabs + Statistic + Timeline + Drawer (row inspector) + Badge |
+| **Authenticated app shell** | ThemeProvider + NotificationProvider + AppShell + SecureLayout + Wizard tour |
+
+Use `get_pattern` MCP tool for the full wired recipe (components + state + wiring steps + code example) for any of these.
+
+---
+
+## Key component patterns
+
+### ThemeProvider (required at app root)
+
+```tsx
+import { ThemeProvider } from '@geomak/ui'
+
+<ThemeProvider defaultTheme="system">
+  <App />
+</ThemeProvider>
+```
+
+### Modal
+
+```tsx
+import { Modal } from '@geomak/ui'
+
+const [open, setOpen] = useState(false)
+
+<Modal open={open} onClose={() => setOpen(false)} title="Confirm" onOk={handleOk}>
+  <p>Are you sure?</p>
+</Modal>
+```
+
+---
+
+## Storybook
+
+Stories live in `src/**/*.stories.tsx` (CSF3 format). The Storybook dev server
+is in `.claude/launch.json` as `"storybook"` (port 6006).
+
+Guide MDX files live in `src/docs/` (one per component).
+
+---
+
+## Repository conventions
+
+- Component source: `src/components/{core,inputs,forms,layout,marketing}/`
+- Hooks: `src/hooks/`
+- Story title format: `"Category/ComponentName"` or `"Category/ComponentName/Guide"`
+- All MDX guides use HTML tables (not GFM) with exported `th/td/td0/tbl` style constants
+- Commit convention: `fix:` (patch), `feat:` (minor), `docs:` (no bump); semantic-release runs in CI
+- Never bump `version` in `package.json` manually

package/README.md

@@ -137,53 +137,93 @@ The standard **gray / slate / zinc** ramps and **black** stay available alongsid
 
 ## AI toolchain (Claude Code)
 
-OxygenUI ships a built-in MCP server and a set of Claude Code skills and commands that let AI assistants look up component APIs, search by use-case, and scaffold new components, all grounded in the real MDX documentation.
+OxygenUI ships a built-in MCP server and a set of Claude Code skills and commands that let AI assistants look up component APIs, search by use-case, generate complete page components, and bootstrap entire apps, all grounded in the real MDX documentation.
+
+### Setup
+
+The toolchain has two parts: the **MCP server** (does the work) and the **commands + skill** (how you call it from Claude Code). Both can be installed at user scope (available in every project on your machine) or project scope (committed to the repo, shared with the whole team).
+
+#### Option A — User scope (recommended for individuals)
+
+Installs everything into `~/.claude/`. Available in every Claude Code session from that point on.
+
+```bash
+# 1. Install commands + skill + MCP server config in one shot
+npx --package=@geomak/ui@latest setup-claude
+
+# If you already have @geomak/ui installed locally:
+node node_modules/@geomak/ui/scripts/setup-claude.mjs
+```
+
+#### Option B — Project scope (recommended for teams)
+
+Commits the toolchain into the repo so every developer who clones it gets it automatically.
+
+```bash
+# 1. Install commands + skill + .mcp.json into the project directory
+npx --package=@geomak/ui@latest setup-claude --scope project
+
+# If you already have @geomak/ui installed locally:
+node node_modules/@geomak/ui/scripts/setup-claude.mjs --scope project
+
+# 2. Commit the generated files so your team gets them on clone
+git add .claude/ .mcp.json
+git commit -m "chore: add OxygenUI Claude Code toolchain"
+```
+
+Both options write a `.mcp.json` / `~/.claude/mcp.json` entry pointing to `https://oxygenui.com/mcp` alongside the commands and skill, so no manual config is needed. Restart Claude Code (or reload the MCP server list) after running.
+
+---
 
 ### MCP server
 
-The server is deployed alongside Storybook on Netlify as a Netlify Function at `/mcp`. It exposes four tools:
+The server is deployed alongside Storybook at `https://oxygenui.com/mcp` (Netlify Function). It exposes eight tools in two tiers.
+
+**Lookup tier** (docs + tokens):
 
 | Tool | What it does |
 |---|---|
 | `list_components` | Browse all 100+ components with slug, category, and description |
-| `get_component` | Fetch the full props API and usage examples for one component by slug |
+| `get_component` | Full props API and usage examples for one component by slug |
 | `find_component` | Keyword search across names, categories, and descriptions |
 | `get_token` | Look up CSS custom properties by name or category prefix |
 
-**Connect it:**
-
-```jsonc
-// .mcp.json (already in the repo, update the URL after first deploy)
-{
-  "mcpServers": {
-    "oxygen-ui": {
-      "type": "http",
-      "url": "https://your-site.netlify.app/mcp"
-    },
-    "oxygen-ui-local": {
-      "type": "http",
-      "url": "http://localhost:8888/mcp"
-    }
-  }
-}
-```
+**Generation tier** (patterns + code):
 
-Or add it from the CLI: `claude mcp add oxygen-ui --transport http https://your-site.netlify.app/mcp`
+| Tool | What it does |
+|---|---|
+| `get_pattern` | Full wired recipe for a page type: components, state, wiring steps, and a complete code example. Patterns: `crud-list`, `dashboard`, `settings-tabs`, `multi-step-form`, `detail-page`, `app-bootstrap` |
+| `get_form_binding` | Correct `useForm` binder for any input (`fieldNative` / `fieldChecked` / `fieldTarget` / `field`), with paste-ready snippet |
+| `compare_components` | Decision guide for similar components: Modal vs Drawer, Table vs DataGrid, Tabs vs SegmentedControl |
+| `get_app_bootstrap` | Full Bootstrap.tsx + AppRoutes.tsx + brandTokens.ts template for a new project |
 
 ### Claude Code commands
 
-Four slash commands are registered in `.claude/commands/`:
+Eight slash commands are available after setup:
+
+**Lookup commands:**
 
 | Command | Usage |
 |---|---|
-| `/ui-lookup <name>` | Fetch the full docs for a component, e.g. `/ui-lookup wizard` |
 | `/ui-find <query>` | Search by use-case, e.g. `/ui-find virtualized table` |
-| `/ui-scaffold <name>` | Scaffold a new component with source + story + MDX guide |
-| `/ui-story <name>` | Add story coverage for an existing component |
+| `/ui-lookup <name>` | Full docs for a component, e.g. `/ui-lookup wizard` |
+
+**Generation commands** (write real files into your project):
+
+| Command | Usage |
+|---|---|
+| `/ui-page <type> [entity]` | Scaffold a complete page file. Types: `crud`, `dashboard`, `settings`, `detail`, `multi-step-form`. Example: `/ui-page crud Vessel` |
+| `/ui-bootstrap [name]` | Generate the four-file app bootstrap (Bootstrap.tsx, AppRoutes.tsx, brandTokens.ts, main.tsx) |
+| `/ui-form <field:type ...>` | Generate a fully-wired Form from a field spec, e.g. `/ui-form name:text role:dropdown active:switch` |
+| `/ui-table <entity> [col:type]` | Typed Table with column renderers + actions, e.g. `/ui-table Vessel name:string flag:string status:badge actions:menu` |
+| `/ui-modal <type>` | Complete state + Modal JSX. Types: `confirm-delete`, `form-in-modal`, `detail-view`, `alert` |
+| `/ui-auth-shell [name] [routes]` | Full SecureLayout + AppShell + Wizard tour shell, e.g. `/ui-auth-shell VesOPS dashboard,vessels,settings` |
+
+Two additional library commands (`/ui-scaffold`, `/ui-story`) are available inside the `oxygen-ui` repository itself for contributors.
 
 ### Context skill
 
-The `/oxygen-ui` skill loads the full design system context into any Claude Code session, import patterns, token usage, Tailwind utilities, form API, and repository conventions. Invoke it at the start of any session where you plan to build against `@geomak/ui`.
+The `/oxygen-ui` skill (installed by the setup script) loads the full design system context into any Claude Code session: import patterns, form binder cheat sheet, component decision guide, provider nesting order, React Query integration, and page pattern reference. Invoke it at the start of any session where you plan to build against `@geomak/ui`.
 
 ### Local development with the MCP server
 
@@ -196,7 +236,7 @@ The function is then available at `http://localhost:8888/mcp`. Claude Code picks
 
 ### How the manifest is built
 
-At build time, `scripts/generate-ai-manifest.mjs` scans all 101 MDX guide files in `src/docs/` and the co-located MDX files in `src/components/`, strips Storybook boilerplate, and emits `netlify/functions/ai-manifest.json`. The Netlify Function bundles this JSON via esbuild, no database, no runtime file I/O, no cold-start penalty.
+At build time, `scripts/generate-ai-manifest.mjs` scans all MDX guide files in `src/docs/` and co-located MDX files in `src/components/`, strips Storybook boilerplate, and emits `netlify/_data/ai-manifest.js`. The Netlify Function bundles this via esbuild at deploy time. No database, no runtime file I/O, no cold-start penalty.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geomak/ui",
-  "version": "7.19.0",
+  "version": "7.20.0",
   "description": "Oxygen Design System, reusable UI primitives built with Radix UI behaviours and Tailwind CSS styling",
   "author": "G-MAKROGLOU",
   "license": "MIT",
@@ -27,8 +27,14 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "setup-claude": "scripts/setup-claude.mjs"
+  },
   "files": [
-    "dist"
+    "dist",
+    ".claude/commands",
+    ".claude/skills",
+    "scripts/setup-claude.mjs"
   ],
   "sideEffects": [
     "**/*.css"
@@ -40,6 +46,7 @@
     "dev": "tsup --watch",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
+    "setup-claude": "node scripts/setup-claude.mjs",
     "generate-manifest": "node scripts/generate-ai-manifest.mjs",
     "mcp:dev": "node scripts/generate-ai-manifest.mjs && netlify dev",
     "typecheck": "tsc --noEmit",

package/scripts/setup-claude.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Sets up the OxygenUI Claude Code integration.
+ * Copies commands + skill to the target scope, and writes the MCP server entry.
+ *
+ * Usage:
+ *   npx --package=@geomak/ui@latest setup-claude             # user scope (default)
+ *   npx --package=@geomak/ui@latest setup-claude --scope project
+ */
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = join(__dirname, '..')
+
+// ─── Args ─────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2)
+const scopeIdx = args.indexOf('--scope')
+const scope = scopeIdx !== -1 ? args[scopeIdx + 1] : 'user'
+
+if (scope !== 'user' && scope !== 'project') {
+  console.error('Error: --scope must be "user" or "project"')
+  process.exit(1)
+}
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+
+const CONSUMER_COMMANDS = [
+  'ui-find',
+  'ui-lookup',
+  'ui-page',
+  'ui-bootstrap',
+  'ui-form',
+  'ui-table',
+  'ui-modal',
+  'ui-auth-shell',
+]
+
+const targetBase  = scope === 'user' ? homedir() : process.cwd()
+const claudeDir   = join(targetBase, '.claude')
+const commandsDir = join(claudeDir, 'commands')
+const skillDir    = join(claudeDir, 'skills', 'oxygen-ui')
+const mcpFile     = scope === 'user'
+  ? join(claudeDir, 'mcp.json')
+  : join(process.cwd(), '.mcp.json')
+
+const srcCommandsDir = join(PACKAGE_ROOT, '.claude', 'commands')
+const srcSkillFile   = join(PACKAGE_ROOT, '.claude', 'skills', 'oxygen-ui', 'SKILL.consumer.md')
+const srcSkillFallback = join(PACKAGE_ROOT, '.claude', 'skills', 'oxygen-ui', 'SKILL.md')
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf-8')) } catch { return null }
+}
+
+function writeJson(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n')
+}
+
+function ok(msg)   { console.log(`  \x1b[32m+\x1b[0m ${msg}`) }
+function warn(msg) { console.warn(`  \x1b[33m!\x1b[0m ${msg}`) }
+function info(msg) { console.log(`    ${msg}`) }
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+console.log('\nOxygenUI Claude Code setup\n')
+console.log(`Scope: ${scope === 'user' ? 'user (~/.claude)' : `project (${process.cwd()})`}\n`)
+
+console.log('Commands:')
+mkdirSync(commandsDir, { recursive: true })
+
+for (const name of CONSUMER_COMMANDS) {
+  const src  = join(srcCommandsDir, `${name}.md`)
+  const dest = join(commandsDir, `${name}.md`)
+  if (!existsSync(src)) {
+    warn(`source not found, skipping: ${name}.md`)
+    continue
+  }
+  copyFileSync(src, dest)
+  ok(`/${name}`)
+}
+
+// ─── Skill ────────────────────────────────────────────────────────────────────
+
+console.log('\nSkill:')
+mkdirSync(skillDir, { recursive: true })
+
+const skillSrc = existsSync(srcSkillFile) ? srcSkillFile : srcSkillFallback
+if (!existsSync(skillSrc)) {
+  warn('SKILL.md not found in package, skipping skill')
+} else {
+  copyFileSync(skillSrc, join(skillDir, 'SKILL.md'))
+  ok('/oxygen-ui skill')
+}
+
+// ─── MCP server ───────────────────────────────────────────────────────────────
+
+console.log('\nMCP server:')
+mkdirSync(dirname(mcpFile), { recursive: true })
+
+const existing = readJson(mcpFile) ?? {}
+if (!existing.mcpServers) existing.mcpServers = {}
+
+if (existing.mcpServers['oxygen-ui']) {
+  warn('oxygen-ui entry already exists in ' + mcpFile + ', updating URL')
+}
+
+existing.mcpServers['oxygen-ui'] = {
+  type: 'http',
+  url: 'https://oxygenui.com/mcp',
+}
+
+writeJson(mcpFile, existing)
+ok(`oxygen-ui server -> ${mcpFile}`)
+
+// ─── Done ─────────────────────────────────────────────────────────────────────
+
+console.log('\n\x1b[32mDone.\x1b[0m\n')
+
+if (scope === 'user') {
+  info('The commands, skill, and MCP server are now available in every Claude Code session.')
+  info('Restart Claude Code (or reload the MCP server list) to pick up the new server.')
+} else {
+  info('Commands and skill are in .claude/ and the MCP server is in .mcp.json.')
+  info('Commit both directories so every team member gets the tooling when they clone.')
+  info('')
+  info('Each developer still needs Claude Code installed:')
+  info('  npm install -g @anthropic-ai/claude-code')
+}
+
+console.log()