# NeuroSquad Docs

> NeuroSquad — бесплатное десктопное приложение для Windows и macOS, которое запускает CLI ИИ-агентов для программирования — Claude Code, Codex CLI, Gemini CLI, OpenCode и ещё 15 — рядом, живыми карточками-терминалами на одном холсте или в сетке. Стрелка от агента к другой карточке даёт агенту её инструменты: браузер, терминал, заметку, MCP-сервер или другого агента. Приложение сообщает, когда агент закончил или ждёт ответа, управляется с телефона и точно показывает, сколько стоит каждый агент. Это его руководство пользователя.

- Скачать для Windows или macOS: https://neurosquad.ai/ru/download/
- Сайт продукта (факты, вопросы, CLI агентов, плагины, изменения): https://neurosquad.ai/ru/llms.txt

Краткое оглавление: https://docs.neurosquad.ai/ru/llms.txt

---

## Что такое NeuroSquad

> Двухминутный обзор того, что делает NeuroSquad, и нескольких идей, на которых он построен.

Source: https://docs.neurosquad.ai/ru/getting-started

NeuroSquad — бесплатное десктопное приложение для Windows и macOS для работы с ИИ-агентами для кода:
Claude Code, Codex, Gemini CLI, Qwen Code и [ещё 15 CLI агентов](https://docs.neurosquad.ai/ru/agents). Вместо того чтобы жонглировать окнами терминалов, вы получаете **один большой холст**, где
каждый агент живёт в своей карточке рядом с инструментами, с которыми работает. Нажмите play и
посмотрите на один ход агента:

### Четыре идеи — и вы знаете всё приложение

  - **Воркспейс**: Одна папка проекта. Каждый агент, которого вы добавляете в воркспейс, работает в этой папке. Список воркспейсов — в сайдбаре.
  - **Карточка**: Всё, что есть на холсте: агент, терминал, браузер, заметка, доска задач и [многое другое](https://docs.neurosquad.ai/ru/cards). Их можно двигать, менять размер и группировать как угодно.
  - **Стрелка**: Линия от одной карточки к другой. Стрелка от агента **даёт ему возможность** пользоваться другой карточкой — ходить по сайтам в этом браузере, запускать команды в этом терминале, писать в эту заметку или передавать работу этому агенту. [Подробнее о стрелках](https://docs.neurosquad.ai/ru/canvas/arrows).
  - **Внимание**: Когда агент закончил или остановился, чтобы что-то спросить, NeuroSquad сообщает вам: звук, подсвеченная карточка, уведомление на рабочем столе. Можно отвлечься и ничего не пропустить.

### Чем он не является

- **Это не новый ИИ.** NeuroSquad запускает агентов, которые у вас уже есть, с вашими аккаунтами. Он
их не заменяет.
- **Это не облако для вашего кода.** Агенты, проекты и файлы остаются на вашем компьютере. Вы входите
с бесплатным аккаунтом NeuroSquad, а приложение отправляет статистику использования — счётчики, а
не код, файлы или промпты. См. [Аккаунт и вход](https://docs.neurosquad.ai/ru/getting-started/account).

### Дальше

  - **[Установка](https://docs.neurosquad.ai/ru/getting-started/installation)**: Скачайте установщик, пройдите мастер — готово.
  - **[Ваш первый воркспейс](https://docs.neurosquad.ai/ru/getting-started/first-workspace)**: Покажите NeuroSquad свой проект.

---

## Установка

> Скачайте установщик NeuroSquad для Windows, выберите, куда установить, — остальное подготовит мастер первого запуска.

Source: https://docs.neurosquad.ai/ru/getting-started/installation

NeuroSquad поставляется готовым установщиком для **Windows 10 и 11 (64-бит)**. Скачивается
маленький веб-установщик (160 КБ): он загружает последнюю версию (около 100 МБ), сверяет её
контрольную сумму SHA-256 и запускает установку. Ничего не нужно собирать, и терминал не понадобится. Для Mac —
[Установка на macOS](https://docs.neurosquad.ai/ru/getting-started/macos); версия для Linux появится позже.

[Перейти на страницу загрузки](https://neurosquad.ai/ru/download/)

**1. Скачайте NeuroSquad-Installer.exe**

Откройте [страницу загрузки](https://neurosquad.ai/ru/download/) на нашем сайте и нажмите
**Скачать для Windows**. При запуске он скачает последнюю версию NeuroSquad, проверит её и
откроет установку.

**2. Запустите его — и пройдите SmartScreen**

У установщика пока нет цифровой подписи, поэтому Windows может показать синее окно **Windows
protected your PC** («Система Windows защитила ваш компьютер»). Нажмите **More info**
(«Подробнее»), проверьте, что приложение называется `NeuroSquad-Installer.exe`, и нажмите **Run
anyway** («Выполнить в любом случае»).

**3. Выберите, куда установить**

**Папка установки** уже заполнена: `%LOCALAPPDATA%\Programs\NeuroSquad`. Оставьте её или
выберите другую кнопкой **Обзор…** — строка под полем показывает, сколько места нужно
NeuroSquad (369 МБ) и сколько свободно на диске. Переключатель **Ярлык на рабочем столе**
оставьте включённым, если хотите значок NeuroSquad на рабочем столе.

В папку по умолчанию NeuroSquad ставится только для вашей учётной записи Windows, и внизу окна
написано **права администратора не нужны**. Для папки вроде Program Files там будет **нужны
права администратора · Windows спросит разрешение** — и после нажатия «Установить» Windows
действительно спросит.

**4. Нажмите «Установить»**

Окно показывает текущий шаг, сколько файлов уже распаковано, и полосу прогресса. **Показать
журнал** открывает журнал установки: каждый файл с размером и контрольной суммой, с отметками
времени. **Отмена** работает, пока идёт распаковка, и убирает всё, что успело скопироваться.

**5. Запустите NeuroSquad**

Когда появится **NeuroSquad установлен**, нажмите **Запустить NeuroSquad**. Дальше приложение
есть в меню «Пуск» (и на рабочем столе, если вы оставили ярлык).

> SmartScreen показывает это предупреждение для любого нового приложения, ещё не подписанного
> сертификатом. Скачивайте установщик только с нашей
> [страницы загрузки](https://neurosquad.ai/ru/download/).

### Установка из терминала

Тот же установщик, без окон: для вашей учётной записи Windows, без прав администратора. Каждый
способ сверяет загрузку с контрольной суммой SHA-256, прежде чем её запустить, а дальше NeuroSquad
обновляется сам — как бы вы его ни установили.

**winget** — диспетчер пакетов Windows, встроен в Windows 10 и 11:

```powershell
winget install NeuroSquad.NeuroSquad
```

**Scoop** — добавляет бакет NeuroSquad и устанавливает в папку приложений Scoop:

```powershell
scoop bucket add neurosquad https://github.com/glmn-ai/scoop-neurosquad
scoop install neurosquad
```

**PowerShell** — скачивает последнюю версию, ставит её в `%LOCALAPPDATA%\Programs\NeuroSquad` и
запускает NeuroSquad (Windows PowerShell 5.1 или PowerShell 7):

```powershell
irm https://neurosquad.ai/install.ps1 | iex
```

### Вход

При первом запуске NeuroSquad просит войти в аккаунт NeuroSquad — он бесплатный. Откроется браузер
с app.neurosquad.ai: войдите по коду из письма или через Google, нажмите **Connect**, и приложение
это подхватит. До этого приложение показывает только экран входа. По шагам, и что приложение
отправляет, пока вы вошли: [Аккаунт и вход](https://docs.neurosquad.ai/ru/getting-started/account).

### Мастер первого запуска

После входа NeuroSquad проверяет, что уже есть на компьютере, и предлагает поставить
недостающее. Ничего не меняется, пока вы не нажмёте кнопку, и любой шаг можно пропустить — единственное
исключение Node.js (ниже).

**1. CLI агента**

ИИ-агент, которого будут запускать ваши карточки. Если он уже есть, мастер так и скажет. Если
нет — выберите Claude Code, Codex CLI, OpenCode или Kilo Code и нажмите **Install it for me**: мастер
установит его через npm и покажет, какая именно команда выполняется. Нет npm? Без него CLI агентов
не поставить, поэтому мастер сам устанавливает Node.js LTS: официальный архив с nodejs.org с проверкой
опубликованного SHA-256, только для вашей учётной записи — без прав администратора. На Windows это
уже делает установщик, если Node.js нет; уже установленный Node.js никогда не трогается.

**2. Терминал и Git**

Git for Windows приносит с собой Git Bash — им пользуются карточки терминала и изолированные
worktree. Мастер ставит его через `winget` — и всегда сначала спрашивает.

**3. Диктовка**

Модели распознавания речи в установщике нет — она скачивается отдельно. Выберите модель и
нажмите **Download** или пропустите шаг: диктовка необязательна, и от неё больше ничего не
зависит. Скачать модель можно и позже, в **Settings → Dictation**; до тех пор в строке состояния
написано **Dictation: download the model**. См. [Модели распознавания речи](https://docs.neurosquad.ai/ru/dictation/models).

**4. Готово**

Нажмите **Start working**. Вернуться к этим шагам можно в любой момент в **Settings → Setup**.

> Во все агенты вы входите как обычно — запустите агента один раз в карточке и следуйте его
> собственному приглашению ко входу. NeuroSquad никогда не спрашивает ваши ключи.

### Обновление

NeuroSquad обновляется сам. Чтобы обновиться вручную, снова запустите `NeuroSquad-Installer.exe` со
[страницы загрузки](https://neurosquad.ai/ru/download/) — он всегда скачивает самую новую версию.
Установленную версию установщик находит сам: в поле папки уже стоит папка прежней установки,
кнопка называется **Обновить**, а заметка обещает, что воркспейсы, агенты и настройки сохранятся —
они лежат в `%APPDATA%\NeuroSquad`, а не в папке самого приложения.

Если NeuroSquad ещё запущен, установщик покажет **NeuroSquad ещё работает** со списком процессов,
которые держат его файлы, — само приложение и терминалы его карточек, с именем и PID. Закройте
NeuroSquad сами и нажмите **Проверить ещё раз** или нажмите **Завершить и продолжить** (терминалы
в карточках NeuroSquad остановятся).

Новая версия распаковывается рядом со старой и подменяет её, только когда распакована целиком.
Если обновление не удалось или вы его отменили, прежняя версия остаётся нетронутой.

### Удаление

Откройте **Параметры Windows → Приложения**, найдите **NeuroSquad** и выберите **Удалить** (или
запустите `Uninstall NeuroSquad.exe` в папке установки). Удаляются ровно те файлы, которые
поставил установщик, ярлыки и запись в списке приложений. Файлы, которые вы сами положили в папку
установки, остаются.

Ваши данные тоже остаются — если не включить **Удалить и мои данные NeuroSquad** (по умолчанию
выключено). Этот переключатель удаляет `%APPDATA%\NeuroSquad`: список воркспейсов, агентов,
настройки, модели диктовки и изолированные worktree агентов — незакоммиченная работа в этих
worktree пропадёт. Папки ваших проектов не затрагиваются никогда. См.
[Где хранятся ваши данные](https://docs.neurosquad.ai/ru/help/data).

### Установка без участия пользователя

Для администраторов и скриптов установщик умеет работать без окна. Полный установщик последней
версии лежит по адресу `https://neurosquad.ai/downloads/NeuroSquad-Setup.exe`; веб-установщик
передаёт ему те же параметры.

```text
NeuroSquad-Setup.exe --silent [--dir <папка>] [--no-desktop] [--launch] [--close-app]
```

- `--dir` — папка установки (по умолчанию `%LOCALAPPDATA%\Programs\NeuroSquad` или папка
существующей установки)
- `--no-desktop` — без ярлыка на рабочем столе
- `--launch` — запустить NeuroSquad после установки
- `--close-app` — завершить запущенные процессы NeuroSquad, а не отказаться от установки

Коды выхода: `0` — установлено, `1` — ошибка, `2` — файлы заняты (NeuroSquad запущен, а
`--close-app` не передан). Удаление без окна:

```text
"Uninstall NeuroSquad.exe" --silent [--delete-data]
```

### Если что-то пошло не так

Страница ошибки простыми словами объясняет, что случилось, показывает подробности и журнал и
предлагает **Повторить**. Если установка сорвалась до замены файлов, прежняя версия продолжает
работать.

Полный журнал каждого запуска установщик сохраняет в `%TEMP%\NeuroSquad-Setup-<дата>.log`, а его
копию — как `install.log` в папке установки. Кнопки **Скопировать журнал** и **Открыть файл
журнала** есть в панели журнала — приложите журнал, когда сообщаете о проблеме.

### Дальше

  - **[Ваш первый воркспейс](https://docs.neurosquad.ai/ru/getting-started/first-workspace)**: Покажите NeuroSquad папку проекта — или изучите демо.

---

## Установка на macOS

> Установите NeuroSquad на Mac с Apple silicon или Intel — одной строкой в Терминале или из .dmg — и что macOS спросит при первом запуске.

Source: https://docs.neurosquad.ai/ru/getting-started/macos

NeuroSquad работает на **macOS 12 Monterey и новее**; для **Apple silicon** (M1, M2, M3, M4 и новее)
и для Mac на **Intel** — отдельные сборки. Не знаете, какой у вас Mac? Меню Apple → **Об этом Mac**:
«Чип: Apple M…» — это Apple silicon, «Процессор: Intel» — Intel.

[Перейти на страницу загрузки](https://neurosquad.ai/ru/download/#macos)

### Из Терминала (рекомендуем)

Одна строка выберет сборку для вашего Mac, сверит её с опубликованной контрольной суммой SHA-256,
положит **NeuroSquad.app** в **Программы** и откроет:

```bash
curl -fsSL https://neurosquad.ai/install.sh | bash
```

Если ваша учётная запись не может писать в `/Applications`, скрипт установит приложение в
`~/Applications` — пароль администратора не нужен ни в каком случае. Установленная так копия
открывается сразу, даже без вопроса при первом запуске, о котором ниже. Повторный запуск строки обновит
установленную версию.

### Через Homebrew

Если вы пользуетесь [Homebrew](https://brew.sh), установите NeuroSquad из нашего собственного tap:

```bash
brew install --cask glmn-ai/neurosquad/neurosquad
```

Он поставит сборку для вашего чипа, сверив её с контрольной суммой SHA-256, и снимет пометку о
загрузке, так что приложение откроется без вопроса при первом запуске. Дальше NeuroSquad обновляется
сам, поэтому `brew upgrade` его не трогает (`brew upgrade --greedy` обновит и его). `brew uninstall
--cask neurosquad` удаляет приложение; с `--zap` удалятся и ваши данные NeuroSquad.

### Из .dmg

**1. Скачайте .dmg для своего Mac**

На [странице загрузки](https://neurosquad.ai/ru/download/#macos) нажмите **Скачать .dmg** под
**Apple silicon** или **Intel** (страница подсвечивает тот, о котором сообщил браузер). Прямые
ссылки: [Apple silicon](https://neurosquad.ai/downloads/NeuroSquad-arm64.dmg),
[Intel](https://neurosquad.ai/downloads/NeuroSquad-x64.dmg); контрольные суммы —
[SHA256SUMS-mac.txt](https://neurosquad.ai/downloads/SHA256SUMS-mac.txt).

**2. Перетащите NeuroSquad в «Программы»**

Откройте .dmg и перетащите **NeuroSquad** на папку **Applications** рядом.

**3. Первый запуск: нажмите «Открыть»**

NeuroSquad подписан Apple Developer ID и нотаризован Apple. При первом открытии копии, скачанной
браузером, macOS задаст тот же вопрос, что и для любой программы из интернета: **«NeuroSquad» —
это приложение, загруженное из интернета. Вы действительно хотите его открыть?** — и добавит, что
Apple проверила его на вредоносное ПО и ничего не нашла. Нажмите **Открыть**. Больше macOS
спрашивать не будет.

> Вопрос касается способа загрузки, а не приложения: браузер помечает каждый скачанный файл как «из
> интернета». Установка из Терминала, Homebrew и обновления самого NeuroSquad скачивают без этой
> пометки, поэтому не будет даже этого вопроса.

#### Если macOS всё равно не открывает приложение

Версии до 0.1.218 не были нотаризованы. Если macOS пишет, что **«NeuroSquad» не открыто**, что Apple
не может его проверить или что оно повреждено, скорее всего, у вас такая старая копия: переместите её
в Корзину и заново скачайте .dmg со [страницы загрузки](https://neurosquad.ai/ru/download/#macos) или
установите строкой в Терминале либо через Homebrew (см. выше). Ваши данные останутся на месте.

### Разрешения для диктовки

Голосовой диктовке нужны два разрешения macOS. **Настройки → Диктовка** показывают, чего не
хватает, с кнопкой **Разрешить** и переходом в нужный раздел Системных настроек:

- **Микрофон** — чтобы записывать голос. macOS спросит при первой диктовке.
- **Универсальный доступ** — для глобальной горячей клавиши диктовки, которая работает в любом
приложении. Включите **NeuroSquad** в **Системные настройки → Конфиденциальность и безопасность →
Универсальный доступ**; клавиша заработает сразу после разрешения.

После обновлений эти разрешения сохраняются. Одно исключение: если у вас стояла версия 0.1.214 —
первая сборка для Mac, — после обновления до 0.1.218 macOS ещё раз спросит Микрофон и Универсальный
доступ, потому что именно тогда подпись приложения сменилась на Apple Developer ID.

### Вход и мастер настройки

Дальше всё как на Windows — см. [Установка](https://docs.neurosquad.ai/ru/getting-started/installation), разделы про вход и мастер
настройки. На Mac мастер ставит CLI агентов через npm, а если npm нет — Node.js LTS в `~/.neurosquad/node`
(профиль shell не меняется); Git без участия пользователя он поставить не может и даёт ссылку на его
страницу загрузки (через Homebrew: `brew install git`).
Карточки терминала используют ваш login-shell (`$SHELL`, по умолчанию zsh), а NeuroSquad находит
CLI, установленные через Homebrew, npm, bun, cargo и т. п., хотя приложения, запущенные из Dock,
получают минимальный `PATH`.

### Обновление

NeuroSquad обновляется сам, как и на Windows: новая версия скачивается в фоне, сверяется с
контрольной суммой SHA-256 и устанавливается при перезапуске — приложение заменяется в своей папке и
открывается снова. **NeuroSquad → Проверить обновления…** в строке меню проверяет сразу.

Если NeuroSquad не может писать в свою папку (например, лежит в `/Applications`, а ваша учётная
запись — не администратор), он распакует обновление в **Загрузки** и покажет его в Finder: закройте
NeuroSquad и перетащите новую копию в «Программы» с заменой старой.

### Закрытие и выход

Красная кнопка закрытия прячет окно: NeuroSquad и его агенты продолжают работать, щелчок по значку в
Dock возвращает окно. Выход — **Cmd+Q** (или **NeuroSquad → Завершить NeuroSquad**), он останавливает
терминалы агентов.

### Удаление

Завершите NeuroSquad и перенесите **NeuroSquad.app** из «Программ» в Корзину. Ваши данные — воркспейсы,
агенты, настройки, модели диктовки — остаются в `~/Library/Application Support/NeuroSquad`; удалите и
эту папку, если хотите убрать всё. Папки ваших проектов не трогаются. См.
[Где хранятся ваши данные](https://docs.neurosquad.ai/ru/help/data).

---

## Аккаунт и вход

> Зачем NeuroSquad просит войти, как устроен вход из приложения, тариф и устройства, работа без интернета и какая именно статистика использования отправляется.

Source: https://docs.neurosquad.ai/ru/getting-started/account

NeuroSquad работает с **аккаунтом NeuroSquad**. Он бесплатный: у каждого аккаунта тариф **Free** без
ограничений. Вы входите один раз на каждом компьютере — в браузере, по коду из письма или через
Google.

Ваш код, файлы, промпты и терминалы остаются на вашем компьютере — аккаунт этого не меняет. Он
меняет две вещи: приложение просит войти, а пока вы вошли, отправляет **статистику использования** —
счётчики, а не содержимое. Полный список — [ниже](#what-the-app-sends).

### Зачем аккаунт

- **Тариф принадлежит вам**, а не одному компьютеру.
- **Вы видите все компьютеры**, которые пользуются вашим аккаунтом, и можете выйти на любом из них.
- **Мы узнаём, как пользуются NeuroSquad**, — какими агентами, карточками и функциями, — и понимаем,
что делать дальше.

### Вход из приложения

Пока вы не вошли, NeuroSquad показывает только экран входа: холста нет, и агенты не запускаются.

**1. Открывается браузер**

Приложение открывает **app.neurosquad.ai** в браузере по умолчанию и показывает короткий код
вида `ABCD-EFGH`.

**2. Войдите на странице**

Введите email и 6-значный код из письма (он действует 10 минут) или нажмите **Google**. Новый
email просто создаёт новый аккаунт — отдельной регистрации нет.

**3. Подключите этот компьютер**

Страница спросит, подключить ли NeuroSquad на вашем компьютере — по его имени, — и покажет тот же
код. Проверьте, что он совпадает с кодом в приложении, и нажмите **Connect**. Страница ответит
**Done — return to NeuroSquad**.

**4. Вернитесь в приложение**

Приложение само заметит вход за несколько секунд — или нажмите **I've signed in**, чтобы
проверить сразу. Случайно закрыли вкладку? **Open the browser again** откроет её снова. Код
действует 10 минут, потом начните заново.

> Нажимайте **Connect** только для кода, который видите в своём окне NeuroSquad. Подключив чужой код,
> вы впустите в *свой* аккаунт *чужой* компьютер.

### Ваш тариф

Приложение показывает аккаунт, под которым вы вошли, и его тариф. Сейчас у каждого аккаунта
**Free — без ограничений**.

### Сменить аккаунт или выйти

Выход возвращает приложение на экран входа. С компьютера ничего не удаляется: воркспейсы, агенты,
заметки и настройки остаются на месте и снова будут с вами после входа — под тем же аккаунтом или
под другим.

### Управление аккаунтом в вебе

Откройте [app.neurosquad.ai/account](https://app.neurosquad.ai/account) в любом браузере и войдите
тем же способом. Там можно:

- **Изменить имя и картинку.** Картинка — PNG, JPEG или WebP до 2 МБ; она перекодируется в 256×256,
метаданные удаляются. Без картинки показывается кружок с инициалами — одинаковый в приложении и в
вебе.
- **Посмотреть устройства** — имя каждого компьютера, систему, версию приложения и когда его видели
в последний раз — и **выйти** на любом из них. Этот компьютер вернётся на экран входа.
- **Удалить аккаунт.** Вы подтверждаете это кодом из письма. Аккаунт и его статистика использования
удаляются; на ваших компьютерах ничего не трогается.

### Без интернета

Для входа нужен интернет. Дальше NeuroSquad продолжает работать, даже если NeuroSquad Cloud
недоступен: приложение работает как обычно и показывает неброскую пометку **offline**. Так можно
**7 дней** с момента, когда приложение последний раз связалось с облаком; после этого оно попросит
войти снова.

Если сессия этого компьютера закончилась — например, вы вышли на нём через веб, — приложение
вернётся на экран входа. Данные на компьютере не затрагиваются.

### Что отправляет приложение

Пока вы вошли, приложение отправляет в NeuroSquad Cloud (`api.neurosquad.ai`) эту статистику
использования — и ничего больше. Компьютер обозначается случайным идентификатором установки, а
каждый воркспейс — случайным идентификатором, созданным для него, а не папкой или названием.
Статистика привязана к вашему аккаунту, и команда NeuroSquad видит её по каждому аккаунту.

| Когда | Что |
| --- | --- |
| Каждую минуту, пока приложение работает | Версия приложения, операционная система, в фокусе ли окно, сколько воркспейсов открыто, сколько агентов каждого CLI работает |
| При запуске приложения | Версия приложения, операционная система и её версия, язык приложения; первый запуск новой установки отмечается отдельно |
| Когда открывается воркспейс, затем каждые 30 минут | Сколько в нём карточек каждого типа, агентов каждого CLI, стрелок и групп |
| Когда запускается агент | Какой CLI, свой вход или OpenRouter, включены ли опасный режим и режим холста |
| Когда вы пользуетесь некоторыми функциями | Название функции из фиксированного списка, встроенного в приложение |
| При каждой диктовке | Сколько длилась запись, какая модель и движок (CPU или GPU), получился ли текст — но не сам текст |
| При входе и вместе со всем выше | Ваша страна — сервер определяет её по IP-адресу; сам IP не сохраняется |

Отдельные события хранятся 90 дней; дневные итоги по ним (например, сколько людей были активны за
день) хранятся и дальше.

#### Никогда не отправляется

- Код, содержимое файлов, имена файлов, пути к папкам, адреса репозиториев
- Названия воркспейсов, карточек и агентов
- Промпты, ответы агентов, вывод терминалов
- Переменные окружения, пароли, токены и API-ключи

Сервер отклоняет любое поле, которого нет в его списке, поэтому даже ошибка в приложении не может
подмешать содержимое. Сами агенты по-прежнему общаются со своими ИИ-сервисами напрямую, как всегда, —
не через NeuroSquad. Полное уведомление о приватности — на
[neurosquad.ai/ru/privacy](https://neurosquad.ai/ru/privacy/).

### Дальше

  - **[Ваш первый воркспейс](https://docs.neurosquad.ai/ru/getting-started/first-workspace)**: Укажите NeuroSquad папку проекта — или изучите демо.
  - **[Где хранятся данные](https://docs.neurosquad.ai/ru/help/data)**: Что остаётся на компьютере и как сделать резервную копию.

---

## Ваш первый воркспейс

> Создайте воркспейс для папки проекта или сначала осмотритесь в готовых воркспейсах — демо и «Launch day».

Source: https://docs.neurosquad.ai/ru/getting-started/first-workspace

**Воркспейс** — это папка проекта. Каждый агент в нём запускается в этой папке, поэтому сразу
понимает, о каком «коде» речь.

### Сначала осмотритесь в демо

При самой первой установке NeuroSquad создаёт небольшой воркспейс **NeuroSquad demo**: агент Claude
Code **Lead**, уже соединённый с терминалом, заметка **Start here** и список задач **Try these**, а
ещё доска задач и заметка о том, как работают стрелки. В агенте уже набран первый промпт — он ждёт,
когда вы нажмёте Enter. Демо живёт в служебной папке — ничего вашего не затрагивается. Если вы его
удалили и хотите вернуть, на пустом холсте есть кнопка, чтобы открыть его снова.

### Всё сразу: «Launch day»

Хотите увидеть полную сборку? Откройте **What's new** внизу сайдбара и нажмите **Open Launch day**.
Появится небольшой интернет-магазин, который готовится к запуску, — разложенный по пяти главам в
рамках:

- **Start here** — стикер, заметка-путеводитель и список задач с обзором.
- **Build squad** — три агента Claude Code (**Lead**, **Frontend**, **Backend**) и доска задач, где
задачи уже назначены им. Нажмите **Start**, чтобы начать.
- **Dev tools** — терминал с дев-сервером, браузер и карточка дев-серверов.
- **Business desk** — заметки, карточка Telegram-бота и карточка-референс с макетами.
- **Mission control** — стендап, бюджет, слежение за страницей и таймер фокуса.

Как и демо, он живёт в служебной папке. Удалить его ничего не стоит.

### Создайте воркспейс

**1. Нажмите + рядом с Workspaces в сайдбаре**

Откроется окно **Create workspace**.

**2. Дайте ему имя**

Что-нибудь понятное вам — «Интернет-магазин», «Блог», «Клиент X».

**3. Выберите папку проекта**

Нажмите **Browse…** и выберите папку с проектом. Агенты будут работать там.

**4. Выберите цвет (по желанию)**

Пригодится, когда воркспейсов станет несколько, — цвет отмечает воркспейс в сайдбаре.

> Удаление воркспейса убирает его только из NeuroSquad. Папка и ваши файлы остаются на месте.

### Дополнительно

Если агенты будут работать в [изолированных worktree](https://docs.neurosquad.ai/ru/agents/worktrees), в окне правки воркспейса
можно также задать **команду настройки** (например, установку зависимостей), **файлы для
копирования** в каждый новый worktree (вроде `.env`) и **команду запуска**, которая стартует проект
и открывает его в браузерной карточке. В том же окне настраивается зеркало
[файла инструкций](https://docs.neurosquad.ai/ru/agents/instructions).

### Дальше

  - **[Ваш первый агент](https://docs.neurosquad.ai/ru/getting-started/first-agent)**: Добавьте агента и отправьте ему промпт.

---

## Ваш первый агент

> Добавьте карточку агента, отправьте первый промпт и получите уведомление, когда он закончит.

Source: https://docs.neurosquad.ai/ru/getting-started/first-agent

Любая карточка начинается с одного и того же меню. Главная кнопка добавляет агента, которого вы
выбирали в прошлый раз, а стрелка рядом с ней открывает всё остальное. Наведите курсор на любой
пункт:

**1. Откройте меню добавления**

Открыв воркспейс, нажмите **Add Claude Code** (или стрелку рядом) в правом верхнем углу холста,
строку добавления под воркспейсом в сайдбаре или кнопку на пустом холсте. Меню везде одно и то же.

**2. Выберите агента**

Выберите одного из установленных ИИ-агентов — например, **Claude Code**. Появится карточка с живым
терминалом, и агент запустится в папке вашего проекта. Хотите сначала выбрать модель или роль?
Выберите **New agent… (provider, model, role)** — см. [OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter) и
[Роли](https://docs.neurosquad.ai/ru/agents/roles).

**3. Введите промпт**

Щёлкните по карточке и печатайте, как в обычном терминале. Попробуйте: *«Осмотрись в этом проекте
и расскажи, что он делает»*.

**4. Отвлекитесь**

Займитесь чем-нибудь другим. Когда агент закончит — или будет ждать вашего ответа, — прозвучит
сигнал, карточка подсветится, а уведомление на рабочем столе назовёт агента. См.
[Закончил / ждёт вашего ответа](https://docs.neurosquad.ai/ru/agents/notifications).

Заголовок карточки заполняется сам — по тому, чем занят агент. Щёлкните по заголовку, чтобы дать
карточке своё имя.

> Если агент спросит, можно ли доверять папке, NeuroSquad ответит за вас — вы уже выбрали эту папку,
> когда создавали воркспейс.

### Что дальше

  - **[Дайте ему возможности](https://docs.neurosquad.ai/ru/canvas/arrows)**: Подключите браузер или терминал стрелкой.
  - **[Уведомления](https://docs.neurosquad.ai/ru/agents/notifications)**: «Закончил» и «ждёт вашего ответа».
  - **[Всё о карточке агента](https://docs.neurosquad.ai/ru/agents/card-menu)**: Шапка и меню ⋯ — пункт за пунктом.
  - **[Добавьте второго агента](https://docs.neurosquad.ai/ru/squads)**: И пусть первый им руководит.

---

## Что где находится

> Сайдбар и пять его разделов, холст, верхняя панель и строка состояния — что где находится.

Source: https://docs.neurosquad.ai/ru/getting-started/the-window

Наведите курсор на синие точки, чтобы узнать, для чего нужна каждая часть окна:

### Сайдбар

Ряд из пяти кнопок вверху сайдбара переключает его разделы. Бейджи на них показывают, сколько
агентов работает, сколько ждут вас и сколько задач открыто. Пощёлкайте по ним:

  - **Workspaces**: Ваши проекты, а внутри каждого — его агенты и группы. Крутящееся кольцо вокруг иконки агента значит, что он сейчас работает.
  - **Agents**: Все ИИ-агенты из всех воркспейсов, сгруппированные по тому, чем они заняты: **Needs input**, **Working**, **Finished**, **Idle**, **Not running**. Фильтр по имени, воркспейсу или типу агента.
  - **Inbox**: Всё, что ждёт вас, — агенты, которые закончили или остановились, чтобы что-то спросить. Нажмите **Mark all seen**, когда разберётесь.
  - **Tasks**: Задачи со всех [досок задач](https://docs.neurosquad.ai/ru/cards/kanban) и [списков задач](https://docs.neurosquad.ai/ru/cards/todo) из всех воркспейсов.
  - **Integrations**: Ваши [карточки Telegram](https://docs.neurosquad.ai/ru/integrations/telegram) и ваши [провайдеры моделей](https://docs.neurosquad.ai/ru/providers).

Внизу: **Features** (входящие внимания, шаблоны, журнал сбоев, история активности и команд),
**Usage**, **What's new** и **Settings**. Потяните за край сайдбара, чтобы сделать его шире или уже.

### Остальное окно

  - **Холст (в центре)**: Здесь живут ваши карточки. Двигайте и масштабируйте холст, переставляйте карточки, рисуйте стрелки. См. [Основы холста](https://docs.neurosquad.ai/ru/canvas).
  - **Верхняя панель**: Показывает, где вы находитесь (воркспейс › группа), а дальше — кнопку удалённого доступа, колокольчик уведомлений, кнопку [доски «Команда»](https://docs.neurosquad.ai/ru/squads), кнопку истории диктовки и кнопки окна.
  - **Строка состояния (внизу)**: Сколько агентов работает или ждёт, версия приложения (щёлкните по ней, чтобы узнать, что нового) и состояние диктовки.
  - **История диктовки (справа)**: Всё, что вы недавно надиктовали, — можно снова скопировать. См. [История диктовки](https://docs.neurosquad.ai/ru/dictation/history).

### Полезные сочетания клавиш

| Сочетание | Что делает |
| --- | --- |
| `Ctrl Shift P` | Перейти к любому агенту по имени |
| `Ctrl Shift J` | Перелететь к агенту, который ждёт вас дольше всех |
| `Ctrl Shift F` | Искать по выводу всех агентов |
| `Ctrl Shift Space` | Начать или остановить диктовку |
| `F5` | Показать холст карточку за карточкой |

Полный список — в разделе [Горячие клавиши](https://docs.neurosquad.ai/ru/help/shortcuts).

---

## Основы холста

> Холст — это бесконечная доска, где ваши агенты и их инструменты живут в виде карточек.

Source: https://docs.neurosquad.ai/ru/canvas

У каждого воркспейса свой **холст** — бесконечная доска, которую можно двигать и масштабировать. Всё,
что вы добавляете в воркспейс, появляется на ней в виде **карточки**.

Переключение на другой воркспейс ничего не останавливает: агенты в других воркспейсах продолжают
работать в фоне, а сайдбар показывает, кто из них занят.

  - **[Добавление и расстановка карточек](https://docs.neurosquad.ai/ru/canvas/cards)**: Добавляйте, двигайте, меняйте размер, переименовывайте и удаляйте карточки.
  - **[Стрелки дают возможности](https://docs.neurosquad.ai/ru/canvas/arrows)**: Соединяйте карточки, чтобы агенты могли ими пользоваться.
  - **[Группы](https://docs.neurosquad.ai/ru/canvas/groups)**: Собирайте связанные карточки в именованную рамку.
  - **[Масштаб, перемещение и отмена](https://docs.neurosquad.ai/ru/canvas/moving-around)**: Ориентируйтесь на большом холсте; при отдалении — плитки-обзоры.
  - **[Инструменты холста](https://docs.neurosquad.ai/ru/canvas/tools)**: Направляющие, миникарта, цветные метки, режим показа, журнал стрелки, шаблоны.

---

## Добавление и расстановка карточек

> Как добавлять, двигать, менять размер, переименовывать, выделять и удалять карточки на холсте.

Source: https://docs.neurosquad.ai/ru/canvas/cards

### Добавить карточку

Нажмите **Add Claude Code** в правом верхнем углу холста (на кнопке — тот агент, которого вы
добавляли последним) или стрелку рядом с ней — там всё остальное. Строка добавления в сайдбаре и
пустой холст открывают то же самое меню:

- **ИИ-агенты** — Claude Code, OpenCode, Hermes Agent, Kilo Code, Codex CLI, Pi, omp, Cursor CLI,
Qwen Code и Crush, а также **New agent…**, чтобы сначала выбрать провайдера, модель и роль.
- **Терминалы** — оболочка вашей системы, Windows PowerShell, PowerShell 7, Командная строка и Bash
(только те, что найдены на вашем компьютере).
- **Карточки** — браузер, заметка, список задач, бюджет, доска задач, Telegram-бот, справочник,
дев-серверы, слежение за страницей, таймер фокуса, стикер и стендап. См. [Все карточки](https://docs.neurosquad.ai/ru/cards).

Новая карточка встаёт справа от предыдущей. Карточки, которые агент создаёт себе сам, появляются
вокруг этого агента.

### Двигать, менять размер, переименовывать

- **Двигать:** тяните карточку за шапку.
- **Менять размер:** тяните за край или угол карточки.
- **Переименовать:** щёлкните по заголовку в шапке и введите имя.
- **Развернуть:** кнопка разворота в шапке растягивает карточку на весь холст; нажмите её ещё раз,
чтобы вернуть как было.

### Выделить несколько карточек

Зажмите `Shift` и протяните по пустому холсту, чтобы нарисовать рамку выделения, или
зажмите `Shift` либо `Ctrl` и щёлкайте по карточкам по одной. Затем двигайте их
вместе.

### Удалить

Выделите одну или несколько карточек и нажмите `Delete`. У агента пункт **Delete agent** —
последняя строка его меню ⋯; у остальных карточек кнопка удаления есть в шапке. NeuroSquad всегда
сначала спрашивает: удаление агента завершает его работающую сессию.

> Удаление карточки никогда не удаляет файлы в вашем проекте.

### Открыть в отдельном окне

Карточку агента можно вынести в отдельное окно (**Pop out to new window** в её меню ⋯) — удобно на
втором мониторе. Это тот же агент, просто показанный в двух местах.

---

## Стрелки дают возможности

> Проведите стрелку от агента к другой карточке — и агент сможет ею пользоваться.

Source: https://docs.neurosquad.ai/ru/canvas/arrows

Это самая важная идея в NeuroSquad. **Стрелка от агента к карточке даёт агенту возможность
пользоваться этой карточкой.** Посмотрите, как это работает, — от первой стрелки до журнала стрелки:

### Как провести стрелку

Наведите курсор на карточку — по её краям появятся маленькие точки. Потяните от точки к другой
карточке и отпустите. Чтобы убрать стрелку, выделите её и нажмите `Delete` или дважды
щёлкните по ней.

### Что даёт каждая стрелка

| Стрелка от агента к… | Её подпись | Агент может… |
| --- | --- | --- |
| [браузеру](https://docs.neurosquad.ai/ru/cards/browser) | инструменты браузера | открывать страницы, кликать, вводить текст, читать, что на экране и в консоли |
| [терминалу](https://docs.neurosquad.ai/ru/cards/terminal) | инструменты терминала | запускать команды и читать их вывод |
| [заметке](https://docs.neurosquad.ai/ru/cards/note) | общая заметка | читать и писать заметку |
| [списку задач](https://docs.neurosquad.ai/ru/cards/todo) | список задач | записывать свой план и отмечать выполненные задачи |
| [доске задач](https://docs.neurosquad.ai/ru/cards/kanban) | доска задач | добавлять задачи и продвигать свои задачи дальше |
| другому агенту | связь команды | давать ему задачи и читать его ответы — см. [Команды агентов](https://docs.neurosquad.ai/ru/squads) |

Со стрелками работают и другие карточки: [дев-серверы](https://docs.neurosquad.ai/ru/cards/dev-servers) сообщают подключённому
агенту, какие серверы запущены, [справочник](https://docs.neurosquad.ai/ru/cards/reference) даёт ему читать ваши макеты и
спецификации, [слежение за страницей](https://docs.neurosquad.ai/ru/cards/web-watch) сообщает, что страница изменилась, а карточка
[Telegram](https://docs.neurosquad.ai/ru/integrations/telegram) передаёт ему ваши сообщения и позволяет на них отвечать.

### Смотрите, как это происходит

Пока агент пользуется карточкой, стрелка оживает и показывает, что он делает, — «Opening»,
«Clicking», «Running», «Adding to the note». Вы всегда видите, какой агент что трогает.

### Журнал стрелки

Щёлкните по стрелке, чтобы открыть её **Arrow log**: каждая команда, открытая страница, заметка или
переданная задача, прошедшая по ней, со временем. Журнал сохраняется между перезапусками. **Clear log**
очищает его.

> Подключёнными карточками умеет пользоваться каждый поддерживаемый агент — **aider** и **Pi** через
> расширение NeuroSquad, потому что своего MCP-клиента у них нет. Что ещё получает каждый — см.
> [Поддерживаемые агенты](https://docs.neurosquad.ai/ru/agents).

---

## Режим сетки

> Агенты рядом друг с другом в аккуратной сетке с изменяемыми размерами — и обратно на холст в любой момент.

Source: https://docs.neurosquad.ai/ru/canvas/grid-mode

Холст хорош, чтобы собрать команду: карточки где угодно, стрелки, группы. А когда команда просто
*работает*, чаще нужно обратное — терминалы всех агентов сразу на экране, ровными рядами. Для этого
есть **режим сетки**.

Переключайтесь кнопкой **Холст / Сетка** в заголовке окна или клавишами `Ctrl` `Shift` `G`
(`⌘` `Shift` `G` на Mac). Каждый воркспейс помнит свой режим.

> Переключение ничего не перезапускает. Те же самые терминалы переезжают между холстом и сеткой —
> сессии продолжают работать, а на экране всё остаётся как было.

### Раскладки

Панель над сеткой выбирает раскладку:

| Раскладка | Что получится |
| --- | --- |
| Все плитки | Все агенты ровной сеткой по размеру окна |
| Одна плитка | Один агент на всю область |
| Две рядом | Два агента, слева и справа |
| 2 × 2 | Четыре агента |
| 3 × 2 | Шесть агентов |
| Главная и стопка | Один большой агент слева, до трёх стопкой справа |

Если мест в раскладке меньше, чем агентов, остальные ждут в полосе **Не на экране** под сеткой.
Нажмите на агента — он встанет на место плитки, с которой вы работали.

Плитки не становятся нечитаемо мелкими: если агентов много, а окно маленькое, сетка прокручивается,
а не сжимает их. Кнопка **добавления** на панели добавляет агента или карточку, не выходя из сетки
(в группе новая карточка попадает в эту группу).

### Расстановка плиток

- **Размер:** тяните тонкую линию между плитками. Двойной щелчок по линии выравнивает их обратно.
- **Выровнять:** делает все плитки текущей раскладки одного размера.
- **Поменять местами:** перетащите плитку за заголовок (можно и за имя) на другую плитку.
- **Развернуть:** кнопка разворота в заголовке плитки (или `Ctrl` `Alt` `Enter`)
отдаёт всю сетку одному агенту; нажмите ещё раз, чтобы вернуться.
- **Переход между плитками:** `Ctrl` `Alt` и стрелки — в терминал, куда вы попали,
можно сразу печатать.
- **Отмена:** `Ctrl` `Z` отменяет изменения раскладки сетки (вне терминала).

### Что с чем связано

Под каждой плиткой — ряд чипов с её [стрелками](https://docs.neurosquad.ai/ru/canvas/arrows): агенты, которыми она руководит или
которым подчиняется, и карточки, которыми пользуется, — заметка, браузер, MCP-сервер, навык, плагин.
Маленькая стрелка на чипе показывает направление.

- Наведите на плитку — подсветятся плитки, связанные с ней.
- Нажмите на чип другого агента — сетка перейдёт к его плитке.
- Нажмите на чип любой другой карточки — увидите, что это и с чем она связана, и кнопку
**Показать на холсте**.

Стрелки рисуются и удаляются на холсте; сетка их показывает.

### Фильтры

- **Только агенты** прячет терминалы, заметки, браузеры и все остальные карточки — остаются только
ИИ-агенты.
- **Карточки** показывает или прячет боковую полосу со всем, что не плитка: заметки, задачи, браузер,
карточки MCP и навыков. Наведите на карточку — увидите, с какими плитками она связана; полосу можно
свернуть до узкой ленты значков.
- Кнопка **Команда** открывает и закрывает панель «Команда» справа.

Сетка следует за боковой панелью: выберите группу — и увидите только её агентов.

---

## Группы

> Соберите связанные карточки в именованную цветную рамку и переходите к ней в один клик.

Source: https://docs.neurosquad.ai/ru/canvas/groups

**Группа** — это именованная цветная рамка на холсте. В неё удобно собрать команду агентов, фичу
или эксперимент.

- **Создать:** нажмите **New group** вверху холста (или кнопку с папкой рядом с воркспейсом в
сайдбаре), задайте имя и цвет рамки.
- **Добавить карточки:** перетащите карточку в рамку. Вытащите её обратно, чтобы убрать из группы.
- **Двигать вместе:** тяните рамку — всё внутри поедет вместе с ней.
- **Сфокусироваться:** щёлкните по группе в сайдбаре — холст приблизится к этой рамке.
- **Переименовать или удалить:** в окне правки группы. При удалении группы карточки остаются, просто
перестают быть в группе.

---

## Масштаб, перемещение и отмена

> Как ориентироваться на большом холсте, что показывают плитки-обзоры при отдалении и как отменить изменение раскладки.

Source: https://docs.neurosquad.ai/ru/canvas/moving-around

| Действие | Результат |
| --- | --- |
| тянуть пустой холст | перемещение |
| прокрутка над пустым холстом | масштаб |
| прокрутка над карточкой | прокрутка содержимого карточки |
| `Ctrl` + прокрутка над терминалом | текст крупнее или мельче |
| `Ctrl Z` / `Ctrl Shift Z` | отменить / повторить перемещение, изменение размера или расстановку карточек |

Кнопки в левом нижнем углу холста приближают и отдаляют, вписывают всё в экран и **расставляют всё**
аккуратной сеткой.

### Плитки-обзоры при отдалении

Отдалите холст посильнее — и каждая карточка превратится в крупную читаемую **плитку**: имя и самое
главное для этой карточки — состояние и маскот агента, прогресс списка задач, число задач в колонках
доски, доля потраченного бюджета, оставшееся время таймера. При этом ничего не останавливается:
агенты продолжают работать, а их плитки обновляются на лету. Приблизьте холст обратно — и полные
карточки окажутся ровно там, где были.

В **Settings → Canvas** есть переключатель **Card overview when zoomed out** и настройка **Switch to
the overview below** — масштаб, ниже которого карточки становятся плитками.

### Быстрый переход

- `Ctrl Shift P` — найти любого агента по имени в любом воркспейсе.
- `Ctrl Shift J` — перелететь к агенту, который ждёт вас дольше всех.
- Щелчок по уведомлению — холст перелетает к карточке, и она мигает зелёным.
- Щелчок по группе в сайдбаре — холст приближается к этой группе.

Про направляющие, привязку, миникарту и режим показа — в разделе [Инструменты холста](https://docs.neurosquad.ai/ru/canvas/tools).

---

## Инструменты холста

> Направляющие и привязка, миникарта, цветные метки, режим показа, маскоты, журнал стрелки и шаблоны воркспейсов.

Source: https://docs.neurosquad.ai/ru/canvas/tools

Почти всё это живёт в меню **инструментов холста** — кнопке с ползунками в правом верхнем углу
холста. Здесь же включаются и выключаются его параметры **View**:

Те же переключатели есть и в **Settings → Canvas**.

### Ровные ряды карточек

- **Направляющие** — пока вы тянете карточку, она притягивается к краям и центрам соседних карточек,
а линия-направляющая показывает совпадение.
- **Привязка к сетке** — карточки двигаются шагами точечной сетки, так что ряды и столбцы
выравниваются сами.

### Миникарта

Маленький обзор всего холста в углу. Тяните её или прокручивайте, чтобы перемещаться. По умолчанию
она выключена — включите **Minimap** в меню инструментов.

### Цветные метки

Щёлкните правой кнопкой по шапке любой карточки и выберите **Colour tag** — у карточки появится
цветной край (у агента есть ещё пункт **Color tag** в его меню ⋯). **Remove tag** убирает метку.

### К тому, кто ждёт

`Ctrl Shift J` переносит камеру к агенту, который ждёт вас дольше всех. Нажмите ещё раз —
к следующему.

### Показ холста

Нажмите `F5` (или **Present cards** в меню инструментов), чтобы пройти по карточкам одна за
другой, как по слайдам, — удобно, чтобы показать коллеге, что сделала ваша команда агентов.
Переходите кнопками или клавишами со стрелками, а **End presentation** завершает показ.
[Стикеры](https://docs.neurosquad.ai/ru/cards/sticky) хорошо подходят для титульных слайдов.

### Маскоты агентов

Крошечный робот на каждой карточке ИИ-агента сразу показывает, в каком он состоянии: **Working**,
**Waiting for you**, **Finished**, **Idle** или **Stopped**. Выключите **Agent mascots** в меню
инструментов, если хотите холст поспокойнее.

### Журнал стрелки

Щёлкните по стрелке, чтобы открыть её **Arrow log**: каждая команда, открытая страница, заметка или
переданная задача, прошедшая по ней, со временем. Журнал сохраняется между перезапусками. **Clear log**
очищает его. (Двойной щелчок по стрелке по-прежнему её удаляет.) Посмотреть, как это работает, можно
на странице [Стрелки дают возможности](https://docs.neurosquad.ai/ru/canvas/arrows).

### Шаблоны воркспейсов

Собрали удачную раскладку? **Save as template…** сохраняет её карточки, расположение, стрелки и
рамки — а также имена карточек, цветные метки и команды настройки воркспейса. Разговоры, история
терминалов, заметки и списки в шаблон не попадают.

Чтобы воспользоваться шаблоном, выберите **New workspace from template…**, дайте воркспейсу имя и
папку проекта — и вы получите ту же раскладку, готовую к работе.

#### Шаблон в уже существующий воркспейс

Шаблону не нужен отдельный воркспейс. **Вставить шаблон…** (в меню инструментов холста, а в меню
добавления карточки — пункт **Шаблон…** внизу) открывает шаблоны для этого воркспейса. Любой импорт,
начатый при открытом воркспейсе, — **Использовать шаблон** в маркетплейсе, файл, ссылка — тоже
начинается с **В существующий**, а **Новый воркспейс** — в одно нажатие.

- Папка воркспейса и место, где он работает (этот компьютер, WSL или SSH), не меняются, поэтому
диалог показывает только то, что может там работать; агенты, которые не могут, перечислены до
подтверждения.
- Новые карточки встают вместе рядом с тем, что уже есть на холсте, в раскладке самого шаблона — в
рамке с названием шаблона, если своей рамки у него нет. Ничего из прежнего не сдвигается, ни один
работающий агент не перезапускается.
- Карточки, которые воркспейсу нужны в одном экземпляре, — сквад, бюджет, Code Graph, RTK, а также
Память, caveman, Context7, MCP или навык с теми же настройками — переиспользуются: стрелки шаблона
ведут к вашей карточке, а не к её копии.
- Агент, которому нужен свой worktree, получит его, только если папка — git-репозиторий; иначе он
работает прямо в папке, и диалог об этом предупреждает.
- **Отменить** во всплывающем сообщении после вставки убирает ровно добавленные карточки и рамки.
Всё, что было установлено для шаблона, остаётся установленным.

---

## Поддерживаемые агенты

> Какие ИИ-агенты для кода умеет запускать NeuroSquad и что поддерживает каждый.

Source: https://docs.neurosquad.ai/ru/agents

**Карточка агента** запускает настоящего ИИ-агента для кода — ту же программу, что вы запустили бы в
терминале, с вашим собственным аккаунтом. NeuroSquad поддерживает девятнадцать таких агентов плюс обычные
терминалы.

  - **Claude Code**: Самая глубокая поддержка: точное различие «закончил» и «ждёт вашего ответа», индикатор контекста, журнал.
  - **Codex CLI**: Точно различает «закончил» и «ждёт вас» — с тем, о чём спрашивает; стрелки, режим карточек, продолжает с того же места, индикатор контекста, журнал, модели OpenRouter.
  - **Qwen Code**: Точно различает «закончил» и «ждёт вас» и говорит, что спрашивает; стрелки, режим карточек, продолжает с того же места, индикатор контекста, журнал, модели OpenRouter.
  - **Gemini CLI**: Точно различает «закончил» и «ждёт вас» и говорит, что спрашивает; стрелки (новые работают без перезапуска), режим карточек, навыки, продолжает с того же места, индикатор контекста, Compact, журнал, токены по карточке, модели OpenRouter через NeuroSquad.
  - **Kimi Code**: Точное различие «закончил» и «ждёт вашего ответа» с тем, о чём спрашивает, стрелки, режим карточек, навыки, продолжает с того же места, индикатор контекста, Compact, журнал, расход по карточке, модели OpenRouter.
  - **GitHub Copilot CLI**: Точно различает «закончил» и «ждёт вас» и говорит, что спрашивает; стрелки, режим карточек, навыки, продолжает с того же места, индикатор контекста, Compact, журнал, модели OpenRouter без подписки Copilot.
  - **Hermes Agent**: Точное различие «закончил» и «ждёт вашего ответа», стрелки, режим карточек, навыки, продолжает с того же места, индикатор контекста, журнал, модели OpenRouter.
  - **OpenCode**: Точное различие «закончил» и «ждёт вашего ответа», стрелки, режим карточек, продолжает с того же места; бесплатным моделям не нужен ключ.
  - **Kilo Code**: Точное различие «закончил» и «ждёт вашего ответа», стрелки, режим карточек, навыки, продолжает с того же места, индикатор контекста, журнал, модели OpenRouter.
  - **omp**: Точное различие «закончил» и «ждёт вашего ответа» с тем, о чём он спрашивает, стрелки, режим карточек, навыки, продолжает с того же места, индикатор контекста, журнал, модели OpenRouter.
  - **Pi**: Точное различие «закончил» и «ждёт вашего ответа», стрелки, режим карточек, навыки, продолжает с того же места, индикатор контекста, журнал, модели OpenRouter.
  - **aider**: Точное различие «закончил» и «ждёт вашего ответа» с тем, о чём спрашивает, стрелки и режим карточек через расширение NeuroSquad, навыки, продолжает с того же места, индикатор контекста, Compact, журнал, модели OpenRouter.
  - **Factory Droid**: Точное различие «закончил» и «ждёт вашего ответа» с тем, о чём спрашивает, стрелки, режим карточек, навыки, продолжает с того места, где остановился, индикатор контекста, Compact, журнал, модели OpenRouter без аккаунта Factory.
  - **Amp**: Точное различие «закончил» и «ждёт вашего ответа» через плагин NeuroSquad, стрелки, режим карточек, навыки, продолжает с того места, где остановился, индикатор контекста, журнал. Работает на вашем аккаунте Amp — модели обслуживает Amp, поэтому без OpenRouter и без расходов по карточке.
  - **Auggie**: Точное различие «закончил» и «ждёт вас» с командой, о которой он спрашивает, стрелки, режим карточек, навыки, продолжает с того места, где остановился, индикатор контекста, журнал, токены по карточке. Работает на вашем аккаунте Augment — модели обслуживает Augment, поэтому без OpenRouter.
  - **Cursor CLI**: «Закончил» и «ждёт вас» с командой, о которой он спрашивает, стрелки (инструменты приложения разрешены заранее), режим карточек, навыки, продолжает с того места, где остановился, индикатор контекста, Compact, журнал, передача дел. Работает на вашем аккаунте Cursor — модели предоставляет Cursor, поэтому OpenRouter и расхода по карточке нет.
  - **Goose**: Точное различие «закончил» и «ждёт вашего ответа» с тем, о чём спрашивает, стрелки, режим карточек, навыки, продолжает с того места, где остановился, индикатор контекста, Compact, журнал, расход по карточке, модели OpenRouter.
  - **Cline CLI**: Точное различие «закончил» и «ждёт вашего ответа» с тем, о чём спрашивает, через плагин NeuroSquad, стрелки, режим карточек, навыки, продолжает с того места, где остановился, индикатор контекста, Compact, журнал, расход по карточке, модели OpenRouter.
  - **Crush**: Точное различие «закончил» и «ждёт вашего ответа» с тем, о чём спрашивает, через его собственный канал статуса, стрелки, режим карточек, навыки, продолжает с того места, где остановился, индикатор контекста, Compact, журнал, расход по карточке, модели OpenRouter.

| Агент | Стрелки дают возможности | Продолжает с того же места | Опасный режим |
| --- | --- | --- | --- |
| **Claude Code** | Yes | Yes | Yes |
| **Codex CLI** | Yes | Yes | Yes |
| **Qwen Code** | Yes | Yes | Yes |
| **Gemini CLI** | Yes | Yes | Yes |
| **Kimi Code** | Yes | Yes | Yes |
| **GitHub Copilot CLI** | Yes | Yes | Yes |
| **Cursor CLI** | Yes | Yes | Yes |
| **OpenCode** | Yes | Yes | Yes |
| **Hermes Agent** | Yes | Yes | Yes |
| **Kilo Code** | Yes | Yes | Yes |
| **Pi** | Yes | Yes | No |
| **omp** | Yes | Yes | Yes |
| **Crush** | Yes | Yes | Yes |
| **aider** | Yes | Yes | Yes |
| **Factory Droid** | Yes | Yes | Yes |
| **Amp** | Yes | Yes | Yes |
| **Auggie** | Yes | Yes | Yes |
| **Goose** | Yes | Yes | Yes |
| **Cline CLI** | Yes | Yes | Yes |

  - **Стрелки дают возможности**: Агент может пользоваться подключёнными браузерами, терминалами, заметками и другими агентами и работать в [режиме карточек](https://docs.neurosquad.ai/ru/squads/canvas-mode). См. [Стрелки](https://docs.neurosquad.ai/ru/canvas/arrows).
  - **Продолжает с того же места**: После перезапуска NeuroSquad агент продолжает тот же разговор. Агенты без этой возможности каждый раз начинают разговор заново.
  - **Опасный режим**: Агент может не спрашивать разрешений. См. [Опасный режим](https://docs.neurosquad.ai/ru/agents/dangerous-mode).

Глубже всего поддерживаются **Claude Code**, **Codex CLI**, **Hermes Agent**, **OpenCode**, **Kilo Code** и **Qwen Code**: они точно сообщают
NeuroSquad, когда [ждут вашего ответа](https://docs.neurosquad.ai/ru/agents/notifications), и у них есть индикатор контекста,
Compact и журнал. Расход токенов Claude Code, Codex CLI, OpenCode, Kilo Code, Hermes Agent, Qwen Code, Pi и omp виден в
разделе [Расход и стоимость](https://docs.neurosquad.ai/ru/usage).

Claude Code, Codex CLI, OpenCode, Kilo Code, Qwen Code и Hermes Agent могут также работать на моделях из
[OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter) вместо вашего собственного входа.

**GitHub Copilot CLI** поддерживается так же глубоко: его собственные хуки сообщают NeuroSquad, когда он работает, закончил или ждёт вашего ответа — с командой, которую он хочет выполнить, или вопросом, который задаёт. Новые стрелки доходят до него без перезапуска, режим карточек держится и в опасном режиме, после перезапуска он продолжает тот же разговор, есть индикатор контекста, Compact, журнал и расход по карточке. Работает по вашей подписке Copilot — или вообще без подписки, на моделях OpenRouter.

**Pi** поддерживается так же глубоко — через небольшое расширение NeuroSquad, которое он загружает
при старте: сообщает, когда работает, закончил или ждёт вашего ответа, работает со стрелками и в
режиме карточек, у него есть индикатор контекста, Compact, журнал и модели OpenRouter. Pi никогда не
спрашивает разрешения перед запуском инструмента, поэтому опасный режим включать не нужно — он
уже так работает.

**omp** поддерживается так же глубоко: у него свой MCP-клиент, а небольшое расширение NeuroSquad,
которое он загружает при старте, сообщает, когда он работает, закончил или ждёт вашего ответа — и
какой инструмент хочет запустить или о чём спрашивает. Работает со стрелками и в режиме карточек
(он держится даже в опасном режиме), после перезапуска продолжает тот же разговор, у него есть
индикатор контекста, Compact, журнал и модели OpenRouter.

### Терминалы

Можно добавлять и обычные терминалы — оболочку вашей системы, Windows PowerShell, PowerShell 7,
Командную строку или Bash (Git Bash). См. [Карточка терминала](https://docs.neurosquad.ai/ru/cards/terminal).

> Не знаете, какие агенты у вас есть? **Settings → Harnesses** показывает, что NeuroSquad нашёл на
> компьютере, а **Settings → Setup** может установить агента за вас.

---

## Закончил / ждёт вашего ответа

> Как NeuroSquad сообщает, что агент закончил или ждёт вашего ответа.

Source: https://docs.neurosquad.ai/ru/agents/notifications

Следить за агентами не нужно. NeuroSquad сам даст знать, когда кто-то из них вас ждёт, — и различает
два случая:

### Два вида сигнала

  - **Done**: Агент завершил свой ход и ждёт следующего промпта. Плашка статуса становится зелёной.
  - **Needs input**: Агент остановился на полпути и что-то у вас спрашивает — обычно разрешение, например «можно запустить эту команду?». Плашка становится янтарной, карточка пульсирует. Уведомление показывает, о чём вопрос, и не исчезает, пока вы не ответите: заблокированный агент сам не разблокируется. Как только вы ответите, оно исчезнет само.

> Claude Code, OpenCode, Kilo Code и Hermes Agent точно сообщают NeuroSquad, какой из двух случаев сейчас. У других агентов NeuroSquad
> замечает, что агент затих, и считает, что он закончил.

### Как вы об этом узнаёте

- короткий **звуковой сигнал** (Chime, Ping или Marimba),
- карточка **подсвечивается**, а в сайдбаре рядом с агентом появляется точка,
- **уведомление на рабочем столе** — щёлкните по нему, и холст сам перелетит к нужной карточке,
- **колокольчик уведомлений** в верхней панели хранит список событий,
- по желанию — сообщение в **Slack или Discord** через вебхук,
- по желанию — сообщение в [Telegram](https://docs.neurosquad.ai/ru/integrations/telegram) — на случай, когда вас нет за
компьютером.

Каждый способ включается и выключается в **Settings → Notifications**.

### Как быстро наверстать

- `Ctrl Shift J` — перелететь к агенту, который ждёт дольше всех.
- `Ctrl Shift A` — входящие «требует внимания»: все ждущие агенты одним списком.
- Раздел **Inbox** в сайдбаре показывает тот же список.

Нужна тишина? [Таймер фокуса](https://docs.neurosquad.ai/ru/cards/flow-timer) придержит сигналы «закончил», пока не кончится ваш
блок фокуса.

### О чём приходят уведомления

В **Настройки → Уведомления** у каждого вида свой переключатель: агент **ждёт вас** (с тем, о чём
спрашивает), агент **закончил**, упёрся в **лимит использования**, и **обновление CLI агента,
которое NeuroSquad пропустил**, чтобы агенты продолжали работать (когда обновлять — решаете вы).

**Отправить тестовое уведомление** покажет его сразу. Если система уведомления не показывает —
например, в Windows они выключены для всех приложений (Параметры → Система → Уведомления), —
NeuroSquad скажет об этом там же и будет показывать их в правом нижнем углу своего окна;
**Системные настройки уведомлений** открывают нужное место, чтобы их включить. Их также может
придерживать режим «Не беспокоить» / фокусировка внимания Windows.

### Обновления CLI агентов не прерывают работу

Некоторые CLI агентов обновляются сами при запуске, а некоторые сначала спрашивают («Обновить сейчас /
Пропустить») — и карточка встаёт: ни вы, ни ведущий агент не можете в неё писать. В карточках
NeuroSquad это выключено (только в них — CLI в вашем собственном терминале сохраняет свои настройки),
а вопрос, появившийся всё-таки, получает ответ **«Пропустить»**. Когда выходит новая версия,
NeuroSquad сообщает об этом один раз на версию — с командой для обновления из терминала; когда
обновлять, решаете вы.

---

## Как давать агентам задачи

> Назначайте задачи с доски конкретным агентам и позвольте им самим брать следующую задачу.

Source: https://docs.neurosquad.ai/ru/agents/tasks

Всегда можно просто написать агенту промпт. Но для большой работы с несколькими агентами лучше
подходит [доска задач](https://docs.neurosquad.ai/ru/cards/kanban): у каждой задачи один исполнитель, и **Start** отправляет её
только ему:

**1. Разложите задачи на доске**

Добавьте доску задач и впишите по одной задаче в строку — или попросите ведущего агента разбить
работу на задачи прямо на доске.

**2. Назначьте каждую задачу**

Нажмите **Assign** у задачи и выберите агента. Задачу получит только он, а другие агенты не смогут
её взять или передвинуть. **New agent for this task** в один клик создаёт под неё нового агента.

**3. Нажмите Start**

Задача уходит своему агенту промптом и переезжает в **Doing**. Когда агент закончит, перенесите её
в **Review** или **Done**.

### Пусть работает само

- **Depends on** — задача ждёт в статусе **Blocked**, пока задачи, от которых она зависит, не станут
**Done**.
- **Auto-dispatch** (кнопка с молнией в шапке доски) — когда агент заканчивает ход, его задача
переезжает в **Review**, а следующая готовая задача отправляется ему автоматически.
- **Give unassigned tasks to any idle connected agent** — неназначенные задачи достаются любому
свободному агенту.

Поставьте рядом с самостоятельно работающей доской [карточку бюджета](https://docs.neurosquad.ai/ru/cards/budget), чтобы в ваше
отсутствие ничего не было потрачено сверх меры.

### Все задачи в одном месте

Раздел **Tasks** в сайдбаре собирает задачи со всех досок и списков задач во всех ваших воркспейсах.

---

## Очередь промптов и ежедневные промпты

> Выстройте следующие промпты для занятого агента или отправляйте один и тот же промпт каждый день.

Source: https://docs.neurosquad.ai/ru/agents/queue

### Очередь промптов

Уже придумали следующую задачу, а агент всё ещё занят? Поставьте её в очередь.

**1. Откройте Queue в меню ⋯ карточки агента**

Напишите сообщение и нажмите **Add to queue**. Добавляйте сколько угодно, меняйте порядок
стрелками, щёлкните по сообщению, чтобы его отредактировать.

**2. Занимайтесь своими делами**

Как только агент закончит ход, следующее сообщение отправится автоматически — по одному за ход.

Очередь переживает закрытие воркспейса и приложения. Если агент не запущен, сообщения просто ждут.

### Ежедневные промпты

**Schedule** в меню ⋯ карточки агента каждый день в заданное время отправляет этому агенту промпт —
например, «каждое утро в 9 проверяй новые issue». У каждого запланированного промпта свой
переключатель.

---

## Роли

> Дайте агенту должностную инструкцию — ревьюер, тестировщик, исследователь и другие — в один клик.

Source: https://docs.neurosquad.ai/ru/agents/roles

**Роль** говорит агенту, для какой работы он здесь. В NeuroSquad есть готовые роли — **Reviewer**,
**Tester**, **Researcher**, **Architect**, **Writer** — и **Custom**, где роль можно описать своими
словами.

### Как дать роль

- **При создании агента** — выберите роль в диалоге **New agent**. Она вставляется в нового агента
первым промптом; чтобы отправить её, нажмите Enter в его терминале.
- **Уже запущенному агенту** — выберите **Role** в его меню ⋯, выберите роль и нажмите **Send role**.

Роль отправляется один раз, обычным промптом, который вы видите. NeuroSquad никогда не меняет и не
отправляет её повторно у вас за спиной. Карточка показывает роль рядом с именем агента.

**Подходит для:** команды агентов, где у каждого своя чёткая работа — один пишет код, другой его
тестирует, третий проверяет.

---

## Долгие сессии

> Следите за контекстом, сжимайте его, продолжайте после лимита, передавайте работу свежему агенту и ведите журнал.

Source: https://docs.neurosquad.ai/ru/agents/long-sessions

Агенты, которые работают часами, упираются в пределы: их память (**контекст**) заполняется, а
**лимит использования** вашего тарифа заканчивается. NeuroSquad помогает и с тем, и с другим.

### Индикатор контекста и Compact

Маленькое кольцо в шапке карточки агента показывает, насколько заполнен контекст. После 80% оно
становится янтарным. Щёлкните по нему — увидите разбивку по токенам и сможете:

- **Compact** — попросить агента пересказать разговор и продолжить уже с этого пересказа.
- Или **передать работу** свежему агенту (см. ниже).

### Продолжение после лимита

Когда агент останавливается с сообщением «usage limit reached», в его шапке появляется обратный
отсчёт до сброса лимита. Включите **Auto-resume after a usage limit** (во всплывающем окне этой
плашки или в меню ⋯ карточки) — и NeuroSquad в нужный момент сам отправит агенту «continue». Так
ночная работа продолжится без вас. Там же — **Resume now** и **Dismiss**.

### Передача работы новому агенту

**Hand off to a new agent…** в меню ⋯ запускает свежего агента рядом с этим, в той же папке, на любой
программе-агенте на ваш выбор. Он получает сводку проделанной работы — нажмите **Ask the agent to
write it** или напишите и отредактируйте её сами. Сводка вставляется в нового агента, но не
отправляется, так что её можно проверить, прежде чем нажать Enter.

### Журнал

Включите **Journal to linked note** в меню ⋯ — и каждый законченный ответ будет добавляться в
подключённую [карточку-заметку](https://docs.neurosquad.ai/ru/cards/note). Получается живой журнал того, что сделал агент.

> Индикатор контекста, Compact и журнал работают с Claude Code, OpenCode, Kilo Code и Hermes Agent.

---

## Один файл инструкций

> Напишите инструкции проекта один раз в AGENTS.md — и их прочитает каждый агент.

Source: https://docs.neurosquad.ai/ru/agents/instructions

Программы-агенты читают инструкции проекта из разных файлов: Codex и многие другие — из `AGENTS.md`,
Claude Code — из `CLAUDE.md`, Qwen Code — из `QWEN.md`, Gemini — из `GEMINI.md`. Держать их все в
согласии вручную утомительно.

NeuroSquad позволяет вести **один** файл — `AGENTS.md` — и зеркалит его в `CLAUDE.md`, `GEMINI.md` и
`QWEN.md`.

**1. Откройте диалог редактирования воркспейса**

В разделе **Instructions file** перечислены все файлы с их состоянием: **Missing** (нет),
**In sync** (совпадает) или **Differs** (отличается).

**2. Отметьте файлы для зеркалирования**

Выберите **Copy** (полная копия) или **@import** (короткий файл, который ссылается на
`AGENTS.md`) и нажмите **Write**.

Если в файле уже другое содержимое, NeuroSquad никогда не перезапишет его молча: **Review…** покажет,
что именно изменится, и заменит файл только **Overwrite**.

`AGENTS.md` ещё нет? **Create AGENTS.md from** создаст его из существующего файла, например из
вашего `CLAUDE.md`.

---

## Изолированные worktree

> Дайте агенту собственную копию проекта, чтобы агенты не затирали изменения друг друга, — и добавьте ревьюера на другом ИИ.

Source: https://docs.neurosquad.ai/ru/agents/worktrees

Когда несколько агентов работают в одной папке, они могут перезаписать изменения друг друга.
**Изолированный** агент получает собственную копию проекта (git worktree) на своей ветке и может
менять что угодно, не мешая ни вам, ни другим агентам.

### Как включить

В строке добавления под воркспейсом в сайдбаре включите **Isolate in git worktree** (кнопка со
стопкой квадратов), прежде чем добавить агента. Пока копия готовится, на карточке написано
**Preparing**, затем агент запускается.

> Проект должен быть git-репозиторием. Если Git у вас нет, его может установить мастер установки.

### Автоматическая подготовка копии

В свежей копии нет установленных зависимостей и ваших личных файлов. В диалоге редактирования
воркспейса можно задать:

- **Setup command for isolated agents** — выполняется один раз в каждой новой копии перед запуском
агента, например `npm install`. Пока она идёт, её вывод виден в карточке.
- **Files to copy into a new worktree** — файлы, которые git не отслеживает, но которые нужны агенту,
например `.env`.
- **Run command** — запускает проект из карточки агента (**Run this project** в её меню ⋯); как только
приложение напечатает свой локальный адрес, откроется карточка браузера с ним.

### Как добавить ревьюера

Когда работа выглядит законченной, выберите **Add a reviewer** в меню ⋯ агента. Запустится второй
агент — на **другом ИИ**, если такой у вас установлен, — в том же worktree, со стрелкой от автора, и
получит указание прочитать изменения и **ничего не редактировать**.

### Как забрать работу

Изменения агента живут на его собственной ветке. Когда они вас устраивают, слейте эту ветку из
[карточки терминала](https://docs.neurosquad.ai/ru/cards/terminal) — или просто попросите агента закоммитить и слить свою работу.

---

## Опасный режим

> Как дать агенту работать, не останавливаясь за разрешениями, — и когда этого делать не стоит.

Source: https://docs.neurosquad.ai/ru/agents/dangerous-mode

Обычно агент спрашивает, прежде чем сделать что-то рискованное, — запустить команду, изменить файл.
**Опасный режим** отключает эти вопросы, и агент работает без остановок.

### Как включить

Откройте меню ⋯ карточки агента и выберите **Enable dangerous mode**. В шапке карточки появится
янтарный треугольник. Настройка действует на одну карточку — никогда на всех агентов сразу.
Выключается там же — **Disable dangerous mode**.

- **Claude Code** переключается сразу, в обе стороны: уже следующее разрешение следует переключателю —
без перезапуска, в том же разговоре.
- **Остальные агенты** читают режим при запуске. NeuroSquad предложит **Перезапустить**: агент
перезапустится и продолжит тот же разговор. **Позже** — режим применится при следующем запуске.

> В опасном режиме агент может удалять файлы и запускать любые команды, ничего не спрашивая.
> Включайте его только в проекте, у которого есть резервная копия, — а лучше вместе с
> [изолированным worktree](https://docs.neurosquad.ai/ru/agents/worktrees) и [бюджетом](https://docs.neurosquad.ai/ru/cards/budget).

У Pi этого режима нет — он и так ничего не спрашивает перед запуском инструментов. Обычным терминалам он тоже не нужен.

---

## Всё о карточке агента

> Шапка карточки агента и её меню ⋯ — строка за строкой.

Source: https://docs.neurosquad.ai/ru/agents/card-menu

Шапка показывает то, что нужно видеть с другого конца холста: кто это, чем он занят и какие
постоянные настройки меняют его поведение. Всё, что вы *делаете* с агентом, живёт в меню **⋯**.
Наведите курсор на точки, а потом откройте меню:

### Шапка

  - **Иконка**: Собственная иконка агента; пока он работает, вокруг неё крутится кольцо.
  - **Имя**: Заполняется по тому, над чем работает агент. Щёлкните по нему и впишите своё — ваше имя всегда главнее.
  - **Роль или заголовок сессии**: Мелкий текст после имени: [роль](https://docs.neurosquad.ai/ru/agents/roles) агента или то, чем он сейчас занят.
  - **Статус**: **Working**, **Needs input**, **Done**, **Exited**, **Crashed**… Пока агент простаивает, статуса нет вовсе. См. [Закончил / ждёт вашего ответа](https://docs.neurosquad.ai/ru/agents/notifications).
  - **Лимит и контекст**: Обратный отсчёт, если агента остановил лимит использования, и индикатор контекста. См. [Долгие сессии](https://docs.neurosquad.ai/ru/agents/long-sessions).
  - **Модель**: Плашка с моделью, если агент работает на выбранной вами модели. См. [OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter).
  - **Отметки**: Янтарный треугольник — [опасный режим](https://docs.neurosquad.ai/ru/agents/dangerous-mode), зелёная рамка — [режим карточек](https://docs.neurosquad.ai/ru/squads/canvas-mode).
  - **Развернуть и ⋯**: Развернуть карточку на весь холст; открыть меню.

У ИИ-агентов сверху на карточке сидит маленький [маскот](https://docs.neurosquad.ai/ru/canvas/tools#agent-mascots) — он повторяет
состояние агента.

### Меню ⋯

  - **Сессия**: **Restart session** (совершенно новый разговор; карточка остаётся на месте), **Pop out to new window**, **Minimize** и **Run this project**, если у воркспейса задана команда запуска (см. [Изолированные worktree](https://docs.neurosquad.ai/ru/agents/worktrees)).
  - **Агент**: **Provider and model**, **Enable dangerous mode**, **Enable canvas mode**, **Role**, **Journal to linked note**, **Auto-resume after a usage limit**, **Hand off to a new agent…**, **Clone agent** и **Add a reviewer**.
  - **Промпты**: **Queue** и **Schedule** — см. [Очередь промптов и ежедневные промпты](https://docs.neurosquad.ai/ru/agents/queue).
  - **Порядок**: **Color tag** (цветная метка), личные **Notes** (их можно надиктовать), **Issue/PR link** и **Annotations** — пометки, закреплённые в нужных местах вывода.
  - **Транскрипт**: **Copy transcript**, **Export transcript**, **Export as HTML**, **Open last mentioned file**, **Save snapshot** и ваши **Snapshots**.
  - **Удалить агента**: Последняя строка, отдельно от остальных. Сначала спрашивает — и никогда не трогает ваши файлы.

### В терминале

- Правый клик — **Copy**, **Paste** и **Select all**.
- `Ctrl F` — поиск по выводу.
- `Ctrl` + колесо мыши — размер текста.
- Перетащите файлы из Проводника (на Mac — из Finder) на карточку — их пути впишутся в промпт.

### Если агент упал

NeuroSquad несколько раз перезапускает его сам (**Auto-reconnect** в Settings → General). Если агент
так и не поднялся, на карточке появится кнопка **Reconnect**, а **Crash log** в разделе **Features**
сайдбара запишет, что случилось.

### Шаблоны

Настройте агента, которым пользуетесь часто, — тип агента, цвет, стартовый промпт — и сохраните его
как **шаблон** (**Features → Templates** в сайдбаре). Ваши шаблоны появятся внизу меню добавления.

---

## Все карточки

> Все виды карточек, которые можно поставить на холст, и для чего нужна каждая.

Source: https://docs.neurosquad.ai/ru/cards

Помимо агентов, на холсте могут жить и многие другие карточки. Любую из них можно добавить из меню
добавления. Большинство становятся ещё полезнее, когда вы подключаете к ним агента
[стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows). Вот как выглядит каждая из них, если отдалить холст:

### Работа

  - **[Терминал](https://docs.neurosquad.ai/ru/cards/terminal)**: Настоящая оболочка — для вас или для команд агента.
  - **[Браузер](https://docs.neurosquad.ai/ru/cards/browser)**: Настоящий браузер, который агент видит и в котором кликает.
  - **[Заметка](https://docs.neurosquad.ai/ru/cards/note)**: Общие заметки в Markdown — для вас и ваших агентов.
  - **[Список задач](https://docs.neurosquad.ai/ru/cards/todo)**: Чек-лист, который вы и агенты отмечаете вместе.
  - **[Доска задач](https://docs.neurosquad.ai/ru/cards/kanban)**: Назначайте задачи агентам — и они сами берут следующую.
  - **[Стикер](https://docs.neurosquad.ai/ru/cards/sticky)**: Крупные заголовки, чтобы упорядочить холст.
  - **[Таймер фокуса](https://docs.neurosquad.ai/ru/cards/flow-timer)**: Блоки фокуса, которые придерживают несрочные сигналы.
  - **[Справочник](https://docs.neurosquad.ai/ru/cards/reference)**: Ссылки, картинки, PDF и папки для ваших агентов.
  - **[Дев-серверы](https://docs.neurosquad.ai/ru/cards/dev-servers)**: Запущенные дев-серверы — в один клик до карточки браузера.

### Присмотр

  - **[Бюджет](https://docs.neurosquad.ai/ru/cards/budget)**: Лимит токенов на весь воркспейс.
  - **[Слежение за страницей](https://docs.neurosquad.ai/ru/cards/web-watch)**: Сообщает агентам, когда страница изменилась.
  - **[Стендап](https://docs.neurosquad.ai/ru/cards/standup)**: Что каждый агент сделал сегодня.

### Интеграции

  - **[Telegram-бот](https://docs.neurosquad.ai/ru/integrations/telegram)**: Общайтесь с агентами из Telegram.

---

## Карточка терминала

> Настоящая оболочка на холсте — для вас или для команд агента.

Source: https://docs.neurosquad.ai/ru/cards/terminal

**Карточка терминала** — это обычная оболочка в папке проекта: Windows PowerShell, PowerShell 7,
Командная строка, Bash (Git Bash) или оболочка вашей системы по умолчанию. Выберите её в разделе
**Terminals** меню добавления.

### Пользуйтесь сами

Вводите команды, как в любом терминале. Правый клик — Copy / Paste / Select all, `Ctrl F` —
поиск, `Ctrl` + прокрутка — размер текста.

### Дайте агенту

Проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к терминалу. Агент будет запускать команды **здесь**,
у вас на виду, а не где-то внутри своего окна. Всему долгоиграющему — дев-серверу, тестам в режиме
наблюдения — лучше дать по своей карточке терминала.

**Подходит для:** запуска приложения, прогона тестов, наблюдения за логами, пока агент работает.

---

## Карточка браузера

> Настоящий браузер на холсте, который агент видит и которым пользуется.

Source: https://docs.neurosquad.ai/ru/cards/browser

**Карточка браузера** — настоящий браузер внутри карточки: с кнопками «назад», «вперёд», «обновить»
и адресной строкой. Можно ходить по сайтам самому — а агент, подключённый [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows),
может открывать страницы, кликать, вводить текст и читать, что на экране.

> В первый раз NeuroSquad скачивает собственный браузер (по умолчанию Chrome, около 200 МБ). Он
> хранится отдельно от вашего обычного браузера. Карточка запустится сама, когда загрузка закончится.
> Переключиться на Firefox можно в **Settings → Browser**.

Входы на сайты, сделанные в карточке браузера, запоминаются: войдите один раз, и дальше агент сможет
там работать.

**Подходит для:** проверки приложения, которое агент только что изменил, воспроизведения бага,
заполнения веб-форм, поиска информации.

---

## Карточка заметки

> Общая заметка в Markdown — для вас и ваших агентов.

Source: https://docs.neurosquad.ai/ru/cards/note

**Карточка заметки** хранит текст в Markdown: заголовки, списки, таблицы, код. Пустая заметка
открывается для правки, заполненная показывает отформатированный текст — щёлкните, чтобы править,
`Esc` — чтобы закончить.

Подключите агента [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows) — и он тоже сможет читать и писать заметку. Карточка
показывает, кто написал последнюю версию.

**Подходит для:** журнала находок, который агент ведёт по ходу работы, инструкций, общих для
нескольких агентов, черновика для текущей задачи.

---

## Карточка списка задач

> Чек-лист, который вы и ваши агенты поддерживаете в актуальном состоянии вместе.

Source: https://docs.neurosquad.ai/ru/cards/todo

**Список задач**, общий для вас и ваших агентов. У каждой задачи есть точка статуса:

| Точка | Значение |
| --- | --- |
| серое кольцо | не начата |
| крутящееся кольцо | в работе |
| зелёная точка | готово |
| красная точка | не получилось |

- **Добавляйте** задачу в строке внизу.
- **Щёлкните по точке**, чтобы перевести задачу в следующий статус.
- **Щёлкните по тексту**, чтобы его изменить.

Подключите агента [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows) — он запишет сюда свой план и будет отмечать задачи по
ходу работы, так что прогресс виден с первого взгляда. Списков может быть сколько угодно.

---

## Карточка доски задач

> Канбан-доска для команды агентов — назначьте каждую задачу агенту, и следующая начнётся сама.

Source: https://docs.neurosquad.ai/ru/cards/kanban

У **доски задач** четыре колонки: **To do**, **Doing**, **Review** и **Done**. Добавляйте задачи и
переносите их между колонками сами — или доверьте это агентам.

### Задача для конкретного агента

- **Assign** — выберите агента, который должен сделать задачу. Получит её только он; другие агенты
не могут её двигать или удалять.
- **Start** — отправляет задачу её агенту и переносит в **Doing**.
- **New agent for this task** (в том же списке) — один клик создаёт под задачу свежего агента.

### Задачи, которые зависят от других

**Depends on** позволяет отметить задачи, которые сначала должны оказаться в **Done**. До тех пор
задача помечена как **Blocked** и показывает, чего ждёт.

### Автораздача

Включите **Auto-dispatch** (кнопка с молнией в шапке доски) — и доска работает сама: когда агент
заканчивает ход, его задача переходит в **Review**, а следующая готовая задача автоматически
отправляется ему. С опцией **Give unassigned tasks to any idle connected agent** свободные задачи
достаются тому подключённому агенту, который сейчас не занят.

Агенты, подключённые [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows), тоже могут добавлять задачи и двигать свои дальше.
Вся картина — в разделе [Задачи для агентов](https://docs.neurosquad.ai/ru/agents/tasks).

**Подходит для:** команды агентов, разбирающей бэклог, когда нужно с первого взгляда видеть, кто чем
занят.

---

## Карточка-стикер

> Крупные заголовки и подписи, чтобы упорядочить и пояснить холст.

Source: https://docs.neurosquad.ai/ru/cards/sticky

**Стикер** — крупная жирная подпись: заголовок и необязательный подзаголовок, одного из шести цветов.
Дважды щёлкните по нему, чтобы написать текст.

Стикерами удобно делить большой холст на главы — «Сборка», «Маркетинг», «Присмотр» — или оставить
записку тому, кто откроет воркспейс следующим. Особенно хорошо они смотрятся в
[режиме показа](https://docs.neurosquad.ai/ru/canvas/tools#present-your-canvas).

---

## Карточка таймера фокуса

> Таймер фокуса, который придерживает сигналы «закончил» от агентов до конца блока.

Source: https://docs.neurosquad.ai/ru/cards/flow-timer

Когда агенты заканчивают один за другим, сосредоточиться трудно. **Таймер фокуса** даёт вам блок
сосредоточенной работы — **25 / 5**, **50 / 10** или свои минуты — и приглушает шум, пока он идёт.

- Нажмите **Start focus**. Карточка показывает, сколько осталось и когда блок закончится.
- Если включено **Hold agent pings while focusing**, уведомления «закончил» ждут конца блока.
«Ждёт вашего ответа» приходит всегда — заблокированный агент не должен ждать вас по случайности.
- Когда блок закончится, **While you focused** одним списком покажет, что произошло.

Ещё карточка считает, сколько блоков фокуса вы сделали сегодня.

---

## Карточка-справочник

> Ссылки, картинки, PDF и папки, которые ваши агенты должны держать в голове.

Source: https://docs.neurosquad.ai/ru/cards/reference

**Справочник** — это доска с материалами для ваших агентов: веб-ссылки, картинки, PDF, документы или
целая папка.

- **Add a link** — вставьте ссылку и нажмите Enter.
- **Add files** или перетащите файлы на карточку; **Reference a folder** — чтобы сослаться на папку,
а не копировать её.
- Щёлкните по элементу, чтобы его открыть (**Open**).

Каждый агент, подключённый [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows), видит, что лежит в карточке, и читает это,
когда нужно, — не придётся вставлять одни и те же макеты или спецификации в каждый промпт.

**Подходит для:** макетов дизайна, спецификации продукта, гайдлайнов бренда, документации API.

---

## Карточка дев-серверов

> Все дев-серверы, запущенные на компьютере, — любой открывается в карточке браузера одним щелчком.

Source: https://docs.neurosquad.ai/ru/cards/dev-servers

Агенты обожают запускать дев-серверы — а потом приходится гадать, на каком порту. **Карточка
дев-серверов** показывает все, что запущены на вашем компьютере, и обновляется каждые несколько
секунд.

- **Open in a browser card** — один щелчок, и [карточка браузера](https://docs.neurosquad.ai/ru/cards/browser) откроется на этом
адресе.
- **Copy URL** или **Stop process**, когда сервер больше не нужен. (Системные процессы и сам
NeuroSquad отсюда остановить нельзя.)
- **Show every listening port** — если хотите видеть не только дев-серверы.

Подключённые агенты тоже могут спросить у карточки, какие серверы запущены.

**Подходит для:** чтобы не терять из виду, что запущено, пока несколько агентов работают над
веб-проектом.

---

## Карточка бюджета

> Лимит токенов на весь воркспейс, который ставит агентов на паузу при превышении.

Source: https://docs.neurosquad.ai/ru/cards/budget

**Карточка бюджета** показывает, сколько токенов потратили все агенты этого воркспейса, с разбивкой
по агентам, — относительно заданного вами лимита.

- **Set limit** — выберите лимит токенов (250K, 1M, 5M, 20M или свой). Когда вы к нему
приближаетесь, кольцо становится янтарным — **Near limit**.
- **Когда лимит превышен**, воркспейс встаёт на паузу: каждый агент прерывается (но не закрывается —
его разговор сохраняется), а автоматические промпты — очередь, ежедневные промпты, задачи с доски,
сообщения от других агентов — останавливаются.
- **Печатать самому по-прежнему можно** — бюджет останавливает только автоматику.
- **Чтобы продолжить**, нажмите **Resume** или **Raise limit** выше уже потраченного.

Токены берутся оттуда же, откуда и в разделе [Расход и стоимость](https://docs.neurosquad.ai/ru/usage), поэтому учитывается каждый
агент, чей расход NeuroSquad умеет читать.

**Подходит для:** чтобы оставить команду агентов работать на ночь без неожиданного счёта.

---

## Карточка слежения за страницей

> Следит за веб-страницей и сообщает агентам, когда она меняется.

Source: https://docs.neurosquad.ai/ru/cards/web-watch

**Карточка слежения за страницей** проверяет страницу по расписанию и замечает, когда она меняется, —
список изменений, цену, страницу статуса, тарифы конкурента.

**1. Укажите страницу**

Вставьте адрес и выберите, как часто проверять.

**2. Выберите, что сравнивать**

**Whole page** (всю страницу), только часть между двумя фразами — **Between** (например, между
«Latest release» и «Older releases») или совпадения с шаблоном.

**3. Начните слежение**

Первая проверка — точка отсчёта. Дальше каждое изменение записывается вместе с тем, что
добавилось и что пропало.

Если включено **Tell connected agents when it changes**, каждый агент, подключённый
[стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows), получает сообщение об изменении — и может отреагировать сам: например,
обновить документацию под новую версию библиотеки или написать вам краткую сводку.

**Check now**, **Pause** и **Resume** всегда под рукой. Карточка читает страницу в том виде, в каком
её отдаёт сервер, поэтому текст, который скрипты дорисовывают на странице позже, она не видит.

---

## Карточка стендапа

> Ежедневная сводка того, что сделал сегодня каждый агент воркспейса.

Source: https://docs.neurosquad.ai/ru/cards/standup

**Карточка стендапа** отвечает на вопрос «кто что сегодня сделал?». Для каждого агента воркспейса она
показывает:

- сколько ходов он сделал и сколько времени работал,
- какие файлы трогал и сколько токенов потратил,
- о чём его спросили последним и что он последним ответил.

**Copy as Markdown** — чтобы вставить сводку в чат, или **Send to note** — чтобы положить её в
подключённую [карточку заметки](https://docs.neurosquad.ai/ru/cards/note).

Агенты Claude Code, OpenCode, Kilo Code и Hermes Agent учитываются полностью. Для остальных агентов карточка показывает, что произошло с
момента запуска NeuroSquad.

---

## Что такое команда агентов

> Несколько агентов работают вместе на одном холсте, соединённые стрелками.

Source: https://docs.neurosquad.ai/ru/squads

**Команда агентов** — это группа агентов, работающих вместе. Один агент может вести и раздавать
работу, остальные делают её по частям, а браузеры, терминалы и заметки связывают их всех. Команда
собирается просто: добавьте карточки и проведите [стрелки](https://docs.neurosquad.ai/ru/canvas/arrows). Помощники не обязаны
работать на том же ИИ, что и ведущий:

Разделить работу можно двумя способами — пусть ведущий агент делегирует её по стрелкам, или
разложите задачи на [доске задач](https://docs.neurosquad.ai/ru/cards/kanban) и отдайте каждую конкретному агенту:

  - **[Ведущий агент, который делегирует](https://docs.neurosquad.ai/ru/squads/lead-agent)**: Один агент раздаёт задачи другим и собирает результаты.
  - **[Задачи для конкретных агентов](https://docs.neurosquad.ai/ru/agents/tasks)**: Assign, Start, зависимости и авто-раздача на доске задач.
  - **[Режим карточек](https://docs.neurosquad.ai/ru/squads/canvas-mode)**: Агент сам создаёт нужные ему карточки.
  - **[Рецепты команд](https://docs.neurosquad.ai/ru/squads/recipes)**: Готовые схемы, которые можно повторить.

### Доска «Команда»

В каждом воркспейсе есть карточка **«Команда»**: все его ИИ-агенты на одной доске — кто ждёт вас, кто
работает и сколько, кто закончил, — с типом агента и моделью у каждого. Щёлкните строку, и камера
перелетит к этому агенту.

Кнопка **«Команда»** в верхней панели открывает ту же доску **правой боковой панелью** — для открытого
воркспейса; она остаётся на месте при переключении воркспейсов, даже если карточку вы удалили. Ширину
меняют, перетаскивая край. Пока доска в панели, карточка на холсте только сообщает об этом (дважды
доска не показывается); **«Вернуть на холст»** возвращает её — и саму карточку, если вы её удаляли.

---

## Ведущий агент, который делегирует

> Пусть один агент раздаёт задачи другим агентам и собирает их ответы.

Source: https://docs.neurosquad.ai/ru/squads/lead-agent

Проведите стрелку **от** одного агента **к** другому. Первый становится **ведущим**, второй — его
**помощником**. Теперь ведущий может отправить помощнику задачу, дождаться, пока тот закончит, и
прочитать ответ.

**1. Добавьте двух агентов**

Например, Claude Code в роли ведущего и Codex в роли помощника. Это могут быть разные ИИ.

**2. Проведите стрелку от ведущего к помощнику**

Направление важно: стрелка идёт от того, кто даёт работу, к тому, кто её делает.

**3. Скажите ведущему, чего вы хотите**

*«Исправь баг в оформлении заказа. Пока чинишь, попроси помощника написать для него тесты».*
Стрелка загорается каждый раз, когда ведущий обращается к помощнику, а за работой помощника можно
следить в его собственной карточке.

У ведущего может быть несколько помощников, а помощник может сам вести своих помощников.

> Ведущим должен быть Claude Code, OpenCode, Kilo Code, Hermes Agent, Codex CLI или Qwen Code — агенты, которым [стрелки дают
> возможности](https://docs.neurosquad.ai/ru/canvas/arrows). Помощником может быть любой агент.

### Пусть ведущий соберёт команду сам

Ведущий может и сам создавать помощников — и выбирать, на чём работает каждый. Попросите его,
например: *«Спланируй проект на команду из четырёх разработчиков: выбери для каждого харнесс и
модель и создай их»*. Ведущий:

- видит, какие агенты **установлены на этом компьютере** — создать тот, которого у вас нет, он не
сможет;
- видит **собственные модели** каждого агента (например, `opus` или `sonnet` у Claude Code) и, если
вы подключили [OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter), — что можно брать модели OpenRouter, с ценами и
размером контекста; ваш ключ он не видит;
- создаёт каждого помощника с харнессом, моделью, ролью и первой задачей — сразу со стрелкой к себе.

Модель помощника видна на его карточке и на доске «Команда». Ведущий может сменить модель
созданного им помощника, пока тот не запущен.

### Дайте помощникам нужные карточки

Помощник видит только карточки, подключённые к **его собственной** карточке, — не к ведущему. Поэтому,
раздавая работу, которой нужна карточка (заметка с заданием, терминал, браузер, доска задач), ведущий
сам подключает к ней помощника: может создать помощника уже со стрелкой к вашей заметке или провести
стрелку от работающего помощника посреди задачи. Новая стрелка появляется на холсте, на мгновение
показывает, кто её провёл, и остаётся в [журнале стрелки](https://docs.neurosquad.ai/ru/canvas/arrows#arrow-log). Уже запущенный помощник
получает новые возможности сразу.

Что ведущему можно соединять, ограничено намеренно — стрелка раздаёт возможности:

- только карточки **того же воркспейса**;
- без [режима карточек](https://docs.neurosquad.ai/ru/squads/canvas-mode) один конец стрелки — сам ведущий или созданная им
карточка; в режиме карточек — любые две карточки;
- **терминал**, **браузер**, MCP-сервер, Telegram или своя карточка, которые завели **вы**, передаются
дальше только если вы сами подключили их к ведущему — до вашего терминала ведущий сам не дотянется;
- помощник не может взять командование над своим ведущим и не может перерезать стрелку, по которой
ведущий к нему обращается;
- пока [бюджет](https://docs.neurosquad.ai/ru/cards/budget) воркспейса на паузе, стрелки не проводятся; не больше 30 изменений стрелок в
минуту на агента.

Удалять карточки так ведущий не может — снятая стрелка оставляет обе карточки на месте.

---

## Режим карточек

> Агент работает через карточки — сам открывает себе терминалы, браузеры, заметки и помощников.

Source: https://docs.neurosquad.ai/ru/squads/canvas-mode

Обычно карточки и стрелки расставляете вы. В **режиме карточек** агент делает это сам: он работает
через карточки на холсте, а не где-то внутри своего окна.

Вся история по шагам и что даёт такая работа — на странице [neurosquad.ai/ru/canvas-mode](https://neurosquad.ai/ru/canvas-mode/).

- Для команд он открывает **карточку терминала** — по одной на каждый долгий процесс.
- Когда ему нужен веб, он открывает **карточку браузера**.
- Свой журнал он ведёт в **карточке-заметке**.
- Для работы, которую можно делать параллельно, он создаёт **агентов-помощников**.
- Он **подключает помощников** к карточкам, нужным для их задачи, — вашей заметке, терминалу,
браузеру, доске задач: помощник видит только карточки, подключённые к нему самому. В режиме карточек
он может соединять любые две карточки воркспейса ([что ему можно соединять](https://docs.neurosquad.ai/ru/squads/lead-agent#give-helpers-cards)).

Всё, что он делает, видно прямо на холсте. Карточка в режиме карточек слегка светится зелёным.

### Как включить

Меню карточки агента → **Включить режим карточек**. Пункт есть у каждого ИИ-CLI, которому достаются
инструменты карточек NeuroSquad, — у всех 19: Claude Code, Codex CLI, OpenCode, Kilo Code, Hermes
Agent, Qwen Code, Gemini CLI, GitHub Copilot CLI, Factory Droid, Amp, Auggie, Cursor CLI, Cline CLI,
Goose, Kimi Code, Crush, aider, Pi и omp.

Инструменты карточек и инструкции переключаются сразу, пока агент работает. Кроме того, NeuroSquad
отбирает у CLI его **собственные** инструменты оболочки и веба — чтобы агент действительно
пользовался карточками. У каждого CLI это сделано по-своему:

| CLI | Как отключаются его оболочка и веб | Держится в опасном режиме | С какого момента |
| --- | --- | --- | --- |
| Claude Code | `Bash`, `WebSearch`, `WebFetch` запрещены при запуске; опасный режим их не одобряет | да | со следующего запуска |
| Codex CLI | инструмент оболочки и веб-поиск выключены — модели они не предлагаются | да | со следующего запуска |
| OpenCode, Kilo Code | `bash`, `webfetch`, `websearch` запрещены в конфиге карточки | да | со следующего запуска |
| Hermes Agent | отключены наборы инструментов `terminal`, `code_execution`, `web`, `search` и `browser` | да | со следующего запуска |
| Qwen Code | `run_shell_command`, `monitor`, `web_fetch`, `web_search` отключены и запрещены | да | со следующего запуска |
| Gemini CLI | исключены `run_shell_command`, инструменты фоновых процессов, `web_fetch`, `google_web_search` | да | со следующего запуска |
| GitHub Copilot CLI | исключены инструменты bash/PowerShell, `web_fetch` и `web_search`, оболочка запрещена | да | со следующего запуска |
| Factory Droid | хук запрещает `Execute`, `Script`, `WebSearch`, `FetchUrl` | да | со следующего запуска |
| Amp | плагин NeuroSquad отклоняет его инструменты оболочки, `web_search` и `read_web_page` при каждом вызове | да | со следующего запуска |
| Auggie | инструменты процессов, `web-fetch` и `web-search` убраны | да | со следующего запуска |
| Cursor CLI | хук запрещает `Shell`, `WebFetch`, `WebSearch` — состояние карточки читается при каждом вызове | да | сразу |
| Cline CLI | плагин NeuroSquad убирает `run_commands`, `fetch_web_content`, `web_search` и отклоняет их | да | со следующего запуска |
| Goose | у расширения `developer` остаются только файловые инструменты (без `shell`); у `code_execution` и `computercontroller` инструментов нет | да¹ | со следующего запуска |
| Kimi Code | `Bash`, `WebSearch`, `FetchURL` отключены, и ещё их блокирует хук | да | со следующего запуска |
| Crush | отключены `bash`, его инструменты фоновых задач, `download`, `fetch`, `agentic_fetch`, `sourcegraph` | да | со следующего запуска |
| aider | перестаёт предлагать shell-команды и подтягивать URL из чата² | да | со следующего запуска |
| Pi | исключены `bash` и `powershell`; своих веб-инструментов у Pi нет | да | со следующего запуска |
| omp | `bash`, `eval`, `web_search` и чтение URL заблокированы и скрыты от модели | да | со следующего запуска |

¹ Менеджер расширений Goose остаётся, так что модель при большом желании может включить другое
расширение. ² `/run` и `/web` по-прежнему можете набирать вы сами.

«Со следующего запуска» — CLI подхватывает это, когда карточка запускается заново; до тех пор
текущая сессия сохраняет свои инструменты. Опасный режим пропускает запросы разрешений, но не
возвращает то, что отобрал режим карточек.

> Режим карточек — не песочница. Агент по-прежнему читает и правит файлы проекта своими
> инструментами, а то, что он запускает в карточке терминала, — настоящие команды на вашем компьютере.

---

## Рецепты команд

> Готовые схемы команд агентов, которые можно повторить на своём холсте.

Source: https://docs.neurosquad.ai/ru/squads/recipes

### Разработчик и тестировщик

**Карточки:** агент, терминал с вашим дев-сервером, браузер.
**Стрелки:** агент → терминал, агент → браузер.

Попросите: *«Добавь форму подписки на рассылку, потом открой страницу в браузере и проверь, что всё
работает».* Агент правит код, видит результат в браузере и чинит то, что сломалось.

### Ведущий и помощники

**Карточки:** один ведущий агент, два агента-помощника, [доска задач](https://docs.neurosquad.ai/ru/cards/kanban).
**Стрелки:** ведущий → каждый помощник, все трое → доска задач.

Попросите ведущего разбить работу на задачи на доске и раздать их. Вы смотрите, как задачи
переезжают из **To do** в **Done**.

### Автор и ревьюер

**Карточки:** [изолированный](https://docs.neurosquad.ai/ru/agents/worktrees) агент.
Затем выберите **Add a reviewer** в меню агента — второй агент на другом ИИ прочитает изменения,
ничего не редактируя. Вы читаете обоих, передаёте замечания автору и сливаете его ветку.

### Ночная смена

**Карточки:** [изолированный](https://docs.neurosquad.ai/ru/agents/worktrees) агент, карточка [бюджета](https://docs.neurosquad.ai/ru/cards/budget).
**Schedule** в меню агента запускает работу ночью, бюджет не даёт потратить лишнего, а поскольку
агент работает на своей ветке, утром вы сливаете то, что нравится, и выбрасываете остальное.

---

## Ваши агенты в телефоне

> Следите за NeuroSquad и управляйте им с телефона — дома или в дороге.

Source: https://docs.neurosquad.ai/ru/remote

Запустили долгую задачу и отошли? **Удалённый доступ** позволяет открыть NeuroSquad на телефоне:
видеть, какие агенты работают или ждут, читать их экраны, отправлять промпты и слышать сигнал, когда
кто-то из них вас ждёт.

Всю работу делает компьютер — телефон лишь окно в него. Никакого магазина приложений и никакого
входа на телефоне: сканируете QR-код и добавляете страницу на главный экран.

  - **[Подключить телефон](https://docs.neurosquad.ai/ru/remote/pairing)**: Включите доступ и отсканируйте код — в той же сети Wi-Fi.
  - **[Вдали от дома](https://docs.neurosquad.ai/ru/remote/internet)**: Заходите на компьютер через интернет с помощью Cloudflare.
  - **[Что можно делать с телефона](https://docs.neurosquad.ai/ru/remote/on-the-phone)**: Воркспейсы, карточки, промпты и оповещения.

### Вы всегда знаете, что кто-то подключён

Пока подключён хоть один телефон, по верху окна NeuroSquad идёт **зелёная полоса**: «iPhone is
connected remotely on your network». Закрыть её нельзя: удалённый доступ может всё то же, что и
окно, поэтому искать эти сведения вам никогда не придётся. Кнопка **Remote access** в верхней
панели показывает подключённые устройства и выключает удалённый доступ.

> Любой, у кого есть ваша ссылка для подключения, может читать ваши терминалы и отправлять промпты
> вашим агентам. Не делитесь ни ссылкой, ни скриншотом QR-кода. Если это уже случилось, нажмите
> **Regenerate** — все подключённые телефоны сразу отключатся.

---

## Подключить телефон

> Включите удалённый доступ и отсканируйте QR-код телефоном.

Source: https://docs.neurosquad.ai/ru/remote/pairing

**1. Откройте Remote access**

Нажмите кнопку **Remote access** в верхней панели (или зайдите в **Settings → Remote access**) и
включите удалённый доступ.

**2. Выберите Local network**

Телефон должен быть в той же сети Wi-Fi, что и компьютер. Если компьютер подключён к нескольким
сетям, выберите ту, в которой телефон.

**3. Отсканируйте QR-код**

Наведите камеру телефона на код и откройте ссылку. Готово.

**4. Добавьте на главный экран**

В браузере телефона выберите **Share → Add to Home Screen** («Поделиться → На экран „Домой“»).
Дальше страница будет открываться как приложение.

> Не меняйте порт в **Settings → Remote access**, чтобы ярлык на главном экране продолжал работать.

### Отключить телефон

В **Settings → Remote access** нажмите **Regenerate** рядом с **Pairing link**. Все телефоны,
подключённые по старой ссылке, сразу перестанут работать, и им придётся отсканировать новый код.

---

## Вдали от дома

> Заходите в NeuroSquad с мобильного интернета или из другой сети через бесплатный туннель Cloudflare.

Source: https://docs.neurosquad.ai/ru/remote/internet

В одной сети Wi-Fi телефон общается с компьютером напрямую. Чтобы достучаться до компьютера с
мобильного интернета или из другой сети, переключите **Share access over** на **Internet**.
NeuroSquad подключится через **туннель Cloudflare** — на роутере ничего настраивать не нужно.

### Два вида туннеля

  - **Быстрый (без аккаунта)**: Бесплатно, без регистрации. Вы получаете случайный https-адрес. Он меняется при каждом запуске NeuroSquad, так что после перезапуска отсканируйте код заново. В первый раз NeuroSquad скачивает небольшую вспомогательную программу Cloudflare (около 55 МБ).
  - **Свой туннель Cloudflare**: Постоянный адрес на вашем собственном домене. Создайте туннель в панели Cloudflare, затем вставьте его публичное имя хоста и токен туннеля в **Settings → Remote access**.

> Так NeuroSquad оказывается в открытом интернете. Между посторонним человеком и вашими агентами
> стоит только ссылка для подключения — никогда ею не делитесь. Трафик шифруется и проходит через
> Cloudflare.

### Локальная сеть или интернет?

| | Локальная сеть | Интернет |
| --- | --- | --- |
| Работает | в той же сети Wi-Fi | где угодно |
| Настройка | не нужна | не нужна (быстрый) или аккаунт Cloudflare (свой туннель) |
| Адрес | не меняется | быстрый: меняется при перезапуске |

---

## Что можно делать с телефона

> Воркспейсы, живые экраны агентов, промпты, новые карточки и оповещения — с телефона.

Source: https://docs.neurosquad.ai/ru/remote/on-the-phone

- **Видеть все воркспейсы** — сколько в каждом карточек, сколько из них работает и сколько ждёт вас.
- **Открывать воркспейс** — карта его холста со всеми карточками и их статусами.
- **Читать экран агента** — вживую, с масштабированием.
- **Отправлять промпт** — напечатайте его на телефоне или воспользуйтесь голосовой клавиатурой
телефона.
- **Добавлять карточку** или **создавать воркспейс** — выбирайте папку на компьютере прямо с
телефона.
- **Получать оповещения** — пока страница открыта, она подаёт сигнал и показывает каждого агента,
который закончил или ждёт вас.

> Карточка работает, только пока её воркспейс открыт на компьютере. Если открыть карточку, чей
> воркспейс там не открыт, телефон попросит сначала открыть его на компьютере.

> Push-уведомлений на заблокированный телефон пока нет — для них нужен постоянный https-адрес.
> Держите страницу открытой, чтобы слышать сигнал.

---

## Говорите вместо набора

> Нажмите горячую клавишу, скажите — и слова появятся текстом. Всё обрабатывается на вашем компьютере.

Source: https://docs.neurosquad.ai/ru/dictation

Объяснить задачу вслух часто быстрее, чем напечатать. В NeuroSquad встроена диктовка, и работает
она в любом месте компьютера — не только в NeuroSquad.

**1. Нажмите горячую клавишу**

`Ctrl Shift Space`. Маленькая чёрная капсула покажет, что идёт запись.

**2. Говорите**

Скажите, что нужно, — сколько угодно долго.

**3. Нажмите горячую клавишу ещё раз**

Текст скопируется в буфер обмена. Если NeuroSquad на переднем плане, он ещё и сразу вставится в
агента, с которым вы работаете.

**Нажмите** клавишу, чтобы начать и закончить, или **удерживайте** её, пока говорите, и отпустите,
когда закончите.

> Речь никогда не покидает ваш компьютер. Модель распознавания работает локально, а звук хранится
> ровно столько, сколько нужно, чтобы превратить его в текст.

### Сменить горячую клавишу

**Settings → Dictation → Dictation shortcut → Change**, затем нажмите новое сочетание. Там же можно
выбрать, где на экране появляется капсула (**Overlay position**).

  - **[Модели распознавания речи](https://docs.neurosquad.ai/ru/dictation/models)**: Быстрее или точнее — выбирать вам.
  - **[История диктовки](https://docs.neurosquad.ai/ru/dictation/history)**: Всё, что вы сказали, — можно скопировать ещё раз.

---

## Модели распознавания речи

> Выбирайте между моделью распознавания речи по умолчанию и более крупными и точными.

Source: https://docs.neurosquad.ai/ru/dictation/models

Модель выбирается в **Settings → Dictation**. Все они работают на вашем компьютере. В установщик
ни одна не входит: каждая скачивается один раз — в мастере первого запуска или прямо в настройках.
Пока модели на диске нет, в строке состояния написано **Dictation: download the model**.

  - **Parakeet (по умолчанию)**: Скачивается один раз и используется по умолчанию. Быстрая на любом компьютере и достаточно точная для повседневной диктовки. Понимает английский и основные европейские языки, включая русский.
  - **Whisper large-v3-turbo**: Скачивается один раз. Заметно лучше справляется с акцентами, фоновым шумом и пунктуацией, но на обычном процессоре работает медленнее.
  - **Whisper на видеокарте (faster-whisper)**: Та же модель Whisper, ускоренная видеокартой NVIDIA: десять минут речи — за несколько секунд. Нужна разовая дополнительная установка, её предложат прямо в настройках. Только Windows.

Нет видеокарты NVIDIA? Оставайтесь на Parakeet — для большинства это правильный выбор.

---

## История диктовки

> Всё, что вы надиктовали, — в боковой панели, можно скопировать ещё раз.

Source: https://docs.neurosquad.ai/ru/dictation/history

Всё, что вы диктуете, сохраняется текстом в панели **истории диктовки** справа в окне. Откройте её,
чтобы ещё раз скопировать прежнюю диктовку, — удобно, если текст ушёл не в то окно.

- **Copy** — скопировать запись одним кликом.
- **Delete** — удалить одну запись, **Clear** — очистить всю историю.

Хранится только текст, звук — никогда, и всё остаётся на вашем компьютере.

---

## Расход и стоимость

> Смотрите, сколько именно токенов тратят агенты и во что это обходится, — по агентам, воркспейсам, типам агентов, моделям и провайдерам.

Source: https://docs.neurosquad.ai/ru/usage

ИИ-агенты оплачиваются за токены. Раздел **Usage** в сайдбаре показывает, куда уходят ваши
токены — и ваши деньги.

### Выберите период

Выберите **Today**, **7 days**, **30 days**, **This month**, **Last month** или **All time** — или
любой **Date range**. Каждое число сравнивается с предыдущим периодом той же длины. Фильтрами можно
сузить картину до одного воркспейса или одного агента. **Include usage outside cards** добавляет и
сессии, которые вы запускали в своём терминале, вне NeuroSquad.

### Что вы видите

- **Токены и стоимость** за период — наверху.
- **Токены по времени** с разбивкой по агентам и **из чего состоят токены** — новый ввод, контекст,
перечитанный из кэша, контекст, записанный в кэш, вывод.
- **Когда уходят токены** — карта «день недели × час», по которой видно, когда агенты заняты больше
всего.
- **Все агенты** — сортируемая таблица с точными числами: запросы, ввод, кэш, вывод, итог, пиковый
контекст, стоимость и доля.

Вкладки разбивки делят те же числа **By agent**, **By workspace**, **By harness**, **By model** и
**By provider**. Щёлкните по агенту или воркспейсу, чтобы перейти к нему.

### Сравнение моделей

**Compare models** ставит несколько моделей рядом: стоимость, токены, стоимость запроса, стоимость
1000 токенов вывода, доля в периоде и прайсовая цена каждой модели.

### Точные числа и откуда они берутся

Стоимость считается точно и округляется только на экране. Строки всегда складываются в итог. Каждая
стоимость — это либо то, что записала сама программа-агент, либо прайсовая цена модели, а запросы,
отправленные через [OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter), считаются по собственному каталогу OpenRouter.

> Расход читается из собственных журналов агентов: **Claude Code**, **Codex CLI**, **OpenCode**, **Kilo Code**,
> **Hermes Agent**, **Pi** и **omp**. Раздел сам подскажет, какие из ваших агентов не учтены. Если у вас подписка, а не
> оплата за токены, показанная стоимость — это сколько та же работа стоила бы по прайсу.

### Экспорт

**Export CSV** сохраняет таблицу, чтобы открыть её в Excel или Google Sheets.

### OpenRouter

Если вы пользуетесь [OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter), вкладка **By provider** показывает, что
OpenRouter сообщает о вашем ключе: потрачено сегодня, за неделю, за месяц и за всё время, и ваш
лимит. Это данные по ключу целиком — по всем агентам и всем другим приложениям, которые его
используют.

### Держите расходы под контролем

- Карточка агента показывает, насколько заполнен контекст агента Claude Code, OpenCode, Kilo Code или Hermes Agent.
- [Карточка бюджета](https://docs.neurosquad.ai/ru/cards/budget) задаёт лимит токенов на весь воркспейс и ставит его агентов на
паузу при превышении.

---

## Провайдеры моделей

> Выбирайте, на какой ИИ-модели работает каждый агент, — через свой вход или через провайдера вроде OpenRouter.

Source: https://docs.neurosquad.ai/ru/providers

По умолчанию каждый агент работает через аккаунт, в который вы вошли: Claude Code — через вашу
подписку Claude, Codex — через ваш аккаунт OpenAI и так далее. В NeuroSquad это называется
**Default (harness login)**.

**Провайдер моделей** позволяет выбирать модель самому: один раз подключите провайдера в
**Settings → Providers**, а затем выбирайте провайдера и модель для каждого агента. Удобно, чтобы
попробовать на задаче другую модель или отдать рутину модели подешевле.

  - **[OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter)**: Сотни моделей от множества ИИ-лабораторий по одному ключу — для Claude Code, Codex CLI, OpenCode, Kilo Code, Qwen Code, Hermes Agent, Pi и omp.
  - **[Аккаунты CLI и лимиты тарифа](https://docs.neurosquad.ai/ru/providers/accounts)**: Несколько входов в Claude Code или Codex рядом, счётчик каждого тарифа и передача работы на другой аккаунт одним нажатием.

Какой провайдер и какую модель использует агент, видно по маленькому ярлыку на его карточке, а во
сколько обходится каждая — в разделе [Расход и стоимость](https://docs.neurosquad.ai/ru/usage).

### Модель собственного входа агента

И без провайдера можно выбрать, на какой из **своих** моделей работает агент: меню ⋯ карточки →
**Провайдер и модель**, оставьте **Default (harness login)** и выберите или впишите модель —
например, `opus` для Claude Code или `anthropic/claude-sonnet-4-5` для OpenCode. Агент получит её
при следующем запуске. Crush и Amp выбирают модель сами, поэтому у них этого нет.

---

## OpenRouter

> Запускайте Claude Code, Codex CLI, OpenCode, Kilo Code, Qwen Code, Gemini CLI, GitHub Copilot CLI, Hermes Agent, Pi, omp, Factory Droid или Crush на сотнях моделей по одному ключу OpenRouter.

Source: https://docs.neurosquad.ai/ru/providers/openrouter

[OpenRouter](https://openrouter.ai) даёт доступ к моделям множества ИИ-лабораторий по одному ключу, а
оплата списывается с ваших кредитов OpenRouter. NeuroSquad может запускать через него агентов
**Claude Code**, **Codex CLI**, **OpenCode**, **Kilo Code**, **Qwen Code**, **Gemini CLI**, **GitHub Copilot CLI**, **Hermes Agent**, **Pi**, **omp**, **Factory Droid** и **Crush** (Factory Droid для этого не нужен аккаунт Factory).

### 1. Подключите ключ

**1. Откройте Settings → Providers**

Если ключа ещё нет, нажмите **Get a key** — откроется сайт OpenRouter.

**2. Вставьте ключ и нажмите Save and test**

Появится **Key works**. Ключ шифруется средствами вашей операционной системы и передаётся только
тем агентам, которых вы на него направили.

После подключения на той же странице видно, сколько потрачено (**Spent**) сегодня, за неделю и за
месяц, ваш лимит, если вы задали его в OpenRouter, и список доступных моделей (**Models**).

### 2. Создайте агента на модели

В меню добавления выберите **New agent… (provider, model, role)**. Диалог спросит:

- **Harness** — какую программу-агента запускать (Claude Code, Codex CLI, OpenCode, Kilo Code, Qwen Code, Gemini CLI, GitHub Copilot CLI, Hermes Agent, Pi, omp, Factory Droid или Crush).
- **Provider** — **OpenRouter** или **Default (harness login)**.
- **Model** — ищите в каталоге; у каждой модели указаны размер контекста и цена за миллион токенов.
Оставьте **Harness default**, чтобы модель выбрал сам агент.
- **Role** (необязательно) — см. [Роли](https://docs.neurosquad.ai/ru/agents/roles).
- **Name** (необязательно).

На карточке агента появится ярлык с его провайдером и моделью.

### Как поменять потом

Откройте **Provider and model** в меню карточки агента, выберите новые значения и нажмите **Apply**.
Изменение вступит в силу при следующем запуске агента.

### Без ключа

Если ключ не сохранён, в OpenRouter ничего не отправляется: агент просто работает через свой
**вход по умолчанию**, а его ярлык становится янтарным, чтобы вы это заметили. Диалог **New agent**
тоже предупредит об этом и предложит **Open settings**.

> Гарантированно Claude Code работает только с моделями самой Anthropic. На других моделях его
> инструменты могут работать неправильно — окно выбора модели об этом предупреждает.

---

## Аккаунты CLI и лимиты тарифа

> Несколько входов в Claude Code или Codex рядом, расход лимитов каждого тарифа и продолжение работы на другом аккаунте одним нажатием.

Source: https://docs.neurosquad.ai/ru/providers/accounts

Если у вас больше одной подписки Claude или ChatGPT, например личная и рабочая, NeuroSquad держит
входы раздельно и показывает, сколько израсходовано на каждом тарифе.

### Счётчики тарифа

В шапке карточки **Claude Code** или **Codex CLI** есть маленькое кольцо. Оно показывает, насколько
заполнено самое загруженное окно тарифа, например `7d 80%`. По нажатию открываются все окна со
временем сброса:

- **Claude Code** (Pro и Max): 5-часовое и недельное окно.
- **Codex CLI** (тарифы ChatGPT): окна вашего тарифа, например 5 часов и неделя.

С 80% кольцо жёлтое, с 95% красное. В этих двух точках приходит уведомление; его можно выключить в
**Настройки → Уведомления → Агент упёрся в лимит использования**.

Все счётчики собраны и в одном месте:

- **Расход → Лимиты тарифа** показывает все аккаунты.
- Доска **Команда** показывает строку для каждого аккаунта своих агентов.

Цифры приходят от самих CLI:

- **Claude Code** передаёт их своей строке статуса после каждого ответа.
- **Codex** пишет их в свой журнал сессии.

NeuroSquad никогда не читает ваш вход и не запрашивает расход у сервисов сам. Поэтому:

- Счётчик Claude Code появляется после первого ответа в карточке.
- Пока ни одна карточка Claude Code не запущена, он показывает последние цифры и их возраст.
- Окно, чьё время сброса прошло, показано как начавшееся заново.

#### Ваша строка статуса Claude Code продолжает работать

Чтобы получать цифры, карточка Claude Code пропускает свою строку статуса через NeuroSquad. Если у вас
есть своя строка статуса, NeuroSquad по-прежнему запускает вашу команду и показывает её вывод. Если
нет, в строке будет счётчик, например `5h 6% · 7d 80%`.

Чтобы строка статуса Claude Code осталась совсем нетронутой, выключите **Настройки → Аккаунты CLI →
Счётчик тарифа Claude Code**. Тогда у карточек Claude Code не будет счётчика.

Остальные CLI не передают цифры тарифа локальным программам, поэтому счётчика у них нет. Сколько они
стоят, видно в разделе [Расход](https://docs.neurosquad.ai/ru/usage).

### Несколько аккаунтов одного CLI

Откройте **Настройки → Аккаунты CLI** и нажмите **Добавить аккаунт** под Claude Code или Codex CLI.
Дайте ему название, например *Рабочий*.

- У каждого аккаунта своя папка для входа, настроек и истории этого CLI.
- **Ваш аккаунт**, то есть обычный вход, остаётся ровно там, где был.
- Новый аккаунт начинается с нуля: ваши настройки в него не копируются.

Чтобы работать на аккаунте, выберите его у карточки в одном из мест:

- Меню ⋯ карточки → **Провайдер и модель** → **Аккаунт**.
- Диалог **Новый агент…**.

Выбор действует со следующего запуска карточки. В первый раз войдите **внутри карточки** обычным
входом самого CLI:

- В Claude Code выполните `/login`.
- Codex сам покажет экран входа.

> NeuroSquad никогда не читает, не копирует и не отправляет то, что CLI хранит в папке аккаунта. Вход
> всегда выполняется в самом CLI.

Удаление аккаунта удаляет его папку: этот вход и разговоры на нём. Карточки на нём при следующем
запуске вернутся на ваш аккаунт.

### Продолжить на другом аккаунте

Когда тариф карточки почти израсходован или лимит уже наступил, откройте счётчик или чип лимита и нажмите
**Продолжить на другом аккаунте…**. Откроется диалог [передачи](https://docs.neurosquad.ai/ru/agents/long-sessions). Выберите аккаунт,
проверьте сводку и создайте новую карточку. Она появится рядом со старой, в той же папке, с набранной
сводкой.

Сам по себе аккаунт не переключается никогда. Каждый аккаунт используется так, как позволяет его тариф,
и перенос работы всегда остаётся вашим решением.

Если на аккаунт ещё не входили из NeuroSquad, новая карточка сначала откроет вход CLI. Сводка
копируется в буфер обмена, чтобы вставить её после входа.

### Расход по аккаунтам

**Расход → По аккаунтам** делит токены и стоимость по входу, который за них заплатил. Обычный вход
каждого CLI показан как *Ваш аккаунт*, у каждого добавленного аккаунта своя строка.

---

## Интеграции

> Подключайте агентов к Telegram — и как хранятся сохранённые токены и ключи.

Source: https://docs.neurosquad.ai/ru/integrations

Интеграции работают так же, как любые другие карточки: добавьте карточку, один раз подключите
аккаунт и проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к ней. После этого агент может пользоваться
сервисом, а вы видите каждое обращение на стрелке.

  - **[Бот в Telegram](https://docs.neurosquad.ai/ru/integrations/telegram)**: Общайтесь с агентами из Telegram и получайте сообщение, когда они закончат.

### Ваши пароли и токены в безопасности

Пароли, токены и ключи шифруются средствами вашей операционной системы и хранятся на вашем
компьютере. После сохранения они больше нигде не показываются — ни в приложении, ни на телефоне
через [удалённый доступ](https://docs.neurosquad.ai/ru/remote). Удаление карточки удаляет и её сохранённые секреты.

> Раздел **Integrations** в сайдбаре показывает ваши карточки Telegram во всех воркспейсах, а также
> ваших [провайдеров моделей](https://docs.neurosquad.ai/ru/providers).

---

## Бот в Telegram

> Пишите агентам из Telegram, получайте их ответы — и сообщение, когда они закончат.

Source: https://docs.neurosquad.ai/ru/integrations/telegram

**Карточка Telegram** подключает вашего собственного бота в Telegram к вашим агентам. Напишите боту с
телефона — и сообщение получат агенты, подключённые к карточке [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows). Ответить
они могут в том же чате.

Всё работает с вашего компьютера — никакой сервер настраивать не нужно.

### Настройка

**1. Создайте бота**

В Telegram откройте **@BotFather** (в карточке есть кнопка для этого), отправьте `/newbot` и
придумайте имя. BotFather ответит токеном.

**2. Вставьте токен**

Добавьте карточку Telegram, вставьте токен и нажмите **Connect**.

**3. Напишите боту и нажмите Allow**

Отправьте боту `/start`. Карточка покажет этот чат в списке «Wants to talk to your agents» —
нажмите **Allow**.

> До агентов доходят только чаты, для которых вы нажали **Allow**. Всех остальных, кто найдёт вашего
> бота, он просто игнорирует.

### Уведомления в Telegram

Настройка **Tell me in Telegram when a connected agent finishes or needs input** отправляет
сообщение во все разрешённые чаты, когда подключённый агент закончил или ждёт ответа, — можно
отойти от компьютера и всё равно знать, когда вернуться.

Ещё можно писать сообщения от имени бота прямо в карточке и выбирать, какой из подключённых агентов
их получит.

---

## Навыки и MCP

> Навыки со skills.sh и инструменты любого MCP-сервера — ставятся один раз и выдаются конкретным агентам стрелкой.

Source: https://docs.neurosquad.ai/ru/skills-mcp

Два вида дополнений делают агента сильнее в конкретной работе, и NeuroSquad ставит оба сам:

  - **MCP-сервер**: Небольшая программа или веб-сервис, который даёт агенту **новые инструменты**: прочитать файл Figma, открыть задачи GitHub, сделать запрос к базе, получить свежую документацию библиотеки. Говорит на Model Context Protocol — стандарте, который понимают все крупные агенты.
  - **Навык**: Папка с **экспертными инструкциями** (`SKILL.md`, иногда со скриптами и справочными файлами), которая объясняет агенту, как хорошо делать определённую работу: продумать идею до реализации, сделать выразительный интерфейс, составить нормальный план тестирования.

### Как это устроено

**1. Найдите в каталоге**

**Skills & MCP** ищет по официальному **MCP Registry** (около 35 000 серверов) и **skills.sh**
(20 000 самых популярных навыков, с числом установок и проверками безопасности) — по мере ввода.
См. [Каталог и установка](https://docs.neurosquad.ai/ru/skills-mcp/catalog).

**2. Установите один раз**

До любой загрузки видно, что именно будет запущено, — и вы подтверждаете. Всё ставится в
собственную папку NeuroSquad: ничего глобально, ваши настройки агентов не трогаются.

**3. Положите карточку на холст и протяните стрелку**

Карточка **MCP server** или **Skill** — это один установленный элемент. Протяните стрелку от неё
к агенту — и у агента он есть. См. [Как выдать агентам](https://docs.neurosquad.ai/ru/skills-mcp/cards).

> **Видят только подключённые агенты.** Агент без стрелки к карточке MCP или навыка не видит ничего
> из установленного — даже того, что оно есть. Пять агентов могут делить один сервер, а могут
> получить каждый свой.

### Какие агенты это умеют

| Агент | Навыки и MCP-серверы | После того как нарисована стрелка |
| --- | --- | --- |
| **Claude Code** | Да | Сразу, без перезапуска |
| **Hermes Agent** | Да | Сразу, без перезапуска |
| **Kilo Code** | Да | Сразу, без перезапуска |
| **GitHub Copilot CLI** | Да | Сразу, без перезапуска |
| **Pi** | Да | Сразу, без перезапуска |
| **omp** | Да | Сразу, без перезапуска |
| **aider** | Да | Сразу, без перезапуска |
| **Factory Droid** | Да | Сразу, без перезапуска |
| **Amp** | Да | Сразу, без перезапуска |
| **Auggie** | Да | Сразу, без перезапуска |
| **Goose** | Да | Сразу, без перезапуска |
| **Codex CLI** | Да | При следующем запуске агента |
| **Qwen Code** | Да | При следующем запуске агента |
| **Gemini CLI** | Да | Сразу |
| **Kimi Code** | Да | При следующем запуске агента |
| **Cline CLI** | Да | При следующем запуске агента |
| Остальные агенты | Нет | — |

То же самое карточка пишет рядом с каждым подключённым агентом: **Сразу**, **После перезапуска**
или **Недоступно**. Последнее значит, что NeuroSquad вообще не выдаёт этому агенту инструменты — это
те же агенты, которым [стрелки](https://docs.neurosquad.ai/ru/canvas/arrows) не дают возможностей.

### Откуда агент знает, что у него есть

Ничего объяснять агенту не нужно.

- **Навыки:** инструмент агента `skill_load` перечисляет все подключённые навыки со строкой «когда
использовать», поэтому агент сам загружает подходящий навык перед задачей — так же, как работают
собственные навыки Claude Code.
- **MCP-серверы:** инструменты каждого сервера появляются под его именем, например
`framelink__get_figma_data`; в описании каждого указан сервер, плюс собственные подсказки сервера.
- **`neurosquad_connections`** — инструмент, которым агент смотрит, что на другом конце его стрелок, —
тоже перечисляет подключённые серверы и навыки.

### Что стоит знать

- **Каждый вызов установленного сервера вы подтверждаете.** Его инструменты идут через отдельный
сервер (`ns-connected`), который NeuroSquad не разрешает заранее, поэтому Claude Code, Codex и
Qwen спрашивают перед каждым вызовом — если только вы сами не включили агенту режим, где всё
разрешено. Hermes Agent сам никогда не спрашивает, поэтому за него спрашивает NeuroSquad:
**Разрешить один раз**, **Разрешить до перезапуска** или **Запретить** (без ответа за пять минут —
отказ). Если сервер позже меняет свои инструменты, на карточке появляется блок с изменениями:
пока вы их не примете, агенты новых и изменённых инструментов не видят.
- **Это сторонний код.** Установленный сервер работает на вашем компьютере (или это сервис в
интернете); текст навыка попадает прямо в инструкции агента. Ставьте то, чему доверяете, — каталог
показывает источник, точные команды и, для навыков, проверки безопасности.
- **Пока ставится не всё.** Серверы, опубликованные только как MCPB, NuGet- или Cargo-пакеты, и
пакеты, поднимающие локальный веб-сервер, видны, но не устанавливаются.
- **Некоторые входы пускают только одобренные приложения.** Например, официальный удалённый сервер
Figma отказывает во входе приложениям, которых он не одобрил. Берите сервер с личным токеном —
**Framelink Figma MCP** (`FIGMA_API_KEY`) работает с вашим токеном Figma.

---

## Каталог и установка

> Поиск по MCP Registry и skills.sh, точный план запуска и установка серверов и навыков в собственную папку NeuroSquad.

Source: https://docs.neurosquad.ai/ru/skills-mcp/catalog

**Навыки, MCP и плагины** — одно окно с четырьмя вкладками: **MCP-серверы**, **Навыки**,
**Плагины** и **Установленные**. Откройте его из сайдбара (**Интеграции → Навыки, MCP и плагины**)
или из пустой карточки MCP или навыка кнопкой **Browse** — тогда установленное сразу попадёт в эту
карточку. Пункт **Плагин…** в меню добавления карточек открывает его на вкладке «Плагины».

### Поиск

Результаты появляются по мере ввода. Весь каталог хранится на компьютере и обновляется в фоне,
поэтому поиск мгновенный и работает без сети.

- **MCP-серверы** — из официального **MCP Registry**, все опубликованные там серверы. Фильтр по
способу запуска: **Локально** (пакет работает на вашем компьютере), **Удалённо** (сервис в
интернете) и **Без настройки** (ничего заполнять не нужно).
- **Навыки** — со **skills.sh**, самого популярного каталога навыков для агентов. Первыми идут самые
устанавливаемые; пока вы в сети, к результатам добавляется его собственный поиск с числом установок.
- **Установленные** — ваша библиотека: всё, что стоит на компьютере, с настройками, обновлениями и
удалением.

### Установка MCP-сервера

**1. Выберите способ запуска**

Многие серверы запускаются по-разному: **npm**-пакет (нужен Node.js), **PyPI**-пакет (нужен uv
или Python), **Docker**-образ (нужен Docker) или **удалённый** сервис по HTTPS. Способы, которые
NeuroSquad пока не умеет, показаны серым с причиной.

**2. Заполните настройки**

Ключи и токены (токен Figma, API-ключ) вводятся в поля-пароли. Они шифруются системным хранилищем
ключей и **никогда не показываются агентам** — агент получает только инструменты.

**3. Прочитайте «What will run»**

Точные команды, пакет и закреплённая версия, имена передаваемых настроек. Если Docker-образ
просит доступ к файлам, сети или устройствам, вы увидите предупреждение.

**4. Подтвердите и установите**

Отметьте галочку и нажмите **Install**. Вывод идёт прямо под кнопкой. Затем NeuroSquad один раз
запускает сервер, чтобы узнать его инструменты, — и всё готово.

> Всё ставится в собственную папку данных NeuroSquad — своя копия каждого пакета, своё окружение
> Python. Ничего не ставится глобально, `~/.claude`, `~/.codex` и другие настройки агентов не
> трогаются. Исключение — Docker-образы: они, как всегда, живут в Docker.

После установки откройте сервер во вкладке **Установленные**, чтобы:

- **Проверить** — запустить заново и перечитать инструменты.
- **Показать журнал** — что сервер написал, если он не запускается.
- **Войти / Выйти** — для удалённых серверов, работающих через ваш аккаунт (OAuth). Страница входа
откроется в браузере; токены хранятся зашифрованными.
- Изменить **настройки** — сохранённый ключ остаётся, пока вы не введёте новый.
- **Удалить** — удаляет файлы, настройки и сохранённые ключи. Карточки с ним остаются на холсте и
просят выбрать другой.

Сервер запускается, только когда он впервые понадобился агенту, один на всех подключённых агентов, и
останавливается после десяти минут без дела.

### Установка навыка

**5. Откройте его**

Вы видите его `SKILL.md` целиком, файлы и размер, лицензию и проверки безопасности, которые
публикует skills.sh (Snyk, Socket и другие).

**6. Обратите внимание на скрипты**

Если в навыке есть скрипты, об этом будет сказано: агент, следуя навыку, может их запускать.

**7. Подтвердите и установите**

Отметьте «Я прочитал навык» и нажмите **Install**. Ставится ровно то, что вы только что прочитали:
если навык успел измениться, вас попросят посмотреть ещё раз.

Во вкладке **Установленные** навык можно **обновить**, когда выходит новая версия, **открыть папку**
с его файлами или **удалить**.

### Добавление плагина

Плагины встроены в NeuroSquad — чтобы их показать, ничего не скачивается. Каждый плагин — это
карточка, которая меняет работу подключённых к ней агентов; первый —
[RTK-AI Token Saver](https://docs.neurosquad.ai/ru/plugins/rtk-ai-token-saver), он сжимает вывод их шелл-команд.

1. Выберите **Плагин…** в меню добавления карточек (поиск меню тоже находит его по словам `токен`,
`token` или `rtk`) или откройте вкладку **Плагины** в каталоге.
2. Выберите плагин: видно, что он делает, как им пользоваться и с какими агентами он работает.
3. Нажмите **Добавить на канвас**. Карточка появится на канвасе воркспейса, из которого открыто
меню (из сайдбара — открытого сейчас воркспейса). Проведите к ней стрелку от агента.

### Безопасность

- **Всё из каталога — сторонний код.** MCP-сервер — это программа с правами вашей учётной записи или
веб-сервис, с которым говорят агенты. Ставьте то, что поставили бы и так.
- **Текст навыка становится инструкцией агенту.** Навык может велеть агенту что угодно — прочитайте
его до установки; для этого каталог и показывает его целиком.
- Удалённые серверы — **только HTTPS**. Ключи никогда не попадают в командную строку или журнал.

---

## Как выдать агентам

> Карточки MCP-сервера и навыка — соединяются с агентами стрелками; получают их только подключённые агенты.

Source: https://docs.neurosquad.ai/ru/skills-mcp/cards

Установленный сервер или навык попадает к агенту через карточку на холсте. Добавьте её из
[меню добавления](https://docs.neurosquad.ai/ru/canvas/cards) — **MCP server** или **Skill** — и выберите, что она означает:
**Browse** открывает каталог, а уже установленное можно выбрать прямо на карточке.

### Соедините стрелкой

Протяните [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) между карточкой и агентом. Вот и всё:

- Агент получает инструменты сервера или навык — и **больше никто**.
- Одна карточка может быть соединена с несколькими агентами; у агента может быть несколько карточек.
- Удалите стрелку — и агент снова это теряет.

Каждая карточка показывает, каким агентам она выдана и что это значит для каждого:

  - **Сразу**: Агент получает это немедленно, посреди разговора. Так работают Claude Code, Kilo Code и Hermes Agent.
  - **После перезапуска**: Агент читает свои инструменты при запуске: перезапустите его, чтобы новая стрелка подействовала. Так работают Codex CLI и Qwen Code.
  - **Недоступно**: NeuroSquad не выдаёт инструменты такому агенту.

Нажмите на имя агента в карточке — камера перелетит к нему.

### Карточка MCP-сервера

- **Шапка:** имя сервера, сколько у него инструментов, и точка — работает, не запущен (стартует при
первом вызове), запускается, не запустился или ждёт входа.
- **Инструменты:** все инструменты сервера. Последний вызванный агентом подсвечивается, а карточка
ненадолго пишет «by Designer».
- **Проблемы — на месте:** «Сервер не запустился» с последней строкой журнала и **Try again**;
«нужно войти» с кнопкой **Sign in**.
- **Settings** открывает его в каталоге; **Change server** переключает карточку на другой.

### Карточка навыка

- Имя навыка, откуда он, файлы и есть ли скрипты, и описание — та самая строка «когда использовать»,
которую видит агент.
- Кто загружал его последним и сколько раз.
- Разверните карточку, чтобы прочитать `SKILL.md` целиком.
- **Details** открывает его в каталоге (обновить, открыть папку, удалить); **Change skill**
переключает карточку на другой.

При отдалении карточки становятся плитками: у сервера — число инструментов и агентов, у навыка — имя.

> Агент сам загружает подходящий навык **до** начала задачи — его инструмент `skill_load` перечисляет
> все подключённые навыки с тем, когда их использовать. Если нужен конкретный навык в любом случае,
> просто скажите: «используй навык brainstorming».

---

## Плагины

> Встроенные дополнения, которые подключаются к агенту стрелкой — без перезапуска и без правки настроек самого CLI.

Source: https://docs.neurosquad.ai/ru/plugins

Плагин меняет то, как работает подключённый агент. Добавьте его из меню добавления карточек —
**Плагин…** открывает вкладку **Плагины** в каталоге, где можно найти и выбрать нужный, — и
подключите к агенту [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows). Агент подхватит плагин на следующем действии;
уберёте стрелку — перестанет.

Плагины встроены в NeuroSquad и проверяются, прежде чем попасть в список. Собственные настройки
CLI не меняются: плагин — это слой, который NeuroSquad добавляет одной карточке агента.

  - **[RTK-AI Token Saver](https://docs.neurosquad.ai/ru/plugins/rtk-ai-token-saver)**: Сжимает вывод шелл-команд агента — меньше токенов, те же факты.
  - **[Caveman](https://docs.neurosquad.ai/ru/plugins/caveman)**: Агент отвечает коротко — без воды, код и ошибки дословно.
  - **[Память (mem0)](https://docs.neurosquad.ai/ru/plugins/mem0-memory)**: Долговременная память агентов между сессиями — хранится на вашем компьютере.
  - **[Context7 — актуальная документация](https://docs.neurosquad.ai/ru/plugins/context7-docs)**: Свежая документация библиотек нужной версии вместо устаревших знаний модели.
  - **[Граф кода](https://docs.neurosquad.ai/ru/plugins/code-graph)**: Граф знаний вашего кода — агенты находят вызовы и определения вместо grep.
  - **[Graphify](https://docs.neurosquad.ai/ru/plugins/graphify)**: Живая карта кода — агенты задают ей структурные вопросы, и каждый запрос подсвечивается на карте.

Скоро будут и другие плагины. Навыки и MCP-серверы подключаются так же, через свои вкладки
каталога, — см. [Навыки и MCP](https://docs.neurosquad.ai/ru/skills-mcp).

---

## RTK-AI Token Saver

> Подключите к ней агента — вывод его git, ls, grep и тестов вернётся сжатым: меньше токенов, те же факты.

Source: https://docs.neurosquad.ai/ru/plugins/rtk-ai-token-saver

Агенты читают много вывода команд: каждый `git status`, `git log`, список файлов и прогон тестов
попадает в их контекст. Плагин **RTK-AI Token Saver** пропускает команды оболочки агента через
[RTK](https://github.com/rtk-ai/rtk) — открытый инструмент, который оставляет факты и убирает шум:
`git status` превращается в компактный список изменённых файлов, прошедшие тесты — в одну строку.

### Как пользоваться

1. В меню добавления карточек выберите **Плагин…**, откройте **RTK-AI Token Saver** на вкладке
**Плагины** и нажмите **Добавить на канвас**.
2. Если RTK не установлен, нажмите **Скачать RTK**. NeuroSquad скачает официальную сборку с GitHub
(около 4,5 МБ) и сверит её с контрольной суммой, которую публикует GitHub; без контрольной суммы
скачивание не выполняется. RTK уже стоит (`winget install rtk-ai.rtk`, `brew install rtk`)? Он
найдётся сам.
3. Проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к карточке.

Всё — уже **следующая** команда агента идёт через RTK. Без перезапуска. Уберите стрелку — и
следующая команда снова выполнится как обычно.

### Что показывает карточка

- **Насколько меньше вывода** читают подключённые агенты — в процентах — и примерно сколько токенов
это сэкономило.
- Каждого подключённого агента: его экономию и последнюю сжатую команду, например
`git status → rtk git status`.
- Какая версия RTK используется — ваша установка или скачанная.

Каждая сжатая команда вспыхивает на стрелке и попадает в журнал стрелки.

> RTK считает токены как байты ÷ 4: процент точный, число токенов — приблизительное. RTK сжимает
> только вывод команд оболочки — ваши промпты, чтение файлов самим агентом и его ответы не меняются.

### С какими агентами работает

Вживую — с **Claude Code**, **Cursor CLI**, **OpenCode** и **Kilo Code**. Других агентов подключить
можно, но карточка пометит их **Не поддерживается**: их CLI пока не дают переписать команду до
запуска.

- **Опасный режим** — сжимается каждая поддерживаемая команда.
- **Обычный режим (Claude Code)** — команды только для чтения (`git status`, `git log`, `ls`, `cat`,
`grep`) сжимаются без запроса, как и выполнялись раньше. Команды, которые и так спросили бы
(`git push`, `cargo test`…), спрашивают один раз — вы разрешаете `rtk`-версию. Остальное
выполняется без изменений. RTK не добавляет запросов и не разрешает то, что спросило бы.
- **Обычный режим (Cursor, OpenCode, Kilo)** — их запросы разрешений нельзя предсказать снаружи,
поэтому для них RTK работает только в опасном режиме.
- **Режим карточек** — у агента нет своей оболочки, сжимать нечего.

Если RTK нет, он упал или не знает команду — выполняется исходная команда без изменений. Агенту,
которому нужен полный вывод одной команды, достаточно запустить её с `RTK_DISABLED=1` впереди.

### Приватность

RTK работает на вашем компьютере. NeuroSquad выключает собственную (добровольную) телеметрию RTK у
каждого агента, которого запускает, и хранит историю RTK отдельно для каждого агента в папке данных
NeuroSquad. Ваши настройки RTK остаются как есть.

RTK создан rtk-ai и распространяется по лицензии Apache 2.0.

---

## Caveman

> Подключите к ней агента — его ответы станут короткими: без воды, а код, команды и тексты ошибок останутся дословными.

Source: https://docs.neurosquad.ai/ru/plugins/caveman

Агенты любят объяснять: вежливое вступление, пересказ, «я бы рекомендовал…». Плагин **Caveman** даёт
подключённому агенту правила ответов [caveman](https://github.com/JuliusBrussee/caveman) — открытого
проекта Julius Brussee: убрать воду, оставить каждый технический факт. Как пишет автор, caveman делает
меньше не мозг, а «рот».

Один и тот же вопрос — пример из README самого caveman (на английском):

- **Без caveman:** «The reason your React component is re-rendering is likely because you're
creating a new object reference on each render cycle. When you pass an inline object as a prop,
React's shallow comparison sees it as a different object every time, which triggers a re-render.
I'd recommend using useMemo to memoize the object.»
- **С caveman (Full):** «New object ref each render. Inline object prop = new ref = re-render.
Wrap in `useMemo`.»

### Как пользоваться

1. В меню добавления карточек выберите **Плагин…**, откройте **Caveman** на вкладке **Плагины** и
нажмите **Добавить на канвас**.
2. Выберите уровень на карточке:
   - **Lite** — без воды и оговорок, полные предложения остаются.
   - **Full** — классический стиль caveman, уровень автора по умолчанию.
   - **Ultra** — самый сжатый: уходят и союзы, каждый факт — один раз.
   - **文言文** — те же три уровня на классическом китайском.
3. Проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к карточке.

Готово — **следующий** ответ агента уже следует правилам. Без перезапуска, в CLI ничего не
устанавливается. Смените уровень — следующий ход получит новый. Уберите стрелку — следующий ход получит
короткую записку «отвечай как обычно».

### Что остаётся дословным

Код, команды, пути к файлам и тексты ошибок не сокращаются — только текст вокруг них. Предупреждения
о безопасности и подтверждения необратимых действий приходят полными предложениями. Код,
сообщения коммитов, документация и описания pull request агент пишет обычным языком. Язык ответа
остаётся вашим.

### Что показывает карточка

- Уровень и пример ответа caveman для него (и тот же ответ без caveman).
- Каждого подключённого агента: работает ли он вживую, что получил последним (правила, напоминание
или записку о возврате) и сколько ходов шло с правилами.
- Во что обходятся правила: это входные токены модели — полный набор один раз за сессию (около 1 400
токенов), дальше короткое напоминание в каждом ходе (около 60). Обе цифры — оценка, 4 символа на
токен.

> Короткие ответы — это меньше **выходных** токенов, но сами правила — дополнительные **входные**
> токены, а размышления модели не сокращаются. На очень коротких вопросах правила могут стоить
> больше, чем экономят, — автор caveman пишет то же самое. Попробуйте на своей работе и оставьте там,
> где это окупается.

### С какими агентами работает

Вживую — с **Claude Code**, **Codex** и **Qwen Code**: правила уходят через хук, который срабатывает
перед каждым ходом и умеет добавить текст для модели. Других агентов можно подключить, но карточка
пометит их **Не поддерживается** — их CLI пока не дают добавить текст к ходу снаружи.

Опасный режим и режим карточек здесь роли не играют: плагин меняет то, как агент пишет, а не то, что
ему разрешено.

### Откуда это

Правила — собственные правила caveman: текст его навыка `caveman` и напоминание на каждый ход,
перенесённые в NeuroSquad без изменений из закреплённой версии и используемые по лицензии MIT.
NeuroSquad ничего не скачивает, никуда ничего не отправляет и не меняет настройки вашего CLI.
Отдельные прокси и движок caveman в этот плагин не входят.

---

## Память (mem0)

> Долговременная память, общая для агентов между сессиями: они запоминают факты и решения и вспоминают их потом. Хранится на вашем компьютере.

Source: https://docs.neurosquad.ai/ru/plugins/mem0-memory

Когда сессия агента заканчивается, он всё забывает. Плагин **Память** даёт подключённым агентам
долговременную память: они сохраняют то, что стоит помнить, — решение, договорённость, ваше
предпочтение, факт о проекте — и находят это снова в следующих сессиях, в других агентах, после
перезапуска.

В основе — [mem0](https://github.com/mem0ai/mem0), открытый движок памяти (Apache-2.0), встроенный в
NeuroSquad. Память хранится на вашем компьютере, в папке данных NeuroSquad. Ни аккаунта, ни сервера
не нужно.

### Как пользоваться

1. В меню добавления карточки выберите **Плагин…**, откройте **Память (mem0)** на вкладке
**Плагины** и нажмите **Добавить на канвас**.
2. Проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к карточке.

Теперь у агента есть инструменты памяти. Попросите его что-нибудь запомнить («запомни: деплой только
через GitHub Actions») или просто работайте — агенту подсказано искать в памяти перед работой, которая
может зависеть от прежних решений, и сохранять устойчивые факты. Уберите стрелку — инструменты
пропадут, а записи останутся на карточке.

Большинство агентов получают инструменты сразу, без перезапуска. Codex, Kimi Code, Cursor и Crush
читают список инструментов один раз при старте, поэтому видят инструменты памяти с самого начала, а
стрелка решает, пройдёт ли вызов. Qwen Code и Cline подхватят их при следующем запуске.

### Что может агент

| Инструмент | Что делает |
| --- | --- |
| `memory_search` | Находит записи, подходящие к вопросу, лучшие первыми |
| `memory_add` | Сохраняет факт (или кусок разговора, из которого нужно выделить факты) |
| `memory_list` | Показывает записи, новые первыми |
| `memory_get` | Читает одну запись |
| `memory_update` | Исправляет запись, которая устарела |
| `memory_delete` | Забывает запись |

Агент может изменить или удалить только те записи, которые сохранил **сам**. Чтобы агенты могли
править любые записи — ваши и других агентов, — включите **Агенты могут менять любые записи** в
настройках карточки.

### Карточка

Карточка показывает, сколько записей в памяти, — новые первыми, кто и когда сохранил каждую. Запись,
которую агент только что сделал, ненадолго подсвечивается. Можно искать, добавить запись самому
кнопкой **+**, изменить или удалить любую запись, экспортировать всё в JSON-файл и очистить память.

### Чья память: область

Откройте настройки (значок с ползунками на карточке) и выберите **область**:

- **Этот воркспейс** (по умолчанию) — все агенты, подключённые к карточкам памяти в этом
воркспейсе, делят одну память.
- **Все воркспейсы** — одна память на все воркспейсы: для того, что верно везде, например ваших
предпочтений и правил.
- **У каждого агента своя** — у каждого подключённого агента личная память; карточка показывает все.

Записи принадлежат области, а не карточке: удалите карточку и добавьте новую с той же областью —
записи на месте. Удаляет их кнопка **Очистить** в настройках.

### Поиск: по словам или по смыслу

Сразу после добавления карточка ищет **по словам** — по общим словам и их частям, поэтому «postgres»
находит «PostgreSQL». Это работает офлайн и без настройки, но синонимы не связывает («машина» и
«автомобиль»).

Для поиска **по смыслу** нажмите **Скачать 150 МБ** в блоке **Умный поиск** на карточке (или выберите
его в Настройках → Поиск). Один раз скачается небольшая многоязычная модель — она работает на вашем
компьютере, офлайн и понимает русский, английский, китайский и десятки других языков, так что вопрос
по-русски находит запись, сделанную по-английски. Каждый файл сверяется с контрольной суммой.

Можно также взять модель эмбеддингов из [OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter) или с
[сервера моделей](https://docs.neurosquad.ai/ru/providers), добавленного в Настройки → Провайдеры, который говорит на OpenAI API, —
например, Ollama с `nomic-embed-text` или LM Studio.

Выбор действует на все карточки памяти. При переключении все записи переиндексируются; карточка
показывает прогресс, а агенты ждут окончания.

### Выделение фактов

По умолчанию запись хранится ровно так, как написана. Выберите модель в разделе **Выделение фактов** —
и mem0 будет превращать сохраняемое агентами в короткие факты и пропускать уже известное. Это один
запрос к этой модели на каждое сохранение.

### Автоматическая память

Два переключателя в настройках, оба выключены по умолчанию:

- **Автоматические подсказки** — перед каждым вашим промптом к ходу агента добавляются самые
подходящие записи как заметки. Работает с **Claude Code**, **Codex**, **Qwen Code**, **OpenCode**,
**Kilo Code**, **Gemini CLI**, **pi** и **omp**. Остальные агенты ищут сами через `memory_search`.
- **Автоматическое сохранение** — когда подключённый агент заканчивает ход, ваш промпт и его итоговый
ответ уходят модели выделения фактов, и она сохраняет только устойчивые факты (часто — ничего).
Нужна модель выделения фактов.

### История, экспорт и импорт

- Кнопка с часами у записи показывает её историю: когда она добавлена и каждую правку — с текстом до
неё.
- **Экспорт** в настройках сохраняет записи карточки в JSON-файл. **Импорт** читает такой файл,
показывает, сколько записей новых и сколько уже есть (их пропустит), даёт выбрать область и добавляет
новые. Кнопка **Отменить** на карточке удаляет ровно то, что добавил последний импорт.

### Воркспейсы в WSL и по SSH

Агенты в воркспейсе внутри WSL или на SSH-хосте пользуются карточкой так же: стрелка даёт им
инструменты `memory_*`, а автоматическое вспоминание доходит до Claude Code там через его хук
промпта. Сами воспоминания остаются в папке данных NeuroSquad на этом компьютере — на той стороне
ничего не хранится, — и область «этот воркспейс», как обычно, держит воспоминания воркспейсов
раздельно.

### Удаление воркспейса или агента

При удалении воркспейса удаляются и записи, сохранённые для него; при удалении агента — его личные
записи (область «у каждого агента своя»). В подтверждении написано, сколько. Общие для всех
воркспейсов записи остаются.

> Ваши ключи остаются в NeuroSquad: они уходят только выбранному провайдеру, вместе с каждым
> запросом. В mem0 ничего не отправляется — собственная статистика движка отключена.

> Записи — это заметки из прошлого, а не инструкции: они могут устареть. Не просите агента
> запоминать пароли и ключи.

---

## Context7 — актуальная документация

> Подключите агента — и он будет сверяться с актуальной документацией нужной версии библиотек, с которыми работает, а не полагаться на то, что помнит с обучения.

Source: https://docs.neurosquad.ai/ru/plugins/context7-docs

Модель знает библиотеку такой, какой та была на момент обучения. А API меняются: у хука новая
сигнатура, опцию конфига переименовали, фреймворк перешёл на новый роутер. Плагин **Context7** даёт
подключённому агенту два инструмента из [Context7](https://github.com/upstash/context7) — открытого
проекта Upstash: найти библиотеку и прочитать её текущую документацию и примеры кода — для той
версии, которая стоит в проекте.

### Как пользоваться

1. В меню добавления карточки выберите **Плагин…**, откройте **Context7 — актуальная документация**
на вкладке **Плагины** и нажмите **Добавить на канвас**.
2. Проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к карточке.

Теперь у агента два инструмента:

- `context7_resolve_library_id` — находит библиотеку по названию («React», «Next.js», «Django») и
перечисляет совпадения с их id в Context7 (`/reactjs/react.dev`), числом примеров кода,
надёжностью источника и проиндексированными версиями.
- `context7_query_docs` — возвращает документацию и примеры одной библиотеки по одному конкретному
вопросу («useEffect cleanup function»).

Большинство агентов сами обращаются к ним, когда задача касается API библиотеки. Можно и попросить:
«сначала сверься с документацией Next.js» — или дописать в промпт **use context7**. Уберите стрелку —
инструменты пропадут. Для большинства CLI без перезапуска, в сам CLI ничего не устанавливается.

### Работает без аккаунта

Индекс документации Context7 — облачный сервис, бесплатный. Без ключа у него лимит запросов ниже;
бесплатный API-ключ из [панели Context7](https://context7.com/dashboard) его поднимает. Вставьте ключ
в панели **Ключ и кеш** на карточке — он хранится зашифрованным на вашем компьютере, больше не
показывается и никогда не попадает в файлы или командную строку. Один ключ на все карточки Context7.

Карточка показывает, сколько запросов осталось и когда лимит сбросится. Когда лимит исчерпан,
карточка пишет **Лимит исчерпан**, агенты получают понятное сообщение вместо ошибки, а новые запросы
не отправляются до сброса — ответы из кеша при этом работают.

### Кеш

Каждый ответ хранится на компьютере 24 часа. Если два агента спросили одно и то же или агент
повторил вопрос, ответ берётся из кеша и не тратит запрос. Панель **Ключ и кеш** показывает, сколько
ответов в кеше и сколько запросов он обслужил, и умеет его очищать.

### Автодокументация

Включите **Автодокументацию** на карточке — и агент будет получать подсказку перед каждым вашим
промптом:

- Если промпт упоминает зависимость проекта (из `package.json`, `requirements.txt`,
`pyproject.toml`, `Cargo.toml` или `go.mod`), агент получает короткую заметку, что для неё есть
актуальная документация, — с версией из вашего проекта. Запрос при этом не отправляется, так что
ход начинается так же быстро. Заметка — не чаще раза в полчаса на библиотеку.
- Если в промпте есть слово **context7** («use context7») и названа зависимость или id библиотеки
(`/vercel/next.js`), в ход сразу добавляется сама документация. NeuroSquad ждёт её около полутора
секунд; если Context7 отвечает медленнее, агент получает заметку, а ответ сохраняется в кеш на
следующий раз.

Автодокументация работает в **Claude Code**, **Codex**, **Qwen Code**, **OpenCode**, **Kilo Code**,
**pi**, **omp** и **Gemini CLI**. Любой другой агент, подключённый стрелкой, получает оба инструмента.

### Воркспейсы в WSL и по SSH

Агенты в воркспейсе внутри WSL или на SSH-хосте получают оба инструмента по стрелке как обычно —
запросы делает NeuroSquad на этом компьютере. Автодокументация читает `package.json` и другие
манифесты проекта из WSL или через SSH-соединение.

### Что показывает карточка

- Состояние сервиса — **Готово**, **Лимит исчерпан**, **Нет связи** или **Ошибка** — с остатком
запросов и датой сброса.
- **Проверить запрос**: введите библиотеку и вопрос и посмотрите, что получил бы агент.
- **Последние запросы**: какая библиотека и вопрос, какой агент спросил, когда и взят ли ответ из
кеша.

> Названия библиотек и вопросы отправляются на серверы Context7 (их держит Upstash). Не пишите в
> вопросах секреты, пароли и закрытый код — описания инструментов говорят агентам то же самое.
> Остальной проект остаётся на компьютере: автодокументация читает список зависимостей локально и
> отправляет только название библиотеки и вопрос.

### Откуда это

Оба инструмента — инструменты официального MCP-сервера Context7 (`@upstash/context7-mcp`, лицензия
MIT) с его описаниями; NeuroSquad обращается к тому же API Context7 напрямую, поэтому ничего
дополнительно не устанавливается и не запускается. Сам индекс документации — облачный сервис
Context7. Если нужен поиск по документации, который никогда не покидает компьютер, вместо него можно
добавить самостоятельно размещаемый MCP-сервер документации со вкладки **MCP** каталога.

---

## Граф кода

> Подключите к нему агента — и он будет находить код по структуре: кто вызывает функцию, что она вызывает, где объявлен символ, — вместо grep и чтения файла за файлом.

Source: https://docs.neurosquad.ai/ru/plugins/code-graph

Чтобы ответить «что вызывает `processOrder`?», агент обычно запускает grep, открывает файл, снова
grep, открывает следующий — и тратит тысячи токенов на код, который ему не нужен. Плагин **Граф кода**
индексирует код воркспейса в граф знаний — функции, классы, методы, вызовы, импорты, маршруты — с
помощью [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp), открытого движка от
DeusData. Подключённый агент спрашивает граф и получает ответ одним вызовом.

### Как пользоваться

1. В меню добавления карточки выберите **Плагин…**, откройте **Граф кода** на вкладке **Плагины** и
нажмите **Добавить на канвас**.
2. Нажмите **Скачать** на карточке. NeuroSquad скачает официальную сборку codebase-memory-mcp с
GitHub (около 40 МБ, около 300 МБ после распаковки) и сверит её с контрольной суммой, зашитой в
приложение, — несовпадающий файл удаляется. Это нужно один раз.
3. Нажмите **Построить граф**. Большинству проектов хватает секунд, очень большому — нескольких
минут.
4. Проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к карточке.

Теперь у агента есть инструменты графа. Большинство CLI подхватывают их без перезапуска; уберите
стрелку — и они пропадут.

### Что умеет агент

| Инструмент | На что отвечает |
| --- | --- |
| `codegraph_search_graph` | Найти функции, классы и другие символы по имени, шаблону или смыслу |
| `codegraph_trace_path` | Кто вызывает функцию и что вызывает она — на несколько шагов вглубь |
| `codegraph_get_code_snippet` | Исходник одного символа, не открывая весь файл |
| `codegraph_query_graph` | Запросы Cypher (только чтение) для многошаговых вопросов |
| `codegraph_get_architecture` | Языки, пакеты, точки входа, маршруты, горячие места |
| `codegraph_search_code` | Текстовый поиск, ранжированный по графу |
| `codegraph_get_file_outline` | Всё, что объявлено в одном файле |
| `codegraph_detect_changes` | Какие символы задевают ваши незакоммиченные изменения |
| `codegraph_get_graph_schema`, `codegraph_index_status`, `codegraph_check_index_coverage` | Что в графе и насколько он полон |
| `codegraph_reindex` | Переиндексировать сейчас, сразу после правок |

Можно просто попросить: «найди через граф кода всё, что вызывает `validateOrder`».

### Карточка

- **Главное** — сколько символов в графе, сколько файлов, вызовов и связей и актуален ли он.
- **Поиск** — введите имя и посмотрите, где оно объявлено.
- **Что внутри** — функции, интерфейсы, классы, типы и языки проекта.
- **Кто пользуется** — подключённые агенты и их последний вызов графа.

### Всегда актуален

С включённым **Автообновлением** (по умолчанию) карточка замечает изменения файлов и через несколько
секунд переиндексирует — только изменённое, поэтому быстро. Ещё она обновляет граф, когда
подключённый агент заканчивает ход. Выключите — и обновляйте вручную кнопкой **Обновить**.

> Граф строится по папке воркспейса. Агент в изолированном worktree всё равно спрашивает граф основной
> папки.

### Воркспейсы в WSL и по SSH

Для воркспейса внутри WSL или на SSH-хосте движок работает **там**, рядом с кодом. Карточка
показывает где — **WSL · Ubuntu** или **SSH · ваш хост**:

- **Скачать** загружает Linux-сборку движка (x86-64 или ARM64 — по процессору хоста) и проверяет
её здесь; первая **Построить граф** копирует её в собственную папку NeuroSquad на той стороне
(`~/.neurosquad`), проверяет ещё раз и распаковывает там — один раз на дистрибутив или хост.
- Граф тоже лежит в этой папке. В проект и в остальную домашнюю папку там ничего не пишется, а код
не приходит на этот компьютер: агенты получают ответы на свои запросы.
- Актуальность: для проекта WSL на диске Windows (`/mnt/c/…`) карточка следит за файлами как обычно;
в остальных случаях обновляет граф после хода подключённого агента и по кнопке **Обновить**.
- Удаление карточки (или воркспейса) удаляет граф на той стороне; выход из NeuroSquad останавливает
движок там.

Движок работает только на Linux: для SSH-хоста на macOS карточка скажет «Для этого хоста нет сборки
движка».

### Приватность и хранение

Всё работает на вашем компьютере. codebase-memory-mcp ничего никуда не отправляет — ни аккаунта, ни
телеметрии, код не покидает машину. Движок и граф лежат в папке данных NeuroSquad: в проект и в
домашнюю папку ничего не пишется, а если у вас установлен свой codebase-memory-mcp, он продолжает
работать отдельно. Удалите карточку — удалится и её граф.

codebase-memory-mcp создан DeusData и распространяется по лицензии MIT.

---

## Graphify

> Живая карта структуры вашего кода. Подключённые агенты задают ей структурные вопросы вместо grep, а каждый запрос подсвечивается на карте в момент, когда он идёт.

Source: https://docs.neurosquad.ai/ru/plugins/graphify

Вопросы вроде «как запрос доходит до базы данных?» или «что сломается, если поменять `parseConfig`?»
обычно стоят агенту длинной цепочки grep и чтения файлов. Плагин **Graphify** превращает
воркспейс в граф знаний с помощью [graphify](https://github.com/Graphify-Labs/graphify) —
открытого инструмента Graphify-Labs: файлы, функции, классы, вызовы, импорты, разделы Markdown и
комментарии `NOTE:` / `WHY:`, сгруппированные в подсистемы. Подключённый агент спрашивает граф
словами или по имени символа и за один вызов получает нужную часть графа — с файлом и строкой для
каждого результата.

Карточка рисует граф картой, и каждый запрос агента проигрывается на ней вживую: видно, что агент
спросил, с каких узлов начал, как расходился поиск и что нашёл.

### Как пользоваться

1. В меню добавления карточек выберите **Плагин…**, откройте **Graphify** на вкладке **Плагины** и
нажмите **Добавить на канвас**.
2. Нажмите **Установить** на карточке (один раз на компьютер). NeuroSquad скачивает
[uv](https://github.com/astral-sh/uv) 0.12.22 с GitHub и сверяет его с контрольной суммой,
зашитой в приложение; uv ставит собственный Python 3.12, затем устанавливает graphify 0.9.74 с
PyPI, где каждый пакет закреплён по хешу (`--require-hashes`, только готовые бинарные пакеты).
Около 250 МБ, всё в папке данных приложения. Ваши собственные настройки Python, uv и pip не
используются и не меняются.
3. Затем карточка сама строит граф **всего воркспейса**. Видно, сколько файлов уже прочитано,
сколько всего и сколько примерно осталось.
4. Проведите [стрелку](https://docs.neurosquad.ai/ru/canvas/arrows) от агента к карточке.

Теперь у агента есть инструменты графа. Большинство CLI подхватывают их без перезапуска; уберите
стрелку — и они пропадут.

### Что может агент

| Инструмент | На что отвечает |
| --- | --- |
| `graphify_query` | Вопрос словами или именами символов → нужный подграф (символы, файлы со строками, связи вызовов и импортов) |
| `graphify_neighbors` | Всё, что символ вызывает, кто его вызывает, что он импортирует и кто импортирует его, с файлом и строкой каждого использования |
| `graphify_path` | Кратчайшая цепочка вызовов и импортов между двумя местами |
| `graphify_affected` | Радиус изменения: всё, что зависит от символа или файла, транзитивно |
| `graphify_node` | Где находится символ, его тип и подсистема |
| `graphify_community` | Все участники одной подсистемы |
| `graphify_god_nodes` | Самые связанные символы — ядро кодовой базы |
| `graphify_stats` | Размер графа и сколько связей прочитано прямо из кода |
| `graphify_reindex` | Обновить граф сейчас, после только что сделанных правок |

Пока первая сборка идёт, инструменты отвечают, сколько осталось («граф ещё строится: 37%, 170 из
461 файла…»), — агент продолжает обычным поиском и спрашивает снова позже.

### Как агентов направляют к графу

Агент, у которого есть инструмент графа, пользуется им не всегда: модели привыкли к grep. Graphify
добавляет три лёгких слоя, ни один из которых ничего не блокирует:

- **Описания инструментов** говорят, когда граф лучше («используйте до grep, если вопрос о
структуре»), а когда по-прежнему нужен текстовый поиск (строковые литералы, сообщения в логах,
значения конфигов). В Claude Code `graphify_query`, `graphify_neighbors` и `graphify_affected`
загружены всегда, а не спрятаны за поиском инструментов.
- **Заметка в первом ходе.** Первый ход сессии со стрелкой несёт одну короткую фактическую
заметку: что такое граф, какой инструмент на какой вопрос отвечает и когда grep всё ещё уместен.
Следующие ходы получают однострочное напоминание, если запрос про структуру кода (и каждый пятый
ход в любом случае). Когда вы убираете стрелку, следующий ход получает одну заметку о том, что
инструментов больше нет. Claude Code, Codex и Qwen Code получают её через хук промпта; OpenCode,
Kilo Code, pi, omp и Gemini CLI — через плагин, расширение или мост хуков NeuroSquad. Остальные
CLI получают только инструменты.
- **Подсказка перед текстовым поиском (Claude Code).** Когда агент собирается выполнить `Grep`,
`Glob` или команду `grep` / `rg` / `find` по тому, что похоже на имя символа, он получает одну
строку контекста с отсылкой к `graphify_neighbors` и `graphify_query`. Поиск всё равно
выполняется как просили: решение о разрешении не принимается, ваши правила allow и deny и запросы
подтверждения работают как раньше. Подсказка молчит две минуты после обращения агента к графу и
приходит не чаще раза в 45 секунд и раза в четыре поиска.

Выключите **Направлять агентов к графу** в настройках карточки, чтобы оставить только инструменты.

### Карта

- **Файлы** — точки, размер которых зависит от содержимого, а цвет — от подсистемы. Приблизьте
карту (или нажмите **Показать символы**), чтобы увидеть функции и классы вокруг каждого файла.
- **Запросы вживую.** Когда агент спрашивает граф, его стартовые узлы расходятся кругами, поиск
распространяется шаг за шагом вдоль пройденных связей, а панель результатов показывает находки с
файлом и строкой. Нажмите на результат, чтобы навести на него карту, или откройте файл в
редакторе.
- **Лента** внизу: недавние запросы и кто их задал. Нажмите на запрос, чтобы проиграть его снова.
- **Поиск** по графу — в поле в углу; совпадения подсвечиваются так же.
- **Нажмите на узел**, чтобы увидеть его детали и связи; **Вписать карту** возвращает всё в кадр.
- **Разверните** карточку, чтобы посмотреть карту крупно.

Перетаскивайте карту мышью, масштабируйте колесом; анимации карты ставятся на паузу, пока вы
масштабируете канвас или карточка вне экрана.

### Всегда актуален

С включённым **Автообновлением** (по умолчанию) карточка замечает изменённые файлы и обновляет граф
примерно через 4 секунды после последнего изменения. Ещё она обновляется после хода подключённого
агента и один раз при открытии приложения. graphify хранит кеш каждого прочитанного файла, так что
при обновлении перечитывается только изменённое. Выключите, чтобы обновлять вручную кнопкой
**Обновить**.

### Настройки

Кнопка настроек в шапке карточки:

- **Автообновление** и **Направлять агентов к графу** (см. выше).
- **Языки**: исключить из графа целые языки.
- **Дополнительно игнорировать**: шаблоны по одному на строку, синтаксис `.gitignore`. Файлы
`.gitignore` и `.graphifyignore` проекта учитываются всегда.
- **Включать файлы из .gitignore**: для сгенерированного кода, которому место в графе.

Изменение того, что индексируется, перестраивает граф.

### Воркспейсы в WSL и по SSH

- **WSL**: graphify работает в Windows и читает файлы дистрибутива через их путь в Windows. Для
проекта на диске Windows (`/mnt/c/…`) карточка следит за файлами как обычно; для проекта на
собственном диске дистрибутива она обновляется после хода подключённого агента и по кнопке
**Обновить**.
- **SSH**: не поддерживается, карточка так и говорит. Используйте плагин
[Граф кода](https://docs.neurosquad.ai/ru/plugins/code-graph) — он запускает свой движок на SSH-хосте.

### Graphify или Граф кода?

Оба индексируют код, но хорошо отвечают на разные вопросы — их можно использовать вместе.

| | Граф кода | Graphify |
| --- | --- | --- |
| Сильная сторона | Точная навигация: вызывающие и вызываемые, фрагменты кода, Cypher только для чтения, смысловой поиск | Вопросы словами → нужный подграф, как всё связано, что затронет изменение |
| Дополнительно | Маршруты, пакеты | Подсистемы, разделы Markdown, комментарии `NOTE:` / `WHY:` |
| На карточке | Статистика индекса и поиск | Живая карта с анимацией каждого запроса |
| WSL / SSH | Работает внутри WSL и на SSH-хостах | WSL через пути Windows; SSH нет |

> Граф строится по папке воркспейса. Агент, работающий в изолированном worktree, всё равно
> обращается к графу основной папки.

### Приватность и хранение

Всё работает на вашем компьютере. Graphify читает только код (никаких документов, изображений и
прочего, для чего понадобилась бы языковая модель), языковые модели не используются, ключи API в
него не передаются. У graphify нет телеметрии, а его необязательный журнал запросов выключен.
Движок лежит в папке данных приложения, каждый граф — в `graphify/projects/<папка>-<хеш>/` там же.
В ваш проект и домашнюю папку ничего не пишется. Удаление последней карточки папки удаляет её граф.

graphify создан Graphify-Labs и распространяется по лицензии Apache License 2.0.

### Решение проблем

- **Установка не проходит через прокси.** uv берёт `HTTPS_PROXY` / `HTTP_PROXY` из окружения
приложения; задайте переменную до запуска NeuroSquad и снова нажмите **Установить**.
- **Установка падает с «no matching distribution».** Для одного из пакетов нет готовой бинарной
сборки под вашу систему; из исходников graphify не собирается. Карточка показывает сообщение uv.
- **«Граф ещё строится».** Первая сборка очень большого воркспейса занимает время; карточка
показывает прогресс. Агенты на свои вопросы получают тот же прогресс.
- **Агент продолжает пользоваться grep.** Проверьте, что стрелка на месте, что **Направлять агентов
к графу** включено и что CLI агента из тех, кто получает подсказки (остальных карточка помечает
«только инструменты»). Можно и попросить прямо: «найди через graphify…».
- **Карта пустая или в ней не хватает файлов.** Проверьте **Языки** и **Дополнительно
игнорировать** в настройках, а также `.gitignore` проекта.
- **Карточка пишет, что SSH не поддерживается.** Для SSH-воркспейсов используйте плагин «Граф
кода».

---

## Настройки

> Что можно изменить в настройках NeuroSquad, раздел за разделом.

Source: https://docs.neurosquad.ai/ru/settings

Откройте **Settings** внизу сайдбара. Изменения применяются сразу.

  - **Language (язык)**: English, Русский или 中文 — язык всего приложения. Переключается мгновенно; пока вы его не выбрали, NeuroSquad следует языку системы.
  - **General (общие)**: **Auto-reconnect** — автоматически перезапускать агента, если он неожиданно завершился. Включено по умолчанию.
  - **System (система)**: **Keep agents running when the window is closed** — закрытие окна прячет NeuroSquad в системный трей, а не завершает его, так что агенты продолжают работать и по-прежнему присылают уведомления. Выключено по умолчанию.
  - **Notifications (уведомления)**: **Sound** (Chime, Ping или Marimba), **Highlight** (и её цвет), **System notifications** и необязательный **Webhook** для Slack или Discord. См. [Закончил / ждёт вашего ответа](https://docs.neurosquad.ai/ru/agents/notifications).
  - **Dictation (диктовка)**: Модель распознавания речи, процессор или видеокарта, **Dictation shortcut** (горячая клавиша) и **Overlay position** — где появляется капсула записи. См. [Диктовка](https://docs.neurosquad.ai/ru/dictation).
  - **Canvas (холст)**: **Card overview when zoomed out** и масштаб, на котором он включается, **Alignment guides**, **Snap to grid**, **Minimap** и **Agent mascots**. См. [Инструменты холста](https://docs.neurosquad.ai/ru/canvas/tools).
  - **Browser (браузер)**: Какой браузер используют карточки браузера — Chrome (по умолчанию) или Firefox, — а также его загрузка и удаление.
  - **Harnesses (харнессы)**: Какие ИИ-агенты NeuroSquad нашёл на вашем компьютере. Установили нового? Нажмите **Check again**.
  - **Setup (установка)**: Те же шаги, что и в мастере первого запуска: установка агента, Git или модели распознавания речи.
  - **Providers (провайдеры)**: Ваш ключ OpenRouter, сколько вы потратили, и каталог моделей. См. [Провайдеры моделей](https://docs.neurosquad.ai/ru/providers).
  - **Remote access (удалённый доступ)**: Удалённый доступ с телефона — ссылка для подключения, порт, сетевой адрес, интернет-туннель. См. [Удалённый доступ](https://docs.neurosquad.ai/ru/remote).
  - **Shortcuts (горячие клавиши)**: Список горячих клавиш (`Ctrl Shift /`). См. [Горячие клавиши](https://docs.neurosquad.ai/ru/help/shortcuts).

### Что настраивается в других местах

- **Опасный режим** и **режим карточек** — для каждого агента отдельно, в меню ⋯ его карточки.
- **Размер текста в терминале** — `Ctrl` + прокрутка над любым терминалом.
- **Команда настройки, файлы для копирования, команда запуска, файл инструкций** — в окне правки
каждого воркспейса.

---

## Card SDK

> Делайте свои карточки для холста NeuroSquad — небольшие веб-приложения, которые следят за агентами и дают им указания, обмениваются данными по стрелкам и дают агентам новые инструменты, — и делитесь ими через GitHub.

Source: https://docs.neurosquad.ai/ru/card-sdk

**Своя карточка** — это небольшое веб-приложение, которое живёт на холсте рядом с вашими агентами,
терминалами и заметками. Сделать такую может кто угодно с помощью Card SDK (`@neurosquad/card-sdk`),
выложить на GitHub — а любой другой поставит её, вставив в NeuroSquad адрес `owner/repo`.

Этот раздел для двух читателей:

- **Для всех**, кто хочет пользоваться карточкой, сделанной кем-то другим, — начните с
[Установки карточек сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards). Там объяснено, что карточка может и
чего не может, что говорит диалог установки и как забрать доступ обратно.
- **Для разработчиков**, которые хотят сделать свою, — начните с [Быстрого старта](https://docs.neurosquad.ai/ru/card-sdk/quick-start):
рабочая карточка на вашем холсте за несколько минут.

### Что умеет карточка

Своя карточка — полноправный житель холста: у неё такая же шапка, она меняет размер, входит в
[группы](https://docs.neurosquad.ai/ru/canvas/groups), принимает [стрелки](https://docs.neurosquad.ai/ru/canvas/arrows), показывает плитку при отдалении и
лежит в сайдбаре, как любая другая карточка. Внутри своей коробки она рисует что угодно. Через SDK
она может:

  - **Следить за агентами**: Кто работает, кто ждёт вас, когда ход начался и закончился — а если вы её подключите, то и что агент выводит на экран.
  - **Давать указания агентам**: Отправить промпт агенту, к которому вы её подключили. Пока агент работает, промпты встают в очередь и учитывают бюджет воркспейса.
  - **Общаться с другими карточками**: Типизированные порты по стрелкам: карточка может дописать заметку, добавить задачи в список или передать данные другой своей карточке.
  - **Давать агентам инструменты**: Объявите инструмент и реализуйте его в карточке — подключённые агенты вызовут его через MCP-сервер приложения.
  - **Ходить в интернет**: Запросы к объявленным хостам — через прокси приложения и с секретами, которых карточка никогда не видит.
  - **Работать с файлами проекта**: Читать и писать файлы в папке воркспейса, если вы разрешите.
  - **Запускать команды**: Выполнить команду в подключённом терминале и получить код выхода и вывод.
  - **Настройки и хранилище**: Форма настроек, которую рисует приложение, хранилище карточки, переживающее перезапуски, тема и язык приложения.

### Карточки никогда не покидают холст

Коду сообщества не доверяют по умолчанию, поэтому карточка работает **запертой в своей коробке**:

- Она работает в отдельном изолированном процессе. Зависшая или упавшая карточка не может
заморозить холст или утянуть что-то за собой.
- Сама по себе она не может добраться ни до приложения, ни до ваших других карточек, ни до Node.js,
ваших файлов, cookies или интернета. Всё идёт через SDK, и приложение сверяет каждый запрос с тем,
что вы разрешили.
- Она не может открывать окна и всплывающие окна, уходить в полноэкранный режим, показывать
системные диалоги, присылать уведомления ОС, скачивать файлы или уводить приложение на другую
страницу. Она рисует только внутри своей карточки.
- Когда от вас нужно решение — подтверждение, ссылка, разрешение, промпт агенту в опасном режиме,
секрет вроде API-ключа, — спрашивает **приложение**, в своём собственном диалоге, который
**затемняет всё окно**, включая сайдбар и заголовок. Карточка не может рисовать за пределами своей
коробки, поэтому подделать такой диалог ей не удастся. Всё, что внутри тела карточки, принадлежит
самой карточке: NeuroSquad никогда не спрашивает там ключи.

### Модель безопасности простыми словами

  - **Что ей можно — решаете вы**: Карточка перечисляет нужные ей [разрешения](https://docs.neurosquad.ai/ru/card-sdk/permissions). Вы видите их — сначала самые рискованные — ещё до установки. Карточка без разрешений может только рисовать в своей коробке.
  - **Стрелка — это согласие**: Всё, что доходит до другой карточки или агента, — данные через порт, промпт, команда, чтение экрана, — требует стрелки между двумя карточками **и** соответствующего разрешения. Нет стрелки — нет данных.
  - **Привязка к коммиту**: Установка — это этот репозиторий на этом конкретном коммите, причём коммите самого репозитория, а не форка. За вашей спиной ничего не меняется: обновления никогда не ставятся сами, а обновление, которому нужно больше доступа или которое меняет то, что карточка даёт агентам, спрашивает вас снова.
  - **Секреты остаются в приложении**: API-ключи вводятся только в собственном диалоге приложения, хранятся в зашифрованном виде, и приложение само подставляет их в запросы к тем адресам в интернете, которые вы разрешили. Сама карточка их никогда не видит.
  - **Некоторые файлы недоступны**: Даже с доступом к файлам карточка никогда не может менять `.git`, настройки и инструкции ваших агентов (`.claude/`, `.mcp.json`, `CLAUDE.md`, `AGENTS.md`…) и CI-процессы — а если воркспейс — это ваша домашняя папка или целый диск, доступа к файлам у неё нет вообще.
  - **Всё на виду**: Промпт или вызов инструмента через карточку подсвечивает стрелку, по которой он прошёл, и попадает в [журнал стрелки](https://docs.neurosquad.ai/ru/canvas/arrows#arrow-log) с именем карточки.

> Карточки сообщества не делает и не проверяет команда NeuroSquad. Ставьте карточки от тех, кому
> доверяете, и читайте список разрешений: карточка, которой можно давать указания агентам или
> запускать команды, может всё, что могут эти агенты и терминалы.

### В этом разделе

  - **[Установка карточек сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards)**: Для пользователей: установить, проверить, отозвать, обновить и удалить.
  - **[Быстрый старт](https://docs.neurosquad.ai/ru/card-sdk/quick-start)**: От пустой папки до карточки на холсте и на GitHub.
  - **[Справочник по манифесту](https://docs.neurosquad.ai/ru/card-sdk/manifest)**: Каждое поле `neurosquad-card.json`.
  - **[Разрешения](https://docs.neurosquad.ai/ru/card-sdk/permissions)**: Каждое: что видит пользователь, что оно открывает.
  - **[Справочник API](https://docs.neurosquad.ai/ru/card-sdk/api)**: Все методы и события, с типами и примерами.
  - **[React-привязки](https://docs.neurosquad.ai/ru/card-sdk/react)**: `CardProvider` и хуки.
  - **[UI-кит и оформление](https://docs.neurosquad.ai/ru/card-sdk/styling)**: Выглядеть как родная — или по-своему.
  - **[Тесты](https://docs.neurosquad.ai/ru/card-sdk/testing)**: Хост в памяти для тестов и превью в браузере.
  - **[Справочник CLI](https://docs.neurosquad.ai/ru/card-sdk/cli)**: `create`, `dev`, `validate`, `pack`.
  - **[Публикация и обновления](https://docs.neurosquad.ai/ru/card-sdk/publishing)**: GitHub, версии, что видят пользователи при обновлении.
  - **[Чек-лист безопасности](https://docs.neurosquad.ai/ru/card-sdk/security)**: Что проверить, прежде чем делиться карточкой.
  - **[Вопросы и решение проблем](https://docs.neurosquad.ai/ru/card-sdk/faq)**: Частые ошибки и как их исправить.

> Card SDK — новинка. Всё здесь описывает версию 1 протокола карточек; кое-что сознательно отложено
> на потом — галерея карточек, автоматические обновления, карточки, работающие вовсе без страницы,
> выбор файла и запуск кода карточек на телефоне. Об этом сказано там, где это важно.

---

## Установка карточек сообщества

> Что такое карточка сообщества, как поставить её с GitHub, как читать диалог разрешений и как её обновить, выключить, отозвать доступ или удалить.

Source: https://docs.neurosquad.ai/ru/card-sdk/community-cards

Карточки сообщества — это карточки, которые другие люди сделали с помощью [Card SDK](https://docs.neurosquad.ai/ru/card-sdk) и
выложили на GitHub. Они живут в **Settings → Custom cards**, а после установки добавляются на холст
как любая другая карточка.

### Установить карточку

**1. Откройте Settings → Custom cards**

В блоке **Install a card** вставьте адрес на GitHub, который вам дали. Подойдёт любой из вариантов:
`owner/repo`, `owner/repo@v1.2.0` (тег, ветка или коммит), `owner/repo/cards/pomodoro` (карточка в
подпапке) или полная ссылка `https://github.com/…` — в том числе вида `/tree/<branch>/<folder>` или
`/releases/tag/<tag>`.

**2. Нажмите Install и прочитайте диалог**

NeuroSquad скачивает именно этот коммит, проверяет его и показывает, что это за карточка и что она
собирается делать. Пока ничего не установлено.

**3. Нажмите Install в диалоге**

Или **Cancel** — тогда скачанное выбрасывается.

**4. Добавьте её на холст**

В меню добавления (**+** на холсте или в сайдбаре) выберите **Custom card…** и нужную карточку.
Копий можно добавить сколько угодно; у каждой свои настройки и данные.

> Нужны карточки, которые уже кто-то проверил? В списке [проверенных карточек](https://docs.neurosquad.ai/ru/card-sdk/verified-cards)
> — карточки сообщества, которые просмотрела команда NeuroSquad; их можно поставить со вкладки
> **Verified** в окне **Custom card…**.

### Как читать диалог установки

  - **Имя, автор, версия**: Автор указан **со слов самой карточки** (self-declared) — карточка говорит, кто её сделал, никто это не проверял. Доверяйте адресу репозитория, а не имени. Называть себя «NeuroSquad», «official» или «verified» могут только официальные карточки; любую другую, которая попробует, приложение не установит.
  - **Источник и коммит**: Репозиторий на GitHub и конкретный коммит, который будет установлен, с кнопкой **View source**, чтобы прочитать этот код. Установка привязана к этому коммиту, и коммит должен принадлежать самому репозиторию (лежать в его ветке по умолчанию): коммит, который есть только в форке, отклоняется. Переименованный или перенесённый репозиторий нужно ставить под новым именем.
  - **Community или Official**: Каждая карточка помечена **Community code, not made or checked by NeuroSquad** («код сообщества, NeuroSquad его не писал и не проверял») — кроме карточек, которые команда NeuroSquad публикует из организации `glmn-ai` на GitHub (проверяется по идентификатору аккаунта в самом GitHub, а не только по имени): у них значок **Official**.
  - **This card will be able to**: Нужные ей [разрешения](https://docs.neurosquad.ai/ru/card-sdk/permissions) — **сначала высокий риск**, и показаны они раньше собственного описания карточки, каждое с понятным объяснением и часто с причиной от автора. Они даются целиком: чтобы поставить карточку, вы выдаёте их все.
  - **It may ask later for**: Необязательные разрешения. При установке они **не** выдаются; карточка попросит их на экране, когда понадобится, и вы можете отказать.
  - **Инструменты и порты**: Инструменты, которые она даёт подключённым к ней агентам, и сколько у неё портов данных для стрелок.

> Больше всего внимания — строкам **High risk**. Карточка, которой можно **давать указания агентам**
> или **запускать команды в терминалах**, может всё, что могут эти агенты и терминалы: править ваш
> код, удалять файлы, пушить в git. Карточка, которая **читает файлы** и может ходить **на любой
> адрес в сети**, может отправить туда файлы вашего проекта.

### Чего карточка не может никогда

Что бы она ни просила, карточка работает запертой в своей коробке. Она не может открывать окна,
напрямую обращаться к приложению или другим карточкам, читать ваши файлы или выходить в сеть сверх
того, что вы разрешили, показывать системные уведомления или рисовать за пределами своей карточки.
Приложение проверяет каждый запрос карточки, при каждом вызове. См.
[Карточки никогда не покидают холст](https://docs.neurosquad.ai/ru/card-sdk#cards-never-leave-the-canvas).

**Настоящий запрос NeuroSquad затемняет всё окно.** Когда от вас нужно решение — подтверждение,
ссылка, разрешение, промпт агенту в опасном режиме, секретный ключ, — приложение спрашивает в своём
собственном диалоге с заголовком **NeuroSquad is asking** («NeuroSquad спрашивает») поверх фона,
который затемняет и сайдбар, и заголовок окна. Карточка может рисовать только внутри своей коробки,
поэтому подделать это не может. Слова самой карточки появляются в таком диалоге только как цитата, а
**Cancel** всегда принадлежит приложению.

**Всё, что внутри тела карточки, принадлежит самой карточке.** Сам NeuroSquad никогда не спрашивает
пароли или API-ключи внутри карточки. Если карточке нужен ключ, его вводят через **Settings…**
карточки (секретное поле открывает диалог приложения) — ключ хранится в зашифрованном виде,
отправляется только на разрешённые вами адреса в интернете, и карточка его никогда не видит.

**Настройки ваших агентов и репозиторий защищены.** Даже карточка, которой можно менять файлы, не
может трогать `.git`, настройки и инструкции агентов (`.claude/`, `.codex/`, `.cursor/`,
`.mcp.json`, `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `QWEN.md`…), настройки редактора и CI
(`.vscode/`, `.idea/`, `.github/workflows/`, `.husky/`…) и настройки пакетных менеджеров (`.npmrc`,
`.yarnrc`…). А если папка воркспейса — это ваша домашняя папка, корень диска или в ней лежат данные
самого NeuroSquad, доступа к файлам не получает ни одна карточка.

### Как пользоваться карточкой

- **Стрелки.** Большинство карточек умеют больше, когда их подключают. Стрелка между карточкой и
агентом позволяет карточке смотреть на экран агента или отправлять ему промпты (если у неё есть
эти разрешения), а агенту — вызывать инструменты карточки. Стрелка между двумя карточками пускает
данные через их порты — от начала стрелки к её концу.
- **Settings…** в меню **⋯** карточки открывает её настройки, если они есть. Некоторые общие для
всех копий этой карточки (в форме это помечено).
- **Промпт агенту в опасном режиме** всегда требует вашего согласия: приложение показывает, что
карточка хочет отправить, а вы нажимаете **Send prompt** или **Cancel**. Промпты, которые карточка
поставила в очередь агента, выбрасываются, если вы уберёте стрелку, отзовёте разрешение или
переведёте агента в опасный режим; очередь показывает, от какой карточки пришёл каждый.
- **Ссылки**, которые карточка хочет открыть, сначала показываются целиком; только `https://` и
только после нажатия **Open link**.
- **Лимиты.** Карточка может отправить не больше 6 промптов и 30 команд терминала в минуту, каким бы
способом она их ни отправляла.
- **Внимание.** Карточка может пульсировать и появляться во входящих (Inbox), когда вы ей нужны, —
как ждущий агент. Звуков и уведомлений ОС она подавать не может.
- **Карточки на паузе.** Карточка, на которую вы давно не смотрели (её воркспейс скрыт больше
минуты или открыто слишком много карточек), ставится на паузу ради памяти и продолжает с того же
места. Карточки с разрешением **Keep running when you are not looking** на паузу не ставятся.

### Обновления

NeuroSquad проверяет новые версии через минуту после запуска, а потом раз в день (или когда вы
нажимаете **Check for updates**). Карточка, установленная с ветки, обновляется до её свежего коммита;
установленная из релиза — следит за последним релизом; привязанная к тегу или коммиту не обновляется
никогда.

**Ничего не обновляется само.** Доступное обновление видно как **Update** в **Settings → Custom
cards** и как точка на карточке. Нажатие показывает, что меняется: **новые разрешения**, **новые
адреса, к которым она будет подключаться**, разрешения, которые ей **больше не нужны**, и изменения
в том, что она предлагает: новые или переформулированные **инструменты** для агентов, новые порты
или порты с другим типом (**ports**), новые **секретные настройки**, изменённые **имя, автор или
домашняя страница**, — со ссылкой на изменения кода на GitHub. Если обновлению нужно что-то из этого,
оно ждёт вашего согласия; до тех пор работает старая версия.

### Выключить, отозвать, удалить

В **Settings → Custom cards** у каждой установленной карточки есть:

- переключатель **Turned on** — выключенная карточка останавливает все свои копии (на них написано
«This card is turned off»), её инструменты пропадают у агентов, ничего не удаляется;
- **Permissions** — нажмите **Revoke** рядом с любым разрешением, чтобы забрать его. Карточки этого
пакета перезагрузятся без него;
- **Uninstall** — удаляет пакет. Вы выбираете, **удалить ли и её карточки со всех холстов** (по
умолчанию да; иначе они остаются заглушками «package missing») и **удалить ли её сохранённые данные
и секреты** (по умолчанию нет).

### Приватные репозитории и лимиты GitHub

GitHub ограничивает, как часто можно скачивать без аккаунта. Если установка или проверка обновлений
говорит, что GitHub ограничивает запросы, — или вы хотите ставить из приватного репозитория, —
добавьте **GitHub token** в **Settings → Custom cards**. Он хранится в зашифрованном виде и никогда
не показывается карточкам.

### Свои карточки на телефоне

При [удалённом доступе](https://docs.neurosquad.ai/ru/remote) своя карточка показывается на телефоне шапкой и плиткой-сводкой с
надписью «Open on the computer to use this card» («Откройте на компьютере, чтобы пользоваться
карточкой»). Её код работает только на компьютере — инструменты, порты и промпты продолжают работать
там, пока вы смотрите с телефона.

---

## Проверенные карточки

> Список карточек сообщества, которые просмотрела команда NeuroSquad, — где его найти, что значит значок Verified и чего он не значит, как устроены проверенные обновления и как автору отправить карточку на проверку.

Source: https://docs.neurosquad.ai/ru/card-sdk/verified-cards

Выложить [карточку сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards) на GitHub может кто угодно, и до установки
её никто не проверяет. **Проверенные карточки** (verified) — исключение: это карточки сообщества,
которые команда NeuroSquad прочитала и опробовала, каждый раз — одну конкретную версию. Они собраны в
открытом каталоге, и приложение умеет ставить их прямо оттуда.

Каталог — это файл `verified.json` в открытом репозитории
[glmn-ai/neurosquad-cards](https://github.com/glmn-ai/neurosquad-cards). Каждая запись фиксирует, что
именно проверено:

- название и описание карточки (на английском, русском и китайском), автор и лицензия;
- где она лежит — репозиторий на GitHub `owner/repo` и, если нужно, папка внутри него;
- проверенная **версия**, точный проверенный **коммит** и **хеш дерева** (tree hash) папки карточки
на этом коммите;
- разрешения и сетевые адреса, которыми карточка пользуется;
- теги и категория — агенты, продуктивность, инструменты разработчика, данные, интеграции,
развлечения или другое;
- кто проверял, когда и заметки по итогам проверки.

Приложение скачивает список при запуске, каждые 6 часов и по кнопке **Refresh**. Без сети оно
показывает последнюю скачанную копию, а на свежей установке — копию, которая поставляется вместе с
приложением.

### Найти и поставить проверенную карточку

Список есть в двух местах: вкладка **Verified** в окне **Custom card…** из меню добавления (**+** на
холсте или в сайдбаре) и раздел **Verified cards** в **Settings → Custom cards**.

Поиск идёт по названиям на всех трёх языках, описаниям и тегам — прямо на вашем компьютере. Можно
также отфильтровать по категории. В каждой строке — иконка, название, описание, автор, категория и
краткая сводка разрешений, а также кнопка: **Install**, **Installed** или **Verified update**.

**1. Найдите карточку**

Откройте вкладку **Verified** или раздел **Verified cards**, воспользуйтесь поиском или выберите
категорию.

**2. Нажмите Install**

NeuroSquad скачивает **ровно проверенный коммит** — а не самый свежий код в репозитории — и сверяет
хеш дерева файлов с проверенным. Если они не совпадают, установка отклоняется: «файлы отличаются
от того, что проверяли».

**3. Прочитайте диалог разрешений и подтвердите**

Вы увидите тот же [диалог установки](https://docs.neurosquad.ai/ru/card-sdk/community-cards#reading-the-install-dialog), что и
для любой другой карточки. Проверка не отменяет вашего согласия: получит ли карточка то, что
просит, по-прежнему решаете вы.

Любую карточку по-прежнему можно поставить по её адресу на GitHub. Каталог лишь добавляет список
карточек, которые кто-то уже посмотрел.

### Значок Verified

У проверенной карточки есть значок **Verified** — щит с галочкой: в строке каталога, в диалоге
установки, у установленной карточки в **Settings → Custom cards** и в панели **About** самой
карточки.

Это не то же самое, что значок **Official**. Official значит, что карточку публикует команда
NeuroSquad из своей организации `glmn-ai` на GitHub; Verified — что команда проверила эту версию.
У карточки могут быть оба.

Значок показывается, только если с текущей записью списка совпадают все три пункта:

- источник карточки — тот же репозиторий и та же папка;
- коммит, с которого она установлена;
- хеш дерева её файлов — равен проверенному.

Поэтому у карточки, подключённой из локальной папки, установленной с другого коммита (например, с
последнего коммита ветки) или с отличающимися файлами, значка нет — даже если другая её версия
проверена.

> **Verified** значит: проверено командой NeuroSquad в версии X такого-то числа. Это не гарантия,
> что в карточке нет ошибок или что она навсегда останется безопасной, и ничего не говорит о других
> её версиях. Читайте диалог разрешений так же внимательно, как для любой другой карточки.

### Проверенные обновления

Когда список указывает для карточки новую проверенную версию, в **Settings → Custom cards** у неё
появляется **Verified update available**. Нажатие ставит ровно этот проверенный коммит через обычный
[диалог обновления](https://docs.neurosquad.ai/ru/card-sdk/community-cards#updates), который показывает, что меняется в разрешениях
карточки. Сами по себе обновления не ставятся никогда.

Если карточку убрали из списка, значок пропадает, а нейтральная пометка говорит, что её больше нет в
списке проверенных. Карточка остаётся установленной и продолжает работать; оставлять ли её — решать
вам.

### На телефоне

При [удалённом доступе](https://docs.neurosquad.ai/ru/remote) список проверенных карточек можно листать на телефоне, но не ставить
из него: установка возможна только на компьютере.

### Авторам: как пройти проверку

Проверка — это pull request в
[glmn-ai/neurosquad-cards](https://github.com/glmn-ai/neurosquad-cards), который добавляет запись
вашей карточки в `verified.json`. Точные правила и формат записи — в его
[CONTRIBUTING.md](https://github.com/glmn-ai/neurosquad-cards/blob/HEAD/CONTRIBUTING.md); прочитайте
его до того, как открывать pull request.

**4. Опубликуйте карточку**

Она должна лежать в **открытом** репозитории на GitHub, в **ветке по умолчанию**. См.
[Публикация и обновления](https://docs.neurosquad.ai/ru/card-sdk/publishing).

**5. Возьмите коммит и хеш дерева**

Выберите точный коммит, который хотите отдать на проверку. Для хеша дерева запустите
[`neurosquad-card pack`](https://docs.neurosquad.ai/ru/card-sdk/cli#pack) на папке карточки на этом коммите — он печатает хеш
дерева, который приложение записывает при установке.

**6. Откройте pull request**

Добавьте свою запись в `verified.json` — названия и описания, репозиторий и папку, версию, коммит,
хеш дерева, разрешения, сетевые адреса, теги, категорию, лицензию, — как описано в
CONTRIBUTING.md.

**Обновление проверенной карточки** — ещё один pull request, в котором поднимаются версия, коммит и
хеш дерева. Каждая версия проверяется заново; пока новую не приняли, значок у пользователей остаётся на
проверенной версии, а код, запушенный за это время, не предлагается как проверенное обновление.

#### Что смотрят при проверке

- Весь исходный код на этом коммите. Никакого обфусцированного кода и никакого минифицированного
кода без исходников.
- Разрешения и сетевые адреса — минимум того, что нужно карточке, и совпадают с записью.
- Описания её инструментов и портов честные.
- Манифест совпадает с записью — название и версия.
- Хеш дерева воспроизводится.
- У карточки есть лицензия.
- Она ставится и работает в текущей версии приложения.
- Она не выдаёт себя за NeuroSquad или любой другой бренд.
- Она не следит за пользователем сверх того, что объявила.

Большую часть этого покрывает [чек-лист безопасности](https://docs.neurosquad.ai/ru/card-sdk/security) — пройдите его перед
отправкой.

---

## Быстрый старт

> Создайте карточку из шаблона, запустите её вживую в NeuroSquad с горячей перезагрузкой, опубликуйте на GitHub и установите оттуда.

Source: https://docs.neurosquad.ai/ru/card-sdk/quick-start

Нужны NeuroSquad и Node.js 18.17 или новее. Никакого аккаунта разработчика; для простого шаблона — никаких
инструментов сборки.

### 1. Создайте карточку

```bash
npx @neurosquad/card-sdk create my-card                    # plain HTML + JS, no build step
npx @neurosquad/card-sdk create my-card --template react   # React + Vite + TypeScript
```

Оба шаблона дают одну и ту же рабочую карточку: агенты на холсте с живыми статусами, черновик,
который сохраняется в хранилище карточки, входной и выходной [порт](https://docs.neurosquad.ai/ru/card-sdk/api/ports) и
[инструмент](https://docs.neurosquad.ai/ru/card-sdk/api/tools), который могут вызывать подключённые агенты. Прочитайте её, потом
меняйте.

**Простой шаблон** (`vanilla`):

```text
my-card/
  neurosquad-card.json   the manifest: name, size, permissions, settings, ports, tools
  index.html             the page loaded into the card
  main.js                the card's code
  style.css
  icon.png               square PNG or WebP, 128 KB at most
  vendor/                the SDK (card-sdk.js), the UI kit (ui.css), the mock host, the manifest schema
```

**Шаблон React**: тот же манифест и иконка, папка `src/` с `main.tsx`, `App.tsx` и `i18n.ts` и
конфиг Vite, уже настроенный под карточки (относительные URL, никаких встроенных скриптов). Сначала
выполните `npm install`; `npm run build` пишет `dist/` — именно его загружает приложение.

### 2. Посмотрите без приложения

Откройте страницу саму по себе — она заработает на **мок-хосте** с примерами агентов и подключённой
заметкой, так что над внешним видом можно работать в любом браузере:

```bash
npx serve .      # plain template, then open http://localhost:3000
npm run dev      # React template
```

В консоли браузера им управляет `mockHost`: `mockHost.setAgentStatus('a2', 'working')`,
`mockHost.setLanguage('ru')`, `mockHost.sendPortMessage('text', 'hello')`. См.
[Тесты с мок-хостом](https://docs.neurosquad.ai/ru/card-sdk/testing).

### 3. Запустите её вживую в NeuroSquad

**1. Включите режим разработчика**

В NeuroSquad: **Settings → Custom cards → Developer mode**. Он позволяет CLI на этом компьютере
попросить подключить папку; слушает только `127.0.0.1`.

**2. Подключите папку**

В папке карточки выполните `npx @neurosquad/card-sdk dev`. Приложение попросит подтвердить
подключение, а потом покажет тот же диалог разрешений, что увидит пользователь. Примите его.

**3. Добавьте карточку**

На холсте: **+ → Custom card…** и выберите свою карточку (у неё значок **Dev**).

**4. Правьте и сохраняйте**

Каждое сохранение перезагружает карточку. Терминал, где запущен `dev`, печатает журнал карточки —
`card.log.*`, необработанные ошибки и отклонённые промисы. **r** — перезагрузить вручную, **q** —
выйти.

С шаблоном React `dev` ещё и запускает за вас `npm run watch`, так что `dist/` пересобирается при
каждом сохранении. Передайте `--no-build`, чтобы запускать свой наблюдатель.

> Режим разработчика — не обход согласия: подключённая папка получает ровно те разрешения, что
> объявлены в её манифесте, и только после того же диалога. Поменяете разрешения в манифесте —
> карточка спросит снова.

**Без CLI.** Кнопка **Settings → Custom cards → Link a folder…** тоже подключает папку — удобно,
если вы просто хотите попробовать карточку, которую вам прислали папкой.

### 4. Проверьте её так, как проверит установщик

```bash
npx @neurosquad/card-sdk validate
```

`validate` прогоняет собственные проверки манифеста из приложения и правила установщика для файлов,
предупреждает о том, что заблокирует песочница (встроенные скрипты, внешние файлы), и печатает диалог
установки, который увидят ваши пользователи. `pack` идёт на шаг дальше и перечисляет, какие именно
файлы будут установлены, вместе с **хешем дерева**, который записывает приложение. См.
[Справочник CLI](https://docs.neurosquad.ai/ru/card-sdk/cli).

### 5. Опубликуйте на GitHub

Запушьте папку карточки в репозиторий на GitHub — в отдельный или в папку внутри большого. Это и есть
вся публикация. Важно не ошибиться в нескольких вещах:

- `neurosquad-card.json` должен лежать в корне папки карточки.
- **Коммитьте результат сборки.** Приложение ставит прямо из репозитория и никогда ничего не
собирает. В `.gitignore` шаблона React папка `dist/` намеренно не игнорируется.
- Ставьте теги на релизы (`v1.0.0`) — тогда можно установить фиксированную версию или следить за
последним релизом.

Подробнее — в [Публикации и обновлениях](https://docs.neurosquad.ai/ru/card-sdk/publishing).

### 6. Установите её с GitHub

В **Settings → Custom cards → Install a card** вставьте `your-name/my-card` (или
`your-name/my-cards/pomodoro` для карточки из папки `pomodoro` репозитория, `your-name/my-card@v1.0.0`
для тега) и нажмите **Install**. Именно так делают ваши пользователи; см.
[Установку карточек сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards).

### Самая маленькая карточка

Шаблон не нужен. Три файла:

```json filename="neurosquad-card.json"
{
  "manifestVersion": 1,
  "name": "hello-card",
  "displayName": "Hello",
  "version": "0.1.0",
  "protocol": 1
}
```

```html filename="index.html"
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <script type="module" src="main.js"></script>
  </head>
  <body>
    <h1 id="title">…</h1>
  </body>
</html>
```

```js filename="main.js"
// card-sdk.js is dist/card-sdk.js from the @neurosquad/card-sdk package, copied next to this file.
import { connect } from './card-sdk.js'

const card = await connect()
document.getElementById('title').textContent = `Hello from ${card.workspace.name}`
card.setStatus('Ready', { tone: 'success' })
```

Она не просит разрешений, поэтому может только рисовать в своей коробке, пользоваться хранилищем и
настройками и менять свою шапку — и это уже полезная карточка.

### Дальше

  - **[Справочник по манифесту](https://docs.neurosquad.ai/ru/card-sdk/manifest)**: Размер, разрешения, настройки, порты, инструменты.
  - **[Справочник API](https://docs.neurosquad.ai/ru/card-sdk/api)**: Что умеет `card.*`.
  - **[Чек-лист безопасности](https://docs.neurosquad.ai/ru/card-sdk/security)**: Прежде чем делиться.

---

## Справочник по манифесту

> Каждое поле neurosquad-card.json — описание, размер, разрешения, форма настроек, порты и инструменты — и правила, которые проверяет приложение.

Source: https://docs.neurosquad.ai/ru/card-sdk/manifest

У каждой карточки в корне папки лежит `neurosquad-card.json`. Приложение читает его при установке и
отказывается ставить карточку, чей манифест не проходит проверку; `npx @neurosquad/card-sdk validate`
выполняет ровно те же проверки на вашей машине.

Для подсказок в редакторе укажите в `$schema` схему, которая поставляется с SDK:
`./node_modules/@neurosquad/card-sdk/schema/neurosquad-card.v1.json` (шаблон React) или
`./vendor/neurosquad-card.schema.json` (простой шаблон). Она же экспортируется как
`@neurosquad/card-sdk/schema.json`.

### Полный пример

```json
{
  "$schema": "./node_modules/@neurosquad/card-sdk/schema/neurosquad-card.v1.json",
  "manifestVersion": 1,
  "name": "test-radar",
  "displayName": { "en": "Test radar", "ru": "Радар тестов", "zh": "测试雷达" },
  "version": "1.0.0",
  "protocol": 1,
  "description": "Runs the test suite in a connected terminal and shows what broke.",
  "author": { "name": "Acme", "url": "https://acme.dev" },
  "license": "MIT",
  "homepage": "https://acme.dev/test-radar",
  "keywords": ["tests", "ci"],
  "icon": "icon.png",
  "minAppVersion": "0.1.100",
  "entry": "dist/index.html",
  "card": {
    "defaultSize": { "w": 460, "h": 340 },
    "minSize": { "w": 320, "h": 220 }
  },
  "permissions": [
    "agents.read",
    "terminals.write",
    { "id": "fs.read", "reason": "Reads the JUnit report" },
    { "id": "network", "hosts": ["api.github.com"], "reason": "Links failures to GitHub issues" },
    { "id": "clipboard.write", "optional": true }
  ],
  "settings": [
    { "key": "command", "type": "string", "label": "Test command", "default": "npm test" },
    { "key": "githubToken", "type": "secret", "label": "GitHub token", "scope": "package" }
  ],
  "ports": {
    "inputs": [{ "id": "run", "label": "Run", "type": "ns:trigger", "default": true }],
    "outputs": [
      { "id": "failures", "label": "Failures", "type": "ns:tasks", "retain": true },
      { "id": "summary", "label": "Summary", "type": "ns:markdown" }
    ]
  },
  "tools": [
    {
      "name": "run_tests",
      "title": "Run the tests",
      "description": "Runs the project's tests and returns failing test names with messages.",
      "inputSchema": {
        "type": "object",
        "properties": { "filter": { "type": "string", "maxLength": 200 } }
      },
      "timeoutMs": 120000
    }
  ]
}
```

### Описание

| Поле | Обязательно | Правило | Значение |
| --- | --- | --- | --- |
| `$schema` | | строка | Для редактора. Приложение его игнорирует. |
| `manifestVersion` | да | `1` | Формат манифеста. |
| `name` | да | `a-z`, цифры и `-`, начинается с буквы, 2–48 символов | Идентификатор пакета. С него начинаются [имена инструментов](https://docs.neurosquad.ai/ru/card-sdk/api/tools) карточки, и он же — пространство имён её своих типов портов. Зарезервированы (встроенные карточки и семейства инструментов): `neurosquad`, `neurosquad-card`, `custom`, `canvas`, `browser`, `terminal`, `agent`, `note`, `todo`, `kanban`, `host`, `system`, `telegram`, `image`, `reference`, `ports`, `web-watch`, `watch`, `timer`, `sticky`, `standup`, `squad`, `mcp`, `skill`, `official`. |
| `displayName` | да | локализуемый текст, ≤ 80 | Имя карточки в меню, шапке и диалоге установки. |
| `version` | да | SemVer (`1.2.0`, `1.2.0-beta.1`) | Для информации — установка привязана к коммиту, а не к версии. Но всё равно повышайте её: пользователи видят её при обновлении. |
| `protocol` | да | целое число | Протокол карточек, под который вы писали, — сегодня `1`. Карточку под более новый протокол, чем знает приложение, оно откажется ставить с сообщением «нужен более новый NeuroSquad». |
| `description` | | локализуемый текст, ≤ 300 | Показывается в диалоге установки и в выборе карточек. |
| `author` | | `{ "name", "url"? }` | `url` должен быть `https://`. Показывается как **указанный самим автором** (self-declared). |
| `license` | | строка ≤ 100 | Идентификатор SPDX, например `MIT`. |
| `homepage` | | URL `https://` | |
| `keywords` | | ≤ 20 уникальных строк, до 40 символов каждая | |
| `icon` | | путь к `.png` или `.webp` в пакете | Квадратная, ≤ 128 КБ (от 128×128 выглядит чётко). Проверяется по содержимому при установке. Без иконки у карточки будет кусочек пазла. |
| `minAppVersion` | | SemVer | Минимальная версия NeuroSquad, в которой карточка работает. |
| `entry` | | путь к файлу `.html`, по умолчанию `index.html` | Страница, которая загружается в карточку. |

**Локализуемый текст** — это либо обычная строка, либо объект, где обязателен английский:
`{ "en": "Test radar", "ru": "Радар тестов", "zh": "测试雷达" }`. Приложение показывает язык
пользователя, а если его нет — английский.

**Правила для текста.** В именах, описаниях, подписях, причинах и описаниях инструментов нельзя
использовать управляющие символы (табуляция и перевод строки в описаниях допустимы), переопределения
и изоляцию направления текста (bidi), разделители строк, символы нулевой ширины и другие невидимые
символы. Называть себя «NeuroSquad», «official» или «verified» в `displayName` или `author` могут
только официальные карточки (опубликованные из организации `glmn-ai`) — `validate` предупреждает,
приложение отказывает.

**Пути** (`entry`, `icon`) задаются относительно манифеста через `/` — без `..`, без ведущего `/`,
без обратных слэшей, без имён устройств Windows (`con`, `nul`…), ничего внутри `__ns/` (эта папка
зарезервирована приложением), не глубже 20 уровней и не длиннее 240 символов.

### Размер — `card`

```json
"card": {
  "defaultSize": { "w": 460, "h": 340 },
  "minSize": { "w": 320, "h": 220 },
  "maxSize": { "w": 1200, "h": 900 }
}
```

Размеры — в единицах холста (CSS-пиксели при масштабе 100 %), целые числа: ширина 200–2400,
высота 120–1800, причём `minSize ≤ defaultSize ≤ maxSize`. По умолчанию 420×320, минимум 200×120,
максимум 2400×1800. Пользователь меняет размер в этих пределах; [`card.requestResize()`](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#resize)
тоже в них ограничивается.

### Разрешения — `permissions`

Список (до 32) идентификаторов разрешений или объектов с подробностями:

```json
"permissions": [
  "agents.read",
  { "id": "network", "hosts": ["api.github.com", "*.example.com", "status.example.org:8443"] },
  { "id": "fs.read", "reason": { "en": "Reads the JUnit report", "ru": "Читает отчёт JUnit" } },
  { "id": "clipboard.write", "optional": true }
]
```

| Ключ | Значение |
| --- | --- |
| `id` | Один из идентификаторов со страницы [Разрешения](https://docs.neurosquad.ai/ru/card-sdk/permissions). |
| `hosts` | Только для `network`, и там обязателен: до 32 шаблонов хостов. |
| `reason` | Локализуемый текст ≤ 300, показывается под разрешением в диалоге установки. Объясните зачем. |
| `optional` | `true` — не спрашивается при установке; карточка просит его во время работы через [`card.permissions.request()`](https://docs.neurosquad.ai/ru/card-sdk/api/environment#permissions). |

Обязательные разрешения при установке выдаются целиком или никак. Если указать один и тот же
идентификатор дважды, записи объединятся (и обязательная победит необязательную).

**Шаблоны хостов** для `network`: только имена хостов в нижнем регистре — `api.example.com`,
`api.example.com:8443` (порт, отличный от 443) или `*.example.com` (любой поддомен, но не сам
`example.com`). Без схемы, пути, IP-адреса, голого `*` и `localhost` — этот компьютер открывает
отдельное разрешение `network.local`.

### Форма настроек — `settings`

До 40 полей. Форму рисует приложение (она открывается из **⋯ → Settings…** карточки или вызовом
[`card.settings.open()`](https://docs.neurosquad.ai/ru/card-sdk/api/storage-settings#settings)); карточка читает значения.

```json
"settings": [
  { "key": "command", "type": "string", "label": "Test command", "default": "npm test", "maxLength": 200 },
  { "key": "notes", "type": "text", "label": "Notes", "placeholder": "Anything the agents should know" },
  { "key": "interval", "type": "number", "label": "Check every (min)", "default": 5, "min": 1, "max": 60, "step": 1 },
  { "key": "compact", "type": "boolean", "label": "Compact view", "default": false },
  { "key": "branch", "type": "select", "label": "Branch", "default": "main",
    "options": [{ "value": "main", "label": "main" }, { "value": "dev", "label": "dev" }] },
  { "key": "accent", "type": "color", "label": "Accent", "default": "#22c55e" },
  { "key": "apiKey", "type": "secret", "label": "API key", "required": true, "scope": "package" }
]
```

| Ключ | Значение |
| --- | --- |
| `key` | Начинается с буквы; буквы, цифры, `_`, `-`; до 64 символов. Уникален. |
| `type` | `string` (одна строка), `text` (несколько строк), `number`, `boolean`, `select`, `color` (`#rrggbb`), `secret`. |
| `label`, `description`, `placeholder` | Локализуемый текст (≤ 80, ≤ 300, ≤ 80). |
| `default` | Значение типа поля. Для `select` — один из вариантов, для `color` — `#rrggbb`, для `number` — в пределах `min`/`max`. **Для `secret` не допускается.** |
| `required` | Без него форма не сохранится. |
| `scope` | `instance` (по умолчанию): своё у каждой карточки на холсте. `package`: общее для всех карточек этого пакета. |
| `maxLength` | `string`, `text`, `secret`. По умолчанию 2 000 для `string`, 20 000 для `text`. |
| `min`, `max`, `step` | `number`. |
| `options` | Только `select`, 1–50 пар `{ "value", "label" }`. |

**Секреты** вводятся только в форме приложения, хранятся в зашифрованном виде и никогда не доходят
до карточки: карточка узнаёт лишь, задан ли секрет, и пользуется им через подстановку
`{{secret:<key>}}` в [заголовках сетевых запросов](https://docs.neurosquad.ai/ru/card-sdk/api/network#secrets).

### Порты — `ports`

Типизированные каналы данных по стрелкам: до 16 входов (`inputs`) и 16 выходов (`outputs`).
Подробно — в разделе [Порты](https://docs.neurosquad.ai/ru/card-sdk/api/ports).

```json
"ports": {
  "inputs": [
    { "id": "run", "label": "Run", "type": "ns:trigger", "default": true },
    { "id": "lookup", "label": "Look up", "type": "ns:text", "mode": "request",
      "response": { "type": "ns:json" } }
  ],
  "outputs": [
    { "id": "failures", "label": "Failures", "type": "ns:tasks", "retain": true },
    { "id": "coverage", "label": "Coverage", "type": "test-radar/coverage",
      "description": "Line coverage per file, 0..1",
      "schema": {
        "type": "object",
        "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
      } }
  ]
}
```

| Ключ | Для | Значение |
| --- | --- | --- |
| `id` | обоих | `a-z`, цифры, `-`, начинается с буквы, до 32 символов. Уникален в пределах направления. |
| `label`, `description` | обоих | Локализуемый текст (≤ 80, ≤ 500). Его видят пользователи, другие карточки и агенты, которые изучают порт. |
| `type` | обоих | Общеизвестный тип `ns:*` или свой `<package-name>/<type-name>`. |
| `schema` | обоих | Дополнительная JSON Schema, которой значение тоже должно соответствовать. **Обязательна для своих типов.** |
| `mode` | входов | `stream` (по умолчанию): сообщения без ответа. `request`: отправитель ждёт ответа. |
| `response` | входов-запросов | `{ "type", "schema"? }` — тип ответа. Обязателен для `mode: "request"`. |
| `default` | входов | Предпочтительный вход, когда выход другой карточки подходит к нескольким. Не больше одного. |
| `retain` | выходов | Приложение хранит последнее значение: другие карточки могут прочитать его в любой момент, а только что подключённая получает его один раз. |

Свой тип из пространства имён другого пакета допустим (с предупреждением) — так две карточки
договариваются об общем формате.

### Инструменты — `tools`

До 32 инструментов, которые могут вызывать подключённые к карточке агенты. Подробно — в разделе
[Инструменты для агентов](https://docs.neurosquad.ai/ru/card-sdk/api/tools).

| Ключ | Значение |
| --- | --- |
| `name` | `a-z`, цифры, `_`, начинается с буквы, до 40 символов. Агент видит `<name with - → _>_<tool>`, например `test_radar_run_tests`. Это имя не может совпадать со встроенным инструментом NeuroSquad (`canvas_spawn_card`, `terminal_send_keys`…) и не может содержать `__`. |
| `title` | До 80 символов, название для человека. |
| `description` | До 2 000 символов, **для модели**, по-английски: что делает и что возвращает. |
| `inputSchema` | JSON Schema с `"type": "object"`. Свойство `card` зарезервировано (его добавляет приложение). |
| `readOnly` | `true`, если инструмент ничего не меняет, — подсказка для агента. |
| `timeoutMs` | 1 000–120 000, по умолчанию 30 000. |

### Ваши JSON Schema

Схемы портов, схемы ответов и `inputSchema` инструментов используют безопасное подмножество JSON
Schema 2020-12 и проверяются при установке (≤ 500 узлов, глубина ≤ 16):

- **Поддерживается:** `type`, `enum`, `const`, `properties`, `required`, `additionalProperties`,
`minProperties`, `maxProperties`, `items`, `minItems`, `maxItems`, `uniqueItems`, `minLength`,
`maxLength`, `format`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`,
`anyOf`, `oneOf`, `$ref` (`#` или `#/$defs/<name>`), `$defs`.
- **Форматы:** `uri`, `date-time`, `date`, `email`, `color`, `uuid`.
- **Аннотации, которые игнорируются:** `$id`, `$schema`, `$comment`, `title`, `description`,
`default`, `examples`, `deprecated`, `readOnly`, `writeOnly`.
- **Ограничения:** `enum` — не больше 256 вариантов и 16 КБ в сумме; `const` — не больше 4 КБ.
- **Нельзя:** `pattern` (регулярные выражения из карточки выполнялись бы в приложении — риск отказа в
обслуживании) и любые ключевые слова не из списка выше.

> `$id` схемы, `https://neurosquad.ai/schemas/neurosquad-card.v1.json`, — это идентификатор, а не
> адрес для скачивания: указывайте в `$schema` копию из SDK.

---

## Разрешения

> Тринадцать разрешений карточек — риск каждого, точные слова, которые пользователь видит при установке, что каждое открывает и какие ограничения соблюдает приложение.

Source: https://docs.neurosquad.ai/ru/card-sdk/permissions

Карточка без разрешений может рисовать в своей коробке, пользоваться [хранилищем](https://docs.neurosquad.ai/ru/card-sdk/api/storage-settings),
читать свои настройки, менять свою шапку — и ни с кем ничем не обмениваться. Всё остальное — это
разрешения, которые вы объявляете в [манифесте](https://docs.neurosquad.ai/ru/card-sdk/manifest#permissions), а пользователь
выдаёт.

Как это устроено:

- **На пакет, с проверкой на каждый запрос.** Пользователь выдаёт разрешение вашему пакету
карточки (всем её копиям на всех холстах). Приложение проверяет выдачу при каждом вызове, внутри
приложения — не в SDK и не в вашей карточке.
- **Обязательные — целиком при установке.** Диалог установки перечисляет их, начиная с самых
рискованных. Отказаться — значит не устанавливать.
- **Необязательные — во время работы** (`"optional": true`). Вызовите
[`card.permissions.request()`](https://docs.neurosquad.ai/ru/card-sdk/api/environment#permissions), пока карточка на экране;
приложение спросит в своём диалоге на всё окно, и пользователь может отказать.
- **Одни включают другие.** `fs.write` включает `fs.read`; `agents.output`, `agents.prompt` и
`terminals.write` включают `agents.read`.
- **Пользователь может отозвать** любое разрешение в **Settings → Custom cards**. Страницы карточки
перезагружаются с урезанными правами и получают событие `permissions.changed`; пишите код с
расчётом на это.
- **Обновление, добавляющее разрешения или сетевые хосты,** применяется только после согласия
пользователя. Разрешения, которые вы убрали, отзываются.
- **Стрелка — согласие на данные.** Разрешения, которые затрагивают другую карточку, агента или
терминал, работают только с карточками, соединёнными с вашей [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows), — в любом
направлении, если не сказано иное.

Если разрешения нет, вызов падает с `PERMISSION_DENIED` (`error.permission` называет какое).

### Коротко

| Разрешение | Риск | Открывает |
| --- | --- | --- |
| `agents.read` | Низкий | `agents.list/get`, события статуса, ходов и изменений, порт агента `status` |
| `agents.output` | Высокий | Чтение экранов и ответов **подключённых** агентов и терминалов |
| `agents.prompt` | Высокий | Отправку промптов **подключённым** ИИ-агентам |
| `terminals.write` | Высокий | Запуск команд в **подключённых** терминалах |
| `cards.connected` | Средний | Чтение и изменение **подключённых** заметок, списков задач, досок задач, стикеров |
| `network` + хосты | Средний | `net.fetch` к перечисленным хостам |
| `network.local` | Высокий | `net.fetch` к серверам на этом компьютере |
| `fs.read` | Высокий | Чтение файлов в папке воркспейса |
| `fs.write` | Высокий | Запись файлов в папке воркспейса (включает `fs.read`) |
| `clipboard.write` | Низкий | Копирование текста в буфер обмена |
| `canvas.spawn` | Низкий | Добавление до 4 карточек рядом с собой |
| `background` | Низкий | Работу, пока никто не смотрит |
| `usage.read` | Низкий | Расход токенов и стоимость воркспейса |

### Каждое разрешение

#### `agents.read` — низкий

**Пользователь видит:** *See the agents on this canvas* — «Видеть агентов на этом холсте. Их имена,
какой инструмент у каждого и работает ли он, ждёт вас или закончил».

**Открывает:** [`card.agents.list()` / `get()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents), события `agents.status`,
`agents.turn`, `agents.changed` и встроенный выходной порт агента `status`.

**Границы:** ИИ-агенты и терминалы воркспейса самой карточки. Другие карточки — не агенты и в
список не попадают.

#### `agents.output` — высокий

**Пользователь видит:** *Read what agents and terminals connected to it print* — «Читать вывод
подключённых к ней агентов и терминалов. Всё, что на экранах карточек агентов и терминалов,
соединённых с ней стрелкой, включая показанные там секреты».

**Открывает:** `card.agents.readScreen()`, `card.agents.lastReply()`, живой вывод через
`card.agents.onOutput()`, выходные порты агента `reply` и терминала `exit`.

**Границы:** только агенты и терминалы, подключённые стрелкой. Включает `agents.read`.

#### `agents.prompt` — высокий

**Пользователь видит:** *Give instructions to agents connected to it* — «Давать указания
подключённым к ней агентам. Набирать и отправлять промпты ИИ-агентам, соединённым с ней стрелкой.
Агент может править файлы и запускать команды, значит, карточка может заставить его сделать всё,
что умеет агент».

**Открывает:** [`card.agents.prompt()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#prompting) и входной порт агента `prompt`.

**Границы:** подключённые стрелкой **ИИ**-агенты (не терминалы). Промпты идут через очередь промптов
и [бюджет](https://docs.neurosquad.ai/ru/cards/budget) воркспейса, не больше 6 в минуту на карточку (метод и входной порт агента
`prompt` считаются вместе); каждый виден на стрелке и в журнале стрелки. Агенту в
[опасном режиме](https://docs.neurosquad.ai/ru/agents/dangerous-mode) каждый промпт отправляется только после согласия
пользователя на карточке. Включает `agents.read`.

#### `terminals.write` — высокий

**Пользователь видит:** *Run commands in terminals connected to it* — «Запускать команды в
подключённых к ней терминалах. Набирать и выполнять команды в карточках терминалов, соединённых с
ней стрелкой, — всё, что могли бы запустить вы сами».

**Открывает:** [`card.terminals.run()` и `write()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#terminals), входной порт
терминала `command`.

**Границы:** карточки терминалов (bash, PowerShell, cmd), подключённые стрелкой. Не больше 30 команд
в минуту на карточку — `run` и порт терминала `command` считаются вместе; `write` — не больше 60 в
минуту. Каждая команда видна на стрелке. Включает `agents.read`.

#### `cards.connected` — средний

**Пользователь видит:** *Read and change cards connected to it* — «Читать и менять подключённые к
ней карточки. Заметки, чек-листы, доски задач и стикеры, соединённые с ней стрелкой».

**Открывает:** [порты встроенных карточек](https://docs.neurosquad.ai/ru/card-sdk/api/ports#built-in-cards) — заметки, списка
задач, доски задач и стикера: дописать заметку, добавить задачи, прочитать список.

**Границы:** карточки этих четырёх видов, подключённые стрелкой.

#### `network` — средний, нужны `hosts`

**Пользователь видит:** *Connect to `api.github.com`, `*.example.com`* — «Подключаться к …
Отправлять и получать данные только с этих адресов в интернете. Туда может уйти всё, что видит
карточка».

**Открывает:** [`card.net.fetch()`](https://docs.neurosquad.ai/ru/card-sdk/api/network) к этим хостам по `https`.

**Границы:** ровно объявленные шаблоны хостов и только публичные адреса — хост, который резолвится
в частный, локальный или адрес облачных метаданных, отклоняется, и при каждом редиректе тоже.
Попросить «любой хост» в версии 1 нельзя.

#### `network.local` — высокий

**Пользователь видит:** *Connect to servers on this computer* — «Подключаться к серверам на этом
компьютере. Обращаться к программам на localhost, например дев-серверам и локальным базам данных».

**Открывает:** `card.net.fetch()` к `localhost`, `127.0.0.1` и `::1`, по `http` или `https`.

**Границы:** любой порт, кроме собственных серверов NeuroSquad: его MCP-сервера, сервера удалённого
доступа, сервера подключения папок для разработчиков, порта отладки Chrome каждой браузерной
карточки и дев-сервера самого приложения. [Подстановки секретов](https://docs.neurosquad.ai/ru/card-sdk/api/network#secrets) в
запросах к этому компьютеру никогда не заполняются.

#### `fs.read` — высокий

**Пользователь видит:** *Read files in the workspace folder* — «Читать файлы в папке воркспейса.
Любой файл в папке проекта этого воркспейса, включая секреты в файлах вроде `.env`».

**Открывает:** [`card.fs.stat/list/read*/watch()`](https://docs.neurosquad.ai/ru/card-sdk/api/files) и абсолютный путь `path`
воркспейса в `card.workspace`.

**Границы:** папка воркспейса. Пути задаются относительно неё; `..` и абсолютные пути отклоняются,
ссылка, ведущая наружу, — тоже. Если папка воркспейса — это домашняя папка пользователя, корень диска
или в ней лежит папка данных самого NeuroSquad, отклоняется любой вызов к файлам.

#### `fs.write` — высокий

**Пользователь видит:** *Change files in the workspace folder* — «Менять файлы в папке воркспейса.
Создавать, перезаписывать и переносить в корзину файлы в папке проекта этого воркспейса. Агенты
воркспейса читают и запускают эти файлы, поэтому карточка может заставить их выполнять команды.
Защищены: `.git`, настройки агентов (`.claude`, `.mcp.json`, `CLAUDE.md`, `AGENTS.md` и подобные) и
данные самого NeuroSquad».

**Открывает:** `card.fs.writeText/writeBytes/mkdir/trash()`.

**Границы:** как у `fs.read`, за вычетом [защищённых путей](https://docs.neurosquad.ai/ru/card-sdk/api/files#protected): любой
`.git`, настройки агентов и редакторов, CI-процессы. Безвозвратного удаления нет — `trash` переносит
в корзину ОС. Включает `fs.read`.

#### `clipboard.write` — низкий

**Пользователь видит:** *Copy to your clipboard* — «Копировать в буфер обмена. Заменять содержимое
буфера обмена текстом из карточки».

**Открывает:** [`card.copyText()`](https://docs.neurosquad.ai/ru/card-sdk/api/files#clipboard), не чаще раза в секунду. Читать
буфер обмена нельзя.

#### `canvas.spawn` — низкий

**Пользователь видит:** *Add cards next to itself* — «Добавлять карточки рядом с собой. Ставить на
холст до 4 новых карточек рядом с собой».

**Открывает:** [`card.spawn()`](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#spawn) — ещё одну копию вашей карточки или
заметку, список задач, доску задач, стикер, соединённые с ней стрелкой.

**Границы:** 4 карточки на карточку, 4 в минуту, в пределах лимита карточек воркспейса.

#### `background` — низкий

**Пользователь видит:** *Keep running when you are not looking* — «Работать, когда вы не смотрите.
Оставаться активной, пока её воркспейс скрыт. Тратит больше памяти и батареи».

**Открывает:** карточку не [усыпляют](https://docs.neurosquad.ai/ru/card-sdk/api/environment#lifecycle), когда она скрыта.

**Границы:** в фоне во всём приложении работает не больше 8 таких карточек; сверх этого те, что
давно не показывались, всё равно усыпляются.

#### `usage.read` — низкий

**Пользователь видит:** *See token usage and costs* — «Видеть расход токенов и стоимость. Сколько
токенов потратили агенты этого воркспейса и сколько это стоило».

**Открывает:** [`card.usage()`](https://docs.neurosquad.ai/ru/card-sdk/api/files#usage) и [`card.agents.usage()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#usage) для агентов, подключённых стрелкой.

**Границы:** воркспейс самой карточки.

### Что ещё перечисляет диалог установки

Выводится из манифеста, а не из разрешений: имена [инструментов](https://docs.neurosquad.ai/ru/card-sdk/api/tools), которые
карточка даёт подключённым агентам, и сколько у неё входных и выходных портов. Необязательные
разрешения показываются под **It may ask later for**.

> Просите минимум. Каждая строка высокого риска заставляет осторожного пользователя задуматься, а
> отсутствие `reason` — гадать. Если сильное разрешение нужно лишь иногда, сделайте его
> необязательным и попросите, когда пользователь дойдёт до этой функции.

---

## connect() и объект карточки

> Как подключить карточку к NeuroSquad, типизированный объект Card, его живой контекст, вызов любого метода и подписка на любое событие.

Source: https://docs.neurosquad.ai/ru/card-sdk/api

Всё, что делает карточка, идёт через один объект — **карточку**, которую возвращает `connect()`:

```ts
import { connect } from '@neurosquad/card-sdk'

const card = await connect()
card.setStatus(`Hello, ${card.workspace.name}`, { tone: 'success' })
```

`connect()` ждёт, пока приложение передаст карточке её личный канал, представляется и возвращает
[`Card`](#the-card-object). Повторный вызов возвращает ту же карточку.

> **Импортируйте SDK из входного скрипта.** Он начинает слушать рукопожатие приложения сразу после
> загрузки. Карточка, которая грузит SDK поздно (динамическим `import()` после таймера), может его
> пропустить и упасть с `UNAVAILABLE`.

### `connect(options?)`

```ts
import { connect } from '@neurosquad/card-sdk'

const card = await connect({
  theme: true,          // apply the app theme as --ns-* CSS variables on <html> (default true)
  syncLang: true,       // keep <html lang> equal to the app language (default true)
  forwardErrors: true,  // send uncaught errors and rejections to the card log (default true)
  timeoutMs: 10_000     // how long to wait for the app (default 10 000)
})
```

| Параметр | По умолчанию | Значение |
| --- | --- | --- |
| `theme` | `true` | `false` — не трогать ваш CSS; элемент — положить переменные `--ns-*` на него, а не на `<html>`. См. [Тема](https://docs.neurosquad.ai/ru/card-sdk/api/environment#theme). |
| `syncLang` | `true` | Держать `<html lang>` равным языку приложения. |
| `forwardErrors` | `true` | Пересылать `error` и `unhandledrejection` в [журнал карточки](https://docs.neurosquad.ai/ru/card-sdk/api/environment#log). |
| `timeoutMs` | `10000` | Сколько ждать канал от приложения, а потом его ответ. |
| `port` | — | Использовать этот канал вместо ожидания приложения — для [мок-хоста](https://docs.neurosquad.ai/ru/card-sdk/testing). |

Отклоняется с [`CardSdkError`](https://docs.neurosquad.ai/ru/card-sdk/api/errors):

- `UNAVAILABLE` — страница открыта не внутри карточки NeuroSquad (сама по себе в браузере). Для
превью используйте [мок-хост](https://docs.neurosquad.ai/ru/card-sdk/testing), как это делают шаблоны.
- `PROTOCOL_MISMATCH` — приложение старше протокола карточек, на котором говорит ваш SDK. Карточка
показывает «нужен более новый NeuroSquad».

### Объект карточки

| Член | Что это |
| --- | --- |
| `card.context` | Всё, что приложение сообщило карточке, [поддерживается в актуальном виде](#context). |
| `card.setTitle / setStatus / setBadge / setOverview / attention / requestResize / openLink / focusCard / spawn` | [Шапка карточки](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui) |
| `card.ui` | [Тосты, диалог подтверждения, меню карточки](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#ui) |
| `card.storage` | [Хранилище карточки и пакета](https://docs.neurosquad.ai/ru/card-sdk/api/storage-settings#storage) |
| `card.settings` | [Значения формы настроек](https://docs.neurosquad.ai/ru/card-sdk/api/storage-settings#settings) |
| `card.agents` | [Агенты, их статусы, вывод и промпты](https://docs.neurosquad.ai/ru/card-sdk/api/agents) |
| `card.terminals` | [Команды в подключённых терминалах](https://docs.neurosquad.ai/ru/card-sdk/api/agents#terminals) |
| `card.ports` | [Типизированные данные к подключённым карточкам и от них](https://docs.neurosquad.ai/ru/card-sdk/api/ports) |
| `card.tools` | [Инструменты для подключённых агентов](https://docs.neurosquad.ai/ru/card-sdk/api/tools) |
| `card.net` | [HTTP через прокси приложения](https://docs.neurosquad.ai/ru/card-sdk/api/network) |
| `card.fs` | [Файлы в папке воркспейса](https://docs.neurosquad.ai/ru/card-sdk/api/files) |
| `card.permissions` | [Состояние разрешений, запрос необязательных](https://docs.neurosquad.ai/ru/card-sdk/api/environment#permissions) |
| `card.lifecycle` | [Видимость, усыпление, разворот, изменение размера](https://docs.neurosquad.ai/ru/card-sdk/api/environment#lifecycle) |
| `card.log` | [Строки журнала карточки](https://docs.neurosquad.ai/ru/card-sdk/api/environment#log) |
| `card.copyText / usage / getWorkspace / getTheme / getI18n` | [Буфер обмена, расход](https://docs.neurosquad.ai/ru/card-sdk/api/files), свежие снимки |
| `card.host` | [Определение возможностей](#feature-detection) |
| `card.call / on / once / waitFor` | [Любой метод, любое событие](#any-method-any-event) |
| `card.close() / closed` | Закрыть канал; последующие вызовы падают с `UNAVAILABLE`. |

### Контекст

`card.context` — это `HostContext`: то, что приложение отправило при подключении карточки,
**обновляемое по каждому событию** (видимость, размер, тема, язык, настройки, разрешения,
соседи). При каждом изменении объект заменяется, а не мутирует, — его безопасно использовать с
`useSyncExternalStore` из React.

```ts
import type { HostContext } from '@neurosquad/card-sdk'

function describe(context: HostContext): string {
  const { instance, workspace, visibility, i18n, launch } = context
  return `${instance.displayName} ${instance.version} in "${workspace.name}", ${visibility}, ${i18n.language}, started: ${launch}`
}

card.onContextChange((context) => render(describe(context)))
```

| Поле | Тип | Значение |
| --- | --- | --- |
| `instance` | `CardInstanceInfo` | `instanceId` (идентификатор этой карточки на холсте), `packageId`, `name`, `displayName`, `version`, `commit` (`null` для подключённой папки), `title`, `size`, `dev`. |
| `workspace` | `WorkspaceInfo` | `id`, `name` и `path` (абсолютный) — только с `fs.read`. |
| `visibility` | `'visible'`, `'offscreen'`, `'overview'` или `'hidden'` | См. [Жизненный цикл](https://docs.neurosquad.ai/ru/card-sdk/api/environment#lifecycle). |
| `expanded` | `boolean` | Карточка развёрнута на весь холст. |
| `theme` | `ThemeSnapshot` | Цвета, скругления и шрифты приложения. |
| `i18n` | `{ language, locale }` | `en`, `ru` или `zh` и локаль для `Intl`. |
| `settings` | `SettingsSnapshot` | `values` и `secrets` (какие секретные ключи заданы). |
| `permissions` | `PermissionState[]` | Каждое объявленное разрешение с `granted`, `optional`, `hosts`, `reason`. |
| `ports` | `{ inputs, outputs }` | Ваши собственные порты, подписи уже на нужном языке. |
| `peers` | `PeerInfo[]` | Карточки, соединённые стрелками. |
| `launch` | `'created'`, `'opened'`, `'resumed'`, `'reloaded'` или `'updated'` | Почему запустилась эта страница. |
| `spawnInit` | JSON или нет | Данные от карточки, которая [создала](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#spawn) эту, при первом запуске. |
| `chrome` | `CardChromeState` или нет | Что приложение показывает для этой карточки прямо сейчас — `title`, `status`, `badge`, `overview`, `attention`; сохраняется между перезагрузками. См. [Шапка карточки](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#attention). В старых версиях приложения отсутствует. |
| `appVersion` | `string` | Версия NeuroSquad. |
| `limits` | `LIMITS` | Все лимиты протокола, см. [Лимиты](https://docs.neurosquad.ai/ru/card-sdk/api/errors#limits). |
| `protocol` | `number` | Протокол карточек, на котором говорит приложение. |

Сокращения на самой карточке: `card.instanceId`, `card.instance`, `card.workspace`,
`card.visibility`, `card.expanded`, `card.size`, `card.theme`, `card.i18n`, `card.language`,
`card.launch`, `card.spawnInit`, `card.limits`, `card.appVersion`.

**`launch`** говорит, что произошло: `created` (карточку только что добавили на холст), `opened`
(открыли воркспейс), `resumed` (вернулась после [усыпления](https://docs.neurosquad.ai/ru/card-sdk/api/environment#lifecycle)),
`reloaded` (пользователь нажал Reload, в режиме разработчика изменился файл или отозвали
разрешение), `updated` (установлена новая версия вашей карточки).

### Любой метод, любое событие

Пространства имён — это удобная обёртка над двумя примитивами, оба полностью типизированы по
протоколу:

```ts
// Any method: params and result are typed from the method name.
const { keys } = await card.call('storage.keys', { scope: 'instance', prefix: 'draft:' })
const info = await card.call('card.getInfo')

// Any event: the payload is typed from the event name. Returns a function that removes the listener.
const off = card.on('agents.turn', (turn) => {
  if (turn.phase === 'end') render(`${turn.agentId} finished a turn`)
})
off()

// Once, or as a promise.
card.once('lifecycle.expanded', ({ expanded }) => render(expanded))
const next = await card.waitFor('agents.status', (e) => e.status === 'needs-input', { timeoutMs: 60_000 })
render(next.agentId)
```

Темы с подпиской (`agents.status`, `agents.turn`, `agents.changed`, `storage.changed`) подписываются
в приложении автоматически, пока есть хотя бы один слушатель, и отписываются, когда уходит
последний. Для `agents.output` нужны идентификаторы агентов — используйте
[`card.agents.onOutput()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#output). Если для темы нужно разрешение, которого у
вас нет, слушатель просто ничего не получает, а в журнал карточки уходит предупреждение.

События, которые могут прийти раньше, чем вы подпишетесь, — `ports.message`, `ui.menu`,
`fs.changed`, — сохраняются (до 100) и доставляются первому слушателю, так что между `connect()` и
вашим `on()` ничего не теряется.

#### Все события

| Событие | Данные | Когда |
| --- | --- | --- |
| `lifecycle.visibility` | `{ state }` | Изменилась видимость. |
| `lifecycle.suspend` | `{ graceMs }` | Страницу вот-вот выгрузят. Используйте `card.lifecycle.onSuspend`. |
| `lifecycle.expanded` | `{ expanded }` | Карточку развернули или вернули. |
| `lifecycle.resized` | `{ w, h }` | Изменился размер карточки. |
| `settings.changed` | `SettingsSnapshot` | Изменились настройки (форма или `settings.set`). |
| `theme.changed` | `ThemeSnapshot` | Изменилась тема приложения. |
| `i18n.changed` | `{ language, locale }` | Изменился язык приложения. |
| `permissions.changed` | `PermissionState[]` | Изменилась выдача разрешений. |
| `ui.menu` | `{ id }` | Выбран добавленный вами пункт меню. |
| `ports.message` | см. [Порты](https://docs.neurosquad.ai/ru/card-sdk/api/ports#receiving) | На вход пришло значение. |
| `ports.request` | см. [Порты](https://docs.neurosquad.ai/ru/card-sdk/api/ports#requests) | Соседняя карточка обращается к входу-запросу. Используйте `card.ports.onRequest`. |
| `ports.peersChanged` | `PeerInfo[]` | Изменились стрелки или соседи. |
| `tools.call`, `tools.cancel` | см. [Инструменты](https://docs.neurosquad.ai/ru/card-sdk/api/tools) | Агент вызывает инструмент. Используйте `card.tools.handle`. |
| `net.chunk` | см. [Сеть](https://docs.neurosquad.ai/ru/card-sdk/api/network#streaming) | Кусок потокового ответа. Используйте `response.chunks()`. |
| `fs.changed` | `{ watchId, path, type }` | Изменился отслеживаемый файл. Используйте `card.fs.watch`. |
| `storage.changed` | `{ scope, key, byInstance }` | Другая копия карточки записала ключ пакета. Тема. |
| `agents.status` | `{ agentId, status, at }` | Изменился статус агента. Тема, `agents.read`. |
| `agents.turn` | `{ agentId, phase, at }` | Ход начался или закончился. Тема, `agents.read`. |
| `agents.changed` | `{ agents }` | Агентов добавили, удалили или переименовали. Тема, `agents.read`. |
| `agents.output` | `{ agentId, text, at }` | Вывод подключённого агента. `agents.output`. |
| `host.ping` | `{ seq }` | Пульс — SDK отвечает за вас. |

### Определение возможностей

Новые методы и события появляются внутри одной версии протокола. Прежде чем пользоваться тем, чего в
приложении пользователя может ещё не быть, проверьте:

```ts
if (await card.host.supports('usage.summary')) {
  const usage = await card.usage('today')
  render(usage.totalCostMicroUsd)
}

const { protocol, methods, events } = await card.host.capabilities()
render(protocol, methods.length, events.length)

// A method newer than your SDK's types:
const result = await card.callUnchecked('some.newMethod', { any: 'params' })
render(result)
```

### Соглашения

- **Идентификаторы.** Идентификаторы карточек и агентов — это идентификаторы на холсте, тот же
`cardId`, что вы получаете из `card.ports.peers`, `card.agents.list()` или `card.spawn()`.
- **Подключена** — значит, между двумя карточками есть стрелка, в любом направлении. Для портов
направление ещё и важно (см. [Порты](https://docs.neurosquad.ai/ru/card-sdk/api/ports#direction)).
- **Каждый вызов проверяется дважды.** SDK проверяет параметры по тем же схемам, что и приложение, и
сразу падает с `INVALID_PARAMS` и точным путём; приложение проверяет снова — плюс разрешения,
видимость, стрелки и ограничения частоты.
- **Передаётся только JSON.** Никаких `Blob` и `ArrayBuffer`: помощники, которые принимают байты
(`fs.writeBytes`, тела `net.fetch`), сами кодируют их в base64.
- **Ответы могут прийти не по порядку;** события приходят в том порядке, в каком их отправило
приложение.
- **Никогда не доверяйте событиям `message` у `window`.** Любая другая карточка на холсте может
сделать `postMessage` в ваш фрейм. Доверенный канал только один — тот, что SDK получает от
приложения в `connect()`; не добавляйте свои слушатели `message`, которые что-то делают с
пришедшим.

---

## Шапка карточки и диалоги

> Шапка карточки — заголовок, статус, бейдж, — её плитка обзора, привлечение внимания, изменение размера, ссылки, полёт камеры и создание карточек; тосты, диалоги подтверждения и меню карточки.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/card-ui

Шапку карточки, её плитку обзора и диалоги рисует **приложение**, а не ваша страница, — поэтому они
выглядят как родные, работают, пока карточка усыплена, и видны на телефоне. Вы задаёте их
содержимое.

**Вызывайте их сколько угодно часто.** Приложение ограничивает частоту этих обновлений (заголовок —
30 в минуту; статус, бейдж и обзор — по 120 в минуту; внимание — раз в 10 секунд), а SDK берёт это
на себя: для `setTitle`, `setStatus`, `setBadge`, `setOverview` и `attention` он отправляет по одному
вызову каждого метода за раз, схлопывает вызовы, сделанные тем временем, в один с последним
значением и повторяет последнее значение, если приложение ответило `RATE_LIMITED`. Из-за частоты они
никогда не бросают исключений — обновлять на каждом рендере нормально. Обновление, которое ничего не
меняет, ничего не стоит.

### Заголовок

```ts
await card.setTitle('Checkout tests') // null clears it
```

Имя в шапке, в сайдбаре и в карточке «Команда». Если пользователь переименовал карточку, побеждает
его имя; если нет ни того ни другого, показывается `displayName` из манифеста. До 120 символов;
управляющие символы, символы направления текста (bidi) и невидимые символы вырезаются.

### Статус

```ts
await card.setStatus('Running tests…', { busy: true })       // spinner
await card.setStatus('3 failed', { tone: 'danger' })
await card.setStatus(null)                                    // clear
```

Плашка в шапке, до 80 символов. Тона: `default`, `accent`, `success`, `warning`, `danger`.

### Бейдж

```ts
await card.setBadge(3)                          // a count
await card.setBadge('NEW', { tone: 'accent' })  // or a short text, ≤ 12 characters
await card.setBadge(null)                       // clear
```

### Плитка обзора

Когда пользователь отдаляет холст за порог обзора, каждая карточка вместо тела показывает плитку с
главным фактом. Ваша показывает то, что вы задали здесь, — и продолжает показывать, пока карточка
усыплена, и на [телефоне](https://docs.neurosquad.ai/ru/card-sdk/phone). Приложение это запоминает.

```ts
await card.setOverview({
  primary: '3 failing',        // big line, ≤ 160
  secondary: 'checkout, auth', // small line, ≤ 160
  progress: 0.8,               // 0..1, a progress bar; null hides it
  tone: 'danger',
  icon: 'bug-ant'
})
```

Держите её актуальной: на загруженном холсте большинство видит от вашей карточки только её.

**Иконки**, которые умеет рисовать приложение (heroicons, контурные): `academic-cap`, `arrow-path`,
`beaker`, `bell`, `bolt`, `book-open`, `bug-ant`, `calendar`, `camera`, `chart-bar`, `chart-pie`,
`chat-bubble-left-right`, `check-circle`, `clock`, `cloud`, `code-bracket`, `command-line`,
`cpu-chip`, `cube`, `currency-dollar`, `document-text`, `exclamation-triangle`, `film`, `fire`,
`flag`, `folder`, `globe-alt`, `heart`, `inbox`, `key`, `light-bulb`, `link`, `list-bullet`, `map`,
`megaphone`, `moon`, `musical-note`, `newspaper`, `paper-airplane`, `pause`, `photo`, `play`,
`puzzle-piece`, `rocket-launch`, `server`, `shield-check`, `signal`, `sparkles`, `star`, `stop`,
`sun`, `table-cells`, `tag`, `trash`, `trophy`, `users`, `wrench-screwdriver` (список —
`HOST_ICON_NAMES` в SDK). Внутри своей страницы рисуйте любые иконки.

### Внимание

```ts
await card.attention('needs-input', 'Pick a branch to deploy')
await card.attention('info')    // a softer pulse
await card.attention('none')    // clear
```

`needs-input` заставляет карточку пульсировать, как агент, который ждёт пользователя, и добавляет её
во **входящие** (Inbox). Не чаще раза в 10 секунд. В версии 1 нет ни звука, ни уведомлений ОС.

**Что показано сейчас.** Приложение сохраняет заголовок, статус, бейдж, обзор и внимание карточки
при перезагрузках, усыплении и обновлениях. `card.context.chrome` сообщает вашей странице, что там
сейчас, так что карточка, поднявшая внимание до перезагрузки, может снять устаревшую пульсацию:

```ts
const attention = card.context.chrome?.attention
if (attention && !stillNeedsTheUser()) await card.attention('none')

declare function stillNeedsTheUser(): boolean
```

В старых версиях приложения `chrome` нет — считайте это «неизвестно».

### Изменение размера

```ts
const applied = await card.requestResize({ w: 640, h: 480 })
render(applied.w, applied.h)
```

Ограничивается `minSize`/`maxSize` манифеста; возвращает размер, который реально применился. Шаг
попадает в историю отмены холста, как изменение размера руками. Не чаще раза в 500 мс. Пользователь
тоже всегда может поменять размер — слушайте [`card.lifecycle.onResized`](https://docs.neurosquad.ai/ru/card-sdk/api/environment#lifecycle).

### Открыть ссылку

```ts
const opened = await card.openLink('https://github.com/acme/app/issues/42')
```

Приложение показывает полный адрес в своём диалоге на всё окно; ссылка откроется в браузере
пользователя только после **Open link**. Только `https://` и только пока карточка видна (иначе
`NOT_VISIBLE`). Возвращает `false`, если пользователь отказался. Карточка не может ни перейти на
другую страницу сама, ни открыть окно.

### Полететь к другой карточке

```ts
await card.focusCard(cardId)
```

Переносит камеру к другой карточке того же воркспейса — для кнопок вида «покажи упавшего агента».
Только пока ваша карточка видна, не чаще раза в 5 секунд.

### Создать карточку

Нужно разрешение [`canvas.spawn`](https://docs.neurosquad.ai/ru/card-sdk/permissions#canvas-spawn).

```ts
// A note next to this card, connected with an arrow from this card.
const noteId = await card.spawn('note', { title: 'Test report' })
await card.ports.send(noteId, 'summary', '# Report\n\nAll green.')

// Another copy of this card, with data for its first start.
await card.spawn('self', { init: { suite: 'e2e' }, connect: false })
```

Виды: `self` (ещё одна карточка вашего пакета, которая при первом запуске получает `init` как
`card.spawnInit`), `note`, `todo`, `kanban`, `sticky`. Новая карточка встаёт рядом с вашей и
соединяется стрелкой от вашей карточки, если не указать `connect: false`. Не больше 4 на карточку и
4 в минуту.

### Сведения о карточке

```ts
const info = await card.getInfo() // CardInstanceInfo, fresh from the app
render(info.instanceId, info.packageId, info.commit ?? 'dev folder', info.size)
```

### Тосты

```ts
await card.ui.toast('Copied', { tone: 'success', durationMs: 2000 })
```

Небольшое уведомление внутри коробки карточки, до 280 символов, на 1–15 секунд, не чаще раза в 2
секунды.

### Диалог подтверждения

`alert`, `confirm` и `prompt` в песочнице карточки ничего не делают. Попросите приложение:

```ts
const ok = await card.ui.confirm({
  title: 'Delete all saved runs?',
  message: 'This removes 42 runs from this card. It cannot be undone.',
  confirmLabel: 'Delete',
  cancelLabel: 'Keep',
  tone: 'danger'
})
if (ok) await card.storage.clear()
```

Приложение показывает это **своим диалогом поверх всего окна**, а не внутри карточки: неизменный
заголовок о том, что ваша карточка просит подтверждения, ваши `title` и `message` как цитата, ваша
`confirmLabel` (её заменяет «Confirm» приложения, если она похожа на отмену, отказ или «нет»,
называет NeuroSquad или содержит управляющие символы) и собственная кнопка Cancel приложения. Только
пока карточка видна, не больше 10 в минуту. Диалоги от нескольких карточек выстраиваются в очередь.

### Меню карточки

Добавьте до 12 пунктов в меню **⋯** карточки, после собственных пунктов приложения (Settings…,
Reload, About…).

```ts
await card.ui.setMenu([
  { id: 'rerun', label: 'Run again', icon: 'arrow-path', onSelect: () => void rerun() },
  { id: 'export', label: 'Copy report', icon: 'document-text', onSelect: () => void copyReport() },
  { id: 'reset', label: 'Reset', tone: 'danger', disabled: true }
])

// Or handle every choice in one place:
card.ui.onMenu((id) => card.log.info('menu', id))

declare function rerun(): Promise<void>
declare function copyReport(): Promise<void>
```

Каждый вызов заменяет прежние пункты (не больше 30 вызовов в минуту). `onSelect` остаётся в вашей
карточке — в приложение он не отправляется.
Подписи до 60 символов; `icon` — одна из [иконок приложения](#overview).

> Всё на этой странице, кроме диалогов и ссылок, работает, даже когда карточки нет на экране.
> Диалогам, ссылкам, полёту камеры и запросам разрешений нужно, чтобы пользователь смотрел: иначе
> они падают с `NOT_VISIBLE`.

---

## Хранилище и настройки

> Постоянное хранилище ключ/значение для карточки и для пакета, а также чтение и изменение формы настроек, которую приложение рисует по вашему манифесту.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/storage-settings

### Хранилище

У страницы карточки нет `localStorage`, `indexedDB` и cookies — в её песочнице нет источника
(origin), к которому их можно привязать. Вместо них — `card.storage`: значения JSON, которые
приложение атомарно хранит на диске и которые переживают перезагрузки, усыпление и перезапуски.
Разрешение не нужно.

```ts
// This card on the canvas (instance scope).
const draft = await card.storage.get('draft', '')          // string, '' when missing
await card.storage.set('draft', `${draft}\nmore`)
await card.storage.set('runs', [{ at: Date.now(), failed: 3 }])
const runs = await card.storage.get<{ at: number; failed: number }[]>('runs')  // undefined when missing
await card.storage.delete('draft')
const keys = await card.storage.keys('run:')               // keys starting with a prefix
const { bytes, quota } = await card.storage.usage()
render(runs?.length, keys, bytes, quota)

// Shared by every copy of this card, on every canvas (package scope).
await card.storage.package.set('lastSync', Date.now())
card.storage.onChange(({ key, byInstance }) => {
  if (key === 'lastSync') render(`updated by card ${byInstance}`)
})
```

| Метод | Результат |
| --- | --- |
| `get(key)` | Значение или `undefined`. |
| `get(key, fallback)` | Значение или `fallback`. Результат типизирован по запасному значению. |
| `set(key, value)` | Сохраняет любое значение JSON. |
| `delete(key)` | |
| `keys(prefix?)` | `string[]` |
| `clear()` | Удаляет все ключи этой области. |
| `usage()` | `{ bytes, quota, keys }` |
| `onChange(handler)` | Другая копия этой карточки записала ключ **пакета**: `{ scope, key, byInstance }`. |

Те же методы есть у `card.storage.package`.

**Лимиты:** ключи до 256 символов, значения до 1 МБ, не больше 10 000 ключей; 5 МБ на карточку,
20 МБ на пакет. Превышение — `QUOTA_EXCEEDED`. Запись доходит до диска примерно за четверть секунды и
сбрасывается при выходе из приложения.

**Что с ним происходит:** хранилище карточки удаляется вместе с карточкой. Хранилище пакета
переживает удаление пакета, если пользователь не отметит **Also delete its saved data and secrets**.
Обновления хранилище не трогают — держите сохранённые структуры читаемыми для новых версий (храните
поле `version`, если можете их поменять).

> Сохраняйтесь до выгрузки: карточку, скрытую какое-то время, усыпляют, и её страница выбрасывается.
> Записывайте то, что ещё в памяти, в [`card.lifecycle.onSuspend`](https://docs.neurosquad.ai/ru/card-sdk/api/environment#lifecycle).

### Настройки

Объявите поля в [`settings`](https://docs.neurosquad.ai/ru/card-sdk/manifest#settings) манифеста; приложение нарисует форму (из
**⋯ → Settings…** карточки или по вызову `card.settings.open()`), проверит её и сохранит значения.
Ваша карточка их читает:

```ts
const command = card.settings.value<string>('command') ?? 'npm test'
const all = card.settings.values                         // defaults filled in, secrets never included
const hasKey = card.settings.hasSecret('apiKey')         // true when the user saved one

card.settings.onChange((snapshot) => {
  render(snapshot.values['command'], snapshot.secrets['apiKey'])
})

// Change your own non-secret settings (a toggle in your UI, say). Validated like the form.
await card.settings.set({ compact: true })

// Open the form on the card (only while it is visible).
if (!hasKey) await card.settings.open()

render(command, all)
```

| Член | Что это |
| --- | --- |
| `values` | Текущие значения, со значениями по умолчанию. Поддерживаются в актуальном виде. |
| `secrets` | `Record<key, boolean>`: какие секретные настройки заданы. |
| `value(key)` | Одно значение, тип задаёте вы. |
| `hasSecret(key)` | Задана ли секретная настройка. |
| `get()` | Свежий `SettingsSnapshot` из приложения. |
| `set(values)` | Меняет несекретные настройки; все копии карточки получают `settings.changed`. Неверные значения — `INVALID_PARAMS`. Не больше 60 в минуту. |
| `open()` | Открывает форму настроек на карточке. `NOT_VISIBLE`, если карточки нет на экране. |
| `onChange(handler)` | Пользователь сохранил форму, или `set` что-то поменял. |

**Области.** У поля с `"scope": "package"` одно значение на все копии вашей карточки; остальные —
свои у каждой карточки.

**Секреты.** Поле `secret` вводится только в собственном диалоге приложения — в форме настроек его
строка показывает лишь «задан» или «не задан» и открывает этот диалог на всё окно, — и хранится
приложением в зашифрованном виде. Карточка никогда не может его прочитать — ни через `values`, ни
каким-либо методом. Чтобы им воспользоваться, вставьте `{{secret:<key>}}` в
[заголовок сетевого запроса](https://docs.neurosquad.ai/ru/card-sdk/api/network#secrets); приложение подставит значение на выходе,
и только для хостов в интернете, выданных вашей карточке (никогда для `localhost`). Не делайте
внутри карточки собственное поле «вставьте ваш API-ключ»: тогда утечь ключ сможет уже по вашей вине,
а пользователям сказано, что NeuroSquad никогда не спрашивает ключи внутри карточки.

---

## Тема, язык и жизненный цикл

> Как следовать теме и языку приложения на лету, видимость и усыпление, воркспейс, необязательные разрешения во время работы и журнал карточки.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/environment

### Тема

`connect()` записывает живую тему приложения в `<html>` вашей страницы как CSS-переменные и держит их
актуальными:

- `--ns-<token>` для каждого токена: `background`, `background-secondary`, `background-tertiary`,
`foreground`, `muted`, `surface`, `surface-foreground`, `surface-secondary`,
`surface-secondary-foreground`, `surface-tertiary`, `surface-tertiary-foreground`, `overlay`,
`overlay-foreground`, `default`, `default-foreground`, `accent`, `accent-foreground`,
`accent-soft`, `accent-soft-foreground`, `success`, `success-foreground`, `success-soft`,
`warning`, `warning-foreground`, `warning-soft`, `danger`, `danger-foreground`, `danger-soft`,
`border`, `border-secondary`, `separator`, `focus`, `link`, `field-background`,
`field-foreground`, `field-placeholder`, `field-border`, `radius`, `field-radius`;
- `--ns-font-sans`, `--ns-font-mono` — наборы шрифтов приложения (сами шрифты не передаются:
кладите свои в пакет или используйте системные);
- `color-scheme` и `data-ns-scheme="dark"` на `<html>`.

```css
.panel {
  background: var(--ns-surface);
  color: var(--ns-surface-foreground);
  border: 1px solid var(--ns-border);
  border-radius: var(--ns-radius);
  font-family: var(--ns-font-sans);
}
.panel--alert { background: var(--ns-danger-soft); color: var(--ns-danger); }
```

В коде `card.theme` — это `ThemeSnapshot` (`scheme`, `tokens`, `fontSans`, `fontMono`),
поддерживается в актуальном виде; `card.on('theme.changed', …)` сообщает об изменении, а
`applyTheme(snapshot, element)` записывает переменные куда угодно (например, в shadow root).

> Сегодня приложение тёмное, поэтому `scheme` всегда `dark`, — но не зашивайте это: пользуйтесь
> переменными, и светлая тема просто заработает, когда появится. Руководство по оформлению —
> [UI-кит и оформление](https://docs.neurosquad.ai/ru/card-sdk/styling).

### Язык

Приложение говорит по-английски, по-русски и на упрощённом китайском и переключается на лету.
`card.i18n` — это `{ language: 'en' | 'ru' | 'zh', locale }` (`locale` — `en-US`, `ru-RU` или
`zh-CN`, для `Intl`), `<html lang>` следует за ним, а тексты из вашего манифеста (`displayName`,
подписи, описания) приложение подставляет само.

Для ваших собственных строк `createTranslator` следует за языком приложения на лету:

```ts
import { createTranslator } from '@neurosquad/card-sdk'

const t = createTranslator(
  {
    en: { title: 'Tests', failed_one: '{{count}} test failed', failed_other: '{{count}} tests failed' },
    ru: {
      title: 'Тесты',
      failed_one: '{{count}} тест упал',
      failed_few: '{{count}} теста упало',
      failed_many: '{{count}} тестов упало',
      failed_other: '{{count}} теста упало'
    },
    zh: { title: '测试', failed_other: '{{count}} 个测试失败' }
  },
  card
)

render(t('title'), t('failed', { count: 3 }))
t.onChange(() => render(t('title')))   // re-render on a language switch

const when = new Intl.DateTimeFormat(card.i18n.locale, { timeStyle: 'short' }).format(Date.now())
render(when)
```

- Ключи могут быть вложенными (`{ list: { empty: '…' } }` → `t('list.empty')`); `en` обязателен и
служит запасным языком, а за ним — сам ключ.
- Подстановки `{{name}}` заполняются из второго аргумента; числа форматируются по локали.
- При `count` формы множественного числа `key_one`, `key_few`, `key_many`, `key_other` выбираются
через `Intl.PluralRules` — в русском используются все четыре, в китайском только `_other`.
- `t.language`, `t.locale`, `t.onChange(fn)`, `t.setLanguage(lang)`, `t.dispose()`.

### Жизненный цикл и видимость

Холст на 50 карточек не может гонять 50 веб-приложений на полной скорости, поэтому приложение
сообщает карточке, где она, и ставит её на паузу, когда её никто не видит.

| `card.visibility` | Значение | Что делать |
| --- | --- | --- |
| `visible` | На экране, тело показано. | Работать. |
| `offscreen` | Её воркспейс показан, но карточка вне видимой области. | Остановить анимации и опрос. |
| `overview` | Холст отдалён: приложение показывает вашу [плитку обзора](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#overview) вместо тела. | Остановить анимации; держать плитку актуальной. |
| `hidden` | Её воркспейс не показан или окно скрыто. | Остановить всё, что нужно только для глаз. |

```ts
card.lifecycle.onVisibility((state) => {
  if (state === 'visible') startAnimation()
  else stopAnimation()
})

card.lifecycle.onSuspend(async (graceMs) => {
  // The page is about to be unloaded. You have graceMs (about a second) to save.
  await card.storage.set('draft', currentDraft())
})

card.lifecycle.onExpanded((expanded) => render(expanded ? 'big layout' : 'compact layout'))
card.lifecycle.onResized(({ w, h }) => render(w, h))

if (card.launch === 'resumed') render('back from a pause — state restored from storage')

declare function startAnimation(): void
declare function stopAnimation(): void
declare function currentDraft(): string
```

**Усыпление.** Карточку, чей воркспейс скрыт уже минуту, усыпляют: она получает `lifecycle.suspend`,
у неё есть примерно секунда (`graceMs`), чтобы сохраниться, потом её страница выгружается.
Приложение продолжает показывать её шапку и [плитку обзора](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#overview). Когда
пользователь снова на неё смотрит, страница запускается заново с `card.launch === 'resumed'`. Во всём
приложении одновременно работает не больше 24 страниц карточек; сверх этого усыпляются и те
карточки вне экрана или в скрытых воркспейсах, что дольше всех не показывались. Карточки с
разрешением [`background`](https://docs.neurosquad.ai/ru/card-sdk/permissions#background) не усыпляются, когда скрыты (до 8 во
всём приложении).

**Ленивый запуск.** Страница карточки создаётся, когда карточку впервые действительно видно в
показанном воркспейсе, а не при открытии воркспейса. До этого в теле заглушка, а в шапке — то, что
вы задали в прошлый раз.

**Что ещё нужно знать**

- Инструменты и входы-запросы **будят** усыплённую карточку: прежде чем доставить вызов,
приложение запускает её страницу (ждёт до 10 секунд). Потоковые сообщения усыплённой карточке
отбрасываются — используйте `retain` на выходах, чтобы карточка могла догнать через `ports.read`.
- Пока холст перетаскивают или масштабируют, ваша карточка не получает событий мыши.
- Колесо мыши внутри карточки прокручивает карточку, а не холст. Горячие клавиши приложения не
работают, пока фокус внутри карточки.
- Карточка, которая 15 секунд не отвечает на пульс приложения, показывается как **Not responding**
с кнопкой Reload. SDK отвечает на пульс сам; причиной обычно бывает долгий синхронный цикл в вашем
коде.
- Каждый отдельный пакет карточек — это один процесс браузера (~30–60 МБ); копии одной карточки
делят его.

**События не воспроизводятся заново.** Пока страница карточки не работает — ещё не смонтирована,
усыплена или выгружена, — она пропускает события вроде `agents.turn`. При старте восстанавливайте
показанное из `card.agents.list()` (`status`, `turnStartedAt` и `lastTurn` — когда и чем закончился
последний ход) и из сохраняемых значений портов, а не рассчитывайте, что видели каждое событие.

### Воркспейс

```ts
const workspace = await card.getWorkspace()  // { id, name, path? }
render(workspace.name, workspace.path ?? 'no fs.read — no path')
```

`card.workspace` содержит то же и поддерживается в актуальном виде. `path` (абсолютный) есть только
при `fs.read`.

### Разрешения во время работы

```ts
async function copyReport(text: string): Promise<boolean> {
  if (!card.permissions.has('clipboard.write')) {
    // Declared with "optional": true in the manifest. Only while the card is visible.
    const granted = await card.permissions.request('clipboard.write')
    if (!granted.includes('clipboard.write')) return false
  }
  await card.copyText(text)
  return true
}

card.permissions.onChange((all) => render(all.filter((p) => p.granted).map((p) => p.id)))
```

| Член | Что это |
| --- | --- |
| `all` | Все объявленные разрешения: `{ id, granted, optional, hosts?, reason? }`. Поддерживается в актуальном виде. |
| `has(id)` | Выдано напрямую или через включение (`fs.write` включает `fs.read`). |
| `list()` | Свежий список из приложения. |
| `request(...ids)` | Просит у пользователя **необязательные** объявленные разрешения (в диалоге приложения на всё окно). Возвращает идентификаторы, выданные сейчас. Только пока карточка видна, не чаще раза в 5 секунд; запрос того, что не объявлено как необязательное, падает с `PERMISSION_DENIED`. |
| `onChange(handler)` | Выдача изменилась — пользователь выдал разрешение или отозвал его в настройках. |

### Журнал карточки

```ts
card.log.info('run started', { filter: 'checkout' })
card.log.warn('slow response', 1834, 'ms')
card.log.error(new Error('parser failed'))
```

Строки попадают в журнал пакета в приложении (`card-logs`, 256 КБ, по кругу) и — пока запущен
`neurosquad-card dev` — в ваш терминал. Аргументы склеиваются как в `console.log` (объекты — как
JSON, ошибки — со стеком), до 2 000 символов в строке, не больше 50 строк в секунду — сверх этого
строки отбрасываются и пишется одно предупреждение «N lines dropped». Необработанные ошибки и
отклонённые промисы автоматически пишутся как `error` (чтобы отключить, передайте
`forwardErrors: false` в `connect()`).

---

## Агенты и терминалы

> Список агентов и их живой статус, события ходов, чтение экранов подключённых агентов, отправка промптов и запуск команд в подключённых терминалах.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/agents

### Список агентов

Нужно разрешение [`agents.read`](https://docs.neurosquad.ai/ru/card-sdk/permissions#agents-read).

```ts
import type { AgentInfo } from '@neurosquad/card-sdk'

const agents: AgentInfo[] = await card.agents.list()
const waiting = agents.filter((a) => a.kind === 'ai' && a.status === 'needs-input')
const one = await card.agents.get(agents[0].id)
render(waiting.map((a) => a.name), one.model ?? 'default model')
```

Все ИИ-агенты и терминалы воркспейса карточки (другие карточки агентами не считаются):

| Поле | Тип | Значение |
| --- | --- | --- |
| `id` | `string` | Идентификатор карточки на холсте. |
| `name` | `string` | То, что видит пользователь. |
| `harness` | `string` | `claude-code`, `codex-cli`, `opencode`, `qwen-code`, `shell-bash`, `shell-powershell`, `shell-cmd`… |
| `kind` | `'ai'` или `'shell'` | ИИ-агент или терминал. |
| `status` | `AgentStatus` | `working`, `needs-input`, `finished`, `idle` или `exited`. |
| `connected` | `boolean` | С вашей карточкой его соединяет стрелка. |
| `sessionTitle` | `string?` | Заголовок, который агент дал своей сессии. |
| `turnStartedAt` | `number?` | Время начала текущего хода (мс с эпохи), пока статус `working`. |
| `lastTurn` | `{ startedAt, endedAt, endedAs }?` | Последний завершённый ход с момента запуска приложения: время в мс с эпохи (`startedAt` может быть `null`) и `endedAs` — `finished` или `needs-input`; чтобы догнать ходы, пропущенные, пока карточка не работала. |
| `model` | `string?` | Модель, на которой он работает, если известна. |

Статусы берутся из того же трекера, что и в остальном приложении, — для Claude Code из его
собственных хуков (для OpenCode и Kilo Code — из плагина NeuroSquad, для Hermes Agent — из его вебхуков жизненного цикла), поэтому `needs-input` («ждёт вашего разрешения») и `finished` различаются точно.

### События

```ts
card.agents.onStatus(({ agentId, status }) => render(agentId, status))
card.agents.onTurn(({ agentId, phase, at }) => render(agentId, phase, new Date(at)))
card.agents.onChanged((agents) => render(agents.length))   // added, removed or renamed

// Only one agent:
card.agents.onStatus((e) => render(e.status), agentId)
```

- `agents.status` — `{ agentId, status, at }` при каждой смене статуса.
- `agents.turn` — `{ agentId, phase: 'start' | 'end', at }`. Ход начинается, когда промпт отправлен,
и заканчивается, когда агент закончил или ждёт ввода.
- `agents.changed` — `{ agents }`, весь новый список.

SDK подписывается, пока у вас есть слушатели. Каждый метод возвращает функцию, которая убирает
слушателя.

### Чтение вывода

Нужно разрешение [`agents.output`](https://docs.neurosquad.ai/ru/card-sdk/permissions#agents-output) и **стрелка** между вашей
карточкой и агентом или терминалом.

```ts
// The visible screen, as text (up to 500 lines).
const screen = await card.agents.readScreen(agentId, 80)

// The last reply, from the agent's own session log (Claude Code, OpenCode, Kilo Code, Hermes Agent). null for others.
const { text, at } = await card.agents.lastReply(agentId)

// Live output: ANSI colours stripped, delivered in chunks about every 100 ms.
const stop = card.agents.onOutput([agentId, shellId], ({ agentId: from, text: chunk }) => {
  if (chunk.includes('FAIL')) render(`${from} printed a failure`)
})
stop() // when you no longer need it

render(screen, text, at)
```

Для агента без стрелки эти вызовы падают с `NOT_CONNECTED`. `readScreen` для незапущенного агента
падает с `UNAVAILABLE`.

### Промпты агентам

Нужно разрешение [`agents.prompt`](https://docs.neurosquad.ai/ru/card-sdk/permissions#agents-prompt) и стрелка к **ИИ**-агенту
(терминалам отправляют [команды](#terminals)).

```ts
import { isCardSdkError } from '@neurosquad/card-sdk'

try {
  const delivered = await card.agents.prompt(agentId, 'Run the checkout tests and fix what fails.')
  // 'sent'    — submitted now
  // 'queued'  — the agent is working; it goes out when the turn ends
  // 'inserted'— typed in only (submit: false); the user presses Enter
  card.ui.toast(delivered === 'queued' ? 'Queued after the current turn' : 'Sent')
} catch (error) {
  if (isCardSdkError(error, 'NOT_CONNECTED')) card.ui.toast('Draw an arrow from me to an agent')
  else if (isCardSdkError(error, 'BUDGET_PAUSED')) card.ui.toast('The workspace is over its budget')
  else if (isCardSdkError(error, 'USER_CANCELLED')) card.ui.toast('Not sent')
  else throw error
}
```

Параметры — `card.agents.prompt(agentId, text, { submit, whenBusy })`:

| Параметр | По умолчанию | Значение |
| --- | --- | --- |
| `submit` | `true` | `false` набирает текст в поле ввода агента, не нажимая Enter, — пользователь проверяет и отправляет сам. Результат `inserted`. |
| `whenBusy` | `'queue'` | Пока агент работает: `queue` ставит в [очередь промптов](https://docs.neurosquad.ai/ru/agents/queue) агента (`queued`), `send` отправляет всё равно (`sent`), `fail` отказывает с `BUSY`. |

Что приложение делает с каждым промптом:

- Он идёт тем же путём, что и очередь промптов и [бюджет](https://docs.neurosquad.ai/ru/cards/budget): если воркспейс вышел за
бюджет, вызов падает с `BUDGET_PAUSED` (человек, набирающий руками, не ограничен — ваша карточка
ограничена).
- Он виден на стрелке и в её [журнале](https://docs.neurosquad.ai/ru/canvas/arrows#arrow-log) с именем вашей карточки.
- Агенту в [опасном режиме](https://docs.neurosquad.ai/ru/agents/dangerous-mode) приложение сначала показывает промпт в своём
диалоге на всё окно и ждёт **Send prompt**; если пользователь откажется — `USER_CANCELLED`; если
вашей карточки нет на экране — `NOT_VISIBLE`.
- Не больше 6 промптов в минуту на карточку — вместе с промптами, отправленными через порт агента
`prompt`, — до 20 000 символов каждый.
- Промптов от карточек в очереди — не больше 10 на агента; видно, от какой карточки каждый, и они
выбрасываются до отправки, если пропала стрелка, разрешение, сама карточка или её пакет или агента
перевели в опасный режим.

> Промпт — это указание тому, кто может править файлы и запускать команды. Никогда не пересылайте в
> промпт текст из интернета, файла или другой карточки, не показав его сначала пользователю, — именно
> так и происходит внедрение промптов (prompt injection). Если текст не ваш, лучше `submit: false`.

### Прогон одного агента

С NeuroSquad 0.1.254 (SDK 1.1). Нужно разрешение [`usage.read`](https://docs.neurosquad.ai/ru/card-sdk/permissions#usage-read)
и стрелка к ИИ-агенту. Сначала проверьте `card.host.supports('agents.usage')`: старое приложение
ответит `METHOD_NOT_FOUND`.

```ts
const run = await card.agents.usage(agentId, since /* мс эпохи */, until /* необязательно, по умолчанию сейчас */)
```

Возвращает цифры этого агента в окне — те же, из которых строится раздел «Расход» приложения. Ваш
фрейм может стоять на паузе или быть выгружен, пока агент работает: историю статусов ведёт само
приложение, поэтому время считается верно.

| Поле | Значение |
| --- | --- |
| `prompts` | Сколько ходов дали агенту. Ответ на запрос разрешения продолжает тот же ход. |
| `requests` | Запросы к модели (обращения к API), записанные харнессом в окне. |
| `inputTokens` / `outputTokens` | Некешированный ввод; вывод вместе с рассуждениями (`reasoningTokens` — их часть). |
| `cacheReadTokens` / `cacheWriteTokens` | Работа с кешем — там, где харнесс и провайдер о ней сообщают. |
| `totalTokens` | Ввод + вывод + чтение кеша + запись в кеш. |
| `elapsedMs` | От первого промпта до последнего завершения (до текущего момента, пока идёт ход). |
| `workingMs` | Сколько агент работал; ожидание пользователя не входит. |
| `costMicroUsd` | Стоимость, записанная харнессом, иначе по прайсу; `null`, если цена неизвестна. |
| `model`, `provider`, `status`, `timingComplete` | Контекст для цифр. |

> `null` значит **не сообщается**: в журнале харнесса нет такого числа (некоторые не пишут запись в
> кеш или рассуждения), локальный сервер не прислал счётчики кеша или приложение вообще не читает
> журнал расхода этого харнесса (Amp, Cursor). Показывайте «не сообщается», а не 0. Токены — точные
> целые числа.

### Терминалы

Нужно разрешение [`terminals.write`](https://docs.neurosquad.ai/ru/card-sdk/permissions#terminals-write) и стрелка к карточке
терминала (bash, PowerShell или cmd).

```ts
// Run a command and wait for it to finish.
const result = await card.terminals.run(shellId, 'npm test -- --reporter=dot', { timeoutMs: 120_000 })
if (result.timedOut) render('still running after 2 minutes')
else render(result.exitCode === 0 ? 'passed' : `failed with ${result.exitCode}`, result.output)

// Or just type into it (and press Enter).
await card.terminals.write(shellId, 'git status', { submit: true })
```

| | `run(agentId, command, { timeoutMs? })` | `write(agentId, text, { submit? })` |
| --- | --- | --- |
| Делает | Выполняет одну команду и ждёт, пока вернётся приглашение | Набирает текст; `submit: true` нажимает после него Enter |
| Возвращает | `{ exitCode, output, truncated, timedOut }` | ничего |
| Лимиты | тайм-аут 1–120 с (по умолчанию 120), вывод до 64 КБ; 30 команд в минуту на карточку, вместе с портом терминала `command` | 60 в минуту |

В cmd `exitCode` равен `null` — cmd его не сообщает. Пользователь видит каждую команду в самом
терминале и на стрелке. Бюджет агентов на команды не распространяется — терминал не ИИ-агент, — но
они выполняются со всеми правами пользователя: см. [чек-лист безопасности](https://docs.neurosquad.ai/ru/card-sdk/security).

---

## Порты: карточки говорят с карточками

> Типизированные входы и выходы по стрелкам — общеизвестные типы и свои типы на JSON Schema, emit, send, запрос и ответ, сохраняемые значения, как узнать, что принимает подключённая карточка, и порты встроенных заметки, списка задач, доски задач, стикера, агента и терминала.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/ports

Порты позволяют карточке обмениваться **типизированными данными** с карточками, соединёнными с ней
стрелками: ваш радар тестов отправляет упавшие тесты в список задач, заметка передаёт свой текст
вашему резюмирующему инструменту, две свои карточки договариваются о собственном формате. Порты
объявляются в [манифесте](https://docs.neurosquad.ai/ru/card-sdk/manifest#ports); приложение само маршрутизирует, преобразует и
проверяет каждое значение.

### Направление

Стрелка **от карточки A к карточке B** несёт **выходы** A на **входы** B. Если карточки соединены в
обе стороны, данные идут в обе стороны. (Инструментам и разрешениям агентов направление не важно,
портам — важно.)

`card.ports.peers` перечисляет все карточки, соединённые с вашей, с полем `direction`:

- `downstream` — ваша карточка → соседняя: ваши выходы доходят до её входов;
- `upstream` — соседняя → ваша: её выходы доходят до ваших входов;
- `both` — в обе стороны.

### Типы

У каждого порта есть тип: **общеизвестный** `ns:*` или **свой** `<package-name>/<type-name>` с JSON
Schema.

| Тип | Значение |
| --- | --- |
| `ns:any` | Любой JSON. Как вход принимает любой тип выхода без изменений. |
| `ns:text` | Строка (до 1 000 000). |
| `ns:markdown` | Строка Markdown (до 1 000 000). |
| `ns:number` | Число. |
| `ns:boolean` | `true` или `false`. |
| `ns:json` | Объект или массив. |
| `ns:url` | Строка URI. |
| `ns:image` | `{ mimeType, data, alt? }` — PNG, JPEG, WebP или GIF в base64, не больше ~700 КБ. |
| `ns:file-ref` | `{ path, line? }` — файл в папке воркспейса. Получение такого значения не даёт доступа к файлам. |
| `ns:task` | `{ text, id?, status?, column?, assignee? }` — `status`: `pending`, `active`, `done` или `error`. |
| `ns:tasks` | Массив до 200 `ns:task`. |
| `ns:task-patch` | `{ ref, text?, status?, column? }` — изменить одну задачу; `ref` — её идентификатор или точный текст. |
| `ns:table` | `{ columns: string[], rows: (string, number, boolean or null)[][] }` |
| `ns:event` | `{ type, data?, at? }` |
| `ns:trigger` | Пустой сигнал: `{}` или `null`. |

**Свой тип** называется по имени вашего пакета — `test-radar/coverage` — и обязан иметь `schema`
([безопасное подмножество](https://docs.neurosquad.ai/ru/card-sdk/manifest#json-schema), без `pattern`). Другая карточка может
объявить тот же тип, чтобы работать с вашей. Любой порт может добавить `schema` поверх своего типа;
значение должно подходить под обе.

### Отправка: `emit`

```ts
const delivered = await card.ports.emit('failures', [
  { text: 'checkout › pays with a saved card', status: 'error' },
  { text: 'auth › logs in with SSO', status: 'error' }
])
if (delivered === 0) card.ui.toast('Connect me to a todo list to track these')
```

Значение проверяется по схемам выхода и доставляется **каждой соседней карточке ниже по стрелке**,
у которой есть совместимый вход. У каждой из них приложение выбирает вход: помеченный `default`,
иначе вход ровно того же типа, иначе первый совместимый (входы-запросы через `emit` не выбираются
никогда). Если типы различаются, значение преобразуется (см. ниже) и проверяется по схемам этого
входа. Вы получаете число карточек, которые его приняли.

Чтобы отправить одной конкретной карточке и, при желании, в конкретный вход:

```ts
await card.ports.send(noteId, 'summary', '## Nightly run\n\nAll green.', { input: 'replace' })
```

### Приём

```ts
card.ports.onMessage<string>((text, message) => {
  render(`${message.fromKind} card ${message.from} sent ${message.type} on ${message.output}`, text)
}, { input: 'notes' })
```

`message` — это `{ from, fromKind, output, input, type, sourceType, data, at }`: `type` — тип
**вашего** входа (после преобразования), `sourceType` — объявленный тип выхода отправителя до
преобразования (в старых версиях приложения отсутствует). Без `input` вы получаете значения со всех
входов. Сообщения, пришедшие до подписки, сохраняются (до 100) и доставляются первому слушателю.

### Преобразование типов

Выход доходит до входа другого типа, только если для этой пары есть преобразование:

| Тип входа | Принимает выходы типа | Как |
| --- | --- | --- |
| тот же тип | тот же тип | без изменений |
| `ns:any` | любые | без изменений |
| `ns:text` | `markdown`, `url` | без изменений |
|  | `number`, `boolean` | `String(value)` |
|  | `json` | отформатированный JSON |
| `ns:markdown` | `text`, `url` | без изменений |
|  | `number` | `String(value)` |
|  | `json` | блок кода `json` |
|  | `table` | таблица Markdown |
|  | `tasks` | чек-лист (`- [x] done`, `- [ ] open`) |
| `ns:tasks` | `task` | оборачивается в массив |
|  | `text`, `markdown` | по задаче на каждую непустую строку (маркеры списков и чекбоксы убираются) |
| `ns:json` | `table`, `tasks`, `task`, `event`, `file-ref`, `task-patch` | без изменений |
| `ns:trigger` | `event`, `text`, `number`, `boolean`, `json` | становится `{}` — «что-то произошло» |

Свои типы совпадают только с тем же своим типом (или с `ns:any`). Помощники `portsCompatible`,
`portCoercion`, `coercePortValue` и `pickInputFor` экспортируются из SDK, если хотите рассуждать об
этом сами.

### Запросы: спросить и ответить

Вход с `"mode": "request"` отвечает на вопросы. Тип ответа объявляется в `response`:

```json
{ "id": "lookup", "label": "Look up", "type": "ns:text", "mode": "request",
  "response": { "type": "ns:json" } }
```

```ts
// The answering card:
card.ports.onRequest<string>('lookup', async (query, request) => {
  const hits = await search(query, request.signal)   // request.signal aborts at the deadline
  return { query, hits }                               // checked against response.type
})

// The asking card (connected to it by an arrow, either direction):
const answer = await card.ports.request<{ hits: string[] }>(peerId, 'lookup', 'flaky tests', {
  timeoutMs: 10_000
})
render(answer.hits)

declare function search(q: string, signal: AbortSignal): Promise<string[]>
declare const peerId: string
```

Исключение в обработчике возвращает ошибку; промис спрашивающего отклоняется. Запросы, пришедшие
до регистрации обработчика, ждут почти до своего дедлайна, а потом получают «no handler». Тайм-аут
по умолчанию 30 с, максимум 120 с (`TIMEOUT`). Запрос к усыплённой карточке будит её (до 10 с) или
падает с `UNAVAILABLE`.

### Сохраняемые значения

Пометьте выход `"retain": true`, и приложение будет хранить его последнее значение (до 256 КБ):

- карточка, подключённая **позже**, сразу получает его один раз;
- любая подключённая карточка может прочитать его в любой момент, куда бы ни смотрела стрелка:

```ts
const last = await card.ports.read<{ text: string }[]>(todoId, 'items')
if (last) render(`${last.data.length} items, as of ${new Date(last.at).toLocaleTimeString()}`)

declare const todoId: string
```

Именно через сохраняемые значения карточка догоняет события после усыпления — потоковые
сообщения, отправленные, пока её страница была выгружена, в очередь не ставятся.

### Кто подключён: обнаружение

Карточка может узнать, что выдают и принимают подключённые к ней карточки — включая встроенные, —
и подстроиться:

```ts
import type { PeerInfo } from '@neurosquad/card-sdk'

function describePeer(peer: PeerInfo): string {
  const ins = peer.inputs.map((p) => `${p.id}:${p.type}`).join(', ') || 'none'
  const outs = peer.outputs.map((p) => `${p.id}:${p.type}`).join(', ') || 'none'
  return `${peer.name} (${peer.kind}, ${peer.direction}) — in: ${ins}; out: ${outs}`
}

card.ports.peers.forEach((peer) => render(describePeer(peer)))
card.ports.onPeersChanged((peers) => render(peers.map(describePeer)))

// Is there a checklist downstream that takes tasks?
const taskSink = card.ports.peers.find(
  (p) => p.direction !== 'upstream' && p.inputs.some((i) => i.type === 'ns:tasks')
)
render(taskSink?.name ?? 'no task list connected')
```

`PeerInfo` — это `{ cardId, kind, name, type?, direction, inputs, outputs }`. `kind` — `custom`,
`note`, `todo`, `kanban`, `sticky`, `agent`, `terminal` или `other` (карточка без портов, например
браузер). `type` — харнесс для агентов и терминалов, имя пакета для своих карточек. Каждый порт —
это `PortInfo`: `{ id, label, description?, type, schema?, mode, response?, retain, default,
permission? }`; `permission` задан у портов встроенных карточек и называет, что нужно **вашей**
карточке, чтобы им пользоваться.

Ваши собственные порты: `card.ports.inputs`, `card.ports.outputs` или `card.ports.describe()`.

Три помощника покрывают то, что нужно большинству карточек перед отправкой:

```ts
import { hasDownstreamPeer, permissionForPeer, requestPermissions } from '@neurosquad/card-sdk'

async function sendSummary(text: string): Promise<void> {
  if (!hasDownstreamPeer(card.ports.peers)) {
    card.ui.toast('Draw an arrow from this card to a note')
    return
  }
  // Which permission does sending Markdown to each peer need? (cards.connected for a note)
  const needed = card.ports.peers
    .map((peer) => permissionForPeer(peer, { outputType: 'ns:markdown' }))
    .filter((id) => id !== null)
  // Asks only for what is missing; never throws — resolves with what is usable now.
  const usable = await requestPermissions(card, ...needed)
  if (usable.length === needed.length) await card.ports.emit('summary', text)
}
```

### Встроенные карточки

Собственные карточки приложения участвуют через адаптеры. Для работы с ними нужно разрешение из
последней колонки — у **вашей** карточки.

| Карточка | Входы | Выходы | Нужно |
| --- | --- | --- | --- |
| Заметка | `append` (`ns:markdown`, по умолчанию): добавляет абзац в конец · `replace` (`ns:markdown`): заменяет всю заметку | `text` (`ns:markdown`, сохраняется): заметка, при каждом изменении | `cards.connected` |
| Список задач | `add` (`ns:tasks`, по умолчанию): добавляет пункты · `update` (`ns:task-patch`): меняет текст или статус одного пункта | `items` (`ns:tasks`, сохраняется): все пункты, при каждом изменении | `cards.connected` |
| Доска задач | `add` (`ns:tasks`, по умолчанию): добавляет задачи без исполнителя · `update` (`ns:task-patch`): переносит или правит одну задачу | `tasks` (`ns:tasks`, сохраняется): все задачи с их колонками | `cards.connected` |
| Стикер | `title` (`ns:text`, по умолчанию): задаёт заголовок | `title` (`ns:text`, сохраняется) | `cards.connected` |
| ИИ-агент | `prompt` (`ns:text`, по умолчанию): отправляет промпт — ровно как [`agents.prompt`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#prompting) с параметрами по умолчанию | `status` (`ns:event`, сохраняется): `{ type: "status", data: { status } }` | `agents.prompt` / `agents.read` |
|  |  | `reply` (`ns:markdown`, сохраняется): итоговое сообщение в конце хода — Claude Code и Hermes Agent | `agents.output` |
| Терминал | `command` (`ns:text`, по умолчанию): выполняет одну команду | `exit` (`ns:event`): `{ type: "exit", data: { command, exitCode } }` после каждой команды | `terminals.write` / `agents.output` |

Так, если от вашей карточки к заметке идёт стрелка, `card.ports.emit('summary', '# Done')` допишет в
неё абзац; если от списка задач к вашей карточке, ваш вход `ns:tasks` будет получать каждое
изменение списка.

### Лимиты

Значение до 1 МБ (сохраняемое — до 256 КБ); не больше 20 сообщений в секунду на выход. Значение,
не прошедшее схему, отклоняется с `INVALID_PARAMS` и точным путём — приложение никогда не доставит
то, что не соответствует объявленному получателем.

> Между двумя своими карточками порты не требуют разрешений: согласие — это стрелка, которую провёл
> пользователь. Данные идут только по стрелкам, только из объявленных выходов в объявленные входы и
> только в направлении стрелки.

---

## Инструменты для агентов (MCP)

> Объявите инструмент в манифесте, реализуйте его в карточке — и подключённые агенты смогут вызывать его через MCP-сервер NeuroSquad; результаты, картинки, ошибки, прогресс, отмена и тайм-ауты.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/tools

Карточка может дать агентам новые возможности. Объявите инструмент в манифесте, реализуйте его в
карточке — и каждый агент, соединённый с карточкой стрелкой, увидит его в своём списке инструментов
через MCP-сервер, который приложение и так запускает для своих агентов (Claude Code, Codex, Qwen
Code). Разрешение не нужно: согласие — это стрелка, которую проводит пользователь.

### Объявить

```json
"tools": [
  {
    "name": "run_tests",
    "title": "Run the tests",
    "description": "Runs the project's tests in the connected terminal and returns the failing tests with their messages, or 'All tests passed'.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "filter": { "type": "string", "maxLength": 200, "description": "Only tests whose name contains this" }
      }
    },
    "timeoutMs": 120000
  }
]
```

Агент видит его как **`<card name with - → _>_<tool>`** — `test_radar_run_tests` для карточки с именем
`test-radar` — с вашей `inputSchema` и необязательным аргументом `card`, который добавляет приложение
(идентификатор или имя — чтобы выбрать одну карточку, когда подключено несколько копий). Описание
доходит до модели с префиксом `[Custom card "<displayName>" by <author>, community code]`. Если два
пакета дадут одно и то же имя, его сохраняет установленный первым, а более поздний получает `_2`,
`_3`.

Имена, которые приложение не пропустит при установке: итоговое имя, совпадающее с собственным
инструментом NeuroSquad (`canvas_spawn_card`, `terminal_send_keys`, `browser_navigate`…), любое имя
с `__` (зарезервировано за MCP-серверами, которые ставит пользователь), и `name` карточки, совпадающий
со встроенным семейством вроде `telegram`, `squad`, `ports` или `mcp` (см.
[зарезервированные имена](https://docs.neurosquad.ai/ru/card-sdk/manifest#identity)). Обновление, которое добавляет инструмент или
меняет формулировку его описания, снова спрашивает пользователя.

Пишите описание для модели: что инструмент делает, когда его использовать и что он возвращает.
Аргументов — поменьше и с ограничениями (`enum`, `maxLength`, `minimum`…); приложение проверяет их
до того, как их увидит ваша карточка.

### Реализовать

```ts
import { toolError } from '@neurosquad/card-sdk'

card.tools.handle<{ filter?: string }>('run_tests', async ({ filter }, call) => {
  call.progress('running the tests…')                  // shown on the arrow
  const terminal = (await card.agents.list()).find((a) => a.kind === 'shell' && a.connected)
  if (!terminal) return toolError('Connect a terminal card to the Test radar card first.')

  const result = await card.terminals.run(terminal.id, `npm test -- ${filter ?? ''}`, {
    timeoutMs: 110_000
  })
  if (call.signal.aborted) return                       // the agent gave up; nothing is sent
  return result.exitCode === 0 ? 'All tests passed' : result.output
})
```

Обработчик получает проверенные аргументы и объект `call`:

| `call.` | Что это |
| --- | --- |
| `callId` | Идентификатор вызова. |
| `tool` | Имя инструмента, как в вашем манифесте. |
| `agent` | `{ id, name }` вызывающего агента. |
| `deadline` | Время (мс с эпохи), после которого приложение перестаёт ждать. |
| `signal` | `AbortSignal`, срабатывает при отмене или по дедлайну. |
| `progress(message)` | Короткая строка (до 200 символов) на стрелке, пока вы работаете; не чаще 4 раз в секунду. |

**То, что вы возвращаете,** становится результатом инструмента:

| Возвращаете | Агент получает |
| --- | --- |
| строку | этот текст |
| `undefined` | `OK` |
| любое другое значение JSON | отформатированный JSON текстом |
| `toolText(text)` | текст (то же, что строка) |
| `toolImage(base64, 'image/png', caption?)` | картинку и подпись текстом |
| `toolError(message)` | неудачный результат (`isError: true`), который модель может прочитать и учесть |
| `ToolResultPayload` | ровно его: `{ content: [{ type: 'text', text } or { type: 'image', data, mimeType }], isError? }`, 1–16 частей |

**Исключение** тоже возвращает агенту ошибку — с текстом ошибки (и пишет предупреждение в журнал
карточки). Результат — до 1 МБ.

### Время

- Тайм-аут по умолчанию 30 с или `timeoutMs` инструмента (до 120 с). По дедлайну приложение сообщает
агенту, что время вышло, и отправляет карточке `tools.cancel` — `call.signal` срабатывает, а всё,
что вы вернёте после этого, отбрасывается.
- Вызовы, пришедшие до регистрации обработчика (например, пока карточка ещё грузит данные), ждут
`handle()` до своего дедлайна.
- Вызов к карточке, чья страница усыплена, будит её (до 10 с); если её воркспейс не открыт, агенту
говорят открыть воркспейс, где лежит эта карточка.
- Каждый вызов идёт по стрелке: её подпись показывает инструмент и ваши строки прогресса, а сам
вызов остаётся в [журнале стрелки](https://docs.neurosquad.ai/ru/canvas/arrows#arrow-log).

### Включить и выключить инструмент

```ts
await card.tools.setEnabled('run_tests', false) // hidden from agents (e.g. until the user signs in)
await card.tools.setEnabled('run_tests', true)
```

Это действует на все копии вашей карточки.

### С React

```tsx
import { useTool } from '@neurosquad/card-sdk/react'

export function Scratchpad({ text }: { text: string }) {
  useTool('read_scratchpad', () => text || '(empty)') // the latest `text` is always used
  return <pre>{text}</pre>
}
```

> Результаты инструментов попадают прямо в контекст агента. Всё, что вы возвращаете из интернета,
> файла или от пользователя, считайте недоверенным: указывайте, откуда это, держите коротким и
> никогда не позволяйте инструменту, который может вызвать агент, молча сделать что-то
> разрушительное — сначала спросите пользователя через `card.ui.confirm`.

---

## Сеть

> card.net.fetch — HTTP через прокси NeuroSquad к хостам, которые объявила карточка; ответы JSON, двоичные и потоковые, секреты в заголовках, редиректы и лимиты.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/network

Страница карточки вообще не может выйти в сеть — её песочница блокирует любой запрос, картинку или
шрифт не из пакета. Вместо этого `card.net.fetch` идёт через прокси в приложении, который
пропускает только то, что разрешил пользователь:

- [`network`](https://docs.neurosquad.ai/ru/card-sdk/permissions#network) с `hosts`: запросы `https` к этим хостам;
- [`network.local`](https://docs.neurosquad.ai/ru/card-sdk/permissions#network-local): `http` или `https` к `localhost`,
`127.0.0.1` и `::1` — кроме собственных локальных серверов NeuroSquad (его MCP-сервера, удалённого
доступа, подключения папок для разработчиков, портов отладки Chrome браузерных карточек): до них не
достучаться.

### Запрос

```ts
const res = await card.net.fetch('https://api.github.com/repos/acme/app/issues?state=open', {
  headers: { accept: 'application/vnd.github+json' },
  responseType: 'json'
})
if (!res.ok) throw new Error(`GitHub said ${res.status} ${res.statusText}`)
const issues = await res.json<{ number: number; title: string }[]>()
render(issues.map((i) => `#${i.number} ${i.title}`))
```

Выглядит как `fetch`, но с несколькими отличиями:

| Параметр | Значение |
| --- | --- |
| `method` | `GET` (по умолчанию), `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`. Тело без метода означает `POST`. |
| `headers` | Объект или пары `[name, value]`. Может содержать [`{{secret:<key>}}`](#secrets). |
| `body` | Строка (отправляется как есть), байты (`Uint8Array`, `ArrayBuffer`) или любое другое значение JSON (сериализуется, с `content-type: application/json`, если вы не задали свой). До 5 МБ. |
| `responseType` | `text` (по умолчанию), `json` (разбирает приложение), `base64` (двоичные данные) или `stream`. |
| `timeoutMs` | 1 000–120 000, по умолчанию 30 000. |
| `signal` | `AbortSignal`; отмена прерывает запрос в приложении. |

Результат — `CardResponse`: `ok`, `status`, `statusText`, `url` (после редиректов), `headers`
(`get`, `has`, перебираемые; имена в нижнем регистре), `truncated` и методы тела `text()`, `json()`,
`bytes()`, `arrayBuffer()`, `chunks()`, `lines()` — тело читается один раз, как у `Response`.

```ts
// POST JSON, read binary.
const upload = await card.net.fetch('https://api.example.com/v1/render', {
  method: 'POST',
  body: { chart: 'coverage', width: 640 },
  responseType: 'base64'
})
const png = await upload.bytes()
render(png.byteLength)
```

**Условные запросы и пустые ответы.** Условные заголовки вроде `If-None-Match` и
`If-Modified-Since` передаются, и возвращаются все заголовки ответа, кроме `set-cookie` (так что
`etag` и заголовки лимитов на месте). Пустое тело — `304 Not Modified` или `204 No Content` — при
`responseType: 'json'` даёт `null` из `res.json()`.

### Секреты в заголовках

Никогда не кладите API-ключ в код или хранилище карточки. Объявите [настройку](https://docs.neurosquad.ai/ru/card-sdk/manifest#settings)
типа `secret`, пусть пользователь введёт ключ в форме настроек приложения, и сошлитесь на него в
**значении заголовка**:

```ts
if (!card.settings.hasSecret('apiKey')) {
  await card.settings.open()
} else {
  const res = await card.net.fetch('https://api.example.com/v1/me', {
    headers: { authorization: 'Bearer {{secret:apiKey}}' },
    responseType: 'json'
  })
  render(await res.json())
}
```

Приложение подставляет вместо `{{secret:apiKey}}` сохранённый секрет (сначала этой карточки, потом
общий для пакета) на выходе — только в запросах к выданным хостам **в интернете**, никогда к этому
компьютеру (`network.local`). Ваша карточка значения не видит никогда. Подстановки работают только в
значениях заголовков — не в URL и не в теле, которые оседают в логах серверов, — а заголовки с
секретами **отбрасываются**, если редирект ведёт на другой хост. Подстановка секрета, который
пользователь не задал, падает с `INVALID_PARAMS`.

### Потоковые ответы

Для server-sent events, NDJSON или долгих загрузок запросите поток. Промис разрешается, как только
пришли заголовки; тело приходит кусками (до 64 КБ каждый):

```ts
const controller = new AbortController()
const stream = await card.net.fetch('https://api.example.com/v1/events', {
  headers: { accept: 'text/event-stream' },
  responseType: 'stream',
  signal: controller.signal
})
for await (const line of stream.lines()) {
  if (line.startsWith('data: ')) render(JSON.parse(line.slice(6)))
}
// controller.abort() ends it early.
```

`chunks()` отдаёт строки для текстовых кусков и `Uint8Array` для двоичных; `lines()` делит по
переводам строк; `for await (const chunk of response)` тоже работает. Оборвавшийся поток бросает
`NETWORK_ERROR`. Одновременно открыто не больше 4 потоков; поток закрывается после 5 минут без данных
или после 256 МБ. WebSocket в версии 1 не поддерживается.

### Что проверяет прокси

1. **Схема.** Только `https`, кроме `http` к этому компьютеру с `network.local`. Никаких имени
пользователя и пароля в URL; `#fragment` не отправляется.
2. **Хост.** Ровно ваши объявленные шаблоны (`api.example.com`, `*.example.com`,
`host.example.com:8443`). Всё остальное падает с `HOST_NOT_ALLOWED`.
3. **Адрес.** Приложение само резолвит имя; при выдаче на публичный хост каждый адрес должен быть
публичным — частные сети, loopback, link-local и адреса облачных метаданных отклоняются, а запрос
идёт на тот адрес, который проверили (никакого DNS rebinding).
4. **Заголовки.** Нельзя задавать `host`, `cookie`, `origin`, `referer`, `user-agent`,
`content-length`, `connection`, `proxy-*`, `sec-*`, `x-forwarded-*` и подобные. Приложение
отправляет `User-Agent: NeuroSquad-Card/<app version> (<your card name>)`. Cookies никогда не
сохраняются и не отправляются, а `set-cookie` вам никогда не возвращается.
5. **Редиректы.** Их выполняет приложение, не больше 5, и каждый шаг заново проверяется правилами
1–4.
6. **Лимиты.** Тело запроса до 5 МБ; ответ до 10 МБ (более длинное тело text или base64 приходит
обрезанным, с `truncated: true`; более длинное тело JSON падает с `TOO_LARGE`); 6 запросов
одновременно; 120 в минуту; тайм-аут до 120 с — причём он покрывает чтение всего тела, а не
только заголовков.

Ошибки: `HOST_NOT_ALLOWED` (хост или адрес не разрешён), `NETWORK_ERROR` (DNS, соединение, TLS),
`TIMEOUT`, `TOO_LARGE`, `RATE_LIMITED`, `PERMISSION_DENIED` (сетевых разрешений нет вовсе).
HTTP-статус с ошибкой исключением **не** считается — проверяйте `res.ok`.

> Диалог установки говорит пользователям, что всё, что видит ваша карточка, может уйти на
> перечисленные вами хосты. Держите список коротким и конкретным: маска или хост общего назначения
> (сервис для вставки текста, сокращатель ссылок) заставит осторожного пользователя отказаться.

---

## Файлы, буфер обмена и расход

> Чтение, запись, список и слежение за файлами в папке воркспейса; копирование в буфер обмена; расход токенов и стоимость воркспейса.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/files

### Файлы в папке воркспейса

Для чтения нужно [`fs.read`](https://docs.neurosquad.ai/ru/card-sdk/permissions#fs-read), для изменений —
[`fs.write`](https://docs.neurosquad.ai/ru/card-sdk/permissions#fs-write). Каждый путь задаётся **относительно папки
воркспейса** — папки проекта, которую пользователь выбрал для воркспейса, — через `/` или `\`;
`''` или `'.'` — сама папка.

```ts
// Read
const pkg = JSON.parse(await card.fs.readText('package.json')) as { name: string }
const logo = await card.fs.readBytes('public/logo.png')
const info = await card.fs.stat('src/index.ts')          // { path, type, size, mtimeMs }
const { entries, truncated } = await card.fs.list('src', { recursive: true, maxEntries: 2000 })
render(pkg.name, logo.byteLength, info.size, entries.length, truncated)

// Write (atomically: a temporary file, then a rename)
await card.fs.writeText('reports/latest.md', '# Report\n', { createDirs: true })
await card.fs.mkdir('reports/archive')
await card.fs.trash('reports/old.md')                     // to the OS trash; there is no hard delete

// Write only if nobody changed it since you read it
const before = await card.fs.stat('TODO.md')
await card.fs.writeText('TODO.md', '- [ ] ship it\n', { ifMtimeMs: before.mtimeMs })
```

| Метод | Результат |
| --- | --- |
| `stat(path)` | `{ path, type: 'file' or 'directory', size, mtimeMs }` |
| `list(path?, { recursive?, maxEntries? })` | `{ entries: { path, type, size? }[], truncated }` — до 5 000 записей; рекурсивный список пропускает `.git` и `node_modules`, если только вы не просите содержимое внутри них |
| `readText(path, { maxBytes? })` | текст UTF-8 |
| `readBytes(path, { maxBytes? })` | `Uint8Array` |
| `read(path, { encoding?, maxBytes? })` | `{ data, encoding, size, truncated }` — результат как есть |
| `writeText(path, text, { createDirs?, ifMtimeMs? })` | новый `FsStat` |
| `writeBytes(path, bytes, { createDirs?, ifMtimeMs? })` | новый `FsStat` |
| `mkdir(path)` | `FsStat` |
| `trash(path)` | переносит файл или папку в корзину ОС (60 в минуту) |
| `watch(path, handler, { recursive? })` | возвращает функцию, которая прекращает слежение |

Чтение и запись — до 10 МБ за раз.

**Слежение:**

```ts
const stop = await card.fs.watch('reports', ({ path, type }) => {
  render(`${path} ${type === 'rename' ? 'was added or removed' : 'changed'}`)
}, { recursive: true })
// later
await stop()
```

Изменения объединяются с задержкой 100 мс; не больше 20 наблюдателей на карточку; наблюдатели
останавливаются, когда страница карточки выгружается (подпишитесь снова после `launch === 'resumed'`).

**Ограда.** Абсолютные пути и любые `..` отклоняются сразу. Дальше приложение находит настоящий путь
цели (а для нового файла — ближайшей существующей папки) и отказывает, если он вне папки воркспейса,
— так что символическая ссылка или junction наружу не помогут. Всё это падает с `FS_DENIED`; прочие
проблемы файловой системы (не найдено, не папка…) — с `FS_ERROR`, а неудачная проверка `ifMtimeMs` —
с `FS_ERROR` и `data.conflict`.

**Доступа к файлам нет вовсе** — любой вызов `fs.*` падает с `FS_DENIED`, — если папка воркспейса —
это домашняя папка пользователя, корень диска или в ней лежит папка данных самого NeuroSquad.

#### Защищённые пути

Запись, `mkdir` и `trash` для них отклоняются (`FS_DENIED`) на любой глубине; проверяется и путь,
который вы передали, и настоящий путь за любой ссылкой — иначе карточка могла бы выполнить код через
git, агентов пользователя или их инструменты:

- всё внутри папки с именем `.git` (включая файл `.git` подмодуля или worktree), `.gitmodules`,
`.gitattributes`;
- папки `.claude`, `.codex`, `.cursor`, `.gemini`, `.qwen`, `.opencode`, `.kilocode`, `.windsurf`,
`.continue`, `.vscode`, `.idea`, `.husky`, `.devcontainer` и `.github/workflows`;
- файлы `.mcp.json`, `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `GEMINI.md`, `QWEN.md`,
`.cursorrules`, `.windsurfrules`, `opencode.json`, `opencode.jsonc`, `.envrc`, `.npmrc`, `.yarnrc`,
`.yarnrc.yml`, `.pnpmfile.cjs`.

Читать их с `fs.read` можно.

> Выбора файла в версии 1 нет: карточка работает только с папкой воркспейса. Чтобы указать карточке
> на файл, дайте пользователю ввести путь в настройке или получайте `ns:file-ref` через порт.

### Буфер обмена

Нужно [`clipboard.write`](https://docs.neurosquad.ai/ru/card-sdk/permissions#clipboard-write) — хороший кандидат на
необязательное разрешение.

```ts
await card.copyText('npm test -- --grep checkout')
```

Не чаще раза в секунду, до 1 МБ. Собственный `navigator.clipboard` браузера в карточке не работает,
а читать буфер обмена нельзя вовсе.

### Расход токенов и стоимость

Нужно [`usage.read`](https://docs.neurosquad.ai/ru/card-sdk/permissions#usage-read).

```ts
const summary = await card.usage('7d') // 'today' (default), '7d' or '30d'
const dollars = (summary.totalCostMicroUsd / 1_000_000).toFixed(2)
render(`$${dollars}${summary.partial ? ' + unpriced models' : ''}`)
for (const row of summary.rows) {
  render(row.name, row.harness, row.inputTokens, row.outputTokens, row.costMicroUsd ?? 'no price')
}
```

Те же числа, что на странице [Расход](https://docs.neurosquad.ai/ru/usage) приложения, для воркспейса карточки: `period`, `from` и
`to` (локальные сутки, конец не включается) и по каждому агенту `inputTokens`, `outputTokens`,
`cacheReadTokens`, `cacheWriteTokens` и `costMicroUsd`. Деньги — в **целых микродолларах**
(1 000 000 = $1). У модели без известной цены `costMicroUsd: null` — никогда не `0`, — она не входит
в `totalCostMicroUsd` и выставляет `partial: true`.

---

## Ошибки и лимиты

> CardSdkError и все коды ошибок — что вызывает каждую и что с ней делать, а также все лимиты протокола карточек в одной таблице.

Source: https://docs.neurosquad.ai/ru/card-sdk/api/errors

### `CardSdkError`

Любой отказ — от приложения или от собственных проверок SDK ещё до того, как запрос покинет
карточку, — это `CardSdkError`:

```ts
import { CardSdkError, isCardSdkError } from '@neurosquad/card-sdk'

async function saveReport(text: string): Promise<void> {
  try {
    await card.fs.writeText('reports/latest.md', text, { createDirs: true })
  } catch (error) {
    if (isCardSdkError(error, 'PERMISSION_DENIED')) {
      card.ui.toast(`This needs the ${error.permission} permission`)
    } else if (isCardSdkError(error, 'RATE_LIMITED')) {
      await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 1000))
      return saveReport(text)
    } else if (error instanceof CardSdkError) {
      card.log.error(error.code, error.method, error.hostMessage, error.data)
    } else {
      throw error
    }
  }
}
```

| Свойство | Что это |
| --- | --- |
| `code` | Один из кодов ниже. |
| `message` | `method: host message [CODE] — hint`, готово для журнала. |
| `hostMessage` | Только сообщение приложения (по-английски, для разработчиков — пользователям показывайте свой текст). |
| `method` | Метод, который упал, если ошибка пришла из вызова. |
| `data` | Подробности: ошибки схемы, `{ permission }`, `{ retryAfterMs }`, `{ conflict }`… |
| `hint` | Подсказка в одну строку — для кодов, у которых она есть. |
| `permission` | Для `PERMISSION_DENIED`: недостающее разрешение. |
| `retryAfterMs` | Для `RATE_LIMITED`: сколько ждать. |
| `issues` | Для `INVALID_PARAMS` / `BAD_REQUEST`: `{ path, keyword, message }[]` — где параметры не совпали со схемой. |

`isCardSdkError(error, code?)` — защитник типа, при желании для одного кода.

### Коды ошибок

| Код | Значит | Обычно |
| --- | --- | --- |
| `BAD_REQUEST` | Сообщение повреждено или его параметры — не простой JSON. | В параметрах `Date`, `Map` или экземпляр класса — передавайте простые данные. |
| `INVALID_PARAMS` | Параметры не подходят под схему метода. | Точный путь — в `error.issues`. А также значение порта, не прошедшее схему, или незаданный `{{secret:…}}`. |
| `METHOD_NOT_FOUND` | Приложение не знает этот метод. | Старое приложение — проверяйте через `card.host.supports()`. |
| `PERMISSION_DENIED` | У пакета нет разрешения. | Объявите его в манифесте или, если оно необязательное, попросите через `card.permissions.request()`. |
| `NOT_CONNECTED` | Целевая карточка или агент не соединены с вашей стрелкой. | Попросите пользователя её провести. |
| `NOT_FOUND` | Нет такой карточки, агента, ключа, файла или порта. | |
| `QUOTA_EXCEEDED` | Квота исчерпана: байты или ключи хранилища, созданные карточки, наблюдатели за файлами, полная очередь промптов агента. | Удалите старые данные, остановите старых наблюдателей, подождите. |
| `RATE_LIMITED` | Слишком много вызовов. Сколько ждать — в `data.retryAfterMs`. | Объединяйте вызовы, откладывайте, отступайте. (Заголовок, статус, бейдж, обзор и внимание из-за этого никогда не отклоняются — SDK схлопывает и повторяет их.) |
| `TOO_LARGE` | Сообщение, значение или ответ больше лимита. | См. [Лимиты](#limits). |
| `TIMEOUT` | Нет ответа вовремя (запрос к порту, команда, сетевой запрос). | |
| `BUDGET_PAUSED` | Воркспейс вышел за бюджет; программные промпты отклоняются. | Пользователь поднимает лимит в карточке [Budget](https://docs.neurosquad.ai/ru/cards/budget). |
| `BUSY` | Агент посреди хода, а вы указали `whenBusy: 'fail'`. | |
| `HOST_NOT_ALLOWED` | `net.fetch` к хосту вне выданных или к хосту, который резолвится в заблокированный адрес. | Добавьте хост в разрешение `network`. |
| `NETWORK_ERROR` | Сбой DNS, соединения, TLS или потока. | |
| `FS_DENIED` | Путь вне папки воркспейса, внутри `.git/` или через ссылку, ведущую наружу. | Используйте относительный путь. |
| `FS_ERROR` | Любая другая проблема с файлом; `data.conflict`, если не совпал `ifMtimeMs`. | |
| `NOT_VISIBLE` | Нужно, чтобы карточка была на экране: диалоги, ссылки, полёт камеры, запросы разрешений, промпты агенту в опасном режиме. | Повторите, когда `card.visibility === 'visible'`. |
| `USER_CANCELLED` | Пользователь отказался (подтверждение, промпт агенту в опасном режиме) или вызов отменён. | |
| `UNAVAILABLE` | Цель не запущена, воркспейс не открыт, карточка усыплена или соединение закрыто. | |
| `PROTOCOL_MISMATCH` | Карточка сделана под более новый протокол, чем знает приложение. | Пользователь обновляет NeuroSquad. |
| `NOT_READY` | Вызов сделан до завершения рукопожатия. | Дождитесь `connect()`. |
| `INTERNAL` | Ошибка в приложении. | Сообщите о ней, приложив журнал карточки. |

### Лимиты

Все лимиты есть в `card.limits` (константа `LIMITS` из SDK). Дешёвые SDK проверяет до отправки;
приложение соблюдает все.

| Область | Лимит |
| --- | --- |
| **Сообщения** | до 1 МБ каждое (запросы `fs.write` и `net.fetch` и ответы `fs.read`, `fs.list`, `net.fetch` — до 12 МБ); до 64 вызовов одновременно (сверх этого SDK ставит их в очередь); 200 вызовов/с, всплески до 400; значения не глубже 64 уровней и не больше 200 000 узлов |
| **Пакет** | архив до 50 МБ; распакованный до 100 МБ; до 5 000 файлов; каждый до 20 МБ; пути до 240 символов и 20 уровней; манифест до 256 КБ; иконка до 128 КБ |
| **Манифест** | до 40 настроек; до 16 входов и 16 выходов; до 32 инструментов; до 32 сетевых хостов; схемы до 500 узлов и 16 уровней, `enum` до 256 вариантов и 16 КБ, `const` до 4 КБ |
| **Хранилище** | ключ до 256 символов; значение до 1 МБ; до 10 000 ключей; 5 МБ на карточку, 20 МБ на пакет |
| **Сеть** | тело до 5 МБ; ответ до 10 МБ; 6 одновременно; 120 в минуту; до 5 редиректов; тайм-аут 30 с (максимум 120 с), включая тело; до 4 потоков, каждый закрывается после 5 минут тишины или 256 МБ |
| **Файлы** | чтение и запись до 10 МБ; список до 5 000 записей; до 20 наблюдателей |
| **Агенты** | промпт до 20 000 символов, 6 в минуту на карточку (метод и порт вместе), до 10 в очереди на агента; команда до 20 000 символов; 30 команд в минуту на карточку (`run` и порт терминала вместе, тайм-аут до 120 с), `write` 60 в минуту; экран до 500 строк; вывод доставляется каждые 100 мс или 64 КБ |
| **Инструменты** | результат до 1 МБ; тайм-аут 30 с (максимум 120 с); прогресс 4 раза в секунду |
| **Порты** | 20 сообщений/с на выход; сохраняемое значение до 256 КБ; тайм-аут запроса 30 с (максимум 120 с) |
| **Интерфейс карточки** | заголовок до 120 (30 в минуту); статус до 80, статус/бейдж/обзор — по 120 в минуту; строки обзора до 160; тост до 280 (один в 2 с); текст подтверждения до 1 000 (10 в минуту); до 12 пунктов меню (30 изменений в минуту); `settings.set` 60 в минуту; `tools.setEnabled` 30 в минуту; `usage.summary` 6 в минуту; внимание раз в 10 с; полёт камеры раз в 5 с; изменение размера раз в 500 мс; до 4 созданных карточек; буфер обмена раз в секунду, до 1 МБ |
| **Журнал** | строка до 2 000 символов; 50 строк в секунду |
| **Страницы** | во всём приложении работает до 24 страниц карточек; из них в фоне — до 8; усыпление через 60 с скрытности, на сохранение — 1 с; пульс каждые 5 с, «не отвечает» через 15 с; готовность — в течение 10 с после запуска |

---

## React-привязки

> CardProvider и хуки из @neurosquad/card-sdk/react — контекст, настройки, хранилище, агенты, порты, инструменты, тема, язык и видимость.

Source: https://docs.neurosquad.ai/ru/card-sdk/react

`@neurosquad/card-sdk/react` оборачивает карточку в провайдер и отдаёт её живое состояние через хуки.
React 18.2+ или 19 — peer-зависимость; шаблон React всё настраивает сам.

```tsx
import { createRoot } from 'react-dom/client'
import { CardProvider, useCardContext, useStorage } from '@neurosquad/card-sdk/react'

function App() {
  const { instance, workspace } = useCardContext()
  const [count, setCount] = useStorage('count', 0)
  return (
    <button className="ns-btn ns-btn--primary" onClick={() => setCount(count + 1)}>
      {instance.displayName} in {workspace.name}: {count}
    </button>
  )
}

createRoot(document.getElementById('root')!).render(
  <CardProvider fallback={<p>Connecting…</p>}>
    <App />
  </CardProvider>
)
```

### `CardProvider`

| Свойство | Значение |
| --- | --- |
| `card` | Карточка, которую вы подключили сами, — например, с [мок-хоста](https://docs.neurosquad.ai/ru/card-sdk/testing). Без неё провайдер сам вызывает `connect()`. |
| `connectOptions` | Параметры для `connect()`. |
| `fallback` | Показывается, пока идёт подключение. |
| `errorFallback` | `(error) => ReactNode`, показывается, если подключиться не удалось. По умолчанию — текст ошибки. |

Шаблон React сначала подключается, а потом передаёт `card` — так одна и та же точка входа работает и
в приложении, и, с мок-хостом, в превью в браузере.

### Хуки

| Хук | Возвращает |
| --- | --- |
| `useCard()` | [`Card`](https://docs.neurosquad.ai/ru/card-sdk/api#the-card-object) — для всего, у чего нет своего хука. |
| `useCardContext()` | Живой [`HostContext`](https://docs.neurosquad.ai/ru/card-sdk/api#context); перерисовывает при любом изменении. |
| `useSettings()` | `[settings, setSettings]` — `settings.values`, `settings.secrets`; сеттер меняет несекретные значения. |
| `useStorage(key, initial, { scope? })` | `[value, setValue, { loading, error }]` — как `useState`, только с сохранением. Сеттер обновляет сразу и пишет в фоне; принимает и функцию. С `scope: 'package'` следит за записями других копий карточки. |
| `useAgents()` | `{ agents, loading, error, refresh }` — обновляется по событиям статуса и изменений. Нужно `agents.read`. |
| `useAgentStatus(agentId)` | Статус одного агента или `undefined`. |
| `usePort(input?)` | `{ data, message }` — последнее значение, пришедшее на вход (или на любой вход). |
| `useEmit(output)` | Стабильная функция `(data) => Promise<number>`, отправляющая в выход. |
| `usePortRequest(input, handler)` | Отвечает на вход-запрос, пока компонент смонтирован. |
| `usePeers()` | Подключённые карточки и их порты, вживую. |
| `useTool(name, handler)` | Реализует инструмент из манифеста, пока компонент смонтирован; всегда вызывает последний обработчик. |
| `useCardEvent(event, handler)` | Любое событие, пока компонент смонтирован; всегда вызывает последний обработчик. |
| `useTheme()` | `ThemeSnapshot`, вживую (CSS-переменные уже применены). |
| `useLanguage()` | `{ language, locale }`, вживую. |
| `useTranslator(catalog)` | [Переводчик](https://docs.neurosquad.ai/ru/card-sdk/api/environment#i18n), перерисовывающий при смене языка. Каталог объявляйте вне компонента. |
| `useVisibility()` | `visible`, `offscreen`, `overview` или `hidden`. |
| `usePaused()` | `true`, когда тело карточки никто не видит, — ставьте на паузу анимации и опрос. |
| `useExpanded()` | Развёрнута ли карточка. |

### Пример побольше

```tsx
import type { Catalog } from '@neurosquad/card-sdk'
import {
  useAgents,
  useCard,
  useEmit,
  usePaused,
  usePort,
  useTool,
  useTranslator
} from '@neurosquad/card-sdk/react'
import { useEffect } from 'react'

const catalog: Catalog = {
  en: { waiting_one: '{{count}} agent waits for you', waiting_other: '{{count}} agents wait for you' },
  ru: {
    waiting_one: '{{count}} агент ждёт вас',
    waiting_few: '{{count}} агента ждут вас',
    waiting_many: '{{count}} агентов ждут вас',
    waiting_other: '{{count}} агента ждут вас'
  },
  zh: { waiting_other: '{{count}} 个智能体在等你' }
}

export function Waiting() {
  const card = useCard()
  const t = useTranslator(catalog)
  const paused = usePaused()
  const { agents } = useAgents()
  const waiting = agents.filter((a) => a.status === 'needs-input')
  const { data: note } = usePort<string>('notes')
  const emit = useEmit<string>('digest')

  // Keep the overview tile and attention in step with the data.
  useEffect(() => {
    void card.setOverview({ primary: t('waiting', { count: waiting.length }), icon: 'bell' })
    void card.attention(waiting.length > 0 ? 'needs-input' : 'none').catch(() => undefined)
  }, [card, t, waiting.length])

  useTool('list_waiting', () => waiting.map((a) => a.name))

  return (
    <div className="ns-stack">
      <p className={paused ? '' : 'pulse'}>{t('waiting', { count: waiting.length })}</p>
      {note ? <pre className="ns-mono">{note}</pre> : null}
      <button className="ns-btn" onClick={() => void emit(waiting.map((a) => `- ${a.name}`).join('\n'))}>
        Send digest
      </button>
    </div>
  )
}
```

> Хуки, которые обращаются к приложению (`useAgents`, `useStorage`), не бросают исключения, а
> сообщают об ошибках в поле `error` — нехватка разрешения появится там как `CardSdkError` с
> `PERMISSION_DENIED`.

### Локальная копия SDK

Если карточка подключает SDK по ссылке `file:`, npm создаёт символическую ссылку, и Vite может
загрузить вторую копию React рядом с SDK — тогда хуки падают с «Invalid hook call». В
`vite.config.ts` шаблона React уже есть `resolve: { dedupe: ['react', 'react-dom'] }`; в своей
сборке добавьте его сами или укажите `install-links=true` в `.npmrc` карточки.

---

## UI-кит и оформление

> Оформляйте карточку как угодно — или выглядите как родная с необязательным китом ui.css на живой теме приложения; классы, переменные и правила песочницы для стилей, шрифтов и картинок.

Source: https://docs.neurosquad.ai/ru/card-sdk/styling

Внутри своей коробки карточка — обычная веб-страница: любой фреймворк, любой CSS, canvas, WebGL,
WebAssembly. Оформить её можно двумя путями:

- **Как родная** — необязательный кит `ui.css`: небольшой тёмный набор кнопок, полей, списков и
бейджей на живой теме приложения. Карточки на нём выглядят частью NeuroSquad и следуют его теме.
- **Свой дизайн** — просто не подключайте кит. Переменные темы всё равно под рукой, если захочется
позаимствовать цвет.

### UI-кит

```html
<link rel="stylesheet" href="vendor/ui.css" />   <!-- plain template -->
```

```ts
import '@neurosquad/card-sdk/ui.css'              // with a bundler (React template)
```

Поставьте `class="ns-kit"` на `<body>` — это даст базовую типографику, фон и полосы прокрутки, — и
пользуйтесь классами:

```html
<body class="ns-kit">
  <header class="ns-spread">
    <h1 class="ns-title ns-truncate">Test radar</h1>
    <span class="ns-badge ns-badge--danger">3 failed</span>
  </header>

  <ul class="ns-list ns-scroll">
    <li class="ns-list-item"><span class="ns-dot ns-dot--danger"></span> checkout › pays</li>
    <li class="ns-list-item"><span class="ns-dot ns-dot--success"></span> auth › logs in</li>
  </ul>

  <label class="ns-field">
    <span class="ns-label">Filter</span>
    <input class="ns-input" placeholder="checkout" />
  </label>

  <div class="ns-row">
    <button class="ns-btn ns-btn--primary">Run</button>
    <button class="ns-btn ns-btn--ghost ns-btn--sm">Clear</button>
  </div>
</body>
```

| Группа | Классы |
| --- | --- |
| Раскладка | `ns-kit`, `ns-stack` (вертикально), `ns-row` (горизонтально), `ns-spread` (space-between), `ns-grow`, `ns-scroll`, `ns-pad`, `ns-divider` |
| Поверхности | `ns-surface`, `ns-surface--inset`, `ns-callout`, `ns-callout--success`, `ns-callout--danger`, `ns-empty` |
| Текст | `ns-title`, `ns-subtitle`, `ns-muted`, `ns-small`, `ns-mono`, `ns-truncate`, `ns-kbd`, `ns-help`, `ns-error` |
| Кнопки | `ns-btn` + `--primary`, `--secondary`, `--outline`, `--ghost`, `--danger`, `--sm`, `--lg`, `--icon` |
| Поля | `ns-field`, `ns-label`, `ns-input`, `ns-textarea`, `ns-select`, `ns-switch` |
| Списки | `ns-list`, `ns-list-item` |
| Статус | `ns-badge` + `--accent`, `--success`, `--warning`, `--danger`; `ns-dot` + те же; `ns-spinner`, `ns-progress` |

Вне приложения (в превью в браузере) кит откатывается к тёмной теме приложения, так что и превью
выглядит правильно.

### Переменные темы

`connect()` кладёт живую тему приложения на `<html>` в виде переменных `--ns-<token>` —
`--ns-background`, `--ns-surface`, `--ns-foreground`, `--ns-muted`, `--ns-accent`, `--ns-success`,
`--ns-warning`, `--ns-danger`, их варианты `-foreground` и `-soft`, `--ns-border`, `--ns-focus`,
`--ns-field-*`, `--ns-radius`, `--ns-font-sans`, `--ns-font-mono` и другие (полный список — в разделе
[Тема](https://docs.neurosquad.ai/ru/card-sdk/api/environment#theme)). Пользуйтесь ими в своём CSS, и карточка будет следовать за
приложением:

```css
:root { color-scheme: dark; }
body {
  margin: 0;
  background: var(--ns-background, #0b0b0f);
  color: var(--ns-foreground, #fafafa);
  font: 13px/1.45 var(--ns-font-sans, system-ui, sans-serif);
}
.chip {
  border-radius: calc(var(--ns-radius, 0.5rem) * 2);
  background: var(--ns-accent-soft);
  color: var(--ns-accent-soft-foreground);
}
```

Давайте переменным запасные значения (как выше), если страница должна отображаться и вне
приложения. Чтобы ваши цвета никто не трогал, подключайтесь через `connect({ theme: false })`.

### Правила песочницы для страниц

Ваша страница отдаётся из собственного пакета со строгой политикой безопасности контента (CSP). На
практике:

- **Никаких встроенных скриптов и атрибутов `onclick="…"`** — код кладите в файлы `.js`. `eval` и
`new Function` тоже заблокированы (WebAssembly разрешён).
- **Никаких внешних файлов.** Скрипты, стили, шрифты и картинки должны лежать в пакете;
`<link href="https://fonts…">` или `<img src="https://…">` заблокируются. Картинки `data:` и `blob:`
работают. За удалёнными данными ходите через [`card.net.fetch`](https://docs.neurosquad.ai/ru/card-sdk/api/network), а картинки
превращайте в URL `blob:`.
- **Встроенные стили можно** (`style="…"` и `<style>`).
- **Относительные URL.** Страница отдаётся с `nscard://<id>/<path>`; собирайте с относительными
путями к ресурсам (в Vite — `base: './'`, как в шаблоне React).
- **Никаких `localStorage`, cookies, `alert`, всплывающих окон, загрузок, полноэкранного режима,
камеры и микрофона.** Используйте `card.storage`, `card.ui.confirm`, `card.openLink`.
- **Никакой записи в буфер обмена со страницы.** Обработчики `copy`/`cut` и
`document.execCommand('copy')` ничего не делают (иначе любая карточка могла бы подменить буфер
обмена по клику). Используйте [`card.copyText`](https://docs.neurosquad.ai/ru/card-sdk/api/files#clipboard); обычное
копирование выделенного текста пользователем по-прежнему работает.
- **Никаких вложенных фреймов.** Элементы `iframe`, `frame`, `object` и `embed` удаляются.
- **Только blob-воркеры.** `new Worker('worker.js')` в источнике карточки не работает; скачайте
скрипт, заверните его в `Blob` и запустите `new Worker(URL.createObjectURL(blob))`.
- **Никогда не доверяйте событиям `message`.** Другие карточки могут делать `postMessage` в ваш
фрейм.

`npx @neurosquad/card-sdk validate` предупреждает о встроенных скриптах, встроенных обработчиках и
внешних файлах во входной странице.

> **Формы никуда не уводят.** Событие `submit` у `<form>` срабатывает, и ваш обработчик выполняется,
> но саму отправку приложение отменяет, а `form.submit()` ничего не делает — страница карточки не
> может ничего никуда отправить или перезагрузиться. Всё равно вызывайте в обработчике
> `event.preventDefault()` и делайте работу в JavaScript.

### Дизайн для холста

- **Маленькая и большая.** Карточка часто размером 400×300, а иногда развёрнута на весь экран.
Пусть оба вида выглядят законченными: переключайте раскладку через `card.lifecycle.onExpanded` или
`useExpanded()`.
- **Пусто, загрузка, ошибка.** Показывайте что-то осмысленное, пока данные не пришли, когда их нет и
когда вызов упал.
- **Плитка обзора — это ваша карточка издалека.** Держите [`setOverview`](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#overview)
актуальным, с одним главным фактом.
- **Тихо, когда не видно.** Останавливайте анимации, когда `usePaused()` возвращает true, — на холсте
бывает пятьдесят карточек.
- **Шапка — забота приложения.** Не повторяйте в теле имя карточки или кнопку закрытия: в шапке они
уже есть.

> Всё, что внутри тела карточки, принадлежит самой карточке, и пользователям об этом сказано. Не
> подражайте диалогам NeuroSquad и не спрашивайте пароли и ключи внутри карточки — используйте
> настройки `secret`, которые приложение запрашивает в своей собственной форме.

---

## Тесты с мок-хостом

> createMockHost — NeuroSquad в памяти, который применяет проверки приложения, записывает, что сделала ваша карточка, и позволяет управлять ею из тестов или превью в браузере.

Source: https://docs.neurosquad.ai/ru/card-sdk/testing

В `@neurosquad/card-sdk/testing` есть хост в памяти, который говорит на настоящем протоколе и
применяет проверки приложения в том же порядке — схемы параметров, разрешения, видимость и, по
желанию, ограничения частоты. Хранилище, настройки, агенты, порты, инструменты, сеть и файлы
имитируются. Код вашей карточки работает с ним без изменений.

### Модульный тест

```ts
import { createMockHost } from '@neurosquad/card-sdk/testing'
import type { CardManifest } from '@neurosquad/card-sdk'
import { describe, expect, it } from 'vitest'

const manifest: CardManifest = {
  manifestVersion: 1,
  name: 'test-radar',
  displayName: 'Test radar',
  version: '1.0.0',
  protocol: 1,
  permissions: ['agents.read'],
  ports: { outputs: [{ id: 'summary', label: 'Summary', type: 'ns:markdown' }] },
  tools: [{ name: 'summary', description: 'Returns the summary.', inputSchema: { type: 'object' } }]
}

describe('test radar', () => {
  it('sends its summary to a connected note and answers the tool', async () => {
    const host = createMockHost({
      manifest,
      agents: [{ id: 'a1', name: 'Claude Code', harness: 'claude-code', kind: 'ai', status: 'idle', connected: true }],
      peers: [
        {
          cardId: 'note-1',
          kind: 'note',
          name: 'Notes',
          direction: 'downstream',
          inputs: [{ id: 'append', label: 'Append', type: 'ns:markdown', mode: 'stream', retain: false, default: true }],
          outputs: []
        }
      ]
    })
    const card = await host.connect()

    // The code under test would normally live in your card's module.
    card.tools.handle('summary', () => '# All green')
    await card.ports.emit('summary', '# All green')

    expect(host.deliveries).toEqual([{ to: 'note-1', output: 'summary', input: 'append', data: '# All green' }])
    await expect(host.callTool('summary', {})).resolves.toEqual({
      content: [{ type: 'text', text: '# All green' }]
    })
  })

  it('is refused what it did not declare', async () => {
    const card = await createMockHost({ manifest }).connect()
    await expect(card.agents.prompt('a1', 'hi')).rejects.toMatchObject({ code: 'PERMISSION_DENIED' })
  })
})
```

Моку нужен `MessageChannel` — он есть в Node 18+ и в любом браузере.

### Параметры

`createMockHost(options)`:

| Параметр | Значение |
| --- | --- |
| `manifest` | Ваш манифест; проверяется так же, как в приложении (неверный — исключение). По умолчанию — минимальный. |
| `grant` | Выданные разрешения: по умолчанию все **обязательные**; `'all'` — вместе с необязательными; или список идентификаторов. |
| `context` | Переопределения контекста, отправляемого при подключении (`visibility`, `i18n`, `workspace`, `instance`…). |
| `agents` | `AgentInfo[]` в воркспейсе. |
| `screens`, `replies` | Что возвращают `readScreen` и `lastReply` для каждого агента. |
| `peers` | Подключённые карточки (`PeerInfo`, плюс сохраняемые значения `retained` и функция `respond` для запросов). |
| `files` | Папка воркспейса: `{ 'path/to/file': 'text' or Uint8Array }`. |
| `fetch` | Обрабатывает `net.fetch` после проверок URL и разрешений: `(req) => ({ status?, headers?, body?, stream?, error? })`. По умолчанию — `NETWORK_ERROR`. |
| `confirm` | Отвечает на `ui.confirm`, `openLink` и промпты в опасном режиме. По умолчанию — «да». |
| `requestPermissions` | Отвечает на `permissions.request`. По умолчанию выдаёт всё, что просят. |
| `hostProtocol` | Притвориться более старым или новым приложением (чтобы проверить `PROTOCOL_MISMATCH`). |
| `enforceRateLimits` | Применять ограничения частоты методов. По умолчанию `false`, чтобы тесты были детерминированными. |
| `usage` | `UsageSummary`, который возвращает `usage.summary`. |
| `agentUsage` | Что возвращает `agents.usage` по id агента (поверх нулевого прогона) или функция от `(agentId, since, until)`. Поменять позже — `setAgentUsage`. |
| `settings` | Начальные значения настроек, как будто пользователь их сохранил. |
| `secrets` | Значения секретных настроек, которые ввёл пользователь: подставляются в заголовки `{{secret:key}}`; объявленный секрет, которого здесь нет, падает с `INVALID_PARAMS`, как в приложении. |
| `verbose` | Печатать каждый запрос и событие. |

### Управление карточкой

| Метод | Делает |
| --- | --- |
| `connect(options?)` | Настоящий `Card`, подключённый к этому хосту. |
| `setVisibility(state)`, `setExpanded(bool)`, `resize({ w, h })`, `suspend(graceMs?)` | События жизненного цикла. |
| `setTheme(theme)`, `setLanguage('ru')` | Смена темы и языка. |
| `setSettings(values, secrets?)` | Пользователь сохранил форму настроек (`secrets` — какие заданы). |
| `setSecret(key, value)` | Пользователь ввёл (или, с `null`, очистил) секретную настройку. |
| `setGrants(ids)`, `setPeers(peers)` | Меняет выдачу разрешений или стрелки (с соответствующими событиями). |
| `sendPortMessage(input, data, from?)` | На вход приходит значение. |
| `requestPort(input, data)` | Обращается к входу-запросу; возвращает ответ карточки. |
| `callTool(tool, args, { agent?, timeoutMs? })` | Вызывает инструмент, как агент; возвращает результат. `cancelTool(callId)` отменяет. |
| `setAgentStatus(id, status)`, `agentOutput(id, text)` | События агентов (доставляются, если карточка подписана); смена статуса порождает и `agents.turn` по правилу приложения. |
| `touchFile(path, data?)`, `readFile(path)` | Меняет файл (уведомляя наблюдателей), читает то, что записала карточка. |
| `emit(event, data)` | Отправляет любое событие. |
| `ping()` | Пульс; разрешается, когда карточка ответит. |
| `handle(method, fn)` | Заменяет поведение метода (выполняется после проверок). |

### Что он записывает

`calls` (каждый запрос), `events`, `storage.instance` / `storage.package` (Map), `deliveries`,
`retained`, `prompts`, `terminal`, `logs`, `toasts`, `clipboard`, `spawned`, `aborted`, `pongs`,
`subscriptions`, `chrome` (`title`, `status`, `badge`, `overview`, `attention`, `menu`,
`enabledTools`), `files`, а также текущие `hostContext` и `grants`.

### Превью в браузере

Оба шаблона запускают мок-хост, если страницу открыть вне приложения, так что `npx serve .` или
`npm run dev` показывают рабочую карточку с примерами данных. Если настраиваете сами, схема такая:

```ts
import { connect, type Card, type CardManifest } from '@neurosquad/card-sdk'

async function start(): Promise<Card> {
  if (window.parent !== window) return connect()          // inside NeuroSquad
  const { createMockHost } = await import('@neurosquad/card-sdk/testing')
  const manifest = (await (await fetch('./neurosquad-card.json')).json()) as CardManifest
  const host = createMockHost({ manifest, grant: 'all' })
  Object.assign(window, { mockHost: host })               // drive it from the DevTools console
  return host.connect()
}

const app = await start()
render(app.instance.displayName)
```

> Мок точен в **правилах**, но не в **остальном приложении**: он не запускает агентов, не рисует
> стрелки и не показывает вашу плитку обзора. Перед публикацией запустите карточку по-настоящему через
> `neurosquad-card dev`.

### Чего мок не имитирует

Мок повторяет правила приложения — разрешения, видимость (`NOT_VISIBLE` для диалогов и запросов
разрешений), схемы значений портов и аргументов инструментов, сообщения портов только от карточек
выше по стрелке, события хода, выведенные из смены статуса, подстановку секретов в заголовки, — но
он не песочница браузера и не интерфейс приложения:

- ваша страница не в песочнице, поэтому формы могут уводить страницу, обработчики `copy` работают,
вложенные фреймы и воркеры из файлов загружаются — проверяйте это в приложении через
`neurosquad-card dev`;
- диалоги, шапка и плитка обзора приложения не рисуются — смотрите `host.chrome`;
- настоящих агентов, терминалов и стрелок нет — это данные, которые вы передаёте.

---

## Справочник CLI

> neurosquad-card create, dev, validate и pack — все флаги, что проверяет каждая команда и как подключение для разработчика находит приложение.

Source: https://docs.neurosquad.ai/ru/card-sdk/cli

В SDK есть утилита командной строки `neurosquad-card`. Ей нужен только Node.js 18.17+ — других
зависимостей нет. Запускайте без установки:

```bash
npx @neurosquad/card-sdk <command>
```

или, в проекте, где установлен `@neurosquad/card-sdk` (как в шаблоне React),
`npx neurosquad-card <command>`. `--help` перечисляет всё, `--version` печатает версию SDK.

### `create`

```bash
neurosquad-card create <folder> [--template vanilla|react] [--name <slug>] [--display-name <text>] [--force]
```

Новая карточка из шаблона.

| Флаг | Значение |
| --- | --- |
| `--template` | `vanilla` (по умолчанию): HTML + JS, без сборки, SDK копируется в `vendor/`. `react`: React + Vite + TypeScript. |
| `--name` | `name` в манифесте. По умолчанию — из имени папки (`My Card` → `my-card`). |
| `--display-name` | `displayName` в манифесте. По умолчанию — из имени (`my-card` → `My card`). |
| `--force` | Писать в непустую папку. |

### `dev`

```bash
neurosquad-card dev [folder] [--user-data-dir <dir>] [--no-build] [--no-logs]
```

Подключает папку к запущенному приложению с живой перезагрузкой и транслирует журнал карточки.

1. Находит папку данных NeuroSquad — `%APPDATA%\NeuroSquad` в Windows,
`~/Library/Application Support/NeuroSquad` в macOS, `~/.config/NeuroSquad` в Linux, или
`--user-data-dir` / переменную окружения `NEUROSQUAD_USER_DATA_DIR` для другого профиля — и
читает `card-dev.json`, который приложение пишет, пока включён **режим разработчика** (порт и
одноразовый токен локального сервера подключения).
2. Просит приложение подключить папку. Приложение показывает подтверждение с папкой и именем
карточки, потом обычный диалог разрешений. `dev` ждёт вашего согласия до 5 минут.
3. Запускает вашу сборку в режиме наблюдения, если она есть в `package.json`: `npm run watch`, иначе
`npm run build -- --watch`. `--no-build` это пропускает. **Это собственные npm-скрипты папки** —
запускайте `dev` только на папках, которым доверяете, или передавайте `--no-build`.
4. Транслирует журнал карточки — `card.log.*`, необработанные ошибки, отклонённые промисы — со всех
копий карточки. `--no-logs` это пропускает.

Приложение следит за папкой и перезагружает все копии карточки при каждом изменении (их `launch` —
`reloaded`). Если манифест перестаёт проходить проверку, проблемы видны на карточке и в вашем
терминале. Клавиши: **r** перезагружает карточку, **q** (или Ctrl+C) выходит. После выхода папка
остаётся подключённой; отключить её можно в **Settings → Custom cards → Developer mode**.

Если `dev` говорит, что режим разработчика выключен, включите его в **Settings → Custom cards**.
Сервер подключения слушает только `127.0.0.1`, существует, только пока включён режим разработчика,
и каждое подключение нужно подтвердить в приложении.

### `validate`

```bash
neurosquad-card validate [folder] [--json] [--app-version <x.y.z>]
```

Выполняет проверки установщика без установки:

- манифест — собственным валидатором приложения (схема, затем смысловые проверки: размеры,
настройки, порты, инструменты, схемы, зарезервированные имена);
- файлы: пути, которые установщик отклонит, файлы больше 20 МБ, больше 5 000 файлов или 100 МБ в
сумме, имена, отличающиеся только регистром, символические ссылки (установщик их пропускает),
случайно оставленный `.tgz`;
- иконку: существует, PNG или WebP по содержимому, до 128 КБ, квадратная (и замечание, если меньше
64×64);
- входную страницу: встроенные `<script>`, встроенные обработчики `on…=` и внешние `src`/`href`,
которые заблокирует песочница;
- подсказки: нет иконки, лицензии, описания; имя или автор выдают себя за NeuroSquad, official или
verified (у неофициальных карточек приложение такое отклоняет).

`validate` и `pack` безопасно запускать на папке, которую вам кто-то прислал: git работает с
отключёнными хуками самой папки, а текст карточки печатается без escape-последовательностей и
символов направления текста (bidi).

Затем печатает **превью диалога установки** — что увидят пользователи, начиная с высокого риска, с
вашими объяснениями — и при ошибках завершается с ненулевым кодом. `--json` печатает отчёт для
машин; `--app-version` дополнительно сверяет `minAppVersion` с этой версией.

```text
Install dialog preview:
Test radar (test-radar 1.0.0)
  by Acme (self-declared)
  Community code, not made or checked by NeuroSquad.
  It will be able to:
   high    Run commands in terminals connected to it
           Type and run commands in terminal cards you connect to it with an arrow — anything you could run yourself.
   high    Read files in the workspace folder
           Any file in this workspace’s project folder, including secrets stored in files like .env.
           Why: Reads the JUnit report
   low     See the agents on this canvas
           Their names, which tool they run, and whether they are working, waiting for you or finished.
  May ask later for:
   - Copy to your clipboard
  Tools for connected agents: test_radar_run_tests
  Ports: 1 in (run:ns:trigger), 2 out (failures:ns:tasks, summary:ns:markdown)

11 files, 236.7 KB (file list from the folder)
✔ valid
```

### `pack`

```bash
neurosquad-card pack [folder] [--out <file.tgz>] [--dry-run] [--json] [--allow-secret-files]
```

То же, что `validate`, плюс что именно будет установлено: файлы, которые отслеживает git, и
неотслеживаемые, но не игнорируемые — то, что попадает в архив вашего репозитория на GitHub, — с
размерами и **хешем дерева**, который приложение записывает при установке (sha-256 по пути и
sha-256 каждого файла). Потом пишет воспроизводимый `<name>-<version>.tgz` (или `--out`);
`--dry-run` ничего не пишет.

`pack` отказывается упаковывать файлы, похожие на учётные данные, — `.env*` (кроме `.env.example`,
`.sample`, `.template`, `.dist`), `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_rsa*`, `.npmrc`,
`.git-credentials`, `.netrc`, — если не передать `--allow-secret-files`, и пропускает всё, до чего
можно дойти только через символическую ссылку или junction.

```text
file                                size
README.md                           1.4 KB
icon.png                            4.1 KB
index.html                          1.6 KB
main.js                             7.5 KB
neurosquad-card.json                1.6 KB
…
11 files, 236.7 KB unpacked, 66.2 KB packed
tree hash  8315b0d598fee984f9144bfcaa03129de8d3be56fac57a1e4925efbb7b74842d
✔ dry run: the installer would accept this package
```

Вне git-репозитория список файлов — это просто содержимое папки.

Запускайте перед тегом релиза: если какого-то файла нет в списке (например, результата сборки,
который вы забыли закоммитить), пользователи его не получат.

> Хеш дерева — это способ, которым пользователь (или вы) может убедиться, что установленная карточка
> байт в байт совпадает с тем коммитом, за который себя выдаёт.

---

## Публикация и обновления

> Как поделиться карточкой через GitHub, с каких адресов её можно установить, как установка привязывается к коммиту, как обновления доходят до пользователей и когда они спрашивают снова, и версии карточки и протокола.

Source: https://docs.neurosquad.ai/ru/card-sdk/publishing

Магазина нет: **карточка опубликована, когда она на GitHub**, и ставится по своему адресу на GitHub.
Проверка — по желанию: чтобы карточка попала в [каталог проверенных](https://docs.neurosquad.ai/ru/card-sdk/verified-cards) приложения
(поиск прямо из меню добавления и значок «Проверена»), пришлите pull request в
`glmn-ai/neurosquad-cards`, как описано в его [SUBMITTING.md](https://github.com/glmn-ai/neurosquad-cards/blob/HEAD/docs/SUBMITTING.md). Каждая проверенная версия
закреплена на одном коммите.

### Опубликовать

1. Выполните `npx @neurosquad/card-sdk validate` и `pack --dry-run`. Исправьте все ошибки; прочитайте
превью диалога установки глазами незнакомого человека.
2. Закоммитьте всё, что нужно карточке, — включая результат сборки (`dist/`): приложение никогда
ничего не собирает. `pack` перечисляет ровно то, что будет установлено.
3. Запушьте в публичный репозиторий на GitHub (приватные тоже работают — для пользователей, которые
добавят GitHub-токен).
4. При желании поставьте тег релиза: `git tag v1.0.0 && git push --tags` — и создайте из тега релиз
на GitHub.
5. Сообщите людям адрес.

**Несколько карточек в одном репозитории** — это нормально: каждая лежит в своей папке со своим
манифестом и ставится как `owner/repo/path/to/folder`.

### С каких адресов можно установить

| Адрес | Что ставится | За чем следят обновления |
| --- | --- | --- |
| `owner/repo` | свежий коммит ветки по умолчанию | ветка по умолчанию |
| `owner/repo@main` | эта ветка | эта ветка |
| `owner/repo@v1.2.0` | этот тег | ни за чем — тег неизменен |
| `owner/repo@<40-hex commit>` | этот коммит | ни за чем |
| `https://github.com/owner/repo/releases/tag/v1.2.0` | этот релиз | **последний релиз** |
| `owner/repo/cards/pomodoro`, `https://github.com/owner/repo/tree/main/cards/pomodoro` | карточка из этой папки | как выше |

Подойдут и `github.com/owner/repo`, `https://github.com/owner/repo.git`. Ссылку (ref), в которой
есть `/`, нужно указывать через `@ref`.

**Привязка к коммиту.** Какой бы ни был адрес, приложение сводит его к одному коммиту и ставит файлы
этого коммита. Коммит, заданный хешем, должен быть достижим из ветки по умолчанию репозитория —
коммит, который есть только в форке, отклоняется, — а переименованный или переданный репозиторий
нужно ставить под его текущим именем. Приложение записывает коммит и хеш дерева всех файлов.
Введённый пользователем адрес — не идентичность карточки, ею является `github:owner/repo[/folder]`,
— поэтому обновление сохраняет разрешения карточки, её хранилище и все копии на всех холстах.

### Как обновления доходят до пользователей

- Приложение проверяет через минуту после запуска, потом каждые 24 часа и когда пользователь
нажимает **Check for updates**.
- Более новый коммит скачивается и проверяется, а потом предлагается: **Update** в настройках и точка
на карточке. **Ничего не применяется автоматически.**
- Пользователь видит, что меняется: новую версию, старый → новый коммит со ссылкой на сравнение в
GitHub и разницу в разрешениях:
  - **новые разрешения** и **новые сетевые хосты** → обновление ждёт согласия пользователя;
  - **разрешения, которые больше не нужны** → отзываются при обновлении;
  - новые **необязательные** разрешения → показываются как «может попросить позже» и никогда не
выдаются сами;
  - новые или переформулированные **инструменты**, новые порты или порты с другим типом, новые
**секретные настройки**, изменённые **displayName, автор или домашняя страница** → обновление
тоже ждёт согласия пользователя.
- При обновлении каждая открытая копия карточки перезагружается с `launch === 'updated'`.
Хранилище и настройки переносятся — если вы поменяли их структуру, переносите данные в коде.
- Если в новом приложении манифест перестал проходить проверку, карточка показывается сломанной, с
причиной; запускать её всё равно не будут.

> Перезапись тега или истории не протащит код мимо пользователей: тот же коммит, скачанный заново с
> другим содержимым, отклоняется, а каждое обновление показывается до применения. Но с каждым
> принятым обновлением пользователи доверяют вам — защитите свой аккаунт GitHub (2FA) и проверяйте
> пул-реквесты в вашу карточку как код, который будет работать на чужих машинах.

### Версии

**`version` вашей карточки** — для информации (установка привязана к коммитам), но пользователи
видят её в диалоге установки, в диалоге обновления и в **Settings → Custom cards**. Пользуйтесь
SemVer и повышайте её в каждом релизе. Ломающие изменения портов и инструментов описывайте в
описании: от них могут зависеть чужие карточки и привычки агентов.

**`minAppVersion`** не даёт поставить карточку в слишком старое приложение.

**Протокол** версионируется отдельно: `"protocol": 1` в манифесте, `CARD_PROTOCOL_VERSION` в SDK.

- Новые методы, события и необязательные поля появляются **внутри** протокола 1. Проверяйте их
наличие через `card.host.supports('method.name')` и продолжайте работать без них.
- Ломающее изменение стало бы протоколом 2. Приложение, которое знает только 1, отклонит карточку под
2 с сообщением «нужен более новый NeuroSquad»; карточки протокола 1 приложение продолжало бы
обслуживать параллельно ещё минимум год.
- Обновлять `@neurosquad/card-sdk` в пределах одной мажорной версии безопасно; пересоберите и
опубликуйте заново.

### Изменение разрешений и того, что предлагает карточка

Добавив обязательное разрешение или сетевой хост — или инструмент, порт, секретную настройку, или
поменяв имя, автора или домашнюю страницу карточки, — вы заставляете каждого текущего пользователя
принять обновление, прежде чем он получит из него **хоть что-то**, включая исправления ошибок.
Подумайте о том, чтобы:

- сделать новое разрешение **необязательным** и просить его, когда пользователь дойдёт до функции;
- выпустить изменение разрешений отдельным релизом и объяснить его в описании.

### Как вывести карточку из обращения

Не удаляйте репозиторий: установленным копиям он для работы не нужен, но нужен для обновлений и
переустановки. Напишите об этом в описании и укажите замену.

---

## Чек-лист безопасности

> Что песочница уже гарантирует и чек-лист для автора перед публикацией карточки — минимум прав, внедрение промптов, секреты, сеть, файлы, команды и обновления.

Source: https://docs.neurosquad.ai/ru/card-sdk/security

Ваша карточка будет работать на чужих машинах рядом с агентами, которые могут править код и
запускать команды. Приложение многое делает, чтобы её сдержать, — но что вы попросите и что сделаете
с этим, зависит от вас. Эта страница — чек-лист, который стоит пройти перед тем, как делиться
карточкой, и снова перед каждым релизом.

### Что приложение уже гарантирует

Ослабить это вы не должны (и не сможете):

- Карточка работает в отдельном изолированном процессе без доступа к приложению, Node.js, другим
карточкам, cookies и `localStorage` и не может открывать окна, уводить приложение на другую
страницу или рисовать за пределами своей коробки.
- Она ни до чего не может дотянуться — ни до сети, ни до файлов, ни до агентов, — кроме как через
SDK, а приложение сверяет каждый запрос с тем, что выдал пользователь.
- Её страница загружает только файлы из собственного пакета: никаких удалённых скриптов, встроенных
скриптов и `eval`.
- В страницах карточек отключены WebRTC и предварительный DNS, так что обходных каналов в сеть нет.
Формы никогда не уводят страницу, вложенные фреймы удаляются, а писать в буфер обмена сама
страница не может.
- Решения и секреты запрашиваются в собственном диалоге приложения на всё окно, который карточка не
может подделать; ваш текст появляется там только как цитата.
- Даже с `fs.write` нельзя изменить `.git`, настройки агентов и редакторов, CI-процессы и настройки
пакетных менеджеров, а если воркспейс — домашняя папка или корень диска, доступа к файлам у
карточек нет вовсе.
- Промпты и команды ограничены на карточку (6 и 30 в минуту), каким бы способом их ни отправляли, а
промпты в очереди выбрасываются, когда пропадает стрелка или разрешение.
- Данные доходят до другой карточки или агента только по стрелке, которую провёл пользователь.
- Секреты, введённые в настройки `secret`, никогда не доходят до карточки.
- У каждой копии карточки своё хранилище; пакеты не могут читать данные друг друга.

### Перед публикацией

**Разрешения**

- [ ] Каждое разрешение действительно используется. Уберите лишние — каждое из них это строка в
диалоге установки и повод отказаться.
- [ ] У каждого разрешения есть `reason` простыми словами.
- [ ] Редко нужные сильные разрешения сделаны `optional` и запрашиваются в момент использования.
- [ ] В `network` перечислены конкретные хосты. Никаких доменов «на всё», сервисов для вставки
текста, сокращателей ссылок и масок `*.`, без которых можно обойтись.
- [ ] Вы не используете `network.local`, если карточка не про локальные серверы.

**Промпты, инструменты и команды** — самая рискованная часть

- [ ] Ничего из интернета, файла, порта или вывода агента не уходит в `agents.prompt` или
`terminals.run/write`, пока пользователь это не увидит. Иначе одна враждебная веб-страница или
файл может перехватить управление агентом пользователя (внедрение промптов).
- [ ] Промпты, собранные из недоверенного текста, отправляются с `submit: false`, чтобы пользователь
сам проверил и отправил их.
- [ ] Команды — это фиксированные строки или собираются из настроек, которые ввёл пользователь, но
никогда не из скачанных данных. Всё, что подставляете, экранируйте.
- [ ] Инструменты, которые может вызвать агент, не делают ничего разрушительного (запись файлов,
команды, промпты, трата денег) без предварительного `card.ui.confirm`.
- [ ] Результаты инструментов со сторонним содержимым говорят, откуда оно, и остаются короткими.
- [ ] Вы никогда не отправляете промпты в цикле. Лимит — 6 промптов в минуту, и бюджет всё равно
считается.

**Секреты**

- [ ] API-ключи — это настройки `secret`, которые используются как `{{secret:key}}` в заголовках, —
никогда не текстовое поле внутри карточки, не хранилище, не код и не репозиторий.
- [ ] Карточка не просит пароли или ключи внутри своего тела. Пользователям сказано, что NeuroSquad
так никогда не делает и что настоящий запрос затемняет всё окно.
- [ ] Карточке не нужны секреты на `localhost` — туда они никогда не отправляются.

**Файлы**

- [ ] `fs.write` действительно нужен. Если вы только выпускаете отчёт, подумайте о том, чтобы
отправлять его в заметку.
- [ ] Вы пишете только туда, где этого ждёт пользователь (например, в папку из настройки), и никогда
не поверх конфигурации, lock-файлов, файлов CI или скриптов, которые выполняются при сборке.
- [ ] Вы используете `ifMtimeMs`, когда переписываете файл, который пользователь может править.
- [ ] Вы не читаете `.env` и другие файлы с секретами, если в этом не заявленное назначение
карточки.

**Что вы показываете и отправляете**

- [ ] Сторонний текст выводится как текст (`textContent`), а не как HTML (`innerHTML`). Худшее
песочница остановит, но вашу карточку всё равно можно испортить или запутать.
- [ ] Порты отправляют только то, что сказано в их описании.
- [ ] Вы не реагируете на события `message` у `window`: написать в ваш фрейм может любая карточка.
Доверять можно только каналу SDK.

**Упаковка и обновления**

- [ ] `pack --dry-run` перечисляет только то, что вы собирались выпустить, — никаких `.env`, ключей,
личных заметок, `node_modules` или тестовых данных с настоящими сведениями. (`pack` отказывается
упаковывать файлы, похожие на учётные данные, если не передать `--allow-secret-files`.)
- [ ] Ваше имя и автор не выдают себя за NeuroSquad, official или verified.
- [ ] На аккаунте GitHub включена двухфакторная аутентификация. Любой, кто может пушить в ваш
репозиторий, может выпустить обновление вашим пользователям.
- [ ] Зависимости зафиксированы (lock-файл), и перед релизом вы собираете с чистой установки.
- [ ] Изменения, добавляющие разрешения, выходят отдельным релизом с объяснением.

**Поведение**

- [ ] Карточка ставит на паузу опрос и анимации, когда её не видно, и сохраняется в `onSuspend`.
- [ ] Сетевой опрос разумный (лимит — 120 запросов в минуту; держитесь намного ниже).
- [ ] Карточка работает — упрощается, объясняет, — когда разрешение отозвано.

> Нашли, как карточке выбраться из своей коробки, получить то, что ей не выдавали, или обмануть
> собственные диалоги приложения? Это уязвимость NeuroSquad, а не вашей карточки, — сообщите команде
> лично, через [сервер в Discord](https://docs.neurosquad.ai/ru/help/faq#discord), а не в открытой ветке.

### Что говорят пользователям

Диалог установки говорит пользователям этими словами, что карточка — код сообщества, который
NeuroSquad не проверял, что каждое разрешение означает в худшем случае (например, что при доступе к
сети «туда может уйти всё, что видит карточка») и что «всё внутри карточки принадлежит самой
карточке». Пишите описание и причины так, чтобы осторожный пользователь, прочитав эти строки, всё
равно согласился.

---

## На телефоне

> Как свои карточки выглядят при удалённом доступе — только шапка и плитка обзора, код работает на компьютере, — и что это значит для дизайна карточки.

Source: https://docs.neurosquad.ai/ru/card-sdk/phone

При [удалённом доступе](https://docs.neurosquad.ai/ru/remote) телефон показывает весь холст. Свои карточки — единственное
исключение из правила «всё работает так же»: **телефон никогда не запускает код карточек.** У кода
сообщества одна песочница — на компьютере, а не вторая, более слабая, в браузере телефона.

Что телефон показывает для своей карточки:

- **шапку** — иконку, заголовок, плашку статуса и бейдж, ровно такими, какими их задала ваша
карточка;
- **содержимое обзора**, которое вы задали через [`card.setOverview()`](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#overview), —
при любом масштабе, а не только при отдалении;
- строку **«Open on the computer to use this card»** («Откройте на компьютере, чтобы пользоваться
карточкой»).

Пока кто-то смотрит с телефона, продолжает работать всё, что работает на компьютере. Инструменты,
которые вызывают агенты, порты, которые доставляют данные, промпты и команды — всё это выполняется
на странице карточки на компьютере, пока там открыт её воркспейс (усыплённую карточку, как обычно,
разбудят по требованию).

С телефона нельзя устанавливать, обновлять, выдавать разрешения, подключать папки или отвечать на
диалоги карточки: при удалённом доступе всё это заблокировано и требует компьютера.

### Как это учесть в дизайне

- **Пусть обзор рассказывает главное.** `primary` — один факт (`3 failing`, `Deploy ready`,
`Waiting for review`), `secondary` — подробность, `progress` — полоса, `tone` — цвет, `icon` — из
[иконок приложения](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#overview). Обновляйте его всякий раз, как этот факт
меняется.
- **Пользуйтесь плашкой статуса и бейджем** для того, что должно быть видно с первого взгляда.
- **Вызывайте `card.attention('needs-input', …)`**, когда пользователь должен что-то сделать, —
карточка пульсирует и попадает во входящие (Inbox).
- **Не полагайтесь на страницу карточки ни в чём срочном**: пользователь на телефоне не может её ни
увидеть, ни нажать.

В версии 1 запустить страницу вашей карточки на телефоне нельзя.

---

## Вопросы и решение проблем

> Ответы для пользователей и авторов карточек и решения частых ошибок — карточка не подключается, скрипты заблокированы, после установки не хватает файлов, ошибки разрешений и стрелок, ограничения частоты.

Source: https://docs.neurosquad.ai/ru/card-sdk/faq

### Для всех

#### Безопасна ли карточка сообщества?

Она заперта в своей коробке и может только то, что вы разрешили, — приложение проверяет каждый
запрос. Но сами разрешения бывают сильными: карточка, которой можно давать указания агентам или
запускать команды, может всё, что могут эти агенты и терминалы. Ставьте карточки от тех, кому
доверяете, и читайте диалог. См. [Установку карточек сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards).

#### Карточка просит ввести API-ключ прямо в ней. Вводить?

Нет. NeuroSquad никогда не спрашивает ключи внутри карточки. Хорошо сделанная карточка просит ключи
в своей форме **Settings…** (это собственная форма приложения), где они хранятся в зашифрованном виде
и никогда не показываются карточке. Всё, что вы вводите в тело карточки, уходит карточке.

#### Почему карточка пишет «Paused to save memory»?

Карточки, на которые вы давно не смотрели, усыпляются, чтобы большой холст оставался быстрым.
Посмотрите на неё — она продолжит с того же места.

#### Карточка пишет «Not responding».

Её код занят больше 15 секунд. Нажмите **Reload**. Если это повторяется, выключите карточку в
**Settings → Custom cards** и сообщите её автору. Больше ничего на холсте это не затрагивает.

#### Почему нельзя пользоваться своей карточкой на телефоне?

Код карточек работает только на компьютере; телефон показывает шапку и сводку. См.
[На телефоне](https://docs.neurosquad.ai/ru/card-sdk/phone).

#### При установке пишет, что GitHub ограничивает запросы.

GitHub ограничивает анонимные скачивания. Добавьте **GitHub token** в **Settings → Custom cards** — с
ним можно ставить и из приватных репозиториев.

### Для авторов

#### `connect()` падает с `UNAVAILABLE`.

- **Страница открыта вне приложения** (во вкладке браузера): так и должно быть. Для превью
используйте [мок-хост](https://docs.neurosquad.ai/ru/card-sdk/testing), как это делают шаблоны.
- **Внутри приложения:** SDK должен импортироваться входным скриптом, чтобы слушать ещё до окончания
загрузки страницы. Ленивый `import()` SDK может пропустить рукопожатие приложения.

#### Мой скрипт не запускается. В консоли — нарушение политики безопасности контента.

Карточки не могут выполнять встроенные скрипты и атрибуты `onclick="…"` и не могут загружать скрипты,
стили, шрифты и картинки из интернета. Перенесите код в файлы `.js`, соберите зависимости в пакет,
положите шрифты в пакет. `npx @neurosquad/card-sdk validate` укажет на проблемные места во входной
странице. См. [Правила песочницы](https://docs.neurosquad.ai/ru/card-sdk/styling#sandbox-rules-for-pages).

#### С `dev` всё работает, а после установки с GitHub страница пустая или не хватает файлов.

Установленная карточка — это ровно то, что лежит в вашем репозитории на этом коммите. Обычно
результат сборки не закоммичен (`dist/` в `.gitignore`) или ресурсы указаны абсолютными путями
(`/assets/…`) вместо относительных (`./assets/…`; в Vite — `base: './'`). Запустите
`pack --dry-run`, чтобы увидеть, что получат пользователи.

#### `validate` пишет, что файл «exists but would not be in the package (ignored by git?)».

Список файлов — это то, что git положил бы в архив GitHub: отслеживаемые файлы плюс
неотслеживаемые, но не игнорируемые. Закоммитьте файл или уберите его из игнорируемых. Так бывает
и когда папка карточки лежит внутри игнорируемой папки другого репозитория — перенесите её или
заведите для неё отдельный репозиторий.

#### `PERMISSION_DENIED`

Разрешение не объявлено в манифесте, пользователь его отозвал, или оно необязательное и ещё не
выдано. Какое именно — в `error.permission`. Объявите его или попросите через
`card.permissions.request()`, пока карточка видна. Для подключённой папки изменение разрешений в
манифесте снова спросит вас.

#### `NOT_CONNECTED`

Агент, терминал или карточка, к которой вы обращаетесь, не соединены с вашей карточкой стрелкой.
Попросите пользователя её провести — что подключено, говорят `card.ports.peers` и `agent.connected`.

#### `emit` возвращает 0.

Ни у одной карточки ниже по стрелке нет совместимого входа. Проверьте направление стрелки (от вашей
карточки к соседней), типы (см. [Преобразование типов](https://docs.neurosquad.ai/ru/card-sdk/api/ports#conversion)) и, для
встроенных карточек, наличие `cards.connected`.

#### `NOT_VISIBLE`

Диалогам, ссылкам, полёту камеры, запросам разрешений, форме настроек и промптам агентам в опасном
режиме нужно, чтобы карточка была на экране. Вызывайте их из действия пользователя или ждите, пока
`lifecycle.visibility` станет `visible`.

#### `RATE_LIMITED`

Подождите `error.retryAfterMs`. Лимиты методов: внимание раз в 10 с, тосты раз в 2 с, изменение
размера раз в 500 мс, буфер обмена раз в секунду, промпты 6 в минуту, команды 30 в минуту, сеть 120
в минуту, выходы портов 20 в секунду. См. [Лимиты](https://docs.neurosquad.ai/ru/card-sdk/api/errors#limits).

#### `HOST_NOT_ALLOWED`

Хоста из URL нет среди ваших хостов `network` (поддомен не совпадает с точным хостом — используйте
`*.example.com`), редирект увёл в другое место, или хост резолвится в частный адрес. Для `localhost`
объявите `network.local`.

#### Мой инструмент не появляется у агента.

- Инструменты карточки видят только агенты, соединённые с ней стрелкой, и только агенты с MCP
(Claude Code, Codex, Qwen Code).
- Агенту может понадобиться новый ход, чтобы заметить изменившийся список инструментов.
- Проверьте имя: агенты видят `<card name with _>_<tool>`, например `test_radar_run_tests`.
- `card.tools.setEnabled(name, false)` скрывает инструмент у всех копий карточки.

#### Где смотреть ошибки моей карточки?

Запустите `npx @neurosquad/card-sdk dev`: он транслирует `card.log.*`, необработанные ошибки и
отклонённые промисы. Приложение тоже хранит последние 256 КБ журнала каждого пакета.

#### Может ли карточка работать в фоне?

Объявите разрешение `background`. Без него карточку, чей воркспейс скрыт минуту, усыпляют:
сохраняйтесь в `card.lifecycle.onSuspend` и восстанавливайтесь при `launch === 'resumed'`.

#### Можно ли пользоваться `localStorage`, IndexedDB, cookies, WebSocket, `window.open`?

Нет — у песочницы нет источника (origin) для хранилища и нет всплывающих окон. Используйте
`card.storage`, `card.net.fetch` (потоковые ответы покрывают server-sent events; WebSocket в
версии 1 не поддерживается) и `card.openLink`.

#### Может ли карточка читать буфер обмена, пользоваться камерой или микрофоном, выбрать файл?

Не в версии 1. Карточка может записать текст в буфер обмена (`clipboard.write`) и работать с файлами
в папке воркспейса (`fs.read`, `fs.write`).

#### Есть ли галерея карточек?

Пока нет — карточками делятся по их адресу на GitHub.

#### Форма ничего не перезагружает и никуда не отправляет.

Так и задумано: события `submit` срабатывают, но страница карточки никогда не уходит на другой адрес
и не отправляет форму. Обрабатывайте данные в обработчике `submit` (вызовите
`event.preventDefault()`). См. [Правила песочницы](https://docs.neurosquad.ai/ru/card-sdk/styling#sandbox-rules-for-pages).

#### Карточка продолжает пульсировать после перезагрузки.

Внимание, поднятое прежним запуском страницы, переживает перезагрузки и обновления. При запуске
проверьте `card.context.chrome?.attention` и снимите его через `card.attention('none')`, когда
причины больше нет.

#### В пакете нет `dist/`, хотя я его собрал.

`.gitignore` родительского репозитория может игнорировать `dist`. Добавьте `!dist/` в `.gitignore`
карточки (в шаблоне React это уже сделано) и проверьте через `pack --dry-run`.

#### Кнопка «копировать» ничего не делает.

Страница не может писать в буфер обмена через события `copy` или `execCommand`. Объявите
`clipboard.write` (можно необязательным) и вызывайте `card.copyText(text)`.

#### `new Worker('worker.js')` не работает.

В карточке работают только blob-воркеры: скачайте скрипт, сделайте из него `Blob` и запустите
воркер из `URL.createObjectURL(blob)`.

#### Установка карточки отклонена: «only official cards may call themselves…».

Карточки, опубликованные не из официальной организации, не могут использовать «NeuroSquad»,
«official» или «verified» в имени или авторе. Переименуйте карточку.

#### Запись отклоняется с `FS_DENIED`, хотя у меня есть `fs.write`.

Путь [защищён](https://docs.neurosquad.ai/ru/card-sdk/api/files#protected) (`.git`, настройки агентов, CI-процессы, настройки
пакетных менеджеров), или воркспейс — это домашняя папка или корень диска, где у карточек нет доступа
к файлам.

---

## Помощь

> Ответы, решения проблем, горячие клавиши и где хранятся ваши данные.

Source: https://docs.neurosquad.ai/ru/help

Что-то не получается, интересно или нужна горячая клавиша? Начните отсюда.

  - **[Частые вопросы](https://docs.neurosquad.ai/ru/help/faq)**: Короткие ответы на самые частые вопросы.
  - **[Решение проблем](https://docs.neurosquad.ai/ru/help/troubleshooting)**: Частые проблемы и как их решить.
  - **[Горячие клавиши](https://docs.neurosquad.ai/ru/help/shortcuts)**: Все сочетания клавиш в NeuroSquad.
  - **[Где хранятся ваши данные](https://docs.neurosquad.ai/ru/help/data)**: Что NeuroSquad хранит на вашем компьютере и как сделать резервную копию или всё сбросить.
  - **[Документация для ИИ-ассистентов](https://docs.neurosquad.ai/ru/help/ai-assistants)**: Каждая страница в виде простого Markdown и всё руководство одним файлом — для агента.

> Не нашли ответ? Спросите в [Discord-сервере NeuroSquad](https://discord.gg/DyKn8cGTc) — там отвечают разработчики и другие пользователи.

---

## Частые вопросы

> Короткие ответы на самые частые вопросы.

Source: https://docs.neurosquad.ai/ru/help/faq

#### NeuroSquad — это ИИ?

Нет. Он запускает ИИ-агентов, которыми вы уже пользуетесь, — Claude Code, Codex, Qwen Code и других —
и даёт им общий холст, инструменты и уведомления.

#### На каких системах он работает?

Windows 10 и 11 (64-бит), из готового установщика на нашей
[странице загрузки](https://neurosquad.ai/ru/download/). На Mac (macOS 12 и новее, Apple silicon или Intel) — см.
[Установка на macOS](https://docs.neurosquad.ai/ru/getting-started/macos). Версия для Linux появится позже.

#### Как его установить и обновить?

Скачайте `NeuroSquad-Installer.exe` со [страницы загрузки](https://neurosquad.ai/ru/download/) и
запустите его — он скачает последнюю версию — или воспользуйтесь winget, Scoop либо командой
PowerShell. Дальше NeuroSquad обновляется сам; ваши данные сохраняются. См. [Установка](https://docs.neurosquad.ai/ru/getting-started/installation).

#### Нужен ли аккаунт?

Да, бесплатный аккаунт NeuroSquad: при первом запуске приложение попросит войти — в браузере, по коду
из письма или через Google. У каждого аккаунта тариф Free без ограничений. В самих агентов вы тоже
входите, как в обычном терминале. См. [Аккаунт и вход](https://docs.neurosquad.ai/ru/getting-started/account).

#### На каких языках приложение?

На английском, русском и китайском. Выберите язык настройкой **Language** в **Settings** — он
применяется мгновенно. Пока вы не выбрали, NeuroSquad следует языку системы.

#### Платно ли пользоваться агентами?

Агентов оплачиваете их собственным провайдерам — ровно так же, как если бы запускали их сами.
NeuroSquad показывает, сколько токенов они тратят, в разделе [Расход и стоимость](https://docs.neurosquad.ai/ru/usage), а
[карточка бюджета](https://docs.neurosquad.ai/ru/cards/budget) может ограничить расход.

#### Мой код куда-то отправляется?

Сам NeuroSquad никуда ваш код не отправляет. Агенты общаются со своими ИИ-сервисами, как и всегда.
Диктовка целиком работает на вашем компьютере. Приложение отправляет только статистику
использования — счётчики вроде числа карточек каждого типа в воркспейсе, но никогда код, имена
файлов, пути или промпты. Полный список — в разделе [Аккаунт и вход](https://docs.neurosquad.ai/ru/getting-started/account#what-the-app-sends).

#### Можно ли использовать другую ИИ-модель?

Да. Подключите ключ [OpenRouter](https://docs.neurosquad.ai/ru/providers/openrouter) и запускайте Claude Code, Codex CLI,
OpenCode, Kilo Code, Qwen Code, Hermes Agent или Crush на сотнях моделей.

#### Можно ли общаться с агентами из Telegram?

Да — подключите своего бота [карточкой Telegram](https://docs.neurosquad.ai/ru/integrations/telegram). До агентов доходят только
чаты, которые вы разрешили.

#### Какие агенты умеют пользоваться стрелками?

Claude Code, Codex CLI и Qwen Code. Остальные агенты отлично работают в карточках, но пока не умеют
пользоваться подключёнными карточками. См. [Поддерживаемые агенты](https://docs.neurosquad.ai/ru/agents).

#### Продолжают ли агенты работать, если переключить воркспейс?

Да. Переключение воркспейсов ничего не останавливает. А если включить **Keep agents running when the
window is closed** (Settings → System), агенты продолжат работать даже после закрытия окна.

#### Могут ли два агента работать над одним проектом?

Да. Чтобы они не мешали друг другу, дайте им [изолированные worktree](https://docs.neurosquad.ai/ru/agents/worktrees) или
разбейте работу на отдельные задачи на [доске задач](https://docs.neurosquad.ai/ru/cards/kanban).

#### Переживёт ли разговор перезапуск?

Claude Code, Qwen Code и Pi — да, они продолжают тот же разговор. Остальные агенты начинают с чистого
листа.

#### Можно ли пользоваться с телефона?

Да — см. [Удалённый доступ](https://docs.neurosquad.ai/ru/remote).

#### Удаляются ли мои файлы, если удалить воркспейс или карточку?

Никогда. Они только убираются из NeuroSquad.

#### Есть ли светлая тема?

Пока нет. NeuroSquad бывает только тёмным.

#### Где задать вопрос или предложить идею?

На нашем [сервере в Discord](https://discord.gg/DyKn8cGTc). Спрашивайте что угодно, сообщайте об ошибках и предлагайте новые
возможности — команда всё читает.

---

## Решение проблем

> Частые проблемы и как их решить.

Source: https://docs.neurosquad.ai/ru/help/troubleshooting

#### При запуске установщика Windows пишет «Windows protected your PC»

Установщик пока не подписан, поэтому SmartScreen о нём предупреждает. Нажмите **More info**,
убедитесь, что это `NeuroSquad-Installer.exe`, затем нажмите **Run anyway**. Скачивайте установщик
только с нашей [страницы загрузки](https://neurosquad.ai/ru/download/). См.
[Установка](https://docs.neurosquad.ai/ru/getting-started/installation).

#### Веб-установщик пишет, что не удалось скачать NeuroSquad

`NeuroSquad-Installer.exe` нужен доступ к github.com, где публикуется NeuroSquad. Проверьте
подключение или прокси и нажмите **Повторить**. Если GitHub ограничивает запросы из вашей сети,
подождите несколько минут — или скачайте полный установщик напрямую:
`https://neurosquad.ai/downloads/NeuroSquad-Setup.exe`. Файл, контрольная сумма SHA-256 которого не
совпала, веб-установщик никогда не запускает. Его журнал — `%TEMP%\NeuroSquad-Installer-<дата>.log`.

#### Установка не удалась или установщик пишет, что NeuroSquad ещё работает

Закройте NeuroSquad (в том числе из трея) или дайте установщику завершить его процессы кнопкой
**Завершить и продолжить**. В остальных случаях страница ошибки объясняет, что пошло не так, а
полный журнал лежит в `%TEMP%\NeuroSquad-Setup-<дата>.log` (и в `install.log` в папке установки).
Неудачное обновление оставляет прежнюю версию рабочей. См.
[Если что-то пошло не так](https://docs.neurosquad.ai/ru/getting-started/installation#if-something-goes-wrong).

#### Установленный агент показан как «Not found»

Откройте **Settings → Harnesses** и нажмите **Check again**. Всё ещё не видно? Полностью закройте
NeuroSquad (в том числе из трея) и запустите снова или установите агента через **Settings → Setup**.

#### Карточка агента сразу закрывается

Попробуйте запустить того же агента в своём терминале, в той же папке. Сообщение, которое он там
покажет, обычно и есть ответ — чаще всего агент просто ещё не вошёл в аккаунт.

#### Я провёл стрелку, а агент говорит, что инструментов у него нет

- Проверьте, что агент — Claude Code, Codex CLI или Qwen Code.
- Для стрелок между агентами проверьте направление: **от** ведущего **к** помощнику.
- Попросите агента «проверить свои подключения в NeuroSquad».

#### Агент запустил команду в своём окне, а не в моей карточке терминала

Скажите это в промпте: *«запускай все команды в подключённом терминале»*. Или включите
[режим карточек](https://docs.neurosquad.ai/ru/squads/canvas-mode).

#### Карточка браузера не запускается

В первый раз ей нужно скачать браузер. Если загрузка прервалась, откройте **Settings → Browser** и
нажмите **Resume download**.

#### Диктовка ничего не делает

- Возможно, модель распознавания речи ещё не скачана — тогда в строке состояния написано
**Dictation: download the model**. Скачайте её в **Settings → Dictation**.
- Возможно, та же горячая клавиша занята другим приложением — поменяйте её в **Settings → Dictation**.
- Проверьте, что Windows разрешает настольным приложениям пользоваться микрофоном (**Параметры
Windows → Конфиденциальность и защита → Микрофон**).
- Если текст попал в буфер обмена, но не в агента, значит, окно NeuroSquad не было активным — просто
вставьте его.

#### Телефон не подключается

- В режиме **Local network** телефон должен быть в той же сети Wi-Fi. Попробуйте выбрать другой
**Network address** в **Settings → Remote access**.
- В режиме **quick internet tunnel** адрес меняется при каждом запуске NeuroSquad — отсканируйте код
заново.

#### В разделе Usage ничего нет

Расход читается из журналов Claude Code, Codex CLI, OpenCode, Hermes Agent, Pi и omp; остальные агенты не
учитываются. Попробуйте период подлиннее или нажмите **Refresh**.

#### Карточка Telegram не подключается

Вставьте целиком токен, который прислал BotFather, затем отправьте своему боту `/start` и нажмите
**Allow** в карточке. Сообщения из чатов, которые вы не разрешили, игнорируются.

#### Агент на OpenRouter входит под моим обычным аккаунтом

Ключ не сохранён — плашка модели у агента становится янтарной. Добавьте ключ в **Settings →
Providers** и перезапустите агента.

#### С большим количеством карточек всё тормозит

Каждая карточка агента — это работающая программа. Закройте те, что больше не нужны, и отдалите
холст — карточки превратятся в лёгкие [плитки обзора](https://docs.neurosquad.ai/ru/canvas/moving-around).

### Не помогло?

Напишите в [Discord-сервер NeuroSquad](https://discord.gg/DyKn8cGTc): что вы делали, чего ожидали и что произошло на самом
деле. Скриншот очень поможет.

### «… не установлен» на карточке агента

CLI агента этой карточки нет на компьютере (или его нет в PATH) — например, ведущий агент создал
помощника на агенте, которого у вас нет. Карточка предлагает **Установить…** (мастер установки),
**Выбрать другой харнесс** (переключает карточку на установленный, сохраняя её место и стрелки) и
**Повторить** (если вы поставили его сами — перезапуск не нужен).

---

## Горячие клавиши

> Все сочетания клавиш в NeuroSquad.

Source: https://docs.neurosquad.ai/ru/help/shortcuts

### В любом месте приложения

| Сочетание | Что делает |
| --- | --- |
| `Ctrl Shift P` | Перейти к любому агенту по имени |
| `Ctrl Shift A` | Входящие «Needs attention» |
| `Ctrl Shift J` | Перелететь к агенту, который ждёт вас дольше всех |
| `Ctrl Shift F` | Поиск по выводу всех агентов |
| `Ctrl Shift B` | Режим фокуса — скрыть сайдбар и строку состояния |
| `Ctrl Shift /` | Показать этот список |
| `Ctrl Shift Space` | Диктовка (работает, даже когда NeuroSquad не на переднем плане) |

### В терминале

| Сочетание | Что делает |
| --- | --- |
| `Ctrl F` | Поиск по этому терминалу |
| `Ctrl` + прокрутка | Крупнее или мельче текст |
| правый клик | Copy, Paste, Select all |

Всё остальное уходит самому агенту, так что его собственные сочетания клавиш работают как обычно.

### На холсте

| Сочетание | Что делает |
| --- | --- |
| `Shift` + перетаскивание | Выделить несколько карточек |
| `Delete` | Удалить выделенное (сначала спросит) |
| `Ctrl Z` | Отменить перемещение или изменение размера |
| `Ctrl Shift Z` или `Ctrl Y` | Повторить |
| `F5` | Показать карточки по одной |
| щелчок по стрелке | Открыть журнал стрелки |

---

## Где хранятся ваши данные

> Что NeuroSquad хранит на вашем компьютере, где именно и как это сохранить в резервную копию или сбросить.

Source: https://docs.neurosquad.ai/ru/help/data

Всё, что помнит NeuroSquad, — воркспейсы, карточки, раскладки холста, заметки, списки дел,
настройки, история диктовки — хранится в одной папке на вашем компьютере:

```text
%APPDATA%\NeuroSquad
```

Вставьте этот путь в адресную строку Проводника Windows, чтобы открыть папку. Установка новой версии
эту папку не трогает, удаление приложения тоже — если в окне удаления не включить **Удалить и мои
данные NeuroSquad**. См. [Удаление](https://docs.neurosquad.ai/ru/getting-started/installation#uninstalling).

На Mac папка такая:

```text
~/Library/Application Support/NeuroSquad
```

В Finder выберите **Переход → Переход к папке…** (`⇧` `⌘` `G`) и вставьте путь.
Обновления её не трогают, перенос приложения в Корзину — тоже.

### Чего там нет

- **Вашего кода.** NeuroSquad помнит только, где лежит папка проекта. Он никогда её не копирует.
- **Входа в аккаунты агентов.** Агенты используют собственный вход; NeuroSquad его не видит.
- **Ключи, которые вы сохраняете в NeuroSquad** (OpenRouter, токены ботов Telegram), шифруются
средствами системы (Windows или Связка ключей на Mac), и прочитать их обратно нельзя — даже с телефона.
- **Звука.** От диктовки остаётся только текст.

### Что уходит с компьютера

Вход в аккаунт NeuroSquad и, пока вы вошли, статистика использования — только счётчики, никогда код,
имена файлов, пути или промпты. Выход из аккаунта ничего в этой папке не удаляет. См.
[Аккаунт и вход](https://docs.neurosquad.ai/ru/getting-started/account#what-the-app-sends).

### Резервная копия, перенос и сброс

- **Резервная копия:** скопируйте папку.
- **Перенос на другой компьютер:** скопируйте туда папку. Если проекты там лежат в других местах,
поменяйте папку у каждого воркспейса. Сохранённые ключи не переносятся — введите их заново.
- **Начать с чистого листа:** закройте NeuroSquad и удалите папку. Ваши проекты это не затронет.

> Прежде чем что-то менять в этой папке, закройте NeuroSquad (в том числе из трея).

---

## Документация для ИИ-ассистентов

> Передайте эту документацию ChatGPT, Claude или агенту в карточке — каждая страница в виде простого Markdown и оглавления одним файлом.

Source: https://docs.neurosquad.ai/ru/help/ai-assistants

Это руководство могут читать и ваши агенты. У каждой страницы есть версия для них — простой
Markdown, без меню и скриптов, — так что агент в карточке NeuroSquad или ИИ-ассистент в браузере
ответит на вопрос «как сделать…» о NeuroSquad по настоящей документации.

### Каждая страница в Markdown

Добавьте `.md` к адресу любой страницы:

| Страница | Markdown |
| --- | --- |
| `https://docs.neurosquad.ai/ru/canvas/arrows` | `https://docs.neurosquad.ai/ru/canvas/arrows.md` |
| `https://docs.neurosquad.ai/ru/agents` | `https://docs.neurosquad.ai/ru/agents.md` |

Интерактивные копии интерфейса приложения в Markdown не попадают; всё, что они показывают, есть в
тексте вокруг них.

### Всё руководство одним файлом

| Файл | Что в нём |
| --- | --- |
| [`/ru/llms.txt`](https://docs.neurosquad.ai/ru/llms.txt) | Все страницы по разделам — с кратким описанием и ссылкой на `.md` |
| [`/ru/llms-full.txt`](https://docs.neurosquad.ai/ru/llms-full.txt) | Все страницы целиком, одним Markdown-файлом |

Они следуют соглашению [llms.txt](https://llmstxt.org). У английской и китайской версий — свои:
`/llms.txt`, `/llms-full.txt`, `/zh/llms.txt`, `/zh/llms-full.txt`. Есть такой файл и у сайта
продукта — [neurosquad.ai/ru/llms.txt](https://neurosquad.ai/ru/llms.txt): главные факты,
поддерживаемые CLI агентов, плагины и последние релизы.

### Спросите агента в NeuroSquad

Дайте карточке агента вопрос и адрес. CLI агента с инструментом загрузки веб-страниц (у Claude Code
он есть) прочитает страницу сам:

```text
Прочитай https://docs.neurosquad.ai/ru/llms.txt, найди страницу про очередь промптов
и расскажи, как отправить три промпта один за другим.
```

Или проведите стрелку от агента к [карточке браузера](https://docs.neurosquad.ai/ru/cards/browser), и он откроет документацию там.

> Markdown собирается из тех же страниц, что вы читаете, при каждой публикации документации, поэтому
> он никогда не старее сайта.

## Другие языки

- en: https://docs.neurosquad.ai/llms-full.txt
- zh: https://docs.neurosquad.ai/zh/llms-full.txt