docs/README.md

# Документация

Единое пространство для идей, черновиков и первых версий документаций, которые ещё формируются и постепенно становятся самостоятельными материалами.

Проект собирает рабочие документации, стандарты и LLM-артефакты в одном месте, чтобы не создавать отдельное пространство для каждого материала на ранней стадии.

## Что внутри

- React/Vite-лендинг со списком документаций.
- VitePress-сборка для `SLM Design`.
- VitePress-сборка для `NextJS Style Guide`.
- VitePress-сборка для `Figma Adaptive Standards`.
- VitePress-сборка для `Template Sync Strategy`.
- Корневой `llms.txt` как карта всех документаций.
- Собственные `llms.txt` и `llms-full.txt` внутри каждой документации.
- ZIP-архивы Markdown-контента для каждой документации.
- Docker/Caddy-конфигурация для публикации статической сборки.
- Gitea CI/CD для ветки `master`.

## Документации

- `SLM Design` — архитектура frontend-приложений через слои, модули, публичные API и DI через фабрики.
- `NextJS Style Guide` — практический стайлгайд для разработки frontend-приложений на Next.js и TypeScript.
- `React Style Guide` — будущие правила написания React-кода.
- `Figma Adaptive Standards` — стандарты подготовки адаптивных макетов в Figma.
- `Template Sync Strategy` — стратегия создания проектов от шаблона и долгосрочного обновления приложений через Git.

## Структура

```text
build.ts                       сборка всего репозитория
projects/<slug>/build.ts       сборка конкретного проекта
projects/<slug>/canons/        исходные Markdown-материалы проекта
projects/<slug>/docs/          VitePress-конфигурация проекта
projects/<slug>/scripts/       уникальные вспомогательные скрипты проекта
projects/_shared/lib/          общие библиотечные функции сборки
projects/_shared/docs/         общая VitePress-тема
src/                           React-лендинг
public/                        статические файлы и сгенерированные документации
dist/                          итоговая статическая сборка
```

## Команды

```bash
npm ci
npm run dev
```

```bash
npm run build
```

Основные скрипты:

- `npm run dev` — запускает Vite dev server.
- `npm run build` — одной командой собирает проектные документации, ZIP-архивы, корневой `llms.txt`, агентов и лендинг.
- `npm run build:slm-design` — собирает только проект `SLM Design`.
- `npm run build:nextjs-style-guide` — собирает только проект `NextJS Style Guide`.
- `npm run build:figma-adaptive-standards` — собирает только проект `Figma Adaptive Standards`.
- `npm run build:template-sync-strategy` — собирает только проект `Template Sync Strategy`.
- `npm run app:build` — собирает React/Vite-лендинг без проектных артефактов.
- `npm run lint` — запускает ESLint.

## Проекты

Каждая документация живёт в собственной папке `projects/<slug>` и сама владеет исходниками, конфигами и сборкой.

```text
projects/slm-design/
  build.ts
  project.config.ts
  canons/
  docs/
    docs.config.ts
    .vitepress/
  scripts/
```

Общая команда `npm run build` запускает корневой `build.ts`. Он последовательно вызывает `projects/<slug>/build.ts`, затем собирает общие артефакты репозитория.

Если скрипт является библиотечной функцией сборки, он лежит в `projects/_shared/lib`. Если скрипт уникален для проекта, он лежит в `projects/<slug>/scripts`.

## LLM-артефакты

Корневой файл:

```text
/llms.txt
```

Он является навигационной картой пространства документаций и указывает на `llms.txt` конкретных материалов.

Пример проектных артефактов:

```text
/slm-design/llms.txt
/slm-design/llms-full.txt
/nextjs-style-guide/llms.txt
/nextjs-style-guide/llms-full.txt
/figma-adaptive-standards/llms.txt
/figma-adaptive-standards/llms-full.txt
/template-sync-strategy/llms.txt
/template-sync-strategy/llms-full.txt
/slm-design/slm-design.zip
/nextjs-style-guide/nextjs-style-guide.zip
/figma-adaptive-standards/figma-adaptive-standards.zip
/template-sync-strategy/template-sync-strategy.zip
```

Корневой `llms-full.txt` намеренно не создаётся. Полные bundles остаются внутри конкретных документаций.

## Caddy

`Caddyfile` отдаёт статическую сборку из `/srv`, поддерживает clean URLs и выставляет контекстные `Link` headers:

- `/slm-design/*` → `/slm-design/llms.txt`
- `/nextjs-style-guide/*` → `/nextjs-style-guide/llms.txt`
- `/react-style-guide/*` → `/react-style-guide/llms.txt`
- `/figma-adaptive-standards/*` → `/figma-adaptive-standards/llms.txt`
- `/template-sync-strategy/*` → `/template-sync-strategy/llms.txt`
- остальные пути → `/llms.txt`

Редиректов `llms.txt` в корень нет.

## Docker

Локальная проверка образа:

```bash
docker build -t all-docs:test .
```

Docker-сборка выполняет:

```bash
npm run build
```

## CI/CD

Workflow находится в `.gitea/workflows/ci.yml`.

Особенности:

- запускается только для ветки `master`;
- не создаёт версии и теги;
- собирает документацию, лендинг и Docker-образ;
- деплоит контейнер `docs` в Docker network `web`.