@pathbit/agentdevkit 0.0.11 → 0.0.13

package/CHANGELOG.md

@@ -4,6 +4,20 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.13 — 2026-11-12
+
+- Proteção de caches de agentes mesmo com negações genéricas no `.gitignore`.
+- Matriz de compatibilidade ampliada para os sete projetos públicos solicitados.
+- Dois exemplos reproduzíveis com produto, design e três specs testadas.
+
+## 0.0.12 — 2026-11-12
+
+- Entradas e recursos existentes recebem referências em blocos próprios do kit.
+- Texto, metadados e alterações humanas são preservados nas atualizações.
+- Comandos Gemini recebem complementos dentro do prompt TOML.
+- Arquivos mistos não são desindexados nem ignorados como se fossem do kit.
+- Título principal do README: Pathbit AI - AgentDevKit.
+
 ## 0.0.11 — 2026-11-12
 
 - Skills de segurança incluídas nas instalações, com revisão e correção guiadas.

package/README.en.md

@@ -43,7 +43,7 @@ Then open the project in your coding agent and ask:
 
 See [installation](docs/guides/installation.md) for runtime preparation, previews
 and updates. Both [package registries][packages] provide the same version;
-the [v0.0.11 release][release] retains artifacts and checksums for verification.
+the [v0.0.12 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.
 
@@ -90,7 +90,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.11
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.12
 [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

@@ -44,7 +44,7 @@ Después, abre el proyecto en tu agente y pide:
 La [guía de instalación](docs/guides/installation.md) incluye preparación del
 runtime, simulación y actualización. Los dos [registros][packages] ofrecen
 la misma versión;
-la [release v0.0.11][release] conserva artefactos y checksums para verificarlos.
+la [release v0.0.12][release] conserva artefactos y checksums para verificarlos.
 No requiere instalación global.
 La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 
@@ -92,7 +92,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.11
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.12
 [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

@@ -1,4 +1,4 @@
-# AgentDevKit
+# Pathbit AI - AgentDevKit
 
 [English](https://github.com/pathbit/AgentDevKit/blob/master/README.en.md) · [Español](https://github.com/pathbit/AgentDevKit/blob/master/README.es.md) · [Pacote npm][npm-package]
 
@@ -14,6 +14,10 @@ cada cliente conserva seu formato de descoberta. No repositório, o código
 fica em `src/`, os testes em `tests/` e os recursos compartilhados em
 `.pbai4devs/`. Pastas nativas, entradas e preferências são geradas localmente.
 
+Já tem instruções ou skills no projeto? O kit acrescenta suas referências em
+blocos delimitados e preserva o conteúdo humano, inclusive em nomes iguais.
+Veja a [integração em projetos existentes](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md).
+
 ## Começar em um projeto
 
 Prepare [Node.js 24+ e npm](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/prerequisites.md) no Windows, macOS ou
@@ -42,7 +46,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 e GitHub Packages][packages] e na [release v0.0.11][release],
+versão publicada no [npm e GitHub Packages][packages] e na [release v0.0.12][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`.
@@ -102,7 +106,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.11
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.12
 [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/guides/cli.md

@@ -81,7 +81,8 @@ 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`.
+Um complemento pode ser gerenciado por bloco sem tornar o arquivo propriedade
+do kit. Conteúdo humano não é substituído por `--force`.
 
 | Código | Significado |
 | --- | --- |

package/docs/guides/installation.md

@@ -79,7 +79,7 @@ npx @pathbit/agentdevkit sync --check
 
 Se escolheu GitHub Packages, use o mesmo prefixo
 `npx --registry=https://npm.pkg.github.com` nesses comandos. Para fixar a versão,
-use `@pathbit/agentdevkit@0.0.11` no lugar do nome sem versão, em qualquer destino.
+use `@pathbit/agentdevkit@0.0.12` no lugar do nome sem versão, em qualquer destino.
 O próximo passo é [preparar as ferramentas](prerequisites.md#depois-de-instalar-o-kit).
 
 ## O que fica no projeto
@@ -110,8 +110,10 @@ quando o repositório for iniciado.
 
 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.
+O conteúdo do `.gitignore` existente e os arquivos rastreados são preservados.
+Quando há exceções no `.gitignore` da raiz, o kit pode acrescentar um bloco
+limitado ao estado privado dos clientes, sem criar pastas não selecionadas.
+Conflitos detectados nas demais proteções são informados para revisão.
 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.
 
@@ -132,11 +134,28 @@ 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.
 
-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.
+Entradas como `AGENTS.md`, `claude.md` e `GEMINI.md`, além de skills, agentes,
+comandos e regras existentes, recebem apenas um complemento do kit:
+
+```markdown
+<!-- BEGIN AGENTDEVKIT -->
+Leia e siga [origem](caminho/para/.pbai4devs/recurso.md).
+<!-- END AGENTDEVKIT -->
+```
+
+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
+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.
+
+Links simbólicos preexistentes são preservados sem atravessá-los. O campo
+`preserved` informa rotas que continuam sob controle do projeto. Um formato
+não suportado ou um bloco alterado é informado; `--force` não permite apagar
+instruções humanas para reconstruir um apontamento.
 
 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

package/docs/guides/troubleshooting.md

@@ -36,6 +36,7 @@ agente; arquivos próprios também podem manter uma pasta após a desmarcação.
 | `E_TARGET`, `E_SYMLINK` | Use a pasta real, fora dos diretórios reservados. |
 | `E_CONFLICT` ou lista `conflicts` | Revise o plano e os arquivos afetados. |
 | `E_STATE`, `E_BLOCK`, `E_TEMPLATE` | Restaure o arquivo; não invente hashes. |
+| `E_MANAGED_BLOCK` | Revise marcadores ou formato; preserve suas instruções. |
 | `E_CHANGED` | Um arquivo mudou durante a operação; gere outro plano. |
 
 ## Conflitos e backups
@@ -81,12 +82,14 @@ local coerente com os arquivos correspondentes. O estado pessoal não é
 versionado. Não invente hashes nem apague o estado para ocultar conflitos;
 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.
+Entradas humanas recebem um bloco delimitado do kit. Edite fora dos marcadores
+`BEGIN AGENTDEVKIT` e `END AGENTDEVKIT`; não altere hashes do estado. Um bloco
+modificado precisa de revisão, mesmo com `--force`. Se o recurso for retirado,
+somente seu bloco comprovado é removido, preservando o texto humano.
 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.
+atravessá-los. Consulte `preserved` no JSON para ver as rotas mantidas sob
+controle do projeto, inclusive quando complementadas. 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.
 

package/docs/maintainers/maintenance.md

@@ -28,6 +28,10 @@ O CI tem quatro perfis:
 | macOS / Node 24 | Portabilidade da CLI, arquivos e runtime. |
 | Linux / Node 26 | Smoke de compatibilidade. |
 
+O perfil macOS usa o runner padrão `macos-15-intel`. O label `macos-latest`
+usa ARM64 e pode ter filas diferentes; confira os [runners disponíveis][runners]
+antes de mudar a arquitetura. Provas locais devem informar a arquitetura usada.
+
 A distribuição real é testada uma vez no perfil completo. Os outros perfis
 validam seus riscos específicos. Execuções antigas da mesma referência podem
 ser canceladas quando substituídas, sem cancelar uma publicação em andamento.
@@ -113,3 +117,4 @@ aprovado; uma aprovação de CI não substitui a instalação real pelo registro
 [release]: https://github.com/pathbit/AgentDevKit/actions/workflows/release.yml
 [package]: https://www.npmjs.com/package/@pathbit/agentdevkit
 [security-ci]: https://github.com/pathbit/AgentDevKit/actions/workflows/security-tools.yml
+[runners]: https://docs.github.com/en/actions/reference/runners/github-hosted-runners

package/docs/maintainers/packages.md

@@ -42,7 +42,7 @@ npx --registry=https://npm.pkg.github.com @pathbit/agentdevkit init
 ```
 
 Para repetir uma instalação, fixe a versão após o nome, como
-`@pathbit/agentdevkit@0.0.11`, nos dois destinos.
+`@pathbit/agentdevkit@0.0.12`, nos dois destinos.
 
 Acrescente `--agents codex,claude` para selecionar clientes, `--dry-run` para
 simular ou use `update`, `doctor` e `sync --check` no lugar de `init`.
@@ -89,7 +89,7 @@ Por padrão, uma tag publica nos dois destinos. Para completar o GitHub
 Packages de uma tag existente, preservando a release e o npm:
 
 ```console
-gh workflow run Release -f tag=v0.0.11 -F package_only=true -f registry=github
+gh workflow run Release -f tag=v0.0.12 -F package_only=true -f registry=github
 ```
 
 Se o artefato expirou, reexecute o CI original da tag antes da publicação.

package/docs/product/design.md

@@ -53,9 +53,15 @@ antigos sem escolha explícita mantêm esse comportamento.
 O instalador monta um plano, confere hashes e caminhos, apresenta conflitos e
 aplica mudanças com backup local. `--dry-run` não altera arquivos nem índice.
 
-Entradas humanas permanecem intactas. O kit cria suas próprias entradas quando
-faltam; na migração, separa seus blocos de texto humano. Nunca é possível
-ignorar somente um trecho de arquivo no Git.
+Entradas humanas recebem referências em um bloco delimitado do kit. O texto
+externo, frontmatter e nome existente são preservados; somente o hash do bloco
+é registrado. Alterações externas continuam permitidas; alterações dentro do
+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].
 
 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`
@@ -114,3 +120,4 @@ referência não comprova a execução da skill.
 [Recursos](../guides/resources.md)
 
 [clients]: ../../.pbai4devs/templates/clients/ADAPTERS.json
+[additive]: ../specs/additive-integration/SPEC.md

package/docs/product/prd.md

@@ -1,7 +1,7 @@
 ---
 description: Requisitos da distribuição portátil AgentDevKit.
 status: aprovado
-version: 0.0.11
+version: 0.0.12
 ---
 
 # PRD do AgentDevKit
@@ -46,6 +46,7 @@ extraído do projeto de origem como produto independente.
 | FR-024 | Incluir procedimentos de segurança nas instalações do kit. |
 | FR-025 | Compor entregas com agentes, skills, comandos, scripts e regras. |
 | FR-026 | Auditar localmente com ferramentas OSS e relatórios sem segredos. |
+| FR-027 | Complementar instruções existentes sem substituir conteúdo humano. |
 
 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

@@ -22,6 +22,7 @@ status: vigente
 | Coexistência v0.0.9 | Agentes, documentos e projetos reais | [Spec][coexistence]. |
 | Instalação nos dois registries v0.0.10 | Pacote e guias de pré-requisitos | [Spec][dual-install]. |
 | Segurança local v0.0.11 | Ferramentas e papéis especializados | [Spec][security]. |
+| Integração v0.0.12 | Preservação e propriedade por bloco | [Spec][additive]. |
 
 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
@@ -46,3 +47,4 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [coexistence]: ../specs/v0.0.9/SPEC.md
 [dual-install]: ../specs/v0.0.10/SPEC.md
 [security]: ../specs/security-ecosystem/SPEC.md
+[additive]: ../specs/additive-integration/SPEC.md

package/docs/specs/README.md

@@ -17,6 +17,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [Dois registries](dual-registry/SPEC.md): versão e bytes iguais no npm e GitHub.
 - [v0.0.10](v0.0.10/SPEC.md): release com instalação pelos dois registries e pré-requisitos.
 - [Ecossistema de segurança](security-ecosystem/SPEC.md): fluxos e scanners locais.
+- [Integração sem substituição][additive]: acréscimos em arquivos existentes.
+- [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 
@@ -25,3 +27,6 @@ projeto, siga o [fluxo](../guides/workflow.md) e use os
 [modelos compartilhados](../../.pbai4devs/templates/README.md).
 
 [Wiki](../README.md) · [Roadmap](../product/roadmap.md)
+
+[additive]: additive-integration/SPEC.md
+[oss]: real-projects/SPEC.md

package/docs/specs/additive-integration/README.md

@@ -0,0 +1,9 @@
+---
+description: Acréscimos seguros em instruções e pastas existentes.
+---
+
+# Integração sem substituição
+
+A [spec](SPEC.md) define blocos gerenciados, preservação humana e suas provas.
+
+[Specs](../README.md) · [Instalação](../../guides/installation.md)

package/docs/specs/additive-integration/SPEC.md

@@ -0,0 +1,53 @@
+---
+description: Complementar instruções existentes sem substituir conteúdo humano.
+status: aprovado
+version: 0.0.12
+---
+
+# Integração sem substituição
+
+## Objetivo
+
+Ao instalar, atualizar ou sincronizar, acrescentar referências do AgentDevKit
+aos arquivos de instruções existentes. Preservar conteúdo, metadados, nomes,
+permissões e índice Git do usuário, inclusive em colisões de nomes.
+
+## Contrato
+
+- Entradas raiz existentes recebem um bloco curto; aliases únicos como
+  `agents.md` são reutilizados sem criar uma segunda entrada.
+- Skills, agentes, regras e comandos Markdown existentes recebem só uma
+  referência ao hub. O frontmatter humano não é substituído.
+- Comandos Gemini existentes recebem a referência dentro de `prompt`, em
+  TOML válido. Sintaxe não suportada é preservada e informada.
+- O estado registra a propriedade do bloco, nunca do arquivo humano inteiro.
+- Atualizações preservam edições humanas fora do bloco. Marcadores ambíguos
+  ou blocos adulterados impedem substituição, inclusive com `--force`.
+- Remover um recurso gerenciado remove somente sua contribuição comprovada.
+- Arquivos humanos continuam sujeitos às escolhas de Git do próprio projeto;
+  o kit ignora seus derivados por arquivo, não a pasta inteira do cliente.
+- Links simbólicos não são seguidos. Configurações externas ao escopo de
+  instruções não são reformatadas nem mescladas arbitrariamente.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Entradas raiz humanas recebem a referência e preservam seus bytes. |
+| AC-002 | Colisões Markdown preservam frontmatter e texto, com bloco único. |
+| AC-003 | Repetições são idempotentes; edições fora do bloco são preservadas. |
+| AC-004 | Blocos alterados, ambiguidades e links não causam perda de dados. |
+| AC-005 | Retirada de bloco preserva texto, permissões e índice humano. |
+| AC-006 | TOML mantém semântica humana e referência válida no prompt. |
+| AC-007 | Git não passa a ignorar arquivos humanos por propriedade parcial. |
+| AC-008 | Pacote real, regressões, maturidade e revisão independente passam. |
+
+## Validação
+
+Fixtures existentes incluem frontmatter próprio, caixa diferente, BOM, CRLF,
+ausência de newline final, alterações posteriores, arquivos já staged e
+comandos estruturados. Testar perda de origem, rollback, `--force`, simulação,
+`doctor`, `sync --check` e instalação do pacote gerado.
+
+Testes são versionados. Backups, snapshots e relatórios ficam ignorados em
+`.agent-tests/` ou `tmp/`; não alterar projetos consumidores nesta entrega.

package/docs/specs/real-projects/SPEC.md

@@ -0,0 +1,26 @@
+---
+description: Compatibilidade com repositórios públicos e exemplos incrementais.
+status: aprovado
+version: 0.0.13
+---
+
+# Projetos reais e exemplos incrementais
+
+Validar a instalação e manutenção do pacote em commits fixos de projetos reais,
+preservando suas configurações e seu índice Git. Demonstrar o fluxo de produto,
+design e três specs em dois projetos novos, com resultados locais ignorados.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Testar os sete repositórios, com commits registrados. |
+| AC-002 | Testar init repetido, update, sync e preservação nos clones. |
+| AC-003 | Proteger caches ante exceções Git, preservando texto e índice. |
+| AC-004 | Produto e design antes das três specs de cada projeto novo. |
+| AC-005 | Documentar reprodução, limites e saídas ignoradas. |
+| AC-006 | Testes de regressão, pacote e revisão independente passam. |
+
+Os testes de compatibilidade não executam nem compilam as aplicações externas.
+Aprovações de produto e revisão nos exemplos são simuladas. Código de teste é
+versionado; clones, projetos gerados e evidências permanecem fora do Git.

package/package.json

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