cx-viewer 1.0.0

package/concepts/pl/Tool-TaskUpdate.md

@@ -0,0 +1,123 @@
+# TaskUpdate
+
+## Definicja
+
+Aktualizuje status, zawartość lub zależności zadania na liście zadań.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `taskId` | string | Tak | ID zadania do aktualizacji |
+| `status` | enum | Nie | Nowy status: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | Nie | Nowy tytuł |
+| `description` | string | Nie | Nowy opis |
+| `activeForm` | string | Nie | Tekst w czasie teraźniejszym ciągłym wyświetlany podczas wykonywania |
+| `owner` | string | Nie | Nowy odpowiedzialny za zadanie (nazwa agenta) |
+| `metadata` | object | Nie | Metadane do scalenia (ustawienie na null usuwa klucz) |
+| `addBlocks` | string[] | Nie | Lista ID zadań zablokowanych przez to zadanie |
+| `addBlockedBy` | string[] | Nie | Lista ID zadań poprzedzających, które blokują to zadanie |
+
+## Przepływ statusów
+
+```
+pending → in_progress → completed
+```
+
+`deleted` może być ustawiony z dowolnego statusu, trwale usuwa zadanie.
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Oznaczanie zadania jako `in_progress` przy rozpoczęciu pracy
+- Oznaczanie zadania jako `completed` po zakończeniu pracy
+- Ustawianie zależności między zadaniami
+- Aktualizacja zawartości zadania przy zmianie wymagań
+
+**Ważne zasady:**
+- Oznaczaj jako `completed` tylko po pełnym ukończeniu zadania
+- W przypadku błędów lub blokad zachowaj status `in_progress`
+- Nie oznaczaj jako `completed` gdy testy nie przechodzą, implementacja jest niepełna lub wystąpiły nierozwiązane błędy
+
+## Uwagi
+
+- Przed aktualizacją należy pobrać najnowszy stan zadania przez TaskGet, aby uniknąć przestarzałych danych
+- Po ukończeniu zadania wywołaj TaskList, aby znaleźć następne dostępne zadanie
+
+## Tekst oryginalny
+
+<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/pl/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## Definicja
+
+Tworzy nowy zespół do koordynacji wielu agentów pracujących nad projektem. Zespoły umożliwiają równoległe wykonywanie zadań poprzez wspólną listę zadań i wymianę wiadomości między agentami.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|----------|-----|----------|------|
+| `team_name` | string | Tak | Nazwa nowego zespołu |
+| `description` | string | Nie | Opis / cel zespołu |
+| `agent_type` | string | Nie | Typ / rola lidera zespołu |
+
+## Co zostaje utworzone
+
+- **Plik konfiguracyjny zespołu**: `~/.claude/teams/{team-name}/config.json` — przechowuje listę członków i metadane
+- **Katalog listy zadań**: `~/.claude/tasks/{team-name}/` — wspólna lista zadań dla wszystkich członków zespołu
+
+Zespoły mają relację 1:1 z listami zadań.
+
+## Przepływ pracy zespołu
+
+1. **TeamCreate** — utwórz zespół i jego listę zadań
+2. **TaskCreate** — zdefiniuj zadania dla zespołu
+3. **Agent** (z `team_name` + `name`) — uruchom członków zespołu dołączających do zespołu
+4. **TaskUpdate** — przypisz zadania do członków przez `owner`
+5. Członkowie pracują nad zadaniami i komunikują się przez **SendMessage**
+6. Zamknij członków po zakończeniu, następnie **TeamDelete** dla porządku
+
+## Powiązane narzędzia
+
+| Narzędzie | Przeznaczenie |
+|-----------|---------------|
+| `TeamDelete` | Usuń zespół i katalogi zadań |
+| `SendMessage` | Komunikacja między agentami w zespole |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Zarządzanie wspólną listą zadań |
+| `Agent` | Uruchom członków zespołu dołączających do zespołu |

package/concepts/pl/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## Definicja
+
+Usuwa zespół i powiązane katalogi zadań po zakończeniu pracy w ramach współpracy wielu agentów. Jest to odpowiednik porządkujący dla TeamCreate.
+
+## Zachowanie
+
+- Usuwa katalog zespołu: `~/.claude/teams/{team-name}/`
+- Usuwa katalog listy zadań: `~/.claude/tasks/{team-name}/`
+- Czyści kontekst zespołu z bieżącej sesji
+
+**Ważne**: TeamDelete zakończy się błędem, jeśli zespół nadal ma aktywnych członków. Członkowie zespołu muszą najpierw zostać poprawnie zamknięci za pomocą żądań shutdown wysyłanych przez SendMessage.
+
+## Typowe użycie
+
+TeamDelete jest wywoływany na końcu przepływu pracy zespołu:
+
+1. Wszystkie zadania są ukończone
+2. Członkowie zespołu są zamykani przez `SendMessage` z `shutdown_request`
+3. **TeamDelete** usuwa katalogi zespołu i zadań
+
+## Powiązane narzędzia
+
+| Narzędzie | Przeznaczenie |
+|-----------|---------------|
+| `TeamCreate` | Utwórz nowy zespół i jego listę zadań |
+| `SendMessage` | Komunikacja z członkami zespołu / wysyłanie żądań shutdown |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Zarządzanie wspólną listą zadań |
+| `Agent` | Uruchom członków zespołu dołączających do zespołu |

