diff --git a/README.md b/README.md
index 2a083ba..61d9b9a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,60 @@
-# tf-pr-commenter
+# Terraform/OpenTofu PR Commenter
 
+This action posts the results of Terraform or OpenTofu commands (`fmt`, `init`, `plan`, `validate`) as pull request comments on **GitHub** or **Gitea**. It is designed to work with CI workflows and ensures every command posts a comment, even if it succeeds.
+
+---
+
+## Features
+
+- Supports Terraform and OpenTofu.
+- Works on GitHub Actions and Gitea Actions.
+- Posts `fmt` and `plan` outputs with syntax-highlighted diffs.
+- `init` and `validate` outputs are posted in expandable `<details>` blocks.
+- Automatically updates existing comments or creates new ones.
+- Supports per-file diffs for `fmt`.
+
+---
+
+## Inputs
+
+| Input | Description | Required | Default |
+|-------|-------------|----------|---------|
+| `command` | Command type (`fmt`, `init`, `plan`, `validate`) | Yes | — |
+| `commenter_input` | Stdout or newline-separated file list from the previous step | Yes | — |
+| `commenter_exitcode` | Exit code from the previous step | Yes | — |
+| `pr_number` | Pull request number | No | — |
+| `pr_comments_url` | URL for PR comments API | No | — |
+| `pr_comment_uri` | URI for individual PR comment API | No | — |
+| `github_token` | GitHub token (for GitHub Actions) | No | — |
+| `gitea_token` | Gitea token (for Gitea Actions) | No | — |
+| `gitea_action` | Set to `true` if running in Gitea Actions | No | `false` |
+| `gitea_api_url` | Gitea API URL | No | — |
+| `gitea_repository` | Gitea repository (`owner/repo`) | No | — |
+| `highlight_changes` | Enable diff highlighting | No | `true` |
+| `tf_workspace` | Terraform/OpenTofu workspace | No | `default` |
+
+---
+
+## Usage
+
+### GitHub Actions Example
+
+```yaml
+- name: Tofu Plan PR Comment
+  uses: ./actions/tf-pr-comment
+  with:
+    command: plan
+    commenter_input: ${{ steps.tofu-plan.outputs.plan-output }}
+    commenter_exitcode: ${{ steps.tofu-plan.outputs.exitcode }}
+  env:
+    PR_NUMBER: ${{ needs.check-and-create-pr.outputs.pr_number }}
+    PR_COMMENTS_URL: ${{ needs.check-and-create-pr.outputs.pr_comments_url }}
+    PR_COMMENT_URI: ${{ needs.check-and-create-pr.outputs.pr_comment_uri }}
+    GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN }}
+```
+
+## Notes
+
+* For fmt, it is recommended to pass a newline-separated list of files from a previous step to properly generate per-file diffs.
+* The action automatically creates or updates PR comments, so duplicate comments are avoided.
+* Diff syntax highlighting works on GitHub. On Gitea, diffs are shown in plain text.
\ No newline at end of file