chore: revises docs

docs/AGENTS.md

@@ -0,0 +1,3 @@
+# Agent Guidelines
+
+When renaming or moving documentation files under `docs/admin-sdk/`, add redirect entries to `docs/admin-sdk/docs.yml` mapping old `.html` paths to new ones so the developer portal preserves external links.

docs/admin-sdk/CHANGELOG.md

@@ -1,4 +1,4 @@
-# admin-sdk-docs
+# Changelog
 
 ## 1.0.0
 

docs/admin-sdk/api-reference/base-options.md

@@ -1,19 +1,89 @@
-# Base options
-There are options that exist for every message type in the SDK. You'll find a list with all of them below.
+# Base Options
 
-| Name         | Required | Default        | Availability        | Description                                                                                     |
-| :----------- | :------- | :------------- | :------------------ | :---------------------------------------------------------------------------------------------- |
-| `privileges` | false    |                | >= Shopware 6.6.3.0 | The privileges that will be checked before executing the message in the Shopware Administration |
+Base options are shared configuration options that can be passed to SDK methods which accept a single payload object. They are provided as additional properties alongside the method's own parameters.
 
-## Example privileges
-```typescript
-import * as sw from '@shopware-ag/meteor-admin-sdk';
+This applies to APIs such as `notification.dispatch()`, `toast.dispatch()`, many `ui.*` methods, `context.*`, `data.get()`, and `data.update()`.
 
-// This notification will only be displayed if the user has `product:read` permissions.
-sw.notification.dispatch({
+Higher-level data helpers such as `data.repository.*` and `data.subscribe()` currently use narrower method signatures and do not expose base options on their public API.
+
+More options may be added in the future. Currently, the following option is available:
+
+| Name         | Required | Default | Availability        | Description                                                                                |
+| :----------- | :------- | :------ | :------------------ | :----------------------------------------------------------------------------------------- |
+| `privileges` | false    |         | >= Shopware 6.6.3.0 | Check the current user's privileges before executing the action. See [Privileges](#privileges). |
+
+#### Usage
+
+In this example, the base options are passed on the same object as the method-specific fields:
+
+```ts
+import { notification } from '@shopware-ag/meteor-admin-sdk';
+
+notification.dispatch({
+    title: 'Product report ready',
+    message: 'Your product report is ready',
+    /* ... base options ... */
+});
+```
+
+## Privileges
+
+The `privileges` option accepts an array of privilege strings. When provided, the SDK checks whether the current Administration user holds all listed privileges before executing the action. If any privilege is missing, the action is silently skipped.
+
+:::warning Not a security feature
+Privilege checks happen client-side in the browser. They prevent UI elements from appearing for users who lack the required permissions, but they do not enforce access control on the server. Server-side authorization is still required for any sensitive operation.
+:::
+
+#### Privilege string format
+
+Each privilege string follows the pattern `action:entity`:
+
+```
+'product:read'
+'order:update'
+'category:create'
+'customer:delete'
+```
+
+Available actions:
+
+| Action       | Description                          |
+| :----------- | :----------------------------------- |
+| `read`       | Read access to the entity            |
+| `create`     | Permission to create new entities    |
+| `update`     | Permission to modify existing entities |
+| `delete`     | Permission to remove entities        |
+| `additional` | Custom additional privileges         |
+
+#### Usage
+
+Pass the `privileges` array to any SDK method that supports base options:
+
+```ts
+import { notification, ui } from '@shopware-ag/meteor-admin-sdk';
+
+notification.dispatch({
+    title: 'Product report ready',
     message: 'Your product report is ready',
     privileges: [
         'product:read',
     ],
 });
