Doc refactoring (#1719)

* adapting structure, fixing typos, spelling, grammar and links

* updating gdpr docs

* general extensions restructuring

* extending - custom grid columns

* extending - custom icons & tooltips

* extending - custom perspective widgets

* doc style adaptions & front matter

* doc style adaptions & front matter

* doc style & content adaptions

* doc style & content adaptions

* link fixes

* restructuring studio-backend bundle

* Update README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* add docs for field types and translations

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: lukmzig <lukas.mzigot@pimcore.com>

Author: 3 people

README.md

@@ -11,8 +11,8 @@ It provides a unified interface based on the OpenApi Specification for all backe
 
 It uses [zircote/swagger-php](https://github.com/zircote/swagger-php) attributes to generate the OpenApi Specification.
 
-Swagger-ui is available at `/pimcore-studio/api/docs` and the OpenApi Specification is available at `/pimcore-studio/api/docs.json`.
-Every description is translatable and can be found in the `studio_api_docs.en.yaml` folder of the bundle.
+Swagger UI is available at `/pimcore-studio/api/docs` in the `dev` environment, and the OpenApi Specification (JSON) is available at `/pimcore-studio/api/docs/json`.
+Every description is translatable and can be found in the `studio_api_docs.en.yaml` file of the bundle.
 
 ## Requirements
 This bundle requires the following dependencies:
@@ -22,11 +22,20 @@ This bundle requires the following dependencies:
 * Generic Data Index
 * Mercure (https://mercure.rocks)
 
+## Features in a Nutshell
+
+- OpenAPI-documented REST API for all Pimcore operations (assets, data objects, documents)
+- Real-time updates via Mercure (Server-Sent Events)
+- Extensible architecture: custom endpoints, filters, grid columns, document types
+- Grid system with configurable columns, filters, and data transformers
+- Generic Execution Engine integration for background task processing
+- GDPR data extraction support
+- Perspective and widget system for UI customization
+- Comprehensive event system for customization hooks
+
 ## Documentation Overview
 
-- [Installation](./doc/00_Installation.md)
-- [Mercure Setup](./doc/02_Mercure_Setup.md)
-- [Grid](./doc/03_Grid.md)
-- [Generic Execution Engine](./doc/04_Generic_Execution_Engine.md)
-- [Additional Attributes](./doc/05_Additional_Custom_Attributes.md)
-- [Studio User](./doc/07_User.md)
+- [Architecture Overview](./doc/01_Architecture_Overview/README.md)
+- [Installation and Configuration](./doc/02_Installation_and_Configuration/README.md)
+- [Extending](./doc/03_Extending/README.md)
+- [Development Details](./doc/04_Development_Details/README.md)

doc/03_Grid.md doc/01_Architecture_Overview/01_Grid.mddoc/03_Grid.md renamed to doc/01_Architecture_Overview/01_Grid.md

@@ -1,31 +1,39 @@
+---
+title: Grid
+description: "Grid system architecture: columns, filters, transformers, and configuration."
+---
+
 # Grid
 
-On the request level we have three main components for the grid: `Column`, `ColumnConfiguration` and `ColumnData`.
+The grid API has three main request-level components: `Column`, `ColumnConfiguration`, and `ColumnData`.
 
 ## Column
-A column is a single column in the grid. It has a name, type and a locale. It is used to get the data for the column.
-in addition, it has a configuration which can be used to configure the column, like the direction of the sorting
+
+A column defines which data to fetch. It has a name, type, and locale, plus an optional configuration
+(e.g. sort direction).
 
 ## ColumnConfiguration
-A column configuration represents how the column should behave, for example if it should be sort-able or editable. 
-For the column to be exportable please make sure that it can be represented as a string.
+
+A column configuration declares how the column behaves: sortable, filterable, editable, exportable.
+For export support, the column value must be representable as a string.
 
 ## ColumnData
-A column data is the actual data for a column. It has a reference to the column and the actual data.
 
+The actual data for a column. Contains a reference to the column definition and the resolved value.
 
 ## Filter
-A filter is a way to filter the data in the grid. One Property of getting the grid data is the `filter` property.
-Here you can define `page`, `pageSize` and `includeDescendants`.
 
-`page` is the page number of the data you want to get. 
-`pageSize` is the number of items you want to get.
-`includeDescendants` is a boolean value to include the descendants of the current item.
+The grid `filter` property controls pagination and scope:
+
+- `page` - the page number
+- `pageSize` - the number of items per page
+- `includeDescendants` - whether to include child elements
 
 ### ColumnFilter
-It is also possible to filter the data by a column. This is done by adding a `columnFilter` to the `filter` property.
-A `columnFilter` has a reference to the column and the value you want to filter by. Some filters do not require a 
-specific column, like the `system.tag` filter. This filters will be applied to the general search query.
+
+Add a `columnFilter` to the `filter` property to filter by specific column values. Each column filter
+references a column and a filter value. Some filters (e.g. `system.tag`) apply to the general search
+query and do not require a specific column key.
 
 Available filters are:
 
@@ -52,7 +60,7 @@ Available filters are:
 |         classificationstore.date         | object of ISO 8601<br/>will round to day |          `from`, `to`, or `on`          |      true      |
 |       classificationstore.datetime       |            object of ISO 8601            |          `from`, `to`, or `on`          |      true      |
 |         classificationstore.time         |              object (12:45)              |          `from`, `to`, or `on`          |      true      |
-|    classificationstore.quantity_value    |              sting, integer              | `from`, `to`, `is`, `setting`, `unitId` |      true      |
+|    classificationstore.quantity_value    |              string, integer              | `from`, `to`, `is`, `setting`, `unitId` |      true      |
 | classificationstore.input_quantity_value |                  string                  |    `unitId`(string), `value`(string)    |      true      |
 |        classificationstore.select        |                  array                   |                                         |      true      |
 |       classificationstore.boolean        |                  array                   |        `true`, `false` or `null`        |      true      |
@@ -124,7 +132,7 @@ Filter by Number:
 ```
 
 Classification Store Basic Filter Value:
-The filter value of a Classification Store looks a bit difrent. All Filter need to have a groupId and keyId
+The filter value of a Classification Store looks a bit different. All filters need to have a groupId and keyId
 ```json
 ...
 "columnFilters" [
@@ -167,12 +175,14 @@ To filter by this structure:
 ```
 
 ## Advanced Columns
-Advanced columns are a special type of column that can be used to display data in a more advanced way. There are a few types of data sources for advanced columns:
-- `simpleField` - a simple field in the object
-- `relationField` - a relation field in the object
-- `staticText` - a static text that is not related to the object
 
-Let's take a look at the `simpleField` type. The `simpleField` call the getter method of the object. You just have to pass the `field`.
+Advanced columns combine multiple data sources and transformers. Data source types:
+
+- `simpleField` - calls a getter method on the object
+- `relationField` - resolves a value through a relation
+- `staticText` - a fixed text value, not related to the object
+
+The `simpleField` type calls the object's getter for the specified field:
 ```json
 ...
 "columns": [
@@ -341,7 +351,7 @@ Available configurations:
             "transformers": [
                 {
                   "key": "combine",
-                  "congfig": {
+                  "config": {
                     "glue": " - "
                   }
                 }

doc/04_Generic_Execution_Engine.md …_Overview/02_Generic_Execution_Engine.mddoc/04_Generic_Execution_Engine.md renamed to doc/01_Architecture_Overview/02_Generic_Execution_Engine.md doc/04_Generic_Execution_Engine.md renamed to doc/01_Architecture_Overview/02_Generic_Execution_Engine.md

@@ -1,3 +1,8 @@
+---
+title: Generic Execution Engine
+description: Background task processing for bulk operations, exports, and asynchronous jobs.
+---
+
 # Generic Execution Engine
 :::caution
 
@@ -7,9 +12,11 @@ Messages are dispatched via `pimcore_generic_execution_engine` transport. Please
 
 :::
 
-The Generic Execution Engine is a powerful tool to execute actions in the background. It is based on the Symfony Messenger component, to learn more about it, please visit the [Generic Execution Engine documentation](https://github.com/pimcore/pimcore/tree/11.x/doc/19_Development_Tools_and_Details/08_Generic_Execution_Engine).
+The Generic Execution Engine executes long-running actions in the background using the Symfony Messenger
+component. For the core framework documentation, see the
+[Generic Execution Engine](https://github.com/pimcore/pimcore/blob/2026.x/doc/09_Development_Tools/01_Generic_Execution_Engine/README.md).
 
-There are several actions, which currently take benefits of Execution Engine:
+The Studio Backend uses the Execution Engine for these operations:
 
 ### Asset ZIP Upload
 When uploading a ZIP file containing assets, the ZIP file is extracted and the assets are created in the background.
@@ -28,11 +35,11 @@ pimcore_studio_backend:
 ```
 
 ### Element CSV Export
-Elements like Assets and Data Objects can be exported based on the provided grid configuration as a CSV file. The export is done in the background and can be downloaded after its finished.
+Elements like Assets and Data Objects can be exported based on the provided grid configuration as a CSV file. The export is done in the background and can be downloaded after it's finished.
 There are some configuration options available for the CSV export, which can be configured in the `config.yaml` file.
 
 ### Element XLSX Export
-Elements like Assets and Data Objects can be exported based on the provided grid configuration as a XLSX file. The export is done in the background and can be downloaded after its finished.
+Elements like Assets and Data Objects can be exported based on the provided grid configuration as a XLSX file. The export is done in the background and can be downloaded after it's finished.
 
 ```yaml
 pimcore_studio_backend:
@@ -49,15 +56,15 @@ Assets, Documents, Data Objects and folders can be deleted in the background. Th
 
 ### Elements Recycle Bin
 Before deleting elements, they and the respective children are moved to the recycle bin. This is done in the background while using the Generic Execution Engine.
-by default, recycle bin in only used for elements with less than 100 children. This can be configured in the `config.yaml` file.
+By default, the recycle bin is only used for elements with fewer than 100 children. Configure the threshold in `config.yaml`:
 
 ```yaml
 pimcore_studio_backend:
     element_recycle_bin_threshold: 100
 ```
 
 ### Elements Patching
-Patching of multiple elements is executed with the help of Generic Execution Engine in the background. This is useful when using a bulk patches on a large number of elements.
+Patching of multiple elements is executed with the help of Generic Execution Engine in the background. This is useful when using bulk patches on a large number of elements.
 
 ### Elements Rewrite References
 When cloning elements, the references to other elements can be rewritten. When this is desired, the action is executed in the background. This is useful when cloning a large number of elements or large trees.

doc/01_Architecture_Overview/README.md

@@ -0,0 +1,115 @@
+---
+title: Architecture Overview
+description: REST API design, request flow, tagged service extensibility, and core subsystems.
+---
+
+# Architecture Overview
+
+The Studio Backend Bundle exposes a REST API built on Symfony that serves as the backend for
+Pimcore Studio. All endpoints are documented via OpenAPI/Swagger attributes using the
+[zircote/swagger-php](https://zircote.github.io/swagger-php/) library.
+
+## Request Flow
+
+A typical API request flows through these layers:
+
+```
+HTTP Request
+  → Symfony Firewall (pimcore_studio authentication)
+    → Route matching (#[Route] attribute)
+      → Permission check (#[IsGranted] attribute, UserPermissionVoter)
+        → Controller (extends AbstractApiController)
+          → Service layer (business logic, data access)
+            → Hydrator (transforms models to API schema objects)
+              → PreResponse event (dispatched before serialization)
+                → JSON serialization (Symfony Serializer)
+                  → HTTP Response
+```
+
+**Controllers** extend `AbstractApiController`, which provides `jsonResponse()` for JSON
+serialization and a configurable URL prefix (`{prefix}`). Controllers use Symfony's
+`#[MapQueryString]` and `#[MapRequestPayload]` for type-safe parameter binding.
+
+**Services** encapsulate business logic behind interfaces (e.g. `NoteServiceInterface`,
+`LayoutServiceInterface`). Controllers depend on service interfaces, not implementations.
+
+**Hydrators** transform Pimcore model objects into typed API schema classes. Schema classes
+use OpenAPI `#[Schema]` and `#[Property]` attributes to generate the Swagger documentation.
+
+**PreResponse events** fire after hydration but before serialization, letting subscribers add
+custom attributes or modify the response. See
+[Additional and Custom Attributes](../03_Extending/02_Additional_and_Custom_Attributes.md)
+for the full event list.
+
+## Authentication and Security
+
+The bundle registers its own Symfony firewall (`pimcore_studio`) with a custom user provider
+(`Pimcore\Security\User\UserProvider`). Authentication uses bearer tokens obtained through
+the login endpoint. The `UserPermissionVoter` evaluates `#[IsGranted]` attributes against
+permissions stored in `users_permission_definitions`.
+
+## Tagged Service Extensibility
+
+Most extension points follow the same pattern: implement an interface, tag the service,
+and the bundle auto-discovers it at runtime. Key service tags:
+
+| Tag | Purpose |
+|-----|---------|
+| `pimcore.studio_backend.update_adapter` | Element update pipeline |
+| `pimcore.studio_backend.patch_adapter` | Bulk patch pipeline |
+| `pimcore.studio_backend.data_adapter` | Data object field save/load |
+| `pimcore.studio_backend.grid_column_definition` | Grid column type registration |
+| `pimcore.studio_backend.grid_column_resolver` | Grid column value resolution |
+| `pimcore.studio_backend.grid_column_collector` | Grid column availability |
+| `pimcore.studio_backend.grid_transformer` | Grid data transformation |
+| `pimcore.studio_backend.search_index.filter` | Search index filters (OpenSearch/ES) |
+| `pimcore.studio_backend.listing.filter` | Listing filters (classic Pimcore listings) |
+| `pimcore.studio_backend.field_definition_resolver` | Field definition resolution (dot notation) |
+| `pimcore.studio_backend.widget_repository` | Perspective widget config storage |
+| `pimcore.studio_backend.widget_hydrator` | Perspective widget config hydration |
+| `pimcore.studio_backend.gdpr_data_provider` | GDPR data extraction |
+| `pimcore.studio_backend.settings_provider` | Settings panel data |
+| `pimcore.studio_backend.filter_service` | Filter service registration |
+
+Most tags have dedicated guides in [Extending](../03_Extending/README.md). Tags without
+a dedicated guide (`settings_provider`, `filter_service`) follow the same pattern:
+implement the interface and register with the tag.
+
+## Real-Time Updates
+
+The bundle integrates [Mercure](https://mercure.rocks/) to deliver real-time updates to
+connected Pimcore Studio clients via Server-Sent Events (SSE). When elements are created,
+modified, or deleted, the backend publishes updates that connected clients receive instantly
+without polling. See [Mercure Setup](../02_Installation_and_Configuration/01_Mercure_Setup.md)
+for configuration details.
+
+## Core Subsystems
+
+### Grid System
+
+The Grid system provides configurable columns, filters, and data transformers for listing
+and searching assets, data objects, and documents. It is composed of three main components:
+column definitions (what columns exist), column resolvers (how values are fetched), and
+column collectors (which columns are available in a given context).
+
+- [Grid Architecture](./01_Grid.md)
+
+### Generic Execution Engine
+
+The Generic Execution Engine handles long-running and background tasks such as bulk operations,
+CSV/XLSX exports, ZIP uploads/downloads, and element cloning. It provides a unified interface
+for scheduling, tracking progress, and reporting results.
+
+- [Generic Execution Engine](./02_Generic_Execution_Engine.md)
+
+### MCP Server Infrastructure (Experimental)
+
+The bundle provides shared infrastructure for
+[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers. This includes a
+dedicated `pimcore_mcp` firewall (separate from the Studio API firewall), a dual authentication
+chain (session bridge for internal agent-server use, personal access tokens for external MCP
+clients like Claude Desktop or Cursor), and pre-registered PSR-7/PSR-17 bridge services.
+Bundles that implement MCP servers route their controllers under `/pimcore-mcp/` and get
+authentication handled automatically.
+
+- [MCP Server Infrastructure](../04_Development_Details/08_MCP_Server.md)

doc/02_Mercure_Setup.md …on_and_Configuration/01_Mercure_Setup.mddoc/02_Mercure_Setup.md renamed to doc/02_Installation_and_Configuration/01_Mercure_Setup.md doc/02_Mercure_Setup.md renamed to doc/02_Installation_and_Configuration/01_Mercure_Setup.md

@@ -1,3 +1,8 @@
+---
+title: Mercure Setup
+description: Configure Mercure for real-time updates in Pimcore Studio.
+---
+
 # Mercure Setup
 
 ## Start and configure Mercure server
@@ -142,10 +147,10 @@ routed correctly to the Mercure instance.
 Also, keep in mind, that communication needs to be HTTPS. Thus, it might be useful to place the Mercure server behind a reverse
 proxy of the actual webserver (who handles the certificates).
 
-Beware that the development ui is not working when using a reverse proxy. (See open ticket https://github.com/dunglas/mercure/issues/951)
+Beware that the development UI is not working when using a reverse proxy. (See open ticket https://github.com/dunglas/mercure/issues/951)
 
 #### Apache Reverse Proxy
-For apache for example enable `http_proxy` in apache and add the following reverse proxy in your apache config:
+For Apache, for example, enable `http_proxy` in apache and add the following reverse proxy in your apache config:
 ```
    ProxyPass /hub/ http://localhost:3000/
    ProxyPassReverse /hub/ http://localhost:3000/
@@ -160,7 +165,7 @@ For Nginx use following configuration:
 ```
 
 ### Development UI
-The development ui can be helpful to develop new features. It is possible to subscribe and publish messages.
+The development UI can be helpful to develop new features. It is possible to subscribe and publish messages.
 
 With the configuration below, the development ui is available at `http://localhost:8080/.well-known/mercure/ui/`.
 

doc/07_User.md …tion_and_Configuration/02_Studio_User.mddoc/07_User.md renamed to doc/02_Installation_and_Configuration/02_Studio_User.md doc/07_User.md renamed to doc/02_Installation_and_Configuration/02_Studio_User.md

@@ -1,3 +1,8 @@
+---
+title: Studio User
+description: Default key bindings and user configuration for Pimcore Studio.
+---
+
 # Studio User
 ## Default Key Bindings
 To change the default key bindings, you can add a Symfony configuration file in your project. 

doc/10_Extending_Studio/07_Notes.md …_Configuration/03_Defining_Note_Types.mddoc/10_Extending_Studio/07_Notes.md renamed to doc/02_Installation_and_Configuration/03_Defining_Note_Types.md doc/10_Extending_Studio/07_Notes.md renamed to doc/02_Installation_and_Configuration/03_Defining_Note_Types.md

@@ -1,4 +1,9 @@
-# Extending Notes
+---
+title: Defining Note Types
+description: Add custom note types for assets, documents, and data objects.
+---
+
+# Defining Note Types
 
 Notes to log changes or events on elements independently of the versioning. You can get more general information about notes [here](https://pimcore.com/docs/platform/Pimcore/Tools_and_Features/Notes_and_Events/)