This is not canonical documentation. The canon — the source of truth about system behaviour — lives in VISION.md, ARCHITECTURE-V6.md, OWNERSHIP-MAP.md, RULES-CODDING-DEVOPS.md, WORKFLOW-ARCHITECTURE.md at the repo root. The manuals/ folder describes how to use the already-built Axon platform: what each role does, which options exist in every Console section and what they do, how to walk through the create / configure / run flow for a given process.
Whenever a manual disagrees with the canon — the canon wins, and the manual is considered stale and must be fixed.
🇬🇧 English is the default language of this site. Русский — use the language selector in the header. Rendered with Material for MkDocs (see Material-for-MkDocs.md at the repo root).
Running processes, working with cases, conversations, monitoring own runs
reviewer
Approvals: what to approve, how, what to look at
read_only
Reading dashboards, statuses, audit
engineer / "architect"
Where the "code ↔ Console" boundary runs: what is written in modules/ and git, what is configured in the UI. This is a persona, not an RBAC role — it does not exist in core/models/auth.py; for Console actions (e.g. publish_definition) it needs an ordinary manager+ role
Every manual states audience: in its frontmatter — who it is primarily addressed to. If a manual describes a programmer's work, add the engineer tag and a dedicated section/subsection "what's done in code vs in Console" (see the example in Connectors-Credentials.md §2.1).
Canon = source of truth about behaviour. If a feature works differently from what the manual says, that's a bug in the manual (or a regression in the system — then fix the system).
Manuals = the operational layer. They do not introduce new rules, do not design architecture, do not contain secrets or internal implementation detail beyond what a user needs.
A manual's owner = the feature's owner. The OWNERSHIP-MAP.md zone that owns the described feature is responsible for keeping the manual current. Change a feature's behaviour in a PR — update its manual in the same PR. By analogy with VISION.md invariant 8 ("code without a test is unprotected tissue"): a feature without an updated manual is undocumented tissue.
Deletion is a virtue (VISION.md invariant 6) applies to manuals too: dropped a layer/option — drop the section about it. Don't pad the manual for volume.
Transparency (invariant 9): a manual explains what and why at the operator's level, but does not duplicate the internal implementation — that's what ARCHITECTURE-V6.md and the code are for.
Languages. Site default — EN; RU — second language (selector in the header). The team's working language is Russian (.claude/CLAUDE.md rule): a manual is often written in RU first, then translated. Every manual exists in both locales (see §5). Technical identifiers (connector_key, credential:create, WorkflowDefinition, command names, env vars) are identical in both locales, in Latin script.
One manual = one file per locale.manuals/en/<Topic-Name>.md + manuals/ru/<Topic-Name>.md. Name — TitleCase-With-Dashes.md (same in both folders). Site navigation comes from nav: in mkdocs.yml; the human-readable catalog is §6 here (they must match).
Frontmatter is mandatory (see _meta/_TEMPLATE.en.md / _meta/_TEMPLATE.ru.md): title, audience, status (draft / review / stable), covers, canonical_refs, last_reviewed (per-locale). For an untranslated locale — add translation_status: pending.
The manual structure is fixed — the same 10 sections as in _meta/_TEMPLATE.*. A section may be left almost empty with a "— not in this feature" note, but the order and headings don't change: this makes manuals predictable and indexable.
Every claim about RBAC / commands / behaviour is traceable. Cite code (file:line; use plain code rather than a markdown link pointing outside docs_dir — otherwise mkdocs build --strict fails) or canon (ARCHITECTURE-V6.md §11, CONCEPT-*.md §X). Don't invent permissions, roles, options, command names.
The Feynman test. The "What it is and why" section must explain the gist in 60 seconds. If you can't — the feature is too complex or you didn't understand it; figure it out before writing.
Keep screenshots and option lists. For UI sections — list every button / field / toggle / column and what it does (not "and other settings"). Screenshots — in manuals/assets/<manual-slug>/ (shared by both locales; links ../assets/...), create the folder as needed.
A role on every step. In step-by-step flows, state for every step who performs it and which permission gates it.
Cross-link within your locale, don't duplicate. If a topic is covered by another manual — link to it ([Foo.md](Foo.md) — within the same locale folder), don't rewrite. Don't make cross-locale links — use the header language selector to switch languages. Content duplication between manuals is an autoimmune disease (by analogy with tests).
Bump last_reviewed on every substantive edit (per locale). A manual not reviewed for more than one release is a candidate for review status.
Layout: manuals/en/ (default language, built at the site root) + manuals/ru/ (built at /ru/) — mirror trees. Plugin — mkdocs-static-i18n (docs_structure: folder, fallback_to_default: true).
Every manual must have a file in manuals/en/ — otherwise, with EN as default, there is nothing to fall back to. For a not-yet-translated manual the EN file is a thin stub: frontmatter (status: draft, translation_status: pending) + an admonition "English translation pending — use the language selector → Русский". For draft skeletons (content is TODO anyway) that's enough.
A translation does not block merging a RU edit and vice versa — it's a separate follow-up PR. Translation lag is visible: "translation pending" banner + per-locale status.
_meta/_TEMPLATE.ru.md and _meta/_TEMPLATE.en.md — templates (excluded from the site build via exclude_docs).
Statuses: ✅ stable · 🟡 review · 🚧 draft (skeleton file exists) · ⬜ planned (no file yet). EN translation: full for stable manuals; for draft — a stub with a banner.
All roles (owner/admin/manager/operator/reviewer/read_only/system), the full permission × role matrix, instance vs project scope, ActorContext, breakglass, how they're assigned
Definition vs Workflow (run) vs Case vs Template/Catalog; the Step model and step_type taxonomy; 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 patterns
Fill in the frontmatter (audience, canonical_refs — which canon sections you rely on). For an untranslated locale — leave a stub with the translation banner (translation_status: pending).
Walk through all 10 sections. Mark empty ones "— not in this feature", don't delete headings.
Add a row to the §6 catalog here and an entry to nav: in mkdocs.yml — they must match.
Check against the §3 checklist; run mkdocs build --strict (§8) — it catches broken links and nav gaps. The manual's PR reviewer = the owner of the relevant OWNERSHIP-MAP.md zone.
Change a feature's behaviour in code — fix its manual in the same PR and bump last_reviewed.
# from the repo rootpipinstall-rdocker/docs/requirements.txt
mkdocsserve# http://127.0.0.1:8000 — live reload, language selector, dark thememkdocsbuild--strict# build into ./site (gitignored); --strict makes warnings (broken links, nav gaps) fatal
Deploying as a service (docs in docker-compose.docs.yml, nginx behind Traefik+auth) — see Material-for-MkDocs.md §7. Stand up the container once enough manuals exist; until then mkdocs serve locally is enough.