# SEO Farm: локальный SEO-редакторский контур

## 1. Вводная

SEO Farm — локальное приложение для автоматизации ручной SEO-работы с текстами сайта:

- анализ существующей страницы или чернового текста;
- извлечение смысловых тем и seed-запросов из уже сформированного текста;
- сбор реальных ключевых запросов через Яндекс Wordstat;
- чистка, группировка и привязка ключей к секциям страницы;
- проверка SEO-структуры, переспама, конкурирующих смыслов и длины текста под дизайн;
- редактор SEO-правок и фильтр качества текста через `ru-text`;
- аудит изображений, видео, alt-текстов, постеров, подписей и медиа-контекста;
- генерация аккуратных вариантов правок через Codex;
- ручное утверждение перед внесением изменений.

Ключевая идея: не заставлять модель "напихать ключи", а построить управляемый процесс:

```text
черновик / готовая страница
  -> смыслы и секции
  -> seed-запросы
  -> Wordstat
  -> ключи и частотность
  -> карта ключей по секциям
  -> SEO-правки текста и медиа-описаний
  -> анти-переспам
  -> редакторский ru-text-фильтр
  -> ручное утверждение
  -> сайт
```

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

## 2. Почему это нужно

Текущая боль:

- ключевые слова приходится искать руками;
- Wordstat требует ручного копирования, фильтрации и группировки;
- нейросети часто вставляют ключи формально, портят смысл и делают текст похожим на SEO-портянку;
- платные сервисы вроде Rush Analytics, Text.ru, Тургенева и NeuronWriter частично закрывают задачу, но не дают гибкого локального процесса под конкретный сайт и дизайн;
- сайт может иметь жёсткие визуальные ограничения: текст нельзя просто раздувать ради SEO;
- нужен контроль не только по ключам, но и по тону, структуре, конкурентным смыслам и длине блоков.

SEO Farm должна стать локальной "панелью управления" для этого процесса.

Важно: инструмент работает не только с видимым текстом страницы. Он должен проверять медиа-слой сайта: изображения, видео, постеры, подписи, alt-тексты, aria-label/title и контекст вокруг медиа. Для SEO и доступности это отдельная зона работы, а не побочный пункт.

## 3. Основной пользовательский сценарий

### 3.1. Project Setup

MVP работает с уже существующим кодом, страницей или черновым текстом. Создание текста с нуля не входит в MVP.

Пользователь создаёт проект в SEO Farm и указывает `targetProjectPath` — папку подопытного сайта. Пользователь не выбирает вручную `index.html`, `css`, `images` и другие файлы. Приложение само сканирует проект.

```text
Project Setup
  -> create project
  -> choose project source
  -> MVP source: local_folder -> targetProjectPath
  -> save project + source config to Postgres
  -> run project scan
```

Codex через `codex exec` должен запускаться с явным контекстом target project:

```text
- может читать source через local_folder adapter
- или prompt получает абсолютные пути к extracted snapshot/projectIndex файлам
- результат возвращается как structured JSON
- target project не меняется напрямую моделью
```

### 3.2. Project Scan

Приложение сканирует папку проекта и строит `projectIndex`:

- HTML/Markdown/текстовые страницы;
- CSS;
- изображения;
- видео;
- возможные entry points;
- игнорируемые технические папки: `.git`, `node_modules`, `dist`, build-артефакты.

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

### 3.3. Baseline Audit

Baseline audit — первый смысловой шаг пользователя после scan. Парсинг и извлечение текста происходят внутри аудита технически, но в UI пользователь видит именно аудит проекта/страницы.

Проверки:

- структура страниц;
- `title`;
- `description`;
- `h1/h2`;
- видимые тексты;
- media-объекты;
- alt/title/aria;
- filename;
- desktop/adaptive дубли;
- пустые/слабые SEO-зоны;
- первичные проблемы, которые есть до работы с Wordstat.

### 3.4. Page Workspace

Пользователь выбирает страницу или группу страниц для SEO-цикла.

