Add YAML schema validation documentation to VSCode setup guide

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Author: Copilot

docs/src/content/docs/setup/vscode.md

@@ -63,3 +63,59 @@ Configure VS Code to automatically compile workflows when files change. Create o
 ```
 
 The task starts automatically when you open a Markdown file under `.github/workflows/`. If it doesn't start, use the command palette (`Ctrl + Shift + P`) and run `Tasks: Manage Automatic Tasks` to enable automatic task execution.
+
+## YAML Schema Validation
+
+The repository is configured to provide real-time validation and autocomplete for workflow frontmatter using the [RedHat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
+
+### Features
+
+- **Real-time validation**: Frontmatter fields are validated as you type against the comprehensive workflow schema
+- **Autocomplete**: Get intelligent suggestions for field names and values
+- **Hover documentation**: See descriptions and examples for each field by hovering over it
+- **Error highlighting**: Invalid configurations are highlighted with descriptive error messages
+
+### Setup
+
+1. **Install the extension**: When you open the repository, VS Code will recommend installing the RedHat YAML extension. Accept the recommendation or install it manually from the Extensions marketplace.
+
+2. **Automatic configuration**: The schema is automatically applied to all `.md` files in `.github/workflows/` via `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "./pkg/parser/schemas/main_workflow_schema.json": ".github/workflows/*.md"
+  }
+}
+```
+
+### Usage
+
+When editing workflow markdown files (`.md` files in `.github/workflows/`), the YAML frontmatter block is validated:
+
+```yaml
+---
+name: My Workflow  # ✓ Valid string
+on: push           # ✓ Valid trigger
+permissions:
+  contents: read   # ✓ Valid permission level
+engine: copilot    # ✓ Valid engine
+invalid-field: x   # ✗ Error: Unknown property
+---
+```
+
+The extension validates:
+- Required fields (e.g., `on` trigger is required)
+- Field types (strings, numbers, booleans, objects, arrays)
+- Enum values (e.g., `engine` must be one of: `copilot`, `claude`, `codex`, `custom`)
+- Nested object structures
+- Complex conditional logic
+
+### Troubleshooting
+
+If schema validation isn't working:
+
+1. **Check extension is installed**: Look for "YAML" in your installed extensions list
+2. **Reload VS Code**: Use `Ctrl+Shift+P` → "Developer: Reload Window"
+3. **Verify file pattern**: Schema only applies to `.md` files in `.github/workflows/`
+4. **Check YAML frontmatter**: Ensure your frontmatter is wrapped in `---` delimiters