@pathbit/agentdevkit 0.0.10 → 0.0.11

package/.pbai4devs/tools/README.md

@@ -8,8 +8,9 @@ Cada pasta mantém `TOOL.json`, `SCRIPT.mjs` e um guia.
 O catálogo local `catalog.json` relaciona essas definições aos comandos
 de instalação, atualização, verificação e execução. Ao editar definições,
 rode `sincronizar-agentes` e `--check`; versões instaladas ficam no estado local.
-O instalador comum consulta `latest` na origem oficial e instala com
-`--ignore-scripts`. Pacotes e estado ficam em `<nome>/.local/`; cache em
+Para npm, o instalador consulta `latest` e usa `--ignore-scripts`.
+Scanners nativos usam versões e SHA-256 revisados em `TOOL.json`; `update`
+aplica esse pin. Pacotes e estado ficam em `<nome>/.local/`; cache em
 `.cache/` e atalhos em `bin/`, todos ignorados. Tools ficam só em `.pbai4devs`.
 
 | CLI | Grupo | Uso |
@@ -22,9 +23,14 @@ O instalador comum consulta `latest` na origem oficial e instala com
 | [opensrc][source] | source | Fontes de dependências. |
 | [webreel][video] | video | Roteiros e vídeos do navegador. |
 | [portless][proxy] | proxy | Proxy e URLs locais estáveis. |
+| [gitleaks](gitleaks/README.md) | security | Segredos em arquivos e Git. |
+| [osv-scanner](osv-scanner/README.md) | security | Dependências com base local. |
+| [opengrep](opengrep/README.md) | security | Código com regras locais. |
 
 `setup` instala e verifica todos os CLIs compatíveis. O grupo `base` limita a
-seleção a navegador e lint; outros grupos permitem escolher por tarefa.
+seleção a navegador e lint; `security` seleciona os três scanners.
+As bases de vulnerabilidades são preparadas separadamente; instalar o CLI
+não transforma uma base ausente em resultado limpo.
 Confira Node/npm pelo [primeiro uso][manager] antes de executar os scripts.
 O instalador usa o mesmo Node 24+ com npm em todos os sistemas. Plataformas aceitas
 ficam em cada `TOOL.json`; ausência de restrição npm não comprova teste do SO.
@@ -45,6 +51,8 @@ O [instalador comum][manager] aceita nomes ou grupos, como `setup`, `install bas
 `update video`, `check source` e `list`.
 
 O preparo verifica o CLI; fluxos de aplicação precisam de provas específicas.
+O [fluxo de segurança](../commands/auditar-seguranca/COMMAND.md) usa análise
+offline e relatórios redigidos. Downloads públicos exigem rede, não conta.
 Skills usa descoberta sem importação automática ou symlinks. Portless é opt-in:
 o preparo não inicia proxy. Webreel exige executáveis explícitos para gravar
 sem baixar recursos em `~/.webreel`; seu guia lista os overrides. Use caminhos

package/.pbai4devs/tools/gitleaks/README.md

@@ -0,0 +1,22 @@
+---
+description: Instalacao local revisada do gitleaks.
+---
+
+# gitleaks
+
+Procura segredos em arquivos e no historico Git.
+
+Versao revisada: **8.30.1**. Licenca: [MIT](https://github.com/gitleaks/gitleaks/blob/v8.30.1/LICENSE).
+Downloads vem da [release oficial](https://github.com/gitleaks/gitleaks/releases/tag/v8.30.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/gitleaks/SCRIPT.mjs <acao>`.
+
+Use os comandos de seguranca do kit para obter saida redigida. Resultados
+exigem triagem; revogar credenciais reais continua necessario.
+
+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/gitleaks/SCRIPT.mjs

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

package/.pbai4devs/tools/gitleaks/TOOL.json

@@ -0,0 +1,67 @@
+{
+  "name": "gitleaks",
+  "description": "Detecta segredos locais e no historico Git.",
+  "group": "security",
+  "source": "https://github.com/gitleaks/gitleaks/releases/tag/v8.30.1",
+  "license": "MIT",
+  "licenseSource": "https://github.com/gitleaks/gitleaks/blob/v8.30.1/LICENSE",
+  "download": {
+    "provider": "github-release",
+    "repository": "gitleaks/gitleaks",
+    "channel": "reviewed",
+    "version": "8.30.1",
+    "tag": "v8.30.1",
+    "assets": {
+      "darwin-arm64": {
+        "file": "gitleaks_8.30.1_darwin_arm64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "b40ab0ae55c505963e365f271a8d3846efbc170aa17f2607f13df610a9aeb6a5"
+      },
+      "darwin-x64": {
+        "file": "gitleaks_8.30.1_darwin_x64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "dfe101a4db2255fc85120ac7f3d25e4342c3c20cf749f2c20a18081af1952709"
+      },
+      "linux-arm64": {
+        "file": "gitleaks_8.30.1_linux_arm64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080"
+      },
+      "linux-x64": {
+        "file": "gitleaks_8.30.1_linux_x64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+      },
+      "win32-arm64": {
+        "file": "gitleaks_8.30.1_windows_arm64.zip",
+        "format": "zip",
+        "binary": "gitleaks.exe",
+        "sha256": "b95f5e4f5c425cedca7ee203d9afd29597e692c4924a12ed42f970537c72cc0f"
+      },
+      "win32-x64": {
+        "file": "gitleaks_8.30.1_windows_x64.zip",
+        "format": "zip",
+        "binary": "gitleaks.exe",
+        "sha256": "d29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e"
+      }
+    }
+  },
+  "platforms": [
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-arm64",
+    "linux-x64",
+    "win32-arm64",
+    "win32-x64"
+  ],
+  "scripts": {
+    "entry": "SCRIPT.mjs"
+  },
+  "probe": [
+    "version"
+  ]
+}

package/.pbai4devs/tools/opengrep/README.md

@@ -0,0 +1,22 @@
+---
+description: Instalacao local revisada do opengrep.
+---
+
+# opengrep
+
+Executa regras SAST armazenadas no projeto.
+
+Versao revisada: **1.33.1**. Licenca: [LGPL-2.1](https://github.com/opengrep/opengrep/blob/v1.33.1/LICENSE).
+Downloads vem da [release oficial](https://github.com/opengrep/opengrep/releases/tag/v1.33.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/opengrep/SCRIPT.mjs <acao>`.
+
+Use `--config` com regras locais e `--disable-version-check`. Nao use `auto`
+ou URLs de regras no modo local.
+
+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/opengrep/SCRIPT.mjs

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

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,15 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 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.11 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.11
 [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.11][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.11
 [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

@@ -42,7 +42,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.11][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 +57,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 +102,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.11
 [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/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.11` 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
@@ -150,9 +150,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.