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

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

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

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

Аккордеон (:::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

=== Заголовок в колонках — нельзя

Так нельзя (в превью торчит сырой ===):

:::columns
1:1
=== Левая
Текст.
=== Правая
Текст.
:::/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-клиента в IDE (mcp.json → headers.Authorization, значение после Bearer ). В Личном кабинете он генерируется один раз при первичной настройке — не запрашивай его заново и не ищи в переменных окружения.

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

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

• В конфиге Cursor / Claude Code в поле url указывай …/mcp, не …/sse.
• Заголовок Authorization: Bearer <токен> обязателен на POST /mcp.
• Без токена — 401.
• Токен привязан к аккаунту: права и квоты — как в UI Демонстратора.
• MCP и публичный сайт — только app.longread.agency. Другие шлюзы Демонстратора не используй.
• Share url отдавай с хостом https://app.longread.agency. Если в ответе localhost / 127.0.0.1 — подставь этот host (token тот же) и проверь ссылку. Loopback человеку не отдавай.

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) — только при закрытой вкладке; при открытом редакторе API вернёт 409;
• title вместе с телом: save-material-content + title; theme — apply-material-theme.
• Переименование без записи тела (например, снять суффикс «(копия)» после duplicate-material): rename-material (material_id + title). Контент не трогается.

5. Проверить verify.ok и verify.integrity.ok / get-material. source: yjs_room или db_fallback. Не сдавай по одному verify.ok.

Запрещено писать 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.

Kind и CDN URL — не путать

В markdown / обложку / логотип ставь только full_url (или url) из ответа upload / list-resources / get-resource-status. Не собирай CDN-путь руками и не «чини» подстроки в URL.

Частая ошибка: логотип/обложку залить как file (получится files/originals/…), потом «исправить» на выдуманный files/processed/…. Пути files/processed/ нет. Для показа — перезалей как image и возьми новый full_url с /images/…webp.

Картинка-image: jpeg / png / webp / gif / svg. SVG принимается как image без растеризации — сервер санитизирует (вырезает скрипты/обработчики) и хранит как …/images/{hash}.svg. Растр (jpeg/png/webp/gif) пережимается в …/images/{hash}.webp. SVG как file — только для скачивания, не для показа.

Как загрузить локальный файл → 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-имя).
• Подменять в URL originals ↔ processed / images / выдуманные сегменты.
• Искать токен в переменных окружения шелла: там может лежать старый/отозванный токен. Токен для curl — тот же Bearer, что стоит в конфиге MCP-клиента в IDE (сервер demonstrator-mcp / user-demonstrator-mcp), или спроси у пользователя.

Дерево решений: как загрузить файл

Файл — картинка для показа? (PNG/JPEG/WebP)
  ├─ Файл локально на твоём диске (C:\...)
  │   → Shell curl multipart (↓ см. «Картинка — curl»).
  │   → НЕ вызывай recipe-upload-and-insert / upload-media-from-fs с file_path.
  │   → НЕ вызывай presign-media-upload (пресайн не для image).
  │
  ├─ Файл уже на публичном HTTPS
  │   → recipe-upload-and-insert с file_url + kind: image
  │
  └─ Файл на сервере MCP (не твоя машина)
      → upload-media-from-fs с file_path

Файл — аудио / видео / file / web_archive?
  ├─ Файл локально на твоём диске
  │   → presign-media-upload → Shell curl PUT → complete-media-upload
  │   → ИЛИ recipe-upload-and-insert если не нужно вручную PUT
  │
  ├─ Файл на публичном HTTPS
  │   → recipe-upload-and-insert с file_url
  │
  └─ Файл на сервере MCP
      → upload-media-from-fs с file_path

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

После 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-клиента в IDE (сервер demonstrator-mcp / user-demonstrator-mcp). Не ищи токен в переменных окружения шелла — там может лежать старый/отозванный токен после ротации. Если в конфиге IDE токена нет — спроси у пользователя. Prod API: https://app.longread.agency.

Если POST /api/resources отвечает 401 — токен не тот или ротирован: стоп и спроси у пользователя актуальный токен. Не перебирай варианты.

