From 7d4ef2203a783e6aeb86cbf6e23010e8a9c34b54 Mon Sep 17 00:00:00 2001
From: baturns <enesbatur@protonmail.com>
Date: Wed, 22 Apr 2026 00:21:15 +0300
Subject: [PATCH] docs(readme): expand overview for BAT-10

Add purpose, differentiation, use cases, and feature summary; include
stats screenshot; document install via cargo install --path; align
TASKWAL_DIR wording with USAGE for Windows.

Made-with: Cursor
---
 README.md | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f555f43..283c9bd 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,58 @@
 # TaskWAL (`tw`)
 
-Local-first task tracker using an append-only JSONL write-ahead log (`~/.taskwal/wal.log` on Unix, `%USERPROFILE%\.taskwal\wal.log` on Windows).
+**TaskWAL** is a **local-first**, Kanban-style task tracker for the terminal. Every change is appended to a **write-ahead log** (JSON lines on disk); the tool **replays** that log to build your **Todo**, **Doing**, and **Done** columns—no server, no account, no cloud sync.
 
 ![TaskWAL board (TUI)](docs/images/board.png)
 
-## Build
+The default data file is `wal.log` under `~/.taskwal/` on Unix and `%USERPROFILE%\.taskwal\` on Windows.
+
+![TaskWAL stats (text output)](docs/images/stats.png)
+
+## Why TaskWAL?
+
+- **Offline and yours:** Tasks live on your machine. There is no hosted backend or login—just a directory and a log file.
+- **Transparent history:** The WAL is **append-only**. Deletes and edits are **events** in the log, not silent overwrites. Inspect or script against the stream with `tw log`.
+- **Terminal-native:** Small CLI for day-to-day moves, plus an optional full-screen **board** (`tw board`) with `ratatui` for keyboard-driven review.
+- **Daily focus:** The **Done** column defaults to what you finished **today** (local calendar date), so `tw ls` and `tw board` stay oriented around “what I closed this day” unless you widen the view (`--all`, `--date`).
+
+## Use cases
+
+- **Personal inbox + WIP limits:** Capture work in Todo, pull a few items into Doing, close them to Done when finished.
+- **Developer workflow:** Stay in the shell next to git and builds; no context switch to a web app.
+- **Travel or locked-down networks:** Full functionality without connectivity.
+- **Automation and backup:** JSONL lines are easy to grep, pipe, or archive; replay semantics stay predictable.
+
+## Features at a glance
+
+- Stable **ULID** task identifiers (prefix matching when unique)
+- **Tags**, **notes**, rename, column moves, and **append-only** removal
+- **`tw ls`** (columns in the terminal) and **`tw board`** (interactive TUI) with the same view flags
+- **`tw stats`** for aggregate counts and **`tw log`** for raw WAL output
+- Optional **`TASKWAL_DIR`** to relocate the data directory
+
+For every subcommand, flag, and TUI key, see the full guides: **[docs/USAGE.md](docs/USAGE.md)** (English) and **[docs/KULLANIM.md](docs/KULLANIM.md)** (Türkçe).
+
+## Installation
 
 Requires [Rust](https://rustup.rs/) 1.70+.
 
+**Build** (binary at `target/release/tw`):
+
 ```bash
 cargo build --release
-# binary: target/release/tw
 ```
 
+**Install** into Cargo’s bin directory (e.g. `~/.cargo/bin/tw` on Unix):
+
+```bash
+cargo install --path . --force
+```
+
+Re-run `cargo install` after pulling updates. If `cargo` is not on your `PATH`, see [docs/USAGE.md](docs/USAGE.md) for shell setup hints.
+
 ## Cross-platform
 
-- **macOS / Linux / Windows:** 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).
 
 ## Documentation
@@ -66,7 +103,7 @@ tw log              # raw WAL JSON lines
 
 ## 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 (tests and custom locations). WAL file: `$TASKWAL_DIR/wal.log` on Unix; `%TASKWAL_DIR%\wal.log` on Windows.
 
 ## License