fix: добавить cache-busting для ARCHITECTURE.md через query-параметр версии

- Добавлен лендинг на React + Vite с темой и карточками навигации
- Добавлен модуль темы (src/infra/theme) с поддержкой system/light/dark
- Документация переписана: разделы «Модули», «Сегменты», «Компонент»
- Добавлена страница навигации docs/index.md
- Генерация llms.txt переведена на парсинг сайдбара VitePress
- Описания для llms.txt вынесены в frontmatter (поле description)
- Удалена директория generated/, архив ZIP убран с лендинга
- Удалены английская документация, README_RU, concat-md.js
- Добавлен vite-плагин для UTF-8 заголовков текстовых артефактов
- Caddyfile обновлён: charset=utf-8 для llms.txt и ARCHITECTURE.md

.gitea/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
     outputs:
-      new_tag: ${{ steps.tag.outputs.new_tag }}
+      version: ${{ steps.version.outputs.version }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -21,42 +21,41 @@ jobs:
         with:
           node-version: 24
 
-      - name: Генерация ARCHITECTURE.md
+      - name: Версия из package.json
+        id: version
+        run: |
+          VERSION="v$(node -p "require('./package.json').version")"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Версия: $VERSION"
+
+      - name: Генерация docs
         run: |
           npm ci
           npm run docs
 
-      - name: Автоматический тег (semver patch)
+      - name: Коммит generated/
-        id: tag
         run: |
-          LAST_TAG=$(git tag -l 'v*' --sort=-v:refname | head -1)
-          if [ -z "$LAST_TAG" ]; then
-            NEW_TAG="v0.1.0"
-          else
-            MAJOR=$(echo "$LAST_TAG" | cut -d. -f1)
-            MINOR=$(echo "$LAST_TAG" | cut -d. -f2)
-            PATCH=$(echo "$LAST_TAG" | cut -d. -f3)
-            NEW_TAG="${MAJOR}.${MINOR}.$((PATCH + 1))"
-          fi
-          git tag "$NEW_TAG"
-          git push origin "$NEW_TAG"
-          echo "new_tag=$NEW_TAG" >> $GITHUB_OUTPUT
-          echo "Создан тег: $NEW_TAG"
-
-      - name: Подставить URL с тегом и коммит
-        run: |
-          NEW_TAG=${{ steps.tag.outputs.new_tag }}
-          sed -i "s|raw/branch/main|raw/tag/${NEW_TAG}|g" README_RU.md
           git config user.name "CI Bot"
           git config user.email "ci@gromlab.ru"
           git add generated/ README_RU.md
           if git diff --cached --quiet; then
             echo "Нет изменений, пропуск"
           else
-            git commit -m "docs: обновить ARCHITECTURE.md и README (${NEW_TAG}) [skip ci]"
+            git commit -m "docs: обновить generated (${{ steps.version.outputs.version }}) [skip ci]"
             git push origin main
           fi
 
+      - name: Создать тег
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          if git tag -l "$VERSION" | grep -q "$VERSION"; then
+            echo "Тег $VERSION уже существует, пропуск"
+          else
+            git tag "$VERSION"
+            git push origin "$VERSION"
+            echo "Создан тег: $VERSION"
+          fi
+
   docker:
     runs-on: ubuntu-latest
     needs: docs
@@ -93,7 +92,7 @@ jobs:
             type=ref,event=branch
             type=sha,prefix=
             type=raw,value=latest,enable={{is_default_branch}}
-            type=raw,value=${{ needs.docs.outputs.new_tag }}
+            type=raw,value=${{ needs.docs.outputs.version }}
 
       - name: Build and push
         uses: docker/build-push-action@v5
@@ -105,7 +104,7 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           build-args: |
-            VERSION_TAG=${{ needs.docs.outputs.new_tag }}
+            VERSION_TAG=${{ needs.docs.outputs.version }}
           provenance: false
           sbom: false
 
@@ -134,31 +133,23 @@ jobs:
             IMAGE="${{ env.REGISTRY_IMAGE }}:latest"
             CONTAINER="slm-design"
 
-            # Логин в реестр
             echo '${{ secrets.CR_TOKEN }}' | docker login ${{ env.DOCKER_REGISTRY }} -u '${{ secrets.CR_USER }}' --password-stdin
 
-            # Сохранить ID текущего образа до pull
             OLD_IMAGE_ID=$(docker images -q "$IMAGE" 2>/dev/null || true)
-
-            # Скачать новый образ
             docker pull "$IMAGE"
 
-            # Перезапустить контейнер
             docker stop "$CONTAINER" 2>/dev/null || true
             docker rm "$CONTAINER" 2>/dev/null || true
             docker run -d --name "$CONTAINER" --network web --restart unless-stopped "$IMAGE"
 
-            # Удалить старый образ если он отличается от нового
             NEW_IMAGE_ID=$(docker images -q "$IMAGE")
             if [ -n "$OLD_IMAGE_ID" ] && [ "$OLD_IMAGE_ID" != "$NEW_IMAGE_ID" ]; then
               docker rmi "$OLD_IMAGE_ID" 2>/dev/null || true
             fi
 
-            # Очистка
             docker image prune -af --filter "label=org.opencontainers.image.title=$CONTAINER"
             docker image prune -f
             docker builder prune -f 2>/dev/null || true
 
-            # Статус
             docker ps --filter "name=$CONTAINER"
           SCRIPT

.gitignore

@@ -136,6 +136,16 @@ dist
 .vitepress/dist
 docs/.vitepress
 
+# Generated artifacts
+public/docs/
+public/llms.txt
+public/llms-full.txt
+public/slm-design.zip
+generated/
+
+# Vite
+dist
+
 # Рабочие заметки
 notes
 

.vitepress/config.ts

@@ -1,59 +1,28 @@
 import { defineConfig } from 'vitepress';
 
-const ruSidebar = [
+const sidebar = [
   {
-    text: 'Введение',
+    text: 'Архитектура',
-    link: '/',
-  },
-  {
-    text: 'Справочник',
     items: [
-      { text: 'Слои', link: '/reference/layers' },
+      { text: 'Обзор', link: '/architecture/' },
-      { text: 'Модули', link: '/reference/modules' },
+      { text: 'Слои', link: '/architecture/layers' },
-      { text: 'Сегменты', link: '/reference/segments' },
+      { text: 'Модули', link: '/architecture/modules' },
-    ],
+      { text: 'Сегменты', link: '/architecture/segments' },
-  },
-
-];
-
-const enSidebar = [
-  {
-    text: 'Architecture',
-    items: [
-      { text: 'Overview', link: '/en/architecture/overview' },
-      { text: 'Terminology', link: '/en/architecture/terminology' },
-      { text: 'Layers', link: '/en/architecture/layers' },
-      { text: 'Module', link: '/en/architecture/module' },
-      { text: 'Edge Cases', link: '/en/architecture/edge-cases' },
-      { text: 'Rationale', link: '/en/architecture/rationale' },
     ],
   },
 ];
 
 export default defineConfig({
   srcDir: 'docs',
+  outDir: 'public/docs',
   title: 'SLM Design',
   description: 'Правила и стандарты архитектуры проекта',
+  base: '/docs/',
 
-  rewrites: {
-    'ru/:rest*': ':rest*',
-  },
-
-  locales: {
-    root: {
-      label: 'Русский',
-      lang: 'ru-RU',
   themeConfig: {
-        sidebar: ruSidebar,
+    sidebar,
-      },
+    socialLinks: [
-    },
+      { icon: 'github', link: 'https://gromlab.ru/gromov/slm-design' },
-    en: {
+    ],
-      label: 'English',
-      lang: 'en-US',
-      link: '/en/',
-      themeConfig: {
-        sidebar: enSidebar,
-      },
-    },
   },
 });

.vitepress/theme/custom.css

@@ -1,17 +0,0 @@
-.VPNavBarTitle.has-sidebar .title {
-  border-top: none !important;
-  padding-top: 0;
-}
-
-.VPNavBarTitle .title {
-  white-space: normal;
-  line-height: 1.2;
-  padding: 6px 0;
-}
-
-.VPNavBarTitle .title span {
-  display: block;
-  min-width: 0;
-  max-width: 100%;
-  overflow-wrap: anywhere;
-}

.vitepress/theme/index.ts

@@ -1,4 +0,0 @@
-import DefaultTheme from 'vitepress/theme';
-import './custom.css';
-
-export default DefaultTheme;

Caddyfile

@@ -1,5 +1,10 @@
 :8082 {
 	root * /srv
+	@plainText path /llms.txt /llms-full.txt
+	header @plainText Content-Type "text/plain; charset=utf-8"
+	@markdown path /ARCHITECTURE.md
+	header @markdown Content-Type "text/markdown; charset=utf-8"
 	file_server
-	try_files {path} /index.html
+	header Link "</llms.txt>; rel=\"llms\""
+	try_files {path} {path}.html {path}/index.html /index.html
 }

Dockerfile

@@ -1,12 +1,12 @@
 FROM node:24-alpine AS build
 ARG VERSION_TAG=main
 WORKDIR /app
+RUN apk add --no-cache zip
 COPY package*.json ./
 RUN npm ci
 COPY . .
-RUN sed -i "s|raw/branch/main|raw/tag/${VERSION_TAG}|g" docs/ru/index.md \
+RUN npm run generate && npm run docs:build && npm run build
-    && npm run build
 
 FROM caddy:2-alpine
 COPY Caddyfile /etc/caddy/Caddyfile
-COPY --from=build /app/.vitepress/dist /srv
+COPY --from=build /app/dist /srv

README.md

@@ -1,6 +1,94 @@
 # SLM Design
+Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
 
-Scoped Layered Module Design — модульная архитектура фронтенд-приложений.
+## Преимущества
 
-- [Документация](https://slm.gromov.io)
+### Вертикальная организация домена
-- [ARCHITECTURE.md для AI-ассистентов](generated/ru/ARCHITECTURE.md)
+
+Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
+
+### Dependency Injection без фреймворков
+
+Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
+
+### Разделение ответственности без перегрузки слоёв
+
+Сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
+
+### Горизонтальная инкапсуляция
+
+Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
+
+### Колокация по умолчанию
+
+Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
+
+### Явное разделение каркаса и контента
+
+Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
+
+### Масштабирование через группировку
+
+При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
+
+## Происхождение
+
+SLM Design вырос на основе:
+
+- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
+- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
+- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
+- **Colocation Principle** — код живёт рядом с местом использования
+
+## Пример структуры проекта
+
+```text
+src/
+├── app/
+│
+├── layouts/
+│   ├── main/
+│   └── dashboard/
+│
+├── screens/
+│   ├── home/
+│   ├── products/
+│   ├── product-detail/
+│   └── about/
+│
+├── widgets/
+│   ├── page-heading/
+│   ├── hero-section/
+│   └── promo-banner/
+│
+├── business/
+│   ├── auth/
+│   ├── catalog/
+│   ├── orders/
+│   └── chat/
+│
+├── infra/
+│   ├── theme/
+│   ├── i18n/
+│   ├── backend-api/
+│   └── logger/
+│
+├── ui/
+│   ├── button/
+│   ├── input/
+│   ├── modal/
+│   ├── toast/
+│   └── dropdown/
+│
+└── shared/
+    ├── lib/
+    ├── types/
+    └── styles/
+```
+
+## Принципы
+
+- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
+- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
+- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
+- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.

README_RU.md

@@ -1,98 +0,0 @@
-# SLM Design
-Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
-
-<!-- rules-link -->
-🤖 Для AI-ассистентов доступен единый файл правил: [gromlab.ru/.../raw/tag/v0.1.1/.../ARCHITECTURE.md](https://gromlab.ru/gromov/slm-design/raw/tag/v0.1.1/generated/ru/ARCHITECTURE.md)
-<!-- /rules-link -->
-
-## Преимущества
-
-### Вертикальная организация домена
-
-Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
-
-### Разделение ответственности без перегрузки слоёв
-
-Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
-
-### Горизонтальная инкапсуляция
-
-Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
-
-### Колокация по умолчанию
-
-Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
-
-### Явное разделение каркаса и контента
-
-Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
-
-### Масштабирование через группировку
-
-При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
-
-### Dependency Injection без фреймворков
-
-Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
-
-## Происхождение
-
-SLM Design вырос на основе:
-
-- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
-- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
-- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
-- **Colocation Principle** — код живёт рядом с местом использования
-
-## Пример структуры проекта
-
-```text
-src/
-├── app/
-│
-├── layouts/
-│   ├── main/
-│   └── dashboard/
-│
-├── screens/
-│   ├── home/
-│   ├── products/
-│   ├── product-detail/
-│   └── about/
-│
-├── widgets/
-│   ├── page-heading/
-│   ├── hero-section/
-│   └── promo-banner/
-│
-├── business/
-│   ├── auth/
-│   ├── catalog/
-│   ├── orders/
-│   └── chat/
-│
-├── infrastructure/
-│   ├── theme/
-│   ├── i18n/
-│   ├── backend-api/
-│   └── logger/
-│
-├── ui/
-│   ├── button/
-│   ├── input/
-│   ├── modal/
-│   ├── toast/
-│   └── dropdown/
-│
-└── shared/
-    ├── lib/
-    ├── types/
-    └── styles/
-```
-
-## Принципы
-
-- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
-- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
-- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
-- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.

concat-md.js

@@ -1,92 +0,0 @@
-import path from "path";
-import fs from "fs";
-
-// Явный порядок файлов внутри каждого языка
-const fileOrder = [
-  "index.md",
-  // reference
-  "reference/layers.md",
-  "reference/modules.md",
-  "reference/segments.md",
-
-];
-
-// Удалить frontmatter из содержимого md-файла
-const stripFrontmatter = (content) =>
-  content.replace(/^---[\s\S]*?---\n*/m, "");
-
-// Удалить блоки между маркерами <!-- rules-link --> и <!-- /rules-link -->
-const stripRulesLink = (content) =>
-  content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");
-
-// Сдвинуть уровень заголовков на 1 вниз (h1→h2, h2→h3, ...)
-// Не трогает заголовки внутри блоков кода
-const shiftHeadings = (content) => {
-  const lines = content.split("\n");
-  let inCodeBlock = false;
-
-  return lines
-    .map((line) => {
-      if (line.startsWith("```")) inCodeBlock = !inCodeBlock;
-      if (inCodeBlock) return line;
-      if (/^#{1,5}\s/.test(line)) return "#" + line;
-      return line;
-    })
-    .join("\n");
-};
-
-// Собрать ARCHITECTURE.md с мета-якорями для каждого файла
-const buildRules = (lang) => {
-  const srcDir = `./docs/${lang}`;
-  const outDir = `./generated/${lang}`;
-  const outFile = path.join(outDir, "ARCHITECTURE.md");
-
-  if (!fs.existsSync(srcDir)) {
-    console.log(`Пропуск ${lang}: папка ${srcDir} не найдена`);
-    return;
-  }
-
-  fs.mkdirSync(outDir, { recursive: true });
-
-  const parts = [];
-
-  for (const file of fileOrder) {
-    const filePath = path.join(srcDir, file);
-    if (!fs.existsSync(filePath)) continue;
-
-    const raw = fs.readFileSync(filePath, "utf8");
-    const content = stripRulesLink(stripFrontmatter(raw)).trim();
-    if (!content) continue;
-
-    // Мета-якорь: путь VitePress без расширения
-    const route = "/" + file.replace(/\.md$/, "");
-    // index.md остаётся без сдвига (его h1 — главный заголовок документа)
-    const processed = file === "index.md" ? content : shiftHeadings(content);
-    parts.push(`<!-- ${route} -->\n${processed}`);
-  }
-
-  fs.writeFileSync(outFile, parts.join("\n\n"), "utf8");
-  console.log(`ARCHITECTURE.md (${lang}) создан: ${outFile}`);
-};
-
-// Собираем ARCHITECTURE.md для обоих языков
-buildRules("ru");
-buildRules("en");
-
-// Генерируем README из index.md
-const buildReadme = (lang, outFile) => {
-  const indexPath = `./docs/${lang}/index.md`;
-
-  if (!fs.existsSync(indexPath)) {
-    console.log(`Пропуск README (${lang}): ${indexPath} не найден`);
-    return;
-  }
-
-  const content = stripFrontmatter(fs.readFileSync(indexPath, "utf8"));
-  fs.writeFileSync(outFile, content, "utf8");
-  console.log(`${outFile} создан из ${indexPath}`);
-};
-
-buildReadme("ru", "./README_RU.md");
-
-

docs/architecture/index.md

@@ -1,23 +1,24 @@
 ---
 title: SLM Design
+description: Назначение архитектуры, ключевые принципы и карта разделов документации
 ---
 
 # SLM Design
 Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
 
-<!-- rules-link -->
-🤖 Для AI-ассистентов доступен единый файл правил: [gromlab.ru/.../raw/branch/main/.../ARCHITECTURE.md](https://gromlab.ru/gromov/slm-design/raw/branch/main/generated/ru/ARCHITECTURE.md)
-<!-- /rules-link -->
-
 ## Преимущества
 
 ### Вертикальная организация домена
 
 Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
 
+### Dependency Injection без фреймворков
+
+Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
+
 ### Разделение ответственности без перегрузки слоёв
 
-Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
+Сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
 
 ### Горизонтальная инкапсуляция
 
@@ -35,10 +36,6 @@ Scoped Layered Module Design — модульная архитектура фр
 
 При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
 
-### Dependency Injection без фреймворков
-
-Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
-
 ## Происхождение
 
 SLM Design вырос на основе:
@@ -75,7 +72,7 @@ src/
 │   ├── orders/
 │   └── chat/
 │
-├── infrastructure/
+├── infra/
 │   ├── theme/
 │   ├── i18n/
 │   ├── backend-api/

docs/architecture/layers.md

@@ -1,5 +1,6 @@
 ---
 title: Слои
+description: Иерархия слоёв от app до shared, правила зависимостей и зона ответственности каждого слоя
 ---
 
 # Слои
@@ -17,7 +18,7 @@ title: Слои
 | Группа | Слои | Описание |
 |--------|------|----------|
 | Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
-| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
+| Ядро | `business`, `infra`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
 | Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
 
 ## Направление зависимостей
@@ -25,12 +26,12 @@ title: Слои
 Любой импорт между модулями — только через публичный API.
 
 ```
-app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
+app → [ layouts | screens ] → widgets → business → infra → ui → shared
 ```
 
 - `layouts` и `screens` — параллельные слои, не импортируют друг друга
 - Модули одного слоя в группе «Композиция» изолированы друг от друга
-- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
+- Модули одного слоя `infra` и `ui` могут импортировать друг друга через публичный API
 - Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
 - Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
 
@@ -128,7 +129,7 @@ src/widgets/
 
 Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
 
-Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
+Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`. Каждый бизнес-модуль создаёт публичный runtime API через фабрику в корне. Cross-domain зависимости: runtime — через аргументы фабрики, типы — напрямую через `import type`.
 
 Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
 
@@ -159,19 +160,20 @@ src/business/
 
 - Один модуль = один бизнес-домен
 - Циклические зависимости между доменами запрещены
-- Импорт кода между доменами — через фабрику. `import type` — напрямую
+- Публичный runtime API — через фабрику в корне модуля (`{name}.factory.ts`). `index.ts` экспортирует только фабрику и type-only экспорты
+- Импорт runtime-кода между доменами — через фабрику. `import type` — напрямую
 - Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
 
-## Слой Infrastructure
+## Слой infra
 
 Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
 
-Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
+Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`.
 
-Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
+Отличие от `shared/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
 
 ```text
-src/infrastructure/
+src/infra/
 ├── theme/
 ├── i18n/
 ├── backend-api/
@@ -184,7 +186,7 @@ src/infrastructure/
 ### Требования
 
 - Один модуль = один техсервис
-- Импортирует `infrastructure/`, `ui/`, `shared/`
+- Импортирует `infra/`, `ui/`, `shared/`
 
 ## Слой UI
 
@@ -235,7 +237,7 @@ src/ui/
 
 Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
 
-Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
+Отличие от `infra/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
 
 Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
 

docs/architecture/modules.md

@@ -0,0 +1,289 @@
+---
+title: Модули
+description: Структура модуля, типы (UI, бизнес, инфра), публичный API, отличие модуля от компонента
+---
+
+# Модули
+
+Раздел описывает модуль как границу ответственности в SLM: что считается модулем, что такое компонент внутри модуля и как модуль взаимодействует с остальным кодом.
+
+## Определение
+
+**Модуль — минимальная архитектурная единица SLM. Он живёт на одном из слоёв, владеет конкретной областью ответственности и предоставляет наружу только публичный API.**
+
+Модуль может содержать всё, что нужно этой области: компоненты, вложенные модули, хуки, сторы, сервисы, типы, стили, конфиги и утилиты. Набор сегментов не фиксирован — модуль включает только то, что реально нужно.
+
+Модуль не обязан быть UI-блоком. Это может быть страница, виджет, бизнес-домен, инфраструктурный сервис или UI-kit сущность.
+
+Главная граница модуля — не папка, а ответственность.
+
+## Компонент
+
+**Компонент — презентационная единица модуля, которая находится только в `ui/` своего родительского модуля и отвечает за отображение части интерфейса.**
+
+Компонент не является архитектурной единицей: он не владеет сценарием, зависимостями, данными или внутренней структурой. Он работает только внутри границы родительского модуля.
+
+> Компонент отображает. Модуль организует.
+
+Компонент не может:
+
+- Импортировать код проекта за пределами родительского модуля.
+- Владеть архитектурными зависимостями.
+- Содержать любые компоненты.
+- Содержать любые модули.
+- Делать внешние запросы.
+- Самостоятельно получать данные.
+- Выбирать источник данных.
+- Композировать данные.
+- Вызывать сценарные хуки.
+- Оркестрировать сценарий.
+- Композировать модули.
+- Решать, как устроен процесс.
+- Содержать бизнес-логику.
+- Содержать сценарную логику.
+
+Если компоненту требуется что-то из этого списка, он перестаёт быть компонентом и должен быть оформлен как модуль.
+
+```text
+auth/
+├── ui/
+│   └── logout-button/
+│       ├── logout-button.tsx
+│       ├── styles/
+│       │   └── logout-button.module.css
+│       ├── types/
+│       │   └── logout-button-props.type.ts
+│       └── index.ts
+└── index.ts
+```
+
+## Что считается модулем
+
+Модулем считается папка, которая представляет самостоятельную область ответственности и имеет публичную границу.
+
+Примеры модулей:
+
+- `screens/home/` — модуль страницы.
+- `widgets/page-heading/` — модуль виджета.
+- `business/auth/` — модуль бизнес-домена.
+- `infra/theme/` — модуль инфраструктурного сервиса.
+- `ui/button/` — модуль UI-kit сущности.
+- `screens/home/parts/hero-section/` — вложенный модуль страницы.
+
+Не считаются модулями:
+
+- `ui/`, `parts/`, `hooks/`, `types/`, `styles/`, `config/` — это сегменты.
+- `screens/shop/`, `business/commerce/` — это группы, если в них нет `index.ts`.
+- `screens/home/ui/user-card/` — это компонент, если он находится в `ui/` и соблюдает ограничения компонента.
+
+## Типы модулей
+
+Тип модуля определяет обязательный корневой файл и стартовую структуру.
+
+### UI-модуль
+
+Модуль строится вокруг основного UI-компонента и обязан иметь основной `.tsx` файл в корне:
+
+```text
+header/
+├── header.tsx
+└── index.ts
+```
+
+`ui/` внутри такого модуля используется только для компонентов, которые помогают корневому `.tsx` файлу.
+
+### Бизнес-модуль
+
+Бизнес-модуль — модуль, который строится вокруг публичного runtime API.
+
+Бизнес-модуль обязан иметь фабрику в корне:
+
+```text
+auth/
+├── auth.factory.ts
+├── index.ts
+└── types/
+```
+
+Фабрика возвращает публичный runtime API модуля.
+
+### Инфраструктурный модуль
+
+Инфраструктурный модуль — модуль, который строится вокруг технического сервиса или интеграции.
+
+Инфраструктурный модуль не обязан иметь фиксированный корневой файл. Его структура определяется природой сервиса.
+
+```text
+theme/
+├── index.ts
+├── config/
+├── hooks/
+├── styles/
+└── ui/
+```
+
+```text
+backend-api/
+├── backend-api.client.ts
+├── config/
+├── types/
+└── index.ts
+```
+
+## Структура
+
+Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль включает только те части, которые нужны его ответственности.
+
+```text
+{module-name}/
+├── {module-name}.factory.ts     # фабрика (для business-модулей)
+├── {module-name}.tsx            # корневой файл модуля (опционален)
+├── ui/                          # компоненты модуля
+├── parts/                       # вложенные модули
+├── hooks/                       # хуки
+├── stores/                      # сторы состояния
+├── services/                    # внешние источники данных
+├── mappers/                     # трансформация данных между форматами
+├── types/                       # типы
+├── styles/                      # стили
+├── lib/                         # утилиты модуля
+├── config/                      # константы и конфигурация
+└── index.ts                     # публичный API
+```
+
+Подробное описание сегментов — в разделе [Сегменты](/architecture/segments).
+
+## Публичный API
+
+Внешний код импортирует модуль только через публичный API.
+
+```ts
+// Хорошо
+import { customerFactory } from '@/business/customer'
+import type { Customer } from '@/business/customer'
+```
+
+```ts
+// Плохо
+import { validateToken } from '@/business/auth/lib/tokens'
+```
+
+`index.ts` модуля не обязан экспортировать всё содержимое. Он экспортирует только то, что действительно нужно снаружи.
+
+Внутренние сегменты модуля остаются деталями реализации.
+
+Business-модуль экспортирует из `index.ts` только фабрику и type-only экспорты. Хуки, компоненты, сервисы, мапперы и утилиты напрямую из `index.ts` не экспортируются — они доступны через API, который возвращает фабрика.
+
+```ts
+// business/customer/index.ts
+export { customerFactory } from './customer.factory'
+
+export type { Customer } from './types/customer.type'
+export type { CustomerApi } from './types/customer-api.type'
+export type { CustomerDeps } from './types/customer-deps.type'
+export type { CustomerFactory } from './types/customer-factory.type'
+```
+
+## Фабрика
+
+Business-модуль всегда экспортирует фабрику. Фабрика лежит в корне модуля (`{name}.factory.ts`), типизируется через `{Name}Factory` и возвращает публичный runtime API модуля.
+
+Всё, что нужно внешнему коду в runtime, должно быть частью API, который возвращает фабрика.
+
+Модуль без cross-domain зависимостей экспортирует фабрику без аргументов. Модуль с зависимостями — фабрику, принимающую зависимости доменными именами. Типы всегда экспортируются напрямую через `export type` — `import type` не является runtime-зависимостью.
+
+Компоновка фабрик происходит на уровне модуля-потребителя: screen, layout, widget или любой другой модуль группы «Композиция».
+
+### Структура business-модуля
+
+```text
+business/customer/
+├── customer.factory.ts
+├── index.ts
+└── types/
+    ├── customer.type.ts
+    ├── customer-api.type.ts
+    ├── customer-deps.type.ts
+    └── customer-factory.type.ts
+```
+
+### Типы
+
+```ts
+// business/customer/types/customer-api.type.ts
+export type CustomerApi = {
+  useCustomer: () => Customer
+  CustomerCard: (props: CustomerCardProps) => ReactNode
+}
+```
+
+```ts
+// business/order/types/order-deps.type.ts
+export type OrderDeps = {
+  customer: Pick<CustomerApi, 'useCustomer'>
+}
+```
+
+```ts
+// business/order/types/order-factory.type.ts
+export type OrderFactory = (deps: OrderDeps) => OrderApi
+```
+
+### Фабрика без зависимостей
+
+```ts
+// business/customer/customer.factory.ts
+import type { CustomerFactory } from './types/customer-factory.type'
+
+export const customerFactory: CustomerFactory = () => {
+  return {
+    useCustomer,
+    CustomerCard,
+  }
+}
+```
+
+### Фабрика с зависимостями
+
+```ts
+// business/order/order.factory.ts
+import type { OrderFactory } from './types/order-factory.type'
+
+export const orderFactory: OrderFactory = (deps) => {
+  return {
+    useOrder,
+    OrderCard,
+  }
+}
+```
+
+### Композиция на уровне screen
+
+```tsx
+// screens/home/home.screen.tsx
+import { customerFactory } from '@/business/customer'
+import { orderFactory } from '@/business/order'
+
+const customer = customerFactory()
+const order = orderFactory({ customer })
+
+const { useOrder, OrderCard } = order
+
+export const HomeScreen = () => {
+  const currentOrder = useOrder()
+
+  return <OrderCard order={currentOrder} />
+}
+```
+
+## Жизненный цикл
+
+Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
+
+- Нужен на одной странице → `screens/{name}/parts/`
+- Появился в 2+ местах → поднимается по природе:
+  - абстрактный UI → `ui/`
+  - блок с данными/логикой → `widgets/`
+  - представление бизнес-домена → `business/{area}/parts/`
+
+Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.

docs/architecture/segments.md

@@ -1,5 +1,6 @@
 ---
 title: Сегменты
+description: Сегменты внутри модуля (ui/, model/, lib/ и др.), назначение и правила размещения файлов
 ---
 
 # Сегменты
@@ -14,7 +15,7 @@ title: Сегменты
 
 | Сегмент | Содержимое |
 |---------|------------|
-| `ui/` | Компоненты модуля — только `.tsx` файлы |
+| `ui/` | Презентационные компоненты родительского модуля |
 | `parts/` | Вложенные модули со своими сегментами |
 | `hooks/` | React-хуки |
 | `stores/` | Сторы состояния |
@@ -27,24 +28,48 @@ title: Сегменты
 
 ## Сегмент ui/
 
-Компоненты, принадлежащие модулю. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков. Использует сегменты родительского модуля.
+Презентационные компоненты родительского модуля. `ui/` содержит только компоненты, которые отвечают за отображение части интерфейса и не выходят за границы своего модуля.
+
+Компонент в `ui/`:
+
+- Находится в собственной папке.
+- Может содержать только `{name}.tsx`, `index.ts`, `styles/`, `types/`.
+- Не содержит любые компоненты.
+- Не содержит любые модули.
+- Не импортирует код проекта за пределами родительского модуля.
+- Не делает внешние запросы.
+- Не вызывает сценарные хуки.
+- Не получает данные самостоятельно, не выбирает источник данных и не композирует данные.
+- Не содержит бизнес-логику или сценарную логику.
+
+Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе [Компонент](/architecture/modules#компонент).
+
+Корневой файл модуля в `ui/` не размещается. Он лежит в корне модуля: `{module-name}.tsx`.
 
 ```text
-auth/
+user/
 ├── ui/
-│   ├── auth-provider.tsx
+│   ├── user-avatar/
-│   ├── auth-guard.tsx
+│   │   ├── user-avatar.tsx
-│   └── logout-button.tsx
+│   │   ├── styles/
+│   │   │   └── user-avatar.module.css
+│   │   ├── types/
+│   │   │   └── user-avatar-props.type.ts
+│   │   └── index.ts
+│   └── user-status/
+│       ├── user-status.tsx
+│       └── index.ts
 ├── types/
 ├── hooks/
+├── user.tsx
 └── index.ts
 ```
 
-Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
+Если UI-сущности нужна внутренняя декомпозиция, сценарная логика, получение данных или собственные архитектурные зависимости — это уже не компонент в `ui/`, а модуль в `parts/`.
 
 ## Сегмент parts/
 
-Вложенные модули со своими сегментами. Каждый элемент `parts/` — полноценный модуль: папка с компонентом, хуками, стилями, типами и т.д.
+Вложенные модули со своими сегментами. `parts/` содержит только модули: каждый элемент `parts/` — папка полноценного модуля с собственным публичным API. Отдельные `.tsx`, стили, хуки или произвольные файлы в `parts/` не размещаются.
 
 ```text
 home/
@@ -52,17 +77,20 @@ home/
 │   ├── hero-section/
 │   │   ├── hero-section.tsx
 │   │   ├── styles/
-│   │   └── parts/
+│   │   ├── parts/
-│   │       └── top-banner/
+│   │   │   └── top-banner/
-│   │           └── top-banner.tsx
+│   │   │       ├── top-banner.tsx
+│   │   │       └── index.ts
+│   │   └── index.ts
 │   └── features-section/
 │       ├── features-section.tsx
-│       └── hooks/
+│       ├── hooks/
+│       └── index.ts
 ├── home.screen.tsx
 └── index.ts
 ```
 
-Отличие от `ui/`: элемент `parts/` — модуль со своими сегментами. Элемент `ui/` — компонент, один `.tsx` файл.
+Отличие от `ui/`: элемент `parts/` — модульная папка со своими сегментами. Элемент `ui/` — компонент родительского модуля без собственной архитектурной ответственности.
 
 Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
 

docs/en/architecture/edge-cases.md

@@ -1,5 +0,0 @@
----
-title: Edge Cases
----
-
-# Edge Cases

docs/en/architecture/layers.md

@@ -1,5 +0,0 @@
----
-title: Layers
----
-
-# Layers

docs/en/architecture/module.md

@@ -1,5 +0,0 @@
----
-title: Module
----
-
-# Module

docs/en/architecture/overview.md

@@ -1,7 +0,0 @@
----
-title: Overview
----
-
-# Overview
-
-Architecture based on SLM Design (Scoped Layered Module Design) and strict module boundaries.

docs/en/architecture/rationale.md

@@ -1,5 +0,0 @@
----
-title: Rationale
----
-
-# Rationale

docs/en/architecture/terminology.md

@@ -1,5 +0,0 @@
----
-title: Terminology
----
-
-# Terminology

docs/en/index.md

@@ -1,7 +0,0 @@
-# SLM Design
-
-Project architecture rules and standards.
-
-## For Assistants
-
-Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-guide/raw/branch/main/generated/en/RULES.md

docs/index.md

@@ -0,0 +1,29 @@
+---
+title: Документация
+---
+
+# Документация
+
+Раздел помогает быстро найти нужное правило SLM Design. Здесь собраны маршруты чтения, карта разделов и ссылки на материалы для AI-ассистентов.
+
+## С чего начать
+
+- Если вы знакомитесь с подходом впервые — начните с [SLM Design](/architecture/).
+- Если проектируете структуру `src/` — откройте [Слои](/architecture/layers).
+- Если создаёте новый домен или блок интерфейса — используйте [Модули](/architecture/modules).
+- Если выбираете папку внутри модуля — смотрите [Сегменты](/architecture/segments).
+
+## Разделы
+
+| Раздел | Когда открывать |
+|--------|----------------|
+| [SLM Design](/architecture/) | Нужно понять общую идею архитектуры и контекст правил. |
+| [Слои](/architecture/layers) | Нужно определить, где должен жить код и какие зависимости допустимы. |
+| [Модули](/architecture/modules) | Нужно оформить границы модуля, публичный API или фабрику. |
+| [Сегменты](/architecture/segments) | Нужно выбрать внутреннюю папку для компонента, хука, стиля, типа или конфига. |
+
+## Для ассистентов
+
+- `/llms.txt` — краткая карта документации.
+- `/llms-full.txt` — полный контекст архитектуры.
+- `/slm-design.zip` — архив Markdown-файлов.

docs/ru/reference/modules.md

@@ -1,164 +0,0 @@
----
-title: Модули
----
-
-# Модули
-
-Раздел описывает модули SLM: что такое модуль, из чего он состоит и как взаимодействует с остальным кодом.
-
-## Определение
-
-**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
-
-## Модуль vs компонент
-
-**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
-
-**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
-
-```text
-auth/                              
-├── ui/
-│   ├── auth-guard.tsx
-│   └── logout-button.tsx
-├── parts/
-│   ├── login-form/
-│   ├── registration-form/
-│   └── restore-form/
-├── hooks/
-├── stores/
-├── types/
-├── auth.tsx             # корневой компонент (опционален)
-└── index.ts
-```
-
-## Структура
-
-Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
-
-```text
-{module-name}/
-├── {module-name}.tsx            # корневой компонент (опционален)
-├── ui/                          # компоненты модуля (только .tsx)
-├── parts/                       # вложенные модули (со своими сегментами)
-├── hooks/                       # хуки
-├── stores/                      # сторы состояния
-├── services/                    # внешние источники данных
-├── mappers/                     # трансформация данных между форматами
-├── types/                       # типы
-├── styles/                      # стили
-├── lib/                         # утилиты модуля
-├── config/                      # константы
-└── index.ts                     # публичный API
-```
-
-Подробное описание каждого сегмента — в разделе [Сегменты](/reference/segments).
-
-## Публичный API
-
-Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
-
-```ts
-// business/auth/index.ts
-export type { User, Session } from './types/user.types'
-export { useAuth } from './hooks/use-auth.hook'
-export { AuthGuard } from './ui/auth-guard'
-```
-
-Импорт в обход `index.ts` запрещён:
-
-```ts
-// Плохо
-import { validateToken } from '@/business/auth/lib/tokens'
-
-// Хорошо
-import { useAuth } from '@/business/auth'
-```
-
-## Фабрика
-
-Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
-
-Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
-
-### Модуль без зависимостей — прямой экспорт:
-
-```ts
-// business/auth/index.ts
-export { useAuth } from './hooks/use-auth'
-export { useCurrentUser } from './hooks/use-current-user'
-export type { User, Session } from './types'
-```
-
-### Модуль с зависимостями — фабрика:
-
-```ts
-// business/chat/types/deps.ts
-import type { User } from '@/business/auth'
-
-export interface ChatDeps {
-  useCurrentUser: () => User | null
-}
-```
-
-```ts
-// business/chat/index.ts
-import type { ChatDeps } from './types/deps'
-
-export function chatFactory(deps: ChatDeps) {
-  return {
-    useMessages: (roomId: string) => {
-      const user = deps.useCurrentUser()
-      // ...
-    },
-    useSendMessage: (roomId: string) => {
-      const user = deps.useCurrentUser()
-      return (text: string) => { /* ... */ }
-    },
-    useChatRooms: () => {
-      const user = deps.useCurrentUser()
-      // ...
-    },
-    ChatBadge: ({ count }: { count: number }) => { /* ... */ },
-  }
-}
-
-export type { Message, ChatRoom } from './types'
-export type { ChatDeps } from './types/deps'
-```
-
-### Использование на странице:
-
-```tsx
-// screens/support/support.tsx
-import { useCurrentUser } from '@/business/auth'
-import { chatFactory } from '@/business/chat'
-
-const chat = chatFactory({ useCurrentUser })
-
-export function SupportScreen() {
-  const { useMessages, useSendMessage, ChatBadge } = chat
-  const messages = useMessages('support')
-  const sendMessage = useSendMessage('support')
-
-  return (
-    <div>
-      <ChatBadge count={messages.length} />
-      {messages.map(m => <MessageBubble key={m.id} {...m} />)}
-      <MessageInput onSend={sendMessage} />
-    </div>
-  )
-}
-```
-
-## Жизненный цикл
-
-Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
-
-- Нужен на одной странице → `screens/{name}/parts/`
-- Появился в 2+ местах → поднимается по природе:
-  - абстрактный UI → `ui/`
-  - блок с данными/логикой → `widgets/`
-  - представление бизнес-домена → `business/{area}/parts/`
-
-Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.

generate.ts

@@ -0,0 +1,185 @@
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { execFileSync } from "child_process";
+
+const SRC_DIR = "./docs";
+const PUBLIC_DIR = "./public";
+const PUBLIC_ARCHITECTURE_FILE = "ARCHITECTURE.md";
+
+interface SidebarItem {
+  text: string;
+  link: string;
+}
+
+interface SidebarGroup {
+  text: string;
+  items: SidebarItem[];
+}
+
+function parseSidebar(): SidebarGroup[] {
+  const configPath = path.join(".vitepress", "config.ts");
+  const raw = fs.readFileSync(configPath, "utf8");
+  const start = raw.indexOf("const sidebar = [");
+  const end = raw.indexOf("];", start) + 2;
+  const section = raw.substring(start, end);
+
+  const groups: SidebarGroup[] = [];
+  const groupParts = section.split(/\n\s*\}\s*,?\s*\n/).filter(Boolean);
+
+  for (const part of groupParts) {
+    const textMatch = part.match(/text:\s*'([^']*)'/);
+    if (!textMatch) continue;
+    const items: SidebarItem[] = [];
+    const itemRe = /\{\s*text:\s*'([^']*)'\s*,\s*link:\s*'([^']*)'\s*\}/g;
+    let im: RegExpExecArray | null;
+    while ((im = itemRe.exec(part)) !== null) {
+      items.push({ text: im[1], link: im[2] });
+    }
+    if (items.length > 0) groups.push({ text: textMatch[1], items });
+  }
+  return groups;
+}
+
+const SIDEBAR = parseSidebar();
+
+function getAllFiles(): string[] {
+  return SIDEBAR.flatMap((g) =>
+    g.items.map((item) => {
+      const rel = item.link.replace(/^\//, "") + ".md";
+      const indexPath = rel.replace(/\.md$/, "/index.md");
+      const filePath = path.join(SRC_DIR, indexPath);
+      return fs.existsSync(filePath) ? indexPath : rel;
+    })
+  );
+}
+
+const stripFrontmatter = (content: string) =>
+  content.replace(/^---[\s\S]*?---\n*/m, "");
+
+const stripRulesLink = (content: string) =>
+  content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");
+
+const shiftHeadings = (content: string) => {
+  const lines = content.split("\n");
+  let inCodeBlock = false;
+  return lines
+    .map((line) => {
+      if (line.startsWith("```")) inCodeBlock = !inCodeBlock;
+      if (inCodeBlock) return line;
+      if (/^#{1,5}\s/.test(line)) return "#" + line;
+      return line;
+    })
+    .join("\n");
+};
+
+const buildArchitectureMarkdown = (routePrefix: string) => {
+  const files = getAllFiles();
+  const parts: string[] = [];
+
+  for (const file of files) {
+    const filePath = path.join(SRC_DIR, file);
+    if (!fs.existsSync(filePath)) continue;
+    const raw = fs.readFileSync(filePath, "utf8");
+    const content = stripRulesLink(stripFrontmatter(raw)).trim();
+    if (!content) continue;
+
+    const route = routePrefix + "/" + file.replace(/\.md$/, "");
+    const processed = file.endsWith("index.md") ? content : shiftHeadings(content);
+    parts.push(`<!-- ${route} -->\n${processed}`);
+  }
+
+  return parts.join("\n\n");
+};
+
+function buildLlms() {
+  const parts: string[] = [`# SLM Design\n`];
+  parts.push(`> Scoped Layered Module Design — модульная архитектура фронтенд-приложений\n`);
+
+  for (const group of SIDEBAR) {
+    parts.push(`## ${group.text}`);
+    for (const item of group.items) {
+      const rel = item.link.replace(/^\//, "") + ".md";
+      const indexPath = rel.replace(/\.md$/, "/index.md");
+      const fileRel = fs.existsSync(path.join(SRC_DIR, indexPath)) ? indexPath : rel;
+      const filePath = path.join(SRC_DIR, fileRel);
+      let desc = "";
+      if (fs.existsSync(filePath)) {
+        const raw = fs.readFileSync(filePath, "utf8");
+        const fm = raw.match(/^---[\s\S]*?---\n*/m);
+        desc = fm ? fm[0].match(/description:\s*(.+)/)?.[1] || "" : "";
+      }
+      const route = "/docs" + item.link;
+      const line = desc
+        ? `- [${item.text}](${route}): ${desc}`
+        : `- [${item.text}](${route})`;
+      parts.push(line);
+    }
+    parts.push("");
+  }
+
+  const outPath = path.join(PUBLIC_DIR, "llms.txt");
+  fs.mkdirSync(PUBLIC_DIR, { recursive: true });
+  fs.writeFileSync(outPath, parts.join("\n"), "utf8");
+  console.log(`llms.txt создан: ${outPath}`);
+}
+
+function buildLlmsFull() {
+  const outPath = path.join(PUBLIC_DIR, "llms-full.txt");
+  fs.writeFileSync(outPath, buildArchitectureMarkdown("/docs"), "utf8");
+  console.log(`llms-full.txt создан: ${outPath}`);
+}
+
+function buildPublicArchitecture() {
+  const outPath = path.join(PUBLIC_DIR, PUBLIC_ARCHITECTURE_FILE);
+  fs.mkdirSync(PUBLIC_DIR, { recursive: true });
+  fs.writeFileSync(outPath, buildArchitectureMarkdown("/docs"), "utf8");
+  console.log(`${PUBLIC_ARCHITECTURE_FILE} создан: ${outPath}`);
+}
+
+function buildZip() {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "slm-"));
+  const tmpDir = path.join(tmpRoot, "slm-design");
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  const files = getAllFiles();
+  for (const file of files) {
+    const src = path.join(SRC_DIR, file);
+    if (!fs.existsSync(src)) continue;
+    let content = fs.readFileSync(src, "utf8");
+    content = stripRulesLink(stripFrontmatter(content)).trim();
+    const destName = path.basename(file);
+    fs.writeFileSync(path.join(tmpDir, destName), content, "utf8");
+  }
+
+  const pkg = JSON.parse(fs.readFileSync("./package.json", "utf8"));
+  const version = `v${pkg.version}`;
+  fs.writeFileSync(path.join(tmpDir, "VERSION"), `${version}\n${new Date().toISOString()}\n`, "utf8");
+
+  const outPath = path.resolve(PUBLIC_DIR, "slm-design.zip");
+  fs.mkdirSync(PUBLIC_DIR, { recursive: true });
+  if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
+
+  execFileSync("zip", ["-rq", outPath, "slm-design"], { cwd: tmpRoot });
+  fs.rmSync(tmpRoot, { recursive: true });
+  console.log(`slm-design.zip создан: ${outPath}`);
+}
+
+function buildReadme() {
+  const indexPath = path.join(SRC_DIR, "architecture/index.md");
+  if (!fs.existsSync(indexPath)) {
+    console.log("Пропуск README: index.md не найден");
+    return;
+  }
+
+  let content = stripFrontmatter(fs.readFileSync(indexPath, "utf8"));
+  content = content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");
+  fs.writeFileSync("./README.md", content, "utf8");
+  console.log("README.md создан");
+}
+
+buildLlms();
+buildLlmsFull();
+buildPublicArchitecture();
+buildZip();
+buildReadme();

generated/en/ARCHITECTURE.md

@@ -1,8 +0,0 @@
-<!-- /index -->
-# SLM Design
-
-Project architecture rules and standards.
-
-## For Assistants
-
-Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-guide/raw/branch/main/generated/en/RULES.md

index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SLM Design</title>
+    <meta name="description" content="Scoped Layered Module Design — модульная архитектура фронтенд-приложений" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package.json

@@ -2,15 +2,24 @@
   "name": "slm-design",
   "private": true,
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.1.5",
   "scripts": {
-    "docs": "node ./concat-md.js",
+    "dev": "vite",
-    "dev": "vitepress dev .",
+    "build": "vite build",
-    "build": "vitepress build .",
+    "preview": "vite preview",
-    "serve": "vitepress serve ."
+    "docs:dev": "vitepress dev . --port 5174",
+    "docs:build": "vitepress build .",
+    "generate": "tsx ./generate.ts"
   },
-  "dependencies": {},
   "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "tsx": "^4.21.0",
     "vitepress": "^1.6.3"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   }
 }

public/ARCHITECTURE.md

@@ -1,4 +1,4 @@
-<!-- /index -->
+<!-- /docs/architecture//index -->
 # SLM Design
 Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
 
@@ -8,9 +8,13 @@ Scoped Layered Module Design — модульная архитектура фр
 
 Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
 
+### Dependency Injection без фреймворков
+
+Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
+
 ### Разделение ответственности без перегрузки слоёв
 
-Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
+Сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
 
 ### Горизонтальная инкапсуляция
 
@@ -28,10 +32,6 @@ Scoped Layered Module Design — модульная архитектура фр
 
 При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
 
-### Dependency Injection без фреймворков
-
-Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
-
 ## Происхождение
 
 SLM Design вырос на основе:
@@ -68,7 +68,7 @@ src/
 │   ├── orders/
 │   └── chat/
 │
-├── infrastructure/
+├── infra/
 │   ├── theme/
 │   ├── i18n/
 │   ├── backend-api/
@@ -94,7 +94,7 @@ src/
 - **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
 - **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
 
-<!-- /reference/layers -->
+<!-- /docs/architecture/layers -->
 ## Слои
 
 Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом.
@@ -110,7 +110,7 @@ src/
 | Группа | Слои | Описание |
 |--------|------|----------|
 | Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
-| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
+| Ядро | `business`, `infra`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
 | Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
 
 ### Направление зависимостей
@@ -118,12 +118,12 @@ src/
 Любой импорт между модулями — только через публичный API.
 
 ```
-app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
+app → [ layouts | screens ] → widgets → business → infra → ui → shared
 ```
 
 - `layouts` и `screens` — параллельные слои, не импортируют друг друга
 - Модули одного слоя в группе «Композиция» изолированы друг от друга
-- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
+- Модули одного слоя `infra` и `ui` могут импортировать друг друга через публичный API
 - Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
 - Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
 
@@ -221,7 +221,7 @@ src/widgets/
 
 Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
 
-Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
+Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`. Каждый бизнес-модуль создаёт публичный runtime API через фабрику в корне. Cross-domain зависимости: runtime — через аргументы фабрики, типы — напрямую через `import type`.
 
 Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
 
@@ -252,19 +252,20 @@ src/business/
 
 - Один модуль = один бизнес-домен
 - Циклические зависимости между доменами запрещены
-- Импорт кода между доменами — через фабрику. `import type` — напрямую
+- Публичный runtime API — через фабрику в корне модуля (`{name}.factory.ts`). `index.ts` экспортирует только фабрику и type-only экспорты
+- Импорт runtime-кода между доменами — через фабрику. `import type` — напрямую
 - Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
 
-### Слой Infrastructure
+### Слой infra
 
 Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
 
-Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
+Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`.
 
-Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
+Отличие от `shared/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
 
 ```text
-src/infrastructure/
+src/infra/
 ├── theme/
 ├── i18n/
 ├── backend-api/
@@ -277,7 +278,7 @@ src/infrastructure/
 #### Требования
 
 - Один модуль = один техсервис
-- Импортирует `infrastructure/`, `ui/`, `shared/`
+- Импортирует `infra/`, `ui/`, `shared/`
 
 ### Слой UI
 
@@ -328,7 +329,7 @@ src/ui/
 
 Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
 
-Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
+Отличие от `infra/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
 
 Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
 
@@ -344,46 +345,144 @@ src/shared/
 
 - Не имеет runtime-состояния
 
-<!-- /reference/modules -->
+<!-- /docs/architecture/modules -->
 ## Модули
 
-Раздел описывает модули SLM: что такое модуль, из чего он состоит и как взаимодействует с остальным кодом.
+Раздел описывает модуль как границу ответственности в SLM: что считается модулем, что такое компонент внутри модуля и как модуль взаимодействует с остальным кодом.
 
 ### Определение
 
-**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
+**Модуль — минимальная архитектурная единица SLM. Он живёт на одном из слоёв, владеет конкретной областью ответственности и предоставляет наружу только публичный API.**
 
-### Модуль vs компонент
+Модуль может содержать всё, что нужно этой области: компоненты, вложенные модули, хуки, сторы, сервисы, типы, стили, конфиги и утилиты. Набор сегментов не фиксирован — модуль включает только то, что реально нужно.
 
-**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
+Модуль не обязан быть UI-блоком. Это может быть страница, виджет, бизнес-домен, инфраструктурный сервис или UI-kit сущность.
 
-**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
+Главная граница модуля — не папка, а ответственность.
+
+### Компонент
+
+**Компонент — презентационная единица модуля, которая находится только в `ui/` своего родительского модуля и отвечает за отображение части интерфейса.**
+
+Компонент не является архитектурной единицей: он не владеет сценарием, зависимостями, данными или внутренней структурой. Он работает только внутри границы родительского модуля.
+
+> Компонент отображает. Модуль организует.
+
+Компонент не может:
+
+- Импортировать код проекта за пределами родительского модуля.
+- Владеть архитектурными зависимостями.
+- Содержать любые компоненты.
+- Содержать любые модули.
+- Делать внешние запросы.
+- Самостоятельно получать данные.
+- Выбирать источник данных.
+- Композировать данные.
+- Вызывать сценарные хуки.
+- Оркестрировать сценарий.
+- Композировать модули.
+- Решать, как устроен процесс.
+- Содержать бизнес-логику.
+- Содержать сценарную логику.
+
+Если компоненту требуется что-то из этого списка, он перестаёт быть компонентом и должен быть оформлен как модуль.
 
 ```text
 auth/
 ├── ui/
-│   ├── auth-guard.tsx
+│   └── logout-button/
-│   └── logout-button.tsx
+│       ├── logout-button.tsx
-├── parts/
+│       ├── styles/
-│   ├── login-form/
+│       │   └── logout-button.module.css
-│   ├── registration-form/
+│       ├── types/
-│   └── restore-form/
+│       │   └── logout-button-props.type.ts
+│       └── index.ts
+└── index.ts
+```
+
+### Что считается модулем
+
+Модулем считается папка, которая представляет самостоятельную область ответственности и имеет публичную границу.
+
+Примеры модулей:
+
+- `screens/home/` — модуль страницы.
+- `widgets/page-heading/` — модуль виджета.
+- `business/auth/` — модуль бизнес-домена.
+- `infra/theme/` — модуль инфраструктурного сервиса.
+- `ui/button/` — модуль UI-kit сущности.
+- `screens/home/parts/hero-section/` — вложенный модуль страницы.
+
+Не считаются модулями:
+
+- `ui/`, `parts/`, `hooks/`, `types/`, `styles/`, `config/` — это сегменты.
+- `screens/shop/`, `business/commerce/` — это группы, если в них нет `index.ts`.
+- `screens/home/ui/user-card/` — это компонент, если он находится в `ui/` и соблюдает ограничения компонента.
+
+### Типы модулей
+
+Тип модуля определяет обязательный корневой файл и стартовую структуру.
+
+#### UI-модуль
+
+Модуль строится вокруг основного UI-компонента и обязан иметь основной `.tsx` файл в корне:
+
+```text
+header/
+├── header.tsx
+└── index.ts
+```
+
+`ui/` внутри такого модуля используется только для компонентов, которые помогают корневому `.tsx` файлу.
+
+#### Бизнес-модуль
+
+Бизнес-модуль — модуль, который строится вокруг публичного runtime API.
+
+Бизнес-модуль обязан иметь фабрику в корне:
+
+```text
+auth/
+├── auth.factory.ts
+├── index.ts
+└── types/
+```
+
+Фабрика возвращает публичный runtime API модуля.
+
+#### Инфраструктурный модуль
+
+Инфраструктурный модуль — модуль, который строится вокруг технического сервиса или интеграции.
+
+Инфраструктурный модуль не обязан иметь фиксированный корневой файл. Его структура определяется природой сервиса.
+
+```text
+theme/
+├── index.ts
+├── config/
 ├── hooks/
-├── stores/
+├── styles/
+└── ui/
+```
+
+```text
+backend-api/
+├── backend-api.client.ts
+├── config/
 ├── types/
-├── auth.tsx             # корневой компонент (опционален)
 └── index.ts
 ```
 
 ### Структура
 
-Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
+Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль включает только те части, которые нужны его ответственности.
 
 ```text
 {module-name}/
-├── {module-name}.tsx            # корневой компонент (опционален)
+├── {module-name}.factory.ts     # фабрика (для business-модулей)
-├── ui/                          # компоненты модуля (только .tsx)
+├── {module-name}.tsx            # корневой файл модуля (опционален)
-├── parts/                       # вложенные модули (со своими сегментами)
+├── ui/                          # компоненты модуля
+├── parts/                       # вложенные модули
 ├── hooks/                       # хуки
 ├── stores/                      # сторы состояния
 ├── services/                    # внешние источники данных
@@ -391,106 +490,132 @@ auth/
 ├── types/                       # типы
 ├── styles/                      # стили
 ├── lib/                         # утилиты модуля
-├── config/                      # константы
+├── config/                      # константы и конфигурация
 └── index.ts                     # публичный API
 ```
 
-Подробное описание каждого сегмента — в разделе [Сегменты](/reference/segments).
+Подробное описание сегментов — в разделе [Сегменты](/architecture/segments).
 
 ### Публичный API
 
-Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
+Внешний код импортирует модуль только через публичный API.
 
 ```ts
-// business/auth/index.ts
+// Хорошо
-export type { User, Session } from './types/user.types'
+import { customerFactory } from '@/business/customer'
-export { useAuth } from './hooks/use-auth.hook'
+import type { Customer } from '@/business/customer'
-export { AuthGuard } from './ui/auth-guard'
 ```
 
-Импорт в обход `index.ts` запрещён:
-
 ```ts
 // Плохо
 import { validateToken } from '@/business/auth/lib/tokens'
+```
 
-// Хорошо
+`index.ts` модуля не обязан экспортировать всё содержимое. Он экспортирует только то, что действительно нужно снаружи.
-import { useAuth } from '@/business/auth'
+
+Внутренние сегменты модуля остаются деталями реализации.
+
+Business-модуль экспортирует из `index.ts` только фабрику и type-only экспорты. Хуки, компоненты, сервисы, мапперы и утилиты напрямую из `index.ts` не экспортируются — они доступны через API, который возвращает фабрика.
+
+```ts
+// business/customer/index.ts
+export { customerFactory } from './customer.factory'
+
+export type { Customer } from './types/customer.type'
+export type { CustomerApi } from './types/customer-api.type'
+export type { CustomerDeps } from './types/customer-deps.type'
+export type { CustomerFactory } from './types/customer-factory.type'
 ```
 
 ### Фабрика
 
-Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
+Business-модуль всегда экспортирует фабрику. Фабрика лежит в корне модуля (`{name}.factory.ts`), типизируется через `{Name}Factory` и возвращает публичный runtime API модуля.
 
-Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
+Всё, что нужно внешнему коду в runtime, должно быть частью API, который возвращает фабрика.
 
-#### Модуль без зависимостей — прямой экспорт:
+Модуль без cross-domain зависимостей экспортирует фабрику без аргументов. Модуль с зависимостями — фабрику, принимающую зависимости доменными именами. Типы всегда экспортируются напрямую через `export type` — `import type` не является runtime-зависимостью.
 
-```ts
+Компоновка фабрик происходит на уровне модуля-потребителя: screen, layout, widget или любой другой модуль группы «Композиция».
-// business/auth/index.ts
+
-export { useAuth } from './hooks/use-auth'
+#### Структура business-модуля
-export { useCurrentUser } from './hooks/use-current-user'
+
-export type { User, Session } from './types'
+```text
+business/customer/
+├── customer.factory.ts
+├── index.ts
+└── types/
+    ├── customer.type.ts
+    ├── customer-api.type.ts
+    ├── customer-deps.type.ts
+    └── customer-factory.type.ts
 ```
 
-#### Модуль с зависимостями — фабрика:
+#### Типы
 
 ```ts
-// business/chat/types/deps.ts
+// business/customer/types/customer-api.type.ts
-import type { User } from '@/business/auth'
+export type CustomerApi = {
-
+  useCustomer: () => Customer
-export interface ChatDeps {
+  CustomerCard: (props: CustomerCardProps) => ReactNode
-  useCurrentUser: () => User | null
 }
 ```
 
 ```ts
-// business/chat/index.ts
+// business/order/types/order-deps.type.ts
-import type { ChatDeps } from './types/deps'
+export type OrderDeps = {
+  customer: Pick<CustomerApi, 'useCustomer'>
+}
+```
 
-export function chatFactory(deps: ChatDeps) {
+```ts
+// business/order/types/order-factory.type.ts
+export type OrderFactory = (deps: OrderDeps) => OrderApi
+```
+
+#### Фабрика без зависимостей
+
+```ts
+// business/customer/customer.factory.ts
+import type { CustomerFactory } from './types/customer-factory.type'
+
+export const customerFactory: CustomerFactory = () => {
   return {
-    useMessages: (roomId: string) => {
+    useCustomer,
-      const user = deps.useCurrentUser()
+    CustomerCard,
-      // ...
-    },
-    useSendMessage: (roomId: string) => {
-      const user = deps.useCurrentUser()
-      return (text: string) => { /* ... */ }
-    },
-    useChatRooms: () => {
-      const user = deps.useCurrentUser()
-      // ...
-    },
-    ChatBadge: ({ count }: { count: number }) => { /* ... */ },
   }
 }
-
-export type { Message, ChatRoom } from './types'
-export type { ChatDeps } from './types/deps'
 ```
 
-#### Использование на странице:
+#### Фабрика с зависимостями
+
+```ts
+// business/order/order.factory.ts
+import type { OrderFactory } from './types/order-factory.type'
+
+export const orderFactory: OrderFactory = (deps) => {
+  return {
+    useOrder,
+    OrderCard,
+  }
+}
+```
+
+#### Композиция на уровне screen
 
 ```tsx
-// screens/support/support.tsx
+// screens/home/home.screen.tsx
-import { useCurrentUser } from '@/business/auth'
+import { customerFactory } from '@/business/customer'
-import { chatFactory } from '@/business/chat'
+import { orderFactory } from '@/business/order'
 
-const chat = chatFactory({ useCurrentUser })
+const customer = customerFactory()
+const order = orderFactory({ customer })
 
-export function SupportScreen() {
+const { useOrder, OrderCard } = order
-  const { useMessages, useSendMessage, ChatBadge } = chat
-  const messages = useMessages('support')
-  const sendMessage = useSendMessage('support')
 
-  return (
+export const HomeScreen = () => {
-    <div>
+  const currentOrder = useOrder()
-      <ChatBadge count={messages.length} />
+
-      {messages.map(m => <MessageBubble key={m.id} {...m} />)}
+  return <OrderCard order={currentOrder} />
-      <MessageInput onSend={sendMessage} />
-    </div>
-  )
 }
 ```
 
@@ -506,7 +631,7 @@ export function SupportScreen() {
 
 Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
 
-<!-- /reference/segments -->
+<!-- /docs/architecture/segments -->
 ## Сегменты
 
 Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит.
@@ -519,7 +644,7 @@ export function SupportScreen() {
 
 | Сегмент | Содержимое |
 |---------|------------|
-| `ui/` | Компоненты модуля — только `.tsx` файлы |
+| `ui/` | Презентационные компоненты родительского модуля |
 | `parts/` | Вложенные модули со своими сегментами |
 | `hooks/` | React-хуки |
 | `stores/` | Сторы состояния |
@@ -532,24 +657,48 @@ export function SupportScreen() {
 
 ### Сегмент ui/
 
-Компоненты, принадлежащие модулю. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков. Использует сегменты родительского модуля.
+Презентационные компоненты родительского модуля. `ui/` содержит только компоненты, которые отвечают за отображение части интерфейса и не выходят за границы своего модуля.
+
+Компонент в `ui/`:
+
+- Находится в собственной папке.
+- Может содержать только `{name}.tsx`, `index.ts`, `styles/`, `types/`.
+- Не содержит любые компоненты.
+- Не содержит любые модули.
+- Не импортирует код проекта за пределами родительского модуля.
+- Не делает внешние запросы.
+- Не вызывает сценарные хуки.
+- Не получает данные самостоятельно, не выбирает источник данных и не композирует данные.
+- Не содержит бизнес-логику или сценарную логику.
+
+Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе [Компонент](/architecture/modules#компонент).
+
+Корневой файл модуля в `ui/` не размещается. Он лежит в корне модуля: `{module-name}.tsx`.
 
 ```text
-auth/
+user/
 ├── ui/
-│   ├── auth-provider.tsx
+│   ├── user-avatar/
-│   ├── auth-guard.tsx
+│   │   ├── user-avatar.tsx
-│   └── logout-button.tsx
+│   │   ├── styles/
+│   │   │   └── user-avatar.module.css
+│   │   ├── types/
+│   │   │   └── user-avatar-props.type.ts
+│   │   └── index.ts
+│   └── user-status/
+│       ├── user-status.tsx
+│       └── index.ts
 ├── types/
 ├── hooks/
+├── user.tsx
 └── index.ts
 ```
 
-Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
+Если UI-сущности нужна внутренняя декомпозиция, сценарная логика, получение данных или собственные архитектурные зависимости — это уже не компонент в `ui/`, а модуль в `parts/`.
 
 ### Сегмент parts/
 
-Вложенные модули со своими сегментами. Каждый элемент `parts/` — полноценный модуль: папка с компонентом, хуками, стилями, типами и т.д.
+Вложенные модули со своими сегментами. `parts/` содержит только модули: каждый элемент `parts/` — папка полноценного модуля с собственным публичным API. Отдельные `.tsx`, стили, хуки или произвольные файлы в `parts/` не размещаются.
 
 ```text
 home/
@@ -557,17 +706,20 @@ home/
 │   ├── hero-section/
 │   │   ├── hero-section.tsx
 │   │   ├── styles/
-│   │   └── parts/
+│   │   ├── parts/
-│   │       └── top-banner/
+│   │   │   └── top-banner/
-│   │           └── top-banner.tsx
+│   │   │       ├── top-banner.tsx
+│   │   │       └── index.ts
+│   │   └── index.ts
 │   └── features-section/
 │       ├── features-section.tsx
-│       └── hooks/
+│       ├── hooks/
+│       └── index.ts
 ├── home.screen.tsx
 └── index.ts
 ```
 
-Отличие от `ui/`: элемент `parts/` — модуль со своими сегментами. Элемент `ui/` — компонент, один `.tsx` файл.
+Отличие от `ui/`: элемент `parts/` — модульная папка со своими сегментами. Элемент `ui/` — компонент родительского модуля без собственной архитектурной ответственности.
 
 Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
 

src/App.tsx

@@ -0,0 +1,5 @@
+import { HomeScreen } from './screens/home'
+
+export default function App() {
+  return <HomeScreen />
+}

src/env.d.ts

@@ -0,0 +1 @@
+declare const __BUILD_VERSION__: string

src/infra/theme/config/theme.config.ts

@@ -0,0 +1,20 @@
+import type { ThemeMode } from '../types/theme-mode.type'
+
+export const THEME_STORAGE_KEY = 'slm-theme'
+
+export const THEME_TOGGLE_OPTIONS: ReadonlyArray<{
+  value: Exclude<ThemeMode, 'system'>
+  ariaLabel: string
+  title: string
+}> = [
+  {
+    value: 'light',
+    ariaLabel: 'Включить светлую тему',
+    title: 'Светлая',
+  },
+  {
+    value: 'dark',
+    ariaLabel: 'Включить тёмную тему',
+    title: 'Тёмная',
+  },
+]

src/infra/theme/hooks/use-theme.hook.ts

@@ -0,0 +1,79 @@
+import { useEffect, useLayoutEffect, useState } from 'react'
+
+import { THEME_STORAGE_KEY } from '../config/theme.config'
+import type { ResolvedTheme, ThemeMode } from '../types/theme-mode.type'
+
+const DARK_THEME_QUERY = '(prefers-color-scheme: dark)'
+
+const canUseDom = () => typeof window !== 'undefined' && typeof document !== 'undefined'
+
+const isThemeMode = (value: string | null): value is ThemeMode => {
+  return value === 'system' || value === 'dark' || value === 'light'
+}
+
+const getSystemTheme = (): ResolvedTheme => {
+  if (!canUseDom()) return 'light'
+
+  return window.matchMedia(DARK_THEME_QUERY).matches ? 'dark' : 'light'
+}
+
+const resolveTheme = (theme: ThemeMode): ResolvedTheme => {
+  return theme === 'system' ? getSystemTheme() : theme
+}
+
+const getStoredTheme = (): ThemeMode => {
+  if (!canUseDom()) return 'system'
+
+  const storedTheme = window.localStorage.getItem(THEME_STORAGE_KEY)
+
+  return isThemeMode(storedTheme) ? storedTheme : 'system'
+}
+
+const applyTheme = (theme: ThemeMode) => {
+  if (!canUseDom()) return
+
+  const resolvedTheme = resolveTheme(theme)
+
+  document.documentElement.dataset.theme = theme
+  document.documentElement.style.colorScheme = resolvedTheme
+
+  if (theme === 'system') {
+    window.localStorage.removeItem(THEME_STORAGE_KEY)
+    return
+  }
+
+  window.localStorage.setItem(THEME_STORAGE_KEY, theme)
+}
+
+export function useTheme() {
+  const [theme, setTheme] = useState<ThemeMode>(getStoredTheme)
+  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(() => resolveTheme(getStoredTheme()))
+
+  useLayoutEffect(() => {
+    applyTheme(theme)
+    setResolvedTheme(resolveTheme(theme))
+  }, [theme])
+
+  useEffect(() => {
+    if (!canUseDom()) return undefined
+
+    const mediaQuery = window.matchMedia(DARK_THEME_QUERY)
+    const handleSystemThemeChange = () => {
+      if (theme !== 'system') return
+
+      const nextResolvedTheme = resolveTheme(theme)
+      document.documentElement.style.colorScheme = nextResolvedTheme
+      setResolvedTheme(nextResolvedTheme)
+    }
+
+    mediaQuery.addEventListener('change', handleSystemThemeChange)
+
+    return () => mediaQuery.removeEventListener('change', handleSystemThemeChange)
+  }, [theme])
+
+  return {
+    theme,
+    resolvedTheme,
+    setTheme,
+  }
+}

src/infra/theme/index.ts

@@ -0,0 +1,6 @@
+import './styles/theme.css'
+
+export { ThemeToggle } from './ui/theme-toggle'
+export { useTheme } from './hooks/use-theme.hook'
+
+export type { ResolvedTheme, ThemeMode } from './types/theme-mode.type'

src/infra/theme/styles/theme-toggle.module.css

@@ -0,0 +1,55 @@
+.root {
+  display: inline-flex;
+  align-items: stretch;
+  gap: 2px;
+  height: 36px;
+  padding: 4px;
+  border: 1px solid var(--border-soft);
+  border-radius: 999px;
+  background: var(--surface-soft);
+}
+
+.option {
+  appearance: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  color: var(--text-muted);
+  background: transparent;
+  font: inherit;
+  font-size: 13px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  cursor: pointer;
+  transition: background-color 150ms ease, color 150ms ease, box-shadow 150ms ease;
+}
+
+.option:hover {
+  color: var(--text-primary);
+}
+
+.option:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 3px;
+}
+
+.option[data-active='true'] {
+  color: var(--text-primary);
+  background: var(--page-bg);
+  box-shadow: 0 1px 2px var(--shadow-subtle);
+}
+
+.icon {
+  display: inline-flex;
+  width: 16px;
+  height: 16px;
+}
+
+.icon svg {
+  width: 100%;
+  height: 100%;
+}

src/infra/theme/styles/theme.css

@@ -0,0 +1,85 @@
+:root {
+  color-scheme: light;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  --page-bg: #f7f7fa;
+  --surface: #f0f1f5;
+  --surface-soft: #ffffff;
+  --surface-strong: #ffffff;
+  --surface-raised: #ffffff;
+  --surface-muted: #eef0ff;
+  --text-primary: #181a22;
+  --text-secondary: #5d6474;
+  --text-muted: #8b93a5;
+  --border-soft: #dfe2ea;
+  --border-strong: #c8ceda;
+  --accent-cool: #6677ff;
+  --focus-ring: rgba(102, 119, 255, 0.56);
+  --shadow-subtle: rgba(25, 31, 54, 0.1);
+}
+
+:root[data-theme='dark'] {
+  color-scheme: dark;
+  --page-bg: #1b1c21;
+  --surface: #24262d;
+  --surface-soft: #202229;
+  --surface-strong: #2a2c34;
+  --surface-raised: #202229;
+  --surface-muted: #2b2e3b;
+  --text-primary: #f1f3f8;
+  --text-secondary: #a9afbf;
+  --text-muted: #747c90;
+  --border-soft: #343741;
+  --border-strong: #454957;
+  --accent-cool: #8492ff;
+  --focus-ring: rgba(132, 146, 255, 0.66);
+  --shadow-subtle: rgba(0, 0, 0, 0.24);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    color-scheme: dark;
+    --page-bg: #1b1c21;
+    --surface: #24262d;
+    --surface-soft: #202229;
+    --surface-strong: #2a2c34;
+    --surface-raised: #202229;
+    --surface-muted: #2b2e3b;
+    --text-primary: #f1f3f8;
+    --text-secondary: #a9afbf;
+    --text-muted: #747c90;
+    --border-soft: #343741;
+    --border-strong: #454957;
+    --accent-cool: #8492ff;
+    --focus-ring: rgba(132, 146, 255, 0.66);
+    --shadow-subtle: rgba(0, 0, 0, 0.24);
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  min-height: 100%;
+  background: var(--page-bg);
+}
+
+body {
+  min-width: 320px;
+  min-height: 100vh;
+  margin: 0;
+  background: var(--page-bg);
+  color: var(--text-primary);
+}
+
+button,
+a {
+  -webkit-tap-highlight-color: transparent;
+}
+
+a {
+  color: inherit;
+}

src/infra/theme/types/theme-mode.type.ts

@@ -0,0 +1,3 @@
+export type ThemeMode = 'system' | 'dark' | 'light'
+
+export type ResolvedTheme = 'dark' | 'light'

src/infra/theme/ui/theme-toggle.tsx

@@ -0,0 +1,61 @@
+import { THEME_TOGGLE_OPTIONS } from '../config/theme.config'
+import { useTheme } from '../hooks/use-theme.hook'
+import type { ThemeMode } from '../types/theme-mode.type'
+import type { ReactNode } from 'react'
+import styles from '../styles/theme-toggle.module.css'
+
+const iconByTheme: Record<Exclude<ThemeMode, 'system'>, ReactNode> = {
+  light: (
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none">
+      <circle cx="12" cy="12" r="4" stroke="currentColor" strokeWidth="2" />
+      <path
+        d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+      />
+    </svg>
+  ),
+  dark: (
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none">
+      <path
+        d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  ),
+}
+
+type ThemeToggleProps = {
+  className?: string
+}
+
+export function ThemeToggle({ className }: ThemeToggleProps) {
+  const { theme, resolvedTheme, setTheme } = useTheme()
+  const rootClassName = className ? `${styles.root} ${className}` : styles.root
+  const toggleTheme = (value: Exclude<ThemeMode, 'system'>) => {
+    setTheme(theme === value ? 'system' : value)
+  }
+
+  return (
+    <div className={rootClassName} role="group" aria-label="Тема" data-resolved-theme={resolvedTheme}>
+      {THEME_TOGGLE_OPTIONS.map((option) => (
+        <button
+          className={styles.option}
+          type="button"
+          aria-pressed={theme === option.value}
+          aria-label={option.ariaLabel}
+          title={option.title}
+          data-active={theme === option.value}
+          key={option.value}
+          onClick={() => toggleTheme(option.value)}
+        >
+          <span className={styles.icon}>{iconByTheme[option.value]}</span>
+        </button>
+      ))}
+    </div>
+  )
+}

src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

src/screens/home/config/home-screen.config.ts

@@ -0,0 +1,32 @@
+const version = __BUILD_VERSION__
+
+export const repositoryUrl = 'https://gromlab.ru/gromov/slm-design'
+
+export const homeCards = [
+  {
+    title: 'Документация',
+    description: 'Слои, модули, сегменты и правила зависимостей для frontend-проектов.',
+    href: '/docs/',
+    cta: 'Открыть →',
+  },
+  {
+    title: 'ARCHITECTURE.md',
+    description: 'Полная версия архитектуры в одном файле',
+    href: `/ARCHITECTURE.md?v=${version}`,
+    cta: 'Открыть →',
+  },
+  {
+    title: 'Ассистенту',
+    description: 'Карта документации для AI-агентов:',
+    actions: [
+      {
+        href: '/llms.txt',
+        label: 'llms.txt',
+      },
+      {
+        href: '/llms-full.txt',
+        label: 'llms-full.txt',
+      },
+    ],
+  },
+] as const

src/screens/home/home.screen.tsx

@@ -0,0 +1,66 @@
+import { ThemeToggle } from '../../infra/theme'
+import { homeCards, repositoryUrl } from './config/home-screen.config'
+import styles from './styles/home-screen.module.css'
+
+const version = __BUILD_VERSION__ as string
+
+export function HomeScreen() {
+  return (
+    <main className={styles.page}>
+      <section className={styles.hero}>
+        <h1 className={styles.title}>SLM Design</h1>
+        <p className={styles.lead}>
+          Scoped Layered Module Design — соглашения по архитектуре frontend-приложений:
+          слои, модули, сегменты, публичные API и направление зависимостей.
+        </p>
+
+        <div className={styles.controls}>
+          <a className={styles.repoLink} href={repositoryUrl} target="_blank" rel="noopener noreferrer">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+              <path d="M12 .3a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57L9 21.07c-3.34.72-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.08-.74.09-.73.09-.73 1.2.09 1.83 1.24 1.83 1.24 1.08 1.83 2.81 1.3 3.5 1 .1-.78.42-1.31.76-1.61-2.67-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.14-.3-.54-1.52.1-3.18 0 0 1-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.64 1.66.24 2.88.12 3.18a4.65 4.65 0 0 1 1.23 3.22c0 4.61-2.8 5.63-5.48 5.92.42.36.81 1.1.81 2.22l-.01 3.29c0 .31.2.69.82.57A12 12 0 0 0 12 .3Z" />
+            </svg>
+            <span>Репозиторий</span>
+          </a>
+          <ThemeToggle className={styles.themeToggle} />
+        </div>
+      </section>
+
+      <section className={styles.cards} aria-label="Быстрые переходы">
+        {homeCards.map((card) => {
+          if ('href' in card) {
+            return (
+              <a
+                className={`${styles.card} ${styles.cardLink}`}
+                href={card.href}
+                download={'download' in card ? card.download : undefined}
+                key={card.title}
+              >
+                <h2>{card.title}</h2>
+                <p>{card.description}</p>
+                <span className={styles.cardCta}>{card.cta}</span>
+              </a>
+            )
+          }
+
+          return (
+            <article className={styles.card} key={card.title}>
+              <h2>{card.title}</h2>
+              <p>{card.description}</p>
+              <div className={styles.cardActions}>
+                {card.actions.map((action) => (
+                  <a className={styles.cardAction} href={action.href} key={action.href}>
+                    {action.label}
+                  </a>
+                ))}
+              </div>
+            </article>
+          )
+        })}
+      </section>
+
+      <footer className={styles.footer}>
+        <span>{version}</span>
+      </footer>
+    </main>
+  )
+}

src/screens/home/index.ts

@@ -0,0 +1 @@
+export { HomeScreen } from './home.screen'

src/screens/home/styles/home-screen.module.css

@@ -0,0 +1,216 @@
+.page {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 64px;
+  min-height: 100vh;
+  padding: 48px 32px;
+  background: var(--page-bg);
+  color: var(--text-primary);
+}
+
+.hero {
+  text-align: center;
+}
+
+.title {
+  margin: 0 0 16px;
+  color: var(--accent-cool);
+  font-size: 56px;
+  font-weight: 750;
+  letter-spacing: -0.035em;
+  line-height: 1;
+}
+
+.lead {
+  max-width: 740px;
+  margin: 0 auto;
+  color: var(--text-secondary);
+  font-size: 18px;
+  line-height: 1.55;
+}
+
+.controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  margin-top: 28px;
+}
+
+.controls > * {
+  box-sizing: border-box;
+  height: 36px;
+}
+
+.repoLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 0 14px;
+  border: 1px solid var(--border-soft);
+  border-radius: 999px;
+  color: var(--text-secondary);
+  background: var(--surface-soft);
+  font-size: 13px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: border-color 150ms ease, color 150ms ease;
+}
+
+.repoLink:hover {
+  border-color: var(--accent-cool);
+  color: var(--text-primary);
+}
+
+.repoLink svg {
+  flex-shrink: 0;
+}
+
+.themeToggle {
+  flex-shrink: 0;
+}
+
+.cards {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 16px;
+  width: 100%;
+  max-width: 1100px;
+  margin: 0 auto;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 178px;
+  padding: 24px;
+  border: 1px solid var(--border-soft);
+  border-radius: 12px;
+  color: inherit;
+  background: var(--surface-soft);
+  text-decoration: none;
+}
+
+.cardLink {
+  transition: border-color 200ms ease, transform 200ms ease;
+}
+
+.cardLink:hover {
+  border-color: var(--accent-cool);
+  transform: translateY(-2px);
+}
+
+.card h2 {
+  margin: 0;
+  color: var(--text-primary);
+  font-size: 18px;
+  font-weight: 650;
+  line-height: 1.3;
+}
+
+.card p {
+  margin: 0;
+  color: var(--text-secondary);
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.cardActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: auto;
+}
+
+.cardCta {
+  margin-top: auto;
+  color: var(--accent-cool);
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.cardAction {
+  display: inline-flex;
+  align-items: center;
+  padding: 6px 12px;
+  border: 1px solid var(--border-soft);
+  border-radius: 8px;
+  color: var(--text-primary);
+  background: var(--page-bg);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 13px;
+  font-weight: 500;
+  text-decoration: none;
+  transition: border-color 150ms ease, color 150ms ease;
+}
+
+.cardAction:hover {
+  border-color: var(--accent-cool);
+  color: var(--accent-cool);
+}
+
+.footer {
+  margin: 0;
+  color: var(--text-muted);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 12px;
+  text-align: center;
+}
+
+@media (max-width: 768px) {
+  .page {
+    justify-content: flex-start;
+    gap: 40px;
+    padding: 48px 20px 56px;
+  }
+
+  .title {
+    font-size: 38px;
+  }
+
+  .lead {
+    font-size: 16px;
+  }
+
+  .cards {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 480px) {
+  .page {
+    gap: 36px;
+    padding: 44px 16px 48px;
+  }
+
+  .title {
+    font-size: 32px;
+  }
+
+  .lead {
+    font-size: 15px;
+    line-height: 1.5;
+  }
+
+  .controls {
+    margin-top: 32px;
+  }
+
+  .repoLink {
+    width: 36px;
+    justify-content: center;
+    padding: 0;
+  }
+
+  .repoLink span {
+    display: none;
+  }
+
+  .card {
+    min-height: 160px;
+    padding: 20px;
+  }
+}

vite.config.ts

@@ -0,0 +1,79 @@
+import { defineConfig, Plugin } from 'vite'
+import react from '@vitejs/plugin-react'
+import { readFileSync, existsSync } from 'fs'
+import { resolve } from 'path'
+
+const pkg = JSON.parse(readFileSync('./package.json', 'utf8'))
+
+const textArtifacts: Record<string, string> = {
+  '/llms.txt': 'text/plain; charset=utf-8',
+  '/llms-full.txt': 'text/plain; charset=utf-8',
+  '/ARCHITECTURE.md': 'text/markdown; charset=utf-8',
+}
+
+function serveTextArtifacts(): Plugin {
+  return {
+    name: 'serve-text-artifacts',
+    configureServer(server) {
+      const publicDir = resolve('public')
+
+      server.middlewares.use((req, res, next) => {
+        const url = req.url?.split('?')[0]
+        const contentType = url ? textArtifacts[url] : undefined
+        if (!url || !contentType) return next()
+
+        const filePath = resolve(publicDir, url.slice(1))
+        if (!existsSync(filePath)) return next()
+
+        res.setHeader('Content-Type', contentType)
+        res.end(readFileSync(filePath))
+      })
+    },
+  }
+}
+
+function serveDocs(): Plugin {
+  return {
+    name: 'serve-docs',
+    configureServer(server) {
+      const publicDir = resolve('public')
+
+      server.middlewares.use((req, _res, next) => {
+        const url = req.url?.split('?')[0]
+        if (!url?.startsWith('/docs')) return next()
+
+        const filePath = resolve(publicDir, url.slice(1))
+
+        if (url === '/docs') {
+          if (existsSync(resolve(filePath, 'index.html'))) {
+            req.url = '/docs/index.html'
+            return next()
+          }
+        }
+
+        if (url.endsWith('/')) {
+          if (existsSync(resolve(filePath, 'index.html'))) {
+            req.url = url + 'index.html'
+            return next()
+          }
+        }
+
+        if (!url.split('/').pop()?.includes('.')) {
+          if (existsSync(filePath + '.html')) {
+            req.url = url + '.html'
+            return next()
+          }
+        }
+
+        next()
+      })
+    },
+  }
+}
+
+export default defineConfig({
+  plugins: [react(), serveTextArtifacts(), serveDocs()],
+  define: {
+    __BUILD_VERSION__: JSON.stringify(`v${pkg.version}`),
+  },
+})