From af2a78b6474bc09de612f3c38118850f5c80fa05 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Wed, 13 May 2026 16:57:59 -0400
Subject: [PATCH 01/12] RHIDP-2409:  Improve Documentation for Entities:
 Mandatory Fields, Entity Tabs, and Conditional Visibility

---
 .../assembly-rhdh-default-configuration.adoc  |  4 ++
 .../proc-define-catalog-entities.adoc         | 49 +++++++++++++
 ...f-catalog-entity-descriptor-reference.adoc | 72 +++++++++++++++++++
 3 files changed, 125 insertions(+)
 create mode 100644 modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
 create mode 100644 modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc

diff --git a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
index 9780be0abba..788ab8e29c7 100644
--- a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
+++ b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
@@ -16,6 +16,10 @@ include::../modules/configure_configuring-rhdh/con-automated-operator-features.a
 
 include::../modules/configure_configuring-rhdh/ref-time-syntax-in-rhdh.adoc[leveloffset=+1]
 
+include::../modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc[leveloffset=+1]
+
+include::../modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc[leveloffset=+1]
+
 :context: {previouscontext}
 :!previouscontext:
 
diff --git a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
new file mode 100644
index 00000000000..99604ab723b
--- /dev/null
+++ b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
@@ -0,0 +1,49 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="define-catalog-entities_{context}"]
+= Define catalog entities
+
+[role="_abstract"]
+Populate the {product-title} software catalog by creating YAML descriptor files for components, APIs, and resources.
+
+.Prerequisites
+
+* You have an active {product-title} instance.
+* You have access to a Git repository to host your catalog descriptor files.
+
+.Procedure
+
+. Create a YAML file named `catalog-info.yaml` in the root directory of your software component.
+
+. Define the base metadata for the entity using the following template:
++
+[source,yaml]
+----
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-component
+  description: A description of your component
+spec:
+  type: service
+  lifecycle: production
+  owner: group:example-team
+----
+
+. To enable specific user interface elements, configure the `spec.type` or add annotations:
+
+** To display the *API* tab, set `spec.type` to `service`.
+
+** To display the *Docs* tab, add the `backstage.io/techdocs-ref` annotation to the `metadata` section.
+
+. Save the file and commit it to your Git repository.
+
+.Verification
+
+. Log in to your {product-title} instance.
+
+. Navigate to the *Catalog* page.
+
+. Select your component and verify that all mandatory fields are correctly displayed in the *About* card.
+
+. Confirm that the expected navigation tabs, such as *API* or *Docs*, are visible based on your configuration.
diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
new file mode 100644
index 00000000000..dd017c4a597
--- /dev/null
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -0,0 +1,72 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="catalog-entity-descriptor-reference_{context}"]
+= Catalog entity descriptor reference
+
+[role="_abstract"]
+Use these reference tables to identify required YAML attributes and mandatory fields for registering components in the {product-title} catalog.
+
+== Mandatory fields for catalog entities
+
+The following table lists the fields required for each entity kind supported by {product-title}. If you do not provide a mandatory field, the catalog processor fails to validate the entity and throws a `TypeError`.
+
+== Mandatory fields by entity kind
+[cols="1,3", options="header"]
+|===
+| Entity Kind | Mandatory Fields
+
+| *Component*
+| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.lifecycle`, `spec.owner`
+
+| *Template*
+| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.parameters`, `spec.steps`
+
+| *API*
+| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.lifecycle`, `spec.owner`, `spec.definition`
+
+| *Group*
+| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.children` (can be empty)
+
+| *User*
+| `apiVersion`, `kind`, `metadata.name`, `spec.memberOf` (can be empty)
+
+| *Resource*
+| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.owner`
+
+| *System*
+| `apiVersion`, `kind`, `metadata.name`, `spec.owner`
+
+| *Domain*
+| `apiVersion`, `kind`, `metadata.name`, `spec.owner`
+
+| *Location*
+| `apiVersion`, `kind`, `metadata.name`, `spec` (can be an empty object `{}`)
+|===
+
+== Conditional UI behavior for components
+
+The visibility of navigation tabs in the {product-title} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
+
+== Component UI behavior mapping
+[cols="1,1,2", options="header"]
+|===
+| Field or Annotation | Setting | UI Change
+
+| `spec.type`
+| `service`
+| The *API* tab is visible in the component interface.
+
+| `spec.type`
+| `website` or `library`
+| The *API* tab is hidden, but provided and consumed APIs remain visible under the *Dependencies* tab.
+
+| `metadata.annotations`
+| `backstage.io/techdocs-ref`
+| The *Docs* tab is visible, providing access to TechDocs documentation.
+|===
+
+[role="_additional-resources"]
+== Additional resources
+
+* For information about establishing ownership relations in the catalog graph, see link:https://backstage.io/docs/features/software-catalog/descriptor-format/#spec-field[Upstream descriptor documentation].
+* To learn more about namespace assignments, see link:https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-the-metadata[Common metadata fields].
\ No newline at end of file

From dead9bcbb0ed827c35294a690ab8cedacd12243f Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Thu, 14 May 2026 08:11:23 -0400
Subject: [PATCH 02/12] RHIDP-2409: updated attributes

---
 .../proc-define-catalog-entities.adoc                       | 6 +++---
 .../ref-catalog-entity-descriptor-reference.adoc            | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
index 99604ab723b..0f68fdf4e69 100644
--- a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
+++ b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
@@ -4,11 +4,11 @@
 = Define catalog entities
 
 [role="_abstract"]
-Populate the {product-title} software catalog by creating YAML descriptor files for components, APIs, and resources.
+Populate the {product} software catalog by creating YAML descriptor files for components, APIs, and resources.
 
 .Prerequisites
 
-* You have an active {product-title} instance.
+* You have an active {product-very-short} instance.
 * You have access to a Git repository to host your catalog descriptor files.
 
 .Procedure
@@ -40,7 +40,7 @@ spec:
 
 .Verification
 
-. Log in to your {product-title} instance.
+. Log in to your {product-very-short} instance.
 
 . Navigate to the *Catalog* page.
 
diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index dd017c4a597..9708f817d3d 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -4,11 +4,11 @@
 = Catalog entity descriptor reference
 
 [role="_abstract"]
-Use these reference tables to identify required YAML attributes and mandatory fields for registering components in the {product-title} catalog.
+Use these reference tables to identify required YAML attributes and mandatory fields for registering components in the {product} catalog.
 
 == Mandatory fields for catalog entities
 
-The following table lists the fields required for each entity kind supported by {product-title}. If you do not provide a mandatory field, the catalog processor fails to validate the entity and throws a `TypeError`.
+The following table lists the fields required for each entity kind supported by {product-very-short}. If you do not provide a mandatory field, the catalog processor fails to validate the entity and throws a `TypeError`.
 
 == Mandatory fields by entity kind
 [cols="1,3", options="header"]
@@ -45,7 +45,7 @@ The following table lists the fields required for each entity kind supported by
 
 == Conditional UI behavior for components
 
-The visibility of navigation tabs in the {product-title} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
+The visibility of navigation tabs in the {product-very-short} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
 
 == Component UI behavior mapping
 [cols="1,1,2", options="header"]

From 3e8ca87deabb45cbcebf68f42a9df585938d0d70 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 15 May 2026 17:44:21 -0400
Subject: [PATCH 03/12] RHIDP-2409: edits from dev review

---
 .../proc-define-catalog-entities.adoc         | 31 +++++++++----
 ...f-catalog-entity-descriptor-reference.adoc | 45 ++++++++++++++-----
 2 files changed, 55 insertions(+), 21 deletions(-)

diff --git a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
index 0f68fdf4e69..e89fee6d049 100644
--- a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
+++ b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
@@ -6,6 +6,11 @@
 [role="_abstract"]
 Populate the {product} software catalog by creating YAML descriptor files for components, APIs, and resources.
 
+[IMPORTANT]
+====
+Tab visibility logic for *Provided APIs* and *Consumed APIs* applies exclusively to entities of `kind: Component`. Other entity kinds follow distinct schema rules and UI layouts.
+====
+
 .Prerequisites
 
 * You have an active {product-very-short} instance.
@@ -15,26 +20,34 @@ Populate the {product} software catalog by creating YAML descriptor files for co
 
 . Create a YAML file named `catalog-info.yaml` in the root directory of your software component.
 
-. Define the base metadata for the entity using the following template:
+. Define the entity by using the descriptor format. 
+
+. Set the `kind` field to `Component`, `API`, `Resource`, or `Location`. 
+
+. For `kind: Component`, specify the `spec.type` to determine user interface (UI) visibility.
 +
 [source,yaml]
 ----
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
-  name: example-component
-  description: A description of your component
+  name: example-service
+  annotations:
+    backstage.io/techdocs-ref: dir:. 
 spec:
   type: service
   lifecycle: production
-  owner: group:example-team
+  owner: group:default/engineering-team
 ----
++
+where:
++
+`metadata.annotations.backstage.io/techdocs-ref`:: Specifies the `techdocs-ref` annotation that identifies the source directory for the Docs tab.
+`spec.type.`:: Specifies the service type that enables the *Provided APIs* and *Consumed APIs* tabs.
 
-. To enable specific user interface elements, configure the `spec.type` or add annotations:
-
-** To display the *API* tab, set `spec.type` to `service`.
-
-** To display the *Docs* tab, add the `backstage.io/techdocs-ref` annotation to the `metadata` section.
+. Optional: Configure the *Docs* tab for the entity:
+.. Add the `backstage.io/techdocs-ref` annotation to the entity metadata.
+.. Ensure the cluster administrator has configured the `TechDocs` plugin and a compatible storage backend. If these are not configured, the *Docs* tab will not appear.
 
 . Save the file and commit it to your Git repository.
 
diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 9708f817d3d..5a2b77adc96 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -6,11 +6,10 @@
 [role="_abstract"]
 Use these reference tables to identify required YAML attributes and mandatory fields for registering components in the {product} catalog.
 
-== Mandatory fields for catalog entities
+== Mandatory fields by entity kind
 
 The following table lists the fields required for each entity kind supported by {product-very-short}. If you do not provide a mandatory field, the catalog processor fails to validate the entity and throws a `TypeError`.
 
-== Mandatory fields by entity kind
 [cols="1,3", options="header"]
 |===
 | Entity Kind | Mandatory Fields
@@ -40,33 +39,55 @@ The following table lists the fields required for each entity kind supported by
 | `apiVersion`, `kind`, `metadata.name`, `spec.owner`
 
 | *Location*
-| `apiVersion`, `kind`, `metadata.name`, `spec` (can be an empty object `{}`)
+| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.target`
 |===
 
 == Conditional UI behavior for components
 
