Merge pull request #1 from enesify/feature/bat-8-update-readme-file

docs(BAT-8): refresh README, add USAGE, screenshots, and docs skill

Author: enesify

.cursor/skills/taskwal-project-docs/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: taskwal-project-docs
+description: Maintains TaskWAL user-facing documentation in English and Turkish and TUI screenshots when the CLI, board, or on-disk layout changes. Use when editing src/, adding or changing tw subcommands or TUI behavior, updating README or docs, or when the user asks to sync or refresh project documentation.
+---
+
+# TaskWAL project documentation
+
+## Files to keep aligned
+
+| Asset | Role |
+| ----- | ---- |
+| [README.md](../../../README.md) | Short overview, quick reference, links to full guides |
+| [docs/USAGE.md](../../../docs/USAGE.md) | Full English user guide |
+| [docs/KULLANIM.md](../../../docs/KULLANIM.md) | Full Turkish user guide (mirror of USAGE) |
+| [docs/images/](../../../docs/images/) | `board.png`, `stats.png` for README and guides |
+
+## When to update
+
+1. **CLI change** (`src/main.rs`, `src/commands.rs`): reflect new/changed subcommands, flags, or id rules in README (table or examples), then **both** USAGE and KULLANIM.
+2. **TUI change** (`src/ui/`): update keyboard tables, command-line (`:`) behavior, and **refresh screenshots** if the visible layout or colors change materially.
+3. **Data paths / env**: keep README, USAGE, and KULLANIM consistent (`TASKWAL_DIR`, WAL path).
+4. **Analytics text** (`tw stats` output vs stats screen): keep USAGE/KULLANIM descriptions in sync with `src/` and [src/ui/stats.rs](../../../src/ui/stats.rs).
+
+## Screenshots
+
+- Regenerate stylized PNGs after meaningful UI changes:
+
+  ```bash
+  pip install --target .docgen_pillow pillow   # once; .docgen_pillow is gitignored
+  PYTHONPATH=.docgen_pillow python3 scripts/generate_doc_screenshots.py
+  ```
+
+- Commit updated files under `docs/images/`. The script draws an approximation of the TUI; replace with real terminal captures if you need pixel-perfect fidelity.
+
+## Checklist
+
+- [ ] README links to USAGE and KULLANIM
+- [ ] English and Turkish guides describe the same commands and keys
+- [ ] Image paths in markdown use `images/...` from `docs/*.md` and `docs/images/...` from README root
+- [ ] No drive-by edits to unrelated markdown

.gitignore

@@ -1,3 +1,4 @@
 /target
 **/*.rs.bk
 .DS_Store
+.docgen_pillow/

README.md

@@ -2,6 +2,8 @@
 
 Local-first task tracker using an append-only JSONL write-ahead log (`~/.taskwal/wal.log` on Unix, `%USERPROFILE%\.taskwal\wal.log` on Windows).
 
+![TaskWAL board (TUI)](docs/images/board.png)
+
 ## Build
 
 Requires [Rust](https://rustup.rs/) 1.70+.
@@ -13,33 +15,58 @@ cargo build --release
 
 ## Cross-platform
 
-- **macOS / Linux / Windows**: the same codebase; `crossterm` + `ratatui` work on common terminals.
+- **macOS / Linux / Windows:** same codebase; `crossterm` + `ratatui` work on common terminals.
 - Build on each OS you ship for, or use cross-compilation (e.g. `cargo build --release --target x86_64-pc-windows-gnu` from a configured toolchain).
 
-## Usage
+## Documentation
+
+- **English (full guide):** [docs/USAGE.md](docs/USAGE.md)
+- **Türkçe (tam kılavuz):** [docs/KULLANIM.md](docs/KULLANIM.md)
 
-Türkçe ayrıntılı kılavuz: [docs/KULLANIM.md](docs/KULLANIM.md).
+## Usage (quick reference)
 
 ```bash
 tw add "Write API" --tag backend
-tw start 01HX…      # prefix match if unique
+tw start 01HX…       # prefix match if unique
 tw done 01HX…
+tw back 01HX…       # one step back: Done→Doing or Doing→Todo
+tw edit 01HX… "New title"
+tw note 01HX… "Blocked on API"
+tw rm 01HX…
+
 tw ls               # Todo/Doing: all open tasks; Done: today (local) by default
 tw ls --all         # Done column: all completed tasks
 tw ls --date 2026-04-01
-tw stats
-tw board
+
+tw board            # interactive Kanban TUI (same view flags as ls)
+tw stats            # aggregate stats (all-time), text output
 tw log              # raw WAL JSON lines
 ```
 
+### Commands
+
+| Command | Purpose |
+|--------|---------|
+| `add <title>` | New task (Todo); `--tag` / `-t` comma-separated tags |
+| `start <id>` | Move to Doing |
+| `done <id>` | Move to Done |
+| `back <id>` | Move one column backward |
+| `edit <id> <title>` | Rename task |
+| `note <id> <text>` | Append a note |
+| `rm <id>` | Remove task (append-only delete event in WAL) |
+| `ls` | Print board columns for the current view (`--all`, `--date`) |
+| `board` | Full-screen TUI board (`--all`, `--date`) |
+| `stats` | Print statistics |
+| `log` | Dump WAL as JSON lines |
+
 ### Daily view rules
 
-- **Todo / Doing:** every open task is listed (carry-over across days; nothing unfinished disappears from the default view).
+- **Todo / Doing:** every open task is listed (carry-over across days).
 - **Done:** by default, tasks completed on **today’s local calendar date**. Use `--all` or `--date` to widen.
 
 ## Environment
 
-- **`TASKWAL_DIR`**: override the data directory (used by tests and for custom locations). WAL file: `$TASKWAL_DIR/wal.log`.
+- **`TASKWAL_DIR`:** override the data directory (used by tests and for custom locations). WAL file: `$TASKWAL_DIR/wal.log`.
 
 ## License
 

docs/KULLANIM.md

@@ -2,6 +2,8 @@
 
 Bu belge, projenin **mevcut sürümü** için komut satırı ve TUI kullanımını anlatır.
 
+İngilizce aynı seviyede kılavuz: [USAGE.md](USAGE.md).
+
 ## Uygulama nedir?
 
 TaskWAL, görevlerinizi **yerel bilgisayarınızda** tutan bir iş takip aracıdır. Tüm değişiklikler, silme dahil, **append-only** bir günlük dosyasına (WAL) yazılır; uygulama bu dosyayı okuyup güncel pano (Todo / Doing / Done) durumunu **yeniden oynatarak** (replay) üretir.
@@ -17,7 +19,7 @@ TaskWAL, görevlerinizi **yerel bilgisayarınızda** tutan bir iş takip aracıd
 
 Özel konum için ortam değişkeni:
 
-- `**TASKWAL_DIR`**: Veri klasörü. WAL yolu: `$TASKWAL_DIR/wal.log` (Windows’ta `%TASKWAL_DIR%\wal.log`).
+- **`TASKWAL_DIR`**: Veri klasörü. WAL yolu: `$TASKWAL_DIR/wal.log` (Windows’ta `%TASKWAL_DIR%\wal.log`).
 
 ## Kurulum ve `tw` komutu
 
@@ -51,8 +53,8 @@ tw <komut> --help
 **Done** kolonu:
 
 - **Varsayılan:** Yerel saat diliminde **seçilen takvim gününde** tamamlanan görevler. Seçim belirtilmezse gün = **bugün**.
-- `**--all`:** Tamamlanan **tüm** görevler (geçmiş dahil); Todo/Doing yine tüm açık işlerdir.
-- `**--date YYYY-MM-DD`:** Done kolonu yalnızca o yerel güne düşen tamamlamalara göre süzülür.
+- **`--all`:** Tamamlanan **tüm** görevler (geçmiş dahil); Todo/Doing yine tüm açık işlerdir.
+- **`--date YYYY-MM-DD`:** Done kolonu yalnızca o yerel güne düşen tamamlamalara göre süzülür.
 
 `--all` ile `--date` **birlikte kullanılamaz.**
 
@@ -69,7 +71,7 @@ tw add "API taslağını yaz"
 tw add "Review" --tag backend,urgent
 ```
 
-- `**--tag` / `-t`:** Virgülle ayrılmış etiket listesi.
+- **`--tag` / `-t`:** Virgülle ayrılmış etiket listesi.
 
 ### `tw start <id>`
 
@@ -79,6 +81,10 @@ Görevi **Doing** kolonuna taşır. İlk kez Doing’e geçişte “başlangıç
 
 Görevi **Done** kolonuna taşır; tamamlanma zamanı kaydedilir.
 
+### `tw back <id>`
+
+Görevi **bir kolon geri** alır: Done → Doing → Todo (uygun olduğunda).
+
 ### `tw edit <id> <yeni başlık>`
 
 Başlığı günceller.
@@ -115,6 +121,10 @@ tw board --all
 tw board --date 2026-04-01
 ```
 
+![Board TUI](images/board.png)
+
+**Seçili kolon** kenarlığı vurgulanır. **Seçili satır** açık ve koyu temalarda okunaklı görünsün diye **turuncu** arka plan ve kalın yazı ile gösterilir.
+
 **Klavye (board ekranı):**
 
 
@@ -124,10 +134,14 @@ tw board --date 2026-04-01
 | `↑` / `↓` | Seçili kolonda satır                                                   |
 | `s`       | Seçili görevi Doing’e al                                               |
 | `d`       | Seçili görevi Done’a al                                                |
+| `b`       | Seçili görevi bir kolon geri al (Done→Doing→Todo)                      |
 | `a`       | Done kolonu: bugünün tamamlananları ↔ tüm tamamlananlar arasında geçiş |
 | `g`       | İstatistik ekranına geç                                                |
 | `q`       | Çıkış                                                                  |
+| `:`       | Komut satırı (aşağıya bakın)                                           |
+| `Esc`     | Komut satırında iptal                                                  |
 
+**Komut satırı (`:`):** Örneğin `add Yeni görev` veya `start 01ABC123` yazın (`tw` öneki isteğe bağlı). **Enter** ile çalıştırın, **Esc** ile iptal.
 
 **İstatistik ekranı:**
 
@@ -149,7 +163,11 @@ Yeni görev **CLI** ile eklenir: `tw add "…"`.
 - Ortalama **lead** süresi (gün): oluşturma → tamamlanma  
 - Aktif gün başına düşen ortalama tamamlanan iş  
 - Yerel günlere göre **streak** (ardışık günler)  
-- Son günlerin kısa dökümü
+- Son günlerin kısa dökümü  
+
+`tw board` içindeki tam ekran istatistik görünümü:
+
+![İstatistik ekranı](images/stats.png)
 
 ### `tw log`