docs: clarify coverage architecture artifacts

.bazelrc

@@ -18,6 +18,9 @@ common --registry=https://bcr.bazel.build
 # into the graph; an empty ANDROID_HOME keeps it inert on stripped runners.
 common --repo_env=ANDROID_HOME=
 
+# for plantuml
+build --java_runtime_version=remotejdk_17
+
 test --test_output=errors
 
 # Rust toolchain for the analysis-test fixtures (same registration as the

.github/workflows/docs-publish.yml

@@ -0,0 +1,35 @@
+# *******************************************************************************
+# Copyright (c) 2026 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+name: Publish Documentation
+
+on:
+  workflow_run:
+    workflows: ["Tests"]
+    types: [completed]
+
+jobs:
+  docs-publish:
+    # Only publish runs that produce an addressable documentation version.
+    # Merge-group runs are ephemeral and should not update Pages previews.
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      contains(fromJSON('["pull_request", "push", "release"]'), github.event.workflow_run.event)
+    uses: eclipse-score/cicd-workflows/.github/workflows/docs-publish.yml@d2083d5dac0e309643d9f495e61342dfbaf07ed5 # main, 2026-09-24
+    with:
+      deployment_type: workflow
+    permissions:
+      actions: read
+      contents: write
+      id-token: write
+      pages: write
+      pull-requests: write

.github/workflows/format.yml

@@ -27,13 +27,9 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7.0.1
-      - uses: castler/setup-bazel@cache-optimized
+      - uses: eclipse-score/cicd-actions/setup-bazel-cache@setup-bazel-cache/v0.1.0
         with:
-          bazelisk-cache: true
-          disk-cache: format
-          repository-cache: true
-          cache-optimized: true
-          cache-save: ${{ github.ref == 'refs/heads/main' }}
+          disk-cache-key: format
       - name: Run formatting checks
         # score_tooling >= 2 tags format tests `manual`; lift the tag filter.
         run: bazel test --test_tag_filters= //tools:format.check

.github/workflows/tests.yml

@@ -17,16 +17,15 @@ on:
   push:
     branches:
       - main
