cc-viewer 1.6.182 → 1.6.183

package/concepts/pt-BR/Tool-Bash.md

@@ -1,167 +1,39 @@
 # Bash
 
-## Definição
+Executa um comando de shell dentro de um diretório de trabalho persistente e retorna seu stdout/stderr. Melhor reservar para operações que nenhuma ferramenta dedicada do Claude Code consegue expressar, como executar git, npm, docker ou scripts de build.
 
-Executa comandos shell, com suporte a configuração opcional de timeout. O diretório de trabalho persiste entre comandos, mas o estado do shell (variáveis de ambiente, etc.) não persiste.
+## Quando usar
 
-## Parâmetros
-
-| Parâmetro | Tipo | Obrigatório | Descrição |
-|------|------|------|------|
-| `command` | string | Sim | Comando bash a ser executado |
-| `description` | string | Não | Descrição curta do comando |
-| `timeout` | number | Não | Timeout em milissegundos, máximo 600000, padrão 120000 |
-| `run_in_background` | boolean | Não | Se deve executar em segundo plano |
-
-## Cenários de Uso
-
-**Adequado para:**
-- Operações git (commit, push, branch, etc.)
-- Comandos de gerenciamento de pacotes como npm/yarn
-- Operações docker
-- Comandos de compilação e build
-- Listar conteúdo de diretórios (`ls`)
-- Outros comandos de sistema que requerem execução shell
-
-**Não adequado para:**
-- Ler arquivos — deve usar Read
-- Buscar nomes de arquivo — deve usar Glob
-- Buscar conteúdo de arquivo — deve usar Grep
-- Editar arquivos — deve usar Edit
-- Escrever arquivos — deve usar Write
-- Exibir informações ao usuário — exibir diretamente no texto da resposta
-- Processos de longa duração (dev server, modo watch) — recomendar que o usuário execute manualmente
-
-## Observações
-
-- Caminhos com espaços devem ser envolvidos em aspas duplas
-- Saída acima de 30000 caracteres será truncada
-- Comandos em segundo plano obtêm resultados via TaskOutput
-- Prefira usar caminhos absolutos, evite `cd`
-- Comandos independentes podem invocar múltiplos Bash em paralelo
-- Comandos com dependências devem ser encadeados com `&&`
-- O ambiente shell é inicializado a partir do profile do usuário (bash ou zsh)
-
-## Texto original
-
-<textarea readonly>Executes a given bash command and returns its output.
-
-The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).
+- Executar operações git (`git status`, `git diff`, `git commit`, `gh pr create`)
+- Rodar gerenciadores de pacote e ferramentas de build (`npm install`, `npm run build`, `pytest`, `cargo build`)
+- Iniciar processos de longa duração (dev servers, watchers) em segundo plano com `run_in_background`
+- Invocar CLIs específicas de domínio (`docker`, `terraform`, `kubectl`, `gh`) que não têm equivalente embutido
+- Encadear passos dependentes com `&&` quando a ordem importa
 
-IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
-
- - File search: Use Glob (NOT find or ls)
- - Content search: Use Grep (NOT grep or rg)
- - Read files: Use Read (NOT cat/head/tail)
- - Edit files: Use Edit (NOT sed/awk)
- - Write files: Use Write (NOT echo >/cat <<EOF)
- - Communication: Output text directly (NOT echo/printf)
-While the Bash tool can do similar things, it’s better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
-
-# Instructions
- - If your command will create new directories or files, first use this tool to run `ls` to verify the parent directory exists and is the correct location.
- - Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
- - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.
- - You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). By default, your command will timeout after 120000ms (2 minutes).
- - You can use the `run_in_background` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter.
- - Write a clear, concise description of what your command does. For simple commands, keep it brief (5-10 words). For complex commands (piped commands, obscure flags, or anything hard to understand at a glance), include enough context so that the user can understand what your command will do.
- - When issuing multiple commands:
-  - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
-  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
-  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
-  - DO NOT use newlines to separate commands (newlines are ok in quoted strings).
- - For git commands:
-  - Prefer to create a new commit rather than amending an existing commit.
-  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
-  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
- - Avoid unnecessary `sleep` commands:
-  - Do not sleep between commands that can run immediately — just run them.
-  - If your command is long running and you would like to be notified when it finishes – simply run your command using `run_in_background`. There is no need to sleep in this case.
-  - Do not retry failing commands in a sleep loop — diagnose the root cause or consider an alternative approach.
-  - If waiting for a background task you started with `run_in_background`, you will be notified when it completes — do not poll.
-  - If you must poll an external process, use a check command (e.g. `gh run view`) rather than sleeping first.
-  - If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.
-
-# Committing changes with git
-
-Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
-
-Git Safety Protocol:
-- NEVER update the git config
-- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions. Taking unauthorized destructive actions is unhelpful and can result in lost work, so it's best to ONLY run these commands when given direct instructions 
-- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
-- NEVER run force push to main/master, warn the user if they request it
-- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
-- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add .", which can accidentally include sensitive files (.env, credentials) or large binaries
-- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive
-
-1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel, each using the Bash tool:
-  - Run a git status command to see all untracked files. IMPORTANT: Never use the -uall flag as it can cause memory issues on large repos.
-  - Run a git diff command to see both staged and unstaged changes that will be committed.
-  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
-2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
-  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
-  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
-  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
-  - Ensure it accurately reflects the changes and their purpose
-3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands:
-   - Add relevant untracked files to the staging area.
-   - Create the commit with a message ending with:
-   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
-   - Run git status after the commit completes to verify success.
-   Note: git status depends on the commit completing, so run it sequentially after the commit.
-4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
-
-Important notes:
-- NEVER run additional commands to read or explore code, besides git bash commands
-- NEVER use the TodoWrite or Agent tools
-- DO NOT push to the remote repository unless the user explicitly asks you to do so
-- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
-- IMPORTANT: Do not use --no-edit with git rebase commands, as the --no-edit flag is not a valid option for git rebase.
-- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
-- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:
-<example>
-git commit -m "$(cat <<'EOF'
-   Commit message here.
-
-   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
-   EOF
-   )"
-</example>
+## Parâmetros
 
-# Creating pull requests
-Use the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed.
+- `command` (string, obrigatório): O comando de shell exato a executar.
+- `description` (string, obrigatório): Um resumo curto em voz ativa (5-10 palavras para comandos simples; mais contexto para os com pipes ou obscuros).
+- `timeout` (number, opcional): Timeout em milissegundos, até `600000` (10 minutos). O padrão é `120000` (2 minutos).
+- `run_in_background` (boolean, opcional): Quando `true`, o comando roda desanexado e você recebe uma notificação na conclusão. Não adicione `&` por conta própria.
 
-IMPORTANT: When the user asks you to create a pull request, follow these steps carefully:
+## Exemplos
 
-1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel using the Bash tool, in order to understand the current state of the branch since it diverged from the main branch:
-   - Run a git status command to see all untracked files (never use -uall flag)
-   - Run a git diff command to see both staged and unstaged changes that will be committed
-   - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote
-   - Run a git log command and `git diff [base-branch]...HEAD` to understand the full commit history for the current branch (from the time it diverged from the base branch)
-2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request title and summary:
-   - Keep the PR title short (under 70 characters)
-   - Use the description/body for details, not the title
-3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands in parallel:
-   - Create new branch if needed
-   - Push to remote with -u flag if needed
-   - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting.
-<example>
-gh pr create --title "the pr title" --body "$(cat <<'EOF'
-## Summary
-<1-3 bullet points>
+### Exemplo 1: Inspecionar o estado do repositório antes de commitar
+Dispare `git status` e `git diff --stat` como duas chamadas `Bash` paralelas na mesma mensagem para coletar contexto rapidamente, depois monte o commit em uma chamada subsequente.
 
