fix: исправить доступность артефактов документации

- добавлены HTML-подсказки для обнаружения llms.txt агентами - обновлена карточка скачивания спецификации и архива - добавлен раздел с порядком чтения спецификации - исправлена генерация ссылок для single-file, Markdown и ZIP - обновлены сгенерированные README.md и ARCHITECTURE.md
fix: исправить ссылки llms на markdown-файлы
2026-05-02 18:51:44 +03:00 · 2026-05-02 06:53:35 +03:00 · 2026-05-01 23:57:56 +03:00 · 2026-05-01 21:42:36 +03:00 · 2026-05-01 21:18:09 +03:00
12 changed files with 307 additions and 211 deletions
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -2,12 +2,37 @@ name: CI/CD Pipeline

 on:
  push:
-    branches: [main]
+    branches: [main, dev]

 jobs:
-  docs:
+  build:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Установка зависимостей
+        run: npm ci
+
+      - name: Генерация артефактов
+        run: npm run generate
+
+      - name: Сборка документации
+        run: npm run docs:build
+
+      - name: Сборка лендинга
+        run: npm run build
+
+  version:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, '[skip ci]')
    outputs:
      version: ${{ steps.version.outputs.version }}
    steps:
@@ -16,11 +41,6 @@ jobs:
        with:
          fetch-depth: 0

-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-
      - name: Версия из package.json
        id: version
        run: |
@@ -28,23 +48,6 @@ jobs:
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "Версия: $VERSION"

-      - name: Генерация docs
-        run: |
-          npm ci
-          npm run docs
-
-      - name: Коммит generated/
-        run: |
-          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: обновить generated (${{ steps.version.outputs.version }}) [skip ci]"
-            git push origin main
-          fi
-
      - name: Создать тег
        run: |
          VERSION=${{ steps.version.outputs.version }}
@@ -58,7 +61,7 @@ jobs:

  docker:
    runs-on: ubuntu-latest
-    needs: docs
+    needs: version
    if: "!contains(github.event.head_commit.message, '[skip ci]')"
    steps:
      - name: Checkout
@@ -92,7 +95,7 @@ jobs:
            type=ref,event=branch
            type=sha,prefix=
            type=raw,value=latest,enable={{is_default_branch}}
-            type=raw,value=${{ needs.docs.outputs.version }}
+            type=raw,value=${{ needs.version.outputs.version }}

      - name: Build and push
        uses: docker/build-push-action@v5
@@ -104,7 +107,7 @@ jobs:
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
-            VERSION_TAG=${{ needs.docs.outputs.version }}
+            VERSION_TAG=${{ needs.version.outputs.version }}
          provenance: false
          sbom: false

--- a/.gitignore
+++ b/.gitignore
@@ -135,6 +135,7 @@ dist
 .vitepress/cache
 .vitepress/dist
 docs/.vitepress
+docs/public/

 # Generated artifacts
 public/docs/
@@ -149,4 +150,3 @@ dist
 # Рабочие заметки
 notes

-
--- a/.vitepress/config.ts
+++ b/.vitepress/config.ts
@@ -14,10 +14,18 @@ const sidebar = [

 export default defineConfig({
  srcDir: 'docs',
+  srcExclude: ['public/**'],
  outDir: 'public/docs',
  title: 'SLM Design',
  description: 'Правила и стандарты архитектуры проекта',
  base: '/docs/',
+  cleanUrls: true,
+  head: [
+    ['meta', { name: 'llms', content: '/llms.txt' }],
+    ['link', { rel: 'alternate llms', type: 'text/plain', href: '/llms.txt', title: 'llms.txt' }],
+    ['link', { rel: 'alternate', type: 'text/plain', href: '/llms-full.txt', title: 'llms-full.txt' }],
+    ['link', { rel: 'alternate', type: 'text/markdown', href: '/ARCHITECTURE.md', title: 'ARCHITECTURE.md' }],
+  ],

  themeConfig: {
    sidebar,
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,182 +4,79 @@

 ## О проекте

-Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.
+Сайт-документация архитектуры SLM Design с лендингом.

- Движок: VitePress
- Языки: русский (основной), английский
- Русская версия: `docs/ru/`
- Английская версия: `docs/en/`
+- Лендинг: React + Vite
+- Документация: VitePress
+- Язык: русский
+- Документация: `docs/architecture/`

 ## Команды

 | Команда | Что делает |
 |---------|-----------|
-| `npm run dev` | Локальный сервер разработки |
-| `npm run build` | Сборка статического сайта |
-| `npm run docs` | Генерация `generated/{lang}/RULES.md` — единый файл для AI-ассистентов |
+| `npm run dev` | Локальный сервер лендинга |
+| `npm run build` | Сборка лендинга |
+| `npm run docs:dev` | Локальный сервер документации |
+| `npm run docs:build` | Сборка документации |
+| `npm run generate` | Генерация артефактов (llms.txt, llms-full.txt, ARCHITECTURE.md, ZIP, README) |

 ## Структура файлов

 ```
 docs/
-├── ru/                          # Русская версия (основная)
-│   ├── index.md                 # Главная страница
-│   ├── basics/                  # Базовые правила
-│   │   ├── tech-stack.md
-│   │   ├── architecture.md
-│   │   ├── code-style.md
-│   │   ├── naming.md
-│   │   ├── documentation.md
-│   │   └── typing.md
-│   └── applied/                 # Прикладные разделы
-│       ├── vscode.md
-│       ├── project-structure.md
-│       ├── components.md
-│       ├── page-level.md
-│       ├── templates-generation.md
-│       ├── styles.md
-│       ├── images-sprites.md
-│       ├── svg-sprites.md
-│       ├── video.md
-│       ├── api.md
-│       ├── stores.md
-│       ├── hooks.md
-│       ├── fonts.md
-│       └── localization.md
-├── en/                          # Английская версия (зеркало ru/)
+├── index.md                      # Страница навигации по документации
+└── architecture/                 # Разделы архитектуры
+    ├── index.md                  # Обзор SLM Design
+    ├── layers.md                 # Слои
+    ├── modules.md                # Модули
+    └── segments.md               # Сегменты
 .vitepress/
-├── config.ts                    # Конфигурация VitePress, сайдбары, локали
-generated/
-├── ru/RULES.md                  # Сгенерированный единый файл (ru)
-└── en/RULES.md                  # Сгенерированный единый файл (en)
-concat-md.js                     # Скрипт генерации RULES.md
+├── config.ts                     # Конфигурация VitePress, сайдбар
+public/
+├── llms.txt                      # Карта документации для LLM
+├── llms-full.txt                 # Полная документация в одном файле
+└── ARCHITECTURE.md               # Единый файл архитектуры
+generate.ts                       # Скрипт генерации артефактов
+src/                              # Исходники лендинга (React + Vite)
 ```

 ### Добавление нового раздела

-1. Создать `.md`-файл в нужной папке (`basics/` или `applied/`).
-2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод).
-3. Добавить файл в массив `fileOrder` — `concat-md.js` (для генерации RULES.md).
+1. Создать `.md`-файл в `docs/architecture/`.
+2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
+3. Добавить `description` в frontmatter файла — используется для `llms.txt`.
+4. Запустить `npm run generate` для обновления артефактов.

-## Два типа документации
-
-### Базовые правила
-
-**Отвечает на вопрос:** «Каким должен быть любой код?»
-
-Универсальные стандарты, **не привязанные к конкретной области**.
-Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.
-
-Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.
-
-**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
-
-### Прикладные разделы
-
-**Отвечает на вопрос:** «Как работать с X?»
-
-Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.
-
-**Граница:** прикладной раздел не дублирует базовые правила.
-Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.
-
-## Структура прикладного раздела
-
-Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.
-
-```markdown
-# {Название}
-
-Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.
-
-## Что нужно знать
-
-Неочевидная информация, которую читатель должен знать перед чтением раздела.
-Если для раздела нет такой вводной — секция не создаётся.
-
-## Структура
-
-Файловая организация: какие файлы создавать и куда класть.
-Обязательно — дерево файлов через code-block.
-
-## Правила
-
-Конкретные требования, специфичные для области. Делятся на две подсекции:
-
-### Реализация
-
-Как написан код внутри файла: синтаксис, паттерны, API.
-Отвечает на вопрос: «Как писать код?»
-
-Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.
-
-### Организация
-
-Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
-Отвечает на вопрос: «Где что лежит и за что отвечает?»
-
-Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.
-
-Формат обеих подсекций — маркированный список.
-Для неочевидных случаев — блоки «Хорошо / Плохо».
-Если в области нет правил одной из категорий — подсекция не создаётся.
-
-## Именование
-
-Соглашения по именам, специфичные для этой области.
-Только то, что НЕ покрыто в базовом разделе «Именование».
-
-## Типизация
-
-Правила типизации, специфичные для этой области.
-Только то, что НЕ покрыто в базовом разделе «Типизация».
-
-## Документирование
-
-Что и как документировать в этой области.
-Только то, что НЕ покрыто в базовом разделе «Документирование».
-
-## Примеры
-
-Полноценные примеры кода.
-Каждый пример с путём к файлу и пояснениями.
-
-```
-
-### Порядок секций
-
-Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
-
-Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
-
-### Секции-расширения базовых правил
-
-«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.
-
- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).
-
-Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.
-
-## Конвенции оформления
-
-### Frontmatter
+## Frontmatter

 Каждый `.md`-файл начинается с YAML frontmatter:

 ```yaml
 ---
 title: Название раздела
+description: Краткое описание для llms.txt
 ---
 ```

-Значение `title` совпадает с текстом `h1`-заголовка в файле.
+- `title` — совпадает с `h1`-заголовком в файле.
+- `description` — кратное описание содержимого страницы, используется при генерации `llms.txt`.
+
+## Структура страницы документации
+
+Каждая страница начинается одинаково:
+
+1. **Заголовок** (`h1`) — совпадает с `title` из frontmatter.
+2. **Описание раздела** — 1–2 строки сразу после заголовка. Говорит, что это за раздел, какую информацию он описывает и что читатель в нём получит.
+3. **Определение** (`## Определение`) — для справочных страниц, посвящённых одному термину. Короткая формулировка жирным: что это за сущность и какую роль она играет.
+4. **Контент** — остальные `h2`-подразделы.
+
+## Конвенции оформления

 ### Заголовки

 - Один `h1` на файл — совпадает с `title` из frontmatter.
- Сразу после `h1` — вводный абзац (одно-два предложения).
+- Сразу после `h1` — описание раздела (1–2 предложения).
 - Основные секции — `h2`.
 - Подсекции внутри `h2` — `h3`.
 - `h4` не используется.
@@ -194,8 +91,6 @@ title: Название раздела

 Используются для контрастного сравнения правильного и неправильного подхода.

-Формат:
-
 ```markdown
 **Хорошо:**

@@ -217,11 +112,10 @@ title: Название раздела

 ### Ссылки между разделами

-Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.
+Раздел может ссылаться на другие разделы, но не дублирует их содержимое.

 ## Принципы

 1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
-2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
-3. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
-4. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.
+2. **Пустые секции не создавать.** Если для раздела нет специфики — секция не создаётся.
+3. **Примеры обязательны.** Раздел без примеров кода — незавершён.
--- a/40
+++ b/40
@@ -1,10 +1,40 @@
 :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
+
+	# Устаревшие пути llms.txt в подпапках ведём к корневым артефактам.
+	redir /docs/llms.txt /llms.txt 301
+	redir /docs/llms-full.txt /llms-full.txt 301
+
+	# Чистые URL: запросы вида `/docs/foo.html` редиректим на `/docs/foo`.
+	@legacyHtml {
+		path_regexp legacyHtml ^(/.+)\.html$
+		not path /index.html
+	}
+	redir @legacyHtml {re.legacyHtml.1} 301
+
 	header Link "</llms.txt>; rel=\"llms\""
+
+	@existingText {
+		path *.txt
+		file
+	}
+	header @existingText Content-Type "text/plain; charset=utf-8"
+
+	@existingMarkdown {
+		path *.md
+		file
+	}
+	header @existingMarkdown Content-Type "text/markdown; charset=utf-8"
+
+	@architecture path /ARCHITECTURE.md
+	header @architecture Cache-Control "no-cache, no-store, must-revalidate"
+
+	@missingText {
+		path *.txt *.md
+		not file
+	}
+	respond @missingText 404
+
+	file_server
 	try_files {path} {path}.html {path}/index.html /index.html
 }
--- a/README.md
+++ b/README.md
@@ -1,6 +1,16 @@
 # SLM Design
 Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.

+## Разделы спецификации
+
+Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
+
+- [Слои](docs/architecture/layers.md) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
+- [Модули](docs/architecture/modules.md) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
+- [Сегменты](docs/architecture/segments.md) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
+
+Рекомендуемый порядок чтения: обзор → слои → модули → сегменты.
+
 ## Преимущества

 ### Вертикальная организация домена
--- a/docs/architecture/index.md
+++ b/docs/architecture/index.md
@@ -6,6 +6,16 @@ description: Назначение архитектуры, ключевые пр
 # SLM Design
 Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.

+## Разделы спецификации
+
+Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
+
+- [Слои](/architecture/layers) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
+- [Модули](/architecture/modules) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
+- [Сегменты](/architecture/segments) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
+
+Рекомендуемый порядок чтения: обзор → слои → модули → сегменты.
+
 ## Преимущества

 ### Вертикальная организация домена
--- a/generate.ts
+++ b/generate.ts
@@ -5,7 +5,12 @@ import { execFileSync } from "child_process";

 const SRC_DIR = "./docs";
 const PUBLIC_DIR = "./public";
+const DOCS_PUBLIC_DIR = path.join(SRC_DIR, "public");
+const DOC_ROUTE_PREFIX = "/docs";
 const PUBLIC_ARCHITECTURE_FILE = "ARCHITECTURE.md";
+const PUBLIC_ARCHITECTURE_NOTICE = `> Локальная копия канонической спецификации SLM Design.
+> Источник: https://slm-design.gromlab.ru/ARCHITECTURE.md
+> Не редактировать вручную в этом проекте.`;

 interface SidebarItem {
  text: string;
@@ -43,15 +48,54 @@ function parseSidebar(): SidebarGroup[] {

 const SIDEBAR = parseSidebar();

+function linkToFileRel(link: string): string {
+  const rel = link.replace(/^\//, "");
+  if (rel === "" || rel.endsWith("/")) return `${rel}index.md`;
+  return `${rel}.md`;
+}
+
+function fileRelToRoute(file: string): string {
+  const route = file.endsWith("/index.md")
+    ? file.replace(/index\.md$/, "")
+    : file.replace(/\.md$/, "");
+  return `${DOC_ROUTE_PREFIX}/${route}`;
+}
+
+function fileRelToMdUrl(file: string): string {
+  return `${DOC_ROUTE_PREFIX}/${file}`;
+}
+
+const ARCHITECTURE_LINK_RE = /\]\((\/architecture(?:\/[^)\s#]*)?)(#[^)\s]*)?\)/g;
+
+function architectureRouteToFileRel(route: string): string {
+  if (route.replace(/\/$/, "") === "/architecture") return "architecture/index.md";
+  return linkToFileRel(route);
+}
+
+function transformArchitectureLinks(
+  content: string,
+  toHref: (route: string, hash: string) => string,
+): string {
+  return content.replace(ARCHITECTURE_LINK_RE, (_match, route: string, hash = "") => {
+    return `](${toHref(route, hash)})`;
+  });
+}
+
+function transformArchiveLinks(content: string): string {
+  return transformArchitectureLinks(content, (route, hash) => {
+    const fileName = path.basename(architectureRouteToFileRel(route));
+    return `./${fileName}${hash}`;
+  });
+}
+
+function transformSiteMarkdownLinks(content: string): string {
+  return transformArchitectureLinks(content, (route, hash) => {
+    return `${fileRelToMdUrl(architectureRouteToFileRel(route))}${hash}`;
+  });
+}
+
 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;
-    })
-  );
+  return SIDEBAR.flatMap((g) => g.items.map((item) => linkToFileRel(item.link)));
 }

 const stripFrontmatter = (content: string) =>
@@ -60,6 +104,38 @@ const stripFrontmatter = (content: string) =>
 const stripRulesLink = (content: string) =>
  content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");

+function slugifyHeading(heading: string): string {
+  return heading
+    .trim()
+    .replace(/[`*_~[\]()]/g, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, "")
+    .trim()
+    .replace(/\s+/g, "-");
+}
+
+function fileRelToSingleFileAnchor(file: string): string {
+  const filePath = path.join(SRC_DIR, file);
+  if (!fs.existsSync(filePath)) return slugifyHeading(path.basename(file, ".md"));
+
+  const raw = stripFrontmatter(fs.readFileSync(filePath, "utf8"));
+  const title = raw.match(/^#\s+(.+)$/m)?.[1];
+  return slugifyHeading(title ?? path.basename(file, ".md"));
+}
+
+function transformSingleFileLinks(content: string): string {
+  return transformArchitectureLinks(content, (route, hash) => {
+    if (hash) return hash;
+    return `#${fileRelToSingleFileAnchor(architectureRouteToFileRel(route))}`;
+  });
+}
+
+function transformReadmeLinks(content: string): string {
+  return transformArchitectureLinks(content, (route, hash) => {
+    return `docs/${architectureRouteToFileRel(route)}${hash}`;
+  });
+}
+
 const shiftHeadings = (content: string) => {
  const lines = content.split("\n");
  let inCodeBlock = false;
@@ -84,8 +160,9 @@ const buildArchitectureMarkdown = (routePrefix: string) => {
    const content = stripRulesLink(stripFrontmatter(raw)).trim();
    if (!content) continue;

-    const route = routePrefix + "/" + file.replace(/\.md$/, "");
-    const processed = file.endsWith("index.md") ? content : shiftHeadings(content);
+    const route = routePrefix + fileRelToRoute(file).replace(DOC_ROUTE_PREFIX, "");
+    const shifted = file.endsWith("index.md") ? content : shiftHeadings(content);
+    const processed = transformSingleFileLinks(shifted);
    parts.push(`<!-- ${route} -->\n${processed}`);
  }

@@ -99,9 +176,7 @@ function buildLlms() {
  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 fileRel = linkToFileRel(item.link);
      const filePath = path.join(SRC_DIR, fileRel);
      let desc = "";
      if (fs.existsSync(filePath)) {
@@ -109,7 +184,7 @@ function buildLlms() {
        const fm = raw.match(/^---[\s\S]*?---\n*/m);
        desc = fm ? fm[0].match(/description:\s*(.+)/)?.[1] || "" : "";
      }
-      const route = "/docs" + item.link;
+      const route = fileRelToMdUrl(fileRel);
      const line = desc
        ? `- [${item.text}](${route}): ${desc}`
        : `- [${item.text}](${route})`;
@@ -130,10 +205,29 @@ function buildLlmsFull() {
  console.log(`llms-full.txt создан: ${outPath}`);
 }

+function copyMarkdownFiles() {
+  fs.rmSync(DOCS_PUBLIC_DIR, { recursive: true, force: true });
+
+  let copied = 0;
+  for (const file of getAllFiles()) {
+    const src = path.join(SRC_DIR, file);
+    if (!fs.existsSync(src)) continue;
+
+    const content = transformSiteMarkdownLinks(fs.readFileSync(src, "utf8"));
+    const dest = path.join(DOCS_PUBLIC_DIR, file);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, content, "utf8");
+    copied++;
+  }
+
+  console.log(`скопировано ${copied} .md-файлов в ${DOCS_PUBLIC_DIR}`);
+}
+
 function buildPublicArchitecture() {
  const outPath = path.join(PUBLIC_DIR, PUBLIC_ARCHITECTURE_FILE);
+  const content = `${PUBLIC_ARCHITECTURE_NOTICE}\n\n${buildArchitectureMarkdown("/docs")}`;
  fs.mkdirSync(PUBLIC_DIR, { recursive: true });
-  fs.writeFileSync(outPath, buildArchitectureMarkdown("/docs"), "utf8");
+  fs.writeFileSync(outPath, content, "utf8");
  console.log(`${PUBLIC_ARCHITECTURE_FILE} создан: ${outPath}`);
 }

@@ -148,6 +242,7 @@ function buildZip() {
    if (!fs.existsSync(src)) continue;
    let content = fs.readFileSync(src, "utf8");
    content = stripRulesLink(stripFrontmatter(content)).trim();
+    content = transformArchiveLinks(content);
    const destName = path.basename(file);
    fs.writeFileSync(path.join(tmpDir, destName), content, "utf8");
  }
@@ -174,12 +269,14 @@ function buildReadme() {

  let content = stripFrontmatter(fs.readFileSync(indexPath, "utf8"));
  content = content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");
+  content = transformReadmeLinks(content);
  fs.writeFileSync("./README.md", content, "utf8");
  console.log("README.md создан");
 }

 buildLlms();
 buildLlmsFull();
+copyMarkdownFiles();
 buildPublicArchitecture();
 buildZip();
 buildReadme();
--- a/index.html
+++ b/index.html
@@ -5,10 +5,28 @@
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>SLM Design</title>
    <meta name="description" content="Scoped Layered Module Design — модульная архитектура фронтенд-приложений" />
+    <meta name="llms" content="/llms.txt" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="alternate llms" type="text/plain" href="/llms.txt" title="llms.txt" />
+    <link rel="alternate" type="text/plain" href="/llms-full.txt" title="llms-full.txt" />
+    <link rel="alternate" type="text/markdown" href="/ARCHITECTURE.md" title="ARCHITECTURE.md" />
  </head>
  <body>
-    <div id="root"></div>
+    <div id="root">
+      <main>
+        <h1>SLM Design</h1>
+        <p>Scoped Layered Module Design — модульная архитектура фронтенд-приложений.</p>
+        <nav aria-label="Карта сайта и AI-артефакты">
+          <ul>
+            <li><a href="/docs/">Документация</a></li>
+            <li><a href="/llms.txt" rel="alternate" type="text/plain">llms.txt</a></li>
+            <li><a href="/llms-full.txt" rel="alternate" type="text/plain">llms-full.txt</a></li>
+            <li><a href="/ARCHITECTURE.md" rel="alternate" type="text/markdown">ARCHITECTURE.md</a></li>
+            <li><a href="/slm-design.zip" download>slm-design.zip</a></li>
+          </ul>
+        </nav>
+      </main>
+    </div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
 </html>
--- a/public/ARCHITECTURE.md
+++ b/public/ARCHITECTURE.md
@@ -1,7 +1,21 @@
-<!-- /docs/architecture//index -->
+> Локальная копия канонической спецификации SLM Design.
+> Источник: https://slm-design.gromlab.ru/ARCHITECTURE.md
+> Не редактировать вручную в этом проекте.
+
+<!-- /docs/architecture/ -->
 # SLM Design
 Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.

+## Разделы спецификации
+
+Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
+
+- [Слои](#слои) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
+- [Модули](#модули) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
+- [Сегменты](#сегменты) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
+
+Рекомендуемый порядок чтения: обзор → слои → модули → сегменты.
+
 ## Преимущества

 ### Вертикальная организация домена
@@ -494,7 +508,7 @@ backend-api/
 └── index.ts                     # публичный API
 ```

-Подробное описание сегментов — в разделе [Сегменты](/architecture/segments).
+Подробное описание сегментов — в разделе [Сегменты](#сегменты).

 ### Публичный API

@@ -671,7 +685,7 @@ export const HomeScreen = () => {
 - Не получает данные самостоятельно, не выбирает источник данных и не композирует данные.
 - Не содержит бизнес-логику или сценарную логику.

-Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе [Компонент](/architecture/modules#компонент).
+Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе [Компонент](#компонент).

 Корневой файл модуля в `ui/` не размещается. Он лежит в корне модуля: `{module-name}.tsx`.

--- a/src/screens/home/config/home-screen.config.ts
+++ b/src/screens/home/config/home-screen.config.ts
@@ -1,5 +1,3 @@
-const version = __BUILD_VERSION__
-
 export const repositoryUrl = 'https://gromlab.ru/gromov/slm-design'

 export const homeCards = [
@@ -10,10 +8,19 @@ export const homeCards = [
    cta: 'Открыть →',
  },
  {
-    title: 'ARCHITECTURE.md',
-    description: 'Полная версия архитектуры в одном файле',
-    href: `/ARCHITECTURE.md?v=${version}`,
-    cta: 'Открыть →',
+    title: 'Скачать',
+    description: 'Локальная копия спецификации и архив документации.',
+    actions: [
+      {
+        href: '/ARCHITECTURE.md',
+        label: 'ARCHITECTURE.md',
+      },
+      {
+        href: '/slm-design.zip',
+        label: 'slm-design.zip',
+        download: true,
+      },
+    ],
  },
  {
    title: 'Ассистенту',
--- a/src/screens/home/home.screen.tsx
+++ b/src/screens/home/home.screen.tsx
@@ -48,7 +48,12 @@ export function HomeScreen() {
              <p>{card.description}</p>
              <div className={styles.cardActions}>
                {card.actions.map((action) => (
-                  <a className={styles.cardAction} href={action.href} key={action.href}>
+                  <a
+                    className={styles.cardAction}
+                    download={'download' in action ? action.download : undefined}
+                    href={action.href}
+                    key={action.href}
+                  >
                    {action.label}
                  </a>
                ))}
Author	SHA1	Message	Date
S.Gromov	1a1de7cad4	fix: исправить доступность артефактов документации All checks were successful CI/CD Pipeline / build (push) Successful in 16s Details CI/CD Pipeline / version (push) Successful in 4s Details CI/CD Pipeline / docker (push) Successful in 43s Details CI/CD Pipeline / deploy (push) Successful in 7s Details - добавлены HTML-подсказки для обнаружения llms.txt агентами - обновлена карточка скачивания спецификации и архива - добавлен раздел с порядком чтения спецификации - исправлена генерация ссылок для single-file, Markdown и ZIP - обновлены сгенерированные README.md и ARCHITECTURE.md	2026-05-02 18:51:44 +03:00
S.Gromov	07542330b5	fix: исправить ссылки llms на markdown-файлы All checks were successful CI/CD Pipeline / build (push) Successful in 16s Details CI/CD Pipeline / version (push) Successful in 4s Details CI/CD Pipeline / docker (push) Successful in 42s Details CI/CD Pipeline / deploy (push) Successful in 6s Details - обновлены ссылки llms.txt на доступные .md-файлы - добавлено копирование markdown-файлов в публичную статику - исключена docs/public из сканирования VitePress и индекса Git - добавлена пометка для локальной копии ARCHITECTURE.md	2026-05-02 06:53:35 +03:00
S.Gromov	245dbbe302	chore: обновить правила отдачи документации All checks were successful CI/CD Pipeline / build (push) Successful in 16s Details CI/CD Pipeline / version (push) Successful in 4s Details CI/CD Pipeline / docker (push) Successful in 41s Details CI/CD Pipeline / deploy (push) Successful in 5s Details - добавлены редиректы для устаревших путей llms - добавлен редирект HTML-страниц на чистые URL - добавлена защита текстовых артефактов от SPA-фолбэка - включены чистые URL в конфигурации VitePress	2026-05-01 23:57:56 +03:00
S.Gromov	ee5b947fb0	fix: заменить cache-busting через query на Cache-Control заголовок (#6 ) All checks were successful CI/CD Pipeline / build (push) Successful in 17s Details CI/CD Pipeline / version (push) Successful in 4s Details CI/CD Pipeline / docker (push) Successful in 1m4s Details CI/CD Pipeline / deploy (push) Successful in 7s Details fix: заменить cache-busting через query на Cache-Control заголовок - Убран query-параметр ?v= из ссылки на ARCHITECTURE.md - Добавлен заголовок Cache-Control: no-cache для ARCHITECTURE.md в Caddyfile Reviewed-on: #6 Co-authored-by: S.Gromov <zz-gromov@ya.ru> Co-committed-by: S.Gromov <zz-gromov@ya.ru>	2026-05-01 21:42:36 +03:00
S.Gromov	b3d501c920	chore: обновить CI для dev-ветки и актуализировать CONTRIBUTING.md All checks were successful CI/CD Pipeline / build (push) Successful in 17s Details CI/CD Pipeline / version (push) Successful in 4s Details CI/CD Pipeline / docker (push) Successful in 56s Details CI/CD Pipeline / deploy (push) Successful in 7s Details - Добавлен триггер dev в CI со сборочным job (generate + docs:build + build) - Убраны устаревшие шаги: npm run docs, коммит generated/, README_RU.md - Прод-пайплайн: build → version (тег) → docker → deploy - CONTRIBUTING.md переписан под текущую структуру проекта	2026-05-01 21:18:09 +03:00