Refine documentation for Arm SoC Migration Power, enhancing clarity and consistency across multiple sections

Author: madeline-underwood

content/learning-paths/servers-and-cloud-computing/arm-soc-migration-learning-path/_index.md

@@ -1,21 +1,22 @@
 ---
-title: Migrate applications between Arm platforms with AI assistance
+title: Migrate applications between Arm platforms using Kiro Arm SoC Migration Power
 
 minutes_to_complete: 60
 
-who_is_this_for: This is an advanced topic for developers migrating applications between Arm platforms using AI-assisted tooling with Kiro's Arm SoC Migration Power. You will learn a practical, repeatable migration workflow through an example that moves an application from the cloud to the edge — from AWS Graviton (Neoverse-based) to Raspberry Pi 5 (Cortex-A based).
+who_is_this_for: This is an advanced topic for experienced developers who need to migrate applications between Arm-based platforms using AI-assisted tooling. You will work through a structured, repeatable migration workflow using Kiro Arm SoC Migration Power, moving an application from AWS Graviton3 (Neoverse) to Raspberry Pi 5 (Cortex-A). The techniques apply broadly to cloud-to-edge and cross-architecture migrations across the Arm ecosystem.
 
 learning_objectives:
-    - Install and configure Kiro's Arm SoC Migration Power
-    - Understand a structured migration workflow applicable across Arm platforms
-    - Use AI-guided migration to identify platform-specific and hardware-dependent code
-    - Create Hardware Abstraction Layers with Power assistance
-    - Validate and verify migrations with automated analysis
+   - Install and configure Kiro Arm SoC Migration Power
+   - Apply a structured migration workflow across Arm platforms
+   - Identify platform-specific and hardware-dependent code using AI-guided analysis
+   - Implement hardware abstraction layers to isolate platform-specific dependencies
+   - Validate and verify the migrated application using automated analysis
 
 prerequisites:
-    - Access to a source and target Arm platforms (the example uses AWS Graviton3 and Raspberry Pi 5)
-    - Basic understanding of C programming
-    - Familiarity with embedded systems, Linux environments, or cloud computing concepts
+    - Access to both source and target Arm platforms (for example, AWS Graviton3 and Raspberry Pi 5)
+    - Working knowledge of C programming
+    - Familiarity with Linux development environments and basic embedded or cloud deployment concepts
+    - Experience building applications with GCC and CMake
 
 author: Daniel Schleicher
 
@@ -36,7 +37,7 @@ tools_software_languages:
 
 further_reading:
     - resource:
-        title: Kiro ARM SoC Migration Power Documentation
+        title: Kiro Arm SoC Migration Power Documentation
         link: https://kiro.dev/powers/arm-soc-migration
         type: documentation
     - resource:

content/learning-paths/servers-and-cloud-computing/arm-soc-migration-learning-path/graviton-development.md

@@ -10,21 +10,21 @@ layout: learningpathall
 
 In this section, you will build and validate the application on the source Arm platform before performing any migration steps.
 
-This example uses AWS Graviton3 as the source platform, however the same principles apply to any Arm-to-Arm migration scenario (for example, from Raspberry Pi 4 to Pi 5, or from i.MX8 to Jetson).
+This example uses AWS Graviton3 as the source platform. The same principles apply to any Arm-to-Arm migration scenario, such as Raspberry Pi 4 to Raspberry Pi 5 or i.MX8 to Jetson.
 
-### Download the Application (Local Machine)
+### Download the application (local machine)
 
-Download the `sensor-monitor` application to your local machine (where Kiro IDE is installed).
+Download the `sensor-monitor` application to your local machine (where Kiro IDE is installed). You inspect the project locally, then build and validate it on the Graviton3 instance.
 
 ```bash
 wget https://github.com/ArmDeveloperEcosystem/arm-learning-paths/raw/main/content/learning-paths/servers-and-cloud-computing/arm-soc-migration-learning-path/projects/sensor-monitor.tar.gz
 tar -xzf sensor-monitor.tar.gz
 cd sensor-monitor
 ```
 
-The package includes the complete source code, a Makefile, and platform-specific implementations. You will analyze and migrate this code using the ARM SoC Migration Power.
+The archive includes the complete source code, a Makefile, and platform-specific implementations. You will analyze and migrate this code using the Arm SoC Migration Power.
 
-### Upload to the Graviton Instance for Testing
+### Upload to the Graviton instance for testing
 
 Before migrating, verify that the application builds and runs correctly on the source Arm platform.
 
