cx-viewer 1.0.0

package/concepts/uk/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## Визначення
+
+Створює нову команду для координації кількох агентів, що працюють над проєктом. Команди забезпечують паралельне виконання завдань через спільний список завдань та обмін повідомленнями між агентами.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `team_name` | string | Так | Назва нової команди |
+| `description` | string | Ні | Опис / призначення команди |
+| `agent_type` | string | Ні | Тип / роль керівника команди |
+
+## Що створюється
+
+- **Файл конфігурації команди**: `~/.claude/teams/{team-name}/config.json` — зберігає список учасників і метадані
+- **Каталог списку завдань**: `~/.claude/tasks/{team-name}/` — спільний список завдань для всіх учасників команди
+
+Команди мають відповідність 1:1 зі списками завдань.
+
+## Робочий процес команди
+
+1. **TeamCreate** — створити команду та її список завдань
+2. **TaskCreate** — визначити завдання для команди
+3. **Agent** (з `team_name` + `name`) — запустити учасників, які приєднуються до команди
+4. **TaskUpdate** — призначити завдання учасникам через `owner`
+5. Учасники виконують завдання та спілкуються через **SendMessage**
+6. Завершити роботу учасників післ�� закінчення, потім **TeamDelete** для очищення
+
+## Пов'язані інструменти
+
+| Інструмент | Призначення |
+|------------|-------------|
+| `TeamDelete` | Видалити команду та каталоги завдань |
+| `SendMessage` | Міжагентне спілкування всередині команди |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Управління спільним списком завдань |
+| `Agent` | Запустити учасників, які приєднуються до команди |

package/concepts/uk/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## Визначення
+
+Видаляє команду та пов'язані з нею каталоги завдань після завершення роботи в режимі багатоагентної співпраці. Це інструмент очищення, який є парним до TeamCreate.
+
+## Поведінка
+
+- Видаляє каталог команди: `~/.claude/teams/{team-name}/`
+- Видаляє каталог завдань: `~/.claude/tasks/{team-name}/`
+- Очищає контекст команди з поточної сесії
+
+**Важливо**: TeamDelete завершиться помилкою, якщо в команді ще є активні учасники. Спочатку необхідно коректно завершити роботу учасників через запити на завершення роботи в SendMessage.
+
+## Типове використання
+
+TeamDelete викликається в кінці робочого процесу команди:
+
+1. Всі завдання виконано
+2. Учасники завершують роботу через `SendMessage` з `shutdown_request`
+3. **TeamDelete** видаляє каталоги команди та завдань
+
+## Пов'язані інструменти
+
+| Інструмент | Призначення |
+|------------|-------------|
+| `TeamCreate` | Створити нову команду та її список завдань |
+| `SendMessage` | Спілкуватися з учасниками / надсилати запити на завершення роботи |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Управління спільним списком завдань |
+| `Agent` | Запустити учасників, які приєднуються до команди |

