Docs: чистка репозитория и профессиональный README / documentation

[ZhuchkaTriplesix]

Контекст

Репозиторий вырос за время разработки theme system (#37), QueryaDropdown (#87–#90), драйверов БД и CI. Часть артефактов — spike-отчёты, черновики roadmap, дублирующиеся инструкции — устарела или не соответствует уровню production open-source продукта.

Цель: привести репозиторий к профессиональному виду для контрибьюторов, пользователей и релизов — без потери технически ценной истории.

Цель

1. Аудит и чистка — убрать или архивировать лишнее, оставить только то, что нужно для сборки, разработки и поддержки.
2. Документация premium-уровня — README как витрина проекта, структурированный docs/, единый tone of voice, актуальные ссылки и скриншоты (по возможности).

Часть A — Аудит и чистка репозитория

A1. Инвентаризация (обязательный первый шаг)

Составить таблицу «файл / директория → keep | archive | delete → обоснование»:

Кандидаты на ревью	Тип
docs/research_theme.md	research / draft
docs/editor-spike-report.md	spike
docs/code-forge-evaluation.md	evaluation
docs/mysql-implementation-plan.md	implementation plan (возможно выполнен)
docs/perf-baseline.md	internal baseline
docs/roadmap.md	living doc (нужна актуализация, не удаление)
.cursor/rules/	agent-only (оставить, не дублировать в user docs)
themes/samples/	sample assets
Tracked generated / env-specific файлы	e.g. .flutter-plugins-dependencies

Не трогать без явного решения:

• third_party/ (vendored shadcn_flutter)
• test/, CI workflows, release scripts
• CHANGELOG.md, LICENSE

A2. Правила чистки

• Удалять только после проверки ссылок (grep по repo + GitHub issues/PR)
• Ценные черновики → docs/archive/ с одной строкой в README docs index («исторические материалы»)
• Дубли инструкций объединять (например Flutter pin: README ↔ CONTRIBUTING ↔ CI)
• .gitignore / .gitattributes: не коммитить локальные артефакты, если они случайно tracked

A3. Структура docs/ (целевая)

docs/
├── README.md              # индекс документации (новый)
├── getting-started.md     # установка, первый запуск (можно вынести из README)
├── user-guide.md          # актуализировать
├── architecture.md        # lib/, features/, core/ — для контрибьюторов (новый)
├── security.md
├── theme.md + theme-import.md
├── contributing/          # или ссылка на CONTRIBUTING.md + расширения
├── release/               # tags-and-releases, release-checklist, macos-signing
├── roadmap.md
└── archive/               # spike/evaluation/research (опционально)

Часть B — README и tone of voice

B1. README.md (главная витрина)

Структура в professional OSS стиле:

1. Hero — одно предложение + badges (CI, license, Flutter stable pin, platforms)
2. Screenshots / demo — placeholder или реальные (dark UI, connections, SQL workspace)
3. Features — bullet list по драйверам и ключевым возможностям (theme, secure storage, export)
4. Quick start — 3 команды до flutter run
5. Documentation — таблица ссылок на docs/
6. Development — flutter test, flutter analyze, ссылка на CONTRIBUTING
7. Project structure — краткая таблица lib/
8. License & third_party

Требования к prose:

• English (primary для GitHub audience) или RU+EN split — зафиксировать один язык в issue при старте работы
• Без marketing fluff; короткие предложения; working links only
• Версия / релиз: ссылка на latest tag и CHANGELOG

B2. CONTRIBUTING.md

• Расширить: GitFlow (issue/* → PR → dev), labels, CI expectations
• Ссылка на docs/architecture.md и .cursor/rules/gitflow.md (для агентов — без дублирования всего текста)
• Pre-PR checklist (analyze, test, scope)

B3. docs/README.md (индекс)

Единая точ входа: «User / Developer / Release / Theme / Archive» с описанием каждого файла в 1 строку.

B4. Согласованность

• Все cross-links проверены (нет битых путей после move/delete)
• Roadmap синхронизирован с закрытыми issues ([Epic] Система тем и стилей Querya Desktop #37, UI: унификация выпадающих списков на MenuAnchor (QueryaDropdown) #87, UI: дизайн-система для QueryaDropdown (триггер, меню, hover, selected) #89…)
• User guide отражает текущий UI (MenuAnchor dropdowns, Interface scale, Preferences)

Acceptance criteria

• Таблица аудита в PR description или docs/archive/AUDIT.md
• README соответствует структуре B1; проходит review «можно показать инвестору/на GitHub trending»
• docs/README.md — навигация по всей документации
• Нет dead links в markdown (можно скрипт markdown-link-check или ручной grep)
• CONTRIBUTING + CI pin Flutter согласованы
• flutter test / CI без изменений поведения приложения (docs-only PR допустим; cleanup — отдельные коммиты)
• Issue/PR не удаляет third_party/ и не трогает секреты

Вне scope

• Переписывание third_party/shadcn_flutter docs
• Маркeting-сайт / landing вне repo
• Полная i18n документации (RU+EN) — отдельный issue, если нужно

Предлагаемая декомпозиция PR

1. PR 1: audit table + .gitignore / archive moves
2. PR 2: README + docs/README + getting-started
3. PR 3: architecture.md + CONTRIBUTING + roadmap sync

Референсы (текущее состояние)

• README.md — базовый, но без badges/screenshots/architecture
• CONTRIBUTING.md — минимальный
• docs/roadmap.md — draft, частично outdated
• Spike/eval: docs/editor-spike-report.md, docs/code-forge-evaluation.md, docs/research_theme.md