[rules score] update documentation

.bazelignore

@@ -18,3 +18,5 @@ bazel/rules/rules_score/test
 # Separate local Bazel modules (use @seooc// and @some_other_library// instead)
 bazel/rules/rules_score/examples/seooc
 bazel/rules/rules_score/examples/some_other_library
+# Separate local Bazel module (system integrator demo, depends on @seooc//)
+bazel/rules/rules_score/examples/integrator

.github/workflows/tests.yml

@@ -122,6 +122,11 @@ jobs:
               cd bazel/rules/rules_score/examples/seooc
               bazel build //...
               bazel test //...
+          - name: integrator_example
+            run: |
+              cd bazel/rules/rules_score/examples/integrator
+              bazel build //...
+              bazel test //...
           - name: some_other_library_example
             run: |
               cd bazel/rules/rules_score/examples/some_other_library

bazel/rules/rules_score/BUILD

@@ -165,6 +165,15 @@ sphinx_docs_library(
     strip_prefix = "validation/core/docs/specifications/",
 )
 
+# Source files from the standalone minimal example, mapped into the Sphinx
+# source tree so that general.rst can reference them via literalinclude.
+sphinx_docs_library(
+    name = "minimal_example_srcs",
+    srcs = ["//bazel/rules/rules_score/examples/minimal:doc_sources"],
+    prefix = "bazel/rules/rules_score/docs/examples/minimal/",
+    strip_prefix = "bazel/rules/rules_score/examples/minimal/",
+)
+
 sphinx_module(
     name = "rules_score_doc",
     testonly = True,
@@ -182,6 +191,7 @@ sphinx_module(
         "//bazel/rules/rules_score/docs/requirements:use_cases_rst",
     ],
     docs_library_deps = [
+        ":minimal_example_srcs",
         ":tool_readme_ai_checker_assets",
         ":validation_specs",
     ],

bazel/rules/rules_score/docs/_assets/MySeooc_WriteSequence.puml → bazel/rules/rules_score/docs/_assets/SeoocExample_DynamicDesign.puml

@@ -11,15 +11,12 @@
 ' SPDX-License-Identifier: Apache-2.0
 ' *******************************************************************************
 
-@startuml MySeooc_WriteSequence
+@startuml SeoocExample_DynamicDesign
 
-actor Caller
-participant KeyValueStore
-participant StorageBackend
+participant "Unit 1" as unit_1 <<unit>>
+participant "Unit 2" as unit_2 <<unit>>
 
-Caller -> KeyValueStore : write(key, value)
-KeyValueStore -> StorageBackend : flush()
-StorageBackend --> KeyValueStore : OK
-KeyValueStore --> Caller : Result::Ok
+unit_1 -> unit_2 : GetData()
+unit_2 --> unit_1 : return : Data*
 
 @enduml

bazel/rules/rules_score/docs/_assets/SeoocExample_FTA.puml

@@ -0,0 +1,29 @@
+' *******************************************************************************
+' 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
+' *******************************************************************************
+
+@startuml SeoocExample_FTA
+
+!include fta_metamodel.puml
+
+$TopEvent("SampleFailureMode takes over the world", "SampleLibrary.SampleFailureMode")
+
+$OrGate("OG1", "SampleLibrary.SampleFailureMode")
+
+$IntermediateEvent("SampleFailureMode is Angry", "IEF", "OG1")
+$BasicEvent("Just bad luck", "SampleLibrary.JustBadLuck", "OG1")
+
+$AndGate("AG2", "IEF")
+$BasicEvent("No More Cookies", "SampleLibrary.NoMoreCookies", "AG2")
+$BasicEvent("No More Coffee", "SampleLibrary.NoMoreCoffee", "AG2")
+
+@enduml

bazel/rules/rules_score/docs/_assets/MySeooc_StaticDesign.puml → bazel/rules/rules_score/docs/_assets/SeoocExample_InternalApi.puml

@@ -11,13 +11,14 @@
 ' SPDX-License-Identifier: Apache-2.0
 ' *******************************************************************************
 
-@startuml MySeooc_StaticDesign
+@startuml SeoocExample_InternalApi
 
-package "MySeooc" as MySeooc <<SEooC>> {
-    component "KvsComponent" as KvsComponent <<component>> {
-        component "KeyValueStore" as KeyValueStore <<unit>>
-        component "StorageBackend" as StorageBackend <<unit>>
+namespace safety_software_seooc_example {
+  namespace component_example {
+    interface "InternalInterface" as InternalInterface <<interface>>{
+      {abstract} GetData(BindingType binding): Data*
     }
+  }
 }
 
 @enduml

bazel/rules/rules_score/docs/_assets/MySeooc_PublicApi.puml → bazel/rules/rules_score/docs/_assets/SeoocExample_PublicApi.puml

@@ -11,11 +11,11 @@
 ' SPDX-License-Identifier: Apache-2.0
 ' *******************************************************************************
 
-@startuml MySeooc_PublicApi
+@startuml SeoocExample_PublicApi
 
-interface "KeyValueStore" as KVS {
-    + write(key: string, value: bytes): Result
-    + read(key: string): Optional<bytes>
+package "SampleLibraryAPI" as SampleLibraryAPI {
+    interface "GetNumber" as GetNumber
+    ' interface "SetNumber" as SetNumber
 }
 
 @enduml

bazel/rules/rules_score/docs/_assets/SeoocExample_StaticDesign.puml

@@ -0,0 +1,32 @@
+' *******************************************************************************
+' 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
+' *******************************************************************************
+
+@startuml SeoocExample_StaticDesign
+
+package "Safety Software SEooC Example" as safety_software_seooc_example <<SEooC>> {
+    component "ComponentExample" as component_example <<component>> {
+        component "Unit 1" as unit_1 <<unit>>
+        component "Unit 2" as unit_2 <<unit>>
+        component "Sub Component Example" as sub_component_example <<component>>
+
+        interface "InternalInterface" as InternalInterface
+        unit_1 -l-( InternalInterface
+        unit_2 )-r- InternalInterface
+    }
+}
+
+package "SampleLibraryAPI" as SampleLibraryAPI
+
+component_example --> SampleLibraryAPI
+
+@enduml

bazel/rules/rules_score/docs/_assets/SeoocExample_UnitClassDiagram.puml

@@ -0,0 +1,36 @@
+' *******************************************************************************
+' 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
+' *******************************************************************************
+
+@startuml SeoocExample_UnitClassDiagram
+
+namespace unit_1 {
+    class Foo <<final>>{
+        --
+        + GetNumber() : uint8_t
+        + SetNumber(value : uint8_t) : void
+    }
+}
+
+namespace unit_2 {
+    class Bar <<final>>{
+        --
+        - foo_ : unique_ptr<unit_1::Foo>
+        --
+        + Bar(foo : unique_ptr<unit_1::Foo>)
+        + AssertNumber() : bool
+    }
+}
+
+Bar --> Foo : uses
+
+@enduml

bazel/rules/rules_score/docs/integration_guide.rst

@@ -15,6 +15,17 @@
 Integration Guide
 =================
 
+Build Flow
+----------
+
+The diagram below shows how input files flow through the Bazel rules to
+produce the final outputs.
+
+.. uml:: _assets/seooc_flow.puml
+   :align: center
+   :alt: SEooC build flow
+   :width: 90%
+
 .. _rule-toolchain-configuration:
 
 Toolchain Setup

bazel/rules/rules_score/docs/overview.rst

@@ -17,16 +17,18 @@ Overview
 
 ``rules_score`` organises safety-critical software artefacts into four groups:
 
-**Documentation Rule** — the generic Sphinx builder underlying all other rules:
+**Documentation Rules** — Sphinx builder and supporting helpers:
 
 - :ref:`sphinx_module <rule-sphinx-module>` — Builds Sphinx HTML from RST/MD sources with dependency merging
+- :ref:`filter_execpath <rule-filter-execpath>` — Resolves a build output path into a Sphinx ``-D`` flag at analysis time *(advanced)*
 
 **Artifact Rules** — declare individual process work products:
 
 - :ref:`assumed_system_requirements <rule-assumed-system-req>` — System-level requirements received from the wider context
 - :ref:`feature_requirements <rule-feature-requirements>` — High-level feature specifications
 - :ref:`component_requirements <rule-component-requirements>` — Component-level requirements
 - :ref:`assumptions_of_use <rule-assumptions-of-use>` — Safety-relevant operating conditions imposed on the integrator
+- :ref:`glossary <rule-glossary>` — Glossary pages included in the generated documentation
 - :ref:`architectural_design <rule-architectural-design>` — Software architecture (static, dynamic, public API)
 - :ref:`unit_design <rule-unit-design>` — Code-level design diagrams scoped to a single unit
 - :ref:`fmea <rule-fmea>` — Failure Mode and Effects Analysis (failure modes, FTA, control measures)
@@ -40,10 +42,61 @@ Overview
 
 All rules support cross-module dependencies for sphinx-needs integration and HTML merging.
 
-Architecture diagram
---------------------
+Quick Reference
+---------------
 
-.. uml:: _assets/rules_score_overview.puml
-   :align: center
-   :alt: Overview of rules_score architecture
-   :width: 100%
+.. list-table::
+   :header-rows: 1
+   :widths: 28 20 52
+
+   * - Rule
+     - Category
+     - User Guide
+   * - :ref:`sphinx_module <rule-sphinx-module>`
+     - Documentation
+     - :doc:`integration_guide`
+   * - :ref:`filter_execpath <rule-filter-execpath>`
+     - Documentation
+     - :ref:`Rule reference <rule-filter-execpath>` *(advanced)*
+   * - :ref:`assumed_system_requirements <rule-assumed-system-req>`
+     - Artifact
+     - :doc:`user_guide/requirements`
+   * - :ref:`feature_requirements <rule-feature-requirements>`
+     - Artifact
+     - :doc:`user_guide/requirements`
+   * - :ref:`component_requirements <rule-component-requirements>`
+     - Artifact
+     - :doc:`user_guide/requirements`
+   * - :ref:`assumptions_of_use <rule-assumptions-of-use>`
+     - Artifact
+     - :doc:`user_guide/assumptions_of_use`
+   * - :ref:`glossary <rule-glossary>`
+     - Artifact
+     - :ref:`Rule reference <rule-glossary>`
+   * - :ref:`architectural_design <rule-architectural-design>`
+     - Artifact
+     - :doc:`user_guide/architectural_design`
+   * - :ref:`unit_design <rule-unit-design>`
+     - Artifact
+     - :doc:`user_guide/unit_design`
+   * - :ref:`fmea <rule-fmea>`
+     - Artifact
+     - :doc:`user_guide/dependability_analysis`
+   * - :ref:`dependability_analysis <rule-dependability-analysis>`
+     - Artifact
+     - :doc:`user_guide/dependability_analysis`
+   * - :ref:`unit <rule-unit>`
+     - Structural
+     - :doc:`user_guide/architectural_design`
+   * - :ref:`component <rule-component>`
+     - Structural
+     - :doc:`user_guide/architectural_design`
+   * - :ref:`dependable_element <rule-dependable-element>`
+     - Structural
+     - :doc:`user_guide/general`
+
+.. seealso::
+
+   :doc:`User Guide <user_guide/index>` — step-by-step guides for every rule
+
+   :doc:`Rule Reference <rule_reference>` — complete attribute reference for all rules