Apply suggestions from code review

shyim · lasomethingsomething · Copilot · web-flow · commit 76cde531ee1b · 2026-07-08T13:10:13.000+02:00
Co-authored-by: somethings &lt;l.apple@shopware.com&gt;
Co-authored-by: Copilot Autofix powered by AI &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md
@@ -13,15 +13,15 @@ Shopware CLI provides a fully integrated Docker-based development environment. A
 The development environment requires a compatibility date of `2026-03-01` or later in your `.shopware-project.yml`. Projects created with `shopware-cli project create` have this set automatically.
 :::
 
-## Starting the Environment
+## Starting the environment
 
 From your Shopware project root, run:
 
 ```bash
 shopware-cli project dev
 ```
 
-This launches the interactive **DevTUI** dashboard. If your containers aren't running yet, the dashboard starts them. If Shopware hasn't been installed, it guides you through the installation wizard.
+This launches the development terminal user interface (TUI). If your containers aren't running yet, the dashboard starts them. If Shopware hasn't been installed, it guides you through the installation wizard.
 
 To start without the interactive dashboard (for CI or scripting):
 
@@ -71,8 +71,7 @@ Use `↑`/`↓` to navigate sources and `enter` to select one. Scroll with `pgup
 
 ### Config tab (3)
 
-Adjust your Docker environment without touching YAML:
-
+The following table lists the settings you can change in the Config tab:
 | Setting | Options |
 |---------|---------|
 | **PHP Version** | `8.2`, `8.3`, `8.4`, `8.5` |
@@ -82,15 +81,15 @@ When selecting `blackfire` or `tideways`, additional credential fields appear. S
 
 After changing settings, select **Save & Regenerate** to update `compose.yaml`. Restart the environment for changes to take effect.
 
-## Migrating from Legacy Setups
+## Migrating from legacy setups
 
-If your project was created before March 2026 and uses the older `make up`/`make setup` workflow with a hand-written `compose.yaml`, running `shopware-cli project dev` automatically detects this and launches a **setup wizard** instead of the dashboard.
+If your project was created before March 2026 and uses the older `make up`/`make setup` workflow with a hand-written `compose.yaml`, running `shopware-cli project dev` automatically detects this and launches a setup wizard instead of the dashboard.
 
-### What Triggers the Wizard
+### What triggers the wizard
 
 The wizard appears when your project's `compatibility_date` in `.shopware-project.yml` is before `2026-03-01` (or missing entirely). This signals that the project hasn't been configured for the new development environment yet.
 
-### What the Wizard Does
+### What the wizard does
 
 Walking through the setup wizard takes about a minute. Here's what happens at each step:
 
@@ -108,17 +107,17 @@ After you confirm, the wizard:
 - Generates a new `compose.yaml` tailored to your project's dependencies
 - Starts the Docker containers and runs the Shopware installer
 
-### What Happens to Existing Files
+### What happens to existing files
 
 | File | What changes |
 |------|-------------|
 | `.shopware-project.yml` | Updated with `compatibility_date`, `environments`, and `docker` config |
 | `.shopware-project.local.yml` | Created if you chose a profiler with credentials (Blackfire, Tideways) |
-| `compose.yaml` | **Replaced** with the CLI-managed version. Your old file is overwritten — back it up first. Move any customizations to `compose.override.yaml`. |
-| `Makefile` | **Not touched**. You can delete it once you've migrated, or keep it around |
+| `compose.yaml` | **Replaced** with the CLI-managed version - your old file is overwritten, so back it up first and move any customizations to `compose.override.yaml` |
+| `Makefile` | **Not touched** - you can delete it once you've migrated, or keep it around |
 | `composer.json` | If `shopware/deployment-helper` isn't already present, it's added to `require` |
 
-### After the Wizard Completes
+### After the wizard completes
 
 If `shopware/deployment-helper` was added to `composer.json`, you'll be prompted to run:
 
@@ -128,9 +127,9 @@ composer install
 
 This pulls in the helper package, which the dashboard uses to run the Shopware installer. After that, the environment starts automatically.
 
-Once migrated, the legacy `make up`/`make down`/`make setup` workflow is no longer needed — use `shopware-cli project dev` to manage your environment instead. If you had customizations in your old `compose.yaml`, move them to `compose.override.yaml` before running the wizard (or recover them from git afterwards).
+Once migrated, the legacy `make up`/`make down`/`make setup` workflow is no longer needed; use `shopware-cli project dev` to manage your environment instead. If you had customizations in your old `compose.yaml`, move them to `compose.override.yaml` before running the wizard (or recover them from git afterwards).
 
-## Viewing Application Logs
+## Viewing application logs
 
 Inspect Shopware logs without opening the dashboard:
 
@@ -151,7 +150,7 @@ shopware-cli project logs -l
 shopware-cli project logs --lines 50
 ```
 
-## Running Shopware Commands
+## Running Shopware commands
 
 Use `shopware-cli project console` to run `bin/console` commands from your host — no need to shell into the container:
 
@@ -163,7 +162,7 @@ shopware-cli project console dal:refresh:index
 
 When using the Docker executor, commands automatically run inside the web container via `docker compose exec`.
 
-## Docker Services
+## Docker services
 
 The CLI generates a `compose.yaml` tailored to your project:
 
@@ -220,7 +219,7 @@ The compose file inspects your `composer.lock` at generation time:
 - `shopware/elasticsearch` → adds **OpenSearch** with environment variables
 - PHP version defaults to `8.3`, overridable in the Config tab
 
-## Environment Executors
+## Environment executors
 
 The CLI abstracts command execution across environment types, configured per environment in `.shopware-project.yml`:
 
@@ -253,7 +252,7 @@ The web container exposes these ports by default:
 | `9999` | Storefront Proxy |
 | `5773` | IDE debugging |
 
-## Configuration Reference
+## Configuration reference
 
 ### .shopware-project.yml
 
@@ -279,7 +278,7 @@ environments:
       password: shopware
 ```
 
-### .shopware-project.local.yml
+### `.shopware-project.local.yml`
 
 Sensitive credentials are stored in `.shopware-project.local.yml` (add to `.gitignore`):
 
@@ -292,7 +291,7 @@ docker:
 
 ## Troubleshooting
 
-### compose.yaml keeps getting reset
+### `compose.yaml` keeps getting reset
 
 This is by design. `compose.yaml` is fully managed and regenerated on config changes. Use `compose.override.yaml` for all customizations. See [Customizing with compose.override.yaml](#customizing-with-composeoverrideyaml).
 
@@ -308,7 +307,7 @@ The development TUI's initialization wizard, which mirrors steps in Shopware's i
 
 Set `compatibility_date: '2026-03-01'` in `.shopware-project.yml`. For more context, see the [build command docs](../../products/tools/cli/project-commands/build.md#compatibility-date).
 
-## Next Steps
+## Next steps
 
 - [Start Developing](./start-developing.md) — What to do once your environment is running
 - [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes
diff --git a/guides/development/index.md b/guides/development/index.md
@@ -78,7 +78,7 @@ The Administration is part of the runtime environment and will be used throughou
 
 ## Development tooling
 
-* [Development Environment](./dev-environment.md) — Docker-based environment with an interactive terminal dashboard, log streaming, and runtime configuration
+* [Development Environment](./dev-environment.md) — Docker-based environment with an interactive terminal user interface (TUI), log streaming, and runtime configuration
 * `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../resources/references/core-reference/commands-reference.md). You can run these from your host with `shopware-cli project console`.
 * The standalone [Shopware CLI](../../products/tools/cli/installation.md) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](../../products/tools/cli/project-commands/helper-commands.md).
 * IDE support: Shopware provides a [PHPStorm plugin](tooling/shopware-toolbox.md) and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=shopware.shopware-lsp).
diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md
@@ -9,14 +9,14 @@ nav:
 
 This guide covers what to do once your [development environment](./dev-environment.md) is running.
 
-## Your Environment
+## Your environment
 
 Once the containers are up, you have:
 
 - **Storefront**: `http://127.0.0.1:8000`
 - **Administration**: `http://127.0.0.1:8000/admin` *(default credentials: `admin` / `shopware`)*
 
-The DevTUI dashboard (`shopware-cli project dev`) shows these URLs and your credentials at a glance.
+The development terminal user interface (TUI) (`shopware-cli project dev`) shows these URLs and your credentials at a glance.
 
 Common development areas:
 
@@ -47,7 +47,7 @@ make shell
 docker compose exec web bash
 ```
 
-Most tasks are now easier with `shopware-cli project console` and the DevTUI dashboard.
+Most tasks are now easier with `shopware-cli project console` and the development TUI.
 :::
 
 ## Frontend development
@@ -86,18 +86,18 @@ shopware-cli project admin-build --only-custom-static-extensions
 
 For more details, see [Using Watchers](./tooling/using-watchers.md).
 
-## Administration Setup
+## Administration setup
 
 When accessing the Administration for the first time:
 
 - Sign in or create a Shopware account (required to install Store extensions)
-- Connect to the **Shopware Store**
+- Connect to the Shopware Store
 - Install plugins or themes from the Store
 - Configure payment methods if needed
 
 Basic shop settings (name, language, currency) can be changed later under **Settings > Shop > Basic information**.
 
-## Environment Customization
+## Environment customization
 
 ### compose.override.yaml
 
@@ -117,7 +117,7 @@ services:
       - "3306:3306"   # Expose MySQL to host
 ```
 
-### Connecting to a Remote Database
+### Connecting to a remote database
 
 To use an external database, set `DATABASE_URL` in `.env.local`:
 
@@ -127,11 +127,11 @@ DATABASE_URL="mysql://user:password@<host>:3306/<database>"
 
 If the container can't reach `localhost`, try `host.docker.internal` or your host's LAN IP.
 
-### Environment Variables
+### Environment variables
 
 Create a `.env` file in the project root to override defaults. Most changes apply immediately. Changes to `APP_ENV` require a restart (`shopware-cli project dev stop && shopware-cli project dev start`).
 
-## Shopware Account and Private Composer Packages
+## Shopware account and private Composer packages
 
 To install licensed extensions from Shopware's private Composer registry:
 
@@ -141,7 +141,7 @@ composer config --global http-basic.packages.shopware.com <username> <token>
 
 Create an access token in your Shopware account under **Shops > Licenses**.
 
-## Next Steps
+## Next steps
 
 - [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes
 - [Work with APIs](./integrations-api/index.md) — Integrate external systems
diff --git a/guides/installation/index.md b/guides/installation/index.md
@@ -85,7 +85,7 @@ cd my-shop
 shopware-cli project dev
 ```
 
-This launches the interactive **DevTUI** dashboard. The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment — Shop URLs, credentials, watchers, logs, and service configuration — all in one place.
+This launches the development terminal user interface (TUI). The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment — Shop URLs, credentials, watchers, logs, and service configuration — all in one place.
 
 For details, see the [Development Environment guide](../development/dev-environment.md).
 
diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md
@@ -11,7 +11,7 @@ You have just installed Shopware, and this section guides you through the fundam
 
 ## Development tooling
 
-The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) dashboard (`shopware-cli project dev`), which provides:
+The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) terminal user interface (TUI), available via `shopware-cli project dev`. It provides:
 
 - One-command start/stop of the entire stack
 - Real-time log streaming from `var/log/` and Docker containers
@@ -22,7 +22,7 @@ The Docker setup provisions Shopware for development. The recommended way to man
 Development tools such as:
 
 - [`shopware/dev-tools`](https://github.com/shopware/dev-tools)
-- [Symfony profiler]( https://symfony.com/doc/current/profiler.html) (**only in development mode**)
+- [Symfony profiler](https://symfony.com/doc/current/profiler.html) (**only in development mode**)
 - linting and testing tools
 
 are managed via the Shopware CLI. These are installed into the user's environment and shared across projects and extensions, rather than being added as project-level `require-dev` dependencies.
diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md
@@ -11,7 +11,7 @@ This page is a quick reference for the `shopware-cli project dev` and `shopware-
 
 ## Commands
 
-### Start the Environment
+### Start the environment
 
 ```bash
 # Interactive dashboard (default when run in a terminal)
@@ -33,7 +33,7 @@ The interactive dashboard has three tabs:
 - **Instance** — containers, watcher processes, and log files with live-streaming
 - **Config** — PHP version, profiler
 
-### View Application Logs
+### View application logs
 
 ```bash
 # Last 100 lines of the most recently modified log file
@@ -74,7 +74,7 @@ environments:
       password: shopware
 ```
 
-## Further Reading
+## Further reading
 
 - [Development Environment guide](../../../../guides/development/dev-environment.md) — full workflow, setup wizard, service overview, troubleshooting
 - [Start Developing](../../../../guides/development/start-developing.md) — next steps after your environment is running
diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md
@@ -25,12 +25,12 @@ shopware-cli project create <folder-name> <version>
 
 The version parameter can be also `latest` for the latest stable version or `dev-trunk` for the latest development version.
 
-## Development Environment
+## Development environment
 
 Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](../../../../guides/development/dev-environment.md) guide for the full workflow, or the [CLI command reference](./dev-environment.md) for a quick overview.
 
 ```bash
-# Launch the interactive dashboard
+# Launch the interactive development terminal user interface (TUI)
 shopware-cli project dev
 
 # Start/stop in the background
