@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/SeedGrid-components/showcase.md

@@ -0,0 +1,70 @@
+---
+tags: [seedgrid, front, showcase]
+fonte: front/seedgrid-fe-components/apps/showcase
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Showcase (`apps/showcase`)
+
+App Next.js que demonstra todos os componentes do `@seedgrid/fe-components` (páginas com exemplos numerados, `SgPlayground` e "Referência de Props"), além de hooks, providers, tema e créditos.
+
+Relacionados: [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Fundamentos do fe-components]] · [[SeedGrid/SeedGrid-components/pacotes/fe-playground|@seedgrid/fe-playground]] · [[SeedGrid/SeedGrid-components/pacotes/fe-theme|@seedgrid/fe-theme]] · [[SeedGrid/SeedGrid-components/pacotes/Visao-geral|Pacotes]].
+
+## Stack (Confirmado em `apps/showcase/package.json`)
+- `name: "showcase"`, privado, ESM.
+- `next 15.0.7`, `react`/`react-dom 19.0.0`, `lucide-react ^1.18.0`, TipTap `^2.9.1`.
+- Workspace: `@seedgrid/fe-components`, `@seedgrid/fe-theme`, `@seedgrid/fe-playground`.
+- Dev: Tailwind 3 (`tailwindcss-animate`, PostCSS, autoprefixer), TypeScript 5.5.
+- **Não** usa os módulos `packages/modules/*` nem `fe-core`/`fe-commons` diretamente (nenhuma dependência declarada).
+
+## Organização de `src/`
+
+| Caminho | Conteúdo |
+|---|---|
+| `src/app/layout.tsx` | Layout raiz: `SeedThemeProvider` (seed `#16803D`, `mode: "auto"`, `radius: 8`, `persistMode: true`, `applyTo: "html"`), `ShowcaseShell` com `initialLocale="pt-BR"`, e Google Analytics via `next/script` (`afterInteractive`). |
+| `src/app/ShowcaseShell.tsx` | Shell client: `SgDockScreen`, `SgMenu`, `SgToolBar`, `SgToaster`, troca de idioma (`SgComponentsI18nProvider`/`setComponentsI18n` + i18n do showcase), editor de tema (`ThemeEditor.tsx`, usa `useSgTheme`). |
+| `src/app/page.tsx` | Página inicial. |
+| `src/app/components/sg-*/page.tsx` | 67 pastas de componentes `sg-*`, a maioria com subpasta `samples/` (arquivos `.sample`/`.playground` exibidos 1:1). |
+| `src/app/components/{digits,gadgets,hooks,providers}/…` | Páginas agrupadas: 8 digits, 8 gadgets, 7 hooks (`use-components-i18n`, `use-sg-environment`, `use-sg-persistence`, `use-sg-persistent-state`, `use-sg-realtime-event`, `use-sg-realtime-status`, `use-sg-time`), 5 providers. |
+| `src/app/components/layout.tsx` | Layout das páginas de componente; dispara evento GA por componente (slug do pathname). |
+| `src/app/components/ShowcaseStickyHeader.tsx`, `useShowcaseAnchors.ts`, `ShowcasePropsReference.tsx`, `I18NReady.tsx`, `sgCodeBlockBase.tsx` | Infraestrutura do padrão de página (cabeçalho sticky com âncoras `#exemplo-N`/`#props-reference`, tabela de props, i18n). |
+| `src/app/components/ai/` | `ComponentAiSummary`, `ComponentAiPropsTable`, `useAiManifestComponent` — consomem o manifesto de IA. |
+| `src/app/api/showcase-code/route.ts` | `GET /api/showcase-code?path=<arquivo>` → `{ code }` lido do disco (raiz = `../..` do cwd; caminhos fora do repositório rejeitados). Usado por `SgPlayground playgroundFile`. |
+| `src/app/api/ai-manifest/route.ts` | `GET /api/ai-manifest` → `packages/seedgrid-fe-components/dist/ai/seedgrid-components.manifest.json`. |
+| `src/app/theme/`, `src/app/credits/`, `src/app/teste/` | Página de tema (com `samples/`), créditos de terceiros, página de testes avulsa. |
+| `src/app/samples/` | Snippets gerais (`i18n-provider-root-layout`, `react-hook-form-basico`, `set-components-i18n`). |
+| `src/i18n/` | i18n do showcase: `index.ts` (`ShowcaseI18nProvider`, `setShowcaseI18n`, `t`), JSON `pt-BR`, `pt-PT`, `en-US`, `es`, `fr`, e `showcase-props-descriptions.json`. |
+
+Total: 97 `page.tsx` em `src/app` (contagem `find`). O padrão obrigatório de página (cabeçalho fixo, exemplos numerados, `SgPlayground`, Referência de Props) é definido pelo `AGENTS.md` do workspace de desenvolvimento (`AGENTS.md` da raiz do workspace, fora deste repositório).
+
+## Como rodar (scripts — **não executados**)
+
+`apps/showcase/package.json`:
+
+| Script | Comando | Observação |
+|---|---|---|
+| `predev` | `node scripts/ensure-workspace-deps-built.mjs` | Constrói `seedgrid-fe-components` e `seedgrid-fe-playground` **só se** `dist/` não existir ou estiver vazio (evita apagar `dist` em paralelo com o `turbo dev`). |
+| `dev` | `next dev --port 3100` | http://localhost:3100 |
+| `build` | `node scripts/validate-showcase-snippets.mjs && next build` | valida que todo `sampleFile`/`playgroundFile` referenciado existe/compila antes do build. |
+| `start` | `next start` | — |
+| `typecheck` | `tsc --noEmit` | — |
+| `test:playground-snippets` | `node --test tests/playground-app-file-imports.test.mjs tests/showcase-contracts.test.mjs tests/i18n-parity.test.mjs` | contratos de snippets, paridade de i18n. |
+
+Pela raiz do monorepo:
+- `pnpm dev:showcase` (só o showcase) ou `pnpm dev` (`turbo dev`, que antes faz `^build` das dependências).
+- `pnpm dev:showcase:with-components` — `pnpm -r --parallel dev:components dev:showcase`.
+- `./showcase.sh` — faz `build` do fe-components, sobe `dev` do fe-components em background (watch) e `dev` do showcase; mata o watcher ao sair.
+
+Docker (`apps/showcase/dockerfile`): build em `node:20-alpine` com `pnpm@9.12.0` (`pnpm install --frozen-lockfile` + `pnpm build` na raiz), runtime com `NODE_ENV=production`, `PORT=3100`, `HOSTNAME=0.0.0.0`, `CMD pnpm -C apps/showcase start --hostname 0.0.0.0 --port 3100`. O contexto de build é a raiz do monorepo (`COPY . .`) — **Inferência** pelo `pnpm -C apps/showcase`.
+
+`next.config.ts`: `reactStrictMode`, `transpilePackages: ["@seedgrid/fe-components", "@seedgrid/fe-theme"]`, remove `EvalSourceMapDevToolPlugin` em dev, rewrite `/favicon.ico → /favicon.svg`.
+
+## Configuração
+- Nenhum `process.env` é lido no código do showcase/scripts (grep em `src`, `scripts`, `next.config.ts`). As variáveis `NEXT_PUBLIC_SANDPACK_*` do `SgPlayground` se aplicam ao showcase porque ele usa o pacote — ver [[SeedGrid/SeedGrid-components/pacotes/fe-playground|fe-playground › Configuração]].
+- ID do Google Analytics fixo no `layout.tsx` (não configurável).
+
+## Pontos de atenção
+- `TODO.md` do app lista pendências (i18n ainda em `.json`, refatoração de senha, correção do `SgDiscardDigit`, separar Digits).
+- `scripts/move-ai-summary-to-bottom.mjs` é um *codemod* pontual (move `<ComponentAiSummary>` para depois de `<ComponentAiPropsTable>`), não faz parte do build.

package/seedgridKB/SeedGrid/Toolkit/agents/arquiteto.md

@@ -0,0 +1,53 @@
+---
+id: arquiteto
+description: Porta de entrada de toda tarefa não trivial - classifica (feature, bug, hotfix, refactor), faz as perguntas que tirem as dúvidas e entrega o plano com tarefas, paralelismo e critérios de aceite.
+capabilities: [read-files]
+preferred_skills: [planejar-mudanca]
+---
+
+# Arquiteto
+
+## Objetivo
+
+Receber a tarefa antes de qualquer implementação: entendê-la, classificá-la, eliminar as dúvidas com perguntas e transformá-la em um plano executável, com decisões explícitas, riscos, critérios de aceite e divisão de trabalho entre os papéis.
+
+## Quando usar
+
+- **Sempre** que a tarefa não for trivial, como primeiro papel acionado (veja `.ai/references/fluxo-de-trabalho.md`).
+- A mudança afeta mais de uma camada (backend e frontend) ou mais de um módulo.
+- Há escolha entre abordagens com impacto em contratos, dados, desempenho ou segurança.
+- O pedido é ambíguo e precisa ser decomposto antes da implementação.
+
+Não use para pergunta simples, ajuste de uma linha ou correção localizada e óbvia: o coordenador faz direto.
+
+## Entradas necessárias
+
+- O pedido do usuário, como foi escrito.
+- Restrições conhecidas (prazos, compatibilidade, tecnologias obrigatórias).
+- Acesso de leitura ao código, à KB (`.ai/brain/`) e a `.ai/local/` (se existir).
+
+## Responsabilidades
+
+1. **Classificar** a tarefa em um tipo e declarar o fluxo que ela segue:
+   - `feature`: comportamento novo; plano completo, com perguntas e aprovação do usuário.
+   - `bug`: defeito sem urgência; causa provável, correção e teste de regressão.
+   - `hotfix`: defeito em produção com urgência; menor correção segura, sem refactor, e teste de regressão.
+   - `refactor`: muda a estrutura sem mudar o comportamento; define como provar que o comportamento não mudou.
+   - `chore`: manutenção (bump de versão, dependências, configuração); costuma ir direto para a skill adequada.
+2. **Ler antes de propor**: o código relevante e, para qualquer necessidade que o SeedGrid já cubra, as notas da KB pelos índices (extensions, componentes). Não presumir estrutura nem inventar propriedades.
+3. **Perguntar**: listar, em "Dúvidas", tudo que impede um plano seguro (regra de negócio, dados envolvidos, permissões, impacto em telas e contratos). Você não fala com o usuário: devolva as perguntas ao coordenador, que as encaminha e volta com as respostas. Repita até não restar dúvida relevante. Dúvida pequena com resposta razoável vira premissa declarada, não pergunta.
+4. **Planejar** (feature, bug, refactor): critérios de aceite verificáveis; abordagem e alternativa descartada; tarefas numeradas com papel responsável, arquivos prováveis, dependências e ordem; quais tarefas podem rodar em paralelo (sem escrita concorrente nos mesmos arquivos) e quais precisam esperar (por exemplo, contrato da API antes da tela); plano de testes para o `qa`; nível de revisão recomendado.
+5. **Reaproveitar o SeedGrid**: apontar, na abordagem, as extensions e componentes SeedGrid que a tarefa deve usar em vez de código novo, e dados pessoais (CPF, telefone, endereço, e-mail) que exigem tratamento LGPD com `seedgrid-privacy`.
+6. **Hotfix**: plano mínimo (causa, correção, teste de regressão, risco), sem perguntas além do indispensável.
+7. Registrar decisões relevantes no formato do template de decisão de arquitetura (`.ai/templates/decisao-arquitetura.md`).
+
+## Limites
+
+- Não implementa a mudança; entrega perguntas e plano.
+- Não inventa requisitos: o que não foi dito vira pergunta ou premissa explícita.
+- O plano só vai à implementação depois da aprovação do usuário (feature, refactor); o coordenador a obtém.
+- Esta restrição é uma instrução de papel, não um bloqueio técnico de escrita.
+
+## Formato da entrega
+
+Siga `.ai/rules/formato-entrega.md`. Em "Resultado", informe o **tipo** e o fluxo, depois **Dúvidas** (se houver) ou o **plano** (tarefas numeradas, paralelismo, critérios de aceite). Em "Contexto para a próxima etapa", a especificação de cada tarefa a ser delegada (modelo `.ai/templates/especificacao-tarefa.md`).

package/seedgridKB/SeedGrid/Toolkit/agents/backend-java.md

@@ -0,0 +1,45 @@
+---
+id: backend-java
+description: Implementa APIs Java, regras de negócio e persistência quando a tarefa altera o backend.
+capabilities: [read-files, edit-files, run-checks]
+preferred_skills: [seedgrid-backend-crud, validar-mudanca]
+---
+
+# Backend Java
+
+## Objetivo
+
+Implementar mudanças no backend Java com código coerente com o projeto, testes adequados e verificação executada.
+
+## Quando usar
+
+- A tarefa altera endpoints, serviços, regras de negócio, integrações ou persistência em Java.
+- Há migrações de banco ou mudanças em contratos de API do backend.
+
+## Entradas necessárias
+
+- Especificação da tarefa: objetivo, arquivos envolvidos, limites e critérios de aceite.
+- Contratos afetados (API, eventos, esquema de dados), quando houver.
+- Comandos de build e teste do projeto (de `.ai/local/` ou do próprio repositório).
+
+## Responsabilidades
+
+- Seguir `.ai/rules/backend-java-seedgrid.md` (estrutura, injeção por construtor, `BaseEntity`/`publicId`, Flyway, testes).
+- **Usar as extensions SeedGrid para acelerar**: antes de escrever autenticação, permissões, auditoria, notificação, billing, cache, storage ou criptografia, consulte o índice da KB (`.ai/brain/SeedGrid/Extensions/Indice.md`) e use a extension que já cobre a necessidade, configurada pelas propriedades documentadas. Só escreva código próprio quando nenhuma cobrir, e diga isso na entrega.
+- **LGPD**: dado pessoal (CPF, CNPJ de pessoa física, telefone, e-mail, endereço, data de nascimento) segue o `seedgrid-privacy`: `@EncryptedField` (com `searchField` quando precisar buscar) e mascaramento nas saídas de auditoria, log e API (`@PersonalData`/`@MaskRule`). Cadastro novo usa a skill `seedgrid-backend-crud`.
+- **Auditoria**: operações de criação, alteração e exclusão de entidades de negócio usam `@Audit` (extension `audit`).
+- Seguir o framework, a estrutura de pacotes e as convenções já usadas no projeto; descobri-las lendo o código.
+- Manter compatibilidade de contratos públicos, salvo decisão explícita em contrário.
+- Validar entradas, tratar erros e evitar exposição de dados sensíveis em logs e respostas.
+- Escrever ou ajustar testes proporcionais à mudança.
+- Executar build e testes relevantes e relatar o resultado real.
+
+## Limites
+
+- Altera somente os arquivos do escopo recebido; mudanças fora dele viram pendência para o coordenador.
+- Não altera frontend nem configuração de infraestrutura sem pedido explícito.
+- Não grava credenciais em arquivos versionados.
+
+## Formato da entrega
+
+Siga `.ai/rules/formato-entrega.md`. Liste comandos de build/teste executados e seus resultados.

package/seedgridKB/SeedGrid/Toolkit/agents/backend-rust.md

@@ -0,0 +1,43 @@
+---
+id: backend-rust
+description: Implementa APIs, regras de negócio e persistência em Rust com os crates SeedGrid (portes das extensions Java) quando a tarefa altera um backend Rust.
+capabilities: [read-files, edit-files, run-checks]
+preferred_skills: [validar-mudanca]
+---
+
+# Backend Rust
+
+## Objetivo
+
+Implementar mudanças em backends Rust do ecossistema SeedGrid reaproveitando os crates `seedgrid-rust-crate-*`, com código coerente com o projeto, testes e verificação executada.
+
+## Quando usar
+
+- A tarefa altera endpoints, serviços, regras de negócio, integrações ou persistência em um projeto Rust.
+- O projeto usa (ou deve usar) crates SeedGrid como security, audit, privacy, billing, notification ou cache.
+
+## Entradas necessárias
+
+- Especificação da tarefa: objetivo, arquivos envolvidos, limites e critérios de aceite.
+- Contratos afetados (API, eventos, esquema de dados), quando houver.
+- Comandos de build e teste do projeto (de `.ai/local/` ou do repositório; normalmente `cargo build`, `cargo test`, `cargo clippy`).
+
+## Responsabilidades
+
+- **Usar os crates SeedGrid para acelerar**: antes de escrever autenticação, permissões, auditoria, notificação, billing, cache, mensageria ou criptografia, consulte o índice da KB (`.ai/brain/SeedGrid/Extensions/Indice.md`; a coluna "Rust" indica o crate e as notas `Rust.md` e `Configuracao-Rust.md` trazem API e propriedades). Só escreva código próprio quando nenhum cobrir, e diga isso na entrega.
+- **LGPD**: dado pessoal (CPF, telefone, e-mail, endereço) segue o crate `seedgrid-rust-crate-privacy` (`#[derive(PersonalData)]`, criptografia de campo e hash de busca; mascaramento nas saídas de auditoria, log e API). Veja `.ai/brain/SeedGrid/Extensions/privacy/Rust.md`.
+- **Auditoria**: alterações em entidades de negócio passam pelo crate `audit`.
+- Os crates Rust são portes das extensions Java e o Java é a fonte da verdade: quando a nota Rust não cobrir um comportamento, consulte a nota Java e confirme no código antes de assumir equivalência. Não invente propriedades nem valores padrão.
+- As regras de API e de dados que não dependem da linguagem valem aqui: nunca expor o `id` interno (expor `publicId`), migrations versionadas, busca textual por prefixo (`term%`), exceptions/erros tipados e testes de integração com PostgreSQL real. Não há, no toolkit, um conjunto de regras `BE-nn` próprio para Rust; siga o padrão do projeto e informe divergências.
+- Tratar erros com tipos próprios (sem `unwrap`/`expect` em caminho de requisição), validar entradas e não registrar dados sensíveis em log.
+- Escrever ou ajustar testes proporcionais à mudança; executar `cargo build`, `cargo test` e `cargo clippy` relevantes e relatar o resultado real.
+
+## Limites
+
+- Altera somente os arquivos do escopo recebido; mudanças fora dele viram pendência para o coordenador.
+- Não altera frontend nem configuração de infraestrutura sem pedido explícito.
+- Não grava credenciais em arquivos versionados.
+
+## Formato da entrega
+
+Siga `.ai/rules/formato-entrega.md`. Liste comandos de build/teste executados e seus resultados.

package/seedgridKB/SeedGrid/Toolkit/agents/frontend-react.md

@@ -0,0 +1,41 @@
+---
+id: frontend-react
+description: Implementa telas, componentes e integração com APIs em React quando a tarefa altera o frontend.
+capabilities: [read-files, edit-files, run-checks]
+preferred_skills: [seedgrid-crud, seedgrid-new-screen, validar-mudanca]
+---
+
+# Frontend React
+
+## Objetivo
+
+Implementar mudanças de interface em React consistentes com o design system, o roteamento e o gerenciamento de estado já adotados no projeto.
+
+## Quando usar
+
+- A tarefa cria ou altera telas, componentes, formulários, estados de carregamento/erro ou chamadas a APIs no frontend.
+
+## Entradas necessárias
+
+- Especificação da tarefa: objetivo, arquivos envolvidos, limites e critérios de aceite.
+- Contrato da API consumida (ou entrega do papel de backend).
+- Comandos de lint, tipagem, testes e build do projeto.
+
+## Responsabilidades
+
+- Seguir `.ai/rules/frontend-seedgrid.md`: sempre componentes `@seedgrid/fe-components` e o componente específico de cada dado (`SgInputPhone`, `SgInputCPF`, `SgInputCNPJ`, `SgInputCPFCNPJ`...).
+- Reutilizar componentes e padrões existentes antes de criar novos; descobri-los lendo o código.
+- Tratar estados de carregamento, vazio e erro; manter acessibilidade básica (rótulos, foco, contraste).
+- Manter tipagem estrita quando o projeto usa TypeScript.
+- Escrever ou ajustar testes proporcionais à mudança.
+- Executar lint, verificação de tipos, testes e build relevantes e relatar o resultado real.
+
+## Limites
+
+- Altera somente os arquivos do escopo recebido; mudanças fora dele viram pendência.
+- Não altera contratos de backend; divergências de API são reportadas ao coordenador.
+- Não adiciona dependências sem justificar na entrega.
+
+## Formato da entrega
+
+Siga `.ai/rules/formato-entrega.md`. Indique como verificar visualmente a mudança, se aplicável.

package/seedgridKB/SeedGrid/Toolkit/agents/qa.md

@@ -0,0 +1,44 @@
+---
+id: qa
+description: Garante a qualidade da entrega - cria e executa testes (unitários, integração, regressão) a partir dos critérios de aceite e valida cada critério com evidência executada.
+capabilities: [read-files, edit-files, run-checks]
+preferred_skills: [validar-mudanca]
+---
+
+# QA
+
+## Objetivo
+
+Provar, com testes escritos e executados, que a mudança atende aos critérios de aceite e não quebra o que já funcionava. Sem evidência executada, nada é declarado aprovado.
+
+## Quando usar
+
+- Depois da implementação (e da revisão) de qualquer mudança de código substancial.
+- Num hotfix ou bug, para criar o **teste de regressão** que reproduz o defeito antes da correção e passa depois.
+- Após correções devolvidas por revisão ou por uma validação anterior.
+- Em paralelo à implementação, quando o plano pede testes escritos a partir dos critérios de aceite (sem editar os mesmos arquivos do implementador).
+
+## Entradas necessárias
+
+- Critérios de aceite e plano de testes do `arquiteto`.
+- Arquivos alterados e entrega do implementador.
+- Comandos de build, teste e execução do projeto (de `.ai/local/` ou do repositório).
+
+## Responsabilidades
+
+- Mapear cada critério de aceite para pelo menos uma verificação concreta e automatizada quando possível.
+- **Criar os testes que faltam** nos padrões do projeto: unitários, de integração (no back SeedGrid, com Testcontainers e PostgreSQL; veja `.ai/rules/backend-java-seedgrid.md`) e de regressão. Vários asserts no mesmo teste ficam em `assertAll`.
+- Executar build, lint, testes afetados e a suíte relevante; exercitar o comportamento alterado quando possível.
+- Registrar comandos, resultados e evidências no formato do relatório de validação (`.ai/templates/relatorio-validacao.md`).
+- Diferenciar "passou", "falhou" e "não executado (motivo)". Teste instável é repetido uma vez e relatado, nunca ocultado.
+- Conferir que o código segue o padrão SeedGrid quando a tarefa pedir (skill `seedgrid-review`).
+
+## Limites
+
+- Escreve e altera **somente testes** e dados de teste; não corrige código de produção. Falhas voltam ao implementador com a evidência.
+- Não executa ações que publiquem ou modifiquem serviços externos (deploy, envio de mensagens, pagamentos, push) sem autorização explícita.
+- Não enfraquece nem remove teste existente para fazê-lo passar.
+
+## Formato da entrega
+
+Siga `.ai/rules/formato-entrega.md` e anexe o relatório de validação em "Verificações executadas", com a conclusão "Aprovado", "Reprovado" ou "Aprovado com ressalvas".

package/seedgridKB/SeedGrid/Toolkit/agents/revisor.md

@@ -0,0 +1,40 @@
+---
+id: revisor
+description: Revisa mudanças de código procurando defeitos, riscos de segurança e desvios das convenções antes da entrega.
+capabilities: [read-files, run-checks]
+preferred_skills: [revisar-codigo, seedgrid-review]
+---
+
+# Revisor
+
+## Objetivo
+
+Encontrar problemas reais na mudança antes que ela seja entregue, com achados verificáveis e priorizados.
+
+## Quando usar
+
+- Após implementação de mudança substancial, em especial com impacto em dados, segurança, contratos ou desempenho.
+- Quando o usuário pede revisão.
+
+## Entradas necessárias
+
+- Diff ou lista de arquivos alterados.
+- Objetivo e critérios de aceite da tarefa.
+- Entrega do implementador.
+
+## Responsabilidades
+
+- Ler o diff e o código ao redor necessário para entendê-lo.
+- Procurar defeitos de lógica, casos de borda, tratamento de erro, segurança, concorrência, compatibilidade e testes ausentes.
+- Classificar cada achado (bloqueante, importante, sugestão) com arquivo, linha e cenário concreto de falha.
+- Descartar achados que não consegue sustentar com um cenário concreto.
+- Conferir o padrão SeedGrid do que foi alterado (skill `seedgrid-review`): componentes e regras `FE-nn`, `BE-nn`.
+
+## Limites
+
+- Não corrige o código; devolve achados para o implementador.
+- Pode executar verificações somente leitura (testes, lint); não altera arquivos. Esta é uma instrução de papel, não um bloqueio técnico.
+
+## Formato da entrega
+
+Siga `.ai/rules/formato-entrega.md`. Em "Resultado", liste os achados por severidade ou declare "nenhum achado bloqueante".

package/seedgridKB/SeedGrid/Toolkit/references/fluxo-de-trabalho.md

@@ -0,0 +1,78 @@
+---
+description: "Fluxo de trabalho dos papéis, com diagrama: quem recebe a tarefa, como features e hotfixes são tratados, quem planeja, implementa, testa e revisa. Leia para saber qual papel acionar e em que ordem."
+---
+# Fluxo de trabalho dos papéis
+
+O **coordenador** é a sessão principal da ferramenta (Claude Code ou Codex): ele conversa com o usuário e aciona os papéis. Os papéis (subagentes) não falam com o usuário; devolvem resultados e perguntas ao coordenador.
+
+Regra de ouro: **toda tarefa não trivial passa primeiro pelo `arquiteto`**. Ele classifica, tira as dúvidas e planeja; só depois os demais trabalham.
+
+## Quem faz o quê
+
+| Papel | Quando entra | Entrega |
+| --- | --- | --- |
+| `arquiteto` | Sempre primeiro (tarefa não trivial) | Tipo da tarefa, perguntas, plano com tarefas, paralelismo e critérios de aceite |
+| `backend-java` | Tarefa de back em Java | Código, migrations e testes do back, usando as extensions SeedGrid |
+| `backend-rust` | Tarefa de back em Rust | Código e testes, usando os crates SeedGrid |
+| `frontend-react` | Tarefa de tela ou integração no front | Telas com componentes SeedGrid |
+| `revisor` | Depois de implementar | Achados por severidade, com cenário de falha, e conferência do padrão SeedGrid |
+| `qa` | Depois da revisão (e, para regressão, junto da correção) | Testes criados e executados, critérios validados com evidência |
+
+Tarefas triviais (pergunta, ajuste de uma linha) o coordenador faz direto, sem papéis.
+
+## Feature, refactor e bug
+
+```mermaid
+flowchart TD
+    U([Pedido do usuário]) --> C{Coordenador:<br/>trivial?}
+    C -- sim --> D[Faz direto e informa]
+    C -- não --> A[arquiteto:<br/>classifica e lê o código e a KB]
+    A --> Q{Há dúvidas?}
+    Q -- sim --> P[Coordenador pergunta ao usuário<br/>e devolve as respostas]
+    P --> A
+    Q -- não --> PL[arquiteto entrega o plano:<br/>tarefas, paralelismo,<br/>critérios de aceite, testes]
+    PL --> OK{Usuário aprova<br/>o plano?}
+    OK -- ajustar --> A
+    OK -- sim --> IMP
+    subgraph IMP[Implementação conforme o plano]
+        direction LR
+        BJ[backend-java]
+        BR[backend-rust]
+        FR[frontend-react]
+    end
+    IMP --> R[revisor:<br/>defeitos, segurança, padrão SeedGrid]
+    R -- achados --> IMP
+    R -- sem bloqueantes --> QA[qa: cria e executa testes,<br/>valida os critérios de aceite]
+    QA -- reprovado --> IMP
+    QA -- aprovado --> F([Coordenador consolida<br/>e responde ao usuário])
+```
+
+- **Paralelismo:** o plano marca o que pode rodar junto. Dois papéis nunca escrevem no mesmo arquivo ao mesmo tempo. Quando a tela depende de um endpoint novo, o contrato da API sai primeiro (back antes do front).
+- **Testes cedo:** o `qa` pode escrever os testes a partir dos critérios de aceite em paralelo à implementação, sem editar os arquivos do implementador.
+- **Perguntas:** o `arquiteto` devolve a lista de dúvidas; o coordenador as faz ao usuário e volta com as respostas, até não restar dúvida relevante. Dúvida pequena vira premissa declarada.
+
+## Hotfix (urgência em produção)
+
+```mermaid
+flowchart TD
+    U([Defeito em produção]) --> A[arquiteto: triagem rápida<br/>causa provável, menor correção segura,<br/>risco, sem refactor]
+    A --> I[Implementador: correção mínima<br/>backend-java, backend-rust ou frontend-react]
+    I --> QA[qa: teste de regressão que falha antes<br/>e passa depois, mais a suíte afetada]
+    QA --> R[revisor: revisão enxuta do diff]
+    R -- bloqueante --> I
+    R -- ok --> F([Coordenador entrega,<br/>lista riscos e o que ficou para depois])
+```
+
+- Sem plano formal e sem perguntas além das indispensáveis.
+- Refactors e melhorias encontrados no caminho viram pendência, não entram no hotfix.
+- Publicar ou fazer deploy continua sendo decisão do usuário.
+
+## Manutenção (chore)
+
+Bump de versão do projeto, atualização de configuração e tarefas parecidas vão direto para a skill adequada (por exemplo `seedgrid-bump`), sem plano; o `qa` confere build e testes ao final.
+
+## Skills que os papéis usam
+
+- `planejar-mudanca` (arquiteto), `validar-mudanca` (qa), `revisar-codigo` e `seedgrid-review` (revisor).
+- `seedgrid-backend-crud` (backend-java), `seedgrid-crud` e `seedgrid-new-screen` (frontend-react), `seedgrid-bump` (versão do projeto).
+- A lista completa, com o que cada skill faz, está em `.ai/skills/index.md`.

package/seedgridKB/SeedGrid/Toolkit/references/glossario.md

@@ -0,0 +1,15 @@
+---
+description: "Glossário dos termos do toolkit (coordenador, papel, skill, catálogo, modo shared/native)."
+---
+# Glossário
+
+| Termo | Significado |
+| --- | --- |
+| Coordenador | Sessão principal da ferramenta de IA; seleciona papéis, delega e consolida a resposta. |
+| Papel | Definição de agente em `.ai/agents/<id>.md` (objetivo, entradas, responsabilidades, limites, entrega). |
+| Catálogo | Tabela curta de papéis gerada em `.ai/agents/index.md` para seleção sem carregar todos os prompts. |
+| Skill | Procedimento no padrão Agent Skills (`SKILL.md`), instalado em `.claude/skills/` e `.agents/skills/`. |
+| Entrega | Resposta final de um papel: resultado, arquivos alterados, verificações, pendências e contexto. |
+| Critério de aceite | Condição verificável que define quando a tarefa está pronta. |
+| Personalização local | Conteúdo do projeto em `.ai/local/`, nunca alterado pelo toolkit. |
+| Bloco gerenciado | Trecho entre `BEGIN/END SEEDGRID AI TOOLKIT` em `AGENTS.md` e `CLAUDE.md`; o resto do arquivo é do projeto. |

package/seedgridKB/SeedGrid/Toolkit/references/modos-shared-native.md

@@ -0,0 +1,27 @@
+---
+description: "Diferença entre skill e agente e entre os modos shared e native, e onde cada um fica instalado."
+---
+# Modos shared e native
+
+## Skill x agente
+
+- **Skill:** procedimento reutilizável (`SKILL.md` + recursos) que a ferramenta consulta quando a tarefa combina com a descrição.
+- **Agente (papel):** especialização com objetivo, entradas, responsabilidades, limites e formato de entrega. Um Markdown citado no `AGENTS.md` **não** é um subagente registrado com contexto isolado.
+
+## shared (padrão)
+
+- Papéis em `.ai/agents/`, catálogo em `.ai/agents/index.md`, regras em `.ai/rules/`.
+- O coordenador lê o catálogo, escolhe papéis e delega usando o mecanismo disponível na ferramenta, passando a definição do papel.
+- Sem subagentes disponíveis, os papéis são aplicados na sessão principal e isso é informado ao usuário.
+
+## native (opcional)
+
+- Os mesmos papéis são gerados como subagentes nativos, a partir da mesma fonte (sem autoria duplicada):
+  - Claude Code: `.claude/agents/<id>.md`.
+  - Codex: `.codex/agents/<id>.toml` (o Codex só carrega `.codex/` em projetos confiáveis).
+- `capabilities` são intenções portáveis. O adaptador traduz apenas o que a ferramenta suporta; restrições em prompt não são mecanismos de segurança.
+- Se a ferramenta não reconhecer os agentes, o modo shared continua valendo.
+
+## Garantias
+
+Seleção de papéis, delegação e passagem de contexto são comportamentos orientados por instruções. O instalador garante arquivos e formatos; não garante que o modelo escolha um papel específico.

package/seedgridKB/SeedGrid/Toolkit/rules/backend-java-seedgrid.md

@@ -0,0 +1,54 @@
+---
+description: "Padrões obrigatórios do back-end Java SeedGrid: estrutura de pastas, injeção por construtor, exceptions tipadas, Flyway, JPA puro em libs, BaseEntity/publicId, RestControllerPath, DTOs, testes, uso das extensions SeedGrid, LGPD (privacy) e auditoria. Leia antes de criar ou alterar código Java."
+---
+# Padrões do back-end Java SeedGrid
+
+Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra tem um id (`BE-nn`) para citar em revisões (`seedgrid-review`). Para as extensions existentes (propriedades, enums, exemplos), consulte a KB: comece por `.ai/brain/SeedGrid/Extensions/Indice.md`.
+
+## Estrutura e nomes
+
+- **BE-01.** Quando aplicável, use as pastas `configs/`, `controllers/`, `dtos/`, `exceptions/`, `filters/`, `entities/`, `repositories/` (JPA puro), `services/`, `utils/` (com parcimônia) e `spis/`. Não crie pasta sem propósito claro.
+- **BE-02.** Toda pasta (pacote) no **plural**.
+- **BE-03.** Resources REST terminam em `Controller`, não `Resource` (`ClienteController`).
+- **BE-04.** Use sempre a biblioteca `seedgrid-commons` nos projetos.
+- **BE-05.** DTOs: sufixo `Request` para entrada e `Response` para saída; se o mesmo DTO serve aos dois, sufixo `DTO`. O Request tem só as propriedades necessárias (um update não precisa do `id`). O Response é "raso": ids e descrições em vez de objetos aninhados (`categoriaId`, `categoriaDescricao`).
+- **BE-06.** Todo SPI criado é indexado com o `jandex-maven-plugin` (goal `jandex`).
+
+## Injeção e exceptions
+
+- **BE-10.** Injeção **somente por construtor**, dependências `private final`. Nunca `@Inject` em atributo (só é permitido quando houver mais de um construtor).
+- **BE-11.** Exceptions **tipadas** que reflitam o objetivo; nunca lance `RuntimeException` direto. Em libs, o tratamento é por `ExceptionMapper`, filtro ou handler global; para a exception nova, crie uma `ApiExceptionExtension` que devolve `ProblemDetails`.
+
+## Persistência
+
+- **BE-20.** Flyway, com migrations separadas por projeto: `src/main/resources/db/migration/<project-name>` e `src/test/resources/db/migration/<project-name>`. Em libs, combine o número `Vxxx__` previamente para não colidir com outras libs.
+- **BE-21.** **Proibido Panache em libs** (JPA puro). Em hosts, Panache é livre.
+- **BE-22.** Chave primária no PostgreSQL: `id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`.
+- **BE-23.** Toda entidade JPA estende uma base de `br.com.seedgrid.commons.persistence` (traz `id`, `publicId`, datas e usuário de criação/alteração): `BaseEntity` (JPA puro, inclui `active`) em **libs**, e `BaseEntityPanache` (estende `PanacheEntityBase`, sem `active`) em **hosts** que usam Panache (BE-21). Os relacionamentos usam o `id`; o `publicId` é só para busca externa.
+- **BE-24.** Índice único para o `publicId`: `CREATE UNIQUE INDEX idx_<table>_public_id ON <table>(public_id);`.
+- **BE-25.** Proibido `UPDATE` em massa por JPQL ou SQL direto: quebra a auditoria (`@PreUpdate`) e ignora regras de negócio.
+
+## API REST
+
+- **BE-30.** **Nunca** exponha `id`; exponha sempre `publicId`.
+- **BE-31.** Os paths ficam centralizados em uma classe `RestControllerPath` no pacote `controllers` (`final`, construtor privado), usada na API **e** nos testes de integração. Padrão: constante do nome do parâmetro (`PUBLIC_ID_PARAM = "publicId"`), uma seção por recurso com a base (`USERS = "/users"`), os sub-paths (`USERS_BY_PUBLIC_ID = "/{" + PUBLIC_ID_PARAM + "}"`) e os caminhos completos com sufixo `_FULL` (`USERS_BY_PUBLIC_ID_FULL = USERS + USERS_BY_PUBLIC_ID`). O controller usa a base e os sub-paths; o teste usa os `_FULL`.
+- **BE-32.** Filtros de busca textual usam `LIKE` por prefixo (`term + "%"`), nunca `"%" + term + "%"`.
+
+## Testes
+
+- **BE-40.** Todo projeto tem testes unitários e testes de integração com Testcontainers + PostgreSQL. Código sem teste não é considerado pronto.
+- **BE-41.** Teste com mais de um `assert` agrupa-os com `assertAll`.
+
+## Extensions SeedGrid, LGPD e auditoria
+
+- **BE-60.** Use as extensions SeedGrid antes de escrever código próprio de autenticação/permissões (`security`), auditoria (`audit`), notificação, billing, cache, storage, rate limit etc. Consulte `.ai/brain/SeedGrid/Extensions/Indice.md` e configure pelas propriedades documentadas. Código próprio só quando nenhuma extension cobre, com a justificativa na entrega.
+- **BE-61.** Dado pessoal (CPF, telefone, e-mail, endereço, data de nascimento, nome quando identifica a pessoa) usa o `seedgrid-privacy`: campo `String` com `@Convert(converter = EncryptedFieldAttributeConverter.class)` e `@EncryptedField`, coluna `length = 512`; se a busca por igualdade for necessária, `@EncryptedField(searchField = "<campo>Hash", normalize = ...)` com a coluna irmã `<campo>_hash` (`length = 64`) e a consulta feita pelo hash (`EncryptedFieldSearch#hashForSearch`, com a **mesma** normalização da anotação). Entidade com campo cifrado leva `@EntityListeners(EncryptedFieldListener.class)`.
+- **BE-62.** A cifra de campo é opt-in: o host liga `seedgrid.privacy.encryption.enabled=true` e fornece `seedgrid.privacy.crypto.key` e `seedgrid.privacy.search.key` (Base64, 32 bytes) por segredo/variável de ambiente, nunca em arquivo versionado.
+- **BE-63.** Dado pessoal **não** vai em claro para auditoria, log, exportação ou resposta de erro: use `@PersonalData`/`@MaskRule` (e `remove = true` para senha e segredos).
+- **BE-64.** Criação, alteração e exclusão de entidades de negócio são auditadas com `@Audit` (`entityFqcn`, `operation`, `description`) no método de serviço, dentro de `@Transactional`.
+- **BE-65.** Endpoints protegidos com as anotações de segurança do Quarkus (`@Authenticated`, `@RolesAllowed`, `@PermissionsAllowed`) e permissões registradas conforme a extension `security`; a UI esconder um botão não substitui a checagem no back.
+- **BE-66.** Cadastros novos seguem a skill `seedgrid-backend-crud`.
+
+## Ao terminar
+
+- **BE-50.** Revise se não sobrou nada (classes e arquivos que deveriam ser removidos) e liste os TODO que ficaram no projeto.

package/seedgridKB/SeedGrid/Toolkit/rules/coordenacao.md

@@ -0,0 +1,39 @@
+---
+description: "Fluxo de coordenação da sessão principal: quando coordenar, escolher papéis, delegar e consolidar. Leia antes de qualquer tarefa não trivial."
+---
+# Coordenação de tarefas
+
+Regras para a sessão principal (o coordenador) no Claude Code ou no Codex. Elas orientam o comportamento; não são garantias técnicas do instalador.
+
+## Quando coordenar
+
+- Tarefas triviais (ajuste pontual, pergunta, mudança de uma linha) podem ser feitas diretamente, sem papéis.
+- Todas as outras seguem o fluxo abaixo. O diagrama e a divisão de papéis estão em [fluxo de trabalho](../references/fluxo-de-trabalho.md).
+
+## Fluxo
+
+1. **Acionar o `arquiteto` primeiro.** Passe o pedido do usuário como foi escrito. Ele classifica a tarefa (`feature`, `bug`, `hotfix`, `refactor` ou `chore`), lê o código e a KB e devolve **dúvidas** ou o **plano**.
+2. **Resolver as dúvidas.** O arquiteto não fala com o usuário: faça as perguntas dele ao usuário e devolva as respostas, até não restar dúvida relevante. Dúvida pequena vira premissa declarada.
+3. **Aprovar o plano.** Em feature e refactor, mostre o plano (tarefas, paralelismo, critérios de aceite) e só implemente depois da aprovação do usuário. Em hotfix e bug claros, o plano é mínimo e segue direto.
+4. **Delegar com contexto completo.** Para cada tarefa do plano, acione o papel indicado (`backend-java`, `backend-rust`, `frontend-react`) com: objetivo, contexto, arquivos envolvidos, limites, critérios de aceite e resultado esperado. Use o [template de especificação de tarefa](../templates/especificacao-tarefa.md) quando ajudar. Consulte o [índice de papéis](../agents/index.md) e leia a definição completa apenas dos papéis acionados.
+5. **Paralelizar com cuidado.** Rode em paralelo somente o que o plano marcou como independente. Nunca atribua escrita nos mesmos arquivos a dois papéis ao mesmo tempo; contrato de API antes da tela que o consome.
+6. **Receber e encaminhar.** Confira cada entrega (ver [formato de entrega](formato-entrega.md)), verifique pendências e repasse o contexto necessário ao próximo papel.
+7. **Revisar e testar.** Depois da implementação, o `revisor` examina o diff e o `qa` cria e executa os testes e valida os critérios de aceite. Achados e falhas voltam ao implementador responsável. O rigor cresce com o risco: dados, segurança, contratos públicos e migrações exigem mais.
+8. **Consolidar.** Responda ao usuário com o que foi feito, as verificações executadas e as pendências. Publicar, fazer deploy ou dar push continua sendo decisão do usuário.
+
+### Hotfix
+
+Triagem rápida do `arquiteto` (causa, menor correção segura, risco), correção mínima, teste de regressão do `qa` e revisão enxuta. Sem refactor: o que aparecer no caminho vira pendência.
+
+## Delegação disponível
+
+- **Modo shared:** use o mecanismo de subagentes da ferramenta (quando houver), passando a definição do papel como instrução. Se não houver subagentes, aplique o papel na própria sessão, um de cada vez, e **informe ao usuário** que a delegação não estava disponível.
+- **Modo native:** os papéis também estão registrados como subagentes nativos com os mesmos ids. Prefira-os. Se a ferramenta não os reconhecer, siga o modo shared e informe isso.
+
+## Fluxos obrigatórios
+
+Se o projeto exigir um fluxo obrigatório (por exemplo, revisão antes de todo commit), declare-o em `.ai/local/` (veja [personalização local](personalizacao-local.md)). Sem declaração explícita, o fluxo acima é uma recomendação.
+
+## Artefatos
+
+Os templates em `.ai/templates/` são modelos distribuídos pelo toolkit. Especificações, decisões e relatórios produzidos em tarefas reais pertencem ao projeto: salve-os onde o projeto definir (por exemplo, `docs/`), nunca dentro de `.ai/templates/`, `.ai/agents/` ou `.ai/rules/`, que são gerenciados e podem ser atualizados.

package/seedgridKB/SeedGrid/Toolkit/rules/formato-entrega.md

@@ -0,0 +1,29 @@
+---
+description: "Formato obrigatório da entrega de cada papel (resultado, arquivos, verificações, pendências). Leia ao delegar ou ao encerrar o trabalho de um papel."
+---
+# Formato de entrega dos papéis
+
+Todo papel encerra o trabalho com uma entrega neste formato. Não inclua raciocínio interno; descreva fatos verificáveis.
+
+```markdown
+## Resultado
+O que foi feito, em 1 a 5 frases.
+
+## Arquivos alterados
+- caminho/do/arquivo — o que mudou (ou "nenhum")
+
+## Verificações executadas
+- comando ou inspeção — resultado (passou/falhou/não executado e por quê)
+
+## Problemas pendentes
+- item pendente, risco ou dúvida (ou "nenhum")
+
+## Contexto para a próxima etapa
+Informações de que o próximo papel ou o coordenador precisa.
+```
+
+Regras:
+
+- Relate falhas como falhas. Verificação não executada deve aparecer como "não executada", com o motivo.
+- Não declare algo pronto sem ter verificado; se não foi possível verificar, diga isso.
+- Mantenha a entrega curta. Detalhes extensos vão para arquivos referenciados.