@pathbit/agentdevkit 0.0.8 → 0.0.9

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,16 @@ 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.

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.8 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.8
+[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.8][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.8
+[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.8][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.8
+[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

@@ -77,6 +77,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 |
 | --- | --- |

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

@@ -84,9 +84,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 +102,7 @@ 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.9][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.8/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