diff --git a/.wordlist.txt b/.wordlist.txt
index 6a62453a2c..bce4dfa739 100644
--- a/.wordlist.txt
+++ b/.wordlist.txt
@@ -333,6 +333,7 @@ Deployer
 Deprecations
 Deutsch
 DevOps
+DevTUI
 DevTools
 Devenv
 DeviceHelper
@@ -540,6 +541,7 @@ LONGTEXT
 LUA
 LandingPage
 LastNameRule
+LavinMQ
 Lerna
 Lifecycle
 LineItemClearanceSaleRule
@@ -1023,6 +1025,8 @@ TCP
 TLS
 TTL
 TTLs
+TUI
+TUI's
 TaxFreeConfigField
 TaxProvider
 TaxProviderStruct
@@ -1180,6 +1184,7 @@ actionAmount
 actionType
 actionability
 activateShopwareTheme
+adminer
 adr
 afterSort
 ag
@@ -1636,8 +1641,10 @@ jwks
 jwt
 kebabCase
 keyframes
+keypress
 landingpage
 lang
+lavinmq
 lazysizes
 libxml
 lifecycle
@@ -1762,6 +1769,7 @@ org's
 organizationUnitIds
 otel
 otlp
+overridable
 overrideComponentSetup
 oversales
 paas
@@ -1903,6 +1911,7 @@ rollout
 routeName
 routeScope
 routeScopes
+runnable
 runtime
 runtimes
 salesChannel
@@ -2140,6 +2149,7 @@ wishlist
 wordlist
 www
 xasjkyld
+xdebug
 xhost's
 xkeys
 xl
diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md
new file mode 100644
index 0000000000..846c3f0ce0
--- /dev/null
+++ b/guides/development/dev-environment.md
@@ -0,0 +1,325 @@
+---
+nav:
+  title: Development Environment
+  position: 3
+
+---
+
+# Development Environment
+
+Shopware CLI provides a fully integrated Docker-based development environment. A single command launches your entire stack, streams logs, manages watchers, and lets you configure PHP and profiling - all without manually editing Docker files.
+
+:::info
+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
+
+From your Shopware project root, run:
+
+```bash
+shopware-cli project dev
+```
+
+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):
+
+```bash
+shopware-cli project dev start
+```
+
+To check whether the environment is running:
+
+```bash
+shopware-cli project dev status
+```
+
+To stop everything:
+
+```bash
+shopware-cli project dev stop
+```
+
+## Development terminal user interface (TUI)
+
+The dashboard has three tabs, which can be switched to with the corresponding number key or by using the Tab button.
+
+### 1. Overview Tab
+
+Your environment at a glance:
+
+**Left panel:**
+
+- **Shop** - Shopware version, environment type (`docker`, `local`, or `symfony-cli`), shop and admin URLs, and security update expiry date
+- **Access** - URLs, usernames, and passwords for Shop Admin, Adminer, and Mailpit
+- **Setup health** - runtime checks (PHP version, memory limit), local behavior warnings, and debug settings, each showing the current value against the recommended one
+
+**Right panel:**
+
+- **Watchers** - toggle Admin and Storefront watchers on or off
+
+### 2. Instance Tab
+
+Browse and stream logs from your running environment:
+
+- **Containers** - all Docker containers with a live status indicator for the active one
+- **Processes** - watcher processes (Admin Watcher, Storefront Watcher) when running
+- **Log files** - application log files (e.g., `dev.log`)
+
+Use the sidebar to switch sources. Toggle follow mode with `Enter`.
+
+### 3. Config Tab
+
+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` |
+| **Profiler** | `none`, `xdebug`, `blackfire`, `tideways`, `pcov`, `spx` |
+
+When selecting `blackfire` or `tideways`, additional credential fields appear. Sensitive credentials are stored in `.shopware-project.local.yml` (excluded from version control).
+
+:::info
+The profiler is now configured via the Config tab.
+:::
+
+After changing settings, select **Save & Regenerate** to update `compose.yaml`. Restart the environment for changes to take effect.
+
+## 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.
+
+### 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
+
+Walking through the setup wizard takes about a minute. Here's what happens at each step:
+
+1. **Welcome** - explains what the wizard will do and asks you to proceed
+2. **Admin user** - pre-fills `admin` (you can change it) for the Shopware admin account
+3. **Admin password** - pre-fills `shopware` (you can change it); stored as credentials in `.shopware-project.yml`
+4. **PHP version** - reads your `composer.lock` to determine compatible PHP versions and offers the highest supported one as the default (e.g., `8.5`)
+
+After you confirm, the wizard:
+
+- Sets `compatibility_date` to `2026-03-01` in `.shopware-project.yml`
+- Adds a `local` environment with type `docker` and your chosen URL/credentials
+- Configures the Docker PHP version
+- 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
+
+| 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, 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
+
+If `shopware/deployment-helper` was added to `composer.json`, you'll be prompted to run:
+
+```bash
+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).
+
+## Viewing application logs
+
+Inspect Shopware logs without opening the dashboard:
+
+```bash
+# Last 100 lines of the most recently modified log
+shopware-cli project logs
+
+# A specific log file
+shopware-cli project logs dev-2026-05-18.log
+
+# Follow the log (like tail -f)
+shopware-cli project logs -f
+
+# List available log files
+shopware-cli project logs -l
+
+# Set number of lines
+shopware-cli project logs --lines 50
+```
+
+## Running Shopware commands
+
+Use `shopware-cli project console` to run `bin/console` commands from your host - no need to shell into the container:
+
+```bash
+shopware-cli project console cache:clear
+shopware-cli project console plugin:refresh
+shopware-cli project console dal:refresh:index
+```
+
+When using the Docker executor, commands automatically run inside the web container via `docker compose exec`.
+
+To type a little less, you can also use the `swx` alias as a shortcut for `shopware-cli project console`:
+
+```bash
+swx cache:clear
+swx plugin:refresh
+swx dal:refresh:index
+```
+
+## Docker services
+
+The CLI generates a `compose.yaml` tailored to your project:
+
+| Service | Description | URL |
+|---------|-------------|-----|
+| **web** | PHP + Node.js with Caddy | `http://127.0.0.1:8000` |
+| **database** | MariaDB 11.8 | internal |
+| **adminer** | Database management UI | `http://127.0.0.1:9080` |
+| **mailer** | Mailpit (email testing) | `http://127.0.0.1:8025` |
+| **lavinmq** | Message queue * | `http://127.0.0.1:15672` |
+| **opensearch** | Search engine * | `http://127.0.0.1:9200` |
+| **blackfire** | Blackfire agent * | internal |
+| **tideways-daemon** | Tideways agent * | internal |
+
+\* *Auto-detected from `composer.lock` or enabled via configuration.*
+
+::: warning
+The `compose.yaml` file is fully managed by the Shopware CLI and regenerated whenever you change configuration. **Never edit it directly.**
+:::
+
+### Customizing with `compose.override.yaml`
+
+Place all customizations in `compose.override.yaml`. Docker Compose [merges multiple files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/), so your overrides are applied on top of the managed file:
+
+```yaml
+# compose.override.yaml
+services:
+  web:
+    environment:
+      APP_ENV: dev
+      COMPOSER_HOME: /tmp/composer
+    ports:
+      - "9003:9003"   # Xdebug
+
+  # Add your own services
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+```
+
+The CLI-generated `compose.yaml` includes this header for clarity:
+
+```yaml
+# This file is managed by shopware-cli. Do not edit manually.
+# Create a compose.override.yaml to customize services.
+```
+
+### Auto-Detection
+
+The compose file inspects your `composer.lock` at generation time:
+
+- `symfony/amqp-messenger` - adds **LavinMQ** and sets `MESSENGER_TRANSPORT_DSN`
+- `shopware/elasticsearch` - adds **OpenSearch** with environment variables
+- PHP version defaults to `8.3`, overridable in the Config tab
+
+## Environment executors
+
+The CLI abstracts command execution across environment types, configured per environment in `.shopware-project.yml`:
+
+| Type | Behavior |
+|------|----------|
+| `docker` | Executes commands inside the web container via `docker compose exec` |
+| `local` | Executes commands directly on the host |
+| `symfony-cli` | Uses the Symfony CLI binary (auto-detected) |
+
+```yaml
+environments:
+  local:
+    type: docker
+    url: http://127.0.0.1:8000
+    admin_api:
+      username: admin
+      password: shopware
+```
+
+## Ports
+
+The web container exposes these ports by default:
+
+| Port | Purpose |
+|------|---------|
+| `8000` | Storefront |
+| `8080` | HTTP (alternative) |
+| `5173` | Admin Watcher (Vite) |
+| `9998` | Storefront Watcher |
+| `9999` | Storefront Proxy |
+| `5773` | IDE debugging |
+
+## Configuration reference
+
+### `.shopware-project.yml`
+
+```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
+    profiler: xdebug             # none (empty), xdebug, blackfire, tideways, pcov, spx
+    blackfire_server_id: ""     # required when profiler is blackfire
+    blackfire_server_token: ""  # required when profiler is blackfire
+    tideways_api_key: ""        # required when profiler is tideways
+
+environments:
+  local:
+    type: docker
+    url: http://127.0.0.1:8000
+    admin_api:
+      username: admin
+      password: shopware
+```
+
+### `.shopware-project.local.yml`
+
+Sensitive credentials are stored in `.shopware-project.local.yml` (add to `.gitignore`):
+
+```yaml
+docker:
+  php:
+    blackfire_server_id: "your-server-id"
+    blackfire_server_token: "your-server-token"
+```
+
+## Troubleshooting
+
+### `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).
+
+### Containers won't start
+
+Check logs with `shopware-cli project logs -f` or from the Instance tab in the TUI.
+
+### Shopware isn't installed
+
+The development TUI's initialization wizard, which mirrors steps in Shopware's in-browser First Run Wizard, prompts you to run the installer. It uses `shopware/deployment-helper` to install Shopware with your chosen locale, currency, and Admin credentials.
+
+### Compatibility date error
+
+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
+
+- [Start Developing](./start-developing.md) - What to do once your environment is running
+- [Build Extensions](./extensions/index.md) - Create plugins, apps, and themes
+- [Using Watchers](./tooling/using-watchers.md) - Hot Module Replacement for Admin and Storefront
diff --git a/guides/development/index.md b/guides/development/index.md
index b45418226c..da2902a9ac 100644
--- a/guides/development/index.md
+++ b/guides/development/index.md
@@ -40,7 +40,8 @@ To sell an extension or offer paid features, see the [Monetization guide](moneti
 
 Most development follows this sequence:
 
-* Set up the environment
+* [Set up the environment](./dev-environment.md) — Start your Docker-based development environment with `shopware-cli project dev`
+* [Start developing](./start-developing.md) — Run commands, use watchers, and customize your environment
 * Create the project or extension
 * Install and activate it
 * Implement business logic
@@ -77,7 +78,8 @@ The Administration is part of the runtime environment and will be used throughou
 
 ## Development tooling
 
-* `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).
+* [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).
 * [Deployment Helper](../hosting/installation-updates/deployments/deployment-helper.md): Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
@@ -88,4 +90,4 @@ The [troubleshooting](troubleshooting/index.md) guides provide reference informa
 
 ## Next steps
 
-Move on to the [Start Developing guide](start-developing.md).
+Set up your [Development Environment](./dev-environment.md), then move on to [Start Developing](./start-developing.md).
diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md
index 793936fbbb..f2f59fa43c 100644
--- a/guides/development/start-developing.md
+++ b/guides/development/start-developing.md
@@ -7,149 +7,144 @@ nav:
 
 # Start Developing
 
-This section outlines the typical next steps for development in your running Shopware instance.
+This guide covers what to do once your [development environment](./dev-environment.md) is running.
 
-## Access Administration and Storefront
+## Your environment
 
-- Storefront: `http://127.0.0.1:8000`
-- Administration: `http://127.0.0.1:8000/admin` *(default credentials: `admin` / `shopware`)*
+Once the containers are up, you have:
 
-Common development areas:
+- **Storefront**: `http://127.0.0.1:8000`
+- **Administration**: `http://127.0.0.1:8000/admin` *(default credentials: `admin` / `shopware`)*
+
+The development terminal user interface (TUI) (`shopware-cli project dev`) shows these URLs and your credentials at a glance.
 
-- `custom/`: your plugins and themes
-- `bin/console`: application CLI (Symfony console)
-- the Administration UI
+Common development areas:
 
-Projects follow the [project template layout](../installation/project-overview.md).
+- `custom/` - your plugins and themes
+- `bin/console` - application CLI (Symfony console), runnable from your host via `shopware-cli project console`
+- The Administration UI
 
-## Using `bin/console` for development
+## Running commands
 
-To run commands, open a shell inside the web container:
+Use `shopware-cli project console` to run `bin/console` commands from your host - no need to enter the container:
 
 ```bash
-make shell
+# Clear caches
+shopware-cli project console cache:clear
+
+# Install and activate a plugin
+shopware-cli project console plugin:install --activate MyPlugin
+
+# Run database migrations
+shopware-cli project console database:migrate --all
 ```
 
-This command drops you into the container’s terminal; you will see the prompt change.
+For the shorter `swx` alias, see [Running Shopware commands](./dev-environment.md#running-shopware-commands).
 
-From inside the container, retrieve a list of commands with:
+:::info Legacy workflow
+If your project uses the older `make`-based setup and you need to shell into the container manually:
 
 ```bash
-bin/console
+make shell
+docker compose exec web bash
 ```
 
-Tasks handled in `bin/console` include:
-
-- Installing and activating plugins
-- Clearing caches
-- Running migrations
-- Adjusting system configuration
-- Running plugin-related development tasks
-
-:::info
-Inside the container, you only need `bin/console …`. But if you prefer to run commands from your host machine instead, you can use the full Docker prefix: `docker compose exec web bin/console cache:clear`.
+Most tasks are now easier with `shopware-cli project console` and the development TUI.
 :::
 
-## Administration setup tasks
+## Frontend development
 
-- Open the **Admin** at `http://localhost:8000/admin`
-- Sign in or create a Shopware account; this is necessary when you want to install Store extensions.
-- Connect to the **Shopware Store**
-- Install plugins or themes from the Store
-- Configure payment methods if you need them (not required for local development)
+When developing the Administration or Storefront, use watchers for Hot Module Replacement. Start them directly from the DevTUI Overview tab (key `1`), or from the command line:
 
-Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **`Settings > Shop > Basic information`**.
+```bash
+# Administration (Vite HMR on port 5173)
+shopware-cli project admin-watch
 
-## Frontend development
+# Storefront (webpack HMR on port 9998)
+shopware-cli project storefront-watch
+```
 
-Use these commands when developing or customizing the UI, including Storefront, Administration, or extensions that affect either one:
+To only watch specific extensions:
 
 ```bash
-# Build the administration (admin panel)
-make build-administration
-
-# Build the storefront (shop frontend)
-make build-storefront
+shopware-cli project admin-watch --only-extensions MyPlugin,OtherPlugin
+shopware-cli project storefront-watch --only-extensions MyPlugin,OtherPlugin
+```
 
-# Start a watcher to rebuild the Administration automatically when files change
-make watch-admin
+To exclude specific extensions:
 
-# Start a watcher for Storefront
-make watch-storefront
+```bash
+shopware-cli project admin-watch --skip-extensions SomePlugin
 ```
 
-### Alternative: use Shopware CLI
+For the Storefront Watcher, the CLI prompts you to select a sales channel if one isn't configured.
 
-If you prefer not to use `make`, you can use the [Shopware CLI](https://developer.shopware.com/docs/products/cli/) to build and watch the Administration and Storefront. Run the following commands:
+When working with many third-party extensions, building only custom extensions speeds things up:
 
 ```bash
-shopware-cli project admin-build
-shopware-cli project storefront-build
-shopware-cli project admin-watch
-shopware-cli project storefront-watch
+shopware-cli project storefront-build --only-custom-static-extensions
+shopware-cli project admin-build --only-custom-static-extensions
 ```
 
-The `watch` commands monitor changes to the Administration and Storefront and automatically rebuild them.
+For more details, see [Using Watchers](./tooling/using-watchers.md).
 
-## Local environment overview
+## Administration setup
 
-With Shopware running, your local setup includes:
+When accessing the Administration for the first time:
 
-- **Web service:** Serves the Storefront and the Administration.
-- **Database (MariaDB):** Runs on port 3306 inside Docker.
-  - Internal hostname: `database`.
-  - Host access: `localhost:3306`, if you want to inspect the database directly.
-- **Mailpit:** A local mail-testing tool available at `http://localhost:8025`. Use it to view emails sent by Shopware (e.g., registration or order confirmations) without an external mail server.
-- **Adminer (database UI):** A lightweight web interface for viewing and editing your database, available at `http://localhost:8080`.
+- Sign in or create a Shopware account (required to install Store extensions)
+- Connect to the Shopware Store
+- Install plugins or themes from the Store
+- Configure payment methods if needed
 
-For Docker setups, inspect ports and services with:
+Basic shop settings (name, language, currency) can be changed later under **Settings > Shop > Basic information**.
 
-```bash
-docker compose ps
-```
+## Environment customization
 
-## Environment setup
+### compose.override.yaml
 
-### Connecting to a remote database
+The `compose.yaml` file is managed by shopware-cli and regenerated automatically. Place all customizations in `compose.override.yaml`:
 
-To use a database outside the Docker stack, set `DATABASE_URL` in `.env.local` in the standard form:
+```yaml
+# compose.override.yaml
+services:
+  web:
+    environment:
+      APP_ENV: dev
+    ports:
+      - "9003:9003"   # Xdebug
 
-```bash
-DATABASE_URL="mysql://user:password@<host>:3306/<database>"
+  database:
+    ports:
+      - "3306:3306"   # Expose MySQL to host
 ```
 
-Containers cannot always reach services bound only to the host's `localhost`. If `localhost` does not work, try `host.docker.internal` or your host machine’s LAN IP, or add an `extra_hosts` entry in `compose.yaml`.
-
-### Environment variables
+### Connecting to a remote database
 
-You can create a `.env` file in the project root to override default environment variables. Most changes take effect automatically without requiring container restarts. Changes to `APP_ENV` require a restart:
+To use an external database, set `DATABASE_URL` in `.env.local`:
 
 ```bash
-make up
+DATABASE_URL="mysql://user:password@<host>:3306/<database>"
 ```
 
-### Docker overrides
+If the container can't reach `localhost`, try `host.docker.internal` or your host's LAN IP.
 
-Use `compose.override.yaml` to:
-
-- Change ports
-- Add services
-- Enable debugging
-- Adjust networking
+### Environment variables
 
-This keeps your changes local and out of version control.
+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 Composer (private packages)
+## Shopware account and private Composer packages
 
-Shopware operates a private Composer registry for licensed and commercial extensions. To install packages that require Shopware account authentication, configure Composer with your Shopware account credentials (create an access token in your Shopware account when prompted):
+To install licensed extensions from Shopware's private Composer registry:
 
 ```bash
 composer config --global http-basic.packages.shopware.com <username> <token>
 ```
 
-Use the hostname and steps described in your Shopware account or in the extension download instructions, if they differ.
+Create an access token in your Shopware account under **Shops > Licenses**.
 
 ## Next steps
 
-- Build extensions: [Extensions](extensions/index.md).
-- Integrate via HTTP: [APIs](integrations-api/index.md).
+- [Build Extensions](./extensions/index.md) - Create plugins, apps, and themes
+- [Work with APIs](./integrations-api/index.md) - Integrate external systems
+- [Set up CI/CD](../../products/tools/cli/project-commands/build.md) - Automate builds and deployments
diff --git a/guides/development/tooling/index.md b/guides/development/tooling/index.md
index 85f9ed9ef1..594b7373a2 100644
--- a/guides/development/tooling/index.md
+++ b/guides/development/tooling/index.md
@@ -9,11 +9,13 @@ nav:
 
 Shopware provides official tools that support the full lifecycle of a Shopware project, from development to deployment and long-term maintenance:
 
+- [Development Environment](../dev-environment.md): The Docker-based development environment with an interactive terminal dashboard that manages your entire stack, streams logs, and controls watchers.
+
 - [Admin Extension SDK](https://developer.shopware.com/resources/admin-extension-sdk/): an NPM library for Shopware 6 apps and plugins that need an easy way to extend or customize the Administration.
 
 - `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).
 
-- [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper.md):  Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
+- [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper.md): Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
 
 - [Fixture Bundle](../../../guides/development/tooling/fixture-bundle.md): Seed development environments with demo and test data.
 
diff --git a/guides/installation/index.md b/guides/installation/index.md
index 56ce7edc57..434c682308 100644
--- a/guides/installation/index.md
+++ b/guides/installation/index.md
@@ -90,63 +90,32 @@ If the summary looks good, choose `proceed` to start the process of setting up S
 
 When it finishes, users who did not install with Docker will receive guidance to continue.
 
-### Finish Docker setup (optional)
+### Start your development environment
 
-When setup finishes, users who installed with Docker will see this prompt:
-
-- Start containers:  `cd <project name> && make up`
-- Set up Shopware:  `make setup`
-- Stop containers:  `make down` (do this later)
-
-Running `make up` starts Shopware and all required services (web server, database, search, Mailpit, etc.) in the background. Docker images already include all required PHP extensions and services, so the system-check step of the installer is always fulfilled.
-
-Running `make setup` is necessary to access the new shop.
-
-:::info
-What happens during `make setup`:
-
-- The Makefile runs the Shopware installer inside the web container
-- Shopware is installed automatically (no browser wizard required)
-- A MariaDB database is created
-- An admin user is created, with username `admin` and password `shopware`
-- Required services (database, search, mail, etc.) are preconfigured and run inside Docker
-- The Shopware project is configured to connect to the database via the Docker service name `database`
-- Database credentials are defined in the `compose.yaml`
-- If Elasticsearch was enabled during project creation, a compatible search service runs as part of the Docker stack.
-:::
-
-Check the container status anytime with the following command:
+Once the project is created, start the development environment with:
 
 ```bash
-docker compose ps
+cd my-shop
+shopware-cli project dev
 ```
 
-::: info
-Docker installations are set up through the CLI wizard. `make setup` runs the installer inside the web container and configures the database for you. There is no browser installer step to fill in.
+This launches the Development 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.
 
-If you set `DATABASE_URL` yourself or connect external tooling, use the Docker service name `database` as the host, not `localhost`, because containers reach each other by service name on the Docker network. The database name and credentials are defined in your project's `compose.yaml`.
-:::
+For details, see the [Development Environment guide](../development/dev-environment.md).
 
-### Accessing the new shop (all setups)
+### Accessing your shop
 
-The prompt also provides links to access the new shop in the browser:
+When the environment is running, your shop is accessible at:
 
 - Storefront: [http://127.0.0.1:8000](http://127.0.0.1:8000)
 - Admin: [http://127.0.0.1:8000/admin](http://127.0.0.1:8000/admin)
-- Credentials: `admin` / `shopware`
-
-Users who do not install with Docker can also use the Storefront and Administration URLs to continue.
-
-If you're setting up Shopware for the very first time, you may prefer to complete Shopware installation from the Administration UI using the First Run Wizard:
-
-- Sign in or create a Shopware account; this is necessary when you want to install Store extensions
-- Connect to the **Shopware Store**
-- Install plugins or themes from the Store
-- Configure payment methods if you need them (not required for local development)
+- Default credentials: `admin` / `shopware`
 
-Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **`Settings > Shop > Basic information`**.
+Check container status anytime with:
 
-However, most developers will want to continue from the terminal.
+```bash
+docker compose ps
+```
 
 ### Next steps
 
diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md
index 4a2abd61a9..970649c209 100644
--- a/guides/installation/project-overview.md
+++ b/guides/installation/project-overview.md
@@ -11,19 +11,27 @@ You have just installed Shopware, and this section guides you through the fundam
 
 ## Development tooling
 
-The Docker setup provisions Shopware for development. Development tools such as:
+The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) 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
+- Admin and Storefront Watchers (HMR)
+- PHP version and profiler configuration (xdebug, blackfire, tideways, etc.)
+- Service discovery (Adminer, Mailpit, queue, etc.)
+
+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.
+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.
 
 [Demo data](https://github.com/shopware/SwagPlatformDemoData) is optional and can be installed during the in-browser first-run wizard.
 
 Your local project is ready for debugging, profiling, and extension development out of the box.
 
-In day-to-day development, you’ll mostly interact with:
+In day-to-day development, you'll mostly interact with:
 
 - **Makefile**: shortcuts for Docker and Shopware commands (`make up`, `make setup`, etc.)
 - **custom/**: where you build your own plugins and themes
@@ -54,10 +62,10 @@ Container names depend on the name of your project folder.
 | Name                                  | Type                    | Purpose                                                                                                                       |
 |---------------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------|
 | **Network `my-project_default`**      | Docker network          | A private virtual network so all containers can communicate (for example, the web container connects to the database).        |
-| **Volume `my-project_db-data`**       | Persistent storage      | Stores the MariaDB database files so your data isn’t lost when containers are stopped or rebuilt.                             |
+| **Volume `my-project_db-data`**       | Persistent storage      | Stores the MariaDB database files so your data isn't lost when containers are stopped or rebuilt.                             |
 | **Container `my-project-mailer-1`**   | Mailpit service         | Captures outgoing emails for local testing. View at `http://localhost:8025`.                           |
 | **Container `my-project-database-1`** | MariaDB service         | Runs the Shopware database. Inside the Docker network, its hostname is `database`.                                            |
-| **Container `my-project-web-1`**      | PHP + Caddy web service | Runs Shopware itself and serves the storefront and Admin UI at `http://localhost:8000`.                |
+| **Container `my-project-web-1`**      | PHP + Caddy web service | Runs Shopware itself and serves the Storefront and Admin UI at `http://localhost:8000`.                |
 | **Container `my-project-adminer-1`**  | Adminer (DB UI)         | Lightweight web interface for viewing and editing your database. Available at `http://localhost:8080`. |
 
 ### Project structure
@@ -91,17 +99,17 @@ This table outlines the key directories and files in your Shopware project and t
 
 | Item                      | Type                        | Purpose / what it contains                                                                 | Notes                                                                                             |
 |---------------------------|-----------------------------|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
-| **bin/**                  | Directory                   | Executable scripts (e.g., `bin/console` — the main CLI for Shopware/Symfony).              | Think of it like `npm run` or `go run` scripts. Use `bin/console` to run commands inside the app. |
-| **compose.yaml**          | Docker                      | Defines the Docker services (web, database, mailpit, etc.).                                | Equivalent to your project’s “infrastructure recipe.”                                             |
+| **bin/**                  | Directory                   | Executable scripts (e.g., `bin/console` - the main CLI for Shopware/Symfony).              | Think of it like `npm run` or `go run` scripts. Use `bin/console` to run commands inside the app. |
+| **compose.yaml**          | Docker                      | Defines the Docker services (web, database, mailpit, etc.).                                | Equivalent to your project's "infrastructure recipe."                                             |
 | **compose.override.yaml** | Docker                      | Local overrides for the default Docker Compose stack (e.g., port mappings, extra volumes). | Optional; used to customize or extend services locally.                                           |
 | **composer.json**         | PHP dependency manifest     | Lists PHP dependencies and metadata (like `package.json`).                                 | `composer install` reads this.                                                                    |
-| **composer.lock**         | Dependency lock file        | Locks exact versions of PHP packages.                                                      | Don’t edit manually; committed to git.                                                            |
+| **composer.lock**         | Dependency lock file        | Locks exact versions of PHP packages.                                                      | Don't edit manually; committed to git.                                                            |
 | **config/**               | Directory                   | Symfony configuration files (framework, database, mail, etc.).                             | Similar to `config/` in many web frameworks.                                                      |
-| **custom/**               | Directory                   | Your plugins, themes, or app customizations.                                               | This is where you add new extensions — your “src” for Shopware plugins.                           |
+| **custom/**               | Directory                   | Your plugins, themes, or app customizations.                                               | This is where you add new extensions - your "src" for Shopware plugins.                           |
 | **files/**                | Directory                   | Uploaded media and temporary files.                                                        | Ignored by git; generated at runtime.                                                             |
 | **Makefile**              | Build helper                | Shortcuts for Docker tasks (`make up`, `make setup`, etc.).                                | Replaces long Docker commands with memorable aliases.                                             |
 | **public/**               | Web root                    | The actual web-server-accessible directory (contains `index.php`, assets, etc.).           | Like `/dist` in JS frameworks or `/public_html`.                                                  |
-| **src/**                  | Source code                 | Shopware’s core application source.                                                        | Where the main PHP codebase lives; not usually edited in a project clone.                         |
+| **src/**                  | Source code                 | Shopware's core application source.                                                        | Where the main PHP codebase lives; not usually edited in a project clone.                         |
 | **symfony.lock**          | Symfony dependency snapshot | Records Symfony recipes applied during setup.                                              | Used internally by Symfony Flex; no manual editing.                                               |
 | **var/**                  | Runtime data                | Cache, logs, temporary files.                                                              | Can safely be deleted (Shopware rebuilds it).                                                     |
 | **vendor/**               | Dependency code             | All installed PHP libraries from Composer.                                                 | Analogous to `node_modules/`.                                                                     |
diff --git a/products/tools/cli/index.md b/products/tools/cli/index.md
index 1cc279c3c4..d8e81fd859 100644
--- a/products/tools/cli/index.md
+++ b/products/tools/cli/index.md
@@ -10,6 +10,7 @@ nav:
 [Shopware CLI](https://github.com/shopware/shopware-cli) is the open-source command-line interface for working with Shopware 6. It's a standalone developer tool that you install and configure separately from your Shopware instance. Once set up, it helps you automate and speed up common tasks such as:
 
 - managing and configuring Shopware projects
+- starting and operating an integrated Docker-based development environment
 - building, validating, and packaging extensions
 - uploading and maintaining extensions in the Shopware Store
 - running CI/CD pipelines for Shopware-based solutions
diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md
new file mode 100644
index 0000000000..71c375abaf
--- /dev/null
+++ b/products/tools/cli/project-commands/dev-environment.md
@@ -0,0 +1,80 @@
+---
+nav:
+  title: Development Environment
+  position: 1
+
+---
+
+# Development Environment (CLI Reference)
+
+This page is a quick reference for the `shopware-cli project dev` and `shopware-cli project logs` commands. For the full development workflow and setup guide, see [Development Environment](../../../../guides/development/dev-environment.md).
+
+## Commands
+
+### Start the environment
+
+```bash
+# Interactive dashboard (default when run in a terminal)
+shopware-cli project dev
+
+# Start in the background (for CI or scripting)
+shopware-cli project dev start
+
+# Check whether the environment is running
+shopware-cli project dev status
+
+# Stop the environment
+shopware-cli project dev stop
+```
+
+The interactive dashboard has three tabs:
+
+- **Overview** — shop info, access credentials, setup health checks, and watcher toggles
+- **Instance** — containers, watcher processes, and log files with live-streaming
+- **Config** — PHP version, profiler
+
+### View application logs
+
+```bash
+# Last 100 lines of the most recently modified log file
+shopware-cli project logs
+
+# A specific log file
+shopware-cli project logs dev-2026-05-18.log
+
+# Follow the log in real time
+shopware-cli project logs -f
+
+# List available log files
+shopware-cli project logs -l
+
+# Set number of lines to show (default: 100)
+shopware-cli project logs --lines 50
+```
+
+## Configuration
+
+The environment is configured in `.shopware-project.yml`. See the [full configuration reference](../../../../guides/development/dev-environment.md#configuration-reference) for all options.
+
+```yaml
+# .shopware-project.yml
+compatibility_date: '2026-03-01'
+
+docker:
+  php:
+    version: "8.3"
+    profiler: xdebug
+
+environments:
+  local:
+    type: docker
+    url: http://127.0.0.1:8000
+    admin_api:
+      username: admin
+      password: shopware
+```
+
+## 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
index 2fd24bcaf8..71ee0f5de0 100644
--- a/products/tools/cli/project-commands/helper-commands.md
+++ b/products/tools/cli/project-commands/helper-commands.md
@@ -25,6 +25,23 @@ 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
+
+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 development terminal user interface (TUI)
+shopware-cli project dev
+
+# Start/stop in the background
+shopware-cli project dev start
+shopware-cli project dev status
+shopware-cli project dev stop
+
+# View application logs
+shopware-cli project logs
+```
+
 ## Replacements to include in shell scripts
 
 Shopware CLI contains replacements for `bin/build-administration.sh` and `bin/build-storefront.sh`.
@@ -36,7 +53,7 @@ Shopware CLI contains replacements for `bin/build-administration.sh` and `bin/bu
 | bin/watch-storefront.sh     | `shopware-cli project storefront-watch` |
 | bin/watch-administration.sh | `shopware-cli project admin-watch`      |
 
-Additionally to the replacement, Shopware CLI allows only watching a specific set of extensions or excluding a few.
+In addition to the replacements, Shopware CLI allows only watching a specific set of extensions or excluding a few.
 
 To only watch specific extensions:
 
@@ -52,7 +69,7 @@ shopware-cli project admin-watch --skip-extensions <name>,<second>....
 
 ### Building only custom extensions
 
-When working with a lot of 3rd party extensions, `project storefront-build` and `project admin-build` would become slow, when all extensions are built.
+When working with many third-party extensions, `project storefront-build` and `project admin-build` would become slow, when all extensions are built.
 This is unnecessary because store extensions are shipped together with their assets.
 
 Use
@@ -82,7 +99,7 @@ It is just a shortcut for `bin/console cache:clear` without having to be in the
 shopware-cli project clear-cache
 ```
 
-If in the `.shopware-project.yml` a API connection is configured, it will clear the remote instance cache.
+If an API connection is configured in the `.shopware-project.yml`, it will clear the remote instance cache.
 
 ## Console
 
@@ -92,6 +109,8 @@ Similar to `clear-cache`, there is also a general shortcut for `bin/console`:
 shopware-cli project console <command>
 ```
 
+A shorter `swx` alias is also available. See [Running Shopware commands](../../../../guides/development/dev-environment.md#running-shopware-commands).
+
 ## Admin API
 
 If you want to make requests against the Shopware-API using curl, you need to get a JWT token and add it as a header. Shopware CLI has a helper command for that: