docs: добавлен AGENTS.md с правилами для агентов

- ссылка на CONTRIBUTING.md как основной источник правил
- операционные напоминания: язык, npm run docs, обновление конфигов, кеш

.vitepress/config.ts

@@ -21,8 +21,8 @@ const ruSidebar = [
     items: [
       { text: 'Настройка VS Code', link: '/applied/vscode' },
       { text: 'Структура проекта', link: '/applied/project-structure' },
-      { text: 'Компоненты', link: '/applied/components' },
+      { text: 'UI и компоненты', link: '/applied/components' },
-      { text: 'Page-level компоненты', link: '/applied/page-level' },
+      { text: 'Страницы (App Router)', link: '/applied/page-level' },
       { text: 'Шаблоны и генерация кода', link: '/applied/templates-generation' },
       { text: 'Стили', link: '/applied/styles' },
       { text: 'Изображения', link: '/applied/images-sprites' },

AGENTS.md

@@ -1,32 +1,9 @@
-# NextJS Style Guide — правила для агентов
+# Правила для агентов
 
-Это проект документации (VitePress). Агент является основным писателем контента в этом проекте — записывает, оформляет и редактирует материал по указаниям пользователя.
+При работе с документацией следовать правилам из CONTRIBUTING.md.
 
-## Документация
+- Язык документации и коммитов — русский.
-
+- После изменений в `.md`-файлах — запустить `npm run docs` для обновления RULES.md.
-### Tip-блоки со ссылками
+- При добавлении нового раздела — обновить сайдбар (`.vitepress/config.ts`)
-При создании или редактировании документации добавлять tip-блоки (`::: tip`)
+  и порядок файлов (`concat-md.js`).
-с ссылками на связанные разделы, где можно найти развёрнутое описание
+- Не коммитить `.vitepress/cache/`.
-процесса, действия или настройки.
-
-Формат:
-```
-::: tip Заголовок блока
-Описание — [Название раздела](/путь).
-:::
-```
-
-Заголовок обязателен — он должен кратко описывать о чём блок.
-Описание должно объяснять что найдёт читатель по ссылке.
-
-### Структура разделов
-- **Workflow** — порядок действий ("что делать и в каком порядке")
-- **Базовые правила** — стандарты и конвенции ("каким должен быть код")
-- **Прикладные разделы** — конфигурация и устройство конкретной области ("как это настроить и использовать")
-
-Не дублировать информацию между разделами — использовать ссылки.
-
-### Единообразие
-- Заголовок страницы (h1) совпадает с названием в sidebar.
-- Описание раздела (текст после h1) раскрывает смысл через "Как...".
-- Не описывать инструменты генерации в каждом разделе — ссылаться на прикладной раздел "Шаблоны и генерация кода".

CONTRIBUTING.md

@@ -0,0 +1,220 @@
+# Правила работы над документацией
+
+Мета-документ: как устроен проект, как писать и редактировать разделы.
+
+## О проекте
+
+Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.
+
+- Движок: VitePress
+- Языки: русский (основной), английский
+- Русская версия: `docs/ru/`
+- Английская версия: `docs/en/`
+
+## Команды
+
+| Команда | Что делает |
+|---------|-----------|
+| `npm run dev` | Локальный сервер разработки |
+| `npm run build` | Сборка статического сайта |
+| `npm run docs` | Генерация `generated/{lang}/RULES.md` — единый файл для AI-ассистентов |
+
+## Структура файлов
+
+```
+docs/
+├── ru/                          # Русская версия (основная)
+│   ├── index.md                 # Главная страница
+│   ├── workflow.md              # Workflow (единый файл)
+│   ├── basics/                  # Базовые правила
+│   │   ├── tech-stack.md
+│   │   ├── architecture.md
+│   │   ├── code-style.md
+│   │   ├── naming.md
+│   │   ├── documentation.md
+│   │   └── typing.md
+│   └── applied/                 # Прикладные разделы
+│       ├── vscode.md
+│       ├── project-structure.md
+│       ├── components.md
+│       ├── page-level.md
+│       ├── templates-generation.md
+│       ├── styles.md
+│       ├── images-sprites.md
+│       ├── svg-sprites.md
+│       ├── video.md
+│       ├── api.md
+│       ├── stores.md
+│       ├── hooks.md
+│       ├── fonts.md
+│       └── localization.md
+├── en/                          # Английская версия (зеркало ru/)
+.vitepress/
+├── config.ts                    # Конфигурация VitePress, сайдбары, локали
+generated/
+├── ru/RULES.md                  # Сгенерированный единый файл (ru)
+└── en/RULES.md                  # Сгенерированный единый файл (en)
+concat-md.js                     # Скрипт генерации RULES.md
+```
+
+### Добавление нового раздела
+
+1. Создать `.md`-файл в нужной папке (`basics/` или `applied/`).
+2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод).
+3. Добавить файл в массив `fileOrder` — `concat-md.js` (для генерации RULES.md).
+
+## Три типа документации
+
+### Workflow
+
+**Отвечает на вопрос:** «Что делать и в каком порядке?»
+
+Пошаговые инструкции. Описывает процесс, а не правила.
+Не содержит развёрнутых примеров кода — только минимальные команды и шаги.
+
+Живёт в одном файле `workflow.md`.
+
+### Базовые правила
+
+**Отвечает на вопрос:** «Каким должен быть любой код?»
+
+Универсальные стандарты, **не привязанные к конкретной области**.
+Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.
+
+Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.
+
+**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
+
+### Прикладные разделы
+
+**Отвечает на вопрос:** «Как работать с X?»
+
+Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.
+
+**Граница:** прикладной раздел не дублирует базовые правила.
+Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.
+
+## Структура прикладного раздела
+
+Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.
+
+```markdown
+# {Название}
+
+Одно-два предложения: что это за область, зачем она нужна.
+
+## Что нужно знать
+
+Контекст перед правилами: технологии, термины, принципы работы.
+Не правила — фундамент, без которого правила будут непонятны.
+
+## Структура
+
+Файловая организация: какие файлы создавать и куда класть.
+Обязательно — дерево файлов через code-block.
+
+## Правила
+
+Конкретные требования к реализации в этой области.
+Формат — маркированный или нумерованный список.
+Для неочевидных случаев — блоки «Хорошо / Плохо».
+
+## Именование
+
+Соглашения по именам, специфичные для этой области.
+Только то, что НЕ покрыто в базовом разделе «Именование».
+
+## Типизация
+
+Правила типизации, специфичные для этой области.
+Только то, что НЕ покрыто в базовом разделе «Типизация».
+
+## Документирование
+
+Что и как документировать в этой области.
+Только то, что НЕ покрыто в базовом разделе «Документирование».
+
+## Примеры
+
+Полноценные примеры кода.
+Каждый пример с путём к файлу и пояснениями.
+```
+
+### Порядок секций
+
+Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
+Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
+
+### Секции-расширения базовых правил
+
+«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.
+
+- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
+- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).
+
+Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.
+
+## Конвенции оформления
+
+### Frontmatter
+
+Каждый `.md`-файл начинается с YAML frontmatter:
+
+```yaml
+---
+title: Название раздела
+---
+```
+
+Значение `title` совпадает с текстом `h1`-заголовка в файле.
+
+### Заголовки
+
+- Один `h1` на файл — совпадает с `title` из frontmatter.
+- Сразу после `h1` — вводный абзац (одно-два предложения).
+- Основные секции — `h2`.
+- Подсекции внутри `h2` — `h3`.
+- `h4` не используется.
+
+### Примеры кода
+
+- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
+- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
+- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.
+
+### Блоки «Хорошо / Плохо»
+
+Используются для контрастного сравнения правильного и неправильного подхода.
+
+Формат:
+
+```markdown
+**Хорошо:**
+
+\`\`\`tsx
+// правильный код
+\`\`\`
+
+**Плохо:**
+
+\`\`\`tsx
+// неправильный код
+\`\`\`
+```
+
+### Таблицы
+
+Используются для структурированных перечислений: настройки, команды, соответствия.
+Формат — стандартный Markdown: `| Ключ | Описание |`.
+
+### Ссылки между разделами
+
+Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.
+
+## Принципы
+
+1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
+2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
+3. **Workflow vs правила.** Workflow описывает процесс (шаги). Правила описывают результат (каким должен быть код).
+4. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
+5. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.

docs/ru/applied/components.md

@@ -1,8 +1,8 @@
 ---
-title: Компоненты
+title: UI и компоненты
 ---
 
-# Компоненты
+# UI и компоненты
 
 Раздел описывает правила создания UI‑компонентов. Эти правила обязательны для всех слоёв FSD: `app`, `screens`, `layouts`, `widgets`, `features`, `entities`, `shared`.
 

docs/ru/applied/page-level.md

@@ -1,8 +1,8 @@
 ---
-title: Page-level компоненты
+title: Страницы (App Router)
 ---
 
-# Page-level компоненты
+# Страницы (App Router)
 
 Специальные файлы Next.js App Router, которые фреймворк использует по соглашению: `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`, `template.tsx`.
 

docs/ru/workflow.md

@@ -6,14 +6,6 @@ title: Workflow
 
 Порядок действий при разработке — от создания проекта до реализации фич.
 
-## Начало работы
-
-Подготовка окружения перед началом разработки.
-
-1. Открыть проект в VS Code.
-2. Установить рекомендуемые расширения (редактор предложит автоматически).
-3. Ознакомиться со стеком: Next.js (App Router), Mantine, Zustand, FSD.
-
 ## Создание проекта
 
 Инициализация нового проекта из готового шаблона.

generated/ru/RULES.md

@@ -944,7 +944,7 @@ src/
 Каждый элемент на своём слое, с публичным API и чёткими границами ответственности.
 
 <!-- /applied/components -->
-## Компоненты
+## UI и компоненты
 
 Раздел описывает правила создания UI‑компонентов. Эти правила обязательны для всех слоёв FSD: `app`, `screens`, `layouts`, `widgets`, `features`, `entities`, `shared`.
 
@@ -1031,7 +1031,7 @@ export { Container } from './container'
 Вложенные компоненты подчиняются тем же правилам по структуре, именованию и стилю (включая папку `styles/` для их стилей).
 
 <!-- /applied/page-level -->
-## Page-level компоненты
+## Страницы (App Router)
 
 Специальные файлы Next.js App Router, которые фреймворк использует по соглашению: `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`, `template.tsx`.