fix(docs): upgrade pymdown-extensions to 10.21.3 for pygments 2.20.0 compat (#514)

* fix(docs): pin pygments below 2.20 to fix mkdocstrings source-highlight crash

The CD docs build crashed in mkdocstrings source highlighting:
html.escape('NoneType') via pygments 2.20.0's HtmlFormatter, which
escapes the 'filename' option (None for mkdocstrings source blocks)
without guarding None. Pin pygments < 2.20 (resolves to 2.19.2) in the
docs group to restore the build.

Validated locally: full CD docs sequence (vrg-docs-stage +
vrg-docs-patch-nav + mkdocs build) completes cleanly.

The pin is technical debt; revisit/unpin tracked in #513 (records the
broken version and how to validate a fix). Refs #512.

* fix(docs): upgrade pymdown-extensions for pygments 2.20.0 compatibility

Supersedes the previous pygments<2.20 pin on this branch. Pinning
pygments down was a dead end: pygments 2.19.2 carries CVE-2026-4539
(fixed in 2.20.0), so pip-audit blocks it.

The actual incompatibility is pymdown-extensions < 10.21.3 passing
filename=None into pygments' HtmlFormatter, which crashes mkdocstrings
source highlighting on pygments >= 2.20.0. pymdown-extensions 10.21.3
fixes that. So: stay on pygments 2.20.0 (CVE-safe) and floor
pymdown-extensions >= 10.21.3.

Result: docs build is green AND audit is clean; no pinned-down
dependency, so no tech debt (closes the need for #513). Validated locally
via the full CD docs sequence (stage + patch-nav + mkdocs build) and
vrg-validate (incl. pip-audit). Refs #512.

---------

Co-authored-by: Phillip Moore <w.phillip.moore@gmail.com>

Author: wphillipmoore-vergil-agent[bot]

pyproject.toml

@@ -49,6 +49,11 @@ docs = [
     "mike",
     "mkdocs-material",
     "mkdocstrings[python]",
+    # pymdown-extensions < 10.21.3 passes filename=None into pygments'
+    # HtmlFormatter, which crashes mkdocstrings source highlighting on
+    # pygments >= 2.20.0. 10.21.3 fixes it; keep pygments current (2.20.0
+    # carries the CVE-2026-4539 fix). See #512.
+    "pymdown-extensions>=10.21.3",
 ]
 
 [tool.setuptools]