Track upstream discovery state

README.md

@@ -10,6 +10,7 @@ This tool fetches TODO items from the [Debian UDD (Ultimate Debian Database)](ht
 
 - Python 3.10+
 - System packages: `python3-click`, `python3-debian`, `python3-rich`
+- Package update workflow tools: `salsa`, `gbp`, `dch`, `debuild`, `update-debian-package`
 
 Install dependencies on Debian/Ubuntu:
 
@@ -27,7 +28,10 @@ apt install python3-click python3-debian python3-rich
 ./todo list --show-prerelease
 
 # Fetch latest data and show changes
-./todo update
+./todo refresh
+
+# Update a package checkout to the new upstream version
+./todo update <source-package>
 ```
 
 Running `./todo` without arguments is equivalent to `./todo list`.
@@ -36,7 +40,7 @@ Running `./todo` without arguments is equivalent to `./todo list`.
 
 - `todo.json` - Cached TODO list from UDD (auto-downloaded)
 - `notes` - Per-package notes (one package per line: `<source> <note>`)
-- `.vcs_git_cache.json` - Cache of Vcs-Git and uploader info from APT sources
+- `.debian_todo.sqlite3` - SQLite cache for source metadata and package discovery state
 
 ## Notes File Format
 
@@ -70,8 +74,11 @@ PYTHONPATH=. pytest tests/ -v
 - Compares normalized versions to avoid false positives
 - Shows team from Vcs-Git (e.g., `python-team`, `HA` for homeassistant-team)
 - Displays uploaders when no team is set
+- Shows the first-seen timestamp for current upstream versions when available
+- Tracks when each upstream version was first seen and sorts `./todo list` by that date
+- Updates package checkouts with `salsa`, `gbp import-orig`, changelog entries, `update-debian-package`, and `debuild -S`
 - Responsive output: table view on wide terminals, compact view on narrow
-- Caches APT source parsing for faster subsequent runs
+- Caches APT source parsing and package state in SQLite for faster subsequent runs
 
 ## License