@zaip-ai/cli 0.1.0 → 1.0.1

package/templates/.agents/skills/zaip-skill-setup/SKILL.md

@@ -1,12 +1,25 @@
 ---
 name: zaip-skill-setup
-description: Install, diagnose, migrate, upgrade, or roll back ZAIP-AIOS V2 configuration, Rules, Requirements, skills, data layout, and legacy compatibility.
+description: Install, diagnose, migrate, upgrade, or roll back ZAIP configuration and layout.
 ---
 
 # Configurar ZAIP-AIOS
 
-1. Faça dry-run e rejeite conflitos de checksum ou arquivos do usuário.
-2. Crie ou valide as cinco Rules (`core`, `workflow`, `architecture`, `security`, `context`) e os cinco Requirements de área (`work-lifecycle`, `execution-engine`, `cost-observability`, `kanban-dashboard`, `context-engine`), além de config, skills e data.
-3. Preserve raízes V1 como legado somente leitura até migração explícita e idempotente.
-4. Rode doctor, validações de skills, encoding, adapters e evals aplicáveis.
-5. Repita o dry-run e exija ausência de drift; em upgrade, valide rollback antes de aplicar.
+1. Faça dry-run, descubra a versão/layout e rejeite conflitos de checksum, ownership ou arquivos divergentes do usuário.
+2. Instale/valide `config/project.yaml`, `config/framework.lock.yaml`, as cinco Rules core em `rules/zaip`, `rules/project` preservada, todos os Requirements/skills gerenciados pelo manifest, as raízes V2 de `data` e o dashboard frontend-only em `.agents/dashboard` quando ele fizer parte da distribuição.
+3. Nunca mantenha lista fixa da quantidade de Requirements ou skills no workflow; derive o catálogo do release/lock vigente.
+4. Preserve arquivos do projeto. Configuração específica usa `$zaip-skill-config`; Rules específicas usam `$zaip-skill-rules`.
+5. Mantenha raízes V1 somente leitura até migração explícita, planejada, idempotente e reversível.
+6. Rode doctor, skills, encoding, architecture, adapters e validações aplicáveis; repita o dry-run e exija ausência de drift.
+7. Em upgrade, confirme backup/rollback e não substitua `rules/project` nem escolhas de `project.yaml` silenciosamente.
+8. Somente no repositório-fonte do framework, após alterar arquivo gerenciado rode `pnpm sync:framework-lock` e `pnpm validate:framework-lock`; em projeto consumidor, o lock muda apenas por setup/upgrade transacional.
+
+## Perfis Codex ZAIP-AIOS
+
+- Gere e documente exatamente `zaip-aios-security` e `zaip-aios-full-access`; leia `.agents/zaip-aios/guides/10-seguranca.md` antes de alterá-los.
+- Em `zaip-aios-security`, materialize uma tabela com a raiz física absoluta do repositório, `"." = "write"`, `".git" = "write"`, `".agents" = "write"` e `".codex" = "write"`; isso inclui as árvores de controle e as operações Git sem liberar `C:\`. Não use `extends = ":workspace"` nem `:workspace_roots` no Windows. Permita escrita em `~/.ssh` para fluxos Git/SSH autorizados e configure rede `limited` com allowlist exclusiva para `github.com`.
+- Configure `approval_policy = "never"`; mantenha a autorização explícita de deploy nas Rules, hooks e skills, sem depender de escalada para o fluxo GitHub permitido pelo perfil.
+- Em `zaip-aios-full-access`, represente explicitamente escrita em `:root`/`C:\` e rede `full` com `"*" = "allow"`. Marque o perfil como excepcional e de maior risco.
+- Preserve as camadas compensatórias em ambos: instruções e escopo, hook `PreToolUse`, regras `forbidden`, política GitHub, proteção de segredos, lifecycle sanitizado, escopos de subagentes e ACLs do sistema operacional.
+- Não apresente essas camadas como substitutas do sandbox restrito; full access permanece capaz de alcançar `.agents`, `.codex`, outros caminhos em `C:\` e rede quando o host permitir.
+- Após sincronizar configuração e projeções, exija reinício completo. Valide escrita em workspace/`.git`/`.agents`/`.codex`, negação externa, acesso SSH ao `github.com` e bloqueio de outros destinos no perfil restrito; no full access, valide somente a configuração e as camadas, sem criar probes externos desnecessários. Se uma configuração antiga já tiver materializado ACLs de negação, feche o Codex, faça backup de `~/.codex/cap_sid`, remova somente o arquivo ativo e deixe o Codex recriá-lo; nunca tente corrigir as ACLs manualmente.

package/templates/.agents/skills/zaip-skill-setup/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ZAIP Setup"
-  short_description: "Install or migrate ZAIP-AIOS V2"
-  default_prompt: "Use $zaip-skill-setup to install, validate, or migrate a ZAIP-AIOS V2 workspace."
+  short_description: "Install, diagnose, migrate, upgrade, or roll back ZAIP."
+  default_prompt: "Use $zaip-skill-setup to install, diagnose, migrate, upgrade, or roll back a ZAIP-AIOS V2 workspace."

package/templates/.agents/skills/zaip-skill-spec/SKILL.md

@@ -1,12 +1,45 @@
 ---
 name: zaip-skill-spec
-description: Create, refine, prepare, execute, validate, and complete optional ZAIP delivery SPECs and their task DAGs. Use when technical intent needs a durable plan broader than one task.
+description: Create, refine, prepare, and analyze multi-Task ZAIP delivery SPECs and DAGs while preserving draft status until the user explicitly requests ready or execution.
 ---
 
 # Trabalhar com SPECs
 
-1. Confirme que uma SPEC agrega valor; Task-first continua válida para trabalho pontual.
-2. Registre escopo, fora de escopo, Requirements/AC, riscos, DAG, critérios de paralelismo e orçamento.
-3. Use `prepare` para validar e persistir o plano com IDs pré-alocados; não crie trabalho executável.
-4. Só após pedido explícito, use `execute` para materializar Changes, Tasks e Execution de forma idempotente.
-5. Acompanhe o resultado macro da SPEC agregando todas as Tasks, Executions, Runs, evidências, tokens e custos.
+SPEC é opcional para trabalho técnico amplo; Task-first continua válida para uma mudança pontual. A SPEC permanece em Planejamento com `status: draft` durante criação, revisão, refinamento e `prepare`.
+
+## Limite de autoridade
+
+1. Não invoque `spec ready`, `spec execute` ou `spec activate` por inferência, conveniência ou conclusão do conteúdo.
+2. Pedido para criar, revisar, aprovar conteúdo, refinar, planejar ou preparar preserva `draft`.
+3. Somente pedido explícito para mover a “Pronto para Executar” delega a promoção para `$zaip-skill-move-spec`.
+4. Somente pedido explícito para executar delega preparação necessária e execução para `$zaip-skill-execution`.
+
+## Create e refine
+
+1. Defina objetivo, escopo, fora de escopo, Requirements/AC, design, riscos, rollout/fallback, orçamento e perguntas bloqueantes.
+2. Antes do design técnico, leia `stack.profile` e `stack.overrides` em `.agents/config/project.yaml`, resolva `.zaip-aios/profiles/<stack.profile>.json` e considere essa a stack padrão do projeto.
+3. Registre em `implementation` o snapshot resolvido: `stack_profile`, `stack_overrides`, uma `stack_description` curta que mencione componentes e versões exatas, e `stack_components` com nome, tipo, versão exata e `version_source` workspace-relative. Nunca invente versões; use manifests, lockfiles, arquivos de runtime, imagens ou profiles verificáveis.
+4. Se vier de um PRD, mantenha `prd_id`; caso contrário, preserve a SPEC standalone sem PRD sintético.
+5. Decomponha em Tasks pequenas, verificáveis e com write scopes; modele dependências e integração na DAG.
+6. Refinar ou comparar SPECs não cria Change, Task executável, Execution nem Run.
+7. Para refine Git-native, edite somente o arquivo canônico retornado pelo create enquanto `status: draft`; preserve ID/`created_at`, incremente `revision`, atualize `updated_at` e valide com `zaip spec show <ID>`. Não use `prepare` como encerramento automático da criação. Depois de `ready`, não faça patch manual: prepare nova revisão antes da execução ou registre rework após materialização.
+
+## Prepare
+
+1. Valide referências, cobertura de AC, IDs, ciclos, conflitos de paralelismo, comandos de verificação e o snapshot de stack contra a configuração atual do projeto.
+2. Bloqueie stack ausente, profile/overrides divergentes, versão em range ou móvel, componente sem linguagem, descrição sem componente/versão ou `version_source` inexistente. Mudança posterior da stack exige nova revisão da SPEC; não reinterprete silenciosamente snapshot preparado.
+3. Gere e valide o PreparedPlan conforme [o contrato compacto](../zaip-skill-execution/references/prepared-plan.md), então persista IDs pré-alocados sem mudar `draft` para `ready`; preparação continua em Planejamento.
+4. Quando o plano for global de um PRD, a SPEC pode ser preparada/ativada pelo pai sem duplicar outra Execution.
+5. Após `prepare`, mostre que a SPEC continua em Planejamento e pare; não encadeie `spec ready` ou `spec execute` sem a solicitação explícita correspondente.
+
+## Handoff e analyze
+
+1. Pare em Planejamento após `prepare`. Somente após pedido explícito de promoção, use `$zaip-skill-move-spec`; somente após pedido explícito de execução, delegue a `$zaip-skill-execution`.
+2. Considere a SPEC entregável somente quando Changes, Tasks, Executions, Runs e evidências descendentes passarem.
+3. Na análise, agregue tokens/custo por conversa, planejamento, execução e total, sem dupla contagem.
+
+## Assurance de entrega
+
+1. Antes de entregar uma SPEC, construa a matriz parental completa de ACs e produza pelo menos três validações e três Evidences próprias; resultados das Tasks não substituem esta camada.
+2. As modalidades mínimas são integração, spec review e quality review. O review é de autor e Run diferentes, e todos os artefatos usam o commit final esperado.
+3. Uma SPEC com Tasks `lite` continua usando rigor parental: a redução vale para a Task avulsa, não para a alegação integrada da SPEC.

package/templates/.agents/skills/zaip-skill-spec/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ZAIP SPEC"
-  short_description: "Plan and execute optional delivery SPECs"
-  default_prompt: "Use $zaip-skill-spec to create, refine, prepare, or execute an optional technical SPEC."
+  short_description: "Crie SPECs sem promover antes da autorização."
+  default_prompt: "Use $zaip-skill-spec para criar ou preparar uma SPEC e mantê-la em draft até eu pedir promoção ou execução."

package/templates/.agents/skills/zaip-skill-task/SKILL.md

@@ -1,13 +1,41 @@
 ---
 name: zaip-skill-task
-description: Plan, prepare, execute, verify, and complete ZAIP task-first work or tasks inside a dependency DAG, including Changes, Executions, Runs, evidence, and costs.
+description: Prepare task-first ZAIP work or DAG Tasks without implicit execution.
 ---
 
-# Executar Tasks
+# Trabalhar com Tasks
 
-1. Diferencie conversa, planejamento e execução; não transforme pergunta sem mutação em Task automaticamente.
-2. Para Task-first, prepare um plano direto sem criar PRD ou SPEC sintéticas.
-3. Em `execute`, materialize Change, Task e Execution antes da primeira mutação; selecione apenas Task pronta na DAG.
-4. Implemente com contexto focado e registre decisões humanas e da IA junto da Change/Execution.
-5. Valide cada Acceptance Criterion com teste/eval/evidência determinística e derive o ledger do Git diff.
-6. Conclua somente após preencher resultado, cobertura de custo e evidências; bloqueios devem informar causa e próximo passo.
+Somente trabalho executável é capturado como Task-first. Perguntas, análises pontuais read-only e classificações incertas permanecem conversas com Run sem Task; refinamentos e rework reutilizam a Task vigente, salvo pedido explícito de uma nova Task.
+
+## Captura de chat
+
+1. Classifique e capture o turno antes do trabalho substantivo. Pergunta, análise read-only ou dúvida usa `conversation start --intent conversation`; nenhuma Task é criada.
+2. Resposta, aprovação, continuação, refinamento ou rework usa `--intent continue|refine|rework` e reutiliza o alvo explícito ou o foco válido da mesma thread. Alvo não resolvido cai para conversa.
+3. Para trabalho novo, use `--intent new-work` com título semântico de 4 a 10 palavras, short name, objetivo e `--write-scopes` quando o escopo já for conhecido. A captura cria a Task; somente planejamento explicitamente solicitado pode parar em `planned`/Pronto para Executar. Nunca copie ou trunque o prompt como título.
+4. Pedido avulso executável materializa e inicia Execution, Change, Task e Run raiz do `zaip-agent-orchestrator` antes da primeira mutação; a Task entra diretamente em `executing`. Definition é exclusiva de PRD e Planning é exclusiva de SPEC no board.
+
+## Create e refine
+
+1. `task create` persiste uma Task manual em `draft`, com objetivo, Requirements/AC, risco, prioridade, dependências e write scopes.
+2. Nenhum Change, Execution ou Run de execução existe nessa fase; o Run de captura `conversation`, telemetria de planning e IDs futuros podem existir sem materializar trabalho.
+3. Refine escopo, fora de escopo, plano, fallback e critérios até que a Task seja verificável.
+4. Para refine Git-native, edite somente o arquivo canônico retornado pelo create enquanto `status: draft`; preserve IDs/`created_at`, incremente `revision`, atualize `updated_at` e valide com `zaip task show <ID>`. Não edite manualmente uma Task `planned` ou materializada; refaça o plano antes da execução ou crie rework depois.
+
+## Prepare
+
+1. `task prepare <TASK-ID>` automático valida e persiste o plano somente quando `depends_on` está vazio. Se houver dependências, construa a DAG completa conforme [o contrato compacto](../zaip-skill-execution/references/prepared-plan.md) e use `task prepare <TASK-ID> --plan <plan.json>`.
+2. A Task passa a `planned`, mas o produto não é modificado e Change/Execution/Run ainda não são criados.
+3. Repetir prepare do mesmo plano reutiliza hash e IDs; mudança semântica exige nova revisão do plano.
+
+## Handoff
+
+1. Pare em planejamento após `prepare`. Somente após pedido explícito de execução, delegue `task execute <TASK-ID>`, verificação e conclusão a `$zaip-skill-execution`.
+2. Ao inspecionar resultado, exija Run terminal, evidência por AC e arquivos derivados do Git diff; falha lógica requer rework rastreável.
+
+## Assurance proporcional
+
+1. Quando `assurance.version: 1` estiver ativo, Task standalone `lite` termina com exatamente uma validação tipada aprovada e exatamente uma Evidence tipada aprovada cobrindo todos os ACs. Ajustes simples de frontend podem usar esse perfil e não exigem Evidence de Definição ou Planejamento; a Evidence comprova somente a entrega e sua verificação.
+2. Task `standard` usa exatamente duas validações/Evidences no perfil base ou três no elevado; `standard_depth: auto` eleva Tasks com múltiplos write scopes. Inclua teste executado e modalidades distintas.
+3. Task `critical` usa três ou mais validações, Evidence por AC, teste, quality review por autor/Run independente, discriminação de mutação, rollback e commit final. Nunca rebaixe risco sensível para caber no perfil `lite`.
+4. Quantidade não substitui semântica: cada Evidence referencia validações aprovadas da mesma Task, Change e Execution e descreve o outcome observado.
+5. Nunca encerre a Run raiz sem executar `zaip-agent-execution-finalizer` como último Sub-Run da Execution nem com a Task em `executing` ou `verifying`. Gate insuficiente ou finalizador ausente termina a tentativa em `blocked`; retome com `task resume`. Falha técnica usa `failed` e `task rework` na mesma identidade; completed/cancelled são imutáveis.

package/templates/.agents/skills/zaip-skill-task/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ZAIP Task"
-  short_description: "Execute traceable Tasks and DAGs"
-  default_prompt: "Use $zaip-skill-task to plan, execute, and verify task-first work or a Task in a DAG."
+  short_description: "Create, refine, prepare, or inspect ZAIP Tasks."
+  default_prompt: "Use $zaip-skill-task to create, refine, prepare, or inspect Task-first or DAG work without starting execution."

package/templates/.agents/skills/zaip-skill-text-encoding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zaip-skill-text-encoding
-description: Detect, prevent, and fix UTF-8 and mojibake issues in ZAIP repositories. Use when UI copy, docs, rules, skills, Markdown, JSON, HTML, CSS, or TypeScript text shows broken accents, malformed Portuguese diacritics, replacement-character corruption, or other encoding regressions, or when text files need guardrails against encoding corruption.
+description: Detect, prevent, and fix UTF-8, mojibake, and malformed text in ZAIP repositories.
 ---
 
 # Protect text encoding
@@ -13,8 +13,8 @@ description: Detect, prevent, and fix UTF-8 and mojibake issues in ZAIP reposito
 
 ## Targets
 
-- `apps/kanban/src`
-- `apps/kanban/index.html`
+- `.agents/dashboard/apps/frontend/src`
+- `.agents/dashboard/apps/frontend/index.html`
 - `.agents/rules`
 - `.agents/requirements`
 - `.agents/skills`

package/templates/.agents/skills/zaip-skill-tool-setup/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: zaip-skill-tool-setup
+description: Discover, install, configure, authenticate, enable, disable, and diagnose ZAIP MCP servers and API-backed tools for Codex. Use when a user asks to activate a tool, configure connectors, prepare credentials, edit project-scoped Codex MCP settings, list ready tools, or run a tool doctor.
+---
+
+# Configurar tools ZAIP
+
+1. Leia `.agents/tools/catalog.yaml` e somente o manifesto da tool solicitada.
+2. Execute `scripts/inspect-tool.mjs <id> [mcp|api]` para produzir um plano sem segredos.
+3. Confirme que a implementacao ou URL MCP e oficial, verificavel ou mantida pelo ZAIP; nunca invente pacote.
+4. Prefira `.codex/config.toml` project-scoped. Preserve entradas existentes e apresente diff antes de mudar configuracao global.
+5. Mantenha a tool desabilitada ate dependencias, transporte e autenticacao serem validados.
+6. Para credenciais, crie apenas nomes em `.agents/.env.example`. Oriente o usuario a salvar valores fora do chat; nunca leia, imprima ou registre valores.
+7. Prefira OAuth quando suportado. Explique origem, escopos e URL oficial ao solicitar uma secret.
+8. Exija aprovacao para instalacao global, OAuth, escrita externa, cloud, gasto ou alteracao fora do workspace.
+9. Ative com `default_tools_approval_mode = "writes"`; aplique allowlist quando o servidor expuser tools amplas.
+10. Rode um doctor read-only, reporte `installed`, `configured`, `auth-pending`, `ready`, `disabled` ou `error`, e indique se reiniciar o Codex e necessario.
+11. Registre estado local sem secrets com `scripts/tool-state.mjs`; nunca altere o manifesto canônico para representar uma máquina.
+
+Leia `references/codex-config.md` ao gerar TOML. Leia `references/secrets.md` quando houver autenticacao.
+
+APIs sem MCP confiavel devem acionar `$zaip-skill-api-to-mcp`; nao exponha a API diretamente como se fosse MCP.

package/templates/.agents/skills/zaip-skill-tool-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Tool Setup"
+  short_description: "Configure e valide tools MCP e APIs sob demanda"
+  default_prompt: "Use $zaip-skill-tool-setup para descobrir, configurar, ativar ou desativar uma tool com seguranca."

package/templates/.agents/skills/zaip-skill-tool-setup/references/codex-config.md

@@ -0,0 +1,24 @@
+# Configuracao Codex
+
+O Codex compartilha MCPs entre app, CLI e extensao. Use `.codex/config.toml` em projeto confiavel ou `~/.codex/config.toml` para escopo global.
+
+STDIO exige `command`; pode usar `args`, `cwd`, `env_vars`, timeouts, allow/deny lists e modos de aprovacao. HTTP exige `url` e pode usar OAuth ou `bearer_token_env_var`.
+
+```toml
+[mcp_servers.exemplo]
+command = "executavel-verificado"
+args = []
+env_vars = ["EXEMPLO_TOKEN"]
+enabled = false
+default_tools_approval_mode = "writes"
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+```
+
+Nunca grave valores secretos no TOML. Use `codex mcp list`, `/mcp` e, para OAuth, `codex mcp login <nome>`.
+
+## Modelo e esforço
+
+`model` e `model_reasoning_effort` são defaults duráveis. O Codex aplica primeiro flags da CLI, depois `.codex/config.toml` do projeto confiável e só então `~/.codex/config.toml`. Para permitir escolha manual por Task, não fixe esses campos no projeto. O arquivo global pode guardar a última preferência escolhida pelo usuário; sem `model` global, o Codex usa a escolha da sessão ou o modelo recomendado.
+
+Depois de alterar configuração global ou de projeto, reinicie o Codex. Use `/debug-config` ou `codex --strict-config` para diagnosticar precedência e chaves desconhecidas.

package/templates/.agents/skills/zaip-skill-tool-setup/references/secrets.md

@@ -0,0 +1,8 @@
+# Secrets
+
+- Versione `.agents/.env.example` somente com nomes e comentarios.
+- Ignore `.agents/.env`, `.agents/.env.*`, `.agents/local/` e `.agents/secrets/`.
+- Prefira secret manager ou arquivo fora do repositorio para producao.
+- Nao peça segredo no chat, argumento de processo, log ou evidencia.
+- Valide presenca sem exibir valor; redija erros e headers.
+- Solicite menor escopo, expiracao e ambiente sandbox quando disponiveis.

package/templates/.agents/skills/zaip-skill-tool-setup/scripts/configure-local-mcp.mjs

@@ -0,0 +1,52 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+const [id, ...flags] = process.argv.slice(2);
+if (!/^[a-z0-9-]+$/.test(id ?? ""))
+  throw new Error("Usage: configure-local-mcp.mjs <id> [--enable|--disable] [--write]");
+const enabled = flags.includes("--enable");
+const write = flags.includes("--write");
+const configPath = resolve(".codex/config.toml");
+const serverPath = `.agents/tools/servers/${id}/server.mjs`;
+const start = `# zaip-managed:${id}:start`;
+const end = `# zaip-managed:${id}:end`;
+let current = "";
+try {
+  current = await readFile(configPath, "utf8");
+} catch (error) {
+  if (error.code !== "ENOENT") throw error;
+}
+if (current.includes(`[mcp_servers.${id}]`) && !current.includes(start))
+  throw new Error(`Unmanaged MCP entry already exists: ${id}`);
+const block = `${start}\n[mcp_servers.${id}]\ncommand = "node"\nargs = ["${serverPath}"]\ncwd = "."\nenabled = ${enabled}\ndefault_tools_approval_mode = "writes"\nstartup_timeout_sec = 20\ntool_timeout_sec = 60\n${end}`;
+const expression = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\s*`, "m");
+const next = `${current.replace(expression, "").trimEnd()}${current.trim() ? "\n\n" : ""}${block}\n`;
+if (write) {
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, next, "utf8");
+}
+if (write) {
+  await ensureFile(
+    resolve(".agents/.gitignore"),
+    "/.env\n/.env.*\n!/.env.example\n/local/\n/secrets/\n",
+  );
+  await ensureFile(
+    resolve(".agents/.env.example"),
+    "# ZAIP tool secrets. Keep values empty in Git and never paste secrets into chat.\n",
+  );
+}
+process.stdout.write(
+  `${JSON.stringify({ id, enabled, write, config: ".codex/config.toml", restart_required: write, preview: write ? undefined : block }, null, 2)}\n`,
+);
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function ensureFile(path, content) {
+  try {
+    await readFile(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+  }
+}

package/templates/.agents/skills/zaip-skill-tool-setup/scripts/inspect-tool.mjs

@@ -0,0 +1,35 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+
+const root = resolve(import.meta.dirname, "../../../..");
+const [id, requestedType] = process.argv.slice(2);
+if (!id) throw new Error("Usage: inspect-tool.mjs <id> [mcp|api]");
+const catalog = parse(await readFile(resolve(root, ".agents/tools/catalog.yaml"), "utf8"));
+const matches = catalog.tools.filter(
+  (entry) => entry.id === id && (!requestedType || entry.type === requestedType),
+);
+if (matches.length !== 1) {
+  throw new Error(
+    matches.length === 0 ? `Unknown tool: ${id}` : `Ambiguous tool: ${id}; specify mcp or api`,
+  );
+}
+const entry = matches[0];
+const manifest = parse(await readFile(resolve(root, ".agents/tools", entry.manifest), "utf8"));
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      id: entry.id,
+      type: entry.type,
+      status: manifest.status,
+      enabled: manifest.enabled,
+      credentials: manifest.authentication?.required_variables ?? [],
+      capabilities: manifest.capabilities ?? [],
+      access: manifest.security?.default_access,
+      write_requires_approval: manifest.security?.write_requires_approval,
+      next: entry.type === "api" ? "find-or-build-mcp" : "verify-implementation",
+    },
+    null,
+    2,
+  )}\n`,
+);

package/templates/.agents/skills/zaip-skill-tool-setup/scripts/tool-state.mjs

@@ -0,0 +1,26 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { parse, stringify } from "yaml";
+
+const [command = "list", id, field, value] = process.argv.slice(2);
+const path = resolve(".agents/local/tools-state.yaml");
+let state = { schema_version: 1, profile: "default", tools: {} };
+try {
+  state = parse(await readFile(path, "utf8"));
+} catch (error) {
+  if (error.code !== "ENOENT") throw error;
+}
+if (command === "list") process.stdout.write(`${stringify(state)}\n`);
+else if (command === "set") {
+  if (
+    !/^[a-z0-9-]+$/.test(id ?? "") ||
+    !["installation", "authentication", "runtime", "health"].includes(field)
+  )
+    throw new Error(
+      "Usage: tool-state.mjs set <id> <installation|authentication|runtime|health> <value>",
+    );
+  state.tools[id] = { ...(state.tools[id] ?? {}), [field]: value };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, stringify(state), "utf8");
+  process.stdout.write(`${stringify(state.tools[id])}\n`);
+} else throw new Error("Use list or set");

package/templates/.agents/tools/README.md

@@ -0,0 +1,9 @@
+# ZAIP tools
+
+Catálogo de integrações de exemplo para descoberta sob demanda. Leia primeiro apenas `catalog.yaml`. Todos os exemplos começam desabilitados, sem credenciais e em modo read-only.
+
+- `mcp/`: servidores MCP e capacidades apresentadas ao agente.
+- `api/`: contratos para acesso HTTP direto.
+- `policies/`: limites comuns de segurança, aprovação e segredos.
+
+Ativar um exemplo exige escolher uma implementação real, configurar secrets fora do Git, validar permissões e executar testes em sandbox.

