forlogic-core 2.1.1 → 2.1.3

package/dist/README.md

@@ -0,0 +1,1079 @@
+# 🧱 Guia de Desenvolvimento
+
+> **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.
+
+---
+
+## 📦 Instalação
+
+### Pré-requisitos
+
+A biblioteca `forlogic-core` requer as seguintes **peer dependencies** instaladas no seu projeto:
+
+```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.
+
+### Sincronizar regras e convenções
+
+```bash
+npx lib-update
+```
+
+> Copia apenas `docs/KNOWLEDGE.md` (regras + mapa de módulos) e `.note/memory/rules/`.
+> Documentação de componentes é acessada via rota `/ds` ou cross-project.
+
+### ⚠️ 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`.
+
+---
+
+## 📦 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:
+
+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
+
+### 📋 Checklist OBRIGATÓRIO Antes de Criar Componentes
+
+```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?
+```
+
+### ✅ 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                |
+| `npx lib-update`                  | Sincroniza regras e KNOWLEDGE.md                    |
+
+### ⚠️ 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
+
+> **📋 Schema Padrão**: Veja no **Custom Knowledge** do projeto (Settings → Manage Knowledge) qual é o schema padrão deste projeto específico.
+
+### ⚠️ TOP 4 ERROS MAIS COMUNS
+
+1. **ESQUECER SCHEMA**
+
+```typescript
+// ❌ ERRADO
+.from('table')
+
+// ✅ CORRETO (verifique o schema padrão no Custom Knowledge)
+.schema('SEU_SCHEMA').from('table')
+```
+
+2. **RLS COM SINTAXE INCORRETA**
+
+```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
+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 (...);
+
+-- ✅ CORRETO: Use soft delete com UPDATE
+ALTER TABLE seu_schema.table ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE;
+```
+
+4. **CRIAR ÍNDICES AUTOMATICAMENTE**
+
+```sql
+-- ❌ PROIBIDO criar índices sem aprovação
+CREATE INDEX idx_table_user ON seu_schema.table(id_user);
+
+-- ✅ Apenas quando solicitado explicitamente e aprovado
+```
+
+---
+
+## 📝 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:**
+
+```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
+```
+
+---
+
+## 🚫 ÍNDICES: ABSOLUTAMENTE PROIBIDO CRIAR AUTOMATICAMENTE
+
+### ⚠️ REGRA DE OURO
+
+**NUNCA, EM HIPÓTESE ALGUMA, criar índices automaticamente em migrations!**
+
+### 🤔 Por Quê?
+
+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
+
+### ❌ 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);
+```
+
+### ✅ Quando Criar Índices?
+
+**APENAS** quando:
+
+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
+
+### 📋 Checklist OBRIGATÓRIO Antes de Qualquer Migration
+
+```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)
+```
+
+---
+
+## ⚙️ Configuração Vite e Tailwind (Projetos Consumidores)
+
+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.
+
+### 📦 Imports Disponíveis
+
+```typescript
+// Configurações Vite (headers de segurança, CSP, CORS)
+import { createSecurityHeadersPlugin, createForlogicViteConfig } from 'forlogic-core/vite';
+
+// Preset Tailwind (cores, animações, gradientes)
+import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
+```
+
+---
+
+### 🔒 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
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react-swc';
+import { createSecurityHeadersPlugin } from 'forlogic-core/vite';
+
+export default defineConfig(({ mode }) => ({
+  plugins: [
+    react(),
+    createSecurityHeadersPlugin(mode === 'development', {
+      supabaseUrls: ['https://seu-projeto.supabase.co'],
+    }),
+  ],
+}));
+```
+
+#### Configuração Completa
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react-swc';
+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,
+    }),
+  ],
+}));
+```
+
+#### 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
+
+```typescript
+// tailwind.config.ts
+import type { Config } from 'tailwindcss';
+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
+  ],
+} 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`
+
+```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>
+  );
+}
+
+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`?
+```
+
+---
+
+## 🚀 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
+
+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
+
+---
+
+## 🎯 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} />
+```
+
+### 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>;
+}
+```
+
+### Interface SidebarActionsConfig
+
+```typescript
+interface SidebarActionsConfig {
+  triggerLabel?: string;    // Rótulo do gatilho (padrão: 'Criar')
+  triggerIcon?: LucideIcon; // Ícone do gatilho (padrão: Plus)
+  actions: SidebarModuleAction[];
+}
+```
+
+### Gerenciamento de Modais (Opcional)
+
+Para desabilitar o gatilho quando há modais abertos, use o `ModalStateProvider`:
+
+```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)
+
+## 🛠️ CLI: Sincronizar Regras e Convenções
+
+O `forlogic-core` disponibiliza um comando CLI para sincronizar regras e convenções arquiteturais para projetos consumidores.
+
+### Uso
+
+```bash
+# Via npx (recomendado)
+npx lib-update
+
+# Ou adicione ao package.json do seu projeto:
+{
+  "scripts": {
+    "lib-update": "lib-update"
+  }
+}
+
+# E execute:
+npm run lib-update
+```
+
+### O que é sincronizado
+
+| Arquivo/Diretório       | Descrição                                        |
+| ----------------------- | ------------------------------------------------ |
+| `docs/KNOWLEDGE.md`     | Regras críticas + mapa de módulos para IA/Lovable |
+| `.note/memory/rules/`   | Regras de schema, RLS, índices, .env             |
+
+### O que NÃO é sincronizado (leitura via cross-project → projeto **Admin**)
+
+| Recurso                     | Como acessar                                              |
+| --------------------------- | --------------------------------------------------------- |
+| Documentação de componentes | Rota `/ds` no projeto **Admin** ou cross-project          |
+| Props, exemplos, tipos      | Ler dos `*Doc.tsx` via cross-project → projeto **Admin**  |
+| Padrões de layout/CRUD      | `.note/memory/patterns/` via cross-project → **Admin**    |
+
+> 💡 A IA consegue ler o código-fonte do forlogic-core no projeto **Admin** via cross-project visibility.