Update docs

README.md

@@ -6,6 +6,22 @@ A GitHub action to create a repository dispatch event.
 
 ## Usage
 
+Dispatch to the current repository by elivating the permissions of the default `GITHUB_TOKEN`.
+```yml
+permissions:
+  actions: write
+
+jobs:
+  repositorydispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Repository Dispatch
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          event-type: my-event
+```
+
+Dispatch to a remote repository using a `repo` scoped GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
 ```yml
       - name: Repository Dispatch
         uses: peter-evans/repository-dispatch@v2
@@ -18,22 +34,23 @@ A GitHub action to create a repository dispatch event.
 
 | Name | Description | Default |
 | --- | --- | --- |
-| `token` | (**required**) A GitHub access token with `actions: write` permission to the repository being dispatched. | |
+| `token` | (**required**) `GITHUB_TOKEN` (permissions `actions: write`) or a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). See [token](#token) for further details. | `GITHUB_TOKEN` |
 | `repository` | The full name of the repository to send the dispatch. | `github.repository` (current repository) |
 | `event-type` | (**required**) A custom webhook event name. | |
 | `client-payload` | JSON payload with extra information about the webhook event that your action or workflow may use. | `{}` |
 
 #### `token`
 
-This action creates [`repository_dispatch`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. The default `GITHUB_TOKEN` 
+This action creates [`repository_dispatch`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events.
-token can only be used if you are dispatching the same repo. In this case you must assign the permission `action: write` to the token, see [permissions api](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs). Example:
+The default `GITHUB_TOKEN` token can only be used if you are dispatching the same repository that the workflow is executing in.
+In this case you must [elevate the token permissions](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) to allow the dispatch.
+
 ```yaml
 permissions:
   actions: write
 ```
 
-The solution to trigger other repositories is to manually create a [PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and store it as a secret e.g. `${{ secrets.PERSONAL_TOKEN }}`.
+To dispatch to a remote repository you must create a [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with the `repo` scope and store it as a secret.
-
 If you will be dispatching to a public repository then you can use the more limited `public_repo` scope.
 
 ## Example