docs(cli) Custom argparse documentation engine with syntax highlighting

AGENTS.md

@@ -156,6 +156,14 @@ windows:
 3. **Keep doctests simple and focused** on demonstrating usage
 4. **Add blank lines between test sections** for improved readability
 
+**Doctest exceptions** (patterns where doctests are not required):
+
+1. **Sphinx/docutils `visit_*`/`depart_*` methods** - tested via integration tests; 0 examples across docutils (851 methods), Sphinx (800+), and CPython's `ast.NodeVisitor`
+2. **Sphinx `setup()` functions** - entry points not testable in isolation
+3. **Complex recursive traversal functions** - extract helper predicates instead
+
+**Best practice for node processing**: Extract testable helper functions (like `_is_usage_block()`) and doctest those. Keep complex visitor logic in integration tests.
+
 ## Documentation Standards
 
 ### Code Blocks in Documentation

CHANGES

@@ -31,7 +31,28 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
-_Notes on the upcoming release will go here._
+### Documentation
+
+#### CLI documentation overhaul with sphinx_argparse_neo (#1009)
+
+Replaced the `pretty_argparse` extension with a new `sphinx_argparse_neo` package:
+
+- **New argparse documentation engine**: Complete rewrite for cleaner, more maintainable CLI docs
+- **Syntax highlighting**: Custom Pygments lexers for CLI usage blocks and argparse output
+- **Examples transformation**: Automatically converts epilog "examples:" definition lists into proper documentation sections with TOC entries
+- **ANSI stripping**: Removes escape codes when `FORCE_COLOR` is set
+- **RST emphasis escaping**: Prevents warnings from glob patterns like `django-*`
+- **Restructured CLI pages**: Consistent layout matching vcspull documentation pattern
+
+### Bug fixes
+
+#### Docutils node.children protocol (#1009)
+
+- Fixed direct `node.children` assignment that bypassed docutils' parent-child tracking mechanism
+
+#### Mypy type annotation (#1009)
+
+- Added missing type annotation to fix `no-any-return` error
 
 ## tmuxp 1.63.1 (2026-01-11)