Методика: какой блок выбрать

Используйте эту таблицу для выбора блока под задачу.

Быстрый выбор

Когда что использовать

Аккордеон (:::acc)

Используйте для однородных пунктов: заголовок открывает пояснение по клику.

Подходит для:

• Глоссария: термин — заголовок, определение — тело.
• FAQ: вопрос — заголовок, ответ — тело.
• Подсказок к шагам, когда порядок не важен.

Не путайте с :::steps. Аккордеон не нумерует пункты.

Вкладки (:::tab)

Используйте для равнозначных панелей с короткими ярлыками.

Подходит для:

• Вариантов: теория / практика, условие / решение.
• «До и после» без морали «плохо/хорошо».

Не используйте вкладки для контраста «плохо/хорошо». Для этого — :::compare или :::checklist duo.

Карточки (:::flip)

Используйте для самопроверки: вспомнил → перевернул → проверил.

Лицо — тезис. Оборот — развёрнутый ответ.

Глоссарий из 10+ терминов лучше делать аккордеоном.

Тест (:::test)

• [test] / [verification] — один правильный ответ. Обязателен минимум один + и один -.
• [think] / [narrative] — опрос. Нет правильного ответа. Нейтральный ok:.

Не ставьте [test] с искусственным + там, где подходит [think].

Шаги (:::steps)

Используйте для процесса с порядком: инструкция, алгоритм, «сначала → потом».

• :::steps — со стрелками между шагами.
• :::steps grid — сетка без стрелок.

Не используйте :::steps для норм без последовательности. Для этого — :::important rule или чеклист.

Чеклист (:::checklist)

Используйте для критериев, требований, списка «что проверить» или списка возможностей.

• + в начале строки — зелёная галочка (плюс / фича / «как надо»).
• - в начале строки — красный крест (минус / ошибка).
• Список преимуществ или возможностей продукта — все пункты с +. Не используйте - как обычный маркер списка.
• Одна колонка: :::checklist.
• Две колонки: :::checklist duo. Тональность: === + … / === - ….

Отличие от :::compare: чеклист — набор пунктов с ✓/✗. Сравнение — ровно 2 текстовые колонки.

Тест (:::test)

• Открытие только :::test. Режим [test] или [think] — отдельной строкой внутри блока.
• Не пишите :::test[test] и не клеите режим к имени блока.

Сравнение (:::compare)

Используйте для контраста подходов. Ровно 2 колонки с заголовками.

Важное (:::important)

• Краткая оговорка: !!! текст.
• Блок: :::important idea / problem / solution / info / rule.
• Иконку система рисует сама. Не вставляйте эмодзи и символы иконок в текст.
• Только короткая врезка. Не оборачивайте весь урок или статью в :::important.

Хотспот (:::hotspot)

Используйте для схемы или фото с кликабельными точками.

Требуется реальная картинка ![…](url). Без маркеров блок ведёт себя как обычное изображение.

Колонки (:::columns)

Используйте для параллельной вёрстки: текст + врезка, две равные колонки.

Пишите :::columns … :::/columns.

Соотношение: пресет (2:1, 1:1:1) или проценты через дефис (70-30). Не 50/50. Разделитель — пустой ===. Заголовки внутри — ###.

Не заменяйте колонками :::compare или :::checklist duo. В колонках нет семантики «плохо/хорошо».

Не путать

Anti-patterns: wrong → right

Шаги как аккордеон — нельзя

Так нельзя:

:::acc
=== Шаг 1
Откройте файл.
=== Шаг 2
Сохраните файл.
:::/acc

Так надо:

:::steps
=== Откройте файл
Дважды щёлкните по ярлыку.
=== Сохраните файл
Ctrl+S или меню «Файл».
:::/steps

Норма как steps — нельзя

Так нельзя:

:::steps
=== Правило 1
Не храните пароли в чате.
:::/steps

Так надо:

:::important rule
Не храните пароли в чате.
:::/important

Плохо/хорошо вкладками — нельзя

Так нельзя:

:::tab
=== Плохо
Длинный абзац без структуры.
=== Хорошо
Список и заголовки.
:::/tab

Так надо:

:::compare
=== Плохо
Длинный абзац без структуры.
=== Хорошо
Список и заголовки.
:::/compare

Колонки со слэшем — нельзя

Так нельзя:

:::columns
50/50
===
Левая.
===
Правая.
:::/columns

Так надо:

:::columns
50-50
===
Левая.
===
Правая.
:::/columns

Опрос с фейковым «верным» — нельзя

Так нельзя:

:::test
[test]
===
Как вам курс?
+ Отлично
- Нормально
ye: Верно!
no: Неверно.
:::/test

Так надо:

:::test
[think]
===
Как вам курс?
- Отлично
- Нормально
- Сложно
ok: Спасибо за ответ!
:::/test

Режим теста на строке открытия — нельзя

Так нельзя:

:::test[test]
===
Вопрос?
+ Да
- Нет
:::/test

Так надо:

:::test
[test]
===
Вопрос?
+ Да
- Нет
:::/test

Фичи чеклистом с минусами — нельзя

Так нельзя (все пункты красные ✗):

:::checklist
- Поддерживает мультимодальные запросы
- Использует Query Fan-Out
:::/checklist

Так надо (зелёные ✓):

:::checklist
+ Поддерживает мультимодальные запросы
+ Использует Query Fan-Out
:::/checklist

Весь урок в important — нельзя

Так нельзя: открыть :::important idea в начале файла и закрыть :::/important в конце, а внутри — #, ##, steps, compare.

Так надо: обычный Markdown-каркас; :::important только на короткий акцент (несколько предложений).

Блок в одну строку — нельзя

Так нельзя:

:::steps === Шаг 1 Текст. === Шаг 2 Текст. :::/steps

Так надо:

:::steps
=== Шаг 1
Текст.
=== Шаг 2
Текст.
:::/steps

То же для :::compare и :::checklist duo.

Размещение и объём

• Перед интерактивом добавьте короткую подводку — связующий текст.
• Между блоками — связный текст. Не ставьте несколько интерактивов подряд без пояснений.
• Внутри :::acc, :::tab, :::flip не ставьте заголовки ###. Структура — только через === и текст.
• В подводках не используйте штампы: «далее», «ниже», «удобно».

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

MCP-инструменты Демонстратора

Карта инструментов (имя → зачем). Полные схемы параметров не дублируются здесь.

Параметры инструментов

После подключения MCP клиент вызывает tools/list. Сервер отдаёт канонические inputSchema (required, типы, enums, лимиты).

• Бери аргументы только из tools/list / подсказок клиента — не из этой страницы и не из догадок.
• Этот файл — ориентир «какой tool выбрать». Контракт вызова — у MCP.
• Без токена схемы недоступны (401).
• Нет нужного tool в tools/list → стоп, спроси пользователя. Не обходи дырку delete+create / массовой перезаписью.
• Soft-delete в корзину, перенос, смешивание материалов, replace_all поверх живого контента — только после описания процедуры и прямого подтверждения пользователя (см. README.md, блок СТОП).
• Вне MCP (не ищи в tools/list): permanent delete-project / delete-resource, снятие share-ссылок, invite/ACL пространства, suggestions propose/apply (WIP), restore из entity-snapshot / backup ZIP.

Подключение к MCP

Подпишись на remote MCP-шлюз на сервере Демонстратора. Клонировать репозиторий и запускать node локально не нужно.

Токен — в Личном кабинете Демонстратора (раздел MCP / API-токен).

{
  "mcpServers": {
    "demonstrator-mcp": {
      "url": "https://app.longread.agency/mcp/demonstrator/mcp",
      "headers": {
        "Authorization": "Bearer ВСТАВЬ_ТОКЕН_ИЗ_ЛК"
      }
    }
  }
}

Эндпоинты шлюза:

• В конфиге Cursor / Claude Code в поле url указывай …/mcp, не …/sse.
• Заголовок Authorization: Bearer <токен> обязателен на POST /mcp.
• Без токена — 401.
• Токен привязан к аккаунту: права и квоты — как в UI Демонстратора.
• Публичный MCP — только Prod (app.longread.agency). Не используй dev.app.longread.agency в публичных правилах /agent/.

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-мост, не прямым PATCH в БД:

• полное тело: apply-material-point-patch с mode: "replace_all" + content

или save-material-content (тот же POST /api/collab/materials/:id/patch);

• точечно: find_replace_once / range_patch;
• title вместе с телом: save-material-content + title; theme — apply-material-theme.

5. Проверить verify.ok / get-material. В ответе смотри source: yjs_room (комната открыта) или db_fallback.

Запрещено писать markdown через raw PATCH /api/materials с полем content (tool update-material-content удалён): открытый редактор перезапишет старым Yjs-документом.

Полный маршрут и сценарий без MCP — в README.md.

Каталог (обзор)

Ниже — имя и краткое действие. Схемы полей — в tools/list.

Проекты и пространства

Создание пространства, приглашения, смена состава/ролей, permanent delete-project — только через UI, не через MCP.

Структура

Порядок: три разных оси (не путать)

Можно чередовать: раздел → прототип → раздел → прототип. Это штатный project_sequence, не запрет продукта.

Стартовый/пустой sequence (миграция + UI-fallback) часто выглядит как «сначала все разделы, потом корневые» — дефолт, не закон. Не сочиняй «разделы всегда сверху» / «без разделов только плоский список».

Дерево слева sequence почти не отражает: смешанный список — в сетке карточек.

patch-project-sequence: items: [{ "item_type": "section"|"material", "item_id": N }, …] сверху вниз. В items только корневые материалы (без section_id). Перед вызовом — подтверждение пользователя (см. СТОП в README.md).

reorder-sections / reorder-materials не умеют смешивать типы — для этого только sequence.

Медиа

Permanent удаление ресурса — только UI (delete-resource в MCP нет).

Upload и insert: осмысленный filename / display_name. «Без названия» в медиатеке — брак; сразу rename-resource.

Как загрузить локальный файл → Object Storage → CDN

MCP не читает файлы с диска агента (C:\…). Не вызывай upload-media-from-fs с Windows-path. insert-media-block файл не загружает. Сначала upload, потом insert.

Запрещено

• Писать свой upload (Python, Node).
• Искать upload-local-media.ps1 вне текущего workspace.
• Спрашивать пользователя «как залить».
• Класть файлы на VPS «под from-fs».
• Передавать file_base64 в MCP.
• Заливать файл с кириллицей в пути или имени (сначала скопируй в ASCII-имя).

#### Выбор пути

После upload вызови MCP insert-media-block или вставь ![…](full_url) в content. Processing-медиа: get-resource-status до ready / failed. На каждом upload передай material_id или project_id.

ASCII-only на диске. Путь и имя файла для upload — только латиница/цифры (C:\work\media\fig-01.png). Кириллица в папках или имени файла ломает curl у агентов. Русское имя в медиатеке — после upload: rename-resource или display_name / name в insert-media-block.

#### Картинка — curl

Токен — из ЛК (тот же Bearer, что у MCP). Prod API: https://app.longread.agency.

