diff --git a/README.md b/README.md
index e4ddcbc..c3a1ae9 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,44 @@
-# PieVR
+# pievr
 
-## Database Schema & Core Concepts
-- **Storage:** SQLite (`storage/` directory, ignored in `.gitignore`).
-- **Tables:**
-  - `questions`: stores core question data (`id`, `type`, `question_text`, `payload` as JSON, `active`, `last_asked_at`, `streak`, `times_asked`, `times_correct`, `created_at`).
-  - `tags`: tags for granular and cross-cutting topic selection (`id`, `name`).
-  - `question_tags`: many-to-many relationship between questions and tags.
-- **Priority & Spaced Repetition:** No hardcoded calendar intervals. Priorities and scheduling metrics are stored as raw counters (`streak`, `times_asked`, `last_asked_at`) in the database, while complex priority/decay formulas are calculated dynamically on the fly in Go.
+Telegram bot for technical interview preparation using flashcards and smart prioritized spaced repetition.
+
+## Overview
+
+**pievr** is a personal Telegram bot designed to streamline technical interview preparation. Instead of standard rigid calendar intervals (like traditional spaced repetition apps), it uses a dynamic priority queue system based on recent performance and time elapsed.
+
+## Core Concepts & Architecture
+
+### 1. Dynamic Priority System
+- **No Calendar Dates:** Spaced repetition doesn't rely on strict dates.
+- **Priority Calculation:** Priorities are calculated dynamically in Go code based on:
+  - Time elapsed since the question was last asked (older unseen/unasked questions rise in priority).
+  - Success streak (`streak`): successful answers decrease priority, while mistakes increase it sharply.
+- **New Questions Mix:** Unseen questions (`times_asked = 0`) have no priority and are smoothly mixed into study sessions in a configurable proportion alongside prioritized review questions.
+
+### 2. Flexible Tagging
+- Questions support multiple tags (many-to-many relationship) to allow granular topic filtering and cross-cutting selections (e.g., combining `go` and `concurrency`).
+
+### 3. LLM Integration (Gemini API)
+- **Configurable BaseURL:** Configurable via environment or config file to support proxies or custom endpoints.
+- **Background Generation:** Background workers passively generate questions in bulk (e.g., in JSON batches) to maintain a target buffer of questions.
+- **Self-Validation:** When questions are generated, the LLM validates them by answering its own questions before they enter the active pool.
+- **Bot Interaction:** The bot can operate as an AI assistant with tool-use capabilities to query the database, manage tags, and fetch questions.
+
+### 4. Database Schema (SQLite)
+Stored locally in `storage/` (excluded via `.gitignore`):
+- **`questions`**: Stores core content (`type`, `question_text`, `payload` as JSON, `active`, `last_asked_at`, `streak`, `times_asked`, `times_correct`, `created_at`).
+- **`tags`**: Tag definitions (`name`).
+- **`question_tags`**: Many-to-many mapping between questions and tags.
+
+## Project Structure
+- `cmd/` — Application entrypoints
+- `internal/` — Private application code (domain, services, storage, bot handlers)
+- `prompts/` — Prompt templates embedded via `go:embed`
+- `storage/` — SQLite database files and schemas
+- `docs/` — Documentation and architectural notes
+
+## Development Workflow
+1. Sync with `master` before starting any new feature branch.
+2. Implement features or fixes in dedicated feature branches (`feature/...` or `fix/...`).
+3. Rebase against `master` before pushing.
+4. Open a Pull Request for review and merge.