Update documentation for CodeQL language-specific detection

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Author: Copilot

.github/CodeQL-README.md

@@ -1,13 +1,34 @@
 # CodeQL scanning for this repository
 
-This repository uses C++ (C++20 / moving to C++23) built with CMake under the phlex-src directory, plus some Python and CI bits (Bash). The repository includes a CodeQL GitHub Actions workflow on branch `copilot/codeql-workflow` that:
+This repository uses C++ (C++20 / moving to C++23) built with CMake under the phlex-src directory, plus some Python and CI bits (Bash). The repository includes a CodeQL GitHub Actions workflow that:
 
 - Runs on pushes to `main`, PRs targeting `main`, a weekly schedule, and can be run manually.
 - Uses the repository's existing Phlex CMake build actions (not CodeQL autobuild) so the same build configuration is used for tests and release builds.
 - Scans C++ and Python sources and is scoped to the `phlex-src` tree (see the CodeQL config).
 - Uses RelWithDebInfo build type in CI so debug symbols are present while keeping realistic optimization.
+- **Implements intelligent language detection**: On pull requests, only languages with relevant file changes are analyzed, significantly reducing CI time.
 
-Important workflow-specific notes
+## Language-Specific Analysis and Automatic Detection
+
+The CodeQL workflow analyzes three language categories:
+
+1. **C++** (`cpp`): Analyzes C++ and header files, plus CMake files
+2. **Python** (`python`): Analyzes Python source files
+3. **GitHub Actions** (`actions`): Analyzes workflow and action YAML files
+
+### Detection Behavior by Event Type
+
+- **Pull Requests**: Only languages with relevant file changes are analyzed
+  - Example: A PR changing only Python files will skip C++ and Actions analysis (saves 35-70 minutes)
+  - Example: A PR changing only C++ files will skip Python and Actions analysis (saves 10-20 minutes)
+  - Example: A PR changing only workflow files will skip C++ and Python analysis
+- **Pushes to main/develop**: All languages are analyzed (no detection)
+- **Scheduled runs**: All languages are analyzed (no detection)
+- **Manual runs** (`workflow_dispatch`): All languages are analyzed (no detection)
+
+This detection mechanism follows the same pattern used by other workflows in this repository (python-check, clang-tidy-check, etc.) and uses the `detect-relevant-changes` action.
+
+## Important workflow-specific notes
 
 - The workflow sets `autobuild: false` during the CodeQL init so the repository's own configure / build steps run. This is intentional: the Phlex build actions are used to build exactly what you ship.
 - The workflow tries to locate and copy a compile_commands.json (from `phlex-src/build/` or `phlex-build/`) to the workspace root so diagnostic tools and manual inspection have a predictable path.

.github/REUSABLE_WORKFLOWS.md

@@ -414,6 +414,12 @@ jobs:
 
 Performs static analysis on the codebase using GitHub CodeQL to identify potential security vulnerabilities and coding errors.
 
+**Key Features:**
+
+- **Automatic Relevance Detection**: On pull requests, the workflow automatically detects which languages have relevant file changes and only runs CodeQL analysis for those languages. This significantly reduces CI time when changes affect only a subset of languages.
+- **Language-Specific Scanning**: Supports separate analysis for C++, Python, and GitHub Actions workflows.
+- **Fallback to Full Scan**: Scheduled runs, manual triggers (`workflow_dispatch`), and pushes to main branches always run all language scans regardless of changes.
+
 #### Usage Example
 
 ```yaml
@@ -426,10 +432,22 @@ jobs:
 
 - `checkout-path` (string, optional): Path to check out code to.
 - `build-path` (string, optional): Path for build artifacts.
-- `language-matrix` (string, optional, default: `'["cpp", "python", "actions"]'`): JSON array of languages to analyze.
+- `language-matrix` (string, optional, default: `'["cpp", "python", "actions"]'`): JSON array of languages to analyze. When provided in `workflow_call`, bypasses automatic detection and forces analysis of specified languages.
 - `pr-number` (string, optional): PR number if run in PR context.
 - `pr-head-repo` (string, optional): The full name of the PR head repository.
 - `pr-base-repo` (string, optional): The full name of the PR base repository.
+- `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
+- `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
+- `ref` (string, optional): The branch, ref, or SHA to checkout.
+- `repo` (string, optional): The repository to checkout from.
+
+#### Behavior Notes
+
+- **Pull Requests**: Only languages with relevant file changes are analyzed. For example, a PR that only modifies Python files will skip C++ and Actions analysis, saving 35-70 minutes of CI time.
+- **Manual Runs** (`workflow_dispatch`): All languages are analyzed regardless of changes.
+- **Scheduled Runs**: All languages are analyzed regardless of changes.
+- **Pushes to main/develop**: All languages are analyzed regardless of changes.
+- **Language Override**: Providing the `language-matrix` input in `workflow_call` bypasses automatic detection.
 
 ### Other Workflows