@pathbit/agentdevkit 0.0.0-stage → 0.0.5

package/docs/product/design.md

@@ -0,0 +1,94 @@
+---
+description: Fontes, geração local e arquitetura do AgentDevKit.
+status: aprovado
+---
+
+# Design técnico
+
+O repositório contém o gerador. A instalação produz a estrutura usada pelos
+agentes em outro projeto. [PRD](prd.md) e [specs](../specs/README.md) definem os
+contratos de cada entrega.
+
+## Fontes no repositório
+
+```text
+AgentDevKit/
+├── src/              CLI e instalação
+├── bin/              entrada do pacote npx
+├── tests/            testes do produto
+├── scripts/release/  CI, empacotamento e publicação
+├── examples/         guia e cenários gerados localmente
+├── docs/             guias e decisões do produto
+└── .pbai4devs/        skills, regras, templates e ferramentas compartilhadas
+```
+
+Metadados npm, licença, documentação e workflows do GitHub ficam nos seus
+locais padrão. Pastas nativas dos clientes, índices e estado local não fazem
+parte da fonte versionada.
+
+`npm run examples` gera as árvores de demonstração em `examples/generated/`.
+Elas contêm `.claude`, `.codex` e os demais clientes, sem misturar exemplos com
+a configuração ativa da raiz. `npm run test:examples` executa os cenários.
+O [guia de desenvolvimento](../maintainers/development.md) reúne os comandos
+do projeto.
+
+## Resultado instalado
+
+`.pbai4devs` recebe os recursos compartilhados, sem copiar o núcleo do gerador,
+as automações de release ou os testes exclusivos do produto. Os layouts dos
+clientes vêm da [configuração declarativa][clients]. Os arquivos nativos são
+pequenos apontamentos para o hub, sem symlinks.
+
+A escolha salva determina as derivações. Atualizações e sincronizações não
+reativam clientes desmarcados. `all` preserva a intenção de usar todos; estados
+antigos sem escolha explícita mantêm esse comportamento.
+
+## Instalação e propriedade
+
+O instalador monta um plano, confere hashes e caminhos, apresenta conflitos e
+aplica mudanças com backup local. `--dry-run` não altera arquivos nem índice.
+
+Entradas humanas permanecem intactas. O kit cria suas próprias entradas quando
+faltam; na migração, separa seus blocos de texto humano. Nunca é possível
+ignorar somente um trecho de arquivo no Git.
+
+Saídas identificadas são excluídas localmente do versionamento. O Git local
+usa `info/exclude`; fora de um repositório, a proteção fica no `.gitignore`
+da raiz. A política vem dos templates, não de listas copiadas por cliente.
+Os arquivos humanos de `.github` e `.vscode` continuam versionáveis.
+
+O estado registra versão, escolha e propriedade local. Índices e manifesto
+podem ser reconstruídos. Downloads, credenciais e relatórios ficam fora do
+pacote e do Git.
+
+## Runtime
+
+O launcher aceita Node 18+ e prepara Node 24+ antes de carregar o núcleo.
+O bootstrap usa JavaScript, download oficial, SHA-256 e extração por `tar`
+com argumentos separados, sem shell. Falhas preservam o runtime anterior.
+Sem Node, o agente usa primeiro o instalador nativo do sistema operacional.
+
+## Verificação e publicação
+
+O CI separa a suíte completa dos testes de portabilidade. A publicação usa um
+artifact aprovado do mesmo commit e verifica versão, origem e checksum.
+Não há novo empacotamento entre teste e publicação.
+
+O npm público recebe o mesmo tarball da release, como `@pathbit/agentdevkit`.
+O workflow prioriza o secret `NPMJS_TOKEN` do repositório, recebido pela
+variável interna `NPM_TOKEN`; sem token, usa OIDC. Confirma a integridade da
+versão no registro e testa `--version`, `init`, `doctor` e `sync --check` via
+`npm exec`, em projeto temporário com cache novo.
+Os comandos sugeridos pela CLI e pelas notas usam o nome e a versão do pacote.
+O modo manual de pacote permite publicar uma tag existente sem alterar sua
+release. A instalação do consumidor é validada sem token ou configuração
+de autenticação, conforme [pacote npm](../maintainers/packages.md).
+
+Testes comprovam arquivos e operações executadas. O carregamento em um
+aplicativo específico depende das capacidades desse cliente; gerar uma
+referência não comprova a execução da skill.
+
+[Wiki](../README.md) · [Manutenção](../maintainers/maintenance.md) ·
+[Recursos](../guides/resources.md)
+
+[clients]: ../../.pbai4devs/templates/clients/ADAPTERS.json

package/docs/product/prd.md

@@ -0,0 +1,64 @@
+---
+description: Requisitos da distribuição portátil AgentDevKit.
+status: aprovado
+version: 0.0.5
+---
+
+# PRD do AgentDevKit
+
+## Problema e público
+
+Desenvolvedores precisam reutilizar instruções de agentes entre projetos e
+clientes sem copiar procedimentos divergentes, perder configurações locais
+ou iniciar código antes de definir o produto.
+
+O AgentDevKit atende pessoas e equipes que usam agentes de desenvolvimento
+em projetos novos ou existentes. A primeira entrega distribui o kit já
+extraído do projeto de origem como produto independente.
+
+## Requisitos
+
+| ID | Resultado esperado |
+| --- | --- |
+| FR-001 | Instalar e atualizar uma origem única `.pbai4devs`. |
+| FR-002 | Gerar entradas conforme a descoberta nativa de cada cliente. |
+| FR-003 | Preservar código, documentos, configurações e dados existentes. |
+| FR-004 | Oferecer CLI Node 24+ com idioma persistido: PT padrão, EN e ES. |
+| FR-005 | Indicar estado, pendências e próximos passos em cada resultado. |
+| FR-006 | Seguir preparação, produto, design, configuração, specs e revisão. |
+| FR-007 | Distribuir testes/modelos sem resultados, segredos ou downloads. |
+| FR-008 | Validar o pacote local e preparar a release versionada v0.0.1. |
+| FR-009 | Selecionar agentes e criar apenas seus apontamentos necessários. |
+| FR-010 | Reutilizar a seleção e alterá-la sem perder arquivos próprios. |
+| FR-011 | Versionar as fontes; manter derivações e preferências locais. |
+| FR-012 | Gerar layouts nativos a partir de configurações e templates. |
+| FR-013 | Usar JavaScript/Node nas automações e manter distribuição via npx. |
+| FR-014 | Reutilizar no release o pacote verificado, sem duplicar o CI. |
+| FR-015 | Publicar no npm público, instalável via npx sem autenticação. |
+| FR-016 | Organizar código e testes em `src/` e `tests/`, na raiz. |
+| FR-017 | Gerar exemplos isolados e acessíveis por comandos documentados. |
+
+Execuções repetidas devem ser idempotentes; a CLI oferece simulação e JSON.
+As instruções permanecem concisas, com detalhes opcionais em referências.
+Na configuração interativa, o usuário escolhe seus agentes. Em automações,
+a opção explícita ou a escolha salva orientam o instalador; sem escolha,
+todos os clientes são mantidos para compatibilidade.
+
+## Limites e sucesso
+
+O kit não define a stack dos projetos, não publica automaticamente, não cria
+PRD/specs sem descoberta e não comprova carregamento pelo cliente apenas por
+gerar arquivos. Não copia documentos reais de produto para o projeto-alvo.
+
+A entrega exige testes de projeto vazio e existente, preservação de arquivos,
+atualização, idiomas, catálogos e distribuição sem artefatos locais.
+Os aceites da distribuição ficam na [spec inicial](../specs/v0.0.1/SPEC.md);
+a [spec de seleção](../specs/v0.0.2/SPEC.md) detalha a instalação por agente.
+
+## Autorização
+
+Escopo autorizado pela solicitação explícita de criação do AgentDevKit.
+Este estado registra requisitos aceitos; testes e publicação têm validação
+própria e não são considerados concluídos por esta aprovação.
+
+[Wiki](../README.md) · [Design](design.md) · [Fluxo de uso](../guides/workflow.md)

package/docs/product/roadmap.md

@@ -0,0 +1,36 @@
+---
+description: Entregas e dependências do AgentDevKit.
+status: vigente
+---
+
+# Roadmap
+
+| Entrega | Dependência | Referência |
+| --- | --- | --- |
+| Escopo e design | Solicitação de extração | PRD, UX e design. |
+| CLI, adaptadores e pacote v0.0.1 | PRD, UX e design | Spec v0.0.1. |
+| Provas de instalação e maturidade | Pacote e CLI | Testes e CI. |
+| Release v0.0.1 | Aceites e revisão | Pacote versionado e changelog. |
+| Seleção de agentes v0.0.2 | CLI e adaptadores | [Spec][selection]. |
+| Fontes e geração local v0.0.3 | Seleção e distribuição | [Spec][source]. |
+| Pacote npm no GitHub Packages | Artefato aprovado da release | [Spec][packages]. |
+| Estrutura e exemplos v0.0.4 | CLI, distribuição e gerador | [Spec][layout]. |
+| Instalação pelo registro v0.0.5 | Pacote publicado | [Spec][registry]. |
+
+A primeira entrega segue a [spec v0.0.1](../specs/v0.0.1/SPEC.md) e está disponível
+na [release v0.0.1][release]. Os detalhes de mudanças estão no
+[changelog](../../CHANGELOG.md), e o processo de publicação em
+[manutenção](../maintainers/maintenance.md).
+
+Não há datas ou entregas futuras assumidas. Novos clientes e funcionalidades
+exigem revisão do escopo e specs próprias. Melhorias na wiki acompanham o
+comportamento existente, sem alterar a versão de uma release já publicada.
+
+[Wiki](../README.md) · [Specs](../specs/README.md)
+
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.1
+[selection]: ../specs/v0.0.2/SPEC.md
+[source]: ../specs/v0.0.3/SPEC.md
+[packages]: ../specs/github-packages/SPEC.md
+[layout]: ../specs/v0.0.4/SPEC.md
+[registry]: ../specs/v0.0.5/SPEC.md

package/docs/product/ux-ui.md

@@ -0,0 +1,42 @@
+---
+description: Jornadas e comunicação da interface de linha de comando.
+status: aprovado
+---
+
+# UX da CLI
+
+O produto usa uma CLI; não há interface web ou desktop nesta entrega.
+A experiência prioriza comandos curtos, resultados legíveis e continuidade.
+
+| Jornada | Resposta esperada |
+| --- | --- |
+| Primeiro uso | Local instalado, resumo e próxima etapa para o projeto. |
+| Projeto existente | Mudanças propostas e preservação dos arquivos próprios. |
+| Atualização | O que mudou, conflitos/backups e como verificar o resultado. |
+| Diagnóstico | Pendências observadas e próximos comandos ou skills. |
+| Automação | JSON único e código de saída, sem depender do texto traduzido. |
+
+PT é padrão. EN e ES alteram a interface e os próximos passos, mantendo nomes
+de comandos e caminhos. O idioma salvo é reutilizado nas próximas execuções.
+Mensagens distinguem confirmação, aviso e falha sem afirmar testes não feitos.
+
+O primeiro uso interativo permite escolher idioma e agentes de código.
+Quem automatiza pode fornecer `--lang`, `--agents` e ler `--json`; o resultado
+inclui a próxima ação. Agentes em aplicativos podem reunir a escolha pelo
+chat e passá-la à CLI, sem depender de um terminal interativo. Instalação
+normal resume mudanças; simulação lista uma amostra e o JSON fornece o plano.
+
+`doctor` responde sobre a instalação do kit, enquanto `next` orienta o trabalho
+do projeto. Essa distinção evita tratar um diagnóstico saudável como prova
+de que a aplicação está pronta. Conflitos devem levar à comparação de arquivos
+antes de qualquer substituição. Veja [CLI](../guides/cli.md) e
+[recuperação](../guides/troubleshooting.md) para o comportamento observável.
+
+O comando `agents` consulta a seleção sem escrever arquivos. Sua alteração
+permite simular o plano antes de remover apontamentos gerados. Pastas próprias
+não são apagadas para aparentar uma instalação menor.
+
+Escopo autorizado junto ao [PRD](prd.md). Testes verificam as jornadas reais;
+a aprovação do desenho não substitui as evidências de funcionamento.
+
+[Wiki](../README.md) · [Fluxo de uso](../guides/workflow.md)

package/docs/specs/README.md

