-
+```
+
+### Fallback language / translations
+
+Extensions must work independently of the system language.
+
+If a translation is missing (e.g., Spanish), a proper fallback (usually English) must be used.
+
+If your extension is available in multiple languages, define them in your Shopware Account under “Translations into the following languages are available,” located in the "Description & images" section.
+
+We review:
+
+* Text snippets
+* `config.xml`
+* `composer.json`
+
+### Reserve your extension name with a store preview
+
+To secure an idea early, create a preview in your Shopware Account. Request this by providing placeholder images, meaningful use cases, key features, a description, and an expected release month. No binary upload is required.
+
+### Extension master data/license
+
+The license selected in your Shopware Account must match the license defined in `composer.json`. The selected license cannot be changed after the extension has been created. Changes require creating a new extension with a new technical name and uploading it again.
+
+## Screenshots and media requirements
+
+* Use English-only screenshots for the English store listing and preview images.
+* Screenshots in German for the German store description are optional.
+* Only images that represent or show the function of the extension are permissible.
+* Advertising for other extensions or services is not permitted.
+* Ensure that screenshots show the extension's functionality in action in the Storefront and administration, as well as configuration options and how-to-use details.
+* We recommend screenshots showing mobile and desktop views.
+
+:::Info
+[How To - Add images and icons to extensions](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to)
+:::
+
+## Preview requirements
+
+* A preview image must be available in the Extension Manager.
+* Store a valid favicon named `plugin.png` (112x112px) under `src/Resources/config/`. This favicon will help you identify your extension in the Extension Manager module in the Administration.
+* [Themes](../../../../../guides/plugins/themes/) require a preview image in the Theme Manager.
+* [Shopping World elements](../../../../../concepts/commerce/content/shopping-experiences-cms.md#elements) must include an element icon.
+
+Read our [How to request a preview](https://docs.shopware.com/en/account-en/extension-partner/extensions?category=account-en/extension-partner#how-can-i-request-a-preview) guide for additional help.
+
+## Demo shop requirements
+
+* URLs must not contain `http:` or `https:`.
+* Test environments will be automatically deleted after two weeks, so do not link to them.
+
+## Manufacturer profile requirements
+
+The manufacturer profile exists in your account under Shopware Account > Extension Partner > [Extension Partner profile](https://account.shopware.com/producer/profile).
+
+* A manufacturer logo is required.
+* No iframes, tracking, or external scripts are allowed.
+* External sources must use HTTPS.
+* Must contain accurate English and German descriptions.
+
+::: info
+The source code's descriptions, profiles, and instructions do not allow iframes, external scripts, or tracking pixels. Custom styles may not overwrite the original Shopware styles. External sources must be included via https.
+:::
+
+::: info
+You can no longer advertise Shopware certificates within a extension's description, images, or your manufacturer profile.
+Manufacturer/partner certificates are dynamically loaded at the end of each extension description and published by Shopware.
+:::
+
+## Data Protection
+
+If the personal data of customers, including store operators and their customers, is processed according to Art. 28 DSGVO:
+
+* Subprocessor information must be declared.
+* Additional processors must be listed accordingly, under "further subprocessors."
+
+An extension with a name that directly reflects its functional purpose is permissible, even if it shares the same name as another extension.
+
+The store display name must be used for `composer.json` and `config.xml`.
+
+Not allowed:
+
+* Inline styles.
+* Certificates in descriptions.
+* Iframes, tracking pixels, external scripts.
+
+We allow up to two YouTube videos embedded in your extension description.
+
+:::info
+Video content—especially explainer videos, product demos, and tutorials—increases awareness and trust and has proven to convert potential customers better than other content types.
+:::
+
+## Functional requirements
+
+All extensions must:
+
+* Work without 500 errors.
+* Avoid 400 errors unless they are related to an API call.
+* Be installable and uninstallable without issues.
+* During uninstall, users must be able to choose in the Extension Manager whether to "completely delete or "keep the app data, text snippets, media folder including own media and table adjustments." The free [Adminer](https://store.shopware.com/en/frosh79014577529f/adminer-for-admin.html) extension from Friends of Shopware enables you to do this via your provided test environment.
+* Avoid extending or overwriting the Extension Manager.
+* Properly register cookies in the [Cookie Consent Manager](../../../../../guides/plugins/plugins/storefront/add-cookie-to-manager).
+ * Every cookie set from the store URL should be optional and not technically required for running Shopware. We differentiate between "Technically required", "Marketing," and "Comfort features."
+ * All cookies must appear (unchecked) in the cookie configuration box in the frontend.
+* Not introduce severe performance regressions.
+* Not break Storefront SEO, structured data, or canonical logic.
+* If the extension publishes messages to the message queue, each message must not exceed 262,144 bytes (256 KB). This limitation is set by common message queue workers.
+* After uninstalling the extension, Shopping Experiences must continue to work in the frontend.
+
+### Plugin-specific requirements
+
+These apply only to plugins:
+
+* [Composer dependencies](../../../../../guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies) must be declared in `composer.json` so they are traceable.
+ * If `executeComposerCommands() === true` is used, dependencies are installed dynamically and do not need to be bundled.
+* `composer.lock` must not be included in the archive.
+* Deliver uncompiled (readable) JavaScript in addition to compiled assets. Uncompiled sources must be included in a separate folder to allow code review.
+ * Build `main.js` and create the minified code according to our documentation: [Loading the JS files](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#loading-the-js-files) and [Injecting into the Administration](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#injecting-into-the-administration).
+* Only production files may be included in archive.
+* Unified logs must be written to `/var/log/`.
+* No forbidden PHP statements like `die`, `exit`, or `var_dump` are allowed. See [List of blockers](https://s3.eu-central-1.amazonaws.com/wiki-assets.shopware.com/1657519735/blocker.txt)
+* Shopware must have access to the unminified source code of the extension at all times.
+
+### App-specific requirements
+
+These apply only to apps:
+
+* Per-sales-channel configuration required if using `config.xml``.
+* No loading external files during installation.
+* API integrations must include API test button.
+* Must not modify Extension Manager.
+* STP agreement required for commission-based integrations.
+* Apps that appear in the Storefront and use a `config.xml` must be able to be configured separately for each sales channel.
+
+## Code and security requirements
+
+* Pass automated code reviews (PHPStan, SonarQube).
+* Not include development files or unused resources in the binary.
+* Include only necessary dependencies.
+* Use secure cookie settings.
+
+## Composer and dependencies
+
+If the extension includes Composer dependencies:
+
+* All delivered code must be traceable via Composer.
+* The extension must not exceed store size limits.
+
+## Storefront guidelines
+
+* No inline CSS allowed in storefront templates. Use your own classes and let your CSS be compiled by the plugin. See [Add SCSS variables](../../../../../guides/plugins/plugins/storefront/add-scss-variables.md#add-scss-variables).
+* Avoid using the `!important` rule unless unavoidable.
+* All images must include meaningful `alt` tags, or original `alt` tags from the media manager.
+* All links must include meaningful `title` tags.
+* External links must use `target="_blank"` together with `rel="noopener"`.
+* No `` tags in the storefront templates, which are set to ``. These are reserved exclusively for content purposes.
+ * However, you may employ ``, for instance.
+* Performance should remain stable (Lighthouse A/B check recommended).
+* Test the frontend and the checkout for new errors throughout the entire Storefront using the Browser Debug Console, paying close attention to JavaScript errors.
+
+## SEO & indexing requirements
+
+* New controller URLs or XHR requests must include the header `X-Robots-Tag: noindex, nofollow`. See [robots meta tag](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag?hl=de#xrobotstag) documentation for additional guidance.
+* Public frontend URLs created by the extension must appear in `sitemap.xml` and include a valid canonical tag, unique meta descriptions, and `title` tags (configurable via Administration or as a text snippet).
+
+## Administration guidelines
+
+* Do not add new main menu entries in the Administration, to preserve look and feel consistency.
+* Create a dedicated media folder with correct thumbnail settings or use an existing one (except for uploads defined in `config.xml`).
+* Custom media folders and their contents must be removed during uninstall.
+* All links must include meaningful `title` tags.
+* All images must include meaningful `alt` tags, or original `alt` tags from the media manager.
+* If your API corresponds via API credentials to external services, provide an API test button. ([Example implementation](https://github.com/shyim/ShyimApiTest) in the system config form)
+* It is possible to validate required credentials while saving them in extension settings. Display a status message in the Administration and log the result in Shopware.
+* If API data is incorrect, an entry must appear in the `/var/log/` file or in the database event log.
+
+### Installation and lifecycle
+
+* The Extension Manager (Debug Console) controls installation, uninstallation, reinstallation, and deletion.
+* Install, uninstall, reinstall must work without exceptions.
+* No 400/500 errors during install/uninstall are allowed.
+* Users must be able to choose whether to delete or keep extension data.
+* Special PHP requirements must be validated during installation.
+* If validation fails, a growl message must appear in the Administration.
+* Extensions must not modify or overwrite the Extension Manager.
+* Apps must not reload or load external files during installation.
+
+### Error messages and logging
+
+* Error or informational messages can only be recorded in the event log of Shopware's log folder, `/var/log/`.
+* Do not write to Shopware’s default logs or outside the system log directory. This ensures that the log file can never be accessed via the URL.
+* Log files must follow naming pattern: `MyExtension-Year-Month-Day.log`.
+* Payment apps must use the "plugin logger" service.
+* If storing logs in a database, avoid using custom log tables. Otherwise, you have to implement scheduled cleanup (max retention six months).
+
+### API integrations
+
+If external APIs are used:
+
+* API test button required.
+* Credentials must be validated on save.
+* Success/failure must display status message in Administration.
+* Errors must be logged in `/var/log/` or database.
+
+## Commercial and external integrations
+
+If your extension integrates with external services and generates revenue (e.g., interfaces with downstream fees), a Shopware Technology Partner (STP) agreement may be required.
+
+Commission-based integrations must report usage data according to the STP contract:
+
+Every external technology extension needs to track its commission. Below is an example of implementing the tracking logic:
+
+```json
+ {
+ "identifier": "8e167662-6bbb-11eb-9439-0242ac130002",
+ "reportDate": "2005-08-15T15:52:01",
+ "instanceId": "alur24esfaw3ghk",
+ "shopwareVersion": "6.3.1",
+ "reportDataKeys": [
+ {
+ "customer": 3
+ },
+ {
+ "turnover": 440
+ }
+ ]
+ }
+```
+
+`// POST /shopwarepartners/reports/technology` allows partners to send Shopware the info based on the STP contract.
+
+If you have any questions regarding the STP agreement, please contact our sales team at [alliances@shopware.com](mailto:alliances@shopware.com) or call **+44 (0) 203 095 2445 (UK) / 00 800 746 7626 0 (worldwide) / +49 (0) 25 55 / 928 85-0 (Germany)**.
+
+**Progressive Web App:** If your app is Progressive Web App-compatible and you would like the PWA flag, please contact us at [alliances@shopware.com](mailto:alliances@shopware.com).
+
+### External fonts and services
+
+If external fonts (e.g., Google Fonts, Font Awesome) or other third-party services are used, this must be clearly stated in the store description.
+
+If personal data is transferred, update your data protection information accordingly. A tooltip in the extension configuration is recommended to inform users.
+
+## Lighthouse A/B-Testing
+
+Run a [Google Lighthouse](https://developer.chrome.com/docs/lighthouse) audit before and after activating the extension.
+
+Significant regressions in performance, accessibility, best practices, or SEO are allowed. No new console errors may be introduced.
+
+### schema.org/rich snippets A/B-testing checklist
+
+A/B testing can ensure structured data is valid and rich results behave correctly across page types.
+
+Use Scheme.org's [Schema Markup Validator](https://validator.schema.org/) and Google's [Rich Result Tester](https://search.google.com/test/rich-results) to check the homepage, categories, and product detail pages — including available products, unavailable products, products with no review, single review, reviews with varied ratings, out-of-stock products, products for future release, and/or any other product configuration and product types (including EAN, MPN, width, length, height, and weight). Also check for duplicate entries and any new bugs.
+
+## Tools
+
+Use the [Shopware CLI](/development/tooling/cli) to build, validate, and upload Shopware 6 plugin releases to the Community Store. It also supports managing store descriptions and plugin images efficiently.
+
+## Final notes
+
+An extension may be rejected if:
+
+* It violates coding standards.
+* It introduces security issues.
+* It bundles unauthorized files.
+* It breaks storefront behavior.
+* It misrepresents functionality in the store description.
+
+Ensure full compliance before submission to avoid delays in publication.
diff --git a/guides/development/extensions/monetization/store-review-errors.md b/guides/development/extensions/monetization/store-review-errors.md
new file mode 100644
index 0000000000..22a2db29be
--- /dev/null
+++ b/guides/development/extensions/monetization/store-review-errors.md
@@ -0,0 +1,167 @@
+---
+nav:
+ title: Store Review Errors
+ position: 30
+
+---
+
+# Common Store Review Errors
+
+These errors apply to all extensions submitted to the Shopware Store (plugins and apps).
+
+## Composer and bootstrap issues
+
+### Missing or invalid `composer.json`
+
+Typical causes:
+
+* `composer.json` missing.
+* Technical name mismatch between Store and `composer.json`.
+* Wrong `extra.shopware-plugin-class`.
+* The extension archive has an incorrect ZIP structure.
+
+Check:
+
+* Store technical name matches the `composer.json` name.
+* `extra.shopware-plugin-class` points to the correct bootstrap class.
+* Namespace matches exactly (case-sensitive).
+* Archive contains correct root folder structure.
+
+Example [reference](https://github.com/FriendsOfShopware/FroshPlatformPerformance/blob/master/composer.json#L20):
+
+**Correct**: `Swag\\MyPlugin\\SwagMyPlugin`
+**Incorrect**: `Swag\\MyPlugin\\SwagMyPluginSW6`
+
+[Extension Meta Information – Explanation of the properties](../../../../../guides/plugins/plugins/plugin-base-guide#the-composerjson-file)
+
+### Missing bootstrap class
+
+Common causes include:
+
+* Wrong ZIP structure.
+* A typo.
+* Case-sensitive filename mismatch.
+* Namespace mismatch.
+
+### `composer.lock` Problems
+
+Rules:
+
+* `composer.lock` must NOT be included in the archive.
+* Lock file must match `composer.json` before packaging.
+* Run `composer update` if lock is outdated.
+
+## Dependency and version errors
+
+### Missing Shopware packages
+
+An example error might look like `Class Shopware\Storefront\* not found`. To fix:
+
+* Declare required packages correctly and explicitly in `composer.json`: e.g., `"require": {"shopware/frontend": "*"}`.
+* Avoid "*" version constraints. Using "*" may resolve to Early Access (EA) versions, causing review failures.
+* Use proper version ranges (e.g. `~6.1.0`).
+* If needed, set `"minimum-stability": "RC"`.
+
+This example shows the correct format:
+
+```xml
+"require": {
+
+ "shopware/core": "~6.1.0",
+
+ "shopware/storefront": "~6.1.0"
+
+},
+
+"minimum-stability": "RC"
+```
+
+### Class Not Found (EA Version Issue)
+
+In the Shopware 6 Early Access (EA) version,`Class Shopware\Core\System\Snippet\Files\SnippetFileInterface` is not found and could not be autoloaded, causing the code review to fail.
+
+**Cause**: Composer resolved an Early Access version due to wildcard constraints.
+
+**Solution**: Pin versions and define minimum stability (see above).
+
+## Code & Static Analysis Errors
+
+### Forbidden Statements
+
+Blocked:
+
+* `die`
+* `exit`
+* `var_dump`
+
+### Invalid method usage
+
+You might see `Call to static method *jsonEncode() on an unknown class*`. Shopware always uses `json_encode()` exclusively - there is no other fallback.
+
+### Remove dead code
+
+Remove out-commented code from your source code. Ensure there are no unused classes or files.
+
+## Cross-Domain Messaging
+
+Ensure that cross-document messages are sent to the intended domain. Unrestricted messaging will be rejected.
+
+Link: ["Cross-document messaging domains should be carefully restricted"](https://rules.sonarsource.com/javascript/RSPEC-2819)
+
+## Cookie and security issues
+
+Cookies must be set securely. All non-essential cookies must be registered in the Cookie Consent Manager.
+
+## Packaging errors and unauthorized files and folders
+
+Extensions submitted to the Shopware Store must not contain development files, temporary artifacts, or unused resources.
+
+* ./tests
+* .DS_Store
+* .editorconfig
+* .eslintrc.js
+* .git
+* .github
+* .gitignore
+* .gitkeep
+* .gitlab-ci.yml
+* .gitpod.Dockerfile
+* .gitpod.yml
+* .phar
+* .php-cs-fixer.cache
+* .php-cs-fixer.dist.php
+* .php_cs.cache
+* .php_cs.dist
+* .prettierrc
+* .stylelintrc
+* .stylelintrc.js
+* .sw-zip-blacklist
+* .tar
+* .tar.gz
+* .travis.yml
+* .zip
+* .zipignore
+* ISSUE_TEMPLATE.md
+* Makefile
+* Thumbs.db
+* __MACOSX
+* auth.json
+* bitbucket-pipelines.yml
+* build.sh
+* composer.lock
+* eslint.config.js
+* grumphp.yml
+* package-lock.json
+* package.json
+* phpdoc.dist.xml
+* phpstan-baseline.neon
+* phpstan.neon
+* phpstan.neon.dist
+* phpunit.sh
+* phpunit.xml.dist
+* phpunitx.xml
+* psalm.xml
+* rector.php
+* shell.nix
+* stylelint.config.js
+* webpack.config.js
diff --git a/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md b/guides/development/extensions/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md
similarity index 100%
rename from guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md
rename to guides/development/extensions/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md
diff --git a/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md b/guides/development/extensions/plugins/administration/advanced-configuration/add-shortcuts.md
similarity index 100%
rename from guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md
rename to guides/development/extensions/plugins/administration/advanced-configuration/add-shortcuts.md
diff --git a/guides/plugins/plugins/administration/advanced-configuration/extending-webpack.md b/guides/development/extensions/plugins/administration/advanced-configuration/extending-webpack.md
similarity index 100%
rename from guides/plugins/plugins/administration/advanced-configuration/extending-webpack.md
rename to guides/development/extensions/plugins/administration/advanced-configuration/extending-webpack.md
diff --git a/guides/development/extensions/plugins/administration/advanced-configuration/index.md b/guides/development/extensions/plugins/administration/advanced-configuration/index.md
new file mode 100644
index 0000000000..c596acacda
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/advanced-configuration/index.md
@@ -0,0 +1,16 @@
+---
+nav:
+ title: Advanced Configuration
+ position: 50
+---
+
+# Advanced Configuration
+
+This section covers advanced Administration and build-related customizations for plugins. Use these guides to extend or override core behavior in a more advanced way:
+
+*
+*
+*
+*
+
+These topics go beyond basic plugin setup and require familiarity with the Administration architecture and component overriding.
diff --git a/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md b/guides/development/extensions/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md
similarity index 97%
rename from guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md
rename to guides/development/extensions/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md
index 3a6453001e..ec09f0c1a9 100644
--- a/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md
+++ b/guides/development/extensions/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md
@@ -1,3 +1,10 @@
+---
+nav:
+ title: Modify Dynamic Product Groups Blacklist
+ position: 140
+
+---
+
# Modify dynamic product groups blacklist
## Overview
diff --git a/guides/plugins/plugins/administration/data-handling-processing/handling-media.md b/guides/development/extensions/plugins/administration/data-handling-processing/handling-media.md
similarity index 100%
rename from guides/plugins/plugins/administration/data-handling-processing/handling-media.md
rename to guides/development/extensions/plugins/administration/data-handling-processing/handling-media.md
diff --git a/guides/development/extensions/plugins/administration/data-handling-processing/index.md b/guides/development/extensions/plugins/administration/data-handling-processing/index.md
new file mode 100644
index 0000000000..f2171a5225
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/data-handling-processing/index.md
@@ -0,0 +1,19 @@
+---
+nav:
+ title: Data Handling and Processing
+ position: 10
+---
+
+# Data Handling and Processing
+
+These guides cover how plugins work with data in the Administration and Storefront.
+
+They cover how to manipulate, display, and extend data in the Administration, including working with repositories, criteria, associations, custom fields, media, and related UI components.
+
+*
+*
+*
+*
+*
+*
+*
diff --git a/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md b/guides/development/extensions/plugins/administration/data-handling-processing/search-custom-data.md
similarity index 100%
rename from guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md
rename to guides/development/extensions/plugins/administration/data-handling-processing/search-custom-data.md
diff --git a/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md b/guides/development/extensions/plugins/administration/data-handling-processing/the-shopware-object.md
similarity index 100%
rename from guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md
rename to guides/development/extensions/plugins/administration/data-handling-processing/the-shopware-object.md
diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md b/guides/development/extensions/plugins/administration/data-handling-processing/using-custom-fields.md
similarity index 100%
rename from guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md
rename to guides/development/extensions/plugins/administration/data-handling-processing/using-custom-fields.md
diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md b/guides/development/extensions/plugins/administration/data-handling-processing/using-data-handling.md
similarity index 100%
rename from guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md
rename to guides/development/extensions/plugins/administration/data-handling-processing/using-data-handling.md
diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md b/guides/development/extensions/plugins/administration/data-handling-processing/using-the-data-grid-component.md
similarity index 100%
rename from guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md
rename to guides/development/extensions/plugins/administration/data-handling-processing/using-the-data-grid-component.md
diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md b/guides/development/extensions/plugins/administration/data-handling-processing/using-vuex-state.md
similarity index 100%
rename from guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md
rename to guides/development/extensions/plugins/administration/data-handling-processing/using-vuex-state.md
diff --git a/guides/development/extensions/plugins/administration/index.md b/guides/development/extensions/plugins/administration/index.md
new file mode 100644
index 0000000000..fbca3c97b4
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/index.md
@@ -0,0 +1,39 @@
+---
+nav:
+ title: Administration
+ position: 60
+
+---
+
+# Administration
+
+The Administration allows you to customize and extend the functionality of Shopware's backend interface. You can add modules, routes, components, services, permissions, and UI logic.
+
+Typical use cases include:
+
+* Adding a custom module
+* Registering routes and navigation entries
+* Creating Vue components
+* Working with repositories and API data
+* Handling permissions (ACL)
+* Injecting services
+* Customizing templates and styling
+
+This section follows a practical development workflow. Start with registering a module and route, then build your components, connect data, and refine permissions and UI behavior.
+
+## Developer workflow
+
+When extending the Administration inside a plugin, follow this sequence:
+
+1. [Add a custom module](module-component-management/add-custom-module.md) and [menu entry](routing-navigation/add-menu-entry.md)
+2. [Add custom routes](routing-navigation/add-custom-route.md)
+3. [Add custom components](module-component-management/add-custom-component.md) and [use base components](module-component-management/using-base-components.md)
+4. Connect [data](data-handling-processing/using-data-handling.md) (repositories or [API requests](services-utilities/making-api-requests.md))
+5. Handle permissions and [add ACL rules](permissions-error-handling/add-acl-rules.md)
+6. [Inject services](services-utilities/injecting-services.md) and [extend services](services-utilities/extending-services.md)
+7. [Customize templates](templates-styling/writing-templates.md) and [add custom styles](templates-styling/add-custom-styles.md)
+8. Manage state using [Vuex](data-handling-processing/using-vuex-state.md) or [Pinia](system-updates/pinia.md)
+
+Advanced topics such as [mixins and directives](mixins-directives/using-mixins.md) or [extending webpack](advanced-configuration/extending-webpack.md) are covered separately.
+
+Let’s start by [adding a custom module](module-component-management/add-custom-module.md).
diff --git a/guides/plugins/plugins/administration/mixins-directives/add-mixins.md b/guides/development/extensions/plugins/administration/mixins-directives/add-mixins.md
similarity index 100%
rename from guides/plugins/plugins/administration/mixins-directives/add-mixins.md
rename to guides/development/extensions/plugins/administration/mixins-directives/add-mixins.md
diff --git a/guides/plugins/plugins/administration/mixins-directives/adding-directives.md b/guides/development/extensions/plugins/administration/mixins-directives/adding-directives.md
similarity index 100%
rename from guides/plugins/plugins/administration/mixins-directives/adding-directives.md
rename to guides/development/extensions/plugins/administration/mixins-directives/adding-directives.md
diff --git a/guides/development/extensions/plugins/administration/mixins-directives/index.md b/guides/development/extensions/plugins/administration/mixins-directives/index.md
new file mode 100644
index 0000000000..c98bf9cfd7
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/mixins-directives/index.md
@@ -0,0 +1,15 @@
+---
+nav:
+ title: Mixins and Directives
+ position: 70
+---
+
+# Mixins and Directives
+
+Mixins and directives allow you to extend and reuse logic within the Shopware Administration. Use mixins to share behavior across multiple components, and directives to add custom DOM behavior.
+
+*
+*
+*
+
+These guides focus on extending the Administration using Vue-based patterns supported by Shopware.
diff --git a/guides/plugins/plugins/administration/mixins-directives/using-mixins.md b/guides/development/extensions/plugins/administration/mixins-directives/using-mixins.md
similarity index 100%
rename from guides/plugins/plugins/administration/mixins-directives/using-mixins.md
rename to guides/development/extensions/plugins/administration/mixins-directives/using-mixins.md
diff --git a/guides/plugins/plugins/administration/module-component-management/add-custom-component.md b/guides/development/extensions/plugins/administration/modules-components/add-custom-component.md
similarity index 100%
rename from guides/plugins/plugins/administration/module-component-management/add-custom-component.md
rename to guides/development/extensions/plugins/administration/modules-components/add-custom-component.md
diff --git a/guides/plugins/plugins/administration/module-component-management/add-custom-field.md b/guides/development/extensions/plugins/administration/modules-components/add-custom-field.md
similarity index 100%
rename from guides/plugins/plugins/administration/module-component-management/add-custom-field.md
rename to guides/development/extensions/plugins/administration/modules-components/add-custom-field.md
diff --git a/guides/plugins/plugins/administration/module-component-management/add-custom-module.md b/guides/development/extensions/plugins/administration/modules-components/add-custom-module.md
similarity index 100%
rename from guides/plugins/plugins/administration/module-component-management/add-custom-module.md
rename to guides/development/extensions/plugins/administration/modules-components/add-custom-module.md
diff --git a/guides/plugins/plugins/administration/module-component-management/customizing-components.md b/guides/development/extensions/plugins/administration/modules-components/customizing-components.md
similarity index 100%
rename from guides/plugins/plugins/administration/module-component-management/customizing-components.md
rename to guides/development/extensions/plugins/administration/modules-components/customizing-components.md
diff --git a/guides/plugins/plugins/administration/module-component-management/customizing-modules.md b/guides/development/extensions/plugins/administration/modules-components/customizing-modules.md
similarity index 100%
rename from guides/plugins/plugins/administration/module-component-management/customizing-modules.md
rename to guides/development/extensions/plugins/administration/modules-components/customizing-modules.md
diff --git a/guides/development/extensions/plugins/administration/modules-components/index.md b/guides/development/extensions/plugins/administration/modules-components/index.md
new file mode 100644
index 0000000000..2edbc85908
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/modules-components/index.md
@@ -0,0 +1,21 @@
+---
+nav:
+ title: Modules and Components
+ position: 80
+---
+
+# Modules and Components
+
+This guide covers how to create, extend, and customize Administration modules and Vue components. Use them to:
+
+* Create custom modules and routes
+* Register and build custom components
+* Override or extend existing components
+* Work with base components and input fields
+
+*
+*
+*
+*
+*
+*
diff --git a/guides/plugins/plugins/administration/module-component-management/using-base-components.md b/guides/development/extensions/plugins/administration/modules-components/using-base-components.md
similarity index 100%
rename from guides/plugins/plugins/administration/module-component-management/using-base-components.md
rename to guides/development/extensions/plugins/administration/modules-components/using-base-components.md
diff --git a/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md b/guides/development/extensions/plugins/administration/permissions-error-handling/add-acl-rules.md
similarity index 100%
rename from guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md
rename to guides/development/extensions/plugins/administration/permissions-error-handling/add-acl-rules.md
diff --git a/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md b/guides/development/extensions/plugins/administration/permissions-error-handling/add-error-handling.md
similarity index 100%
rename from guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md
rename to guides/development/extensions/plugins/administration/permissions-error-handling/add-error-handling.md
diff --git a/guides/development/extensions/plugins/administration/permissions-error-handling/index.md b/guides/development/extensions/plugins/administration/permissions-error-handling/index.md
new file mode 100644
index 0000000000..bdaf07c839
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/permissions-error-handling/index.md
@@ -0,0 +1,17 @@
+---
+nav:
+ title: Permissions and Error Handling
+ position: 90
+---
+
+# Permissions and Error Handling
+
+These guides cover access control and error management in the Shopware Administration, to ensure plugins integrate securely and provides proper feedback to users. Use them to:
+
+* Define and register custom ACL privileges
+* Protect routes, menu entries, and shortcuts
+* Handle API validation errors in components
+* Surface and map errors in forms and pages
+
+*
+*
diff --git a/resources/references/administration-reference/directives.md b/guides/development/extensions/plugins/administration/reference/directives.md
similarity index 100%
rename from resources/references/administration-reference/directives.md
rename to guides/development/extensions/plugins/administration/reference/directives.md
diff --git a/guides/development/extensions/plugins/administration/reference/index.md b/guides/development/extensions/plugins/administration/reference/index.md
new file mode 100644
index 0000000000..956568f770
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/reference/index.md
@@ -0,0 +1,22 @@
+---
+nav:
+ title: Administration Reference
+ position: 50
+
+---
+
+# Administration Reference
+
+Plugins extend the Administration by integrating directly into the Vue-based admin framework. Use these guides when building custom admin modules, components, or extending existing ones.
+
+## Core Concepts
+
+* [Utils](utils): Global utility functions available on the `Shopware` object.
+* [Mixins](mixins): Shared Vue mixins used across the Administration.
+* [Directives](directives): Globally registered Vue directives.
+
+Use these guides to:
+
+* Reuse core functionality instead of implementing it again
+* Follow Administration extension conventions
+* Build extensions that integrate cleanly into the Admin UI
diff --git a/resources/references/administration-reference/mixins.md b/guides/development/extensions/plugins/administration/reference/mixins.md
similarity index 100%
rename from resources/references/administration-reference/mixins.md
rename to guides/development/extensions/plugins/administration/reference/mixins.md
diff --git a/resources/references/administration-reference/utils.md b/guides/development/extensions/plugins/administration/reference/utils.md
similarity index 100%
rename from resources/references/administration-reference/utils.md
rename to guides/development/extensions/plugins/administration/reference/utils.md
diff --git a/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md b/guides/development/extensions/plugins/administration/routing-navigation/add-custom-route.md
similarity index 100%
rename from guides/plugins/plugins/administration/routing-navigation/add-custom-route.md
rename to guides/development/extensions/plugins/administration/routing-navigation/add-custom-route.md
diff --git a/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md b/guides/development/extensions/plugins/administration/routing-navigation/add-menu-entry.md
similarity index 100%
rename from guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md
rename to guides/development/extensions/plugins/administration/routing-navigation/add-menu-entry.md
diff --git a/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md b/guides/development/extensions/plugins/administration/routing-navigation/add-new-tab.md
similarity index 100%
rename from guides/plugins/plugins/administration/routing-navigation/add-new-tab.md
rename to guides/development/extensions/plugins/administration/routing-navigation/add-new-tab.md
diff --git a/guides/development/extensions/plugins/administration/routing-navigation/index.md b/guides/development/extensions/plugins/administration/routing-navigation/index.md
new file mode 100644
index 0000000000..0b4f6545b0
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/routing-navigation/index.md
@@ -0,0 +1,14 @@
+---
+nav:
+ title: Routing and Navigation
+ position: 30
+---
+
+# Routing and Navigation
+
+These guides help with adding and managing Administration routes, menu entries, and tabs.
+
+*
+*
+*
+*
diff --git a/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md b/guides/development/extensions/plugins/administration/routing-navigation/overriding-routes.md
similarity index 100%
rename from guides/plugins/plugins/administration/routing-navigation/overriding-routes.md
rename to guides/development/extensions/plugins/administration/routing-navigation/overriding-routes.md
diff --git a/guides/plugins/plugins/administration/services-utilities/add-custom-service.md b/guides/development/extensions/plugins/administration/services-utilities/add-custom-service.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/add-custom-service.md
rename to guides/development/extensions/plugins/administration/services-utilities/add-custom-service.md
diff --git a/guides/plugins/plugins/administration/services-utilities/add-filter.md b/guides/development/extensions/plugins/administration/services-utilities/add-filter.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/add-filter.md
rename to guides/development/extensions/plugins/administration/services-utilities/add-filter.md
diff --git a/guides/plugins/plugins/administration/services-utilities/extending-services.md b/guides/development/extensions/plugins/administration/services-utilities/extending-services.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/extending-services.md
rename to guides/development/extensions/plugins/administration/services-utilities/extending-services.md
diff --git a/guides/development/extensions/plugins/administration/services-utilities/index.md b/guides/development/extensions/plugins/administration/services-utilities/index.md
new file mode 100644
index 0000000000..c542775c21
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/services-utilities/index.md
@@ -0,0 +1,25 @@
+---
+nav:
+ title: Services and Utilities
+ position: 100
+---
+
+# Services and Utilities
+
+These guides covers how to create, extend, and use services and utility helpers in the Shopware Administration. Use them to:
+
+* Structure reusable logic and integrate cleanly with the Administration’s service container.
+* Register and inject custom services
+* Extend or decorate existing services
+* Make API requests from the Administration
+* Create and use filters
+* Work with utility helpers and data validation
+
+*
+*
+*
+*
+*
+*
+*
+*
diff --git a/guides/plugins/plugins/administration/services-utilities/injecting-services.md b/guides/development/extensions/plugins/administration/services-utilities/injecting-services.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/injecting-services.md
rename to guides/development/extensions/plugins/administration/services-utilities/injecting-services.md
diff --git a/guides/plugins/plugins/administration/services-utilities/making-api-requests.md b/guides/development/extensions/plugins/administration/services-utilities/making-api-requests.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/making-api-requests.md
rename to guides/development/extensions/plugins/administration/services-utilities/making-api-requests.md
diff --git a/guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md b/guides/development/extensions/plugins/administration/services-utilities/the-sanitizer-helper.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md
rename to guides/development/extensions/plugins/administration/services-utilities/the-sanitizer-helper.md
diff --git a/guides/plugins/plugins/administration/services-utilities/using-filter.md b/guides/development/extensions/plugins/administration/services-utilities/using-filter.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/using-filter.md
rename to guides/development/extensions/plugins/administration/services-utilities/using-filter.md
diff --git a/guides/plugins/plugins/administration/services-utilities/using-utils.md b/guides/development/extensions/plugins/administration/services-utilities/using-utils.md
similarity index 100%
rename from guides/plugins/plugins/administration/services-utilities/using-utils.md
rename to guides/development/extensions/plugins/administration/services-utilities/using-utils.md
diff --git a/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md b/guides/development/extensions/plugins/administration/templates-styling/add-custom-styles.md
similarity index 100%
rename from guides/plugins/plugins/administration/templates-styling/add-custom-styles.md
rename to guides/development/extensions/plugins/administration/templates-styling/add-custom-styles.md
diff --git a/guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md b/guides/development/extensions/plugins/administration/templates-styling/adding-responsive-behavior.md
similarity index 96%
rename from guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md
rename to guides/development/extensions/plugins/administration/templates-styling/adding-responsive-behavior.md
index 3e54bc7031..6e3f720562 100644
--- a/guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md
+++ b/guides/development/extensions/plugins/administration/templates-styling/adding-responsive-behavior.md
@@ -1,11 +1,11 @@
---
nav:
- title: Adding responsive behavior
- position: 260
+ title: Adding Responsive Behavior
+ position: 80
---
-# Adding responsive behavior
+# Adding Responsive Behavior
## Overview
diff --git a/guides/plugins/plugins/administration/templates-styling/adding-snippets.md b/guides/development/extensions/plugins/administration/templates-styling/adding-snippets.md
similarity index 100%
rename from guides/plugins/plugins/administration/templates-styling/adding-snippets.md
rename to guides/development/extensions/plugins/administration/templates-styling/adding-snippets.md
diff --git a/guides/development/extensions/plugins/administration/templates-styling/index.md b/guides/development/extensions/plugins/administration/templates-styling/index.md
new file mode 100644
index 0000000000..bd4981d505
--- /dev/null
+++ b/guides/development/extensions/plugins/administration/templates-styling/index.md
@@ -0,0 +1,24 @@
+---
+nav:
+ title: Templates and Styling
+ position: 40
+---
+
+# Templates and Styling
+
+These guides explain how to build and customize Administration templates, styles, assets, and translations in plugins. They focus on the visual and structural aspects of Administration extensions.
+
+Use them to:
+
+* Write Twig/Vue-based templates
+* Add custom SCSS styles
+* Register and use snippet translations
+* Work with static assets in the Administration
+
+## Topics
+
+*
+*
+*
+*
+*
\ No newline at end of file
diff --git a/guides/plugins/plugins/administration/templates-styling/using-assets.md b/guides/development/extensions/plugins/administration/templates-styling/using-assets.md
similarity index 100%
rename from guides/plugins/plugins/administration/templates-styling/using-assets.md
rename to guides/development/extensions/plugins/administration/templates-styling/using-assets.md
diff --git a/guides/plugins/plugins/administration/templates-styling/writing-templates.md b/guides/development/extensions/plugins/administration/templates-styling/writing-templates.md
similarity index 100%
rename from guides/plugins/plugins/administration/templates-styling/writing-templates.md
rename to guides/development/extensions/plugins/administration/templates-styling/writing-templates.md
diff --git a/guides/plugins/plugins/administration/system-updates/vue-native.md b/guides/development/extensions/plugins/administration/vue-native.md
similarity index 92%
rename from guides/plugins/plugins/administration/system-updates/vue-native.md
rename to guides/development/extensions/plugins/administration/vue-native.md
index 99f2594b45..fc0d13b472 100644
--- a/guides/plugins/plugins/administration/system-updates/vue-native.md
+++ b/guides/development/extensions/plugins/administration/vue-native.md
@@ -16,7 +16,6 @@ This document outlines the reasons for this change and provides an overview of o
## Current status
-To better understand the changes described in this article, let's recap the current status.
The Shopware 6 Administration is built around Vue.js with several custom systems on top to allow for extensions.
### Custom component registration
@@ -37,7 +36,7 @@ Shopware.Component.register('sw-component', {
{% endblock %}
```
-## Why Go Native?
+## Why go native?
Our transition to a more native Vue.js approach is driven by several key factors:
@@ -56,19 +55,22 @@ Our transition to a more native Vue.js approach is driven by several key factors
### 1. Moving from Options API to Composition API
-#### Why Make This Change?
+#### Why make this change?
We aim to better align with Vue's ecosystem, to minimize the amount of specifications new Developers need to learn.
+
The Composition API has become the new standard for Vue's documentation and projects all over Github.
+
Renowned libraries like `vue-i18n` are dropping support of the Options API, as seen in their [migration guide](https://vue-i18n.intlify.dev/guide/migration/vue3#summary), and we expect similar transitions from other tools in the ecosystem.
This also aligns with Vue's best practices, as highlighted in the official [Composition API FAQ](https://vuejs.org/guide/extras/composition-api-faq.html#why-composition-api).
-#### What Will Change?
+#### What will change?
We will gradually transform our components from Options API to Composition API. Together with native blocks, this builds the foundation to use Single File Components (SFC).
+
The transformation will be stretched over multiple major versions to offer enough time for all of us to adapt. Take a look at the estimated timeline below.
-#### Upgrade Path
+#### Upgrade path
| Shopware Version | Options API | Composition API |
|:----------------:|---------------------------------|------------------------------|
@@ -78,21 +80,21 @@ The transformation will be stretched over multiple major versions to offer enoug
*Extensions still can register components using the Options API; overwriting Core components needs the Composition API.
-### 2. TwigJS to Native Blocks
+### 2. TwigJS to native blocks
-#### Why Make This Change?
+#### Why make this change?
Vue has no native support for blocks like in Twig.js. Vue has slots, but slots don't work like blocks.
-Recently, we accomplished the unthinkable and found a way to implement blocks with native Vue components.
-This will allow us to finally use SFC and keep the extendability of Twig.js.
-Lowering the learning curve, as the Twig.js syntax is especially unfamiliar to Vue developers.
+
+Implementing blocks with native Vue components allows using SFC and keeping the extendability of Twig.js. This lowers the learning curve, as the Twig.js syntax is especially unfamiliar to Vue developers.
+
Standard tooling like VSCode, ESLint, and Prettier will work out of the box.
-#### What Will Change?
+#### What will change?
We will gradually transform all component templates from external `*.html.twig` files with Twig.Js into `.vue` files using the native block implementation.
-#### Upgrade Path
+#### Upgrade path
| Shopware Version | Twig.Js | Native blocks |
|:----------------:|---------------------------------|------------------------------|
@@ -104,11 +106,11 @@ We will gradually transform all component templates from external `*.html.twig`
### 3. Vuex to Pinia
-#### Why Make This Change?
+#### Why make this change?
-Vuex has been the default State management for Vue 2. For Vue 3 Pinia took it's place.
+Vuex has been the default State management for Vue 2. For Vue 3 Pinia took its place.
-#### What Will Change?
+#### What will change?
We will move all core Vuex states to Pinia stores. The public API will change from `Shopware.State` to `Shopware.Store`.
@@ -127,7 +129,7 @@ Now let's take a look how core and extension components will evolve.
### Shopware 6.7
-First we start with the current status which is still compatible with Shopware 6.7.
+The current status is still compatible with Shopware 6.7.
#### Core component
@@ -290,7 +292,7 @@ Shopware.Component.register('your-crazy-ai-field', {
### Shopware 6.9
-The only difference for 6.9 is that you can no longer register new components via `Shopware.Component.register`.
+Registering new components via `Shopware.Component.register` will no longer be possible.
## FAQ
diff --git a/guides/development/extensions/plugins/architecture/cart-process.md b/guides/development/extensions/plugins/architecture/cart-process.md
new file mode 100644
index 0000000000..1c6aab500f
--- /dev/null
+++ b/guides/development/extensions/plugins/architecture/cart-process.md
@@ -0,0 +1,31 @@
+---
+nav:
+ title: Cart Extension Architecture
+ position: 30
+
+---
+
+# Cart Extension Architecture
+
+The cart is recalculated multiple times per request to resolve dependencies between line items. Custom extensions must follow strict performance and determinism rules.
+
+## Design principles
+
+* Cart processing is multi-pass and must remain deterministic.
+* Data loading must be separated from calculation to ensure stable performance.
+* Price logic must be centralized and reusable.
+
+## Extension guidelines
+
+* Use `CartDataCollector` to load external data once.
+* Use `CartProcessor` to modify calculated items.
+* Never perform database queries in `process()`.
+* Always use `PriceCalculator` classes for price adjustments.
+
+## Technical rules
+
+* `CartProcessorInterface::process()` must not execute queries, as it runs multiple times per request.
+* The `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface::collect()` method must check whether data was already loaded and append it to `CartDataCollection`. This is to avoid having to execute unnecessarily many queries on the database.
+* Line items must be created via a `LineItemFactoryHandler` class.
+* All price calculations must use the `Shopware\Core\Checkout\Cart\Price` calculators, which are stored inside the `Shopware\Core\Checkout\Cart\Price` class.
+* Cart-related functions must be mapped via corresponding Store API routes in the `Shopware\Core\Checkout\Cart\SalesChannel` namespace.
diff --git a/guides/development/extensions/plugins/architecture/context-rules-rule-systems.md b/guides/development/extensions/plugins/architecture/context-rules-rule-systems.md
new file mode 100644
index 0000000000..18f4005ce8
--- /dev/null
+++ b/guides/development/extensions/plugins/architecture/context-rules-rule-systems.md
@@ -0,0 +1,30 @@
+---
+nav:
+ title: Rule System Extension Architecture
+ position: 40
+
+---
+
+# Rule System Extension Architecture
+
+Rules are evaluated synchronously during request handling. They must be deterministic and performant. Custom rule implementations must operate only on data already available in the evaluation context.
+
+## Design Principles
+
+* Rule evaluation must not introduce database queries, as all rules are evaluated during a request cycle.
+* Rules must rely exclusively on the provided evaluation scope.
+* Rule execution must be predictable and free of side effects.
+
+## Extension Guidelines
+
+* Never execute database queries inside rule classes.
+* Use the provided rule scopes to access data.
+* Do not mutate state during rule evaluation.
+* Keep rule logic lightweight and computation-focused.
+
+## Technical requirements
+
+* Cart-related rules must support:
+ * the `\Shopware\Core\Checkout\Cart\Rule\CartRuleScope` class
+ * the `\Shopware\Core\Checkout\Cart\Rule\LineItemScope`class
+* Rules may only access data exposed through their respective scope classes.
diff --git a/guides/development/extensions/plugins/architecture/dependency-injection-dependency-handling.md b/guides/development/extensions/plugins/architecture/dependency-injection-dependency-handling.md
new file mode 100644
index 0000000000..0f358f9460
--- /dev/null
+++ b/guides/development/extensions/plugins/architecture/dependency-injection-dependency-handling.md
@@ -0,0 +1,45 @@
+---
+nav:
+ title: Dependency Injection & Dependency Handling
+ position: 50
+
+---
+
+# Dependency Injection and Dependency Handling
+
+Shopware separates responsibilities between domains (Core, Storefront, Administration).
+Plugins must respect these boundaries to ensure deterministic behavior, testability, and compatibility.
+
+## Domain separation
+
+The `Core` domain is framework-level logic. It must remain independent from HTTP state and presentation concerns.
+
+The `Storefront` domain handles HTTP requests, sessions, and customer interaction.
+
+## Core domain rules
+
+* The Core domain must never access the PHP session.
+* Core services must not rely on request state.
+* Business logic must remain stateless and deterministic.
+* Dependencies must be injected via the service container.
+
+There is only one PHP session per storefront request. Session handling must be implemented in the Storefront domain and never inside Core services.
+
+## Extension guidelines
+
+When extending Core functionality:
+
+* Inject dependencies via the constructor.
+* Avoid reading request data directly in Core classes.
+* Avoid session access inside services registered in Core.
+* Keep domain logic independent from HTTP concerns.
+* Use Store API routes or Storefront controllers to bridge between HTTP/session state and Core services.
+
+Violating domain boundaries can lead to:
+
+* Unpredictable behavior in background jobs
+* Broken CLI execution
+* Inconsistent cart or rule evaluation
+* Reduced testability
+
+Respecting these boundaries ensures stable, maintainable extensions.
diff --git a/guides/development/extensions/plugins/architecture/events.md b/guides/development/extensions/plugins/architecture/events.md
new file mode 100644
index 0000000000..f79260a76c
--- /dev/null
+++ b/guides/development/extensions/plugins/architecture/events.md
@@ -0,0 +1,32 @@
+---
+nav:
+ title: Event Extension Architecture
+ position: 70
+
+---
+
+# Event Extension Architecture
+
+Events provide extension points for loading additional data or reacting to system changes. They are designed for observation and enrichment, not for altering core control flow.
+
+## Design Principles
+
+* Events expose extension points without breaking encapsulation.
+* Events should not mutate core program flow.
+* Business logic replacement must use decoration, not events.
+* Events must remain predictable and side-effect aware.
+
+## Extension Guidelines
+
+* Use events to add data, not to override behavior.
+* Avoid heavy computation or database queries inside event subscribers.
+* Keep subscribers idempotent and deterministic.
+* Prefer decoration when you need to change logic execution.
+
+## Technical Requirements
+
+* Events must always implement the `\Shopware\Core\Framework\Event\ShopwareEvent` interface.
+* Sales channel events must implement these interfaces:
+ * `ShopwareSalesChannelEvent`
+ * `\Shopware\Core\Framework\Event\SalesChannelAware`
+* Events are intended for enrichment and extension, not for control-flow modification.
diff --git a/guides/development/extensions/plugins/architecture/index.md b/guides/development/extensions/plugins/architecture/index.md
new file mode 100644
index 0000000000..6994bb4adb
--- /dev/null
+++ b/guides/development/extensions/plugins/architecture/index.md
@@ -0,0 +1,22 @@
+---
+nav:
+ title: Plugin Architecture
+ position: 1
+
+---
+
+# Plugin Architecture
+
+This section defines the architectural rules and extension contracts for core subsystems.
+
+These documents describe how to safely extend Shopware without breaking determinism, performance, or system boundaries.
+
+## Subsystems
+
+* [Cart Extension Architecture](cart-process.md)
+* [Rule System Extension Architecture](context-rules-rule-systems.md)
+* [Page Loader Extension Architecture](pageloader.md)
+* [Event Extension Architecture](events.md)
+* [Dependency Injection and Dependency Handling](dependency-injection-dependency-handling.md)
+
+These guidelines are mandatory for plugin developers extending core functionality.
diff --git a/guides/development/extensions/plugins/architecture/pageloader.md b/guides/development/extensions/plugins/architecture/pageloader.md
new file mode 100644
index 0000000000..23e0fff690
--- /dev/null
+++ b/guides/development/extensions/plugins/architecture/pageloader.md
@@ -0,0 +1,36 @@
+---
+nav:
+ title: Page Loader Extension Architecture
+ position: 80
+
+---
+
+# Page Loader Extension Architecture
+
+Page loaders assemble all data required to render a storefront page. They centralize data fetching and guarantee consistent storefront behavior.
+
+## Design principles
+
+* Page loaders separate HTTP concerns from business logic.
+* Data must be fetched via Store API routes.
+* Page loaders must remain replaceable via decoration.
+* Pages must be fully constructed before rendering.
+
+## Extension guidelines
+
+* Divide page loaders by domains that represent different Storefront sections: e.g. products, account, checkout.
+* Provide an abstract base class for [decoration](../../references/adr/2020-11-25-decoration-pattern.md). The decoration pattern can be used to completely replace the page loader in a project.
+* Return a dedicated page object containing all required data.
+* Dispatch a corresponding `PageLoaded` event after loading. This event can be used to provide further data by third-party developers.
+* Never access repositories directly inside a page loader.
+* Use Store API routes for all data retrieval, to ensure that Store API can access all storefront functionalities.
+* Page objects must extend from the base `\Shopware\Storefront\Page\Page` class.
+
+## Why this matters
+
+Page loaders guarantee that:
+
+* Storefront rendering remains deterministic.
+* Data can be reused via the Store API.
+* Extensions can replace or decorate page behavior safely.
+* Rendering logic stays independent from database concerns.
diff --git a/guides/plugins/plugins/checkout/cart/add-cart-discounts.md b/guides/development/extensions/plugins/checkout/cart/add-cart-discounts.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/add-cart-discounts.md
rename to guides/development/extensions/plugins/checkout/cart/add-cart-discounts.md
diff --git a/guides/plugins/plugins/checkout/cart/add-cart-items.md b/guides/development/extensions/plugins/checkout/cart/add-cart-items.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/add-cart-items.md
rename to guides/development/extensions/plugins/checkout/cart/add-cart-items.md
diff --git a/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md b/guides/development/extensions/plugins/checkout/cart/add-cart-processor-collector.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md
rename to guides/development/extensions/plugins/checkout/cart/add-cart-processor-collector.md
diff --git a/guides/plugins/plugins/checkout/cart/add-cart-validator.md b/guides/development/extensions/plugins/checkout/cart/add-cart-validator.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/add-cart-validator.md
rename to guides/development/extensions/plugins/checkout/cart/add-cart-validator.md
diff --git a/guides/plugins/plugins/checkout/cart/change-price-of-item.md b/guides/development/extensions/plugins/checkout/cart/change-price-of-item.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/change-price-of-item.md
rename to guides/development/extensions/plugins/checkout/cart/change-price-of-item.md
diff --git a/guides/plugins/plugins/checkout/cart/customize-price-calculation.md b/guides/development/extensions/plugins/checkout/cart/customize-price-calculation.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/customize-price-calculation.md
rename to guides/development/extensions/plugins/checkout/cart/customize-price-calculation.md
diff --git a/guides/plugins/plugins/checkout/cart/index.md b/guides/development/extensions/plugins/checkout/cart/index.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/index.md
rename to guides/development/extensions/plugins/checkout/cart/index.md
diff --git a/guides/plugins/plugins/checkout/cart/tax-provider.md b/guides/development/extensions/plugins/checkout/cart/tax-provider.md
similarity index 100%
rename from guides/plugins/plugins/checkout/cart/tax-provider.md
rename to guides/development/extensions/plugins/checkout/cart/tax-provider.md
diff --git a/guides/plugins/plugins/checkout/document/add-custom-document-type.md b/guides/development/extensions/plugins/checkout/document/add-custom-document-type.md
similarity index 100%
rename from guides/plugins/plugins/checkout/document/add-custom-document-type.md
rename to guides/development/extensions/plugins/checkout/document/add-custom-document-type.md
diff --git a/guides/plugins/plugins/checkout/document/add-custom-document.md b/guides/development/extensions/plugins/checkout/document/add-custom-document.md
similarity index 100%
rename from guides/plugins/plugins/checkout/document/add-custom-document.md
rename to guides/development/extensions/plugins/checkout/document/add-custom-document.md
diff --git a/guides/plugins/plugins/checkout/document/index.md b/guides/development/extensions/plugins/checkout/document/index.md
similarity index 100%
rename from guides/plugins/plugins/checkout/document/index.md
rename to guides/development/extensions/plugins/checkout/document/index.md
diff --git a/guides/plugins/plugins/checkout/index.md b/guides/development/extensions/plugins/checkout/index.md
similarity index 100%
rename from guides/plugins/plugins/checkout/index.md
rename to guides/development/extensions/plugins/checkout/index.md
diff --git a/guides/plugins/plugins/checkout/order/index.md b/guides/development/extensions/plugins/checkout/order/index.md
similarity index 100%
rename from guides/plugins/plugins/checkout/order/index.md
rename to guides/development/extensions/plugins/checkout/order/index.md
diff --git a/guides/plugins/plugins/checkout/order/listen-to-order-changes.md b/guides/development/extensions/plugins/checkout/order/listen-to-order-changes.md
similarity index 100%
rename from guides/plugins/plugins/checkout/order/listen-to-order-changes.md
rename to guides/development/extensions/plugins/checkout/order/listen-to-order-changes.md
diff --git a/guides/plugins/plugins/checkout/order/using-the-state-machine.md b/guides/development/extensions/plugins/checkout/order/using-the-state-machine.md
similarity index 100%
rename from guides/plugins/plugins/checkout/order/using-the-state-machine.md
rename to guides/development/extensions/plugins/checkout/order/using-the-state-machine.md
diff --git a/guides/plugins/plugins/checkout/payment/add-payment-plugin.md b/guides/development/extensions/plugins/checkout/payment/add-payment-plugin.md
similarity index 100%
rename from guides/plugins/plugins/checkout/payment/add-payment-plugin.md
rename to guides/development/extensions/plugins/checkout/payment/add-payment-plugin.md
diff --git a/guides/plugins/plugins/checkout/payment/customize-payment-provider.md b/guides/development/extensions/plugins/checkout/payment/customize-payment-provider.md
similarity index 100%
rename from guides/plugins/plugins/checkout/payment/customize-payment-provider.md
rename to guides/development/extensions/plugins/checkout/payment/customize-payment-provider.md
diff --git a/guides/plugins/plugins/checkout/payment/index.md b/guides/development/extensions/plugins/checkout/payment/index.md
similarity index 100%
rename from guides/plugins/plugins/checkout/payment/index.md
rename to guides/development/extensions/plugins/checkout/payment/index.md
diff --git a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md b/guides/development/extensions/plugins/configuration/add-plugin-configuration.md
similarity index 93%
rename from guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md
rename to guides/development/extensions/plugins/configuration/add-plugin-configuration.md
index 9839d5cdc5..d106fc1cb3 100644
--- a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md
+++ b/guides/development/extensions/plugins/configuration/add-plugin-configuration.md
@@ -7,24 +7,19 @@ nav:
# Add Plugin Configuration
-The `Shopware plugin system` provides you with the option to create a configuration page for your plugin without any knowledge of templating or the `Shopware Administration`.
-
-## Prerequisites
-
-To build your own configuration page for your plugin, you first need a plugin as base.
-Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).
+Shopware allows you to define a configuration page for your plugin using a `config.xml` file. No custom Administration module or knowledge of templating required.
## Create your plugin configuration
::: info
-This video is part of the online training ["Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma) available on Shopware Academy for **free**.
+This video is part of the free Shopware Academy online training ["Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::
-All you need to do is create a `config.xml` file inside a `Resources/config` directory in your plugin root.
-The content of the `config.xml` will be dynamically rendered in the Administration.
-Below you'll find an example structure:
+Create `src/Resources/config/config.xml` inside your plugin. The content of the `config.xml` will be dynamically rendered in the Administration.
+
+An example structure:
```text
└── plugins
@@ -45,7 +40,7 @@ As you now know how to create configurations, you can start to fill it with life
The `config.xml` follows a simple syntax.
You can organize the content in `` elements.
-Every `config.xml` must contain a minimum of one `` element and each `` must contain one `` and at least one `<input-field>`.
+Each `config.xml` must contain at least one `<card>` with a `<title>` and at least one `<input-field>`.
See the minimum `config.xml` below:
```xml
@@ -92,6 +87,9 @@ Your `<input-field>` can be of different types, this is managed via the `type` a
Unless defined otherwise, your `<input-field>` will be a text field.
Below you'll find a list of all available `<input-field type="?">`.
+<details>
+<summary>Supported input field types</summary>
+
| Type | Configuration settings | Renders | Default value example |
|:--------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------|:----------------------------------------|
| text | [copyable](add-plugin-configuration#copyable), [placeholder](add-plugin-configuration#label-placeholder-and-help-text), [length](add-plugin-configuration#text-length-restrictions) | Text field | Some text |
@@ -110,6 +108,8 @@ Below you'll find a list of all available `<input-field type="?">`.
| single-select | [options](add-plugin-configuration#options), [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | Single-Select box | option_id |
| multi-select | [options](add-plugin-configuration#options), [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | Multi-Select box | [option_id1, option_id2] |
+</details>
+
### Input field settings
These settings are used to configure your `<input-field>`.
@@ -220,7 +220,7 @@ Below, you'll find an example of how to use this setting.
</input-field>
```
-#### options
+#### Options
You can use `<options>` to add settings to a `<input-field>` of the types `single-select` and `multi-select`.
Each `<option>` represents one setting you can select.
@@ -251,6 +251,9 @@ As you can see above, `<name>` elements are translatable via the `lang` attribut
### Advanced custom input fields
+<details>
+<summary>Advanced configuration components</summary>
+
For more complex and advanced configurations it is possible to declare a `<component name="componentName">` element.
This element can render many admin components.
It is also possible to render your own admin component which you could deliver with your plugin.
@@ -389,14 +392,16 @@ Now all that's left to do is to present you a working example `config.xml` and s
</config>
```
+</details>
+
## Add values to your configuration
After adding your input fields to the `config.xml`, you can add values to your configuration.
-To do so, navigate from the sidebar to the `Extensions` > `My extensions` > `Apps` tab and click `Configure`.
+To do so, navigate from the sidebar to the `Extensions` > `My extensions` > `Plugins` tab and click `Configure`.
Now you can see the `Configuration` tab and fill in the values for your input fields.
## Next steps
-Now you've added your own plugin configuration.
-But how do you actually read which configurations the shop owner used?
-This will be covered in our guide about [Using the plugin configuration](use-plugin-configuration).
+Now that your configuration is defined:
+
+* Use it in your plugin logic: [Using the plugin configuration](use-plugin-configuration)
diff --git a/guides/development/extensions/plugins/configuration/index.md b/guides/development/extensions/plugins/configuration/index.md
new file mode 100644
index 0000000000..5ce6e261a5
--- /dev/null
+++ b/guides/development/extensions/plugins/configuration/index.md
@@ -0,0 +1,22 @@
+---
+nav:
+ title: Configuration
+ position: 30
+---
+
+# Plugin Configuration
+
+Plugins can provide configurable settings that are managed via the Administration.
+
+This section explains:
+
+* How to define a configuration page using `config.xml`
+* How to read and use configuration values in PHP
+* How to access configuration in Administration and Storefront code
+
+Configuration is stored via the `SystemConfigService` and can be scoped per sales channel if required.
+
+## Guides
+
+* <PageRef page="./add-plugin-configuration" />
+* <PageRef page="./use-plugin-configuration" />
diff --git a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md b/guides/development/extensions/plugins/configuration/use-plugin-configuration.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md
rename to guides/development/extensions/plugins/configuration/use-plugin-configuration.md
diff --git a/guides/development/extensions/plugins/content/cms/add-cms-block.md b/guides/development/extensions/plugins/content/cms/add-cms-block.md
new file mode 100644
index 0000000000..4759e0dd27
--- /dev/null
+++ b/guides/development/extensions/plugins/content/cms/add-cms-block.md
@@ -0,0 +1,228 @@
+---
+nav:
+ title: Add CMS block
+ position: 10
+---
+
+# Add CMS Blocks
+
+## What is a Block?
+
+A CMS block in Shopware is a fundamental structural component of the Shopping Experience (CMS) system. Understanding the hierarchy helps clarify what blocks are:
+
+### CMS Hierarchy
+
+* Page - The top-level container (e.g., category page, shop page, product page)
+* Section - Horizontal segments within a page (can be single-column or two-column with sidebar)
+* **Block - Units that usually span an entire row with custom layout and styling**
+* **Slots - A named container inside a block. Each slot represents a designated area that can hold exactly one CMS element**
+* Elements - The actual content primitives (text, image, video, product listing, etc.) placed inside slots
+
+A block represents a reusable layout unit that defines how elements are arranged in slots. For example, Shopware's built-in `image-text` block displays an image on the left and text on the right. Blocks are clustered into categories like Text, Images, Commerce, and Video for organizational purposes in the administration interface.
+
+**Key concept**: Blocks define the structure (layout and slots), while elements provide the actual content. This separation allows the same block to display different types of content in its slots.
+
+> **Learn more**: For a deeper understanding of the CMS architecture, see the [Shopping Experience fundamental guide](https://developer.shopware.com/docs/concepts/commerce/content/shopping-experiences-cms.html).
+
+## Where to Find Blocks
+
+Blocks are located in the Shopping Experience module in the Shopware Administration:
+
+* Navigate to Content → Shopping Experience
+* Create a new layout or edit an existing one
+* In the layout designer, you'll see a sidebar with available blocks organized by category:
+ * Text - Text-only blocks
+ * Images - Image-only blocks
+ * Text & Images - Combined text and image blocks
+ * Commerce - Product sliders, listings, etc.
+ * Video - YouTube and Vimeo video blocks
+ * Form - Contact and newsletter forms
+ * Sidebar - Category navigation and listing filters
+
+Drag and drop blocks from the sidebar into your layout sections.
+
+You can find related block code here:
+
+* Administration: `src/Administration/Resources/app/administration/src/module/sw-cms/blocks/`
+* Storefront: `src/Storefront/Resources/views/storefront/block/`
+* Core: `\Shopware\Core\Content\Cms\SalesChannel\SalesChannelCmsPageLoader::load`
+
+## How to Create a Block in the Administration
+
+### Directory Structure
+
+We recommend this structure for CMS blocks:
+
+```TEXT
+<plugin root>/src/Resources/app/administration/src/
+├── main.js
+└── module/
+ └── sw-cms/
+ └── blocks/
+ └── text-image/ (category)
+ └── image-text-reversed/ (block name)
+ ├── index.js
+ ├── component/
+ │ ├── index.js
+ │ ├── cms-block-image-text-reversed.html.twig
+ │ └── cms-block-image-text-reversed.scss
+ └── preview/
+ ├── index.js
+ ├── cms-block-preview-image-text-reversed.html.twig
+ └── cms-block-preview-image-text-reversed.scss
+```
+
+### Step 1: Import Your Block in main.js
+
+```JS
+// <plugin root>/src/Resources/app/administration/src/main.js
+import './module/sw-cms/blocks/text-image/image-text-reversed';
+```
+
+### Step 2: Register the Block
+
+```JS
+// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/image-text-reversed/index.js
+import './component';
+import './preview';
+
+Shopware.Service('cmsService').registerCmsBlock({
+ name: 'image-text-reversed',
+ category: 'text-image',
+ label: 'cms.blocks.imageTextReversed.label',
+ component: 'cms-block-image-text-reversed',
+ previewComponent: 'cms-block-preview-image-text-reversed',
+ defaultConfig: {
+ marginBottom: '20px',
+ marginTop: '20px',
+ marginLeft: '20px',
+ marginRight: '20px',
+ sizingMode: 'boxed',
+ },
+ slots: {
+ left: 'text',
+ right: 'image',
+ },
+});
+```
+
+| Property | Description |
+|------------------|----------------------------------------------------------------------------------------------|
+| `name` | Technical name of your block |
+| `category` | Which category it appears under (`text`, `image`, `text-image`, `commerce`, `form`, `video`, `sidebar`) |
+| `label` | Display name in the UI |
+| `component` | Vue component for rendering the block in the designer |
+| `previewComponent` | Vue component for the block thumbnail preview |
+| `defaultConfig` | Default styling values |
+| `slots` | Defines which element types go in which slots (key = slot name, value = element type) |
+
+### Step 3: Create the Block Component
+
+It's important to include all slots you defined in the block configuration (Step 2). These are used for configuring elements in the administration interface.
+
+```JS
+// image-text-reversed/component/index.js
+Shopware.Component.register('cms-block-image-text-reversed', {
+ template: `<div style="display: flex; gap: 16px;">
+ <slot name="left" />
+ <slot name="right" />
+ </div>`,
+});
+```
+
+### Step 4: Create the Preview Component
+
+The preview is shown as a thumbnail when selecting a block from the editor sidebar. You could also display a static image of your final Storefront block here.
+
+```JS
+// image-text-reversed/preview/index.js
+Shopware.Component.register('cms-block-preview-image-text-reversed', {
+ template: `<div style="display: flex; gap: 16px;">
+ <h2>Lorem ipsum dolor sit amet</h2>
+ <img :src="assetFilter('/administration/administration/static/img/cms/preview_mountain_small.jpg')" />
+ </div>`,
+ computed: {
+ assetFilter() {
+ return Shopware.Filter.getByName('asset');
+ },
+ },
+});
+```
+
+After this, the block preview should appear in the Shopping Experience block sidebar under the "Text & Images" category and can be added to a layout.
+
+## How to Create a Block in the Storefront
+
+The Storefront template defines how your element appears on the actual storefront. It is expected to be located in the directory `src/Resources/views/storefront/block`. In there, a twig template file has to follow this naming convention:
+
+* **Prefix**: `cms-block-`
+* **Technical name**: `image-text-reversed` (The `name` property in Step 2)
+* **Extension**: `.html.twig`
+
+**Shopware is expecting the prefix as part of the full filename in `src/Storefront/Resources/views/storefront/section/cms-section-block-container.html.twig`.**
+
+Full example: `cms-block-image-text-reversed.html.twig`
+
+### Basic Template
+
+You can create your own blocks or extend and reuse existing ones. Don't forget to clear the Storefront cache after adding new templates.
+
+```TWIG
+{# <plugin root>/src/Resources/views/storefront/block/cms-block-image-text-reversed.html.twig #}
+<div class="col-md-6">
+ {% set element = block.slots.getSlot('left') %}
+
+ {% sw_include '@Storefront/storefront/element/cms-element-' ~ element.type ~ '.html.twig' with {
+ 'element': element
+ } %}
+</div>
+
+<div class="col-md-6">
+ {% set element = block.slots.getSlot('right') %}
+
+ {% sw_include '@Storefront/storefront/element/cms-element-' ~ element.type ~ '.html.twig' with {
+ 'element': element
+ } %}
+</div>
+```
+
+The `block` is automatically passed to the template and contains meta data and configuration values. See the `CmsBlockDefinition.php` for a full overview.
+
+### How to Render Slots
+
+Slots contain elements that need to be rendered. Here are the key methods:
+
+#### 1. Get a Slot by Name
+
+```TWIG
+{% set leftSlot = block.slots.getSlot('left') %}
+```
+
+#### 2. Render an Element
+
+Use `sw_include` to dynamically include the correct element template:
+
+```TWIG
+{% sw_include "@Storefront/storefront/element/cms-element-" ~ leftSlot.type ~ ".html.twig" with {
+ 'element': leftSlot
+} %}
+```
+
+This dynamically builds the template path based on the element type. For example:
+
+* If `leftSlot.type` is text, it renders cms-element-text.html.twig
+* If `leftSlot.type` is image, it renders cms-element-image.html.twig
+
+#### 3. Loop Through All Slots
+
+```TWIG
+{% for slotName, slot in block.slots %}
+ {% sw_include "@Storefront/storefront/element/cms-element-" ~ slot.type ~ ".html.twig" with {
+ 'element': slot
+ } %}
+{% endfor %}
+```
+
+## Next steps
+
+Now you've got your very own CMS block running, what about a custom CMS element? Head over to our guide, which will explain exactly that: [Creating a custom CMS element](add-cms-element)
diff --git a/guides/plugins/plugins/content/cms/add-cms-element.md b/guides/development/extensions/plugins/content/cms/add-cms-element.md
similarity index 100%
rename from guides/plugins/plugins/content/cms/add-cms-element.md
rename to guides/development/extensions/plugins/content/cms/add-cms-element.md
diff --git a/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md b/guides/development/extensions/plugins/content/cms/add-data-to-cms-elements.md
similarity index 100%
rename from guides/plugins/plugins/content/cms/add-data-to-cms-elements.md
rename to guides/development/extensions/plugins/content/cms/add-data-to-cms-elements.md
diff --git a/guides/plugins/plugins/content/cms/index.md b/guides/development/extensions/plugins/content/cms/index.md
similarity index 100%
rename from guides/plugins/plugins/content/cms/index.md
rename to guides/development/extensions/plugins/content/cms/index.md
diff --git a/guides/plugins/plugins/content/index.md b/guides/development/extensions/plugins/content/index.md
similarity index 100%
rename from guides/plugins/plugins/content/index.md
rename to guides/development/extensions/plugins/content/index.md
diff --git a/guides/plugins/plugins/content/mail/add-data-to-mails.md b/guides/development/extensions/plugins/content/mail/add-data-to-mails.md
similarity index 100%
rename from guides/plugins/plugins/content/mail/add-data-to-mails.md
rename to guides/development/extensions/plugins/content/mail/add-data-to-mails.md
diff --git a/guides/plugins/plugins/content/mail/add-mail-template.md b/guides/development/extensions/plugins/content/mail/add-mail-template.md
similarity index 100%
rename from guides/plugins/plugins/content/mail/add-mail-template.md
rename to guides/development/extensions/plugins/content/mail/add-mail-template.md
diff --git a/guides/plugins/plugins/content/mail/index.md b/guides/development/extensions/plugins/content/mail/index.md
similarity index 100%
rename from guides/plugins/plugins/content/mail/index.md
rename to guides/development/extensions/plugins/content/mail/index.md
diff --git a/guides/plugins/plugins/content/media/add-custom-file-extension.md b/guides/development/extensions/plugins/content/media/add-custom-file-extension.md
similarity index 100%
rename from guides/plugins/plugins/content/media/add-custom-file-extension.md
rename to guides/development/extensions/plugins/content/media/add-custom-file-extension.md
diff --git a/guides/plugins/plugins/content/media/index.md b/guides/development/extensions/plugins/content/media/index.md
similarity index 100%
rename from guides/plugins/plugins/content/media/index.md
rename to guides/development/extensions/plugins/content/media/index.md
diff --git a/guides/plugins/plugins/content/media/prevent-deletion-of-media-files-referenced-in-your-plugins.md b/guides/development/extensions/plugins/content/media/prevent-deletion-of-media-files-referenced-in-your-plugins.md
similarity index 100%
rename from guides/plugins/plugins/content/media/prevent-deletion-of-media-files-referenced-in-your-plugins.md
rename to guides/development/extensions/plugins/content/media/prevent-deletion-of-media-files-referenced-in-your-plugins.md
diff --git a/guides/plugins/plugins/content/media/remote-thumbnail-generation.md b/guides/development/extensions/plugins/content/media/remote-thumbnail-generation.md
similarity index 100%
rename from guides/plugins/plugins/content/media/remote-thumbnail-generation.md
rename to guides/development/extensions/plugins/content/media/remote-thumbnail-generation.md
diff --git a/guides/plugins/plugins/content/seo/add-custom-seo-url.md b/guides/development/extensions/plugins/content/seo/add-custom-seo-url.md
similarity index 100%
rename from guides/plugins/plugins/content/seo/add-custom-seo-url.md
rename to guides/development/extensions/plugins/content/seo/add-custom-seo-url.md
diff --git a/guides/plugins/plugins/content/seo/extend-robots-txt.md b/guides/development/extensions/plugins/content/seo/extend-robots-txt.md
similarity index 100%
rename from guides/plugins/plugins/content/seo/extend-robots-txt.md
rename to guides/development/extensions/plugins/content/seo/extend-robots-txt.md
diff --git a/guides/plugins/plugins/content/seo/index.md b/guides/development/extensions/plugins/content/seo/index.md
similarity index 100%
rename from guides/plugins/plugins/content/seo/index.md
rename to guides/development/extensions/plugins/content/seo/index.md
diff --git a/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md b/guides/development/extensions/plugins/content/sitemap/add-custom-sitemap-entries.md
similarity index 100%
rename from guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md
rename to guides/development/extensions/plugins/content/sitemap/add-custom-sitemap-entries.md
diff --git a/guides/plugins/plugins/content/sitemap/index.md b/guides/development/extensions/plugins/content/sitemap/index.md
similarity index 100%
rename from guides/plugins/plugins/content/sitemap/index.md
rename to guides/development/extensions/plugins/content/sitemap/index.md
diff --git a/guides/development/extensions/plugins/content/sitemap/modify-sitemap-entries.md b/guides/development/extensions/plugins/content/sitemap/modify-sitemap-entries.md
new file mode 100644
index 0000000000..9c2e09dcda
--- /dev/null
+++ b/guides/development/extensions/plugins/content/sitemap/modify-sitemap-entries.md
@@ -0,0 +1,168 @@
+---
+nav:
+ title: Modifying sitemap entries
+ position: 20
+
+---
+
+# Modify Sitemap Entries
+
+## Overview
+
+You might have had a look at our guide about [adding custom sitemap entries](add-custom-sitemap-entries),
+e.g. for a custom entity.
+However, you might not want to add new URLs, but rather modify already existing ones.
+This guide will cover modifying e.g. the product URLs for the sitemap.
+
+## Prerequisites
+
+This guide is built upon the [Plugin base guide](../../plugin-base-guide), like most guides.
+
+Modifying the sitemap entries is done via decoration, so should know how that's done as well.
+Also, knowing how the URL providers work, like it's explained in our guide about [adding custom sitemap entries](add-custom-sitemap-entries),
+will come in handy.
+
+## Modifying the sitemap
+
+There's two ways of actually modifying the sitemap entries, but both ways are done by decorating
+the respective `UrlProvider`, e.g. the `Shopware\Core\Content\Sitemap\Provider\ProductUrlProvider` for products.
+
+Hence, let's start with creating the basic decorated class for the `ProductUrlProvider`. We'll call
+this class `DecoratedProductUrlProvider`:
+
+<Tabs>
+<Tab title="DecoratedProductUrlProvider.php">
+
+```php
+// <plugin root>/src/Core/Content/Sitemap/Provider/DecoratedProductUrlProvider.php
+<?php declare(strict_types=1);
+
+namespace Swag\BasicExample\Core\Content\Sitemap\Provider;
+
+use Doctrine\DBAL\Connection;
+use Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider;
+use Shopware\Core\Content\Sitemap\Struct\UrlResult;
+use Shopware\Core\Framework\Uuid\Uuid;
+use Shopware\Core\System\SalesChannel\SalesChannelContext;
+
+class DecoratedProductUrlProvider extends AbstractUrlProvider
+{
+ private AbstractUrlProvider $decoratedUrlProvider;
+
+ public function __construct(AbstractUrlProvider $abstractUrlProvider)
+ {
+ $this->decoratedUrlProvider = $abstractUrlProvider;
+ }
+
+ public function getDecorated(): AbstractUrlProvider
+ {
+ return $this->decoratedUrlProvider;
+ }
+
+ public function getName(): string
+ {
+ return $this->getDecorated()->getName();
+ }
+
+ public function getUrls(SalesChannelContext $context, int $limit, ?int $offset = null): UrlResult
+ {
+ return $this->getDecorated()->getUrls($context, $limit, $offset);
+ }
+}
+```
+
+</Tab>
+
+<Tab title="services.xml">
+
+```xml
+// <plugin root>/src/Resources/config/services.xml
+<?xml version="1.0" ?>
+<container xmlns="http://symfony.com/schema/dic/services"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+ <services>
+ <service id="Swag\BasicExample\Core\Content\Sitemap\Provider\DecoratedProductUrlProvider" decorates="Shopware\Core\Content\Sitemap\Provider\ProductUrlProvider">
+ <argument type="service" id="Swag\BasicExample\Core\Content\Sitemap\Provider\DecoratedProductUrlProvider.inner" />
+ </service>
+ </services>
+</container>
+```
+
+</Tab>
+</Tabs>
+
+Now let's get on to the two possible ways and its benefits.
+
+### Adjusting the getUrls method
+
+By adjusting the `getUrls` method, you can execute the parent's `getUrls` method and modify its return value, which
+is an instance of the `UrlResult`.
+On this instance, you can use the method `getUrls` to actually get the `Url` instances and make adjustments to them - or even remove them.
+
+```php
+// <plugin root>/src/Core/Content/Sitemap/Provider/DecoratedProductUrlProvider.php
+public function getUrls(SalesChannelContext $context, int $limit, ?int $offset = null): UrlResult
+{
+ $urlResult = $this->getDecorated()->getUrls($context, $limit, $offset);
+ $urls = $urlResult->getUrls();
+
+ /* Change $urls, e.g. removing entries or updating them by iterating over them. */
+
+ return new UrlResult($urls, $urlResult->getNextOffset());
+}
+```
+
+You could iterate over the `$urls` array and modify each entry - or even create a new array with less entries,
+if you want to fully remove some.
+
+There is one main downside to this way:
+You don't have access to a lot of information about the entity itself, that was used for this `Url` instance.
+E.g. if you'd like to filter all products with a given name, you can't do that here, since the name itself isn't available.
+The only reliable information you have here, is the ID of the entity by using the method `getIdentifier` on the `Url` instance.
+
+Also, it's not the best way in terms of performance to read all SEO URLs from the database, only to filter them afterwards.
+
+### Overriding the getSeoUrls method
+
+The available SEO URLs are read in the protected method `getSeoUrls` of the `AbstractUrlProvider`.
+Since it's a protected method, you can override it and create a custom SQL in order to only read the data you really want.
+
+For this you'll most likely want to copy the original method's code and paste it into your overridden method.
+You can then add new lines to the SQL statement in order to do the necessary filtering or customising.
+
+```php
+// <plugin root>/src/Core/Content/Sitemap/Provider/DecoratedProductUrlProvider.php
+protected function getSeoUrls(array $ids, string $routeName, SalesChannelContext $context, Connection $connection): array
+{
+ /* Make adjustments to this SQL */
+ $sql = 'SELECT LOWER(HEX(foreign_key)) as foreign_key, seo_path_info
+ FROM seo_url WHERE foreign_key IN (:ids)
+ AND `seo_url`.`route_name` =:routeName
+ AND `seo_url`.`is_canonical` = 1
+ AND `seo_url`.`is_deleted` = 0
+ AND `seo_url`.`language_id` =:languageId
+ AND (`seo_url`.`sales_channel_id` =:salesChannelId OR seo_url.sales_channel_id IS NULL)';
+
+ return $connection->fetchAll(
+ $sql,
+ [
+ 'routeName' => $routeName,
+ 'languageId' => Uuid::fromHexToBytes($context->getSalesChannel()->getLanguageId()),
+ 'salesChannelId' => Uuid::fromHexToBytes($context->getSalesChannelId()),
+ 'ids' => Uuid::fromHexToBytesList(array_values($ids)),
+ ],
+ [
+ 'ids' => Connection::PARAM_STR_ARRAY,
+ ]
+ );
+}
+```
+
+Now you could adjust the SQL statement to fit your needs, e.g. by adding a `JOIN` to the respective entities' table.
+
+However, there is a downside here as well:
+Overriding the method like this is not really update-compatible. If the original method is changed in a future
+update, those changes will not apply for your modification, hence you might not receive a performance update or a bugfix
+for those few lines of code.
diff --git a/guides/plugins/plugins/content/sitemap/remove-sitemap-entries.md b/guides/development/extensions/plugins/content/sitemap/remove-sitemap-entries.md
similarity index 100%
rename from guides/plugins/plugins/content/sitemap/remove-sitemap-entries.md
rename to guides/development/extensions/plugins/content/sitemap/remove-sitemap-entries.md
diff --git a/guides/plugins/plugins/content/stock/implementing-your-own-stock-storage.md b/guides/development/extensions/plugins/content/stock/implementing-your-own-stock-storage.md
similarity index 100%
rename from guides/plugins/plugins/content/stock/implementing-your-own-stock-storage.md
rename to guides/development/extensions/plugins/content/stock/implementing-your-own-stock-storage.md
diff --git a/guides/plugins/plugins/content/stock/index.md b/guides/development/extensions/plugins/content/stock/index.md
similarity index 100%
rename from guides/plugins/plugins/content/stock/index.md
rename to guides/development/extensions/plugins/content/stock/index.md
diff --git a/guides/plugins/plugins/content/stock/loading-stock-information-from-different-source.md b/guides/development/extensions/plugins/content/stock/loading-stock-information-from-different-source.md
similarity index 100%
rename from guides/plugins/plugins/content/stock/loading-stock-information-from-different-source.md
rename to guides/development/extensions/plugins/content/stock/loading-stock-information-from-different-source.md
diff --git a/guides/plugins/plugins/content/stock/reading-writing-stock.md b/guides/development/extensions/plugins/content/stock/reading-writing-stock.md
similarity index 100%
rename from guides/plugins/plugins/content/stock/reading-writing-stock.md
rename to guides/development/extensions/plugins/content/stock/reading-writing-stock.md
diff --git a/guides/development/extensions/plugins/creating-plugins.md b/guides/development/extensions/plugins/creating-plugins.md
new file mode 100644
index 0000000000..371af13f75
--- /dev/null
+++ b/guides/development/extensions/plugins/creating-plugins.md
@@ -0,0 +1,223 @@
+---
+nav:
+ title: Creating plugins
+ position: 2
+
+---
+
+## Creating and installing plugins
+
+This guide walks you through creating a basic Shopware plugin and installing it locally on your Shopware 6 instance.
+
+::: info
+Refer to this video on **[Creating a plugin](https://www.youtube.com/watch?v=_Tkoq5W7woI)** that shows how to bootstrap a plugin. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
+:::
+
+## Prerequisites
+
+You'll need:
+
+* PHP knowledge
+* A running Shopware 6 instance; refer to our [Install Shopware 6](../../installation/) guide if needed
+* full file system and command line access
+
+`<shopware project root>/custom/plugins` contains all plugins from the Shopware store. You install and manage these plugins via the Shopware Administration.
+
+## 1. Choose a name
+
+Use **UpperCamelCase**, which means that your plugin name must begin with a capital letter too. Whenever possible, begin it with a company prefix to avoid duplicate names (e.g., `SwagBasicExample`). Choose a name that describes your plugin as succinctly and clearly as possible.
+
+::: info
+A vendor prefix is required if you plan to publish your plugin in the [Shopware Community Store](https://store.shopware.com/en).
+:::
+
+## 2. Generate the plugin structure
+
+From your Shopware project's root directory, run:
+
+```bash
+bin/console plugin:create SwagBasicExample
+```
+
+Optionally, you can run this command to create a demo configuration file in the `Resources` directory:
+
+```bash
+bin/console plugin:create SwagBasicExample --create-config
+```
+
+The command will generate all the basic required files that are needed for an extension to be installed on a Shopware instance. Make sure to adjust the namespace in the files as per your need.
+
+### Structure for long-term maintainability
+
+When building multiple custom features, consider grouping related functionality inside a single plugin or repository instead of creating many isolated plugins.
+
+Keeping extensions in one repository with shared CI, shared static analysis rules, and unified coding standards makes future upgrades significantly easier to manage.
+
+## 3. Plugin structure
+
+Generated location:
+
+```bash
+custom/plugins/SwagBasicExample
+```
+
+Minimal structure:
+
+```text
+SwagBasicExample/
+├── composer.json
+└── src/
+ └── SwagBasicExample.php
+```
+
+Basic plugin class:
+
+```php
+<?php declare(strict_types=1);
+
+namespace Swag\BasicExample;
+
+use Shopware\Core\Framework\Plugin;
+
+class SwagBasicExample extends Plugin
+{
+}
+```
+
+## 4. composer.json essentials
+
+To be installable, your plugin requires a `composer.json` file in its root directory: `custom/plugins/SwagBasicExample/composer.json`. Shopware uses this file to identify and register your plugin.
+
+This file contains basic metadata that Shopware needs to know about your plugin, such as:
+
+* The technical name
+* The description
+* The author
+* The used license
+* The current plugin version
+* The required dependencies
+* and other configuration details.
+
+At a minimum, it must define:
+
+* `"type": "shopware-platform-plugin"`, so that Shopware can safely recognize your plugin
+* `require` field must include `shopware/core`, to check for compatibility
+* `"extra.shopware-plugin-class"` pointing to your plugin base class
+* [PSR-4](https://www.php-fig.org/psr/psr-4/) autoload configuration
+
+The `extra.shopware-plugin-class` value must reference your plugin’s base PHP class (e.g. `Swag\\BasicExample\\SwagBasicExample`).
+
+The `autoload.psr-4` namespace must match your directory structure. If you change the path (for example, not using `src/`), your folders must reflect that configuration.
+
+::: info
+[This video](https://www.youtube.com/watch?v=CY3SlfwkTm8) explains the `composer.json` structure in more detail. Our free ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma) training is another useful resource.
+:::
+
+This file can also be read by [Composer](https://getcomposer.org/).
+
+Here's an example `composer.json` you can refer to:
+
+<details>
+<summary>Example composer.json</summary>
+
+```javascript
+// <plugin root>/composer.json
+{
+ "name": "swag/basic-example",
+ "description": "Description for the plugin SwagBasicExample",
+ "version": "1.0.0",
+ "type": "shopware-platform-plugin",
+ "license": "MIT",
+ "authors": [
+ {
+ "name": "Shopware"
+ }
+ ],
+ "require": {
+ "shopware/core": "~6.6.0"
+ },
+ "extra": {
+ "shopware-plugin-class": "Swag\\BasicExample\\SwagBasicExample",
+ "label": {
+ "de-DE": "Der angezeigte lesbare Name für das Plugin",
+ "en-GB": "The displayed readable name for the plugin"
+ },
+ "description": {
+ "de-DE": "Beschreibung in der Administration für das Plugin",
+ "en-GB": "Description in the Administration for this plugin"
+ }
+ },
+ "autoload": {
+ "psr-4": {
+ "Swag\\BasicExample\\": "src/"
+ }
+ }
+}
+```
+</details>
+
+::: warning
+If you change the `autoload.psr-4` path (for example, not using `src/`), adjust your directory structure accordingly.
+:::
+
+::: Info
+Set up [CI](../../testing/ci.md) early. Run static analysis, tests, and `shopware-cli extension build` in CI so your plugin ZIP is reproducible and safe to promote across environments.
+:::
+
+## Add Shopware Packagist (optional)
+
+Shopware's Packagist instance enables management of Shopware Store plugins directly in the `composer.json`. To add the repository to your project, run:
+
+```bash
+composer config repositories.shopware composer https://packages.shopware.com
+```
+
+Authentication via API token is required. Refer to ["Using Composer for plugin installation in Shopware"](https://www.shopware.com/en/news/using-composer-for-plugin-installation-in-shopware/) for detailed information.
+
+### Manual creation (optional)
+
+In most cases, you should use `bin/console plugin:create`. Manual creation is only useful if you need full control over the structure or are working in a custom setup.
+
+Navigate to `custom/plugins` to create a new directory named after your plugin, so that it looks like this:
+
+```bash
+custom/plugins/SwagBasicExample
+```
+
+Minimal structure:
+
+```text
+SwagBasicExample/
+├── composer.json
+└── src/
+ └── SwagBasicExample.php
+```
+
+- **namespace**: here, it's `Swag\BasicExample`. We recommend using a combination of your manufacturer prefix and the technical name to name it.
+- **`src/` directory**: recommended but not strictly required.
+- **PHP class**: `SwagBasicExample.php`, which you name after your plugin.
+
+The new class `SwagBasicExample` must extend Shopware's abstract plugin class, `Shopware\Core\Framework\Plugin`:
+
+```php
+// <plugin root>/src/SwagBasicExample.php
+<?php declare(strict_types=1);
+
+namespace Swag\BasicExample;
+
+use Shopware\Core\Framework\Plugin;
+
+class SwagBasicExample extends Plugin
+{
+}
+```
+
+::: warning
+If you change the `autoload.psr-4` path (for example, not using `src/`), your directory structure must match that configuration.
+:::
+
+And that's it. The basic structure and all necessary files for your plugin to be installable are done.
+
+## Next steps
+
+[Install and activate](install-activate) your plugin.
diff --git a/guides/plugins/plugins/plugin-fundamentals/custom-fields-of-type-media.md b/guides/development/extensions/plugins/database/custom-fields-of-type-media.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/custom-fields-of-type-media.md
rename to guides/development/extensions/plugins/database/custom-fields-of-type-media.md
diff --git a/guides/plugins/plugins/plugin-fundamentals/database-migrations.md b/guides/development/extensions/plugins/database/database-migrations.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/database-migrations.md
rename to guides/development/extensions/plugins/database/database-migrations.md
diff --git a/guides/development/extensions/plugins/database/index.md b/guides/development/extensions/plugins/database/index.md
new file mode 100644
index 0000000000..024224b551
--- /dev/null
+++ b/guides/development/extensions/plugins/database/index.md
@@ -0,0 +1,22 @@
+---
+nav:
+ title: Database
+ position: 40
+---
+
+# Database
+
+Plugins can extend or interact with the Shopware database using migrations, entities, and custom fields.
+
+This section covers:
+
+* How to create and manage database migrations
+* How to generate migrations from entity definitions
+* How to work with custom fields (e.g., media custom fields)
+
+## Guides
+
+* <PageRef page="./database-migrations" />
+* <PageRef page="./custom-fields-of-type-media" />
+
+Use migrations for schema changes and structural updates. Use custom fields to extend existing entities without modifying the core schema.
diff --git a/guides/plugins/plugins/plugin-fundamentals/add-plugin-dependencies.md b/guides/development/extensions/plugins/dependencies/add-plugin-dependencies.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/add-plugin-dependencies.md
rename to guides/development/extensions/plugins/dependencies/add-plugin-dependencies.md
diff --git a/guides/development/extensions/plugins/dependencies/index.md b/guides/development/extensions/plugins/dependencies/index.md
new file mode 100644
index 0000000000..d1d86047e1
--- /dev/null
+++ b/guides/development/extensions/plugins/dependencies/index.md
@@ -0,0 +1,19 @@
+---
+nav:
+ title: Dependencies
+ position: 70
+---
+
+# Dependencies
+
+These guides explain how to manage plugin dependencies in Shopware, including plugin requirements, Composer packages, and NPM packages. Use them to:
+
+* Declare dependencies on other plugins
+* Add and bundle Composer dependencies
+* Install and configure NPM packages for Administration or Storefront
+
+Proper dependency management ensures compatibility, predictable installation behavior, and clean integration with Shopware’s build and package systems.
+
+* <PageRef page="./add-plugin-dependencies" />
+* <PageRef page="./using-composer-dependencies" />
+* <PageRef page="./using-npm-dependencies" />
diff --git a/guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies.md b/guides/development/extensions/plugins/dependencies/using-composer-dependencies.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies.md
rename to guides/development/extensions/plugins/dependencies/using-composer-dependencies.md
diff --git a/guides/plugins/plugins/plugin-fundamentals/using-npm-dependencies.md b/guides/development/extensions/plugins/dependencies/using-npm-dependencies.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/using-npm-dependencies.md
rename to guides/development/extensions/plugins/dependencies/using-npm-dependencies.md
diff --git a/guides/development/extensions/plugins/execution/add-custom-commands.md b/guides/development/extensions/plugins/execution/add-custom-commands.md
new file mode 100644
index 0000000000..0d17c960d7
--- /dev/null
+++ b/guides/development/extensions/plugins/execution/add-custom-commands.md
@@ -0,0 +1,18 @@
+---
+nav:
+ title: Add custom CLI commands
+ position: 90
+
+---
+
+# Add Custom CLI Commands
+
+Shopware CLI commands are based on Symfony Console. This means that creating custom commands in Shopware plugins follows the standard Symfony approach.
+
+See the [official Symfony documentation](https://symfony.com/doc/current/console.html) for the full guide.
+
+Commands registered as services in a Shopware plugin are automatically available via `bin/console`.
+
+## More interesting topics
+
+* [Adding a scheduled task](add-scheduled-task)
diff --git a/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md b/guides/development/extensions/plugins/execution/add-scheduled-task.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md
rename to guides/development/extensions/plugins/execution/add-scheduled-task.md
diff --git a/guides/development/extensions/plugins/execution/index.md b/guides/development/extensions/plugins/execution/index.md
new file mode 100644
index 0000000000..07653162c5
--- /dev/null
+++ b/guides/development/extensions/plugins/execution/index.md
@@ -0,0 +1,12 @@
+---
+nav:
+ title: Execution
+ position: 60
+---
+
+# Execution
+
+These guides cover runtime execution topics in plugins, including CLI commands and background processing.
+
+* <PageRef page="./add-custom-commands" />
+* <PageRef page="./add-scheduled-task" />
diff --git a/guides/plugins/plugins/framework/rule/add-custom-rules.md b/guides/development/extensions/plugins/framework/add-custom-rules.md
similarity index 96%
rename from guides/plugins/plugins/framework/rule/add-custom-rules.md
rename to guides/development/extensions/plugins/framework/add-custom-rules.md
index 0b1516632d..1a074c7deb 100644
--- a/guides/plugins/plugins/framework/rule/add-custom-rules.md
+++ b/guides/development/extensions/plugins/framework/add-custom-rules.md
@@ -7,6 +7,8 @@ nav:
# Add Custom Rules
+The Rule Builder allows users to add custom rules to create dynamic conditions and actions within the e-commerce platform. Using the Rule Builder, you can define specific criteria based on various attributes, such as customer data, cart contents, order details, or other relevant factors. These custom rules can then trigger specific actions, such as applying discounts, displaying personalized content, or adjusting pricing based on specific conditions. The Rule Builder empowers businesses to create highly tailored and automated experiences for their customers, enhancing the flexibility and customization options within the Shopware framework.
+
## Overview
In this guide you will learn how to create rules in Shopware. Rules are used by the rule builder.
diff --git a/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md b/guides/development/extensions/plugins/framework/add-rate-limiter-to-api-route.md
similarity index 94%
rename from guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md
rename to guides/development/extensions/plugins/framework/add-rate-limiter-to-api-route.md
index 380621a2d5..1328230b76 100644
--- a/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md
+++ b/guides/development/extensions/plugins/framework/add-rate-limiter-to-api-route.md
@@ -7,6 +7,8 @@ nav:
# Add Rate Limiter to API Route
+A rate limiter controls the rate or frequency at which API requests can be made. It sets limits on the number of requests that can be processed within a specified time period, preventing excessive usage. Hence eliminating the chance of brute-force attacks. Rate limiters help maintain system stability, protect against misuse, and ensure fair resource allocation by enforcing predefined limits on the rate of incoming requests.
+
## Overview
In this guide you'll learn how to secure API routes with a rate limit to reduce the risk against bruteforce attacks.
diff --git a/guides/development/extensions/plugins/framework/caching.md b/guides/development/extensions/plugins/framework/caching.md
new file mode 100644
index 0000000000..a84e71ec37
--- /dev/null
+++ b/guides/development/extensions/plugins/framework/caching.md
@@ -0,0 +1,414 @@
+---
+nav:
+ title: Caching
+ position: 20
+
+---
+
+# Caching
+
+Caching is a technique to store frequently accessed data in a temporary storage layer for faster retrieval, reducing latency and improving performance by avoiding repeated and costly data retrieval operations
+
+While caching enhances performance, it requires careful management of data consistency, cache invalidation strategies, and storage efficiency to prevent serving outdated or incorrect data.
+
+This guide will show you how you can modify the default caching mechanisms to suite your needs. If you are looking for information on how to add your routes to the HTTP-Cache, take a look at [this guide](../../storefront/add-caching-to-custom-controller.md).
+
+## Cache layers
+
+The current cache system of Shopware is based on a multi-layer system, in which the individual layers build on each other to improve performance and scalability.
+There is the [HTTP-Cache](../../../../../concepts/framework/http_cache.md) on the outer level and then multiple smaller internal "Object Caches" that are used to cache data in the application.
+
+For information on how to configure the different cache layers, please refer to the [caching hosting guide](../../../../hosting/performance/caches.md).
+
+### HTTP-Cache
+
+Before jumping in and adjusting the HTTP-Caching, please familiarize yourself with the general [HTTP-Cache concept](../../../../../concepts/framework/http_cache.md) first.
+
+#### Manipulating the cache key
+
+There are several entry points to manipulate the cache key.
+
+* `Shopware\Core\Framework\Adapter\Cache\Http\Extension\CacheHashRequiredExtension`: used to determine whether the cache hash should be calculated or if the request in running in the default state, and therefore no cache-hash is needed.
+* `Shopware\Core\Framework\Adapter\Cache\Event\HttpCacheCookieEvent`: used to calculate the cache hash based on the application state, supports both reverse proxy caches and the default symfony HTTP-cache component.
+* `Shopware\Core\Framework\Adapter\Cache\Http\Extension\ResolveCacheRelevantRuleIdsExtension`: used to determine which rule IDs are relevant for the cache hash.
+* `Shopware\Core\Framework\Adapter\Cache\Event\HttpCacheKeyEvent`: used to calculate the exact cache key based on the response, only for symfony's default HTTP-cache component.
+
+##### Modifying when the cache hash is calculated
+
+By default, the cache hash is only calculated when the request is not in the default state, which is: no logged in customer, default currency, and an empty cart.
+The reason is that the very first request to the application from a client should always be cached in the best case, the state that the application is in then is the "default state", which does not require a cache hash.
+You can overwrite the default behaviour and add more conditions where the cache hash needs to be applied, e.g., when you shop needs to be more dynamic e.g. based on campaign query parameters:
+
+```php
+class RequireCacheHash implements EventSubscriberInterface
+{
+ public static function getSubscribedEvents(): array
+ {
+ return [
+ CacheHashRequiredExtension::NAME . '.post' => 'onRequireCacheHash',,
+ ];
+ }
+
+ public function onRequireCacheHash(CacheHashRequiredExtension $extension): void
+ {
+ if ($extension->request->query->has('campaignId')) {
+ $extension->result = true;
+ }
+ }
+}
+```
+
+##### Modifying the cache hash
+
+The cache hash is used as the basis for the cache key.
+It is calculated based on the application state, which includes the current user, the current language, and so on.
+As the cache hash is calculated based on the application state, you have access to the resolved `SalesChannelContext` to determine the cache hash.
+It is stored alongside the response as a cookie and thus also provided with all following requests, to allow differentiating the cache based on the application state.
+As the cache hash will be carried over to the next request, the computed cache hash can be used inside reverse proxy caches as well as the default symfony HTTP-cache component.
+
+:::info
+The cache hash is only computed on every response as soon as the application state differs from the default state, which is: no logged in customer, default currency, and an empty cart.
+:::
+
+By default, the cache hash will consist of the following parts:
+
+* `rule-ids`: The matched rule IDs, to reduce possible cache permutations starting with v6.8.0.0, this will only include the rule IDs in `rule areas` that are cache relevant. See the next chapter how to extend this.
+* `version-id`: The context version used to load versioned DAL entities.
+* `currency-id`: The currency ID of the context.
+* `tax-state`: The tax state of the context (gross/net).
+* `logged-in`: Whether a customer is logged in in the current state or not.
+
+To modify the cache hash, you can subscribe to the `HttpCacheCookieEvent` event and add your own parts to the cache hash.
+This allows you to add more parts to the cache hash, e.g., the current customer's group.
+You can also disable the cache for certain conditions, because if that condition is met, the content is so dynamic that caching is not efficiently possible e.g., if the cart is filled.
+
+```php
+class HttpCacheCookieListener implements EventSubscriberInterface
+{
+ public function __construct(
+ private readonly CartService $cartService
+ ) {
+ }
+
+ public static function getSubscribedEvents(): array
+ {
+ return [
+ HttpCacheCookieEvent::class => 'onCacheCookie',
+ ];
+ }
+
+ public function onCacheCookie(HttpCacheCookieEvent $event): void
+ {
+ // you can add custom parts to the cache hash
+ // keep in mind that every possible value will increase the number of possible cache permutations
+ // and therefore directly impact cache hit rates, which in turn decreases performance
+ $event->add('customer-group', $event->context->getCustomerId());
+
+ // disable cache for filled carts
+ $cart = $this->cartService->getCart($event->context->getToken(), $event->context);
+ if ($cart->getLineItems()->count() > 0) {
+ // you can also explicitly disable caching based on specific conditions
+ $event->isCacheable = false;
+ }
+ }
+}
+```
+
+Additionally, you can modify the cache hash from the frontend client directly by adding separate cookies with the relevant value.
+You can configure custom cookies that are relevant for the cache hash in the `shopware.http_cache.cookies` option:
+
+```yaml
+shopware:
+ http_cache:
+ cookies:
+ - 'my-custom-cookie'
+```
+
+As soon as the cookie is set, that value will be included in the cache hash.
+Essentially, it saves you the effort to implement a custom cache cookie listener as shown above.
+This makes it especially suited for headless projects where the frontend implementation is more decoupled from the backend.
+
+##### Marking rule areas as cache relevant
+
+Starting with v6.8.0.0, the cache hash will only include the rule IDs in `rule areas` that are cache relevant.
+The reason is that a lot of rules are not relevant for the cache, e.g., rules that only affect pricing or shipping methods.
+This greatly reduces the number of possible cache permutations, which in turn improves the cache hit rate.
+
+By default, only the following rule areas are cache relevant:
+
+* `RuleAreas::PRODUCT_AREA`
+
+If you use the rule system in a way that is relevant for the cache (because the response differs based on the rules), you should add your rule area to the list of cache relevant rule areas.
+To do so, you need to subscribe to the `ResolveCacheRelevantRuleIdsExtension` event.
+
+```php
+class ResolveRuleIds implements EventSubscriberInterface
+{
+ public static function getSubscribedEvents(): array
+ {
+ return [
+ ResolveCacheRelevantRuleIdsExtension::NAME . '.pre' => 'onResolveRuleAreas',
+ ];
+ }
+
+ public function onResolveRuleAreas(ResolveCacheRelevantRuleIdsExtension $extension): void
+ {
+ $extension->ruleAreas[] = RuleExtension::MY_CUSTOM_RULE_AREA;
+ }
+}
+```
+
+This implies that you defined the rule area in your custom entities that have an associated rule entity, by using the DAL flag `Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\RuleAreas` on the rule association in the entity extension.
+
+```php
+class RuleExtension extends EntityExtension
+{
+ public const MY_CUSTOM_RULE_AREA = 'custom';
+
+ public function getEntityName(): string
+ {
+ return RuleDefinition::ENTITY_NAME;
+ }
+
+ public function extendFields(FieldCollection $collection): void
+ {
+ $collection->add(
+ (new ManyToManyAssociationField(
+ 'myPropertyName',
+ MyCustomDefinition::class,
+ MyMappingDefinition::class,
+ RuleDefinition::ENTITY_NAME . '_id',
+ MyCustomDefinition::ENTITY_NAME . '_id',
+ ))->addFlags(new CascadeDelete(), new RuleAreas(self::MY_CUSTOM_RULE_AREA)),
+ );
+ }
+}
+```
+
+For details on how to extend core definitions refer to the [DAL Guide](../../framework/data-handling/add-complex-data-to-existing-entities.md).
+
+##### Modifying the cache keys
+
+You can also modify the exact cache key used to store the response in the [symfony HTTP-Cache](https://symfony.com/doc/current/http_cache.html).
+If possible, you should manipulate the cache hash (as already explained above) instead, as that is also used in reverse proxy caches.
+You can do so by subscribing to the `HttpCacheKeyEvent` event and add your specific part to the key.
+
+```php
+class CacheKeySubscriber implements EventSubscriberInterface
+{
+ public static function getSubscribedEvents(): array
+ {
+ return [
+ HttpCacheKeyEvent::class => 'addKeyPart',
+ ];
+ }
+
+ public function addKeyPart(HttpCacheKeyEvent $event): void
+ {
+ $request = $event->request;
+ // Perform checks to determine the key
+ $key = $this->determineKey($request);
+ $event->add('myCustomKey', $key);
+
+ // You can also disable caching for certain conditions
+ $event->isCacheable = false;
+ }
+}
+```
+
+:::info
+The event is called on any Request; make sure that you don't use expensive operations like Database Queries.
+
+Also, with an external reverse proxy, the cache key might be generated on the proxy and not in your application. In that case, you need to add the key part to the reverse proxy configuration.
+:::
+
+#### Adding cache tags
+
+One problem with caching is that you not only need to retrieve the correct data, but also need to have a performant way to invalidate the cache when the data changes.
+Only invalidating the caches based on the unique cache key is often not that helpful, because you don't know which cache keys are affected by the change of a specific data set.
+Therefore, a tagging system is used alongside the cache keys to make cache invalidations easier and more performant. Every cache entry can be tagged with multiple tags, thus we can invalidate the cache based on the tags.
+For example, all pages that contain product data are tagged with product IDs of all products they contain. So if a product is changed, we can invalidate all cache entries that are tagged with the product ID of the changed product.
+
+To add your own cache tags to the HTTP-Cache, you can use the `CacheTagCollector` service.
+
+```php
+class MyCustomEntityExtension
+{
+ public function __construct(
+ private readonly CacheTagCollector $cacheTagCollector,
+ ) {}
+
+ public function loadAdditionalData(): void
+ {
+ // Load the additional data you need, add it to the response, then add the correct tag to the cache entry
+ $this->cacheTagCollector->addTag('my-custom-entity-' . $idOfTheLoadedData);
+ }
+}
+```
+
+#### Invalidating the cache
+
+Adding custom cache tags is only useful if you also use them to invalidate the cache when the data changed.
+To invalidate the cache, you need to call the `CacheInvalidator` service and pass the tag you want to invalidate.
+
+```php
+class CacheInvalidationSubscriber implements EventSubscriberInterface
+{
+ public function __construct(private CacheInvalidator $cacheInvalidator)
+ {
+ }
+
+ public static function getSubscribedEvents()
+ {
+ return [
+ // The EntityWrittenContainerEvent is a generic event always thrown when an entities are written. This contains all changed entities
+ EntityWrittenContainerEvent::class => 'invalidate'
+ ],
+ ];
+ }
+
+ public function invalidate(EntityWrittenContainerEvent $event): void
+ {
+ // Check if own entity written. In some cases, you want to use the primary keys for further cache invalidation
+ $changes = $event->getPrimaryKeys(ExampleDefinition::ENTITY_NAME);
+
+ // No example entity changed? Then the cache does not need to be invalidated
+ if (empty($changes)) {
+ return;
+ }
+
+ foreach ($changes as $id) {
+ // Invalidate the cache for the changed entity
+ $this->cacheInvalidator->invalidate([
+ 'my-custom-entity-' . $id
+ ]);
+ }
+ }
+}
+```
+
+##### Overwrite default cache invalidation behaviour
+
+The default tags that shopware adds to the HTTP-Cache are also invalidated automatically when the data changes. This is done by the `CacheInvalidationSubscriber` class, which listens to various events and invalidates the cache based on the tags that are added to the cache entries.
+However, the subscriber adheres to an exact invalidation concept, where any data written to the product invalidates cache tags for that specific product, even if the data is not used in the corresponding pages. This might lead to cases where the cache is invalidated too often, and the invalidation can be tweaked to the project's needs. Moreover, due to project-specific variations, it is not feasible to generalize the process.
+Therefore, all events it listens to are configured over the service configuration, so that all events, on which the subscriber listens to, can be manipulated via compiler passes.
+
+:::code-group
+
+```xml [PLUGIN_ROOT/src/Core/Framework/DependencyInjection/cache.xml]
+<service id="Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber">
+ <tag name="kernel.event_listener" event="Shopware\Core\Content\Category\Event\CategoryIndexerEvent" method="invalidateCategoryRouteByCategoryIds" priority="2000" />
+
+ <tag name="kernel.event_listener" event="Shopware\Core\Content\Category\Event\CategoryIndexerEvent" method="invalidateListingRouteByCategoryIds" priority="2001" />
+
+ <tag name="kernel.event_listener" event="Shopware\Core\Content\LandingPage\Event\LandingPageIndexerEvent" method="invalidateIndexedLandingPages" priority="2000" />
+
+ <!-- ... -->
+</service>
+```
+
+:::
+
+For example, if you want to disable all cache invalidations in a project, you can remove the `kernel.event_listener` tag of the service definition via compiler pass and implement your own cache invalidation.
+
+```php
+use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
+use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
+use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
+use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;
+
+class TweakCacheInvalidation implements CompilerPassInterface
+{
+ public function process(ContainerBuilder $container): void
+ {
+ $container
+ ->getDefinition(CacheInvalidationSubscriber::class)
+ ->clearTag('kernel.event_listener')
+ }
+
+}
+```
+
+However, suppose only certain parts of the cache invalidation are to be adjusted, finer adjustments to the class can be made using `Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener`, in which it is possible to define which event listeners of the service are to be removed.
+
+```php
+use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
+use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
+use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
+use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;
+
+class TweakCacheInvalidation implements CompilerPassInterface
+{
+ public function process(ContainerBuilder $container): void
+ {
+ RemoveEventListener::remove(
+ $container,
+ CacheInvalidationSubscriber::class,
+ [
+ [ProductIndexerEvent::class, 'invalidateListings'],
+ [ProductNoLongerAvailableEvent::class, 'invalidateListings'],
+ ]
+ );
+ }
+}
+```
+
+### Object Cache
+
+The internal caches are built upon the [Symfony Cache](https://symfony.com/doc/current/components/cache.html) component and are used internally to cache data that is expensive to compute or retrieve.
+As the object caches are handled internally, it should not be necessary to control them directly, therefore adding custom tags or manipulating the cache key is not supported for the various object caches.
+
+#### Cache invalidation
+
+However, you can still manually invalidate the object caches, via the same mechanism as you invalidate the HTTP-Cache, the `CacheInvalidator` service.
+
+You can use the `CacheInvalidator` service to invalidate the object caches by passing the tag you want to invalidate.
+
+```php
+public function invalidateSystemConfigCache(): void
+{
+ $this->cacheInvalidator->invalidate([
+ CachedSystemConfigLoader::CACHE_TAG
+ ]);
+}
+```
+
+## Delayed Invalidation
+
+By default, the cache invalidation happens delayed (for both http and object caches). This means that the invalidation is not instant, but rather all the tags that should be invalidated are invalidated in a regular interval. For special cases where you need to immediately clear the cache take a look at the [force immediate invalidation](#force-immediate-invalidation) section.
+This really benefits the performance of the system, as the invalidation is not done immediately, but rather in a batch process.
+Additionally, it prevents cases where sometimes the caches are written and deleted more often than they are read, which only leads to overhead, more resource needs on the caching side and a bad cache-hit rate.
+
+The invalidation of the delayed cache is done via the `shopware.invalidate_cache` task, that runs every 5 minutes (default setting). However, that run interval can be adjusted in the database.
+If your caches don't seem to be invalidated at all, please ensure that the scheduled tasks are running correctly.
+
+You can also manually invalidate the cache entries that are marked for delayed invalidation by running the `cache:clear:delayed` command or calling the `CacheInvalidator::invalidateExpired()` method from your plugin or send an API request to the `DELETE /api/_action/cache-delayed` endpoint.
+For debug purposes you can also watch the tags that are marked for delayed invalidation by running the `cache:watch:delayed` command.
+
+### Force immediate invalidation
+
+Some changes require that the caches should be invalidated immediately and returning stale content is not acceptable.
+In that case you can pass the `force=true` flag to the CacheInvalidator service, which will invalidate the cache immediately.
+
+```php
+public function invalidateSystemConfigCache(): void
+{
+ $this->cacheInvalidator->invalidate([
+ CachedSystemConfigLoader::CACHE_TAG
+ ], true);
+}
+```
+
+If you sent an API request with critical information, where the cache should be invalidated immediately, you can set the `sw-force-cache-invalidate` header on your request.
+
+```http
+POST /api/product
+sw-force-cache-invalidate: 1
+```
+
+## Manual cache clear
+
+You can also manually clear the caches when you performed some actions that made a cache invalidation necessary, but where it was not triggered automatically.
+To clear all caches, you can execute the `cache:clear:all` command, which clears the HTTP-Cache, the object caches as well as any other caches that are registered in the system.
+The `cache:clear` command on the other hand will only clear the object caches, but won't invalidate the HTTP-Cache.
+On the other hand, the `cache:clear:http` command will clear the complete HTTP-Cache, but won't invalidate the object caches.
diff --git a/guides/plugins/plugins/framework/custom-field/add-custom-field.md b/guides/development/extensions/plugins/framework/custom-field/add-custom-field.md
similarity index 100%
rename from guides/plugins/plugins/framework/custom-field/add-custom-field.md
rename to guides/development/extensions/plugins/framework/custom-field/add-custom-field.md
diff --git a/guides/plugins/plugins/framework/custom-field/fetching-data-from-entity-selection.md b/guides/development/extensions/plugins/framework/custom-field/fetching-data-from-entity-selection.md
similarity index 100%
rename from guides/plugins/plugins/framework/custom-field/fetching-data-from-entity-selection.md
rename to guides/development/extensions/plugins/framework/custom-field/fetching-data-from-entity-selection.md
diff --git a/guides/plugins/plugins/framework/custom-field/index.md b/guides/development/extensions/plugins/framework/custom-field/index.md
similarity index 100%
rename from guides/plugins/plugins/framework/custom-field/index.md
rename to guides/development/extensions/plugins/framework/custom-field/index.md
diff --git a/guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md b/guides/development/extensions/plugins/framework/data-handling/add-complex-data-to-existing-entities.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md
rename to guides/development/extensions/plugins/framework/data-handling/add-complex-data-to-existing-entities.md
diff --git a/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md b/guides/development/extensions/plugins/framework/data-handling/add-custom-complex-data.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md
rename to guides/development/extensions/plugins/framework/data-handling/add-custom-complex-data.md
diff --git a/guides/plugins/plugins/framework/data-handling/add-data-associations.md b/guides/development/extensions/plugins/framework/data-handling/add-data-associations.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/add-data-associations.md
rename to guides/development/extensions/plugins/framework/data-handling/add-data-associations.md
diff --git a/guides/plugins/plugins/framework/data-handling/add-data-indexer.md b/guides/development/extensions/plugins/framework/data-handling/add-data-indexer.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/add-data-indexer.md
rename to guides/development/extensions/plugins/framework/data-handling/add-data-indexer.md
diff --git a/guides/plugins/plugins/framework/data-handling/add-data-translations.md b/guides/development/extensions/plugins/framework/data-handling/add-data-translations.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/add-data-translations.md
rename to guides/development/extensions/plugins/framework/data-handling/add-data-translations.md
diff --git a/guides/plugins/plugins/framework/data-handling/deleting-associated-data.md b/guides/development/extensions/plugins/framework/data-handling/deleting-associated-data.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/deleting-associated-data.md
rename to guides/development/extensions/plugins/framework/data-handling/deleting-associated-data.md
diff --git a/guides/plugins/plugins/framework/data-handling/entities-via-attributes.md b/guides/development/extensions/plugins/framework/data-handling/entities-via-attributes.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/entities-via-attributes.md
rename to guides/development/extensions/plugins/framework/data-handling/entities-via-attributes.md
diff --git a/guides/plugins/plugins/framework/data-handling/field-inheritance.md b/guides/development/extensions/plugins/framework/data-handling/field-inheritance.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/field-inheritance.md
rename to guides/development/extensions/plugins/framework/data-handling/field-inheritance.md
diff --git a/guides/plugins/plugins/framework/data-handling/index.md b/guides/development/extensions/plugins/framework/data-handling/index.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/index.md
rename to guides/development/extensions/plugins/framework/data-handling/index.md
diff --git a/guides/plugins/plugins/framework/data-handling/reading-data.md b/guides/development/extensions/plugins/framework/data-handling/reading-data.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/reading-data.md
rename to guides/development/extensions/plugins/framework/data-handling/reading-data.md
diff --git a/guides/plugins/plugins/framework/data-handling/replacing-associated-data.md b/guides/development/extensions/plugins/framework/data-handling/replacing-associated-data.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/replacing-associated-data.md
rename to guides/development/extensions/plugins/framework/data-handling/replacing-associated-data.md
diff --git a/guides/plugins/plugins/framework/data-handling/using-database-events.md b/guides/development/extensions/plugins/framework/data-handling/using-database-events.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/using-database-events.md
rename to guides/development/extensions/plugins/framework/data-handling/using-database-events.md
diff --git a/guides/plugins/plugins/framework/data-handling/using-flags.md b/guides/development/extensions/plugins/framework/data-handling/using-flags.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/using-flags.md
rename to guides/development/extensions/plugins/framework/data-handling/using-flags.md
diff --git a/guides/plugins/plugins/framework/data-handling/versioning-entities.md b/guides/development/extensions/plugins/framework/data-handling/versioning-entities.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/versioning-entities.md
rename to guides/development/extensions/plugins/framework/data-handling/versioning-entities.md
diff --git a/guides/plugins/plugins/framework/data-handling/writing-data.md b/guides/development/extensions/plugins/framework/data-handling/writing-data.md
similarity index 100%
rename from guides/plugins/plugins/framework/data-handling/writing-data.md
rename to guides/development/extensions/plugins/framework/data-handling/writing-data.md
diff --git a/guides/plugins/plugins/framework/event/add-custom-event.md b/guides/development/extensions/plugins/framework/event/add-custom-event.md
similarity index 100%
rename from guides/plugins/plugins/framework/event/add-custom-event.md
rename to guides/development/extensions/plugins/framework/event/add-custom-event.md
diff --git a/guides/plugins/plugins/framework/event/finding-events.md b/guides/development/extensions/plugins/framework/event/finding-events.md
similarity index 100%
rename from guides/plugins/plugins/framework/event/finding-events.md
rename to guides/development/extensions/plugins/framework/event/finding-events.md
diff --git a/guides/plugins/plugins/framework/event/index.md b/guides/development/extensions/plugins/framework/event/index.md
similarity index 100%
rename from guides/plugins/plugins/framework/event/index.md
rename to guides/development/extensions/plugins/framework/event/index.md
diff --git a/guides/plugins/plugins/plugin-fundamentals/listening-to-events.md b/guides/development/extensions/plugins/framework/event/listening-to-events.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/listening-to-events.md
rename to guides/development/extensions/plugins/framework/event/listening-to-events.md
diff --git a/guides/plugins/plugins/framework/extension/creating-custom-extension.md b/guides/development/extensions/plugins/framework/extension/creating-custom-extension.md
similarity index 100%
rename from guides/plugins/plugins/framework/extension/creating-custom-extension.md
rename to guides/development/extensions/plugins/framework/extension/creating-custom-extension.md
diff --git a/guides/plugins/plugins/framework/extension/extension-vs-events.md b/guides/development/extensions/plugins/framework/extension/extension-vs-events.md
similarity index 100%
rename from guides/plugins/plugins/framework/extension/extension-vs-events.md
rename to guides/development/extensions/plugins/framework/extension/extension-vs-events.md
diff --git a/guides/plugins/plugins/framework/extension/finding-extensions.md b/guides/development/extensions/plugins/framework/extension/finding-extensions.md
similarity index 100%
rename from guides/plugins/plugins/framework/extension/finding-extensions.md
rename to guides/development/extensions/plugins/framework/extension/finding-extensions.md
diff --git a/guides/plugins/plugins/framework/extension/index.md b/guides/development/extensions/plugins/framework/extension/index.md
similarity index 100%
rename from guides/plugins/plugins/framework/extension/index.md
rename to guides/development/extensions/plugins/framework/extension/index.md
diff --git a/guides/plugins/plugins/framework/filesystem/filesystem.md b/guides/development/extensions/plugins/framework/filesystem.md
similarity index 81%
rename from guides/plugins/plugins/framework/filesystem/filesystem.md
rename to guides/development/extensions/plugins/framework/filesystem.md
index 5e3028f755..590be7448c 100644
--- a/guides/plugins/plugins/framework/filesystem/filesystem.md
+++ b/guides/development/extensions/plugins/framework/filesystem.md
@@ -5,19 +5,21 @@ nav:
---
-# Filesystem - Flysystem
+# Filesystem
-## Overview
+Plugins often need to read and write files. Shopware uses [Flysystem](https://flysystem.thephpleague.com/docs/), a file storage library for PHP. It provides a unified interface to interact with different storage backends, whether local file systems or cloud providers.
+
+Plugins do not require handling underlying configuration. It is possible to use the Flysystem abstraction directly, and the read/write API remains the same regardless of where files are stored.
-Flysystem is a file storage library for PHP. It provides one interface to interact with many types of filesystems. The Flysystem file system in Shopware is flexible, allowing seamless interaction with various file storage systems. It provides a consistent interface to access, manipulate, and manage files across different storage backends.
+To learn more about filesystem configuration in Shopware, see the [filesystem guide](../../../../hosting/infrastructure/filesystem), including details on using cloud storage such as Amazon S3.
## Prerequisites
This guide is built upon both the [Plugin base guide](../../plugin-base-guide) and the [Add custom service guide](../../plugin-fundamentals/add-custom-service).
-## Flysystem overview
+## Overview
-The Flysystem enables your plugin to read and write files through a common interface. There are several default namespaces/directories that are available, for example:
+The Flysystem enables plugins to read and write files through a common interface. There are several default namespaces/directories that are available, for example:
* One for private files of the shop: invoices, delivery notes
* One for public files: product pictures, media files
diff --git a/guides/plugins/plugins/framework/flow/action-transactions.md b/guides/development/extensions/plugins/framework/flow/action-transactions.md
similarity index 100%
rename from guides/plugins/plugins/framework/flow/action-transactions.md
rename to guides/development/extensions/plugins/framework/flow/action-transactions.md
diff --git a/guides/plugins/plugins/framework/flow/add-flow-builder-action.md b/guides/development/extensions/plugins/framework/flow/add-flow-builder-action.md
similarity index 100%
rename from guides/plugins/plugins/framework/flow/add-flow-builder-action.md
rename to guides/development/extensions/plugins/framework/flow/add-flow-builder-action.md
diff --git a/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md b/guides/development/extensions/plugins/framework/flow/add-flow-builder-trigger.md
similarity index 100%
rename from guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md
rename to guides/development/extensions/plugins/framework/flow/add-flow-builder-trigger.md
diff --git a/guides/plugins/plugins/framework/flow/index.md b/guides/development/extensions/plugins/framework/flow/index.md
similarity index 100%
rename from guides/plugins/plugins/framework/flow/index.md
rename to guides/development/extensions/plugins/framework/flow/index.md
diff --git a/guides/development/extensions/plugins/framework/index.md b/guides/development/extensions/plugins/framework/index.md
new file mode 100644
index 0000000000..947d4c10d6
--- /dev/null
+++ b/guides/development/extensions/plugins/framework/index.md
@@ -0,0 +1,24 @@
+---
+nav:
+ title: Framework
+ position: 50
+
+---
+
+# Framework
+
+This section covers core extension points of the Shopware framework. The framework offers data abstraction, custom fields, events, rules, message queues, file systems, flows, and rate limiters.
+
+These guides explain how to work with the underlying runtime systems that power Shopware, including:
+
+* [Custom Field](./custom-field/)
+* [Data Handling](./data-handling/)
+* [Event](./event/)
+* [Extension](./extension/)
+* [Flow](./flow/)
+* [Message Queue](./message-queue/)
+* [System Check](./system-check/)
+* [Add Custom Rules](./add-custom-rules.md)
+* [Add Rate Limiter to API Route](./add-rate-limiter-to-api-route.md)
+* [Caching](./caching.md)
+* [Filesystem](./filesystem.md)
diff --git a/guides/plugins/plugins/framework/message-queue/add-message-handler.md b/guides/development/extensions/plugins/framework/message-queue/add-message-handler.md
similarity index 100%
rename from guides/plugins/plugins/framework/message-queue/add-message-handler.md
rename to guides/development/extensions/plugins/framework/message-queue/add-message-handler.md
diff --git a/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md b/guides/development/extensions/plugins/framework/message-queue/add-message-to-queue.md
similarity index 100%
rename from guides/plugins/plugins/framework/message-queue/add-message-to-queue.md
rename to guides/development/extensions/plugins/framework/message-queue/add-message-to-queue.md
diff --git a/guides/plugins/plugins/framework/message-queue/add-middleware.md b/guides/development/extensions/plugins/framework/message-queue/add-middleware.md
similarity index 100%
rename from guides/plugins/plugins/framework/message-queue/add-middleware.md
rename to guides/development/extensions/plugins/framework/message-queue/add-middleware.md
diff --git a/guides/plugins/plugins/framework/message-queue/index.md b/guides/development/extensions/plugins/framework/message-queue/index.md
similarity index 100%
rename from guides/plugins/plugins/framework/message-queue/index.md
rename to guides/development/extensions/plugins/framework/message-queue/index.md
diff --git a/guides/plugins/plugins/framework/system-check/add-custom-check.md b/guides/development/extensions/plugins/framework/system-check/add-custom-check.md
similarity index 100%
rename from guides/plugins/plugins/framework/system-check/add-custom-check.md
rename to guides/development/extensions/plugins/framework/system-check/add-custom-check.md
diff --git a/guides/plugins/plugins/framework/system-check/index.md b/guides/development/extensions/plugins/framework/system-check/index.md
similarity index 100%
rename from guides/plugins/plugins/framework/system-check/index.md
rename to guides/development/extensions/plugins/framework/system-check/index.md
diff --git a/guides/development/extensions/plugins/index.md b/guides/development/extensions/plugins/index.md
new file mode 100644
index 0000000000..607e5f52c3
--- /dev/null
+++ b/guides/development/extensions/plugins/index.md
@@ -0,0 +1,131 @@
+---
+nav:
+ title: Plugins
+ position: 1
+
+---
+
+# Plugins
+
+Plugins are Shopware’s PHP-based, server-side extension type for enhancing platform functionality. They allow you to extend, overwrite, and modify Shopware's core capabilities at runtime.
+
+If you need to implement business logic, integrate external systems, or modify platform behavior beyond styling, you are looking for a plugin.
+
+Plugins run directly inside the Shopware environment and provide full access to:
+
+* The Symfony service container
+* Events and subscribers
+* Database layer and migrations
+* CLI commands and scheduled tasks
+* Administration extensions
+* Storefront extensions
+
+Technically, plugins are extensions of [Symfony bundles](symfony-bundles) and integrate deeply into the Shopware runtime. They follow a defined directory structure and, when used as managed extensions, provide a lifecycle (install, update, deactivate, uninstall).
+
+Plugins can ship their own assets, controllers, services, and tests, enabling deep platform and full extensibility across core and custom functionality.
+
+## When to create and use a plugin
+
+You will typically use a plugin when you need to:
+
+* Implement custom business logic for customer tracking, content, products and product imports, etc.
+* Modify or customize checkout or pricing behavior or calculations
+* Add database entities or migrations
+* Listen to and react to platform events
+* Register services in the DI container
+* Extend the Administration with custom modules
+* Add backend commands or scheduled tasks
+* Integrate third-party systems, including identity providers
+* Enable dynamic validations
+
+:::Info
+For infrastructure and external system integrations (e.g., Redis, Elasticsearch, or custom APIs), refer to the dedicated [integration guides](./integrations) in this section.
+:::
+
+### Choosing the right extension type
+
+| Requirement | Use |
+|-------------|------|
+| Backend logic or deep integration | Plugin |
+| Storefront styling or template overrides only | Plugin-based Theme |
+| SaaS-based integration without server access | App |
+
+::: info
+If your extension focuses only on design changes, a simple template adjustment—typically done through a plugin-based theme—may be the best choice.
+:::
+
+## Plugin types
+
+Shopware supports multiple plugin models, which differ in their folder structure and functionality.
+
+### Static plugins (recommended)
+
+Static plugins are ideal for:
+
+* Custom project logic
+* Team development workflows
+* CI/CD pipelines
+* Long-term maintainability
+
+Characteristics:
+
+* Versioned in Git
+* Live inside your project repository
+* Are installed and managed via Composer
+* Integrate cleanly into deployment workflows
+* No dependency on Administration installation
+* Offer clear separation between project code and marketplace extensions
+
+Project-specific static plugins live in `<shopware project root>/custom/static-plugins`. They must be required via Composer before they can be installed and activated:
+
+```bash
+composer require <vendor>/<plugin-name>
+```
+
+You can find the vendor/package name in the plugin's `composer.json` file under `name`.
+
+:::info
+The Shopware Administration does not detect static plugins. The project must require them via Composer for them to be installable.
+:::
+
+### Managed plugins
+
+Managed plugins are commonly used for marketplace-distributed extensions. They are located in `<shopware root>/custom/plugins` and are typically installed and managed via the Shopware Administration.
+
+### Bundles
+
+Symfony-based [bundles](https://developer.shopware.com/docs/guides/plugins/plugins/bundle.html) are installed via Composer. They do not have a Shopware plugin lifecycle and are not managed via Administration.
+
+Bundles are useful when you want:
+
+* Full Symfony-level control
+* No lifecycle handling or Administration management
+* Pure project-level customization
+
+Choose the extension model that best fits your distribution and maintenance strategy.
+
+## Architectural recommendation
+
+There is no need to create a separate plugin for every distinct functionality.
+
+For custom projects, it is often preferable to:
+
+* Maintain all custom logic in a single repository
+* Share one CI pipeline and one set of static analysis rules
+* Organize functionality through clean internal directory structure
+
+It does not matter whether static plugins or Symfony bundles internally are used, as much as having:
+
+* Clear domain boundaries
+* Consistent structure
+* Centralized quality control
+
+It is perfectly valid to ship multiple separate plugins, but keeping them in a single repository with unified tooling significantly reduces long-term maintenance and upgrade friction.
+
+## Next steps
+
+:::info
+Make note of [CI](../testing/ci.md) and other testing guidance to prevent upgrade-related regressions.
+:::
+
+Review the [Plugin base guide](plugin-base-guide) to learn how to create plugins.
diff --git a/guides/development/extensions/plugins/install-activate.md b/guides/development/extensions/plugins/install-activate.md
new file mode 100644
index 0000000000..94e2f372b7
--- /dev/null
+++ b/guides/development/extensions/plugins/install-activate.md
@@ -0,0 +1,55 @@
+---
+nav:
+ title: Install and activate plugins
+ position: 3
+
+---
+
+# Install and activate plugins
+
+This guide explains how to install and activate a newly created plugin.
+
+From your Shopware project root directory, refresh the list of plugins:
+
+```bash
+bin/console plugin:refresh
+```
+
+A warning about the `version` field of the `composer.json` file might appear; this can be ignored. You should see a list like this:
+
+```bash
+Shopware Plugin Service
+=======================
+
+ ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- -------------
+ Plugin Label Version Upgrade version Author Installed Active Upgradeable
+ ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- -------------
+ SwagBasicExample The displayed readable name for the plugin 1.0.0 Shopware No No No
+ ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- -------------
+```
+
+This output is a **good sign**, because this means Shopware recognized your plugin successfully.
+
+Now install and activate:
+
+```bash
+bin/console plugin:install --activate SwagBasicExample
+```
+
+This should print the following output:
+
+```bash
+Shopware Plugin Lifecycle Service
+=================================
+
+ Install 1 plugin(s):
+ * The displayed readable name for the plugin (v1.0.0)
+
+ Plugin "SwagBasicExample" has been installed and activated successfully.
+```
+
+If successful, your plugin is now active and ready to use!
+
+## Next steps
+
+Review our [plugin lifecycle](plugin-fundamentals/plugin-lifecycle) guide next.
diff --git a/guides/plugins/plugins/api/customer-specific-pricing.md b/guides/development/extensions/plugins/integrations/commercial/customer-specific-pricing.md
similarity index 100%
rename from guides/plugins/plugins/api/customer-specific-pricing.md
rename to guides/development/extensions/plugins/integrations/commercial/customer-specific-pricing.md
diff --git a/guides/development/extensions/plugins/integrations/commercial/index.md b/guides/development/extensions/plugins/integrations/commercial/index.md
new file mode 100644
index 0000000000..0afaf11fe3
--- /dev/null
+++ b/guides/development/extensions/plugins/integrations/commercial/index.md
@@ -0,0 +1,15 @@
+---
+nav:
+ title: Commercial
+ position: 90
+
+---
+
+# Commercial Plugins
+
+The Commercial plugin extends Shopware with advanced enterprise features available as part of the Shopware Commercial plans.
+
+This section documents the API-first features provided by the Commercial plugin and how to integrate them into your systems:
+
+* [Multi-Inventory](./multi-inventory.md)
+* [Customer-specific Pricing](./customer-specific-pricing.md)
diff --git a/guides/plugins/plugins/api/multi-inventory.md b/guides/development/extensions/plugins/integrations/commercial/multi-inventory.md
similarity index 100%
rename from guides/plugins/plugins/api/multi-inventory.md
rename to guides/development/extensions/plugins/integrations/commercial/multi-inventory.md
diff --git a/guides/plugins/plugins/elasticsearch/add-product-entity-extension-to-elasticsearch.md b/guides/development/extensions/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md
similarity index 100%
rename from guides/plugins/plugins/elasticsearch/add-product-entity-extension-to-elasticsearch.md
rename to guides/development/extensions/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md
diff --git a/guides/plugins/plugins/elasticsearch/index.md b/guides/development/extensions/plugins/integrations/elasticsearch/index.md
similarity index 100%
rename from guides/plugins/plugins/elasticsearch/index.md
rename to guides/development/extensions/plugins/integrations/elasticsearch/index.md
diff --git a/guides/development/extensions/plugins/integrations/index.md b/guides/development/extensions/plugins/integrations/index.md
new file mode 100644
index 0000000000..bc16c3ed1d
--- /dev/null
+++ b/guides/development/extensions/plugins/integrations/index.md
@@ -0,0 +1,15 @@
+---
+nav:
+ title: Integrations
+ position: 30
+---
+
+# Integrations
+
+Plugins are commonly used to integrate external systems and infrastructure services into Shopware. Typical scenarios that go beyond basic plugin setup include:
+
+* Infrastructure integrations, including [Redis](./redis) and [Elasticsearch](./elasticsearch)
+* Commercial & API-based integrations, including [customer-specific pricing](./customer-specific-pricing), [multi-inventory](./multi-inventory), and [API](./api)
+* Extended search capabilities, including [adding product entity extensions to Elasticsearch](./add-product-entity-extension-to-elasticsearch)
+
+Use these guides when a plugin needs to connect to external services, extend core infrastructure, or integrate ERP and pricing systems.
diff --git a/guides/plugins/plugins/redis.md b/guides/development/extensions/plugins/integrations/redis.md
similarity index 100%
rename from guides/plugins/plugins/redis.md
rename to guides/development/extensions/plugins/integrations/redis.md
diff --git a/guides/plugins/plugins/plugin-fundamentals/logging.md b/guides/development/extensions/plugins/logging.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/logging.md
rename to guides/development/extensions/plugins/logging.md
diff --git a/guides/development/extensions/plugins/plugin-base-guide.md b/guides/development/extensions/plugins/plugin-base-guide.md
new file mode 100644
index 0000000000..ff6487c50d
--- /dev/null
+++ b/guides/development/extensions/plugins/plugin-base-guide.md
@@ -0,0 +1,44 @@
+---
+nav:
+ title: Plugin Base Guide
+ position: 2
+
+---
+
+# Plugin Base Guide
+
+This guide outlines the typical development flow when creating a Shopware plugin, using the recommended static plugin approach. Core concepts apply to all plugin types. Not every plugin requires all steps.
+
+## Typical Plugin Development Flow
+
+1. [Create the plugin structure](creating-plugins)
+2. [Install and activate the plugin](install-activate)
+3. [Understand the plugin lifecycle](plugin-fundamentals/plugin-lifecycle)
+4. [Add plugin configuration](plugin-fundamentals/add-plugin-configuration)
+5. [Register services and use dependency injection](plugin-fundamentals/dependency-injection)
+6. [Listen to events or decorate services](plugin-fundamentals/listening-to-events)
+7. Extend the platform (either or both):
+ * [Storefront](storefront/index.md)
+ * [Administration](administration/index.md)
+8. [Add database migrations](plugin-fundamentals/database-migrations) (if required)
+9. [Add scheduled tasks or CLI commands](scheduled-task) (if required)
+10. Add configuration (if required)
+ * [npm](using-npm-dependencies)
+ * [Composer](using-composer-dependencies)
+11. [Write tests](testing/index.md)
+ * CI and upgrade safety: Configure [CI](../../testing/ci.md) to run static analysis, tests, and produce reproducible artifacts to avoid upgrade regressions.
+12. Add [diagnostics](logging.md)
+
+## Upgrade readiness
+
+Design plugins so that:
+
+* Migrations are idempotent
+* Lifecycle logic is minimal and predictable
+* Domain logic is encapsulated behind services
+
+Upgrades are easier when the plugin surface area is small and well-structured.
+
+## Getting Started
+
+The first step is to [create the plugin structure](creating-plugins.md).
diff --git a/guides/development/extensions/plugins/plugin-lifecycle.md b/guides/development/extensions/plugins/plugin-lifecycle.md
new file mode 100644
index 0000000000..55c353b9ad
--- /dev/null
+++ b/guides/development/extensions/plugins/plugin-lifecycle.md
@@ -0,0 +1,190 @@
+---
+nav:
+ title: Plugin lifecycle methods
+ position: 3
+
+---
+
+# Plugin Lifecycle Methods
+
+## Overview
+
+Whenever you create a Shopware plugin, you have to extend the `Shopware\Core\Framework\Plugin` class. If you investigate this class, you will see that this class extends `Shopware\Core\Framework\Bundle`, which in return extends the Symfony's `Bundle` class:
+
+```php
+//
+class YourNamespace\PluginName extends
+
+ // plugin lifecycles
+ abstract class Shopware\Core\Framework\Plugin extends
+
+ // adds support for migrations, filesystem, events, themes
+ abstract class Shopware\Core\Framework\Bundle extends
+
+ // Symfony base bundle
+ abstract class Symfony\Component\HttpKernel\Bundle
+```
+
+A Shopware plugin goes through several lifecycle stages:
+
+- Install
+- Activate
+- Deactivate
+- Update
+- Uninstall
+
+| Lifecycle | Description |
+| :--- | :--- |
+| `install()` | Executed on plugin install |
+| `activate()` | Executed **before** plugin activation |
+| `deactivate()` | Executed **before** plugin deactivation |
+| `update()` | Executed on plugin update |
+| `postInstall()` | Executed **after** successful plugin install |
+| `postUpdate()` | Executed **after** successful plugin update |
+| `uninstall()` | Executed on plugin uninstallation |
+
+Each stage allows you to prepare, modify, or clean up your plugin’s integration with the system.
+
+Lifecycle methods are implemented in your base plugin class (`<plugin root>/src/SwagBasicExample.php`), which acts like a bootstrap file, and provide access to the [service container](dependency-injection) via `$this->container`.
+
+## Install
+
+`install()` is executed when the plugin is installed. Use this method to:
+
+- Register entities (e.g., payment methods)
+- Create initial data
+- Prepare system requirements
+
+```php
+// <plugin root>/src/SwagBasicExample
+public function install(InstallContext $installContext): void
+{
+ // Do stuff such as creating a new payment method
+}
+```
+
+The `InstallContext` provides:
+
+* Current plugin version
+* Current Shopware version
+* System `Context`, which provides information about the system (e.g., current language, currency, and permissions)
+* [Plugin migrations](database-migrations)
+* Auto-migration control \(`isAutoMigrate` or `setAutoMigrate` to prevent execution\)
+
+::: info
+
+Avoid creating new business data for your plugin in the `install()` method. Creating fully active entities at this stage, when the plugin isn't active yet, may affect the system before the plugin is actually enabled. A good rule of thumb: Only create data that can be safely activated or deactivated independently—for example, a payment method. You can create the entity during `install()`, but keep it inactive until the `activate()` method runs.
+:::
+
+## Activate
+
+`activate()` is executed once the plugin is activated. You most likely want to do one of the following things here:
+
+* Activate entities that you created in the install method, e.g. such as a payment method
+* Create new entities or data, that you couldn't create in the install method
+
+```php
+// <plugin root>/src/SwagBasicExample
+public function activate(ActivateContext $activateContext): void
+{
+ // Activate entities, such as a new payment method
+ // Or create new entities here, because now your plugin is installed and active for sure
+}
+```
+
+The `ActivateContext` provides the same information as the `InstallContext`.
+
+## Deactivate
+
+The opposite of `activate()` in most respects. It is executed when the plugin is deactivated.
+
+* Deactivate entities created by the `install` method
+* Remove entities that cannot be safely deactivated and that would otherwise interfere with the system if left active while the plugin is inactive.
+
+```php
+// <plugin root>/src/SwagBasicExample
+public function deactivate(DeactivateContext $deactivateContext): void
+{
+ // Deactivate entities, such as a new payment method
+ // Or remove previously created entities
+}
+```
+
+The `DeactivateContext` provides the same information as the `InstallContext`.
+
+## Update
+
+The `update()` method runs when your plugin is updated to a new version. Database changes should be handled via [plugin migrations](database-migrations), rather than inside `update()`, to avoid repeated execution or version checks. However, `update()` is still useful for non-database adjustments, feature toggles, configuration changes, or logic that depends on the previous and new plugin versions.
+
+```php
+// <plugin root>/src/SwagBasicExample
+public function update(UpdateContext $updateContext): void
+{
+ // Update necessary stuff, mostly non-database related
+}
+```
+
+The `UpdateContext` provides the same information as the `InstallContext`, but comes with one additional method. Use `getUpdatePluginVersion()` to retrieve the target version being installed, and `getCurrentPluginVersion()` to retrieve the version currently installed before the update.
+
+::: warning
+Run [CI](../../testing/ci.md) (static analysis, tests, and reproducible artifact) before plugin updates to reduce the risk of upgrade-time failures.
+:::
+
+### PostInstall and PostUpdate methods
+
+Two more lifecycle methods are worth mentioning: `PostUpdate` and `PostInstall`. These are executed **after** a successful install or update. These are useful for actions that should only run once the installation or update process has fully completed.
+
+```php
+// <plugin root>/src/SwagBasicExample
+public function postInstall(InstallContext $installContext): void
+{
+}
+
+public function postUpdate(UpdateContext $updateContext): void
+{
+}
+```
+
+## Uninstall
+
+The opposite of `install()`, this is executed when the plugin is uninstalled. Use it to remove or clean up data created by your plugin.
+
+::: warning
+Do not blindly delete entities your plugin created. For example, if your plugin registered a payment method that was used in real orders, removing it would leave those orders in a broken state. In such cases, it's better to deactivate the entity instead of deleting it. Always consider the impact on existing production data.
+:::
+
+```php
+// <plugin root>/src/SwagBasicExample
+public function uninstall(UninstallContext $uninstallContext): void
+{
+ // Remove or deactivate the data created by the plugin
+}
+```
+
+The `uninstall()` method receives an `UninstallContext`, which provides the same information as the `install` method. Important information is available with the `UninstallContext`, plus the`keepUserData()` flag.
+
+### Keeping user data upon uninstall
+
+When uninstalling a plugin, you can choose whether to remove all associated plugin data. If `keepUserData()` returns `true`, you must not delete persistent data created by your plugin. Respect this flag to avoid unintended data loss.
+
+```php
+// <plugin root>/src/SwagBasicExample
+public function uninstall(UninstallContext $uninstallContext): void
+{
+ parent::uninstall($uninstallContext);
+
+ if ($uninstallContext->keepUserData()) {
+ return;
+ }
+
+ // Remove or deactivate the data created by the plugin
+}
+```
+
+::: info
+Refer to this video on **[Uninstalling a plugin](https://www.youtube.com/watch?v=v9OXrUJzC1I)** when dealing with plugin uninstall routines. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
+:::
+
+## Next steps
+
+Now let's [add plugin configuration](plugin-fundamentals/add-plugin-configuration).
\ No newline at end of file
diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-service.md b/guides/development/extensions/plugins/services/add-custom-service.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/add-custom-service.md
rename to guides/development/extensions/plugins/services/add-custom-service.md
diff --git a/guides/plugins/plugins/plugin-fundamentals/adjusting-service.md b/guides/development/extensions/plugins/services/adjusting-service.md
similarity index 100%
rename from guides/plugins/plugins/plugin-fundamentals/adjusting-service.md
rename to guides/development/extensions/plugins/services/adjusting-service.md
diff --git a/guides/plugins/plugins/plugin-fundamentals/dependency-injection.md b/guides/development/extensions/plugins/services/dependency-injection.md
similarity index 98%
rename from guides/plugins/plugins/plugin-fundamentals/dependency-injection.md
rename to guides/development/extensions/plugins/services/dependency-injection.md
index dd42a95c54..f31efa869d 100644
--- a/guides/plugins/plugins/plugin-fundamentals/dependency-injection.md
+++ b/guides/development/extensions/plugins/services/dependency-injection.md
@@ -1,6 +1,6 @@
---
nav:
- title: Dependency injection
+ title: Dependency Injection
position: 40
---
diff --git a/guides/development/extensions/plugins/services/index.md b/guides/development/extensions/plugins/services/index.md
new file mode 100644
index 0000000000..42f1c2f2c2
--- /dev/null
+++ b/guides/development/extensions/plugins/services/index.md
@@ -0,0 +1,13 @@
+---
+nav:
+ title: Services
+ position: 50
+---
+
+# Services
+
+This section explains how to register, customize and extend services within your plugin:
+
+* [Dependency Injection](./dependency-injection.md)
+* [Add Custom Service](./add-custom-service.md)
+* [Adjusting a Service](./adjusting-service.md)
diff --git a/guides/plugins/plugins/framework/store-api/add-store-api-route.md b/guides/development/extensions/plugins/store-api/add-store-api-route.md
similarity index 100%
rename from guides/plugins/plugins/framework/store-api/add-store-api-route.md
rename to guides/development/extensions/plugins/store-api/add-store-api-route.md
diff --git a/guides/development/extensions/plugins/store-api/index.md b/guides/development/extensions/plugins/store-api/index.md
new file mode 100644
index 0000000000..611a5d3113
--- /dev/null
+++ b/guides/development/extensions/plugins/store-api/index.md
@@ -0,0 +1,34 @@
+---
+nav:
+ title: Store API
+ position: 60
+
+---
+
+# Store API
+
+Use the Store API to add custom endpoints or extend existing ones in plugins. Store API routes are service-based and follow strict architectural conventions to ensure consistency, cacheability, and extensibility.
+
+## Core Principles
+
+Routes:
+
+* Do not implement the Sales Channel API, deprecated as of 6.4.
+* Define Store API controllers as services.
+* Use named routes internally.
+* Each route class or API method requires the attribute: `#[Route(defaults: [\Shopware\Core\PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [\Shopware\Core\Framework\Routing\StoreApiRouteScope::ID]])]`.
+* Response decorators must extend `StoreApiResponse`.
+
+Route design:
+
+* A route represents a single, focused functionality.
+* A route must return a `StoreApiResponse`, to convert to JSON.
+* A route response can only contain one object.
+* Routes may be decorated to extend behavior.
+
+Storefront integration:
+
+* Storefront controllers must not access repositories directly.
+* Controllers must call Store API routes.
+* Page loaders and controllers may call multiple routes.
+* Business logic belongs in Store API routes, not in controllers.
diff --git a/guides/plugins/plugins/framework/store-api/override-existing-route.md b/guides/development/extensions/plugins/store-api/override-existing-route.md
similarity index 100%
rename from guides/plugins/plugins/framework/store-api/override-existing-route.md
rename to guides/development/extensions/plugins/store-api/override-existing-route.md
diff --git a/guides/plugins/plugins/storefront/add-caching-to-custom-controller.md b/guides/development/extensions/plugins/storefront/advanced/add-caching-to-custom-controller.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-caching-to-custom-controller.md
rename to guides/development/extensions/plugins/storefront/advanced/add-caching-to-custom-controller.md
diff --git a/guides/development/extensions/plugins/storefront/advanced/add-cookie-to-manager.md b/guides/development/extensions/plugins/storefront/advanced/add-cookie-to-manager.md
new file mode 100644
index 0000000000..a5dc304041
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/advanced/add-cookie-to-manager.md
@@ -0,0 +1,173 @@
+---
+nav:
+ title: Add cookie to manager
+ position: 160
+
+---
+
+# Add Cookie to Manager
+
+## Overview
+
+Since the GDPR was introduced, every website has to be shipped with some sort of a cookie consent manager. This is also the case for Shopware 6 of course, which comes with a cookie consent manager by default. In this guide you will learn how you can add your own cookies to the cookie consent manager of Shopware 6.
+
+::: info
+For a comprehensive understanding of Shopware's cookie consent system, see the [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management).
+:::
+
+## Prerequisites
+
+This guide is built upon the [Plugin base guide](../plugin-base-guide), so take a look at that first if you're lacking a running plugin. Also, you will need to know how to [create your own service](../plugin-fundamentals/add-custom-service) and [subscribe to an event](../plugin-fundamentals/listening-to-events), so you might want to take a look at those guides as well.
+
+## Extend the cookie consent manager
+
+Adding custom cookies requires you to listen to the `CookieGroupsCollectEvent` and add your custom cookies to the collection.
+
+::: tip
+It is recommended to use an event listener if you're listening to a single event. If you need to react to multiple events, an event subscriber is the better choice.
+:::
+
+### Registering your event listener
+
+Start with creating the `services.xml` and registering your event listener.
+
+```xml
+// <plugin root>/src/Resources/config/services.xml
+<?xml version="1.0" ?>
+
+<container xmlns="http://symfony.com/schema/dic/services"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+ <services>
+ <service id="PluginName\Listener\CookieListener">
+ <tag name="kernel.event_listener" event="Shopware\Storefront\Framework\Cookie\CookieGroupsCollectEvent"/>
+ </service>
+ </services>
+</container>
+```
+
+In the next step we'll create the actual listener class.
+
+### Creating the listener
+
+We need to create a class called `CookieListener` with an `__invoke` method. This method will be executed once the `CookieGroupsCollectEvent` is dispatched.
+
+The event object that is passed to our listener method contains the cookie groups collection, which we can use to add our custom cookies.
+
+::: warning
+Since Shopware 6.7.3.0, cookies use structured objects (`CookieEntry` and `CookieGroup`) instead of arrays for better type safety and consistency. The array format is deprecated.
+:::
+
+Let's have a look at an example:
+
+```php
+// <plugin root>/src/Listener/CookieListener.php
+<?php declare(strict_types=1);
+
+namespace PluginName\Listener;
+
+use Shopware\Storefront\Framework\Cookie\CookieGroupsCollectEvent;
+use Shopware\Core\Framework\Cookie\CookieEntry;
+use Shopware\Core\Framework\Cookie\CookieGroup;
+
+class CookieListener
+{
+ public function __invoke(CookieGroupsCollectEvent $event): void
+ {
+ $cookieGroups = $event->getCookieGroups();
+
+ // Create a single cookie
+ $singleCookie = new CookieEntry(
+ 'cookie.name',
+ 'cookie-key',
+ 'cookie value',
+ 30,
+ 'cookie.description'
+ );
+
+ // Create entries collection for cookie group
+ $groupEntries = [
+ new CookieEntry(
+ 'cookie.first_child_name',
+ 'cookie-key-1',
+ 'cookie value',
+ 30
+ ),
+ new CookieEntry(
+ 'cookie.second_child_name',
+ 'cookie-key-2',
+ 'cookie value',
+ 60
+ )
+ ];
+
+ // Create a cookie group with multiple cookies
+ $cookieGroup = new CookieGroup(
+ 'cookie.group_name',
+ $groupEntries,
+ 'cookie.group_description'
+ );
+
+ $cookieGroups->add($cookieGroup);
+ $cookieGroups->add($singleCookie);
+ }
+}
+```
+
+This will eventually lead to a new group being created, containing two new cookies, as well as a new cookie without a group.
+
+And that's basically it already. After loading your Storefront, you should now see your new cookies and the cookie-group.
+
+## Parameter Reference
+
+For a complete list of available parameters and their types, refer to the source code:
+
+* [`CookieEntry`](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Cookie/Struct/CookieEntry.php) - Individual cookie definition
+* [`CookieGroup`](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Cookie/Struct/CookieGroup.php) - Cookie group definition
+
+::: info
+Cookie groups should not have the `cookie`, `value`, `expiration`, or `isRequired` parameters. These only apply to individual `CookieEntry` objects within the group's `entries`.
+:::
+
+## Migrating from CookieProviderInterface (Shopware 6.7.2 and earlier)
+
+If you are upgrading from an older version, you might have used the `CookieProviderInterface` to add custom cookies. This interface is now deprecated and should be replaced with the `CookieGroupsCollectEvent`.
+
+For backward compatibility, you can still use the `CookieProviderInterface` to provide cookies in the old array syntax. However, it is highly recommended to use the new event-based system to provide the new object structure.
+
+## Cookie Configuration Changes and Re-Consent
+
+Since Shopware 6.7.3.0, cookie configurations include a hash that tracks changes. When you modify cookie configurations through your plugin (add/remove/change cookies), the hash changes automatically, triggering a re-consent flow for users.
+
+This helps maintain transparency by re-prompting users when cookie handling changes, supporting GDPR compliance requirements. The hash is automatically calculated from all cookie configurations provided by the `CookieProvider`.
+
+::: info
+**Hash Storage Format**: The configuration hash is stored in the browser's `cookie-config-hash` cookie as an object where the language ID is the key and the cookie hash is the value, for example: `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`. This enables per-language consent tracking. Since cookies are stored per domain by the browser, installations using different domains for different languages don't encounter tracking conflicts. The language ID is specifically used when multiple languages are served from the same domain.
+:::
+
+::: info
+While this feature helps with GDPR compliance, shop owners are responsible for ensuring their overall cookie usage, privacy policies, and data handling practices comply with GDPR and other applicable regulations.
+:::
+
+### How it works
+
+1. Your plugin adds/modifies cookies via the `CookieGroupsCollectEvent`
+2. Shopware calculates a hash of the entire cookie configuration
+3. The hash is stored in the user's browser as an object where the language ID is the key and the hash is the value (e.g., `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`)
+4. On the next visit, if the hash differs for the current language, the consent banner appears again
+5. Users are informed about changes and can make new choices
+
+This automatic re-consent mechanism helps shop owners maintain transparency about cookie changes.
+
+::: info
+The configuration hash is exposed via the Store API endpoint `/store-api/cookie/groups`. For API documentation, see [Fetch all cookie groups](https://shopware.stoplight.io/docs/store-api/f9c70be044a15-fetch-all-cookie-groups).
+:::
+
+## Video Platform Cookies
+
+YouTube and Vimeo cookies are now handled separately in Shopware's cookie management. If you're adding video functionality to your plugin, ensure you register the appropriate cookie for your video platform or reuse existing ones.
+
+## Next steps
+
+Those changes will mainly just show your new cookies in the cookie consent manager, but without much function. Head over to our guide about [Reacting to cookie consent changes](reacting-to-cookie-consent-changes) to see how you can implement your custom logic once your cookie got accepted or declined.
diff --git a/guides/development/extensions/plugins/storefront/advanced/index.md b/guides/development/extensions/plugins/storefront/advanced/index.md
new file mode 100644
index 0000000000..b6fd475ba3
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/advanced/index.md
@@ -0,0 +1,16 @@
+---
+nav:
+ title: Advanced
+ position: 100
+---
+
+# Advanced Storefront Customization
+
+This section covers advanced topics for extending and customizing the Storefront in plugins.
+
+These guides focus on performance optimization, caching behavior, cookie consent integration, and JavaScript plugin control:
+
+* [Add caching to custom controller](./add-caching-to-custom-controller.md)
+* [Add cookie to manager](./add-cookie-to-manager.md)
+* [Reacting to cookie consent changes](./reacting-to-cookie-consent-changes.md)
+* [Remove Javascript plugin](./remove-unnecessary-js-plugin.md)
diff --git a/guides/plugins/plugins/storefront/reacting-to-cookie-consent-changes.md b/guides/development/extensions/plugins/storefront/advanced/reacting-to-cookie-consent-changes.md
similarity index 100%
rename from guides/plugins/plugins/storefront/reacting-to-cookie-consent-changes.md
rename to guides/development/extensions/plugins/storefront/advanced/reacting-to-cookie-consent-changes.md
diff --git a/guides/plugins/plugins/storefront/remove-unnecessary-js-plugin.md b/guides/development/extensions/plugins/storefront/advanced/remove-unnecessary-js-plugin.md
similarity index 100%
rename from guides/plugins/plugins/storefront/remove-unnecessary-js-plugin.md
rename to guides/development/extensions/plugins/storefront/advanced/remove-unnecessary-js-plugin.md
diff --git a/guides/plugins/plugins/storefront/add-custom-controller.md b/guides/development/extensions/plugins/storefront/controllers/add-custom-controller.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-controller.md
rename to guides/development/extensions/plugins/storefront/controllers/add-custom-controller.md
diff --git a/guides/plugins/plugins/storefront/add-custom-page.md b/guides/development/extensions/plugins/storefront/controllers/add-custom-page.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-page.md
rename to guides/development/extensions/plugins/storefront/controllers/add-custom-page.md
diff --git a/guides/plugins/plugins/storefront/add-custom-pagelet.md b/guides/development/extensions/plugins/storefront/controllers/add-custom-pagelet.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-pagelet.md
rename to guides/development/extensions/plugins/storefront/controllers/add-custom-pagelet.md
diff --git a/guides/plugins/plugins/storefront/add-data-to-storefront-page.md b/guides/development/extensions/plugins/storefront/controllers/add-data-to-storefront-page.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-data-to-storefront-page.md
rename to guides/development/extensions/plugins/storefront/controllers/add-data-to-storefront-page.md
diff --git a/guides/plugins/plugins/storefront/add-dynamic-content-via-ajax-calls.md b/guides/development/extensions/plugins/storefront/controllers/add-dynamic-content-via-ajax-calls.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-dynamic-content-via-ajax-calls.md
rename to guides/development/extensions/plugins/storefront/controllers/add-dynamic-content-via-ajax-calls.md
diff --git a/guides/development/extensions/plugins/storefront/controllers/index.md b/guides/development/extensions/plugins/storefront/controllers/index.md
new file mode 100644
index 0000000000..a9d47f42ba
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/controllers/index.md
@@ -0,0 +1,53 @@
+---
+nav:
+ title: Storefront Controllers
+ position: 140
+
+---
+
+# Storefront Controllers
+
+Storefront controllers define HTTP endpoints for the storefront scope.
+They coordinate page rendering and delegate business logic to Store API routes or page loaders.
+
+## Core Principles
+
+Structure:
+
+* A Storefront controller must extend `\Shopware\Storefront\Controller\StorefrontController`.
+* The class must define the storefront route scope: `#[Route(defaults: [\Shopware\Core\PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [\Shopware\Storefront\Framework\Routing\StorefrontRouteScope::ID]])]`.
+* Each action requires a `#Route` attribute.
+* Route names should use the `frontend` prefix (unless explicitly configured otherwise).
+* Each route must define the corresponding HTTP Method: GET, POST, DELETE, PATCH.
+* Each action must declare a return type.
+* The function name should be concise.
+* Dependencies must be injected via the class constructor and defined in the DI-container service definition.
+* Dependent services must be assigned to a private class property.
+
+Responsibilities:
+
+* A controller represents a single entry point.
+* A route must have a single purpose.
+* Controllers must not contain business logic.
+* Business logic belongs in Store API routes.
+* Controllers must not access repositories directly.
+
+Data Loading:
+
+* Read operations must delegate to Store API routes or page loaders.
+* Routes that render full storefront pages should use a page loader class to load all corresponding data.
+* Page loaders may call multiple Store API routes.
+
+Write Operations:
+
+* must call a corresponding Store API route.
+* Use the `createActionResponse()` function for redirects or forwards.
+
+Caching:
+
+* Pages with identical data for all users should use the `_httpCache` attribute.
+
+## Additional guidelines
+
+* Use Symfony flash bags for error reporting.
+* Storefront functionality should be available inside the Store API too.
diff --git a/guides/plugins/plugins/storefront/add-custom-captcha.md b/guides/development/extensions/plugins/storefront/howto/add-custom-captcha.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-captcha.md
rename to guides/development/extensions/plugins/storefront/howto/add-custom-captcha.md
diff --git a/guides/plugins/plugins/storefront/add-custom-sorting-product-listing.md b/guides/development/extensions/plugins/storefront/howto/add-custom-sorting-product-listing.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-sorting-product-listing.md
rename to guides/development/extensions/plugins/storefront/howto/add-custom-sorting-product-listing.md
diff --git a/guides/plugins/plugins/storefront/add-listing-filters.md b/guides/development/extensions/plugins/storefront/howto/add-listing-filters.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-listing-filters.md
rename to guides/development/extensions/plugins/storefront/howto/add-listing-filters.md
diff --git a/guides/development/extensions/plugins/storefront/howto/index.md b/guides/development/extensions/plugins/storefront/howto/index.md
new file mode 100644
index 0000000000..5d8867e41e
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/howto/index.md
@@ -0,0 +1,18 @@
+---
+nav:
+ title: How-To Guides
+ position: 300
+---
+
+# How-To Guides
+
+This section contains practical guides for implementing common customization and extension scenarios in the Storefront:
+
+* [Add custom captcha](./add-custom-captcha.md)
+* [Add custom sorting for product listing](./add-custom-sorting-product-listing.md)
+* [Add custom listing filters](./add-listing-filters.md)
+* [Working with media and thumbnails](./use-media-thumbnails.md)
+* [Add custom field in the Storefront](./using-custom-fields-storefront.md)
+* [Using a modal window](./using-a-modal-window.md)
+* [Using the datepicker plugin](./using-the-datepicker-plugin.md)
+* [Use nested line items](./use-nested-line-items.md)
diff --git a/guides/plugins/plugins/storefront/use-media-thumbnails.md b/guides/development/extensions/plugins/storefront/howto/use-media-thumbnails.md
similarity index 100%
rename from guides/plugins/plugins/storefront/use-media-thumbnails.md
rename to guides/development/extensions/plugins/storefront/howto/use-media-thumbnails.md
diff --git a/guides/plugins/plugins/storefront/use-nested-line-items.md b/guides/development/extensions/plugins/storefront/howto/use-nested-line-items.md
similarity index 100%
rename from guides/plugins/plugins/storefront/use-nested-line-items.md
rename to guides/development/extensions/plugins/storefront/howto/use-nested-line-items.md
diff --git a/guides/plugins/plugins/storefront/using-a-modal-window.md b/guides/development/extensions/plugins/storefront/howto/using-a-modal-window.md
similarity index 100%
rename from guides/plugins/plugins/storefront/using-a-modal-window.md
rename to guides/development/extensions/plugins/storefront/howto/using-a-modal-window.md
diff --git a/guides/plugins/plugins/storefront/using-custom-fields-storefront.md b/guides/development/extensions/plugins/storefront/howto/using-custom-fields-storefront.md
similarity index 100%
rename from guides/plugins/plugins/storefront/using-custom-fields-storefront.md
rename to guides/development/extensions/plugins/storefront/howto/using-custom-fields-storefront.md
diff --git a/guides/plugins/plugins/storefront/using-the-datepicker-plugin.md b/guides/development/extensions/plugins/storefront/howto/using-the-datepicker-plugin.md
similarity index 100%
rename from guides/plugins/plugins/storefront/using-the-datepicker-plugin.md
rename to guides/development/extensions/plugins/storefront/howto/using-the-datepicker-plugin.md
diff --git a/guides/development/extensions/plugins/storefront/index.md b/guides/development/extensions/plugins/storefront/index.md
new file mode 100644
index 0000000000..76a7ffba69
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/index.md
@@ -0,0 +1,99 @@
+---
+nav:
+ title: Storefront
+ position: 70
+
+---
+
+# Storefront
+
+The [Storefront](https://developer.shopware.com/docs/concepts/framework/architecture/storefront-concept.html) is the customer-facing layer of Shopware. When building a plugin, you extend the Storefront to:
+
+* Add new pages or endpoints
+* Modify templates and layouts
+* Inject dynamic data
+* Add JavaScript behavior
+* Customize styling and assets
+
+This section follows a practical development workflow and mirrors the folder structure inside `/storefront`.
+
+## How to use this section
+
+Most Storefront customizations follow this sequence:
+
+1. Add or extend a controller
+2. Render or override a template
+3. Inject data into the page
+4. Enhance behavior with JavaScript
+5. Apply styling and assets
+
+Start with the `/controllers` folder and move downward as needed.
+
+## Section structure
+
+### Controllers
+
+Create new routes and pages, or extend existing ones.
+
+* [Add custom controller](controllers/add-custom-controller.md)
+* [Add custom page](controllers/add-custom-page.md)
+* [Add data to a storefront page](controllers/add-data-to-storefront-page.md)
+
+### Templates
+
+Override or extend Twig templates and layout blocks.
+
+* [Customize templates](templates/customize-templates.md)
+* [Customize header & footer](templates/customize-header-footer.md)
+* [Add Twig function](templates/add-custom-twig-function.md)
+
+### JavaScript
+
+Extend or override frontend behavior.
+
+* [Add custom JavaScript](javascript/add-custom-javascript.md)
+* [Override existing JavaScript](javascript/override-existing-javascript.md)
+* [React to JavaScript events](javascript/reacting-to-javascript-events.md)
+* [Fetch data dynamically](javascript/fetching-data-with-javascript.md)
+* [Add JavaScript as script tag](javascript/add-javascript-as-script-tag.md)
+
+### Styling and assets
+
+Control appearance and resources.
+
+* [Add custom styling](styling/add-custom-styling.md)
+* [Add custom assets](styling/add-custom-assets.md)
+* [Add icons](styling/add-icons.md)
+* [Add translations](styling/add-translations.md)
+* [Add SCSS variables](styling/add-scss-variables.md)
+* [Add SCSS variables via subscriber](styling/add-scss-variables-via-subscriber.md)
+
+## Advanced
+
+Infrastructure and optimization topics.
+
+* [Add caching to custom controller](advanced/add-caching-to-custom-controller.md)
+* [React to cookie consent changes](advanced/reacting-to-cookie-consent-changes.md)
+* [Remove unnecessary JS plugin](advanced/remove-unnecessary-js-plugin.md)
+* [Add cookie to manager](advanced/add-cookie-to-manager.md)
+
+## How-to
+
+Feature-specific examples and focused use-cases.
+
+* [Custom captcha](howto/add-custom-captcha.md)
+* [Listing filters](howto/add-listing-filters.md)
+* [Custom sorting for product listing](howto/add-custom-sorting-product-listing.md)
+* [Use nested line items](howto/use-nested-line-items.md)
+* [Using a modal window](howto/using-a-modal-window.md)
+* [Using custom fields in storefront](howto/using-custom-fields-storefront.md)
+* [Use media thumbnails](howto/use-media-thumbnails.md)
+* [Using the datepicker plugin](howto/using-the-datepicker-plugin.md)
+
+## Build and watch
+
+After modifying Storefront code, [rebuild your assets](using-watchers.html).
+
+## Headless storefront
+
+[Visit these pages](https://developer.shopware.com/frontends/) if you are building a headless frontend instead of extending the default Storefront.
diff --git a/guides/plugins/plugins/storefront/add-custom-javascript.md b/guides/development/extensions/plugins/storefront/javascript/add-custom-javascript.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-javascript.md
rename to guides/development/extensions/plugins/storefront/javascript/add-custom-javascript.md
diff --git a/guides/plugins/plugins/storefront/add-javascript-as-script-tag.md b/guides/development/extensions/plugins/storefront/javascript/add-javascript-as-script-tag.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-javascript-as-script-tag.md
rename to guides/development/extensions/plugins/storefront/javascript/add-javascript-as-script-tag.md
diff --git a/guides/plugins/plugins/storefront/fetching-data-with-javascript.md b/guides/development/extensions/plugins/storefront/javascript/fetching-data-with-javascript.md
similarity index 100%
rename from guides/plugins/plugins/storefront/fetching-data-with-javascript.md
rename to guides/development/extensions/plugins/storefront/javascript/fetching-data-with-javascript.md
diff --git a/guides/development/extensions/plugins/storefront/javascript/index.md b/guides/development/extensions/plugins/storefront/javascript/index.md
new file mode 100644
index 0000000000..8a660a406d
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/javascript/index.md
@@ -0,0 +1,19 @@
+---
+nav:
+ title: JavaScript
+ position: 40
+---
+
+# Storefront JavaScript
+
+This section explains how to extend and customize the Storefront using JavaScript plugins. It covers creating custom plugins, overriding existing functionality, reacting to events, loading external scripts, and interacting with the Store API.
+
+* [Add custom Javascript](./add-custom-javascript.md)
+* [Add Javascript as script tag](./add-javascript-as-script-tag.md)
+* [Fetching data with Javascript](./fetching-data-with-javascript.md)
+* [Override existing Javascript](./override-existing-javascript.md)
+* [Reacting to javascript events](./reacting-to-javascript-events.md)
+
+## Reference
+
+* [Storefront plugins and helper](./plugin-reference.md)
diff --git a/guides/plugins/plugins/storefront/override-existing-javascript.md b/guides/development/extensions/plugins/storefront/javascript/override-existing-javascript.md
similarity index 100%
rename from guides/plugins/plugins/storefront/override-existing-javascript.md
rename to guides/development/extensions/plugins/storefront/javascript/override-existing-javascript.md
diff --git a/resources/references/storefront-reference/plugin-reference.md b/guides/development/extensions/plugins/storefront/javascript/plugin-reference.md
similarity index 99%
rename from resources/references/storefront-reference/plugin-reference.md
rename to guides/development/extensions/plugins/storefront/javascript/plugin-reference.md
index 224681ef53..5ec54b95b3 100644
--- a/resources/references/storefront-reference/plugin-reference.md
+++ b/guides/development/extensions/plugins/storefront/javascript/plugin-reference.md
@@ -7,7 +7,7 @@ nav:
# Storefront plugins and helper
-This is a list of available javascript plugins and helpers that can be used and extended.
+This is a list of available JavaScript plugins and helpers that can be used and extended.
## Plugins
diff --git a/guides/plugins/plugins/storefront/reacting-to-javascript-events.md b/guides/development/extensions/plugins/storefront/javascript/reacting-to-javascript-events.md
similarity index 100%
rename from guides/plugins/plugins/storefront/reacting-to-javascript-events.md
rename to guides/development/extensions/plugins/storefront/javascript/reacting-to-javascript-events.md
diff --git a/guides/plugins/plugins/storefront/add-custom-assets.md b/guides/development/extensions/plugins/storefront/styling/add-custom-assets.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-assets.md
rename to guides/development/extensions/plugins/storefront/styling/add-custom-assets.md
diff --git a/guides/plugins/plugins/storefront/add-custom-styling.md b/guides/development/extensions/plugins/storefront/styling/add-custom-styling.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-styling.md
rename to guides/development/extensions/plugins/storefront/styling/add-custom-styling.md
diff --git a/guides/plugins/plugins/storefront/add-icons.md b/guides/development/extensions/plugins/storefront/styling/add-icons.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-icons.md
rename to guides/development/extensions/plugins/storefront/styling/add-icons.md
diff --git a/guides/plugins/plugins/storefront/add-scss-variables-via-subscriber.md b/guides/development/extensions/plugins/storefront/styling/add-scss-variables-via-subscriber.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-scss-variables-via-subscriber.md
rename to guides/development/extensions/plugins/storefront/styling/add-scss-variables-via-subscriber.md
diff --git a/guides/plugins/plugins/storefront/add-scss-variables.md b/guides/development/extensions/plugins/storefront/styling/add-scss-variables.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-scss-variables.md
rename to guides/development/extensions/plugins/storefront/styling/add-scss-variables.md
diff --git a/guides/plugins/plugins/storefront/add-translations.md b/guides/development/extensions/plugins/storefront/styling/add-translations.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-translations.md
rename to guides/development/extensions/plugins/storefront/styling/add-translations.md
diff --git a/guides/development/extensions/plugins/storefront/styling/index.md b/guides/development/extensions/plugins/storefront/styling/index.md
new file mode 100644
index 0000000000..51927d0f5d
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/styling/index.md
@@ -0,0 +1,16 @@
+---
+nav:
+ title: Styling
+ position: 30
+---
+
+# Storefront Styling
+
+This section explains how to customize the visual appearance of the Storefront in plugins.
+
+* [Add custom styling](./add-custom-styling.md)
+* [Add custom assets](./add-custom-assets.md)
+* [Add custom icons](./add-icons.md)
+* [Add SCSS variables](./add-scss-variables.md)
+* [Add SCSS variables via Subscriber](./add-scss-variables-via-subscriber.md)
+* [Add translations](./add-translations.md)
diff --git a/guides/plugins/plugins/storefront/add-custom-twig-function.md b/guides/development/extensions/plugins/storefront/templates/add-custom-twig-function.md
similarity index 100%
rename from guides/plugins/plugins/storefront/add-custom-twig-function.md
rename to guides/development/extensions/plugins/storefront/templates/add-custom-twig-function.md
diff --git a/guides/plugins/plugins/storefront/customize-header-footer.md b/guides/development/extensions/plugins/storefront/templates/customize-header-footer.md
similarity index 100%
rename from guides/plugins/plugins/storefront/customize-header-footer.md
rename to guides/development/extensions/plugins/storefront/templates/customize-header-footer.md
diff --git a/guides/plugins/plugins/storefront/customize-templates.md b/guides/development/extensions/plugins/storefront/templates/customize-templates.md
similarity index 100%
rename from guides/plugins/plugins/storefront/customize-templates.md
rename to guides/development/extensions/plugins/storefront/templates/customize-templates.md
diff --git a/guides/development/extensions/plugins/storefront/templates/index.md b/guides/development/extensions/plugins/storefront/templates/index.md
new file mode 100644
index 0000000000..d2fc0864f8
--- /dev/null
+++ b/guides/development/extensions/plugins/storefront/templates/index.md
@@ -0,0 +1,17 @@
+---
+nav:
+ title: Templates
+ position: 20
+---
+
+# Storefront Templates
+
+This section explains how to customize and extend Storefront templates in plugins.
+
+* [Customize templates](./customize-templates.md)
+* [Customize Header/Footer](./customize-header-footer.md)
+* [Add custom Twig functions](./add-custom-twig-function.md)
+
+## Reference
+
+* [Shopware's Twig functions](./twig-function-reference.md)
diff --git a/resources/references/storefront-reference/twig-function-reference.md b/guides/development/extensions/plugins/storefront/templates/twig-function-reference.md
similarity index 99%
rename from resources/references/storefront-reference/twig-function-reference.md
rename to guides/development/extensions/plugins/storefront/templates/twig-function-reference.md
index cba2bd9f90..df615d6b25 100644
--- a/resources/references/storefront-reference/twig-function-reference.md
+++ b/guides/development/extensions/plugins/storefront/templates/twig-function-reference.md
@@ -5,7 +5,7 @@ nav:
---
-# Shopware's twig functions
+# Shopware's Twig Functions
In Shopware, Twig's functionality is extended with custom tags, functions, filters, and extensions.
diff --git a/guides/plugins/plugins/bundle.md b/guides/development/extensions/plugins/symfony-bundles.md
similarity index 52%
rename from guides/plugins/plugins/bundle.md
rename to guides/development/extensions/plugins/symfony-bundles.md
index d1ec4876b2..dca02eaf10 100644
--- a/guides/plugins/plugins/bundle.md
+++ b/guides/development/extensions/plugins/symfony-bundles.md
@@ -1,19 +1,48 @@
---
nav:
- title: Bundle
+ title: Symfony Bundles
position: 20
---
-# Bundle
+# Using Symfony Bundles Instead of Plugins
-Plugins are based on the Symfony bundle concept, but offer additional features like lifecycle events and the ability to be managed in the Shopware administration.
-This is maybe unwanted in some cases, like project critical customizations which should not be managed via the Shopware administration.
-In this case, you can use a Symfony bundle instead of a plugin.
+This guide handles some basic concepts of Shopware plugins covered in our [Plugin base guide](plugin-base-guide).
-## Project Structure
+::: info
+Check out our [Shopware Toolbox PHPStorm extension](../../../resources/tooling/ide/shopware-toolbox) with useful features like autocompletion, code generation or guideline checks.
+:::
-Here's how a typical Shopware 6 project structure looks like when using bundles:
+You might use a Symfony bundle instead of a plugin when:
+
+* You do not need a plugin lifecycle
+* You do not want Administration management
+* You are building project-level customization
+* You want pure Symfony integration
+
+## How Plugins extend bundles
+
+Shopware plugins extend Symfony bundles and add:
+
+* Plugin lifecycle (install, update, activate, uninstall)
+* Automatic migration handling
+* Asset building integration
+* Administration management
+
+Class hierarchy: Plugin → Shopware\Bundle → Symfony\Bundle
+
+## When to use a bundle
+
+Use a pure Symfony bundle when:
+
+* You are customizing a single project
+* You want no plugin lifecycle
+* You manage everything via Composer
+* You do not distribute the extension
+
+## Project structure
+
+Here's how a typical Shopware 6 project structure looks when bundles are used:
```text
project-root/
@@ -52,18 +81,14 @@ project-root/
The Bundle is typically placed in the `src/` folder of your project, which is the standard location for custom code in a Shopware project. You still will need to register the bundle in the `config/bundles.php` file of your project.
-## Choosing the right Bundle class
+## Choosing the right bundle class
There are two Bundle classes you can choose from:
-- `Shopware\Core\Framework\Bundle`
-- `Symfony\Component\HttpKernel\Bundle\Bundle`
-
-The first one is the Shopware bundle class and the second one is the Symfony bundle class.
-The Shopware bundle class extends the Symfony bundle class, but offers additional features like acting as theme, bringing JavaScript/CSS files, Migrations, etc.
-If you don't need these features, you can use the Symfony bundle class instead.
+* `Shopware\Core\Framework\Bundle`: the Shopware bundle class, which extends the Symfony bundle class with additional features like acting as theme, bringing JavaScript/CSS files, and migrations
+* `Symfony\Component\HttpKernel\Bundle\Bundle`: the Symfony bundle class, which you can use if you don't need additional features
-## Creating a Bundle
+## Creating a bundle
By default, The namespace `App\` is registered to the `src` folder in any Shopware project to be used for customizations. We recommend using this namespace, if you like to change the project structure, you can change the `App\` namespace in the `composer.json` file of your project.
@@ -89,11 +114,9 @@ App\YourBundleName\YourBundleName::class => ['all' => true],
//...
```
-## Adding services, twig templates, routes, theme, etc
+## Adding services, Twig templates, routes, and themes
-You can add services, twig templates, routes, etc. to your bundle like you would do in a plugin.
-Just create `Resources/config/services.xml` and `Resources/config/routes.xml` files or `Resources/views` for twig templates.
-The bundle will be automatically detected and the files will be loaded.
+You can add services, twig templates, routes, etc. to your bundle like you would do in a plugin. Just create `Resources/config/services.xml` and `Resources/config/routes.xml` files or `Resources/views` for twig templates. The bundle will be automatically detected and the files will be loaded.
To mark your bundle as a theme, it's enough to implement the `Shopware\Core\Framework\ThemeInterface` interface in your bundle class.
This will automatically register your bundle as a theme and make it available in the Shopware administration.
@@ -101,8 +124,7 @@ You can also add a `theme.json` file to define the theme configuration like [des
## Adding migrations
-Migrations are not automatically detected in bundles.
-To enable migrations, you need to overwrite the `build` method in your bundle class like this:
+Migrations are not automatically detected in bundles. To enable migrations, overwrite the `build` method in your bundle class:
```php
// <project root>/src/YourBundleName.php
@@ -139,11 +161,9 @@ deployment:
bin/console database:migrate <BundleName> --all
```
-## Integration into Shopware-CLI
+## Integration into Shopware CLI
-Shopware-CLI cannot detect bundles automatically, therefore the assets of the bundles are not built automatically.
-You will need to adjust the `composer.json` file of your project to specify the path to the bundle.
-This is done by adding the `extra` section to the `composer.json` file:
+The Shopware CLI cannot detect bundles automatically, therefore the assets of the bundles are not built automatically. You will need to adjust your project's `composer.json` file to specify the path to the bundle. Do this by adding the `extra` section to the `composer.json` file:
```json
{
@@ -157,4 +177,20 @@ This is done by adding the `extra` section to the `composer.json` file:
}
```
-This will tell Shopware-CLI where the bundle is located and what the name of the bundle is.
+This will tell Shopware CLI where the bundle is located and its name.
+
+## Next steps
+
+Now that you know about the differences between a Symfony bundle and a Shopware plugin, you might also want to have a look into the following Symfony-specific topics and how they are integrated in Shopware 6:
+
+* [Dependency Injection](plugin-fundamentals/dependency-injection)
+* [Listening to events](plugin-fundamentals/listening-to-events)
+
+::: info
+Here are some useful videos explaining:
+
+* **[Bundle Methods in a plugin](https://www.youtube.com/watch?v=cUXcDwQwmPk)**
+* **[Symfony services in Shopware 6](https://www.youtube.com/watch?v=l5QJ8EtilaY)**
+
+Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
+:::
diff --git a/guides/plugins/themes/add-assets-to-theme.md b/guides/development/extensions/themes/assets/add-assets-to-theme.md
similarity index 100%
rename from guides/plugins/themes/add-assets-to-theme.md
rename to guides/development/extensions/themes/assets/add-assets-to-theme.md
diff --git a/guides/plugins/themes/add-icons.md b/guides/development/extensions/themes/assets/add-icons.md
similarity index 100%
rename from guides/plugins/themes/add-icons.md
rename to guides/development/extensions/themes/assets/add-icons.md
diff --git a/guides/development/extensions/themes/assets/index.md b/guides/development/extensions/themes/assets/index.md
new file mode 100644
index 0000000000..82639e15da
--- /dev/null
+++ b/guides/development/extensions/themes/assets/index.md
@@ -0,0 +1,14 @@
+---
+nav:
+ title: Assets
+ position: 30
+---
+
+# Theme Assets
+
+This section explains how to work with assets in a Shopware theme.
+
+It covers adding custom assets such as images, fonts, and icon packs, and how to reference them in Twig and SCSS.
+
+* [Add assets to a Theme](./add-assets-to-theme.md)
+* [Add custom icons](./add-icons.md)
diff --git a/guides/development/extensions/themes/configuration/index.md b/guides/development/extensions/themes/configuration/index.md
new file mode 100644
index 0000000000..6b2bd9a0b6
--- /dev/null
+++ b/guides/development/extensions/themes/configuration/index.md
@@ -0,0 +1,16 @@
+---
+nav:
+ title: Configuration
+ position: 40
+---
+
+# Theme Configuration
+
+This section explains how to configure themes in Shopware.
+
+It covers the structure of `theme.json`, configurable theme fields in the Administration, and how to use configuration inheritance between themes.
+
+## Guides
+
+* [Theme configuration](./theme-configuration.md)
+* [Theme inheritance configuration](./theme-inheritance-configuration.md)
diff --git a/guides/plugins/themes/theme-configuration.md b/guides/development/extensions/themes/configuration/theme-configuration.md
similarity index 100%
rename from guides/plugins/themes/theme-configuration.md
rename to guides/development/extensions/themes/configuration/theme-configuration.md
diff --git a/guides/plugins/themes/theme-inheritance-configuration.md b/guides/development/extensions/themes/configuration/theme-inheritance-configuration.md
similarity index 100%
rename from guides/plugins/themes/theme-inheritance-configuration.md
rename to guides/development/extensions/themes/configuration/theme-inheritance-configuration.md
diff --git a/guides/plugins/themes/create-a-theme.md b/guides/development/extensions/themes/create-a-theme.md
similarity index 58%
rename from guides/plugins/themes/create-a-theme.md
rename to guides/development/extensions/themes/create-a-theme.md
index 0be91731d6..a98fb14645 100644
--- a/guides/plugins/themes/create-a-theme.md
+++ b/guides/development/extensions/themes/create-a-theme.md
@@ -5,53 +5,48 @@ nav:
---
-# Create a First Theme
+# Create Your First Theme
## Overview
-This guide will show you how to create a theme from scratch. You will also learn how to install and activate your theme.
+This guide will show you how to create, install, and activate a custom Shopware 6 theme.
## Prerequisites
-All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line.
+All you need:
-## Create your first plugin theme
+- Running Shopware 6 instance
+- Full file system and CLI access
-Let's get started with creating your plugin by finding a proper name for it.
+## Name your plugin theme
-### Name your plugin theme
-
-First, you need to find a name for your theme. We're talking about a technical name here, so it needs to describe your theme appearance as short as possible, written in UpperCamelCase. To prevent issues with duplicated theme names, you should add a shorthand prefix for your company.
-Shopware uses "Swag" as a prefix for that case.
-For this example guide we'll use the theme name **SwagBasicExampleTheme.**
-
-::: info
-Notice: The name of a theme must begin with a capital letter too!
-:::
+Use **UpperCamelCase**, which means that your theme name must begin with a capital letter too. Whenever possible, begin it with a company prefix to avoid duplicate names (e.g., `SwagBasicExampleTheme`). Choose a name that describes your theme appearance as succinctly and clearly as possible.
### Create a plugin-based theme
-Now that you've found your name, it's time to actually create your plugin.
-
-Open your terminal and run the following command to create a new theme
+Now it's time to create your plugin, running this command in your terminal:
```bash
bin/console theme:create SwagBasicExampleTheme
+```
-# you should get an output like this:
+You should get an output like this:
+```bash
Creating theme structure under .../development/custom/plugins/SwagBasicExampleTheme
```
-After your theme was created successfully Shopware has to know that it now exists. You have to refresh the plugin list by running the following command.
+Shopware needs to know that your new plugin exists. Refresh the plugin list by running:
```bash
bin/console plugin:refresh
+```
-# you should get an output like this
+You should get an output like this, which indicates that Shopware recognises your plugin theme:
[OK] Plugin list refreshed
+```bash
Shopware Plugin Service
=======================
@@ -64,12 +59,17 @@ Shopware Plugin Service
1 plugins, 0 installed, 0 active , 0 upgradeable
```
-Now Shopware recognises your plugin theme. The next step is the installation and activation of your theme. Run the following command in terminal.
+### Activating your plugin
+
+The next command installs and activates your theme:
```bash
-# run this command to install and activate your plugin
bin/console plugin:install --activate SwagBasicExampleTheme
+```
+
+You should see output like this, indicating success:
+```bash
Shopware Plugin Lifecycle Service
=================================
@@ -81,17 +81,17 @@ Shopware Plugin Lifecycle Service
[OK] Installed 1 plugin(s).
```
-Your theme was successfully installed and activated.
+### Assign to a sales channel
-The last thing we need to do to work with the theme is to assign it to a sales channel. You can do that by running the `theme:change` command in the terminal and follow the instructions.
+The final step in this guide is to assign your theme to a sales channel, which changes default Storefront theme. Run:
```bash
-# run this to change the current Storefront theme
$ bin/console theme:change
+```
-# you will get an interactive prompt to change the
-# current theme of the Storefront like this
+You will see an interactive prompt like this:
+```bash
Please select a sales channel:
[0] Storefront | 64bbbe810d824c339a6c191779b2c205
[1] Headless | 98432def39fc4624b33213a56b8c944d
@@ -106,14 +106,11 @@ Set "SwagBasicExampleTheme" as new theme for sales channel "Storefront"
Compiling theme 13e0a4a46af547479b1347617926995b for sales channel SwagBasicExampleTheme
```
-At first, we have to select a sales channel. The obvious choice here is the 'Storefront'. Afterwards enter the number for our theme.
-
-Now your theme is fully installed, and you can start your customization.
+First, select `Storefront` as the sales channel. Then enter your theme's number. This fully installs your theme, and you can start your customization.
### Directory structure of a theme
```bash
-# structure of a plugin-based theme
├── composer.json
└── src
├── Resources
@@ -134,6 +131,33 @@ Now your theme is fully installed, and you can start your customization.
└── SwagBasicExampleTheme.php
```
+## Troubleshooting
+
+Theme not visible?
+
+```bash
+bin/console plugin:refresh
+bin/console plugin:list
+```
+
+Theme not applied?
+
+```bash
+bin/console theme:change
+bin/console theme:compile
+```
+
+Errors or no changes?
+
+```bash
+bin/console cache:clear
+```
+
+Also:
+
+- Check `var/log/`
+- Verify file permissions in `custom/plugins/`
+
## Next steps
Now that you have created your own theme, the next step is to learn how to make settings and adjustments.
diff --git a/guides/development/extensions/themes/index.md b/guides/development/extensions/themes/index.md
new file mode 100644
index 0000000000..d5c12824c4
--- /dev/null
+++ b/guides/development/extensions/themes/index.md
@@ -0,0 +1,16 @@
+---
+nav:
+ title: Themes
+ position: 30
+---
+
+# Storefront Themes
+
+Themes enable customizing the visual appearance of the Shopware Storefront.
+
+Themes are technically implemented as plugins, but unlike a plugin they lack backend logic. They focus purely on storefront presentation and are managed per sales channel via the Theme Manager.
+
+## Getting started
+
+* [Theme Base Guide](./theme-base-guide.md)
+* [Create a first theme](./create-a-theme.md)
\ No newline at end of file
diff --git a/guides/plugins/themes/add-theme-inheritance-without-resources.md b/guides/development/extensions/themes/inheritance/add-theme-inheritance-without-resources.md
similarity index 100%
rename from guides/plugins/themes/add-theme-inheritance-without-resources.md
rename to guides/development/extensions/themes/inheritance/add-theme-inheritance-without-resources.md
diff --git a/guides/plugins/themes/add-theme-inheritance.md b/guides/development/extensions/themes/inheritance/add-theme-inheritance.md
similarity index 100%
rename from guides/plugins/themes/add-theme-inheritance.md
rename to guides/development/extensions/themes/inheritance/add-theme-inheritance.md
diff --git a/guides/development/extensions/themes/inheritance/index.md b/guides/development/extensions/themes/inheritance/index.md
new file mode 100644
index 0000000000..e6be65b18c
--- /dev/null
+++ b/guides/development/extensions/themes/inheritance/index.md
@@ -0,0 +1,12 @@
+---
+nav:
+ title: Inheritance
+ position: 50
+---
+
+# Theme Inheritance
+
+This section explains how to extend and compose themes using Shopware’s inheritance system. Guides cover:
+
+* [Theme inheritance](./add-theme-inheritance.md)
+* [Add theme inheritance without resources](./add-theme-inheritance-without-resources.md)
\ No newline at end of file
diff --git a/guides/plugins/themes/add-css-js-to-theme.md b/guides/development/extensions/themes/styling/add-css-js-to-theme.md
similarity index 100%
rename from guides/plugins/themes/add-css-js-to-theme.md
rename to guides/development/extensions/themes/styling/add-css-js-to-theme.md
diff --git a/guides/development/extensions/themes/styling/index.md b/guides/development/extensions/themes/styling/index.md
new file mode 100644
index 0000000000..4f7ef2f29b
--- /dev/null
+++ b/guides/development/extensions/themes/styling/index.md
@@ -0,0 +1,13 @@
+---
+nav:
+ title: Styling
+ position: 45
+---
+
+# Theme Styling
+
+This section explains how to customize the visual styling of a Shopware theme. Included guides:
+
+* [Add SCSS Styling and JavaScript to a Theme](./add-css-js-to-theme.md)
+* [Override Bootstrap variables in a Theme](./override-bootstrap-variables-in-a-theme.md)
+* [Override responsive breakpoints in a Theme](./override-theme-breakpoints.md)
diff --git a/guides/plugins/themes/override-bootstrap-variables-in-a-theme.md b/guides/development/extensions/themes/styling/override-bootstrap-variables-in-a-theme.md
similarity index 100%
rename from guides/plugins/themes/override-bootstrap-variables-in-a-theme.md
rename to guides/development/extensions/themes/styling/override-bootstrap-variables-in-a-theme.md
diff --git a/guides/plugins/themes/override-theme-breakpoints.md b/guides/development/extensions/themes/styling/override-theme-breakpoints.md
similarity index 100%
rename from guides/plugins/themes/override-theme-breakpoints.md
rename to guides/development/extensions/themes/styling/override-theme-breakpoints.md
diff --git a/guides/development/extensions/themes/theme-base-guide.md b/guides/development/extensions/themes/theme-base-guide.md
new file mode 100644
index 0000000000..30214a28cf
--- /dev/null
+++ b/guides/development/extensions/themes/theme-base-guide.md
@@ -0,0 +1,56 @@
+---
+nav:
+ title: Theme Base Guide
+ position: 10
+
+---
+
+# Theme Base Guide
+
+## What is a theme?
+
+Storefront Themes enable you to customize the visual appearance of the Shopware Storefront. They are not a separate extension type, but are implemented as plugins—or, in Cloud environments, delivered via Apps.
+
+Shopware comes with a default theme built on top of Bootstrap 5. Everything you can do with Bootstrap, you can do with the Shopware Storefront.
+
+Another handy capability is the theme configuration. As a theme developer, you can define variables configurable via the Administration. Those variables are accessible in your theme and let you implement powerful features.
+
+## What themes can do
+
+Themes allow you to:
+
+* Override Twig templates
+* Add and customize SCSS/CSS styling
+* Provide JavaScript for storefront behavior
+* Define configurable theme settings in the Administration
+* Control template and style inheritance order
+
+::: info
+Note that a plugin can also override templates.
+:::
+
+## How themes differ from regular plugins
+
+* They typically do not contain backend PHP logic. They're stripped-down plugins consisting of a UI.
+* They're visible in the theme manager once activated and assigned per sales channel.
+* They focus on storefront presentation.
+* They require implementing `ThemeInterface`.
+* They can inherit from other themes.
+
+Themes are assigned per sales channel and managed via the Theme Manager.
+
+If you need database changes, custom entities, or console commands, [build a Plugin](../plugins/plugin-base-guide) instead.
+
+## Developer workflow
+
+If you are building a theme, follow this path:
+
+1. [Create a theme](create-a-theme.md)
+2. Configure it via [`theme.json`](configuration/theme-configuration.md)
+3. [Add SCSS styling and JavaScript](styling/add-css-js-to-theme.md)
+4. [Add assets](assets/add-assets-to-theme.md) and [icons](assets/add-icons.md)
+5. [Override Bootstrap variables or breakpoints](styling/override-bootstrap-variables-in-a-theme.md) or [responsive breakpoints](styling/override-theme-breakpoints.md)
+6. Customize templates (see [Storefront template customization](../plugins/storefront/templates/customize-templates.md))
+7. Use [theme inheritance](inheritance/add-theme-inheritance.md) if needed
+
+Now that you know what you can do with themes, the next steps would be to [create themes](create-a-theme).
diff --git a/guides/development/index.md b/guides/development/index.md
new file mode 100644
index 0000000000..bdcf6ed165
--- /dev/null
+++ b/guides/development/index.md
@@ -0,0 +1,103 @@
+---
+nav:
+ title: Development
+ position: 1
+
+---
+
+# Development
+
+This guide covers post-installation information for building, extending, and debugging Shopware during development. The development path depends on what is being built:
+
+* Custom project
+* Extension: apps, plugins, or plugin-based themes
+* Storefront customization
+* Administration extension
+* Headless integration
+
+All development scenarios share common foundations:
+
+* APIs
+* Testing
+* Tooling
+* CLI and system commands
+* Configuration
+* Debugging
+
+To build a custom Shopware project without creating an extension for distribution, start here.
+
+## Extension development
+
+To build an extension, first choose the correct type:
+
+* Plugin
+* App
+* Plugin-based theme
+
+Each extension guide walks you through the full development flow: creation → lifecycle → implementation → testing.
+
+To sell an extension or offer paid features, see the [Monetization guide](./monetization) for available models such as paid extensions, In-App Purchases, and commission-based integrations.
+
+## Typical development workflow
+
+Most development follows this sequence:
+
+* Set up the environment
+* Create the project or extension
+* Install and activate it
+* Implement business logic
+* Extend Storefront or Administration
+* Add configuration or database changes (if required)
+* Test and debug
+
+Before beginning implementation, review the recommended [Code structure](extensions/code-structure.md). A consistent architecture prevents long-term maintenance issues and reduces upgrade friction.
+
+:::tip Upgrade awareness
+Before starting new development, review the [Upgrades and Migrations](../upgrades-and-migrations/index.md) section to avoid patterns that are deprecated or scheduled for removal.
+:::
+
+:::info Upgrade impact in real projects
+Upgrade complexity depends on the installation:
+
+* Heavy custom code increases migration effort.
+* No custom code but 60 Store plugins can be equally complex.
+* Most real-world projects fall somewhere in between.
+
+A consistent architecture, centralized CI, and controlled extension strategy help you get ahead of upgrade pain.
+:::
+
+Set up automated testing and [Continuous Integration (CI)](testing/ci.md) early. Static analysis, tests, and reproducible builds help catch breaking changes before they reach production.
+
+## Working in the system
+
+### Administration
+
+To begin any development, first access the Administration by opening [http://localhost/admin](http://localhost/admin).
+
+Use the Administration to:
+
+* Install and activate extensions
+* Configure the system
+* Manage entities such as products and customers
+* Verify extension behavior
+
+The Administration is part of the runtime environment and will be used throughout development.
+
+### 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.html).
+* The standalone [Shopware CLI](https://developer.shopware.com/docs/products/cli/installation.html) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](products/cli/project-commands/helper-commands.html).
+* IDE support: Shopware provides a [PhpStorm plugin](shopware-toolbox.md) and [VS Code extension](../development/tooling/vscode.md).
+*[Deployment Helper](guides/hosting/deployment-helper/): Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
+
+### Troubleshooting
+
+The [troubleshooting](/troubleshooting) guides provide reference information about the data abstraction layer (DAL), flow, and rules.
+
+## Next steps
+
+Continue with the guide related to the development goal:
+
+* [Extensions](extensions/index.md): Build Plugins, Apps, or plugin-based Themes
+* [APIs](apis/index.md): Work with Admin API, Store API, and data access
+* [Testing](testing/index.md): Unit testing, E2E testing, and CI practices to prevent upgrade regressions
diff --git a/guides/development/testing/ci.md b/guides/development/testing/ci.md
new file mode 100644
index 0000000000..d5e142c484
--- /dev/null
+++ b/guides/development/testing/ci.md
@@ -0,0 +1,33 @@
+---
+nav:
+ title: CI
+ position: 10
+
+---
+
+# CI
+
+CI should, at minimum, run static analysis and coding standards checks alongside the project or extension build to keep artifacts reproducible. Add sanity checks such as smoke tests and lightweight integration tests to catch regressions early. Automated tests—from unit to integration and E2E, where feasible—make refactors, upgrades, and dependency changes safer.
+
+:::info
+Follow the [Deployment guide](../../hosting/deployments.md) for information about promotion and release.
+:::
+
+## Cross-cutting practices
+
+* Fail fast on coding standards and static analysis before slower E2E tests.
+* Use the ([Shopware CLI formatter](../../products/cli/formatter.md)) to keep code style consistent and run the bundled validation tools in CI using ([Shopware CLI validation tools](../../products/cli/validation.md)).
+* Produce artifacts once per commit (ZIP for plugins, deployable image/package for apps, built assets for projects) and promote the same artifact through stages.
+
+## Custom projects
+
+* Reuse the ([Project build command](../../products/cli/project-commands/build.md)) to compile Storefront and Administration assets and warm caches. Run it in CI so deployments do not rebuild.
+* Use environment-specific config only in deployment, not in CI. See [setup patterns](../installation/setups/index.md) you can mirror in pipelines.
+* Add smoke tests against the HTTP layer plus DAL-level integration tests for custom entities.
+* Cache Composer/NPM dependencies but keep lockfiles committed for deterministic builds.
+
+## Custom/Store plugins
+
+* Build and validate with `shopware-cli extension build` ([Extension build command](../../products/cli/extension-commands/build.md)) to ensure the ZIP is reproducible.
+* Run unit/integration tests with the Shopware test environment; keep fixtures inside the plugin to avoid coupling to project data.
+* For Store plugins, add the Shopware Store validations early (linting, metadata, PHPStan) to catch review issues before submission ([Store submission via CLI](../../products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md)).
diff --git a/guides/plugins/plugins/testing/playwright/actor-pattern.md b/guides/development/testing/e2e-playwright/actor-pattern.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/actor-pattern.md
rename to guides/development/testing/e2e-playwright/actor-pattern.md
diff --git a/guides/plugins/plugins/testing/playwright/best-practices.md b/guides/development/testing/e2e-playwright/best-practices.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/best-practices.md
rename to guides/development/testing/e2e-playwright/best-practices.md
diff --git a/guides/plugins/plugins/testing/playwright/deployment.md b/guides/development/testing/e2e-playwright/deployment.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/deployment.md
rename to guides/development/testing/e2e-playwright/deployment.md
diff --git a/guides/plugins/plugins/testing/playwright/fixtures.md b/guides/development/testing/e2e-playwright/fixtures.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/fixtures.md
rename to guides/development/testing/e2e-playwright/fixtures.md
diff --git a/guides/plugins/plugins/testing/playwright/index.md b/guides/development/testing/e2e-playwright/index.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/index.md
rename to guides/development/testing/e2e-playwright/index.md
diff --git a/guides/plugins/plugins/testing/playwright/install-configure.md b/guides/development/testing/e2e-playwright/install-configure.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/install-configure.md
rename to guides/development/testing/e2e-playwright/install-configure.md
diff --git a/guides/plugins/plugins/testing/playwright/language-agnostic-testing.md b/guides/development/testing/e2e-playwright/language-agnostic-testing.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/language-agnostic-testing.md
rename to guides/development/testing/e2e-playwright/language-agnostic-testing.md
diff --git a/guides/plugins/plugins/testing/playwright/local-development.md b/guides/development/testing/e2e-playwright/local-development.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/local-development.md
rename to guides/development/testing/e2e-playwright/local-development.md
diff --git a/guides/plugins/plugins/testing/playwright/page-object.md b/guides/development/testing/e2e-playwright/page-object.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/page-object.md
rename to guides/development/testing/e2e-playwright/page-object.md
diff --git a/guides/plugins/plugins/testing/playwright/test-data-service.md b/guides/development/testing/e2e-playwright/test-data-service.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/test-data-service.md
rename to guides/development/testing/e2e-playwright/test-data-service.md
diff --git a/guides/plugins/plugins/testing/playwright/test-suite-types.md b/guides/development/testing/e2e-playwright/test-suite-types.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/test-suite-types.md
rename to guides/development/testing/e2e-playwright/test-suite-types.md
diff --git a/guides/plugins/plugins/testing/playwright/test.md b/guides/development/testing/e2e-playwright/test.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/test.md
rename to guides/development/testing/e2e-playwright/test.md
diff --git a/guides/development/testing/index.md b/guides/development/testing/index.md
new file mode 100644
index 0000000000..aefd7e6fa4
--- /dev/null
+++ b/guides/development/testing/index.md
@@ -0,0 +1,63 @@
+---
+nav:
+ title: Testing
+ position: 80
+
+---
+
+# Testing
+
+This section covers automated testing strategies and quality requirements for Shopware extensions.
+
+## End-to-End testing
+
+For simulating real user journeys and integration scenarios, Shopware recommends end-to-end (E2E) testing. Playwright is the officially supported tool for automating entire workflows across the application.
+
+Playwright provides:
+
+* Preconfigured fixtures
+* Storefront and Administration page objects
+* API clients
+* Test data helpers
+
+<PageRef page="./e2e-playwright/index.md" />
+
+## Unit testing
+
+Shopware supports both PHP backend logic and JavaScript components (for Storefront and Administration). Unit tests validate isolated logic in your extension.
+
+### PHP (PHPUnit)
+
+Use PHPUnit to write and run backend unit tests for your PHP code.
+
+<PageRef page="./unit-testing/php-unit.md" />
+
+### JavaScript (Jest)
+
+Use Jest to test Storefront JS and Vue components following modern best practices.
+
+<PageRef page="./unit-testing/jest-storefront.md" />
+
+Test custom Administration panel modules and components using Jest with the Shopware admin setup.
+
+<PageRef page="./unit-testing/jest-admin.md" />
+
+## Continuous Integration (CI)
+
+Automate quality checks, builds, and artifact creation in your CI pipeline to keep extensions reproducible and safe to deploy.
+
+Learn how to structure CI for projects and plugins, including static analysis, test execution, and artifact promotion:
+
+<PageRef page="./ci.md" />
+
+## Testing guidelines for extensions
+
+To publish your extension in the Shopware Store, follow the testing criteria used during the Store review process.
+
+<PageRef page="./testing-guidelines.md" />
+
+It focuses on how your extension is functionally tested before approval.
+
+For the official publication requirements, legal conditions, and compliance rules, see:
+
+<PageRef page="../store/quality-guidelines.md" />
diff --git a/resources/guidelines/testing/store/index.md b/guides/development/testing/testing-guidelines.md
similarity index 97%
rename from resources/guidelines/testing/store/index.md
rename to guides/development/testing/testing-guidelines.md
index 7304c63b84..690e69466a 100644
--- a/resources/guidelines/testing/store/index.md
+++ b/guides/development/testing/testing-guidelines.md
@@ -37,7 +37,7 @@ Here is what the test criteria include:
* **[Lighthouse audit home/listing/detail](../store/quality-guidelines-apps/#frontend-apps)** - We check:
- * If your extension affects the Storefront or not? (so that the search engines have no problems with it).
+ * If your extension affects the Storefront or not? (so that the search engines have no problems with it).
* If all buttons, labels, etc., are named correctly?
We pay attention to all five audits. The app must not limit these. Like most search engines, we also pay attention to mobile-first.
diff --git a/guides/development/testing/unit/index.md b/guides/development/testing/unit/index.md
new file mode 100644
index 0000000000..c8dee6b313
--- /dev/null
+++ b/guides/development/testing/unit/index.md
@@ -0,0 +1,18 @@
+---
+nav:
+ title: Unit Testing
+ position: 60
+---
+
+# Unit Testing
+
+This section explains how to write and execute unit tests in Shopware.
+
+## JavaScript testing (Jest)
+
+* [Jest unit tests in Shopware's Administration](./jest-admin.md)
+* [Jest unit tests in Shopware's Storefront](./jest-storefront.md)
+
+## PHP testing (PHPUnit)
+
+* [PHP unit testing](./php-unit.md)
diff --git a/guides/plugins/plugins/testing/jest-admin.md b/guides/development/testing/unit/jest-admin.md
similarity index 100%
rename from guides/plugins/plugins/testing/jest-admin.md
rename to guides/development/testing/unit/jest-admin.md
diff --git a/guides/plugins/plugins/testing/jest-storefront.md b/guides/development/testing/unit/jest-storefront.md
similarity index 100%
rename from guides/plugins/plugins/testing/jest-storefront.md
rename to guides/development/testing/unit/jest-storefront.md
diff --git a/guides/plugins/plugins/testing/php-unit.md b/guides/development/testing/unit/php-unit.md
similarity index 100%
rename from guides/plugins/plugins/testing/php-unit.md
rename to guides/development/testing/unit/php-unit.md
diff --git a/products/cli/shopware-account-commands/authentication.md b/guides/development/tooling/cli/account-commands/authentication.md
similarity index 100%
rename from products/cli/shopware-account-commands/authentication.md
rename to guides/development/tooling/cli/account-commands/authentication.md
diff --git a/products/cli/shopware-account-commands/configure-composer-repository.md b/guides/development/tooling/cli/account-commands/configure-composer-repository.md
similarity index 100%
rename from products/cli/shopware-account-commands/configure-composer-repository.md
rename to guides/development/tooling/cli/account-commands/configure-composer-repository.md
diff --git a/guides/development/tooling/cli/account-commands/index.md b/guides/development/tooling/cli/account-commands/index.md
new file mode 100644
index 0000000000..c4f6f998c6
--- /dev/null
+++ b/guides/development/tooling/cli/account-commands/index.md
@@ -0,0 +1,14 @@
+---
+nav:
+ title: Account Commands
+ position: 30
+---
+
+# Account Commands
+
+This section documents Shopware CLI commands that interact with the Shopware Account and the Shopware Store.
+
+* [Authentication](./authentication.md)
+* [Releasing automated extension to Shopware Store](./releasing-extension-to-shopware-store.md)
+* [Updating Store Page of Extension](./updating-store-page.md)
+* [Configure Composer Repository](./configure-composer-repository.md)
diff --git a/products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md b/guides/development/tooling/cli/account-commands/releasing-extension-to-shopware-store.md
similarity index 100%
rename from products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md
rename to guides/development/tooling/cli/account-commands/releasing-extension-to-shopware-store.md
diff --git a/products/cli/shopware-account-commands/updating-store-page.md b/guides/development/tooling/cli/account-commands/updating-store-page.md
similarity index 100%
rename from products/cli/shopware-account-commands/updating-store-page.md
rename to guides/development/tooling/cli/account-commands/updating-store-page.md
diff --git a/products/cli/automatic-refactoring.md b/guides/development/tooling/cli/automatic-refactoring.md
similarity index 100%
rename from products/cli/automatic-refactoring.md
rename to guides/development/tooling/cli/automatic-refactoring.md
diff --git a/products/cli/extension-commands/admin-watcher.md b/guides/development/tooling/cli/extension-commands/admin-watcher.md
similarity index 100%
rename from products/cli/extension-commands/admin-watcher.md
rename to guides/development/tooling/cli/extension-commands/admin-watcher.md
diff --git a/products/cli/extension-commands/configuration.md b/guides/development/tooling/cli/extension-commands/configuration.md
similarity index 100%
rename from products/cli/extension-commands/configuration.md
rename to guides/development/tooling/cli/extension-commands/configuration.md
diff --git a/products/cli/extension-commands/extract-meta-data.md b/guides/development/tooling/cli/extension-commands/extract-metadata.md
similarity index 93%
rename from products/cli/extension-commands/extract-meta-data.md
rename to guides/development/tooling/cli/extension-commands/extract-metadata.md
index 5d2f8eaee0..46982377e2 100644
--- a/products/cli/extension-commands/extract-meta-data.md
+++ b/guides/development/tooling/cli/extension-commands/extract-metadata.md
@@ -1,11 +1,11 @@
---
nav:
- title: Extracting Meta Data
+ title: Extracting Metadata
position: 4
---
-# Extracting Meta Data
+# Extracting Metadata
There are helpers in Shopware CLI to extract data of an extension. This is useful in your CI/CD pipeline to get the extension version or the changelog for the automated release.
diff --git a/guides/development/tooling/cli/extension-commands/index.md b/guides/development/tooling/cli/extension-commands/index.md
new file mode 100644
index 0000000000..adbb6b1802
--- /dev/null
+++ b/guides/development/tooling/cli/extension-commands/index.md
@@ -0,0 +1,14 @@
+---
+nav:
+ title: Extension Commands
+ position: 20
+---
+
+# Extension Commands
+
+This section documents the available Shopware CLI commands for developing, validating, and releasing extensions:
+
+* [Standalone Admin Watcher](./admin-watcher.md)
+* [Configuration](./configuration.md)
+* [Extracting Meta Data](./extract-meta-data.md)
+* [Validation](./validation.md)
diff --git a/products/cli/validation.md b/guides/development/tooling/cli/extension-commands/validation.md
similarity index 100%
rename from products/cli/validation.md
rename to guides/development/tooling/cli/extension-commands/validation.md
diff --git a/products/cli/formatter.md b/guides/development/tooling/cli/formatter.md
similarity index 100%
rename from products/cli/formatter.md
rename to guides/development/tooling/cli/formatter.md
diff --git a/products/cli/index.md b/guides/development/tooling/cli/index.md
similarity index 61%
rename from products/cli/index.md
rename to guides/development/tooling/cli/index.md
index 5cd70cdc2a..5daadda587 100644
--- a/products/cli/index.md
+++ b/guides/development/tooling/cli/index.md
@@ -7,16 +7,16 @@ nav:
# Shopware CLI
-[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](installation/) and configure separately from your Shopware instance. Once set up, it helps you automate and speed up common tasks such as:
+[Shopware CLI](https://github.com/shopware/shopware-cli) is the open-source command-line interface for working with Shopware 6. Install it via [installation](installation/) or our [Docker setup](docker-setup).
-- managing and configuring Shopware projects
-- building, validating, and packaging extensions
-- uploading and maintaining extensions in the Shopware Store
-- running CI/CD pipelines for Shopware-based solutions
+Shopware CLI helps you automate and speed up common tasks such as:
-Shopware CLI runs on macOS, Linux, and via Docker. For system-level requirements (PHP, DB, memory, etc.) see the [General Requirements](../guides/requirements/).
+* managing and configuring Shopware projects
+* building, validating, and packaging extensions
+* uploading and maintaining extensions in the Shopware Store
+* running CI/CD pipelines for Shopware-based solutions
-**Supported platforms (short):** macOS (Homebrew), Debian/Ubuntu (APT), other Linux via RPM or manual installation, and Docker. Windows users should use WSL 2 or Docker. (See full [installation](installation.md) page for Windows details.)
+**Supported platforms:** macOS (Homebrew), Debian/Ubuntu (APT), other Linux via RPM or manual installation, and Docker. Windows users should use WSL 2 or Docker. See our [Hardware Requirements](../guides/hardware-requirements/).
## Quickstart
@@ -67,15 +67,36 @@ COPY --from=ghcr.io/shopware/shopware-cli:bin /shopware-cli /usr/local/bin/shopw
**Binary & releases:** Prebuilt packages and archives are published at [shopware/shopware-cli · Releases](https://github.com/shopware/shopware-cli/releases).
-## Overview
+## Develop
-Shopware CLI is organized into three main command scopes that cover the most common development and maintenance workflows:
+### Create or work on a project
-- Project commands: interact with your Shopware project (e.g., build, dump DB, or sync configuration)
-- Extension commands: build and validate Shopware extensions
-- Store commands: publish or update extensions in the Shopware Store
+Work directly with your [Shopware project](deployment/) to automate setup and maintenance tasks. Available commands include:
+
+```bash
+shopware-cli project create # Create a new Shopware 6 project
+shopware-cli project dump # Dumps the Shopware database
+shopware-cli project admin-watch
+```
+
+Useful development helpers:
+
+```bash
+shopware-cli project image-proxy #Image proxy
+shopware-cli project console #Console shortcut
+shopware-cli project worker #Worker processes
+
+### Work on an extension
-## Automatic refactoring
+Create, build, and validate Shopware [extensions](plugins/) and prepare them for the [Store](https://store.shopware.com/de/) or distribution. Available commands include:
+
+```bash
+shopware-cli extension fix # Fix an extension
+shopware-cli extension build # Builds assets for extensions
+shopware-cli extension validate # Validate an extension
+```
+
+### Automatic refactoring
Shopware CLI also includes an automatic refactoring tool for PHP, JavaScript, and Admin Twig files. It uses:
@@ -95,33 +116,52 @@ shopware-cli project fix /path/to/your/project
Always back up or version your code before running refactoring commands, as they will modify files in place. [Learn more here](automatic-refactoring/).
-### Project commands
+:::tip Preparing for major upgrades
+Before upgrading to a new major Shopware version, review the [Upgrades and Migrations guide](/guides/upgrades-and-migrations/) and use `shopware-cli project fix` or `extension fix` to address deprecations early.
+:::
-Work directly with your [Shopware project](deployment/) to automate setup and maintenance tasks. Available commands include:
+## Deploy
+
+Prepare your project for CI or production:
```bash
-shopware-cli project create # Create a new Shopware 6 project
-shopware-cli project dump # Dumps the Shopware database
shopware-cli project ci # Build Shopware in the CI
```
-### Extension commands
-
-Create, build, and validate Shopware [extensions](plugins/) and prepare them for the [Store](https://store.shopware.com/de/) or distribution. Available commands include:
+Package an extension for distribution:
```bash
-shopware-cli extension fix # Fix an extension
-shopware-cli extension build # Builds assets for extensions
-shopware-cli extension validate # Validate an extension
+shopware-cli extension zip
```
-### Store commands
-
-Publish and manage your extensions in the [Store](https://store.shopware.com/de/), with commands such as:
+Publish and manage your extensions in the [Store](https://store.shopware.com/de/):
```bash
shopware-cli store login # Login to Shopware Store portal.store
+shopware-cli extension publish
shopware-cli token: Manage tokens for Store authentication
```
+## Run / Operate
+
+Operational helpers:
+
+```bash
+shopware-cli project worker
+shopware-cli project clear-cache
+shopware-cli project admin-api
+```
+
+These commands simplify common Symfony console and runtime operations.
+
+## Upgrade / Maintain
+
+Keep your project or extension up to date:
+
+```bash
+shopware-cli project fix
+shopware-cli extension validate --full
+shopware-cli extension format
+```
+
Run any command with `--help` to see its available options. Example: `shopware-cli extension --help`
diff --git a/products/cli/installation.md b/guides/development/tooling/cli/installation.md
similarity index 100%
rename from products/cli/installation.md
rename to guides/development/tooling/cli/installation.md
diff --git a/products/cli/project-commands/autofix.md b/guides/development/tooling/cli/project-commands/autofix.md
similarity index 100%
rename from products/cli/project-commands/autofix.md
rename to guides/development/tooling/cli/project-commands/autofix.md
diff --git a/products/cli/extension-commands/build.md b/guides/development/tooling/cli/project-commands/build.md
similarity index 100%
rename from products/cli/extension-commands/build.md
rename to guides/development/tooling/cli/project-commands/build.md
diff --git a/products/cli/project-commands/helper-commands.md b/guides/development/tooling/cli/project-commands/helper-commands.md
similarity index 100%
rename from products/cli/project-commands/helper-commands.md
rename to guides/development/tooling/cli/project-commands/helper-commands.md
diff --git a/products/cli/project-commands/image-proxy.md b/guides/development/tooling/cli/project-commands/image-proxy.md
similarity index 100%
rename from products/cli/project-commands/image-proxy.md
rename to guides/development/tooling/cli/project-commands/image-proxy.md
diff --git a/guides/development/tooling/cli/project-commands/index.md b/guides/development/tooling/cli/project-commands/index.md
new file mode 100644
index 0000000000..f46256b1b0
--- /dev/null
+++ b/guides/development/tooling/cli/project-commands/index.md
@@ -0,0 +1,16 @@
+---
+nav:
+ title: Project Commands
+ position: 20
+---
+
+# Project Commands
+
+This section documents the available Shopware CLI commands for developing, validating, and releasing extensions.
+
+* [Autofixer](./autofix.md)
+* [Building extensions and creating archives](./build.md)
+* [Helper Commands](./helper-commands.md)
+* [Image Proxy](./image-proxy.md)
+* [Generating MySQL dumps](./mysql-dump.md)
+* [Remote Extension Management](./remote-extension-managment.md)
diff --git a/products/cli/project-commands/mysql-dump.md b/guides/development/tooling/cli/project-commands/mysql-dump.md
similarity index 100%
rename from products/cli/project-commands/mysql-dump.md
rename to guides/development/tooling/cli/project-commands/mysql-dump.md
diff --git a/products/cli/project-commands/remote-extension-managment.md b/guides/development/tooling/cli/project-commands/remote-extension-managment.md
similarity index 100%
rename from products/cli/project-commands/remote-extension-managment.md
rename to guides/development/tooling/cli/project-commands/remote-extension-managment.md
diff --git a/resources/tooling/cli/using-watchers.md b/guides/development/tooling/cli/project-commands/using-watchers.md
similarity index 100%
rename from resources/tooling/cli/using-watchers.md
rename to guides/development/tooling/cli/project-commands/using-watchers.md
diff --git a/resources/tooling/fixture-bundle/index.md b/guides/development/tooling/fixture-bundle.md
similarity index 97%
rename from resources/tooling/fixture-bundle/index.md
rename to guides/development/tooling/fixture-bundle.md
index 33218c423c..e4161a521b 100644
--- a/resources/tooling/fixture-bundle/index.md
+++ b/guides/development/tooling/fixture-bundle.md
@@ -7,7 +7,9 @@ nav:
# Fixture Bundle
-The Fixture Bundle provides a flexible and organized way to load test and demo data into your Shopware 6 application. It's designed to be extensible and easy to use, supporting dependency management, priority-based execution, and group filtering. This guide will walk you through the process of creating and managing data fixtures for your Shopware project.
+The Fixture Bundle provides a flexible and organized way to load-test and demo data into your Shopware 6 application. It's designed to be extensible and easy to use, supporting dependency management, priority-based execution, and group filtering. It works for the Shopware core, plugins, and apps.
+
+This guide will walk you through the process of creating and managing data fixtures for your Shopware project.
## Installation
diff --git a/guides/development/tooling/index.md b/guides/development/tooling/index.md
new file mode 100644
index 0000000000..077d8622f5
--- /dev/null
+++ b/guides/development/tooling/index.md
@@ -0,0 +1,20 @@
+---
+nav:
+ title: Tooling
+ position: 30
+
+---
+
+# Tooling
+
+Shopware provides official tools that support the full lifecycle of a Shopware project, from development to deployment and long-term maintenance.
+
+## Development
+
+[Shopware CLI](/docs/guides/development/tooling/cli/): The central command-line tool for working with Shopware projects and extensions, including scaffolding, builds, validation, packaging, Store interaction, CI support, and development workflows such as watchers and [formatting](/docs/guides/development/tooling/cli/formatter/).
+
+[Admin Extension SDK](/resources/admin-extension-sdk/): JavaScript SDK for building Administration extensions (Apps) and integrating with the Shopware Administration.
+
+[Fixture Bundle](/docs/resources/tooling/fixture-bundle/): Seed development environments with demo and test data.
+
+[PHPStorm Setup](/docs/guides/installation/ide/phpstorm/): Recommended IDE configuration and debugging setup.
diff --git a/resources/guidelines/troubleshooting/phpstan.md b/guides/development/tooling/phpstan.md
similarity index 100%
rename from resources/guidelines/troubleshooting/phpstan.md
rename to guides/development/tooling/phpstan.md
diff --git a/resources/tooling/ide/shopware-toolbox.md b/guides/development/tooling/shopware-toolbox.md
similarity index 52%
rename from resources/tooling/ide/shopware-toolbox.md
rename to guides/development/tooling/shopware-toolbox.md
index d1eb8f4033..3e1b53703e 100644
--- a/resources/tooling/ide/shopware-toolbox.md
+++ b/guides/development/tooling/shopware-toolbox.md
@@ -7,7 +7,9 @@ nav:
# Shopware 6 Toolbox
-Shopware 6 Toolbox is a helper plugin and productivity tool for common tasks for Shopware 6 development. It adds some live templates and scaffolding of common Shopware files.
+[Shopware 6 Toolbox](https://plugins.jetbrains.com/plugin/17632-shopware-6-toolbox) is a productivity plugin for JetBrains IDEs (e.g., PhpStorm) that enhances the Shopware 6 development experience. It provides live templates and scaffolding for common Shopware tasks.
+
+Shopware Toolbox is not a standalone application. It runs inside PhpStorm (and other JetBrains IDEs) and provides Shopware-specific development helpers.
@@ -19,7 +21,7 @@ Shopware 6 Toolbox is a helper plugin and productivity tool for common tasks for
Multiple live templates for development. Use Cmd/Ctrl + J to see all live templates available.
-### Generators
+### Code generators
* Vue.js Admin component
* config.xml
@@ -28,7 +30,7 @@ Multiple live templates for development. Use Cmd/Ctrl + J to see all live templa
* Scheduled task
* Changelog
-### Static code check
+### Static code checks
Inspection to show an error when abstract class is used incorrectly in the constructor (guideline check).
@@ -37,13 +39,16 @@ Inspection to show an error when abstract class is used incorrectly in the const
* Admin components
* Snippets in Administration and Storefront
* Storefront functions `theme_config`, `config`, `seoUrl`, `sw_include` and `sw_extends`
-* Repositories at this.repositoryFactory.create
+* Repository auto-completion at `this.repositoryFactory.create`
* Module.register labels
-* Show only admin component auto-completion when the twig file is next to an index.js
+* Context-aware admin component auto-completion (only when Twig file is next to an `index.js`)
* Feature flags
## Installation
-Either search for `Shopware 6 Toolbox` in the JetBrains Marketplace or get it on the marketplace website.
+Follow these steps:
-<PageRef page="https://plugins.jetbrains.com/plugin/17632-shopware-6-toolbox" title="Shopware 6 Toolbox on JetBrains Marketplace" target="_blank" />
+1. Open PhpStorm
+2. Go to Settings → Plugins
+3. Search for “Shopware 6 Toolbox”
+4. Install and restart the IDE
diff --git a/resources/references/core-reference/dal-reference/aggregations-reference.md b/guides/development/troubleshooting/dal-reference/aggregations-reference.md
similarity index 100%
rename from resources/references/core-reference/dal-reference/aggregations-reference.md
rename to guides/development/troubleshooting/dal-reference/aggregations-reference.md
diff --git a/resources/references/core-reference/dal-reference/fields-reference/enum-field.md b/guides/development/troubleshooting/dal-reference/fields-reference/enum-field.md
similarity index 100%
rename from resources/references/core-reference/dal-reference/fields-reference/enum-field.md
rename to guides/development/troubleshooting/dal-reference/fields-reference/enum-field.md
diff --git a/resources/references/core-reference/dal-reference/fields-reference/index.md b/guides/development/troubleshooting/dal-reference/fields-reference/index.md
similarity index 100%
rename from resources/references/core-reference/dal-reference/fields-reference/index.md
rename to guides/development/troubleshooting/dal-reference/fields-reference/index.md
diff --git a/resources/references/core-reference/dal-reference/filters-reference.md b/guides/development/troubleshooting/dal-reference/filters-reference.md
similarity index 100%
rename from resources/references/core-reference/dal-reference/filters-reference.md
rename to guides/development/troubleshooting/dal-reference/filters-reference.md
diff --git a/resources/references/core-reference/dal-reference/flags-reference.md b/guides/development/troubleshooting/dal-reference/flags-reference.md
similarity index 100%
rename from resources/references/core-reference/dal-reference/flags-reference.md
rename to guides/development/troubleshooting/dal-reference/flags-reference.md
diff --git a/resources/references/core-reference/dal-reference/index.md b/guides/development/troubleshooting/dal-reference/index.md
similarity index 100%
rename from resources/references/core-reference/dal-reference/index.md
rename to guides/development/troubleshooting/dal-reference/index.md
diff --git a/resources/references/core-reference/flow-reference.md b/guides/development/troubleshooting/flow-reference.md
similarity index 95%
rename from resources/references/core-reference/flow-reference.md
rename to guides/development/troubleshooting/flow-reference.md
index a85fd849f1..e5db8633c9 100644
--- a/resources/references/core-reference/flow-reference.md
+++ b/guides/development/troubleshooting/flow-reference.md
@@ -116,3 +116,10 @@ nav:
| employee.status.changed | Triggers when the status of an employee changes | Employee Management |
| employee.role.changed | Triggers when the role of an employee changes | Employee Management |
| employee.order.placed | Triggers when an employee places an order | Employee Management |
+
+# Actions Reference
+
+| Class | Description | Component |
+|:------------------------------------------------|:---------------------------------------------------------------|:--------------------|
+| ChangeEmployeeStatusAction | Assigns the configured status to the employee | Employee Management |
+| ChangeCustomerSpecificFeaturesAction | Adds or removes the configured b2b components for the customer | Employee Management |
diff --git a/guides/development/troubleshooting/index.md b/guides/development/troubleshooting/index.md
new file mode 100644
index 0000000000..f8b7a4396d
--- /dev/null
+++ b/guides/development/troubleshooting/index.md
@@ -0,0 +1,16 @@
+---
+nav:
+ title: Troubleshooting
+ position: 1
+---
+
+# Troubleshooting
+
+Quick, targeted troubleshooting resources for common runtime, data, and integration issues.
+
+Sections:
+
+* [DAL Reference](dal-reference): documents fields, flags, filters, and aggregations for effective data management and querying within the platform.
+ * [Fields Reference](dal-reference/fields-reference/index.md): field types, flags, enum fields.
+* [Rules Reference](rules-reference.md)
+* [Flow Reference](flow-reference.md)
diff --git a/resources/references/core-reference/rules-reference.md b/guides/development/troubleshooting/rules-reference.md
similarity index 100%
rename from resources/references/core-reference/rules-reference.md
rename to guides/development/troubleshooting/rules-reference.md
diff --git a/resources/references/config-reference/server/nginx.md b/guides/hosting/configuration-reference.md
similarity index 68%
rename from resources/references/config-reference/server/nginx.md
rename to guides/hosting/configuration-reference.md
index 9a35d03f6d..822686b43f 100644
--- a/resources/references/config-reference/server/nginx.md
+++ b/guides/hosting/configuration-reference.md
@@ -1,8 +1,38 @@
-# Nginx
+---
+nav:
+ title: Configuration Reference
+ position: 20
-::: info
-The document root must always point to the public folder, to ensure all functionality works.
-:::
+---
+
+# Configuration Reference
+
+This guide provides the required server configuration reference for deploying Shopware in production environments.
+
+## Important
+
+The document root must always point to the `/public` directory. All server examples below assume this setup.
+
+## Apache
+
+```text
+<VirtualHost *:80>
+ ServerName "HOST_NAME"
+ DocumentRoot _SHOPWARE_LOCATION_/public
+
+ <Directory _SHOPWARE_LOCATION_>
+ Options Indexes FollowSymLinks MultiViews
+ AllowOverride All
+ Order allow,deny
+ allow from all
+ </Directory>
+
+ ErrorLog ${APACHE_LOG_DIR}/shopware.error.log
+ CustomLog ${APACHE_LOG_DIR}/shopware.access.log combined
+</VirtualHost>
+```
+
+## Nginx
```text
server {
@@ -94,3 +124,30 @@ server {
}
}
```
+
+## Caddy
+
+```text
+mydomain.com {
+ header {
+ X-Frame-Options DENY
+ Referrer-Policy no-referrer-when-downgrade
+ }
+
+ @svg {
+ file
+ path *.svg
+ }
+
+ header @svg Content-Security-Policy "script-src 'none'"
+
+ @default {
+ not path /theme/* /media/* /thumbnail/* /bundles/* /css/* /fonts/* /js/* /recovery/* /sitemap/*
+ }
+
+ root * public
+ php_fastcgi 127.0.0.1:9000
+ encode zstd gzip
+ file_server
+}
+```
diff --git a/guides/hosting/deployments.md b/guides/hosting/deployments.md
new file mode 100644
index 0000000000..0299252656
--- /dev/null
+++ b/guides/hosting/deployments.md
@@ -0,0 +1,33 @@
+---
+nav:
+ title: Deployments
+ position: 3
+
+---
+
+# Deployments
+
+Deploy with the same artifacts you built in [CI](../../development/testing/ci.md). Keep configuration outside the codebase, and make database changes predictable. Separate build from runtime wherever possible so releases stay repeatable and reversible.
+
+## Cross-cutting practices
+
+* Roll forward by default. Keep rollbacks minimal (DB-aware and version-pinned) and practice them.
+* Use maintenance mode for schema-changing releases. Add health checks and smoke tests post-deploy before exiting maintenance.
+* Tag releases consistently across code, artifacts, and Store metadata. keep build logs and deploy reports for audits.
+
+## Custom projects
+
+* Follow the deployment helper flow ([Deployment helper](../hosting/installation-updates/deployments/deployment-helper.md)) to keep steps ordered and reversible.
+* Use a repeatable deploy strategy (e.g. via the [Deployment helper](../hosting/installation-updates/deployments/deployment-helper.md)); keep environment config and secrets outside the repo.
+
+## Custom/Store plugins
+
+* Ship plugins as versioned ZIP files from CI, using the ([Extension build command](../../products/cli/extension-commands/build.md)). Install/activate via CLI or deployment automation.
+* Apply plugin migrations during deploy and keep update steps idempotent so retries are safe.
+* For Store plugins, avoid post-deploy manual tweaks.
+
+## Apps
+
+* Deploy app backends like any web service; use blue/green or canary so webhook handling is uninterrupted.
+* Keep manifest versions in sync with deployed code; register new webhooks before emitting new events to avoid gaps.
+* Externalize credentials and endpoints; design for multi-tenant hosting and retry-safe handlers.
diff --git a/resources/guidelines/troubleshooting/elasticsearch.md b/guides/hosting/infrastructure/elasticsearch/troubleshooting.md
similarity index 100%
rename from resources/guidelines/troubleshooting/elasticsearch.md
rename to guides/hosting/infrastructure/elasticsearch/troubleshooting.md
diff --git a/guides/hosting/infrastructure/optional-packages.md b/guides/hosting/infrastructure/optional-packages.md
new file mode 100644
index 0000000000..6192296bab
--- /dev/null
+++ b/guides/hosting/infrastructure/optional-packages.md
@@ -0,0 +1,35 @@
+---
+nav:
+ title: Optional Packages
+ position: 40
+---
+
+# Optional Packages
+
+The minimal project template is intentionally small and does not include additional infrastructure integrations or developer tooling by default.
+
+Extend a project with optional packages as needed.
+
+## Symfony development tools
+
+Install Symfony’s profiler and related development tools:
+
+```bash
+composer require --dev symfony/profiler-pack
+```
+
+## PaaS integration
+
+Install the Platform-as-a-Service integration:
+
+```bash
+composer require paas --ignore-platform-req=ext-amqp
+```
+
+## Fastly integration
+
+Install Fastly support:
+
+```bash
+composer require fastly
+```
diff --git a/guides/hosting/installation-updates/extension-managment.md b/guides/hosting/installation-updates/extension-management.md
similarity index 100%
rename from guides/hosting/installation-updates/extension-managment.md
rename to guides/hosting/installation-updates/extension-management.md
diff --git a/resources/guidelines/troubleshooting/performance.md b/guides/hosting/performance/troubleshooting.md
similarity index 98%
rename from resources/guidelines/troubleshooting/performance.md
rename to guides/hosting/performance/troubleshooting.md
index c384260613..10313e0491 100644
--- a/resources/guidelines/troubleshooting/performance.md
+++ b/guides/hosting/performance/troubleshooting.md
@@ -1,11 +1,11 @@
---
nav:
- title: Performance
+ title: Troubleshooting
position: 20
---
-# Performance
+# Troubleshooting
## Common Performance Considerations
diff --git a/guides/integrations-api/general-concepts/api-versioning.md b/guides/integrations-api/general-concepts/api-versioning.md
deleted file mode 100644
index 5abebd5048..0000000000
--- a/guides/integrations-api/general-concepts/api-versioning.md
+++ /dev/null
@@ -1,90 +0,0 @@
----
-nav:
- title: API Versioning
- position: 40
-
----
-
-# API Versioning
-
-## Overview
-
-Starting with Shopware version 6.4.0.0, we have changed our API versioning strategy. This article covers what we've done and changed, how it used to be, and what the version strategy looks like now.
-
-### Versioning prior to 6.4.0.0
-
-Prior to Shopware 6.4.0.0, the API version was mainly found in the routes themselves.
-
-`/api/v3/example-route`
-
-By using the version, one can ensure that the application continues to work because we are not going to introduce breaking changes within a version. However, versions must still be removed from time to time, which can still break the application.
-
-More on this can be found in our guide [ADR regarding the API version removal](https://github.com/shopware/shopware/blob/trunk/adr/2020-12-02-removing-api-version.md) section.
-
-### Versioning starting with 6.3.5.0
-
-With Shopware 6.4.0.0, we removed the API version from the routes.
-
-**Old**:
-
-`/api/v3/example-route`
-
-**New**:
-
-`/api/example-route`
-
-The version inside the route will keep working with Shopware 6.3.\*, but it will be removed with the next major Shopware version, 6.4.0.
-
-### Deprecations
-
-Deprecations are now added with patch and minor releases but only removed with a major release. This has always been the case for the Core and is now adapted to the API.
-
-Also, deprecated fields and routes are now shown in the Swagger documentation. Have a look at the FAQ beneath to learn how to open Swagger. Have a look for the `@deprecated` annotation on routes or the `Deprecated` flag on entity fields to see which fields or routes are deprecated in the code.
-
-### Route and field availability
-
-The Swagger API reference now includes the necessary information about the route and field availability. For routes, this can look like this:
-
-
-
-Note the availability information.
-
-Same for fields, here is an example of how it would look like:
-
-
-
-### API expectations
-
-API expectations can be used as a request header to define the necessary conditions for the server side. Example conditions could be the Shopware version, the existence of plugins, or the version of a plugin. There are some examples:
-
-```text
-GET /api/test
-sw-expect-packages: shopware/core:~6.4
-```
-
-This would expect that at least Shopware with version 6.4 is installed.
-
-```text
-GET /api/test
-sw-expect-packages: shopware/core:~6.4,swag/paypal:*
-```
-
-This would expect that the Shopware version is at least 6.4 and PayPal is installed in any version.
-
-If the conditions are not met, the backend will answer with a *417 Expectation Failed* error.
-
-## FAQ
-
-### I ensure that my application will keep on working by using the version in the route. What now?
-
-Yes, this was necessary for the previous versioning strategy since breaks were also introduced with Shopware minor releases. The new versioning strategy comes with the benefit that breaks are only introduced with major releases, which were always breaking anyway. Thus, one route will keep working for you until the next major release.
-
-### How do I get the currently used version via the API?
-
-You can read the currently used version in the API as well. Starting with Shopware 6.3.5.0, you can use this route to fetch the current version: `GET /api/_info/version`
-
-Prior to that, the version was readable using the following route: `GET /api/v2/_info/config`
-
-### How do I open up the Stoplight page?
-
-Navigate to the following URL in your shop: `/api/_info/stoplightio.html`
diff --git a/guides/integrations-api/general-concepts/generated-reference.md b/guides/integrations-api/general-concepts/generated-reference.md
deleted file mode 100644
index aa7f387b95..0000000000
--- a/guides/integrations-api/general-concepts/generated-reference.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-nav:
- title: Generated Reference
- position: 30
-
----
-
-# Generated Reference
-
-Shopware generates schemas for both HTTP APIs that can be interpreted by API client libraries and documentation tools, such as [Stoplight.io](https://stoplight.io/).
-
-These schemas are generated using PHP annotations based on the [swagger-php](https://github.com/zircote/swagger-php) library. When building API extensions, you can also leverage these annotations to let Shopware generate standardized endpoint documentation for your custom endpoints on-the-fly.
-
-::: warning
-Due to security restrictions, your **`APP_ENV`** environment variable has to be set to **`dev`** to access any of the specifications described below.
-:::
-
-## Stoplight
-
-The easiest way to access the generated schema is Stoplight. [Stoplight](https://docs.stoplight.io/) is a collaborative platform equipping your team with tooling across the API lifecycle that helps them build quality APIs efficiently. Shopware already ships with these user interfaces. They are accessible at the following endpoint relative to their respective base path:
-
-```text
-/(api|store-api)/_info/stoplightio.html
-```
-
-::: info
-The above path is relative and contains `api` (Admin API) and `store-api` seperated by a pipe. Please choose the appropriate option.
-:::
-
-You will find a list of all generic endpoints (entity endpoints like product, category, etc.) for the **Admin API** here `api/_info/stoplightio.html?type=jsonapi#/` or access it via the top navigation bar.
-
-## OpenAPI schema
-
-If you don't want to bother with the UI but just fetch the schema definition instead, use the following endpoint:
-
-```text
-/(api|store-api)/_info/openapi3.json
-```
-
-## Entity schema
-
-If you would like to access the schema definitions of all available entities instead of an endpoint reference, use one of the corresponding schema endpoints instead:
-
-```text
-/(api|store-api)/_info/open-api-schema.json
-```
diff --git a/guides/integrations-api/general-concepts/index.md b/guides/integrations-api/general-concepts/index.md
deleted file mode 100644
index 7a17689adf..0000000000
--- a/guides/integrations-api/general-concepts/index.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-nav:
- title: General Concepts
- position: 10
-
----
-
-# General Concepts
-
-Even though the Admin API and the Store API serve very different purposes, they have some commonalities handy to be aware of.
-
-## Querying data
-
-For the Admin API these apply to the `/search` endpoint, whilst for the Store API they apply to almost every endpoint that returns a list of records.
-
-It starts with a very simple underlying concept, which encapsulates your entire search description in one generic object, referred to as the **search criteria**.
-
-<PageRef page="search-criteria" />
-
-There are some additional instructions that can be specified using **request headers**.
-
-<PageRef page="request-headers" />
-
-## Documentation
-
-Here you find a common approach regarding the way that Shopware provides endpoint references for its APIs:
-
-<PageRef page="generated-reference" />
-
-## API versioning
-
-Starting with Shopware version 6.4.0.0, we changed our API versioning strategy. The following article will cover what has been done and changed, how it used to be and how the version strategy looks like now.
-
-<PageRef page="api-versioning" />
-
-These topics provide essential foundations for effective API development and usage in Shopware.
diff --git a/guides/integrations-api/index.md b/guides/integrations-api/index.md
deleted file mode 100644
index 784a91bc0f..0000000000
--- a/guides/integrations-api/index.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-nav:
- title: Integrations / API
- position: 40
-
----
-
-# Integrations/API
-
-Generally, Shopware provides two APIs that serve two aspects of integrations with our platform. Both APIs are based on HTTP and though they serve different use cases, they share some underlying concepts. We recommend understanding these concepts before diving deeper into either of the APIs.
-
-<PageRef page="general-concepts/" />
-
-## Customer-facing interactions - Store API
-
-Frontend applications usually provide interfaces for users \(customers\). These applications usually don't expose sensitive data and have two layers of users - anonymous and authenticated i.e., unregistered and registered. Payloads are usually small, performance and availability are critical.
-
-<PageRef page="https://shopware.stoplight.io/docs/store-api/7b972a75a8d8d-shopware-store-api" title="Store API Endpoint Reference" target="_blank" />
-
-## Backend-facing integrations - Admin API
-
-These integrations are characterized by the exchange of structured data, synchronizations, imports, exports and notifications. Performance is also important in terms of high data loads rather than fast response times. Consistency, error handling, and transaction-safety are critical.
-
-<PageRef page="https://shopware.stoplight.io/docs/admin-api/8d53c59b2e6bc-shopware-admin-api" title="Admin API Endpoint Reference" target="_blank" />
-
-Shopware's Store and Admin APIs offer essential technical resources for you to interact with and customize the platform's core functions, enabling tailored solutions and seamless integration.
diff --git a/guides/legacy-setups/migrate-zip-to-composer-project.md b/guides/legacy-setups/migrate-zip-to-composer-project.md
new file mode 100644
index 0000000000..1887b5de35
--- /dev/null
+++ b/guides/legacy-setups/migrate-zip-to-composer-project.md
@@ -0,0 +1,151 @@
+---
+nav:
+ title: Migrate Zip Installation to Composer Project
+ position: 100
+---
+
+# Migrate from Zip Installation to Composer Project Template
+
+:::info
+This guide only applies to legacy Shopware installations created before version 6.5 using the deprecated zip distribution. For new projects, use the recommended [Docker setup](../../installation/docker-setup.md).
+:::
+
+## Background
+
+Before Shopware 6.5, Shopware was distributed for installation as a zip archive containing all required dependencies. This approach has been replaced by a Composer-based project template using Symfony Flex.
+
+The modern setup provides:
+
+* Proper dependency management
+* Cleaner configuration handling
+* Symfony Flex integration
+* Easier CI/CD workflows
+* Better extension management
+
+## Automatic migration (Recommended)
+
+With Shopware CLI, automatic migration is possible:
+
+```bash
+shopware-cli project autofix flex
+```
+
+This converts the installation to a Symfony Flex-based project structure.
+
+## Manual migration
+
+If automatic migration is not possible, follow these steps.
+
+### 1. Create a Backup
+
+Before making any changes:
+
+* Ensure a clean Git state
+* Either stash everything, or create a full backup of files and database
+
+### 2. Adjust Root `composer.json`
+
+Add the Symfony Flex configuration:
+
+First, adjust your root `composer.json`. Add the following lines to your `composer.json`:
+
+```json
+"extra": {
+ "symfony": {
+ "allow-contrib": true,
+ "endpoint": [
+ "https://raw.githubusercontent.com/shopware/recipes/flex/main/index.json",
+ "flex://defaults"
+ ]
+ }
+}
+```
+
+Next, replace all the existing scripts:
+
+```json
+"scripts": {
+ "auto-scripts": [],
+ "post-install-cmd": [
+ "@auto-scripts"
+ ],
+ "post-update-cmd": [
+ "@auto-scripts"
+ ]
+}
+```
+
+Finally, remove any fixed PHP platform configuration as it will now be determined by the required packages:
+
+```diff
+"config": {
+ "optimize-autoloader": true,
+- "platform": {
+- "php": "7.4.3"
+- },
+ "sort-packages": true,
+ "allow-plugins": {
+ "composer/package-versions-deprecated": true
+ }
+},
+```
+
+### 3. Clean up legacy template files
+
+After installing the new Composer packages, remove obsolete files:
+
+```bash
+rm -r .dockerignore \
+ .editorconfig \
+ .env.dist \
+ .github \
+ .gitlab-ci \
+ .gitlab-ci.yml \
+ Dockerfile \
+ docker-compose.yml \
+ easy-coding-standard.php \
+ PLATFORM_COMMIT_SHA \
+ artifacts \
+ bin/deleted_files_vendor.sh \
+ bin/entrypoint.sh \
+ bin/package.sh \
+ config/etc \
+ src \
+ config/secrets \
+ config/services \
+ config/services.xml \
+ config/services_test.xml \
+ license.txt \
+ phpstan.neon \
+ phpunit.xml.dist \
+ psalm.xml
+```
+
+Create a fresh environment file:
+
+```bash
+touch .env
+```
+
+### 4. Install required Composer packages
+
+Ensure Composer is installed before proceeding. Follow the [official documentation](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos) for instructions.
+
+To install Symfony Flex, run the following commands and allow both new Composer plugins:
+
+```bash
+composer require "symfony/flex:*" "symfony/runtime:*"
+
+composer recipe:install --force --reset
+```
+
+### 5. Update environment variables
+
+Adjusting environment variables may be necessary as the names have changed:
+
+| **Old name** | **New name** |
+|-------------------|----------------|
+| MAILER_URL | MAILER_DSN |
+| SHOPWARE_ES_HOSTS | OPENSEARCH_URL |
+
+After reviewing the changes, commit them to the Git repository. All upcoming config changes can be applied with `composer recipes:update`.
diff --git a/guides/plugins/apps/starter/index.md b/guides/plugins/apps/starter/index.md
deleted file mode 100644
index fb2212a72d..0000000000
--- a/guides/plugins/apps/starter/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: App Starter Guides
- position: 10
-
----
-
-# App Starter Guides
-
-The app starter guide provides a comprehensive approach to extending the platform's functionality. The following section guides you on creating custom API endpoints with App scripts, reading and writing data to/from Shopware, and creating custom admin extensions.
diff --git a/guides/plugins/index.md b/guides/plugins/index.md
deleted file mode 100644
index ce6d056686..0000000000
--- a/guides/plugins/index.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-nav:
- title: Extensions
- position: 20
-
----
-
-# Extensions
-
-As a Shopware developer, your primary focus is developing extensions that enhance or modify Shopware's functionality. Shopware offers three extension types—Plugins, Themes, and Apps—each with its own benefits and implications.
-
-To dive straight in, take a look at our introduction guides, which provide essential information on how to create, configure, and extend your store with Shopware extensions:
-
-<PageRef page="plugins/plugin-base-guide" />
-
-<PageRef page="apps/app-base-guide" />
-
-<PageRef page="themes/theme-base-guide" />
-
-## At a glance
-
-This comparison table aims to help you decide which Shopware extension type best fits your use case.
-
-| Task | Plugin | Theme | App | Remarks |
-|:--------------------------------------------|:-------|:-----------------------------|:----|:-------------------------------------------------------------------------------------------------------------|
-| Change Storefront appearance | ✅ | ✅ | ✅ | |
-| Add admin modules | ✅ | ❌ | ✅ | |
-| Execute webhooks | ✅ | ❌ | ✅ | Apps' main functionality is to call webhooks, but plugins can be implemented to do that as well. |
-| Add custom entities | ✅ | ❌ | ✅ | |
-| Modify database structure | ✅ | ❌ | ❌ | |
-| Integrate payment providers | ✅ | ❌ | ✅ | |
-| Publish in the Shopware Store | ✅ | ✅ | ✅ | |
-| Install in Shopware 6 Cloud Shops | ❌ | ❌ (unless delivered via App) | ✅ | While theme plugins can’t be installed in Cloud, Apps can include themes and provide the same functionality. |
-| Install in Shopware 6 self-hosted Shops | ✅ | ✅ | ✅ | Apps can be installed and used since Shopware 6.4.0.0. |
-| Add custom logic/routes/commands | ✅ | ❌ | ✅ | Apps extract functionalities/logic into separate services, so technically, they can add custom logic. |
-| Control order of style/template inheritance | ❌ | ✅ | ✅ | |
diff --git a/guides/plugins/plugins/administration/index.md b/guides/plugins/plugins/administration/index.md
deleted file mode 100644
index 4d6e58719c..0000000000
--- a/guides/plugins/plugins/administration/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Administration
- position: 60
-
----
-
-# Administration
-
-Shopware allows to extend the functionality of the Shopware administration panel, providing additional features and customization options for managing the e-commerce platform. The plugin allows businesses to tailor the administration interface to their specific needs, adding custom sections, modules, services, or functionalities to streamline their workflow and enhance the user experience. The administration plugin offers flexibility in configuring dashboards, menu structures, permissions, and settings, empowering businesses to create a customized and efficient administration experience that aligns with their unique requirements.
diff --git a/guides/plugins/plugins/administration/system-updates/meteor-components.md b/guides/plugins/plugins/administration/system-updates/meteor-components.md
deleted file mode 100644
index d93dab20af..0000000000
--- a/guides/plugins/plugins/administration/system-updates/meteor-components.md
+++ /dev/null
@@ -1,83 +0,0 @@
----
-nav:
- title: Upgrading to Meteor Components
- position: 260
----
-
-# Future Development Roadmap: Upgrading to Meteor Components
-
-> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change.
-> This document serves as a general guideline for our development direction.
-
-## Introduction
-
-With the release of Shopware 6.7, we will replace several current administration components with components from the [Meteor Component Library](https://meteor-component-library.vercel.app/).
-
-## Why Meteor Components?
-
-The Meteor Component Library is Shopware's official collection of reusable components used across multiple Shopware projects and built on the Shopware Design System.
-
-Using a shared component library offers several advantages:
-
-- **Consistent Design**: All components follow the Shopware Design System guidelines.
-- **Consistent Behavior**: All components share standardized behavior patterns and API conventions.
-- **Reusability**: Components can be seamlessly integrated across different projects and apps.
-- **Maintenance**: Updates and improvements to components are managed centrally and automatically propagate to all projects using the component library.
-
-## Migration guide
-
-For each component being replaced, we provide a detailed upgrade guide that explains the migration process from the old component to the new Meteor Component. You can find these guides in the technical upgrade documentation for the release.
-
-## Using Codemods for migration
-
-To simplify the plugin migration process, we provide codemods that automatically replace old components with new Meteor Components.
-
-### Prerequisites
-
-- A [development installation of Shopware](https://github.com/shopware/shopware) must be installed
-- Your plugin must be located in the `custom/plugins` folder
-
-### Running the Migration Tool
-
-1. Execute the following composer command:
-
- ```bash
- # Main command which also outputs the help text
- composer run admin:code-mods
-
- ## Example with arguments
- # composer run admin:code-mods -- --plugin-name example-plugin --fix -v 6.7
- ```
-
-2. Provide your plugin name and target Shopware version for migration
-3. The tool will:
- - Automatically replace compatible components with Meteor Components
- - Add guidance comments for components that require manual migration
- - Fixes some other deprecated code where possible
-
-## Supporting Extension Developers
-
-To support extension developers and ensure compatibility between Shopware 6.6 and Shopware 6.7, a new prop called `deprecated` has been added to Shopware components.
-
-- **Prop Name**: `deprecated`
-- **Default Value**: `false` (uses the new Meteor Components by default)
-- **Purpose**:
- - When `deprecated` is set to `true`, the component will render the old (deprecated) version instead of the new Meteor Component.
- - This allows extension developers to maintain a single codebase compatible with both Shopware 6.6 and 6.7 without being forced to immediately migrate to Meteor Components.
-
-Example:
-
-```html
-<!-- Uses mt-button in 6.7 and sw-button-deprecated in 6.6 -->
-<template>
- <sw-button />
-</template>
-
-
-<!-- Uses sw-button-deprecated in 6.6 and 6.7 -->
-<template>
- <sw-button deprecated />
-</template>
-```
-
-> **Important:** Although the old components can still be used with the `deprecated` prop, we highly recommend migrating to Meteor Components whenever possible to align with future Shopware development.
diff --git a/guides/plugins/plugins/administration/system-updates/pinia.md b/guides/plugins/plugins/administration/system-updates/pinia.md
deleted file mode 100644
index 9e45a5d6a5..0000000000
--- a/guides/plugins/plugins/administration/system-updates/pinia.md
+++ /dev/null
@@ -1,265 +0,0 @@
----
-nav:
- title: Upgrading to Pinia
- position: 261
----
-
-# Migration from Vuex in Shopware to Pinia
-
-## Introduction
-
-With the release of Shopware 6.7, we will replace Vuex with [Pinia](https://pinia.vuejs.org/) as the state management library for the administration.
-
-## Why Pinia?
-
-Migrating to Pinia simplifies state management with an intuitive API, no need for mutations, better TypeScript support, and seamless integration with Vue 3 Composition API. It’s lightweight, modular, and offers modern features like devtools support, making it a more efficient alternative to Vuex.
-
-## Migration Guide
-
-To migrate a Vuex store to Pinia, you need to make some changes to the store definition and how you access it in components.
-
-- First, register it with `Shopware.Store.register` and define the store with `state`, `getters`, and `actions` properties:
-
-**Before (Vuex):**
-
-```javascript
-export default {
- namespaced: true,
-
- state: {
- // Initial state
- ...
- },
- mutations: {
- ...
- },
- getters: {
- ...
- },
- actions: {
- ...
- },
-}
-```
-
-**After (Pinia):**
-
-```javascript
-const store = Shopware.Store.register('<storeName>', {
- state: () => ({
- // Initial state
- ...
- }),
- getters: {
- ...
- },
- actions: {
- ...
- },
-});
-export default store;
-```
-
-- You can also register the store with an `id` property in the definition object, for example:
-
-```javascript
-const store = Shopware.Store.register({
- id: '<storeName>',
- state: () => ({
- // Initial state
- }),
- getters: {
- // ...
- },
- actions: {
- // ...
- },
-});
-```
-
-- If you register a store that already exists, it will be overwritten. You can also unregister a store:
-
-```javascript
-Shopware.Store.unregister('<storeName>');
-```
-
-- To register a store from a component or index file, simply import the store file.
-
-**Before (Vuex):**
-
-```javascript
-import productsStore from './state/products.state';
-
-Shopware.State.registerModule('product', productsStore);
-```
-
-**After (Pinia):**
-
-```javascript
-import './state/products.state';
-```
-
-### Key Changes
-
-#### State
-
-In Pinia, `state` must be a function returning the initial state instead of a static object.
-
- ```javascript
- state: () => ({
- productName: '',
- })
- ```
-
-#### Mutations
-
-Vuex `mutations` are no longer needed in Pinia, since you can modify state directly in actions or compute it dynamically.
-
-```javascript
-actions: {
- updateProductName(newName) {
- this.productName = newName; // Directly update state
- },
-},
-```
-
-#### Getters
-
-- There cannot be getters with the same name as a property in the state, as both are exposed at the same level in the store.
-- Getters should be used to compute and return information based on state, without modifying it.
-
-#### TypeScript
-
-We recommend migrating JavaScript stores to TypeScript for stricter typing, better autocompletion, and fewer errors during development.
-
-```typescript
-const store = Shopware.Store.register({
- id: 'myStore',
- ...
-});
-
-export type StoreType = ReturnType<typeof store>;
-```
-
-Then, you can use this type to extend `PiniaRootState`:
-
-```typescript
-import type { StoreType } from './store/myStore';
-
-declare global {
- interface PiniaRootState {
- myStore: StoreType;
- }
-}
-```
-
-### Composables as a Store
-
-With Pinia, you can use reactive properties inside a store and define it like a composable. Keep in mind that only variables and functions returned from the store will be tracked by Pinia in devtools.
-
-```typescript
-const store = Shopware.Store.register('<storeName>', function() {
- const count = ref(0);
-
- const doubled = computed(() => count.value * 2);
-
- function increment() {
- count.value++;
- }
-
- function decrement() {
- count.value--;
- }
-
- return { count, doubled, increment, decrement };
-});
-```
-
-You can also use a composable function defined outside the store. This allows you to encapsulate and reuse logic across different stores or components, promoting better code organization and modularity:
-
-```typescript
-// composables/myComposable.ts
-export function useMyComposable() {
- const count = ref(0);
-
- const doubled = computed(() => count.value * 2);
-
- function increment() {
- count.value++;
- }
-
- function decrement() {
- count.value--;
- }
-
- return { count, doubled, increment, decrement };
-}
-```
-
-```typescript
-// store/myStore.ts
-import { useMyComposable } from '../composables/myComposable';
-
-const store = Shopware.Store.register('myStore', useMyComposable);
-```
-
-### Accessing the Store
-
-To access the store in Vuex, you would typically do:
-
-```javascript
-Shopware.State.get('<storeName>');
-```
-
-When migrating to Pinia, it changes to:
-
-```javascript
-Shopware.Store.get('<storeName>');
-```
-
-### Testing
-
-To test your store, just import it so it's registered. You can use `$reset()` to reset the store before each test:
-
-```javascript
-import './store/my.store';
-
-describe('my store', () => {
- const store = Shopware.Store.get('myStore');
-
- beforeEach(() => {
- store.$reset();
- });
-
- it('has initial state', () => {
- expect(store.count).toBe(0);
- });
-});
-```
-
-When testing components that use Pinia stores, register Pinia as a plugin and reset it before each test:
-
-```javascript
-import { createPinia, setActivePinia } from 'pinia';
-
-const pinia = createPinia();
-
-describe('my component', () => {
- beforeEach(() => {
- setActivePinia(pinia);
- });
-
- it('is a component', async () => {
- const wrapper = mount(await wrapTestComponent('myComponent', { sync: true }), {
- global: {
- plugins: [pinia],
- stubs: {
- // ...
- },
- },
- });
-
- expect(wrapper.exists()).toBe(true);
- });
-});
-```
diff --git a/guides/plugins/plugins/administration/system-updates/vite.md b/guides/plugins/plugins/administration/system-updates/vite.md
deleted file mode 100644
index ae20f20183..0000000000
--- a/guides/plugins/plugins/administration/system-updates/vite.md
+++ /dev/null
@@ -1,158 +0,0 @@
----
-nav:
- title: Changing from Webpack to Vite
- position: 260
----
-
-# Future Development Roadmap: Changing from Webpack to Vite
-
-> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change.
-> This document serves as a general guideline for our development direction.
-
-## Introduction
-
-We are planning substantial changes to the way we build our Vue.js application.
-The current Webpack build system has been in place for quite some time now, but like everything in tech, it becomes outdated sooner than later. Additionally to Webpack being slow and outdated, we identified a security risk for the future of our application. Many Webpack maintainers have moved on to other projects. Therefore, the Webpack project no longer receives significant updates. The same applies to the Webpack loaders we currently use.
-
-## Introducing Vite
-
-The Vue.js ecosystem has built its own bundler: Vite. Vite is fast, easier to configure and the new standard for Vue.js applications. That's why we decided to switch to Vite with Shopware 6.7.
-
-## Consequences for extensions
-
-For apps there are no consequences as your build process is already decoupled from Shopware. For plugins you only need to get active if you currently extend the webpack config by providing your own `webpack.config.js` file.
-
-### Migrate the custom webpack config to Vite
-
-If you have a custom webpack config, you need to migrate it to Vite. You need to do the following steps:
-
- 1. Create a new config file `vite.config.mts` to your plugin in the `YourApp/src/Resources/app/administration/src` directory. Previously you had a `webpack.config.js` in the following directory: `YourApp/src/Resources/app/administration/build/`
- 2. Remove the old `webpack.config.js` file
- 3. Make sure to remove all webpack related dependencies from your `package.json` file
- 4. Make sure to add the Vite dependencies to your `package.json` file
-
-A basic config migration could look like this:
-
-```javascript
-// Old Webpack config
-module.exports = () => {
- return {
- resolve: {
- alias: {
- '@example': 'src/example',
- }
- }
- };
-};
-```
-
-```typescript
-// New Vite config
-import { defineConfig } from 'vite';
-
-export default defineConfig({
- resolve: {
- alias: {
- '@example': 'src/example',
- },
- },
-});
-```
-
-Of course, this is a very basic example. The Vite config can be much more complex and powerful. You can find more information about the Vite config in the [Vite documentation](https://vite.dev/config/). Depending on your webpack config, the migration can be very individual.
-
-## Implementation details
-
-In this section we'll document the implementation details of the new Vite setup.
-
-### Feature flag
-
-The system is already in place and can be tested by activating the feature flag: `ADMIN_VITE`.
-
-### Bundle information
-
-The information about all active bundles/plugins is written to `<shopwareRoot>/var/plugins.json` by the `Shopware\Core\Framework\Plugin\Command\BundleDumpCommand`. This command can be triggered standalone by running `php bin/console bundle:dump`. It is also part of the composer commands `build:js:admin`, `build:js:storefront`, `watch:admin` and `watch:storefront`. This file is used to load all the Shopware Bundles and custom plugins.
-
-### Building the Shopware Administration
-
-The command responsible for building the Shopware Administration with all extensions remains `composer build:js:admin`.
-
-### Building the core
-
-The Vite config located under `<shopwareRoot>/src/Administration/Resources/app/administration/vite.config.mts` is only responsible for the core without extensions. Currently there are a few file duplications because Vite requires different module loading order. You can recognize these files, they look like this: `*.vite.ts`. So for example the entry file `<shopwareRoot>/src/Administration/Resources/app/administration/src/index.vite.ts`.
-
-### Building extensions
-
-The script responsible for building all extensions is located at `<shopwareRoot>/src/Administration/Resources/app/administration/build/plugins.vite.ts`. This script uses the JS API of Vite to build all extensions. As mentioned above, it's still part of the `composer build:js:admin` command and needs no manual execution.
-
-The script will do the following:
-
-1. Get all bundles/plugins from the `<shopwareRoot>/var/plugins.json`
-2. Call `build` from Vite for each plugin
-3. The `build` function of Vite will automatically load `vite.config` files from the path of the entry file.
-
-### Dev mode/HMR server
-
-The command responsible for serving the application in dev mode (HMR server) is still `composer watch:admin`. For the core it's just going to take the `vite.config.mts` again and this time the `plugins.vite.ts` script will call `createServer` for each plugin.
-
-### Loading Vite assets
-
-Once built the right assets need to be loaded somehow into the administration. For the core we use the `pentatrion_vite` Symfony bundle. Loading the correct file(s) based on the `entrypoints.json` file generated by its counterpart `vite-plugin-symfony`. For bundles and plugins the boot process inside the `application.ts` will load and inject the entry files based on the environment.
-
-Production build:
-
-- Information is taken from the `/api/_info/config` call
-
-Dev mode/HMR server:
-
-- Information is served by our own Vite plugin `shopware-vite-plugin-serve-multiple-static` in form of the `sw-plugin-dev.json` file requested by the `application.ts`
-
-## Vite plugins
-
-To accomplish all this, we created a few Vite plugins and in this section we'll take the time to explain what they do. All our Vite plugin names are prefixed with `shopware-vite-plugin-`. I'll leave this out of the headlines for better readability.
-
-### asset-path
-
-This plugin manipulates the chunk loading function of Vite, to prepend the `window.__sw__.assetPath` to the chunk path. This is needed for cluster setups, serving the assets from a S3 bucket.
-
-### static-assets
-
-Copies static admin assets from `static` to the output directory so they can get served.
-
-### serve-multiple-static
-
-Serves static assets in dev mode (HMR server).
-
-### vue-globals
-
-Replacing all Vue imports in bundles/plugins to destructure from `Shopware.Vue`. This solves the problem of having multiple Vue instances. It does this by creating a temporary file exporting the Shopware.Vue and adding an alias to point every Vue import to that temporary file. This way it will result in bundled code like this:
-
-From this:
-
-```vue
-// From this
-<script setup>
-import { ref } from 'vue';
-</script>
-
-// To this
-<script setup>
-const { ref } = window['Shopware']['Vue'];
-</script>
-```
-
-### override-component
-
-Registering `*.override.vue` files automatically. It will search for all files matching the override pattern and automatically import them into the bundle/plugin entry file. Additionally, these imports will be registered as override components by calling `Shopware.Component.registerOverrideComponent`. This will make sure that all overrides are loaded at any time as soon as the bundle/plugin script is injected. To learn more about the new overrides take a look at the Vue native docs right next to this file.
-
-### twigjs
-
-Transforming all `*.html.twig` files in a way that they can be loaded by Vite.
-
-## HMR reloading
-
-A quick note on HMR (Hot Module Replacement). Vite is only capable of reloading `*.vue` files. This means that we can only leverage the HMR by the time we transitioned everything to SFC (Single File Components) but once we do the Vite setup will be able to distinguish between changes in a plugin or the core.
-
-## Performance
-
-Vite is able to build the core Administration in ~18s on my system. This is a saving of over 50% compared to Webpack. In dev mode it's similar but not directly comparable. The Vite dev server starts instantly and moves the loading time to the first request. Webpack on the other hand compiles a long time upfront until the server is ready.
diff --git a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md b/guides/plugins/plugins/administration/system-updates/vue-migration-build.md
deleted file mode 100644
index ecdbbe522d..0000000000
--- a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md
+++ /dev/null
@@ -1,147 +0,0 @@
----
-nav:
- title: Removing Vue Migration Build
- position: 260
----
-
-# Future Development Roadmap: Removing Vue Migration Build
-
-> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change.
-> This document serves as a general guideline for our development direction.
-
-## Introduction
-
-Prior to Shopware 6.7, we utilized the Vue migration build to facilitate the transition from Vue 2 to Vue 3 for plugin developers. This approach allowed most public APIs to behave similarly to Vue 2 while enabling gradual migration.
-
-With the release of Shopware 6.7, the Vue migration build will be removed. All plugins must be fully migrated to Vue 3 without relying on the migration build.
-
-## Why remove the Vue migration build?
-
-The Vue migration build was a temporary solution to help transition from Vue 2 to Vue 3. However, maintaining it indefinitely would introduce complexity, potential performance bottlenecks, and incompatibility with future Vue versions. Removing it ensures that all plugins fully adopt Vue 3, leveraging its improved reactivity system, better TypeScript support, and performance enhancements.
-
-## Migration guide
-
-Shopware's administration is built using Vue 3, and all plugins should be updated accordingly. We recommend referring to the official [Vue 3 migration guide](https://v3-migration.vuejs.org/) for detailed information on breaking changes and deprecations.
-
-Below are some of the most common changes observed in our codebase. This list is not exhaustive, so always consult the official guide for comprehensive migration steps.
-
-### Common Migration Changes
-
-#### `$listeners` removed
-
-In Vue 2, `$listeners` was used to access event listeners passed to a component. In Vue 3, event listeners are now included in `$attrs`.
-
-Before (Vue 2):
-
-```vue
-<template>
- <sw-button v-on="$listeners">Click me</sw-button>
-</template>
-```
-
-After (Vue 3):
-
-```vue
-<template>
- <sw-button v-bind="$attrs">Click me</sw-button>
-</template>
-```
-
-More detailed guide about [`$listeners` breaking changes](https://v3-migration.vuejs.org/breaking-changes/listeners-removed.html).
-
-#### `$scopedSlots` removed
-
-Previously, scoped slots were accessed using `$scopedSlots`. In Vue 3, `$slots` now unifies all slots and exposes them as functions.
-
-Before (Vue 2):
-
-```js
-this.$scopedSlots.header
-```
-
-After (Vue 3):
-
-```js
-this.$slots.header()
-```
-
-More detailed guide about [`$slots` unification breaking changes](https://v3-migration.vuejs.org/breaking-changes/slots-unification.html).
-
-#### `$children` removed
-
-Vue 2 allowed access to child components using `$children`. In Vue 3, this is no longer supported, and you should use template refs instead.
-
-Before (Vue 2):
-
-```js
-this.$children.childrenMethod();
-```
-
-After (Vue 3):
-
-```js
-// <sw-child ref="childrenRef" />
-
-this.$refs.childrenRef.childrenMethod();
-```
-
-More detailed guide about [`$children` breaking changes](https://v3-migration.vuejs.org/breaking-changes/children).
-
-#### Some Events API removed
-
-The methods `$on`, `$off` and `$once` are removed in Vue 3 without a replacement. You can still use `$emit` to trigger event handlers declaratively attached by a parent component.
-
-Alternatively you can use inject/provide to pass down event handlers using a registration pattern.
-
-It is not possible to give a general guide for this change. You need to adjust your code based on your specific use case. Here is an example how you could adjust your code:
-
-Before (Vue 2):
-
-```js
-created() {
- this.$parent.$on('doSomething', this.eventHandler);
-},
-
-beforeDestroy() {
- this.$parent.$off('doSomething', this.eventHandler);
-}
-```
-
-After (Vue 3):
-
-```js
-// The parent component needs to provide the event handler
-inject: ['registerDoSomething', 'unregisterDoSomething'],
-
-created() {
- this.registerDoSomething(this.eventHandler);
-},
-
-beforeDestroy() {
- this.unregisterDoSomething(this.eventHandler);
-}
-```
-
-More detailed guide about [Events API breaking changes](https://v3-migration.vuejs.org/breaking-changes/events-api.html).
-
-#### `$set`, `$delete` removed
-
-Vue 2 required `$set` and `$delete` for reactive property modifications. Vue 3’s new reactivity system, based on ES6 Proxies, removes the need for these methods.
-
-Before (Vue 2):
-
-```js
-this.$set(this.myObject, 'key', 'value');
-this.$delete(this.myObject, 'key');
-```
-
-After (Vue 3):
-
-```js
-this.myObject.key = 'value';
-delete this.myObject.key;
-```
-
-## Conclusion
-
-With Shopware 6.7, the Vue migration build will be fully removed. To ensure compatibility, all plugins must be updated to Vue 3 following the official migration guide. If you encounter challenges during migration, refer to the official Vue 3 documentation or seek assistance from the Shopware developer community.
diff --git a/guides/plugins/plugins/api/index.md b/guides/plugins/plugins/api/index.md
deleted file mode 100644
index 94a991f7dc..0000000000
--- a/guides/plugins/plugins/api/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: API
- position: 90
-
----
-
-# API
-
-Commercial plugins are pre-built extensions developed by third-party vendors that offer specific features and integrations. In some cases, commercial plugins may expose their own APIs, which developers can use to interact with the plugin's functionalities allowing customization and integration with other systems.
-
-Overall, commercial plugins and APIs work together to expand the capabilities of the Shopware platform. Commercial plugins offer ready-to-use solutions, while APIs provide the flexibility for developers to build custom integrations and extend the functionality of Shopware even further.
diff --git a/guides/plugins/plugins/framework/filesystem/index.md b/guides/plugins/plugins/framework/filesystem/index.md
deleted file mode 100644
index c5f8e20a8a..0000000000
--- a/guides/plugins/plugins/framework/filesystem/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Filesystem
- position: 70
-
----
-
-# Filesystem
-
-Plugins often need the ability to read and write files. Thanks to the [Flysystem](https://flysystem.thephpleague.com/docs/) that Shopware uses, this can be managed very easily. It does not matter whether the files are stored on the local file system or at a cloud provider. The read and write access remains the same. If you want to learn more about the configuration of the file system in Shopware, have a look at the [filesystem guide](../../../../hosting/infrastructure/filesystem). For example, you will learn how to outsource the file system to the Amazon cloud. In a plugin, we don't have to worry about the configuration and can use the advantages of the Flysystem directly.
diff --git a/guides/plugins/plugins/framework/index.md b/guides/plugins/plugins/framework/index.md
deleted file mode 100644
index 0727fe82bb..0000000000
--- a/guides/plugins/plugins/framework/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: Framework
- position: 50
-
----
-
-# Framework
-
-Shopware is a flexible e-commerce framework that allows developers to extend and customize the platform according to specific business needs, creating scalable and personalized online stores. The Shopware framework offers data abstraction, custom fields, events, rules, message queues, file systems, flows, and rate limiters.
-
-More about these features and their extensibility is mentioned in the further sections.
diff --git a/guides/plugins/plugins/framework/rate-limiter/index.md b/guides/plugins/plugins/framework/rate-limiter/index.md
deleted file mode 100644
index 15ca1de8f0..0000000000
--- a/guides/plugins/plugins/framework/rate-limiter/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Rate Limiter
- position: 90
-
----
-
-# Rate Limiter
-
-A rate limiter controls the rate or frequency at which API requests can be made. It sets limits on the number of requests that can be processed within a specified time period, preventing excessive usage. Hence eliminating the chance of brute-force attacks. Rate limiters help maintain system stability, protect against misuse, and ensure fair resource allocation by enforcing predefined limits on the rate of incoming requests.
diff --git a/guides/plugins/plugins/framework/rule/index.md b/guides/plugins/plugins/framework/rule/index.md
deleted file mode 100644
index a61e4b808a..0000000000
--- a/guides/plugins/plugins/framework/rule/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Rule
- position: 50
-
----
-
-# Rule
-
-The Rule Builder allows users to add custom rules to create dynamic conditions and actions within the e-commerce platform. Using the Rule Builder, you can define specific criteria based on various attributes, such as customer data, cart contents, order details, or other relevant factors. These custom rules can then trigger specific actions, such as applying discounts, displaying personalized content, or adjusting pricing based on specific conditions. The Rule Builder empowers businesses to create highly tailored and automated experiences for their customers, enhancing the flexibility and customization options within the Shopware framework.
diff --git a/guides/plugins/plugins/framework/store-api/index.md b/guides/plugins/plugins/framework/store-api/index.md
deleted file mode 100644
index c7d807d26d..0000000000
--- a/guides/plugins/plugins/framework/store-api/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Store API
- position: 60
-
----
-
-# Store API
-
-The Store API plugin in Shopware enables the addition of custom endpoints to the existing Store API and the ability to override or extend the functionality of existing endpoints. This allows developers to customize the API according to their specific requirements, providing additional functionality or modifying the behavior of existing endpoints.
diff --git a/guides/plugins/plugins/index.md b/guides/plugins/plugins/index.md
deleted file mode 100644
index 6ceb090859..0000000000
--- a/guides/plugins/plugins/index.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-nav:
- title: Plugins
- position: 10
-
----
-
-# Plugins
-
-Plugins are Shopware's server-side extension type, giving you deep integration with the e-commerce platform. They allow you to extend, overwrite, and modify Shopware’s core capabilities. Unlike apps and themes, plugins run directly inside the shop environment and can interact tightly with the system.
-
-You will likely create a plugin when you need to make profound changes or require complex functionalities such as:
-
-- Custom price calculation
-- Product imports
-- Custom content/product logic
-- Integrating third-party identity providers
-- Dynamic validations
-- Customer tracking or behavioral logic
-
-Refer to our [Plugin Base Guide](plugin-base-guide/) and [Plugin Fundamentals](plugin-fundamentals/) for guidance on plugin development.
-
-::: info
-If your extension focuses only on design changes, a simple template adjustment—typically done through a theme plugin—may be the best choice.
-:::
-
-## Types of plugins
-
-Shopware plugins differ in their folder structure and functionality.
-
-### Plugins
-
-`<shopware project root>/custom/plugins` contains all plugins from the Shopware store. You install and manage these plugins via the Shopware Administration.
-
-### Static plugins
-
-`<shopware project root>/custom/static-plugins` contains all project-specific plugins that are typically committed to the Git repository.
-
-:::info
-The Shopware Administration does not detect static plugins. The project must require them via Composer for them to be installable.
-:::
-
-```bash
-# You can find the vendor/package name in the plugin's composer.json file under "name"
-composer req <vendor>/<plugin-name>
-```
-
-### Symfony bundle / Shopware bundle
-
-You can also use Shopware/Symfony bundles instead of plugins.
-Bundles are a good choice when you want to avoid plugin lifecycle handling or Administration management.
-You install bundles via Composer. They are not managed by the Shopware Administration.
-
-## Feature comparison
-
-::: tip
-
-For customizing projects, we recommend using [bundles](https://developer.shopware.com/docs/guides/plugins/plugins/bundle.html) instead of plugins.
-As bundles are not managed via Administration and don't have a lifecycle, they offer full control over the project.
-
-:::
-
-| Feature | Plugin | Static Plugin | Shopware Bundle | Symfony Bundle |
-|-----------------------------------------------|--------------------|-------------------------|---------------------------------|---------------------------------|
-| Installation | Via Shopware Admin | Via Composer | Via Composer | Via Composer |
-| Repository Location | `custom/plugins` | `custom/static-plugins` | `vendor` or inside `src` folder | `vendor` or inside `src` folder |
-| Lifecycle Events (install, update, uninstall) | Yes | Yes | No | No |
-| Can be managed in Administration | Yes | No | No | No |
-| Can be a Theme | Yes | Yes | Yes | No |
-| Can modify Admin / Storefront with JS/CSS | Yes | Yes | Yes | No |
diff --git a/guides/plugins/plugins/plugin-base-guide.md b/guides/plugins/plugins/plugin-base-guide.md
deleted file mode 100644
index 0f1fbd3ffa..0000000000
--- a/guides/plugins/plugins/plugin-base-guide.md
+++ /dev/null
@@ -1,205 +0,0 @@
----
-nav:
- title: Plugin Base Guide
- position: 10
-
----
-
-# Plugin Base Guide
-
-## Overview
-
-Plugins in Shopware are essentially an extension of [Symfony bundles](plugins-for-symfony-developers). Such bundles and plugins can provide their own resources like assets, controllers, services or tests, which you'll learn in the next guides.
-A plugin is the main way to extend your Shopware 6 instance programmatically.
-
-This section guides you through the basics of creating a plugin from scratch, which can then be installed on your Shopware 6 instance. Refer to the Guide section to know how to [Install Shopware 6](../../installation/).
-
-## Prerequisites
-
-All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line.
-Of course, you'll have to understand PHP, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.
-
-## Create your first plugin
-
-Let's get started with creating your plugin by finding a proper name for it.
-
-### Name your plugin
-
-First, you need to find a name for your plugin. We're talking about a technical name here, so it needs to describe your plugins functionality as short as possible, written in UpperCamelCase. To prevent issues with duplicated plugin names, you should add a shorthand prefix for your company.
-Shopware uses "Swag" as a prefix for that case.
-For this example guide we'll use the plugin name **SwagBasicExample.**
-
-::: info
-Using a prefix for your plugin name is not just a convention we'd recommend, but a hard requirement if you want to publish your plugin in the [Shopware Community Store](https://store.shopware.com/en).
-:::
-
-### **Create the plugin**
-
-Now that you've found your name, it's time to actually create your plugin.
-
-Shopware provides a handy command that you can use to generate the plugin structure. Go to your shopware project's root directory and run the following command:
-
-```bash
-bin/console plugin:create SwagBasicExample
-```
-
-You can pass an addition flag `-c` or `--create-config` in the above command which would also create a demo configuration file in the `Resources` directory. The command will generate all the basic required files that are needed for an extension to be installed on a Shopware instance. Make sure to adjust the namespace in the files as per your need.
-
-If you want to create the structure manually please follow the instructions below:
-
-For this, please navigate to the directory `custom/plugins`, that you should find in your Shopware 6 installation. Inside the `plugins` directory, create a new directory named after your plugin, so it should look like this: `custom/plugins/SwagBasicExample`
-
-By convention, you'll have another directory in there, which is called `src`. This is not required, but recommended. And that's it for the directory structure for now.
-
-Inside your `src` directory, create a PHP class named after your plugin, `SwagBasicExample.php`.
-This new class `SwagBasicExample` has to extend from Shopware's abstract Plugin class, which is `Shopware\Core\Framework\Plugin`.
-
-Apart from this, only the namespace is missing. You can freely define it, but we'd recommend using a combination of your manufacturer prefix and the technical name, so in this `guide` this would be: `Swag\BasicExample`
-
-```php
-// <plugin root>/src/SwagBasicExample.php
-<?php declare(strict_types=1);
-
-namespace Swag\BasicExample;
-
-use Shopware\Core\Framework\Plugin;
-
-class SwagBasicExample extends Plugin
-{
-}
-```
-
-Basically that's it for the PHP part, your basic plugin class is already done.
-
-::: info
-Refer to this video on **[Creating a plugin](https://www.youtube.com/watch?v=_Tkoq5W7woI)** that shows how to bootstrap a plugin. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
-:::
-
-#### The composer.json file
-
-You've created the necessary plugin structure and the plugin base class. The only thing missing for your plugin to be fully functional, is a `composer.json` file inside your plugin's root directory.
-`custom/plugins/SwagBasicExample/composer.json`
-
-This file consists of basic information, that Shopware needs to know about your plugin, such as:
-
-* The technical name
-* The description
-* The author
-* The used license
-* The current plugin version
-* The required dependencies
-* ... and a few more
-
-This file can also be read by [Composer](https://getcomposer.org/), but that's not part of this guide.
-Further information you'll have to add in there: The `type` has to be `shopware-platform-plugin`, so Shopware can safely recognize your plugin as such
-and the `require` field must include at least `shopware/core`, to check for compatibility.
-
-Here's an example `composer.json` for this guide, which will do the trick:
-
-```javascript
-// <plugin root>/composer.json
-{
- "name": "swag/basic-example",
- "description": "Description for the plugin SwagBasicExample",
- "version": "1.0.0",
- "type": "shopware-platform-plugin",
- "license": "MIT",
- "authors": [
- {
- "name": "Shopware"
- }
- ],
- "require": {
- "shopware/core": "~6.6.0"
- },
- "extra": {
- "shopware-plugin-class": "Swag\\BasicExample\\SwagBasicExample",
- "label": {
- "de-DE": "Der angezeigte lesbare Name für das Plugin",
- "en-GB": "The displayed readable name for the plugin"
- },
- "description": {
- "de-DE": "Beschreibung in der Administration für das Plugin",
- "en-GB": "Description in the Administration for this plugin"
- }
- },
- "autoload": {
- "psr-4": {
- "Swag\\BasicExample\\": "src/"
- }
- }
-}
-```
-
-There's another two things that you need to know:
-
-1. The `shopware-plugin-class` information. This has to point to the plugin's base PHP class. The one, that you've previously created.
-2. The whole `autoload` part. This has to mention your [PSR-4](https://www.php-fig.org/psr/psr-4/) namespace. So if you'd like to have another namespace for your plugin, this is the place to go.
-
-::: warning
-The path you've configured in the configuration `autoload.psr-4`, `src/` in this case, will be referred to as `<plugin root>/src` in almost all code examples. If you're using a custom path here, e.g. just a slash `/`, then the examples would be `<plugin root>/` here instead.
-:::
-
-And that's it. The basic structure and all necessary files for your plugin to be installable are done.
-
-::: info
-Refer to this video on **[The composer.json plugin file](https://www.youtube.com/watch?v=CY3SlfwkTm8)** that explains the basic structure of the `composer.json` plugin file. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
-:::
-
-## Install your plugin
-
-You can safely install your plugin now and Shopware should easily recognize it like this.
-
-Open up your command line terminal and navigate to your Shopware 6 directory, the one which also contains the `custom` directory.
-
-Once inside there, you need to refresh the list of plugins, that Shopware knows yet. This is done with the following command:
-
-```bash
-php bin/console plugin:refresh
-```
-
-There might be a warning appearing regarding the `version` of the `composer.json` file, but you can safely ignore that.
-You should end up with a list like the following:
-
-```bash
-Shopware Plugin Service
-=======================
-
- ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- -------------
- Plugin Label Version Upgrade version Author Installed Active Upgradeable
- ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- -------------
- SwagBasicExample The displayed readable name for the plugin 1.0.0 Shopware No No No
- ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- -------------
-```
-
-This output is a **good sign**, because this means Shopware recognized your plugin successfully. But it's not installed yet, so let's do that.
-
-```bash
-php bin/console plugin:install --activate SwagBasicExample
-```
-
-This should print the following output:
-
-```bash
-Shopware Plugin Lifecycle Service
-=================================
-
- Install 1 plugin(s):
- * The displayed readable name for the plugin (v1.0.0)
-
- Plugin "SwagBasicExample" has been installed and activated successfully.
-```
-
-And that's basically it.
-**You've just successfully created your Shopware 6 plugin!**
-
-## Next steps
-
-There's many more things to discover when creating your first plugin. Hence, here's a list of important articles, that may be of interest for you.
-
-* [Installing data with your plugin](plugin-fundamentals/database-migrations)
-* [Learn more about the plugin lifecycle methods](plugin-fundamentals/plugin-lifecycle)
-* [Adding a configuration to your plugin](plugin-fundamentals/add-plugin-configuration)
-* [Learning about the service container](plugin-fundamentals/dependency-injection)
-* [Adding a custom service](plugin-fundamentals/add-custom-service)
-* [Start listening to events](plugin-fundamentals/listening-to-events)
diff --git a/guides/plugins/plugins/plugin-fundamentals/index.md b/guides/plugins/plugins/plugin-fundamentals/index.md
deleted file mode 100644
index 63ffb640f1..0000000000
--- a/guides/plugins/plugins/plugin-fundamentals/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: Plugin fundamentals
- position: 10
-
----
-
-# Plugin Fundamentals
-
-Shopware plugins are PHP-based extensions that enhance the functionality of the Shopware e-commerce platform. They follow a specific directory structure and have a lifecycle for installation, activation, deactivation, and uninstallation. Plugins can utilize hooks and events to interact with core functionality, and they can have controllers, services, and models to handle specific tasks. Plugin configuration options can be defined, and integration with various parts of Shopware is possible.
-
-You will learn more about it in depth in the following sections.
diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md
deleted file mode 100644
index 0598bb51e3..0000000000
--- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md
+++ /dev/null
@@ -1,153 +0,0 @@
----
-nav:
- title: Plugin lifecycle methods
- position: 140
-
----
-
-# Plugin Lifecycle Methods
-
-## Overview
-
-A Shopware plugin can be installed, activated, deactivated and then again uninstalled. Those are some plugin lifecycle methods, which will be covered a bit more in this guide.
-
-## Prerequisites
-
-This guide is built upon our [plugin base guide](../plugin-base-guide), which explains the basics of a plugin as a whole. Make sure to have a look at it to get started on building your first plugin.
-
-## Lifecycle methods
-
-Each of the followings methods are going to be part of the plugin bootstrap, in this example the file will be `<plugin root>/src/SwagBasicExample.php`, which is the bootstrap file of the previously mentioned plugin base guide.
-
-Throughout all of the lifecycle methods, you have access to the [service container](dependency-injection) via `$this->container`.
-
-### Install
-
-The install method of a plugin is executed when the plugin is installed. You can use this method to install all the necessary requirements for your plugin, e.g. a new payment method.
-
-```php
-// <plugin root>/src/SwagBasicExample
-public function install(InstallContext $installContext): void
-{
- // Do stuff such as creating a new payment method
-}
-```
-
-In your install method, you have access to the `InstallContext`, which provides information such as:
-
-* The current plugin version
-* The current Shopware version
-* The `Context`, which provides a lot more of system information, e.g. the currently used language
-* A collection of the [plugin migrations](database-migrations)
-* If the migrations should be executed \(`isAutoMigrate` or `setAutoMigrate` to prevent the execution\)
-
-::: info
-You maybe don't want to create new data necessary for your plugin in the `install` method, even though it seems to be the perfect place. That's because an installed plugin is not automatically active yet - hence some data changes would have an impact on the system before the plugin is even active and therefore functioning. A good rule of thumb is: Only install new data or entities, that can be activated or deactivated themselves, such as a payment method. This way you can create a new payment method in the `install` method, but keep it inactive for now.
-:::
-
-### Uninstall
-
-The opposite of the `install` method. It gets executed once the plugin is uninstalled. You might want to remove the data, that your plugin created upon installation.
-
-::: warning
-You can't simply remove everything that your plugin created previously. Think about a new payment method, that your plugin created and which was then used for actual orders. If you were to remove this payment method when uninstalling the plugin, all the orders that used this payment method would be broken, since the system wouldn't find the used payment method anymore. In this case, you most likely just want to deactivate the respective entity, if possible. Be careful here!
-:::
-
-```php
-// <plugin root>/src/SwagBasicExample
-public function uninstall(UninstallContext $uninstallContext): void
-{
- // Remove or deactivate the data created by the plugin
-}
-```
-
-The `uninstall` method comes with the `UninstallContext`, which offers the same information as the `install` method. There's one more very important information available with the `UninstallContext`, which is the method `keepUserData`.
-
-#### Keeping user data upon uninstall
-
-When uninstalling a plugin, the user is asked if he really wants to delete all the plugin data. The method `keepUserData` of the `UninstallContext` will provide the users decision. If `keepUserData` returns `true`, you should **not** remove important data of your plugin, the user wants to keep them.
-
-```php
-// <plugin root>/src/SwagBasicExample
-public function uninstall(UninstallContext $uninstallContext): void
-{
- parent::uninstall($uninstallContext);
-
- if ($uninstallContext->keepUserData()) {
- return;
- }
-
- // Remove or deactivate the data created by the plugin
-}
-```
-
-::: info
-Refer to this video on **[Uninstalling a plugin](https://www.youtube.com/watch?v=v9OXrUJzC1I)** dealing with plugin uninstall routines. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
-:::
-
-### Activate
-
-The `activate` method is executed once the plugin gets actually activated. You most likely want to do one of the following things here:
-
-* Activate entities that you created in the install method, e.g. such as a payment method
-* Create new entities or data, that you couldn't create in the install method
-
-```php
-// <plugin root>/src/SwagBasicExample
-public function activate(ActivateContext $activateContext): void
-{
- // Activate entities, such as a new payment method
- // Or create new entities here, because now your plugin is installed and active for sure
-}
-```
-
-The `ActivateContext` provides the same information as the `InstallContext`.
-
-### Deactivate
-
-The opposite of the `activate` method. It is triggered once the plugin deactivates the plugin. This method should mostly do the opposite of the plugin's `activate` method:
-
-* Deactivate entities created by the `install` method
-* Maybe remove entities, that cannot be deactivated but would harm the system, if they remained in the system while the plugin is inactive
-
-```php
-// <plugin root>/src/SwagBasicExample
-public function deactivate(DeactivateContext $deactivateContext): void
-{
- // Deactivate entities, such as a new payment method
- // Or remove previously created entities
-}
-```
-
-The `DeactivateContext` provides the same information as the `InstallContext`.
-
-### Update
-
-The `update` method is executed once your plugin gets updated to a new version. You do not need to update database entries here, since this should be done via [plugin migrations](database-migrations). Otherwise you'd have to check if this specific update to an entity was already done in a previous `update` method execution, mostly by using plugin version conditions.
-
-However, of course you can still do that if necessary. Also, non-database updates can be done here.
-
-```php
-// <plugin root>/src/SwagBasicExample
-public function update(UpdateContext $updateContext$context): void
-{
- // Update necessary stuff, mostly non-database related
-}
-```
-
-The `UpdateContext` provides the same information as the `InstallContext`, but comes with one more method. In order to get the new plugin version, you can use the method `getUpdatePluginVersion` in contrast to the `getCurrentPluginVersion`, which will return the currently installed plugin version.
-
-### PostInstall and PostUpdate methods
-
-There are two more lifecycle methods, that are worth mentioning: `PostUpdate` and `PostInstall`, which are executed **after** the respective process of installing or updating your plugin is fully and successfully done.
-
-```php
-// <plugin root>/src/SwagBasicExample
-public function postInstall(InstallContext $installContext): void
-{
-}
-
-public function postUpdate(UpdateContext $updateContext): void
-{
-}
-```
diff --git a/guides/plugins/plugins/plugins-for-symfony-developers.md b/guides/plugins/plugins/plugins-for-symfony-developers.md
deleted file mode 100644
index 41ecf3581c..0000000000
--- a/guides/plugins/plugins/plugins-for-symfony-developers.md
+++ /dev/null
@@ -1,80 +0,0 @@
----
-nav:
- title: Plugins for Symfony developers
- position: 20
-
----
-
-# Plugins for Symfony Developers
-
-## Overview
-
-This guide serves as an entry point for developers familiar with the concepts of `Symfony bundles`.
-
-::: info
-Check out our [Shopware Toolbox PHPStorm extension](../../../resources/tooling/ide/shopware-toolbox) with useful features like autocompletion, code generation or guideline checks.
-:::
-
-## Prerequisites
-
-This guide handles some base concepts of Shopware plugins. Therefore, you may want to have a look at [Plugin base guide](plugin-base-guide) first.
-
-As this guide also references the functionality of Symfony bundles, you should have at least a basic knowledge of it. You may want to have a look or refresh your knowledge on Symfony's [Bundle system](https://symfony.com/doc/current/bundles.html).
-
-## Symfony bundles
-
-A bundle is the Symfony's preferred way to provide additional third-party features to any Symfony application. Those bundles are everywhere: Symfony even outsources many of its core features into external bundles. The template engine `Twig`, the `Security` bundle, the `WebProfiler`, as well as many other third-party bundles can be installed on demand to extend your Symfony application in any way. The Bundle System is Symfony's way of providing an extendable framework with plugin capabilities.
-
-## Shopware plugins
-
-Shopware is building upon the `Symfony Bundle System` to extend its functionality even more. This allows the Shopware Plugin System to function as a traditional plugin system with features like plugin lifecycles and more.
-
-Whenever you create a Shopware plugin, you have to extend the `Shopware\Core\Framework\Plugin` class. If you investigate this class, you will see that this class extends `Shopware\Core\Framework\Bundle`, which in return extends the Symfony's `Bundle` class:
-
-```php
-//
-class YourNamespace\PluginName extends
-
- // plugin lifecycles
- abstract class Shopware\Core\Framework\Plugin extends
-
- // adds support for migrations, filesystem, events, themes
- abstract class Shopware\Core\Framework\Bundle extends
-
- // Symfony base bundle
- abstract class Symfony\Component\HttpKernel\Bundle
-```
-
-As you can see, any Shopware plugin is also a Symfony bundle internally as well, and will be handled as such by Symfony. A plugin adds support for some cases, specific to the Shopware environment. These include, for example, handling plugin migrations and registering Shopware business events.
-
-### Plugin lifecycle
-
-As mentioned before, Shopware extends the `Symfony Bundle System` with some functionality to adjust its use for the Shopware ecosystem. For you as plugin developer, the most important addition is the extended plugin lifecycle.
-
-A Shopware plugin runs through a lifecycle. Your plugin's base class can implement the following methods to execute any sort of installation or maintenance tasks.
-
-| Lifecycle | Description |
-| :--- | :--- |
-| `install()` | Executed on plugin install |
-| `postInstall()` | Executed **after** successful plugin install |
-| `update()` | Executed on plugin update |
-| `postUpdate()` | Executed **after** successful plugin update |
-| `uninstall()` | Executed on plugin uninstallation |
-| `activate()` | Executed **before** plugin activation |
-| `deactivate()` | Executed **before** plugin deactivation |
-
-## Next steps
-
-Now that you know about the differences between a Symfony bundle and a Shopware plugin, you might also want to have a look into the following Symfony-specific topics and how they are integrated in Shopware 6:
-
-* [Dependency Injection](plugin-fundamentals/dependency-injection)
-* [Listening to events](plugin-fundamentals/listening-to-events)
-
-::: info
-Here are some useful videos explaining:
-
-* **[Bundle Methods in a plugin](https://www.youtube.com/watch?v=cUXcDwQwmPk)**
-* **[Symfony services in Shopware 6](https://www.youtube.com/watch?v=l5QJ8EtilaY)**
-
-Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
-:::
diff --git a/guides/plugins/plugins/storefront/index.md b/guides/plugins/plugins/storefront/index.md
deleted file mode 100644
index 2cc1c8d77d..0000000000
--- a/guides/plugins/plugins/storefront/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: Storefront
- position: 70
-
----
-
-# Storefront
-
-Storefront handles the e-commerce platform's front end, including the online store's visual presentation and user interface.
-
-You can customize and enhance the storefront by adding or modifying templates, layouts, styles, and components via plugins. It allows adding custom pages, layouts, dynamic content, filters, media, assets, and styles to create unique and engaging shopping experiences, ensuring a seamless and visually appealing interface for customers. It enables businesses to showcase their products, implement responsive designs, optimize performance, and deliver a personalized shopping journey to online visitors.
diff --git a/guides/plugins/plugins/testing/cypress/cypress-best-practises.md b/guides/plugins/plugins/testing/cypress/cypress-best-practises.md
deleted file mode 100644
index 6557fc91a0..0000000000
--- a/guides/plugins/plugins/testing/cypress/cypress-best-practises.md
+++ /dev/null
@@ -1,235 +0,0 @@
----
-nav:
- title: Best practices on writing end-to-end tests
- position: 12
-
----
-
-# Best practices for writing end-to-end tests
-
-## Overview
-
-A typical E2E test can be complex, with many steps that take a lot of time to complete manually. Because of this complexity, E2E tests can be difficult to automate and slow to execute. The following tips can help reduce the cost and pain of E2E testing and still reap the benefits.
-
-Cypress got you covered with their best practices as well: So please also look at their best practices to get to know their patterns:
-
-<PageRef page="https://docs.cypress.io/guides/references/best-practices.html" title="Best Practices | Cypress Documentation" target="_blank" />
-
-::: warning
-We strongly recommend following Cypress own best practices as well.
-:::
-
-## Amount and prioritization of end-to-end tests
-
-### Video
-
-When it comes to dividing test types, selecting and prioritizing test cases, and thus designing tests, things get a bit more complicated. We have generally aligned our test strategy with the test pyramid, although not 100%. The pyramid states that end-to-end tests should be written in a few but well chosen test cases because end-to-end tests are slow and expensive.
-
-At [Shopware Community Day](https://scd.shopware.com/en-US/) 2020, we gave a talk on how we approach automated testing in Shopware, how far we have come on this journey, and what we have gained so far:
-
-<YoutubeRef video="sxvQoWF4KS0" title="A matter of trust – test - #SCD20 (ENG) - YouTube" target="_blank" />
-
-To sum it up briefly, the end-to-end tests are slow and thus expensive to maintain. That is why we need a way to prioritize our test cases.
-
-### When should I write an end-to-end test
-
-::: danger
-Cover every possible workflow with E2E tests.
-:::
-
-::: tip
-Use proper prioritization to choose test cases covered by E2E tests.
-:::
-
-Due to running times, it is not advisable to cover every single workflow available. The following criteria may help you with that:
-
-* **Cover the most general, most used workflows of a feature**, e.g., CRUD operations. The term "[happy path](https://en.wikipedia.org/wiki/Happy_path)" describes those workflows quite well.
-* **Beware the critical path**: Cover those workflows with E2E tests, which are the most vulnerable and would cause the most damage if broken.
-* **Avoid duplicate coverage**: E2E tests should only cover what they can, usually big-picture user stories \(workflows\) that contain many components and views.
- * Sometimes, unit tests are better suited. For example, use an E2E test to test your application's reaction to a failed validation, not the validation itself.
-
-## Workflow-based end-to-end tests
-
-::: danger
-Write the E2E test as you would write unit tests.
-:::
-
-::: tip
-Writing E2E tests in a "workflow-based" manner means writing the test describing a real user's workflow just like a real user would use your application.
-:::
-
-A test should be written "workflow-based" - We like to use this word very much because it is simply apt for this purpose. You should always keep your persona and goal of an E2E test in mind. The test is then written from the user's point of view, not from the developer's point of view.
-
-## Structure and scope
-
-### Test scope
-
-::: danger
-Write long E2E tests covering lots of workflows and use cases.
-:::
-
-::: tip
-Keep tests as simple as possible. Only test the workflow you explicitly want to test. Ideally, use **one test for one workflow**.
-:::
-
-The second most important thing is to test the workflow you explicitly want to test. Any other steps or workflows to get your test running should be done using API operations in the `beforeEach` hook, as we don't want to test them more than once. For example, if you want to test the checkout process, you shouldn't do all the steps, like creating the sales channel, products, and categories, although you need them to process the checkout. Use the API to create these things and let the test just do the checkout.
-
-You need to focus on the workflow to be tested to ensure minimum test runtimes and to get a valid result of your test case if it fails. For this workflow, you have to think like the end-user would do - Focus on the usage of your feature, not technical implementation.
-
-Other examples of steps or workflow to cut off the actual tests are:
-
-* The routines which should only provide the data we need: Just use test fixtures to create this data to have everything available before the test starts.
-* Logging in to the Administration: You need it in almost every Administration test, but writing it in all tests is pure redundancy and way more error sensitive.
-
-::: info
-This [scope practice](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State) is also mentioned in Cypress best practices as well.
-:::
-
-### Focus on stability first
-
-::: danger
-Design your tests dependent on each other, doing lots of write operations without removing corresponding data.
-:::
-
-::: tip
-Keep tests isolated, enable them to run independently, and restore a clean installation between tests
-:::
-
-It is important to focus on stability as the most important asset of a test suite. A flaky test like this can block the continuous deployment pipeline, making feature delivery slower than it needs to be. Moreover, imagine the following case: Tests that fail to deliver deterministic results: Those flaky test is problematic because they won't show valid results anymore, making them useless. After all, you wouldn't trust one any more than you would trust a liar. If you want to find out more on that topic, including solutions, please take a look at this article:
-
-<PageRef page="https://www.smashingmagazine.com/2021/04/flaky-tests-living-nightmare/" title="Flaky tests" target="_blank" />
-
-This was one of the reasons you need stable tests to create value. To achieve that, you have several possibilities. We will introduce you to some of them in the following paragraphs.
-
-Let's start with some easy strategy. Keep tests as simple as possible, and avoid a lot of logic in each one. Think about it this way, the more you do in a test, the more you can go wrong. In addition, by avoiding big tests, you avoid causing load on your application and resource leaks in your environment.
-
-When planning your test cases and structure, always keep your tests isolated from other tests so that they are able to be run in an independent or random order. Don't ever rely on previous tests. You need to test specs in isolation to take control of your application’s state. Every test is supposed to be able to run on its own and independent from any other tests. This is crucial to ensure valid test results. You can realize these using test fixtures to create all data you need beforehand and take care of the cleanup of your application using an appropriate reset method.
-
-## Choosing selectors
-
-::: danger
-Choose fuzzy selectors which are prone to change, e.g. xpath.
-:::
-
-::: tip
-Use selectors which won't change often.
-:::
-
-XPath selectors are quite fuzzy and rely a lot on the texts, which can change quickly. Please avoid using them as much as possible. If you work in Shopware platform and notice that one selector is missing or not unique enough, just add another one in the form of an additional class.
-
-### Avoid framework specific selectors
-
-::: danger
-Choose framework specific syntax as a selector prone to change, e.g. `.btn-primary`.
-:::
-
-::: tip
-Use individual selectors which won't often change, e.g., `.btn-buy`.
-:::
-
-Using selectors which rely on a framework specific syntax can be unstable because the framework selectors are prone to change. Instead, you should use individual selectors, which are less likely to change.
-
-```html
-<button class="btn btn-primary btn-buy">Add to cart</button>
-```
-
-```javascript
-// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
-cy.get('.btn.btn-primary').click();
-
-// ✓ Instead, you should use a shopware specific class like `.btn-buy`.
-// (This also remains stable when the button variant is changed to, e.g., `.btn-secondary`.)
-cy.get('.btn-buy').click();
-```
-
-```html
-<button
- data-toggle="modal"
- data-target="#exampleModal"
- class="btn btn-primary btn-open-settings">
- Open settings modal
-</button>
-```
-
-```javascript
-// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
-cy.get('[data-toggle="modal"]').click();
-
-// ✓ Instead, you should use a shopware specific class like `.btn-open-settings`.
-cy.get('.btn-open-settings').click();
-```
-
-```html
-<div class="custom-control custom-checkbox">
- <label
- for="tos"
- class="checkout-confirm-tos-label custom-control-label">
- I have read and accepted the general terms and conditions.
- </label>
-</div>
-```
-
-```javascript
-// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
-cy.get('.custom-checkbox label').click();
-
-// ✓ Instead, you should use a shopware specific class like `.checkout-confirm-tos-label`.
-cy.get('.checkout-confirm-tos-label').click();
-```
-
-If there are no suitable selectors available, please add descriptive classes or IDs for your desired elements.
-
-## Waiting in E2E tests
-
-::: danger
-Waiting for arbitrary time periods, e.g., using `cy.wait(500)`
-:::
-
-::: tip
-Use route aliases or assertions to guard Cypress from proceeding until an explicit condition is met.
-:::
-
-Never use fixed waiting times in the form of `.wait(500)` or similar. Using Cypress, you never need to do this. Cypress has a built-in retry-ability in almost every command, so you don't need to wait, e.g., if an element already exists. If you need more than that, we got you covered. Wait for changes in the UI instead, notifications, API requests, etc., via the appropriate assertions. For example, if you need to wait for an element to be visible:
-
-```javascript
-cy.get('.sw-category-tree').should('be.visible');
-```
-
-Another useful way for waiting in the Administration is using Cypress possibility to work with [network requests](https://docs.cypress.io/app/guides/network-requests). Here you can let the test wait for a successful API response:
-
-```javascript
-cy.server();
-
-// Route POST requests with matching URL and assign an alias to it
-cy.route({
- url: '/api/search/category',
- method: 'post'
-}).as('getData');
-
-// Later, you can use the alias to wait for the API response
-cy.wait('@getData').then((xhr) => {
- expect(xhr).to.have.property('status', 200);
-});
-```
-
-::: info
-This [best practice](https://docs.cypress.io/guides/references/best-practices#Unnecessary-Waiting) is also mentioned in Cypress best practices as well. Actually, it can be considered a general best practice to avoid flakiness.
-:::
-
-## Cypress commands and their queue
-
-::: danger
-Using vanilla JavaScript logic alongside cypress commands without further caution
-:::
-
-::: tip
-If you need vanilla Javascript in your test, wrap it in a Cypress `then` or build a custom command to get it queued.
-:::
-
-Cypress commands are asynchronous and get queued for execution at a later time. During execution, subjects are yielded from one command to the next, and a lot of helpful Cypress code runs between each command to ensure everything is in order.
-
-This won't happen with Vanilla JS, though. It will be executed immediately. In the worst case, this difference can cause timing issues. So always wrap your vanilla JavaScript code into Cypress commands or `then` in order to make use of Cypress command queue.
-
-::: warning
-Concerning Cypress `then`: Even though Cypress commands look like promises, they aren't completely the same. Head over to the [Cypress docs](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress#Commands-Are-Not-Promises) for more information.
-:::
diff --git a/guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.md b/guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.md
deleted file mode 100644
index a0186f7ad9..0000000000
--- a/guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.md
+++ /dev/null
@@ -1,558 +0,0 @@
----
-nav:
- title: Cypress End-to-end testing
- position: 11
-
----
-
-# Cypress End-to-End Testing
-
-## Overview
-
-In end-to-end testing \(E2E testing in short\) real user workflows are simulated, whereby as many as possible functional areas and parts of the technology stack used in the application should be included. This way, we are able to put our UI under constant stress and ensure that Shopware's main functionalities are always working correctly.
-
-## Prerequisites
-
-To use Shopware E2E tests, at first you need to have a Shopware 6 installation running. Making sure, that your tests are reliable, you should have a clean installation. Cleanup means no categories, no products, no settings, nothing!
-
-The easiest way to clean up your installation is the initialization. Using the command `composer run init` Shopware 6 gets initialized clean and without demo data. Installation of E2E dependencies can be accomplished separately by running `npm install` in the E2E folder you're using, e.g. for Shopware Administration it's `src/Administration/Resources/app/administration/test/e2e`.
-
-Since our tests should run on an installation that is as close as possible to a release package, we use production mode. If you run the tests on a development environment, the test results may vary.
-
-On top of that, please make sure your shop has a theme assigned. When using `composer run e2e:open` or `run`, this is done automatically.
-
-This guide also won't teach you how to write Cypress tests in general. Please take a look at the official Cypress documentation for further guidance.
-
-<PageRef page="https://docs.cypress.io/" title="Cypress Documentation" target="_blank" />
-
-### Using our testsuite
-
-The [E2E platform testsuite package](https://github.com/shopwareArchive/e2e-testsuite-platform) contains commands and helpers supporting you while building E2E tests for Shopware 6. On top of that, test data management and custom commands are included as well. More on that here: [Command reference](../../../../resources/references/core-reference/commands-reference/).
-
-This test suite is built on top of [Cypress](https://www.cypress.io/) as well as the following Cypress plugins:
-
-* [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests)
-* [cypress-log-to-output](https://github.com/flotwig/cypress-log-to-output)
-* [cypress-file-upload](https://github.com/abramenal/cypress-file-upload)
-
-Here you can find the npm package of our testsuite:
-
-<PageRef page="https://www.npmjs.com/package/@shopware-ag/e2e-testsuite-platform" title="@shopware-ag/e2e-testsuite-platform - npm" target="_blank" />
-
-Please have a look on our [cypress.json](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/3.x/cypress.json), a few of our commands expect some configuration, e.g. viewportHeight and width, because the admin menu only opens if the viewport is wide enough.
-
-## Setup steps
-
-When you use our [Development template](https://github.com/shopwareArchive/development), we provide you some tooling scripts located in `dev-ops/e2e/actions`, to use E2E tests more comfortably.
-
-The`composer` scripts to run our E2E tests in CLI or in Cypress' test runner are explained in the paragraph [Executing e2e tests](end-to-end-testing/#executing-e2e-tests).
-
-<Tabs>
-<Tab title="Plugin setup">
-
-Depending on your environment \(administration or storefront\) please create the following folder structure:
-
-```text
-Resources
- `-- app
- `-- <environment>
- `-- test
- `-- e2e
- `-- cypress
- |-- fixtures
- |-- integration
- |-- plugins
- `-- support
-```
-
-We will cover the use of every folder in detail.
-
-Within the folder `Resources/app/<environment>/test/e2e`, please run `npm init -y` to generate a `package.json` file. It is very convenient to place a script inside the newly created `package.json` to run the tests locally. Please add the following section to do so:
-
-```javascript
-"scripts": {
- "open": "node_modules/.bin/cypress open"
-},
-```
-
-Now install this package with the following command:
-
-```text
-npm install @shopware-ag/e2e-testsuite-platform
-```
-
-As next step, please create a new file `e2e/cypress/plugins/index.js` with the following content:
-
-```javascript
-module.exports = require('@shopware-ag/e2e-testsuite-platform/cypress/plugins');
-```
-
-Finally, create a new file e2e/cypress/support/index.js with the following line:
-
-```javascript
-// Require test suite commands
-require('@shopware-ag/e2e-testsuite-platform/cypress/support');
-```
-
-</Tab>
-
-<Tab title="Platform: Developing with docker">
-If you are using docker, you don't need to install a thing: We use the [Cypress/Included image](https://github.com/cypress-io/cypress-docker-images/tree/master/included) to use Cypress in Docker completely.
-
-However, as we're using this image for running the test runner as well, you may need to do some configuration first. Based on this [guide](https://www.cypress.io/blog/run-cypress-with-a-single-docker-command) you need to forward the XVFB messages from Cypress out of the Docker container into an X11 server running on the host machine. The guide shows an example for Mac; other operating systems might require different commands.
-
-In case you're using Docker on Mac we have summarized the steps from the guide mentioned above, so you can follow these to prepare your environment to get the Test Runner up and running:
-
-**Install and configure XQuartz**
-
-Install XQuartz via [Homebrew](https://docs.brew.sh/Installation) or alternatively [download](https://www.xquartz.org/) it from the official homepage:
-
-```bash
-brew install --cask xquartz
-```
-
-Run XQuartz via CLI or open it from your Desktop:
-
-```bash
-open -a XQuartz
-```
-
-Got to `XQuartz > Preferences` (`⌘ + ,`) and enable `Allow connections from network clients`:
-
-
-
-::: warning
-Restart your Mac before proceeding with the following steps.
-:::
-
-**Configure your environment**
-
-Grab your IP address and save it to the environment variable `IP`:
-
-```bash
-IP=$(ipconfig getifaddr en0)
-```
-
-Depending on how you're connected you might have to use another interface instead of `en0`.
-
-Now set the `DISPLAY` environment variable:
-
-```bash
-DISPLAY=$IP:0
-```
-
-Add `$IP` to xhost's ACL:
-
-```bash
-xhost + $IP
-```
-
-::: danger
-It is **crucial** to set these environment variables in the **same terminal session** from where you will later run `psh e2e:open`!
-
-Make sure that the `DISPLAY` environment variable on your Mac is properly set **before** you start the containers as it will be **passed** to the Cypress container when the container is **created**.
-Updating the variable on your host won't update it in the container until it is re-created!
-:::
-</Tab>
-</Tabs>
-
-## Executing E2E tests
-
-<Tabs>
-<Tab title="Plugin setup">
-
-If you want to run E2E tests in your plugin, just switch to the folder `Resources/app/<environment>/test/e2e` and execute the following command:
-
-```bash
-CYPRESS_baseUrl=<your-url> npm run open
-```
-
-`<your-url>` means the Storefront-URL of your Shopware environment.
-
-It opens up the Cypress test runner which allows you to run and debug your tests, similar to the `e2e:open` command.
-
-::: danger
-Don't forget that you might need to adjust test cleanup and other environment-related things according to your plugin's setup.
-:::
-
-</Tab>
-
-<Tab title="Execution in platform project">
-If you use Docker for your development environment, you are able to start right away.
-
-To prepare your shopware installation, your environment and install dependencies, please run the following command as first step, **outside** of your docker container:
-
-```bash
- composer run e2e:setup
-```
-
-In our tests, we assume a clean shopware installation, so we strongly recommend to use `e2e:setup`. However, if your shopware installation is already clean and prepared, you can skip the preparation of your shopware installation by using the following command **inside** your docker container:
-
-```bash
- composer run e2e:prepare
-```
-
-Afterwards, just use the following command outside of your container to run the Cypress Test Runner:
-
-```bash
-composer run e2e:open
-```
-
-If you want to run the tests in CLI, please use the following command outside your container:
-
-```bash
-composer e2e:cypress -- run --spec="cypress/e2e/administration/**/*.cy.js"
-```
-
-or
-
-```bash
-composer e2e:cypress -- run --spec="cypress/e2e/storefront/**/*.cy.js"
-```
-
-To see a complete overview on all psh scripts for e2e tests, feel free to refer to our [e2e command reference](../../../../../resources/references/testing-reference/e2e-commands/).
-</Tab>
-</Tabs>
-
-## Writing your first test
-
-### Folder structure
-
-In Shopware platform, you can find the tests in `src/Administration/Resources/app/administration/test/e2e`. There you can find the following folder structure, depending on your environment being Administration or Storefront:
-
-```bash
-`-- e2e
- `-- cypress
- |-- fixtures
- `-- example.json
- |-- integration
- `-- testfile.spec.js
- |-- plugins
- `-- index.js
- |-- support
- |-- commands.js
- `-- index.js
- |--cypress.json
- `--cypress.env.json
-```
-
-In the `cypress` folder, all test related folders are located. Most things will take place in these four folders:
-
-* `fixtures`: Fixtures are used as external pieces of static data that can be used by your tests. You can use them
-
- with the `cy.fixture` command.
-
-* `integration`: By default, the test files are located here. A file with the suffix "\*.spec.js" is a test file that
-
- contains a sequence of tests, performed in the order defined in it.
-
-* `plugins`: Contains extensions or plugins. By default, Cypress will automatically include the plugins file before
-
- every single spec file it runs.
-
-* `support`: The support folder is a great place to put reusable behavior such as custom commands or global overrides in,
-
- that you want to be applied and available to all of your spec files.
-
-These two configuration files are important to mention as well:
-
-* `cypress.json`
-* `cypress.env.json`
-
- These are Cypress configuration files. If you need more information about them, take a look at the
-
- [Cypress configuration docs](https://docs.cypress.io/app/references/configuration).
-
-If you need to use this structure in a plugin, it is just the path to the `e2e` folder, which is slightly different. You can find the folder structure in the paragraph [Setup](cypress-end-to-end-testing#setup-steps).
-
-If you want to contribute to Shopware platform's tests, please ensure to place your test in one of those folders:
-
-```javascript
-`-- integration
- |-- catalogue
- |-- content
- |-- customer
- |-- general
- |-- media-marketing
- |-- order
- |-- rule-product-stream
- `-- settings
-```
-
-::: warning
-This is important because otherwise your test is not considered by our CI.
-:::
-
-### Test layout and syntax
-
-Cypress tests are written in Javascript. If you worked with Mocha before, you will be familiar with Cypress' test layout. The test interface borrowed from Mocha provides `describe()`, `context()`, `it()` and `specify()`.
-
-To have a frame surrounding your test and provide a nice way to keep your test organized, use `describe()` \(or `context()` as its alias\):
-
-```javascript
-describe('Test: This is my test file', () => {
- it('test something', () => {
- // This is your first test
- });
- it('tests something else', () => {
- // This is your second test
- });
-});
-```
-
-The `it()` functions within the `describe()` function are your actual tests. Similar to `describe()` and `context()`, `it()` is identical to `specify()`. However, for writing Shopware tests we focus on `it()` to keep it consistent.
-
-## Commands and assertions
-
-In Cypress, you use commands and assertions to describe the workflow you want to test.
-
-### Commands
-
-Commands are the actions you need to do in order to interact with the elements of your application and reproduce the workflow to test in the end.
-
-```javascript
-it('test something', () => {
- ...
- cy.get('.sw-grid__row--0')
- .contains('A Set Name Snippet')
- .dblclick();
- cy.get('.sw-grid__row--0 input')
- .clear()
- .type('Nordfriesisch')
- .click();
- ...
- });
-```
-
-You can chain commands by passing its return value to the next one. These commands may contain extra steps to take, e.g. a `click` or `type` operation.
-
-Cypress provides a lot of commands to represent a variety of steps a user could do. On top of that, our E2E testsuite contains a couple of [custom commands](../../../../../resources/references/testing-reference/e2e-custom-commands/) specially for Shopware.
-
-### Assertions
-
-Assertions describe the desired state of your elements, objects and application. Cypress bundles the Chai Assertion Library \(including extensions for Sinon and jQuery\) and supports both BDD \(expect/should\) and TDD \(assert\) style assertions. For consistency reasons, we prefer BDD syntax in Shopware's tests.
-
-```javascript
-it('test something', () => {
- ...
- cy.get('.sw-loader')
- .should('not.exist')
- .should('be.visible')
- .should('not.have.css', 'display', 'none');
- cy.get('div')
- .should(($div) => {
- expect($div).to.have.length(1)
- });
- ...
- });
-```
-
-## Hooks
-
-You might want to set hooks to run before a set of tests or before each test. At Shopware we use those to e.g. clean up Shopware itself, login to the Administration or to set the admin language.
-
-Cypress got you covered, similar to Mocha, by providing hooks. These can be used to set conditions that you can run before or after a set of tests or each test.
-
-```javascript
-describe('We are using hooks', function() {
- before(function() {
- // runs once before all tests in the block
- })
-
- beforeEach(function() {
- // runs before each test in the block
- })
-
- afterEach(function() {
- // runs after each test in the block
- })
-
- after(function() {
- // runs once after all tests in the block
- })
-})
-```
-
-### Build up and teardown
-
-As we mentioned before, we use these hooks to build up the ideal situation for our test to run. This includes cleaning up the tests' state - based on a clean Shopware installation. According to Cypress' [thoughts on anti-patterns](https://docs.cypress.io/guides/references/best-practices.html#Using-after-or-afterEach-hooks) we clean up the previous state of Shopware beforehand. The reason is pretty simple: You can't be completely sure to reach the `after` hook \(sometimes tests may fail\), the safer way to cleanup your tests is the `beforeEach` hook. On top of stability advantages, it's possible to stop the tests anytime without manual cleanup.
-
-## Handling test data
-
-It's important and necessary the E2E tests are isolated. This means that the test should create itself beforehand, all the data needed for running. Afterwards, state in the database and the browser must be removed completely. This way, the spec avoids dependencies to demo data or data from other tests and cannot be disturbed by those.
-
-One test should only test one workflow, the one it's written for. For example, if you want to test the creation of products, you should not include the creation of categories in your test, although its creation is needed to test the product properly. As best practise we recommend handling everything not related to the test using the [lifecycle hooks](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests.html#Hooks) provided by Cypress.
-
-In Shopware platform, we use Shopware's REST API to create the data we need. As a result, our tests are able to focus on one single workflow without having to test the workflows which normally need to be done to provide the data we need. Another aspect of handling it this way is, that creating test data via API is faster than doing it inside the test.
-
-### Cypress' fixtures
-
-To define the request you send to Shopware and to set first test data, store as `json` file in the folder `e2e/cypress/fixtures`. You can use those files to provide fixed test data which can be used directly to create the desired entity without any further searching or processing. Fortunately, Cypress provides a way to handle those fixtures by default. The command `cy.fixture()` loads this fixed set of data located in a json file.
-
-In the example file below, this file is used in order to define and create a customer. So, it provides data so that the customer can be created in Shopware.
-
-```json
-{
- "customerNumber": "C-1232123",
- "salutation": "Mr",
- "firstName": "Pep",
- "lastName": "Eroni",
- "email": "test@example.com",
- "guest": true,
- "addresses": [
- {
- ...
- }
- ]
-}
-```
-
-::: warning
-Use only fields, which you can access in the UI / Storefront. Keep in mind that all tests in the file may use the fixture. So keep an eye on compatibility.
-:::
-
-A small note on ID usage: Using ids may be easier for finding elements, but it isn't a proper way for testing in every case - It depends on your application. You need to be 100% sure that the id is persistent and won't change between builds. Never use ids here if you cannot be 100% sure they will not change at all, e.g. in another build.
-
-::: info
-At our case at Shopware, Ids on UUID basis tend to change from one installation to the next, so they are not always suitable to be used as selector in your test.
-:::
-
-### API implementation
-
-Analogue to the Administration itself, the api access of the e2e test is based on [axios](https://www.npmjs.com/package/axios), a promise based HTTP client for the browser and node.js.
-
-Just like the Administration, we use services to access Shopware's REST API. Therefore, we use the ApiService to provide the basic methods for accessing the api. Located in `e2e/cypress/support/service/api.service.js`, ApiService is shared between all repositories and acts as a basis for all your next steps of creating fixtures. That implies that the axios implementation of all important api methods can be found there. This service acts as an interface: Next to the basic functions like get, post etc the request method is specified here as well as some Shopware-related methods which have to be available in all repositories.
-
-::: info
-Cypress provides an own axios-based way to handle requests in its command `cy.request`. However, Cypress commands are not real promises, see [Commands are not Promises](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Not-Promises). As we aim to parallelize the promises to fetch test data, we use our own implementation instead.
-:::
-
-### Services and commands
-
-In order to get all test fixture data applied to our Shopware installation, we use services to send the API requests to find, create or update the data we need. To access these services conveniently, we provide custom commands, which we'll cover a bit later. Let's continue with the general things first.
-
-All fixture services can be found in `cypress/support/service/`:
-
-```bash
-service
- |-- administration // this folder stores the Administration channel API services
- `-- <environment>
- `-- test
- `-- e2e
- `-- cypress
- |-- fixture
- |-- admin-api.service.js // Provides all methods which communicate with admin api directly
- `-- fixture.service.js // Provides all methods for general fixture handling
- |-- saleschannel // this one stores the sales channel API services
- `-- api.service.js // axios interface
-```
-
-If you want to use all known services, you can access them using custom commands. These commands can be found in `cypress/support/commands/api-commands.js` for general operation and `cypress/support/commands/fixture-commands.js` specifically for fixture handling.
-
-#### Default fixture command
-
-The stationary fixtures mentioned in the paragraph "Cypress' fixtures" can be sent to Shopware's REST API directly: In most cases Shopware does not need any additional data, like IDs or other data already stored in Shopware. That means the request can be sent, and the desired entity can be created immediately: You just need to use the `createDefaultFixture(endpoint, options = [])` command, as seen below:
-
-```javascript
- beforeEach(() => {
- cy.createDefaultFixture('tax');
- });
-```
-
-In this example, a tax rate will be created with the data provided based on the `json` file located in the `fixtures` folder. Let's look at the command in detail:
-
-```javascript
-Cypress.Commands.add('createDefaultFixture', (endpoint, data = {}, jsonPath) => {
- const fixture = new Fixture();
- let finalRawData = {};
-
- if (!jsonPath) {
- jsonPath = endpoint;
- }
-
- // Get test data from cy.fixture first
- return cy.fixture(jsonPath).then((json) => {
-
- // Merge fixed test data with possible custom one
- finalRawData = Cypress._.merge(json, data);
-
- // Create the fixture using method from fixture service
- return fixture.create(endpoint, finalRawData);
- });
-});
-```
-
-#### Commands of customised services
-
-You will notice soon that some entities need data which has already been created. That means you have to find out specific IDs or employ a completely different handling. In this case, your own service has to be created, located in `e2e/cypress/support/service`. Some examples for these services are:
-
-* Customer
-* Sales channel
-* Languages
-* Products
-
-In most cases, the usage of these services is similar to the basic ones already implemented. There are commands for each of those services provided by our E2E testsuite package. You don't need to define the API endpoint when using those commands. As these services are extending the `FixturesService`, all methods of it can be used in all other services as well.
-
-#### Writing your own customised service
-
-Let's look at the custom service `shipping.fixture.js`. This service is a rather simple example - It depicts a service in need of some customization for creating a shipping method correctly. With that being said, let's start.
-
-Your `ShippingFixtureService` has to extend the class `AdminFixtureService`. Afterwards, you create a function called `setShippingFixture(userData)` with the parameter `userData` for the data you want to use to create your shipping method. This way, your class should look like this:
-
-```javascript
-const AdminFixtureService = require('../fixture.service.js');
-
-class ShippingFixtureService extends AdminFixtureService {
- setShippingFixture(userData) {
- // Here we're going to create our shipping fixture
- }
-}
-
-module.exports = ShippingFixtureService;
-
-global.ShippingFixtureService = new ShippingFixtureService();
-```
-
-All custom services hold a distinct method for creating fixtures: First, it's important to collect the necessary data via REST API. This is done by filtering POST requests used in promises. In case of your our `ShippingFixtureService`, you need the ID of the rule you want to use for the availability, and the ID of the delivery time.
-
-```javascript
- const findRuleId = () => this.search('rule', {
- type: 'equals',
- value: 'Cart >= 0 (Payment)'
- });
- const findDeliveryTimeId = () => this.search('delivery-time', {
- type: 'equals',
- value: '3-4 weeks'
-});
-```
-
-The responses of these calls are used to provide the missing IDs for your final POST request. At first, we will merge the missing data with the existing data, then create our shipping method:
-
-```javascript
-return Promise.all([
- findRuleId(),
- findDeliveryTimeId()
-]).then(([rule, deliveryTime]) => {
- return this.mergeFixtureWithData(userData, {
- availabilityRuleId: rule.id,
- deliveryTimeId: deliveryTime.id
- });
-}).then((finalShippingData) => {
- return this.apiClient.post('/shipping-method?_response=true', finalShippingData);
-});
-```
-
-That's it! There you go: You have successfully created a customised service that sets up a shipping method in Shopware. Actually, we use this service in our platform test to create our shipping method as well. You can find the full service [here](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/master/cypress/support/service/administration/fixture/shipping.fixture.js). So please look at this example to see the whole class.
-
-Below you will find some best practices and tricks we explored to help you with your testing tasks:
-
-* A source of information can be found in FieldCollection of the several EntityDefinition files. All fields belonging to an entity are defined there. For example, if you're searching for customer related data, please search for the `CustomerDefinition` in Shopware platform.
-* If you want to extract mandatory data that is not covered by the error message received with the API's response, it's useful to reproduce your workflow manually: E.g. if you need to find out what data is mandatory for creating a customer, try to save an empty one in the Administration. Keep an eye on the developer tools of your browser while doing so, especially on the preview and response section of your request. As you get your response, you can see what data is still missing.
-* If you need to set non-mandatory data, reproducing the above mentioned workflow is recommended as well: Even if the error response does not contain a readable error, you can still inspect it: All the relevant information is stored in 'data'. IDs can be found there directly, other relevant data is stored in "attributes".
-* Cypress' test runner can help you a lot with inspecting API requests. Just click on the request in the test runner's log to get a full print of it in your console.
-
-## More interesting topics
-
-* [Unit testing with PHPUnit](../php-unit)
-* [Jest unit tests in Shopware's administration](../jest-admin)
-* [Jest unit tests in Shopware's storefront](../jest-storefront)
diff --git a/guides/plugins/plugins/testing/cypress/index.md b/guides/plugins/plugins/testing/cypress/index.md
deleted file mode 100644
index 124ca83ff4..0000000000
--- a/guides/plugins/plugins/testing/cypress/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: Cypress End-to-end testing
- position: 10
-
----
-
-# Cypress End-to-end testing
-
-:::warning
-Cypress will be deprecated in the future and is no longer maintained. We recommend using [Playwright](../playwright/index.md) for new projects.
-:::
diff --git a/guides/plugins/plugins/testing/index.md b/guides/plugins/plugins/testing/index.md
deleted file mode 100644
index b1cc8cfc68..0000000000
--- a/guides/plugins/plugins/testing/index.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-nav:
- title: Testing
- position: 80
-
----
-
-# Testing
-
-Robust testing is crucial for developing reliable and maintainable Shopware plugins and themes. Shopware provides tooling and guidance for several types of tests, ensuring your code is production-ready and meets community standards.
-
-## Unit Testing
-
-Unit testing is the base layer of an effective test strategy. Shopware supports both PHP backend logic and JavaScript components (for Storefront and Administration):
-
-Use PHPUnit to write and run backend unit tests for your PHP code.
-
-<PageRef page="php-unit" />
-
-Use Jest to test Storefront JS and Vue components following modern best practices.
-
-<PageRef page="jest-storefront" />
-
-Test custom Administration panel modules and components using Jest with the Shopware admin setup.
-
-<PageRef page="jest-admin" />
-
-## End-to-End (E2E) Testing
-
-For simulating real user journeys and integration scenarios, Shopware recommends end-to-end (E2E) testing. Playwright is the officially supported tool for automating entire workflows across the application.
-
-Automate browser interactions to verify plugins and customizations work as intended in real-world Shopware environments.
-
-<PageRef page="playwright/" />
-
-Refer to the individual guides for setup, examples, and best practices for each testing type.
diff --git a/guides/plugins/themes/add-assets-to-theme.md.rej b/guides/plugins/themes/add-assets-to-theme.md.rej
deleted file mode 100644
index c0453cd693..0000000000
--- a/guides/plugins/themes/add-assets-to-theme.md.rej
+++ /dev/null
@@ -1,12 +0,0 @@
-diff a/guides/plugins/themes/add-assets-to-theme.md b/guides/plugins/themes/add-assets-to-theme.md (rejected hunks)
-@@ -53,8 +52,8 @@ This way of adding custom assets refers to the default way of dealing with asset
-
- You can link to the asset with the twig [asset](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets) function:
-
--```html
--<img src="{{ asset('bundles/swagbasicexampletheme/your-image.png', 'asset') }}">
-+```twig
-+{{ asset('bundles/swagbasicexampletheme/your-image.png', 'asset') }}
- ```
-
- In SCSS you can link to the asset like the following:
diff --git a/guides/plugins/themes/differences-plugins-and-apps-vs-themes.md b/guides/plugins/themes/differences-plugins-and-apps-vs-themes.md
deleted file mode 100644
index 03f0853ab6..0000000000
--- a/guides/plugins/themes/differences-plugins-and-apps-vs-themes.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-nav:
- title: Differences Plugins and Apps vs Themes
- position: 30
-
----
-
-# Differences Plugins and Apps vs Themes
-
-A theme is a special type of Plugin or App, aimed at easily changing the visual appearance of the Storefront. If you want to get more information about plugins and apps you can check out the [Plugin Base Guide](../plugins/plugin-base-guide) and [App Base Guide](../apps/app-base-guide).
-
-There are basically several ways to change the appearance of the Storefront. You can have "regular" plugins or apps whose main purpose is to add new functions and change the behavior of the shop. These plugins / apps might also contain SCSS/CSS and JavaScript to be able to embed their new features into the Storefront.
-
-Technically, a theme is also a plugin / app, but it will be visible in the theme manger once it's activated and can be assigned to a specific sales channel, while plugins / apps are activated globally. To distinguish a theme from a "regular" plugin / app you need to implement the Interface `Shopware\Storefront\Framework\ThemeInterface`. A theme can inherit also from other themes, overwrite the default configuration \(colors, fonts, media\) and add new configuration options.
-
-You do not need to write any PHP code in a theme. If you need PHP code, you should choose a plugin instead. Another important distinction to themes is this: Themes are specific for a sales channel and have to be assigned to them to take effect, the other way around plugins and apps have a global effect on the Shopware installation.
-
-## Next steps
-
-Now that you have learned the differences between themes, plugins and apps, you can create your first theme.
-
-* [Create a first Shopware theme](create-a-theme)
diff --git a/guides/plugins/themes/index.md b/guides/plugins/themes/index.md
deleted file mode 100644
index 28c15966f0..0000000000
--- a/guides/plugins/themes/index.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-nav:
- title: Themes
- position: 20
-
----
-
-# Themes
-
-A Shopware theme is an extension (plugin or app) that enables you to customize and modify the appearance and design of your online storefront. You can change the layout, styling, typography, colors, images, and other visual elements to match your brand identity and desired user experience.
-
-```text
-Extensions
-├── Plugin
-│ └── can include a Theme (not for Cloud)
-└── App
- └── can include a Theme (Cloud-ready)
-```
-
-Tasks that themes enable include:
-
-* template overrides
-* custom styles
-* configuration interfaces
-* control the order in which styles and templates are loaded
-
-::: info
-Note that a plugin can also override templates.
-:::
-
-To get started with your first theme, follow our [Theme Base Guide](theme-base-guide).
-
-For more on how themes relate to plugins and apps, see [Plugins and Apps vs Themes](./differences-plugins-and-apps-vs-themes.md).
diff --git a/guides/plugins/themes/theme-base-guide.md b/guides/plugins/themes/theme-base-guide.md
deleted file mode 100644
index f694213dd4..0000000000
--- a/guides/plugins/themes/theme-base-guide.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-nav:
- title: Theme Base Guide
- position: 10
-
----
-
-# Theme Base Guide
-
-A theme gives you the ability to extend/change the visual appearance of the Storefront via styling the SCSS/CSS and adjusting twig templates. You can also provide JavaScript with your theme to change how the Storefront behaves in the browser. For example, JavaScript is used in Shopware to open the offcanvas shopping-cart. Now, as you might know, Shopware comes with a default theme, to make things a bit easier. The default theme in Shopware is built on top of Bootstrap 5, style-wise. So everything you can do with Bootstrap, you can do with the Shopware Storefront as well.
-
-Another handy capability is the theme configuration: As a theme developer you can define variables which can be configured by the shop owner in the Administration. Those variables are accessible in your theme and let you implement powerful features.
-
-## Next steps
-
-Now that you know what you can do with themes, the next steps would be to [create themes](create-a-theme).
diff --git a/resources/guidelines/code/backward-compatibility.md b/resources/contributors/code/backward-compatibility.md
similarity index 100%
rename from resources/guidelines/code/backward-compatibility.md
rename to resources/contributors/code/backward-compatibility.md
diff --git a/resources/guidelines/code/contribution.md b/resources/contributors/code/contribution.md
similarity index 100%
rename from resources/guidelines/code/contribution.md
rename to resources/contributors/code/contribution.md
diff --git a/resources/guidelines/code/core/6.5-new-php-language-features.md b/resources/contributors/code/core/6.5-new-php-language-features.md
similarity index 100%
rename from resources/guidelines/code/core/6.5-new-php-language-features.md
rename to resources/contributors/code/core/6.5-new-php-language-features.md
diff --git a/resources/guidelines/code/core/adr.md b/resources/contributors/code/core/adr.md
similarity index 100%
rename from resources/guidelines/code/core/adr.md
rename to resources/contributors/code/core/adr.md
diff --git a/resources/guidelines/code/core/database-migations.md b/resources/contributors/code/core/database-migations.md
similarity index 99%
rename from resources/guidelines/code/core/database-migations.md
rename to resources/contributors/code/core/database-migations.md
index 770eb40815..3d6422a139 100644
--- a/resources/guidelines/code/core/database-migations.md
+++ b/resources/contributors/code/core/database-migations.md
@@ -187,7 +187,7 @@ For that use the `MigrationTestTrait` trait, which encapsulates your migration t
Unfortunately, database transactions won't work with DDL commands.
DDL commands will fire an implicit commit and end an active transaction.
-> https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html
+> [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html)
All DDL commands **must** be done outside of transactions.
Therefore, you **must** undo your DDL commands manually after the test and it is best to handle the transaction start and rollback manually in your test and not rely on the `MigrationTestTrait`.
diff --git a/resources/guidelines/code/core/decorator-pattern.md b/resources/contributors/code/core/decorator-pattern.md
similarity index 100%
rename from resources/guidelines/code/core/decorator-pattern.md
rename to resources/contributors/code/core/decorator-pattern.md
diff --git a/resources/guidelines/code/core/domain-exceptions.md b/resources/contributors/code/core/domain-exceptions.md
similarity index 100%
rename from resources/guidelines/code/core/domain-exceptions.md
rename to resources/contributors/code/core/domain-exceptions.md
diff --git a/resources/guidelines/code/core/feature-flags.md b/resources/contributors/code/core/feature-flags.md
similarity index 92%
rename from resources/guidelines/code/core/feature-flags.md
rename to resources/contributors/code/core/feature-flags.md
index 12962858ea..70218b5a81 100644
--- a/resources/guidelines/code/core/feature-flags.md
+++ b/resources/contributors/code/core/feature-flags.md
@@ -7,7 +7,7 @@ You can find the original version [here](https://github.com/shopware/shopware/bl
## Introduction
Feature flags enable the developer to create new code which is hidden behind the flag and merge it into the trunk branch, even when the code is not finalized.
-We use this functionality to merge breaks into the trunk early, without them already being switched active. To learn more about breaking changes and backward compability take a look to our [Backward Compatibility Guide](/docs/resources/guidelines/code/backward-compatibility.html)
+We use this functionality to merge breaks into the trunk early, without them already being switched active. To learn more about breaking changes and backward compatibility take a look to our [Backward Compatibility Guide](/docs/resources/guidelines/code/backward-compatibility.html)
### Activating the flag
To switch flags on and off you can use the ***.env*** to configure each feature flag. Using dots inside an env variable are not allowed, so we use underscore instead:
@@ -77,7 +77,7 @@ class ApiController
}
}
```
-Putting the old behaviuor inside the if block makes it easier to remove the feature flag later on.
+Putting the old behavior inside the if block makes it easier to remove the feature flag later on.
And you can use it simply to throw exceptions:
@@ -146,7 +146,7 @@ When you want to toggle different parts of the template you can use the flag in
### Using flags in config.xml
-When you want to toggle config input fields in config.xml like [basicInformatation.xml](https://gitlab.shopware.com/shopware/6/product/platform/-/blob/trunk/src/Core/System/Resources/config/basicInformation.xml), you can add a `flag` element like this:
+When you want to toggle config input fields in config.xml like [basicInformation.xml](https://gitlab.shopware.com/shopware/6/product/platform/-/blob/trunk/src/Core/System/Resources/config/basicInformation.xml), you can add a `flag` element like this:
```xml
<input-field type="bool" flag="v6.5.0.0">
diff --git a/resources/guidelines/code/core/index.md b/resources/contributors/code/core/index.md
similarity index 100%
rename from resources/guidelines/code/core/index.md
rename to resources/contributors/code/core/index.md
diff --git a/resources/guidelines/code/core/unit-tests.md b/resources/contributors/code/core/unit-tests.md
similarity index 100%
rename from resources/guidelines/code/core/unit-tests.md
rename to resources/contributors/code/core/unit-tests.md
diff --git a/resources/guidelines/code/core/writing-code-for-static-analysis.md b/resources/contributors/code/core/writing-code-for-static-analysis.md
similarity index 100%
rename from resources/guidelines/code/core/writing-code-for-static-analysis.md
rename to resources/contributors/code/core/writing-code-for-static-analysis.md
diff --git a/resources/guidelines/code/document-code.md b/resources/contributors/code/document-code.md
similarity index 100%
rename from resources/guidelines/code/document-code.md
rename to resources/contributors/code/document-code.md
diff --git a/resources/guidelines/code/index.md b/resources/contributors/code/index.md
similarity index 100%
rename from resources/guidelines/code/index.md
rename to resources/contributors/code/index.md
diff --git a/resources/guidelines/code/platform-domains.md b/resources/contributors/code/platform-domains.md
similarity index 100%
rename from resources/guidelines/code/platform-domains.md
rename to resources/contributors/code/platform-domains.md
diff --git a/resources/guidelines/code/public-apis.md b/resources/contributors/code/public-apis.md
similarity index 100%
rename from resources/guidelines/code/public-apis.md
rename to resources/contributors/code/public-apis.md
diff --git a/resources/guidelines/code/routing.md b/resources/contributors/code/routing.md
similarity index 100%
rename from resources/guidelines/code/routing.md
rename to resources/contributors/code/routing.md
diff --git a/resources/guidelines/code/session-and-state.md b/resources/contributors/code/session-and-state.md
similarity index 100%
rename from resources/guidelines/code/session-and-state.md
rename to resources/contributors/code/session-and-state.md
diff --git a/resources/references/core-reference/composer-commands-reference.md b/resources/contributors/composer-commands-reference.md
similarity index 100%
rename from resources/references/core-reference/composer-commands-reference.md
rename to resources/contributors/composer-commands-reference.md
diff --git a/resources/guidelines/index.md b/resources/contributors/index.md
similarity index 81%
rename from resources/guidelines/index.md
rename to resources/contributors/index.md
index a935d9e46a..e515f1b8f9 100644
--- a/resources/guidelines/index.md
+++ b/resources/contributors/index.md
@@ -13,12 +13,8 @@ The code section lays out the coding standards. This helps anyone understand and
<PageRef page="./code/" />
-The test section briefs you about best practices for writing end-to-end tests.
-
-<PageRef page="./testing/" />
-
The document section details you on the language style, grammar, markdown syntax, and documentation process.
-<PageRef page="./documentation-guidelines/" />
+<PageRef page="./documentation-guidelines" />
this document serves as a comprehensive resource for both readers and contributors, offering essential coding, testing, and documentation guidelines to maintain consistency, promote best practices, and facilitate effective collaboration.
diff --git a/resources/guidelines/documentation-guidelines/01-general.md b/resources/documentation-guidelines/01-general.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/01-general.md
rename to resources/documentation-guidelines/01-general.md
diff --git a/resources/guidelines/documentation-guidelines/02-conceptual-structure.md b/resources/documentation-guidelines/02-conceptual-structure.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/02-conceptual-structure.md
rename to resources/documentation-guidelines/02-conceptual-structure.md
diff --git a/resources/guidelines/documentation-guidelines/03-language-and-grammar.md b/resources/documentation-guidelines/03-language-and-grammar.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/03-language-and-grammar.md
rename to resources/documentation-guidelines/03-language-and-grammar.md
diff --git a/resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md b/resources/documentation-guidelines/04-fonts-and-formats/01-text.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md
rename to resources/documentation-guidelines/04-fonts-and-formats/01-text.md
diff --git a/resources/guidelines/documentation-guidelines/04-fonts-and-formats/02-code.md b/resources/documentation-guidelines/04-fonts-and-formats/02-code.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/04-fonts-and-formats/02-code.md
rename to resources/documentation-guidelines/04-fonts-and-formats/02-code.md
diff --git a/resources/guidelines/documentation-guidelines/04-fonts-and-formats/index.md b/resources/documentation-guidelines/04-fonts-and-formats/index.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/04-fonts-and-formats/index.md
rename to resources/documentation-guidelines/04-fonts-and-formats/index.md
diff --git a/resources/guidelines/documentation-guidelines/05-methodize-assets.md b/resources/documentation-guidelines/05-methodize-assets.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/05-methodize-assets.md
rename to resources/documentation-guidelines/05-methodize-assets.md
diff --git a/resources/guidelines/documentation-guidelines/06-doc-process.md b/resources/documentation-guidelines/06-doc-process.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/06-doc-process.md
rename to resources/documentation-guidelines/06-doc-process.md
diff --git a/resources/guidelines/documentation-guidelines/07-embedding-external-repositories.md b/resources/documentation-guidelines/07-embedding-external-repositories.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/07-embedding-external-repositories.md
rename to resources/documentation-guidelines/07-embedding-external-repositories.md
diff --git a/resources/guidelines/documentation-guidelines/index.md b/resources/documentation-guidelines/index.md
similarity index 100%
rename from resources/guidelines/documentation-guidelines/index.md
rename to resources/documentation-guidelines/index.md
diff --git a/resources/guidelines/code/cart-process.md b/resources/guidelines/code/cart-process.md
deleted file mode 100644
index 46fd86c351..0000000000
--- a/resources/guidelines/code/cart-process.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-nav:
- title: Cart Process
- position: 30
-
----
-
-# Cart Process
-
-* Within `\Shopware\Core\Checkout\Cart\CartProcessorInterface::process`, no queries may be executed because this method is executed several times in a row to resolve the dependencies of the elements in the shopping cart.
-* The `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface::collect` method must always check if the required data has already been loaded. This is to avoid having to execute unnecessarily many queries on the database. The loaded data will be appended to the passed *CartDataCollection*.
-* The creation of line items must always take place via a `LineItemFactoryHandler` class.
-* All price calculations must take place via an appropriate `PriceCalculator`. All price calculators are stored inside the `Shopware\Core\Checkout\Cart\Price` class.
-* All shopping cart functions must be mapped via a corresponding store API route. The routes are located in the `Shopware\Core\Checkout\Cart\SalesChannel` namespace.
diff --git a/resources/guidelines/code/context-rules-rule-systems.md b/resources/guidelines/code/context-rules-rule-systems.md
deleted file mode 100644
index 0ed910452e..0000000000
--- a/resources/guidelines/code/context-rules-rule-systems.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: Context Rules & Rule Systems
- position: 40
-
----
-
-# Context Rules and Rule Systems
-
-* In a rule, there must never be a query against the database because all configured rules are validated in a request.
-* Rules that check for the cart must always support the `\Shopware\Core\Checkout\Cart\Rule\CartRuleScope` class and the `\Shopware\Core\Checkout\Cart\Rule\LineItemScopeclass`.
-* Rules may only access data provided in the appropriate scopes.
diff --git a/resources/guidelines/code/dependency-injection-dependency-handling.md b/resources/guidelines/code/dependency-injection-dependency-handling.md
deleted file mode 100644
index 4795ff3573..0000000000
--- a/resources/guidelines/code/dependency-injection-dependency-handling.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Dependency Injection & Dependency Handling
- position: 50
-
----
-
-# Dependency Injection and Dependency Handling
-
-Within the Core domain, it is not allowed to access the PHP session. There is only one PHP session if it is a storefront request. The appropriate implementation and consideration of session data must be handled in the Storefront domain.
diff --git a/resources/guidelines/code/events.md b/resources/guidelines/code/events.md
deleted file mode 100644
index d4eb97c7b2..0000000000
--- a/resources/guidelines/code/events.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: Events
- position: 70
-
----
-
-# Events
-
-* An event must always implement the `\Shopware\Core\Framework\Event\ShopwareEvent` interface.
-* Events thrown in the context of a sales channel must always implement the interfaces `ShopwareSalesChannelEvent` and `Shopware\Core\Framework\Event\SalesChannelAware`.
-* Events are mostly used to allow developers to load more data. They should, as a rule, not interfere with the program flow. The decoration pattern is intended for influencing the program flow.
diff --git a/resources/guidelines/code/pageloader.md b/resources/guidelines/code/pageloader.md
deleted file mode 100644
index c81e1bd530..0000000000
--- a/resources/guidelines/code/pageloader.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-nav:
- title: Page Loader
- position: 80
-
----
-
-# Page Loader
-
-* Pageloaders must be divided into appropriate domains that represent the different sections of the Storefront - "products", "account", etc.
-* Each page loader must have an abstract class from which it derives ( See [decoration pattern](../../references/adr/2020-11-25-decoration-pattern.md)). This pattern can be used to completely replace the page loader in a project.
-* Each page loader has a page object to return, in which all the necessary information for the page is present.
-* At the end of each pageloader, an individual `PageLoaded` event is thrown. This event can be used to provide further data by third-party developers.
-* Page loaders are not allowed to work directly with repositories but are only allowed to load data via the Store API. This is to ensure that all storefront functionalities can also be accessed via the Store API.
-* A Page object must always extend from the base `\Shopware\Storefront\Page\Page` class.
diff --git a/resources/guidelines/code/store-api.md b/resources/guidelines/code/store-api.md
deleted file mode 100644
index 85325a1844..0000000000
--- a/resources/guidelines/code/store-api.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-nav:
- title: Store API
- position: 130
-
----
-
-# Store API
-
-## Routes
-
-* Stop implementing the Sales Channel API.
- It will be deprecated in the 6.4 major release.
- Define API Controllers \(Routes\) as services. Use named Routes internally.
-* The class or each API method requires the attribute: `#[Route(defaults: [\Shopware\Core\PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [\Shopware\Core\Framework\Routing\StoreApiRouteScope::ID]])]`.
-* Decorator of response extends on `StoreApiResponse`.
-
-## Page Loader
-
-* Routes represent a single functionality.
-* Controller/Pageloader only works with routes.
-* Controller/Pageloader can call multiple routes.
-* A route has to return a StoreApiResponse, to convert to JSON.
-* A route response can only contain one object.
-* The Storefront controller should never work with the repository again. It should be injected inside a route.
diff --git a/resources/guidelines/code/storefront-controller.md b/resources/guidelines/code/storefront-controller.md
deleted file mode 100644
index 18e5b2b884..0000000000
--- a/resources/guidelines/code/storefront-controller.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-nav:
- title: Storefront Controller
- position: 140
-
----
-
-# Storefront Controller
-
-## Controller
-
-* Each controller action requires a `#Route` attribute.
-* The name of the route should start with "frontend".
-* Each route should define the corresponding HTTP Method \(GET, POST, DELETE, PATCH\).
-* The function name should be concise.
-* Each function should define a return type hint.
-* A route should have a single purpose.
-* Use Symfony flash bags for error reporting.
-* Each storefront functionality has to be available inside the Store API too.
-* A Storefront controller should never contain business logic.
-* The class requires the attribute: `#[Route(defaults: [\Shopware\Core\PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [\Shopware\Storefront\Framework\Routing\StorefrontRouteScope::ID]])]`.
-* Depending services have to be injected over the class constructor.
-* Depending services have to be defined in the DI-Container service definition.
-* Depending services have to be assigned to a private class property.
-* A Storefront controller has to extend the `\Shopware\Storefront\Controller\StorefrontController`.
-
-## Read operations inside Storefront controllers
-
-* A Storefront controller should never use a repository directly. The data should be fetched over a route or page loader.
-* Routes that load a full Storefront page should use a page loader class to load all corresponding data.
-* Pages that contain data that are the same for all customers should have the `_httpCache` attribute.
-
-## Write operations inside Storefront controllers
-
-* Write operations should create their response with the `createActionResponse` function to allow different forwards and redirects.
-* Each write operation has to call a corresponding Store API route.
diff --git a/resources/guidelines/testing/index.md b/resources/guidelines/testing/index.md
deleted file mode 100644
index 3416cd8aab..0000000000
--- a/resources/guidelines/testing/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Test
- position: 30
-
----
-
-# Testing
-
-Testing ensures software reliability, quality, and optimum performance. Detailed E2E testing and quality guidelines are described in the following sections.
diff --git a/resources/guidelines/testing/store/quality-guidelines-plugins/index.md b/resources/guidelines/testing/store/quality-guidelines-plugins/index.md
deleted file mode 100644
index 643c20989d..0000000000
--- a/resources/guidelines/testing/store/quality-guidelines-plugins/index.md
+++ /dev/null
@@ -1,555 +0,0 @@
----
-nav:
- title: Quality guidelines for apps in the plugin system
- position: 10
-
----
-
-# Quality Guidelines for the Plugin System in the Shopware Store
-
-> **Changelog**
->
->> 09/10/24: Quality guidelines for apps in the plugin system.
->
->> 01/08/24: [Added - Message queue](..//quality-guidelines-plugins/#message-queue)
->
->> 06/09/23: [Added - Rules for own composer dependencies](../quality-guidelines-plugins/#own-composer-dependencies)
->
->> 26/07/23: [Added - Identical name rule](../quality-guidelines-plugins/#every-app-based-on-the-plugin-system)
-
-## The way we test apps based on the plugin system
-
-It is always a good idea to review our test process before submitting your app for review.
-This ensures the quickest way for your app to be published.
-
-We perform the *first test*, and if successful, we do the *follow-up test* again with the most current Shopware version.
-
-The app is tested with the latest official Shopware 6 CE Version.
-
-::: info
-We always test with the [actual SW6 version](https://www.shopware.com/de/download/#shopware-6).
-So set it to the actual SW6 version e.g., shopware/testenv:6.6.6.
-Always test with the app`s highest supported Shopware version.
-:::
-
-Link: [Test your app for the Shopware Store (DE):](https://www.youtube.com/watch?v=gLb5CmOdi4g) and EN version is coming soon.
-
-**Progressive Web App:** If your app is PWA compatible and you would like the PWA flag, please contact us at [alliances@shopware.com](mailto:alliances@shopware.com).
-
-## Checklist for app testing
-
-Could you be sure to use the most recent testing checklist from Shopware and not any other provider?
-Please pay attention to every point in this guide. We'll review it before you release your app.
-
-### Every app based on the plugin system
-
-* We pay attention to the automatic code review and look for security issues and shopware coding standards in the manual code review.
-
-* We check the complete functionality of the app (separately sales channel configurations in the config.xml, the uninstallation and reinstallation procedure) and check for styling errors on every viewport.
-
-Link: [Documentation for Extension Partner](https://docs.shopware.com/en/account-en/extension-partner/extensions?category=account-en/extension-partner#how-can-i-request-a-preview)
-
-::: info
-**Safe your app idea and get a preview in the store**
-If you already have an idea and don't want it to be snatched away, ensure you get it by creating a preview in your account.
-You can apply for this if you have maintained placeholder images for the store, meaningful use cases, highlight features, a description, and a release month without uploading any binary.
-:::
-
-## App store description
-
-The release to the English store is standard.
-As an app will be released in both stores (German and International), the content must accurately translate 1:1 from English to German.
-
-* The mandatory number of characters is set in short and long descriptions. No blank spaces as fillers are allowed (EN/DE).
-* Check if the description makes sense and describe the use cases of your app.
-* Check if your configuration manual includes step-by-step instructions on how to configure and use your app.
-* Check if you have included enough screenshots showing the app in action in the Storefront and administration.
-* Check if the display name does not contain the terms "plugin" or "shopware".
-* Check if all images for the English store description contain the English language. **Please do not mix English with other languages in your screenshots. Screenshots in German for the German store description are optional.**
-* Check if you explained the setup of the app and added a configuration manual.
-
-### Display Name
-
-According to the new naming scheme, extensions may no longer display the words "plugin" and "shopware" in their names.
-An extension with a name that directly reflects its functional purpose is permissible, even if it shares the same name as another extension.
-
-Also, the store-display name had to be used for `composer.json` and `config.xml`.
-
-### Short description
-
-(Min. 150 — max. 185 characters)—The app's short description must be unique and at least 150 characters long.
-Use the short description wisely, as the text will tease your app in the overview along with the "Customers also bought" and "Customers also viewed" recommendations.
-The short description is also published as a meta-description.
-
-### Description
-
-(Min. 200 characters)—The app description must be at least 200 characters long and describe the app's functions in detail.
-
-* Inline styles will be stripped. The following HTML tags are allowed:
-
-```markdown
-<a> <p> <br> <b> <strong> <i> <ul> <ol> <li> <h2> <h3> <h4> <h5>
-```
-
-* **Tips:**
-
- * When it comes to increasing your app sales, it is important that potential customers feel completely informed about your products and services.
- To this end, you should provide description, highlights, and features that are meaningful, detailed, and easy to understand, even for people with very minimal technical knowledge.
- Explain step-by-step how your app works and how to use it to achieve the desired result.
- Of course, your app description should be accompanied by clean HTML source code.
-
- * Video content increases awareness and trust and has proven to convert potential customers better than other content types.
- You can help your customers better understand your app or service with explainer videos, product demos, tutorials, etc.
- You can embed a maximum of 2 YouTube videos in your app description.
-
-::: info
-You can no longer advertise your Shopware certificates within the app description, in your app images, or in your manufacturer profile.
-The manufacturer/partner certificates are dynamically loaded at the end of each app description and published by us.
-:::
-
-### Images
-
-::: info
-Screenshots and preview images in English are standard. Only full English screenshots are accepted. Please do not mix English with other languages in your screenshots. Screenshots in German for the German store description are optional.
-:::
-
-Include several screenshots and descriptive images from the Storefront and backend that represent the app functionality.
-They must show the app "in action", its configuration options, and how to use it.
-We recommend uploading screenshots showing the mobile and desktop-view.
-
-Only images that represent or show the function of the extension may be used. Advertising for other extensions or services is not permitted.
-
-Link: [How To - Add images and icons to extensions](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to)
-
-### Link to demoshop
-
-If you provide a demo shop, the link must be valid (the URL cannot contain `http:` or `https:`).
-Do not link to your test environments, as we will delete them automatically two weeks after they are created.
-
-### Personal data protection information
-
-If necessary, personal data protection information has to be set.
-If personal data of the customers (store operator and/or his customers) are processed with this extension according to Art. 28 DSGVO, the following information of the data processing company must be stored in the field "Subprocessor".
-
-If other companies are involved in the data processing of personal data, the same information must be stored accordingly for them in the field "Further subprocessors".
-
-### Configuration manual
-
-Explain how your app is installed and configured, how it works on a technical base, and how it can be used to achieve the desired result.
-Of course, your app manual should contain a setup guide and be accompanied by clean HTML source code.
-
-### Manufacturer Profile
-
-Your manufacturer profile must mandatorily contain accurate English and German descriptions and a manufacturer logo.
-You can find the manufacturer profile in your account under Shopware Account > Extension Partner > [Extension Partner profile](https://account.shopware.com/producer/profile).
-
-::: info
-The source code's descriptions, profiles, and instructions do not allow iframes, external scripts, or tracking pixels.
-Custom styles may not overwrite the original Shopware styles. External sources must be included via https.
-:::
-
-## Basic Guidelines
-
-### Testing functionality
-
-Due to our quality assurance, we check the app's complete functionality and test it wherever it impacts the administration or storefront.
-
-Also, every app will be code-reviewed by one of our core-developer ensuring coding and security standards.
-
-### Extension master data/license
-
-Please enter the valid license you set in your Shopware account.
-You have to identify this license in the `composer.json` as well.
-
-::: info
-The chosen license can't be changed after adding your app to your account.
-If you want to change the license later, add a new app based on the app system with a new technical name and upload the extension again.
-:::
-
-### Fallback language / Translations
-
-The installation is not always in English or German.
-Could you make sure that your app works in other languages as well?
-For example, if the customer has his installation in Spanish and your app is not yet available in this language, you should use the English translation as a fallback.
-
-If your app is available in more than one language (e.g., English, Spanish, French and German), these can be defined using the option "Translations into the following languages are available" (located in the "Description & images" section of your *Account*).
-
-We check for text snippets, `config.xml`, and `composer.json`.
-
-### Valid preview images for the Shopware administration
-
-Preview images: There must be a preview image available in the *Extension Manager*.
-You must upload a valid favicon named plugin.png (png / 112 x 112 pixels) for the app.
-This favicon will help you identify your app in the Extension Manager module in the administration.
-The favicon has to be stored under `src/Resources/config/`.
-
-Also, provide a preview image for Themes in the *Theme Manager* and CMS elements in the *Shopping Experiences*.
-
-### Configuration per sales channel
-
-Apps that appear in the Storefront and use a `config.xml` must be able to be configured separately for each sales channel.
-
-### External links with rel="noopener"
-
-Every external link in the administration or Storefront must be marked as *rel="noopener" AND target="_blank"*.
-
-### Error messages and logging
-
-Error or informational messages can only be recorded in the event log of Shopware's log folder (/var/log/).
-You have to develop your own log service.
-Never write app exceptions into the Shopware default log or outside the Shopware system log folder.
-This ensures that the log file can never be accessed via the URL.
-
-For payment apps, we check if the "plugin logger" service is used for the debug/error.log and that logs are written in the directory /var/log/. Log files must be used in every circumstance.
-
-The log file had to be named like this: "MyExtension-Year-Month-Day.log"
-
-Another solution is to store them in the database.
-Try to avoid using your own log tables. Otherwise, you have to implement a scheduled task that regularly empties your log table within the given time of max. 6 months.
-
-### Avoid 400/500 Error
-
-*Avoid 500 errors at any time.* Avoid 400 errors unless they are related to an API call.
-
-### With "Install/Uninstall" the user must decide whether the data/table is to be deleted or not
-
-When clicking on the "Install / Uninstall" option in the Extension Manager, the user must be presented with the options "completely delete" or "keep the app data, text snippets, media folder including own media and table adjustments".
-You can check this using the Adminer-App from *Friends of Shopware* in your provided test-environment.
-
-### Not allowed to extend the Extension Manager
-
-The *Extension Manager* must not be extended or overwritten.
-
-### Own composer dependencies
-
-Composer dependencies are possible if they are in the `composer.json`.
-With `executeComposerCommands() === true` in the plugin base class, we provide a dynamic installation of the composer dependencies by default, so they don't have to be included.
-Everything that is delivered in code should be traceable either directly or via `composer.json`.
-
-[Developer documentation article to add private dependency](../../../../../guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies)
-
-### Extension manager
-
-The Debug Console controls the app's installation, uninstallation, reinstallation, and deletion.
-No 400 errors or exceptions are allowed to appear. If the app requires special PHP options, it must be queried during installation.
-If the query is negative, a growl message must appear in the administration.
-
-### Reloading of files not allowed
-
-Apps may not load other files during and after the installation in the *Extension Manager*.
-
-### Uncompiled JavaScript must be delivered within the binary
-
-Compiled JavaScript offers many benefits such as improved performance and code optimization.
-However, it is difficult to read and understand the compiled code.
-The uncompiled JavaScript code must be placed in a separate folder to ensure it remains accessible to all developers.
-This allows other developers to review and understand the code in its original, readable form.
-
-Please build your `main.js` as described in our documentation and create the minified code as described in our developer documentation.
-
-[Loading the JS files](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#loading-the-js-files)
-
-[Injecting into the Administration](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#injecting-into-the-administration)
-
-Shopware reserves the right to publish extensions with minified code after individual consideration and consultation with the developer.
-For this, the developer must ensure that Shopware has access to the current unminified code of the extension at all times.
-
-### Message queue
-
-If the extension adds messages to the message queue, ensure they are not bigger than 262,144 bytes (256 KB).
-This limitation is set by common message queue workers and should not be exceeded.
-
-### Note on Shopware technology partner contract for interfaces
-
-You have now read the complete list of requirements for developing and releasing apps based on our app system in the Shopware Community Store.
-
-If your app is a software app/interface with downstream costs, transaction fees, or service fees for the customer, we need to complete a technology partner agreement in order to activate your app.
-
-If you have any questions regarding the technology partner agreement, please contact our sales team by writing an email to [alliances@shopware.com](mailto:alliances@shopware.com) or calling **+44 (0) 203 095 2445 (UK) / 00 800 746 7626 0 (worldwide) / +49 (0) 25 55 / 928 85-0 (Germany)**.
-
-## Storefront Guidelines
-
-### Testing the storefront
-
-Test the frontend and the checkout for new errors throughout the entire Storefront using the Browser Debug Console and also pay attention to JavaScript errors.
-
-### Links must include a title tag
-
-Links in the storefront and administration must include a meaningful "title tag".
-
-### Images must include the alt-tag
-
-Links in the storefront and administration must include a meaningful "alt tag" or the original alt tag from the media manager.
-
-### Do not use `<hX>`-Tags
-
-The utilization of `<hX>`-tags in the storefront templates, which are set to `<meta name="robots" content="index,follow">`, is not permissible, as these tags are reserved exclusively for content purposes.
-However, you may employ `<span class="h2">`, for instance.
-
-### Do not use inline-css in the storefront templates
-
-Use your own classes and let your CSS be compiled by the plugin.
-
-[Add SCSS variables](../../../../../guides/plugins/plugins/storefront/add-scss-variables.md#add-scss-variables)
-
-### Prevent `!important` usage
-
-Please avoid using the `!important` rule whenever possible.
-
-[Add SCSS variables](../../../../../guides/plugins/plugins/storefront/add-scss-variables.md#add-scss-variables)
-
-### New controller URLs / XHR requests
-
-We check for new XHR/Document requests in the storefront as they must be accompanied by an `X-Robots-Tag` in the header request with the directive "noindex, nofollow.".
-For further details, please refer to the [robots meta tag](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag?hl=de#xrobotstag) article.
-
-If the app creates its own controller URLs set to "index, follow" and the URLs are accessible via the frontend, then these "app URLs" must also appear in the `sitemap.xml`.
-In addition, these pages must include a valid canonical tag, their own meta description, and a title tag, which can be entered individually via the administration or as a text snippet.
-
-### Lighthouse A/B-Testing
-
-Could you do an A/B test with *Lighthouse Audit* to check the performance and quality of your frontend app?
-There should not be any drastic change in performance, accessibility values, or any new errors when activating the app.
-
-* **Testing tool** for A/B-Testing:
- * Link: [Google Lighthouse](https://developer.chrome.com/docs/lighthouse)
-
-### schema.org/Rich Snippets A/B-Testing
-
-Do an A/B-Test with *Scheme.org's Structured Data Testing Tool* and *Google Rich Result Tester* to check the homepage, categories, and various product detail pages (incl. available products, unavailable products, products with no review, single review, many reviews with various ratings, out-of-stock products, products to be released in the future or any other kind of product configuration and products including ean, mpn, width, length, height, weight).
-Also, could you check for duplicate entries as well as any new bugs?
-
-* **Testing tool** for A/B-Testing:
- * Link: [Schema Markup Validator of schema.org](https://validator.schema.org/)
- * Link: [Google Rich Result Tester](https://search.google.com/test/rich-results)
-
-### Usage of fonts from external sources
-
-If you are using external fonts (e.g., Google fonts, Fontawesome) or external services, the app store description must contain this information.
-
-Please be aware that you might have to edit your *data protection information*.
-This info could be placed as a tooltip near the font settings of the app configuration.
-
-### Register your cookie to the Cookie Consent Manager
-
-We expect every cookie set from the store URL to be optional and not technically required for running shopware.
-Therefore, the cookies had to be [registered in our Cookie Consent Manager](../../../../../guides/plugins/plugins/storefront/add-cookie-to-manager).
-
-We differentiate between "Technically required", "Marketing" and "Comfort features".
-All cookies must appear (unchecked) in the cookie configuration box in the frontend.
-
-## Administration guidelines
-
-### Menu entries in the main menu are not allowed
-
-Menu entries in the main menu of the administration are not allowed because of the look and feel.
-
-### Own media folder
-
-Manufacturer must create their own media folders with the right thumbnail settings or use existing ones to upload images, except for upload fields within the `config.xml`.
-
-If you use your own media folder, keep in mind that the folder and the included data had to be removed if selected during the uninstallation.
-
-### API test button
-
-* If your API corresponds via API credentials to external services, we expect an API test button.
-Apart from that, you can validate the required credentials while saving them in the app settings.
-In this case, a status message must be displayed in the administration and Shopware log.
-If the API data is incorrect, an entry must appear in the event log file in the Shopware folder `/var/log/` respectively in the database.
-
-* **Example** for implementing an API Test Button into the System Config form:
- * Link: [GitHub](https://github.com/shyim/ShyimApiTest)
-
-### Shopping experiences
-
-[Shopping worlds elements](../../../../../concepts/commerce/content/shopping-experiences-cms.md#elements) must include an element icon.
-If the app is deleted, *Shopping Worlds* should work flawlessly in the frontend.
-
-### Themes
-
-[Themes](../../../../../guides/plugins/themes/) must include its own preview image.
-
-### External technology/ Shopware Technology Partner (STP) apps
-
-Every external technology app needs to track its commission.
-Below is an example of implementing the tracking logic in their extensions:
-
-// POST /shopwarepartners/reports/technology - Allows partners to send us the info based on the STP contract
-
-```json
- {
- "identifier": "8e167662-6bbb-11eb-9439-0242ac130002",
- "reportDate": "2005-08-15T15:52:01",
- "instanceId": "alur24esfaw3ghk",
- "shopwareVersion": "6.3.1",
- "reportDataKeys": [
- {
- "customer": 3
- },
- {
- "turnover": 440
- }
- ]
- }
-```
-
-### Automatic code reviews with PhpStan and SonarQube
-
-Our most current code review configurations when uploading apps via the Shopware Account can be found on GitHub.
-
-* Link: [Code reviews for Shopware 6 on GitHub](https://github.com/shopwareLabs/store-plugin-codereview)
-
-### Sonarcube Rules status Blocker
-
-The following statements will be blocked as of 1st Oct. 2022:
--die; exit; var_dump
-
-* Link: [Refer to the list of the already existing blockers](https://s3.eu-central-1.amazonaws.com/wiki-assets.shopware.com/1657519735/blocker.txt).
-
-### Automated code tests with Cypress
-
-There are Cypress tests for Shopware 6 on GitHub.
-The project is driven by the *Friends of Shopware* group. You can contribute at any time:
-
-* Link: [Developer Documentation Cypress Tests for Shopware 6](../../../../../guides/plugins/plugins/testing/end-to-end-testing/)
-* Link: [Cypress Tests for Shopware 6](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources)
-
-### Useful tool for plugin development and extension management
-
-The [`shopware-cli`](https://github.com/shopware/shopware-cli) is a useful tool for building, validating and uploading new Shopware 6 plugin releases to the Community Store. It also allows you to manage the store description and images of your plugins efficiently.
-
-## Automatic code review - Errors
-
-### The required composer.json file was not found
-
-**Cause:** Error in composer.json
-
-One possible cause is that the technical app name from the Community Store or Account does not match the technical name entered in composer.json, or the app is incorrectly zipped.
-The technical app name must be stored in the composer.json, located at `composer.json` > extra > `shopware-plugin-class`.
-Could you take a look at the bootstrap class? Most of the errors are caused by the wrong technical name.
-For example, "Swag\\MyPlugin\\SwagMyPluginSW6" instead of "Swag\\MyPlugin\\SwagMyPlugin".
-
-Link: [Example of a valid composer.json](https://github.com/FriendsOfShopware/FroshPlatformPerformance/blob/master/composer.json#L20).
-
-### Ensure cross-domain messages are sent to the intended domain
-
-Link: ["Cross-document messaging domains should be carefully restricted"](https://rules.sonarsource.com/javascript/RSPEC-2819)
-
-### No bootstrapping file found. Expecting bootstrapping in
-
-The bootstrap cannot be found.
-The reasons could be that the folder structure in the ZIP file needs to be corrected, a typo, or a case-sensitive error in the app source (e.g., in the technical name).
-
-### Class Shopware\Storefront\* not found
-
-Missing requirements in the composer.json (e.g. "require": {"shopware/frontend": "*"},)
-
-Link: "[Shopware App Development: App Meta Information - Explanation of the properties](../../../../../guides/plugins/plugins/plugin-base-guide#the-composerjson-file)
-
-### Cookies are written safely
-
-Be sure you set cookies as secure.
-Remember to register your cookie to the *Cookie Consent Manager*.
-
-### Call to static method jsonEncode() on an unknown class
-
-Shopware always uses json_Encode exclusively - there is no other fallback.
-
-### The lock file is not up to date with the latest changes in composer.json
-
-You may need to get updated dependencies. Run an update to update them.
-
-The `composer.lock` in the app archive has to be deleted.
-
-### Class Shopware\Core\System\Snippet\Files\SnippetFileInterface not found and could not be autoloaded
-
-In the Shopware 6 Early Access (EA) version, the mentioned class did not exist.
-Therefore, the code review failed. The reason for the problem is the following specification in the composer.json:
-
-```xml
-
-<pre>"require": {
-
- "shopware/core": "*",
-
- "shopware/storefront": "*"
-
-},</pre>
-```
-
-The Composer resolves this to "Whatever is the latest from these repositories" and then installs the Early Access version instead of the current Release Candidate.
-This happens because the Composer does not know an EA as a stability level (like stable or RC) and is, therefore, ultimately considered "stable".
-The solution is to amend the requirement as follows:
-
-```xml
-<pre>"require": {
-
- "shopware/core": "~6.1.0",
-
- "shopware/storefront": "~6.1.0"
-
-},
-
-"minimum-stability": "RC"</pre>
-```
-
-This ensures that at least version Shopware 6.1 is installed, even if it is a Release Candidate.
-It will be preferred as soon as the final 6.1 is released.
-
-### Remove out-commented code from your source-code
-
-### Unauthorized file formats or folders detected in the app
-
-Remove out-commented code, unused files and folders, and all dev-files from your binary.
-
-Here are some examples of not allowed folders and files:
-
-* ./tests
-* .DS_Store
-* .editorconfig
-* .eslintrc.js
-* .git
-* .github
-* .gitignore
-* .gitkeep
-* .gitlab-ci.yml
-* .gitpod.Dockerfile
-* .gitpod.yml
-* .phar
-* .php-cs-fixer.cache
-* .php-cs-fixer.dist.php
-* .php_cs.cache
-* .php_cs.dist
-* .prettierrc
-* .stylelintrc
-* .stylelintrc.js
-* .sw-zip-blacklist
-* .tar
-* .tar.gz
-* .travis.yml
-* .zip
-* .zipignore
-* ISSUE_TEMPLATE.md
-* Makefile
-* Thumbs.db
-* __MACOSX
-* auth.json
-* bitbucket-pipelines.yml
-* build.sh
-* composer.lock
-* eslint.config.js
-* grumphp.yml
-* package-lock.json
-* package.json
-* phpdoc.dist.xml
-* phpstan-baseline.neon
-* phpstan.neon
-* phpstan.neon.dist
-* phpunit.sh
-* phpunit.xml.dist
-* phpunitx.xml
-* psalm.xml
-* rector.php
-* shell.nix
-* stylelint.config.js
-* webpack.config.js
diff --git a/resources/guidelines/troubleshooting/index.md b/resources/guidelines/troubleshooting/index.md
deleted file mode 100644
index 2abc7f7837..0000000000
--- a/resources/guidelines/troubleshooting/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Troubleshooting
- position: 10
-
----
-
-# Troubleshooting
-
-Use this section to diagnose and resolve common issues you might encounter while working with Shopware projects.
diff --git a/resources/references/administration-reference/index.md b/resources/references/administration-reference/index.md
deleted file mode 100644
index 48b54480c4..0000000000
--- a/resources/references/administration-reference/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Administration Reference
- position: 50
-
----
-
-# Administration Reference
-
-This section covers concepts on Utils, Mixins and Directives.
diff --git a/resources/references/api-reference/index.md b/resources/references/api-reference/index.md
deleted file mode 100644
index 0c108436a1..0000000000
--- a/resources/references/api-reference/index.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-nav:
- title: API Reference
- position: 10
-
----
-
-# API Reference
-
-The API references provide detailed information about the available endpoints, methods, parameters, request and response formats, and authentication mechanisms of an API. It provides essential information on how to interact with the API, what data can be sent or received, and how to handle different API responses.
-
-These references guide you to use the correct syntax, understand the expected input and output formats, implement the necessary authentication mechanisms and successful API requests and effectively utilize the functionality provided by the API in your applications.
-
-There are two dedicated API reference documents for your reference:
-
-* [Store API reference](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) - Focused on customer-facing aspects, the Store API allows you to access and manipulate data related to products, customer interactions, shopping carts, and others that significantly impact the frontend user experience. It caters to both anonymous and authenticated users.
-
-* [Admin API reference](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide) - Primarily for backend and administrative functions, the Admin API enables structured data exchanges, bulk operations, data synchronization, and import-export tasks, addressing the backend needs of the Shopware platform.
diff --git a/resources/references/app-reference/index.md b/resources/references/app-reference/index.md
index ce4c1e9835..fc9cbc0801 100644
--- a/resources/references/app-reference/index.md
+++ b/resources/references/app-reference/index.md
@@ -7,6 +7,32 @@ nav:
# App Reference
-The app reference document gives you an understanding of the app structure, functions, methods, events, variables, responses, and examples for building quality apps in Shopware.
+This section provides structured reference documentation for building Shopware Apps. Use these references when implementing specific app features, configuring the manifest, or working with scripts and webhooks.
-Overall, the app reference document is a valuable resource for creating feature-rich and seamless custom apps that integrate seamlessly with the Shopware platform.
+## Manifest and configuration
+
+Technical reference for `manifest.xml` and its supported sections:
+
+* [Manifest Reference](manifest-reference.md)
+* [CMS Reference](cms-reference.md)
+* [Entities Reference](entities-reference.md)
+* [Flow Action Reference](flow-action-reference.md)
+* [Payment Reference](payment-reference.md)
+* [Webhook Events Reference](webhook-events-reference.md)
+
+## Script reference
+
+Technical reference for Twig-based app scripts and available services:
+
+* [Script Reference](script/index.md)
+
+Includes:
+
+* Cart manipulation services
+* Data loading services
+* Custom endpoint services
+* Product services
+* Miscellaneous services
+* Available hooks
+
+Use the [App Base Guide](../../../guides/plugins/apps/app-base-guide) for step-by-step development.
diff --git a/resources/references/commands-reference.md b/resources/references/commands-reference.md
new file mode 100644
index 0000000000..6b37dc2aa2
--- /dev/null
+++ b/resources/references/commands-reference.md
@@ -0,0 +1,423 @@
+---
+nav:
+ title: Commands Reference
+ position: 10
+
+---
+
+# Commands Reference
+
+These commands can be executed using the Shopware command line interface \(CLI\), located within your Shopware project.
+
+```bash
+$ bin/console [command] [parameters]
+```
+
+## Commands
+
+### General
+
+| Command | Description |
+|:-------------|:-----------------------------------------------|
+| `about` | Displays information about the current project |
+| `completion` | Dump the shell completion script |
+| `help` | Displays help for a command |
+| `list` | Lists commands |
+
+### Administration
+
+| Command | Description |
+|:-----------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `administration:delete-extension-local-public-files` | Deletes all files in the local public folder of the extension. This command should run after assets:install so the assets are available in the public folder. |
+| `administration:delete-files-after-build` | Deletes all unnecessary files of the administration after the build process |
+
+### App
+
+| Command | Description |
+|:-------------------------|:-------------------------------------------------------------------------|
+| `app:activate` | Activates the app in the folder with the given name |
+| `app:create` | Creates an app skeleton |
+| `app:deactivate` | Deactivates the app in the folder with the given name |
+| `app:install` | Installs the app in the folder with the given name |
+| `app:list` | Lists all apps |
+| `app:refresh` | \[app:update\] Refreshes the installed apps |
+| `app:uninstall` | Uninstalls the app |
+| `app:url-change:resolve` | Resolves changes in the app URL and how the app system should handle it. |
+| `app:validate` | Checks manifests for errors |
+
+### Assets
+
+| Command | Description |
+|:-----------------|:---------------------------------------------------------|
+| `assets:install` | Installs bundles web assets under a public web directory |
+
+### Bundle
+
+| Command | Description |
+|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------------|
+| `bundle:dump` | \[administration:dump:plugins\|administration:dump:bundles\] Creates a JSON file with the configuration for each active Shopware bundle. |
+
+### Cache
+
+| Command | Description |
+|:-----------------------------|:------------------------------------------------------------------------------------------------|
+| `cache:clear` | Clears the cache |
+| `cache:clear:all` | Clear all caches/pools, invalidates expired tags, removes old system and twig cache directories |
+| `cache:clear:delayed` | Invalidates the delayed cache keys/tags |
+| `cache:clear:http` | Clear only the HTTP cache |
+| `cache:pool:clear` | Clears cache pools |
+| `cache:pool:delete` | Deletes an item from a cache pool |
+| `cache:pool:invalidate-tags` | Invalidate cache tags for all or a specific pool |
+| `cache:pool:list` | Lists available cache pools |
+| `cache:pool:prune` | Prunes cache pools |
+| `cache:warmup` | Warms up an empty cache |
+| `cache:watch:delayed` | Watches the delayed cache keys/tags |
+
+### Cart
+
+| Command | Description |
+|:---------------|:--------------------------------------|
+| `cart:migrate` | Migrates carts from redis to database |
+
+### Changelog
+
+| Command | Description |
+|:--------------------|:-------------------------------------------------------------------------------------------------------|
+| `changelog:change` | Returns all changes made in a specific / unreleased version. |
+| `changelog:check` | Checks the validation of a given changelog file or of all files in the "changelog/\_unreleased" folder |
+| `changelog:create` | Creates a changelog markdown file in `/changelog/_unreleased` |
+| `changelog:release` | Creates or updates the final changelog for a new release |
+
+### Config
+
+| Command | Description |
+|:------------------------|:-------------------------------------------------|
+| `config:dump-reference` | Dumps the default configuration for an extension |
+
+### Customer
+
+| Command | Description |
+|:--------------------------------|:-------------------------------|
+| `customer:delete-unused-guests` | Deletes unused guest customers |
+
+### Dal
+
+| Command | Description |
+|:-----------------------|:---------------------------------------|
+| `dal:create:entities` | Creates the entity classes |
+| `dal:create:hydrators` | Creates the hydrator classes |
+| `dal:migration:create` | Creates migration for entity schema |
+| `dal:create:schema` | Creates the database schema |
+| `dal:refresh:index` | Refreshes the index for a given entity |
+| `dal:validate` | Validates the DAL definitions |
+
+### Database
+
+| Command | Description |
+|:-------------------------------|:---------------------------------------|
+| `database:clean-personal-data` | Cleans personal data from the database |
+| `database:create-migration` | Creates a new migration file |
+| `database:migrate` | Executes all migrations |
+| `database:migrate-destructive` | Executes all migrations |
+| `database:refresh-migration` | Refreshes the migration state |
+
+### Debug
+
+| Command | Description |
+|:-------------------------|:-----------------------------------------------------------|
+| `debug:autowiring` | Lists classes/interfaces you can use for autowiring |
+| `debug:business-events` | Dumps all business events |
+| `debug:config` | Dumps the current configuration for an extension |
+| `debug:container` | Displays current services for an application |
+| `debug:dotenv` | Lists all dotenv files with variables and values |
+| `debug:event-dispatcher` | Displays configured listeners for an application |
+| `debug:messenger` | Lists messages you can dispatch using the message buses |
+| `debug:router` | Displays current routes for an application |
+| `debug:scheduler` | Lists schedules and their recurring messages |
+| `debug:serializer` | Displays serialization information for classes |
+| `debug:translation` | Displays translation messages information |
+| `debug:twig` | Shows a list of twig functions, filters, globals and tests |
+| `debug:validator` | Displays validation constraints for classes |
+
+### Dotenv
+
+| Command | Description |
+|:--------------|:--------------------------------------------|
+| `dotenv:dump` | Compile .env files to .env.local.php |
+
+### Error
+
+| Command | Description |
+|:-------------|:---------------------------------------------------------------------------------|
+| `error:dump` | Dump error pages to plain HTML files that can be directly served by a web server |
+
+### Es
+
+| Command | Description |
+|:--------------------------|:-----------------------------------------------|
+| `es:admin:index` | Indexes the elasticsearch for the admin search |
+| `es:admin:mapping:update` | Update the Elasticsearch indices mapping |
+| `es:admin:reset` | Reset Admin Elasticsearch indexing |
+| `es:admin:test` | Allows you to test the admin search index |
+| `es:create:alias` | Creates the elasticsearch alias |
+| `es:index` | Reindexes all entities to elasticsearch |
+| `es:index:cleanup` | Cleans outdated indices |
+| `es:mapping:update` | Update the Elasticsearch indices mapping |
+| `es:reset` | Resets the elasticsearch index |
+| `es:status` | Shows the status of the elasticsearch index |
+| `es:test:analyzer` | Allows to test an elasticsearch analyzer |
+
+### Feature
+
+| Command | Description |
+|:------------------|:-----------------------------------------------------------------------------------------------------------------------|
+| `feature:disable` | Disable feature flags |
+| `feature:dump` | \[administration:dump:features\] Creates a JSON file with feature config for JS testing and hot reloading capabilities |
+| `feature:enable` | Enable feature flags |
+| `feature:list` | List all registered features |
+
+### Framework
+
+| Command | Description |
+|:------------------------------|:-----------------------------------------|
+| `framework:demodata` | Generates demo data |
+| `framework:dump:class:schema` | Dumps the schema of the given entity |
+| `framework:schema` | Dumps the api definition to a json file. |
+
+### Http
+
+| Command | Description |
+|:---------------------|:------------------------|
+| `http:cache:warm:up` | Warms up the HTTP cache |
+
+### Import
+
+| Command | Description |
+|:----------------|:---------------------------------|
+| `import:entity` | Imports entities from a CSV file |
+
+### Import-export
+
+| Command | Description |
+|:-------------------------------|:----------------------------------------|
+| `import-export:delete-expired` | Deletes all expired import/export files |
+
+### Integration
+
+| Command | Description |
+|:---------------------|:--------------------------------------------------|
+| `integration:create` | Create an integration and dump the key and secret |
+
+### Lint
+
+| Command | Description |
+|:--------------------|:----------------------------------------------------------------------|
+| `lint:container` | Ensures that arguments injected into services match type declarations |
+| `lint:translations` | Lint translations files syntax and outputs encountered errors |
+| `lint:twig` | Lints a Twig template and outputs encountered errors |
+| `lint:xliff` | Lints a XLIFF file and outputs encountered errors |
+| `lint:yaml` | Lints a YAML file and outputs encountered errors |
+
+### Mailer
+
+| Command | Description |
+|:--------------|:--------------------------------------------|
+| `mailer:test` | Tests Mailer transports by sending an email |
+
+### Make plugin
+
+Generating the skeletons and essential files needed to create and structure a Shopware plugin.
+
+ | Command | Description |
+ |:------------------------------------|:-----------------------------------------------|
+ | `make:plugin:admin-module` | Generate an administration module skeleton |
+ | `make:plugin:command` | Generate a plugin CLI command skeleton |
+ | `make:plugin:composer` | Generate a composer configuration for a plugin |
+ | `make:plugin:config` | Generate a plugin system config skeleton |
+ | `make:plugin:custom-fieldset` | Generate a custom field set for a plugin |
+ | `make:plugin:entity` | Generate entity scaffolding for a plugin |
+ | `make:plugin:event-subscriber` | Generate an event subscriber skeleton |
+ | `make:plugin:javascript-plugin` | Generate a JavaScript plugin skeleton |
+ | `make:plugin:plugin-class` | Generate the base plugin class |
+ | `make:plugin:scheduled-task` | Generate a scheduled task skeleton |
+ | `make:plugin:store-api-route` | Generate a Store API route skeleton |
+ | `make:plugin:storefront-controller` | Generate a Storefront controller skeleton |
+ | `make:plugin:tests` | Generate a plugin tests skeleton |
+
+### Media
+
+| Command | Description |
+|:--------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `media:delete-local-thumbnails` | Deletes all physical media thumbnails when remote thumbnails is enabled. |
+| `media:delete-unused` | Deletes all media files that are never used. Use the `--dry-run` flag to see a paginated list of files that will be deleted, without actually deleting them. Use the `--grace-period-days=10` to set a grace period for unused media, meaning only media uploaded before the current date and time minus 10 days will be considered for deletion. The default is 20 and therefore any media uploaded in the previous 20 days will not be considered for deletion even if it is unused. Use the `--folder-entity` flag to target only a specific folder (e.g. `--folder-entity=PRODUCT` to purge all product images) |
+| `media:generate-media-types` | Generates the media types for all media entities |
+| `media:generate-thumbnails` | Generates the thumbnails for all media entities |
+| `media:update-path` | Iterates over the media and updates the path column. |
+
+### Messenger
+
+| Command | Description |
+|:-----------------------------|:--------------------------------------------------------|
+| `messenger:consume` | Consumes messages |
+| `messenger:failed:remove` | Removes given messages from the failure transport |
+| `messenger:failed:retry` | Retries one or more messages from the failure transport |
+| `messenger:failed:show` | Shows one or more messages from the failure transport |
+| `messenger:setup-transports` | Prepares the required infrastructure for the transport |
+| `messenger:stats` | Shows the message count for one or more transports |
+| `messenger:stop-workers` | Stops workers after their current message |
+
+### Number-range
+
+| Command | Description |
+|:-----------------------|:-------------------------------------------------|
+| `number-range:migrate` | Migrates the increment storage of a number range |
+
+### Plugin
+
+| Command | Description |
+|:--------------------|:---------------------------------------------------------------|
+| `plugin:activate` | Activates given plugins |
+| `plugin:create` | Creates a plugin skeleton |
+| `plugin:deactivate` | Deactivates given plugins |
+| `plugin:install` | Installs given plugins |
+| `plugin:list` | Lists all plugins |
+| `plugin:refresh` | Refreshes the plugins list in the storage from the file system |
+| `plugin:uninstall` | Uninstalls given plugins |
+| `plugin:update` | Updates given plugins |
+| `plugin:update:all` | Install all available plugin updates |
+| `plugin:zip-import` | Imports a plugin from a zip file |
+
+### Product-export
+
+| Command | Description |
+|:--------------------------|:--------------------------------|
+| `product-export:generate` | Generates a product export file |
+
+### Router
+
+| Command | Description |
+|:---------------|:---------------------------------------------------|
+| `router:match` | Helps debug routes by simulating a path info match |
+
+### S3
+
+| Command | Description |
+|:--------------------|:----------------------------------------------------------------|
+| `s3:set-visibility` | Sets the visibility of all files in the s3 filesystem to public |
+
+### Sales-channel
+
+| Command | Description |
+|:------------------------------------|:----------------------------------------------|
+| `sales-channel:create` | Creates a new sales channel |
+| `sales-channel:create:storefront` | Creates a new storefront sales channel |
+| `sales-channel:list` | Lists all sales channels |
+| `sales-channel:maintenance:disable` | Disables maintenance mode for a sales channel |
+| `sales-channel:maintenance:enable` | Enables maintenance mode for a sales channel |
+| `sales-channel:update:domain` | Updates a sales channel domain |
+
+### Scheduled-task
+
+| Command | Description | Version |
+|:----------------------------|:------------------------------|:--------|
+| `scheduled-task:deactivate` | Deactivate a scheduled task | 6.7.2.0 |
+| `scheduled-task:register` | Registers all scheduled tasks |
+| `scheduled-task:run` | Runs scheduled tasks |
+| `scheduled-task:run-single` | Runs single scheduled tasks | 6.5.5.0 |
+| `scheduled-task:list` | Lists all scheduled tasks | 6.5.5.0 |
+| `scheduled-task:schedule` | Schedule a scheduled task | 6.7.2.0 |
+
+### Secrets
+
+| Command | Description |
+|:-----------------------------|:--------------------------------------------------------|
+| `secrets:decrypt-to-local` | Decrypts all secrets and stores them in the local vault |
+| `secrets:encrypt-from-local` | Encrypts all local secrets to the vault |
+| `secrets:generate-keys` | Generates new encryption keys |
+| `secrets:list` | Lists all secrets |
+| `secrets:remove` | Removes a secret from the vault |
+| `secrets:reveal` | Reveal the value of a secret |
+| `secrets:set` | Sets a secret in the vault |
+
+### Server
+
+| Command | Description |
+|:--------------|:-----------------------------------------------------------------------|
+| `server:dump` | Start a dump server that collects and displays dumps in a single place |
+| `server:log` | Start a log server that displays logs in real time |
+
+### Services
+
+| Command | Description |
+|:-------------------|:----------------------|
+| `services:install` | Install all services |
+
+### Sitemap
+
+| Command | Description |
+|:-------------------|:-----------------------------------------------------------|
+| `sitemap:generate` | Generates sitemaps for a given shop \(or all active ones\) |
+
+### Snippets
+
+| Command | Description |
+|:--------------------|:-------------------|
+| `snippets:validate` | Validates snippets |
+
+### State-machine
+
+| Command | Description |
+|:---------------------|:-----------------------------------------|
+| `state-machine:dump` | Dumps a state machine to a graphviz file |
+
+### Store
+
+| Command | Description |
+|:-----------------|:----------------------------------|
+| `store:download` | Downloads a plugin from the store |
+| `store:login` | Login for the store |
+
+### System
+
+| Command | Description |
+|:-----------------------------|:-----------------------------------------------------------------------------------|
+| `system:check` | Check the shopware application system health |
+| `system:config:get` | Gets a config value |
+| `system:config:set` | Sets a config value |
+| `system:configure-shop` | Configures the shop |
+| `system:generate-app-secret` | Generates a new app secret |
+| `system:generate-jwt-secret` | Generates a new JWT secret |
+| `system:install` | Installs the Shopware 6 system |
+| `system:is-installed` | Checks if the system is installed and returns exit code 0 if Shopware is installed |
+| `system:setup` | Setup the system |
+| `system:setup:staging` | Installs the Shopware 6 system in staging mode |
+| `system:update:finish` | Finishes the update process |
+| `system:update:prepare` | Prepares the update process |
+
+### Theme
+
+| Command | Description |
+|:----------------------|:---------------------------------------------|
+| `theme:change` | Changes the active theme for a sales channel |
+| `theme:compile` | Compiles the theme |
+| `theme:create` | Creates a theme skeleton |
+| `theme:dump` | Dumps the theme configuration |
+| `theme:prepare-icons` | Prepares the theme icons |
+| `theme:refresh` | Refreshes the theme configuration |
+
+### Translation
+
+| Command | Description |
+|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------|
+| `translation:extract` | Extract missing translations keys from code to translation files |
+| `translation:install` | Downloads and installs translations from the translations GitHub repository for the specified locales or all available locales |
+| `translation:pull` | Pull translations from a given provider. |
+| `translation:push` | Push translations to a given provider. |
+
+### User
+
+| Command | Description |
+|:-----------------------|:-------------------------------|
+| `user:change-password` | Changes the password of a user |
+| `user:create` | Creates a new user |
+| `user:list` | List current users |
diff --git a/resources/references/config-reference/index.md b/resources/references/config-reference/index.md
deleted file mode 100644
index a32b623a83..0000000000
--- a/resources/references/config-reference/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Config Reference
-
-This section gives you a reference on server configuration.
diff --git a/resources/references/config-reference/server/apache.md b/resources/references/config-reference/server/apache.md
deleted file mode 100644
index b40222374d..0000000000
--- a/resources/references/config-reference/server/apache.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Apache
-
-::: info
-The document root must always point to the public folder, to ensure all functionality works.
-:::
-
-```text
-<VirtualHost *:80>
- ServerName "HOST_NAME"
- DocumentRoot _SHOPWARE_LOCATION_/public
-
- <Directory _SHOPWARE_LOCATION_>
- Options Indexes FollowSymLinks MultiViews
- AllowOverride All
- Order allow,deny
- allow from all
- </Directory>
-
- ErrorLog ${APACHE_LOG_DIR}/shopware.error.log
- CustomLog ${APACHE_LOG_DIR}/shopware.access.log combined
-</VirtualHost>
-```
diff --git a/resources/references/config-reference/server/caddy.md b/resources/references/config-reference/server/caddy.md
deleted file mode 100644
index 9db63a85b1..0000000000
--- a/resources/references/config-reference/server/caddy.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Caddy
-
-```text
-mydomain.com {
- header {
- X-Frame-Options DENY
- Referrer-Policy no-referrer-when-downgrade
- }
-
- @svg {
- file
- path *.svg
- }
-
- header @svg Content-Security-Policy "script-src 'none'"
-
- @default {
- not path /theme/* /media/* /thumbnail/* /bundles/* /css/* /fonts/* /js/* /recovery/* /sitemap/*
- }
-
- root * public
- php_fastcgi 127.0.0.1:9000
- encode zstd gzip
- file_server
-}
-```
diff --git a/resources/references/config-reference/server/index.md b/resources/references/config-reference/server/index.md
deleted file mode 100644
index 080f8c2223..0000000000
--- a/resources/references/config-reference/server/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Server
-
-This section gives you a reference on server configuration.
diff --git a/resources/references/core-reference/actions-reference.md b/resources/references/core-reference/actions-reference.md
deleted file mode 100644
index c810c93f4b..0000000000
--- a/resources/references/core-reference/actions-reference.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Actions Reference
-
-## B2B
-
-| Class | Description | Component |
-|:------------------------------------------------|:---------------------------------------------------------------|:--------------------|
-| ChangeEmployeeStatusAction | Assigns the configured status to the employee | Employee Management |
-| ChangeCustomerSpecificFeaturesAction | Adds or removes the configured b2b components for the customer | Employee Management |
diff --git a/resources/references/core-reference/index.md b/resources/references/core-reference/index.md
deleted file mode 100644
index a84ca7e8e0..0000000000
--- a/resources/references/core-reference/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Core Reference
- position: 20
-
----
-
-# Core Reference
-
-The Core reference documents essential components like the DAL, administration panel, flags, filters, Flow Builder, and Rules for efficient platform usage. It details about the classes, methods, commands, events, etc, for your reference. This helps you understand how to use these features to enhance the functionality.
diff --git a/resources/references/index.md b/resources/references/index.md
index e937a0dd77..dc59ae4227 100644
--- a/resources/references/index.md
+++ b/resources/references/index.md
@@ -7,4 +7,43 @@ nav:
# References
-The references serve as essential resources for developers, administrators, and testers, providing comprehensive details on implementation parameters. They cover every aspect of the platform, including objects, functions, classes, and more. By consulting these references, you will be able to gain a deep understanding of Shopware's capabilities and utilize its features effectively in your development, administration, and testing tasks.
+This section contains structured technical reference documentation for Shopware. Use it when you need precise specifications, XML schemas, CLI commands, event payloads, or implementation details. Step-by-step guides are in other sections.
+
+## Core & Platform References
+
+Behavior, parameters, and configuration:
+
+* **Security**: Platform security features, configuration options, and hardening
+* **Commands Reference**: Complete CLI command overview (`bin/console`)
+* System & configuration details
+
+## App Development Reference
+
+Authoritative reference documentation for building Shopware Apps and implementing or validating features:
+
+* **Manifest Reference**: `manifest.xml` structure and supported sections
+* **CMS Reference**: `cms.xml` blocks and slots definition
+* **Entities Reference**: `entities.xml` schema and relations
+* **Flow Action Reference**: `flow-action.xml` definition
+* **Payment Reference**: App-based payment API contracts
+* **Webhook Events Reference**: Available webhook events, payloads, and permissions
+
+## Script Reference
+
+Detailed reference for Twig-based App Scripts:
+
+* Available services
+* Cart manipulation
+* Data loading
+* Custom endpoints
+* Hooks and extension points
+
+## Architecture Decision Records (ADRs)
+
+The ADR folder documents architectural decisions made in Shopware:
+
+* Rationale behind technical design choices
+* Trade-offs and constraints
+* Historical context for core architecture
+
+Consult ADRs when you need to understand *why* something works the way it does.
diff --git a/resources/references/storefront-reference/index.md b/resources/references/storefront-reference/index.md
deleted file mode 100644
index 9a445ebba3..0000000000
--- a/resources/references/storefront-reference/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Storefront Reference
- position: 60
-
----
-
-# Storefront Reference
-
-The storefront reference documents functions, filters, and extensions that are available for customizing storefronts. It helps you understand how to use these features to enhance the functionality and appearance of your storefront.
diff --git a/resources/references/testing-reference/e2e-commands.md b/resources/references/testing-reference/e2e-commands.md
deleted file mode 100644
index 90f3a45457..0000000000
--- a/resources/references/testing-reference/e2e-commands.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-nav:
- title: E2E Commands
- position: 20
-
----
-
-# E2E Commands
-
-| Command | Description |
-|:--------------------------------------|:-----------------------------------------------------------------|
-| `bin/console e2e:restore-db` | Sets Shopware back to state of the backup |
-| `APP_ENV=e2e bin/console e2e:dump-db` | Creates a backup of Shopware's database |
-| `composer run e2e:setup` | Prepares Shopware installation and environment for Cypress usage |
-| `composer run e2e:open` | Opens Cypress' e2e tests runner |
-| `composer run e2e:prepare` | Install dependencies and prepare database for Cypress usage |
-| `composer e2e:cypress -- run --spec="cypress/e2e/administration/**/*.cy.js"` | Runs Cypress' admin e2e tests in CLI |
-| `composer e2e:cypress -- run --spec="cypress/e2e/storefront/**/*.cy.js"` | Runs Cypress' storefront e2e tests in CLI |
diff --git a/resources/references/testing-reference/e2e-custom-commands.md b/resources/references/testing-reference/e2e-custom-commands.md
deleted file mode 100644
index dbd2560098..0000000000
--- a/resources/references/testing-reference/e2e-custom-commands.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-nav:
- title: Custom E2E Commands
- position: 10
-
----
-
-# Custom E2E Commands
-
-## General commands
-
-| Command | Parameter | Description |
-| :--- | :--- | :--- |
-| setLocaleToEnGb | - | Switches administration UI locale to EN\_GB |
-| login | `(userType)` | Logs in to the Administration manually |
-| typeAndCheck | `(textToType)` | Types in an input element and checks if the content was correctly typed |
-| clearTypeAndCheck | `(textToType)` | Clears field, types in an input element and checks if the content was correctly typed |
-| typeMultiSelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in a sw-select field and checks if the content was correctly typed \(multi select\) |
-| typeSingleSelect | `(textToType, selector)` | Types in an sw-select field \(single select\) |
-| typeSingleSelectAndCheck | `(textToType, selector)` | Types in an sw-select field and checks if the content was correctly typed \(single select\) |
-| typeLegacySelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in an legacy swSelect field and checks if the content was correctly typed |
-| typeAndCheckSearchField | `(searchTerm)` | Types in the global search field and verify search terms in url |
-| awaitAndCheckNotification | `(message)` | Wait for a notification to appear and check its message |
-| clickContextMenuItem | `(actionInMenuSelector, openMenuSelector, scope = '')` | Click context menu in order to cause a desired action |
-| clickMainMenuItem | `({ targetPath, mainMenuId, subMenuId })` | Navigate to module by clicking the corresponding main menu item |
-| openUserActionMenu | `({ targetPath, mainMenuId, subMenuId })` | Click user menu to open it up |
-| dragTo | `(target)` | Drags the previous subject element to a target, performing a drag and drop operation |
-| onlyOnFeature | `(feature)` | Only run the test \(skip otherwise\) if the feature is activated |
-| skipOnFeature | `(feature)` | Skip the test if the feature is activated |
-
-## Storefront-related / Sales Channel API commands
-
-| Command | Parameter | Description |
-| :--- | :--- | :--- |
-| getSalesChannelId | - | Get the sales channel Id via Admin API |
-| storefrontApiRequest | `(method, endpoint, header = {}, body = {})` | Performs Storefront API Requests |
-| getRandomProductInformationForCheckout | - | Returns random product with id, name and url to view product |
-
-## System Commands
-
-| Command | Parameter | Description |
-| :--- | :--- | :--- |
-| activateShopwareTheme | - | Activates Shopware theme for Cypress test runner |
-| cleanUpPreviousState | - | Cleans up any previous state by restoring database and clearing caches |
-| openInitialPage | - | Opens up the administration initially and waits for the "me" call to be successful |
-
-## API commands
-
-| Command | Parameter | Description |
-| :--- | :--- | :--- |
-| authenticate | - | Authenticate towards the Shopware API |
-| loginViaApi | - | Logs in silently using Shopware API |
-| searchViaAdminApi | `(data)` | Search for an existing entity using Shopware API at the given endpoint |
-| requestAdminApi | `(method, url, requestData)` | Handling API requests |
-| updateViaAdminApi | `(endpoint, id, data)` | Updates an existing entity using Shopware API at the given endpoint |
-
-## Fixture commands
-
-| Command | Parameter | Description |
-| :--- | :--- | :--- |
-| setToInitialState | - | Sets Shopware back to its initial state if using platform E2E backup routine |
-| createDefaultFixture | `(endpoint, data = {}, jsonPath)` | Create entity using Shopware API via given endpoint |
-| createProductFixture | `(userData = {})` | Create product fixture using Shopware API via given endpoint |
-| createCategoryFixture | `(userData = {})` | Create category fixture using Shopware API via given endpoint |
-| createSalesChannelFixture | `(userData = {}` | Create sales channel fixture using Shopware API via given endpoint |
-| setSalesChannelDomain | `(salesChannelName = 'Storefront')` | Create sales channel domain using Shopware API at the given endpoint |
-| createCustomerFixture | `(userData = {})` | Create customer fixture using Shopware API via given endpoint |
-| createCmsFixture | `(userData = {})` | Create cms fixture using Shopware API at the given endpoint |
-| createPropertyFixture | `(options, userData)` | Create property fixture using Shopware API at the given endpoint |
-| createLanguageFixture | - | Create language fixture using Shopware API at the given endpoint |
-| createShippingFixture | `(userData)` | Create shipping fixture using Shopware API at the given endpoint |
-| createSnippetFixture | - | Create snippet fixture using Shopware API at the given endpoint |
-| createGuestOrder | `productId, userData)` | Create guest order fixture |
-| setProductFixtureVisibility | `(productName, categoryName)` | Sets category and visibility for a product in order to set it visible in the Storefront |
diff --git a/resources/references/testing-reference/index.md b/resources/references/testing-reference/index.md
deleted file mode 100644
index 547041bd74..0000000000
--- a/resources/references/testing-reference/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Testing Reference
- position: 70
-
----
-
-# Testing Reference
-
-In this reference, all Shopware commands provided by [E2E-testsuite-platform](https://github.com/shopware/e2e-testsuite-platform) or [Shopware Platform](https://github.com/shopware/shopware) are listed here.
diff --git a/resources/references/upgrades/administration/index.md b/resources/references/upgrades/administration/index.md
deleted file mode 100644
index ce7b1d6f0a..0000000000
--- a/resources/references/upgrades/administration/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Administration
- position: 10
-
----
-
-# Administration
-
-This section contains all upgrade guides related to the Shopware Administration.
diff --git a/resources/references/upgrades/administration/vue3.md b/resources/references/upgrades/administration/vue3.md
deleted file mode 100644
index 4fcb3c1dfb..0000000000
--- a/resources/references/upgrades/administration/vue3.md
+++ /dev/null
@@ -1,140 +0,0 @@
----
-nav:
- title: Vue 3 upgrade
- position: 10
-
----
-
-# Vue 3 upgrade
-
-## Introduction
-
-The Shopware administration uses Vue.js `2`, which will reach its end of life (EOL) **on December 31st 2023**. To deliver up-to-date and maintainable software, the administration will use Vue.js `3` from Shopware version `6.6` and upwards. If you are unfamiliar with the changes from Vue.js `2` to Vue.js `3`, please refer to this [official guide](https://v3-migration.vuejs.org/).
-
-## FAQ
-
-Let's start with some frequently asked questions. These will also help you figure out if this upgrade affects you.
-
-### Which extensions are affected by the Vue 3 upgrade?
-
-App-based extensions aren't affected by these changes. However, if your extension is plugin-based and contains custom administration code, you likely need to do some refactoring.
-
-### Are there any breaking changes I should be aware of?
-
-Yes, Vue 3 introduced breaking changes. It's crucial to review the migration guide provided by Vue.js and this document for detailed information.
-
-### What steps should I follow to upgrade my Shopware plugin to Vue 3?
-
-Typically, the process involves updating your project dependencies and modifying your code to adhere to Vue 3's API changes. Consult the Vue 3 documentation and this document's step-by-step instructions.
-
-### Can one plugin version be compatible with Shopware 6.5 and 6.6?
-
-No, your plugin requires a new version in the Store. For instance, version `1.x` is for Shopware `6.5.x`, while version `2.0` is compatible with Shopware `6.6` and newer.
-
-### How can I check if my Shopware extension is compatible with Vue 3?
-
-You can verify compatibility by reviewing the extension's functionality and updating test suites according to this document.
-
-### Do I need to rewrite my extension to upgrade to Vue 3?
-
-While some changes are required, a complete rewrite is not necessary. The amount of effort is dictated by your use of Vue's internal API.
-
-### Are tools or libraries available to facilitate the migration to Vue 3?
-
-Yes, there are tools and migration helpers that can automate certain aspects of the upgrade process. You could start by enabling the Vue 3 rule set of `eslint`.
-
-### Where can I find support and community discussions about updating Shopware plugin to Vue 3?
-
-You can participate in discussions and seek help on the Shopware community Discord. There is a dedicated channel for this topic called `#shopware-development`.
-
-## External resources
-
-Here is a handpicked selection of external resources. This list provides a handy reference, granting you access to all the essential materials you might need.
-
-- [Vue 3 migration guide](https://v3-migration.vuejs.org)
-- [Vue 3 breaking changes](https://v3-migration.vuejs.org/breaking-changes/)
-- [Vue router migration guide](https://router.vuejs.org/guide/migration/)
-- [Vue test utils migration guide](https://test-utils.vuejs.org/migration/)
-
-## Step-by-step guide
-
-To follow along, you should have the following:
-
-- the latest Shopware `trunk` or an official release candidate
-- installed and activated your plugin
-- a running administration watcher (`composer run watch:admin`)
-
-### Update your plugin npm dependencies
-
-Make sure to align your `package.json` dependencies with the [administration](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/package.json).
-
-### Check your templates
-
-For your templates to work correctly, perform the following in no specific order:
-
-- Replace all `sw-field` usages with the corresponding [components](https://github.com/shopware/shopware/blob/6.5.x/src/Administration/Resources/app/administration/src/app/component/form/sw-field/index.js#L16).
-- [Check all v-models](https://v3-migration.vuejs.org/breaking-changes/v-model.html)
-- [Check event listeners](https://v3-migration.vuejs.org/breaking-changes/v-model.html#_3-x-syntax)
-- [Check for deprecated slot syntax](https://eslint.vuejs.org/rules/no-deprecated-slot-attribute.html)
-- [Check router-view transition combinations](https://router.vuejs.org/guide/migration/#-router-view-keep-alive-and-transition-)
-- [Check your key attributes](https://v3-migration.vuejs.org/breaking-changes/key-attribute.html)
-- [Check for filter usages](https://v3-migration.vuejs.org/breaking-changes/filters.html)
-
-### Check your code
-
-Most of your code should be unaffected by the upgrade. You can start by searching for `this.$`. The usage of `this.$` is an indicator of Vue's internal API. These calls are very likely to break except for `this.$tc`.
-
-If you have a lot of Vue internal API calls, check out the [Known issues section](#known-issues).
-The best way to find errors is to test your application thoroughly, either by hand or automated.
-
-## Known issues
-
-### Lifecycle hooks
-
-Lifecycle hooks such as `@hook:mounted` may be triggered multiple times if the component is loaded asynchronously. Vue 3 will emit the hook for the `AsyncComponentWrapper` and the underlying component. You can only use those hooks if your code allows to be executed multiple times.
-
-### Using slots programmatically
-
-It is no longer sufficient to check if `this.$slots` has a property with the slot name to see if that slot exists. Instead, you must verify if your `slotName` contains an actual `v-node`.
-
-### this.$parent
-
-`this.$parent` is prone to errors because Vue 3 wraps the `AsyncWrapperComponent` around asynchronous components. Leading to the virtual dom tree to differ from Vue 2 to Vue 3. Where in Vue 2, a `this.$parent` call was successful, in Vue 3, a `this.$parent.$parent` may be necessary.
-Try to avoid `this.$parent` communication wherever possible as this is an anti pattern. Use services or event communication instead.
-
-### Vue dev tools performance
-
-Vue dev tools causes massive performance issues with huge Vue 3 applications.
-There is an open [issue on Github](https://github.com/vuejs/devtools-v6/issues/1875) with next to no activity from the maintainers.
-
-### v-model changes
-
-`v-model` has several breaking changes. Please consider the official [guide](https://v3-migration.vuejs.org/breaking-changes/v-model.html)
-
-### vuex reactivity
-
-Vuex stores lose reactivity if one or more getters alter state data. For more context, see [here](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#reactivity-fundamentals).
-
-### Form field id's
-
-Fields in the administration no longer have the previous ID almost exclusively used in tests. To fix any failing test, add the `name` attribute to your field with a unique identifier.
-
-### Prop default
-
-Prop default functions no longer have access to the component's `this` scope. You can no longer call `this.$tc` in default functions. Use `Shopware.Snippet.tc` instead.
-
-### Mutating props
-
-This is an antipattern also for Vue 2. In Vue 2, however, those mutations were not always detected. In Vue 3, this will fail with hard errors. Take a look at this [example](https://eslint.vuejs.org/rules/no-mutating-props.html) to get a basic understanding of how to avoid mutating props directly.
-
-## Conclusion
-
-This document emphasizes the crucial need to upgrade your Shopware extensions to Vue.js 3 as Vue.js 2 reaches its end of life on December 31st 2023. Here's a concise recap of the key points:
-
-- **Transition to Vue 3**: Shopware will adopt Vue.js 3 from version 6.6 onwards.
-- **FAQ**: Addressing frequently asked questions:
- - **Extension Compatibility**: Plugin-based extensions with custom administration code are primarily affected. App-based extensions remain unaffected.
- - **Breaking Changes**: Vue 3 introduces significant modifications, necessitating review through the Vue.js migration guide.
- - **Migration Steps**: Adapting your Shopware plugin to Vue 3 involves aligning dependencies and adhering to Vue 3's API changes, following the Vue 3 documentation.
-- **Dual Compatibility**: For plugins serving both Shopware 6.5 and 6.6, separate versions are required.
-- **Support**: Find support in the Shopware community Discord channel #shopware-development.
diff --git a/resources/references/upgrades/core/index.md b/resources/references/upgrades/core/index.md
deleted file mode 100644
index e5d404a66e..0000000000
--- a/resources/references/upgrades/core/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Core
- position: 20
-
----
-
-# Core upgrade and migration guides
-
-This section contains all upgrade and migration guides related to the Shopware Core.
diff --git a/resources/references/upgrades/core/translation/extension-translation.md b/resources/references/upgrades/core/translation/extension-translation.md
deleted file mode 100644
index ff25abbddd..0000000000
--- a/resources/references/upgrades/core/translation/extension-translation.md
+++ /dev/null
@@ -1,106 +0,0 @@
----
-nav:
-title: Migrating Extensions
-position: 20
----
-
-# Migrating Extension Translations to the Country-Independent Snippet Layer
-
-Starting with **Shopware 6.7.3**, a new country-independent snippet layer has been introduced to reduce duplicate
-translations across similar language variants (e.g., `en-GB`, `en-US`, `en-CA` can share a common "en" base layer).
-
-This change implements a hierarchical fallback system that automatically resolves translations through multiple layers,
-significantly reducing maintenance overhead for extension developers.
-
-## How the New System Works
-
-The snippet loading system now follows this resolution order:
-
-1. **Country-specific layer** (e.g., `en-GB`, `de-DE`) — Highest priority
-2. **Language base layer** (e.g., `en`, `de`, `es`) **NEW fallback layer**
-3. **British English fallback** (`en-GB`) - Legacy fallback to maximize compatibility
-4. **Default fallback** (`en`) - Last resort
-
-When a translation key is requested, Shopware will:
-
-- First check the specific country variant (e.g., `es-AR`)
-- If not found, check the base language (e.g., `es`)
-- If not found, the legacy fallback will be checked (`en-GB`)
-- Finally, fall back to `en` if still not found
-
-**Result**: ~90% reduction in duplicate translations while maintaining full functionality.
-
-## Migrating Your Extensions
-
-### Automatic
-
-Shipping with Shopware **6.7.3**, there's the command line tool `bin/console translation:lint-filenames` that can be used to
-check the translation files, or use the `--fix` parameter to even automate the migration process. For more information, see [this migration article](../../../../../concepts/translations/fallback-language-selection.md#migration-and-linting-via-command).
-
-### Manual
-
-#### Step 1: Rename your existing files
-
-Rename your existing files from country-specific naming to the language base layer naming.
-
-```Generic
-├── messages.en-GB.base.json ⇒ messages.en.base.json
-├── messages.de-DE.base.json ⇒ messages.de.base.json
-├── messages.fr-FR.base.json ⇒ messages.fr.base.json
-└···
-```
-
-#### Step 2: Re-create empty country-specific files
-
-Re-create empty files with the former names of the country-specific naming.
-
-```Generic
-├── messages.en-GB.base.json
-├── messages.de-DE.base.json
-├── messages.fr-FR.base.json
-└···
-```
-
-#### Step 3: Remove duplicates from other country-specific files
-
-Check for duplicate translations across country-specific files and remove them from the country-specific layer.
-
-Here are some example locales that are a dialect to the generic base layer.
-
-```Generic
-├── messages.en-US.base.json (dialect of en-GB with the en base layer)
-├── messages.en-IN.base.json (dialect of en-GB with the en base layer)
-├── messages.de-AT.base.json (dialect of de-DE with the de base layer)
-├── messages.de-CH.base.json (dialect of de-DE with the de base layer)
-├── messages.pt-BR.base.json (dialect of pt-PT with the pt base layer)
-└···
-```
-
-For more details on selecting a fallback language and structuring your snippet files, see the [Fallback Languages guide](../../../../../concepts/translations/fallback-language-selection.md).
-
-## Testing Your Migration
-
-After the snippet files have been renamed, changing the locale to one of the empty snippet sets should still provide
-all translated strings. Changing to a country-specific locale should also provide all translated strings with just
-country-specific terms being replaced.
-
-## Best Practices
-
-### 1. Maintain Backward Compatibility
-
-Keep existing country-specific files during transition to ensure compatibility with older Shopware versions that don't
-support the base layer.
-
-## Troubleshooting
-
-### Common Migration Issues
-
-#### 1. Translations Not Found After Migration
-
-**Symptoms**: Missing translations in frontend/backend after restructuring
-**Solution**:
-
-```bash
-bin/console cache:clear
-bin/console snippet:validate
-```
diff --git a/resources/references/upgrades/core/translation/index.md b/resources/references/upgrades/core/translation/index.md
deleted file mode 100644
index 98cfc5a4e8..0000000000
--- a/resources/references/upgrades/core/translation/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Translation
- position: 10
-
----
-
-# Update And Migration Guides For Translations In The Shopware Core
-
-This section contains all upgrade and migration guides related to translations in the Shopware Core.
diff --git a/resources/references/upgrades/index.md b/resources/references/upgrades/index.md
deleted file mode 100644
index 023adeb784..0000000000
--- a/resources/references/upgrades/index.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-nav:
- title: Upgrades and Migrations
- position: 50
-
----
-
-# Upgrades and Migrations
-
-Software projects typically undergo changes and upgrades, for Shopware this is not different.
-This section provides you with comprehensive update guides for specific technical changes.
diff --git a/resources/tooling/cli/index.md b/resources/tooling/cli/index.md
deleted file mode 100644
index f94529f69a..0000000000
--- a/resources/tooling/cli/index.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-nav:
- title: CLI
- position: 10
-
----
-
-# CLI
diff --git a/resources/tooling/ide/index.md b/resources/tooling/ide/index.md
deleted file mode 100644
index 445496aee8..0000000000
--- a/resources/tooling/ide/index.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-nav:
- title: IDE
- position: 20
-
----
-
-# IDE
diff --git a/resources/tooling/index.md b/resources/tooling/index.md
deleted file mode 100644
index c650f6da87..0000000000
--- a/resources/tooling/index.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-nav:
- title: Tooling
- position: 30
-
----
-
-# Tooling