Release 2.2.1 — Hotfix

- Add recommended CLI options section to README (D34)
- Re-render example graph with --no-defines --concentrate
- Add graph0 regeneration instructions as HTML comment
- Finalize changelog and bump version to 2.2.1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Technologicat

CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
-## 2.2.1 (in progress)
+## 2.2.1 (22 March 2026) — *Hotfix*
+
+### Documentation
+
+- **Recommended options in README** — added a section with recommended CLI
+  options for common use cases: clean uses-only graphs, `fdp` layout for
+  larger projects, and `--depth 1` for high-level overviews.  Re-rendered
+  the example graph with `--no-defines --concentrate`.
+- **`--concentrate` precision caveat** — noted that GraphViz's edge
+  concentration can produce small gaps at split/merge points.
 
 ### Bug fixes
 

README.md

@@ -47,6 +47,7 @@ This revival was carried out by [Technologicat](https://github.com/Technologicat
 - [Overview](#overview)
 - [Usage](#usage)
     - [CLI usage](#cli-usage)
+        - [Recommended options](#recommended-options)
         - [Graph depth control](#graph-depth-control)
         - [Filtering](#filtering)
         - [Call path listing](#call-path-listing)
@@ -73,17 +74,25 @@ This revival was carried out by [Technologicat](https://github.com/Technologicat
 
 # Overview
 
+<!-- To regenerate graph0:
+     pyan3 tests/orbital/*.py --dot --colored --no-defines --concentrate --file graph0.dot
+     dot -Tsvg graph0.dot -o graph0.svg
+     dot -Tpng graph0.dot -o graph0.png
+     rm graph0.dot
+-->
 [![Example output](graph0.png "Example: GraphViz rendering of Pyan output (click for .svg)")](graph0.svg)
 
-**Defines** relations are drawn with _dotted gray arrows_.
+This example was rendered with the [recommended options](#recommended-options): `--colored --no-defines --concentrate`.
 
-**Uses** relations are drawn with _black solid arrows_. Recursion is indicated by an arrow from a node to itself. [Mutual recursion](https://en.wikipedia.org/wiki/Mutual_recursion#Basic_examples) between nodes X and Y is indicated by a pair of arrows, one pointing from X to Y, and the other from Y to X.
+**Uses** relations are drawn with _black solid arrows_. Recursion is indicated by an arrow from a node to itself. [Mutual recursion](https://en.wikipedia.org/wiki/Mutual_recursion#Basic_examples) between nodes X and Y is indicated by a pair of arrows, one pointing from X to Y, and the other from Y to X. With `--concentrate`, bidirectional edges are merged into double-headed arrows.
+
+**Defines** relations (drawn with _dotted gray arrows_) can be enabled with `--defines`.
 
 **Nodes** are always filled, and made translucent to clearly show any arrows passing underneath them. This is especially useful for large graphs with GraphViz's `fdp` filter. If colored output is not enabled, the fill is white.
 
 In **node coloring**, the [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV) color model is used. The **hue** is determined by the _filename_ the node comes from. The **lightness** is determined by _depth of namespace nesting_, with darker meaning more deeply nested. Saturation is constant. The spacing between different hues depends on the number of files analyzed; better results are obtained for fewer files.
 
-**Groups** are filled with translucent gray to avoid clashes with any node color.
+**Groups** can be enabled with `--grouped` (and `--nested-groups` for nested subgraph clusters). Groups are filled with translucent gray to avoid clashes with any node color.
 
 The nodes can be **annotated** by _filename and source line number_ information.
 
@@ -115,6 +124,29 @@ pyan3 *.py --uses --no-defines --colored --grouped --annotated --html >myuses.ht
 pyan3 src/ --uses --no-defines --text
 ```
 
+### Recommended options
+
+For a clean uses-only call graph:
+
+```bash
+pyan3 src/*.py --dot --colored --no-defines --concentrate --file output.dot
+dot -Tsvg output.dot -o output.svg
+```
+
+This omits defines edges (which tend to clutter the graph) and merges bidirectional uses edges into double-headed arrows. The `dot` layout works well for hierarchical call graphs; for larger graphs, `fdp` (force-directed) can produce more readable results:
+
+```bash
+pyan3 src/*.py --dot --colored --no-defines --concentrate --graphviz-layout fdp --file output.dot
+fdp -Tsvg output.dot -o output.svg
+```
+
+For a high-level overview, add `--depth 1` to collapse everything down to modules, classes, and top-level functions:
+
+```bash
+pyan3 src/*.py --dot --colored --no-defines --concentrate --depth 1 --file overview.dot
+```
+
+
 ### Graph depth control
 
 Collapse the graph to a desired level of detail:

TODO_DEFERRED.md

@@ -28,12 +28,6 @@ Items with GitHub ticket numbers are tracked externally. The rest are internal n
 - **D31: Test suite organization**: Tests are spread across few modules (`test_features.py`, `test_regressions.py`, `test_modvis.py`, `test_writers.py`, `test_analyzer.py`, `test_sphinx.py`, `test_coverage.py`). Consider reorganizing by concern — e.g. separate CLI tests from unit tests, group by module under test.
 - **D32: Analyzer module split**: `analyzer.py` is ~2200 lines. Consider splitting into submodules (e.g. visitors, postprocessing, scope handling) without changing the public API.
 - **D33: Type annotations for pyan's own code**: Add type annotations to pyan's modules. The analyzer is the largest target (~2200 lines). Would improve IDE support and catch bugs.
-- **D34: Document recommended options in README**: The README should include a recommended set of options for common use cases, e.g.:
-  - `pyan3 src/*.py --dot --colored --no-defines --concentrate --file output.dot` for a clean uses-only call graph
-  - Laying out with `fdp` (works well with Pyan call graphs): `fdp -Txdot output.dot -o output.xdot`
-  - `--depth 1` for module+class/function overview, default depth for full detail
-
-Discovered during raven-xdot-viewer dark mode contrast fix.
 
 ## Done
 
@@ -51,4 +45,5 @@ Discovered during raven-xdot-viewer dark mode contrast fix.
 - **D12**: Tuple unpacking with `Starred`
 - **D16**: Review flake8/ruff warnings (`1af4e31`..`9c9c45c`)
 - **D17**: README example graph
+- **D34**: Document recommended options in README
 - **D27**: Directional graph filtering (`1e096ec`)