docs: Root README was updated

Author: cmath10

README.md

@@ -2,7 +2,7 @@
 
 [🌐 Translations](./docs/INDEX.md#readme) • [📜 Code of Conduct](./CODE_OF_CONDUCT.md)
 
-Tools for analyzing git history and creating new releases according to [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/).
+Monorepo with tools for analyzing git history and creating releases according to the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/).
 
 [![Tests Status](https://github.com/modulify/conventional/actions/workflows/tests.yml/badge.svg)](https://github.com/modulify/conventional/actions)
 [![codecov](https://codecov.io/gh/modulify/conventional/branch/main/graph/badge.svg)](https://codecov.io/gh/modulify/conventional)
@@ -12,8 +12,47 @@ Tools for analyzing git history and creating new releases according to [conventi
 - [`@modulify/conventional-git`](./packages/conventional-git) — Thin wrapper over git with conventional-commit parsing and semantic tag helpers.
 - [`@modulify/conventional-bump`](./packages/conventional-bump) — Semantic-release helper that recommends the next version (major/minor/patch).
 - [`@modulify/conventional-changelog`](./packages/conventional-changelog) — Generate a changelog from your git history using Nunjucks templates.
+- [`@modulify/conventional-release`](./packages/conventional-release) — Library-first release orchestration package with a config-driven CLI.
 
-## Usage example
+## High-level release flow
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+const result = await run()
+
+if (!result.changed) {
+  console.log('No changes since last release')
+} else {
+  for (const slice of result.slices) {
+    if (!slice.changed) continue
+    console.log(slice.id, slice.nextVersion, slice.tag)
+  }
+}
+```
+
+The `@modulify/conventional-release` package combines:
+- version recommendation from `@modulify/conventional-bump`
+- changelog writing from `@modulify/conventional-changelog`
+- manifest updates
+- release commit and tag creation
+
+It also ships the `conventional-release` binary, so a consumer project can use:
+
+```json
+{
+  "scripts": {
+    "release": "conventional-release",
+    "release:dry": "conventional-release --dry"
+  }
+}
+```
+
+See the package README for the full API and CLI reference: [`@modulify/conventional-release`](./packages/conventional-release/README.md)
+
+## Low-level composition
+
+If you want to build your own release flow, the lower-level packages can still be used directly:
 
 ```ts
 import { Client } from '@modulify/conventional-git'
@@ -24,20 +63,45 @@ import semver from 'semver'
 const git = new Client()
 const advisor = new ReleaseAdvisor({ git })
 
-// 1. Get current version and recommend next one
 const currentVersion = await git.version() ?? '0.0.0'
 const recommendation = await advisor.advise({
   preMajor: semver.lt(currentVersion, '1.0.0')
 })
 
 if (recommendation) {
   const nextVersion = semver.inc(currentVersion, recommendation.type)
-
-  // 2. Generate and write changelog
   const write = createWrite({ git, file: 'CHANGELOG.md' })
-  await write(nextVersion)
 
-  // 3. You can now update package.json, commit and tag
+  await write(nextVersion)
   console.log(`Next release: ${nextVersion}`)
 }
 ```
+
+## Why this exists
+
+The project did not start as an abstract experiment. It grew out of a practical need to work with deeply nested workspace trees, including repositories with two or three levels of nesting, where most release tools on the market still assume a flat or near-flat monorepo layout.
+
+## Repository development
+
+Local setup:
+
+```bash
+make .yarnrc.yml
+yarn install
+```
+
+Useful commands:
+
+```bash
+make test
+make test-coverage
+make build
+make typecheck
+make eslint
+```
+
+Release preview for this repository:
+
+```bash
+yarn release:dry
+```

docs/ru/README.md

@@ -1,8 +1,8 @@
 # Conventional commits toolkit
 
-[🌐 Translations](../../docs/INDEX.md#readme)
+[🌐 Translations](../../docs/INDEX.md#readme) • [📜 Code of Conduct](../../CODE_OF_CONDUCT.md)
 
-Набор инструментов для анализа истории git и создания новых релизов в соответствии со [спецификацией conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
+Монорепозиторий с инструментами для анализа истории git и создания релизов в соответствии со [спецификацией Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 [![Tests Status](https://github.com/modulify/conventional/actions/workflows/tests.yml/badge.svg)](https://github.com/modulify/conventional/actions)
 [![codecov](https://codecov.io/gh/modulify/conventional/branch/main/graph/badge.svg)](https://codecov.io/gh/modulify/conventional)
@@ -12,8 +12,47 @@
 - [`@modulify/conventional-git`](../../packages/conventional-git) — Тонкая обертка над git с парсингом conventional-коммитов и помощниками для семантических тегов.
 - [`@modulify/conventional-bump`](../../packages/conventional-bump) — Помощник для семантических релизов, который рекомендует следующую версию (major/minor/patch).
 - [`@modulify/conventional-changelog`](../../packages/conventional-changelog) — Генерация чейнджлога из истории git с использованием шаблонов Nunjucks.
+- [`@modulify/conventional-release`](../../packages/conventional-release) — Library-first пакет для оркестрации релизов с конфигурируемым CLI.
 
-## Пример использования
+## Высокоуровневый release flow
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+const result = await run()
+
+if (!result.changed) {
+  console.log('Нет изменений с прошлого релиза')
+} else {
+  for (const slice of result.slices) {
+    if (!slice.changed) continue
+    console.log(slice.id, slice.nextVersion, slice.tag)
+  }
+}
+```
+
+Пакет `@modulify/conventional-release` объединяет:
+- рекомендации по версии из `@modulify/conventional-bump`
+- запись changelog из `@modulify/conventional-changelog`
+- обновление манифестов пакетов
+- создание release-коммита и тегов
+
+Он также поставляет бинарник `conventional-release`, поэтому в потребляющем проекте можно использовать:
+
+```json
+{
+  "scripts": {
+    "release": "conventional-release",
+    "release:dry": "conventional-release --dry"
+  }
+}
+```
+
+Полное описание API и CLI находится в README пакета: [`@modulify/conventional-release`](../../packages/conventional-release/README.md)
+
+## Низкоуровневая композиция
+
+Если нужен собственный release flow, низкоуровневые пакеты по-прежнему можно использовать напрямую:
 
 ```ts
 import { Client } from '@modulify/conventional-git'
@@ -24,20 +63,45 @@ import semver from 'semver'
 const git = new Client()
 const advisor = new ReleaseAdvisor({ git })
 
-// 1. Получение текущей версии и рекомендации следующей
 const currentVersion = await git.version() ?? '0.0.0'
 const recommendation = await advisor.advise({
   preMajor: semver.lt(currentVersion, '1.0.0')
 })
 
 if (recommendation) {
   const nextVersion = semver.inc(currentVersion, recommendation.type)
-
-  // 2. Генерация и запись чейнджлога
   const write = createWrite({ git, file: 'CHANGELOG.md' })
-  await write(nextVersion)
 
-  // 3. Теперь вы можете обновить package.json, закомитить и создать тег
+  await write(nextVersion)
   console.log(`Следующий релиз: ${nextVersion}`)
 }
 ```
+
+## Почему проект появился
+
+Проект возник не как абстрактный эксперимент, а из практической потребности работать с глубоко вложенными деревьями workspaces, включая репозитории с двумя или тремя уровнями вложенности, тогда как большинство release-инструментов на рынке до сих пор предполагают плоскую или почти плоскую монорепу.
+
+## Разработка репозитория
+
+Локальная подготовка:
+
+```bash
+make .yarnrc.yml
+yarn install
+```
+
+Полезные команды:
+
+```bash
+make test
+make test-coverage
+make build
+make typecheck
+make eslint
+```
+
+Предпросмотр релиза для этого репозитория:
+
+```bash
+yarn release:dry
+```