diff --git a/README.md b/README.md
index d50fbed..bb15360 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,8 @@ Based on the [Determinate Nix Installer](https://github.com/DeterminateSystems/n
 
 ## ️🔧 Usage
 
+Here's an example Actions workflow configuration that uses `determinate-nix-action`:
+
 ```yaml
 on:
   pull_request:
@@ -43,18 +45,21 @@ on:
     branches: [main]
 
 jobs:
-  lints:
-    name: Build
+  build-pkg:
+    name: Build Nix package
     runs-on: ubuntu-latest
     permissions:
-      id-token: "write"
-      contents: "read"
+      id-token: write
+      contents: read
     steps:
       - uses: actions/checkout@v4.2.2
       - uses: DeterminateSystems/determinate-nix-action@main # or v3.5.2 to pin to a release
       - run: nix build .
 ```
 
+> [!IMPORTANT]
+> If you use [FlakeHub], you need to add a `permissions` block like the one in the example above or else Determinate Nix can't authenticate with FlakeHub or [FlakeHub Cache][cache].
+
 ## 📌 Version Pinning: Lock It Down!
 
 ### Why Pin Your Action?
@@ -124,3 +129,6 @@ We're committed to making your experience with Determinate Nix as smooth as poss
 - 📧 **Need direct support?** Email us at [support@determinate.systems](mailto:support@determinate.systems)
 
 🤝 **Looking for enterprise support?** We offer dedicated support contracts and shared Slack channels for organizations requiring priority assistance. [Contact us](mailto:support@determinate.systems) to learn more.
+
+[cache]: https://flakehub.com/cache
+[flakehub]: https//flakehub.com
diff --git a/tools/README.template.md b/tools/README.template.md
index d46a51f..f5f6d8b 100644
--- a/tools/README.template.md
+++ b/tools/README.template.md
@@ -36,6 +36,8 @@ Based on the [Determinate Nix Installer](https://github.com/DeterminateSystems/n
 
 ## ️🔧 Usage
 
+Here's an example Actions workflow configuration that uses `determinate-nix-action`:
+
 ```yaml
 on:
   pull_request:
@@ -43,18 +45,21 @@ on:
     branches: [main]
 
 jobs:
-  lints:
-    name: Build
+  build-pkg:
+    name: Build Nix package
     runs-on: ubuntu-latest
     permissions:
-      id-token: "write"
-      contents: "read"
+      id-token: write
+      contents: read
     steps:
       - uses: actions/checkout@<!-- checkout_action_tag -->
       - uses: DeterminateSystems/determinate-nix-action@main # or <!-- version --> to pin to a release
       - run: nix build .
 ```
 
+> [!IMPORTANT]
+> If you use [FlakeHub], you need to add a `permissions` block like the one in the example above or else Determinate Nix can't authenticate with FlakeHub or [FlakeHub Cache][cache].
+
 ## 📌 Version Pinning: Lock It Down!
 
 ### Why Pin Your Action?
@@ -102,3 +107,6 @@ We're committed to making your experience with Determinate Nix as smooth as poss
 - 📧 **Need direct support?** Email us at [support@determinate.systems](mailto:support@determinate.systems)
 
 🤝 **Looking for enterprise support?** We offer dedicated support contracts and shared Slack channels for organizations requiring priority assistance. [Contact us](mailto:support@determinate.systems) to learn more.
+
+[cache]: https://flakehub.com/cache
+[flakehub]: https//flakehub.com