+[IMPORTANT]
+====
+Tab visibility logic for *Provided APIs* and *Consumed APIs* applies exclusively to entities of `kind: Component`. Other entity kinds follow distinct schema rules and UI layouts.
+====
+
 The visibility of navigation tabs in the {product-very-short} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
 
-== Component UI behavior mapping
+.Component UI behavior mapping
 [cols="1,1,2", options="header"]
 |===
 | Field or Annotation | Setting | UI Change
 
 | `spec.type`
 | `service`
-| The *API* tab is visible in the component interface.
+| Enables the **Provided APIs** and **Consumed APIs** tabs.
 
 | `spec.type`
 | `website` or `library`
-| The *API* tab is hidden, but provided and consumed APIs remain visible under the *Dependencies* tab.
+| Hides the API tabs, but displays provided and consumed APIs under the **Dependencies** tab.
 
 | `metadata.annotations`
 | `backstage.io/techdocs-ref`
-| The *Docs* tab is visible, providing access to TechDocs documentation.
+| Enables the **Docs** tab.
 |===
 
-[role="_additional-resources"]
-== Additional resources
-
-* For information about establishing ownership relations in the catalog graph, see link:https://backstage.io/docs/features/software-catalog/descriptor-format/#spec-field[Upstream descriptor documentation].
-* To learn more about namespace assignments, see link:https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-the-metadata[Common metadata fields].
\ No newline at end of file
+== Spec fields for locations
+
+While the `spec` block for a `kind: Location` entity can technically be empty, you must define the following fields for practical use:
+
+`type`:: Specifies the location engine type, such as `url`.
+`target`:: Specifies the explicit URI pointing to the target data, such as a Git repository URL. This field is required.
+
+[source,yaml,subs="+attributes"]
+----
+apiVersion: backstage.io/v1alpha1
+kind: Location
+metadata:
+  name: organizational-catalog-targets
+spec:
+  type: url
+  target: https://github.com/org/repo/blob/main/catalog-info.yaml
+----
++
+where
++
+`spec.type`:: Specifies the location engine type, which is typically `url`.
+`spec.target`:: Specifies the URI pointing to the entity data to be registered.
\ No newline at end of file

