Improve documentation structure and content across GitHub Actions Runner

[Copilot]

This PR significantly enhances the documentation for the GitHub Actions Runner repository to improve user experience and reduce setup friction. The changes address several pain points identified in the existing documentation while maintaining consistency with the project's style and structure.

Key Improvements Made

📚 Enhanced Main README

• Restructured the main README with clearer sections for "Documentation and Resources" and "Support and Community"
• Improved the download/install section with better formatting and clearer platform distinctions
• Clarified contribution guidelines and support channels to reduce confusion
• Added direct links to comprehensive documentation index and troubleshooting resources

🛠️ Comprehensive OS Prerequisites

Updated all platform-specific setup guides with detailed instructions and troubleshooting:

Linux (docs/start/envlinux.md):

• Added manual installation commands for all supported distributions (Debian, Fedora, SUSE)
• Included comprehensive troubleshooting section with common issues and solutions
• Enhanced dependency information with specific package versions

Windows (docs/start/envwin.md):

• Added complete setup workflow with PowerShell examples
• Included system requirements, Visual Studio setup, and Windows-specific considerations
• Added troubleshooting for common issues like execution policies and firewall configuration

macOS (docs/start/envosx.md):

• Added detailed setup instructions with Homebrew integration
• Included Xcode configuration and code signing considerations
• Added macOS-specific troubleshooting for Gatekeeper and launchd services

📖 Improved Navigation and Structure

• Created comprehensive documentation index (docs/README.md) with organized sections and quick navigation
• Added table of contents to the contribution guide (docs/contribute.md)
• Fixed broken internal references and improved cross-linking between documents
• Created troubleshooting quick reference (docs/checks/README.md) with categorized issue types

🔧 Enhanced Automation Documentation

• Added extensive troubleshooting section to docs/automate.md with common issues and solutions
• Included advanced examples for organization-level runners and GitHub Enterprise scenarios
• Added network connectivity testing and PAT token validation steps

Problem Solved

The original documentation had several issues that created friction for users:

• Inconsistent messaging about contributions vs. the detailed contribution guide
• Very basic OS prerequisite files that left users struggling with setup
• Broken internal links and poor navigation structure
• Limited troubleshooting information forcing users to search elsewhere

Impact

These improvements provide:

• Faster Onboarding: Clear, step-by-step instructions reduce trial-and-error setup time
• Better Problem Resolution: Comprehensive troubleshooting sections address common issues proactively
• Improved Discoverability: Well-organized index and cross-references help users find information quickly
• Support for All Platforms: Detailed, platform-specific guidance ensures consistent experience across Windows, macOS, and Linux

The documentation now serves as a complete resource for both new users getting started and experienced users implementing advanced configurations, while maintaining the project's existing style and approach.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/TingluoHuang/REDACTED_L0/tarball/RepositoryActionWithInvalidWrapperActionfile_Node
  • Triggering command: /home/REDACTED/work/REDACTED/REDACTED/_dotnetsdk/8.0.412/dotnet exec --runtimeconfig /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.runtimeconfig.json --depsfile /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.deps.json /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/testhost.dll --port 33609 --endpoint 127.0.0.1:033609 --role client --parentprocessid 4147 --telemetryoptedin false (http block)
• https://api.github.com/repos/TingluoHuang/REDACTED_L0/tarball/repositoryactionwithactionfileanddockerfile
  • Triggering command: /home/REDACTED/work/REDACTED/REDACTED/_dotnetsdk/8.0.412/dotnet exec --runtimeconfig /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.runtimeconfig.json --depsfile /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.deps.json /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/testhost.dll --port 33609 --endpoint 127.0.0.1:033609 --role client --parentprocessid 4147 --telemetryoptedin false (http block)
• https://api.github.com/repos/TingluoHuang/REDACTED_L0/tarball/repositoryactionwithdockerfile
  • Triggering command: /home/REDACTED/work/REDACTED/REDACTED/_dotnetsdk/8.0.412/dotnet exec --runtimeconfig /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.runtimeconfig.json --depsfile /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.deps.json /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/testhost.dll --port 33609 --endpoint 127.0.0.1:033609 --role client --parentprocessid 4147 --telemetryoptedin false (http block)
• https://api.github.com/repos/actions/download-artifact/tarball/master
  • Triggering command: /home/REDACTED/work/REDACTED/REDACTED/_dotnetsdk/8.0.412/dotnet exec --runtimeconfig /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.runtimeconfig.json --depsfile /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.deps.json /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/testhost.dll --port 33609 --endpoint 127.0.0.1:033609 --role client --parentprocessid 4147 --telemetryoptedin false (http block)
• https://api.github.com/repos/actions/setup-node/tarball/v1
  • Triggering command: /home/REDACTED/work/REDACTED/REDACTED/_dotnetsdk/8.0.412/dotnet exec --runtimeconfig /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.runtimeconfig.json --depsfile /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/Test.deps.json /home/REDACTED/work/REDACTED/REDACTED/src/Test/bin/Debug/net8.0/testhost.dll --port 33609 --endpoint 127.0.0.1:033609 --role client --parentprocessid 4147 --telemetryoptedin false (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.