package/concepts/uk/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## Визначення
+
+Отримує вміст веб-сторінки за вказаним URL, конвертує HTML у markdown та обробляє вміст за допомогою AI-моделі відповідно до prompt.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `url` | string (URI) | Так | Повний URL для отримання |
+| `prompt` | string | Так | Описує, яку інформацію потрібно витягти зі сторінки |
+
+## Сценарії використання
+
+**Підходить для:**
+- Отримання вмісту публічних веб-сторінок
+- Перегляд онлайн-документації
+- Витягування конкретної інформації з веб-сторінки
+
+**Не підходить для:**
+- URL, що потребують автентифікації (Google Docs, Confluence, Jira, GitHub тощо) — спочатку шукайте спеціалізований MCP-інструмент
+- URL GitHub — пріоритетно використовуйте `gh` CLI
+
+## Примітки
+
+- URL повинен бути повним дійсним URL
+- HTTP автоматично оновлюється до HTTPS
+- При занадто великому вмісті результати можуть бути зведені
+- Містить 15-хвилинний кеш з автоочищенням
+- Коли URL перенаправляє на інший хост, інструмент повертає URL перенаправлення, і потрібно зробити новий запит з новим URL
+- Якщо доступний MCP-інструмент web fetch, надавайте йому перевагу
+
+## Оригінальний текст
+
+<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/uk/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## Визначення
+
+Виконує запит до пошукової системи та повертає результати пошуку для отримання актуальної інформації.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `query` | string | Так | Пошуковий запит (мінімум 2 символи) |
+| `allowed_domains` | string[] | Ні | Включати результати лише з цих доменів |
+| `blocked_domains` | string[] | Ні | Виключити результати з цих доменів |
+
+## Сценарії використання
+
+**Підходить для:**
+- Отримання актуальної інформації, що виходить за межі дати відсічення знань моделі
+- Пошук поточних подій та найновіших даних
+- Пошук найактуальнішої технічної документації
+
+## Примітки
+
+- Результати пошуку повертаються у форматі markdown-гіперпосилань
+- Після використання обов'язково додайте розділ "Sources:" в кінці відповіді зі списком відповідних URL
+- Підтримує фільтрацію за доменами (включення/виключення)
+- У пошуковому запиті слід використовувати поточний рік
+- Доступний лише в США
+
+## Оригінальний текст
+
+<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/uk/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## Визначення
+
+Записує вміст у локальну файлову систему. Якщо файл вже існує, перезаписує його.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `file_path` | string | Так | Абсолютний шлях до файлу (повинен бути абсолютним) |
+| `content` | string | Так | Вміст для запису |
+
+## Сценарії використання
+
+**Підходить для:**
+- Створення нових файлів
+- Коли потрібно повністю переписати вміст файлу
+
+**Не підходить для:**
+- Зміна локальної частини файлу — слід використовувати Edit
+- Не слід проактивно створювати файли документації (*.md) або README, якщо користувач явно не просить
+
+## Примітки
+
+- Якщо цільовий файл вже існує, його потрібно спочатку прочитати через Read, інакше буде помилка
+- Перезаписує весь вміст існуючого файлу
+- Надавайте перевагу Edit для редагування існуючих файлів; Write використовується лише для створення нових файлів або повного перезапису
+
+## Оригінальний текст
+
+<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/uk/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## Визначення
+
+Виконує Python-код у Jupyter kernel поточного файлу notebook.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `code` | string | Так | Python-код для виконання |
+
+## Сценарії використання
+
+**Підходить для:**
+- Виконання коду в середовищі Jupyter notebook
+- Тестування фрагментів коду
+- Аналіз даних та обчислення
+
+**Не підходить для:**
+- Виконання коду поза середовищем Jupyter — слід використовувати Bash
+- Зміна файлів — слід використовувати Edit або Write
+
+## Примітки
+
+- Це MCP (Model Context Protocol) інструмент, наданий інтеграцією з IDE
+- Код виконується в поточному Jupyter kernel, стан зберігається між викликами
+- Якщо користувач явно не просить, уникайте оголошення змінних або зміни стану kernel
+- Після перезапуску kernel стан втрачається
+
+## Оригінальний текст
+
+<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/uk/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Визначення
+
+Отримує діагностичну інформацію мови з VS Code, включаючи синтаксичні помилки, помилки типів, попередження lint тощо.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `uri` | string | Ні | URI файлу. Якщо не вказано, отримує діагностику для всіх файлів |
+
+## Сценарії використання
+
+**Підходить для:**
+- Перевірка синтаксичних, типових, lint та інших семантичних проблем коду
+- Перевірка після редагування коду, чи не з'явилися нові помилки
+- Заміна команд Bash для перевірки якості коду
+
+**Не підходить для:**
+- Запуск тестів — слід використовувати Bash
+- Перевірка помилок виконання — слід використовувати Bash для виконання коду
+
+## Примітки
+
+- Це MCP (Model Context Protocol) інструмент, наданий інтеграцією з IDE
+- Доступний лише в середовищі VS Code / IDE
+- Надавайте перевагу цьому інструменту замість команд Bash для перевірки проблем коду
+
+## Оригінальний текст
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/uk/Tools.md

