xertica-ui 2.2.1 → 2.4.0

package/templates/guidelines/Guidelines.md

@@ -1,553 +1,577 @@
-# 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 (GENERATED — do not hand-edit)
-│   ├── context/
-│   │   └── AuthContext.tsx       # AuthProvider + useAuth() hook
-│   └── components/
-│       ├── AppLayout.tsx         # Sidebar + children + optional XerticaAssistant
-│       └── AuthGuard.tsx         # 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/
-│   │   ├── data/mock.ts          # Types + async fetch + factory functions (getMockXxx)
-│   │   ├── hooks/useFeatureCards.ts  # React Query, queryKey includes `language`
-│   │   ├── store/dashboardStore.ts   # Zustand UI state (no server data)
-│   │   ├── ui/HomeContent.tsx
-│   │   └── index.ts
-│   ├── template/
-│   │   ├── ui/TemplateContent.tsx
-│   │   └── index.ts
-│   └── assistant/                # Always present — AppLayout depends on it
-│       ├── data/mock.ts          # AssistantConfig + getMockRichSuggestions() / getMockFeedbackOptions()
-│       ├── hooks/useAssistantConfig.ts
-│       └── index.ts
-│
-├── 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
-│   └── AssistantPage.tsx
-│
-├── i18n.ts                       # i18next setup (GENERATED — covers only your selected languages)
-├── locales/
-│   ├── .languages.json           # CLI-managed selection ({ "version": 1, "codes": [...] })
-│   ├── pt-BR/                    # one folder per language — only your selected languages exist
-│   │   ├── common.json
-│   │   ├── nav.json
-│   │   ├── errors.json
-│   │   ├── languageSelector.json
-│   │   ├── themeToggle.json
-│   │   ├── pages/
-│   │   │   └── home.json, login.json, templates.json, resetPassword.json, verifyEmail.json,
-│   │   │       loginTemplate.json, formTemplate.json, dashboardTemplate.json, crudTemplate.json
-│   │   └── components/
-│   │       └── assistant.json, sidebar.json, media.json, projectCard.json, ...
-│   ├── en/                       # same structure
-│   └── es/                       # same structure
-└── 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
-```
-
-> **Files generated by the CLI** (`App.tsx`, `i18n.ts`, `locales/.languages.json`) are rewritten by `npx xertica-ui update`. Avoid hand-editing them; use the CLI to add/remove languages and let it regenerate them.
-
----
-
-## 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';
-import { useTranslation } from 'react-i18next';
-
-const { t } = useTranslation();
-toast.success(t('users.createSuccess'));
-toast.error(t('errors.somethingWentWrong'));
-```
-
-Never render `<Toaster>` manually — it is auto-injected by `<XerticaProvider>` in `App.tsx`. Always translate the message text through `t()`.
-
-### Translations — never hardcode strings
-
-Every user-facing string must come from `useTranslation()`. Add new keys to the appropriate split JSON file under `src/locales/<lang>/` for all configured languages:
-
-```tsx
-// ❌ Wrong
-<Button aria-label="Save">Save</Button>
-
-// ✅ Correct
-const { t } = useTranslation();
-<Button aria-label={t('common.save')}>{t('common.save')}</Button>
-```
-
-This applies to `aria-label`, `placeholder`, `title`, toast messages, error text, dropdown items — everything the user can read.
-
----
-
-## 6. Internationalization
-
-### Selecting languages on init
-
-The CLI's `init` command asks which languages your app should support (`pt-BR`, `en`, `es`). Pick **1, 2, or 3**. The CLI:
-
-- Copies only the locale **folders** for the languages you chose (each is a directory tree with split JSON files)
-- Generates `src/i18n.ts` with `import.meta.glob` calls for exactly those languages — Vite auto-discovers all JSON files in the folder at build time
-- Injects the `availableLanguages` prop into `src/app/App.tsx` (omitted when all 3 defaults are selected)
-- Persists the selection in `src/locales/.languages.json`
-
-### Monolingual mode
-
-When you select only one language, the `<LanguageSelector>` automatically renders `null` (there is nothing to switch to). A header comment in the generated `App.tsx` documents this. To force the selector visible anyway:
-
-```tsx
-<LanguageSelector showWhenMonolingual />
-```
-
-### Adding or removing languages later
-
-```bash
-npx xertica-ui update
-# → select "Languages"
-```
-
-The CLI shows your current selection, prompts for the new set, displays the diff (`+ es`, `- en`), and on confirm:
-- copies any newly-added locale JSONs from `node_modules/xertica-ui/templates/src/locales/`
-- removes JSONs of unselected languages
-- regenerates `src/i18n.ts` and `src/app/App.tsx`
-- updates `src/locales/.languages.json`
-
-> The `update` → **Project files** flow also reads `.languages.json` and preserves your selection. Updating App.tsx and i18n.ts won't reset your languages.
-
-### Using translations in components
-
-```tsx
-import { useTranslation } from 'react-i18next';
-
-function MyComponent() {
-  const { t } = useTranslation();
-  return <h1>{t('home.welcome')}</h1>;
-}
-```
-
-### Reading the configured language set
-
-```tsx
-import { useLanguage } from 'xertica-ui/hooks';
-
-const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
-```
-
-- Never hardcode the language list when building a custom settings UI — iterate over `availableLanguages` so it stays in sync with whatever you configured.
-
-### Factory functions for translated mock data
-
-Outside the React render cycle (mock fetch functions, fallback options), use **functions** so `i18n.t()` re-runs on every call instead of being frozen at module-load time:
-
-```tsx
-// ❌ Wrong — frozen in initial language
-export const MOCK_OPTIONS = [i18n.t('feedback.notWhatIWanted')];
-
-// ✅ Correct — re-evaluated every call
-export function getMockOptions() {
-  return [i18n.t('feedback.notWhatIWanted')];
-}
-```
-
-Inside components, build label maps for enums with `useMemo([..., t])`:
-
-```tsx
-const statusLabels = useMemo(() => ({
-  active: t('status.active'),
-  inactive: t('status.inactive'),
-}), [t]);
-```
-
----
-
-## 7. Server State (React Query)
-
-Each feature has its own `data/mock.ts` (typed fetch functions) and `hooks/use<Xxx>.ts` (React Query wrappers). Replace the mock fetch with a real API call without touching the consumer code.
-
-### Language-aware queryKey — mandatory
-
-Every hook whose response contains translated strings **must** include the active language in its `queryKey`:
-
-```tsx
-// features/home/hooks/useFeatureCards.ts
-import { useQuery } from '@tanstack/react-query';
-import { useLanguage } from 'xertica-ui/hooks';
-import { fetchFeatureCards, type FeatureCard } from '../data/mock';
-
-export function useFeatureCards() {
-  const { language } = useLanguage();
-  return useQuery<FeatureCard[]>({
-    queryKey: ['home', 'feature-cards', language], // ← language as third element
-    queryFn: fetchFeatureCards,
-    staleTime: 10 * 60 * 1000,
-  });
-}
-```
-
-Switching language creates a new cache key → cache miss → automatic refetch in the new locale. Switching back is an instant cache hit. No page reload required.
-
-### Connecting to a real API
-
-Replace only the `fetch*` function in `data/mock.ts` — the hook and the components stay unchanged:
-
-```ts
-// data/mock.ts — after
-export async function fetchFeatureCards(): Promise<FeatureCard[]> {
-  const res = await fetch('/api/feature-cards', {
-    headers: { 'Accept-Language': i18n.language },
-  });
-  if (!res.ok) throw new Error('Failed');
-  return res.json();
-}
-```
-
-Pass `Accept-Language: i18n.language` so the backend returns localized strings — mirroring the mock pattern.
-
----
-
-## 8. Loading States — Skeletons
-
-Always render a skeleton placeholder — never a spinner — for data-bearing surfaces. Spinner-only loading is acceptable **only** for inline actions (button submit, "saving…" state).
-
-Every card pattern ships with a matching `*Skeleton`:
-
-```tsx
-import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui';
-
-{isLoading
-  ? <ActivityCardSkeleton rows={5} />
-  : <ActivityCard items={items} />}
-```
-
-Available skeleton companions: `ActivityCardSkeleton`, `ProfileCardSkeleton`, `ProjectCardSkeleton`, `NotificationCardSkeleton`, `QuickActionCardSkeleton`, `FeatureCardSkeleton`, `StatsCardSkeleton`.
-
-For grids, render one skeleton per expected card:
-
-```tsx
-{isLoading ? (
-  <>
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-  </>
-) : (
-  data.map(item => <FeatureCard key={item.id} {...item} />)
-)}
-```
-
-For tables, render skeleton rows with the `<Skeleton>` primitive (from `xertica-ui/ui`):
-
-```tsx
-{isLoading
-  ? Array.from({ length: 5 }).map((_, i) => (
-      <TableRow key={i}>
-        <TableCell><Skeleton className="h-3.5 w-28" /></TableCell>
-        <TableCell><Skeleton className="h-5 w-16 rounded-full" /></TableCell>
-      </TableRow>
-    ))
-  : rows.map(...)}
-```
-
-Pass `rows={maxItems}` to list-style skeletons so the placeholder height matches the loaded state's row count.
-
----
-
-## 9. 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.
-
----
-
-## 10. Authentication Pattern
-
-The auth flow is managed in `src/app/context/AuthContext.tsx` via the `useAuth()` hook:
-
-- `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>` wrapper that redirects to `/login` if user is null
-- `useAuth().login(email, password)` stores the user
-- `useAuth().logout()` clears storage and navigates to `/login`
-
-To add social login, extend the `login` logic in `AuthContext.tsx` and wire the provider button in `SocialLoginButtons.tsx`.
-
----
-
-## 11. 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`          |
-| i18n & language configuration       | `node_modules/xertica-ui/docs/i18n.md`              |
-| State management (React Query)      | `node_modules/xertica-ui/docs/state-management.md`  |
-| This project's rules (you are here) | `CLAUDE.md` at project root                         |
-
----
-
-## 12. 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`) — message translated via `t()`
-- [ ] **All user-facing strings go through `useTranslation()`** — added to all configured `locales/*.json`
-- [ ] **Server-state hooks include `language` in their `queryKey`** when the response contains translated strings
-- [ ] **Loading states render a `*Skeleton`** (not just a spinner) for cards/lists/tables
-- [ ] 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 (GENERATED — do not hand-edit)
+│   ├── context/
+│   │   └── AuthContext.tsx       # AuthProvider + useAuth() hook
+│   └── components/
+│       ├── AppLayout.tsx         # Sidebar + children + optional XerticaAssistant
+│       └── AuthGuard.tsx         # 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/
+│   │   ├── data/mock.ts          # Types + async fetch + factory functions (getMockXxx)
+│   │   ├── hooks/useFeatureCards.ts  # React Query, queryKey includes `language`
+│   │   ├── store/dashboardStore.ts   # Zustand UI state (no server data)
+│   │   ├── ui/HomeContent.tsx
+│   │   └── index.ts
+│   ├── template/
+│   │   ├── ui/TemplateContent.tsx
+│   │   └── index.ts
+│   └── assistant/                # Always present — AppLayout depends on it
+│       ├── data/mock.ts          # AssistantConfig + getMockRichSuggestions() / getMockFeedbackOptions()
+│       ├── hooks/useAssistantConfig.ts
+│       └── index.ts
+│
+├── 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
+│   └── AssistantPage.tsx
+│
+├── i18n.ts                       # i18next setup (GENERATED — covers only your selected languages)
+├── locales/
+│   ├── .languages.json           # CLI-managed selection ({ "version": 1, "codes": [...] })
+│   ├── pt-BR/                    # one folder per language — only your selected languages exist
+│   │   ├── common.json
+│   │   ├── nav.json
+│   │   ├── errors.json
+│   │   ├── languageSelector.json
+│   │   ├── themeToggle.json
+│   │   ├── pages/
+│   │   │   └── home.json, login.json, templates.json, resetPassword.json, verifyEmail.json,
+│   │   │       loginTemplate.json, formTemplate.json, dashboardTemplate.json, crudTemplate.json
+│   │   └── components/
+│   │       └── assistant.json, sidebar.json, media.json, projectCard.json, ...
+│   ├── en/                       # same structure
+│   └── es/                       # same structure
+└── 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
+```
+
+> **Files generated by the CLI** (`App.tsx`, `i18n.ts`, `locales/.languages.json`) are rewritten by `npx xertica-ui update`. Avoid hand-editing them; use the CLI to add/remove languages and let it regenerate them.
+
+---
+
+## 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';
+import { useTranslation } from 'react-i18next';
+
+const { t } = useTranslation();
+toast.success(t('users.createSuccess'));
+toast.error(t('errors.somethingWentWrong'));
+```
+
+Never render `<Toaster>` manually — it is auto-injected by `<XerticaProvider>` in `App.tsx`. Always translate the message text through `t()`.
+
+### Translations — never hardcode strings
+
+Every user-facing string must come from `useTranslation()`. Add new keys to the appropriate split JSON file under `src/locales/<lang>/` for all configured languages:
+
+```tsx
+// ❌ Wrong
+<Button aria-label="Save">Save</Button>;
+
+// ✅ Correct
+const { t } = useTranslation();
+<Button aria-label={t('common.save')}>{t('common.save')}</Button>;
+```
+
+This applies to `aria-label`, `placeholder`, `title`, toast messages, error text, dropdown items — everything the user can read.
+
+---
+
+## 6. Internationalization
+
+### Selecting languages on init
+
+The CLI's `init` command asks which languages your app should support (`pt-BR`, `en`, `es`). Pick **1, 2, or 3**. The CLI:
+
+- Copies only the locale **folders** for the languages you chose (each is a directory tree with split JSON files)
+- Generates `src/i18n.ts` with `import.meta.glob` calls for exactly those languages — Vite auto-discovers all JSON files in the folder at build time
+- Injects the `availableLanguages` prop into `src/app/App.tsx` (omitted when all 3 defaults are selected)
+- Persists the selection in `src/locales/.languages.json`
+
+### Monolingual mode
+
+When you select only one language, the `<LanguageSelector>` automatically renders `null` (there is nothing to switch to). A header comment in the generated `App.tsx` documents this. To force the selector visible anyway:
+
+```tsx
+<LanguageSelector showWhenMonolingual />
+```
+
+### Adding or removing languages later
+
+```bash
+npx xertica-ui update
+# → select "Languages"
+```
+
+The CLI shows your current selection, prompts for the new set, displays the diff (`+ es`, `- en`), and on confirm:
+
+- copies any newly-added locale JSONs from `node_modules/xertica-ui/templates/src/locales/`
+- removes JSONs of unselected languages
+- regenerates `src/i18n.ts` and `src/app/App.tsx`
+- updates `src/locales/.languages.json`
+
+> The `update` → **Project files** flow also reads `.languages.json` and preserves your selection. Updating App.tsx and i18n.ts won't reset your languages.
+
+### Enabling or disabling Dark Mode support later
+
+```bash
+npx xertica-ui update
+# → select "Dark Mode"
+```
+
+The CLI reads your current setting from `.xertica.json` and prompts you to enable or disable dark mode. On confirmation, it updates `.xertica.json` and regenerates `App.tsx` to set `disableDarkMode={true}` or `false`.
+
+### Adding or removing the AI Assistant later
+
+```bash
+npx xertica-ui update
+# → select "Assistant"
+```
+
+The CLI detects whether the assistant is currently active (via `.xertica.json` or page presence) and prompts to add or remove the feature. It automatically copies/deletes the feature files and updates `AuthGuard.tsx`, `HomePage.tsx`, and `TemplatePage.tsx` to reflect the change.
+
+### Using translations in components
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function MyComponent() {
+  const { t } = useTranslation();
+  return <h1>{t('home.welcome')}</h1>;
+}
+```
+
+### Reading the configured language set
+
+```tsx
+import { useLanguage } from 'xertica-ui/hooks';
+
+const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
+```
+
+- Never hardcode the language list when building a custom settings UI — iterate over `availableLanguages` so it stays in sync with whatever you configured.
+
+### Factory functions for translated mock data
+
+Outside the React render cycle (mock fetch functions, fallback options), use **functions** so `i18n.t()` re-runs on every call instead of being frozen at module-load time:
+
+```tsx
+// ❌ Wrong — frozen in initial language
+export const MOCK_OPTIONS = [i18n.t('feedback.notWhatIWanted')];
+
+// ✅ Correct — re-evaluated every call
+export function getMockOptions() {
+  return [i18n.t('feedback.notWhatIWanted')];
+}
+```
+
+Inside components, build label maps for enums with `useMemo([..., t])`:
+
+```tsx
+const statusLabels = useMemo(
+  () => ({
+    active: t('status.active'),
+    inactive: t('status.inactive'),
+  }),
+  [t]
+);
+```
+
+---
+
+## 7. Server State (React Query)
+
+Each feature has its own `data/mock.ts` (typed fetch functions) and `hooks/use<Xxx>.ts` (React Query wrappers). Replace the mock fetch with a real API call without touching the consumer code.
+
+### Language-aware queryKey — mandatory
+
+Every hook whose response contains translated strings **must** include the active language in its `queryKey`:
+
+```tsx
+// features/home/hooks/useFeatureCards.ts
+import { useQuery } from '@tanstack/react-query';
+import { useLanguage } from 'xertica-ui/hooks';
+import { fetchFeatureCards, type FeatureCard } from '../data/mock';
+
+export function useFeatureCards() {
+  const { language } = useLanguage();
+  return useQuery<FeatureCard[]>({
+    queryKey: ['home', 'feature-cards', language], // ← language as third element
+    queryFn: fetchFeatureCards,
+    staleTime: 10 * 60 * 1000,
+  });
+}
+```
+
+Switching language creates a new cache key → cache miss → automatic refetch in the new locale. Switching back is an instant cache hit. No page reload required.
+
+### Connecting to a real API
+
+Replace only the `fetch*` function in `data/mock.ts` — the hook and the components stay unchanged:
+
+```ts
+// data/mock.ts — after
+export async function fetchFeatureCards(): Promise<FeatureCard[]> {
+  const res = await fetch('/api/feature-cards', {
+    headers: { 'Accept-Language': i18n.language },
+  });
+  if (!res.ok) throw new Error('Failed');
+  return res.json();
+}
+```
+
+Pass `Accept-Language: i18n.language` so the backend returns localized strings — mirroring the mock pattern.
+
+---
+
+## 8. Loading States — Skeletons
+
+Always render a skeleton placeholder — never a spinner — for data-bearing surfaces. Spinner-only loading is acceptable **only** for inline actions (button submit, "saving…" state).
+
+Every card pattern ships with a matching `*Skeleton`:
+
+```tsx
+import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui';
+
+{
+  isLoading ? <ActivityCardSkeleton rows={5} /> : <ActivityCard items={items} />;
+}
+```
+
+Available skeleton companions: `ActivityCardSkeleton`, `ProfileCardSkeleton`, `ProjectCardSkeleton`, `NotificationCardSkeleton`, `QuickActionCardSkeleton`, `FeatureCardSkeleton`, `StatsCardSkeleton`.
+
+For grids, render one skeleton per expected card:
+
+```tsx
+{
+  isLoading ? (
+    <>
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+    </>
+  ) : (
+    data.map(item => <FeatureCard key={item.id} {...item} />)
+  );
+}
+```
+
+For tables, render skeleton rows with the `<Skeleton>` primitive (from `xertica-ui/ui`):
+
+```tsx
+{isLoading
+  ? Array.from({ length: 5 }).map((_, i) => (
+      <TableRow key={i}>
+        <TableCell><Skeleton className="h-3.5 w-28" /></TableCell>
+        <TableCell><Skeleton className="h-5 w-16 rounded-full" /></TableCell>
+      </TableRow>
+    ))
+  : rows.map(...)}
+```
+
+Pass `rows={maxItems}` to list-style skeletons so the placeholder height matches the loaded state's row count.
+
+---
+
+## 9. 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.
+
+---
+
+## 10. Authentication Pattern
+
+The auth flow is managed in `src/app/context/AuthContext.tsx` via the `useAuth()` hook:
+
+- `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>` wrapper that redirects to `/login` if user is null
+- `useAuth().login(email, password)` stores the user
+- `useAuth().logout()` clears storage and navigates to `/login`
+
+To add social login, extend the `login` logic in `AuthContext.tsx` and wire the provider button in `SocialLoginButtons.tsx`.
+
+---
+
+## 11. 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`          |
+| i18n & language configuration       | `node_modules/xertica-ui/docs/i18n.md`              |
+| State management (React Query)      | `node_modules/xertica-ui/docs/state-management.md`  |
+| This project's rules (you are here) | `CLAUDE.md` at project root                         |
+
+---
+
+## 12. 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`) — message translated via `t()`
+- [ ] **All user-facing strings go through `useTranslation()`** — added to all configured `locales/*.json`
+- [ ] **Server-state hooks include `language` in their `queryKey`** when the response contains translated strings
+- [ ] **Loading states render a `*Skeleton`** (not just a spinner) for cards/lists/tables
+- [ ] Responsive on mobile, tablet, and desktop