@zaip-ai/cli 2.0.0 → 2.2.0

package/templates/.agents/skills/zaip-skill-meta-token-onboarding/references/onboarding-manual.md

@@ -0,0 +1,96 @@
+# Teste simplificado: Graph API primeiro, MCP depois
+
+Este roteiro é para a pessoa testar os próprios ativos, sem virar Tech Provider. Ele não cria acesso a uma conta, não publica anúncios e não substitui as políticas atuais da Meta. Pense em três coisas: o **app** é o cadastro da integração, a **BM** é o portfólio empresarial que reúne ou compartilha contas de anúncio, e o **token** é uma chave temporária para a pessoa provar o próprio acesso.
+
+## O que a pessoa precisa preparar
+
+1. Abrir [Meta for Developers](https://developers.facebook.com/), escolher **Entrar** ou **Começar** e usar o próprio login Meta. Concluir as verificações que a tela solicitar.
+2. Abrir **Meus apps** e escolher **Criar app**. Dar um nome, seguir o caso de uso que o painel apresentar para Marketing API ou gerenciamento de anúncios e confirmar o próprio papel no app. O nome e o tipo disponíveis podem mudar; para este teste, o app é só o cadastro da integração e não exige programar ou publicar um software.
+3. Anotar o App ID; o App Secret continua privado.
+4. Confirmar que a própria pessoa tem um papel adequado no app e acesso aos ativos que pretende consultar. Não exija que ela seja administradora de todos os ativos. Para uma prova de leitura de ativos próprios, normalmente não é preciso concluir app review; isso não garante acesso a qualquer BM, conta ou recurso. A Meta pode exigir verificações específicas, aprovações e níveis de acesso conforme o caso.
+5. Abrir o [Graph API Explorer](https://developers.facebook.com/tools/explorer/). Escolher o app, **Token do usuário**, marcar `ads_read` e `business_management` e clicar em **Gerar token**, como no exemplo fornecido. Se o painel atual exigir as dependências `pages_read_engagement` e `pages_show_list`, marque-as para completar o consentimento. Se também for testar o ramo MCP bearer, selecione `ads_mcp_management` nesse momento. Caso adicione esse escopo depois, gere um novo token, conclua o consentimento e repita a troca; escopos não são acrescentados editando `.env`. O token temporário é uma credencial: não envie por chat, e-mail, issue, log ou captura de tela.
+
+`ads_read` permite as leituras de marketing descritas aqui. `business_management` permite descobrir os negócios que o usuário pode administrar. Alguns desses escopos também podem permitir operações de escrita em outros fluxos, mas este roteiro autoriza somente `GET` e ferramentas read-only. Escopos adicionais só devem ser solicitados se a resposta da Meta ou o painel atual mostrar que são necessários para um recurso específico.
+
+## Arquivo local e troca por token de longa duração
+
+O `.env` fica na raiz do repositório, deve estar ignorado pelo Git e só pode ser escrito após a pessoa pedir explicitamente essa ação. É uma persistência local, não um mecanismo automático do host.
+
+| Chave local | Valor que a pessoa preenche | Uso |
+| --- | --- | --- |
+| `META_APP_ID` | ID do app próprio | troca server-side |
+| `META_APP_SECRET` | segredo do mesmo app | troca server-side |
+| `META_GRAPH_API_VERSION` | versão Graph escolhida para o teste | endpoints Graph |
+| `META_GRAPH_ACCESS_TOKEN` | token de usuário temporário ou renovado | leituras Graph |
+
+Use a versão selecionada no painel, por exemplo `vNN.0`; não trate uma versão como universal. Um `.env` local terá somente placeholders neste guia:
+
+```dotenv
+META_APP_ID=PREENCHA_LOCALMENTE
+META_APP_SECRET=PREENCHA_LOCALMENTE
+META_GRAPH_API_VERSION=vNN.0
+META_GRAPH_ACCESS_TOKEN=PREENCHA_LOCALMENTE
+```
+
+Antes de gravar, valide que `.env` é ignorado e não rastreado com `git check-ignore .env` e `git ls-files --error-unmatch .env`; ambos os comandos tratam apenas o caminho, não o valor. Ao atualizar, preserve comentários e chaves não relacionadas.
+
+O App Secret fica em **App Settings > Basic > Show** no painel do app. Antes da troca, o agente autorizado valida o token temporário em `GET /me?fields=id,name`; uma resposta com `id` e `name` mostra quem foi autenticado. A troca é um `GET https://graph.facebook.com/{META_GRAPH_API_VERSION}/oauth/access_token` com os parâmetros `grant_type=fb_exchange_token`, `client_id`, `client_secret` e `fb_exchange_token`. O processo monta os valores somente em memória, usa HTTPS para `graph.facebook.com` e não imprime nem registra a URL completa, argumentos ou logs com credenciais. A troca usa token válido, App ID e App Secret do mesmo app. A Meta normalmente devolve um token de longa duração em torno de 60 dias, mas o retorno, a expiração e a elegibilidade pertencem à resposta atual da Meta. Se o token expirar, é preciso fazer novo login e gerar um novo token temporário; não há renovação infinita garantida.
+
+Após uma troca bem-sucedida, o agente valida de novo `GET /me` usando o token retornado e confirma o mesmo `id` antes de substituir `META_GRAPH_ACCESS_TOKEN` localmente. Quando disponível, também confere metadados redigidos em `debug_token` — `app_id`, `is_valid`, escopos e expiração. A atualização do `.env` é atômica, preserva comentários e chaves não relacionadas e interpreta dotenv como dados, sem `source` ou `eval`. Qualquer erro de escopo, validade, aplicação ou permissão deve ser comunicado sem copiar a credencial.
+
+## Prova de leitura da API
+
+Peça leituras apenas, com campos mínimos, `limit` moderado e paginação até o fim ou até um limite declarado.
+
+1. **Identidade.** `GET /me?fields=id,name`. Guarde apenas os valores de negócio necessários para a resposta; não o token.
+2. **BMs disponíveis.** `GET /me/businesses?fields=id,name`. A pessoa escolhe uma BM à qual tenha acesso. Para um cenário de teste mais representativo, escolha uma BM que tenha pelo menos um conjunto de anúncios ativo e válido; isso é uma verificação adicional do cenário, não requisito de autenticação.
+3. **Contas da BM.** Leia as duas relações, sempre paginando: `GET /BM_ID/owned_ad_accounts?fields=id,name,account_status` e `GET /BM_ID/client_ad_accounts?fields=id,name,account_status`. Una as listas e remova duplicatas pelo `id`. A pessoa escolhe uma conta cujo ID é `act_...`.
+4. **Campanhas.** `GET /act_ID/campaigns?fields=id,name,status,effective_status`, com `ads_read`. A resposta com dados ou uma lista vazia prova a leitura para a conta escolhida; uma lista vazia não significa falha de autorização. Para conferir o cenário de conjunto ativo, a leitura adicional filtra `adsets` por `effective_status=ACTIVE`. Esse status não comprova entrega, validade comercial ou performance e o roteiro nunca ativa anúncios.
+
+Registre para a pessoa somente: endpoint, data/hora, ID selecionado, número de páginas, resultado `dados`, `vazio`, `scope-insufficient` ou `erro`. Não coloque tokens, secrets, headers de autorização, URLs completas ou payloads brutos em evidência.
+
+## Prova da API e prova do MCP
+
+Uma resposta Graph API prova o token e os endpoints Graph; `ads_read` não valida sozinho o MCP. Ela não prova que um MCP foi instalado, autenticado ou autorizou a mesma conta. OAuth é o caminho padrão para o MCP oficial Meta Ads configurado por ZAIP. A metadata atual do recurso Meta Ads anuncia bearer header e inclui `ads_read`, `business_management`, `pages_show_list` e `ads_mcp_management` entre os scopes; isso permite testar o ramo bearer quando ele for explicitamente solicitado, mas não prova antecipadamente que um token de usuário será aceito.
+
+Se `tools/list` ou a documentação atual do MCP exigirem `ads_mcp_management`, peça esse escopo apenas no ramo de teste MCP e respeite suas dependências atuais no painel. Ele não substitui `ads_read` para a consulta Graph de campanhas nem autoriza escrita. O vídeo de operações de escrita citado pela Meta para App Review não é etapa deste tutorial.
+
+No ramo bearer explicitamente solicitado, confira primeiro o contrato de recurso atual em `https://mcp.facebook.com/ads`. Se ele continuar aceitando bearer e exigir `ads_mcp_management`, obtenha o escopo no token, respeitando dependências mostradas no painel. Há duas opções: configurar o host para mapear a variável local de token para `bearer_token_env_var`, sem gravar valor literal; ou usar um agente HTTP direto que mantenha a variável somente em memória. `.env` não é carregado automaticamente: o processo do host precisa receber a variável por um carregamento dotenv local e seguro. Em ambos os casos, envie POST para `initialize`, `notifications/initialized`, `tools/list` e `tools/call` de leitura; mantenha os headers de sessão e da versão de protocolo conforme a resposta do servidor. Chame uma ferramenta de leitura de campanhas para a mesma `act_ID` já escolhida. Não altere TOML ou configuração de host sem esse pedido explícito; se ele existir, a edição é permitida dentro desse escopo. Declare falha apenas pela resposta observada, nunca por suposição. OAuth continua disponível como o caminho padrão, sem forçar uma troca de volta.
+
+Para validar um MCP após configurá-lo, o agente deve: (1) obter `tools/list` e seus schemas; (2) executar uma ferramenta de leitura real; e (3) informar se recebeu dados, vazio, falta de escopo, política bloqueada ou erro de transporte. Descobrir ferramentas ou concluir OAuth não é leitura real. Para o MCP oficial, use `$zaip-skill-meta-ads-setup` e depois `$zaip-skill-meta-ads`.
+
+## Prompts copiáveis, sem segredo
+
+Após salvar as credenciais localmente, fora do chat, a pessoa pode pedir:
+
+> Use esta skill para verificar localmente se as chaves Meta necessárias existem no `.env` da raiz, sem mostrar valores. Valide `GET /me` antes de qualquer troca de token.
+
+> Com minha autorização para trocar o token, use `META_GRAPH_API_VERSION` e faça a troca local do token Graph temporário. Não mostre nem grave segredos em logs, URLs, argumentos, records ou evidências. Valide `/me` com o token retornado antes de atualizar o `.env`.
+
+> Faça somente leituras Graph paginadas: minhas BMs, as contas próprias e de cliente da BM que eu escolher e as campanhas da conta `act_...` que eu escolher. Não altere ativos; informe cobertura e qualquer limitação.
+
+> Com minha autorização para configurar e testar o ramo bearer MCP, confira o contrato atual, mapeie a variável local no host sem valor literal, recarregue, liste as tools e faça uma leitura de campanhas na mesma conta `act_...`. Não escreva nem declare falha sem uma resposta observada.
+
+## Sobre acesso permanente e a Zaip
+
+Este fluxo é intencionalmente temporário e adequado a um teste simples. Acesso duradouro, automação em produção e uso com terceiros dependem do produto Meta, do modelo de token, da revisão, das permissões e das políticas aplicáveis. Para cenários elegíveis, um system user pode ter token sem expiração conforme a documentação atual da Meta no Postman; ele continua revogável e não depende de uma parceria universal.
+
+A [Zaip](https://zaip.com.br/) se apresenta institucionalmente como Parceiro Oficial Tech Provider no contexto WhatsApp. Pode ajudar a estruturar soluções e conformidade com as políticas aplicáveis, sem afirmar auditoria independente, selo de Ads ou MCP, nem token permanente exclusivo de parceiro.
+
+## Referências oficiais e limite de política
+
+- [Meta: tokens de longa duração](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived/) — página verificada em 2026-09-06: troca server-side requer token válido, App ID e App Secret; token de usuário costuma durar cerca de 60 dias.
+- [Meta: autorização da Marketing API](https://developers.facebook.com/docs/marketing-api/overview/authorization/) — página verificada em 2026-09-06: testes de contas próprias têm limites e os níveis Limited e Full Access são avaliados pela Meta; não confunda com acesso garantido a todos os ativos.
+- [Meta Ads MCP: recurso OAuth protegido](https://mcp.facebook.com/.well-known/oauth-protected-resource/ads) — metadata verificada em 2026-09-06; suporta bearer header e anuncia scopes, mas não atesta a aceitação de um token específico.
+- [Meta: permissões](https://developers.facebook.com/docs/permissions/) — consulte para `ads_mcp_management` e dependências atuais antes do ramo bearer.
+- [Meta Graph API: negócios do usuário](https://developers.facebook.com/docs/graph-api/reference/user/businesses/), [contas próprias da BM](https://developers.facebook.com/docs/marketing-api/reference/business/owned_ad_accounts/), [contas de cliente da BM](https://developers.facebook.com/docs/marketing-api/reference/business/client_ad_accounts/) e [campanhas da conta](https://developers.facebook.com/docs/marketing-api/reference/ad-account/campaigns/) — referências das edges usadas nas leituras.
+- [Meta Postman: Facebook Marketing API](https://www.postman.com/meta/facebook-marketing-api/documentation/0zr4mes/facebook-marketing-api-mapi?entity=request-31691153-6b7e9445-1832-42ae-b40a-bdd1b831f714) — coleção direta da Meta sobre tokens de usuário e system user; consulte antes de afirmar elegibilidade ou expiração.
+- [Meta Graph API Explorer](https://developers.facebook.com/tools/explorer/) — a interface e as permissões disponíveis podem mudar; siga a tela atual da Meta.
+
+## Como concluir o teste
+
+- **API validada:** o novo token respondeu o mesmo `id` em `/me`, a BM e uma conta `act_...` foram selecionadas e a leitura de campanhas devolveu dados ou vazio legítimo.
+- **MCP validado:** depois de `initialize` ou reload, `tools/list` e uma ferramenta de leitura de campanhas para a mesma `act_ID` responderam de forma observável.
+- **Cenário ativo confirmado:** a leitura opcional de `adsets` encontrou um conjunto com status ativo e válido. Isso confirma o cenário de teste, não a autenticação.
+
+As políticas e os produtos Meta mudam. Quando a tela ou a resposta da API divergir deste guia, trate a fonte Meta atual como autoridade e reporte a divergência antes de ampliar permissões ou mudar o fluxo.

package/templates/.agents/skills/zaip-skill-release-qualification/SKILL.md

@@ -7,6 +7,10 @@ description: Qualify an exact ZAIP release candidate through source-template-pac
 
 Use before deciding whether a concrete candidate is ready. It does not publish.
 
+The only public npm package is `@zaip-ai/cli`; the installation entry point is
+`npx @zaip-ai/cli@latest init`. Verify that release automation, manifests, and
+registry checks target only this package before qualifying the next publication.
+
 1. Identify the exact candidate revision, version, and intended distribution surface.
    Do not substitute current working-tree checks for candidate evidence.
 2. Validate framework lock, source-to-public-template parity, generated artifacts,

package/templates/.agents/skills/zaip-skill-sales-methodology/SKILL.md

@@ -3,23 +3,13 @@ name: zaip-skill-sales-methodology
 description: Design evidence-backed sales processes, qualification playbooks, and configurable scripts. Use for internal sales-methodology work; not for external commercial acts or campaign production.
 ---
 
-# Metodologia comercial
+# Sales proporcional ao pedido
 
-## Localização canônica
+- Explique conceitos ou revise texto pontual diretamente quando houver contexto suficiente; uma pergunta sobre BANT não exige playbook completo.
+- SPIN é um banco adaptativo de perguntas; BANT registra evidências de Budget, Authority, Need e Timing. Preserve intenção, fatos e estágio demonstrado do comprador, sem pressão manipulativa.
+- Nunca invente urgência, autoridade, ROI, preço, prova ou dados. Hipóteses ficam rotuladas. Pergunte somente por lacuna material; resposta ausente não é aprovação.
+- Esta skill orienta trabalho interno. Contato com prospects, proposta, pagamento, preço/desconto, assinatura ou outro ato externo exige autorização específica vigente.
+- Para processo, qualificação, negociação, roteiro por etapa ou entrega persistente, carregue [o fluxo progressivo](references/extended-workflow.md), com SPIN/BANT, handoffs e limites. Artefatos vivem em `.agents/sales/`; `playbook.md` centraliza o processo.
+- Campanha pertence a Marketing; estratégia empresarial/RevOps a Growth; decisão de marca a Branding; dados e políticas aos respectivos especialistas.
 
-Salve processos comerciais, playbooks, scripts internos, matrizes de objeções e materiais de enablement em `.agents/sales/`. Não salve esses artefatos em `docs/`, na raiz do repositório ou em diretórios de brand, marketing ou growth.
-
-O arquivo central da área é `.agents/sales/playbook.md`; atualize-o quando uma decisão mudar o processo comercial, qualificação, handoff ou narrativa sales-facing. Materiais específicos podem ser arquivos adicionais na mesma pasta.
-
-## Descoberta e entrega progressivas
-
-1. Comece pelas referências acessíveis fornecidas — texto, site, PDF, PPT, planilha, arquivo ou imagem — e registre fonte, locator e classificação: fato, decisão aprovada, hipótese, dado ou lacuna. Preserve o que já foi aprovado e não recrie nem duplique o playbook central.
-2. Se o trabalho começar do zero ou o contexto for insuficiente, faça no máximo cinco perguntas críticas por turno, por até três turnos. Pergunte somente por lacunas materiais: ICP, oferta, processo, persona, canal, origem, etapa, autoridade ou compliance. Espere as respostas antes de avançar nas partes que delas dependem; silêncio não é resposta nem aprovação. Após três turnos, marque lacunas e use somente hipóteses delegáveis, sem fabricar consciência, urgência, prova, ROI, preço, dados ou autoridade.
-3. Pedido pontual com contexto suficiente deve ser executado diretamente, sem questionário obrigatório nem playbook completo.
-4. Aplique somente as partes necessárias ao escopo solicitado: `ICP, oferta e processo` → `etapas e handoff` → `roteiro por etapa` → `playbook completo`. Identifique o material em construção e consolide em `.agents/sales/playbook.md` somente quando houver contexto suficiente para mudar processo, qualificação, handoff ou narrativa sales-facing. Materiais específicos ficam em arquivos complementares sem repetir a fonte central, sem exigir todos os módulos ou formatos.
-5. Desenhe cada etapa com objetivo, dono, entrada, abertura, perguntas, evidência, campos SPIN/BANT, transição, objeções, prova autorizada, microcompromisso, saída, CRM, handoff/SLA e próximo passo. Inclua caminhos de `not-qualified`, `nurture` e `no-decision`.
-6. Use as três etapas ZAIP: descoberta/pré-qualificação (tipicamente SDR), alinhamento/qualificação com handoff definido para closer, e fechamento/negociação pelo closer. O preço só pode ser apresentado como aprovado; proposta e contrato seguem o handoff autorizado.
-7. Aplique SPIN como banco adaptativo de Situation, Problem, Implication e Need-payoff, nunca como interrogatório ou ordem rígida. Use BANT como campos e gates de evidência (Budget, Authority, Need, Timing), nunca para pressionar ou desqualificar de forma manipulativa.
-8. Adapte narrativa, perguntas e CTA a unaware, problem-aware, solution-aware, product-aware e most-aware somente quando houver evidência do estágio. Use o roteiro genérico de qualificação curta e a estrutura de fechamento em [referência de processo](references/sales-process-framework.md).
-9. Aaron somente desenha ou melhora processo, playbook e script internos. Não contata prospects, envia proposta ou link de pagamento, altera preço/desconto, assina contrato nem executa ato comercial externo ou vinculante sem autoridade explícita.
-10. Encaminhe estratégia Growth/RevOps, estratégia empresarial e economia end-to-end para Robert; campanha e copy de aquisição para Lúcia; marca e tom ainda não decididos para Sarah; dados e métodos quantitativos para Gabi; políticas ou limites legais para Renata; e produção documental genérica para Clara. Sales-facing scripts e enablement pertencem a Aaron; copy de campanha pertence a Lúcia.
+Uma interaction read-only não materializa Task/Change. Entrega persistente segue lifecycle, Requirements/AC e assurance proporcionais; só trabalho técnico carrega engenharia.

package/templates/.agents/skills/zaip-skill-sales-methodology/references/extended-workflow.md

@@ -0,0 +1,20 @@
+# Metodologia comercial
+
+## Localização canônica
+
+Salve processos comerciais, playbooks, scripts internos, matrizes de objeções e materiais de enablement em `.agents/sales/`. Não salve esses artefatos em `docs/`, na raiz do repositório ou em diretórios de brand, marketing ou growth.
+
+O arquivo central da área é `.agents/sales/playbook.md`; atualize-o quando uma decisão mudar o processo comercial, qualificação, handoff ou narrativa sales-facing. Materiais específicos podem ser arquivos adicionais na mesma pasta.
+
+## Descoberta e entrega progressivas
+
+1. Comece pelas referências acessíveis fornecidas — texto, site, PDF, PPT, planilha, arquivo ou imagem — e registre fonte, locator e classificação: fato, decisão aprovada, hipótese, dado ou lacuna. Preserve o que já foi aprovado e não recrie nem duplique o playbook central.
+2. Se o trabalho começar do zero ou o contexto for insuficiente, faça no máximo cinco perguntas críticas por turno, por até três turnos. Pergunte somente por lacunas materiais: ICP, oferta, processo, persona, canal, origem, etapa, autoridade ou compliance. Espere as respostas antes de avançar nas partes que delas dependem; silêncio não é resposta nem aprovação. Após três turnos, marque lacunas e use somente hipóteses delegáveis, sem fabricar consciência, urgência, prova, ROI, preço, dados ou autoridade.
+3. Pedido pontual com contexto suficiente deve ser executado diretamente, sem questionário obrigatório nem playbook completo.
+4. Aplique somente as partes necessárias ao escopo solicitado: `ICP, oferta e processo` → `etapas e handoff` → `roteiro por etapa` → `playbook completo`. Identifique o material em construção e consolide em `.agents/sales/playbook.md` somente quando houver contexto suficiente para mudar processo, qualificação, handoff ou narrativa sales-facing. Materiais específicos ficam em arquivos complementares sem repetir a fonte central, sem exigir todos os módulos ou formatos.
+5. Desenhe cada etapa com objetivo, dono, entrada, abertura, perguntas, evidência, campos SPIN/BANT, transição, objeções, prova autorizada, microcompromisso, saída, CRM, handoff/SLA e próximo passo. Inclua caminhos de `not-qualified`, `nurture` e `no-decision`.
+6. Use as três etapas ZAIP: descoberta/pré-qualificação (tipicamente SDR), alinhamento/qualificação com handoff definido para closer, e fechamento/negociação pelo closer. O preço só pode ser apresentado como aprovado; proposta e contrato seguem o handoff autorizado.
+7. Aplique SPIN como banco adaptativo de Situation, Problem, Implication e Need-payoff, nunca como interrogatório ou ordem rígida. Use BANT como campos e gates de evidência (Budget, Authority, Need, Timing), nunca para pressionar ou desqualificar de forma manipulativa.
+8. Adapte narrativa, perguntas e CTA a unaware, problem-aware, solution-aware, product-aware e most-aware somente quando houver evidência do estágio. Use o roteiro genérico de qualificação curta e a estrutura de fechamento em [referência de processo](sales-process-framework.md).
+9. Aaron somente desenha ou melhora processo, playbook e script internos. Não contata prospects, envia proposta ou link de pagamento, altera preço/desconto, assina contrato nem executa ato comercial externo ou vinculante sem autoridade explícita.
+10. Encaminhe estratégia Growth/RevOps, estratégia empresarial e economia end-to-end para Robert; campanha e copy de aquisição para Lúcia; marca e tom ainda não decididos para Sarah; dados e métodos quantitativos para Gabi; políticas ou limites legais para Renata; e produção documental genérica para Clara. Sales-facing scripts e enablement pertencem a Aaron; copy de campanha pertence a Lúcia.

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

@@ -5,6 +5,9 @@ description: Install, diagnose, migrate, upgrade, or roll back ZAIP configuratio
 
 # Configurar ZAIP-AIOS
 
+Use somente o pacote público `@zaip-ai/cli`: `npx @zaip-ai/cli@latest init`.
+Para escolher o perfil, acrescente `--profile full|dev-lite|lite` ao comando `init`.
+
 For the isolated SQLite dashboard, also discover and use `$zaip-skill-sqlite-read-model`.
 The setup must verify Node.js 22+, install the LTS release with `winget` when the user has
 authorized automatic prerequisite installation, and create the disposable database only from

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

@@ -19,7 +19,7 @@ description: Detect, prevent, and fix UTF-8, mojibake, and malformed text in ZAI
 - `.agents/requirements`
 - `.agents/skills`
 - `docs`
-- `plan-create-zaip-aios`
+- `public-cli`
 
 ## Notes
 

package/templates/.agents/zaip-aios/INDEX.md

@@ -29,7 +29,7 @@ introduzidos em releases mais novas.
 | Consultar instalação detalhada | [20 — Instalação detalhada](guides/20-instalacao-detalhada.md) |
 | Consultar telemetria do Monitor | [21 — Telemetria do Monitor de Custos](guides/21-telemetria-monitor-custos.md) |
 | Entender fluxos e roteamento | [22 — Fluxos e roteamento](guides/22-fluxos-e-roteamento.md) |
-| Consultar a política de modelos | [23 — Orquestração de modelos](guides/23-orquestracao-de-modelos.md) |
+| Escolher modelos e limitar o diagnóstico Astra | [23 — Orquestração de modelos](guides/23-orquestracao-de-modelos.md) |
 | Entender cálculo e fontes de custo | [24 — Cálculo](guides/24-calculo-de-custos-openai.md) e [25 — Fontes](guides/25-fontes-de-precos-openai.md) |
 | Consultar qualidade e release | [26 — Qualidade e release](guides/26-qualidade-e-release.md) |
 | Entender a telemetria Git-native | [27 — Telemetria Git-native](guides/27-telemetria-git-native.md) |

package/templates/.agents/zaip-aios/README.md

@@ -39,11 +39,17 @@ presença de uma instrução ou screenshot não comprova execução naquele ambi
 - Use o guia 09 para delegacao entre os 23 agentes e 6 squads registrados.
 - Use o guia 16 para entender status, reconciliacao e a ordem de finalizacao.
 - Use os guias 17 e 24 a 25 para interpretar tokens, precificacao e conversao de moeda.
+- Use o [guia 08](guides/08-contexto-e-tokens.md) para consultas com contexto enxuto e
+  o [guia 23](guides/23-orquestracao-de-modelos.md) para a divisão Luna/Terra/Sol e o
+  diagnóstico Astra em `high`, limitado a três invocações por tarefa.
 - Use os guias 18 a 28 quando precisar do contrato completo de agentes, lifecycle, telemetria, qualidade, instalacao ou roteamento.
 
 O instalador npm projeta esta pasta da `.agents` canonica para o tarball e a
 recria no projeto consumidor. Arquivos em `public-cli/packages/cli/templates`
 sao artefatos gerados do empacotamento, nao uma segunda fonte a ser editada.
+Os manuais completos em português e inglês são instalados como
+`.agents/README.md` e `.agents/README-ENG.md`; os READMEs da raiz do consumidor
+permanecem sob sua autoria.
 
 Para concluir trabalho, use [revisão e validação](guides/07-revisao-e-validacao.md)
 e o [contrato de prova observável](../skills/zaip-skill-change/references/observable-evidence.md).

package/templates/.agents/zaip-aios/guides/08-contexto-e-tokens.md

@@ -2,9 +2,25 @@
 
 1. Comece por `project.yaml`, `core.md` e pelos manifests de `.agents/records/lifecycle/`.
 2. Carregue somente a Rule, Requirement ou skill acionada.
-3. Prefira indices, resumos e busca direcionada a arquivos completos.
+3. Prefira índices, resumos e busca direcionada a arquivos completos.
 4. Abra records apenas por lifecycle ID conhecido.
-5. Resuma fatos estaveis; preserve texto literal apenas quando normativo.
-6. Remova do contexto resultados superados e detalhes nao acionaveis.
+5. Resuma fatos estáveis; preserve texto literal apenas quando normativo.
+6. Remova do contexto resultados superados e detalhes não acionáveis.
 
 Para tools, leia `catalog.yaml`, escolha um ID e abra somente seu manifesto.
+
+## Consulta simples e diagnóstico difícil
+
+Uma pergunta simples de Marketing, Sales, Growth ou Ops recebe o contexto do domínio
+necessário à resposta. Não cria Task/Change artificial nem carrega instruções de
+engenharia ou diagnóstico Astra apenas por mencionar um departamento.
+
+O [guia 23](23-orquestracao-de-modelos.md) define a escalada excepcional. A
+[Rule Astra](../../rules/astra-diagnostic.md) só é carregada ao avaliar elegibilidade:
+prova da falha, dificuldade estruturada e, no caso preventivo, impacto crítico comprovado.
+A consulta diagnóstica usa contexto novo e delimitado, sem histórico integral ou ferramentas;
+o executor recebe a rota corrigida e preserva os critérios de aceite originais.
+
+Menos texto de prompt não comprova menor custo total. Compare tokens, tempo, reparos e
+custo por tarefa aceita; mantenha separado o custo de uma pergunta simples. Consumo
+ausente permanece indisponível. Veja [observabilidade e custos](11-observabilidade-e-custos.md).

package/templates/.agents/zaip-aios/guides/12-instalacao-e-upgrade.md

@@ -1,10 +1,40 @@
-# Instalacao e upgrade
+# Instalação e upgrade
 
-1. Verifique versao atual e estado limpo ou conscientemente preservado.
-2. Execute doctor/integrity antes da mudanca.
-3. Faça dry-run da instalacao, migracao ou upgrade.
-4. Revise arquivos gerenciados, publicos e preservados.
+1. Verifique versão atual e estado limpo ou conscientemente preservado.
+2. Execute doctor/integrity antes da mudança.
+3. Faça dry-run da instalação, migração ou upgrade.
+4. Revise arquivos gerenciados, públicos e preservados.
 5. Aplique, valide adapters e rode gates.
-6. Teste rollback e confirme a versao final.
+6. Teste rollback e confirme a versão final.
 
-`framework.lock.yaml` e relevante neste fluxo; nao o carregue no trabalho comum.
+`framework.lock.yaml` é relevante neste fluxo; não o carregue no trabalho comum.
+
+## Atualizar pelo pacote público
+
+Na raiz do projeto consumidor:
+
+```bash
+npx @zaip-ai/cli@latest init --dry-run
+npx @zaip-ai/cli@latest init
+npx @zaip-ai/cli@latest doctor --json
+node .agents/runtime/bin/zaip.mjs doctor --json
+```
+
+O primeiro doctor verifica a instalação; o segundo verifica o runtime distribuído.
+Leia o plano antes de autorizar uma substituição com `--force --yes`. O upgrade
+preserva o perfil de instalação salvo e as escolhas do projeto.
+
+Os manuais instalados ficam em `.agents/README.md` (português) e
+`.agents/README-ENG.md` (inglês), com navegação em [INDEX.md](../INDEX.md).
+Os READMEs da raiz pertencem ao projeto consumidor e são preservados.
+As versões geradas em `public-cli/packages/cli/templates` vêm das fontes canônicas.
+
+Novas instalações mantêm seleção de modelo em `manual`. Instalar ou atualizar
+não ativa Astra automaticamente. O opt-in `auto` aplica-se a SPEC/PRD e a allowlist
+Astra habilita somente diagnóstico `high`, limitado e evidenciado, conforme o
+[guia 23](23-orquestracao-de-modelos.md). Conversas e Tasks avulsas preservam a seleção do host.
+
+`@latest` entrega o que está publicado no npm. Uma atualização local das fontes ou
+um pacote validado localmente só chegará a esse comando após publicação.
+Consulte [instalação detalhada](20-instalacao-detalhada.md) e
+[qualificação do pacote](26-qualidade-e-release.md).

package/templates/.agents/zaip-aios/guides/20-instalacao-detalhada.md

@@ -4,7 +4,7 @@ Este guia descreve o modelo de lifecycle V2 no layout V3. Durante a transição,
 
 ## Pré-requisitos
 
-- Node.js compatível com o pacote (declara 22+); para Dashboard, confirme `node:sqlite` disponível, como no ambiente de referência 22.16.0;
+- Node.js 22.16.0 ou superior, conforme o requisito do pacote, com `node:sqlite` disponível;
 - Git;
 - permissões de escrita no repositório consumidor.
 
@@ -28,6 +28,19 @@ instalador; nos exemplos de lifecycle deste guia, `zaip ...` é uma abreviação
 de `node .agents/runtime/bin/zaip.mjs ...` no projeto consumidor. Use o caminho
 explícito para evitar colisão entre os dois CLIs.
 
+### Manuais e seleção de modelos
+
+Antes de usar os comandos de desenvolvimento abaixo, consulte os manuais instalados
+em `.agents/README.md` e `.agents/README-ENG.md` e o [índice local](../INDEX.md).
+O instalador preserva os READMEs do projeto na raiz. Os perfis `full`, `dev-lite`
+e `lite` selecionam ferramentas de instalação; eles não classificam a dificuldade
+de uma tarefa nem ativam um modelo mais caro.
+
+O default de seleção de modelos é `manual`. O modo `auto` exige opt-in do projeto,
+permanece restrito a SPEC/PRD e mantém Astra como consultor diagnóstico opcional em
+`high`, com teto de três invocações por Task e devolução aos executores.
+Veja o [contrato de modelos e seus limites](23-orquestracao-de-modelos.md).
+
 ## Construir o CLI
 
 Somente no repositório-fonte, para manutenção do framework:

package/templates/.agents/zaip-aios/guides/23-orquestracao-de-modelos.md

@@ -11,7 +11,7 @@ Este guia define como o ZAIP-AIOS recomenda modelo, `reasoning effort` e velocid
 
 Na implementação atual, a política suporta `manual`, `off` e `auto`. No projeto ZAIP-AIOS, `auto` está ativado somente para Executions originadas por SPEC ou PRD; Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex. `manual` continua disponível para rollback e permanece o default de novas instalações.
 
-Toda Execution originada por PRD ou SPEC solicita velocidade `standard`, sem exceção ou override para Fast. A única forma suportada de executar trabalho de produto mais rápido é iniciar uma Task-first realmente independente e selecionar Fast manualmente no Codex; o ZAIP não ativa, persiste nem herda essa velocidade.
+Na política automática, Executions originadas por PRD ou SPEC solicitam velocidade `standard`, sem override para Fast. Em Conversation ou Task-first independente, a seleção de Fast pertence ao host/Codex; o ZAIP não a ativa, persiste nem herda. Velocidade do provider, paralelismo e tempo total até a tarefa aceita são medidas distintas.
 
 ## Estado atual
 
@@ -74,13 +74,14 @@ Para permitir escolha manual em Conversation e Task-first, não fixe `model`, `m
 
 ## Família de modelos
 
-A política automática deve permanecer inicialmente na família GPT-5.6:
+A política preserva GPT-5.6 para execução e acrescenta Astra somente para diagnóstico difícil evidenciado:
 
 | Modelo | Uso preferencial |
 | --- | --- |
 | `gpt-5.6-luna` | trabalho claro, repetitivo, determinístico e de alto volume |
 | `gpt-5.6-terra` | implementação, teste, diagnóstico e integração cotidiana |
 | `gpt-5.6-sol` | trabalho ambíguo, transversal, arquitetural, crítico ou de alto valor |
+| `gpt-6-astra` | diagnóstico excepcional, somente `high`, seguido de devolução ao executor |
 
 Os defaults iniciais ficam definidos assim:
 
@@ -91,6 +92,7 @@ Os defaults iniciais ficam definidos assim:
 | velocidade fallback/baseline | `standard` |
 | modelo eficiente elegível | `gpt-5.6-luna` |
 | modelo frontier elegível | `gpt-5.6-sol` |
+| consultor diagnóstico excepcional | `gpt-6-astra high`; até três diagnósticos por Task |
 | teto automático de effort | `xhigh` |
 | `xhigh` automático | habilitado somente pelos critérios de elegibilidade |
 | `max` e `Ultra` automáticos | fora de escopo |
@@ -98,7 +100,34 @@ Os defaults iniciais ficam definidos assim:
 
 Terra `medium` é o fallback quando os sinais forem insuficientes ou conflitantes. Sol não deve ser usado em tudo; Luna não deve ser usado quando a Task depende de julgamento arquitetural ou ambiguidade relevante.
 
-`ultra` e `max` não fazem parte da política: o ZAIP-AIOS nunca os seleciona. A seleção usa somente Luna, Terra ou Sol com effort `low`, `medium`, `high` ou `xhigh`.
+`ultra` e `max` não fazem parte da política: o ZAIP-AIOS nunca os seleciona. Luna, Terra e Sol usam effort `low`, `medium`, `high` ou `xhigh` conforme elegibilidade. Astra usa somente `high`; nem um override libera `xhigh`, `max` ou `ultra` para ele.
+
+### Astra: diagnóstico, correção de rota e devolução
+
+Sol permanece como escolha normal da faixa difícil. Astra recebe uma questão diagnóstica delimitada quando o ganho potencial de evitar novo reparo justifica seu uso. A regra canônica é [RULE-ASTRA-DIAGNOSTIC](../../rules/astra-diagnostic.md), carregada apenas nessa avaliação; o kernel e os prompts de Marketing, Sales, Growth e Ops não incorporam essa expansão.
+
+| Situação observada | Rota |
+| --- | --- |
+| Pergunta direta, copy, análise comercial simples, alteração mecânica | Luna/Terra conforme perfil existente |
+| Arquitetura ou problema difícil com caminho conhecido | Sol; execução delimitada em Luna/Terra |
+| Tentativa executora falhou por hipótese/raciocínio; complexidade ou ambiguidade alta e evidência disponível | Um diagnóstico Astra high antes do reparo seguinte |
+| Impacto material crítico e diagnóstico difícil, ambos evidenciados | Astra high preventivamente, antes da primeira implementação |
+| Falha de ambiente, credencial, ferramenta, sintaxe ou ausência de prova | Corrigir a condição ou obter prova com o executor; não acionar Astra |
+| Mesmo diagnóstico/plano sem progresso, ou três diagnósticos já reservados | Parar a escalada; executar rota útil ou registrar bloqueio concreto |
+
+A expressão “tarefa crítica”, o risco isolado, o departamento, a quantidade de arquivos e o tamanho do pedido nunca bastam. A política usa metadados estruturados e prova referenciada. Um reparo localizado não se torna diagnóstico difícil só porque a primeira tentativa falhou.
+
+Cada ciclo significa **uma invocação diagnóstica Astra governada**, com reserva atômica antes do dispatch. O teto é três por ID estável de Task, somando retomadas, Runs e Executions; normalmente basta uma consulta. Uma reserva consumida não permite repetir o dispatch nem é devolvida após timeout. Call interna, evento de uso e checkpoint não são contadores de diagnóstico.
+
+O pacote de entrada contém falha observada, tentativa anterior, evidência, restrições e critérios de aceite. É uma sessão nova, sem herdar histórico integral, sem ferramentas de execução nem filhos. O envelope limita a entrada serializada a 48000 bytes, declara até 8000 tokens de saída e termina após até 180 segundos. Bytes não equivalem a tokens; o runtime verifica o consumo informado pelo provider, sem transformar orçamento declarado em economia medida.
+
+Astra retorna JSON com `findings`, `evidence`, `cause_or_hypothesis`, `route`, `scope`, `test_plan`, `executor` e `recommended_model` restrito a Luna/Terra/Sol. O coordenador valida o retorno e entrega a correção ao executor. Astra não implementa, não substitui a revisão normal e não finaliza a entrega.
+
+O objetivo da segunda tentativa é aplicar uma hipótese corrigida e testável. Outra consulta precisa de evidência nova e mudança de hipótese/rota; não se permite repetir o mesmo plano alternando Astra e Sol. Se faltar prova para avançar, o retorno identifica a prova faltante, sem prometer resolução automática.
+
+A política `model-orchestration-v2` mantém legível a configuração anterior com três modelos. Incluir Astra na allowlist habilita apenas essa rota condicionada; removê-lo desativa novos diagnósticos preservando histórico e quota. Novas instalações continuam em `manual`. O modo automático permanece restrito a SPEC/PRD. O framework controla processos que ele próprio despacha; não consegue alterar ou limitar uma sessão manual já selecionada no aplicativo Codex.
+
+O isolamento é aplicado pelo adapter Codex antes da inferência: configuração transitória, sandbox de leitura, ferramentas de shell/apps/browser/multi-agent desabilitadas e cada servidor MCP efetivo desabilitado individualmente. Se a configuração não puder ser verificada, o diagnóstico não inicia. Um evento inesperado de ferramenta provoca cancelamento adicional; essa verificação posterior não substitui a restrição anterior.
 
 ## Reasoning effort
 

package/templates/.agents/zaip-aios/guides/26-qualidade-e-release.md

@@ -50,6 +50,27 @@ sincronize/audite novamente o template público. Execute gates geradores em
 checkout/worktree isolado para preservar trabalho concorrente. Gates locais,
 artefato exato, CI terminal e produção continuam sendo provas distintas.
 
+### Paridade de documentação no pacote npm
+
+Atualize primeiro `README.md` e `README-ENG.md` do repositório-fonte, mantendo
+português como principal e equivalência de seções, tabelas, exemplos e links.
+Atualize também os guias afetados, seu índice e os READMEs do CLI público.
+Sincronize o manifesto de integridade e o template por seus geradores oficiais.
+
+O `pack:check` de `public-cli` instala o TGZ real em um consumidor temporário:
+confere os hashes dos dois manuais, dos índices e de todos os arquivos do handbook
+contra o manifest do próprio pacote, incluindo a Rule Astra, e verifica que
+os READMEs da raiz do consumidor sobrevivem à instalação e à reinstalação.
+O relatório registra a quantidade de arquivos documentais conferidos.
+
+Novas instalações continuam em `manual`; a documentação não deve confundir
+perfil de instalação com modelo/effort nem apresentar estimativas de tokens
+como economia financeira medida. O escopo automático e os limites Astra
+devem coincidir com o [guia 23](23-orquestracao-de-modelos.md).
+
+Esses checks comprovam paridade local do candidato. Publicação npm, a tag
+`latest`, CI remoto e economia em tarefas reais precisam de suas próprias evidências.
+
 ### Falhas de desempenho no dashboard
 
 Reproduza a rota, período, filtro, offset e tamanho da página que falharam.