@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-hostinger-cloudflare-terraform/references/operational-contract.md

@@ -2,9 +2,9 @@
 
 ## Preflight de autonomia
 
-Leia `.env` local ignorado na raiz antes de uma alternativa `.agents/.env` explicitamente selecionada. Leia-o como dados com parser dotenv; nunca use `source` ou `eval`. Com o mandato da Task e a arquitetura, o agente deriva e preenche o contrato neutro; não exige JSON manual nem nova autorização para cada passo dentro do escopo. Verifique presença sanitizada de `ZAIP_CLOUD_PROFILE=autonomous-cloud`, tokens de provider, conta e zona Cloudflare, conta Hostinger, dois IDs de VPS em adoção/importação e dois fingerprints SSH. Compare os identificadores com a Task/Execution; não descubra um alvo por token e depois o trate como autorizado.
+Leia `.env` local ignorado na raiz antes de uma alternativa `.agents/.env` explicitamente selecionada. Leia-o como dados com parser dotenv; nunca use `source` ou `eval`. Com o mandato da Task e a arquitetura, o agente deriva e preenche o contrato neutro; não exige JSON manual nem nova autorização para cada passo dentro do escopo. Verifique somente os módulos usados: DNS requer conta/zona/token Cloudflare; API VPS requer seus IDs/token; SSH requer os hosts e fingerprints declarados; Terraform requer seu backend. Quantidade de VPS vem da topologia aprovada. A derivação combinada legada exige seus dois papéis e não deve ser usada para DNS-only ou topologia diferente. Compare os identificadores com a Task/Execution; não descubra um alvo por token e depois o trate como autorizado.
 
-Uma credencial Cloudflare deve ter escopo mínimo DNS Read/DNS Write para a zona delimitada. A credencial Hostinger deve se limitar às VPS delimitadas. `ZAIP_HOSTINGER_ACCOUNT_ID` é um rótulo declarado do escopo: a API de VPS confirma a visibilidade dos IDs pelo token, mas não prova esse rótulo. O acesso SSH usa caminho local ignorado e fingerprint de host conhecido; não armazene chave privada em `.env`, Terraform, state ou evidência.
+Uma credencial Cloudflare deve ter Zone Read para conferir a identidade da zona e DNS Read para leitura ou DNS Write/Edit para escrita, restritos à zona delimitada. Permissões de Pages, Workers e R2 são separadas. A credencial Hostinger deve se limitar às VPS delimitadas. `ZAIP_HOSTINGER_ACCOUNT_ID` é um rótulo declarado do escopo: a API de VPS confirma a visibilidade dos IDs pelo token, mas não prova esse rótulo. O acesso SSH usa caminho local ignorado e fingerprint de host conhecido; não armazene chave privada em `.env`, Terraform, state ou evidência.
 
 Antes de `plan` ou `apply`, a descoberta de leitura consulta a identidade da zona Cloudflare e confirma seu `zone_id` e `account_id`, depois consulta as VPS Hostinger delimitadas e confirma a visibilidade de seus IDs pelo token. Registre somente os identificadores e momento observados. A resposta da API, token e conteúdo de state não entram em logs. O validador de plano recebe esse contrato observado como entrada; um output escrito pelo próprio plano não prova a conta nem torna a integração pronta para uso real.
 
@@ -16,4 +16,4 @@ Antes de executar uma função de provider, confira a documentação da versão
 
 ## Provas esperadas
 
-Após apply, compare recursos com read-after-write, confirme cada destino DNS, handshake TLS e health check. Teste que VPS 2 e serviços privados recusam conexões públicas e que VPS 1 só aceita origem e administração permitidas. Execute restore de uma cópia de backup e confirme que parar beta não afeta produção. Registre IDs não secretos, horários, hash de plano, resultado e limitações.
+Após apply, compare recursos com read-after-write e aplique [as provas DNS/TLS/domínio](cloudflare-dns.md). Teste que serviços privados recusam conexões públicas e que o ingress só aceita origem e administração permitidas, conforme a topologia declarada. Execute restore de uma cópia de backup e confirme que parar beta não afeta produção quando esses serviços estiverem no escopo. Registre IDs não secretos, horários, hash de plano, resultado e limitações.

package/templates/.agents/skills/zaip-skill-hostinger-cloudflare-terraform/references/vps-onboarding.md

