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

## Блоки

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

**Тип блока (`block_type`)** — как заполняется содержимое:

| Тип        | Что значит                                                                                                                                                                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema`   | обычный блок: значения полей заполняются строго по схеме. Значение по умолчанию                                                                                                                                                                    |
| `markdown` | блок с визуальным редактором текста: в значениях появляется зарезервированный ключ `_markdown` со строкой Markdown, которая при рендере превращается в HTML и приходит в шаблон как `{{ content }}`. Рядом с ним у блока могут быть и обычные поля |

Markdown понимается в диалекте GFM: таблицы, зачёркивание, автоссылки.
Подробнее — [Markdown в блоках](/docs/templates/markdown).

:::note[Есть ещё `html`]
Тип `html` остался от первой версии системы: схемы у таких блоков нет. Новые блоки
им не создают, документация его не описывает.
:::

**Ревизия блока** — неизменяемый снимок содержимого блока: шаблон, стили, скрипт,
схема, changelog, автор и дата. Сохранение блока не перезаписывает предыдущее
состояние, а добавляет ревизию. У блока есть указатель на текущую.

**Версия блока** — пара чисел `мажор.минор` у ревизии. Минорная растёт при любых
совместимых правках; мажорная — только когда из схемы пропало поле (удалено или
переименовано), потому что страницы могут потерять настройки. Первая ревизия — `1.0`.
См. [Ревизии и версии](/docs/blocks/revisions).

**Схема полей** — описание настроек блока: имена полей, типы, подписи, значения
по умолчанию, обязательность, группировка по вкладкам. Именно она превращает кусок
разметки в настраиваемый блок. Полный справочник — [Схема полей](/docs/blocks/schema).

**Значения полей** — заполненная по схеме структура для конкретного вхождения блока
на страницу. В API это `placeholder_values`, в шаблоне — `props`.

**Пресет блока** — сохранённый набор заполненных значений, чтобы не заполнять форму
заново. См. [Пресеты](/docs/blocks/presets).

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

## Шаблоны

**Liquid** — язык шаблонов. Работает дважды: на сервере при публикации и в браузере
при предпросмотре, разными движками. Оба настроены мягко: неизвестная переменная
и неизвестный фильтр дают пустую строку, а не ошибку. См.
[Liquid: основы](/docs/templates/liquid-basics).

**Плейсхолдер** — место в шаблоне, куда подставляется значение поля: `{{ props.title }}`.
Поля доступны только через `props`; `{{ title }}` не выведет ничего.

**Переменные сайта** — значения уровня сайта с синтаксисом `@имя`. Подставляются
в уже отрендеренный HTML, поэтому работают и в блоках, и в макетах; неизвестное имя
заменяется пустой строкой. См. [Переменные сайта](/docs/site/variables).

**Дизайн-токены и тема** — цветовая схема магазина, синхронизированная с витрины.
Блок, использующий токены, перекрашивается вместе с сайтом.

## Страницы и макеты

**Страница** — упорядоченный набор блоков внутри сайта плюс SEO-поля и связь
с опубликованной страницей на витрине.

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

**Папка страниц** — группировка страниц внутри сайта. Вложенность произвольной
глубины; папка принадлежит одному сайту, перенос между сайтами запрещён. Папки
необязательны — большинство страниц лежат в корне. См. [Папки](/docs/pages/folders).

**Макет** — обёртка страницы: шапка, футер, общая структура. Это документ вида
«Макет», собранный из блоков вокруг **лэйаута**; содержимое страницы приходит в его
шаблон переменной `{{ content }}`, которую заполняет витрина.
См. [Что такое макет](/docs/layouts/what-is-layout).

**Лэйаут** — блок с ролью `layout`: единственный блок верхнего уровня документа-макета.
В его шаблоне обязательны `{{ content }}` и `{{ cms_assets_head }}`.

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

## Данные

**Источник данных** — именованный поставщик живых данных с витрины: товары рубрики,
содержимое корзины и подобное. У источника есть стабильный идентификатор, схема
параметров (`params_schema`) и ссылка на тип результата.

**Тип результата** — описание формы данных, которые возвращает источник, плюс
**заглушка** (`stub`) — готовый пример этой формы. Несколько источников могут
возвращать один тип.

**Слот привязки (binding slot)** — объявленное в схеме блока место под данные:
какой тип результата ожидается, какие источники допустимы и какой из них
подставляется по умолчанию. Наличие слотов делает блок SSR-блоком.

**Привязка (binding)** — назначение источника слоту у конкретного блока на странице,
вместе с параметрами запроса: `{ "<слот>": { "source": "<id>", "params": { … } } }`.

**Слот композиции (slot)** — объявленная в схеме блока область под **другие блоки**:
`{{ slots.<имя> }}` в шаблоне выводит собранный HTML вложенных блоков. Блок с непустым
`slots` называется **контейнером** — две колонки, табы, аккордеон. Не путать со слотом
привязки: тот даёт данные (`{{ data.<имя> }}`), этот — вложенную вёрстку. Подробности —
[Схема полей](/docs/blocks/schema#блоки-контейнеры-slots) и
[Сборка страницы](/docs/pages/composition#блоки-в-слотах-контейнера).

:::caution[В PageCraft источники отдают заглушку]
В предпросмотре и при сборке страницы в PageCraft источник возвращает `stub` своего
типа результата — реального каталога здесь нет. Реальные данные подставляются уже
на витрине. Поэтому `params` — это декларация о поведении на боевом сайте, а не
проверка наличия данных: подобрать `limit`, сортировку и фильтр надо самому,
и значения по умолчанию у слота хватит только чтобы блок не выглядел пустым.
:::

Подробности — [Биндинги и слоты](/docs/data/bindings) и
[Реестр источников](/docs/data/providers).

## Библиотека и совместная работа

**Область видимости (`scope`)** — `private` (блок или макет виден только владельцу)
или `global` (общая библиотека, видна всем). Новый блок создаётся приватным, форк
чужого — тоже.

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

**Форк** — копия чужого блока или макета в свою коллекцию для доработки. Ответ
на ситуацию «в общем блоке чего-то не хватает»: вместо правки общего блока —
своя копия. У исходника хранится счётчик форков, у копии — ссылка на источник.

**Устаревший (deprecated)** — пометка «пользоваться не рекомендуется» у блока или
источника данных. Из списков и поиска он пропадает, существующие страницы продолжают
работать. См. [Устаревание и апгрейды](/docs/blocks/deprecation).

**Тег** — метка для фильтрации в библиотеке. Теги блоков и теги макетов — раздельные
справочники, общие для всех пользователей.

**Избранное** — личная пометка блока или макета, независимая от владения и области
видимости.

**Соредактор** — пользователь, которому владелец открыл доступ к своему сайту.
Может всё, кроме удаления сайта и управления доступом. Уровней доступа нет:
соредактор либо есть, либо нет. См. [Совместный доступ](/docs/site/sharing).

**Приглашение** — предложение стать соредактором сайта, отправленное владельцем
по GitHub-логину. Живёт внутри системы, ждёт ответа приглашённого; принятое даёт
доступ, отклонённое закрывается.

**Присвоение («сделать копию себе»)** — операция владельца сайта: чужой блок,
стоящий на его страницах, копируется в его библиотеку, и все экземпляры на его
сайтах переключаются на копию. Отличается от форка тем, что применяется
к приватному блоку соредактора и переводит уже стоящие экземпляры. См.
[Блоки при совместном доступе](/docs/site/shared-blocks#присвоение-сделать-копию-себе).

## Публикация

**Провайдер публикации** — реализация выкладки собранной страницы во внешнюю систему.
Основной — 4CMS; есть также FTP, но он не развивается.

**SSR (серверный рендеринг)** — сборка HTML на стороне PageCraft: шаблоны блоков
рендерятся с их значениями и данными, результат оборачивается в макет.
См. [SSR-блоки](/docs/data/ssr-blocks).

**Живой URL** — адрес опубликованной страницы на витрине.

## Внешние системы и агенты

**4CMS** — eком-платформа 4partners, целевая система для публикации.

**API-ключ** — способ аутентификации внешнего клиента в публичном API `/api/v1/*`.
Строка вида `pb_` + 64 шестнадцатеричных символа, передаётся заголовком
`Authorization: Bearer pb_…`. Создаётся в интерфейсе, хранится только в виде хеша —
показать повторно нельзя. Действует от имени своего владельца и видит те же
данные, что и он, включая расшаренные ему сайты. См. [API-ключи](/docs/api/api-keys).

**Скилл (agent skill)** — пакет инструкций для ИИ-агента, который PageCraft раздаёт
по `/.well-known/agent-skills/`. Агент читает скилл и узнаёт правила системы, вместо
того чтобы их угадывать. См. [Скиллы](/docs/api/skills).

**Харнесс** — среда, в которой работает агент: Claude Code, Cursor и подобные.

## Перегруженные термины

**«Слот»** значит разное:

| Где встречается                  | Что значит                                                     |
| -------------------------------- | -------------------------------------------------------------- |
| `bindingSlots` в схеме блока     | место под данные из источника                                  |
| `{{ content }}` в шаблоне макета | единственное место, куда вставляется HTML всех блоков страницы |

Слоты вложенных блоков (блок внутри блока) в PageCraft **не реализованы**.

**«Публикация»** значит два разных действия:

- публикация **страницы** — выкладка на витрину через провайдера;
- публикация **блока** — заявка на попадание в общую библиотеку.

В документации первое называется «публикация страницы», второе — «заявка в библиотеку».

---

**Источники:** `backend/src/Entity/Block.php`, `backend/src/Entity/BlockRevision.php`,
`backend/src/Entity/PageBlock.php`, `backend/src/Entity/PageFolder.php`,
`backend/src/Entity/Site.php`, `backend/src/Entity/DataSource.php`,
`backend/src/Entity/DataResultType.php`, `backend/public/block-schema.json`,
`backend/src/Service/BlockVersionService.php`,
`backend/src/Service/Block/BlockPlaceholderSchemaBuilder.php`,
`backend/src/Service/Block/ForkBlockService.php`,
`backend/src/Service/ApiKey/CreateApiKeyService.php`,
`backend/src/Service/PageFolder/UpdatePageFolderService.php`,
`backend/src/Publishing/BlockRenderer.php`, `backend/src/Publishing/LayoutRenderer.php`.