Publish troubleshooting guide for common CI failures #23

Summary

Author a troubleshooting guide covering frequent CI issues: missing runner versions, cache pitfalls, failed tag lookups, and security gate skips. Link to versions manifests and setup-python references.

Why

When the action skips or fails, users need actionable steps. Centralizing guidance reduces support load and accelerates fixes.

What needs to happen

• Compile common failure modes from issues/support history (runner availability, registry misses, cache misses, etc.).
• Document root causes, mitigation steps, and relevant links (versions manifest, setup-python docs, etc.).
• Ensure the guide stays updated as new features (runner gate, registry checks) land.
• Link the guide from README and PR templates if helpful.

References

• Roadmap quality item: "Troubleshooting guide".
• https://github.com/actions/python-versions
• https://github.com/actions/setup-python

Acceptance criteria

• Troubleshooting guide exists in docs with discrete sections per failure mode.
• README or contributing docs link to the guide.
• Content references authoritative upstream docs for runner versions and setup guidance.