diff --git a/products/cli/extension-commands/configuration.md b/products/cli/extension-commands/configuration.md
index 886ec833bb..030e394823 100644
--- a/products/cli/extension-commands/configuration.md
+++ b/products/cli/extension-commands/configuration.md
@@ -12,6 +12,8 @@ Many configurations can be changed using a `.shopware-extension.yml` file in the
 Here is an example of a `.shopware-extension.yml` file:
 
 ```yaml
+compatibility_date: '2026-02-11'
+
 build:
   extraBundles:
     - path: src/Foo
@@ -42,6 +44,20 @@ validation:
 
 When you edit that file in an editor, you will get autocompletion and hints for the available options.
 
+## Compatibility date
+
+You can define a `compatibility_date` in `.shopware-extension.yml`:
+
+```yaml
+compatibility_date: '2026-02-11'
+```
+
+The `compatibility_date` lets Shopware CLI introduce behavior changes without breaking existing projects by default. New or potentially breaking changes are activated only for configurations that opt in with a date at or after the feature's rollout date.
+
+- Format: `YYYY-MM-DD`
+- If the field is missing, Shopware CLI uses `2026-02-11` as fallback
+- When missing, Shopware CLI logs a warning during config loading
+
 ## Environment variables
 
 Additionally, you can set environment variables to change the behavior of the CLI. The following environment variables are available:
diff --git a/products/cli/project-commands/build.md b/products/cli/project-commands/build.md
index e809478706..aba6f3fcb1 100644
--- a/products/cli/project-commands/build.md
+++ b/products/cli/project-commands/build.md
@@ -153,6 +153,8 @@ All existing environment variables from the parent process are also inherited, s
 You can configure the build process with a `.shopware-project.yml` file. The following options are available:
 
 ```yaml
+compatibility_date: '2026-02-11'
+
 build:
   # Browserlist configuration for Storefront
   browserslist: 'defaults'
@@ -190,6 +192,20 @@ build:
     post-assets: []
 ```
 
+## Compatibility date
+
+You can define a `compatibility_date` in `.shopware-project.yml`:
+
+```yaml
+compatibility_date: '2026-02-11'
+```
+
+The `compatibility_date` lets Shopware CLI introduce behavior changes without breaking existing projects by default. New or potentially breaking changes are activated only for configurations that opt in with a date at or after the feature's rollout date.
+
+- Format: `YYYY-MM-DD`
+- If the field is missing, Shopware CLI uses `2026-02-11` as fallback
+- When missing, Shopware CLI logs a warning during config loading
+
 ## Supporting bundles
 
 Shopware CLI automatically detects plugins and Apps. Custom bundles (classes that extend bundle class from Shopware) cannot be automatically detected as Shopware CLI does not execute any PHP code.