+
+ui.actionButton.add({
+    name: 'generate-report',
+    entity: 'product',
+    view: 'detail',
+    label: 'Generate Report',
+    privileges: [
+        'product:read',
+        'order:read',
+    ],
+});
 ```
+
+#### Parameters
+
+| Name         | Type       | Required | Description                                                                 |
+| :----------- | :--------- | :------- | :-------------------------------------------------------------------------- |
+| `privileges` | `string[]` | false    | Array of `action:entity` strings. All must match for the action to execute. |

docs/admin-sdk/api-reference/cms/index.md

@@ -1,5 +1,15 @@
 ---
-title: "CMS"
+title: "Extending the CMS"
 nav:
   position: 300
 ---
+
+
+# Extending the CMS
+
+These CMS extension features allow extensions to register new CMS blocks and CMS elements for use in the Shopware Shopping Experiences editor.
+
+Features in this section include:
+
+- [Register CMS Block](./registerCmsBlock.md): Add custom CMS blocks that define layout structures in the Shopping Experiences editor.
+- [Register CMS Element](./registerCmsElement.md): Create custom CMS elements that render content or functionality inside CMS blocks.

docs/admin-sdk/api-reference/cms/registerCmsBlock.md

@@ -1,3 +1,9 @@
+---
+title: "Register CMS block"
+sidebar_position: 20
+---
+
+
 # Register CMS block
 
 > Available since Shopware v6.6.1.0
@@ -6,8 +12,13 @@ With `cms.registerCmsBlock` you can register CMS blocks to use in the Shopping E
 
 ![Register a CMS block in your Shopping Experiences Module via App](../assets/register-cms-block-example.png)
 
-#### Usage:
+## registerCmsBlock()
+
+#### Usage
+
 ```ts