package/concepts/pl/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## Definicja
+
+Pobiera zawartość strony internetowej pod podanym URL, konwertuje HTML na markdown i przetwarza zawartość za pomocą modelu AI zgodnie z promptem.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `url` | string (URI) | Tak | Pełny URL do pobrania |
+| `prompt` | string | Tak | Opis informacji do wyodrębnienia ze strony |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Pobieranie zawartości publicznych stron internetowych
+- Przeglądanie dokumentacji online
+- Wyodrębnianie określonych informacji ze stron internetowych
+
+**Nieodpowiednie zastosowanie:**
+- URL wymagające uwierzytelnienia (Google Docs, Confluence, Jira, GitHub itp.) — należy najpierw poszukać dedykowanego narzędzia MCP
+- URL GitHub — preferuj użycie `gh` CLI
+
+## Uwagi
+
+- URL musi być pełnym, prawidłowym URL
+- HTTP jest automatycznie aktualizowane do HTTPS
+- Zbyt duża zawartość może zostać podsumowana
+- Zawiera 15-minutowy samoczyszczący się cache
+- Gdy URL przekierowuje na inny host, narzędzie zwraca URL przekierowania — należy ponowić żądanie z nowym URL
+- Jeśli dostępne jest narzędzie web fetch dostarczane przez MCP, preferuj jego użycie
+
+## Tekst oryginalny
+
+<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/pl/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## Definicja
+
+Wykonuje zapytanie do wyszukiwarki, zwracając wyniki wyszukiwania w celu uzyskania aktualnych informacji.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `query` | string | Tak | Zapytanie wyszukiwania (minimum 2 znaki) |
+| `allowed_domains` | string[] | Nie | Uwzględnij tylko wyniki z tych domen |
+| `blocked_domains` | string[] | Nie | Wyklucz wyniki z tych domen |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Uzyskiwanie najnowszych informacji wykraczających poza datę odcięcia wiedzy modelu
+- Wyszukiwanie bieżących wydarzeń i najnowszych danych
+- Wyszukiwanie najnowszej dokumentacji technicznej
+
+## Uwagi
+
+- Wyniki wyszukiwania są zwracane w formacie hiperłączy markdown
+- Po użyciu należy dołączyć sekcję "Sources:" na końcu odpowiedzi z listą odpowiednich URL
+- Obsługuje filtrowanie domen (uwzględnianie/wykluczanie)
+- W zapytaniach wyszukiwania należy używać bieżącego roku
+- Dostępne tylko w USA
+
+## Tekst oryginalny
+
+<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/pl/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## Definicja
+
+Zapisuje zawartość do lokalnego systemu plików. Jeśli plik już istnieje, nadpisuje go.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `file_path` | string | Tak | Bezwzględna ścieżka do pliku (musi być bezwzględna) |
+| `content` | string | Tak | Zawartość do zapisania |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Tworzenie nowych plików
+- Gdy wymagane jest całkowite przepisanie zawartości pliku
+
+**Nieodpowiednie zastosowanie:**
+- Modyfikacja lokalnej zawartości pliku — należy użyć Edit
+- Nie należy proaktywnie tworzyć plików dokumentacji (*.md) ani README, chyba że użytkownik wyraźnie o to prosi
+
+## Uwagi
+
+- Jeśli plik docelowy już istnieje, należy go najpierw odczytać za pomocą Read, w przeciwnym razie operacja się nie powiedzie
+- Nadpisuje całą zawartość istniejącego pliku
+- Preferuj Edit do edycji istniejących plików, Write służy tylko do tworzenia nowych plików lub całkowitego przepisywania
+
+## Tekst oryginalny
+
+<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/pl/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## Definicja
+
+Wykonuje kod Python w jądrze Jupyter bieżącego pliku notebook.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `code` | string | Tak | Kod Python do wykonania |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Wykonywanie kodu w środowisku Jupyter notebook
+- Testowanie fragmentów kodu
+- Analiza danych i obliczenia
+
+**Nieodpowiednie zastosowanie:**
+- Wykonywanie kodu poza środowiskiem Jupyter — należy użyć Bash
+- Modyfikacja plików — należy użyć Edit lub Write
+
+## Uwagi
+
+- To jest narzędzie MCP (Model Context Protocol), dostarczane przez integrację z IDE
+- Kod jest wykonywany w bieżącym jądrze Jupyter, stan jest zachowywany między wywołaniami
+- O ile użytkownik wyraźnie nie poprosi, należy unikać deklarowania zmiennych lub modyfikowania stanu jądra
+- Po restarcie jądra stan zostaje utracony
+
+## Tekst oryginalny
+
+<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/pl/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definicja
+
+Pobiera informacje diagnostyczne języka z VS Code, w tym błędy składni, błędy typów, ostrzeżenia lint itp.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `uri` | string | Nie | URI pliku. Jeśli nie podano, pobiera diagnostykę wszystkich plików |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Sprawdzanie problemów semantycznych kodu: składnia, typy, lint itp.
+- Weryfikacja po edycji kodu, czy nie wprowadzono nowych błędów
+- Zastępowanie poleceń Bash do sprawdzania jakości kodu
+
+**Nieodpowiednie zastosowanie:**
+- Uruchamianie testów — należy użyć Bash
+- Sprawdzanie błędów runtime — należy użyć Bash do wykonania kodu
+
+## Uwagi
+
+- To jest narzędzie MCP (Model Context Protocol), dostarczane przez integrację z IDE
+- Dostępne tylko w środowisku VS Code / IDE
+- Preferuj użycie tego narzędzia zamiast poleceń Bash do sprawdzania problemów z kodem
+
+## Tekst oryginalny
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/pl/Tools.md

@@ -0,0 +1,67 @@
+# Przegląd narzędzi Claude Code
+
+Claude Code udostępnia modelowi zestaw wbudowanych narzędzi poprzez mechanizm tool_use API Anthropic. Tablica `tools` w każdym żądaniu MainAgent zawiera pełne definicje JSON Schema tych narzędzi, a model wywołuje je w odpowiedzi poprzez bloki content `tool_use`.
+
+Poniżej znajduje się kategoryzowany indeks wszystkich narzędzi.
+
+## System agentów
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [Task](Tool-Task.md) | Uruchomienie sub-agenta (SubAgent) do obsługi złożonych wieloetapowych zadań |
+| [TaskOutput](Tool-TaskOutput.md) | Pobranie wyniku zadania w tle |
+| [TaskStop](Tool-TaskStop.md) | Zatrzymanie działającego zadania w tle |
+| [TaskCreate](Tool-TaskCreate.md) | Utworzenie wpisu na strukturalnej liście zadań |
+| [TaskGet](Tool-TaskGet.md) | Pobranie szczegółów zadania |
+| [TaskUpdate](Tool-TaskUpdate.md) | Aktualizacja statusu zadania, zależności itp. |
+| [TaskList](Tool-TaskList.md) | Wyświetlenie listy wszystkich zadań |
+
+## Operacje na plikach
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [Read](Tool-Read.md) | Odczyt zawartości pliku (obsługa tekstu, obrazów, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Edycja pliku przez precyzyjne zastępowanie ciągów znaków |
+| [Write](Tool-Write.md) | Zapis lub nadpisanie pliku |
+| [NotebookEdit](Tool-NotebookEdit.md) | Edycja komórek Jupyter notebook |
+
+## Wyszukiwanie
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [Glob](Tool-Glob.md) | Wyszukiwanie plików według wzorca nazwy |
+| [Grep](Tool-Grep.md) | Wyszukiwanie zawartości plików oparte na ripgrep |
+
+## Terminal
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [Bash](Tool-Bash.md) | Wykonywanie poleceń shell |
+
+## Web
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [WebFetch](Tool-WebFetch.md) | Pobieranie zawartości stron internetowych i przetwarzanie przez AI |
+| [WebSearch](Tool-WebSearch.md) | Zapytania do wyszukiwarki |
+
+## Planowanie i interakcja
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Wejście w tryb planowania, projektowanie planu wdrożenia |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Wyjście z trybu planowania i przesłanie planu do zatwierdzenia przez użytkownika |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Zadanie pytania użytkownikowi w celu uzyskania wyjaśnienia lub decyzji |
+
+## Rozszerzenia
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [Skill](Tool-Skill.md) | Wykonanie umiejętności (slash command) |
+
+## Integracja z IDE
+
+| Narzędzie | Przeznaczenie |
+|------|------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Pobranie informacji diagnostycznych języka z VS Code |
+| [executeCode](Tool-executeCode.md) | Wykonanie kodu w jądrze Jupyter |

package/concepts/pl/ToolsFirst.md

@@ -0,0 +1,77 @@
+# Dlaczego Tools są wyświetlane jako pierwsze?
+
+W panelu kontekstu cc-viewer **Tools pojawiają się przed System Prompt i Messages**. Ta kolejność dokładnie odzwierciedla **sekwencję prefiksu KV-Cache w Anthropic API**.
+
+## Sekwencja prefiksu KV-Cache
+
+Gdy Anthropic API buduje KV-Cache, łączy kontekst w prefiks w tej **stałej kolejności**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+Oznacza to, że **Tools znajdują się przed System Prompt na samym początku prefiksu cache**.
+
+## Dlaczego Tools mają większy wpływ na cache niż System?
+
+W dopasowywaniu prefiksu KV-Cache **wcześniejsza treść jest bardziej krytyczna** — każda zmiana unieważnia wszystko, co po niej następuje:
+
+1. **Dopasowywanie prefiksu zaczyna się od początku**: KV-Cache porównuje bieżące żądanie z zbuforowanym prefiksem token po tokenie od początku. W momencie znalezienia niezgodności cała późniejsza treść zostaje unieważniona.
+
+2. **Zmiana Tools = cały cache unieważniony**: Ponieważ Tools są na pierwszym miejscu, każda zmiana w definicjach narzędzi (nawet dodanie lub usunięcie jednego MCP tool) **przerywa prefiks od samego początku**, unieważniając cały zbuforowany System Prompt i Messages.
+
+3. **Zmiana System = cache Messages unieważniony**: System Prompt znajduje się w środku, więc jego zmiany unieważniają tylko następującą po nim część Messages.
+
+4. **Zmiana Messages = dotyczy tylko końca**: Messages są na końcu, więc dołączanie nowych wiadomości unieważnia jedynie niewielki końcowy segment — cache Tools i System pozostaje nienaruszony.
+
+## Praktyczny wpływ
+
+| Typ zmiany | Wpływ na cache | Typowy scenariusz |
+|------------|---------------|-------------------|
+| Tool dodane/usunięte | **Pełne unieważnienie** | Połączenie/rozłączenie serwera MCP, włączenie/wyłączenie wtyczki IDE |
+| Zmiana System Prompt | Utrata cache Messages | Edycja CLAUDE.md, wstrzyknięcie system reminder |
+| Nowa wiadomość dodana | Tylko przyrost końcowy | Normalny przepływ rozmowy (najczęstszy, najtańszy) |
+
+Dlatego `tools_change` w [CacheRebuild](CacheRebuild.md) jest zazwyczaj najdroższym powodem przebudowy — przerywa łańcuch prefiksu na samym początku.
+
+## Dlaczego definicje narzędzi są umieszczone przed "mózgiem"?
+
+Z perspektywy cache'owania, umieszczenie Tools na pierwszym miejscu jest faktem technicznym. Ale z perspektywy projektowania kognitywnego ta kolejność jest równie logiczna — **Tools to ręce i nogi, System Prompt to mózg**.
+
+Przed podjęciem działania człowiek musi rozpoznać, jakie kończyny i narzędzia ma do dyspozycji. Niemowlę nie rozumie najpierw zasad świata (System), a potem uczy się chwytać — najpierw wyczuwa, że ma ręce i nogi, a następnie stopniowo rozumie zasady przez interakcję ze środowiskiem. Podobnie LLM musi wiedzieć, jakie narzędzia może wywołać (czytanie plików, pisanie kodu, wyszukiwanie, wykonywanie poleceń) przed otrzymaniem instrukcji zadania (System Prompt), aby móc dokładnie ocenić "co mogę zrobić" i "jak powinienem to zrobić" podczas przetwarzania instrukcji.
+
+Gdyby było odwrotnie — najpierw powiedzieć modelowi "twoim zadaniem jest refaktoryzacja tego modułu", potem "masz narzędzia Read, Edit, Bash" — modelowi brakowałoby kluczowych informacji o granicach swoich możliwości przy rozumieniu zadania, co mogłoby prowadzić do nierealistycznych planów lub pominięcia dostępnych podejść.
+
+**Poznaj swoje karty zanim zdecydujesz, jak grać.** To jest logika kognitywna stojąca za umieszczeniem Tools przed System.
+
+## Dlaczego narzędzia MCP również znajdują się na tej pozycji?
+
+Narzędzia MCP (Model Context Protocol), podobnie jak narzędzia wbudowane, są umieszczone na samym początku obszaru Tools. Zrozumienie pozycji MCP w kontekście pomaga ocenić jego realne korzyści i koszty.
+
+### Zalety MCP
+
+- **Rozszerzenie możliwości**: MCP pozwala modelom na dostęp do usług zewnętrznych (zapytania do baz danych, wywołania API, operacje IDE, sterowanie przeglądarką itp.), przekraczając granice narzędzi wbudowanych
+- **Otwarty ekosystem**: Każdy może zaimplementować serwer MCP; model zyskuje nowe możliwości bez ponownego trenowania
+- **Ładowanie na żądanie**: Serwery MCP mogą być selektywnie łączone/rozłączane w zależności od scenariusza, elastycznie komponując zestawy narzędzi
+
+### Koszty MCP
+
+- **Zabójca cache'u**: Definicja JSON Schema każdego narzędzia MCP jest dołączana na samym początku prefiksu KV-Cache. Dodanie lub usunięcie jednego narzędzia MCP = **cały cache unieważniony od początku**. Częste łączenie/rozłączanie serwerów MCP drastycznie obniża współczynnik trafień cache'u
+- **Puchnięcie prefiksu**: Schematy narzędzi MCP są typowo większe niż narzędzia wbudowane (szczegółowe opisy parametrów, wartości enum itp.). Wiele narzędzi MCP znacząco zwiększa liczbę tokenów w obszarze Tools, zmniejszając przestrzeń kontekstu dostępną dla Messages
+- **Narzut opóźnienia**: Wywołania narzędzi MCP wymagają komunikacji międzyprocesowej (JSON-RPC przez stdio/SSE), o rząd wielkości wolniejszej niż wywołania wbudowanych funkcji
+- **Ryzyko stabilności**: Serwery MCP to procesy zewnętrzne, które mogą się zawiesić, przekroczyć limit czasu lub zwrócić nieoczekiwane formaty, wymagając dodatkowej obsługi błędów
+
+### Praktyczne rekomendacje
+
+| Scenariusz | Rekomendacja |
+|-----------|-------------|
+| Długie rozmowy, częsta interakcja | Minimalizować liczbę narzędzi MCP, aby chronić stabilność prefiksu cache'u |
+| Krótkie zadania, jednorazowe operacje | Swobodnie używać narzędzi MCP; wpływ na cache jest ograniczony |
+| Częste dodawanie/usuwanie serwerów MCP | Każda zmiana wywołuje pełną przebudowę cache'u; rozważyć ustalenie zestawu narzędzi |
+| Zbyt duże Tool Schemas | Skrócić opisy i enumy, aby zmniejszyć zużycie tokenów prefiksu |
+
+W panelu Context cc-viewer narzędzia MCP są wyświetlane obok narzędzi wbudowanych w obszarze Tools, dając jasny widok na rozmiar Schema każdego narzędzia i jego wkład w prefiks cache'u.

package/concepts/pl/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Zanieczyszczenie kontekstu w Translate API
+
+## Kontekst
+
+CC-Viewer zawiera wbudowaną funkcję tłumaczenia (`POST /api/translate`) opartą na Anthropic Messages API. We wczesnej implementacji żądania tłumaczenia ponownie wykorzystywały buforowane dane uwierzytelniające z sesji Claude Code — w tym zarówno nagłówki `x-api-key`, jak i `authorization`. Powodowało to subtelny, ale poważny problem: wyniki tłumaczeń często zwracały nieistotną treść.
+
+## Przyczyna źródłowa
+
+### Fundamentalna różnica między dwoma metodami uwierzytelniania
+
+Anthropic API obsługuje dwie metody uwierzytelniania:
+
+| Metoda | Nagłówek | Typowe źródło | Charakterystyka |
+|--------|----------|---------------|-----------------|
+| Klucz API | `x-api-key: sk-ant-...` | Zmienna środowiskowa / Console | Bezstanowy, każde żądanie jest niezależne |
+| Token OAuth | `authorization: Bearer sessionToken` | Logowanie subskrypcyjne Claude Code | Powiązany z sesją, serwer utrzymuje powiązanie kontekstu |
+
+Kluczowa różnica: **Klucze API są bezstanowe** — każde żądanie jest całkowicie niezależne; natomiast **tokeny sesji OAuth są stanowe** — serwer Anthropic wiąże żądania używające tego samego tokena z tym samym kontekstem sesji.
+
+### Łańcuch zanieczyszczenia
+
+Gdy Claude Code używa logowania subskrypcyjnego OAuth, przepływ uwierzytelniania wygląda następująco:
+
+```
+Główna rozmowa Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                        ↑
+Żądanie tłumaczenia CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Ponieważ żądania tłumaczenia ponownie wykorzystywały ten sam token sesji, serwer Anthropic może powiązać żądania tłumaczenia z kontekstem głównej rozmowy Claude Code. Powoduje to:
+
+1. **Wyniki tłumaczenia pod wpływem kontekstu głównej rozmowy**: Prompt systemowy żądania tłumaczenia to „jesteś tłumaczem", ale kontekst serwera nadal zawiera historię rozmów Claude Code, co może zakłócać działanie modelu
+2. **Główna rozmowa zakłócana przez żądania tłumaczenia**: Treść żądań tłumaczenia (fragmenty tekstu UI) może zostać wstrzyknięta do kontekstu głównej rozmowy, powodując odchylenia w odpowiedziach Claude Code
+3. **Nieprzewidywalne zachowanie**: Ponieważ zanieczyszczenie kontekstu jest zachowaniem po stronie serwera, klient nie może go wykryć ani kontrolować
+
+## Wnioski
+
+- **Tokeny sesji OAuth to nie „po prostu kolejny klucz API"** — niosą ze sobą stan po stronie serwera, a ich ponowne użycie oznacza współdzielenie kontekstu
+- **Wewnętrzne wywołania usług powinny używać niezależnego, bezstanowego uwierzytelniania**, aby uniknąć powiązania z sesjami użytkowników
+
+## Odnośniki
+
+- [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/)