@pathbit/agentdevkit 0.0.7 → 0.0.9

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,25 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 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.
+- Conflitos de ignore recusados antes das gravações e rollback revisado.
+- Permissões mantidas em atualização, backup e restauração de arquivos.
+- Caminhos simbólicos de ferramentas bloqueados antes de escrita externa.
+- Argumentos de ferramentas preservados após `--`; ajuda sem projeto válido.
+- Verificação de artefatos com nomes próprios, arquivos e regras aninhadas.
+
 ## 0.0.7 — 2026-11-11
 
 - Artefatos de testes e pastas temporárias protegidos em projetos existentes.

package/README.en.md

@@ -34,7 +34,7 @@ Then open the project in your coding agent and ask:
 
 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.7 release][release] retains artifacts and checksums for verification.
+[v0.0.9 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.
 
@@ -44,6 +44,7 @@ The CLI supports `pt`, `en` and `es`; it saves your selection per project.
 | --- | --- |
 | 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 +79,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.7
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.9
 [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

package/README.es.md

@@ -35,7 +35,7 @@ Después, abre el proyecto en tu agente y pide:
 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.7][release] conserva artefactos y checksums para verificarlos.
+la [release v0.0.9][release] conserva artefactos y checksums para verificarlos.
 No requiere instalación global.
 La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 
@@ -45,6 +45,7 @@ La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 | --- | --- |
 | 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 +81,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.7
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.9
 [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

package/README.md

@@ -32,7 +32,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.7][release],
+versão publicada no [npm público][packages] e na [release v0.0.9][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`.
@@ -43,6 +43,7 @@ O idioma da CLI pode ser `pt`, `en` ou `es`.
 | --- | --- |
 | 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 +90,7 @@ 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.7
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.9
 [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

package/docs/README.md

@@ -24,6 +24,7 @@ pode trocar de agente sem manter várias cópias das mesmas instruções.
 | --- | --- |
 | Primeiro uso | [Instalar][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) |

package/docs/guides/README.md

@@ -7,6 +7,7 @@ description: Guias de instalação, uso e verificação do AgentDevKit.
 - [Instalação](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

@@ -63,11 +63,22 @@ e `unlock`. Consultar ou executar não instala silenciosamente.
 `setup` prepara as ferramentas compatíveis; outros comandos podem receber
 um nome ou grupo. Consulte [ferramentas e testes](tools-and-testing.md).
 
+Em `tools`, use `--` antes dos argumentos que pertencem à ferramenta:
+
+```console
+npx @pathbit/agentdevkit tools run agent-browser -- --json --help
+```
+
+Nesse exemplo, `--json` pertence ao agent-browser. Opções do kit ficam antes
+do separador. `--help` e `--version` do kit não exigem um projeto instalado.
+
 ## JSON e retorno
 
 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 |
 | --- | --- |

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

@@ -64,6 +64,8 @@ O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
 e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
 O `.gitignore` existente e seus arquivos rastreados são preservados;
 uma exceção humana que conflite com essa proteção é informada como conflito.
+Nomes próprios de artefatos e arquivos existentes também são conferidos;
+a validação fica restrita ao projeto e aos ignores de seus ancestrais.
 
 Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
 do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
@@ -82,14 +84,25 @@ 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
+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.7][spec]
+[Wiki](../README.md) · [Spec v0.0.9][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.7/SPEC.md
+[spec]: ../specs/v0.0.9/SPEC.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

@@ -32,6 +32,8 @@ node .pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs setup
 `setup` reutiliza instalações saudáveis e verifica as compatíveis. Um nome
 ou grupo limita a seleção. `check`, `info` e `run` não trocam uma consulta
 por instalação. Downloads, caches e recibos permanecem locais e ignorados.
+O gerenciador recusa links simbólicos nos caminhos que escreve ou usa como
+estado local; a atualização não segue esses links para fora da instalação.
 
 ## Escolher a prova
 

package/docs/guides/troubleshooting.md

@@ -84,15 +84,15 @@ 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
 

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/packages.md

@@ -64,7 +64,7 @@ existir; a primeira publicação pode usar o secret `NPMJS_TOKEN`.
 Para publicar somente o pacote de uma tag que já tem artefato aprovado:
 
 ```console
-gh workflow run release.yml --ref master -f tag=v0.0.7 -F package_only=true
+gh workflow run release.yml --ref master -f tag=v0.0.9 -F package_only=true
 ```
 
 Se o artefato expirou, reexecute o CI original da tag antes da publicação.

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.