@@ -34,7 +34,7 @@ Upload the archive to the Graviton instance:
 scp -i graviton-migration-key.pem sensor-monitor.tar.gz ec2-user@$(aws ec2 describe-instances --filters "Name=tag:Name,Values=graviton-migration-source" "Name=instance-state-name,Values=running" --query 'Reservations[0].Instances[0].PublicIpAddress' --output text):~
 ```
 
-### Build and Test on Graviton
+### Build and test on Graviton
 
 Connect to the instance:
 
@@ -51,16 +51,16 @@ make
 ./sensor_monitor
 ```
 
-If successful, the application compiles with GCC (AArch64 target) and displays simulated sensor readings.
+If successful, the application compiles for AArch64 using GCC and displays simulated sensor readings.
 
 This confirms:
 
 - The toolchain is functional
 - The application builds cleanly on Arm64 Linux
 
-This state becomes your baseline reference for migration validation.
+This validated build becomes your migration baseline. Any functional differences after migration can be compared against this known-good state.
 
-### Application Overview
+### Application overview
 
 The `sensor-monitor` application demonstrates a common embedded/edge design pattern: business logic separated from platform-specific hardware interaction.
 

content/learning-paths/servers-and-cloud-computing/arm-soc-migration-learning-path/migration.md

@@ -8,14 +8,14 @@ layout: learningpathall
 
 ## Use Arm SoC Migration Power for AI-guided migration
 
-In this section you will learn how to use the Arm SoC Migration Power to migrate your application between Arm-based platforms. The example demonstrates migration from:
+In this section, you use the Arm SoC Migration Power to migrate your application between Arm-based platforms. The example demonstrates migration from:
 
 - **Source:** AWS Graviton3 (Neoverse-V1, Arm64 Linux, cloud deployment)
 - **Target:** Raspberry Pi 5 (BCM2712, Cortex-A76, edge deployment)
 
-However, the workflow applies to any Arm-to-Arm migration.
+However, the workflow applies to any Arm-to-Arm migration. The migration process follows four phases: discovery, architecture analysis, abstraction design, and platform-specific implementation.
 
-For each step below, an example prompt for the Graviton-to-Pi-5 scenario is provided alongside a general pattern you can adapt for other platform pairs. Being explicit in your prompts improves the quality of the Power's architectural reasoning.
+For each step below, an example prompt for the Graviton-to-Pi-5 scenario is provided alongside a general pattern you can adapt for other platform pairs. Being explicit in your prompts improves the quality and precision of the Power’s architectural analysis.
 
 ### Initiate migration
 