From e6ac11b08c57113a015f9982cc31deb76a1ddbe8 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 15 May 2026 17:53:59 -0400
Subject: [PATCH 04/12] RHDHBUGS-2409: revised heading that failed CQA check

---
 .../ref-catalog-entity-descriptor-reference.adoc                | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 5a2b77adc96..5b4c529f863 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -51,7 +51,7 @@ Tab visibility logic for *Provided APIs* and *Consumed APIs* applies exclusively
 
 The visibility of navigation tabs in the {product-very-short} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
 
-.Component UI behavior mapping
+== Component UI behavior mapping
 [cols="1,1,2", options="header"]
 |===
 | Field or Annotation | Setting | UI Change

From c0708768147982ea3b8b39da7f6aac19c4a38725 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 15 May 2026 18:02:57 -0400
Subject: [PATCH 05/12] RHDHBUGS-2409: minor edit

---
 .../ref-catalog-entity-descriptor-reference.adoc                | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 5b4c529f863..2c3d90d0053 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -87,7 +87,7 @@ spec:
   target: https://github.com/org/repo/blob/main/catalog-info.yaml
 ----
 +
-where
+where:
 +
 `spec.type`:: Specifies the location engine type, which is typically `url`.
 `spec.target`:: Specifies the URI pointing to the entity data to be registered.
