Navegação Definitiva

Acesso à web para hosts que o navegador do usuário não consegue abrir (WAF / 403 / Cloudflare / páginas com pontuação de bot) e para plataformas com um leitor nativo. A leitura e interação em uma página que o navegador do usuário consegue abrir pertencem ao motor associado da habilidade browser, não aqui. Comece no nível mais barato que consegue alcançar o host bloqueado e suba apenas quando não conseguir:

Nível 1 — insane-search (extração headless + bypass de WAF) -> Nível 1.5 — agent-reach (APIs nativas da plataforma, especialmente plataformas chinesas) -> Nível 2 — um navegador real através de omowright de js eval: 2a o motor próprio (um navegador que seu código inicia, CloakBrowser para discrição), 2b o motor associado (o navegador logado do próprio usuário).

FASE 0 — ROTEIE PRIMEIRO (OBRIGATÓRIO)

User request
  |
  +- a page the user's browser can open (read, click, screenshot, QA, login)  NOT this skill (browser skill, attached engine)
  +- simple search query ------------------------------ NOT this skill (use web-search)
  |
  +- URL blocked / 403 / Cloudflare / WAF ------------- TIER 1  insane-search
  +- YouTube/Vimeo/TikTok subtitles or metadata ------- TIER 1  insane-search (yt-dlp)
  +- archive snapshot of a dead or changed page ------- TIER 1  insane-search (surrogates, provenance-tagged)
  |
  +- Chinese platform (xhs/douyin/weibo/bilibili/v2ex/wechat)  TIER 1.5 agent-reach
  +- podcast transcript / stock forum ----------------- TIER 1.5 agent-reach
  +- Twitter feed / LinkedIn profile / GitHub via CLI - TIER 1.5 agent-reach
  |
  +- Tier 1/1.5 returned empty or partial ------------- TIER 2  2a owned engine (stealth)
  +- a blocked host that also needs a click, a scroll or a screenshot  TIER 2  2a owned engine
  +- the user's account on a host the owned engine cannot pass  TIER 2  2b attached engine (their browser)

Leia a referência correspondente antes de agir: references/insane-search/README.md, references/agent-reach/README.md, ou references/chrome-stealth.md.

Nível 1 — insane-search (extração headless)

Quando: bypass de URL bloqueado, metadados de mídia, substitutos de arquivo — sem necessidade de interface de navegador. Por que primeiro: ~10x mais rápido que um navegador, sem inicialização de processo; lida com a maioria das solicitações de "buscar esta página bloqueada" via imitação de TLS curl_cffi, yt-dlp (1858 sites), APIs públicas oficiais, transformações de URL móvel, substitutos de arquivo de Fase-2.5 (snapshots do Wayback / archive.today, com proveniência marcada — veja references/insane-search/cache-archive.md), um Jina Reader com chave (JINA_API_KEY), e um fallback Playwright de Chrome real. O motor vive dentro desta habilidade em engine/ e é invocado como um módulo. Resultados substitutos são CÓPIAS datadas: um resultado cujo provenance é snapshot deve ser reportado com seu snapshot_timestamp, nunca apresentado como a página ao vivo.

# Core command — auto-detects WAF, runs the full fetch grid (run from the skill dir):
python3 -m engine "https://example.com/blocked-page"
#   add --selector "<CSS>" for positive-proof validation, --device auto|desktop|mobile,
#   --trace to inspect every attempt, --json for machine-readable output.

# YouTube subtitles / metadata (no browser):
yt-dlp --write-sub --write-auto-sub --sub-lang "en,ko" --skip-download -o "/tmp/%(id)s" "<URL>"

# Reddit / HN / Bluesky / arXiv etc. use official public endpoints — see the Phase 0 index in
# references/insane-search/README.md (Twitter syndication, Reddit .json, HN Firebase, ...).

O harness completo do motor (regras R1-R7, o índice oficial de API da Fase 0, a regra de nome de site inexistente e os mergulhos profundos references/insane-search/*.md para TLS, roteamento Playwright, Naver, mídia, etc.) está em references/insane-search/README.md. Leia-o antes de ajustar o motor ou adicionar um perfil WAF.

Escalar para Nível 1.5 ou Nível 2 quando

• O alvo é uma plataforma chinesa / social com um leitor nativo -> Nível 1.5.
• insane-search retorna vazio/parcial, ou a página bloqueada precisa de interação JS, uma captura de tela, ou reprodução de mídia -> Nível 2.

Nível 1.5 — agent-reach (leitores nativos da plataforma)

…