Auto-build: copilot (powershell) from 113dc9e

.github/skills/mxl-compile/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: mxl-compile
+description: Компиляция табличного документа (MXL) из JSON-определения. Используй когда нужно создать макет печатной формы
+argument-hint: <JsonPath> <OutputPath>
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+---
+
+# /mxl-compile — Компилятор макета из DSL
+
+Принимает компактное JSON-определение макета и генерирует корректный Template.xml для табличного документа 1С. Claude описывает *что* нужно (области, параметры, стили), скрипт обеспечивает *корректность* XML (палитры, индексы, объединения, namespace).
+
+## Использование
+
+```
+/mxl-compile <JsonPath> <OutputPath>
+```
+
+## Параметры
+
+| Параметр   | Обязательный | Описание                           |
+|------------|:------------:|------------------------------------|
+| JsonPath   | да           | Путь к JSON-определению макета     |
+| OutputPath | да           | Путь для генерации Template.xml    |
+
+## Команда
+
+```powershell
+powershell.exe -NoProfile -File ".github/skills/mxl-compile/scripts/mxl-compile.ps1" -JsonPath "<путь>.json" -OutputPath "<путь>/Template.xml"
+```
+
+## Рабочий процесс
+
+1. Написать JSON-определение (Write tool) → файл `.json`
+2. Вызвать `/mxl-compile` для генерации Template.xml
+3. Вызвать `/mxl-validate` для проверки корректности
+4. Вызвать `/mxl-info` для верификации структуры
+
+**Если макет создаётся по изображению** (скриншот, скан печатной формы) — сначала вызвать `/img-grid` для наложения сетки, по ней определить границы колонок и пропорции, затем использовать `"Nx"` ширины + `"page"` для автоматического расчёта размеров.
+
+## Что читать под задачу
+
+Ниже — всё, что нужно для типового макета. Остальное лежит по файлу на задачу, читать нужно
+только свой:
+
+| Задача | Ключи | Файл |
+|---|---|---|
+| Свойство стиля вне частых: отступ, защита, узор, маска, поведение при выводе | — | `reference/style-properties.md` |
+| Область, не описываемая диапазоном строк; свои ширины колонок у части документа | `namedAreas`, `columnSets`, `columnSet` | `reference/layout.md` |
+| Колонтитулы, ориентация, поля, масштаб | `header`, `footer`, `printSettings` | `reference/print.md` |
+| Картинка, фигура или надпись поверх сетки; картинка в ячейке | `pictures`, `drawings`, `pictureParameter` | `reference/drawings.md` |
+| Ячейки для ввода данных пользователем | `valueType`, `controlType`, `value` | `reference/input-cells.md` |
+| Сворачиваемые группы строк или колонок | `rowGroups`, `columnGroups` | `reference/groups.md` |
+| Всплывающая подсказка у ячейки | `note` | `reference/notes.md` |
+
+## Пример
+
+```json
+{
+  "columns": 5,
+  "columnWidths": { "1": 5, "2": 40, "3-5": 12 },
+  "fonts": { "жирный": { "face": "Arial", "size": 10, "bold": true } },
+  "styles": {
+    "шапка":  { "font": "жирный", "horizontalAlignment": "Center", "textPlacement": "Wrap", "border": "Solid" },
+    "клетка": { "border": "Solid" },
+    "число":  { "border": "Solid", "horizontalAlignment": "Right", "format": "ЧЦ=15; ЧДЦ=2" },
+    "итог":   { "font": "жирный", "horizontalAlignment": "Right", "topBorder": "Solid" }
+  },
+  "areas": [
+    { "name": "Заголовок", "rows": [
+      { "height": 20, "cells": [{ "col": 1, "span": 5, "style": "шапка", "param": "ЗаголовокОтчёта" }] },
+      {}
+    ]},
+    { "name": "ШапкаТаблицы", "rows": [
+      { "rowStyle": "шапка", "cells": ["№", "Номенклатура", "Количество", "Цена", "Сумма"] }
+    ]},
+    { "name": "Строка", "rows": [
+      { "rowStyle": "клетка", "cells": [
+        { "col": 1, "param": "НомерСтроки" },
+        { "col": 2, "param": "Товар", "detail": "Номенклатура" },
+        { "col": 3, "style": "число", "param": "Количество" },
+        { "col": 4, "style": "число", "param": "Цена" },
+        { "col": 5, "style": "число", "param": "Сумма" }
+      ]}
+    ]},
+    { "name": "Итого", "rows": [
+      { "rowStyle": "итог", "cells": [null, null, null, "Итого:", "{Всего}"] }
+    ]}
+  ]
+}
+```
+
+Шапка таблицы и итог записаны позиционно — позиция берётся из порядка, `col` не нужен;
+строка таблицы записана ячейками с `col`, потому что у них разные стили и расшифровка.
+
+## Структура DSL
+
+```
+{ columns, page, defaultWidth, columnWidths, columnStyles, textLanguages,
+  fonts:  { имя: { face, size, bold, italic, underline, strikeout } | { ref } },
+  styles: { имя: { font, horizontalAlignment, verticalAlignment, textPlacement,
+                   border, leftBorder, topBorder, rightBorder, bottomBorder,
+                   borderColor, backColor, textColor, format } },
+  areas: [{ name, columnSet, rows: [
+    { height, hidden, rowStyle, empty, cells: [
+      { col, span, rowspan, style, param, detail, text, template, note,
+        valueType, controlType, value, pictureParameter } ] } ] }],
+  namedAreas, columnSets, rowGroups, columnGroups, header, footer, printSettings,
+  pictures, drawings
+}
+```
+
+Верхний уровень: `columns` обязателен, остальное по необходимости.
+
+| Ключ | Описание |
+|---|---|
+| `columns` | Количество колонок раскладки по умолчанию |
+| `page` | Формат страницы: `"A4-landscape"` (780), `"A4-portrait"` (540) или число. Сам вычисляет `defaultWidth` из суммы пропорций `"Nx"` |
+| `defaultWidth` | Ширина колонок по умолчанию (10) |
+| `columnWidths` | Ширины: ключи 1-based (`"1"`, `"3-14"`, `"5,7,9"`), значение — число или `"2x"` (доля от `defaultWidth`) |
+| `columnStyles` | Стиль на колонку целиком: те же ключи диапазонов, значение — имя стиля |
+| `textLanguages` | Языки, на которые разворачивается текст, заданный строкой (по умолчанию `["ru"]`) |
+| `areas` | Области — диапазоны подряд идущих строк, в порядке документа |
+
+## Области, строки, ячейки
+
+**Область** (`areas[]`) — диапазон подряд идущих строк: `name` (необязательно; с именем область
+доступна как `Макет.ПолучитьОбласть("Имя")`) и `rows`. Область без имени — просто кусок сетки.
+
+**Строка** (`rows[]`): `height`, `hidden`, `rowStyle`, `cells`. Пустая строка — `{}`,
+а `{ "empty": 3 }` заменяет три подряд. `height` и `hidden` — свойства самой строки, у ячейки
+таких нет.
+
+**Ячейка** (`cells[]`):
+
+| Ключ | Описание |
+|---|---|
+| `col` | Позиция колонки, 1-based |
+| `span` / `rowspan` | Объединение вправо / вниз |
+| `style` | Имя стиля; перекрывает `rowStyle` для этой ячейки |
+| `param` | Параметр заполнения — `Область.Параметры.Имя = …` |
+| `text` | Статический текст: строка или объект «язык → текст» |
+| `template` | Текст со вставками `[Параметр]` |
+| `detail` | Параметр расшифровки; ставится и без `param` |
+
+Содержимое задаётся ровно одним ключом из `param` / `text` / `template`; ячейка без них —
+пустая (нужна, например, ради рамки). Пустая строка `"text": ""` — это тоже текст, а не
+отсутствие текста.
+
+### Короткая форма: список ячеек позиционно
+
+Позиция берётся из порядка, `col` не нужен:
+
+| Элемент | Значение |
+|---|---|
+| `"текст"` | Статический текст |
+| `{ "ru": "…", "en": "…" }` | Тот же текст на нескольких языках |
+| `"{Имя}"` | Параметр заполнения |
+| `">"` | Продолжение ячейки слева — увеличивает её `span` |
+| `"|"` | Продолжение ячейки сверху — увеличивает её `rowspan` |
+| `null` | Пропуск колонки |
+| `{ … }` | Обычная ячейка без `col` — когда нужны `style`, `detail`, `template` |
+
+```json
+"rows": [
+  ["Вид", "Остаток", ">", "Итог"],
+  ["|",   "начало",  "конец", "|"],
+  ["{Вид}", "{Нач}", "{Кон}", "{Итог}"]
+]
+```
+
+Здесь «Вид» и «Итог» объединены по вертикали, «Остаток» — по горизонтали на две колонки.
+
+Позиционный список — это форма записи ЯЧЕЕК, а не строки. Если у строки нет своих свойств, он
+и есть строка (как в примере выше). Если нужны `height`, `hidden` или `rowStyle` — тот же
+список кладётся в `cells`:
+
+```json
+{ "rowStyle": "итог", "cells": [null, null, null, "Итого:", "{Всего}"] }
+```
+
+### `rowStyle` — оформление строки
+
+Стиль ложится на ВСЮ ширину строки: колонки без явных ячеек получают его тоже — так выходят
+сплошные рамки в табличной части. Он же становится оформлением самой строки. Ячейки с `rowspan`
+из предыдущих строк при этом пропускаются.
+
+## Оформление
+
+Ячейка, строка и колонка ссылаются на один и тот же именованный стиль: ячейка — ключом `style`,
+строка — `rowStyle`, колонка — через `columnStyles`.
+
+**Шрифт** (`fonts.<имя>`): `face` (Arial), `size` (10), `bold`, `italic`, `underline`,
+`strikeout`. Либо ссылка вместо описания: `{ "ref": "style:TextFont" }`,
+`{ "ref": "sys:DefaultGUIFont" }`. Шрифт `"default"` берётся, когда стиль не указал свой.
+
+**Частые ключи стиля** — имя ключа совпадает с именем свойства в выгрузке, значения перечислений
+регистр не различают:
+
+| Ключ | Значение |
+|---|---|
+| `font` | Имя из `fonts` |
+| `horizontalAlignment` | `Left`, `Center`, `Right`, `Justify`, `Auto` |
+| `verticalAlignment` | `Top`, `Center`, `Bottom` |
+| `textPlacement` | Длинный текст: `Wrap` (перенос), `Cut` (обрезать), `Block`, `Auto` |
+| `border` | Рамка со всех сторон |
+| `leftBorder`, `topBorder`, `rightBorder`, `bottomBorder` | Отдельная сторона |
+| `borderColor` | Цвет рамки |
+| `backColor`, `textColor` | Цвет фона и текста |
+| `format` | Формат данных 1С: `"ЧЦ=15; ЧДЦ=2"`, `"ДФ=dd.MM.yyyy"` |
+
+**Рамка**: `"Solid"` (ширина 1) либо `{ "style": "Solid", "width": 2 }`. Стили линии: `None`,
+`Solid`, `Dotted`, `Dashed`, `DashDotted`, `DashDottedDotted`, `ThinDashed`, `LargeDashed`,
+`ThickDashed`, `Double`. Стороны можно задавать по отдельности всегда: совпавшие четыре
+компилятор свернёт сам.
+
+**Цвет** — нотация платформы: `#RRGGBB`, `style:ИмяСтиля` (элемент стиля конфигурации),
+`web:Имя`, `win:Имя`. Несуществующее имя платформа отвергнет при загрузке.
+
+```json
+"styles": {
+  "шапка":  { "font": "жирный", "horizontalAlignment": "Center", "backColor": "#EBEBEB" },
+  "рамка":  { "border": { "style": "Solid", "width": 2 } },
+  "снизу":  { "bottomBorder": "Dotted" }
+}
+```

