> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração — Env, Slashes e /config

> Referência completa dos sete padrões: todos os env vars CHATCLI_QUALITY_* e CHATCLI_EMBED_*, os cinco slashes (/thinking, /plan, /refine, /verify, /reflect), e o que /config quality mostra.

Toda a configuração do harness/pipeline de qualidade em um lugar só. Três canais: **env vars** (persistentes), **slashes** (sessão), **/config quality** (inspeção).

***

## `/config quality`

Comando único que lista todo o estado do pipeline:

```bash theme={"system"}
/config quality
```

Saída típica:

```text theme={"system"}
✨ HARNESS/PIPELINE DE QUALIDADE DO AGENTE ──────────────────
  CHATCLI_QUALITY_ENABLED              : enabled
  Hooks registrados                   : pre=0, post=2

  ── Self-Refine (#5)
  CHATCLI_QUALITY_REFINE_ENABLED       : disabled
  CHATCLI_QUALITY_REFINE_MAX_PASSES    : 1
  CHATCLI_QUALITY_REFINE_MIN_BYTES     : 200
  CHATCLI_QUALITY_REFINE_EPSILON       : 50
  CHATCLI_QUALITY_REFINE_EXCLUDE       : formatter, deps, refiner, verifier
  CHATCLI_QUALITY_REFINE_CONVERGENCE_ENABLED   : enabled
  CHATCLI_QUALITY_REFINE_CONVERGENCE_EMBEDDING : disabled
  CHATCLI_QUALITY_REFINE_CONVERGENCE_STRICT    : disabled
  CHATCLI_QUALITY_REFINE_CONVERGENCE_CHAR_HIGH : 0.99
  CHATCLI_QUALITY_REFINE_CONVERGENCE_JACCARD_HIGH: 0.95
  CHATCLI_QUALITY_REFINE_CONVERGENCE_EMBEDDING_SIM: 0.92

  ── Chain-of-Verification / CoVe (#6)
  CHATCLI_QUALITY_VERIFY_ENABLED       : disabled
  CHATCLI_QUALITY_VERIFY_NUM_QUESTIONS : 3
  CHATCLI_QUALITY_VERIFY_REWRITE       : enabled
  CHATCLI_QUALITY_VERIFY_EXCLUDE       : formatter, deps, shell, refiner, verifier

  ── Reflexion (#3)
  CHATCLI_QUALITY_REFLEXION_ENABLED       : enabled
  CHATCLI_QUALITY_REFLEXION_ON_ERROR      : enabled
  CHATCLI_QUALITY_REFLEXION_ON_HALLUCINATION: enabled
  CHATCLI_QUALITY_REFLEXION_ON_LOW_QUALITY : disabled
  CHATCLI_QUALITY_REFLEXION_PERSIST       : enabled
  CHATCLI_QUALITY_REFLEXION_QUEUE_ENABLED : enabled
  CHATCLI_QUALITY_REFLEXION_QUEUE_WORKERS : 2
  CHATCLI_QUALITY_REFLEXION_QUEUE_CAPACITY: 1000
  CHATCLI_QUALITY_REFLEXION_QUEUE_MAX_ATTEMPTS: 5
  CHATCLI_QUALITY_REFLEXION_QUEUE_STALE_AFTER : 168h0m0s
  Estado em tempo real                  : queue=0 dlq=0

  ── Plan-and-Solve / ReWOO (#2)
  CHATCLI_QUALITY_PLAN_FIRST_MODE      : auto
  CHATCLI_QUALITY_PLAN_FIRST_THRESHOLD : 6

  ── RAG + HyDE (#4)
  CHATCLI_QUALITY_HYDE_ENABLED         : disabled
  CHATCLI_QUALITY_HYDE_USE_VECTORS     : disabled
  CHATCLI_EMBED_PROVIDER               : (not set)
  CHATCLI_EMBED_MODEL                  : (not set)
  CHATCLI_QUALITY_HYDE_NUM_KEYWORDS    : 5
  Índice vetorial                     : (not attached)

  ── Backbone de reasoning (#7)
  CHATCLI_QUALITY_REASONING_MODE       : auto
  CHATCLI_QUALITY_REASONING_BUDGET     : 8000
  CHATCLI_QUALITY_REASONING_AUTO_AGENTS: planner, refiner, verifier, reflexion
```

