diff --git a/README.md b/README.md
index aa287e2..18a75c4 100644
--- a/README.md
+++ b/README.md
@@ -1,261 +1,83 @@
+# Alexander Smart Speaker
+
 <div align="center">
 
-# 🎙️ Alexander Smart Speaker
+Голосовой ассистент для Linux: wake word, STT/TTS, AI-диалог и полезные голосовые навыки.
 
-**Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков**
-
-[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://www.linux.org/)
-[![License](https://img.shields.io/github/license/your-username/alexander_smart-speaker)](LICENSE.txt)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Linux](https://img.shields.io/badge/Platform-Linux-FCC624?logo=linux&logoColor=111)](https://www.linux.org/)
+[![MIT License](https://img.shields.io/badge/License-MIT-2ea44f)](LICENSE.txt)
+[![Wake Word](https://img.shields.io/badge/Wake%20Word-Porcupine-0b7285)](https://picovoice.ai/platform/porcupine/)
+[![STT](https://img.shields.io/badge/STT-Deepgram-4c6ef5)](https://deepgram.com/)
+[![TTS](https://img.shields.io/badge/TTS-Silero-7950f2)](https://github.com/snakers4/silero-models)
 
 </div>
 
-## ✨ Возможности
+## Что это
 
-| Функция | Описание |
-|--------|----------|
-| 🔊 **Активация по ключевому слову** | Активация по команде `Alexandr` |
-| 🧠 **Диалог с AI** | Взаимодействие с Perplexity с сохранением контекста |
-| 🌐 **Перевод** | Перевод RU ↔ EN с озвучиванием |
-| 🌤️ **Погода** | Информация о погоде по умолчанию и по названию города |
-| ⏰ **Таймеры и будильники** | Управление таймерами, будильниками и секундомерами |
-| 🔊 **Управление громкостью** | Регулировка системной громкости |
-| 🎵 **Spotify интеграция** | Управление воспроизведением (play/pause/next/current track) |
-| 🌍 **Игра в города** | Классическая игра в города |
+`Alexander Smart Speaker` слушает ключевое слово `Alexandr`, распознает речь, маршрутизирует команду в нужный модуль и озвучивает ответ.
+Проект оптимизирован под русский язык, но поддерживает RU/EN сценарии (включая перевод и mixed-language TTS).
 
-## 🏗️ Архитектура проекта
+## Возможности
 
-### Диаграмма взаимодействия компонентов
+- Активация по wake word `Alexandr` (Porcupine).
+- Распознавание речи через Deepgram (WebSocket, VAD, fast stop).
+- Озвучка через Silero TTS (RU + EN, с прерыванием по wake word).
+- AI-диалог через Perplexity API со streaming-ответом и контекстом.
+- Перевод RU -> EN и EN -> RU.
+- Погода: текущий прогноз по городу по умолчанию или по названию города.
+- Таймеры, будильники (включая будни/выходные), секундомеры.
+- Управление громкостью системы (через `pactl`/`amixer`).
+- Управление Spotify (play/pause/next/what's playing).
+- Мини-игра "Города".
+
+## Как это работает
 
 ```mermaid
-graph TB
-    subgraph "Основной цикл"
-        A[main() - основной цикл] --> B{Режим активации}
-        B -->|Ожидание wake word| C[wait_for_wakeword()]
-        B -->|Режим диалога| D[listen() в режиме follow-up]
-        C --> E[Прослушивание команды]
-        D --> E
-        E --> F[Анализ команды]
-    end
-    
-    subgraph "Аудио подсистема"
-        C1[wait_for_wakeword()<br/>wakeword.py<br/>check_wakeword_once()]
-        E1[listen()<br/>stt.py<br/>get_recognizer()]
-        G1[speak()<br/>tts.py<br/>initialize()]
-        H1[parse_volume_text()<br/>sound_level.py<br/>set_volume()]
-        
-        C1 -.-> E1
-        E1 -.-> G1
-        H1 -.-> G1
-    end
-    
-    subgraph "Ядро"
-        F1[is_stop_command()<br/>commands.py<br/>_normalize_text()]
-        F2[ask_ai_stream()<br/>ai.py<br/>translate_text()]
-        F3[clean_response()<br/>cleaner.py]
-        F5[get_smalltalk_response()<br/>smalltalk.py]
-        
-        F --> F1
-        F --> F2
-        F --> F3
-        F --> F5
-    end
-    
-    subgraph "Функции"
-        I1[get_weather_report()<br/>weather.py]
-        I2[get_timer_manager()<br/>timer.py]
-        I3[get_alarm_clock()<br/>alarm.py]
-        I4[get_stopwatch_manager()<br/>stopwatch.py]
-        I5[get_music_controller()<br/>music.py]
-        I6[get_cities_game()<br/>cities_game.py]
-        
-        F --> I1
-        F --> I2
-        F --> I3
-        F --> I4
-        F --> I5
-        F --> I6
-    end
-    
-    subgraph "Обработка команд"
-        F --> J{Тип команды}
-        J -->|Small talk| K[get_smalltalk_response()]
-        J -->|Повтор| L[Повтор последнего ответа]
-        J -->|Стоп| M[is_stop_command()]
-        J -->|Таймер| N[parse_command() timer]
-        J -->|Будильник| O[parse_command() alarm]
-        J -->|Секундомер| P[parse_command() stopwatch]
-        J -->|Громкость| Q[parse_volume_text() + set_volume()]
-        J -->|Погода| R[get_weather_report()]
-        J -->|Музыка| S[parse_command() music]
-        J -->|Перевод| T[parse_translation_request()]
-        J -->|Города| U[handle() cities_game]
-        J -->|AI| V[ask_ai_stream()]
-    end
-    
-    subgraph "Ответ пользователю"
-        K --> W[clean_response()]
-        L --> W
-        M --> W
-        N --> W
-        O --> W
-        P --> W
-        Q --> W
-        R --> W
-        S --> W
-        T --> W
-        U --> W
-        V --> W
-        
-        W --> X[speak()]
-        X --> Y[Возврат в режим ожидания]
-        Y --> A
-    end
-    
-    %% Connections
-    C1 -.-> A
-    E1 -.-> F
-    G1 -.-> X
-    F2 -.-> V
-    F3 -.-> W
-    I1 -.-> R
-    I2 -.-> N
-    I3 -.-> O
-    I4 -.-> P
-    I5 -.-> S
-    I6 -.-> U
-    
-    style A fill:#e1f5fe
-    style F fill:#f3e5f5
-    style X fill:#e8f5e8
-    style Y fill:#fff3e0
-</graph>
+flowchart TD
+    A[Wake Word: Alexandr] --> B[STT: Deepgram]
+    B --> C{Маршрутизация команды}
+    C --> D[Feature modules]
+    C --> E[AI/Translation]
+    D --> F[TTS: Silero]
+    E --> F
+    F --> G[Follow-up режим или ожидание wake word]
 ```
 
-### Диаграмма потока команд от wake word до функций
+## Быстрый старт
 
-```mermaid
-graph TD
-    subgraph "Активация и распознавание"
-        A[wait_for_wakeword()<br/>wakeword.py] --> B[listen()<br/>stt.py]
-        B --> C[Распознанный текст]
-    end
-    
-    subgraph "Анализ команды"
-        C --> D{Тип команды}
-    end
-    
-    subgraph "Обработка специфических команд"
-        D -->|Small talk| E[get_smalltalk_response()<br/>smalltalk.py]
-        D -->|Стоп команда| F[is_stop_command()<br/>commands.py]
-        D -->|Таймер| G[parse_command()<br/>timer.py]
-        D -->|Будильник| H[parse_command()<br/>alarm.py]
-        D -->|Секундомер| I[parse_command()<br/>stopwatch.py]
-        D -->|Громкость| J[parse_volume_text()<br/>sound_level.py<br/>set_volume()]
-        D -->|Погода| K[get_weather_report()<br/>weather.py]
-        D -->|Музыка| L[parse_command()<br/>music.py]
-        D -->|Перевод| M[parse_translation_request()<br/>ai.py<br/>translate_text()]
-        D -->|Города| N[handle()<br/>cities_game.py]
-        D -->|Обычный вопрос| O[ask_ai_stream()<br/>ai.py]
-    end
-    
-    subgraph "Ответ пользователю"
-        E --> P[clean_response()<br/>cleaner.py]
-        F --> P
-        G --> P
-        H --> P
-        I --> P
-        J --> P
-        K --> P
-        L --> P
-        M --> P
-        N --> P
-        O --> P
-        P --> Q[speak()<br/>tts.py]
-    end
-    
-    subgraph "Цикл управления"
-        Q --> R{Продолжить диалог?}
-        R -->|Да| S[Остаться в режиме ожидания]
-        R -->|Нет| T[Ждать wake word снова]
-        S --> B
-        T --> A
-    end
-</graph>
-```
-
-## 🛠️ Технологии
-
-| Компонент | Технология |
-|-----------|------------|
-| **Wake word** | `pvporcupine` |
-| **STT** | `deepgram-sdk` |
-| **TTS** | `Silero` (`torch`, `torchaudio`) |
-| **AI** | Perplexity API |
-| **Погода** | Open-Meteo |
-| **Музыка** | Spotify Web API (`spotipy`) |
-
-## 📋 Требования
-
-- **ОС**: Linux
-- **Python**: 3.9+
-- **Системные пакеты**:
+### 1) Системные зависимости (Ubuntu/Debian)
 
 ```bash
 sudo apt-get update
-sudo apt-get install -y portaudio19-dev libasound2-dev mpg123
+sudo apt-get install -y portaudio19-dev libasound2-dev mpg123 pulseaudio-utils alsa-utils
 ```
 
-> 💡 Для управления громкостью необходим `pactl` или `amixer` (обычно из `pulseaudio-utils`/`alsa-utils`).
+### 2) Установка Python-зависимостей
 
-## 🚀 Установка
-
-1. **Клонируйте репозиторий**:
 ```bash
-git clone https://github.com/your-username/alexander_smart-speaker.git
+git clone <URL_ВАШЕГО_РЕПОЗИТОРИЯ>
 cd alexander_smart-speaker
-```
-
-2. **Настройте виртуальное окружение**:
-```bash
-python -m venv venv
-source venv/bin/activate  # или venv\Scripts\activate на Windows
+python3 -m venv venv
+source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-## ⚙️ Настройка
+### 3) Настройка `.env`
 
-1. **Создайте файл конфигурации**:
 ```bash
 cp .env.example .env
 ```
 
-2. **Обязательные переменные окружения**:
+Минимально обязательные переменные:
 
 ```ini
-PERPLEXITY_API_KEY=your_perplexity_api_key_here
-DEEPGRAM_API_KEY=your_deepgram_api_key_here
-PORCUPINE_ACCESS_KEY=your_porcupine_access_key_here
+PERPLEXITY_API_KEY=...
+DEEPGRAM_API_KEY=...
+PORCUPINE_ACCESS_KEY=...
 ```
 
-3. **Полная конфигурация** (как в `.env.example`):
-
-```ini
-PERPLEXITY_API_KEY=your_perplexity_api_key_here
-PERPLEXITY_MODEL=llama-3.1-sonar-small-128k-chat
-DEEPGRAM_API_KEY=your_deepgram_api_key_here
-PORCUPINE_ACCESS_KEY=your_porcupine_access_key_here
-PORCUPINE_SENSITIVITY=0.8
-TTS_EN_SPEAKER=en_0
-WEATHER_LAT=63.56
-WEATHER_LON=53.69
-WEATHER_CITY=Ухта
-SPOTIFY_CLIENT_ID=your_spotify_client_id
-SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
-SPOTIFY_REDIRECT_URI=http://localhost:8888/callback
-```
-
-## ▶️ Запуск
+### 4) Запуск
 
 ```bash
 make run
@@ -263,62 +85,76 @@ make run
 python run.py
 ```
 
-## 🗣️ Примеры голосовых команд
+После запуска ассистент перейдет в режим ожидания фразы `Alexandr`.
 
-| Категория | Команды |
-|-----------|---------|
-| **Активация** | `Alexandr` |
-| **Диалог** | `Почему небо голубое?` |
-| **Погода** | `Какая сейчас погода?`, `Погода в Москве` |
-| **Перевод** | `Переведи на английский: как дела` |
-| **Таймер** | `Поставь таймер на 5 минут` |
-| **Будильник** | `Поставь будильник на 7:30`, `Будильник по будням в 8:00` |
-| **Секундомер** | `Запусти секундомер`, `Покажи активные секундомеры` |
-| **Громкость** | `Громкость 5` |
-| **Spotify** | `Включи музыку`, `Пауза`, `Что сейчас играет` |
-| **Игра** | `Давай сыграем в города` |
-| **Остановка** | `Стоп`, `Хватит`, `Повтори` |
+## Конфигурация `.env`
 
-## 🛠️ Полезные команды
+| Переменная | Обязательно | По умолчанию | Назначение |
+|---|---|---|---|
+| `PERPLEXITY_API_KEY` | Да | - | Ключ Perplexity API |
+| `PERPLEXITY_MODEL` | Нет | `llama-3.1-sonar-small-128k-chat` | Модель Perplexity |
+| `DEEPGRAM_API_KEY` | Да | - | Ключ Deepgram STT |
+| `PORCUPINE_ACCESS_KEY` | Да | - | Ключ PicoVoice Porcupine |
+| `PORCUPINE_SENSITIVITY` | Нет | `0.8` | Чувствительность wake word |
+| `TTS_EN_SPEAKER` | Нет | `en_0` | Английский голос TTS |
+| `WEATHER_LAT` | Нет | - | Широта города по умолчанию |
+| `WEATHER_LON` | Нет | - | Долгота города по умолчанию |
+| `WEATHER_CITY` | Нет | `Ухта` | Город по умолчанию для погоды |
+| `SPOTIFY_CLIENT_ID` | Нет | - | Spotify OAuth Client ID |
+| `SPOTIFY_CLIENT_SECRET` | Нет | - | Spotify OAuth Client Secret |
+| `SPOTIFY_REDIRECT_URI` | Нет | `http://localhost:8888/callback` | Redirect URI для Spotify |
 
-| Команда | Назначение |
-|---------|------------|
+## Примеры голосовых команд
+
+| Категория | Примеры |
+|---|---|
+| Активация | `Alexandr` |
+| AI-диалог | `Почему небо голубое?` |
+| Перевод | `Переведи на английский: как дела` |
+| Погода | `Какая погода?`, `Погода в Москве` |
+| Таймер | `Поставь таймер на 5 минут` |
+| Будильник | `Поставь будильник на 7:30`, `Будильник по будням в 8:00` |
+| Секундомер | `Запусти секундомер`, `Покажи активные секундомеры` |
+| Громкость | `Громкость 7` |
+| Spotify | `Включи музыку`, `Пауза`, `Что сейчас играет` |
+| Игра | `Давай сыграем в города` |
+| Управление диалогом | `Повтори`, `Стоп`, `Хватит` |
+
+## Полезные команды
+
+| Команда | Что делает |
+|---|---|
 | `make run` | Запуск ассистента |
-| `make check` | Базовая проверка проекта |
-| `make qwen-context` | Собрать контекст проекта |
+| `make check` | Локальная проверка проекта (`scripts/qwen-check.sh`) |
+| `make qwen-context` | Сбор контекста проекта (`scripts/qwen-context.sh`) |
 
-## 📁 Структура проекта
+## Структура проекта
 
-```
+```text
 alexander_smart-speaker/
-├── run.py                 # точка входа
+├── run.py
 ├── app/
-│   ├── main.py           # главный цикл ассистента
-│   ├── audio/            # wake word, STT, TTS, громкость
-│   ├── core/             # конфиг, AI, роутинг команд, утилиты
-│   └── features/         # погода, будильник, таймер, секундомер, музыка, города
-├── assets/               # модели и звуки
-├── data/                 # сохраненные будильники/таймеры/секундомеры
-└── scripts/              # скрипты для установки и обслуживания
+│   ├── main.py
+│   ├── audio/      # wakeword, stt, tts, volume
+│   ├── core/       # config, ai, command helpers, cleaner
+│   └── features/   # weather, timer, alarm, stopwatch, music, cities game
+├── assets/
+│   ├── models/     # Porcupine keyword model (.ppn)
+│   └── sounds/     # звуки уведомлений и будильника
+├── data/           # persisted JSON: alarms, timers, stopwatches
+└── scripts/
 ```
 
-## 🔧 Диагностика проблем
+## Диагностика
 
-| Проблема | Решение |
-|----------|---------|
-| Ошибки STT/AI | Проверьте ключи в `.env` |
-| Нет звука | Проверьте системное устройство вывода и утилиты `pactl`/`amixer` |
-| Не играет будильник/таймер | Убедитесь, что установлен `mpg123` |
-| Spotify не управляется | Проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства |
+| Проблема | Что проверить |
+|---|---|
+| Не реагирует на `Alexandr` | `PORCUPINE_ACCESS_KEY`, микрофон, чувствительность `PORCUPINE_SENSITIVITY` |
+| STT не распознает речь | `DEEPGRAM_API_KEY`, сетевой доступ, выбранный микрофон |
+| Нет звука | корректное аудиоустройство и доступность `pactl`/`amixer` |
+| Будильник/таймер не звонит | наличие `mpg123` в системе |
+| Spotify не управляется | заполнены `SPOTIFY_*`, есть активное устройство, Premium-аккаунт |
 
-## 📄 Лицензия
+## Лицензия
 
-MIT, см. [LICENSE.txt](LICENSE.txt).
-
----
-
-<div align="center">
-
-**Если вам понравился проект, поставьте ⭐ звезду!**
-
-</div>
\ No newline at end of file
+Проект распространяется по лицензии MIT. См. `LICENSE.txt`.