+import { cms } from '@shopware-ag/meteor-admin-sdk';
+
 cms.registerCmsBlock({
     name: 'dailymotion-dual-block',
     label: 'ex.cms.dailymotion.block.label',
@@ -25,6 +36,7 @@ cms.registerCmsBlock({
 ```
 
 #### Parameters
+
 | Name           | Required | Description                                                                                                                                                                                                                                                                                             |
 | :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `name`         | true     | The name of the cms block - Should have vendor prefix. It can be used in the Storefront for overriding the default layout.                                                                                                                                                                              |
@@ -34,12 +46,15 @@ cms.registerCmsBlock({
 | `previewImage` | false    | The URL of the preview image. This image is shown in the Shopping Experiences Module when selecting the CMS block.                                                                                                                                                                                      |
 | `slotLayout`   | false    | The layout of the slots. This is used to define the grid layout of the slots. You can use the [CSS grid shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/grid) here.                                                                                                                  |
 
+#### Return value
+
+Returns a promise without data.
 
 ## Storefront usage
 
 The CMS block will render automatically in the Storefront without any additional work. It renders the block as a CSS grid with the slots as grid items and the grid shorthand syntax you provided in the `slotLayout` property.
 
-If you want you can override the default layout by creating a new template file in your app. The file should be named `cms-block-app-renderer.html.twig` and should be placed in the `<your-app>/Resources/views/storefront/block` directory of your app folder. More details on how to customize the Storefront in your App can be found in this documentation: https://developer.shopware.com/docs/guides/plugins/apps/storefront/customize-templates.html
+If you want you can override the default layout by creating a new template file in your app. The file should be named `cms-block-app-renderer.html.twig` and should be placed in the `<your-app>/Resources/views/storefront/block` directory of your app folder. More details on how to customize the Storefront in your App can be found in the [Customize Templates](https://developer.shopware.com/docs/guides/plugins/apps/storefront/customize-templates.html) guide.
 
 Inside this file you need to define the block layout and the slots. The block which needs to be created follows this naming pattern: `block_app_renderer_${yourBlockName}`. The `${yourBlockName}` is the name of the block you registered with `cms.registerCmsBlock` except that you need to replace the hyphens with underscores.
 
@@ -65,4 +80,4 @@ Example:
         {% endfor %}
     </div>
 {% endblock %}
-```
+```

docs/admin-sdk/api-reference/cms/registerCmsElement.md

@@ -1,4 +1,10 @@
-# Register CMS element
+---
+title: "Register CMS Element"
+sidebar_position: 30
+---
+
+
+# Register CMS Element
 
 > Available since Shopware v6.4.17.0
 
@@ -7,8 +13,13 @@ More information on how to develop CMS elements can be found in these guides for
 
 ![Register a CMS element in your Shopping Experiences Module via App](../assets/register-cms-element-example.png)
 
-#### Usage:
+## registerCmsElement()
+
+#### Usage
+
 ```ts
+import { cms } from '@shopware-ag/meteor-admin-sdk';
+
 void cms.registerCmsElement({
     name: 'dailymotionElement',
     label: 'Dailymotion Video',
@@ -22,8 +33,13 @@ void cms.registerCmsElement({
 ```
 
 #### Parameters
+
 | Name            | Required | Description                                                                                              |
 |:----------------|:---------|:---------------------------------------------------------------------------------------------------------|
 | `name`          | true     | The name of the cms element, which will also be used to generate locationIds - Should have vendor prefix |
 | `label`         | true     | The label, which is visible when selecting the cms element - Use snippet keys here!                      |
 | `defaultConfig` | true     | Object containing the defaultConfig; same like in plugin development.                                    |
+
+#### Return value
+
+Returns a promise without data.

docs/admin-sdk/api-reference/composables/index.md

@@ -3,3 +3,15 @@ title: "Vue Composables"
 nav:
   position: 400
 ---
+
+
+# Vue Composables
+
+Composable APIs provide reusable Vue Composables for working with the Shopware Administration data layer and shared state inside extensions.
+
+They simplify common tasks such as accessing repositories or sharing reactive state between different parts of an extension.
+
+Currently, the SDK exposes:
+
+- [useRepository](./useRepository.md): Create a reactive repository instance for a given entity.
+- [useSharedState](./useSharedState.md): Share reactive state between different extension components.

docs/admin-sdk/api-reference/composables/useRepository.md

@@ -1,71 +1,45 @@
+---
+title: "useRepository"
+nav:
+  position: 20
+---
+
 # useRepository
 
-The `composables.useRepository` function is a reactive wrapper around the `getRepository` function. It creates a repository instance that automatically updates when its dependencies change. This is particularly useful when you need a repository that responds to reactive data changes in your Vue components.
+The `composables.useRepository` function creates a reactive repository instance that automatically updates when its dependencies change. This is particularly useful when you need a repository that responds to reactive data changes in your Vue components.
+
+`useRepository` accepts reactive references (refs) or values as parameters and returns a computed repository that updates when those parameters change.
 
-Unlike `getRepository`, which returns a static repository instance, `useRepository` accepts reactive references (refs) or values as parameters and returns a computed repository that updates when those parameters change.
+## Usage
 
-#### Usage:  
 ```ts
 // Inside a Vue component setup
-import { ref } from 'vue';
-import { composables } from '@shopware-ag/meteor-admin-sdk';
+import { ref } from "vue";
+import { composables } from "@shopware-ag/meteor-admin-sdk";
 const { useRepository } = composables;
 
 // With a reactive entity name
-const entityName = ref('product');
+const entityName = ref("product");
 const productRepository = useRepository(entityName);
 
 // The repository updates automatically if entityName changes
-entityName.value = 'category';
+entityName.value = "category";
 // Now productRepository.value references a category repository
 
-// With a reactive repository factory
-const myFactory = ref(customRepositoryFactory);
-const repository = useRepository('product', myFactory);
+// With a custom repository factory
+const repository = useRepository("product", myRepositoryFactory);
 
 // Search for products
 const products = await repository.value.search(criteria);
 ```
 
-## Dynamic Repository Creation
-
-The main advantage of `useRepository` is that it automatically recreates the repository when its inputs change:
-
-1. If the entity name changes, a new repository for the different entity type is created
-2. If the repository factory changes, a new repository using the different factory is created
-
-This reactivity is implemented using Vue's computed properties, ensuring that the repository is only recreated when necessary.
-
-#### Parameters
-| Name                | Required | Description                                                     |
-|:--------------------|:---------|:----------------------------------------------------------------|
-| `entityNameRef`     | true     | The name of the entity type as a ref or static value            |
-| `repositoryFactory` | false    | Optional repository factory as a ref or static value            |
+## Parameters
 
-#### Return Value
-A computed ref containing a repository that updates when its dependencies change. The repository provides the same methods as described in the `getRepository` documentation, but you need to access them through the `.value` property of the computed ref.
+| Name                | Required | Description                                          |
+| :------------------ | :------- | :--------------------------------------------------- |
+| `entityNameRef`     | true     | The name of the entity type as a ref or static value |
+| `repositoryFactory` | false    | Optional repository factory as a ref or static value |
 
-## Relationship with getRepository
-
-Under the hood, `useRepository` calls `getRepository` whenever its dependencies change. This means:
-
-- It uses the same repository factory resolution logic as `getRepository`
-- It provides the same repository interface and functionality
-- It adds reactivity, automatically updating when inputs change
-
-```ts
-// Example implementation (simplified)
-import { computed } from 'vue';
-import { getRepository } from './getRepository';
-
-export function useRepository(entityNameRef, factoryRef) {
-  return computed(() => {
-    const entityName = unref(entityNameRef);
-    const factory = unref(factoryRef);
-
-    return getRepository(entityName, factory);
-  });
-}
-```
+## Return value
 
-This pattern follows Vue's composition API conventions, where composables prefixed with "use" typically provide reactive wrappers around non-reactive functionality.
+A computed ref containing a repository that updates when its dependencies change. Access the repository methods through the `.value` property of the computed ref.