fix: rename to pievr and write comprehensive README (#3)

Fixes capitalization to pievr and replaces README with a full, comprehensive documentation of project architecture, concepts, and roadmap.

Co-authored-by: StirGpea <stir@openclaw.local>
Reviewed-on: #3
Co-authored-by: stirgpea <stjrgpea@wivziv.com>
Co-committed-by: stirgpea <stjrgpea@wivziv.com>

.gitignore

@@ -0,0 +1,18 @@
+/bin/
+/vendor/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+/storage/*.db
+/storage/*.db-journal
+.env
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+

README.md

@@ -1 +1,44 @@
-# PieVR
+# pievr
+
+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.

internal/storage/schema.sql

@@ -0,0 +1,23 @@
+CREATE TABLE IF NOT EXISTS questions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    type TEXT NOT NULL,
+    question_text TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    active BOOLEAN DEFAULT 1,
+    last_asked_at DATETIME,
+    streak INTEGER DEFAULT 0,
+    times_asked INTEGER DEFAULT 0,
+    times_correct INTEGER DEFAULT 0,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS tags (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT UNIQUE NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS question_tags (
+    question_id INTEGER REFERENCES questions(id) ON DELETE CASCADE,
+    tag_id INTEGER REFERENCES tags(id) ON DELETE CASCADE,
+    PRIMARY KEY (question_id, tag_id)
+);