chore: push major docs revision (do not merge)

guides/development/accessibility/index.md

@@ -0,0 +1,23 @@
+---
+nav:
+  title: Accessibility
+  position: 20
+---
+
+# Accessibility
+
+Shopware is committed to creating inclusive and barrier-free shopping experiences. Accessibility affects both the core Storefront and all custom themes and extensions. Developers are responsible for ensuring that their implementations follow accessibility standards such as WCAG 2.1 AA.
+
+## In this section
+
+* <PageRef page="./storefront-accessibility" />
+* <PageRef page="./accessibility-checklist" />
+
+## Why accessibility matters
+
+* Legal compliance (e.g., EU accessibility regulations)
+* Better usability for all users
+* Improved SEO and performance
+* Future-proof storefront implementations
+
+Shopware continuously introduces accessibility improvements in new releases. Always test extensions with the `ACCESSIBILITY_TWEAKS` feature flag enabled to ensure compatibility.

guides/development/apis/index.md

@@ -0,0 +1,79 @@
+---
+nav:
+  title: Working with APIs
+  position: 10
+
+---
+
+# Working with APIs
+
+Shopware provides two HTTP APIs:
+
+* [Admin API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide)
+* [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide).
+
+These APIs serve different purposes but share common principles and infrastructure.
+
+## Admin API
+
+Primarily for backend and administrative functions, the Admin API enables structured data exchanges, bulk operations, data synchronization, and import-export tasks.
+
+Use it when:
+
+* Managing entities (products, categories, orders)
+* Running backend integrations
+* Performing bulk operations
+* Building admin-side applications
+
+Full endpoint documentation (local instance required): `/api/_info/stoplightio.html`.
+
+Search endpoints use: `POST /api/search/{entity}`
+
+## Store API
+
+This customer-facing API allows you to access and manipulate data related to products, customer interactions, shopping carts, and other aspects of Shopware that significantly impact the frontend user experience. It serves both anonymous and authenticated users.
+
+Use it when:
+
+* Interacting with products and listings
+* Managing carts and checkout
+* Building headless storefronts
+* Serving anonymous or authenticated customers
+
+Full endpoint documentation (local instance required): `/store-api/_info/stoplightio.html`
+
+## Shared API mechanics
+
+Both APIs use the same foundational structures:
+
+* [Search Criteria](search-criteria): encapsulates the entire search definition in one generic object
+* [Request Headers](request-headers): additional instructions
+* [Partial Data Loading](partial-data-loading)
+
+These define how data is filtered, structured, and versioned.
+
+For architectural background, see the [API overview](apis).
+
+## Generated API reference
+
+### OpenAPI schema
+
+Shopware exposes OpenAPI schemas for both Admin API and Store API. These schemas are generated via PHP annotations using [swagger-php](https://github.com/zircote/swagger-php). If you build custom endpoints, you can leverage these annotations to generate standardized documentation for your custom endpoints.
+
+::: warning
+Due to security restrictions, your **`APP_ENV`** environment variable must be set to **`dev`** to access the specifications described below.
+:::
+
+To retrieve the raw schema definition directly, use the following endpoint:
+
+```text
+/(api|store-api)/_info/openapi3.json
+```
+
+### Entity schema
+
+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
+```

guides/integrations-api/general-concepts/request-headers.md → guides/development/apis/request-headers.md

@@ -7,7 +7,9 @@ nav:
 
 # Request Headers
 
-## sw-language-id
+## Common headers
+
+### sw-language-id
 
 By default, the API delivers the entities via the system language. This can be changed by specifying a language id using the `sw-language-id` header.
 
@@ -40,24 +42,25 @@ POST /api/search/product
 --header 'sw-inheritance: 1'
 ```
 
-## sw-skip-trigger-flow
-
-Flows are an essential part of Shopware and are triggered by events like the creation of a customer. When migrating from another e-commerce platform to shopware, you might import hundreds of thousands of customers via the sync API. In that case, you don't want to trigger the `send email on customer creation` flow. To avoid this behavior, you can pass the `sw-skip-trigger-flow` header.
+## sw-context-token
 
-```bash
-POST /api/_action/sync
---header 'sw-skip-trigger-flow: 1'
-```
+The `sw-context-token` is used to recognize your customers in the context of the Store API. Refer to [Authentication & Authorization](https://shopware.stoplight.io/docs/store-api/8e1d78252fa6f-authentication-and-authorisation) section of Store API for more details on this.
 
 ## sw-access-token
 
 Any request to the Store API needs an Authentication with a `sw-access-token`. Refer to [Authentication & Authorization](https://shopware.stoplight.io/docs/store-api/8e1d78252fa6f-authentication-and-authorisation) section of Store API for more details on this.
 
-## sw-context-token
+## sw-app-user-id
 
-The `sw-context-token` is used to recognize your customers in the context of the Store API. Refer to [Authentication & Authorization](https://shopware.stoplight.io/docs/store-api/8e1d78252fa6f-authentication-and-authorisation) section of Store API for more details on this.
+The `sw-app-user-id` header allows apps to execute API requests in the context of a specific user. When this header is included, the system calculates the effective permissions by intersecting the user's permissions with the app's permissions, ensuring that the request runs with the most restrictive permissions from both sources.
+
+This header is particularly useful when an app needs to perform actions on behalf of a user while maintaining proper permission boundaries.
+
+To use the `sw-app-user-id` header, the specified user must either be an admin user, have explicit permission for the specific app, or have the `app.all` permission.
 
-## sw-currency-id
+## Advanced headers
+
+### sw-currency-id
 
 When calling the API, a client can include the `sw-currency-id` header to indicate the currency in which it wants to receive prices. For example, if the header is set to "USD," the API might respond with prices converted to U.S. dollars. This header is associated with the currency settings in the admin panel. It allows clients to dynamically switch between different currencies based on their preferences.
 
@@ -66,7 +69,16 @@ POST /api/search/order
 --header 'sw-currency-id: 1987f5c352434028802556e065cd5b1e'
 ```
 
-## sw-include-seo-urls
+### sw-skip-trigger-flow
+
+Flows are an essential part of Shopware and are triggered by events like the creation of a customer. When migrating from another e-commerce platform to shopware, you might import hundreds of thousands of customers via the sync API. In that case, you don't want to trigger the `send email on customer creation` flow. To avoid this behavior, you can pass the `sw-skip-trigger-flow` header.
+
+```bash
+POST /api/_action/sync
+--header 'sw-skip-trigger-flow: 1'
+```
+
+### sw-include-seo-urls
 
 This header indicates whether SEO-friendly URLs for products or categories should be included in the API response. If an API request is made and the `sw-include-seo-urls` header is set, the API response will include all the configured SEO URLs for the specified product. This can provide additional information to the client about the various SEO-friendly paths associated with the product, allowing for better SEO management or customization.
 
@@ -75,14 +87,6 @@ POST /api/search/product
 --header 'sw-include-seo-urls: 1'
 ```
 
-## sw-app-integration-id
+### sw-app-integration-id
 
 The `sw-app-integration-id` enables seamless connection and data exchange between different software components. This header is required for correct permission checks performed by the backend when fetching or manipulating data. It overrides the default behavior and uses the privileges provided by the app. This is used in the Meteor Admin SDK for the [Repository Data Handling](/resources/admin-extension-sdk/api-reference/data/repository). But the developer itself doesn’t need to care about it because it is handled automatically by the admin.
-
-## sw-app-user-id
-
-The `sw-app-user-id` header allows apps to execute API requests in the context of a specific user. When this header is included, the system calculates the effective permissions by intersecting the user's permissions with the app's permissions, ensuring that the request runs with the most restrictive permissions from both sources.
-
-This header is particularly useful when an app needs to perform actions on behalf of a user while maintaining proper permission boundaries.
-
-To use the `sw-app-user-id` header, the specified user must either be an admin user, have explicit permission for the specific app, or have the `app.all` permission.