RHDHBUGS-3277: Missing prerequisites and configuration details for Scorecard Aggregation cards

artifacts/snip-tag-for-OCI-package-paths.adoc

@@ -4,8 +4,8 @@ where:
 `<tag>`::
 Enter your {product-very-short} version of {backstage} and the plugin version, in the format `pass:c,a,q[bs_<backstage-version>__<plugin-version>]` (note the double underscore delimiter).
 To find these versions, complete the following steps: 
-.  Find your {backstage} version in the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/latest/html/red_hat_developer_hub_release_notes/pr01[{product-very-short} release notes preface].
-. Locate the plugin version in the {dynamic-plugins-reference-book-link}[Dynamic Plugins Reference guide].
+..  Find your {backstage} version in the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/latest/html/red_hat_developer_hub_release_notes/pr01[{product-very-short} release notes preface].
+.. Locate the plugin version in the {dynamic-plugins-reference-book-link}[Dynamic Plugins Reference guide].
 For example, for {product-very-short} 1.9 based on {backstage} 1.45.3, use the format `pass:c,a,q[bs_1.45.3__<plugin-version>]`.
 +
 [TIP]

assemblies/observability_evaluate-project-health-using-scorecards/assembly-configure-scorecard-cards-on-the-homepage.adoc

@@ -9,15 +9,15 @@ ifdef::context[:parent-context: {context}]
 [role="_abstract"]
 Scorecard visualization cards on the {product} homepage display aggregated metrics to give engineering managers and platform teams immediate visibility into portfolio health trends.
 
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc[leveloffset=+1]
+
 include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-a-default-scorecard-aggregation-card.adoc[leveloffset=+1]
 
 include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-a-status-grouped-tracking-type.adoc[leveloffset=+1]
 
 include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-an-average-tracking-type.adoc[leveloffset=+1]
 
-include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc[leveloffset=+1]
-
-include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc[leveloffset=+1]
-
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]

modules/observability_evaluate-project-health-using-scorecards/proc-configure-a-default-scorecard-aggregation-card.adoc

@@ -8,7 +8,7 @@ Add a standard scorecard summary card to your homepage using default, out-of-the
 
 .Prerequisites
 
-* The scorecard plugin is installed and configured in your {product} instance.
+* You have installed and configured Scorecard backend and frontend plugins, and at least one Scorecard plugin module.
 
 * You have administrator permissions to update application configuration files.
 
@@ -17,23 +17,37 @@ Add a standard scorecard summary card to your homepage using default, out-of-the
 
 . Navigate to your scorecard card block under the `home.page/cards` mount point.
 
-. Update the configuration to use the `aggregationId` property with an established system metric name:
+. Add a new item to the `mountPoints` array under the `scorecard` plugin configuration, setting `aggregationId` to your preferred metric ID.
++
+NOTE: The following example shows how to configure the mount point for a read-only homepage. For customizable homepage configuration, see xref:configure-portfolio-health-on-a-customizable-home-page_configure-scorecard-cards-on-the-homepage[Configure portfolio health on a customizable home page].
 +
 [source,yaml]
 ----
-- mountPoint: home.page/cards
-  importName: ScorecardHomepageCard
-  config:
-    props:
-      aggregationId: "github.open_prs"
-    layouts:
-      xl: { w: 3, h: 6, x: 3 }
-      lg: { w: 4, h: 6, x: 4 }
-      md: { w: 6, h: 6, x: 6 }
-      sm: { w: 12, h: 6 }
-      xs: { w: 12, h: 6 }
-      xxs: { w: 12, h: 6 }
+plugins:
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:<tag>
+    disabled: false
+    pluginConfig:
+      dynamicPlugins:
+        frontend:
+          red-hat-developer-hub.backstage-plugin-scorecard:
+            mountPoints:
+              - mountPoint: home.page/cards
+                importName: ScorecardHomepageCard
+                config:
+                  props:
+                    aggregationId: "github.open_prs"
+                  layouts:
+                    xl: { w: 3, h: 6, x: 3 }
+                    lg: { w: 4, h: 6, x: 4 }
+                    md: { w: 6, h: 6, x: 6 }
+                    sm: { w: 12, h: 6 }
+                    xs: { w: 12, h: 6 }
+                    xxs: { w: 12, h: 6 }
 ----
++
+include::{docdir}/artifacts/snip-tag-for-OCI-package-paths.adoc[]
++
+`aggregationId`:: The aggregation identifier used in the mount point configuration. For default aggregations, this value must match the `metricId` from your installed Scorecard module. For more information, see xref:available-scorecard-metric-providers-and-metric-ids_evaluate-project-health-using-scorecards[Available scorecard metric providers and metric IDs].
 
 . Save the modified configuration file and restart your {product} instance.
 

modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-a-status-grouped-tracking-type.adoc

@@ -8,7 +8,7 @@ Configure a scorecard aggregation card to count entities based on status thresho
 
 .Prerequisites
 
-* The scorecard plugin is installed and configured in your {product} instance.
+* You have installed and configured Scorecard backend and frontend plugins, and at least one Scorecard plugin module.
 
 .Procedure
 . Open your `app-config.yaml` file.
@@ -29,6 +29,8 @@ scorecard:
 
 . Reference your custom aggregation ID inside the homepage card properties block under the `home.page/cards` mount point:
 +
+NOTE: Add this mount point inside the `mountPoints` array of your Scorecard plugin configuration. The following example shows how to configure the mount point for a read-only homepage. For complete configuration examples, see xref:configure-portfolio-health-on-a-customizable-home-page_configure-scorecard-cards-on-the-homepage[Configure portfolio health on a customizable home page] or xref:configure-portfolio-health-on-a-read-only-home-page_configure-scorecard-cards-on-the-homepage[Configure portfolio health on a read-only home page].
++
 [source,yaml]
 ----
 - mountPoint: home.page/cards

modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-an-average-tracking-type.adoc

@@ -6,7 +6,8 @@
 Configure a scorecard aggregation card to calculate a single weighted portfolio score across multiple components.
 
 .Prerequisites
-* The scorecard plugin is installed and configured in your {product} instance.
+
+* You have installed and configured Scorecard backend and frontend plugins, and at least one Scorecard plugin module.
 
 .Procedure
 
@@ -61,6 +62,8 @@ options:
 
 . Reference your average tracking aggregation ID inside the homepage card properties block under the `home.page/cards` mount point:
 +
+NOTE: Add this mount point inside the `mountPoints` array of your Scorecard plugin configuration. The following example shows how to configure the mount point for a read-only homepage. For complete configuration examples, see xref:configure-portfolio-health-on-a-customizable-home-page_configure-scorecard-cards-on-the-homepage[Configure portfolio health on a customizable home page] or xref:configure-portfolio-health-on-a-read-only-home-page_configure-scorecard-cards-on-the-homepage[Configure portfolio health on a read-only home page].
++
 [source,yaml]
 ----
 - mountPoint: home.page/cards