@@ -0,0 +1,20 @@
+---
+description: Incrementos verificáveis do AgentDevKit.
+---
+
+# Specs
+
+- [v0.0.1](v0.0.1/SPEC.md): primeira distribuição independente.
+- [v0.0.2](v0.0.2/SPEC.md): seleção persistente de agentes por projeto.
+- [v0.0.3](v0.0.3/SPEC.md): fontes, saídas locais e automações Node.
+- [GitHub Packages](github-packages/SPEC.md): pacote npm instalável via npx.
+- [v0.0.4](v0.0.4/SPEC.md): estrutura padrão e exemplos na raiz.
+- [v0.0.5](v0.0.5/SPEC.md): instalação pelo registro em todos os fluxos.
+
+Cada incremento vincula requisitos, critérios, testes e evidências locais.
+
+Estes são os incrementos do próprio AgentDevKit. Para criar uma spec do seu
+projeto, siga o [fluxo](../guides/workflow.md) e use os
+[modelos compartilhados](../../.pbai4devs/templates/README.md).
+
+[Wiki](../README.md) · [Roadmap](../product/roadmap.md)

package/docs/specs/github-packages/SPEC.md

@@ -0,0 +1,45 @@
+---
+description: Publicação do pacote único no registro npm do GitHub.
+status: aprovado
+---
+
+# Pacote npm no GitHub Packages
+
+## Objetivo
+
+Publicar `@pathbit/agentdevkit` no GitHub Packages, vinculado a este repositório,
+para instalação com `npx`. Escopo confirmado pelo usuário nesta solicitação.
+O [PRD](../../product/prd.md), o [design](../../product/design.md) e a
+[UX da CLI](../../product/ux-ui.md) já definem o produto. Este incremento é um novo
+canal de distribuição do pacote existente, sem mudança da interface da CLI.
+
+## Contrato
+
+- Um pacote npm com CLI, skills e recursos compartilhados.
+- Publicar o tarball aprovado do CI, preservando origem, versão e bytes.
+- Usar `GITHUB_TOKEN` do Actions com permissão de escrita de pacotes.
+- Incluir publicação nas releases futuras e permitir adicionar uma tag
+  existente ao registro sem recriar sua release.
+- Conferir a integridade da versão no registro; versões com outros bytes
+  são conflitos. Uma repetição com bytes iguais é segura.
+- Provar instalação da CLI a partir do registro, com credencial do workflow.
+- Documentar que GitHub Packages exige autenticação inclusive para pacotes
+  npm públicos; não versionar credenciais nem alterar o login local do usuário.
+
+Não separar componentes em múltiplos pacotes, não criar um registro npmjs e
+não modificar tags publicadas. Dependência: [v0.0.3](../v0.0.3/SPEC.md).
+
+## Critérios de aceite
+
+| ID | Resultado | Prova |
+| --- | --- | --- |
+| AC-001 | Pacote único com registro e repositório definidos. | Metadados. |
+| AC-002 | Publica o artifact aprovado, sem repack. | Testes e workflow. |
+| AC-003 | Repetição e conflitos tratados por integridade. | Testes negativos. |
+| AC-004 | CLI instalada pelo registro executa corretamente. | Actions real. |
+| AC-005 | Login, npx, limites e manutenção documentados. | Lint e revisão. |
+
+Evidências em `.agent-tests/github-packages/`, fora do Git. A publicação da
+versão 0.0.3 usa o artefato de sua tag existente; futuras versões seguem o CI.
+
+[Specs](../README.md) · [Roadmap](../../product/roadmap.md)

package/docs/specs/v0.0.1/README.md

@@ -0,0 +1,10 @@
+---
+description: Primeira distribuição independente do AgentDevKit.
+---
+
+# v0.0.1
+
+Leia a [spec](SPEC.md) para escopo, critérios e provas esperadas.
+Resultados de execução ficam ignorados em `.agent-tests/`, fora desta pasta.
+
+[Todas as specs](../README.md) · [Wiki](../../README.md)

package/docs/specs/v0.0.1/SPEC.md

