forlogic-core 2.0.3 → 2.0.4

package/README.md

@@ -1,1033 +1,303 @@
-# 🧱 Guia de Desenvolvimento
+# forlogic-core — Knowledge Base
 
-> **IMPORTANTE**: Este README é genérico para todos os projetos. Para configurações específicas do projeto (como schema padrão), consulte o **Custom Knowledge** do projeto nas configurações do Lovable.
+> **Documento de referência** para projetos que consomem `forlogic-core`.
+> Cole este conteúdo como Custom Knowledge no Lovable ou use como README.md com Claude Code.
 
 ---
 
-## 📦 Instalação
+## 🔗 Cross-Project: Projeto Admin (DS + Lib)
 
-### Pré-requisitos
+> **Para consultar componentes, props, tipos, exemplos e implementação**: use cross-project (`@Admin`) para ler arquivos do projeto **"Admin"** (`qualiex-admin`).
 
-A biblioteca `forlogic-core` requer as seguintes **peer dependencies** instaladas no seu projeto:
+### Caminhos úteis no projeto Admin
 
-```bash
-# Dependências obrigatórias
-npm install react@^18.0.0 react-dom@^18.0.0
-npm install lucide-react@>=0.400.0
-
-# Internacionalização (i18n)
-npm install i18next@^25.0.0 react-i18next@^16.0.0
-```
-
-### Instalar a Biblioteca
-
-```bash
-npm install forlogic-core
-```
-
-**Nota**: O npm/yarn irá alertar automaticamente se alguma peer dependency estiver faltando ou com versão incompatível.
-
-### ⚠️ IMPORTANTE: Imports de i18n
-
-**Sempre** importe hooks de internacionalização do `forlogic-core`, nunca diretamente de `react-i18next`:
-
-```tsx
-// ❌ ERRADO - Causa conflito de instâncias (erro NO_I18NEXT_INSTANCE)
-import { useTranslation } from 'react-i18next';
-
-// ✅ CORRETO - Usa a mesma instância configurada pelo CoreProviders
-import { useTranslation } from 'forlogic-core';
-```
-
-Isso garante que todos os componentes compartilhem a mesma instância do i18next configurada pelo `CoreProviders`.
+| O que procurar | Caminho no Admin |
+|----------------|------------------|
+| Código-fonte dos componentes UI | `lib/components/ui/` |
+| Sistema CRUD | `lib/crud/` |
+| Barrel exports (lista completa) | `lib/exports/ui.ts`, `lib/exports/index.ts` |
+| Documentação MD do Design System | `docs/design-system/` |
+| Docs interativos (código-fonte) | `src/design-system/docs/` |
+| Hooks compartilhados | `lib/hooks/` |
+| Providers (CoreProviders) | `lib/providers/` |
+| Serviços (Base, Email, Error) | `lib/services/` |
+| Config Vite/Tailwind | `lib/vite/`, `lib/tailwind/` |
 
 ---
 
-## 📦 LIB-FIRST: Sempre Use Componentes da forlogic-core
-
-> **⚠️ REGRA FUNDAMENTAL**: Antes de criar qualquer componente, serviço ou utilitário no projeto, VERIFIQUE se já existe na `forlogic-core`.
-
-### 🤔 Por Quê?
-
-A `forlogic-core` é a **biblioteca central** de componentes, serviços e utilitários compartilhados entre todos os projetos. Quando você cria um componente local que já existe na lib:
+## 0. Schema do Projeto
 
-1. **❌ Drift de Design** - O componente local não acompanha evoluções futuras da lib
-2. **❌ Duplicação de Código** - Aumenta tamanho do bundle e manutenção
-3. **❌ Inconsistência** - UI/UX diferente entre projetos
-4. **❌ Retrabalho** - Correções de bugs precisam ser feitas em múltiplos lugares
+> ⚠️ **Substitua `SCHEMA_PADRAO` pelo schema do SEU projeto.**
 