package/templates/.agents/tools/api/asaas/README.md

@@ -0,0 +1,22 @@
+# Asaas API
+
+Exemplo API desabilitado para `asaas`. Ele documenta descoberta e políticas; escolha e audite uma implementação real antes de ativar.
+
+Endpoint de referência: `https://api.asaas.com/v3`.
+
+## Capacidades
+
+- `customers.read`
+- `payments.read`
+- `payments.write`
+
+## Configuração
+
+1. Revise o manifest e limite as capacidades necessárias.
+2. Configure as variáveis fora do Git:
+
+- `ASAAS_API_KEY`
+
+3. Teste em sandbox usando somente leitura.
+4. Registre aprovação antes de habilitar qualquer operação de escrita.
+5. Valide redaction, timeout, retry, rate limit e idempotência.

package/templates/.agents/tools/api/asaas/manifest.yaml

@@ -0,0 +1,20 @@
+schema_version: 1
+id: asaas
+name: "Asaas API"
+type: api
+status: example
+enabled: false
+base_url: "https://api.asaas.com/v3"
+authentication:
+  source: environment
+  required_variables:
+    - ASAAS_API_KEY
+capabilities:
+    - customers.read
+    - payments.read
+    - payments.write
+security:
+  default_access: read-only
+  write_requires_approval: true
+  redact_secrets: true
+  retries_require_idempotency: true