-## Test plan
-[Bulleted markdown checklist of TODOs for testing the pull request...]
+### Exemplo 2: Encadear passos de build dependentes
+Use uma única chamada como `npm ci && npm run build && npm test` para que cada passo só rode após o anterior ter sucesso. Use `;` apenas se intencionalmente quiser que passos posteriores rodem mesmo após falhas.
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-EOF
-)"
-</example>
+### Exemplo 3: Dev server de longa duração
+Invoque `npm run dev` com `run_in_background: true`. Você será notificado quando ele sair. Não faça polling com loops de `sleep`; diagnostique falhas em vez de repetir cegamente.
 
-Important:
-- DO NOT use the TodoWrite or Agent tools
-- Return the PR URL when you're done, so the user can see it
+## Observações
 
-# Other common operations
-- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments</textarea>
+- O diretório de trabalho persiste entre chamadas, mas o estado do shell (variáveis exportadas, funções de shell, aliases) não. Prefira caminhos absolutos e evite `cd` a menos que o usuário peça.
+- Prefira ferramentas dedicadas em vez de equivalentes via pipe no shell: `Glob` em vez de `find`/`ls`, `Grep` em vez de `grep`/`rg`, `Read` em vez de `cat`/`head`/`tail`, `Edit` em vez de `sed`/`awk`, `Write` em vez de `echo >` ou heredocs, e texto comum do assistente em vez de `echo`/`printf` para saída dirigida ao usuário.
+- Coloque entre aspas duplas qualquer caminho que contenha espaços (por exemplo `"/Users/me/My Project/file.txt"`).
+- Para comandos independentes, faça múltiplas chamadas `Bash` em paralelo dentro de uma única mensagem. Só encadeie com `&&` quando um comando depende de outro.
+- Saída acima de 30000 caracteres é truncada. Ao capturar logs grandes, redirecione para um arquivo e leia-o com a ferramenta `Read`.
+- Nunca use flags interativas como `git rebase -i` ou `git add -i`; elas não podem receber entrada através desta ferramenta.
+- Não pule git hooks (`--no-verify`, `--no-gpg-sign`) nem execute operações destrutivas (`reset --hard`, `push --force`, `clean -f`) a menos que o usuário peça explicitamente.

package/concepts/pt-BR/Tool-CronCreate.md