@@ -0,0 +1,67 @@
+# Перелік інструментів Claude Code
+
+Claude Code надає моделі набір вбудованих інструментів через механізм tool_use API Anthropic. Масив `tools` кожного запиту MainAgent містить повні визначення JSON Schema цих інструментів, і модель викликає їх через `tool_use` content block у відповіді.
+
+Нижче наведено категоризований індекс усіх інструментів.
+
+## Система агентів
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Task](Tool-Task.md) | Запуск підагента (SubAgent) для обробки складних багатокрокових завдань |
+| [TaskOutput](Tool-TaskOutput.md) | Отримання виводу фонового завдання |
+| [TaskStop](Tool-TaskStop.md) | Зупинка запущеного фонового завдання |
+| [TaskCreate](Tool-TaskCreate.md) | Створення запису структурованого списку завдань |
+| [TaskGet](Tool-TaskGet.md) | Отримання деталей завдання |
+| [TaskUpdate](Tool-TaskUpdate.md) | Оновлення статусу завдання, залежностей тощо |
+| [TaskList](Tool-TaskList.md) | Перелік усіх завдань |
+
+## Операції з файлами
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Read](Tool-Read.md) | Читання вмісту файлу (підтримка тексту, зображень, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Редагування файлу через точну заміну рядків |
+| [Write](Tool-Write.md) | Запис або перезапис файлу |
+| [NotebookEdit](Tool-NotebookEdit.md) | Редагування комірки Jupyter notebook |
+
+## Пошук
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Glob](Tool-Glob.md) | Пошук файлів за шаблоном імені файлу |
+| [Grep](Tool-Grep.md) | Пошук вмісту файлів на основі ripgrep |
+
+## Термінал
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Bash](Tool-Bash.md) | Виконання shell-команд |
+
+## Web
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [WebFetch](Tool-WebFetch.md) | Отримання вмісту веб-сторінки та обробка за допомогою AI |
+| [WebSearch](Tool-WebSearch.md) | Запит до пошукової системи |
+
+## Планування та взаємодія
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Вхід у режим планування, проєктування плану реалізації |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Вихід з режиму планування та подання плану на затвердження користувачем |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Запитання користувачу для уточнення або прийняття рішення |
+
+## Розширення
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Skill](Tool-Skill.md) | Виконання навички (slash command) |
+
+## Інтеграція з IDE
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Отримання діагностичної інформації мови VS Code |
+| [executeCode](Tool-executeCode.md) | Виконання коду в Jupyter kernel |

package/concepts/uk/ToolsFirst.md

@@ -0,0 +1,77 @@
+# Чому Tools відображаються першими?
+
+На панелі Context у cc-viewer **Tools з'являються перед System Prompt та Messages**. Такий порядок точно відображає **послідовність префікса KV-Cache в Anthropic API**.
+
+## Послідовність префікса KV-Cache
+
+Коли Anthropic API будує KV-Cache, він об'єднує контекст у префікс у такому **фіксованому порядку**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+Це означає, що **Tools розміщені перед System Prompt на самому початку префікса кешу**.
+
+## Чому Tools мають більшу вагу в кеші, ніж System?
+
+При зіставленні префіксів KV-Cache **більш раннє розташування контенту є більш критичним** — будь-яка зміна скасовує все, що йде після:
+
+1. **Зіставлення префіксів починається з початку**: KV-Cache порівнює поточний запит із кешованим префіксом token за token від початку. Щойно виявляється розбіжність, весь наступний контент стає недійсним.
+
+2. **Зміна Tools = весь кеш скасовано**: Оскільки Tools стоять першими, будь-яка зміна у визначеннях інструментів (навіть додавання або видалення одного MCP tool) **ламає префікс з самого початку**, роблячи недійсними весь кешований System Prompt та Messages.
+
+3. **Зміна System = кеш Messages скасовано**: System Prompt розташований посередині, тому його зміни скасовують лише наступну частину Messages.
+
+4. **Зміна Messages = впливає тільки на хвіст**: Messages знаходяться в кінці, тому додавання нових повідомлень скасовує лише невеликий кінцевий сегмент — кеш Tools та System залишається незайманим.
+
+## Практичний вплив
+
+| Тип зміни | Вплив на кеш | Типовий сценарій |
+|-----------|-------------|-----------------|
+| Tool додано/видалено | **Повне скасування** | Підключення/відключення MCP server, увімкнення/вимкнення плагіна IDE |
+| Зміна System Prompt | Втрата кешу Messages | Редагування CLAUDE.md, ін'єкція system reminder |
+| Додано нове повідомлення | Лише хвостове збільшення | Звичайний хід розмови (найпоширеніший, найдешевший) |
+
+Саме тому `tools_change` у [CacheRebuild](CacheRebuild.md) зазвичай є найдорожчою причиною перебудови — вона ламає ланцюг префіксів з самого початку.
+
+## Чому визначення інструментів розміщуються перед "мозком"?
+
+З точки зору кешування, розміщення Tools на першому місці — це технічний факт. Але з точки зору когнітивного дизайну цей порядок також логічний — **Tools — це руки і ноги, System Prompt — це мозок**.
+
+Перед тим як діяти, людина повинна усвідомити, які кінцівки та інструменти їй доступні. Немовля не спочатку розуміє правила світу (System), а потім вчиться хапати — воно спочатку відчуває, що має руки і ноги, а потім поступово розуміє правила через взаємодію з навколишнім середовищем. Аналогічно, LLM повинна знати, які інструменти може викликати (читання файлів, написання коду, пошук, виконання команд) до отримання інструкцій завдання (System Prompt), щоб точно оцінити "що я можу зробити" і "як мені це зробити" при обробці інструкцій.
+
+Якби порядок був зворотним — спочатку сказати моделі "твоє завдання — рефакторити цей модуль", потім "у тебе є інструменти Read, Edit, Bash" — моделі бракувало б критичної інформації про межі своїх можливостей при розумінні завдання, що могло б призвести до нереалістичних планів або пропуску доступних підходів.
+
+**Дізнайся, які карти на руках, перш ніж вирішувати, як грати.** Це когнітивна логіка розміщення Tools перед System.
+
+## Чому інструменти MCP теж знаходяться на цій позиції?
+
+Інструменти MCP (Model Context Protocol), як і вбудовані інструменти, розміщуються на самому початку області Tools. Розуміння позиції MCP в контексті допомагає оцінити його реальні переваги та витрати.
+
+### Переваги MCP
+
+- **Розширення можливостей**: MCP дозволяє моделям звертатися до зовнішніх сервісів (запити до баз даних, API-виклики, операції IDE, керування браузером тощо), виходячи за межі вбудованих інструментів
+- **Відкрита екосистема**: Будь-хто може реалізувати MCP-сервер; модель отримує нові можливості без перенавчання
+- **Завантаження на вимогу**: MCP-сервери можна підключати/відключати вибірково залежно від завдання, гнучко складаючи набори інструментів
+
+### Витрати MCP
+
+- **Вбивця кешу**: JSON Schema кожного MCP-інструменту конкатенується на самий початок префіксу KV-Cache. Додавання або видалення одного MCP-інструменту = **весь кеш інвалідується з самого початку**. Часте підключення/відключення MCP-серверів різко знижує відсоток влучань у кеш
+- **Роздування префіксу**: Schemas MCP-інструментів зазвичай більші за вбудовані (детальні описи параметрів, перерахування тощо). Велика кількість MCP-інструментів значно збільшує кількість токенів в області Tools, скорочуючи простір контексту для Messages
+- **Накладні витрати на затримку**: Виклики MCP-інструментів потребують міжпроцесної комунікації (JSON-RPC через stdio/SSE), на порядок повільніше за виклики вбудованих функцій
+- **Ризик стабільності**: MCP-сервери — це зовнішні процеси, які можуть аварійно завершитись, спричинити таймаут або повернути неочікуваний формат, потребуючи додаткової обробки помилок
+
+### Практичні рекомендації
+
+| Сценарій | Рекомендація |
+|----------|-------------|
+| Довгі розмови, часта взаємодія | Мінімізувати кількість MCP-інструментів для захисту стабільності префіксу кешу |
+| Короткі завдання, разові операції | Вільно використовувати MCP-інструменти; вплив на кеш обмежений |
+| Часте додавання/видалення MCP-серверів | Кожна зміна викликає повну перебудову кешу; розглянути фіксацію набору інструментів |
+| Занадто великі Tool Schemas | Скоротити описи та enum для зменшення витрат токенів префіксу |
+
+У панелі Context cc-viewer інструменти MCP відображаються поряд із вбудованими інструментами в області Tools, даючи наочне уявлення про розмір Schema кожного інструменту та його внесок у префікс кешу.

package/concepts/uk/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Забруднення контексту в Translate API
+
+## Передумови
+
+CC-Viewer містить вбудовану функцію перекладу (`POST /api/translate`), що працює на основі Anthropic Messages API. У ранній реалізації запити на переклад повторно використовували кешовані облікові дані автентифікації із сесії Claude Code — включаючи заголовки `x-api-key` та `authorization`. Це спричинило непомітну, але серйозну проблему: результати перекладу часто повертали нерелевантний вміст.
+
+## Кореневе причина
+
+### Фундаментальна різниця між двома методами автентифікації
+
+Anthropic API підтримує два методи автентифікації:
+
+| Метод | Заголовок | Типове джерело | Характеристики |
+|-------|-----------|----------------|----------------|
+| API-ключ | `x-api-key: sk-ant-...` | Змінна середовища / Console | Без стану, кожен запит незалежний |
+| OAuth-токен | `authorization: Bearer sessionToken` | Вхід за підпискою Claude Code | Прив'язаний до сесії, сервер підтримує асоціацію контексту |
+
+Ключова різниця: **API-ключі не зберігають стан** — кожен запит повністю незалежний; тоді як **OAuth-токени сесії зберігають стан** — сервер Anthropic асоціює запити з однаковим токеном з одним і тим самим контекстом сесії.
+
+### Ланцюг забруднення
+
+Коли Claude Code використовує OAuth-вхід за підпискою, потік автентифікації виглядає так:
+
+```
+Основна розмова Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                        ↑
+Запит перекладу CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Оскільки запити на переклад повторно використовували той самий токен сесії, сервер Anthropic може асоціювати запити на переклад із контекстом основної розмови Claude Code. Це призводить до:
+
+1. **Результати перекладу під впливом контексту основної розмови**: Системний промпт запиту на переклад — «ви перекладач», але серверний контекст все ще містить історію розмов Claude Code, що потенційно може впливати на модель
+2. **Основна розмова порушується запитами на переклад**: Вміст запитів на переклад (фрагменти тексту UI) може бути впроваджений у контекст основної розмови, спричиняючи відхилення у відповідях Claude Code
+3. **Непередбачувана поведінка**: Оскільки забруднення контексту — це поведінка на стороні сервера, клієнт не може її виявити або контролювати
+
+## Отримані уроки
+
+- **OAuth-токени сесії — це не «просто ще один API-ключ»** — вони несуть серверний стан, і їх повторне використання означає спільне використання контексту
+- **Внутрішні виклики сервісів повинні використовувати незалежну автентифікацію без стану**, щоб уникнути асоціації з користувацькими сесіями
+
+## Посилання
+
+- [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/)

package/concepts/uk/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — Найкраща Машина Бажань
+
+## Що таке UltraPlan
+
+UltraPlan — це **локалізована реалізація** нативної команди `/ultraplan` Claude Code від cc-viewer. Він дозволяє використовувати повні можливості `/ultraplan` у вашому локальному середовищі **без необхідності запуску офіційного віддаленого сервісу Claude**, спрямовуючи Claude Code на виконання складних завдань планування та реалізації з використанням **мультиагентної співпраці**.
+
+Порівняно зі звичайним режимом Plan або Agent Team, UltraPlan може:
+- Автоматично оцінювати складність завдання та обирати оптимальну стратегію планування
+- Розгортати кілька паралельних агентів для дослідження кодової бази з різних вимірів
+- Залучати зовнішні дослідження (webSearch) для отримання найкращих галузевих практик
+- Автоматично формувати команду Code Review після виконання плану для ревью коду
+- Створювати повний замкнений цикл **План → Виконання → Ревью → Виправлення**
+
+---
+
+## Важливі зауваження
+
+### 1. UltraPlan не всемогутній
+UltraPlan — це потужніша машина бажань, але це не означає, що кожне бажання може бути здійснене. Він потужніший за Plan та Agent Team, але не може безпосередньо «заробити вам гроші». Враховуйте розумну гранулярність завдань — розбивайте великі цілі на виконувані завдання середнього розміру замість того, щоб намагатися досягти всього за один раз.
+
+### 2. Наразі найефективніший для програмних проєктів
+Шаблони та робочі процеси UltraPlan глибоко оптимізовані для програмних проєктів. Інші сценарії (документація, аналіз даних тощо) можна спробувати, але, можливо, варто зачекати на адаптації в майбутніх версіях.
+
+### 3. Час виконання та вимоги до контекстного вікна
+- Успішний запуск UltraPlan зазвичай займає **30 хвилин або більше**
+- Вимагає, щоб MainAgent мав велике контекстне вікно (рекомендується модель Opus з контекстом 1M)
+- Якщо у вас лише модель на 200K, **обов'язково виконайте `/clear` контексту перед запуском**
+- Команда `/compact` Claude Code працює погано при недостатньому контекстному вікні — не допускайте вичерпання простору
+- Підтримання достатнього простору контексту є критично важливою передумовою для успішного виконання UltraPlan
+
+Якщо у вас є запитання чи пропозиції щодо локалізованого UltraPlan, не соромтеся відкривати [Issues на GitHub](https://github.com/anthropics/claude-code/issues) для обговорення та співпраці.
+
+---
+
+## Як це працює
+
+UltraPlan пропонує два режими роботи:
+
+### Автоматичний режим
+Автоматично аналізує складність завдання (оцінка 4-12) та направляє до різних стратегій:
+
+| Маршрут | Оцінка | Стратегія |
+|---------|--------|-----------|
+| Маршрут A | 4-6 | Легке планування з прямим дослідженням коду |
+| Маршрут B | 7-9 | Планування зі структурними діаграмами (Mermaid / ASCII) |
+| Маршрут C | 10-12 | Мультиагентне дослідження + замкнений цикл ревью |
+
+### Примусовий режим
+Безпосередньо активує повний мультиагентний робочий процес Маршруту C:
+1. Розгортання до 5 паралельних агентів для одночасного дослідження кодової бази (архітектура, ідентифікація файлів, оцінка ризиків тощо)
+2. Опціональне розгортання дослідницького агента для вивчення галузевих рішень через webSearch
+3. Синтез усіх результатів агентів у детальний план реалізації
+4. Розгортання агента-рев'юера для ретельної перевірки плану з кількох точок зору
+5. Виконання плану після затвердження
+6. Автоматичне формування команди Code Review для перевірки якості коду після реалізації

package/concepts/zh/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（请求体增量对比）
+
+## 背景
+
+Codex 的 MainAgent 采用全量上下文发送机制——每次请求都会携带完整的对话历史、system prompt、工具定义等内容。这意味着随着对话推进，请求体会越来越庞大，直接查看原始 Body 很难快速定位"这一轮到底新增了什么"。
+
+Body Diff JSON 正是为了解决这个问题：它自动对比前后两个 MainAgent 请求的 body，提炼出增量部分，让你一眼看清本次请求实际新增的内容。
+
+## 工作原理
+
+1. **识别连续的 MainAgent 请求**：当前请求必须是 MainAgent 类型，且存在上一个 MainAgent 请求
+2. **逐字段对比**：遍历请求体的所有顶层字段，跳过 `_` 前缀的内部属性
+3. **智能差异提取**：
+   - 新增的字段：直接展示
+   - 删除的字段：不显示（通常不影响理解）
+   - 变更的字段：展示当前值
+   - `messages` 数组特殊处理：只展示新增的消息（因为正常对话是追加模式，前缀消息不变）
+4. **请求体缩小检测**：如果当前请求体比上一个更小，说明发生了上下文截断或会话重置，此时会显示提示信息而非 diff
+
+## 典型场景
+
+在一轮正常对话中，Body Diff JSON 通常只包含：
+- `messages`：新增的 1~2 条消息（用户的输入 + 上一轮助手的回复）
+
+如果你看到 diff 中出现了 `system`、`tools`、`model` 等字段的变更，说明本轮请求发生了配置变化，这往往也是缓存重建的原因。
+
+## 使用方式
+
+- Body Diff JSON 显示在 MainAgent 请求的详情面板中
+- 点击标题可展开/收起
+- 支持 JSON 和 Text 两种查看模式，以及一键复制
+- 在左上角 **CX-Viewer → 全局设置** 中，可以设置"默认展开 Body Diff JSON"

package/concepts/zh/BodyFields.md

@@ -0,0 +1,42 @@
+# Request Body 字段说明
+
+Claude API `/v1/messages` 请求体的顶层字段说明。
+
+## 字段列表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| **model** | string | 使用的模型名称，如 `claude-opus-4-6`、`claude-sonnet-4-6` |
+| **messages** | array | 对话消息历史。每条消息包含 `role`（user/assistant）和 `content`（文本、图片、tool_use、tool_result 等 block 数组） |
+| **system** | array | System prompt。包含 Codex 的核心指令、工具使用说明、环境信息、CLAUDE.md 内容等。带 `cache_control` 的块会被 prompt caching |
+| **tools** | array | 可用工具定义列表。每个工具包含 `name`、`description` 和 `input_schema`（JSON Schema）。MainAgent 通常有 20+ 工具，SubAgent 只有少量 |
+| **metadata** | object | 请求元数据，通常包含 `user_id` 用于标识用户 |
+| **max_tokens** | number | 模型单次回复的最大 token 数，如 `16000`、`64000` |
+| **thinking** | object | 扩展思考配置。`type: "enabled"` 开启思考模式，`budget_tokens` 控制思考 token 上限 |
+| **context_management** | object | 上下文管理配置。`truncation: "auto"` 允许 Codex 自动截断过长的消息历史 |
+| **output_config** | object | 输出配置，如 `format` 设置 |
+| **stream** | boolean | 是否启用流式响应。Codex 始终使用 `true` |
+
+## messages 结构
+
+每条消息的 `content` 是一个 block 数组，常见类型：
+
+- **text**: 普通文本内容
+- **tool_use**: 模型调用工具（含 `name`、`input`）
+- **tool_result**: 工具执行结果（含 `tool_use_id`、`content`）
+- **image**: 图片内容（base64 或 URL）
+- **thinking**: 模型的思考过程（扩展思考模式）
+
+## system 结构
+
+system prompt 数组中通常包含：
+
+1. **核心 agent 指令**（"You are Codex..."）
+2. **工具使用规范**
+3. **CLAUDE.md 内容**（项目级指令）
+4. **技能提示**（skills reminder）
+5. **环境信息**（OS、shell、git 状态等）— 事实上 Codex 非常依赖 git。如果项目存在 git 仓库，Codex 能展现出对项目更好的理解能力，包括可以拉取远端的变更和 commit 记录来辅助分析
+
+带 `cache_control: { type: "ephemeral" }` 标记的块会被 Anthropic API 缓存 5 分钟，命中缓存时以 `cache_read_input_tokens` 计费（远低于 `input_tokens`）。
+
+> **注意**：对于 Codex 这类特殊客户端，Anthropic 服务端实际上并不完全依赖请求中的 `cache_control` 属性来决定缓存行为。服务端会对特定字段（如 system prompt、tools 定义）自动执行缓存策略，即使请求中未显式携带 `cache_control` 标记。因此，当你在请求体中没有看到该属性时不必疑惑——服务端已在幕后完成了缓存操作，只是未将此信息暴露给客户端。这是 Codex 与 Anthropic API 之间的一种默契。