@diegosouzacdv/jev-browser-mcp 0.6.2 → 0.7.1

package/README.md

@@ -17,7 +17,7 @@ versão em produção, use o número explícito no argumento do pacote:
   "mcpServers": {
     "jev-browser": {
       "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.6.2"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.7.1"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
         "JEV_BROWSER_MODE": "computer"
@@ -32,7 +32,7 @@ um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
 de configuração. Para instalar no projeto Node do próprio harness:
 
 ```sh
-npm install @diegosouzacdv/jev-browser-mcp@0.6.2
+npm install @diegosouzacdv/jev-browser-mcp@0.7.1
 ```
 
 Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
@@ -40,7 +40,7 @@ fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cad
 inicialização:
 
 ```sh
-npm install --global @diegosouzacdv/jev-browser-mcp@0.6.2
+npm install --global @diegosouzacdv/jev-browser-mcp@0.7.1
 ```
 
 Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
@@ -49,14 +49,23 @@ Para atualizar, rode `npm install --global
 
 O padrão `computer` exige Chrome ou Edge instalado. Se optar por `harness`,
 configure `JEV_BROWSER_MODE=harness` antes de instalar o navegador gerenciado
-pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp@0.6.2 --install-browser`.
-
-O padrão é `computer`: o pacote abre o Chrome/Edge instalado e usa um perfil
-persistente exclusivo em `browser.computer_user_data_dir`. No modo `harness`, a
-instalação baixa uma vez o Chrome/Edge que o Playwright controlará. Personalize
-as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
-`JEV_BROWSER_PROFILE`. O browser permanece aquecido enquanto o processo MCP
-estiver ativo e fecha quando o harness encerra o processo. `JEV_PROVIDER_URL`
+pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp@0.7.1 --install-browser`.
+
+O padrão é `computer`: o pacote abre o Chrome/Edge instalado e usa um perfil
+persistente exclusivo por processo MCP em `browser.computer_user_data_dir`. O
+template aceita `{browser}` e `{session}`; por padrão, `{session}` é `pid-<PID>`.
+Use um `JEV_BROWSER_SESSION_ID` único por instância para manter um nome estável
+entre reinicializações. Um
+`JEV_BROWSER_PROFILE` explícito também recebe o sufixo da sessão, a menos que o
+caminho contenha `{session}`. Assim, processos MCP independentes não disputam o
+mesmo perfil. Clientes conectados ao mesmo processo MCP compartilham a sessão;
+para isolamento entre harnesses, execute uma instância por sessão. No modo
+`harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright controlará.
+Personalize as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
+`JEV_BROWSER_PROFILE`. Sem um ID estável, o perfil é específico do processo e
+uma reinicialização começa outra sessão. O browser permanece aquecido enquanto
+o processo MCP estiver ativo e fecha quando o harness encerra o processo.
+`JEV_PROVIDER_URL`
 e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
 nome de variável declarado em `jev.credential_env`.
 
@@ -76,8 +85,14 @@ publicada.
 
 ### Contrato do pacote
 
-O executável oferece `browser_health`, `choose_next_action` e `run_browser_flow`, mantém uma
-sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
+O executável oferece `browser_health`, `describe_actions`, `choose_next_action`
+e `run_browser_flow`, mantém uma sessão do browser por processo e reutiliza
+essa sessão entre chamadas. `browser_health` informa versão, sessão e
+capacidades; `describe_actions` publica o schema atual das ações, opções,
+aliases, placeholders, campos obrigatórios de `flow`/plano e requisitos
+condicionais por ação. `run_browser_flow` agrega campos obrigatórios ausentes
+em todos os planos e etapas antes de abrir o navegador. Consulte essas ferramentas
+antes de construir um plano para evitar nomes de campos desatualizados. O plano
 passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
 hover, espera, teclas aprovadas, asserções por elemento, upload restrito a uma
 raiz local configurada e reações idempotentes a um comentário único. Também
@@ -112,9 +127,14 @@ Cada plano pode usar:
 - `navigate` para mudar de página no meio do fluxo. Com a continuidade ligada,
   um `initial_url` de mesma origem diferente da URL ativa produz erro claro; use
   `navigate` ou `continue_from_current_page: false` para escolher o destino;
-- `click`, `type`, `clear`, `hover`, `select_option`, `press`, `assert_*` e upload com
-  papel/nome acessível ou um localizador: `label`, `placeholder`, `title`,
-  `text`, `test_id` ou `selector`;
+- `click`, `check`, `uncheck`, `type`, `clear`, `hover`, `select_option`,
+  `press` e `assert_*` aceitam papel/nome acessível ou localizadores como
+  `label`, `placeholder`, `title`, `text`, `test_id` e `selector`;
+- `screenshot` e `clear_storage` atuam na página/contexto atual; `upload_file`
+  recebe o arquivo e o alvo de upload. Os limites e formatos estão descritos nas
+  seções de evidências e upload;
+- `navigate_menu` para percorrer uma sequência de rótulos de menu; veja a seção
+  de navegação de menus para o formato e as opções;
 - `name_match: "exact" | "contains" | "regex"` para controlar a comparação do
   nome acessível; regex rejeita construções com backtracking excessivo. O papel
   `switch` funciona em cliques, verificações e asserções;
@@ -131,8 +151,11 @@ Cada plano pode usar:
   espaços/glyphs de uso privado, como ícones Font Awesome; controles
   desabilitados não aparecem no diagnóstico, mas continuam contando para que o
   índice aponte ao controle correto;
-- `selector` com CSS ou XPath como último recurso. O MCP identifica essa escolha
-  em `warnings`; não é permitido enviar JavaScript nem coordenadas;
+- `selector` com CSS ou XPath como último recurso. O MCP identifica essa escolha
+  em `warnings`; não é permitido enviar JavaScript nem coordenadas;
+- quando `click` falha porque o alvo está fora da viewport ou não está visível,
+  o MCP tenta rolar o alvo até a tela; se isso não bastar, tenta focar o controle
+  e enviar `Enter`, sem repetir cegamente o clique;
 - `timeout_seconds` opcional em cada etapa, limitado pela configuração central;
 - `type` com `mode: "keys"` para digitar sequencialmente em campos com máscara,
   `blur: true` para desfocar o campo e `sensitive: false` para permitir que o
@@ -140,7 +163,7 @@ Cada plano pode usar:
   de ambiente do processo MCP, sem colocá-lo no plano. Nesse modo, `\n` envia
   Enter e `\t` envia Tab;
 - `wait_for_text`, `wait_for_value`, `wait_for_enabled` e `wait_for_condition`
-  (`url`, `network_idle`, `hidden`, `text_hidden` ou `angular_idle`). `wait` recebe
+  (`url`, `network_idle`, `hidden` ou `angular_idle`). `wait` recebe
   `ms` para uma pausa curta e limitada. `angular_idle` aguarda requisições
   `$http` e digest do AngularJS. `wait_for_text` aceita `fail_on: {"role":"alert"}` para
   interromper a espera assim que um alerta visível aparecer e incluir seu texto
@@ -150,10 +173,48 @@ Cada plano pode usar:
   `ready_stable_ms`; WebSocket, EventSource e polling não relacionado não
   bloqueiam a espera. Se não surgir requisição correspondente, o passo conclui
   após a janela de silêncio;
+- `assert_network` valida resposta HTTP observada (inclusive sucesso 2xx ou erro
+  esperado); `wait_for_request` aguarda uma resposta usando `*` como curinga na
+  URL e filtros opcionais de método/status; `assert_ws` confere texto, pares
+  JSON esperados ou código de fechamento de WebSocket. `wait_for_request`
+  consulta o histórico desde o começo da chamada, inclusive requisições feitas
+  durante a navegação inicial e dentro de iframes; URLs cobertas por uma
+  asserção ficam retidas mesmo quando a SPA excede o buffer circular;
+- `evaluate` lê somente caminhos de propriedades como `navigator.mediaDevices`,
+  `document.readyState` ou `location.pathname`. Não aceita código, chamadas de
+  função, armazenamento local ou propriedades de credenciais. Strings e números
+  voltam diretamente; objetos e arrays retornam somente tipo, chaves e tamanho,
+  sem despejar seus valores;
+- `http_request` executa somente GET com a sessão da página; `inspect_cookies`
+  retorna apenas metadados e valores redigidos; `read_angular_state` devolve o
+  nome do estado e nomes dos parâmetros, sem valores. As três ações exigem
+  `local_only: true` e página em loopback. `http_request` fica restrito à mesma
+  origem, não segue redirecionamentos e limita/redige o corpo opcional;
+- `frame: "first"` seleciona o primeiro iframe; `frame: {"url_contains":"..."}`
+  localiza um iframe pela URL. Uma string diferente continua buscando o nome ou
+  título exato do frame;
+- `navigate_menu` aceita `path` para menus acessíveis ou `screen` para procurar
+  código/nome pela tela Acesso Rápido do SAFI. O segundo caminho usa a interface
+  do SAFI e preserva as verificações de acesso do próprio aplicativo;
+- `new_tab`, `switch_tab` e `new_context` abrem/selecionam abas e criam contexto
+  separado dentro do fluxo; `target_page: "popup"` mantém popups abertos para
+  passos posteriores;
+- `if_visible` em um clique torna a ação condicional e
+  `when: {"visible":"..."}` em cada plano limita as opções do Jev às que
+  correspondem à tela atual;
+- `fill` é alias de `type`, `press_key` de `press`, `duration_ms` de `wait.ms` e
+  `value` de campos de texto. `timeout_ms` funciona por etapa. Placeholders usam
+  `{nome}`; referências desconhecidas e `{{nome}}` são recusadas antes da
+  navegação;
 - `press` (o alias legado `press_key` também é aceito) com `PageDown`, `PageUp`,
   `Home`, `End`, setas, `Enter`, `Escape`, `Tab`, `Shift+Tab`, `Space`,
   `Backspace` ou `Delete`. `clear` limpa um campo sem exigir texto. Sem alvo,
   `press` envia a tecla ao elemento focado; com alvo, usa o localizador informado;
+- `screenshot` grava uma imagem local; `full_page: true` inclui a página inteira.
+  Também é possível pedir uma captura após qualquer etapa com `screenshot: true`;
+- `clear_storage` limpa cookies, local/session storage, IndexedDB, Cache Storage
+  e service workers do contexto atual. Como opção de fluxo,
+  `options.clear_storage: true` também recarrega a página antes do snapshot inicial;
 - `assert_text`, `assert_value`, `assert_visible`, `assert_hidden` e
   `assert_enabled`; `assert_text`
   pode receber apenas `role` quando a região, como `alert`, não tem nome acessível;
@@ -169,19 +230,25 @@ Cada plano pode usar:
 
 As proteções e evidências por etapa usam estes campos:
 
-- `confirm_dialog` recebe `expected_text` e `button`. Em diálogos HTML, o MCP
-  confere o texto antes de localizar e clicar no botão. Também trata diálogos
-  nativos `alert`/`confirm`: precisa haver uma etapa `confirm_dialog` logo após
-  o clique que os abre, o texto deve corresponder e um diálogo inesperado é
-  fechado sem aceitar;
-- `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
+- `confirm_dialog` recebe `expected_text` e `button`. Em diálogos HTML, o MCP
+  confere o texto antes de localizar e clicar no botão. Também trata diálogos
+  nativos `alert`/`confirm`: precisa haver uma etapa `confirm_dialog` logo após
+  o clique que os abre, o texto deve corresponder e um diálogo inesperado é
+  fechado sem aceitar;
+- `confirm_modal` combina o clique no gatilho, a conferência do texto e o clique
+  afirmativo em uma única etapa protegida. Também aceita os aliases
+  `trigger`/`confirm`, por exemplo
+  `{"action":"confirm_modal","trigger":"Salvar","expected_text":"Confirma a alteração?","confirm":"OK"}`;
+- `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
   O MCP também classifica botões conhecidos como `Salvar`, `Emitir`, `Cancelar`
   ou `Sim` pelo nome e pelo controle resolvido, inclusive quando o plano usa um
   seletor CSS. `options.dry_run: true` executa até a primeira etapa mutável e
   para antes dela; retorna `dry_run_stopped_before_step` e um
-  `confirmation_token` temporário, de uso único e vinculado ao fluxo e à página.
-  Reenvie a mesma chamada com `options.confirmation_token` para autorizar essa
-  etapa. O MCP pausa novamente antes de cada outra etapa mutável. Sem `dry_run`,
+  `confirmation_token` temporário, de uso único e vinculado ao fluxo e à página.
+  Reenvie a mesma chamada com `options.confirmation_token` para retomar no passo
+  pausado sem repetir os passos anteriores; o MCP confere a rota e o alvo da
+  mutação antes de executá-la. Ele pausa novamente antes de cada outra etapa
+  mutável. Sem `dry_run`,
   o primeiro pedido de ação mutável também retorna `status: "confirmation_required"`
   e token; nenhuma etapa mutável roda sem essa autorização. O token expira após
   dez minutos por padrão;
@@ -217,9 +284,34 @@ incluindo respostas 2xx ou erros esperados como 404. Exemplo:
 }
 ```
 
-Essa asserção aparece na evidência como `response_status`, separado do campo
-`status` da etapa (`passed` ou `failed`). `message_contains` lê somente resposta
-da mesma origem e respeita o limite configurado para captura de corpos.
+Essa asserção aparece na evidência como `response_status`, separado do campo
+`status` da etapa (`passed` ou `failed`). `message_contains` lê somente resposta
+da mesma origem e respeita o limite configurado para captura de corpos.
+`assert_network` consulta respostas desde o marcador da etapa e usa a resposta
+da navegação inicial como fallback quando nenhuma resposta posterior corresponde.
+`wait_for_request` e `expected_outcome.request` consultam desde o início do fluxo.
+URLs cobertas por uma asserção são retidas em um buffer separado limitado por
+`jev_browser_mcp.browser.max_network_history_events` (4096 eventos nesta
+configuração). A captura de página também observa requisições de iframes.
+Um único plano `fast_path` composto apenas por `assert_network` e
+`wait_for_request` não espera um snapshot visual, então endpoints que respondem
+sem HTML também podem ser verificados. `navigation_http_status` registra um
+status HTTP de erro recebido pela navegação inicial; ele não é uma falha de rede.
+
+`options.capture_network: "all"` inclui até o limite de diagnóstico eventos
+com URL sem query string, método, status, tipo de recurso, duração e cabeçalhos
+de resposta de uma allowlist. `capture_network_url_contains` filtra as URLs.
+Quando o Chromium informa cookies bloqueados, `blocked_cookies` mostra nome,
+domínio, caminho, flags e motivo, sem revelar valores.
+
+Para aguardar a API antes de abrir a interface, passe
+`options.wait_for_http: {"url":"http://localhost:8000/health","timeout_ms":30000}`.
+Também aceita apenas a URL como string ou `{ "url": "...", "timeout_seconds": 30 }`.
+O probe faz GET e tenta novamente até o limite; qualquer resposta abaixo de 500
+indica que o servidor respondeu (inclusive 4xx), enquanto 5xx e erros de conexão
+são repetidos. Ao expirar, `reason` inclui a última causa. Por segurança, a URL
+precisa ser loopback ou usar o mesmo host de `initial_url`; isso permite, por
+exemplo, Vite em `localhost:5173` e API em `localhost:8000`.
 
 Exemplo de parâmetro e extração: passe `params: {"pedido":"1528721"}`, filtre
 com `within: {"row_containing_exact":"{pedido}"}`, e use uma etapa
@@ -227,8 +319,10 @@ com `within: {"row_containing_exact":"{pedido}"}`, e use uma etapa
 A etapa seguinte pode localizar o mesmo documento com `name: "{documento}"`.
 
 Em `wait_for_condition` com `condition: "hidden"`, use qualquer um desses
-localizadores, `near` ou `within`; `text_hidden` recebe o texto direto. Para
-aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
+localizadores, `near` ou `within`; para esperar texto desaparecer, use
+`{"condition":"hidden","text":"Carregando..."}`. Para esperar que texto suma
+antes do primeiro passo, use `options.ready: {"hidden_text":"Carregando..."}`.
+Para aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
 `url_contains`. O filtro considera somente a atividade correspondente e termina
 após a janela configurada sem atividade; também termina caso nenhuma requisição
 correspondente apareça. Para validar status e corpo, prefira `assert_network`.
@@ -239,16 +333,44 @@ ocorrência zero-based dentro desse escopo; sem `index`, o MCP exige exatamente
 um alvo. Para uma página com rótulo `for` quebrado, `label` também procura o
 controle próximo ao texto visível do rótulo.
 
-`within` pode combinar um container e uma linha. Use, por exemplo,
+`within` pode combinar um container e uma linha. Use, por exemplo,
 `{"role":"cell","name":"Documento A","within":{"role":"table","row_containing_word":"1528721"}}`.
 `row_containing_word` usa limites de palavra para não confundir `1528721` com
 `15287210`; `row_containing_exact` continua disponível para texto de célula
 exato. `check` e `uncheck` alteram checkboxes, e `select_option` aceita rótulo
 exato (`option`), valor (`value`) ou rótulo parcial único (`label_contains`).
-`navigate_menu` percorre uma lista de rótulos exatos e abre `#open_btn` quando o
-primeiro item ainda está oculto. Se vários itens visíveis tiverem o mesmo
-rótulo, seleciona a última ocorrência, útil quando o submenu recém-aberto
-repete o nome da categoria pai.
+`navigate_menu` percorre uma lista de rótulos exatos e abre `#open_btn` quando o
+primeiro item ainda está oculto. Se vários itens visíveis tiverem o mesmo
+rótulo, seleciona a última ocorrência, útil quando o submenu recém-aberto
+repete o nome da categoria pai. Para o SAFI, `screen` pesquisa o nome ou código
+na tela Acesso Rápido, exige um resultado único e clica no link oficial da linha;
+por exemplo, `{"action":"navigate_menu","screen":"TCN00022"}`.
+
+Em uma instância local do SAFI, `http_request` pode obter a lista de telas pela
+sessão já aberta sem ler o HTML:
+
+```json
+{
+  "flow": "Consultar telas disponíveis no perfil atual do SAFI",
+  "initial_url": "http://localhost:8011/safi/",
+  "candidate_plans": {
+    "inspect": {
+      "description": "Ler a lista de telas do SAFI no ambiente local",
+      "steps": [{
+        "action": "http_request",
+        "url": "/safi/api/menu/telas_menu",
+        "include_body": true
+      }]
+    }
+  },
+  "options": { "local_only": true, "fast_path": true }
+}
+```
+
+O endpoint usa a sessão atual e pode retornar uma lista específica do perfil.
+Os valores de cookies nunca são retornados. O acesso ao menu continua sujeito
+às permissões verificadas pela própria interface; não use esse diagnóstico
+contra produção.
 
 ```json
 {
@@ -274,13 +396,14 @@ Exemplos para controles legados sem nome acessível:
 {"action":"click","selector":"#save-document"}
 ```
 
-O reconhecimento retorna `unnamed_controls_initial` e
-`unnamed_controls_final`, cada um com papel, índice Playwright por papel, rótulo
-mais próximo e um trecho HTML sanitizado dos controles visíveis e habilitados
-sem nome. Nomes vazios ou compostos apenas por espaços e glyphs da área Unicode
-de uso privado (como ícones Font Awesome) entram nessa lista e podem ser
-selecionados com `name: ""` e o mesmo índice. `unnamed_controls` continua
-disponível como alias da lista final. O placeholder conta como nome acessível.
+Por padrão, controles sem nome não são devolvidos em listas separadas. Defina
+`options.include_unnamed_controls: true` para receber
+`unnamed_controls_initial` e `unnamed_controls_final`, cada uma com papel,
+índice Playwright por papel, rótulo mais próximo e um trecho HTML sanitizado.
+Nomes vazios ou compostos apenas por espaços e glyphs da área Unicode de uso
+privado (como ícones Font Awesome) entram nessa lista e podem ser selecionados
+com `name: ""` e o mesmo índice. O alias redundante `unnamed_controls` foi
+removido. O placeholder conta como nome acessível.
 O snapshot também resume campos de formulário com `id`, `name`, valor, estado
 desabilitado, rótulo e índice zero-based entre campos de mesmo nome. Valores
 sensíveis, como senha, token e cartão, são ocultados. `snapshot_include_hidden`
@@ -291,10 +414,14 @@ Em uma etapa `type`, `text` contém o valor a digitar; use `target_text` para
 localizar pelo texto visível próximo ao campo. Esse localizador exige `role`
 `textbox`, `searchbox` ou `combobox`.
 
-Por padrão, o MCP executa todos os passos antes de avaliar `expected_outcome`.
-Valores dentro de campos não contam como resultado visível. `stop_on_expected:
-true` habilita parada antecipada quando o texto esperado aparece fora dos
-campos; mantenha `false` para fluxos com várias etapas.
+Por padrão, o MCP executa todos os passos antes de avaliar os critérios.
+`expected_outcome` aceita texto descritivo ou uma asserção estruturada, por
+exemplo `{"text":"Tecnologia atualizada com sucesso."}` ou
+`{"request":"PUT */api/tecnologia","status":200}`. A forma estruturada pode
+incluir `message_contains` e reprova se a resposta correspondente não for
+observada. Valores dentro de campos não contam como texto visível.
+`stop_on_expected: true` habilita parada antecipada quando o texto esperado
+aparece fora dos campos; mantenha `false` para fluxos com várias etapas.
 
 Os erros de validação apontam o campo inválido e os campos aceitos. Os limites
 de `timeout_seconds` informam o máximo configurado, em vez de exigir tentativa
@@ -330,11 +457,13 @@ verificar:
 {"action":"audit_accessibility","standard":"wcag2aa"}
 ```
 
-O MCP usa `@axe-core/playwright` com as tags WCAG 2.0 e 2.1 A/AA. O retorno
-resume as violações por regra, impacto e quantidade de nós, sem copiar HTML ou
-trechos da página. Qualquer violação reprova esse fluxo. A auditoria automática
-encontra problemas comuns, mas não comprova conformidade WCAG completa; combine-a
-com revisão manual e testes com usuários assistivos.
+O MCP usa `@axe-core/playwright` com as tags WCAG 2.0 e 2.1 A/AA. O retorno
+resume as violações por regra, impacto e quantidade de nós, sem copiar HTML ou
+trechos da página. A etapa falha quando encontra violações no impacto definido
+por `fail_on_impact`; o padrão é `minor`, e níveis abaixo do limite são relatados
+sem bloquear o fluxo. A auditoria automática encontra problemas comuns, mas não
+comprova conformidade WCAG completa; combine-a com revisão manual e testes com
+usuários assistivos.
 
 Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
 corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
@@ -431,25 +560,68 @@ validadores.
   harness e CI. O processo MCP conserva browser, contexto e página entre
   chamadas; cookies, local storage e estado da página permanecem enquanto o
   processo estiver ativo. Encerre o processo para descartar o contexto isolado.
-- `computer` abre o Chrome ou Edge instalado em modo visível e usa o diretório
-  persistente `browser.computer_user_data_dir`, separado por navegador. Não
-  reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
-  cookies permanecem nele entre chamadas.
+- `computer` abre o Chrome ou Edge instalado em modo visível e usa o diretório
+  persistente `browser.computer_user_data_dir`, separado por navegador e por
+  processo MCP. Não
+  reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
+  cookies permanecem nele entre chamadas.
+
+`fresh_context: true` abre um contexto descartável, sem cookies nem storage do
+perfil persistente; requer `initial_url` e fecha esse contexto ao terminar. Use
+`clear_storage: true` para limpar cookies, local/session storage, IndexedDB,
+Cache Storage e service workers antes de recarregar a página atual. Para salvar
+e reutilizar o estado de autenticação de uma conta de teste, use um nome simples
+em `storage_state`:
+
+```json
+{"options":{"storage_state":"aluno-a"}}
+```
+
+O estado fica em `storage-state/<nome>.json` dentro da pasta de artefatos, com
+permissões restritas no sistema operacional; não use uma conta real nem
+compartilhe esse arquivo. `storage_state` não pode ser combinado com
+`fresh_context` ou `clear_storage`.
 
 `browser.max_flow_steps` limita os passos de cada plano candidato; os planos
-não são somados. `browser.max_text_entry_chars` limita cada valor digitado. O resultado contém
-`status`, o plano escolhido, as ações executadas, a última captura acessível e
-se o critério esperado apareceu. Quando existem asserções explícitas, `status`
-também pode ser `passed` com todas elas satisfeitas; `assertions_passed` registra
-esse resultado e `expected_outcome_visible` continua descrevendo somente o
-texto global. `incomplete` significa que nenhum critério foi comprovado;
-confiança do Jev não substitui essa verificação. `timings_ms.ready_ms` mede a
-espera da SPA; `warnings` registra capturas vazias durante transições; e
-`failed_step` identifica índice, ação, localizador, timeout e erro resumido
-quando uma etapa falha. Cada etapa executada também registra a composição do
-localizador usado e, quando disponível, `resolved_target` com tag, `id`, papel,
-nome acessível, `title` casado e `href` sanitizado do elemento resolvido.
-Etapas `type` só incluem o valor final do campo quando `sensitive: false`.
+não são somados. `browser.max_text_entry_chars` limita cada valor digitado. O
+resultado contém `status`, o plano escolhido, as ações executadas, a última
+captura acessível e se o texto descritivo esperado apareceu. `expected_outcome`
+como string é descrição, não uma asserção: `expected_outcome_visible` é
+informado separadamente, e um plano concluído pode passar mesmo se a frase não
+estiver visível. Use `{ "text": "..." }` ou
+`{ "request": "...", "status": 200 }` para exigir uma condição; as
+verificações ficam em `expected_outcome_checks`, e uma condição não satisfeita
+reprova o fluxo. As asserções `assert_*`, auditorias de acessibilidade e
+downloads também aparecem em campos próprios do resultado.
+
+Os status do fluxo incluem `passed`, `failed`, `incomplete`, `environment_error`,
+`dry_run` e `confirmation_required`. O fluxo fica `passed` se não houve falha ou
+pausa de mutação e o texto esperado apareceu, uma asserção/auditoria/download
+passou ou todas as etapas do plano foram executadas. `incomplete` é devolvido
+quando nenhuma dessas condições se aplica; confiança do Jev, sozinha, não
+comprova o resultado. `environment_error` identifica falha de
+navegação, autenticação ou sessão do browser; `navigation_error` contém o código
+detectado, como `ERR_CONNECTION_REFUSED`, `AUTHENTICATION_REQUIRED` ou
+`BROWSER_DISCONNECTED`, `BROWSER_PAGE_NOT_RESTORED` ou
+`BROWSER_PROFILE_IN_USE`, e `reason` orienta a recuperação. Se uma navegação falhar
+e a chamada seguinte tentar reutilizar a página, o MCP informa que a navegação
+anterior não carregou; reinicie a navegação com
+`continue_from_current_page: false` (ou o alias `reuse_page: false`). Uma sessão
+desconectada pode ser reaberta por `browser_health`. `run_browser_flow` também
+tenta reconectar e repetir uma vez quando a desconexão acontece antes da primeira
+etapa; a repetição exige `initial_url`. Sem essa URL, o resultado informa
+`BROWSER_PAGE_NOT_RESTORED`, e chamadas posteriores em `reuse_page` continuam
+recusadas até uma nova navegação explícita. Se qualquer etapa já executou ou
+há token de confirmação de mutação, o MCP não repete o fluxo automaticamente.
+
+`current_url` é devolvido para diagnóstico sem query string nem fragmento; IDs
+longos no caminho também podem ser redigidos. `timings_ms.ready_ms` mede a espera
+da SPA; `warnings` registra capturas vazias durante transições; e `failed_step`
+identifica índice, ação, localizador, timeout e erro resumido quando uma etapa
+falha. Cada etapa executada também registra a composição do localizador usado
+e, quando disponível, `resolved_target` com tag, `id`, papel, nome acessível,
+`title` casado e `href` sanitizado do elemento resolvido. Etapas `type` só
+incluem o valor final do campo quando `sensitive: false`.
 
 Com `capture_network_error_bodies: true`, respostas JSON de erro da mesma
 origem são capturadas mesmo quando usam transferência chunked e não enviam
@@ -472,30 +644,36 @@ continua informada mesmo quando a lista é truncada.
 
 O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
 `block_trackers`, `block_fonts`, `local_only`, `busy_selectors`,
-`auto_angular_idle`, `login_url_contains`, `login_text`, `capture_console_errors`,
-`capture_network_errors`, `capture_network_error_bodies`, `ready_timeout_seconds`,
-`ready_network_idle`, `ready_stable_ms`, `ready_text`, `continue_from_current_page`,
-`reuse_page`, `step_timeout_seconds`, `max_flow_steps`, `return_snapshot`,
+`auto_angular_idle`, `login_url_contains`, `login_text`, `capture_console_errors`,
+`capture_network_errors`, `capture_network_error_bodies`, `capture_network`,
+`capture_network_url_contains`, `ready_timeout_seconds`,
+`ready_network_idle`, `ready_stable_ms`, `ready_text`, `ready`, `continue_from_current_page`,
+`reuse_page`, `reuse_page_match`, `step_timeout_seconds`, `max_flow_steps`, `return_snapshot`,
 `screenshot_on_failure`, `screenshot_on_success`, `trace_on_failure`,
-`trace_on_success`, `record_video`, `snapshot_include_hidden`, `stop_on_expected`,
+`trace_on_success`, `record_video`, `snapshot_include_hidden`, `include_unnamed_controls`, `stop_on_expected`,
 `dry_run`, `confirmation_token`, `report_path`, `permissions`, `fake_media`,
 `viewport`, `mobile`, `device_scale_factor`, `locale`, `timezone_id`,
-`color_scheme`, `geolocation` e `allow_mutations`. Sem override,
-os padrões são lidos de `jev_browser_mcp` em
-`config/ui-testing.json`: um plano candidato pula a chamada Decisions;
-captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
-de recursos ficam desligados; o plano roda até o fim e campos ocultos não são
-acrescentados ao snapshot. O browser espera a SPA renderizar uma captura
-acessível estável na navegação inicial. Depois, a continuidade fica ligada por
+`color_scheme`, `geolocation`, `console_levels`, `fresh_context`,
+`clear_storage`, `storage_state`, `wait_for_http` e `allow_mutations`. Sem override,
+os padrões são lidos de `jev_browser_mcp` em
+`config/ui-testing.json`: um plano candidato pula a chamada Decisions;
+captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
+de recursos ficam desligados; o plano roda até o fim e campos ocultos não são
+acrescentados ao snapshot. `return_snapshot: "diff"` é o padrão, e as listas de
+controles sem nome só aparecem com `include_unnamed_controls: true`. O browser
+espera a SPA renderizar uma captura acessível estável na navegação inicial.
+Depois, a continuidade fica ligada por
 padrão: `continue_from_current_page: true` mantém a página e seu estado entre
 chamadas na mesma origem, não repete `page.goto` e consulta um snapshot atual
 sem esperar novamente por `load`/`networkidle`. As etapas continuam aguardando
 seus próprios alvos e condições. `reuse_page` segue como alias legado; defina
 `continue_from_current_page: false` para iniciar cada chamada em `initial_url`.
 Se a página atual e `initial_url` tiverem origens diferentes, o MCP navega para
-`initial_url`. Se forem da mesma origem mas URLs completas diferentes, o MCP
-recusa continuar silenciosamente e pede uma etapa `navigate` ou
-`continue_from_current_page: false`. `snapshot_scope` aceita `body`, `main` ou
+`initial_url`. URLs da mesma origem são comparadas após normalizar e ordenar a
+query string. Se a rota normalizada diferir, o MCP pede uma etapa `navigate` ou
+`continue_from_current_page: false`. `reuse_page_match: "path"` ignora a query;
+um plano cuja primeira etapa seja `navigate` pode trocar a rota explicitamente.
+`snapshot_scope` aceita `body`, `main` ou
 `dialog`; se `main` não existir, o snapshot usa `body`.
 
 `block_trackers: true` bloqueia analytics/trackers e os tipos de recurso
@@ -511,14 +689,29 @@ precisaria chamar o provedor Jev; use exatamente um plano com `fast_path: true`.
 `allow_mutations: true` pula a confirmação humana somente para URLs em
 `localhost`, `127.0.0.1` ou `::1`; use esse modo apenas em ambientes locais
 controlados.
-`step_timeout_seconds` define o timeout padrão por etapa e cada etapa pode
-substituí-lo com `timeout_seconds`. `max_flow_steps` reduz o limite por chamada,
-sem superar o teto da configuração. `return_snapshot` aceita `full`, `diff` ou
-`none`; `diff` retorna linhas acessíveis novas desde o snapshot inicial.
-
-Com `capture_console_errors` e `capture_network_errors`, o retorno traz
-`console_errors` e `network_failures`, limitados em quantidade e tamanho.
-Mensagens de erro idênticas do console são agrupadas em uma entrada com `count`.
+`step_timeout_seconds` define o timeout padrão por etapa e cada etapa pode
+substituí-lo com `timeout_seconds`. `max_flow_steps` reduz o limite por chamada,
+sem superar o teto da configuração. `return_snapshot` aceita `diff`, `full` ou
+`none`; `diff` retorna linhas acessíveis novas desde o snapshot inicial.
+
+`options.ready` aguarda condições da aplicação antes do primeiro snapshot e da
+seleção do plano. Aceita `"network_idle"`,
+`{"hidden_text":"Aguarde."}` e `{"selector":"#cdTecnologia","has_value":true}`;
+uma lista combina condições, e todas precisam passar. `has_value` aceita
+`true` (valor não vazio), `false` (vazio) ou o valor textual exato.
+`ready_text` também pode exigir uma frase no snapshot inicial;
+`ready_network_idle: true` solicita uma espera best-effort por `networkidle`.
+`ready_timeout_seconds` limita a espera de inicialização e `ready_stable_ms`
+define a janela usada para considerar o snapshot estável.
+
+`console_levels` aceita `log`, `info`, `debug`, `warn` e `error`. Com
+`console_levels: ["log","warn","error"]` e `capture_network_errors`, o retorno
+traz mensagens do console agrupadas por texto e nível (`console_messages` com
+`count`), além de `console_errors` para compatibilidade. `network_failures`
+contém eventos limitados em quantidade e tamanho. Mensagens idênticas do console
+são agrupadas em uma entrada com `count`.
+Controles sem nome acessível aparecem em um único aviso com a contagem e alguns
+exemplos, em vez de gerar uma mensagem por controle.
 Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
 fragmentos, valores de formulário e nomes de arquivo são removidos ou
 sanitizados. `capture_network_error_bodies: true` lê somente respostas JSON
@@ -552,15 +745,18 @@ Para testar microfone, conceda permissão no escopo da chamada:
 {
   "options": {
     "permissions": ["microphone"],
-    "fake_media": "fixtures/resposta-aluno.wav",
+    "fake_media": {"audio":"fixtures/resposta-aluno.wav"},
     "block_trackers": true
   }
 }
 ```
 
-`fake_media` exige um WAV RIFF válido dentro de `JEV_BROWSER_UPLOAD_ROOT` e
-respeita os mesmos limites de upload. O MCP adiciona as opções de dispositivo
-falso do Chromium e concede permissão ao contexto. Sem esse arquivo, a
+`fake_media` aceita tanto o caminho WAV direto quanto o objeto
+`{"audio":"caminho.wav"}`. Exige um WAV RIFF válido dentro de
+`JEV_BROWSER_UPLOAD_ROOT` e respeita os mesmos limites de upload. Ao informar
+`fake_media`, o MCP concede automaticamente a permissão `microphone`, adiciona
+as opções de dispositivo falso do Chromium e usa o arquivo como entrada de
+áudio. Sem esse arquivo, a
 permissão de microfone usa o dispositivo autorizado pelo browser; no modo
 `computer`, o sistema operacional ainda pode pedir acesso ao dispositivo.
 
@@ -580,22 +776,62 @@ andamento, sem repetir o clique.
 
 Se o Chrome/Edge não iniciar porque o perfil persistente já está aberto, o erro
 identifica o PID que o mantém ocupado quando o sistema consegue associar o
-perfil ao processo. Em Windows, o MCP consulta a linha de comando dos processos
-Chrome/Edge; em outros sistemas, usa o `SingletonLock` do Chromium. Configure
-`JEV_BROWSER_PROFILE` com outro diretório absoluto para usar uma sessão isolada.
+perfil ao processo. Em Windows, o MCP consulta a linha de comando dos processos
+Chrome/Edge; em outros sistemas, usa o `SingletonLock` do Chromium. O caminho
+padrão já separa processos por PID; configure `JEV_BROWSER_PROFILE` para mudar
+a raiz e `JEV_BROWSER_SESSION_ID` para nomear a instância.
 Resultados MCP incluem `server_version`; erros também começam com a versão do
-servidor para facilitar a comparação entre instalações. A ferramenta
-`browser_health` informa se a sessão está ativa e tenta reconectar um browser
-que encerrou desde a chamada anterior. Passe `{"restart":true}` para fechar e
-reiniciar somente o navegador administrado por este processo MCP. Um fluxo pode
-ser repetido automaticamente uma vez após `BROWSER_DISCONNECTED` quando nenhuma
-etapa mutável foi executada.
-
-`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
-`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;
-o diretório persistente armazena dados de login e é resolvido sob a pasta home
-do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
-`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
+servidor para facilitar a comparação entre instalações. A ferramenta
+`browser_health` informa se a sessão está ativa e tenta reconectar um browser
+que encerrou desde a chamada anterior. Passe `{"restart":true}` para fechar e
+reiniciar somente o navegador administrado por este processo MCP. Perfil ocupado
+é devolvido como `BROWSER_PROFILE_IN_USE` com o PID detectado e não provoca
+encerramento do Chrome/Edge existente.
+
+`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
+`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}` e
+`{session}`;
+o diretório persistente armazena dados de login e é resolvido sob a pasta home
+do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
+`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
+
+## Preparar smoke autenticado local
+
+O MCP não cria a identidade nem os dados do sistema testado. Para um smoke de
+administração, suba a API e a UI locais, use um banco descartável com dados
+fictícios e uma identidade OIDC de teste que tenha explicitamente a claim
+`administrator`. Mantenha as regras de autorização de produção iguais; um token
+de operador legado não deve ser promovido para admin só para fazer o smoke.
+
+Faça o preflight nesta ordem:
+
+1. `browser_health` confirma a versão, o perfil/sessão e a conexão do navegador.
+   Se o perfil estiver ocupado, use outro `JEV_BROWSER_SESSION_ID` ou
+   `JEV_BROWSER_PROFILE`; não encerre o Chrome do operador.
+2. `options.wait_for_http` aguarda a API local responder antes de abrir a UI.
+   Informe a URL da interface em `initial_url` e a rota de health da API no
+   probe.
+3. `run_browser_flow` confirma que a tela administrativa esperada está visível
+   e que a identidade abriu com papel administrativo. Se aparecer a tela de
+   login, configure a conta de teste ou o provedor OIDC local; não copie o token
+   para `flow`, `params` ou logs. Use `text_env` para campos secretos.
+4. Valide primeiro uma prévia read-only com `assert_*`, `assert_network` e
+   captura de evidência. Para um fluxo que poderia gravar dados, use
+   `dry_run: true`; ele para antes da primeira etapa marcada como mutável.
+5. Só execute o passo de gravação em dados fictícios, depois de conferir o texto
+   do diálogo com `confirm_modal`/`confirm_dialog` e autorizar o token de
+   confirmação. Reinicializações de serviços e consultas diretas ao banco ficam
+   fora do smoke de tela.
+
+Esse preflight é um roteiro composto por `browser_health`, `wait_for_http` e
+asserções da própria aplicação; não há uma ferramenta genérica que valide a
+claim OIDC `administrator`. A checagem do papel precisa usar um sinal visível ou
+uma asserção específica do sistema consumidor.
+
+Um `expected_outcome` descreve o objetivo; o resultado `passed` vem das
+asserções explícitas ou da conclusão do plano. Verifique
+`expected_outcome_visible` separadamente quando a frase global fizer parte do
+critério do teste.
 
 Defina o valor secreto na variável indicada por `jev.credential_env`, usando o
 secret manager ou ambiente do processo que inicia o harness. Não grave a chave
@@ -639,10 +875,13 @@ valores dos controles são substituídos e hrefs têm query string e fragmento
 removidos; padrões de PII também são mascarados. Com fast-path, um plano não
 gera chamada remota. Os passos, valores digitados, valores esperados pelas
 asserções, caminhos e conteúdo dos arquivos não são enviados.
-Não inclua segredos em `flow`, `expected_outcome` ou nas descrições. A resposta
-retorna o plano escolhido quando houver decisão, custo/confiança do provedor
-quando disponíveis e o snapshot final sanitizado. O fluxo passa quando o texto
-esperado aparece no snapshot ou quando todas as asserções declaradas passam.
+Não inclua segredos em `flow`, `expected_outcome` ou nas descrições. A resposta
+retorna o plano escolhido quando houver decisão, custo/confiança do provedor
+quando disponíveis e o snapshot final sanitizado. Um `expected_outcome` em
+texto simples é descritivo: `expected_outcome_visible` indica separadamente se
+a frase apareceu, e completar o plano pode resultar em `passed` mesmo que ela
+não apareça. Use a forma estruturada para tornar texto ou resposta de rede uma
+condição obrigatória; se ela não passar, o fluxo falha.
 
 `network_idle` é uma espera limitada e opcional. Polling e conexões contínuas
 não relacionadas a `url_contains` não bloqueiam o modo filtrado; prefira