diff --git a/README.md b/README.md
index d9befe4..498c951 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,97 @@
 # ВДНХ Афиша API (Тестовое задание)
 
-## Постановка задачи
-В рамках тестового задания надо написать бэкэнд для Афиши событий https://vdnh.ru/  (фронтенд делать не надо)
+Бэкенд-приложение для фильтрации и вывода афиши событий Выставки (ВДНХ) на основе предоставленного технического задания.
 
-1. Сделать метод апи, который позволяет фильтровать события по нескольким категориям и промежутку дат. Список событий должен иметь пагинацию.
-2. Должен быть реализован сидинг (посев данных) для категорий и событий.
-3. Код должен быть залит на открытый источник (предпочтительно github) и предоставлен json-импорт для swagger или postman.
+## 🛠 Стек технологий
+- **PHP:** 8.2 / 8.3
+- **Framework:** Laravel 11.x (или ваша версия)
+- **Database:** MySQL / PostgreSQL
+- **API Specification:** Postman (коллекция в корне проекта)
 
-## Развертывание проекта
-1. `composer install`
-2. Настроить подключение к БД в `.env`
-   DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
-3. `php artisan migrate:fresh --seed` 
-(команда развернет БД, создаст тестового юзера, 11 категорий и 40 сгенерированных событий).
+---
 
-## Эндпоинты
-- `GET /api/gigs` — Получение списка событий с пагинацией и фильтрами.
-- Для тестирования импортируйте файл `gigs_api_collection.json` в Postman.
+## 📋 Постановка задачи
+Разработать JSON API для Афиши событий (https://vdnh.ru/) со следующими требованиями:
+1. Метод API для фильтрации событий по нескольким категориям и промежутку дат.
+2. Реализация пагинации для списка событий.
+3. Наличие сидеров (Database Seeding) для наполнения тестовыми данными.
+4. Публикация на GitHub + предоставление коллекции для Postman.
+
+## 🚀 Развертывание проекта
+
+Выполните последовательно следующие команды в терминале:
+
+1. **Клонирование репозитория и установка зависимостей:**
+   ```bash
+   composer install
+   ```
+
+2. **Настройка окружения:**
+   ```bash
+   cp .env.example .env
+   php artisan key:generate
+   ```
+   *Отредактируйте файл `.env`, указав ваши доступы к базе данных (`DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`).*
+
+3. **Миграции и наполнение базы (Сидинг):**
+   ```bash
+   php artisan migrate:fresh --seed
+   ```
+   > 💡 **Что произойдет:** Команда полностью пересоздаст структуру БД и запустит сидеры, которые сгенерируют **11 реальных категорий** и **40 тестовых событий** со случайными датами для удобной проверки фильтрации.
+
+## 💻 Консольные команды (CLI)
+
+Для удобства управления пользователями и токенами добавлены кастомные Artisan-команды:
+
+1. **Создание пользователя и генерация API-токена:**
+   ```bash
+   php artisan user:create-api-user "Ivan Ivanov" ivan@example.com "secret123"
+   ```
+   *Команда регистрирует нового пользователя в базе данных и сразу генерирует для него первый Sanctum-токен.*
+
+2. **Сброс пароля и выдача нового токена:**
+   ```bash
+   php artisan user:reset-password ivan@example.com "new_secret123"
+   ```
+   *Команда находит пользователя по email, обновляет его пароль и выводит в консоль новый рабочий Sanctum-токен.*
+
+
+## 📡 Документация API (Эндпоинты)
+
+*Для всех запросов обязательно передавайте заголовки:*
+- `Accept: application/json`
+- `Content-Type: application/json`
+
+### 1. Авторизация (Получение токена)
+
+*   **URL:** `/api/login`
+*   **Метод:** `POST`
+
+#### Тело запроса (JSON):
+```json
+{
+    "email": "user@example.com",
+    "password": "your_password"
+}
+```
+*В ответе возвращаются  данные пользователя и его `access_token` для авторизации в защищенных эндпоинтах.*
+
+### 2. Получение списка событий с фильтрацией и пагинацией
+
+*   **URL:** `/api/gigs`
+*   **Метод:** `GET`
+
+#### Параметры запроса (Query Parameters):
+
+| Параметр | Тип | Обязательный | Описание | Пример |
+| :--- | :--- | :--- | :--- | :--- |
+| `categories` | `array` | Нет | Массив ID или слагов категорий | `categories[]=1&categories[]=2` |
+| `date_from` | `string` | Нет | Начало диапазона дат (`YYYY-MM-DD`) | `2026-05-01` |
+| `date_to` | `string` | Нет | Конец диапазона дат (`YYYY-MM-DD`) | `2026-05-31` |
+| `page` | `integer` | Нет | Номер страницы пагинации | `2` |
+
+#### Пример запроса:
+`GET /api/gigs?categories[]=1&categories[]=4&date_from=2026-02-01&date_to=2026-05-31`
+
+---