---
id: README
updated: 2026-08-16 14:20 GMT+3
---

# Demonstrator Agent Rules

**Для агента primary-источник — эти `.md` файлы** (и этот README). HTML-страница `/agent/` с вкладками — зеркало для человека; не полагайся на вкладки как на полный контекст.

## Скоуп MCP

Агент пишет контент, структурирует курс (порядок, перенос, копирование), soft-delete в корзину и восстанавливает из корзины. Медиа, виджеты, темы, создание/обновление share-ссылок — да.

**Вне MCP (не вызывай и не обходи):** permanent delete проекта/ресурса; снятие share-ссылок; приглашения и ACL пространства; suggestions propose/apply (WIP); restore из entity-snapshot / backup ZIP.

## MCP — только `app.longread.agency`

Единственная среда: **`https://app.longread.agency`**.

- MCP: `https://app.longread.agency/mcp/demonstrator/mcp`. Токен уже лежит в конфиге MCP-клиента в IDE (`mcp.json` → `headers.Authorization`, значение после `Bearer `) — не бери его из переменных окружения и не проси «из ЛК». В Cursor сервер `demonstrator-mcp` / `user-demonstrator-mcp`.
- Share, материалы, ссылки человеку — только с хостом `app.longread.agency`.
- Если tool вернул share/`url` с `localhost` или `127.0.0.1` — **не отдавай как есть**: замени host на `https://app.longread.agency`, тот же `token` в query. Проверь, что страница открывается.
- Другие MCP-серверы Демонстратора в конфиге IDE **игнорируй**. Не выбирай их.

## Эталон и сдача

- Если человек дал эталон через `@path` — **только этот файл**. Не подменяй `_compare_extract`, «похожим» dump из чата или соседним черновиком.
- Нет явного пути — спроси один источник. Не собирай текст из нескольких неоговорённых кусков.

### Перед сдачей

1. `get-material` — хвост `content` целый (см. `03-mcp-tools.md`): нет дубля раздела внизу, нет голых `===` / обрывков fence.
2. Открой share на `app.longread.agency` и пробеги глазами: нет сырых `===`, нет `:::/…` в видимом тексте, нет лишнего CTA/кнопок вне ТЗ и эталона, логотип/обложка/картинки грузятся (URL с `/images/…`, не «починенный» руками путь), конец материала совпадает с задуманным.
3. Share-host — `app.longread.agency`, не loopback.

## СТОП: разрушительные действия только после прямого «да»

Агент **не** сам решает шаги, которые меняют уже существующий контент или структуру курса. Перед таким шагом опиши процедуру: что, зачем, какие id, что пропадёт / переедет / перезапишется. Жди прямого подтверждения пользователя. Без явного «да» / «делай» — не вызывай tool.

**Запрещено без прямого подтверждения пользователя (не «подразумевалось», не «логично»):**

- **Soft-delete в корзину:** `delete-material`, `delete-section` (и массовые soft-delete)
- **Перенос / порядок:** `reorder-*`, `patch-project-sequence`, смена `section_id` / проекта, перекладка уроков между разделами
- **Смешивание:** склейка нескольких материалов в один; раскладка одного скрипта по многим урокам «как решил агент»; слияние чужих правок с новой версией без согласования
- **Полная перезапись тела:** `replace_all` / `save-material-content` поверх уже непустого урока «по скрипту / файлу / ТЗ» без согласования
- **Bake виджета / insert в материал:** только после краткого BRIEF (зачем виджет, что делает, почему не штатные блоки) и прямого «да» (см. `05-html-widget-rules.md`)
- **Обход «тулзов не хватает»:** нет операции в `tools/list` → стоп и вопрос. Не самодельный workaround через delete+create / массовую перезапись / UI-only API

**Обязательно в вопросе пользователю:** цель → конкретные шаги (tools + id) → риск (что потеряется) → варианты. Жди ответа. Не меняй план втихую.

Сбой MCP (401, timeout) — тоже стоп и вопрос. Не «лечи» пересборкой. То же для `curl`-загрузки картинок: `401` от `/api/resources` — токен не тот или ротирован; стоп и спроси актуальный токен у пользователя. Не ищи токен в переменных окружения шелла.

Выбери сценарий ниже.

## Сценарий 1: IDE-агент с MCP (Cursor, Claude Code, VS Code)

Ты можешь писать файлы и вызывать MCP-инструменты.

1. Правила уже в проекте (человек распаковал zip с `/agent/`) или читай raw `.md` с https://app.longread.agency/agent/ — entrypoint `SKILL.md`, затем `README` + `01`–`06`. Word/PPT на диске — опционально отдельный zip вспомогательных правил (`demonstrator-agent-helpers.zip`), не часть ядра.
2. Токен уже в конфиге MCP-клиента (`mcp.json` → `headers.Authorization`). В Личном кабинете он был сгенерирован один раз при первичной настройке — не запрашивай его заново и не ищи в env.
3. Подпишись на remote MCP:

```json
{
  "mcpServers": {
    "demonstrator-mcp": {
      "url": "https://app.longread.agency/mcp/demonstrator/mcp",
      "headers": {
        "Authorization": "Bearer <токен_из_mcp.json>"
      }
    }
  }
}
```

4. Аргументы tools — из `tools/list` после подключения.

### Happy path: материал с нуля

