cx-viewer 1.0.0

package/concepts/es/Tool-TaskStop.md

@@ -0,0 +1,32 @@
+# TaskStop
+
+## Definición
+
+Detiene una tarea en segundo plano en ejecución.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `task_id` | string | No | ID de la tarea en segundo plano a detener |
+| `shell_id` | string | No | Obsoleto, usar `task_id` en su lugar |
+
+## Casos de uso
+
+**Adecuado para:**
+- Terminar tareas de larga duración que ya no son necesarias
+- Cancelar tareas en segundo plano iniciadas por error
+
+## Notas
+
+- Devuelve estado de éxito o fallo
+- El parámetro `shell_id` está obsoleto, se debe 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/es/Tool-TaskUpdate.md

@@ -0,0 +1,123 @@
+# TaskUpdate
+
+## Definición
+
+Actualiza el estado, contenido o relaciones de dependencia de una tarea en la lista de tareas.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `taskId` | string | Sí | ID de la tarea a actualizar |
+| `status` | enum | No | Nuevo estado: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | No | Nuevo título |
+| `description` | string | No | Nueva descripción |
+| `activeForm` | string | No | Texto en gerundio mostrado cuando está en progreso |
+| `owner` | string | No | Nuevo responsable de la tarea (nombre del agent) |
+| `metadata` | object | No | Metadatos a fusionar (establecer como null para eliminar una clave) |
+| `addBlocks` | string[] | No | Lista de IDs de tareas bloqueadas por esta tarea |
+| `addBlockedBy` | string[] | No | Lista de IDs de tareas previas que bloquean esta tarea |
+
+## Flujo de estados
+
+```
+pending → in_progress → completed
+```
+
+`deleted` puede ser alcanzado desde cualquier estado, elimina permanentemente la tarea.
+
+## Casos de uso
+
+**Adecuado para:**
+- Marcar una tarea como `in_progress` al comenzar a trabajar
+- Marcar una tarea como `completed` al terminar el trabajo
+- Establecer relaciones de dependencia entre tareas
+- Actualizar el contenido de la tarea cuando cambian los requisitos
+
+**Reglas importantes:**
+- Solo marcar como `completed` cuando la tarea está completamente terminada
+- Mantener como `in_progress` cuando se encuentran errores o bloqueos
+- No marcar como `completed` cuando las pruebas fallan, la implementación es parcial o hay errores sin resolver
+
+## Notas
+
+- Antes de actualizar, se debe obtener el estado más reciente de la tarea mediante TaskGet para evitar datos obsoletos
+- Después de completar una tarea, llamar a TaskList para encontrar la siguiente tarea disponible
+
+## 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/es/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## Definición
+
+Crea un nuevo equipo para coordinar múltiples agentes trabajando en un proyecto. Los equipos permiten la ejecución paralela de tareas mediante una lista de tareas compartida y mensajería entre agentes.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `team_name` | string | Sí | Nombre para el nuevo equipo |
+| `description` | string | No | Descripción / propósito del equipo |
+| `agent_type` | string | No | Tipo / rol del líder del equipo |
+
+## Qué crea
+
+- **Archivo de configuración del equipo**: `~/.claude/teams/{team-name}/config.json` — almacena la lista de miembros y metadatos
+- **Directorio de lista de tareas**: `~/.claude/tasks/{team-name}/` — lista de tareas compartida para todos los compañeros de equipo
+
+Los equipos tienen una correspondencia 1:1 con las listas de tareas.
+
+## Flujo de trabajo del equipo
+
+1. **TeamCreate** — crear el equipo y su lista de tareas
+2. **TaskCreate** — definir tareas para el equipo
+3. **Agent** (con `team_name` + `name`) — generar compañeros de equipo que se unen al equipo
+4. **TaskUpdate** — asignar tareas a los compañeros mediante `owner`
+5. Los compañeros trabajan en las tareas y se comunican mediante **SendMessage**
+6. Detener a los compañeros al terminar, luego **TeamDelete** para limpiar
+
+## Herramientas relacionadas
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| `TeamDelete` | Eliminar el equipo y los directorios de tareas |
+| `SendMessage` | Comunicación entre agentes dentro del equipo |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Gestionar la lista de tareas compartida |
+| `Agent` | Generar compañeros de equipo que se unen al equipo |

package/concepts/es/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## Definición
+
+Elimina un equipo y sus directorios de tareas asociados cuando el trabajo de colaboración multi-agent ha concluido. Es la contrapartida de limpieza de TeamCreate.
+
+## Comportamiento
+
+- Elimina el directorio del equipo: `~/.claude/teams/{team-name}/`
+- Elimina el directorio de tareas: `~/.claude/tasks/{team-name}/`
+- Limpia el contexto del equipo de la sesión actual
+
+**Importante**: TeamDelete fallará si el equipo todavía tiene miembros activos. Los compañeros de equipo deben cerrarse primero correctamente mediante solicitudes de apagado de SendMessage.
+
+## Uso típico
+
+TeamDelete se llama al final de un flujo de trabajo de equipo:
+
+1. Todas las tareas están completadas
+2. Los compañeros de equipo se cierran mediante `SendMessage` con `shutdown_request`
+3. **TeamDelete** elimina los directorios del equipo y de tareas
+
+## Herramientas relacionadas
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| `TeamCreate` | Crear un nuevo equipo y su lista de tareas |
+| `SendMessage` | Comunicarse con los compañeros / enviar solicitudes de apagado |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Gestionar la lista de tareas compartida |
+| `Agent` | Generar compañeros de equipo que se unen al equipo |

package/concepts/es/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## Definición
+
+Obtiene el contenido de una página web de una URL especificada, convierte el HTML a markdown y procesa el contenido con un modelo de IA según el prompt.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `url` | string (URI) | Sí | URL completa a obtener |
+| `prompt` | string | Sí | Describe qué información extraer de la página |
+
+## Casos de uso
+
+**Adecuado para:**
+- Obtener contenido de páginas web públicas
+- Consultar documentación en línea
+- Extraer información específica de páginas web
+
+**No adecuado para:**
+- URLs que requieren autenticación (Google Docs, Confluence, Jira, GitHub, etc.) — buscar primero herramientas MCP dedicadas
+- URLs de GitHub — preferir usar el CLI `gh`
+
+## Notas
+
+- La URL debe ser una URL válida completa
+- HTTP se actualiza automáticamente a HTTPS
+- Los resultados pueden ser resumidos si el contenido es demasiado grande
+- Incluye caché con auto-limpieza de 15 minutos
+- Cuando la URL redirige a un host diferente, la herramienta devuelve la URL de redirección y se necesita hacer una nueva solicitud con la nueva URL
+- Si hay una herramienta web fetch proporcionada por MCP disponible, preferir usar esa
+
+## 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/es/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## Definición
+
+Ejecuta consultas en motores de búsqueda y devuelve resultados de búsqueda para obtener información actualizada.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `query` | string | Sí | Consulta de búsqueda (mínimo 2 caracteres) |
+| `allowed_domains` | string[] | No | Solo incluir resultados de estos dominios |
+| `blocked_domains` | string[] | No | Excluir resultados de estos dominios |
+
+## Casos de uso
+
+**Adecuado para:**
+- Obtener información actualizada más allá de la fecha de corte del conocimiento del modelo
+- Buscar eventos actuales y datos recientes
+- Buscar la documentación técnica más reciente
+
+## Notas
+
+- Los resultados de búsqueda se devuelven en formato de hipervínculos markdown
+- Después de usar, se debe incluir una sección "Sources:" al final de la respuesta, listando las URLs relevantes
+- Soporta filtrado de dominios (incluir/excluir)
+- Se debe usar el año actual en las consultas de búsqueda
+- Solo disponible en Estados Unidos
+
+## 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/es/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## Definición
+
+Escribe contenido en el sistema de archivos local. Si el archivo ya existe, lo sobrescribe.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `file_path` | string | Sí | Ruta absoluta del archivo (debe ser ruta absoluta) |
+| `content` | string | Sí | Contenido a escribir |
+
+## Casos de uso
+
+**Adecuado para:**
+- Crear archivos nuevos
+- Cuando se necesita reescribir completamente el contenido de un archivo
+
+**No adecuado para:**
+- Modificar contenido parcial de un archivo — usar Edit
+- No se deben crear proactivamente archivos de documentación (*.md) o README, a menos que el usuario lo solicite explícitamente
+
+## Notas
+
+- Si el archivo de destino ya existe, se debe leer primero con Read, de lo contrario fallará
+- Sobrescribe todo el contenido del archivo existente
+- Preferir usar Edit para editar archivos existentes, Write solo para crear archivos nuevos o reescrituras completas
+
+## 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/es/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## Definición
+
+Ejecuta código Python en el kernel de Jupyter del archivo notebook actual.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `code` | string | Sí | Código Python a ejecutar |
+
+## Casos de uso
+
+**Adecuado para:**
+- Ejecutar código en un entorno Jupyter notebook
+- Probar fragmentos de código
+- Análisis de datos y cálculos
+
+**No adecuado para:**
+- Ejecución de código fuera del entorno Jupyter — usar Bash
+- Modificar archivos — usar Edit o Write
+
+## Notas
+
+- Esta es una herramienta MCP (Model Context Protocol), proporcionada por la integración con el IDE
+- El código se ejecuta en el kernel de Jupyter actual, el estado persiste entre llamadas
+- A menos que el usuario lo solicite explícitamente, se debe evitar declarar variables o modificar el estado del kernel
+- El estado se pierde al reiniciar el 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/es/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definición
+
+Obtiene información de diagnóstico del lenguaje de VS Code, incluyendo errores de sintaxis, errores de tipo, advertencias de lint, etc.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `uri` | string | No | URI del archivo. Si no se proporciona, obtiene la información de diagnóstico de todos los archivos |
+
+## Casos de uso
+
+**Adecuado para:**
+- Verificar problemas semánticos de sintaxis, tipos, lint, etc. del código
+- Verificar si se introdujeron nuevos errores después de editar código
+- Reemplazar comandos Bash para verificar la calidad del código
+
+**No adecuado para:**
+- Ejecutar pruebas — usar Bash
+- Verificar errores en tiempo de ejecución — usar Bash para ejecutar el código
+
+## Notas
+
+- Esta es una herramienta MCP (Model Context Protocol), proporcionada por la integración con el IDE
+- Solo disponible en entornos VS Code / IDE
+- Preferir usar esta herramienta en lugar de comandos Bash para verificar problemas de código
+
+## Texto original
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/es/Tools.md

@@ -0,0 +1,67 @@
+# Resumen de herramientas de Claude Code
+
+Claude Code proporciona al modelo un conjunto de herramientas integradas a través del mecanismo tool_use de la API de Anthropic. Cada solicitud MainAgent incluye las definiciones completas en JSON Schema de estas herramientas en el array `tools`, y el modelo las invoca mediante content blocks `tool_use` en la respuesta.
+
+A continuación se presenta el índice clasificado de todas las herramientas.
+
+## Sistema de Agents
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Task](Tool-Task.md) | Iniciar un sub-agent (SubAgent) para manejar tareas complejas de múltiples pasos |
+| [TaskOutput](Tool-TaskOutput.md) | Obtener la salida de tareas en segundo plano |
+| [TaskStop](Tool-TaskStop.md) | Detener una tarea en segundo plano en ejecución |
+| [TaskCreate](Tool-TaskCreate.md) | Crear una entrada en la lista de tareas estructurada |
+| [TaskGet](Tool-TaskGet.md) | Obtener detalles de una tarea |
+| [TaskUpdate](Tool-TaskUpdate.md) | Actualizar el estado, dependencias, etc. de una tarea |
+| [TaskList](Tool-TaskList.md) | Listar todas las tareas |
+
+## Operaciones de archivos
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Read](Tool-Read.md) | Leer contenido de archivos (soporta texto, imágenes, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Editar archivos mediante reemplazo exacto de cadenas |
+| [Write](Tool-Write.md) | Escribir o sobrescribir archivos |
+| [NotebookEdit](Tool-NotebookEdit.md) | Editar celdas de Jupyter notebook |
+
+## Búsqueda
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Glob](Tool-Glob.md) | Buscar archivos por coincidencia de patrones de nombre |
+| [Grep](Tool-Grep.md) | Búsqueda de contenido de archivos basada en ripgrep |
+
+## Terminal
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Bash](Tool-Bash.md) | Ejecutar comandos shell |
+
+## Web
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [WebFetch](Tool-WebFetch.md) | Obtener contenido web y procesarlo con IA |
+| [WebSearch](Tool-WebSearch.md) | Consultas en motores de búsqueda |
+
+## Planificación e interacción
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Entrar en modo de planificación para diseñar un plan de implementación |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Salir del modo de planificación y enviar el plan para aprobación del usuario |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Hacer preguntas al usuario para obtener aclaraciones o decisiones |
+
+## Extensiones
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Skill](Tool-Skill.md) | Ejecutar una habilidad (slash command) |
+
+## Integración con IDE
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Obtener información de diagnóstico del lenguaje de VS Code |
+| [executeCode](Tool-executeCode.md) | Ejecutar código en el kernel de Jupyter |

package/concepts/es/ToolsFirst.md

