Introduced clearer mental model and progression

Author: madeline-underwood

content/learning-paths/servers-and-cloud-computing/arm-mcp-server/1-overview.md

@@ -10,31 +10,42 @@ layout: learningpathall
 
 The Arm MCP Server is a tool that enables AI-powered developer tools to become Arm cloud migration and optimization experts. It implements the Model Context Protocol (MCP), an open standard that allows AI assistants to access external tools and data sources.
 
+Think of the Arm MCP Server as a bridge between AI coding assistants and Arm-specific migration and optimization tools. It allows AI agents to use real, structured capabilities instead of guessing.
+
 By connecting your AI coding assistant to the Arm MCP Server, you gain access to Arm-specific knowledge, container image inspection tools, and code analysis capabilities that streamline the process of migrating applications from x86 to Arm.
 
 ## How to interact with the Arm MCP Server
 
-There are multiple ways to interact with the Arm MCP Server, depending on your development environment and workflow:
+The Arm MCP Server supports different interaction styles depending on the complexity of the migration task, from quick checks to fully automated workflows:
+
+- Direct AI chat: quick, exploratory checks
+- Prompt files: repeatable, structured workflows
+- Agentic workflows: fully autonomous multi-step migrations
 
-### 1. Direct AI Chat
+
+## Direct AI chat
 
 You can ask your AI assistant natural language questions, and it will automatically use the MCP tools when appropriate. For example:
 
 ```text
 Check if the nginx:latest Docker image supports Arm architecture
 ```
 
-### 2. Prompt Files
+## Prompt files
 
 Many AI coding tools support prompt files that provide structured instructions. These files can reference MCP tools and guide the AI through complex workflows like full codebase migrations.
 
-### 3. Agentic Workflows
+## Agentic workflows
 
 Tools like GitHub Copilot Agent Mode, Claude Code, Kiro, and OpenAI Codex support autonomous agent workflows where the AI can execute multi-step migration tasks with minimal intervention. These fully agentic workflows can be combined with prompt files and direct chat to create an extremely powerful development system.
 
-## Available Arm MCP Server Tools
+## Available Arm MCP Server tools
+
+The Arm MCP Server provides several specialized tools for migration and optimization, and these are detailed below.
 
-The Arm MCP Server provides several specialized tools for migration and optimization:
+{{% notice Note %}}
+You don't need all of these tools immediately. You'll start by using image inspection and knowledge lookup tools, and encounter the others as workflows become more advanced.
+{{% /notice %}}
 
 ### knowledge_base_search
 
@@ -78,9 +89,9 @@ To use the Arm MCP Server with an AI coding assistant, you need to configure the
 
 The required configuration steps vary by AI coding assistant. Refer to the installation guides below for step-by-step instructions on connecting the following AI coding assistants to the Arm MCP server:
 
-  [GitHub Copilot](/install-guides/github-copilot/)
-  [Gemini CLI](/install-guides/gemini/)
-  [Kiro CLI](/install-guides/kiro-cli/)
+- [GitHub Copilot](/install-guides/github-copilot/)
+- [Gemini CLI](/install-guides/gemini/)
+- [Kiro CLI](/install-guides/kiro-cli/)
 
 ## What you've accomplished and what's next
 

content/learning-paths/servers-and-cloud-computing/arm-mcp-server/2-docker-check.md

@@ -6,13 +6,15 @@ weight: 3
 layout: learningpathall
 ---
 
-## Checking Base Images for Arm Compatibility
+## Checking base images for Arm compatibility
 
 This section demonstrates just one example of using direct AI chat with the Arm MCP Server. You can use similar natural language prompts to check library compatibility, search for Arm documentation, or analyze code for migration issues.
 
 A common first step when migrating a containerized application to Arm is verifying that the base container images support the arm64 architecture. The Arm MCP Server simplifies this process by allowing you to ask this question directly using a natural language prompt, without manually inspecting image manifests or registry metadata. 
 
-## Example: Legacy CentOS 6 Application
+Direct AI chat works best as a fast decision gate as it helps you rule out incompatible base images and configurations before investing time in deeper migration or automation work.
+
+## Example: Legacy CentOS 6 application
 
 Consider an application built on CentOS 6, a legacy Linux distribution that has reached end of life (EOL). This example represents a typical x86-optimized, compute-heavy benchmark application that you might encounter when migrating older workloads.
 
@@ -75,7 +77,7 @@ RUN chmod +x start.sh
 CMD ["./start.sh"]
 ```
 
-## Using the Arm MCP Server to Check Compatibility
+## Using the Arm MCP Server to check compatibility
 
 With the Arm MCP Server connected to your AI assistant, you can quickly verify base image compatibility using a simple natural language prompt:
 

content/learning-paths/servers-and-cloud-computing/arm-mcp-server/3-simd-migration.md

@@ -6,11 +6,13 @@ weight: 4
 layout: learningpathall
 ---
 
-## Migrating SIMD Code with AI Assistance
+## Migrating SIMD code with AI assistance
 
-When migrating applications from x86 to Arm, you may encounter SIMD (Single Instruction, Multiple Data) code that is written using architecture-specific intrinsics. On x86 platforms, SIMD is commonly implemented with SSE, AVX, or AVX2 intrinsics, while Arm platforms use NEON and SVE intrinsics to provide similar vectorized capabilities. Updating this code manually can be time-consuming and challenging. By combining the Arm MCP Server with a well-defined prompt file, you can automate much of this work and guide an AI assistant through a structured, architecture-aware migration of your codebase.
+When migrating applications from x86 to Arm, you might encounter SIMD (Single Instruction, Multiple Data) code that is written using architecture-specific intrinsics. On x86 platforms, SIMD is commonly implemented with SSE, AVX, or AVX2 intrinsics, while Arm platforms use NEON and SVE intrinsics to provide similar vectorized capabilities. Updating this code manually can be time-consuming and challenging. By combining the Arm MCP Server with a well-defined prompt file, you can automate much of this work and guide an AI assistant through a structured, architecture-aware migration of your codebase.
 
-## Sample x86 Code with AVX2 Intrinsics
+## Sample x86 code with AVX2 intrinsics
+
+{{% notice Note %}}You don't need to understand every detail of this code to follow the migration workflow. It's included to represent the kind of architecture-specific SIMD logic commonly found in real-world applications. {{% /notice %}}
 
 The following example shows a matrix multiplication implementation using x86 AVX2 intrinsics. This is representative of performance-critical code found in compute benchmarks and scientific workloads. Copy this code into a file named `matrix_operations.cpp`:
 
@@ -170,7 +172,9 @@ int main() {
 }
 ```
 