1. `list-projects` — найди `project_id` (или `create-project`).
2. `create-material` — `title` + `project_id` (контент можно пустым).
3. Собери markdown по `01-syntax.md` / `02-methodology.md`.
4. Запиши тело через **Yjs collab-мост**: `apply-material-point-patch` (`mode: "replace_all"`) или `save-material-content`. Title — через `save-material-content` + `title`; theme — `apply-material-theme`. Не raw PATCH `content` в БД (открытый редактор откатит). Tool `update-material-content` удалён.
5. После записи: `verify.ok` **и** `verify.integrity.ok`, плюс хвост `get-material` при сомнении (см. `03`). Не сдавай по одному `verify.ok`.

Медиа с диска — `03-mcp-tools.md`:

- картинка для показа (логотип, обложка): `kind: image`, Shell `curl` multipart → `full_url` с `/images/…webp`, затем `insert-media-block` (insert файл не заливает). Токен для `curl` — тот же Bearer, что в конфиге MCP-клиента в IDE (сервер `demonstrator-mcp` / `user-demonstrator-mcp`); не из переменных окружения шелла. `401` на `/api/resources` — стоп и вопрос пользователю;
- audio/video/**скачиваемый** file: MCP `presign-media-upload` → PUT → `complete-media-upload` (`files/originals/` у file — норма, не «баг»);
- уже HTTPS: `upload-media-from-fs` только с `file_url` и верным `kind`.

Не пиши Python upload. Не ищи helper вне workspace. Не спрашивай способ заливки. Путь/имя файла — ASCII-only; русское имя — после upload. **Не переписывай** сегменты CDN (`originals`/`processed`/`images`) руками. Не ищи токен в переменных окружения шелла.

ИИ-HTML (только IDE + MCP): правь и отлаживай **локальный `.html`**. `bake-widget`, CDN и `insert-ai-widget-block` — только после прямого вопроса и «да» пользователя. Не пеки на каждой правке. В материал ставь **id**, не draft. После bake poll **`archives/`**, пока маркер не совпадёт с локальным HTML. Draft и `get-widget` — не сдача. Без локального файла и без вставки `:::ai_widget` (когда bake разрешён) работа не сдана. Чат-боты без MCP bake не делают — отдают код. Детали — `05-html-widget-rules.md`.

## Сценарий 2: Чат-бот без MCP (Gemini Web, ChatGPT, NotebookLM, WebUI)

Ты **не** качаешь файлы и **не** кладёшь их в RAG сам — у тебя нет такого доступа. Правила в контексте появляются только если **человек** заранее приложил `.md` (Knowledge / Project files / загрузка в чат).

Если правила уже в контексте — работай как референс:

1. Опирайся на цепочку `01-syntax` → `02-methodology` → `04-css` → `05-html-widget` → `06-russian-typography`. `03-mcp-tools` — только обзор (API не вызываешь).
2. Отдай пользователю **готовый markdown** материала. Он вставит в редактор вручную.
3. Если файлов нет во входе — попроси человека скачать zip с https://app.longread.agency/agent/ и приложить.

### Для человека (как дать боту правила)

На https://app.longread.agency/agent/ нажми **«Скачать .zip с правилами»**. Распакуй и загрузи `.md` в Knowledge / Project files / вложение чата — до просьбы писать материал. Не нужно копировать curl.
### Медиа без MCP

- Не выдумывай URL и не обещай загрузку файлов.
- Либо оставь **CDN-заполнитель** из `01-syntax.md` (`https://cdn.longread.agency/demo/...`).
- Либо **спроси у пользователя** готовый HTTPS-URL (или resource id, если он сам загрузил в ЛК).
- ИИ-HTML без MCP: отдай **готовый** фрагмент `:::ai_widget` … `:::/ai_widget` (и HTML, если нужно); bake пользователь сделает в UI или через агента с MCP. Не ограничивайся одной ссылкой на HTML.

## Файлы

| Файл | Содержание |
|---|---|
| `SKILL.md` | Короткий entrypoint-скилл агента |
| `01-syntax.md` | Синтаксис Markdown и блоков `:::тип` |
| `02-methodology.md` | Какой блок выбрать + anti-patterns |
| `03-mcp-tools.md` | Карта MCP-инструментов и подключение |
| `04-css-generation.md` | CSS-темы (`--longread-*`) |
| `05-html-widget-rules.md` | ИИ-HTML (`:::ai_widget`) |
| `06-russian-typography.md` | Русская типографика (—, «ёлочки», …, NBSP) |

Пакеты на `/agent/`: `demonstrator-agent-rules.zip` (ядро `01`–`06`) и необязательный `demonstrator-agent-helpers.zip` (вспомогательные правила пайплайна — отдельно, не продолжение нумерации).

## Даты обновления

В шапке каждого файла:

```yaml
---
id: …
updated: 2026-08-06 15:40 GMT+3
---
```

Сверка:

1. Открой локальный `.md` → поле `updated:`
2. Сравни с тем же файлом на `https://app.longread.agency/agent/<файл>` (или с таблицей на HTML-странице)
3. Если локальный `updated` старше — снова скачай zip с `/agent/` или raw `.md`
4. Не сравнивай по mtime — смотри только `updated:` в frontmatter
5. Часовой пояс в `updated:` — **GMT+3** (Москва)

Работай **только по источнику** (`/agent/`), не «по памяти». У локальной копии нет `updated:` — она вне механизма сверки, эталоном не считать. Не выдумывай «механизмы сверки» и несуществующие файлы/папки: единственная сверка — `updated:` + чтение с `/agent/`.