.

TOOLS

@@ -89,9 +89,22 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot
 
 ---
 
-## 6. Instalação Rápida (Copia e Cola)
+## 6. Automação e Testes de Interface (Browser)
 
-Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm` e `snap` já configurados).
+### agent-browser
+- **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA.
+- **Por que ajuda as IAs:** Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (`@e1`, `@e2`), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais.
+- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
+- **Instalação:**
+  - Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
+  - Com NPM: `npm install -g agent-browser && agent-browser install`
+- **Documentação:** https://agent-browser.dev/
+
+---
+
+## 7. Instalação Rápida (Copia e Cola)
+
+Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados).
 
 ### Linux (Debian / Ubuntu)
 
@@ -103,7 +116,10 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh
 # 2. Instalar ferramentas em Node
 npm install -g @ast-grep/cli @biomejs/biome
 
-# 3. Instalar yq via snap 
+# 3. Instalar automação de navegador para IA (visível com --headed)
+bun i -g agent-browser && agent-browser install
+
+# 4. Instalar yq via snap 
 sudo snap install yq
 ```
 
@@ -113,4 +129,5 @@ sudo snap install yq
 # Instalar utilitários essenciais
 brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
 npm install -g @biomejs/biome
+bun i -g agent-browser && agent-browser install
 ```

agents/front/persona

@@ -47,6 +47,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 8. Implementar fluxos de navegação e estados de interface
 9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
 10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
+11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`)** para acompanhamento do operador (ver `rules/testes-interface-agent-browser.md`)
 
 ## Restrições
 

agents/testes/persona

@@ -45,6 +45,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 6. Identificar casos extremos e cenários de falha não cobertos
 7. Validar schemas Zod contra dados reais de produção
 8. Documentar bugs encontrados com passos de reprodução
+9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe cada ação na tela (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
 
 ## Restrições
 
@@ -112,6 +113,7 @@ Artefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent
 - [ ] Casos extremos (null, vazio, limite) testados?
 - [ ] Erros de rede/banco simulados?
 - [ ] Performance em volume realista de dados?
+- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) com screenshots comprobatórios?
 
 ## Memória Persistente & Identidade do Projeto
 

agents/ux/persona

@@ -45,6 +45,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 6. Organizar a hierarquia de informação das telas
 7. Revisar labels, placeholders e textos de ajuda
 8. Identificar inconsistências de UX entre módulos
+9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe a validação visual (ver `rules/testes-interface-agent-browser.md`)
 
 ## Restrições
 

global/rules/testes-interface-agent-browser.md

@@ -0,0 +1,133 @@
+---
+type: rule
+name: testes-interface-agent-browser
+description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) ao operador.
+scope: global
+trigger: always_on
+updatedAt: "2026-09-16"
+---
+
+# Regra: Testes Automatizados de Interface e Navegação com agent-browser
+
+## Contexto
+
+Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica.
+
+Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA.
+
+---
+
+## Regra
+
+Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**:
+
+1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador.
+2. **Executar SEMPRE em Modo Visível (`--headed`)**:
+   - A janela do navegador **deve sempre aparecer na área de trabalho do operador**.
+   - É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção.
+   - Usar a flag `--headed` nos comandos de abertura (`agent-browser open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
+3. **Utilizar o modelo de referências (`@ref`)**:
+   - Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
+   - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
+4. **Registrar evidências e fechar sessão**:
+   - Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
+   - Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
+
+---
+
+## Instalação e Configuração
+
+O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
+
+```bash
+# Instalação global via bun (recomendado)
+bun i -g agent-browser
+
+# Download do motor do navegador (primeira execução)
+agent-browser install
+```
+
+Documentação de referência: **https://agent-browser.dev/**
+
+---
+
+## Protocolo Operacional Padrão
+
+Todo teste ou navegação de interface executado pela IA deve seguir o fluxo:
+
+### 1. Abertura com Janela Visível
+
+```bash
+# Abrir sempre visível ao operador humano
+agent-browser open --headed http://localhost:8080
+```
+
+### 2. Inspeção de Elementos Interativos
+
+```bash
+# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2)
+agent-browser snapshot -i
+```
+
+### 3. Interações por Referência Direta
+
+```bash
+# Interagir diretamente com os elementos identificados no snapshot
+agent-browser fill @e1 "usuario@exemplo.com"
+agent-browser fill @e2 "senhaSegura123"
+agent-browser click @e3
+```
+
+### 4. Validação e Evidência
+
+```bash
+# Aguardar estabilização se houver transição assíncrona
+agent-browser wait 1000
+
+# Obter novo snapshot para verificar estado pós-ação
+agent-browser snapshot -i
+
+# Capturar evidência gráfica do teste
+agent-browser screenshot evidencias/teste-login-sucesso.png
+
+# Verificar erros no console do navegador
+agent-browser console
+```
+
+### 5. Finalização
+
+```bash
+# Fechar a sessão do navegador ao concluir o teste
+agent-browser close
+```
+
+---
+
+## Boas Práticas e Proibições
+
+### Proibido ❌
+- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
+- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
+- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
+- **Proibido deixar processos ou janelas orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`).
+
+### Permitido e Recomendado ✅
+- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
+- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional.
+- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
+
+---
+
+## Impacto
+
+- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real.
+- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto.
+- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos.
+
+---
+
+## Referências
+
+- Documentação Oficial: https://agent-browser.dev/
+- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
+- Ferramentas CLI: `.agent/TOOLS`