@@ -0,0 +1,57 @@
+---
+description: CLI e recursos portáteis da primeira distribuição AgentDevKit.
+status: aprovado
+version: 0.0.1
+---
+
+# Distribuição v0.0.1
+
+## Objetivo e escopo
+
+Distribuir o kit independente, instalável em projetos novos e existentes,
+conforme [PRD](../../product/prd.md), [UX](../../product/ux-ui.md) e [design](../../product/design.md).
+Inclui CLI, recursos, adaptadores, idiomas e testes. Publicação depende da
+validação da entrega; não inclui backend nem interface gráfica.
+
+## Critérios de aceite
+
+| Critério | Resultado observável |
+| --- | --- |
+| AC-001 | Tarball contém CLI/recursos sem resultados, downloads ou segredos. |
+| AC-002 | `init` instala em diretório vazio e oferece próximos passos. |
+| AC-003 | Instalação e atualização preservam conteúdo próprio existente. |
+| AC-004 | Repetição é idempotente; simulação não altera o alvo. |
+| AC-005 | PT padrão, EN/ES e idioma persistido funcionam com JSON válido. |
+| AC-006 | Adaptadores, catálogos e sincronização refletem a origem única. |
+| AC-007 | Projeto recebe orientação sem criação indevida de produto. |
+| AC-008 | Testes da infraestrutura e cenários de maturidade passam. |
+
+## Plano de verificação
+
+Evidências: `.agent-tests/agentdevkit-v0.0.1/<execucao>/` e relatórios do CI.
+A tabela define as provas; resultados reais ficam no relatório ignorado de
+cada execução, sem versionar aprovações ou saídas de testes nesta spec.
+
+| Critério | Método | Requer | Assertiva | Evidência |
+| --- | --- | --- | --- | --- |
+| AC-001 | pack | Node/npm | Sem extras | pack.json |
+| AC-002 | init | Tarball | Recursos/next | empty.json |
+| AC-003 | init/update | Sentinelas | Hashes iguais | existing.json |
+| AC-004 | repetir/simular | Alvo | Idempotente | repeat.json |
+| AC-005 | PT/EN/ES | Alvos | Idioma/JSON | languages.json |
+| AC-006 | sync/check | Fontes | Índices iguais | sync.log |
+| AC-007 | next/doctor | Fases | Ação aplicável | next.json |
+| AC-008 | testes/matriz | Kit | Casos passaram | matrix.json |
+
+Execute `npm test` para distribuição e CLI; `npm run test:infra` para as
+automações; e o script `testar-maturidade` para os oito cenários. A distribuição
+usa `npm pack` e npx offline sobre o tarball real. Sentinelas são arquivos do
+usuário cujo conteúdo deve permanecer idêntico após instalar e atualizar.
+
+## Documentação e autorização
+
+README PT/EN/ES, instalação, produto e guias compartilhados acompanham a CLI.
+Escopo autorizado pela solicitação atual de criação do AgentDevKit.
+Critérios mantidos exigem prova aprovada na revisão antes de concluir a release.
+
+[Todas as specs](../README.md) · [Wiki](../../README.md)

package/docs/specs/v0.0.2/README.md

@@ -0,0 +1,10 @@
+---
+description: Seleção de agentes no AgentDevKit.
+---
+
+# v0.0.2
+
+Leia a [spec](SPEC.md) para o escopo e os critérios de seleção dos agentes.
+Evidências ficam em `.agent-tests/`, fora do Git.
+
+[Todas as specs](../README.md) · [Wiki](../../README.md)

package/docs/specs/v0.0.2/SPEC.md

@@ -0,0 +1,67 @@
+---
+description: Instalação seletiva e persistente dos agentes usados pelo projeto.
+status: aprovado
+version: 0.0.2
+---
+
+# Selecionar agentes por projeto
+
+## Objetivo
+
+Criar apenas os apontamentos dos agentes escolhidos, mantendo a origem única
+em `.pbai4devs`. A seleção funciona no terminal, em agentes desktop e em
+execuções sem interação. Escopo solicitado e autorizado pelo usuário, conforme
+[PRD](../../product/prd.md), [UX](../../product/ux-ui.md) e [design](../../product/design.md).
+
+## Comportamento
+
+- `init --agents codex,claude` instala os clientes selecionados.
+- `agents` consulta; `agents codex,claude` altera; `agents all` ativa todos.
+- No primeiro uso interativo, a CLI pergunta idioma e agentes.
+- Em um aplicativo, o agente pode reunir a escolha pelo chat e passá-la à CLI.
+- A prioridade é opção explícita, escolha salva e, por último, `all`.
+- Sem terminal interativo, com `--yes`, `--json` ou `--dry-run`, não há pergunta.
+- A seleção é persistida em `estado/agentdevkit.json`; `all` mantém seu sentido
+  de todos, inclusive clientes adicionados em versões futuras.
+- Atualizar, sincronizar, trocar idioma e consultar não reativam clientes
+  desmarcados. Estados antigos sem seleção continuam equivalentes a `all`.
+- Dependências de descoberta são incluídas: Codex precisa de `.agents`, por
+  exemplo. As pastas efetivas podem ser compartilhadas entre clientes.
+- Desmarcar remove somente derivados próprios comprovados. Arquivos humanos
+  permanecem; alterações em arquivos gerenciados produzem conflitos e backup.
+
+O hub, scripts, modelos e ferramentas permanecem completos. Selecionar agentes
+não instala ferramentas, escolhe a stack nem inicia o produto. Não inclui
+detecção por processos, configuração global de editores ou login nos clientes.
+
+## Plano
+
+1. Centralizar IDs, aliases, dependências e entradas nativas nos adaptadores.
+2. Filtrar o manifesto e persistir a escolha na instalação.
+3. Implementar consulta, alteração e perguntas sem bloquear automações.
+4. Remover derivados desmarcados com as proteções existentes de propriedade.
+5. Atualizar os guias e as skills de configuração; sincronizar os recursos.
+6. Verificar seleção, migração, preservação, pacote real e distribuição.
+
+## Critérios de aceite
+
+| ID | Resultado observável | Prova |
+| --- | --- | --- |
+| AC-001 | Gera só os clientes escolhidos e suas dependências. | Adaptadores |
+| AC-002 | Escolha explícita e pergunta interativa funcionam. | CLI e terminal |
+| AC-003 | Sem interação, há seleção salva ou fallback all. | CLI/JSON |
+| AC-004 | Atualização e sync preservam a escolha. | CLI e script direto |
+| AC-005 | Alterar seleção preserva conteúdo humano. | Hashes e conflitos |
+| AC-006 | Erros de entrada e simulação não alteram o alvo. | Testes negativos |
+| AC-007 | Estado legado e all mantêm compatibilidade. | Migração e repetição |
+| AC-008 | Pacote real, guias e revisão são verificados. | Pacote, lint e CI |
+
+Use Node 24/26, diretórios vazios e existentes e instalações via tarball real.
+Teste as raízes, entradas, índices e `.gitignore`; não considere apenas a
+mensagem de sucesso. Exercite o sincronizador instalado sem depender de `src/`.
+
+Código de testes é versionado. Resultados e relatório por critério ficam em
+`.agent-tests/client-selection/<execucao>/`. A seleção de arquivos não comprova
+carregamento em todo aplicativo; registre separadamente o que foi executado.
+
+[Todas as specs](../README.md) · [Wiki](../../README.md)

package/docs/specs/v0.0.3/README.md

@@ -0,0 +1,10 @@
+---
+description: Fontes versionadas e geração local do AgentDevKit.
+---
+
+# v0.0.3
+
+A [spec](SPEC.md) define a separação entre fontes e derivados, o runtime Node
+e o fluxo de verificação e publicação.
+
+[Todas as specs](../README.md) · [Wiki](../../README.md)

package/docs/specs/v0.0.3/SPEC.md

