Initial commit

.template/development/modules/references.md

@@ -0,0 +1,49 @@
+# Модуль: Ссылки и библиографии
+
+**Ответственность**: предоставляет русскоязычные перекрёстные ссылки и модель одной или нескольких библиографических секций Typst 0.15.
+**Расположение**: `.template/lib/domain/references.typ`, `.template/lib/presentation/references.typ`
+
+## Публичный интерфейс
+
+| Символ | Тип | Описание |
+|--------|-----|----------|
+| `vref()` | contextual function | Форматирует одну ссылку с падежом для рисунка, таблицы, формулы, раздела или приложения |
+| `vrefs()` | contextual function | Форматирует массив однородных labels с корректным соединением |
+| `eqref()` | contextual function | Создаёт ссылку на формулу без лишнего supplement |
+| `bibliography-section()` | domain constructor | Описывает sources, title, style, target, group и политику переноса |
+| `render-bibliographies()` | function | Размещает произвольное число секций через нативный `bibliography()` |
+| `validate-bibliographies()` | function | Проверяет ids, sources, target/group и наличие default coverage policy |
+
+`vref()` и `vrefs()` по умолчанию используют предложный падеж и прописную первую букву названия объекта. Короткие коды — `"и"`, `"р"`, `"д"`, `"в"`, `"т"`, `"п"`; прежние сокращения и полные русские названия нормализуются во внутренние ключи `"имен"`, `"род"`, `"дат"`, `"вин"`, `"тв"`, `"предл"`. Строчная форма включается явно через `capitalized: false`.
+
+## Зависимости
+
+| Модуль | Что использует |
+|--------|----------------|
+| Typst `query`, `selector`, `ref`, `cite` | Разрешение labels и citations |
+| Typst 0.15 `bibliography(target:, group:)` | Несколько списков источников и управление нумерацией |
+| `.template/lib/domain/document.typ` | Profile metadata и render options |
+
+## Инварианты
+
+- Cross-reference label и bibliography citation являются разными типами использования и не смешиваются в одной функции.
+- `vref` всегда обрабатывает состояние `element == none`, потому что Typst может ещё не обнаружить элемент.
+- `vref` поддерживает `имен`, `род`, `дат`, `вин`, `тв`, `предл`; неизвестный падеж является ошибкой, а не тихим fallback.
+- `vrefs` объединяет однородные labels под одной формой множественного числа (`рисунках 1 и 2`, `приложениях А и Б`), смешанные типы форматирует поэлементно.
+- Заголовок с supplement `Приложение` классифицируется отдельно от обычного раздела и поддерживает все шесть падежей.
+- Каждая bibliography section имеет стабильный id и хотя бы один source.
+- Последующие секции по умолчанию начинаются с новой страницы (`page_break: true`), поэтому их заголовки и записи не могут наложиться; компактный режим включается явно.
+- `target` передаётся как `auto`, label, selector, location или function без преобразования в строку.
+- `group: none` сбрасывает нумерацию секции; одинаковая строковая группа продолжает нумерацию.
+- Если используется несколько sections, fixture обязан доказать, что каждая citation попала ровно в одну bibliography.
+
+## Намеренно НЕ обрабатывает
+
+- Редактирование `.bib` и Hayagriva-файлов.
+- Поиск научных источников.
+- Ссылки на внешние URL без label.
+- Автоматическое определение падежа по окружающему тексту.
+
+## Заметки для агента
+
+> Typst 0.15 нативно распределяет citations между несколькими bibliographies. Не воспроизводите этот алгоритм вручную. Domain хранит настройки, presentation вызывает built-in и смещает уровень заголовка библиографии по официальной схеме. Добавьте fixtures для поглавных, тематических, общей и раздельной нумерации.