@pathbit/agentdevkit 0.0.10 → 0.0.12

package/.pbai4devs/tools/opengrep/TOOL.json

@@ -0,0 +1,71 @@
+{
+  "name": "opengrep",
+  "description": "Analisa codigo com regras SAST locais.",
+  "group": "security",
+  "source": "https://github.com/opengrep/opengrep/releases/tag/v1.33.1",
+  "license": "LGPL-2.1",
+  "licenseSource": "https://github.com/opengrep/opengrep/blob/v1.33.1/LICENSE",
+  "download": {
+    "provider": "github-release",
+    "repository": "opengrep/opengrep",
+    "channel": "reviewed",
+    "version": "1.33.1",
+    "tag": "v1.33.1",
+    "assets": {
+      "darwin-arm64": {
+        "file": "opengrep_osx_arm64",
+        "format": "raw",
+        "binary": "opengrep_osx_arm64",
+        "sha256": "a17c1881bb40e3214266a7a291cf4f2ae3bc56c1715628b5712d2ec816bc3e2d"
+      },
+      "darwin-x64": {
+        "file": "opengrep_osx_x86",
+        "format": "raw",
+        "binary": "opengrep_osx_x86",
+        "sha256": "c3bd18e0d898d44e28419d95dad57c8928bb46ab32889a0ee1f72a87ad9627af"
+      },
+      "linux-arm64": {
+        "file": "opengrep_manylinux_aarch64",
+        "format": "raw",
+        "binary": "opengrep_manylinux_aarch64",
+        "sha256": "d1433f63a90b8bc0b6ad4b498a13b372b856ce9a754a43484ba4920fe2d76dcf"
+      },
+      "linux-x64": {
+        "file": "opengrep_manylinux_x86",
+        "format": "raw",
+        "binary": "opengrep_manylinux_x86",
+        "sha256": "46e8133cc490f9f50518061590ce2f6be5a08afaeda034471c0ceda4b3899808"
+      },
+      "win32-x64": {
+        "file": "opengrep_windows_x86.exe",
+        "format": "raw",
+        "binary": "opengrep_windows_x86.exe",
+        "sha256": "132e606e071bdd3928286fddc893198a6106a90820d46e21197e0ace1a23e0c1"
+      }
+    }
+  },
+  "platforms": [
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-arm64",
+    "linux-x64",
+    "win32-x64"
+  ],
+  "scripts": {
+    "entry": "SCRIPT.mjs"
+  },
+  "probe": [
+    "--disable-version-check",
+    "--version"
+  ],
+  "env": {
+    "SEMGREP_ENABLE_VERSION_CHECK": "0",
+    "SEMGREP_SEND_METRICS": "off",
+    "SEMGREP_RULES": "",
+    "OPENGREP_ENABLE_VERSION_CHECK": "0"
+  },
+  "envPaths": {
+    "XDG_CONFIG_HOME": "config",
+    "XDG_CACHE_HOME": "cache"
+  }
+}

package/.pbai4devs/tools/osv-scanner/README.md

@@ -0,0 +1,23 @@
+---
+description: Instalacao local revisada do osv-scanner.
+---
+
+# osv-scanner
+
+Compara dependencias com bases de vulnerabilidades baixadas previamente.
+
+Versao revisada: **2.7.1**. Licenca: [Apache-2.0](https://github.com/google/osv-scanner/blob/v2.7.1/LICENSE).
+Downloads vem da [release oficial](https://github.com/google/osv-scanner/releases/tag/v2.7.1);
+cada plataforma tem SHA-256 fixado em `TOOL.json`.
+
+`SCRIPT.mjs install` baixa e verifica o executavel. `update` aplica a versao
+revisada do catalogo; nao seleciona `latest` sem revisao. `check` verifica
+integridade e versao sem rede; `run` preserva argumentos e codigo de saida.
+Use `node .pbai4devs/tools/osv-scanner/SCRIPT.mjs <acao>`.
+
+Use `--offline` para impedir consultas durante a varredura. A atualizacao das
+bases e uma operacao separada; ausencia de base nao significa ausencia de
+vulnerabilidades.
+
+Binarios, caches e resultados ficam locais e ignorados. O CLI nao exige
+conta nem pagamento. Consulte o [gerenciador](../../scripts/preparar-ferramentas/README.md).

package/.pbai4devs/tools/osv-scanner/SCRIPT.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../../scripts/preparar-ferramentas/SCRIPT.mjs';
+
+try { process.exitCode = await main(['--tool', "osv-scanner", ...process.argv.slice(2)]); }
+catch (error) { console.error(error.message); process.exitCode = 1; }

package/.pbai4devs/tools/osv-scanner/TOOL.json

@@ -0,0 +1,70 @@
+{
+  "name": "osv-scanner",
+  "description": "Analisa dependencias com bases locais de vulnerabilidades.",
+  "group": "security",
+  "source": "https://github.com/google/osv-scanner/releases/tag/v2.7.1",
+  "license": "Apache-2.0",
+  "licenseSource": "https://github.com/google/osv-scanner/blob/v2.7.1/LICENSE",
+  "download": {
+    "provider": "github-release",
+    "repository": "google/osv-scanner",
+    "channel": "reviewed",
+    "version": "2.7.1",
+    "tag": "v2.7.1",
+    "assets": {
+      "darwin-arm64": {
+        "file": "osv-scanner_darwin_arm64",
+        "format": "raw",
+        "binary": "osv-scanner_darwin_arm64",
+        "sha256": "b22c02877a811c8f78956e8643efa554932b7378f590d13f8e97d4e9448a29f3"
+      },
+      "darwin-x64": {
+        "file": "osv-scanner_darwin_amd64",
+        "format": "raw",
+        "binary": "osv-scanner_darwin_amd64",
+        "sha256": "b8420d5485ba792626315f1bf9a5a2046e971d38eea75bf9090c38852dbc3b1b"
+      },
+      "linux-arm64": {
+        "file": "osv-scanner_linux_arm64",
+        "format": "raw",
+        "binary": "osv-scanner_linux_arm64",
+        "sha256": "983d22fbad9724514e3fcc6acc83b5fa64c5ffa6b0d9f510028f22c1b223ff81"
+      },
+      "linux-x64": {
+        "file": "osv-scanner_linux_amd64",
+        "format": "raw",
+        "binary": "osv-scanner_linux_amd64",
+        "sha256": "fb7dab19a8bd9bbe5c3189f09d4b7ee1820c9553a23bac202648a56efd2f6ee8"
+      },
+      "win32-arm64": {
+        "file": "osv-scanner_windows_arm64.exe",
+        "format": "raw",
+        "binary": "osv-scanner_windows_arm64.exe",
+        "sha256": "5f3998b55c9268f8468502bbcb60645038fd5b145ee5e685e6ae2a32e923afc7"
+      },
+      "win32-x64": {
+        "file": "osv-scanner_windows_amd64.exe",
+        "format": "raw",
+        "binary": "osv-scanner_windows_amd64.exe",
+        "sha256": "7121dcf420aefbbf89a7f0050c4d3094e079ff93afd334dfc96f16b02ec85800"
+      }
+    }
+  },
+  "platforms": [
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-arm64",
+    "linux-x64",
+    "win32-arm64",
+    "win32-x64"
+  ],
+  "scripts": {
+    "entry": "SCRIPT.mjs"
+  },
+  "probe": [
+    "--version"
+  ],
+  "envPaths": {
+    "OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY": "data/osv"
+  }
+}

package/CHANGELOG.md

@@ -4,6 +4,23 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 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.
+- Agentes, comandos e regras conectados em fluxos de entrega e auditoria.
+- Gitleaks, OSV-Scanner e Opengrep locais, com versões e hashes revisados.
+- Auditoria offline e preparo explícito de bases, sem conta de análise externa.
+- Relatórios redigidos, testes reais dos scanners e preservação de recursos próprios.
+- Curadoria de ferramentas e skills com licenças, fontes e limites documentados.
+
 ## 0.0.10 — 2026-11-12
 
 - Mesmo pacote publicado no npm e GitHub Packages, com versão e bytes iguais.

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.10 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.
 
@@ -57,6 +57,7 @@ The CLI supports `pt`, `en` and `es`; it saves your selection per project.
 | 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] |
+| Review security with local tools | [Local security](docs/guides/security.md) |
 | Look up options or fix an error | [CLI][cli] · [Troubleshooting][help] |
 | Improve the kit | [Contributing](CONTRIBUTING.md) |
 | Try the scenarios | [Examples](https://github.com/pathbit/AgentDevKit/tree/master/examples) |
@@ -89,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.10
+[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.10][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.
 
@@ -58,6 +58,7 @@ La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 | 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] |
+| Revisar seguridad con herramientas locales | [Seguridad local](docs/guides/security.md) |
 | Consultar opciones o resolver un error | [CLI][cli] · [Soluciones][help] |
 | Mejorar el kit | [Contribuir](CONTRIBUTING.md) |
 | Probar los escenarios | [Ejemplos](https://github.com/pathbit/AgentDevKit/tree/master/examples) |
@@ -91,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.10
+[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.10][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`.
@@ -57,6 +61,7 @@ O idioma da CLI pode ser `pt`, `en` ou `es`.
 | 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] |
+| Revisar segurança sem serviços externos | [Segurança local](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/security.md) |
 | Consultar opções ou resolver um erro | [CLI][cli] · [Soluções][help] |
 | Melhorar o próprio kit | [Contribuir](https://github.com/pathbit/AgentDevKit/blob/master/CONTRIBUTING.md) |
 | Experimentar os cenários | [Exemplos](https://github.com/pathbit/AgentDevKit/tree/master/examples) |
@@ -101,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.10
+[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/README.md

@@ -27,6 +27,7 @@ pode trocar de agente sem manter várias cópias das mesmas instruções.
 | 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] |
+| Revisar segurança | [Scanners locais e controles](guides/security.md) |
 | Executar ou verificar algo | [CLI](guides/cli.md) → [ferramentas e testes][tests] |
 | Corrigir uma dificuldade | [Soluções e recuperação](guides/troubleshooting.md) |
 | Contribuir com o kit | [Contribuir][contrib] → [design](product/design.md) |
@@ -39,10 +40,10 @@ pode trocar de agente sem manter várias cópias das mesmas instruções.
 
 | Termo | Significado |
 | --- | --- |
-| Skill | Procedimento que o agente segue para uma tarefa. |
+| Skill | Procedimento que orienta decisões e ações de uma tarefa. |
 | Regra | Orientação aplicável a um contexto de trabalho. |
-| Comando | Entrada para executar um caso de uso. |
-| Perfil de agente | Papel especializado, como revisão. |
+| Comando | Entrada de um caso de uso com passos, argumentos e saída. |
+| Perfil de agente | Responsável por uma tarefa completa. |
 | Adaptador | Traduz referências para o formato de cada cliente. |
 | Espelho | Apontamento gerado para um recurso da origem. |
 | Template | Modelo que será preenchido com decisões do projeto. |
@@ -52,6 +53,8 @@ pode trocar de agente sem manter várias cópias das mesmas instruções.
 O agente lê e executa as instruções conforme as capacidades de seu cliente.
 A CLI instala, sincroniza e diagnostica arquivos. Ter um apontamento correto
 não comprova que determinado cliente carregou ou executou a skill.
+O [guia de recursos](guides/resources.md) mostra como esses componentes se
+combinam; não existe uma proporção obrigatória entre suas quantidades.
 
 ## Conheça este produto
 

package/docs/guides/README.md

@@ -10,6 +10,7 @@ description: Guias de instalação, uso e verificação do AgentDevKit.
 - [Fluxo de trabalho](workflow.md)
 - [Evoluir documentação existente](documentation.md)
 - [Recursos dos agentes](resources.md)
+- [Segurança local](security.md)
 - [Ferramentas e testes](tools-and-testing.md)
 - [Solução de problemas](troubleshooting.md)
 

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.10` 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
@@ -132,11 +132,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
@@ -150,9 +167,9 @@ 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.10][spec]
+[Wiki](../README.md) · [Spec de segurança][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.10/SPEC.md
+[spec]: ../specs/security-ecosystem/SPEC.md
 [tokens]: https://github.com/settings/tokens
 [github-auth]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages

package/docs/guides/resources.md

@@ -23,7 +23,7 @@ Os caminhos abaixo são relativos a `.pbai4devs/`.
 | Skill | Procedimento e decisões. | `skills/<grupo>/<nome>/SKILL.md` |
 | Regra | Convenção aplicada a um contexto. | `rules/<nome>/RULE.md` |
 | Comando | Entrada de um caso de uso. | `commands/<nome>/COMMAND.md` |
-| Agente | Papel, ferramentas e limites. | `agents/<nome>/AGENT.md` |
+| Agente | Responsável por uma tarefa. | `agents/<nome>/AGENT.md` |
 | Modelo | Base a preencher. | `templates/<nome>/TEMPLATE.md` |
 | Tool | Configuração e entrada de uma CLI. | `tools/<nome>/TOOL.json` |
 | Script | Automação executável reutilizável. | `scripts/<nome>/SCRIPT.mjs` |
@@ -32,6 +32,53 @@ Uma skill explica como decidir; um script executa a operação. Um comando
 encaminha a essas fontes, sem repetir suas instruções. Uma regra mantém uma
 convenção recorrente; um agente define quem revisa ou executa determinado papel.
 
+Uma skill pode orientar o uso de outras skills, comandos e agentes. Quem faz
+essas chamadas é o cliente de IA, dentro das ferramentas e permissões disponíveis.
+Um workflow é a sequência de passos e entregas descrita no comando; não precisa
+ser outro tipo de arquivo ou um agendamento em segundo plano.
+
+```mermaid
+flowchart LR
+  pedido["Pedido"] --> comando["Comando"]
+  comando --> agente["Agente responsável"]
+  regras["Regras"] -.-> agente
+  agente --> skill["Skill"]
+  skill --> script["Script quando necessário"]
+  script --> tool["Ferramenta local"]
+  tool --> prova["Evidências"]
+  prova --> revisao["Revisão independente"]
+```
+
+O agente principal reúne resultados e mantém o contexto. Quando um cliente
+não permite delegação aninhada, o especialista devolve o próximo passo ao
+principal. Markdown e links não criam processos nem executam código sozinhos.
+
+## Três fluxos completos
+
+| Etapa | Comando | Resultado |
+| --- | --- | --- |
+| Planejar | `planejar-entrega` | Dúvidas, plano e aceites. |
+| Implementar | `implementar-entrega` | Código, testes e documentos. |
+| Auditar | `auditar-seguranca` | Sinais locais e triagem. |
+
+O planejador combina as skills da fase para reunir as decisões. O implementador
+executa o plano aprovado. O auditor interpreta os scanners preparados por
+`preparar-seguranca` e verifica os controles que exigem contexto.
+
+No fluxo de implementação, `validar-entrega` executa as provas e
+`atualizar-documentacao` aciona o documentador. O revisor recebe a entrega
+final por `revisar-entrega`; quem implementou não substitui a revisão independente.
+Falhas retornam ao responsável com evidência e escopo de correção.
+
+Na segurança, scanners e análise manual se complementam. Achados confirmados
+seguem `corrigir-vulnerabilidade`; depois são testados de novo. O
+[guia de segurança](security.md) define preparação, limites e resultados.
+
+Não busque quantidades iguais por tipo: uma skill atende vários comandos,
+um perfil usa várias skills e uma regra vale em diferentes fluxos. Crie um
+perfil quando houver responsabilidade recorrente e contexto próprio; use
+skill para um procedimento e comando para uma entrada de trabalho clara.
+
 Modelos não são documentos aprovados do produto. Ferramentas usam um
 `SCRIPT.mjs` fino para delegar ao instalador comum; não precisam de cópias em
 cada cliente nem de outro instalador escrito do zero.

package/docs/guides/security-references.md

@@ -0,0 +1,97 @@
+---
+description: Ferramentas e skills de segurança locais e open source.
+---
+
+# Referências de segurança
+
+As verificações do kit executam no computador do projeto. Não exigem conta,
+assinatura ou envio de código a um serviço. Downloads de ferramentas e bases
+públicas são etapas explícitas; a análise usa os arquivos locais.
+
+## Ferramentas selecionadas
+
+| Ferramenta | Origem e licença | Função |
+| --- | --- | --- |
+| [Gitleaks][gitleaks] | Comunidade, MIT | Segredos em arquivos e Git. |
+| [OSV-Scanner][osv] | Google, Apache-2.0 | Dependências, com base OSV local. |
+| [Opengrep][opengrep] | Consórcio, LGPL-2.1 | Código, com regras locais. |
+
+O catálogo fixa versões e hashes revisados. `install` verifica o download;
+`check` confere o binário local; `update` aplica o pin revisado no catálogo.
+Nenhum dos três exige Python instalado. O upstream do Gitleaks está focado
+em manutenção e correções; isso deve ser considerado nas próximas revisões.
+
+OSV deve usar `--offline`, não somente `--offline-vulnerabilities`.
+A base precisa ser preparada antes: ausência de dados não é resultado limpo.
+Opengrep usa configuração local e checagem de versão desativada; não use
+`--config auto`. O comando de auditoria normaliza os resultados e remove
+segredos e trechos de código dos relatórios.
+
+## Complementos por necessidade
+
+| Ferramenta | Licença | Quando considerar |
+| --- | --- | --- |
+| [Trivy][trivy] | Apache-2.0 | Imagens, IaC e SBOM. |
+| [ZAP][zap] | Apache-2.0 | Aplicação em execução; exige Java. |
+| [DevSkim][devskim] | MIT | Projetos .NET; exige runtime local. |
+
+Esses complementos não são instalados pelo grupo `security`. Uma adoção exige
+testar seu modo local, dependências, versão e licença. No ZAP, instalação não
+inicia proxy, daemon ou ataque; configure identidades de teste e alvo local.
+No Trivy, `--offline-scan` sozinho não bloqueia toda atualização de base.
+
+Serviços de análise que exigem conta ficam fora desse fluxo. CodeQL CLI não
+atende ao requisito de código aberto; Bandit e rotinas Python ficam fora do
+runtime adotado. Uma opção gratuita não é automaticamente open source.
+
+## Skills de mercado
+
+| Fonte | Recurso | Tratamento |
+| --- | --- | --- |
+| [OpenAI][openai] | Práticas e ameaças | Apache-2.0 por pasta. |
+| [GitHub][copilot] | Revisão de segurança | MIT. |
+| [Trail of Bits][tob] | Contexto e diffs | CC-BY-SA-4.0; candidata. |
+
+Os [pins e licenças do catálogo][catalog] evitam importar uma origem móvel.
+As quatro skills próprias de segurança já acompanham o kit; referências
+externas são opcionais e lidas por tarefa, sem copiar texto para os clientes.
+Preserve atribuição e share-alike dos recursos da Trail of Bits.
+Uma lista estática de CVEs em uma skill não substitui uma base atualizada.
+
+## O artigo como ponto de partida
+
+O [artigo compartilhado][article] orientou cinco temas: acesso aos dados,
+autorização no servidor, acesso por ID, segredos e entradas não confiáveis.
+O kit trata essas perguntas com verificações específicas:
+
+- PostgreSQL/Supabase usa RLS e políticas; Firebase usa Security Rules.
+  Papéis privilegiados e SDKs de servidor precisam de controles próprios.
+- Ocultar um botão não autoriza uma operação. Teste sem sessão e com dois
+  usuários ou tenants, incluindo acesso ao objeto de outra identidade.
+- Variáveis enviadas ao bundle são públicas; variáveis do servidor não são
+  automaticamente expostas. Um segredo confirmado exige remoção e rotação.
+- Validação de entrada, consultas parametrizadas, codificação de saída,
+  controles de upload e limites de uso resolvem riscos diferentes.
+
+As referências técnicas são [RLS][rls], [Firebase Rules][firebase],
+[autorização][authz], [segredos][secrets] e [uploads][uploads]. O kit não usa as
+estatísticas do artigo como comprovação de segurança do projeto.
+
+[Segurança no fluxo](security.md) · [Recursos](resources.md)
+
+[gitleaks]: https://github.com/gitleaks/gitleaks/tree/v8.30.1
+[osv]: https://github.com/google/osv-scanner/tree/v2.7.1
+[opengrep]: https://github.com/opengrep/opengrep/tree/v1.33.1
+[trivy]: https://github.com/aquasecurity/trivy
+[zap]: https://www.zaproxy.org/docs/desktop/start/features/
+[devskim]: https://github.com/microsoft/DevSkim
+[openai]: https://github.com/openai/skills
+[copilot]: https://github.com/github/awesome-copilot
+[tob]: https://github.com/trailofbits/skills
+[catalog]: ../../.pbai4devs/external-skills/CATALOG.json
+[article]: https://manodeyvin.com.br/p/5-vacilacoes-de-seguranca-que-a-ia
+[rls]: https://supabase.com/docs/guides/database/postgres/row-level-security
+[firebase]: https://firebase.google.com/docs/rules
+[authz]: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
+[secrets]: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
+[uploads]: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html

package/docs/guides/security.md

@@ -0,0 +1,32 @@
+---
+description: Segurança com scanners locais, triagem e provas de controles.
+language: pt
+---
+
+# Segurança local
+
+O kit instala skills, regras, comandos e perfis para revisar segurança.
+Os scanners exigem preparo explícito; nenhuma auditoria ou aplicação começa
+em segundo plano apenas porque os arquivos de instrução foram instalados.
+
+O [guia operacional][guide] acompanha o hub no projeto consumidor. Ele explica
+preparo das ferramentas, bases offline, relatório e triagem, além dos testes
+manuais de autorização, isolamento de dados, entradas e abuso.
+
+- [Preparar segurança][prepare]: instalar e verificar os scanners locais.
+- [Auditar segurança][audit]: analisar o alvo autorizado e interpretar sinais.
+- [Revisar autorização][authorization]: testar identidade e acesso por recurso.
+- [Modelar ameaças][threats]: antecipar riscos das fronteiras de confiança.
+- [Curadoria](security-references.md): fontes, licenças e ferramentas avaliadas.
+
+Use o [mapa do ecossistema](resources.md) para entender como perfis, skills,
+comandos, regras e scripts se conectam. Resultados ficam em `.agent-tests/`;
+scanners sozinhos não aprovam a segurança de um produto.
+
+[Wiki](../README.md) · [Ferramentas e testes](tools-and-testing.md)
+
+[guide]: ../../.pbai4devs/skills/seguranca/REFERENCE.md
+[prepare]: ../../.pbai4devs/commands/preparar-seguranca/COMMAND.md
+[audit]: ../../.pbai4devs/commands/auditar-seguranca/COMMAND.md
+[authorization]: ../../.pbai4devs/skills/seguranca/revisar-autorizacao/SKILL.md
+[threats]: ../../.pbai4devs/skills/seguranca/modelar-ameacas/SKILL.md

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.