diff --git a/README.md b/README.md
index 3cec246..e4bbc05 100644
--- a/README.md
+++ b/README.md
@@ -38,3 +38,15 @@ This repository contains GitHub Actions that are used by various projects at Q42
     </tr>
   </tbody>
 </table>
+
+## Requirements
+
+These actions target iOS/Xcode workflows and must run on a macOS runner (e.g. `runs-on: macos-latest`). 
+They rely on macOS-only tooling such as `security`, `uuidgen`, and Xcode/keychain paths.
+
+## Versioning
+
+Reference an action by tag:
+
+- `@v1` — a moving major-version tag that tracks the latest release in the `v1` line. Convenient, but the underlying commit changes over time.
+- `@v1.0.0` — an immutable tag pinned to a specific release. Prefer this when you need reproducible builds.
diff --git a/install-certificate/README.md b/install-certificate/README.md
index 8ce9bef..831815a 100644
--- a/install-certificate/README.md
+++ b/install-certificate/README.md
@@ -1,6 +1,16 @@
-## [install-certificate](https://github.com/q42/actions/blob/main/install-certificate/action.yml)
+# [install-certificate](https://github.com/q42/actions/blob/main/install-certificate/action.yml)
 
-Installs the specified certificate in the keychain.
+Installs the code signing certificate(s) from a base64-encoded P12 file into a temporary keychain. A P12 may contain more than one certificate; all of them are imported.
+
+## Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `build-certificate-base64` | yes | The base64-encoded P12 build certificate. |
+| `certificate-password` | yes | The password for the P12 build certificate. |
+| `keychain-password` | no | Password for the temporary keychain the certificate is imported into. Defaults to a randomly generated value (`uuidgen`) when unset or empty, which is fine for most CI runs. |
+
+## Example
 
 ```yml
 - name: Install Certificate
diff --git a/install-provisioning-profile/README.md b/install-provisioning-profile/README.md
index ffe6682..bee54fc 100644
--- a/install-provisioning-profile/README.md
+++ b/install-provisioning-profile/README.md
@@ -1,10 +1,20 @@
-## [install-provisioning-profile](https://github.com/q42/actions/blob/main/install-provisioning-profile/action.yml)
+# [install-provisioning-profile](https://github.com/q42/actions/blob/main/install-provisioning-profile/action.yml)
 
 Installs the specified provisioning profile so that Xcode can use it.
 
+## Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `build-provision-profile-base64` | yes | The base64-encoded build provisioning profile. |
+
+## Example
+
 ```yml
 - name: Install Provisioning Profile
   uses: q42/actions/install-provisioning-profile@v1
   with:
     build-provision-profile-base64: ${{ vars.PROVISIONING_PROFILE_PRODUCTION }}
 ```
+
+The example reads from `vars` rather than `secrets` because a provisioning profile is not sensitive (it contains no private key). Storing it as a repository/organization variable keeps it out of your secret store; using a secret works too.
diff --git a/upload-symbols-to-firebase/README.md b/upload-symbols-to-firebase/README.md
index ad7386b..2f1eb0e 100644
--- a/upload-symbols-to-firebase/README.md
+++ b/upload-symbols-to-firebase/README.md
@@ -1,12 +1,21 @@
-## [upload-symbols-to-firebase](https://github.com/q42/actions/blob/main/upload-symbols-to-firebase/action.yml)
+# [upload-symbols-to-firebase](https://github.com/q42/actions/blob/main/upload-symbols-to-firebase/action.yml)
 
 Uploads dSYM files to Firebase Crashlytics using the `upload-symbols` tool from the Firebase iOS SDK.
 
-The action needs to locate the `upload-symbols` binary, which ships as part of the Firebase iOS SDK SPM package. There are three ways to point it at the tool, in order of precedence: an explicit `upload-symbols-path`, a custom `source-packages-path`, or auto-discovery inside `derived-data-path`.
+The action needs to locate the `upload-symbols` binary, which ships as part of the Firebase iOS SDK SPM package. 
+There are three ways to point it at the tool, in order of precedence: an explicit `upload-symbols-path`, a custom `source-packages-path`, or auto-discovery inside `derived-data-path`.
 
-The `archive-path` parameter should point to an Xcode archive bundle (`.xcarchive`). Any dSYM files contained within this archive will be uploaded to Firebase.
+## Inputs
 
-The `google-service-info-plist` specifies the path to the `GoogleService-Info.plist` file for your Firebase project.
+| Input | Required | Description |
+| --- | --- | --- |
+| `derived-data-path` | yes | Path to the Xcode DerivedData directory. Used to discover the `upload-symbols` tool when neither `upload-symbols-path` nor `source-packages-path` is set. |
+| `google-service-info-plist` | yes | Path to the `GoogleService-Info.plist` file for the target Firebase project. |
+| `archive-path` | yes | Path to the `.xcarchive` bundle. dSYMs are read from its `dSYMs` directory. |
+| `source-packages-path` | no | Custom cloned source packages directory (the value passed to `-clonedSourcePackagesDirPath`). Searched for the tool before falling back to the SPM checkout inside `derived-data-path`. |
+| `upload-symbols-path` | no | Explicit path to the `upload-symbols` tool. Takes precedence over all discovery strategies. |
+
+## Examples
 
 ### Discover via DerivedData