Merge branch 'main' into add-faqs

Author: sushmangupta

.gitbook.yaml

@@ -93,7 +93,7 @@ redirects:
     products/cli/project-commands/project-config-sync.html: guides/development/tooling/fixture-bundle.html
     products/sales-agent/deployment.html: products/sales-agent/best-practices/app-deployment/hosted-with-ubuntu-server.html
     guides/installation/requirements.html: guides/installation/system-requirements.html
-    guides/installation/setups/docker.html: guides/installation/docker-setup.html
+    guides/installation/setups/docker.html: guides/installation/legacy-setups/docker-setup.html
     guides/installation/template.html: guides/installation/project-overview.html
     guides/installation/setups/docker-options.html: guides/installation/advanced-options.html
     guides/installation/setups/devenv.html: guides/installation/legacy-setups/devenv-setup.html
@@ -181,3 +181,5 @@ redirects:
     resources/references/core-reference/flow-reference.html: guides/development/troubleshooting/flow-reference.html
     resources/references/core-reference/rules-reference.html: guides/development/troubleshooting/rules-reference.html
     guides/hosting/installation-updates/extension-managment.html: guides/hosting/installation-updates/extension-management.html
+    guides/installation/start-developing.html: guides/development/start-developing.html
+    

.github/workflows/validate-external-links.yml

@@ -18,7 +18,7 @@ jobs:
         uses: lycheeverse/lychee-action@v2
         with:
           fail: false
-          args: --retry-wait-time 10 --max-retries 3 --timeout 30 --accept=200,403,429,408 -s "https"  "**/*.html" "**/*.md" "**/*.txt" "**/*.json" --exclude "https://github.com/\[your*" --exclude "https://localhost:9200" --base-url https://developer.shopware.com 
+          args: --retry-wait-time 10 --max-retries 3 --timeout 30 --accept=200,403,429,408 -s "https"  "**/*.html" "**/*.md" "**/*.txt" "**/*.json" --exclude "https://github.com/\[your*" --exclude "https://localhost:9200"
 
       - name: Find Link Checker Issue
         uses: micalevisk/last-issue-action@v2

.wordlist.txt

@@ -1277,6 +1277,7 @@ control
 copyToClipboard
 copyable
 cors
+countryId
 createActionResponse
 createCategoryFixture
 createCmsFixture
@@ -1687,6 +1688,7 @@ opcache
 openInitialPage
 openSUSE
 openUserActionMenu
+openapi
 opensearch
 openssl
 orchestrator
@@ -1843,6 +1845,7 @@ salesChannelId
 salesChannelLoaded
 saleschannel
 saleschannelrepositoryfacade
+salutationId
 sandboxed
 sarven
 scalability

concepts/extensions/apps-concept.md

@@ -7,51 +7,51 @@ nav:
 
 # Apps
 
-The app system allows you to extend and modify the functionality and appearance of Shopware. It leverages well defined extension points you can hook into to implement your specific use case.
+The app system allows you to extend and modify the functionality and appearance of Shopware. It leverages well-defined extension points you can hook into to implement your specific use case.
 
 The app system is designed to be decoupled from Shopware itself. This has two great advantages:
 
 1. **Freedom of choice:** You need to understand only the interface between Shopware and your app to get started with developing your own app. You don't need special knowledge of the inner workings and internal structure of Shopware itself. Additionally, you have the freedom to choose a programming language or framework of your choice to implement your app. This is achieved by decoupling the deployment of Shopware itself and your app and by using the Admin API and webhooks to communicate between Shopware and your app instead of using programming language constructs directly.
-2. **Fully cloud compatible:** By decoupling Shopware and your app, your app is automatically compatible for use in a multi-tenant cloud system. Therefore your app can be used within self-hosted shops and shops on [Shopware SaaS](../../products/saas).
+2. **Fully cloud compatible:** By decoupling Shopware and your app, your app is automatically compatible with multi-tenant cloud systems. Therefore, your app can be used within self-hosted shops and shops on [Shopware SaaS](../../products/saas.md).
 
-The central interface between your app and Shopware is defined by a dedicated manifest file. The manifest is what glues Shopware and your app together. It defines your app's features and how Shopware can connect to it. You can find more information about how to use the manifest file in the [App base Guide](../../guides/plugins/apps/app-base-guide).
+The central interface between your app and Shopware is defined by a dedicated manifest file. The manifest is what glues Shopware and your app together. It defines your app's features and how Shopware can connect to it. You can find more information about how to use the manifest file in the [App base Guide](../../guides/plugins/apps/app-base-guide.md).
 
 ## Communication between Shopware and your app
 