@@ -37,7 +37,7 @@ The application uses [source-specific features] and needs [target-specific featu
 
 ### Discovery phase
 
-The Power will prompt you for information about your platforms:
+Provide detailed information about both platforms:
 
 **Example for Graviton → Raspberry Pi 5:**
 ```
@@ -58,7 +58,7 @@ The general pattern for other Arm-based platform migrations:
 Scan my codebase for [source platform]-specific code that needs migration to [target platform].
 Focus on [platform-specific features].
 ```
-This step ensures migration is systematic rather than ad hoc.
+This ensures the migration is systematic, traceable, and grounded in explicit platform assumptions.
 
 
 ### Architecture analysis
@@ -116,7 +116,7 @@ The general pattern for other Arm-based platform migrations:
 Help me implement [feature] for [target platform]. Show me how to [specific requirement].
 ```
 
-The power will provide target platform-specific code. Example for `platform/bcm2712/sensor_bcm2712.c`:
+The Power will provide target platform-specific code. Example for `platform/bcm2712/sensor_bcm2712.c`:
 
 ```c
 #include "hal/spi.h"
@@ -137,6 +137,7 @@ void sensor_cleanup(void) {
     spi_cleanup();
 }
 ```
+Review all generated or refactored code carefully to ensure correctness, performance, and alignment with your hardware constraints.
 
 ### Update the build system
 
@@ -154,7 +155,7 @@ Update my build system for [source platform]/[target platform] support with prop
 platform selection and cross-compilation.
 ```
 
-The power will generate a platform-aware build configuration. Example `CMakeLists.txt`:
+The Power will generate a platform-aware build configuration. Example `CMakeLists.txt`:
 
 ```cmake
 cmake_minimum_required(VERSION 3.16)

content/learning-paths/servers-and-cloud-computing/arm-soc-migration-learning-path/setup.md

@@ -6,7 +6,7 @@ weight: 2
 layout: learningpathall
 ---
 
-## Install and configure Kiro's Arm SoC Migration Power
+## Install and configure Kiro Arm SoC Migration Power
 
 In this section, you will install Kiro IDE, enable Kiro Arm SoC Migration Power, and prepare the development environment.
 
@@ -41,8 +41,11 @@ The Arm SoC Migration Power extends Kiro with specialized knowledge and tools fo
 
 ### Verify installation
 
-After installation, test the Power by entering: "I just installed the arm-soc-migration power and want to use it."
+After installation, enter the following prompt in Kiro:
 
+```text
+I just installed the Arm SoC Migration Power and want to use it.
+```
 The Power should respond and guide you through any additional setup steps.
 
 It supports migrations across a wide range of Arm-based platforms, including:
@@ -87,9 +90,9 @@ docker --version
 Ensure Docker is running before using the Arm SoC Migration Power. The Power will automatically pull and run the Arm MCP server container when needed.
 {{% /notice %}}
 
-### Launch AWS Graviton instance (source platform)
+### Launch AWS Graviton3 instance (source platform)
 
-You will use an AWS Graviton instance as the source platform in this migration scenario.
+You will use an AWS Graviton3 instance as the source platform in this migration scenario.
 
 {{% notice Note %}}
 Before proceeding, ensure you are authenticated with the AWS CLI. Follow the [AWS CLI install guide](/install-guides/aws-cli/) if you haven't configured credentials yet.
@@ -111,17 +114,24 @@ aws ec2 create-key-pair --key-name graviton-migration-key \
 chmod 400 graviton-migration-key.pem
 ```
 
-Create the security group and allow SSH access:
+Create the security group and allow SSH access. Restrict SSH access to your current public IP address.
 
 ```bash
 SG_ID=$(aws ec2 create-security-group \
   --group-name graviton-migration-sg \
   --description "Security group for Arm SoC migration" \
   --query 'GroupId' --output text)
+
+MY_IP=$(curl -s https://checkip.amazonaws.com)
+
 aws ec2 authorize-security-group-ingress \
-  --group-id $SG_ID --protocol tcp --port 22 --cidr 0.0.0.0/0
+  --group-id $SG_ID \
+  --protocol tcp \
+  --port 22 \
+  --cidr ${MY_IP}/32
 ```
 
+
 Find the latest Amazon Linux 2023 arm64 AMI and launch the instance:
 
 ```bash
@@ -146,11 +156,11 @@ echo "ssh -i graviton-migration-key.pem ec2-user@$(aws ec2 describe-instances --
 
 Copy and execute the output command to connect to your instance.
 
-### Install development tools on the Graviton instance
+### Install development tools on the Graviton3 instance
 
-The Graviton instance needs development tools to compile the sensor-monitor example application.
+The Graviton3 instance needs development tools to compile the sensor-monitor example application.
 
-Once connected to your Graviton instance, install the required tools:
+Once connected to your Graviton3 instance, install the required tools:
 
 ```bash
 sudo dnf install -y gcc make wget tar
@@ -161,8 +171,8 @@ sudo dnf install -y gcc make wget tar
 In this section:
 
 - You installed Kiro IDE and the Arm SoC Migration Power
-- You launched an AWS Graviton3 instance as your source platform
+- You provisioned an AWS Graviton3 instance as your source platform
 - You installed the build tools needed for the migration example
 
-In the next section, you'll build and test the sensor-monitor application on the Graviton instance to establish a validated baseline before migration.
+In the next section, you'll build and test the sensor-monitor application on the Graviton3 instance to establish a validated baseline before migration.
 

content/learning-paths/servers-and-cloud-computing/arm-soc-migration-learning-path/validation.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Validate migration using the Power's testing recommendations
 
-Migration is not complete until the application is validated on both source and target platforms.
+Migration is not complete until the application is validated on both source and target platforms under realistic conditions.
 
 In this section, you will use the Arm SoC Migration Power's testing recommendations to:
 
@@ -32,7 +32,7 @@ The general pattern for other Arm-based platforms:
 Help me verify my [source platform] build still works after adding [target platform] support.
 ```
 
-Follow the power's guidance. Example for Graviton:
+Follow the Power's guidance. Example for Graviton:
 
 ```bash
 cmake -DTARGET_PLATFORM=GRAVITON -B build-graviton
@@ -79,7 +79,7 @@ The general pattern for other Arm-based platforms:
 What tests should I run on [target platform] to validate the migration from [source platform]?
 ```
 
-The power will recommend platform-appropriate tests. Example for Raspberry Pi 5:
+The Power will recommend platform-appropriate tests. Example for Raspberry Pi 5:
 - GPIO functionality tests
 - SPI communication validation
 - Real sensor reading verification
@@ -106,7 +106,7 @@ The general pattern for other Arm-based platforms:
 Compare performance between [source platform] and [target platform] for my application.
 ```
 
-The power will analyze platform-specific characteristics. Example analysis:
+The Power will analyze platform-specific characteristics. Example analysis:
 - CPU performance differences
 - Memory usage comparison
 - I/O timing characteristics