diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b87117f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# WorkTime Bot
+
+A single-user Telegram time-tracking bot. Clock in/out, toggle remote/onsite, mark day off, get daily reports, and export monthly Excel reports.
+
+## Quick Start
+
+```bash
+cp .env.example .env
+# edit .env — set BOT_TOKEN and BOT_ALLOWED_USERS
+docker compose up -d
+```
+
+### Environment Variables
+
+| Variable            | Purpose                                                     |
+| ------------------- | ----------------------------------------------------------- |
+| `BOT_TOKEN`         | Telegram Bot API token (required)                           |
+| `BOT_ALLOWED_USERS` | Comma-separated Telegram user IDs (empty = allow all)       |
+| `HTTPS_PROXY`       | Outbound proxy for Telegram API (e.g. `http://proxy:10808`) |
+| `DB_PATH`           | Path to SQLite database (default: `db.sqlite3`)             |
+| `BOT_WEBHOOK_URL`   | Set for webhook mode (omit for polling)                     |
+
+## Usage
+
+**Persistent reply keyboard** at the bottom: `Clock In` / `Clock Out`
+
+**Inline menu** on `/start`:
+
+- Clock In / Clock Out
+- Report / Export
+- Toggle Remote/Onsite / Day Off
+
+### Commands
+
+| Command                    | Action                       |
+| -------------------------- | ---------------------------- |
+| `/start`                   | Show inline menu             |
+| `Clock In` or `/clockin`   | Record clock-in              |
+| `Clock Out` or `/clockout` | Record clock-out             |
+| `/remote`                  | Toggle remote/onsite mode    |
+| `/report`                  | Today's work & break summary |
+| `/export`                  | Monthly `.xlsx` report       |
+| `/dayoff`                  | Toggle today as day off      |
+
+Daily report is sent automatically at 23:00.
+
+## How Break Time Works
+
+The gap between a clock-out and the next clock-in is counted as break:
+
+```
+09:00 Clock In     → work starts
+12:00 Clock Out    → work: 3h, break starts
+13:00 Clock In     → break: 1h, work resumes
+17:00 Clock Out    → work: 4h
+                    total: 7h work, 1h break
+```
+
+## Project Structure
+
+```
+├── cmd/bot/           main.go, webhook.go
+├── internal/
+│   ├── bot/           handlers, export, totals
+│   └── db/            SQLite store
+├── db/schema.sql      Database schema
+├── Dockerfile
+└── docker-compose.yml
+```
+
+## Build
+
+```bash
+docker compose up -d --build
+```