kaiten-cli 0.3.3__tar.gz → 0.3.5__tar.gz

{kaiten_cli-0.3.3 → kaiten_cli-0.3.5}/.gitignore

@@ -12,6 +12,7 @@ htmlcov/
 .bin/
 .pipx/
 .uv-tools/
+node_modules/
 build/
 dist/
 *.egg-info/

{kaiten_cli-0.3.3 → kaiten_cli-0.3.5}/AGENTS.md

@@ -5,6 +5,10 @@ This file only captures agent-specific guidance.
 For install, human-oriented usage, and the full docs map, start with [README.md](README.md).  
 For the full command catalog, use [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md).  
 For the system map, use [ARCHITECTURE.md](ARCHITECTURE.md).
+For the PyPI publishing process, use [docs/PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).
+For a stable install, start with `pip install kaiten-cli`; pipx and uv are alternatives.
+Use a Git install when the requested source is a branch or tag. Check the installed
+version separately from the checkout: they can differ.
 For optimized LLM workflows, start with:
 
 - [skills/kaiten-cli-heavy-data/SKILL.md](skills/kaiten-cli-heavy-data/SKILL.md)
@@ -95,3 +99,4 @@ kaiten profile add main --domain <company-subdomain-or-url> --token <api-token>
 - Attaching a PR to a card usually means the GitHub addon, not `external-links create`; check both sources when looking for every PR a card references.
 - The GitHub addon UUID is derived from its mount path only on on-premises Kaiten; elsewhere it is random. `addons uid` returns the derived guess, `space-addons list` and `company-addons list` return the real one, and the `github-addon` commands re-resolve it from the card's space when the guess finds no data.
 - Live validation is opt-in and documented in [LIVE_VALIDATION.md](LIVE_VALIDATION.md).
+- For installations without the verified server-side API fix, document content updates should use the explicitly selected temporary compatibility fallback `documents update --content-mode yjs` (requires an existing Node.js 20+). It is a future removal candidate, not deprecated; see the retirement criteria in `docs/DOCUMENT_YJS_VERIFICATION.md`. API replacement of `data`/`text` is blocked without `--allow-unsafe-content-replace` because synchronization with an open editor may duplicate the entire document. Never treat this flag as an automatic fallback after a failed Yjs update; an unacknowledged write may already have been saved.

{kaiten_cli-0.3.3 → kaiten_cli-0.3.5}/API_BEHAVIOR_MATRIX.md

@@ -8,18 +8,25 @@
 
 | Поле | Значение |
 |------|----------|
-| Contract baseline | `kaiten-cli v0.1.23` |
+| Исторический contract baseline | `kaiten-cli v0.1.23` |
 | Tenant class | Kaiten sandbox test tenant |
-| Текущий аудит | `2026-07-09`; live suite **не запускался** |
+| Последний зафиксированный аудит | `2026-07-09`; live suite **не запускался** |
 | Последняя полная live campaign | `TBD`: дата и commit не подтверждены в репозитории |
-| Источник до следующего live run | checked-in contracts и `tests/live/`; записи ниже нельзя считать повторно подтверждёнными текущим аудитом |
+| Источник до следующего live run | checked-in contracts и `tests/live/`; записи ниже не являются свежей live-проверкой текущего выпуска |
 
 После следующей полной live campaign эту таблицу нужно обновить точными датой, commit SHA, версией CLI и tenant class. Secrets, tenant URL и идентификаторы тестовых сущностей сюда не записываются.
 
+Публикация новой версии CLI и успешный offline CI не меняют дату или статус
+исторической live-проверки. Текущий command surface задаёт реестр CLI.
+
 ## Default rule
 
 Все canonical команды из registry, которые не перечислены ниже, считаются `live_passed`: они должны проходить по normal success-path в полном live suite.
 
+Это правило интерпретации закодированной матрицы и ожидаемого success-path,
+а не свидетельство нового прогона каждой команды. Для добавленных позднее команд
+сохраняется явный статус `live_not_validated` до фактической live-проверки.
+
 ## Validated success-path contracts with special notes
 
 | Command | Verb / Path | Status | Notes |

{kaiten_cli-0.3.3 → kaiten_cli-0.3.5}/ARCHITECTURE.md

@@ -111,6 +111,30 @@ Git URL, and installer commands are passed directly to `subprocess` without a
 shell. A confirmed update is a separate local side effect and does not alter the
 already completed Kaiten command.
 
+PyPI installations do not use this post-command check. They are updated manually
+through the same installer: pip, pipx, or uv. Git installations retain their Git
+source; the updater does not migrate them to PyPI.
+
+## Packaging and Releases
+
+Hatchling builds the Python 3.11+ wheel and sdist from `pyproject.toml`; the package
+version comes from `src/kaiten_cli/__init__.py`. Stable installations use PyPI;
+Git installations can follow a branch or a specific tag.
+
+Pushing a stable `vX.Y.Z` tag runs release preflight, the full reusable CI and then
+the PyPI upload. Preflight checks the tag/version, triggering commit, ancestry in
+`origin/master` and absence of the version on PyPI. CI checks both archives and
+their installation; the upload job publishes those same artifacts without a rebuild.
+PRs and ordinary `master` pushes run CI without uploading.
+
+The upload uses Trusted Publishing through the GitHub environment `pypi`, which
+allows only tags matching `v*`. Only the upload job has `id-token: write`; no
+long-lived PyPI API token is stored in the repository. See the
+[publishing guide](docs/PYPI_PUBLISHING.md) for setup, release and readback steps.
+
+The PyPI project description is packaged from README at build time. Updating the
+repository docs does not replace metadata in an already published release.
+
 ## Mutation Safety
 
 - Transport retries are limited to safe HTTP methods. An ambiguous timeout, connection failure, HTTP 5xx, or malformed successful response for a remote mutation is returned without retry and explicitly tells the caller to verify remote state.
@@ -164,6 +188,7 @@ Primary docs:
 - [README.md](README.md) for install, usage, config, and operator guidance
 - [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) for the full generated command catalog
 - [AGENTS.md](AGENTS.md) for agent-specific usage and safety shortcuts
+- [docs/PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md) for PyPI setup, release and verification
 - `skills/` for repo-local LLM workflows in `SKILL.md` format
 - [LIVE_VALIDATION.md](LIVE_VALIDATION.md) for live test process
 - [API_BEHAVIOR_MATRIX.md](API_BEHAVIOR_MATRIX.md) for documented sandbox contracts
@@ -175,7 +200,7 @@ Primary docs:
 
 - The manual registry is easy to inspect, but large and maintenance-heavy.
 - Runtime behaviors are now explicit, but still centralized in one behavior module.
-- Request-scoped cache is built in, but persistent cache deliberately stays conservative and opt-in.
+- Request-scoped cache is built in; persistent cache defaults to `auto` with adaptive TTLs. Freshness overrides remain explicit.
 - Snapshot refresh is still rebuild-oriented in v1; there is no incremental sync yet.
 - Local metric semantics are still generic; tenant-specific flow profiles are intentionally deferred.
 - The default local card path is intentionally summary-first to reduce token and payload cost before LLM involvement.

kaiten_cli-0.3.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viktor Ognev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{kaiten_cli-0.3.3 → kaiten_cli-0.3.5}/LIVE_VALIDATION.md

@@ -6,11 +6,14 @@
 
 ## Статус проверки
 
-- На `2026-07-09` в рамках текущего аудита live suite **не запускался**.
-- Текущий contract baseline — `kaiten-cli v0.1.23`; tenant class ранее зафиксированных контрактов — Kaiten sandbox test tenant.
+- В последнем зафиксированном аудите от `2026-07-09` live suite **не запускался**.
+- Исторический contract baseline — `kaiten-cli v0.1.23`; tenant class ранее зафиксированных контрактов — Kaiten sandbox test tenant.
 - Дата и commit последней полной live campaign не подтверждены в репозитории и остаются `TBD`.
 - До нового запуска [API_BEHAVIOR_MATRIX.md](API_BEHAVIOR_MATRIX.md) описывает ранее наблюдавшиеся и закодированные контракты, а не свежую проверку production или sandbox API.
 
+Версия baseline и дата аудита относятся к истории live-проверок, а не к текущему
+выпуску CLI. Успешный CI и публикация пакета в PyPI не обновляют эти свидетельства.
+
 После каждой полной campaign нужно записать в оба документа дату, commit SHA, версию CLI и tenant class, не сохраняя credentials, tenant URL и идентификаторы временных сущностей.
 
 ## Ограничения пространства
@@ -108,11 +111,12 @@ Harness делает следующее:
   - если live API отвечает `405`, CLI делает `GET /projects/{project_id}?with_cards_data=true`
   - затем извлекает embedded cards list из project payload
 - `checklists.list`
-  - direct `GET /cards/{card_id}/checklists` возвращает `405`
+  - direct `GET /cards/{card_id}/checklists` ранее возвращал `405` на проверенном tenant
   - CLI делает `GET /cards/{card_id}` и извлекает embedded `checklists`
 - `checklist-items.list`
-  - direct `GET /cards/{card_id}/checklists/{checklist_id}/items` возвращает `405`
-  - CLI делает `GET /cards/{card_id}` и извлекает `items` из matching checklist
+  - direct `GET /cards/{card_id}/checklists/{checklist_id}/items` ранее возвращал `405` на проверенных экземплярах
+  - CLI делает `GET /cards/{card_id}/checklists/{checklist_id}` и извлекает `items` из отдельного чеклиста
+  - ошибки API, включая отсутствие чеклиста, сохраняются; чтения всей карточки как fallback нет
 
 ## Expected-error contracts
 

{kaiten_cli-0.3.3 → kaiten_cli-0.3.5}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.5
 Name: kaiten-cli
-Version: 0.3.3
+Version: 0.3.5
 Summary: LLM-oriented CLI for Kaiten
 Project-URL: Homepage, https://github.com/ViktorOgnev/kaiten-cli
 Project-URL: Repository, https://github.com/ViktorOgnev/kaiten-cli
 Project-URL: Issues, https://github.com/ViktorOgnev/kaiten-cli/issues
 Author: Viktor Ognev
+License-Expression: MIT
+License-File: LICENSE
 Keywords: api,automation,cli,kaiten,llm
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
@@ -16,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1
@@ -55,50 +58,137 @@ Description-Content-Type: text/markdown
 
 Источник истины для CLI — локальный реестр `src/kaiten_cli/registry/`.
 
+## Обновление содержимого документов
+
+**Временный резервный механизм совместимости.** Режим `--content-mode yjs`
+предназначен для установок, где исправленный серверный API ещё не выпущен или
+не включён. Он сохраняет историю совместного редактирования и остаётся нужен
+для поддержки старых облачных и on-premise установок.
+
+Этот fallback выбирается только явно; CLI не переключается на него автоматически
+при ошибках API. Механизм — кандидат на последующее удаление, но пока не объявлен
+deprecated и даты удаления нет.
+
+```bash
+kaiten --locale ru --json --profile main documents update \
+  --document-uid <uid> --content-mode yjs --data @document.json
+```
+
+Можно передать `--text` вместо `--data`. В этом режиме метаданные, например
+`--title`, обновляются отдельной командой. Если Socket.IO работает на отдельном
+сервере, укажите его origin через `--socket-url https://socket.example.com`.
+По умолчанию используется origin выбранного профиля, путь Socket.IO — `/socket.io`.
+Режим использует внутренний протокол Kaiten, а не гарантированный Public API;
+совместимость конкретной установки требует проверки на тестовом документе.
+
+Для Yjs нужен заранее установленный **Node.js 20+**. JavaScript-помощник,
+библиотеки и схемы документов уже входят в пакет CLI. CLI не устанавливает Node,
+не запускает npm и не скачивает зависимости. Без Node остальные команды работают;
+Yjs-обновление завершится до записи с `config_error` и кодом выхода `3`.
+
+**Полная API-запись может создать дубль всего документа при синхронизации
+с открытым редактором.** Поэтому `documents update` с `data` или `text` без
+Yjs-режима заблокирован (`mutation_blocked`, код `6`). Для осознанного разрешения
+старого PATCH укажите `--allow-unsafe-content-replace`; предупреждение о риске
+будет выведено в stderr, JSON в stdout сохранит прежний формат.
+
+Автоматического перехода с Yjs на PATCH и автоматических повторов записи нет.
+Успех Yjs означает подтверждение и проверку сохранённого состояния через повторную
+синхронизацию. При обрыве после отправки CLI сообщает, что результат записи
+неизвестен. При параллельных правках возможен конфликт проверки: CLI не
+перезаписывает чужие изменения повторной попыткой. Результат Yjs содержит
+`document_uid`, `content_mode`, `schema_version`, `data` и `status`
+(`verified` или `unchanged`); это результат синхронизации, а не REST-снимок метаданных.
+Сокетные попытки отражаются в `stats.document_sync` отдельно от HTTP-запросов.
+
+Серверные исправления уже смержены, но это не подтверждает их rollout на конкретной
+установке. Удалить резервный путь можно после проверки обычного PATCH с сохранением
+старого состояния редактора, включения исправления на поддерживаемых установках
+и пересмотра минимальной поддерживаемой версии сервера. Подробности и состав
+удаляемого слоя — в [протоколе проверки](docs/DOCUMENT_YJS_VERIFICATION.md#temporary-fallback-and-retirement).
+
 ## Быстрый старт
 
+### Установка через Homebrew
+
+На macOS и Linux:
+
+```bash
+brew install ViktorOgnev/tap/kaiten-cli
+kaiten --locale ru --version
+```
+
+Homebrew устанавливает Python, Node.js для Yjs и зависимости CLI в управляемое
+окружение. Отдельно устанавливать pipx или uv не требуется. Формула находится в
+[публичном tap](https://github.com/ViktorOgnev/homebrew-tap); пока она не входит
+в основной каталог Homebrew.
+
+Обновление:
+
+```bash
+brew update
+brew upgrade kaiten-cli
+```
+
+При переходе с pipx или uv сначала удалите прежнюю установку соответствующим
+менеджером (`pipx uninstall kaiten-cli` или `uv tool uninstall kaiten-cli`).
+Для pip используйте `python -m pip uninstall kaiten-cli` именно в прежнем
+окружении. Эти команды не удаляют профили Kaiten. После установки проверьте
+`command -v kaiten` и `type -a kaiten`: запускаемый файл должен принадлежать
+Homebrew. При необходимости выполните `hash -r` или откройте новый терминал.
+Обновляйте Homebrew-установку только через `brew upgrade`.
+
 ### Установка из PyPI
 
-Требуется Python 3.11 или новее. Начиная с выпуска `0.3.3`, стабильные версии
-публикуются в PyPI.
+Требуется Python 3.11 или новее. Стабильные версии доступны в
+[PyPI](https://pypi.org/project/kaiten-cli/), начиная с выпуска `0.3.3`.
 
 Рекомендуемый путь:
 
 ```bash
-uv tool install kaiten-cli
+pip install kaiten-cli
 ```
 
-Альтернатива:
+Установка CLI в отдельное окружение через pipx:
 
 ```bash
 pipx install kaiten-cli
 ```
 
-Установка в локальное виртуальное окружение:
+Альтернатива через uv:
+
+```bash
+uv tool install kaiten-cli
+```
+
+Для установки через pip можно предварительно создать и активировать виртуальное
+окружение. На macOS и Linux:
 
 ```bash
 python3 -m venv .venv
-.venv/bin/python -m pip install kaiten-cli
+source .venv/bin/activate
+pip install kaiten-cli
 ```
 
-В уже активированном виртуальном окружении достаточно `pip install kaiten-cli`.
+В Windows PowerShell окружение активируется командой `.\.venv\Scripts\Activate.ps1`.
 
 ### Установка из Git
 
-Для установки текущего состояния `master`:
+PyPI устанавливает опубликованный выпуск. Для установки текущего состояния
+`master`, которое может содержать ещё не выпущенные изменения, используйте Git:
 
 ```bash
-uv tool install git+https://github.com/ViktorOgnev/kaiten-cli.git
+pip install git+https://github.com/ViktorOgnev/kaiten-cli.git
 ```
 
 Для установки конкретного выпуска:
 
 ```bash
-uv tool install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.3"
+pip install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.5"
 ```
 
-Вместо `uv tool install` можно использовать `pipx install` или
-`python -m pip install` в виртуальном окружении.
+Вместо `pip install` можно использовать `pipx install` или `uv tool install`.
+Чтобы выбрать конкретный Python для pip, используйте `python -m pip install`.
 
 ### Проверка установки
 
@@ -239,39 +329,41 @@ PowerShell необходимо использовать отдельную ру
 Для установки из PyPI обновление выполняется вручную тем же менеджером:
 
 ```bash
-uv tool upgrade kaiten-cli
-pipx upgrade kaiten-cli
 python -m pip install --upgrade kaiten-cli
+pipx upgrade kaiten-cli
+uv tool upgrade kaiten-cli
 ```
 
 Выберите команду своего менеджера; для pip используйте Python того окружения,
 куда установлен пакет. Встроенное предложение обновиться для установок из PyPI
 пока не поддерживается.
 
-Если CLI установлен по адресу ветки Git, обновление выполняется вручную:
+Для установки из Git-ветки `master` обновление выполняется вручную:
 
 ```bash
-uv tool upgrade kaiten-cli
+python -m pip install --upgrade git+https://github.com/ViktorOgnev/kaiten-cli.git
 pipx upgrade kaiten-cli
+uv tool upgrade kaiten-cli
 ```
 
 Установка из Git без тега использует текущую версию из ветки `master`.
 Установку можно закрепить на конкретном выпуске с помощью тега:
 
 ```bash
-uv tool install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.3"
+pip install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.5"
 ```
 
-Для установки из Git после успешной команды в интерактивном терминале CLI не чаще одного раза в сутки
-проверяет стабильные теги `vX.Y.Z` в том же Git-репозитории. Если найден новый
-релиз, появляется вопрос `Update now ...? [y/N]`. Основная команда к этому
+При установке из Git CLI после успешной команды в интерактивном терминале
+не чаще одного раза в сутки проверяет стабильные теги `vX.Y.Z` в том же
+Git-репозитории. Если найден новый релиз, появляется вопрос `Update now ...? [y/N]`.
+Основная команда к этому
 моменту уже завершена; подтверждённое обновление применяется со следующего запуска.
 
 Способ обновления соответствует способу установки:
 
-- `uv tool` → `uv tool upgrade kaiten-cli`;
+- виртуальное окружение и pip → текущий `python -m pip install --upgrade <git-source>`;
 - `pipx` → `pipx upgrade kaiten-cli`;
-- виртуальное окружение и pip → текущий `python -m pip install --upgrade <git-source>`.
+- `uv tool` → `uv tool upgrade kaiten-cli`.
 
 Для установки, закреплённой на `@vX.Y.Z`, подтверждение заменяет текущий тег на
 новый с помощью того же менеджера. Проверка не запускается в режиме `--json`,

{kaiten_cli-0.3.3 → kaiten_cli-0.3.5}/README.md

@@ -10,50 +10,137 @@
 
 Источник истины для CLI — локальный реестр `src/kaiten_cli/registry/`.
 
+## Обновление содержимого документов
+
+**Временный резервный механизм совместимости.** Режим `--content-mode yjs`
+предназначен для установок, где исправленный серверный API ещё не выпущен или
+не включён. Он сохраняет историю совместного редактирования и остаётся нужен
+для поддержки старых облачных и on-premise установок.
+
+Этот fallback выбирается только явно; CLI не переключается на него автоматически
+при ошибках API. Механизм — кандидат на последующее удаление, но пока не объявлен
+deprecated и даты удаления нет.
+
+```bash
+kaiten --locale ru --json --profile main documents update \
+  --document-uid <uid> --content-mode yjs --data @document.json
+```
+
+Можно передать `--text` вместо `--data`. В этом режиме метаданные, например
+`--title`, обновляются отдельной командой. Если Socket.IO работает на отдельном
+сервере, укажите его origin через `--socket-url https://socket.example.com`.
+По умолчанию используется origin выбранного профиля, путь Socket.IO — `/socket.io`.
+Режим использует внутренний протокол Kaiten, а не гарантированный Public API;
+совместимость конкретной установки требует проверки на тестовом документе.
+
+Для Yjs нужен заранее установленный **Node.js 20+**. JavaScript-помощник,
+библиотеки и схемы документов уже входят в пакет CLI. CLI не устанавливает Node,
+не запускает npm и не скачивает зависимости. Без Node остальные команды работают;
+Yjs-обновление завершится до записи с `config_error` и кодом выхода `3`.
+
+**Полная API-запись может создать дубль всего документа при синхронизации
+с открытым редактором.** Поэтому `documents update` с `data` или `text` без
+Yjs-режима заблокирован (`mutation_blocked`, код `6`). Для осознанного разрешения
+старого PATCH укажите `--allow-unsafe-content-replace`; предупреждение о риске
+будет выведено в stderr, JSON в stdout сохранит прежний формат.
+
+Автоматического перехода с Yjs на PATCH и автоматических повторов записи нет.
+Успех Yjs означает подтверждение и проверку сохранённого состояния через повторную
+синхронизацию. При обрыве после отправки CLI сообщает, что результат записи
+неизвестен. При параллельных правках возможен конфликт проверки: CLI не
+перезаписывает чужие изменения повторной попыткой. Результат Yjs содержит
+`document_uid`, `content_mode`, `schema_version`, `data` и `status`
+(`verified` или `unchanged`); это результат синхронизации, а не REST-снимок метаданных.
+Сокетные попытки отражаются в `stats.document_sync` отдельно от HTTP-запросов.
+
+Серверные исправления уже смержены, но это не подтверждает их rollout на конкретной
+установке. Удалить резервный путь можно после проверки обычного PATCH с сохранением
+старого состояния редактора, включения исправления на поддерживаемых установках
+и пересмотра минимальной поддерживаемой версии сервера. Подробности и состав
+удаляемого слоя — в [протоколе проверки](docs/DOCUMENT_YJS_VERIFICATION.md#temporary-fallback-and-retirement).
+
 ## Быстрый старт
 
+### Установка через Homebrew
+
+На macOS и Linux:
+
+```bash
+brew install ViktorOgnev/tap/kaiten-cli
+kaiten --locale ru --version
+```
+
+Homebrew устанавливает Python, Node.js для Yjs и зависимости CLI в управляемое
+окружение. Отдельно устанавливать pipx или uv не требуется. Формула находится в
+[публичном tap](https://github.com/ViktorOgnev/homebrew-tap); пока она не входит
+в основной каталог Homebrew.
+
+Обновление:
+
+```bash
+brew update
+brew upgrade kaiten-cli
+```
+
+При переходе с pipx или uv сначала удалите прежнюю установку соответствующим
+менеджером (`pipx uninstall kaiten-cli` или `uv tool uninstall kaiten-cli`).
+Для pip используйте `python -m pip uninstall kaiten-cli` именно в прежнем
+окружении. Эти команды не удаляют профили Kaiten. После установки проверьте
+`command -v kaiten` и `type -a kaiten`: запускаемый файл должен принадлежать
+Homebrew. При необходимости выполните `hash -r` или откройте новый терминал.
+Обновляйте Homebrew-установку только через `brew upgrade`.
+
 ### Установка из PyPI
 
-Требуется Python 3.11 или новее. Начиная с выпуска `0.3.3`, стабильные версии
-публикуются в PyPI.
+Требуется Python 3.11 или новее. Стабильные версии доступны в
+[PyPI](https://pypi.org/project/kaiten-cli/), начиная с выпуска `0.3.3`.
 
 Рекомендуемый путь:
 
 ```bash
-uv tool install kaiten-cli
+pip install kaiten-cli
 ```
 
-Альтернатива:
+Установка CLI в отдельное окружение через pipx:
 
 ```bash
 pipx install kaiten-cli
 ```
 
-Установка в локальное виртуальное окружение:
+Альтернатива через uv:
+
+```bash
+uv tool install kaiten-cli
+```
+
+Для установки через pip можно предварительно создать и активировать виртуальное
+окружение. На macOS и Linux:
 
 ```bash
 python3 -m venv .venv
-.venv/bin/python -m pip install kaiten-cli
+source .venv/bin/activate
+pip install kaiten-cli
 ```
 
-В уже активированном виртуальном окружении достаточно `pip install kaiten-cli`.
+В Windows PowerShell окружение активируется командой `.\.venv\Scripts\Activate.ps1`.
 
 ### Установка из Git
 
-Для установки текущего состояния `master`:
+PyPI устанавливает опубликованный выпуск. Для установки текущего состояния
+`master`, которое может содержать ещё не выпущенные изменения, используйте Git:
 
 ```bash
-uv tool install git+https://github.com/ViktorOgnev/kaiten-cli.git
+pip install git+https://github.com/ViktorOgnev/kaiten-cli.git
 ```
 
 Для установки конкретного выпуска:
 
 ```bash
-uv tool install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.3"
+pip install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.5"
 ```
 
-Вместо `uv tool install` можно использовать `pipx install` или
-`python -m pip install` в виртуальном окружении.
+Вместо `pip install` можно использовать `pipx install` или `uv tool install`.
+Чтобы выбрать конкретный Python для pip, используйте `python -m pip install`.
 
 ### Проверка установки
 
@@ -194,39 +281,41 @@ PowerShell необходимо использовать отдельную ру
 Для установки из PyPI обновление выполняется вручную тем же менеджером:
 
 ```bash
-uv tool upgrade kaiten-cli
-pipx upgrade kaiten-cli
 python -m pip install --upgrade kaiten-cli
+pipx upgrade kaiten-cli
+uv tool upgrade kaiten-cli
 ```
 
 Выберите команду своего менеджера; для pip используйте Python того окружения,
 куда установлен пакет. Встроенное предложение обновиться для установок из PyPI
 пока не поддерживается.
 
-Если CLI установлен по адресу ветки Git, обновление выполняется вручную:
+Для установки из Git-ветки `master` обновление выполняется вручную:
 
 ```bash
-uv tool upgrade kaiten-cli
+python -m pip install --upgrade git+https://github.com/ViktorOgnev/kaiten-cli.git
 pipx upgrade kaiten-cli
+uv tool upgrade kaiten-cli
 ```
 
 Установка из Git без тега использует текущую версию из ветки `master`.
 Установку можно закрепить на конкретном выпуске с помощью тега:
 
 ```bash
-uv tool install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.3"
+pip install "git+https://github.com/ViktorOgnev/kaiten-cli.git@v0.3.5"
 ```
 
-Для установки из Git после успешной команды в интерактивном терминале CLI не чаще одного раза в сутки
-проверяет стабильные теги `vX.Y.Z` в том же Git-репозитории. Если найден новый
-релиз, появляется вопрос `Update now ...? [y/N]`. Основная команда к этому
+При установке из Git CLI после успешной команды в интерактивном терминале
+не чаще одного раза в сутки проверяет стабильные теги `vX.Y.Z` в том же
+Git-репозитории. Если найден новый релиз, появляется вопрос `Update now ...? [y/N]`.
+Основная команда к этому
 моменту уже завершена; подтверждённое обновление применяется со следующего запуска.
 
 Способ обновления соответствует способу установки:
 
-- `uv tool` → `uv tool upgrade kaiten-cli`;
+- виртуальное окружение и pip → текущий `python -m pip install --upgrade <git-source>`;
 - `pipx` → `pipx upgrade kaiten-cli`;
-- виртуальное окружение и pip → текущий `python -m pip install --upgrade <git-source>`.
+- `uv tool` → `uv tool upgrade kaiten-cli`.
 
 Для установки, закреплённой на `@vX.Y.Z`, подтверждение заменяет текущий тег на
 новый с помощью того же менеджера. Проверка не запускается в режиме `--json`,