docs: update titles for clarity and add beta feature warnings in blueprint documentation

Author: davidbquali

docs/blueprint-designer-guide/autogenerated-blueprints.md

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 5
-title: Auto-generated Blueprints
+title: Blueprints Auto-generation
 ---
 
 ## Torque auto-generated blueprints

docs/blueprint-designer-guide/blueprint-consumption-policies.md

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 16
-title: Blueprint Consumption Policies
+title: Blueprint Policies
 ---
 
 As the blueprint designer, you can define the blueprint's default and max duration configurations or allow it to run indefinitely, to support scenarios that deploy an environment that must be always online or delivers a static cloud resource.

docs/blueprint-designer-guide/blueprint-templates.md

@@ -0,0 +1,146 @@
+---
+sidebar_position: 5
+title: Blueprint Templates
+---
+
+A **blueprint template** is a reusable blueprint foundation you can standardize and reuse across teams. It lets you publish a blueprint skeleton with shared metadata, inputs, outputs, and grains, then adapt it for specific use cases.
+
+:::warning Beta Feature
+Blueprint Templates is currently in beta.
+Behavior and schema details may change as the feature evolves.
+:::
+
+To mark a blueprint as a template, add a `template` section with `placeholders`:
+
+```yaml
+template:
+  placeholders: []
+```
+
+## When to use templates
+
+Templates are useful when you want consistency and speed while still allowing teams to customize implementation details.
+
+Common examples:
+
+- **Standardized infrastructure starters** - provide a base VM, Kubernetes, or application deployment pattern that teams can reuse
+- **Organization guardrails** - enforce shared conventions (metadata labels, required inputs, common setup grains) in a single reusable blueprint definition
+
+## How templates work
+
+A template is a valid blueprint YAML file. It is authored and stored like any other blueprint, and includes the same blueprint sections (`spec_version`, `metadata`, `inputs`, `outputs`, `grains`, and so on).
+
+The difference is the `template` block:
+
+- `template.placeholders` indicates this blueprint is intended to be used as a template
+- placeholders can be used to keep explicit extension points in the blueprint structure
+
+This allows platform teams to maintain one reusable baseline while keeping room for per-template adaptations.
+
+## Template YAML structure
+
+```yaml
+spec_version: 2
+
+description: Reusable blueprint template
+
+template:
+  placeholders: []
+
+metadata:
+  display-name: Template VM Deployment
+  blueprint-labels:
+    - key: Category
+      value: VMaaS
+
+inputs:
+  agent:
+    type: agent
+
+outputs:
+  status:
+    value: '{{ .grains.health-check.outputs.status }}'
+
+grains:
+  initial-setup:
+    kind: shell
+    spec: ...
+
+  vm-deployment:
+    kind: terraform
+    spec: ...
+
+  health-check:
+    kind: shell
+    depends-on: vm-deployment
+    spec: ...
+```
+
+### Key sections
+
+| Section | Description |
+|---|---|
+| `template.placeholders` | Marks the blueprint as a template and defines placeholder slots. |
+| `metadata` | Standard catalog metadata such as display name, labels, and icon. |
+| `inputs` | Parameters exposed to the end user (for example `agent`). |
+| `outputs` | Values exposed from deployed grains (for example health or endpoint status). |
+| `grains` | The reusable deployment flow that template consumers can adapt. |
+
+## Example: template VM deployment blueprint
+
+The following example shows a VM deployment blueprint marked as a template:
+
+```yaml
+spec_version: 2
+description: An Ubuntu Template VM Deployment Blueprint is a standardized framework that automates the provisioning and configuration of virtual machines (VMs) across various cloud platforms and on-premises environments. It provides a reusable template for deploying VMs with predefined settings, such as operating system, resource allocation, and network configurations. This blueprint streamlines the deployment process, ensures consistency across environments, and accelerates time-to-deployment for applications and services that require VM infrastructure.
+
+template:
+  placeholders: []
+  
+metadata:
+  blueprint-labels:
+    - key: Category
+      value: VMaaS
+  display-name: Template VM Deployment
+  icon:
+    path: graphics/Ubuntu.svg
+
+inputs:
+  agent:
+    type: agent
+
+outputs:
+  status:
+    # placeholder. should be adapted if changed in the health-check
+    value: '{{.grains.health-check.outputs.status}}'
+
+grains:
+  initial-setup:
+    kind: shell
+    spec:
+      agent:
+        name: '{{.inputs.agent}}'
+      ...
+
+  vm-deployment:
+    kind: terraform
+    spec:
+      agent:
+        name: '{{.inputs.agent}}'
+      ...
+
+  # placeholder for grain
+  health-check:
+    kind: shell
+    depends-on: vm-deployment
+    spec:
+      agent:
+        name: '{{.inputs.agent}}'
+      ...
+```
+
+## Related topics
+
+- [Blueprint YAML Structure](/blueprint-designer-guide/blueprints/blueprints-yaml-structure)
+- [Blueprint Families](/blueprint-designer-guide/blueprint-families)
+- [Blueprint Publishing](/blueprint-designer-guide/blueprint-publishing)

docs/blueprint-designer-guide/blueprints/blueprints-yaml-structure.md

@@ -494,6 +494,11 @@ The ability to use outputs from specific grain usually requires the grain deploy
 
 Use `when` on a grain to control whether that grain runs or is skipped.
 
+:::warning Beta Feature
+Grain `when` is currently in beta.
+Behavior and schema details may change as the feature evolves.
+:::
+
 #### Skip or run a grain
 
 Use the `when` field on a grain to decide if that grain should run. If `when` evaluates to `false`, Torque skips the grain.
@@ -550,6 +555,11 @@ grains:
 
 Use `approvals` on a grain when you need a human gate before that grain executes.
 
+:::warning Beta Feature
+Grain `approvals` is currently in beta.
+Behavior and schema details may change as the feature evolves.
+:::
+
 #### Human gate
 
 Use the `approvals` block directly under a grain (not under `condition`) to require approval before the grain executes.