Для выбранной страницы создаются:

```text
originalText
  - неизменённый снимок текста из target project

workingText
  - рабочая копия для SEO-правок

sectionMap
  - sectionId
  - DOM selector
  - source file
  - context
```

Codex и пользователь работают только с `workingText`. Target project не меняется до ручного `Apply`.

### 3.5. Meaning Extraction

Codex через `codex exec` анализирует выбранную страницу и извлекает:

- главный смысл страницы;
- смыслы секций;
- продуктовые сущности;
- потенциальные seed-запросы;
- возможные конкурирующие интенты;
- зоны с риском SEO-размытия;
- зоны с ограничением по длине.

Важно: seed-запросы рождаются из уже существующего смысла текста, а не из головы.

### 3.6. Seed Review

UI показывает seed-запросы. Пользователь:

- включает/выключает seeds;
- добавляет свои;
- объединяет похожие;
- помечает приоритет.

После утверждения seeds идут в Wordstat.

### 3.7. Wordstat Collection

Wordstat MCP в этой архитектуре — просто "рука в Wordstat":

- получает похожие запросы;
- получает частотность;
- получает динамику;
- получает региональные данные, если нужно.

Результаты сохраняются в истории проекта. Запросы группируются по частотности:

- ВЧ — высокочастотные, широкие, использовать осторожно;
- СЧ — среднечастотные, основные рабочие;
- НЧ — низкочастотные, точные и часто полезные для секций.

### 3.8. Keyword Cleaning

Keyword Cleaning — assisted workflow, не ручная таблица с нуля.

`keywordService` предлагает классификацию:

- `use` — использовать на странице;
- `support` — поддерживающие формулировки;
- `article` — отложить в backlog будущих материалов, не пихать в текущую страницу;
- `risky` — можно использовать только аккуратно;
- `trash` — удалить.

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

### 3.9. Keyword Map

Keyword Map не должен быть ручной дрочней.

Система предлагает:

- какой ключ к какой секции относится;
- роль ключа: `primary`, `secondary`, `supporting`, `do_not_use_on_page`, `article_backlog`;
- `soft_forms`;
- лимиты точного вхождения;
- предупреждения о риске переспама.

Пользователь редактирует и утверждает предложения.

### 3.10. Optimization Plan

Перед переписыванием система формирует план:

- какие секции трогать;
- какие секции не трогать;
- какие ключи добавить;
- какие ключи сократить;
- какие media SEO задачи есть;
- где есть риск по длине;
- где есть риск по тону.

Без подтверждения пользователя план не переходит в rewrite.

### 3.11. Rewrite Workspace

Codex получает структурированное задание:

```text
Секция: ...
Текущий workingText: ...
Смысл: ...
Основные ключи: ...
Поддерживающие ключи: ...
Лимит длины: не длиннее текущего / максимум N строк
Тон: строгий B2B, без рекламной воды
Запрещено: ломать смысл, раздувать текст, делать SEO-портянку
Задача: предложить 3 варианта правки
```

Модель предлагает варианты. Пользователь выбирает, редактирует или просит переписать. Изменения попадают только в `workingText`.

### 3.12. Media SEO: изображения, видео и alt-тексты

Отдельный сценарий нужен для медиа:

1. Приложение парсит страницу и находит:
   - `<img>`;
   - `<picture>`;
   - `srcset`;
   - `<video>`;
   - `poster`;
   - `<source>`;
   - фоновые изображения в CSS, если выбран анализ проекта;
   - подписи, соседний текст и заголовки секции.

2. Для каждого медиа-объекта фиксируются:
   - путь к файлу;
   - имя файла как SEO-сигнал и источник подсказки для поисковика;
   - секция страницы;
   - текущий `alt`;
   - `title`;
   - `aria-label`;
   - подпись рядом;
   - размеры;
   - вес файла, если доступен;
   - контекст секции;
   - связанные ключи из карты страницы.