\ No newline at end of file

From f4072e9f6b61672b6ae013b6cad5d38545319630 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 15 May 2026 18:11:33 -0400
Subject: [PATCH 06/12] RHDHBUGS-2409: tshooing format

---
 .../ref-catalog-entity-descriptor-reference.adoc                | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 2c3d90d0053..894c1773827 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -88,6 +88,6 @@ spec:
 ----
 +
 where:
-+
+
 `spec.type`:: Specifies the location engine type, which is typically `url`.
 `spec.target`:: Specifies the URI pointing to the entity data to be registered.
\ No newline at end of file

From 34b6609598c89bd4244b88acd4c8514e26442e95 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 15 May 2026 18:22:13 -0400
Subject: [PATCH 07/12] RHDHBUGS-2409: tshooting HTML issue

---
 .../ref-catalog-entity-descriptor-reference.adoc                | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 894c1773827..2d1db7cc83b 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -86,7 +86,7 @@ spec:
   type: url
   target: https://github.com/org/repo/blob/main/catalog-info.yaml
 ----
-+
+
 where:
 
 `spec.type`:: Specifies the location engine type, which is typically `url`.

From 1e81937c70b807cb28bf01569fa362cdecc4dfcf Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Mon, 18 May 2026 13:22:18 -0400
Subject: [PATCH 08/12] RHIDP-2409: added new topics based on review input

---
 ...oc-define-api-entities-in-the-catalog.adoc | 37 ++++++++
 .../proc-define-catalog-entities.adoc         |  2 +-
 .../proc-define-component-in-the-catalog.adoc | 35 ++++++++
 .../proc-define-locations-in-the-catalog.adoc | 42 +++++++++
 .../proc-define-resources-in-the-catalog.adoc | 41 +++++++++
 ...f-catalog-entity-descriptor-reference.adoc | 88 +++++++++----------
 6 files changed, 198 insertions(+), 47 deletions(-)
 create mode 100644 modules/configure_configuring-rhdh/proc-define-api-entities-in-the-catalog.adoc
 create mode 100644 modules/configure_configuring-rhdh/proc-define-component-in-the-catalog.adoc
 create mode 100644 modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc
 create mode 100644 modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc

diff --git a/modules/configure_configuring-rhdh/proc-define-api-entities-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-api-entities-in-the-catalog.adoc
new file mode 100644
index 00000000000..9339c0d1c34
--- /dev/null
+++ b/modules/configure_configuring-rhdh/proc-define-api-entities-in-the-catalog.adoc
@@ -0,0 +1,37 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="define-apis-in-the-catalog_{context}"]
+= Define APIs in the catalog
+
+[role="_abstract"]
+Expose your interfaces for consumption within the hub by registering an API entity descriptor.
+
+.Procedure
+
+. Create a YAML file named `catalog-info.yaml` in your repository.
+
+. Add the following API schema configuration to the file:
++
+[source,yaml]
+----
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: example-api
+spec:
+  type: openapi
+  lifecycle: production
+  owner: group:example-team
+  definition: |
+    openapi: "3.0.0"
+    info:
+      title: Example API
+      version: "1.0.0"
+    paths: {}
+----
+
+. Save and commit the file to your Git repository.
+
+.Verification
+
+* Navigate to the *Catalog* page in the UI, filter by *API*, and verify your endpoint definition is visible.
\ No newline at end of file
diff --git a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
index e89fee6d049..05dc56b3b0c 100644
--- a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
+++ b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
@@ -6,7 +6,7 @@
 [role="_abstract"]
 Populate the {product} software catalog by creating YAML descriptor files for components, APIs, and resources.
 
-[IMPORTANT]
+[NOTE]
 ====
 Tab visibility logic for *Provided APIs* and *Consumed APIs* applies exclusively to entities of `kind: Component`. Other entity kinds follow distinct schema rules and UI layouts.
 ====
diff --git a/modules/configure_configuring-rhdh/proc-define-component-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-component-in-the-catalog.adoc
new file mode 100644
index 00000000000..d32acc287c3
--- /dev/null
+++ b/modules/configure_configuring-rhdh/proc-define-component-in-the-catalog.adoc
@@ -0,0 +1,35 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="define-software-component-in-the-catalog_{context}"]
+= Define software components in the catalog
+
+[role="_abstract"]
+Populate your software catalog by creating and configuring a YAML descriptor file that defines your application or service. 
+
+.Prerequisites
+
+* You have access to a Git repository to host your catalog files.
+
+.Procedure
+
+. Create a YAML file named `catalog-info.yaml` in the root directory of your repository.
+
+. Add the following component configuration to the file:
++
+[source,yaml]
+----
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-service
+spec:
+  type: service
+  lifecycle: production
+  owner: group:example-team
+----
+
+. Save and commit the file to your Git repository.
+
+.Verification
+
+* Navigate to the *Catalog* page in the UI, filter by *Component*, and verify your service is visible.
diff --git a/modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc
new file mode 100644
index 00000000000..77797874af0
--- /dev/null
+++ b/modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc
@@ -0,0 +1,42 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="define-locations-in-the-catalog_{context}"]
+= Define locations in the catalog
+
+[role="_abstract"]
+Import multiple entity descriptors into the software catalog by creating a YAML descriptor file that defines a location entity.
+
+.Prerequisites
+
+* You have an active {product-title} instance.
+* You have access to a Git repository to host your catalog descriptor files.
+
+.Procedure
+
+. Create a YAML file named `catalog-info.yaml` in your centralized repository folder.
+
+. Add the location configuration to the file, using the `spec.targets` array to point to your individual target configurations:
++
+[source,yaml]
+----
+apiVersion: backstage.io/v1alpha1
+kind: Location
+metadata:
+  name: example-location
+spec:
+  type: url
+  targets:
+    - https://github.com/example-org/example-repo/blob/main/catalog-info.yaml
+----
+
+. Save the file and commit it to your Git repository.
+
+.Verification
+
+. Log in to your {product-title} instance web console.
+
+. Navigate to the *Catalog* page using the left sidebar menu.
+
+. Locate the *Filters* panel on the left side of the catalog view and click *Location*.
+
+. Confirm that your newly defined location entity appears in the list and that the target data components are successfully discovered without validation errors.
\ No newline at end of file
diff --git a/modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc
new file mode 100644
index 00000000000..cc561c84e88
--- /dev/null
+++ b/modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc
@@ -0,0 +1,41 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="define-resources-in-the-catalog_{context}"]
+= Define resources in the catalog
+
+[role="_abstract"]
+Track infrastructure dependencies by creating a YAML descriptor file to register a resource entity in the software catalog.
+
+.Prerequisites
+
+* You have an active {product-title} instance.
+* You have access to a Git repository to host your catalog descriptor files.
+
+.Procedure
+
+. Create a YAML file named `catalog-info.yaml` in your project or infrastructure repository directory.
+
+. Add the following resource configuration to the file:
++
+[source,yaml]
+----
+apiVersion: backstage.io/v1alpha1
+kind: Resource
+metadata:
+  name: example-database
+spec:
+  type: database
+  owner: group:example-team
+----
+
+. Save the file and commit it to your Git repository.
+
+.Verification
+
+. Log in to your {product-title} instance web console.
+
+. Navigate to the *Catalog* page using the left sidebar menu.
+
+. Locate the *Filters* panel on the left side of the catalog view and click *Resource*.
+
+. Confirm that your newly defined resource appears in the filtered list.
\ No newline at end of file
diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 2d1db7cc83b..8bf2adef513 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -6,50 +6,69 @@
 [role="_abstract"]
 Use these reference tables to identify required YAML attributes and mandatory fields for registering components in the {product} catalog.
 