package/templates/.agents/tools/api/github/README.md

@@ -0,0 +1,22 @@
+# GitHub REST and GraphQL APIs
+
+Exemplo API desabilitado para `github`. Ele documenta descoberta e políticas; escolha e audite uma implementação real antes de ativar.
+
+Endpoint de referência: `https://api.github.com`.
+
+## Capacidades
+
+- `repositories.read`
+- `issues.read`
+- `pull_requests.write`
+
+## Configuração
+
+1. Revise o manifest e limite as capacidades necessárias.
+2. Configure as variáveis fora do Git:
+
+- `GITHUB_TOKEN`
+
+3. Teste em sandbox usando somente leitura.
+4. Registre aprovação antes de habilitar qualquer operação de escrita.
+5. Valide redaction, timeout, retry, rate limit e idempotência.

package/templates/.agents/tools/api/github/manifest.yaml

@@ -0,0 +1,20 @@
+schema_version: 1
+id: github
+name: "GitHub REST and GraphQL APIs"
+type: api
+status: example
+enabled: false
+base_url: "https://api.github.com"
+authentication:
+  source: environment
+  required_variables:
+    - GITHUB_TOKEN
+capabilities:
+    - repositories.read
+    - issues.read
+    - pull_requests.write
+security:
+  default_access: read-only
+  write_requires_approval: true
+  redact_secrets: true
+  retries_require_idempotency: true