.github/skills/mxl-compile/reference/drawings.md

@@ -0,0 +1,72 @@
+# Рисунки и картинки
+
+Рисунок — объект поверх сетки ячеек: картинка, фигура или надпись. Его положение задают два
+якоря: ячейка плюс смещение в точках от её левого верхнего угла.
+
+```json
+"pictures": {
+  "знак":  { "ref": "v8ui:Стоп48" },
+  "логотип": { "data": "iVBORw0KGgo...", "transparent": { "x": 24, "y": 29 } }
+},
+"drawings": [
+  { "type": "Picture", "picture": "логотип", "name": "Логотип",
+    "begin": { "row": 1, "col": 1 },
+    "end":   { "row": 3, "col": 2, "dy": 34, "dx": 115 },
+    "pictureSize": "Proportionally", "detail": "ПараметрРасшифровки" },
+  { "type": "Rectangle", "style": "заливка",
+    "line": { "style": "Dashed", "width": 2 },
+    "sides": { "left": true, "top": true, "right": false, "bottom": false },
+    "begin": { "row": 5, "col": 1 }, "end": { "row": 6, "col": 3 } },
+  { "type": "Text", "text": { "ru": "Подпись", "en": "Signature" },
+    "begin": { "row": 8, "col": 1 }, "end": { "row": 8, "col": 3, "dy": 12 } }
+]
+```
+
+| Поле | Обяз. | По умолч. | Описание |
+|------|:-----:|-----------|----------|
+| `type` | нет | `Picture` | `Picture`, `Rectangle`, `Ellipse`, `Line`, `Text`, `Chart`, `GanttChart` |
+| `begin` / `end` | да | — | Якоря: `row`, `col` (1-based) и смещения `dy`, `dx` в точках |
+| `picture` | нет | — | Имя записи из `pictures` |
+| `pictureSize` | нет | `Stretch` | Как картинка заполняет прямоугольник: `Stretch`, `AutoSize`, `Proportionally`, `RealSize` |
+| `text` | нет | — | Надпись: строка или объект «язык → текст» |
+| `name` | нет | — | Имя рисунка, по которому к нему обращаются из кода |
+| `detail` | нет | — | Параметр расшифровки |
+| `style` | нет | — | Именованный стиль: заливка, шрифт, выравнивание надписи |
+| `line` | нет | — | Линия рисунка (она же его рамка) — как `border` у ячейки |
+| `sides` | нет | — | Какие стороны рамки видны: `left`, `top`, `right`, `bottom` |
+| `id` | нет | номер по порядку | Идентификатор рисунка |
+| `zOrder` | нет | номер по порядку | Порядок перекрытия: чем больше, тем выше |
+
+Порядок в списке `drawings` — порядок в документе; кто кого перекрывает, задаёт `zOrder`.
+
+Запись в `pictures` — либо ссылка (`ref`), либо сами данные в base64 (`data`). Ссылкой
+задаются и предопределённая картинка платформы, и общая картинка конфигурации — пишутся они
+одинаково, префиксом `v8ui:`. Пустая запись `{}` — картинка не задана, такое в макетах встречается.
+Прозрачность задаётся ключом `transparent` в одной из двух форм: `false` — прозрачного фона
+нет; `{ "x": …, "y": … }` — прозрачным считается цвет пикселя с этими координатами внутри
+картинки (по флажку «прозрачный фон» Конфигуратор берёт её правый нижний пиксель).
+
+Одну запись `pictures` могут использовать несколько рисунков — данные в макете не дублируются.
+
+## Картинка в ячейке
+
+Картинка бывает не только поверх сетки, но и внутри ячейки — тогда её задаёт стиль, а сама
+картинка берётся из той же палитры `pictures`:
+
+```json
+{
+  "columns": 2,
+  "pictures": { "стоп": { "ref": "v8ui:Стоп48" } },
+  "styles": { "значок": { "picIndex": 1, "picHorizontalAlignment": "Center",
+                          "picVerticalAlignment": "Center", "textPosition": "Bottom" } },
+  "areas": [{ "rows": [
+    [{ "style": "значок", "text": "удалить", "pictureParameter": "Удалить" }]
+  ]}]
+}
+```
+
+- `picIndex` — номер записи в `pictures`, считая с единицы в порядке объявления;
+- `picHorizontalAlignment`, `picVerticalAlignment`, `pictureSizeMode`, `textPosition` — как
+  картинка стоит в ячейке и где относительно неё текст (значения — в `style-properties.md`);
+- `pictureParameter` — ключ самой ЯЧЕЙКИ, а не стиля: имя параметра, которым картинку
+  подставляют из кода, как `param` подставляет текст. С текстом ячейки уживается.

