Improve workflow documentation and job output naming

- Standardized `REUSABLE_WORKFLOWS.md` with consistent structure, full
  usage examples, and comprehensive input documentation for all workflows.
- Added documentation for missing workflows to `REUSABLE_WORKFLOWS.md`.
- Ensured consistency in job outputs (`has_changes`) across modernized
  workflows.

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

Author: google-labs-jules[bot]

.github/REUSABLE_WORKFLOWS.md

@@ -2,7 +2,7 @@
 
 ## Overview and General Instructions
 
-The workflows in `Framework-R-D/phlex/` maybe invoked as follows:
+The workflows in `Framework-R-D/phlex/` may be invoked as follows:
 
 1. Automatically as part of CI checks on a PR submitted to `Framework-R-D/phlex`, at PR creation time and thereafter on pushes to the PR branch. This should work whether your PR branch is situated in the primary repository or a fork.
 1. Via triggering comments on the PR (`@phlexbot <action>`).
@@ -97,35 +97,35 @@ jobs:
 - `build-path` (string, optional): Path for build artifacts.
 - `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs the build if C++ or CMake files have changed.
 - `build-combinations` (string, optional): A space-separated list of build combinations to run.
-- `ref` (string, optional): The branch or ref to check out.
-- `repo` (string, optional): The repository to check out from (e.g., `my-org/my-repo`).
+- `ref` (string, optional): The branch, ref, or SHA to check out.
+- `repo` (string, optional): The repository to check out from.
 - `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.
 
-### 2. `python-check.yaml`
+### 2. `cmake-format-check.yaml`
 
-Checks Python code for formatting and type errors using `ruff` and `mypy`.
+Checks CMake files for formatting issues using `gersemi`.
 
 #### Usage Example
 
 ```yaml
 jobs:
-  check_python:
-    uses: Framework-R-D/phlex/.github/workflows/python-check.yaml@cef968c52aab432b836bb28119a9661c82c8b0d1
+  check_cmake_format:
+    uses: Framework-R-D/phlex/.github/workflows/cmake-format-check.yaml@cef968c52aab432b836bb28119a9661c82c8b0d1
 ```
 
 #### All Inputs
 
 - `checkout-path` (string, optional): Path to check out code to.
-- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Python files have changed.
+- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if CMake files have changed.
 - `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.
 
 ### 3. `cmake-format-fix.yaml`
 
 Automatically formats CMake files using `gersemi` and commits the changes. Typically triggered by an `issue_comment`.
 
-#### Usage Example (in a workflow triggered by `issue_comment`)
+#### Usage Example
 
 ```yaml
 name: 'Bot Commands'
@@ -154,35 +154,60 @@ jobs:
 #### All Inputs
 
 - `checkout-path` (string, optional): Path to check out code to.
-- `ref` (string, **required**): The branch or ref to check out.
+- `ref` (string, **required**): The branch, ref, or SHA to check out.
 - `repo` (string, **required**): The repository to check out from.
 
-### 4. `python-fix.yaml`
+### 4. `python-check.yaml`
 
-Automatically formats and fixes Python code using `ruff` and commits the changes. Typically triggered by an `issue_comment`.
+Checks Python code for formatting and type errors using `ruff` and `mypy`.
 
-#### Usage Example (in a workflow triggered by `issue_comment`)
+#### Usage Example
 
-*Similar to `cmake-format-fix.yaml`, but triggered by a command like `@<repo>bot python-fix`.*
+```yaml
+jobs:
+  check_python:
+    uses: Framework-R-D/phlex/.github/workflows/python-check.yaml@cef968c52aab432b836bb28119a9661c82c8b0d1
+```
 
 #### All Inputs
 
 - `checkout-path` (string, optional): Path to check out code to.
-- `ref` (string, **required**): The branch or ref to check out.
-- `repo` (string, **required**): The repository to check out from.
+- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Python files have changed.
+- `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.
 
-### 5. `markdown-fix.yaml`
+### 5. `python-fix.yaml`
 
-Automatically formats Markdown files using `markdownlint` and commits the changes. Typically triggered by an `issue_comment`.
+Automatically formats and fixes Python code using `ruff` and commits the changes. Typically triggered by an `issue_comment`.
+
+#### Usage Example
 
-#### Usage Example: `markdown-fix.yaml` (in a workflow triggered by `issue_comment`)
+```yaml
+name: 'Bot Commands'
+on:
+  issue_comment:
+    types: [created]
 
-*Similar to `cmake-format-fix.yaml`, but triggered by a command like `@<repo>bot markdown-fix`.*
+jobs:
+  fix-python:
+    # Run only on comments from collaborators/owners that start with the bot command
+    if: >
+      github.event.issue.pull_request &&
+      (github.event.comment.author_association == 'COLLABORATOR' || github.event.comment.author_association == 'OWNER') &&
+      startsWith(github.event.comment.body, format('@{0}bot python-fix', github.event.repository.name))
+    uses: Framework-R-D/phlex/.github/workflows/python-fix.yaml@cef968c52aab432b836bb28119a9661c82c8b0d1
+    with:
+      # The ref and repo of the PR need to be retrieved and passed
+      ref: ${{ steps.get_pr_info.outputs.ref }}
+      repo: ${{ steps.get_pr_info.outputs.repo }}
+    secrets:
+      WORKFLOW_PAT: ${{ secrets.WORKFLOW_PAT }}
+```
 
-#### All Inputs: `markdown-fix.yaml`
+#### All Inputs
 
 - `checkout-path` (string, optional): Path to check out code to.
-- `ref` (string, **required**): The branch or ref to check out.
+- `ref` (string, **required**): The branch, ref, or SHA to check out.
 - `repo` (string, **required**): The repository to check out from.
 
 ### 6. `markdown-check.yaml`
@@ -203,9 +228,86 @@ jobs:
 - `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Markdown files have changed. Note that this workflow automatically emulates the trigger type of the caller; it will run relevance checks if called from a `pull_request` or `push` event, and skip them (running on all files) otherwise.
 - `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.
+- `ref` (string, optional): The branch, ref, or SHA to check out.
+- `repo` (string, optional): The repository to check out from.
+
+### 7. `markdown-fix.yaml`
+
+Automatically formats Markdown files using `markdownlint` and commits the changes. Typically triggered by an `issue_comment`.
+
+#### Usage Example
+
+```yaml
+name: 'Bot Commands'
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  fix-markdown:
+    # Run only on comments from collaborators/owners that start with the bot command
+    if: >
+      github.event.issue.pull_request &&
+      (github.event.comment.author_association == 'COLLABORATOR' || github.event.comment.author_association == 'OWNER') &&
+      (
+        startsWith(github.event.comment.body, format('@{0}bot format', github.event.repository.name)) ||
+        startsWith(github.event.comment.body, format('@{0}bot markdown-fix', github.event.repository.name))
+      )
+    uses: Framework-R-D/phlex/.github/workflows/markdown-fix.yaml@cef968c52aab432b836bb28119a9661c82c8b0d1
+    with:
+      # The ref and repo of the PR need to be retrieved and passed
+      ref: ${{ steps.get_pr_info.outputs.ref }}
+      repo: ${{ steps.get_pr_info.outputs.repo }}
+    secrets:
+      WORKFLOW_PAT: ${{ secrets.WORKFLOW_PAT }}
+```
+
+#### All Inputs
+
+- `checkout-path` (string, optional): Path to check out code to.
+- `ref` (string, **required**): The branch, ref, or SHA to check out.
+- `repo` (string, **required**): The repository to check out from.
+
+### 8. `actionlint-check.yaml`
+
+Checks GitHub Actions workflow files for errors and best practices using `actionlint`.
+
+#### Usage Example
+
+```yaml
+jobs:
+  check_actions:
+    uses: Framework-R-D/phlex/.github/workflows/actionlint-check.yaml@cef968c52aab432b836bb28119a9661c82c8b0d1
+```
+
+#### All Inputs
+
+- `checkout-path` (string, optional): Path to check out code to.
+- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if workflow files have changed.
+- `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.
+
+### 9. `codeql-analysis.yaml`
+
+Performs static analysis on the codebase using GitHub CodeQL to identify potential security vulnerabilities and coding errors.
+
+#### Usage Example
+
+```yaml
+jobs:
+  analyze:
+    uses: Framework-R-D/phlex/.github/workflows/codeql-analysis.yaml@cef968c52aab432b836bb28119a9661c82c8b0d1
+```
+
+#### All Inputs
+
+- `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.
+- `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.
 
 ### Other Workflows
 
-The repository also provides `actionlint-check.yaml`, `cmake-format-check.yaml`, and `codeql-analysis.yaml`, which can be used in a similar manner.
+The repository also provides `clang-format-check.yaml`, `clang-format-fix.yaml`, `clang-tidy-check.yaml`, and `clang-tidy-fix.yaml`, which can be used in a similar manner.

.github/workflows/markdown-check.yaml

@@ -73,7 +73,7 @@ jobs:
       contents: read
       packages: read
     outputs:
-      matched: ${{ steps.filter.outputs.matched }}
+      has_changes: ${{ steps.filter.outputs.matched }}
     steps:
     - name: Checkout code
       uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -107,7 +107,7 @@ jobs:
       needs.detect-changes.result == 'skipped' ||
       (
         needs.detect-changes.result == 'success' &&
-        needs.detect-changes.outputs.matched == 'true'
+        needs.detect-changes.outputs.has_changes == 'true'
       )
     runs-on: ubuntu-latest
     permissions:
@@ -157,7 +157,7 @@ jobs:
           (github.event.pull_request || github.event.before)
         )
       ) &&
-      (needs.detect-changes.result == 'success' && needs.detect-changes.outputs.matched != 'true')
+      (needs.detect-changes.result == 'success' && needs.detect-changes.outputs.has_changes != 'true')
     runs-on: ubuntu-latest
     permissions:
       contents: read