@@ -0,0 +1,64 @@
+---
+description: Fonte única, saídas locais e automações JavaScript.
+status: aprovado
+version: 0.0.3
+---
+
+# Fontes e geração local
+
+## Objetivo
+
+Manter em `.pbai4devs` as fontes do kit e gerar a estrutura específica de cada
+agente quando necessária. Os derivados e as preferências são locais; código,
+templates, testes e documentação permanecem versionados. Escopo autorizado
+na solicitação atual e vinculado ao [PRD](../../product/prd.md).
+
+## Contrato
+
+- O produto, o launcher, os testes e as automações ficam em `.pbai4devs`.
+  Metadados npm, licença, documentação e integração GitHub ficam na raiz.
+- Configurações declarativas e templates descrevem nomes, diretórios,
+  metadados e apontamentos dos clientes.
+- A instalação gera apenas clientes escolhidos, entradas e índices locais.
+  Os apontamentos seguem para a fonte compartilhada, sem symlinks.
+- Saídas e estado pessoal são ignorados pelo Git. `.github/workflows`, issues
+  e configurações humanas não são confundidos com derivações dos agentes.
+- Um `.gitignore` não controla diretórios irmãos. O gerador aplica exclusões
+  locais do Git; sem repositório, usa uma proteção no `.gitignore` da raiz.
+- Migrar arquivos já rastreados exige retirar do índice somente os derivados
+  identificados, preservando o conteúdo no disco.
+- Entradas humanas são preservadas. Blocos antigos do kit são migrados sem
+  apagar conteúdo humano fora do bloco; alterações conflitantes exigem revisão.
+- O pacote continua executável por `npx`. O launcher aceita Node 18+ e prepara
+  Node 24+ para o núcleo quando necessário. Não há bootstrap `.sh` ou `.ps1`.
+- Sem Node/npm, o agente usa o instalador nativo do sistema; JavaScript não
+  consegue executar antes de existir um runtime.
+- O CI separa a verificação completa dos testes de portabilidade. A release
+  reutiliza o artifact aprovado do mesmo commit, sem repetir o empacotamento.
+
+## Critérios de aceite
+
+| ID | Resultado observável | Verificação |
+| --- | --- | --- |
+| AC-001 | Fontes no hub; nenhum derivado rastreado. | Git e inventário |
+| AC-002 | Templates geram clientes e entradas corretas. | Geração e npx |
+| AC-003 | Derivados ignorados em Git, subpasta e worktree. | Git real |
+| AC-004 | Migração preserva conteúdo humano e disco. | Hashes e índice |
+| AC-005 | Automações Node, sem scripts shell próprios. | Inventário/runtime |
+| AC-006 | npx instala, atualiza e sincroniza o pacote. | Tarball real |
+| AC-007 | CI não duplica a suíte completa na release. | Workflow/artifact |
+| AC-008 | Runtime antigo se recupera com integridade. | Bootstrap e falhas |
+| AC-009 | Guias, testes e release refletem o contrato. | Lint/revisão/CI |
+
+## Provas
+
+Execute testes em diretórios novos, existentes, com e sem Git, em subpastas
+e worktrees. Verifique bytes preservados e paths ignorados, não apenas mensagens.
+Teste seleção individual e `all`, erro de download/checksum, pacote adulterado,
+origem incorreta do artifact e arquivos locais fora do pacote.
+
+Resultados ficam em `.agent-tests/source-only/`; não são commitados. O CI deve
+validar os sistemas suportados com grupos adequados, sem prometer tempos fixos.
+A aprovação exige revisão independente e evidências por critério.
+
+[Todas as specs](../README.md) · [Wiki](../../README.md)

package/docs/specs/v0.0.4/README.md

@@ -0,0 +1,10 @@
+---
+description: Organização do repositório e exemplos de desenvolvimento.
+---
+
+# Estrutura e exemplos
+
+A [spec](SPEC.md) define a organização do produto em `src/`, `tests/`,
+`scripts/` e `examples/`, preservando os recursos compartilhados e o pacote.
+
+[Todas as specs](../README.md)

package/docs/specs/v0.0.4/SPEC.md