curl.exe -sS -X POST "https://app.longread.agency/api/resources" `
  -H "Authorization: Bearer TOKEN_FROM_LK" `
  -H "Accept: application/json" `
  -F "file=@C:\work\media\fig-01.png;filename=fig-01.png;type=image/png" `
  -F "material_id=123" `
  -F "original_name=fig-01.png"

1. Из JSON возьми id и full_url (или url). 2. Вызови insert-media-block или вставь ![подпись](full_url). 3. Задай читаемое имя. Иначе вызови rename-resource.

Для image нет presign-media-upload. Нет MCP-tool, который читает локальный png. Если upload-local-media.ps1 уже лежит в текущем workspace — можно вызвать его вместо curl. Иначе делай curl. Не сканируй диск.

#### audio / video / file / web_archive

1. MCP presign-media-upload (kind, filename, size, material_id или project_id). 2. Shell: curl.exe -sS -X PUT "<upload_url>" -H "Content-Type: …" --data-binary "@C:\path\to\file". 3. MCP complete-media-upload (тот же material_id / project_id). 4. MCP insert-media-block.

#### Уже публичный HTTPS

MCP upload-media-from-fs: только file_url (https://…). Не C:\….

Медиатека проекта

Медиатека = resource_links на project_id / material_id.

• Upload без material_id/project_id — MCP отклоняет вызов.
• При записи content через collab backend линкует твои ресурсы из markdown в материал/проект.
• Чужой CDN URL / demo-заполнитель без upload в медиатеку не попадает.

Что не делать

• Не писать свои upload-скрипты сверх curl / MCP выше.
• Не искать helper вне текущего workspace.
• Не считать insert-media-block заменой upload.
• Не вызывать несуществующие base64-tools (upload-media-resource / upload-resource).
• Не класть медиа на диск VPS «под from-fs».
• Не подставлять Windows-path в upload-media-from-fs.
• Не загружать без material_id / project_id.

ИИ-HTML (:::ai_widget)

Имя в медиатеке

Ресурс без нормального original_name в UI выглядит как «Без названия» / бессмысленный дефолт. Это брак.

• create-widget: всегда передай name (коротко по смыслу: «Квиз онбординг», не uuid).
• Upload: осмысленный filename; если в библиотеке плохое имя — сразу rename-resource.
• insert-media-block: можно display_name / name — MCP переименует ресурс.

Не готово: виджет/файл в медиатеке без читаемого имени.

Путь создания ИИ-HTML (только IDE + MCP)

локальный .html + маркер + отладка → вопрос «bake на CDN?» → «да» →
create-widget → save-widget-draft → bake-widget (ready) →
insert-ai-widget-block (fence = id, не draft) →
poll archives/ до совпадения маркера → get-material

1. Запиши и отладь HTML в workspace (widgets/<slug>.html). Добавь уникальный маркер. 2. Спроси пользователя про bake/insert. Жди прямого «да». Не вызывай bake-widget на каждой правке. 3. create-widget → save-widget-draft (HTML с диска) → bake-widget. 4. insert-ai-widget-block — в блок только CDN entry_url после bake (ready). Draft URL и bare id в материал запрещены. 5. Poll: get-resource-status / archive-info → HTML с archives/ (entry_url, учти ?v=). Маркер должен совпасть с локальным файлом. get-widget и draft — не критерий сдачи. 6. get-material — fence на месте. Путь к локальному файлу — пользователю.

В create-widget всегда передай name (имя в медиатеке). Без имени — не готово; при ошибке — rename-resource.

Шаблон: линейный диалог (assemble-linear-dialog)

Когда нужен диалоговый плеер, не пиши HTML с нуля — собери сценарий JSON и вызови assemble-linear-dialog. Shell канонический; агент заполняет данные (пул портретов, локации, реплики с парой слотов).

scenario.json на диске → create-widget → assemble-linear-dialog →
вопрос «bake на CDN?» → «да» → bake-widget → insert-ai-widget-block (CDN URL)

1. Сохрани scenario локально (widgets/<slug>-scenario.json). Поля: characters[] (пул портретов), steps[] с leftPortraitId / rightPortraitId / speakerSide, опционально locations[]. Эталон: docs/templates/linear-dialog/scenario.example.json. 2. На сцене всегда два слота картинок; characters[] — N вариаций (ракурсы/эмоции). На каждой реплике задай пару портретов и кто говорит (speakerSide: left|right). 3. Демо-медиа CDN: avatar-bot.webp, avatar-user.webp, slider-1.webp на cdn.longread.agency/demo/. 4. create-widget с name → assemble-linear-dialog (widget_id + scenario). Не нужен save-widget-draft. 5. Bake/insert — только после прямого «да» (как у свободного HTML). Insert пишет CDN entry_url, не id. 6. При 403 ai_widget_templates_forbidden — шаблоны только у тестеров; не обходи через свободный HTML без согласования.

Правка существующего линейного диалога

Тот же assemble-linear-dialog — создаёт и обновляет. Отдельного «refine» в MCP нет (Studio AI через MCP не вызываем).

get-widget → взять scenario → править JSON (локально или в ответе) →
assemble-linear-dialog (полный scenario) → при необходимости снова bake после «да»

1. get-widget (widget_id) → поля archetype: linear_dialog и scenario. 2. Если scenario пуст — вытащи из HTML #vn-scenario или восстанови из локального widgets/<slug>-scenario.json. 3. Внеси правки в полный scenario (реплики, портреты пула, leftPortraitId/rightPortraitId/speakerSide, локации, порядок steps / next). Не отправляй diff / SEARCH-REPLACE по shell. 4. Обнови локальный widgets/<slug>-scenario.json. 5. assemble-linear-dialog с тем же widget_id и полным scenario — пересоберёт draft. 6. Запрещено для диалога: save-widget-draft с ручным HTML плеера; правка CSS/JS shell; вызов /api/ai/widgets/*/refine*. 7. Повторный bake-widget / insert — только после прямого «да» пользователя (как при создании).

Чат-боты без MCP этот путь не используют. Они отдают HTML/markdown кодом и bake не делают.

Не готово (IDE): только bare id в fence; bake без «да»; bake без локального файла; bake без insert; сдача по draft при отстающем archive; fence с draft_url; ресурс в медиатеке без читаемого имени.

Серверный контракт — 05-html-widget-rules.md.

Корзина

Share-ссылки

Создание и обновление — да. Снятие / unpublish ссылок через MCP нельзя (только UI).

Ответ create/get содержит url — полный канонический URL.

Типы ссылок: preview (просмотр), preview_comments (с комментариями).

Comment/share ≠ editor body. republish-comments-snapshot, share-links с preview_comments и get-material-preview-with-comments — про публичный review/HTML. Текст урока в редакторе правят только save-material-content / apply-material-point-patch. В ответах материала нет внутренних publish-кэшей — только content.

Чтение и экспорт

Предложения правок

Сейчас вне MCP (недоделано; вернём позже). Пиши тело сразу через collab (save-material-content / apply-material-point-patch).

Запись контента

Источник правды при открытом редакторе — Yjs collab, не строка в БД. Все правки тела материала — через collab-мост.

Режимы apply-material-point-patch

Все write-операции используют expected_version (tool подставит сам, если не передан).

Ответ содержит source:

• yjs_room — материал был открыт в редакторе; текст ушёл в Yjs, потом в БД;
• db_fallback — вкладка редактора не была открыта (нет живых WS).

Если материал открыт в редакторе, а запись в Yjs невозможна, API вернёт 409 (editor_open_room_not_ready / collab_room_push_failed). Не считай это успехом. Закрой вкладку или повтори, когда комната готова. Тихого db_fallback при открытом редакторе больше нет — иначе открытая вкладка затрёт правки агента.

После записи проверяйте verify.ok и source. Не пишите тело через raw PATCH «в базу». Вторичных «workspace»/publish body-полей в ответах нет — править нечего, кроме content через collab.

Темы

Правила CSS для customOverlayCss — см. раздел «Правила CSS-генерации».

Правила CSS-генерации тем

Вы пишете CSS для apply-material-theme с параметром customOverlayCss. Этот CSS изменяет внешний вид материала. Соблюдайте правила ниже.

CSS-переменные

Материалу гарантированно доступны переменные в :root. Используйте их для цветов. Не хардкодьте цвета.

Селекторный контекст

Каждое правило начинайте с .longread-theme-custom.

Запрещены селекторы: body, html, :root.

/* Верно */
.longread-theme-custom h1 { color: var(--longread-accent); }

/* Запрещено */
body { background: #fff; }

Опасные CSS-свойства

Эти свойства могут сломать вёрстку блоков Демонстратора:

display, position, flex, grid, width, height, overflow.

Если задача требует одного из этих свойств — сначала предупреди пользователя: объясни, что свойство может поломать вёрстку. Меняй только после прямого подтверждения пользователя.

Безопасные CSS-свойства

По умолчанию используй эти свойства — они не ломают вёрстку:

border, border-radius, border-color, background, font-family, font-size, font-weight, color, text-shadow, box-shadow, padding, margin, transform, letter-spacing.

Псевдоэлементы ::before и ::after разрешены везде, кроме селекторов ниже.

Селекторы с высоким риском

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

• .test-options и input[type=radio] / input[type=checkbox]
• ::before, ::after, ::marker на элементах .test-options

Селекторы с ограничениями

.block.important

• Сохраняйте padding-left >= 3em. Это место под иконку.
• Запрещено менять ::before (position, left, top, transform, display, width, height).

.flip-front и .flip-back

• Сохраняйте padding-bottom.

blockquote

Три уровня цитат. Используйте эти селекторы.

Уровень 1:

.longread-theme-custom > blockquote:not(:has(blockquote)),
.longread-theme-custom :not(blockquote) > blockquote:not(:has(blockquote)) {
  /* стили уровня 1 */
}

Контейнер цитаты (сброс):

.longread-theme-custom blockquote:has(> blockquote) {
  border: none;
  background: none;
  box-shadow: none;
  padding-left: 0;
}

Уровень 2:

.longread-theme-custom blockquote:not(:has(> blockquote > blockquote)) > blockquote:not(:has(blockquote)) {
  /* только color, font-style, font-size */
  /* без border, без ::before */
}

Уровень 3:

.longread-theme-custom blockquote blockquote blockquote {
  /* border, border-radius, background, padding */
  /* ::before { content: none } */
}