# duckduckgo-search-cli — Instruções para Agentes


## Regra Zero
- Leia este documento INTEGRALMENTE antes de invocar `duckduckgo-search-cli`.
- TODAS as suas invocações DEVEM estar em TOTAL conformidade com as regras aqui.
- Violações resultam em erros de execução, pipelines bloqueados e perda de resultados.
- A Regra Zero se aplica a cada chamada, cada script, cada pipeline, sem exceção.


## Visão Geral
- `duckduckgo-search-cli` é uma CLI Rust para busca DuckDuckGo via HTTP puro.
- Projetada para consumo por LLMs e agentes de IA em pipelines automatizados.
- Saída estruturada em JSON, Markdown, texto simples ou TSV.
- Códigos de saída são semanticamente definidos para tratamento preciso de erros.
- Versão: 0.7.5 (preparada 2026-06-14; v0.7.0–v0.7.4 também suportadas) — MSRV: Rust 1.88.


## Instalação
- Instale via Cargo: `cargo install duckduckgo-search-cli`
- Verifique a instalação: `duckduckgo-search-cli --version`
- Atualize para a versão mais recente: `cargo install duckduckgo-search-cli --force`


## Início Rápido
- OBRIGATÓRIO: SEMPRE envolva com `timeout` e passe `-q -f json`:

```bash
timeout 30 duckduckgo-search-cli -q -f json --num 15 "rust async runtime"
```

- Processe a saída com `jaq` — JAMAIS com `jq` ou ferramentas de texto:

```bash
timeout 30 duckduckgo-search-cli -q -f json --num 10 "consulta" | jaq -r '.resultados[].url'
```

- Verifique o exit code ANTES de parsear:

```bash
timeout 60 duckduckgo-search-cli -q -f json --num 15 "consulta" > /tmp/out.json
case $? in
  0) jaq '.resultados[].url' /tmp/out.json ;;
  3) echo "bloqueado, aguardando 300s"; sleep 300 ;;
  4) echo "timeout global, aumente --global-timeout" ;;
  5) echo "zero resultados, reformule a consulta" ;;
  *) echo "erro inesperado" ;;
esac
```


## Referência de Flags
- `-q, --quiet` — silencia logs de tracing; stdout carrega apenas o payload
- `-f, --format <FORMAT>` — formato de saída: `json` (OBRIGATÓRIO em scripts), `markdown`, `text`, `tsv`
- `-n, --num <N>` — número de resultados por página (padrão 15, máximo 30)
- `--pages <N>` — número de páginas a buscar (padrão 2, auto-paginação)
- `--parallel <N>` — requisições concorrentes em multi-query (DEVE ser ≤ 5)
- `--queries-file <FILE>` — arquivo com uma consulta por linha para modo lote
- `--fetch-content` — busca conteúdo completo da página por resultado (multiplicador de latência N×)
- `--max-content-length <N>` — limite de bytes buscados por página (DEVE usar com `--fetch-content`)
- `--output <FILE>` — grava JSON em arquivo com validação de segurança de caminho
- `--endpoint <html|lite>` — endpoint de busca (padrão `html`; use `lite` apenas após exit code 3)
- `--global-timeout <SEGS>` — timeout total em segundos para todas as consultas (DEVE ser < `timeout` externo)
- `--per-host-limit <N>` — máximo de requisições concorrentes por host (padrão 2, NÃO exceder 2)
- `--retries <N>` — número de tentativas com backoff exponencial (padrão 2)
- `--timeout <SEGS>` — timeout por requisição em segundos
- `--proxy <URL>` — PROIBIDO em argv; use a variável de ambiente `HTTPS_PROXY`
- `--no-proxy` — ignora toda configuração de proxy
- `--lang <LANG>` — filtro de idioma (ex.: `en-us`, `pt-br`)
- `--country <CC>` — filtro de país (ex.: `us`, `br`)
- `--time-filter <d|w|m>` — filtro de tempo: dia, semana, mês
- `--stream` — PROIBIDO: flag placeholder, NÃO implementada
- `-v, --verbose` — saída detalhada para diagnóstico
- `deep-research <QUERY>` — subcomando de fan-out de queries (v0.7.0)
- `--max-sub-queries <N>` — máximo de sub-queries produzidas (1..=12, padrão 5)
- `--sub-query-strategy <heuristic|manual>` — estratégia de geração de sub-queries
- `--sub-queries-file <PATH>` — lê sub-queries explícitas (estratégia manual)
- `--aggregate <rrf|dedupe-by-url>` — algoritmo de agregação
- `--depth <N>` — rounds de reflexão (planejado, não executado na v0.7.0)
- `--synthesize` — produz relatório final em Markdown/PlainText/JSON
- `--budget-tokens <N>` — orçamento de tokens para o relatório de síntese
- `--synth-format <markdown|plain|json>` — formato de saída da síntese
- `--probe-deep` — executa uma query real e classifica o body como `ok` ou `captcha` (v0.7.3+)
- `--no-warmup` — pula o warm-up `GET https://duckduckgo.com/` antes da primeira query real (v0.7.3+)
- `--no-cookie-persistence` — mantém cookies em memória apenas; nunca grava `cookies.json` em disco (v0.7.3+)
- `--cookies-path <PATH>` — sobrescreve o path XDG padrão do cookie jar (v0.7.3+)
- `--allow-lite-fallback` — opt-in para fallback automático `html → lite` quando CAPTCHA é detectado (v0.7.3+)


