@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/Toolkit/rules/frontend-seedgrid.md

@@ -0,0 +1,47 @@
+---
+description: "Padrões obrigatórios do front-end SeedGrid: usar sempre os componentes @seedgrid/fe-components e o componente certo para cada tipo de dado (telefone, CPF, CNPJ, e-mail, moeda...). Leia antes de criar ou alterar qualquer tela React."
+---
+# Padrões do front-end SeedGrid
+
+Regras **obrigatórias** para telas React que usam `@seedgrid/fe-components`. Cada regra tem um id (`FE-nn`) para citar em revisões (`seedgrid-review`). Para detalhes de props e exemplos, consulte a KB: comece por `.ai/brain/SeedGrid/SeedGrid-components/Indice.md` e abra só a nota do grupo necessário.
+
+## Componentes SeedGrid primeiro
+
+- **FE-01.** Use componentes SeedGrid para toda a interface. Só use elemento HTML cru (`<input>`, `<button>`, `<select>`, `<textarea>`, `<table>`) se **não existir** componente SeedGrid equivalente; nesse caso, justifique em comentário curto.
+- **FE-02.** Antes de criar um componente novo, procure no índice da KB se já existe um que atenda. Não reimplemente o que o SeedGrid já oferece.
+- **FE-03.** Não invente props. Confirme nome e tipo na nota `API` do grupo; se não achar, diga que não encontrou.
+
+## Componente certo para cada dado
+
+Nunca use `SgInputText` (nem `<input>` com máscara própria) para um dado que tem componente específico:
+
+| Dado | Componente |
+| --- | --- |
+| **FE-10.** Telefone, celular, WhatsApp | `SgInputPhone` |
+| **FE-11.** CPF | `SgInputCPF` |
+| **FE-12.** CNPJ | `SgInputCNPJ` |
+| **FE-13.** Campo que aceita CPF **ou** CNPJ | `SgInputCPFCNPJ` |
+| **FE-14.** E-mail | `SgInputEmail` |
+| **FE-15.** CEP / código postal | `SgInputPostalCode` |
+| **FE-16.** Senha | `SgInputPassword` |
+| **FE-17.** Valor monetário | `SgInputCurrency` (`currency="BRL"`, `decimals={2}`) |
+| **FE-18.** Número (inteiro ou decimal não monetário) | `SgInputNumber` |
+| **FE-19.** Data / data de nascimento | `SgInputDate` / `SgInputBirthDate` |
+| **FE-20.** Busca remota com debounce | `SgInputTextSearch` |
+| **FE-21.** Código de uso único (OTP) | `SgInputOTP` |
+| **FE-22.** Sim/não | `SgToggleSwitch` |
+| **FE-23.** Uma opção de lista fixa ou carregada uma vez | `SgCombobox` (lista remota ou grande: `SgAutocomplete`) |
+| **FE-24.** Texto longo | `SgInputTextArea` |
+
+## Estrutura e feedback
+
+- **FE-30.** Botões: `SgButton`. Layout: `SgStack`, `SgGrid`, `SgCard` etc. no lugar de `div` com flex/grid escritos à mão.
+- **FE-31.** Tabelas de dados: `SgDatatable`, paginada e ordenada no servidor quando a lista puder crescer.
+- **FE-32.** Confirmação de ação destrutiva: `SgConfirmationDialog`, nunca `window.confirm`/`alert`.
+- **FE-33.** Avisos ao usuário: `toast` (ou `sgWhistle`), não `alert`.
+- **FE-34.** Carregamento: `SgSkeleton` (tabelas com skeleton em formato de tabela).
+- **FE-35.** Textos para o usuário em linguagem de negócio, não detalhe técnico.
+
+## CRUDs
+
+Telas de cadastro seguem a skill `seedgrid-crud` (páginas `*_list` e `*_edit`, `publicId` nas URLs, proxy em `app/api/...`). Nunca exponha o `id` numérico ao navegador quando houver `publicId`.

package/seedgridKB/SeedGrid/Toolkit/rules/personalizacao-local.md

@@ -0,0 +1,22 @@
+---
+description: "Como personalizar o toolkit sem gerar conflito: usar .ai/local/, que nunca é alterado pelo seedgrid-ai. Leia antes de editar qualquer arquivo de .ai/."
+---
+# Personalização local
+
+O conteúdo em `.ai/agents/`, `.ai/rules/`, `.ai/templates/` e `.ai/references/` é gerenciado pelo `seedgrid-ai` e pode ser substituído em atualizações. Não edite esses arquivos: alterações locais geram conflito no próximo `update`.
+
+Personalize em `.ai/local/`, que o toolkit nunca cria, altera ou remove:
+
+| Arquivo sugerido | Uso |
+| --- | --- |
+| `.ai/local/projeto.md` | Stack, comandos de build/teste, convenções e arquitetura do projeto |
+| `.ai/local/fluxos.md` | Fluxos obrigatórios (ex.: revisão antes de merge) |
+| `.ai/local/papeis/<id>.md` | Complementos a um papel do catálogo (mesmo id) |
+
+Precedência ao ler instruções:
+
+1. Pedido explícito do usuário na sessão.
+2. `.ai/local/` (específico do projeto).
+3. Regras compartilhadas em `.ai/rules/` e papéis em `.ai/agents/`.
+
+Se `.ai/local/` não existir, siga apenas as regras compartilhadas. Ao ler um papel, verifique se existe `.ai/local/papeis/<id>.md` e aplique o complemento.

package/seedgridKB/SeedGrid/Toolkit/skills/planejar-mudanca/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: planejar-mudanca
+description: Planeja uma mudança de código antes de implementar - entende o objetivo, lê o código afetado, define critérios de aceite, divide em tarefas e identifica riscos. Use quando a tarefa atravessa vários arquivos ou camadas, é ambígua ou envolve decisão de arquitetura.
+metadata:
+  toolkit: seedgrid-ai
+---
+
+# Planejar mudança
+
+Produza um plano curto e verificável antes de alterar código não trivial.
+
+## Passos
+
+1. **Objetivo.** Reescreva o pedido em uma frase e liste as restrições explícitas. Se faltar informação indispensável, pergunte antes de seguir.
+2. **Reconhecimento.** Leia os arquivos que serão afetados e o código que os chama. Anote convenções do projeto (estrutura, testes, nomes). Não presuma estrutura que não viu.
+3. **Critérios de aceite.** Escreva de 2 a 6 critérios verificáveis (comportamento observável, testes, comandos).
+4. **Abordagem.** Descreva a solução escolhida e, se houver escolha relevante, ao menos uma alternativa e por que foi descartada.
+5. **Tarefas.** Divida em tarefas pequenas com: papel responsável, arquivos prováveis, dependências e ordem. Marque o que pode ser paralelo; nunca coloque dois responsáveis escrevendo no mesmo arquivo ao mesmo tempo.
+6. **Riscos e verificação.** Liste riscos (dados, segurança, contratos, desempenho, migração) e o nível de revisão e validação proporcional.
+
+## Saída
+
+Use o modelo [assets/especificacao-tarefa.md](assets/especificacao-tarefa.md) para cada tarefa delegada. Para o plano geral, responda com:
+
+```markdown
+## Objetivo
+## Critérios de aceite
+## Abordagem
+## Tarefas
+| # | Tarefa | Papel | Arquivos | Depende de | Paralela? |
+## Riscos e verificação
+## Dúvidas
+```
+
+## Cuidados
+
+- Tarefas triviais não precisam de plano formal: implemente direto e diga isso.
+- O plano é uma saída do projeto; não o salve dentro das pastas gerenciadas pelo toolkit (`.ai/templates/`, `.ai/rules/`, `.ai/agents/`).

package/seedgridKB/SeedGrid/Toolkit/skills/revisar-codigo/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: revisar-codigo
+description: Revisa um diff ou conjunto de arquivos alterados procurando defeitos de lógica, segurança, tratamento de erros, compatibilidade e testes ausentes, com achados priorizados e cenário concreto de falha. Use após implementar uma mudança substancial ou quando pedirem revisão de código.
+metadata:
+  toolkit: seedgrid-ai
+---
+
+# Revisar código
+
+Encontre problemas reais e verificáveis; evite comentários de estilo sem impacto.
+
+## Passos
+
+1. **Escopo.** Obtenha o diff (por exemplo, `git diff` ou `git diff <base>...HEAD`) e o objetivo da mudança. Sem diff disponível, peça a lista de arquivos alterados.
+2. **Contexto.** Leia o código ao redor de cada trecho alterado e os pontos que o chamam.
+3. **Análise.** Percorra o [checklist](references/checklist.md). Para cada suspeita, construa um cenário concreto: entrada/estado → comportamento errado.
+4. **Filtro.** Descarte suspeitas que não sustentam um cenário concreto. Não reporte preferências pessoais como defeitos.
+5. **Verificações somente leitura.** Se útil, rode testes ou lint existentes para confirmar um achado. Não altere arquivos.
+
+## Saída
+
+```markdown
+## Achados
+### [bloqueante|importante|sugestão] Título curto
+- Local: caminho/arquivo:linha
+- Cenário: entrada/estado → resultado incorreto
+- Correção sugerida: uma ou duas frases
+
+## Sem achados em
+Áreas revisadas sem problemas relevantes.
+```
+
+Se não houver achados bloqueantes, diga isso explicitamente.

package/seedgridKB/SeedGrid/Toolkit/skills/revisar-codigo/references/checklist.md

@@ -0,0 +1,25 @@
+# Checklist de revisão
+
+## Correção
+- Condições de borda: vazio, nulo, limites numéricos, listas grandes, fuso horário, codificação de texto.
+- Caminhos de erro: exceções engolidas, retornos ignorados, mensagens que escondem a causa.
+- Estado: mutações compartilhadas, ordem de inicialização, cache inválido.
+- Concorrência: condições de corrida, transações, idempotência em reprocessamento.
+
+## Segurança
+- Entrada não confiável chegando a SQL, shell, caminhos de arquivo, HTML ou desserialização.
+- Autorização verificada no servidor para cada operação, não apenas na interface.
+- Segredos em código, logs, mensagens de erro ou arquivos versionados.
+- Dados pessoais expostos além do necessário.
+
+## Contratos e compatibilidade
+- APIs públicas, eventos, esquemas e formatos de arquivo alterados sem versionamento ou migração.
+- Migrações de banco reversíveis ou com plano de recuperação.
+
+## Testes
+- O comportamento novo tem teste que falharia sem a mudança?
+- Casos de erro e de borda cobertos na medida do risco.
+
+## Manutenção
+- Duplicação de lógica existente no projeto.
+- Nomes e estrutura coerentes com o restante do código.

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-backend-crud/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: seedgrid-backend-crud
+description: Cria ou padroniza um CRUD de back-end Java com as extensions SeedGrid - entidade com BaseEntity e publicId, migration Flyway, campos pessoais cifrados com seedgrid-privacy (LGPD), auditoria com @Audit, permissões, controller com RestControllerPath, DTOs e testes. Use ao criar uma entidade nova com API, ou ao adicionar campo pessoal, auditoria ou permissão a um cadastro existente.
+metadata:
+  toolkit: seedgrid-ai
+---
+
+# CRUD de back-end SeedGrid
+
+Monta um cadastro completo no padrão `.ai/rules/backend-java-seedgrid.md` (regras `BE-nn`), reaproveitando as extensions SeedGrid. Antes de começar, leia essa rule e, para cada extension usada, só a nota do grupo na KB (`.ai/brain/SeedGrid/Extensions/Indice.md` → `privacy`, `audit`, `commons`, `security`). Não invente propriedades nem anotações: confirme na KB ou no código.
+
+## Passos
+
+1. **Levantar.** Entidade, campos, quais são **dados pessoais** (CPF, telefone, e-mail, endereço, nascimento), quais precisam de **busca por igualdade**, permissões e se há relacionamentos. Leia um cadastro existente do projeto e copie as convenções dele. Dúvida de regra de negócio: pergunte.
+2. **Entidade** (`entities/`): estenda a base do `seedgrid-commons` (BE-23). **Host com Panache:** `BaseEntityPanache` (`id`, `publicId`, datas, usuário de criação/alteração; sem `active`). **Lib** (JPA puro, sem Panache, BE-21): `BaseEntity` (as mesmas colunas mais `active`). Se o projeto já tem cadastros, siga a base que eles usam. Relacionamentos usam o `id`; o `publicId` é só para fora (BE-30).
+3. **Campos pessoais** (BE-61): para cada um, `@Convert(converter = EncryptedFieldAttributeConverter.class)` + `@EncryptedField`, coluna `length = 512`. Com busca: `@EncryptedField(searchField = "cpfHash", normalize = SearchNormalization.CANONICAL)` (e-mail: `EMAIL`) e o campo irmão `cpfHash` (`length = 64`). Adicione `@EntityListeners(EncryptedFieldListener.class)` na entidade. Marque os mesmos campos com `@PersonalData` para o mascaramento na auditoria (BE-63).
+4. **Migration Flyway** (BE-20, BE-22, BE-24): tabela com `id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`, as colunas da base escolhida (`public_id`, `created_at`, `updated_at` como `timestamptz`, `create_user_public_id`, `update_user_public_id`, e `active` só no `BaseEntity`; a lib não traz migrations), colunas cifradas com `VARCHAR(512)` e de hash com `VARCHAR(64)`, e `CREATE UNIQUE INDEX idx_<tabela>_public_id ON <tabela>(public_id)`. A pasta segue `db/migration/<projeto>`.
+5. **Repository** (`repositories/`, JPA puro em libs; Panache só em hosts, BE-21). Busca por campo cifrado usa o hash: `CryptoProvider.getSecureSearch().hashForSearch(valor, <mesma normalização>)`.
+6. **Service** (`services/`, injeção por construtor, BE-10): regras de negócio e exceptions tipadas (BE-11). Criar, alterar e excluir com `@Transactional` e `@Audit(entityFqcn = "...", operation = AuditOperationEnum.CREATE|UPDATE|DELETE, description = "...")` (BE-64). Para UPDATE/DELETE, o repository precisa expor `findByIdOptional` (é por ele que o `@Audit` captura o "antes").
+7. **DTOs** (`dtos/`, BE-05): `...Request` só com o necessário, `...Response` raso, com `publicId` e **sem** `id`. Nada de dado pessoal em claro em respostas de erro ou log.
+8. **Controller** (`controllers/`, BE-03, BE-31): primeiro acrescente a seção do recurso em `RestControllerPath` (base, `..._BY_PUBLIC_ID`, `..._FULL`; o controller usa base e sub-paths, o teste usa os `_FULL`); `GET` paginado (`page`, `size`, `sortField`, `sortOrder`, com `LIKE` por prefixo, BE-32), `GET` por `publicId`, `POST`, `PUT`, `DELETE`. Proteja com `@PermissionsAllowed("<ENTIDADE>_READ|CREATE|EDIT|DELETE")` (ou `@RolesAllowed`), conforme a extension `security` (BE-65), e registre as permissões como o projeto faz.
+9. **Testes** (BE-40, BE-41): unitário do service e de integração do controller com Testcontainers + PostgreSQL, cobrindo CRUD, validação, permissão negada, **dado pessoal gravado cifrado** (consulta direta na coluna), busca pelo hash e registro de auditoria sem dado pessoal em claro. Vários asserts: `assertAll`.
+10. **Fechar** (BE-50): rode build e testes, remova o que sobrou e liste os TODO.
+
+## Cuidados
+
+- Cifra de campo é opt-in: exige `seedgrid.privacy.encryption.enabled=true`, `seedgrid.privacy.crypto.key` e `seedgrid.privacy.search.key` fornecidos por variável de ambiente ou segredo, nunca versionados (BE-62). Sem a chave configurada, a leitura de valor já cifrado falha.
+- A tela correspondente segue a skill `seedgrid-crud`; menu e permissão da tela, a `seedgrid-new-screen`.
+- Para conferir o resultado contra o padrão, use `seedgrid-review back`.

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-bump/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: seedgrid-bump
+description: Sobe a versão do projeto inteiro de uma vez, mantendo a mesma versão no back (pom.xml) e em todos os apps de front (package.json), e no que mais a exibir. Use quando pedirem bump, nova versão ou release do projeto (patch, minor, major ou uma versão informada). Não altera dependências.
+metadata:
+  toolkit: seedgrid-ai
+---
+
+# Bump de versão do projeto
+
+Regra: **o projeto inteiro tem uma única versão**. Back e todos os fronts (por exemplo `backend/`, `admin/`, `frontend/`) saem sempre com o mesmo número. Esta skill muda **a versão do próprio projeto**; não sobe versões de dependências nem de extensions SeedGrid.
+
+## Passos
+
+1. **Descobrir a versão atual e onde ela está.** Leia a versão do `pom.xml` do back (a do projeto, não a de `<dependency>` nem `<parent>`) e o campo `version` de cada `package.json` de aplicação (ignore `node_modules` e pacotes que não sejam do projeto). Procure também onde a versão aparece como texto: `application.properties` (`app.build.version=${APP_VERSION:dev}` lê da variável de ambiente `APP_VERSION`, então não é editado), `Dockerfile`, `docker-compose`, README e changelog. Se as versões atuais já divergem entre si, **pare e mostre a divergência** antes de seguir.
+2. **Definir a nova versão** `X.Y.Z` (semver) a partir do pedido: `patch` (correção), `minor` (funcionalidade compatível), `major` (quebra de compatibilidade) ou um número informado. Sem indicação, sugira com base nas mudanças desde a última versão e confirme com o usuário.
+3. **Mostrar o plano** (arquivo: versão atual → nova) e só então alterar.
+4. **Aplicar** a mesma `X.Y.Z` em todos os arquivos encontrados: `pom.xml` do back (sem sufixo `-SNAPSHOT` em release; se o projeto usa `-SNAPSHOT` no desenvolvimento, pergunte se quer voltar para o próximo `-SNAPSHOT` depois), cada `package.json` de aplicação e os textos que repetem a versão. Mantenha a formatação dos arquivos; mude só a versão. Em `package.json` com lockfile, atualize também o campo de versão do próprio projeto no lockfile quando existir.
+5. **Verificar.** Rode build e testes de cada parte (`mvn -q verify` ou o comando do projeto, e `build`/`lint`/testes dos fronts) e confirme que nenhuma versão ficou para trás com uma busca pela versão antiga.
+6. **Registrar.** Atualize o changelog se o projeto tiver um, com o que mudou desde a versão anterior.
+7. **Entregar.** Liste os arquivos alterados e os resultados dos comandos. Commit, tag e push **só se o usuário pedir**; sugira a mensagem e a tag (`vX.Y.Z`).
+
+## Regras
+
+- Nunca altere versões de `<dependency>`, `<parent>`, BOMs, extensions SeedGrid ou pacotes `@seedgrid/*`; atualização de dependências é outra tarefa.
+- Não publique artefatos, não faça deploy e não envie nada a serviços externos.
+- Se houver mudanças não commitadas no repositório, avise antes de alterar.

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-crud/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: seedgrid-crud
+description: Create or refactor SeedGrid CRUD flows in a Next.js app built on the SeedGrid boilerplate, using the project standard of separate `*_list` and `*_edit` pages, `publicId` routing, Next API proxy routes, and SeedGrid components. Use when you need to build or standardize an entity CRUD (users, roles, plans, API keys, audit screens, etc.) with `SgDatatable`, `SgInputTextSearch`, permissions, user-facing copy, and menu/breadcrumb integration.
+---
+
+# SeedGrid CRUD
+
+Build SeedGrid CRUDs with the structure of the boilerplate's `users` and `roles` screens
+(`app/security/users/user_list`, `user_edit`; `app/security/roles/role_list`, `role_edit`). Keep the
+pages user-facing, consistent, and navigable through `SgMenu` and `SgBreadcrumb`.
+
+Read the existing screens of the project before writing a new one and copy their conventions (imports,
+hooks, helpers). The names below (`Shell`, `useSavedToast`, `ListLoadError`, `adminProxyClient`, ...)
+are the boilerplate's own; if the project names them differently, use the project's equivalents.
+
+To register the menu item, icon and permission of a new screen, use the `seedgrid-new-screen` skill.
+
+## Workflow
+
+1. Identify the entity, its permissions, and the backend endpoints that already exist (do not invent
+   endpoints; check the backend or the SeedGrid knowledge base in `.ai/brain/`).
+2. Create the pages under `app/<module>/<entity>/`:
+   - `<entity>_list/page.tsx`: table, search, pagination, sort and actions
+   - `<entity>_edit/page.tsx`: create/update in a dedicated page
+   - `page.tsx`: `redirect("/<module>/<entity>/<entity>_list")`
+3. Prefer `publicId` in URLs and route params. Keep the numeric `id` internal only.
+4. Use Next API routes in `app/api/<module>/<entity>/` as server-side proxies to the backend.
+5. Use SeedGrid components for the whole UI structure.
+6. Write user-facing labels and descriptions. Do not expose technical implementation details in the UI.
+7. Validate navigation, permission gates, and loading/error states.
+
+## Required Patterns
+
+- Use the list/edit split described in `references/patterns.md`.
+- Use `publicId` routing and proxy conventions from `references/routing.md`.
+- Use `SgInputTextSearch` as the standard remote-search input.
+- Use the checklist in `references/checklist.md` before closing the task.
+
+## Required UI Components
+
+- Layout/navigation: `Shell`, `SgMenu`, `SgBreadcrumb`, `SgCard`, `SgStack`, `SgGrid`
+- Listing: `SgDatatable`, `DatatableSkeleton` (table-shaped loading), `StatusBadge`, `ListLoadError`
+- Search: `SgInputTextSearch`
+- Destructive confirmation: `SgConfirmationDialog`
+- Feedback: `toast` from `@seedgrid/fe-components`
+- Edit: `SgInputText`, `SgInputNumber`, `SgInputCurrency`, `SgInputPassword`, `SgInputDate`, `SgToggleSwitch`, `SgButton` as applicable
+
+## Input Type Standard
+
+Never use `SgInputText` (or a raw text input with `inputMode`) for numeric or
+monetary fields — it lets the user type letters and the value only fails at
+submit. Match the input component to the data type:
+
+- **Monetary value** (price, fee, overage, balance) → `SgInputCurrency`
+  with `currency="BRL"`, `decimals={2}`, `minValue={0}` (or `allowNegative`
+  when negatives are valid). Read it back with `parseDecimalInput` from
+  `@/lib/format` (handles the pt-BR comma).
+- **Integer count** (requests, users, quantity, day-of-month) → `SgInputNumber`
+  with `decimals={0}` and an appropriate `minValue`. Parse with
+  `Number.parseInt(value, 10)`.
+- **Decimal non-money** (rates, factors) → `SgInputNumber` with the needed
+  `decimals` and `parseDecimalInput`.
+- **Date** → `SgInputDate`. **Free text** → `SgInputText`.
+
+Both `SgInputCurrency` and `SgInputNumber` are controlled via
+`inputProps={{ value }}` and report back a string through `onChange`. Keep the
+form state as the raw string and convert only on submit.
+
+## Search Standard
+
+For searchable lists:
+
+- Use `SgInputTextSearch` by name, not an ad-hoc input.
+- Apply minimum 3 characters.
+- Use debounce and distinct semantics.
+- Cancel in-flight requests when the query changes (an RxJS `Subject` + `switchMap`, with an
+  `AbortController` aborted on unsubscribe).
+- Keep the request server-side paginated and sortable.
+
+### Server-side `LIKE` must be a PREFIX match
+
+The backend that feeds the `SgDatatable` binds the search term as `term + "%"`, never
+`"%" + term + "%"`. A leading wildcard makes the database unable to use the column index, so every
+keystroke turns the list query into a full table scan — the cost grows with the table, exactly where
+it hurts most.
+
+```java
+// CORRECT — uses the index
+queryObj.setParameter("term", query + "%");
+// WRONG — scans the whole table
+queryObj.setParameter("term", "%" + query + "%");
+```
+
+The JPQL/Panache clause itself does not change (`lower(u.name) LIKE :term`); only the bound value
+does. Trade-off accepted deliberately: the user finds "AVENTAL IMPERIO" by typing `avental`, not by
+typing `imperio`.
+
+Equality (`= :param`) stays the right call for codes/IDs and for closed option lists (the filter fed
+by a `DISTINCT`, rendered as `SgCombobox`/`SgAutocomplete`), where no `LIKE` is needed at all.
+
+### Critical RxJS pitfall (incremental search must keep working)
+
+The debounce in `SgInputTextSearch` lives inside an `useEffect` subscription. Do
+**not** put the `onSearchChange`/`onChange` callbacks in that effect's dependency
+array. Parent pages recreate those callbacks on every render (and each keystroke
+triggers a parent re-render via `setRawSearch`), so a callback-dependent effect
+tears down and re-subscribes on every keystroke. The cleanup `unsubscribe()`
+cancels the pending `debounceTime` timer, so the debounced value never reaches
+`onSearchChange` and the search silently never fires.
+
+Correct pattern: hold the latest callback in a `useRef`, keep the subscription
+effect dependencies limited to stable values (`changes$`, `debounceMs`,
+`minChars`), and call `onSearchChangeRef.current(...)` inside the subscriber.
+
+```ts
+const onSearchChangeRef = useRef(onSearchChange);
+onSearchChangeRef.current = onSearchChange;
+
+useEffect(() => {
+  const subscription = changes$
+    .pipe(map((raw) => raw.trim()), debounceTime(debounceMs), distinctUntilChanged())
+    .subscribe((next) => {
+      if (next.length === 0 || next.length >= minChars) {
+        onSearchChangeRef.current(next);
+      }
+    });
+  return () => subscription.unsubscribe();
+}, [changes$, debounceMs, minChars]); // never include the callbacks here
+```
+
+The parent does not need `useCallback` for this to work — the component must be
+robust to recreated callbacks on its own.
+
+## List Toolbar Layout Standard
+
+The list header (search + `Novo` action) must not split the row into two equal
+halves. The search is the primary control and should dominate the width.
+
+- Lay the toolbar out with `SgStack direction="row" align="end" gap={12} wrap`
+  (not a 50/50 `SgGrid`).
+- Wrap `SgInputTextSearch` in a growing container so it takes the remaining
+  space: `<div style={{ flex: 1, minWidth: 240 }}>`.
+- Keep the create button compact: short label (`Novo`, not `Novo usuario`) and
+  `size="md"`.
+- The button is shorter than the input by default. `SgInputText` is `h-11`
+  (44px); `SgButton size="md"` is `h-10` (40px). Match them with
+  `style={{ height: 44 }}` so the button lines up with the field.
+- `align="end"` keeps the button aligned to the input's baseline (the input has
+  a label above it).
+- `wrap` lets them stack on narrow viewports.
+
+```tsx
+<SgStack align="end" direction="row" gap={12} wrap>
+  <div style={{ flex: 1, minWidth: 240 }}>
+    <SgInputTextSearch id="<entity>-search" label="Busca por nome" ... />
+  </div>
+  {canCreate ? (
+    <SgButton
+      appearance="outline"
+      label="Novo"
+      leftIcon={<Plus size={16} />}
+      severity="secondary"
+      size="md"
+      style={{ height: 44 }}
+      onClick={() => router.push("/<module>/<entity>/<entity>_edit")}
+    />
+  ) : null}
+</SgStack>
+```
+
+## Destructive Action Standard
+
+Delete (and any irreversible action) must use `SgConfirmationDialog`, never the
+native `window.confirm`. The native dialog is the wrong, inconsistent popup.
+
+- Drive the dialog with controlled state: a single `entityToDelete` state opens
+  it (`open={entityToDelete !== null}`).
+- The row action only sets state (`onClick={() => setEntityToDelete(row)}`); it
+  does not perform the delete.
+- Run the request in `onConfirm`. Keep the dialog open during the async call
+  with `closeOnConfirm={false}`, show progress on the confirm button
+  (`label: deleting ? "Excluindo..." : "Excluir"`, `disabled: deleting`), and
+  clear the state in a `finally` to close it.
+- Use `severity="danger"`, a user-facing title and message that names the entity
+  and warns the action cannot be undone.
+- After deleting the last row on a page, step `page` back by one (mirror the
+  existing list paging logic).
+
+```tsx
+<SgConfirmationDialog
+  open={entityToDelete !== null}
+  severity="danger"
+  title="Excluir <entity>"
+  message={entityToDelete ? `Tem certeza que deseja excluir "${entityToDelete.name}"? Esta acao nao pode ser desfeita.` : ""}
+  confirmButton={{ label: deleting ? "Excluindo..." : "Excluir", severity: "danger", disabled: deleting }}
+  cancelButton={{ label: "Cancelar", disabled: deleting }}
+  closeOnConfirm={false}
+  onConfirm={() => void confirmDelete()}
+  onCancel={() => setEntityToDelete(null)}
+/>
+```
+
+## Permission Standard
+
+- Hide menu entries if the user lacks view permission.
+- Hide create/edit/delete actions if the user lacks the corresponding permission.
+- If the page is opened without permission, render a proper blocked state (a `Shell` with a
+  "Sem permissao" card) instead of failing.
+- Permissions are checked in the UI **and** enforced by the backend; the UI gate is only for
+  usability.
+
+## Error And Fallback Standard
+
+- A load failure must never look like an empty list. Keep the error in its own state and render
+  `ListLoadError` (with a retry) **instead of** the table; do not fall through to "Nenhum registro
+  encontrado".
+- If the backend is unavailable or the session is invalid, proxy routes return the real error status
+  as `problem+json` (use the project's `problemResponse`), never a `200` with an empty page.
+- Show the message from the backend with `extractApiErrorMessage`, falling back to a generic
+  user-facing text.
+- Avoid uncaught runtime failures: every request has a `catch` that ends in a visible state.

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-crud/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SeedGrid CRUD"
+  short_description: "Padrao CRUD SeedGrid"
+  default_prompt: "Use $seedgrid-crud to create a SeedGrid CRUD with list/edit pages, publicId routing, and SgInputTextSearch."

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-crud/references/checklist.md

@@ -0,0 +1,31 @@
+# Delivery Checklist
+
+Before finishing a CRUD task, verify:
+
+- Menu entry exists only if the user has view permission
+- `SgMenu` and `SgBreadcrumb` navigate to valid routes
+- There are two pages, `*_list` and `*_edit`, plus a `page.tsx` that redirects to the list
+- `SgInputTextSearch` is used for remote search when the list is searchable
+- Search uses min 3 chars and cancels in-flight requests
+- `SgInputTextSearch` keeps its RxJS subscription stable: callbacks live in a `useRef`, never in the subscription effect's deps (otherwise per-keystroke re-subscribes cancel the debounce and search stops firing)
+- Typing in the search field actually triggers requests (verify incremental search end-to-end, not just that it renders)
+- Backend `LIKE` filters bind `term + "%"` (prefix), never `"%" + term + "%"`
+- `SgDatatable` is server-paginated and sortable
+- Column layout persistence uses the project environment pattern when available
+- Edit and delete actions are permission-gated
+- Delete uses a controlled `SgConfirmationDialog` (`severity="danger"`), never `window.confirm`; request runs in `onConfirm` with `closeOnConfirm={false}` and a busy/disabled confirm button
+- List toolbar uses `SgStack` row with the search growing (`flex: 1`) and a compact `Novo` button, height-matched to the input (`style={{ height: 44 }}`), not a 50/50 `SgGrid`
+- `publicId` is used in the edit URL and in the detail/update/delete proxy routes
+- Edit page uses SeedGrid form components
+- Numeric and monetary fields use the right input type, never `SgInputText`: `SgInputCurrency` (`currency="BRL"`, `decimals={2}`) for money; `SgInputNumber` (`decimals={0}`) for integer counts. Verify the field rejects letters at type-time, not only at submit
+- Copy is user-facing, not technical
+- Table loading uses a table-shaped skeleton (`DatatableSkeleton`: header + body rows, column count matching the table), not a single rectangle; row count is capped (e.g. `Math.min(pageSize, 8)`). Edit/form pages may still use a rectangular `SgSkeleton`
+- A list load failure shows `ListLoadError` (with retry) instead of the table, never an empty list
+- Proxy routes return the real error status as `problem+json` for invalid session and connection failure, without crashing the page
+- TypeScript passes
+
+Recommended verification command, in the folder of the Next.js app (`frontend/` in the boilerplate):
+
+```bash
+npx tsc --noEmit --pretty false
+```