@@ -0,0 +1,57 @@
+# CronCreate
+
+Agenda um prompt para ser colocado na fila em um momento futuro, seja uma única vez ou de forma recorrente. Utiliza a sintaxe cron padrão de 5 campos no fuso horário local do usuário, sem necessidade de conversão de fuso horário.
+
+## Quando usar
+
+- **Lembretes de uma única vez**: Quando o usuário quer ser lembrado em um horário específico ("me lembre amanhã às 15h"). Com `recurring: false`, a tarefa é excluída automaticamente após a execução.
+- **Agendamentos recorrentes**: Quando algo precisa ser executado repetidamente ("todo dia útil às 9h", "a cada 30 minutos"). O valor padrão `recurring: true` cobre esse caso.
+- **Loops de agente autônomo**: Para construir fluxos de trabalho que se re-ativam sozinhos conforme um cronograma — por exemplo, resumos diários ou verificações periódicas de status.
+- **Tarefas duráveis**: Quando o agendamento precisa sobreviver a um reinício de sessão. Com `durable: true`, a tarefa é salva em `.claude/scheduled_tasks.json`.
+- **Horários aproximados**: Quando o usuário diz "por volta das 9h" ou "a cada hora", escolha um valor de minuto deslocado (ex.: `57 8 * * *` ou `7 * * * *`) para evitar que muitos usuários se concentrem em :00 ou :30.
+
+## Parâmetros
+
+- `cron` (string, obrigatório): Expressão cron de 5 campos no fuso horário local do usuário. Formato: `minuto hora dia-do-mês mês dia-da-semana`. Exemplo: `"0 9 * * 1-5"` significa segunda–sexta às 9:00.
+- `prompt` (string, obrigatório): O texto do prompt a ser colocado na fila quando o cron disparar — a mensagem exata que será enviada ao REPL no horário agendado.
+- `recurring` (boolean, opcional, padrão `true`): Com `true`, o job é executado a cada intervalo cron correspondente e expira automaticamente após 7 dias. Com `false`, o job é executado exatamente uma vez e então excluído — para lembretes de uma única vez.
+- `durable` (boolean, opcional, padrão `false`): Com `false`, o agendamento existe apenas na memória e é perdido ao encerrar a sessão. Com `true`, a tarefa é persistida em `.claude/scheduled_tasks.json` e sobrevive a reinicializações.
+
+## Exemplos
+
+### Exemplo 1: lembrete de uma única vez
+
+O usuário diz: "Me lembre amanhã às 14:30 de enviar o relatório semanal." Supondo que amanhã seja 21 de abril:
+
+```json
+{
+  "cron": "30 14 21 4 *",
+  "prompt": "Lembrete: envie o relatório semanal agora.",
+  "recurring": false,
+  "durable": true
+}
+```
+
+`recurring: false` garante que a tarefa se exclua após disparar. `durable: true` a mantém em caso de reinicializações anteriores.
+
+### Exemplo 2: tarefa matinal recorrente em dias úteis
+
+O usuário diz: "Todo dia útil de manhã, resuma as minhas issues abertas no GitHub."
+
+```json
+{
+  "cron": "3 9 * * 1-5",
+  "prompt": "Resuma todas as issues abertas no GitHub atribuídas a mim.",
+  "recurring": true,
+  "durable": true
+}
+```
+
+O minuto `3` em vez de `0` evita o pico de carga na hora exata. O job expira automaticamente após 7 dias.
+
+## Observações
+
+- **Expiração automática em 7 dias**: Jobs recorrentes são excluídos automaticamente após no máximo 7 dias. Para agendamentos mais longos, recrie a tarefa antes de ela expirar.
+- **Dispara apenas em repouso**: `CronCreate` coloca o prompt na fila somente quando o REPL não está processando outra consulta. Se o REPL estiver ocupado no momento do disparo, o prompt aguarda o término da consulta atual.
+- **Evite os minutos :00 e :30**: Para horários aproximados, escolha deliberadamente valores de minuto deslocados para distribuir a carga do sistema. Reserve :00/:30 apenas quando o usuário especificar esse minuto exato.
+- **Sem conversão de fuso horário**: A expressão cron é interpretada diretamente no fuso horário local do usuário. Não é necessário converter para UTC ou qualquer outro fuso.

package/concepts/pt-BR/Tool-CronDelete.md

@@ -0,0 +1,43 @@
+# CronDelete
+
+Cancela um job cron previamente agendado com `CronCreate`. Remove-o imediatamente do armazenamento de sessão em memória. Não tem efeito se o job já foi excluído automaticamente (jobs de execução única são removidos após disparar, jobs recorrentes expiram após 7 dias).
+
+## Quando usar
+
+- Um usuário solicita interromper uma tarefa agendada recorrente antes da expiração automática de 7 dias.
+- Um job de execução única não é mais necessário e deve ser cancelado antes de disparar.
+- É necessário alterar a expressão de agendamento de um job existente — excluí-lo com `CronDelete` e, em seguida, recriá-lo com `CronCreate` usando a nova expressão.
+- Limpar vários jobs desatualizados para manter o armazenamento de sessão organizado.
+
+## Parâmetros
+
+- `id` (string, obrigatório): O ID do job retornado por `CronCreate` quando o job foi criado pela primeira vez. Este valor deve corresponder exatamente; busca aproximada ou por nome não é suportada.
+
+## Exemplos
+
+### Exemplo 1: cancelar um job recorrente em execução
+
+Um job recorrente foi criado anteriormente com o ID `"cron_abc123"`. O usuário solicita sua interrupção.
+
+```
+CronDelete({ id: "cron_abc123" })
+```
+
+O job é removido do armazenamento de sessão e não será disparado novamente.
+
+### Exemplo 2: remover um job de execução única desatualizado antes de disparar
+
+Um job de execução única com ID `"cron_xyz789"` foi agendado para ser executado em 30 minutos, mas o usuário decidiu que não é mais necessário.
+
+```
+CronDelete({ id: "cron_xyz789" })
+```
+
+O job é cancelado. Nenhuma ação será executada quando o momento de disparo original chegar.
+
+## Observações
+
+- O `id` deve ser obtido do valor de retorno de `CronCreate`. Não há como buscar um job por descrição ou callback — armazene o ID caso precise cancelar mais tarde.
+- Se o job já foi excluído automaticamente (disparado como execução única, ou atingiu a expiração recorrente de 7 dias), chamar `CronDelete` com esse ID é uma operação sem efeito e não produzirá um erro.
+- `CronDelete` afeta apenas a sessão em memória atual. Se o ambiente de execução não persistir o estado do cron entre reinicializações, os jobs agendados serão perdidos na reinicialização independentemente de `CronDelete` ter sido chamado.
+- Não existe operação de exclusão em lote; cancele cada job individualmente usando seu próprio `id`.

package/concepts/pt-BR/Tool-CronList.md

@@ -0,0 +1,30 @@
+# CronList
+
+Lista todos os jobs cron agendados via `CronCreate` na sessao atual. Retorna um resumo de cada cron ativo, incluindo `id`, expressao cron, `prompt` abreviado, flag `recurring`, flag `durable` e o proximo horario de execucao.
+
+## Quando usar
+
+- Para auditar todos os jobs atualmente agendados antes de fazer alteracoes ou encerrar uma sessao.
+- Para encontrar o `id` correto de um job antes de chamar `CronDelete` para remove-lo.
+- Para depurar por que um job esperado nunca foi disparado, confirmando sua existencia e verificando o proximo horario de execucao.
+- Para confirmar que um job de execucao unica (nao recorrente) ainda nao foi disparado e permanece pendente.
+
+## Parametros
+
+Nenhum.
+
+## Exemplos
+
+### Exemplo 1: auditar todos os jobs agendados
+
+Invocar `CronList` sem argumentos para obter a lista completa de todos os jobs cron ativos. A resposta inclui para cada job seu `id`, a expressao cron que define seu agendamento, uma versao truncada do `prompt` que sera executado, se e `recurring` (recorrente), se e `durable` (persistente apos reinicializacoes) e o proximo horario de execucao agendado.
+
+### Exemplo 2: localizar o id de uma tarefa recorrente especifica
+
+Se varios jobs cron foram criados e e necessario excluir um especifico, invocar `CronList` primeiro. Percorrer a lista retornada para encontrar o job cujo resumo de `prompt` e expressao cron correspondam a tarefa a ser removida. Copiar seu `id` e passa-lo para `CronDelete`.
+
+## Observacoes
+
+- Apenas jobs criados na sessao atual sao listados, a menos que tenham sido criados com `durable: true`, o que permite que persistam apos reinicializacoes de sessao.
+- O campo `prompt` no resumo e truncado; exibe apenas o inicio do texto completo do prompt, nao o conteudo integral.
+- Jobs de execucao unica (`recurring` e `false`) que ja foram disparados sao excluidos automaticamente e nao aparecem mais na lista.

package/concepts/pt-BR/Tool-Edit.md

@@ -1,46 +1,38 @@
 # Edit
 
-## Definição
+Executa uma substituição exata de string dentro de um arquivo existente. É a forma preferida de modificar arquivos porque apenas o diff é transmitido, mantendo as edições precisas e auditáveis.
 
-Edita arquivos através de substituição exata de strings. Substitui `old_string` por `new_string` no arquivo.
+## Quando usar
 
-## Parâmetros
+- Corrigir um bug em uma única função sem reescrever o arquivo ao redor
+- Atualizar um valor de configuração, string de versão ou caminho de import
+- Renomear um símbolo ao longo de um arquivo com `replace_all`
+- Inserir um bloco próximo a um ponto de âncora (expanda `old_string` para incluir o contexto ao redor, depois forneça o texto de substituição)
+- Aplicar edições pequenas e bem delimitadas como parte de uma refatoração em múltiplos passos
 