+  release:
+    types: [published]
   merge_group:
     types: [checks_requested]
 concurrency:
   group: tests-${{ github.event.pull_request.number || github.run_id }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 permissions:
-  contents: write
-  pages: write
-  pull-requests: write
-  id-token: write
+  contents: read
 env:
   ANDROID_HOME: ""
   ANDROID_SDK_ROOT: ""
@@ -40,13 +39,9 @@ jobs:
         uses: eclipse-score/more-disk-space@v1
         with:
           level: 4
-      - uses: castler/setup-bazel@cache-optimized
+      - uses: eclipse-score/cicd-actions/setup-bazel-cache@setup-bazel-cache/v0.1.0
         with:
-          bazelisk-cache: true
-          disk-cache: unit_tests
-          repository-cache: true
-          cache-optimized: true
-          cache-save: ${{ github.ref == 'refs/heads/main' }}
+          disk-cache-key: unit_tests
       - name: Build everything
         run: bazel build --lockfile_mode=error //...
       - name: Run unit and Starlark analysis tests
@@ -85,13 +80,9 @@ jobs:
         uses: eclipse-score/more-disk-space@v1
         with:
           level: 4
-      - uses: castler/setup-bazel@cache-optimized
+      - uses: eclipse-score/cicd-actions/setup-bazel-cache@setup-bazel-cache/v0.1.0
         with:
-          bazelisk-cache: true
-          disk-cache: integration_tests
-          repository-cache: true
-          cache-optimized: true
-          cache-save: ${{ github.ref == 'refs/heads/main' }}
+          disk-cache-key: integration_tests
       - name: Run the end-to-end pipeline test (C++ + Rust consumer workspace)
         run: integration_tests/run_integration_test.sh
       - name: Upload coverage report of the integration workspace
@@ -104,15 +95,12 @@ jobs:
           retention-days: 10
   docs:
     needs: unit_tests
-    uses: eclipse-score/cicd-workflows/.github/workflows/docs.yml@93aac16ada7d247bbb6ae926509ddea74cf5213a # v0.0.2
+    uses: eclipse-score/cicd-workflows/.github/workflows/docs.yml@d2083d5dac0e309643d9f495e61342dfbaf07ed5 # main, 2026-09-24
     permissions:
-      contents: write
-      pages: write
-      pull-requests: write
-      id-token: write
+      contents: read
     with:
       # docs() lives in //docs (the root package must not load dev deps), so
-      # the output is docs/_build; the reusable workflow archives _build.
+      # move its output to _build, which the reusable workflow uploads.
       bazel-target: "//docs:docs && mv docs/_build _build"
       tests-report-artifact: tests-report
       retention-days: 3

.yamlfmt

@@ -0,0 +1,3 @@
+formatter:
+  type: basic
+  retain_line_breaks: true

docs/architecture/index.rst

@@ -39,35 +39,69 @@ backends that produce the same report zip:
 
    @startuml
    skinparam componentStyle rectangle
+   skinparam artifactBackgroundColor #EAF2F8
+   skinparam artifactBorderColor #4E79A7
+   skinparam componentBackgroundColor #FFF2CC
+   skinparam componentBorderColor #B58B00
+   skinparam usecaseBackgroundColor #E2F0D9
+   skinparam usecaseBorderColor #548235
    package "Phase 1: bazel coverage --config=llvm_cov" {
-     [Clang / rustc\ncovmap instrumentation] --> [test binaries]
-     [test binaries] --> (profraw per test)
-     (profraw per test) --> [merger.py\n--coverage_output_generator]
-     [merger.py\n--coverage_output_generator] --> (coverage.dat zip\nprofdata + meta.json)
-     [score_coverage_scope\naspect] --> (allowlist.txt\npath_map.txt\nobjects.txt\nsource files)
-     (coverage.dat zip\nprofdata + meta.json) --> [reporter.py\n--coverage_report_generator]
-     (allowlist.txt\npath_map.txt\nobjects.txt\nsource files) --> [reporter.py\n--coverage_report_generator]
-     [reporter.py\n--coverage_report_generator] --> (_coverage_report.dat zip\nhtml_report, lcov_report, text_report)
+     artifact "test binaries" as llvm_bins
+     artifact "profraw per test" as llvm_profraw
+     artifact "coverage.dat zip\nprofdata + meta.json" as llvm_test_zip
+     artifact "allowlist.txt\npath_map.txt\nobjects.txt\nsource files" as llvm_scope_files
+     component "Clang / rustc\ncovmap instrumentation" as llvm_instrumentation
+     component "merger.py\n--coverage_output_generator" as llvm_merger
+     component "score_coverage_scope\naspect" as llvm_scope
+     component "reporter.py\n--coverage_report_generator" as llvm_reporter
+
+     llvm_instrumentation --> llvm_bins
+     llvm_bins --> llvm_profraw
+     llvm_profraw --> llvm_merger
+     llvm_merger --> llvm_test_zip
+     llvm_scope --> llvm_scope_files
+     llvm_test_zip --> llvm_reporter
+     llvm_scope_files --> llvm_reporter
    }
+
    package "Phase 1, gcov backend: bazel coverage --config=qnx" {
-     [GCC / QCC\n-fprofile-arcs -ftest-coverage] --> [test binaries (QEMU on QNX)]
-     [test binaries (QEMU on QNX)] --> (.gcda per test)
-     (.gcda per test) --> [Bazel collector\ngcov + lcov_merger]
-     [Bazel collector\ngcov + lcov_merger] --> (coverage.dat LCOV)
-     (coverage.dat LCOV) --> [gcov_reporter.py\n--coverage_report_generator]
-     (allowlist.txt\npath_map.txt\ngcno.txt\nsource files) --> [gcov_reporter.py\n--coverage_report_generator]
-     [gcov_reporter.py\n--coverage_report_generator] --> (_coverage_report.dat zip\nhtml_report, lcov_report, text_report)
+     artifact "test binaries (QEMU on QNX)" as gcov_bins
+     artifact ".gcda per test" as gcda
+     artifact "coverage.dat LCOV" as gcov_lcov
+     artifact "allowlist.txt\npath_map.txt\ngcno.txt\nsource files" as gcov_scope_files
+     component "GCC / QCC\n-fprofile-arcs -ftest-coverage" as gcov_instrumentation
+     component "Bazel collector\ngcov + lcov_merger" as gcov_collector
+     component "gcov_reporter.py\n--coverage_report_generator" as gcov_reporter
+
+     gcov_instrumentation --> gcov_bins
+     gcov_bins --> gcda
+     gcda --> gcov_collector
+     gcov_collector --> gcov_lcov
+     gcov_lcov --> gcov_reporter
+     gcov_scope_files --> gcov_reporter
    }
+
    package "Phase 2: bazel run //:generate_coverage_html" {
-     (_coverage_report.dat zip\nhtml_report, lcov_report, text_report) --> [generate_coverage_html.py]
-     [generate_coverage_html.py] --> [justify.py]
-     [justify.py] --> (manifest.json)
-     (manifest.json) --> [effective_coverage.py]
-     [effective_coverage.py] --> (report.json\nsummary.txt)
-     [generate_coverage_html.py] --> [coverage_summary.py]
-     [generate_coverage_html.py] --> (gate verdict\nexit 0 / 1 / 2)
-     [generate_coverage_html.py] --> (archive dir)
+     artifact "_coverage_report.dat zip\nhtml_report, lcov_report, text_report" as report_zip
+     artifact "manifest.json" as manifest
+     artifact "report.json\nsummary.txt" as effective_report
+     artifact "archive dir" as archive_dir
+     component "generate_coverage_html.py" as generate_coverage_html
+     component "justify.py" as justify
+     component "effective_coverage.py" as effective_coverage
+     component "coverage_summary.py" as coverage_summary
+
+     report_zip --> generate_coverage_html
+     generate_coverage_html --> justify
+     justify --> manifest
+     manifest --> effective_coverage
+     effective_coverage --> effective_report
+     generate_coverage_html --> coverage_summary
+     generate_coverage_html --> (gate verdict\nexit 0 / 1 / 2)
+     generate_coverage_html --> archive_dir
    }
+   llvm_reporter --> report_zip
+   gcov_reporter --> report_zip
    @enduml
 
 Phase 1: collection