docs: update README, PLAN, TODO, MENTOR_CONTEXT with full implemented functionality and architecture

2026-10-07 15:20:44 +03:00
parent c89b0d6238
commit 03c692fe43
6 changed files with 351 additions and 240 deletions
@@ -19,6 +19,7 @@ data/audio_cache/
 data/*.db
 data/*.db-wal
 data/*.db-shm
 data/*.backup*
 # Environment & Secret variables
 .env
@@ -1,11 +1,13 @@
-# Workspace Context & English Mentor Rules
+# Workspace Context & English Mentor Rules: study.qpid.pro
 > This file is automatically discovered by the Antigravity agent in this workspace.
 ## English Mentor & Tech Pair Programmer Role
- The assistant acts as a dedicated **English Language Mentor** and **Senior Software Engineer** working on `notes.qpid.pro`.
+- The assistant acts as a dedicated **English Language Mentor** and **Senior Software Engineer** working on `study.qpid.pro`.
- Full mentor instructions, pedagogical framework, and project session context are maintained in [MENTOR_CONTEXT.md](file:///home/kopri/notes.qpid.pro/MENTOR_CONTEXT.md), [PEDAGOGY.md](file:///home/kopri/notes.qpid.pro/PEDAGOGY.md), and [PLAN.md](file:///home/kopri/notes.qpid.pro/PLAN.md).
+- Full mentor instructions, pedagogical framework, and project session context are maintained in [MENTOR_CONTEXT.md](MENTOR_CONTEXT.md), [PEDAGOGY.md](PEDAGOGY.md), [PLAN.md](PLAN.md), and [README.md](README.md).
 - When discussing vocabulary or practicing English:
  - Focus on the **Lexical Approach** (chunks, collocations, idiomatic usage).
  - Provide IPA transcriptions, pronunciation tips, and realistic contextual examples.
  - Give constructive, encouraging feedback and natural phrasing improvements.
 - When working on codebase:
  - Follow the **Ponytail principles**: minimal code, standard library & native platform features first, 100% test passing (`pytest tests/test_api.py`), offline-first resilience.
@@ -1,15 +1,15 @@
-# 🎓 Mentor Context & Session State: English & notes.qpid.pro
+# 🎓 Mentor Context & Session State: English & study.qpid.pro
 > **Файл контекста сессии и роли ментора по английскому языку**  
-> Ссылка на проект: [notes.qpid.pro](https://notes.qpid.pro)  
+> Ссылка на проект: [study.qpid.pro](https://study.qpid.pro)  
-> Директория проекта: `/home/kopri/notes.qpid.pro`  
+> Директория проекта: `/home/ai-projects/services/study.qpid.pro`  
 > Назначение файла: хранение роли ментора, педагогических принципов, архитектурного контекста и прогресса студента.
 ---
 ## 🧑‍🏫 Роль: Твой персональный ментор по английскому языку
-Ты выступаешь в роли **опытного, поддерживающего и практико-ориентированного ментора по английскому языку** с сильным фокусом на IT/Tech и живую разговорную речь.
+Ты выступаешь в роли **опытного, поддерживающего и практико-ориентированного ментора по английскому языку** с сильным фокусом на IT/Tech, живую разговорную речь и методику *Comprehensible Input*.
 ### Ключевые функции ментора:
 1. **Разбор лексики и устойчивых выражений (The Lexical Approach)**:
@@ -22,31 +22,32 @@
 4. **Тактичная коррекция ошибок (Constructive Feedback)**:
   - Если пользователь пишет на английском с ошибкой, мягко показать естественный вариант (natural phrasing) и объяснить причину.
 5. **Интерактивные тренировки**:
-   - Генерировать карточки, упражнения с пропусками (Cloze deletions), квизы на идиомы и фразовые глаголы для добавления в сервис `notes.qpid.pro`.
+   - Генерировать карточки, упражнения с пропусками (Cloze deletions), квизы на идиомы и фразовые глаголы для добавления в сервис `study.qpid.pro`.
 ---
-## 📱 О проекте `notes.qpid.pro`
+## 📱 О проекте `study.qpid.pro`
- **Что это**: Защищённый персональный тренажёр и словарь английского языка (PWA / Web-сервис).
+- **Что это**: Защищённый персональный тренажёр, читалка и словарь английского языка (PWA / Docker / Web-сервис).
- **Сайт**: [https://notes.qpid.pro](https://notes.qpid.pro) (IP: `31.77.203.213`)
+- **Сайт**: [https://study.qpid.pro](https://study.qpid.pro)
 - **Репозиторий**: [ai.qpid.pro/gitea/Antigravity/notes-qpid-pro](https://ai.qpid.pro/gitea/Antigravity/notes-qpid-pro)
 - **Техстек**:
-  - Backend: Python 3.12 (FastAPI, Uvicorn, SQLite WAL)
+  - Backend: Python 3.12 (FastAPI, Uvicorn, SQLite WAL, 11 модульных APIRouters)
-  - Frontend: Vanilla JS / Modern CSS / HTML5 PWA (без тяжёлых фреймворков)
+  - Frontend: Vanilla JS / Modern CSS (7 предметных таблиц) / HTML5 PWA (Service Worker v6.7)
-  - Сервер: Nginx Reverse Proxy + SSL Let's Encrypt + Systemd
+  - Сервер: Docker, Nginx Reverse Proxy, SSL Let's Encrypt
-  - Безопасность: PBKDF2 пароли, HttpOnly Cookies, CSRF/Rate Limiter
+  - Локальный ИИ: Ollama + Qwen 2.5 3B (контекстный перевод предложений, педагогический дебрифинг уроков)
-  - Интеграции: Free Dictionary API (IPA + audio), MyMemory API
+  - Озвучка: Piper Neural TTS (чистый нативный голос VITS без внешних API)
  - Тестирование: 44/44 проходящих интеграционных теста в Pytest.
 ---
 ## 🧠 5 Золотых педагогических принципов проекта
 1. **Лексические блоки (Chunks)**: Учить готовые связки, а не отдельные слова.
-2. **Контекстный якорь**: Каждое слово сохраняется в предложении из реальной ситуации.
+2. **Контекстный якорь**: Каждое слово сохраняется в предложении из реальной ситуации (книга, статья, фильм).
-3. **Фонетический якорь (IPA + Audio)**: Закрепление звучания на слух, исключение субвокализации с ошибками.
+3. **Фонетический якорь (IPA + Neural Audio)**: Закрепление звучания на слух, исключение субвокализации с ошибками.
-4. **Интервальные повторения (SRS / SM-2)**: Повторение по кривой забывания Эббингауза (1, 2, 5, 12, 28, 65 дней).
+4. **Интервальные повторения (SRS / SM-2)**: Повторение по кривой забывания Эббингауза (1, 6, $I \times EF$ дней) с интерливингом (Smart Daily Mix).
-5. **Активное припоминание (Active Recall)**: Двусторонние карточки + упражнения с пропусками.
+5. **Активное припоминание (Active Recall)**: Двусторонние 3D-карточки, умный квиз, активный набор текста руками и упражнения Cloze Tap.
 ---
@@ -55,7 +56,7 @@
 Когда ты начинаешь новый диалог или хочешь активировать этот режим, просто напиши:
 - `Вспомни контекст ментора MENTOR_CONTEXT.md` или `Работай по MENTOR_CONTEXT.md`
 - `Проверь мое предложение на английском: "..."`
- `Разбери слово/идиому "..." (транскрипция, примеры, связки, карточка для notes.qpid.pro)`
+- `Разбери слово/идиому "..." (транскрипция, примеры, связки, карточка для study.qpid.pro)`
 - `Дай 5 полезных phrasal verbs для IT/dev на сегодня`
 - `Давай попрактикуем диалог на английском на тему ...`
@@ -66,32 +67,7 @@
 | Дата | Тема / Фокус | Ключевые концепции | Статус |
 | :--- | :--- | :--- | :--- |
 | *Инициализация* | Запуск проекта notes.qpid.pro & MVP | SRS, Lexical approach, Contextual anchoring | Выполнено |
-| `2026-09-23` | Стратегия начитки тех. текстов (Extensive Reading) & Умные тесты | Чтение без упора на грамматику (85-90% Comprehensible input), выжимка связок (chunks), умный микс в тестах (Новые + Повтор + Проблемные/Leeches), активный ввод Ru->En | Зафиксировано, переход к чтению |
+| `2026-09-23` | Стратегия начитки тех. текстов (Extensive Reading) & Умные тесты | Чтение без упора на грамматику (85-90% Comprehensible input), выжимка связок (chunks), умный микс в тестах (Новые + Повтор + Leeches), активный ввод Ru->En | Выполнено |
-
+| `2026-10-06` | Интеграция читалки (EPUB/PDF/RFC/Wikipedia) & Piper TTS | Офлайн-читалка, IETF RFC стандарты, Wikipedia статьи, локальная нейро-озвучка Piper | Выполнено |
---
+| `2026-10-07` | Murphy Grammar, CEFR Cloze Tap & Комплексный урок | 15 юнитов Мерфи, тесты A1–B2, gap-ингестия, конструктор уроков, сессионный раннер, ИИ-дебрифинг Qwen 2.5 3B | Выполнено |
-
+| `2026-10-07` | Полный рефакторинг архитектуры (5 этапов) | Модуляризация бэкенда (11 роутеров), вынос датасетов в JSON (-3100 строк), модульные CSS, Keep-Alive пул Ollama | Выкачено на прод study.qpid.pro |
 ## 🎯 Сформулированные требования к умному тренажеру (Smart Daily Quiz)
 1. **Сбалансированная сессия на день (Smart Mix)**:
   - ~10 новых добавленных слов (New)
   - ~10 слов по интервальной очереди (Review / Due SRS)
   - ~5 проблемных слов (Leeches / High-error rate)
   - Случайное перемешивание (shuffled) в одной тренировке.
 2. **Проблемные слова (Leech Detection)**:
   - Автоматическая маркировка карточек с частыми ошибками и повышение частоты их появления.
 3. **Режим активного ввода (Active Typing / Production)**:
   - Показ русского значения / контекста с пропуском $\rightarrow$ набор правильного английского слова руками для моторной памяти и спеллинга.
 4. **Контроль дубликатов при пополнении словаря (Duplicate Prevention & Merging)**:
   - При добавлении слова/фразы проверять наличие в словаре.
   - Вместо создания дубликата предлагать дополнить существующую карточку новым примером контекста/значением или отредактировать её.
 5. **Строгая оценка уровня владения (Active CEFR Vocabulary Weighting)** *(В планах)*:
   - Считать уровень не по общему числу карточек, а по реальному активному объёму: слова в статусах `Mastered` (интервал > 21 дня) и `Review` с весовыми коэффициентами.
   - Учитывать Retention Rate % как множитель уверенности.
   - Показывать индикатор прогресса (сколько слов осталось выучить до следующего уровня).
 6. **Интерактивная читалка и авто-тегирование источников (Reader & Source-scoped Learning)** *(В планах)*:
   - Автоматическое присвоение тегов при сохранении из читалки: `#название-книги`, `#жанр`, `#автор`.
   - Запуск любых SRS-тренировок и квизов с фильтром по тегу источника (например, повторить только слова из *Fight Club* или *Clean Code*).
   - Подсветка в тексте книги уже изучаемых и выученных слов, перевод фраз/chunks при выделении.
@@ -1,175 +1,111 @@
-# План развития проекта Notes (notes.qpid.pro)
+# План развития и архитектурная дорожная карта: Study Qpid (study.qpid.pro)
-> **Принцип проектирования**: *«Работает как автомат Калашникова»* — сверхнадёжно, мгновенно, защищено для публичного интернета, без раздутых зависимостей и постоянного ручного обслуживания.
+> **Принцип проектирования**: *«Работает как автомат Калашникова»* — сверхнадёжно, мгновенно, полностью автономно, защищено для публичного интернета, без раздутых зависимостей и без привязки к платным внешним API.
 ---
-## 1. Архитектура и защита системы
+## 1. Архитектура системы
-Сервис разворачивается на публичном сервере с белым IP (`31.77.203.213`). Вся система проектируется с учётом сетевой безопасности и изоляции личных данных.
+Сервис разворачивается в Docker-окружении на защищённом сервере за Nginx с SSL Let's Encrypt (`study.qpid.pro`).
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                       notes.qpid.pro                        │
+│                       study.qpid.pro                        │
 │            Nginx (HTTPS / Let's Encrypt / Security Headers) │
 └──────────────────────────────┬──────────────────────────────┘
-                               │ proxy_pass :8002
+                               │ proxy_pass 127.0.0.1:8002
 ┌──────────────────────────────▼──────────────────────────────┐
-│                    Слой безопасности (Auth)                 │
+│             Docker Container: study-qpid-pro                │
-│  • Аутентификация: сессионные токены (HTTP-only cookies)    │
+│                                                             │
-│  • Хэширование паролей: PBKDF2-HMAC-SHA256 (соль + 100k)   │
+│  • FastAPI Lifespan & Security Middlewares (GZip, Headers)  │
-│  • Защита от перебора (Rate Limiter: макс 5 попыток/мин)    │
+│  • Модульные APIRouters (auth, cards, srs, reader, etc.)    │
-│  • Закрытый доступ: все эндпоинты требуют авторизации       │
+│  • SQLite WAL + mmap I/O (транзакции, 0.01ms чтение)        │
 │  • Локальный Piper Neural TTS (чистый нативный голос VITS)  │
 │  • Вынесенные JSON-датасеты (data/seeds/)                   │
 │  • Модульные CSS-стили (7 предметных таблиц + PWA SW v6.7)  │
 └──────────────────────────────┬──────────────────────────────┘
-                               │
+                               │ http://ollama:11434 (Keep-Alive 120s)
 ┌──────────────────────────────▼──────────────────────────────┐
-│                    Backend: Python 3.12                     │
+│              Docker Container: study-ollama                 │
-│    FastAPI / Uvicorn + SQLite (WAL mode) + Dictionary APIs  │
+│  • Qwen 2.5 3B Instruct (контекстный перевод предложений    │
-└──────────────────────────────┬──────────────────────────────┘
+│    и педагогический дебрифинг уроков)                       │
-                               │
+└─────────────────────────────────────────────────────────────┘
       ┌───────────────────────┴───────────────────────┐
       ▼                                               ▼
 ┌─────────────────────────────┐         ┌─────────────────────────────┐
 │     Внешние открытые API    │         │      Локальная БД SQLite    │
 │ • Free Dictionary API       │         │ • users (аккаунт, пароль)   │
 │   (IPA, audio, definitions) │         │ • vocabulary_cards          │
 │ • MyMemory / Translation    │         │ • sessions (активные входы) │
 │   (русский перевод фразы)   │         │ • tags & categories         │
 └─────────────────────────────┘         └─────────────────────────────┘
 ```
-### Выбор технологий:
+---
- **Безопасность**: Защищённые сессии (Signed HTTP-only cookie `SameSite=Lax`, `Secure`). Защита от CSRF, XSS и брутфорс-атак через встроенный rate limiter.
+
- **Backend**: Python 3.12 + FastAPI (асинхронный, легковесный, моментальный старт).
+## 2. Реализованные этапы развития (Completed Roadmap)
- **База данных**: SQLite в режиме `WAL` (Write-Ahead Logging). Идеальная транзакционная надежность, автономность, бэкап в один файл.
+
- **Frontend**: Чистый Vanilla ES6+ / Modern CSS / HTML5. Мгновенная загрузка (< 50 мс), оффлайн-кэш, адаптивность (смартфон + десктоп), поддержка хоткеев.
+### ✅ Этап 1: Защищённое ядро (MVP) и базовый словарь
- **Внешние API (Zero-cost & Open)**:
+- [x] Авторизация на сессионных куках (`HttpOnly`, `SameSite=Lax`, `Secure`).
-  1. *Free Dictionary API* (`api.dictionaryapi.dev`): фонетическая транскрипция IPA, аудио-произношение нативных дикторов (US/UK), части речи, толкования и примеры.
+- [x] Хэширование паролей `PBKDF2-HMAC-SHA256` с уникальной солью на пользователя.
-  2. *MyMemory Translation API*: литературный перевод фраз, идиом и предложений на русский язык.
+- [x] Rate limiting для предотвращения атак перебором.
 - [x] Офлайн-словарь (140k+ записей) с каскадным переводом.
 - [x] Сохранение слов с контекстным предложением и горячими клавишами (`Ctrl+Enter`).
 - [x] Журнал личного словаря, поиск, фильтрация по тегам и коллекциям.
 ### ✅ Этап 2: Организация, экспорт и PWA
 - [x] Коллекции и теги, разбивка слов по категориям.
 - [x] Пакетные операции над карточками (массовое перемещение, удаление, добавление тегов).
 - [x] Экспорт данных в форматы: CSV, JSON, Anki TSV и Markdown.
 - [x] PWA-манифест и Service Worker для офлайн-доступа к приложению.
 ### ✅ Этап 3: Алгоритм интервальных повторений (SRS SM-2) и тренажер
 - [x] Реализация математической модели SuperMemo SM-2 (Ease Factor, Repetitions, Intervals).
 - [x] 3D-флип карточки с градацией оценок (Снова, Трудно, Хорошо, Легко).
 - [x] Режим Smart Quiz (выбор из 4 вариантов с дистракторами из той же части речи).
 - [x] Режим активного ввода (Active Typing) с набором английского слова по русскому переводу.
 - [x] Smart Daily Mix: сбалансированная подборка (10 новых + 10 повторов + 5 проблемных слов).
 - [x] Детекция проблемных слов (Leeches) и повторный фокус на них.
 - [x] Аналитика: календарь активности (Heatmap 180 дней), стрик дней, процент удержания (Retention Rate), оценка уровня CEFR.
 ### ✅ Этап 4: Интерактивная читалка и книжная полка
 - [x] Поддержка книг и документов: EPUB, PDF, TXT, Markdown (`.md`).
 - [x] Автоматический сборщик стандартов IETF RFC по номеру или URL.
 - [x] Интеграция с Wikipedia: автономная загрузка статей с очисткой верстки под тайм-бюджет.
 - [x] Интерактивный клик-перевод каждого слова с выводом контекста.
 - [x] Добавление слова и цитаты в словарь в 1 клик прямо из текста.
 - [x] Непрерывное чтение (continuous scroll) с карточками перехода между главами.
 - [x] Темы оформления (Light, Dark, Sepia, Night, Parchment, Hacker) и типографика.
 ### ✅ Этап 5: Автономный локальный ИИ (Ollama) и нейро-озвучка (Piper)
 - [x] Развертывание локального контейнера Ollama с моделью `qwen2.5:3b`.
 - [x] Контекстный перевод предложений с учетом целевого слова и сохранением в кэш SQLite.
 - [x] Локальный VITS-синтез речи Piper TTS (US Lessac, RU Dmitri) с нулевой задержкой.
 - [x] Фоновое пред-кэширование произношения слов и предложений при добавлении в словарь.
 - [x] Тренажёр аудирования (Listening) с проверкой понимания.
 ### ✅ Этап 6: Грамматика Murphy & Тестирование CEFR
 - [x] 260 интерактивных заданий Cloze Tap по международным уровням A1–B2.
 - [x] Автоматическая gap-ингестия: отправка ошибочных слов из тестов в активный тренажёр SRS.
 - [x] Фоновый воркер майнинга тестов из загруженной литературы.
 - [x] 15 базовых юнитов грамматики Murphy с формулами и теорией.
 - [x] Синхронизация с рукописным бумажным конспектом.
 ### ✅ Этап 7: Конструктор комплексного урока & Сессионный раннер
 - [x] Единый конструктор ежедневного урока: блоки слов (Flashcards/Quiz/Typing/Dictation), грамматики, аудирования, чтения.
 - [x] Встроенные готовые шаблоны (Экспресс, Сбалансированный, Глубокий, Аудио+Чтение).
 - [x] Адаптивный подбор темы грамматики («Самая слабая тема по ошибкам», «Предыдущая тема»).
 - [x] Сквозная телеметрия ошибок сессии и интеллектуальный ИИ-дебрифинг от Qwen 2.5 3B.
 - [x] Детерминированный фолбэк для мгновенного завершения сессии при выключенной Ollama.
 ### ✅ Этап 8: Глубокий технический рефакторинг и оптимизация (Beta-refactor)
 - [x] **Этап 1 рефакторинга**: Удаление мертвого кода (`parse_text`), оптимизация SQL в фоновых задачах.
 - [x] **Этап 2 рефакторинга**: Вынос 3 100+ строк захардкоженных датасетов в `data/seeds/*.json`.
 - [x] **Этап 3 рефакторинга**: Keep-Alive пул соединений для Ollama (120s), офлайн-лемматизация в словаре.
 - [x] **Этап 4 рефакторинга**: Модуляризация бэкенда (`app/main.py` сокращён с 2 240 до 142 строк, создано 11 APIRouters).
 - [x] **Этап 5 рефакторинга**: Модуляризация CSS (`style.css` 8 746 строк разделен на 7 предметных файлов, обновлён прекэш SW v6.7).
 - [x] 100% покрытие авто-тестами: 44/44 тестов проходят в Docker.
 ---
-## 2. Этапы реализации (Roadmap)
+## 3. Ближайшие планы и вектор развития (Future Enhancements)
 ### Этап 1 (Текущая итерация): Безопасное ядро (MVP) — Общий английский, перевод и фиксация
 *Цель: создать защищённый, сверхбыстрый и надёжный персональный словарь для повседневного и профессионального английского языка.*
 - [x] **1.1. Модуль защиты и авторизации**:
  - Страница авторизации (минималистичный дизайн, вход по логину и паролю).
  - Защита всех API эндпоинтов: неавторизованные запросы блокируются (`401 Unauthorized`).
  - Надежное хранение паролей в SQLite (`PBKDF2-HMAC-SHA256` с уникальной солью).
  - Rate Limiter на эндпоинт `/api/login` (не более 5 неудачных попыток в минуту с IP).
  - Сессии через зашифрованные `HttpOnly` cookie.
  - Кнопка «Выйти из аккаунта» в шапке сервиса.
 - [x] **1.2. Быстрый поиск и каскадный перевод (General & Idiomatic English)**:
  - Строка поиска в фокусе сразу при открытии страницы.
  - Поддержка любых форм языка:
    - Отдельные слова (существительные, глаголы, прилагательные);
    - Фразовые глаголы (*run into*, *figure out*, *call off*);
    - Идиомы и разговорные фразы (*once in a blue moon*, *take for granted*);
    - Предложения целиком (из книг, сериалов, документации).
  - Автоматическое получение:
    - Фонетической транскрипции (IPA);
    - Нативного аудио-произношения (US/UK);
    - Частей речи и толкования на английском;
    - Русского перевода.
  - Кэширование словарных запросов в локальной базе для мгновенных повторных ответов.
 - [x] **1.3. Контекстное сохранение слова в 1 клик**:
  - Горячие клавиши:
    - `Enter` — мгновенный перевод;
    - `Ctrl + Enter` (или `Cmd + Enter`) — мгновенное сохранение в словарь;
    - `Esc` — очистить ввод;
    - `Ctrl + P` или клик на динамик — прослушать произношение.
  - Возможность подправить перевод перед сохранением под свой контекст.
  - Поле для ввода контекстного предложения (где встретилось слово/выражение).
  - Выбор/ввод тегов (`#general`, `#phrasal-verb`, `#idiom`, `#daily`, `#networking`).
 - [x] **1.4. Журнал личного словаря (History & Words List)**:
  - Хронологическая лента всех сохраненных слов с датой и временем.
  - Живой поиск по английским словам, русскому переводу и контексту.
  - Фильтр по тегам в один клик.
  - Воспроизведение аудио прямо из списка.
  - Удаление / редактирование карточек.
 - [x] **1.5. Инфраструктурное развертывание**:
  - Конфигурация Nginx для `notes.qpid.pro` с proxy на бэкенд (`127.0.0.1:8002`).
  - Systemd-сервис для автозапуска и перезапуска при сбоях.
 ---
 ### Этап 2: Организация, теги, экспорт и PWA
 *Цель: гибкое управление растущим словарным запасом и удобство на мобильных.*
 - [x] **2.1. Расширенная организация и контроль качества**:
  - Коллекции и папки (например, «Разговорный», «Работа», «Книги/Сериалы», «Сети/IT»).
  - Быстрое массовое тегирование и групповые действия (удаление, перемещение).
  - **Контроль и предотвращение дубликатов (Duplicate Prevention & Merging)**:
    - Проверка при вводе и сохранении (case-insensitive trim).
    - Уведомление, если слово/фраза уже есть в словаре.
    - Возможность дописать новый контекстный пример / значение к существующей карточке вместо пложения дублей или перейти к её редактированию.
 - [x] **2.2. Экспорт данных**:
  - Экспорт базы в CSV (UTF-8 BOM), JSON, Markdown.
  - Экспорт в колоду Anki (`.tsv`) с аудио, контекстными предложениями и поддержкой Cloze deletion (`{{c1::word}}`).
 - [x] **2.3. PWA (Progressive Web App)**:
  - Установка на экран смартфона (iOS / Android) как нативное приложение.
  - Service Worker, Web Manifest, оффлайн-кэш статики.
 ---
 ### Этап 3: Встроенный тренажер интервальных повторений (SRS / SM-2)
 *Цель: перевод слов из пассивного словаря в активную долговременную память.*
 - [x] **3.1. Движок SuperMemo-2 (SM-2) & Умная выборка**:
  - Расчет интервалов забывания Эббингауза: `Again`, `Hard`, `Good`, `Easy`.
  - **Умный микс дня (Daily Quiz Mix)**: баланс сессии (до 10 новых + 10 интервальных повторений + 5 проблемных слов в разнобой).
  - **Детектор трудных слов (Leeches)**: автоматическая маркировка слов с частыми ошибками и их приоритетное подмешивание.
 - [x] **3.2. Режим Flashcards**:
  - Двусторонняя карточка En $\rightarrow$ Ru и Ru $\rightarrow$ EN с нативной озвучкой, подсказкой контекста и горячими клавишами `Space`, `1..4`.
 - [x] **3.3. Режим Multiple Choice Quiz (4 варианта ответа)**:
  - Выбор правильного перевода среди 4 вариантов со случайными дистракторами из базы.
  - Мгновенная проверка, подсветка цветом (зеленый/красный) и горячие клавиши `1..4`.
 - [x] **3.4. Режим активного набора (Active Typing / Ru $\rightarrow$ En)**:
  - Видишь русский перевод / контекст с пропуском $\rightarrow$ вводишь английское слово с клавиатуры (прокачка моторной памяти и спеллинга).
 - [x] **3.5. Режим Cloze Deletion (Контекстные пропуски)**:
  - Заполнение пропущенного слова прямо в живом предложении.
 - [x] **3.6. Аудио-тренажёр (Dictation)**:
  - Слушаем слово $\rightarrow$ печатаем правильный спеллинг.
 ---
 ### Этап 4: Интеллектуальный помощник и аналитика
 *Цель: отслеживание динамики и поддержка мотивации.*
 - [x] **4.1. Статистика, Daily Streak и Календарь активности**:
  - Сетка активности за 180 дней с градацией интенсивности (серый, салатовый, зеленый, изумрудный).
  - Учёт непрерывных дней занятий (Daily Streak 🔥) и рекорда серии.
  - Сегментированный прогресс-бар стадий освоения (Новые, В процессе, Закрепление, Выучено).
  - Оценка уровня владения языком (A1 - C1) по объёму активного словаря.
  - Процент точности запоминания (Retention Rate %).
 - [ ] **4.2. Быстрый захват из браузера**:
  - Букмарклет для выделения текста на любой странице и отправки в словарь.
 - [x] **4.3. Честный и строгий расчёт уровня CEFR (Active Vocabulary & Retention Weighting)**:
  - Расчёт уровня владения исключительно по **активным выученным словам** (стадии `Mastered` и `Review` в алгоритме SM-2), исключая пассивные добавленные карточки, которые ещё не прошли интервальные повторения.
  - Корректирующий коэффициент точности: учёт Retention Rate %, чтобы уровень отражал реальную память, а не просто количество выписанных слов.
  - Индикатор пути к следующему уровню (например: «*До уровня B2 осталось закрепить 142 слова*»).
 ---
 ### Этап 5: Интерактивная Читалка & Библиотека (Interactive Reader & Source-based Learning)
 *Цель: чтение живых книг, статей и документации с мгновенным клик-переводом и авто-тегированием источников.*
 - [x] **5.1. Хранилище текстов и парсер форматов (Bookshelf & Document Engine)**:
  - Поддержка форматов: вставка текста из буфера, `.txt`, `.md`, электронные книги `.epub` (с разбивкой по главам и сохранением позиции чтения).
  - Умная очистка веб-статей от лишней верстки и рекламы (Reader view).
 - [x] **5.2. Автоматическое тегирование источников (Source & Metadata Auto-tagging)**:
  - Каждое слово, сохранённое из книги/статьи, автоматически получает теги источника:
    - Название произведения (например, `#fight-club`, `#the-martian`, `#designing-data-intensive-apps`).
    - Тип/жанр материала (например, `#novel`, `#tech-article`, `#documentation`, `#cybersecurity`).
    - Автор / Источник (например, `#author:chuck-palahniuk`, `#cloudflare-blog`).
  - Автоматический захват предложения-контекста, в котором слово встретилось в книге.
 - [x] **5.3. Запуск тестов и тренировок по источникам и тегам (Tag-scoped SRS Quizzes)**:
  - Возможность запустить любую тренировку (Карточки, 4 варианта ответа, Набор слова, Диктант) **строго по словам конкретной книги, статьи или автора**.
  - Быстрый запуск из читалки: *«Повторить все 35 новых слов из Fight Club»* прямо во время или после прочтения главы.
 - [x] **5.4. Интерактивный клик-перевод и подсветка (Interactive Reader Layer)**:
  - Клик по любому слову $\rightarrow$ моментальный перевод, транскрипция, нативное аудио и кнопка «+ В словарь» в 1 клик.
  - Выделение фраз/связок (chunks) мышкой или тапом с литературным переводом всего выражения.
  - Подсветка в тексте книги уже выученных (`mastered`) и изучаемых (`learning`) слов.
 1. **Браузерный букмарклет для захвата слов**:
   - Минималистичный JS-скрипт для браузера, позволяющий по клику отправить выделенное слово и контекст страницы в личный словарь `study.qpid.pro`.
 2. **HTML5 Web Speech API fallback**:
   - Дополнительный запасной канал озвучивания через встроенный `window.speechSynthesis` при мобильном режиме без связи.
 3. **Расширение библиотеки Murphy**:
   - Постепенное расширение учебных юнитов грамматики с 15 до 30+ тем (Passive Voice, Reported Speech, Phrasal Verbs in Context).
 4. **Адаптивные интервалы по времени суток**:
   - Учёт утренних и вечерних окон повторения в сессионном раннере для максимальной концентрации.
@@ -1,46 +1,219 @@
-# Notes (notes.qpid.pro)
+# Study Qpid (study.qpid.pro)
-> **Защищённый персональный тренажёр и словарь английского языка.**  
+> **Автономный персональный тренажёр и интерактивная языковая среда английского языка.**  
-> Создан для быстрого и надёжного расширения словарного запаса (общий английский, фразовые глаголы, идиомы, профессиональные термины) без отвлечения от чтения и просмотра контента.
+> Создан для быстрого и надёжного расширения активного словарного запаса, автоматизации грамматики и беглого чтения технической и художественной литературы с поддержкой локального искусственного интеллекта (Ollama) и локального синтеза речи (Piper TTS) без внешних платных API.
 ---
-## 🎯 Концепция и методика
+## 🎯 Концепция и философия системы
 Чтение статей, книг или просмотр видео на английском часто тормозится незнакомыми словами и выражениями. Обычный переводчик даёт мгновенный ответ, но слово сразу забывается. Ручные списки превращаются в «кладбище информации».
-Проект решает эту проблему по принципу **«автомата Калашникова»**:
+Традиционное изучение языка разбивается о разрозненность: словарь в одном приложении, карточки в другом, книги в третьем, а грамматика в тетрадке.
-1. **Безопасность**: сервис работает на белом IP, защищён авторизацией (сессии, хэширование паролей, защита от брутфорса).
+
-2. **Мгновенный поиск и перевод**: фокус на строке ввода, каскадный перевод (словарная статья + толкование + русский перевод).
+**Study Qpid** объединяет весь цикл в единый закрытый контур по принципу **«автомата Калашникова»**:
-3. **Контекстный якорь**: сохранение слова вместе с живым предложением (где встретилось выражение).
+1. **100% автономность и приватность**: веб-сервис развернут в Docker, защищён строгой авторизацией (сессии HttpOnly, хэширование PBKDF2-HMAC-SHA256, rate limiting). Локальный ИИ (Qwen 2.5 3B) и синтез речи (Piper) работают полностью на собственном сервере без передачи данных сторонним компаниям.
-4. **Фонетическое закрепление**: нативное аудио-произношение (US/UK) и транскрипция IPA.
+2. **Контекстный якорь и лексический подход**: слова изучаются в готовых блоках (*chunks*) и живых предложениях из прочитанных книг и документации.
-5. **Интервальные повторения (SRS / SM-2)**: встроенные карточки для перевода слов в долговременную память.
+3. **Многомодальный интервальный тренажер (SRS SM-2)**: 5 различных режимов работы с карточками (3D Flashcards, умная викторина с дистракторами по частям речи, активный ввод Typing, аудио-диктант, аудирование Q&A).
 4. **Интерактивная читалка**: мгновенный перевод кликом по слову, захват предложений в карточки в 1 клик, поддержка форматов EPUB, PDF, TXT, Markdown, спецификаций IETF RFC и статей Wikipedia.
 5. **Грамматический трек Murphy & CEFR**: 15 базовых юнитов грамматики с формулами, связка с бумажной рабочей тетрадью, 260 интерактивных тестов Cloze Tap и автоматическая отправка ошибок в активную очередь повторений.
 6. **Конструктор комплексного урока**: единый сессионный раннер, собирающий ежедневный урок из слов, грамматики, аудирования, чтения и завершающийся педагогическим разбором ошибок от локальной нейросети.
 ---
-## 📂 Документация проекта
+## 🚀 Основной реализованный функционал
- 📚 [**Источники бесплатных книг (BOOKS_SOURCES.md)**](BOOKS_SOURCES.md) — проверенные каталоги адаптированных книг (A1–C1) и оригинальной классики в EPUB/TXT для читалки.
+### 1. 🔍 Контекстный словарь и поиск
- 📋 [**План функционала и архитектура (PLAN.md)**](PLAN.md) — детальный план итераций: от защищённого MVP до умных интервальных тренажёров.
+* **Локальная словарная база**: более 140 000 словарных статей в SQLite, дополненных морфологическим анализатором (лемматизация инфлексий `starts` → `start`, `studying` → `study`).
- 🎓 [**Методология и педагогика (PEDAGOGY.md)**](PEDAGOGY.md) — методические правила эффективного освоения языка: лексические связки (chunks), контекст, фонетика, кривая забывания Эббингауза.
+* **Детектор фразовых глаголов и идиом**: при поиске слова в контексте предложения система автоматически определяет устойчивые связки (*look forward to*, *run into*, *figure out*) и предлагает сохранить именно целостное выражение.
- ✅ [**Очередь задач и бэклог (TODO.md)**](TODO.md) — текущий статус реализации оптимизаций и фичей.
+* **Каскадный перевод**: офлайн-словарь + транскрипция IPA + толкование на английском + русский перевод.
 * **Управление базой**: разбивка по коллекциям (*General*, *IT/Tech*, *Phrasal Verbs* и др.), система тегов, быстрый поиск и фильтрация, пакетные операции (перемещение, тегирование, удаление).
 ### 2. 🧠 Локальный ИИ (Ollama & Qwen 2.5 3B)
 * **Контекстный перевод предложений**: перевод предложения с фокусом на точное значение целевого слова в данном контексте через локальную LLM (`qwen2.5:3b`).
 * **Кэширование переводов**: все сгенерированные переводы сохраняются в SQLite (`sentence_translations`) с моментальной отдачей при повторных запросах.
 * **Педагогический дебрифинг урока**: анализ ошибок сессии, определение паттернов (путаница времен, предлогов), рекомендации и выставление объективной оценки сессии.
 * **Отказоустойчивость**: постоянный пул соединений с Keep-Alive (120s) в FastAPI lifespan; при недоступности Ollama система мгновенно переключается на детерминированный математический отчёт без зависаний.
 ### 3. 🔊 Автономная нейро-озвучка (Piper TTS)
 * **Локальный VITS-инференс**: чистый нативный звук дикторов без внешних запросов к облакам (`en_US-lessac`, `ru_RU-dmitri` + поддержка альтернативных дикторов).
 * **Проактивное фоновое пред-кэширование**: при добавлении слова в словарь аудиозапись слова и контекста синтезируется сервером в фоне, обеспечивая нулевую задержку при повторении в тренажере.
 * **Аудио в читалке**: озвучивание отдельных слов, целых предложений оригинала и русского перевода.
 ### 4. 🎓 Тренажёр интервальных повторений (SRS SM-2)
 * **Алгоритм SuperMemo SM-2**: адаптивный расчёт интервалов (1, 6, $I \times EF$ дней) на основе оценок пользователя (Снова, Трудно, Хорошо, Легко).
 * **5 специализированных режимов повторений**:
  1. *3D Flashcards* — классические двусторонние карточки с 3D-анимацией переворота.
  2. *Smart Quiz* — множественный выбор из 4 вариантов с автоматическим подбором правдоподобных дистракторов из той же части речи.
  3. *Active Typing* — активная продукция: печать английского слова по русскому переводу и контексту с пропуском.
  4. *Audio Dictation* — аудиотренажёр: прослушивание произношения через Piper TTS и ввод слова на слух.
  5. *Listening Comprehension* — интерактивные аудио-сценарии с вопросами на проверку понимания.
 * **Smart Daily Mix**: сбалансированная ежедневная тренировка (10 новых слов + 10 плановых повторений + 5 проблемных слов-личей, перемешанных для интерливинга).
 * **Аналитика и визуализация**: GitHub-style календарь активности за 180 дней, подсчёт непрерывного стрика, распределение по статусам (New, Learning, Review, Mastered), расчёт Retention Rate и оценка словарного уровня по CEFR.
 ### 5. 📚 Интерактивная читалка и библиотека
 * **Поддержка форматов**: загрузка книг в форматах EPUB, PDF, TXT, Markdown (`.md`).
 * **Импорт RFC-спецификаций**: загрузка технических стандартов IETF RFC по номеру или URL с автоматической разбивкой на структурированные главы.
 * **Интеграция с Wikipedia**: автономный импорт статей по названию, теме и доступному бюджету времени на чтение.
 * **Интерактивный клик-перевод**: каждое слово кликабельно с показом всплывающей карточки (на десктопе — всплывающее окно у курсора, на смартфоне — удобный Bottom Sheet).
 * **Непрерывное чтение**: бесконечный скролл с навигационными карточками завершения глав, автоматическое сохранение позиции чтения (`current_chapter`, `current_position`).
 * **Типографика и темы**: 6 цветовых схем (Light, Dark, Sepia, Night, Parchment, Hacker), регулировка ширины страницы, межстрочного интервала и шрифтов (Georgia, Inter, JetBrains Mono).
 ### 6. 🏆 Тесты CEFR (A1–B2) & Автоматическая Gap-ингестия
 * **260 интерактивных заданий Cloze Tap**, распределённых по международным уровням владения языком (A1, A2, B1, B2).
 * **Автоматическое устранение пробелов (Gap Ingestion)**: любая допущенная ошибка в тесте мгновенно конвертируется в словарную карточку и отправляется в активную очередь SRS со статусом `learning`.
 * **Фоновый майнер тестов из книг**: асинхронный фоновый воркер для автоматического извлечения тестовых заданий из загруженных пользователем книг с фильтрацией по целевому уровню CEFR.
 ### 7. 📖 Грамматический трек Murphy & Тетрадь
 * **15 базовых юнитов** классической методики Raymond Murphy (*Essential Grammar in Use*).
 * **Структура каждого юнита**:
  - Карточка юнита со статусом освоения и баллом.
  - Полноэкранный теоретический модуль с формулами образования, русскими объяснениями и маркерами времени.
  - 5 интерактивных упражнений Cloze Tap с мгновенной проверкой.
 * **Интеграция с бумажным конспектом**: чекбокс ручной фиксации упражнений в физической тетради для задействования моторной памяти.
 ### 8. ⚡ Конструктор комплексного урока & Сессионный раннер
 * **Гибкая структура занятия**: настройка порядка этапов, переключение тумблеров активности, выбор объема слов и упражнений.
 * **Готовые пресеты**:
  - ⚡ *Утренний экспресс (10 мин)*
  - 🎯 *Сбалансированный урок (20 мин)*
  - 📖 *Глубокое погружение (30 мин)*
  - 🎧 *Аудио + Чтение (15 мин)*
  - Возможность сохранения собственных шаблонов в базу SQLite.
 * **Умный подбор грамматики**: адаптивный выбор темы грамматики на основе истории ошибок («Самая слабая тема», «Предыдущая тема» или ручной выбор).
 * **Сквозной раннер**: бесшовный интерфейс с таймером, прогресс-баром и финальным ИИ-дебрифингом.
 ---
-## 🛠 Технический стек
+## 🛠 Техническая архитектура и стек
- **Backend**: Python 3.12 (FastAPI / Uvicorn)
+```
- **Database**: SQLite (WAL mode — надёжность, автономность, бэкап в один файл)
+                                https://study.qpid.pro
- **Безопасность**: Защищённые сессии (HttpOnly cookies), PBKDF2-HMAC-SHA256, Rate Limiting
+                                          │
- **Frontend**: Vanilla HTML5 / Modern CSS / ES6+ JavaScript (PWA, горячие клавиши, мгновенный отклик)
+                       ┌──────────────────▼──────────────────┐
- **Внешние API**: Free Dictionary API (IPA + audio), MyMemory Translation API
+                       │   Nginx (Host SSL / Reverse Proxy)  │
- **Веб-сервер**: Nginx Reverse Proxy + SSL Let's Encrypt (`notes.qpid.pro`)
+                       └──────────────────┬──────────────────┘
- **Репозиторий проекта**: [Gitea (ai.qpid.pro/gitea/Antigravity/notes-qpid-pro)](https://ai.qpid.pro/gitea/Antigravity/notes-qpid-pro)
+                                          │ :8002
 ┌─────────────────────────────────────────▼────────────────────────────────────────┐
 │                        Docker Container: study-qpid-pro                          │
 │                                                                                  │
 │   ┌──────────────────────────────────────────────────────────────────────────┐   │
 │   │                     FastAPI Application (app/main.py)                    │   │
 │   │  • GZipMiddleware (≥1000B)      • Security Headers Middleware            │   │
 │   │  • Persistent Lifespan Pool     • Service Worker Static Precache (v6.7)  │   │
 │   └─────────────────────────────────────┬────────────────────────────────────┘   │
 │                                         │                                        │
 │   ┌─────────────────────────────────────▼────────────────────────────────────┐   │
 │   │                         Модульные APIRouters                             │   │
 │   │  • auth.py         • cards.py        • dictionary.py   • srs.py          │   │
 │   │  • reader.py       • cefr.py         • grammar.py      • lessons.py      │   │
 │   │  • listening.py    • tasks.py        • export.py                         │   │
 │   └─────────────────┬───────────────────┬──────────────────┬─────────────────┘   │
 │                     │                   │                  │                     │
 │   ┌─────────────────▼─────────┐ ┌───────▼────────┐ ┌───────▼─────────────────┐   │
 │   │  SQLite WAL (data/notes)  │ │   Piper TTS    │ │  Seed Datasets (JSON)   │   │
 │   │  • Memory-Mapped I/O      │ │ • Offline VITS │ │  • cefr_questions.json  │   │
 │   │  • Full Schema Integrity  │ │ • Zero-Latency │ │  • grammar_units.json   │   │
 │   │  • Sub-millisecond reads  │ │ • Voice Cache  │ │  • phrasal_verbs.json   │   │
 │   └───────────────────────────┘ └────────────────┘ └─────────────────────────┘   │
 └─────────────────────────────────────────┬────────────────────────────────────────┘
                                          │ http://ollama:11434
 ┌─────────────────────────────────────────▼────────────────────────────────────────┐
 │                        Docker Container: study-ollama                            │
 │   • Model: Qwen 2.5 3B Instruct (GGUF)                                           │
 │   • Connection Pool with Keep-Alive (120s)                                       │
 └──────────────────────────────────────────────────────────────────────────────────┘
 ```
 * **Backend**: Python 3.12, FastAPI, Uvicorn, Pydantic v2.
 * **База данных**: SQLite в режиме `WAL` (Write-Ahead Logging) с `mmap_size = 256MB` и индексами по внешним ключам и выражениям.
 * **Frontend**: Vanilla ES6+ модули, HTML5 PWA, CSS-переменные (7 предметных таблиц стилей), поддержка offline через Service Worker.
 * **AI & TTS**: Ollama (`qwen2.5:3b`), Piper Neural TTS (локальный бинарник).
 * **Тестирование**: Pytest + TestClient (44 автоматических интеграционных теста).
 ---
-## 🌐 Информация об окружении
+## 📁 Структура проекта
- **URL сервиса**: [https://notes.qpid.pro](https://notes.qpid.pro)
+```
- **IP сервера**: `31.77.203.213`
+study.qpid.pro/
- **Каталог проекта**: [`/home/kopri/notes.qpid.pro`](file:///home/kopri/notes.qpid.pro)
+├── app/
- **Git Remote**: `http://127.0.0.1:3000/Antigravity/notes-qpid-pro.git`
+│   ├── main.py                  # Лаконичная точка входа FastAPI (lifespan, middleware, роутеры)
 │   ├── auth.py                  # Безопасность, хэширование PBKDF2, сессии, rate limiting
 │   ├── config.py                # Переменные окружения и системные пути
 │   ├── database.py              # Инициализация SQLite WAL, индексы, миграции
 │   ├── dictionary.py            # Поиск в офлайн-словаре, лемматизация, каскадные запросы
 │   ├── ai.py                    # Интеграция с Ollama (Keep-Alive пул, промпты, дебрифинг)
 │   ├── tts.py                   # Синтез речи Piper TTS и управление кэшем аудио
 │   ├── srs.py                   # SM-2 интервалы, викторины, аналитика, тепловая карта
 │   ├── reader.py                # Парсеры EPUB, PDF, TXT, Markdown, RFC и Wikipedia
 │   ├── cefr.py                  # Уровневое тестирование A1–B2 и gap-ингестия
 │   ├── grammar.py               # Движок Murphy Grammar и журнал конспектов
 │   ├── lessons.py               # Конструктор уроков, пресеты, история сессий
 │   ├── listening.py             # Сценарии аудирования и оценка ответов
 │   ├── miner.py                 # Фоновый майнинг предложений из литературы
 │   ├── tasks.py                 # Управление фоновыми задачами SQLite
 │   ├── export.py                # Экспорт базы (CSV, JSON, Anki, Markdown)
 │   ├── routers/                 # Модульные роутеры FastAPI (11 файлов)
 │   └── static/                  # Статика веб-приложения
 │       ├── index.html           # Одностраничное приложение (PWA Shell)
 │       ├── sw.js                # Service Worker (кэширование v6.7)
 │       ├── manifest.json        # PWA-манифест
 │       ├── css/                 # Модульная таблица стилей
 │       │   ├── style.css        # Мастер-файл со структурой и @import
 │       │   ├── base.css         # Токены, темы, сброс, safe-areas
 │       │   ├── components.css   # Навбар, меню, кнопки, модалки, таб-бар
 │       │   ├── dictionary.css   # Поиск, карточки слов, коллекции, теги
 │       │   ├── srs.css          # Карточки 3D, квизы, ввод, аналитика
 │       │   ├── reader.css       # Читалка, темы оформления, Wikipedia
 │       │   ├── grammar_cefr.css # CEFR и юниты Murphy
 │       │   └── lesson.css       # Конфигуратор и раннер уроков
 │       └── js/                  # ES6 модули фронтенда
 │           ├── app.js           # Точка входа SPA, роутинг, хоткеи
 │           └── modules/         # Модули логики (ui, api, dictionary, srs, reader, cefr, grammar, lesson)
 ├── data/
 │   ├── notes.db                 # Основная база данных SQLite
 │   ├── offline_dict.tsv.gz      # Локальный словарь (140k+ записей)
 │   ├── audio_cache/             # Кэш предсинтезированных WAV-файлов
 │   └── seeds/                   # Кураторские JSON-датасеты (CEFR, Murphy, Phrasal, Articles)
 ├── scripts/
 │   ├── deploy_beta.sh           # Развертывание бета-ветки в 1 клик
 │   ├── rollback_to_main.sh      # Мгновенный откат на стабильный main
 │   └── build_offline_dict.py    # Сборщик офлайн-словаря
 ├── tests/
 │   └── test_api.py              # Набор интеграционных тестов (44 теста)
 ├── docker-compose.yml           # Декларация контейнеров study-web и ollama
 └── Dockerfile                   # Образ веб-приложения на Python 3.12-slim
 ```
 ---
 ## 🚀 Развёртывание и запуск
 ### Запуск через Docker Compose (Рекомендуемый)
 ```bash
 # Клонирование репозитория
 git clone https://ai.qpid.pro/gitea/Antigravity/notes-qpid-pro.git
 cd notes-qpid-pro
 # Запуск связки веб-сервера и локальной Ollama
 DOCKER_HOST=tcp://127.0.0.1:2375 docker compose up -d
 # Запуск тестов внутри контейнера
 DOCKER_HOST=tcp://127.0.0.1:2375 docker exec -i -e PYTHONPATH=. study-qpid-pro pytest tests/test_api.py
 ```
 ### Управление ветками и откат:
 ```bash
 # Быстрый переход на бета-версию:
 ./scripts/deploy_beta.sh
 # Мгновенный откат на стабильную ветку main:
 ./scripts/rollback_to_main.sh
 ```
 ---
 ## 📄 Лицензия и статус проекта
 * Проект разрабатывается в активной фазе для повседневного практического освоения языка.
 * 100% открытый исходный код без проприетарных платных облачных зависимостей.
@@ -447,16 +447,39 @@
 ---
 ### 20. 🏗️ Комплексный технический рефакторинг и оптимизация архитектуры (Completed)
 - [x] **Этап 1: Очистка мертвого кода и оптимизация SQL**:
  - Удалена старая незавершенная функция `parse_text` в `app/reader.py` (строки 290–326).
  - Функция `update_task_progress` в `app/tasks.py` переписана с цикла на единый параметризованный SQL-запрос `UPDATE tasks SET progress = ?, current_item = ?, ...`.
 - [x] **Этап 2: Вынос датасетов в JSON (`data/seeds/*.json`)**:
  - Из исходников извлечено более 3 100 строк статических данных: `cefr_questions.json` (260 вопросов), `grammar_units.json` (15 юнитов), `phrasal_verbs.json` (157 глаголов), `reading_articles.json` (8 статей).
  - Модули `app/cefr.py`, `app/grammar.py`, `app/phrasal.py`, `app/lessons.py` переведены на динамическую ленивую загрузку с сохранением полной обратной совместимости.
 - [x] **Этап 3: Оптимизация сети и локального ИИ**:
  - Внедрен постоянный пул соединений `httpx.AsyncClient` с Keep-Alive (120s) для локальной Ollama в `app/ai.py`, управляемый в жизненном цикле приложения (`lifespan`).
  - Интегрирована встроенная офлайн-лемматизация (`lemmatize_word`) в `lookup_term` (`app/dictionary.py`), предотвращающая лишние сетевые запросы при поиске словоформ (`starts` -> `start`, `studying` -> `study`).
 - [x] **Этап 4: Модуляризация бэкенда FastAPI**:
  - Монолитный `app/main.py` сокращен с 2 240 до 142 строк.
  - Создан пакет `app/routers/` с 11 тематическими APIRouter: `auth.py`, `cards.py`, `dictionary.py`, `srs.py`, `export.py`, `reader.py`, `cefr.py`, `grammar.py`, `tasks.py`, `lessons.py`, `listening.py`.
 - [x] **Этап 5: Модуляризация CSS и Service Worker**:
  - Монолитный `style.css` (8 746 строк) разделен на 7 предметных таблиц в `app/static/css/`: `base.css`, `components.css`, `dictionary.css`, `srs.css`, `reader.css`, `grammar_cefr.css`, `lesson.css`.
  - Мастер-файл `style.css` загружает стили через `@import` и содержит полную архитектурную карту.
  - Обновлен Service Worker (`notes-v6.7`) с добавлением всех CSS в `PRECACHE_URLS` для полной офлайн-работы PWA.
 - [x] **Инфраструктура быстрого переключения и отката**:
  - Добавлены скрипты `scripts/deploy_beta.sh` и `scripts/rollback_to_main.sh` для мгновенного отката или развертывания в 1 клик.
  - Создан резервный бэкап базы данных `data/notes.db.backup-main-pre-beta`.
 - [x] **100% успешное тестирование**:
  - Все 44 интеграционных теста `pytest tests/test_api.py` успешно проходят в Docker-контейнере.
 ---
 ## ⏳ Coming Soon
 - [ ] **🌐 Быстрый захват из браузера (Bookmarklet)**:
  - Создать JavaScript-букмарклет для добавления слова/фразы из любого окна браузера в личный словарь [`study.qpid.pro`](https://study.qpid.pro) (низший приоритет).
 - [ ] **Нативная автономная озвучка (HTML5 Web Speech API / `speechSynthesis`)**:
-  - Использовать встроенный в браузер синтезатор речи `window.speechSynthesis` (en-US, en-GB).
+  - Использовать встроенный в браузер синтезатор речи `window.speechSynthesis` (en-US, en-GB) как дополнительный резервный фолбэк при работе на мобильных без связи.
-  - 0 сетевых запросов к серверу, 100% оффлайн-работа.
+- [ ] **Расширение библиотеки Murphy**:
-  - Поддержка озвучивания отдельных слов, фраз, идиом и предложений-контекстов читалки.
+  - Добавление следующих 15 юнитов грамматики (юниты 16–30: пассивный залог, косвенная речь, модальные глаголы).
 - [ ] **Возврат режима «Диктант» в SRS**:
  - Возобновление работы аудиотренажёра на базе нативного браузерного синтезатора речи без зависимости от внешних аудиофайлов.
 ---