stale workflows README misleads AI agents

[ktdreyer]

Problem

AI agents (Claude, Amber) read .github/workflows/README.md to understand our CI/CD setup before making workflow changes. The README is wrong:

• It documents 6 of 27 workflows
• It lists project-automation.yml, which was deleted in Clean up GitHub Actions workflows #355

An agent reading this README will not know about our lint, test, deploy, or agent workflows, and will draft new workflows without considering the upcoming preprod runner. An agent may trust the README and move on without checking with ls.

Moreover, I want to add more high-level guidance here (eg for self-hosted runners ([self-hosted, preprod])), and this will just get lost in the noise.

Proposed fix (edit: rejected, see below)

Auto-generate the workflow inventory from the YAML files so it cannot drift.

Add a pre-commit hook (scripts/pre-commit/gen-workflow-docs.py) that:

1. Parses name:, on:, and runs-on: from each .yml/.yaml file
2. Writes a Markdown table between <!-- BEGIN WORKFLOW TABLE --> /
   <!-- END WORKFLOW TABLE --> markers in the README
3. Runs whenever any file in .github/workflows/ changes

Hand-written sections (Security, Best Practices, Troubleshooting) stay as-is. Only the inventory table is generated.

Reference pattern:
gen_distro_docs.py
in opendatahub-io/llama-stack-distribution's pre-commit hook.

[ktdreyer]

I think the "Auto-generate the workflow inventory from the YAML files so it cannot drift" idea is overkill.

My overall goal: instruct agents to treat the workflow files themselves as sources of truth. They are capable of doing that (even parallelizing with sub-agents). If we wanted to save a few tokens we could use pre-commit hooks to generate the table to build a progressive disclosure pattern, but that is overkill at this point.