docs: document project upgrade wizard

.wordlist.txt

@@ -1826,6 +1826,7 @@ precompile
 preconfigured
 prefetch
 prefixer
+preflight
 preload
 preloaded
 preloading

guides/hosting/installation-updates/performing-updates.md

@@ -2,7 +2,6 @@
 nav:
   title: Performing Shopware Updates
   position: 20
-
 ---
 
 # Performing Shopware Updates
@@ -22,17 +21,28 @@ There are two Shopware update types:
 
 ## Preparations
 
-### Check extension compatibility
+### Check project and extension compatibility
+
+The recommended preflight is the Shopware CLI upgrade wizard in dry-run mode. It checks project readiness, Composer-managed extension compatibility, and whether Composer can resolve the selected target version without modifying project files:
+
+```bash
+shopware-cli project upgrade \
+  --no-interaction \
+  --target latest-patch \
+  --dry-run
+```
+
+If you're following older guides that mention `shopware-cli project upgrade-check`, use the dry-run command above instead.
 
-Before any update, check if the installed extensions are compatible with the new version. Run the upgrade check command to analyze your project for compatibility issues:
+For an interactive target picker and guided workflow, run:
 
 ```bash
-shopware-cli project upgrade-check
+shopware-cli project upgrade
 ```
 
-This command checks your installed extensions against the target Shopware version. If an extension is not compatible, check with the extension developer if an update is available. If you don't have the Shopware CLI installed, see the [installation guide](../../../products/tools/cli/index.md).
+See [Upgrade a Shopware Project](../../../products/tools/cli/project-commands/upgrade.md) for the full workflow. If you don't have Shopware CLI installed, see the [installation guide](../../../products/tools/cli/index.md).
 
-Managing all extensions through Composer is the best way to ensure compatibility. It simplifies the update process as Composer automatically resolves the correct versions of the extensions.
+Managing extensions through Composer is required by the upgrade wizard and gives Composer the information it needs to resolve extension versions together with Shopware. If the readiness check finds locally managed plugins, the CLI points you to `shopware-cli project autofix composer-plugins` where migration is possible.
 
 ### Create backups
 
@@ -44,29 +54,49 @@ If blue-green deployment is enabled, you can rollback to the previous version wi
 
 ### Enable maintenance mode
 
-Before you start the update process, set the Sales Channels into maintenance mode. This can be done using the Administration or with the terminal:
+Before you update a running production environment, set the Sales Channels into maintenance mode. This can be done using the Administration or with the terminal:
 
 ```bash
 bin/console sales-channel:maintenance:enable --all
 ```
 
