forlogic-core 2.2.6 → 2.2.7

package/docs/SUPABASE_SECRETS.md

@@ -1,122 +1,122 @@
-# Supabase Secrets — Inventário
-
-> **Projeto Supabase:** `ccjfvpnndclajkleyqkc`
->
-> Todas as secrets são compartilhadas entre os projetos Lovable que apontam para este mesmo projeto Supabase.
-> Última atualização: 2026-05-04
-
----
-
-## Infraestrutura Supabase (automáticas)
-
-Secrets gerenciadas automaticamente pelo Supabase. **Não editar manualmente.**
-
-| Secret | Finalidade | Projetos |
-|--------|-----------|----------|
-| `SUPABASE_URL` | URL do projeto Supabase | Todos com edge functions |
-| `SUPABASE_SERVICE_ROLE_KEY` | Chave admin — bypass de RLS em edge functions | Todos com edge functions |
-| `SUPABASE_ANON_KEY` | Chave pública anon (usada em `createClient` server-side) | Cockpit, Educação, PDI, Competências, Colaboradores |
-| `SUPABASE_DB_URL` | Connection string PostgreSQL | Infraestrutura interna Supabase |
-
----
-
-## Autenticação e JWT
-
-| Secret | Finalidade | Projetos | Observações |
-|--------|-----------|----------|-------------|
-| `JWT_SECRET` | Verificação de assinatura HMAC-SHA256 dos JWTs customizados | **Admin** (validate-token, azure-blob-upload, clicksign, d4sign, send-email), **Cockpit** (_shared/auth), **Colaboradores** (sensitive-data, entra-id-sync, collaborator-webhook, contract-*), **PDI** (dev-tokens) | Crítica — usada para validar tokens em todas as edge functions protegidas |
-| `VALIDATE_JWT_ENDPOINT` | URL de endpoint externo para validação de JWT (Qualiex API) | **Admin** (validate-token), **Treinamentos** (docs-documents-used, docs-process-outdated, notify-leader) | Fallback quando JWT_SECRET não é usado diretamente |
-| `SUPABASE_PUBLISHABLE_KEY` | Chave pública do projeto (alias da anon key) | **Admin** (validate-token) | Usada para validar tokens de projetos consumidores |
-| `SUPABASE_PUBLISHABLE_KEYS` | Lista de chaves públicas de múltiplos projetos | **Admin** (validate-token) | Suporte multi-projeto na validação |
-| `SUPABASE_SECRET_KEYS` | Lista de chaves secretas de múltiplos projetos | **Admin** (validate-token) | Suporte multi-projeto na validação |
-| `SUPABASE_JWKS` | JSON Web Key Set para validação de tokens | **Admin** (validate-token) | Padrão JWKS para rotação de chaves |
-
----
-
-## Desenvolvimento e Preview
-
-| Secret | Finalidade | Projetos | Observações |
-|--------|-----------|----------|-------------|
-| `DEV_ACCESS_TOKEN` | Token OAuth pré-configurado para ambiente de preview | **Admin**, **Cockpit** (sync-completed, view-pendencias), **Documentos**, **PDI** | Permite autenticação no preview Lovable sem fluxo OAuth |
-| `DEV_ID_TOKEN` | ID token pré-configurado para ambiente de preview | **Admin**, **Cockpit**, **Documentos**, **PDI** | Par do DEV_ACCESS_TOKEN |
-| `DEV_TOKENS_SECRET` | Secret de autenticação da edge function `dev-tokens` | **Admin** | Protege o endpoint que retorna os tokens de dev |
-| `CRON_SECRET` | Header de autenticação do cron job `audit-ship` | **Admin** | Enviado como `x-cron-secret` pelo pg_cron |
-
----
-
-## E-mail (AWS SES)
-
-| Secret | Finalidade | Projetos |
-|--------|-----------|----------|
-| `AWS_ACCESS_KEY_ID` | Credencial IAM para AWS SES | **Admin** (send-email), **Cockpit** (notify-suggestion), **Treinamentos** (docs-process-outdated) |
-| `AWS_SECRET_ACCESS_KEY` | Credencial IAM para AWS SES | **Admin** (send-email), **Cockpit** (notify-suggestion), **Treinamentos** (docs-process-outdated) |
-| `AWS_SES_REGION` | Região do SES (default: `us-east-1`) | **Admin**, **Cockpit**, **Treinamentos** |
-| `AWS_SES_FROM_EMAIL` | Endereço de e-mail remetente | **Admin**, **Cockpit**, **Treinamentos** |
-| `AWS_SES_FROM_NAME` | Nome exibido como remetente | **Admin**, **Cockpit**, **Treinamentos** |
-| `SUGGESTION_NOTIFY_EMAIL` | E-mail destino para notificações de sugestões do Cockpit | **Cockpit** (notify-suggestion) |
-
----
-
-## Azure
-
-| Secret | Finalidade | Projetos | Observações |
-|--------|-----------|----------|-------------|
-| `AZURE_BLOB_ACCOUNT_URL` | URL da conta Azure Blob Storage | **Admin** (azure-blob-upload) | Upload de arquivos para Azure |
-| `AZURE_BLOB_ACCOUNT_KEY` | SharedKey da conta Azure Blob | **Admin** (azure-blob-upload) | Método preferido de autenticação |
-| `AZURE_BLOB_SAS_TOKEN` | SAS Token para Azure Blob | **Admin** (azure-blob-upload) | ⚠️ **Deprecated** — fallback do `AZURE_BLOB_ACCOUNT_KEY` |
-| `AZURE_TENANT_ID` | Tenant ID do Azure AD (Entra ID) | **Colaboradores** (entra-id-sync) | Sincronização de usuários via Microsoft Graph |
-| `AZURE_CLIENT_ID` | Client ID do app Azure AD | **Colaboradores** (entra-id-sync) | Par do AZURE_TENANT_ID |
-
-> **Nota:** Existia uma secret `AZURE_CLIENT_SECRET` que era recriada indevidamente. Nenhum projeto no workspace a referencia no código — a origem da recriação não foi identificada.
-
----
-
-## Integrações de IA
-
-| Secret | Finalidade | Projetos |
-|--------|-----------|----------|
-| `OPENAI_API_KEY` | Chave da API OpenAI (GPT) | **Educação** (generate-block-content, generate-course-structure, process-document, extract-certificate-data, generate-quiz-from-document), **Desempenho** (generate-questions-ai, performance-generate-*), **PDI** (generate-pdi-actions, generate-strategic-plan), **Competências** (generate-questions-ai), **Pulso** (analyze-comments, analyze-survey-data, generate-action-plan, refine-action-plan, analyze-custom-survey, generate-survey-action-plan), **Treinamentos** (generate-quiz-from-document, suggest-evaluation-criteria, validate-certificate) |
-| `OPENROUTER_API_KEY` | Chave do OpenRouter (modelo: `google/gemini-2.5-flash`) | **Matriz de Foco** (generic-app-scan, manager-chat, outlook-calendar, redundancy-hunter, smart-assistant) |
-| `LOVABLE_API_KEY` | Chave da API Lovable (AI Gateway) | **Educação** (generate-questions-ai) |
-
----
-
-## Integrações Externas
-
-| Secret | Finalidade | Projetos | Observações |
-|--------|-----------|----------|-------------|
-| `CLICKSIGN_SANDBOX_API_KEY` | API Key do Clicksign (ambiente sandbox) | **Admin** (clicksign) | Assinatura eletrônica de documentos |
-| `ELASTIC_URL` | URL do cluster Elasticsearch | **Admin** (audit-ship) | Destino dos logs de auditoria |
-| `ELASTIC_API_KEY` | API Key do Elasticsearch | **Admin** (audit-ship) | Autenticação no cluster |
-| `HUBSPOT_PRIVATE_APP_TOKEN` | Token de app privado do HubSpot | **Cockpit** (hubspot-tickets) | No código é lido como `HUBSPOT_ACCESS_TOKEN` via `Deno.env.get()` |
-| `SENSITIVE_DATA_KEY` | Chave AES-GCM para criptografia de dados sensíveis (CPF, etc.) | **Colaboradores** (sensitive-data, api-export-sensitive-data, entra-id-sync), **Matriz de Foco** (generic-app-scan, generic-app-secrets, migrate-legacy-tokens) | Chave hex de 256 bits |
-| `VITE_QUALIEX_API_URL` | URL da API Qualiex | **Admin** (validate-token), **Cockpit** (_shared/auth), **Treinamentos** (docs-process-outdated, notify-leader) | Configuração de ambiente (prod vs dev) |
-
----
-
-## Secrets sem Referência no Código
-
-| Secret | Status | Recomendação |
-|--------|--------|-------------|
-| `VITE_BUILDER_API_KEY` | Nenhuma edge function ou código frontend referencia esta secret | ⚠️ Candidata a remoção — verificar se algum serviço externo a utiliza antes de deletar |
-
----
-
-## Secrets Específicas de Projetos (não listadas acima)
-
-Estas secrets são usadas apenas por projetos específicos mas vivem no mesmo projeto Supabase:
-
-| Secret (no código) | Projeto | Finalidade |
-|---------------------|---------|-----------|
-| `TRAININGS_SERVICE_API_KEY` | **Treinamentos** | Auth service-to-service entre edge functions |
-| `HUBSPOT_ACCESS_TOKEN` | **Cockpit** | Mesmo valor de `HUBSPOT_PRIVATE_APP_TOKEN` (nome diferente no `Deno.env.get`) |
-
-> **Nota:** Estas secrets podem não estar na lista do dashboard se foram adicionadas diretamente ou por outro projeto. Verifique no [painel de secrets](https://supabase.com/dashboard/project/ccjfvpnndclajkleyqkc/settings/functions).
-
----
-
-## Referências
-
-- [Painel de Secrets do Supabase](https://supabase.com/dashboard/project/ccjfvpnndclajkleyqkc/settings/functions)
-- [Plano de Segurança (Fase 2)](./../.lovable/plan.md)
-- [Inventário de Storage Buckets](./STORAGE_BUCKETS.md)
+# Supabase Secrets — Inventário
+
+> **Projeto Supabase:** `ccjfvpnndclajkleyqkc`
+>
+> Todas as secrets são compartilhadas entre os projetos Lovable que apontam para este mesmo projeto Supabase.
+> Última atualização: 2026-05-04
+
+---
+
+## Infraestrutura Supabase (automáticas)
+
+Secrets gerenciadas automaticamente pelo Supabase. **Não editar manualmente.**
+
+| Secret | Finalidade | Projetos |
+|--------|-----------|----------|
+| `SUPABASE_URL` | URL do projeto Supabase | Todos com edge functions |
+| `SUPABASE_SERVICE_ROLE_KEY` | Chave admin — bypass de RLS em edge functions | Todos com edge functions |
+| `SUPABASE_ANON_KEY` | Chave pública anon (usada em `createClient` server-side) | Cockpit, Educação, PDI, Competências, Colaboradores |
+| `SUPABASE_DB_URL` | Connection string PostgreSQL | Infraestrutura interna Supabase |
+
+---
+
+## Autenticação e JWT
+
+| Secret | Finalidade | Projetos | Observações |
+|--------|-----------|----------|-------------|
+| `JWT_SECRET` | Verificação de assinatura HMAC-SHA256 dos JWTs customizados | **Admin** (validate-token, azure-blob-upload, clicksign, d4sign, send-email), **Cockpit** (_shared/auth), **Colaboradores** (sensitive-data, entra-id-sync, collaborator-webhook, contract-*), **PDI** (dev-tokens) | Crítica — usada para validar tokens em todas as edge functions protegidas |
+| `VALIDATE_JWT_ENDPOINT` | URL de endpoint externo para validação de JWT (Qualiex API) | **Admin** (validate-token), **Treinamentos** (docs-documents-used, docs-process-outdated, notify-leader) | Fallback quando JWT_SECRET não é usado diretamente |
+| `SUPABASE_PUBLISHABLE_KEY` | Chave pública do projeto (alias da anon key) | **Admin** (validate-token) | Usada para validar tokens de projetos consumidores |
+| `SUPABASE_PUBLISHABLE_KEYS` | Lista de chaves públicas de múltiplos projetos | **Admin** (validate-token) | Suporte multi-projeto na validação |
+| `SUPABASE_SECRET_KEYS` | Lista de chaves secretas de múltiplos projetos | **Admin** (validate-token) | Suporte multi-projeto na validação |
+| `SUPABASE_JWKS` | JSON Web Key Set para validação de tokens | **Admin** (validate-token) | Padrão JWKS para rotação de chaves |
+
+---
+
+## Desenvolvimento e Preview
+
+| Secret | Finalidade | Projetos | Observações |
+|--------|-----------|----------|-------------|
+| `DEV_ACCESS_TOKEN` | Token OAuth pré-configurado para ambiente de preview | **Admin**, **Cockpit** (sync-completed, view-pendencias), **Documentos**, **PDI** | Permite autenticação no preview Lovable sem fluxo OAuth |
+| `DEV_ID_TOKEN` | ID token pré-configurado para ambiente de preview | **Admin**, **Cockpit**, **Documentos**, **PDI** | Par do DEV_ACCESS_TOKEN |
+| `DEV_TOKENS_SECRET` | Secret de autenticação da edge function `dev-tokens` | **Admin** | Protege o endpoint que retorna os tokens de dev |
+| `CRON_SECRET` | Header de autenticação do cron job `audit-ship` | **Admin** | Enviado como `x-cron-secret` pelo pg_cron |
+
+---
+
+## E-mail (AWS SES)
+
+| Secret | Finalidade | Projetos |
+|--------|-----------|----------|
+| `AWS_ACCESS_KEY_ID` | Credencial IAM para AWS SES | **Admin** (send-email), **Cockpit** (notify-suggestion), **Treinamentos** (docs-process-outdated) |
+| `AWS_SECRET_ACCESS_KEY` | Credencial IAM para AWS SES | **Admin** (send-email), **Cockpit** (notify-suggestion), **Treinamentos** (docs-process-outdated) |
+| `AWS_SES_REGION` | Região do SES (default: `us-east-1`) | **Admin**, **Cockpit**, **Treinamentos** |
+| `AWS_SES_FROM_EMAIL` | Endereço de e-mail remetente | **Admin**, **Cockpit**, **Treinamentos** |
+| `AWS_SES_FROM_NAME` | Nome exibido como remetente | **Admin**, **Cockpit**, **Treinamentos** |
+| `SUGGESTION_NOTIFY_EMAIL` | E-mail destino para notificações de sugestões do Cockpit | **Cockpit** (notify-suggestion) |
+
+---
+
+## Azure
+
+| Secret | Finalidade | Projetos | Observações |
+|--------|-----------|----------|-------------|
+| `AZURE_BLOB_ACCOUNT_URL` | URL da conta Azure Blob Storage | **Admin** (azure-blob-upload) | Upload de arquivos para Azure |
+| `AZURE_BLOB_ACCOUNT_KEY` | SharedKey da conta Azure Blob | **Admin** (azure-blob-upload) | Método preferido de autenticação |
+| `AZURE_BLOB_SAS_TOKEN` | SAS Token para Azure Blob | **Admin** (azure-blob-upload) | ⚠️ **Deprecated** — fallback do `AZURE_BLOB_ACCOUNT_KEY` |
+| `AZURE_TENANT_ID` | Tenant ID do Azure AD (Entra ID) | **Colaboradores** (entra-id-sync) | Sincronização de usuários via Microsoft Graph |
+| `AZURE_CLIENT_ID` | Client ID do app Azure AD | **Colaboradores** (entra-id-sync) | Par do AZURE_TENANT_ID |
+
+> **Nota:** Existia uma secret `AZURE_CLIENT_SECRET` que era recriada indevidamente. Nenhum projeto no workspace a referencia no código — a origem da recriação não foi identificada.
+
+---
+
+## Integrações de IA
+
+| Secret | Finalidade | Projetos |
+|--------|-----------|----------|
+| `OPENAI_API_KEY` | Chave da API OpenAI (GPT) | **Educação** (generate-block-content, generate-course-structure, process-document, extract-certificate-data, generate-quiz-from-document), **Desempenho** (generate-questions-ai, performance-generate-*), **PDI** (generate-pdi-actions, generate-strategic-plan), **Competências** (generate-questions-ai), **Pulso** (analyze-comments, analyze-survey-data, generate-action-plan, refine-action-plan, analyze-custom-survey, generate-survey-action-plan), **Treinamentos** (generate-quiz-from-document, suggest-evaluation-criteria, validate-certificate) |
+| `OPENROUTER_API_KEY` | Chave do OpenRouter (modelo: `google/gemini-2.5-flash`) | **Matriz de Foco** (generic-app-scan, manager-chat, outlook-calendar, redundancy-hunter, smart-assistant) |
+| `LOVABLE_API_KEY` | Chave da API Lovable (AI Gateway) | **Educação** (generate-questions-ai) |
+
+---
+
+## Integrações Externas
+
+| Secret | Finalidade | Projetos | Observações |
+|--------|-----------|----------|-------------|
+| `CLICKSIGN_SANDBOX_API_KEY` | API Key do Clicksign (ambiente sandbox) | **Admin** (clicksign) | Assinatura eletrônica de documentos |
+| `ELASTIC_URL` | URL do cluster Elasticsearch | **Admin** (audit-ship) | Destino dos logs de auditoria |
+| `ELASTIC_API_KEY` | API Key do Elasticsearch | **Admin** (audit-ship) | Autenticação no cluster |
+| `HUBSPOT_PRIVATE_APP_TOKEN` | Token de app privado do HubSpot | **Cockpit** (hubspot-tickets) | No código é lido como `HUBSPOT_ACCESS_TOKEN` via `Deno.env.get()` |
+| `SENSITIVE_DATA_KEY` | Chave AES-GCM para criptografia de dados sensíveis (CPF, etc.) | **Colaboradores** (sensitive-data, api-export-sensitive-data, entra-id-sync), **Matriz de Foco** (generic-app-scan, generic-app-secrets, migrate-legacy-tokens) | Chave hex de 256 bits |
+| `VITE_QUALIEX_API_URL` | URL da API Qualiex | **Admin** (validate-token), **Cockpit** (_shared/auth), **Treinamentos** (docs-process-outdated, notify-leader) | Configuração de ambiente (prod vs dev) |
+
+---
+
+## Secrets sem Referência no Código
+
+| Secret | Status | Recomendação |
+|--------|--------|-------------|
+| `VITE_BUILDER_API_KEY` | Nenhuma edge function ou código frontend referencia esta secret | ⚠️ Candidata a remoção — verificar se algum serviço externo a utiliza antes de deletar |
+
+---
+
+## Secrets Específicas de Projetos (não listadas acima)
+
+Estas secrets são usadas apenas por projetos específicos mas vivem no mesmo projeto Supabase:
+
+| Secret (no código) | Projeto | Finalidade |
+|---------------------|---------|-----------|
+| `TRAININGS_SERVICE_API_KEY` | **Treinamentos** | Auth service-to-service entre edge functions |
+| `HUBSPOT_ACCESS_TOKEN` | **Cockpit** | Mesmo valor de `HUBSPOT_PRIVATE_APP_TOKEN` (nome diferente no `Deno.env.get`) |
+
+> **Nota:** Estas secrets podem não estar na lista do dashboard se foram adicionadas diretamente ou por outro projeto. Verifique no [painel de secrets](https://supabase.com/dashboard/project/ccjfvpnndclajkleyqkc/settings/functions).
+
+---
+
+## Referências
+
+- [Painel de Secrets do Supabase](https://supabase.com/dashboard/project/ccjfvpnndclajkleyqkc/settings/functions)
+- [Plano de Segurança (Fase 2)](./../.lovable/plan.md)
+- [Inventário de Storage Buckets](./STORAGE_BUCKETS.md)

package/docs/WORKSPACE_KNOWLEDGE.md

@@ -1,154 +1,154 @@
-# forlogic-core — Workspace Knowledge
-
-> **Documento para colar no Lovable Workspace Knowledge** de projetos consumidores.
-> Funciona como mapa de referências cruzadas entre os projetos.
-
----
-
-## Projetos do Ecossistema
-
-| Projeto | Alias | Responsabilidade |
-|---------|-------|-----------------|
-| **forlogic-docs** | `@forlogic-docs` | Fonte canônica de regras, padrões, templates e documentação |
-| **qualiex-admin** | `@Admin` | Código-fonte da lib `forlogic-core`, Design System e docs gerados |
-
----
-
-## Onde buscar cada informação
-
-### Regras e Padrões → `@forlogic-docs`
-
-| O que | Caminho |
-|-------|---------|
-| Constituição (regras canônicas) | `docs/engenharia/padroes/constitution.md` |
-| Guia de migração de ícones | `docs/engenharia/padroes/icon-migration.md` |
-| Guia de publicação da lib | `docs/engenharia/devops/publish.md` |
-| Prompt: auditoria | `docs/templates/prompts/audit.md` |
-| Prompt: criação de tela | `docs/templates/prompts/new-screen.md` |
-| Prompt: starter template | `docs/templates/prompts/starter.md` |
-| ADRs (decisões de arquitetura) | `docs/adrs/` |
-| Specs de API | `docs/apis/` |
-
-### Código-fonte e Design System → `@Admin`
-
-| O que | Caminho |
-|-------|---------|
-| Código 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/` |
-| Golden snippets (exemplos) | `docs/design-system/examples.md` |
-| 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/` |
-| Spec do módulo Queries | `spec/queries.md` |
-| Inventário de Supabase Storage | `docs/STORAGE_BUCKETS.md` |
-
----
-
-## Schema do Projeto
-
-> ⚠️ **O schema é definido no `README.md` de cada projeto consumidor.** Consulte-o antes de qualquer query.
-
-```ts
-// ✅ CORRETO — substituir pelo schema do projeto
-supabase.schema('SCHEMA_DO_PROJETO').from('tabela').select('*');
-
-// ❌ ERRADO
-supabase.from('tabela').select('*');
-```
-
----
-
-## Regras Invioláveis (resumo)
-
-> Fonte canônica: `@forlogic-docs docs/engenharia/padroes/constitution.md`
-
-| Regra | Detalhe |
-|-------|---------|
-| Schema obrigatório | `.schema('...')` em toda query Supabase |
-| Sem DELETE físico | Soft delete com `deleted_at` |
-| **Sem acesso anon** | RLS policies devem usar `TO authenticated` — **nunca** conceder acesso ao role `anon` sem justificativa documentada |
-| Lib-first | Usar `forlogic-core` antes de criar componente |
-| Import do Supabase | `getSupabaseClient()` de `forlogic-core` |
-| Import de i18n | `useTranslation` de `forlogic-core`, nunca de `react-i18next` |
-| Sem hardcoded admin | Nunca localStorage/sessionStorage para roles |
-| **PK Override** | `VITE_SUPABASE_PK_OVERRIDE` **obrigatória** no `.env` — nunca remover. Ver `@Admin docs/design-system/patterns/feature-flags.md` |
-
-### Política de acesso `anon` no Supabase
-
-**Por padrão, nenhuma tabela, function ou storage policy deve conceder acesso ao role `anon`.**
-
-Todas as policies devem usar `TO authenticated` e validar o JWT do tenant:
-
-```sql
--- ✅ CORRETO
-CREATE POLICY "select" ON schema.tabela
-FOR SELECT TO authenticated
-USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
-
--- ❌ ERRADO — nunca usar anon
-CREATE POLICY "select" ON schema.tabela
-FOR SELECT TO anon, authenticated
-USING (true);
-```
-
-**Exceções são permitidas apenas quando:**
-
-1. A funcionalidade é **intencionalmente pública** (ex: validação de certificado, página de candidatura externa)
-2. A exceção está **documentada na migration SQL** com comentário `-- ANON: <motivo>`
-3. A exceção está **registrada no `@security-memory`** do projeto
-
-**Funções `SECURITY DEFINER`:** por padrão, revogar permissão de `anon`:
-
-```sql
-REVOKE EXECUTE ON FUNCTION schema.minha_funcao FROM anon;
--- Manter apenas authenticated
-GRANT EXECUTE ON FUNCTION schema.minha_funcao TO authenticated;
-```
-
----
-
-## 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` |
-| Navegação | `navigation.md` |
-| Dialogs | `dialogs.md` |
-| Layout | `layout.md` |
-| CRUD | `crud.md` |
-
-### Aliases
-
-| Original | Alias(es) |
-|----------|-----------|
-| Combobox | SelectSearch, MultiSelect, EntitySelect |
-| ComboTree | TreeSelect |
-| ActionButton | ActionMenu, RowActions |
-| CrudPrimitiveTable | DataTable |
-
----
-
-## Instrução para IA — Leitura Obrigatória
-
-**QUANDO** criar ou modificar qualquer arquivo `.tsx`:
-
-- **SE** contém tabela/CRUD → **LER** `@Admin docs/design-system/crud.md` ANTES
-- **SE** contém formulário → **LER** `@Admin docs/design-system/inputs.md` ANTES
-- **SE** contém modal → **LER** `@Admin docs/design-system/dialogs.md` ANTES
-- **SE** contém botões/ações → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
-- **SE** é layout → **LER** `@Admin docs/design-system/layout.md` ANTES
-
-**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência.
-
-**VALIDAÇÃO**: Todo import de componente visual DEVE vir de `forlogic-core`.
+# forlogic-core — Workspace Knowledge
+
+> **Documento para colar no Lovable Workspace Knowledge** de projetos consumidores.
+> Funciona como mapa de referências cruzadas entre os projetos.
+
+---
+
+## Projetos do Ecossistema
+
+| Projeto | Alias | Responsabilidade |
+|---------|-------|-----------------|
+| **forlogic-docs** | `@forlogic-docs` | Fonte canônica de regras, padrões, templates e documentação |
+| **qualiex-admin** | `@Admin` | Código-fonte da lib `forlogic-core`, Design System e docs gerados |
+
+---
+
+## Onde buscar cada informação
+
+### Regras e Padrões → `@forlogic-docs`
+
+| O que | Caminho |
+|-------|---------|
+| Constituição (regras canônicas) | `docs/engenharia/padroes/constitution.md` |
+| Guia de migração de ícones | `docs/engenharia/padroes/icon-migration.md` |
+| Guia de publicação da lib | `docs/engenharia/devops/publish.md` |
+| Prompt: auditoria | `docs/templates/prompts/audit.md` |
+| Prompt: criação de tela | `docs/templates/prompts/new-screen.md` |
+| Prompt: starter template | `docs/templates/prompts/starter.md` |
+| ADRs (decisões de arquitetura) | `docs/adrs/` |
+| Specs de API | `docs/apis/` |
+
+### Código-fonte e Design System → `@Admin`
+
+| O que | Caminho |
+|-------|---------|
+| Código 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/` |
+| Golden snippets (exemplos) | `docs/design-system/examples.md` |
+| 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/` |
+| Spec do módulo Queries | `spec/queries.md` |
+| Inventário de Supabase Storage | `docs/STORAGE_BUCKETS.md` |
+
+---
+
+## Schema do Projeto
+
+> ⚠️ **O schema é definido no `README.md` de cada projeto consumidor.** Consulte-o antes de qualquer query.
+
+```ts
+// ✅ CORRETO — substituir pelo schema do projeto
+supabase.schema('SCHEMA_DO_PROJETO').from('tabela').select('*');
+
+// ❌ ERRADO
+supabase.from('tabela').select('*');
+```
+
+---
+
+## Regras Invioláveis (resumo)
+
+> Fonte canônica: `@forlogic-docs docs/engenharia/padroes/constitution.md`
+
+| Regra | Detalhe |
+|-------|---------|
+| Schema obrigatório | `.schema('...')` em toda query Supabase |
+| Sem DELETE físico | Soft delete com `deleted_at` |
+| **Sem acesso anon** | RLS policies devem usar `TO authenticated` — **nunca** conceder acesso ao role `anon` sem justificativa documentada |
+| Lib-first | Usar `forlogic-core` antes de criar componente |
+| Import do Supabase | `getSupabaseClient()` de `forlogic-core` |
+| Import de i18n | `useTranslation` de `forlogic-core`, nunca de `react-i18next` |
+| Sem hardcoded admin | Nunca localStorage/sessionStorage para roles |
+| **PK Override** | `VITE_SUPABASE_PK_OVERRIDE` **obrigatória** no `.env` — nunca remover. Ver `@Admin docs/design-system/patterns/feature-flags.md` |
+
+### Política de acesso `anon` no Supabase
+
+**Por padrão, nenhuma tabela, function ou storage policy deve conceder acesso ao role `anon`.**
+
+Todas as policies devem usar `TO authenticated` e validar o JWT do tenant:
+
+```sql
+-- ✅ CORRETO
+CREATE POLICY "select" ON schema.tabela
+FOR SELECT TO authenticated
+USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
+
+-- ❌ ERRADO — nunca usar anon
+CREATE POLICY "select" ON schema.tabela
+FOR SELECT TO anon, authenticated
+USING (true);
+```
+
+**Exceções são permitidas apenas quando:**
+
+1. A funcionalidade é **intencionalmente pública** (ex: validação de certificado, página de candidatura externa)
+2. A exceção está **documentada na migration SQL** com comentário `-- ANON: <motivo>`
+3. A exceção está **registrada no `@security-memory`** do projeto
+
+**Funções `SECURITY DEFINER`:** por padrão, revogar permissão de `anon`:
+
+```sql
+REVOKE EXECUTE ON FUNCTION schema.minha_funcao FROM anon;
+-- Manter apenas authenticated
+GRANT EXECUTE ON FUNCTION schema.minha_funcao TO authenticated;
+```
+
+---
+
+## 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` |
+| Navegação | `navigation.md` |
+| Dialogs | `dialogs.md` |
+| Layout | `layout.md` |
+| CRUD | `crud.md` |
+
+### Aliases
+
+| Original | Alias(es) |
+|----------|-----------|
+| Combobox | SelectSearch, MultiSelect, EntitySelect |
+| ComboTree | TreeSelect |
+| ActionButton | ActionMenu, RowActions |
+| CrudPrimitiveTable | DataTable |
+
+---
+
+## Instrução para IA — Leitura Obrigatória
+
+**QUANDO** criar ou modificar qualquer arquivo `.tsx`:
+
+- **SE** contém tabela/CRUD → **LER** `@Admin docs/design-system/crud.md` ANTES
+- **SE** contém formulário → **LER** `@Admin docs/design-system/inputs.md` ANTES
+- **SE** contém modal → **LER** `@Admin docs/design-system/dialogs.md` ANTES
+- **SE** contém botões/ações → **LER** `@Admin docs/design-system/buttons-actions.md` ANTES
+- **SE** é layout → **LER** `@Admin docs/design-system/layout.md` ANTES
+
+**SEMPRE** consultar `@Admin docs/design-system/examples.md` como referência.
+
+**VALIDAÇÃO**: Todo import de componente visual DEVE vir de `forlogic-core`.