@pathbit/agentdevkit 0.0.17 → 0.0.19

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

@@ -375,19 +375,36 @@ function ignoreFixture(t) {
   return context;
 }
 
-test('fontes novas permanecem elegíveis e derivados locais ficam fora do índice', t => {
+test('fontes permanecem elegíveis e pastas de clientes aceitam opt-in explícito', t => {
   const { root, file } = ignoreFixture(t);
   const outputs = ['.github/skills/generated/SKILL.md', '.vscode/.gitignore', '.github/.gitignore'];
-  applyLocalIgnore(planLocalIgnore(root, { outputs }));
-  const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs', '.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
+  const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs'];
+  const clients = ['.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
   const generated = [...outputs, '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf', '.pbai4devs/state/agentdevkit.json'];
-  for (const path of [...sources, ...generated]) file(path, 'fixture\n');
+  for (const path of [...sources, ...clients, ...generated.filter(path => !path.endsWith('/.gitignore'))]) file(path, 'fixture\n');
+  file('.github/auth.json', 'credencial local\n');
+  file('.vscode/logs/session.log', 'artefato local\n');
+  assert.equal(git(root, ['add', '--', clients[0], sources[0]]).status, 0);
+  const index = git(root, ['ls-files', '--stage', '-z']).stdout;
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
   assert.deepEqual(ignoredPaths(root, sources), []);
+  assert.deepEqual(new Set(ignoredPaths(root, clients)), new Set(clients));
   assert.deepEqual(new Set(ignoredPaths(root, generated)), new Set(generated));
+  assert.equal(git(root, ['ls-files', '--stage', '-z']).stdout, index);
+  for (const path of clients) assert.equal(readFileSync(join(root, path), 'utf8'), 'fixture\n', path);
+
+  const exceptions = '!/.github/\n!/.vscode/\n';
+  file('.gitignore', exceptions);
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), exceptions);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']).stdout, index);
+  assert.deepEqual(ignoredPaths(root, clients), []);
+  const privateFiles = ['.github/auth.json', '.vscode/logs/session.log'];
+  assert.deepEqual(new Set(ignoredPaths(root, privateFiles)), new Set(privateFiles));
   assert.equal(git(root, ['add', '--all']).status, 0);
   const tracked = git(root, ['ls-files', '-z']).stdout.split('\0');
-  for (const path of sources) assert.ok(tracked.includes(path), path);
-  for (const path of generated) assert.equal(tracked.includes(path), false, path);
+  for (const path of [...sources, ...clients, ...outputs]) assert.ok(tracked.includes(path), path);
+  for (const path of [...generated.filter(path => !outputs.includes(path)), ...privateFiles]) assert.equal(tracked.includes(path), false, path);
 });
 
 test('ignores locais cobrem resultados em qualquer caixa sem bloquear fixtures', t => {

package/.pbai4devs/templates/gitignore/TEMPLATE.md

@@ -7,14 +7,21 @@ description: Exemplo opcional de regras de ignore para o projeto.
 O `.gitignore` da raiz pertence ao projeto; o kit não o cria nem o altera.
 O projeto pode adotar este exemplo e seus próprios padrões se desejar.
 Regras de artefatos locais vêm de [shared.ignore](shared.ignore) e
-[agents.ignore](agents.ignore). As saídas calculadas usam
-[local.ignore](local.ignore) em `.git/info/exclude`; sem Git, essa proteção
-fica pendente até `git init` e sincronização, antes de adicionar arquivos.
+[agents.ignore](agents.ignore). As pastas dos clientes usam
+[local.ignore](local.ignore) em `.git/info/exclude`; o `.gitignore` deste hub
+não alcança pastas irmãs com `../`. As regras locais não são copiadas pelo Git:
+execute `init` ou `sync` em cada clone com Git inicializado, antes de adicionar
+arquivos. Worktrees do mesmo repositório podem compartilhar as exclusões;
+sem Git, essa proteção fica pendente.
 O sincronizador mantém o bloco `BEGIN AGENT IGNORE` / `END AGENT IGNORE`;
-regras próprias ficam fora dele, com exceções depois do bloco. Para permitir
-novos arquivos compartilhados, ajuste as fontes e sincronize. Raízes dedicadas
-dos clientes são locais. Em `.github` e `.vscode`, arquivos próprios continuam
-elegíveis; somente os derivados são excluídos.
+regras próprias ficam fora dele, com exceções depois do bloco. Arquivos já
+rastreados permanecem no índice; o kit não os desindexa automaticamente.
+Pastas dos clientes também podem conter arquivos humanos ainda não rastreados.
+Em especial, `.github` pode conter workflows e formulários do projeto.
+Para permitir o versionamento, acrescente uma exceção literal ao `.gitignore`
+da raiz, como `!/.claude/` ou `!/.github/`. Regras mais profundas continuam
+válidas. Evite exceções amplas como `!/.claude/**`, que podem expor arquivos
+privados e artefatos; `doctor` informa regras conflitantes.
 Ignore binários baixados por local, não por extensão: `.bat`, `.exe` e outros
 arquivos podem ser scripts ou fixtures necessários. Não use regras genéricas
 como `Release/`, `Scripts/` ou `Lib/` que escondam fontes e modelos.

package/.pbai4devs/templates/gitignore/shared.ignore

@@ -1,3 +1,4 @@
+# Pastas irmas: templates/gitignore/local.ignore e .git/info/exclude.
 # Derivados locais
 /catalog.json
 /skills.json

package/CHANGELOG.md

@@ -4,6 +4,17 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.19 — 2026-11-13
+
+- Pastas dos clientes são ignoradas localmente por padrão, com exceções do projeto.
+- O índice Git e os arquivos já rastreados permanecem intactos.
+
+## 0.0.18 — 2026-11-13
+
+- Sincronização preserva recursos próprios, colisões e alterações humanas.
+- Limpeza de recursos obsoletos exige comprovação de propriedade.
+- Comandos e efeitos sobre arquivos, índice e backups documentados.
+
 ## 0.0.17 — 2026-11-13
 
 - A pasta compartilhada de estado passa a se chamar `.pbai4devs/state`.

package/README.en.md

@@ -13,7 +13,7 @@ Organize work with coding agents, from planning to verification. Keep skills,
 rules, commands and agent profiles in `.pbai4devs`; the kit generates the
 references each client can discover. Code lives in `src/`, product tests in
 `tests/`, and shared agent resources in `.pbai4devs/`. Generated client
-folders, entrypoints and preferences stay local and untracked.
+folders are ignored locally by default; projects can opt in to tracking them.
 See the [supported clients][clients].
 
 ## Start in your project

package/README.es.md

@@ -13,8 +13,8 @@ Organiza el trabajo con agentes de código, desde la planificación hasta la
 verificación. Mantén skills, reglas, comandos y perfiles en `.pbai4devs`;
 el kit genera las referencias de cada [cliente compatible][clients].
 El código vive en `src/`, las pruebas del producto en `tests/` y los recursos
-compartidos en `.pbai4devs/`. Las carpetas, entradas y preferencias generadas
-son locales y no se versionan.
+compartidos en `.pbai4devs/`. Las carpetas de clientes se ignoran localmente
+por defecto; cada proyecto puede elegir versionarlas.
 
 ## Empezar en tu proyecto
 

package/docs/guides/cli.md

@@ -22,17 +22,17 @@ atendido; lá os comandos de manutenção usam o pacote por `npx`.
 
 | Comando | Resultado |
 | --- | --- |
-| `init [pasta]` | Instala ou reaplica os recursos. |
-| `update` | Usa os recursos da versão do pacote executado. |
-| `sync` | Reconstrói as derivações da fonte do projeto. |
-| `sync --check` | Confere as derivações sem escrever. |
-| `doctor` | Diagnostica a instalação. |
-| `next` | Orienta a próxima etapa do projeto. |
+| `init [pasta]` | Instala o kit no projeto ou reaplica a instalação. |
+| `update` | Atualiza a fonte usando a versão do pacote executado. |
+| `sync` | Atualiza catálogos e apontamentos a partir da fonte local. |
+| `sync --check` | Confere sincronização sem alterar o projeto. |
+| `doctor` | Diagnostica o kit e indica divergências. |
+| `next` | Mostra a próxima etapa, sem iniciá-la. |
 | `lang [idioma]` | Consulta ou altera o idioma: pt, en ou es. |
-| `agents` | Consulta clientes disponíveis e seleção local. |
-| `agents codex,claude` | Altera a seleção local. |
-| `agents all` | Habilita todos os clientes. |
-| `tools <ação>` | Executa o gerenciador de ferramentas. |
+| `agents` | Mostra os clientes disponíveis e a seleção salva. |
+| `agents codex,claude` | Altera a seleção e os apontamentos necessários. |
+| `agents all` | Seleciona todos os clientes compatíveis. |
+| `tools <ação>` | Consulta, instala, atualiza ou executa ferramentas. |
 | `--help`, `--version` | Ajuda ou versão do pacote. |
 
 Sem comando, a CLI executa `init`, que pode criar arquivos. `language` é alias
@@ -48,16 +48,49 @@ de `lang`; `clients`, de `agents`. O idioma não traduz documentos existentes.
 | `--clients <lista>` | Alias de `--agents`. |
 | `--yes`, `-y` | Evita perguntas iniciais; não força conflitos. |
 | `--dry-run` | Exibe o plano sem aplicar alterações. |
-| `--force` | Substitui conflitos gerenciados, com backup. |
+| `--force` | Solicita reparos gerenciados permitidos, com backup. |
 | `--json` | Produz uma resposta JSON para automação. |
 
 O primeiro uso interativo reúne idioma e clientes. Sem interação, valem as
 opções explícitas, a escolha local salva e, por último, `all`. Confira os
 [IDs e dependências](../../.pbai4devs/COMPATIBILIDADE.md).
 
-`update` não procura automaticamente a próxima versão: execute o pacote
-da versão desejada. `sync` não atualiza a fonte distribuída.
-A seleção e os derivados são locais; o source compartilhado permanece no Git.
+`update` usa a versão executada; para escolher outra, fixe-a no nome do
+pacote. `sync` usa o que já está em `.pbai4devs`: ele não baixa outra versão.
+Ambos conciliam recursos e removem apontamentos obsoletos quando a propriedade
+do kit é comprovada. Recursos e configurações próprios permanecem no projeto.
+Diretórios antigos sem comprovação de propriedade podem permanecer vazios.
+Ao mudar a seleção, pastas compartilhadas continuam quando outro cliente
+precisa delas; arquivos adicionais da equipe devem ser preservados.
+
+Antes de aplicar em projeto existente, confira o plano e depois o diagnóstico:
+
+```console
+npx @pathbit/agentdevkit update --dry-run --json
+npx @pathbit/agentdevkit update
+npx @pathbit/agentdevkit doctor
+npx @pathbit/agentdevkit sync --check
+```
+
+Use `init --dry-run --json`, `sync --dry-run --json` ou
+`agents codex,claude --dry-run --json` para as outras operações. Examine
+`plan`, `conflicts`, `preserved`, `untrackedPaths` e `localIgnore` antes de
+aplicar. Conflitos sem solução interrompem a operação; não presuma que uma
+colisão de nomes torna um arquivo propriedade do kit.
+
+O sincronizador independente também pode ser executado pelo
+[script local](../../.pbai4devs/scripts/sincronizar-agentes/README.md). Seu
+`--check` apenas confere e `--force` é explícito na linha de comando. O
+comando agêntico [sincronizar](../../.pbai4devs/commands/sincronizar/COMMAND.md)
+orienta executar o script com `--force`; ele não é o mesmo que `sync` da CLI.
+
+No Git, o kit preserva o `.gitignore` da raiz e pode atualizar
+`.git/info/exclude` para ocultar por padrão as pastas dos clientes. O projeto
+pode reabri-las no `.gitignore` da raiz, como em `!/.claude/`; consulte as
+[exceções e seus efeitos](installation.md#git-e-migração). Os comandos não
+retiram arquivos já rastreados do índice, e `untrackedPaths` permanece vazio
+por compatibilidade. Backups locais ficam em `.agent-tests/` e não substituem
+o histórico Git.
 
 ## Ferramentas
 
@@ -80,7 +113,7 @@ 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.
+`preserved` lista caminhos mantidos pelo projeto e o motivo.
 Um complemento pode ser gerenciado por bloco sem tornar o arquivo propriedade
 do kit. Conteúdo humano não é substituído por `--force`.
 

package/docs/guides/installation.md

@@ -87,7 +87,7 @@ O próximo passo é [preparar as ferramentas](prerequisites.md#depois-de-instala
 | Conteúdo | Tratamento |
 | --- | --- |
 | `.pbai4devs` com recursos e templates | Fonte compartilhada versionável. |
-| Skills, regras e comandos nos clientes | Apontamentos locais gerados. |
+| Recursos nos clientes | Apontamentos locais; pastas ignoradas por padrão. |
 | Entradas da raiz criadas pelo kit | Arquivos locais gerados. |
 | Índices, manifesto e seleção pessoal | Derivados locais ignorados. |
 | Código, documentos e configurações humanas | Preservados. |
@@ -102,16 +102,35 @@ identifica a licença dos recursos do AgentDevKit, sem redefinir a do projeto.
 
 ## Git e migração
 
-Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore. Para os
-apontamentos externos, o kit gera exclusões locais do Git, sem ignorar
-workflows, formulários de issues ou configurações humanas em `.github`.
-O kit não cria nem altera o `.gitignore` da raiz. Sem Git, a exclusão local
-fica pendente; execute `git init` e `npx @pathbit/agentdevkit sync` antes de
-usar `git add`. No GitHub Packages, use o prefixo de registry da instalação.
+Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore: `../` não
+alcança pastas irmãs. O kit gera regras em `.git/info/exclude` para ignorar
+por padrão as pastas dos clientes, sem alterar o `.gitignore` da raiz.
+Essas regras são locais, não acompanham o clone; execute `init` ou `sync`
+em cada clone com Git inicializado, antes de usar `git add`. Sem Git, a
+exclusão fica pendente até `git init` e sincronização.
+Worktrees do mesmo repositório podem compartilhar esse arquivo de exclusões.
+
+Para versionar uma pasta de cliente, o projeto pode acrescentar uma exceção
+literal ao seu próprio `.gitignore` da raiz, por exemplo:
+
+```gitignore
+!/.claude/
+!/.github/
+```
+
+A exceção da raiz tem precedência sobre `.git/info/exclude`; regras de um
+`.gitignore` mais profundo continuam valendo. Não use `!/.claude/**`: um
+curinga amplo pode reabrir credenciais e artefatos que devem ficar locais.
+O diagnóstico informa exceções que exponham esses arquivos.
+
+O padrão também oculta arquivos humanos ainda não rastreados nas pastas dos
+clientes. Em especial, `.github` pode conter workflows, formulários de issues
+e outras configurações do projeto; use `!/.github/` se precisar versioná-los.
+O mesmo cuidado vale para `.vscode` e configurações próprias de outros agentes.
 
 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 conteúdo do `.gitignore` existente e os arquivos rastreados são preservados.
+O conteúdo do `.gitignore` existente na raiz é preservado.
 Uma exceção que reabra arquivo privado ou artefato é informada como conflito;
 o projeto decide como ajustar suas próprias regras.
 Negativas com curingas também podem ser recusadas preventivamente, mesmo antes
@@ -119,12 +138,10 @@ de existir um arquivo correspondente. Examine a regra indicada no diagnóstico.
 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.
-Artefatos já rastreados são informados por `doctor` e `sync --check` para
-revisão; não são removidos automaticamente do índice.
-Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
-de aplicar. Conteúdo humano não deve ser classificado como saída do gerador.
+Ignorar uma pasta não retira arquivos já rastreados do índice. O kit preserva
+o índice, inclusive alterações preparadas; para mudar o rastreamento, o projeto
+decide a ação Git. `--dry-run` e `sync --check` também não alteram o índice.
+Revise o plano e os conflitos antes de aplicar em um projeto existente.
 
 ## Atualizar e escolher agentes
 
@@ -133,13 +150,20 @@ continua válida; `agents` consulta e `agents codex,claude` altera a seleção.
 `agents all` habilita todos. As pastas compartilhadas permanecem quando
 necessárias para outro cliente, como `.agents` para Codex e Antigravity.
 
-Confira a simulação antes de atualizar um projeto existente. Arquivos
-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.
+Confira `update --dry-run --json` antes de atualizar um projeto existente.
+Revise arquivos criados, atualizados e removidos, conflitos e `preserved`.
+`sync` usa as fontes já instaladas e não baixa uma nova versão. Consulte a
+[referência da CLI](cli.md) para todos os comandos.
+
+Skills e outros recursos próprios podem coexistir com os do kit. Um nome
+igual não comprova propriedade: conteúdo humano e arquivos adicionais não
+devem ser descartados para reconstruir apontamentos. Remoções automáticas
+ficam restritas a arquivos obsoletos cuja propriedade possa ser comprovada.
+`--force` não autoriza substituir conteúdo próprio; backups ficam em
+`.agent-tests/` e devem ser revisados quando houver reparo gerenciado.
 
-Entradas como `AGENTS.md`, `claude.md` e `GEMINI.md`, além de skills, agentes,
-comandos e regras existentes, recebem apenas um complemento do kit:
+Em entradas como `AGENTS.md`, `claude.md` e `GEMINI.md`, e em recursos nativos
+compatíveis, o kit pode acrescentar apenas uma referência delimitada:
 
 ```markdown
 <!-- BEGIN AGENTDEVKIT -->
@@ -148,13 +172,15 @@ Leia e siga [origem](caminho/para/.pbai4devs/recurso.md).
 ```
 
 O texto e o frontmatter humanos permanecem; a referência usa o caminho real
-do recurso. Repetir a operação não duplica o bloco. Edite suas instruções fora
+do recurso. Um arquivo que não possa receber o bloco é preservado e informado,
+sem prometer a adição do apontamento. Repetir a operação não duplica o bloco.
+Edite suas instruções fora
 dele: atualizações alteram somente a contribuição do kit. Nomes de entradas
 com caixa diferente são reaproveitados quando há uma única opção.
 Comandos Gemini mantêm a referência dentro do valor `prompt` em TOML válido.
 Configurações que não são instruções não recebem uma mesclagem arbitrária.
-Arquivos mistos permanecem sob controle do Git do projeto; somente derivados
-integralmente gerados pelo kit recebem exclusão local.
+Arquivos mistos não passam a pertencer ao kit. Sua visibilidade para o Git
+também depende da regra aplicada à pasta do cliente.
 
 Links simbólicos preexistentes são preservados sem atravessá-los. O campo
 `preserved` informa rotas que continuam sob controle do projeto. Um formato

package/docs/guides/troubleshooting.md

@@ -164,8 +164,9 @@ não devem ser versionados. Verifique com `git status` e `git check-ignore -v
 retira automaticamente do Git; revise a remoção do índice sem apagar dados.
 
 O `.gitignore` do hub não controla pastas irmãs. Confira a proteção local
-gerada pelo kit, incluindo `info/exclude` nos repositórios Git. Preserve
-configurações humanas em `.github` e `.vscode` ao migrar arquivos antigos.
+gerada pelo kit em `info/exclude`. Para versionar configurações humanas novas
+em `.github` ou `.vscode`, reabra a pasta com `!/.github/` ou `!/.vscode/`
+no `.gitignore` da raiz. Confira as regras com `git check-ignore -v`.
 
 Para pedir ajuda, inclua SO/arquitetura, versões de Node/npm/AgentDevKit,
 comando executado, código de saída e trecho relevante do JSON, sem segredos.

package/docs/product/design.md

@@ -60,13 +60,13 @@ bloco exigem revisão e não autorizam sobrescrever o arquivo com `--force`.
 Arquivos novos e integralmente gerados continuam com propriedade integral.
 Comandos TOML recebem a referência no valor de `prompt`, preservando as demais
 chaves. Configurações nativas fora desse escopo permanecem sob controle humano.
-Nunca é possível ignorar somente um trecho de arquivo no Git: arquivos mistos
-não entram nas exclusões do kit. Veja a [spec de integração][additive].
+Nunca é possível ignorar somente um trecho de arquivo no Git. Veja a
+[spec de integração][additive].
 
-Saídas identificadas são excluídas localmente do versionamento. O Git local
-usa `info/exclude`; fora de um repositório, a proteção fica no `.gitignore`
-da raiz. A política vem dos templates, não de listas copiadas por cliente.
-Os arquivos humanos de `.github` e `.vscode` continuam versionáveis.
+O Git usa `info/exclude` para ignorar localmente pastas de clientes, inclusive
+seus arquivos humanos ainda não rastreados. Exceções literais no `.gitignore`
+da raiz permitem versioná-las. Arquivos já rastreados e o índice permanecem;
+sem Git, a proteção fica pendente. A política vem dos templates.
 
 O estado registra versão, escolha e propriedade local. Índices e manifesto
 podem ser reconstruídos. Downloads, credenciais e relatórios ficam fora do

package/docs/specs/README.md

@@ -21,9 +21,11 @@ description: Incrementos verificáveis do AgentDevKit.
   especialistas, colaboração e provas.
 - [Confiabilidade da pipeline](ci-resilience/SPEC.md): testes e releases.
 - [Pasta de estado](state-directory/SPEC.md): migração segura para `state`.
+- [Sincronização segura](safe-synchronization/SPEC.md): preservar recursos próprios.
 - [Integração sem substituição][additive]: acréscimos em arquivos existentes.
 - [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
 - [Ignore do projeto](project-ignore/SPEC.md): preservar o arquivo da raiz.
+- [Ignore de clientes](client-ignore/SPEC.md): padrão local e exceções do projeto.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/client-ignore/SPEC.md

@@ -0,0 +1,21 @@
+---
+description: Exclusão local de clientes com escolha explícita do projeto.
+---
+
+# Ignore de clientes
+
+O Git não aplica `../` no `.gitignore` do hub às pastas irmãs. O kit usa
+exclusões locais do Git e o projeto escolhe exceções no seu `.gitignore`.
+
+## Critérios de aceite
+
+- AC-001: Pastas de clientes são ignoradas por padrão em repositórios Git,
+  sem modificar o `.gitignore` da raiz.
+- AC-002: Uma exceção literal da raiz, como `!/.claude/`, permite versionar
+  o cliente e continua válida após instalação, atualização e sincronização.
+- AC-003: Credenciais e artefatos continuam protegidos; exceções inseguras
+  são informadas antes de qualquer mudança.
+- AC-004: Arquivos humanos e o índice Git, incluindo alterações preparadas,
+  são preservados. Arquivos já rastreados continuam rastreados.
+- AC-005: Documentação e testes explicam e verificam precedência, limites,
+  clones, clientes compartilhados, cenários sem Git e sistemas suportados.

package/docs/specs/safe-synchronization/SPEC.md

@@ -0,0 +1,21 @@
+---
+description: Sincronização segura com recursos e alterações próprios do projeto.
+---
+
+# Sincronização segura
+
+Projetos podem ter arquivos próprios e recursos adicionais aos do pacote.
+Os comandos devem preservar esse conteúdo ao instalar, atualizar e sincronizar.
+
+## Critérios de aceite
+
+- AC-001: Recursos humanos ou modificados no hub e nos clientes são
+  preservados, inclusive em colisões e com `--force`.
+- AC-002: A limpeza remove somente saídas obsoletas com propriedade comprovada;
+  pastas e arquivos adicionais da equipe não são removidos.
+- AC-003: Um conteúdo divergente preparado no índice não é descartado pela
+  sincronização; `.gitignore` da raiz e dados humanos são preservados.
+- AC-004: `init`, `update`, `sync`, consultas e opções estão documentados com
+  seus efeitos sobre arquivos, backups, seleção de clientes e Git.
+- AC-005: Testes exercitam instalações existentes, obsolescência, colisões,
+  execução repetida, Git e falhas; a CI contempla Linux, Windows e macOS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",

package/src/i18n.mjs

@@ -42,6 +42,16 @@ const messages = {
 };
 export const text = (language, key) => messages[language || 'pt'][key] || key;
 export function explainError(language, code) {
+  if (code === 'E_STAGED') return {
+    pt: 'Há alterações preparadas diferentes dos arquivos locais; revise-as antes de atualizar.',
+    en: 'Staged changes differ from the working files; review them before updating.',
+    es: 'Hay cambios preparados distintos de los archivos locales; revíselos antes de actualizar.',
+  }[language || 'pt'];
+  if (code === 'E_GIT') return {
+    pt: 'Não foi possível verificar o índice Git com segurança; nenhum arquivo foi alterado.',
+    en: 'The Git index could not be checked safely; no files were changed.',
+    es: 'No se pudo verificar el índice Git de forma segura; no se modificaron archivos.',
+  }[language || 'pt'];
   if (code === 'E_CONFIG_PARSE') return {
     pt: 'Não foi possível analisar a configuração legada com segurança; revise o frontmatter e as aspas antes de executar update.',
     en: 'The legacy configuration could not be safely parsed; review its frontmatter and quoted values before running update.',