Это не каноническая документация. Каноны — источник истины о поведении системы: VISION.md, ARCHITECTURE-V6.md, OWNERSHIP-MAP.md, RULES-CODDING-DEVOPS.md, WORKFLOW-ARCHITECTURE.md в корне репозитория. Папка manuals/ описывает, как пользоваться уже построенной платформой Axon: какая роль что делает, какие опции есть в каждом разделе Console и что они выполняют, как пройти флоу создания / настройки / запуска того или иного процесса.
При любом расхождении мануала с канонами — каноны главнее, а мануал считается устаревшим и подлежит правке.
🇬🇧 English is the default language of this site. Russian — переключатель языка в шапке. Rendered with Material for MkDocs (см. Material-for-MkDocs.md в корне репо).
Запуск процессов, работа с кейсами, конверсации, мониторинг своих run'ов
reviewer
Approvals: что approve'ить, как, на что смотреть
read_only
Чтение дашбордов, статусов, аудита
engineer / «architect» (программист)
Где проходит граница «код ↔ Console»: что пишется в modules/ и git, что настраивается в UI. Это персона, а не RBAC-роль — её нет в core/models/auth.py; для действий через Console (например publish_definition) ей нужна обычная роль manager+
Каждый мануал во frontmatter явно указывает audience: — кому он адресован в первую очередь. Если мануал описывает работу программиста — добавляй тег engineer и отдельный раздел/подраздел «что делается в коде, а что в Console» (см. пример в Connectors-Credentials.md §2.1).
Каноны = источник истины о поведении. Если фича работает не так, как написано в мануале, — баг в мануале (или регрессия в системе; тогда чиним систему).
Мануалы = операционный слой. Они не вводят новых правил, не проектируют архитектуру, не содержат секретов и внутренних деталей реализации сверх необходимого для пользователя.
Owner мануала = owner фичи. За актуальность мануала отвечает зона из OWNERSHIP-MAP.md, которой принадлежит описываемая фича. Меняешь поведение фичи в PR — обнови соответствующий мануал в том же PR. Аналогия с инвариантом 8 VISION.md («код без теста — незащищённая ткань»): фича без обновлённого мануала — недокументированная ткань.
Удаление — добродетель (VISION.md инвариант 6) распространяется и на мануалы: выкинули слой/опцию — выкинули и раздел про неё. Не наращивай мануал ради объёма.
Прозрачность (инвариант 9): мануал объясняет что и почему на уровне оператора, но не дублирует внутреннюю реализацию — для неё есть ARCHITECTURE-V6.md и код.
Языки. Сайт по умолчанию — EN; RU — второй язык (переключатель в шапке). Рабочий язык команды — русский (правило .claude/CLAUDE.md): мануал часто пишется на RU первым, затем переводится. Каждый мануал существует в обеих локалях (см. §5). Технические идентификаторы (connector_key, credential:create, WorkflowDefinition, имена команд, env-vars) — одинаковы в обеих локалях, латиницей.
Файл = один мануал, две локали.manuals/en/<Topic-Name>.md + manuals/ru/<Topic-Name>.md. Имя — TitleCase-With-Dashes.md (одинаковое в обеих папках). Навигация на сайте — из nav: в mkdocs.yml; человекочитаемый каталог — §5 этого файла (должны совпадать).
Frontmatter обязателен (см. _meta/_TEMPLATE.ru.md / _meta/_TEMPLATE.en.md): title, audience, status (draft / review / stable), covers, canonical_refs, last_reviewed (per-locale). Для непереведённой локали — дополнительно translation_status: pending.
Структура мануала фиксирована — те же 10 разделов, что в _meta/_TEMPLATE.*. Раздел можно оставить почти пустым с пометкой «— нет в этой фиче», но порядок и заголовки не меняются: это делает мануалы предсказуемыми и индексируемыми.
Каждое утверждение о RBAC / командах / поведении — прослеживаемо. Ссылайся на код (file:line, plain code без markdown-ссылки наружу из docs_dir — иначе mkdocs build --strict падает) или канон (ARCHITECTURE-V6.md §11, CONCEPT-*.md §X). Не выдумывай permissions, роли, опции, имена команд.
Тест Фейнмана. Раздел «Что это и зачем» обязан объяснять суть за 60 секунд. Если не получается — фича слишком сложна или ты её не понял; разберись прежде чем писать.
Скриншоты и списки опций сохраняй. Для UI-разделов — перечисляй каждую кнопку / поле / тоггл / колонку и что оно делает (а не «и другие настройки»). Скриншоты — в manuals/assets/<manual-slug>/ (общий для обеих локалей; ссылки ../assets/...), папку создаём по мере надобности.
Роль на каждом шаге. В пошаговых флоу у каждого шага указывай, кто его выполняет и каким permission это гейтится.
Cross-link внутри своей локали, не дублируй. Если тема покрыта другим мануалом — ссылайся ([Foo.md](Foo.md) — внутри той же локальной папки), а не переписывай. Кросс-локальные ссылки не делай — для перехода между языками есть переключатель в шапке. Дублирование контента между мануалами — аутоиммунное заболевание (по аналогии с тестами).
last_reviewed обновляй при каждой правке по существу (per-locale). Мануал, не пересмотренный больше одного релиза, — кандидат на статус review.
Раскладка: manuals/en/ (язык по умолчанию, билдится в корень сайта) + manuals/ru/ (билдится в /ru/) — зеркальные деревья. Плагин — mkdocs-static-i18n (docs_structure: folder, fallback_to_default: true).
Каждый мануал обязан иметь файл в manuals/en/ — иначе при EN-default нечему делать fallback. Для ещё не переведённого мануала EN-файл — тонкий стаб: frontmatter (status: draft, translation_status: pending) + admonition «English translation pending — use the language selector → Русский». Для draft-скелетов (содержание и так TODO) этого достаточно.
Перевод EN не блокирует мерж RU-правки и наоборот — это отдельный follow-up PR. Лаг перевода виден: баннер «translation pending» + статус per-locale.
_meta/_TEMPLATE.ru.md и _meta/_TEMPLATE.en.md — шаблоны (исключены из сборки сайта через exclude_docs).
Статусы: ✅ stable · 🟡 review · 🚧 draft (есть файл-скелет) · ⬜ planned (файла ещё нет). Перевод EN: полный — у stable-мануалов; у draft — стаб с баннером.
Все роли (owner/admin/manager/operator/reviewer/read_only/system), полная матрица permission × роль, instance vs project scope, ActorContext, breakglass, как назначаются
Definition vs Workflow (run) vs Case vs Template/Catalog; Step model и таксономия step_type; authoring vs runtime; publish (publish_definition); Run Wizard; pause/resume/cancel/retry/replan; binding profiles; execution_mode (leaf/graph/hybrid); SubFlows; collections & labels; Magic Box-паттерны
Скопируй _meta/_TEMPLATE.ru.md → manuals/ru/<Topic-Name>.md и _meta/_TEMPLATE.en.md → manuals/en/<Topic-Name>.md (одинаковое имя файла).
Заполни frontmatter (audience, canonical_refs — на какие разделы канонов опираешься). Для непереведённой EN-локали — оставь стаб с баннером перевода (translation_status: pending).
Пройдись по всем 10 разделам. Пустые помечай «— нет в этой фиче», заголовки не удаляй.
Добавь строку в каталог §6 этого файла и запись в nav: в mkdocs.yml — они должны совпадать.
Проверь по чеклисту §3; прогони mkdocs build --strict (§8) — он ловит битые ссылки и дыры в nav. PR-ревьюер мануала = owner соответствующей зоны OWNERSHIP-MAP.md.
Меняешь поведение фичи в коде — правишь её мануал в том же PR и обновляешь last_reviewed.
# из корня репозиторияpipinstall-rdocker/docs/requirements.txt
mkdocsserve# http://127.0.0.1:8000 — live-reload, переключатель языков, тёмная темаmkdocsbuild--strict# сборка в ./site (gitignored); --strict делает warning'и (битые ссылки, дыры nav) фатальными
Деплой как сервис (docs в docker-compose.docs.yml, nginx за Traefik+auth) — см. Material-for-MkDocs.md §7. Контейнер поднимаем, когда наберётся критическая масса мануалов; до этого достаточно mkdocs serve локально.