diff --git a/README.md b/README.md
index af7f593..adb4563 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,146 @@
-# Linux Auth
\ No newline at end of file
+# Linux Auth — Приложение аутентификации на Linux
+
+Linux Auth — консольное приложение для аутентификации пользователей на Linux (Debian 12) с использованием локальной SQLite базы данных.  
+Поддерживает:  
+
+- Ввод логина и пароля с маской  
+- Ограничение числа попыток входа  
+- Сброс формы  
+- Настраиваемые параметры через TOML  
+- CLI утилиты для инициализации и добавления пользователей  
+
+## Настройка окружения
+
+1. Установить Go, gcc и SQLite dev на Debian 12:
+
+```bash
+bash scripts/config.sh
+```
+
+- Обновляет репозитории
+
+- Устанавливает Go, GCC, SQLite
+
+- Подготавливает зависимости Go проекта
+
+## Сборка проекта
+
+Скрипт ```build.sh``` собирает все бинарники:
+
+- Основное приложение: authapp
+
+- Инициализация пользователей: init_users
+
+- CLI утилита для добавления пользователей: add_user
+
+```
+bash scripts/build.sh
+```
+
+- CGO включён для работы с go-sqlite3
+
+- Создаёт release и debug версии (build/release/, build/debug/)
+
+## Инициализация пользователей
+
+Перед первым запуском необходимо создать начальных пользователей:
+
+```
+./build/release/init_users
+```
+
+- Создаёт пользователей из скрипта (admin, user1)
+
+- Пароли автоматически хешируются через SHA-256
+
+## Добавление новых пользователей
+
+Используйте утилиту ```add_user``` для добавления пользователя без изменения кода:
+
+```
+./build/release/add_user -username USER -password PASS
+```
+
+Пример:
+```
+./build/release/add_user -username test -password 1234
+```
+
+## Запуск основного приложения
+```
+bash scripts/run.sh
+```
+
+- Запускает authapp с конфигурацией configs/config.toml
+
+- Поддерживает ввод логина и пароля с маской
+
+- Предусмотрена логика ограничения попыток и блокировки пользователя
+
+- Позволяет сбросить форму и повторить попытку
+
+Пример работы:
+```
+=== AuthApp ===
+Логин: admin
+Пароль: ******
+Доступ разрешён. Добро пожаловать, admin!
+```
+
+## Конфигурация (configs/config.toml)
+
+Пример:
+```
+[app]
+name = "AuthApp"
+max_login_attempts = 3
+lock_timeout_sec = 300
+
+[database]
+type = "sqlite"
+path = "./data/users.db"
+
+[security]
+password_hash = "sha256"
+
+[ui]
+show_welcome = true
+```
+
+- ```max_login_attempts``` — количество попыток перед блокировкой
+
+- ```lock_timeout_sec``` — время блокировки пользователя (сек)
+
+- ```password_hash``` — алгоритм хеширования пароля
+
+- ```show_welcome``` — вывод приветствия при старте
+
+## Особенности и назначение утилит
+
+```authapp```: Основное приложение для аутентификации пользователей
+```init_users```:Создаёт начальных пользователей в базе SQLite (admin, user1)
+```add_user```: CLI утилита для добавления новых пользователей без перекомпиляции
+
+## Проверка работы
+
+Собрать проект: 
+```
+bash scripts/build.sh
+```
+
+Инициализировать пользователей: 
+```
+./build/release/init_users
+```
+
+Запустить приложение: 
+```
+bash scripts/run.sh
+```
+
+Протестировать успешный и неуспешный вход
+
+Добавить нового пользователя: 
+```
+./build/release/add_user -username test -password 1234
+```
\ No newline at end of file