cx-viewer 1.0.0

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

@@ -0,0 +1,32 @@
+# TaskStop
+
+## Definição
+
+Para uma tarefa em segundo plano que está em execução.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `task_id` | string | Não | ID da tarefa em segundo plano a parar |
+| `shell_id` | string | Não | Descontinuado, use `task_id` em vez disso |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Encerrar tarefas de longa duração que não são mais necessárias
+- Cancelar tarefas em segundo plano iniciadas por engano
+
+## Observações
+
+- Retorna status de sucesso ou falha
+- O parâmetro `shell_id` está descontinuado, deve-se usar `task_id`
+
+## Texto original
+
+<textarea readonly>
+- Stops a running background task by its ID
+- Takes a task_id parameter identifying the task to stop
+- Returns a success or failure status
+- Use this tool when you need to terminate a long-running task
+</textarea>

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

@@ -0,0 +1,123 @@
+# TaskUpdate
+
+## Definição
+
+Atualiza o status, conteúdo ou dependências de uma tarefa na lista de tarefas.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `taskId` | string | Sim | ID da tarefa a atualizar |
+| `status` | enum | Não | Novo status: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | Não | Novo título |
+| `description` | string | Não | Nova descrição |
+| `activeForm` | string | Não | Texto no gerúndio exibido quando em andamento |
+| `owner` | string | Não | Novo responsável pela tarefa (nome do agent) |
+| `metadata` | object | Não | Metadados a mesclar (definir como null para excluir chave) |
+| `addBlocks` | string[] | Não | Lista de IDs de tarefas bloqueadas por esta tarefa |
+| `addBlockedBy` | string[] | Não | Lista de IDs de tarefas pré-requisito que bloqueiam esta tarefa |
+
+## Fluxo de Status
+
+```
+pending → in_progress → completed
+```
+
+`deleted` pode ser atingido a partir de qualquer status, removendo permanentemente a tarefa.
+
+## Cenários de Uso
+
+**Adequado para:**
+- Marcar tarefa como `in_progress` ao iniciar o trabalho
+- Marcar tarefa como `completed` após concluir o trabalho
+- Definir dependências entre tarefas
+- Atualizar conteúdo da tarefa quando requisitos mudam
+
+**Regras importantes:**
+- Só marcar como `completed` quando a tarefa estiver totalmente concluída
+- Manter como `in_progress` ao encontrar erros ou bloqueios
+- Não marcar como `completed` quando testes falham, implementação está incompleta ou há erros não resolvidos
+
+## Observações
+
+- Antes de atualizar, deve-se obter o status mais recente da tarefa via TaskGet para evitar dados desatualizados
+- Após concluir uma tarefa, chamar TaskList para encontrar a próxima tarefa disponível
+
+## Texto original
+
+<textarea readonly>Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to `deleted` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: `pending` → `in_progress` → `completed`
+
+Use `deleted` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using `TaskGet` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+```json
+{"taskId": "1", "status": "in_progress"}
+```
+
+Mark task as completed after finishing work:
+```json
+{"taskId": "1", "status": "completed"}
+```
+
+Delete a task:
+```json
+{"taskId": "1", "status": "deleted"}
+```
+
+Claim a task by setting owner:
+```json
+{"taskId": "1", "owner": "my-name"}
+```
+
+Set up task dependencies:
+```json
+{"taskId": "2", "addBlockedBy": ["1"]}
+```
+</textarea>

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

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## Definição
+
+Cria uma nova equipe para coordenar múltiplos agents trabalhando em um projeto. As equipes permitem execução paralela de tarefas por meio de uma lista de tarefas compartilhada e troca de mensagens entre agents.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|-----------|------|-------------|-----------|
+| `team_name` | string | Sim | Nome para a nova equipe |
+| `description` | string | Não | Descrição / propósito da equipe |
+| `agent_type` | string | Não | Tipo / papel do líder da equipe |
+
+## O que é criado
+
+- **Arquivo de configuração da equipe**: `~/.claude/teams/{team-name}/config.json` — armazena lista de membros e metadados
+- **Diretório da lista de tarefas**: `~/.claude/tasks/{team-name}/` — lista de tarefas compartilhada para todos os integrantes
+
+Equipes têm correspondência 1:1 com listas de tarefas.
+
+## Fluxo de trabalho da equipe
+
+1. **TeamCreate** — criar a equipe e sua lista de tarefas
+2. **TaskCreate** — definir tarefas para a equipe
+3. **Agent** (com `team_name` + `name`) — iniciar integrantes que entram na equipe
+4. **TaskUpdate** — atribuir tarefas aos integrantes via `owner`
+5. Integrantes trabalham nas tarefas e se comunicam via **SendMessage**
+6. Encerrar integrantes ao concluir, depois **TeamDelete** para limpeza
+
+## Ferramentas relacionadas
+
+| Ferramenta | Finalidade |
+|------------|------------|
+| `TeamDelete` | Remover equipe e diretórios de tarefas |
+| `SendMessage` | Comunicação entre agents dentro da equipe |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Gerenciar a lista de tarefas compartilhada |
+| `Agent` | Iniciar integrantes que entram na equipe |

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

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## Definição
+
+Remove uma equipe e seus diretórios de tarefas associados quando o trabalho de colaboração multi-agent é concluído. Esta é a contrapartida de limpeza do TeamCreate.
+
+## Comportamento
+
+- Remove o diretório da equipe: `~/.claude/teams/{team-name}/`
+- Remove o diretório de tarefas: `~/.claude/tasks/{team-name}/`
+- Limpa o contexto da equipe da sessão atual
+
+**Importante**: TeamDelete falhará se a equipe ainda tiver integrantes ativos. Os integrantes devem ser encerrados graciosamente primeiro via solicitações de shutdown do SendMessage.
+
+## Uso típico
+
+TeamDelete é chamado no final de um fluxo de trabalho de equipe:
+
+1. Todas as tarefas estão concluídas
+2. Integrantes são encerrados via `SendMessage` com `shutdown_request`
+3. **TeamDelete** remove os diretórios de equipe e tarefas
+
+## Ferramentas relacionadas
+
+| Ferramenta | Finalidade |
+|------------|------------|
+| `TeamCreate` | Criar uma nova equipe e sua lista de tarefas |
+| `SendMessage` | Comunicar com integrantes / enviar solicitações de shutdown |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Gerenciar a lista de tarefas compartilhada |
+| `Agent` | Iniciar integrantes que entram na equipe |

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

@@ -0,0 +1,55 @@
+# WebFetch
+
+## Definição
+
+Busca o conteúdo de uma URL especificada, converte HTML para markdown e processa o conteúdo usando um modelo de IA com base no prompt.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `url` | string (URI) | Sim | URL completa a ser buscada |
+| `prompt` | string | Sim | Descreve que informação extrair da página |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Obter conteúdo de páginas web públicas
+- Consultar documentação online
+- Extrair informações específicas de páginas web
+
+**Não adequado para:**
+- URLs que requerem autenticação (Google Docs, Confluence, Jira, GitHub, etc.) — deve primeiro procurar ferramentas MCP dedicadas
+- URLs do GitHub — prefira usar o CLI `gh`
+
+## Observações
+
+- A URL deve ser uma URL válida completa
+- HTTP é automaticamente atualizado para HTTPS
+- Resultados podem ser resumidos quando o conteúdo é muito grande
+- Inclui cache com auto-limpeza de 15 minutos
+- Quando a URL redireciona para um host diferente, a ferramenta retorna a URL de redirecionamento, sendo necessário fazer nova requisição com a nova URL
+- Se houver uma ferramenta web fetch fornecida por MCP disponível, prefira usá-la
+
+## Texto original
+
+<textarea readonly>IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, you MUST use ToolSearch first to find a specialized tool that provides authenticated access.
+
+- Fetches content from a specified URL and processes it using an AI model
+- Takes a URL and a prompt as input
+- Fetches the URL content, converts HTML to markdown
+- Processes the content with the prompt using a small, fast model
+- Returns the model's response about the content
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - The prompt should describe what information you want to extract from the page
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large
+  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
+  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
+  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).
+</textarea>

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

@@ -0,0 +1,58 @@
+# WebSearch
+
+## Definição
+
+Executa consultas em mecanismo de busca, retornando resultados de pesquisa para obter informações atualizadas.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `query` | string | Sim | Consulta de busca (mínimo 2 caracteres) |
+| `allowed_domains` | string[] | Não | Incluir apenas resultados destes domínios |
+| `blocked_domains` | string[] | Não | Excluir resultados destes domínios |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Obter informações atualizadas além da data de corte do conhecimento do modelo
+- Buscar eventos atuais e dados recentes
+- Pesquisar documentação técnica mais recente
+
+## Observações
+
+- Os resultados de busca são retornados em formato de hyperlinks markdown
+- Após o uso, é obrigatório incluir uma seção "Sources:" no final da resposta, listando as URLs relevantes
+- Suporta filtragem de domínios (inclusão/exclusão)
+- A consulta de busca deve usar o ano atual
+- Disponível apenas nos EUA
+
+## Texto original
+
+<textarea readonly>
+- Allows Claude to search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond Claude's knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+  - Example format:
+
+    [Your answer here]
+
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+
+Usage notes:
+  - Domain filtering is supported to include or block specific websites
+  - Web search is only available in the US
+
+IMPORTANT - Use the correct year in search queries:
+  - The current month is March 2026. You MUST use this year when searching for recent information, documentation, or current events.
+  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
+</textarea>

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

@@ -0,0 +1,39 @@
+# Write
+
+## Definição
+
+Escreve conteúdo no sistema de arquivos local. Se o arquivo já existir, será sobrescrito.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `file_path` | string | Sim | Caminho absoluto do arquivo (deve ser caminho absoluto) |
+| `content` | string | Sim | Conteúdo a ser escrito |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Criar novos arquivos
+- Quando é necessário reescrever completamente o conteúdo do arquivo
+
+**Não adequado para:**
+- Modificar conteúdo parcial de um arquivo — deve usar Edit
+- Não deve criar proativamente arquivos de documentação (*.md) ou README, a menos que o usuário solicite explicitamente
+
+## Observações
+
+- Se o arquivo de destino já existir, é obrigatório lê-lo primeiro via Read, caso contrário falhará
+- Sobrescreve todo o conteúdo do arquivo existente
+- Prefira usar Edit para editar arquivos existentes; Write é apenas para criar novos arquivos ou reescrita completa
+
+## Texto original
+
+<textarea readonly>Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.</textarea>

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

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## Definição
+
+Executa código Python no kernel Jupyter do arquivo notebook atual.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `code` | string | Sim | Código Python a ser executado |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Executar código em ambiente Jupyter notebook
+- Testar trechos de código
+- Análise de dados e cálculos
+
+**Não adequado para:**
+- Execução de código fora do ambiente Jupyter — deve usar Bash
+- Modificar arquivos — deve usar Edit ou Write
+
+## Observações
+
+- Esta é uma ferramenta MCP (Model Context Protocol), fornecida pela integração com IDE
+- O código é executado no kernel Jupyter atual, o estado persiste entre chamadas
+- A menos que o usuário solicite explicitamente, deve-se evitar declarar variáveis ou modificar o estado do kernel
+- O estado é perdido após reiniciar o kernel
+
+## Texto original
+
+<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
+    
+    All code will be executed in the current Jupyter kernel.
+    
+    Avoid declaring variables or modifying the state of the kernel unless the user
+    explicitly asks for it.
+    
+    Any code executed will persist across calls to this tool, unless the kernel
+    has been restarted.</textarea>

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

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definição
+
+Obtém informações de diagnóstico de linguagem do VS Code, incluindo erros de sintaxe, erros de tipo, avisos de lint, etc.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `uri` | string | Não | URI do arquivo. Se não fornecido, obtém diagnósticos de todos os arquivos |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Verificar problemas semânticos como sintaxe, tipos e lint no código
+- Verificar se novas edições introduziram erros
+- Substituir comandos Bash para verificar qualidade do código
+
+**Não adequado para:**
+- Executar testes — deve usar Bash
+- Verificar erros de runtime — deve usar Bash para executar o código
+
+## Observações
+
+- Esta é uma ferramenta MCP (Model Context Protocol), fornecida pela integração com IDE
+- Disponível apenas em ambiente VS Code / IDE
+- Prefira usar esta ferramenta em vez de comandos Bash para verificar problemas no código
+
+## Texto original
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/pt-BR/Tools.md

@@ -0,0 +1,67 @@
+# Visão Geral das Ferramentas do Claude Code
+
+O Claude Code fornece ao modelo um conjunto de ferramentas integradas através do mecanismo tool_use da API da Anthropic. O array `tools` de cada requisição MainAgent contém as definições completas em JSON Schema dessas ferramentas, e o modelo as invoca através de content blocks `tool_use` na resposta.
+
+A seguir está o índice categorizado de todas as ferramentas.
+
+## Sistema de Agents
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Task](Tool-Task.md) | Iniciar um sub-agent (SubAgent) para processar tarefas complexas de múltiplas etapas |
+| [TaskOutput](Tool-TaskOutput.md) | Obter a saída de tarefas em segundo plano |
+| [TaskStop](Tool-TaskStop.md) | Parar uma tarefa em segundo plano em execução |
+| [TaskCreate](Tool-TaskCreate.md) | Criar uma entrada na lista de tarefas estruturada |
+| [TaskGet](Tool-TaskGet.md) | Obter detalhes de uma tarefa |
+| [TaskUpdate](Tool-TaskUpdate.md) | Atualizar status, dependências, etc. de uma tarefa |
+| [TaskList](Tool-TaskList.md) | Listar todas as tarefas |
+
+## Operações de Arquivo
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Read](Tool-Read.md) | Ler conteúdo de arquivo (suporta texto, imagens, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Editar arquivo através de substituição exata de string |
+| [Write](Tool-Write.md) | Escrever ou sobrescrever arquivo |
+| [NotebookEdit](Tool-NotebookEdit.md) | Editar células de Jupyter notebook |
+
+## Busca
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Glob](Tool-Glob.md) | Buscar arquivos por padrão de nome de arquivo |
+| [Grep](Tool-Grep.md) | Busca de conteúdo de arquivo baseada em ripgrep |
+
+## Terminal
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Bash](Tool-Bash.md) | Executar comandos shell |
+
+## Web
+
+| Ferramenta | Finalidade |
+|------|------|
+| [WebFetch](Tool-WebFetch.md) | Buscar conteúdo de página web e processar com IA |
+| [WebSearch](Tool-WebSearch.md) | Consulta em mecanismo de busca |
+
+## Planejamento e Interação
+
+| Ferramenta | Finalidade |
+|------|------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Entrar no modo de planejamento para projetar plano de implementação |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Sair do modo de planejamento e submeter plano para aprovação do usuário |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Fazer perguntas ao usuário para obter esclarecimentos ou decisões |
+
+## Extensões
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Skill](Tool-Skill.md) | Executar skill (slash command) |
+
+## Integração com IDE
+
+| Ferramenta | Finalidade |
+|------|------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Obter informações de diagnóstico de linguagem do VS Code |
+| [executeCode](Tool-executeCode.md) | Executar código no kernel Jupyter |

package/concepts/pt-BR/ToolsFirst.md

