diff --git a/README.md b/README.md
index d8ad002..cd03c94 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,109 @@
 # mysitenews
 
+Графическое приложение на Qt для заполнения таблицы `random_data` в PostgreSQL.
+
+При запуске открывается окно подключения к БД. После успешного подключения
+появляется форма добавления записи с полями `name` и `text`, а также счётчик
+текущего количества записей в таблице.
+
+## Возможности
+
+- подключение к PostgreSQL (host, port, user, password);
+- сохранение последней успешной конфигурации подключения;
+- отображение количества записей в `public.random_data`;
+- добавление записей (`name`, `text`);
+- показ ошибки при неудачном подключении.
+
+## Требования
+
+- CMake 3.16+;
+- компилятор с поддержкой C++17;
+- Qt 5 или Qt 6 (модули `Widgets` и `Sql`);
+- драйвер PostgreSQL для Qt (`QPSQL`);
+- сервер PostgreSQL.
+
+Проверить наличие драйвера можно так:
+
+```bash
+ls /usr/lib/x86_64-linux-gnu/qt6/plugins/sqldrivers/
+```
+
+В каталоге должен быть `libqsqlpsql.so` (для Qt 5 — `libqsqlpsql.so` в
+соответствующем каталоге плагинов). В Debian/Ubuntu драйвер ставится пакетом
+`libqt6sql6-psql` (для Qt 5 — `libqt5sql5-psql`).
+
+## Сборка и запуск
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+./build/mysitenews
+```
+
+При сборке из Qt Creator используется каталог `build/Desktop-Debug`.
+
+## База данных
+
+Приложение обращается к БД `cards` и таблице `public.random_data`.
+Ожидаемая структура таблицы:
+
+```sql
+CREATE TABLE public.random_data (
+    id         serial PRIMARY KEY,
+    name       varchar(100) NOT NULL,
+    text       text NOT NULL,
+    description text,
+    created_at timestamp DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### Права пользователя
+
+Пользователю БД нужны права на таблицу и на последовательность `id`:
+
+```sql
+GRANT SELECT, INSERT ON public.random_data TO cards_user;
+GRANT USAGE, SELECT ON SEQUENCE public.random_data_id_seq TO cards_user;
+```
+
+Без прав на последовательность вставка завершится ошибкой
+`permission denied for sequence random_data_id_seq`.
+
+## Использование
+
+1. Запустите приложение.
+2. Введите адрес сервера, порт (по умолчанию `5432`), имя пользователя и пароль.
+3. Нажмите **OK**. При ошибке подключения будет показано сообщение.
+4. Заполните поля `name` и `text` и нажмите **ADD**.
+
+Поле `text` сохраняется как HTML (`QTextEdit::toHtml()`). Оба поля обязательны.
+Длина `name` ограничена таблицей — 100 символов.
+
+## Конфигурация
+
+После успешного подключения параметры сохраняются через `QSettings`
+(`QSettings("mysitenews", "mysitenews")`). В Linux файл находится по пути:
+
+```
+~/.config/mysitenews/mysitenews.conf
+```
+
+Сохраняются `db/host`, `db/port`, `db/database`, `db/user`, `db/password`.
+При следующем запуске поля формы заполняются этими значениями.
+
+**Внимание:** пароль хранится в открытом виде. Не используйте этот способ
+для продакшн-окружений; предпочтительнее `~/.pgpass` или переменные окружения.
+
+## Структура проекта
+
+| Файл | Назначение |
+| --- | --- |
+| `main.cpp` | точка входа, связывает окно авторизации и рабочее окно |
+| `auth.h` / `auth.cpp` | окно подключения к БД, сохранение конфигурации |
+| `widget.h` / `widget.cpp` | форма добавления записей и подсчёт количества |
+| `CMakeLists.txt` | конфигурация сборки |
+
+## Лицензия
+
+Проект распространяется под GNU General Public License v3. Подробности — в
+файле [LICENSE](LICENSE).