# Design: YAML-First Interpolation

## Problem Statement

The current implementation performs string-based interpolation on the raw YAML file content before parsing. This approach has several issues:

1. **Quoting complexity**: We must handle YAML quoting rules manually, leading to edge cases and bugs
2. **Type loss**: All interpolated values become strings, even if they should be numbers or booleans
3. **YAML special values**: Values like "no", "yes", "true", "false", "on", "off" require special handling
4. **Nested interpolation quoting**: Complex logic needed to avoid double-quoting in nested interpolations
5. **Fragile string manipulation**: Operating on raw YAML text is error-prone

## Proposed Solution

Parse the YAML file first, then walk the parsed structure to perform interpolations. This approach:

1. **Leverages YAML parser**: Let the YAML library handle all parsing, quoting, and escaping
2. **Preserves types**: Can return actual numbers, booleans, etc. from interpolations
3. **Simplifies logic**: No string manipulation or quoting logic needed
4. **Clear semantics**: Users control types through YAML syntax (quoted vs unquoted)
5. **Robust**: YAML serializer handles all edge cases correctly

## Implementation Details

### Constraints

- Interpolation only occurs in YAML values, not keys
- Users must properly quote interpolations if they want string output
- The entire file must be valid YAML before interpolation

### Workflow

1. Parse YAML file into a data structure (map/slice/scalar)
2. Recursively walk the structure:
   - For string values: check for `${...}` patterns and interpolate
   - For other types: pass through unchanged
3. Handle the special `env` key to inject environment variables
4. Return the modified structure

### Type Handling

Users control the output type through YAML syntax:

```yaml
# String output (user quotes the interpolation)
port: "${ENV:PORT}"          # Result: "8080" (string)

# Numeric output (no quotes)
port: ${ENV:PORT}            # Result: 8080 (number)

# Boolean output
enabled: ${ENV:ENABLED}      # Result: true/false (boolean)
```

### Benefits

1. **Correctness**: YAML parser handles all edge cases
2. **Type safety**: Preserves intended types
3. **Simplicity**: Removes complex string manipulation
4. **Predictability**: Users have explicit control over types
5. **Maintainability**: Less code, fewer edge cases