SSAUGenerator/AGENTS.md

# AGENTS.md — управление проектом SSAU Generator

Репозиторий содержит два независимых генератора отчётных документов из Markdown.
Этот файл описывает управление проектом в целом. Правила работы с конкретным
документом — в [`docx/AGENTS.md`](docx/AGENTS.md) и [`pptx/AGENTS.md`](pptx/AGENTS.md).

## Что использовать по запросу пользователя

- Просит **сгенерировать документ** (отчёт, DOCX, пояснительную записку,
  лабораторную работу) — используйте генератор в папке `docx/`.
- Просит **сгенерировать презентацию** (PPTX, слайды) — используйте генератор в
  папке `pptx/`.

Команды запускаются из корня репозитория; генератору указывается `config.yaml`
нужного проекта. Содержимое документа задаётся Markdown-файлами и `config.yaml`
проекта, а не кодом генератора.

## Правила работы над проектом

- **Уточните название проекта.** Если пользователь не указал, над каким проектом
  ведётся работа, сначала спросите его. Проект — это папка `content/<проект>/`.
- **Один проект за сессию.** В рамках одной сессии работайте только над одним
  проектом.
- **Создание — только через `--init`.** Новый проект создавайте командами с флагом
  `--init` (см. ниже): они формируют правильную структуру и общий каталог
  ресурсов.
- **Сначала план — потом работа.** Прежде чем наполнять проект, составьте план и
  сохраните его в `content/<проект>/PLAN.md` (см. раздел «Планирование проекта»).
  Работу над содержимым начинайте только после согласования плана с пользователем.
- **Имя результата = имя проекта.** Документ и презентация собираются в папку
  проекта, а имя файла совпадает с именем проекта:
  `content/<проект>/<проект>.docx` и `content/<проект>/<проект>.pptx`.
  Соответствующий путь задаётся ключом `output` в `config.yaml`.
- **Пересобирайте после правок.** При любом изменении исходных файлов
  (`config.yaml`, `*.md`, ресурсов в `assets/`) заново запускайте сборку docx
  и/или pptx, чтобы результат соответствовал исходникам.

## Структура репозитория

```
ssau-generator/
├── docx/            # генератор DOCX (только код)
├── pptx/            # генератор PPTX (только код)
├── tools/           # общий plantuml.jar
├── content/         # проекты (в git хранится только example)
│   └── example/
│       ├── assets/  # общие ресурсы проекта (для docx и pptx)
│       ├── docx/    # config.yaml + *.md
│       ├── pptx/    # config.yaml + slides/
│       └── PLAN.md  # согласованный план проекта
├── AGENTS.md        # этот файл
└── README.md
```

## Проекты и каталог content

- **Один проект = одна папка** `content/<проект>/`.
- Внутри проекта при необходимости лежат папки `docx/` и `pptx/`.
- **Общие ресурсы проекта** (титульный лист, задники, изображения, исходники
  `.puml`) размещаются в `content/<проект>/assets/` и используются обоими
  генераторами. В `docx/` и `pptx/` внутри проекта хранятся только `config.yaml`
  и Markdown.
- Папки `content/*` добавлены в `.gitignore`; в репозитории хранится только
  `content/example/`. Рабочие проекты пользователя коммитить не нужно.

## Планирование проекта

Перед наполнением проекта составьте план и сохраните его в
`content/<проект>/PLAN.md`. План создаётся **до** работы над `config.yaml` и
Markdown и согласуется с пользователем. В плане укажите:

- **реквизиты** — студент (ФИО), группа, дисциплина;
- **тему** работы и её цель;
- **структуру** — разделы и подразделы с названиями и пунктами (для документа —
  по `sections`, для презентации — список слайдов);
- **краткое содержание** каждого раздела/слайда;
- **список источников** — если согласован с пользователем;
- **нюансы** — особые требования пользователя (объём, оформление, сроки,
  ограничения и т.п.), если они указаны;
- прочие согласованные детали.

Пример готового плана — `content/example/PLAN.md`.

## Создание нового проекта

Проект создаётся командами с флагом `--init` — они формируют структуру и общие
ресурсы автоматически:

```powershell
# только документ DOCX
node docx/src/cli.js --content content/<проект>/docx --init

# только презентация PPTX
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init

# оба генератора (каталог content/<проект>/assets/ создаётся первым вызовом
# и переиспользуется вторым)
```

После создания отредактируйте `config.yaml` и Markdown; общие ресурсы
(титульный лист, задники, изображения, `.puml`) положите в
`content/<проект>/assets/`.

## Сборка

```powershell
# Документ DOCX
node docx/src/cli.js --content content/<проект>/docx --check
node docx/src/cli.js --content content/<проект>/docx

# Презентация PPTX
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --check
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml
```

Результат: `content/<проект>/<проект>.docx` или
`content/<проект>/<проект>.pptx` (имя и путь задаются ключом `output` в
`config.yaml`). После правок исходников пересобирайте файлы.

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

- Node.js 18+, зависимости устанавливаются командой `npm install` в `docx/` и
  `pptx/`.
- Java 11+ и файл `tools/plantuml.jar` — для рендеринга схем PlantUML (`.puml`).

## Правила

- Для сборки документа не редактируйте код генераторов — меняйте `config.yaml`
  и Markdown проекта.
- Не коммитьте содержимое `content/`, кроме `content/example/`.
- Не храните ресурсы внутри `docx/` и `pptx/` — общие файлы живут в
  `content/<проект>/assets/`.