-### 📋 Checklist OBRIGATÓRIO Antes de Criar Componentes
+```ts
+// ✅ CORRETO
+supabase.schema('SCHEMA_PADRAO').from('tabela').select('*');
 
-```markdown
-- [ ] Pesquisei se o componente existe na forlogic-core?
-- [ ] Verifiquei a documentação do Design System (/design_system)?
-- [ ] Confirmei que a funcionalidade não pode ser alcançada com props/variantes existentes?
-- [ ] Se não existe, solicitei a inclusão na lib para beneficiar todos os projetos?
+// ❌ ERRADO (vai falhar)
+supabase.from('tabela').select('*');
 ```
 
-### ✅ CORRETO: Usar da Lib
-
-```typescript
-// ✅ Sempre importe da forlogic-core
-import {
-  Button,
-  Input,
-  Dialog,
-  Combobox,
-  SplitButton,
-  RichTextEditor,
-  createCrudPage,
-  cn,
-  formatDatetime
-} from 'forlogic-core';
-```
-
-### ❌ PROIBIDO: Criar Localmente (se existe na lib)
-
-```typescript
-// ❌ NUNCA crie pastas/arquivos que já existem na lib
-src/components/ui/button.tsx      // Existe na lib
-src/components/ui/dialog.tsx      // Existe na lib
-src/lib/utils.ts                  // cn() existe na lib
-src/components/SplitButton.tsx    // Existe na lib (a partir de v1.12.2)
-```
-
-### 🔄 Processo Quando Precisa de Customização
-
-| Cenário                             | Ação Correta                                         |
-| ----------------------------------- | ---------------------------------------------------- |
-| Componente não existe na lib        | ✅ Criar localmente E solicitar inclusão na lib      |
-| Precisa de variante nova            | ✅ Solicitar variante na lib (PR ou pedido)          |
-| Precisa de comportamento específico | ✅ Usar composição/wrapper ao invés de recriar       |
-| Bug no componente da lib            | ✅ Reportar e corrigir na lib, não criar cópia local |
-
-### 📖 Onde Verificar Componentes Disponíveis
-
-| Recurso                           | Descrição                                           |
-| --------------------------------- | --------------------------------------------------- |
-| `/design_system`                  | Design System com todos os componentes documentados |
-| `forlogic-core/lib/exports/ui.ts` | Lista de exports de UI                              |
-| `forlogic-core/lib/index.ts`      | Index principal com todos os exports                |
-
-### ⚠️ Exceções (quando PODE criar localmente)
-
-1. **Componente específico de negócio** - Ex: `InvoiceCard`, `UserProfileWidget`
-2. **Composição de componentes da lib** - Ex: wrapper que combina Dialog + Form
-3. **Componente temporário** - Protótipo que será migrado para a lib depois
-4. **Funcionalidade não generalizável** - Algo tão específico que não faz sentido na lib
-
-> **📝 Mesmo nas exceções, avalie se o componente poderia ser generalizado e incluído na lib para beneficiar outros projetos.**
-
 ---
 
-## 🤖 REGRAS CRÍTICAS
+## 1. Regras Invioláveis
 
-> **📋 Schema Padrão**: Veja no **Custom Knowledge** do projeto (Settings → Manage Knowledge) qual é o schema padrão deste projeto específico.
+| Regra | Detalhe |
+|-------|---------|
+| Schema obrigatório | `.schema('SCHEMA_PADRAO')` em toda query Supabase |
+| Sem DELETE físico | Soft delete com `deleted_at` + policy `FOR UPDATE` |
+| Sem índices automáticos | Apenas com aprovação explícita + EXPLAIN ANALYZE |
+| Sem modificar `.env` | Apenas com autorização do usuário |
+| Sem hardcoded admin | Nunca localStorage/sessionStorage para roles |
+| Lib-first | Usar `forlogic-core` antes de criar componente |
+| Import do Supabase | Sempre `getSupabaseClient()` de `forlogic-core` |
+| Import de i18n | Sempre `useTranslation` de `forlogic-core`, nunca de `react-i18next` |
 
-### ⚠️ TOP 4 ERROS MAIS COMUNS
+---
 
-1. **ESQUECER SCHEMA**
+## 2. RLS — Políticas de Segurança
 
-```typescript
-// ❌ ERRADO
-.from('table')
+### Sintaxe obrigatória
 
-// ✅ CORRETO (verifique o schema padrão no Custom Knowledge)
-.schema('SEU_SCHEMA').from('table')
-```
+- `SELECT` → `USING` | `INSERT` → `WITH CHECK` | `UPDATE` → `USING` + `WITH CHECK`
+- **Nunca** `FOR DELETE`
+- **Sempre** `(SELECT auth.jwt())` com parênteses (evita re-execução por linha)
 
-2. **RLS COM SINTAXE INCORRETA**
+### Padrão JWT alias (multi-tenancy)
 
 ```sql
--- ❌ ERRADO: Usar WITH CHECK em SELECT
-CREATE POLICY "Users view own" ON seu_schema.table
-FOR SELECT WITH CHECK (auth.uid() = id_user);
-
--- ✅ CORRETO: USING para SELECT
-CREATE POLICY "Users view own" ON seu_schema.table
+CREATE POLICY "table_select" ON SCHEMA_PADRAO.tabela
 FOR SELECT USING (
   ((SELECT auth.jwt()) ->> 'alias'::text) = alias
 );
-```
 
-3. **CRIAR POLÍTICAS DELETE**
-
-```sql
--- ❌ PROIBIDO: Política DELETE
-CREATE POLICY "table_delete" ON seu_schema.table
-FOR DELETE USING (...);
+CREATE POLICY "table_insert" ON SCHEMA_PADRAO.tabela
+FOR INSERT WITH CHECK (
+  ((SELECT auth.jwt()) ->> 'alias'::text) = alias
+);
 
