Merge pull request #3532 from anupras-mohapatra-arm/performix-dynamic-insights

Performix dynamic insights LP review + style skill tweak to handle lists based on Arm tech writing style

Author: pareenaverma

.github/skills/writing-style-review/SKILL.md

@@ -47,6 +47,7 @@ Use this skill for granular prose, voice, readability, terminology, and style re
 - Flag pages over 3500 words total when prose density hurts review or learning.
 - Use visual breaks to prevent walls of text. Code blocks count as visual breaks.
 - If a section explains three or more things, suggest splitting it.
+- Ensure lists have a lead-in sentence or phrase ending with a colon. Ensure each item starts with a capitalized word unless the word is supposed to be styled differently. Ensure list items don't end with periods unless the item is one or more complete sentences.
 
 ## Arm framing and technical depth
 

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

@@ -1,11 +1,7 @@
 ---
-title: Generate Arm Performix AI Insights in VS Code with Codex
+title: Generate Arm Performix AI insights in Visual Studio Code with Codex
 
-draft: true
-cascade:
-    draft: true
-
-description: Configure the Arm Performix MCP server for Codex in Visual Studio Code and use profile evidence to generate and validate AI Insights.
+description: Configure the Arm Performix MCP server for Codex in Visual Studio Code and use profile evidence to generate and validate AI insights.
 
 minutes_to_complete: 20
 
@@ -15,17 +11,67 @@ learning_objectives:
     - Configure the Arm Performix MCP server for the Codex extension in VS Code.
     - Verify that Codex can access Arm Performix recipes, targets, and runs.
     - Create or select a supported Code Hotspots run.
-    - Generate an AI Insight and validate its recommendations against profile evidence.
+    - 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.
-    - 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.
+    - 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
+
+# START generated_summary_faq
+generated_summary_faq:
+  template_version: summary-faq-v3
+  generated_at: '2026-07-27T15:24:59Z'
+  generator: ai
+  ai_assisted: true
+  ai_review_required: true
+  model: gpt-5
+  prompt_template: summary-faq-v3
+  source_hash: 3e21e94826b1e02673c240ad88dc503354a1920397903348316d696cf4e2aa2c
+  summary_generated_at: '2026-07-27T15:24:59Z'
+  summary_source_hash: 3e21e94826b1e02673c240ad88dc503354a1920397903348316d696cf4e2aa2c
+  faq_generated_at: '2026-07-27T15:24:59Z'
+  faq_source_hash: 3e21e94826b1e02673c240ad88dc503354a1920397903348316d696cf4e2aa2c
+  summary: >-
+    You'll learn how to connect Codex in Visual Studio Code to the Arm Performix Model
+    Context Protocol (MCP) server, generate an AI insight for a specific Code Hotspots run, and
+    validate the result with profile evidence. After configuring the MCP server on your local machine, you’ll select or create a representative Code Hotspots run, request an AI insight by run ID, and evaluate its supporting evidence.
+    Then, you'll open the same run in Arm Performix to inspect flame graphs, functions, call
+    stacks, source, and disassembly to confirm the recommendation.
+  faqs:
+  - question: How do I confirm Codex is connected to Arm Performix through MCP?
+    answer: >-
+      Ask Codex to list Arm Performix recipes, targets, or supported Code Hotspots runs. A successful
+      listing confirms the MCP server is configured and reachable.
+  - question: Which MCP configuration method should I use, and where should I configure it?
+    answer: >-
+      You can update Codex extension settings, run the `codex mcp add` command, or
+      edit `~/.codex/config.toml`. Configure the MCP on the host where Codex runs; in remote development,
+      verify which machine hosts Codex.
+  - question: What should I prepare before creating a new Code Hotspots run?
+    answer: >-
+      Choose a representative workload and specify the executable with an absolute path. Build the workload with debug symbols when possible and aim for at least 20 seconds of activity to collect
+      enough samples.
+  - question: How do I make sure Codex uses the exact profile I want?
+    answer: >-
+      Request the AI insight using the run ID. If you don’t know it, ask Codex to list supported
+      Code Hotspots runs with IDs, targets, workloads, and creation times. Then, select the correct
+      ID.
+  - question: What should I check to validate an AI insight against the profile?
+    answer: >-
+      Open the same run in Arm Performix and inspect the **Flame graph**, **Functions**, **Call Stack**,
+      **Source**, and **Disassembly** views. Confirm that the cited functions, call paths, and sample percentages
+      match the evidence referenced by the insight.
+# END generated_summary_faq
 
 author: 
     - Julie Gaskin
 
+generate_summary_faq: false
+rerun_summary: false
+rerun_faqs: false
+
 ### Tags
 skilllevels: Introductory
 subjects: Performance and Architecture

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

@@ -9,27 +9,27 @@ 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`.
+- 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
+## Configure the MCP server in the Codex extension
 
-To add the server in Visual Studio 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 Visual Studio Code:
     C:\Users\<username>\AppData\Local\Programs\Arm Performix\assets\apx\apx.exe
     ```
 
-6. Add one argument:
+6. Add the following arguments:
 
     ```text
     mcp
@@ -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
 
@@ -121,9 +123,79 @@ If Codex returns Performix recipes or runs, the end-to-end connection works. An
 Next, ask Codex to identify runs that support the insight workflow:
 
 ```text
-List the Arm Performix Code Hotspots runs that can be used to generate an AI Insight. Include the run ID and enough workload and target details for me to choose the correct run.
+List the Arm Performix Code Hotspots runs that can be used to generate an AI insight. Include the run ID and enough workload and target details for me to choose the correct run.
 ```
 
 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 diagnose MCP connection issues: 
+
+### 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 for the following:
+
+- 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 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

@@ -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
 
@@ -34,20 +34,20 @@ 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.
+- `<target-name>` with the Performix target name returned by Codex
+- `<command>` with the command that starts your workload on the target
 
 For example:
 
 ```text
 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 and workload, 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:
 
@@ -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 now have the stable identifier Codex needs to analyze the intended profile.
+
+Next, you'll generate AI insights from a Code Hotspots run.