docs: enhance cookbook recipes with verification steps and templates

This commit refines the project documentation by adding result verification steps to all recipes in the cookbook and formalizing documentation standards in the project guidelines.

Changes:
- docs/howtos/cookbook.md:
  - Added 'Verify' steps to all recipes using GraphQL queries or agent checks.
  - Enhanced 'Extending Schema with a New Device Type' recipe:
    - Updated Step 1 with a realistic schema using 'DistanceTrackerDevice' implementing 'Host' and 'Device' interfaces.
    - Added mandatory advice for new device types to implement 'Host' and 'Device'.
    - Referenced the existing 'location_tracker_devices.graphql' as a prepared real-world sample.
    - Split Step 3 into Method A (Manual Creation) and Method B (Automated Import).
    - Expanded Step 4 with a host creation step (using importHosts) and a filtered allDevices query using tag_deviceType.
  - Standardized icons for preparation (🛠️), configuration (⚙️), execution (🚀), and verification (✅).
- .junie/guidelines.md:
  - Added 'Documentation Templates' section defining a formal Recipe Template.
  - Standardized icons and step naming to maintain visual consistency across all guides.
  - Added 'Review & Approval' rule to prevent automatic commits without user review.
- readme.improvement.plan.md:
  - Added and completed 'Priority 7: Standardization & Verification' tasks.
  - Updated implementation order to reflect the new standardization phase.

.junie/guidelines.md

@@ -53,6 +53,45 @@ The [Roadmap](../roadmap.md) is to be considered as outlook giving constraints o
     - *Format*: Use plain text for general descriptions that follow a primary list item.
 - **Formatting**: Avoid extra blank lines between headers and list items.
 
+## Documentation Templates
+
+### Cookbook & Recipes
+Follow this template for all cookbook entries to ensure consistency and AI-parsability.
+
+#### Recipe Template
+```markdown
+## 🍳 Recipe: [Action-Oriented Title]
+
+[Brief description of what this recipe achieves.]
+
+### 📋 Prerequisites
+- [Constraint 1]
+- [Constraint 2]
+
+### 🛠️ Step 1: [Preparation/Definition]
+[Instructions for preparing data or environment.]
+
+### ⚙️ Step 2: [Configuration/Settings]
+[Instructions for configuring settings or environment variables.]
+
+### 🚀 Step 3: [Execution/Action]
+[The main GraphQL operation or command to execute.]
+
+### ✅ Step 4: [Verification]
+[How to verify that the operation was successful using a query or agent check.]
+```
+
+#### Standard Icons for Steps
+- 🍳 **Recipe**: Main header icon.
+- 📋 **Prerequisites**: Necessary conditions before starting.
+- 🛠️ **Preparation**: Initial setup, data definition, or file creation.
+- ⚙️ **Configuration**: Changes to settings, `.env`, or Zabbix UI.
+- 🚀 **Execution**: The primary action or mutation.
+- ✅ **Verification**: Result checking and outcome validation.
+- 💡 **Tip/Alternative**: Helpful hints or alternative methods.
+- 🤖 **AI/MCP**: Agent-specific instructions.
+
 ### Git Standards
 - **Commit Messages:** Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g. `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `style:`).
     - If a commit is complex and covers different aspects, the message **must** always contain a detailed list of what was changed within the optional "body" section, in addition to the short "description" in the header.
+- **Review & Approval**: Never commit changes automatically. Always present the proposed changes and the updated plan to the user for review. Allow the user to provide feedback or add tasks to the plan before proceeding with a commit.

docs/howtos/cookbook.md

@@ -14,25 +14,46 @@ To generate a test case from a recipe:
 
 ## 🍳 Recipe: Extending Schema with a New Device Type
 
-This recipe shows how to add support for a new specialized device type without modifying the core API code.
+This recipe shows how to add support for a new specialized device type without modifying the core API code. We will use the `DistanceTrackerDevice` as an example.
 
 ### 📋 Prerequisites
 - Zabbix Template Group `Templates/Roadwork/Devices` exists.
 - Zabbix GraphQL API is running.
 
 ### 🛠️ Step 1: Define the Schema Extension
-Create a new `.graphql` file in `schema/extensions/` (e.g. `distance_tracker.graphql`):
+Create a new `.graphql` file in `schema/extensions/` (e.g. `distance_tracker.graphql`). 
+
+> **Advice**: A new device type must always implement both the `Host` and `Device` interfaces to ensure compatibility with the API's core logic and resolvers.
+
 ```graphql
-type DistanceTrackerDevice {
+type DistanceTrackerDevice implements Host & Device {
-  id: String
+  # Mandatory Host & Device fields
+  hostid: ID!
+  host: String!
+  deviceType: String
+  hostgroups: [HostGroup!]
   name: String
-  location: Location
+  tags: DeviceConfig
-  distance: Float
+  
-  batteryLevel: Float
+  # Specialized state for this device
-  lastSeen: DateTime
+  state: DistanceTrackerState
+}
+
+type DistanceTrackerState implements DeviceState {
+  operational: OperationalDeviceData
+  current: DistanceTrackerValues
+}
+
+type DistanceTrackerValues {
+  timeFrom: Time
+  timeUntil: Time
+  count: Int
+  distances: [SensorDistanceValue!]
 }
 ```
 
+> **Reference**: This example is based on the already prepared sample: [location_tracker_devices.graphql](../../schema/extensions/location_tracker_devices.graphql).
+
 ### ⚙️ Step 2: Configure Environment Variables
 Add the new schema and resolver to your `.env` file:
 ```env
@@ -41,8 +62,67 @@ ADDITIONAL_RESOLVERS=DistanceTrackerDevice
 ```
 Restart the API server.
 
-### 🚀 Step 3: Import the Template
+### 🚀 Step 3: Execution/Action (Choose Method)
-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`).
+
+#### Method A: Manual Creation in Zabbix
+If you prefer to configure Zabbix manually:
+1.  **Create Template**: Create a template named `Distance Tracker Device`.
+2.  **Create Items**: Add items with keys that match the GraphQL fields:
+    *   `state.current.timeFrom`
+    *   `state.current.timeUntil`
+    *   `state.current.count`
+    *   `state.current.json_distances` (maps to `distances` array)
+3.  **Add Tag**: Add a host tag to the template with name `deviceType` and value `DistanceTrackerDevice`.
+
+#### Method B: Automated Import
+Execute the `importTemplates` mutation to create the template and items automatically. 
+> **Reference**: Use the [Sample: Distance Tracker Import](../../docs/queries/sample_import_distance_tracker_template.graphql) for a complete mutation and variables example.
+
+### ✅ Step 4: Verify the Extension
+Verify that the new type is available and correctly mapped by creating a test host and querying it.
+
+#### 1. Create a Test Host
+Use the `importHosts` mutation to create a host and explicitly set its `deviceType` to `DistanceTrackerDevice`.
+```graphql
+mutation CreateTestDistanceTracker($host: String!, $groupNames: [String!]!) {
+  importHosts(hosts: [{
+    deviceKey: $host,
+    deviceType: "DistanceTrackerDevice",
+    groupNames: $groupNames
+  }]) {
+    hostid
+    message
+  }
+}
+```
+
+#### 2. Query the Device
+Query the newly created device. Use the `tag_deviceType: ["DistanceTrackerDevice"]` argument to ensure you only retrieve devices of this specific type and prevent showing all devices.
+```graphql
+query VerifyNewDeviceType {
+  # 1. Check if the type exists in the schema
+  __type(name: "DistanceTrackerDevice") {
+    name
+    fields {
+      name
+    }
+  }
+  # 2. Query the specific device
+  allDevices(tag_deviceType: ["DistanceTrackerDevice"]) {
+    ... on DistanceTrackerDevice {
+      name
+      state {
+        current {
+          count
+          distances {
+            distance
+          }
+        }
+      }
+    }
+  }
+}
+```
 
 > **Reference**: See how items map to fields in the [Zabbix to GraphQL Mapping](../../README.md#zabbix-to-graphql-mapping).
 
@@ -71,6 +151,20 @@ mutation CreateNewHost($host: String!, $groups: [Int!]!, $templates: [Int!]!) {
 }
 ```
 
+### ✅ Step 3: Verify Host Creation
+Check if the host is correctly provisioned and linked to groups:
+```graphql
+query VerifyHost($host: String!) {
+  allHosts(filter_host: $host) {
+    hostid
+    host
+    hostgroups {
+      name
+    }
+  }
+}
+```
+
 ---
 
 ## 🍳 Recipe: Managing User Permissions
@@ -81,7 +175,8 @@ Create a template group with the prefix `Permissions/` in Zabbix (e.g. `Permissi
 ### ⚙️ Step 2: Assign to User Group
 In Zabbix, give a User Group `Read` access to this template group.
 
-### 🚀 Step 3: Verify via API
+### ✅ Step 3: Verify via API
+Verify that the current user has the expected permissions:
 ```graphql
 query CheckMyPermissions {
   hasPermissions(permissions: [
@@ -120,6 +215,22 @@ mutation BulkProvisioning($templates: [CreateTemplate!]!, $hosts: [CreateHost!]!
 }
 ```
 
+### ✅ Step 4: Verify Bulk Import
+Verify that all entities were created and linked correctly:
+```graphql
+query VerifyBulkImport($pattern: String!) {
+  allHosts(name_pattern: $pattern) {
+    hostid
+    host
+    ... on ZabbixHost {
+      parentTemplates {
+        name
+      }
+    }
+  }
+}
+```
+
 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).
 
 ---