@@ -0,0 +1,77 @@
+# ¿Por qué se listan primero los Tools?
+
+En el panel Context de cc-viewer, **los Tools aparecen antes que el System Prompt y los Messages**. Este orden refleja con precisión la **secuencia de prefijo KV-Cache de la API de Anthropic**.
+
+## Secuencia de prefijo KV-Cache
+
+Cuando la API de Anthropic construye el KV-Cache, concatena el contexto en un prefijo en este **orden fijo**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+Esto significa que **los Tools se encuentran antes del System Prompt, al comienzo del prefijo de caché**.
+
+## ¿Por qué los Tools tienen mayor peso en caché que System?
+
+En la coincidencia de prefijo KV-Cache, **el contenido más temprano es más crítico** — cualquier cambio invalida todo lo que viene después:
+
+1. **La coincidencia de prefijo comienza desde el principio**: El KV-Cache compara la solicitud actual con el prefijo almacenado en caché token por token desde el inicio. En el momento en que se detecta una discrepancia, todo el contenido posterior queda invalidado.
+
+2. **Cambio en Tools = todo el caché invalidado**: Como los Tools están primero, cualquier cambio en las definiciones de tool (incluso agregar o eliminar un solo MCP tool) **rompe el prefijo desde el mismísimo inicio**, invalidando todo el System Prompt y los Messages almacenados en caché.
+
+3. **Cambio en System = caché de Messages invalidado**: El System Prompt está en el medio, por lo que sus cambios solo invalidan la porción de Messages que le sigue.
+
+4. **Cambio en Messages = solo el final se ve afectado**: Los Messages están al final, por lo que agregar nuevos messages solo invalida un pequeño segmento final — los cachés de Tools y System permanecen intactos.
+
+## Impacto práctico
+
+| Tipo de cambio | Impacto en caché | Escenario típico |
+|-------------|-------------|-----------------|
+| Tool agregado/eliminado | **Invalidación completa** | Conexión/desconexión de servidor MCP, activación/desactivación de plugin IDE |
+| Cambio en System Prompt | Caché de Messages perdido | Edición de CLAUDE.md, inyección de system reminder |
+| Nuevo message agregado | Solo incremento de cola | Flujo de conversación normal (el más común, el más económico) |
+
+Por eso `tools_change` en [CacheRebuild](CacheRebuild.md) tiende a ser la razón de reconstrucción más costosa — rompe la cadena de prefijo desde el principio.
+
+## ¿Por qué las definiciones de herramientas se colocan antes del "cerebro"?
+
+Desde la perspectiva del caché, que los Tools estén primero es un hecho técnico. Pero desde la perspectiva del diseño cognitivo, este orden es igualmente lógico — **los Tools son las manos y los pies, el System Prompt es el cerebro**.
+
+Antes de actuar, una persona necesita percibir qué extremidades y herramientas tiene disponibles. Un bebé no comprende primero las reglas del mundo (System) para luego aprender a agarrar — primero percibe que tiene manos y pies, y luego comprende gradualmente las reglas a través de la interacción con el entorno. Del mismo modo, un LLM necesita saber qué herramientas puede llamar (leer archivos, escribir código, buscar, ejecutar comandos) antes de recibir las instrucciones de tarea (System Prompt), para poder evaluar con precisión "qué puedo hacer" y "cómo debo hacerlo" al procesar las instrucciones.
+
+Si fuera al revés — decirle primero al modelo "tu tarea es refactorizar este módulo", y luego "tienes las herramientas Read, Edit, Bash" — el modelo carecería de información crucial sobre los límites de sus capacidades al entender la tarea, produciendo potencialmente planes poco realistas u omitiendo enfoques disponibles.
+
+**Conocer las cartas que tienes antes de decidir cómo jugar.** Esta es la lógica cognitiva detrás de que los Tools precedan al System.
+
+## ¿Por qué las herramientas MCP también están en esta posición?
+
+Las herramientas MCP (Model Context Protocol), al igual que las herramientas integradas, se colocan al inicio de la zona Tools. Comprender la posición de MCP en el contexto ayuda a evaluar sus beneficios y costes reales.
+
+### Ventajas de MCP
+
+- **Extensión de capacidades**: MCP permite a los modelos acceder a servicios externos (consultas a bases de datos, llamadas API, operaciones IDE, control del navegador, etc.), superando los límites de las herramientas integradas
+- **Ecosistema abierto**: Cualquiera puede implementar un servidor MCP; el modelo obtiene nuevas capacidades sin reentrenamiento
+- **Carga bajo demanda**: Los servidores MCP pueden conectarse/desconectarse selectivamente según el escenario, componiendo conjuntos de herramientas flexibles
+
+### Costes de MCP
+
+- **Asesino de caché**: La definición JSON Schema de cada herramienta MCP se concatena al inicio del prefijo KV-Cache. Añadir o eliminar una herramienta MCP = **todo el caché se invalida desde el principio**. Conectar/desconectar frecuentemente servidores MCP reduce drásticamente la tasa de aciertos del caché
+- **Inflación del prefijo**: Los Schemas de herramientas MCP suelen ser más grandes que los de herramientas integradas (descripciones detalladas de parámetros, valores de enumeración, etc.). Muchas herramientas MCP aumentan significativamente el conteo de tokens de la zona Tools, reduciendo el espacio de contexto disponible para Messages
+- **Sobrecarga de latencia**: Las llamadas a herramientas MCP requieren comunicación entre procesos (JSON-RPC sobre stdio/SSE), un orden de magnitud más lento que las llamadas a funciones integradas
+- **Riesgo de estabilidad**: Los servidores MCP son procesos externos que pueden fallar, expirar o devolver formatos inesperados, requiriendo manejo de errores adicional
+
+### Recomendaciones prácticas
+
+| Escenario | Recomendación |
+|-----------|--------------|
+| Conversaciones largas, interacción frecuente | Minimizar la cantidad de herramientas MCP para proteger la estabilidad del prefijo de caché |
+| Tareas cortas, operaciones puntuales | Usar herramientas MCP libremente; el impacto en el caché es limitado |
+| Adición/eliminación frecuente de servidores MCP | Cada cambio desencadena una reconstrucción completa del caché; considerar fijar el conjunto de herramientas |
+| Schemas de herramientas sobredimensionados | Reducir descripciones y enums para disminuir el consumo de tokens del prefijo |
+
+En el panel Context de cc-viewer, las herramientas MCP se muestran junto a las herramientas integradas en la zona Tools, ofreciendo una vista clara del tamaño del Schema de cada herramienta y su contribución al prefijo de caché.

package/concepts/es/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Contaminación de contexto de la API de traducción
+
+## Contexto
+
+CC-Viewer incluye una función de traducción integrada (`POST /api/translate`) impulsada por la API de mensajes de Anthropic. En la implementación inicial, las solicitudes de traducción reutilizaban las credenciales de autenticación almacenadas en caché de la sesión de Claude Code, incluyendo tanto los encabezados `x-api-key` como `authorization`. Esto provocó un problema sutil pero grave: los resultados de traducción devolvían con frecuencia contenido irrelevante.
+
+## Causa raíz
+
+### Diferencia fundamental entre los dos métodos de autenticación
+
+La API de Anthropic admite dos métodos de autenticación:
+
+| Método | Encabezado | Origen típico | Características |
+|--------|------------|---------------|-----------------|
+| Clave API | `x-api-key: sk-ant-...` | Variable de entorno / Console | Sin estado, cada solicitud es independiente |
+| Token OAuth | `authorization: Bearer sessionToken` | Inicio de sesión con suscripción de Claude Code | Vinculado a la sesión, el servidor mantiene la asociación de contexto |
+
+La diferencia clave: **las claves API son sin estado** — cada solicitud es completamente independiente; mientras que **los tokens de sesión OAuth son con estado** — el servidor de Anthropic asocia las solicitudes que usan el mismo token al mismo contexto de sesión.
+
+### Cadena de contaminación
+
+Cuando Claude Code utiliza el inicio de sesión OAuth por suscripción, el flujo de autenticación es el siguiente:
+
+```
+Conversación principal de Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                                  ↑
+Solicitud de traducción de CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Dado que las solicitudes de traducción reutilizaban el mismo token de sesión, el servidor de Anthropic podía asociar las solicitudes de traducción con el contexto de la conversación principal de Claude Code. Esto provoca:
+
+1. **Los resultados de traducción se ven influenciados por el contexto de la conversación principal**: El prompt del sistema de la solicitud de traducción es "eres un traductor", pero el contexto del servidor aún contiene el historial de conversación de Claude Code, lo que puede interferir con el modelo
+2. **La conversación principal se ve perturbada por las solicitudes de traducción**: El contenido de las solicitudes de traducción (fragmentos de texto de la interfaz) puede inyectarse en el contexto de la conversación principal, causando que las respuestas de Claude Code se desvíen
+3. **Comportamiento impredecible**: Dado que la contaminación de contexto es un comportamiento del lado del servidor, el cliente no puede detectarlo ni controlarlo
+
+## Lecciones aprendidas
+
+- **Los tokens de sesión OAuth no son "simplemente otra clave API"** — llevan estado del lado del servidor, reutilizarlos significa compartir contexto
+- **Las llamadas internas de servicio deben usar autenticación independiente y sin estado** para evitar la asociación con sesiones de usuario
+
+## Referencias
+
+- [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/)