versão 1

2026-06-18 11:59:57 -03:00 · 2026-06-18 11:59:57 -03:00 · 1cb4c14d33
commit 1cb4c14d33
85 changed files with 11836 additions and 0 deletions
--- a/agents/ag-front/persona.md
+++ b/agents/ag-front/persona.md
@ -0,0 +1,77 @@
+---
+name: ag-front
+display_name: "Agente Frontend"
+description: >
+  Responsável pelo desenvolvimento da interface do software, implementação das telas,
+  fluxos de uso, integração com APIs e regras necessárias para a experiência do usuário.
+scope: [front]
+inherits: [global]
+tools:
+  - view_file
+  - list_dir
+  - grep_search
+  - write_to_file
+  - replace_file_content
+  - multi_replace_file_content
+  - run_command
+  - send_message
+---
+
+# Agente Frontend (@ag-front)
+
+## Identidade
+
+Você é o agente especialista em desenvolvimento frontend do ecossistema Azteca. Você constrói interfaces Vue 3 que são funcionais, acessíveis, bem organizadas e que comunicam com clareza ao usuário técnico do domínio ambiental.
+
+## Escopo de Atuação
+
+- Pacotes: `*-front`
+- Linguagem: TypeScript + Vue 3
+- Framework UI: Vuetify
+- Validação: Zod (schemas importados de `*-comuns`)
+- Importações permitidas de: `*-comuns` apenas
+
+## Responsabilidades
+
+1. Implementar páginas e componentes Vue 3 (`paginas/`, `componentes/`)
+2. Criar composables reutilizáveis (`composables/use*.ts`)
+3. Integrar com APIs do backend via `*-comuns` (schemas compartilhados)
+4. Garantir mensagens de UI no vocabulário do domínio (não técnico)
+5. Extrair CSS para arquivos co-localizados quando necessário
+6. Manter componentes dentro do limite de 250 linhas
+7. Implementar fluxos de navegação e estados de interface
+
+## Restrições
+
+- NUNCA importar de pacotes `*-back` diretamente
+- NUNCA usar `any` ou `as any`
+- Todo componente Vue deve usar `defineComponent` com `setup()`
+- `setup()` não pode ser um proxy vazio — lógica real deve estar dentro do `.vue`
+- CSS extenso deve ser extraído para arquivo co-localizado (`.css`)
+- Mensagens visíveis ao usuário devem estar em linguagem do domínio, sem jargões técnicos
+- Schemas Zod importados de `*-comuns` — nunca redefinidos no front
+
+## Colaborações
+
+- **Recebe schemas de:** `@ag-back` (via `*-comuns`)
+- **Recebe especificações de:** `@ag-arquiteto`
+- **Recebe diretrizes de UX de:** `@ag-ux`
+- **Entrega para validação:** `@ag-testes`
+- **Entrega build para:** `@ag-deploy`
+
+## Tom e Estilo
+
+- Foco na experiência do usuário técnico (engenheiros, gestores ambientais)
+- Componentes pequenos e composáveis
+- Nomes descritivos em português para variáveis de domínio
+- Estados de interface explícitos: loading, erro, vazio, sucesso
+
+## Checklist antes de entregar tela
+
+- [ ] Componente abaixo de 250 linhas?
+- [ ] CSS extraído se contribui para o limite?
+- [ ] Mensagens ao usuário sem termos técnicos?
+- [ ] `defineComponent` com `setup()` real?
+- [ ] Schemas importados de `*-comuns`?
+- [ ] Estados de loading, erro e vazio implementados?
+- [ ] Build passa (`tsc --noEmit` + `biome check`)?
--- a/agents/ag-front/rules/escrita-natural.md
+++ b/agents/ag-front/rules/escrita-natural.md
@ -0,0 +1,169 @@
+---
+type: rule
+name: escrita-natural
+trigger: context_match
+description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica.
+scope: global
+updatedAt: "2026-06-01"
+ativacao: >
+  Aplicar quando o agente estiver produzindo textos comerciais, de marketing,
+  orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo.
+  NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio).
+---
+
+# Regra: Escrita Estratégica e Natural
+
+## 🎯 Objetivo
+
+Produzir textos que:
+
+- Mostrem domínio real do problema
+- Se destaquem entre propostas genéricas
+- Soem humanos, não institucionais
+- Convençam com clareza e impacto
+
+---
+
+## 🧠 Princípios obrigatórios
+
+### 1. Começar pelo problema real
+
+Evitar introduções genéricas.
+
+❌
+"O presente projeto tem como objetivo..."
+
+✅
+"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios."
+
+---
+
+### 2. Conectar problema → solução → impacto
+
+Cada parágrafo deve seguir uma lógica clara:
+
+- Qual é o problema?
+- Como a solução resolve?
+- O que muda na prática?
+
+✅ Exemplo:
+"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho."
+
+---
+
+### 3. Usar exemplos concretos (sempre que possível)
+
+Todo conceito deve ser ancorado na prática.
+
+❌
+"A solução permite coleta de dados estruturados."
+
+✅
+"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet."
+
+---
+
+### 4. Escrever como quem vive o problema
+
+O texto deve ter contexto real:
+
+- campo
+- operação
+- prefeitura
+- equipe técnica
+
+✅
+"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos."
+
+---
+
+### 5. Persuasão baseada em impacto real
+
+Evitar adjetivos vazios.
+
+❌
+"Solução inovadora e eficiente"
+
+✅
+"A solução elimina falhas críticas e garante rastreabilidade completa das informações."
+
+---
+
+### 6. Linguagem natural (sem burocracia)
+
+Preferir:
+
+- "Com a solução..."
+- "Na prática..."
+- "Isso permite..."
+- "Como resultado..."
+
+Evitar:
+
+- "Dessa forma"
+- "Destarte"
+- "O presente projeto"
+
+---
+
+### 7. Variar estrutura de frases (regra crítica)
+
+Nunca repetir padrões como:
+
+- "A solução permite..."
+- "O sistema permite..."
+
+Alternar com:
+
+- "Na prática, o técnico..."
+- "Com isso..."
+- "Isso reduz..."
+- "Como resultado..."
+
+---
+
+### 8. Parágrafos objetivos
+
+- 2 a 4 linhas
+- Uma ideia principal por parágrafo
+- Explica bem sem ser longo
+
+---
+
+### 9. Tom humano e próximo
+
+O texto deve parecer escrito por quem constrói a solução.
+
+✅
+"A solução resolve um problema real que impacta o dia a dia das equipes."
+
+---
+
+## 🚫 Proibido
+
+- Texto genérico que serve para qualquer projeto
+- Parágrafos longos sem exemplo
+- Repetição de estrutura
+- Uso de termos sem explicação prática
+- Linguagem excessivamente institucional
+
+---
+
+## 🔍 Checklist final
+
+Antes de finalizar:
+
+- [ ] O problema está claro?
+- [ ] Existe exemplo prático?
+- [ ] O impacto está explícito?
+- [ ] O texto soa humano?
+- [ ] Há repetição de estrutura?
+- [ ] Parece algo real ou genérico?
+
+---
+
+## 💡 Regra de ouro
+
+Se o texto poderia ser usado por qualquer empresa → está errado.
+
+Se parece que vem de quem vive o problema → está certo.
--- a/agents/ag-front/rules/estrutura-vue.md
+++ b/agents/ag-front/rules/estrutura-vue.md
@ -0,0 +1,86 @@
+---
+type: rule
+name: estrutura-vue
+description: Padrões obrigatórios de estrutura para componentes Vue 3 (defineComponent, setup, CSS, dispatch)
+scope: global
+trigger: file_match
+globs:
+  - "**/*.vue"
+updatedAt: "2026-06-01"
+---
+
+# Regra: Estrutura de Componentes Vue
+
+## 1. `defineComponent` obrigatório
+
+Todo componente Vue deve usar `defineComponent`:
+
+```vue
+<script lang="ts">
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  name: 'MeuComponente',
+  setup() {
+    // lógica aqui
+  }
+})
+</script>
+```
+
+## 2. `setup()` não pode ser externo
+
+O `setup()` deve estar sempre dentro do `.vue`. Nunca delegar para arquivo externo.
+
+```ts
+// ❌ Proibido — setup esvaziado
+export default defineComponent({
+  setup(props, { emit }) {
+    return useEliTabela(props, emit)  // proxy vazio
+  }
+})
+
+// ✅ Correto — setup com lógica própria
+export default defineComponent({
+  setup(props, { emit }) {
+    const estado = ref(null)
+    const carregar = async () => { ... }
+    return { estado, carregar }
+  }
+})
+```
+
+> Composables `use*.ts` podem encapsular lógica reutilizável pontual, mas nunca substituir o `setup()`. Se ultrapassar 250 linhas → extrair subcomponentes, CSS ou Dispatch Table.
+
+## 3. CSS co-localizado
+
+Separação de estilos em arquivo externo quando o CSS contribui para o total de linhas:
+
+```
+MeuComponente.vue
+MeuComponente.css
+```
+
+Importar via `import './MeuComponente.css'` ou `<style src="./MeuComponente.css" />`.
+
+## 4. Dispatch Table
+
+Uso de mapa de funções para eliminar `if/else` ou `switch` longos:
+
+```ts
+// handlers.ts
+export const acaoHandlers: Record<string, () => void> = {
+  salvar: () => { ... },
+  cancelar: () => { ... },
+  excluir: () => { ... },
+}
+```
+
+## Impacto
+
+Sem estes padrões, componentes perdem inferência de tipos, lógica fica inauditável em composables externos, e CSS cresce inline sem controle.
+
+## Referências
+
+- Rule: `.agent/rules/limite-linhas.global.md`
+- Rule: `.agent/rules/typescript-sem-any.global.md`
--- a/agents/ag-front/rules/mensagens-usuario.md
+++ b/agents/ag-front/rules/mensagens-usuario.md
@ -0,0 +1,123 @@
+---
+type: rule
+name: mensagens-usuario
+description: Toda mensagem visível ao usuário final deve ser escrita em linguagem do domínio, sem termos técnicos de TI
+scope: global
+trigger: file_match
+globs:
+  - "**/*.vue"
+  - "**/*.ts"
+  - "**/*.tsx"
+updatedAt: "2026-06-01"
+---
+
+# Regra: Mensagens Orientadas ao Domínio
+
+## Contexto
+
+O usuário final dos módulos SaaS é profissional de **engenharia, ciência ou gestão ambiental**. Ele entende de legislação, processos técnicos e ciência aplicada — mas **não tem obrigação de entender tecnologia**.
+
+Toda mensagem visível na interface — erro, validação, confirmação, tooltip, empty state, ajuda — deve ser escrita na linguagem do domínio do módulo.
+
+## Regra
+
+### 1. Erros de validação devem indicar O QUE preencher, não O QUE falhou
+
+```typescript
+// ❌ ERRADO — linguagem técnica
+"Campo obrigatório"
+"Erro de validação"
+"Formato inválido"
+"Payload inválido"
+
+// ✅ CORRETO — linguagem do domínio
+"Informe a Área do Empreendimento (em hectares)"
+"Selecione o Tipo de Licença: LP, LI ou LO"
+"A Data da Vistoria deve ser anterior à data atual"
+"Informe o CNPJ no formato 00.000.000/0000-00"
+```
+
+### 2. Erros de sistema devem ser traduzidos para o usuário
+
+```typescript
+// ❌ ERRADO — erro técnico exposto
+"Erro 500: Internal Server Error"
+"Timeout na requisição"
+"Network Error"
+"ECONNREFUSED"
+
+// ✅ CORRETO — mensagem humanizada
+"Não foi possível salvar. Tente novamente em instantes."
+"A operação demorou mais que o esperado. Tente novamente."
+"Sem conexão com o servidor. Verifique sua internet."
+```
+
+### 3. Estados vazios devem explicar o contexto
+
+Quando uma lista ou tabela está vazia, a mensagem deve orientar o usuário:
+
+```typescript
+// ❌ ERRADO — genérico
+"Nenhum registro encontrado"
+"Lista vazia"
+
+// ✅ CORRETO — explica o domínio e orienta
+"Nenhuma condicionante cadastrada para esta licença."
+"Nenhum relatório de monitoramento registrado neste período."
+"Nenhum empreendimento encontrado com os filtros aplicados. Tente ampliar a busca."
+```
+
+### 4. Confirmações devem descrever a consequência
+
+```typescript
+// ❌ ERRADO — genérico
+"Tem certeza que deseja excluir?"
+"Confirmar operação?"
+
+// ✅ CORRETO — descreve o impacto
+"Excluir esta condicionante? O prazo de cumprimento e os documentos vinculados serão removidos."
+"Arquivar esta licença? Ela não aparecerá mais nas listagens ativas."
+```
+
+### 5. Labels e placeholders devem usar vocabulário do domínio
+
+```typescript
+// ❌ ERRADO — genérico
+label: "Nome"
+placeholder: "Digite aqui"
+
+// ✅ CORRETO — específico do domínio
+label: "Razão Social do Empreendedor"
+placeholder: "Ex: Mineração Vale Verde Ltda."
+
+label: "Área Total do Empreendimento"
+placeholder: "Em hectares (ex: 150,5)"
+```
+
+### 6. Schemas Zod devem ter mensagens de domínio
+
+```typescript
+// ❌ ERRADO — mensagens padrão do Zod
+const zEmpreendimento = z.object({
+  nome: z.string().min(1),                // "String must contain at least 1 character(s)"
+  area: z.number().positive(),            // "Number must be greater than 0"
+})
+
+// ✅ CORRETO — mensagens customizadas
+const zEmpreendimento = z.object({
+  nome: z.string().min(1, "Informe o nome do empreendimento"),
+  area: z.number({ invalid_type_error: "A área deve ser um número" })
+    .positive("A área deve ser maior que zero"),
+  cnpj: z.string().regex(/^\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}$/,
+    "CNPJ inválido. Use o formato 00.000.000/0000-00"),
+})
+```
+
+## Impacto
+
+Sem esta regra, o agente gera mensagens técnicas que confundem gestores ambientais, consultores e técnicos de campo — forçando a equipe de suporte a traduzir erros de sistema para o vocabulário do cliente.
+
+## Referências
+
+- Rule: `.agent/rules/zod-validacao-padrao.global.md` (schemas com mensagens customizadas)
+- Workflow: `.agent/workflows/ux.global.md` (design de interface)
--- a/agents/ag-front/workflows/adicionar-ajuda.md
+++ b/agents/ag-front/workflows/adicionar-ajuda.md
@ -0,0 +1,118 @@
+---
+type: workflow
+name: adicionar-ajuda
+description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
+scope: global
+updatedAt: "2026-06-01"
+---
+
+# Workflow: Adicionar Ajuda em Telas
+
+Este workflow automatiza a inserção do botão de ajuda e a criação do arquivo de documentação correspondente sempre que uma tela é criada ou modificada de forma significativa.
+
+O objetivo da ajuda é **auxiliar o usuário final a compreender e utilizar corretamente a aplicação**, explicando o funcionamento da tela de forma clara e objetiva.
+
+## Pré-requisitos
+
+- O arquivo alvo deve ser um componente de interface (`.tsx` para React ou `.vue` para Vue).
+- O projeto deve possuir um componente de ajuda (ex: `BotaoAjuda`, `HelpButton` ou equivalente) disponível para uso na interface.
+- Caso não exista, criar um componente reutilizável que exiba o conteúdo do `.ajuda.md` em modal ou drawer.
+
+## Passos
+
+### 1. Identificar o Componente Alvo
+
+Determine qual arquivo representa a tela principal ou modal que está sendo criado ou editado.
+
+- React → `.tsx`
+- Vue → `.vue`
+
+### 2. Verificar Existência de Ajuda
+
+Procure por um arquivo de ajuda com o mesmo nome do componente e sufixo indicativo de ajuda (ex.: `.ajuda.md`) localizado na mesma pasta.
+
+Exemplo:
+
+```
+
+TelaCadastroUsuario.tsx
+TelaCadastroUsuario.ajuda.md
+
+```
+
+ou
+
+```
+
+TelaCadastroUsuario.vue
+TelaCadastroUsuario.ajuda.md
+
+````
+
+### 3. Criar ou Atualizar o Arquivo Markdown
+
+Se o arquivo `.ajuda.md` não existir, crie-o utilizando o template básico abaixo.
+
+O conteúdo deve ser escrito **pensando no usuário final**, explicando de forma simples como utilizar a tela.
+
+A documentação deve incluir, quando aplicável:
+
+- **Objetivo da tela**
+- **Descrição dos botões**
+- **Descrição dos campos de formulário**
+- **Regras de preenchimento e validações**
+- **Fluxo esperado de uso**
+- **Contexto técnico ou legal**, quando relevante para o entendimento da funcionalidade
+
+Template inicial:
+
+```markdown
+# Ajuda: [Nome da Tela]
+
+## Objetivo da Tela
+
+Explique de forma simples para que serve esta tela dentro do sistema.
+
+## Botões
+
+- **Salvar**: grava as informações preenchidas.
+- **Cancelar**: descarta as alterações realizadas.
+- **Excluir**: remove o registro atual do sistema.
+
+## Campos do Formulário
+
+- **Nome**: informe o nome completo do responsável.
+- **Data de Vistoria**: data em que a vistoria foi realizada.
+- **Observações**: campo livre para registrar informações adicionais.
+
+## Fluxo de Uso
+
+1. Preencha os campos obrigatórios.
+2. Revise as informações inseridas.
+3. Clique em **Salvar** para registrar os dados no sistema.
+
+## Informações Técnicas ou Legais (quando aplicável)
+
+Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.
+````
+
+### 4. Posicionamento do Botão de Ajuda
+
+O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.
+
+#### Telas / Páginas
+
+* O botão deve ficar na **parte inferior esquerda da página**.
+* Deve respeitar espaçamento suficiente das bordas da interface.
+* **Não pode sobrepor nenhum componente da tela.**
+* **Não pode ficar oculto ou sobreposto pela barra de módulos da aplicação.**
+* Ajustar `margin`, `padding` ou `z-index` quando necessário para garantir visibilidade adequada.
+
+#### Modais e Diálogos
+
+* O botão deve ficar na **parte inferior esquerda do modal**.
+* Preferencialmente no rodapé do modal ou em um container equivalente.
+* **Não pode sobrepor botões ou ações do modal.**
+* Garantir espaçamento adequado para não interferir na usabilidade.
+
+
--- a/agents/ag-front/workflows/criar-fluxograma.md
+++ b/agents/ag-front/workflows/criar-fluxograma.md
@ -0,0 +1,189 @@
+---
+type: workflow
+name: criar-fluxograma
+description: Criar ou atualizar uma página de fluxograma interativo em qualquer sistema
+scope: global
+updatedAt: "2026-06-01"
+---
+
+# Workflow: Criar Fluxograma de Decisões
+
+Este workflow cria uma **página interativa de fluxograma** em qualquer aplicação web, usando Mermaid.js instalado como dependência do projeto.
+
+## Princípio
+
+O fluxograma é um artefato vivo. Ele documenta visualmente:
+- Os **pontos de entrada** do processo
+- As **decisões** tomadas em cada etapa
+- Os **registros gerados** (banco, fila, log, e-mail, etc.)
+- As **proteções e regras** que governam os estados
+
+Deve ser mantido sempre sincronizado com o código real.
+
+---
+
+## Passos
+
+### 1. Levantar o processo a ser documentado
+
+Ler os arquivos de código relevantes para entender:
+
+- Quais são os **pontos de entrada**? (funções de API, eventos, webhooks, ações do usuário)
+- Quais são as **decisões**? (condições `if/else`, guards, validações)
+- Quais são os **efeitos colaterais**? (gravações em banco, envios de e-mail, filas, logs)
+- Quais são os **estados possíveis**? (status, notas, flags, etapas)
+- Existe **hierarquia ou prioridade** entre estados?
+
+### 2. Organizar os diagramas
+
+Dividir o processo em **um diagrama por ponto de entrada**.
+
+Cada diagrama deve mostrar:
+- Todos os caminhos possíveis, inclusive early returns e casos de erro
+- Registros gerados com ícone indicativo (ex: 🗄️ banco, 📧 e-mail, 🚫 bloqueio)
+- Decisões claramente separadas por ramificações
+
+Definir a orientação de cada diagrama:
+- `flowchart TD` → vertical (melhor para fluxos sequenciais com poucas ramificações)
+- `flowchart LR` → horizontal (melhor para pipelines e fluxos com muitas etapas em linha)
+
+### 3. Instalar o Mermaid
+
+Instalar como dependência do projeto antes de qualquer implementação:
+
+```bash
+# npm
+npm install mermaid
+
+# pnpm
+pnpm add mermaid
+```
+
+### 4. Criar a página com Mermaid
+
+Adaptar à plataforma do projeto (Vue, React, HTML puro, etc.), mas garantir:
+
+#### Importação
+
+```js
+import mermaid from 'mermaid';
+```
+
+#### Inicialização com tema institucional
+
+Adaptar as cores para a identidade visual do projeto:
+
+```js
+mermaid.initialize({
+  startOnLoad: false,
+  theme: 'base',
+  themeVariables: {
+    primaryColor: '#4F46E5',       // cor primária do projeto
+    primaryTextColor: '#1F2933',
+    primaryBorderColor: '#3730A3', // variação mais escura da primária
+    lineColor: '#6B7280',
+    secondaryColor: '#E0E7FF',     // variação clara da primária
+    tertiaryColor: '#F3F4F6',
+    fontFamily: "'Inter', 'Segoe UI', sans-serif",
+    fontSize: '13px',
+  },
+});
+```
+
+#### Renderização de cada diagrama
+
+```js
+// Para cada diagrama:
+const { svg } = await mermaid.render(`id-unico-${idx}`, codigoMermaid);
+container.innerHTML = svg;
+
+// Tornar o SVG responsivo:
+const svgEl = container.querySelector('svg');
+if (svgEl) {
+  svgEl.style.width = '100%';
+  svgEl.style.height = 'auto';
+  svgEl.removeAttribute('width');
+}
+```
+
+### 5. Registrar a rota e adicionar acesso
+
+- Registrar a rota `/fluxograma` (ou equivalente) no sistema de rotas do projeto
+- Adicionar botão de navegação na tela de administração ou dashboard
+
+---
+
+## Padrão de sintaxe Mermaid
+
+### Tipos de nó por semântica
+
+| Situação | Sintaxe | Exemplo |
+|---|---|---|
+| Início / Fim | `A(["Texto"])` | `A(["Início"])` |
+| Decisão | `B{"Condição?"}` | `B{"Nota é ativa?"}` |
+| Ação / Processo | `C["Texto"]` | `C["Consulta banco"]` |
+| Registro em banco | `D[("🗄️ Grava dado")]` | `D[("🗄️ Grava 203_neutro")]` |
+| E-mail / notificação | `E["📧 Envia e-mail"]` | `E["📧 Agenda na fila"]` |
+| Bloqueio / guard | `F["🚫 Retorna sem ação"]` | `F["🚫 Nota ativa, ignora"]` |
+| Proteção / regra | `G["🛡️ Regra aplicada"]` | `G["🛡️ SQL CASE protege"]` |
+
+### Regras para evitar erros de parsing
+
+```
+✅ Nós com parênteses → usar aspas:
+   A["Texto (com parênteses)"]
+
+✅ Labels de arestas com texto especial → usar aspas:
+   A -- "Label aqui" --> B
+
+✅ Emojis → sempre dentro de aspas:
+   A["🗄️ Grava registro"]
+
+❌ Não usar < > dentro de labels sem aspas
+❌ Não usar & diretamente — usar texto alternativo
+```
+
+### Cores de destaque para nós
+
+```
+style NomeNo fill:#22C55E,color:#fff    → verde sucesso
+style NomeNo fill:#DC2626,color:#fff    → vermelho erro
+style NomeNo fill:#F59E0B,color:#000    → amarelo alerta
+style NomeNo fill:#4F46E5,color:#fff    → cor institucional (adaptar ao projeto)
+style NomeNo fill:#6B7280,color:#fff    → cinza neutro
+```
+
+---
+
+## Validação antes de finalizar
+
+- [ ] Cada ponto de entrada tem seu próprio diagrama?
+- [ ] Todos os registros gerados estão mapeados?
+- [ ] Os caminhos de bloqueio e early return estão visíveis?
+- [ ] A hierarquia de estados (se existir) está documentada?
+- [ ] A data de atualização está registrada na página?
+- [ ] A sintaxe Mermaid está correta (sem erros de parsing)?
+- [ ] O SVG está responsivo (largura 100%, sem width fixo)?
+
+---
+
+## Manutenção
+
+Sempre que o processo mudar:
+
+1. Identificar qual diagrama é afetado
+2. Atualizar o código Mermaid correspondente
+3. Atualizar a data de atualização na página
+4. Se houver novo estado ou proteção, documentar na legenda
+
+---
+
+## Referência de implementação
+
+Se o projeto já possuir um fluxograma implementado, usar como referência.
+Caso contrário, seguir os passos acima para criar a primeira implementação.
+
+## Referências
+
+- Workflow: `.agent/workflows/otimizar-codigos.global.md`
+- Skill: `.agent/skills/documentar-decisao-tecnica.global/SKILL.md` (para decisões que geram fluxogramas)
--- a/agents/ag-front/workflows/ux.md
+++ b/agents/ag-front/workflows/ux.md
@ -0,0 +1,257 @@
+---
+type: workflow
+name: ux
+description: Revisar e otimizar UX de componentes e telas Vue (Frontend)
+scope: global
+updatedAt: "2026-06-01"
+---
+
+# Workflow: Revisão de UX
+
+Guia de revisão e otimização de interfaces Vue 3 + Vuetify 3 no ecossistema Azteca — para usuários corporativos com baixa familiaridade tecnológica.
+
+---
+
+## Perfil do Usuário
+
+O público-alvo das interfaces é corporativo e diversificado em experiência técnica:
+
+- Gestores públicos e ambientais
+- Técnicos de campo
+- Consultores ambientais
+- Operadores administrativos
+
+**Premissa central**: o usuário não tem familiaridade avançada com tecnologia. A interface precisa ser autoexplicativa, sem dependência de treinamento prévio.
+
+---
+
+## Paleta de Cores Institucional
+
+Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta** (primária), **Âmbar terroso** (apoio/aviso), **Cinza musgo** (neutros). Semânticas independentes para garantir reconhecimento universal.
+
+### Escala primária — Verde floresta
+
+| Token | Hex | Stop | Uso |
+|---|---|---|---|
+| `--cor-eli-primaria-bg` | `#EEF3D0` | 50 | Fundo de cards destacados, linhas ativas, hover suave |
+| `--cor-eli-primaria-zebra` | `#F6F9E8` | 30 | Linha zebrada de tabelas (quase branco esverdeado) |
+| `--cor-eli-primaria-suave` | `#BFC99C` | — | **Cabeçalho de tabela** — sage/olive mudo, sem limão, texto escuro |
+| `--cor-eli-primaria-clara` | `#D4E290` | 100 | Badges, chips, seleção, fundo de hover em listas |
+| `--cor-eli-primaria-media` | `#ADCC44` | 200 | Tags, indicadores secundários |
+| `--cor-eli-primaria-acao` | `#8AAF00` | 400 | Ação secundária, ícones ativos |
+| `--cor-eli-primaria` | `#688C00` | 600 | **Botões principais, links ativos, destaques — CTA principal** |
+| `--cor-eli-primaria-escura` | `#4A6500` | 800 | Hover em botões, bordas ativas, títulos com ênfase |
+| `--cor-eli-primaria-texto` | `#2E3F00` | 900 | Texto escuro sobre fundos claros da paleta primária |
+
+### Escala de apoio — Âmbar terroso
+
+| Token | Hex | Stop | Uso |
+|---|---|---|---|
+| `--cor-eli-alerta-bg` | `#FAF3DF` | 50 | Fundo de banners de aviso |
+| `--cor-eli-alerta-clara` | `#F5DC8A` | 100 | Badges de atenção, chips de alerta |
+| `--cor-eli-alerta` | `#DDB847` | 200 | Ícones de aviso, bordas de alerta |
+| `--cor-eli-alerta-forte` | `#8C6A00` | 600 | Texto sobre fundo de alerta, status pendente |
+
+### Escala neutra — Cinza musgo
+
+| Token | Hex | Stop | Uso |
+|---|---|---|---|
+| `--cor-eli-fundo` | `#F2F3EE` | 50 | Background geral de páginas |
+| `--cor-eli-borda` | `#D5D8CC` | 100 | Bordas padrão de containers |
+| `--cor-eli-borda-forte` | `#B5BAA8` | 200 | Bordas de foco, divisores |
+| `--cor-eli-neutro` | `#5E6553` | 600 | Textos secundários, ícones inativos |
+| `--cor-eli-neutro-escuro` | `#3E4436` | 800 | Texto de label, cabeçalhos de tabela |
+| `--cor-eli-superficie` | `#FFFFFF` | — | Cards, modais, popovers |
+
+### Cores semânticas
+
+| Token | Hex | Uso |
+|---|---|---|
+| `--cor-eli-sucesso` | `#2e7d32` | Confirmações, status positivo |
+| `--cor-eli-sucesso-bg` | `#E8F5E9` | Fundo de mensagens de sucesso |
+| `--cor-eli-erro` | `#c62828` | Erros, ações destrutivas |
+| `--cor-eli-erro-bg` | `#FFEBEE` | Fundo de mensagens de erro |
+| `--cor-eli-info` | `#1565c0` | Informações auxiliares |
+| `--cor-eli-info-bg` | `#E3F2FD` | Fundo de banners informativos |
+
+### Regras de contraste
+
+- Texto sobre `--cor-eli-primaria` (`#688C00`) deve ser **branco** (`#ffffff`) — contraste 4.6:1 ✓
+- Texto sobre `--cor-eli-primaria-bg` (`#EEF3D0`) deve ser `--cor-eli-primaria-texto` (`#2E3F00`) — contraste 12:1 ✓
+- Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓
+- Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓
+- Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓
+- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`.
+- Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold).
+
+---
+
+## Passos
+
+### 1. Identificar o escopo da revisão
+
+Determinar qual componente, tela ou modal será revisado. Pode ser:
+
+- Um componente isolado (ex: `EliTabela`, `EliCartao`)
+- Uma página completa (ex: `PaginaCadastro.vue`)
+- Um modal ou drawer (ex: `EliTabelaModalFiltroAvancado.vue`)
+- Uma interação específica (ex: fluxo de filtro, paginação, menu de ações)
+
+### 2. Mapear o estado atual
+
+Antes de alterar, entender o que já existe:
+
+- Ler o template (`<template>`) para entender a estrutura visual
+- Ler o CSS/SCSS associado para mapear os tokens de design em uso
+- Identificar quais componentes Vuetify estão sendo utilizados (ex: `v-btn`, `v-dialog`, `v-select`)
+- Verificar se existem estilos inline que deveriam migrar para classes CSS
+
+### 3. Avaliar contra os critérios de UX
+
+Para cada elemento da interface, avaliar:
+
+#### Clareza
+
+- [ ] O propósito de cada elemento é óbvio sem instrução?
+- [ ] Labels e placeholders são descritivos? (ex: "Buscar por nome ou CPF" vs "Buscar")
+- [ ] Ícones acompanham texto quando a ação não é universalmente reconhecível?
+- [ ] O estado vazio (empty state) orienta o usuário sobre o próximo passo?
+
+#### Hierarquia visual
+
+- [ ] O olho do usuário é guiado para a ação principal primeiro?
+- [ ] Ações primárias usam `--cor-eli-primaria` (`#688C00`) com destaque?
+- [ ] Ações secundárias são visuais mas não competem com a primária?
+- [ ] Ações destrutivas (Excluir, Limpar) usam `--cor-eli-erro` com variante `text` ou `outlined`?
+
+#### Feedback e estados
+
+- [ ] Botões têm estados claros de hover (`--cor-eli-primaria-escura`), focus e disabled (`--cor-eli-borda-forte`)?
+- [ ] Carregamentos exibem indicador visual (spinner, skeleton, barra de progresso)?
+- [ ] Erros de formulário aparecem próximos ao campo com mensagem descritiva, usando `--cor-eli-erro` + `--cor-eli-erro-bg`?
+- [ ] Sucesso de operações tem confirmação visual (snackbar, toast, badge) com `--cor-eli-sucesso`?
+
+#### Densidade e espaçamento
+
+- [ ] O espaçamento segue múltiplos de 4px (4, 8, 12, 16, 24, 32)?
+- [ ] Em desktop, o espaço horizontal é bem aproveitado? (ex: grids de 2+ colunas para formulários largos)
+- [ ] Em mobile, os elementos empilham verticalmente sem quebra visual?
+- [ ] Modais têm largura proporcional ao conteúdo?
+
+#### Tipografia
+
+- [ ] Tamanhos de fonte seguem a escala: 12px (caption), 14px (body), 16px (subtitle), 20px (title), 24px (heading)?
+- [ ] Textos longos usam `line-height: 1.5` para legibilidade?
+- [ ] Labels de formulário são visualmente distintos do conteúdo preenchido?
+
+#### Acessibilidade básica
+
+- [ ] Elementos interativos têm `aria-label` quando o texto visual não é suficiente?
+- [ ] Foco via teclado (`Tab`) segue uma ordem lógica?
+- [ ] Cores não são o único meio de comunicar estado (ex: ícone + cor para erro)?
+- [ ] Todo texto sobre cor primária ou escura usa branco (`#FFFFFF`)?
+- [ ] Todo texto sobre `--cor-eli-primaria-bg` usa `--cor-eli-primaria-texto` (`#2E3F00`)?
+
+### 4. Aplicar padrões Vue/Vuetify do projeto
+
+Ao implementar melhorias, seguir os padrões do ecossistema:
+
+#### Componentes Vuetify
+
+- Usar `v-btn` com variantes do tema (`color="primary"`) em vez de classes CSS manuais para botões
+- Usar `v-dialog` para modais, `v-menu` para popovers contextuais
+- Usar `v-text-field`, `v-select` etc. para inputs sempre que possível
+- Aproveitar props de Vuetify: `density`, `variant`, `rounded`, `elevation`
+
+#### Iconografia — Lucide (obrigatório)
+
+Todos os ícones do projeto devem vir exclusivamente da biblioteca **`@lucide/vue`** (dependência já instalada no `package.json`).
+
+**Proibido**:
+- SVG inline manual (hardcoded no template)
+- Ícones de `@mdi/font` ou Material Design Icons em componentes do projeto
+- Bibliotecas alternativas (Font Awesome, Heroicons, etc.)
+
+**Como usar**:
+
+```vue
+<script lang="ts">
+import { Filter, Plus, X, Trash2, Eye } from "@lucide/vue"
+</script>
+
+<template>
+  <!-- Uso direto como componente -->
+  <Filter :size="18" :stroke-width="2" />
+
+  <!-- Dentro de botão -->
+  <button>
+    <Plus :size="15" :stroke-width="2.5" />
+    Adicionar
+  </button>
+</template>
+```
+
+**Props úteis**: `:size` (número em px), `:stroke-width` (espessura do traço, padrão 2), `:color` (cor do ícone).
+
+**Catálogo de referência**: https://lucide.dev/icons — buscar pelo nome do ícone em inglês.
+
+> Os tokens CSS estão documentados nas tabelas da seção **Paleta de Cores Institucional** acima.
+> No código, usar `var(--token, #fallback)` — sempre com fallback hardcoded em componentes de biblioteca.
+
+- Classes devem seguir BEM: `eli-componente__elemento--modificador`
+- Evitar `!important` — resolver especificidade via seletor mais específico
+- Usar `var(--cor-eli-primaria)` em vez de valores hex hardcoded no CSS dos componentes
+- Transições padrão: `transition: all 0.2s ease` para hover/focus
+
+#### Composição de componentes
+
+- Componentes filhos devem receber dados via `props` e emitir eventos via `$emit`
+- Evitar acessar o DOM diretamente; preferir `ref` do Vue
+- Não duplicar CSS entre componentes — extrair para classe utilitária ou CSS do componente pai
+
+### 5. Implementar melhorias prioritárias
+
+Ordenar as melhorias por impacto no usuário:
+
+1. **Crítico**: elementos que causam confusão ou impedem o uso (falta de feedback, botão invisível, estado vazio sem orientação)
+2. **Alto**: melhorias que reduzem atrito (espaçamento, hierarquia de botões, responsividade)
+3. **Médio**: refinamentos visuais (transições, micro-animações, consistência de cores)
+4. **Baixo**: polish (sombras sutis, arredondamentos, tipografia refinada)
+
+### 6. Validar resultado
+
+Após implementar:
+
+- [ ] A tela renderiza sem erros no console?
+- [ ] Os estados (vazio, carregando, erro, com dados) estão todos cobertos?
+- [ ] A paleta de cores está coerente com a base `#688C00`?
+- [ ] Todos os tokens usados estão definidos na escala primária, de apoio ou neutra?
+- [ ] Nenhuma cor está hardcoded no CSS do componente (usar `var(--token, #fallback)`)?
+- [ ] Tokens novos têm fallback hardcoded? (ex: `var(--cor-eli-primaria-suave, #BFC99C)`)?
+- [ ] Contraste de texto validado: branco sobre `--cor-eli-primaria` e `--cor-eli-primaria-escura`; `--cor-eli-neutro-escuro` sobre `--cor-eli-primaria-suave`?
+- [ ] Nenhuma ação ficou sem feedback visual?
+- [ ] O layout não quebra em larguras menores que 1024px?
+- [ ] Componentes Vuetify recebem props de tema (`color`, `variant`) em vez de override CSS?
+- [ ] Efeito zebra de tabelas tem fundo branco explícito nas linhas normais (para funcionar sobre qualquer fundo de página)?
+
+---
+
+## Anti-padrões a evitar
+
+| ❌ Anti-padrão | ✅ Alternativa |
+|---|---|
+| Botão sem label de texto | Botão com ícone + texto, ou `aria-label` descritivo |
+| Cor vermelha para ação primária | Vermelho apenas para destrutivas; primária usa `--cor-eli-primaria` |
+| Modal com scroll interno extenso | Dividir em etapas ou usar drawer lateral |
+| Tabela com 15+ colunas visíveis | Usar o modal de colunas para esconder as menos usadas |
+| Placeholder como único label | Label fixo acima do campo + placeholder como exemplo |
+| Ações alinhadas à esquerda em linha de tabela | Ações à direita, próximas ao fim da linha visual |
+| Toast/snackbar sem ação de fechar | Sempre incluir botão de fechar ou auto-dismiss com tempo suficiente (5s+) |
+| Estilos inline em `<template>` | Migrar para `<style scoped>` com classe BEM |
+| Cor hex hardcoded no componente | Usar `var(--cor-eli-primaria)` e demais tokens com fallback |
+| Texto escuro (`#333`) sobre `--cor-eli-primaria` | Usar branco (`#FFFFFF`) para garantir contraste WCAG AA |
+| Amarelo/âmbar para sucesso | Âmbar é reservado para **aviso**; sucesso usa `--cor-eli-sucesso` (`#2E7D32`) |
+| Misturar stops da paleta fora dos tokens | Usar apenas os tokens definidos; nunca interpolar valores avulsos |
+| Usar `--cor-eli-media` ou `--cor-eli-acao` como fundo de cabeçalho | Usar `--cor-eli-primaria-suave` (`#BFC99C`) — verde mudo sem efeito limão |
+| `var(--token)` sem fallback em componente de biblioteca | Sempre declarar `var(--token, #valor)` — o projeto destino pode não ter o token atualizado |
+| Zebra de tabela sem fundo branco explícito nas linhas normais | Declarar `.eli-tabela__tr .eli-tabela__td { background: var(--cor-eli-superficie, #fff) }` antes da regra zebra |