Add doc-random mise task for documentation review

- New mise task selects a random doc card for periodic review
- Add how-to/knowledgebase section with review-documentation guide
- Clean up obsolete zk/ directory references from doc-links

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/changelog.d/random-doc-review.feature.md

@@ -0,0 +1 @@
+Add doc-random mise task for random documentation review

docs/how-to/index.md

@@ -28,6 +28,12 @@ Task-oriented instructions for common BlumeOps operations. These guides assume y
 |-------|-------------|
 | [[update-documentation]] | Publish docs via build-blumeops workflow |
 
+## Knowledge Base
+
+| Guide | Description |
+|-------|-------------|
+| [[review-documentation]] | Periodically review and maintain documentation |
+
 ## Operations
 
 | Guide | Description |

docs/how-to/knowledgebase/review-documentation.md

@@ -0,0 +1,58 @@
+---
+title: review-documentation
+tags:
+  - how-to
+  - documentation
+  - maintenance
+---
+
+# Review Documentation
+
+How to periodically review and maintain the BlumeOps knowledge base.
+
+## Quick Random Review
+
+Select a random documentation card for review:
+
+```bash
+mise run doc-random
+```
+
+This displays a random card with a review checklist to guide your assessment.
+
+## Review Checklist
+
+When reviewing a documentation card, consider:
+
+| Check | Description |
+|-------|-------------|
+| **Accuracy** | Is the information current and correct? |
+| **Links** | Are wiki-links working? Should more be added? |
+| **Scope** | Is the card appropriately sized (not too large/small)? |
+| **Category** | Is it in the right section (reference/how-to/tutorial/explanation)? |
+| **Frontmatter** | Are title and tags appropriate? |
+| **Related** | Should it link to related cards? |
+
+## When to Review
+
+Consider running `mise run doc-random` during:
+
+- Start of work sessions (quick maintenance)
+- After major infrastructure changes (verify docs reflect reality)
+- When learning the system (random exploration)
+
+## Making Changes
+
+If a card needs updates:
+
+1. Create a feature branch
+2. Make the edits
+3. Run `mise run doc-links` to verify links
+4. Create a PR for review
+
+See [[update-documentation]] for publishing changes.
+
+## Related
+
+- [[update-documentation]] - Publishing documentation changes
+- [[exploring-the-docs]] - Navigating the documentation

docs/tutorials/ai-assistance-guide.md

@@ -88,6 +88,7 @@ BlumeOps operations are driven by mise tasks. Run `mise tasks` to list all avail
 | `doc-links` | Validate wiki-links in documentation |
 | `doc-titles` | Check for duplicate doc titles |
 | `doc-filenames` | Check for duplicate doc filenames |
+| `doc-random` | Select a random doc card for review |
 | `indri-runner-logs` | View Forgejo workflow logs from local runner |
 
 For ArgoCD operations, use the `argocd` CLI directly:

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,84 @@
+#!/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)?",
+        title="[bold yellow]Review Guidance[/bold yellow]",
+        border_style="yellow",
+    ))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())