-== Mandatory fields by entity kind
 
-The following table lists the fields required for each entity kind supported by {product-very-short}. If you do not provide a mandatory field, the catalog processor fails to validate the entity and throws a `TypeError`.
 
-[cols="1,3", options="header"]
+
+
+
+
+
+
+
+== Mandatory fields for catalog entities
+
+The following table lists the fields required for each entity kind supported by {product-title}. If you do not provide a mandatory field, the catalog processor fails to validate the entity and throws a `TypeError`.
+
+== Mandatory fields by entity kind
+[cols="1,2,2", options="header"]
 |===
-| Entity Kind | Mandatory Fields
+| Entity Kind | Mandatory Fields | Practical Usage and Optional Fields
 
-| *Component*
+| **Component**
 | `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.lifecycle`, `spec.owner`
+| —
 
-| *Template*
+| **Template**
 | `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.parameters`, `spec.steps`
+| —
 
-| *API*
+| **API**
 | `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.lifecycle`, `spec.owner`, `spec.definition`
+| —
 
-| *Group*
+| **Group**
 | `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.children` (can be empty)
+| —
 
-| *User*
+| **User**
 | `apiVersion`, `kind`, `metadata.name`, `spec.memberOf` (can be empty)
+| —
 
-| *Resource*
+| **Resource**
 | `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.owner`
+| —
 
-| *System*
+| **System**
 | `apiVersion`, `kind`, `metadata.name`, `spec.owner`
+| —
 
-| *Domain*
+| **Domain**
 | `apiVersion`, `kind`, `metadata.name`, `spec.owner`
+| —
+
+| **Location**
+| `apiVersion`, `kind`, `metadata.name`, `spec`
+| While `spec` can technically be empty (`{}`), practical usage requires pointing to target definitions using these optional fields:
 
