docs: document cache:clear:all confirmation and cache hash behavior

.wordlist.txt

@@ -129,6 +129,7 @@ CSP
 CSPs
 CSRF
 CSV
+CacheClearCommand
 CacheInvalidator
 CacheInvalidatorS
 CachedProductListingRouteTest
@@ -585,6 +586,7 @@ MyExtension
 MyPlugin
 MyTestClass
 MyTestInterface
+NFS
 NPM
 NUR
 NVDA

guides/hosting/infrastructure/reverse-http-cache.md

@@ -214,7 +214,7 @@ So, when a product is invalidated, the object cache and the HTTP cache will also
 There are a few different cache clearing commands:
 
 1. `bin/console cache:clear` - Clears and warms up the application cache (In versions before 6.7 this command also cleared the HTTP cache)
-2. `bin/console cache:clear:all` - Clears everything, including application cache, cache pools and the HTTP cache (Since version 6.6.8)
+2. `bin/console cache:clear:all` - Clears everything, including application cache, cache pools, HTTP cache, and other kernel cache directories. Prompts for confirmation in interactive mode; use `--force` to skip (Since version 6.6.8)
 3. `bin/console cache:clear:http` - Clears the reverse proxy cache if enabled, if not it clears the `http` cache pool (Since version 6.6.10)
 4. `bin/console cache:pool:clear --all` - Clears only the object cache (Useful for when you don't want to clear the http cache, pre version 6.6.10)
 

guides/hosting/installation-updates/deployments/build-w-o-db.md

@@ -1376,3 +1376,15 @@ index.json
 ### Partially compiling the Storefront
 
 You can also build just the Javascript bundle using `CI=1 SHOPWARE_SKIP_THEME_COMPILE=true PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true bin/build-storefront.sh` (without the need for the above loader) in your CI. After that, run `bin/console theme:dump` on your production system when the database is available. This will happen automatically if theme variables are changed via the admin panel.
+
+## Cache directory and hash implications
+
+When using `bin/ci` or `ComposerPluginLoader`, the cache directory name includes a hash computed from active plugins. Since `ComposerPluginLoader` marks all Composer-installed plugins as active, while `DbalKernelPluginLoader` (used by web requests) respects the database `active` column, the cache hashes can differ.
+
+This means:
+
+- Cache warmed with `bin/ci` uses a hash based on all Composer-installed plugins being active
+- Production web requests use a hash based on actual database plugin state
+- If any plugin is deactivated in the database, web requests create a new cache directory
+
+To ensure cache is properly cleared across all configurations, use `cache:clear:all` instead of `cache:clear` in deployment scripts. In interactive terminals, this command prompts for confirmation; use `--force` to skip the prompt in CI/CD pipelines.

guides/plugins/apps/app-base-guide.md

@@ -85,12 +85,14 @@ If the changes are still not visible, try:
 bin/console cache:clear:http
 ```
 
-or
+or for a complete cache reset:
 
 ```bash
-bin/console cache:clear:all
+bin/console cache:clear:all --force
 ```
 
+The `--force` flag skips the confirmation prompt that appears in interactive terminals.
+
 By default, your app files will be [validated](app-base-guide#validation) before installation.
 To skip the validation, you may use the `--no-validate` flag.
 

guides/plugins/plugins/framework/caching/index.md

@@ -409,6 +409,20 @@ sw-force-cache-invalidate: 1
 ## Manual cache clear
 
 You can also manually clear the caches when you performed some actions that made a cache invalidation necessary, but where it was not triggered automatically.
-To clear all caches, you can execute the `cache:clear:all` command, which clears the HTTP-Cache, the object caches as well as any other caches that are registered in the system.
+
+To clear all caches, you can execute the `cache:clear:all` command, which clears the HTTP-Cache, the object caches as well as removes other kernel cache directories. In interactive terminals, this command prompts for confirmation; use `--force` to skip the prompt.
+
 The `cache:clear` command on the other hand will only clear the object caches, but won't invalidate the HTTP-Cache.
 On the other hand, the `cache:clear:http` command will clear the complete HTTP-Cache, but won't invalidate the object caches.
+
+::: warning
+`cache:clear` only clears the cache directory matching the current kernel's configuration. If you run `bin/console cache:clear` but web requests still use stale cache, the CLI and web server may be using different cache directories. This can happen when plugins are in different states (e.g., installed via Composer but not yet activated in the database). Use `cache:clear:all` to clear all cache variants.
+:::
+
+::: details How cache:clear works internally
+The Symfony `cache:clear` command uses an atomic directory swap to ensure the application always has a valid cache. It first removes any leftover temporary directories, then creates and warms up the new cache in `var/cache/{env}_new/`. Once ready, it renames the current cache directory to a backup and moves the new one into place. Finally, it removes the backup.
+
+This approach ensures zero downtime because the application always has a working cache directory. The swap uses filesystem rename operations which are atomic on most systems. On NFS filesystems, directories are deleted instead of renamed due to limitations with atomic operations.
+
+For more details, see the [Symfony CacheClearCommand source](https://github.com/symfony/symfony/blob/7.4/src/Symfony/Bundle/FrameworkBundle/Command/CacheClearCommand.php).
+:::

resources/references/core-reference/commands-reference.md

@@ -59,19 +59,19 @@ $ bin/console [command] [parameters]
 
 ### Cache
 
-| Command                      | Description                                                                                     |
-|:-----------------------------|:------------------------------------------------------------------------------------------------|
-| `cache:clear`                | Clears the cache                                                                                |
-| `cache:clear:all`            | Clear all caches/pools, invalidates expired tags, removes old system and twig cache directories |
-| `cache:clear:delayed`        | Invalidates the delayed cache keys/tags                                                         |
-| `cache:clear:http`           | Clear only the HTTP cache                                                                       |
-| `cache:pool:clear`           | Clears cache pools                                                                              |
-| `cache:pool:delete`          | Deletes an item from a cache pool                                                               |
-| `cache:pool:invalidate-tags` | Invalidate cache tags for all or a specific pool                                                |
-| `cache:pool:list`            | Lists available cache pools                                                                     |
-| `cache:pool:prune`           | Prunes cache pools                                                                              |
-| `cache:warmup`               | Warms up an empty cache                                                                         |
-| `cache:watch:delayed`        | Watches the delayed cache keys/tags                                                             |
+| Command                      | Description                                                                                                                      |
+|:-----------------------------|:---------------------------------------------------------------------------------------------------------------------------------|
+| `cache:clear`                | Clears the cache                                                                                                                 |
+| `cache:clear:all`            | Clears all caches/pools, invalidates expired tags, removes old kernel cache directories. Requires confirmation or `--force` flag |
+| `cache:clear:delayed`        | Invalidates the delayed cache keys/tags                                                                                          |
+| `cache:clear:http`           | Clear only the HTTP cache                                                                                                        |
+| `cache:pool:clear`           | Clears cache pools                                                                                                               |
+| `cache:pool:delete`          | Deletes an item from a cache pool                                                                                                |
+| `cache:pool:invalidate-tags` | Invalidate cache tags for all or a specific pool                                                                                 |
+| `cache:pool:list`            | Lists available cache pools                                                                                                      |
+| `cache:pool:prune`           | Prunes cache pools                                                                                                               |
+| `cache:warmup`               | Warms up an empty cache                                                                                                          |
+| `cache:watch:delayed`        | Watches the delayed cache keys/tags                                                                                              |
 
 ### Cart