@zaip-ai/cli 1.0.7 → 1.0.8

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

@@ -1,13 +1,42 @@
 # ZAIP-AIOS Handbook
 
-Documentacao operacional local do ZAIP-AIOS para pessoas e agentes.
+Este handbook e a camada operacional instalada junto do ZAIP-AIOS. Ele ajuda
+pessoas e agentes a localizar o procedimento certo sem carregar todo o
+framework no contexto. O contrato executavel continua nos arquivos canonicos
+em `.agents/config/`, `.agents/rules/`, `.agents/requirements/` e
+`.agents/skills/`.
 
-## Leitura eficiente
+## O que esta pasta contem
 
-1. Leia primeiro apenas `INDEX.md`.
-2. Abra somente o guia relacionado ao trabalho atual.
-3. Para integracoes, consulte `.agents/tools/catalog.yaml` e depois um unico manifesto.
-4. Nao carregue toda esta pasta no contexto.
+- `INDEX.md`: roteador de baixo custo para os guias.
+- `guides/`: explicacoes curtas para instalacao, lifecycle, agentes, custos,
+  seguranca, contexto e ferramentas.
+- `VERSION`: versao do handbook distribuido pelo instalador.
 
-`VERSION` informa a versao do handbook instalada. As regras canonicas continuam em
-`.agents/rules/`; este handbook explica como aplica-las, mas nao as substitui.
+O handbook nao substitui Rules, Requirements, Skills nem records do lifecycle.
+Quando houver conflito, prevalece a configuracao do projeto e a regra aplicavel.
+
+## Como consultar sem desperdiçar contexto
+
+1. Leia primeiro `INDEX.md` e escolha um unico guia pelo objetivo atual.
+2. Leia `.agents/config/project.yaml` antes de executar trabalho: ele define se
+   ZAIP esta ativo, a stack e os clientes habilitados.
+3. Para trabalho persistente, carregue `.agents/rules/core.md` e somente as
+   Rules, Requirements e Skills relacionadas ao escopo.
+4. Para MCPs e integracoes, abra `.agents/tools/catalog.yaml` e depois apenas o
+   manifesto da ferramenta escolhida.
+5. Leia records de lifecycle apenas por ID explicito; historico geral nao e
+   contexto de descoberta.
+
+## Mapa rapido
+
+- Comece pelo guia 01 para a primeira instalacao e pelo 12 para upgrade ou
+  rollback.
+- Use os guias 03 a 06 para Tasks, SPECs, PRDs e execucao com evidencias.
+- 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 o guia 17 para interpretar tokens, precificacao e conversao de moeda.
+
+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.

package/templates/.agents/zaip-aios/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.8

package/templates/.agents/zaip-aios/guides/09-agentes-e-squads.md

@@ -1,8 +1,45 @@
 # Agentes e squads
 
-1. Delegue apenas subtarefas concretas e independentes.
-2. Dê a cada agente objetivo, limites, entradas e formato de saida.
-3. Evite dois agentes editando os mesmos arquivos.
-4. Centralize decisoes arquiteturais e integracao no agente responsavel.
-5. Exija evidencias, nao apenas declaracoes de conclusao.
-6. Use paralelismo somente quando reduzir caminho critico sem aumentar conflito.
+O catalogo em `.agents/config/agents/catalog.yaml` e a fonte canonica para
+delegacao. Ele registra 23 agentes e 6 squads. Nomes exibidos, perfis e
+capacidades podem mudar; antes de delegar, consulte o registro atual em vez de
+memorizar uma lista ou inventar uma identidade.
+
+## Como escolher
+
+1. Quebre o trabalho em subtarefas concretas, independentes e verificaveis.
+2. Escolha pelo conjunto de `capabilities`, `execution_eligibility`, ferramentas
+   e `write_scopes` do catalogo, nao apenas pelo titulo do agente.
+3. Use apenas o `codex_name` e o `codex_task_name` exatos do registro. Nao use
+   `default`, `worker`, `explorer` ou nomes ad-hoc.
+4. Defina objetivo, escopo de escrita, entradas, criterio de aceite e formato de
+   retorno antes da delegacao.
+5. Nao atribua a dois agentes arquivos ou responsabilidades que conflitem.
+
+## Squads
+
+As seis squads coordenam contextos recorrentes: entrega critica, analise de
+produto, design e website, marca e marketing, growth e RevOps, e vendas e
+governanca. A squad e um roteador de capacidade; a delegacao continua usando o
+agente catalogado que satisfaz o trabalho concreto.
+
+## Execucao e fechamento
+
+Uma Execution de delivery precisa de ao menos um executor elegivel. O
+orquestrador coordena a DAG, preserva a separacao de telemetria entre raiz e
+Sub-Runs e captura metadados observados apos spawn e termino. Reviewer,
+auditor ou integrador so entram quando sua capacidade for necessaria.
+
+O ultimo filho e sempre `zaip-agent-finalizer`, depois que os demais
+descendentes terminaram. Ele nao reescreve evidencia: aplica uma decisao
+restrita baseada em testes, diffs e registros reais. O resultado so deve ser
+reportado apos a barreira de finalizacao estar satisfeita.
+
+## Boas praticas
+
+- Centralize decisoes arquiteturais e integracao no responsavel adequado.
+- Exija caminhos de evidencia e resultados de comandos, nao declaracoes de
+  conclusao.
+- Use paralelismo apenas quando reduzir o caminho critico sem elevar conflito.
+- Escale bloqueios de autoridade, credencial, seguranca ou escopo; nao suponha
+  permissao externa.

package/templates/.agents/zaip-aios/guides/10-seguranca.md

@@ -6,13 +6,21 @@ O ZAIP-AIOS oferece dois perfis atuais:
 
 | Perfil | Filesystem nativo | Rede de comandos | Uso recomendado |
 | --- | --- | --- | --- |
-| `zaip-aios-security` | Escrita na raiz física do repositório, incluindo `.git`, `.agents`, `.codex` e demais arquivos ocultos | Limitada a `github.com` | Trabalho normal e princípio de menor privilégio, incluindo deploy GitHub autorizado |
-| `zaip-aios-full-access` | Escrita em `C:\` inteiro no Windows, quando as permissões do sistema permitirem | Completa, todos os domínios | Correção de configuração, diagnóstico ou operação que realmente exija acesso fora do workspace |
+| `zaip-aios-full-access` | Escrita em `C:\` inteiro no Windows, quando as permissões do sistema permitirem | Completa, todos os domínios | Default humano; evita prompt técnico do Codex para comandos, mas não cria autoridade para ações externas, destrutivas ou de publicação |
+| `zaip-aios-security` | Escrita na raiz física do repositório, incluindo `.git`, `.agents`, `.codex` e demais arquivos ocultos | Limitada a `github.com` | Opt-in de menor privilégio; reinicie o Codex após selecionar |
 
 A permissão nativa determina o que o processo tecnicamente consegue alcançar. Ela não
 substitui autorização do usuário, regras do repositório, hooks, skills ou controles do
 sistema operacional.
 
+`approval_policy = "never"` remove a confirmação técnica prévia do Codex para a
+execução de comandos dentro do perfil. Isso não é uma autorização de negócio ou
+de escopo: deploy, push/publicação, ações remotas, gastos, exclusões relevantes
+e mudanças fora do objetivo continuam exigindo pedido explícito do usuário no
+turno atual. Apps e MCPs podem manter seu próprio
+`default_tools_approval_mode = "approve"`; esse ajuste é independente da
+política de aprovação de comandos.
+
 ## `zaip-aios-security`
 
 ### Acesso concedido
@@ -70,7 +78,11 @@ pelo sandbox nativo:
 - o impacto máximo de uma edição comum fica contido no repositório;
 - todas as camadas ZAIP descritas abaixo continuam ativas.
 
-Esse perfil deve ser o padrão para desenvolvimento, revisão, testes, manutenção normal e deploy GitHub autorizado quando a escrita na identidade SSH local for necessária. A escrita em `~/.ssh` e o egress para `github.com` ampliam o impacto potencial; nunca altere chaves, credenciais ou remotos sem autorização explícita.
+Esse perfil é a opção de menor privilégio recomendada quando o trabalho cabe no workspace,
+especialmente para revisão, testes e manutenção delimitada. O perfil humano continua sendo
+`zaip-aios-full-access`; selecione `zaip-aios-security` explicitamente quando desejar contenção
+nativa. A escrita em `~/.ssh` e o egress para `github.com` ampliam o impacto potencial; nunca
+altere chaves, credenciais ou remotos sem autorização explícita.
 
 ## `zaip-aios-full-access`
 
@@ -118,8 +130,10 @@ conteúdo malicioso, dependência comprometida ou erro de escopo pode tentar:
 - enviar dados pela rede;
 - ampliar o impacto de uma falha de supply chain.
 
-Ele deve ser ativado somente quando o perfil restrito não consegue executar uma operação
-legítima e explicitamente autorizada. Após a correção, volte para `zaip-aios-security`.
+Ele é o default humano de permissão nativa. `approval_policy = "never"` evita
+prompt técnico para comandos, mas não substitui autorização explícita para
+operações externas, destrutivas ou de publicação. O hook complementar permanece
+default-deny para operações externas e não torna este perfil equivalente ao restrito.
 
 ## Camadas que reduzem o risco do full access
 
@@ -130,7 +144,7 @@ O acesso completo é mitigado por defesa em profundidade, mas nenhuma camada tor
    gasto e mutações remotas exigem pedido explícito no turno atual.
 2. **Escopo do repositório:** `AGENTS.md`, Rules e skills limitam o trabalho ao objetivo e
    proíbem inferir autoridade adicional a partir do acesso técnico.
-3. **Hook `PreToolUse`:** valida comandos e patches antes da execução; bloqueia escapes do
+3. **Hook `PreToolUse` ativo nos dois perfis:** valida comandos e patches antes da execução; bloqueia escapes do
    repositório, referências diretas a segredos, elevação, persistência de sistema, firewall,
    antivírus, serviços, Git destrutivo, banco destrutivo e clientes remotos não autorizados.
 4. **Regras `forbidden`:** arquivos em `.codex/rules/` negam classes perigosas de comandos
@@ -159,7 +173,7 @@ Use `zaip-aios-security` quando:
 - comandos precisam, no máximo, alcançar `github.com` para operações Git/SSH autorizadas;
 - menor privilégio é desejado.
 
-Use `zaip-aios-full-access` apenas quando:
+Use `zaip-aios-full-access` como default humano quando:
 
 - for necessário corrigir a própria configuração de permissões;
 - uma operação autorizada precisar de um caminho fora do workspace;

package/templates/.agents/zaip-aios/guides/17-como-o-custo-e-calculado.md

@@ -0,0 +1,32 @@
+# Como o custo é calculado
+
+Cada valor começa na telemetria de uma chamada LLM. O dashboard não estima uso ausente: dado indisponível continua indisponível.
+
+## 1. Separe os componentes de uso
+
+- **Tokens de input** incluem instruções, histórico, contexto, ferramentas e a mensagem atual.
+- **Tokens de cache** fazem parte do input, não são uma quantidade extra. Eles são subtraídos do input antes da aplicação da sua própria tarifa.
+- **Tokens de output** são tudo que o modelo gerou.
+- **Tokens de reasoning** fazem parte do output. O output é cobrado uma única vez, então reasoning não cria uma segunda cobrança.
+
+## 2. Aplique as tarifas publicadas do modelo
+
+O modelo e o tier de serviço escolhidos definem a tabela de tarifas. Para uma chamada, o total em USD é:
+
+| Componente | Cálculo |
+| --- | --- |
+| Input faturável | `(input - cache) / 1.000.000 × tarifa de input` |
+| Cache | `cache / 1.000.000 × tarifa de cache` |
+| Output | `output / 1.000.000 × tarifa de output` |
+
+O dashboard soma esses componentes uma única vez. Quando uma tarifa publicada não existe, ela permanece indisponível em vez de ser inventada.
+
+## 3. Considere contexto, velocidade e esforço
+
+Acima do limite de contexto longo de um modelo, o multiplicador publicado de input também vale para cache e o multiplicador de output vale para todo o output. Priority/Fast usa a sua tabela de tarifas publicada, quando disponível. O multiplicador exibido é apenas uma comparação com Standard, nunca uma cobrança extra.
+
+O esforço não possui multiplicador direto de preço. Ele só pode aumentar o custo indiretamente quando aumenta reasoning, output ou ciclos de execução registrados.
+
+## 4. Converta para a moeda selecionada
+
+O total da chamada é calculado primeiro em USD. Em BRL, é usada a cotação registrada no período relevante; a cotação atual é mantida separadamente para conversões atuais. Mudar a moeda de exibição nunca altera a telemetria de tokens nem o cálculo em USD.