diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a163c30
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# gitea-ai-pr
+
+A Gitea composite action that posts AI-generated code review comments on pull requests using any OpenAI-compatible API endpoint.
+
+## Features
+
+- Posts a review comment on every PR open/update event
+- Tracks previous reviews and generates incremental diffs on subsequent pushes, so the model only sees what changed
+- Truncates diffs larger than 12 KB to stay within token limits
+- Works with any OpenAI-compatible endpoint (OpenAI, local models via Ollama, etc.)
+
+## Usage
+
+Add the following workflow to your repository at `.gitea/workflows/ai-pr-review.yml`:
+
+```yaml
+name: AI PR Review
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: <org>/gitea-ai-pr@main
+        with:
+          api_url: ${{ secrets.AI_API_URL }}
+          api_key: ${{ secrets.AI_API_KEY }}
+          # model: openai/gpt-oss-120b  # optional, this is the default
+```
+
+## Inputs
+
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `api_url` | Yes | — | Base URL of the OpenAI-compatible API (e.g. `https://api.openai.com/v1`) |
+| `api_key` | Yes | — | API key for the endpoint |
+| `model` | No | `openai/gpt-oss-120b` | Model identifier |
+| `github_token` | No | `${{ github.token }}` | Token used to post comments and fetch PR history |
+
+## How It Works
+
+1. **Fetch context** — checks existing PR comments for a previous AI review and the commit SHA it covered.
+2. **Generate diff** — produces a full diff against `main`, or an incremental diff from the previously reviewed commit if one exists.
+3. **Run review** — calls the configured model via the chat completions API. Incremental runs pass the previous review as conversation history so the model can track resolved and new issues.
+4. **Post comment** — posts the review as a PR comment with a hidden SHA marker used by future runs.
+
+## Secrets
+
+Set the following secrets in your Gitea repository settings:
+
+- `AI_API_URL` — base URL of the API endpoint
+- `AI_API_KEY` — API key
+
+## License
+
+MIT