From d1db77c4666f32b512b7bc8cbada7c3aaea96034 Mon Sep 17 00:00:00 2001
From: "Thomas (Tom) C. Gorordo" <57684088+tgorordo@users.noreply.github.com>
Date: Mon, 25 May 2026 22:25:52 -0700
Subject: [PATCH] Revise README

Updated README to improve clarity and add usage details.
---
 README.md | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index eb398ea..a7d3f84 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ Pairwise majority comparisons scale quadratically in the number of candidates an
 in the number of ballots, while the SCC and condensation graph analysis is 
 approximately quadratic in the number of candidates for the dense tournament graphs typical 
 of Condorcet elections. Internally, repeated ballots are compressed/cache-counted before 
-pairwise evaluation to improve performance over duplicate rankings.
+pairwise evaluation to improve performance over duplicate rankings.
 This is all overkill for small elections, but is fun.
 
 
@@ -33,7 +33,22 @@ executable should give you access to the `smithycmd` CLI command.
 this in your shell as `uv run src/smithycmd.py [...]` from within the repo after cloning it locally.
 
 In either case, the command expects the same argument structure:
-TODO
+```bash
+$ uv run src/smithycmd.py --help
+Usage: smithycmd.py [OPTIONS] BALLOTS
+
+  Compute the Smith set from a box of ranked-choice ballots -- .csv or
+  .xls(x).
+
+  The Smith set is the minimal set of candidates which can beat all others
+  pairwise (simple ranking majority) - if there is a single winner in the set,
+  they are guaranteed the Condorcet i.e. Majority winner.
+
+Options:
+  -b, --show-ballots  Show relevant ballots (after selections).
+  -p, --pretty        Pretty-print output.
+  --help              Show this message and exit.
+```
 
 If you want a 'None' option in your election, it should be included as a candidate.
 
@@ -49,9 +64,9 @@ hosts a [CGI form](https://service.uoregon.edu/TDClient/2030/Portal/KB/ArticleDe
 which accepts a `.csv` or `.xls`(`x`) upload of a ballot-box and responds with the resulting
 Smith set. The application can typically handle ~100s of candidates and ~10ks of votes 
 before running into hosting resource limitations and timing out.
-
+
 No ballot data is retained on the server after execution.
-
+
 
 ### Python Package
 The `smithy` python package primarily provides the function `smith_set(ballot_box_df)`