Update Atmos YAML functions docs (#1826)

* update docs

* update docs

* update docs

* [autofix.ci] apply automated fixes

* docs: Address CodeRabbit nitpick suggestions

- Clarify that !terraform.state returns null when state file doesn't exist
- Enhance YQ expression comments in store.get.mdx to be more specific

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* address comments

* address comments

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Claude <[email protected]>

Author: 3 people

website/docs/functions/index.mdx

@@ -92,11 +92,11 @@ If you must use template functions:
 
 If you have existing template functions, consider migrating to YAML functions:
 
-| Instead of (Template) | Use (YAML) |
-|----------------------|------------|
-| `{{ exec "command" }}` | `!exec command` |
-| `{{ env "VAR" }}` | `!env VAR` |
-| `{{ toJson .values }}` | Native YAML structures |
+| Instead of (Template)         | Use (YAML)                                |
+|-------------------------------|-------------------------------------------|
+| `{{ exec "command" }}`        | `!exec command`                           |
+| `{{ env "VAR" }}`             | `!env VAR`                                |
+| `{{ toJson .values }}`        | Native YAML structures                    |
 | Reading outputs via templates | `!terraform.output` or `!terraform.state` |
 
 ## Performance Considerations

website/docs/functions/yaml/env.mdx

@@ -80,6 +80,11 @@ The `env:` section follows the standard Atmos merge priority:
 This means values defined at the component level will override values from globals.
 :::
 
+:::note Type-Aware Merging
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
+:::
+
 ## Limitations
 
 **Single-Pass Processing**: YAML functions are processed in a single pass. This means `!env` cannot reference environment variables that are defined by other YAML functions in the same component section.

website/docs/functions/yaml/exec.mdx

@@ -67,3 +67,8 @@ You can use [Atmos Stack Manifest Templating](/core-concepts/stacks/templates) i
 Atmos processes the templates first, and then executes the `!exec` function, allowing you to provide the parameters to
 the function dynamically.
 :::
+
+:::note Type-Aware Merging
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
+:::

website/docs/functions/yaml/store.get.mdx

@@ -78,20 +78,25 @@ If you need to retrieve values that follow the Atmos stack/component/key pattern
 [`!store`](/functions/yaml/store) function instead, as it provides better integration with Atmos component dependencies.
 :::
 
+:::note Type-Aware Merging
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
+:::
+
 ### Using YQ Expressions
 
 You can use [YQ](https://mikefarah.gitbook.io/yq) expressions to extract specific values
 from complex data structures:
 
 <File title="stack.yaml">
 ```yaml
-# Extract a field from a JSON object
+# Extract database host from app-config in Redis
 database_host: !store.get redis app-config | query .database.host
 
-# Get the first item from an array
+# Get the first availability zone from Azure Key Vault array
 primary_zone: !store.get azure-keyvault availability-zones | query .[0]
 
-# Extract nested values with a default
+# Extract API key from SSM config with empty object fallback
 api_key: !store.get ssm /external/config | default "{}" | query .api.key
 ```
 </File>

website/docs/functions/yaml/store.mdx

@@ -73,6 +73,11 @@ Atmos processes the templates first, and then executes the `!store` function, al
 the function dynamically.
 :::
 
+:::note Type-Aware Merging
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
+:::
+
 ## Using YQ Expressions to retrieve individual values
 
 To retrieve individual values from complex types such as maps and lists, or do any kind of filtering or querying,

website/docs/functions/yaml/template.mdx

@@ -139,6 +139,11 @@ YAML function. It produces the same results, correctly handles the complex types
 
 :::
 
+:::note Type-Aware Merging
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
+:::
+
 ## Advanced Examples
 
 The `!template` Atmos YAML function can be used to make your stack configuration DRY and reusable.

website/docs/functions/yaml/terraform.output.mdx

@@ -54,6 +54,11 @@ Atmos processes the templates first, and then executes the `!terraform.output` f
 the function dynamically.
 :::
 
+:::note Type-Aware Merging
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
+:::
+
 ## `!terraform.output` Function Execution Flow
 
 When processing the `!terraform.output` YAML function for a component in a stack, Atmos executes the following steps:
@@ -147,6 +152,9 @@ endpoint: !terraform.output services '.endpoints["my-service"]["production"].url
 
 # Combine with stack templating
 token: !terraform.output identity {{ .stack }} '.tokens["github-actions"].value'
+
+# Escape single quotes by doubling them when needed inside the expression
+app_name: !terraform.output config '.apps["app''s-name"].display_name'
 ```
 
 **Quote escaping rules**

website/docs/functions/yaml/terraform.state.mdx

@@ -67,6 +67,11 @@ Atmos processes the templates first, and then executes the `!terraform.state` fu
 the function dynamically.
 :::
 
+:::note Type-Aware Merging
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
+:::
+
 ## `!terraform.state` Function Execution Flow
 
 When processing the `!terraform.state` YAML function for a component in a stack, Atmos executes the following steps:
@@ -128,7 +133,40 @@ For more details, review the following docs:
 
 ## Handling YQ Expressions with Bracket Notation and Quotes
 
-`!terraform.state` shares the same parser as `!terraform.output`, so the quoting rules are identical. When you need double quotes inside a YQ expression (for example, to reference `["github-dependabot"]`), wrap the entire expression in single quotes. Refer to the [!terraform.output guidance](/functions/yaml/terraform.output#handling-yq-expressions-with-bracket-notation-and-quotes) for detailed examples and escape rules.
+When you access map keys that contain special characters (such as hyphens) by using YQ bracket notation, you must wrap the key in double quotes like `["github-dependabot"]`. This often clashes with the surrounding quotes that protect the entire expression in YAML.
+
+To avoid conflicting quotes, wrap the entire YQ expression in single quotes while keeping the double quotes inside the brackets:
+
+```yaml
+# Use single quotes around the expression to allow double quotes inside brackets
+access_key_id: !terraform.state security '.outputs.users["github-dependabot"].access_key_id'
+```
+
+Additional examples:
+
+```yaml
+# Access map keys with special characters
+api_key: !terraform.state config '.outputs.api_keys["service-account-1"]'
+
+# Access nested maps with special characters in multiple levels
+endpoint: !terraform.state services '.outputs.endpoints["my-service"]["production"]'
+
+# Combine with stack templating
+token: !terraform.state identity {{ .stack }} '.outputs.tokens["github-actions"]'
+
+# Escape single quotes by doubling them when needed inside the expression
+app_name: !terraform.state config '.outputs.apps["app''s-name"].display_name'
+```
+
+**Quote escaping rules**
+
+- Wrap the entire YQ expression in single quotes when it contains double quotes.
+- Use double quotes inside brackets for string keys in YQ expressions.
+- If you need single quotes inside the expression, escape them by doubling: `''`.
+
+:::tip
+This quoting pattern works for every Atmos YAML function that accepts YQ expressions, including [!terraform.output](/functions/yaml/terraform.output) and [!include](/functions/yaml/include).
+:::
 
 ## Using YQ Expressions to provide a default value
 
@@ -483,4 +521,5 @@ vars:
 
  - Be mindful of disaster recovery (DR) implications when using it across regions.
 
- - Consider cold-start scenarios: if the dependent component has not yet been provisioned, `terraform output` will fail.
+ - Consider cold-start scenarios: if the referenced component's state file doesn't exist (e.g., not yet provisioned), `!terraform.state` returns `null`.
+   Use the YQ `//` operator to provide default values for components that may not be provisioned yet (see [Using YQ Expressions to provide a default value](#using-yq-expressions-to-provide-a-default-value)).

website/docs/reference/yaml-function-merging.mdx

@@ -0,0 +1,88 @@
+---
+title: Type-Aware Merging of YAML Functions
+sidebar_position: 4
+sidebar_label: YAML Function Merging
+description: How Atmos handles merging YAML functions with concrete values in the inheritance chain
+---
+
+import Intro from '@site/src/components/Intro'
+
+<Intro>
+Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
+</Intro>
+
+## The Problem: Type Conflicts During Merge
+
+When merging stack configurations, Atmos needs to handle both concrete values and YAML function references. Without special handling, the merge process would encounter type mismatches:
+
+```yaml
+# Base catalog (catalog/app/defaults.yaml)
+components:
+  terraform:
+    my-app:
+      vars:
+        database_url: "postgresql://localhost:5432/mydb"  # Concrete string value
+
+# Environment override (stacks/prod/app.yaml)
+components:
+  terraform:
+    my-app:
+      vars:
+        database_url: !env DATABASE_URL  # YAML function reference
+```
+
+The YAML function `!env DATABASE_URL` is a different type than the string `"postgresql://localhost:5432/mydb"`. Without special handling, merging these would cause a type conflict error.
+
+## The Solution: Type-Aware Merging
+
+Atmos handles this gracefully through **type-aware merging**:
+
+1. YAML functions are recognized and wrapped in a special type during parsing
+2. During merge, this allows YAML functions to replace concrete values (and vice versa) without type errors
+3. YAML functions are evaluated as the final step in stack processing, as they have always been
+
+This approach ensures that YAML functions can override static values throughout the inheritance chain.
+
+## Supported Functions
+
+The following YAML functions support type-aware merging:
+
+- [`!env`](/functions/yaml/env) - Environment variables
+- [`!exec`](/functions/yaml/exec) - External command execution
+- [`!store`](/functions/yaml/store) - Store value retrieval
+- [`!store.get`](/functions/yaml/store.get) - Store value retrieval (alias)
+- [`!template`](/functions/yaml/template) - Template rendering
+- [`!terraform.output`](/functions/yaml/terraform.output) - Terraform output values
+- [`!terraform.state`](/functions/yaml/terraform.state) - Terraform state values
+
+## Benefits
+
+- **Flexible Configuration Patterns** - Mix static values and YAML functions across inheritance layers without type conflicts
+- **Gradual Migration** - Migrate from static to dynamic configurations incrementally
+- **Team Collaboration** - Different teams can use different approaches (static vs. templated) in their layers
+- **Multi-Environment Support** - Use static values in dev/staging and YAML functions in production
+
+## Example: Mixed Static and Dynamic Values
+
+```yaml
+# catalog/base.yaml - Base component with static defaults
+components:
+  terraform:
+    my-service:
+      vars:
+        log_level: "info"
+        api_endpoint: "https://api.dev.example.com"
+
+# stacks/prod.yaml - Production uses dynamic values
+import:
+  - catalog/base
+
+components:
+  terraform:
+    my-service:
+      vars:
+        log_level: !env LOG_LEVEL
+        api_endpoint: !terraform.output api-gateway endpoint
+```
+
+In this example, the production stack overrides static defaults with YAML functions. Type-aware merging allows these different value types to coexist without errors.