3. Если это изображение:
   - проверить, есть ли `alt`;
   - определить, декоративное оно или смысловое;
   - для смыслового изображения предложить alt;
   - для декоративного изображения предложить оставить пустой `alt=""` или пометить как decorative.

4. Если это видео:
   - проверить наличие понятного контекста вокруг видео;
   - проверить `poster`;
   - предложить текстовое описание видео;
   - при необходимости предложить подпись/транскрипт;
   - не пытаться писать `alt` прямо на `<video>`, потому что у видео нет обычного `alt` как у изображения.

5. Для распознавания медиа:
   - для изображений модель получает превью или путь к файлу;
   - для видео сначала извлекаются ключевые кадры через FFmpeg;
   - если модель не может уверенно понять содержание, UI должен попросить пользователя уточнить, что изображено.

6. Подбор ключей:
   - alt сначала описывает изображение, а не набивается ключами;
   - ключ можно добавить только если он естественно совпадает с содержанием медиа и секцией;
   - нельзя вставлять ключ в alt, если он не описывает изображение;
   - имя файла тоже учитывается: оно должно быть осмысленным, но не превращаться в набор ключей через дефисы;
   - для видео ключи лучше использовать в подписи, описании, транскрипте или соседнем тексте.

7. Итог:
   - отчёт по missing/weak/duplicate alt;
   - список медиа без описания;
   - список декоративных медиа;
   - предложения alt/title/подписей;
   - предупреждения о SEO-переспаме в alt;
   - ручное утверждение перед внесением.

### 3.13. Final Validation

После текстовых и media-правок приложение запускает финальную проверку:

- `checkOverseo`;
- `ru-text`;
- проверку конкурирующих смыслов;
- проверку длины;
- структуру `title/description/h1/h2`;
- media SEO checks;
- проверку alt/filename на keyword stuffing;
- финальный diff `originalText` vs `workingText`;
- финальный media diff.

Важно: `Apply` нельзя делать после media-правок без повторной финальной проверки.

### 3.14. Apply / Export

Перед применением UI показывает:

- affected files;
- affected sections;
- text diff;
- media diff;
- filename rename plan;
- validation status.

Пользователь нажимает `Apply to target project`. После apply создаётся changeset и сохраняется история.

Безопасный apply-пайплайн:

```text
1. собрать changeset
2. сделать dry-run
3. сохранить backup affected files в object storage
4. применить изменения через backend
5. проверить rename/update references
6. если что-то упало, выполнить rollback
```

Export:

- zip target project;
- export reports;
- export keyword map;
- export changeset summary.

Автоматически публиковать на сайт не нужно.

## 4. Что делаем в MVP

MVP должен дать рабочий локальный процесс, а не идеальный комбайн.

### Обязательно

- UI на React + Vite;
- локальный backend;
- Postgres как основная база проекта;
- MinIO/S3-compatible object storage для raw artifacts, snapshots, backups и exports;
- запуск Codex через `codex exec`;
- создание локального SEO-проекта;
- Project Source Adapter с типом `local_folder` в MVP;
- выбор `targetProjectPath`, то есть папки сайта/кода, а не ручной выбор отдельных файлов;
- автоматический scan проекта и построение `projectIndex`;
- baseline audit до SEO-правок;
- извлечение страниц, секций, смыслов и seed-запросов из существующего проекта;
- подготовка заданий для Wordstat;
- хранение проектов, ключей, решений, черновиков, changesets и отчётов локально;
- карта страницы и секций;
- assisted Keyword Map: предложения от модели плюс ручное утверждение;
- базовая проверка `title/description/h1/h2`;
- проверка ключей и переспама;
- проверка конкурирующих смыслов;
- контроль длины текстов под дизайн;
- интеграция `ru-text` как редактора SEO-правок и фильтра качества текста;
- аудит изображений и видео;
- генерация/проверка alt-текстов, подписей и медиа-описаний;
- `originalText` и `workingText` в UI, чтобы target project не менялся до apply;
- diff, отчёт в UI и ручное применение изменений;
- история запусков.

### Не обязательно в MVP

- автопостинг;
- полноценный контент-календарь;
- генерация будущих статей;
- трекинг позиций;
- интеграция Яндекс Метрики;
- robots.txt/sitemap editor;
- многопользовательский режим;
- облачный деплой.
- Codex skills как зависимость MVP.
- полноценная версионность `workingText` с откатами.

Codex skills можно добавить позже как усиление повторяемых model workflows:

- `seo-seed-extractor`;
- `seo-keyword-classifier`;
- `seo-copy-editor-ru`;
- `media-seo-alt-writer`.

Сначала нужно стабилизировать базовые инструменты, отчёты и сценарии. Skills не должны быть условием работы MVP.

## 5. Архитектура

### 5.1. Общая схема

```text
React/Vite UI
  -> local backend
  -> task runner
  -> Codex provider
       -> codex exec
       -> later: OpenAI API / other API
  -> SEO tools
  -> Wordstat MCP
  -> ru-text
  -> media analyzer
  -> Postgres + object storage
```

### 5.2. Почему `codex exec`

Для MVP выбираем `codex exec`, потому что:

- работает как CLI-команда;
- можно запускать из backend через `child_process.spawn`;
- удобно дебажить;
- подходит для локального приложения;
- не требует сразу строить сложную агентскую инфраструктуру.

Пример внутренней логики:

```text
UI button
  -> POST /api/tasks/extract-seeds
  -> backend запускает codex exec с подготовленным prompt
  -> результат сохраняется
  -> UI показывает отчёт
```

### 5.3. Абстракция модели

Важно сразу не привязать приложение намертво к `codex exec`.

Нужно заложить интерфейс провайдера:

```ts
interface ModelProvider {
  id: string;
  name: string;
  runTask(input: ModelTaskInput): Promise<ModelTaskResult>;
}
```

Первый провайдер:

```text
codex-exec-provider
```

Будущие провайдеры:

```text
openai-api-provider
anthropic-api-provider
local-llm-provider
custom-http-provider
```

Так приложение можно будет использовать:

- локально через Codex;
- удалённо через API;
- как внутренний инструмент;
- как отдельный продукт.

### 5.4. Локальный backend

Backend отвечает за:

- запуск `codex exec`;
- запуск локальных SEO-скриптов;
- создание и хранение SEO-проектов;
- scan `targetProjectPath` и построение `projectIndex`;
- извлечение страниц, секций, текстов и медиа из проекта;
- сохранение `originalText`, `workingText`, отчётов, решений и changesets;
- интеграцию Wordstat MCP;
- интеграцию `ru-text`;
- анализ HTML/CSS-медиа;
- извлечение технических параметров медиа: размер, вес, preview; EXIF как SEO-сигнал в MVP не нужен;
- извлечение кадров из видео;
- безопасность путей;
- очередь задач;
- лог выполнения.

На старте достаточно Node.js + Express/Fastify.

### 5.5. UI

UI должен быть рабочим инструментом, не лендингом.

Основные экраны:

1. **Project Dashboard**
   - список локальных проектов;
   - `targetProjectPath`;
   - статус последнего анализа.
   - история запусков и changesets.

2. **Baseline Audit**
   - найденные страницы;
   - заголовки;
   - `title/description/h1/h2`;
   - медиа;
   - технические SEO-проблемы до правок;
   - конкурирующие смыслы.

3. **Pages / Source**
   - карта страниц и секций из `projectIndex`;
   - оригинальный текст;
   - рабочий текст;
   - текущий смысл секции;
   - ограничения по длине под дизайн.

4. **Seeds**
   - seed-запросы из текста;
   - источник seed-запроса;
   - чекбоксы для выбора;
   - ручное добавление.

5. **Wordstat**
   - запуск сбора;
   - таблица запросов;
   - частотность;
   - ВЧ/СЧ/НЧ;
   - статус: use/support/article/risky/trash.
   - raw-ответы сохраняются локально.

