diff --git a/README.md b/README.md
index 3a3fcdb..90bc4d3 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,8 @@ python3 -m goodnews build-brief --date 2026-05-27 --replace
 python3 -m goodnews show-brief
 python3 -m goodnews list-recent --limit 10
 python3 -m goodnews list-recent --accepted-only --limit 10
+python3 -m goodnews list-category --topic animals --flavor discovery
+python3 -m goodnews list-category --topic environment --flavor solution
 python3 -m goodnews source-report
 python3 -m goodnews list-runs
 ```
@@ -35,6 +37,18 @@ Sources live at:
 config/sources.toml
 ```
 
+## Categories
+
+When classified by the local model, each article is tagged with one **topic**
+and one **flavor**, allowing browsable category feeds (e.g. "feel-good animals",
+"environment solutions") via `list-category`:
+
+- **Topics:** science, environment, health, community, culture, animals
+- **Flavors:** breakthrough, discovery, solution, feelgood, perspective
+
+The allowed values live in `goodnews/taxonomy.py`. The accept/reject gate is kept
+deliberately broad ("not dreary"); ranking and category filters do the curation.
+
 ## Stored Article Data
 
 For each article, the database stores: