From 425e153beecfea0a3125f9ed9817efcf56223abb Mon Sep 17 00:00:00 2001
From: welsberr <welsberr@gmail.com>
Date: Fri, 20 Mar 2026 11:43:43 -0400
Subject: [PATCH] Group CLI examples by task

---
 examples/cli/README.md | 122 +++++++++++++++++++++++++----------------
 1 file changed, 75 insertions(+), 47 deletions(-)

diff --git a/examples/cli/README.md b/examples/cli/README.md
index 8c8088a..35b9c8d 100644
--- a/examples/cli/README.md
+++ b/examples/cli/README.md
@@ -15,7 +15,11 @@ cd citegeist
 export PYTHONPATH=src
 ```
 
-## Global Option
+## Setup
+
+Purpose: point commands at the right database before doing anything else.
+
+### Global Option
 
 Use a non-default database path:
 
@@ -23,7 +27,11 @@ Use a non-default database path:
 .venv/bin/python -m citegeist --db library.sqlite3 topics
 ```
 
-## Ingest
+## Build And Inspect A Library
+
+Purpose: ingest records, search them, inspect them, and export them.
+
+### Ingest
 
 Basic ingest:
 
@@ -49,7 +57,7 @@ Use both ingest options together:
 .venv/bin/python -m citegeist --db library.sqlite3 ingest references.bib --status draft --source-label "manual-import:artificial-life"
 ```
 
-## Search
+### Search
 
 Basic search:
 
@@ -69,7 +77,7 @@ Restrict search to one topic slice:
 .venv/bin/python -m citegeist --db library.sqlite3 search "artificial life" --topic artificial-life
 ```
 
-## Show
+### Show
 
 Show one entry:
 
@@ -101,7 +109,7 @@ Use both:
 .venv/bin/python -m citegeist --db library.sqlite3 show langton1989artificial1 --provenance --conflicts
 ```
 
-## Export
+### Export
 
 Export the whole library:
 
@@ -121,7 +129,11 @@ Write BibTeX to a file:
 .venv/bin/python -m citegeist --db library.sqlite3 export --output artificial-life.bib
 ```
 
-## Entry Review
+## Review And Clean Metadata
+
+Purpose: inspect merge conflicts, apply corrections, and enrich incomplete records.
+
+### Entry Review
 
 Set review status:
 
@@ -147,7 +159,7 @@ Apply the latest proposed conflict value:
 .venv/bin/python -m citegeist --db library.sqlite3 apply-conflict langton1989artificial1 title
 ```
 
-## Extract
+### Extract
 
 Extract draft BibTeX from plaintext:
 
@@ -161,7 +173,7 @@ Write extracted BibTeX to a file:
 .venv/bin/python -m citegeist extract references.txt --output extracted-artificial-life.bib
 ```
 
-## Resolve
+### Resolve
 
 Resolve one or more entries against remote metadata:
 
@@ -169,7 +181,11 @@ Resolve one or more entries against remote metadata:
 .venv/bin/python -m citegeist --db library.sqlite3 resolve langton1989artificial1 bedau2003artificial2
 ```
 
-## Graph Traversal
+## Explore Citation Graphs
+
+Purpose: traverse citation edges, export graph data, and render quick visualizations.
+
+### Graph Traversal
 
 Basic traversal:
 
@@ -219,7 +235,7 @@ Write graph output to a file:
 .venv/bin/python -m citegeist --db library.sqlite3 graph langton1989artificial1 --depth 2 --format dot --output artificial-life.dot
 ```
 
-## Graph Viewer
+### Graph Viewer
 
 Render a standalone HTML page from a `json-graph` export:
 
@@ -233,7 +249,7 @@ Set the HTML page title:
 .venv/bin/python -m citegeist graph-view artificial-life.json --output artificial-life.html --title "Artificial Life Graph"
 ```
 
-## Graph Expansion
+### Graph Expansion
 
 Expand from one or more seed entries:
 
@@ -259,7 +275,11 @@ Limit discoveries per seed:
 .venv/bin/python -m citegeist --db library.sqlite3 expand langton1989artificial1 --source openalex --limit 10
 ```
 
-## Topic Expansion
+## Build A Topic-Centered Bibliography
+
+Purpose: create, expand, inspect, and export a topic slice such as `artificial life`.
+
+### Topic Expansion
 
 Basic topic expansion from stored topic metadata:
 
@@ -303,7 +323,7 @@ Preview without writing:
 .venv/bin/python -m citegeist --db library.sqlite3 expand-topic artificial-life --preview
 ```
 
-## Topic Phrase Storage
+### Topic Phrase Storage
 
 Set a stored topic phrase:
 
@@ -317,45 +337,51 @@ Clear a stored topic phrase:
 .venv/bin/python -m citegeist --db library.sqlite3 set-topic-phrase artificial-life --clear
 ```
 
-## OAI-PMH Harvesting
+### Topic Inspection
 
-Inspect a repository:
+List topics:
 
 ```bash
-.venv/bin/python -m citegeist discover-oai https://example.edu/oai
+.venv/bin/python -m citegeist --db library.sqlite3 topics
 ```
 
-Harvest with default metadata prefix:
+Limit topic rows:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai
+.venv/bin/python -m citegeist --db library.sqlite3 topics --limit 20
 ```
 
-Use an alternate metadata prefix:
+Filter topics by phrase review status:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --metadata-prefix mods
+.venv/bin/python -m citegeist --db library.sqlite3 topics --phrase-review-status pending
 ```
 
-Restrict to a set:
+List entries for a topic:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --set artificial-life
+.venv/bin/python -m citegeist --db library.sqlite3 topic-entries artificial-life
 ```
 
-Harvest a date range:
+Limit topic entries:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --from 2024-01-01 --until 2024-12-31
+.venv/bin/python -m citegeist --db library.sqlite3 topic-entries artificial-life --limit 25
 ```
 
-Limit harvested records and set review status:
+Export one topic slice as BibTeX:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --limit 10 --status draft
+.venv/bin/python -m citegeist --db library.sqlite3 export-topic artificial-life
 ```
 
-## Bootstrap
+Write the topic slice to a file:
+
+```bash
+.venv/bin/python -m citegeist --db library.sqlite3 export-topic artificial-life --output artificial-life-topic.bib
+```
+
+### Bootstrap
 
 Seed from a BibTeX file:
 
@@ -416,7 +442,7 @@ Set review status for imported entries:
 .venv/bin/python -m citegeist --db library.sqlite3 bootstrap --topic "artificial life" --status reviewed
 ```
 
-## Batch Bootstrap
+### Batch Bootstrap
 
 Run a JSON batch file:
 
@@ -424,7 +450,7 @@ Run a JSON batch file:
 .venv/bin/python -m citegeist --db library.sqlite3 bootstrap-batch artificial-life.json
 ```
 
-## Topic Phrase Review Workflow
+### Topic Phrase Review Workflow
 
 Apply topic phrases directly:
 
@@ -498,51 +524,53 @@ Write the review template to a file:
 .venv/bin/python -m citegeist --db library.sqlite3 export-topic-phrase-reviews --output topic-phrase-review.json
 ```
 
-## Topic Inspection
+## Harvest External Repositories
 
-List topics:
+Purpose: inspect and harvest OAI-PMH repositories into the library.
+
+### OAI-PMH Harvesting
+
+Inspect a repository:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 topics
+.venv/bin/python -m citegeist discover-oai https://example.edu/oai
 ```
 
-Limit topic rows:
+Harvest with default metadata prefix:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 topics --limit 20
+.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai
 ```
 
-Filter topics by phrase review status:
+Use an alternate metadata prefix:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 topics --phrase-review-status pending
+.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --metadata-prefix mods
 ```
 
-List entries for a topic:
+Restrict to a set:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 topic-entries artificial-life
+.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --set artificial-life
 ```
 
-Limit topic entries:
+Harvest a date range:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 topic-entries artificial-life --limit 25
+.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --from 2024-01-01 --until 2024-12-31
 ```
 
-Export one topic slice as BibTeX:
+Limit harvested records and set review status:
 
 ```bash
-.venv/bin/python -m citegeist --db library.sqlite3 export-topic artificial-life
+.venv/bin/python -m citegeist --db library.sqlite3 harvest-oai https://example.edu/oai --limit 10 --status draft
 ```
 
-Write the topic slice to a file:
+## Work Through Example Corpora
 
-```bash
-.venv/bin/python -m citegeist --db library.sqlite3 export-topic artificial-life --output artificial-life-topic.bib
-```
+Purpose: run the repo’s example workflows without treating them as the core product surface.
 
-## TalkOrigins Example Commands
+### TalkOrigins Example Commands
 
 Scrape the example corpus: