diff --git a/docs/ai/ios/ios-mcp-vscode.md b/docs/ai/ios/ios-mcp-vscode.md
index d908c16..612e548 100644
--- a/docs/ai/ios/ios-mcp-vscode.md
+++ b/docs/ai/ios/ios-mcp-vscode.md
@@ -34,7 +34,7 @@ This guide covers how to set up MCP (Model Context Protocol) automation for iOS
 	 brew tap getsentry/xcodebuildmcp
 	 brew install xcodebuildmcp
 	 ```
-2. Ensure `.xcodebuildmcp/config.yaml` is present and configured for your workspace, scheme, and simulator.
+2. Ensure `.xcodebuildmcp/config.yaml` is present and configured for your workspace, scheme, and simulator. ([What is config.yaml? See reference and sample.](xcodebuildmcp-config.yaml.md))
 3. Add or update `.vscode/mcp.json`:
 	 ```json
 	 {
diff --git a/docs/ai/ios/ios-xcodebuildmcp-vscode.md b/docs/ai/ios/ios-xcodebuildmcp-vscode.md
index 87411cc..e274683 100644
--- a/docs/ai/ios/ios-xcodebuildmcp-vscode.md
+++ b/docs/ai/ios/ios-xcodebuildmcp-vscode.md
@@ -56,9 +56,11 @@ brew tap getsentry/xcodebuildmcp
 brew install xcodebuildmcp
 ```
 
+
 ### 2. Configure XcodeBuildMCP
 
 - The repo should include `.xcodebuildmcp/config.yaml`. Make sure it points to the correct workspace, scheme, and simulator.
+- [What is config.yaml? See reference and sample.](xcodebuildmcp-config.yaml.md)
 
 Example (Toyota):
 
diff --git a/docs/ai/ios/xcodebuildmcp-config.yaml.md b/docs/ai/ios/xcodebuildmcp-config.yaml.md
new file mode 100644
index 0000000..cdb7170
--- /dev/null
+++ b/docs/ai/ios/xcodebuildmcp-config.yaml.md
@@ -0,0 +1,34 @@
+# xcodebuildmcp/config.yaml Reference
+
+This file is required for XcodeBuildMCP to automate builds, tests, and simulator actions. It tells the tool which workspace, scheme, configuration, and simulator to use.
+
+## Example config.yaml
+```yaml
+schemaVersion: 1
+sessionDefaults:
+  workspacePath: ./OneApp.xcworkspace
+  scheme: ToyotaOneApp
+  configuration: Debug
+  simulatorName: iPhone 17 Pro Max
+  simulatorId: <SIMULATOR_UDID>
+  useLatestOS: true
+```
+
+## Key Fields
+- `workspacePath`: Path to your .xcworkspace or .xcodeproj
+- `scheme`: The Xcode scheme to build/test
+- `configuration`: Build configuration (Debug, Release, etc.)
+- `simulatorName`: Name of the simulator to use
+- `simulatorId`: UDID of the simulator (optional; takes precedence over name)
+- `useLatestOS`: If true, always use the latest available iOS version
+
+## Where to put it
+Place this file at `.xcodebuildmcp/config.yaml` in your repo root.
+
+## Why it matters
+This config lets XcodeBuildMCP run builds, tests, and launches without manual setup. It ensures all developers and CI jobs use the same settings.
+
+## Troubleshooting
+- If builds fail, check workspacePath and scheme.
+- If the simulator isn’t found, check simulatorName or simulatorId.
+- If you change project structure, update config.yaml accordingly.