chore(docs): phase 3 - automate reference docs and version injection

[beonde]

Phase 3: Automate Reference Docs

Part of the documentation remediation plan (Phase 3 of 4).

Changes

Version Variable Injection

• New: hooks/version_vars.py — MkDocs hook that replaces {{ capiscio_version }} and {{ protocol_version }} placeholders with values from mkdocs.yml extra: config
• Uses simple string replacement instead of the macros plugin, avoiding conflicts with GitHub Actions {{ }} syntax in code examples
• 19 version references across 8 files now use placeholders instead of hard-coded strings
• Version bumps now require editing only one place: mkdocs.yml extra: section
• Deliberately skipped: go-api.md (auto-generated by gomarkdoc), llms.txt (static file), and 3 historical "introduced in 0.3.0" table entries in validation.md

Badge API Auto-Generation (mkdocstrings)

• Converted badge.md from 442 lines of hand-written API docs to mkdocstrings auto-generation
• All 7 functions (verify_badge, parse_badge, request_badge, request_badge_sync, request_pop_badge, request_pop_badge_sync, start_badge_keeper) now auto-generated from source docstrings
• All 5 classes (BadgeClaims, VerifyResult, VerifyOptions, VerifyMode, TrustLevel) now auto-generated
• Retained hand-written Quick Start, Error Codes table, Patterns section, and See Also links

Config Quick Start Fix

• Fixed config.md Quick Start showing non-existent fields (validate_inbound, validate_outbound, require_signature, log_level)
• Replaced with correct SecurityConfig constructor: downstream, upstream, strict_mode, fail_mode

Stale Timestamp Cleanup

• Removed VERIFIED: 2025-12-xx HTML comment blocks from grpc.md, deployment.md, badge-ca.md, server/index.md
• The git-revision-date-localized plugin already provides accurate "last updated" dates

Build Verification

• mkdocs build passes with zero errors
• Version placeholders confirmed resolved in built output (0 unsubstituted capiscio_version or protocol_version references)
• mkdocstrings auto-generated 33+ symbol references on the badge page

Files Changed (19)

• 1 new: hooks/version_vars.py
• 1 modified: mkdocs.yml (hook config + version variables)
• 8 modified: version placeholder replacements
• 1 modified: badge.md (mkdocstrings conversion)
• 1 modified: config.md (Quick Start fix)
• 4 modified: VERIFIED timestamp removal
• Net: -183 lines (171 added, 354 removed)

[github-actions]

✅ Documentation Build Successful

The documentation build completed successfully and passed validation checks.

• ✅ Build completed without errors
• ✅ Critical files present (index.html, sitemap.xml, robots.txt)
• ✅ Link validation completed

This PR will deploy to dev-docs.capisc.io when merged to main.