6. **Keyword Cleaning**
   - нормализация и дедупликация запросов;
   - фильтр мусорных интентов;
   - классификация спорных запросов через Codex;
   - массовое утверждение решений.

7. **Keyword Map**
   - предложенная моделью привязка ключей к страницам и секциям;
   - primary/secondary;
   - soft forms;
   - лимиты точного вхождения;
   - ключи для title/description/headings/alt;
   - заметки.

8. **Optimization Plan**
   - что менять;
   - где менять;
   - какие ключи использовать;
   - какие смыслы нельзя ломать;
   - лимиты по длине и тону.

9. **Rewrite**
   - `originalText` слева;
   - `workingText` справа;
   - выбранные ключи;
   - варианты Codex;
   - ручное редактирование;
   - diff.

10. **Media SEO**
   - список изображений и видео;
   - текущие `alt/title/aria`;
   - контекст секции;
   - preview;
   - статус: ok/missing/weak/duplicate/decorative/needs-human;
   - предложенный alt или описание;
   - связанные ключи;
   - проверка, не превращён ли alt в SEO-переспам.

11. **Final Validation**
   - SEO-структура;
   - переспам;
   - конкурирующие смыслы;
   - длина блоков;
   - `ru-text`;
   - media SEO checks;
   - warnings/errors.

12. **Apply / Export**
   - affected files;
   - diff;
   - ручное подтверждение;
   - запись changeset;
   - export zip/reports/keyword map.

13. **Reports / History**
   - сохранённые отчёты;
   - история runs;
   - история решений по ключам;
   - экспорт в Markdown/JSON.

## 6. Предлагаемая структура проекта

```text
SEO-farm/
  README.md
  SEO_FARM_BRIEF.md
  package.json
  app/
    src/
      components/
      pages/
      services/
      styles/
  server/
    src/
      index.ts
      routes/
      providers/
        model/
          ModelProvider.ts
          CodexExecProvider.ts
          OpenAiApiProvider.ts
        storage/
          StorageProvider.ts
          MinioStorageProvider.ts
      services/
        dbService.ts
        projectSourceService.ts
        storageProvider.ts
        taskRunner.ts
        projectStorage.ts
        projectScanService.ts
        reconcileService.ts
        pageWorkspaceService.ts
        wordstatService.ts
        keywordService.ts
        keywordMapService.ts
        validationService.ts
        changesetService.ts
        applyService.ts
        exportService.ts
        ruTextService.ts
        seoAuditService.ts
        mediaAuditService.ts
  tools/
    seo/
      extractText.ts
      extractSeeds.ts
      checkStructure.ts
      checkOverseo.ts
      checkPageMap.ts
      runRuText.ts
      extractMedia.ts
      checkMediaSeo.ts
      extractVideoFrames.ts
  infra/
    postgres/
    minio/
  docs/
```

## 7. Данные и файлы

### 7.1. `project.json`

```json
{
  "id": "nodedc",
  "name": "Node.DC",
  "source": {
    "type": "local_folder",
    "targetProjectPath": "C:/Users/const/Desktop/landing-correction"
  },
  "scan": {
    "include": ["**/*.html", "**/*.md", "css/**/*.css", "images/**/*", "video/**/*"],
    "exclude": ["node_modules/**", "dist/**", ".git/**"]
  },
  "createdAt": "2026-05-01T00:00:00.000Z"
}
```

### 7.2. Локальное хранение проекта

```text
Postgres:
  - projects
  - project_sources
  - scan_versions
  - pages
  - page_versions
  - sections
  - section_versions
  - media_assets
  - media_versions
  - runs
  - seeds
  - wordstat_jobs
  - wordstat_results
  - keyword_decisions
  - keyword_map_items
  - optimization_plans
  - drafts
  - draft_items
  - validations
  - validation_issues
  - changesets
  - changeset_items
  - exports

Object Storage (MinIO locally, S3 later):
  - projects/project-id/scans/scan-version-id/project-index.json
  - projects/project-id/raw/wordstat/*.json
  - projects/project-id/snapshots/original/*.json
  - projects/project-id/snapshots/working/*.json
  - projects/project-id/reports/*
  - projects/project-id/previews/*
  - projects/project-id/video-frames/*
  - projects/project-id/backups/changeset-id/*
  - projects/project-id/exports/*
```

Правило хранения:

```text
Postgres = source of truth
Object Storage = raw artifacts / snapshots / reports / backups / exports
YAML/JSON/Markdown = export, debug, import/export only
```

### 7.3. `page-map.yml`

`page-map.yml`, `keywords.yml` и `media-map.yml` можно сохранять как export/debug artifacts, но не как основную базу проекта.

```yaml
page:
  url: "/"
  primary_intent: ""
  notes: ""
  forbidden_intents: []

sections:
  hero:
    selector: ""
    meaning: ""
    primary_keywords: []
    secondary_keywords: []
    max_lines_hint: 0
```

### 7.4. `keywords.yml`

```yaml
keywords:
  - phrase: ""
    frequency: 0
    frequency_type: "unknown"
    intent: ""
    section: ""
    status: "review"
    exact_limit: 1
    notes: ""
```

### 7.5. Отчёты

```text
reports/
  2026-05-01-audit.md
  2026-05-01-keywords.json
  2026-05-01-ru-text.md
  2026-05-01-media-seo.md
```

### 7.6. `media-map.yml`

```yaml
media:
  - id: "hero-image"
    type: "image"
    file: "images/hero.webp"
    section: "hero"
    decorative: false
    current_alt: ""
    proposed_alt: ""
    related_keywords: []
    status: "review"
    notes: ""

  - id: "product-video"
    type: "video"
    file: "video/product.mp4"
    poster: "images/product-poster.webp"
    section: "architecture"
    current_context: ""
    proposed_description: ""
    transcript_status: "not_needed"
    related_keywords: []
    status: "review"
```

## 8. Проверки

### 8.1. SEO-структура

- `title` есть и не пустой;
- `description` есть и не пустой;
- один главный `h1`;
- нет хаотичных заголовков;
- секции имеют понятную иерархию;
- основной смысл страницы совпадает с `title/h1`.

### 8.2. Ключи

- основной ключ есть в важной зоне;
- ключи не повторяются слишком часто;
- точные вхождения не стоят рядом;
- нет концентрации одного ключа в одном блоке;
- поддерживающие ключи распределены логично;
- ключи не конфликтуют со смыслом секции.

Чистка мусора и проверка переспама делаются локальными инструментами приложения, а не внешним SEO-сервисом.

Чистка ключей:

```text
keywordService
  -> нормализует запросы
  -> убирает дубли
  -> применяет project blacklist
  -> помечает мусорные интенты
  -> просит Codex классифицировать спорные запросы
  -> отдаёт результат на ручное утверждение
```

Важно: `keywordService` не удаляет слова из текста как stopword-инструмент. Его задача — фильтровать Wordstat-ключи на релевантность проекту: что использовать, что отложить, что выкинуть.

Проверка переспама:

```text
checkOverseo
  -> считает точные вхождения
  -> считает soft_forms из keywords.yml
  -> считает классическую/академическую тошноту локально
  -> проверяет плотность по секциям
  -> ищет повторы рядом
  -> ищет повторяющиеся биграммы/триграммы
  -> проверяет title/description/h1/h2
  -> проверяет alt на keyword stuffing
```

Text.ru используем только как референс по смыслу показателей: заспамленность, водность, ключи, группы ключей, смешанные слова. Их API не подключаем.

Подробная спецификация `checkOverseo` вынесена в `CHECK_OVERSEO_SPEC.md`.

### 8.3. Конкурирующие смыслы

Приложение должно предупреждать, если страница одновременно пытается быть:

