Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
enesify merged 1 commit into from
Apr 20, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .cursor/skills/taskwal-project-docs/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
/target
**/*.rs.bk
.DS_Store
.docgen_pillow/
43 changes: 35 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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+.
Expand All @@ -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

Expand Down
28 changes: 23 additions & 5 deletions docs/KULLANIM.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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.**

Expand All @@ -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>`

Expand All @@ -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.
Expand Down Expand Up @@ -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ı):**


Expand All @@ -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ı:**

Expand All @@ -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`

Expand Down
Loading
Loading