@seedgrid/ai-toolkit 0.3.1 → 0.3.2

package/README.md

@@ -37,7 +37,7 @@ Cada pasta de `.ai/` (`rules`, `agents`, `skills`, `templates`, `references`) te
 | `.claude/agents/<id>.md` | Somente `--mode native`: subagentes do Claude Code |
 | `.codex/agents/<id>.toml` | Somente `--mode native`: agentes personalizados do Codex |
 
-Skills: `planejar-mudanca`, `revisar-codigo`, `validar-mudanca` (genéricas) e `seedgrid-crud`, `seedgrid-new-screen`, `seedgrid-review` (padrões SeedGrid). Toda instalação recebe todas as skills.
+Skills: `sg-plan-change`, `sg-code-review`, `sg-validate-change` (genéricas) e `sg-crud-front`, `sg-new-screen`, `sg-review` (padrões SeedGrid). Toda instalação recebe todas as skills.
 
 ## A base de conhecimento (seedgridKB)
 
@@ -101,14 +101,14 @@ seedgrid-ai review back --tool codex             # só o back-end, usando o Code
 
 ### `seedgrid-ai review`
 
-Executa a skill `seedgrid-review` na ferramenta de IA instalada, em modo não interativo e somente leitura (Claude Code: `claude -p` com ferramentas de leitura; Codex: `codex exec --sandbox read-only`). A skill confere o código contra as regras `FE-nn` e `BE-nn` (`.ai/rules/frontend-seedgrid.md` e `backend-java-seedgrid.md`) e o CLI mostra o relatório e devolve o código de saída.
+Executa a skill `sg-review` na ferramenta de IA instalada, em modo não interativo e somente leitura (Claude Code: `claude -p` com ferramentas de leitura; Codex: `codex exec --sandbox read-only`). A skill confere o código contra as regras `FE-nn` e `BE-nn` (`.ai/rules/frontend-seedgrid.md` e `backend-java-seedgrid.md`) e o CLI mostra o relatório e devolve o código de saída.
 
 - **Escopo:** `front`, `back` ou nenhum (os dois). Por padrão revisa os arquivos alterados (diff); `--full` revisa o projeto inteiro.
 - **Ferramenta:** `--tool claude|codex`. Sem a opção, usa a primeira disponível nesta ordem: Claude Code, Codex. Considera só os targets instalados no projeto que tenham a skill e o executável no `PATH`. O CLI não detecta em qual ferramenta você está trabalhando.
 - **Custo e login:** chama o modelo com o seu login na ferramenta e **consome tokens**. É o único comando que faz isso. Nenhum token é lido nem gravado pelo CLI.
 - **Resultado não determinístico:** a revisão é feita por um modelo; execuções repetidas podem apontar itens um pouco diferentes (nos testes, as duas ferramentas acharam as violações óbvias e divergiram nos itens de julgamento). Trate o resultado como revisão, não como prova.
 - **Saída estruturada:** a skill termina com um bloco `seedgrid-review-json`. Se a ferramenta falhar, esgotar o tempo (15 min) ou responder sem o bloco, o comando sai com `1` e mostra o texto bruto; nunca conta como "sem violações".
-- Exige o toolkit instalado (`init`) com a skill `seedgrid-review` (`update` leva as skills novas a projetos já instalados).
+- Exige o toolkit instalado (`init`) com a skill `sg-review` (`update` leva as skills novas a projetos já instalados).
 
 Depois de instalar ou atualizar, **abra uma nova sessão** do Claude Code ou do Codex. Não há recarga garantida em todas as ferramentas.
 

package/dist/adapters/shared.js

@@ -53,19 +53,18 @@ export function renderFolderIndex(bundle, type) {
 }
 export const SKILLS_INDEX_FILE = '.ai/skills/index.md';
 /** Índice das skills do toolkit, gerado das descrições para o AGENTS.md não crescer a cada skill nova. */
-export function renderSkillsIndex(bundle, targets) {
+export function renderSkillsIndex(bundle) {
     const cell = (t) => t.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ').trim();
-    const dirs = [targets.includes('claude') ? '.claude/skills' : null, targets.includes('codex') ? '.agents/skills' : null].filter((d) => d !== null);
     const lines = [
         '# Índice de skills',
         '',
         `<!-- ${GENERATED_NOTICE} a partir do frontmatter de cada SKILL.md (conteúdo ${bundle.contentVersion}). Não edite. -->`,
         '',
-        'Skills instaladas pelo SeedGrid AI Toolkit. Antes de uma tarefa que combine com a descrição, leia o `SKILL.md` indicado e siga-o. Skills do próprio projeto que não são do toolkit não aparecem aqui.',
+        'Skills instaladas pelo SeedGrid AI Toolkit. Antes de uma tarefa que combine com a descrição, leia o `SKILL.md` indicado e siga-o. Skills do próprio projeto não aparecem aqui: se existir `projeto.md` nesta pasta, ele as lista.',
         '',
         '| Skill | O que faz e quando usar | Arquivo |',
         '| --- | --- | --- |',
-        ...bundle.skills.map((k) => `| \`${k.name}\` | ${cell(k.description)} | ${dirs.map((d) => `\`${d}/${k.name}/SKILL.md\``).join(' ou ')} |`),
+        ...bundle.skills.map((k) => `| \`${k.name}\` | ${cell(k.description)} | [${k.name}/SKILL.md](${k.name}/SKILL.md) |`),
         '',
     ];
     return lines.join('\n');
@@ -80,7 +79,12 @@ export function sharedFiles(bundle, targets) {
     for (const type of ['rules', 'templates', 'references']) {
         files.push({ path: sharedDest(`${type}/index.md`), content: renderFolderIndex(bundle, type), component: type });
     }
-    files.push({ path: SKILLS_INDEX_FILE, content: renderSkillsIndex(bundle, targets), component: 'skills-index' });
+    // Cópia canônica em .ai/skills (o AGENTS.md aponta para ela); as cópias nativas das ferramentas vêm dos adapters.
+    for (const k of bundle.skills) {
+        for (const f of k.files)
+            files.push({ path: `.ai/skills/${k.name}/${f.path}`, content: f.content, component: `skill:${k.name}` });
+    }
+    files.push({ path: SKILLS_INDEX_FILE, content: renderSkillsIndex(bundle), component: 'skills-index' });
     return files;
 }
 /** Instruções de consulta à base de conhecimento SeedGrid (.ai/brain/), quando o conteúdo a inclui. */
@@ -106,8 +110,8 @@ function standardsLines(bundle) {
     const present = STANDARD_RULES.filter(([p]) => bundle.shared.some((s) => s.path === p));
     if (present.length === 0)
         return [];
-    const review = bundle.skills.some((k) => k.name === 'seedgrid-review')
-        ? ' Para conferir se o código segue o padrão, use a skill `seedgrid-review`.'
+    const review = bundle.skills.some((k) => k.name === 'sg-review')
+        ? ' Para conferir se o código segue o padrão, use a skill `sg-review`.'
         : '';
     const list = present.map(([p, label]) => `\`.ai/${p}\` (${label})`).join(' e ');
     return [`- **Padrões SeedGrid obrigatórios:** ao implementar ou alterar código, siga ${list}.${review}`];
@@ -130,6 +134,7 @@ export function agentsMdBlock(bundle, targets, mode) {
         'Cada pasta de `.ai/` tem um `index.md` com o que há nela: comece por ele e leia só o que a tarefa pedir.',
         '',
         '- Regras: `.ai/rules/`. Antes de tarefas não triviais, leia `coordenacao.md`.',
+        '- **Documentos que você gerar** (planos, handoff, decisões, especificações, relatórios) são salvos em `.ai/docs/<tipo>/`, por exemplo `.ai/docs/plans/` e `.ai/docs/handoff/`; veja `.ai/rules/documentos.md`.',
         ...standardsLines(bundle),
         '- Papéis: `.ai/agents/`.',
         `- Skills: \`.ai/skills/\` (${bundle.skills.length}). Antes de uma tarefa que combine com a descrição, leia o \`SKILL.md\` indicado no índice.`,

package/dist/cli.js

@@ -25,7 +25,7 @@ Comandos:
   doctor    Diagnostica sintaxe, consistência e limitações; --probe confirma a descoberta real no Codex
   remove    Remove só o que o toolkit instalou e continua intacto
   validate  Valida uma fonte de conteúdo (manifesto, papéis, skills, KB) sem tocar em projetos
-  review    Confere o código contra os padrões SeedGrid, chamando a skill seedgrid-review no Claude Code ou no Codex
+  review    Confere o código contra os padrões SeedGrid, chamando a skill sg-review no Claude Code ou no Codex
   help      Mostra esta ajuda
 
 Uso:

package/dist/commands/review.js

@@ -6,7 +6,7 @@ import { readLock } from '../core/lock.js';
 import { detectTool, runReviewCommand } from '../core/tools.js';
 import { ALL_TARGETS, ToolkitError } from '../core/types.js';
 import { EXIT_ERROR, EXIT_OK, EXIT_VIOLATIONS } from './common.js';
-export const REVIEW_SKILL = 'seedgrid-review';
+export const REVIEW_SKILL = 'sg-review';
 export const REVIEW_SCOPES = ['front', 'back', 'both'];
 const SCOPE_TEXT = { front: 'front', back: 'back', both: 'front e back' };
 export function parseScope(value) {
@@ -60,7 +60,7 @@ async function skillInstalled(projectRoot, target) {
 }
 /**
  * Revisa o código do projeto contra os padrões SeedGrid chamando, em modo somente leitura,
- * a skill seedgrid-review na ferramenta de IA instalada (Claude Code ou Codex).
+ * a skill sg-review na ferramenta de IA instalada (Claude Code ou Codex).
  * Usa o login do usuário na ferramenta e consome tokens; nenhum outro comando chama o modelo.
  */
 export async function reviewCommand(opts) {

package/dist/core/plan.js

@@ -116,6 +116,11 @@ export async function planInstall(projectRoot, desired, lockState, meta) {
         else if (prev) {
             conflicts.push({ path: d.path, reason: 'modificado localmente desde a última instalação' });
         }
+        else if (d.component.startsWith('skill:')) {
+            // Padronização: a skill do toolkit prevalece sobre uma skill de projeto com o mesmo nome (o original vai para o backup).
+            fileOps.push({ path: d.path, action: 'update', reason: 'skill do toolkit substitui arquivo existente de mesmo nome', content: d.content, expectedHash: cur.hash });
+            warnings.push(`${d.path}: substituído pela skill do toolkit; o original fica no backup da operação`);
+        }
         else {
             conflicts.push({ path: d.path, reason: 'arquivo existente não gerenciado pelo toolkit, com conteúdo diferente' });
         }

package/docs/arquitetura.md

@@ -22,7 +22,7 @@ Cada etapa é pura até `applyPlan`: carregar, validar e planejar só leem o dis
 | Caminho | Responsabilidade |
 | --- | --- |
 | `src/cli.ts` | Parsing de argumentos (`node:util.parseArgs`), saída texto/JSON, códigos de saída |
-| `src/commands/` | `init`, `update` (fluxo comum em `install.ts`), `status`, `doctor`, `remove`, `validate`, `review` (única que chama o modelo: executa a skill `seedgrid-review` via `claude -p` ou `codex exec`, somente leitura) |
+| `src/commands/` | `init`, `update` (fluxo comum em `install.ts`), `status`, `doctor`, `remove`, `validate`, `review` (única que chama o modelo: executa a skill `sg-review` via `claude -p` ou `codex exec`, somente leitura) |
 | `src/core/content.ts` | Leitura do manifesto (vault) e validação de schema, nomes, IDs, arquivos, links, referências e da KB (wikilinks, caminhos locais, segredos) |
 | `src/core/plan.ts` | Comparação entre estado desejado, lock e disco; classifica cada item e detecta conflitos |
 | `src/core/apply.ts` | Revalidação, backup, escrita via temporário + renomeação, rollback, limpeza de pastas vazias |
@@ -47,7 +47,7 @@ Para cada arquivo desejado:
 | igual ao desejado | presente / ausente | sem mudança / adotar |
 | igual ao hash do lock | presente | atualizar |
 | diferente de ambos | presente | **conflito** (modificado localmente) |
-| diferente do desejado | ausente | **conflito** (arquivo não gerenciado) |
+| diferente do desejado | ausente | **conflito** (arquivo não gerenciado; exceção: arquivos de skill do toolkit são substituídos, com backup) |
 
 Arquivos no lock que saíram do estado desejado (troca de target/modo, item removido do conteúdo) são apagados se intactos; se modificados, geram conflito.
 

package/docs/compatibilidade.md

@@ -31,7 +31,7 @@ Fontes consultadas: [Claude Code skills](https://code.claude.com/docs/en/skills)
 
 - **Base de conhecimento** (Claude Code 2.1.299, `claude -p`, projeto vazio com `.ai/brain/` instalada): perguntado pelo valor padrão, tipo e classe de `seedgrid.app.ai-pricing.timezone`, respondeu `America/Sao_Paulo`, `String`, `AiPricingScheduler`, citando as notas consultadas; perguntado por uma propriedade inexistente, respondeu que não a encontrou e se recusou a inventar o padrão.
 
-- **`seedgrid-ai review`** (Claude Code 2.1.300 via `claude -p`; Codex 0.160.1 via `codex exec --sandbox read-only`): em projeto descartável com violações plantadas (telefone e CPF em `SgInputText`, `<input>` cru, `window.confirm`, `@Inject` em atributo, `RuntimeException`, pacote no singular), as duas ferramentas executaram a skill `seedgrid-review`, apontaram essas violações com arquivo e linha e fecharam com o bloco `seedgrid-review-json`; o CLI saiu com código 3. Tempos: cerca de 27 s (Claude Code) e 80 s (Codex). Os itens de julgamento divergiram entre as duas ferramentas.
+- **`seedgrid-ai review`** (Claude Code 2.1.300 via `claude -p`; Codex 0.160.1 via `codex exec --sandbox read-only`): em projeto descartável com violações plantadas (telefone e CPF em `SgInputText`, `<input>` cru, `window.confirm`, `@Inject` em atributo, `RuntimeException`, pacote no singular), as duas ferramentas executaram a skill `sg-review`, apontaram essas violações com arquivo e linha e fecharam com o bloco `seedgrid-review-json`; o CLI saiu com código 3. Tempos: cerca de 27 s (Claude Code) e 80 s (Codex). Os itens de julgamento divergiram entre as duas ferramentas.
 
 Nenhuma tarefa publicou ou modificou serviços externos.
 

package/docs/formato.md

@@ -57,7 +57,7 @@ Arquivos e pastas que começam com ponto são ignorados.
 ```json
 {
   "schemaVersion": 2,
-  "contentVersion": "0.3.1",
+  "contentVersion": "0.3.2",
   "toolkitBase": "SeedGrid/Toolkit",
   "components": [
     { "id": "agents", "type": "agents", "files": ["agents/arquiteto.md"] },
@@ -65,9 +65,9 @@ Arquivos e pastas que começam com ponto são ignorados.
     { "id": "templates", "type": "templates", "files": ["templates/especificacao-tarefa.md"] },
     { "id": "references", "type": "references", "files": ["references/glossario.md"] },
     {
-      "id": "skill:planejar-mudanca",
+      "id": "skill:sg-plan-change",
       "type": "skill",
-      "name": "planejar-mudanca",
+      "name": "sg-plan-change",
       "files": [
         "SKILL.md",
         { "path": "assets/especificacao-tarefa.md", "from": "templates/especificacao-tarefa.md" }
@@ -111,7 +111,7 @@ Schema próprio do toolkit, em frontmatter YAML:
 id: backend-java
 description: Implementa APIs Java e persistência quando a tarefa altera o backend.
 capabilities: [read-files, edit-files, run-checks]
-preferred_skills: [validar-mudanca]
+preferred_skills: [sg-validate-change]
 ---
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/ai-toolkit",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Instala agentes, skills, regras, templates e referências versionados em projetos locais para Claude Code e Codex.",
   "type": "module",
   "license": "MIT",

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

@@ -2,7 +2,7 @@
 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]
+preferred_skills: [sg-plan-change]
 ---
 
 # Arquiteto

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

@@ -2,7 +2,7 @@
 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]
+preferred_skills: [sg-crud-back, sg-validate-change]
 ---
 
 # Backend Java
@@ -26,7 +26,7 @@ Implementar mudanças no backend Java com código coerente com o projeto, testes
 
 - 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`.
+- **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 `sg-crud-back`.
 - **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.

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

@@ -2,7 +2,7 @@
 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]
+preferred_skills: [sg-validate-change]
 ---
 
 # Backend Rust

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

@@ -2,7 +2,7 @@
 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]
+preferred_skills: [sg-crud-front, sg-new-screen, sg-validate-change]
 ---
 
 # Frontend React

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

@@ -2,7 +2,7 @@
 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]
+preferred_skills: [sg-validate-change]
 ---
 
 # QA
@@ -31,7 +31,7 @@ Provar, com testes escritos e executados, que a mudança atende aos critérios d
 - 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`).
+- Conferir que o código segue o padrão SeedGrid quando a tarefa pedir (skill `sg-review`).
 
 ## Limites
 

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

@@ -2,7 +2,7 @@
 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]
+preferred_skills: [sg-code-review, sg-review]
 ---
 
 # Revisor
@@ -28,7 +28,7 @@ Encontrar problemas reais na mudança antes que ela seja entregue, com achados v
 - 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`.
+- Conferir o padrão SeedGrid do que foi alterado (skill `sg-review`): componentes e regras `FE-nn`, `BE-nn`.
 
 ## Limites
 

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

@@ -69,10 +69,10 @@ flowchart TD
 
 ## 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.
+Bump de versão do projeto, atualização de configuração e tarefas parecidas vão direto para a skill adequada (por exemplo `sg-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).
+- `sg-plan-change` (arquiteto), `sg-validate-change` (qa), `sg-code-review` e `sg-review` (revisor).
+- `sg-crud-back` (backend-java), `sg-crud-front` e `sg-new-screen` (frontend-react), `sg-bump` (versão do projeto).
 - A lista completa, com o que cada skill faz, está em `.ai/skills/index.md`.

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

@@ -3,7 +3,7 @@ description: "Padrões obrigatórios do back-end Java SeedGrid: estrutura de pas
 ---
 # 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`.
+Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra tem um id (`BE-nn`) para citar em revisões (`sg-review`). Para as extensions existentes (propriedades, enums, exemplos), consulte a KB: comece por `.ai/brain/SeedGrid/Extensions/Indice.md`.
 
 ## Estrutura e nomes
 
@@ -47,7 +47,7 @@ Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra
 - **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`.
+- **BE-66.** Cadastros novos seguem a skill `sg-crud-back`.
 
 ## Ao terminar
 

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

@@ -36,4 +36,4 @@ Se o projeto exigir um fluxo obrigatório (por exemplo, revisão antes de todo c
 
 ## 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.
+Os templates em `.ai/templates/` são modelos distribuídos pelo toolkit. Planos, handoffs, decisões, especificações e relatórios produzidos em tarefas reais são salvos em `.ai/docs/<tipo>/`, conforme [documentos](documentos.md), nunca dentro de `.ai/templates/`, `.ai/agents/` ou `.ai/rules/`, que são gerenciados e podem ser atualizados.

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

@@ -0,0 +1,26 @@
+---
+description: "Onde salvar os documentos que a IA gera (planos, handoff, decisões, relatórios, especificações): sempre em .ai/docs/<tipo>/. Leia antes de criar qualquer arquivo .md de trabalho."
+---
+# Documentos gerados pela IA
+
+Todo documento de trabalho que a IA produzir (plano, handoff, decisão, especificação, relatório, análise, anotações de sessão) é salvo em **`.ai/docs/<tipo>/`**, nunca na raiz do projeto, em `docs/` do projeto ou dentro de `.ai/rules/`, `.ai/agents/`, `.ai/templates/` e `.ai/skills/`, que o toolkit gerencia e reescreve no `update`.
+
+## Pastas por tipo
+
+| Tipo | Pasta | Quando |
+| --- | --- | --- |
+| Plano | `.ai/docs/plans/` | Plano de uma mudança, aprovado ou não, antes de implementar |
+| Handoff | `.ai/docs/handoff/` | Estado e próximos passos para outra sessão, papel ou pessoa continuar |
+| Decisão | `.ai/docs/decisions/` | Decisão de arquitetura e o porquê (modelo: `decisao-arquitetura.md`) |
+| Especificação | `.ai/docs/specs/` | Especificação de tarefa (modelo: `especificacao-tarefa.md`) |
+| Validação | `.ai/docs/reports/` | Relatórios de validação, revisão e testes (modelo: `relatorio-validacao.md`) |
+| Outros | `.ai/docs/<assunto>/` | Qualquer outro documento; crie a pasta com um nome curto no plural |
+
+## Convenções
+
+- Crie a pasta quando precisar. O toolkit não a cria nem a altera: o conteúdo é do projeto e sobrevive ao `update` e ao `remove`.
+- Nome do arquivo: `AAAA-MM-DD-assunto-curto.md` (minúsculas, hífens, sem acentos), por exemplo `2026-10-15-crud-clientes.md`.
+- Comece com um título e uma linha de contexto (tarefa, autor/papel, data). Não grave segredos, tokens nem dados pessoais.
+- Antes de criar, veja se já existe documento do mesmo assunto na pasta e atualize-o em vez de duplicar.
+- Ao citar um documento em outro, use caminho relativo.
+- Versionar ou não é decisão do projeto: se o time não quiser versionar, ele ignora `.ai/docs/` no Git.

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

@@ -3,7 +3,7 @@ description: "Padrões obrigatórios do front-end SeedGrid: usar sempre os compo
 ---
 # 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.
+Regras **obrigatórias** para telas React que usam `@seedgrid/fe-components`. Cada regra tem um id (`FE-nn`) para citar em revisões (`sg-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
 
@@ -44,4 +44,4 @@ Nunca use `SgInputText` (nem `<input>` com máscara própria) para um dado que t
 
 ## 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`.
+Telas de cadastro seguem a skill `sg-crud-front` (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/skills/{seedgrid-bump → sg-bump}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-bump
+name: sg-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

package/seedgridKB/SeedGrid/Toolkit/skills/{revisar-codigo → sg-code-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: revisar-codigo
+name: sg-code-review
 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

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-backend-crud → sg-crud-back}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-backend-crud
+name: sg-crud-back
 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
@@ -25,5 +25,5 @@ Monta um cadastro completo no padrão `.ai/rules/backend-java-seedgrid.md` (regr
 ## 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`.
+- A tela correspondente segue a skill `sg-crud-front`; menu e permissão da tela, a `sg-new-screen`.
+- Para conferir o resultado contra o padrão, use `sg-review back`.

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-crud
+name: sg-crud-front
 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.
 ---
 
@@ -13,7 +13,7 @@ Read the existing screens of the project before writing a new one and copy their
 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.
+To register the menu item, icon and permission of a new screen, use the `sg-new-screen` skill.
 
 ## Workflow
 

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/agents/openai.yaml

@@ -1,4 +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."
+  default_prompt: "Use $sg-crud-front to create a SeedGrid CRUD with list/edit pages, publicId routing, and SgInputTextSearch."

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/references/routing.md

@@ -63,4 +63,4 @@ Resources behind a CRUD should:
 - Menu item should point to the real list route
 - Breadcrumb items must use valid `href` values
 - Parent sections like `/security` must resolve to a real child route if there is no standalone page
-- Registering the menu item, icon and permission is covered by the `seedgrid-new-screen` skill
+- Registering the menu item, icon and permission is covered by the `sg-new-screen` skill

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-new-screen → sg-new-screen}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-new-screen
+name: sg-new-screen
 description: Registrar uma tela, menu ou permissao nova no boilerplate SeedGrid (app do cliente `frontend/` ou admin da plataforma `admin/`) sem esquecer nenhum dos lugares que precisam ficar sincronizados - migration da permissao, item de menu, icone, item ativo, catalogo do editor de perfis e, se for vendavel por plano, o treeview de features do admin e o `@RequiresPlanFeature`. Use ao criar tela nova, acao nova numa tela existente, permissao nova, ou ao mover/renomear item de menu.
 ---
 

package/seedgridKB/SeedGrid/Toolkit/skills/sg-new-screen/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SeedGrid tela nova"
+  short_description: "Tela, menu e permissoes sincronizados"
+  default_prompt: "Use $sg-new-screen to add a new screen with its permissions, menu item, icon, profile-editor catalog and, if sellable, the plan feature tree."

package/seedgridKB/SeedGrid/Toolkit/skills/sg-new-skill/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: sg-new-skill
+description: Cria uma skill nova no projeto - pergunta nome, descrição, quando usar e passos, e grava o SKILL.md em .ai/skills e nas pastas nativas do Claude Code e do Codex, atualizando o índice. Use SEMPRE que pedirem para criar, adicionar ou escrever uma skill, ou para transformar um procedimento repetido em skill.
+metadata:
+  toolkit: seedgrid-ai
+---
+
+# Criar uma skill
+
+Toda skill nova do projeto nasce por aqui, para ficar completa e nos lugares certos. Não crie skill escrevendo arquivos soltos.
+
+## Passos
+
+1. **Levantar os dados.** Pergunte o que faltar (junte as perguntas numa só mensagem e não pergunte o que o pedido já respondeu):
+   - **Nome:** minúsculas, números e hífens (`^[a-z0-9]+(-[a-z0-9]+)*$`), curto e específico (`gerar-relatorio-mensal`). Verbo ou tarefa, não "ajuda".
+   - **Objetivo:** o que a skill faz e o resultado esperado.
+   - **Quando usar:** os pedidos e situações que devem acioná-la (e, se houver, quando **não** usar).
+   - **Passos:** o procedimento, as regras e os cuidados. Se o usuário não tiver, proponha um rascunho e peça confirmação.
+   - **Arquivos de apoio:** checklists, exemplos ou scripts que valham um arquivo à parte (opcional).
+2. **Conferir duplicidade.** Veja `.ai/skills/`, `.claude/skills/` e `.agents/skills/`. Se já existir skill com o nome, ou outra que cubra o mesmo caso, mostre e pergunte se estende a existente. Nunca sobrescreva sem pedido explícito. Nomes que começam com `sg-` são reservados às skills do toolkit: o `update` as gerencia e uma skill do projeto com esse prefixo pode ser substituída. Não use `sg-` nas skills do projeto; se o usuário pedir esse prefixo, avise do risco e sugira outro.
+3. **Escrever o `SKILL.md`** em `.ai/skills/<nome>/SKILL.md`:
+   - Frontmatter só com `name` (igual ao nome da pasta) e `description`. Não use campos específicos de uma ferramenta (`context`, `allowed-tools`, `model` etc.).
+   - `description` em uma ou duas frases: o que faz **e quando usar**, com as palavras que o usuário diria. Se tiver `:`, ponha entre aspas. É por ela que o modelo decide chamar a skill, então seja específico.
+   - Corpo curto e direto: passos numerados, regras e saída esperada. Detalhes longos vão em `references/<assunto>.md`, citados no `SKILL.md` com link relativo. Nada de segredos, nem caminhos absolutos da sua máquina.
+4. **Copiar para as pastas nativas**, com o mesmo conteúdo (inclusive `references/` e demais arquivos), apenas nos destinos que o projeto usa: `.claude/skills/<nome>/` se a pasta `.claude/skills/` existir, `.agents/skills/<nome>/` se `.agents/skills/` existir. Sem nenhuma das duas, fique só com `.ai/skills/` e avise que a skill só será usada se o modelo ler o índice.
+5. **Registrar no índice do projeto.** Acrescente a skill em `.ai/skills/projeto.md` (crie se não existir, com o título `# Skills do projeto`), uma linha por skill: `- [nome](nome/SKILL.md): descrição`. **Não edite `.ai/skills/index.md`**: ele é gerado pelo toolkit e o `update` o reescreve (ele já cita o `projeto.md`).
+6. **Conferir.** Releia o `SKILL.md` gravado, confirme que as cópias são idênticas à de `.ai/skills/`, que nenhum link relativo está quebrado e que o `name` bate com a pasta.
+7. **Entregar.** Liste os arquivos criados e diga como usar: pelo nome (`/<nome>` no Claude Code, `$<nome>` no Codex) ou pedindo a tarefa com as palavras da descrição. Avise que uma sessão nova da ferramenta é necessária para listar a skill no menu.
+
+## Cuidados
+
+- Skills do projeto (inclusive o `projeto.md`) não entram no lock do toolkit: o `seedgrid-ai update` atualiza o conteúdo do toolkit e não as altera nem as remove. Para virarem parte do toolkit, precisam ser adicionadas ao conteúdo do `seedgrid-ai` (fonte e manifesto).
+- Uma skill, uma finalidade. Se a descrição precisa de "e também", provavelmente são duas skills.
+- Não duplique regras que já estão em `.ai/rules/`: cite o arquivo.
+- Para alterar uma skill existente do projeto, edite as três cópias e mantenha-as iguais.

package/seedgridKB/SeedGrid/Toolkit/skills/{planejar-mudanca → sg-plan-change}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: planejar-mudanca
+name: sg-plan-change
 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

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-review → sg-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-review
+name: sg-review
 description: Verifica se o código-fonte de um projeto segue os padrões SeedGrid (front React com @seedgrid/fe-components e back Java), citando cada violação por id de regra, arquivo e linha. Use quando pedirem para revisar, auditar ou conferir o padrão SeedGrid, depois de implementar uma tela ou serviço, ou antes de abrir um PR. Aceita o escopo "front", "back" ou nenhum (os dois).
 metadata:
   toolkit: seedgrid-ai

package/seedgridKB/SeedGrid/Toolkit/skills/{validar-mudanca → sg-validate-change}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: validar-mudanca
+name: sg-validate-change
 description: Valida uma mudança de código executando build, testes e verificações ligadas aos critérios de aceite, e registra evidências em um relatório. Use antes de declarar uma tarefa concluída ou após correções de revisão.
 metadata:
   toolkit: seedgrid-ai

package/seedgridKB/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "contentVersion": "0.3.1",
+  "contentVersion": "0.3.2",
   "toolkitBase": "SeedGrid/Toolkit",
   "components": [
     {
@@ -21,6 +21,7 @@
       "files": [
         "rules/coordenacao.md",
         "rules/formato-entrega.md",
+        "rules/documentos.md",
         "rules/personalizacao-local.md",
         "rules/frontend-seedgrid.md",
         "rules/backend-java-seedgrid.md"
@@ -45,9 +46,9 @@
       ]
     },
     {
-      "id": "skill:planejar-mudanca",
+      "id": "skill:sg-plan-change",
       "type": "skill",
-      "name": "planejar-mudanca",
+      "name": "sg-plan-change",
       "files": [
         "SKILL.md",
         {
@@ -57,18 +58,18 @@
       ]
     },
     {
-      "id": "skill:revisar-codigo",
+      "id": "skill:sg-code-review",
       "type": "skill",
-      "name": "revisar-codigo",
+      "name": "sg-code-review",
       "files": [
         "SKILL.md",
         "references/checklist.md"
       ]
     },
     {
-      "id": "skill:validar-mudanca",
+      "id": "skill:sg-validate-change",
       "type": "skill",
-      "name": "validar-mudanca",
+      "name": "sg-validate-change",
       "files": [
         "SKILL.md",
         {
@@ -78,17 +79,17 @@
       ]
     },
     {
-      "id": "skill:seedgrid-backend-crud",
+      "id": "skill:sg-crud-back",
       "type": "skill",
-      "name": "seedgrid-backend-crud",
+      "name": "sg-crud-back",
       "files": [
         "SKILL.md"
       ]
     },
     {
-      "id": "skill:seedgrid-crud",
+      "id": "skill:sg-crud-front",
       "type": "skill",
-      "name": "seedgrid-crud",
+      "name": "sg-crud-front",
       "files": [
         "SKILL.md",
         "references/patterns.md",
@@ -98,9 +99,9 @@
       ]
     },
     {
-      "id": "skill:seedgrid-new-screen",
+      "id": "skill:sg-new-screen",
       "type": "skill",
-      "name": "seedgrid-new-screen",
+      "name": "sg-new-screen",
       "files": [
         "SKILL.md",
         "references/steps.md",
@@ -109,17 +110,25 @@
       ]
     },
     {
-      "id": "skill:seedgrid-bump",
+      "id": "skill:sg-bump",
       "type": "skill",
-      "name": "seedgrid-bump",
+      "name": "sg-bump",
       "files": [
         "SKILL.md"
       ]
     },
     {
-      "id": "skill:seedgrid-review",
+      "id": "skill:sg-new-skill",
       "type": "skill",
-      "name": "seedgrid-review",
+      "name": "sg-new-skill",
+      "files": [
+        "SKILL.md"
+      ]
+    },
+    {
+      "id": "skill:sg-review",
+      "type": "skill",
+      "name": "sg-review",
       "files": [
         "SKILL.md"
       ]

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SeedGrid tela nova"
-  short_description: "Tela, menu e permissoes sincronizados"
-  default_prompt: "Use $seedgrid-new-screen to add a new screen with its permissions, menu item, icon, profile-editor catalog and, if sellable, the plan feature tree."