shopware · somethings (lasomethingsomething) · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026
diff --git a/concepts/api/index.md b/concepts/api/index.md
@@ -21,3 +21,7 @@ Both APIs use HTTP and exchange JSON payloads. The Administration API requires O
 * Header-based contextual behavior
 
 These patterns form the foundation of integration development.
+
+## Start building
+
+Use the [API](../../guides/development/integrations-api/index.md) guide for practical API setup, authentication, request examples, and links to the generated API reference.
diff --git a/concepts/extensions/index.md b/concepts/extensions/index.md
@@ -22,9 +22,12 @@ Starting with Shopware 6.4.0.0, we introduced a new way to extend Shopware using
 Plugins are executed within the Shopware Core process and can react to events, execute custom code or extend services. They have direct access to the database and guidelines are in place to ensure update-compatibility, such as a service facade or database migrations.
 
 ::: warning
-**Plugins and Shopware cloud** - Due to their direct access to the Shopware process and the database, plugins are not supported by Shopware cloud.
+Due to their direct access to the Shopware process and the database, **plugins are not supported by Shopware cloud**.
 :::
 
-## Start coding
+## Start building
 
-Refer to our Guides section for an [overview of how apps and plugins differ](../../guides/plugins/index).
+Use the [Extensions](../../guides/development/extensions/index.md) guide to choose between apps and plugins, or go directly to the implementation path you need:
+
+- [App Base Guide](../../guides/plugins/apps/app-base-guide.md)
+- [Plugin Base Guide](../../guides/plugins/plugins/plugin-base-guide.md)
diff --git a/guides/development/integrations-api/index.md b/guides/development/integrations-api/index.md
@@ -11,7 +11,7 @@ This guide helps you make your first successful API request. Your Shopware insta
 
 Shopware provides two HTTP APIs:
 
-- **Admin API** for backend operations such as products, orders, customers, plugins, and (via the Sync API) bulk processing
+- **Admin API** for backend operations such as products, orders, customers, plugins, and — via the Sync API — bulk operations (for example, mass imports)
 - **Store API** for storefront-facing interactions such as headless frontends, mobile apps, carts, checkout, and sales channel access
 
 For the complete endpoint reference and schemas, use the official Stoplight documentation:

diff --git a/guides/development/tooling/index.md b/guides/development/tooling/index.md
@@ -7,7 +7,38 @@ nav:
 
 # Tooling
 