.github/skills/mxl-compile/reference/groups.md

@@ -0,0 +1,26 @@
+# Группы строк и колонок
+
+Диапазон строк или колонок, который сворачивается кнопкой на полях. Задаются плоским списком;
+вложенность выражена вхождением одного диапазона в другой:
+
+```json
+"rowGroups": [
+  { "rows": "2-4" },
+  { "rows": 3 },
+  { "rows": 5, "name": "Итоговая", "collapsed": true, "titleLocation": "begin" }
+],
+"columnGroups": [
+  { "cols": "2-3", "name": { "ru": "Показатели", "en": "Values" } },
+  { "cols": 3 }
+]
+```
+
+| Поле | Обяз. | По умолч. | Описание |
+|------|:-----:|-----------|----------|
+| `rows` / `cols` | да | — | Диапазон 1-based: число или `"N-M"` |
+| `name` | нет | — | Имя группы: строка или объект «язык → текст» |
+| `collapsed` | нет | `false` | Свёрнута ли группа при открытии |
+| `titleLocation` | нет | `auto` | Расположение заголовка: `begin`, `end`, `auto` |
+
+Диапазоны либо вложены, либо не пересекаются: частичное пересечение — ошибка. Порядок в списке
+не важен, число уровней вложенности считается само.

.github/skills/mxl-compile/reference/input-cells.md

@@ -0,0 +1,48 @@
+# Ячейки-поля ввода
+
+Ячейка может не показывать текст, а принимать значение от пользователя — так делают макеты для
+ввода данных. Достаточно задать тип значения:
+
+```json
+{ "col": 1, "valueType": "Number(15,3,nonneg)" }
+{ "col": 2, "valueType": "String(10)" }
+{ "col": 3, "valueType": "Boolean", "controlType": "checkbox" }
+{ "col": 4, "valueType": "CatalogRef.Валюты" }
+{ "col": 5, "valueType": "Boolean + String + Date + CatalogRef.Валюты" }
+{ "col": 6, "valueType": "AnyRef" }
+```
+
+Грамматика типа:
+
+| Запись | Значение |
+|---|---|
+| `Boolean` | булево |
+| `String`, `String(10)`, `String(10,fixed)` | строка; без длины — неограниченная, `fixed` — фиксированной длины |
+| `Number`, `Number(15,3)`, `Number(15,3,nonneg)` | число; без параметров — без ограничения разрядности, `nonneg` — неотрицательное |
+| `Date`, `DateTime`, `Time` | дата, дата со временем, время |
+| `CatalogRef.Валюты`, `DocumentRef.Реализация`, `EnumRef.Статусы`, `DefinedType.Сумма` | ссылочный тип |
+| `CatalogRef`, `DocumentRef`, `AnyRef` | категория целиком: любая ссылка этого вида |
+| `A + B` | составной тип; повтор одного примитива недопустим |
+
+Русские имена принимаются наравне с английскими: `Число(15,3)`, `Строка(10)`,
+`СправочникСсылка.Валюты`.
+
+`text` и `template` в такой ячейке недопустимы — платформа не показывает текст там, где вводится
+значение. `param` и `detail` допустимы: они описывают заполнение и расшифровку, а не содержимое.
+
+Пустой тип `"valueType": ""` — «ячейка содержит значение», но тип не ограничен.
+
+Значение поля ввода задаётся ключом `value`. Его тип — тип литерала JSON: строка, число,
+`true`/`false`; к объявленному типу ячейки значение не приводится. Пустая строка означает
+пустое значение объявленного типа. Дата пишется строкой `ГГГГ-ММ-ДДTчч:мм:сс` и читается
+как дата у ячейки, объявленной датой; у ссылочного и составного типа значение — строка.
+
+```json
+{ "col": 1, "valueType": "Number(15,3)", "value": 12.5 }
+{ "col": 2, "valueType": "String(10)", "value": "5" }
+{ "col": 3, "valueType": "Boolean", "value": true }
+{ "col": 4, "valueType": "DateTime", "value": "" }
+```
+
+`controlType` нужен редко: умолчание платформы — поле ввода, и оно подходит всем типам, включая
+`Boolean`. Флажок задаётся явно.

.github/skills/mxl-compile/reference/layout.md

@@ -0,0 +1,74 @@
+# Разметка: области координатами и колоночные раскладки
+
+Читать, когда область не описывается диапазоном подряд идущих строк или когда части документа нужны разные ширины колонок.
+
+## Именованные области координатами (`namedAreas[]`)
+
+Для областей, которые диапазоном подряд идущих строк не описываются: полоса колонок, прямоугольник, ячейка, а также пересекающиеся с другими.
+
+| Поле | Обяз. | Описание |
+|------|:-----:|----------|
+| `name` | да | Имя области |
+| `rows` | \* | Строки: число или диапазон `"N-M"`, 1-based |
+| `cols` | \* | Колонки: число или диапазон `"N-M"`, 1-based |
+| `columnSet` | нет | Колоночная раскладка области. Без ключа выводится из накрытых строк, `""` — привязки нет |
+
+\* Обязательна хотя бы одна из осей.
+
+**Тип области не указывается** — он следует из того, какие оси заданы, как в `ТабличныйДокумент.Область()`: только строки → полоса строк, только колонки → полоса колонок, обе оси → прямоугольник, одиночные значения по обеим осям → одна ячейка.
+
+```json
+"namedAreas": [
+  { "name": "ОбластьПечатиПоВысоте", "rows": "1-48" },
+  { "name": "ОбластьПечатиПоШирине", "cols": "1-35" },
+  { "name": "HZY", "rows": 9, "cols": "16-17" }
+]
+```
+
+Диапазон — та же грамматика, что у `columnWidths`, но **только** число или `"N-M"`: список через запятую запрещён, область непрерывна. Имя обязательно, и хотя бы одна ось должна быть задана; нарушение любого из этих правил → ненулевой код выхода и сообщение в stderr.
+
+## Колоночные раскладки (`columnSets`)
+
+Группа строк может иметь собственные ширины колонок — в 1С это «индивидуальная ширина колонок».
+Документные `columns` и `columnWidths` описывают раскладку по умолчанию; дополнительные
+объявляются в `columnSets`, а область ссылается на нужную ключом `columnSet` — так же, как
+ячейка ссылается на `styles` через `style`.
+
+```json
+{
+  "columns": 52,
+  "columnWidths": { "1": 8 },
+  "columnSets": {
+    "таблица": { "columns": 52, "columnWidths": { "1": 7, "2-52": 24 } }
+  },
+  "areas": [
+    { "name": "Шапка", "rows": [["Отчёт о продажах"]] },
+    { "name": "ТабличнаяЧасть", "columnSet": "таблица",
+      "rows": [["№", "Номенклатура"]] }
+  ]
+}
+```
+
+Раскладка описывается той же парой полей, что и документная: `columns` — количество колонок
+(у раскладок оно обычно разное), `columnWidths` — ширины. Ключ словаря — имя раскладки;
+в макетах, полученных декомпиляцией, это идентификатор из исходного файла, при описании
+с нуля — любая строка.
+
+Все строки области получают раскладку области, поэтому одна область не может смешивать
+раскладки. Позиции колонок (`col`, `span`) проверяются по ширине раскладки СВОЕЙ области,
+а не документной.
+
+Ссылка на необъявленную раскладку → ненулевой код выхода и сообщение в stderr.
+
+## Стиль колонки (`columnStyles`)
+
+Колонка несёт то же оформление, что ячейка и строка. Ключи — та же грамматика диапазонов,
+что у `columnWidths`; значение — имя стиля.
+
+```json
+"columnWidths": { "1": 30, "2-3": 15 },
+"columnStyles": { "1": "по-центру", "4": "скрытая" }
+```
+
+Внутри `columnSets` работает тот же ключ. Ширина и стиль независимы: колонка может иметь
+только ширину, только стиль или и то, и другое.