-## The Arm Migration Prompt File
+Prompt files act as executable migration playbooks. They encode a repeatable process that the AI can follow reliably, rather than relying on one-off instructions or guesswork.
+
+## The Arm migration prompt file
 
 To automate migration, you can define a prompt file that instructs the AI assistant how to analyze and transform the project using the Arm MCP Server. Prompt files encode best practices, tool usage, and migration strategy, allowing the AI assistant to operate fully autonomously through complex multi-step workflows.
 
@@ -203,7 +207,7 @@ Provide a summary of the changes you made and how they'll improve the project.
 ```
 This prompt file encodes best practices, tool usage, and migration strategy, allowing the AI assistant to operate fully agentically.
 
-## Running the Migration
+## Running the migration
 
 With the prompt file in place and the Arm MCP Server connected, invoke the migration workflow from your AI assistant:
 

content/learning-paths/servers-and-cloud-computing/arm-mcp-server/4-agentic-systems.md

@@ -6,17 +6,21 @@ weight: 5
 layout: learningpathall
 ---
 
-## Agentic AI Systems for Migration
+## Set up an agent workflow
 
 Different AI coding tools provide different mechanisms for defining persistent instructions, such as prompt files or configuration documents. While the configuration details vary by tool, the goal remains the same: provide the AI with clear, structured instructions so it can use the Arm MCP Server effectively and carry out multi-step migration workflows autonomously.
 
 This section shows how to set up Arm migration workflows in popular agentic AI systems. You'll see that the core migration logic stays consistent across platforms, but each tool has its own format for defining these instructions.
 
-## Kiro Steering Documents
+{{% notice Note %}}
+The migration instructions below are the same workflow you used in the previous section. Each AI tool simply wraps those instructions in a different format.
+{{% /notice %}}
+
+## Set up Kiro steering documents
 
 [Kiro](https://kiro.dev/) uses "steering documents" - markdown files stored in `.kiro/steering/` that provide persistent context to the AI. You can configure steering documents with different inclusion modes to control when and how the instructions are applied.
 
-### Create Arm Migration Steering Document
+### Create Arm migration steering document
 
 To set up Arm migration in Kiro, create the following file at `.kiro/steering/arm-migration.md`:
 
@@ -48,11 +52,11 @@ Provide a summary of the changes you made and how they'll improve the project.
 
 Reference this steering document in chat with `#arm-migration`.
 
-## OpenAI Codex Prompt Files
+## OpenAI Codex prompt files
 
 [OpenAI Codex](https://openai.com/codex/) uses markdown prompt files stored in `~/.codex/prompts/` or `$CODEX_HOME/prompts/`. The filename determines the command name you'll use to invoke the prompt.
 
-### Create Arm Migration Prompt
+### Create Arm migration prompt
 
 Create the following file at `~/.codex/prompts/arm-migrate.md`:
 
@@ -82,7 +86,7 @@ If you have good versions to update for the Dockerfile, requirements.txt, and ot
 Provide a summary of the changes you made and how they'll improve the project.
 ```
 
-### Running the Codex Prompt
+### Running the Codex prompt
 
 Invoke the prompt with:
 

content/learning-paths/servers-and-cloud-computing/arm-mcp-server/_index.md

@@ -3,13 +3,14 @@ title: Automate x86-to-Arm application migration using Arm MCP Server
 
 minutes_to_complete: 20
 
-who_is_this_for: This is an advanced topic for software developers who want to use AI-powered tools to migrate x86 applications to Arm-based cloud instances.
+who_is_this_for: This is an advanced topic for developers who want to use AI-powered tools to migrate x86 applications to Arm-based cloud instances.
 
 learning_objectives:
-    - Understand how the Arm MCP Server enables AI developer tools to assist with cloud migration
-    - Use AI prompts to check Docker images for Arm compatibility
-    - Perform a fully automated C++ application migration using prompt files with the Arm MCP Server
-    - Configure different agentic systems to automate Arm migration workflows
+  - Explain how the Arm MCP Server enables AI-driven x86-to-Arm migration workflows
+  - Use AI-assisted checks to inspect Docker images for Arm compatibility
+  - Automate the migration of x86-specific C++ code to Arm using structured prompt files
+  - Validate and run a migrated Dockerized C++ application on Arm-based systems
+  - Configure AI agents to reuse the same migration workflow across different tools
 
 prerequisites:
     - An AI-powered IDE such as VS Code with agentic tools like GitHub Copilot, Claude Code, Cursor, or similar