docs: add fix hints and doc refs to coverage and MDX validation output

audit_coverage.py:
- Coverage miss section now shows a structured Fix:/Ref: block with the
  exact generate-ast.py command and a link to CONTRIBUTING.md#validating-docstrings
- Missing symbols listed one per line (symbol indented under module) for
  scannability instead of comma-joined on one long line
- Emit a ::error or ::warning GHA annotation with symbol/module counts
  when coverage symbols are undocumented

validate.py:
- Add _CHECK_FIX_HINTS dict mapping each check label to a (fix text, ref URL)
  pair, covering all 8 check types with specific fix instructions and links
  into CONTRIBUTING.md (root or guide as appropriate)
- _print_check_errors now prints Fix:/Ref: under each section header,
  matching the pattern established by _print_quality_report

Author: planetf1

tooling/docs-autogen/audit_coverage.py

@@ -437,12 +437,17 @@ def walk_module(module, module_path: str) -> None:
 
 _IN_GHA = os.environ.get("GITHUB_ACTIONS") == "true"
 
-# GitHub URL for the contributing guide docstring checks reference section.
-# Each issue kind links to the relevant anchor so developers can navigate directly.
+# Base URLs for documentation references emitted in fix hints.
+# These point to upstream main; anchors for the CI checks reference section
+# will resolve once the PR introducing them is merged.
 _CONTRIB_DOCS_URL = (
     "https://github.com/generative-computing/mellea/blob/main"
     "/docs/docs/guide/CONTRIBUTING.md"
 )
+_COVERAGE_DOCS_URL = (
+    "https://github.com/generative-computing/mellea/blob/main"
+    "/CONTRIBUTING.md#validating-docstrings"
+)
 
 # Per-kind fix hints: (one-line fix text, CONTRIBUTING.md anchor)
 _KIND_FIX_HINTS: dict[str, tuple[str, str]] = {
@@ -865,11 +870,32 @@ def main():
     print(f"CLI commands: {len(report['cli_commands'])}")
 
     if report["missing_symbols"]:
+        total_missing = sum(len(s) for s in report["missing_symbols"].values())
+        print(f"\n{'─' * 60}")
+        print(
+            f"  Missing API docs — {total_missing} symbol(s) across "
+            f"{len(report['missing_symbols'])} module(s)"
+        )
         print(
-            f"\n⚠️  Missing documentation for {len(report['missing_symbols'])} modules:"
+            "  Fix: Run the doc generation pipeline to produce MDX for new symbols,\n"
+            "       then add entries to docs/docs/docs.json navigation.\n"
+            "       uv run python tooling/docs-autogen/generate-ast.py"
         )
+        print(f"  Ref: {_COVERAGE_DOCS_URL}")
+        print(f"{'─' * 60}")
         for module, symbols in sorted(report["missing_symbols"].items()):
-            print(f"  {module}: {', '.join(symbols)}")
+            print(f"  {module}")
+            for sym in sorted(symbols):
+                print(f"    {sym}")
+        if _IN_GHA:
+            _gha_cmd(
+                "error" if report["coverage_percentage"] < args.threshold else "warning",
+                "API Coverage",
+                f"{total_missing} symbol(s) undocumented in "
+                f"{len(report['missing_symbols'])} module(s) — "
+                f"coverage {report['coverage_percentage']}% "
+                f"(threshold {args.threshold}%)",
+            )
 
     # Quality audit — scoped to documented (API reference) symbols only
     quality_issues: list[dict] = []

tooling/docs-autogen/validate.py

@@ -18,6 +18,57 @@
 
 _IN_GHA = os.environ.get("GITHUB_ACTIONS") == "true"
 
+_ROOT_CONTRIB = (
+    "https://github.com/generative-computing/mellea/blob/main/CONTRIBUTING.md"
+)
+_GUIDE_CONTRIB = (
+    "https://github.com/generative-computing/mellea/blob/main"
+    "/docs/docs/guide/CONTRIBUTING.md"
+)
+
+# Per-check fix hints: label (as passed to _print_check_errors) -> (fix text, ref URL)
+_CHECK_FIX_HINTS: dict[str, tuple[str, str]] = {
+    "Source links": (
+        "Regenerate API docs to update version tags in source links: "
+        "uv run python tooling/docs-autogen/generate-ast.py",
+        f"{_ROOT_CONTRIB}#validating-docstrings",
+    ),
+    "MDX syntax": (
+        "Check for unclosed ``` fences, missing frontmatter, or unescaped {{ }} "
+        "in code blocks. Each error includes the file and line number.",
+        f"{_GUIDE_CONTRIB}#frontmatter-required-on-every-page",
+    ),
+    "Internal links": (
+        "Verify the relative link path resolves to an existing .mdx file. "
+        "Each error shows the file, line, and broken link target.",
+        f"{_GUIDE_CONTRIB}#links",
+    ),
+    "Anchor collisions": (
+        "Rename one of the conflicting headings so they produce unique anchors. "
+        "Each error shows both heading texts and their line numbers.",
+        f"{_GUIDE_CONTRIB}#headings",
+    ),
+    "RST docstrings": (
+        "Replace RST double-backtick notation (``Symbol``) with single backticks "
+        "(`Symbol`) in the Python source docstring.",
+        f"{_ROOT_CONTRIB}#docstrings",
+    ),
+    "Stale files": (
+        "Delete the listed files — they are review artifacts or superseded content "
+        "that should not ship.",
+        f"{_GUIDE_CONTRIB}#missing-content",
+    ),
+    "Doc imports": (
+        "Update the import path in the documentation code block to match the "
+        "current module/symbol location.",
+        f"{_GUIDE_CONTRIB}#code-and-fragment-consistency",
+    ),
+    "Examples catalogue": (
+        "Add a row for the new example directory to docs/docs/examples/index.md.",
+        f"{_GUIDE_CONTRIB}#keeping-the-examples-catalogue-up-to-date",
+    ),
+}
+
 # GitHub Actions silently drops inline diff annotations beyond ~10 per step.
 # We cap at 20 total across all validate.py checks so the most important issues
 # from each category remain visible in the PR diff.  The complete list is always
@@ -590,8 +641,13 @@ def _print_check_errors(
     """
     if not errors:
         return
+    fix_hint, ref_url = _CHECK_FIX_HINTS.get(label, ("", ""))
     print(f"\n{'─' * 50}")
     print(f"  {label} ({len(errors)} error(s))")
+    if fix_hint:
+        print(f"  Fix: {fix_hint}")
+    if ref_url:
+        print(f"  Ref: {ref_url}")
     print(f"{'─' * 50}")
     capped = 0
     for e in errors: