@pathbit/agentdevkit 0.0.8 → 0.0.10

package/.pbai4devs/scripts/verificar-recursos/SCRIPT.mjs

@@ -20,6 +20,39 @@ function checkedStat(root, location) {
   return item;
 }
 
+function checkedPath(root, path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /[\\\x00-\x1f\x7f:]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) fail(`Caminho gerenciado invalido: ${path}`);
+  let location = root;
+  for (const part of path.split('/')) { location = join(location, part); checkedStat(root, location); }
+  return location;
+}
+
+function ownership(root) {
+  const file = checkedPath(root, '.pbai4devs/estado/agentdevkit.json');
+  if (!checkedStat(root, file)) return null;
+  const readState = location => {
+    try { return JSON.parse(readFileSync(location, 'utf8')); }
+    catch { fail(`Estado invalido: ${normalize(relative(root, location))}`); }
+  };
+  const state = readState(file);
+  const validMap = value => value && typeof value === 'object' && !Array.isArray(value)
+    && Object.values(value).every(hash => typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash));
+  if (state?.schemaVersion !== 1 || !validMap(state.files) || !validMap(state.blocks)) fail('Estado de propriedade invalido.');
+  const files = { ...state.files };
+  const derivedFile = checkedPath(root, '.pbai4devs/estado/derived.json');
+  if (checkedStat(root, derivedFile)) {
+    const derived = readState(derivedFile);
+    if (derived?.schemaVersion !== 1 || !validMap(derived.entries) || Object.keys(derived.entries).some(path => !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(path))
+      || !validMap(derived.outputs ?? {}) || Object.keys(derived.outputs ?? {}).some(path => !/^\.[a-z0-9][a-z0-9-]*\/(?:skills|rules|agents)\.json$/.test(path))) fail('Estado de entradas derivadas invalido.');
+    Object.assign(files, derived.entries, derived.outputs);
+  }
+  for (const path of [...Object.keys(files), ...Object.keys(state.blocks)]) {
+    const location = checkedPath(root, path);
+    if (!checkedStat(root, location)?.isFile()) fail(`Arquivo gerenciado ausente: ${path}`);
+  }
+  return { files, blocks: state.blocks };
+}
+
 export function registryRoots(root) {
   checkedStat(root, join(root, '.pbai4devs'));
   const file = join(root, '.pbai4devs/espelhos.conf');
@@ -44,7 +77,7 @@ function walk(root, location, files, { skipTools = true } = {}) {
   } else if (item.isFile() && ['.md', '.mdc'].includes(extname(location).toLowerCase())) files.add(location);
 }
 
