diff --git a/readme.md b/readme.md
index e817bfd..c452a15 100644
--- a/readme.md
+++ b/readme.md
@@ -1,31 +1,76 @@
 # Create Gitea Pull Request
 
-Opens a pull request on Gitea. Use this after your workflow has already **pushed a branch**. This action does not change git; it only tells Gitea “merge this branch into that one”.
+Opens a pull request on Gitea. The source branch must already exist on the remote. This action does not commit or push; it only asks Gitea to open a PR from `head` into `base`.
 
-**Before this step:** commit your changes and `git push` the source branch.
+**Before this step:** commit your changes and push the source branch.
+
+## Minimal example
+
+Same repository, target branch `main` (the default):
 
 ```yaml
-- uses: https://gitea.psi.ch/pombas_n/pullrequest@main
-  id: pr
+- uses: actions/pullrequest@v1
   with:
-    token: ${{ secrets.GITHUB_TOKEN }}   # needs permission to create pull requests
-    repository: linux/WebHosting_DMZ     # owner/repo; omit to use this workflow's repo
-    title: Fix markdown typos            # what people see in the PR list
-    body: Automated typo fixes.          # optional description
-    head: typos                          # branch that has the changes (already pushed)
-    base: master                         # branch you want to merge into
+    token: ${{ secrets.GITHUB_TOKEN }}
+    title: Fix markdown typos
+    head: typos
+    base: main
 ```
 
-Then you can print the result:
+## Full example
+
+```yaml
+- uses: actions/pullrequest@v1
+  id: pr
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    gitea_url: https://gitea.psi.ch
+    repository: linux/WebHosting_DMZ
+    title: Fix markdown typos
+    body: Automated typo fixes.
+    head: typos
+    base: master
+```
+
+Print the created PR:
 
 ```yaml
 - run: echo "${{ steps.pr.outputs.html_url }}"
 ```
 
-`head` is the branch with the work. `base` is the target. For a fork use `owner:branch` as `head`.
+`head` is the branch with the changes. `base` is the branch you merge into. For a fork, set `head` to `owner:branch`.
 
-If an open PR for the same `head` → `base` already exists, the action reuses it instead of failing. Set `allow_existing: "false"` if you want a failure instead.
+If `gitea_url` is omitted, the action uses `${{ github.server_url }}` (the instance running the workflow). If `repository` is omitted, it uses `${{ github.repository }}`.
 
-Optional: `gitea_url` (default `https://gitea.psi.ch`).
+## Token (`secrets.GITHUB_TOKEN`)
 
-Outputs: `number`, `url` (API), `html_url` (browser).
+Pass a token with permission to create pull requests.
+
+In Gitea Actions, `${{ secrets.GITHUB_TOKEN }}` is the default token for the workflow. It is enough when:
+
+- the job runs in the **same repository** as the PR, and
+- the token is allowed to write (create pull requests / push related refs).
+
+Use a **personal access token** (or another repo secret) instead when you open a PR in a **different** repository, or when the default token cannot create pull requests.
+
+Do not print the token in logs.
+
+## Inputs
+
+| Input | Required | Default | Description |
+| --- | --- | --- | --- |
+| `token` | yes | - | Token with pull-request write access |
+| `title` | yes | - | Pull request title |
+| `head` | yes | - | Source branch (`owner:branch` for forks) |
+| `body` | no | empty | Pull request description |
+| `base` | no | `main` | Target branch |
+| `repository` | no | current repo | Target as `owner/repo` |
+| `gitea_url` | no | current instance | Gitea base URL |
+
+## Outputs
+
+| Output | Description |
+| --- | --- |
+| `number` | Pull request number |
+| `url` | API URL |
+| `html_url` | Browser URL |