@diegosouzacdv/jev-browser-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,1818 +1,374 @@
-# Orquestrador Multi-Agente Corporativo
+# Automação de tela com Jev e Playwright
 
-Orquestrador de desenvolvimento de software com LangGraph, LangChain, MCP,
-persistência SQLite, revisão multiagente, gates determinísticos, HITL e
-artefatos versionados por manifesto.
+## Instalar em outros harnesses com npm/npx
 
-O provedor LLM padrão do código é a Groq quando nenhuma variável é definida.
-O modelo padrão do perfil operacional deste projeto é
-`deepseek/deepseek-v4-flash-0731`, usado via OpenRouter.
-A chave nunca deve ser gravada no código, no `.env.example`, em checkpoints,
-logs ou relatórios.
+O repositório também contém um pacote Node independente do harness. Ele fala
+MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
+qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
+usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
+Python do orquestrador. As opções específicas do pacote ficam isoladas no
+bloco `jev_browser_mcp` para preservar o contrato do servidor Python.
 
-As configurações operacionais dos agentes ficam centralizadas em
-`config/agent-policy.json` (modelo, limite, timeout, retry, contrato, contexto,
-skills, MCP e ownership). Valide ou projete as variáveis de um workflow com:
-
-```bash
-python scripts/validate_agent_policy.py validate
-python scripts/render_agent_policy.py show
-python scripts/render_agent_policy.py --github-env
-```
-
-`ORQUESTRADOR_AGENT_RUNTIME_JSON` e demais variáveis legadas existem apenas
-para compatibilidade explícita; os workflows canônicos derivam a configuração
-do arquivo central.
-
-## 1. Pré-requisitos
-
-- Python 3.12+;
-- Git;
-- Docker Desktop/Engine para o sandbox estrito e para o Gitea local;
-- Node.js/npm somente quando houver validação TypeScript;
-- uma chave Groq criada no [console de API da Groq](https://console.groq.com/keys)
-  ou uma chave OpenRouter criada em [OpenRouter Keys](https://openrouter.ai/settings/keys);
-- OpenSSH no Windows para o acesso ao Gitea;
-- portas locais `3000` (HTTP) e `2222` (SSH) livres.
-
-Se uma chave foi publicada em chat, commit ou log, revogue-a e crie outra antes
-de continuar.
-
-## 2. Instalação local
-
-Windows PowerShell:
-
-```powershell
-py -3.12 -m venv .venv
-.venv\Scripts\Activate.ps1
-python -m pip install --upgrade pip
-pip install -r requirements.txt
-Copy-Item .env.example .env
-```
-
-Linux/macOS:
-
-```bash
-python3.12 -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
-pip install -r requirements.txt
-cp .env.example .env
-```
-
-Edite `.env` localmente. O arquivo `.env.example` é o catálogo versionado das
-variáveis suportadas; o `.env` é ignorado pelo Git e contém os valores
-específicos da máquina. Para o perfil local deste projeto:
-
-```dotenv
-ORQUESTRADOR_LLM_PROVIDER=openrouter
-OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
-ORQUESTRADOR_AGENT_MODEL=deepseek/deepseek-v4-flash-0731
-MCP_FILESYSTEM_ROOTS=.
-ORQUESTRADOR_SANDBOX_MODE=docker
-```
-
-Quando a chave estiver cadastrada no ambiente de usuário do Windows, use a
-expansão `${OPENROUTER_API_KEY}` acima; não copie o segredo para o `.env`. Para
-CI e produção, use secrets/variáveis do ambiente; não publique o arquivo `.env`.
-
-### Conferir a integridade da `.venv`
-
-A `.venv` é ignorada pelo Git: se algo reescrever um arquivo dela, nada o traz de
-volta. Em 2026-08-28 um script de tradução reescreveu 23 pacotes (`resolver` →
-`resolve`), e isso só apareceu semanas depois, como erros sem relação aparente.
-Cada pacote instalado guarda o sha256 de cada arquivo no próprio `RECORD`, e o
-script abaixo confere tudo contra ele:
-
-```powershell
-.venv\Scripts\python.exe scripts\venv_integrity.py
-```
-
-```bash
-.venv/bin/python scripts/venv_integrity.py
-```
-
-Sai `0` com `"clean": true`; sai `1` nomeando pacote e arquivo em `mismatched`
-(conteúdo diferente), `missing` (arquivo apagado) ou `unverifiable` (pacote sem
-`RECORD`, que não dá para conferir e por isso não conta como limpo). Rode com o
-interpretador da `.venv` que quer conferir. Leva de 1 a 11 s, conforme o cache de
-disco. Para reparar um pacote apontado:
-`pip install --force-reinstall --no-deps <pacote>==<versão>`.
-
-Na agenda do Hermes, uma vez por semana, pela skill
-`.hermes/skills/orquestrador-venv-integrity/`, que só reporta e nunca repara; o
-comando `hermes cron create` está no `SKILL.md` dela.
-
-## 2.1. Gitea local para Actions e espelhamento do GitHub
-
-O GitHub é a origem canônica deste projeto. O Gitea é uma cópia local usada para
-executar os workflows self-hosted; portanto, o fluxo normal é publicar primeiro
-em `origin` (GitHub) e depois atualizar o remote `gitea`. Não trate o clone local
-do Gitea como fonte de verdade.
-
-| Componente | Caminho/URL nesta máquina |
-|---|---|
-| Checkout de desenvolvimento | `C:\orquestrador` |
-| Servidor Gitea, compose e dados persistentes | `C:\gitea` |
-| Runner Linux/Docker | `C:\gitea-runner` |
-| Runner Windows/host | `C:\gitea-runner-win` |
-| URL configurada no compose | `http://192.168.1.3:3000` |
-| SSH do Gitea | `ssh://gitea-local/...` na porta `2222` |
-
-O `docker-compose.yml` atual usa `192.168.1.3`. Se o endereço da máquina mudar, atualize
-`ROOT_URL`, `DOMAIN` e `SSH_DOMAIN` no compose antes de registrar novos runners.
-Não misture `localhost`, o IP da LAN e outro hostname no mesmo registro: o endereço usado
-pelo runner precisa ser alcançável por ele.
-
-Referências oficiais: [instalação com Docker](https://docs.gitea.com/next/installation/install-with-docker/),
-[Gitea Actions](https://docs.gitea.com/usage/actions/overview/) e
-[Gitea Runner](https://docs.gitea.com/usage/actions/act-runner/).
-
-### Subir o servidor Gitea
-
-Inicie o Docker Desktop com o engine Linux e confirme que ele está saudável:
-
-~~~powershell
-docker info
-docker compose version
-~~~
-
-Suba a instância já configurada em `C:\gitea`; não recrie o volume de dados:
-
-~~~powershell
-Set-Location C:\gitea
-docker compose pull
-docker compose up -d
-docker compose ps
-docker compose logs --tail 100 server
-Invoke-WebRequest http://192.168.1.3:3000/api/v1/version -TimeoutSec 10
-~~~
-
-Na primeira instalação, acesse <http://192.168.1.3:3000>, crie o usuário
-administrador, ative Actions e confirme que o repositório
-`admin/projeto-global` existe. Os dados ficam em `C:\gitea\gitea`; não use
-`docker compose down -v`, pois isso remove o armazenamento persistente.
-
-Para parar temporariamente sem apagar dados:
-
-~~~powershell
-Set-Location C:\gitea
-docker compose stop
-~~~
-
-### GitHub como origem e Gitea como espelho
-
-No checkout principal, preserve `origin` apontando para o GitHub e mantenha o
-Gitea em um segundo remote:
-
-~~~powershell
-Set-Location C:\orquestrador
-git remote -v
-git remote set-url origin https://github.com/diegosouzacdv/orquestrador.git
-git remote set-url gitea ssh://gitea-local/admin/projeto-global.git
-git fetch origin --prune
-~~~
-
-Se `gitea` ainda não existir, use `git remote add gitea ...` em vez de
-`set-url`. A chave SSH do Gitea pode ser criada assim:
-
-~~~powershell
-$sshDir = Join-Path $env:USERPROFILE ".ssh"
-New-Item -ItemType Directory -Force $sshDir | Out-Null
-ssh-keygen -t ed25519 -C "gitea-local" -f (Join-Path $sshDir "gitea_local")
-Get-Content (Join-Path $sshDir "gitea_local.pub")
-~~~
-
-Adicione a chave pública em **Gitea → Settings → SSH / GPG Keys** e crie
-`C:\Users\<usuario>\.ssh\config`:
-
-~~~sshconfig
-Host gitea-local
-  HostName 192.168.1.3
-  Port 2222
-  User git
-  IdentityFile ~/.ssh/gitea_local
-  IdentitiesOnly yes
-~~~
-
-Valide a autenticação e publique o mesmo commit nos dois destinos:
-
-~~~powershell
-ssh -T gitea-local
-git pull --ff-only origin master
-git push origin master
-git push gitea master:master
-git push gitea --tags
-git ls-remote origin refs/heads/master
-git ls-remote gitea refs/heads/master
-~~~
-
-O `ssh -T` pode responder que não existe shell interativo; isso é esperado se a
-autenticação funcionar. O último bloco deve mostrar o mesmo SHA no GitHub e
-no Gitea. O clone atual em `C:\gitea-runner\repositorio` é apenas um bootstrap
-antigo e não deve ser usado como origem do espelho sem antes conferir seus
-remotes e seu estado:
-
-~~~powershell
-git -C C:\gitea-runner\repositorio remote -v
-git -C C:\gitea-runner\repositorio status --short --branch
-~~~
-
-Para espelhar também branches e tags removidas, use um clone bare dedicado.
-O comando `git push --mirror` substitui todas as refs do repositório de destino;
-confirme o destino antes de executá-lo e não aponte para um repositório com
-trabalho independente:
-
-~~~powershell
-$mirror = "C:\gitea-runner\github-mirror.git"
-if (Test-Path $mirror) { throw "O mirror já existe; valide-o manualmente antes de reutilizar o caminho." }
-git clone --mirror https://github.com/diegosouzacdv/orquestrador.git $mirror
-Set-Location $mirror
-git remote add gitea ssh://gitea-local/admin/projeto-global.git
-git fetch origin --prune
-git push --mirror gitea
-~~~
-
-### Runner Linux/Docker — `C:\gitea-runner`
-
-Este é o runner usado pelos workflows com `runs-on: ubuntu-latest`, como
-`.gitea/workflows/agentic-graph-e2e.yml` e
-`.gitea/workflows/mcp-integration-smoke.yml`. Ele usa Docker Desktop e o
-socket `/var/run/docker.sock` dentro dos jobs. O socket dá ao job controle do
-Docker do host; aceite jobs somente do repositório confiável.
-
-O binário e a configuração já ficam em `C:\gitea-runner`. Se for necessário
-registrar novamente, gere o arquivo uma única vez, solicite um token novo na
-interface do Gitea e não salve o token em arquivo, histórico ou Git:
-
-~~~powershell
-Set-Location C:\gitea-runner
-if (!(Test-Path .\config.yaml)) {
-  .\act_runner.exe config generate | Out-File -Encoding utf8 .\config.yaml
-}
-$runnerToken = Read-Host "Token do runner Gitea"
-.\act_runner.exe register --no-interactive --instance "http://192.168.1.3:3000" --token $runnerToken --name "orquestrador-local" --labels "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04,ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04"
-Remove-Variable runnerToken
-~~~
-
-Na configuração, preserve pelo menos estas opções para os workflows Docker:
-
-~~~yaml
-container:
-  options: --volume /var/run/docker.sock:/var/run/docker.sock --add-host=host.docker.internal:host-gateway
-  valid_volumes:
-    - '**'
-  require_docker: true
-  docker_timeout: 60s
-  bind_workdir: true
-~~~
-
-Teste em primeiro plano antes de depender do serviço do Windows:
-
-~~~powershell
-docker info
-Set-Location C:\gitea-runner
-.\act_runner.exe daemon --config C:\gitea-runner\config.yaml
-~~~
-
-Nesta máquina, o serviço `GiteaActRunner` já está configurado para executar
-`C:\gitea-runner\act_runner.exe daemon --config C:\gitea-runner\config.yaml`.
-Depois que o Docker Desktop estiver pronto, reinicie-o e confira o log:
-
-~~~powershell
-Get-Service GiteaActRunner
-Restart-Service GiteaActRunner
-Get-Content C:\gitea-runner\service.err.log -Tail 80
-~~~
-
-O serviço deve aparecer como `Running` e o runner deve ficar online em
-**Gitea → Actions → Runners**. Se `docker info` falhar ou o log mencionar
-`Docker Engine socket not found`, corrija o Docker Desktop primeiro; reiniciar
-o runner sozinho não resolve essa causa.
-
-Estado verificado em 2026-09-13: serviço `Running`, runner `orquestrador-local`
-(id 3) em `v3.3.1`, com as três labels `ubuntu-*` e `last_online` corrente. O
-log de sucesso tem exatamente três linhas — `Starting runner daemon`,
-`Docker is ready` e `declare successfully`. A ausência de `Docker is ready`
-neste runner é defeito; no runner Windows, não.
-
-Uma enxurrada de `failed to fetch task ... target machine actively refused it`
-**não** é defeito do runner: é o container do Gitea parado. O runner fica em
-retry e volta sozinho quando o servidor sobe — foi o que ocorreu entre 07:41 e
-07:55 de 2026-09-13, com recuperação às 07:59 sem nenhuma intervenção no
-runner. Antes de mexer no runner, confira `docker compose ps` em `C:\gitea`.
-
-### Runner Windows/host — `C:\gitea-runner-win`
-
-Este é um segundo runner, independente do runner Docker, registrado como
-`orquestrador-windows` (id 4) com a label `windows-latest:host`. Ele é usado
-pelos jobs Windows da matriz `os: [ubuntu-latest, windows-latest]` de
-`.gitea/workflows/antigravity-sdk-homologation.yml` — hoje o único workflow
-Gitea que não é só `ubuntu-latest`. Sem este runner, a perna `windows-latest`
-dessa matriz fica enfileirada para sempre em vez de falhar, que é o sintoma
-pelo qual essa ausência costuma ser percebida.
-
-**O serviço `GiteaActRunnerWindows` já existe nesta máquina** e está correto:
-NSSM, `AUTO_START`, `Application=C:\gitea-runner-win\act_runner.exe`,
-`AppDirectory=C:\gitea-runner-win`,
-`AppParameters=daemon --config C:\gitea-runner-win\config.yaml`. Confira antes
-de tentar criá-lo de novo — `nssm install` sobre um serviço existente não é o
-caminho:
-
-~~~powershell
-sc.exe query GiteaActRunnerWindows
-reg query "HKLM\SYSTEM\CurrentControlSet\Services\GiteaActRunnerWindows\Parameters"
-~~~
-
-#### As duas causas que mantiveram este runner parado
-
-Diagnosticadas em 2026-09-13, com o serviço existente e bem configurado:
-
-1. **O binário não estava lá.** `C:\gitea-runner-win\` tinha `.runner` e
-   `config.yaml`, mas não `act_runner.exe`. O serviço sobe, não acha o
-   executável e morre com `ESTADO: STOPPED`, `WIN32_EXIT_CODE: 1066 (0x42a)` e
-   `SERVICE_EXIT_CODE: 3` — `ERROR_PATH_NOT_FOUND`. O 1066 é genérico
-   ("erro específico do serviço") e não aponta o arquivo; quem lê só o 1066
-   procura defeito de registro e não encontra nada.
-2. **`require_docker: true` herdado do runner Docker.** O `config.yaml` deste
-   diretório é cópia do config do runner Linux, inclusive do bloco
-   `container:`. A opção está documentada no próprio arquivo como *"Always
-   require a reachable docker daemon, **even if not required by runner**"* —
-   ou seja, ela amarra a subida deste runner ao Docker Desktop, que um runner
-   `host` não usa. Com o Docker parado, o runner Windows recusa subir sem ter
-   motivo próprio para isso.
-
-Correção das duas, na ordem:
-
-~~~powershell
-Set-Location C:\gitea-runner-win
-if (!(Test-Path .\act_runner.exe)) {
-  Copy-Item C:\gitea-runner\act_runner.exe .\act_runner.exe
-}
-.\act_runner.exe --version   # precisa casar com o runner Docker: v3.3.1
-~~~
-
-No `config.yaml` deste runner, e **somente** neste, deixe:
-
-~~~yaml
-container:
-  require_docker: false
-~~~
-
-O resto do bloco `container:` (socket Docker, `valid_volumes`, `bind_workdir`)
-é inerte aqui, porque um runner `host` não cria container — mas mantê-lo copiado
-é o que faz `require_docker` voltar despercebido na próxima cópia do arquivo.
-
-Valide em foreground antes de depender do serviço:
-
-~~~powershell
-Set-Location C:\gitea-runner-win
-.\act_runner.exe daemon --config C:\gitea-runner-win\config.yaml
-~~~
-
-O sucesso são **duas** linhas, sem `Docker is ready`:
-
-~~~text
-level=info msg="Starting runner daemon"
-level=info msg="runner: orquestrador-windows, with version: v3.3.1, with labels: [windows-latest], declare successfully"
-~~~
-
-`Docker is ready` aqui significa que `require_docker` voltou a `true`. A label
-sai como `windows-latest` porque o `:host` é o modo de execução do lado do
-runner, não parte do nome da label — `runs-on: windows-latest` no workflow é o
-que casa.
-
-O `config.yaml` desse runner aponta
-`ORQUESTRADOR_WINDOWS_PYTHON` para
-`C:\orquestrador\.venv\Scripts\python.exe`. Confira que o ambiente virtual
-existe e tem as dependências do projeto antes de iniciar o serviço.
-
-Encerre o foreground com `Ctrl+C` antes de subir o serviço: os dois usam o
-mesmo `.runner.lock` e a mesma identidade registrada.
-
-#### Subir o serviço — exige PowerShell elevado
-
-`sc.exe start` sem elevação falha com `OpenService FALHA 5: Acesso negado`, e
-esse 5 é do controle do serviço, não do runner. Em PowerShell **como
-administrador**:
-
-~~~powershell
-Start-Service GiteaActRunnerWindows
-Get-Service GiteaActRunner, GiteaActRunnerWindows
-~~~
-
-Executado pelo operador em 2026-09-13: o serviço ficou `RUNNING` e os **dois**
-runners passaram a reportar `last_online` no mesmo minuto — id 3
-(`orquestrador-local`) e id 4 (`orquestrador-windows`), com 12 segundos de
-diferença. É essa a evidência que fecha a subida dos dois runners; serviço
-`RUNNING` sozinho não prova conexão com o Gitea.
-
-Só crie o serviço com NSSM se `sc.exe query` disser que ele não existe. Ele
-precisa de diretório de trabalho próprio e não pode reutilizar o registro do
-runner Docker:
-
-~~~powershell
-$nssm = (Get-Command nssm.exe).Source
-& $nssm install GiteaActRunnerWindows C:\gitea-runner-win\act_runner.exe
-& $nssm set GiteaActRunnerWindows AppDirectory C:\gitea-runner-win
-& $nssm set GiteaActRunnerWindows AppParameters 'daemon --config C:\gitea-runner-win\config.yaml'
-& $nssm set GiteaActRunnerWindows Start SERVICE_AUTO_START
-Start-Service GiteaActRunnerWindows
-~~~
-
-O modo `host` expõe o ambiente Windows, ferramentas e credenciais da máquina
-ao job. Use-o apenas para workflows confiáveis.
-
-### Secrets e workflows
-
-Secrets do GitHub não são copiados automaticamente para o Gitea. Cadastre no
-repositório Gitea, em **Settings → Actions → Secrets**, os valores exigidos
-pelos workflows, como `OPENROUTER_API_KEY`, `CONTEXT7_API_KEY`,
-`TWENTY_FIRST_API_KEY` e `GEMINI_API_KEY` quando aplicável. Tokens de clone e
-tokens de registro de runner devem ser tratados separadamente e nunca entrar
-no repositório.
-
-Os arquivos em `.gitea/workflows/` são executados pelo Gitea. Os arquivos em
-`.github/workflows/` continuam sendo executados pelo GitHub Actions; o fato de
-o conteúdo ser espelhado não faz o Gitea executar workflows do GitHub. Dentro
-de um job Docker, use `http://host.docker.internal:3000` para acessar o Gitea;
-`localhost` aponta para o próprio container.
-
-### Diagnóstico e manutenção
-
-~~~powershell
-Set-Location C:\gitea
-docker compose ps
-docker compose logs --tail 100 server
-Get-Service GiteaActRunner
-Get-Content C:\gitea-runner\service.err.log -Tail 80
-Get-Service GiteaActRunnerWindows -ErrorAction SilentlyContinue
-Get-Content C:\gitea-runner-win\service.err.log -Tail 80 -ErrorAction SilentlyContinue
-~~~
-
-Serviço `Running` prova que o processo existe, não que o runner está falando
-com o Gitea. Quem responde isso é o `last_online` do servidor, e ele é
-consultável sem abrir a interface e sem autenticar:
-
-~~~powershell
-docker exec gitea sqlite3 /data/gitea/gitea.db "select id, name, version, agent_labels, datetime(last_online,'unixepoch','localtime') from action_runner where deleted is null;"
-~~~
-
-**O `where deleted is null` não é opcional.** O Gitea apaga runner por *soft
-delete*: a linha permanece em `action_runner` com a coluna `deleted`
-preenchida, e a interface e a API deixam de listá-la. Uma consulta sem esse
-filtro mostra registros já removidos como se estivessem ativos — foi o que
-aconteceu em 2026-09-13, quando os ids 1 e 2 foram lidos como "órfãos
-aparecendo offline na interface" e na verdade já tinham sido excluídos em
-2026-08-30, minutos depois de criados e antes do id 3 existir.
-
-Um `last_online` recente é o runner online agora. Os registros vivos nesta
-máquina são o id 3 (`orquestrador-local`, labels `ubuntu-*`) e o id 4
-(`orquestrador-windows`, label `windows-latest`). Para conferir o que a
-interface de fato mostra, sem depender da leitura do banco:
-
-~~~powershell
-docker exec gitea sqlite3 /data/gitea/gitea.db "select id, datetime(deleted,'unixepoch','localtime') from action_runner;"
-~~~
-
-Nunca apague linha de `action_runner` por SQL: remover runner é operação de
-interface, e o soft delete existe para preservar a trilha dos jobs que aquele
-runner atendeu.
-
-Se um runner for removido pela interface do Gitea, pare o daemon e remova
-somente `.runner` e `.runner.lock` no diretório daquele runner; preserve
-`config.yaml`, registre um novo token e valide novamente. Nunca remova
-`C:\gitea\gitea` para corrigir um problema de runner.
-
-No diagnóstico desta máquina, em 2026-09-11, o endpoint do Gitea recusou
-conexão porque o container estava parado e `C:\gitea-runner\service.err.log`
-registrou `Docker Engine socket not found`. A sequência de recuperação é:
-
-~~~powershell
-Set-Location C:\gitea
-docker compose up -d
-docker info
-Restart-Service GiteaActRunner
-Get-Content C:\gitea-runner\service.err.log -Tail 80
-~~~
-
-Em 2026-09-13 o Gitea (`1.27.3`) e o runner Docker estavam saudáveis, e só o
-runner Windows estava parado: binário ausente e `require_docker: true` herdado.
-A lição de diagnóstico é que os dois runners falham por causas **disjuntas** —
-o Docker depende do Docker Desktop e do container do Gitea; o Windows/host não
-depende de nenhum dos dois. Tratar "os runners não sobem" como um problema só
-faz procurar causa comum onde não há.
-
-## 2.2. Variáveis de ambiente
-
-O arquivo [`.env.example`](.env.example) é o catálogo versionado das variáveis
-suportadas. O `.env` local é ignorado pelo Git e não deve ser publicado.
-Para as credenciais cadastradas no ambiente de usuário do Windows, use referências
-sem copiar os valores:
-
-```dotenv
-OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
-CONTEXT7_API_KEY=${CONTEXT7_API_KEY}
-TWENTY_FIRST_API_KEY=${TWENTY_FIRST_API_KEY}
-```
-
-Abra um novo PowerShell depois de alterar variáveis no Windows. Confira somente
-a presença das credenciais:
-
-```powershell
-python -c "import os; from dotenv import load_dotenv; load_dotenv('.env', override=False); names=['OPENROUTER_API_KEY','CONTEXT7_API_KEY','TWENTY_FIRST_API_KEY']; print({n:bool(os.environ.get(n)) for n in names})"
-git check-ignore -v .env
-python scripts/validate_agent_policy.py validate
-python scripts/plan_status.py validate
-```
-
-As variáveis estão organizadas no `.env.example` por provider LLM, OpenRouter,
-MCP, Gitea/Git, sandbox, retry, kernel, orçamento, observabilidade, skills,
-HITL, identidade e mídia. O modelo padrão operacional é
-`deepseek/deepseek-v4-flash-0731`; o Backend usa `reasoning_effort=max` na
-política central `config/agent-policy.json`. Não habilite overrides legados.
-
-## 2.3. Supermemory local (memória entre sessões)
-
-Desde 2026-09-23, por decisão do operador, a memória entre sessões mora no
-`supermemory-server` rodando no **WSL Ubuntu** da máquina do operador. O plano da
-nuvem chegou ao limite e passou a recusar gravações, e o conector da nuvem foi
-**desativado** no mesmo dia (claude.ai → Settings → Connectors → Supermemory). As
-regras de uso estão no `AGENTS.md`, subseção "Supermemory: o servidor local do
-operador".
-
-Tudo abaixo roda **dentro do Ubuntu** (`wsl -d Ubuntu`), a partir de `~`, nunca
-de `/mnt/c/...`: a pasta de dados segue o diretório atual quando não é fixada, e
-`/mnt/c` é o disco do Windows, mais lento.
-
-### Instalar (uma vez)
-
-```bash
-sudo apt update && sudo apt install -y curl
-cd ~ && curl -fsSL https://supermemory.ai/install | bash
-echo 'export PATH="$HOME/.supermemory/bin:$PATH"' >> ~/.bashrc
-```
-
-### Configuração fixa (uma vez)
-
-Embedding multilíngue e local, com a pasta de dados fixada. Nada disso é
-segredo. O `embedding-plan.json` que o assistente grava **não** é o que o
-servidor carrega; sem estas variáveis ele sobe com o modelo inglês de 768
-dimensões, que não combina com as tabelas de 1024 (medido em 2026-09-23).
-
-```bash
-cat >> ~/.bashrc <<'EOF'
-export SUPERMEMORY_EMBEDDING_PROVIDER=local
-export SUPERMEMORY_EMBEDDING_MODEL=Xenova/bge-m3
-export SUPERMEMORY_EMBEDDING_DIMENSIONS=1024
-export SUPERMEMORY_DATA_DIR="$HOME/.supermemory"
-EOF
-source ~/.bashrc
-```
-
-Chave do LLM que extrai as memórias (GLM, pela API compatível com OpenAI da
-Z.ai). A chave vai para um arquivo **fora** de `~/.supermemory`, porque o
-servidor lê o `~/.supermemory/env`, cifra o conteúdo em `env.enc` e apaga o
-original; e a extração roda num processo que só enxerga variáveis exportadas.
-
-```bash
-mkdir -p ~/.config/glm && chmod 700 ~/.config/glm
-read -rsp "Chave GLM: " K; echo; printf '%s' "$K" > ~/.config/glm/key; unset K
-chmod 600 ~/.config/glm/key
-
-cat >> ~/.bashrc <<'EOF'
-sm() { ( export OPENAI_API_KEY="$(cat "$HOME/.config/glm/key")" \
-  OPENAI_BASE_URL=https://api.z.ai/api/coding/paas/v4 \
-  OPENAI_MODEL=glm-4.6 OPENAI_FAST_MODEL=glm-4.5-air
-  exec supermemory-server "$@" ); }
-EOF
-source ~/.bashrc
-```
-
-`OPENAI_BASE_URL` depende do plano da Z.ai: com a assinatura de código use a URL
-`coding` acima; com saldo pré-pago, `https://api.z.ai/api/paas/v4`. A URL errada
-responde `Insufficient balance or no resource package`.
-
-### Subir e conferir
-
-```bash
-cd ~ && sm                      # sobe em http://localhost:6767 e fica em primeiro plano
-supermemory-server doctor       # noutro terminal: provedor, embedding, pasta de dados
-```
-
-O quadro `supermemory ready` precisa mostrar `database /home/<você>/.supermemory` e
-`embeddings local · Xenova/bge-m3 · 1024d`. **Não compartilhe prints desse quadro:
-a linha `api key` traz a chave inteira.**
-
-### Testar
-
-```bash
-# grava um documento; no terminal do servidor a linha final deve terminar em "N memories"
-curl -s http://localhost:6767/v3/documents -H "Content-Type: application/json" \
-  -d '{"content":"Teste do Supermemory local.","containerTag":"orquestrador"}'; echo
-
-# busca: containerTags é LISTA. Sem ela, ou com containerTag no singular, a
-# resposta é 200 com resultado vazio -- parece "nada gravado" e não é.
-curl -s http://localhost:6767/v4/search -H "Content-Type: application/json" \
-  -d '{"q":"supermemory local","containerTags":["orquestrador"],"searchMode":"memories","threshold":0}'; echo
-```
-
-Mande sempre `threshold`. Sem ele o servidor aplica um limiar próprio e descarta
-memória relevante: medido em 2026-09-23, "Hermes cron workdir" devolveu 1 memória
-sem `threshold` e as do mesmo assunto com `threshold: 0`. Com 0, a busca devolve
-as mais próximas até o `limit`, cada uma com a `similarity` ao lado. O cliente do
-orquestrador manda o valor de `config/durable-stores.json`,
-`memory_store.search_threshold`.
-
-Teste de ponta a ponta de **todas** as chamadas que o orquestrador faz (gravar,
-buscar, editar, grafo, ler, esquecer, apagar), num espaço descartável
-`orquestrador-smoke`, que ele limpa no fim. Cada linha diz `OK` ou `FAIL` com o
-motivo que o servidor deu:
-
-```bash
-PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_local_smoke.py
-```
-
-No **Windows**, que é onde a `.venv` do projeto mora, rode pelo PowerShell a
-partir do checkout — o Windows alcança o servidor do WSL por `127.0.0.1:6767`.
-Os scripts abaixo (migração e sync) seguem a mesma forma:
-
-```powershell
-cd C:\orquestrador            # ou a worktree da branch que tem os scripts
-$env:PYTHONPATH = (Get-Location).Path
-$env:PYTHONUTF8 = "1"          # o console cp1252 quebra no ✅ das memórias
-$py = "C:\orquestrador\.venv\Scripts\python.exe"
-& $py scripts\supermemory_local_smoke.py
-```
-
-A busca do smoke tenta de novo por até 30 s antes de reprovar: o servidor indexa
-a memória nova na própria fila, e uma espera fixa confundia "ainda não indexou"
-com "a busca não funciona".
-
-### Listar as memórias
-
-```bash
-# documentos do espaço, paginados
-curl -s http://localhost:6767/v3/documents/list -H "Content-Type: application/json" \
-  -d '{"containerTags":["orquestrador"],"page":1,"limit":50}'; echo
-
-# um documento com as memórias extraídas dele
-curl -s http://localhost:6767/v3/documents/<documentId>; echo
-```
-
-Pelo orquestrador, o grafo inteiro (todos os documentos com as memórias de cada
-um) sai de `GET /memory/graph` da API HTTP (seção 7), autenticado como as outras
-rotas.
-
-### Migrar as memórias da nuvem (uma vez)
-
-Com o servidor de pé, a partir do checkout do orquestrador:
-
-```bash
-PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_migrate_to_local.py --dry-run
-PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_migrate_to_local.py
-```
-
-São as 33 memórias de `docs/supermemory/cloud-export-2026-09-23.json`, já
-normalizadas para o padrão de gravação, escritas com o texto exato, sem reprocessar
-no LLM. O script confere o export inteiro contra o padrão **antes** da primeira
-gravação — `--dry-run` lista em `invalid` o que seria recusado — e guarda em
-`data/supermemory-migration.json` o que já foi aceito: rodar de novo não duplica.
-
-### Padrão de gravação (aplicado pelo código)
-
-Toda gravação — MCP, tela, migração, inbox — passa por `src/memory/standard.py`,
-que recusa e nomeia cada violação. O formato que passa:
-
-```text
-TEC-002 was delivered on 2026-09-22 in commit 93bbf57.
-STK-004 was marked ✅, meaning developed and validated within the scope of the cited evidence, not approved by the operator, on 2026-09-22 in commit d2ab40d.
-```
-
-Uma frase, em inglês, com data ISO e âncora (SHA, id de item ou `session <id>`),
-ícone com o sentido escrito, sem estado volátil ("still pending", "in progress")
-e sem segredo. Os valores estão em `config/durable-stores.json`,
-`memory_store.standard`.
-
-### Sincronizar com as sessões da nuvem
-
-Sessões na nuvem não alcançam este servidor. Elas leem
-`docs/supermemory/snapshot.json` e gravam em `docs/supermemory/inbox/`, que chegam
-aqui pelo git. Depois de trazer as branches mescladas para o checkout:
-
-```bash
-PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_sync.py
-git add docs/supermemory/snapshot.json
-git commit -m "memory: snapshot do servidor local" -- docs/supermemory/snapshot.json
-```
-
-O script aplica cada operação do inbox uma vez (o registro fica em
-`data/supermemory-sync.json`) e reescreve o snapshot a partir do servidor. Rode-o
-depois da migração, para o snapshot passar a vir do servidor, e sempre que um
-inbox novo chegar. O Hermes pode rodá-lo na mesma agenda do laço do plano.
-
-As memórias seguidas de uma mesma sessão vão numa chamada só, e o servidor faz um
-documento por chamada: no grafo, cada sessão aparece como um documento com os
-fatos em volta. Até 2026-09-23 cada memória ia sozinha, e o grafo mostrava um par
-documento-memória para cada uma.
-
-### Reagrupar as memórias gravadas uma por documento (uma vez)
-
-As 42 memórias gravadas antes dessa mudança continuam uma por documento. O
-reagrupamento junta cada lote de gravação da nuvem e cada sessão do inbox num
-documento só. Ele só apaga um documento antigo **depois** de conferir que cada
-memória dele está no documento novo, e no fim confere que o conjunto de memórias
-é o mesmo de antes, sem perda e sem duplicata. Memória que o repositório não
-conhece (gravada pela tela, por exemplo) fica onde está.
-
-```powershell
-git fetch origin claude/nifty-knuth-27gns3
-git checkout origin/claude/nifty-knuth-27gns3
-& $py scripts\supermemory_sync.py                  # aplica o que estiver no inbox
-& $py scripts\supermemory_regroup.py               # só o plano, não toca em nada
-& $py scripts\supermemory_regroup.py --apply       # "verified": true no fim
-& $py scripts\supermemory_sync.py                  # snapshot a partir do servidor
-git add docs/supermemory/snapshot.json
-git commit -m "memory: snapshot reagrupado" -- docs/supermemory/snapshot.json
-```
-
-`--apply` sai `0` só com `"verified": true`. Se sair `1`, nada foi apagado antes
-do problema: o relatório nomeia o grupo que o servidor não confirmou. Rodar de
-novo é seguro.
-
-### Sessões e Hermes: o MCP `supermemory-local`
-
-O `.mcp.json` declara `supermemory-local`, um MCP `stdio` que chama o servidor
-local. Ferramentas: `search_memory`, `add_memory` (`action` `save`/`forget`),
-`list_memories`, `get_document`, `update_memory`, `delete_document`. O
-interpretador vem de `ORQUESTRADOR_PYTHON`:
-
-```powershell
-# Windows (checkout em C:\orquestrador)
-[System.Environment]::SetEnvironmentVariable("ORQUESTRADOR_PYTHON", "C:\orquestrador\.venv\Scripts\python.exe", "User")
-```
-
-```bash
-# Linux/WSL
-echo "export ORQUESTRADOR_PYTHON=$PWD/.venv/bin/python" >> ~/.bashrc
-```
-
-Depois, em uma sessão nova, `/mcp` deve listar `supermemory-local` conectado.
-Se o interpretador escolhido não tiver o pacote `mcp`, o servidor se entrega ao
-`python` da `.venv` do projeto. Sessões na nuvem (claude.ai/code) **não** alcançam
-o `localhost` do operador: o mesmo MCP responde a elas pelo snapshot e grava no
-inbox, com o erro do servidor ao lado para ninguém confundir espelho com servidor.
-Para o MCP subir num container da nuvem, o ambiente precisa da `.venv` com
-`requirements.txt` instalado — o script de setup do ambiente é o lugar.
-
-Hermes, em `~/.hermes/config.yaml`. O nome `supermemory` mantém as ferramentas
-`mcp_supermemory_search_memory` e `mcp_supermemory_add_memory` que a skill
-`orquestrador-plan-loop` já chama:
-
-```yaml
-mcp_servers:
-  supermemory:
-    command: /caminho/do/orquestrador/.venv/bin/python
-    args: ["/caminho/do/orquestrador/mcp_servers/supermemory_local_server.py"]
-```
-
-### Espaço de desenvolvimento e despacho contínuo pelo Hermes
-
-Desde 2026-09-24 a memória tem dois espaços. O geral (`orquestrador`) guarda
-decisões e achados; o de desenvolvimento (`orquestrador-dev`) guarda só os
-registros `[dispatch]`, `[result]`, `[blocked]` e `[compact]` do despacho. O mesmo
-servidor MCP atende os dois: `supermemory-dev` é ele com
-`SUPERMEMORY_LOCAL_SPACE=dev`, já declarado no `.mcp.json`. O espaço dev não tem
-espelho versionado; sem o servidor, ele responde com o erro e nada mais.
-
-O Hermes despacha cada task do plano para a sessão Claude Code persistente do
-papel dela (`backend`, `frontend`, `docs`, `dba`), um turno por task com
-`claude -p --resume`, até o plano acabar. Política em `config/dev-dispatch.json`;
-instalação, pré-requisitos (login do Claude Code, uma worktree e uma sessão por
-papel, o campo `role` nos itens) e operação em
-[`.hermes/skills/orquestrador-dev-dispatcher/SKILL.md`](.hermes/skills/orquestrador-dev-dispatcher/SKILL.md).
-Para ver o que ele faria sem lançar nada:
-
-```powershell
-$env:HERMES_HOME = "$env:LOCALAPPDATA\hermes"
-C:\orquestrador\.venv\Scripts\python.exe .hermes\skills\orquestrador-dev-dispatcher\scripts\dispatch_tick.py --repo C:\orquestrador --dry-run
-```
-
-### Segurança da porta 6767
-
-O servidor escuta em `0.0.0.0:6767` (`ss -ltn | grep 6767`), e não há opção
-documentada para prendê-lo ao `localhost`. No WSL2 em modo NAT, o padrão, só o
-próprio Windows o alcança. Se o `.wslconfig` usa `networkingMode=mirrored`, ou se
-houver `portproxy`, a rede local também alcança. Bloqueie a entrada vinda da rede
-no firewall do Windows (PowerShell como administrador). O tráfego de loopback
-não passa por essa regra:
-
-```powershell
-New-NetFirewallRule -DisplayName "Supermemory local - bloqueia rede" -Direction Inbound `
-  -Protocol TCP -LocalPort 6767 -RemoteAddress LocalSubnet,Internet -Action Block
-```
-
-## 3. Modelos Groq
-
-Os perfis podem ser alterados sem modificar código:
-
-```dotenv
-ORQUESTRADOR_MODEL_STRUCTURED=openai/gpt-oss-20b
-ORQUESTRADOR_MODEL_CODING=openai/gpt-oss-120b
-ORQUESTRADOR_MODEL_REASONING=openai/gpt-oss-120b
-ORQUESTRADOR_MODEL_RESEARCH=groq/compound
-ORQUESTRADOR_MODEL_RESEARCH_FAST=groq/compound-mini
-ORQUESTRADOR_MODEL_INPUT_GUARD=meta-llama/llama-prompt-guard-2-86m
-ORQUESTRADOR_MODEL_OUTPUT_GUARD=openai/gpt-oss-safeguard-20b
-```
-
-Mapa recomendado, conforme a documentação oficial da Groq:
-
-| Perfil/modelo | Janela | Máx. saída | Uso |
-|---|---:|---:|---|
-| `openai/gpt-oss-20b` | 131.072 | 65.536 | router, classificações e JSON estruturado rápido |
-| `openai/gpt-oss-120b` | 131.072 | 65.536 | código, arquitetura, review, compliance e DBA |
-| `groq/compound` | 131.072 | 8.192 | pesquisa/agentes com ferramentas Groq |
-| `groq/compound-mini` | 131.072 | 8.192 | pesquisa rápida e sumarização |
-| `meta-llama/llama-prompt-guard-2-86m` | 512 | 512 | classificação de prompt de entrada |
-| `openai/gpt-oss-safeguard-20b` | 131.072 | 65.536 | inspeção de saída/safety |
-| `qwen/qwen3.6-27b` | 131.072 | 16.384 | alternativa experimental; modelo preview e mais caro |
-
-O perfil estruturado usa `json_schema` nos GPT-OSS; o perfil de
-código/raciocínio usa o GPT-OSS 120B. Compound fica reservado para pesquisa
-com ferramentas. Prompt Guard e Safeguard permanecem nos portões de segurança
-e foram validados pelo smoke real do workflow Groq.
-
-Os números da tabela são capacidades máximas dos modelos, não a quota da
-conta. No tier on-demand com 8.000 TPM, configure limites conservadores para
-que entrada mais saída solicitada caibam na quota:
-
-```dotenv
-ORQUESTRADOR_LLM_MAX_INPUT_CHARS=12000
-ORQUESTRADOR_GROQ_MAX_COMPLETION_TOKENS=2048
-```
-
-Ao migrar para um tier superior, esses dois valores podem ser aumentados sem
-alterar o código.
-
-Para OpenRouter, os limites não ficam presos aos valores conservadores da
-Groq. O catálogo operacional por modelo está centralizado em
-[`src/llm/llm_model_config.py`](src/llm/llm_model_config.py). A troca global do modelo
-é feita em um único ponto:
-
-| Modelo agentic | Contexto | Máx. saída | Input / 1M | Output / 1M |
-|---|---:|---:|---:|---:|
-| `deepseek/deepseek-v4-flash-0731` | 1.310.720 | 943.718 | US$ 0,04 | US$ 0,08 |
-| `minimax/minimax-m3` (fallback produção) | 1.048.576 | 512.000 | US$ 0,30 | US$ 1,20 |
-| `moonshotai/kimi-k2.7-code` (fallback produção) | 262.144 | 235.929 | US$ 0,67 | US$ 3,40 |
-
-Os valores são snapshot do catálogo e não substituem o preço efetivo da
-resposta. O adapter registra usage/custo retornados pelo OpenRouter.
-
-```dotenv
-ORQUESTRADOR_LLM_PROVIDER=openrouter
-ORQUESTRADOR_AGENT_MODEL=deepseek/deepseek-v4-flash-0731
-```
-
-O `DeepSeek V4 Flash 0731` está registrado com contexto de 1.310.720 tokens e
-até 943.718 tokens de saída. O limite de entrada operacional é de 1.000.000
-de caracteres para evitar enviar acidentalmente o repositório inteiro em uma
-única chamada. Esses valores podem ser sobrescritos temporariamente com
-`ORQUESTRADOR_MODEL_CONFIG_JSON`, sem editar agentes. Um teto operacional por
-ambiente (`ORQUESTRADOR_OPENROUTER_MAX_COMPLETION_TOKENS` ou
-`ORQUESTRADOR_LLM_MAX_INPUT_CHARS`) continua disponível e tem precedência.
-
-Referências oficiais: [Quickstart Groq](https://console.groq.com/docs/quickstart),
-[modelos](https://console.groq.com/docs/models), [API compatível com OpenAI](https://console.groq.com/docs/openai),
-[Structured Outputs](https://console.groq.com/docs/structured-outputs),
-[LangChain + Groq](https://console.groq.com/docs/langchain),
-[Prompt Caching](https://console.groq.com/docs/prompt-caching) e
-[limites](https://console.groq.com/docs/rate-limits).
-Páginas dos modelos: [Compound](https://console.groq.com/docs/compound),
-[Compound mini](https://console.groq.com/docs/compound/systems/compound-mini),
-[GPT-OSS 120B](https://console.groq.com/docs/model/openai/gpt-oss-120b),
-[GPT-OSS 20B](https://console.groq.com/docs/model/openai/gpt-oss-20b),
-[Qwen 3.6 27B](https://console.groq.com/docs/model/qwen/qwen3.6-27b),
-[Prompt Guard 86M](https://console.groq.com/docs/model/meta-llama/llama-prompt-guard-2-86m) e
-[Safeguard 20B](https://console.groq.com/docs/model/openai/gpt-oss-safeguard-20b).
-
-## 4. Roteamento multi-provedor
-
-Os agentes usam uma fábrica única (`src/llm/llm_provider.py`) e podem ser
-direcionados individualmente, por perfil ou globalmente. O comportamento
-legado continua sendo Groq por padrão. As credenciais são sempre lidas de
-variáveis de ambiente:
-
-```dotenv
-# Provedor único para todos os agentes
-ORQUESTRADOR_LLM_PROVIDER=groq
-GROQ_API_KEY=...
-
-# Alternativas suportadas pelo adapter
-ANTHROPIC_API_KEY=...
-OPENAI_API_KEY=...
-GEMINI_API_KEY=...
-```
-
-Para escolher provedor e modelo por agente, use JSON no secret/variável
-`ORQUESTRADOR_LLM_ROUTING_JSON` (não coloque chaves dentro do JSON):
+Instale a versão publicada do npm diretamente no harness. Para fixar uma
+versão em produção, use o número explícito no argumento do pacote:
 
 ```json
 {
-  "default": {"provider": "groq", "model": "openai/gpt-oss-20b"},
-  "profiles": {
-    "reasoning": {"provider": "anthropic", "model": "claude-sonnet-4-5"},
-    "coding": {"provider": "openai", "model": "gpt-4o-mini"}
-  },
-  "agents": {
-    "agent_architect": {"provider": "anthropic", "model": "claude-opus-4-1"},
-    "agent_backend": {"provider": "openai", "model": "gpt-4o"},
-    "agent_code_review": {"provider": "groq", "model": "openai/gpt-oss-120b"}
+  "mcpServers": {
+    "jev-browser": {
+      "command": "npx",
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.4.0"],
+      "env": {
+        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
+        "JEV_BROWSER_MODE": "computer"
+      }
+    }
   }
 }
 ```
 
-Precedência: `agents` > `profiles` > `default` > variáveis legadas de
-provedor/perfil. Assim, o futuro frontend poderá salvar uma política de
-execução sem alterar o código dos agentes. Para trocar tudo de uma vez,
-defina apenas `ORQUESTRADOR_LLM_PROVIDER`, a chave correspondente e os
-modelos `ORQUESTRADOR_MODEL_*`.
-
-## 5. Executar o orquestrador
-
-Modo automático para CI/local:
-
-```bash
-python main.py --auto-aprovar --tipo new --prazo "2 semanas" \
-  "Criar um sistema de controle de tarefas"
-```
-
-Opções importantes:
-
-```bash
-python main.py --projeto-id meu-projeto --documentacao docs/requisitos.md pedido
-python main.py --no-cache --auto-aprovar pedido
-python main.py --resume --thread-id minha-thread
-python main.py --devops --auto-aprovar pedido
-```
-
-O resultado só é considerado entrega aprovada quando `compliance_status=approved`.
-No modo sem chave LLM, o fluxo pode terminar com artefato fallback rejeitado.
-
-## 6. Sandbox e gates D2
-
-Construa a imagem segura:
-
-```bash
-docker build -f docker/Dockerfile.sandbox -t orquestrador-sandbox:py312 .
-```
-
-Execute gates em container:
-
-```bash
-ORQUESTRADOR_SANDBOX_MODE=docker \
-ORQUESTRADOR_SANDBOX_IMAGE=orquestrador-sandbox:py312 \
-python -m pytest -q
-```
+O formato de interpolação de variáveis varia por harness. Injete a chave por
+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
+```
+
+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 --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`
+e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
+nome de variável declarado em `jev.credential_env`.
+
+Uma aplicação Node também pode importar `createJevBrowserServer` por
+`@diegosouzacdv/jev-browser-mcp/server` e conectar o servidor ao transporte MCP
+que ela já utiliza.
+
+O pacote é montado em uma pasta temporária isolada: o publicador usa o campo
+`files` do `package.json` para copiar somente o código Node, a configuração
+compartilhada e esta documentação, que também vira o `README.md` da raiz do
+pacote. Assim, o npm não inclui o README geral do orquestrador na página do MCP.
+Para gerar e conferir o pacote antes de publicar, execute
+`npm run pack:jev-browser-mcp`; para publicar uma versão já autenticada no npm, execute
+`npm run publish:jev-browser-mcp`. A instalação por npm é a recomendada; use a
+referência GitHub somente quando precisar experimentar uma revisão ainda não
+publicada.
+
+### Contrato do pacote
+
+O executável oferece `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
+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
+aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
+JavaScript enviado pelo harness, seletores livres nem coordenadas. Ele usa a
+biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
+Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
+`stderr` para não misturar com JSON-RPC.
+
+O modo `computer` grava cookies no perfil exclusivo configurado, e conteúdo da
+página pode conter instruções maliciosas. O Jev recebe a captura acessível com
+uma instrução para tratar esse conteúdo como dado não confiável; não inclua
+segredos no fluxo, no resultado esperado ou nas descrições dos planos.
+
+Para um fluxo conhecido, o LLM do harness procura o cenário e os critérios de
+aceitação no projeto e chama `jev_browser.run_browser_flow` com planos
+candidatos declarativos. O MCP abre uma única sessão do Playwright, navega para
+a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
+plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
+resultado esperado na tela.
+
+Cada plano pode usar:
+
+- `click`, `type`, `hover` e `select_option` com papel/nome acessível exatos;
+- `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
+  valor apareça nas evidências;
+- `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
+  `text_hidden`);
+- `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
+  `Enter`, `Escape` ou `Tab`;
+- `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`; `assert_text`
+  pode receber apenas `role` quando a região, como `alert`, não tem nome acessível;
+- `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
+  dropzone;
+- `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
+- `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
+  não repetem uma reação já no estado pedido e distinguem `Curtir` de
+  `Descurtir`.
+
+Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
+container acessível único, como uma linha ou card. `index` escolhe uma ocorrência
+zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
 
-O container usa rede desabilitada, filesystem read-only, usuário não-root,
-limites de CPU/memória/PIDs, timeout e ambiente sem credenciais. O contrato
-`config/frontend-validation.json` fixa a versão do TypeScript usada pelo
-validador e pelo `docker/Dockerfile.sandbox`; o workflow instala essa mesma versão
-antes do graph. ESLint e Playwright continuam pertencendo ao projeto gerado e
-só são executados quando sua configuração e dependências versionadas existem.
-O modo
-`subprocess` é apenas uma opção local de desenvolvimento.
-
-Os gates executam compilação Python, Ruff, mypy, pytest, TypeScript e EXPLAIN
-SQL quando o artefato e o ambiente suportam cada verificação.
-
-## 7. HITL HTTP
-
-`HITL_API_TOKEN` é um token interno criado pelo operador para proteger a API
-HTTP local. Ele não é fornecido pelo Google, não é `GEMINI_API_KEY`, não é uma
-credencial OAuth do Antigravity e não é um token do Gitea. Mantenha-o fora do
-repositório, prompts, argumentos de processo, logs e artefatos.
-
-Em Windows PowerShell, gere um token aleatório sem colar o valor literal no
-histórico. Esta forma funciona também no Windows PowerShell antigo; não troque
-por uma expressão com parênteses ou barras invertidas:
-
-~~~powershell
-$bytes = New-Object byte[] 32
-$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
-
-try {
-    $rng.GetBytes($bytes)
-}
-finally {
-    $rng.Dispose()
+```json
+{
+  "action": "click",
+  "role": "button",
+  "name": "Add to cart",
+  "within": {"role": "group", "name": "Sauce Labs Backpack"}
 }
-
-$env:HITL_API_TOKEN = [Convert]::ToBase64String($bytes)
-Remove-Variable bytes, rng
-~~~
-
-A variável vale para a janela/processo atual. Inicie a API na mesma janela,
-preferencialmente a partir do checkout:
-
-~~~powershell
-Set-Location C:\orquestrador
-& 'C:\orquestrador\.venv\Scripts\python.exe' -m uvicorn server.app:app --host 127.0.0.1 --port 8000
-~~~
-
-Se a API rodar como serviço, carregue o mesmo token pelo cofre de segredos do
-serviço; não coloque o valor diretamente no comando, no arquivo versionado ou
-em `setx` compartilhado. Para chamar a API em outro terminal, forneça o mesmo
-valor ao ambiente desse cliente e use apenas o cabeçalho Bearer:
-
-~~~powershell
-$headers = @{ Authorization = "Bearer $env:HITL_API_TOKEN" }
-~~~
-
-Não execute `$env:HITL_API_TOKEN` sozinho, pois isso imprime o segredo. Ao
-terminar a sessão, limpe a variável se ela não for mais necessária:
-
-~~~powershell
-Remove-Item Env:HITL_API_TOKEN -ErrorAction SilentlyContinue
-~~~
-
-Verifique saúde:
-
-```bash
-curl http://127.0.0.1:8000/health
-```
-
-Consulte ou retome uma thread usando `Authorization: Bearer ...`:
-
-```bash
-curl -H "Authorization: Bearer $HITL_API_TOKEN" \
-  http://127.0.0.1:8000/threads/minha-thread/state
-
-curl -X POST -H "Authorization: Bearer $HITL_API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"resume_data":{"aprovado":true}}' \
-  http://127.0.0.1:8000/threads/minha-thread/resume
-```
-
-### 7.1. Antigravity OAuth: state dir, host e container
-
-`ORQUESTRADOR_ANTIGRAVITY_STATE_DIR` é o diretório privado onde a API mantém o
-estado protegido do login Antigravity. Ele não é uma API key, não é o
-`client_id`, não é o `client_secret` e não deve apontar para o checkout. O
-diretório pode conter o refresh token; por isso, copiar seus arquivos para
-prompt, log, issue, artefato ou workspace é uma violação da fronteira de
-credenciais.
-
-Há duas visões do mesmo diretório no ambiente local:
-
-| Onde | Caminho | Uso |
-|---|---|---|
-| API no host Windows | `C:\orquestrador-secrets\antigravity-state` | persistência do login e do refresh |
-| job Linux do runner Docker | `/var/lib/orquestrador/antigravity-state` | caminho usado pelo workflow |
-| secret do Gitea | `/var/lib/orquestrador/antigravity-state` | valor que o job recebe; não use o caminho Windows |
-
-O secret do Gitea configura somente o processo do job. Ele não configura uma
-API que já esteja rodando no host. A API precisa receber o caminho Windows em
-seu próprio ambiente; o runner precisa montar o mesmo diretório no caminho
-Linux antes de executar o workflow.
-
-O diretório deve ser criado e protegido pelo administrador do host, fora de
-`C:\orquestrador`, com ACL/DACL privada e sem junction, symlink ou reparse
-point. Para o job Linux, o runner autorizado deve montar esse mesmo diretório
-como `/var/lib/orquestrador/antigravity-state`; o valor salvo no Gitea é sempre
-o caminho Linux, nunca o caminho Windows. Não liste nem copie os arquivos de
-estado OAuth.
-
-#### 1. Cadastrar o caminho no Gitea
-
-Em `admin/projeto-global`, abra **Settings → Actions → Secrets** e cadastre
-somente o par abaixo:
-
-~~~text
-Nome:  ORQUESTRADOR_ANTIGRAVITY_STATE_DIR
-Valor: /var/lib/orquestrador/antigravity-state
-~~~
-
-Não coloque o caminho Windows nesse secret: o job é Linux dentro do Docker.
-Não tente ler o valor de volta pela interface e não registre secrets em
-artefatos. Os secrets `ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_ID` e
-`ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET` continuam necessários nos
-passos Kernel/Claude: a conta persistida contém um `refreshToken`, e o proxy
-precisa desses dois valores para convertê-lo em um access token antes da probe.
-Eles não são necessários para SDK ou Pi e não devem ser injetados nesses jobs.
-
-**Não crie um cliente OAuth próprio para esta rota.** Esta instrução existiu
-aqui até 2026-09-14 e estava errada; ela custou três runs e duas sessões de
-diagnóstico, e o sintoma não apontava para ela.
-
-Um cliente criado no seu projeto do Google Cloud **autentica com sucesso** — o
-login abre, o consentimento passa, o `refresh_token` é emitido e renovado — e
-mesmo assim toda chamada morre em `UPSTREAM_HTTP_403`. O Google emite token
-para qualquer cliente válido; o backend do Antigravity só aceita token cunhado
-pelo cliente em que ele confia. A falha aparece apenas na chamada real, muito
-depois do login, e se parece com um problema de conta ou de modelo.
-
-O par que a rota exige é o que o snapshot upstream traz embutido, visível nas
-linhas removidas de `antigravity_proxy/patches/003-account-boundary.patch`. O
-patch o tirou do **default de runtime** para que uma cópia do sidecar não fosse
-fonte de credencial; o valor continua no repositório, dentro do patch, e é dali
-que ele deve ser lido para preencher as duas variáveis:
-
-~~~text
-ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_ID
-ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET
-~~~
-
-Isso vale para o ambiente da API **e** para os secrets do Gitea: os dois lados
-precisam do mesmo cliente, porque o refresh token fica preso ao cliente que o
-emitiu. Trocar o cliente invalida a conta persistida — é obrigatório
-`logout` seguido de `auto --force-login` depois de mudar esses valores.
-
-Como confirmar em segundos, sem gastar uma corrida da matriz:
-
-~~~powershell
-Set-Location C:\orquestrador
-$env:PYTHONPATH = "."
-& '.\.venv\Scripts\python.exe' scripts\list_antigravity_models.py
-~~~
-
-Com o cliente certo, isso lista os modelos que a conta anuncia — em 2026-09-14,
-onze, incluindo `gemini-3.8-flash-tiered`, que é o default do workflow. Com o
-cliente errado, responde `500 ... UPSTREAM_HTTP_403`, e nenhuma troca de conta
-ou de modelo muda esse resultado.
-
-#### 2. Login automático
-
-Depois de configurar no ambiente da API `ORQUESTRADOR_ANTIGRAVITY_STATE_DIR`,
-`ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_ID` e
-`ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET`, execute somente o helper abaixo
-no host autorizado:
-
-~~~powershell
-Set-Location C:\orquestrador
-& 'C:\orquestrador\.venv\Scripts\python.exe' scripts\antigravity_auth.py auto
-~~~
-
-O helper valida o ambiente, abre o navegador, recebe o callback loopback sem
-clipboard ou impressão de código e executa `refresh`. Se já houver uma conta,
-ele não abre novo login. O resultado esperado é `ready`; a API grava o estado
-protegido somente no state dir. Não execute outro fluxo OAuth em paralelo.
-
-O valor produzido depois do login é estado protegido da conta, não deve ser
-usado como `ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET` nem copiado para
-prompt, log, issue ou artefato.
-
-Somente depois de `status` pronto, refresh aprovado, DACL/reparse verificados e
-mount confirmado deve ser disparada a matriz real. O procedimento detalhado de
-AGS-004/ACP está em
-[`docs/ags004-acp-live-runbook.md`](docs/ags004-acp-live-runbook.md).
-
-## 8. Testes locais
-
-```bash
-pytest -q
-ruff check .
-mypy agents src server main.py scripts pi_harness mcp_servers
-python scripts/smoke/mcp_tools_binding.py
-python scripts/smoke/full_orchestrator_e2e.py
-```
-
-Smoke real Groq, com limite baixo de tokens:
-
-```bash
-GROQ_API_KEY="$GROQ_API_KEY" ORQUESTRADOR_SMOKE_MAX_TOKENS=512 \
-  ORQUESTRADOR_SMOKE_RUN_GRAPH=false \
-  python scripts/smoke_groq.py
-```
-
-O smoke não imprime a chave. O prompt caching é automático na Groq; o teste
-registra `cached_tokens`, mas um cache miss não é tratado como falha porque a
-Groq não garante hit em toda chamada. O workflow manual aprovado percorre
-Compound, Compound Mini, Prompt Guard, GPT-OSS 20B, GPT-OSS 120B, Qwen 27B e
-Safeguard 20B; todas as chamadas retornaram `OK`. O grafo fica desativado nesse
-workflow para separar smoke de modelos de gates HITL/Compliance.
-
-## 9. Batch API
-
-Ative somente para workloads assíncronos:
-
-```dotenv
-ORQUESTRADOR_BATCH_ENABLED=true
-ORQUESTRADOR_USE_BATCH=true
-```
-
-O adapter usa JSONL e a API Groq Batch. A janela é assíncrona; acompanhe o
-`batch_id` e não coloque prompts completos no `GraphState`.
-
-O Batch depende de habilitação do plano Groq. Se a API responder
-`403 not_available_for_plan`, a credencial está válida, mas a conta ainda não
-possui esse recurso; o adapter registra a situação e usa uma simulação offline
-correlacionável para testes locais. A execução real exige habilitar o Batch no
-plano Groq e usar um modelo elegível.
-
-Documentação: [Groq Batch API](https://console.groq.com/docs/batch) e
-[referência de batches](https://console.groq.com/docs/api-reference).
-
-## 10. Git remoto e GitHub Checks
-
-Em GitHub Actions, configure secrets/variáveis:
-
-```dotenv
-GITHUB_TOKEN=provided-by-github-actions
-GITHUB_REPOSITORY=owner/repository
-GITHUB_SHA=commit-sha
-ORQUESTRADOR_GIT_REMOTE=https://github.com/owner/repository.git
-```
-
-O workflow cria branch por thread, publica commit, abre PR draft e publica
-GitHub Check. Sem credencial explícita, o sistema mantém apenas branch/commit
-local e não inventa URL de PR.
-
-## 11. CI
-
-O workflow `quality.yml` é o portão determinístico: instalação, Ruff, mypy,
-pytest, os smokes e o build do sandbox. Ele é **dividido em dois jobs** —
-`quality` roda `-m 'not slow and not quarantine'` e `slow-e2e` roda o
-complemento —, e os dois somados são `pytest -q`.
-
-**Quando ele roda está nos próprios arquivos, e as duas superfícies diferem de
-propósito.** No GitHub, `pull_request` e disparo manual; no Gitea, disparo
-manual apenas, porque enfileirar um check obrigatório contra um runner local
-que nem sempre está ligado seria pior que não ter. Esta frase dizia "em todo
-push/PR" até 2026-09-15, o que estava errado nas duas — e é o tipo de cópia em
-prosa que `tests/guards/test_governance_document_truth_guard.py` passou a
-conferir contra o YAML.
-
-Ele **não bloqueia merge** em nenhuma das duas: o `master` do Gitea não tem
-regra de proteção, e a do GitHub é recurso pago em repositório privado. O que
-segura a qualidade antes do push é a regra de trabalho do `AGENTS.md`, aplicada
-pelo hook de pre-commit; o workflow é a repetição disso num Linux, que é o
-ambiente que a máquina do operador não tem.
-
-O workflow `groq-smoke.yml` é manual (`workflow_dispatch`) e exige o secret
-`GROQ_API_KEY` em um GitHub Environment protegido. Ele não deve ser executado
-em PRs de forks.
-
-Para executar o E2E do grafo com LLM real, use o workflow manual
-`.github/workflows/groq-graph-e2e.yml`. Ele usa o mesmo Environment protegido,
-executa as trilhas `new`, `feature` e `fix` com Groq e mantém os limites do tier
-on-demand. O workflow define `ORQUESTRADOR_REQUIRE_REAL_LLM=true`, portanto
-fallback offline faz o job falhar. A execução pode terminar com
-`compliance_status=rejected` por
-pendências legítimas; o objetivo desse workflow é comprovar o caminho real do
-grafo, não forçar aprovação de uma entrega sem evidência.
-
-No GitHub: **Actions → groq-graph-e2e → Run workflow → master**. Se o
-Environment exigir aprovação, aprove o job antes que os secrets sejam
-liberados.
-
-Permissões mínimas recomendadas:
-
-```yaml
-permissions:
-  contents: read
-  checks: write
-```
-
-Para PR remoto, conceda `contents: write` e `pull-requests: write` apenas no
-workflow manual protegido.
-
-## 12. Observabilidade
-
-Para exportar spans via OTLP:
-
-```dotenv
-OTEL_SERVICE_NAME=orquestrador
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-```
-
-Sem endpoint, o sistema registra apenas eventos técnicos locais. Prompts,
-código, tokens de autenticação e conteúdo de documentação não entram nos
-traces.
-
-## 13. Artefatos e D5
-
-O código gerado é salvo em `workspace/<thread-id>/`; o estado carrega hashes e
-referências do manifesto. Checkpoints legados ainda podem ser lidos durante a
-migração, mas novas execuções não precisam persistir blobs completos quando
-`ORQUESTRADOR_LEGACY_CODE_STATE=false`.
-
-## 14. Documentação do projeto
-
-- [Trilha de sessões e status](docs/plano-agentic-skills-status.md) (append-only, com índice em `docs/plano-status.json`)
-- [Estrutura de pastas e nomenclatura](docs/planos/auditoria/estrutura-pastas-e-nomenclatura.md)
-- [Fluxo de agentes, documentação e execução](docs/fluxo-agentes-documentacao-e-execucao.md)
-- [Guia de atualização dos validadores](docs/planos/auditoria/guia-atualizacao-versoes-validadores.md)
-
-## 15. Time travel, retenção e governança
-
-Forks são não destrutivos: o checkpoint pai permanece na thread original e o
-fork recebe novo `thread_id`, workspace independente e branch local.
-
-```bash
-python scripts/time_travel.py list --thread-id <id>
-python scripts/time_travel.py fork --thread-id <id> --checkpoint-id <cp> \
-  --field prazo_entrega --value "2026-09-15"
-python scripts/time_travel.py retention --days 30       # dry-run
-python scripts/time_travel.py retention --days 30 --purge --legal-hold <id>
 ```
 
-Objetos D5 são endereçados por SHA-256 e o modo legado permanece opt-in:
-`ORQUESTRADOR_LEGACY_CODE_STATE=true`.
-
-## 16. Web escopada, qualidade e Batch
-
-Configure `ORQUESTRADOR_WEB_ALLOWLIST` antes de habilitar o MCP web; sem
-allowlist, HTTPS, resolução pública e aprovação humana, o conteúdo é
-bloqueado. Para quality gates completos, use `docker/Dockerfile.quality`, que instala
-Playwright/Lighthouse e grava `data/quality-evidence.json`.
-
-Submissão/consulta Batch:
-
-```bash
-python scripts/batch_cli.py submit --prompt "health" --model deepseek/deepseek-v4-flash-0731
-python scripts/batch_cli.py status <batch-id>
-```
-
-O workflow `.github/workflows/batch-submit.yml` usa somente modelos Groq Batch
-elegíveis e um GitHub Environment protegido.
-
-## 17. OpenRouter opcional (multi-provedor e multimodal)
-
-Groq continua sendo o padrão. Para habilitar OpenRouter, configure a chave
-somente no ambiente de execução (nunca em `GraphState`, registry ou logs):
-
-```dotenv
-ORQUESTRADOR_LLM_PROVIDER=openrouter
-OPENROUTER_API_KEY=...
-OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
-# opcional: OPENROUTER_HTTP_REFERER=https://seu-dominio
-# opcional: OPENROUTER_TITLE=Orquestrador
-# opcional: ORQUESTRADOR_OPENROUTER_TIMEOUT_SECONDS=90
-# compatibilidade legada, somente com ORQUESTRADOR_POLICY_LEGACY_OVERRIDES=true
-# ORQUESTRADOR_OPENROUTER_REASONING_EFFORT=low
-# ORQUESTRADOR_OPENROUTER_STRUCTURED_METHOD=json_schema
-# ORQUESTRADOR_OPENROUTER_REQUIRE_PARAMETERS=true
-# ORQUESTRADOR_OPENROUTER_STRUCTURED_RETRIES=1
-# opcional: ORQUESTRADOR_SMOKE_MAX_COMPLETION_TOKENS=16
-# opcional: ORQUESTRADOR_LLM_LOG_PREVIEW_CHARS=120 (0 desabilita previews)
-```
-
-Para modelos marcados no catálogo local como compatíveis, o padrão é
-`json_schema` com `strict=true`. No E2E canônico,
-`ORQUESTRADOR_OPENROUTER_REQUIRE_PARAMETERS=true` também restringe o
-roteamento a endpoints que aceitem os parâmetros enviados. Use `json_mode`
-somente como override para um modelo/endpoint sem structured outputs nativos.
-
-As chamadas diretas de OpenRouter (catálogo, mídia, TTS/STT, vídeo e smoke)
-usam o pacote oficial `openrouter==1.1.81`, com respostas tipadas e clientes
-síncrono/assíncrono. O LangGraph permanece sobre LangChain para preservar
-`Runnable`, saída estruturada, callbacks, ferramentas e o roteamento entre
-Groq, OpenRouter e demais provedores. O Batch é a única exceção: nessa versão
-do SDK o endpoint `/beta/batches` ainda não está exposto, portanto fica em um
-transporte HTTP privado e isolado.
-
-O SDK não realiza novas tentativas por conta própria. Backoff, circuit breaker,
-limite de quatro tentativas e fallback continuam centralizados no orquestrador.
-O adapter aceita `max_tokens` apenas por compatibilidade e o converte para
-`max_completion_tokens`; código novo deve usar o segundo nome.
-
-Cada chamada OpenRouter também emite logs reduzidos `[OPENROUTER] REQUEST`,
-`RESPONSE` e `ERROR`, com agente, modelo, tentativa, duração, hashes,
-tamanhos, tokens/cache, generation ID e erro sanitizado. Prompts e respostas
-completos não são gravados; o preview é limitado por
-`ORQUESTRADOR_LLM_LOG_PREVIEW_CHARS` (defina `0` em ambientes sensíveis).
-
-Os limites físicos de cada modelo permanecem em `src/llm/llm_model_config.py`. Já
-os orçamentos operacionais por agente ficam em um único JSON:
-
-```dotenv
-# Somente para migração de ambientes antigos; a fonte normal é
-# config/agent-policy.json e o mapa é ignorado sem opt-in explícito.
-ORQUESTRADOR_POLICY_LEGACY_OVERRIDES=true
-ORQUESTRADOR_AGENT_RUNTIME_JSON={"agent_clean_code":{"max_completion_tokens":8192,"reasoning_effort":"minimal","timeout_seconds":180,"structured_retries":1},"agent_code_review":{"max_completion_tokens":8192,"reasoning_effort":"minimal","timeout_seconds":180,"structured_retries":0}}
-ORQUESTRADOR_REVIEW_MAX_INPUT_CHARS=30000
-ORQUESTRADOR_RED_TEAM_MAX_INPUT_CHARS=30000
-```
-
-Falhas do Planejador ou de Requisitos são bloqueantes. Primeiro,
-`structured_retries` repete apenas a chamada do agente. Se todas as tentativas
-falharem, o portão `critical_failure_gate` permite repetir somente esse nó a
-partir do checkpoint ou encerrar. `ORQUESTRADOR_CRITICAL_NODE_RETRIES` limita
-essas repetições manuais (padrão: `1`). Em CI, `auto_aprovar` escolhe encerrar;
-documentação ausente nunca é transformada em fallback aprovado.
-
-Planejador e Consultor persistem seus resultados antes dos nós de aprovação.
-Assim, retomar um HITL não repete a chamada LLM. Clean Code, Code Review, Red
-Team e Compliance usam contratos compactos; fallback de um quality gate é
-registrado em `validacoes_fallback`, reprova o Compliance e faz o E2E real
-falhar explicitamente.
-
-O dispatcher é orientado por fases: o roadmap normalizado atribui os agentes
-de implementação e o grafo executa `agent_dba` (persistência/contrato),
-`agent_backend` (API) e `agent_frontend` (interface) em etapas separadas,
-com fan-in e aprovação HITL entre elas. Code Review e Red Team só começam após
-a última fase; threads antigas sem a atribuição `agentes` mantêm o fan-out
-legado para compatibilidade.
-
-O workflow `openrouter-graph-e2e.yml` define
-`ORQUESTRADOR_ITERATIVE_REPAIR=false`: ele valida uma rodada completa e
-encaminha achados ao Compliance sem repetir três ciclos de geração, que
-custariam três vezes mais para dizer a mesma coisa. O padrão está em
-`defaults.iterative_repair` e a variável o sobrepõe para uma corrida.
-
-Antes isso era `ORQUESTRADOR_E2E_NO_REPAIR`, lida com literal dentro de
-`src/state/graph.py`. É deliberadamente independente de
-`ORQUESTRADOR_RUN_MODE`: amarrar as duas faria quem quer uma corrida mais
-barata pinar o provedor sem pedir, e tornaria impossível medir o próprio laço
-de reparação.
-
-Rotas podem ser escolhidas por agente/perfil/thread em
-`ORQUESTRADOR_LLM_ROUTING_JSON`; `fallback_models` usa a cascata nativa do
-OpenRouter e `external_routes` define a cascata entre provedores. O limite é
-de quatro tentativas e erros de autenticação, payload, orçamento e segurança
-não fazem fallback.
-
-A precedência é `thread/agente > thread/perfil > projeto/agente >
-projeto/perfil > defaults do projeto > ambiente`. O registry persiste apenas
-JSON de política; chaves permanecem exclusivamente em variáveis de ambiente.
-
-### Claude Code como harness opcional
-
-É possível adicionar o Claude Code/Anthropic Agent SDK como backend de
-execução dos agentes de código, mantendo a OpenRouter como gateway. A
-arquitetura recomendada é preservar o LangGraph como plano de controle
-(roteamento, HITL, orçamento, checkpoints, Compliance e D5) e delegar apenas
-uma tarefa de implementação isolada ao harness Claude Code, com workspace e
-tools permitidas explicitamente.
-
-O processo filho receberá as credenciais somente em memória:
-
-```dotenv
-ANTHROPIC_BASE_URL=https://openrouter.ai/api
-ANTHROPIC_AUTH_TOKEN=<valor de OPENROUTER_API_KEY injetado no processo>
-ANTHROPIC_API_KEY=
-```
-
-O executor está disponível por política explícita. O workflow canônico usa
-`deepseek/deepseek-v4-flash-0731` através do protocolo Anthropic Skin. A
-documentação da OpenRouter garante formalmente o Claude Code apenas com
-modelos Anthropic first-party; DeepSeek, MiniMax e Kimi são portanto uma rota
-experimental do projeto e precisam de E2E próprio. A política de produção é:
-
 ```json
-{"agents":{"agent_backend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"]},"agent_frontend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"]}}}
-```
-
-MiniMax M3 custa US$ 0,30/M de input e US$ 1,20/M de output; Kimi K2.7
-Code custa US$ 0,67/M de input e US$ 3,40/M de output (valores de catálogo,
-o custo efetivo vem do usage). Esses fallbacks só são habilitados quando
-`ORQUESTRADOR_EXECUTOR_FALLBACK_MODE=production`; workflows usam
-`disabled`, DeepSeek exclusivamente e no máximo três tentativas. Erros de
-payload, autenticação, orçamento, segurança e ownership nunca fazem fallback.
-
-Documentação oficial: [Quickstart](https://openrouter.ai/docs/quickstart),
-[Client SDKs](https://openrouter.ai/docs/client-sdks/overview),
-[SDK Python](https://openrouter.ai/docs/client-sdks/python/overview),
-[model fallbacks](https://openrouter.ai/docs/guides/routing/model-fallbacks),
-[multimodal](https://openrouter.ai/docs/guides/overview/multimodal/overview),
-[Batch](https://openrouter.ai/docs/batch-quickstart),
-[prompt caching](https://openrouter.ai/docs/guides/best-practices/prompt-caching#caching-in-the-batch-api)
-e [MCP administrativo](https://openrouter.ai/docs/guides/overview/mcp-server).
-Para o harness, consulte [Claude Code com OpenRouter](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration)
-e [Anthropic Agent SDK com OpenRouter](https://openrouter.ai/docs/guides/community/anthropic-agent-sdk).
-
-Workflows manuais separados:
-
-```text
-.github/workflows/openrouter-smoke.yml
-.github/workflows/openrouter-graph-e2e.yml
-.github/workflows/openrouter-batch-submit.yml
-.github/workflows/openrouter-batch-status.yml
+{"action":"click","role":"button","name":"Add to cart","index":0}
 ```
 
-Configuração no GitHub:
-
-1. Crie uma chave em [OpenRouter Keys](https://openrouter.ai/settings/keys).
-2. Em **Settings → Environments**, crie exatamente `openrouter-smoke`,
-   `openrouter-graph-e2e` e `openrouter-batch`.
-3. Em cada Environment, adicione o secret **`OPENROUTER_API_KEY`**. Não use
-   Repository variable nem coloque a chave no YAML. Se o Environment exigir
-   aprovação, aprove a implantação antes da execução.
-4. Opcionalmente adicione as variables `OPENROUTER_HTTP_REFERER` e
-   `OPENROUTER_TITLE` para identificação da aplicação.
-5. Em **Actions → workflow → Run workflow**, execute primeiro o smoke. Depois
-   use o graph E2E. Batch exige quota/plano habilitado; submeta o lote e copie
-   o `batch_id` impresso para o workflow de status.
-
-Pela CLI do GitHub:
-
-```bash
-gh secret set OPENROUTER_API_KEY --env openrouter-smoke --repo OWNER/REPO
-gh secret set OPENROUTER_API_KEY --env openrouter-graph-e2e --repo OWNER/REPO
-gh secret set OPENROUTER_API_KEY --env openrouter-batch --repo OWNER/REPO
-  gh workflow run openrouter-smoke.yml --ref master -f model=deepseek/deepseek-v4-flash-0731
-gh run watch --exit-status
-```
-
-O grafo E2E executa uma trilha por vez por padrão, reduzindo rate limit e
-duração. Escolha a trilha assim:
-
-A trilha `new` do workflow usa deliberadamente o pedido fixo e pequeno
-`CRUD simples de produtos (código identificador e nome)`, para validar o
-fluxo do grafo e o Compliance sem transformar o teste em uma geração de
-produto grande. Ele pode ser sobrescrito apenas por `ORQUESTRADOR_E2E_CLIENT_INPUT`
-em execuções controladas.
+### Captura de downloads
 
-Quando a trilha `new` não recebe `projeto_id` nem `mcp_roots`, o Arquiteto usa
-um contexto **greenfield** determinístico e não indexa o código-fonte do
-próprio orquestrador. Para evoluir um código existente desde o início, registre
-o projeto/base ou forneça um root MCP explícito; nesse caso a análise detalhada
-do repositório continua habilitada.
-
-```bash
-gh workflow run openrouter-graph-e2e.yml --ref master \
-  -f model=deepseek/deepseek-v4-flash-0731 -f tracks=new
-# Para executar todas: -f tracks=new,feature,fix
-```
-
-O primeiro passo de cada workflow executa `test -n "$OPENROUTER_API_KEY"`; se
-falhar, o secret está no Environment errado, o Environment não foi aprovado ou
-o nome está diferente. A API usa `https://openrouter.ai/api/v1`, conforme o
-[Quickstart oficial](https://openrouter.ai/docs/quickstart), e os modelos
-devem ser IDs publicados no [catálogo](https://openrouter.ai/models).
-Para contas com crédito limitado, reduza opcionalmente
-`ORQUESTRADOR_OPENROUTER_MAX_COMPLETION_TOKENS`; quando ausente, cada modelo
-usa o limite registrado em `src/llm/llm_model_config.py`. Os workflows OpenRouter
-usam uma cascata paga de DeepSeek V4 Flash e Solar Pro4, evitando as cotas
-instáveis dos endpoints gratuitos.
-
-O smoke registra modelo efetivo, generation ID, tokens, cache, custo e BYOK.
-O smoke usa `ORQUESTRADOR_SMOKE_MAX_COMPLETION_TOKENS` (16 por padrão, apenas
-para manter a chamada curta); `ORQUESTRADOR_SMOKE_MAX_TOKENS` continua aceito
-temporariamente. Ele não limita as execuções do grafo. No Batch, `max_tokens`
-é opcional por item: se omitido, o adapter não injeta um teto artificial do
-OpenRouter; informe-o somente quando quiser limitar aquele item.
-Batch OpenRouter aceita apenas texto, um modelo por lote e janela de 24 horas;
-simulação offline só é permitida com
-`ORQUESTRADOR_BATCH_OFFLINE_SIMULATION=true`.
-
-Uploads multimodais são armazenados localmente por SHA-256 em D5. Imagem,
-PDF, áudio e vídeo são convertidos para as partes da API apenas durante a
-requisição; base64 e binários não entram em checkpoints. As APIs prontas para
-frontend são `/llm/*`, `/integrations/openrouter/mcp/*`, `/media/*`,
-`/batches` e `POST /threads`. Para OAuth administrativo por usuário configure
-`OIDC_ISSUER_URL`, `OIDC_AUDIENCE`, `OIDC_JWKS_URL` e
-`ORQUESTRADOR_CREDENTIAL_ENCRYPTION_KEY`.
-
-## Planejamento especializado e executores agentic
-
-O grafo separa planejamento e execução: requisitos, arquitetura e Clean Code
-alimentam os planos DBA, Backend e Frontend; uma validação determinística
-confere cobertura/propriedade; uma única aprovação HITL libera a ordem DBA →
-Backend → Frontend. Backend não pode possuir migrations e Frontend não pode
-inventar endpoint, SQL ou regra de negócio. Migrations que falham no banco
-efêmero não entram no manifesto D5.
-
-O executor padrão é o **`kernel`**, declarado em `config/agent-policy.json`
-(`defaults.executor`). Os executores selecionáveis são `kernel`, `claude_code`,
-`pi` e `antigravity_sdk` (`defaults.selectable.executor`); `legacy` (o adapter
-LangChain) e `deepseek_harness` permanecem apenas como compatibilidade, em
-`COMPATIBILITY_EXECUTOR_NAMES` de `src/execution/executors.py`, e não são o
-padrão de nada. Claude Code pode ser ativado por política para Backend/Frontend
-e usa o SDK `claude-agent-sdk` com OpenRouter/Anthropic Skin. DeepSeek Harness é
-somente shadow/piloto em Linux, workspace isolado e sem aplicar artefatos ao
-workspace canônico. Se um executor explicitamente solicitado não estiver
-disponível, a execução é bloqueada; não há fallback silencioso.
-
-Cada executor externo trabalha numa cópia descartável do workspace. Apenas
-arquivos textuais permitidos pela task card, pertencentes ao agente e dentro do
-orçamento são promovidos ao armazenamento D5. Remoções, binários, paths fora do
-plano e violações de propriedade bloqueiam a fase. Claude Code não recebe Bash,
-WebFetch, WebSearch ou NotebookEdit; os limites de contexto/conclusão do
-DeepSeek vêm de `src/llm/llm_model_config.py`, e não do arquivo Cordis.
-
-O executor `pi` roda o loop do harness Pi (`@earendil-works/pi-agent-core` +
-`pi-ai`) num sidecar Node privado em `pi_harness/worker/`. Ele vem **desligado** em
-`config/agent-policy.json` (`pi_harness.enabled=false`) e, quando ligado,
-atende só os owners listados em `pi_harness.agents`. O sidecar não recebe
-credencial, Git, shell nem o workspace canônico: cada inferência volta para a
-fachada central em `src/llm/llm_provider.py` e cada ferramenta é revalidada contra
-o WorkPacket em `pi_harness/tools.py`. Instale o worker com
-`npm ci --ignore-scripts --prefix pi_harness/worker` e verifique o runtime com
-`python -m pi_harness.bridge`. Detalhes de operação em
-[`docs/planos/auditoria/operacao-pi-harness.md`](docs/planos/auditoria/operacao-pi-harness.md).
-
-Instale os SDKs opcionais em Linux/Docker com
-`pip install -r requirements-agentic.txt`; a instalação padrão não os exige.
-As versões testadas são `claude-agent-sdk==0.2.128` e
-`deepseek-harness-sdk==0.1.1rc2`. O DeepSeek Harness não possui wheel do runtime
-para Windows e, por isso, seu piloto roda apenas em Linux.
-
-Exemplo de política (sem credenciais; fallbacks somente em produção):
+Marque o clique que deve iniciar um download com `expect_download: true`. O
+Playwright começa a aguardar o evento antes do clique; após a transferência
+terminar, o MCP verifica o tamanho, sanitiza o nome sugerido e copia o arquivo
+para `JEV_BROWSER_ARTIFACT_DIR` (ou para o diretório de artefatos configurado).
+O resultado inclui a lista `downloaded_files`, com nome, caminho local e bytes;
+cada passo também contém o arquivo capturado. Os limites contam arquivos e bytes
+por fluxo. A checagem de tamanho acontece depois da transferência do navegador,
+antes de copiar para a pasta de artefatos.
 
 ```json
-{"default":{"executor":"kernel"},"fallback_mode":"disabled","agents":{"agent_backend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"],"shadow_executor":"pi"},"agent_frontend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"],"shadow_executor":"pi"},"agent_dba":{"executor":"kernel"}}}
+{"action":"click","role":"button","name":"Export report","expect_download":true}
 ```
 
-MCPs são registrados por especialidade: Context7 (`resolve-library-id` e
-`query-docs`) para planejamento/desenvolvimento, 21st somente para Frontend e
-PostgreSQL somente leitura para o DBA. Configure `CONTEXT7_API_KEY`,
-`TWENTY_FIRST_API_KEY` e `MCP_POSTGRES_DSN` apenas no secret manager; o estado
-guarda somente hashes de evidência e capacidades liberadas.
-
-O cliente MCP aplica a allowlist antes de cada chamada, protege conteúdo
-externo contra prompt injection e limita o texto retornado. No PostgreSQL, o
-modelo não recebe a ferramenta `connect` nem o DSN: o orquestrador conecta com
-um usuário read-only, entrega somente schema/query/EXPLAIN e desconecta. A
-validação de migrations usa separadamente `MCP_POSTGRES_VALIDATION_DSN`, que é
-aceito apenas para hosts allowlisted e bancos efêmeros. Para inspecionar a
-conectividade real use `GET /mcp/capabilities?probe=true`.
+`jev_browser_mcp.browser.max_download_files`, `max_download_file_bytes`,
+`max_download_total_bytes` e `max_download_timeout_seconds` definem os limites.
+O diretório de artefatos deve ser local e protegido: arquivos baixados podem
+conter dados da aplicação.
 
-Claude Code recebe proxies MCP locais, não os servidores remotos brutos. Esses
-proxies publicam exclusivamente a allowlist read-only e reaplicam sanitização e
-Prompt Guard em cada resultado. Portanto, ferramentas novas ou mutantes que o
-21st venha a publicar não ficam automaticamente acessíveis ao executor.
+### Auditoria automatizada de acessibilidade
 
-### MCP de navegador com Jev e Playwright
+Use `audit_accessibility` depois de colocar a página no estado que deseja
+verificar:
 
-O pacote independente `@diegosouzacdv/jev-browser-mcp` conecta qualquer harness
-compatível com MCP por `stdio` ao Jev e ao Playwright. Requer Node.js 22 ou mais
-recente. Instale o navegador do Playwright uma vez para execuções no modo
-`harness`:
+```json
+{"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.
+
+Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
+corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
+conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
+configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
+próximos quando o snapshot os encontrar. O plano não aceita JavaScript enviado
+pelo harness, coordenadas ou seletores livres.
+
+Os aliases `value` → `text` em `type`/`wait_for_text` e `value` → `expected` em
+asserções são aceitos. `comment` também é aceito em planos e passos, mas é
+ignorado e não é enviado ao Jev. Campos fora do contrato continuam sendo
+recusados.
+
+### Upload de arquivos
+
+Defina `JEV_BROWSER_UPLOAD_ROOT` como uma pasta absoluta que contenha os arquivos
+de fixture. Cada caminho passado ao fluxo também precisa ser absoluto; o MCP
+resolve links simbólicos e recusa qualquer arquivo fora dessa raiz. Só aceita
+arquivos regulares, até 5 arquivos por passo, 10 MiB por arquivo e 25 MiB no
+total do passo, conforme `jev_browser_mcp.browser` em `config/ui-testing.json`.
+Os bytes são lidos e validados no processo local antes de serem entregues ao
+Playwright. O MCP não envia esses bytes ao Jev nem os inclui diretamente na
+resposta; texto que o próprio site exibir na interface ainda pode aparecer no
+snapshot devolvido ao harness.
 
-```sh
-npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
+```json
+{"action":"upload_file","target":"input","label":"Nota fiscal","file_path":"/fixtures/nota.pdf"}
 ```
 
-Registre o servidor MCP no formato aceito pelo seu harness. Exemplo de
-configuração comum:
+Para uma área de arrastar, use o papel e o nome acessível da dropzone. Para um
+botão que abre a janela nativa, use `target: "button"`; sem `target`, a presença
+de `label` seleciona o input e `role`/`name` seleciona esse botão.
 
 ```json
-{
-  "mcpServers": {
-    "jev-browser": {
-      "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp"],
-      "env": {
-        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
-        "JEV_BROWSER_MODE": "harness"
-      }
-    }
-  }
-}
+{"action":"upload_file","target":"dropzone","role":"region","name":"Anexos","file_paths":["/fixtures/a.pdf","/fixtures/b.png"]}
 ```
 
-Configure `OPENROUTER_API_KEY` no secret manager ou no ambiente do processo
-que inicia o harness. Não coloque a chave no JSON. O endpoint e o modelo
-Decisions têm valores padrão no pacote; `JEV_PROVIDER_URL` e `JEV_MODEL` podem
-substituí-los.
-
-Escolha o navegador por variáveis de ambiente:
+Se `JEV_BROWSER_UPLOAD_ROOT` não estiver definido, a ação recusa a execução. O
+limite evita que um plano transforme o MCP em leitor arbitrário de arquivos do
+computador.
 
-- `JEV_BROWSER_MODE=harness` inicia um navegador isolado e sem interface,
-  adequado para testes automatizados e CI.
-- `JEV_BROWSER_MODE=computer` abre o Chrome ou Edge instalado. O MCP usa um
-  perfil persistente próprio; faça login nele uma vez. Não configure o perfil
-  pessoal que já está aberto no computador.
-- `JEV_BROWSER_CHANNEL=chrome` ou `msedge` escolhe o navegador.
-- `JEV_BROWSER_PROFILE` define o caminho absoluto do perfil persistente no
-  modo `computer`.
-
-Para um fluxo conhecido, o agente do harness consulta o cenário e os critérios
-de aceitação no projeto e chama `run_browser_flow` uma vez. Informe o objetivo,
-a URL inicial, o resultado esperado e planos candidatos declarativos. O Jev
-escolhe um dos planos com base no snapshot acessível da página; o MCP executa
-os passos e confere se o resultado esperado apareceu. Exemplo resumido:
+Exemplo de chamada:
 
 ```json
 {
-  "flow": "Adicionar o produto ao carrinho",
+  "flow": "Adicionar o produto ao carrinho e confirmar o resumo",
   "initial_url": "http://127.0.0.1:4173/products/coffee",
   "expected_outcome": "Coffee added to cart",
+  "options": {
+    "fast_path": true,
+    "snapshot_scope": "main",
+    "capture_network_errors": true,
+    "screenshot_on_failure": true
+  },
   "candidate_plans": {
-    "add_product": {
-      "description": "Adicionar o produto visível ao carrinho",
+    "add_and_confirm": {
+      "description": "Adicionar o produto visível ao carrinho e abrir o resumo",
       "steps": [
         {"action": "click", "role": "button", "name": "Add to cart"},
-        {"action": "wait_for_text", "text": "Coffee added to cart"}
+        {"action": "wait_for_text", "text": "Coffee added to cart"},
+        {"action": "click", "role": "link", "name": "View cart"},
+        {"action": "assert_text", "role": "heading", "name": "Order summary", "expected": "Coffee"}
       ]
     }
   }
 }
 ```
 
-O servidor também oferece `choose_next_action` para exploração passo a passo;
-esse modo exige chamadas separadas do harness e costuma ser mais lento. Os
-planos aceitam ações limitadas como clique por papel e nome acessível,
-preenchimento, espera por texto, rolagem e reação idempotente a um comentário
-único. Não aceitam JavaScript arbitrário, coordenadas nem seletores livres.
-Valores digitados ficam no Playwright e são removidos do conteúdo enviado ao
-Jev. Não coloque senhas, tokens ou outros segredos na descrição do fluxo ou
-nos critérios.
-
-O contrato também oferece `select_option`, `hover`, teclas `Enter`/`Escape`/`Tab`,
-asserções por elemento (`assert_text`, `assert_value`, `assert_visible`,
-`assert_hidden`), escopo de alvo por `within` e índice zero-based com `index`,
-além de alvos nomeados em iframes. `upload_file` aceita inputs, botões que abrem
-o seletor nativo e dropzones; configure `JEV_BROWSER_UPLOAD_ROOT` para limitar
-os arquivos locais que o MCP pode ler. `click` com `expect_download: true`
-captura arquivos na pasta de artefatos dentro dos limites configurados, e
-`audit_accessibility` roda axe nas tags WCAG 2.0/2.1 A/AA. A análise automatizada
-não substitui auditoria manual. Um único plano usa o fast-path por padrão e não
-chama a API Decisions. `options` pode limitar o
-snapshot a `main` ou `dialog`, bloquear rastreadores, capturar erros de console
-e rede e salvar screenshot/trace local em falhas. Os caminhos e limites estão
-descritos no [guia completo](docs/jev-browser-mcp.md).
-
-A resposta informa o status, o plano escolhido, as ações executadas, a captura
-final e se o resultado esperado foi confirmado. Consulte o [guia completo do
-MCP Jev Browser](docs/jev-browser-mcp.md) para schemas, limites, tempos e
-detalhes de segurança.
-
-O sidecar PostgreSQL de teste pode ser validado localmente com:
-
-```bash
-docker compose -f docker-compose.agentic.yml up -d --build
-python scripts/smoke_mcp.py postgres --rows
-python scripts/smoke_postgres_discovery.py --seed tests/fixtures/postgres_existing_schema.sql
-docker compose -f docker-compose.agentic.yml down -v
-```
-
-`smoke_mcp.py postgres` lista as ferramentas publicadas; `--rows` chama
-`pg_query`/`pg_explain` de verdade e exige que o gate recuse a leitura de linhas
-sem consent `read_only_data`. Listar ferramenta não é exercitá-la: foi por isso
-que um nome de argumento errado sobreviveu a probes verdes.
-
-`smoke_postgres_discovery.py` homologa AUD-034-DISCOVERY ponta a ponta —
-introspecta o schema físico por MCP, aplica `UP`/`DOWN` no banco efêmero,
-reintrospecta e compara os três snapshots. Sai com 0 somente quando a migration
-reversível é verificada **e** a irreversível é bloqueada. As duas DSNs são
-deliberadamente diferentes: `MCP_POSTGRES_DSN` é read-only e é a que a sessão
-MCP usa, `MCP_POSTGRES_VALIDATION_DSN` é a única que aplica migration e só é
-aceita para host allowlisted e banco efêmero.
-
-Novas APIs autenticadas: `GET/PUT /execution/policies`,
-`GET /execution/executors` e `GET /mcp/capabilities`. `POST /threads` aceita
-`execution_policy` por thread. Workflows de rollout:
-
-```text
-.github/workflows/agentic-offline.yml
-.github/workflows/mcp-integration-smoke.yml
-.github/workflows/agentic-graph-e2e.yml
-.github/workflows/deepseek-harness-eval.yml
-.github/workflows/executor-benchmark.yml
-.github/workflows/skills-offline.yml
-```
-
-### Skills por agente
-
-O catálogo canônico fica em `.agents/skills`. A descoberta retorna apenas
-nome, descrição, origem e hash; corpo e referências são carregados somente
-quando a política do agente autoriza a skill e a stack é compatível. O estado,
-relatório e logs recebem somente `skill_catalog_digest` e hashes de evidência.
-Campos `model`, `provider`, `tools`, credenciais e orçamento encontrados em
-frontmatter são inertes: a rota continua sendo resolvida exclusivamente pela
-política LLM/execution policy.
-
-Exemplo para ativar `frontend-design` no Designer UI e Remotion no Frontend/Code Review:
-
-```json
-{
-  "default": {"executor": "kernel", "skills": [], "skill_mode": "disabled"},
-  "agents": {
-    "agent_ui_designer": {"skills": ["frontend-design"], "skill_mode": "required"},
-    "agent_frontend": {"skills": ["frontend-design", "remotion-best-practices"], "skill_mode": "auto"},
-    "agent_code_review": {"skills": ["remotion-best-practices"], "skill_mode": "auto"}
-  }
-}
-```
-
-Valide o bundle e seu lockfile sem rede:
-
-```bash
-python scripts/validate_skills.py
-python -m pytest -q tests/test_skill_registry.py
-```
-
-As APIs autenticadas `GET /skills`, `GET /skills/{name}`,
-`GET /skills/capabilities`, `GET/PUT /skills/policies` e
-`POST /skills/validate` nunca retornam o corpo da skill. Instalação remota fica
-desabilitada até existir preview/diff, scanner, aprovação HITL e atualização
-atômica do lockfile. `find-skills` é reservado ao futuro curador administrativo
-e não é liberado aos desenvolvedores.
-
-Crie o Environment protegido `agentic-e2e`, exija aprovação manual e cadastre
-`OPENROUTER_API_KEY`, `CONTEXT7_API_KEY` e uma `TWENTY_FIRST_API_KEY` nova. A
-ordem de rollout é: `agentic-offline`, `mcp-integration-smoke`,
-`agentic-graph-e2e`, `deepseek-harness-eval` e, por fim,
-`executor-benchmark`. Os três últimos são validações reais/manuais: não devem
-ser tratados como aprovados somente porque a suíte offline passou. Consulte os
-guias oficiais:
-[Claude Code com OpenRouter](https://openrouter.ai/docs/guides/coding-agents/claude-code-integration),
-[Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python),
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md),
-[Context7](https://github.com/upstash/context7),
-[21st MCP](https://github.com/21st-dev/magic-mcp) e
-[pg-mcp-server](https://github.com/stuzero/pg-mcp-server).
+O plano é montado pelo LLM do harness, mas o Jev escolhe qual plano fornecido
+deve executar usando o fluxo e o snapshot inicial. O Jev não cria ações, nomes
+de controles ou valores de formulário. Valores de `type` são usados localmente
+pelo Playwright e são removidos do texto enviado ao provedor e da evidência de
+retorno. Use valores de teste; autenticação deve ficar no perfil de navegador
+configurado.
+
+O MCP também mantém `choose_next_action` para fluxos exploratórios em que o
+harness precisa inspecionar e decidir entre ações uma por vez. Esse caminho é
+mais lento porque exige uma nova decisão e uma nova chamada de ferramenta por
+ação; prefira `run_browser_flow` quando os passos esperados puderem ser
+descritos antes da execução.
+
+## Configuração
+
+Edite `config/ui-testing.json`. URL, modelo do provedor, variável de credencial
+e limites compartilhados ficam nos blocos `browser` e `jev`. As opções próprias
+do pacote Node ficam no bloco opcional `jev_browser_mcp`, que não altera o
+contrato lido pelo servidor Python. Preserve a estrutura completa exigida pelos
+validadores.
+
+`browser.mode` aceita `harness` ou `computer`; o padrão é `computer`:
+
+- `harness` usa Chrome headless e contexto isolado, adequado a execuções do
+  harness e CI; o estado de autenticação é descartado ao final da chamada.
+- `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.
+
+`browser.max_flow_steps` limita a soma de passos declarados entre os planos e
+`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, alvo, timeout e erro resumido quando uma
+etapa falha.
+
+`jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
+seletores e condições. `JEV_BROWSER_UPLOAD_ROOT` libera uploads somente dentro
+de uma pasta absoluta escolhida pelo operador.
+`jev_browser_mcp.browser.max_upload_files`, `max_upload_path_chars`,
+`max_upload_file_bytes` e `max_upload_total_bytes` limitam quantidade e tamanho.
+Não configure a raiz como o disco inteiro ou a pasta home: use uma pasta de
+fixtures dedicada.
+
+Os limites de download ficam no mesmo bloco: `max_download_files`,
+`max_download_file_bytes`, `max_download_total_bytes` e
+`max_download_timeout_seconds`. `jev_browser_mcp.jev.max_accessibility_violations`
+limita quantas descrições de violações axe entram no resultado; a contagem total
+continua informada mesmo quando a lista é truncada.
+
+O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
+`block_trackers`, `capture_console_errors`, `capture_network_errors`,
+`capture_network_error_bodies`, `ready_timeout_seconds`, `ready_network_idle`,
+`ready_stable_ms`, `ready_text`, `reuse_page`, `screenshot_on_failure` e
+`trace_on_failure`. 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 browser espera a SPA renderizar uma captura
+acessível estável. `ready_text` pode identificar o conteúdo que marca a
+prontidão. `reuse_page: true` pula a navegação somente quando a página e
+`initial_url` têm a mesma origem. `snapshot_scope` aceita `body`, `main` ou
+`dialog`.
+
+`block_trackers: true` bloqueia os domínios e tipos de recurso listados na
+configuração (analytics, Hotjar, fontes externas e mídia). Isso pode alterar o
+layout ou o comportamento do site, então a opção é desligada por padrão.
+
+Com `capture_console_errors` e `capture_network_errors`, o retorno traz
+`console_errors` e `network_failures`, limitados em quantidade e tamanho.
+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
+4xx/5xx da mesma origem, limita o corpo e inclui apenas o campo textual
+`message`, também sanitizado. Em falhas, `screenshot_on_failure` salva
+screenshot local e retorna
+`screenshot_path`. `trace_on_failure: true` também grava um `.zip` compatível
+com o Trace Viewer do Playwright e retorna `trace_path`. O diretório padrão é
+`~/.cache/orquestrador/jev-browser-artifacts`; `JEV_BROWSER_ARTIFACT_DIR` pode
+substituí-lo por uma pasta absoluta fora do pacote. Screenshots e traces podem
+conter dados visíveis da aplicação: mantenha o diretório local protegido e
+compartilhe os arquivos somente se o teste permitir.
+
+`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.
+
+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
+em `config/ui-testing.json`. `provider_url` é o endpoint HTTPS completo da API
+Decisions. O cliente não
+segue redirects e recusa URL com credencial, query string ou fragmento. O Jev
+fica indisponível quando a política de MCP está em modo offline.
+
+Na primeira execução, aqueça uma vez o cache local do pacote declarado em
+`browser.playwright_mcp_package` com `npx --yes <pacote> --help`. O MCP inicia
+depois com `--offline`, evitando uma consulta ao registry npm em cada fluxo.
+Quando a versão configurada mudar, aqueça o novo pacote uma vez.
+
+## Desempenho e evidência
+
+O pacote Node usa a decisão remota do Jev para escolher entre múltiplos planos.
+Com exatamente um plano e `fast_path` ligado (padrão), executa esse plano sem
+chamar a API Decisions; `jev_decisions` fica em zero. Inclua o fluxo completo em
+um plano candidato para evitar chamadas separadas ao harness; seleção,
+navegação, ações e asserções ficam em uma chamada MCP. O servidor Python
+`mcp_servers/jev_browser_server.py` mantém seu fluxo próprio e usa uma decisão
+remota do Jev por chamada. A sessão Playwright fecha antes de o MCP Python
+retornar. O perfil do modo `computer` preserva o login para chamadas seguintes;
+nesse servidor o processo e a janela não são reutilizados. O pacote Node mantém
+o browser aquecido até o harness encerrar o processo. O snapshot enviado ao Jev
+e devolvido ao harness remove o rodapé e, se ainda exceder o limite, mantém o
+início e o fim da captura com um marcador de truncamento. `snapshot_scope` pode
+limitar a captura a `main` ou `dialog`; iframes nomeados contidos nesse escopo
+também podem ser incluídos.
+
+A chamada composta aquecida deve ficar dentro da meta de 20 segundos em páginas
+que respondem normalmente; a inicialização fria, páginas lentas, MFA e conteúdo
+sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
+`navigation_ms`, `initial_snapshot_ms`, `jev_decision_ms` e `browser_plan_ms`
+para localizar o custo. O teto observado em um fluxo sintético local anterior
+foi 6,411 s; isso não mede o Instagram nem garante o mesmo tempo em outros sites.
+
+O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
+são enviados ao endpoint Decisions quando há mais de uma opção. 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.
+
+`network_idle` é uma espera limitada e opcional; páginas com polling ou conexões
+contínuas podem atingir o timeout. Prefira `wait_for_text` e asserções de
+elemento quando houver um sinal de interface específico.
+
+Consulte a [introdução do Jev](https://docs.typesafe.ai/introduction) e o
+[tutorial da API Decisions no OpenRouter](https://openrouter.ai/docs/guides/community/jev-tutorial)
+para os tipos de resposta e autenticação.