package/templates/.agents/tools/api/google-ads/README.md

@@ -0,0 +1,23 @@
+# Google Ads API
+
+Exemplo API desabilitado para `google-ads`. Ele documenta descoberta e políticas; escolha e audite uma implementação real antes de ativar.
+
+Endpoint de referência: `https://googleads.googleapis.com`.
+
+## Capacidades
+
+- `campaigns.read`
+- `reports.read`
+- `campaigns.write`
+
+## Configuração
+
+1. Revise o manifest e limite as capacidades necessárias.
+2. Configure as variáveis fora do Git:
+
+- `GOOGLE_ADS_DEVELOPER_TOKEN`
+- `GOOGLE_ADS_CUSTOMER_ID`
+
+3. Teste em sandbox usando somente leitura.
+4. Registre aprovação antes de habilitar qualquer operação de escrita.
+5. Valide redaction, timeout, retry, rate limit e idempotência.

package/templates/.agents/tools/api/google-ads/manifest.yaml

@@ -0,0 +1,21 @@
+schema_version: 1
+id: google-ads
+name: "Google Ads API"
+type: api
+status: example
+enabled: false
+base_url: "https://googleads.googleapis.com"
+authentication:
+  source: environment
+  required_variables:
+    - GOOGLE_ADS_DEVELOPER_TOKEN
+    - GOOGLE_ADS_CUSTOMER_ID
+capabilities:
+    - campaigns.read
+    - reports.read
+    - campaigns.write
+security:
+  default_access: read-only
+  write_requires_approval: true
+  redact_secrets: true
+  retries_require_idempotency: true

