diff --git a/README.md b/README.md
new file mode 100644
index 0000000..999306d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+# uv-cache
+
+This is a very simple action that sets up cache support for `uv`. It doesn't do
+anything else. I wrote this to work well with
+[based-alpine](https://git.ficd.sh/ficd/based-alpine).
+
+## Requirements
+
+All dependencies `actions/cache@v4` must be satisfied, and `uv` must be
+available on the path.
+
+## Usage
+
+Using this action is very simple. We also provide one output: `cache-hit`, which
+is either "true" or "false".
+
+```yaml
+# you should always checkout first
+# otherwise there is nothing to check cache against
+- name: checkout source
+  uses: actions/checkout@v4
+- name: setup cache
+  # assign the id if you want to check the boolean later
+  id: uv-cache
+  uses: https://git.ficd.sh/ficd/uv-cache@v1
+- name: Check cache status
+  run: |
+    echo "Cache hit? ${{ steps.uv-cache.outputs.cache-hit }}"
+```
diff --git a/action.yml b/action.yml
index 4ab22f8..909304f 100644
--- a/action.yml
+++ b/action.yml
@@ -1,6 +1,10 @@
 name: Setup uv cache
 description: Composite action to determine uv cache dir and restore cache.
 author: Daniel Fichtinger
+outputs:
+  cache-hit:
+    description: "Whether the uv cache was restored"
+    value: ${{ steps.cache-output.outputs.cache-hit }}
 runs:
   using: "composite"
   steps:
@@ -10,9 +14,15 @@ runs:
       run: |
         echo "dir=$(uv cache dir)" >> "$GITHUB_OUTPUT"
     - name: Restore uv cache
+      id: cache-restore
       uses: actions/cache@v4
       with:
         path: ${{ steps.uv-cache.outputs.dir }}
         key: ${{ runner.os }}-uv-${{ hashFiles('**/*requirements*.txt', '**/*requirements*.in', '**/*constraints*.txt', '**/*constraints*.in', '**/pyproject.toml', '**/uv.lock') }}
         restore-keys: |
           ${{ runner.os }}-uv-
+    - name: Capture cache-hit output
+      id: cache-output
+      shell: bash
+      run: |
+        echo "cache-hit=${{ steps.cache-restore.outputs.cache-hit }}" >> "$GITHUB_OUTPUT"