@@ -0,0 +1,77 @@
+# Por que os Tools são listados primeiro?
+
+No painel Context do cc-viewer, **os Tools aparecem antes do System Prompt e dos Messages**. Essa ordenação reflete precisamente a **sequência de prefixo KV-Cache da API da Anthropic**.
+
+## Sequência de prefixo KV-Cache
+
+Quando a API da Anthropic constrói o KV-Cache, ela concatena o contexto em um prefixo nesta **ordem fixa**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+Isso significa que **os Tools ficam antes do System Prompt, bem no início do prefixo de cache**.
+
+## Por que os Tools têm maior peso de cache do que System?
+
+Na correspondência de prefixo KV-Cache, **o conteúdo anterior é mais crítico** — qualquer alteração invalida tudo o que vem depois:
+
+1. **A correspondência de prefixo começa pelo início**: O KV-Cache compara a requisição atual com o prefixo em cache token por token desde o início. No momento em que uma divergência é encontrada, todo o conteúdo subsequente é invalidado.
+
+2. **Alteração nos Tools = cache inteiro invalidado**: Como os Tools vêm primeiro, qualquer alteração nas definições de tool (mesmo adicionar ou remover um único MCP tool) **quebra o prefixo desde o início absoluto**, invalidando todos os System Prompt e Messages em cache.
+
+3. **Alteração no System = cache de Messages invalidado**: O System Prompt fica no meio, então suas alterações invalidam apenas a porção de Messages que o segue.
+
+4. **Alteração nos Messages = apenas o final é afetado**: Os Messages ficam no final, então adicionar novos messages invalida apenas um pequeno segmento final — os caches de Tools e System permanecem intactos.
+
+## Impacto prático
+
+| Tipo de alteração | Impacto no cache | Cenário típico |
+|-------------|-------------|-----------------|
+| Tool adicionado/removido | **Invalidação completa** | Conexão/desconexão de servidor MCP, ativação/desativação de plugin de IDE |
+| Alteração no System Prompt | Cache de Messages perdido | Edição de CLAUDE.md, injeção de system reminder |
+| Novo message adicionado | Apenas incremento de cauda | Fluxo de conversa normal (o mais comum, o mais barato) |
+
+É por isso que `tools_change` no [CacheRebuild](CacheRebuild.md) tende a ser o motivo de reconstrução mais custoso — ele quebra a cadeia de prefixo bem na frente.
+
+## Por que as definições de ferramentas vêm antes do "cérebro"?
+
+Do ponto de vista do cache, o fato de Tools estar em primeiro é um fato técnico. Mas do ponto de vista do design cognitivo, essa ordem é igualmente lógica — **Tools são as mãos e os pés, System Prompt é o cérebro**.
+
+Antes de agir, uma pessoa precisa perceber quais membros e ferramentas tem disponíveis. Um bebê não entende primeiro as regras do mundo (System) para depois aprender a agarrar — ele primeiro percebe que tem mãos e pés, e gradualmente entende as regras pela interação com o ambiente. Da mesma forma, um LLM precisa saber quais ferramentas pode chamar (ler arquivos, escrever código, pesquisar, executar comandos) antes de receber as instruções da tarefa (System Prompt), para poder avaliar com precisão "o que posso fazer" e "como devo fazer" ao processar as instruções.
+
+Se fosse invertido — primeiro dizer ao modelo "sua tarefa é refatorar este módulo", depois "você tem as ferramentas Read, Edit, Bash" — o modelo não teria informações cruciais sobre os limites de suas capacidades ao entender a tarefa, potencialmente produzindo planos irrealistas ou negligenciando abordagens disponíveis.
+
+**Conhecer as cartas que se tem antes de decidir como jogar.** Esta é a lógica cognitiva por trás de Tools preceder System.
+
+## Por que as ferramentas MCP também estão nesta posição?
+
+Ferramentas MCP (Model Context Protocol), assim como ferramentas integradas, são posicionadas no início da área Tools. Entender a posição do MCP no contexto ajuda a avaliar seus reais benefícios e custos.
+
+### Vantagens do MCP
+
+- **Extensão de capacidades**: MCP permite que modelos acessem serviços externos (consultas a bancos de dados, chamadas API, operações IDE, controle de navegador, etc.), ultrapassando os limites das ferramentas integradas
+- **Ecossistema aberto**: Qualquer pessoa pode implementar um servidor MCP; o modelo ganha novas capacidades sem retreinamento
+- **Carregamento sob demanda**: Servidores MCP podem ser conectados/desconectados seletivamente conforme o cenário, compondo conjuntos de ferramentas flexíveis
+
+### Custos do MCP
+
+- **Assassino de cache**: A definição JSON Schema de cada ferramenta MCP é concatenada no início do prefixo KV-Cache. Adicionar ou remover uma ferramenta MCP = **todo o cache invalidado desde o início**. Conectar/desconectar servidores MCP com frequência reduz drasticamente a taxa de acerto do cache
+- **Inchaço do prefixo**: Schemas de ferramentas MCP são tipicamente maiores que ferramentas integradas (descrições detalhadas de parâmetros, valores enum, etc.). Muitas ferramentas MCP aumentam significativamente a contagem de tokens na área Tools, reduzindo o espaço de contexto disponível para Messages
+- **Overhead de latência**: Chamadas de ferramentas MCP requerem comunicação entre processos (JSON-RPC via stdio/SSE), uma ordem de magnitude mais lenta que chamadas de funções integradas
+- **Risco de estabilidade**: Servidores MCP são processos externos que podem falhar, expirar ou retornar formatos inesperados, necessitando tratamento de erros adicional
+
+### Recomendações práticas
+
+| Cenário | Recomendação |
+|---------|-------------|
+| Conversas longas, interação frequente | Minimizar a quantidade de ferramentas MCP para proteger a estabilidade do prefixo de cache |
+| Tarefas curtas, operações pontuais | Usar ferramentas MCP livremente; impacto no cache é limitado |
+| Adição/remoção frequente de servidores MCP | Cada mudança dispara reconstrução completa do cache; considerar fixar o conjunto de ferramentas |
+| Schemas de ferramentas superdimensionados | Reduzir descriptions e enums para diminuir o consumo de tokens no prefixo |
+
+No painel Context do cc-viewer, ferramentas MCP são exibidas ao lado das ferramentas integradas na área Tools, oferecendo uma visão clara do tamanho do Schema de cada ferramenta e sua contribuição para o prefixo de cache.

package/concepts/pt-BR/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Poluição de Contexto na Translate API
+
+## Contexto
+
+O CC-Viewer inclui um recurso de tradução integrado (`POST /api/translate`) alimentado pela Anthropic Messages API. Na implementação inicial, as requisições de tradução reutilizavam credenciais de autenticação em cache da sessão do Claude Code — incluindo os cabeçalhos `x-api-key` e `authorization`. Isso causou um problema sutil, mas grave: os resultados da tradução frequentemente retornavam conteúdo irrelevante.
+
+## Causa Raiz
+
+### Diferença fundamental entre dois métodos de autenticação
+
+A Anthropic API suporta dois métodos de autenticação:
+
+| Método | Cabeçalho | Origem típica | Características |
+|--------|-----------|---------------|-----------------|
+| Chave de API | `x-api-key: sk-ant-...` | Variável de ambiente / Console | Sem estado, cada requisição é independente |
+| Token OAuth | `authorization: Bearer sessionToken` | Login por assinatura do Claude Code | Vinculado à sessão, o servidor mantém associação de contexto |
+
+A diferença fundamental: **Chaves de API são sem estado** — cada requisição é completamente independente; enquanto **tokens de sessão OAuth são com estado** — o servidor da Anthropic associa requisições que usam o mesmo token ao mesmo contexto de sessão.
+
+### Cadeia de poluição
+
+Quando o Claude Code usa login OAuth por assinatura, o fluxo de autenticação é assim:
+
+```
+Conversa principal do Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                              ↑
+Requisição de tradução do CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Como as requisições de tradução reutilizavam o mesmo token de sessão, o servidor da Anthropic pode associar as requisições de tradução ao contexto da conversa principal do Claude Code. Isso causa:
+
+1. **Resultados de tradução influenciados pelo contexto da conversa principal**: O prompt de sistema da requisição de tradução é "você é um tradutor", mas o contexto do servidor ainda contém o histórico de conversas do Claude Code, potencialmente interferindo no modelo
+2. **Conversa principal perturbada pelas requisições de tradução**: O conteúdo das requisições de tradução (fragmentos de texto da UI) pode ser injetado no contexto da conversa principal, fazendo com que as respostas do Claude Code desviem
+3. **Comportamento imprevisível**: Como a poluição de contexto é um comportamento do lado do servidor, o cliente não pode detectá-la ou controlá-la
+
+## Lições Aprendidas
+
+- **Tokens de sessão OAuth não são "apenas mais uma chave de API"** — eles carregam estado do lado do servidor, e reutilizá-los significa compartilhar contexto
+- **Chamadas internas de serviço devem usar autenticação independente e sem estado** para evitar associação com sessões de usuários
+
+## Referências
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)