@@ -0,0 +1,97 @@
+# Onboarding modular de VPS existente
+
+Esta é uma capacidade genérica. IDs, contas, hosts, chaves, inventários e decisões pertencem ao consumidor. Exemplos usam nomes fictícios. Não há conexão ou implantação implícita. Nunca reinicie/desligue o computador local.
+
+| Etapa | Pré-requisitos próprios | Operação do runner |
+| --- | --- | --- |
+| Capacidades locais | Node e instalação íntegra | `vps:capabilities` |
+| Arquitetura/decisão | Contexto e decisão autorizada | `vps:prepare`, `vps:architecture` |
+| Chave externa/agente/importação/geração | Identidade nomeada e modalidade autorizada | `vps:credential:prepare` |
+| Descoberta Hostinger | Conta de referência, seletor ID/IP/hostname e token local | `vps:discover` |
+| Confiança do servidor | Host/porta e fingerprint pública verificada por canal confiável | `vps:ssh:trust` |
+| Teste e inventário SSH | Chave/agente selecionado e confiança já preparada | `vps:ssh:test`, `vps:ssh:inventory` |
+| Host ou containers | Inventário, script/reversão revisados e readback delimitado | `vps:host:configure`, `vps:containers:configure` |
+| Pública de login root | API disponível, VPS exata e cadastro explicitamente autorizado | `vps:public-key:register` |
+| DNS/TLS | Conta/zona/registros Cloudflare e autoridade de escrita | Contrato `autonomous-cloud` de DNS |
+| Preparo de adoção Terraform | IDs observados, fonte pública/hash e mapeamento de recursos | `vps:terraform:prepare`; import genérico ainda indisponível |
+| Monitoramento/backup | Host inventariado, script revisado, restore/health por evidência | Configuração delimitada e readback; testes de restore próprios |
+
+SSH não exige token Hostinger, Cloudflare, Terraform ou segundo host. A ausência de API não bloqueia arquitetura, preparo local ou SSH autorizado. Uma ou várias VPS seguem a escolha do consumidor. Nenhuma operação `vps:*` cria, reinstala ou exclui VPS. O runner não remove acesso anterior: uma restrição de acesso exige fluxo próprio com novo acesso comprovado antes de restringir o antigo.
+
+## O agente prepara os artefatos
+
+Descubra primeiro o que já é conhecido e verificável. Reaproveite autorização e contexto. O usuário fornece somente uma lacuna real, agrupada em uma pergunta curta. Nunca peça JSON, hashes, IDs internos, chave privada ou passphrase. O agente produz `.agents/config/vps-onboarding-request.json`, sem segredos, e executa:
+
+```text
+node .agents/tools/cloud-runner.mjs --operation vps:capabilities
+node .agents/tools/cloud-runner.mjs --operation vps:prepare --request .agents/config/vps-onboarding-request.json
+node .agents/tools/cloud-runner.mjs --operation vps:architecture --contract .agents/config/vps-onboarding-contract.json
+```
+
+O request versão 1 contém `authorization: {confirmed:true,reference:<autorização real>,architecture:true|false}`, `targets` e, quando aplicável, `architecture`. Não registre uma sugestão exploratória como confirmação humana. O contrato resultante vincula a raiz física do projeto e devolve os hashes de cada alvo. Estes hashes são gerados e utilizados pelo agente; `BINDING_GERADO` abaixo é somente uma indicação documental:
+
+```text
+node .agents/tools/cloud-runner.mjs --operation vps:credential:prepare --contract .agents/config/vps-onboarding-contract.json --target primary --binding BINDING_GERADO
+node .agents/tools/cloud-runner.mjs --operation vps:ssh:trust --contract .agents/config/vps-onboarding-contract.json --target primary --binding BINDING_GERADO
+node .agents/tools/cloud-runner.mjs --operation vps:ssh:test --contract .agents/config/vps-onboarding-contract.json --target primary --binding BINDING_GERADO
+node .agents/tools/cloud-runner.mjs --operation vps:ssh:inventory --contract .agents/config/vps-onboarding-contract.json --target primary --binding BINDING_GERADO
+```
+
+Cada target possui `name`, `purpose`, `allowed_operations` e somente os módulos disponíveis. `ssh` contém `host`, `user`, `port`, `host_fingerprint` e `trust: {source,reference}`. As fontes aceitas são `previously-verified`, `authenticated-provider` e `human-public-confirmation`. `host_public_key` pode conter a pública autenticada. Sem ela, keyscan apenas coleta candidatas e o pin anterior seleciona a identidade; nunca autentica por conta própria. Divergência preserva known_hosts e bloqueia. Sem canal autenticado automatizável, solicite somente a fingerprint/pública indispensável e explique o motivo; Terminal Web é último recurso.
+
+## Quatro modalidades de credencial
+
+Todos os caminhos são literais, ligados ao alvo e verificados fisicamente; symlinks, junctions, hardlinks de chave e troca após validação são negados. O runner não percorre diretórios nem tenta chaves alternativas. A privada externa é passada ao OpenSSH, sem leitura de bytes privados pelo JavaScript.
+
+| `credential.mode` | Campos e comportamento |
+| --- | --- |
+| `external-key` | `name`, `path` absoluto fora do projeto; conferir permissões existentes sem alterá-las. Preferir chave protegida. |
+| `agent` | `name`, `path` da identidade **pública**, `agent_endpoint` explícito. Agente pode conter várias identidades; `IdentitiesOnly` e a pública selecionam somente a autorizada. |
+| `import` | `name`, `path` da dedicada original, `import_authorized:true`. Copiar exclusivamente para `.agents/private/state/ssh/<name>/identity`; preservar original, bytes e passphrase, sem sobrescrever. |
+| `generate` | `name`; geração protegida usa terminal interativo disponível, com passphrase digitada no OpenSSH, nunca no chat/contrato. Em host sem TTY, retornar dependência humana concreta. |
+
+Geração não assistida exige `unprotected:true` **e** `unprotected_acceptance:true`. Uma geração interativa que resultar sem frase também exige aceitação específica antes de habilitar uso. `ssh-keygen` verifica proteção efetiva; não remover passphrase. A chave privada permanece somente no armazenamento protegido, nunca em `.env`, contratos, Terraform, state, Git, logs, telemetria ou chat. Apenas sua referência/pública/fingerprint pode ser registrada. O preparo retorna somente a pública verificada do sidecar selecionado, quando disponível; importação copia também essa pública e cadastro pode resolvê-la internamente após geração, sem exigir JSON manual. Criptografia de disco é sondada por BitLocker no Windows, distinguindo observada, permissão negada e indisponível; ausência de consulta não significa “disco sem criptografia”.
+
+O runner prepara exclusão Git e permissões de `.agents/private/state/ssh`, conhecido host e referências públicas. No Windows aplica somente a DACL necessária, preservando owner/auditoria e verificando-a em seguida; falha fecha o acesso. Se a chave externa tem permissões largas, diagnosticar sem alterá-la silenciosamente.
+
+## Evolução e retomada
+
+Chave protegida em `external-key`, `import` ou `generate` não autentica em modo batch sem agente. Após preparar/importar, carregue somente a identidade autorizada pelo mecanismo interativo seguro disponível e revise o contrato para `mode:agent`, apontando à pública local verificada e ao endpoint selecionado. O agente prepara a revisão e os hashes; o operador só intervém no prompt TTY quando inevitável, nunca com passphrase no chat. Sem agente disponível, o teste retorna diagnóstico sanitizado e não tenta outra chave.
+
+Para referências existentes, `vps:prepare` deriva automaticamente `public_fingerprint` por OpenSSH no caminho autorizado, após validar mandato, permissões e identidade física. Se o agente já conhece essa fingerprint, pode fornecê-la; divergência bloqueia. Não pedir ao usuário calcular hash nem ler privada no JavaScript.
+
+O mesmo request é idempotente. Quando descoberta, geração ou confirmação pública completar o contexto, o agente atualiza o request com `expected_previous_hash` igual ao `contract_sha256` observado e a autorização vigente. `vps:prepare` salva snapshot protegido do contrato anterior e faz substituição atômica sob lock. Um hash antigo ou mudança concorrente bloqueia; não peça ao usuário apagar o contrato. As referências físicas de chave e hashes dos alvos são regeneradas a partir dos dados presentes.
+
+Locks carregam PID e operação. Um dono ainda existente mantém `onboarding_writer_busy`; somente dono comprovadamente morto admite recuperação automática, com readback antes de qualquer repetição externa. Lock malformado exige diagnóstico delimitado do agente; nunca limpeza global.
+
+Geração interrompida com chave existente não é sobrescrita/adotada automaticamente. O agente verifica pública, proteção, ACL e autorização e prepara uma revisão com `credential.reconcile_existing_generation: {public_fingerprint,authorization_reference}`. Sem essa evidência, permanece `key_generation_requires_reconciliation`. Importação compara bytes e pode retomar uma cópia idêntica; conflitos preservam ambos os arquivos.
+
+Cadastro público e configuração registram tentativa antes do efeito. Depois de timeout/resposta perdida, leem o estado. Ausência de confirmação bloqueia um segundo POST/script; não cria duplicatas. Distinguir autorizado, preparado, tentado, executado e comprovado. Uma tentativa pendente é uma condição de observação, não uma instrução para reenviar.
+
+## Arquitetura e configuração
+
+Reutilize `.agents/architecture/software-architecture.md` quando principal; outra principal existente pode ser indicada em `architecture.principal`. Ambiguidade exige descoberta. `architecture` registra `id`, `origin:human|agent`, `kind:confirmed|technical|exploration`, referência de autorização, razão disponível (ou null), alternativas, consequências e pendências. Para documento existente, fornecer `previous_sha256` e `document` completo revisado, preservando conteúdo não afetado e removendo instruções antigas incompatíveis. `hosts` e `sections` cobrem topologia, redes/portas, dados, capacidade, backup, observabilidade, recuperação, dependências e sequência. O original integral e a decisão ficam no histórico explicitamente superado, com uma única principal vigente.
+
+Proposta, planejado, código/configuração e implantação verificada são estados distintos. Referência de implementação possui caminho/hash e interpretação de quantidade de hosts informada pelo agente; o hash não demonstra essa interpretação. Duas VPS no Terraform diante de uma escolhida resultam em adaptação pendente. Não aplicar o plano antigo. Documento não concede compra, deploy ou migração.
+
+Para `vps:host:configure` ou `vps:containers:configure`, preencher o módulo correspondente de `target.configuration.host|containers`: referência de autorização, `previous_access_preserved:true`, locator/hash do inventário SSH, scripts e hashes de aplicação/readback, e `expected_marker` público. Inventário precisa corresponder ao mesmo acesso. Scripts são revisados e vinculados ao alvo; não há comando remoto arbitrário por argumento. A verificação consulta o estado antes e depois e descarta saída bruta. Rollback/restore fazem parte do plano revisado; teste de configuração não prova restauração sem execução própria.
+
+## Dados SSH e provider
+
+SO e versão possuem probes independentes. `findmnt` observa metadados de mounts de `/srv`, `/opt` e `/var/lib/docker/volumes`; `docker volume ls` lista apenas nome/driver. Ausência de ferramenta ou diretório permanece lacuna explícita. Configuração exige esses campos ou aceitação específica de cada lacuna com razão, sem presumir sucesso de um probe composto parcialmente falho.
+
+Inventário SSH usa probes fixos de SO/arquitetura, CPU/RAM/disco/livre, hostname/interfaces, identidade/privilégio efetivo, Docker/Compose, serviços, portas, firewall e metadados dos diretórios pertinentes. Não lê ambientes de processos, configurações secretas, logs ou árvores arbitrárias. `sudo` não é sondado nem presumido. Saída/tempo são limitados; ferramenta ausente ou privilégio insuficiente é indisponível. Inventário fica em `.agents/private/state/cloud/onboarding` do consumidor, com fonte e momento; arquitetura usa referência mínima.
+
+Plano/cobrança/ID/backups do painel não são inferidos de SSH. O adapter Hostinger usa a [OpenAPI oficial](https://developers.hostinger.com/openapi/openapi.json), versão observada 1.66.0 em 2026-10-15, e a [visão geral](https://docs.hostinger.com/api-reference/overview). A coleção VM é array, sem paginação declarada. Match por ID/IP/hostname exige unicidade e consulta o ID real; hostname numérico não é ID. Metadados ausentes permanecem null. Não existe capacidade de fingerprint de host demonstrada nessa spec.
+
+`GET/POST /api/vps/v1/virtual-machines/{id}/ssh-keys` cadastra **públicas de login root**, com body `keys:[<OpenSSH pública>]`, e não a identidade do servidor. Não configura outro usuário por inferência. Token fica no dotenv selecionado e é enviado só ao request mínimo. Credencial não amplia a VPS autorizada.
+
+## Atualização e prova
+
+`vps:terraform:prepare` prepara adoção **local** por alvo: `target.terraform` identifica endereço de recurso, observação provider/hash, fonte pública `.tf`/hash e contagem interpretada. O recibo vincula ID existente, conta, autorização e topologia de um ou vários hosts, apontando divergência. Não carrega credenciais nem executa init/import/plan/apply. Backend/locking e schema do provider são verificações próprias pendentes. Import efetivo genérico ainda não é suportado: nunca encaminhar um host ao executor legado de duas funções/Cloudflare; SSH e preparo documental continuam independentes.
+
+Observações de inventário não comprovam deploy. Readback de configuração atualiza o estado operacional somente no escopo host/containers e data referenciados; decisão posterior preserva essas referências sem transformar aplicação em implantada. A fonte de implementação aceita somente configuração pública pertinente em `infra/` ou `infrastructure/`, sem state/plan/env/chaves.
+
+Use o tarball local candidato realmente produzido/testado, ou a versão publicada que já contenha esta capacidade. Ciclo aberto não significa pacote publicado: não afirmar que `@latest` já inclui uma mudança local. Primeiro dry-run e revisão de conflitos/backup; depois init autorizado normal ou force, e `doctor --json`/`hook status --json`. Updates normais e force preservam arquitetura, histórico e configurações do consumidor; não copiar arquitetura ou dados do mantenedor. O runner e todos os módulos são distribuídos em paridade e conferidos pelo hook contra o lock gerenciado. Fonte alterada, wrappers, argumentos extras e acesso genérico a segredos permanecem negados. Contratos locais não são uma barreira contra quem já pode editar o próprio código/mandato; preservar vínculo com autorização humana e revisão do diff.
+
+Provas locais do consumidor: `node --test .agents/tools/cloud-onboarding.test.mjs`; `node --test .agents/tools/cloud-onboarding.ssh.integration.test.mjs`. No checkout mantenedor, qualificação por `scripts/qualify-vps-onboarding.mjs`. SSH real loopback usa dependência test-only explicitamente instalada e fixada (`ssh2@1.17.0` em `.local/temp/vps-ssh-test-server`, instalação sem scripts). Inventário do servidor de teste é resposta sintética sobre protocolo real, não medição Linux nem implantação. Não ocultar dependência ausente como teste aprovado. Não instalar serviço global ou reiniciar o SO para obter evidência.

package/templates/.agents/skills/zaip-skill-image-optimization/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: zaip-skill-image-optimization
+description: Inventory, generate and verify responsive images when creating any site or landing page, optimizing images, or auditing image delivery while preserving the design.
+---
+
+# Otimização de imagens
+
+Componha performance-engineering: torne a imagem LCP descoberta no HTML inicial,
+priorize somente o hero necessário e verifique CPU/LCP além de bytes. Preserve o design;
+uma medição isolada de transferência não prova performance completa.
+
+Aplique automaticamente na criação de qualquer site/LP, sem exigir pedido separado. Preserve identidade, composição, crop, alpha, cores, acessibilidade e conversão. Não use geração de imagens para compressão/conversão.
+
+1. Escolha o modo: **criação** integra assets desde o início; **auditoria** apenas lê; **correção** mede antes e altera o gargalo observado; **verificação de publicação** confere assets do candidato já autorizado. Esta skill não autoriza deploy.
+2. Inventarie originais, dimensões, bytes, formato, alpha, hashes/duplicatas e referências no código. Classifique LCP/hero, galeria, logo, ícone e social; referências estáticas não comprovam uso/download no navegador.
+3. Leia [pipeline e configuração](references/pipeline.md). Prefira o otimizador nativo da stack quando adequado. O script usa `sharp` previamente instalado pelo projeto; não instala dependências. Preserve originais e gere somente larguras úteis ao layout/DPR, sem ampliar. Se o codec estiver ausente, declare a limitação.
+4. Integre com [adaptadores](references/adapters.md): `srcset`/`sizes`, dimensões intrínsecas, `picture` para art direction e uma única imagem por viewport. Hero/LCP não usa lazy; prioridade/preload só com justificativa e seleção consistente. Demais imagens fora da dobra usam lazy. Alt descreve informação; decoração usa alt vazio.
+5. Valide manifesto e budgets; cache longo/immutable fica restrito aos derivados com hash. Não aplique ao HTML, manifesto ou nomes mutáveis. Não envie o inventário completo como JavaScript ao cliente.
+6. Examine screenshots mobile/desktop equivalentes, primeira dobra, galerias e formulário. Verifique waterfall: PNG pesado ainda requisitado, viewport oposto baixado e preload duplicado são falhas de integração mesmo com manifesto válido. Preserve `object-fit`/`object-position` e não aceite screenshots apenas por existirem.
+7. Registre comando, codec/versão, candidato, data, viewport/DPR, CPU/rede/cache e URL para medições no navegador. Separe bytes em disco, transferência inicial e página percorrida; o script não mede Lighthouse, PageSpeed, CWV ou qualidade visual. Compare antes/depois sob condições equivalentes e teste conversão com mocks/sandbox.
+
+Comandos da raiz do consumidor; caminhos de configuração são relativos a essa raiz:
+
+```sh
+node .agents/skills/zaip-skill-image-optimization/scripts/images.mjs inventory image-config.json
+node .agents/skills/zaip-skill-image-optimization/scripts/images.mjs generate image-config.json
+node .agents/skills/zaip-skill-image-optimization/scripts/images.mjs verify image-manifest.json
+node --test .agents/skills/zaip-skill-image-optimization/scripts/images.test.mjs
+```
+
+Use `$zaip-skill-website-readiness` para SEO/GEO e verificação conjunta; `$zaip-skill-performance-engineering` para diagnóstico de performance. Alterações pequenas validam assets e rotas afetados; criação e revisão ampla incluem integração visual/funcional proporcional.

package/templates/.agents/skills/zaip-skill-image-optimization/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Image Optimization"
+  short_description: "Responsive images with verified assets and budgets"
+  default_prompt: "Use $zaip-skill-image-optimization to optimize site images while preserving the design."

package/templates/.agents/skills/zaip-skill-image-optimization/references/adapters.md

@@ -0,0 +1,36 @@
+# Integração por stack
+
+Use URLs reais do manifesto; `HASH` abaixo representa o SHA gerado. Confira waterfall em viewports e DPR representativos. Não use dois elementos `<img>` desktop/mobile ocultos por CSS: ambos podem baixar.
+
+## HTML estático
+
+```html
+<picture>
+  <source media="(max-width: 640px)" srcset="/images/derived/hero-mobile-480-HASH.webp 480w, /images/derived/hero-mobile-960-HASH.webp 960w" sizes="100vw" width="960" height="1200">
+  <img src="https://example.com/images/derived/hero-960-HASH.webp"
+       srcset="/images/derived/hero-480-HASH.webp 480w, /images/derived/hero-960-HASH.webp 960w"
+       sizes="(max-width: 640px) 100vw, 960px" width="960" height="540"
+       loading="eager" fetchpriority="high" alt="Descrição do conteúdo informativo">
+</picture>
+```
+
+Fontes distintas só para art direction aprovada. Preserve dimensões/aspect-ratio de cada crop, `object-fit` e `object-position`. Imagem descoberta cedo no HTML costuma dispensar preload. Quando medido como necessário, `imagesrcset`/`imagesizes` correspondem à imagem selecionada, com `media` mutuamente exclusivo para art direction. Não preload WebP e AVIF simultaneamente; escolha um formato suportado ou dispense preload. Confira que o navegador não baixou também o fallback. Fora da primeira dobra: `loading="lazy"`, sem prioridade alta; reserve espaço.
+
+## React/Vite
+
+Gere antes de `vite build`; copie somente o fragmento necessário do manifesto para cada componente no build, ou gere módulos de props por imagem. Inventário não pertence ao bundle global.
+
+```jsx
+export function Hero({ image }) {
+  const props = { src: image.fallback.url, srcSet: image.srcset.webp,
+    sizes: image.sizes, width: image.fallback.width, height: image.fallback.height,
+    loading: "eager", fetchPriority: "high", alt: "Descrição real do conteúdo" };
+  return <img {...props} />;
+}
+```
+
+Escolha `fallback` do formato correspondente ao `srcSet`. Verifique links diretos/reload, HTML de metadados sociais e ausência de URLs dos originais pesados no waterfall. SSR/SSG/prerender é decisão de stack/indexabilidade, não requisito da compressão.
+
+## Frameworks com otimização nativa
+
+Em Astro use componentes/serviços nativos; em Next o componente/loader configurado; em Nuxt o módulo de imagens já adotado. Leia a documentação da versão instalada para props, prioridade/preload e formatos. Passe dimensões e sizes reais, preserve crop e política de domínios remotos. Não pré-converta todos os originais só para alimentar outro otimizador. Audite URLs geradas, variantes, cache e bytes com requests reais. Não afirme teste na aplicação só porque o exemplo compila.

package/templates/.agents/skills/zaip-skill-image-optimization/references/pipeline.md

@@ -0,0 +1,35 @@
+# Pipeline reproduzível
+
+O CLI usa Node ESM e resolve `sharp` da raiz do projeto. Não instala nem baixa nada. `--sharp-root PATH` permite usar uma instalação já autorizada; mantenha a versão de sharp/libvips no lock do projeto. A mesma fonte/configuração/versão gera bytes e nomes iguais. Mudanças de codec podem produzir outros hashes. O manifesto registra versões, sem timestamp para preservar idempotência.
+
+Exemplo de `image-config.json`; adapte fontes, larguras e limites ao produto:
+
+```json
+{
+  "outputDir": "public/images/derived",
+  "manifest": "image-manifest.json",
+  "publicBase": "/images/derived/",
+  "budgets": { "maxImageBytes": 250000, "maxTotalBytes": 1500000 },
+  "usageFiles": ["src/Hero.tsx", "index.html"],
+  "images": [{
+    "source": "assets/originals/hero.png",
+    "role": "hero",
+    "widths": [480, 960, 1440],
+    "formats": ["webp"],
+    "quality": 82,
+    "sizes": "(max-width: 640px) 100vw, 960px"
+  }]
+}
+```
+
+`inventory` lê fontes declaradas e `usageFiles`, retorna dimensões orientadas, formato detectado, MIME, bytes, alpha, SHA-256, duplicatas e referências literais. Inclua todas as fontes; complete referências dinâmicas com rede observada. `generate` aceita raster estático, mantém proporção sem crop, aplica orientação EXIF e saída sRGB; nunca amplia, remove alpha ou altera originais. SVG/logos vetoriais e animações permanecem no pipeline próprio: inventário aceita, conversão recusa. AVIF/WebP servem fotos/alpha; PNG lossless favorece gráficos sensíveis; JPEG só sem alpha. Preserve PNG/SVG ou use WebP lossless (`lossless: true`) quando necessário para legibilidade. PNG ignora quality; escolher formato demanda comparação visual.
+
+Larguras acima da fonte são descartadas; a largura original só é adicionada quando todas as solicitadas excedem a fonte. Evite dezenas de variantes. Para art direction crie fontes separadas com recortes aprovados; a ferramenta não inventa crop. Favicon, app icon e imagem social são produtos diferentes: use dimensões/composição específicas, não resize deformado. Mantenha imagem social acessível por URL absoluta.
+
+`verify` falha para arquivo ausente, MIME/extensão/formato incorretos, hash/dimensões alterados, orçamento excedido, duplicatas no manifesto e configuração inválida. Lê os arquivos reais. `maxTotalBytes` soma derivados em disco, não prevê download por viewport. Não reduza budgets para obter PASS; registre exceção/evidência. Cache HTTP, downloads/preload e UI exigem teste real do site.
+
+Saída usa `nome-WIDTH-SHA256.ext`, SHA completo dos bytes. Somente essa família recebe immutable. Manifesto e HTML revalidam conforme hosting; não aplique regra genérica para `/images/`. A ferramenta conserva derivados antigos para rollback e não faz limpeza destrutiva. Publicação preserva referências do candidato anterior enquanto necessário.
+
+Gere antes do build em checkout limpo, depois verifique. Versione configuração/fontes e automatize geração no build; não dependa de manifesto que existe apenas na máquina local. Com otimização nativa, teste o build e sua saída com gates equivalentes; não execute dois pipelines em paralelo.
+
+O caso de referência Moradigna reduziu transferência local ao percorrer a página de 29,97 MB para 1,34 MB mobile e 32,42 MB para 1,89 MB desktop. Não eram Lighthouse, PageSpeed ou GTmetrix; valores não são meta, baseline universal nem promessa para outro projeto.

package/templates/.agents/skills/zaip-skill-image-optimization/scripts/images.mjs

@@ -0,0 +1,370 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MIME = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  avif: "image/avif",
+  svg: "image/svg+xml",
+  gif: "image/gif",
+  tiff: "image/tiff",
+  heif: "image/heif",
+};
+const digest = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+const fail = (message) => {
+  throw new Error(message);
+};
+const positive = (value) => Number.isSafeInteger(value) && value > 0;
+const relative = (root, target) => path.relative(root, target).split(path.sep).join("/");
+
+export function loadSharp(root = process.cwd()) {
+  try {
+    return createRequire(path.join(path.resolve(root), "package.json"))("sharp");
+  } catch {
+    fail(
+      "sharp is unavailable. Use a project-installed, approved dependency or --sharp-root PATH; no installation was performed.",
+    );
+  }
+}
+
+// Resolve existing ancestors as well as lexical paths to reject symlink escapes.
+async function contained(root, value) {
+  if (typeof value !== "string" || !value || path.isAbsolute(value))
+    fail("Path must be relative to project root");
+  const target = path.resolve(root, value);
+  const check = (candidate) => {
+    const rel = path.relative(root, candidate);
+    if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+      fail(`Path escapes project root: ${value}`);
+  };
+  check(target);
+  let ancestor = target;
+  while (true) {
+    try {
+      check(await fs.realpath(ancestor));
+      break;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) throw error;
+      ancestor = parent;
+    }
+  }
+  return target;
+}
+
+// Canonicalize missing destinations through their nearest existing ancestor,
+// so aliases in parent directories (including Windows junctions) also match.
+async function fileIdentity(file) {
+  let ancestor = file;
+  const missing = [];
+  while (true) {
+    try {
+      const real = await fs.realpath(ancestor);
+      const canonical = path.join(real, ...missing);
+      const stat = missing.length ? null : await fs.stat(file, { bigint: true });
+      return {
+        canonical: process.platform === "win32" ? canonical.toLowerCase() : canonical,
+        inode: stat && stat.ino !== 0n ? `${stat.dev}:${stat.ino}` : null,
+      };
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) throw error;
+      missing.unshift(path.basename(ancestor));
+      ancestor = parent;
+    }
+  }
+}
+
+const sameIdentity = (a, b) =>
+  a.canonical === b.canonical || (a.inode !== null && a.inode === b.inode);
+
+async function protectOriginals(file, sources) {
+  const target = await fileIdentity(file);
+  if (sources.some((source) => sameIdentity(source, target)))
+    fail("Destination would overwrite an original through a path alias");
+  return target;
+}
+
+function budgets(value) {
+  if (!value || !positive(value.maxImageBytes) || !positive(value.maxTotalBytes))
+    fail("Explicit positive integer maxImageBytes and maxTotalBytes budgets are required");
+  return value;
+}
+
+function checkBudget(entries, limits) {
+  budgets(limits);
+  for (const entry of entries)
+    if (entry.bytes > limits.maxImageBytes) fail(`Image budget exceeded: ${entry.file}`);
+  if (entries.reduce((sum, entry) => sum + entry.bytes, 0) > limits.maxTotalBytes)
+    fail("Total derivative budget exceeded");
+}
+
+async function inspect(file, sharp) {
+  const bytes = await fs.readFile(file);
+  const meta = await sharp(bytes, { animated: true }).metadata();
+  const rotated = [5, 6, 7, 8].includes(meta.orientation);
+  const format = meta.format === "heif" && meta.compression === "av1" ? "avif" : meta.format;
+  return {
+    width: rotated ? meta.height : meta.width,
+    height: rotated ? meta.width : meta.height,
+    format,
+    mime: MIME[format] ?? "application/octet-stream",
+    alpha: Boolean(meta.hasAlpha),
+    pages: meta.pages ?? 1,
+    bytes: bytes.length,
+    sha256: digest(bytes),
+  };
+}
+
+export async function inventory(config, { root = process.cwd(), sharp = loadSharp(root) } = {}) {
+  root = await fs.realpath(root);
+  if (!Array.isArray(config.images) || !config.images.length)
+    fail("images must be a non-empty array");
+  const usage = await Promise.all(
+    (config.usageFiles ?? []).map(async (file) => ({
+      file,
+      text: await fs.readFile(await contained(root, file), "utf8"),
+    })),
+  );
+  const seen = new Set();
+  const images = [];
+  for (const entry of config.images) {
+    const file = await contained(root, entry.source);
+    const real = await fs.realpath(file);
+    if (seen.has(real)) fail(`Duplicate source: ${entry.source}`);
+    seen.add(real);
+    const meta = await inspect(file, sharp);
+    images.push({
+      source: entry.source,
+      role: entry.role ?? "unclassified",
+      ...meta,
+      references: usage
+        .filter(
+          (item) =>
+            item.text.includes(entry.source) || item.text.includes(path.basename(entry.source)),
+        )
+        .map((item) => item.file),
+    });
+  }
+  const duplicates = [...new Set(images.map((item) => item.sha256))]
+    .map((hash) => images.filter((item) => item.sha256 === hash).map((item) => item.source))
+    .filter((group) => group.length > 1);
+  return {
+    schemaVersion: 1,
+    referenceMethod: "literal source or basename; dynamic use requires browser evidence",
+    images,
+    duplicates,
+  };
+}
+
+async function writeChanged(file, bytes) {
+  try {
+    if ((await fs.readFile(file)).equals(Buffer.from(bytes))) return;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  // Replace directory entries instead of following an existing symlink/hardlink.
+  const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, bytes, { flag: "wx" });
+    await fs.rename(temporary, file);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}
+
+export async function generate(config, { root = process.cwd(), sharp = loadSharp(root) } = {}) {
+  root = await fs.realpath(root);
+  budgets(config.budgets);
+  const outputDir = await contained(root, config.outputDir);
+  const manifestFile = await contained(root, config.manifest);
+  if (
+    typeof config.publicBase !== "string" ||
+    !/^\/(?!\/)[^?#\\\s]*\/$/.test(config.publicBase) ||
+    config.publicBase.includes("..")
+  )
+    fail("publicBase must be a root-relative URL directory");
+  const originals = await inventory(config, { root, sharp });
+  const plans = config.images.map((entry, index) => {
+    const meta = originals.images[index];
+    if (!["png", "jpeg", "webp", "avif", "tiff"].includes(meta.format) || meta.pages !== 1)
+      fail(
+        "Conversion requires a static raster image; preserve vectors/animations in their native pipeline",
+      );
+    if (!Array.isArray(entry.widths) || !entry.widths.length || !entry.widths.every(positive))
+      fail("widths must be positive integers");
+    if (
+      !Array.isArray(entry.formats) ||
+      !entry.formats.length ||
+      !entry.formats.every((format) => ["webp", "avif", "png", "jpeg"].includes(format))
+    )
+      fail("Unsupported output formats");
+    if (meta.alpha && entry.formats.includes("jpeg"))
+      fail("JPEG would discard alpha; select an alpha-capable format");
+    if (entry.quality !== undefined && (!positive(entry.quality) || entry.quality > 100))
+      fail("quality must be an integer from 1 to 100");
+    if (entry.lossless !== undefined && typeof entry.lossless !== "boolean")
+      fail("lossless must be boolean");
+    if (typeof entry.sizes !== "string" || !entry.sizes.trim())
+      fail("Explicit layout sizes is required");
+    const widths = [...new Set(entry.widths.filter((width) => width <= meta.width))].sort(
+      (a, b) => a - b,
+    );
+    if (!widths.length) widths.push(meta.width);
+    return { entry, meta, widths, formats: [...new Set(entry.formats)].sort() };
+  });
+  const sourceIdentities = await Promise.all(
+    config.images.map(async (entry) => fileIdentity(await contained(root, entry.source))),
+  );
+  const manifestIdentity = await protectOriginals(manifestFile, sourceIdentities);
+  const manifest = {
+    schemaVersion: 1,
+    generator: { name: "zaip-images", sharp: sharp.versions.sharp, vips: sharp.versions.vips },
+    budgets: config.budgets,
+    images: [],
+  };
+  const pending = new Map();
+  for (const { entry, meta, widths, formats } of plans) {
+    const image = {
+      source: entry.source,
+      sourceSha256: meta.sha256,
+      role: entry.role ?? "unclassified",
+      sizes: entry.sizes,
+      variants: [],
+      srcset: {},
+    };
+    for (const format of formats) {
+      for (const width of widths) {
+        const file = await contained(root, entry.source);
+        const bytes = await sharp(file)
+          .rotate()
+          .resize({ width, withoutEnlargement: true })
+          .toColourspace("srgb")
+          .toFormat(format, { quality: entry.quality ?? 82, lossless: entry.lossless ?? false })
+          .toBuffer();
+        const actual = await sharp(bytes).metadata();
+        const hash = digest(bytes);
+        const stem = path
+          .basename(entry.source, path.extname(entry.source))
+          .replace(/[^a-zA-Z0-9_-]/g, "-");
+        const name = `${stem}-${actual.width}-${hash}.${format}`;
+        const target = await contained(root, relative(root, path.join(outputDir, name)));
+        const targetIdentity = await protectOriginals(target, sourceIdentities);
+        if (sameIdentity(targetIdentity, manifestIdentity))
+          fail("Output would overwrite the manifest through a path alias");
+        pending.set(target, bytes);
+        image.variants.push({
+          file: relative(root, target),
+          url: config.publicBase + name,
+          format,
+          mime: MIME[format],
+          width: actual.width,
+          height: actual.height,
+          alpha: Boolean(actual.hasAlpha),
+          bytes: bytes.length,
+          sha256: hash,
+        });
+      }
+      image.srcset[format] = image.variants
+        .filter((item) => item.format === format)
+        .map((item) => `${item.url} ${item.width}w`)
+        .join(", ");
+    }
+    image.fallback = image.variants.filter((item) => item.format === entry.formats[0]).at(-1);
+    manifest.images.push(image);
+  }
+  const unique = [
+    ...new Map(
+      manifest.images.flatMap((item) => item.variants).map((item) => [item.file, item]),
+    ).values(),
+  ];
+  checkBudget(unique, config.budgets);
+  // Recheck aliases before writing; do not rely solely on lexical config paths.
+  for (const file of [...pending.keys(), manifestFile])
+    await protectOriginals(file, sourceIdentities);
+  for (const [file, bytes] of pending) await writeChanged(file, bytes);
+  await writeChanged(manifestFile, JSON.stringify(manifest, null, 2) + "\n");
+  return manifest;
+}
+
+export async function verify(manifest, { root = process.cwd(), sharp = loadSharp(root) } = {}) {
+  root = await fs.realpath(root);
+  if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.images) || !manifest.images.length)
+    fail("Invalid or empty image manifest");
+  const actualFiles = new Map();
+  const seenSources = new Set();
+  for (const image of manifest.images) {
+    if (seenSources.has(image.source)) fail("Duplicate source in manifest");
+    seenSources.add(image.source);
+    const source = await inspect(await contained(root, image.source), sharp);
+    if (source.sha256 !== image.sourceSha256) fail(`Source changed: ${image.source}`);
+    if (!Array.isArray(image.variants) || !image.variants.length) fail("Missing variants");
+    const seen = new Set();
+    for (const variant of image.variants) {
+      if (seen.has(variant.file)) fail("Duplicate variant");
+      seen.add(variant.file);
+      const file = await contained(root, variant.file);
+      const actual = await inspect(file, sharp);
+      for (const key of ["width", "height", "format", "mime", "alpha", "bytes", "sha256"]) {
+        if (variant[key] !== actual[key]) fail(`Asset ${key} mismatch: ${variant.file}`);
+      }
+      if (actual.width > source.width || actual.height > source.height) fail("Upscaled asset");
+      if (Math.abs(actual.height - (source.height * actual.width) / source.width) > 1)
+        fail("Asset aspect ratio changed");
+      if (source.alpha && !actual.alpha) fail("Asset lost alpha");
+      if (!path.basename(file).endsWith(`-${actual.width}-${actual.sha256}.${actual.format}`))
+        fail("Asset filename hash/extension mismatch");
+      if (typeof variant.url !== "string" || !variant.url.endsWith("/" + path.basename(file)))
+        fail("Asset URL mismatch");
+      actualFiles.set(file, { file: variant.file, bytes: actual.bytes });
+    }
+    for (const format of new Set(image.variants.map((item) => item.format))) {
+      const expected = image.variants
+        .filter((item) => item.format === format)
+        .map((item) => `${item.url} ${item.width}w`)
+        .join(", ");
+      if (image.srcset?.[format] !== expected) fail("srcset mismatch");
+    }
+    if (
+      !image.sizes?.trim() ||
+      !image.variants.some((item) => JSON.stringify(item) === JSON.stringify(image.fallback))
+    )
+      fail("Invalid sizes/fallback");
+  }
+  checkBudget([...actualFiles.values()], manifest.budgets);
+  return {
+    valid: true,
+    files: actualFiles.size,
+    totalBytes: [...actualFiles.values()].reduce((sum, item) => sum + item.bytes, 0),
+    scope: "local asset integrity; browser/HTTP/visual validation required separately",
+  };
+}
+
+export async function main(args = process.argv.slice(2)) {
+  const [command, input, option, sharpRoot] = args;
+  if (
+    !["inventory", "generate", "verify"].includes(command) ||
+    !input ||
+    (option && (option !== "--sharp-root" || !sharpRoot)) ||
+    args.length > 4
+  )
+    fail("Usage: images.mjs inventory|generate|verify FILE.json [--sharp-root PATH]");
+  const value = JSON.parse(await fs.readFile(input, "utf8"));
+  const sharp = loadSharp(sharpRoot ?? process.cwd());
+  const result = await { inventory, generate, verify }[command](value, { sharp });
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}