cx-viewer 1.0.0

package/concepts/it/Tool-TaskUpdate.md

@@ -0,0 +1,123 @@
+# TaskUpdate
+
+## Definizione
+
+Aggiorna lo stato, il contenuto o le dipendenze di un task nella lista dei task.
+
+## Parametri
+
+| Parametro | Tipo | Obbligatorio | Descrizione |
+|------|------|------|------|
+| `taskId` | string | Sì | ID del task da aggiornare |
+| `status` | enum | No | Nuovo stato: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | No | Nuovo titolo |
+| `description` | string | No | Nuova descrizione |
+| `activeForm` | string | No | Testo al presente progressivo mostrato durante l'esecuzione |
+| `owner` | string | No | Nuovo responsabile del task (nome dell'agent) |
+| `metadata` | object | No | Metadati da unire (impostare a null per eliminare una chiave) |
+| `addBlocks` | string[] | No | Lista degli ID dei task bloccati da questo task |
+| `addBlockedBy` | string[] | No | Lista degli ID dei task prerequisiti che bloccano questo task |
+
+## Flusso degli stati
+
+```
+pending → in_progress → completed
+```
+
+`deleted` può essere raggiunto da qualsiasi stato e rimuove permanentemente il task.
+
+## Scenari d'uso
+
+**Adatto per:**
+- Contrassegnare un task come `in_progress` quando si inizia il lavoro
+- Contrassegnare un task come `completed` quando il lavoro è terminato
+- Impostare le dipendenze tra i task
+- Aggiornare il contenuto del task quando i requisiti cambiano
+
+**Regole importanti:**
+- Contrassegnare come `completed` solo quando il task è completamente terminato
+- In caso di errori o blocchi, mantenere `in_progress`
+- Non contrassegnare come `completed` in caso di test falliti, implementazione incompleta o errori non risolti
+
+## Note
+
+- Prima dell'aggiornamento, ottenere lo stato più recente del task tramite TaskGet per evitare dati obsoleti
+- Dopo aver completato un task, chiamare TaskList per trovare il prossimo task disponibile
+
+## Testo originale
+
+<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/it/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## Definizione
+
+Crea un nuovo team per coordinare più agent che lavorano su un progetto. I team permettono l'esecuzione parallela dei task tramite una lista di task condivisa e la messaggistica tra agent.
+
+## Parametri
+
+| Parametro | Tipo | Obbligatorio | Descrizione |
+|-----------|------|--------------|-------------|
+| `team_name` | string | Sì | Nome del nuovo team |
+| `description` | string | No | Descrizione / scopo del team |
+| `agent_type` | string | No | Tipo / ruolo del responsabile del team |
+
+## Cosa viene creato
+
+- **File di configurazione del team**: `~/.claude/teams/{team-name}/config.json` — memorizza la lista dei membri e i metadati
+- **Directory della lista dei task**: `~/.claude/tasks/{team-name}/` — lista dei task condivisa per tutti i membri del team
+
+I team hanno una corrispondenza 1:1 con le liste dei task.
+
+## Flusso di lavoro del team
+
+1. **TeamCreate** — creare il team e la sua lista dei task
+2. **TaskCreate** — definire i task per il team
+3. **Agent** (con `team_name` + `name`) — avviare i membri del team che si uniscono al team
+4. **TaskUpdate** — assegnare i task ai membri tramite `owner`
+5. I membri lavorano sui task e comunicano tramite **SendMessage**
+6. Terminare i membri al completamento, poi **TeamDelete** per la pulizia
+
+## Strumenti correlati
+
+| Strumento | Scopo |
+|-----------|-------|
+| `TeamDelete` | Rimuovere il team e le directory dei task |
+| `SendMessage` | Comunicazione tra agent all'interno del team |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Gestire la lista dei task condivisa |
+| `Agent` | Avviare i membri del team che si uniscono al team |

package/concepts/it/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## Definizione
+
+Rimuove un team e le relative directory dei task quando il lavoro di collaborazione multi-agent è completato. È la controparte di pulizia di TeamCreate.
+
+## Comportamento
+
+- Rimuove la directory del team: `~/.claude/teams/{team-name}/`
+- Rimuove la directory della lista dei task: `~/.claude/tasks/{team-name}/`
+- Cancella il contesto del team dalla sessione corrente
+
+**Importante**: TeamDelete fallirà se il team ha ancora membri attivi. I membri del team devono prima essere terminati correttamente tramite richieste di shutdown di SendMessage.
+
+## Utilizzo tipico
+
+TeamDelete viene chiamato alla fine di un flusso di lavoro del team:
+
+1. Tutti i task sono completati
+2. I membri del team vengono terminati tramite `SendMessage` con `shutdown_request`
+3. **TeamDelete** rimuove le directory del team e dei task
+
+## Strumenti correlati
+
+| Strumento | Scopo |
+|-----------|-------|
+| `TeamCreate` | Creare un nuovo team e la sua lista dei task |
+| `SendMessage` | Comunicare con i membri del team / inviare richieste di shutdown |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Gestire la lista dei task condivisa |
+| `Agent` | Avviare i membri del team che si uniscono al team |

package/concepts/it/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## Definizione
+
+Recupera il contenuto di una pagina web dall'URL specificato, converte l'HTML in markdown e lo elabora con un modello AI in base al prompt.
+
+## Parametri
+
+| Parametro | Tipo | Obbligatorio | Descrizione |
+|------|------|------|------|
+| `url` | string (URI) | Sì | URL completo da recuperare |
+| `prompt` | string | Sì | Descrive quali informazioni estrarre dalla pagina |
+
+## Scenari d'uso
+
+**Adatto per:**
+- Ottenere il contenuto di pagine web pubbliche
+- Consultare documentazione online
+- Estrarre informazioni specifiche da una pagina web
+
+**Non adatto per:**
+- URL che richiedono autenticazione (Google Docs, Confluence, Jira, GitHub, ecc.) — cercare prima uno strumento MCP dedicato
+- URL di GitHub — preferire l'uso della CLI `gh`
+
+## Note
+
+- L'URL deve essere un URL valido e completo
+- HTTP viene automaticamente aggiornato a HTTPS
+- I risultati possono essere riassunti se il contenuto è troppo grande
+- Include una cache auto-pulente di 15 minuti
+- Quando l'URL reindirizza a un host diverso, lo strumento restituisce l'URL di reindirizzamento e occorre effettuare una nuova richiesta con il nuovo URL
+- Se è disponibile uno strumento web fetch fornito da MCP, preferire quello
+
+## Testo originale
+
+<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/it/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## Definizione
+
+Esegue una query su motore di ricerca, restituendo risultati di ricerca per ottenere informazioni aggiornate.
+
+## Parametri
+
+| Parametro | Tipo | Obbligatorio | Descrizione |
+|------|------|------|------|
+| `query` | string | Sì | Query di ricerca (minimo 2 caratteri) |
+| `allowed_domains` | string[] | No | Includi solo risultati da questi domini |
+| `blocked_domains` | string[] | No | Escludi risultati da questi domini |
+
+## Scenari d'uso
+
+**Adatto per:**
+- Ottenere informazioni aggiornate oltre la data di cutoff della conoscenza del modello
+- Cercare eventi attuali e dati recenti
+- Cercare la documentazione tecnica più recente
+
+## Note
+
+- I risultati di ricerca vengono restituiti in formato hyperlink markdown
+- Dopo l'uso, è obbligatorio aggiungere una sezione "Sources:" alla fine della risposta, elencando gli URL pertinenti
+- Supporta il filtro per dominio (inclusione/esclusione)
+- Usare l'anno corrente nelle query di ricerca
+- Disponibile solo negli Stati Uniti
+
+## Testo originale
+
+<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/it/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## Definizione
+
+Scrive contenuto nel file system locale. Se il file esiste già, viene sovrascritto.
+
+## Parametri
+
+| Parametro | Tipo | Obbligatorio | Descrizione |
+|------|------|------|------|
+| `file_path` | string | Sì | Percorso assoluto del file (deve essere assoluto) |
+| `content` | string | Sì | Contenuto da scrivere |
+
+## Scenari d'uso
+
+**Adatto per:**
+- Creare nuovi file
+- Quando è necessario riscrivere completamente il contenuto di un file
+
+**Non adatto per:**
+- Modificare contenuto parziale di un file — usare Edit
+- Non creare proattivamente file di documentazione (*.md) o README, a meno che l'utente non lo richieda esplicitamente
+
+## Note
+
+- Se il file di destinazione esiste già, è necessario prima leggerlo tramite Read, altrimenti l'operazione fallisce
+- Sovrascrive l'intero contenuto del file esistente
+- Preferire Edit per modificare file esistenti, Write è solo per creare nuovi file o riscritture complete
+
+## Testo originale
+
+<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/it/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## Definizione
+
+Esegue codice Python nel kernel Jupyter del file notebook corrente.
+
+## Parametri
+
+| Parametro | Tipo | Obbligatorio | Descrizione |
+|------|------|------|------|
+| `code` | string | Sì | Codice Python da eseguire |
+
+## Scenari d'uso
+
+**Adatto per:**
+- Eseguire codice in un ambiente Jupyter notebook
+- Testare frammenti di codice
+- Analisi dati e calcoli
+
+**Non adatto per:**
+- Esecuzione di codice in ambienti non Jupyter — usare Bash
+- Modificare file — usare Edit o Write
+
+## Note
+
+- Questo è uno strumento MCP (Model Context Protocol), fornito dall'integrazione IDE
+- Il codice viene eseguito nel kernel Jupyter corrente, lo stato persiste tra le chiamate
+- A meno che l'utente non lo richieda esplicitamente, evitare di dichiarare variabili o modificare lo stato del kernel
+- Lo stato viene perso dopo il riavvio del kernel
+
+## Testo originale
+
+<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/it/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definizione
+
+Ottiene informazioni diagnostiche del linguaggio da VS Code, inclusi errori di sintassi, errori di tipo, avvisi lint, ecc.
+
+## Parametri
+
+| Parametro | Tipo | Obbligatorio | Descrizione |
+|------|------|------|------|
+| `uri` | string | No | URI del file. Se non fornito, ottiene le informazioni diagnostiche di tutti i file |
+
+## Scenari d'uso
+
+**Adatto per:**
+- Controllare problemi semantici del codice come sintassi, tipi, lint
+- Verificare se sono stati introdotti nuovi errori dopo la modifica del codice
+- Sostituire i comandi Bash per controllare la qualità del codice
+
+**Non adatto per:**
+- Eseguire test — usare Bash
+- Controllare errori a runtime — usare Bash per eseguire il codice
+
+## Note
+
+- Questo è uno strumento MCP (Model Context Protocol), fornito dall'integrazione IDE
+- Disponibile solo in ambienti VS Code / IDE
+- Preferire questo strumento rispetto ai comandi Bash per controllare i problemi del codice
+
+## Testo originale
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/it/Tools.md

@@ -0,0 +1,67 @@
+# Panoramica degli strumenti di Claude Code
+
+Claude Code fornisce al modello un set di strumenti integrati tramite il meccanismo tool_use dell'API Anthropic. L'array `tools` di ogni richiesta MainAgent contiene le definizioni JSON Schema complete di questi strumenti, e il modello li invoca tramite content block `tool_use` nella risposta.
+
+Di seguito l'indice categorizzato di tutti gli strumenti.
+
+## Sistema Agent
+
+| Strumento | Scopo |
+|------|------|
+| [Task](Tool-Task.md) | Avvia un sub agent (SubAgent) per gestire task complessi multi-step |
+| [TaskOutput](Tool-TaskOutput.md) | Ottieni l'output di un task in background |
+| [TaskStop](Tool-TaskStop.md) | Ferma un task in background in esecuzione |
+| [TaskCreate](Tool-TaskCreate.md) | Crea una voce nella lista dei task strutturata |
+| [TaskGet](Tool-TaskGet.md) | Ottieni i dettagli di un task |
+| [TaskUpdate](Tool-TaskUpdate.md) | Aggiorna lo stato, le dipendenze, ecc. di un task |
+| [TaskList](Tool-TaskList.md) | Elenca tutti i task |
+
+## Operazioni sui file
+
+| Strumento | Scopo |
+|------|------|
+| [Read](Tool-Read.md) | Leggi il contenuto di un file (supporta testo, immagini, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Modifica un file tramite sostituzione esatta di stringhe |
+| [Write](Tool-Write.md) | Scrivi o sovrascrivi un file |
+| [NotebookEdit](Tool-NotebookEdit.md) | Modifica celle di Jupyter notebook |
+
+## Ricerca
+
+| Strumento | Scopo |
+|------|------|
+| [Glob](Tool-Glob.md) | Cerca file per pattern di nome file |
+| [Grep](Tool-Grep.md) | Ricerca nel contenuto dei file basata su ripgrep |
+
+## Terminale
+
+| Strumento | Scopo |
+|------|------|
+| [Bash](Tool-Bash.md) | Esegui comandi shell |
+
+## Web
+
+| Strumento | Scopo |
+|------|------|
+| [WebFetch](Tool-WebFetch.md) | Recupera contenuto web ed elaboralo con AI |
+| [WebSearch](Tool-WebSearch.md) | Query su motore di ricerca |
+
+## Pianificazione e interazione
+
+| Strumento | Scopo |
+|------|------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Entra in modalità pianificazione per progettare un piano di implementazione |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Esci dalla modalità pianificazione e invia il piano per l'approvazione dell'utente |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Poni domande all'utente per ottenere chiarimenti o decisioni |
+
+## Estensioni
+
+| Strumento | Scopo |
+|------|------|
+| [Skill](Tool-Skill.md) | Esegui una skill (slash command) |
+
+## Integrazione IDE
+
+| Strumento | Scopo |
+|------|------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Ottieni informazioni diagnostiche del linguaggio da VS Code |
+| [executeCode](Tool-executeCode.md) | Esegui codice nel kernel Jupyter |

package/concepts/it/ToolsFirst.md

@@ -0,0 +1,77 @@
+# Perché i Tools sono elencati per primi?
+
+Nel pannello Context di cc-viewer, **i Tools appaiono prima di System Prompt e Messages**. Questo ordine riflette con precisione la **sequenza del prefisso KV-Cache dell'API di Anthropic**.
+
+## Sequenza del prefisso KV-Cache
+
+Quando l'API di Anthropic costruisce il KV-Cache, concatena il contesto in un prefisso in questo **ordine fisso**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+Ciò significa che **i Tools si trovano prima del System Prompt, all'inizio del prefisso di cache**.
+
+## Perché i Tools hanno un peso di cache maggiore di System?
+
+Nella corrispondenza del prefisso KV-Cache, **il contenuto precedente è più critico** — qualsiasi modifica invalida tutto ciò che segue:
+
+1. **La corrispondenza del prefisso inizia dall'inizio**: Il KV-Cache confronta la richiesta corrente con il prefisso memorizzato nella cache token per token dall'inizio. Nel momento in cui viene rilevata una discrepanza, tutto il contenuto successivo viene invalidato.
+
+2. **Modifica dei Tools = intera cache invalidata**: Poiché i Tools sono in prima posizione, qualsiasi modifica alle definizioni dei tool (anche aggiungere o rimuovere un singolo MCP tool) **rompe il prefisso dal primissimo inizio**, invalidando tutti i System Prompt e i Messages memorizzati nella cache.
+
+3. **Modifica di System = cache dei Messages invalidata**: Il System Prompt si trova nel mezzo, quindi le sue modifiche invalidano solo la porzione dei Messages che segue.
+
+4. **Modifica dei Messages = solo la coda è interessata**: I Messages sono alla fine, quindi aggiungere nuovi messages invalida solo un piccolo segmento finale — le cache di Tools e System rimangono intatte.
+
+## Impatto pratico
+
+| Tipo di modifica | Impatto sulla cache | Scenario tipico |
+|-------------|-------------|-----------------|
+| Tool aggiunto/rimosso | **Invalidazione completa** | Connessione/disconnessione server MCP, attivazione/disattivazione plugin IDE |
+| Modifica del System Prompt | Cache dei Messages persa | Modifica di CLAUDE.md, iniezione di system reminder |
+| Nuovo message aggiunto | Solo incremento della coda | Flusso di conversazione normale (il più comune, il meno costoso) |
+
+Ecco perché `tools_change` in [CacheRebuild](CacheRebuild.md) tende ad essere il motivo di ricostruzione più costoso — rompe la catena del prefisso fin dall'inizio.
+
+## Perché le definizioni degli strumenti vengono prima del "cervello"?
+
+Dal punto di vista della cache, il fatto che i Tools siano per primi è un dato tecnico. Ma dal punto di vista del design cognitivo, quest'ordine è altrettanto logico — **i Tools sono le mani e i piedi, il System Prompt è il cervello**.
+
+Prima di agire, una persona deve percepire quali arti e strumenti ha a disposizione. Un neonato non comprende prima le regole del mondo (System) per poi imparare ad afferrare — percepisce prima di avere mani e piedi, poi comprende gradualmente le regole attraverso l'interazione con l'ambiente. Allo stesso modo, un LLM deve sapere quali strumenti può chiamare (leggere file, scrivere codice, cercare, eseguire comandi) prima di ricevere le istruzioni del compito (System Prompt), per poter valutare con precisione "cosa posso fare" e "come devo procedere" nell'elaborare le istruzioni.
+
+Se fosse il contrario — dire prima al modello "il tuo compito è ristrutturare questo modulo", poi "hai gli strumenti Read, Edit, Bash" — il modello mancherebbe di informazioni cruciali sui limiti delle proprie capacità nella comprensione del compito, producendo potenzialmente piani irrealistici o trascurando approcci disponibili.
+
+**Conoscere le carte che si hanno prima di decidere come giocarle.** Questa è la logica cognitiva dietro il posizionamento dei Tools prima del System.
+
+## Perché anche gli strumenti MCP sono in questa posizione?
+
+Gli strumenti MCP (Model Context Protocol), come gli strumenti integrati, sono posizionati all'inizio dell'area Tools. Comprendere la posizione di MCP nel contesto aiuta a valutare i reali benefici e costi.
+
+### Vantaggi di MCP
+
+- **Estensione delle capacità**: MCP permette ai modelli di accedere a servizi esterni (query database, chiamate API, operazioni IDE, controllo browser, ecc.), superando i limiti degli strumenti integrati
+- **Ecosistema aperto**: Chiunque può implementare un server MCP; il modello acquisisce nuove capacità senza ri-addestramento
+- **Caricamento su richiesta**: I server MCP possono essere connessi/disconnessi selettivamente in base allo scenario, componendo insiemi di strumenti flessibili
+
+### Costi di MCP
+
+- **Cache killer**: La definizione JSON Schema di ogni strumento MCP viene concatenata all'inizio del prefisso KV-Cache. Aggiungere o rimuovere uno strumento MCP = **tutta la cache invalidata dall'inizio**. Connettere/disconnettere frequentemente server MCP riduce drasticamente il tasso di successo della cache
+- **Gonfiamento del prefisso**: Gli Schema degli strumenti MCP sono tipicamente più grandi degli strumenti integrati (descrizioni dettagliate dei parametri, valori enum, ecc.). Molti strumenti MCP aumentano significativamente il conteggio dei token nell'area Tools, riducendo lo spazio di contesto disponibile per i Messages
+- **Overhead di latenza**: Le chiamate agli strumenti MCP richiedono comunicazione tra processi (JSON-RPC su stdio/SSE), un ordine di grandezza più lento delle chiamate a funzioni integrate
+- **Rischio di stabilità**: I server MCP sono processi esterni che possono bloccarsi, andare in timeout o restituire formati inattesi, richiedendo gestione degli errori aggiuntiva
+
+### Raccomandazioni pratiche
+
+| Scenario | Raccomandazione |
+|----------|----------------|
+| Conversazioni lunghe, interazione frequente | Minimizzare il numero di strumenti MCP per proteggere la stabilità del prefisso di cache |
+| Compiti brevi, operazioni una tantum | Usare liberamente gli strumenti MCP; l'impatto sulla cache è limitato |
+| Aggiunta/rimozione frequente di server MCP | Ogni modifica attiva una ricostruzione completa della cache; considerare di fissare l'insieme di strumenti |
+| Schema di strumenti sovradimensionati | Ridurre descrizioni ed enum per diminuire il consumo di token nel prefisso |
+
+Nel pannello Context di cc-viewer, gli strumenti MCP sono visualizzati accanto agli strumenti integrati nell'area Tools, offrendo una vista chiara delle dimensioni dello Schema di ogni strumento e del suo contributo al prefisso di cache.

package/concepts/it/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Inquinamento del contesto dell'API di traduzione
+
+## Contesto
+
+CC-Viewer include una funzionalità di traduzione integrata (`POST /api/translate`) basata sull'API Messages di Anthropic. Nell'implementazione iniziale, le richieste di traduzione riutilizzavano le credenziali di autenticazione memorizzate nella cache della sessione di Claude Code — inclusi gli header `x-api-key` e `authorization`. Questo ha causato un problema sottile ma grave: i risultati delle traduzioni restituivano frequentemente contenuti irrilevanti.
+
+## Causa principale
+
+### Differenza fondamentale tra i due metodi di autenticazione
+
+L'API di Anthropic supporta due metodi di autenticazione:
+
+| Metodo | Header | Origine tipica | Caratteristiche |
+|--------|--------|----------------|-----------------|
+| Chiave API | `x-api-key: sk-ant-...` | Variabile d'ambiente / Console | Senza stato, ogni richiesta è indipendente |
+| Token OAuth | `authorization: Bearer sessionToken` | Login con abbonamento Claude Code | Legato alla sessione, il server mantiene l'associazione del contesto |
+
+La differenza chiave: **le chiavi API sono senza stato (stateless)** — ogni richiesta è completamente indipendente; mentre **i token di sessione OAuth sono con stato (stateful)** — il server di Anthropic associa le richieste che utilizzano lo stesso token allo stesso contesto di sessione.
+
+### Catena di inquinamento
+
+Quando Claude Code utilizza il login OAuth tramite abbonamento, il flusso di autenticazione si presenta così:
+
+```
+Conversazione principale Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                                 ↑
+Richiesta di traduzione CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Poiché le richieste di traduzione riutilizzavano lo stesso token di sessione, il server di Anthropic poteva associare le richieste di traduzione al contesto della conversazione principale di Claude Code. Questo causa:
+
+1. **I risultati della traduzione sono influenzati dal contesto della conversazione principale**: Il prompt di sistema della richiesta di traduzione è "sei un traduttore", ma il contesto del server contiene ancora la cronologia della conversazione di Claude Code, potenzialmente interferendo con il modello
+2. **La conversazione principale viene disturbata dalle richieste di traduzione**: Il contenuto delle richieste di traduzione (frammenti di testo dell'interfaccia) può essere iniettato nel contesto della conversazione principale, causando deviazioni nelle risposte di Claude Code
+3. **Comportamento imprevedibile**: Poiché l'inquinamento del contesto è un comportamento lato server, il client non può rilevarlo né controllarlo
+
+## Lezioni apprese
+
+- **I token di sessione OAuth non sono "semplicemente un'altra chiave API"** — portano con sé lo stato lato server, riutilizzarli significa condividere il contesto
+- **Le chiamate interne ai servizi dovrebbero utilizzare un'autenticazione indipendente e senza stato** per evitare l'associazione con le sessioni utente
+
+## Riferimenti
+
+- [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/)