first pass for performix codex insights

Author: anupras-mohapatra-arm

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

@@ -1,9 +1,5 @@
 ---
-title: Generate Arm Performix AI Insights in VS Code with Codex
-
-draft: true
-cascade:
-    draft: true
+title: Generate Arm Performix AI insights in Visual Studio Code with Codex
 
 description: Configure the Arm Performix MCP server for Codex in Visual Studio Code and use profile evidence to generate and validate AI Insights.
 
@@ -18,7 +14,7 @@ learning_objectives:
     - Generate an AI Insight and validate its recommendations against profile evidence.
 
 prerequisites:
-    - Arm Performix version 2026.2.5 or later installed. See the [Arm Performix install guide](/install-guides/performix/) for installation and target setup instructions.
+    - Arm Performix version 2026.2.5 or later installed. For installation and target setup instructions, see the [Arm Performix install guide](/install-guides/performix/).
     - Visual Studio Code with the Codex extension installed.
     - Access to Codex through ChatGPT sign-in, or an organization-approved OpenAI API key provided through the `OPENAI_API_KEY` environment variable.
     - Permission from your organization to share profile data, symbols, source excerpts, disassembly excerpts, and performance metrics with Codex.

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

@@ -9,21 +9,21 @@ layout: learningpathall
 ---
 ## Choose a configuration method
 
-Codex CLI and the Codex extension share MCP configuration on the same host. Choose one of these methods:
+Codex CLI and the Codex extension share MCP configuration on the same host. Choose one of the following methods:
 
 - Use the Codex extension settings.
 - Run `codex mcp add` in a terminal.
 - Edit `~/.codex/config.toml`.
 
-You only need to complete one method. The MCP server is a local standard input/output (STDIO) process started by the `apx` executable.
+You need to complete only one method. The MCP server is a local standard input and output (STDIO) process started by the `apx` executable.
 
 {{% notice Note %}}
-Configure the server on the host where Codex runs. In a local 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.
+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
 
-To add the server in Visual Studio Code:
+To add the server in VS Code:
 
 1. Open the Codex sidebar and select the gear icon.
 2. Select **MCP servers**, then select **Add server**.
@@ -80,9 +80,9 @@ codex mcp add arm-performix -- "/Applications/Arm Performix.app/Contents/assets/
 
 Restart the Codex extension after the command completes.
 
-## Configure the server in `config.toml`
+## Configure the server in the Codex config file
 
-For direct configuration, open `~/.codex/config.toml` and add:
+For direct configuration, open `~/.codex/config.toml` and add the following:
 
 ```toml
 [mcp_servers.arm-performix]
@@ -92,13 +92,15 @@ args = ["mcp", "start"]
 
 Replace `command` with the full path to `apx` on your host. Save the file and restart the Codex extension.
 
+{{% notice Note %}}
 On Windows, use a TOML literal string so backslashes in the path aren't treated as escape characters:
 
 ```toml
 [mcp_servers.arm-performix]
 command = 'C:\Program Files\Arm Performix\assets\apx\apx.exe'
 args = ["mcp", "start"]
 ```
+{{% /notice %}}
 
 ## Check that the MCP server is connected
 
@@ -126,4 +128,74 @@ List the Arm Performix Code Hotspots runs that can be used to generate an AI Ins
 
 Record the run ID you want to analyze. A run name can be changed and might not be unique, so use the run ID in later prompts.
 
-You have now configured and tested the MCP connection. If no supported run is available, create a Code Hotspots run in the next section.
+## Troubleshoot the MCP connection
+
+Use the following checks to troubleshoot issues with MCP connection: 
+
+### The Arm Performix MCP server isn't listed
+
+Check whether Codex loaded the server configuration:
+
+```bash
+codex mcp list
+```
+
+Find `arm-performix` in the output. Then confirm:
+
+- The command is the full path to the `apx` executable, including `apx.exe` on Windows.
+- The arguments are `mcp` and `start`.
+- The server is enabled.
+- You restarted the extension after changing the configuration.
+- You edited the configuration for the same user account and Codex host that runs the extension.
+
+### The MCP server fails to start
+
+Run the executable's built-in help from a terminal to separate an `apx` problem from a Codex configuration problem. Replace `<path-to-apx>` with the configured path:
+
+```bash
+"<path-to-apx>" mcp --help
+```
+
+If the help text doesn't appear, check the executable path, file permissions, and installed Arm Performix version. If it does appear, reopen **MCP servers** in the Codex extension and check the server status.
+
+In a remote development session, make sure `apx` is installed on the Codex host and that this installation uses the expected Performix configuration and run data.
+
+### Codex doesn't use Arm Performix
+
+Name the server and task explicitly:
+
+```text
+Use the Arm Performix MCP server to list the available Arm Performix runs.
+```
+
+For a specific run:
+
+```text
+Use Arm Performix to generate an AI Insight for run ID "<run-id>".
+```
+
+If you have several MCP servers, an ambiguous prompt such as `give me insights` might not select Arm Performix.
+
+### Code Hotspots runs are missing
+
+Check:
+
+- You created at least one completed Code Hotspots run.
+- The MCP server runs as the same user who created or imported the run.
+- The GUI, CLI, and MCP server use the same Arm Performix data location.
+- The selected run contains enough samples and profile data for analysis.
+- A remote Visual Studio Code environment isn't using a different home directory or Performix configuration.
+
+Compare the MCP result with the CLI:
+
+```bash
+apx run list
+```
+
+If the CLI also returns no run, create or import a run. If the CLI returns the run but Codex doesn't, recheck which host, user, and configuration start the MCP server.
+
+## What you've accomplished and what's next
+
+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/).

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

@@ -1,5 +1,5 @@
 ---
-title: Create a Code Hotspots run
+title: Create an Arm Performix Code Hotspots run
 
 weight: 4
 
@@ -9,16 +9,16 @@ layout: learningpathall
 ---
 ## Prepare a representative workload
 
-You can skip this section if you already selected a supported Code Hotspots run.
+If you already have a supported Code Hotspots 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/).
 
 For a new run, choose a workload that represents the behavior you want to optimize. Specify the executable with an absolute path because Performix doesn't support relative workload paths. Build it with debug symbols when possible so Performix can attribute samples to functions and source lines. Aim for at least 20 seconds of representative activity; a very short run might not collect enough samples for useful analysis.
 
 Before profiling, make sure you know:
 
-- The Performix target name.
-- The executable path and arguments on the target.
-- The workload's working directory and required environment variables.
-- Whether running the workload has side effects.
+- the Performix target name
+- the executable path and arguments on the target
+- the workload's working directory and required environment variables
+- whether running the workload has side effects
 
 ## Create a run with Codex
 
@@ -36,8 +36,8 @@ Use Arm Performix to run the Code Hotspots recipe on target "<target-name>" with
 
 Replace:
 
-- `<target-name>` with the Performix target name returned by Codex.
-- `<command>` with the command that starts your workload on the target.
+- `<target-name>` with the Performix target name returned by Codex
+- `<command>` with the command that starts your workload on the target
 
 For example:
 
@@ -66,12 +66,36 @@ apx recipe run code_hotspots \
     --timeout 30 
 ```
 
-The `--timeout 30` option limits profiling to 30 seconds; it doesn't make a short workload run longer. Use a duration that captures representative behavior. Add `--working-dir`, `--env`, or `--source` when your workload needs a specific working directory, environment variables, or host-based source mapping. For an already-running process, replace `--workload` with `--pid <process-id>`.
+The `--timeout 30` option limits profiling to 30 seconds and doesn't make a short workload run longer. Use a duration that captures representative behavior.
+
+Add `--working-dir`, `--env`, or `--source` when your workload needs a specific working directory, environment variables, or host-based source mapping. For an already-running process, replace `--workload` with `--pid <process-id>`.
 
 When collection finishes, list the saved runs:
 
 ```bash
 apx run list
 ```
 
-Confirm that the new run completed successfully and record its run ID. You now have the stable identifier Codex needs to analyze the intended profile.
+Confirm that the new run completed successfully and record its run ID.
+
+## Troubleshoot remote target authentication
+
+If remote target authentication fails, check that:
+
+- SSH key-based authentication works without an interactive password prompt.
+- The private key doesn't require an interactive passphrase.
+- Passwordless `sudo` is configured for the target user.
+- Strict host-key checking succeeds.
+- `~/.ssh/known_hosts` contains the target key and each jump-node key.
+
+Use the Arm Performix target test to check the configured connection independently of Codex:
+
+```bash
+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.
+
+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

@@ -1,5 +1,5 @@
 ---
-title: Generate AI Insights
+title: Generate Arm Performix AI insights for a Code Hotspots run
 
 weight: 5
 
@@ -51,6 +51,22 @@ 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.
+
 ## Iterate and measure
 
 After you review the evidence, use a controlled optimization loop:
@@ -64,4 +80,8 @@ After you review the evidence, use a controlled optimization loop:
 
 Codex can help with more of this loop if your environment exposes build, deployment, remote-execution, or source-control tools. Review proposed code changes and command approvals before Codex applies or runs them.
 
-You have now generated an evidence-based hypothesis. Next, open the same run in Arm Performix to inspect the underlying profile views.
+## What you've accomplished and what's next
+
+You've now generated an evidence-based hypothesis.
+
+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

@@ -22,4 +22,8 @@ Use the AI Insight to focus your investigation, not replace it. For example, if
 
 For a before-and-after comparison, keep the workload, target, input, thread count, CPU affinity, and collection settings consistent. A lower sample percentage doesn't prove that a function became faster if total runtime or the surrounding workload changed.
 
-You have configured the Performix MCP server, selected or created a Code Hotspots run, generated an AI Insight, and checked its recommendation against the profile. Continue with the [Arm Performix getting-started video](https://youtu.be/_eX8ZpNT0kc) to explore the graphical workflow.
+## What you've accomplished
+
+You've now configured the Performix MCP server, selected or created a Code Hotspots run, generated an AI Insight, and checked its recommendation against the profile. 
+
+You can continue with the [Arm Performix getting-started video](https://youtu.be/_eX8ZpNT0kc) to explore the graphical workflow.

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

@@ -1,27 +1,29 @@
 ---
-title: Overview
+title: Understand the AI-assisted Arm Performix insight workflow
 
 weight: 2
 
 description: Learn how Codex uses the Arm Performix MCP server to turn profiling data into evidence-based performance recommendations.
 
 layout: learningpathall
 ---
-## Understand the AI-assisted profiling workflow
+## 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 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 will 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.
 
-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. Confirm that this use complies with your organization's data-handling policy before you continue.
+{{% 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.
 
-## How it works
+## Arm Performix insights workflow
 
-Arm Performix stores profiling runs, target information, and rendered analysis data. Its 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 select Performix capabilities as tools that an MCP-compatible assistant can call.
 
 When you ask for insights, the flow is:
 
@@ -32,4 +34,8 @@ When you ask for insights, the flow is:
 
 The available evidence depends on how the run was collected. Debug symbols and source mappings improve function and source-line attribution, while a representative profiling duration improves sampling quality.
 
- Next, configure the local MCP server and verify that Codex can use its tools.
+## 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. 
+
+Next, you'll configure the local MCP server and verify that Codex can use its tools.