From 312013c7b94f1bcd6c8a35f56c69ab2a2619b030 Mon Sep 17 00:00:00 2001
From: "shopware-docs-updater[bot]"
 <313750211+shopware-docs-updater[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 09:41:28 +0000
Subject: [PATCH] docs: document deprecation of top-level url/admin_api in
 favor of environments

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 guides/development/dev-environment.md                  | 4 ++--
 products/tools/cli/project-commands/helper-commands.md | 4 +++-
 2 files changed, 5 insertions(+), 3 deletions(-)

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