+Do not enable maintenance mode merely to prepare and test the upgrade locally. Apply it according to your deployment procedure when the upgraded code is ready to move to the running environment.
+
 ### Additional steps for major updates
 
 For major updates, consider the following additional preparations:
 
 - **Update PHP version**: Update the PHP version to the minimum required version for the new Shopware version *before* updating Shopware. Shopware versions always support an overlapping PHP version, so this is safe to do beforehand. You can find the minimum required PHP version in the [System Requirements guide](../../installation/system-requirements.md).
 - **Check upgrade changes**: Review the [UPGRADE.md](https://github.com/search?q=repo%3Ashopware%2Fshopware+UPGRADE-6+language%3AMarkdown+NOT+path%3A%2F%5Eadr%5C%2F%2F+NOT+path%3A%2F%5Echangelog%5C%2F%2F&type=code&l=Markdown) for all breaking changes and migration instructions.
-- **Update extensions first**: Update all extensions to their latest versions before updating Shopware to ensure a smooth transition. After updating Shopware, update all extensions again to get versions compatible with the new Shopware version.
+- **Review extension updates**: Use the upgrade wizard's extension queue and report to identify compatible releases, updates, blockers, and items that still need manual or vendor review.
+
+## Prepare the update locally with Shopware CLI (recommended)
+
+The recommended workflow is to apply the upgrade to your local project first:
+
+```bash
+shopware-cli project upgrade
+```
+
+The wizard performs read-only readiness and compatibility checks first, lets you review the planned project changes, then runs the Composer update, refreshes Symfony Flex recipes, runs Shopware Deployment Helper, and writes `.shopware-cli/upgrade/report.md`.
+
+If an essential execution step fails or the run is canceled, Shopware CLI restores `composer.json` and `composer.lock` and writes a failure report. Always start from a clean Git state, so you can review or restore any other changed files as well.
+
+After a successful local run:
 
-## Performing the update via CLI (recommended)
+1. Review `.shopware-cli/upgrade/report.md` and the Git diff.
+2. Test the Administration, Storefront, integrations, and installed extensions.
+3. Run your automated test suite.
+4. Commit `composer.json`, `composer.lock`, and any reviewed configuration changes.
+5. Deploy through your normal process.
 
-The recommended way to update Shopware is via the command line. The update process consists of two phases: preparing the update locally and deploying it to the server.
+The upgrade wizard does not deploy the project to production.
 
-### Local development environment
+## Manual local preparation
 
-Perform the following steps in your local development environment:
+If you cannot use the Shopware CLI upgrade wizard, prepare the Composer changes manually.
 
-#### 1. Update the Shopware version constraint
+### 1. Update the Shopware version constraint
 
 Edit your `composer.json` and update the `shopware/core` version constraint to the target version:
 
@@ -78,25 +108,25 @@ Edit your `composer.json` and update the `shopware/core` version constraint to t
 }
 ```
 
-#### 2. Run Composer update
+### 2. Run Composer update
 
 Run the update command with `--no-scripts` to prevent the automatic execution of scripts during the update:
 
 ```bash
 composer update --no-scripts
 ```
 
-#### 3. Update Symfony Flex recipes
+### 3. Update Symfony Flex recipes
 
 Update the Symfony Flex recipes to apply any configuration changes:
 
 ```bash
 composer recipes:update
 ```
 
-This command shows available recipe updates and allows you to apply them interactively. Review the changes carefully before applying them.
+Review the changes carefully before applying them.
 
-#### 4. Commit and deploy
+### 4. Commit and deploy
 
 Commit the changes to your Git repository:
 
@@ -107,33 +137,33 @@ git commit -m "Update Shopware to 6.7.0"
 
 Review any other changed files (e.g., from recipe updates) and commit them as well. Then deploy the changes to your server using your deployment process.
 
-### Production server
+## Production server
 
-After deploying the updated code to your server, run the following commands:
+After deploying the updated code to your server, run the following commands according to your deployment process.
 
-#### 1. Enable maintenance mode
+### 1. Enable maintenance mode
 
 ```bash
 bin/console sales-channel:maintenance:enable --all
 ```
 
-#### 2. Prepare the update
+### 2. Prepare the update
 
 ```bash
 bin/console system:update:prepare
 ```
 
 This command triggers events that allow extensions to prepare for the update.
 
-#### 3. Finish the update
+### 3. Finish the update
 
 Run the Shopware update scripts to execute database migrations and other necessary update tasks:
 
 ```bash
 bin/console system:update:finish
 ```
 
-#### 4. Disable maintenance mode
+### 4. Disable maintenance mode
 
 ```bash
 bin/console sales-channel:maintenance:disable --all
@@ -148,31 +178,33 @@ Only run these commands on the production server after the updated code has been
 Shopware also provides a web-based updater in the Administration panel. This method handles the entire update process through the browser.
 
 :::warning
-The web updater is only recommended for small instances. Since the update runs in the browser, you may encounter timeout problems, memory limits, or other resource issues on larger shops. For production environments, use the CLI method described above.
+The web updater is only recommended for small instances. Since the update runs in the browser, you may encounter timeout problems, memory limits, or other resource issues on larger shops. For production environments, use the local preparation and deployment workflow described above.
 :::
 
 To use the web updater:
 
-1. Log in to the Administration
-2. Navigate to **Settings** > **System** > **Shopware Update**
-3. Follow the on-screen instructions to complete the update
+1. Log in to the Administration.
+2. Navigate to **Settings** > **System** > **Shopware Update**.
+3. Follow the on-screen instructions to complete the update.
 
 The web updater will automatically enable maintenance mode, download the update, run migrations, and disable maintenance mode when complete.
 
 ## Final steps
 
 Before you remove the maintenance mode, verify the update was successful:
 
-- **Check the Administration**: Make sure the administration is working correctly.
+- **Check the Administration**: Make sure the Administration is working correctly.
 - **Check the Storefront**: Make sure your main processes are working correctly (e.g., adding products to the cart, checkout, etc.).
 - **Check the Extensions**: Make sure that all extensions are working correctly.
-- **Check the Performance**: Make sure that there is no major performance degradation.
+- **Check the Performance**: Make sure there is no major performance degradation.
 - **Check the Logs**: Check your error logs for any issues.
+- **Review the upgrade report**: If you used Shopware CLI, keep the report with the upgrade context or attach a redacted copy when asking another developer, extension vendor, hosting provider, or Shopware support for help.
 
 ## Tools for extension developers
 
 If you maintain custom extensions, these tools can help with upgrades:
 
+- **[Shopware CLI upgrade wizard](../../../products/tools/cli/project-commands/upgrade.md)**: Check a Composer-managed extension set against a target Shopware version and produce a shareable compatibility/Composer report from a representative test project.
 - **[Rector for Shopware](https://github.com/FriendsOfShopware/shopware-rector)**: Automatically upgrades PHP code for Shopware compatibility.
 - **[Codemods](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/code-mods.js)**: Helps upgrade Administration JavaScript code.
 - **[Twig Block Versioning](https://www.shopware.com/en/news/twig-block-versioning-in-shopware-phpstorm-plugin/)**: A [PHPStorm Plugin](https://plugins.jetbrains.com/plugin/17632-shopware-6-toolbox) feature that tracks which Twig blocks you've overwritten and alerts you when they may need updates.

guides/upgrades-migrations/index.md

@@ -8,6 +8,10 @@ nav:
 
 This section covers version-based upgrades and the required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements.
 
+:::info
+For a guided local upgrade, use [`shopware-cli project upgrade`](../../products/tools/cli/project-commands/upgrade.md). It checks project readiness and Composer-managed extensions, verifies the selected target with Composer before modifying project files, runs the upgrade locally, and writes a shareable report.
+:::
+
 ## Scope of this section
 
 Upgrades typically fall into one of these categories:
@@ -27,13 +31,13 @@ Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce break
 
 When targeting a new Shopware version:
 
-1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files
-2. Check breaking changes per layer (Core / Admin / Storefront / API)
-3. Validate extension compatibility
-4. Apply required migrations
-5. Rebuild Admin/Storefront assets if needed
-6. Test critical flows
-7. Update extension versions if required
+1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files.
+2. Check breaking changes per layer (Core / Admin / Storefront / API).
+3. Run the [Shopware CLI upgrade preflight](../../products/tools/cli/project-commands/upgrade.md#run-a-non-interactive-preflight) or otherwise validate extension compatibility and Composer resolution.
+4. Apply required migrations and project changes.
+5. Rebuild Admin/Storefront assets if needed.
+6. Test critical flows and extension behavior.
+7. Commit the reviewed project changes and deploy through your normal process.
 
 :::info Upgrade impact in real projects
 Upgrade complexity depends on the installation:
@@ -47,19 +51,21 @@ A consistent architecture, centralized CI, and controlled extension strategy hel
 
 ### Custom projects
 
-* Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order.
+* Follow the [Performing updates guide](../hosting/installation-updates/performing-updates.md) to stage, test, and execute upgrades in order.
 * Review [RELEASE_INFO](https://github.com/shopware/shopware/blob/trunk/RELEASE_INFO-6.7.md) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release.
 * Use feature toggles to decouple risky changes from the deployment.
 
 ## Upgrade strategy for extension developers
 
 To reduce long-term upgrade cost:
 
-* Avoid internal APIs and undocumented features
-* Keep dependencies aligned with Shopware core
-* Maintain automated test coverage
-* Keep database migrations idempotent
-* Track deprecations continuously—do not batch them
+* Avoid internal APIs and undocumented features.
+* Keep dependencies aligned with the Shopware core.
+* Maintain automated test coverage.
+* Keep database migrations idempotent.
+* Track deprecations continuously—do not batch them.
+
+The Shopware CLI upgrade wizard can also be useful when you maintain extensions: assemble the extensions in a representative Composer-managed test project, select the target Shopware version, and use the extension queue and generated report to identify updates, blockers, and items that need manual review. This does not replace testing the extension itself against the target Shopware version.
 
 ### Custom plugins
 
@@ -81,6 +87,8 @@ To reduce long-term upgrade cost:
 
 ## Next steps
 
-For the operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware.md).
+For the guided local workflow, continue with [Upgrade a Shopware Project](../../products/tools/cli/project-commands/upgrade.md).
+
+For the wider operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware.md) and [Performing Shopware Updates](../hosting/installation-updates/performing-updates.md).
 
 For general development best practices that reduce upgrade friction, see the [Development guide](../development/index.md).

guides/upgrades-migrations/upgrade-shopware.md

@@ -6,20 +6,45 @@ nav:
 
 # Upgrade Shopware
 
-This guide explains how to update an existing Shopware installation using Composer.
+This guide explains how to update an existing Shopware installation. For local project preparation, the recommended workflow is the [Shopware CLI upgrade wizard](../../products/tools/cli/project-commands/upgrade.md), which combines readiness checks, extension compatibility analysis, Composer resolution, the local upgrade, and a shareable report.
 
 For maintaining custom plugins or apps, review the [Upgrades and Migrations](../upgrades-migrations/index.md) guide before performing updates.
 
-## Standard update process
+## Recommended: prepare the upgrade with Shopware CLI
 
-Shopware updates can be executed via Composer or with the web-based updater in the Administration panel.
+From a clean Git working tree in your local Shopware project, run:
 
-### 1. Enable maintenance mode
+```bash
+shopware-cli project upgrade
+```
+
+The wizard checks project readiness, lets you choose the target Shopware version, checks Composer-managed extensions, and verifies the target dependency set with Composer before changing project files. You review the plan before the CLI applies the upgrade locally.
+
+After the local upgrade succeeds, test the shop and extensions, review the generated report and changed files, commit the project changes, and deploy them through your normal process. The wizard does not deploy to production for you.
+
+For CI or a read-only preflight, use the non-interactive mode with `--dry-run`:
+
+```bash
+shopware-cli project upgrade \
+  --no-interaction \
+  --target latest-patch \
+  --dry-run
+```
+
+See [Upgrade a Shopware Project](../../products/tools/cli/project-commands/upgrade.md) for prerequisites, extension handling, rollback behavior, reports, and all command options.
+
+## Manual Composer update
+
+If you cannot use the Shopware CLI upgrade wizard, you can prepare the project manually with Composer.
+
+### 1. Enable maintenance mode when updating a running environment
 
 ```bash
 bin/console sales-channel:maintenance:enable --all
 ```
 
+For the recommended local-first workflow, enable maintenance mode as part of your normal deployment procedure rather than while preparing the project locally.
+
 ### 2. Update Composer dependencies
 
 Before running the update, adjust the required Shopware version in `composer.json` to the version to be installed. When using the Commercial plugin, update the `shopware/commercial` requirement to a compatible version as well.
@@ -52,7 +77,7 @@ Complete the update by running:
 bin/console system:update:finish
 ```
 
-This command applies all required update routines for the newly installed Shopware version, including running database migrations, and recompiling themes with the latest code.
+This command applies all required update routines for the newly installed Shopware version, including running database migrations and recompiling themes with the latest code.
 
 After the update process has finished successfully, disable maintenance mode separately:
 
@@ -62,17 +87,22 @@ bin/console sales-channel:maintenance:disable --all
 
 ## Operational best practices
 
-* Automate pre-upgrade checks (PHP/DB versions, extensions, disk space).
-* Always test upgrades on staging with production-like data.
-* Keep verified database backups and a recovery plan.
-* Review changelogs and UPGRADE files before applying changes.
-* Track deprecations early and use official tooling (Rector, Administration codemods referenced in [Performing updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work.
-* Avoid skipping major versions.
-* Commit the `composer.lock` file.
-* Run post-upgrade smoke tests.
+* Start from a clean Git working tree and a recoverable database backup.
+* Test upgrades locally or on staging with production-like data before production rollout.
+* Review release notes, changelogs, and UPGRADE files for the target version.
+* Check extension compatibility and investigate items that need vendor or manual review.
+* Track deprecations early and use official tooling (Rector, Administration codemods referenced in [Performing Shopware Updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work.
+* Avoid skipping major versions unless you have explicitly tested the full upgrade path.
+* Commit `composer.json`, `composer.lock`, and review recipe/configuration changes.
+* Run post-upgrade smoke tests and your automated test suite.
 
 ## After the update
 
-* Clear caches if necessary
-* Rebuild Administration and Storefront assets if required
-* Test critical business flows (checkout, login, API integrations)
+* Review the Shopware CLI upgrade report when you used the wizard.
+* Clear caches if necessary.
+* Rebuild Administration and Storefront assets if required.
+* Test critical business flows such as checkout, login, and API integrations.
+* Test installed extensions and custom project code.
+* Review logs for new errors or deprecations.
+
+For production-oriented preparation, maintenance mode, deployment, and verification guidance, see [Performing Shopware Updates](../hosting/installation-updates/performing-updates.md).