docs: explain the shop ID choice for staging copies

guides/hosting/installation-updates/creating-a-staging-instance.md

@@ -76,7 +76,7 @@ Do not share resources like MySQL, Redis, or ElasticSearch/OpenSearch between li
 After importing the database, modify the `.env` file to use the staging database. If you use ElasticSearch/OpenSearch, set a `SHOPWARE_ES_INDEX_PREFIX` to avoid conflicts with the live environment.
 
 ::: warning
-If you don't use the included Staging Mode, make sure to disable email sending in the staging environment to avoid sending test emails to real customers, and that you reset the app system by deleting "core.app.shopId" from the `system_config` table to avoid leaks of data between live and staging environments.
+If you don't use the included staging mode, disable email sending in the staging environment, so no test emails reach real customers. Also run `bin/console app:shop-id:change uninstall-apps`, which removes the apps from the copy and gives it its own shop ID, so apps don't mix up data between live and staging.
 :::
 
 ### 4. Activating staging mode
@@ -184,6 +184,20 @@ Uses regular expressions for advanced URL rewriting. In this example, `https://m
 
 The staging command deletes all apps with active external connections to prevent data corruption or leaks in the live environment. Since the staging instance is a copy of the live environment, apps would retain their original connections. After executing the command, reinstall apps to create new instance IDs, making the app installation completely isolated from the live environment.
 
+## If Shopware asks about the shop ID
+
+When Shopware detects that it runs in a new environment, for example because `APP_URL` changed, it stops talking to apps and asks how to continue: in a modal in the Administration, or with `bin/console app:shop-id:change`.
+
+| Option in the Administration   | Strategy for `app:shop-id:change` | Use it when                                               |
+| ------------------------------ | --------------------------------- | --------------------------------------------------------- |
+| Generate a new shop identifier | `reinstall-apps`                  | this is a copy, such as staging, and you want apps in it  |
+| Uninstall apps                 | `uninstall-apps`                  | this is a copy, and you don't need apps in it             |
+| Keep the shop identifier       | `move-shop-permanently`           | you permanently moved your live shop to this installation |
+
+::: warning
+Never choose **Keep the shop identifier** on a copy. The copy takes over the app registrations of the shop it was copied from, and the apps stop working there.
+:::
+
 ## Protecting the staging environment
 
 Protect your staging environment from unauthorized access using password protection, IP restriction, or OAuth authentication.

guides/plugins/apps/lifecycle/app-registration-setup.md

@@ -494,18 +494,29 @@ It is especially assumed that the environment variable will change when a shop i
 Remember that this is only relevant for apps that have their own backends and where communication between app backends and shopware is necessary.
 That is why simple themes are not affected by shop migrations, and they will continue to work.
 
-### Detecting APP_URL changes
+### Detecting a moved or copied shop
 
-Every time a request is made against an app backend, Shopware checks whether the current APP_URL differs from the one used when Shopware generated an ID for this shop.
-If the APP_URL differs, Shopware will stop sending requests to the installed apps to prevent data corruption on the apps' side.
-Now the user can resolve the issue using one of the following strategies.
-The user can either run a strategy with the `bin/console app:shop-id:change` command, or with a modal that pops up when the Administration is opened. The former command name `app:url-change:resolve` still works as an alias and is deprecated for removal in v6.8.0.
+Together with the shop ID, Shopware stores fingerprints of the environment it was generated in.
+Before each request to an app backend, Shopware compares them with the current environment, and each changed fingerprint adds to a score:
 
-### APP_URL change resolver
+| Fingerprint           | Score when it changes                                |
+| --------------------- | ---------------------------------------------------- |
+| `APP_URL`             | 100                                                  |
+| Installation path     | Up to 100, depending on how much of the path changed |
+| Sales channel domains | 25                                                   |
 
-* **MoveShopPermanently**: This strategy should be used if the live production shop is migrated from one URL to another.
+From a score of 75, Shopware stops sending requests to the installed apps to prevent data corruption on the apps' side.
+Changing `APP_URL` alone is enough to stop the requests. A new release directory from a deployment usually isn't.
+`bin/console app:shop-id:check` shows the stored and current fingerprints with their scores.
+
+The user resolves the situation with one of the following strategies, either with the `bin/console app:shop-id:change` command or in a modal that pops up when the Administration is opened.
+
+### Strategies
+
+* **Keep the shop identifier** (`move-shop-permanently`): This strategy should be used if the live production shop is migrated from one URL to another.
 This strategy notifies all apps about the APP_URL change, and the apps keep working as before, including any data already associated with that shop.
 It is important to note that in this case, apps in the old installation on the old URL (if it is still running) will stop working.
+Never use it for a copy: the copy takes over the app registrations of the shop it was copied from, and the apps stop working there.
 
 Technically, this is achieved by rerunning the registration process for all apps.
 During registration, the same shopId is used as before, but with a different shop-url and a different key pair for communicating with the Shopware API.
@@ -514,10 +525,10 @@ Also, you must generate a new communication secret during this registration proc
 This way, it is ensured that the apps are notified of the new URL and that the integration with the old installation stops working.
 because a new communication secret is associated with the given shopId that the old installation does not know.
 
-* **ReinstallApps**: This strategy makes sense to use in the case of the staging shop.
+* **Generate a new shop identifier** (`reinstall-apps`): Use this for a copy of a shop, such as staging, when you want to use the apps in the copy.
 By running this strategy, all installed apps will be reinstalled.
 This means that this installation will get a new shopId, which is used during registration.
 
 As the new installation will get a new shopId, the installed apps will continue working on the old installation as before, but, as a consequence, the data on the app's side associated with the old shopId cannot be accessed on the new installation.
 
-* **UninstallApps**: This strategy will simply uninstall all apps on the new installation, thus keeping the old installation working like before.
+* **Uninstall apps** (`uninstall-apps`): This strategy will simply uninstall all apps on the new installation, thus keeping the old installation working like before.

guides/plugins/apps/lifecycle/app-secret-recovery.md

@@ -121,7 +121,7 @@ A recovery that keeps reporting **no candidate was accepted** against a healthy
 This case is genuinely unrecoverable, not a defect: the app keys registration by **shop ID**, and the clone now legitimately owns that ID's secret. No secret Shop A holds can reclaim it — the only correct move is to give Shop A its own identity.
 
 ::: warning
-A cloned shop (for example, a staging instance restored from a production dump) shares the original's shop ID and app secrets. Run `bin/console app:shop-id:change` on the clone on first boot so it takes a distinct identity. See [Creating a staging instance](../../../hosting/installation-updates/creating-a-staging-instance.md).
+A cloned shop (for example, a staging instance restored from a production dump) shares the original's shop ID and app secrets. Activate staging mode on the clone before you use it, see [Creating a staging instance](../../../hosting/installation-updates/creating-a-staging-instance.md).
 :::
 
 ## Uninstall, reinstall, and the deleted-apps store