git:20261014.06158d8 to git:20261018.bc36d0a

45 added, 3 removed. Audit A to A.

---

description: The Russian documentation tree (docs/ru), what moves with an English page, the stamp, and the writing rules for Russian and English documentation

globs: docs/**, internal/config/config.schema.json, internal/docs/**, internal/docsgen/**

alwaysApply: false

---

# Documentation in two languages

The documentation exists in English (`docs/<group>/<page>.md`) and in Russian

(`docs/ru/<group>/<page>.md`, the same name and the same path under `docs/ru/`). The English page is

the source; the Russian page is its translation and moves with it in the same pull request. Every

surface shows the language it already knows the person uses (the web UI's locale, the terminal's

locale), so a page that is current in one language and stale in the other is a bug the reader sees.

## What moves together

| You change | You also change |

| --- | --- |

| an English page | its Russian page, then restamp it (below) |

| a page added to `docs/nav.yaml` | the Russian page and its entry in `docs/ru/nav.yaml` |

| a title or summary in `docs/nav.yaml` | the entry in `docs/ru/nav.yaml`: `title` and `summary` translated, `en:` set to the new English text |

| a `description` in `internal/config/config.schema.json` | its entry in `docs/ru/config-descriptions.yaml`: `en` set to the new English text, `ru` translated |

| the introduction of `docs/README.md` | the introduction of `docs/ru/README.md`, then restamp it |

| a page removed from `docs/nav.yaml` or moved | its Russian page removed or moved to the same new path, and its entry in `docs/ru/nav.yaml` with it |

Not translated: `docs/plans/` (design records), `docs/assets/` (shared: a Russian page embeds the same

files), and the pages the map lists from the repository root (`CONTRIBUTING.md`, `DESIGN.md`,

`AGENTS.md`). The changelog is generated in both languages.

## A Russian page

- **Headings**: the same headings as the English page, in the same order and at the same levels.

Translate them; never add, drop, merge or split one. One address names a section in both languages

because the Russian heading at a position answers to the English heading's anchor. A page whose

English H1 is its title in `docs/nav.yaml` starts with its Russian title from `docs/ru/nav.yaml`.

- **Literal text stays literal**: code blocks, inline code, commands, flags, config keys, paths, file

names, identifiers, HTTP routes, model and product names, and program output are copied unchanged.

Comments inside code blocks stay as they are.

- **The web UI by its labels**: a control or a screen of the web UI is named the way the Russian

interface names it; look the English label up in `external/ui/src/ui/i18n/messages/en.ts` and take

the same key from `ru.ts`.

- **Links**: copy every link target as the English page writes it. `make docs` makes it right for the

translation's folder: a link to another page keeps its relative path and gets the anchor GitHub

gives the Russian heading (`../features/mcp.md#общие-серверы`); an image, a design record or a

repository file gets the one more `../` the deeper folder needs. A link already written that way is

left alone.

- **Generated blocks** keep their `` / ``

markers; `make docs` fills them.

- - **Captions**: the italic caption under a screenshot is translated; the screenshot is the English one.

+ - **Captions and alt text**: the italic caption under a screenshot and the alt text of every image

+ are translated; the image file is the English one. `make docs-check` reports an alt text of more

+ than one word with no Cyrillic letter in it.

- **The stamp**: the last line, ``, is the digest of the

English page the translation follows. docsgen writes it; never edit it by hand.

## Commands

```bash

make docs # both hubs, generated blocks, the Russian changelog, the links of docs/ru

make docs-check # what CI runs: both trees, the map, parity, stamps, links, typography

make docs-stamp PAGES="docs/ru/features/mcp.md" # after the Russian page says what the English one says

make docs-stamp PAGES="..." UNCHANGED=1 # the English change needs no translation (a fixed typo)

```

`make docs-check` reports a stale Russian page with the command that shows what changed in the

English page since the translation was stamped. Restamp a page only after its translation says what

- the English page says; a stamp over an untranslated change is a stale page CI cannot see, which is why

- the stamp refuses a page whose translation did not change since `HEAD` unless `UNCHANGED=1` says so.

+ the English page says and, for new or rewritten prose, has passed the cross-review below; a stamp

+ over an untranslated change is a stale page CI cannot see, which is why the stamp refuses a page

+ whose translation did not change since `HEAD` unless `UNCHANGED=1` says so.

The pre-commit hook reports a stale stamp as a warning; CI fails on it.

## Writing Russian

The reader is a person who installs and runs Coddy, often a developer, sometimes not. Write the way

a careful Russian-speaking engineer explains the program to a colleague: plain, exact, active. A

translation renders the meaning of the English sentence, not its word order. Run every draft through

the prose skills that **`AGENTS.md`** lists (*Prose skills*: stop-slop, humanizer-ru, ru-text, logika);

the typography below wins where one of them disagrees.

Typography and form (`make docs-check` enforces the dashes, the quotes and the horizontal rules outside code):

- a hyphen with spaces ` - ` instead of an em dash or an en dash, ranges as `10-15`;

- straight quotes `"..."`, never guillemets or curly quotes;

- no horizontal rules, and no emoji either (not checked: keep it by hand);

- a colon only to introduce a list; before a code block or a table end the sentence with a period;

- list items end with `;`, the last with `.`; keep a list a list and prose prose, as in the source;

- numbers in prose take a decimal comma (`1,5 МБ`), units in Russian (`КБ`, `МБ`, `мс`, `с`); values

inside code stay as written.

Wording:

- no calques: "является", "данный", "осуществлять", "в рамках", "производить" (as "to perform"),

"позволяет" where a direct verb fits, "при помощи", "на сегодняшний день";

- no stock phrases: "стоит отметить", "важно понимать", "таким образом", "не просто X, а Y",

"X - это Y, а не Z";

- no hedging where the English states a fact: write "Coddy делает", not "Coddy может делать";

- verbs over nouns: "сжимает контекст", not "осуществляет сжатие контекста";

- one term for one concept within a page and across pages (the glossary below); do not vary terms

for style;

- the reader is addressed as "вы" in lower case, instructions in the imperative ("запустите",

"откройте");

- the paired Russian wording rule holds: "агентный", never "агентский"; "субагент", never "сабагент";

"worktree", never a translation.

Glossary (English - Russian):

- agent - агент; agentic - агентный; subagent - субагент;

- session - сессия; conversation - диалог; chat (the web UI entity) - чат; turn - ход;

message - сообщение; transcript - транскрипт;

- prompt - промпт; system prompt - системный промпт; composer - поле ввода;

- tool - инструмент; tool call - вызов инструмента; tool result - результат инструмента;

- permission - разрешение; approval - одобрение; permission mode - режим разрешений;

- the modes Agent, Plan and Ask - режимы "Агент", "План" и "Чат" (the identifiers `agent`, `plan`,

`ask` stay in code);

- skill - скил; rule - правило; hook - хук; mention - упоминание;

- workspace - рабочая папка; background task - фоновая задача;

- scheduler - планировщик; job - задание; run (of a job or a task) - запуск;

- swarm - рой; node - узел; relay - релей; ring - кольцо;

- memory - память; compaction - сжатие контекста; context window - окно контекста;

- reasoning - рассуждение; reasoning level - уровень рассуждения;

- provider - провайдер; model - модель; environment - окружение; remote mode - удалённый режим;

- surface - интерфейс; console - консоль; web UI - веб-интерфейс; harness - харнес;

+ - stacked shell (the web UI below 1200 px, the rail turned into a top bar) - раскладка с верхней панелью;

- gateway - шлюз (Telegram gateway - Telegram-шлюз); bot - бот;

- trust - доверие; trust receipt - расписка; sandbox - песочница; loop guard - защита от зацикливания;

- endpoint - эндпоинт; route - маршрут; request - запрос; response - ответ; streaming - потоковая передача;

- configuration, config - конфигурация; config file - файл конфигурации; key (of the config) - ключ;

- release - релиз; build - сборка; binary - бинарник; build tag - тег сборки;

- pull request - пул-реквест; issue - issue; worktree - worktree; daemon - демон; service - сервис;

- page - страница; section - раздел; screenshot - скриншот; caption - подпись.

Names stay in Latin script: Coddy, MCP, ACP, ReAct, SSE, OpenAI, Telegram, GitHub, Docker, systemd,

the names of models, commands and files.

+ ## Cross-review of a translation

+ A translation an agent drafted reads like one even when every check passes: the English word order

+ kept, three clauses strung on participles and "а ещё", a hedge the English does not make, a term

+ that drifts from the glossary. `make docs-check` sees dashes, quotes and banned words, and the prose

+ skills are run by the agent that wrote the draft over its own sentences, so neither is a second

+ reader. New or rewritten Russian prose is read by reviewers who did not write it before it is

+ stamped.

+ It applies to a pull request that adds a Russian page or adds or rewrites Russian prose: a section,

+ a paragraph, a list item, a table cell that holds a sentence, a summary in `docs/ru/nav.yaml`, a

+ description in `docs/ru/config-descriptions.yaml`. A fixed typo, a copied key or path and a restamp

+ with `UNCHANGED=1` need no review.

+ 1. Write the brief into a file. For every changed passage it carries the English source and the

+ Russian text side by side, inline, so a reviewer needs no checkout; then the rules the text is

+ held to: the typography, the wording and the glossary of *Writing Russian*, the paired Russian

+ wording rule, and the Russian labels of the web UI controls the passages name (from `ru.ts`).

+ 2. Send it to `/crossreview` (bundled with Coddy; other agents install it from

+ [EvilFreelancer/crossreview](https://github.com/EvilFreelancer/crossreview)), or to another

+ quorum of at least three reviewers who stay blind to each other. Each finding names the passage,

+ quotes the Russian words and proposes a rewrite, and is one of four kinds:

+ - a sentence that reads as translated: English word order, a calque, a chain of clauses a Russian

+ writer would split, a word that says nothing;

+ - a term that differs from the glossary, or a control named otherwise than the interface names it;

+ - a meaning the Russian changes: a claim added, lost, weakened or hedged;

+ - typography the rules above forbid.

+ 3. Check every finding yourself against the English page and this rule, and decide alone. A rewrite

+ that changes the meaning, a term or a label is rejected however many reviewers propose it, and a

+ matter of taste is not a finding.

+ 4. Apply the confirmed rewrites and send the rewritten passages to a second round with a fresh brief,

+ never with the first round's answers. Stamp the page once a round confirms nothing about meaning,

+ terms, labels or a sentence that reads as translated; otherwise review what changed once more,

+ three rounds at most. A finding that undoes a rewrite an earlier round confirmed is rejected, and

+ after the third round whoever runs the review checks the last rewrites alone and stamps the page.

+ 5. The pull request description says the translation was cross-reviewed: the pages, the rounds, and

+ how many findings were confirmed and how many rejected.

## Writing English

The English pages follow `docs/contributing/documentation.md`. The same discipline applies: a hyphen

with spaces instead of an em dash, active voice with a named actor, specific statements instead of

vague ones, no filler ("It's worth noting", "Here's what"), no intensifiers (actually, really, very),

no "not X but Y" where a direct statement does. Write the English page so that it can be translated

sentence by sentence: one claim per sentence, the same term for the same thing.