Merge pull request #3475 from anupras-mohapatra-arm/fixes

Style-based updates to Performix MCP LP + fixing rendering of inline math equations

Author: jasonrandrews

.github/skills/markdown-component-edit/references/component-patterns.md

@@ -86,4 +86,28 @@ Rules:
 - Keep each tab roughly comparable in length and detail.
 - Avoid hiding critical sequential instructions inside tabs unless the user chooses one path.
 
+## Mathematical expressions
 
+Use `\(...\)` to display a mathematical expression inline.
+
+For example:
+
+```md
+\(\sqrt{re^2 + im^2}\)
+```
+
+Use `$$...$$` or `\[...\]` to display a mathematical expression in a block.
+
+For example:
+
+```md
+$$re_{new} = re_z^2 - im_z^2 + re_c$$
+```
+
+or
+
+```md
+\[
+re_{new} = re_z^2 - im_z^2 + re_c
+\]
+```

content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/1-overview.md

@@ -1,36 +1,39 @@
 ---
-title: Understand AI-driven profiling with Arm Performix MCP
+title: Understand AI-driven profiling with Arm Performix MCP tool
+description: Understand how the Arm MCP Server exposes Arm Performix so an AI agent can run Code Hotspots profiling and propose evidence-based optimizations.
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Why AI-driven profiling with Arm Performix
+## Why profile with Arm Performix using AI
 
-The Arm MCP Server exposes Arm Performix as a first-class tool that AI coding assistants can invoke directly. Rather than switching between your IDE and the Performix GUI to analyze results and then back again to apply code changes, an AI agent can orchestrate the entire profiling pipeline — configuring the recipe, launching the collection run, retrieving hotspot data, and proposing optimizations — all in a single agentic workflow.
+The Arm MCP Server exposes Arm Performix as a first-class tool that AI coding assistants can invoke directly. Rather than switching between your IDE and the Performix GUI to analyze results and then back again to apply code changes, an AI agent can orchestrate the entire profiling pipeline. Configuring the recipe, launching the collection run, retrieving hotspot data, and proposing optimizations can all be part of a single agentic workflow.
 
-## What is the Arm Performix tool in the MCP Server?
+## What the Arm Performix tool is
 
-Arm Performix is a performance profiling tool that simplifies the workflow of collecting CPU samples, building flame graphs, and identifying the functions that dominate application runtime. When integrated into the MCP server, it lets an AI agent orchestrate the entire profiling pipeline — configuring the recipe, launching the collection run, and retrieving the resulting hotspot data — without manual interaction with the Performix engine.
+Arm Performix is a performance profiling tool that simplifies the workflow of collecting CPU samples, building flame graphs, and identifying the functions that dominate application runtime. 
 
-Context switching for profiling is removed. Rather than switching between your IDE and the Performix GUI to analyze results and then back again to apply code changes, an AI agent can do all of this for you in a single agentic workflow.
+When you integrate Arm Performix into the MCP server, the tool lets an AI agent orchestrate the entire profiling pipeline — configuring the recipe, launching the collection run, and retrieving the resulting hotspot data — without manual interaction with the Performix engine.
+
+You don't need to context switch between your IDE and the Performix GUI to analyze results and then back again to apply code changes. An AI agent can do all of this for you in a single agentic workflow.
 
 ## How the MCP tool works
 
 The `apx_recipe_run` tool in the Arm MCP Server accepts a recipe name, a binary path on the remote target, and SSH connection details. It starts the Performix collection run on the configured remote target, waits for the application to finish, and then returns a structured summary of the profiling results. The summary includes the top CPU-time-consuming functions ordered by sample percentage, call stack context for each hotspot, and any relevant observations about the application's runtime behavior.
 
-The agent uses this data to cross-reference hotspot function names against the source files in your workspace, reason about why those functions are expensive, and propose specific code changes. Because the AI can see both the profiling output and the source code simultaneously, it avoids the guesswork that is common in manual profiling workflows.
+The agent uses this data to cross-reference hotspot function names against the source files in your workspace, reason about why those functions are expensive, and propose specific code changes. Because the AI can see both the profiling output and the source code simultaneously, it avoids the guesswork that's common in manual profiling workflows.
 
-**Use case:** Automating the Code Hotspots recipe on a C++ application running on an Arm Neoverse target to identify and fix the most CPU-intensive functions. In this Learning Path, the agent drives three successive optimization passes — each validated by a re-profile before moving to the next — to achieve a measured ~12x runtime improvement.
+You'll use this tool in the following sections to automate the Code Hotspots recipe on a C++ application running on an Arm Neoverse target and identify and fix the most CPU-intensive functions. The agent will drive three successive optimization passes — each validated by a re-profile before moving to the next — to achieve a measured ~12x runtime improvement.
 
 ## How to interact with the Arm MCP Server for profiling
 
 The Arm MCP Server supports the same interaction styles as the rest of its tool suite: direct chat, prompt files, and agentic workflows. For profiling tasks, prompt files are the recommended approach. Profiling workflows typically involve multiple sequential steps — building the application, running a recipe, reading results, editing code, and repeating. Encoding this sequence in a prompt file makes it repeatable, shareable, and easy to version-control alongside the application.
 
 ### Direct AI chat
 
-You can ask your AI assistant direct questions and it will invoke the `apx_recipe_run` tool when appropriate. For example:
+You can ask your AI assistant direct questions and it'll invoke the `apx_recipe_run` tool when appropriate. For example:
 
 ```text
 Run the Code Hotspots recipe on /home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread_debug and tell me which functions are the hottest
@@ -44,18 +47,24 @@ For repeatable workflows, a prompt file encodes the full profiling sequence as a
 
 ### Agentic workflows
 
-Tools like GitHub Copilot Agent Mode, Claude Code, Kiro, and OpenAI Codex support autonomous multi-step execution. When you combine a prompt file with an agentic workflow, the profiling step is deterministic: the agent calls `arm-mcp/apx_recipe_run` through the Arm MCP Server, which runs the Performix recipe on your target and returns the identified hotspots as structured, reproducible data. The agent then reasons over those hotspots, locating the corresponding source code, forming a hypothesis about why each function is expensive, and proposing a targeted change — before rebuilding and calling `arm-mcp/apx_recipe_run` again to measure the delta. Every decision in the loop is grounded in the hotspot data returned by the tool; the AI never guesses at performance characteristics.
+Tools such as GitHub Copilot Agent Mode, Claude Code, Kiro, and OpenAI Codex support autonomous multi-step execution. When you combine a prompt file with an agentic workflow, the profiling step is deterministic: the agent calls `arm-mcp/apx_recipe_run` through the Arm MCP Server, which runs the Performix recipe on your target and returns the identified hotspots as structured, reproducible data. The agent then reasons over those hotspots, locating the corresponding source code, forming a hypothesis about why each function is expensive, and proposing a targeted change — before rebuilding and calling `arm-mcp/apx_recipe_run` again to measure the delta.
+
+Every decision in the loop is grounded in the hotspot data returned by the tool; the AI never guesses at performance characteristics.
 
-## Setting up the Arm MCP Server
+## Set up the Arm MCP Server
 
-To use the Arm MCP Server with an AI coding assistant, you need to configure the assistant to connect to the MCP server. Connecting your assistant allows it to query Arm-specific tools, documentation, and capabilities exposed through the Model Context Protocol (MCP).
+To use the Arm MCP Server with an AI coding assistant, configure the assistant to connect to the MCP server. Connecting your assistant allows it to query Arm-specific tools, documentation, and capabilities exposed through the Model Context Protocol (MCP).
 
-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:
+The required configuration steps vary by AI coding assistant. For step-by-step instructions on connecting AI coding assistants to the Arm MCP server, see the following install guides:
 
 - [GitHub Copilot](/install-guides/github-copilot/)
-- [Gemini CLI](/install-guides/gemini/)
+- [Antigravity CLI](/install-guides/antigravity/)
 - [Kiro CLI](/install-guides/kiro-cli/)
 - [Codex CLI](/install-guides/codex-cli/)
 - [Claude Code](/install-guides/claude-code/)
 
-In the next section, you'll build the Mandelbrot example application on your remote Arm server and confirm that Arm Performix can reach the target.
+## What you've learned and what's next
+
+You've now learned what the Arm Performix tool for the Arm MCP Server is and how the tool works. You've also learned why the tool is useful and how you can interact with it.
+
+Next, you'll build the Mandelbrot example application on your remote Arm server and confirm that Arm Performix can reach the target.

content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/2-setup.md

@@ -1,5 +1,6 @@
 ---
 title: Build the Mandelbrot example on Arm Neoverse
+description: Build the Mandelbrot C++ example on an Arm Neoverse target and confirm the binary path that Performix will profile through the Arm MCP Server.
 weight: 3
 
 ### FIXED, DO NOT MODIFY
@@ -8,25 +9,29 @@ layout: learningpathall
 
 ## Prepare the profiling target
 
-In this section, you'll build the Mandelbrot C++ application on your remote Arm server and confirm that Arm Performix can reach the target.
+You'll build and profile the Mandelbrot C++ application used in the [Find code hotspots with Arm Performix](/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/) Learning Path on your remote Arm server and confirm that Arm Performix can reach the target.
 
 ## About the example application
 
-This Learning Path profiles the same Mandelbrot C++ application used in the [Find code hotspots with Arm Performix](/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/) Learning Path. It generates a 1920×1080 bitmap of the Mandelbrot set by iterating a simple recurrence for each pixel and is compute-heavy enough to produce clear profiling signal without requiring a long-running workload. The single-threaded build is intentionally unoptimized so that the hotspot analysis surfaces a meaningful target for improvement.
+The application generates a 1920×1080 bitmap of the Mandelbrot set by iterating a simple recurrence for each pixel and is compute-heavy enough to produce clear profiling signal without requiring a long-running workload. The single-threaded build is intentionally unoptimized so that the hotspot analysis surfaces a meaningful target for improvement.
 
-You don't need to understand the Mandelbrot algorithm to follow this Learning Path.
+You don't need to understand the Mandelbrot algorithm to follow the Learning Path.
 
 ## Connect to your Arm target
 
-For profiling, the Learning Path targets an AWS Graviton3 metal instance (`m7g.metal`) with 64 Neoverse V1 cores. Any Arm Linux server with multiple cores works for the parallelization step, but a metal instance gives you direct access to all hardware threads without the overhead of virtualization.
+For profiling, you'll target an AWS Graviton3-based metal instance (`m7g.metal`) with 64 Neoverse V1 cores. Any Arm Linux server with multiple cores works, but a metal instance gives you direct access to all hardware threads without the overhead of virtualization.
 
-You connect to the remote target via SSH through the Arm MCP Server. The `apx_recipe_run` tool accepts the target host IP address and SSH username directly as parameters, so there is no separate target configuration step required. Ensure your remote Arm server is reachable over SSH from the machine running your AI coding assistant, and follow the [Configure your MCP client](https://github.com/arm/mcp?tab=readme-ov-file#2-configure-your-mcp-client) instructions in the Arm MCP Server repository before continuing.
+Connect to the remote target via SSH through the Arm MCP Server. The `apx_recipe_run` tool accepts the target host IP address and SSH username directly as parameters, so there's no separate target configuration step required.
+
+Ensure your remote Arm server is reachable over SSH from the machine running your AI coding assistant, and follow the [Configure your MCP client](https://github.com/arm/mcp?tab=readme-ov-file#2-configure-your-mcp-client) instructions in the Arm MCP Server repository before continuing.
 
 ## Build the application on the remote server
 
-In this section you'll build the debug binary for the Mandelbrot C++ application, the sample workload you'll profile in the next section.
+Build the debug binary for the Mandelbrot C++ application, the sample workload that you'll profile in the next section.
+
+Connect to the remote server over SSH and install the required build tools.
 
-Connect to the remote server over SSH and install the required build tools. On `dnf`-based systems such as Amazon Linux 2023 or RHEL, run:
+On `dnf`-based systems such as Amazon Linux 2023 or RHEL, run:
 
 ```bash
 sudo dnf update && sudo dnf install -y git gcc-c++ make
@@ -48,10 +53,14 @@ ls -lh build/mandelbrot_single_thread_debug
 
 ## Verify the binary path for Performix
 
-Note the absolute path to the binary on the remote server. You'll need this when configuring the Code Hotspots recipe in the next section. For the default setup the path is:
+Note the absolute path to the binary on the remote server. You'll need this when configuring the Code Hotspots recipe in the next section. For the default setup, the path is:
 
 ```text
 /home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread_debug
 ```
 
-You now have everything in place: a compiled, debug-enabled binary on an Arm Neoverse target that Performix can reach. In the next section, you'll create a GitHub Copilot prompt file to drive the Code Hotspots recipe through the Arm MCP Server.
+## What you've accomplished and what's next
+
+You've now got everything in place for profiling: a compiled, debug-enabled binary on an Arm Neoverse target that Performix can reach.
+
+Next, you'll create a GitHub Copilot prompt file to drive the Code Hotspots recipe through the Arm MCP Server.