ci: scope-aware build matrix

.github/workflows/ci-build.yml

@@ -158,6 +158,7 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Process Coverage
+        id: process-coverage
         if: matrix.coverage == 'true'
         uses: alandefreitas/cpp-actions/process-coverage@v1.9.4
         with:
@@ -166,3 +167,19 @@ jobs:
           html-report: true
           codecov-token: ${{ secrets.CODECOV_TOKEN }}
           codecov-flags: cpp
+
+      # Save the produced LCOV report so PRs that don't change source files
+      # can replay it to codecov without re-running a Coverage build.
+      # `ci-scope-detector.yml` probes this artifact by name and merge-base SHA.
+      - name: Save coverage for replay
+        if: |
+          matrix.coverage == 'true' &&
+          github.event_name == 'push' &&
+          github.ref_name == 'develop' &&
+          steps.process-coverage.outputs.lcov-file != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-develop
+          path: ${{ steps.process-coverage.outputs.lcov-file }}
+          retention-days: 90
+          if-no-files-found: error

.github/workflows/ci-documentation.yml

@@ -0,0 +1,135 @@
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# Copyright (c) 2026 Alan de Freitas (alandefreitas@gmail.com)
+#
+# Official repository: https://github.com/cppalliance/mrdocs
+#
+# Per-OS validation that the docs/website/Antora-UI pipelines build
+# cleanly with the installed mrdocs binary. Scope-gated: runs when
+# source, docs, build, or third-party files changed (i.e. anything
+# that can influence rendered documentation). Skipped on tooling /
+# ci / toolchain-only PRs.
+
+name: Documentation
+
+on:
+  workflow_call:
+    inputs:
+      submatrix:
+        description: 'JSON-encoded releases submatrix from cpp-matrix'
+        type: string
+        required: true
+      use-develop-binaries:
+        description: 'true to fetch packages from develop-release instead of this run'
+        type: boolean
+        default: false
+
+jobs:
+  documentation:
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(inputs.submatrix) }}
+
+    defaults:
+      run:
+        shell: bash
+
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.runs-on }}
+    container: ${{ matrix.container }}
+    permissions:
+      contents: read
+    steps:
+      - name: Container Bootstrap
+        uses: alandefreitas/cpp-actions/container-bootstrap@v1.9.4
+
+      - name: Install packages
+        uses: alandefreitas/cpp-actions/package-install@v1.9.4
+        with:
+          apt-get: build-essential asciidoctor cmake bzip2 git rsync
+
+      - name: Clone MrDocs
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup C++
+        uses: alandefreitas/cpp-actions/setup-cpp@v1.9.4
+        id: setup-cpp
+        with:
+          compiler: ${{ matrix.compiler }}
+          version: ${{ matrix.version }}
+
+      # Same dual-source pattern as ci-releases.yml: fresh-build artifact
+      # when we built this run, develop-release fallback otherwise.
+      - name: Download MrDocs package (fresh build)
+        if: ${{ !inputs.use-develop-binaries }}
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ matrix.mrdocs-release-package-artifact }}
+          path: packages
+
+      - name: Download MrDocs package (develop-release fallback)
+        if: ${{ inputs.use-develop-binaries }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          mkdir -p packages
+          case "${{ runner.os }}" in
+            Linux)   pattern='*Linux*' ;;
+            Windows) pattern='*Windows*' ;;
+            macOS)   pattern='*Darwin*' ;;
+            *) echo "::error::unknown runner.os: ${{ runner.os }}"; exit 1 ;;
+          esac
+          gh release download develop-release --pattern "$pattern" -D packages
+
+      - name: Install MrDocs from Package
+        run: .github/scripts/install-mrdocs-package.sh
+
+      - name: Generate Landing Page
+        working-directory: docs/website
+        run: |
+          npm ci
+          node render.js
+          mkdir -p ../../build/website
+          cp index.html ../../build/website/index.html
+          cp robots.txt ../../build/website/robots.txt
+          cp styles.css ../../build/website/styles.css
+          cp -r assets ../../build/website/assets
+
+      - name: Generate Antora UI
+        working-directory: docs/ui
+        run: |
+          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
+          export GH_TOKEN
+          npm ci
+          npx gulp lint
+          npx gulp
+
+      - name: Generate Local Documentation
+        working-directory: docs
+        run: |
+          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
+          export GH_TOKEN
+          set -x
+          npm ci
+          npx antora antora-playbook.yml --attribute branchesarray=HEAD --stacktrace --log-level=debug
+          mkdir -p ../build/docs-local
+          cp -vr build/site/* ../build/docs-local
+
+      - name: Upload Website as Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: Website ${{ runner.os }}
+          path: build/website
+          retention-days: 30

.github/workflows/ci-matrix.yml

@@ -115,6 +115,11 @@ jobs:
 
           submatrices: |
             releases: {{ieq is-release-build 'true'}}
+            # `coverage` is a raw boolean factor (undefined on non-Coverage rows),
+            # so `ieq` would crash. Wrap in `#if` like the `is-bottleneck` extra-value
+            # above to handle undefined cleanly.
+            coverage: {{#if coverage}}true{{/if}}
+            releases-and-coverage: {{#if (or (ieq is-release-build 'true') coverage)}}true{{/if}}
           trace-commands: true
           github-token: ${{ secrets.GITHUB_TOKEN }}