From 91a1523d717dc6822e26dec84ed2a8f9f4a4a14f Mon Sep 17 00:00:00 2001
From: Andreas Hilbig <andreas.hilbig@hilbigit.com>
Date: Fri, 30 Jan 2026 15:07:14 +0100
Subject: [PATCH] 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.
---
 .idea/workspace.xml        | 16 ++++++--
 README.md                  | 76 ++++++++++++++++++-----------------
 docs/howtos/README.md      | 11 +++--
 docs/howtos/cookbook.md    | 36 +++++++++++++++++
 docs/howtos/maintenance.md | 58 +++++++++++++++++++++++++++
 docs/howtos/schema.md      | 12 +-----
 docs/queries/README.md     | 28 +++++++++++++
 readme.improvement.plan.md | 82 +++++++++++++++++++++++---------------
 8 files changed, 231 insertions(+), 88 deletions(-)
 create mode 100644 docs/howtos/maintenance.md
 create mode 100644 docs/queries/README.md

diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index c153fa3..9f7d5a4 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -4,9 +4,9 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="d7a71994-2699-4ae4-9fd2-ee13b7f33d35" name="Changes" comment="chore: add MCP integration and refactor documentation into modular how-to guides  &#10;&#10;- Moved GraphQL query samples into a new `docs/queries` directory for better organization.   &#10;- Added new queries and mutations, including `createHost.graphql` and `GetApiVersion.graphql`.  &#10;- Introduced `mcp-config.yaml` and updated `docker-compose.yml` for MCP integration.   &#10;- Updated IntelliJ `.idea/workspace.xml` settings to reflect project changes.  &#10;- Added new how-to guides (`docs/howtos`) for permissions, tags, MCP integration, and schema usage.  &#10;- Enhanced tests by updating file paths and improving sample data locations.  &#10;- Refined permissions and host group structures in `zabbix-hostgroups.ts` and `resolvers.ts`.">
-      <change beforePath="$PROJECT_DIR$/.idea/runConfigurations/index_ts.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/runConfigurations/index_ts.xml" afterDir="false" />
+    <list default="true" id="d7a71994-2699-4ae4-9fd2-ee13b7f33d35" name="Changes" comment="docs: refactor documentation and upgrade to Node.js 24&#10;&#10;This commit upgrades the project to Node.js 24 (LTS) and performs a major refactoring of the documentation to support both advanced users and AI-based automation (MCP).&#10;&#10;Changes:&#10;- Environment &amp; CI/CD:&#10;  - Set Node.js version to &gt;=24 in package.json and .nvmrc.&#10;  - Updated Dockerfile to use Node 24 base image.&#10;  - Updated @types/node to ^24.10.9.&#10;- Documentation:&#10;  - Refactored README.md with comprehensive technical reference, configuration details, and Zabbix-to-GraphQL mapping.&#10;  - Created docs/howtos/cookbook.md with practical recipes for common tasks and AI test generation.&#10;  - Updated docs/howtos/mcp.md to emphasize GraphQL's advantages for AI agents and Model Context Protocol.&#10;  - Added readme.improvement.plan.md to track documentation evolution.&#10;  - Enhanced all how-to guides with improved cross-references and up-to-date information.&#10;- Guidelines:&#10;  - Updated .junie/guidelines.md with Node 24 requirements and enhanced commit message standards (Conventional Commits 1.0.0).&#10;- Infrastructure &amp; Code:&#10;  - Updated docker-compose.yml with Apollo MCP server integration.&#10;  - Refined configuration and schema handling in src/api/ and src/datasources/.&#10;  - Synchronized generated TypeScript types with schema updates.">
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -199,7 +199,7 @@
       <workItem from="1769256682556" duration="8928000" />
       <workItem from="1769699975260" duration="75000" />
       <workItem from="1769700092648" duration="5212000" />
-      <workItem from="1769724930397" duration="14118000" />
+      <workItem from="1769724930397" duration="16056000" />
     </task>
     <task id="LOCAL-00001" summary="chore: Update IntelliJ workspace settings and add GitHub Actions workflow for Docker deployment">
       <option name="closed" value="true" />
@@ -393,7 +393,15 @@
       <option name="project" value="LOCAL" />
       <updated>1769730441542</updated>
     </task>
-    <option name="localTasksCounter" value="25" />
+    <task id="LOCAL-00025" summary="docs: refactor documentation and upgrade to Node.js 24&#10;&#10;This commit upgrades the project to Node.js 24 (LTS) and performs a major refactoring of the documentation to support both advanced users and AI-based automation (MCP).&#10;&#10;Changes:&#10;- Environment &amp; CI/CD:&#10;  - Set Node.js version to &gt;=24 in package.json and .nvmrc.&#10;  - Updated Dockerfile to use Node 24 base image.&#10;  - Updated @types/node to ^24.10.9.&#10;- Documentation:&#10;  - Refactored README.md with comprehensive technical reference, configuration details, and Zabbix-to-GraphQL mapping.&#10;  - Created docs/howtos/cookbook.md with practical recipes for common tasks and AI test generation.&#10;  - Updated docs/howtos/mcp.md to emphasize GraphQL's advantages for AI agents and Model Context Protocol.&#10;  - Added readme.improvement.plan.md to track documentation evolution.&#10;  - Enhanced all how-to guides with improved cross-references and up-to-date information.&#10;- Guidelines:&#10;  - Updated .junie/guidelines.md with Node 24 requirements and enhanced commit message standards (Conventional Commits 1.0.0).&#10;- Infrastructure &amp; Code:&#10;  - Updated docker-compose.yml with Apollo MCP server integration.&#10;  - Refined configuration and schema handling in src/api/ and src/datasources/.&#10;  - Synchronized generated TypeScript types with schema updates.">
+      <option name="closed" value="true" />
+      <created>1769780136862</created>
+      <option name="number" value="00025" />
+      <option name="presentableId" value="LOCAL-00025" />
+      <option name="project" value="LOCAL" />
+      <updated>1769780136862</updated>
+    </task>
+    <option name="localTasksCounter" value="26" />
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
diff --git a/README.md b/README.md
index dd8a992..2e47315 100644
--- a/README.md
+++ b/README.md
@@ -31,25 +31,29 @@ The Zabbix GraphQL API acts as a wrapper and enhancer for the native Zabbix JSON
 
 ## How-To Guides
 
-For detailed information on specific topics, please refer to our how-to guides:
+For detailed information on specific topics and practical step-by-step instructions, please refer to our guides:
 
-*   [**Cookbook**](./docs/howtos/cookbook.md): Practical, step-by-step recipes for quick start and AI test generation.
+*   [**Cookbook**](./docs/howtos/cookbook.md): Practical, task-oriented recipes for quick start and AI test generation.
 *   [**Schema & Extension Overview**](./docs/howtos/schema.md): Detailed explanation of the schema structure and extension mechanism.
 *   [**Hierarchical Data Mapping**](./docs/howtos/hierarchical_data_mapping.md): How Zabbix items are mapped to nested GraphQL fields.
 *   [**Roles & Permissions**](./docs/howtos/permissions.md): Managing user rights through Zabbix template groups.
-*   [**Zabbix Tags Usage**](./docs/howtos/tags.md): Using tags for classification and metadata.
-*   [**MCP & Agent Integration**](./docs/howtos/mcp.md): Connecting LLMs and autonomous agents to Zabbix via Model Context Protocol.
+*   [**Technical Maintenance**](./docs/howtos/maintenance.md): Guide on code generation, testing, and Docker maintenance.
+*   [**MCP & Agent Integration**](./docs/howtos/mcp.md): Connecting LLMs and autonomous agents via Model Context Protocol.
 
 See the [How-To Overview](./docs/howtos/README.md) for a complete list of documentation.
 
 ## How to Install and Start
 
-### Prerequisites
+### 📋 Prerequisites
+Before you begin, ensure you have met the following requirements:
 
 *   **Node.js**: Version 24 (LTS) or higher recommended.
 *   **Zabbix**: A running Zabbix instance (compatible with Zabbix 6.0+).
+ with API access
+*   **Zabbix Super Admin Token** (for full functionality / privilege escalation)
+*   **Zabbix User Access** (groups and roles depending on your use case)
 
-### Installation
+### 🛠️ Installation
 
 1.  Clone the repository:
     ```bash
@@ -61,6 +65,21 @@ See the [How-To Overview](./docs/howtos/README.md) for a complete list of docume
     ```bash
     npm install
     ```
+### Starting the API
+
+#### Development Mode
+Starts the server with `nodemon` and `tsx` for automatic reloading:
+```bash
+npm run start
+```
+
+#### Production Mode
+Builds the project and runs the compiled code:
+```bash
+npm run prod
+```
+
+The API will be available at `http://localhost:4000/`.
 
 ## ⚙️ Configuration
 
@@ -93,6 +112,8 @@ In production environments, the `ZABBIX_DEVELOPMENT_TOKEN` should **always be un
 *   **Zabbix Frontend Widgets**: When accessing the API from widgets embedded in the Zabbix frontend, no static token is needed. Authentication is automatically derived from the `zbx_session` cookie provided by the Zabbix web login, which is forwarded to the Zabbix API.
 *   **Other Production Tools**: For other purposes (e.g. accessing the API from external tools or scripts), a Zabbix session or auth token must be passed via the `zabbix-auth-token` HTTP header.
 
+> **Recipe**: See [Managing User Permissions](./docs/howtos/cookbook.md#recipe-managing-user-permissions) for setup instructions.
+
 ### 2. Privilege Escalation
 
 *   **`ZABBIX_PRIVILEGE_ESCALATION_TOKEN`**: Certain operations, such as importing hosts, templates, or user rights, require Super Admin access to Zabbix for specific parts of the process. This token allows the API to perform these administrative tasks even when the initiating user does not have Super Admin rights themselves.
@@ -116,21 +137,8 @@ The API maps Zabbix entities to GraphQL types as follows:
 | Tag | `Tag` | Represents a Zabbix tag associated with a host or template |
 | Inventory | `Location` | Host inventory information maps to location data |
 
-### Starting the API
+> **Detailed Guide**: For a deeper dive into how Zabbix items are transformed into GraphQL fields, see [Hierarchical Data Mapping](./docs/howtos/hierarchical_data_mapping.md).
 
-#### Development Mode
-Starts the server with `nodemon` and `tsx` for automatic reloading:
-```bash
-npm run start
-```
-
-#### Production Mode
-Builds the project and runs the compiled code:
-```bash
-npm run prod
-```
-
-The API will be available at `http://localhost:4000/`.
 
 ## Running with Docker
 
@@ -212,23 +220,9 @@ ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice
 
 ## Usage Samples
 
-The `docs/queries` directory contains several sample GraphQL queries and mutations to help you get started:
+The `docs/queries` directory contains several sample GraphQL queries and mutations to help you get started.
 
-*   **Hosts**:
-    *   [Query All Hosts](docs/queries/sample_all_hosts_query.graphql)
-    *   [Import Hosts](docs/queries/sample_import_hosts_mutation.graphql)
-*   **Templates**:
-    *   [Query Templates](docs/queries/sample_templates_query.graphql)
-    *   [Import Templates](docs/queries/sample_import_templates_mutation.graphql)
-    *   [Import Distance Tracker Template](docs/queries/sample_import_distance_tracker_template.graphql) (Schema Extension Example)
-    *   [Delete Templates](docs/queries/sample_delete_templates_mutation.graphql)
-*   **Template Groups**:
-    *   [Import Host Template Groups](docs/queries/sample_import_host_template_groups_mutation.graphql)
-    *   [Import Permissions Template Groups](docs/queries/sample_import_permissions_template_groups_mutation.graphql)
-    *   [Delete Template Groups](docs/queries/sample_delete_template_groups_mutation.graphql)
-*   **User Rights**:
-    *   [Export User Rights](docs/queries/sample_export_user_rights_query.graphql)
-    *   [Import User Rights](docs/queries/sample_import_user_rights_mutation.graphql)
+> **Samples Reference**: See the [Sample Queries & Mutations Overview](./docs/queries/README.md) for a categorized list of examples.
 
 ## 🔄 API Version
 
@@ -238,6 +232,16 @@ The API version is automatically set during the Docker build process based on th
 
 This API is designed to work with Zabbix 7.4, which is the version it runs productively with. While it may work with earlier versions (like 6.0+), 7.4 is the officially supported and tested version.
 
+## 🛠️ Technical Maintenance
+
+For information on code generation, running tests, and managing the project's development lifecycle, please refer to the [Technical Maintenance Guide](./docs/howtos/maintenance.md).
+
+## 🔗 External Resources
+
+- **Zabbix API Documentation**: [https://www.zabbix.com/documentation/7.0/en/manual/api](https://www.zabbix.com/documentation/7.0/en/manual/api)
+- **Apollo Server Documentation**: [https://www.apollographql.com/docs/apollo-server/](https://www.apollographql.com/docs/apollo-server/)
+- **Model Context Protocol (MCP)**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)
+
 ## License
 
 This project is licensed under the **GNU Affero General Public License v3.0**. See the [LICENSE](LICENSE) file for details.
diff --git a/docs/howtos/README.md b/docs/howtos/README.md
index 2a50708..c67e860 100644
--- a/docs/howtos/README.md
+++ b/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.
diff --git a/docs/howtos/cookbook.md b/docs/howtos/cookbook.md
index e50bc93..c807958 100644
--- a/docs/howtos/cookbook.md
+++ b/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).
diff --git a/docs/howtos/maintenance.md b/docs/howtos/maintenance.md
new file mode 100644
index 0000000..5dcbfd3
--- /dev/null
+++ b/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)
diff --git a/docs/howtos/schema.md b/docs/howtos/schema.md
index 838eb97..c121a4d 100644
--- a/docs/howtos/schema.md
+++ b/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
 
diff --git a/docs/queries/README.md b/docs/queries/README.md
new file mode 100644
index 0000000..e08de52
--- /dev/null
+++ b/docs/queries/README.md
@@ -0,0 +1,28 @@
+# Sample Queries & Mutations
+
+This directory contains practical examples of GraphQL operations for the Zabbix GraphQL API. You can use these as templates for your own automation or integration tasks.
+
+## 📁 Available Samples
+
+### 🖥️ Hosts
+- [Query All Hosts](./sample_all_hosts_query.graphql): Retrieve basic host information and inventory.
+- [Import Hosts](./sample_import_hosts_mutation.graphql): Create or update multiple hosts with tags and group assignments.
+- [Query All Devices](./sample_all_devices_query.graphql): Query specialized devices using the `allDevices` query.
+
+### 📄 Templates
+- [Query Templates](./sample_templates_query.graphql): List available templates and their items.
+- [Import Templates](./sample_import_templates_mutation.graphql): Create or update complex templates with item definitions and preprocessing.
+- [Import Distance Tracker Template](./sample_import_distance_tracker_template.graphql): Example of importing a template for a schema extension.
+- [Delete Templates](./sample_delete_templates_mutation.graphql): Remove templates by ID or name pattern.
+
+### 📂 Template Groups
+- [Import Host Template Groups](./sample_import_host_template_groups_mutation.graphql): Create groups specifically for host templates.
+- [Import Permissions Template Groups](./sample_import_permissions_template_groups_mutation.graphql): Create groups for the permission system.
+- [Delete Template Groups](./sample_delete_template_groups_mutation.graphql): Remove template groups by ID or name pattern.
+
+### 🔐 User Rights
+- [Export User Rights](./sample_export_user_rights_query.graphql): Export existing user roles and groups for auditing or migration.
+- [Import User Rights](./sample_import_user_rights_mutation.graphql): Provision user roles and group permissions at scale.
+
+## 🍳 Related Recipes
+For step-by-step guides on how to use these operations in common scenarios, see the [Cookbook](../howtos/cookbook.md).
diff --git a/readme.improvement.plan.md b/readme.improvement.plan.md
index c552fc9..ec3cba6 100644
--- a/readme.improvement.plan.md
+++ b/readme.improvement.plan.md
@@ -5,68 +5,84 @@ This plan outlines the steps to refactor and improve the Zabbix GraphQL API docu
 ## Priority 1: Reference Documentation (Advanced Users)
 
 ### 1.1 Enhance README.md
-- **Feature-to-Code Mapping**: Add "Reference" links to each feature in the features list (from public origin).
-- **Comprehensive Config Reference**: Update environment variables table with detailed descriptions, defaults, and requirements.
-- **Auth Separation**: Explain `ZABBIX_PRIVILEGE_ESCALATION_TOKEN` vs `ZABBIX_DEVELOPMENT_TOKEN`.
-- **Entity Mapping Table**: Include the Zabbix-to-GraphQL entity mapping table.
-- **API Versioning**: Document how the version is determined and Zabbix version compatibility (7.4 focus).
+- [x] **Feature-to-Code Mapping**: Add "Reference" links to each feature in the features list (from public origin).
+- [x] **Comprehensive Config Reference**: Update environment variables table with detailed descriptions, defaults, and requirements.
+- [x] **Auth Separation**: Explain `ZABBIX_PRIVILEGE_ESCALATION_TOKEN` vs `ZABBIX_DEVELOPMENT_TOKEN`.
+- [x] **Entity Mapping Table**: Include the Zabbix-to-GraphQL entity mapping table.
+- [x] **API Versioning**: Document how the version is determined and Zabbix version compatibility (7.4 focus).
 
 ### 1.2 Update Detailed Guides
-- Ensure `docs/howtos/schema.md`, `permissions.md`, etc., are up-to-date with the latest implementation details.
+- [x] Ensure `docs/howtos/schema.md`, `permissions.md`, etc., are up-to-date with the latest implementation details.
 
 ## Priority 2: Cookbook & AI-Ready Instructions
 
 ### 2.1 Create the Cookbook (`docs/howtos/cookbook.md`)
-- **Step-by-Step Recipes**: Create practical, task-oriented guides.
-- **Recipe: Schema Extension**: Move the "Distance Tracker" example into the cookbook.
-- **Recipe: Basic Monitoring**: Step-by-step to monitor a new host.
-- **Recipe: Bulk Import**: Guide for mass importing templates and hosts.
+- [x] **Step-by-Step Recipes**: Create practical, task-oriented guides.
+- [x] **Recipe: Schema Extension**: Move the "Distance Tracker" example into the cookbook.
+- [x] **Recipe: Basic Monitoring**: Step-by-step to monitor a new host.
+- [x] **Recipe: Bulk Import**: Guide for mass importing templates and hosts.
 
 ### 2.2 AI/MCP Integration for Test Generation
-- **MCP Server Documentation**: Explicitly document how to start and use the `zabbix-graphql` MCP server.
-- **Test Generation Instructions**: Provide specific instructions on how an AI can use the Cookbook recipes to generate test cases.
-- **Metadata for AI**: Use structured headers and clear prerequisites in recipes to make them "AI-parsable".
+- [x] **MCP Server Documentation**: Explicitly document how to start and use the `zabbix-graphql` MCP server.
+- [x] **Test Generation Instructions**: Provide specific instructions on how an AI can use the Cookbook recipes to generate test cases.
+- [x] **Metadata for AI**: Use structured headers and clear prerequisites in recipes to make them "AI-parsable".
 
 ## Priority 3: Technical Maintenance (from Public Origin)
 
 ### 3.1 Code Generation Section
-- Explain the GraphQL Codegen setup and how to regenerate types.
-- Document the `codegen.ts` configuration.
-- Add instructions for updating generated types after schema changes.
+- [x] Explain the GraphQL Codegen setup and how to regenerate types.
+- [x] Document the `codegen.ts` configuration.
+- [x] Add instructions for updating generated types after schema changes.
 
 ## Priority 4: Improve Examples
 
 ### 4.1 Complete Examples
-- Add more complete examples for each major operation.
-- Include error handling examples.
-- Add examples for common use cases beyond the distance tracker.
+- [x] Add more complete examples for each major operation.
+- [x] Include error handling examples.
+- [x] Add examples for common use cases beyond the distance tracker.
 
 ### 4.2 Testing Examples
-- Add information about how to run tests.
-- Include examples of unit and integration tests.
-- Explain the test structure and how to add new tests.
+- [x] Add information about how to run tests.
+- [x] Include examples of unit and integration tests.
+- [x] Explain the test structure and how to add new tests.
 
 ## Priority 5: Documentation Links
 
 ### 5.1 Cross-Reference Improvements
-- Add links to relevant sections in schema files.
-- Include references to specific resolver implementations.
-- Link to related documentation files in the docs directory.
+- [x] Add links to relevant sections in schema files.
+- [x] Include references to specific resolver implementations.
+- [x] Link to related documentation files in the docs directory.
 
 ### 5.2 External Resources
-- Link to official Zabbix API documentation.
-- Include references to Apollo Server documentation.
+- [x] Link to official Zabbix API documentation.
+- [x] Include references to Apollo Server documentation.
+
+## Priority 6: Refine Structure & DRY (New)
+
+### 6.1 Separate Cookbook from Reference
+- [x] Move instructional "how-to" steps from README.md to `cookbook.md` or specific how-tos where they distract from reference info.
+- [x] Ensure `README.md` focuses on "What" (specification/reference) and `cookbook.md` focuses on "How" (recipes).
+
+### 6.2 Eliminate Redundancy (DRY)
+- [x] Identify and remove duplicate information between `README.md` and `docs/howtos/` (e.g., Zabbix to GraphQL Mapping).
+- [x] Centralize core definitions to a single source of truth and use links elsewhere.
+
+### 6.3 Enhance Cross-References
+- [x] Add explicit "See also" or "Related Recipes" links in reference sections.
+- [x] Link from recipes back to technical reference material for deep-dives.
 
 ## Implementation Order
-1. **Foundation**: Update `README.md` with missing reference information from public origin.
-2. **Cookbook Alpha**: Create `docs/howtos/cookbook.md` with the first set of recipes.
-3. **AI Bridge**: Document MCP server usage and test generation workflow.
-4. **Maintenance**: Add Codegen and Testing sections.
-5. **Cross-Linking**: Optimize all links and cross-references.
-6. **Optimize**: Run import optimization across the project.
+1. [x] **Foundation**: Update `README.md` with missing reference information from public origin.
+2. [x] **Cookbook Alpha**: Create `docs/howtos/cookbook.md` with the first set of recipes.
+3. [x] **AI Bridge**: Document MCP server usage and test generation workflow.
+4. [x] **Maintenance**: Add Codegen and Testing sections.
+5. [x] **Cross-Linking**: Optimize all links and cross-references.
+6. [x] **Optimize**: Run import optimization across the project.
+7. [x] **Refine & DRY**: Execute Priority 6 tasks to further clean up and structure documentation.
 
 ## Success Metrics
 - All environment variables documented.
 - Clear distinction between Reference and Cookbook.
 - Functional MCP-based test generation using cookbook instructions.
 - Accurate representation of features and compatibility.
+- Zero redundant tables or instructional blocks across the doc set.