package/templates/.agents/tools/api/google-analytics/README.md

@@ -0,0 +1,22 @@
+# Google Analytics Data API
+
+Exemplo API desabilitado para `google-analytics`. Ele documenta descoberta e políticas; escolha e audite uma implementação real antes de ativar.
+
+Endpoint de referência: `https://analyticsdata.googleapis.com`.
+
+## Capacidades
+
+- `metadata.read`
+- `reports.read`
+
+## Configuração
+
+1. Revise o manifest e limite as capacidades necessárias.
+2. Configure as variáveis fora do Git:
+
+- `GOOGLE_APPLICATION_CREDENTIALS`
+- `GA4_PROPERTY_ID`
+
+3. Teste em sandbox usando somente leitura.
+4. Registre aprovação antes de habilitar qualquer operação de escrita.
+5. Valide redaction, timeout, retry, rate limit e idempotência.

package/templates/.agents/tools/api/google-analytics/manifest.yaml

@@ -0,0 +1,20 @@
+schema_version: 1
+id: google-analytics
+name: "Google Analytics Data API"
+type: api
+status: example
+enabled: false
+base_url: "https://analyticsdata.googleapis.com"
+authentication:
+  source: environment
+  required_variables:
+    - GOOGLE_APPLICATION_CREDENTIALS
+    - GA4_PROPERTY_ID
+capabilities:
+    - metadata.read
+    - reports.read
+security:
+  default_access: read-only
+  write_requires_approval: true
+  redact_secrets: true
+  retries_require_idempotency: true