## Códigos de Saída
| Código | Significado | Ação do Agente |
|--------|-------------|----------------|
| `0` | Sucesso | Parsear `.resultados` |
| `1` | Erro de runtime | Ler stderr; retry único com `-v` |
| `2` | Erro de configuração | Executar `duckduckgo-search-cli init-config --force`; tentar novamente |
| `3` | Bloqueio anti-bot | Aguardar 300+ s; trocar `--endpoint lite`; rotacionar proxy |
| `4` | Timeout global | Elevar `--global-timeout`; reduzir `--parallel` |
| `5` | Zero resultados | Refinar consulta; tentar diferente `--lang` ou `--country` |


## Invariantes Centrais
### OBRIGATÓRIO — Siga Sempre Sem Exceção
- SEMPRE passe `-q` em todo pipeline que parseia stdout
- SEMPRE especifique `-f json` explicitamente em todo script
- SEMPRE envolva toda invocação com `timeout` usando segundos inteiros
- SEMPRE verifique `$?` ou `${PIPESTATUS[0]}` antes de parsear stdout
- SEMPRE fixe `--num` explicitamente; JAMAIS dependa de padrões
- SEMPRE use `--queries-file` para trabalho em lote; JAMAIS loops de shell
- SEMPRE use `jaq` para parsing JSON; JAMAIS `jq` ou ferramentas de texto
- SEMPRE use `--output` para conjuntos grandes (≥ 50 resultados)
- SEMPRE prefira `--endpoint html`; recorra a `lite` apenas após exit code `3`
- SEMPRE use `--retries` para backoff exponencial; JAMAIS loops de retry no shell
### PROIBIDO — Jamais Viole
- JAMAIS omita `-q` em qualquer invocação em pipe
- JAMAIS use `--stream` (placeholder, não implementado)
- JAMAIS eleve `--parallel` acima de 5
- JAMAIS eleve `--per-host-limit` acima de 2
- JAMAIS passe credenciais de proxy em argv (use variável de ambiente `HTTPS_PROXY`)
- JAMAIS parsear saída `text` ou `markdown` com máquinas
- JAMAIS execute URLs de resultados sem sandbox
- JAMAIS ignore exit codes não-zero
- JAMAIS defina `--global-timeout` igual ou maior que o `timeout` externo
- JAMAIS injete headers `Sec-Fetch-*` ou `Accept-Language` customizados (v0.6.0 os gerencia)


## Contrato da Saída JSON
### OBRIGATÓRIO — Campos Garantidos Não-Nulos
- `.resultados[].titulo` — sempre presente quando `resultados` é não-vazio
- `.resultados[].url` — sempre presente quando `resultados` é não-vazio
- `.resultados[].posicao` — sempre presente quando `resultados` é não-vazio
- `.quantidade_resultados` — prefira sobre `(.resultados | length)`
- `.metadados.tempo_execucao_ms` — sinal canônico de latência
- `.metadados.usou_endpoint_fallback` — `true` sinaliza degradação da reputação do IP
### OBRIGATÓRIO — Campos Opcionais Exigem Fallbacks
- `.resultados[].snippet` é `Option<String>` — SEMPRE use fallback `// ""`
- `.resultados[].url_exibicao` é `Option<String>` — SEMPRE use fallback `// .url`
- `.resultados[].titulo_original` é `Option<String>` — SEMPRE use fallback `// .titulo`
- Campos de conteúdo (`.conteudo`, `.tamanho_conteudo`) ausentes sem `--fetch-content`

