xertica-ui 2.1.3 → 2.1.4

package/templates/guidelines/Guidelines.md

@@ -1,325 +1,325 @@
-# Project Guidelines — Xertica UI App
-
-> **Scope**: These guidelines apply to React applications scaffolded with `npx xertica-ui@latest init`. They define the FSD/FDA architecture, import conventions, component rules, and AI agent behavior for this project.
->
-> **AI agents**: Read this file first. Then read `node_modules/xertica-ui/llms-compact.txt` for component reference, and `node_modules/xertica-ui/docs/decision-tree.md` before choosing between similar components.
-
----
-
-## 1. Architecture — Feature-Sliced Design + Feature-Driven Architecture
-
-This project follows **FSD (Feature-Sliced Design)** layered architecture combined with **FDA (Feature-Driven Architecture)** vertical slicing. Layers can only import from layers below them.
-
-```
-src/
-├── app/                          # Layer 1 — Application shell (imports from all layers)
-│   ├── App.tsx                   # XerticaProvider + BrowserRouter + AuthGuard
-│   └── components/
-│       ├── AppLayout.tsx         # Sidebar + children + optional XerticaAssistant
-│       └── AuthGuard.tsx         # Auth state management + all route definitions
-│
-├── shared/                       # Layer 2 — Shared utilities (no business domain)
-│   ├── config/
-│   │   └── navigation.ts         # RouteConfig type, routes[], getRouteByPath()
-│   ├── lib/
-│   │   └── auth.ts               # getStoredUser, storeUser, clearStoredUser
-│   └── types/
-│       └── auth.ts               # User interface
-│
-├── features/                     # Layer 3 — Vertical slices by business capability
-│   ├── auth/
-│   │   ├── index.ts              # Public barrel — import from here, never from /ui/*
-│   │   └── ui/
-│   │       ├── AuthPageShell.tsx         # Split-screen layout for auth pages
-│   │       ├── SocialLoginButtons.tsx    # Google / MT Login / gov.br buttons
-│   │       ├── LoginContent.tsx
-│   │       ├── ForgotPasswordContent.tsx
-│   │       ├── VerifyEmailContent.tsx
-│   │       └── ResetPasswordContent.tsx
-│   ├── home/
-│   │   ├── index.ts
-│   │   └── ui/
-│   │       └── HomeContent.tsx
-│   └── template/
-│       ├── index.ts
-│       └── ui/
-│           ├── TemplateContent.tsx
-│           └── FormTemplate.tsx
-│
-├── pages/                        # Layer 4 — Route entrypoints (thin wrappers only)
-│   ├── LoginPage.tsx
-│   ├── ForgotPasswordPage.tsx
-│   ├── VerifyEmailPage.tsx
-│   ├── ResetPasswordPage.tsx
-│   ├── HomePage.tsx              # AppLayout + HomeContent + XerticaAssistant
-│   └── TemplatePage.tsx          # AppLayout + TemplateContent + XerticaAssistant
-│
-└── styles/                       # Visual tokens and Tailwind entry
-    ├── index.css                 # Imports: xertica-ui/style.css, tokens.css, @source
-    └── xertica/
-        └── tokens.css            # Brand CSS variables — edit here to customize theme
-```
-
----
-
-## 2. Layer Responsibilities
-
-### `app/`
-Initializes the application. Contains only providers, the router, `AuthGuard` (auth state + routes), and `AppLayout` (layout shell). No business logic here.
-
-### `shared/`
-Framework-agnostic code with no business domain: primitive types, localStorage helpers, navigation config. Importable by any layer. Must not import from `features/` or `pages/`.
-
-### `features/`
-Each feature is a self-contained vertical slice. The `index.ts` is the only public interface — always import from the barrel, never from internal paths:
-
-```tsx
-// ✅ Correct
-import { LoginContent } from '../features/auth';
-
-// ❌ Wrong — never import from internal feature paths
-import { LoginContent } from '../features/auth/ui/LoginContent';
-```
-
-Features must not import from each other. If two features share code, extract it to `shared/`.
-
-### `pages/`
-Thin route wrappers that compose `AppLayout` + feature content + optional `XerticaAssistant`. No logic, no state, no API calls here:
-
-```tsx
-// ✅ Correct — thin wrapper
-export function HomePage({ user, onLogout }: PageProps) {
-  const { assistenteExpanded, toggleAssistente } = useLayout();
-  return (
-    <AppLayout user={user} onLogout={onLogout} assistant={<XerticaAssistant ... />}>
-      <HomeContent user={user} onLogout={onLogout} />
-    </AppLayout>
-  );
-}
-```
-
----
-
-## 3. Import Rules
-
-Always use the correct `xertica-ui` subpath for the layer you are in:
-
-```tsx
-// shared/ui → UI primitives
-import { Button, Card, Input, Badge, Table, Dialog, Select } from 'xertica-ui/ui';
-
-// app layer → providers and brand
-import { XerticaProvider, XerticaLogo, ThemeToggle }        from 'xertica-ui/brand';
-
-// features/layout → navigation shell
-import { Sidebar, Header }                                   from 'xertica-ui/layout';
-
-// features/assistant → AI assistant
-import { XerticaAssistant, generateDemoResponse }            from 'xertica-ui/assistant';
-
-// features/media → media players
-import { VideoPlayer, AudioPlayer }                          from 'xertica-ui/media';
-
-// shared/lib → hooks and contexts
-import { useLayout, useOptionalLayout, useTheme }            from 'xertica-ui/hooks';
-
-// styles → imported once by src/styles/index.css
-import 'xertica-ui/style.css';
-```
-
-Icons always come from `lucide-react` — never from `xertica-ui`:
-
-```tsx
-import { Home, Settings, Plus, Trash2, ChevronRight } from 'lucide-react';
-```
-
----
-
-## 4. Adding a New Route (Step-by-Step)
-
-1. **Create the feature content** — `src/features/<name>/ui/<NameContent>.tsx`
-2. **Export from the barrel** — add to `src/features/<name>/index.ts`
-3. **Create the page** — `src/pages/<NamePage>.tsx` (thin AppLayout wrapper)
-4. **Register the route** — add to `routes` array in `src/shared/config/navigation.ts`:
-
-   ```ts
-   import { MyIcon } from 'lucide-react';
-   
-   export const routes: RouteConfig[] = [
-     { path: '/home', label: 'Home', icon: Home },
-     { path: '/my-feature', label: 'My Feature', icon: MyIcon }, // ← add here
-   ];
-   ```
-
-5. **Register the `<Route>`** — add to `src/app/components/AuthGuard.tsx`:
-
-   ```tsx
-   import { MyFeaturePage } from '../../pages/MyFeaturePage';
-   
-   // inside <Routes>:
-   <Route path="/my-feature" element={
-     <ProtectedRoute user={user}>
-       <MyFeaturePage user={user} onLogout={handleLogout} />
-     </ProtectedRoute>
-   } />
-   ```
-
-6. **Add a navigation card** to `HomeContent.tsx` if it's a primary module.
-
----
-
-## 5. Non-Negotiable Rules
-
-### HTML — never use raw elements for UI
-
-| ❌ Never | ✅ Always |
-|---|---|
-| `<button>` | `<Button>` from `xertica-ui/ui` |
-| `<input>` | `<Input>` from `xertica-ui/ui` |
-| `<select>` | `<Select>` from `xertica-ui/ui` |
-| `<h1>` / `<h2>` for page headers | `<PageHeader><PageHeaderHeading>` from `xertica-ui/ui` |
-| `<div class="card ...">` | `<Card>` from `xertica-ui/ui` |
-| custom scrollable div | `<ScrollArea>` from `xertica-ui/ui` |
-
-### Colors — context-dependent rules
-
-| ❌ Never (any context) | Reason |
-|---|---|
-| `#3b82f6`, `rgb(59, 130, 246)`, `hsl(...)` | Raw values — non-themeable |
-| `style={{ color: '#...' }}` for theming | Non-themeable inline style |
-
-| ❌ Wrong for semantic/status contexts | ✅ Required instead |
-|---|---|
-| `bg-red-500` / `text-red-500` for errors | `bg-destructive` / `text-destructive` |
-| `bg-green-500` for success states | `bg-success` |
-| `bg-yellow-500` for warnings | `bg-warning` |
-
-> For **layout, spacing, and general non-semantic UI** (custom components, decorative elements where no semantic token applies), standard Tailwind color utilities like `bg-blue-500` or `text-gray-700` are acceptable.
-
-| ❌ Never | ✅ Always |
-|---|---|
-| `rounded-lg`, `rounded-xl` | `rounded-[var(--radius)]` |
-
-### Layout state — never hardcode
-
-```tsx
-// ✅ Correct
-const { sidebarExpanded, sidebarWidth } = useLayout();
-<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
-
-// ✅ Correct for reusable components that may render outside XerticaProvider
-const layout = useOptionalLayout();
-const fallbackSidebarWidth = layout?.sidebarWidth ?? 80;
-
-// ❌ Wrong
-<div style={{ paddingLeft: '256px' }}>
-```
-
-### Destructive actions — always confirm
-
-```tsx
-// ✅ Always wrap in AlertDialog
-<AlertDialog>
-  <AlertDialogTrigger asChild>
-    <Button variant="destructive">Delete</Button>
-  </AlertDialogTrigger>
-  <AlertDialogContent>
-    <AlertDialogHeader>
-      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
-      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
-    </AlertDialogHeader>
-    <AlertDialogFooter>
-      <AlertDialogCancel>Cancel</AlertDialogCancel>
-      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
-    </AlertDialogFooter>
-  </AlertDialogContent>
-</AlertDialog>
-```
-
-### Page structure — always use PageHeader
-
-Every page must use `<PageHeader>` for its title and primary actions. Never use raw `<h1>` or `<h2>`:
-
-```tsx
-<PageHeader>
-  <PageHeaderHeading>Users</PageHeaderHeading>
-  <PageHeaderDescription>Manage your team members.</PageHeaderDescription>
-  <Button><Plus className="size-4 mr-2" />New User</Button>
-</PageHeader>
-```
-
-### Toast notifications
-
-```tsx
-import { toast } from 'sonner';
-
-toast.success('User created successfully');
-toast.error('Failed to save changes');
-toast.warning('Session expires in 5 minutes');
-```
-
-Never render `<Toaster>` manually — it is auto-injected by `<XerticaProvider>` in `App.tsx`.
-
----
-
-## 6. Theme & Token Customization
-
-To change the color scheme, edit `src/styles/xertica/tokens.css`. To switch themes via CLI:
-
-```bash
-npx xertica-ui update
-# → select "Theme only"
-```
-
-The token file uses HSL values and supports both light and dark modes via the `.dark` class on `<html>`.
-
-Never import or modify anything inside `node_modules/xertica-ui/styles/` — override via `tokens.css` only.
-
----
-
-## 7. Authentication Pattern
-
-The auth flow is managed in `src/app/components/AuthGuard.tsx`:
-
-- `getStoredUser()` / `storeUser()` / `clearStoredUser()` — from `src/shared/lib/auth.ts`
-- Auth pages (`/login`, `/forgot-password`, etc.) redirect to `/home` when user is already logged in
-- Protected routes use `<ProtectedRoute user={user}>` wrapper that redirects to `/login` if user is null
-- `handleLogin(email, password)` stores the user and navigates to the first protected route
-- `handleLogout()` clears storage and navigates to `/login`
-
-To add social login, extend `handleLogin` logic in `AuthGuard.tsx` and wire the provider button in `SocialLoginButtons.tsx`.
-
----
-
-## 8. AI Agent Documentation Reference
-
-| What you need | Where to read |
-|---|---|
-| Quick import + rules reference | `node_modules/xertica-ui/llms-compact.txt` |
-| Full component API | `node_modules/xertica-ui/llms-full.txt` |
-| "Should I use Dialog or Sheet?" | `node_modules/xertica-ui/docs/decision-tree.md` |
-| Specific component props | `node_modules/xertica-ui/docs/components/[name].md` |
-| All components + their imports | `node_modules/xertica-ui/components.json` |
-| Mandatory AI rules | `node_modules/xertica-ui/docs/ai-usage.md` |
-| This project's rules (you are here) | `CLAUDE.md` at project root |
-
----
-
-## 9. Development Checklist
-
-Before completing any feature:
-
-- [ ] Feature content is in `src/features/<name>/ui/`
-- [ ] Feature exports via `src/features/<name>/index.ts`
-- [ ] Page is a thin wrapper in `src/pages/`
-- [ ] Route registered in `src/shared/config/navigation.ts`
-- [ ] Route registered in `src/app/components/AuthGuard.tsx`
-- [ ] Home navigation card added (if primary module)
-- [ ] Only `xertica-ui` components used — no raw HTML elements
-- [ ] No raw hex/rgb values — semantic tokens for semantic/status contexts; Tailwind utilities acceptable for non-semantic layout
-- [ ] No hardcoded radii — use `rounded-[var(--radius)]`
-- [ ] Icons from `lucide-react` only
-- [ ] Destructive actions wrapped in `<AlertDialog>`
-- [ ] Layout state from `useLayout()` — no hardcoded widths
-- [ ] Toast used for action feedback (`toast.success`, `toast.error`)
-- [ ] Responsive on mobile, tablet, and desktop
+# Project Guidelines — Xertica UI App
+
+> **Scope**: These guidelines apply to React applications scaffolded with `npx xertica-ui@latest init`. They define the FSD/FDA architecture, import conventions, component rules, and AI agent behavior for this project.
+>
+> **AI agents**: Read this file first. Then read `node_modules/xertica-ui/llms-compact.txt` for component reference, and `node_modules/xertica-ui/docs/decision-tree.md` before choosing between similar components.
+
+---
+
+## 1. Architecture — Feature-Sliced Design + Feature-Driven Architecture
+
+This project follows **FSD (Feature-Sliced Design)** layered architecture combined with **FDA (Feature-Driven Architecture)** vertical slicing. Layers can only import from layers below them.
+
+```
+src/
+├── app/                          # Layer 1 — Application shell (imports from all layers)
+│   ├── App.tsx                   # XerticaProvider + BrowserRouter + AuthGuard
+│   └── components/
+│       ├── AppLayout.tsx         # Sidebar + children + optional XerticaAssistant
+│       └── AuthGuard.tsx         # Auth state management + all route definitions
+│
+├── shared/                       # Layer 2 — Shared utilities (no business domain)
+│   ├── config/
+│   │   └── navigation.ts         # RouteConfig type, routes[], getRouteByPath()
+│   ├── lib/
+│   │   └── auth.ts               # getStoredUser, storeUser, clearStoredUser
+│   └── types/
+│       └── auth.ts               # User interface
+│
+├── features/                     # Layer 3 — Vertical slices by business capability
+│   ├── auth/
+│   │   ├── index.ts              # Public barrel — import from here, never from /ui/*
+│   │   └── ui/
+│   │       ├── AuthPageShell.tsx         # Split-screen layout for auth pages
+│   │       ├── SocialLoginButtons.tsx    # Google / MT Login / gov.br buttons
+│   │       ├── LoginContent.tsx
+│   │       ├── ForgotPasswordContent.tsx
+│   │       ├── VerifyEmailContent.tsx
+│   │       └── ResetPasswordContent.tsx
+│   ├── home/
+│   │   ├── index.ts
+│   │   └── ui/
+│   │       └── HomeContent.tsx
+│   └── template/
+│       ├── index.ts
+│       └── ui/
+│           ├── TemplateContent.tsx
+│           └── FormTemplate.tsx
+│
+├── pages/                        # Layer 4 — Route entrypoints (thin wrappers only)
+│   ├── LoginPage.tsx
+│   ├── ForgotPasswordPage.tsx
+│   ├── VerifyEmailPage.tsx
+│   ├── ResetPasswordPage.tsx
+│   ├── HomePage.tsx              # AppLayout + HomeContent + XerticaAssistant
+│   └── TemplatePage.tsx          # AppLayout + TemplateContent + XerticaAssistant
+│
+└── styles/                       # Visual tokens and Tailwind entry
+    ├── index.css                 # Imports: xertica-ui/style.css, tokens.css, @source
+    └── xertica/
+        └── tokens.css            # Brand CSS variables — edit here to customize theme
+```
+
+---
+
+## 2. Layer Responsibilities
+
+### `app/`
+Initializes the application. Contains only providers, the router, `AuthGuard` (auth state + routes), and `AppLayout` (layout shell). No business logic here.
+
+### `shared/`
+Framework-agnostic code with no business domain: primitive types, localStorage helpers, navigation config. Importable by any layer. Must not import from `features/` or `pages/`.
+
+### `features/`
+Each feature is a self-contained vertical slice. The `index.ts` is the only public interface — always import from the barrel, never from internal paths:
+
+```tsx
+// ✅ Correct
+import { LoginContent } from '../features/auth';
+
+// ❌ Wrong — never import from internal feature paths
+import { LoginContent } from '../features/auth/ui/LoginContent';
+```
+
+Features must not import from each other. If two features share code, extract it to `shared/`.
+
+### `pages/`
+Thin route wrappers that compose `AppLayout` + feature content + optional `XerticaAssistant`. No logic, no state, no API calls here:
+
+```tsx
+// ✅ Correct — thin wrapper
+export function HomePage({ user, onLogout }: PageProps) {
+  const { assistenteExpanded, toggleAssistente } = useLayout();
+  return (
+    <AppLayout user={user} onLogout={onLogout} assistant={<XerticaAssistant ... />}>
+      <HomeContent user={user} onLogout={onLogout} />
+    </AppLayout>
+  );
+}
+```
+
+---
+
+## 3. Import Rules
+
+Always use the correct `xertica-ui` subpath for the layer you are in:
+
+```tsx
+// shared/ui → UI primitives
+import { Button, Card, Input, Badge, Table, Dialog, Select } from 'xertica-ui/ui';
+
+// app layer → providers and brand
+import { XerticaProvider, XerticaLogo, ThemeToggle }        from 'xertica-ui/brand';
+
+// features/layout → navigation shell
+import { Sidebar, Header }                                   from 'xertica-ui/layout';
+
+// features/assistant → AI assistant
+import { XerticaAssistant, generateDemoResponse }            from 'xertica-ui/assistant';
+
+// features/media → media players
+import { VideoPlayer, AudioPlayer }                          from 'xertica-ui/media';
+
+// shared/lib → hooks and contexts
+import { useLayout, useOptionalLayout, useTheme }            from 'xertica-ui/hooks';
+
+// styles → imported once by src/styles/index.css
+import 'xertica-ui/style.css';
+```
+
+Icons always come from `lucide-react` — never from `xertica-ui`:
+
+```tsx
+import { Home, Settings, Plus, Trash2, ChevronRight } from 'lucide-react';
+```
+
+---
+
+## 4. Adding a New Route (Step-by-Step)
+
+1. **Create the feature content** — `src/features/<name>/ui/<NameContent>.tsx`
+2. **Export from the barrel** — add to `src/features/<name>/index.ts`
+3. **Create the page** — `src/pages/<NamePage>.tsx` (thin AppLayout wrapper)
+4. **Register the route** — add to `routes` array in `src/shared/config/navigation.ts`:
+
+   ```ts
+   import { MyIcon } from 'lucide-react';
+   
+   export const routes: RouteConfig[] = [
+     { path: '/home', label: 'Home', icon: Home },
+     { path: '/my-feature', label: 'My Feature', icon: MyIcon }, // ← add here
+   ];
+   ```
+
+5. **Register the `<Route>`** — add to `src/app/components/AuthGuard.tsx`:
+
+   ```tsx
+   import { MyFeaturePage } from '../../pages/MyFeaturePage';
+   
+   // inside <Routes>:
+   <Route path="/my-feature" element={
+     <ProtectedRoute user={user}>
+       <MyFeaturePage user={user} onLogout={handleLogout} />
+     </ProtectedRoute>
+   } />
+   ```
+
+6. **Add a navigation card** to `HomeContent.tsx` if it's a primary module.
+
+---
+
+## 5. Non-Negotiable Rules
+
+### HTML — never use raw elements for UI
+
+| ❌ Never | ✅ Always |
+|---|---|
+| `<button>` | `<Button>` from `xertica-ui/ui` |
+| `<input>` | `<Input>` from `xertica-ui/ui` |
+| `<select>` | `<Select>` from `xertica-ui/ui` |
+| `<h1>` / `<h2>` for page headers | `<PageHeader><PageHeaderHeading>` from `xertica-ui/ui` |
+| `<div class="card ...">` | `<Card>` from `xertica-ui/ui` |
+| custom scrollable div | `<ScrollArea>` from `xertica-ui/ui` |
+
+### Colors — context-dependent rules
+
+| ❌ Never (any context) | Reason |
+|---|---|
+| `#3b82f6`, `rgb(59, 130, 246)`, `hsl(...)` | Raw values — non-themeable |
+| `style={{ color: '#...' }}` for theming | Non-themeable inline style |
+
+| ❌ Wrong for semantic/status contexts | ✅ Required instead |
+|---|---|
+| `bg-red-500` / `text-red-500` for errors | `bg-destructive` / `text-destructive` |
+| `bg-green-500` for success states | `bg-success` |
+| `bg-yellow-500` for warnings | `bg-warning` |
+
+> For **layout, spacing, and general non-semantic UI** (custom components, decorative elements where no semantic token applies), standard Tailwind color utilities like `bg-blue-500` or `text-gray-700` are acceptable.
+
+| ❌ Never | ✅ Always |
+|---|---|
+| `rounded-lg`, `rounded-xl` | `rounded-[var(--radius)]` |
+
+### Layout state — never hardcode
+
+```tsx
+// ✅ Correct
+const { sidebarExpanded, sidebarWidth } = useLayout();
+<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
+
+// ✅ Correct for reusable components that may render outside XerticaProvider
+const layout = useOptionalLayout();
+const fallbackSidebarWidth = layout?.sidebarWidth ?? 80;
+
+// ❌ Wrong
+<div style={{ paddingLeft: '256px' }}>
+```
+
+### Destructive actions — always confirm
+
+```tsx
+// ✅ Always wrap in AlertDialog
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Page structure — always use PageHeader
+
+Every page must use `<PageHeader>` for its title and primary actions. Never use raw `<h1>` or `<h2>`:
+
+```tsx
+<PageHeader>
+  <PageHeaderHeading>Users</PageHeaderHeading>
+  <PageHeaderDescription>Manage your team members.</PageHeaderDescription>
+  <Button><Plus className="size-4 mr-2" />New User</Button>
+</PageHeader>
+```
+
+### Toast notifications
+
+```tsx
+import { toast } from 'sonner';
+
+toast.success('User created successfully');
+toast.error('Failed to save changes');
+toast.warning('Session expires in 5 minutes');
+```
+
+Never render `<Toaster>` manually — it is auto-injected by `<XerticaProvider>` in `App.tsx`.
+
+---
+
+## 6. Theme & Token Customization
+
+To change the color scheme, edit `src/styles/xertica/tokens.css`. To switch themes via CLI:
+
+```bash
+npx xertica-ui update
+# → select "Theme only"
+```
+
+The token file uses HSL values and supports both light and dark modes via the `.dark` class on `<html>`.
+
+Never import or modify anything inside `node_modules/xertica-ui/styles/` — override via `tokens.css` only.
+
+---
+
+## 7. Authentication Pattern
+
+The auth flow is managed in `src/app/components/AuthGuard.tsx`:
+
+- `getStoredUser()` / `storeUser()` / `clearStoredUser()` — from `src/shared/lib/auth.ts`
+- Auth pages (`/login`, `/forgot-password`, etc.) redirect to `/home` when user is already logged in
+- Protected routes use `<ProtectedRoute user={user}>` wrapper that redirects to `/login` if user is null
+- `handleLogin(email, password)` stores the user and navigates to the first protected route
+- `handleLogout()` clears storage and navigates to `/login`
+
+To add social login, extend `handleLogin` logic in `AuthGuard.tsx` and wire the provider button in `SocialLoginButtons.tsx`.
+
+---
+
+## 8. AI Agent Documentation Reference
+
+| What you need | Where to read |
+|---|---|
+| Quick import + rules reference | `node_modules/xertica-ui/llms-compact.txt` |
+| Full component API | `node_modules/xertica-ui/llms-full.txt` |
+| "Should I use Dialog or Sheet?" | `node_modules/xertica-ui/docs/decision-tree.md` |
+| Specific component props | `node_modules/xertica-ui/docs/components/[name].md` |
+| All components + their imports | `node_modules/xertica-ui/components.json` |
+| Mandatory AI rules | `node_modules/xertica-ui/docs/ai-usage.md` |
+| This project's rules (you are here) | `CLAUDE.md` at project root |
+
+---
+
+## 9. Development Checklist
+
+Before completing any feature:
+
+- [ ] Feature content is in `src/features/<name>/ui/`
+- [ ] Feature exports via `src/features/<name>/index.ts`
+- [ ] Page is a thin wrapper in `src/pages/`
+- [ ] Route registered in `src/shared/config/navigation.ts`
+- [ ] Route registered in `src/app/components/AuthGuard.tsx`
+- [ ] Home navigation card added (if primary module)
+- [ ] Only `xertica-ui` components used — no raw HTML elements
+- [ ] No raw hex/rgb values — semantic tokens for semantic/status contexts; Tailwind utilities acceptable for non-semantic layout
+- [ ] No hardcoded radii — use `rounded-[var(--radius)]`
+- [ ] Icons from `lucide-react` only
+- [ ] Destructive actions wrapped in `<AlertDialog>`
+- [ ] Layout state from `useLayout()` — no hardcoded widths
+- [ ] Toast used for action feedback (`toast.success`, `toast.error`)
+- [ ] Responsive on mobile, tablet, and desktop