diff --git a/docs/ai/android.md b/docs/ai/android/android.md
similarity index 57%
rename from docs/ai/android.md
rename to docs/ai/android/android.md
index 670f2f3..f3d601c 100644
--- a/docs/ai/android.md
+++ b/docs/ai/android/android.md
@@ -1,6 +1,6 @@
 # Android AI Setup
 
-You are here: [AI Docs Home](index.md) > Android Setup
+You are here: [AI Docs Home](../index.md) > Android Setup
 
 ## Contents
 - Setup
@@ -9,29 +9,10 @@ You are here: [AI Docs Home](index.md) > Android Setup
 - Android Troubleshooting
 - Next Steps
 
-## Setup: VS Code + GitHub Copilot Extension
-### Prerequisites
-- VS Code installed and up to date.
-- GitHub account with Copilot Enterprise access.
+## Setup: VS Code + GitHub Copilot
+Before starting, complete the [VS Code Initial Setup](../vscode-setup.md) for Copilot and Copilot Chat. This covers installing VS Code, GitHub Copilot, signing in, and verifying suggestions.
 
-### Install and Sign In (High-Level)
-1. Install the GitHub Copilot extension.
-2. Sign in with your GitHub account.
-3. Confirm Copilot is enabled in VS Code.
-4. Run a simple prompt to verify suggestions appear.
-
-### Example Prompt (VS Code)
-Open a Kotlin file and add:
-
-Example prompt:
-```text
-// Create a Kotlin data class for a user profile with name and email.
-```
-
-### Verification Steps
-- Open a Kotlin file and start a small function.
-- Confirm inline suggestions appear.
-- Open Copilot Chat and ask a short question.
+Once Copilot is working, continue below for Android-specific guidance.
 
 ## Android-Specific Guidance
 - Ask for Kotlin/Java patterns with small, bounded tasks.
@@ -45,7 +26,7 @@ Refactor this repository to reduce duplication. Keep the public API the same and
 ```
 
 ## MCP For Android (High-Level)
-MCP tools can automate Android tasks like builds, tests, and diagnostics. The exact tool depends on your team setup.
+MCP tools can automate Android tasks like builds, tests, and diagnostics. Complete the [VS Code Initial Setup](../vscode-setup.md) first, then follow your team’s approved Android MCP tool instructions here.
 
 ### What To Add Here
 When you identify the approved Android MCP tool(s), add:
@@ -72,6 +53,6 @@ Refactor this file to reduce duplication without changing behavior.
 - Multiple AI extensions competing for suggestions.
 
 ## Next Steps
-- For workflow patterns, read [Cross-Platform AI Usage](cross-platform.md).
-- For safety rules, read [Governance, Privacy, and Policy](governance.md).
-- For cost guidance, read [Usage and Token Budgeting](usage-tokens.md).
+- For workflow patterns, read [Cross-Platform AI Usage](../cross-platform.md).
+- For safety rules, read [Governance, Privacy, and Policy](../governance.md).
+- For cost guidance, read [Usage and Token Budgeting](../usage-tokens.md).
diff --git a/docs/ai/cross-platform.md b/docs/ai/cross-platform.md
deleted file mode 100644
index ec853b5..0000000
--- a/docs/ai/cross-platform.md
+++ /dev/null
@@ -1,175 +0,0 @@
-# Cross-Platform AI Usage
-
-You are here: [AI Docs Home](index.md) > Cross-Platform AI Usage
-
-## Contents
-- Instructions (Always-On Rules)
-- Agents.md
-- Agents vs Skills
-- Prompting Patterns
-- Prompting Anti-Patterns
-- Plan-First Workflow
-- Starter Prompts
-- MCP Overview
-- Next Steps
-
-## Instructions (Always-On Rules)
-Instructions are repo-scoped rules that auto-apply based on file patterns. They are always on and do not need to be invoked.
-
-Where they live:
-- Repo instructions directory (for example, [assets/instructions/](../../assets/instructions/))
-- Editor or org-level instruction files when configured by your team
-
-## Agents.md
-### What It Is
-Agents define a structured workflow so tasks are broken into clear steps, with explicit inputs and outputs.
-
-### How to Use It
-1. Read [Agents.md](../../Agents.md).
-2. Choose a workflow that matches your task.
-3. Provide the inputs in a short, bounded request.
-
-### Example Request
-Example prompt:
-
-```text
-Goal: Improve readability in this module
-Inputs: src/foo/Bar.kt, keep behavior the same
-Output: A small refactor and a short summary
-Verification: No tests needed
-```
-
-### When to Use Agents vs Chat
-- Use agents for multi-step tasks like refactors, doc audits, or migrations.
-- Use chat for quick questions or one-off explanations.
-
-## Agents vs Skills (Quick Compare)
-- Agents are full modes/personas that control behavior end-to-end. They can be stored in a repo or a user-level folder.
-- Skills are focused workflows you load for specific tasks. They are typically installed globally via the approved skills directory.
-
-## Chat Modes In Copilot
-Ask: Quick Q and A or summaries.
-Edit: Targeted file edits with constraints.
-Plan: Planning only, no edits yet.
-Agent: Multi-step work across files or tools.
-
-Example prompts:
-```text
-Ask: Explain this error message and list the top 3 likely fixes.
-Edit: In this file, extract a helper function for validation and keep behavior the same.
-Plan: Provide a 5-step plan to split this class into smaller components. Wait for approval.
-Agent: Refactor the service layer, update tests, run the test task, and summarize results.
-```
-
-### Request Template
-Use this structure to get consistent results:
-
-```text
-Goal: <one sentence>
-Inputs: <files, constraints, context>
-Output: <expected deliverable>
-Verification: <tests or checks>
-```
-
-## Prompting Patterns
-Example prompts:
-```text
-Refactors: Refactor this file to improve readability without changing behavior.
-Tests: Add unit tests for this service. Keep the existing public API.
-Debugging: Explain this error and list likely fixes in order.
-Understanding code: Summarize what this module does and call out risks.
-```
-
-## Prompting Anti-Patterns (And Fixes)
-Common mistakes and better alternatives:
-
-Example prompts:
-```text
-Too broad: Fix everything in this project.
-Better: Refactor this file to remove duplication. Do not change behavior.
-
-Too vague: Make this code better.
-Better: Improve naming and add comments only where logic is complex.
-
-Missing inputs: Update the service to handle retries.
-Better: Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
-```
-
-### Example: Too Broad vs Scoped
-Example prompts:
-```text
-Too broad: Fix everything in this project.
-Scoped: Refactor this file to remove duplication. Do not change behavior.
-```
-
-## Plan-First Workflow
-1. Ask for a short plan.
-2. Approve or adjust the plan.
-3. Ask for targeted changes.
-4. Verify with tests or review.
-
-### Example Plan Request
-Example prompt:
-```text
-Provide a 5-step plan to refactor this module. Wait for approval before edits.
-```
-
-## Starter Prompts (Copy/Paste)
-Use these when you are not sure where to begin:
-
-Example prompts:
-```text
-Summarize this file in 5 bullets and list 2 risks.
-Refactor this function to remove duplication. Keep behavior the same.
-List tests I should add for this change.
-Explain this error and propose the top 3 fixes.
-Create a 5-step plan to split this class into smaller components.
-```
-
-## Connecting Skills
-- Use skills for tasks with known workflows.
-- Combine multiple skills when a task spans domains.
-- Pass concise context between steps to reduce repetition.
-
-## Efficiency Tips
-- Keep prompts small and scoped.
-- Reuse context from earlier steps instead of repeating it.
-- Ask for summaries before asking for edits.
-
-### Example Summary Request
-Example prompt:
-```text
-Summarize the decisions so far in 6 bullets so I can start a new chat.
-```
-
-## MCP (Model Context Protocol) - Cross-Platform Overview
-MCP is an open standard that lets tools and agents interact with real systems. In plain language, MCP lets the assistant "do" things (like run builds or fetch logs) instead of just talking about them.
-
-### How MCP Helps In A Workflow
-Think of MCP as a set of safe, structured buttons the assistant can press. You ask a question, the assistant calls a tool, and it returns a clear result.
-
-### Common MCP Use Cases (All Platforms)
-- Run builds and tests
-- Fetch logs or diagnostics
-- Query project configuration
-- Generate previews or reports
-
-### Example Workflow
-1. Ask the assistant to run a build.
-2. The MCP tool runs it and returns the result.
-3. You ask for a summary and next steps.
-
-### Example Prompt
-Example prompt:
-```text
-Use the build MCP tool to run the build and summarize any errors.
-```
-
-### Where To Learn More
-- iOS examples: see [iOS Setup](ios.md)
-- Android examples: see [Android Setup](android.md)
-
-## Next Steps
-- If you need skills guidance, read [Skills Library](skills.md).
-- For safety rules, read [Governance, Privacy, and Policy](governance.md).
-- If setup is not working, follow [Troubleshooting and FAQ](troubleshooting.md).
diff --git a/docs/ai/crossplatform/cross-platform.md b/docs/ai/crossplatform/cross-platform.md
new file mode 100644
index 0000000..c37a977
--- /dev/null
+++ b/docs/ai/crossplatform/cross-platform.md
@@ -0,0 +1,23 @@
+# Cross-Platform AI Usage (Overview)
+
+You are here: [AI Docs Home](../index.md) > Cross-Platform AI Usage
+
+This page gives a high-level overview of cross-platform AI usage, agent workflows, and prompting patterns. For detailed patterns, anti-patterns, and workflows, see the linked guides below.
+
+## Quick Links
+- [Prompting Patterns](prompting-patterns.md)
+- [Prompting Anti-Patterns](prompting-antipatterns.md)
+- [Plan-First Workflow](plan-first-workflow.md)
+- [Starter Prompts](starter-prompts.md)
+- [MCP Overview](mcp-overview.md)
+
+## Repo Instructions (Always-On Rules)
+Instructions are repo-scoped rules that auto-apply based on file patterns. See your repo’s instructions directory (e.g., [assets/instructions/](../../assets/instructions/)).
+
+## Agents and Skills
+- Agents: Use for multi-step, structured tasks (see [Agents.md](../../Agents.md)).
+- Skills: Use for focused, repeatable workflows (see [Skills Library](../skills.md)).
+
+## Next Steps
+- For safety rules, read [Governance, Privacy, and Policy](../governance.md)
+- If setup is not working, follow [Troubleshooting and FAQ](../troubleshooting.md)
diff --git a/docs/ai/crossplatform/mcp-overview.md b/docs/ai/crossplatform/mcp-overview.md
new file mode 100644
index 0000000..851e848
--- /dev/null
+++ b/docs/ai/crossplatform/mcp-overview.md
@@ -0,0 +1,24 @@
+# MCP (Model Context Protocol) - Cross-Platform Overview
+
+MCP is an open standard that lets tools and agents interact with real systems. In plain language, MCP lets the assistant "do" things (like run builds or fetch logs) instead of just talking about them.
+
+## How MCP Helps In A Workflow
+Think of MCP as a set of safe, structured buttons the assistant can press. You ask a question, the assistant calls a tool, and it returns a clear result.
+
+## Common MCP Use Cases (All Platforms)
+- Run builds and tests
+- Fetch logs or diagnostics
+- Query project configuration
+- Generate previews or reports
+
+## Example Workflow
+1. Ask the assistant to run a build.
+2. The MCP tool runs it and returns the result.
+3. You ask for a summary and next steps.
+
+## Example Prompt
+Use the build MCP tool to run the build and summarize any errors.
+
+## Where To Learn More
+- iOS examples: see [iOS Setup](../ios/ios.md)
+- Android examples: see [Android Setup](../android/android.md)
diff --git a/docs/ai/crossplatform/plan-first-workflow.md b/docs/ai/crossplatform/plan-first-workflow.md
new file mode 100644
index 0000000..f9c4a1b
--- /dev/null
+++ b/docs/ai/crossplatform/plan-first-workflow.md
@@ -0,0 +1,10 @@
+# Plan-First Workflow
+
+1. Ask for a short plan.
+2. Approve or adjust the plan.
+3. Ask for targeted changes.
+4. Verify with tests or review.
+
+### Example Plan Request
+
+Provide a 5-step plan to refactor this module. Wait for approval before edits.
diff --git a/docs/ai/crossplatform/prompting-antipatterns.md b/docs/ai/crossplatform/prompting-antipatterns.md
new file mode 100644
index 0000000..89e2c60
--- /dev/null
+++ b/docs/ai/crossplatform/prompting-antipatterns.md
@@ -0,0 +1,17 @@
+# Prompting Anti-Patterns (And Fixes)
+
+Common mistakes and better alternatives:
+
+**Too broad:** Fix everything in this project.
+**Better:** Refactor this file to remove duplication. Do not change behavior.
+
+**Too vague:** Make this code better.
+**Better:** Improve naming and add comments only where logic is complex.
+
+**Missing inputs:** Update the service to handle retries.
+**Better:** Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
+
+### Example: Too Broad vs Scoped
+
+Too broad: Fix everything in this project.
+Scoped: Refactor this file to remove duplication. Do not change behavior.
diff --git a/docs/ai/crossplatform/prompting-patterns.md b/docs/ai/crossplatform/prompting-patterns.md
new file mode 100644
index 0000000..104c599
--- /dev/null
+++ b/docs/ai/crossplatform/prompting-patterns.md
@@ -0,0 +1,8 @@
+# Prompting Patterns
+
+Example prompts:
+
+- Refactor this file to improve readability without changing behavior.
+- Add unit tests for this service. Keep the existing public API.
+- Explain this error and list likely fixes in order.
+- Summarize what this module does and call out risks.
diff --git a/docs/ai/crossplatform/starter-prompts.md b/docs/ai/crossplatform/starter-prompts.md
new file mode 100644
index 0000000..07211dd
--- /dev/null
+++ b/docs/ai/crossplatform/starter-prompts.md
@@ -0,0 +1,9 @@
+# Starter Prompts (Copy/Paste)
+
+Use these when you are not sure where to begin:
+
+- Summarize this file in 5 bullets and list 2 risks.
+- Refactor this function to remove duplication. Keep behavior the same.
+- List tests I should add for this change.
+- Explain this error and propose the top 3 fixes.
+- Create a 5-step plan to split this class into smaller components.
diff --git a/docs/ai/index.md b/docs/ai/index.md
index 35963ca..111ddbc 100644
--- a/docs/ai/index.md
+++ b/docs/ai/index.md
@@ -5,28 +5,25 @@ You are here: AI Docs Home
 ## Contents
 - Guided Paths
 - Start Here
+- Platform Setup
+    - [VS Code Initial Setup](vscode-setup.md)
+    - [iOS Setup](ios/ios.md)
+    - [Android Setup](android/android.md)
 - Use AI Day-To-Day
 - Safety And Cost
-- iOS MCP Details
-
-Welcome. This section is the entry point for AI enablement. It assumes no prior knowledge and is safe to follow step-by-step.
-
-## Who This Is For
-You can be an expert engineer and still be new to AI. This guide explains every step and includes examples to keep you from guessing.
-
 ## How To Use This Guide
 Follow the steps in order. Do not skip ahead if this is your first time.
 
 ### Example Path (New iOS Engineer)
 1. Read [AI Overview](overview.md)
-2. Follow [iOS Setup](ios.md)
+2. Follow [iOS Setup](ios/ios.md)
 3. Skim [Usage and Token Budgeting](usage-tokens.md)
 4. Return to [Cross-Platform AI Usage](cross-platform.md)
 
 ## Guided Paths (Pick One)
 - New to AI: [AI Overview](overview.md) -> [Cross-Platform AI Usage](cross-platform.md) -> [Usage and Token Budgeting](usage-tokens.md)
-- iOS setup: [AI Overview](overview.md) -> [iOS Setup](ios.md) -> [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.md)
-- Android setup: [AI Overview](overview.md) -> [Android Setup](android.md) -> [Cross-Platform AI Usage](cross-platform.md)
+- iOS setup: [AI Overview](overview.md) -> [iOS Setup](ios/ios.md) -> [MCP](ios/ios-mcp.md)
+- Android setup: [AI Overview](overview.md) -> [Android Setup](android/android.md) 
 - Contributors: [AI Overview](overview.md) -> [Governance, Privacy, and Policy](governance.md) -> [Troubleshooting and FAQ](troubleshooting.md)
 
 ## If You Are New
@@ -40,20 +37,19 @@ If you will edit these docs, start with the "Key Repo Files" section in the over
 
 ## Start Here
 - [AI Overview](overview.md)
-- [iOS Setup](ios.md)
-- [Android Setup](android.md)
+- [iOS Setup](ios/ios.md)
+- [Android Setup](android/android.md)
 
 ## Use AI Day-To-Day
-- [Cross-Platform AI Usage](cross-platform.md) - Agents, instructions, prompting patterns, MCP overview, and workflow tips
+- [Cross-Platform AI Usage](crossplatform/cross-platform.md) - Overview, agent workflows, and navigation to:
+    - [Prompting Patterns](crossplatform/prompting-patterns.md)
+    - [Prompting Anti-Patterns](crossplatform/prompting-antipatterns.md)
+    - [Plan-First Workflow](crossplatform/plan-first-workflow.md)
+    - [Starter Prompts](crossplatform/starter-prompts.md)
+    - [MCP Overview](crossplatform/mcp-overview.md)
 - [Skills Library](skills.md)
 
 ## Safety And Cost
 - [Governance, Privacy, and Policy](governance.md)
 - [Usage and Token Budgeting](usage-tokens.md)
 - [Troubleshooting and FAQ](troubleshooting.md)
-
-## iOS MCP Details
-- [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.md) - Full MCP setup and usage for Xcode workflows
-
-## Confluence Mapping
-This folder maps 1:1 to Confluence pages so content can be copied without rework.
diff --git a/docs/ai/ios.md b/docs/ai/ios.md
deleted file mode 100644
index 21cb1f8..0000000
--- a/docs/ai/ios.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# iOS AI Setup
-
-You are here: [AI Docs Home](index.md) > iOS Setup
-
-## Contents
-- Setup Path A (Xcode)
-- Setup Path B (VS Code)
-- iOS-Specific Guidance
-- MCP For iOS
-- iOS Troubleshooting
-- Next Steps
-
-## Setup Path A: Xcode + GitHub Copilot for Xcode
-### Prerequisites
-- Xcode installed and up to date.
-- GitHub account with Copilot Enterprise access.
-
-### Install and Sign In (High-Level)
-1. Install the GitHub Copilot for Xcode plugin.
-2. Sign in with your GitHub account.
-3. Confirm Copilot is enabled in Xcode.
-4. Run a simple prompt to verify suggestions appear.
-
-### Example Prompt (Xcode)
-Type this in a Swift file comment, then wait for a suggestion:
-
-Example prompt:
-```text
-// Create a function that validates an email string.
-```
-
-### Verification Steps
-- Open a Swift file and start a small function.
-- Confirm inline suggestions appear.
-- Open the Copilot chat panel and ask a short question.
-
-## Setup Path B: VS Code + GitHub Copilot Extension
-### When to Use VS Code on iOS
-- Editing shared docs or configs.
-- Rapid refactors or explorations.
-- Working on multi-platform files.
-
-### Install and Sign In (High-Level)
-1. Install VS Code and the GitHub Copilot extension.
-2. Sign in with your GitHub account.
-3. Confirm Copilot is enabled in VS Code.
-4. Run a simple prompt to verify suggestions appear.
-
-### Example Prompt (VS Code)
-Open a Swift file and add:
-
-Example prompt:
-```text
-// Create a Swift struct for a user profile with name and email.
-```
-
-### Verification Steps
-- Open a Swift file and type a short function signature.
-- Confirm inline suggestions appear.
-- Open Copilot Chat and request a short summary.
-
-## iOS-Specific Guidance
-- Ask for Swift/SwiftUI patterns with small, bounded tasks.
-- Request tests or sample usages for view models.
-- Favor refactor or patch requests over full rewrites.
-
-### Example Request
-Example prompt:
-```text
-Refactor this SwiftUI view to reduce duplication. Do not change behavior. Provide a short diff summary.
-```
-
-### Starter Prompts
-Example prompts:
-```text
-Create a SwiftUI view model for this screen and list its inputs and outputs.
-Write unit tests for this view model using XCTest.
-Refactor this view to reduce duplication without changing behavior.
-```
-
-## MCP For iOS
-The detailed MCP setup and XcodeBuildMCP guidance is in a dedicated page:
-
-- [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.md)
-
-## iOS Troubleshooting
-- If suggestions are missing, confirm sign-in and access.
-- If the plugin is not visible, verify extension compatibility.
-- If responses are blocked, check network or policy constraints.
-
-### Common Setup Gaps
-- Copilot access not provisioned for the GitHub account.
-- Xcode plugin disabled after update.
-- Multiple AI plugins competing for suggestions.
-
-## Next Steps
-- For workflow patterns, read [Cross-Platform AI Usage](cross-platform.md).
-- For MCP automation, read [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.md).
-- For safety rules, read [Governance, Privacy, and Policy](governance.md).
diff --git a/docs/ai/ios/ios-mcp-vscode.md b/docs/ai/ios/ios-mcp-vscode.md
new file mode 100644
index 0000000..d908c16
--- /dev/null
+++ b/docs/ai/ios/ios-mcp-vscode.md
@@ -0,0 +1,88 @@
+
+# MCP for iOS in VS Code
+
+You are here: [AI Docs Home](../index.md) > MCP for iOS in VS Code
+
+## Contents
+- Overview
+- Prerequisites
+- XcodeBuildMCP Setup
+- Xcode Native MCP Setup
+- Example Prompts
+- Troubleshooting
+- Next Steps
+
+---
+
+## Overview
+
+This guide covers how to set up MCP (Model Context Protocol) automation for iOS development in VS Code. Complete the [VS Code Initial Setup](../vscode-setup.md) first.
+
+---
+
+## Prerequisites
+- macOS with Xcode 26.3+ installed (for native MCP) or Xcode 13+ (for XcodeBuildMCP)
+- VS Code with GitHub Copilot and Copilot Chat enabled ([see setup guide](../vscode-setup.md))
+- Node.js 18+ (for XcodeBuildMCP)
+- This repo opened in VS Code (workspace root)
+
+---
+
+## XcodeBuildMCP Setup (External Tool)
+1. Install XcodeBuildMCP:
+	 ```bash
+	 brew tap getsentry/xcodebuildmcp
+	 brew install xcodebuildmcp
+	 ```
+2. Ensure `.xcodebuildmcp/config.yaml` is present and configured for your workspace, scheme, and simulator.
+3. Add or update `.vscode/mcp.json`:
+	 ```json
+	 {
+		 "servers": {
+			 "XcodeBuildMCP": {
+				 "command": "xcodebuildmcp",
+				 "args": ["mcp"]
+			 }
+		 }
+	 }
+	 ```
+4. Restart VS Code. Copilot Chat will discover MCP tools.
+
+---
+
+## Xcode Native MCP Setup (Xcode 26.3+)
+1. Open Xcode.
+2. Go to Settings > Intelligence tab.
+3. Enable Model Context Protocol (toggle on Xcode Tools or Allow external connections).
+4. Add or update `.vscode/mcp.json`:
+	 ```json
+	 {
+		 "servers": {
+			 "XcodeNative": {
+				 "command": "xcrun",
+				 "args": ["mcpbridge"]
+			 }
+		 }
+	 }
+	 ```
+5. Restart VS Code. Copilot Chat will discover the native MCP server.
+
+---
+
+## Example Prompts
+- "Build and run ToyotaOneApp on the iPhone 17 Pro Max simulator."
+- "Run all UI tests and summarize failures."
+- "Take a screenshot of the home screen."
+
+---
+
+## Troubleshooting
+- If MCP tools are not available, confirm `.vscode/mcp.json` is present and correct.
+- For XcodeBuildMCP, check `.xcodebuildmcp/config.yaml` for correct paths and scheme.
+- Simulator not found? Boot it in Xcode or Simulator.app first.
+
+---
+
+## Next Steps
+- For general VS Code setup, see [VS Code Initial Setup](../vscode-setup.md).
+- For iOS basics, see [iOS Setup](ios.md).
diff --git a/docs/ai/ios/ios-mcp.md b/docs/ai/ios/ios-mcp.md
new file mode 100644
index 0000000..6ba8982
--- /dev/null
+++ b/docs/ai/ios/ios-mcp.md
@@ -0,0 +1,37 @@
+# iOS MCP Overview
+
+You are here: [AI Docs Home](../index.md) > iOS MCP Overview
+
+## What is MCP for iOS?
+MCP (Model Context Protocol) enables automation and agent workflows for iOS development. It allows tools like Copilot Chat to build, test, run, and interact with Xcode projects programmatically.
+
+## Why Use MCP?
+- Automate builds, tests, and diagnostics
+- Enable agentic workflows in Copilot Chat and other tools
+- Standardize and speed up repetitive tasks
+- Reduce context switching between tools
+
+## MCP Options for iOS
+There are two main ways to use MCP with iOS projects:
+
+### 1. Xcode Native MCP (Xcode 26.3+)
+- Built into Xcode 26.3 and later
+- Official Apple support
+- Best for seamless integration and live previews
+- [Setup & details](ios-xcodebuildmcp-xcode.md)
+
+### 2. XcodeBuildMCP (External Tool)
+- Open-source bridge for Xcode 13+ (works with older versions)
+- More configuration and CI/CD options
+- Best for advanced automation or older Xcode setups
+- [Setup & details](ios-xcodebuildmcp-vscode.md)
+
+## When to Use Which?
+- Use Xcode Native MCP for the simplest, most integrated experience (especially for new projects or live previews)
+- Use XcodeBuildMCP if you need advanced automation, CI/CD, or support for older Xcode versions
+- You can configure both and switch as needed in VS Code’s `.vscode/mcp.json`
+
+## Next Steps
+- [MCP for iOS in VS Code](ios-mcp-vscode.md)
+- [XcodeBuildMCP (Xcode)](ios-xcodebuildmcp-xcode.md)
+- [XcodeBuildMCP for iOS in VS Code](ios-xcodebuildmcp-vscode.md)
diff --git a/docs/ai/ios/ios-xcodebuildmcp-vscode.md b/docs/ai/ios/ios-xcodebuildmcp-vscode.md
new file mode 100644
index 0000000..87411cc
--- /dev/null
+++ b/docs/ai/ios/ios-xcodebuildmcp-vscode.md
@@ -0,0 +1,160 @@
+
+# XcodeBuildMCP for iOS in VS Code
+
+You are here: [AI Docs Home](../index.md) > XcodeBuildMCP for iOS in VS Code
+
+## Contents
+- Overview
+- Requirements
+- One-time Repo Setup
+- XcodeBuildMCP Installation & Configuration
+- Using XcodeBuildMCP in Copilot Chat
+- Common Actions & Prompts
+- Troubleshooting
+- References
+- Next Steps
+
+---
+
+## Overview
+
+XcodeBuildMCP lets you run Xcode build and test tasks from within VS Code, using agent workflows and Copilot Chat. This reduces context switching and makes iOS automation repeatable.
+
+---
+
+## Requirements
+
+- macOS with Xcode installed (includes iOS Simulator)
+- VS Code with GitHub Copilot Chat enabled
+- MCP tools configured in VS Code (repo includes .vscode/mcp.json)
+- Node.js 18+ (required by the MCP host)
+- This repo opened in VS Code (workspace root)
+
+Optional but commonly needed for successful builds:
+- Ruby + Bundler
+- CocoaPods
+- Flutter + FVM (if working on the Flutter module)
+
+---
+
+## One-time Repo Setup
+
+Run the standard project setup so builds succeed:
+
+1. `./scripts/setup.sh`
+2. `bundle exec pod install`
+3. If using Flutter: `cd ../oneappmodule-2.0/apps/oneapp && fvm flutter pub get`
+
+---
+
+## XcodeBuildMCP Installation & Configuration
+
+### 1. Install XcodeBuildMCP
+
+```bash
+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.
+
+Example (Toyota):
+
+```yaml
+schemaVersion: 1
+sessionDefaults:
+	workspacePath: ./OneApp.xcworkspace
+	scheme: ToyotaOneApp
+	configuration: Debug
+	simulatorName: iPhone 17 Pro Max
+	simulatorId: <SIMULATOR_UDID>
+	useLatestOS: true
+```
+
+Notes:
+- Use either `simulatorName` or `simulatorId`. If both are set, `simulatorId` takes precedence.
+- The simulator must be installed and booted before running build/run.
+
+### 3. Configure MCP in VS Code
+
+- Ensure `.vscode/mcp.json` exists:
+
+```json
+{
+	"servers": {
+		"XcodeBuildMCP": {
+			"command": "xcodebuildmcp",
+			"args": ["mcp"]
+		}
+	}
+}
+```
+
+- Restart VS Code or reload the window. Copilot should discover the tools.
+
+---
+
+## Using XcodeBuildMCP in Copilot Chat
+
+From Copilot Chat, you can ask to build and run via XcodeBuildMCP. Example prompts:
+
+- "build and run ToyotaOneApp on the iPhone 17 Pro Max simulator"
+- "launch ToyotaOneApp without building (use the existing build)"
+- "take a screenshot of the home screen"
+
+Common tool actions the agent will use:
+- list_devices, list_schemes
+- session_set_defaults
+- build_run_sim
+- launch_app_sim (no build)
+- screenshot
+
+---
+
+## Common Actions & Prompts
+
+- **Build:**  
+	"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."
+
+- **Unit Tests:**  
+	"Run unit tests with XcodeBuildMCP and list failing tests with file names."
+
+- **UI Tests:**  
+	"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."
+
+- **Screenshots:**  
+	"Run the UI test that captures screenshots and list the output paths."
+
+- **Run without building:**  
+	"launch ToyotaOneApp without building"
+
+- **Home screen screenshot (example flow):**
+	1. "launch ToyotaOneApp without building"
+	2. Wait for the app to load the home screen
+	3. "take a screenshot of the home screen"
+
+---
+
+## Troubleshooting
+
+- **Build DB locked:** another build is running. Stop it and retry.
+- **Wrong scheme or workspace:** confirm in `.xcodebuildmcp/config.yaml`.
+- **Simulator not found:** install/boot the simulator in Xcode or Simulator.app.
+- If MCP tools are not available in VS Code, confirm `.vscode/mcp.json` is present and enabled.
+
+---
+
+## References
+
+- https://github.com/getsentry/XcodeBuildMCP
+- https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/
+- https://code.visualstudio.com/docs/copilot/customization/mcp-servers
+
+---
+
+## Next Steps
+
+- For iOS setup basics, read [iOS Setup](ios.md).
+- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).
diff --git a/docs/ai/ios-xcodebuildmcp.md b/docs/ai/ios/ios-xcodebuildmcp-xcode.md
similarity index 78%
rename from docs/ai/ios-xcodebuildmcp.md
rename to docs/ai/ios/ios-xcodebuildmcp-xcode.md
index 258015a..eb35200 100644
--- a/docs/ai/ios-xcodebuildmcp.md
+++ b/docs/ai/ios/ios-xcodebuildmcp-xcode.md
@@ -1,16 +1,16 @@
-# XcodeBuildMCP (iOS)
+# XcodeBuildMCP (Xcode)
 
-You are here: [AI Docs Home](index.md) > XcodeBuildMCP (iOS)
+You are here: [AI Docs Home](../index.md) > XcodeBuildMCP (Xcode)
 
 ## Contents
 - What XcodeBuildMCP Is
 - What It Can Do
-- Xcode 26.3 MCP Setup
+- Xcode 26.3 MCP Setup (Xcode)
 - Standardize The Simulator
 - References
 - Next Steps
 
-This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup.
+This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup for Xcode users.
 
 ## What XcodeBuildMCP Is
 XcodeBuildMCP can run build and test tasks without you switching into Xcode for every step. This reduces context switching and makes workflows repeatable.
@@ -73,14 +73,10 @@ Example prompt:
 Build with XcodeBuildMCP and extract the first error message only.
 ```
 
-## Xcode 26.3 MCP Setup (Detailed)
-These steps reflect a common setup as of February 2026. Wording may vary slightly in release candidates.
+## Xcode 26.3 MCP Setup (Xcode)
 
 ### Prerequisites
 - Xcode 26.3 (RC or full release), opened at least once with your project
-- VS Code installed (stable or Insiders)
-- GitHub Copilot extension installed and signed in
-- Node.js and npm installed (for XcodeBuildMCP)
 
 ### Step 1: Enable Xcode MCP Server
 1. Open Xcode.
@@ -89,29 +85,7 @@ These steps reflect a common setup as of February 2026. Wording may vary slightl
 4. Find the Model Context Protocol section.
 5. Toggle on Xcode Tools (or Allow external connections).
 
-### Step 2: Install And Configure XcodeBuildMCP (Recommended Bridge)
-Install:
-
-```bash
-npm install -g xcodebuildmcp@latest
-```
-
-Add to VS Code (create or edit .vscode/mcp.json):
-
-```json
-{
-	"servers": {
-		"XcodeBuildMCP": {
-			"command": "npx",
-			"args": ["-y", "xcodebuildmcp@latest", "mcp"]
-		}
-	}
-}
-```
-
-Restart VS Code or reload the window. Copilot should discover the tools.
-
-### Step 3: Optional Native Xcode MCP Bridge
+### Step 2: Optional Native Xcode MCP Bridge
 Xcode 26.3 includes a native MCP bridge. This exposes Xcode tools directly.
 
 Add to VS Code:
@@ -127,20 +101,9 @@ Add to VS Code:
 }
 ```
 
