diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 28da777..f4e943b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,9 +25,11 @@ jobs:
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
           python-version: ${{ matrix.python-version }}
+          cache: "pip"
 
       - name: Install dependencies
         run: |
+          pip config set global.retries 5 || true
           pip install -e ".[dev]"
 
       - name: Lint with ruff
diff --git a/README.md b/README.md
index 55b4eb9..c075e6c 100644
--- a/README.md
+++ b/README.md
@@ -92,6 +92,22 @@ Use `--output silent` for CI gating:
 configdrift check dev.yaml prod.yaml --output silent || echo "Drift detected!"
 ```
 
+### GitHub Actions example
+
+```yaml
+- name: Detect config drift
+  run: |
+    pip install configdrift
+    configdrift check ./config/staging/app.yaml ./config/prod/app.yaml --output silent
+```
+
+## Troubleshooting
+
+- **Exit code 1 with no output**: use `--output table` to inspect drift details.
+- **TOML parsing errors on Python < 3.11**: install `tomli` and `tomli-w` or use Python 3.11+.
+- **Large config scans are slow**: narrow the scan to changed files or a single directory.
+- **Unexpected breaking drift**: review severity rules in the project settings; `database*` and `auth*` keys are flagged as breaking by default.
+
 ## Supported Formats
 
 | Format  | Extension      | Notes                         |