package/templates/.agents/tools/api/google-search-console/README.md

@@ -0,0 +1,21 @@
+# Google Search Console API
+
+Exemplo API desabilitado para `google-search-console`. Ele documenta descoberta e políticas; escolha e audite uma implementação real antes de ativar.
+
+Endpoint de referência: `https://searchconsole.googleapis.com`.
+
+## Capacidades
+
+- `sites.read`
+- `search_analytics.read`
+
+## Configuração
+
+1. Revise o manifest e limite as capacidades necessárias.
+2. Configure as variáveis fora do Git:
+
+- `GOOGLE_APPLICATION_CREDENTIALS`
+
+3. Teste em sandbox usando somente leitura.
+4. Registre aprovação antes de habilitar qualquer operação de escrita.
+5. Valide redaction, timeout, retry, rate limit e idempotência.

package/templates/.agents/tools/api/google-search-console/manifest.yaml

@@ -0,0 +1,19 @@
+schema_version: 1
+id: google-search-console
+name: "Google Search Console API"
+type: api
+status: example
+enabled: false
+base_url: "https://searchconsole.googleapis.com"
+authentication:
+  source: environment
+  required_variables:
+    - GOOGLE_APPLICATION_CREDENTIALS
+capabilities:
+    - sites.read
+    - search_analytics.read
+security:
+  default_access: read-only
+  write_requires_approval: true
+  redact_secrets: true
+  retries_require_idempotency: true

package/templates/.agents/tools/api/google-tag-manager/README.md

@@ -0,0 +1,22 @@
+# Google Tag Manager API
+
+Exemplo API desabilitado para `google-tag-manager`. Ele documenta descoberta e políticas; escolha e audite uma implementação real antes de ativar.
+
+Endpoint de referência: `https://tagmanager.googleapis.com`.
+
+## Capacidades
+
+- `containers.read`
+- `tags.read`
+- `versions.write`
+
+## Configuração
+
+1. Revise o manifest e limite as capacidades necessárias.
+2. Configure as variáveis fora do Git:
+
+- `GOOGLE_APPLICATION_CREDENTIALS`
+
+3. Teste em sandbox usando somente leitura.
+4. Registre aprovação antes de habilitar qualquer operação de escrita.
+5. Valide redaction, timeout, retry, rate limit e idempotência.