first pass

Author: anupras-mohapatra-arm

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/2-environment-setup.md

@@ -1,20 +1,20 @@
 ---
-title: Environment setup
+title: Set up an Arm-based environment
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-# Environment setup
+## Set up a Microsoft Azure virtual machine powered by Cobalt 100
 
 Set up an Arm Cobalt environment first, then keep your toolchain and runtime configuration stable across all test runs. This creates a reliable Arm baseline for migration and tuning work.
 
-Start with the official [Azure Cobalt setup guide](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cobalt/) and complete VM provisioning there first.
+Start with the [Azure Cobalt Learning Path](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cobalt/) and complete VM provisioning.
 
 This path was validated with Ubuntu 24.04 LTS on Azure Cobalt in `westus2` (example VM size: `Standard_D2ps_v6`, 2 vCPUs).
 
-## Install tools on Cobalt VM
+### Install tools on Cobalt VM
 
 Install the toolchain on the Cobalt VM before building and testing. The commands install the Linux packages used throughout this Learning Path: source control, HTTP validation, JSON inspection, Python for the endpoint tester, package archive inspection, Docker, and the .NET 9 SDK from the Ubuntu backports feed.
 
@@ -46,11 +46,11 @@ aarch64
 Docker version ...
 ```
 
-If you are upgrading from an older .NET version before migrating to Cobalt, you can use [GitHub Copilot modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization/overview) to assess the project and guide the upgrade. In Visual Studio Code, open Copilot Chat and use `@modernize-dotnet`; in Visual Studio, use the Modernize action from Solution Explorer.
+If you're upgrading from an older .NET version before migrating to Cobalt, use [GitHub Copilot modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization/overview) to assess the project and guide the upgrade. In Visual Studio Code, open Copilot Chat and use `@modernize-dotnet`; in Visual Studio, use the Modernize action from Solution Explorer.
 
-## PostgreSQL prerequisite for nopCommerce install
+#### Enable citext to satisfy PostgreSQL prerequisite 
 
-nopCommerce defaults to SQL Server, but this learning path uses PostgreSQL for Arm validation. For PostgreSQL installs, `citext` is required before migration/installation. Without it, installer migrations fail with `type "citext" does not exist` (captured in local test artifacts).
+nopCommerce defaults to SQL Server, but you'll use PostgreSQL for Arm validation. For PostgreSQL installs, you need `citext` before migration or installation. Without it, installer migrations fail with `type "citext" does not exist` (captured in local test artifacts).
 
 Create PostgreSQL and enable `citext` before running the installer. The database runs in Docker on the Cobalt VM so the nopCommerce app can connect to `127.0.0.1:5432` during the local validation phase. Replace the password value before running the command.
 
@@ -70,3 +70,9 @@ docker exec nop-postgres psql -U nop -d nopcommerce \
 ```
 
 The `docker exec` command should print `CREATE EXTENSION`. If it prints `NOTICE: extension "citext" already exists, skipping`, the database is already prepared and you can continue.
+
+## What you've accomplished and what's next
+
+You've set up an Arm-based environment by creating a Microsoft Azure VM powered by Cobalt 100 and installing the toolchain necessary for migration. 
+
+Next, you'll create a reproducable baseline to use for benchmarking.

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/3-checkout-build-baseline.md

@@ -1,18 +1,18 @@
 ---
-title: Build and baseline
+title: Create an Arm baseline before optimization
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-# Build and baseline
+## Build and baseline
 
 Create a reproducible Arm baseline before optimization work. This page pins source, verifies a clean build, and captures a representative endpoint baseline so later changes can be measured against a known control.
 
-## Clone and pin the source
+### Clone and pin the source
 
-Pinning the exact tag and commit avoids silent drift in dependencies and behavior. Run these commands on the Cobalt VM. The later commands assume you are in the `nopCommerce` repository root unless a section says otherwise.
+Pinning the exact tag and commit avoids silent drift in dependencies and behavior. Run the following commands on the Cobalt virtual machine (VM):
 
 ```bash
 git clone https://github.com/nopSolutions/nopCommerce.git
@@ -21,16 +21,17 @@ git fetch --tags --prune
 git checkout release-4.90.3
 git rev-parse --short=10 HEAD   # expect 9beda11c42
 ```
+The later commands assume you're in the `nopCommerce` repository root unless stated otherwise.
 
 If you open a new terminal later, return to the same repository root before running commands:
 
 ```bash
 cd ~/nopCommerce  # replace with your clone path if different
 ```
 
-## Restore and build on Arm
+### Restore and build on Arm
 
