style updates and merging some troubleshooting guidance

Author: anupras-mohapatra-arm

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex.md

@@ -21,15 +21,15 @@ You need to complete only one method. The MCP server is a local standard input a
 Configure the server on the host where Codex runs. In a local Visual Studio Code (VS Code) session, this is your development computer. In a remote development session, confirm which host runs the Codex extension and which Arm Performix data directory it uses.
 {{% /notice %}}
 
-## Configure the server in the Codex extension
+## Configure the MCP server in the Codex extension
 
-To add the server in VS Code:
+To add the MCP server in VS Code:
 
-1. Open the Codex sidebar and select the gear icon.
+1. Open the Codex sidebar and select the **gear icon**.
 2. Select **MCP servers**, then select **Add server**.
-3. Enter `arm-performix` for the server name.
+3. For **Server name**, enter `arm-performix`.
 4. Select **STDIO** as the transport.
-5. Enter the full path to the Arm Performix `apx` executable in the command field.
+5. For **Command**, enter the full path to the Arm Performix `apx` executable.
 
     On macOS:
 
@@ -55,7 +55,7 @@ To add the server in VS Code:
     C:\Users\<username>\AppData\Local\Programs\Arm Performix\assets\apx\apx.exe
     ```
 
-6. Add one argument:
+6. Add the following arguments:
 
     ```text
     mcp
@@ -130,7 +130,7 @@ Record the run ID you want to analyze. A run name can be changed and might not b
 
 ## Troubleshoot the MCP connection
 
-Use the following checks to troubleshoot issues with MCP connection: 
+Use the following checks to diagnore MCP connection issues: 
 
 ### The Arm Performix MCP server isn't listed
 
@@ -198,4 +198,4 @@ If the CLI also returns no run, create or import a run. If the CLI returns the r
 
 You've now configured and tested the MCP connection.
 
-Next, you'll create a Code Hotspots run if no supported run is available. If you have an available supported run, skip to [Generate Arm Performix AI insights for a Code Hotspots run](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/generate_ai_insights/).
+Next, you'll create a Code Hotspots run if no supported run is available. If you already. have a supported run, skip to [Generate Arm Performix AI insights for a Code Hotspots run](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/generate_ai_insights/).

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/create_a_code_hotspots_run.md

@@ -34,7 +34,7 @@ Choose the correct target, then ask Codex to run Code Hotspots. Keep collection
 Use Arm Performix to run the Code Hotspots recipe on target "<target-name>" with workload "<command>". Before starting, repeat the target and workload and ask me to confirm them. When the run completes, return its run ID and collection status.
 ```
 
-Replace:
+Replace the following placeholders:
 
 - `<target-name>` with the Performix target name returned by Codex
 - `<command>` with the command that starts your workload on the target
@@ -45,9 +45,9 @@ For example:
 Use Arm Performix to run the Code Hotspots recipe on target "graviton-dev" with workload "/opt/myapp/bin/my_app --input /data/input.dat". Before starting, repeat the target and workload and ask me to confirm them. When the run completes, return its run ID and collection status.
 ```
 
-After you confirm, Codex uses the MCP server to start the recipe. Review any permission request before allowing the assistant to run a command on the target.
+After you confirm the target, Codex uses the MCP server to start the recipe. Review any permission request before allowing the assistant to run a command on the target.
 
-## Create a run with the Performix CLI
+## Create a run with the Arm Performix CLI
 
 If you prefer to control collection from a terminal, first check that the recipe dependencies and workload are ready:
 
@@ -96,6 +96,6 @@ apx target test --target <target-name>
 
 ## What you've accomplished and what's next
 
-You've now got the stable identifier Codex needs to analyze the intended profile.
+You now have the stable identifier Codex needs to analyze the intended profile.
 
 Next, you'll generate AI insights from a Code Hotspots run.

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/generate_ai_insights.md

@@ -3,13 +3,13 @@ title: Generate Arm Performix AI insights for a Code Hotspots run
 
 weight: 5
 
-description: Ask Codex for an Arm Performix AI Insight tied to a specific run and assess whether the response is supported by profile evidence.
+description: Ask Codex for an Arm Performix AI insight tied to a specific run and assess whether the response is supported by profile evidence.
 
 layout: learningpathall
 ---
 ## Select the exact run
 
-Use a run ID whenever possible. It prevents Codex from selecting a similarly named run or a more recent run from a different workload.
+Use a run ID whenever possible. A run ID prevents Codex from selecting a similarly named run or a more recent run from a different workload.
 
 If you don't have the ID, ask Codex to list supported runs:
 
@@ -35,11 +35,21 @@ Use Arm Performix to explain why function "<function-name>" is hot in run ID "<r
 
 Focused prompts usually produce more useful results than broad application-wide prompts.
 
-## Evaluate the response
+## Evaluate and refine AI insights
 
-A useful response identifies the run it analyzed and connects its conclusion to measured evidence, such as sample percentages, call paths, source attribution, or disassembly. It should also state when the available data can't establish a root cause.
+A useful AI insight identifies the run it analyzed and connects its conclusion to measured evidence, such as sample percentages, call paths, source attribution, or disassembly. It should also state when the available data can't establish a root cause.
 
-Ask follow-up questions when a recommendation isn't traceable:
+If a recommendation isn't traceable, ask for one finding and its evidence:
+
+```text
+Focus on the highest-impact finding in run ID "<run-id>". Cite the measured evidence, distinguish hypotheses from observations, and identify the next Performix view or recipe to inspect.
+```
+You can ask a similar question for a known hotspot:
+
+```text
+For function "<function-name>" in run ID "<run-id>", summarize what Code Hotspots proves, what it doesn't prove, and which additional evidence is needed to identify the root cause.
+```
+The following are some other questions that you can ask:
 
 ```text
 Which measured evidence in this Performix run supports that recommendation?
@@ -51,21 +61,7 @@ Which additional Performix recipe or view would distinguish between those explan
 What is the first optimization I should try, and why?
 ```
 
-## Improve a generic AI Insight
-
-Ask for one finding and its evidence:
-
-```text
-Focus on the highest-impact finding in run ID "<run-id>". Cite the measured evidence, distinguish hypotheses from observations, and identify the next Performix view or recipe to inspect.
-```
-
-For a known hotspot:
-
-```text
-For function "<function-name>" in run ID "<run-id>", summarize what Code Hotspots proves, what it doesn't prove, and which additional evidence is needed to identify the root cause.
-```
-
-If the response remains generic, confirm that the run has enough samples, symbols, source mapping, and disassembly. Code Hotspots locates sampled CPU time; use a more specific Performix recipe when you need evidence about microarchitecture, instruction mix, or memory access.
+Code Hotspots locates sampled CPU time. If you need evidence about microarchitecture, instruction mix, or memory access, use a more specific Performix recipe.
 
 ## Iterate and measure
 
@@ -82,6 +78,6 @@ Codex can help with more of this loop if your environment exposes build, deploym
 
 ## What you've accomplished and what's next
 
-You've now generated an evidence-based hypothesis.
+You've now generated an AI insight and reviewed its supporting evidence.
 
 Next, you'll open the same run in Arm Performix to inspect the underlying profile views.

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/open-in-performix.md

@@ -3,7 +3,7 @@ title: Open the run in Arm Performix for deeper inspection
 
 weight: 6
 
-description: Validate an AI Insight by inspecting flame graphs, functions, call paths, source, and disassembly from the same Arm Performix run.
+description: Validate an AI insight by inspecting flame graphs, functions, call paths, source, and disassembly from the same Arm Performix run.
 
 layout: learningpathall
 ---

content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/overview.md

@@ -9,25 +9,25 @@ layout: learningpathall
 ---
 ## Arm Performix local MCP server
 
-[Arm Performix](https://developer.arm.com/servers-and-cloud-computing/arm-performix) is a performance toolkit designed to help developers identify bottlenecks and validate improvements on Arm-based systems. It simplifies the process of turning low-level performance data into actionable insights through guided analysis paths called recipes. These recipes help you answer common performance questions and move quickly from observation to root cause.
+[Arm Performix](https://developer.arm.com/servers-and-cloud-computing/arm-performix) is a performance toolkit designed to help developers identify bottlenecks and validate improvements on Arm-based systems. The toolkit turns low-level performance data into actionable insights through guided analysis paths called recipes. You can use these recipes to answer common performance questions and move quickly from observation to root cause.
 
 Arm Performix includes a local Model Context Protocol (MCP) server. MCP is a standard way for an AI assistant to discover and call tools. The server lets Codex query Performix recipes, targets, and runs from Visual Studio Code instead of relying on source-code analysis alone.
 
-You'll connect the server to Codex, select or create a Code Hotspots run, and ask for an AI Insight. The response should connect each recommendation to evidence from the selected run.
+You'll connect the server to Codex, select or create a Code Hotspots run, and ask for an AI insight. The response should connect each recommendation to evidence from the selected run.
 
 {{% notice Important %}}
 The MCP server runs on the same host as Codex. It can make profile data, symbols, source excerpts, disassembly excerpts, and performance metrics available to the assistant. Before you continue, confirm that this use complies with your organization's data-handling policy.
 {{% /notice %}}
 
 Use AI-generated responses to support performance investigation. Validate important findings by reviewing the relevant data in Arm Performix and by rerunning the workload after making changes.
 
-## Arm Performix insights workflow
+## How AI-assisted Arm Performix insights are generated
 
-Arm Performix stores profiling runs, target information, and rendered analysis data. The local MCP server exposes select Performix capabilities as tools that an MCP-compatible assistant can call.
+Arm Performix stores profiling runs, target information, and rendered analysis data. The local MCP server exposes specific Performix capabilities as tools that an MCP-compatible assistant can call.
 
 When you ask for insights, the flow is:
 
-1. You ask an AI Assisant, in this case, Codex in VS Code for an Arm Performix insight.
+1. You ask an AI assistant — in this case, Codex in VS Code — for an Arm Performix insight.
 2. Codex calls the Arm Performix MCP server.
 3. Arm Performix gathers relevant run data and profile evidence.
 4. Codex uses that evidence to identify likely bottlenecks, explain why they matter, and suggest the next investigation step.
@@ -36,6 +36,6 @@ The available evidence depends on how the run was collected. Debug symbols and s
 
 ## What you've learned and what's next
 
-You've learned about Arm Performix's local MCP server and the workflow that's executed when you ask for insights using Codex. 
+You've learned about Arm Performix's local MCP server and how AI-assisted insights are generated. 
 
 Next, you'll configure the local MCP server and verify that Codex can use its tools.