forlogic-core 3.0.0 → 3.0.2

package/docs/design-system/patterns/core-providers.md

@@ -1,258 +1,258 @@
-# Padrão: CoreProviders Setup
-
-## Providers incluídos
-
-| Provider | Descrição |
-|----------|-----------|
-| ErrorBoundary | Captura erros de renderização React |
-| I18nextProvider | Sistema de internacionalização |
-| QueryClientProvider | Cache e queries (React Query) |
-| AuthProvider | Autenticação e sessão |
-| LocaleProvider | Idioma, timezone, formato de data |
-| ModuleProvider | Configuração de módulo ativo |
-| ModuleAccessGuard | Bloqueio de acesso por módulo |
-
-## Uso básico
-
-```tsx
-<CoreProviders moduleAlias="performance" appTranslations={{ 'pt-BR': ptBR }}>
-  <BrowserRouter>
-    <Routes />
-  </BrowserRouter>
-</CoreProviders>
-```
-
-## Props
-
-| Prop | Tipo | Obrigatório | Descrição |
-|------|------|-------------|-----------|
-| children | ReactNode | Sim | Componentes filhos |
-| queryClient | QueryClient | Não | Instância customizada (default criado automaticamente) |
-| moduleAlias | string | Não | Alias do módulo para verificação de acesso |
-| moduleApiUrl | string | Não | (DEPRECATED — substituído por `associationsBaseUrl`) |
-| associationsBaseUrl | string | Não | Base URL completa para `/Users/{userId}/associations`. Ver seção abaixo. |
-| moduleAccessGuardProps | object | Não | Props para o ModuleAccessGuard |
-| appTranslations | Record<string, Record<string, string>> | Não | Traduções por idioma no namespace 'app' |
-| clarityProjectId | string | Não | Project ID do Microsoft Clarity. Sem ele, integração desativada. |
-| clarityMode | 'auto' \| 'disabled' | Não | Opt-out do tracking Clarity. Default `'auto'`. |
-| backend | 'supabase' \| 'dotnet' | Não | Backend ativo. Default `'supabase'`. Ver seção abaixo. |
-| signDocumentsSchema | string | Não | Schema onde a tabela de tracking do D4Sign vive neste projeto. Default `'common'`. Ver seção abaixo. |
-| signDocumentsTable | string | Não | Nome da tabela de tracking. Default `'sign_documents'`. |
-
-## Tabela `sign_documents` por schema (D4Sign)
-
-Por padrão, o webhook D4Sign grava o resultado em `common.sign_documents`. Projetos que mantêm a tabela no próprio schema (ex.: Educação) podem redirecionar via:
-
-```tsx
-<CoreProviders
-  moduleAlias="educacao"
-  signDocumentsSchema="educacao"
-  // signDocumentsTable opcional — default 'sign_documents'
->
-  ...
-</CoreProviders>
-```
-
-O que acontece:
-
-1. `DocumentSigner` envia `target_schema` e `target_table` para a edge function `d4sign` no `create_and_send`.
-2. A edge function `d4sign` insere a linha `pending` no schema/tabela alvo e registra o webhook do D4Sign com a URL `/functions/v1/d4sign-webhook?schema={schema}&table={table}`.
-3. A edge function `d4sign-webhook` lê os query params, valida contra uma **allowlist** de schemas (`common`, `educacao`, `treinamentos`, `inovacao`, `public`) e faz o `UPDATE` no schema correto.
-4. O front se inscreve no Realtime no mesmo schema/tabela.
-
-**Requisitos no projeto consumidor:**
-
-Cada projeto que redirecionar o destino precisa criar a tabela no seu próprio schema com **exatamente** o contrato abaixo — os nomes e tipos das colunas são consumidos pelas edge functions `d4sign` e `d4sign-webhook` e pelo `DocumentSigner`. Divergir quebra o fluxo.
-
-### Contrato de campos
-
-| Campo | Tipo | Obrigatório | Default | Preenchido por |
-|---|---|---|---|---|
-| `document_id` | `text` PK | sim | — | front (`DocumentSigner`, `crypto.randomUUID()`) |
-| `alias` | `text` | sim | — | front |
-| `provider` | `text` | sim | `'d4sign'` | front |
-| `envelope_id` | `text` | sim | — | edge `d4sign` (UUID retornado pelo D4Sign) |
-| `signer_email` | `text` | sim | — | front |
-| `signer_name` | `text` | não | — | front |
-| `filename` | `text` | não | — | front |
-| `status` | `text` | sim | `'pending'` | webhook (`pending` → `signed` / `cancelled` / `failed`) |
-| `signed_at` | `timestamptz` | não | — | webhook |
-| `download_url` | `text` | não | — | webhook |
-| `download_url_expires_at` | `timestamptz` | não | — | webhook (~50 min) |
-| `raw_webhook_payload` | `jsonb` | não | — | webhook |
-| `created_at` | `timestamptz` | sim | `now()` | DB |
-| `updated_at` | `timestamptz` | sim | `now()` | trigger |
-
-> **PK em `document_id`** (não `id` serial) — é a chave que o front usa para correlacionar o envelope com a row.
-
-### Script SQL (substituir `{schema}`)
-
-```sql
-CREATE TABLE {schema}.sign_documents (
-  document_id text PRIMARY KEY,
-  alias text NOT NULL,
-  provider text NOT NULL DEFAULT 'd4sign',
-  envelope_id text NOT NULL,
-  signer_email text NOT NULL,
-  signer_name text,
-  filename text,
-  status text NOT NULL DEFAULT 'pending',
-  download_url text,
-  download_url_expires_at timestamptz,
-  raw_webhook_payload jsonb,
-  signed_at timestamptz,
-  created_at timestamptz NOT NULL DEFAULT now(),
-  updated_at timestamptz NOT NULL DEFAULT now()
-);
-
-CREATE INDEX sign_documents_alias_status_idx ON {schema}.sign_documents (alias, status);
-CREATE INDEX sign_documents_envelope_idx     ON {schema}.sign_documents (envelope_id);
-
-GRANT SELECT ON {schema}.sign_documents TO authenticated;
-GRANT ALL    ON {schema}.sign_documents TO service_role;
-
-ALTER TABLE {schema}.sign_documents ENABLE ROW LEVEL SECURITY;
-
-CREATE POLICY "sign_documents_select_own_tenant"
-  ON {schema}.sign_documents
-  FOR SELECT
-  TO authenticated
-  USING (alias = ((SELECT auth.jwt()) ->> 'alias'));
-
-CREATE OR REPLACE FUNCTION {schema}.sign_documents_set_updated_at()
-RETURNS TRIGGER LANGUAGE plpgsql SET search_path = {schema}, public AS $$
-BEGIN NEW.updated_at = now(); RETURN NEW; END;
-$$;
-
-CREATE TRIGGER sign_documents_updated_at
-  BEFORE UPDATE ON {schema}.sign_documents
-  FOR EACH ROW EXECUTE FUNCTION {schema}.sign_documents_set_updated_at();
-
--- Realtime — obrigatório, senão o DocumentSigner nunca recebe o evento de assinatura
-ALTER TABLE {schema}.sign_documents REPLICA IDENTITY FULL;
-ALTER PUBLICATION supabase_realtime ADD TABLE {schema}.sign_documents;
-```
-
-### Notas importantes
-
-- **`sign_configs` continua em `common`** — o webhook lê de lá independentemente do schema alvo. Cada projeto que usa assinatura precisa ter `common.sign_configs` populado (via `/a/cs` no Admin).
-- **`REPLICA IDENTITY FULL` + entrada na publication `supabase_realtime`** são obrigatórios. Sem isso, o `DocumentSigner` fica em loading eterno após assinar.
-- **Schemas novos** precisam ser adicionados à constante `ALLOWED_SCHEMAS` em `supabase/functions/d4sign/index.ts` **e** `supabase/functions/d4sign-webhook/index.ts`, senão o webhook silenciosamente cai para `common` (proteção anti-SSRF).
-
-**Retrocompatibilidade:** sem essas props, tudo continua apontando para `common.sign_documents` — Admin segue funcionando inalterado.
-
-
-## Associações em outra base URL
-
-Por padrão, `useModuleAccess` (e o `ModuleAccessGuard`) busca as associações em:
-
-```
-{QUALIEX_API_URL}/api/common/v1/Users/{userId}/associations
-```
-
-Quando o módulo expõe seu próprio endpoint de associações, informe `associationsBaseUrl` no `CoreProviders`. A lib passa a chamar:
-
-```
-{associationsBaseUrl}/Users/{userId}/associations
-```
-
-`associationsBaseUrl` deve incluir todo o prefixo (host + `/api/{modulo}/v1`):
-
-```tsx
-<CoreProviders
-  backend="dotnet"
-  associationsBaseUrl={import.meta.env.VITE_ASSOCIATIONS_API_URL}
-  // ex: "https://api.qualiex.com/api/inovacao/v1"
->
-  ...
-</CoreProviders>
-```
-
-Características:
-
-- **Uma única variável** — não exige `moduleAlias`. Pode ser usada sem ativar o `ModuleAccessGuard` (útil enquanto o software do módulo ainda não foi cadastrado no `SOFTWARES_MAP` da lib).
-- A API alvo deve responder no mesmo contrato (`UserAssociation[]`) e aceitar os headers `Authorization: Bearer <token>` e `un-alias: <alias>`.
-- Demais endpoints (`/companiesusers`, `/softwares`) continuam consultando a common.
-
-
-## Backend (Supabase opcional)
-
-A prop `backend` controla se a lib usa o stack Supabase ou apenas a API .NET do Qualiex.
-
-- `'supabase'` (default, retrocompat): inicializa o cliente Supabase, valida tokens via Edge Function `validate-token` e exige `SUPABASE_URL` + `SUPABASE_PUBLISHABLE_KEY` (ou as versões `VITE_SUPABASE_*` legadas) no `.env`. O `vite.config.ts` consolida ambos os formatos via `resolveSupabaseEnv()` — ver `docs/design-system/patterns/feature-flags.md`.
-- `'dotnet'`: a lib **não** chama Supabase em nenhum momento da inicialização. O `AuthProvider` autentica apenas com os tokens OAuth do Qualiex (`access_token` + `id_token`). Não exige envs do Supabase. **Importante:** defina `VITE_APP_ENV="DEV"` no `.env` quando o app rodar contra o ambiente dev do Qualiex — sem essa variável, o failsafe assume `PROD`.
-
-### Exemplos de uso por backend
-
-```tsx
-// ============================================================
-// Módulo COM Supabase (default — não precisa declarar backend)
-// ============================================================
-// .env obrigatório:
-//   SUPABASE_URL="https://<project>.supabase.co"
-//   SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."
-//   VITE_SUPABASE_PK_OVERRIDE="sb_publishable_..."
-//
-import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter } from 'react-router';
-import pt from '@/locales/pt-BR.json';
-
-<CoreProviders moduleAlias="performance" appTranslations={{ 'pt-BR': pt }}>
-  <BrowserRouter>
-    <Routes />
-  </BrowserRouter>
-</CoreProviders>
-```
-
-```tsx
-// ============================================================
-// Módulo SEM Supabase (ex.: Documentos, APIs próprias)
-// ============================================================
-// .env obrigatório:
-//   VITE_APP_ENV="DEV"   // ou "PROD"
-//
-// Nenhuma env do Supabase é exigida.
-//
-import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter } from 'react-router';
-import pt from '@/locales/pt-BR.json';
-
-<CoreProviders
-  backend="dotnet"
-  moduleAlias="documents"
-  appTranslations={{ 'pt-BR': pt }}
->
-  <BrowserRouter>
-    <Routes />
-  </BrowserRouter>
-</CoreProviders>
-```
-
-
-### O que funciona sem Supabase em `backend="dotnet"`
-
-A lib mantém os seguintes recursos funcionando 100% sem nenhuma env var Supabase:
-
-- **Logos e favicon** (`assets`, `logoSrc`, `smallLogoSrc`): servidos a partir de bucket público fixo embutido na lib.
-- **Login automático em dev/preview**: `shouldUseDevTokens()` agora exige modo Supabase, então em modo dotnet o `ProtectedRoute` sempre vai para `loginProd()` (OAuth real), mesmo em `localhost`/Lovable preview.
-- **Logoff manual**: `TokenManager.clearAll()` preserva o flag `manual_logout`, garantindo que `logout()` realmente deslogue (sem auto-login no próximo render).
-- **`LegacyKeyBanner`**: oculto automaticamente em modo dotnet.
-
-### Features que continuam exigindo Supabase
-
-Mesmo com `backend="dotnet"`, se você importar qualquer um dos módulos abaixo eles vão falhar em runtime sem Supabase configurado:
-
-- `forlogic-core/sign`
-- `forlogic-core/audit-trail`
-- `forlogic-core/action-plans`
-- `forlogic-core/leadership`
-- `forlogic-core/places`
-- `EmailService` (do barrel principal)
-
-Esses módulos **foram removidos do barrel principal** (breaking change) — importe-os via subpath quando precisar. Use `isSupabaseConfigured()` para checar disponibilidade antes de chamar `getSupabaseClient()`.
-
-## QueryClient default
-
-```ts
-{ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, retry: 1 } } }
-```
+# Padrão: CoreProviders Setup
+
+## Providers incluídos
+
+| Provider | Descrição |
+|----------|-----------|
+| ErrorBoundary | Captura erros de renderização React |
+| I18nextProvider | Sistema de internacionalização |
+| QueryClientProvider | Cache e queries (React Query) |
+| AuthProvider | Autenticação e sessão |
+| LocaleProvider | Idioma, timezone, formato de data |
+| ModuleProvider | Configuração de módulo ativo |
+| ModuleAccessGuard | Bloqueio de acesso por módulo |
+
+## Uso básico
+
+```tsx
+<CoreProviders moduleAlias="performance" appTranslations={{ 'pt-BR': ptBR }}>
+  <BrowserRouter>
+    <Routes />
+  </BrowserRouter>
+</CoreProviders>
+```
+
+## Props
+
+| Prop | Tipo | Obrigatório | Descrição |
+|------|------|-------------|-----------|
+| children | ReactNode | Sim | Componentes filhos |
+| queryClient | QueryClient | Não | Instância customizada (default criado automaticamente) |
+| moduleAlias | string | Não | Alias do módulo para verificação de acesso |
+| moduleApiUrl | string | Não | (DEPRECATED — substituído por `associationsBaseUrl`) |
+| associationsBaseUrl | string | Não | Base URL completa para `/Users/{userId}/associations`. Ver seção abaixo. |
+| moduleAccessGuardProps | object | Não | Props para o ModuleAccessGuard |
+| appTranslations | Record<string, Record<string, string>> | Não | Traduções por idioma no namespace 'app' |
+| clarityProjectId | string | Não | Project ID do Microsoft Clarity. Sem ele, integração desativada. |
+| clarityMode | 'auto' \| 'disabled' | Não | Opt-out do tracking Clarity. Default `'auto'`. |
+| backend | 'supabase' \| 'dotnet' | Não | Backend ativo. Default `'supabase'`. Ver seção abaixo. |
+| signDocumentsSchema | string | Não | Schema onde a tabela de tracking do D4Sign vive neste projeto. Default `'common'`. Ver seção abaixo. |
+| signDocumentsTable | string | Não | Nome da tabela de tracking. Default `'sign_documents'`. |
+
+## Tabela `sign_documents` por schema (D4Sign)
+
+Por padrão, o webhook D4Sign grava o resultado em `common.sign_documents`. Projetos que mantêm a tabela no próprio schema (ex.: Educação) podem redirecionar via:
+
+```tsx
+<CoreProviders
+  moduleAlias="educacao"
+  signDocumentsSchema="educacao"
+  // signDocumentsTable opcional — default 'sign_documents'
+>
+  ...
+</CoreProviders>
+```
+
+O que acontece:
+
+1. `DocumentSigner` envia `target_schema` e `target_table` para a edge function `d4sign` no `create_and_send`.
+2. A edge function `d4sign` insere a linha `pending` no schema/tabela alvo e registra o webhook do D4Sign com a URL `/functions/v1/d4sign-webhook?schema={schema}&table={table}`.
+3. A edge function `d4sign-webhook` lê os query params, valida contra uma **allowlist** de schemas (`common`, `educacao`, `treinamentos`, `inovacao`, `public`) e faz o `UPDATE` no schema correto.
+4. O front se inscreve no Realtime no mesmo schema/tabela.
+
+**Requisitos no projeto consumidor:**
+
+Cada projeto que redirecionar o destino precisa criar a tabela no seu próprio schema com **exatamente** o contrato abaixo — os nomes e tipos das colunas são consumidos pelas edge functions `d4sign` e `d4sign-webhook` e pelo `DocumentSigner`. Divergir quebra o fluxo.
+
+### Contrato de campos
+
+| Campo | Tipo | Obrigatório | Default | Preenchido por |
+|---|---|---|---|---|
+| `document_id` | `text` PK | sim | — | front (`DocumentSigner`, `crypto.randomUUID()`) |
+| `alias` | `text` | sim | — | front |
+| `provider` | `text` | sim | `'d4sign'` | front |
+| `envelope_id` | `text` | sim | — | edge `d4sign` (UUID retornado pelo D4Sign) |
+| `signer_email` | `text` | sim | — | front |
+| `signer_name` | `text` | não | — | front |
+| `filename` | `text` | não | — | front |
+| `status` | `text` | sim | `'pending'` | webhook (`pending` → `signed` / `cancelled` / `failed`) |
+| `signed_at` | `timestamptz` | não | — | webhook |
+| `download_url` | `text` | não | — | webhook |
+| `download_url_expires_at` | `timestamptz` | não | — | webhook (~50 min) |
+| `raw_webhook_payload` | `jsonb` | não | — | webhook |
+| `created_at` | `timestamptz` | sim | `now()` | DB |
+| `updated_at` | `timestamptz` | sim | `now()` | trigger |
+
+> **PK em `document_id`** (não `id` serial) — é a chave que o front usa para correlacionar o envelope com a row.
+
+### Script SQL (substituir `{schema}`)
+
+```sql
+CREATE TABLE {schema}.sign_documents (
+  document_id text PRIMARY KEY,
+  alias text NOT NULL,
+  provider text NOT NULL DEFAULT 'd4sign',
+  envelope_id text NOT NULL,
+  signer_email text NOT NULL,
+  signer_name text,
+  filename text,
+  status text NOT NULL DEFAULT 'pending',
+  download_url text,
+  download_url_expires_at timestamptz,
+  raw_webhook_payload jsonb,
+  signed_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX sign_documents_alias_status_idx ON {schema}.sign_documents (alias, status);
+CREATE INDEX sign_documents_envelope_idx     ON {schema}.sign_documents (envelope_id);
+
+GRANT SELECT ON {schema}.sign_documents TO authenticated;
+GRANT ALL    ON {schema}.sign_documents TO service_role;
+
+ALTER TABLE {schema}.sign_documents ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "sign_documents_select_own_tenant"
+  ON {schema}.sign_documents
+  FOR SELECT
+  TO authenticated
+  USING (alias = ((SELECT auth.jwt()) ->> 'alias'));
+
+CREATE OR REPLACE FUNCTION {schema}.sign_documents_set_updated_at()
+RETURNS TRIGGER LANGUAGE plpgsql SET search_path = {schema}, public AS $$
+BEGIN NEW.updated_at = now(); RETURN NEW; END;
+$$;
+
+CREATE TRIGGER sign_documents_updated_at
+  BEFORE UPDATE ON {schema}.sign_documents
+  FOR EACH ROW EXECUTE FUNCTION {schema}.sign_documents_set_updated_at();
+
+-- Realtime — obrigatório, senão o DocumentSigner nunca recebe o evento de assinatura
+ALTER TABLE {schema}.sign_documents REPLICA IDENTITY FULL;
+ALTER PUBLICATION supabase_realtime ADD TABLE {schema}.sign_documents;
+```
+
+### Notas importantes
+
+- **`sign_configs` continua em `common`** — o webhook lê de lá independentemente do schema alvo. Cada projeto que usa assinatura precisa ter `common.sign_configs` populado (via `/a/cs` no Admin).
+- **`REPLICA IDENTITY FULL` + entrada na publication `supabase_realtime`** são obrigatórios. Sem isso, o `DocumentSigner` fica em loading eterno após assinar.
+- **Schemas novos** precisam ser adicionados à constante `ALLOWED_SCHEMAS` em `supabase/functions/d4sign/index.ts` **e** `supabase/functions/d4sign-webhook/index.ts`, senão o webhook silenciosamente cai para `common` (proteção anti-SSRF).
+
+**Retrocompatibilidade:** sem essas props, tudo continua apontando para `common.sign_documents` — Admin segue funcionando inalterado.
+
+
+## Associações em outra base URL
+
+Por padrão, `useModuleAccess` (e o `ModuleAccessGuard`) busca as associações em:
+
+```
+{QUALIEX_API_URL}/api/common/v1/Users/{userId}/associations
+```
+
+Quando o módulo expõe seu próprio endpoint de associações, informe `associationsBaseUrl` no `CoreProviders`. A lib passa a chamar:
+
+```
+{associationsBaseUrl}/Users/{userId}/associations
+```
+
+`associationsBaseUrl` deve incluir todo o prefixo (host + `/api/{modulo}/v1`):
+
+```tsx
+<CoreProviders
+  backend="dotnet"
+  associationsBaseUrl={import.meta.env.VITE_ASSOCIATIONS_API_URL}
+  // ex: "https://api.qualiex.com/api/inovacao/v1"
+>
+  ...
+</CoreProviders>
+```
+
+Características:
+
+- **Uma única variável** — não exige `moduleAlias`. Pode ser usada sem ativar o `ModuleAccessGuard` (útil enquanto o software do módulo ainda não foi cadastrado no `SOFTWARES_MAP` da lib).
+- A API alvo deve responder no mesmo contrato (`UserAssociation[]`) e aceitar os headers `Authorization: Bearer <token>` e `un-alias: <alias>`.
+- Demais endpoints (`/companiesusers`, `/softwares`) continuam consultando a common.
+
+
+## Backend (Supabase opcional)
+
+A prop `backend` controla se a lib usa o stack Supabase ou apenas a API .NET do Qualiex.
+
+- `'supabase'` (default, retrocompat): inicializa o cliente Supabase, valida tokens via Edge Function `validate-token` e exige `SUPABASE_URL` + `SUPABASE_PUBLISHABLE_KEY` (ou as versões `VITE_SUPABASE_*` legadas) no `.env`. O `vite.config.ts` consolida ambos os formatos via `resolveSupabaseEnv()` — ver `docs/design-system/patterns/feature-flags.md`.
+- `'dotnet'`: a lib **não** chama Supabase em nenhum momento da inicialização. O `AuthProvider` autentica apenas com os tokens OAuth do Qualiex (`access_token` + `id_token`). Não exige envs do Supabase. **Importante:** defina `VITE_APP_ENV="DEV"` no `.env` quando o app rodar contra o ambiente dev do Qualiex — sem essa variável, o failsafe assume `PROD`.
+
+### Exemplos de uso por backend
+
+```tsx
+// ============================================================
+// Módulo COM Supabase (default — não precisa declarar backend)
+// ============================================================
+// .env obrigatório:
+//   SUPABASE_URL="https://<project>.supabase.co"
+//   SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."
+//   VITE_SUPABASE_PK_OVERRIDE="sb_publishable_..."
+//
+import { CoreProviders } from 'forlogic-core';
+import { BrowserRouter } from 'react-router';
+import pt from '@/locales/pt-BR.json';
+
+<CoreProviders moduleAlias="performance" appTranslations={{ 'pt-BR': pt }}>
+  <BrowserRouter>
+    <Routes />
+  </BrowserRouter>
+</CoreProviders>
+```
+
+```tsx
+// ============================================================
+// Módulo SEM Supabase (ex.: Documentos, APIs próprias)
+// ============================================================
+// .env obrigatório:
+//   VITE_APP_ENV="DEV"   // ou "PROD"
+//
+// Nenhuma env do Supabase é exigida.
+//
+import { CoreProviders } from 'forlogic-core';
+import { BrowserRouter } from 'react-router';
+import pt from '@/locales/pt-BR.json';
+
+<CoreProviders
+  backend="dotnet"
+  moduleAlias="documents"
+  appTranslations={{ 'pt-BR': pt }}
+>
+  <BrowserRouter>
+    <Routes />
+  </BrowserRouter>
+</CoreProviders>
+```
+
+
+### O que funciona sem Supabase em `backend="dotnet"`
+
+A lib mantém os seguintes recursos funcionando 100% sem nenhuma env var Supabase:
+
+- **Logos e favicon** (`assets`, `logoSrc`, `smallLogoSrc`): servidos a partir de bucket público fixo embutido na lib.
+- **Login automático em dev/preview**: `shouldUseDevTokens()` agora exige modo Supabase, então em modo dotnet o `ProtectedRoute` sempre vai para `loginProd()` (OAuth real), mesmo em `localhost`/Lovable preview.
+- **Logoff manual**: `TokenManager.clearAll()` preserva o flag `manual_logout`, garantindo que `logout()` realmente deslogue (sem auto-login no próximo render).
+- **`LegacyKeyBanner`**: oculto automaticamente em modo dotnet.
+
+### Features que continuam exigindo Supabase
+
+Mesmo com `backend="dotnet"`, se você importar qualquer um dos módulos abaixo eles vão falhar em runtime sem Supabase configurado:
+
+- `forlogic-core/sign`
+- `forlogic-core/audit-trail`
+- `forlogic-core/action-plans`
+- `forlogic-core/leadership`
+- `forlogic-core/places`
+- `EmailService` (do barrel principal)
+
+Esses módulos **foram removidos do barrel principal** (breaking change) — importe-os via subpath quando precisar. Use `isSupabaseConfigured()` para checar disponibilidade antes de chamar `getSupabaseClient()`.
+
+## QueryClient default
+
+```ts
+{ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, retry: 1 } } }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forlogic-core",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",