# AGENTS.md — работа с документом DOCX

Генератор `docx/` собирает отчёт в формате **DOCX** из обычных **Markdown**-файлов
по фиксированному дизайну СТО 02068410-004-2018. Этот файл — инструкция агенту по
созданию и правке конкретного документа. Поведение полностью задаётся `config.yaml`
проекта, менять код генератора не нужно.

## 1. Требования

- Node.js 18+, зависимости ставятся командой `npm install` в папке `docx/`.
- Windows/macOS/Linux.
- Готовые PNG вставляются без внешних зависимостей. Для рендеринга PlantUML
  (`.puml`) нужны Java 11+ и файл `plantuml.jar` (см. `plantuml` в конфиге).

## 2. Раскладка проекта

Проект лежит в `content/<проект>/docx/` рядом с `config.yaml`:

```
content/<проект>/
├── assets/               # общие ресурсы проекта (общие с pptx)
│   ├── title-page.docx   # титульный лист
│   └── images/           # PNG-рисунки и исходники .puml
└── docx/
    ├── config.yaml       # настройки документа
    ├── 01-introduction.md
    ├── 02-*.md
    └── 05-bibliography.md
```

Все относительные пути в `config.yaml` считаются **от каталога самого
`config.yaml`**. Если ресурсы общие с презентацией, указывайте их через `../assets`
(например, `paths.assets: ../assets`, `document.titlePage: ../assets/title-page.docx`).

Отчёт собирается в папку проекта и называется по имени проекта:
`content/<проект>/<проект>.docx`. Значение ключа `document.output` при такой
раскладке — `../<проект>.docx`.

Структуру проекта создавайте командой `--init`: она формирует `config.yaml`,
примеры `*.md` и общий каталог `content/<проект>/assets/` (титульный лист,
изображения), который используется и генератором `pptx`.

Готовый пример со всеми возможностями — `content/example/docx/`.

## 3. Командная строка

Из корня репозитория:

```
node docx/src/cli.js [опции]

  --config <путь>   путь к config.yaml (по умолчанию config.yaml в текущем каталоге)
  --content <dir>   каталог проекта: config.yaml, *.md и assets/ (по умолчанию текущий)
  --output <путь>   переопределить путь выходного .docx
  --check           только проверить конфиг и ссылки, без записи файла
  --init            создать шаблон config.yaml/*.md/assets и выйти
  --verbose         подробный вывод
  --version         показать версию
  --help            справка
```

Типичный цикл:

```powershell
node docx/src/cli.js --content content/<проект>/docx --init    # создать структуру проекта
node docx/src/cli.js --content content/<проект>/docx --check   # проверить
node docx/src/cli.js --content content/<проект>/docx           # собрать
```

После любого изменения исходников (`config.yaml`, `*.md`, ресурсов `assets/`)
**пересоберите документ**, чтобы результат соответствовал исходникам.

Если `config.yaml` не найден, инструмент сам создаёт шаблон (`config.yaml`,
примеры Markdown и общий `assets/`) и завершается.

## 4. Схема `config.yaml`

Любой ключ можно опустить — берётся значение по умолчанию (см.
`docx/src/config/defaults.js`).

### document
| Ключ | Тип | Смысл |
|------|-----|-------|
| `output` | string | путь выходного `.docx` (относительно `config.yaml`) |
| `titlePage` | string/null | путь к готовому `title-page.docx`; `null` — без титульника |
| `features.updateFields` | bool | обновлять поля (в т.ч. оглавление) при открытии в Word |

Титульный лист склеивается перед документом, между ним и текстом вставляется
разрыв страницы. При `--init` создаётся пример `assets/title-page.docx`.

### paths
| Ключ | Смысл |
|------|-------|
| `assets` | корень ресурсов; `file=images/x.png` в директивах ищется здесь |

### Структура и оформление

| Раздел | Назначение |
|--------|-----------|
| `page` | `width`, `height` (DXA), `margins` (twips) |
| `typography` | `font`, `sizeBody`/`sizeTable`/`sizeSmall`, `lineSpacing`, `color`, `useBold`, `allowEmphasis`, `language` |
| `headings` | интервалы/выравнивание `struct`, `section`, `subsection`, `point` |
| `captions` | префиксы и тире подписей `figure`, `table`, `tableContinue` |
| `lists` | `bulletChar`, `letterSuffix`, `numberSuffix`, `nestedLevelStep`, `forbiddenLetters` |
| `numbering` | `figures`, `tables`, `formulas`: `global` или `section` |
| `formula` | `spacingBeforeAfter`, `whereTabPosition` |
| `table` | `font`, `size`, `borderColor`, `borderSize`, `cellMargins`, `headerFill`, `cellFill` |
| `figure` | `maxWidth` (px, `null` — по ширине), `maxHeight` (px) |
| `pageNumber` | `align`, `format`, `startFrom` |
| `toc` | `enabled`, `title`, `depth` (1..3) |
| `bibliography` | `title` |
| `citation` | `bracketOpen`, `bracketClose`, `pagePrefix` |
| `appendix` | `labelPrefix`, `forbiddenLetters` |

### plantuml

| Ключ | Тип | Смысл |
|------|-----|-------|
| `enabled` | bool | включить рендеринг `.puml`; `false` — считать ошибкой |
| `java` | string | `auto` — `%JAVA_HOME%\bin\java`, иначе `java` из PATH |
| `jar` | string | путь к `plantuml.jar` (относительно `config.yaml`) |
| `format` | string | только `png` |
| `charset` | string | кодировка исходника (по умолчанию `UTF-8`) |
| `cache` | bool | не перерисовывать неизменённый исходник |
| `cacheDir` | string | каталог кэша PNG (относительно `config.yaml`) |
| `timeoutMs` | int | таймаут рендера одной диаграммы, мс |

Общий `plantuml.jar` репозитория лежит в `tools/plantuml.jar`; из проекта путь
вида `../../../tools/plantuml.jar`. Ошибки рендера (нет `jar`, нет Java,
синтаксическая ошибка) — фатальные: сборка останавливается с кодом `1`.

### sections — структура документа

Упорядоченный список частей:

```yaml
sections:
  - { type: toc }                                          # поле оглавления
  - { file: 01-introduction.md, type: structural, title: Введение }
  - { file: 02-main.md,         type: numbered }           # # = 1, ## = 1.1, ### = 1.1.1
  - { file: 04-conclusion.md,   type: structural, title: Заключение }
  - { file: 05-bibliography.md, type: bibliography }
  - { file: 06-appendix-a.md,   type: appendix, letter: А, title: Приложение }
```

| type | Поведение |
|------|-----------|
| `toc` | вставляет оглавление (не требует `file`) |
| `structural` | ненумерованный раздел (Введение/Заключение): заголовок = `title`, ЗАГЛАВНЫМИ, по центру, с новой страницы |
| `numbered` | нумеруемый раздел; `#` = раздел, `##`/`###` = подраздел/пункт |
| `bibliography` | список источников; нумеруется автоматически |
| `appendix` | приложение: заголовок «ПРИЛОЖЕНИЕ <letter>» + `title`, буквенный префикс у рисунков/таблиц |

## 5. Формат контента

### Заголовки

В файле `type: numbered`:

```md
# НАЗВАНИЕ РАЗДЕЛА        -> 1 НАЗВАНИЕ РАЗДЕЛА (с новой страницы)
## Подраздел             -> 1.1 Подраздел
### Пункт                -> 1.1.1 Пункт
```

Номера подставляются автоматически (Word-numbering). В `structural`/`appendix`
заголовок берётся из `title`, а заголовки внутри файла рендерятся без номера.

### Абзацы и списки

Обычные абзацы и списки Markdown. Пример:

```md
- первый пункт;
- второй пункт:
  1. вложенный пункт (выведется как «а) вложенный пункт»);
  2. ещё один.
```

Маркер вложенности выбирается автоматически: тире → `а)` → `1)`. Полужирный и
курсив по умолчанию игнорируются (СТО).

### Таблицы

- Обычная GFM-таблица без директивы — таблица **без подписи и номера**.
- С подписью и автономером — директива `::: table`:

```md
::: table "Название таблицы" id=params note="примечание"
| Параметр | Значение |
|---|---|
| A | 1 |
| B | 2 |
:::
```

### Рисунки

```md
::: figure "Название рисунка" id=arch file=images/arch.png
а) первый поясняемый элемент;
б) второй поясняемый элемент.
:::
```

`file` — относительно `paths.assets`. Если файла нет — предупреждение, подпись
всё равно выводится. Подпись ставится под рисунком по центру:
`Рисунок N — Наименование`. Если пояснять нечего, тело директивы оставляют
пустым:

```md
::: figure "Общая схема системы" id=common file=images/common.png
:::
```

**PlantUML.** Если `file` оканчивается на `.puml` (`.plantuml`, `.pu`, `.iuml`),
файл рендерится в PNG через `plantuml.jar` и вставляется как обычный рисунок:

```md
::: figure "Диаграмма последовательности" id=seq file=images/seq.puml
а) запрос клиента;
б) ответ сервера.
:::
```

Ошибка рендера фатальна, `--check` тоже рендерит `.puml`.

В приложениях номер рисунка получает префикс буквы: `Рисунок А.1 — Наименование`.

### Формулы

```md
::: formula id=line
y = a*x + b
:::

::: where
y — результат;
x — аргумент;
a — коэффициент.
:::
```

Поддерживается простой синтаксис: `^` (степень), `_` (индекс), `/` (дробь). Номер
формулы ставится автоматически справа.

### Примечания и термины

```md
::: note
Текст примечания.
:::

::: notes
- первое примечание;
- второе примечание.
:::

::: definitions
Термин — определение;
Ещё термин — определение.
:::
```

### Разрыв страницы

```md
::: pagebreak
:::
```

Тематический разрыв `---` также трактуется как разрыв страницы.

### Ссылки на источники

`[@1]` — ссылка на 1-й источник, `[@1, с. 96]` — с номером страницы. Список
источников — Markdown-список в файле `type: bibliography`; порядок строк = номера.
Ссылка вне диапазона — ошибка в `--check`.

### Перекрёстные ссылки

`@fig:id`, `@tbl:id`, `@eq:id` подставляют актуальный номер рисунка/таблицы/
формулы (например `2`, `1.1`, `А.1`). `id` задаётся в директиве.

### Блоки кода

Fenced-блоки ``` игнорируются с предупреждением (функция листингов удалена).

## 6. Проверка и ошибки

`--check` проверяет:

- корректность `config.yaml` (типы, существование файлов, буквы приложений);
- наличие всех `sections[].file`;
- существование меток в `@fig/@tbl/@eq`;
- диапазон ссылок `[@n]`;
- рендеринг всех `::: figure ... file=*.puml`.

Ошибки печатаются списком и возвращают код выхода `1`. Предупреждения (например,
отсутствующий PNG) не останавливают сборку; ошибки PlantUML — фатальные.

## 7. Подготовка диаграмм

Готовые PNG кладутся в общий каталог ресурсов (`content/<проект>/assets/images/`).
Исходники PlantUML (`.puml`) кладутся туда же и указываются в
`::: figure ... file=images/<имя>.puml`. Диаграммы других форматов (Mermaid,
draw.io) готовятся внешними средствами и вставляются как PNG.

## 8. Замечания по дизайну

- Дизайн фиксирован под СТО 02068410-004-2018; меняются только параметры из
  `config.yaml`.
- Полужирный и курсив по умолчанию отключены (`typography.useBold`,
  `allowEmphasis`).
- Оглавление — поле Word; при открытии нажмите «Обновить поле» либо включите
  `document.features.updateFields`.