docs: complete documentation refactoring and structure optimization

This commit finalizes the documentation improvement plan by:
- Centralizing reference material in README.md.
- Creating a dedicated Technical Maintenance guide (docs/howtos/maintenance.md).
- Creating a categorized Sample Queries & Mutations overview (docs/queries/README.md).
- Eliminating redundant information across the doc set (DRY principle).
- Optimizing cross-references between reference documentation and the Cookbook.
- Updating the improvement plan to reflect all tasks as completed.

docs/howtos/README.md

@@ -16,12 +16,15 @@ Understand how the API automatically maps flat Zabbix item keys into nested Grap
 ### 🔐 [Roles and Permissions Extension](./permissions.md)
 Discover how the permission system works, how to define permission levels using Zabbix template groups, and how to query user permissions.
 
-### 🏷️ [Zabbix Tags Usage](./tags.md)
-Learn how Zabbix tags are used for device classification, host categorization, and as metadata within the GraphQL API.
+### 🛠️ [Technical Maintenance](./maintenance.md)
+Guide on code generation (GraphQL Codegen), running Jest tests, and local Docker builds.
 
 ### 🤖 [MCP & Agent Integration](./mcp.md)
-Discover how to integrate the Zabbix GraphQL API with the Model Context Protocol (MCP) to enable LLMs and autonomous agents to interact with your Zabbix data efficiently.
+Discover how to integrate with the Model Context Protocol (MCP) to enable LLMs and autonomous agents to interact with Zabbix efficiently.
 
 ---
 
-For practical examples of GraphQL operations, check the [Sample Queries](../queries/) directory.
+## 🔍 Additional Resources
+
+- **[Sample Queries](../queries/README.md)**: Categorized list of practical GraphQL operation examples.
+- **[Main README](../../README.md)**: Technical reference, configuration, and environment setup.

docs/howtos/cookbook.md

@@ -44,6 +44,8 @@ Restart the API server.
 ### Step 3: Import the Template
 Execute the `importTemplates` mutation to create the template in Zabbix. Use Zabbix item keys that match your GraphQL fields (e.g. `distance.current` for `distance`).
 
+> **Reference**: See how items map to fields in the [Zabbix to GraphQL Mapping](../../README.md#zabbix-to-graphql-mapping).
+
 ---
 
 ## 🍳 Recipe: Provisioning a New Host
@@ -56,6 +58,8 @@ Execute the `importTemplates` mutation to create the template in Zabbix. Use Zab
 Define the host name, groups, and templates to link.
 
 ### Step 2: Execute `createHost` Mutation
+For more details on the input fields, see the [Reference: createHost](../../schema/mutations.graphql).
+
 ```graphql
 mutation CreateNewHost($host: String!, $groups: [Int!]!, $templates: [Int!]!) {
   createHost(host: $host, hostgroupids: $groups, templateids: $templates) {
@@ -85,3 +89,35 @@ query CheckMyPermissions {
   ])
 }
 ```
+
+---
+
+## 🍳 Recipe: Bulk Import of Templates and Hosts
+
+This recipe guides you through performing a mass import of multiple templates and hosts in a single operation.
+
+### Step 1: Prepare Template Import
+Use the `importTemplates` mutation. You can provide multiple template definitions in the `templates` array.
+
+### Step 2: Prepare Host Import
+Use the `importHosts` mutation. Link them to the newly imported templates using their names or IDs.
+
+### Step 3: Combined Operation (Optional)
+You can execute both mutations in a single GraphQL request to ensure atomic-like provisioning of your infrastructure.
+
+```graphql
+mutation BulkProvisioning($templates: [CreateTemplate!]!, $hosts: [CreateHost!]!) {
+  importTemplates(templates: $templates) {
+    templateid
+    host
+    message
+  }
+  importHosts(hosts: $hosts) {
+    hostid
+    deviceKey
+    message
+  }
+}
+```
+
+For detailed examples of the input structures, refer to [Sample Import Templates](../../docs/queries/sample_import_templates_mutation.graphql) and [Sample Import Hosts](../../docs/queries/sample_import_hosts_mutation.graphql).

docs/howtos/maintenance.md

@@ -0,0 +1,58 @@
+# Technical Maintenance Guide
+
+This guide covers the technical aspects of maintaining and developing the Zabbix GraphQL API.
+
+## 🛠️ Development & Maintenance Tasks
+
+### Code Generation
+
+The project uses [GraphQL Codegen](https://the-guild.dev/graphql/codegen) to generate TypeScript types from the GraphQL schema. This ensures type safety and consistency between the schema and the implementation.
+
+- **Configuration**: `codegen.ts`
+- **Generated Output**: `src/schema/generated/graphql.ts`
+
+#### How to Regenerate Types
+Whenever you modify any `.graphql` files in the `schema/` directory, you must regenerate the TypeScript types:
+
+```bash
+npm run codegen
+```
+
+### Testing
+
+We use [Jest](https://jestjs.io/) for unit and integration testing.
+
+- **Test Directory**: `src/test/`
+- **Execution**:
+  ```bash
+  npm run test
+  ```
+
+#### Adding New Tests
+- **Location**: Place new test files in `src/test/` with the `.test.ts` extension.
+- **Coverage**: Ensure you cover both successful operations and error scenarios.
+- **Best Practice**: If you find a bug, first create a reproduction test in `src/test/` to verify the fix.
+
+## 🔄 Updating Dependencies
+
+To keep the project secure and up-to-date:
+
+1. Check for updates: `npm outdated`
+2. Update packages: `npm update`
+3. Verify with tests: `npm run test`
+
+## 🐳 Docker Image Maintenance
+
+The `Dockerfile` uses a multi-stage build to keep the production image small and secure.
+
+- **Base Image**: Node 24 (LTS)
+- **Build Argument**: `API_VERSION` (used to embed the version into the image)
+
+To build a fresh image locally:
+```bash
+docker build -t zabbix-graphql-api --build-arg API_VERSION=$(git describe --tags --always) .
+```
+
+---
+**Related Reference**: [Project Configuration Reference](../../README.md#configuration)
+**Related Cookbook**: [Extending the Schema](./cookbook.md#recipe-extending-schema-with-a-new-device-type)

docs/howtos/schema.md

@@ -16,17 +16,7 @@ For comprehensive understanding of each operation, read the detailed comments in
 
 ### Zabbix to GraphQL Mapping
 
-The API maps Zabbix entities to GraphQL types as follows:
-
-| Zabbix Entity | GraphQL Type | Description |
-|---------------|--------------|-------------|
-| Host | `Host` / `Device` | Represents a Zabbix host; `Device` is a specialized `Host` with a `deviceType` tag |
-| Host Group | `HostGroup` | Represents a Zabbix host group |
-| Template | `Template` | Represents a Zabbix template |
-| Template Group | `HostGroup` | Represents a Zabbix template group |
-| Item | Nested fields in `Device` | Zabbix items become nested fields in the device based on their key names |
-| Tag | `Tag` | Represents a Zabbix tag associated with a host or template |
-| Inventory | `Location` | Host inventory information maps to location data |
+For a detailed mapping of Zabbix entities to GraphQL types, please refer to the [Zabbix to GraphQL Mapping](../../README.md#zabbix-to-graphql-mapping) section in the main README.
 
 ### Zabbix Entity Relationships