xertica-ui 2.0.2 → 2.0.4

package/guidelines/Guidelines.md

@@ -1,657 +1,250 @@
-# Xertica UI - Project Guidelines
-
-## 📋 Visão Geral do Projeto
-
-O **Xertica UI** é um Design System completo construído com React e Tailwind CSS v4.0, seguindo uma arquitetura **CLI-first** (modelo shadcn/ui). O sistema está 100% pronto para publicação no NPM e todos os componentes são portáveis, independentes e reutilizáveis.
-
----
-
-## 🎨 Design System - Princípios Fundamentais
-
-### Variáveis CSS Semânticas
-
-**REGRA CRÍTICA**: Todos os componentes e páginas DEVEM usar exclusivamente as variáveis CSS definidas em `/styles/xertica/tokens.css`.
-
-#### Cores
-```css
-/* Sempre use as variáveis semânticas */
-var(--background)
-var(--foreground)
-var(--card)
-var(--card-foreground)
-var(--primary)
-var(--primary-foreground)
-var(--secondary)
-var(--secondary-foreground)
-var(--muted)
-var(--muted-foreground)
-var(--accent)
-var(--accent-foreground)
-var(--destructive)
-var(--destructive-foreground)
-var(--border)
-var(--input)
-var(--ring)
-var(--chart-1) até var(--chart-5)
-```
-
-#### Espaçamentos
-```css
-/* Use os tokens de spacing */
-var(--spacing-xs)    /* 4px */
-var(--spacing-sm)    /* 8px */
-var(--spacing-md)    /* 16px */
-var(--spacing-lg)    /* 24px */
-var(--spacing-xl)    /* 32px */
-var(--spacing-2xl)   /* 48px */
-var(--spacing-3xl)   /* 64px */
-```
-
-#### Bordas e Raios
-```css
-var(--radius)        /* Border radius padrão */
-var(--radius-sm)     /* Border radius pequeno */
-var(--radius-lg)     /* Border radius grande */
-var(--radius-full)   /* Border radius circular */
-```
-
-#### Tipografia
-
-**REGRA CRÍTICA**: Apenas a fonte **Roboto** pode ser utilizada (definida em `/styles/globals.css`).
-
-```css
-/* Importado no globals.css */
-@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700;800&display=swap');
-
-/* Font weights disponíveis */
-font-weight: 400;  /* Regular */
-font-weight: 500;  /* Medium */
-font-weight: 600;  /* Semibold */
-font-weight: 700;  /* Bold */
-font-weight: 800;  /* Extra Bold */
-```
-
-**NÃO use** classes Tailwind para font-size, font-weight ou line-height, **A MENOS** que o usuário solicite explicitamente.
-
----
-
-## 🧩 Componentes do Design System
-
-### Localização
-Todos os componentes do Design System estão em `/components/ui/` (156 componentes disponíveis).
-
-### Regra de Ouro: REUTILIZE, NÃO RECRIE
-
-**SEMPRE**:
-1. ✅ Use componentes existentes em `/components/ui/`
-2. ✅ Consulte os componentes disponíveis antes de criar novos
-3. ✅ Combine componentes existentes para criar funcionalidades complexas
-4. ✅ Estenda componentes existentes com props adicionais se necessário
-
-**NUNCA**:
-1. ❌ Crie versões personalizadas de componentes que já existem
-2. ❌ Crie componentes inline que duplicam funcionalidades existentes
-3. ❌ Ignore os componentes do design system
-
-### Componentes Principais Disponíveis
-
-#### Layout & Estrutura
-- `Card`, `CardHeader`, `CardTitle`, `CardContent`, `CardFooter`
-- `Separator`
-- `ScrollArea`
-- `Sheet`
-- `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
-- `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
-- `Collapsible`
-- `Resizable`, `ResizablePanel`, `ResizablePanelGroup`, `ResizableHandle`
-
-#### Navegação
-- `Breadcrumb`
-- `NavigationMenu`
-- `Menubar`
-- `Sidebar` (componente especializado do Xertica)
-- `PageHeader` (componente especializado do Xertica)
-
-#### Formulários
-- `Input`
-- `Textarea`
-- `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`
-- `Checkbox`
-- `RadioGroup`, `RadioGroupItem`
-- `Switch`
-- `Slider`
-- `Calendar`
-- `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage`
-- `Label`
-- `InputOTP`
-- `FileUpload`
-- `Search`
-
-#### Botões & Ações
-- `Button` (variants: default, destructive, outline, secondary, ghost, link)
-- `Toggle`, `ToggleGroup`
-- `DropdownMenu`
-- `ContextMenu`
-
-#### Feedback
-- `Alert`, `AlertTitle`, `AlertDescription`
-- `AlertDialog`
-- `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`
-- `Drawer`
-- `toast` (Sonner)
-- `Progress`
-- `Skeleton`
-- `Badge`
-- `NotificationBadge`
-
-#### Dados & Visualização
-- `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableCell`
-- `Chart` (Recharts integration)
-- `StatsCard`
-- `Avatar`, `AvatarImage`, `AvatarFallback`
-- `Empty`
-- `Rating`
-- `Timeline`
-- `TreeView`
-
-#### Navegação & Tour
-- `Stepper`, `StepperItem`
-- `Pagination`
-- `Command`, `CommandInput`, `CommandList`, `CommandItem`, `CommandGroup`
-
-#### Overlays
-- `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`
-- `Popover`, `PopoverTrigger`, `PopoverContent`
-- `HoverCard`, `HoverCardTrigger`, `HoverCardContent`
-
-#### Especialidades Xertica
-- `Map`, `SimpleMap`, `RouteMap` (Google Maps integration)
-- `XerticaAssistant` (Assistente IA integrado)
-
----
-
-## 🎯 Ícones
-
-**REGRA CRÍTICA**: Apenas ícones do **lucide-react** podem ser utilizados.
-
-```tsx
-import { Home, User, Settings, FileText, ChevronRight, Menu } from 'lucide-react';
-
-// Uso
-<Home className="w-5 h-5" />
-<Settings className="w-6 h-6 text-primary" />
-```
-
-**NÃO use**:
-- ❌ Font Awesome
-- ❌ Material Icons
-- ❌ SVGs customizados (a menos que absolutamente necessário)
-- ❌ Qualquer outra biblioteca de ícones
-
----
-
-## 📄 Estrutura de Páginas
-
-### Anatomia de uma Página Padrão
-
-Todas as páginas devem seguir esta estrutura:
-
-```tsx
-import React from 'react';
-import { Card, CardContent, CardHeader, CardTitle } from './ui/card';
-import { Button } from './ui/button';
-import { ScrollArea } from './ui/scroll-area';
-import { ChevronRight, Menu, IconName } from 'lucide-react';
-import { useLocation, useNavigate } from 'react-router-dom';
-import { getRouteByPath } from '../routes';
-import { ThemeToggle } from './ThemeToggle';
-import { LanguageSelector } from './LanguageSelector';
-import { PageHeader } from './ui/page-header';
-
-interface PageContentProps {
-  sidebarExpanded: boolean;
-  assistenteExpanded?: boolean;
-  onToggleSidebar?: () => void;
-  onToggleAssistente?: () => void;
-}
-
-export function PageContent({ 
-  sidebarExpanded, 
-  assistenteExpanded = false, 
-  onToggleSidebar, 
-  onToggleAssistente 
-}: PageContentProps) {
-  const location = useLocation();
-  const navigate = useNavigate();
-  
-  const currentRoute = getRouteByPath(location.pathname);
-  const breadcrumbLabel = currentRoute?.label || 'Página';
-
-  return (
-    <div 
-      className={`flex-1 flex flex-col overflow-hidden transition-all duration-300 ${
-        sidebarExpanded ? 'md:pl-64' : 'md:pl-20'
-      } ${
-        assistenteExpanded ? 'md:pr-[420px]' : 'md:pr-20'
-      }`}
-    >
-      {/* Header fixo */}
-      <header className="bg-card shadow-sm border-b border-border px-[24px] py-[14px] flex-shrink-0">
-        <div className="flex items-center justify-between p-[0px]">
-          <div className="flex items-center gap-2 text-muted-foreground">
-            <Button
-              variant="ghost"
-              size="sm"
-              onClick={onToggleSidebar}
-              className="md:hidden mr-2 p-2"
-            >
-              <Menu className="w-5 h-5" />
-            </Button>
-            <span className="text-primary font-medium">Xertica.ai</span>
-            <ChevronRight className="w-4 h-4" />
-            <span className="text-foreground font-medium">{breadcrumbLabel}</span>
-          </div>
-          
-          <div className="flex items-center gap-3">
-            <LanguageSelector variant="minimal" showIcon={false} className="hidden sm:flex" />
-            <ThemeToggle className="hover:bg-accent" />
-          </div>
-        </div>
-      </header>
-
-      {/* Área de conteúdo */}
-      <main className="flex-1 overflow-hidden bg-muted">
-        <ScrollArea className="h-full">
-          <div className="p-2 sm:p-4 md:p-6">
-            <div className="max-w-6xl mx-auto space-y-8">
-              {/* Cabeçalho da página */}
-              <PageHeader 
-                title="Título da Página"
-                subtitle="Descrição da página"
-              />
-
-              {/* Conteúdo principal */}
-              <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
-                {/* Cards e conteúdo aqui */}
-              </div>
-            </div>
-          </div>
-        </ScrollArea>
-      </main>
-    </div>
-  );
-}
-```
-
-### Componentes Obrigatórios de uma Página
-
-1. **Header** com breadcrumb
-2. **Menu toggle** para mobile
-3. **ThemeToggle** e **LanguageSelector**
-4. **ScrollArea** para conteúdo scrollável
-5. **Responsividade** para sidebar e assistente
-6. **Espaçamento padronizado** (`p-2 sm:p-4 md:p-6`)
-7. **Container centralizado** (`max-w-6xl mx-auto`)
-
----
-
-## 🗂️ Hierarquia e Navegação
-
-### Páginas Primárias (Top-Level)
-
-Quando criar uma **nova página primária**:
-
-#### 1. Criar o arquivo da página
-```
-/components/MinhaNovaPage.tsx
-/components/MinhaNovaContent.tsx
-```
-
-#### 2. Adicionar rota em `/routes.tsx`
-```tsx
-import { MinhaIcon } from 'lucide-react';
-
-export const routes: RouteConfig[] = [
-  {
-    path: '/home',
-    label: 'Home',
-    icon: Home,
-  },
-  {
-    path: '/minha-nova-pagina',
-    label: 'Minha Nova Página',
-    icon: MinhaIcon,
-  },
-  // ... outras rotas
-];
-```
-
-#### 3. Adicionar ao Sidebar (`/components/Sidebar.tsx`)
-O Sidebar lê automaticamente de `routes.tsx`, mas verifique se está sendo renderizado corretamente.
-
-#### 4. Adicionar card na Home (`/components/HomeContent.tsx`)
-```tsx
-<Card className="hover:shadow-xl transition-shadow duration-200 flex flex-col h-full">
-  <CardHeader>
-    <div className="flex items-center gap-3">
-      <div className="p-2 bg-[var(--chart-2)]/20 rounded-[var(--radius)]">
-        <MinhaIcon className="w-6 h-6 text-[var(--chart-2)]" />
-      </div>
-      <CardTitle className="text-sm">Minha Nova Página</CardTitle>
-    </div>
-  </CardHeader>
-  <CardContent className="flex-1">
-    <p className="text-muted-foreground">
-      Descrição da funcionalidade
-    </p>
-  </CardContent>
-  <CardFooter>
-    <Button 
-      variant="outline"
-      className="w-full"
-      onClick={() => navigate('/minha-nova-pagina')}
-    >
-      Acessar
-    </Button>
-  </CardFooter>
-</Card>
-```
-
-#### 5. Adicionar roteamento em `/App.tsx`
-```tsx
-import { MinhaNovaPage } from './components/MinhaNovaPage';
-
-// No componente App
-{location.pathname === '/minha-nova-pagina' && (
-  <MinhaNovaPage 
-    sidebarExpanded={sidebarExpanded}
-    assistenteExpanded={assistenteExpanded}
-    onToggleSidebar={toggleSidebar}
-    onToggleAssistente={toggleAssistente}
-  />
-)}
-```
-
-### Sub-Páginas (Nested Routes)
-
-Quando criar uma **sub-página**:
-
-#### 1. Estrutura de arquivos
-```
-/components/PaginaPrincipal.tsx
-/components/PaginaPrincipalContent.tsx
-/components/SubPagina.tsx (se necessário página separada)
-```
-
-#### 2. Adicionar ao routes.tsx com hierarquia
-```tsx
-export const routes: RouteConfig[] = [
-  {
-    path: '/pagina-principal',
-    label: 'Página Principal',
-    icon: MainIcon,
-    children: [
-      {
-        path: '/pagina-principal/sub-pagina',
-        label: 'Sub Página',
-        icon: SubIcon,
-      }
-    ]
-  },
-];
-```
-
-#### 3. Renderizar sub-navegação na página pai
-```tsx
-// Na PaginaPrincipalContent.tsx
-<Tabs defaultValue="overview">
-  <TabsList>
-    <TabsTrigger value="overview">Visão Geral</TabsTrigger>
-    <TabsTrigger value="sub-pagina">Sub Página</TabsTrigger>
-  </TabsList>
-  
-  <TabsContent value="overview">
-    {/* Conteúdo principal */}
-  </TabsContent>
-  
-  <TabsContent value="sub-pagina">
-    {/* Conteúdo da sub-página */}
-  </TabsContent>
-</Tabs>
-```
-
-#### 4. Ou usar navegação tradicional
-```tsx
-<Button onClick={() => navigate('/pagina-principal/sub-pagina')}>
-  Ir para Sub Página
-</Button>
-```
-
----
-
-## 🎨 Tailwind CSS v4.0
-
-### Uso Correto
-
-**SEMPRE**:
-- ✅ Use classes utilitárias do Tailwind
-- ✅ Use arbitrary values quando necessário: `bg-[var(--primary)]`
-- ✅ Use variáveis CSS: `text-[var(--foreground)]`
-- ✅ Use classes responsivas: `md:grid-cols-2 lg:grid-cols-3`
-
-**NUNCA**:
-- ❌ Crie classes CSS customizadas (exceto em casos extremos)
-- ❌ Use inline styles (use classes Tailwind)
-- ❌ Modifique `/styles/xertica/tokens.css` sem aprovação
-- ❌ Crie `tailwind.config.js` (estamos usando v4.0)
-
-### Classes Proibidas (a menos que solicitado)
-```css
-/* NÃO use sem solicitação explícita */
-text-xl, text-2xl, text-3xl      /* Font sizes */
-font-bold, font-semibold          /* Font weights */
-leading-tight, leading-relaxed    /* Line heights */
-```
-
----
-
-## 📦 Bibliotecas e Imports
-
-### Bibliotecas Aprovadas
-
-#### Ícones (OBRIGATÓRIO)
-```tsx
-import { IconName } from 'lucide-react';
-```
-
-#### Gráficos
-```tsx
-import { ... } from 'recharts';
-```
-
-#### Animações
-```tsx
-import { motion } from 'motion/react'; // Nome atualizado (não Framer Motion)
-```
-
-#### Carrosséis
-```tsx
-import { ... } from 'react-slick';
-```
-
-#### Drag & Drop
-```tsx
-import { ... } from 'react-dnd';
-```
-
-#### Formulários
-```tsx
-import { ... } from 'react-hook-form@7.55.0'; // Versão específica obrigatória
-```
-
-#### Toast
-```tsx
-import { toast } from 'sonner@2.0.3'; // Versão específica obrigatória
-```
-
-### Bibliotecas Proibidas
-- ❌ `konva` / `react-konva` (não suportado)
-- ❌ `react-resizable` (use `re-resizable` ao invés)
-- ❌ Qualquer biblioteca de ícones além do `lucide-react`
-
----
-
-## 🔄 Temas e Troca de Tema
-
-O sistema suporta troca de temas via atributo `data-theme` no root:
-
-```tsx
-// Uso do ThemeToggle
-import { ThemeToggle } from './ThemeToggle';
-
-<ThemeToggle />
-```
-
-Temas disponíveis são gerenciados em `/styles/xertica/theme-map.css`.
-
----
-
-## 🌐 Internacionalização
-
-O sistema possui suporte a múltiplos idiomas:
-
-```tsx
-import { LanguageSelector } from './LanguageSelector';
-
-<LanguageSelector variant="minimal" showIcon={false} />
-```
-
----
-
-## 📝 Boas Práticas Gerais
-
-### Estrutura de Arquivos
-```
-/components/
-  /ui/                  ← Componentes do Design System (NÃO MODIFICAR)
-  /examples/            ← Exemplos de uso
-  /media/               ← Componentes de mídia
-  MinhaPage.tsx         ← Página wrapper
-  MinhaPageContent.tsx  ← Conteúdo da página
-```
-
-### Nomenclatura
-- **Páginas**: `NomePage.tsx` e `NomePageContent.tsx`
-- **Componentes**: `PascalCase.tsx`
-- **Utilitários**: `camelCase.ts`
-- **Rotas**: `kebab-case` (`/minha-pagina`)
-
-### Imports
-```tsx
-// Componentes UI (sempre de /ui/)
-import { Button } from './ui/button';
-import { Card, CardHeader } from './ui/card';
-
-// Ícones (sempre lucide-react)
-import { Home, Settings } from 'lucide-react';
-
-// Contextos
-import { useTheme } from '../contexts/ThemeContext';
-
-// Router
-import { useNavigate, useLocation } from 'react-router-dom';
-```
-
-### Responsividade
-Sempre use breakpoints mobile-first:
-```tsx
-className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3"
-className="p-2 sm:p-4 md:p-6"
-className="text-sm md:text-base"
-```
-
-### Acessibilidade
-- Use labels em inputs
-- Use aria-labels quando necessário
-- Mantenha contraste adequado (use variáveis do design system)
-- Suporte navegação por teclado
-
----
-
-## 🚀 CLI-Ready e Portabilidade
-
-### Princípios CLI-First
-
-Todos os componentes devem:
-1. ✅ Ser independentes e não depender de CSS global oculto
-2. ✅ Usar apenas variáveis CSS semânticas de `tokens.css`
-3. ✅ Funcionar quando copiados para outro projeto
-4. ✅ Ter zero dependências de arquivos externos (exceto tokens.css)
-5. ✅ Ser publicáveis no NPM sem modificações
-
-### Overrides Opt-in
-
-Componentes podem ter overrides específicos usando atributos `data-*`:
-
-```tsx
-<div data-xertica-chat="true">
-  {/* Componente com estilo específico de chat */}
-</div>
-```
-
-Esses overrides são definidos em `/styles/xertica/app-overrides/`.
-
----
-
-## ✅ Checklist: Antes de Criar Algo Novo
-
-Antes de criar qualquer componente ou página:
-
-- [ ] Consultei `/components/ui/` para ver se já existe?
-- [ ] Posso combinar componentes existentes ao invés de criar novo?
-- [ ] Estou usando APENAS variáveis CSS de `tokens.css`?
-- [ ] Estou usando APENAS ícones do `lucide-react`?
-- [ ] Estou usando a fonte Roboto (definida em globals.css)?
-- [ ] Segui a estrutura padrão de página (header, sidebar, conteúdo)?
-- [ ] Adicionei a rota em `routes.tsx`?
-- [ ] Adicionei card na Home (se página primária)?
-- [ ] Adicionei roteamento em `App.tsx`?
-- [ ] Testei responsividade (mobile, tablet, desktop)?
-- [ ] O componente é portável e CLI-ready?
-
----
-
-## 🎓 Exemplos de Referência
-
-### Páginas Exemplo
-- `/components/HomePage.tsx` e `/components/HomeContent.tsx`
-- `/components/TemplatePage.tsx` e `/components/TemplateContent.tsx`
-- `/components/LoginPage.tsx`
-
-### Componentes Complexos
-- `/components/Sidebar.tsx` (navegação com subitens)
-- `/components/AssistenteXertica.tsx` (painel lateral)
-- `/components/ui/xertica-assistant.tsx` (componente especializado)
-
-### Uso de Componentes UI
-- `/components/examples/` (diversos exemplos de componentes)
-
----
-
-## 📌 Notas Finais
-
-Este Design System foi construído para ser:
-- **Consistente**: Todos usam as mesmas variáveis e componentes
-- **Escalável**: Fácil adicionar novas páginas e funcionalidades
-- **Portável**: Componentes funcionam em qualquer projeto React
-- **Profissional**: Pronto para publicação no NPM
-- **Manutenível**: Estrutura clara e bem documentada
-
-**Lembre-se**: Quando em dúvida, consulte os componentes existentes e siga os padrões estabelecidos. A consistência é a chave para um Design System de sucesso.
-
----
-
-**Última atualização**: Janeiro 2025
-**Versão**: 1.1.0
-**Arquitetura**: CLI-First (modelo shadcn/ui)
-**Status**: 100% CLI-Ready | Pronto para NPM
+# Xertica UI — Library Guidelines
+
+> **Scope**: These guidelines apply to contributors developing the `xertica-ui` package itself (components, documentation, build system). For guidelines on projects that **consume** the package, see `templates/guidelines/Guidelines.md`.
+
+---
+
+## 1. What Xertica UI Is
+
+Xertica UI is an enterprise-grade React component library distributed as an npm package. It is designed to be consumed by both human developers and AI coding agents (LLMs, Cursor, Claude Code, Copilot). Every design decision — from the component API to the documentation format — must serve both audiences.
+
+**Stack:** React 18 · TypeScript 5 · Tailwind CSS v4 · Radix UI · Lucide React · Vite 6
+
+---
+
+## 2. AI-First Documentation
+
+Documentation is a first-class deliverable. Every component ships with:
+
+| File | Purpose | Location |
+|---|---|---|
+| `llms.txt` | Index file following the llmstxt.org standard. Links to all docs. | `/llms.txt` |
+| `llms-compact.txt` | ~4K token quick reference. Critical rules, imports, 12 key components with examples. | `/llms-compact.txt` |
+| `llms-full.txt` | Complete documentation of all 97 components in one file for large-context LLMs. | `/llms-full.txt` |
+| `components.json` | Machine-readable registry: name, category, import path, keywords, related components. | `/components.json` |
+| `docs/decision-tree.md` | Decision trees: Dialog vs Sheet, Tooltip vs HoverCard, etc. | `/docs/decision-tree.md` |
+| `docs/components/[name].md` | Individual component reference with props, examples, and AI rules. | `/docs/components/` |
+| `docs/ai-usage.md` | Mandatory rules for AI agents operating on this library. | `/docs/ai-usage.md` |
+| `CLAUDE.md` | Auto-generated system prompt for consumer projects (injected by CLI). | `/templates/CLAUDE.md` |
+
+### When to update documentation
+
+Every PR that changes a component **must** update:
+- `docs/components/[name].md` — if props, behavior, or examples changed
+- `llms-full.txt` — the relevant component section
+- `components.json` — if the component name, import path, or description changed
+- `CHANGELOG.md` — under the current unreleased version
+
+---
+
+## 3. Package Structure
+
+```
+xertica-ui/
+├── components/                  # Source components (ships in package)
+│   ├── ui/                      # Design system primitives
+│   ├── layout/                  # Sidebar, Header
+│   ├── brand/                   # XerticaProvider, logos, ThemeToggle
+│   ├── assistant/               # XerticaAssistant, MarkdownMessage, CodeBlock
+│   ├── media/                   # VideoPlayer, AudioPlayer
+│   ├── pages/                   # Full-page template components
+│   └── shared/                  # Internal utils (use-mobile, assistant-utils)
+├── contexts/                    # React contexts (LayoutContext, ThemeContext, etc.)
+├── hooks/                       # Hook re-exports
+├── utils/                       # Utility functions (demo-responses, gemini)
+├── styles/                      # Global CSS and token maps
+├── templates/                   # CLI scaffold template (FSD/FDA project)
+├── bin/                         # CLI source and compiled output
+├── dist/                        # Compiled library (ES + CJS + CSS + types)
+├── docs/                        # Markdown docs (ships in package for AI agents)
+├── llms.txt                     # AI documentation index
+├── llms-compact.txt             # Compact AI reference
+├── llms-full.txt                # Full AI documentation
+└── components.json              # Machine-readable component registry
+```
+
+### Why source ships with the package
+
+The `components/` directory is intentionally included in the npm package (via the `files` field in `package.json`). AI agents running in consumer projects can inspect source, stories, and documentation directly from `node_modules/xertica-ui/`. This is the primary AI-first design decision.
+
+---
+
+## 4. Subpath Exports
+
+The package exposes 7 entry points. Always use the most specific subpath:
+
+```tsx
+import { Button, Card, Input }        from 'xertica-ui/ui';
+import { Sidebar, Header }            from 'xertica-ui/layout';
+import { XerticaProvider, XerticaLogo } from 'xertica-ui/brand';
+import { XerticaAssistant }           from 'xertica-ui/assistant';
+import { VideoPlayer, AudioPlayer }   from 'xertica-ui/media';
+import { useLayout, useTheme }        from 'xertica-ui/hooks';
+import 'xertica-ui/style.css';        // once, at root
+```
+
+The root `from 'xertica-ui'` exports everything and remains supported for backward compatibility.
+
+### Adding a new export to a subpath
+
+1. Add the export to the relevant barrel (`components/[category]/index.ts`)
+2. Verify it appears in the compiled `dist/[category].es.js` after `npm run build`
+3. If adding a new top-level category, also update `vite.config.ts` (`lib.entry`) and `package.json` (`exports`)
+
+---
+
+## 5. Design Tokens — Rules for Component Authors
+
+All components must use semantic CSS tokens exclusively. Never hardcode colors, radii, or shadows:
+
+```tsx
+// ✅ Correct
+className="bg-primary text-primary-foreground rounded-[var(--radius)]"
+
+// ❌ Wrong
+className="bg-blue-600 text-white rounded-lg"
+style={{ backgroundColor: '#3b82f6' }}
+```
+
+### Token reference
+
+```
+bg-background / text-foreground       Page background and body text
+bg-card / text-card-foreground        Card surfaces
+bg-muted / text-muted-foreground      Subdued backgrounds and secondary text
+bg-primary / text-primary-foreground  Primary actions and active states
+bg-secondary / text-secondary-fg      Secondary actions
+bg-destructive                        Danger / error states
+bg-accent / text-accent-foreground    Hover states
+bg-success / bg-info / bg-warning     Semantic state colors
+border-border                         Standard borders
+border-input                          Form field borders
+ring-ring                             Focus rings
+```
+
+### Border radius
+
+Always use `rounded-[var(--radius)]` — never `rounded-sm`, `rounded-lg`, or any fixed radius class. The radius is a brand token that must be overridable by consumers.
+
+---
+
+## 6. Component Authoring Rules
+
+### Non-negotiable
+
+- **Never use native HTML interactive elements** where a library component exists. `<Button>` wraps `<button>`, `<Input>` wraps `<input>`. New components must follow the same pattern.
+- **All interactive components must be keyboard navigable** and follow ARIA patterns. Build on Radix UI primitives.
+- **Icons come from `lucide-react` only.** No custom SVGs, no other icon libraries.
+- **No raw inline styles** (except for dynamic values like `sidebarWidth` that genuinely require them).
+
+### Component file structure
+
+```
+components/ui/my-component/
+  index.ts          ← public re-exports only
+  my-component.tsx  ← implementation
+  my-component.stories.tsx
+  my-component.mdx
+  my-component.test.tsx
+```
+
+### Stories requirements
+
+Every component must have:
+- A `Default` story showing the most common usage
+- Stories for all major prop variants
+- An MDX page with: overview, when to use / not to use, props table, examples, AI Rules
+
+### AI Rules section (mandatory in every component doc)
+
+The `## AI Rules` section at the bottom of every `docs/components/[name].md` must contain:
+- What the agent must NEVER do with this component
+- What the agent must ALWAYS do
+- Common mistakes the AI makes and their correct form
+
+---
+
+## 7. Adding a New Component
+
+1. Create `components/ui/[name]/` with the 4 required files (source, stories, mdx, test)
+2. Export from `components/ui/index.ts`
+3. Create `docs/components/[name].md` following the existing format
+4. Add an entry to `components.json` with all fields: `name`, `docPath`, `sourcePath`, `description`, `category`, `import`, `keywords`, `relatedComponents`
+5. Add the component to the relevant section of `llms-full.txt`
+6. Add a one-line entry to `llms.txt` under the correct category
+7. Update `llms-compact.txt` if the component is commonly used
+8. Update `docs/decision-tree.md` if it overlaps with existing components
+9. Update the component count in `README.md`, `llms.txt`, `llms-full.txt`, and `docs/llms.md`
+10. Add a `CHANGELOG.md` entry
+
+---
+
+## 8. Build System
+
+```bash
+npm run build             # Vite multi-entry build (ES + CJS, 7 entry points)
+npm run build:types       # tsc declarations → dist/components/**/*.d.ts
+npm run build:cli         # tsup CLI build → dist/cli.js
+npm run build:production  # alias for npm run build
+```
+
+**prepublishOnly** runs all three in sequence automatically on `npm publish`.
+
+### Multi-entry build
+
+`vite.config.ts` uses `lib.entry` as an object with 7 keys. Output files follow `[entryName].[format].js`. UMD is NOT used (Vite does not support multi-entry + UMD). Format is `["es", "cjs"]`.
+
+### TypeScript declarations
+
+`tsconfig.build.json` compiles declarations. It includes `components/**/*`, `contexts/**/*`, `hooks/**/*`. The `dist/components/` structure mirrors the source and is referenced by the `types` fields in `package.json` exports.
+
+---
+
+## 9. CLI
+
+The CLI (`bin/cli.ts`) scaffolds new projects via `npx xertica-ui@latest init`.
+
+**What the CLI does:**
+1. Copies root config files from `templates/`
+2. Copies `CLAUDE.md` to the project root (AI system prompt)
+3. Copies `src/app/` (App.tsx, AppLayout.tsx)
+4. Copies `src/shared/` (navigation.ts, auth.ts, types)
+5. Copies selected `src/features/` (auth, home, template)
+6. Copies selected `src/pages/` thin wrappers
+7. Generates a tailored `AuthGuard.tsx` based on selected pages
+8. Generates `src/styles/xertica/tokens.css` for the chosen color theme
+
+**`update` command** lets users update theme only or update all project files to a specific version of `xertica-ui`.
+
+---
+
+## 10. Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **Patch** (2.0.x): Bug fixes, doc updates, export additions that don't break anything
+- **Minor** (2.x.0): New components, new subpath exports, new CLI features
+- **Major** (x.0.0): Breaking changes to component APIs, token renames, export removals
+
+Every version bump must:
+1. Update `version` in `package.json`
+2. Update `.version()` in `bin/cli.ts`
+3. Update the version badge in `README.md`
+4. Add a `CHANGELOG.md` entry with Added / Changed / Fixed sections
+5. Update `templates/package.json` `xertica-ui` dependency to `^[new-version]`
+
+---
+
+## 11. Pre-Release Checklist
+
+Before running `npm publish`:
+
+- [ ] `npm run build:production` passes without errors
+- [ ] `npm run build:types` passes without errors
+- [ ] `npm run build:cli` passes without errors
+- [ ] All new components have docs in `docs/components/`, entry in `components.json`, and section in `llms-full.txt`
+- [ ] `llms.txt` is up to date (component count, new entries)
+- [ ] `CHANGELOG.md` has an entry for this version
+- [ ] `README.md` version badge is updated
+- [ ] `templates/package.json` references the new version
+- [ ] `bin/cli.ts` `.version()` matches `package.json`