Add doc-random task and documentation improvements (#98)

## Summary
- Add `doc-random` mise task that selects a random documentation card for review
- Add how-to/knowledgebase section with review-documentation guide
- Add Caddy reference card with proxy configuration details
- Fix replication tutorial sequence (tailscale-setup now links to core-services)
- Fix "BluemeOps" typo in tailscale-setup
- Clean up obsolete zk/ directory references from doc-links

## Deployment and Testing
- [x] `mise run doc-random` works and displays a random card
- [x] `mise run doc-links` passes (all wiki-links valid)
- [x] Pre-commit hooks pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/98

mise-tasks/doc-links

@@ -7,7 +7,7 @@
 """Validate that all wiki-links in documentation point to existing files.
 
 This script scans all markdown files in the docs/ directory (excluding
-changelog.d/ and zk/), extracts wiki-links, and verifies each link target
+changelog.d/), extracts wiki-links, and verifies each link target
 exists as a filename or path in the documentation.
 
 Wiki-link formats supported:
@@ -61,9 +61,9 @@ def main() -> int:
     # Track which filenames are ambiguous (appear multiple times)
     filename_counts: dict[str, list[str]] = {}
 
-    # Scan all markdown files (excluding zk/ and changelog.d/)
+    # Scan all markdown files (excluding changelog.d/)
     for md_file in DOCS_DIR.rglob("*.md"):
-        if "changelog.d" in md_file.parts or "zk" in md_file.parts:
+        if "changelog.d" in md_file.parts:
             continue
         # Track filename occurrences
         filename = md_file.stem
@@ -86,9 +86,9 @@ def main() -> int:
     broken_links: list[tuple[str, int, str]] = []
     ambiguous_links: list[tuple[str, int, str, list[str]]] = []
 
-    # Scan all markdown files for wiki-links (excluding zk/ and changelog.d/)
+    # Scan all markdown files for wiki-links (excluding changelog.d/)
     for md_file in sorted(DOCS_DIR.rglob("*.md")):
-        if "changelog.d" in md_file.parts or "zk" in md_file.parts:
+        if "changelog.d" in md_file.parts:
             continue
 
         rel_path = str(md_file.relative_to(DOCS_DIR))

mise-tasks/doc-random

@@ -0,0 +1,88 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["rich>=13.0.0"]
+# ///
+#MISE description="Select a random documentation card for review"
+"""Select a random documentation card for review.
+
+This script scans all markdown files in the docs/ directory (excluding
+changelog.d/), selects one at random, and displays it for review.
+
+Useful for periodic knowledge base maintenance and verification.
+
+Usage: mise run doc-random
+"""
+
+import random
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+DOCS_DIR = Path(__file__).parent.parent / "docs"
+
+
+def get_all_docs() -> list[Path]:
+    """Get all documentation markdown files, excluding changelog.d."""
+    docs = []
+    for md_file in DOCS_DIR.rglob("*.md"):
+        # Skip changelog fragments
+        if "changelog.d" in md_file.parts:
+            continue
+        docs.append(md_file)
+    return docs
+
+
+def main() -> int:
+    console = Console()
+
+    docs = get_all_docs()
+    if not docs:
+        console.print("[bold red]No documentation files found![/bold red]")
+        return 1
+
+    # Select a random document
+    selected = random.choice(docs)
+    rel_path = selected.relative_to(DOCS_DIR)
+
+    # Display header
+    console.print()
+    console.print(Panel(
+        f"[bold cyan]{rel_path}[/bold cyan]\n"
+        f"[dim]{len(docs)} total docs in knowledge base[/dim]",
+        title="[bold]Random Documentation Card[/bold]",
+        border_style="cyan",
+    ))
+    console.print()
+
+    # Display the file content
+    content = selected.read_text()
+    console.print(Markdown(content))
+
+    # Review checklist
+    console.print()
+    console.print(Panel(
+        "[bold]Review Checklist:[/bold]\n\n"
+        "• Is the information accurate and up-to-date?\n"
+        "• Are there broken or missing wiki-links?\n"
+        "• Should this card link to other related cards?\n"
+        "• Is the card too large and should be split?\n"
+        "• Is the card too small and should be merged?\n"
+        "• Does the frontmatter (tags, title) make sense?\n"
+        "• Is the card in the correct category (reference/how-to/etc)?\n\n"
+        "[bold]Verify Deployed State:[/bold]\n\n"
+        "• If ArgoCD app: is it synced? (argocd app get <app>)\n"
+        "• If Ansible role: does it apply idempotently? (--check --diff)\n"
+        "• If Pulumi: is there drift? (pulumi preview)",
+        title="[bold yellow]Review Guidance[/bold yellow]",
+        border_style="yellow",
+    ))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())