@pathbit/agentdevkit 0.0.8 → 0.0.10

package/docs/guides/documentation.md

@@ -0,0 +1,63 @@
+---
+description: Evoluir documentos existentes e criar somente o que falta.
+---
+
+# Documentação sem perder o contexto
+
+O pacote instala as skills e suas ferramentas. O agente usa esses recursos
+para ler o projeto, propor complementos e editar os documentos autorizados.
+
+## Começar pelo que existe
+
+Depois de instalar o kit, peça ao seu agente:
+
+```text
+Use atualizar-documentacao. Primeiro inventarie e leia os documentos existentes.
+Proponha complementos por arquivo, preservando conteúdo, nomes e decisões.
+Organize por índices e links; crie apenas documentos que realmente faltam.
+```
+
+O inventário pode ser consultado na raiz do projeto:
+
+```console
+node .pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs
+```
+
+O campo `documentation` lista documentos encontrados, possíveis papéis e
+limitações da busca. Os papéis são indícios: o agente ainda precisa ler e
+confirmar o conteúdo. Um nome como `ARCHITECTURE.md` pode servir ao design;
+não é necessário renomeá-lo nem recriá-lo em outra pasta.
+
+## Planejar o complemento
+
+| Situação | Ação |
+| --- | --- |
+| Documento já suficiente | Manter e registrar ausência de impacto. |
+| Falta uma informação comprovada | Acrescentar à seção apropriada. |
+| Documentos difíceis de encontrar | Criar ou completar índices e links. |
+| Documento necessário não existe | Combinar caminho e criar só o necessário. |
+| Decisão não encontrada ou contraditória | Perguntar antes de escrever. |
+
+Os templates ajudam a identificar lacunas. Não substituem documentos
+existentes. Preserve suas seções, âncoras, fatos e decisões; repetir o fluxo
+não deve duplicar conteúdo. Não mova nem exclua arquivos para padronizar.
+
+## Projeto novo ou existente
+
+Em projeto existente, aproveite README, guias, ADRs e documentos de produto.
+Preparar o ambiente ou melhorar a documentação não exige reiniciar o produto.
+
+Em projeto novo, descubra produto e experiência antes de arquitetura e specs.
+Enquanto o objetivo for apenas configurar agentes, mantenha os modelos sem
+inventar PRD, tecnologia ou aprovação. Siga o [fluxo de trabalho](workflow.md).
+
+## Conferir o resultado
+
+Revise o diff e os links. Confirme que o conteúdo anterior foi preservado,
+que arquivos fora do plano não mudaram e que não surgiram decisões inventadas.
+Use `verificar-trabalho` e `revisar-entrega`; salve as provas em `.agent-tests/`.
+
+[Wiki](../README.md) · [Skill compartilhada][skill] · [Testes][tests]
+
+[skill]: ../../.pbai4devs/skills/projeto/atualizar-documentacao/SKILL.md
+[tests]: ../../tests/README.md

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 |
@@ -84,9 +132,16 @@ gerenciados alterados geram conflito; use `--force` somente após revisar o
 backup e o conteúdo que será substituído. Preserve os dados locais, as
 configurações próprias e os commits do projeto.
 
-Links simbólicos em caminhos usados pela instalação podem bloquear a operação.
-O kit informa o caminho e não converte nem remove o link automaticamente.
-Use a simulação para identificar esse caso antes de aplicar.
+Entradas, configurações, skills e agentes humanos permanecem intactos, mesmo
+quando seus nomes coincidem com os do kit. Links simbólicos preexistentes nas
+entradas ou nos clientes são preservados sem leitura ou escrita pelo link.
+O campo `preserved` do JSON informa os caminhos que o kit deixou sob controle
+do projeto; os apontamentos são gerados nas demais rotas disponíveis.
+
+Essa preservação não autoriza trocar arquivos gerenciados por links. Links
+em caminhos já pertencentes ao kit, no hub, no estado ou em ferramentas
+continuam sujeitos à recusa de segurança. Nenhum link humano é adotado como
+propriedade do kit, e `--force` não o substitui.
 
 Arquivos humanos não se tornam gerenciados apenas por conterem um link.
 As alterações de arquivos existentes preservam permissões, inclusive em backup
@@ -95,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.8][spec]
+[Wiki](../README.md) · [Spec v0.0.10][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.8/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/resources.md

@@ -84,18 +84,19 @@ node .pbai4devs/scripts/verificar-recursos/SCRIPT.mjs
 O primeiro comando atualiza apontamentos e índices; `--check` só compara.
 O manifesto instalado respeita os clientes escolhidos. Não o substitua por uma
 lista de todos para reparar recursos; altere a seleção pela CLI se necessário.
-Conflitos de conteúdo próprio exigem revisão. Quando a substituição for
+Conflitos em arquivos gerenciados exigem revisão. Quando a substituição for
 intencional, `--force` faz backup local antes de reparar caminhos gerenciados.
 Não apague pastas inteiras para contornar um conflito.
 
-O `--force` desse script pode limpar extras nas quatro áreas dos clientes,
-com backup. Ele não equivale a `agentdevkit sync --force`: a CLI controla sua
-própria lista de arquivos e preserva recursos locais não registrados por ela.
-Escolha a operação pelo escopo; não prometa preservação indistinta.
+Recursos nativos humanos são preservados, inclusive com `--force` e nomes
+iguais aos do kit. Links humanos são tratados como caminhos opacos; o gerador
+não os atravessa. A CLI informa essas rotas em `preserved` no JSON.
 
 Não edite ou versione `catalog.json`, `skills.json`, `rules.json` ou
 `agents.json`: são derivados locais. Configurações nativas e documentos
 do projeto não devem ser substituídos por cópias desses índices.
+Em uma instalação existente, `verificar-recursos` confere o hub e as derivações
+registradas, sem exigir frontmatter nos documentos humanos do projeto.
 
 ## O que permanece fora dos espelhos
 

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. |
@@ -84,27 +84,43 @@ peça ao agente para comparar as fontes e planejar o reparo com `init`/`sync`.
 Entradas humanas permanecem separadas das geradas. Na migração de versões
 antigas, o kit retira somente seu bloco reconhecido e preserva o texto humano.
 Não altere os marcadores dos blocos que ainda serão migrados.
-Não transforme diretórios de agentes ou o hub em links simbólicos.
+Links humanos preexistentes nas entradas e nos clientes são mantidos sem
+atravessá-los. Consulte `preserved` no JSON para ver as rotas que não receberam
+apontamentos. Não transforme o hub ou caminhos já gerenciados em links.
 Destinos dentro de `.git`, `node_modules` ou `.pbai4devs` são recusados,
 inclusive com variações de maiúsculas/minúsculas.
 
-Na CLI, `sync --force` substitui conflitos identificados, com backup, e
-preserva arquivos nativos próprios que não são do kit. O script compartilhado
-`sincronizar-agentes` tem um modo `--force` mais amplo: pode limpar conteúdo
-extra nas áreas de skills, agents, commands e rules. Prefira a CLI para manter
-a instalação; não trate esses dois comandos como equivalentes.
+Na CLI e no script `sincronizar-agentes`, `--force` repara conflitos gerenciados
+com backup. Recursos nativos humanos e links preservados continuam intactos.
+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/guides/workflow.md

@@ -41,6 +41,8 @@ documentos, não comprova comportamento e não autoriza substituir decisões.
 
 ## 2. Reunir as perguntas no início
 
+Antes de criar documentos, [inventarie e leia o que existe](documentation.md).
+Reutilize os caminhos e complemente lacunas, sem substituir pelo template.
 Antes de escrever documentos ou código, leia o contexto já disponível.
 Reúna as dúvidas que alteram objetivo, escopo, dependências ou critérios.
 Não pergunte novamente o que o usuário já decidiu ou o projeto já registra.

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.8 -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/design.md

@@ -66,6 +66,18 @@ 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.
 
+## Inventário e evolução documental
+
+O inspetor inclui metadados de documentação no JSON: caminhos, tipo, papel
+provável, origem da indicação, tamanho e hash quando couber nos limites.
+Ele não escreve arquivos, não emite conteúdo e não lê destinos simbólicos.
+Limites e avisos impedem interpretar uma busca parcial como ausência de docs.
+
+A skill `atualizar-documentacao` usa esse inventário antes dos templates.
+O agente lê o material, propõe ações por arquivo e aplica complementos
+autorizados. Organização usa índices e links, preservando caminhos e conteúdo.
+Produto e aprovações dependem das decisões reais do usuário.
+
 ## Runtime
 
 O launcher aceita Node 18+ e prepara Node 24+ antes de carregar o núcleo.

package/docs/product/prd.md

@@ -1,7 +1,7 @@
 ---
 description: Requisitos da distribuição portátil AgentDevKit.
 status: aprovado
-version: 0.0.6
+version: 0.0.10
 ---
 
 # PRD do AgentDevKit
@@ -40,6 +40,9 @@ extraído do projeto de origem como produto independente.
 | FR-018 | Publicar autoria PathBit, palavras-chave e licença MIT no npm. |
 | FR-019 | Exibir README legível no npm sem alterar o Markdown fonte. |
 | FR-020 | Levar a licença do kit ao hub sem alterar a licença do projeto. |
+| FR-021 | Inventariar documentos existentes antes de propor alterações. |
+| FR-022 | Complementar documentação sem substituir arquivos por templates. |
+| FR-023 | Provar o fluxo documental em projetos reais e em projeto vazio. |
 
 Execuções repetidas devem ser idempotentes; a CLI oferece simulação e JSON.
 As instruções permanecem concisas, com detalhes opcionais em referências.

package/docs/product/roadmap.md

@@ -19,6 +19,8 @@ status: vigente
 | Apresentação e licença v0.0.6 | Distribuição e atualização | [Spec][public]. |
 | 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
@@ -40,3 +42,5 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [public]: ../specs/v0.0.6/SPEC.md
 [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

@@ -13,6 +13,9 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.6](v0.0.6/SPEC.md): apresentação pública, licença e atualização segura.
 - [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.