@pathbit/agentdevkit 0.0.9 → 0.0.11

package/docs/guides/installation.md

@@ -9,23 +9,58 @@ O pacote traz o gerador e as fontes compartilhadas. A instalação prepara
 
 ## Pré-requisitos
 
-Use Node.js 18+ com npm para iniciar o pacote. O launcher prepara Node 24+
-quando o runtime atual é antigo; o núcleo e as ferramentas usam Node 24+.
-A extração de runtime usa o executável nativo `tar`, sem scripts shell.
-
-Sem Node/npm, o agente precisa primeiro instalar o runtime pelo mecanismo do
-sistema operacional e continuar. `npx` não funciona antes dessa instalação.
-O [guia de preparo][bootstrap] explica as duas situações.
+Prepare [Node.js 24+ com npm e npx](prerequisites.md) no Windows, macOS ou Linux.
+O guia inclui instalação manual e como pedir ao agente para preparar a máquina.
+Git é opcional para instalar o kit. Com Node 18–23 existente, o launcher pode
+preparar Node 24 localmente usando `tar`; veja o [bootstrap][bootstrap].
 
 ## Instalar
 
-O pacote [`@pathbit/agentdevkit`](../maintainers/packages.md) é publicado no
-npm público. Execute na pasta do projeto, sem login:
+Os dois registries oferecem o mesmo [`@pathbit/agentdevkit`](../maintainers/packages.md).
+Escolha um deles e execute na pasta do projeto.
+
+### npm público
+
+É o caminho padrão e não exige conta nem login:
 
 ```console
 npx @pathbit/agentdevkit init
 ```
 
+Para escolher explicitamente esse registry:
+
+```console
+npx --registry=https://registry.npmjs.org @pathbit/agentdevkit init
+```
+
+### GitHub Packages
+
+O pacote é público, mas esse registry exige autenticação para baixar.
+Crie um [personal access token clássico][tokens] com `read:packages`.
+Autentique uma vez no seu computador:
+
+```console
+npm login --registry=https://npm.pkg.github.com --auth-type=legacy --scope=
+```
+
+Informe seu usuário do GitHub e use o token no campo de senha. O npm guarda
+a credencial no arquivo do seu usuário, vinculada ao host do GitHub.
+`--scope=` evita criar um mapeamento permanente do escopo; nunca coloque
+o token nos comandos compartilhados ou no repositório. Veja a
+[autenticação oficial][github-auth].
+
+Depois instale com npx:
+
+```console
+npx --registry=https://npm.pkg.github.com @pathbit/agentdevkit init
+```
+
+As opções de npx, como `--registry`, ficam **antes** do nome do pacote.
+Um `@pathbit:registry` já configurado pode prevalecer sobre essa opção;
+confira o [diagnóstico de registry](troubleshooting.md#download-plataforma-ou-ferramenta-falhando).
+
+### Opções e verificação
+
 Sem comando adicional, o pacote executa `init`. Em terminal interativo,
 pergunta idioma e agentes. No aplicativo desktop, peça ao agente para reunir
 as escolhas no chat e usar `--lang` e `--agents` na CLI.
@@ -34,6 +69,19 @@ Consulte [CLI](cli.md) para acrescentar seleção, destino e simulação. `--jso
 `--yes`, `--dry-run` ou ausência de terminal interativo evitam perguntas.
 Sem escolha explícita ou salva, `all` mantém todos os clientes compatíveis.
 
+Após instalar, confirme a versão, o diagnóstico e os apontamentos:
+
+```console
+npx @pathbit/agentdevkit --version
+npx @pathbit/agentdevkit doctor
+npx @pathbit/agentdevkit sync --check
+```
+
+Se escolheu GitHub Packages, use o mesmo prefixo
+`npx --registry=https://npm.pkg.github.com` nesses comandos. Para fixar a versão,
+use `@pathbit/agentdevkit@0.0.11` no lugar do nome sem versão, em qualquer destino.
+O próximo passo é [preparar as ferramentas](prerequisites.md#depois-de-instalar-o-kit).
+
 ## O que fica no projeto
 
 | Conteúdo | Tratamento |
@@ -102,7 +150,9 @@ e restauração após falha.
 O [fluxo de trabalho](workflow.md) orienta a próxima etapa do projeto.
 Se houver erro, consulte [solução de problemas](troubleshooting.md).
 
-[Wiki](../README.md) · [Spec v0.0.9][spec]
+[Wiki](../README.md) · [Spec de segurança][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.9/SPEC.md
+[spec]: ../specs/security-ecosystem/SPEC.md
+[tokens]: https://github.com/settings/tokens
+[github-auth]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages

package/docs/guides/prerequisites.md

@@ -0,0 +1,123 @@
+---
+description: Instalar Node.js e npm no Windows, macOS ou Linux antes de usar o kit.
+language: pt
+---
+
+# Preparar os pré-requisitos
+
+Instale **Node.js 24+ com npm**. O npm inclui o comando `npx`; não é preciso
+instalar Python, Bun ou o AgentDevKit globalmente. Git é opcional para instalar
+o kit e necessário para trabalhar com o controle de versão do projeto.
+
+## Confira antes de instalar
+
+No terminal do computador ou do agente, execute:
+
+```console
+node --version
+npm --version
+npx --version
+```
+
+Com Node 24+ e os três comandos funcionando, siga para a
+[instalação pelo npm ou GitHub Packages](installation.md#instalar).
+Use o mesmo ambiente em que abrirá o projeto: Windows e WSL, por exemplo,
+têm instalações separadas.
+
+## Windows
+
+No PowerShell, com [WinGet][winget] disponível:
+
+```powershell
+winget install --id OpenJS.NodeJS.LTS --exact --source winget
+```
+
+Sem WinGet, abra o [download oficial do Node.js][node], selecione uma versão
+LTS 24 ou superior e use o instalador Windows `.msi` da sua arquitetura.
+Mantenha npm e a inclusão no PATH habilitados. Feche e reabra o terminal;
+no VS Code, reabra também o terminal integrado. Repita os três comandos acima.
+
+## macOS
+
+No [download oficial][node], selecione Node LTS 24 ou superior e o instalador
+macOS `.pkg`. Conclua a instalação, reabra o terminal e confira as versões.
+O instalador inclui npm e npx.
+
+Se já usa Homebrew, pode manter esse fluxo:
+
+```sh
+brew install node@24
+export PATH="$(brew --prefix node@24)/bin:$PATH"
+```
+
+A segunda linha vale para o terminal atual. Para outros terminais, siga as
+instruções de PATH exibidas pelo Homebrew; não substitua seu perfil inteiro.
+Veja a [fórmula oficial][brew].
+
+## Linux
+
+Em Bash ou Zsh, use o [nvm][nvm] para instalar Node 24 no seu usuário.
+Em Debian/Ubuntu, prepare as dependências se faltarem:
+
+```sh
+sudo apt-get update
+sudo apt-get install -y curl ca-certificates tar xz-utils
+```
+
+Em outra distribuição, instale os equivalentes pelo seu gerenciador de pacotes.
+Execute o instalador oficial do nvm e depois instale o Node:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash
+```
+
+Reabra o terminal para carregar o nvm; então execute:
+
+```sh
+nvm install 24
+nvm use 24
+```
+
+O nvm configura o perfil do seu usuário e inclui npm/npx com o Node.
+Em Alpine ou outra distribuição com musl, confirme o suporte da versão e
+arquitetura no [download oficial][node]; não use um binário glibc nesse ambiente.
+
+## Preparar com ajuda do agente
+
+Você também pode pedir no aplicativo ou terminal do seu agente:
+
+> Confira Node, npm e npx neste ambiente. Se faltarem, instale Node 24+ pelo
+> mecanismo adequado ao meu sistema, preserve a configuração existente e
+> continue até validar os três comandos. Depois me ajude a escolher npm ou
+> GitHub Packages e os agentes que usarei neste projeto.
+
+O agente precisa de acesso ao terminal, à rede e das permissões de instalação
+do sistema. Sem Node/npm, o `npx` ainda não pode executar o kit. Com Node
+18–23 existente, o launcher pode preparar Node 24 localmente; prefira atualizar
+o ambiente para Node 24+ antes de começar.
+
+O [bootstrap do kit][bootstrap] usa `tar` nativo quando precisa baixar um
+runtime, verifica o checksum e não altera o PATH permanentemente.
+
+## Depois de instalar o kit
+
+Na pasta do projeto, prepare e verifique as ferramentas compatíveis:
+
+```console
+npx @pathbit/agentdevkit tools setup
+npx @pathbit/agentdevkit tools check all
+```
+
+Para usar GitHub Packages, acrescente `--registry=https://npm.pkg.github.com`
+antes do nome do pacote, como no [guia de instalação](installation.md#github-packages).
+`tools setup base` limita o preparo a navegador e lint. A instalação dos CLIs
+não instala browsers, FFmpeg nem concede permissões desktop; veja os requisitos
+da tarefa em [ferramentas e testes](tools-and-testing.md).
+
+[Wiki](../README.md) · [Instalar o kit](installation.md)
+
+[node]: https://nodejs.org/en/download
+[winget]: https://learn.microsoft.com/en-us/windows/package-manager/winget/install
+[brew]: https://formulae.brew.sh/formula/node@24
+[nvm]: https://github.com/nvm-sh/nvm#installing-and-updating
+[bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md

package/docs/guides/resources.md

@@ -23,7 +23,7 @@ Os caminhos abaixo são relativos a `.pbai4devs/`.
 | Skill | Procedimento e decisões. | `skills/<grupo>/<nome>/SKILL.md` |
 | Regra | Convenção aplicada a um contexto. | `rules/<nome>/RULE.md` |
 | Comando | Entrada de um caso de uso. | `commands/<nome>/COMMAND.md` |
-| Agente | Papel, ferramentas e limites. | `agents/<nome>/AGENT.md` |
+| Agente | Responsável por uma tarefa. | `agents/<nome>/AGENT.md` |
 | Modelo | Base a preencher. | `templates/<nome>/TEMPLATE.md` |
 | Tool | Configuração e entrada de uma CLI. | `tools/<nome>/TOOL.json` |
 | Script | Automação executável reutilizável. | `scripts/<nome>/SCRIPT.mjs` |
@@ -32,6 +32,53 @@ Uma skill explica como decidir; um script executa a operação. Um comando
 encaminha a essas fontes, sem repetir suas instruções. Uma regra mantém uma
 convenção recorrente; um agente define quem revisa ou executa determinado papel.
 
+Uma skill pode orientar o uso de outras skills, comandos e agentes. Quem faz
+essas chamadas é o cliente de IA, dentro das ferramentas e permissões disponíveis.
+Um workflow é a sequência de passos e entregas descrita no comando; não precisa
+ser outro tipo de arquivo ou um agendamento em segundo plano.
+
+```mermaid
+flowchart LR
+  pedido["Pedido"] --> comando["Comando"]
+  comando --> agente["Agente responsável"]
+  regras["Regras"] -.-> agente
+  agente --> skill["Skill"]
+  skill --> script["Script quando necessário"]
+  script --> tool["Ferramenta local"]
+  tool --> prova["Evidências"]
+  prova --> revisao["Revisão independente"]
+```
+
+O agente principal reúne resultados e mantém o contexto. Quando um cliente
+não permite delegação aninhada, o especialista devolve o próximo passo ao
+principal. Markdown e links não criam processos nem executam código sozinhos.
+
+## Três fluxos completos
+
+| Etapa | Comando | Resultado |
+| --- | --- | --- |
+| Planejar | `planejar-entrega` | Dúvidas, plano e aceites. |
+| Implementar | `implementar-entrega` | Código, testes e documentos. |
+| Auditar | `auditar-seguranca` | Sinais locais e triagem. |
+
+O planejador combina as skills da fase para reunir as decisões. O implementador
+executa o plano aprovado. O auditor interpreta os scanners preparados por
+`preparar-seguranca` e verifica os controles que exigem contexto.
+
+No fluxo de implementação, `validar-entrega` executa as provas e
+`atualizar-documentacao` aciona o documentador. O revisor recebe a entrega
+final por `revisar-entrega`; quem implementou não substitui a revisão independente.
+Falhas retornam ao responsável com evidência e escopo de correção.
+
+Na segurança, scanners e análise manual se complementam. Achados confirmados
+seguem `corrigir-vulnerabilidade`; depois são testados de novo. O
+[guia de segurança](security.md) define preparação, limites e resultados.
+
+Não busque quantidades iguais por tipo: uma skill atende vários comandos,
+um perfil usa várias skills e uma regra vale em diferentes fluxos. Crie um
+perfil quando houver responsabilidade recorrente e contexto próprio; use
+skill para um procedimento e comando para uma entrada de trabalho clara.
+
 Modelos não são documentos aprovados do produto. Ferramentas usam um
 `SCRIPT.mjs` fino para delegar ao instalador comum; não precisam de cópias em
 cada cliente nem de outro instalador escrito do zero.

package/docs/guides/security-references.md

@@ -0,0 +1,97 @@
+---
+description: Ferramentas e skills de segurança locais e open source.
+---
+
+# Referências de segurança
+
+As verificações do kit executam no computador do projeto. Não exigem conta,
+assinatura ou envio de código a um serviço. Downloads de ferramentas e bases
+públicas são etapas explícitas; a análise usa os arquivos locais.
+
+## Ferramentas selecionadas
+
+| Ferramenta | Origem e licença | Função |
+| --- | --- | --- |
+| [Gitleaks][gitleaks] | Comunidade, MIT | Segredos em arquivos e Git. |
+| [OSV-Scanner][osv] | Google, Apache-2.0 | Dependências, com base OSV local. |
+| [Opengrep][opengrep] | Consórcio, LGPL-2.1 | Código, com regras locais. |
+
+O catálogo fixa versões e hashes revisados. `install` verifica o download;
+`check` confere o binário local; `update` aplica o pin revisado no catálogo.
+Nenhum dos três exige Python instalado. O upstream do Gitleaks está focado
+em manutenção e correções; isso deve ser considerado nas próximas revisões.
+
+OSV deve usar `--offline`, não somente `--offline-vulnerabilities`.
+A base precisa ser preparada antes: ausência de dados não é resultado limpo.
+Opengrep usa configuração local e checagem de versão desativada; não use
+`--config auto`. O comando de auditoria normaliza os resultados e remove
+segredos e trechos de código dos relatórios.
+
+## Complementos por necessidade
+
+| Ferramenta | Licença | Quando considerar |
+| --- | --- | --- |
+| [Trivy][trivy] | Apache-2.0 | Imagens, IaC e SBOM. |
+| [ZAP][zap] | Apache-2.0 | Aplicação em execução; exige Java. |
+| [DevSkim][devskim] | MIT | Projetos .NET; exige runtime local. |
+
+Esses complementos não são instalados pelo grupo `security`. Uma adoção exige
+testar seu modo local, dependências, versão e licença. No ZAP, instalação não
+inicia proxy, daemon ou ataque; configure identidades de teste e alvo local.
+No Trivy, `--offline-scan` sozinho não bloqueia toda atualização de base.
+
+Serviços de análise que exigem conta ficam fora desse fluxo. CodeQL CLI não
+atende ao requisito de código aberto; Bandit e rotinas Python ficam fora do
+runtime adotado. Uma opção gratuita não é automaticamente open source.
+
+## Skills de mercado
+
+| Fonte | Recurso | Tratamento |
+| --- | --- | --- |
+| [OpenAI][openai] | Práticas e ameaças | Apache-2.0 por pasta. |
+| [GitHub][copilot] | Revisão de segurança | MIT. |
+| [Trail of Bits][tob] | Contexto e diffs | CC-BY-SA-4.0; candidata. |
+
+Os [pins e licenças do catálogo][catalog] evitam importar uma origem móvel.
+As quatro skills próprias de segurança já acompanham o kit; referências
+externas são opcionais e lidas por tarefa, sem copiar texto para os clientes.
+Preserve atribuição e share-alike dos recursos da Trail of Bits.
+Uma lista estática de CVEs em uma skill não substitui uma base atualizada.
+
+## O artigo como ponto de partida
+
+O [artigo compartilhado][article] orientou cinco temas: acesso aos dados,
+autorização no servidor, acesso por ID, segredos e entradas não confiáveis.
+O kit trata essas perguntas com verificações específicas:
+
+- PostgreSQL/Supabase usa RLS e políticas; Firebase usa Security Rules.
+  Papéis privilegiados e SDKs de servidor precisam de controles próprios.
+- Ocultar um botão não autoriza uma operação. Teste sem sessão e com dois
+  usuários ou tenants, incluindo acesso ao objeto de outra identidade.
+- Variáveis enviadas ao bundle são públicas; variáveis do servidor não são
+  automaticamente expostas. Um segredo confirmado exige remoção e rotação.
+- Validação de entrada, consultas parametrizadas, codificação de saída,
+  controles de upload e limites de uso resolvem riscos diferentes.
+
+As referências técnicas são [RLS][rls], [Firebase Rules][firebase],
+[autorização][authz], [segredos][secrets] e [uploads][uploads]. O kit não usa as
+estatísticas do artigo como comprovação de segurança do projeto.
+
+[Segurança no fluxo](security.md) · [Recursos](resources.md)
+
+[gitleaks]: https://github.com/gitleaks/gitleaks/tree/v8.30.1
+[osv]: https://github.com/google/osv-scanner/tree/v2.7.1
+[opengrep]: https://github.com/opengrep/opengrep/tree/v1.33.1
+[trivy]: https://github.com/aquasecurity/trivy
+[zap]: https://www.zaproxy.org/docs/desktop/start/features/
+[devskim]: https://github.com/microsoft/DevSkim
+[openai]: https://github.com/openai/skills
+[copilot]: https://github.com/github/awesome-copilot
+[tob]: https://github.com/trailofbits/skills
+[catalog]: ../../.pbai4devs/external-skills/CATALOG.json
+[article]: https://manodeyvin.com.br/p/5-vacilacoes-de-seguranca-que-a-ia
+[rls]: https://supabase.com/docs/guides/database/postgres/row-level-security
+[firebase]: https://firebase.google.com/docs/rules
+[authz]: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
+[secrets]: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
+[uploads]: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html

package/docs/guides/security.md

@@ -0,0 +1,32 @@
+---
+description: Segurança com scanners locais, triagem e provas de controles.
+language: pt
+---
+
+# Segurança local
+
+O kit instala skills, regras, comandos e perfis para revisar segurança.
+Os scanners exigem preparo explícito; nenhuma auditoria ou aplicação começa
+em segundo plano apenas porque os arquivos de instrução foram instalados.
+
+O [guia operacional][guide] acompanha o hub no projeto consumidor. Ele explica
+preparo das ferramentas, bases offline, relatório e triagem, além dos testes
+manuais de autorização, isolamento de dados, entradas e abuso.
+
+- [Preparar segurança][prepare]: instalar e verificar os scanners locais.
+- [Auditar segurança][audit]: analisar o alvo autorizado e interpretar sinais.
+- [Revisar autorização][authorization]: testar identidade e acesso por recurso.
+- [Modelar ameaças][threats]: antecipar riscos das fronteiras de confiança.
+- [Curadoria](security-references.md): fontes, licenças e ferramentas avaliadas.
+
+Use o [mapa do ecossistema](resources.md) para entender como perfis, skills,
+comandos, regras e scripts se conectam. Resultados ficam em `.agent-tests/`;
+scanners sozinhos não aprovam a segurança de um produto.
+
+[Wiki](../README.md) · [Ferramentas e testes](tools-and-testing.md)
+
+[guide]: ../../.pbai4devs/skills/seguranca/REFERENCE.md
+[prepare]: ../../.pbai4devs/commands/preparar-seguranca/COMMAND.md
+[audit]: ../../.pbai4devs/commands/auditar-seguranca/COMMAND.md
+[authorization]: ../../.pbai4devs/skills/seguranca/revisar-autorizacao/SKILL.md
+[threats]: ../../.pbai4devs/skills/seguranca/modelar-ameacas/SKILL.md

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

@@ -11,7 +11,8 @@ nem escolhe a stack da aplicação. Consulte o [catálogo][tools].
 
 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`.
+do sistema operacional antes de iniciar `npx`; siga os
+[pré-requisitos por sistema](prerequisites.md).
 
 Para preparar somente o runtime a partir do hub:
 

package/docs/guides/troubleshooting.md

@@ -29,7 +29,7 @@ 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]. |
+| `E401` ou `E403` no registry | No npm, confira o destino; no GitHub, confira [token e login][github-install]. |
 | `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. |
@@ -96,15 +96,31 @@ Para manter a instalação e sua seleção de clientes, prefira a CLI.
 
 ## 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:
+Confira o destino padrão e um possível mapeamento do escopo:
 
 ```console
-npm config set @pathbit:registry https://registry.npmjs.org --location=user
+npm config get registry
+npm config get @pathbit:registry
 ```
 
-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.
+Um valor de `@pathbit:registry` prevalece sobre `npx --registry=...`.
+Se esse mapeamento foi criado apenas para uma instalação antiga, remova
+**somente essa chave** do arquivo que a definiu. No arquivo do usuário:
+
+```console
+npm config delete @pathbit:registry --location=user
+```
+
+Se a chave está no `.npmrc` do projeto ou em variáveis de ambiente, revise
+nesse local; o comando acima não muda essas configurações. Preserve mapeamentos
+exigidos por outras dependências e nunca apague o `.npmrc` inteiro.
+Sem mapeamento do escopo, escolha o registry por execução no
+[guia de instalação](installation.md#instalar).
+
+O npm público não exige login para baixar o kit. No GitHub Packages, use
+um token clássico com `read:packages` e o [login específico][github-install].
+Publicar versões exige permissões adicionais; login no GitHub CLI (`gh`)
+não configura automaticamente a autenticação do npm.
 
 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
@@ -148,4 +164,4 @@ Use as [issues do projeto][issues] ou volte ao [índice](../README.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
+[github-install]: installation.md#github-packages

package/docs/maintainers/README.md

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

package/docs/maintainers/maintenance.md

@@ -32,6 +32,12 @@ 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.
 
+O workflow [Security tools smoke][security-ci] instala os três scanners com
+pins revisados em Linux, macOS e Windows. Depois analisa fixtures locais sem
+rede, com casos inseguros e corrigidos. Essa prova valida o funcionamento das
+ferramentas; não certifica a segurança de uma aplicação. Relatórios normalizados
+são guardados como artifacts, sem binários ou fontes das fixtures.
+
 `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.
@@ -67,9 +73,9 @@ nada. Nunca versione o tarball ou seus relatórios.
 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.
+Também envia o mesmo pacote ao [npm público e GitHub Packages](packages.md),
+confere a integridade nos dois destinos e testa versão, instalação, diagnóstico
+e sincronização. O consumo pelo npm é anônimo; pelo GitHub, autenticado.
 
 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
@@ -86,10 +92,14 @@ Para reiniciar uma publicação que falhou, use **Re-run failed jobs** ou
 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
+Se a release já existe e falta somente o pacote em um registro, use o modo
 `package_only` descrito em [pacote npm](packages.md#publicar-pelo-actions).
 Ele não tenta recriar a release existente.
 
+Execuções concluídas com falha podem ser removidas mediante solicitação,
+sem apagar execuções aprovadas, tags ou releases. Confira a lista e preserve
+os identificadores das execuções e releases mantidas antes da limpeza.
+
 ## Conferir a entrega pública
 
 Confira a versão na [página do pacote][package] e instale pelo nome em um
@@ -102,3 +112,4 @@ aprovado; uma aprovação de CI não substitui a instalação real pelo registro
 [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
+[security-ci]: https://github.com/pathbit/AgentDevKit/actions/workflows/security-tools.yml

package/docs/maintainers/packages.md

@@ -1,13 +1,24 @@
 ---
-description: Instalação e publicação do pacote npm público do AgentDevKit.
+description: Publicação sincronizada do AgentDevKit no npm e no GitHub Packages.
 ---
 
-# Pacote npm público
+# Pacote nos dois registries
 
 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.
 
+Cada versão usa o mesmo TGZ nos dois destinos, com o mesmo número e checksum.
+
+| Destino | Visibilidade | Instalação |
+| --- | --- | --- |
+| [npm público][package] | Pública | `npx`, sem login; opção padrão. |
+| [GitHub Packages][github] | Pública | Exige autenticação do GitHub. |
+
+No GitHub Packages, público significa que o pacote é visível a todos;
+o registry npm do GitHub exige token também para baixar pacotes públicos.
+Consulte a [autenticação oficial][github-auth] se escolher esse destino.
+
 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
@@ -17,13 +28,21 @@ 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:
+Prepare os [pré-requisitos](../guides/prerequisites.md), depois escolha o destino:
 
 ```console
 npx @pathbit/agentdevkit init
 ```
 
-Para repetir uma instalação, fixe a versão desejada após o nome do pacote.
+O comando acima usa o npm público, sem login. Para GitHub Packages, faça a
+[autenticação inicial](../guides/installation.md#github-packages) e execute:
+
+```console
+npx --registry=https://npm.pkg.github.com @pathbit/agentdevkit init
+```
+
+Para repetir uma instalação, fixe a versão após o nome, como
+`@pathbit/agentdevkit@0.0.11`, nos dois destinos.
 
 Acrescente `--agents codex,claude` para selecionar clientes, `--dry-run` para
 simular ou use `update`, `doctor` e `sync --check` no lugar de `init`.
@@ -34,12 +53,12 @@ da aplicação. Para conferir as versões:
 npm view @pathbit/agentdevkit versions --json
 ```
 
-Se existir um mapeamento antigo para o GitHub Packages, siga a
-[correção de registry][fix].
+Se existir um mapeamento de `@pathbit` que impeça alternar o destino, siga o
+[diagnóstico de registry][fix].
 
 ## Publicar pelo Actions
 
-A publicação usa o mesmo TGZ aprovado pelo CI, com acesso público. O workflow
+A publicação usa o mesmo TGZ aprovado pelo CI nos dois registries. 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.
 
@@ -48,6 +67,11 @@ variável interna `NPM_TOKEN` somente na publicação. O token precisa permitir
 publicar no escopo `@pathbit`; credenciais nunca entram nos arquivos
 versionados.
 
+O passo do GitHub Packages usa `GITHUB_TOKEN` com `packages: write` e confirma
+a visibilidade pública. Tokens de um registry não são enviados ao outro.
+O npm continua usando `NPMJS_TOKEN` ou OIDC, com prova de consumo anônimo;
+as provas do GitHub usam autenticação própria.
+
 Sem esse secret, o workflow usa OIDC. Configure o **Trusted Publisher** do npm:
 
 | Campo | Valor |
@@ -61,14 +85,19 @@ 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:
+Por padrão, uma tag publica nos dois destinos. Para completar o GitHub
+Packages de uma tag existente, preservando a release e o npm:
 
 ```console
-gh workflow run release.yml --ref master -f tag=v0.0.9 -F package_only=true
+gh workflow run Release -f tag=v0.0.11 -F package_only=true -f registry=github
 ```
 
 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
+`registry` aceita `both`, `npm` ou `github`. `package_only` impede alterar a
+release existente; cada registry recusa versões com bytes diferentes e pula
+a publicação se a mesma versão já estiver correta.
+
+Depois do envio ao npm, 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 é
@@ -76,12 +105,15 @@ baixável; metadados visíveis sozinhos não comprovam uma instalação funciona
 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.
+O GitHub Packages verifica os mesmos comandos com autenticação. Metadados
+devem indicar visibilidade pública e associação ao repositório correto.
+Uma falha parcial permite repetir apenas o destino pendente usando o artefato
+original; nunca recrie uma versão publicada com outro conteúdo.
 
 [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
+[github]: https://github.com/pathbit/AgentDevKit/pkgs/npm/agentdevkit
+[github-auth]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry
 [fix]: ../guides/troubleshooting.md#download-plataforma-ou-ferramenta-falhando