Docs: add project catalog and validation

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Начало любой новой сессии
 
-Первым прочитать `START_HERE.md`, затем `docs/CODEX_HANDOFF.md`.
+Первым прочитать `START_HERE.md`, затем `docs/CODEX_HANDOFF.md`. Для навигации по остальным материалам использовать `docs/README.md`, а для карты каталогов и модулей — `docs/PROJECT_CATALOG.md`.
 
 Новый чат, Codex Work или другой агент не должен опираться на память предыдущей сессии или предполагать состояние проекта. Перед изменениями нужно прочитать фактические файлы, ветки, Pull Request, issues, tags, Releases и GitHub Actions.
 
@@ -154,4 +154,4 @@
 
 ## English summary
 
-Read `START_HERE.md` and `docs/CODEX_HANDOFF.md` first, then verify the actual GitHub state. Keep calculation logic pure, derive backs from validated fronts, reject underproduction, preserve every feasible alternative inside the stated search scope, and never claim global completeness for a bounded solver. Use feature branches, exact-head PR checks, factual Chromium evidence, immutable release checkpoints, and immediate uNews publication assets.
+Read `START_HERE.md` and `docs/CODEX_HANDOFF.md` first, use `docs/README.md` as the documentation index and `docs/PROJECT_CATALOG.md` as the repository map, then verify the actual GitHub state. Keep calculation logic pure, derive backs from validated fronts, reject underproduction, preserve every feasible alternative inside the stated search scope, and never claim global completeness for a bounded solver. Use feature branches, exact-head PR checks, factual Chromium evidence, immutable release checkpoints, and immediate uNews publication assets.

CONTRIBUTING.md

@@ -25,6 +25,7 @@
 <li>новые параметры добавляются в конфигурацию;</li>
 <li>производственные формулы не меняются без объяснения;</li>
 <li>недопечатка и неправильный оборот недопустимы;</li>
+<li>новые документы добавляются в <code>docs/README.md</code>, а локальные ссылки проверяются командой <code>npm run check:docs</code>;</li>
 <li>изменения должны сопровождаться тестами.</li>
 </ul>
 
@@ -52,6 +53,7 @@
 <li>new settings belong in the central configuration;</li>
 <li>production formulas must not change without explanation;</li>
 <li>underproduction and invalid back forms are prohibited;</li>
+<li>new documents must be listed in <code>docs/README.md</code>, and local links must pass <code>npm run check:docs</code>;</li>
 <li>changes should include appropriate tests.</li>
 </ul>
 

README.md

@@ -3,7 +3,7 @@
 <p align="center"><strong>Расчёт офсетных монтажей · Offset Imposition Planner</strong></p>
 <p align="center"><strong>Version checkpoint / Версия проекта: 0.7.0-alpha.5</strong></p>
 <p align="center"><strong>M7.5 · пользовательские production plans, выбор, экспорт и приоритеты</strong></p>
-<p align="center"><strong><a href="START_HERE.md">Начать здесь / Start here</a> · <a href="docs/CODEX_HANDOFF.md">Передача в Codex / Codex handoff</a></strong></p>
+<p align="center"><strong><a href="START_HERE.md">Начать здесь / Start here</a> · <a href="docs/README.md">Документация / Documentation</a> · <a href="docs/PROJECT_CATALOG.md">Каталог проекта / Project catalog</a></strong></p>
 
 ## Назначение
 
@@ -184,6 +184,8 @@ uImposition — статический браузерный калькулято
 
 ## Документация
 
+- [Полный каталог документации](docs/README.md)
+- [Карта каталогов и модулей проекта](docs/PROJECT_CATALOG.md)
 - [Начать здесь](START_HERE.md)
 - [Codex handoff](docs/CODEX_HANDOFF.md)
 - [Текущее состояние](docs/CURRENT_STATE.md)

START_HERE.md

@@ -14,6 +14,8 @@
 - publication merge commit: `546f637a25b51f72706ebbe7346acb2df9819af8`;
 - следующий функциональный milestone: **M7.6 / `0.7.0-alpha.6`**;
 - основной документ передачи в Codex: `docs/CODEX_HANDOFF.md`;
+- полный каталог документации: `docs/README.md`;
+- карта каталогов и модулей: `docs/PROJECT_CATALOG.md`;
 - полный актуальный остаток: `docs/REMAINING_WORK.md`.
 
 Последние объединённые функциональные PR:
@@ -31,20 +33,21 @@ PR `#46` прошёл `173/173` теста, полный Chromium/PDF workflow 
 1. `AGENTS.md`;
 2. `START_HERE.md`;
 3. `docs/CODEX_HANDOFF.md`;
-4. `VERSION.json`, `VERSION.md`, `CHANGELOG.md`;
-5. `docs/CURRENT_STATE.md`;
-6. `docs/REMAINING_WORK.md`;
-7. `docs/TECHNICAL_SPECIFICATION_RU.md`;
-8. `docs/ARCHITECTURE.md`;
-9. `docs/M7_4_WORK_AND_TURN.md`;
-10. `docs/M7_5_USER_UNIFORM_PRODUCTION_PLANS.md`;
-11. `docs/M7_5_USER_PLAN_SELECTION_EXPORT.md`;
-12. `docs/M7_5_OBJECTIVE_PRIORITY_EDITOR.md`;
-13. `docs/PRODUCTION_COSTING.md`;
-14. `docs/TEST_PLAN.md`;
-15. `docs/GITHUB_ONLY_DEVELOPMENT.md`;
-16. `docs/VERSIONING.md`;
-17. последние PR, Actions, branches, tags, Releases и issues.
+4. `docs/README.md` и `docs/PROJECT_CATALOG.md`;
+5. `VERSION.json`, `VERSION.md`, `CHANGELOG.md`;
+6. `docs/CURRENT_STATE.md`;
+7. `docs/REMAINING_WORK.md`;
+8. `docs/TECHNICAL_SPECIFICATION_RU.md`;
+9. `docs/ARCHITECTURE.md`;
+10. `docs/M7_4_WORK_AND_TURN.md`;
+11. `docs/M7_5_USER_UNIFORM_PRODUCTION_PLANS.md`;
+12. `docs/M7_5_USER_PLAN_SELECTION_EXPORT.md`;
+13. `docs/M7_5_OBJECTIVE_PRIORITY_EDITOR.md`;
+14. `docs/PRODUCTION_COSTING.md`;
+15. `docs/TEST_PLAN.md`;
+16. `docs/GITHUB_ONLY_DEVELOPMENT.md`;
+17. `docs/VERSIONING.md`;
+18. последние PR, Actions, branches, tags, Releases и issues.
 
 ## Что уже работает
 

docs/CODEX_HANDOFF.md

@@ -455,4 +455,4 @@ Codex должен сообщить:
 
 ## English operational summary
 
-Start from `main` commit `009451cce94d5cde05ee72305f30447aa65a646c`. The published checkpoint is still `0.7.0-alpha.4`, while `main` contains unreleased M7.5 user-plan generation, explicit selection/export, and an accessible objective-priority editor. First publish a complete `0.7.0-alpha.5` checkpoint. Then implement M7.6 as a compact lossless comparison table before expanding plan families, general work-and-turn search, mixed-format packing, per-row order parameters, persistence, profitability, and heavy-search workers. Never hide feasible alternatives, never accept underproduction, and never claim global completeness outside an explicitly bounded search space.
+The verified functional M7.5 baseline is PR `#46` at merge commit `009451cce94d5cde05ee72305f30447aa65a646c`. M7.5 is published as prerelease `0.7.0-alpha.5`; its immutable release commit is `195d6496a291095a69cc9089a64154561ffbb1fa`, while later publication and documentation commits remain on `main`. Verify the live `main` head before changing files. The next functional milestone is M7.6: begin with a pure, lossless comparison-table model and tests before UI work or any search-space expansion. Never hide feasible alternatives, never accept underproduction, and never claim global completeness outside an explicitly bounded search space.

docs/PROJECT_CATALOG.md