@@ -132,7 +243,10 @@ This recipe guides you through setting up the Model Context Protocol (MCP) serve
 - **Zabbix GraphQL API**: Ensure the API is running (e.g. `npm run start`).
 - **Docker**: Installed and running for the MCP server container.
 
-### 🛠️ Setup A: JetBrains IDE (AI Chat & Junie)
+### 🛠️ Step 1: Configure the MCP Server
+Choose one of the following setups:
+
+#### Setup A: JetBrains IDE (AI Chat & Junie)
 Configure the IDE to use the GraphQL MCP server for both the built-in AI Chat and the **Junie agent**.
 - **Prerequisite**: Generate the combined schema file (run this in your project root):
   ```bash
@@ -148,9 +262,8 @@ Configure the IDE to use the GraphQL MCP server for both the built-in AI Chat an
     ```text
     run -i --rm -v ${PROJECT_DIR}/mcp-config.yaml:/mcp-config.yaml -v ${PROJECT_DIR}/schema.graphql:/mcp-data/schema.graphql:ro -v ${PROJECT_DIR}/mcp/operations:/mcp/operations -e APOLLO_GRAPH_REF=local@main ghcr.io/apollographql/apollo-mcp-server:latest /mcp-config.yaml
     ```
-- **Verify**: Ask the AI Chat or Junie: "Use MCP to list the configured Zabbix hosts".
 
-### 🛠️ Setup B: Claude Desktop
+#### Setup B: Claude Desktop
 Connect Claude Desktop to the Zabbix GraphQL API by referring to the [Apollo GraphQL MCP Documentation](https://github.com/apollographql/apollo-mcp-server).
 - **Prerequisite**: Generate the combined schema file (run this in your project root):
   ```bash
@@ -180,6 +293,15 @@ Connect Claude Desktop to the Zabbix GraphQL API by referring to the [Apollo Gra
   ```
 - **Restart Claude**: Fully restart the Claude Desktop application to apply the changes.
 
+### 🚀 Step 2: Use an AI Agent
+Provide the recipe to your AI agent and ask it to perform a task.
+- **Example**: "Use MCP to list the configured Zabbix hosts".
+
+### ✅ Step 3: Verify via Agent
+Confirm that the agent can successfully interact with the API:
+- Ask: "What is the current version of the Zabbix API?"
+- The agent should use the `apiVersion` query and respond with the version number.
+
 ### 💡 Alternative: Using Pre-running MCP Server
 If you already have the MCP server running locally (e.g. via `docker-compose.yml`), you can use a simpler configuration.
 - **Sample Configuration**: See [.ai/mcp/mcp.json](../../.ai/mcp/mcp.json) for a sample that connects to a running MCP server via HTTP.

readme.improvement.plan.md

@@ -71,6 +71,17 @@ This plan outlines the steps to refactor and improve the Zabbix GraphQL API docu
 - [x] Add explicit "See also" or "Related Recipes" links in reference sections.
 - [x] Link from recipes back to technical reference material for deep-dives.
 
+## Priority 7: Standardization & Verification (New)
+
+### 7.1 Cookbook Verification Steps
+- [x] Add a result verification step to each recipe in `cookbook.md`.
+- [x] Ensure verification steps use GraphQL queries or agent checks where appropriate.
+- [x] Refine 'Extending Schema' recipe with detailed manual/automated steps and comprehensive verification (Priority 7 enhancement).
+
+### 7.2 Recipe Templating
+- [x] Define a standard template for recipes in `.junie/guidelines.md`.
+- [x] Standardize icons and step naming (🛠️, ⚙️, 🚀, ✅).
+
 ## Implementation Order
 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.
@@ -79,6 +90,7 @@ This plan outlines the steps to refactor and improve the Zabbix GraphQL API docu
 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.
+8. [x] **Standardize**: Add verification steps and formalize the recipe template (Priority 7).
 
 ## Success Metrics
 - All environment variables documented.
@@ -86,3 +98,5 @@ This plan outlines the steps to refactor and improve the Zabbix GraphQL API docu
 - Functional MCP-based test generation using cookbook instructions.
 - Accurate representation of features and compatibility.
 - Zero redundant tables or instructional blocks across the doc set.
+- All recipes include a verification step.
+- Guidelines contain a clear template for future recipes.