@seedgrid/ai-toolkit 0.3.0 → 0.3.2

package/README.md

@@ -4,7 +4,17 @@ Fonte versionada de **agentes (papéis), skills, regras, templates, referências
 
 O toolkit **não** é um orquestrador de modelos: não chama APIs da OpenAI ou da Anthropic, não guarda credenciais e não escolhe fornecedores. Ele instala instruções e configurações; a ferramenta de IA executa e coordena o trabalho.
 
-> Estado: versão 0.3.0 (pacote e conteúdo), pronta para publicar no npm como `@seedgrid/ai-toolkit`. Licença MIT. O pacote ainda **não foi publicado** no npm e o repositório GitHub ainda não existe.
+> Pacote público no npm como `@seedgrid/ai-toolkit` (licença MIT); código em https://github.com/SeedGrid/seedgrid-ai. A versão do pacote e a do conteúdo instalado são a mesma.
+
+## Instalação rápida
+
+```bash
+npx @seedgrid/ai-toolkit@latest install   # uma vez por máquina: instala o comando seedgrid-ai (npm install -g)
+cd /caminho/do/projeto
+seedgrid-ai init                          # instala o toolkit no projeto
+```
+
+Depois é só `seedgrid-ai update`, `seedgrid-ai status`, `seedgrid-ai doctor`, `seedgrid-ai review` etc. (`seedgrid-ai --help` lista tudo). Sem instalar o comando, qualquer comando também funciona com `npx @seedgrid/ai-toolkit <comando>`. Abra uma **sessão nova** do Claude Code ou do Codex depois de instalar no projeto.
 
 ## O que é instalado
 
@@ -27,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)
 
@@ -66,6 +76,7 @@ seedgrid-ai init --target both --mode shared
 ## Comandos
 
 ```bash
+seedgrid-ai install                              # instala o comando seedgrid-ai na máquina (npm install -g)
 seedgrid-ai init --target both --mode shared     # padrão; idempotente
 seedgrid-ai init --target both --mode native     # também registra subagentes nativos
 seedgrid-ai init --source ./seedgridKB --dry-run    # fonte local (desenvolvimento), só o plano
@@ -90,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.
 
@@ -118,15 +129,15 @@ Seleção de papéis e delegação são comportamentos orientados por instruçõ
 
 ## Uso via npm
 
-Depois que a versão for publicada:
-
 ```bash
+npx @seedgrid/ai-toolkit@latest install     # instala o comando seedgrid-ai nesta máquina (uma vez; repita para atualizar o comando)
 cd /caminho/do/projeto
-npx @seedgrid/ai-toolkit@0.2.0 init --target both     # primeira instalação
-npx @seedgrid/ai-toolkit@latest update                # traz o conteúdo da versão mais recente
+seedgrid-ai init --target both              # primeira instalação no projeto
+seedgrid-ai update                          # leva o projeto ao conteúdo da versão do comando instalado
+npx @seedgrid/ai-toolkit@latest update      # ou: usa a versão mais recente sem instalar nada
 ```
 
-Ou instale o comando globalmente: `npm i -g @seedgrid/ai-toolkit` e use `seedgrid-ai`. Se houver versão mais nova publicada, `init`, `update` e `status` avisam e, no terminal, perguntam se devem usá-la (`[Y/n]`); desative com `--no-update-check`. Detalhes em [docs/instalacao.md](docs/instalacao.md#aviso-de-versão-nova). O pacote leva o CLI compilado e o conteúdo; a versão do pacote identifica o conteúdo instalado, e `update` nunca baixa conteúdo por conta própria. Faça commit do resultado no projeto: o restante da equipe recebe tudo pelo Git, sem rodar o CLI.
+`install` executa `npm install -g @seedgrid/ai-toolkit@<versão deste CLI>` e confere se `seedgrid-ai` ficou no PATH; não toca em nenhum projeto (`--dry-run` mostra o comando). Se der erro de permissão, configure um prefixo global do npm para o seu usuário ou continue usando `npx`. Se houver versão mais nova publicada, `init`, `update` e `status` avisam e, no terminal, perguntam se devem usá-la (`[Y/n]`); desative com `--no-update-check`. Detalhes em [docs/instalacao.md](docs/instalacao.md#aviso-de-versão-nova). O pacote leva o CLI compilado e o conteúdo; a versão do pacote identifica o conteúdo instalado, e `update` nunca baixa conteúdo por conta própria. Faça commit do resultado no projeto: o restante da equipe recebe tudo pelo Git, sem rodar o CLI.
 
 ## Repositório e publicação
 

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

@@ -7,25 +7,29 @@ import { doctorCommand } from './commands/doctor.js';
 import { initCommand } from './commands/init.js';
 import { removeCommand } from './commands/remove.js';
 import { reviewCommand } from './commands/review.js';
+import { selfInstallCommand } from './commands/selfinstall.js';
 import { statusCommand } from './commands/status.js';
 import { updateCommand } from './commands/update.js';
 import { validateCommand } from './commands/validate.js';
 import { cliVersion } from './core/env.js';
+import { TOOL_NAME } from './core/lock.js';
 import { ToolkitError } from './core/types.js';
 import { checkLatest, confirm, isInteractive, npxCommandLine, runPublishedVersion, } from './core/updates.js';
 const HELP = `seedgrid-ai — instala o SeedGrid AI Toolkit em projetos locais (Claude Code e Codex)
 
 Comandos:
+  install   Instala o comando seedgrid-ai nesta máquina (npm install -g), para usar sem npx; não altera nenhum projeto
   init      Instala o toolkit (regras, papéis, skills, base de conhecimento) no projeto; idempotente
   update    Leva o projeto ao conteúdo da versão do CLI em execução (use npx @seedgrid/ai-toolkit@latest para a mais nova)
   status    Mostra versões, opções e divergências da instalação
   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:
+  seedgrid-ai install  [--dry-run]
   seedgrid-ai init     [--target claude|codex|both] [--mode shared|native] [--source <pasta>] [--dry-run]
   seedgrid-ai update   [--target ...] [--mode ...] [--source <pasta>] [--dry-run]
   seedgrid-ai status
@@ -46,10 +50,12 @@ Opções comuns:
   --no-update-check    Não consulta o npm por versões mais novas (também: SEEDGRID_AI_NO_UPDATE_CHECK=1)
   --version, --help
 
+Primeira vez: npx @seedgrid/ai-toolkit@latest install  (depois use seedgrid-ai init, update, ... sem npx)
 Padrões do init: --target both --mode shared (ou as opções do lock existente).
 Em terminal interativo, init/update/status perguntam se devem usar uma versão mais nova publicada no npm.
 Conflitos abortam a operação inteira (código de saída 2); nada é sobrescrito.`;
 const COMMANDS = {
+    install: { handler: selfInstallCommand, allowed: ['dry-run'] },
     init: { handler: initCommand, allowed: ['target', 'mode', 'source', 'dry-run'] },
     update: { handler: updateCommand, allowed: ['target', 'mode', 'source', 'dry-run'] },
     status: { handler: statusCommand, allowed: [] },
@@ -174,7 +180,7 @@ export async function main(argv) {
     }
 }
 function updateNotice(info, args) {
-    return `Aviso: versão ${info.latest} disponível no npm (este CLI: ${info.current}). Para usá-la: ${npxCommandLine(info.latest, args)}`;
+    return `Aviso: versão ${info.latest} disponível no npm (este CLI: ${info.current}). Para usá-la: ${npxCommandLine(info.latest, args)}. Para atualizar o comando seedgrid-ai instalado na máquina: npx ${TOOL_NAME}@latest install`;
 }
 /** Repassa o comando para a versão publicada mais nova. */
 async function delegate(info, args) {

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/commands/selfinstall.js

@@ -0,0 +1,63 @@
+import { exec } from 'node:child_process';
+import { cliVersion } from '../core/env.js';
+import { TOOL_NAME } from '../core/lock.js';
+import { EXIT_ERROR, EXIT_OK } from './common.js';
+/** Executa um comando fixo (sem entrada do usuário) e devolve o resultado. shell é necessário para npm.cmd no Windows. */
+function runFixed(command, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = exec(command, { timeout: timeoutMs, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            const e = err;
+            resolve({ code: e ? (typeof e.code === 'number' ? e.code : null) : 0, stdout: stdout.toString(), stderr: stderr.toString() });
+        });
+        child.stdin?.end();
+    });
+}
+/**
+ * Instala o comando `seedgrid-ai` na máquina (npm install -g), na versão deste CLI.
+ * Depois, os demais comandos ficam disponíveis sem npx. Não toca em nenhum projeto.
+ */
+export async function selfInstallCommand(opts) {
+    const version = cliVersion();
+    const command = `npm install -g ${TOOL_NAME}@${version}`;
+    const base = { command: 'install', version, npmCommand: command };
+    if (opts.dryRun) {
+        return {
+            exitCode: EXIT_OK,
+            report: { ...base, dryRun: true },
+            lines: [`Executaria: ${command}`, 'Nada foi instalado (--dry-run).'],
+        };
+    }
+    const run = opts.npmRunner ?? runFixed;
+    const result = await run(command, 5 * 60 * 1000);
+    if (result.code !== 0) {
+        const detail = (result.stderr.trim() || result.stdout.trim() || '(sem saída)').split('\n').slice(-8).join('\n');
+        return {
+            exitCode: EXIT_ERROR,
+            report: { ...base, ok: false, code: result.code, stderr: result.stderr },
+            lines: [
+                `Não foi possível instalar com "${command}" (código ${result.code ?? 'desconhecido'}).`,
+                detail,
+                '',
+                'Se for permissão, configure um prefixo global do npm para o seu usuário ou rode o terminal com a permissão necessária.',
+                'Sem instalar, você ainda pode usar: npx @seedgrid/ai-toolkit <comando>',
+            ],
+        };
+    }
+    const check = await run('seedgrid-ai --version', 30 * 1000);
+    const found = check.code === 0 && check.stdout.trim() === version;
+    return {
+        exitCode: EXIT_OK,
+        report: { ...base, ok: true, onPath: found },
+        lines: [
+            `Instalado: ${TOOL_NAME}@${version} (comando seedgrid-ai).`,
+            found
+                ? 'O comando já está disponível neste terminal.'
+                : 'Se "seedgrid-ai" não for reconhecido, abra um novo terminal ou confira se a pasta global do npm (npm prefix -g) está no PATH.',
+            '',
+            'Próximos passos, na pasta do projeto:',
+            '  seedgrid-ai init       # instala o toolkit no projeto',
+            '  seedgrid-ai --help     # lista todos os comandos',
+            `Para atualizar o próprio comando no futuro: npx ${TOOL_NAME}@latest install`,
+        ],
+    };
+}

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.0",
+  "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/docs/instalacao.md

@@ -1,6 +1,6 @@
 # Instalação em projetos
 
-Os exemplos usam `seedgrid-ai`. Sem `npm link`, troque por `node <pasta-do-toolkit>/dist/cli.js`.
+Os exemplos usam o comando `seedgrid-ai`. Para tê-lo na máquina: `npx @seedgrid/ai-toolkit@latest install` (executa `npm install -g`, uma vez; repita para atualizar o comando). Sem instalar, troque `seedgrid-ai` por `npx @seedgrid/ai-toolkit`; em desenvolvimento do toolkit, por `node <pasta-do-toolkit>/dist/cli.js`.
 
 ## Primeira instalação
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/ai-toolkit",
-  "version": "0.3.0",
+  "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",