-Run the restore and build on the Arm-based VM to establish a native Arm baseline. Restoring first separates package resolution problems from compilation problems, and `--no-restore` makes the build validate the already restored dependency graph.
+Run restore and build on the Arm-based VM to establish a native Arm baseline. Restoring first separates package resolution problems from compilation problems, and `--no-restore` makes the build validate the already restored dependency graph.
 
 ```bash
 # Restore dependencies first so build failures are easier to triage.
@@ -40,7 +41,7 @@ dotnet restore src/Presentation/Nop.Web/Nop.Web.csproj
 dotnet build src/Presentation/Nop.Web/Nop.Web.csproj -c Release --no-restore
 ```
 
-## Start and install nopCommerce
+### Start and install nopCommerce
 
 Start the app locally and complete installer setup with PostgreSQL. Run this command in one terminal and leave it running; `dotnet run` hosts the web application and keeps the terminal attached to the server logs.
 
@@ -73,9 +74,9 @@ curl -s -o /dev/null -w 'install=%{http_code}\n' http://127.0.0.1:5000/install
 
 Expected after successful install: `root=200`, `install=302`.
 
-## Baseline methodology
+### Run the baseline
 
-Do not benchmark `/install`. Baseline stable storefront paths first, then add cart and attribute-change routes only after you know the valid product IDs, attribute IDs, request method, and anti-forgery token behavior for your installed store.
+Don't benchmark `/install`. Baseline stable storefront paths first, then add cart and attribute-change routes only after you know the valid product IDs, attribute IDs, request method, and anti-forgery token behavior for your installed store.
 
 - `/`
 - `/search/`
@@ -211,7 +212,7 @@ python3 test_nopcommerce_endpoints.py \
 
 The command prints the per-route summary and writes the raw measurements to `arm_before.json`. Keep that JSON file unchanged; it is the baseline artifact used by the tuning step.
 
-## Baseline quality rules
+#### Baseline quality rules
 
 Use these rules before you compare any optimization result:
 
@@ -221,3 +222,11 @@ Use these rules before you compare any optimization result:
 - Capture raw JSON for every run and compare medians, not single outliers.
 
 This baseline process becomes the control for every later tuning or code-change decision.
+
+## What you've accomplished and what's next
+
+You've now created a baseline before migrating the application. 
+
+Next, you'll make note of dependencies before migration. 
+
+

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/4-dependency-mapping-manifests.md

@@ -1,32 +1,32 @@
 ---
-title: Audit dependencies
+title: Run dependency discovery before migration
 weight: 4
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-# Audit dependencies
+## Audit application ependencies
 
-Run dependency discovery before migration changes so you understand direct references, transitive risk, and hidden native payloads. This avoids late surprises when deploying to Arm.
+Run dependency discovery before migration changes so you understand direct references, transitive risk, and hidden native payloads. By doing so, you'll avoid late surprises when deploying to Arm.
 
-### 1. Map direct references
+### Map direct references
 
 Start from the `nopCommerce` repository root. Project-level references show what the app explicitly depends on before NuGet expands the graph. The command searches project files under `src` and prints file names and line numbers so you can jump directly to the owning project.
 
 ```bash
 rg -n "<PackageReference|<ProjectReference" src
 ```
 
-### 2. List transitive dependencies
+### List transitive dependencies
 
 Enumerate the full dependency graph for the web entry point. Transitive packages often carry architecture-sensitive constraints, so review the output for runtime-specific package names, native library packages, image processing libraries, database providers, and platform-specific assets.
 
 ```bash
 dotnet list src/Presentation/Nop.Web/Nop.Web.csproj package --include-transitive
 ```
 
-### 3. Generate an SBOM
+### Generate an SBOM
 
 Generate an SBOM so you can track all components, versions, and exposure surface as a first-class migration artifact. While not strictly necessary for migration purposes, this is a best practice that will save your team time down the road. You can also give this SBOM to an LLM to extract insights about your codebase for you.
 
@@ -40,7 +40,7 @@ dotnet-CycloneDX src/Presentation/Nop.Web/Nop.Web.csproj -o sbom/ -rs -F Json
 
 The `-rs` option includes project references, and `-F Json` writes JSON output that is easier to diff in CI. If tool installation is blocked, treat `dotnet list --include-transitive` plus `*.deps.json` evidence as a temporary fallback, not the final state.
 
-### 4. Inspect package internals for native payloads
+### Inspect package internals for native payloads
 
 Inspect package contents directly when a dependency looks architecture-sensitive. NuGet package folders are usually lower case on Linux, so set `PACKAGE_ID` to the folder name under `~/.nuget/packages` and `PACKAGE_VERSION` to the version you want to inspect.
 
@@ -57,7 +57,7 @@ unzip -l "$(basename "$NUPKG")" | rg "runtimes/|native/"
 
 If the command prints `runtimes/linux-arm64`, the package already carries an Arm Linux asset. If it prints only `linux-x64`, `win-x64`, or another non-Arm runtime, trace whether that asset is used by nopCommerce before you treat the dependency as portable. If there is no output, the package does not advertise runtime or native payload directories in the `.nupkg`.
 
-## Dependency cascade rule
+### Dependency cascade rule
 
 Treat dependencies as a chain, not isolated items:
 
@@ -66,3 +66,9 @@ Treat dependencies as a chain, not isolated items:
 - Library B is architecture-sensitive
 
 You must resolve B first, then validate A, then validate the app.
+
+## What you've accomplished and what's next
+
+You've reviewed application dependencies to understand what can change when you migrate to Arm.
+
+Next, you'll explore options to containerize the application. 

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/5-containerization.md

@@ -1,16 +1,18 @@
 ---
-title: Containerize the application
+title: Choose between options to containerize the application
 weight: 5
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-# Containerize the application
+## Containerize the application
 
-Containerization should preserve reproducibility across architectures. This page shows practical paths for Dockerfile-based builds and .NET SDK container publish, with guardrails for multi-architecture delivery.
+Containerization should preserve reproducibility across architectures. The following are practical paths for Dockerfile-based builds and .NET SDK container publish, with guardrails for multi-architecture delivery.
 
-### 1. Dockerfile path
+Use the Dockerfile workflow as the default migration path for nopCommerce until your SDK-published image has the same Linux runtime dependencies and smoke-test results. Use SDK publish when you want MSBuild-owned image metadata and have a repeatable plan for the native packages that the Dockerfile previously installed.
+
+### Dockerfile path
 
 Run a Dockerfile build with `buildx` from the repository root when you want to preserve the upstream nopCommerce Dockerfile behavior. This is the safest first containerization path because the Dockerfile installs runtime packages used by nopCommerce on Linux, including globalization and image-processing dependencies.
 
@@ -32,7 +34,7 @@ docker buildx build --platform linux/amd64,linux/arm64 -t "$IMAGE" --push .
 docker buildx imagetools inspect "$IMAGE"
 ```
 
-### 2. .NET SDK publish path (single architecture)
+### Single architecture .NET SDK publish path
 
 Use SDK publish when you want tighter integration with .NET build settings and fewer custom Docker steps. For nopCommerce, treat this as a validation path until you have confirmed that the generated image includes the Linux native packages your store needs. SDK publish creates the container image, but it does not run `apk add` or `apt-get install` steps like a Dockerfile does.
 
@@ -55,7 +57,7 @@ docker image inspect nopcommerce:arm64-test --format '{{.Architecture}}'
 
 The expected output is `arm64`.
 
-### 3. .NET SDK multi-arch path
+### Multi-arch .NET SDK publish path
 
 Define runtime identifiers and multi-arch container runtime identifiers in the project file, then publish once. Add this metadata only after you have decided where nopCommerce's Linux runtime dependencies will live. If you use SDK publish for production, move those dependencies into a custom base image or another repeatable image-build step before replacing the Dockerfile workflow.
 
@@ -78,16 +80,21 @@ dotnet publish src/Presentation/Nop.Web/Nop.Web.csproj -c Release /t:PublishCont
 
 This is the scalable path for one image definition across both architectures, but the generated image still needs the same smoke test as the Dockerfile image: start the container, connect it to PostgreSQL, and verify storefront routes before you promote it.
 
-## SDK version guardrail
+#### SDK version guardrail
 
 Before choosing the SDK publish path for multi-architecture images, check the SDK version used by CI and by developer workstations:
 
 ```bash
 dotnet --version
 ```
 
-If you cannot use a .NET SDK version that supports multi-RID container publishing, or if SDK publish does not produce the multi-architecture image index you need, use the `docker buildx build --platform linux/amd64,linux/arm64` workflow instead. Multi-RID container publishing starts with .NET SDK versions 8.0.405, 9.0.102, and 9.0.2xx. The nopCommerce `release-4.90.3` source pins SDK `9.0.100` in `global.json` with feature-band roll-forward, so confirm the actual SDK selected by CI is new enough before relying on SDK multi-arch publish.
+If you can't use a .NET SDK version that supports multi-RID container publishing, or if SDK publish does not produce the multi-architecture image index you need, use the `docker buildx build --platform linux/amd64,linux/arm64` workflow instead. 
 
-## Recommendation
+Multi-RID container publishing starts with .NET SDK versions `8.0.405`, `9.0.102`, and `9.0.2xx`. The nopCommerce `release-4.90.3` source pins SDK `9.0.100` in `global.json` with feature-band roll-forward, so confirm the actual SDK selected by CI is new enough before relying on SDK multi-arch publish.
 
-Use the Dockerfile workflow as the default migration path for nopCommerce until your SDK-published image has the same Linux runtime dependencies and smoke-test results. Use SDK publish when you want MSBuild-owned image metadata and have a repeatable plan for the native packages that the Dockerfile previously installed.
+
+## What you've accomplished and what's next
+
+You've learned about different containerization paths for the .NET application and containerized the app. 
+
+Next, you'll tune application performance. 

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/6-deploy-verify-cobalt.md

@@ -1,16 +1,16 @@
 ---
-title: Performance tuning on Cobalt
+title: Tune the performance of the .NET application on Azure
 weight: 6
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-# Performance tuning on Cobalt
+## Apply performance tuning changes
 
 Treat tuning as an experiment pipeline, not a one-shot tweak. On Arm, apply changes in a controlled sequence, measure with fixed workloads, and keep only optimizations that repeatedly improve your target metrics.
 
-## Tuned run configuration
+### Configure a tuned run
 
 Start with a conservative runtime profile that is commonly effective for server workloads. Keep these settings outside the application code at first so you can switch profiles without rebuilding.
 
@@ -35,7 +35,7 @@ dotnet run -c Release --no-build --urls http://0.0.0.0:5000
 
 Increase `DOTNET_ThreadPool_ForceMinWorkerThreads` only when traces or load-test data show thread-pool starvation. Keep `DOTNET_EnableDiagnostics=0` for final measurement runs only; remove it when you need `dotnet-trace`, `dotnet-counters`, or profiler-based evidence.
 
-### Optional spin-wait experiment for .NET 8, 9, and 10
+#### (Optional) Run spin-wait experiment for .NET 8, 9, and 10
 
 If the workload burns CPU while waiting for short-lived thread-pool work, test disabling the thread-pool unfair semaphore spin limit:
 
@@ -45,7 +45,7 @@ export DOTNET_ThreadPool_UnfairSemaphoreSpinLimit=0
 
 Treat this as an experiment, not a default. Turning off spin waiting can reduce wasted CPU on small instances or oversubscribed containers, but it can also increase wake-up latency and reduce peak throughput. Validate it separately from the base tuned profile by changing only this variable between trials.
 
-### Tiered PGO and ReadyToRun optimize different phases
+### Optimize tiered PGO and ReadyToRun 
 
 `DOTNET_TieredPGO=1` and `DOTNET_ReadyToRun=1` are not the same optimization:
 
@@ -73,7 +73,7 @@ jq '.summary' arm_before.json
 jq '.summary' arm_after.json
 ```
 
-## Validation rules for credible tuning gains
+### Validation rules for credible tuning gains
 
 Use these rules before adopting a tuning profile:
 
@@ -83,15 +83,21 @@ Use these rules before adopting a tuning profile:
 - Require improvement in both throughput and p95 latency, not just one.
 - Set a minimum practical threshold (for example, >=5% median gain) before rollout.
 
-## Instance-size tradeoffs
+#### Instance-size tradeoffs
 
 Do not assume the same profile wins on every Azure Cobalt VM size. Smaller instances often benefit from lower CPU burn and predictable p95 latency. Larger instances often benefit from higher concurrency, but can expose GC, database, and shared-resource contention. Compare throughput, p95/p99 latency, CPU utilization, and error rate for each instance size before keeping a tuning profile.
 
-## Interpretation
+### Considerations for interpreting metric improvements
+
+When interpeting metric improvements, consider the following:
 
 - If only one metric improves while p95 or error rate regresses, do not treat the change as a win.
 - If run-to-run variation is near the observed delta, treat it as noise.
-- Keep architecture-specific profiles separate; do not force one profile onto all architectures.
+- Keep architecture-specific profiles separate. Don't force one profile onto all architectures.
+
+## What you've accomplished and what's next
+
+You've applied performance tuning changes to the .NET application. 
 
+Next, you'll use the Arm MCP Server to optimize application performance.
 
-Use this page as a tuning workflow template, then validate with your production-like traffic profile before rollout.