@seedgrid/ai-toolkit 0.0.0-stage → 0.3.1

package/docs/arquitetura.md

@@ -0,0 +1,80 @@
+# Arquitetura
+
+## Visão geral
+
+```text
+seedgridKB/ (vault) ──loadContent──►  ContentBundle (validado)
+                                         │
+                       adapters/ (shared, claude, codex)
+                                         ▼
+                                   DesiredState  (arquivos + blocos)
+                                         │
+              lock + disco ──planInstall/planRemove──►  Plan (ops, conflitos)
+                                         │   sem conflitos e sem --dry-run
+                                         ▼
+                                     applyPlan  (backup → escrita → rollback)
+```
+
+Cada etapa é pura até `applyPlan`: carregar, validar e planejar só leem o disco. Por isso `--dry-run` é garantidamente sem escrita.
+
+## Módulos
+
+| 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/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 |
+| `src/core/blocks.ts` | Localização, inserção, substituição e remoção do bloco gerenciado |
+| `src/core/lock.ts` | Schema, leitura defensiva e serialização do lock |
+| `src/core/paths.ts` | Caminhos relativos seguros e verificação de links simbólicos |
+| `src/core/inspect.ts` | Comparação disco × lock para `status` e `doctor` |
+| `src/core/tools.ts` | Detecção de versões instaladas e sondas locais |
+| `src/adapters/shared.ts` | Arquivos `.ai/`, índices gerados (papéis, rules, skills, templates e references) e bloco do `AGENTS.md` |
+| `src/adapters/claude.ts` | Skills em `.claude/skills/`, bloco do `CLAUDE.md`, subagentes `.claude/agents/*.md` |
+| `src/adapters/codex.ts` | Skills em `.agents/skills/`, agentes `.codex/agents/*.toml` |
+
+Dependências de execução: `yaml` (frontmatter) e `smol-toml` (validação de TOML). Sem dependências nativas.
+
+## Classificação do plano
+
+Para cada arquivo desejado:
+
+| Disco | Lock | Resultado |
+| --- | --- | --- |
+| ausente | qualquer | criar |
+| 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) |
+
+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.
+
+Blocos seguem a mesma lógica sobre o **conteúdo interno** dos marcadores. Marcadores duplicados ou incompletos geram conflito. Se o usuário removeu o bloco inteiro, ele é reinserido no final com aviso.
+
+Hashes são SHA-256 do texto com finais de linha normalizados para LF, para que checkouts com `core.autocrlf` não pareçam customizações.
+
+## Escrita
+
+1. **Revalidação**: o hash de cada alvo é relido; se mudou desde o planejamento, nada é escrito.
+2. **Backup**: arquivos existentes que serão modificados ou apagados são copiados para `.ai/backups/<operação>/`, com `operation.json`.
+3. **Execução**: cada escrita vai para `<arquivo>.seedgrid-tmp-<operação>` e é renomeada sobre o destino (atômico por arquivo onde o sistema suporta). O lock é sempre o último passo.
+4. **Rollback**: em falha, os passos executados são desfeitos em ordem reversa (restauração do backup ou remoção do arquivo criado). Falhas no rollback são relatadas individualmente.
+
+Não há atomicidade global entre vários arquivos.
+
+## Lock
+
+`.ai/toolkit-lock.json` registra `cliVersion`, `contentVersion`, `contentSchemaVersion`, `targets`, `mode`, `source` (`bundled` ou `local`, com caminho apenas se a fonte estiver dentro do projeto), a última operação, e listas de arquivos (`path`, `sha256`, `component`) e blocos (`file`, `sha256`, `createdFile`). Só há caminhos relativos com `/`.
+
+Ao ler, o lock é validado como dado não confiável: caminhos devem ser relativos, sem `..`, e estar sob `.ai/` (exceto `.ai/local/` e `.ai/backups/`), `.claude/skills/`, `.claude/agents/`, `.agents/skills/` ou `.codex/agents/`. Blocos só podem estar em `AGENTS.md` ou `CLAUDE.md`.
+
+O lock só é reescrito quando seu conteúdo muda (a última operação e a versão do CLI não contam), o que mantém a reinstalação sem alterações.
+
+## Shared x native nos adaptadores
+
+O modo shared é o núcleo; native apenas acrescenta arquivos gerados a partir dos mesmos papéis:
+
+- Claude Code: frontmatter `name`, `description` e `tools` (traduzido de `capabilities`: `read-files` → Read, Grep, Glob; `edit-files` → Edit, Write; `run-checks` → Bash; `Skill` quando há `preferred_skills`). Sem `capabilities`, o subagente herda as ferramentas da sessão.
+- Codex: `name`, `description` e `developer_instructions`. `capabilities` não são traduzidas (veja [compatibilidade](compatibilidade.md)). `.codex/config.toml` nunca é alterado.