-| *Location*
-| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.target`
+* `spec.type`: The location type, such as `url` or `file`.
+* `spec.target`: A single string pointer to a target configuration.
+* `spec.targets`: An array of one or more string pointers to target configurations.
+* `spec.presence`: Specifies whether the target must exist (`required`) or can be missing (`optional`).
 |===
 
 == Conditional UI behavior for components
 
-[IMPORTANT]
-====
-Tab visibility logic for *Provided APIs* and *Consumed APIs* applies exclusively to entities of `kind: Component`. Other entity kinds follow distinct schema rules and UI layouts.
-====
-
-The visibility of navigation tabs in the {product-very-short} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
+The visibility of navigation tabs in the {product-title} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
 
 == Component UI behavior mapping
 [cols="1,1,2", options="header"]
@@ -58,36 +77,13 @@ The visibility of navigation tabs in the {product-very-short} interface is deter
 
 | `spec.type`
 | `service`
-| Enables the **Provided APIs** and **Consumed APIs** tabs.
+| The **API** tab is visible in the component interface.
 
 | `spec.type`
 | `website` or `library`
-| Hides the API tabs, but displays provided and consumed APIs under the **Dependencies** tab.
+| The **API** tab is hidden, but provided and consumed APIs remain visible under the **Dependencies** tab.
 
 | `metadata.annotations`
 | `backstage.io/techdocs-ref`
-| Enables the **Docs** tab.
+| The **Docs** tab is visible, providing access to TechDocs documentation.
 |===
-
-== Spec fields for locations
-
-While the `spec` block for a `kind: Location` entity can technically be empty, you must define the following fields for practical use:
-
-`type`:: Specifies the location engine type, such as `url`.
-`target`:: Specifies the explicit URI pointing to the target data, such as a Git repository URL. This field is required.
-
-[source,yaml,subs="+attributes"]
-----
-apiVersion: backstage.io/v1alpha1
-kind: Location
-metadata:
-  name: organizational-catalog-targets
-spec:
-  type: url
-  target: https://github.com/org/repo/blob/main/catalog-info.yaml
-----
-
-where:
-
-`spec.type`:: Specifies the location engine type, which is typically `url`.
-`spec.target`:: Specifies the URI pointing to the entity data to be registered.
\ No newline at end of file

From b2211c01a8d6767b920ff1f995f1b4a433c5dac3 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Mon, 18 May 2026 13:28:15 -0400
Subject: [PATCH 09/12] RHDHBUGS-2409: updated assembly to include new topics

---
 .../assembly-rhdh-default-configuration.adoc              | 8 ++++++++
 ...-catalog.adoc => proc-define-apis-in-the-catalog.adoc} | 0
 ...> proc-define-software-components-in-the-catalog.adoc} | 2 +-
 3 files changed, 9 insertions(+), 1 deletion(-)
 rename modules/configure_configuring-rhdh/{proc-define-api-entities-in-the-catalog.adoc => proc-define-apis-in-the-catalog.adoc} (100%)
 rename modules/configure_configuring-rhdh/{proc-define-component-in-the-catalog.adoc => proc-define-software-components-in-the-catalog.adoc} (93%)

diff --git a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
index 788ab8e29c7..8a1ef7429ec 100644
--- a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
+++ b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
@@ -18,6 +18,14 @@ include::../modules/configure_configuring-rhdh/ref-time-syntax-in-rhdh.adoc[leve
 
 include::../modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc[leveloffset=+1]
 
+include::../modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc[leveloffset=+1]
+
+include::../modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc[leveloffset=+1]
+
+include::../modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc[leveloffset=+1]
+
+include::../modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc[leveloffset=+1]
+
 include::../modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc[leveloffset=+1]
 
 :context: {previouscontext}
diff --git a/modules/configure_configuring-rhdh/proc-define-api-entities-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc
similarity index 100%
rename from modules/configure_configuring-rhdh/proc-define-api-entities-in-the-catalog.adoc
rename to modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc
diff --git a/modules/configure_configuring-rhdh/proc-define-component-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc
similarity index 93%
rename from modules/configure_configuring-rhdh/proc-define-component-in-the-catalog.adoc
rename to modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc
index d32acc287c3..37dffcb2a94 100644
--- a/modules/configure_configuring-rhdh/proc-define-component-in-the-catalog.adoc
+++ b/modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="define-software-component-in-the-catalog_{context}"]
+[id="define-software-components-in-the-catalog_{context}"]
 = Define software components in the catalog
 
 [role="_abstract"]

From 90d85531c1bcc58bb4d13b31a19c4cc9a5a4bbfe Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Mon, 18 May 2026 15:05:57 -0400
Subject: [PATCH 10/12] RHDHBUGS-2489: minor edit

---
 .../ref-catalog-entity-descriptor-reference.adoc             | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 8bf2adef513..85682b5dac6 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -87,3 +87,8 @@ The visibility of navigation tabs in the {product-title} interface is determined
 | `backstage.io/techdocs-ref`
 | The **Docs** tab is visible, providing access to TechDocs documentation.
 |===
+
+[NOTE]
+====
+For the *Docs* tab to successfully render technical documentation, the TechDocs plugin must be configured correctly in your instance.
+====
\ No newline at end of file

From bf85fb761ad3ef924c23c1a8704319bd162487fa Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Tue, 19 May 2026 12:38:29 -0400
Subject: [PATCH 11/12] RHIDP-2409: minor edits from review

---
 .../proc-define-apis-in-the-catalog.adoc      |  2 +-
 .../proc-define-catalog-entities.adoc         | 62 -------------------
 ...f-catalog-entity-descriptor-reference.adoc |  2 +-
 3 files changed, 2 insertions(+), 64 deletions(-)
 delete mode 100644 modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc

diff --git a/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc
index 9339c0d1c34..9c0e52b11a6 100644
--- a/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc
+++ b/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc
@@ -4,7 +4,7 @@
 = Define APIs in the catalog
 
 [role="_abstract"]
-Expose your interfaces for consumption within the hub by registering an API entity descriptor.
+Expose your interfaces for consumption within the hub by registering an API entity.
 
 .Procedure
 
diff --git a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc b/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
deleted file mode 100644
index 05dc56b3b0c..00000000000
--- a/modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-:_mod-docs-content-type: PROCEDURE
-
-[id="define-catalog-entities_{context}"]
-= Define catalog entities
-
-[role="_abstract"]
-Populate the {product} software catalog by creating YAML descriptor files for components, APIs, and resources.
-
-[NOTE]
-====
-Tab visibility logic for *Provided APIs* and *Consumed APIs* applies exclusively to entities of `kind: Component`. Other entity kinds follow distinct schema rules and UI layouts.
-====
-
-.Prerequisites
-
-* You have an active {product-very-short} instance.
-* You have access to a Git repository to host your catalog descriptor files.
-
-.Procedure
-
-. Create a YAML file named `catalog-info.yaml` in the root directory of your software component.
-
-. Define the entity by using the descriptor format. 
-
-. Set the `kind` field to `Component`, `API`, `Resource`, or `Location`. 
-
-. For `kind: Component`, specify the `spec.type` to determine user interface (UI) visibility.
-+
-[source,yaml]
-----
-apiVersion: backstage.io/v1alpha1
-kind: Component
-metadata:
-  name: example-service
-  annotations:
-    backstage.io/techdocs-ref: dir:. 
-spec:
-  type: service
-  lifecycle: production
-  owner: group:default/engineering-team
-----
-+
-where:
-+
-`metadata.annotations.backstage.io/techdocs-ref`:: Specifies the `techdocs-ref` annotation that identifies the source directory for the Docs tab.
-`spec.type.`:: Specifies the service type that enables the *Provided APIs* and *Consumed APIs* tabs.
-
-. Optional: Configure the *Docs* tab for the entity:
-.. Add the `backstage.io/techdocs-ref` annotation to the entity metadata.
-.. Ensure the cluster administrator has configured the `TechDocs` plugin and a compatible storage backend. If these are not configured, the *Docs* tab will not appear.
-
-. Save the file and commit it to your Git repository.
-
-.Verification
-
-. Log in to your {product-very-short} instance.
-
-. Navigate to the *Catalog* page.
-
-. Select your component and verify that all mandatory fields are correctly displayed in the *About* card.
-
-. Confirm that the expected navigation tabs, such as *API* or *Docs*, are visible based on your configuration.
diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
index 85682b5dac6..82cc543440e 100644
--- a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
+++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc
@@ -66,7 +66,7 @@ The following table lists the fields required for each entity kind supported by
 * `spec.presence`: Specifies whether the target must exist (`required`) or can be missing (`optional`).
 |===
 
-== Conditional UI behavior for components
+== Conditional UI behavior for component entities
 
 The visibility of navigation tabs in the {product-title} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor.
 

From 43a7e16062dec93725f5e0abef3976d8ba4c358f Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Tue, 19 May 2026 12:50:32 -0400
Subject: [PATCH 12/12] RHIDP-2409: removed proc from assembly

---
 .../assembly-rhdh-default-configuration.adoc                    | 2 --
 1 file changed, 2 deletions(-)

diff --git a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
index 8a1ef7429ec..ac161d16289 100644
--- a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
+++ b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc
@@ -26,8 +26,6 @@ include::../modules/configure_configuring-rhdh/proc-define-resources-in-the-cata
 
 include::../modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc[leveloffset=+1]
 
-include::../modules/configure_configuring-rhdh/proc-define-catalog-entities.adoc[leveloffset=+1]
-
 :context: {previouscontext}
 :!previouscontext: