Enhance contribution guide, automation docs, and add documentation index

Co-authored-by: salmanmkc <32169182+salmanmkc@users.noreply.github.com>

docs/README.md

@@ -0,0 +1,61 @@
+# GitHub Actions Runner Documentation
+
+Welcome to the GitHub Actions Runner documentation. This guide will help you get started with self-hosted runners, contribute to the project, and troubleshoot common issues.
+
+## 🚀 Getting Started
+
+### Installation and Setup
+- **[Linux Prerequisites](start/envlinux.md)** - Complete setup guide for Linux systems
+- **[Windows Prerequisites](start/envwin.md)** - Complete setup guide for Windows systems  
+- **[macOS Prerequisites](start/envosx.md)** - Complete setup guide for macOS systems
+
+### Quick Start
+1. Download the [latest runner release](https://github.com/actions/runner/releases)
+2. Follow the platform-specific prerequisites guide above
+3. Configure your runner with `./config.sh` (Linux/macOS) or `.\config.cmd` (Windows)
+4. Start the runner with `./run.sh` (Linux/macOS) or `.\run.cmd` (Windows)
+
+## 🔧 Administration and Automation
+
+- **[Automation Scripts](automate.md)** - Automate runner deployment and management
+- **[Troubleshooting Guides](checks/)** - Common issues and solutions
+
+## 🏗️ Development and Contributing
+
+- **[Contributing Guide](contribute.md)** - Development setup, building, and testing
+- **[Architecture Decision Records](adrs/README.md)** - Important architectural decisions and design patterns
+
+## 📋 Reference Materials
+
+### System Checks and Troubleshooting
+- **[Network Connectivity](checks/network.md)** - Troubleshoot network issues
+- **[Git Configuration](checks/git.md)** - Git-related problems
+- **[Actions Troubleshooting](checks/actions.md)** - Action-specific issues
+- **[SSL Certificate Issues](checks/sslcert.md)** - Certificate and TLS problems
+- **[Node.js Issues](checks/nodejs.md)** - Node.js runtime problems
+- **[Internet Connectivity](checks/internet.md)** - General connectivity issues
+
+### Development Resources
+- **[Visual Studio Code Setup](contribute/vscode.md)** - IDE configuration for development
+- **[Design Documentation](design/)** - Technical design documents
+
+## 🆘 Getting Help
+
+### Community Support
+- **[GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)** - Ask questions and get help from the community
+- **[GitHub Support](https://support.github.com/contact/bug-report)** - Report critical bugs or get professional support
+
+### Reporting Issues
+- **Bug Reports**: Open an issue in this repository
+- **Feature Requests**: Use [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions-and-packages)
+- **Security Issues**: Follow our [security policy](../security.md)
+
+## 📖 Additional Resources
+
+- **[GitHub Actions Documentation](https://docs.github.com/en/actions)** - Official GitHub Actions documentation
+- **[Self-hosted Runners Guide](https://docs.github.com/en/actions/hosting-your-own-runners)** - GitHub's official self-hosted runner documentation
+- **[Runner Releases](https://github.com/actions/runner/releases)** - Download the latest runner versions
+
+---
+
+> **Note**: This documentation is maintained by the GitHub Actions team and the community. If you find any issues or have suggestions for improvement, please open an issue or contribute a pull request.

docs/automate.md

@@ -76,3 +76,76 @@ Repo level one-liner.  NOTE: replace with yourorg/yourrepo (repo level) or just
 ```bash
 curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/delete.sh | bash -s yourorg/yourrepo runnername
 ```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Permission Denied
+```bash
+# Ensure scripts have execute permissions
+chmod +x ./config.sh ./run.sh
+```
+
+#### PAT Token Issues
+```bash
+# Verify your PAT has the correct scopes:
+# - repo (for repository-level runners)
+# - admin:org (for organization-level runners)
+export RUNNER_CFG_PAT=your_token_here
+echo $RUNNER_CFG_PAT  # Verify it's set
+```
+
+#### Network Connectivity
+```bash
+# Test GitHub connectivity
+curl -H "Authorization: token $RUNNER_CFG_PAT" https://api.github.com/user
+
+# For GitHub Enterprise Server
+curl -H "Authorization: token $RUNNER_CFG_PAT" https://your-github-enterprise/api/v3/user
+```
+
+#### Service Installation Fails
+```bash
+# Check if running as appropriate user
+whoami
+
+# For Linux - ensure systemd is available
+systemctl --version
+
+# For macOS - ensure launchd is available
+launchctl version
+```
+
+#### Runner Registration Fails
+```bash
+# Check if runner already exists
+curl -H "Authorization: token $RUNNER_CFG_PAT" \
+  "https://api.github.com/repos/OWNER/REPO/actions/runners"
+
+# Remove existing runner if needed
+./config.sh remove --token $RUNNER_CFG_PAT
+```
+
+### Getting Help
+
+- **Configuration Issues**: Check the [Prerequisites](start/envlinux.md) for your platform
+- **Network Problems**: Review [network troubleshooting guide](checks/network.md)
+- **General Support**: Visit [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)
+
+### Advanced Examples
+
+#### Organization-level Runner with Custom Labels
+```bash
+export RUNNER_CFG_PAT=your_org_pat
+curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | \
+  bash -s -- -s myorg -n prod-runner-1 -l production,linux,docker
+```
+
+#### Repository-level Runner for GitHub Enterprise
+```bash
+export RUNNER_CFG_PAT=your_ghe_pat
+curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | \
+  bash -s -- -s myorg/myrepo -g github.company.com -n build-server -u builder
+```
+```

docs/checks/README.md

@@ -0,0 +1,66 @@
+# Troubleshooting Guides
+
+This directory contains troubleshooting guides for common issues you might encounter when setting up or running GitHub Actions self-hosted runners.
+
+## Quick Reference
+
+| Issue Type | Guide | Description |
+|------------|-------|-------------|
+| 🌐 **Network** | [network.md](network.md) | Connection issues, proxy, firewall problems |
+| 🔒 **SSL/TLS** | [sslcert.md](sslcert.md) | Certificate and TLS handshake issues |
+| 📦 **Git** | [git.md](git.md) | Git configuration and repository access |
+| ⚡ **Actions** | [actions.md](actions.md) | Action-specific runtime issues |
+| 🟢 **Node.js** | [nodejs.md](nodejs.md) | Node.js runtime and npm issues |
+| 🌍 **Internet** | [internet.md](internet.md) | General internet connectivity |
+
+## Common First Steps
+
+Before diving into specific guides, try these general troubleshooting steps:
+
+### 1. Check Basic Connectivity
+```bash
+# Test GitHub API access
+curl -I https://api.github.com/
+
+# For GitHub Enterprise Server
+curl -I https://your-github-enterprise.com/api/v3/
+```
+
+### 2. Verify Runner Status
+```bash
+# Check if runner service is running
+./svc.sh status
+
+# View recent logs
+tail -f _diag/Runner_*.log
+```
+
+### 3. Test Runner Configuration
+```bash
+# Re-run configuration
+./config.sh
+
+# Test connection without running
+./run.sh --check
+```
+
+## Getting Additional Help
+
+If these guides don't resolve your issue:
+
+1. **Search existing issues** in the [runner repository](https://github.com/actions/runner/issues)
+2. **Check GitHub Status** at [githubstatus.com](https://githubstatus.com)
+3. **Ask the community** in [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)
+4. **Contact support** for critical issues via [GitHub Support](https://support.github.com/contact)
+
+## Contributing
+
+Found a solution to a common problem not covered here? Consider contributing:
+
+1. Create a new `.md` file for the issue type
+2. Follow the format of existing guides
+3. Submit a pull request with your improvements
+
+---
+
+💡 **Tip**: Always check the `_diag/` directory for detailed log files when troubleshooting issues.

docs/contribute.md

@@ -1,5 +1,24 @@
 # Contributions
 
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Issues](#issues)
+- [Enhancements and Feature Requests](#enhancements-and-feature-requests)
+- [Required Dev Dependencies](#required-dev-dependencies)
+- [Quickstart: Run a Job from a Real Repository](#quickstart-run-a-job-from-a-real-repository)
+- [Development Life Cycle](#development-life-cycle)
+  - [Clone Repository](#clone-repository)
+  - [Build Layout](#build-layout)
+  - [Test Layout](#test-layout)
+  - [Configure Runner](#configure-runner)
+  - [Run Runner](#run-runner)
+  - [View Logs](#view-logs)
+- [Editors](#editors)
+- [Styling](#styling)
+
+## Getting Started
+
 We welcome contributions in the form of issues and pull requests. We view the contributions and the process as the same for github and external contributors. Please note the runner typically requires changes across the entire system and we aim for issues in the runner to be entirely self contained and fixable here. Therefore, we will primarily handle bug issues opened in this repo and we kindly request you to create all feature and enhancement requests on the [GitHub Feedback](https://github.com/community/community/discussions/categories/actions-and-packages) page. 
 
 > IMPORTANT: Building your own runner is critical for the dev inner loop process when contributing changes.  However, only runners built and distributed by GitHub (releases) are supported in production.  Be aware that workflows and orchestrations run service side with the runner being a remote process to run steps.  For that reason, the service can pull the runner forward so customizations can be lost.
@@ -124,8 +143,8 @@ cd runner/_layout
 ./config.(sh/cmd) # configure your custom runner
 ```
 
-You will need your the name of your repository and a runner registration token.
-Check [Quickstart](##Quickstart:-Run-a-job-from-a-real-repository) if you don't know how to get this token.
+You will need the name of your repository and a runner registration token.
+Check the [Quickstart section](#quickstart-run-a-job-from-a-real-repository) if you don't know how to get this token.
 
 These can also be passed down as arguments to `config.(sh/cmd)`:
 ```bash