-Shopware communicates with your app only exclusively via HTTP-Requests. Therefore you are free to choose a tech stack for your app, as long as you can serve HTTP-Requests. Shopware will notify you of events happening in the shop that your app is interested in by posting to HTTP-Endpoints that you define in the manifest file. While processing these events, your app can use the Shopware API to get additional data that your app needs. A schematic overview of the communication may look like this:
+Shopware communicates with your app exclusively via HTTP requests. Therefore, you are free to choose a tech stack for your app, as long as you can serve HTTP requests. Shopware will notify you of events happening in the shop that your app is interested in by posting to HTTP endpoints that you define in the manifest file. While processing these events, your app can use the Shopware API to get additional data that your app needs. A schematic overview of the communication may look like this:
 
 ![Communication between Shopware and your app](../../assets/extensions-apps-shopwareCommunication.svg)
 
-To secure this communication, a registration handshake is performed during the installation of your app. During this registration, it is verified that Shopware talks to the right app backend server, and your app gets credentials used to authenticate against the API. You can read more on the registration workflow in the [App base guide](../../guides/plugins/apps/app-base-guide).
+To secure this communication, a registration handshake is performed during the installation of your app. During this registration, it is verified that Shopware talks to the right app backend server, and your app gets credentials used to authenticate against the API. See [App registration & backend setup](../../guides/plugins/apps/app-registration-setup.md).
 
 ::: info
-Notice that this is optional if Shopware and your app don't need to communicate, e.g., because your app provides a [Theme](apps-concept).
+Note that this is optional if Shopware and your app don't need to communicate, e.g., because your app provides a [Theme](../../guides/plugins/themes/index.md).
 :::
 
 ## Modify the appearance of the Storefront
 
-Your app can modify the Storefront's appearance by shipping your Storefront assets \(template files, javascript sources, SCSS sources, snippet files\) alongside your manifest file. You don't need to serve those assets from your external server, as Shopware will rebuild the Storefront upon the installation of your app and will consider your modifications in that process. Find out more about modifying the appearance of the Storefront in the [App Storefront guide](../../guides/plugins/apps/storefront/)
+Your app can modify the Storefront's appearance by shipping your Storefront assets \(template files, JavaScript sources, SCSS sources, snippet files\) alongside your manifest file. You don't need to serve those assets from your external server, as Shopware will rebuild the Storefront upon the installation of your app and will consider your modifications in that process. Find out more about modifying the appearance of the Storefront in the [App Storefront guide](../../guides/plugins/apps/storefront/index.md).
 
 ## Integrate payment providers
 
 ::: info
 This functionality is available starting with Shopware 6.4.1.0.
 :::
 
-Shopware provides functionality for your app to be able to integrate payment providers. You can use the synchronous payment to provide payment with a provider that does not require any user interaction, for which you can choose a simple request for approval in the background. You can use an asynchronous payment if you would like to redirect a user to a payment provider. Your app, therefore, provides a URL for redirection. After the user returns to the shop, Shopware will verify the payment status with your app. Find out more about providing payment endpoints in the [App payment guide](../../guides/plugins/apps/payment).
+Shopware provides functionality that allows your app to integrate payment providers. You can use synchronous payments with providers that do not require user interaction; in that case, approval can be requested with a simple background request. You can use asynchronous payments if you want to redirect the user to a payment provider. Your app then provides a URL for redirection. After the user returns to the shop, Shopware will verify the payment status with your app. Find out more about providing payment endpoints in the [App payment guide](../../guides/plugins/apps/payment.md).
 
 ## Execute business logic inside Shopware with App Scripts
 
 ::: info
 This functionality is available starting with Shopware 6.4.8.0.
 :::
 
-[App scripts](../../guides/plugins/apps/app-scripts/) allow your app to execute custom business logic inside the Shopware execution stack. This allows for new use cases, e.g., if you need to load additional data that should be rendered in the Storefront or need to manipulate the cart.
+[App scripts](../../guides/plugins/apps/app-scripts/index.md) allow your app to execute custom business logic inside the Shopware execution stack. This allows for new use cases, e.g., if you need to load additional data that should be rendered in the Storefront or need to manipulate the cart.
 
 ## Add conditions to the Rule Builder
 
 ::: info
 This functionality is available starting with Shopware 6.4.12.0.
 :::
 
-Your app may introduce custom conditions for use in the [Rule builder](../framework/rules). For additional information refer to [Add custom rule conditions](../../guides/plugins/apps/rule-builder/add-custom-rule-conditions) from the guides.
+Your app may introduce custom conditions for use in the [Rule builder](../framework/rule-system/index.md). For more information, refer to [Add custom rule conditions](../../guides/plugins/apps/rule-builder/add-custom-rule-conditions.md) in the guides.

guides/development/extensions/architecture/index.md

@@ -1,7 +1,7 @@
 ---
 nav:
   title: Extension Architecture
-  position: 1
+  position: 10
 ---
 
 # Extension Architecture
@@ -35,8 +35,8 @@ Extensions must respect these principles to avoid:
 
 When extending Shopware, it is critical to understand what is part of the stable Public API and what is not:
 
-* [Public API and internal Annotation](internal.md)
-* [Final and internal Annotations](final-and-internal.md)
+* [Public API and Internal Annotation](internal.md)
+* [Final and Internal Annotation](final-and-internal.md)
 
 These guides define what extension developers can rely on and what may change without notice.
 

guides/development/extensions/index.md