global/rules/zod-validacao-padrao.md

@@ -139,7 +139,7 @@ export const zProdutoCriar = z.object({
   nome: z.string().trim().min(1),
   preco: z.coerce.number().positive(),
   ativo: z.boolean().default(true),
-  codigo: z.string().toUpperCase().optional(),
+  codigo: z.string().toUpperCase().nullish(),
   tags: z.array(z.string()).default([]),
 })
 
@@ -149,7 +149,35 @@ produto.nome = produto.nome.trim()
 produto.codigo = produto.codigo?.toUpperCase()
 ```
 
-### 8. Composição e Enums Zod
+### 8. Colunas e Registros que Podem ser Nulos Devem Usar `.nullish()`
+
+Em schemas de tabelas, entidades e contratos de dados que mapeiam colunas do banco de dados ou campos de formulário/API que podem ser nulos ou omitidos, **DEVE-SE obrigatoriamente usar `.nullish()`** (nunca `.optional()` ou `.nullable()` isolados).
+
+**Por que `.nullish()` é obrigatório?**
+- **Bancos relacionais (PostgreSQL/Knex)**: colunas nulas retornam `null`.
+- **Formulários e payloads parciais**: frequentemente omitem o campo (`undefined`) ou enviam `null` ao limpar.
+- `.optional()` aceita apenas `undefined` — **falha** com `Expected string, received null` ao receber dados do banco ou payload com `null`.
+- `.nullable()` aceita apenas `null` — **falha** com `Required` ao omitir o campo em atualizações parciais (`undefined`).
+- `.nullish()` aceita ambos (`T | null | undefined`), garantindo interoperabilidade total entre banco, API e frontend sem erros de runtime.
+
+```typescript
+// ✅ CORRETO — coluna/registro opcional ou nulo com .nullish()
+export const zPontosBase = z.object({
+  id: z.string().max(64).nullish(),
+  nome: z.string().min(1),
+  descricao: z.string().max(5000).nullish(),
+  codigo_empreendimento: zUUID.nullish(),
+  coordenadas: zCoordenadas.nullish(),
+})
+
+// ❌ ERRADO — quebra ao ler do banco quando a coluna for NULL
+descricao: z.string().optional()
+
+// ❌ ERRADO — quebra se o campo for omitido no payload (undefined)
+descricao: z.string().nullable()
+```
+
+### 9. Composição e Enums Zod
 
 ```typescript
 // ✅ Composição de schemas via extend/partial

global/skills/criar-schema-zod/SKILL.md

@@ -72,6 +72,26 @@ export const zUsuarioCriar = z.object({
 | `z{Modulo}Config` | Configuração |
 | `z{Modulo}Ambiente` | Variáveis de ambiente |
 
+### 2.4. Colunas e Campos que Podem ser Nulos: Usar `.nullish()`
+
+Toda coluna do banco de dados relacional ou campo de entidade/registro que puder ser nulo ou omitido **DEVE** utilizar `.nullish()` (nunca `.optional()` ou `.nullable()` isolados):
+
+```typescript
+// ✅ CORRETO — aceita null (do banco PostgreSQL) e undefined (payload omitido)
+export const zPontoCriar = z.object({
+  nome: z.string().min(1),
+  descricao: z.string().max(5000).nullish(),
+  codigo_empreendimento: zUUID.nullish(),
+  coordenadas: zCoordenadas.nullish(),
+})
+
+// ❌ ERRADO — quebra com null retornado pelo Knex/PostgreSQL
+descricao: z.string().optional(),
+
+// ❌ ERRADO — quebra quando a chave é omitida no payload (undefined)
+descricao: z.string().nullable(),
+```
+
 ---
 
 ## PASSO 3 — Derivar o Tipo com `z.infer<>`
@@ -175,6 +195,7 @@ Zero erros = concluído.
 - [ ] A validação usa `safeParse` (exceto em boot/middleware)?
 - [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
 - [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
+- [ ] Colunas e campos que podem ser nulos/opcionais utilizam `.nullish()` (em vez de `.optional()` ou `.nullable()` isolados)?
 - [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
 - [ ] `tsc --noEmit` passa sem erros?
 

global/skills/testar-interface-agent-browser/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: testar-interface-agent-browser
+description: >
+  Executar testes automatizados de interface (E2E), navegação e validação visual
+  no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed).
+scope: global
+---
+
+# Skill: Testar Interface com agent-browser
+
+## Objetivo
+
+Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo que o operador humano sempre acompanhe a execução na tela.
+
+---
+
+## ⚠️ Princípio Fundamental: Navegador Sempre Visível ao Operador
+
+Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na área de trabalho do operador:
+
+- Usar sempre a flag `--headed` na abertura:
+  ```bash
+  agent-browser open --headed <url>
+  ```
+- Ou exportar no ambiente:
+  ```bash
+  export AGENT_BROWSER_HEADED=true
+  ```
+- **Nunca executar em modo headless silencioso**, a menos que o operador humano solicite expressamente essa exceção.
+
+---
+
+## Pré-requisitos e Instalação
+
+```bash
+# Verificar se o agent-browser já está instalado
+which agent-browser || bun i -g agent-browser
+
+# Baixar o binário do Chromium gerenciado pelo daemon (na primeira vez)
+agent-browser install
+```
+
+Documentação oficial: **https://agent-browser.dev/**
+
+---
+
+## Fluxo Operacional Passo a Passo
+
+### 1. Iniciar Sessão Visível
+Abra a aplicação frontend mantendo a janela visível ao operador:
+```bash
+agent-browser open --headed http://localhost:8080
+```
+
+### 2. Obter Snapshot Interativo
+Gere a árvore de acessibilidade enxuta com referências numéricas:
+```bash
+agent-browser snapshot -i
+```
+*Saída de exemplo:*
+```text
+- heading "Qualificação de Fornecedores" [ref=e1]
+- textbox "CNPJ" [ref=e2]
+- textbox "Razão Social" [ref=e3]
+- button "Pesquisar" [ref=e4]
+```
+
+### 3. Interagir com Determinismo
+Utilize as referências identificadas (`@e1`, `@e2`, etc.):
+```bash
+# Preenchimento de campos de texto
+agent-browser fill @e2 "12.345.678/0001-90"
+agent-browser fill @e3 "Indústria Modelo LTDA"
+
+# Acionamento de botões e links
+agent-browser click @e4
+```
+
+### 4. Aguardar Transição e Validar Estado
+Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:
+```bash
+# Aguardar 1 a 2 segundos
+agent-browser wait 1500
+
+# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
+agent-browser snapshot -i
+```
+
+### 5. Verificar Logs de Erro no Console e Rede
+Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:
+```bash
+# Inspecionar mensagens do console do browser
+agent-browser console
+
+# Verificar requisições de rede falhadas
+agent-browser network
+```
+
+### 6. Registrar Evidência Visual
+Capture um screenshot para comprovação do resultado do teste:
+```bash
+# Screenshot padrão ou anotado com identificadores visuais
+agent-browser screenshot evidencias/resultado-sucesso.png
+# agent-browser screenshot --annotate evidencias/resultado-anotado.png
+```
+
+### 7. Encerrar Navegador
+Finalize a sessão limpando os processos do daemon:
+```bash
+agent-browser close
+```
+
+---
+
+## Tabela Rápida de Comandos
+
+| Ação | Comando |
+|---|---|
+| **Abrir tela (visível)** | `agent-browser open --headed <url>` |
+| **Snapshot de elementos** | `agent-browser snapshot -i` |
+| **Clicar elemento** | `agent-browser click @ref` |
+| **Preencher campo** | `agent-browser fill @ref "valor"` |
+| **Selecionar dropdown** | `agent-browser select @ref "opcao"` |
+| **Pressionar tecla** | `agent-browser press Enter` |
+| **Obter texto** | `agent-browser get text @ref` |
+| **Aguardar tempo** | `agent-browser wait <ms>` |
+| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` |
+| **Inspecionar console** | `agent-browser console` |
+| **Inspecionar rede** | `agent-browser network` |
+| **Screenshot** | `agent-browser screenshot <arquivo.png>` |
+| **Auditoria a11y (WCAG)** | `agent-browser a11y` |
+| **Fechar sessão** | `agent-browser close` |
+
+---
+
+## Sessões Persistentes e Autenticação
+
+Para fluxos que necessitam manter login ativo entre comandos:
+```bash
+# Iniciar sessão nomeada com auto-restore
+agent-browser --session auth-test --restore open --headed http://localhost:8080/login
+
+# Verificar status da sessão
+agent-browser session info --json
+```
+
+---
+
+## Skills Nativas do agent-browser
+
+O binário `agent-browser` possui guias aprofundados integrados que podem ser consultados a qualquer momento:
+```bash
+# Guia completo do core (todas as opções e referências)
+agent-browser skills get core --full
+
+# Guia para testes exploratórios e caça a bugs (dogfooding)
+agent-browser skills get dogfood
+```
+
+---
+
+## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify)
+
+1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser fill @ref` ou `agent-browser click @ref`.
+2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser snapshot -i` para interagir com o conteúdo do diálogo.
+3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console.

manifesto.json

@@ -1,6 +1,6 @@
 {
   "versao": "3.2.0",
-  "atualizadoEm": "2026-09-02",
+  "atualizadoEm": "2026-09-16",
   "projeto": "e-licencie",
   "artefatos": {
     "global": {
@@ -28,7 +28,8 @@
         "global/rules/typescript-sem-any.md",
         "global/rules/zod-validacao-padrao.md",
         "global/rules/ddd-documentacao-primeiro.md",
-        "global/rules/identidade-modulo.md"
+        "global/rules/identidade-modulo.md",
+        "global/rules/testes-interface-agent-browser.md"
       ],
       "workflows": [
         "global/workflows/aprimora-ia.md",
@@ -51,7 +52,8 @@
         "global/skills/documentar-regras-negocio/SKILL.md",
         "global/skills/mapear-codigo-fonte/SKILL.md",
         "global/skills/onboarding-projeto/SKILL.md",
-        "global/skills/orquestrar-agentes/SKILL.md"
+        "global/skills/orquestrar-agentes/SKILL.md",
+        "global/skills/testar-interface-agent-browser/SKILL.md"
       ]
     },
     "documentacao": {
@@ -183,7 +185,8 @@
         "persona": "agents/testes/persona",
         "config": "agents/testes/agent.json",
         "skills": [
-          "agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md"
+          "agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md",
+          "skills/testar-interface-agent-browser/SKILL.md"
         ]
       },
       "ux": {

rules/testes-interface-agent-browser.md

@@ -0,0 +1,133 @@
+---
+type: rule
+name: testes-interface-agent-browser
+description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) ao operador.
+scope: global
+trigger: always_on
+updatedAt: "2026-09-16"
+---
+
+# Regra: Testes Automatizados de Interface e Navegação com agent-browser
+
+## Contexto
+
+Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica.
+
+Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA.
+
+---
+
+## Regra
+
+Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**:
+
+1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador.
+2. **Executar SEMPRE em Modo Visível (`--headed`)**:
+   - A janela do navegador **deve sempre aparecer na área de trabalho do operador**.
+   - É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção.
+   - Usar a flag `--headed` nos comandos de abertura (`agent-browser open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
+3. **Utilizar o modelo de referências (`@ref`)**:
+   - Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
+   - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
+4. **Registrar evidências e fechar sessão**:
+   - Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
+   - Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
+
+---
+
+## Instalação e Configuração
+
+O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
+
+```bash
+# Instalação global via bun (recomendado)
+bun i -g agent-browser
+
+# Download do motor do navegador (primeira execução)
+agent-browser install
+```
+
+Documentação de referência: **https://agent-browser.dev/**
+
+---
+
+## Protocolo Operacional Padrão
+
+Todo teste ou navegação de interface executado pela IA deve seguir o fluxo:
+
+### 1. Abertura com Janela Visível
+
+```bash
+# Abrir sempre visível ao operador humano
+agent-browser open --headed http://localhost:8080
+```
+
+### 2. Inspeção de Elementos Interativos
+
+```bash
+# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2)
+agent-browser snapshot -i
+```
+
+### 3. Interações por Referência Direta
+
+```bash
+# Interagir diretamente com os elementos identificados no snapshot
+agent-browser fill @e1 "usuario@exemplo.com"
+agent-browser fill @e2 "senhaSegura123"
+agent-browser click @e3
+```
+
+### 4. Validação e Evidência
+
+```bash
+# Aguardar estabilização se houver transição assíncrona
+agent-browser wait 1000
+
+# Obter novo snapshot para verificar estado pós-ação
+agent-browser snapshot -i
+
+# Capturar evidência gráfica do teste
+agent-browser screenshot evidencias/teste-login-sucesso.png
+
+# Verificar erros no console do navegador
+agent-browser console
+```
+
+### 5. Finalização
+
+```bash
+# Fechar a sessão do navegador ao concluir o teste
+agent-browser close
+```
+
+---
+
+## Boas Práticas e Proibições
+
+### Proibido ❌
+- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
+- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
+- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
+- **Proibido deixar processos ou janelas orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`).
+
+### Permitido e Recomendado ✅
+- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
+- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional.
+- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
+
+---
+
+## Impacto
+
+- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real.
+- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto.
+- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos.
+
+---
+
+## Referências
+
+- Documentação Oficial: https://agent-browser.dev/
+- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
+- Ferramentas CLI: `.agent/TOOLS`

rules/zod-validacao-padrao.md

@@ -139,7 +139,7 @@ export const zProdutoCriar = z.object({
   nome: z.string().trim().min(1),
   preco: z.coerce.number().positive(),
   ativo: z.boolean().default(true),
-  codigo: z.string().toUpperCase().optional(),
+  codigo: z.string().toUpperCase().nullish(),
   tags: z.array(z.string()).default([]),
 })
 
@@ -149,7 +149,35 @@ produto.nome = produto.nome.trim()
 produto.codigo = produto.codigo?.toUpperCase()
 ```
 
-### 8. Composição e Enums Zod
+### 8. Colunas e Registros que Podem ser Nulos Devem Usar `.nullish()`
+
+Em schemas de tabelas, entidades e contratos de dados que mapeiam colunas do banco de dados ou campos de formulário/API que podem ser nulos ou omitidos, **DEVE-SE obrigatoriamente usar `.nullish()`** (nunca `.optional()` ou `.nullable()` isolados).
+
+**Por que `.nullish()` é obrigatório?**
+- **Bancos relacionais (PostgreSQL/Knex)**: colunas nulas retornam `null`.
+- **Formulários e payloads parciais**: frequentemente omitem o campo (`undefined`) ou enviam `null` ao limpar.
+- `.optional()` aceita apenas `undefined` — **falha** com `Expected string, received null` ao receber dados do banco ou payload com `null`.
+- `.nullable()` aceita apenas `null` — **falha** com `Required` ao omitir o campo em atualizações parciais (`undefined`).
+- `.nullish()` aceita ambos (`T | null | undefined`), garantindo interoperabilidade total entre banco, API e frontend sem erros de runtime.
+
+```typescript
+// ✅ CORRETO — coluna/registro opcional ou nulo com .nullish()
+export const zPontosBase = z.object({
+  id: z.string().max(64).nullish(),
+  nome: z.string().min(1),
+  descricao: z.string().max(5000).nullish(),
+  codigo_empreendimento: zUUID.nullish(),
+  coordenadas: zCoordenadas.nullish(),
+})
+
+// ❌ ERRADO — quebra ao ler do banco quando a coluna for NULL
+descricao: z.string().optional()
+
+// ❌ ERRADO — quebra se o campo for omitido no payload (undefined)
+descricao: z.string().nullable()
+```
+
+### 9. Composição e Enums Zod
 
 ```typescript
 // ✅ Composição de schemas via extend/partial

skills/criar-schema-zod/SKILL.md

@@ -72,6 +72,26 @@ export const zUsuarioCriar = z.object({
 | `z{Modulo}Config` | Configuração |
 | `z{Modulo}Ambiente` | Variáveis de ambiente |
 
+### 2.4. Colunas e Campos que Podem ser Nulos: Usar `.nullish()`
+
+Toda coluna do banco de dados relacional ou campo de entidade/registro que puder ser nulo ou omitido **DEVE** utilizar `.nullish()` (nunca `.optional()` ou `.nullable()` isolados):
+
+```typescript
+// ✅ CORRETO — aceita null (do banco PostgreSQL) e undefined (payload omitido)
+export const zPontoCriar = z.object({
+  nome: z.string().min(1),
+  descricao: z.string().max(5000).nullish(),
+  codigo_empreendimento: zUUID.nullish(),
+  coordenadas: zCoordenadas.nullish(),
+})
+
+// ❌ ERRADO — quebra com null retornado pelo Knex/PostgreSQL
+descricao: z.string().optional(),
+
+// ❌ ERRADO — quebra quando a chave é omitida no payload (undefined)
+descricao: z.string().nullable(),
+```
+
 ---
 
 ## PASSO 3 — Derivar o Tipo com `z.infer<>`
@@ -175,6 +195,7 @@ Zero erros = concluído.
 - [ ] A validação usa `safeParse` (exceto em boot/middleware)?
 - [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
 - [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
+- [ ] Colunas e campos que podem ser nulos/opcionais utilizam `.nullish()` (em vez de `.optional()` ou `.nullable()` isolados)?
 - [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
 - [ ] `tsc --noEmit` passa sem erros?
 

skills/testar-interface-agent-browser/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: testar-interface-agent-browser
+description: >
+  Executar testes automatizados de interface (E2E), navegação e validação visual
+  no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed).
+scope: global
+---
+
+# Skill: Testar Interface com agent-browser
+
+## Objetivo
+
+Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo que o operador humano sempre acompanhe a execução na tela.
+
+---
+
+## ⚠️ Princípio Fundamental: Navegador Sempre Visível ao Operador
+
+Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na área de trabalho do operador:
+
+- Usar sempre a flag `--headed` na abertura:
+  ```bash
+  agent-browser open --headed <url>
+  ```
+- Ou exportar no ambiente:
+  ```bash
+  export AGENT_BROWSER_HEADED=true
+  ```
+- **Nunca executar em modo headless silencioso**, a menos que o operador humano solicite expressamente essa exceção.
+
+---
+
+## Pré-requisitos e Instalação
+
+```bash
+# Verificar se o agent-browser já está instalado
+which agent-browser || bun i -g agent-browser
+
+# Baixar o binário do Chromium gerenciado pelo daemon (na primeira vez)
+agent-browser install
+```
+
+Documentação oficial: **https://agent-browser.dev/**
+
+---
+
+## Fluxo Operacional Passo a Passo
+
+### 1. Iniciar Sessão Visível
+Abra a aplicação frontend mantendo a janela visível ao operador:
+```bash
+agent-browser open --headed http://localhost:8080
+```
+
+### 2. Obter Snapshot Interativo
+Gere a árvore de acessibilidade enxuta com referências numéricas:
+```bash
+agent-browser snapshot -i
+```
+*Saída de exemplo:*
+```text
+- heading "Qualificação de Fornecedores" [ref=e1]
+- textbox "CNPJ" [ref=e2]
+- textbox "Razão Social" [ref=e3]
+- button "Pesquisar" [ref=e4]
+```
+
+### 3. Interagir com Determinismo
+Utilize as referências identificadas (`@e1`, `@e2`, etc.):
+```bash
+# Preenchimento de campos de texto
+agent-browser fill @e2 "12.345.678/0001-90"
+agent-browser fill @e3 "Indústria Modelo LTDA"
+
+# Acionamento de botões e links
+agent-browser click @e4
+```
+
+### 4. Aguardar Transição e Validar Estado
+Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:
+```bash
+# Aguardar 1 a 2 segundos
+agent-browser wait 1500
+
+# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
+agent-browser snapshot -i
+```
+
+### 5. Verificar Logs de Erro no Console e Rede
+Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:
+```bash
+# Inspecionar mensagens do console do browser
+agent-browser console
+
+# Verificar requisições de rede falhadas
+agent-browser network
+```
+
+### 6. Registrar Evidência Visual
+Capture um screenshot para comprovação do resultado do teste:
+```bash
+# Screenshot padrão ou anotado com identificadores visuais
+agent-browser screenshot evidencias/resultado-sucesso.png
+# agent-browser screenshot --annotate evidencias/resultado-anotado.png
+```
+
+### 7. Encerrar Navegador
+Finalize a sessão limpando os processos do daemon:
+```bash
+agent-browser close
+```
+
+---
+
+## Tabela Rápida de Comandos
+
+| Ação | Comando |
+|---|---|
+| **Abrir tela (visível)** | `agent-browser open --headed <url>` |
+| **Snapshot de elementos** | `agent-browser snapshot -i` |
+| **Clicar elemento** | `agent-browser click @ref` |
+| **Preencher campo** | `agent-browser fill @ref "valor"` |
+| **Selecionar dropdown** | `agent-browser select @ref "opcao"` |
+| **Pressionar tecla** | `agent-browser press Enter` |
+| **Obter texto** | `agent-browser get text @ref` |
+| **Aguardar tempo** | `agent-browser wait <ms>` |
+| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` |
+| **Inspecionar console** | `agent-browser console` |
+| **Inspecionar rede** | `agent-browser network` |
+| **Screenshot** | `agent-browser screenshot <arquivo.png>` |
+| **Auditoria a11y (WCAG)** | `agent-browser a11y` |
+| **Fechar sessão** | `agent-browser close` |
+
+---
+
+## Sessões Persistentes e Autenticação
+
+Para fluxos que necessitam manter login ativo entre comandos:
+```bash
+# Iniciar sessão nomeada com auto-restore
+agent-browser --session auth-test --restore open --headed http://localhost:8080/login
+
+# Verificar status da sessão
+agent-browser session info --json
+```
+
+---
+
+## Skills Nativas do agent-browser
+
+O binário `agent-browser` possui guias aprofundados integrados que podem ser consultados a qualquer momento:
+```bash
+# Guia completo do core (todas as opções e referências)
+agent-browser skills get core --full
+
+# Guia para testes exploratórios e caça a bugs (dogfooding)
+agent-browser skills get dogfood
+```
+
+---
+
+## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify)
+
+1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser fill @ref` ou `agent-browser click @ref`.
+2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser snapshot -i` para interagir com o conteúdo do diálogo.
+3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console.