- лендингом продукта;
- статьёй про технологию;
- страницей услуги;
- отраслевым каталогом;
- обучающим материалом.

Не все смыслы запрещены, но должен быть один главный.

### 8.4. Длина под дизайн

Для каждого текстового блока можно хранить:

- текущую длину;
- примерное количество строк;
- максимальный лимит;
- предупреждение, если SEO-правка длиннее исходника.

Особенно важно для лендингов с плотной визуальной композицией.

### 8.5. Редактор SEO-правок и фильтр качества

`ru-text` используется после SEO-правок:

- типографика;
- канцелярит;
- стилистические ошибки;
- слабые формулировки;
- business writing;
- UX writing.

Цель — не заменить редактора, а отредактировать и отфильтровать последствия SEO-правок: канцелярит, мутный business tone, слабые формулировки, плохую читаемость и типографические ошибки. SEO-решения принимает не `ru-text` отдельно, а общий контур: карта ключей, анти-переспам, смысловая проверка, редакторская проверка и пользовательское утверждение.

### 8.6. Media SEO

- у смысловых изображений есть нормальный `alt`;
- имя файла осмысленное и не выглядит как keyword stuffing;
- декоративные изображения не получают SEO-текст в `alt`;
- одинаковые alt не размножаются на разные изображения без причины;
- alt описывает изображение, а не просто повторяет ключ;
- для видео есть понятный контекст, подпись, описание или транскрипт, если это нужно;
- poster видео не остаётся без контекста;
- ключи в media-описаниях не конфликтуют с содержанием изображения/видео;
- если модель не уверена, что на медиа, объект получает статус `needs-human`.

## 9. Инструменты и ссылки

### Основные

- Codex non-interactive / `codex exec`: https://developers.openai.com/codex/noninteractive
- Codex через ChatGPT-план: https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan
- Раздельный биллинг ChatGPT и API: https://help.openai.com/en/articles/9039756
- Vite: https://vite.dev/guide/
- React: https://react.dev/
- ru-text: https://github.com/talkstream/ru-text
- MCP-KV Wordstat setup: https://mcp-kv.ru/docs/wordstat-mcp-setup
- MCP-KV SEO tools, справочно/опционально: https://mcp-kv.ru/mcp-server-seo
- Cheerio для HTML-парсинга: https://cheerio.js.org/docs/api/
- image-size для размеров изображений: https://github.com/image-size/image-size
- Sharp для обработки/превью изображений: https://www.npmjs.com/package/sharp
- FFmpeg для извлечения кадров из видео: https://ffmpeg.org/ffmpeg-doc.html
- Text.ru SEO-анализ как референс: https://text.ru/seo
- Text.ru API/check description, только как источник описания модели анализа: https://text.ru/api-check

### Платные/внешние аналоги для ориентира

- Rush Analytics: https://www.rush-analytics.ru/
- Rush Analytics Text Analyzer: https://www.rush-analytics.ru/land/tekstovyy-analizator
- Rush Analytics text analyzer guide: https://www.rush-analytics.ru/faq/rukovodstvo-po-tekstovomu-analizatoru
- Тургенев: https://turgenev.ashmanov.com/
- Text.ru SEO-анализ: https://text.ru/seo
- Text.ru FAQ по SEO-анализу: https://text.ru/faq/instrukcii/seo-analiz-teksta/
- NeuronWriter: https://neuronwriter.com/

Эти сервисы не копируются один в один. Они используются как ориентир по функциям:

- текстовый анализ;
- рекомендации по ключам;
- заспамленность;
- структура текста;
- зоны документа;
- редакторская проверка;
- отчёты для копирайтера.

## 10. Безопасность и ограничения