@@ -0,0 +1,224 @@
+# Каталог проекта uImposition / Project catalog
+
+Последняя структурная сверка: **27 июля 2026**, checkpoint `0.7.0-alpha.5`.
+
+Этот документ объясняет назначение каталогов и активных групп файлов. Он не заменяет [`ARCHITECTURE.md`](ARCHITECTURE.md): архитектура описывает зависимости и поток расчёта, а каталог отвечает на вопрос «где что лежит и куда добавлять новое».
+
+## 1. Корень репозитория
+
+| Путь | Назначение |
+|---|---|
+| `index.html` | Основная страница GitHub Pages и стабильные DOM anchors |
+| `styles.css` | Базовые стили страницы |
+| `m3.css` … `m7-*.css`, `user-*.css` | Стили milestone- и feature-панелей, подключаемые соответствующими UI-модулями |
+| `decision-profile-demo.html` | Изолированная демонстрация decision profile |
+| `site.js` | Вспомогательный ранний browser script; текущий `index.html` его не загружает |
+| `VERSION.json`, `VERSION.md`, `CHANGELOG.md` | Версия, человекочитаемый checkpoint и история изменений |
+| `README.md`, `START_HERE.md`, `AGENTS.md` | Публичное описание, точка входа и обязательные правила агента |
+| `CONTRIBUTING.md`, `LICENSE.md` | Участие в проекте и лицензирование |
+| `package.json` | Node-команды проверок; runtime сайта не требует build step |
+
+Root CSS пока не переносится массово: пути динамически подключаются из UI-модулей и покрыты Chromium-сценариями. Возможная будущая консолидация стилей должна быть отдельным UI/architecture patch.
+
+## 2. Основные каталоги
+
+| Каталог | Что хранится | Правило |
+|---|---|---|
+| `src/` | Production ES modules и UI coordinators | Расчётная логика остаётся чистой и не прячется в DOM |
+| `tests/` | Node unit/integration/regression tests | Имя теста соответствует модулю или milestone |
+| `data/` | Контрольные и regression fixtures | Fixture не выдаётся за automatic solver |
+| `tools/` | Release, documentation, screenshot и PDF tooling | Инструменты не меняют production-формулы |
+| `docs/` | Текущие, нормативные, milestone и исторические документы | Полный индекс находится в [`README.md`](README.md) |
+| `docs/codex-tasks/` | Полные задания и completion records для передачи сессий | Не использовать для коротких временных заметок |
+| `news/` | Patchnotes и реальные release images | Один release — свой текст и своё изображение |
+| `archive/development/` | Постоянные evidence-пакеты опубликованных версий | Не переписывать задним числом |
+| `.github/workflows/` | Quality, Chromium/PDF, uNews и release automation | PR объединяется только после exact-head checks |
+
+## 3. Карта `src/`
+
+### Configuration и ввод
+
+```text
+config.js
+config.example.js
+geometry.js
+orders.js
+orientation.js
+print-specification.js
+```
+
+Здесь находятся presets/limits, лист и печатная область, строки заказов, направления и спецификация печати.
+
+### Лицо, оборот, кандидаты и validation
+
+```text
+front-layout.js
+back-layout.js
+imposition-validation.js
+imposition-candidate.js
+candidate-generator.js
+imposition-distribution.js
+mixed-format-layout.js
+paper-minimizer.js
+```
+
+`mixed-format-layout.js` проверяет переданную раскладку и не является automatic packing solver. Оборот создаётся только из лица.
+
+### Production, стоимость и метрики
+
+```text
+production-metrics.js
+production-validation.js
+production-report.js
+production-cost.js
+production-solution-metrics.js
+solution-metrics.js
+paper-solution-metrics.js
+```
+
+Layout-формы и цветовые пластины остаются разными метриками. Отсутствующая цена не становится нулём.
+
+### Решения и каталог вариантов
+
+```text
+optimization-objectives.js
+decision-profile.js
+pareto-alternatives.js
+pareto-display-set.js
+feasible-solution-catalog.js
+production-alternative-set.js
+alternative-explanations.js
+alternatives-runtime.js
+alternatives-controller.js
+```
+
+Исходный каталог остаётся lossless; filtering, Pareto и recommendation являются представлением и аннотациями.
+
+### Пользовательский M7.5 pipeline
+
+```text
+user-uniform-production-plans.js
+user-production-plans-runtime.js
+user-objective-priority.js
+user-production-plans-ui.js
+user-objective-priority-ui.js
+user-production-plan-details-ui.js
+```
+
+Модель, runtime и UI разделены. Selection оператора не подменяется recommendation, а reranking не регенерирует планы.
+
+### Duplex и work-and-turn
+
+```text
+duplex-strategies.js
+work-and-turn-layout.js
+work-and-turn-control-case.js
+work-and-turn-runtime.js
+work-and-turn-ui.js
+```
+
+Текущий контур ограничен задокументированным симметричным контрольным случаем и не доказывает совместимость с конкретной машиной.
+
+### Представление и PDF
+
+```text
+paper-solution-view.js
+paper-solution-renderer.js
+production-report-renderer.js
+scheme-renderer.js
+pdf-document-model.js
+pdf-binary.js
+pdf-scheme-renderer.js
+pdf-report-renderer.js
+pdf-export-ui.js
+pricing-ui.js
+alternatives-ui.js
+app.js
+```
+
+Renderer получает готовую проверенную модель и не пересчитывает производственные формулы. `app.js` остаётся DOM-координатором.
+
+### Исторические demo entrypoints
+
+```text
+m3-demo.js
+m7-decision-demo.js
+```
+
+Эти модули поддерживают демонстрационные и regression-контуры. Удаление или объединение требует отдельной проверки их HTML/scenario consumers.
+
+## 4. Тесты и fixtures
+
+`tests/` сгруппирован по ответственности:
+
+- geometry/orders/front-back;
+- M4 production report;
+- M5 PDF model, writer и renderers;
+- M6 candidates и paper minimizer;
+- M7 objectives, pricing, Pareto и alternatives;
+- user plan generation, runtime, selection/export и objective persistence;
+- work-and-turn;
+- production regression fixtures.
+
+`data/` содержит:
+
+- `control-case.json` — основной исторический контрольный набор;
+- `control-layout-m3.json` — контрольная раскладка M3;
+- `m7-decision-cases.json` — decision fixtures;
+- `production-regression-cases.json` — производственные regression cases.
+
+Команда полного source/unit контроля:
+
+```text
+npm run check
+```
+
+## 5. Automation
+
+### GitHub Actions
+
+| Workflow | Назначение |
+|---|---|
+| `quality.yml` | Source, documentation и Node tests |
+| `capture-screenshots.yml` | Real Chromium, desktop/mobile screenshots, PDF download, `pdfinfo` и Poppler |
+| `validate-unews.yml` | Проверка patchnote и очереди публикации |
+| `prepare-release-news.yml` | Сбор focused release evidence и manifest |
+| `publish-version-release.yml` | Recovery branch, immutable tag и GitHub Release/prerelease |
+
+### Локальные инструменты
+
+| Путь | Назначение |
+|---|---|
+| `tools/docs/check-docs.mjs` | Локальные Markdown-ссылки и полнота каталога документации |
+| `tools/screenshots/` | Playwright scenarios, capture manifest и подготовка artifacts |
+| `tools/news/prepare-release.mjs` | Patchnote, evidence archive, hashes и release manifest |
+
+## 6. Releases, news и история
+
+- `news/README.md` задаёт формат patchnote.
+- `news/*.{md,png,jpg}` хранит опубликованный текст и focused image конкретной версии.
+- `archive/development/{version}/release.json` хранит manifest.
+- Evidence ZIP и SHA-256 принадлежат конкретному immutable checkpoint.
+- Старые milestone/evidence документы индексируются в [`docs/README.md`](README.md), но не становятся текущими инструкциями.
+
+## 7. Куда добавлять новый файл
+
+| Новый материал | Правильное место |
+|---|---|
+| Чистая расчётная модель | `src/{responsibility}.js` + соответствующий `tests/*.test.js` |
+| DOM/UI renderer | отдельный `src/*-ui.js` или `src/*-renderer.js`; стили — связанный CSS |
+| Fixture | `data/` с явным описанием границы |
+| Chromium scenario | `tools/screenshots/scenarios/` |
+| Текущее состояние | существующий `CURRENT_STATE.md`, `REMAINING_WORK.md` или handoff |
+| Устойчивое правило/справочник | отдельный нормативный файл в `docs/` и запись в `docs/README.md` |
+| Полное задание передачи | `docs/codex-tasks/` |
+| Release note | `news/` |
+| Immutable release evidence | `archive/development/{version}/` и GitHub Release assets |
+
+Не создавать новый документ, если достаточно обновить существующий источник истины. Не переносить и не удалять исторические файлы массово без отдельного решения владельца.
+
+---
+
+## English summary
+
+This catalog maps repository locations to their responsibilities and file-placement rules. Production logic belongs in pure `src/` modules with matching tests; UI stays separate; fixtures remain explicit; documentation is indexed by status; news and release evidence are version-specific and immutable; and historical files are retained until the owner approves a separate archive migration.