@pathbit/agentdevkit 0.0.9 → 0.0.10

package/CHANGELOG.md

@@ -4,6 +4,14 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.10 — 2026-11-12
+
+- Mesmo pacote publicado no npm e GitHub Packages, com versão e bytes iguais.
+- Instalação via npx nos dois registries, com credenciais isoladas por destino.
+- Guias de pré-requisitos para Windows, macOS e Linux, incluindo Node/npm.
+- README, wiki e notas de release com os dois caminhos de instalação.
+- Diagnóstico de mapeamentos antigos de registry sem apagar configurações.
+
 ## 0.0.9 — 2026-11-12
 
 - Links e configurações humanos preservados na instalação dos agentes.

package/README.en.md

@@ -18,12 +18,21 @@ See the [supported clients][clients].
 
 ## Start in your project
 
-With Node.js 18+ and npm, run this in your project. No login is required:
+Use Node.js 24+ with npm. The [prerequisites guide][prerequisites] explains
+installation on Windows, macOS and Linux.
+
+From your project folder, install through **npm**, without logging in:
 
 ```console
 npx @pathbit/agentdevkit init
 ```
 
+Or use **GitHub Packages**, after [authenticating with GitHub][github-install]:
+
+```console
+npx --registry=https://npm.pkg.github.com @pathbit/agentdevkit init
+```
+
 Choose your coding agents when prompted, or pass `--agents codex,claude`.
 The project saves your selection; use `agents` to view or change it later.
 Without interaction or a saved choice, the default is `all` clients.
@@ -32,9 +41,9 @@ Then open the project in your coding agent and ask:
 
 > Read AGENTS.md and use the proximos-passos skill to guide my next steps.
 
-See [installation](docs/guides/installation.md) for Windows, missing Node, previews
-and updates. Install and update through the [public npm package][packages]; the
-[v0.0.9 release][release] retains artifacts and checksums for verification.
+See [installation](docs/guides/installation.md) for runtime preparation, previews
+and updates. Both [package registries][packages] provide the same version;
+the [v0.0.10 release][release] retains artifacts and checksums for verification.
 No global installation is required.
 The CLI supports `pt`, `en` and `es`; it saves your selection per project.
 
@@ -42,6 +51,7 @@ The CLI supports `pt`, `en` and `es`; it saves your selection per project.
 
 | I want to… | Read |
 | --- | --- |
+| Prepare Node.js and npm | [Prerequisites][prerequisites] |
 | Understand the kit | [Documentation wiki](docs/README.md) |
 | Plan or resume a project | [Workflow](docs/guides/workflow.md) |
 | Improve existing documentation | [Inventory and additions](docs/guides/documentation.md) |
@@ -79,7 +89,7 @@ forms. See [how to participate](docs/maintainers/community.md).
 agent to read `AGENTS.md`.
 
 [clients]: .pbai4devs/COMPATIBILIDADE.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.9
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.10
 [npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
 [npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
 [license-badge]: https://img.shields.io/badge/license-MIT-blue
@@ -88,3 +98,5 @@ agent to read `AGENTS.md`.
 [help]: docs/guides/troubleshooting.md
 [issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
 [packages]: docs/maintainers/packages.md
+[prerequisites]: docs/guides/prerequisites.md
+[github-install]: docs/guides/installation.md#github-packages

package/README.es.md

@@ -18,12 +18,21 @@ son locales y no se versionan.
 
 ## Empezar en tu proyecto
 
-Con Node.js 18+ y npm, ejecuta en tu proyecto, sin iniciar sesión:
+Usa Node.js 24+ con npm. La [guía de requisitos][prerequisites] explica
+la instalación en Windows, macOS y Linux.
+
+Desde la carpeta de tu proyecto, instala mediante **npm**, sin iniciar sesión:
 
 ```console
 npx @pathbit/agentdevkit init
 ```
 
+O usa **GitHub Packages**, después de [autenticarte en GitHub][github-install]:
+
+```console
+npx --registry=https://npm.pkg.github.com @pathbit/agentdevkit init
+```
+
 Elige tus agentes en la pregunta inicial o usa `--agents codex,claude`.
 La selección se guarda en el proyecto; `agents` permite consultarla o cambiarla.
 Sin interacción ni selección anterior, el valor predeterminado es `all`.
@@ -32,10 +41,10 @@ Después, abre el proyecto en tu agente y pide:
 
 > Lee AGENTS.md y usa la skill proximos-passos para orientar mi trabajo.
 
-La [guía de instalación](docs/guides/installation.md) incluye Windows, Node ausente,
-simulación y actualización. Instala y actualiza mediante el
-[paquete npm público][packages];
-la [release v0.0.9][release] conserva artefactos y checksums para verificarlos.
+La [guía de instalación](docs/guides/installation.md) incluye preparación del
+runtime, simulación y actualización. Los dos [registros][packages] ofrecen
+la misma versión;
+la [release v0.0.10][release] conserva artefactos y checksums para verificarlos.
 No requiere instalación global.
 La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 
@@ -43,6 +52,7 @@ La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 
 | Quiero… | Leer |
 | --- | --- |
+| Preparar Node.js y npm | [Requisitos][prerequisites] |
 | Entender el kit | [Wiki](docs/README.md) |
 | Planificar o retomar un proyecto | [Flujo](docs/guides/workflow.md) |
 | Mejorar documentación existente | [Inventario y complementos](docs/guides/documentation.md) |
@@ -81,7 +91,7 @@ formularios. Consulta [cómo participar](docs/maintainers/community.md).
 al agente que lea `AGENTS.md`.
 
 [clients]: .pbai4devs/COMPATIBILIDADE.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.9
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.10
 [npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
 [npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
 [license-badge]: https://img.shields.io/badge/license-MIT-blue
@@ -90,3 +100,5 @@ al agente que lea `AGENTS.md`.
 [help]: docs/guides/troubleshooting.md
 [issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
 [packages]: docs/maintainers/packages.md
+[prerequisites]: docs/guides/prerequisites.md
+[github-install]: docs/guides/installation.md#github-packages

package/README.md

@@ -16,12 +16,22 @@ fica em `src/`, os testes em `tests/` e os recursos compartilhados em
 
 ## Começar em um projeto
 
-Com Node.js 18+ e npm, execute na pasta do seu projeto, sem login:
+Prepare [Node.js 24+ e npm](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/prerequisites.md) no Windows, macOS ou
+Linux. Na pasta do seu projeto, instale pelo **npm público**, sem login:
 
 ```console
 npx @pathbit/agentdevkit init
 ```
 
+Ou use **GitHub Packages**, após [autenticar no GitHub][github-install]:
+
+```console
+npx --registry=https://npm.pkg.github.com @pathbit/agentdevkit init
+```
+
+Os dois registries oferecem o mesmo pacote. O GitHub exige token para download,
+mesmo sendo público; o npm continua sendo a opção sem login.
+
 Escolha os agentes na pergunta inicial ou informe `--agents codex,claude`.
 A escolha fica salva no projeto; `agents` permite consultá-la ou alterá-la.
 Sem interação ou escolha anterior, o padrão é `all` (todos os clientes).
@@ -32,7 +42,7 @@ Depois, abra o projeto no seu agente e peça:
 
 Windows, instalação sem Node, simulação e atualização estão no
 [guia de instalação](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md). A distribuição usa a
-versão publicada no [npm público][packages] e na [release v0.0.9][release],
+versão publicada no [npm e GitHub Packages][packages] e na [release v0.0.10][release],
 sem instalação global. Instalação e atualização usam o pacote do registro;
 os arquivos da release servem para conferir os artefatos publicados.
 O idioma da CLI pode ser `pt`, `en` ou `es`.
@@ -41,6 +51,7 @@ O idioma da CLI pode ser `pt`, `en` ou `es`.
 
 | Quero… | Ler |
 | --- | --- |
+| Preparar Node/npm e instalar o kit | [Pré-requisitos](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/prerequisites.md) · [Instalação](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md) |
 | Entender e começar | [Wiki](https://github.com/pathbit/AgentDevKit/blob/master/docs/README.md) |
 | Planejar ou retomar um projeto | [Fluxo de trabalho](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/workflow.md) |
 | Evoluir documentos existentes | [Inventário e complementos](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/documentation.md) |
@@ -90,7 +101,8 @@ ao seu agente para ler `AGENTS.md`.
 [help]: https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/troubleshooting.md
 [issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
 [packages]: https://github.com/pathbit/AgentDevKit/blob/master/docs/maintainers/packages.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.9
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.10
 [npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
 [npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
 [license-badge]: https://img.shields.io/badge/license-MIT-blue
+[github-install]: https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md#github-packages

package/docs/README.md

@@ -22,7 +22,8 @@ pode trocar de agente sem manter várias cópias das mesmas instruções.
 
 | Objetivo | Caminho |
 | --- | --- |
-| Primeiro uso | [Instalar][install] → [seguir o fluxo][flow] |
+| Preparar o computador | [Node/npm no Windows, macOS e Linux](guides/prerequisites.md) |
+| Primeiro uso | [Instalar via npm ou GitHub Packages][install] → [seguir o fluxo][flow] |
 | Projeto em andamento | [Instalar com simulação][install] → [retomar][flow] |
 | Evoluir documentação existente | [Inventariar e complementar](guides/documentation.md) |
 | Personalizar agentes | [Recursos][resources] → [compatibilidade][clients] |
@@ -31,7 +32,7 @@ pode trocar de agente sem manter várias cópias das mesmas instruções.
 | Contribuir com o kit | [Contribuir][contrib] → [design](product/design.md) |
 | Desenvolver e experimentar | [Guia rápido][development] → [exemplos][examples] |
 | Preparar uma versão | [Manutenção e releases](maintainers/maintenance.md) |
-| Publicar ou instalar o pacote npm | [npm público](maintainers/packages.md) |
+| Publicar o pacote nos dois registries | [npm e GitHub Packages](maintainers/packages.md) |
 | Relatar um bug ou propor melhoria | [Participar](maintainers/community.md) |
 
 ## Entenda os termos

package/docs/guides/README.md

@@ -4,7 +4,8 @@ description: Guias de instalação, uso e verificação do AgentDevKit.
 
 # Guias de uso
 
-- [Instalação](installation.md)
+- [Pré-requisitos: Node/npm no Windows, macOS e Linux](prerequisites.md)
+- [Instalação: npm e GitHub Packages](installation.md)
 - [Comandos da CLI](cli.md)
 - [Fluxo de trabalho](workflow.md)
 - [Evoluir documentação existente](documentation.md)

package/docs/guides/cli.md

@@ -10,6 +10,9 @@ Execute o pacote do npm público por `npx`, sem login:
 npx @pathbit/agentdevkit --help
 ```
 
+Para GitHub Packages, autentique conforme a [instalação](installation.md#github-packages)
+e use o prefixo `npx --registry=https://npm.pkg.github.com` nos mesmos comandos.
+
 Nas tabelas, `agentdevkit` representa esse executável. No checkout das fontes,
 use `npm run cli -- <comando>` ou `node bin/agentdevkit.mjs`.
 Esse código não é copiado ao projeto

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.10` 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 v0.0.10][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.9/SPEC.md
+[spec]: ../specs/v0.0.10/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/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

@@ -67,9 +67,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 +86,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

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.10`, 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.10 -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

package/docs/product/prd.md

@@ -1,7 +1,7 @@
 ---
 description: Requisitos da distribuição portátil AgentDevKit.
 status: aprovado
-version: 0.0.9
+version: 0.0.10
 ---
 
 # PRD do AgentDevKit

package/docs/product/roadmap.md

@@ -20,6 +20,7 @@ status: vigente
 | Compatibilidade real v0.0.7 | Testes em clones existentes | [Spec][oss]. |
 | Preservação v0.0.8 | Auditoria e regressões | [Spec][robustness]. |
 | Coexistência v0.0.9 | Agentes, documentos e projetos reais | [Spec][coexistence]. |
+| Instalação nos dois registries v0.0.10 | Pacote e guias de pré-requisitos | [Spec][dual-install]. |
 
 A primeira entrega segue a [spec v0.0.1](../specs/v0.0.1/SPEC.md), disponível
 na [release v0.0.1][release]. Os detalhes de mudanças estão no
@@ -42,3 +43,4 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [oss]: ../specs/v0.0.7/SPEC.md
 [robustness]: ../specs/v0.0.8/SPEC.md
 [coexistence]: ../specs/v0.0.9/SPEC.md
+[dual-install]: ../specs/v0.0.10/SPEC.md

package/docs/specs/README.md

@@ -14,6 +14,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.7](v0.0.7/SPEC.md): projetos reais e proteção local de artefatos.
 - [v0.0.8](v0.0.8/SPEC.md): preservação, transações e validação aprofundada.
 - [v0.0.9](v0.0.9/SPEC.md): coexistência e evolução documental sem perdas.
+- [Dois registries](dual-registry/SPEC.md): versão e bytes iguais no npm e GitHub.
+- [v0.0.10](v0.0.10/SPEC.md): release com instalação pelos dois registries e pré-requisitos.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/dual-registry/SPEC.md

@@ -0,0 +1,43 @@
+---
+description: Mesma versão pública no npm e GitHub Packages e limpeza do histórico falho.
+status: aprovado
+---
+
+# Publicação sincronizada
+
+## Objetivo
+
+Remover as execuções antigas com erro, preservando execuções aprovadas e
+releases publicadas. Publicar o mesmo AgentDevKit no npm e GitHub Packages,
+sem mudar o número ou o conteúdo de uma versão já publicada.
+
+## Contrato
+
+- Excluir somente execuções concluídas com falha confirmada.
+- Preservar tags, releases, assets e execuções aprovadas.
+- Usar o TGZ original aprovado pelo CI nos dois registries.
+- Manter `npx` pelo npm público sem autenticação como opção padrão.
+- Autenticar o GitHub com token próprio, sem compartilhar credenciais.
+- Confirmar visibilidade pública, versão e integridade nos dois destinos.
+- Publicar ambos nas próximas tags; permitir completar só um destino.
+- Recusar uma versão existente com bytes diferentes; nunca reempacotar a tag.
+
+## Critérios de aceite
+
+| ID | Prova |
+| --- | --- |
+| AC-001 | Execuções falhas removidas; aprovadas e releases preservadas. |
+| AC-002 | Mesma versão e mesmo checksum nos dois registries. |
+| AC-003 | GitHub público e associado ao repositório correto. |
+| AC-004 | Tokens isolados e acesso anônimo ao npm preservado. |
+| AC-005 | Automação publica ambos e permite retomar um destino. |
+| AC-006 | Testes e revisão aprovados; consumo dos dois destinos verificado. |
+
+## Validação
+
+Comparar inventários remotos antes/depois da limpeza. Testar perfis de registry,
+erros de autenticação, integridade divergente, repetição e seleção do workflow.
+Completar a versão `0.0.9` no GitHub com seu artefato original, comparar os
+registries e provar instalação, diagnóstico e sincronização.
+
+Provas ficam em `tmp/` ou `.agent-tests/`, ignoradas pelo Git.

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

@@ -0,0 +1,9 @@
+---
+description: Distribuição pelos dois registries e preparo dos pré-requisitos.
+---
+
+# Versão 0.0.10
+
+[Spec](SPEC.md): publicar e verificar os dois caminhos de instalação.
+
+[Specs](../README.md) · [Changelog](../../../CHANGELOG.md)

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

@@ -0,0 +1,42 @@
+---
+description: Publicação da documentação de instalação e da distribuição nos dois registries.
+status: aprovado
+version: 0.0.10
+---
+
+# Publicar e verificar os dois caminhos de instalação
+
+## Objetivo
+
+Publicar a versão 0.0.10 com os guias de pré-requisitos e instalação já
+aprovados. Disponibilizar os mesmos bytes no npm e GitHub Packages e provar
+o consumo da versão publicada nos dois destinos.
+
+## Contrato
+
+- Manter npm público sem login e GitHub Packages com autenticação própria.
+- Usar somente o artefato aprovado pelo CI do commit da tag.
+- Conferir versão, integridade, visibilidade pública e associação ao repositório.
+- Incluir os dois comandos de instalação no README, guias e notas da release.
+- Preservar versões anteriores, arquivos humanos e configurações existentes.
+- Guardar downloads e evidências em diretórios ignorados.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Versão, lockfile, changelog, guias e notas coerentes com 0.0.10. |
+| AC-002 | CI aprovado nos quatro perfis e tag no commit verificado. |
+| AC-003 | Versão 0.0.10 pública nos dois registries, com bytes iguais ao CI. |
+| AC-004 | Versão, init, doctor e sync --check passam nos dois registries. |
+| AC-005 | Licença e guias incluídos, sem artefatos locais ou credenciais. |
+
+## Validação
+
+Testar geração das notas e distribuição local. Após o CI, publicar a tag,
+baixar o artefato original e comparar os checksums da release e dos registries.
+Usar caches e projetos novos: npm sem credenciais; GitHub com token exclusivo.
+Conferir `latest`, README público, licença e os quatro comandos da CLI.
+
+Os instaladores nativos dos sistemas são documentados com fontes oficiais;
+esta release não afirma reinstalá-los em máquinas que já têm os pré-requisitos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",