[product-manager-impersonator] Render alternate workflow examples in docs

Start in docs/hooks.py, especially _generate_page and the lines that read README.md and example.yml and append the example section. Review the existing _generate_page coverage in tests/test_docs_hooks.py, then run that test while checking a temporary workflow containing example.yml and example-chained.yml. Done means both workflow snippets and their sections appear on the generated page.

Feature Idea

Summary: Update the generated workflow docs so pages automatically include alternate example files such as example-chained.yml when a workflow ships them, instead of showing only the detector-only example.yml.

Why a Customer Would Want This

Maintainers evaluating scheduled detectors often want the fully autonomous detector-to-fixer path, but the generated workflow pages currently embed only the default example. When a workflow already ships a chained example, users should be able to copy it directly from the docs page without jumping back to the repository tree or piecing the pattern together from separate chaining docs.

Rough Implementation Sketch

• Extend docs/hooks.py to discover optional example variants next to example.yml (starting with example-chained.yml).
• Render additional sections such as ## Chained Example Workflow after the existing ## Example Workflow block.
• Add a focused tests/test_docs_hooks.py case that creates a temporary workflow directory with both example.yml and example-chained.yml and asserts both snippets are present.
• Keep the first iteration narrow to already-existing files; no new workflow templates are required.

Why It Won't Be That Hard

The docs generator already centralizes workflow page creation in one helper: docs/hooks.py reads README.md and example.yml in _generate_page and appends a single YAML block. Adding optional sibling example rendering is a small extension to that helper plus one existing test module.

Evidence

• docs/hooks.py:81-84 reads only README.md and example.yml for each generated workflow page.
• docs/hooks.py:114 appends a single ## Example Workflow YAML block.
• Existing tests already cover _generate_page behavior in tests/test_docs_hooks.py:22-60, so there is a natural place for coverage.
• The repository already ships chained examples for five detector workflows: gh-agent-workflows/bug-hunter/example-chained.yml, gh-agent-workflows/code-complexity-detector/example-chained.yml, gh-agent-workflows/code-duplication-detector/example-chained.yml, gh-agent-workflows/newbie-contributor-patrol/example-chained.yml, and gh-agent-workflows/test-coverage-detector/example-chained.yml.
• docs/workflows/gh-agent-workflows/bugs.md:19-27 already advertises a chained install path, but the generator still only embeds example.yml on generated pages.

Duplicate check: this is distinct from #1441 (new comment-only chained templates), #887 (permissions in chaining quick-start), #1201 (homepage Bug Hunter setup path), and #849 (Text Auditor chained setup visibility). This proposal is the small reusable docs-generator feature that surfaces alternate examples that already exist.

What is this? | From workflow: Trigger Product Manager Impersonator

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.