@@ -1,6 +1,57 @@
-name: MATLAB Build
+name: MATLAB CI and Pages
 
-# Controls when the action will run. 
+# WORKFLOW OVERVIEW
+# ==================
+# This workflow implements a multi-release MATLAB testing and documentation pipeline.
+# It tests courseware code across multiple MATLAB releases in parallel, validates results,
+# generates a status badge, and deploys documentation to GitHub Pages.
+#
+# ARCHITECTURE:
+#   Phase 1 - test-matrix (parallel): Run tests independently for each MATLAB release
+#   Phase 2 - report-and-deploy (sequential): Merge artifacts, validate, generate badge, deploy
+#
+# KEY FILES:
+#   - buildfile.m              : Defines build tasks (testing, validation, badge generation)
+#   - SoftwareTests/CoursewareSmokeTests.m     : Tests core courseware scripts
+#   - SoftwareTests/FunctionTests.m            : Placeholder for development function tests
+#   - SoftwareTests/CrossReleaseTestResults.m : Validates all releases passed (gate for badge)
+#
+# ARTIFACT FLOW:
+#   1. test-matrix job (runs for each MATLAB release R2025a, R2025b):
+#      $ buildtool test
+#      -> public/R2025a/CoursewareSmokeTests.mat, FunctionTests.mat, etc.
+#      -> Upload artifacts: test-results-R2025a, test-results-R2025b
+#
+#   2. report-and-deploy job (runs once, after test-matrix completes):
+#      $ Download and merge all test-results-* artifacts into public/
+#      $ buildtool report  (runs report:validate, report:badge, report:link tasks)
+#      -> SoftwareTests/CrossReleaseTestResults.m validates all releases passed
+#      -> createBadge() generates public/TestedWith.json (shields.io format)
+#      -> linkResultArtifactPathsInReportIndex() wraps test result links in HTML
+#      -> Deploy public/ to GitHub Pages
+#
+# CUSTOMIZATION:
+#   To change tested MATLAB releases: Edit matrix.Releases list (line 29)
+#   To add/remove products: Edit MATLAB_PRODUCTS env variable (line 28)
+#   To change deploy trigger: Edit 'on' workflow events (lines 3-7)
+#
+# FOR YOUR OWN COURSEWARE:
+#   1. Copy buildfile.m and SoftwareTests/ structure to your repo
+#   2. Create SoftwareTests/CoursewareSmokeTests.m with your own test suite
+#      (reference: https://www.mathworks.com/help/matlab/matlab_prog/write-simple-test-suite.html)
+#   3. Update .github/workflows/ci.yml with your product list and release matrix
+#   4. Push to your release branch and monitor GitHub Actions
+#
+# TROUBLESHOOTING:
+#   If tests fail in CI but pass locally:
+#     - Check version(-release) output matches your installed MATLAB
+#     - Verify all dependencies (products) are listed in MATLAB_PRODUCTS
+#     - Review public/index.html report for detailed test output
+#   If badge generation fails:
+#     - Ensure SoftwareTests/CrossReleaseTestResults.m can find all release artifacts
+#     - Check public/CrossReleaseTestResults.mat for missing or empty result variables
+
+# Controls when the action will run.
 on:
   push:
     branches: [ release ]
@@ -14,107 +65,119 @@ permissions:
   pages: write
   id-token: write
 
+# Cancel older in-progress runs on the same ref to save CI time.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  test:
-    strategy: 
+  test-matrix:
+    name: Test on ${{ matrix.Releases }}
+    strategy:
       fail-fast: false
       matrix:
-        MATLABVersion: [R2024b,R2025a,R2025b]
+        Releases: [R2025b, R2026a]
     runs-on: ubuntu-latest
     env:
+      MATLAB_PRODUCTS: >
+        MATLAB
+        Statistics_and_Machine_Learning_Toolbox 
+        System_Identification_Toolbox 
+        Image_Processing_Toolbox 
       LD_PRELOAD: /usr/lib/x86_64-linux-gnu/libstdc++.so.6
     steps:
       # Checks-out your repository
-      - uses: actions/checkout@v4
-      
+      - uses: actions/checkout@v6
+
       # Sets up a display server
       - name: Start display server
         if: ${{ always() }}
         run: |
-          sudo apt-get install xvfb
+          sudo apt-get update
+          sudo apt-get install -y xvfb
           Xvfb :99 &
           echo "DISPLAY=:99" >> $GITHUB_ENV
-      
+
       # Sets up MATLAB
-      - name: Setup MATLAB
-        uses: matlab-actions/setup-matlab@v2
+      - name: Setup MATLAB ${{ matrix.Releases }}
+        uses: matlab-actions/setup-matlab@v3
         with:
-          release: ${{ matrix.MATLABVersion }}
-          products: MATLAB Statistics_and_Machine_Learning_Toolbox System_Identification_Toolbox 
-          # List required products above in the format shown (and uncomment them)
-          # List of product strings:
-          # Simulink
-          # Statistics_and_Machine_Learning_Toolbox
-          # Simulink_Coder
-          # Econometrics_Toolbox
-          # Deep_Learning_Toolbox
-
-
-      # Run all the tests
-      - name: Run SmokeTests
-        uses: matlab-actions/run-command@v2
+          release: ${{ matrix.Releases }}
+          products: ${{ env.MATLAB_PRODUCTS }}
+          cache: true
+
+      # Run aggregated test task from buildfile.m.
+      - name: Run buildtool test
+        uses: matlab-actions/run-build@v3
         with:
-          command: openProject(pwd); RunAllTests; 
+          tasks: test
+          build-options: -continueOnFailure
 
-      # Upload the test results as artifact
-      - name: Upload TestResults
+      # Upload only files required by buildtool report/pages to reduce artifact size.
+      - name: Upload test results artifact
         if: ${{ always() }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
-          name: TestResults_${{ matrix.MATLABVersion }}
-          path: ./public/*
+          name: ${{ matrix.Releases }}
+          path: |
+            ./public/${{ matrix.Releases }}/
           overwrite: true
+          retention-days: 7
 
-  badge:
+  report-and-deploy:
+    name: Build badge and deploy reports
     if: ${{ always() }}
-    needs: [test]
-    strategy: 
-      fail-fast: false
+    needs: [test-matrix]
     runs-on: ubuntu-latest
-    steps: 
+    steps:
 
       # Checks-out your repository
-      - uses: actions/checkout@v4
-      
-      # Sets up R2023b
-      - name: Setup MATLAB
-        uses: matlab-actions/setup-matlab@v2
+      - uses: actions/checkout@v6
+
+      # GitHub-hosted jobs are isolated; MATLAB install from test-matrix cannot be reused here.
+      # Keep this setup minimal (no extra products) and use artifacts from matrix jobs.
+
+      # Sets latest MATLAB for report task (no toolbox list needed).
+      - name: Setup MATLAB latest
+        uses: matlab-actions/setup-matlab@v3
         with:
-          release: R2024b
-  
+          release: latest
+          cache: true
+
       # Download the test results from artifact
       - name: Download All TestResults
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: public
-          pattern: TestResults_*
-          merge-multiple: true
-          
-      # Create the test results badge
-      - name: Run PostSmokeTest
-        uses: matlab-actions/run-command@v2
+          pattern: R20*
+          merge-multiple: false
+
+      # Aggregate test reports and generate badge via buildfile.
+      - name: Run buildtool report
+        uses: matlab-actions/run-build@v3
+        with:
+          tasks: report
+          build-options: -continueOnFailure
+
+      # Upload the badge as artifact
+      - name: Upload Badge
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v6
         with:
-          command: openProject(pwd); PostSmokeTest;
-      
+          name: Badge-Artifact
+          path: ./public/TestedWith.json
+          overwrite: true
+
       # Deploy reports to GitHub pages
       - name: Setup Pages
+        if: ${{ always() && github.event_name != 'pull_request' }}
         uses: actions/configure-pages@v5
       - name: Upload pages artifact
+        if: ${{ always() && github.event_name != 'pull_request' }}
         uses: actions/upload-pages-artifact@v3
         with:
           path: public
       - name: Deploy to GitHub Pages
+        if: ${{ always() && github.event_name != 'pull_request' }}
         id: deployment
         uses: actions/deploy-pages@v4
-
-      # Commit the JSON for the MATLAB releases badge 
-      - name: Commit changed files
-        continue-on-error: true
-        run: |
-          git config user.name "${{ github.workflow }} by ${{ github.actor }}"
-          git config user.email "<>"
-          git pull
-          git add Images/TestedWith.json
-          git commit Images/TestedWith.json -m "Update CI badges ${{  github.ref_name }}"
-          git fetch
-          git push
 
@@ -47,5 +47,7 @@ codegen/
 # Project settings
 Utilities/ProjectSettings.mat
 
-# GitLab page folder
-public/
+# Testing and CI related artifact
+public/
+.buildtool/
+ci_utilities/