docs: improve schema extensibility documentation and samples

- Added TSDoc for 'createHierarchicalValueFieldResolver'.

- Updated README with 'Extending the Schema' guide and Zabbix preconditions.

- Migrated all MQTT items to Agent 2 'mqtt.get' format across documentation and test data.

- Added 'docs/sample_import_distance_tracker_template.graphql' as a schema extension example.

- Verified all 38 tests pass.

(cherry picked from commit bff9ee6d2e)

README.md

@@ -23,6 +23,7 @@ Compared to the original Zabbix API, this GraphQL API provides several key enhan
     *   On-the-fly permission checks (`hasPermissions`, `userPermissions`).
 *   **Improved Error Reporting**: Detailed error data from Zabbix is appended to GraphQL error messages, making debugging significantly easier.
 *   **Strongly Typed Schema**: Leverages GraphQL's type system for clear API documentation and client-side code generation.
+*   **Dynamic Schema Extensibility**: Easily extend the API with custom schema snippets and dynamic resolvers for specialized device types without modifying the core code.
 
 ## How to Install and Start
 
@@ -71,6 +72,70 @@ npm run prod
 
 The API will be available at `http://localhost:4000/`.
 
+## Extending the Schema
+
+The Zabbix GraphQL API is designed to be highly extensible. You can add your own GraphQL schema snippets and have resolvers dynamically created for them.
+
+### Dynamic Resolvers with `createHierarchicalValueFieldResolver`
+
+The function `createHierarchicalValueFieldResolver` (found in `src/api/resolver_helpers.ts`) allows for the automatic creation of resolvers that map Zabbix items or tags to a hierarchical GraphQL structure. It uses field names and Zabbix item keys (dot-separated) to automatically resolve nested objects.
+
+### Zabbix Preconditions for Hierarchical Mapping
+
+In order for the dynamic resolvers to correctly map Zabbix data to your GraphQL schema, the following preconditions must be met in your Zabbix templates:
+
+*   **Key Naming**: Zabbix item keys (or tags) must match the GraphQL field names.
+*   **Dot Separation**: Use a dot (`.`) as a separator to represent nested object structures. For example, a Zabbix item with the key `state.current.values.temperature` will be automatically mapped to the `temperature` field within the nested structure: `state` -> `current` -> `values` -> `temperature`.
+*   **Type Hinting**: You can guide the type conversion by prepending a type hint and an underscore to the last token of the key:
+    *   `json_`: Parses the value as a JSON object (useful for complex types).
+    *   `str_`: Forces the value to be treated as a string.
+    *   `bool_`: Forces the value to be treated as a boolean.
+    *   `float_`: Forces the value to be treated as a number.
+
+For a complete example of a Zabbix template designed for schema extension, see the [Distance Tracker Import Sample](docs/sample_import_distance_tracker_template.graphql).
+
+### No-Code Extension via Environment Variables
+
+You can extend the schema and add resolvers without writing any TypeScript code by using the following environment variables:
+
+*   **`ADDITIONAL_SCHEMAS`**: A comma-separated list of paths to additional `.graphql` files.
+*   **`ADDITIONAL_RESOLVERS`**: A comma-separated list of GraphQL Type names for which dynamic hierarchical resolvers should be created.
+
+#### Example
+
+Suppose you have custom device definitions in `schema/extensions/`. You can load them and enable dynamic resolution by setting:
+
+```bash
+ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql,./schema/extensions/location_tracker_commons.graphql
+ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice
+```
+
+The API will:
+1. Load all provided schema files.
+2. For each type listed in `ADDITIONAL_RESOLVERS`, it will automatically create a resolver that maps Zabbix items (e.g., an item with key `state.current.values.temperature`) to the corresponding GraphQL fields.
+
+## Sample Environment File
+
+Below is a complete example of a `.env` file showing all available configuration options:
+
+```env
+# Zabbix Connection
+ZABBIX_BASE_URL=http://your-zabbix-instance/zabbix
+ZABBIX_AUTH_TOKEN=your-super-admin-token-here
+
+# General Configuration
+ZABBIX_EDGE_DEVICE_BASE_GROUP=Baustellen-Devices
+API_VERSION=1.0.0
+SCHEMA_PATH=./schema/
+
+# Schema Extensions (No-Code)
+ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql,./schema/extensions/location_tracker_commons.graphql
+ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice
+
+# Logging
+# LOG_LEVEL=debug
+```
+
 ## Usage Samples
 
 The `docs` directory contains several sample GraphQL queries and mutations to help you get started:
@@ -81,6 +146,7 @@ The `docs` directory contains several sample GraphQL queries and mutations to he
 *   **Templates**:
     *   [Query Templates](docs/sample_templates_query.graphql)
     *   [Import Templates](docs/sample_import_templates_mutation.graphql)
+    *   [Import Distance Tracker Template](docs/sample_import_distance_tracker_template.graphql) (Schema Extension Example)
     *   [Delete Templates](docs/sample_delete_templates_mutation.graphql)
 *   **Template Groups**:
     *   [Import Template Groups](docs/sample_import_template_groups_mutation.graphql)