docs: опиши работу с сабмодулями и добавь сборку Doxygen

doc/build-doxygen.ps1

@@ -0,0 +1,28 @@
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+$repositoryRoot = Split-Path -Parent $PSScriptRoot
+$doxygen = Get-Command doxygen -ErrorAction SilentlyContinue
+
+if (-not $doxygen) {
+    throw 'Doxygen не найден в PATH. Установите Doxygen и повторите запуск.'
+}
+
+Push-Location $repositoryRoot
+try {
+    & $doxygen.Source Doxyfile
+    if ($LASTEXITCODE -ne 0) {
+        throw "Doxygen завершился с кодом $LASTEXITCODE."
+    }
+}
+finally {
+    Pop-Location
+}
+
+$indexPath = Join-Path $repositoryRoot '.codex-build\doxygen\html\index.html'
+if (-not (Test-Path -LiteralPath $indexPath)) {
+    throw "Doxygen не создал ожидаемый файл: $indexPath"
+}
+
+Write-Host "[DONE] Doxygen HTML: $indexPath"

doc/submodules.dox

@@ -0,0 +1,96 @@
+/**
+@page submodule_workflow Слияние templates как Git submodule
+
+Основной проект хранит не файлы `templates`, а gitlink: ссылку на один точный
+commit отдельного репозитория. Поэтому слияние выполняется на двух уровнях:
+
+1. исходники и их конфликты объединяются в репозитории `templates`;
+2. основной проект отдельным commit фиксирует итоговый SHA сабмодуля.
+
+@section submodule_clone Клонирование и переключение веток
+
+Новый проект клонируется вместе с сабмодулями:
+
+@code{.sh}
+git clone --recurse-submodules <url-основного-проекта>
+@endcode
+
+После `git switch`, `git pull` или merge рабочее дерево приводится к gitlink,
+который записан в выбранной ревизии проекта:
+
+@code{.sh}
+git submodule update --init --recursive
+@endcode
+
+Detached HEAD внутри `lib/templates` в этом режиме является нормой: основной
+проект фиксирует commit, а не плавающую ветку.
+
+@section submodule_update Обновление зафиксированной версии
+
+Изменение сначала должно быть проверено и слито в `master` репозитория
+`templates`. Затем основной проект выбирает опубликованный commit:
+
+@code{.sh}
+git -C lib/templates fetch origin
+git -C lib/templates switch --detach origin/master
+git add lib/templates
+git diff --cached --submodule=log
+git commit -m "build(templates): обновить общие библиотеки"
+@endcode
+
+Перед commit проверяются тесты самой библиотеки, сборка проекта, адаптеры,
+конфигурация платы и аппаратные тесты. Автоматически двигать сабмодуль на
+последний `master` при каждой сборке не следует: это уничтожает
+воспроизводимость.
+
+@section submodule_develop Изменение templates из основного проекта
+
+Перед редактированием нужно выйти из detached HEAD в обычную ветку:
+
+@code{.sh}
+git -C lib/templates fetch origin
+git -C lib/templates switch -c feat/<имя> origin/master
+@endcode
+
+Commit и ветка отправляются в удалённый репозиторий `templates`. Основной
+проект обновляет gitlink только после публикации итогового SHA, иначе коллеги
+и CI не смогут получить указанную ревизию.
+
+@section submodule_conflict Разрешение конфликта gitlink
+
+Если ветки основного проекта указывают на расходящиеся commits сабмодуля,
+выбирать `ours` или `theirs` наугад нельзя. Сначала определяются обе ссылки:
+
+@code{.sh}
+git ls-files -u lib/templates
+git -C lib/templates fetch origin
+git -C lib/templates log --oneline --graph --decorate --all
+@endcode
+
+Оба commit объединяются и тестируются в отдельной ветке репозитория
+`templates`. После публикации общего commit конфликт завершается в основном
+проекте:
+
+@code{.sh}
+git -C lib/templates switch --detach <итоговый-sha>
+git add lib/templates
+git diff --cached --submodule=log
+git merge --continue
+git submodule update --init --recursive
+@endcode
+
+`git add lib/templates` отмечает разрешённым gitlink. Удалять каталог или
+копировать в него файлы для разрешения конфликта не требуется.
+
+@section submodule_checklist Проверка перед merge request
+
+- итоговый commit `templates` опубликован;
+- `git -C lib/templates status` не показывает локальных изменений;
+- `git submodule status` не начинается с `+`, `-` или `U`;
+- `git diff --submodule=log` показывает ожидаемое обновление;
+- тесты библиотек, сборка основного проекта и проверка платы прошли;
+- изменения адаптеров и новый gitlink закоммичены в основном проекте.
+
+Полная инструкция с разбором всех трёх вариантов merge находится в
+`NEW_PROJECT.md`.
+*/