docs(cli) Custom argparse documentation engine with syntax highlighting (#1009)

Replace external `sphinx-argparse` dependency with custom `sphinx_argparse_neo` extensions, ported from vcspull project. Adds comprehensive documentation infrastructure for CLI commands.

## Changes

### New Extensions
- `docs/_ext/sphinx_argparse_neo/` - Complete argparse documentation engine
- `docs/_ext/argparse_exemplar.py` - Transforms epilog examples into TOC sections
- `docs/_ext/argparse_lexer.py` - Pygments lexers for CLI syntax highlighting
- `docs/_ext/argparse_roles.py` - RST roles for inline CLI formatting
- `docs/_static/css/argparse-highlight.css` - Styling for usage blocks and code

### Bug Fixes
- Use slice assignment for docutils node children manipulation (fixes parent tracking)
- Add type annotation to fix mypy `no-any-return` error
- Escape asterisks in glob patterns to prevent RST emphasis warnings
- Add ID prefix to avoid duplicate section IDs across subcommand pages

### Documentation
- Restructure CLI command pages to match vcspull pattern
- Add doctest exceptions to AGENTS.md for Sphinx visitor patterns
- Add doctests to `_create_example_section()` and `_extract_mutex_groups()`

### Removed
- `pretty_argparse.py` (replaced by new extensions)
- `sphinx-argparse` dependency

Author: tony

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)