-export function collectMarkdown(root, registry = registryRoots(root)) {
+export function collectMarkdown(root, registry = registryRoots(root), { installed = ownership(root) } = {}) {
   const agents = join(root, '.pbai4devs');
   checkedStat(root, agents);
   for (const directory of readdirSync(agents, { withFileTypes: true })) {
@@ -54,10 +87,18 @@ export function collectMarkdown(root, registry = registryRoots(root)) {
     if (item?.isDirectory() && !checkedStat(root, join(location, 'README.md'))?.isFile()) fail(`README ausente: .pbai4devs/${directory.name}/`);
   }
   const files = new Set();
-  const rootMarkdown = readdirSync(root).filter(name => ['.md', '.mdc'].includes(extname(name).toLowerCase()));
-  const sources = ['.pbai4devs', 'docs', 'src', 'bin', 'tests', 'scripts', 'examples',
-    '.github/PULL_REQUEST_TEMPLATE.md', '.github/ISSUE_TEMPLATE', ...rootMarkdown];
-  for (const name of [...sources, ...registry.paths]) walk(root, resolve(root, name), files);
+  if (installed) {
+    walk(root, agents, files);
+    for (const path of Object.keys(installed.files)) {
+      const file = checkedPath(root, path);
+      if (['.md', '.mdc'].includes(extname(path).toLowerCase())) files.add(file);
+    }
+  } else {
+    const rootMarkdown = readdirSync(root).filter(name => ['.md', '.mdc'].includes(extname(name).toLowerCase()));
+    const sources = ['.pbai4devs', 'docs', 'src', 'bin', 'tests', 'scripts', 'examples',
+      '.github/PULL_REQUEST_TEMPLATE.md', '.github/ISSUE_TEMPLATE', ...rootMarkdown];
+    for (const name of [...sources, ...registry.paths]) walk(root, resolve(root, name), files);
+  }
   const tools = join(agents, 'tools');
   if (checkedStat(root, tools)) {
     const guide = join(tools, 'README.md');
@@ -154,8 +195,14 @@ export function checkCatalog(root, build = buildCatalog) {
   return result.catalog;
 }
 
-export function checkAgentExtras(root, agents) {
+export function checkAgentExtras(root, agents, { installed = null } = {}) {
   for (const agent of agents) {
+    if (installed) {
+      const files = Object.keys(installed.files).filter(path => path.startsWith(`${agent}/`));
+      if (files.some(path => auxiliary.some(name => path === `${agent}/${name}` || path.startsWith(`${agent}/${name}/`)))) fail(`Auxiliar gerenciado indevido em ${agent}`);
+      if (files.some(path => ['README.md', 'INSTRUCTIONS.md'].includes(basename(path)))) fail(`Guia gerenciado indevido em ${agent}`);
+      continue;
+    }
     for (const name of auxiliary) if (existsSync(join(root, agent, name))) fail(`Auxiliar indevido em ${agent}/${name}`);
     const files = new Set();
     walk(root, join(root, agent), files);
@@ -183,14 +230,15 @@ export function checkLint(root, files, run = spawnSync) {
 
 export function verifyResources({ root = projectRoot, sourceOnly = false, synchronize = checkSynchronization, lint = checkLint, catalogCheck = checkCatalog } = {}) {
   requireNode();
+  const installed = sourceOnly ? null : ownership(root);
   const built = sourceOnly ? buildCatalog(root) : null;
   if (!sourceOnly) { synchronize(root); catalogCheck(root); }
   const registry = sourceOnly ? { agents: [], paths: [] } : registryRoots(root);
-  const files = collectMarkdown(root, registry);
+  const files = collectMarkdown(root, registry, { installed });
   const virtualPaths = new Set(sourceOnly ? [...built.outputs.keys(), '.pbai4devs/espelhos.conf'] : []);
   checkMarkdown(root, files, { virtualPaths });
   checkResourceReferences(root, files);
-  checkAgentExtras(root, registry.agents);
+  checkAgentExtras(root, registry.agents, { installed });
   return { files, messages: [...lint(root, files), 'recursos=passed'] };
 }
 

package/.pbai4devs/scripts/verificar-recursos/tests/TEST.mjs

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join, relative } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import test from 'node:test';
@@ -40,6 +41,16 @@ function resourceFixture(t) {
 }
 const verify = root => verifyResources({ root, synchronize() {}, catalogCheck() {}, lint: () => ['lint=fixture'] });
 
+function installedFixture(t) {
+  const context = resourceFixture(t);
+  context.file('.pbai4devs/estado/README.md');
+  const generated = '.agents/skills/managed/SKILL.md';
+  context.file(generated, document('# Gerado\n'));
+  const files = { [generated]: createHash('sha256').update(readFileSync(join(context.root, generated))).digest('hex') };
+  context.file('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, version: '0.0.9', language: 'pt', files, blocks: {} }));
+  return { ...context, generated };
+}
+
 function writeCatalog(root) {
   for (const [path, content] of buildCatalog(root).outputs) { mkdirSync(join(root, path, '..'), { recursive: true }); writeFileSync(join(root, path), content); }
 }
@@ -96,6 +107,86 @@ test('coleta source-only ignora exemplos gerados e clientes, sem exigir Git', t
   for (const path of result.files) assert.doesNotMatch(relative(root, path), /examples[\\/]generated|node_modules|TEST-RESULTS|\.github[\\/]skills|\.codex/);
 });
 
+test('instalação valida somente fontes e Markdown próprio, preservando conteúdo humano', t => {
+  const { root, file, generated } = installedFixture(t);
+  const own = ['README.md', 'AGENTS.md', 'docs/product.md', 'src/README.md', '.codex/README.md', '.codex/templates/custom.md', '.codex/skills/human/SKILL.md'];
+  for (const path of own) file(path, '# Texto humano sem frontmatter\n\n[Link próprio](missing-human-file.md)\n');
+  let linted;
+  const result = verifyResources({ root, synchronize() {}, catalogCheck() {}, lint(_root, files) { linted = files; return ['lint=fixture']; } });
+  assert.ok(result.files.includes(join(root, generated)));
+  assert.ok(result.files.includes(join(root, '.pbai4devs/skills/exemplo/SKILL.md')));
+  for (const path of own) assert.equal(result.files.includes(join(root, path)), false, path);
+  assert.deepEqual(linted, result.files);
+  file('.pbai4devs/skills/exemplo/SKILL.md', '# Fonte do kit inválida\n');
+  assert.throws(() => verify(root), /Frontmatter\/H1 invalido: .pbai4devs\/skills\/exemplo\/SKILL.md/);
+});
+
+test('instalação não atravessa links humanos de entradas e skills', t => {
+  const { root, file } = installedFixture(t);
+  file('AGENTS.md', '# Instrução humana sem frontmatter\n');
+  file('own-docs/README.md', '# README humano\n');
+  file('own-skills/human/SKILL.md', '# Skill humana\n');
+  rmSync(join(root, '.codex/skills'), { recursive: true });
+  const links = [['CLAUDE.md', 'AGENTS.md', 'file'], ['README.md', 'own-docs/README.md', 'file'], ['.codex/skills', '../own-skills', 'dir']];
+  for (const [path, target, type] of links) {
+    try { symlinkSync(type === 'dir' && process.platform === 'win32' ? join(root, 'own-skills') : target, join(root, path), process.platform === 'win32' && type === 'dir' ? 'junction' : type); }
+    catch (error) {
+      if (process.platform === 'win32' && ['EPERM', 'EACCES'].includes(error.code)) { t.skip('Sem permissão para criar links no Windows.'); return; }
+      throw error;
+    }
+  }
+  const before = links.map(([path]) => readlinkSync(join(root, path)));
+  const result = verify(root);
+  for (const [path] of links) {
+    assert.equal(lstatSync(join(root, path)).isSymbolicLink(), true);
+    assert.equal(result.files.includes(join(root, path)), false);
+  }
+  assert.deepEqual(links.map(([path]) => readlinkSync(join(root, path))), before);
+});
+
+test('instalação recusa caminho gerenciado substituído por link', t => {
+  const { root, file, generated } = installedFixture(t);
+  const target = file('external.md', '# Conteúdo externo\n');
+  rmSync(join(root, generated));
+  try { symlinkSync(target, join(root, generated), 'file'); }
+  catch (error) {
+    if (process.platform === 'win32' && ['EPERM', 'EACCES'].includes(error.code)) { t.skip('Sem permissão para criar links no Windows.'); return; }
+    throw error;
+  }
+  assert.throws(() => verify(root), /Link simbolico: .agents\/skills\/managed\/SKILL.md/);
+  assert.equal(readFileSync(target, 'utf8'), '# Conteúdo externo\n');
+});
+
+test('instalação confere entradas derivadas sem aplicar lint a blocos humanos', t => {
+  const { root, file } = installedFixture(t);
+  const contents = document('# Entrada gerada\n');
+  file('GEMINI.md', contents);
+  file('.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: { 'GEMINI.md': createHash('sha256').update(contents).digest('hex') } }));
+  file('AGENTS.md', '# Instruções humanas sem frontmatter\n\n<!-- BEGIN AGENTDEVKIT -->\nLeia as fontes.\n<!-- END AGENTDEVKIT -->\n');
+  const statePath = join(root, '.pbai4devs/estado/agentdevkit.json');
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  state.blocks['AGENTS.md'] = createHash('sha256').update('bloco registrado').digest('hex');
+  state.files['.pbai4devs/skills/exemplo/SKILL.md'] = createHash('sha256').update('fonte anterior').digest('hex');
+  writeFileSync(statePath, JSON.stringify(state));
+  const result = verify(root);
+  assert.ok(result.files.includes(join(root, 'GEMINI.md')));
+  assert.equal(result.files.includes(join(root, 'AGENTS.md')), false);
+  assert.ok(result.files.includes(join(root, '.pbai4devs/skills/exemplo/SKILL.md')));
+  file('GEMINI.md', document('# Fonte sincronizada com hash de instalação anterior\n'));
+  assert.ok(verify(root).files.includes(join(root, 'GEMINI.md')));
+});
+
+test('instalação também protege manifestos registrados em derived.outputs', t => {
+  const { root, file } = installedFixture(t);
+  const manifest = '.agents/skills.json';
+  const contents = '{"entries":[]}\n';
+  file(manifest, contents);
+  file('.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: {}, outputs: { [manifest]: createHash('sha256').update(contents).digest('hex') } }));
+  assert.ok(!verify(root).files.includes(join(root, manifest)));
+  rmSync(join(root, manifest));
+  assert.throws(() => verify(root), /Arquivo gerenciado ausente: .agents\/skills.json/);
+});
+
 test('catalogo derivado cobre recursos e detecta JSON editado sem reescrever', t => {
   const { root, file } = resourceFixture(t);
   file('.pbai4devs/commands/inspecionar/COMMAND.md', document('# Inspecionar\n\n[Script](../../scripts/inspecionar/SCRIPT.mjs).\n'));

package/.pbai4devs/skills/produto/criar-design-doc/SKILL.md

@@ -6,6 +6,8 @@ description: Define e revisa o design técnico do produto com o usuário.
 # Criar design técnico
 
 Siga `.pbai4devs/rules/qualidade/RULE.md` ao criar arquivos Markdown.
+Antes de escrever, use `atualizar-documentacao` para ler e reaproveitar documentos
+existentes; aplique o template somente às lacunas.
 
 Consulte `.pbai4devs/estado/configuracao/ESTADO.md` e confira o PRD aprovado
 e UX/UI aprovado ou não aplicável com justificativa,

package/.pbai4devs/skills/produto/criar-prd/SKILL.md

@@ -6,6 +6,8 @@ description: Define e revisa o documento de requisitos do produto com o usuário
 # Criar PRD
 
 Siga `.pbai4devs/rules/qualidade/RULE.md` ao criar arquivos Markdown.
+Antes de escrever, use `atualizar-documentacao` para ler e reaproveitar documentos
+existentes; aplique o template somente às lacunas.
 
 Confira a preparação em `.pbai4devs/estado/configuracao/ESTADO.md`. Se não estiver
 concluída e comprovada, encaminhe a `configurar-projeto` para a fase

package/.pbai4devs/skills/produto/criar-ux-ui/SKILL.md

@@ -6,6 +6,8 @@ description: Define ou justifica a não aplicação de UX e interface com o usu
 # Criar UX/UI
 
 Siga `.pbai4devs/rules/qualidade/RULE.md` ao criar arquivos Markdown.
+Antes de escrever, use `atualizar-documentacao` para ler e reaproveitar documentos
+existentes; aplique o template somente às lacunas.
 
 Consulte `.pbai4devs/estado/configuracao/ESTADO.md` e confira o PRD
 com `status: aprovado` e a

package/.pbai4devs/skills/projeto/atualizar-documentacao/SKILL.md

@@ -5,9 +5,21 @@ description: Atualiza documentos afetados e sua coerência com a entrega.
 
 # Atualizar documentação
 
-Leia o diff, os critérios e o comportamento comprovado. Reúna no início as
-dúvidas que mudam contratos; use o [catálogo](../../../templates/README.md) para
-escolher modelos da fase atual, sem criar documentos de produto antecipados.
+Antes de escrever, execute `inspecionar-projeto` por `executar-script` e consulte
+`documentation`. Abra os documentos relevantes: o inventário não substitui a
+leitura nem comprova aprovação. Confira também o diff e os critérios da tarefa.
+Reúna no início somente dúvidas que os arquivos não respondem.
+
+Proponha por caminho: manter, complementar uma seção ou criar arquivo ausente.
+Reutilize nomes, formatos, decisões, links e estrutura existentes; um documento
+como `ARCHITECTURE.md` pode cumprir o papel de design sem ser renomeado.
+Organize primeiro por índices e links. Não apague, mova ou substitua arquivos
+para padronizá-los. Acrescente apenas fatos comprovados e preserve o conteúdo
+anterior; trate contradições com o usuário antes de editar.
+
+Use o [catálogo](../../../templates/README.md) como lista de lacunas, nunca como
+substituto de um documento existente. Crie somente o que a fase e o pedido
+exigem; ausência de respostas não autoriza inventar PRD, design ou aprovação.
 
 Confira README da raiz/pastas, AGENTS/CLAUDE/GEMINI, contribuição, notas de versão,
 produto/design/specs, ADRs, configuração/exemplos e comentários/docstrings
@@ -17,7 +29,9 @@ Segurança pública depende de suporte e canal confirmado, sem dados fictícios.
 
 Registre por caminho a decisão `updated`, `no-impact` ou `not-applicable`, com
 justificativa, no relatório da entrega ou no resultado da tarefa. Verifique
-links e exemplos; código de teste é versionado, evidências ficam ignoradas.
+links e exemplos; compare o conteúdo anterior e confirme que arquivos fora
+do plano permanecem intactos. Repetir a tarefa não deve duplicar seções.
+Código de teste é versionado, evidências ficam ignoradas.
 
 Acione o [revisor](../../../agents/revisor/AGENT.md) em leitura com o diff,
 documentos, critérios e provas. Aplique os achados pertinentes e peça nova

package/.pbai4devs/skills/projeto/configurar-projeto/SKILL.md

@@ -17,6 +17,8 @@ as ferramentas e rode o diagnóstico. Isso não escolhe a stack da aplicação.
 
 ## Preparar o projeto
 
+Antes de criar estado ou documentos, faça o inventário de `atualizar-documentacao`.
+Mapeie os documentos já existentes aos seus papéis, sem reiniciar o produto.
 Reúna dúvidas no início e aproveite decisões existentes. Quando o projeto
 começar, crie ou retome `.pbai4devs/estado/configuracao/ESTADO.md` pelo modelo.
 Combine os arquivos `prd`, `ux_ui`, `design`, `roadmap` e diretórios `releases`,

package/.pbai4devs/skills/projeto/criar-recurso/SKILL.md

@@ -7,6 +7,7 @@ description: Encaminha criações e cria documentos, modelos ou novos recursos.
 
 Se o pedido for um modelo, trabalhe em `.pbai4devs/templates/` sem iniciar a
 definição do produto. Encaminhe documentos reais à skill correspondente.
+Para documentos, comece pelo inventário e plano de `atualizar-documentacao`.
 
 Confira se o recurso já existe e use a skill específica quando disponível:
 `criar-skill`, `criar-agente`, `criar-comando`, `criar-regra`, `criar-prd`,

package/.pbai4devs/skills/projeto/sincronizar-agentes/SKILL.md

@@ -21,8 +21,9 @@ com as fontes, detectando inclusões, alterações, remoções e links inválido
 Os `.gitignore` de `.pbai4devs` e dos clientes também são gerados dos
 [modelos](../../../templates/gitignore/TEMPLATE.md). Preserve regras próprias
 fora do bloco gerenciado; `--check` identifica blocos ausentes ou divergentes.
-`--force` repara os destinos gerenciados, sobrescreve conflitos e limpa extras
-nesses destinos, com backup local do conteúdo próprio em `.agent-tests/`.
+`--force` repara conflitos gerenciados com backup local em `.agent-tests/`.
+Preserve recursos nativos humanos, inclusive colisões de nomes; links humanos
+são opacos e nunca devem ser atravessados. Confira `preserved` no JSON da CLI.
 Não apague raízes inteiras: workflows, configurações nativas e a origem ficam
 fora da limpeza. `--check` só confere, sem corrigir nem criar backups.
 

package/.pbai4devs/skills/specs/criar-spec/SKILL.md

@@ -5,6 +5,7 @@ description: Cria uma spec de incremento, esclarecendo requisitos e dúvidas com
 
 # Criar spec
 
+Antes de escrever, aplique o inventário e plano de `atualizar-documentacao`.
 Leia os caminhos em `.pbai4devs/estado/configuracao/ESTADO.md`. Exija PRD/design
 aprovados e UX/UI aprovado ou não aplicável com justificativa aprovada.
 Confira evidências, atualidade e decisões essenciais ao incremento; se faltar

package/.pbai4devs/skills/specs/gerenciar-roadmap/SKILL.md

@@ -10,7 +10,8 @@ mostre preparação, releases, specs e tarefas com dependências e bloqueios.
 Use `[ ]`, `[-]` e `[x]` conforme evidências; informe estados desconhecidos.
 Sem roadmap, diga que ainda não foi criado. Não conclua entregas sem prova.
 
-Ao planejar ou atualizar, use o modelo de roadmap no caminho acordado. Registre
+Antes de alterar documentos, aplique o inventário de `atualizar-documentacao`.
+Ao planejar ou atualizar, use o modelo só para lacunas no caminho acordado. Registre
 objetivos, prioridades, etapas, dependências e pendências de PRD, UX/UI e design.
 Mantenha referências e estados coerentes ao aprovar ou revisar documentos;
 não invente escopo, datas ou releases. Identifique as specs do primeiro entregável

package/.pbai4devs/templates/README.md

@@ -30,7 +30,10 @@ enquanto o usuário estiver preparando somente a estrutura dos agentes.
 | [SECURITY][security] | Suporte público | Política/suporte mudar. |
 | [Comando][comando] | Recurso agêntico | Entrada ou fluxo mudar. |
 
-Copie só artefatos aplicáveis, remova instruções/placeholders e confirme fatos.
+Antes, inventarie e leia os documentos existentes com `atualizar-documentacao`.
+Use os modelos como lista de lacunas. Copie somente artefatos aplicáveis ainda
+ausentes; nunca substitua documentos existentes. Remova placeholders e confirme
+fatos nos novos arquivos; preserve nomes, formatos, seções e decisões anteriores.
 README acompanha o projeto desde a preparação; documentos de produto surgem
 após descoberta. Segurança depende de suporte e canal realmente definidos.
 

package/.pbai4devs/templates/configuracao/TEMPLATE.md

@@ -24,6 +24,12 @@ documentos:
 
 # Configuração do projeto
 
+## Documentos existentes
+
+- Inventário e leitura inicial: a registrar antes de criar documentos.
+- Caminhos e papéis reaproveitados: a definir; não impor novos nomes.
+- Lacunas e complementos acordados: a definir, preservando o conteúdo anterior.
+
 ## Preparação
 
 - Evidências e pendências: a definir.

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.
+- Colisões com recursos nativos próprios não são sobrescritas pelo kit.
+- Sincronização mantém recursos humanos, inclusive com `--force`.
+- Caminhos preservados são informados sem registrar propriedade indevida.
+- Matriz OSS verifica agentes preexistentes e sincronização independente.
+- Inventário e fluxo documental exigem leitura e complementos sem substituição.
+- Exercícios documentais cobrem projetos reais e um projeto vazio.
+
 ## 0.0.8 — 2026-11-11
 
 - Preservação de arquivos humanos que parecem apontamentos gerados.

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.8 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,8 +51,10 @@ 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) |
 | Create a skill or command | [Resources](docs/guides/resources.md) |
 | Install tools and verify work | [Tools and tests][tests] |
 | Look up options or fix an error | [CLI][cli] · [Troubleshooting][help] |
@@ -78,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.8
+[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
@@ -87,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.8][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,8 +52,10 @@ 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) |
 | Crear una skill o comando | [Recursos](docs/guides/resources.md) |
 | Instalar herramientas y verificar | [Herramientas y pruebas][tests] |
 | Consultar opciones o resolver un error | [CLI][cli] · [Soluciones][help] |
@@ -80,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.8
+[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
@@ -89,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.8][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,8 +51,10 @@ 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) |
 | Criar uma skill ou comando | [Recursos](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/resources.md) |
 | Instalar ferramentas e comprovar uma entrega | [Ferramentas e testes][tests] |
 | Consultar opções ou resolver um erro | [CLI][cli] · [Soluções][help] |
@@ -89,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.8
+[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,15 +22,17 @@ 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] |
 | Executar ou verificar algo | [CLI](guides/cli.md) → [ferramentas e testes][tests] |
 | Corrigir uma dificuldade | [Soluções e recuperação](guides/troubleshooting.md) |
 | 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,9 +4,11 @@ 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)
 - [Recursos dos agentes](resources.md)
 - [Ferramentas e testes](tools-and-testing.md)
 - [Solução de problemas](troubleshooting.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
@@ -77,6 +80,8 @@ do separador. `--help` e `--version` do kit não exigem um projeto instalado.
 As respostas incluem `ok`, `command`, `version`, `language`, `target` e
 `next`. Conforme a operação, há seleção, plano, conflitos, backup e erros.
 Leia os campos estruturados, não dependa da tradução da mensagem.
+`preserved` lista caminhos nativos humanos mantidos pelo projeto, com o motivo.
+Eles não integram os arquivos gerenciados e não são substituídos por `--force`.
 
 | Código | Significado |
 | --- | --- |