@@ -20,11 +20,11 @@ Plugins and apps are installed and activated for the whole Shopware instance.
 Before choosing an extension type, review the recommended [Code structure](code-structure.md). Following the standard structure reduces upgrade friction and prevents long-term maintenance issues.
 :::
 
-A storefront theme is *not* a separate extension type, but a stripped-down plugin consisting of a customized storefront UI. In cloud environments, storefront themes are delivered via apps.
+A storefront theme is *not* a separate extension type, but a stripped-down plugin consisting of a customized storefront UI. In Cloud environments, storefront themes are delivered via apps.
 
 ## Monetization
 
-To sell an extension or offer paid features, see the [Monetization guide](../../development/monetization/) for available models such as paid extensions, In-App Purchases, and commission-based integrations.
+To sell an extension or offer paid features, see the [Monetization guide](../../development/monetization/index.md) for available models such as paid extensions, In-App Purchases, and commission-based integrations.
 
 ## Which type to build?
 
@@ -40,7 +40,7 @@ This comparison table helps you decide which Shopware extension type best fits y
 | Integrate payment providers                 | ✅                     | ✅   | — |
 | Publish in the Shopware Store               | ✅                     | ✅   | — |
 | Install in Shopware 6 Cloud shops                | ❌                     | ✅   | Plugins (including theme plugins) cannot run in Cloud. |
-| Install in Shopware 6 self-hosted shops     | ✅                     | ✅   | Apps can be installed and used since Shopware 6.4.0.0. |
+| Install in Shopware 6 self-hosted shops     | ✅                     | ✅   | Since Shopware 6.4.0.0, apps can be installed and used in self-hosted shops. |
 | Add custom logic/routes/commands            | ✅                     | ⚠️   | Apps implement logic externally via services and webhooks; they cannot add internal Symfony routes or CLI commands. |
 | Control style/template inheritance          | ✅                     | ✅   | This capability is specific to theme plugins. |
 

guides/development/index.md

@@ -1,18 +1,15 @@
 ---
 nav:
   title: Development
-  position: 30
+  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:
+After [installation](../../guides/installation/index.md), use this guide 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
+* [Build an Extension](../../guides/development/extensions/index.md): Plugins, apps, themes, and Admin or Storefront extensions.
+* [Work with APIs](./integrations-api/index.md): Making API requests, integrating ERP and external systems, and building headless storefronts.
 
 All development scenarios share common foundations:
 
@@ -23,17 +20,19 @@ All development scenarios share common foundations:
 * Configuration
 * Debugging
 
-To build a custom Shopware project without creating an extension for distribution, start here.
+Before starting new development, review the recommended [Code structure](extensions/code-structure.md) guide. A consistent architecture prevents long-term maintenance issues and reduces upgrade friction.
+
+Also review the [Upgrades and Migrations](../upgrades-migrations/index.md) section to avoid patterns that are deprecated or scheduled for removal.
 
 ## Extension development
 
-To build an [Extensions](extensions/index.md), first choose the correct type:
+To build an [Extension](extensions/index.md), first choose the correct type:
 
 * Plugin
 * App
 * Plugin-based theme
 
-Each extension guide walks you through the full development flow: creation → lifecycle → implementation → testing.
+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/index.md) for available models such as paid extensions, In-App Purchases, and commission-based integrations.
 
@@ -49,10 +48,6 @@ Most development follows this sequence:
 * Add configuration or database changes (if required)
 * Test and debug
 
-Before beginning implementation, review the recommended [Code structure](extensions/code-structure.md) guide. A consistent architecture prevents long-term maintenance issues and reduces upgrade friction.
-
-Before starting new development, review the [Upgrades and Migrations](../upgrades-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:
 
@@ -69,7 +64,7 @@ Set up automated testing and [Continuous Integration (CI)](testing/ci.md) early.
 
 ### Administration
 
-To begin any development, first access the Administration by opening [http://localhost/admin](http://localhost/admin).
+Development requires access to the Administration at [http://localhost/admin](http://localhost/admin).
 
 Use the Administration to:
 
@@ -80,13 +75,17 @@ Use the Administration to:
 
 The Administration is part of the runtime environment and will be used throughout development.
 
-### Development tooling
+## Development tooling
 
 * `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../resources/references/core-reference/commands-reference.md).
 * The standalone [Shopware CLI](../../products/cli/installation.md) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](../../products/cli/project-commands/helper-commands.md).
 * IDE support: Shopware provides a [PHPStorm plugin](tooling/shopware-toolbox.md) and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=shopware.shopware-lsp).
-* [Deployment Helper](../hosting/installation-updates/deployments/deployment-helper.md):  Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
+* [Deployment Helper](../hosting/installation-updates/deployments/deployment-helper.md): Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
 
-### Troubleshooting
+## Troubleshooting
 
 The [troubleshooting](troubleshooting/index.md) guides provide reference information about the data abstraction layer (DAL), flow, and rules.
+
+## Next steps
+
+Move on to the [Start Developing guide](start-developing.md).