docs: переработать заголовки и описания разделов

- Зафиксированы новые правила в CONTRIBUTING.md: заголовок и описание
  как навигационный маркер, запреты, тесты и подходящие формы
- Описания во всех 26 разделах переписаны как короткий ответ на
  вопрос «когда сюда нужно?»
- Заголовки приведены к самодостаточному виду: SLM Design, SVG-спрайты,
  VS Code, Чистая установка Next.js, Источники данных, Создание
  проекта вручную, Стили, Алиасы импортов
- Описания добавлены в frontmatter (description) для согласованности
  с llms.txt и SEO
- Удалены навигационные ссылки сразу после описания
- Добавлен docs-overview.md — сводный обзор всех страниц
- Обновлён сайдбар: ссылка «Алиасы» → «Алиасы импортов»

.vitepress/config.ts

@@ -40,7 +40,7 @@ const sidebar = [
   {
     text: 'Настройка',
     items: [
-      { text: 'Алиасы', link: '/docs/setup/aliases' },
+      { text: 'Алиасы импортов', link: '/docs/setup/aliases' },
       { text: 'Biome', link: '/docs/setup/biome' },
       { text: 'PostCSS', link: '/docs/setup/postcss' },
       { text: 'Стили', link: '/docs/setup/styles' },

CONTRIBUTING.md

@@ -98,7 +98,8 @@ generate-llms.ts                 # Скрипт генерации llms.txt и R
 ```markdown
 # {Название}
 
-Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.
+{Одно-два предложения, по которым читатель за секунду решает, нужен ли ему раздел.
+Правила оформления — секция «Заголовок и описание» ниже.}
 
 ## Что нужно знать
 
@@ -183,58 +184,127 @@ title: Название раздела
 
 Значение `title` совпадает с текстом `h1`-заголовка в файле.
 
-### Заголовки
+### Заголовок и описание
 
-- Один `h1` на файл — совпадает с `title` из frontmatter.
+Каждая страница начинается с `h1`-заголовка и абзаца-описания сразу под ним.
-- Сразу после `h1` — вводный абзац (одно-два предложения).
+Эта пара — **навигационный маркер**: попадает в сайдбар, `llms.txt`,
+`README.md` архива и должна за секунду давать читателю или LLM понять,
+**когда сюда нужно идти**.
+
+#### Структура заголовков
+
+- Один `h1` на файл, совпадает с `title` во frontmatter.
+- Сразу после `h1` — описание (одно-два предложения, см. ниже).
 - Основные секции — `h2`.
 - Подсекции внутри `h2` — `h3`.
 - `h4` не используется.
 
-### Вводный абзац
+#### Имя `h1` (заголовок страницы)
 
-Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?».
+- Называет предметную область, а не реализацию.
-Он попадает в `llms.txt` и `README.md` архива как краткое описание,
+- Без имён пакетов, опций, конфигов и путей.
-поэтому должен быть плотным и без воды.
+- Самодостаточен — читается без контекста сайдбара.
+- Исключение: имя инструмента допустимо, если оно — единственное
+  устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`).
 
-**Правила:**
+**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты».
 
-- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе»,
+**Плохо:** «Установка и настройка» (что устанавливаем?),
-  «Здесь рассмотрено», «В этом документе».
+«Использование» (что используем?), «Введение» (во что?).
-- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`).
-- Двоеточие или тире для перечисления **категорий и областей**, а не
-  конкретных значений из содержимого.
-- Не дублировать содержимое: если внутри раздела 12 правил —
-  не перечислять их во вводном абзаце.
-- Не аргументировать («единые правила делают код предсказуемым»).
-- 1–2 предложения.
 
-**Проверка:** если при добавлении нового правила/инструмента/раздела
+#### Описание
-вводный абзац придётся править — он слишком конкретный.
+
+Описание — короткий ответ на вопрос «у меня задача X, мне сюда?».
+Не аннотация. Не оглавление.
+
+**Запреты:**
+
+- Не упоминать конкретные пакеты, библиотеки, инструменты
+  (`@gromlab/svg-sprites`, `Mantine`, `Zustand`).
+- Не упоминать конкретные файлы и пути
+  (`postcss.config.mjs`, `.templates/`, `biome.json`).
+- Не упоминать конкретные опции, ключи API, имена функций
+  (`baseUrl`, `cl()`, `useStore`).
+- Не начинать с «Раздел описывает», «Этот раздел»,
+  «В этом разделе», «Здесь рассмотрено».
+- Не использовать дежурные префиксы как шаблон
+  («Правила работы с...», «Правила написания...») — само то,
+  что раздел про правила, и так понятно из секции и заголовка.
+- Не пересказывать содержимое перечислением подсекций
+  («организация, реализация, делегирование, метаданные»).
+- Не аргументировать пользу
+  («обеспечит единообразие», «упростит поддержку»).
+
+**Требования:**
+
+- 1 предложение, обычно 5–12 слов.
+- Звучит как ответ человека другу, а не как техспек.
+- Описание читается **самостоятельно**, без контекста сайдбара.
+- Если страница вложена в семантическую группу
+  (например, `Данные → REST → Клиенты → ...`) и её заголовок
+  без этой группы теряет смысл — описание явно содержит имя
+  родительской области, чтобы читалось без сайдбара.
+
+**Подходящие формы:**
+
+- «Как X.»
+- «Что такое X.»
+- «Из чего состоит X.»
+- «Установка X.»
+- «Какие X есть и как ими пользоваться.»
+
+Перечисление аспектов через двоеточие — только если без него читатель
+не сможет различить раздел от соседнего.
+
+**Тест навигации.** Читатель видит описание — за секунду должен понять
+«мне сюда» или «нет, не сюда». Если приходится перечитывать —
+описание слишком длинное.
+
+**Тест на изменение.** Если в разделе сменится пакет, переименуется
+файл или добавится правило — придётся ли править описание?
+Если да — оно слишком конкретное.
 
 **Хорошо:**
 
 ```markdown
-Слои SLM: назначение, классификация, направление зависимостей, правила.
+Какие алиасы импортов есть в проекте и как ими пользоваться.
 ```
 
 ```markdown
-Базовый стек проекта по областям: UI, архитектура, данные, состояние,
+Установка и настройка линтера-форматтера в новом проекте.
-локализация, тестирование, стили, генерация кода.
+```
+
+```markdown
+Из чего состоит проект и где что лежит.
+```
+
+```markdown
+Получение REST-данных в серверных компонентах.
 ```
 
 **Плохо:**
 
 ```markdown
-Раздел описывает слои SLM: что такое слой, какие бывают, как между
+Раздел описывает, какие алиасы используются в проекте: их полный список,
-ними направлены зависимости и какие правила действуют на каждом.
+где они объявлены и как ими пользоваться между модулями и внутри модуля.
 ```
 
+_Начинается с «Раздел описывает», пересказывает содержимое._
+
 ```markdown
-Этот раздел описывает базовый стек технологий и библиотек, принятый в
+Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов,
-проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.
+конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
 ```
 
+_Упомянут конкретный файл, перечисление аспектов превратилось в оглавление._
+
+```markdown
+Правила работы с React-компонентами: файловая структура,
+типизация пропсов, документирование, реализация.
+```
+
+_Дежурный префикс «Правила работы с...» плюс оглавление подсекций._
+
 ### Примеры кода
 
 - Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.

docs-overview.md

@@ -0,0 +1,174 @@
+# Обзор страниц документации
+
+Список всех `.md`-страниц в `docs/docs/` в порядке сайдбара (`.vitepress/config.ts`).
+Поля: путь к файлу, заголовок (`h1`), описание (абзац под заголовком).
+
+## Главная
+
+### docs/docs/index.md
+**Заголовок:** NextJS Style Guide
+**Описание:** Стандарты разработки фронтенд-приложений на Next.js и TypeScript.
+
+## Подсказки
+
+### docs/docs/workflow.md
+**Заголовок:** Подсказки
+**Описание:** Короткие ответы на типовые вопросы и решения для спорных ситуаций.
+
+## Базовые правила
+
+### docs/docs/basics/tech-stack.md
+**Заголовок:** Технологии и библиотеки
+**Описание:** Какие библиотеки и инструменты используются в проекте.
+
+### docs/docs/basics/naming.md
+**Заголовок:** Именование
+**Описание:** Как называть переменные, файлы и прочие сущности в коде.
+
+### docs/docs/basics/architecture/index.md
+**Заголовок:** SLM Design
+**Описание:** Архитектурный подход проекта: что такое SLM и как он устроен.
+
+### docs/docs/basics/architecture/reference/layers.md
+**Заголовок:** Слои
+**Описание:** Из каких слоёв состоит архитектура и как они связаны.
+
+### docs/docs/basics/architecture/reference/modules.md
+**Заголовок:** Модули
+**Описание:** Что такое модуль в архитектуре и как он устроен.
+
+### docs/docs/basics/architecture/reference/segments.md
+**Заголовок:** Сегменты
+**Описание:** Что такое сегмент модуля и какие они бывают.
+
+### docs/docs/basics/code-style.md
+**Заголовок:** Стиль кода
+**Описание:** Как оформляется код в проекте.
+
+### docs/docs/basics/documentation.md
+**Заголовок:** Документирование
+**Описание:** Что и как документировать в коде.
+
+### docs/docs/basics/typing.md
+**Заголовок:** Типизация
+**Описание:** Как типизируется код в проекте.
+
+## Создание проекта
+
+### docs/docs/creating-project/from-template.md
+**Заголовок:** Создание проекта из шаблона
+**Описание:** Создание нового проекта на основе готового шаблона.
+
+### docs/docs/creating-project/manual.md
+**Заголовок:** Создание проекта вручную
+**Описание:** Поэтапное создание нового проекта без использования шаблона.
+
+### docs/docs/creating-project/nextjs.md
+**Заголовок:** Чистая установка Next.js
+**Описание:** Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
+
+## Настройка
+
+### docs/docs/setup/aliases.md
+**Заголовок:** Алиасы импортов
+**Описание:** Какие алиасы импортов есть в проекте и как ими пользоваться.
+
+### docs/docs/setup/biome.md
+**Заголовок:** Biome
+**Описание:** Установка и настройка линтера-форматтера в новом проекте.
+
+### docs/docs/setup/postcss.md
+**Заголовок:** PostCSS
+**Описание:** Установка и настройка CSS-процессора в новом проекте.
+
+### docs/docs/setup/styles.md
+**Заголовок:** Стили
+**Описание:** Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
+
+### docs/docs/setup/svg-sprites.md
+**Заголовок:** SVG-спрайты
+**Описание:** Подключение SVG-спрайтов в новом проекте.
+
+### docs/docs/setup/templates.md
+**Заголовок:** Шаблоны генерации
+**Описание:** Подключение шаблонов кодогенерации в новом проекте.
+
+### docs/docs/setup/vscode.md
+**Заголовок:** VS Code
+**Описание:** Единые настройки редактора и расширений для команды.
+
+## Использование
+
+### docs/docs/usage/project-structure.md
+**Заголовок:** Структура проекта
+**Описание:** Из чего состоит проект и где что лежит.
+
+### docs/docs/usage/components.md
+**Заголовок:** Компоненты
+**Описание:** Как устроен и пишется React-компонент в проекте.
+
+### docs/docs/usage/page-level.md
+**Заголовок:** Файлы роутинга
+**Описание:** Что должно лежать в файлах роутинга, а что — в экранах.
+
+### docs/docs/usage/templates-generation.md
+**Заголовок:** Шаблоны и генерация кода
+**Описание:** Как устроены шаблоны кодогенерации и как ими пользоваться.
+
+### docs/docs/usage/styles.md
+**Заголовок:** Стили
+**Описание:** Как пишутся стили в проекте.
+
+### docs/docs/usage/images-sprites.md
+**Заголовок:** —
+**Описание:** _(файл пустой)_
+
+### docs/docs/usage/svg-sprites.md
+**Заголовок:** SVG-спрайты
+**Описание:** Как добавлять и использовать SVG-иконки в коде.
+
+### docs/docs/usage/video.md
+**Заголовок:** —
+**Описание:** _(файл пустой)_
+
+### docs/docs/usage/stores.md
+**Заголовок:** —
+**Описание:** _(файл пустой)_
+
+### docs/docs/usage/hooks.md
+**Заголовок:** —
+**Описание:** _(файл пустой)_
+
+### docs/docs/usage/fonts.md
+**Заголовок:** —
+**Описание:** _(файл пустой)_
+
+### docs/docs/usage/localization.md
+**Заголовок:** —
+**Описание:** _(файл пустой)_
+
+## Данные
+
+### docs/docs/usage/data/index.md
+**Заголовок:** Источники данных
+**Описание:** Какие источники данных используются в проекте и как с ними работать.
+
+### docs/docs/usage/data/rest/clients/auto.md
+**Заголовок:** Автоматическая генерация
+**Описание:** Генерация REST-клиента из OpenAPI-спецификации.
+
+### docs/docs/usage/data/rest/clients/manual.md
+**Заголовок:** Ручное создание
+**Описание:** Создание REST-клиента вручную, когда нет OpenAPI-спецификации.
+
+### docs/docs/usage/data/rest/fetching/server.md
+**Заголовок:** Серверные компоненты
+**Описание:** Получение REST-данных в серверных компонентах.
+
+### docs/docs/usage/data/rest/fetching/client.md
+**Заголовок:** Клиентские компоненты
+**Описание:** Получение REST-данных в клиентских компонентах.
+
+### docs/docs/usage/data/realtime.md
+**Заголовок:** Realtime
+**Описание:** Работа с push-данными от сервера: подписки и события.

docs/docs/basics/architecture/index.md

@@ -1,9 +1,11 @@
 ---
-title: Архитектура
+title: SLM Design
+description: "Архитектурный подход проекта: что такое SLM и как он устроен."
 ---
 
 # SLM Design
-Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
+
+Архитектурный подход проекта: что такое SLM и как он устроен.
 
 ## Преимущества
 

docs/docs/basics/architecture/reference/layers.md

@@ -1,10 +1,11 @@
 ---
 title: Слои
+description: Из каких слоёв состоит архитектура и как они связаны.
 ---
 
 # Слои
 
-Слои SLM: назначение, классификация, направление зависимостей, правила.
+Из каких слоёв состоит архитектура и как они связаны.
 
 ## Определение
 

docs/docs/basics/architecture/reference/modules.md

@@ -1,10 +1,11 @@
 ---
 title: Модули
+description: Что такое модуль в архитектуре и как он устроен.
 ---
 
 # Модули
 
-Модули SLM: состав, границы, взаимодействие с остальным кодом.
+Что такое модуль в архитектуре и как он устроен.
 
 ## Определение
 

docs/docs/basics/architecture/reference/segments.md

@@ -1,10 +1,11 @@
 ---
 title: Сегменты
+description: Что такое сегмент модуля и какие они бывают.
 ---
 
 # Сегменты
 
-Сегменты SLM: типы, назначение, что лежит внутри каждого.
+Что такое сегмент модуля и какие они бывают.
 
 ## Определение
 

docs/docs/basics/code-style.md

@@ -1,10 +1,11 @@
 ---
 title: Стиль кода
+description: Как оформляется код в проекте.
 ---
 
 # Стиль кода
 
-Единые правила оформления кода: форматирование, импорты, читаемость.
+Как оформляется код в проекте.
 
 ## Отступы
 

docs/docs/basics/documentation.md

@@ -1,10 +1,11 @@
 ---
 title: Документирование
+description: Что и как документировать в коде.
 ---
 
 # Документирование
 
-Правила документирования кода: что и когда документировать через JSDoc.
+Что и как документировать в коде.
 
 ## Общие правила
 

docs/docs/basics/naming.md

@@ -1,10 +1,11 @@
 ---
 title: Именование
+description: Как называть переменные, файлы и прочие сущности в коде.
 ---
 
 # Именование
 
-Соглашения об именовании в коде: что и как называть.
+Как называть переменные, файлы и прочие сущности в коде.
 
 ## Базовые правила
 

docs/docs/basics/tech-stack.md

@@ -1,10 +1,11 @@
 ---
 title: Технологии и библиотеки
+description: Какие библиотеки и инструменты используются в проекте.
 ---
 
 # Технологии и библиотеки
 
-Базовый стек проекта по областям: UI, архитектура, данные, состояние, локализация, тестирование, стили, генерация кода.
+Какие библиотеки и инструменты используются в проекте.
 
 ## Что используем
 

docs/docs/basics/typing.md

@@ -1,10 +1,11 @@
 ---
 title: Типизация
+description: Как типизируется код в проекте.
 ---
 
 # Типизация
 
-Правила типизации в TypeScript: общие принципы и работа с динамическими типами.
+Как типизируется код в проекте.
 
 ## Общие правила
 

docs/docs/creating-project/from-template.md

@@ -1,12 +1,12 @@
 ---
 title: Создание проекта из шаблона
+description: Создание нового проекта на основе готового шаблона.
 keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект]
 ---
 
 # Создание проекта из шаблона
 
-Раздел описывает процесс создания нового проекта на основе готового шаблона.
+Создание нового проекта на основе готового шаблона.
-Шаблоны включают преднастроенный код-стайл, структуру проекта и необходимые конфигурации, что позволяет начать работу без дополнительной настройки.
 
 ## Что внутри
 

docs/docs/creating-project/manual.md

@@ -1,15 +1,12 @@
 ---
-title: Вручную
+title: Создание проекта вручную
+description: Поэтапное создание нового проекта без использования шаблона.
 keywords: [создать проект, новый проект, с нуля, init, initialize, scaffold, create-next-app, начать проект, поднять проект, эталонный проект, ручная установка]
 ---
 
 # Создание проекта вручную
 
-Раздел описывает процесс поэтапного создания Next.js-проекта без использования шаблона.Все настройки, включая структуру проекта, код-стайл и конфигурацию, выполняются вручную, что позволяет полностью контролировать каждый шаг.
+Поэтапное создание нового проекта без использования шаблона.
-
-Рекомендуется использовать этот подход, если требуется тонкая настройка проекта или шаблон недоступен. В остальных случаях проще воспользоваться созданием проекта из шаблона.
-
-Если шаблон доступен — быстрее использовать [Создание проекта из шаблона](/docs/creating-project/from-template).
 
 ## Состав эталонного проекта
 

docs/docs/creating-project/nextjs.md

@@ -1,11 +1,12 @@
 ---
-title: Next.js
+title: Чистая установка Next.js
+description: "Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку."
 keywords: [next.js, create-next-app, npx, установка, инициализация, фреймворк, скаффолдинг, app router, typescript]
 ---
 
-# Чистая установка Next.js (App Router + TypeScript)
+# Чистая установка Next.js
 
-Раздел описывает установку Next.js через create-next-app с последующей очисткой стандартного шаблона. В результате создаётся минимальный проект со включёнными App Router и TypeScript, без лишнего кода и зависимостей.
+Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
 
 ## Требования
 

docs/docs/index.md

@@ -1,6 +1,11 @@
+---
+title: NextJS Style Guide
+description: Стандарты разработки фронтенд-приложений на Next.js и TypeScript.
+---
+
 # NextJS Style Guide
 
-Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура.
+Стандарты разработки фронтенд-приложений на Next.js и TypeScript.
 
 ## Использование
 

docs/docs/setup/aliases.md

@@ -1,13 +1,12 @@
 ---
-title: Алиасы
+title: Алиасы импортов
+description: Какие алиасы импортов есть в проекте и как ими пользоваться.
 keywords: [алиасы, aliases, paths, tsconfig, импорты, baseUrl, app, layouts, screens, widgets, business, infrastructure, ui, shared]
 ---
 
-# Алиасы
+# Алиасы импортов
 
-Импорты в проекте идут через алиасы слоёв SLM-архитектуры — по одному на каждый слой `src/`. Префикс `@/` **не используется**: имя слоя само по себе однозначно адресует код.
+Какие алиасы импортов есть в проекте и как ими пользоваться.
-
-Слои и направление зависимостей — [Архитектура: слои](/docs/basics/architecture/reference/layers).
 
 ## Конфиг
 

docs/docs/setup/biome.md

@@ -1,11 +1,12 @@
 ---
 title: Biome
+description: Установка и настройка линтера-форматтера в новом проекте.
 keywords: [biome, линтер, форматтер, lint, format, biome.json, "@biomejs/biome", замена eslint, замена prettier]
 ---
 
 # Biome
 
-Единый линтер и форматтер для JS/TS/JSON в проекте. Заменяет связку ESLint + Prettier одним инструментом.
+Установка и настройка линтера-форматтера в новом проекте.
 
 ## Требования
 

docs/docs/setup/postcss.md

@@ -1,13 +1,12 @@
 ---
 title: PostCSS
+description: Установка и настройка CSS-процессора в новом проекте.
 keywords: [postcss, postcss.config.mjs, postcss-custom-media, postcss-nesting, autoprefixer, postcss-global-data, csstools, "@custom-media", "@nest", css-процессор]
 ---
 
 # PostCSS
 
-Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов, конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
+Установка и настройка CSS-процессора в новом проекте.
-
-Правила написания CSS в компонентах — [Использование](/docs/usage/styles).
 
 ## Зачем PostCSS
 

docs/docs/setup/styles.md

@@ -1,13 +1,12 @@
 ---
 title: Стили
+description: "Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили."
 keywords: [variables.css, media.css, global.css, shared/styles, токены, переменные, custom-media, breakpoints, подключение стилей, базовые стили, инициализация]
 ---
 
 # Стили
 
-Базовая стилевая инфраструктура: токены, breakpoints и точка сборки глобальных стилей в `src/shared/styles/`.
+Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
-
-CSS-процессор — отдельный шаг ([PostCSS](/docs/setup/postcss)). Правила написания CSS в компонентах — [Стили: использование](/docs/usage/styles).
 
 ## Требования
 

docs/docs/setup/svg-sprites.md

@@ -1,13 +1,12 @@
 ---
-title: Установка и настройка
+title: SVG-спрайты
+description: Подключение SVG-спрайтов в новом проекте.
 keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
 ---
 
-# Установка и настройка
+# SVG-спрайты
 
-Первичная настройка пакета `@gromlab/svg-sprites` в проекте. Выполняется один раз при заведении проекта и при смене мажорной версии пакета.
+Подключение SVG-спрайтов в новом проекте.
-
-Что такое спрайты, как с ними работать и как управлять цветом — [Использование](/docs/usage/svg-sprites).
 
 ## Требования
 

docs/docs/setup/templates.md

@@ -1,13 +1,12 @@
 ---
 title: Шаблоны генерации
+description: Подключение шаблонов кодогенерации в новом проекте.
 keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, добавить шаблон, скачать шаблоны, scaffold]
 ---
 
 # Шаблоны генерации
 
-Папка `.templates/` в корне проекта для генератора модулей `@gromlab/create`.
+Подключение шаблонов кодогенерации в новом проекте.
-
-Синтаксис шаблонов и работа генератора — [Шаблоны и генерация кода](/docs/usage/templates-generation).
 
 ## Требования
 

docs/docs/setup/vscode.md

@@ -1,10 +1,11 @@
 ---
-title: Настройка VS Code
+title: VS Code
+description: Единые настройки редактора и расширений для команды.
 ---
 
-# Настройка VS Code
+# VS Code
 
-Каждый проект содержит папку `.vscode/` с конфигурацией редактора. Это гарантирует, что все участники команды работают с одинаковыми настройками форматирования, линтинга и расширениями.
+Единые настройки редактора и расширений для команды.
 
 ## Структура `.vscode/`
 

docs/docs/usage/components.md

@@ -1,13 +1,11 @@
 ---
 title: Компоненты
+description: Как устроен и пишется React-компонент в проекте.
 ---
 
 # Компоненты
 
-Правила написания React-компонентов: файловая структура модуля, типизация пропсов, документирование и реализация. Раздел охватывает компоненты всех слоёв — от `shared/ui` до `screens`.
+Как устроен и пишется React-компонент в проекте.
-
-Архитектурные слои и их назначение описаны в разделе [Архитектура](/docs/basics/architecture/).
-
 
 ## Правила организации
 

docs/docs/usage/data/index.md

@@ -1,11 +1,12 @@
 ---
-title: Введение
+title: Источники данных
+description: Какие источники данных используются в проекте и как с ними работать.
 keywords: [данные, api, rest, realtime, клиент, swr, infrastructure, введение, карта раздела]
 ---
 
-# Введение
+# Источники данных
 
-Работа с источниками данных в проекте: REST, realtime и любые другие каналы, которые появятся в будущем. Раздел описывает, как создаются клиенты для API и как полученные данные доходят до страниц и компонентов.
+Какие источники данных используются в проекте и как с ними работать.
 
 ## Принципы раздела
 

docs/docs/usage/data/realtime.md

@@ -1,13 +1,12 @@
 ---
 title: Realtime
+description: "Работа с push-данными от сервера: подписки и события."
 keywords: [realtime, websocket, sse, подписка, swr subscription, useSWRSubscription, push, события]
 ---
 
 # Realtime
 
-Канал для push-данных: WebSocket, SSE, событийные шины и любой другой источник, инициирующий передачу со стороны сервера. Транспорт не зашит в правила — важна абстракция «подписка».
+Работа с push-данными от сервера: подписки и события.
-
-Получение REST-данных — [REST](/docs/usage/data/rest/clients/auto).
 
 ## Принципы
 

docs/docs/usage/data/rest/clients/auto.md

@@ -1,13 +1,12 @@
 ---
 title: Автоматическая генерация
+description: Генерация REST-клиента из OpenAPI-спецификации.
 keywords: [api, rest, openapi, codegen, генерация, клиент, api-codegen, gromlab, infrastructure, swagger-typescript-api]
 ---
 
 # Автоматическая генерация
 
-Если у API есть OpenAPI-спецификация — клиент генерируется утилитой [@gromlab/api-codegen](https://gromlab.ru/gromov/api-codegen) (обёртка над `swagger-typescript-api`). Ручной код для таких API не пишется.
+Генерация REST-клиента из OpenAPI-спецификации.
-
-Когда схемы нет — [Ручное создание](/docs/usage/data/rest/clients/manual).
 
 В примерах ниже используется условный API `pet-project-api` (kebab-case в путях) / `petProjectApi` (camelCase в коде). В реальном проекте имена выбираются по конкретному API.
 

docs/docs/usage/data/rest/clients/manual.md

@@ -1,13 +1,12 @@
 ---
 title: Ручное создание
+description: "Создание REST-клиента вручную, когда нет OpenAPI-спецификации."
 keywords: [api, rest, клиент, ручной, fetch, infrastructure, api-клиент]
 ---
 
 # Ручное создание
 
-Если у API нет OpenAPI-спецификации — клиент пишется и поддерживается вручную. Цель та же, что и у автогенерации: единая точка работы с API, без прямых `fetch` в коде приложения.
+Создание REST-клиента вручную, когда нет OpenAPI-спецификации.
-
-Когда схема есть — [Автоматическая генерация](/docs/usage/data/rest/clients/auto).
 
 В примерах ниже используется условный API `pet-project-api` / `petProjectApi`. В реальном проекте имена выбираются по конкретному API.
 

docs/docs/usage/data/rest/fetching/client.md

@@ -1,13 +1,12 @@
 ---
 title: Клиентские компоненты
+description: Получение REST-данных в клиентских компонентах.
 keywords: [swr, клиентские компоненты, useSWR, хук, мутация, useSWRMutation, кеш, ревалидация]
 ---
 
 # Клиентские компоненты
 
-В клиентских компонентах данные получаются через **готовые хуки**, которые экспортируются из модуля API. SWR инкапсулирован в хуке — компонент не знает про `useSWR`, ключи и fetcher.
+Получение REST-данных в клиентских компонентах.
-
-Создание клиента и хуков — [Автоматическая](/docs/usage/data/rest/clients/auto) / [Ручная](/docs/usage/data/rest/clients/manual) генерация.
 
 ## Правила
 

docs/docs/usage/data/rest/fetching/server.md

@@ -1,13 +1,12 @@
 ---
 title: Серверные компоненты
+description: Получение REST-данных в серверных компонентах.
 keywords: [server components, rsc, серверные компоненты, fetch, api, app router, прямой вызов]
 ---
 
 # Серверные компоненты
 
-В серверных компонентах (Server Components App Router) данные получаются **прямым вызовом метода API-клиента**. SWR и хуки здесь не применяются — они для клиентского кода.
+Получение REST-данных в серверных компонентах.
-
-Создание клиента — [Автоматическая](/docs/usage/data/rest/clients/auto) / [Ручная](/docs/usage/data/rest/clients/manual) генерация.
 
 ## Правила
 

docs/docs/usage/page-level.md

@@ -1,10 +1,11 @@
 ---
 title: Файлы роутинга
+description: "Что должно лежать в файлах роутинга, а что — в экранах."
 ---
 
 # Файлы роутинга
 
-Правила для специальных файлов App Router (`page.tsx`, `layout.tsx`, `error.tsx`, `not-found.tsx` и др.) — чем наш подход отличается от дефолтного.
+Что должно лежать в файлах роутинга, а что — в экранах.
 
 ## Организация
 

docs/docs/usage/project-structure.md

@@ -1,10 +1,11 @@
 ---
 title: Структура проекта
+description: Из чего состоит проект и где что лежит.
 ---
 
 # Структура проекта
 
-Файловая организация Next.js-проекта по архитектуре SLM.
+Из чего состоит проект и где что лежит.
 
 ## Корень репозитория
 

docs/docs/usage/styles.md

@@ -1,10 +1,11 @@
 ---
-title: Использование
+title: Стили
+description: Как пишутся стили в проекте.
 ---
 
-# Использование
+# Стили
 
-Правила написания CSS: PostCSS Modules, форматирование, переменные. Установка и настройка процессора — [PostCSS](/docs/setup/postcss).
+Как пишутся стили в проекте.
 
 ## Общие правила
 

docs/docs/usage/svg-sprites.md

@@ -1,11 +1,12 @@
 ---
-title: Использование
+title: SVG-спрайты
+description: Как добавлять и использовать SVG-иконки в коде.
 keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
 ---
 
-# Использование
+# SVG-спрайты
 
-Работа с SVG-иконками через сгенерированный компонент `<SvgSprite/>`. Установка пакета — [Установка и настройка](/docs/setup/svg-sprites).
+Как добавлять и использовать SVG-иконки в коде.
 
 ## Шаги
 

docs/docs/usage/templates-generation.md

@@ -1,5 +1,6 @@
 ---
 title: Шаблоны и генерация кода
+description: Как устроены шаблоны кодогенерации и как ими пользоваться.
 ---
 
 <!-- @formatter:off -->
@@ -7,7 +8,7 @@ title: Шаблоны и генерация кода
 
 # Шаблоны и генерация кода
 
-Как работают шаблоны, как их создавать, синтаксис переменных и как генерировать код с помощью расширения VS Code и CLI.
+Как устроены шаблоны кодогенерации и как ими пользоваться.
 
 ## Структура шаблонов
 

docs/docs/workflow.md

@@ -1,7 +1,8 @@
 ---
 title: Подсказки
+description: Короткие ответы на типовые вопросы и решения для спорных ситуаций.
 ---
 
 # Подсказки
 
-Короткие ответы на типовые вопросы и направления в противоречивых ситуациях.
+Короткие ответы на типовые вопросы и решения для спорных ситуаций.