-| Parâmetro | Tipo | Obrigatório | Descrição |
-|------|------|------|------|
-| `file_path` | string | Sim | Caminho absoluto do arquivo a ser modificado |
-| `old_string` | string | Sim | Texto original a ser substituído |
-| `new_string` | string | Sim | Novo texto após a substituição (deve ser diferente de old_string) |
-| `replace_all` | boolean | Não | Se deve substituir todas as ocorrências, padrão `false` |
+## Parâmetros
 
-## Cenários de Uso
+- `file_path` (string, obrigatório): Caminho absoluto do arquivo a modificar.
+- `old_string` (string, obrigatório): O texto exato a procurar. Deve corresponder caractere por caractere, incluindo espaços em branco e indentação.
+- `new_string` (string, obrigatório): O texto de substituição. Deve ser diferente de `old_string`.
+- `replace_all` (boolean, opcional): Quando `true`, substitui toda ocorrência de `old_string`. O padrão é `false`, que exige que a correspondência seja única.
 
-**Adequado para:**
-- Modificar trechos específicos de código em arquivos existentes
-- Corrigir bugs, atualizar lógica
-- Renomear variáveis (com `replace_all: true`)
-- Qualquer cenário que requer modificação precisa do conteúdo de um arquivo
+## Exemplos
 
-**Não adequado para:**
-- Criar novos arquivos — deve usar Write
-- Reescrita em grande escala — pode ser necessário usar Write para sobrescrever o arquivo inteiro
+### Exemplo 1: Corrigir um único ponto de chamada
+Defina `old_string` como a linha exata `const port = 3000;` e `new_string` como `const port = process.env.PORT ?? 3000;`. A correspondência é única, então `replace_all` pode permanecer no padrão.
 
-## Observações
+### Exemplo 2: Renomear um símbolo ao longo de um arquivo
+Para renomear `getUser` para `fetchUser` em todos os lugares em `api.ts`, defina `old_string: "getUser"`, `new_string: "fetchUser"` e `replace_all: true`.
 
-- Antes de usar, é obrigatório ter lido o arquivo via Read, caso contrário ocorrerá erro
-- `old_string` deve ser único no arquivo, caso contrário a edição falhará. Se não for único, forneça mais contexto para torná-lo único, ou use `replace_all`
-- Ao editar texto, deve-se manter a indentação original (tab/espaços), não incluir o prefixo de número de linha da saída do Read
-- Prefira editar arquivos existentes em vez de criar novos
-- `new_string` deve ser diferente de `old_string`
+### Exemplo 3: Desambiguar um trecho repetido
+Se `return null;` aparecer em vários ramos, amplie `old_string` para incluir contexto circundante (por exemplo a linha `if` anterior) para que a correspondência seja única. Caso contrário, a ferramenta retorna erro em vez de adivinhar.
 
-## Texto original
-
-<textarea readonly>Performs exact string replacements in files.
+## Observações
 
-Usage:
-- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. 
-- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
-- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.</textarea>
+- Você deve chamar `Read` no arquivo pelo menos uma vez na sessão atual antes que `Edit` aceite mudanças. Prefixos de número de linha da saída do `Read` não fazem parte do conteúdo do arquivo; não os inclua em `old_string` ou `new_string`.
+- O espaço em branco deve corresponder exatamente. Preste atenção em tabulações versus espaços e espaços finais, especialmente em YAML, Makefiles e Python.
+- Se `old_string` não for único e `replace_all` for `false`, a edição falha. Expanda o contexto ou habilite `replace_all`.
+- Prefira `Edit` em vez de `Write` sempre que o arquivo já existe; `Write` sobrescreve o arquivo inteiro e perde conteúdo não relacionado se você não tiver cuidado.
+- Para múltiplas edições não relacionadas no mesmo arquivo, faça várias chamadas `Edit` em sequência em vez de uma grande substituição frágil.
+- Evite introduzir emoji, texto de marketing ou blocos de documentação não solicitados ao editar arquivos de código.

package/concepts/pt-BR/Tool-EnterPlanMode.md

@@ -1,128 +1,35 @@
 # EnterPlanMode
 
-## Definição
+Coloca a sessão em modo de plano, uma fase de exploração somente leitura em que o assistente investiga o codebase e elabora um plano de implementação concreto para o usuário aprovar antes que qualquer arquivo seja modificado.
 
-Alterna o Claude Code para o modo de planejamento, usado para explorar a base de código e projetar um plano antes da implementação.
+## Quando usar
+
+- O usuário pede uma mudança não trivial que abrange múltiplos arquivos ou subsistemas.
+- Os requisitos são ambíguos e o assistente precisa ler código antes de se comprometer com uma abordagem.
+- Uma refatoração, migração ou atualização de dependência é proposta e o raio de impacto não está claro.
+- O usuário diz explicitamente "planeje isso", "vamos planejar primeiro" ou solicita uma revisão de design.
+- O risco é alto o suficiente para que ir direto para edições possa desperdiçar trabalho ou danificar o estado.
 
 ## Parâmetros
 
-Sem parâmetros.
+Nenhum. `EnterPlanMode` não recebe argumentos — invoque-o com um objeto de parâmetros vazio.
 
-## Cenários de Uso
+## Exemplos
 
-**Adequado para:**
-- Implementação de novas funcionalidades — requer decisões de arquitetura
-- Existem múltiplas abordagens viáveis — requer escolha do usuário
-- Modificações de código afetam comportamento ou estrutura existente
-- Alterações em múltiplos arquivos — possivelmente envolvendo 2-3 ou mais arquivos
-- Requisitos não claros — necessário explorar antes de entender o escopo
-- Preferências do usuário são importantes — a implementação pode ter múltiplas direções razoáveis
+### Exemplo 1: Pedido grande de funcionalidade
 
-**Não adequado para:**
-- Correções de uma ou poucas linhas (erros de digitação, bugs óbvios)
-- O usuário já forneceu instruções muito específicas
-- Tarefas puramente de pesquisa/exploração — deve usar Task (tipo Explore)
+O usuário pede: "Adicione SSO via Okta ao painel de admin." O assistente chama `EnterPlanMode`, depois passa várias rodadas lendo middleware de autenticação, armazenamento de sessão, guards de rota e UI de login existente. Ele escreve um plano descrevendo as mudanças necessárias, passos de migração e cobertura de testes, depois submete via `ExitPlanMode` para aprovação.
 
-## Comportamento no Modo de Planejamento
+### Exemplo 2: Refatoração arriscada
 
-Após entrar no modo de planejamento, o Claude Code irá:
-1. Usar ferramentas Glob, Grep, Read para explorar profundamente a base de código
-2. Compreender padrões e arquitetura existentes
-3. Projetar o plano de implementação
-4. Submeter o plano para aprovação do usuário
-5. Usar AskUserQuestion se necessário para esclarecimentos
-6. Sair via ExitPlanMode quando o plano estiver pronto
+O usuário diz: "Converta os controllers REST para tRPC." O assistente entra em modo de plano, examina cada controller, cataloga o contrato público, lista fases de rollout (shim, dual-read, cutover) e propõe um plano de sequenciamento antes de tocar em qualquer arquivo.
 
 ## Observações
 