curl.exe -sS -X POST "https://app.longread.agency/api/resources" `
  -H "Authorization: Bearer ТОКЕН_ИЗ_КОНФИГА_MCP" `
  -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) — должен быть путь /images/…webp. 2. Вызови insert-media-block (kind: image) или вставь ![подпись](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.

kind: file — только для скачиваемых вложений. Не для логотипа/обложки/блока картинки.

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

MCP upload-media-from-fs: только file_url (https://…). Не C:\…. Для показа картинки — kind: image.

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

Медиатека = 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.
• Не заливать картинку для показа как file и не править CDN-путь вручную.

ИИ-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 канонический; агент заполняет данные (пул портретов, локации, реплики с парой слотов).

Предпочтительный HAPPY PATH: recipe-linear-dialog (создаёт виджет + собирает диалог + валидирует схему, ловит portrait_url и пропущенный id).

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

#### Схема сценария (и частые ошибки)

Эталонный полный пример: docs/templates/linear-dialog/scenario.example.json. Основные поля:

1. Сохрани scenario локально (widgets/<slug>-scenario.json). Начни с 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-мост.

Коридор при открытом редакторе

Серия точечных патчей поверх живого Yjs даёт дубли #/##, обрыв+повтор куска, голые === / :::/…. При открытой вкладке: range_patch и find_replace_once заблокированы (409), replace_all / save-material-content пишут в Yjs, контент приходит в Код как remote change (тост «обновлён с сервера (MCP)»). Не «добивай» пятью find_replace_once после 409.

Future (чат-ассистент по открытому материалу): настоящий agent-WS peer с мелкими Y.Text ops «как юзер» — отдельно от массовой авторской переписки урока; массовые правки всё равно через replace_all + integrity.

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

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

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

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

replace_all / save-material-content при открытой вкладке: контент пишется в Yjs → приходит в Код как remote change (тост «обновлён с сервера (MCP)»). 409 (editor_open_room_not_ready / collab_room_push_failed) возможна только при редкой гонке reconnect — повтори запрос.

Точечный патч при открытой вкладке → 409 point_patch_blocked_editor_open. Используй один replace_all целым телом.

После записи смотри в ответе:

1. verify.ok — байтовое равенство отправленного и прочитанного (не «материал логически целый»). 2. verify.integrity.ok (и/или integrity в ответе collab patch) — структура: нет дублей #/##, нет голых === / orphan :::/…, нет незакрытых блоков, нет повторённого куска. 3. source и хвост get-material глазами при сомнении.

Не сдавай, если verify.ok true, а integrity.ok false. Надёжнее один финальный replace_all / save-material-content целым файлом, чем много мелких find_replace_once.

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

Расхождение с readback: сначала факты, потом диагноз

Не списывай расхождение «отправил — прочитал» на «потерялось при ре-синхронизации Yjs», пока не назвал факты последнего write-вызова.

1. Был ли write-вызов. Если save-material-content / apply-material-point-patch на этот material_id не вызывался, правка в бэкенд не уходила — Yjs тут ни при чём. Ищи, что вообще не записали (или записали не в тот материал). 2. source ответа (обязательно назвать):

• db_fallback → живой Yjs-комнаты не было (вкладка закрыта), текст шёл напрямую в БД. Ре-синхронизации Yjs физически нет — «Yjs затёр правку» неверный вывод. Смотри expected_version и конфликт 409 (version_conflict).
• yjs_room → вкладка была открыта, текст шёл через Yjs. Только здесь возможна гонка reconnect/перезаписи — и то лишь при открытой вкладке.

3. new_version / updated_at. Если версия материала не сдвинулась на момент записи (например, запись «~12:30», а updated_at «~09:29») — запись не дошла до БД. Сверь material_id и был ли ответ ok: true.

Антипаттерн: «потерялось при ре-синхронизации Yjs» при source: db_fallback или при отсутствии write-вызова в истории. Это блокер-регрессия, не «известная проблема».

Темы

apply-material-theme принимает произвольный theme object (merge через MERGE_KEYS). Фон-картинка:

• bgImageResourceId — id image-ресурса (или null, чтобы убрать);
• bgImageMode — pattern (плитка) или frame (фиксированный кадр); по умолчанию pattern.

Не подставляй картинку фона через customOverlayCss (url(...)) — используй поля темы. URL на shared/export резолвит платформа (bg_image_url).

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

Правила CSS тем (customOverlayCss)

CSS для apply-material-theme → customOverlayCss. Это ограничения, не гайд по дизайну.

Фон страницы (shared / export)

В shared колонка текста — body (max-width 720px), а холст страницы — html на весь viewport. Класс .longread-theme-custom вешается и на html, и на body; у колонки background: transparent !important.

Канон shared красит холст так:

html:has(body.shared-view) {
  background-color: var(--longread-bg);
  background-image: var(--longread-bg-image, none);
  background-size: var(--longread-bg-image-size, 960px auto);
}

Специфичность html:has(body.shared-view) выше, чем у .longread-theme-custom. Один только background: …gradient… на классе не перекрывает канон: на html остаётся solid --longread-bg и background-image: none.

Градиент на всё окно (shared / export)

1. theme.bg / --longread-bg — только solid. 2. Визуальный градиент на весь viewport задавай через переменные, которые читает канон холста:

.longread-theme-custom {
  --longread-bg-image:
    radial-gradient(
      ellipse 80% 50% at 70% 0%,
      color-mix(in srgb, var(--longread-accent) 40%, transparent),
      transparent 70%
    ),
    linear-gradient(
      180deg,
      color-mix(in srgb, var(--longread-surface) 85%, var(--longread-accent)) 0%,
      var(--longread-bg) 100%
    );
  /* иначе дефолт 960px auto — плитка, не «на всё окно» */
  --longread-bg-image-size: 100% 100%;
}

3. Без --longread-bg-image холст shared останется плоским, даже если на .longread-theme-custom есть background: …gradient…. 4. Не ставь селекторы html / body. Не клади gradient(...) в --longread-bg. 5. --longread-bg-image — тот же хук, что у картинки из медиатеки (bgImageResourceId). Свой градиент в переменной перебивает page-image — авторская ответственность. С bgImageMode: frame full-bleed градиент через эту var может вести себя иначе; проверяй shared без frame либо не мешай с frame. 6. Перед сдачей — shared-view (hard refresh): у html computed background-image содержит gradient, background-size — на весь холст (100% 100% или эквивалент), а не пятна только на узкой колонке.

Антипаттерн: background: radial-gradient… на .longread-theme-custom без --longread-bg-image / --longread-bg-image-size и без проверки shared.

Штатный фон-картинка (тема)

• bgImageResourceId — id ресурса kind=image в медиатеке (или null / пусто = без картинки).
• bgImageMode:
• pattern — плитка (wallpaper), background-size от холста 960px; на узком экране crop, не scale-down.
• frame — один кадр fixed-слоем #longread-page-bg (не background-attachment: fixed).
• URL резолвит платформа (bg_image_url / theme.bgImageUrl на shared). В customOverlayCss не дублируй картинку через url(...).
• Solid --longread-bg остаётся под картинкой (в т.ч. под прозрачным PNG).
• Свой --longread-bg-image (градиент) в overlay перебивает page image — авторская ответственность.

Цвета — только переменные

Цвета темы материала задаются через --longread-*. В customOverlayCss для любого цвета (color, background, background-color, border-color, outline-color, box-shadow с цветом, text-shadow с цветом, fill, stroke) пиши только var(--longread-…).

Отступы темы (не цвета, но тоже из темы): --longread-content-padding, --longread-block-padding, --longread-block-margin.

Запрещено (цвета)

• Голые #hex, rgb(), rgba(), hsl(), именованные цвета (white, red, …) в свойствах цвета.
• Свои --my-* / хардкод «под палитру клиента» вместо --longread-*.
• Менять значения переменных в :root / html / body из overlay (палитра — полями theme API, не CSS).

/* Верно */
.longread-theme-custom h1 { color: var(--longread-headings); }
.longread-theme-custom .block.btn a {
  background: var(--longread-accent);
  color: var(--longread-surface);
}

/* Запрещено */
.longread-theme-custom h1 { color: #1f3249; }
.longread-theme-custom .card { background: white; }

Исключение: прозрачность через color-mix / oklch от var(--longread-*) — ок. Чистый hex — нет. Иной цвет без переменной — только после прямого «да» пользователя.

Self-lint перед apply-material-theme: в CSS нет # / rgb( / rgba( / hsl( для цветов (кроме редкого согласованного исключения).

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

• Каждое правило — с префикса .longread-theme-custom.
• Запрещены селекторы: body, html, :root.

Не ломай вёрстку

Без прямого «да» пользователя не трогай: display, position, flex, grid, width, height, overflow.

Не стилизуй без «да»: .test-options, radio/checkbox внутри теста, их ::before / ::after / ::marker.

Ограничения:

• .block.important — padding-left ≥ 3em; не ломай ::before (иконка).
• .flip-front / .flip-back — не убирай padding-bottom.

Безопасный коридор по умолчанию: color, background, border*, border-radius, box-shadow, text-shadow, font-*, letter-spacing, padding/margin (осторожно), transform.

Классы блоков (шпаргалка селекторов)

Стилизуй только нужное. Цвета — снова только var(--longread-*).

Вложенные blockquote (три уровня) — не ломай структуру; цвета уровней тоже через --longread-*.

Правила ИИ-HTML (:::ai_widget)

Имя блока — ai_widget (подчёркивание). Не пиши ai-widget, aiwidget или «просто ссылка на HTML».

ИИ-HTML — самодостаточный HTML. Он обязан стоять в материале как блок :::ai_widget … :::/ai_widget. Без этого блока в редакторе виджета для пользователя нет. Сверстать, залить на CDN и прислать URL — не выполнение задачи.

ИИ-HTML всегда часть материала. Он берёт CSS-переменные темы (--longread-*) у родительского лонгрида и живёт в его вёрстке. Без лонгрида нет переменных темы, блочных отступов и рендер-контекста. Не делай из ИИ-HTML отдельную страницу.

Перед create / bake

Не изобретай ИИ-виджет «от себя». Сначала кратко: зачем виджет, что делает пользователь, чем не закрывается штатными блоками (:::test, :::tabs, …). Дождись согласия («да» / BRIEF ок). Потом локальный .html и цикл ниже. Bake/insert — только после отдельного прямого «да».

Обязательный финал (только IDE-агент с MCP)

Это правило — для Cursor / Claude Code / VS Code с MCP. Чат-боты без MCP (Gemini, ChatGPT и т.п.) bake не делают. Они отдают HTML/markdown кодом. См. сценарий 2 в README.md.

С MCP работа в материале готова после вставки :::ai_widget. Bake на CDN — не на каждой итерации.

Цикл отладки (канон)

локальный .html (+ маркер) → открыть в браузере / править на диске → …
→ спросить «запечь на CDN и вставить в материал?» → ждать прямого «да»
→ create-widget (если ещё нет) → save-widget-draft → bake-widget
→ insert-ai-widget-block (fence = id) → poll archives/ до маркера

Пока пользователь не сказал «да» на bake — правь только локальный файл. Не вызывай bake-widget «на всякий случай». Не пеки после каждого фикса.

После правок уже вставленного виджета снова правь локальный .html. Отладь локально. Снова спроси перед следующим save-widget-draft + bake-widget. Не bake каждый раз сам.

После bake/insert: poll archives/ (не draft). Затем get-material. В content должен быть :::ai_widget с id.

Локальная копия на ПК (обязательно при MCP)

Интерактив через MCP в Демонстраторе — ок. На диске рабочей машины всё равно нужна HTML-копия. По ней смотришь и правишь без share/CDN-ссылок.

Обязательно:

1. Сохрани полный HTML в workspace (widgets/ или interactives/), например widgets/quiz-onboarding-<widget_id>.html (или slug без id, пока виджета ещё нет). 2. Отладь локально (открой файл в браузере). Это основной цикл. 3. В ответе укажи локальный путь. 4. Bake/insert — только после прямого вопроса и прямого «да» пользователя.

Запрещено: bake на каждой правке; только MCP/CDN без файла на диске; «открой по ссылке» как единственный способ смотреть интерактив.

Запрещено считать задачу сделанной (IDE + MCP)

• Отдать пользователю только CDN/URL HTML («вот ссылка, вставь сам»).
• Остановить работу на bake-widget без insert-ai-widget-block (когда пользователь уже разрешил bake).
• Поставить в fence draft_url. Сдать по свежему get-widget, пока archives/ без маркера или мигает.
• Оставить в медиатеке виджет/медиа без читаемого имени («Без названия», пусто, uuid).
• Вписать голый URL в абзац / ![…](url) / :::embed вместо :::ai_widget.
• Написать опечатку в типе: :::ai-widget, :::aiwidget.
• Не оставить локальный .html на ПК.
• Запечь на CDN без прямого подтверждения пользователя.

Чат-бот без MCP

Отдай готовый HTML и/или фрагмент markdown с :::ai_widget … :::/ai_widget. Bake, CDN и вопрос «запечь?» к тебе не относятся. Пользователь вставит сам.

Вёрстка и отступы (не липнуть к потолку)

ИИ-HTML живёт внутри материала (iframe / карточка блока). Не делай из него полноэкранный лендинг вплотную к краям.

Обязательно:

• У корневого контейнера (body → первый wrapper) внешний отступ со всех сторон ≥ 16px (лучше 20–24px). Не ставь margin: 0; padding: 0 на html, body без компенсации.
• Первый визуальный блок (картинка, заголовок, карточка) не должен липнуть к верхнему краю виджета.
• Карточка с картинкой сверху: padding у внешней обёртки или margin у карточки от краёв iframe. Full-bleed картинка внутри карточки ок, если сама карточка отстоит от края виджета.

Запрещено:

html, body { margin: 0; padding: 0; } /* и сразу hero/img на всю ширину без обёртки с отступом */
.card { margin: 0; } /* карточка вплотную к верху iframe */
.hero { width: 100%; margin: 0; } /* картинка к потолку виджета */

Нужно (идея):

body {
  margin: 0;
  padding: 20px; /* воздух от краёв блока в лонгриде */
  box-sizing: border-box;
}
.card {
  overflow: hidden;
  border-radius: 12px;
  /* картинка может быть edge-to-edge ВНУТРИ card — снаружи уже есть padding body */
}

Виджет без верхнего воздуха — брак вёрстки, переделай до bake / insert.

Русский текст внутри виджета — по 06-russian-typography.md (—, «ёлочки», …).

Скролл внутри виджета

По умолчанию без скролла. Короткие реплики, обратная связь и описание ситуации должны целиком помещаться в кадр. Не ставь overflow: auto|scroll и фиксированную высоту «наугад», если контент можно уложить или разбить на шаги.

Скролл — только явный замысел. Пример: длинный текст, который пользователь сознательно читает или открывает дополнительно.

Запрещено: весь экран кейса / квиза в одном скролл-боксе «на всякий случай». Скролл ради ленивой вёрстки короткого текста.

Тема и цвета (обязательно)

Внутри :::ai_widget цвета темы приходят как --longread-* на :root (сервер / THEME). Любой цвет в CSS виджета — только var(--longread-…).

button {
  background: var(--longread-accent);
  color: var(--longread-surface);
}

Запрещено

• Голые #hex, rgb() / rgba() / hsl(), white / red и т.п. в свойствах цвета.
• Свои палитры и --brand-* вместо --longread-*.
• «Красивый» цвет мимо темы материала.

Self-lint перед сдачей HTML: в <style> нет цветовых литералов вне var(--longread-*) (кроме согласованного исключения).

Готовых CSS-китов нет — классы свои, цвета только из переменных.

<style id="widget-escape"> — CSS внутри переживает переинжекцию темы; цвета там всё равно через --longread-*, не hex.

Запрещено сервером

• <script src="..."> — внешние скрипты удаляются при bake.
• URL изображений без распознаваемого расширения: .webp, .png, .jpg, .jpeg, .gif, .svg.

Разрешено

• Инлайн <script> без src. Синтаксис JavaScript должен быть валидным.
• Инлайн <style>.

Ограничение размера

500 КБ. Сервер отклоняет HTML больше этого лимита.

Изображения

Только с CDN проекта. URL должен заканчиваться на одно из: .webp, .png, .jpg, .jpeg, .gif, .svg.

MCP-путь (IDE)

1. Сохрани и отладь HTML локально (widgets/<slug>.html). Это основной цикл. Перед bake поставь в HTML уникальный маркер (комментарий / data-build). 2. Спроси: «запечь на CDN и вставить в материал?» Жди прямого «да». Не bake без ответа. 3. create-widget — получи id черновика (material_id / project_id). Всегда передай name — читаемое имя в медиатеке (не uuid, не пусто). 4. save-widget-draft — HTML с диска + theme + assets. 5. bake-widget — дождись статуса ready (ключ archives/{id}/…). 6. insert-ai-widget-block — в fence только CDN entry_url (после ready). Не bare id и не draft_url. 7. Poll archive: get-resource-status / archive-info → entry_url / archives/…. Маркер в archive HTML должен совпасть с маркером локального файла. Пока не совпало — poll. Не сдавай по get-widget / draft. 8. get-material — проверь fence. Пользователю укажи путь к локальному .html.

Шаблон линейного диалога

Для диалогового плеера предпочитай assemble-linear-dialog вместо свободного HTML:

1. Сценарий JSON на диске (widgets/<slug>-scenario.json) — эталон docs/templates/linear-dialog/scenario.example.json. characters[] = пул портретов; на реплике — leftPortraitId, rightPortraitId, speakerSide. 2. create-widget → assemble-linear-dialog (widget_id + scenario). save-widget-draft не нужен. 3. Bake/insert — только после прямого «да». Insert = CDN URL. 4. Фича ai_widget_templates — по умолчанию тестеры; при 403 не обходи без согласования.

Правка уже собранного диалога (тот же tool):

1. get-widget → scenario (+ локальный *-scenario.json). 2. Правишь JSON (реплики / портреты / пары слотов / локации) — полный объект, не патч HTML. 3. Снова assemble-linear-dialog с тем же widget_id. 4. Не вызывай save-widget-draft и не правь shell плеера руками. 5. Повторный bake — только после «да»; в материал снова CDN entry_url.

Имя в медиатеке обязательно. Если создал без имени — сразу rename-resource. «Без названия» / пустой ярлык — брак сдачи.

После bake CDN может кратко отдавать старое поколение на том же URL. Держи poll archive. Не ставь draft в материал. Повторный bake — только после явного «да».

Повторные правки: снова локально → снова вопрос перед bake. Не пеки на каждой итерации.

Не подменяй insert ссылкой на CDN или draft. Не пропускай локальный файл.

Русская типографика

Весь русский текст, который ты пишешь в материалы Демонстратора (markdown уроков, подписи, :::important, тексты внутри ИИ-HTML), подчиняется русской типографике. Смысл не менять — только оформление.

Английский, код, URL, имена блоков :::тип — не трогать этими правилами.

Обязательно

Не ставь дефис - вместо тире между частями предложения. Не ставь прямые кавычки "..." в русском тексте.

Неразрывный пробел в материалах

В markdown материалов редактора:

• Предпочтительно символ Unicode NBSP (U+00A0), не литерал   (в редакторе сущность часто видна как текст).
• Ставь после коротких предлогов/союзов/частиц, чтобы не оставлять их в конце строки: и, а, но, в, во, к, ко, с, со, о, об, от, из, за, на, до, по, при, для, без, или, что, как, то, не, ни, бы, же, ли, уже, ещё, у.
• Между числом и единицей / в и т. д. — тоже NBSP.

Если среда агента плохо вставляет U+00A0 — хотя бы соблюдай тире, кавычки и многоточие; пробелы после коротких слов по возможности.

Где применять

Антипаттерны

• Редактор - это инструмент (дефис вместо —)
• "важный термин" вместо «важный термин»
• подождите... вместо подождите…
•   как видимая строка в теле материала

Чеклист перед сдачей русского текста

• [ ] Тире — «—», не -
• [ ] Кавычки — « » / „ “
• [ ] Многоточие — …
• [ ] Числа с единицами и короткие слова — без «висячих» разрывов (NBSP где уместно)