@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/docs/guides/tools-and-testing.md

@@ -0,0 +1,85 @@
+---
+description: Preparo das ferramentas e escolha de verificações reais.
+---
+
+# Ferramentas e testes
+
+O kit traz definições e automações. Instalar o kit não instala todas as tools
+nem escolhe a stack da aplicação. Consulte o [catálogo][tools].
+
+## Runtime e preparo
+
+O núcleo usa Node.js 24+ com npm. O launcher aceita Node 18+ e prepara o runtime
+atual quando necessário. Sem Node, o agente precisa instalá-lo pelo mecanismo
+do sistema operacional antes de iniciar `npx`.
+
+Para preparar somente o runtime a partir do hub:
+
+```console
+node .pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs --runtime-only
+```
+
+O mesmo JavaScript atende aos sistemas suportados. Não há bootstrap PowerShell,
+SH ou Bash no kit. O executável nativo `tar` é usado sem shell para extrair o
+arquivo oficial após conferir SHA-256. Veja o [guia do bootstrap][bootstrap].
+
+Quando a tarefa pedir instalação das ferramentas:
+
+```console
+node .pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs setup
+```
+
+`setup` reutiliza instalações saudáveis e verifica as compatíveis. Um nome
+ou grupo limita a seleção. `check`, `info` e `run` não trocam uma consulta
+por instalação. Downloads, caches e recibos permanecem locais e ignorados.
+
+## Escolher a prova
+
+| Mudança | Verificação |
+| --- | --- |
+| Lógica ou API | Testes e assertivas de resultado. |
+| Fluxo web | Navegador real, ações e resultado visível. |
+| Aplicativo desktop | Abrir o aplicativo e executar o fluxo. |
+| Documento visual | Renderizar ou abrir o artefato e inspecionar. |
+| Gerador e Git | Instalar, sincronizar e comparar arquivos/índice. |
+
+Use [verificar-trabalho][verify] para vincular aceites às provas. Web pode usar
+[agent-browser][browser] ou o conector Playwright; desktop pode usar
+[agent-desktop][desktop]. Confira console, rede, permissões e efeitos reais.
+Uma captura isolada não demonstra o funcionamento completo.
+
+## Verificar o AgentDevKit
+
+No checkout, `npm test` verifica o produto; `npm run test:infra` verifica as
+automações compartilhadas; `npm run check` valida as fontes. Os perfis de
+[CI](../maintainers/maintenance.md) evitam repetir a suíte completa em cada sistema.
+
+Os testes do produto ficam em `tests/`, na raiz. Os testes compartilhados
+ficam em `scripts/<nome>/tests/` dentro do hub. Em uma aplicação atendida,
+o código de testes segue os diretórios acordados para aquele projeto.
+
+A [matriz de maturidade][matrix] usa oito projetos sintéticos. Ela comprova
+contratos do kit; não aprova um produto real nem certifica todos os aplicativos.
+Os pareceres simulados dessa matriz não substituem revisão independente.
+Use `npm run examples` para preparar as cópias e `npm run test:examples`
+para executá-las em `examples/generated/`. O [guia dos exemplos][examples]
+explica cada cenário; o [guia de desenvolvimento](../maintainers/development.md)
+reúne as verificações do repositório.
+
+## Guardar os resultados
+
+Código de testes e fixtures são versionados. Relatórios, capturas, vídeos,
+downloads e saídas locais são ignorados, inclusive `.playwright*` em qualquer
+caixa. Registre passou, falhou ou não verificado; não transforme ausência de
+prova em sucesso. Feche a entrega pela [revisão][review].
+
+[Wiki](../README.md) · [Recursos](resources.md)
+
+[tools]: ../../.pbai4devs/tools/README.md
+[bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
+[verify]: ../../.pbai4devs/skills/projeto/verificar-trabalho/SKILL.md
+[browser]: ../../.pbai4devs/tools/agent-browser/README.md
+[desktop]: ../../.pbai4devs/tools/agent-desktop/README.md
+[matrix]: ../../.pbai4devs/scripts/testar-maturidade/README.md
+[review]: ../../.pbai4devs/commands/revisar-entrega/COMMAND.md
+[examples]: https://github.com/pathbit/AgentDevKit/tree/master/examples

package/docs/guides/troubleshooting.md

@@ -0,0 +1,151 @@
+---
+description: Diagnóstico, conflitos, backups e recuperação do AgentDevKit.
+---
+
+# Solução de problemas
+
+Comece pelo erro completo e pelo diretório usado. Nos exemplos, `agentdevkit`
+representa o executável obtido por npx, conforme a [referência da CLI][cli].
+O comando completo está na [instalação](installation.md).
+
+## Diagnóstico rápido
+
+```console
+agentdevkit --version
+agentdevkit doctor --target "./meu projeto" --json
+agentdevkit sync --check --target "./meu projeto" --json
+```
+
+`doctor` verifica a instalação do kit. Para as ferramentas, use
+`agentdevkit tools check all`; para o aplicativo, use os testes do projeto.
+Antes de compartilhar uma saída, remova dados privados e caminhos pessoais.
+
+Se faltarem recursos, confira a seleção com `agentdevkit agents`.
+Para incluir um cliente, use `agentdevkit agents codex,claude` com a lista
+completa, ou `agentdevkit agents all`. Reabra a sessão do cliente quando ele
+exigir recarregar as skills. Pastas compartilhadas podem atender mais de um
+agente; arquivos próprios também podem manter uma pasta após a desmarcação.
+
+| Sintoma ou código | Próxima ação |
+| --- | --- |
+| `node` ou `npx` não encontrado | Siga [sem Node/npm][runtime]. |
+| `E401` ou `E403` no registry | Confira se usa o [npm público][packages]. |
+| `E404` ao baixar o pacote | Confira registry, versão e permissão. |
+| `E_ARGS` | Confira comando e aspas com `agentdevkit --help`. |
+| `E_MISSING` | Confirme `--target`; inicialize o projeto correto. |
+| `E_TARGET`, `E_SYMLINK` | Use a pasta real, fora dos diretórios reservados. |
+| `E_CONFLICT` ou lista `conflicts` | Revise o plano e os arquivos afetados. |
+| `E_STATE`, `E_BLOCK`, `E_TEMPLATE` | Restaure o arquivo; não invente hashes. |
+| `E_CHANGED` | Um arquivo mudou durante a operação; gere outro plano. |
+
+## Conflitos e backups
+
+Simule antes de substituir uma alteração própria:
+
+```console
+agentdevkit update --target "./meu projeto" --dry-run --json
+```
+
+Compare cada `conflicts` com o que deseja manter. Edite a origem em
+`.pbai4devs/`, não os apontamentos gerados, quando estiver personalizando um
+recurso. Use `sync` para atualizar suas derivações. `update` reaplica os
+recursos do pacote invocado e pode conflitar com essa personalização.
+
+Quando a substituição for intencional, repita com `--force`. Arquivos
+existentes afetados recebem backup antes da escrita, inclusive em operações
+normais. O campo `backup` informa uma pasta relativa ao projeto:
+
+```text
+.agent-tests/agentdevkit/backups/<identificador>/
+```
+
+O layout interno repete os caminhos originais. Para recuperar:
+
+1. Pare as edições e faça uma cópia do projeto ou um checkpoint no Git.
+2. Compare os arquivos do backup com os atuais no editor.
+3. Restaure somente os arquivos desejados, preservando edições posteriores.
+4. Execute `doctor` e revise o novo plano antes de aplicar qualquer correção.
+
+Não existe comando `undo`. Copiar o backup inteiro não remove arquivos que a
+operação criou; um rollback completo exige conferir o plano e o diff do Git.
+Os backups são locais e ignorados; não substituem o controle de versão.
+
+## Estado ou apontamentos inconsistentes
+
+`missing`, `modified` e `outdated` em `issues` indicam arquivo ausente,
+conteúdo alterado ou derivação pendente. Use `sync --check` para inspecionar;
+se as alterações da origem forem intencionais, execute `sync` e confira de novo.
+
+Se `.pbai4devs/estado/agentdevkit.json` estiver inválido, recupere um backup
+local coerente com os arquivos correspondentes. O estado pessoal não é
+versionado. Não invente hashes nem apague o estado para ocultar conflitos;
+peça ao agente para comparar as fontes e planejar o reparo com `init`/`sync`.
+
+Entradas humanas permanecem separadas das geradas. Na migração de versões
+antigas, o kit retira somente seu bloco reconhecido e preserva o texto humano.
+Não altere os marcadores dos blocos que ainda serão migrados.
+Não transforme diretórios de agentes ou o hub em links simbólicos.
+Destinos dentro de `.git`, `node_modules` ou `.pbai4devs` são recusados,
+inclusive com variações de maiúsculas/minúsculas.
+
+Na CLI, `sync --force` substitui conflitos identificados, com backup, e
+preserva arquivos nativos próprios que não são do kit. O script compartilhado
+`sincronizar-agentes` tem um modo `--force` mais amplo: pode limpar conteúdo
+extra nas áreas de skills, agents, commands e rules. Prefira a CLI para manter
+a instalação; não trate esses dois comandos como equivalentes.
+
+## Download, plataforma ou ferramenta falhando
+
+Se uma instalação antiga configurou `@pathbit` para o GitHub Packages,
+atualize somente esse escopo e repita a instalação:
+
+```console
+npm config set @pathbit:registry https://registry.npmjs.org --location=user
+```
+
+O pacote público não exige autenticação para instalar. Publicar uma versão
+exige acesso de mantenedor no npm; são operações diferentes.
+
+Confira acesso ao GitHub, ao registro npm e a `nodejs.org`, conforme a etapa.
+Mantenha a verificação de certificados e hashes; resolva proxy, rede ou
+dependências do SO e repita. Não troque por um binário de outra arquitetura.
+O launcher aceita Node.js 18+ e prepara Node 24+ para o núcleo. Sem Node/npm,
+o agente precisa instalar o runtime pelo mecanismo do SO antes de usar npx.
+
+`tools setup` reutiliza instalações saudáveis e verifica as compatíveis.
+Não aplicável em uma seleção geral não significa “instalado”. Esse preparo
+também não baixa browsers, concede permissões desktop ou inicia aplicativos.
+Veja [ferramentas][tools] para requisitos adicionais da tarefa.
+
+Um lock indica instalação em andamento ou interrompida. Aguarde a operação
+ativa. Se o processo terminou, tente `agentdevkit tools unlock <nome>`; só um lock
+local com PID comprovadamente morto é removido. Não apague locks ativos ou
+indeterminados para forçar duas instalações ao mesmo tempo.
+
+## Sessões, loops ou calculadora abrindo
+
+O AgentDevKit não agenda sessões, abre a calculadora nem inicia loops por
+conta própria. Uma execução explícita de ferramenta pode abrir o aplicativo
+solicitado. Se algo continua executando, identifique a sessão, tarefa do
+editor, extensão ou processo que o iniciou e pare-o pela interface responsável.
+Apagar apenas os logs não interrompe um processo que continua gravando.
+
+Pastas de clientes e saídas como `.opencode/opencode-loop`, `.playwright*`,
+caches e relatórios
+não devem ser versionados. Verifique com `git status` e `git check-ignore -v
+<caminho>`. Se um arquivo já estava rastreado, acrescentar um ignore não o
+retira automaticamente do Git; revise a remoção do índice sem apagar dados.
+
+O `.gitignore` do hub não controla pastas irmãs. Confira a proteção local
+gerada pelo kit, incluindo `info/exclude` nos repositórios Git. Preserve
+configurações humanas em `.github` e `.vscode` ao migrar arquivos antigos.
+
+Para pedir ajuda, inclua SO/arquitetura, versões de Node/npm/AgentDevKit,
+comando executado, código de saída e trecho relevante do JSON, sem segredos.
+Use as [issues do projeto][issues] ou volte ao [índice](../README.md).
+
+[cli]: cli.md
+[runtime]: installation.md#pré-requisitos
+[tools]: ../../.pbai4devs/scripts/preparar-ferramentas/README.md
+[issues]: https://github.com/pathbit/AgentDevKit/issues
+[packages]: ../maintainers/packages.md#instalar-no-projeto

package/docs/guides/workflow.md

@@ -0,0 +1,130 @@
+---
+description: Do preparo do kit à implementação e revisão de uma entrega.
+---
+
+# Fluxo de trabalho
+
+[Documentação](../README.md) · [Instalação](installation.md) ·
+[Recursos](resources.md) · [Ferramentas e testes](tools-and-testing.md)
+
+O AgentDevKit organiza o trabalho; ele não substitui decisões do projeto.
+Instalar o kit cria sua estrutura de apoio, sem criar um produto, escolher
+uma stack ou gerar PRD, design e specs automaticamente.
+
+## 1. Identificar a situação
+
+Na preparação do kit, escolha os agentes que usa: a CLI pergunta em um terminal
+interativo ou aceita `--agents codex,claude`. Um agente de desktop deve reunir
+essa escolha com você antes de executar a instalação; não deve deduzi-la pelo
+nome do aplicativo ou pelas pastas existentes. Sem resposta disponível, o
+padrão é `all`. A seleção salva continua nas atualizações e sincronizações.
+Use `agents` para consultar ou alterar depois; veja a [referência](cli.md).
+
+Use `doctor` para conferir o kit e `next` para consultar a próxima etapa.
+Nos exemplos, `agentdevkit` representa a CLI; no checkout, use
+`npm run cli -- <comando>`. A invocação por npx está na instalação.
+
+```sh
+agentdevkit doctor --target .
+agentdevkit next --target .
+```
+
+O diagnóstico descreve sinais e arquivos existentes. Ele não aprova
+documentos, não comprova comportamento e não autoriza substituir decisões.
+
+| Situação | Comece por |
+| --- | --- |
+| Só está instalando os agentes | Manter modelos; não iniciar o produto. |
+| Projeto novo, ainda sem decisões | [configurar-projeto][configurar]. |
+| Aplicação existente que precisa rodar | [preparar-dev][preparar]. |
+| Nova funcionalidade em projeto existente | Reutilizar documentos e planejar. |
+
+## 2. Reunir as perguntas no início
+
+Antes de escrever documentos ou código, leia o contexto já disponível.
+Reúna as dúvidas que alteram objetivo, escopo, dependências ou critérios.
+Não pergunte novamente o que o usuário já decidiu ou o projeto já registra.
+A escolha dos clientes precede o preparo opcional de ferramentas; não aprova
+downloads, início do produto ou mudanças na aplicação.
+
+```text
+Use configurar-projeto. Primeiro leia o repositório e reúna as dúvidas.
+Neste momento quero apenas preparar os agentes; não crie produto ou aplicação.
+```
+
+Quando o produto começar, combine os caminhos dos documentos no estado de
+configuração. Não presuma que todo projeto usa as mesmas pastas de documentos.
+O registro é `.pbai4devs/estado/configuracao/ESTADO.md`.
+
+## 3. Definir produto e experiência
+
+[criar-prd][prd] define problema, público, escopo, limites e sucesso esperado.
+[criar-ux-ui][ux] define jornadas e interface. Quando UX/UI não se aplicar,
+registre a justificativa e sua aprovação; ausência de arquivo não significa
+aprovação. Os modelos são preenchidos com respostas reais.
+
+Cada documento começa como rascunho. Uma alteração material exige revisar
+sua aprovação e o impacto nos documentos dependentes.
+
+## 4. Aprovar o desenho técnico
+
+[criar-design-doc][design] usa o produto aprovado para definir arquitetura,
+tecnologia, integrações, riscos e alternativas. Esta etapa registra decisões;
+ela não deve iniciar a aplicação antes da aprovação do trabalho necessário.
+
+[gerenciar-roadmap][roadmap] organiza incrementos, dependências e releases.
+Não invente datas ou funcionalidades futuras para preencher o planejamento.
+
+## 5. Criar uma spec executável
+
+[criar-spec][spec] exige PRD/design aprovados e UX/UI aprovado ou justificado.
+A spec delimita um incremento e vincula seus critérios, como `AC-001`, às
+provas planejadas: método, pré-requisito, assertiva e evidência local.
+
+```text
+Use criar-spec para este incremento. Reúna as dúvidas antes de escrever.
+Vincule os documentos existentes e defina como provar cada critério de aceite.
+```
+
+## 6. Aprovar o plano antes de implementar
+
+[implementar-spec][implementar] começa em leitura e planejamento: examina a
+spec, o código, as dependências e as dúvidas restantes. Apresenta tarefas,
+decisões, riscos e verificação, aguardando a aprovação necessária do plano.
+
+Depois do plano aprovado, complete a configuração técnica que faltar usando
+as decisões já aprovadas. Só marque a configuração como concluída com prova.
+Implemente o escopo da spec; não antecipe recursos de ciclos futuros.
+
+## 7. Provar e revisar a entrega
+
+Use [verificar-trabalho][verificar] para executar as provas relevantes.
+Código e fixtures de teste são versionados; relatórios e capturas ficam em
+`.agent-tests/<referencia>/<execucao>/`, ignorados pelo Git.
+
+[atualizar-documentacao][documentacao] mantém os documentos afetados coerentes.
+O [comando revisar-entrega][revisao] reúne critérios, evidências e revisão
+independente. Seu fluxo é `prepare` → revisão → `seal` → `check`.
+Critério sem prova, falha ou revisão pendente impede concluir a entrega.
+
+## Em um projeto existente
+
+Preparar o ambiente não exige recriar PRD/design/spec ou reorganizar o código.
+Preserve dados, lockfiles, configurações e comandos reais. Uma nova mudança
+funcional precisa de escopo próprio; um reparo não autoriza uma migração ampla.
+Mesmo uma mudança sem spec exige critérios claros e revisão da entrega.
+
+**[ Próximo passo ]** Consulte `next` e use a skill indicada, preservando as
+decisões existentes. Consulte [recursos](resources.md) se faltar um fluxo.
+
+[configurar]: ../../.pbai4devs/skills/projeto/configurar-projeto/SKILL.md
+[preparar]: ../../.pbai4devs/skills/projeto/preparar-dev/SKILL.md
+[prd]: ../../.pbai4devs/skills/produto/criar-prd/SKILL.md
+[ux]: ../../.pbai4devs/skills/produto/criar-ux-ui/SKILL.md
+[design]: ../../.pbai4devs/skills/produto/criar-design-doc/SKILL.md
+[roadmap]: ../../.pbai4devs/skills/specs/gerenciar-roadmap/SKILL.md
+[spec]: ../../.pbai4devs/skills/specs/criar-spec/SKILL.md
+[implementar]: ../../.pbai4devs/skills/specs/implementar-spec/SKILL.md
+[verificar]: ../../.pbai4devs/skills/projeto/verificar-trabalho/SKILL.md
+[documentacao]: ../../.pbai4devs/skills/projeto/atualizar-documentacao/SKILL.md
+[revisao]: ../../.pbai4devs/commands/revisar-entrega/COMMAND.md

package/docs/maintainers/README.md

@@ -0,0 +1,12 @@
+---
+description: Desenvolvimento, contribuição e publicação do AgentDevKit.
+---
+
+# Manutenção
+
+- [Desenvolvimento](development.md)
+- [Manutenção e releases](maintenance.md)
+- [Pacote npm público](packages.md)
+- [Participação na comunidade](community.md)
+
+[Voltar à documentação](../README.md)

package/docs/maintainers/community.md

@@ -0,0 +1,49 @@
+---
+description: Como relatar problemas e propor melhorias para o AgentDevKit.
+---
+
+# Participar da evolução
+
+Use as [issues do AgentDevKit][issues] para relatar problemas e sugerir melhorias.
+Procure relatos semelhantes antes de abrir um novo. Uma reação ou um exemplo
+reproduzível na issue existente ajuda a reunir o contexto.
+
+## Relatar um problema
+
+Escolha [Relatar um problema][bug]. O formulário pede versão do kit, sistema,
+agente/editor, comando ou ação, passos, resultado esperado e observado.
+Logs são opcionais: inclua só o trecho necessário e remova dados privados.
+
+Se não souber uma informação, explique isso. Um exemplo pequeno que reproduz
+o problema costuma ser mais útil que um repositório inteiro.
+
+## Propor uma melhoria
+
+Escolha [Sugerir uma melhoria][feature] e descreva o problema antes da solução.
+Informe quem se beneficia, um exemplo de uso e como reconhecer o resultado.
+O formulário também aceita melhorias na documentação.
+
+Issues não são executadas automaticamente por agentes. Uma proposta precisa
+de triagem e definição de escopo antes de virar implementação ou release.
+Não há prazo de atendimento prometido.
+
+## Acompanhar e contribuir
+
+Os labels `bug`, `enhancement` e `documentation` ajudam a classificar o assunto.
+Mantenedores podem pedir informações, reunir duplicatas e vincular a mudança
+a um PR. Consulte o [roadmap](../product/roadmap.md) para o escopo registrado.
+
+Para contribuir com código ou documentos, siga [Contribuir][contrib]. O modelo
+de PR pede problema, mudança e verificação. Após a revisão, as mudanças passam
+pelo CI; a publicação segue o [fluxo de releases](maintenance.md).
+
+Issues e anexos de um repositório público são públicos. Não envie tokens,
+senhas, dados pessoais ou acesso a serviços. Resultados locais de testes
+continuam fora do Git, conforme o [guia de ferramentas](../guides/tools-and-testing.md).
+
+[Wiki](../README.md) · [Solução de problemas](../guides/troubleshooting.md)
+
+[issues]: https://github.com/pathbit/AgentDevKit/issues
+[bug]: https://github.com/pathbit/AgentDevKit/issues/new?template=bug_report.yml
+[feature]: https://github.com/pathbit/AgentDevKit/issues/new?template=feature_request.yml
+[contrib]: ../../CONTRIBUTING.md

package/docs/maintainers/development.md

@@ -0,0 +1,54 @@
+---
+description: Guia rápido para desenvolver e validar o AgentDevKit.
+---
+
+# Desenvolver o AgentDevKit
+
+Comece com Git, Node.js 24+ e npm. Na raiz do checkout:
+
+```console
+npm ci --ignore-scripts
+npm run check
+npm test
+```
+
+## Onde trabalhar
+
+| Pasta | Conteúdo |
+| --- | --- |
+| [`src/`](../../src/README.md) | Código da CLI e do instalador. |
+| [`bin/`](../../bin/README.md) | Executável do pacote. |
+| [`tests/`][tests] | Testes do produto. |
+| [`scripts/`][scripts] | Verificação, build e publicação. |
+| [`examples/`][examples] | Exemplos para estudar o resultado. |
+| [`.pbai4devs/`](../../.pbai4devs/README.md) | Recursos compartilhados dos agentes. |
+| [`docs/`](../README.md) | Guias, decisões e especificações. |
+
+## Escolha a próxima ação
+
+| Objetivo | Comando |
+| --- | --- |
+| Conhecer os comandos da CLI local | `npm run cli -- --help` |
+| Gerar exemplos com `.claude`, `.codex` e outros | `npm run examples` |
+| Executar os oito cenários de exemplo | `npm run test:examples` |
+| Conferir recursos e documentação | `npm run check` |
+| Testar o produto | `npm test` |
+| Verificar tudo e o pacote real | `npm run verify` |
+| Gerar somente o tarball | `npm run build` |
+
+`generate` é um alias para gerar os exemplos. `agents:sync` sincroniza uma
+configuração local de agentes do próprio checkout, quando adotada de forma
+explícita. O projeto não precisa de todas as pastas de clientes na raiz.
+
+Edite fontes e templates, não os arquivos gerados. Testes e fixtures entram
+no Git; relatórios, caches e `examples/generated/` ficam locais. Antes de
+enviar uma alteração, siga [contribuição](../../CONTRIBUTING.md) e a
+[revisão de entrega][review]. A [publicação](maintenance.md) reaproveita o
+artefato aprovado pelo CI.
+
+[Wiki](../README.md) · [Exemplos][examples]
+
+[review]: ../../.pbai4devs/commands/revisar-entrega/COMMAND.md
+[tests]: https://github.com/pathbit/AgentDevKit/tree/master/tests
+[scripts]: https://github.com/pathbit/AgentDevKit/tree/master/scripts
+[examples]: https://github.com/pathbit/AgentDevKit/tree/master/examples

package/docs/maintainers/maintenance.md

@@ -0,0 +1,104 @@
+---
+description: Verificação, pacotes e releases do AgentDevKit.
+---
+
+# Manutenção e releases
+
+Para atualizar o kit em um projeto, use [instalação](../guides/installation.md).
+Este guia explica como manter e publicar o gerador.
+
+## Manter fontes e guias
+
+Edite `src/` para o código, `tests/` para os testes e `.pbai4devs/` para os
+recursos compartilhados. Documente objetivo, pré-requisito, exemplo e resultado
+esperado. Use links para os detalhes e evite repetir a mesma regra.
+
+Ao mudar layouts, revise templates, compatibilidade e testes. Ao mudar comandos,
+revise ajuda, idiomas e exemplos. Markdown começa com frontmatter e H1.
+Resultados e capturas de verificação permanecem ignorados.
+
+## Verificar sem desperdiçar CI
+
+O CI tem quatro perfis:
+
+| Perfil | Responsabilidade |
+| --- | --- |
+| Linux / Node 24 | Fontes, produto, infraestrutura, lint e pacote real. |
+| Windows / Node 24 | Portabilidade da CLI, arquivos e runtime. |
+| macOS / Node 24 | Portabilidade da CLI, arquivos e runtime. |
+| Linux / Node 26 | Smoke de compatibilidade. |
+
+A distribuição real é testada uma vez no perfil completo. Os outros perfis
+validam seus riscos específicos. Execuções antigas da mesma referência podem
+ser canceladas quando substituídas, sem cancelar uma publicação em andamento.
+
+`npm run verify` executa o perfil completo. `ci:portable` e `ci:smoke`
+executam os demais perfis localmente. `npm run test:examples` verifica os
+cenários em `examples/generated/` quando a mudança afeta a geração.
+A [contribuição](../../CONTRIBUTING.md) explica os checks durante o
+desenvolvimento.
+
+## Gerar um pacote
+
+O [CI][ci] roda em pushes e PRs; também pode ser iniciado em **Run workflow**.
+O perfil completo produz `agentdevkit-<versão>.tgz`, `SHA256SUMS`, notas e
+manifesto. O artifact inclui commit, execução e checksum para identificar
+exatamente o que foi testado. Downloads do Actions exigem login e expiram.
+A instalação usa o pacote nomeado no [npm público](packages.md);
+as releases preservam artefatos e checksums para auditoria.
+
+Para investigar localmente:
+
+```console
+npm run build
+```
+
+O resultado fica em `.agent-tests/release/<versão>/`. Esse comando não publica
+nada. Nunca versione o tarball ou seus relatórios.
+`pack:release` permanece disponível com o mesmo comportamento.
+
+## Publicar uma versão
+
+1. Atualize versão e lockfile, changelog, exemplos e escopo da entrega.
+2. Conclua testes, documentação e revisão independente.
+3. Envie o commit à branch principal e aguarde o CI aprovado.
+4. Crie e envie a tag `v<versão>` para esse mesmo commit.
+
+O [workflow de release][release] localiza o CI aprovado de um push na branch
+principal, confere o commit e baixa seu artifact por ID. Verifica procedência,
+versão e checksum antes de publicar. Não repete a suíte nem reempacota.
+Também envia o pacote ao [npm público](packages.md), confere sua
+integridade no registro e testa versão, instalação, diagnóstico e sincronização
+com a CLI instalada por ele.
+
+Se o artifact expirou, reexecute o CI original do push e depois a release.
+Uma execução manual de CI serve para diagnóstico, mas não substitui essa
+procedência. Uma release existente não é sobrescrita.
+
+Se o upload falhar após a criação do rascunho, ele permanece privado. Confira
+o rascunho antes de tentar novamente: o publicador não substitui uma release
+existente, mesmo em rascunho. Remova somente o rascunho incompleto dessa
+tentativa após conferir a origem; nunca apague uma release publicada para
+repetir o fluxo.
+
+Para reiniciar uma publicação que falhou, use **Re-run failed jobs** ou
+`gh workflow run release.yml --ref vX.Y.Z` com a tag real. A publicação prioriza
+o secret `NPMJS_TOKEN` do repositório; sem ele, usa OIDC, conforme
+[publicação](packages.md).
+
+Se a release já existe e falta somente o pacote no registro, use o modo
+`package_only` descrito em [pacote npm](packages.md#publicar-pelo-actions).
+Ele não tenta recriar a release existente.
+
+## Conferir a entrega pública
+
+Confira a versão na [página do pacote][package] e instale pelo nome em um
+projeto descartável, seguindo [pacote npm](packages.md). Teste seleção,
+`doctor` e `sync --check`. Compare a integridade do registro com o artefato
+aprovado; uma aprovação de CI não substitui a instalação real pelo registro.
+
+[Wiki](../README.md) · [Comunidade](community.md)
+
+[ci]: https://github.com/pathbit/AgentDevKit/actions/workflows/ci.yml
+[release]: https://github.com/pathbit/AgentDevKit/actions/workflows/release.yml
+[package]: https://www.npmjs.com/package/@pathbit/agentdevkit

package/docs/maintainers/packages.md

@@ -0,0 +1,87 @@
+---
+description: Instalação e publicação do pacote npm público do AgentDevKit.
+---
+
+# Pacote npm público
+
+O AgentDevKit é um único pacote: [`@pathbit/agentdevkit`][package]. Ele contém
+a CLI e os recursos compartilhados; a instalação prepara os apontamentos dos
+agentes escolhidos no projeto.
+
+Os metadados identificam PathBit como autor, palavras-chave do kit e licença
+MIT. O README público é gerado sem frontmatter e com links absolutos do GitHub;
+a fonte versionada conserva o YAML. O `LICENSE` canônico acompanha o pacote e
+é instalado em `.pbai4devs/LICENSE`, sem alterar a licença do consumidor.
+Ferramentas de terceiros baixadas à parte mantêm suas próprias licenças e
+não integram o TGZ do AgentDevKit.
+
+## Instalar no projeto
+
+Com Node.js 18+ e npm, execute na pasta do projeto. Não é necessário login:
+
+```console
+npx @pathbit/agentdevkit init
+```
+
+Para repetir uma instalação, fixe a versão desejada após o nome do pacote.
+
+Acrescente `--agents codex,claude` para selecionar clientes, `--dry-run` para
+simular ou use `update`, `doctor` e `sync --check` no lugar de `init`.
+Não é necessário instalar globalmente nem adicionar o kit às dependências
+da aplicação. Para conferir as versões:
+
+```console
+npm view @pathbit/agentdevkit versions --json
+```
+
+Se existir um mapeamento antigo para o GitHub Packages, siga a
+[correção de registry][fix].
+
+## Publicar pelo Actions
+
+A publicação usa o mesmo TGZ aprovado pelo CI, com acesso público. O workflow
+confere versão, origem e integridade; uma versão existente só é aceita quando
+contém os mesmos bytes. Não reempacote nem substitua uma versão publicada.
+
+O workflow prioriza o secret do repositório `NPMJS_TOKEN`, recebido pela
+variável interna `NPM_TOKEN` somente na publicação. O token precisa permitir
+publicar no escopo `@pathbit`; credenciais nunca entram nos arquivos
+versionados.
+
+Sem esse secret, o workflow usa OIDC. Configure o **Trusted Publisher** do npm:
+
+| Campo | Valor |
+| --- | --- |
+| Organization or user | `pathbit` |
+| Repository | `AgentDevKit` |
+| Workflow filename | `release.yml` |
+| Allowed action | Publicação direta com `npm publish` |
+
+O fallback recebe `id-token: write`. O npm exige CLI 11.5.1+ e Node 22.14+;
+o projeto usa Node 24. Configure a relação de confiança depois que o pacote
+existir; a primeira publicação pode usar o secret `NPMJS_TOKEN`.
+
+Para publicar somente o pacote de uma tag que já tem artefato aprovado:
+
+```console
+gh workflow run release.yml --ref master -f tag=v0.0.6 -F package_only=true
+```
+
+Se o artefato expirou, reexecute o CI original da tag antes da publicação.
+Depois do envio, o job usa um ambiente sem credenciais e cache novo para
+executar `--version`, `init`, `doctor` e `sync --check` pelo nome e versão
+publicados. Assim, a verificação comprova o acesso de um usuário comum.
+Confirme também que `latest` aponta para a versão estável e que o tarball é
+baixável; metadados visíveis sozinhos não comprovam uma instalação funcional.
+Se o registro ainda não disponibilizar o pacote, aguarde a verificação sem
+republicar automaticamente a mesma versão.
+
+As versões antigas no [GitHub Packages][legacy] permanecem disponíveis;
+o canal de instalação padrão é o npm público.
+
+[Wiki](../README.md) · [Manutenção](maintenance.md) ·
+[Instalação](../guides/installation.md)
+
+[package]: https://www.npmjs.com/package/@pathbit/agentdevkit
+[legacy]: https://github.com/pathbit/AgentDevKit/pkgs/npm/agentdevkit
+[fix]: ../guides/troubleshooting.md#download-plataforma-ou-ferramenta-falhando