-- Esta ferramenta requer consentimento do usuário para entrar no modo de planejamento
-- Se não tiver certeza se o planejamento é necessário, prefira planejar — alinhar antecipadamente é melhor que retrabalho
-
-## Texto original
-
-<textarea readonly>Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
-
-## When to Use This Tool
-
-**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
-
-1. **New Feature Implementation**: Adding meaningful new functionality
-   - Example: "Add a logout button" - where should it go? What should happen on click?
-   - Example: "Add form validation" - what rules? What error messages?
-
-2. **Multiple Valid Approaches**: The task can be solved in several different ways
-   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
-   - Example: "Improve performance" - many optimization strategies possible
-
-3. **Code Modifications**: Changes that affect existing behavior or structure
-   - Example: "Update the login flow" - what exactly should change?
-   - Example: "Refactor this component" - what's the target architecture?
-
-4. **Architectural Decisions**: The task requires choosing between patterns or technologies
-   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
-   - Example: "Implement state management" - Redux vs Context vs custom solution
-
-5. **Multi-File Changes**: The task will likely touch more than 2-3 files
-   - Example: "Refactor the authentication system"
-   - Example: "Add a new API endpoint with tests"
-
-6. **Unclear Requirements**: You need to explore before understanding the full scope
-   - Example: "Make the app faster" - need to profile and identify bottlenecks
-   - Example: "Fix the bug in checkout" - need to investigate root cause
-
-7. **User Preferences Matter**: The implementation could reasonably go multiple ways
-   - If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead
-   - Plan mode lets you explore first, then present options with context
-
-## When NOT to Use This Tool
-
-Only skip EnterPlanMode for simple tasks:
-- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
-- Adding a single function with clear requirements
-- Tasks where the user has given very specific, detailed instructions
-- Pure research/exploration tasks (use the Agent tool with explore agent instead)
-
-## What Happens in Plan Mode
-
-In plan mode, you'll:
-1. Thoroughly explore the codebase using Glob, Grep, and Read tools
-2. Understand existing patterns and architecture
-3. Design an implementation approach
-4. Present your plan to the user for approval
-5. Use AskUserQuestion if you need to clarify approaches
-6. Exit plan mode with ExitPlanMode when ready to implement
-
-## Examples
-
-### GOOD - Use EnterPlanMode:
-User: "Add user authentication to the app"
-- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
-
-User: "Optimize the database queries"
-- Multiple approaches possible, need to profile first, significant impact
-
-User: "Implement dark mode"
-- Architectural decision on theme system, affects many components
-
-User: "Add a delete button to the user profile"
-- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
-
-User: "Update the error handling in the API"
-- Affects multiple files, user should approve the approach
-
-### BAD - Don't use EnterPlanMode:
-User: "Fix the typo in the README"
-- Straightforward, no planning needed
-
-User: "Add a console.log to debug this function"
-- Simple, obvious implementation
-
-User: "What files handle routing?"
-- Research task, not implementation planning
-
-## Important Notes
-
-- This tool REQUIRES user approval - they must consent to entering plan mode
-- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
-- Users appreciate being consulted before significant changes are made to their codebase
-</textarea>
+- O modo de plano é somente leitura por contrato. Enquanto está nele, o assistente não deve executar `Edit`, `Write`, `NotebookEdit` ou qualquer comando de shell que mute estado. Use apenas `Read`, `Grep`, `Glob` e comandos `Bash` não destrutivos.
+- Não entre em modo de plano para edições triviais de uma linha, perguntas puramente de pesquisa ou tarefas em que o usuário já especificou a mudança em detalhes completos. O overhead prejudica mais do que ajuda.
+- No modo Auto, o modo de plano é desencorajado a menos que o usuário peça explicitamente — o modo Auto prefere ação em vez de planejamento antecipado.
+- Use o modo de plano para reduzir correções de rumo em trabalho caro. Um plano de cinco minutos muitas vezes economiza uma hora de edições mal direcionadas.
+- Uma vez no modo de plano, foque a investigação nas partes do sistema que realmente mudarão. Evite passeios exaustivos pelo repositório não relacionados à tarefa em questão.
+- O plano em si deve ser gravado no disco no caminho que o harness espera para que `ExitPlanMode` possa submetê-lo. O plano deve conter caminhos de arquivos concretos, nomes de funções e passos de verificação, não intenções vagas.
+- O usuário pode rejeitar o plano e pedir revisões. Itere dentro do modo de plano até que o plano seja aceito; só então saia.