diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fcd6ed6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,161 @@
+# Web Auth (PHP + MySQL)
+
+Минимальная система авторизации для статических HTML‑сайтов с проверкой доступа по алиасам сайтов.
+
+## Возможности
+- Авторизация по логину/паролю (PHP + MySQL)
+- Сессии с безопасными cookie
+- Раздельный доступ по сайтам через алиасы
+- Готовый UI для страницы входа
+- Скрипт массового импорта пользователей
+
+---
+
+## Структура проекта
+```
+/
+  api/
+    login.php
+    check_auth.php
+    logout.php
+  config/
+    db.php
+    session.php
+  css/
+    auth.css
+  js/
+    auth.js
+  login.html
+  index.html
+  import_users.php
+```
+
+---
+
+## Требования
+- PHP 7.4+ (с модулями `pdo_mysql`)
+- MySQL/MariaDB
+- Веб‑сервер (Apache/Nginx)
+
+---
+
+## Шаг 1. Создание таблицы пользователей
+
+```sql
+CREATE TABLE users (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  username VARCHAR(64) NOT NULL UNIQUE,
+  password_hash VARCHAR(255) NOT NULL,
+  ok5  TINYINT(1) NOT NULL DEFAULT 0,
+  o7   TINYINT(1) NOT NULL DEFAULT 0,
+  o10m TINYINT(1) NOT NULL DEFAULT 0,
+  o10a TINYINT(1) NOT NULL DEFAULT 0,
+  webp TINYINT(1) NOT NULL DEFAULT 0
+);
+```
+
+> Если таблица уже есть, добавьте колонки алиасов:
+```sql
+ALTER TABLE users
+  ADD COLUMN ok5  TINYINT(1) NOT NULL DEFAULT 0,
+  ADD COLUMN o7   TINYINT(1) NOT NULL DEFAULT 0,
+  ADD COLUMN o10m TINYINT(1) NOT NULL DEFAULT 0,
+  ADD COLUMN o10a TINYINT(1) NOT NULL DEFAULT 0,
+  ADD COLUMN webp TINYINT(1) NOT NULL DEFAULT 0;
+```
+
+---
+
+## Шаг 2. Настройка подключения к БД
+Отредактируйте `config/db.php`:
+```php
+$host = 'localhost';
+$dbname = 'users';
+$username = 'root';
+$password = '...';
+```
+
+---
+
+## Шаг 3. Подключение к сайту
+
+### 1) Добавьте папку `api/`, `js/`, `css/` в корень сайта
+Должны быть доступны:
+- `/api/login.php`
+- `/api/check_auth.php`
+- `/api/logout.php`
+- `/js/auth.js`
+- `/css/auth.css`
+
+### 2) Страница логина
+В `login.html` добавьте:
+```html
+<meta name="site-alias" content="ok5">
+<link rel="stylesheet" href="css/auth.css">
+<script src="js/auth.js"></script>
+```
+
+`site-alias` — это идентификатор сайта для доступа.
+
+### 3) Защищённые страницы
+На любой странице, которую нужно защитить:
+```html
+<script>
+  async function checkAuth() {
+    const response = await fetch('/api/check_auth.php', { credentials: 'same-origin' });
+    const result = await response.json();
+    if (!result.isLoggedIn) window.location.href = '/login.html';
+  }
+  checkAuth();
+</script>
+```
+
+> Рекомендуется использовать **абсолютные пути** (`/api/...`), если страницы лежат в разных каталогах.
+
+---
+
+## Шаг 4. Настройка доступа по алиасам
+Доступ контролируется через поля в `users`:
+- `ok5`, `o7`, `o10m`, `o10a`, `webp`
+
+Пример выдачи доступа:
+```sql
+UPDATE users SET ok5=1, o7=1 WHERE username='ivan';
+```
+
+Если доступа нет → при логине будет ошибка `Нет доступа к сайту`.
+
+---
+
+## Шаг 5. Массовая загрузка пользователей
+1) Создайте файл `users.txt` в корне проекта  
+   Формат: **по одному логину в строке**
+2) Запустите:
+```
+php import_users.php
+```
+3) Результат: `users_with_passwords.txt` (формат `login:password`)
+
+---
+
+## Как применить к любому сайту
+1) Скопируйте папки `api/`, `js/`, `css/` в корень сайта.  
+2) Создайте `login.html` и добавьте `<meta name="site-alias" content="...">`.  
+3) На защищённых страницах используйте проверку `check_auth.php`.  
+4) Добавьте пользователей в таблицу `users` и выдайте доступ по нужному алиасу.
+
+---
+
+## Частые проблемы
+**Ошибка “Метод не поддерживается”**  
+→ Запрос идёт GET‑ом. Проверьте, что `auth.js` подключён и форма имеет `id="loginForm"`.
+
+**Ошибка “Не указан сайт”**  
+→ Нет `site-alias` в `login.html` или не обновлён `auth.js`.
+
+**Ошибка “Could not find driver”**  
+→ В PHP не включён `pdo_mysql`.
+
+---
+
+Если нужно расширить список алиасов — добавьте колонку в БД и внесите её в список в `api/login.php`.