@@ -0,0 +1,53 @@
+---
+description: Estrutura padrão do repositório, exemplos e automações simples.
+status: aprovado
+version: 0.0.4
+---
+
+# Estrutura padrão e exemplos
+
+## Objetivo
+
+Organizar o repositório para que uma pessoa consiga localizar o código,
+experimentar os agentes e verificar uma alteração pelos comandos npm.
+Escopo solicitado pelo usuário: código e testes na raiz, exemplos em pasta
+própria e automações claras. Aprovação geral e execução já autorizadas.
+
+Dependências: [v0.0.3](../v0.0.3/SPEC.md) e
+[GitHub Packages](../github-packages/SPEC.md). O [PRD](../../product/prd.md), o
+[design](../../product/design.md) e a [UX](../../product/ux-ui.md) continuam aplicáveis.
+
+## Contrato
+
+- Código em `src/`, launcher em `bin/`, testes em `tests/` e publicação em
+  `scripts/release/`. `.pbai4devs` mantém os recursos portáveis dos agentes.
+- `examples/` contém o guia versionado. O gerador produz oito cenários em
+  `examples/generated/`, com os diretórios dos clientes e relatório atual.
+- A preparação deve funcionar sem pastas de agentes previamente geradas na
+  raiz. Preparar novamente invalida resultados antigos com propriedade válida.
+- Não remover arquivos humanos. Apenas demonstrações geradas identificadas
+  podem sair da raiz, com backup local. Workflows reais ficam em `.github`.
+- Manter npm/npx, instalação, atualização, escolha de clientes e preservação
+  do projeto consumidor. Não copiar o código do kit para a aplicação atendida.
+- Adaptar build, testes, CI e publicação sem duplicar a matriz. Releases e
+  GitHub Packages usam os mesmos bytes aprovados.
+- Manter guias curtos por tarefa, sem novos frameworks, dependências ou
+  serviços que a CLI não usa.
+
+## Critérios de aceite
+
+| ID | Resultado | Prova |
+| --- | --- | --- |
+| AC-001 | Código e testes nas pastas da raiz. | Inventário e imports. |
+| AC-002 | Comandos npm e pacote continuam funcionais. | CLI e TGZ real. |
+| AC-003 | Exemplos completos gerados de uma origem limpa. | Oito cenários. |
+| AC-004 | Relatórios atuais e conteúdo humano preservado. | Testes negativos. |
+| AC-005 | Upgrade mantém projetos e versões anteriores. | Migração real. |
+| AC-006 | Saídas não entram no Git ou pacote. | Git e inventário. |
+| AC-007 | Publicação preserva a distribuição. | Testes e Actions. |
+| AC-008 | Guias e referências acompanham a nova estrutura. | Lint e revisão. |
+
+Evidências em `.agent-tests/standard-layout/`, fora do versionamento. Testes
+web/desktop não se aplicam: esta entrega altera a CLI, arquivos e automações.
+
+[Desenvolvimento](../../maintainers/development.md) · [Specs](../README.md)

package/docs/specs/v0.0.5/README.md

@@ -0,0 +1,9 @@
+---
+description: Instalação pelo pacote publicado no registro.
+---
+
+# Versão 0.0.5
+
+A [spec](SPEC.md) unifica os comandos de instalação no npm público.
+
+[Specs](../README.md)

package/docs/specs/v0.0.5/SPEC.md

@@ -0,0 +1,42 @@
+---
+description: Pacote nomeado como forma de instalação e atualização.
+status: aprovado
+version: 0.0.5
+---
+
+# Instalação pelo registro
+
+## Objetivo
+
+Instalar o pacote publicado no npm público por nome e versão, sem login.
+O usuário escolheu esse canal para instalar com `npx`, sem baixar a release.
+
+Dependências: [publicação no GitHub Packages](../github-packages/SPEC.md),
+[estrutura padrão](../v0.0.4/SPEC.md), [PRD](../../product/prd.md) e
+[design](../../product/design.md). Mudança solicitada e execução autorizada.
+
+## Contrato
+
+- CLI, notas e guias usam `npx` com nome, versão e registro do pacote.
+- Não exigir login para instalar e ligar a página pública do pacote.
+- Manter o TGZ como artefato técnico aprovado, com checksum e procedência.
+- Depois de publicar, instalar pelo registro em projeto temporário e testar
+  versão, `init`, `doctor` e `sync --check` em cache novo, sem credenciais.
+- Priorizar o secret `NPMJS_TOKEN`, mapeado para `NPM_TOKEN` na publicação;
+  usar OIDC quando ele estiver ausente. Autenticação é só para o mantenedor.
+- Preservar credenciais fora do Git, arquivos humanos e versões anteriores.
+
+## Critérios de aceite
+
+| ID | Resultado | Prova |
+| --- | --- | --- |
+| AC-001 | CLI sugere pacote nomeado em todos os sistemas. | Testes e saída. |
+| AC-002 | Notas e guias usam o registro e apontam o pacote. | Lint e revisão. |
+| AC-003 | Publicação valida o consumidor e recusa falhas. | Testes negativos. |
+| AC-004 | Pacote instala pelo npm público sem login. | Actions real. |
+| AC-005 | Versões e dados anteriores são preservados. | Distribuição e Git. |
+
+Evidências em `.agent-tests/registry-installation/`. A CLI e os arquivos são
+o escopo; não há interface web ou desktop para validar nesta mudança.
+
+[Specs](../README.md) · [Pacote npm](../../maintainers/packages.md)