- Приложение локальное по умолчанию.
- Нельзя автоматически публиковать изменения.
- Нельзя молча менять исходные файлы без подтверждения.
- Пути к проектам должны быть явно разрешены пользователем.
- Wordstat/API/MCP ключи хранить локально и не коммитить.
- Отчёты можно сохранять, но секреты из `.env` не включать.
- Для будущего remote-режима нужна отдельная модель прав доступа.
- Repeated scan должен создавать новый `scan_version`, а не перетирать старые решения.
- Approval/draft/keyword/media-решения должны ссылаться на стабильные `page_id/section_id/media_id`, а не только на текущий DOM selector.

## 11. MVP-порядок реализации

1. Инициализировать React + Vite UI.
2. Добавить локальный backend, Postgres и object storage.
3. Сделать Project Dashboard: создание проекта, `targetProjectPath`, история.
4. Сделать `projectScanService` и `projectIndex`.
5. Сделать baseline audit по найденному проекту.
6. Сделать Page Workspace: `originalText` и `workingText`.
7. Сделать `CodexExecProvider`.
8. Добавить задачу Meaning Extraction: смыслы секций + seed-запросы.
9. Сделать экран Seeds и ручное утверждение seed-запросов.
10. Подготовить интеграцию Wordstat MCP.
11. Сделать Wordstat table с ВЧ/СЧ/НЧ и raw-сохранением в object storage.
12. Сделать `keywordService`: фильтрация мусора, классификация, user approval.
13. Сделать `keywordMapService`: предложить карту ключей по страницам/секциям.
14. Сделать Optimization Plan.
15. Сделать Rewrite Workspace с вариантами правок.
16. Добавить media SEO-аудит: изображения, видео, alt, poster, подписи, имена файлов.
17. Добавить `checkOverseo`.
18. Подключить `ru-text`.
19. Добавить Final Validation, diff, changeset, dry-run, backup и ручное `Apply`.
20. Добавить Export и Reports/History.

## 12. Критерии успеха MVP

MVP считается полезным, если пользователь может:

- создать локальный SEO-проект;
- указать папку target project, а не собирать файлы руками;
- получить scan проекта и baseline audit;
- выбрать страницу/секцию из найденной карты;
- увидеть `originalText` и работать с `workingText`;
- получить seed-запросы из существующего текста;
- сходить по ним в Wordstat;
- получить таблицу ключей с ВЧ/СЧ/НЧ;
- отфильтровать мусорные ключи с помощью правил, Codex-классификации и ручного утверждения;
- получить предложенную карту ключей и утвердить её;
- увидеть, где есть SEO-проблемы;
- получить варианты правки секции;
- проверить правку на переспам и качество;
- увидеть проблемы с alt-текстами, видео и медиа-описаниями;
- получить предложения alt/подписей без SEO-переспама;
- применить изменения только после diff и ручного подтверждения;
- выгрузить архив проекта и отчёты;
- вернуться к проекту позже через историю;
- принять решение без ручного хаоса в таблицах и вкладках.

## 13. Главный принцип продукта

SEO Farm не должна заменять редактора.

Она должна убрать рутину:

- сбор;
- сверка;
- подсчёты;
- повторы;
- отчёты;
- контроль структуры;
- предварительные варианты правок.

Финальное решение остаётся за человеком.

```text
Wordstat даёт спрос.
Codex помогает думать и переписывать.
SEO-check не даёт переблевать ключами.
ru-text редактирует и фильтрует качество SEO-правок.
Media SEO не даёт забыть alt, poster, видео-контекст и подписи.
Пользователь утверждает смысл.
```

## 14. Документы для разработки

- `USER_FLOW.md` — пользовательский путь от создания проекта до apply/export.
- `SEO_FARM_ARCHITECTURE.md` — схема приложения, модулей, storage и инструментов.
- `CHECK_OVERSEO_SPEC.md` — спецификация локального анти-переспам инструмента.
- `IMPLEMENTATION_GUARDRAILS.md` — порядок backend pipeline, границы инструментов и риски разработки.
- `UI_UX_SPEC.md` — обязательные UI/UX-экраны, компоненты, состояния и safety-паттерны.
- `TASK_MANAGER.md` — поэтапный план реализации с подзадачами и критериями готовности.