.github/skills/mxl-compile/reference/notes.md

@@ -0,0 +1,26 @@
+# Примечания к ячейкам
+
+Всплывающая подсказка, которую платформа показывает при наведении. Задаётся ключом `note` —
+строкой, объектом «язык → текст» или полной формой:
+
+```json
+{ "col": 1, "text": "Итого", "note": "Сумма без НДС" }
+{ "col": 2, "note": { "ru": "на дату документа", "en": "as of the document date" } }
+{ "col": 3, "note": { "text": "не более 20%", "style": "жёлтая-подсказка" } }
+{ "col": 4, "note": { "text": "…", "autoSize": false,
+                      "box": { "top": 58, "left": -175, "bottom": 362, "right": 478 } } }
+```
+
+Объект трактуется по ключам — так же, как текст ячейки в короткой форме строки: есть ключ
+примечания (`text`, `style`, `box`, `autoSize`) → это описание примечания, иначе ключи
+считаются идентификаторами языков.
+
+| Поле | По умолч. | Описание |
+|------|-----------|----------|
+| `text` | — | Текст подсказки: строка или объект «язык → текст» |
+| `style` | стиль подсказки | Имя стиля из `styles`; без него — оформление, которое даёт Конфигуратор |
+| `autoSize` | `true` | Подгонять ли размер окошка под текст |
+| `box` | — | Смещения окошка: `top`, `left` — положение, `bottom`, `right` — размер. Без ключа окошко встаёт стандартно |
+
+Координаты ячейки в примечании не задаются. `autoSize` и `box` независимы: при автоподгоне
+размера положение окошка всё равно хранится.