-### Using MCP In VS Code With Copilot
-1. Open your iOS project in VS Code.
-2. Use Copilot Chat in agent mode for multi-step tasks.
-3. MCP tools appear as slash commands once discovered.
-
-Example prompt:
-```text
-Use XcodeBuildMCP to build and summarize errors. Then suggest fixes.
-```
-
 ### Tips And Caveats
 - Xcode must be running (or launchable) for MCP tools to respond.
 - Native Xcode MCP is often best for previews.
-- XcodeBuildMCP is often best for heavy builds and automation.
 
 ## Standardize The Simulator (Avoid Back-And-Forth)
 Pin a simulator name and OS version in your project guidance so the assistant always uses the same target.
@@ -183,4 +146,4 @@ https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-age
 
 ## Next Steps
 - For iOS setup basics, read [iOS Setup](ios.md).
-- For cross-platform usage patterns, read [Cross-Platform AI Usage](cross-platform.md).
+- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).
diff --git a/docs/ai/ios/ios.md b/docs/ai/ios/ios.md
new file mode 100644
index 0000000..e2439b3
--- /dev/null
+++ b/docs/ai/ios/ios.md
@@ -0,0 +1,47 @@
+
+# iOS AI Setup (Quick Start)
+
+You are here: [AI Docs Home](../index.md) > iOS Setup
+
+## Which Path Should I Choose?
+
+- **Use Xcode** if you want the most integrated Apple experience for Swift/SwiftUI and UI design.
+- **Use VS Code** if you want automation, Copilot Chat agent workflows, or work on cross-platform code.
+- You can use both! Many developers do.
+
+---
+
+## Xcode: Copilot Setup Steps
+1. Install Xcode from the Mac App Store and open it once.
+2. Install the [GitHub Copilot for Xcode plugin](https://github.com/github/copilot-xcode) and enable it in Xcode’s Extensions.
+3. Sign in with your GitHub account (Copilot access required).
+4. Open a Swift file and type `//` to trigger a suggestion.
+5. Open Copilot Chat and try a simple prompt (e.g., “Write a Swift function to reverse a string”).
+
+## VS Code: Copilot Setup Steps
+1. Follow the [VS Code Initial Setup](../vscode-setup.md) to install VS Code, Copilot, and sign in.
+2. Open a Swift file and type `//` to trigger a suggestion.
+3. Open Copilot Chat and try a simple prompt.
+
+---
+
+
+## Add MCP Automation (Optional, Advanced)
+- For general MCP usage in VS Code: See [MCP for iOS in VS Code](ios-mcp-vscode.md)
+- For Xcode’s built-in MCP: See [XcodeBuildMCP (Xcode)](ios-xcodebuildmcp-xcode.md)
+- For XcodeBuildMCP in VS Code: See [XcodeBuildMCP for iOS in VS Code](ios-xcodebuildmcp-vscode.md)
+
+---
+
+## Troubleshooting
+- If suggestions are missing, confirm you’re signed in and Copilot is enabled.
+- If the plugin/extension is not visible, check compatibility and restart the app.
+- If responses are blocked, check your network or company policy.
+- If you have multiple AI plugins, disable all but Copilot.
+
+---
+
+## Next Steps
+- For cross-platform patterns, read [Cross-Platform AI Usage](../cross-platform.md)
+- For automation, see the MCP guides above
+- For safety rules, read [Governance, Privacy, and Policy](../governance.md)
diff --git a/docs/ai/overview.md b/docs/ai/overview.md
index ab6264a..eae2c8a 100644
--- a/docs/ai/overview.md
+++ b/docs/ai/overview.md
@@ -211,7 +211,7 @@ Refactor only the validation logic in this file. Keep behavior the same and list
 ```
 
 ## Next Steps
-- If you have not set up an editor yet, go to [iOS Setup](ios.md) or [Android Setup](android.md).
+- If you have not set up an editor yet, go to [iOS Setup](ios/ios.md) or [Android Setup](android/android.md).
 - For day-to-day usage patterns, read [Cross-Platform AI Usage](cross-platform.md).
 - For safety and cost guidance, read [Governance, Privacy, and Policy](governance.md) and [Usage and Token Budgeting](usage-tokens.md).
 
diff --git a/docs/ai/vscode-setup.md b/docs/ai/vscode-setup.md
new file mode 100644
index 0000000..6cdeb84
--- /dev/null
+++ b/docs/ai/vscode-setup.md
@@ -0,0 +1,57 @@
+# VS Code Initial Setup (All Platforms)
+
+You are here: [AI Docs Home](index.md) > VS Code Initial Setup
+
+## Contents
+- Overview
+- Install VS Code
+- Install GitHub Copilot
+- Sign In and Verify
+- Try Copilot Suggestions
+- Next Steps
+
+---
+
+## Overview
+
+This guide covers the basic setup for Visual Studio Code and GitHub Copilot. It applies to all platforms (iOS, Android, cross-platform). Complete these steps before any platform-specific automation or MCP setup.
+
+---
+
+## Install VS Code
+1. Download Visual Studio Code from [code.visualstudio.com](https://code.visualstudio.com/).
+2. Open the installer and follow the prompts to install.
+3. Launch VS Code.
+
+---
+
+## Install GitHub Copilot
+1. In VS Code, open the Extensions sidebar (⇧⌘X).
+2. Search for "GitHub Copilot" and click Install.
+3. (Optional) Search for and install "GitHub Copilot Chat" for chat-based workflows.
+
+---
+
+## Sign In and Verify
+1. After installing, you’ll be prompted to sign in with your GitHub account.
+2. Complete the sign-in flow in your browser.
+3. You must have Copilot access (Copilot Individual, Business, or Enterprise).
+4. Open a code file (e.g., Swift, Kotlin, Java, JS) and type `//` or start a function to trigger a suggestion.
+5. You should see Copilot suggestions inline.
+
+---
+
+## Try Copilot Suggestions
+- Open a file for your platform (Swift for iOS, Kotlin for Android, etc.).
+- Type a comment or function signature, e.g.:
+  - `// Create a function to validate an email address.`
+  - `fun main() {` (for Kotlin)
+- Accept a suggestion with Tab or Enter.
+- Open the Copilot Chat sidebar and try a prompt, e.g.:
+  - "Write a function to reverse a string in Kotlin."
+
+---
+
+## Next Steps
+- For iOS automation, see [MCP for iOS in VS Code](ios/ios-mcp-vscode.md).
+- For Android automation, see [Android Setup](android/android.md).
diff --git a/docs/planning/AI-Docs-Plan.md b/docs/planning/AI-Docs-Plan.md
index 1d026af..264652e 100644
--- a/docs/planning/AI-Docs-Plan.md
+++ b/docs/planning/AI-Docs-Plan.md
@@ -33,7 +33,7 @@ The docs under docs/ai map 1:1 to Confluence pages.
     - overview.md
     - ios.md
     - ios-xcodebuildmcp.md
-    - android.md
+    - android/android.md
     - cross-platform.md
     - skills.md
     - usage-tokens.md