Update readme

README.md

@@ -1,71 +1,92 @@
 # wat
 
-`wat` is a terminal UI wrapper around [Watson](https://tailordev.github.io/Watson/) that lets you browse and launch timers via a keyboard-driven interface.
+`wat` is a TUI interface for [Watson](https://tailordev.github.io/Watson/)
+
+![wat in tarnation](./assets/wat.png "wat")
 
 ---
 
-## Goals & Workflow
+## Overview and screenshots
-- Never type `watson start ...` again—start/stop timers with `Enter`.
-- Maintain three panes simultaneously:
-  1. **Permanent Items** – curated recurring tasks defined in `state.yaml`.
-  2. **Recurring Items** – semi-regular tasks you hop between.
-  3. **Ad-Hoc Items** – last ~20 one-offs, automatically tracked.
-- Highlight clearly when a timer is running (bold green) vs idle (yellow).
-- Keep everything human-editable: YAML state/config under `~/.config/wat`.
 
----
+### Main Interface
 
-## Key Features
+Wat's main screen consists of 3 groupings of tasks, each of which is optional and can be disabled via settings. The idea here is to provide an interface to toggle what task you are currently working on, with lots of options for editing, annotating, and reporting on that time spent later. When you track time on a task, it will show up in the `view` page (v), which is analogous to `watson log`.
-- **Navigation**: `j/k` or arrows move within a pane; `h/l`, arrows, or `Ctrl+n/p` switch panes; `q` quits.
-- **Timer control**: `Enter` toggles the selected item. Starting a different item automatically stops the previous timer.
-- **New entries**: `n` launches a modal (project + optional tag). Item is added to the current pane.
-- **Project reassignment**: `p` opens a modal to change the tags for the selected item.
-- **Log viewing**: `v` opens Watson's log viewer with daily/weekly/monthly views. Use `d`/`w`/`m` to switch periods, `g` to toggle grouping by date/project, `j`/`k` to select entries, `e` to edit, `x` to delete, `c` to copy to clipboard.
-- **Deletion**: `d` removes the selected entry; no noisy status message.
-- **Config editing**:
-  - `Ctrl+e` edits task config (`state.yaml`).
-  - `c` edits app config (`config.yaml`).
-- **Help overlays**: `?` for help, `c` inside help for config instructions.
 
----
+![Toggling a task in the wat interface](./assets/0-track-time.webm "time-tracking")
 
-## Files & Persistence
+The three available categories of task are `Permanent Items`, for tasks that will likely be part of your workflow for the forseeable future, `Recurring Items` for scheduled weekly meetings or tasks which come and go, and `Ad-Hoc Items` for things that will not recur. Eventually, I plan to make the `Ad-Hoc` section display items in reverse order, and remove ones beyond 10 items. This will not delete past time entries for those items.
-```
-~/.config/wat/
-├─ state.yaml    # serialized AppState (items, selections, active timer)
-└─ config.yaml   # UI/app options (help hints, allowed projects, etc.)
-```
-- `state.yaml` and `config.yaml` use `serde_yaml` for readability.
 
----
+### The 'View Entries' Interface
+
+Pressing `v` on the main interface will take the user to the interface for viewing actual time entries, as created from the main interface. The default view is the 'day' view, which shows your entries for the current day. You can press `g` to `group` or `ungroup` your tasks by project. You can also navigate using `h,j,k,l` between entries, entries grouped by project, grouped by day, or all entries. You can press `y` to copy the selection to your clipboard.
+
+![Navigating the daily view](./assets/2-daily-view-and-proj-selection.webm "daily-view")
+
+### Weekly and Monthly View
+
+When in the `view` interface, you can switch to a weekly or monthly view using `w` or `m`. Grouping works the same way in these views as in the `daily` view. You can also press 'r' to reverse the order of the days in the display.
+
+![Navigating by week or month](./assets/3-weekly-view-and-day-selection.webm "week-and-month-view")
+
+### Individual entry editing
+
+When an entry is selected, you can press `e` to edit the full `watson edit` configuration for your selected entry in your chosen `$EDITOR`
+
+![Editing a time entry](./assets/4-individual-editing.webm "editing-an-entry")
+
+### Backfill gap and overlap correction
+
+The `ungrouped` view can also be used as an error resolution and quick edit page using the `b` (backfill) key. Here, `backfill` roughly translates to 'take the current entry and make its start time equal to the stop time of the previous entry'. The `b` key will do nothing if the entry is the first entry of the day.
+
+In the ungrouped view, entries are chronological. Entries with gaps betweent them are denoted by a blank line with three dashes (---). Entries which overlap with the previous entry (which is likely an error and should never happen) are colored yellow. In both cases, pressing `b` will resolve the issue. (You may want gaps in certain cases such as lunch breaks or short breaks, so don't do this without thinking about the context)
+
+![Backfilling Overlapped or Disjointed Entries](./assets/5-backfill-gap-and-overlap-correction.webm "backfilling")
+
+### Rounding
+
+The time tracking software I use at work only accepts logging for tasks and projects in 15m intervals, so I included a hotkey `R` to automatically round tasks to the nearest 15m. This reduces a little burden when reporting time, but keep in mind that if you get unlucky and many entries are rounded down you may end up under-reporting. Keep this in mind and always sanity check your time.
+
+![Rounding](./assets/6-rounding.webm "rounding")
+
+### Annotation
+
+Watson actually doesn't include any options for annotating time entries by default! However, it does allow you to technically assign multiple 'tags' to an entry. In `wat`, we've been treating the `tag` as the name of the time entry more-or-less. When an entry is completed, you can navigate to the view page and press `a` to add a second tag if you want to be more specific about that particular entry. In practice, it looks just fine in the final reporting.
 
 ## Building & Running
 ```
 cargo build
 cargo run
 ```
-Requires `watson` on your `PATH` with a configured workspace.
+Requires `watson` on your `PATH` with a configured workspace. The application will automatically create the necessary `~/.config/watson` directory structure on first run if it doesn't exist.
+
+Otherwise, just download the latest release for a relatively-stable binary.
 
----
 
 ## Keybindings (Summary)
-| Keys | Action |
+| Keys              | Action                                                            |
-|------|--------|
+|-------------------|-------------------------------------------------------------------|
-| `j` / `k`, arrows | Move selection |
+| `j` / `k`, arrows | Move selection                                                    |
-| `h` / `l`, arrows, `Ctrl+n` / `Ctrl+p` | Switch panes |
+| `Enter`           | Start/stop timer                                                  |
-| `Enter` | Start/stop timer |
+| `n`               | New entry (project + optional tag)                                |
-| `n` | New entry (project + optional tag) |
+| `p`               | Reassign project for selected item                                |
-| `p` | Reassign tag for selected item |
+| `v`               | View Watson log (d/w/m period, g group, e edit, x delete, y copy) |
-| `v` | View Watson log (d/w/m period, g group, e edit, x delete, c copy) |
+| `x`               | Delete entry                                                      |
-| `d` | Delete entry |
+| `Ctrl+e`          | Edit task config (`state.yaml`)                                   |
-| `Ctrl+e` | Edit task config (`state.yaml`) |
+| `c`               | Edit app config (`config.yaml`) or show config help               |
-| `c` | Edit app config (`config.yaml`) or show config help |
+| `?`               | Help screen                                                       |
-| `?` | Help screen |
+| `q`               | Quit                                                              |
-| `q` | Quit |
 
----
+## TODO 
 
-## TODO / Follow-ups
+### Architecture
-- Add inline editing of permanent/recurring items instead of dropping to `$EDITOR`.
+Eventually I need to refactor this whole thing, which was mostly written by LLMs. I want to make the underlying data structure for the view display much more solidly defined so that it is more extensible. It should be stored in some kind of nested structure which is aware of ordering as well as grouping and can be dynamically (and optimistically) updated without refreshing the UI when appropriate. Once that is resolved, I can focus on the following upgrades:
-- Consider status messaging for critical errors (currently unused after deleting the delete confirmation).
+
-- Add tests/snapshots for UI components.
+- Adding a `/` command to narrow down entries by fuzzy searching
+- Perhaps having a universal interface for entries going back more than a month
+- An option for people who don't want to copy / paste their hours into another interface
+- Actually ordering the ad-hoc section by most recently used one-offs, and implementing a good way to auto-prune that list
+- Print the time totals at the project-level for each day
+- Some kind of API for the real weirdos out there (sean)
+
+### Terminal interface
+Another big reason I need to drill down and rewrite this with human hands is the difference between the mac and linux terminal handling. I need to learn to use ratatui well enough to understand how to develop for both platforms at once. I originally coded this on a linux machine, and I had a much smoother experience which was largely broken on Mac. This lead to a lot of spaghettification supporting mac, and some of the things I had working on linux are still not working on mac.

assets/sample-conversion.sh

@@ -0,0 +1 @@
+ffmpeg -i add-task.mov -c:v libvpx-vp9 -b:v 0 -crf 30 -pix_fmt yuv420p add-task.webm