-Shopware provides official tools that support the full lifecycle of a Shopware project, from development to deployment and long-term maintenance:
+Shopware provides official tools that support the full lifecycle of a Shopware project, from development to deployment and long-term maintenance.
+
+## Choosing the right CLI
+
+Shopware projects use two main command-line entry points:
+
+| Tool                                                        | Use it for                                                                                                                                                                                                |
+|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `bin/console`                                               | Commands provided by the Shopware application itself, such as plugin lifecycle commands, database migrations, cache clearing, scheduled tasks, and system inspection.                                     |
+| [`shopware-cli`](https://github.com/shopware/shopware-cli/) | Project and extension tooling around Shopware, such as creating projects, running the development environment, building assets, validating and packaging extensions, Store interaction, and CI workflows. |
+| `shopware-cli project console <command>`                    | Running a Shopware `bin/console` command through Shopware CLI when you want the CLI to resolve the project context for you.                                                                               |
+| `swx <command>`                                             | Short alias for `shopware-cli project console <command>`, useful for daily development commands.                                                                                                          |
+| `shopware-cli project dev`                                  | Starting the interactive local development environment and TUI for managing the Docker-based stack, logs, watchers, and common development tasks.                                                         |
+
+As a rule of thumb: use `bin/console` for application-level Shopware commands, use `shopware-cli` for project, extension, build, CI, and development-environment workflows, and use `swx` when you want a quick wrapper around `bin/console`.
+
+## Raw commands, helper commands, or deployment tooling?
+
+Use the lowest-level command that fits the task, but prefer helper or deployment tooling when the same steps need to be repeated reliably.
+
+| Situation                                                 | Prefer                                                      | Why                                                                                                                                                      |
+|-----------------------------------------------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Running a one-off Shopware application command locally    | `bin/console`                                               | Direct access to commands provided by the Shopware application.                                                                                          |
+| Running common Shopware commands during daily development | `shopware-cli project console <command>` or `swx <command>` | Wraps `bin/console` through Shopware CLI and resolves the project context for you.                                                                       |
+| Starting or managing the local development stack          | `shopware-cli project dev`                                  | Provides the interactive development environment for the Docker-based stack, logs, watchers, and common development tasks.                               |
+| Building a project in CI                                  | `shopware-cli project ci`                                   | Produces a reproducible build artifact with dependencies and assets prepared before deployment.                                                          |
+| Installing, updating, or maintaining a deployed instance  | Deployment Helper                                           | Automates deploy-time tasks such as install/update detection, migrations, extension management, maintenance mode, cache handling, and one-time commands. |
+| Debugging an exceptional production issue manually        | Raw commands, carefully                                     | Useful for investigation, but repeated deployment or maintenance steps should move into Deployment Helper configuration.                                 |
+
+As a rule of thumb: use raw `bin/console` commands for direct local or diagnostic work, Shopware CLI helpers for daily development convenience, and Deployment Helper for repeatable deployment and maintenance workflows.
+
+## Available tooling
 
 - [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.
 

diff --git a/guides/hosting/configurations/shopware/index.md b/guides/hosting/configurations/shopware/index.md
@@ -5,8 +5,26 @@ nav:
 
 ---
 
-# Shopware configurations
+# Shopware Configurations
 
 ## Overview
 
 The following section guides you on the security, performance or structural configurations specific to Shopware 6.
+
+## How Shopware configuration works
+
+Shopware configuration can come from different places, depending on whether the value is operational, environment-specific, or meant to be changed by shop administrators.
+
+| Mechanism                            | Use it for                                                                                        | Where it lives                                                                                   |
+|--------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
+| Database-backed system configuration | Shop settings that can be changed in the Administration, through Admin API, or by app/plugin code | Stored in the database and read through Shopware's system configuration                          |
+| Static system configuration          | Settings that must be fixed, versioned, or controlled per environment                             | `config/packages/*.yaml` under `shopware.system_config`                                          |
+| Symfony / bundle configuration       | Technical runtime configuration for Shopware, Symfony, or bundles                                 | `config/packages/*.yaml`, including environment-specific folders such as `config/packages/prod/` |
+| Environment variables                | Secrets, infrastructure values, and deployment-specific values                                    | `.env`, `.env.local`, server/container environment, or deployment platform                       |
+| CLI commands                         | Reading, writing, or inspecting configuration during development, deployment, or maintenance      | `bin/console` / `shopware-cli project console`                                                   |
+
+As a rule of thumb: use Administration or database-backed system configuration for shop settings that merchants may change, static system configuration for values that should be fixed or version-controlled, and environment variables or Symfony configuration for deployment and infrastructure settings.
+
+Static system configuration is an overlay on top of database-loaded system configuration. If the same key is configured in both places, the value from `config/packages` wins and the setting can no longer be changed in the Administration.
+
+For details, see [Static System Configuration](./static-system-config.md).
diff --git a/guides/hosting/installation-updates/extension-management.md b/guides/hosting/installation-updates/extension-management.md
@@ -54,6 +54,10 @@ bin/console plugin:install --activate <extension-name>
 
 You can also find the Composer package name when you click "Install via Composer" in the Shopware Account.
 
+:::warning
+Removing a Composer package or uninstalling a plugin does not cancel a paid subscription. License state is managed in the Shopware Account, and cancellation must be done there.
+:::
+
 ## Migrating already installed extensions to Composer
 
 If you already have extensions installed in your project, you can migrate them to Composer. First, you should install the extension with Composer:

diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md
@@ -27,23 +27,20 @@ Development tools such as:
 
 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.
+[Demo data](https://github.com/shopware/SwagPlatformDemoData) is optional. For developer setups, prefer terminal-based setup and development workflows instead of 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:
 
-- **Makefile**: shortcuts for Docker and Shopware commands (`make up`, `make setup`, etc.)
-- **custom/**: where you build your own plugins and themes
-- **bin/console**: the application CLI that ships with Shopware (Symfony console).
-  It is used for tasks such as running migrations, installing plugins, clearing caches, or managing configuration in your project.
+- **`shopware-cli project dev`**: starts and manages the Docker-based development environment, including containers, logs, watchers, credentials, and service URLs.
+- **`shopware-cli project console <command>`**: runs Shopware application commands from your host without opening an interactive container shell.
+- **`swx <command>`**: shortcut for `shopware-cli project console <command>`, for example `swx cache:clear`.
+- **`custom/`**: where you build your own plugins and themes.
 
-:::info
-`bin/console` differs from the standalone [Shopware CLI](https://github.com/shopware/shopware-cli) used for extension builds and CI workflows.
-The Docker setup already includes the standalone Shopware CLI inside the container.
-:::
+`bin/console` is the application CLI that ships with Shopware (Symfony console). Use it for Shopware application commands such as migrations, plugin installation, cache clearing, or configuration changes. In Docker-based setups, run those commands through `shopware-cli project console` or `swx` so they execute in the correct container context.
 
-Most other files in the project either configure the environment or support these core layers.
+The standalone [Shopware CLI](https://github.com/shopware/shopware-cli) is different from `bin/console`: it manages project workflows such as the development environment, helper commands, extension builds, and CI workflows.
 
 ## Project template
 
@@ -107,7 +104,7 @@ This table outlines the key directories and files in your Shopware project and t
 | **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.                           |
 | **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.                                             |
+| **Makefile**              | Legacy build helper                | May exist in older setups with 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.                         |
 | **symfony.lock**          | Symfony dependency snapshot | Records Symfony recipes applied during setup.                                              | Used internally by Symfony Flex; no manual editing.                                               |

diff --git a/guides/plugins/apps/administration/meteor-admin-sdk.md b/guides/plugins/apps/administration/meteor-admin-sdk.md
@@ -10,12 +10,12 @@ The [Meteor Admin SDK](https://github.com/shopware/meteor/tree/main/packages/adm
 
 To write advanced apps, its recommended that you use the [Meteor Admin SDK](https://github.com/shopware/meteor/tree/main/packages/admin-sdk). It contains helper functions to communicate with the Administration, execute actions, subscribe to data or extend the user interface. It has many more features and is more flexible.
 
-- 🏗  **Works with Shopware 6 Apps and Plugins:** You can use the SDK for your plugins or apps. API usage is identical.
-- 🎢  **Shallow learning curve:** You don't need to have extensive knowledge about the internals of the Shopware 6 Administration. Our SDK hides the complicated stuff behind a beautiful API.
-- 🧰  **Many extension capabilities:** Includes throwing notifications, accessing context information, extending the current UI and more. The feature set of the SDK will gradually be extended, providing more possibilities and flexibility for your ideas and solutions.
-- 🪨  **A stable API with great backwards compatibility:** Don't fear Shopware updates anymore. Breaking changes in this SDK are an exception. If you use the SDK, your apps and plugins will stay stable for a longer time, without any need for code maintenance.
-- 🧭  **Type safety:** The whole SDK is written in TypeScript which provides great autocompletion support and more safety for your apps and plugins.
-- 💙  **Developer experience:** Have a great development experience right from the start. And it will become better and better in the future.
-- 🪶  **Lightweight:** The whole library is completely tree-shakable and dependency-free. Every functionality can be imported granularly to keep your bundle as small and fast as possible.
+- **Works with Shopware 6 Apps and Plugins:** You can use the SDK for your plugins or apps. API usage is identical.
+- **Shallow learning curve:** You don't need to have extensive knowledge about the internals of the Shopware 6 Administration. Our SDK hides the complicated stuff behind a beautiful API.
+- **Many extension capabilities:** Includes throwing notifications, accessing context information, extending the current UI and more. The feature set of the SDK will gradually be extended, providing more possibilities and flexibility for your ideas and solutions.
+- **A stable API with great backwards compatibility:** Don't fear Shopware updates anymore. Breaking changes in this SDK are an exception. If you use the SDK, your apps and plugins will stay stable for a longer time, without any need for code maintenance.
+- **Type safety:** The whole SDK is written in TypeScript which provides great autocompletion support and more safety for your apps and plugins.
+- **Developer experience:** Have a great development experience right from the start. And it will become better and better in the future.
+- **Lightweight:** The whole library is completely tree-shakable and dependency-free. Every functionality can be imported granularly to keep your bundle as small and fast as possible.
 
 Go to [Installation](https://developer.shopware.com/resources/admin-extension-sdk/getting-started/installation.html) to get started. Or check out the [quick start guide](https://developer.shopware.com/resources/admin-extension-sdk/#quick-start).
diff --git a/guides/plugins/plugins/administration/index.md b/guides/plugins/plugins/administration/index.md
@@ -21,6 +21,8 @@ Typical use cases include:
 
 This section follows a practical development workflow. Start with registering a module and route, then build the components, connect data, and refine permissions and UI behavior.
 
+For stable cross-version extension points, use the [Meteor Admin SDK](../../apps/administration/meteor-admin-sdk.md). The SDK can be used by both apps and plugins.
+
 ## Developer workflow
 
 When extending the Administration inside a plugin, follow this sequence: