edit for clarity, remove unneeded sections

Author: JoeStech

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

@@ -6,25 +6,17 @@ weight: 2
 layout: learningpathall
 ---
 
-Create two VMs in the same Azure region with matching OS and tooling so differences are attributable to architecture, not configuration drift.
+# Environment setup
 
-This path was validated with Ubuntu 24.04 LTS VMs in `westus2`:
+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.
 
-| | x86 | Arm |
-|---|---|---|
-| **VM size** | Standard_D2s_v6 | Standard_D2ps_v6 |
-| **vCPUs** | 2 | 2 |
+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.
 
-## Log in and create VMs
+This path was validated with Ubuntu 24.04 LTS on Azure Cobalt in `westus2` (example VM size: `Standard_D2ps_v6`, 2 vCPUs).
 
-```bash
-az login --use-device-code
-az account set --subscription <your-subscription>
-```
-
-Create both VMs in the same resource group and region.
+## Install tools on Cobalt VM
 
-## Install tools on each VM
+Install the toolchain on the Cobalt VM before building and testing.
 
 ```bash
 sudo apt-get update -y
@@ -38,37 +30,31 @@ sudo apt-get install -y dotnet-sdk-9.0
 
 Verify:
 
+Confirm architecture and tool versions before proceeding.
+
 ```bash
 uname -m
 dotnet --version
 docker --version
 ```
 
-Expected output: `x86_64` on the x86 VM, `aarch64` on the Arm VM. Both should report the same .NET SDK version (9.0.x).
+Expected output: `Arm` (kernel strings may still show architecture-specific values). Ensure the .NET SDK version is 9.0.x.
 
 ## PostgreSQL prerequisite for nopCommerce install
 
-nopCommerce migrations on PostgreSQL require the `citext` extension. Create it before running the installer:
+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).
+
+Create PostgreSQL and enable `citext` before running the installer:
 
 ```bash
+# Start PostgreSQL for local validation.
 docker run -d --name nop-postgres \
   -e POSTGRES_USER=nop \
   -e POSTGRES_PASSWORD=<password> \
   -e POSTGRES_DB=nopcommerce \
   -p 5432:5432 postgres:16
 
+# Enable the extension required by nopCommerce migrations.
 docker exec nop-postgres psql -U nop -d nopcommerce \
   -c "CREATE EXTENSION IF NOT EXISTS citext;"
 ```
-
-## Optional: script-driven remote execution
-
-```bash
-az vm run-command invoke \
-  -g <resource-group> \
-  -n <vm-name> \
-  --command-id RunShellScript \
-  --scripts @./your-test-script.sh
-```
-
-This was used to run identical commands on both VMs.

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

@@ -6,10 +6,14 @@ weight: 3
 layout: learningpathall
 ---
 
-Pin nopCommerce to a reproducible release, build on both architectures, and capture a baseline that includes core storefront paths.
+# 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
 
+Pinning the exact tag and commit avoids silent drift in dependencies and behavior.
+
 ```bash
 git clone https://github.com/nopSolutions/nopCommerce.git
 cd nopCommerce
@@ -18,74 +22,73 @@ git checkout release-4.90.3
 git rev-parse --short=10 HEAD   # expect 9beda11c42
 ```
 
-## Restore and build
+## Restore and build on Arm
+
+Run on the Arm VM to establish a native Arm baseline.
 
 ```bash
+# Restore dependencies first so build failures are easier to triage.
 dotnet restore src/Presentation/Nop.Web/Nop.Web.csproj
+
+# Build release binaries without re-restoring packages.
 dotnet build src/Presentation/Nop.Web/Nop.Web.csproj -c Release --no-restore
 ```
 
-## Start the application
+## Start and install nopCommerce
+
+Start the app locally and complete installer setup with PostgreSQL.
 
 ```bash
 cd src/Presentation/Nop.Web
 dotnet run -c Release --no-build --urls http://0.0.0.0:5000
 ```
 
-## Baseline methodology
-
-Do not rely on `/install` alone. Baseline at least:
-
-- Home page
-- Search
-- Product page
-- Cart
-- Checkout
-
-Prerequisite: complete nopCommerce setup first (database configured and installer finished). Otherwise, storefront paths redirect to the install flow and do not represent real behavior.
-
-Use a valid product URL from your seeded catalog (for example, `/apple-macbook-pro`), not a hard-coded slug that may not exist in your dataset.
-
-Quick smoke probe (pre-install, useful as a connectivity check only):
+Complete installation with PostgreSQL (`citext` enabled), then verify:
 
 ```bash
-for p in / \
-         '/search?q=book' \
-         '/apple-macbook-pro' \
-         '/cart' \
-         '/checkout'; do
-  echo "== $p =="
-  for i in $(seq 1 20); do
-    curl -sS -o /dev/null -w '%{time_total}\n' "http://127.0.0.1:5000$p"
-  done
-done
+# Root should return storefront content.
+curl -s -o /dev/null -w 'root=%{http_code}\n' http://127.0.0.1:5000/
+
+# Install route should redirect once installation is complete.
+curl -s -o /dev/null -w 'install=%{http_code}\n' http://127.0.0.1:5000/install
 ```
 
-Before installation is complete, all storefront paths redirect to setup (`302`). Those numbers confirm reachability but are not valid performance baselines.
+Expected after successful install: `root=200`, `install=302`.
 
-## Installed-store endpoint baseline (validated)
+## Baseline methodology
 
-After fixing PostgreSQL setup (`citext`) and completing installation on both machines, the same endpoint benchmark was executed with `wrk` (`-t2 -c32 -d20s`) across this set:
+Do not benchmark `/install`. Baseline real storefront paths:
 
 - `/`
-- `/search?q=book`
-- `/electronics`
-- `/apple-macbook-pro`
-- `/cart`
-- `/checkout`
-
-Storefront pages returned `200`; `/checkout` returned `302` (expected without an authenticated session).
+- `/search/`
+- `/catalog/searchtermautocomplete`
+- `/product/search`
+- `/category/products/`
+- `/addproducttocart/catalog/...`
+- `/addproducttocart/details/...`
+- `/shoppingcart/productdetails_attributechange/...`
+- `/product/combinations`
+- `/cart/estimateshipping`
+- `/cart/selectshippingoption`
+
+Use the endpoint tester:
 
-Requests/second comparison:
+```bash
+# Use fixed concurrency and iterations for a repeatable starting point.
+python3 test_nopcommerce_endpoints.py \
+  --base-url http://127.0.0.1:5000 \
+  --concurrency 8 \
+  --iterations 20 \
+  --json-out arm_before.json
+```
 
-| Endpoint | x86 | Arm | Arm vs x86 |
-|---|---:|---:|---:|
-| `/apple-macbook-pro` | 35.40 | 32.28 | -8.8% |
-| `/electronics` | 99.52 | 76.07 | -23.6% |
-| `/search?q=book` | 28.18 | 27.40 | -2.8% |
+## Baseline quality rules
 
-Different endpoints show different gaps. Avoid reducing migration performance to a single number — use per-endpoint baselines to guide architecture-specific optimizations.
+Use these rules before you compare any optimization result:
 
-## Arm MCP accelerator (optional)
+- Run at least 3 baseline trials with identical parameters.
+- Keep endpoint order fixed per run (not randomized) when comparing before vs after.
+- Keep database state and seeded data identical across runs.
+- Capture raw JSON for every run and compare medians, not single outliers.
 
-Use MCP to script repeated baseline runs and summarize deltas, but keep the manual baseline commands as your ground truth.
+This baseline process becomes the control for every later tuning or code-change decision.

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

@@ -6,23 +6,29 @@ weight: 4
 layout: learningpathall
 ---
 
-Use a manual-first audit, then use the Arm MCP server to accelerate checks.
+# Audit dependencies
 
-## Manual workflow (required)
+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.
 
 ### 1. Map direct references
 
+Start with project-level references to see what your app explicitly depends on.
+
 ```bash
 rg -n "<PackageReference|<ProjectReference" src
 ```
 
 ### 2. List transitive dependencies
 
+Enumerate the full dependency graph; transitive packages often carry architecture-sensitive constraints.
+
 ```bash
 dotnet list src/Presentation/Nop.Web/Nop.Web.csproj package --include-transitive
 ```
 
-### 3. Generate an SBOM (required)
+### 3. 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.
 
 ```bash
 dotnet tool install --global CycloneDX
@@ -33,6 +39,8 @@ If tool installation is blocked, treat `dotnet list --include-transitive` plus `
 
 ### 4. Inspect package internals for native payloads
 
+Inspect package contents directly to find architecture-specific native binaries.
+
 ```bash
 mkdir -p /tmp/nupkg-audit
 cp ~/.nuget/packages/<package>/<version>/<package>.<version>.nupkg /tmp/nupkg-audit/
@@ -50,14 +58,4 @@ Treat dependencies as a chain, not isolated items:
 - Library A depends on library B
 - Library B is architecture-sensitive
 
-You must resolve B first, then validate A, then validate the app. In nopCommerce, `iTextSharp` and `System.Drawing` are an example of this chain.
-
-## Arm MCP accelerator (optional)
-
-After manual evidence is collected, use MCP tools to speed repetitive checks:
-
-- `knowledge_base_search` for package compatibility
-- `skopeo` or `check_image` for container image architecture coverage
-- `migrate_ease_scan` where scanner support exists
-
-Keep manual outputs as the source of truth. Use MCP to prioritize and scale, not to skip evidence.
+You must resolve B first, then validate A, then validate the app.