@wirecat/max-cli 0.0.0-stage → 0.42.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viacheslav Ptsarev
+
+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.

package/README.md

@@ -1,3 +1,531 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/WireCatLabs/max-cli/main/docs/design/logo_text.png" alt="Max CLI" width="480">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# max-cli
+
+Ваши боты [MAX](https://max.ru) и ваш личный аккаунт — в терминале и в ИИ-агентах. `max` —
+программа для терминала и MCP-сервер: пишите от имени бота через официальный Bot API, а в свои
+чаты — сами или руками Claude, Codex, Cursor и других агентов. В группах, которые вы ведёте, —
+следите за непрочитанным и сразу реагируйте на проблемы: спам, чужие ссылки, флуд, вопросы без
+ответа — по вашим правилам.
+
+Работает в Windows, macOS и Linux. Документация — [wirecat.dev/ru/docs/max](https://wirecat.dev/ru/docs/max).
+
+```sh
+max sales bot messages send "Команда продаж" "Сборка готова"   # от имени бота
+max messages send "Иван Петров" "Опаздываю на 15 минут"         # от вашего имени
+```
+
+[![npm](https://img.shields.io/npm/v/@wirecat/max-cli)](https://www.npmjs.com/package/@wirecat/max-cli)
+[![CI](https://github.com/WireCatLabs/max-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/WireCatLabs/max-cli/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/node/v/@wirecat/max-cli)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/bun-1.3%2B-f9f1e1)](https://bun.sh/)
+[![npm downloads](https://img.shields.io/npm/dm/@wirecat/max-cli)](https://www.npmjs.com/package/@wirecat/max-cli)
+[![License: MIT](https://img.shields.io/npm/l/@wirecat/max-cli)](LICENSE)
+
+## Бот
+
+`max bot` работает с ботом через **официальный** [Bot API MAX](https://dev.max.ru/docs-api) по токену
+бота. Ботов может быть несколько: каждый хранится под именем, которое вы выбираете, и это имя —
+первое слово команды.
+
+**Полный Bot API.** Все методы официальной схемы MAX доступны из терминала через
+`max <бот> bot api <операция>`: параметры — флаги, тело запроса — JSON. Удобные команды
+для сообщений и чатов дополняются полным API для собственных сценариев и автоматизации.
+[Руководство по Bot API](docs/bot.md) и [полный справочник команд](docs/commands.md).
+
+```sh
+max sales bot auth set                                   # токен — в скрытом вводе, MAX его проверит
+max sales bot me                                         # какой это бот
+max sales bot api get-updates --limit 10                 # номер группы — в поле chat_id
+max sales bot messages send "Команда продаж" "Сборка готова" --file report.pdf
+max sales bot recipients add "Команда продаж"            # писать только сюда
+max bot list --check                                     # все боты на этом компьютере
+```
+
+Чат называют по номеру или, когда бот его уже видел, по названию; человеку пишут как
+`user:<номер>`. Где взять номер чата — [docs/bot.md](docs/bot.md#где-взять-номер-чата).
+
+- **Сообщения и чаты.** Отправка в чат по номеру, человеку как `user:<номер>` или в чат по
+  названию; правка, удаление, чтение, закрепление. `chats list` — чаты, которые бот видел: списка
+  чатов бота у MAX нет.
+- **Файлы, участники, комментарии, кнопки, меню команд, вебхуки.** `messages send --file`,
+  `chats members`, `chats admins`, `comments`, `callbacks answer`, `commands`, `webhooks` — у каждой записи тот
+  же список получателей и журнал.
+- **Модерация от имени бота.** `bot chats moderate` сверяет новое в группе с правилами
+  (`bot chats rules`) и удаляет спам и людей — с запретом вернуться по ссылке. Вступления видит
+  `bot watch`, который печатает всё, что происходит в чатах бота.
+- **Копия переписки на этом компьютере.** `bot contacts show <кто>` — где человек писал и его личный
+  чат с ботом; `bot search messages --from <кто>` и `bot messages between <кто> <кто>` — без
+  запросов к MAX.
+- **Бот для агента.** `max sales bot mcp` — MCP-сервер бота: агенту доступно то, что разрешают
+  `permissions` профиля бота; `ask` и `allow` разрешают действие без формы, а `readonly` запрещает запись.
+- **Все методы Bot API.** Полное покрытие официальной схемы через `max bot api <операция>` — с флагами
+  для параметров и JSON-телом, которое сверяется со схемой до отправки.
+- **Бот не напишет лишнего.** У каждого бота свой список чатов, куда ему можно писать, и журнал
+  всего, что он отправил, — без текста. `permissions` ограничивает и бота.
+- **Токен не в файле.** Токен бота — в системном хранилище паролей, отдельно от вашего.
+
+Бота создают на [business.max.ru](https://business.max.ru/self); MAX выдаёт их подтверждённым
+организациям, ИП и самозанятым. Полностью — [docs/bot.md](docs/bot.md).
+
+## Личный аккаунт
+
+`max` без слова `bot` работает с вашим личным аккаунтом: как ещё одно ваше устройство, со всеми
+чатами, историей, группами и контактами.
+
+> ⚠️ **Для личного аккаунта max-cli использует неофициальный внутренний API MAX.** API может
+> измениться без предупреждения, а использование инструмента может нарушать условия сервиса. Вы
+> используете max-cli на свой риск; авторы и контрибьюторы не несут ответственности за блокировки
+> аккаунтов, потерю данных или другие последствия. Бот работает через официальный API, и к нему
+> это не относится.
+
+```sh
+max chats list --limit 5
+max messages list "Иван Петров"
+max messages send "Иван Петров" "Опаздываю на 15 минут"
+```
+
+Всё ниже, до раздела «Установка», — про личный аккаунт. Полностью — [docs/usage.md](docs/usage.md).
+
+## Как это использовать
+
+Самое полезное — поручить переписку агенту: Claude, Codex или другому. Он читает чаты через `max`
+и делает то, что вы попросили словами.
+
+- **Проверка по расписанию.** Утром и вечером агент смотрит, что пришло, и присылает короткую
+  сводку: кто ждёт ответа, что срочно, что можно не читать.
+- **Отчёты.** Итог недели по рабочему чату: что решили, кто что взял на себя, какие вопросы
+  остались без ответа.
+- **Кто кому должен.** `max review` одним вызовом отдаёт всё, что было в переписке с прошлого
+  обзора, — ваши сообщения тоже, голосовые — текстом. Агент раскладывает это на «я должен», «жду от
+  других» и «нужно уточнить», а прежде чем назвать что-то просроченным, проверяет рабочие группы:
+  может, уже сделано.
+- **Напоминания.** Кому вы обещали ответить и не ответили; чей вопрос висит третий день.
+- **Черновики ответов.** Агент предлагает текст, а отправляете вы — или он сам, если вы разрешили
+  писать в этот чат.
+- **Поиск.** «Когда мы договорились о встрече с Иваном?» — ответ с датой и самим сообщением.
+- **Группа, которую вы ведёте.** Какие вопросы висят без ответа, кто вступил за неделю и с каким
+  аккаунтом, удалить приглашения в чужие чаты — по вашим правилам и с вашим «да»
+  ([ниже](#группы-которые-вы-ведёте)).
+
+Как это выглядит:
+
+```text
+Вы:     Что я кому обещал за последние три дня?
+Агент:  (вызывает max review: 12 чатов, 3 голосовых расшифровано)
+        Я должен
+        · Ивану Петрову — прислать счёт до пятницы. «Иван Петров», 24.09
+        Жду от других
+        · Ольга — макет к 25.09. В группе «Дизайн» его пока нет
+        Нужно уточнить
+        · «Проект Альфа»: кто везёт образцы — договорились «потом решим», 25.09
+        Следующий обзор — с 26.09, 14:05.
+Вы:     Напомни Ольге про макет.
+Агент:  Черновик: «Ольга, привет! Как там макет?» Отправить?
+Вы:     Да.
+```
+
+Агент отправляет только по вашей просьбе; подтверждение вызовов настройте в своём ИИ-приложении. Чтение не ставит отметку «прочитано». Как настроить
+агента под каждую задачу — готовые запросы, расписание и ограничения:
+[docs/recipes.md](docs/recipes.md).
+
+## Группы, которые вы ведёте
+
+```sh
+max review --chat "Поход" --unanswered            # вопросы, на которые сутки никто не ответил
+max chats events "Поход"                          # кто вступил и вышел за неделю
+max chats members list "Поход" --all              # все участники: когда заведён аккаунт
+max chats rules set "Поход" invites delete        # приглашения в чужие чаты — удалять
+max chats moderate "Поход" --allow-dangerous         # проверить группу и сделать, что разрешено
+```
+
+Проверка сверяет новое в группе с вашими правилами: заблокированные люди, приглашения, ссылки,
+пересланное, флуд, совсем новые аккаунты. По умолчанию она только отмечает. Для каждого действия
+вы решаете сами: никогда, только с флагом, с вашим подтверждением или сразу. Сценарии с агентом,
+все правила и ограничения — [docs/groups.md](docs/groups.md).
+
+## Как это работает
+
+`max` работает от вашего имени, как ещё одно ваше устройство, а не как бот. Вы входите один раз
+по QR-коду, и дальше доступно то же, что в приложении: чаты, сообщения, файлы, группы, контакты и
+профиль.
+
+Агенту `max` подключается одним из двух способов:
+
+- **Агент с терминалом** — Claude Code, Codex, Gemini CLI. Он сам вызывает команды `max`. Дайте
+  ему навык (skill) — инструкцию, как работать с `max`: одна команда, см.
+  [ниже](#для-скриптов-и-агентов).
+- **Агент без терминала** — Claude Desktop, Cursor и другие клиенты MCP. Подключите `max mcp`:
+  готовую запись для их настроек печатает `max mcp config`. Там же есть команды `/catch-up` (что
+  нового), `/review` (кто кому должен), `/reply` (черновик ответа) и `/find` (поиск). По умолчанию
+  права агента задают `permissions`; большинство записей разрешено по умолчанию. `readonly`
+  запрещает запись, а `ask` и `allow` допускают вызванную запись без серверной формы.
+
+## Что умеет
+
+- **Читать.** Чаты, история, одно сообщение вместе с соседними, непрочитанное во всех чатах
+  сразу (`max inbox`), вся переписка с прошлого обзора для разбора «кто кому должен» (`max review`), новые сообщения по мере прихода (`max watch`), скачивание вложений,
+  расшифровка голосовых в текст на вашем компьютере, выгрузка переписки в JSONL или Markdown.
+- **Искать.** Сообщения — по тексту всего прочитанного, без подключения к MAX. Чаты и контакты —
+  по части названия или имени.
+- **Писать.** Текст и разметка, ответы, фото, видео, файлы и голосовые, правка, пересылка, закрепление, реакции,
+  опросы, отложенная отправка, удаление — у себя или у всех.
+- **Вести группы и каналы.** Создать группу, вступить по ссылке, выйти, участники и админы,
+  название и настройки, ссылка-приглашение, папки. Для админа — вопросы без
+  ответа, кто вступил и вышел, все участники с возрастом аккаунта, правила и проверка группы по ним
+  ([docs/groups.md](docs/groups.md)).
+- **Контакты и аккаунт.** Найти человека по номеру, добавить, удалить, переименовать для себя,
+  заблокировать, импортировать из файла; изменить профиль и фото; посмотреть и завершить другие
+  сеансы.
+- **Входить удобным способом.** QR-код прямо в терминале, QR-код или SMS через web.max.ru в
+  браузере, или готовый токен.
+
+## Чем он хорош
+
+- **Читает незаметно.** Чтение не ставит отметку «прочитано»: собеседник не видит, что вы открыли
+  чат. Отметить прочитанным можно, когда нужно: `max chats mark-read` или `--mark-read`.
+- **Агент не напишет лишнего.** Есть профиль только для чтения, список чатов, в которые можно
+  писать, и лимит сообщений в час. В MCP сервер проверяет права профиля; подтверждение действий настраивается в приложении агента.
+  Если имя подходит к двум чатам, `max` не выбирает сам, а показывает оба.
+- **Модерация по вашим правилам, а не по чужим.** Проверка группы по умолчанию только отмечает.
+  Удалить сообщение или человека она может, только если вы разрешили: для каждого действия —
+  никогда, с флагом, с вашим подтверждением или сразу. Не больше 10 действий за раз, и ничего не
+  следит за группой в фоне.
+- **Сообщение не уйдёт дважды.** Если связь оборвалась во время отправки, `max` прямо говорит, что
+  не знает, дошло ли сообщение, и даёт команду для повтора. MAX узнаёт повтор и второго сообщения не
+  создаёт.
+- **Своя копия переписки.** Всё прочитанное сохраняется на вашем компьютере. По ней работает
+  быстрый поиск по тексту сообщений, и её можно читать без интернета (`--offline`). При входе MAX
+  присылает только изменившихся людей. Полный список заново — `max contacts sync`; данные
+  покинутых чатов удаляет `max store clear --left --allow-dangerous`.
+- **Чужой текст не управляет вашим терминалом.** Имена, названия чатов, имена файлов и сообщения
+  пишут другие люди. Управляющие символы из них показываются как текст, имя всегда печатается в одну
+  строку, а автодополнение подставляет только номер чата — поддельную строку переписки или команду в
+  оболочке так не подсунуть.
+- **Пароль от аккаунта не лежит в файле.** Токен входа хранится в системном хранилище паролей:
+  Keychain в macOS, Secret Service (GNOME Keyring, KWallet) в Linux, диспетчер учётных данных в
+  Windows. В историю команд он не попадает.
+- **Скрипт и агент разбирают ответ без догадок.** С `--json` команда отдаёт только данные, в одной и
+  той же форме, без текста для человека вокруг. Ошибка приходит отдельно и с номером, поэтому
+  скрипт сразу понимает, что случилось: нет входа, чат не найден или MAX не ответил вовремя.
+- **Разбор проблем без вашей переписки.** `--trace` показывает каждый запрос к MAX, чтобы понять,
+  почему команда не сработала. В этой записи нет текстов, имён, телефонов и токена, поэтому её
+  можно приложить к сообщению об ошибке. Удачный запуск без флага не записывается, неудачный — всегда, тоже без текстов.
+
+## Под заказ
+
+Делаем автоматизацию процессов и инструменты под вашу задачу: интеграции с MAX и другими
+мессенджерами, ИИ-агентов, внутренние сервисы. Пишите на [info@neirox.ai](mailto:info@neirox.ai).
+
+## Чем отличается от других
+
+Для MAX уже есть хорошие проекты, и max-cli многому у них научился.
+[PyMax](https://github.com/MaxApiTeam/PyMax) — самая полная библиотека для личного аккаунта; её код
+помог разобрать многие операции протокола. Выбирайте то, что подходит под задачу.
+
+| | max-cli | [PyMax](https://github.com/MaxApiTeam/PyMax) | [max-mcp](https://github.com/renosaza/max-mcp) |
+|---|:-:|:-:|:-:|
+| что это | программа для терминала и MCP-сервер | библиотека на Python | MCP-сервер на PyMax |
+| MCP-сервер и навык для агентов | ✅ | — | MCP |
+| ограничения для агента: только чтение, разрешённые действия, список чатов, лимит в час, подтверждение отправки | ✅ | — | — |
+| расшифровка голосовых в текст на вашем компьютере | ✅ | — | — |
+| готовые команды — не нужно писать свою программу | ✅ | — (библиотека для своего кода на Python) | — |
+| локальная копия с поиском и чтением без интернета | ✅ | — | — |
+| новые сообщения в реальном времени | ✅ `max watch` | ✅ обработчики событий | — |
+| отложенная отправка — уходит, даже если компьютер выключен | ✅ | ✅ | — |
+| выгрузка переписки в JSONL или Markdown | ✅ | — | — |
+| чтение, отправка текста, фото и файлов | ✅ | ✅ | ✅ |
+| реакции, правка, пересылка, закрепление | ✅ | ✅ | — |
+| удаление сообщений — у себя или у всех, с лимитом | ✅ | ✅ | — |
+| отметка «прочитано» по запросу | ✅ | ✅ | — |
+| группы и каналы: создать, вступить, участники, админы | ✅ | ✅ | чтение каналов |
+| для админа группы: вопросы без ответа, новенькие, проверка по правилам | ✅ | — | — |
+| контакты, профиль, другие сеансы | ✅ | ✅ | — |
+| отправка видео | ✅ | ✅ | — |
+| отправка кружков | — | ✅ | — |
+| отправка голосовых | ✅ | ⚠️ в 2.4.1 не проходит ([#102](https://github.com/MaxApiTeam/PyMax/issues/102), [#103](https://github.com/MaxApiTeam/PyMax/issues/103)) | — |
+| опросы: показать, проголосовать, создать, закрыть | ✅ | ✅ | — |
+| фото профиля | ✅ | ✅ | — |
+| вход с облачным паролем | ✅ по QR-коду | ✅ | — |
+| установить или снять облачный пароль | — | ✅ | — |
+
+Для бота есть `max bot` — через официальный Bot API, отдельно от личного аккаунта
+([docs/bot.md](docs/bot.md)). Таблица выше — про личный аккаунт.
+
+## Содержание
+
+- [Бот](#бот)
+- [Личный аккаунт](#личный-аккаунт)
+- [Группы, которые вы ведёте](#группы-которые-вы-ведёте)
+- [Установка](#установка)
+- [Вход](#вход)
+- [Использование](#использование)
+- [Для скриптов и агентов](#для-скриптов-и-агентов)
+- [Безопасность](#безопасность)
+- [Документация](#документация)
+- [Разработка](#разработка)
+- [Дорожная карта](#дорожная-карта)
+- [Лицензия](#лицензия)
+- [Участие](#участие)
+
+## Установка
+
+Пакет — **`@wirecat/max-cli`**, команда, которую он ставит, — **`max`**.
+
+Запустить, ничего не устанавливая:
+
+```sh
+npx @wirecat/max-cli --help
+```
+
+Поставить насовсем:
+
+```sh
+npm install -g @wirecat/max-cli
+max --version
+max setup --agent codex  # вход и подключение навыка агента
+```
+
+Глобальная установка через npm устанавливает навык агента, а на Windows сохраняет PATH
+для новых терминалов. Агенту в уже открытом терминале нужно обновить окружение и прочитать
+`max skill show` перед входом. `MAX_INSTALL_AGENT=none` отключает установку навыка.
+
+Нужен **Node 22.16+ (ветка 22.x) или 24+**, либо **Bun 1.3+**. Работает на macOS, Linux и Windows. Подробности,
+переменные окружения и то, куда ложатся файлы, — [docs/installation.md](docs/installation.md).
+
+Если после установки команда `max` не находится, `npx @wirecat/max-cli doctor` скажет почему и
+напечатает команду, которая это исправит.
+
+## Вход
+
+`max setup` проводит через первый запуск: проверяет локальные каталоги, показывает QR-код,
+проверяет аккаунт и до пяти чатов, затем предлагает подключить навык агента. Выделите около
+пяти минут. Скачивание истории — отдельный шаг после выбора чата и объёма; setup не запускает
+фоновый сервис. Повторный запуск проверяет существующую сессию без нового входа.
+
+```sh
+max setup --agent codex                # QR-вход и навык Codex
+max setup --agent claude               # или Claude Code
+max setup --method qr-chrome           # QR через web.max.ru в Chromium
+max setup --method sms                 # номер телефона вводится в браузере
+max setup --method token               # скрытый ввод токена или stdin
+max setup --help                       # все способы и примеры
+```
+
+Вместо агента можно выбрать `cursor`, `gemini`, `all` или `none`. Агент перед входом читает
+`max skill show`; инструкция доступна без сессии. `max session start` остаётся отдельной
+командой импорта токена, а `max session start qr` — явного повторного входа при истёкшей сессии
+([docs/sessions.md](docs/sessions.md)).
+
+Несколько аккаунтов — несколько профилей, и профиль называется **первым словом**, а не флагом:
+
+```sh
+max chats list              # профиль default
+max personal chats list     # профиль personal
+export MAX_PROFILE=personal # или на всю сессию оболочки
+```
+
+## Использование
+
+**Бот пишет в группу, закрепляет объявление и следит за порядком:**
+
+```sh
+max sales bot messages send "Команда продаж" "**Сборка готова**" --md --file report.pdf
+max sales bot messages pin "Команда продаж" <mid>       # id сообщения — из ответа на send
+max sales bot watch --events                             # всё, что происходит в чатах бота, по мере прихода
+max sales bot chats rules set "Команда продаж" links delete
+max sales bot chats moderate "Команда продаж" --dry-run  # что нарушает правила — без действий
+max sales bot contacts show "Иван"                       # где человек писал и его личный чат с ботом
+```
+
+**Разговор от своего имени:**
+
+```sh
+max inbox                                         # непрочитанное во всех чатах, ничего не отмечая
+max messages list "Иван Петров" --limit 20
+max messages send "Иван Петров" "Созвонимся в 15:00?" --reply-to <id>
+max reactions add "Иван Петров" <id> 👍
+max messages send 0 "Позвонить маме" --at-time 2h # напоминание себе в «Избранное» через два часа
+max review --since-time 1d                             # вся переписка за сутки: кто кому что обещал
+```
+
+**Группа, которую вы ведёте:**
+
+```sh
+max chats create "Поход" "Аня" "Борис"            # создать и позвать людей
+max chats admins add "Поход" "Аня" --can pin,members
+max chats link reset "Поход"                      # старая ссылка-приглашение перестаёт работать
+max polls create "Поход" "Когда едем?" "Суббота" "Воскресенье"
+max review --chat "Поход" --unanswered            # вопросы, на которые сутки никто не ответил
+max chats moderate "Поход" --dry-run                 # спам, чужие ссылки, флуд — по вашим правилам
+```
+
+**Найти и сохранить:**
+
+```sh
+max search all "договор"                          # сообщения, почта и заметки сразу, без сети
+max search messages "договор" --chat "Проект Альфа"  # только сообщения одного чата
+max store fetch "Проект Альфа" --last 500
+max store export "Проект Альфа" --format markdown --output alfa.md
+```
+
+Каждая команда отвечает JSON с `--json` и пишет в журнал, что отправила, — без текстов.
+
+Полностью: [docs/usage.md](docs/usage.md). Каждая команда и каждая опция:
+[docs/commands.md](docs/commands.md) — эта страница собирается из самой программы, поэтому описать
+версию, которой не существует, она не может.
+
+## Для скриптов и агентов
+
+### Навык для агентов с терминалом
+
+Навык (skill) — файл с инструкцией, который агент читает перед работой. В навыке `max` описано,
+какие команды есть, что агент делает только по вашей просьбе и как безопасно повторить отправку.
+Его понимают **Claude Code**, **Codex**, **Cursor** и **Gemini CLI**. Навык ставится одной командой и всегда
+той же версии, что и `max`:
+
+```sh
+max skill show                         # прочитать перед входом
+max skill install --for all             # установить без входа
+```
+
+Команда кладёт навык в `~/.claude/skills/max-cli/` для Claude Code и в `~/.agents/skills/max-cli/`
+для Codex, Gemini CLI и Cursor (при поддержке обнаружения навыков); `--for claude` или `--for agents` — только в одну из папок. После
+обновления `max` запустите её ещё раз. Если навыка нет или он старше `max`, агент раз в сутки
+увидит об этом строку в stderr; выключается `max config set skillHint false --defaults`.
+
+Как эти агенты находят навыки: [Codex](https://learn.chatgpt.com/docs/build-skills),
+[Gemini CLI](https://geminicli.com/docs/cli/skills/).
+
+### MCP-сервер для агентов без терминала
+
+Claude Desktop, Cursor и другие клиенты MCP подключаются к `max mcp` и работают с тем же
+аккаунтом. Права `deny`/`readonly` запрещают записи; `ask`/`allow` допускают запрошенное действие через MCP.
+Серверных форм подтверждения нет; подтверждение вызовов зависит от настроек вашего ИИ-приложения.
+Навык доступен ресурсом `max://skill`. Для браузерных клиентов есть
+`max mcp --http --public-url https://<имя>.ts.net`: HTTPS-туннель и вход по коду.
+`--permission ключ=уровень` временно переопределяет права процесса ([подключение](docs/remote.md)).
+
+```sh
+max mcp doctor                      # проверить локальный MCP
+max mcp setup codex                # Codex
+max mcp setup claude-code          # Claude Code
+max mcp config                      # запись для Claude Desktop, Cursor и других — с полными путями
+```
+
+Команды сервера — `/catch-up`, `/review`, `/reply`, `/find` — готовые просьбы: агент знает, какие
+инструменты вызвать и чего не делать.
+
+### Ответы в JSON
+
+```sh
+max chats list --json
+```
+
+С `--json` команда печатает только данные в JSON, без таблиц, цвета и подсказок. Так же она
+работает, когда её вывод читает другая программа, — например, в конвейере `max … | jq`. Любой
+список — чаты, сообщения, участники, всё у бота — приходит в одной форме:
+
+```json
+{ "items": [ … ], "page": 1, "limit": 20, "hasMore": true }
+```
+
+Ошибка приходит отдельно от данных — одной строкой в stderr, а stdout остаётся пустым, поэтому её
+нельзя принять за пустой результат:
+
+```json
+{"error":{"code":"authentication_error","message":"no session for profile \"default\" — run `max setup` in a local terminal; agents: read `max skill show`"}}
+```
+
+У каждой ошибки есть номер — код завершения программы. По нему скрипт решает, что делать дальше:
+`4` — нужно войти, `6` — чат или сообщение не найдены, `9` — MAX не ответил вовремя, `14` —
+неизвестно, выполнено ли изменение. Все коды — в [docs/commands.md](docs/commands.md).
+
+## Безопасность
+
+- Токен входа — в системном хранилище паролей, не в файле и не в строке команды.
+- Локальная копия переписки и все служебные файлы доступны только вашему пользователю; от кражи
+  диска защищает шифрование диска целиком.
+- Перед каждой отправкой, в том числе через фоновый сервер и MCP, `max` проверяет ограничения
+  профиля и пишет строку в журнал — без текста сообщения.
+- Подтверждение MCP-вызовов настройте в приложении агента. `--file` не отправляет ключи и скрытые
+  файлы без `--allow-any-file`; ограничения профиля действуют при каждом вызове.
+- Ограничения защищают от агента, которого уговорило прочитанное сообщение, но не от агента,
+  который хочет их обойти: против такого нужна граница снаружи — песочница или отдельный
+  пользователь.
+
+Подробно — что пишется на диск, что уходит в сеть и чего инструмент не делает никогда:
+[docs/security.md](docs/security.md).
+
+## Документация
+
+- [docs/installation.md](docs/installation.md) — установка, обновление, куда что ложится
+- [docs/bot.md](docs/bot.md) — бот: токен, несколько ботов, сообщения, чаты, список получателей, любая операция API
+- [docs/usage.md](docs/usage.md) — личный аккаунт: вход, чтение, отправка, машинный режим
+- [docs/sessions.md](docs/sessions.md) — токен, хранилище паролей, профили
+- [docs/configuration.md](docs/configuration.md) — настройка по шагам
+- [docs/configuration-reference.md](docs/configuration-reference.md) — все ключи, переменные и порядок разрешения
+- [docs/cli-contract.md](docs/cli-contract.md) — команды, JSON, ошибки, пределы и запуск агентом
+- [docs/mcp.md](docs/mcp.md) — MCP-сервер: подключение, отправка, соединение с MAX
+- [docs/remote.md](docs/remote.md) — ChatGPT или Claude в браузере
+- [docs/groups.md](docs/groups.md) — группы, которые вы ведёте: сценарии с агентом, правила, проверка
+- [docs/people.md](docs/people.md) — один человек: профиль, его сообщения по чатам, похож ли на бота
+- [docs/recipes.md](docs/recipes.md) — рецепты для агентов: сводки, отчёты, долги, напоминания, расписание
+- [docs/diagnostics.md](docs/diagnostics.md) — `--trace`, `--record`, `max runs`
+- [docs/roadmap.md](docs/roadmap.md) — что планируется
+- [docs/security.md](docs/security.md) — что пишется на диск, а что никогда
+- [docs/troubleshooting.md](docs/troubleshooting.md) — по симптому: что делать, когда не работает
+- [docs/commands.md](docs/commands.md) — каждая команда и опция — **генерируется** из программы
+- [docs/dev/protocol.md](docs/dev/protocol.md) — каждый опкод и откуда известна его форма — **генерируется**
+- [docs/dev/ARCHITECTURE.md](docs/dev/ARCHITECTURE.md) — как это устроено и какие швы нельзя пересекать
+- [docs/dev/BACKLOG.md](docs/dev/BACKLOG.md) — что осталось
+
+Оглавление целиком — [docs/README.md](docs/README.md).
+
+## Разработка
+
+```sh
+pnpm install
+pnpm lint && pnpm typecheck && pnpm test
+pnpm build && pnpm smoke:bun          # собранная команда под вторым рантаймом
+pnpm generate                         # переписать сгенерированные файлы
+```
+
+Протокол MAX неофициальный и разобран обратной инженерией: это не Bot API. Каждый опкод и форма
+каждого сообщения объявлены один раз в `src/spec/`, а реестр, типизированный клиент и
+[docs/dev/protocol.md](docs/dev/protocol.md) из них генерируются — и CI падает, если дерево устарело.
+
+Половина, не имеющая отношения к MAX — потоки вывода, рендерер, коды ошибок, хранилище паролей, часы, —
+вынесена в [`@wirecat/cli-core`](https://github.com/WireCatLabs/cli-core) и общая с `braze-cli`.
+
+## Дорожная карта
+
+[docs/roadmap.md](docs/roadmap.md).
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).
+
+## Участие
+
+Пулл-реквесты, сообщения об ошибках и предложения приветствуются —
+[issues](https://github.com/WireCatLabs/max-cli/issues). Как устроен код и как его проверять —
+[docs/dev/ARCHITECTURE.md](docs/dev/ARCHITECTURE.md) и [docs/dev/TESTING.md](docs/dev/TESTING.md).
+
+### Private contact notes and automatic tags
+
+`max contacts alias set <person> <alias>` задаёт локальное имя для выбранного аккаунта;
+`contacts rename` меняет запись в адресной книге мессенджера. Собственные заметки:
+`contacts notes add <person> --file <path>`, затем `list`, `show`, `edit --revision <n>` и `remove`.
+`contacts show --with-notes` включает заметки явно; `contacts list --search-notes <text>` ищет в них.
+Заметка о контакте видна в каждом профиле, который видит этот контакт; псевдоним — только в своём.
+Обновление контактов сохраняет заметки и псевдонимы. Связывание людей не объединяет эти данные.
+
+`max metadata refresh --chat <id>` сохраняет описание группы или канала локально;
+`metadata get --chat <id>` читает сохранённые данные. `tags auto --chat <id> --dry-run`
+показывает метки по ключевым словам. Для актуального описания добавьте `--refresh-metadata`
+без `--dry-run`. Команда обрабатывает не более 500 чатов за запуск, по умолчанию 50.
+Автоматические метки не удаляют ручные; `tags list|remove --source auto` выбирает только
+автоматические метки. Текст сообщений и внешние модели при классификации не используются.

package/dist/adapter/max-adapter.d.ts

@@ -0,0 +1,17 @@
+import type { Message } from "@wirecat/cli-messaging";
+import type { MessageEditing, MessagePins, MessagePolls, MessageReactions, MessengerAdapter, ReadState, ServerReads } from "@wirecat/cli-messaging/cli";
+import type { MaxClient } from "../client.js";
+import type * as Max from "../domain/models.js";
+import { type Reach } from "../download.js";
+import type { SessionStore } from "../session/store.js";
+export type MaxAdapter = MessengerAdapter & ServerReads & MessageEditing & MessagePins & MessageReactions & Pick<ReadState, "markRead"> & MessagePolls & Required<Pick<MessengerAdapter, "buttons" | "pressButton" | "startBot" | "botApp" | "botByLink" | "joinRequests" | "answerJoinRequest" | "people" | "addContact" | "removeContact" | "block" | "unblock" | "renameContact" | "importContacts" | "folders" | "createFolder" | "updateFolder" | "deleteFolder" | "calls" | "privacy" | "media" | "stickerSets" | "stickers" | "mute" | "updatePrivacy" | "orderFolders" | "updateProfile" | "endOtherSessions" | "sessions" | "lookup" | "createGroup" | "join" | "leave" | "deleteChat" | "clearHistory" | "group" | "updateGroup" | "resetInviteLink" | "addMembers" | "removeMembers" | "addAdmin" | "removeAdmin" | "members" | "chatEvents" | "inspect">>;
+/**
+ * cli-messaging's port over a connected `MaxClient` that was built **without** its send guard: the
+ * shared services guard every write, and a second guard would count each one twice. The resend
+ * rule and the name filling stay in `MaxClient` (`NEED-34`).
+ */
+export declare const maxAdapter: (client: MaxClient, store: SessionStore, reach?: Reach, warn?: (message: string) => void, options?: {
+    reactions?: boolean;
+}) => MaxAdapter;
+export declare const toMessage: ({ attachments, replyTo, forwardedFrom, ...message }: Max.Message) => Message;
+//# sourceMappingURL=max-adapter.d.ts.map

package/dist/adapter/max-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/max-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA6B,OAAO,EAAwC,MAAM,wBAAwB,CAAA;AAEtH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EAET,WAAW,EACZ,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAA6B,KAAK,KAAK,EAAe,MAAM,gBAAgB,CAAA;AAInF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGvD,MAAM,MAAM,UAAU,GAAG,gBAAgB,GACvC,WAAW,GACX,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,GAC3B,YAAY,GACZ,QAAQ,CACN,IAAI,CACF,gBAAgB,EACd,SAAS,GACT,aAAa,GACb,UAAU,GACV,QAAQ,GACR,WAAW,GACX,cAAc,GACd,mBAAmB,GACnB,QAAQ,GACR,YAAY,GACZ,eAAe,GACf,OAAO,GACP,SAAS,GACT,eAAe,GACf,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,cAAc,GACd,cAAc,GACd,OAAO,GACP,SAAS,GACT,OAAO,GACP,aAAa,GACb,UAAU,GACV,MAAM,GACN,eAAe,GACf,cAAc,GACd,eAAe,GACf,kBAAkB,GAClB,UAAU,GACV,QAAQ,GACR,aAAa,GACb,MAAM,GACN,OAAO,GACP,YAAY,GACZ,cAAc,GACd,OAAO,GACP,aAAa,GACb,iBAAiB,GACjB,YAAY,GACZ,eAAe,GACf,UAAU,GACV,aAAa,GACb,SAAS,GACT,YAAY,GACZ,SAAS,CACZ,CACF,CAAA;AASH;;;;GAIG;AACH,eAAO,MAAM,UAAU,WACb,SAAS,SACV,YAAY,UACZ,KAAK,SACN,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,YACtB;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,KAC/B,UAsVF,CAAA;AAyCD,eAAO,MAAM,SAAS,wDAAyD,GAAG,CAAC,OAAO,KAAG,OAK3F,CAAA"}