diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md
index 846c3f0ce..3f2f057f3 100644
--- a/guides/development/dev-environment.md
+++ b/guides/development/dev-environment.md
@@ -270,8 +270,6 @@ The web container exposes these ports by default:
 ```yaml
 compatibility_date: '2026-03-01'
 
-url: http://127.0.0.1:8000
-
 docker:
   php:
     version: "8.3"              # 8.2, 8.3, 8.4, 8.5
@@ -289,6 +287,8 @@ environments:
       password: shopware
 ```
 
+Shop URL and Admin API credentials belong under `environments` (an empty `-e`/`--env` defaults to `environments.local`). Top-level `url` and `admin_api` keys are deprecated: existing config files that still use them keep working and log a deprecation warning, but `project create` and `project config init` only write `environments.local`.
+
 ### `.shopware-project.local.yml`
 
 Sensitive credentials are stored in `.shopware-project.local.yml` (add to `.gitignore`):
diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md
index 8ab49fc3a..3cec55608 100644
--- a/products/tools/cli/project-commands/helper-commands.md
+++ b/products/tools/cli/project-commands/helper-commands.md
@@ -192,7 +192,9 @@ To create a new `.shopware-project.yml` configuration file interactively:
 shopware-cli project config init
 ```
 
-This generates a basic configuration file for your Shopware project. The file is also referenced in development environment setup and deployment configurations.
+This generates a basic configuration file for your Shopware project. Shop URL and Admin API credentials are written under `environments.local` (omit `-e`/`--env` on other project commands to target it). The file is also referenced in development environment setup and deployment configurations.
+
+Top-level `url` and `admin_api` keys are deprecated: config files that still use them keep working, but the CLI logs a deprecation warning telling you to move these values under `environments`.
 
 ## Generate JWT secret