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.

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.