***

## Slash commands

### `/thinking` — reasoning override

<CodeGroup>
  ```bash Formas aceitas theme={"system"}
  /thinking                    # mostra estado atual
  /thinking auto               # limpa override
  /thinking off                # força no-thinking no próximo turn
  /thinking on                 # alias para /thinking high
  /thinking low|medium|high|max
  /thinking budget=N           # tier mais próximo de N tokens
  ```
</CodeGroup>

Detalhes: [#7 Reasoning Backbone](/pt/features/quality/reasoning-backbone#thinking-o-slash).

***

### `/plan` — forçar Plan-and-Solve

<CodeGroup>
  ```bash Seis formas (autocomplete via Tab) theme={"system"}
  /plan                               # arma flag; próximo /agent ou /coder usa Plan-First
  /plan <task livre>                  # arma + entra em agent mode e executa
  /plan agent <task>                  # equivalente explícito ao anterior
  /plan coder <task>                  # entra em coder mode (engenheiro de software) e executa
  /plan preview <task>                # dry-run: gera e mostra o plano SEM executar
  /plan dry <task>                    # alias de preview
  ```
</CodeGroup>

<Tip>**Fluxo recomendado para mudanças grandes:** `/plan preview <task>` → revise o plano → `/plan coder <mesma task>` para executar.</Tip>

Detalhes: [#2 Plan-and-Solve](/pt/features/quality/plan-and-solve#plan-invoca%C3%A7%C3%A3o-manual).

***

### `/refine` — Self-Refine session toggle

<CodeGroup>
  ```bash theme={"system"}
  /refine                  # estado atual
  /refine on               # liga para a sessão
  /refine off              # desliga
  /refine once|next        # liga (hoje idêntico a on)
  /refine auto|clear       # limpa override → usa /config
  ```
</CodeGroup>

Detalhes: [#5 Self-Refine](/pt/features/quality/self-refine#refine-session-toggle).

***

### `/verify` — CoVe session toggle

<CodeGroup>
  ```bash theme={"system"}
  /verify                  # estado atual
  /verify on               # liga
  /verify off              # desliga
  /verify once             # liga uma vez
  /verify auto             # limpa override
  ```
</CodeGroup>

Detalhes: [#6 CoVe](/pt/features/quality/cove#verify-session-toggle).

***

### `/reflect` — fila durável de lições

<CodeGroup>
  ```bash Persistir lição manual (sem LLM) theme={"system"}
  /reflect <texto livre da lição>
  # Ex: /reflect quando editar arquivos Go grandes use Edit, não rewrite total
  ```

  ```bash Status theme={"system"}
  /reflect                  # queue depth + DLQ size + subcommands
  ```

  ```bash Inspecionar fila theme={"system"}
  /reflect list             # pendentes + DLQ com preview
  /reflect failed           # só DLQ (com último erro)
  ```

  ```bash Operações na DLQ theme={"system"}
  /reflect retry <job-id>   # reenfileira (reseta attempts)
  /reflect purge <job-id>   # remove definitivo
  /reflect drain            # força replay do WAL
  ```
</CodeGroup>

`/reflect <texto livre>` grava direto em `memory.Fact` (categoria=`lesson`, trigger=`manual`) **sem chamada LLM**. Os subcomandos de fila (list/failed/retry/purge/drain) mostram e operam sobre triggers automáticos (erro, alucinação, baixa qualidade) que ficam em WAL esperando processamento async.

<Info>`/reflect retry ` e `/reflect purge ` têm autocomplete dinâmico: Tab puxa IDs reais da DLQ com preview da task + último erro.</Info>

Detalhes completos: [#3 Reflexion → Fila Durável](/pt/features/quality/reflexion#fila-dur-vel-wal-worker-pool-dlq).

***

## Env vars — referência completa

### Master switch

| Env var                   | Default | Valores       | Efeito                                                                                        |
| ------------------------- | ------- | ------------- | --------------------------------------------------------------------------------------------- |
| `CHATCLI_QUALITY_ENABLED` | `true`  | `true\|false` | Desligar o pipeline inteiro. `false` = `Pipeline.Run` → `agent.Execute` direto, zero overhead |

### Self-Refine (#5)

| Env var                             | Default                           | Valores       | Efeito                                   |
| ----------------------------------- | --------------------------------- | ------------- | ---------------------------------------- |
| `CHATCLI_QUALITY_REFINE_ENABLED`    | `false`                           | `true\|false` | Liga o RefineHook                        |
| `CHATCLI_QUALITY_REFINE_MAX_PASSES` | `1`                               | int ≥ 1       | Hard cap de passes                       |
| `CHATCLI_QUALITY_REFINE_MIN_BYTES`  | `200`                             | int ≥ 0       | Skip outputs menores que N bytes         |
| `CHATCLI_QUALITY_REFINE_EPSILON`    | `50`                              | int ≥ 0       | Threshold do fallback char em caracteres |
| `CHATCLI_QUALITY_REFINE_EXCLUDE`    | `formatter,deps,refiner,verifier` | CSV           | Agents que não passam por refine         |

#### Cascade semântico de convergência

| Env var                                                | Default | Valores       | Efeito                                            |
| ------------------------------------------------------ | ------- | ------------- | ------------------------------------------------- |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_ENABLED`           | `true`  | `true\|false` | Master switch do cascade (char→Jaccard→embedding) |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_EMBEDDING`         | `false` | `true\|false` | Inclui embedding scorer (opt-in — custa \$)       |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_STRICT`            | `false` | `true\|false` | Strict: recusa convergência sem embedding         |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CHAR_HIGH`         | `0.99`  | 0.0-1.0       | Short-circuit CONVERGIU no char                   |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CHAR_LOW`          | `0.3`   | 0.0-1.0       | Short-circuit DIVERGIU no char                    |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_JACCARD_HIGH`      | `0.95`  | 0.0-1.0       | Short-circuit CONVERGIU no Jaccard                |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_EMBEDDING_SIM`     | `0.92`  | 0.0-1.0       | Threshold final do embedding cosine               |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CACHE_SIZE`        | `256`   | int           | LRU cache size                                    |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CACHE_TTL_MIN`     | `5`     | int           | TTL do cache (minutos)                            |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_BREAKER_THRESHOLD` | `3`     | int           | Falhas antes do breaker abrir                     |

### CoVe (#6)

| Env var                                | Default                                 | Valores       | Efeito                             |
| -------------------------------------- | --------------------------------------- | ------------- | ---------------------------------- |
| `CHATCLI_QUALITY_VERIFY_ENABLED`       | `false`                                 | `true\|false` | Liga o VerifyHook                  |
| `CHATCLI_QUALITY_VERIFY_NUM_QUESTIONS` | `3`                                     | int 1-7       | Número de perguntas de verificação |
| `CHATCLI_QUALITY_VERIFY_REWRITE`       | `true`                                  | `true\|false` | Reescrever output em discrepância  |
| `CHATCLI_QUALITY_VERIFY_EXCLUDE`       | `formatter,deps,shell,refiner,verifier` | CSV           | Agents que não passam por verify   |

### Reflexion (#3)

| Env var                                      | Default | Valores       | Efeito                                  |
| -------------------------------------------- | ------- | ------------- | --------------------------------------- |
| `CHATCLI_QUALITY_REFLEXION_ENABLED`          | `true`  | `true\|false` | Liga o ReflexionHook                    |
| `CHATCLI_QUALITY_REFLEXION_ON_ERROR`         | `true`  | `true\|false` | Disparar em erro de worker              |
| `CHATCLI_QUALITY_REFLEXION_ON_HALLUCINATION` | `true`  | `true\|false` | Disparar em `verified_with_discrepancy` |
| `CHATCLI_QUALITY_REFLEXION_ON_LOW_QUALITY`   | `false` | `true\|false` | Disparar em `refine_low_quality`        |
| `CHATCLI_QUALITY_REFLEXION_PERSIST`          | `true`  | `true\|false` | Escrever em memory.Fact                 |

#### Fila durável (WAL + worker pool + DLQ)

| Env var                                         | Default | Valores       | Efeito                                                   |
| ----------------------------------------------- | ------- | ------------- | -------------------------------------------------------- |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_ENABLED`       | `true`  | `true\|false` | Liga a fila (default). `false` = modo legado (goroutine) |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_WORKERS`       | `2`     | int ≥ 1       | Workers processando em paralelo                          |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_CAPACITY`      | `1000`  | int           | Cap in-memory                                            |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_DROP_OLDEST`   | `false` | `true\|false` | `true` = drop oldest; `false` = block                    |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_BLOCK_TIMEOUT` | `5s`    | duração       | Timeout do Enqueue com fila cheia                        |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_MAX_ATTEMPTS`  | `5`     | int ≥ 1       | Retries totais                                           |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_INITIAL_DELAY` | `1s`    | duração       | Primeiro retry delay                                     |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_MAX_DELAY`     | `5m`    | duração       | Cap no backoff exponencial                               |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_JITTER`        | `0.2`   | 0.0-0.5       | Jitter fracionário                                       |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_JOB_TIMEOUT`   | `2m`    | duração       | Timeout per-job                                          |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_STALE_AFTER`   | `168h`  | duração       | Records velhos descartados no replay                     |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_BASE_DIR`      | —       | path          | Override do diretório da fila                            |

### Plan-and-Solve (#2)

| Env var                                | Default | Valores             | Efeito                          |
| -------------------------------------- | ------- | ------------------- | ------------------------------- |
| `CHATCLI_QUALITY_PLAN_FIRST_MODE`      | `auto`  | `off\|auto\|always` | Quando disparar                 |
| `CHATCLI_QUALITY_PLAN_FIRST_THRESHOLD` | `6`     | int 0-10            | Score mínimo para auto disparar |

### RAG + HyDE (#4)

| Env var                             | Default | Valores       | Efeito                            |
| ----------------------------------- | ------- | ------------- | --------------------------------- |
| `CHATCLI_QUALITY_HYDE_ENABLED`      | `false` | `true\|false` | Liga phase 3a (keyword expansion) |
| `CHATCLI_QUALITY_HYDE_USE_VECTORS`  | `false` | `true\|false` | Liga phase 3b (vector search)     |
| `CHATCLI_QUALITY_HYDE_NUM_KEYWORDS` | `5`     | int ≥ 1       | Cap de keywords da hipótese       |

### Embedding providers (usado por HyDE 3b)

| Env var                                                           | Default               | Valores                                  | Efeito                                                                                                                                                                                                       |
| ----------------------------------------------------------------- | --------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CHATCLI_EMBED_PROVIDER`                                          | `null`                | `voyage` / `openai` / `bedrock` / `null` | Escolhe o backend de embeddings                                                                                                                                                                              |
| `CHATCLI_EMBED_MODEL`                                             | provider default      | string                                   | Voyage: `voyage-3`. OpenAI: `text-embedding-3-small` / `-large`. Bedrock: `amazon.titan-embed-text-v2:0` (default), `amazon.titan-embed-text-v1`, `cohere.embed-english-v3`, `cohere.embed-multilingual-v3`. |
| `CHATCLI_EMBED_DIMENSIONS`                                        | nativa do modelo      | int                                      | OpenAI: trunca via Matryoshka (`text-embedding-3-small`=1536, `-large`=3072 nativo). Bedrock Titan v2: aceita 256 / 512 / 1024 (rejeita outros). Bedrock Titan v1 / Cohere v3: dimensão fixa, ignorada.      |
| `VOYAGE_API_KEY`                                                  | —                     | string                                   | Necessário para `provider=voyage`                                                                                                                                                                            |
| `OPENAI_API_KEY`                                                  | —                     | string                                   | Necessário para `provider=openai` (usa a mesma chave do chat)                                                                                                                                                |
| `BEDROCK_REGION` / `AWS_REGION` / `AWS_PROFILE` / credenciais AWS | conforme chat Bedrock | —                                        | Necessárias para `provider=bedrock` — reusa a mesma cadeia da feature [AWS Bedrock](/pt/features/bedrock) (IAM role, SSO, assume-role, profile).                                                             |

<Tip>
  **Bedrock embeddings** suportam Titan (single-text por chamada — paralelizado com pool de 8 workers internamente) e Cohere v3 (batch nativo). A dispatch entre famílias é auto pelo prefixo do model id. Veja [RAG + HyDE](/pt/features/quality/rag-hyde) para arquitetura completa.
</Tip>

### Reasoning Backbone (#7)

| Env var                                 | Default                              | Valores         | Efeito                                                      |
| --------------------------------------- | ------------------------------------ | --------------- | ----------------------------------------------------------- |
| `CHATCLI_QUALITY_REASONING_MODE`        | `auto`                               | `off\|auto\|on` | Política de auto-attach                                     |
| `CHATCLI_QUALITY_REASONING_BUDGET`      | `8000`                               | int (tokens)    | Budget de thinking (Anthropic); mapeado para tier na OpenAI |
| `CHATCLI_QUALITY_REASONING_AUTO_AGENTS` | `planner,refiner,verifier,reflexion` | CSV             | Lista para mode=auto                                        |

### Overrides por agent (aplicam a qualquer agent built-in)

| Env var                       | Efeito                                       |
| ----------------------------- | -------------------------------------------- |
| `CHATCLI_AGENT_<NAME>_MODEL`  | Força modelo específico para aquele agent    |
| `CHATCLI_AGENT_<NAME>_EFFORT` | Força effort tier (`low\|medium\|high\|max`) |

`<NAME>` é o nome em uppercase. Para os novos: `REFINER`, `VERIFIER`.

```bash theme={"system"}
# Exemplos
export CHATCLI_AGENT_REFINER_MODEL="claude-haiku-4-5"
export CHATCLI_AGENT_VERIFIER_MODEL="claude-opus-4-8"
export CHATCLI_AGENT_VERIFIER_EFFORT="max"
```

***

## Presets recomendados

<Tabs>
  <Tab title="Dev barato (default)">
    ```bash theme={"system"}
    # Sem ajustes: chatcli out-of-the-box já é barato
    # ReAct + Reasoning auto para Planner + Reflexion on (só em erros)
    ```

    **Custo extra por turn**: zero normalmente; +1 LLM call em erros raros.
  </Tab>

  <Tab title="Code review rigoroso">
    ```bash theme={"system"}
    export CHATCLI_QUALITY_REFINE_ENABLED=true
    export CHATCLI_QUALITY_REFINE_MAX_PASSES=2
    export CHATCLI_QUALITY_VERIFY_ENABLED=true
    export CHATCLI_QUALITY_VERIFY_NUM_QUESTIONS=5
    ```

    **Custo extra**: +3-4 calls por worker com output não-mecânico. Use em PR reviews críticos.
  </Tab>

  <Tab title="Docs técnicas">
    ```bash theme={"system"}
    export CHATCLI_QUALITY_REFINE_ENABLED=true
    export CHATCLI_QUALITY_VERIFY_ENABLED=true
    export CHATCLI_QUALITY_HYDE_ENABLED=true
    # Opcional: HyDE vectors para recall máximo
    export CHATCLI_QUALITY_HYDE_USE_VECTORS=true

    # Escolha um provider de embeddings (qualquer um destes funciona):
    # — Voyage (recomendado pela Anthropic)
    export CHATCLI_EMBED_PROVIDER=voyage
    export VOYAGE_API_KEY=pa-...

    # — OpenAI (se já tem OPENAI_API_KEY no ambiente)
    # export CHATCLI_EMBED_PROVIDER=openai

    # — Bedrock (mesma cadeia AWS do chat, sem nova API key)
    # export CHATCLI_EMBED_PROVIDER=bedrock
    # export CHATCLI_EMBED_MODEL=amazon.titan-embed-text-v2:0
    # export BEDROCK_REGION=us-east-1
    ```

    **Custo extra**: +1 HyDE hypothesis + refine + verify por doc geração. Output polido e factualmente checado.
  </Tab>

  <Tab title="Incident investigation">
    ```bash theme={"system"}
    export CHATCLI_QUALITY_REASONING_MODE=on
    export CHATCLI_QUALITY_REASONING_BUDGET=16384
    export CHATCLI_QUALITY_REFLEXION_ON_LOW_QUALITY=true
    ```

    **Custo extra**: thinking máximo em todos agents + lesson generation generosa. Use em root-cause analysis.
  </Tab>

  <Tab title="Autopilot batch">
    ```bash theme={"system"}
    export CHATCLI_QUALITY_PLAN_FIRST_MODE=always
    export CHATCLI_QUALITY_REFINE_ENABLED=true
    export CHATCLI_QUALITY_VERIFY_ENABLED=true
    export CHATCLI_QUALITY_REASONING_MODE=on
    ```

    **Custo extra**: todos os padrões ligados sempre. Use em workflows sem user na frente (cron, CI).
  </Tab>
</Tabs>

***

## Desligar tudo

Se algo quebra em produção e você precisa voltar ao comportamento pré-pipeline instantaneamente:

```bash theme={"system"}
export CHATCLI_QUALITY_ENABLED=false
```

Isso faz `Pipeline.Run` degenerar em `return agent.Execute(...)` — **byte-identical** ao chatcli pré-PR. Zero hooks, zero reasoning auto-attach, zero HyDE.

<Tip>O master switch é a saída de emergência. Os toggles individuais são para afinar cenários; o master é para rollback.</Tip>

***

## Interação com outras configs

O harness/pipeline de qualidade não conflita com, nem substitui:

| Feature                            | Relação                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| Skills (com frontmatter `effort:`) | Ganha de `applyAutoReasoning` (skill hint já no ctx)                         |
| Personas (custom agents)           | Podem ter `effort:` no `.md`; override por agente continua funcionando       |
| Multi-agent orchestration          | Dispatcher continua idêntico; pipeline só envolve cada worker                |
| Policy (CODER policy rules)        | Aplicada dentro do worker, independente de refine/verify/reflexion           |
| MCP tools                          | Resultado de MCP tools passa pelo pipeline como qualquer outro worker output |

***

## Leia também

<CardGroup cols={2}>
  <Card title="Visão Geral dos 7 padrões" icon="sparkles" href="/pt/features/quality/overview">
    Volte ao hub.
  </Card>

  <Card title="Environment Variables (completo)" icon="key" href="/pt/reference/environment-variables">
    Toda a matriz de env vars do ChatCLI.
  </Card>

  <Card title="Command Reference" icon="terminal" href="/pt/reference/command-reference">
    Todos os slashes.
  </Card>

  <Card title="/config (hierárquico)" icon="gears" href="/pt/features/config-migration">
    Como `/config <section>` foi estruturado.
  </Card>
</CardGroup>