--- ✅ CORRETO: Use soft delete com UPDATE
-ALTER TABLE seu_schema.table ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE;
+CREATE POLICY "table_update" ON SCHEMA_PADRAO.tabela
+FOR UPDATE
+USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias)
+WITH CHECK (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
 ```
 
-4. **CRIAR ÍNDICES AUTOMATICAMENTE**
+### Soft delete (padrão obrigatório)
 
 ```sql
--- ❌ PROIBIDO criar índices sem aprovação
-CREATE INDEX idx_table_user ON seu_schema.table(id_user);
+ALTER TABLE SCHEMA_PADRAO.tabela ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE;
 
--- ✅ Apenas quando solicitado explicitamente e aprovado
+CREATE POLICY "table_select" ON SCHEMA_PADRAO.tabela
+FOR SELECT USING (
+  deleted_at IS NULL
+  AND ((SELECT auth.jwt()) ->> 'alias'::text) = alias
+);
 ```
 
 ---
 
-## 📝 CONVENÇÕES DE NOMENCLATURA
-
-### ⚠️ PADRÕES OBRIGATÓRIOS
-
-**Foreign Keys (Chaves Estrangeiras):**
-
-```typescript
-// ❌ ERRADO
-process_id: string
-user_id: string
-
-// ✅ CORRETO - Sempre prefixo id_
-id_process: string
-id_user: string
-```
-
-**Booleans:**
+## 3. Convenções SQL
 
-```typescript
-// ❌ ERRADO
-active: boolean
-removed: boolean
-
-// ✅ CORRETO - Sempre prefixo is_
-is_active: boolean
-is_removed: boolean
-```
-
-**Timestamps:**
-
-```typescript
-// ❌ ERRADO
-creation_date: string
-update_time: string
-
-// ✅ CORRETO - Sempre sufixo _at
-created_at: string
-updated_at: string
-deleted_at: string
-```
+| Tipo | Padrão | Exemplo |
+|------|--------|---------|
+| FK | `id_<singular>` | `id_process`, `id_user` |
+| Boolean | `is_` / `has_` | `is_active`, `has_access` |
+| Timestamps | `created_at`, `updated_at`, `deleted_at` | — |
+| Tabelas | plural, snake_case | `processes`, `user_roles` |
 
 ---
 
-## 🚫 ÍNDICES: ABSOLUTAMENTE PROIBIDO CRIAR AUTOMATICAMENTE
-
-### ⚠️ REGRA DE OURO
-
-**NUNCA, EM HIPÓTESE ALGUMA, criar índices automaticamente em migrations!**
+## 4. Lib-First — forlogic-core
 
-### 🤔 Por Quê?
+> Antes de criar qualquer componente, verificar se já existe em `forlogic-core`.
 
-1. **Custo**: Índices ocupam espaço em disco e custam dinheiro
-2. **Performance de Escrita**: Cada índice adiciona overhead em INSERTs/UPDATEs
-3. **Otimização Prematura**: 99% dos índices criados "por precaução" nunca são usados
-4. **Manutenção**: Índices desnecessários dificultam manutenção e análise de queries
+### Import correto
 
-### ❌ Casos PROIBIDOS (mesmo que pareçam "boas práticas")
-
-```sql
--- ❌ PROIBIDO: Índice em FK "porque é boa prática"
-CREATE INDEX idx_subprocess_process ON subprocesses(id_process);
-
--- ❌ PROIBIDO: Índice em campo de busca "porque pode ser útil"
-CREATE INDEX idx_process_title ON processes(title);
-
--- ❌ PROIBIDO: Índice composto "por precaução"
-CREATE INDEX idx_deliverable_status ON deliverables(id_subprocess, is_completed);
+```ts
+import {
+  Button, Dialog, Input, Combobox, SplitButton, RichTextEditor,
+  createCrudPage, CrudTable, CrudActionBar, BaseForm,
+  ActionButton, EmptyState, LoadingState, StepSelector,
+  cn, formatDatetime, useTranslation
+} from 'forlogic-core';
 ```
 
-### ✅ Quando Criar Índices?
+### Checklist
 
-**APENAS** quando:
+- [ ] Pesquisei se existe na forlogic-core?
+- [ ] Verifiquei o Design System (`@Admin docs/design-system/`)?
+- [ ] Pode ser alcançado com props/variantes existentes?
 
-1. ✅ **Solicitado explicitamente** pelo usuário
-2. ✅ **Análise de performance** comprovou necessidade (EXPLAIN ANALYZE)
-3. ✅ **Aprovação prévia** do usuário para incluir na migration
+### Exceções (pode criar localmente)
 
-### 📋 Checklist OBRIGATÓRIO Antes de Qualquer Migration
+1. Componente específico de negócio (ex: `InvoiceCard`)
+2. Composição de componentes da lib (wrapper Dialog + Form)
+3. Protótipo temporário que será migrado para a lib
 
-```markdown
-- [ ] A migration NÃO contém NENHUM `CREATE INDEX`?
-- [ ] A migration NÃO contém políticas DELETE?
-- [ ] Se contém índice, o usuário solicitou EXPLICITAMENTE?
-- [ ] Se contém índice, foi feita análise de performance (EXPLAIN ANALYZE)?
-- [ ] Se contém índice, o usuário APROVOU adicionar à migration?
-- [ ] Estou usando soft delete ao invés de DELETE físico?
-- [ ] Especifiquei o schema correto em todas as tabelas?
-- [ ] Usei sintaxe correta nas políticas RLS (USING vs WITH CHECK)?
-```
-
-### 🔧 Processo Correto Para Criar Índices
-
-1. **Usuário solicita** OU problemas de performance são detectados
-2. **Rodar EXPLAIN ANALYZE** para confirmar necessidade
-3. **Perguntar ao usuário**: "Posso criar o índice X na coluna Y? Isso vai melhorar a query Z mas adiciona overhead."
-4. **Aguardar aprovação** do usuário
-5. **Criar migration separada** apenas com os índices aprovados
-
-### 📝 Template de Migration de Índices (quando aprovado)
-
-```sql
--- Migration: [TIMESTAMP]_add_performance_indexes.sql
--- Aprovado em: [DATA]
--- Justificativa: [RAZÃO ESPECÍFICA]
+---
 
-CREATE INDEX idx_processes_title ON processes.processes(title);
--- Melhora busca por título em 80% (EXPLAIN ANALYZE anexo)
-```
+## 5. Design System — Categorias
+
+> Para ver props e exemplos: `@Admin docs/design-system/<arquivo>.md`
+
+| Categoria | Arquivo |
+|-----------|---------|
+| Fundação | `foundation.md` |
+| Botões & Ações | `buttons-actions.md` |
+| Inputs | `inputs.md` |
+| Seletores | `selectors.md` |
+| Data Display | `data-display.md` |
+| Data Grid | `tables-grids.md` |
+| Gráficos & Dashboards | `charts-dashboards.md` |
+| Navegação | `navigation.md` |
+| Dialogs | `dialogs.md` |
+| Notifications & Feedback | `notifications-feedback.md` |
+| Layout | `layout.md` |
+| CRUD | `crud.md` |
+| Plataforma | `platform.md` |
+| Business Components | `domain.md` |
+| Developer Tools | `infra-utils.md` |
+
+### Aliases disponíveis
+
+| Original | Alias(es) |
+|----------|-----------|
+| Combobox | SelectSearch, MultiSelect, EntitySelect, AutoComplete |
+| ComboTree | TreeSelect |
+| StepSelector | Stepper |
+| ActionButton | ActionMenu, RowActions |
+| TruncatedCell | EllipsisText |
+| CrudPrimitiveTable | DataTable |
+| CrudPrimitivePagination | DataPagination |
+| CrudPrimitiveFilterBar | DataFilterBar |
 
 ---
 
-## ⚙️ Configuração Vite e Tailwind (Projetos Consumidores)
+## 6. Padrões CRUD
 
-A biblioteca `forlogic-core` exporta configurações padronizadas de Vite e Tailwind para garantir consistência de segurança e estilo em todos os projetos.
+### Toolbar — Layout obrigatório de 3 zonas
 
-### 📦 Imports Disponíveis
+| Zona | Posição | Conteúdo |
+|------|---------|----------|
+| Esquerda | `justify-start` | Botão "Novo" + Dropdown ações em lote |
+| Centro | `flex-1 max-w-md` | Campo de busca |
+| Direita | `justify-end` | Filtros + Toggle view |
 
-```typescript
-// Configurações Vite (headers de segurança, CSP, CORS)
-import { createSecurityHeadersPlugin, createForlogicViteConfig } from 'forlogic-core/vite';
+### Defaults
 
-// Preset Tailwind (cores, animações, gradientes)
-import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
-```
+- Column resize/manager: ativados por padrão
+- Paginação: 25 itens/página
+- Busca: no header (na action bar com `showSearch=true`)
+- Ações de linha: sempre usar `ActionButton` da lib
 
 ---
 
-### 🔒 Plugin de Headers de Segurança (Vite)
-
-O plugin configura automaticamente:
-
-- **Content Security Policy (CSP)** - Proteção contra XSS e injeção de scripts
-- **CORS seguro** - Origens confiáveis sem usar `*`
-- **Headers OWASP** - HSTS, X-Content-Type-Options, X-Frame-Options, etc.
-- **Permissions Policy** - Controle de APIs do navegador
-
-#### Uso Básico
+## 7. Padrões Deprecated
 
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
-import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
+| ❌ Não usar | ✅ Usar |
+|------------|--------|
+| `BulkActionBar` separado | Dropdown no `CrudActionBar` |
+| `<MoreHorizontal>` genérico | `ActionButton` |
+| Paginação manual | `CrudPrimitivePagination` |
+| `StatusSelect` | `Combobox` |
+| `DeleteConfirmationDialog` | `Dialog` |
+| `Searchbar` | `Input` com ícone |
+| `public` schema | `.schema('SCHEMA_PADRAO')` |
 
-export default defineConfig(({ mode }) => ({
-  plugins: [
-    react(),
-    createSecurityHeadersPlugin(mode === 'development', {
-      supabaseUrls: ['https://seu-projeto.supabase.co'],
-    }),
-  ],
-}));
-```
+---
 
-#### Configuração Completa
+## 8. Configuração — Vite
 
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
+```ts
 import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
 
 export default defineConfig(({ mode }) => ({
   plugins: [
     react(),
     createSecurityHeadersPlugin(mode === 'development', {
-      // URLs do Supabase para permitir conexões
-      supabaseUrls: [
-        'https://seu-projeto-dev.supabase.co',
-        'https://seu-projeto-prod.supabase.co',
-      ],
-
-      // Origens confiáveis adicionais para CORS
-      trustedOrigins: [
-        'https://meu-app.com',
-        'https://admin.meu-app.com',
-      ],
-
-      // APIs externas para connect-src
-      additionalConnectSrc: [
-        'https://api.exemplo.com',
-        'wss://websocket.exemplo.com',
-      ],
-
-      // CDNs de scripts/estilos/fontes adicionais
-      additionalScriptSrc: ['https://cdn.analytics.com'],
-      additionalStyleSrc: ['https://fonts.custom.com'],
-      additionalFontSrc: ['https://fonts.gstatic.com'],
-
-      // URI para reportar violações CSP
-      cspReportUri: 'https://seu-projeto.supabase.co/functions/v1/csp-report',
-
-      // Opções de produção (defaults: true)
-      enableTrustedTypes: true,
-      upgradeInsecureRequests: true,
+      supabaseUrls: ['https://SEU_PROJETO.supabase.co'],
+      additionalConnectSrc: ['https://*.qualiex.com'],
     }),
   ],
+  resolve: { alias: { '@': path.resolve(__dirname, './src') } },
+  optimizeDeps: { force: true },
 }));
 ```
 
-#### Opções do Plugin
-
-| Opção                     | Tipo       | Padrão | Descrição                               |
-| ------------------------- | ---------- | ------ | --------------------------------------- |
-| `supabaseUrls`            | `string[]` | `[]`   | URLs do Supabase permitidas             |
-| `trustedOrigins`          | `string[]` | `[]`   | Origens confiáveis adicionais para CORS |
-| `additionalScriptSrc`     | `string[]` | `[]`   | Fontes de script adicionais para CSP    |
-| `additionalStyleSrc`      | `string[]` | `[]`   | Fontes de estilo adicionais para CSP    |
-| `additionalConnectSrc`    | `string[]` | `[]`   | APIs/WebSockets adicionais para CSP     |
-| `additionalFontSrc`       | `string[]` | `[]`   | Fontes de font adicionais para CSP      |
-| `cspReportUri`            | `string`   | -      | URI para relatório de violações CSP     |
-| `enableTrustedTypes`      | `boolean`  | `true` | Habilitar Trusted Types em produção     |
-| `upgradeInsecureRequests` | `boolean`  | `true` | Upgrade HTTP→HTTPS em produção          |
-
 ---
 
-### 🏗️ Factory de Configuração Vite (Opcional)
-
-Para projetos que desejam usar a configuração padronizada com segurança:
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
-import path from 'path';
-import { createForlogicViteConfig } from 'forlogic-core/vite';
-
-const forlogicConfig = createForlogicViteConfig({
-  security: {
-    supabaseUrls: ['https://seu-projeto.supabase.co'],
-    trustedOrigins: ['https://meu-app.com'],
-  },
-  server: { host: '::', port: 8080 },
-  build: { chunkSizeWarningLimit: 4000 },
-});
-
-export default defineConfig(({ mode }) => {
-  const isDev = mode === 'development';
-  const baseConfig = forlogicConfig(isDev);
-
-  return {
-    ...baseConfig,
-    plugins: [react(), ...baseConfig.plugins],
-    // IMPORTANTE: resolve.alias deve usar caminhos absolutos
-    resolve: {
-      alias: {
-        '@': path.resolve(__dirname, './src'),
-      },
-    },
-  };
-});
-```
-
-> **⚠️ IMPORTANTE**: A factory **não** configura `resolve.alias` porque caminhos relativos não funcionam corretamente no build. Cada projeto deve definir seus próprios aliases com `path.resolve(__dirname, './caminho')` para garantir caminhos absolutos.
-
----
-
-### 📋 Template Completo para Projetos Consumidores
-
-Copie e adapte este template para novos projetos:
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react-swc';
-import path from 'path';
-import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
-
-export default defineConfig(({ mode }) => {
-  const isDev = mode === 'development';
-
-  return {
-    server: {
-      host: '::',
-      port: 8080,
-    },
-
-    // Força re-bundle quando atualizar forlogic-core
-    optimizeDeps: {
-      force: true,
-    },
-
-    plugins: [
-      react(),
-      // Headers de segurança (CSP, CORS, etc.)
-      createSecurityHeadersPlugin(isDev, {
-        supabaseUrls: [
-          'https://SEU_PROJETO.supabase.co',
-        ],
-        additionalConnectSrc: [
-          'https://*.qualiex.com',
-        ],
-        // Opcional: URI para relatório de violações CSP
-        cspReportUri: isDev
-          ? 'https://SEU_PROJETO_DEV.supabase.co/functions/v1/csp-report'
-          : 'https://SEU_PROJETO_PROD.supabase.co/functions/v1/csp-report',
-      }),
-    ],
-
-    // CRÍTICO: Aliases devem usar caminhos absolutos
-    resolve: {
-      alias: {
-        '@': path.resolve(__dirname, './src'),
-      },
-    },
-
-    publicDir: false,
-
-    esbuild: {
-      sourcemap: true,
-      target: 'es2020',
-    },
-
-    build: {
-      chunkSizeWarningLimit: 4000,
-    },
-  };
-});
-```
-
-#### Checklist de Configuração
-
-```markdown
-- [ ] Substituiu `SEU_PROJETO` pelas URLs do Supabase
-- [ ] Adicionou origens confiáveis em `additionalConnectSrc` se necessário
-- [ ] Verificou que `resolve.alias` usa `path.resolve(__dirname, ...)`
-- [ ] Reiniciou o servidor após modificar o arquivo
-```
-
----
-
-### 🔄 Forçar Re-bundle de Dependências
-
-Se você atualizar a `forlogic-core` e as mudanças não aparecerem no preview:
-
-```typescript
-// vite.config.ts
-export default defineConfig(({ mode }) => ({
-  optimizeDeps: {
-    force: true, // Força re-otimização a cada restart do dev server
-  },
-  // ...
-}));
-```
-
-> **⚠️ IMPORTANTE**: Após adicionar `force: true`, reinicie o servidor completamente (pare e inicie novamente).
-
----
-
-### 🎨 Preset Tailwind CSS
-
-O preset inclui:
-
-- **Cores semânticas** - primary, secondary, destructive, success, warning, etc.
-- **Border radius** - lg, md, sm padronizados
-- **Animações** - accordion, fade, slide, scale
-- **Gradientes** - primary, secondary, accent
-- **Sombras** - xs até 2xl, inner, primary
-
-#### Uso Básico
-
-```typescript
-// tailwind.config.ts
-import type { Config } from 'tailwindcss';
-import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
-
-export default {
-  presets: [forlogicTailwindPreset],
-  content: [
-    ...forlogicContentPaths,
-    // Paths adicionais específicos do seu projeto
-  ],
-} satisfies Config;
-```
-
-#### Uso com Extensões
+## 9. Configuração — Tailwind
 
-```typescript
-// tailwind.config.ts
-import type { Config } from 'tailwindcss';
+```ts
 import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
 
 export default {
   presets: [forlogicTailwindPreset],
-  content: [
-    ...forlogicContentPaths,
-  ],
-  theme: {
-    extend: {
-      // Extensões específicas do seu projeto
-      colors: {
-        brand: {
-          50: 'hsl(var(--brand-50))',
-          // ...
-        },
-      },
-    },
-  },
-  plugins: [
-    require('tailwindcss-animate'),
-    // Plugins adicionais
-  ],
+  content: [...forlogicContentPaths],
 } satisfies Config;
 ```
 
-#### Content Paths Padrão
-
-O `forlogicContentPaths` inclui:
-
-```typescript
-[
-  './pages/**/*.{ts,tsx}',
-  './components/**/*.{ts,tsx}',
-  './app/**/*.{ts,tsx}',
-  './src/**/*.{ts,tsx}',
-  './lib/**/*.{ts,tsx}',
-  './node_modules/forlogic-core/dist/**/*.{js,ts,jsx,tsx}',
-]
-```
-
----
-
-### 📋 Checklist de Configuração
-
-```markdown
-- [ ] Instalou `forlogic-core` no projeto?
-- [ ] Configurou `vite.config.ts` com `createSecurityHeadersPlugin`?
-- [ ] Adicionou URLs do Supabase em `supabaseUrls`?
-- [ ] Configurou `tailwind.config.ts` com `forlogicTailwindPreset`?
-- [ ] Adicionou `forlogicContentPaths` ao content?
-- [ ] Definiu variáveis CSS no `index.css` (--primary, --background, etc.)?
-```
-
 ---
 
-### 🔧 Configuração do package.json (Publicação da Lib)
-
-Para projetos que estão **publicando** a `forlogic-core`, adicione os exports condicionais:
-
-```json
-{
-  "exports": {
-    ".": {
-      "import": "./dist/index.esm.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./vite": {
-      "import": "./dist/vite/index.esm.js",
-      "require": "./dist/vite/index.js",
-      "types": "./dist/vite/index.d.ts"
-    },
-    "./tailwind": {
-      "import": "./dist/tailwind/index.esm.js",
-      "require": "./dist/tailwind/index.js",
-      "types": "./dist/tailwind/index.d.ts"
-    }
-  }
-}
-```
-
----
-
-## 🚩 Feature Flags (Variáveis de Ambiente)
-
-A biblioteca suporta feature flags para habilitar/desabilitar funcionalidades opcionais.
-
-### Variáveis Disponíveis
-
-| Variável                     | Descrição                                                                            | Valores              | Padrão    |
-| ---------------------------- | ------------------------------------------------------------------------------------ | -------------------- | --------- |
-| `VITE_SHOW_USER_PREFERENCES` | Exibe opção de "Preferências" no menu do usuário (idioma, timezone, formato de data) | `"true"` / `"false"` | Não exibe |
-| `VITE_I18N_DEBUG_MODE`       | Modo debug de internacionalização (mostra chaves ao invés de traduções)              | `"true"` / `"false"` | `"false"` |
-| `VITE_IS_QUALIEX`            | Define se usa logos Qualiex ou Forlogic                                              | `"true"` / `"false"` | `"false"` |
-
-### Configuração
-
-Adicione no seu arquivo `.env`:
-
-```env
-# Habilitar opção de preferências no perfil do usuário
-VITE_SHOW_USER_PREFERENCES=true
-
-# Modo debug de i18n (mostra chaves com ícones)
-VITE_I18N_DEBUG_MODE=false
-
-# Usar logos Qualiex
-VITE_IS_QUALIEX=true
-```
-
-> **Nota**: Variáveis de ambiente em Vite precisam ter o prefixo `VITE_` para serem expostas ao cliente.
-
----
-
-## 🌐 Setup de Traduções para Projetos Consumidores
-
-O sistema de i18n usa **namespaces**: a lib fornece traduções base no namespace `core` e cada projeto injeta suas traduções no namespace `app`. A resolução é: `app` → `core` → fallback `pt-BR`.
-
-### Requisitos
-
-| Requisito          | Descrição                                 |
-| ------------------ | ----------------------------------------- |
-| `i18next`          | Peer dependency instalada                 |
-| `react-i18next`    | Peer dependency instalada                 |
-| `CoreProviders`    | Wrapper no App.tsx                        |
-
-### Passo 1: Instalar Peer Dependencies
-
-```bash
-npm install i18next@^25.0.0 react-i18next@^16.0.0
-```
-
-### Passo 2: Criar JSONs de Tradução do Projeto
-
-Crie arquivos JSON flat (um por idioma) com as traduções específicas do seu projeto:
-
-```json
-// src/i18n/pt-BR.json
-{
-  "objective": "Objetivo",
-  "key_result": "Resultado-chave",
-  "cycle": "Ciclo"
-}
-```
-
-### Passo 3: Passar para CoreProviders via `appTranslations`
+## 10. Configuração — CoreProviders
 
 ```tsx
-// src/App.tsx
 import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
 import ptBR from './i18n/pt-BR.json';
-// import enUS from './i18n/en-US.json'; // quando tiver
 
 function App() {
   return (
-    <CoreProviders
-      moduleAlias="performance"
-      appTranslations={{
-        'pt-BR': ptBR,
-        // 'en-US': enUS,
-      }}
-    >
-      <BrowserRouter>
-        <Routes>
-          {/* Suas rotas */}
-        </Routes>
-      </BrowserRouter>
+    <CoreProviders moduleAlias="seu-modulo" appTranslations={{ 'pt-BR': ptBR }}>
+      <BrowserRouter><Routes>{/* ... */}</Routes></BrowserRouter>
     </CoreProviders>
   );
 }
-
-export default App;
 ```
 
-### Passo 4: Usar useTranslation do forlogic-core
-
-```tsx
-// ❌ ERRADO - Cria instância separada (erro NO_I18NEXT_INSTANCE)
-import { useTranslation } from 'react-i18next';
-
-// ✅ CORRETO - Usa mesma instância configurada
-import { useTranslation } from 'forlogic-core';
-
-function MeuComponente() {
-  const { t } = useTranslation();
-  return (
-    <div>
-      <h1>{t('objective')}</h1>     {/* namespace app → "Objetivo" */}
-      <Button>{t('save')}</Button>   {/* app → não encontra → core → "Salvar" */}
-    </div>
-  );
-}
-```
-
-### Como funciona a resolução de namespaces
-
-```
-t('save')
-  1. Busca em namespace 'app' (projeto) → não encontrou
-  2. Busca em namespace 'core' (lib) → "Salvar" ✅
-
-t('objective')
-  1. Busca em namespace 'app' (projeto) → "Objetivo" ✅
-
-t('save') com override no app
-  1. Busca em namespace 'app' → "Gravar" ✅ (sobrescreve o core)
-```
-
-### Troubleshooting
-
-#### Traduções mostram apenas as chaves
-
-| Causa                                | Solução                                                |
-| ------------------------------------ | ------------------------------------------------------ |
-| Peer dependencies faltando           | Instalar `i18next` e `react-i18next`                   |
-| Import de `react-i18next` direto     | Usar import de `forlogic-core`                         |
-| `appTranslations` não passado        | Adicionar prop no `CoreProviders`                      |
-| JSON com formato errado              | Deve ser flat: `{ "key": "value" }`, sem nesting       |
-
-#### Debug: Verificar se traduções foram carregadas
-
-```tsx
-import { i18n } from 'forlogic-core';
-
-console.log('i18n initialized:', i18n.isInitialized);
-console.log('Current language:', i18n.language);
-console.log('Loaded resources:', i18n.store.data);
-// Deve mostrar: { 'pt-BR': { core: {...}, app: {...} } }
-```
-
-### Checklist de Configuração
-
-```markdown
-- [ ] Instalou `i18next@^25.0.0` e `react-i18next@^16.0.0`?
-- [ ] Criou JSONs de tradução em `src/i18n/pt-BR.json`?
-- [ ] Passou `appTranslations` para o `CoreProviders`?
-- [ ] Todos os imports de `useTranslation` são de `forlogic-core` (nunca de `react-i18next`)?
-- [ ] O `App.tsx` usa `CoreProviders`?
-```
+### i18n — Resolução: `t('key')` → app → core → fallback
 
 ---
 
-## 🚀 Quick Setup: CoreProviders
-
-O `CoreProviders` é um componente que encapsula todos os providers essenciais da biblioteca, simplificando drasticamente a configuração de novos projetos.
-
-### O que está incluído
+## 11. Feature Flags
 
-O `CoreProviders` encapsula automaticamente:
-
-| Provider              | Descrição                                                   |
-| --------------------- | ----------------------------------------------------------- |
-| `ErrorBoundary`       | Captura e trata erros de renderização React                 |
-| `I18nextProvider`     | Sistema de internacionalização (i18n)                       |
-| `QueryClientProvider` | Cache e gerenciamento de queries (React Query)              |
-| `AuthProvider`        | Autenticação e gerenciamento de sessão                      |
-| `LocaleProvider`      | Gerenciamento de locale (idioma, timezone, formato de data) |
-| `TranslationLoader`   | Carregamento dinâmico de traduções do banco de dados        |
-
-### Uso Básico
-
-```tsx
-import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-
-function App() {
-  return (
-    <CoreProviders>
-      <BrowserRouter>
-        <Routes>
-          {/* Suas rotas aqui */}
-        </Routes>
-      </BrowserRouter>
-    </CoreProviders>
-  );
-}
-```
-
-### Com QueryClient Customizado
-
-Se você precisar de configurações específicas para o React Query:
-
-```tsx
-import { CoreProviders } from 'forlogic-core';
-import { QueryClient } from '@tanstack/react-query';
-import { BrowserRouter } from 'react-router-dom';
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 10 * 60 * 1000, // 10 minutos
-      retry: 2,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
-
-function App() {
-  return (
-    <CoreProviders queryClient={queryClient}>
-      <BrowserRouter>
-        {/* Suas rotas */}
-      </BrowserRouter>
-    </CoreProviders>
-  );
-}
-```
-
-### Props
-
-| Prop          | Tipo          | Obrigatório | Descrição                                                                   |
-| ------------- | ------------- | ----------- | --------------------------------------------------------------------------- |
-| `children`    | `ReactNode`   | ✅          | Componentes filhos a serem envolvidos                                       |
-| `queryClient` | `QueryClient` | ❌          | Instância customizada do QueryClient. Se não fornecido, um default é criado |
-
-### QueryClient Default
-
-Se você não fornecer um `queryClient`, o `CoreProviders` cria um com as seguintes configurações:
-
-```typescript
-{
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutos
-      retry: 1,
-    },
-  },
-}
-```
-
-### Benefícios
-
-- ✅ **Zero configuração de i18n** - Traduções funcionam automaticamente
-- ✅ **Autenticação pronta** - `useAuth()` disponível em qualquer componente filho
-- ✅ **Tratamento de erros** - ErrorBoundary captura erros de renderização
-- ✅ **React Query configurado** - Cache e queries prontos para uso
-- ✅ **Locale gerenciado** - Preferências de idioma, timezone e formato de data
-- ✅ **Atualizações centralizadas** - Novos providers são adicionados automaticamente
+| Variável | Descrição |
+|----------|-----------|
+| `VITE_SHOW_USER_PREFERENCES` | Preferências no menu do usuário |
+| `VITE_I18N_DEBUG_MODE` | Debug de i18n (mostra chaves) |
+| `VITE_IS_QUALIEX` | Logos Qualiex vs Forlogic |
 
 ---
 
-## 🎯 Ações Principais de Módulo (SidebarActionTrigger)
-
-O `SidebarActionTrigger` permite adicionar ações principais de módulo no sidebar, diferenciadas visualmente da navegação. São gatilhos de ação, não destinos de navegação.
-
-### Conceito
-
-| Característica      | Descrição                                                   |
-| ------------------- | ----------------------------------------------------------- |
-| **Ação de módulo**  | Válida apenas dentro do contexto do módulo ao qual pertence |
-| **Não global**      | Não aplicável a todo o sistema                              |
-| **Não contextual**  | Não depende de seleção de item específico                   |
-| **Destaque visual** | Exibida com aparência diferenciada da navegação             |
-
-### Uso Básico
-
-```tsx
-import { AppSidebar, SidebarConfig } from 'forlogic-core';
-import { Plus, FileText, Folder } from 'lucide-react';
-
-const sidebarConfig: SidebarConfig = {
-  appName: 'Meu Módulo',
-
-  // Ações principais do módulo
-  moduleActions: {
-    triggerLabel: 'Criar',
-    triggerIcon: Plus,
-    actions: [
-      {
-        id: 'create-item',
-        label: 'Novo Item',
-        icon: FileText,
-        onClick: () => openCreateDialog()
-      },
-      {
-        id: 'create-folder',
-        label: 'Nova Pasta',
-        icon: Folder,
-        onClick: () => openFolderDialog()
-      },
-    ]
-  },
-
-  // Navegação
-  navigation: [
-    { label: 'Visão Geral', path: '/', icon: Home },
-    { label: 'Configurações', path: '/settings', icon: Settings },
-  ]
-};
-
-<AppSidebar config={sidebarConfig} />
-```
+## 12. Instrução para IA
 
-### Comportamento
-
-| Cenário               | Comportamento                     |
-| --------------------- | --------------------------------- |
-| **Uma ação**          | Clique executa a ação diretamente |
-| **Múltiplas ações**   | Clique exibe dropdown com opções  |
-| **Modal aberto**      | Gatilho fica desabilitado         |
-| **Sidebar colapsada** | Exibe apenas ícone com tooltip    |
-
-### Props do SidebarActionTrigger
-
-| Prop          | Tipo                   | Obrigatório | Descrição                   |
-| ------------- | ---------------------- | ----------- | --------------------------- |
-| `config`      | `SidebarActionsConfig` | ✅          | Configuração das ações      |
-| `isCollapsed` | `boolean`              | ❌          | Se a sidebar está colapsada |
-| `isDisabled`  | `boolean`              | ❌          | Desabilita o gatilho        |
-
-### Interface SidebarModuleAction
-
-```typescript
-interface SidebarModuleAction {
-  id: string;           // Identificador único
-  label: string;        // Texto do botão/opção
-  icon?: LucideIcon;    // Ícone opcional
-  onClick: () => void;  // Callback de execução
-  disabled?: boolean;   // Estado desabilitado
-  permissionCheck?: () => Promise<boolean>;
-}
-```
+**QUANDO** criar ou modificar qualquer arquivo `.tsx` com JSX:
 
-### Interface SidebarActionsConfig
+- **SE** contém tabela, listagem ou CRUD → **LER** `@Admin docs/design-system/crud.md` e `@Admin docs/design-system/tables-grids.md` ANTES de gerar código
+- **SE** contém formulário, input ou campo → **LER** `@Admin docs/design-system/inputs.md` e `@Admin docs/design-system/selectors.md` ANTES
+- **SE** contém modal ou confirmação → **LER** `@Admin docs/design-system/dialogs.md` ANTES
+- **SE** contém botões ou ações de linha → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
+- **SE** é estrutura de página/layout → **LER** `@Admin docs/design-system/layout.md` ANTES
 
-```typescript
-interface SidebarActionsConfig {
-  triggerLabel?: string;    // Rótulo do gatilho (padrão: 'Criar')
-  triggerIcon?: LucideIcon; // Ícone do gatilho (padrão: Plus)
-  actions: SidebarModuleAction[];
-}
-```
+**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência de implementação.
 
-### Gerenciamento de Modais (Opcional)
+**PROIBIDO** gerar JSX sem ter lido a documentação aplicável acima.
 
-Para desabilitar o gatilho quando há modais abertos, use o `ModalStateProvider`:
+**VALIDAÇÃO pós-geração**: Todo import de componente visual DEVE vir de `forlogic-core`. Se criou componente local que existe na lib, refatore imediatamente.
 
-```tsx
-import { CoreProviders, ModalStateProvider, useModalState } from 'forlogic-core';
-
-// No App.tsx (opcional - CoreProviders não inclui por padrão)
-<CoreProviders>
-  <ModalStateProvider>
-    <AppLayout />
-  </ModalStateProvider>
-</CoreProviders>
-
-// Em componentes com modal
-function MeuDialog({ open, onOpenChange }) {
-  const { registerModal, unregisterModal } = useModalState();
-
-  useEffect(() => {
-    if (open) {
-      registerModal('meu-dialog');
-    } else {
-      unregisterModal('meu-dialog');
-    }
-  }, [open]);
-
-  return <Dialog open={open} onOpenChange={onOpenChange}>...</Dialog>;
-}
-```
-
-### Diretriz para Uso via Prompt
-
-#### ✅ Prompts corretos:
-
-- "Adicione uma ação principal 'Criar Processo' no sidebar do módulo"
-- "Configure o módulo para ter duas ações principais: 'Novo Item' e 'Nova Pasta'"
-- "Adicione o botão de criar no topo do sidebar como ação de módulo"
-
-#### ❌ Prompts ambíguos (evitar):
-
-- "Coloque um botão de criar no menu" (ambíguo - qual menu?)
-- "Adicione navegação para criar" (ação ≠ navegação)
-- "Crie um link para nova entidade" (link = navegação, não ação)
+---
 
-> 💡 A IA consegue ler o código-fonte do forlogic-core no projeto **Admin** via cross-project visibility.
+## 13. Fontes de Contexto (Cross-Project)
+
+| O que | Onde buscar via `@Admin` |
+|-------|--------------------------|
+| Props e tipos de componentes | `lib/components/ui/<componente>.tsx` |
+| Implementação CRUD | `lib/crud/` |
+| Documentação MD (para IA) | `docs/design-system/*.md` |
+| Exemplos interativos (código) | `src/design-system/docs/*Doc.tsx` |
+| Design System visual | Rota `/ds` no app Admin |
+| Hooks compartilhados | `lib/hooks/` |
+| Configuração de exports | `lib/exports/` |
+| Prompt template | `docs/PROMPT_TEMPLATE.md` |
+| Project Knowledge template | `docs/PROJECT_KNOWLEDGE_TEMPLATE.md` |
+| Starter template | `docs/STARTER_TEMPLATE.md` |
+| Prompt de auditoria | `docs/AUDIT_PROMPT.md` |
+| Golden snippets | `docs/design-system/examples.md` |