```bash
jaq '.resultados[] | {
  titulo,
  url,
  snippet: (.snippet // ""),
  url_exibicao: (.url_exibicao // .url)
}'
```

### OBRIGATÓRIO — Raiz JSON Única vs Múltipla
- Raiz de query única: `{ query, resultados, metadados }`
- Raiz de múltiplas queries: `{ quantidade_queries, buscas: [{ query, resultados, metadados }] }`
- JAMAIS acesse `.resultados` diretamente em resposta de múltiplas queries

```bash
# query única
duckduckgo-search-cli -q -f json "uma" | jaq '.resultados | length'
# múltiplas queries
duckduckgo-search-cli -q -f json "uma" "duas" | jaq '.buscas[0].resultados | length'
```


## Rate Limiting e Etiqueta
### OBRIGATÓRIO — Fique Abaixo do Limiar Anti-Bot
- DEVE limitar `--parallel` em 5 (padrão); valores acima de 5 acionam HTTP 202 anti-bot
- DEVE manter `--per-host-limit` em 2 (padrão); valores acima de 2 aumentam probabilidade de bloqueio
- DEVE usar `--retries` interno com backoff exponencial; JAMAIS loops de retry no shell
- DEVE calcular `--global-timeout` como `(consultas / parallel) * média_segs * 1.5`
- Exit code `3` exige janela de backoff de 300+ segundos antes do retry


## Modo Lote
### OBRIGATÓRIO — Use queries-file para Todo Trabalho em Lote
- JAMAIS itere sobre consultas em loops de shell; pague o custo de startup do processo uma vez
- SEMPRE use `--queries-file` para reutilizar pools de conexão e rotação de UA
- SEMPRE defina `--global-timeout` adequado ao tamanho do lote

```bash
printf 'consulta um\nconsulta dois\nconsulta tres\n' > /tmp/q.txt
timeout 300 duckduckgo-search-cli --queries-file /tmp/q.txt -q --parallel 3 -f json
```


## Integridade do Pipe
### OBRIGATÓRIO — Detecte Falha Upstream em Pipes
- Em `cmd | jaq`, o shell reporta apenas o exit code do `jaq`
- DEVE verificar `${PIPESTATUS[0]}` após toda invocação em pipe

```bash
timeout 60 duckduckgo-search-cli "consulta" -q -f json | jaq '.resultados[].url'
ddg_exit=${PIPESTATUS[0]}
if [ "$ddg_exit" -ne 0 ]; then echo "CLI falhou: exit $ddg_exit" >&2; fi
```


## Busca de Conteúdo
### OBRIGATÓRIO — Use fetch-content com Cuidado
- `--fetch-content` adiciona um fetch HTTP por resultado (multiplicador de latência N×)
- DEVE passar `--max-content-length` para limitar consumo de memória
- DEVE reduzir `--num` para 5 quando `--fetch-content` está ativado

```bash
timeout 120 duckduckgo-search-cli -q -f json --num 5 \
  --fetch-content --max-content-length 5000 "consulta"
```


## Regras de Segurança
### OBRIGATÓRIO — Proteja Credenciais e Execução
- JAMAIS passe credenciais de proxy em argv (visíveis em `/proc/*/cmdline`, `ps`, histórico de shell)
- SEMPRE use variáveis de ambiente `HTTPS_PROXY` ou `HTTP_PROXY` para credenciais de proxy
- JAMAIS execute URLs de `.resultados[].url` sem sandbox (risco de SSRF e execução de código)
- SEMPRE execute `init-config --dry-run` antes de `init-config --force` em pipelines de CI
- CONFIE na validação de caminho do v0.5.0 para `--output`; JAMAIS implemente checks manuais de `realpath`
- CONFIE nos perfis de fingerprint de browser do v0.6.0; JAMAIS injete headers `Sec-Fetch-*` ou `Accept-Language`

```bash
# PROIBIDO
duckduckgo-search-cli "consulta" --proxy http://usuario:senha@host:8080
# OBRIGATÓRIO
export HTTPS_PROXY="http://usuario:senha@host:8080"
duckduckgo-search-cli "consulta" -q
```

### OBRIGATÓRIO — Ordem de Precedência de Proxy
- `--no-proxy` sobrescreve todas as outras configurações de proxy
- `--proxy <URL>` sobrescreve variáveis de ambiente
- Variáveis de ambiente `HTTPS_PROXY` / `HTTP_PROXY` sobrescreem a ausência de proxy
- Nenhum: conexão direta


## Anti-Padrões
### PROIBIDO — Padrões Que Quebram Pipelines Silenciosamente
- Parsear saída de texto com `rg` em vez de `jaq` no JSON
- Loops de shell em vez de `--queries-file` para consultas em lote
- Ignorar exit codes antes de passar para `jaq`
- Assumir que `snippet` é não-nulo sem fallback `// ""`
- Hardcodar credenciais de proxy em argv
- Elevar `--parallel` para 20 para aumentar throughput (aciona exit code 3)
- Usar `--stream` (placeholder, comportamento indefinido)
- Invocar sem envoltório `timeout` (pipeline trava indefinidamente)
- Definir `--global-timeout` igual ao `timeout` externo (CLI nunca termina limpa)
- Hardcodar `--identity-profile` em vez de deixar o pool rotacionar adaptativamente (v0.6.5+)
- Ler `.metadados.identidade_usada` como garantia quando é `Option<String>` (v0.6.5+)
- Ler `.metadados.nivel_cascata` como garantia quando é `Option<u32>` (v0.6.5+)
- Pular `duckduckgo-search-cli --probe` antes de lançar queries reais em CI


## v0.7.0 — Subcomando Deep Research

### OBRIGATÓRIO — Use o Novo Subcomando para Pesquisa Multi-Hop

Para perguntas que se beneficiam de fan-out de queries ("compare X vs Y em 2026", "história de Z", "o que mudou na biblioteca W"), use o subcomando `deep-research` em vez de rodar uma única busca.

```bash
timeout 60 duckduckgo-search-cli -q -f json deep-research "melhor cliente http rust 2026" \
  | jaq '.resultados[] | {titulo, url, score}'
```

### OBRIGATÓRIO — Schema de Saída do Deep Research

- O JSON de topo tem três chaves: `metadados`, `resultados` e `sintese` opcional
- `.metadados.query_original` é a entrada do usuário
- `.metadados.sub_queries[]` lista cada sub-query gerada com `texto`, `estrategia`, `status`, `elapsed_ms`
- `.metadados.total_resultados_unicos` é a contagem deduplicada
- `.metadados.tempo_total_ms` é a latência end-to-end
- `.resultados[].score` é um valor normalizado `[0.0, 1.0]` — maior é melhor
- `.resultados[].fontes[]` lista as sub-queries que produziram o resultado (rastreabilidade)
- `.sintese` aparece apenas quando `--synthesize` está ativo

```bash
# Extrair o relatório Markdown (quando --synthesize está ativo)
timeout 120 duckduckgo-search-cli -q -f json deep-research "tópico" \
  --synthesize --synth-format markdown | jaq -r '.sintese'
```

### OBRIGATÓRIO — Arquivo de Sub-Queries Manual

Quando `--sub-query-strategy manual` é definido, a CLI lê sub-queries de `--sub-queries-file PATH`. Comentários (`#`) e linhas em branco são ignorados. O arquivo DEVE conter pelo menos uma linha que não seja comentário.

```bash
cat > /tmp/qs.txt <<EOF
# Visão geral
o que é tokio runtime 2026
# Comparação
tokio vs async-std
EOF

timeout 60 duckduckgo-search-cli -q -f json deep-research "tokio 2026" \
  --sub-query-strategy manual --sub-queries-file /tmp/qs.txt
```

### OBRIGATÓRIO — Herda Flags Globais

`deep-research` aceita todas as flags globais (`-n`, `--lang`, `--country`, `--parallel`, `--endpoint`, `--retries`, `--timeout`, `--global-timeout`, `--proxy`, `--fetch-content`, `--max-content-length`). Os knobs específicos do deep-research são sobrepostos.

### OBRIGATÓRIO — Orçamento de Tokens para Síntese

`--budget-tokens` usa a heurística 1 token ≈ 4 chars. O relatório sintetizado tem teto rígido de 20 referências. Defina `--budget-tokens 0` para desabilitar o teto e contar apenas com o limite de 20 referências.

## v0.6.4 e v0.6.5 — Pool Adaptativo de Identidades Anti-Bot (WS-26)

### OBRIGATÓRIO — Reconhecer as Novas Flags
- `--probe` — verificação de saúde pré-voo. DEVE ser usada em CI antes de lançar queries reais.
- `--identity-profile <auto|chrome-win|chrome-mac|chrome-linux|edge-win|firefox-linux|safari-mac>` — fixa a sessão em uma identidade específica. `auto` (padrão) rotaciona adaptativamente.
- `--seed <u64>` — seed determinístico para seleção de UA E rotação do pool de identidades.

### OBRIGATÓRIO — Ler os Novos Campos de Metadados
- `.metadados.identidade_usada` — `Option<String>` — tag de identidade que produziu a resposta (formato `<família>-<plataforma>-<16hex>`)
- `.metadados.nivel_cascata` — `Option<u32>` (0..=4) — nível de cascata atingido durante a requisição

```bash
# Verifica qual identidade produziu a resposta
timeout 30 duckduckgo-search-cli -q -f json "query" | jaq '.metadados.identidade_usada // "auto"'

# Diagnostica bloqueios repetidos via nível de cascata
timeout 30 duckduckgo-search-cli -q -f json "query" | jaq '.metadados.nivel_cascata // 0'
```

### OBRIGATÓRIO — Estratégia de Cascata Anti-Bot
Quando exit code `3` é encontrado, a CLI já rotacionou por até 5 identidades internamente. Se `--identity-profile auto` está em efeito e exit code `3` persiste, o agente DEVE:
1. Aguardar 300+ segundos antes de retentar (o nível de cascata atingido indica o quão esgotado o pool está)
2. Trocar para `--endpoint lite` como fallback
3. Rotacionar proxy com `--proxy socks5://127.0.0.1:9050`
4. Se o problema persistir, abrir bug com o valor de `nivel_cascata` capturado

### OBRIGATÓRIO — Probe Antes de Queries Reais
```bash
# Gate de pipeline CI
timeout 15 duckduckgo-search-cli --probe || { echo "DDG bloqueado em nível de rede, abortando" >&2; exit 1; }
timeout 30 duckduckgo-search-cli -q -f json "query real"
```


## Compilação
- Build de desenvolvimento: `cargo build`
- Build de release: `timeout 600 cargo build --release`
- Verificar compilação: `timeout 120 cargo check --all-targets`
- Alvos de cross-compilation: ver `docs/CROSS_PLATFORM.md`


## Testes
- Executar todos os testes: `timeout 300 cargo nextest run`
- Executar testes de documentação separadamente: `cargo test --doc`
- Executar testes de integração E2E: `timeout 300 cargo test --test integration_pipeline`
- Executar com todas as features: `timeout 300 cargo test --all-features`
- Cobertura mínima: 80% — JAMAIS faça merge abaixo deste limite


## Linting
- Executar Clippy com warnings como erros: `timeout 180 cargo clippy --all-targets --all-features -- -D warnings`
- ZERO warnings são tolerados em código de produção
- Corrija todas as sugestões do Clippy antes de abrir um pull request


## Formatação
- Verificar formatação: `cargo fmt --all --check`
- Aplicar formatação: `cargo fmt --all`
- ZERO diferenças são toleradas em commits
- Execute verificação de formatação no CI antes de qualquer outro gate


## Cobertura
- Executar com relatório texto: `cargo llvm-cov --text`
- Executar com relatório HTML: `cargo llvm-cov --html`
- Meta mínima: 80% de cobertura de linhas
- Recomendado para código novo: 90% de cobertura de linhas
- Gates de cobertura se aplicam a todo pull request sem exceção


## Auditoria
- Verificar vulnerabilidades: `timeout 120 cargo audit`
- Verificar licenças e supply chain: `timeout 120 cargo deny check advisories licenses bans sources`
- ZERO vulnerabilidades são toleradas em releases
- Execute auditoria no CI a cada push para main


## Sequência de Validação Completa
- Execute os 10 comandos abaixo em ordem antes de qualquer release:
- `cargo fmt --all --check` — ZERO diferenças
- `timeout 180 cargo clippy --all-targets --all-features -- -D warnings` — ZERO warnings
- `timeout 120 cargo check --all-targets` — ZERO erros
- `RUSTDOCFLAGS="-D warnings" timeout 120 cargo doc --no-deps --all-features` — ZERO warnings
- `timeout 300 cargo nextest run` — ZERO falhas
- `cargo llvm-cov --text` — mínimo 80% de cobertura
- `timeout 120 cargo audit` — ZERO vulnerabilidades
- `timeout 120 cargo deny check advisories licenses bans sources` — ZERO violações
- `timeout 120 cargo publish --dry-run --allow-dirty` — ZERO erros
- `cargo package --list` — ZERO arquivos sensíveis


## Padrões de Integração com LLMs
### OBRIGATÓRIO — Padrões Canônicos para Agentes de IA
- Use `-q -f json` como o ÚNICO contrato de saída legível por máquina
- Use `jaq` como o ÚNICO parser JSON em pipelines
- Use `timeout` como o ÚNICO mecanismo para limitar o tempo de execução
- Use `${PIPESTATUS[0]}` como a ÚNICA forma de detectar falha upstream do CLI
- Use `--queries-file` como o ÚNICO mecanismo de invocação em lote
- Use variáveis de ambiente como o ÚNICO armazenamento de credenciais

```bash
# Padrão canônico de invocação por agente
timeout 60 duckduckgo-search-cli -q -f json --num 15 "$CONSULTA" > /tmp/ddg_out.json
ddg_exit=$?
if [ "$ddg_exit" -ne 0 ]; then
  echo "DDG falhou com exit $ddg_exit" >&2
  exit "$ddg_exit"
fi
jaq -r '.resultados[] | "\(.posicao): \(.titulo) — \(.url)"' /tmp/ddg_out.json
```

### OBRIGATÓRIO — Padrão de Carregamento de Contexto para LLMs
- Busque conteúdo para contexto profundo com limites estritos:

```bash
timeout 120 duckduckgo-search-cli -q -f json \
  --num 5 --fetch-content --max-content-length 5000 \
  "$CONSULTA" | jaq '.resultados[] | {titulo, url, conteudo: (.conteudo // "")}'
```

### OBRIGATÓRIO — Padrão de Múltiplas Consultas
- Use `--queries-file` com `--parallel 3` para pesquisa em lote por LLMs:

```bash
printf '%s\n' "${CONSULTAS[@]}" > /tmp/consultas.txt
timeout 300 duckduckgo-search-cli \
  --queries-file /tmp/consultas.txt \
  -q -f json --parallel 3 --per-host-limit 1 --retries 3 \
  --global-timeout 280 > /tmp/multi_out.json
jaq -r '.buscas[].resultados[].url' /tmp/multi_out.json | sort -u
```


## Tratamento de Erros
### OBRIGATÓRIO — Template Completo de Handler

```bash
executar_ddg() {
  local consulta="$1"
  local arquivo_saida="$2"
  timeout 60 duckduckgo-search-cli -q -f json --num 15 "$consulta" > "$arquivo_saida"
  local ec=$?
  case $ec in
    0) return 0 ;;
    3) echo "BLOQUEADO: anti-bot. Aguarde 300s e rotacione proxy." >&2; return 3 ;;
    4) echo "TIMEOUT: aumente --global-timeout." >&2; return 4 ;;
    5) echo "ZERO_RESULTADOS: reformule a consulta." >&2; return 5 ;;
    *) echo "ERRO($ec): verifique stderr." >&2; return "$ec" ;;
  esac
}
```

### OBRIGATÓRIO — Template de Integridade do Pipe

```bash
timeout 60 duckduckgo-search-cli "consulta" -q -f json | jaq '.resultados[].url'
ddg_exit=${PIPESTATUS[0]}
[ "$ddg_exit" -eq 0 ] || { echo "CLI falhou: exit $ddg_exit" >&2; exit "$ddg_exit"; }
```


## Arquivos de Configuração
- Localização padrão: `$XDG_CONFIG_HOME/duckduckgo-search-cli/` (padrão `~/.config/duckduckgo-search-cli/`)
- Override de localização: variável de ambiente `DUCKDUCKGO_SEARCH_CLI_HOME`
- `selectors.toml` — seletores CSS para parsing de HTML
- `user-agents.toml` — pool de rotação de User-Agent
- Inicializar configuração: `duckduckgo-search-cli init-config`
- Atualização segura: `duckduckgo-search-cli init-config --dry-run` depois `--force`
- Componentes `..` em caminhos são rejeitados automaticamente no v0.5.0+


## Cartão de Referência Rápida

| Regra | Instrução |
|-------|-----------|
| R01 | DEVE passar `-q` ao canalizar para qualquer parser |
| R02 | DEVE especificar `-f json` explicitamente em scripts |
| R03 | JAMAIS parsear `text` ou `markdown` com máquinas |
| R04 | DEVE fixar `--num` explicitamente |
| R05 | DEVE limitar `--parallel` em 5 |
| R06 | DEVE usar `--output` para conjuntos grandes |
| R07 | JAMAIS invocar sem `timeout` |
| R08 | DEVE usar `--queries-file` para trabalho em lote |
| R09 | JAMAIS usar `--stream` (não implementado) |
| R10 | DEVE preferir `--endpoint html` |
| R11 | DEVE distinguir raiz JSON única vs múltipla |
| R12 | DEVE tratar `titulo` e `url` como garantidos não-nulos |
| R13 | JAMAIS assumir que campos opcionais estão presentes |
| R14 | DEVE usar `${PIPESTATUS[0]}` para detectar falhas em pipes |
| R15 | JAMAIS passar credenciais de proxy em argv |
| R16 | JAMAIS executar URLs de resultados sem sandbox |
| R17 | JAMAIS injetar headers `Sec-Fetch-*` (v0.6.0 os gerencia) |
| R18 | DEVE rodar `duckduckgo-search-cli --probe-deep` antes de queries reais em runners macOS para detectar CAPTCHA cedo (v0.7.3+) |
| R19 | DEVE tratar o cookie jar (`cookies.json`) como credencial; desabilite com `--no-cookie-persistence` (v0.7.3+) |
| R20 | DEVE usar `--allow-lite-fallback` apenas quando resultados `lite` forem aceitáveis; não habilite em pipelines que precisam de resultados `html` (v0.7.3+) |


## v0.7.3 — Session + Probe-Deep + BoringSSL (correção do GAP-WS-27)

### OBRIGATÓRIO — Reconhecer as Novas Flags
- `--probe-deep` — executa uma query real e reporta `status: "ok"` ou `status: "captcha"`. Use isto em portões de CI para runners macOS para detectar interstitials do Cloudflare Bot Management antes de lançar pipelines custosas.
- `--no-warmup` — pula o warm-up `GET https://duckduckgo.com/` que popula os cookies de sessão.
- `--no-cookie-persistence` — mantém cookies em memória apenas; nunca grava `cookies.json` em disco.
- `--cookies-path <PATH>` — sobrescreve o path XDG padrão do cookie jar. Use isto para apontar para um volume encriptado.
- `--allow-lite-fallback` — opt-in para fallback automático do endpoint `html` para o endpoint `lite` quando CAPTCHA é detectado. Desligado por padrão.

### OBRIGATÓRIO — Pré-requisitos de Build Mudaram (v0.7.3+)
- Compilar do código-fonte no Linux agora requer `cmake`, `perl`, `pkg-config` e `libclang-dev`. Binários pré-compilados do crates.io não são afetados. Este requisito é o trade-off pela troca da stack TLS de `rustls` para BoringSSL (estaticamente vinculado pelo `wreq 6.0.0-rc.29`), que produz fingerprint JA4_o idêntico ao Chrome/Safari e fecha o CAPTCHA do macOS do GAP-WS-27.

### OBRIGATÓRIO — Trate o Cookie Jar como Credencial
- A feature `session` persiste cookies de sessão do DuckDuckGo em `~/.config/duckduckgo-search-cli/cookies.json` (Linux), `%APPDATA%\duckduckgo-search-cli\cookies.json` (Windows), ou `~/Library/Application Support/duckduckgo-search-cli/cookies.json` (macOS) com permissões Unix `0o600`. Leia o arquivo com o mesmo cuidado que leria uma API key.

Upstream: https://github.com/daniloaguiarbr/duckduckgo-search-cli
Contrato de schema válido para `duckduckgo-search-cli` v0.7.5.
Versão em inglês: `docs/AGENTS.md`.
