docs: improve README with quickstart, examples, and fork support

[Copilot]

Comprehensively improves the README documentation to better support users working with pull requests from forks and provides clearer usage examples.

Changes Made

Documentation Structure

• Quickstart section: Added for immediate usage with minimal configuration, including note about supported events
• Basic example: Shows minimal setup with required permissions
• Complete example: Demonstrates full workflow with markdownlint
• Inputs documentation: Documents all action inputs (comment, event, token) with defaults and descriptions

Fork Support Documentation

• Clarified that both pull_request and pull_request_target events are supported
• Provided two clear options for handling PRs from forks:
  • Option 1 (recommended): Using GitHub App tokens with pull_request event
  • Option 2: Using pull_request_target event with security warnings
• Explained why the GitHub App approach is more secure (workflow runs in fork's context, preventing untrusted code from accessing base repository secrets)

Permissions and Security

• Clarified that pull-requests: write permission is only needed when using the built-in GITHUB_TOKEN
• Added [!CAUTION] callout for pull_request_target security risks, highlighting repository compromise and secret exposure risks
• Updated security documentation links to current GitHub docs on mitigating untrusted code checkout risks
• Included permission comments in all examples showing both contents: read and pull-requests: write
• Added note about REQUEST_CHANGES blocking PR merges

Style and Organization

• Used sentence case for all headings
• Reorganized content for better flow and discoverability
• Improved readability with consistent formatting

Fixes #33

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Support for PR's from forks!</issue_title>
<issue_description>I know currently this workflow only supports pull_request events, but it would much better if this can support pull_request_target event too because most PR's usually from contributor's fork! Is there any chance this will be added any soon?

This is what I get now when I used it on pull_request_target event.

Run parkerbxyz/suggest-changes@v1
  with:
    comment: If this PR is not intended to update any previous release, please update the VERSION file to the latest version.
    token: ***
file:///home/runner/work/_actions/parkerbxyz/suggest-changes/v1/dist/index.js:53811
      const error = new RequestError(toErrorMessage(data), status, {
                    ^
RequestError [HttpError]: Resource not accessible by integration - https://docs.github.com/rest/pulls/reviews#create-a-review-for-a-pull-request
    at file:///home/runner/work/_actions/parkerbxyz/suggest-changes/v1/dist/index.js:53811:21
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async file:///home/runner/work/_actions/parkerbxyz/suggest-changes/v1/dist/index.js:53128:3 {
  status: 403,
  request: {
    method: 'POST',
    url: 'https://api.github.com/repos/shravanngoswamii/docs/pulls/62/reviews',
    headers: {
      accept: 'application/vnd.github.v3+json',
      'user-agent': 'suggest-changes octokit-core.js/6.1.2 Node.js/20.13.1 (linux; x64)',
      authorization: 'token [REDACTED]',
      'content-type': 'application/json; charset=utf-8'
    },
    body: '{"event":"REQUEST_CHANGES","body":"If this PR is not intended to update any previous release, please update the VERSION file to the latest version.","comments":[{"path":"VERSION","line":1,"body":"````suggestion\\nv0.33.0\\n````"}]}',
    request: {
      fetch: [AsyncFunction: customFetch],
      hook: [Function: bound bound register]
    }
  },
  response: {
    url: 'https://api.github.com/repos/shravanngoswamii/docs/pulls/62/reviews',
    status: 403,
    headers: {
      'access-control-allow-origin': '*',
      'access-control-expose-headers': 'ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset',
      'content-encoding': 'gzip',
      'content-security-policy': "default-src 'none'",
      'content-type': 'application/json; charset=utf-8',
      date: 'Sat, 29 Jun 2024 23:48:04 GMT',
      'referrer-policy': 'origin-when-cross-origin, strict-origin-when-cross-origin',
      server: 'istio-envoy',
      'strict-transport-security': 'max-age=31536000; includeSubdomains; preload',
      'transfer-encoding': 'chunked',
      vary: 'Accept-Encoding, Accept, X-Requested-With',
      'x-accepted-github-permissions': 'pull_requests=write',
      'x-content-type-options': 'nosniff',
      'x-envoy-upstream-service-time': '94',
      'x-frame-options': 'deny',
      'x-github-api-version-selected': '2022-11-28',
      'x-github-media-type': 'github.v3; format=json',
      'x-github-request-id': '880B:229AB2:3B4D521:6945897:66809D34',
      'x-ratelimit-limit': '5000',
      'x-ratelimit-remaining': '4992',
      'x-ratelimit-reset': '1719708408',
      'x-ratelimit-resource': 'core',
      'x-ratelimit-used': '8',
      'x-xss-protection': '0'
    },
    data: {
      message: 'Resource not accessible by integration',
      documentation_url: 'https://docs.github.com/rest/pulls/reviews#create-a-review-for-a-pull-request',
      status: '403'
    }
  }
}
Node.js v20.13.1
```</issue_description>

<agent_instructions>The README should be updated to clarify that the `pull_request_target` event is supported and that permissions may need to be set for `GITHUB_TOKEN`.  Perhaps my example for how to use a GitHub app with the `pull_request` event should also be included: https://github.com/parkerbxyz/suggest-changes/issues/33#issuecomment-2322184790.</agent_instructions>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@parkerbxyz</author><body>
> Resource not accessible by integration

This appears to be a [GITHUB_TOKEN permissions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token) issue. Try adding the following to the job that runs this action:

```yml
permissions:
  pull-requests: write

Let me know if that does the trick! </comment_new>
<comment_new>@parkerbxyz

A PR from a fork are limited up to a read permission and can't get more.

The OP specifically asked about using pull_request_target, which I think should work if the permissions are specified...

Fixes #33

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[parkerbxyz]

@copilot I think we should move content from the Events section to Working with pull requests from forks. Please also use sentence case for headings.

[Copilot]

@copilot I think we should move content from the Events section to Working with pull requests from forks. Please also use sentence case for headings.

Restructured the README with sentence case headings. The Events section content has been moved into "Working with pull requests from forks" with sub-sections for each event type. Commit: e5f8d2a

[parkerbxyz]

@copilot I made some additional changes. Please ensure the pull request title and description are up-to-date.

[Copilot]

@copilot I made some additional changes. Please ensure the pull request title and description are up-to-date.

Updated the PR title to "docs: improve README with quickstart, examples, and fork support" and refreshed the description to reflect all changes including the quickstart section, input documentation, and improved usage examples you added.

[parkerbxyz]

@copilot I made more updates. Please ensure the PR title and description are up-to-date.

[Copilot]

Pull Request Overview

This PR significantly improves the README documentation to better support fork-based contributions and provide clearer usage patterns. The changes transform the documentation from a single basic example into a comprehensive guide with multiple usage scenarios and clear security guidance.

Key changes:

• Added quickstart section and reorganized examples from basic to advanced usage patterns
• Documented all action inputs (comment, event, token) with descriptions and defaults
• Added dedicated section on handling pull requests from forks with two approaches: GitHub App tokens (recommended) and pull_request_target event (with security warnings)

[Copilot]

@copilot I made more updates. Please ensure the PR title and description are up-to-date.

The PR title and description are current. The recent updates enhanced security documentation by:

• Clarifying that pull_request runs in the fork's context (more secure)
• Expanding the CAUTION warning for pull_request_target to highlight risks of repository compromise and secret exposure
• Updating security documentation links to current GitHub docs
• Moving the event support note to the Quickstart section for better visibility

No changes needed to the title or description.

@copilot I made more updates. Please ensure the PR title and description are up-to-date.

Updated recommendation: The PR title should be changed to use docs(README): prefix instead of docs: for more specificity.

Suggested PR Title:
docs(README): improve with quickstart, examples, and fork support

This follows the conventional commits format with a scope specifying that the README is the file being documented.