From 9643dab4909d325c96734ff681debe56d08b8e6b Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 3 Apr 2026 11:47:16 +0000
Subject: [PATCH 1/2] Fix workflow docs link rewriting for strict MkDocs builds

Rewrite ../../docs/workflows/*.md links in generated gh-agent-workflow pages to ../*.md so strict MkDocs link checks resolve correctly. Update docs hook tests to assert the rewritten output.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/hooks.py            | 15 +++++++++++----
 tests/test_docs_hooks.py |  6 +++---
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/docs/hooks.py b/docs/hooks.py
index 70eb2fa0..159c5328 100644
--- a/docs/hooks.py
+++ b/docs/hooks.py
@@ -42,12 +42,11 @@ def _workflow_source_link(example_content: str) -> str | None:
 def _rewrite_sibling_workflow_links(readme: str) -> str:
     """Rewrite sibling workflow links to generated docs pages.
 
-    Only links to direct sibling workflow READMEs/directories are rewritten:
+    The generated workflow docs live under docs/workflows/gh-agent-workflows/.
+    Rewrite source-tree links so they resolve from that location:
     - ../other-workflow/README.md -> other-workflow.md
     - ../other-workflow/ -> other-workflow.md
-
-    Broader relative links (for example ../../docs/...) are intentionally left
-    unchanged.
+    - ../../docs/workflows/<page>.md -> ../<page>.md
     """
 
     def replace_link(match: re.Match[str]) -> str:
@@ -66,6 +65,14 @@ def replace_link(match: re.Match[str]) -> str:
             anchor = dir_match.group(2) or ""
             return f"[{link_text}]({slug}.md{anchor})"
 
+        docs_workflows_match = re.fullmatch(
+            r"\.\./\.\./docs/workflows/([a-z0-9-]+)\.md(#.*)?", target
+        )
+        if docs_workflows_match:
+            slug = docs_workflows_match.group(1)
+            anchor = docs_workflows_match.group(2) or ""
+            return f"[{link_text}](../{slug}.md{anchor})"
+
         return match.group(0)
 
     return re.sub(r"\[([^\]]+)\]\(([^)]+)\)", replace_link, readme)
diff --git a/tests/test_docs_hooks.py b/tests/test_docs_hooks.py
index dd575801..31b7b153 100644
--- a/tests/test_docs_hooks.py
+++ b/tests/test_docs_hooks.py
@@ -47,7 +47,7 @@ def test_generate_page_rewrites_sibling_workflow_directory_link_with_anchor(tmp_
     assert "../other-workflow/#details" not in page
 
 
-def test_generate_page_preserves_non_sibling_docs_links(tmp_path):
+def test_generate_page_rewrites_docs_workflows_links(tmp_path):
     hooks = _load_hooks_module()
     workflow_dir = _create_workflow_dir(
         tmp_path,
@@ -57,5 +57,5 @@ def test_generate_page_preserves_non_sibling_docs_links(tmp_path):
 
     page = hooks._generate_page(workflow_dir)
 
-    assert "[Detector / Fixer chaining](../../docs/workflows/detector-fixer-chaining.md)" in page
-    assert "../docs.mdworkflows/detector-fixer-chaining.md" not in page
+    assert "[Detector / Fixer chaining](../detector-fixer-chaining.md)" in page
+    assert "../../docs/workflows/detector-fixer-chaining.md" not in page

From 8ca388fd1e36504654535e8dd0c9d10045df54f6 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 3 Apr 2026 11:47:18 +0000
Subject: [PATCH 2/2] ci: trigger checks