# Универсальное мастер-ТЗ для AI-агентов: SEO + AI-контекст

> Единый автоисполняемый сценарий для проверки, синхронизации и улучшения SEO-слоя и AI-контекста на любом домене экосистемы Dragon Education.
> Везде `https://DOMAIN` — подставляй текущий боевой домен (tv140380.ru, dragon-education.ru, dragon-russian.ru, skills-panel.ru и т.д.).

---

## 0. Режим запуска и контекст

### 0.1 Обязательная загрузка перед любыми действиями

⚠ **БЕЗ ВЫПОЛНЕНИЯ ЭТОГО ШАГА СЦЕНАРИЙ НЕ ЗАПУСКАТЬ**

ИИ-агент обязан перед любыми действиями:

1. **Загрузить контекстные файлы текущего домена** (если существуют):
   - `https://DOMAIN/ai-context.json` → Извлечь: `pages[]`, `ecosystem.projects[]`, `stableSEO` флаги
   - `https://DOMAIN/ai-context.md` → Понять содержание и миссию проекта
   - `https://DOMAIN/ai-lovable-guide.md` → Правила работы, шаблоны мета-тегов, защиты
   - `https://DOMAIN/ai-lovable-update.md` → Этот сценарий (уже загружен)

2. **Если какого-то файла нет** — создать по образцу `https://tv140380.ru/` с той же структурой полей, адаптировав под реальный контент и роль DOMAIN.

3. **Загрузить рабочие файлы проекта**:
   - `src/data/seo.ts` → текущие title/description
   - `public/sitemap.xml` → текущие URL
   - `public/robots.txt` → правила индексации
   - `public/ai-seo.json` → данные для Cloudflare Worker
   - `index.html` → noscript + JSON-LD

4. **Подтвердить загрузку в отчёте**:
```markdown
### Контекст загружен
| Файл | Статус | Данные |
|------|--------|--------|
| ai-context.json | ✓ Загружен | N страниц, M stableSEO |
| ai-lovable-guide.md | ✓ Загружен | Шаблоны мета готовы |
| seo.ts | ✓ Прочитан | N записей |
| sitemap.xml | ✓ Прочитан | N URL |
```

### 0.2 Источники истины

| Файл | Роль | URL |
|------|------|-----|
| `/ai-context.json` | Карта домена, экосистема, страницы, contentSummary | `https://DOMAIN/ai-context.json` |
| `/ai-context.md` | Человекочитаемый контекст | `https://DOMAIN/ai-context.md` |
| `/ai-lovable-guide.md` | Правила работы, SEO-шаблоны | `https://DOMAIN/ai-lovable-guide.md` |
| `/ai-lovable-update.md` | Этот файл — мастер SEO-инструкция | `https://DOMAIN/ai-lovable-update.md` |
| `/ai-seo.json` | Данные для Cloudflare Worker | `https://DOMAIN/ai-seo.json` |

### 0.3 Рабочие SEO-файлы проекта

| Файл | Функция |
|------|---------|
| `src/data/seo.ts` | title, description, keywords для React (Helmet) |
| `src/components/Seo.tsx` | Универсальный SEO-компонент |
| `public/sitemap.xml` | URL, lastmod, priority для поисковиков |
| `public/robots.txt` | Правила индексации |
| `public/ai-seo.json` | Данные для Cloudflare Worker HTMLRewriter |
| `index.html` → `<noscript>` | Fallback для краулеров без JS |
| `index.html` → JSON-LD | Структурированные данные Schema.org |

### ⚠ КРИТИЧЕСКАЯ ДИРЕКТИВА

**НЕ ТРОГАТЬ:**
- Контент страниц (тексты, изображения)
- Логику компонентов
- Стили и дизайн
- Что-либо вне SEO-файлов

---

## 1. Архитектура доставки (стандарт v9)

**Действующая цепочка v9:** `Cloudflare → OpenResty → Lovable`. Метатеги и JSON-LD берутся из статического `index.html` и `ai-seo.json`; отдельный Cloudflare Worker v6.x как обязательное звено **снят** — описание ниже сохранено только как исторический контекст для доменов, где он ещё включён.

**Канон фактов (обязателен для всех доменов экосистемы):**

- «собственная защищённая технология»; формулировки «запатентованная технология», «получен патент» **запрещены** до выдачи патента;
- «Участник проекта Сколково с 2023 года», ID 1125355 — не «резидент», не «с 2019»;
- **пять объектов ИС**: заявка на изобретение РФ № 2025106036 (экспертиза по существу), PCT/RU2026/050055, свидетельство ПрЭВМ № 2024690015, заявка на промышленный образец № 2025501183, товарный знак № 1149940;
- 12 лет R&D с 04.04.2014; 17 тыс.+ **оплативших клиентов** (не «учеников», не «11 лет», не «17 500+»);
- точность формирования навыка >99%, доступность 99,98%;
- показатель **ROI из актуальных материалов удалён**; допускается только в архивных разделах с пометкой года оценки;
- термин «Experience Hardening» не использовать в юридических и государственных материалах и не подавать как название технологии;
- дата обновления машиночитаемых файлов ставится автоматически при сборке.

### 1.1 Исторический контекст: Cloudflare Worker v6.4

Ранее на уровне инфраструктуры был развернут общий Cloudflare Worker v6.4:


- `configureByHost(request)` сопоставляет `Host` → `ORIGIN_SUBDOMAIN` и `SITE_URL`
  - Примеры: `dragon-education.ru` → `dragon-education.lovable.app`; `tv140380.ru` → `tv140380.lovable.app`
- `getOrigins()` для любого DOMAIN возвращает:
  - `LOVABLE_ORIGIN` = `https://{ORIGIN_SUBDOMAIN}.lovable.app`
  - `SEO_URL` = `{LOVABLE_ORIGIN}/ai-seo.json`
  - `GEO_URL` = `{LOVABLE_ORIGIN}/ai-geo.json` (опционально)
- Для ботов (Googlebot, PerplexityBot, GPTBot, Claude-Web, ChatGPT-User, Anthropic-ai и др.) включается `HTMLRewriter`:
  - `TitleHandler` — `<title>`
  - `MetaHandler` — description, OG, Twitter
  - `CanonicalHandler` — `<link rel="canonical">`
  - `JsonLdHandler` — `<script type="application/ld+json">`
  - `HreflangHandler` — hreflang-линки (на основе ai-geo.json)

**Требования:**
1. **НЕ** создавать новый Worker, **НЕ** переписывать архитектуру
2. Только обновлять SEO-данные, с которыми Worker уже работает
3. Разрешены только точечные правки (добавить нового бота в список `BOT_AGENTS`)

---

## 2. Аудит маршрутов

### 2.1 Собрать полный список маршрутов

- **Статические**: `/`, лендинги, разделы, архивы
- **Динамические**: `/lesson/*`, `/category/*`, `/library/life/*`, `/library/article/*` и т.п.
- **Служебные**: 404/NotFound, редиректы, старые версии

### 2.2 Для каждого маршрута проверить

- Есть ли title и description в `seo.ts`
- Есть ли запись в `sitemap.xml`
- Есть ли объект в `ai-seo.json`
- Есть ли в `ai-context.json` и `ai-context.md`
- Есть ли в `index.html` (noscript + BreadcrumbList)
- Корректный canonical и robots
- Обновляются ли og:* и twitter:*

### 2.3 Проверка через curl

```bash
curl -H "User-Agent: PerplexityBot" https://DOMAIN/mission
curl -H "User-Agent: Googlebot" https://DOMAIN/expansion/tipler
```

Убедиться, что Worker отдаёт:
- Уникальный `<title>` (не мета главной!)
- Уникальный `<meta name="description">`
- Корректный `<link rel="canonical">`
- JSON-LD (если уместно)

Если страница отдаёт мета главной — это ошибка SEO-слоя, а не повод переписывать Worker.

---

## 3. ai-seo.json — единый SEO-слой для Worker

### 3.1 Структура

```json
{
  "meta": { "version": "1.0.0", "lastUpdated": "YYYY-MM-DD" },
  "default": {
    "title": "…",
    "description": "…",
    "image": "…",
    "locale": "ru_RU",
    "jsonLd": { "@context": "https://schema.org", "@type": "WebSite", "…": "…" }
  },
  "pages": [
    {
      "path": "/example",
      "title": "…",
      "description": "…",
      "canonical": "https://DOMAIN/example",
      "ogImage": "…",
      "noindex": false,
      "jsonLd": { "@context": "https://schema.org", "@type": "Article", "…": "…" }
    }
  ]
}
```

### 3.2 Правила для всех доменов

1. Для каждого маршрута из `ai-context.json.pages` создать/обновить запись в `pages[]`:
   - `path` — строгое соответствие, без `/index`
   - `title` — до ~60 символов, уникальный
   - `description` — до ~160 символов, ясный конспект
   - `canonical` — `https://DOMAIN` + path
   - `ogImage` — осмысленная картинка
   - `noindex` — true только для служебных страниц

2. **StableSEO-страницы** (`stableSEO: true` в ai-context.json):
   - Нельзя менять смысл title/description
   - Допускаются только мягкие правки: орфография, чёткость, длина

3. **Типы JSON-LD по контенту**:
   - Миссия / About: `Organization` / `EducationalOrganization` + `WebSite`
   - Статьи / научные метафоры: `Article` / `BlogPosting` с `headline`, `description`, `author`, `datePublished`, `mainEntityOfPage`, `image`
   - Хаб-страницы: `CollectionPage`
   - FAQ-блоки: `FAQPage`
   - Иерархии: `BreadcrumbList`
   - 404/NotFound: осмысленный title/description, `noindex: true`

---

## 4. seo.ts и Seo-компонент

### 4.1 Централизованный SEO-конфиг

`src/data/seo.ts` (или `seoConfig.ts`) — каждый маршрут имеет уникальный SEO-набор:

- Статические страницы: явная запись в `pageSeo[path]`
- Динамические: фабрики (`getLessonSeo`, `getCategorySeo`, `getArticleSeo` и т.п.)
- Добавить в `allRoutes` с `priority` и `changefreq`

**Запрещено**: захардкоженные `<title>` / `<meta>` прямо в страницах — всё через Seo-компонент.

### 4.2 Seo-компонент (`Seo.tsx`)

```tsx
import Seo from "@/components/Seo";

// Статические страницы (данные из seo.ts по pathname)
<Seo />

// Динамические с переопределениями
<Seo title="Кастомный заголовок" description="Кастомное описание" />
```

- Получает `pathname` из роутера
- Ищет запись в `seo.ts`
- Рендерит `<title>`, `<meta>`, OG/Twitter, JSON-LD
- Подключён на **всех** публичных страницах
- Для 404: отдельный SEO-набор с `noindex`

### 4.3 Шаблоны мета-тегов

**Title** (до 60 символов):
```
{Название страницы} — {Имя проекта}
{Название страницы} | {Имя проекта}
```

**Description** (до 160 символов): начинать с главной выгоды или ключевого факта.

**Canonical URL**: всегда `https://DOMAIN{path}`

---

## 5. index.html, noscript и JSON-LD

### 5.1 Требования к `<head>`

1. `<link rel="sitemap" type="application/xml" href="/sitemap.xml">`
2. Корректный favicon
3. OG и Twitter-теги: `og:title`, `og:description`, `og:image`, `og:url`; `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`
4. JSON-LD:
   - `WebSite` с `name`, `url`, `description`, `potentialAction`
   - `Organization` / `EducationalOrganization` с `name`, `url`, `logo`, `founder`, `sameAs` (домены экосистемы)
   - `BreadcrumbList` для ключевых страниц

### 5.2 noscript — AI-friendly fallback

```html
<noscript>
  <h1>Название проекта</h1>
  <p>Краткое описание миссии/технологии.</p>
  <nav>
    <a href="/">Главная</a> |
    <a href="/mission">Миссия</a> |
    <a href="/technology">Технология</a> |
    <!-- ... -->
  </nav>
  <article data-page="/path">
    <h3><a href="/path">Заголовок страницы</a></h3>
    <p>Описание содержимого для краулеров без JS.</p>
  </article>
</noscript>
```

- Не должен противоречить `ai-context.json` / `ai-context.md`
- Это место, куда AI-бот (и человек без JS) заглядывает за реальным контентом
- Для содержательных страниц можно вложить полные тексты

---

## 6. sitemap.xml и robots.txt

### 6.1 sitemap.xml

- Все важные публичные маршруты + AI-файлы (`ai-context.json`, `ai-context.md`)
- Для каждого `<url>`:
  - `<loc>` — полный URL на `https://DOMAIN`
  - `<lastmod>` — дата последнего SEO-апдейта
  - Осмысленные `changefreq` и `priority`
- Убрать мусорные/мертвые URL

### 6.2 robots.txt

```
User-agent: *
Allow: /

User-agent: GPTBot
Allow: /

User-agent: ChatGPT-User
Allow: /

User-agent: Google-Extended
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: Claude-Web
Allow: /

User-agent: anthropic-ai
Allow: /

Sitemap: https://DOMAIN/sitemap.xml
```

- Явно разрешить всех AI-ботов
- Не запрещать доступ к `/ai-context.json`, `/ai-context.md`
- Ограничить только реально внутренние/админские области

---

## 7. AI-контекст: ai-context.json и ai-context.md

### 7.1 ai-context.json

Минимальная структура верхнего уровня:
- `version` (например, `"20260316-1"`)
- `lastUpdated` (дата)
- `language` (например, `"ru"`)
- `description` — кратко, о чём домен и его роль в экосистеме
- `domain` — сам DOMAIN
- `ecosystem` — полный список доменов Dragon Education (`domain`, `role`, `status`, описание)
- `pages[]` — `path`, `title`, `description`, `contentSummary`, `stableSEO`
- `ai_instructions` / `aiInstructions`

### 7.2 ai-context.md

Человекочитаемое описание:
- Миссия проекта
- Ключевые сущности/уровни/миры
- Краткие описания основных страниц
- Таблица экосистемы доменов и их ролей
- Дата последнего обновления

Структура и тон — адаптированы под конкретный DOMAIN.

---

## 8. AI-SEO Sync Flow (7-точечная синхронизация)

При **любом** добавлении/удалении/обновлении страниц, разделов или крупных блоков контента — обязателен проход по всем 7 точкам:

### 8.1 Обновить `ai-context.json`
- `pages[]` + `ecosystem` + `contentSummary`
- Обновить `version` и `lastUpdated`

### 8.2 Обновить `ai-context.md`
- Добавить строку в таблицу маршрутов
- Обновить дату

### 8.3 Обновить `src/data/seo.ts`
- Добавить в `pageSeo` запись с `path`, `title`, `description`, `keywords`, `stableSEO`
- Добавить в `allRoutes` с `priority` и `changefreq`
- Динамические — через фабрики

### 8.4 Обновить `public/sitemap.xml`
- `<url>` с `loc`, `lastmod`, `changefreq`, `priority`
- `lastmod` = текущая дата

### 8.5 Обновить head + noscript (`index.html`)
- BreadcrumbList JSON-LD: добавить ListItem
- noscript: добавить секцию с описанием и ссылками

### 8.6 Обновить `public/ai-seo.json`
- Добавить объект в `pages[]`
- Обновить `meta.lastUpdated`

### 8.7 Прогнать чеклист анти-регрессии
- Таблица соответствия: `path` ↔ `title/description` ↔ `sitemap` ↔ `ai-context`
- Ни одна внутренняя страница не должна отдавать мета главной

### 8.8 Проверить страницу
- `<Seo />` компонент с корректными props или тянет из `seo.ts` по pathname

---

## 9. StableSEO защита

### 9.1 Алгоритм для stableSEO-страниц

Страницы с `stableSEO: true` имеют защищённые мета-теги.

**Правила:**
- **НЕ изменяйте** смысл `title` и `description` без явного запроса пользователя
- Допускаются только формальные правки: орфография, длина, удаление мусора
- Обязательно синхронизировать `canonical` и `ogImage` с реальным URL

### 9.2 Анти-регрессия

При каждом обновлении проверять:
1. Ни одна внутренняя страница не стала отдавать мета главной
2. `sitemap` / `robots` / `index.html` / `ai-context` — согласованы и актуальны
3. Все stableSEO-страницы сохранили свои мета без изменения смысла

---

## 10. Валидация уникальности мета

Обязательная проверка:
1. **Дубли title**: у каждой страницы — уникальный title
2. **Дубли description**: у каждой страницы — уникальное description
3. **Canonical**: ведёт на правильный URL, не всегда на `/`
4. **Длина**: title ≤ 60, description ≤ 160 символов
5. **noindex**: только для реально служебных страниц

Формат отчёта:
```markdown
### Валидация уникальности
| Path | Title (длина) | Description (длина) | Дубли? | Canonical |
|------|---------------|---------------------|--------|-----------|
| / | ✓ (48) | ✓ (142) | Нет | ✓ |
```

---

## 11. Автоисправления

### 11.1 Алгоритм

Для страниц **без** `stableSEO`:
1. Если `title` отсутствует → автогенерация по шаблону: `{PageName} — {SiteName}`
2. Если `description` отсутствует → автогенерация из `contentSummary` в `ai-context.json`
3. Если `canonical` отсутствует → `https://DOMAIN{path}`
4. Если нет записи в `sitemap.xml` → добавить с текущей датой

### 11.2 Шаблоны исправлений

**sitemap.xml:**
```xml
<url>
  <loc>https://DOMAIN/new-page</loc>
  <lastmod>YYYY-MM-DD</lastmod>
  <changefreq>monthly</changefreq>
  <priority>0.6</priority>
</url>
```

**ai-context.json:**
```json
{
  "path": "/new-page",
  "title": "…",
  "description": "…",
  "contentSummary": "…",
  "stableSEO": false
}
```

**seo.ts:**
```typescript
"/new-page": {
  title: "…",
  description: "…",
  keywords: "…"
}
```

**noscript:**
```html
<article data-page="/new-page">
  <h3><a href="/new-page">Заголовок</a></h3>
  <p>Описание содержимого.</p>
</article>
```

---

## 12. Итеративная прокачка

При каждом повторном апгрейде — не только «проверка», но и **улучшение**:

### 12.1 Переаудит маршрутов
- Нет ли новых страниц без SEO
- Можно ли улучшить title/description (конкретнее, кликабельнее)

### 12.2 Уточнение мета-данных
- Переформулировать слишком общие описания
- Улучшить keywords для динамических фабрик

### 12.3 Усиление структурной разметки
- Добавить `Article`, `FAQPage`, `BreadcrumbList` там, где раньше был минимум
- Убедиться, что новые схемы не конфликтуют с существующими JSON-LD

### 12.4 Уточнение AI-контекста
- Обновить `lastUpdated`
- Дополнить `pages[]` более точными описаниями
- Улучшить формулировки ролей в `ecosystem`

### 12.5 Внутренняя связность
- Нет ли новых страниц вне `sitemap`
- Все маршруты попали в `pages` и таблицу экосистемы

### 12.6 Правило

> Для каждой части (seo.ts, sitemap, robots, index.html, ai-context) задай вопрос: можно ли сделать мета точнее, разметку богаче, экосистему полнее? Если да — считай это задачей, а не опцией.

---

## 13. Переносимость между доменами

### 13.1 Адаптация нового домена

1. Загрузить master-файлы с `tv140380.ru` как эталон
2. Определить `DOMAIN` (spark-time.ru, dragon-education.ru и т.д.)
3. Попытаться получить локальные AI/SEO-файлы DOMAIN
4. Если 404 — создать по образцу `tv140380.ru` с адаптацией

### 13.2 Минимальные требования для нового домена

В `ai-context.json`:
- `version`, `lastUpdated`, `language`, `description`, `domain`
- `ecosystem`, `pages[]`, `ai_instructions`

Обязательные файлы:
- `public/ai-context.json`
- `public/ai-context.md`
- `public/ai-seo.json`
- `public/sitemap.xml`
- `public/robots.txt`
- `src/data/seo.ts` + `src/components/Seo.tsx`

---

## 14. Критерий готовности

### 14.1 Проверка через curl

```bash
curl -H "User-Agent: PerplexityBot" https://DOMAIN/
curl -H "User-Agent: PerplexityBot" https://DOMAIN/mission
curl -H "User-Agent: PerplexityBot" https://DOMAIN/nonexistent-page
```

Проверить:
1. `<title>` и `<meta name="description">` уникальны и осмысленны
2. `<link rel="canonical">` ведёт на правильный URL
3. JSON-LD корректен и не дублируется хаотично
4. HTML содержит реальное содержимое или понятный noscript

### 14.2 Проверка в браузере

- SPA работает как раньше
- Навигация и компоненты не сломаны
- SEO-изменения не ломают UX

---

## 15. Защита от ложных тревог

### HMR-баг в Lovable Preview

В режиме Preview (dev) Lovable может показывать устаревшие или некорректные `<title>` из-за HMR (Hot Module Replacement). Это **не баг SEO**, а артефакт dev-режима.

**Правило:** Не менять SEO-код из-за того, что Preview показывает неправильный title. Проверяй через:
- `curl` с ботовым User-Agent
- Опубликованную версию
- `view-source:` в браузере

---

## 16. Ограничения

1. **Не менять** тексты курсов, статей, поэзии и прочий смысловой контент
2. **Не ломать** дизайн, layout, навигацию и бизнес-логику компонентов
3. **Не переписывать** Cloudflare Worker — только данные
4. Все изменения — **только** в SEO-слое, AI-контексте, структурированной разметке и служебных файлах
5. Если сомневаешься — делай правки минимальными и обратимыми

---

## 17. Финальный чеклист

- [ ] Каждый маршрут имеет запись в `seo.ts` (`pageSeo` + `allRoutes`)
- [ ] Каждый маршрут в `sitemap.xml`
- [ ] Каждый маршрут в `ai-seo.json`
- [ ] Каждый маршрут в `ai-context.json` (`pages[]`)
- [ ] Каждый маршрут в `ai-context.md` (таблица)
- [ ] Каждая страница использует `<Seo />` с корректными данными
- [ ] `index.html` содержит `BreadcrumbList` для ключевых страниц
- [ ] `index.html` noscript содержит описания для ботов
- [ ] `robots.txt` разрешает AI-ботам полный доступ
- [ ] `meta.lastUpdated` / `version` обновлены
- [ ] Ни одна внутренняя страница не отдаёт мета главной
- [ ] Все stableSEO-страницы сохранили свои мета
- [ ] Валидация уникальности пройдена (нет дублей title/description)

---

## 18. Отчёт после апгрейда

### 18.1 Блок «Сохранённая стабильность»
- Подтверждение, что stableSEO не нарушены
- Все файлы согласованы и актуальны

### 18.2 Блок «Что улучшено»
- Какие мета стали лучше и почему
- Какие JSON-LD добавлены/расширены
- Какие страницы/роли добавлены в ai-context
- Любые другие улучшения SEO-слоя

---

## 19. Правило по умолчанию

Если ты (как Lovable/агент) сомневаешься, переписывать ли существующие SEO-данные:

1. Сначала прочитай `ai-context.json` и `ai-context.md`
2. Если страница помечена как `stableSEO: true` — меняй только формальную сторону (длина, повторения, ошибка), без смены смысла
3. Всегда можешь вернуть предыдущий вариант SEO-записи как комментарий/backup, но не выбрасывай информацию

**Эта инструкция должна применяться одинаково для всех доменов экосистемы, обслуживаемых общим Cloudflare Worker.**

---

*Последнее обновление: 2026-03-16*
*Консолидация из: ai-lovable-update-3, ai-seo-universal-tz-2, ai-seo-universal-tz-6-3, ai-seo-universal-tz-3, ai-lovable-update-TZ-master-2, ai-lovable-update-TZ-master-5-4, ai-lovable-update_ТЗ_2, ai-seo-sync-flow-2, ai-seo-sync-flow-копия-2, ai-seo-universal-tz-копия-2*