package/docs/compatibilidade.md

@@ -0,0 +1,50 @@
+# Compatibilidade e limitações
+
+Validação feita em 2026-10-14 (KB incluída em 2026-10-14), Windows 11, Node.js 22.16.0.
+
+## Versões testadas
+
+| Ferramenta | Versão | shared | native |
+| --- | --- | --- | --- |
+| Claude Code | 2.1.299 | validado em sessão real | validado em sessão real |
+| Codex CLI | 0.160.1 | validado em sessão real e com `doctor --probe` | validado em sessão real, **somente com projeto confiável** |
+
+As listas de versões validadas ficam em `src/adapters/claude.ts` e `src/adapters/codex.ts` (`validatedVersions`). O `doctor` avisa quando a versão instalada não consta da lista. Repita o smoke test a cada nova versão das ferramentas antes de ampliar a lista.
+
+## Caminhos validados
+
+| Recurso | Claude Code | Codex |
+| --- | --- | --- |
+| Instruções | `CLAUDE.md` com `@AGENTS.md` | `AGENTS.md` |
+| Skills de projeto | `.claude/skills/<nome>/SKILL.md` | `.agents/skills/<nome>/SKILL.md` |
+| Agentes nativos | `.claude/agents/<id>.md` (frontmatter `name`, `description`, `tools`) | `.codex/agents/<id>.toml` (`name`, `description`, `developer_instructions`) |
+
+Fontes consultadas: [Claude Code skills](https://code.claude.com/docs/en/skills), [Claude Code subagentes](https://code.claude.com/docs/en/sub-agents), [Codex skills](https://developers.openai.com/codex/skills), [Codex subagentes](https://developers.openai.com/codex/multi-agent) (as duas últimas redirecionam para learn.chatgpt.com), [Agent Skills](https://agentskills.io/specification).
+
+## Resultado do smoke test (pasta descartável `proj teste ção`, modo native)
+
+- **Claude Code 2.1.299** (`claude -p`): listou as 3 skills de projeto, os 5 subagentes (`arquiteto`, `backend-java`, `frontend-react`, `revisor`, `validador`) e citou o bloco do `AGENTS.md` recebido via `@AGENTS.md` no `CLAUDE.md`.
+- **Codex 0.160.1** (`codex exec`, sandbox somente leitura):
+  - sem confiança no projeto: listou as 3 skills e o bloco do `AGENTS.md`; **nenhum** agente personalizado;
+  - com `-c "projects={'<caminho>'={trust_level=\"trusted\"}}"`: listou os 5 agentes como `agent_type` e um subagente `revisor` iniciado respondeu.
+  - `codex debug prompt-input` (usado por `doctor --probe`) confirmou `AGENTS.md` e skills sem chamar o modelo.
+
+- **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.
+
+Nenhuma tarefa publicou ou modificou serviços externos.
+
+## Limitações conhecidas
+
+- **Descoberta real**: o `doctor` valida sintaxe e consistência. Só o Codex oferece uma sonda local (`doctor --probe`, para instruções e skills; agentes não aparecem nessa saída). Para o Claude Code e para os agentes do Codex, a confirmação exige abrir uma sessão (veja o smoke test em [manutencao.md](manutencao.md#smoke-test-manual)).
+- **`doctor --probe`** inicia o Codex com a configuração do usuário (por exemplo, servidores MCP configurados podem ser iniciados), embora não chame o modelo.
+- **Codex native exige projeto confiável**: em projeto não confiável, `.codex/agents/` é ignorado silenciosamente e o modo shared continua valendo.
+- **capabilities no Codex não são traduzidas**: a leitura de arquivos no Codex usa o shell, e `sandbox_mode`/`approval_policy` em arquivos de agente não sobrescrevem a sessão principal. Os limites do papel ficam apenas como instrução.
+- **`tools` no Claude Code** limita as ferramentas do subagente, mas não substitui permissões nem sandbox.
+- **Recarga**: o Claude Code observa `.claude/skills/` e `.claude/agents/` apenas se a pasta existia no início da sessão; o Codex detecta skills novas, mas mudanças de configuração exigem reinício. Recomende sempre uma nova sessão.
+- **Escopo de descoberta**: ambas as ferramentas procuram a partir da pasta atual até a raiz do repositório. Sessões abertas fora do projeto não veem a instalação.
+- **Outros produtos**: Claude Desktop, Cowork, Claude web e ChatGPT usam mecanismos próprios. Escrever arquivos no projeto **não** registra skills ou agentes nesses produtos.
+- **Atomicidade**: cada arquivo é escrito por renomeação; não há transação entre vários arquivos. Em falha, há rollback com relato de qualquer item não restaurado.
+- **Instalação global** (`~/.claude`, `~/.agents`, `~/.codex`) não é suportada no MVP.
+- **Seleção e delegação** dependem do modelo seguir as instruções; não são garantias do instalador.

package/docs/formato.md

@@ -0,0 +1,155 @@
+# Formato do conteúdo (autoria)
+
+Todo conteúdo distribuído vive no **vault Obsidian `seedgridKB/`** (abra essa pasta no Obsidian) e é descrito por `seedgridKB/manifest.json`. Valide sempre com:
+
+```bash
+npm run build
+node dist/cli.js validate                          # conteúdo empacotado
+node dist/cli.js validate --source ./seedgridKB    # o vault em edição
+```
+
+A validação acumula todos os problemas e nada é instalado a partir de conteúdo inválido.
+
+## O vault
+
+```text
+seedgridKB/
+├── manifest.json            ← lista o que é distribuído (não aparece no Obsidian)
+├── AGENTS.md, CLAUDE.md     ← instruções para quem MANTÉM o vault; não são distribuídos
+├── Bem-vindo.md, .obsidian/ ← não distribuídos
+└── SeedGrid/
+    ├── Visao-geral.md, Extensions/, SeedGrid-components/, ...   ← base de conhecimento (KB)
+    └── Toolkit/             ← agents/, rules/, templates/, references/, skills/
+```
+
+| Origem no vault | Destino no projeto |
+| --- | --- |
+| `SeedGrid/**` (exceto `Toolkit/`) | `.ai/brain/SeedGrid/**` (somente leitura) |
+| `SeedGrid/Toolkit/agents`, `rules`, `templates`, `references` | `.ai/agents`, `.ai/rules`, `.ai/templates`, `.ai/references` |
+| `SeedGrid/Toolkit/skills/<nome>/` | `.claude/skills/<nome>/` e `.agents/skills/<nome>/` |
+
+O `AGENTS.md` do vault orienta quem **mantém** a documentação (atualizar notas, não inventar comportamento) e é diferente do bloco que o CLI grava nos projetos, que orienta quem **consome** a KB. Por isso o do vault nunca é distribuído.
+
+### Por que `Toolkit/` e não `.ai/`
+
+O Obsidian ignora pastas que começam com ponto: notas dentro de uma pasta `.ai/` ficariam invisíveis no explorador, na busca e no grafo. O instalador faz a tradução para `.ai/` nos projetos.
+
+### Regras de escrita
+
+- **Notas da KB** (`SeedGrid/` fora de `Toolkit/`): wikilinks do Obsidian com **caminho completo a partir da raiz do vault** (`[[SeedGrid/Extensions/security/Configuracao|texto]]`). Nos projetos, o caminho continua válido a partir de `.ai/brain/`.
+- **Conteúdo do Toolkit** (agents, rules, skills...): links **Markdown relativos** (`[texto](../templates/x.md)`), porque skills precisam funcionar fora do Obsidian. Em *Configurações → Arquivos e links*, mantenha "Usar [[Wikilinks]]" desligado ao editar esses arquivos.
+- Pastas de skill precisam manter o nome igual ao campo `name` do `SKILL.md`; o Obsidian atualiza links ao renomear, mas não o `name`.
+
+### Validações da KB
+
+Falham o `validate`, o CI e a publicação:
+
+- wikilink sem destino na base instalada (links dentro de `` `código` `` e de blocos de código são ignorados; `\|` em tabelas é entendido);
+- caminho local de máquina (`C:\Users\...`, `D:\empreendedorismo\...`, `/c/Users/...`);
+- possível segredo (chaves Stripe `sk_live_`/`whsec_`, AWS `AKIA...`, tokens do GitHub, corpo de chave privada). Use placeholders como `<SEGREDO:nome>`;
+- arquivo que não seja `.md` dentro de `SeedGrid/` (imagens ainda não são suportadas);
+- `entrypoints` do manifesto apontando para nota inexistente.
+
+Arquivos e pastas que começam com ponto são ignorados.
+
+## Manifesto
+
+```json
+{
+  "schemaVersion": 2,
+  "contentVersion": "0.3.1",
+  "toolkitBase": "SeedGrid/Toolkit",
+  "components": [
+    { "id": "agents", "type": "agents", "files": ["agents/arquiteto.md"] },
+    { "id": "rules", "type": "rules", "files": ["rules/coordenacao.md"] },
+    { "id": "templates", "type": "templates", "files": ["templates/especificacao-tarefa.md"] },
+    { "id": "references", "type": "references", "files": ["references/glossario.md"] },
+    {
+      "id": "skill:planejar-mudanca",
+      "type": "skill",
+      "name": "planejar-mudanca",
+      "files": [
+        "SKILL.md",
+        { "path": "assets/especificacao-tarefa.md", "from": "templates/especificacao-tarefa.md" }
+      ]
+    },
+    {
+      "id": "brain",
+      "type": "brain",
+      "base": "SeedGrid",
+      "entrypoints": ["Visao-geral.md", "Extensions/Catalogo-de-propriedades.md"]
+    }
+  ]
+}
+```
+
+| Campo | Regra |
+| --- | --- |
+| `schemaVersion` | `2` (versão do formato do manifesto) |
+| `contentVersion` | semver; deve ser **igual** à versão do pacote (`package.json`); aumente a cada mudança de conteúdo |
+| `toolkitBase` | pasta do vault onde ficam `agents/`, `rules/`, `templates/`, `references/` e `skills/` (aqui, `SeedGrid/Toolkit`) |
+| `components[].id` | único; para skills, `skill:<name>` |
+| `components[].type` | `agents`, `rules`, `templates`, `references`, `skill` ou `brain` |
+| `files` (tipos compartilhados) | caminhos relativos a `toolkitBase`, dentro da pasta do tipo; instalados em `.ai/<caminho>` |
+| `files` (skill) | caminhos relativos a `<toolkitBase>/skills/<name>/`; ou `{ "path", "from" }` para copiar um arquivo de outro lugar do toolkit sem duplicar a autoria |
+| `brain.base` | pasta do vault cujas notas `.md` formam a KB (todas, recursivamente); instaladas em `.ai/brain/<base>/` |
+| `brain.exclude` | (opcional) caminhos relativos a `base` a deixar de fora; terminar em `/` exclui uma pasta. `toolkitBase` dentro de `base` é excluído automaticamente |
+| `brain.entrypoints` | notas (relativas a `base`) que o bloco do `AGENTS.md` indica como ponto de partida; precisam existir |
+
+Só pode haver um componente `brain`. Ele é opcional: sem ele, o bloco do `AGENTS.md` não menciona a KB.
+
+Regras verificadas: caminhos relativos sem `..`, sem links simbólicos e em UTF-8; todo arquivo das pastas do toolkit deve constar no manifesto; IDs e nomes únicos; links Markdown relativos devem apontar para arquivos existentes no layout instalado.
+
+Não há sistema de dependências nem perfis no MVP.
+
+## Papéis (`SeedGrid/Toolkit/agents/<id>.md`)
+
+Schema próprio do toolkit, em frontmatter YAML:
+
+```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]
+---
+```
+
+| Campo | Obrigatório | Regra |
+| --- | --- | --- |
+| `id` | sim | minúsculas, números e hífens (até 64); igual ao nome do arquivo |
+| `description` | sim | até 300 caracteres; vai para o catálogo — diga **quando** usar |
+| `capabilities` | não | lista de `read-files`, `edit-files`, `run-checks` (intenções portáveis) |
+| `preferred_skills` | não | nomes de skills existentes no manifesto |
+
+Outros campos são rejeitados. Em especial, **não fixe modelos** (`model`) no conteúdo compartilhado.
+
+O corpo deve ter as seções `## Objetivo`, `## Quando usar`, `## Entradas necessárias`, `## Responsabilidades`, `## Limites` e `## Formato da entrega`. Restrições escritas no corpo são instruções, não mecanismos de segurança; não afirme que uma instrução impede tecnicamente uma ação.
+
+`agents/index.md` é **gerado** a partir do frontmatter e não pode ser escrito à mão.
+
+## Skills (`SeedGrid/Toolkit/skills/<name>/`)
+
+Padrão aberto [Agent Skills](https://agentskills.io/specification):
+
+- `SKILL.md` obrigatório, com frontmatter na primeira linha.
+- `name`: 1 a 64 caracteres, `[a-z0-9-]`, sem hífen no início/fim nem `--`, igual ao nome da pasta.
+- `description`: 1 a 1024 caracteres, dizendo o que faz **e quando usar**.
+- Campos aceitos: `name`, `description`, `license`, `compatibility`, `metadata` (mapa texto→texto), `allowed-tools`. Extensões específicas de ferramenta (como `context`, `paths`, `disable-model-invocation` do Claude Code ou `agents/openai.yaml` do Codex) são rejeitadas no conteúdo compartilhado; se forem necessárias, devem ser implementadas no adaptador.
+- Recursos opcionais em `scripts/`, `references/` e `assets/`, referenciados por caminhos relativos a partir do `SKILL.md`. Cada skill deve ser autocontida.
+- Extensão opcional do Codex: `agents/openai.yaml` (nome de exibição, descrição curta, prompt padrão). É copiado para os dois destinos; o Claude Code o ignora. Liste-o em `files` como qualquer outro arquivo.
+- Mantenha o `SKILL.md` curto (menos de 500 linhas); detalhes vão para `references/`.
+
+Scripts de skills nunca são executados pelo instalador.
+
+## Regras, templates e referências
+
+- `rules/`: instruções de coordenação lidas pela sessão principal. Links relativos entre arquivos `.ai/` são permitidos (por exemplo, `../agents/index.md`).
+- `templates/`: modelos distribuídos. Produtos de tarefas reais (planos, ADRs, relatórios) pertencem a cada projeto e **não** voltam para o toolkit automaticamente.
+- `references/`: conhecimento estático.
+
+Cada arquivo de `rules/`, `templates/` e `references/` precisa de frontmatter com `description` (até 300 caracteres, dizendo o que é e **quando** usar; coloque entre aspas se tiver `:`). É ela que vai para o `index.md` da pasta, gerado na instalação. `index.md` é nome reservado em `agents/`, `rules/`, `templates/` e `references/` e não pode constar no manifesto.
+
+## Blocos gerenciados
+
+O texto dos blocos de `AGENTS.md` e `CLAUDE.md` é gerado pelos adaptadores (`src/adapters/shared.ts` e `src/adapters/claude.ts`), não pelo manifesto. Mantenha-os curtos: eles apontam para `.ai/`, não repetem o conteúdo.

package/docs/instalacao.md

@@ -0,0 +1,105 @@
+# Instalação em projetos
+
+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
+
+```bash
+cd /caminho/do/projeto
+seedgrid-ai init --dry-run                 # revise o plano
+seedgrid-ai init --target both --mode shared
+seedgrid-ai doctor
+```
+
+Depois, abra uma **nova sessão** do Claude Code ou do Codex na pasta do projeto.
+
+Versione no Git: `.ai/` (inclusive `.ai/brain/`, cerca de 2 MB de Markdown; exceto `.ai/backups/`, que já se auto-ignora), `.claude/skills/`, `.agents/skills/`, os agentes nativos (se usados), `AGENTS.md`, `CLAUDE.md` e `.ai/toolkit-lock.json`. Assim toda a equipe recebe a mesma versão.
+
+## A base de conhecimento (`.ai/brain/`)
+
+Toda instalação traz as notas de documentação das extensions e dos componentes SeedGrid em `.ai/brain/SeedGrid/`. O bloco do `AGENTS.md` manda a IA consultá-las pelos índices antes de usar ou configurar qualquer extension ou componente, e responder "não encontrei" em vez de inventar. A pasta é gerenciada: edições locais geram conflito no `update`. Anotações do projeto vão em `.ai/local/`.
+
+As notas indicam, no frontmatter, o `commit` e a data (`analisado-em`) do código que descrevem. Se o projeto usa uma versão diferente das extensions, a IA é instruída a confirmar no código, no jar ou no pacote e a avisar.
+
+## Escolhendo target e modo
+
+- `--target claude`: instala skills só para o Claude Code e cria o bloco do `CLAUDE.md`. O `AGENTS.md` sempre recebe o bloco, porque é a fonte comum das instruções.
+- `--target codex`: instala skills em `.agents/skills/`; não cria `CLAUDE.md`.
+- `--mode native`: também gera subagentes nativos. No Codex, marque o projeto como confiável (o Codex pergunta ao abrir o projeto, ou configure `[projects.'<caminho>'] trust_level = "trusted"` em `~/.codex/config.toml`).
+
+`init` repetido sem opções reaproveita as opções do lock. Com opções diferentes, reconfigura a instalação: por exemplo, `init --mode shared` numa instalação native apaga os agentes nativos intactos.
+
+## Personalizando
+
+Não edite arquivos gerenciados. Use `.ai/local/` (veja `.ai/rules/personalizacao-local.md` no projeto):
+
+- `.ai/local/projeto.md`: stack, comandos de build e teste, convenções.
+- `.ai/local/fluxos.md`: fluxos obrigatórios.
+- `.ai/local/papeis/<id>.md`: complementos a um papel.
+
+Texto fora dos marcadores em `AGENTS.md` e `CLAUDE.md` é seu e é preservado em todas as operações.
+
+## Atualizando
+
+```bash
+seedgrid-ai status             # mostra se o CLI traz conteúdo mais novo
+seedgrid-ai update --dry-run
+seedgrid-ai update
+```
+
+`update` aplica o conteúdo empacotado no CLI **em execução** (ou `--source`). O jeito mais simples de sempre pegar o conteúdo mais recente é `npx @seedgrid/ai-toolkit@latest update`.
+
+### Aviso de versão nova
+
+`init`, `update`, `status` e `doctor` consultam o npm (somente leitura) para saber se existe uma versão publicada mais nova que o CLI em execução:
+
+- **Em terminal interativo**, `init`/`update` perguntam `Usar a X.Y.Z neste update? [Y/n]` e `status` pergunta `Atualizar este projeto agora? [Y/n]`. Com "Y", o comando é repassado para `npx @seedgrid/ai-toolkit@X.Y.Z ...` (versão exata). Com "n", segue com o CLI atual.
+- **Fora do terminal** (pipes, scripts, `--json`), só aparece um aviso com o comando a rodar; nunca há pergunta nem download.
+- Com `CI` definido, `--source`, `--no-update-check` ou `SEEDGRID_AI_NO_UPDATE_CHECK=1`, não há consulta.
+- A consulta usa `npm view` (respeita registry, proxy e `.npmrc`), fica em cache por 12 h em `~/.cache/seedgrid-ai/update-check.json` e, se falhar (sem rede, pacote inexistente), é ignorada em silêncio.
+
+A versão nova planeja de novo e continua abortando em conflitos: aceitar a atualização nunca sobrescreve customizações.
+
+## Conflitos
+
+Exemplo:
+
+```text
+Conflitos (1):
+  ! .ai/rules/coordenacao.md: modificado localmente desde a última instalação
+
+Operação abortada: nada foi alterado.
+```
+
+Opções:
+
+1. Mover a personalização para `.ai/local/` e restaurar o arquivo original (`git checkout -- <arquivo>` ou cópia do backup).
+2. Se o arquivo preexistente não era do toolkit, renomeá-lo ou removê-lo após conferir o conteúdo.
+3. Para blocos editados, devolver o interior dos marcadores ao texto original e levar as mudanças para fora deles.
+
+## Removendo
+
+```bash
+seedgrid-ai remove --dry-run
+seedgrid-ai remove
+```
+
+Remove arquivos gerenciados intactos, os blocos intactos (e `CLAUDE.md`/`AGENTS.md` se o toolkit os criou e ficaram vazios) e o lock. Mantém `.ai/local/`, `.ai/backups/` e qualquer arquivo de terceiros. Pastas só são apagadas se ficarem vazias.
+
+## Recuperação
+
+Cada operação que altera ou apaga arquivos existentes cria `.ai/backups/<operação>/` com:
+
+- cópias dos arquivos, nos mesmos caminhos relativos ao projeto;
+- `operation.json` com o tipo de operação e a lista de arquivos.
+
+Para restaurar manualmente, copie de volta para a raiz do projeto os arquivos listados em `operation.json` (não copie o próprio `operation.json`). Exemplo com Git Bash, Linux ou macOS:
+
+```bash
+B=.ai/backups/20261014T103812Z-22cd26
+(cd "$B" && find . -type f ! -name operation.json) | while read -r f; do cp "$B/$f" "$f"; done
+```
+
+O comando restaura também `.ai/toolkit-lock.json` quando a operação o alterou, mantendo lock e arquivos coerentes. Em seguida, rode `seedgrid-ai status`. Apague `.ai/backups/` quando não precisar mais.
+
+Se a mensagem disser "Rollback INCOMPLETO", os arquivos listados não puderam ser restaurados automaticamente: use o backup indicado.

package/docs/manutencao.md

@@ -0,0 +1,115 @@
+# Manutenção
+
+## Ciclo de desenvolvimento
+
+```bash
+npm install
+npm run build          # src/ -> dist/
+npm test               # compila src/ + tests/ em build-test/ e roda node:test
+node dist/cli.js validate
+```
+
+Os testes criam projetos em diretórios temporários com espaços e Unicode no caminho e cobrem: instalação nova, repetição sem mudanças, atualização de conteúdo intacto, conflito local, preservação de texto antes e depois dos marcadores, dry-run sem escrita, remoção, nomes inválidos, referências quebradas, links para fora do projeto, lock adulterado, CRLF e falha de escrita com rollback. Eles não dependem de Claude Code ou Codex instalados (`SEEDGRID_AI_SKIP_TOOL_DETECTION=1`).
+
+Para testar conteúdo em edição sem recompilar o pacote:
+
+```bash
+node dist/cli.js init --source ./seedgridKB --project ../projeto-descartavel --dry-run
+```
+
+## Versionamento
+
+- `package.json` `version`: versão do CLI **e** do pacote distribuído.
+- `content/manifest.json` `contentVersion`: versão do conteúdo. Aumente a cada mudança em `content/`.
+- `schemaVersion` (manifesto) e `lockVersion` (lock) só mudam com alterações de formato; nesse caso, implemente a leitura do formato anterior ou documente a migração.
+
+Ao mudar conteúdo, aumente `contentVersion` e, para publicar, a versão do pacote.
+
+## Adicionando conteúdo
+
+- Papel: crie `seedgridKB/SeedGrid/Toolkit/agents/<id>.md` seguindo [formato.md](formato.md) e adicione-o ao componente `agents` do manifesto.
+- Skill: crie `seedgridKB/SeedGrid/Toolkit/skills/<nome>/SKILL.md` (+ recursos) e um componente `skill:<nome>`.
+- Rode `node dist/cli.js validate` e `npm test`.
+
+## Ampliando os adaptadores
+
+Antes de gerar qualquer campo novo para uma ferramenta, confira a documentação oficial atual e a versão instalada, faça o smoke test e registre o resultado em [compatibilidade.md](compatibilidade.md). Não acrescente versões a `validatedVersions` sem esse teste.
+
+## Smoke test manual
+
+Use uma pasta descartável. Nenhum passo publica ou altera serviços externos.
+
+```bash
+mkdir "/tmp/proj teste ção" && cd "/tmp/proj teste ção"
+node <toolkit>/dist/cli.js init --target both --mode native
+node <toolkit>/dist/cli.js doctor --probe
+
+# Claude Code: skills, subagentes e instruções
+claude -p "Sem executar ferramentas, liste: (1) skills de projeto disponíveis; (2) tipos de subagente personalizados; (3) a primeira linha do bloco SeedGrid AI Toolkit recebido."
+
+# Codex: skills e instruções (projeto não confiável)
+codex exec --skip-git-repo-check --ephemeral -s read-only "Sem executar comandos, liste: (1) skills do projeto; (2) agentes personalizados; (3) a primeira linha do bloco SeedGrid AI Toolkit do AGENTS.md."
+
+# Codex: agentes nativos (confiança só nesta execução; use o caminho absoluto do Windows/Unix)
+codex exec --skip-git-repo-check --ephemeral -s read-only \
+  -c "projects={'<caminho absoluto>'={trust_level=\"trusted\"}}" \
+  "Sem comandos de shell: liste os agent_type personalizados aceitos por spawn_agent e inicie um 'revisor' com a tarefa 'Responda apenas: papel revisor ativo'."
+```
+
+Resultado esperado: 3 skills, 5 agentes e o bloco citado em cada ferramenta. Registre versões e resultados em [compatibilidade.md](compatibilidade.md).
+
+## Empacotamento
+
+```bash
+npm pack --dry-run      # lista o que entraria no tarball
+npm pack                # gera seedgrid-ai-toolkit-<versão>.tgz
+```
+
+`prepack` limpa e recompila `dist/`. O campo `files` do `package.json` inclui apenas `dist/`, `docs/`, `README.md`, `LICENSE` e, do vault, `seedgridKB/manifest.json` e `seedgridKB/SeedGrid/`. Confira na listagem que:
+
+- `seedgridKB/manifest.json` e todos os arquivos que o manifesto instala estão presentes, e nada além disso do vault (sem `.obsidian/`, `AGENTS.md` e `CLAUDE.md` de manutenção);
+- não há `.ai/backups/`, `build-test/`, `tests/`, `node_modules/`, `.env*`, `*.tgz` nem arquivos `*.seedgrid-tmp-*`.
+
+Teste o tarball sem publicar (o `npx <arquivo.tgz>` não infere o binário de um tarball local; use `npm exec --package`):
+
+```bash
+cd ../projeto-descartavel
+npm exec --yes --package=../seedgrid-ia/seedgrid-ai-toolkit-0.2.0.tgz -- seedgrid-ai init --dry-run
+```
+
+## Publicação no npm
+
+O pacote é público: `@seedgrid/ai-toolkit`, no mesmo escopo de `@seedgrid/fe-components`. O comando instalado é `seedgrid-ai`.
+
+### Versões
+
+O pacote e o conteúdo usam o mesmo número. Para lançar uma versão:
+
+1. Atualize `contentVersion` em `content/manifest.json` (se o conteúdo mudou).
+2. `npm version <x.y.z>` atualiza o `package.json`, faz o commit e cria a tag `v<x.y.z>`.
+3. `git push --follow-tags` dispara o workflow de publicação.
+
+Versões com sufixo (`0.3.0-beta.1`) são publicadas com a dist-tag `next` e marcadas como pré-release; as demais vão para `latest`.
+
+### Workflows
+
+- `.github/workflows/ci.yml`: em push para `main` e em pull requests, roda testes, build, `validate` e `scripts/check-pack.mjs` no Ubuntu e no Windows, com Node 22 e 24.
+- `.github/workflows/release.yml`: em tags `v*`, repete as verificações e exige tag igual à versão e `repository` preenchido. Depois publica no npm com provenance e cria a Release do GitHub com o `.tgz` anexado.
+
+`node scripts/check-pack.mjs` pode ser rodado localmente: confere se todo arquivo do manifesto está no pacote e se não há fonte, testes, backups, `.env`, `.npmrc` ou `.tgz`.
+
+### Primeira publicação (uma vez)
+
+1. Crie o repositório no GitHub e adicione ao `package.json`:
+   ```json
+   "repository": { "type": "git", "url": "git+https://github.com/<org>/<repo>.git" },
+   "homepage": "https://github.com/<org>/<repo>#readme",
+   "bugs": { "url": "https://github.com/<org>/<repo>/issues" }
+   ```
+   A URL precisa ser exatamente a do repositório que publica; o npm a compara ao validar a provenance.
+2. No GitHub, crie o environment `npm` (Settings → Environments). Ele permite exigir aprovação antes de publicar.
+3. Para a primeira versão, o pacote ainda não existe no npm. Escolha uma opção:
+   - **Manual:** com uma conta que publica no escopo `@seedgrid`, rode `npm login` e `npm publish --access public` localmente.
+   - **Pelo workflow:** crie um token granular de publicação no npmjs.com e salve-o como segredo `NPM_TOKEN` no environment `npm`.
+4. No npmjs.com, abra o pacote → Settings → **Trusted Publisher** e cadastre GitHub Actions: organização, repositório, workflow `release.yml` e environment `npm`.
+5. Apague o segredo `NPM_TOKEN` (se criou). Daqui em diante, o workflow publica via OIDC, sem token guardado.

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@seedgrid/ai-toolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Instala agentes, skills, regras, templates e referências versionados em projetos locais para Claude Code e Codex.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SeedGrid/seedgrid-ai.git"
+  },
+  "homepage": "https://github.com/SeedGrid/seedgrid-ai#readme",
+  "bugs": {
+    "url": "https://github.com/SeedGrid/seedgrid-ai/issues"
+  },
+  "bin": {
+    "seedgrid-ai": "dist/cli.js"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist/",
+    "docs/",
+    "seedgridKB/manifest.json",
+    "seedgridKB/SeedGrid/"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test \"build-test/tests/**/*.test.js\"",
+    "validate-content": "npm run build && node dist/cli.js validate",
+    "prepack": "npm run clean && npm run build",
+    "clean": "node -e \"for (const d of ['dist','build-test']) require('node:fs').rmSync(d,{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "smol-toml": "^1.4.2",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "typescript": "~5.9.3"
+  }
+}