.github/skills/mxl-compile/reference/print.md

@@ -0,0 +1,59 @@
+# Печать: колонтитулы и параметры страницы
+
+Читать, когда макет готовят к печати: повторяющиеся надписи сверху и снизу, ориентация, поля, масштаб.
+
+## Колонтитулы
+
+У верхнего и нижнего колонтитула по три слота — `left`, `center`, `right` — и общие настройки:
+
+```json
+"header": {
+  "font": "мелкий",
+  "verticalAlignment": "Bottom",
+  "startPage": 2,
+  "left": "Слева\nвторая строка",
+  "center": "Стр. [&НомерСтраницы] из [&СтраницВсего]",
+  "right": { "ru": "Справа", "en": "Right" }
+},
+"footer": {
+  "show": false,
+  "center": { "formatted": "<b>Итог</> <colorstyle -16>красным</>" }
+}
+```
+
+| Поле | По умолч. | Описание |
+|------|-----------|----------|
+| `left`, `center`, `right` | — | Текст слота: строка, объект «язык → текст» или `{ "formatted": … }` |
+| `font` | — | Имя шрифта из `fonts` — на весь колонтитул |
+| `verticalAlignment` | — | Положение текста по вертикали: `Top`, `Center`, `Bottom` |
+| `show` | `true` | Выводить ли колонтитул |
+| `startPage` | `1` | Страница, с которой колонтитул печатается |
+
+Текст может быть многострочным (`\n`) и содержать поля `[&НомерСтраницы]`, `[&СтраницВсего]`,
+`[&Дата]`, `[&Время]` — платформа подставляет их при печати. `{ "formatted": … }` — форматированная
+строка: разметка живёт прямо в тексте (`<b>жирный</>`, `<fontsize 12>`, `<colorstyle -16>`).
+
+## Параметры печати
+
+Плоский объект; имя ключа совпадает с именем свойства в выгрузке:
+
+```json
+"printSettings": {
+  "pageOrientation": "Landscape",
+  "topMargin": 500, "leftMargin": 500, "bottomMargin": 500, "rightMargin": 500,
+  "headerSize": 1000, "footerSize": 1000,
+  "fitToPage": true, "firstPageNumber": 7
+}
+```
+
+Допустимые ключи: `pageOrientation`, `scale`, `collate`, `copies`, `perPage`, `topMargin`,
+`leftMargin`, `bottomMargin`, `rightMargin`, `headerSize`, `footerSize`, `fitToPage`,
+`blackAndWhite`, `printerName`, `paper`, `paperSource`, `pageWidth`, `pageHeight`, `duplexType`,
+`pagePlacementAlternation`, `firstPageNumber`. Незнакомый ключ — ошибка. Порядок в объекте не
+важен: компилятор пишет свойства в том порядке, что и платформа.
+
+## Чего в DSL нет
+
+Область печати и повторение области при печати (шапка на каждой странице) не описываются:
+эти настройки задаются в Конфигураторе и при пересборке чужого макета теряются. Если задача
+требует именно их — правьте макет в Конфигураторе, а не через DSL.

.github/skills/mxl-compile/reference/style-properties.md

@@ -0,0 +1,81 @@
+# Свойства стиля: полный перечень
+
+Читать, когда нужного свойства нет среди частых, описанных в SKILL.md: отступы, защита, узор, маска, формат редактирования, поведение при выводе.
+
+Имя ключа совпадает с именем свойства в выгрузке — исключений нет.
+
+Тип значения:
+
+- **число** — целое;
+- **да/нет** — `true` / `false`;
+- **перечисление** — одно из указанных, регистр не важен;
+- **цвет** — `#RRGGBB`, `style:Имя`, `web:Имя`, `win:Имя`;
+- **линия** — `"Solid"` либо `{ style, width }`;
+- **текст** — строка (разворачивается на языки макета).
+
+## Текст и выравнивание
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `font` | имя | Ссылка на имя из `fonts` |
+| `horizontalAlignment` | перечисление | `Left`, `Center`, `Right`, `Justify`, `Auto` |
+| `verticalAlignment` | перечисление | `Top`, `Center`, `Bottom` |
+| `textPlacement` | перечисление | `Wrap`, `Cut`, `Block`, `Auto` |
+| `textOrientation` | число | Поворот в десятых долях градуса: `900` = 90° |
+| `textColor` | цвет | Цвет текста |
+| `indent` | число | Отступ текста |
+| `autoIndent` | число | Автоматический отступ |
+| `format` | текст | Формат данных: `"ЧЦ=15; ЧДЦ=2"` |
+| `editFormat` | текст | Формат редактирования |
+| `mask` | текст | Маска ввода |
+| `markNegatives` | да/нет | Выделять отрицательные |
+
+## Фон и рамка
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `backColor` | цвет | Цвет фона |
+| `pattern` | перечисление | `WithoutPattern`, `Solid`, `Pattern1`…`Pattern17` (в Конфигураторе «Узор 1» … «Узор 17») |
+| `patternColor` | цвет | Цвет узора |
+| `border` | линия | Все четыре стороны |
+| `leftBorder`, `topBorder`, `rightBorder`, `bottomBorder` | линия | Отдельная сторона |
+| `borderColor` | цвет | Цвет рамки |
+
+## Поведение
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `hidden` | да/нет | Скрыть |
+| `protection` | да/нет | Защита от редактирования |
+| `print` | да/нет | Выводить на печать |
+| `hyperLink` | да/нет | Гиперссылка |
+| `detailsUse` | перечисление | Использование расшифровки: `Cell`, `Row`, `WithoutProcessing` |
+| `autoMarkIncomplete` | да/нет | Автоотметка незаполненного |
+| `bySelectedColumns` | да/нет | По выделенным колонкам |
+| `columnSizeChange` | перечисление | `Normal`, `QuickChange` |
+| `autoWidthCalculation` | да/нет | Автоматический расчёт ширины |
+| `widthWeightFactor` | число | Весовой коэффициент ширины |
+
+## Картинка в ячейке
+
+Ключи ниже задают картинку внутри ячейки; сама палитра картинок и рисунки поверх сетки —
+в `reference/drawings.md`.
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `picIndex` | число | Номер картинки |
+| `pictureSizeMode` | перечисление | `AutoSize`, `Proportionally`, `RealSize` |
+| `picHorizontalAlignment` | перечисление | `Auto`, `Center`, `Left`, `Right` |
+| `picVerticalAlignment` | перечисление | `Top`, `Center`, `Bottom` |
+| `textPosition` | перечисление | Положение текста относительно картинки: `Auto`, `Top`, `Right`, `Bottom` |
+
+## Чего в стиле нет
+
+- `width` — свойство колонки, задаётся через `columnWidths`;
+- `height` — свойство строки, задаётся ключом `height` у строки;
+- `fillType` — выводится из того, каким ключом задано содержимое ячейки
+  (`text` / `param` / `template`);
+- `containsValue`, `valueType`, `controlType` — свойства конкретной ячейки, а не общего
+  оформления: задаются ключами ячейки `valueType` и `controlType`;
+- линия рисунка и её стороны — свойства рисунка: задаются его ключами `line` и `sides`
+  (`reference/drawings.md`); у ячейки такого свойства нет вовсе.