diff --git a/README.md b/README.md
index d2988b0..f2eba4b 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,25 @@ This compares your spec on the PR branch against the base branch and fails the w
 
 The following actions run the oasdiff CLI directly in your GitHub runner — no account or token required.
 
+### Configuring with `oasdiff.yaml`
+
+All free actions inherit the CLI's config-file support. Drop an `oasdiff.yaml` at your repo root and the actions pick it up automatically — no extra wiring needed:
+
+```yaml
+# oasdiff.yaml at your repo root
+exclude-elements:
+  - endpoints
+flatten-allof: true
+deprecation-days-stable: 180
+fail-on: ERR
+```
+
+Any flag the oasdiff CLI supports works in the config file — see [CONFIG-FILES.md](https://github.com/oasdiff/oasdiff/blob/main/docs/CONFIG-FILES.md) for the full reference and supported file formats (`oasdiff.{json,yaml,yml,toml,hcl}`).
+
+Action `inputs:` take precedence over config-file values, so you can use the file for shared defaults across workflows and override per-workflow via inputs.
+
+> **Limitation**: boolean flags can only be enabled through an action input. If your `oasdiff.yaml` sets `composed: true` and you want to disable it for a specific workflow run, edit the YAML — passing `composed: 'false'` in the action input has no effect.
+
 ### Check for breaking changes
 
 Detects breaking changes and writes inline GitHub annotations to the Actions summary. Fails the workflow when changes at or above the `fail-on` severity are found.