@pathbit/agentdevkit 0.0.8 → 0.0.9

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.8 -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.

package/docs/product/prd.md

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

package/docs/product/roadmap.md

@@ -19,6 +19,7 @@ status: vigente
 | Apresentação e licença v0.0.6 | Distribuição e atualização | [Spec][public]. |
 | Compatibilidade real v0.0.7 | Testes em clones existentes | [Spec][oss]. |
 | Preservação v0.0.8 | Auditoria e regressões | [Spec][robustness]. |
+| Coexistência v0.0.9 | Agentes, documentos e projetos reais | [Spec][coexistence]. |
 
 A primeira entrega segue a [spec v0.0.1](../specs/v0.0.1/SPEC.md), disponível
 na [release v0.0.1][release]. Os detalhes de mudanças estão no
@@ -40,3 +41,4 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [public]: ../specs/v0.0.6/SPEC.md
 [oss]: ../specs/v0.0.7/SPEC.md
 [robustness]: ../specs/v0.0.8/SPEC.md
+[coexistence]: ../specs/v0.0.9/SPEC.md

package/docs/specs/README.md

@@ -13,6 +13,7 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.6](v0.0.6/SPEC.md): apresentação pública, licença e atualização segura.
 - [v0.0.7](v0.0.7/SPEC.md): projetos reais e proteção local de artefatos.
 - [v0.0.8](v0.0.8/SPEC.md): preservação, transações e validação aprofundada.
+- [v0.0.9](v0.0.9/SPEC.md): coexistência e evolução documental sem perdas.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

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

@@ -0,0 +1,9 @@
+---
+description: Preservação de agentes e evolução da documentação existente.
+---
+
+# Versão 0.0.9
+
+[Spec](SPEC.md): preservar agentes e complementar documentos existentes.
+
+[Specs](../README.md) · [Changelog](../../../CHANGELOG.md)

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

@@ -0,0 +1,68 @@
+---
+description: Coexistência com agentes e evolução da documentação existente.
+status: aprovado
+version: 0.0.9
+---
+
+# Preservar agentes e documentação existentes
+
+## Objetivo
+
+Instalar e atualizar o AgentDevKit no Zod e em projetos com agentes próprios,
+preservando configurações, arquivos, permissões, links e estado do Git.
+Orientar também a evolução documental a partir do inventário e da leitura
+dos materiais existentes, sem reiniciar o projeto. O pedido atual substitui
+o bloqueio conservador documentado na
+[versão anterior](../v0.0.8/SPEC.md).
+
+## Contrato
+
+- Tratar links simbólicos humanos nas entradas e nos clientes como caminhos
+  preservados: não abrir, atravessar, converter, sobrescrever ou adotar.
+- Preservar agentes e skills humanos, inclusive nomes iguais aos do kit e
+  durante execução com `--force`. Informar os caminhos preservados.
+- Gerar os apontamentos disponíveis sem atribuir ao kit arquivos preservados.
+  No Zod, manter `.codex/skills` e usar também `.agents/skills` para o Codex.
+- Manter a validação estrita em fontes, estado, ferramentas, Git e caminhos
+  antes pertencentes ao kit. Um link não pode esconder alteração gerenciada.
+- Manter os mesmos contratos na CLI e no sincronizador instalado.
+- Antes de editar documentos, inventariar e ler os existentes. Reaproveitar
+  caminhos, seções e decisões; templates orientam somente lacunas.
+- Organizar por índices e links, sem apagar, mover ou substituir documentos.
+  Em projetos novos, não inventar produto ou aprovação sem respostas.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Links humanos internos, externos e quebrados permanecem intactos. |
+| AC-002 | Skills, agentes e configurações preexistentes são preservados. |
+| AC-003 | Caminhos gerenciados recusam links sem escrita externa. |
+| AC-004 | Init, update, doctor e sync são coerentes e idempotentes. |
+| AC-005 | Zod, Express e Chi passam na matriz do pacote, preservando Git. |
+| AC-006 | Regressões, documentação, CI e pacote público são verificados. |
+| AC-007 | Inventário detecta documentação real sem alterar arquivos. |
+| AC-008 | Skills exigem leitura e plano aditivo antes dos templates. |
+| AC-009 | Exercícios documentais preservam conteúdo e arquivos fora do plano. |
+| AC-010 | Projeto vazio recebe o kit sem documentos de produto inventados. |
+
+## Validação
+
+Executar testes de regressão para links e colisões, inclusive `--force`,
+substituição de caminhos após o plano e mudança de seleção dos clientes.
+Rodar pipeline completo, maturidade e matriz OSS com o TGZ candidato;
+repetir a matriz com o pacote publicado. Comparar bytes, tipos, modos,
+destinos de links, staging e configuração Git nos clones.
+Execute também o inventário instalado e o fluxo de documentação em clones
+reais: plano por arquivo, complemento baseado em fatos, índice novo e revisão.
+Separe essa prova da simples instalação e de fixtures do harness; não atribua
+ao pacote geração automática de conteúdo ou aprovações de produto.
+
+Clones e evidências ficam ignorados em `tmp/` e `.agent-tests/`.
+O escopo é o kit e seu fluxo documental; não afirmar execução das aplicações
+clonadas.
+
+## Documentação afetada
+
+Atualizar instalação, CLI, recuperação, recursos, sincronização, testes,
+changelog e índices. Preservar as specs antigas como histórico.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",
@@ -51,7 +51,8 @@
     "ci:full": "node scripts/release/pipeline.mjs full",
     "ci:portable": "node scripts/release/pipeline.mjs portable",
     "ci:smoke": "node scripts/release/pipeline.mjs smoke",
-    "test:oss": "node tests/oss-compatibility.mjs"
+    "test:oss": "node tests/oss-compatibility.mjs",
+    "test:docs": "node tests/documentation-compatibility.mjs"
   },
   "author": {
     "name": "PathBit",

package/src/cli.mjs

@@ -62,6 +62,7 @@ function print(result, options, output) {
   if (result.clients) output.write(`${text(result.language, 'clientsCurrent')}: ${result.clients.join(', ')}\n`);
   if (result.availableClients) output.write(`${text(result.language, 'clientsAvailable')}: ${result.availableClients.map(client => client.id).join(', ')}\n`);
   if (result.toolOutput) output.write(`${result.toolOutput.trimEnd()}\n`);
+  if (result.preserved?.length) output.write(`${text(result.language, 'preserved')}: ${result.preserved.length}. ${text(result.language, 'preservedDetails')}\n`);
   if (result.plan?.length) {
     const names = { pt: { create: 'criar', update: 'atualizar', remove: 'remover' }, en: { create: 'create', update: 'update', remove: 'remove' }, es: { create: 'crear', update: 'actualizar', remove: 'eliminar' } };
     const labels = {
@@ -123,6 +124,7 @@ export async function main(argv = process.argv.slice(2), context = {}) {
       const found = inspect(target);
       if (found.installed && !found.issues.length) {
         const plan = planInstallation({ target, language, mode: 'sync' });
+        result.preserved = plan.preserved;
         found.issues.push(...plan.changes.map(change => ({ code: 'outdated', path: change.path })));
         found.issues.push(...plan.localIgnoreCheck.missing.map(path => ({ code: 'unignored', path })));
         if (plan.localIgnore.edits.length || plan.untrack?.paths.length) found.issues.push({ code: 'local-ignore', path: '.gitignore / Git info/exclude' });
@@ -144,6 +146,7 @@ export async function main(argv = process.argv.slice(2), context = {}) {
         result.next = getNextSteps({ command: options.command, language, target, installed: Boolean(previous) });
       }
       const plan = planInstallation({ target, language, mode: options.command, force: options.force, clients: options.clients });
+      result.preserved = plan.preserved;
       result.plan = plan.changes.map(({ path, action }) => ({ path, action, conflict: plan.conflicts.includes(path) }));
       result.untrackedPaths = [...(plan.untrack?.paths || [])];
       result.localIgnore = { status: plan.localIgnore.status, edits: plan.localIgnore.edits.map(({ path, before }) => ({ path, action: before === null ? 'create' : 'update' })), missing: plan.localIgnoreCheck.missing };

package/src/i18n.mjs

@@ -7,6 +7,7 @@ export function normalizeLanguage(value) {
 
 const messages = {
   pt: {
+    preserved: 'Caminhos existentes preservados', preservedDetails: 'Use --json para consultar os caminhos e motivos.',
     help: 'AgentDevKit: init [diretório], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <ação>.\nOpções: --target <diretório>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAliases: --clients e clients.',
     clientsCurrent: 'Agentes selecionados', clientsAvailable: 'Agentes disponíveis', clientsSelect: 'Agentes (IDs separados por vírgula ou all) [all]: ', agents: 'Seleção de agentes atualizada.',
     next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano; --force salva backup antes de substituir.',
@@ -15,6 +16,7 @@ const messages = {
     agentLanguage: 'Responda em português, salvo quando o usuário solicitar outro idioma.', inspect: 'Verifique a instalação', workflow: 'Consulte a próxima etapa', install: 'Inicialize este projeto', repair: 'Confira a sincronização', review: 'Revise os arquivos em conflito', tools: 'Resultado da ferramenta',
   },
   en: {
+    preserved: 'Existing paths preserved', preservedDetails: 'Use --json to inspect paths and reasons.',
     help: 'AgentDevKit: init [directory], update, doctor, sync [--check], lang [pt|en|es], agents [list], next, tools <action>.\nOptions: --target <directory>, --lang <language>, --agents <list>, --yes, --dry-run, --force, --json.\nAliases: --clients and clients.',
     clientsCurrent: 'Selected agents', clientsAvailable: 'Available agents', clientsSelect: 'Agents (comma-separated IDs or all) [all]: ', agents: 'Agent selection updated.',
     next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review it; --force backs them up before replacement.',
@@ -23,6 +25,7 @@ const messages = {
     agentLanguage: 'Respond in English unless the user requests another language.', inspect: 'Check the installation', workflow: 'Review the next stage', install: 'Initialize this project', repair: 'Check synchronization', review: 'Review conflicting files', tools: 'Tool result',
   },
   es: {
+    preserved: 'Rutas existentes preservadas', preservedDetails: 'Use --json para consultar las rutas y los motivos.',
     help: 'AgentDevKit: init [directorio], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <acción>.\nOpciones: --target <directorio>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAlias: --clients y clients.',
     clientsCurrent: 'Agentes seleccionados', clientsAvailable: 'Agentes disponibles', clientsSelect: 'Agentes (IDs separados por coma o all) [all]: ', agents: 'Selección de agentes actualizada.',
     next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise el plan; --force guarda una copia antes de reemplazarlos.',

package/src/install.mjs

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
 import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, planUntrack, applyUntrack, restoreUntrack } from '../.pbai4devs/scripts/lib/gitignore.mjs';
+import { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
 import { writeAdapterManifest, adapterRoots, normalizeClients, resolveAdapters } from './adapters/index.mjs';
 import { packageRoot, packageInfo, statePath, entryNames, begin, end } from './config.mjs';
 import { normalizeLanguage, text } from './i18n.mjs';
@@ -173,6 +174,24 @@ function copyResources(source, destination) {
   return files;
 }
 
+function readDerivedState(target) {
+  let entries = {}, outputs = {};
+  const derived = read(target, '.pbai4devs/estado/derived.json');
+  if (derived) {
+    try {
+      const value = JSON.parse(derived);
+      if (value.schemaVersion !== 1 || !value.entries || typeof value.entries !== 'object' || Array.isArray(value.entries)
+        || value.outputs !== undefined && (!value.outputs || typeof value.outputs !== 'object' || Array.isArray(value.outputs))) fail('E_STATE', 'Invalid derived entrypoint state.');
+      entries = value.entries; outputs = value.outputs ?? {};
+      for (const [path, digest] of Object.entries(entries)) if (!entryNames.includes(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived entrypoint state.');
+      for (const [path, digest] of Object.entries(outputs)) if (!allowedManaged(path) || !/^\.[^/]+\/(?:skills|agents|rules)\.json$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived output state.');
+    }
+    catch { fail('E_STATE', 'Invalid derived entrypoint state.'); }
+    for (const path of [...Object.keys(entries), ...Object.keys(outputs)]) safePath(target, path);
+  }
+  return { entries, outputs };
+}
+
 export function planInstallation({ target, language = 'pt', mode = 'init', force = false, clients }) {
   const previous = loadState(target);
   if (mode !== 'init' && !previous) fail('E_MISSING', text(language, 'missing'));
@@ -180,16 +199,37 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
   const active = resolveAdapters(selected);
   const changingClients = clients !== undefined || mode === 'agents';
   const protectedEntries = new Set(), entryConflicts = [], ownedEntrypoints = new Set();
+  const { entries: derivedEntries, outputs: derivedOutputs } = readDerivedState(target);
+  const ownedPaths = [...Object.keys(previous?.files || {}), ...Object.keys(previous?.blocks || {}), ...Object.keys(derivedEntries), ...Object.keys(derivedOutputs)];
+  const preserved = new Map();
+  const recordPreserved = (path, reason) => { preserved.set(path, { path, reason }); return true; };
+  const native = path => entryNames.includes(path) || path === 'README.md' || adapterRoots.some(root => path === root || path.startsWith(`${root}/`));
+  const boundary = path => {
+    if (!native(path)) return false;
+    const found = nativePathBoundary(target, path, ownedPaths, { preserveRootAliases: path === 'README.md' || entryNames.includes(path) });
+    return found ? recordPreserved(found.path, found.reason) : false;
+  };
+  const owned = path => ownedPaths.includes(path);
+  const generatedReference = content => Boolean(content && isReference(content.toString('utf8'))
+    && (content.toString('utf8').split(/\r?\n/).includes('<!-- gerado: sincronizar-agentes -->') || content.toString('utf8').startsWith('# gerado: sincronizar-agentes\n')));
+  const preserveNative = path => {
+    if (!native(path)) return false;
+    if (boundary(path)) return true;
+    const item = stat(safePath(target, path));
+    if (!item || owned(path)) return false;
+    if (!item.isFile() && ownedPaths.some(value => value.startsWith(`${path}/`))) fail('E_PATH', `Managed subtree occupies a file destination: ${path}`);
+    if (item.isFile()) {
+      const current = read(target, path);
+      if (generatedReference(current)) return false;
+      if (path.endsWith('/.gitignore') && current.toString('utf8').split(/\r?\n/).some(line => ['# BEGIN AGENT IGNORE', '# END AGENT IGNORE'].includes(line))) return false;
+    }
+    return recordPreserved(path, item.isFile() ? 'existing-file' : 'existing-directory');
+  };
   for (const name of entryNames) {
+    if (preserveNative(name)) continue;
     const current = read(target, name);
     if (current && previous?.files[name] && previous.files[name] !== hash(current)) { protectedEntries.add(name); entryConflicts.push(name); }
   }
-  let derivedEntries = {};
-  const derived = read(target, '.pbai4devs/estado/derived.json');
-  if (derived) {
-    try { const value = JSON.parse(derived); if (value.schemaVersion === 1 && value.entries && typeof value.entries === 'object') derivedEntries = value.entries; }
-    catch { fail('E_STATE', 'Invalid derived entrypoint state.'); }
-  }
   const stage = realpathSync(mkdtempSync(join(tmpdir(), 'agentdevkit-')));
   try {
     const existing = copyResources(join(target, '.pbai4devs'), join(stage, '.pbai4devs'));
@@ -206,6 +246,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (path.startsWith('.pbai4devs/') && !supplied.has(path.slice(11)) && !internal.has(path.slice(11))) rmSync(safePath(stage, path), { force: true });
     }
     for (const root of active.roots) {
+      if (preserveNative(`${root}/.gitignore`)) continue;
       const content = read(target, `${root}/.gitignore`);
       if (content) write(stage, `${root}/.gitignore`, content);
     }
@@ -214,7 +255,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     writeAdapterManifest(stage, { clients: selected });
     const synchronized = synchronize({ root: stage, force: true, localIgnores: false, generateEntrypoints: false, output() {} });
     for (const name of active.entrypoints) {
-      if (protectedEntries.has(name)) continue;
+      if (protectedEntries.has(name) || preserveNative(name)) continue;
       const current = read(target, name), template = readFileSync(join(packageRoot, '.pbai4devs/templates/entrypoints', name), 'utf8');
       const legacy = entryContent(null, template, language, name);
       const content = legacy.replace(`${begin}\n`, '').replace(`\n${end}`, '');
@@ -222,11 +263,18 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       const knownLegacy = current && previous?.blocks[name] && current.toString('utf8') === entryContent(null, template, previous.language, name);
       if (!current || knownFile || knownLegacy) { write(stage, name, content); ownedEntrypoints.add(name); }
     }
-    if (!read(target, 'README.md')) write(stage, 'README.md', `---\ndescription: ${JSON.stringify(text(language, 'readme'))}\nlanguage: ${language}\n---\n\n# ${text(language, 'project')}\n\n${text(language, 'readme')}\n`);
+    if (!preserveNative('README.md') && !read(target, 'README.md')) write(stage, 'README.md', `---\ndescription: ${JSON.stringify(text(language, 'readme'))}\nlanguage: ${language}\n---\n\n# ${text(language, 'project')}\n\n${text(language, 'readme')}\n`);
     if (!existsSync(join(stage, '.pbai4devs/estado/README.md'))) write(stage, '.pbai4devs/estado/README.md', `---\ndescription: AgentDevKit state.\n---\n\n# AgentDevKit\n\n${text(language, 'state')}\n`);
     const unknown = new Set(existing.filter(path => !supplied.has(path) && !previous?.files[`.pbai4devs/${path}`] && !internal.has(path)));
     const paths = walk(stage, '', path => !path.split('/').includes('.agent-tests')).filter(path => !path.startsWith('.pbai4devs/') || !unknown.has(path.slice(11)));
-    const desired = new Map(paths.map(path => [path, readFileSync(join(stage, path))]));
+    const desired = new Map(paths.filter(path => !preserveNative(path)).map(path => [path, readFileSync(join(stage, path))]));
+    // Native discovery manifests must not advertise resources omitted at a human boundary.
+    const overlapsPreserved = path => [...preserved.keys()].some(kept => path === kept || path.startsWith(`${kept}/`) || kept.startsWith(`${path}/`));
+    for (const [path, content] of desired) if (/^\.agents\/(skills|rules|agents)\.json$/.test(path)) {
+      const discovery = JSON.parse(content);
+      discovery.entries = discovery.entries.filter(entry => !overlapsPreserved(entry.path));
+      desired.set(path, Buffer.from(`${JSON.stringify(discovery, null, 2)}\n`));
+    }
     const manifest = { schemaVersion: 1, version: bundled.length ? packageInfo.version : previous.version, language, files: {}, blocks: {} };
     if (mode !== 'sync' || clients !== undefined || previous?.clients !== undefined) manifest.clients = selected;
     for (const [path, content] of desired) {
@@ -240,7 +288,8 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     for (const [path, content] of desired) {
       const current = read(target, path);
       if (current?.equals(content)) continue;
-      const managed = previous?.blocks[path] ? blockDigest(path, current || Buffer.alloc(0)) === previous.blocks[path] : previous?.files[path] ? hash(current || '') === previous.files[path] : false;
+      const managed = previous?.blocks[path] ? blockDigest(path, current || Buffer.alloc(0)) === previous.blocks[path]
+        : [previous?.files[path], derivedOutputs[path], derivedEntries[path]].some(digest => digest && hash(current || '') === digest);
       const appendBlock = entryNames.includes(path) || path === '.gitignore' || path.endsWith('/.gitignore');
       const conflict = current && path !== statePath && !managed && !appendBlock;
       const changedBlock = current && previous?.blocks[path] && !managed;
@@ -270,11 +319,29 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       }
       changes.push({ path, action: content.trim() ? 'update' : 'remove', content: content.trim() ? Buffer.from(content) : null, beforeHash: hash(current) });
     }
-    for (const root of changingClients ? [] : active.roots) for (const path of walk(join(target, root), '', path => !path.split('/').some(part => ignored.has(part)))) {
+    function nativeFiles(root) {
+      if (boundary(root)) return [];
+      const directory = stat(safePath(target, root));
+      if (!directory?.isDirectory()) return [];
+      const files = [];
+      const visit = folder => {
+        for (const name of readdirSync(safePath(target, folder)).sort()) {
+          const path = `${folder}/${name}`;
+          if (boundary(path)) continue;
+          const info = stat(safePath(target, path));
+          if (path.split('/').some(part => ignored.has(part))) continue;
+          if (info?.isDirectory()) visit(path);
+          else if (info?.isFile()) files.push(path);
+        }
+      };
+      visit(root); return files;
+    }
+    for (const root of changingClients ? [] : active.roots) for (const full of nativeFiles(root)) {
+      const path = full.slice(root.length + 1);
       if (!['skills', 'agents', 'commands', 'rules', 'instructions', 'prompts'].includes(path.split('/')[0])) continue;
-      const full = `${root}/${path}`; if (desired.has(full) || changes.some(change => change.path === full)) continue;
+      if (desired.has(full) || changes.some(change => change.path === full)) continue;
       const current = read(target, full), source = current.toString('utf8');
-      if (!(source.includes('<!-- gerado: sincronizar-agentes -->') || source.startsWith('# gerado: sincronizar-agentes\n'))) continue;
+      if (!(source.includes('<!-- gerado: sincronizar-agentes -->') || source.startsWith('# gerado: sincronizar-agentes\n'))) { recordPreserved(full, 'existing-file'); continue; }
       if (!isReference(source)) conflicts.push(full);
       changes.push({ path: full, action: 'remove', content: null, beforeHash: hash(current) });
     }
@@ -285,7 +352,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       changes.push({ path: legacy, action: 'remove', content: null, beforeHash: hash(legacyContent) });
     }
     const retiredRoots = adapterRoots.filter(root => !active.roots.includes(root) && changes.some(change => change.action === 'remove' && change.path.startsWith(`${root}/`) && (previous?.files[change.path] || previous?.blocks[change.path])));
-    const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])];
+    const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])].filter(path => !overlapsPreserved(path));
     const hashes = {};
     for (const [path, digest] of Object.entries(previous?.files || {})) if ((ownedOutputs.includes(path) || !path.startsWith('.pbai4devs/')) && !protectedEntries.has(path)) hashes[path] = digest;
     for (const path of ownedEntrypoints) { const current = read(target, path); if (current && (previous?.blocks[path] || derivedEntries[path] === hash(current))) hashes[path] = hash(current); }
@@ -298,7 +365,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const localIgnore = planLocalIgnore(target, { outputs: ownedOutputs, templateRoot: stage });
     const localIgnoreCheck = checkLocalIgnore(localIgnore, { replacedBlocks: replacedIgnoreBlocks(target, changes, previous) });
     conflicts.push(...(untrack?.conflicts || []), ...localIgnoreCheck.missing);
-    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck };
+    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
   } finally { rmSync(stage, { recursive: true, force: true }); }
 }
 
@@ -399,10 +466,11 @@ function pruneRemovedDirectories(plan, onRemoved) {
 export function inspect(target) {
   const state = loadState(target);
   if (!state) return { installed: false, issues: [{ code: 'missing', path: statePath }] };
+  const derived = readDerivedState(target);
   const issues = [];
   for (const [path, digest] of Object.entries(state.files)) {
     const content = read(target, path);
-    if (!content || hash(content) !== digest) issues.push({ code: content ? 'modified' : 'missing', path });
+    if (!content || hash(content) !== digest && hash(content) !== derived.outputs[path]) issues.push({ code: content ? 'modified' : 'missing', path });
   }
   for (const [path, digest] of Object.entries(state.blocks)) {
     const content = read(target, path);