diff --git a/content/contribute/contribute-to-docs.adoc b/content/contribute/contribute-to-docs.adoc
index 3a215e6b1..e09b75d96 100644
--- a/content/contribute/contribute-to-docs.adoc
+++ b/content/contribute/contribute-to-docs.adoc
@@ -11,6 +11,16 @@ include::modules/comm-attributes.adoc[]
 
 //Use the Contributor's guide to learn about ways to contribute to the Validated Patterns, to understand the prerequisites and toolchain required for contribution, and to follow some basic documentation style and structure guidelines.
 
+[id="pattern-metadata-in-docs"]
+== Pattern metadata in the docs repository
+
+When a pattern maintainer updates `pattern-metadata.yaml`, a GitHub Actions workflow opens a pull request in this repository.
+The workflow updates generated modules under `modules/<pattern-name>/metadata-<pattern-name>.adoc`.
+Do not edit these files by hand unless documented as a manual exception (for example, when a pattern has empty sizing requirements).
+
+Cluster sizing pages include the generated module and `modules/cluster-sizing-template.adoc` to render sizing tables.
+For more information about the metadata schema and sync workflow, see link:/contribute/pattern-metadata/[Pattern metadata] and link:/contribute/pattern-metadata-documentation-sync/[Metadata and documentation].
+
 include::modules/contributing.adoc[leveloffset=+1]
 include::modules/tools-and-setup.adoc[leveloffset=+1]
 include::modules/doc-guidelines.adoc[leveloffset=+1]
diff --git a/content/contribute/creating-a-pattern.adoc b/content/contribute/creating-a-pattern.adoc
index 0a1be9aa0..d7d05f440 100644
--- a/content/contribute/creating-a-pattern.adoc
+++ b/content/contribute/creating-a-pattern.adoc
@@ -37,6 +37,15 @@ Therefore the question really is: How do I move my successful architecture solut
 * Create a new branch on your new pattern to perform the initial changes.
 * Deploy the initial new pattern to the cluster.
 
+[id="adding-pattern-metadata"]
+== Adding pattern metadata
+
+Add `pattern-metadata.yaml` to the top-level directory of your pattern repository.
+The documentation site and quality engineering workflows use this file as the source of truth for pattern identity, tier, links, and cluster sizing.
+
+Copy an existing file from link:https://github.com/validatedpatterns/multicloud-gitops/blob/main/pattern-metadata.yaml[multicloud-gitops] as a starting point, then update the values for your pattern.
+For more information about metadata fields, the sync workflow, and troubleshooting, see link:/contribute/pattern-metadata/[Pattern metadata].
+
 == Moving to the validated patterns framework
 
 One of the first things that you should do is look at your current implementation of your workload and identify the Kubernetes manifests that are involved in order to run the workloads.
diff --git a/content/contribute/pattern-metadata-documentation-sync.adoc b/content/contribute/pattern-metadata-documentation-sync.adoc
new file mode 100644
index 000000000..68215069b
--- /dev/null
+++ b/content/contribute/pattern-metadata-documentation-sync.adoc
@@ -0,0 +1,125 @@
+---
+menu:
+  contribute:
+    parent: Pattern metadata
+title: Metadata and documentation
+weight: 44
+aliases: /pattern-metadata-documentation-sync/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+[id="pattern-metadata-documentation"]
+= Metadata and documentation
+
+This page describes how `pattern-metadata.yaml` feeds validatedpatterns.io cluster sizing pages and how it relates to Hugo frontmatter on pattern landing pages.
+
+[id="how-the-docs-site-uses-metadata"]
+== How the documentation site uses metadata
+
+When `pattern-metadata.yaml` changes in a pattern repository, an automated workflow can sync those values into this documentation repository.
+
+. A GitHub Actions workflow in the pattern repository runs when `pattern-metadata.yaml` is updated on the `main` branch.
+. The workflow calls the reusable `metadata-docs.yml` workflow from the link:https://github.com/validatedpatterns/docs[`validatedpatterns/docs` repository].
+. The `utils/flatten_yaml.rb` script flattens the YAML structure into AsciiDoc attributes (preserving the source nesting, including `platform`).
+. The workflow opens a pull request against `validatedpatterns/docs` that updates `modules/<pattern-name>/metadata-<pattern-name>.adoc`.
+. Pattern cluster sizing pages include that generated module and the shared `modules/cluster-sizing-template.adoc` template to render sizing tables.
+
+[NOTE]
+====
+Adding or updating `pattern-metadata.yaml` does not create documentation pages by itself.
+You still need pattern content under `content/patterns/<pattern-name>/` in the docs repository, including a cluster sizing page that includes the generated metadata module.
+For more information about creating pattern documentation, see link:/contribute/contribute-to-docs/[Contribute to Validated Patterns documentation].
+====
+
+[id="relationship-to-hugo-frontmatter"]
+== Relationship to Hugo frontmatter
+
+Pattern pages on validatedpatterns.io also use YAML frontmatter in `content/patterns/<pattern-name>/_index.adoc` (or `_index.md`).
+That frontmatter drives the patterns browser, tier badges, and pattern landing pages on the public website.
+It is separate from the catalog the {validated-patterns-op} UI consumes.
+
+Keep both metadata sources aligned:
+
+[cols="1,2,2",options="header"]
+|===
+| Field | `pattern-metadata.yaml` | Hugo `_index` frontmatter
+
+| Pattern name
+| `name`, `display_name`
+| Directory name, `title`
+
+| Tier
+| `tier`
+| `tier`
+
+| Summary
+| `description`
+| `summary`
+
+| GitHub repository
+| `repo_url`, `issues_url`
+| `links.github`, `links.bugs`
+
+| Documentation URL
+| `docs_url`
+| Derived from pattern path
+
+| CI dashboard
+| `ci_url`
+| `links.ci` or `ci`
+
+| Cluster sizing
+| `requirements`, `extra_features`
+| Not stored in frontmatter; rendered from synced metadata module
+|===
+
+[id="enabling-automatic-sync"]
+== Enabling automatic sync to the documentation repository
+
+To push metadata changes from your pattern repository into the docs repository, add a workflow that calls the shared metadata sync workflow.
+
+.Prerequisites
+
+* Your pattern repository is hosted under the `validatedpatterns`, `validatedpatterns-sandbox`, or `validatedpatterns-demos` GitHub organization.
+* The {solution-name-upstream} team has configured authentication for the docs repository (a `DOCS_TOKEN` secret or the Validated Patterns Metadata Sync GitHub App).
+* `repo_url` in `pattern-metadata.yaml` matches the GitHub URL of the pattern repository where the workflow runs.
+
+.Procedure
+
+. Create `.github/workflows/update-metadata.yml` in your pattern repository.
++
+[source,yaml]
+----
+name: Update docs pattern metadata
+on:
+  push:
+    paths:
+      - "pattern-metadata.yaml"
+      - ".github/workflows/update-metadata.yml"
+    branches:
+      - main
+
+jobs:
+  update-metadata:
+    uses: validatedpatterns/docs/.github/workflows/metadata-docs.yml@main
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    secrets:
+      DOCS_TOKEN: ${{ secrets.DOCS_TOKEN }}
+----
+
+. Commit and push `pattern-metadata.yaml` to the `main` branch.
++
+The workflow validates `repo_url`, flattens the metadata, and opens a pull request in the docs repository.
+
+. Review and merge the resulting pull request in `validatedpatterns/docs`.
+
+Contact mailto:validatedpatterns@googlegroups.com[validatedpatterns@googlegroups.com] if you need help configuring repository secrets for metadata sync.
+
+For sync failures, see link:/contribute/pattern-metadata-validation/#metadata-sync-workflow-fails-on-repo-url[Metadata sync workflow fails on repo URL] in Validation and troubleshooting.
diff --git a/content/contribute/pattern-metadata-examples.adoc b/content/contribute/pattern-metadata-examples.adoc
new file mode 100644
index 000000000..c85a22c96
--- /dev/null
+++ b/content/contribute/pattern-metadata-examples.adoc
@@ -0,0 +1,164 @@
+---
+menu:
+  contribute:
+    parent: Pattern metadata
+title: Example metadata files
+weight: 46
+aliases: /pattern-metadata-examples/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+[id="pattern-metadata-examples"]
+= Example metadata files
+
+These examples show `pattern-metadata.yaml` as you author it in a pattern repository (source format).
+For field definitions, see link:/contribute/pattern-metadata-schema-reference/[Schema and field reference].
+
+[id="example-minimal-metadata"]
+== Minimal example (single-cloud hub)
+
+The smallest useful source file for a single-cloud pattern without spoke clusters:
+
+[source,yaml]
+----
+metadata_version: "1.0"
+name: my-pattern
+pattern_version: "1.0"
+display_name: My Pattern
+description: A short description of what this pattern deploys.
+repo_url: https://github.com/validatedpatterns-sandbox/my-pattern
+docs_repo_url: https://github.com/validatedpatterns/docs
+issues_url: https://github.com/validatedpatterns-sandbox/my-pattern/issues
+docs_url: https://validatedpatterns.io/patterns/my-pattern/
+ci_url: https://validatedpatterns.io/ci/?pattern=mypattern
+tier: sandbox
+owners: my-github-user
+requirements:
+  hub:
+    compute:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.2xlarge
+    controlPlane:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.xlarge
+extra_features:
+  hypershift_support: false
+  spoke_support: false
+external_requirements:
+----
+
+[id="example-external-requirements"]
+== Example with external requirements
+
+Based on link:https://github.com/validatedpatterns/rag-llm-gitops[`rag-llm-gitops`] with a GPU sizing note:
+
+[source,yaml]
+----
+metadata_version: "1.0"
+name: rag-llm-gitops
+pattern_version: "1.0"
+display_name: AI Generation with LLM and RAG
+description: Deploy a RAG chatbot that augments LLM responses with enterprise documentation.
+repo_url: https://github.com/validatedpatterns/rag-llm-gitops
+docs_repo_url: https://github.com/validatedpatterns/docs
+issues_url: https://github.com/validatedpatterns/rag-llm-gitops/issues
+docs_url: https://validatedpatterns.io/patterns/rag-llm-gitops/
+ci_url: https://validatedpatterns.io/ci/?pattern=ragllm
+tier: tested
+owners: day0hero, sauagarwa
+requirements:
+  hub:
+    compute:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.2xlarge
+    controlPlane:
+      platform:
+        aws:
+          replicas: 1
+          type: m5.2xlarge
+extra_features:
+  hypershift_support: false
+  spoke_support: false
+external_requirements:
+  cluster_sizing_note: >
+    This pattern requires nodes with GPUs which are only supported in
+    certain regions. Create GPU nodes with `make create-gpu-machineset`
+    after the initial cluster is provisioned.
+----
+
+[id="example-multicloud-metadata"]
+== Full example (multi-cloud hub and spoke)
+
+Based on link:https://github.com/validatedpatterns/multicloud-gitops[`multicloud-gitops`] with hub/spoke sizing, variants, and multi-cloud requirements:
+
+[source,yaml]
+----
+metadata_version: "1.0"
+name: multicloud-gitops
+pattern_version: "1.0"
+display_name: Multicloud Gitops
+description: A multi-cloud pattern which uses GitOps, Hashicorp Vault and ACM to manage applications and secrets across clusters.
+repo_url: https://github.com/validatedpatterns/multicloud-gitops
+docs_repo_url: https://github.com/validatedpatterns/docs
+issues_url: https://github.com/validatedpatterns/multicloud-gitops/issues
+docs_url: https://validatedpatterns.io/patterns/multicloud-gitops/
+ci_url: https://validatedpatterns.io/ci/?pattern=mcgitops
+logo: https://validatedpatterns.io/images/logos/multicloud-gitops.png
+tier: maintained
+owners: mbaldessari, darkdoc
+requirements:
+  hub:
+    compute:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.2xlarge
+        azure:
+          replicas: 3
+          type: Standard_D8s_v3
+        gcp:
+          replicas: 3
+          type: n1-standard-8
+    controlPlane:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.xlarge
+        azure:
+          replicas: 3
+          type: Standard_D4s_v3
+        gcp:
+          replicas: 3
+          type: n1-standard-4
+  spoke:
+    compute:
+      platform:
+        aws:
+          replicas: 0
+          type: m5.2xlarge
+    controlPlane:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.2xlarge
+extra_features:
+  hypershift_support: true
+  spoke_support: true
+external_requirements:
+variants:
+  - name: hub
+    default: true
+    description: Default multicluster hub/spoke Multicloud Gitops variant
+  - name: standalone
+    description: Single cluster Multicloud Gitops (no ACM) variant
+----
diff --git a/content/contribute/pattern-metadata-schema-reference.adoc b/content/contribute/pattern-metadata-schema-reference.adoc
new file mode 100644
index 000000000..2ee06714f
--- /dev/null
+++ b/content/contribute/pattern-metadata-schema-reference.adoc
@@ -0,0 +1,316 @@
+---
+menu:
+  contribute:
+    parent: Pattern metadata
+title: Schema and field reference
+weight: 45
+aliases: /pattern-metadata-schema-reference/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+[id="pattern-metadata-schema"]
+= Schema and field reference
+
+This page documents the JSON schema for normalized catalog files and the fields you author in `pattern-metadata.yaml` at the repository root.
+
+[id="json-schema-overview"]
+== JSON schema overview
+
+The formal schema lives in link:https://github.com/validatedpatterns/pattern-ui-catalog/blob/main/pattern.schema.json[`pattern.schema.json`].
+It applies to **normalized catalog** files (`catalog/<pattern>/pattern.yaml`), not necessarily to every field you author in a pattern repository source file.
+
+For how source files are normalized before validation, see link:/contribute/pattern-metadata-ui-catalog/#source-format-vs-catalog-format[Source format and catalog format].
+
+[id="required-fields-catalog"]
+== Required fields (catalog format)
+
+After normalization, these top-level fields are required:
+
+[cols="1,1,2",options="header"]
+|===
+| Field | Type | Notes
+
+| `metadata_version`
+| string
+| Format `major.minor` (for example, `"1.0"`). Pattern: `^[0-9]+\.[0-9]+$`
+
+| `name`
+| string
+| Lowercase identifier. Pattern: `^[a-z][a-z0-9-]*$`. Must match the repository name.
+
+| `pattern_version`
+| string
+| Pattern implementation version. Format: `^[0-9]+\.[0-9]+$`
+
+| `display_name`
+| string
+| Human-readable name shown in the UI and documentation.
+
+| `repo_url`
+| string (URI)
+| Canonical GitHub URL for the pattern repository.
+
+| `docs_repo_url`
+| string (URI)
+| Documentation repository URL.
+
+| `issues_url`
+| string (URI)
+| Issue tracker URL.
+
+| `docs_url`
+| string (URI)
+| Public documentation URL.
+
+| `ci_url`
+| string (URI)
+| CI dashboard URL for the pattern.
+
+| `tier`
+| string
+| One of: `maintained`, `tested`, `sandbox`
+
+| `owners`
+| array of strings
+| At least one GitHub username. Source files may use a comma-separated string; the catalog converts it to an array.
+
+| `requirements`
+| object
+| Must include `hub`. May include `spoke`. See <<cluster-sizing-fields>>.
+
+| `extra_features`
+| object
+| Must include `hypershift_support` and `spoke_support` (both boolean).
+
+| `org`
+| string
+| GitHub organization name. Added by the catalog generator; do not add manually to source files.
+|===
+
+[id="optional-fields-catalog"]
+== Optional fields (catalog format)
+
+[cols="1,1,2",options="header"]
+|===
+| Field | Type | Notes
+
+| `description`
+| string
+| Short pattern summary. Recommended for UI catalog cards.
+
+| `logo`
+| string (URI)
+| Pattern logo URL.
+
+| `external_requirements`
+| object or null
+| External infrastructure notes. See <<external-requirements-fields>>.
+
+| `clustergroupname`
+| string
+| Default cluster group for install flows. Added from `values-global.yaml` by the catalog generator.
+
+| `variants`
+| array
+| Deployment variants. Each entry requires `name`; `default` and `description` are optional.
+
+| `spoke`
+| null
+| Reserved for future use. Catalog sets this to `null`.
+|===
+
+The schema sets `additionalProperties: false` at the top level and on most nested objects.
+Do not add undeclared fields to catalog files.
+
+[id="identity-fields"]
+== Identity fields (source file)
+
+[cols="1,1,3",options="header"]
+|===
+| Field | Required in source | Description
+
+| `metadata_version`
+| Recommended
+| Schema version for the metadata file (for example, `"1.0"` or `"2.0"`).
+
+| `name`
+| Yes
+| Pattern directory and repository name. Use lowercase letters and dashes (for example, `multicloud-gitops`). Must match `values-global.yaml` → `global.pattern`.
+
+| `display_name`
+| Yes
+| Human-readable pattern name (for example, `Multicloud Gitops`).
+
+| `description`
+| Recommended
+| Short description of the pattern purpose. Displayed in the UI catalog.
+
+| `pattern_version`
+| Yes
+| Version of the pattern implementation (for example, `"1.0"`).
+|===
+
+[id="link-governance-fields"]
+== Link and governance fields (source file)
+
+[cols="1,1,3",options="header"]
+|===
+| Field | Required in source | Description
+
+| `repo_url`
+| Yes
+| Canonical GitHub URL (for example, `https://github.com/validatedpatterns/multicloud-gitops`). The docs sync workflow verifies this matches the repository running the workflow.
+
+| `docs_repo_url`
+| Yes
+| GitHub URL for the documentation repository, typically `https://github.com/validatedpatterns/docs`.
+
+| `issues_url`
+| Yes
+| GitHub issues URL for the pattern repository.
+
+| `docs_url`
+| Yes
+| Public URL on validatedpatterns.io (for example, `https://validatedpatterns.io/patterns/multicloud-gitops/`).
+
+| `ci_url`
+| Yes
+| CI dashboard URL (for example, `https://validatedpatterns.io/ci/?pattern=mcgitops`).
+
+| `logo`
+| Optional
+| Logo URL for the UI catalog and website.
+
+| `tier`
+| Yes
+| One of `sandbox`, `tested`, or `maintained`. For definitions, see link:/learn/about-pattern-tiers-types/[About pattern tiers].
+
+| `owners`
+| Yes
+| GitHub usernames responsible for the pattern. Use a comma-separated string (`user1, user2`) or a YAML list. The catalog normalizes strings to arrays.
+|===
+
+[id="cluster-sizing-fields"]
+== Cluster sizing fields
+
+The `requirements` section defines tested {rh-ocp} cluster configurations.
+
+=== Source format nesting
+
+In pattern repositories, cloud providers are typically nested under a `platform` key:
+
+[source,yaml]
+----
+requirements:
+  hub:
+    compute:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.2xlarge
+    controlPlane:
+      platform:
+        aws:
+          replicas: 3
+          type: m5.xlarge
+----
+
+=== Catalog format nesting
+
+After normalization, cloud providers appear directly under `compute` and `controlPlane`:
+
+[source,yaml]
+----
+requirements:
+  hub:
+    compute:
+      aws:
+        replicas: 3
+        type: m5.2xlarge
+    controlPlane:
+      aws:
+        replicas: 3
+        type: m5.xlarge
+----
+
+=== Cluster roles and node pools
+
+* `hub` — Required. Primary cluster (hub or datacenter).
+* `spoke` — Optional. Managed or edge clusters imported through {rh-rhacm-first}.
+
+Under each cluster role:
+
+* `compute` — Worker node requirements.
+* `controlPlane` — Control plane node requirements.
+
+Under each node pool, define one or more cloud keys (`aws`, `azure`, `gcp`).
+Each cloud entry requires:
+
+* `replicas` — Integer ≥ 0.
+* `type` — Cloud instance type string (for example, `m5.2xlarge`).
+
+Set worker `replicas` to `0` when a cluster role uses control plane nodes only.
+
+=== Extra features
+
+The `extra_features` object requires both keys when present:
+
+[cols="1,1,3",options="header"]
+|===
+| Field | Type | Description
+
+| `hypershift_support`
+| boolean
+| Whether the pattern supports {rh-ocp} hosted control planes (HyperShift).
+
+| `spoke_support`
+| boolean
+| When `true`, documentation cluster sizing templates include a spoke section.
+|===
+
+[id="external-requirements-fields"]
+== External requirements fields
+
+Use `external_requirements` for infrastructure outside the cluster that affects deployment or sizing.
+
+[cols="1,1,3",options="header"]
+|===
+| Field | Type | Description
+
+| `cluster_sizing_note`
+| string
+| Free-text note displayed in documentation and as an "Additional requirements" tooltip in the UI catalog.
+|===
+
+Set `external_requirements:` to null or leave it empty when you have no external requirements.
+
+[id="variants-field"]
+== Variants field
+
+The optional `variants` list describes named deployment topologies (for example, `hub` and `standalone`).
+
+[cols="1,1,3",options="header"]
+|===
+| Field | Required | Description
+
+| `name`
+| Yes
+| Short variant identifier.
+
+| `description`
+| Optional
+| What the variant deploys.
+
+| `default`
+| Optional
+| Boolean. Set to `true` for the default variant.
+|===
+
+Variants are stored for tooling and QE use.
+The UI catalog and documentation sync workflow do not render variant lists today.
+
+For complete YAML examples, see link:/contribute/pattern-metadata-examples/[Example metadata files].
diff --git a/content/contribute/pattern-metadata-ui-catalog.adoc b/content/contribute/pattern-metadata-ui-catalog.adoc
new file mode 100644
index 000000000..05750c99b
--- /dev/null
+++ b/content/contribute/pattern-metadata-ui-catalog.adoc
@@ -0,0 +1,129 @@
+---
+menu:
+  contribute:
+    parent: Pattern metadata
+title: Metadata and the UI catalog
+weight: 43
+aliases: /pattern-metadata-ui-catalog/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+[id="pattern-metadata-ui-catalog"]
+= Metadata and the UI catalog
+
+The {validated-patterns-op} console plugin displays patterns from a catalog served on-cluster.
+This page describes how `pattern-metadata.yaml` becomes catalog data and what the Pattern Catalog page renders.
+
+[id="source-format-vs-catalog-format"]
+== Source format and catalog format
+
+Pattern repositories store `pattern-metadata.yaml` in a **source format** that existing patterns use today.
+The link:https://github.com/validatedpatterns/pattern-ui-catalog[`pattern-ui-catalog`] repository converts that file into a **catalog format** before the UI consumes it.
+
+The catalog generator (`generate-catalog.sh`) applies these normalizations:
+
+[cols="1,2,2",options="header"]
+|===
+| Change | Source format (`pattern-metadata.yaml`) | Catalog format (`catalog/<name>/pattern.yaml`)
+
+| Cloud provider nesting
+| `requirements.hub.compute.platform.aws`
+| `requirements.hub.compute.aws` (the `platform` wrapper is removed)
+
+| Pattern owners
+| Comma-separated string (`owners: user1, user2`) or YAML array
+| YAML array of usernames
+
+| GitHub organization
+| Not present in the source file
+| `org` field added from the repository GitHub organization
+
+| Default cluster group
+| Not present in the source file
+| `clustergroupname` added from `values-global.yaml` → `main.clusterGroupName` when available
+
+| Optional fields
+| May be omitted
+| `external_requirements`, `extra_features`, `docs_repo_url`, `ci_url`, and `spoke` default to `null` when absent
+|===
+
+The authoritative schema for catalog files is link:https://github.com/validatedpatterns/pattern-ui-catalog/blob/main/pattern.schema.json[`pattern.schema.json`].
+For field definitions and required keys, see link:/contribute/pattern-metadata-schema-reference/[Schema and field reference].
+For validation commands, see link:/contribute/pattern-metadata-validation/[Validation and troubleshooting].
+
+[id="catalog-discovery"]
+== Catalog discovery and publication
+
+. The `pattern-ui-catalog` project runs `generate-catalog.sh`, which queries GitHub for public repositories tagged with `ui-catalog-enabled` in the `validatedpatterns` and `validatedpatterns-sandbox` organizations.
+. For each repository, the script fetches `pattern-metadata.yaml` from the default branch.
+. If the file is missing or cannot be parsed, the repository is skipped.
+. The script normalizes the metadata and writes:
++
+* `catalog/catalog.yaml` — index listing all discovered pattern names
+* `catalog/<pattern-name>/pattern.yaml` — normalized metadata for one pattern
+* `catalog/<pattern-name>/values-secret.yaml.template` — optional secret template copy
++
+. The catalog directory is built into a container image (`quay.io/validatedpatterns/pattern-ui-catalog`) and deployed by the operator.
+
+To include a pattern in the UI catalog, tag the GitHub repository with the `ui-catalog-enabled` topic and ensure `pattern-metadata.yaml` is present and parseable.
+
+[id="on-cluster-catalog-access"]
+== On-cluster catalog access
+
+The console plugin fetches catalog data through a proxy path:
+
+[source,text]
+----
+/api/proxy/plugin/patterns-operator-console-plugin/pattern-ui-catalog/catalog.yaml
+/api/proxy/plugin/patterns-operator-console-plugin/pattern-ui-catalog/<pattern>/pattern.yaml
+----
+
+The plugin loads `catalog.yaml`, then fetches each listed `pattern.yaml`.
+You can override the catalog image by patching the `patterns-operator-config` ConfigMap `catalog.image` key.
+For more information about custom catalogs, see the link:https://github.com/validatedpatterns/pattern-ui-catalog#creating-a-custom-catalog[pattern-ui-catalog README].
+
+[id="fields-the-ui-renders"]
+== Fields the UI renders
+
+The Pattern Catalog page in the {hybrid-console-first} uses these metadata fields:
+
+[cols="1,3",options="header"]
+|===
+| Field | UI usage
+
+| `display_name`
+| Pattern card title
+
+| `description`
+| Card body text
+
+| `tier`
+| Tier label with color coding (`maintained`, `tested`, `sandbox`) and filter control
+
+| `logo`
+| Pattern logo on the card (absolute URL, or path relative to the catalog entry)
+
+| `org`
+| Tooltip on the card title
+
+| `requirements`
+| Cloud provider labels and hub/spoke sizing summary with detailed tooltip per cloud (`aws`, `gcp`, `azure`)
+
+| `external_requirements.cluster_sizing_note`
+| "Additional requirements" info icon and tooltip
+
+| `docs_url`, `repo_url`
+| External link buttons on the card
+
+| `name`, `catalogKey`
+| Install, uninstall, and secrets management navigation
+|===
+
+The UI does not currently render `variants`, `ci_url`, `issues_url`, `owners`, or `extra_features` on the catalog cards.
+Install flows use additional fields such as `clustergroupname` and `repo_url` when creating a `Pattern` custom resource.
+
+For more information about installing patterns through the operator, see link:/learn/using-validated-pattern-operator/[Using the Validated Patterns Operator].
diff --git a/content/contribute/pattern-metadata-validation.adoc b/content/contribute/pattern-metadata-validation.adoc
new file mode 100644
index 000000000..9c1aa22e6
--- /dev/null
+++ b/content/contribute/pattern-metadata-validation.adoc
@@ -0,0 +1,108 @@
+---
+menu:
+  contribute:
+    parent: Pattern metadata
+title: Validation and troubleshooting
+weight: 47
+aliases: /pattern-metadata-validation/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+[id="pattern-metadata-validation"]
+= Validation and troubleshooting
+
+This page describes how to validate `pattern-metadata.yaml` and resolve common errors in the UI catalog and documentation sync workflows.
+
+[id="catalog-schema-validation"]
+== Catalog schema validation
+
+The `pattern-ui-catalog` repository validates normalized catalog files:
+
+[source,terminal]
+----
+git clone https://github.com/validatedpatterns/pattern-ui-catalog.git
+cd pattern-ui-catalog
+make generate-catalog    # requires gh, yq, jq, and GitHub authentication
+make schema-validate     # requires check-jsonschema (pip install check-jsonschema)
+----
+
+`make schema-validate` checks:
+
+* `catalog/catalog.yaml` against `catalog.schema.json`
+* Each `catalog/*/pattern.yaml` against `pattern.schema.json`
+
+The pattern-ui-catalog CI pipeline also runs `yamllint` on generated catalog files.
+
+[id="documentation-sync-validation"]
+== Documentation sync validation
+
+The docs metadata workflow (`.github/workflows/metadata-docs.yml`) validates:
+
+* `repo_url` in `pattern-metadata.yaml` matches `https://github.com/<org>/<repo>` for the repository running the workflow
+* The YAML file parses successfully (via `yq` and `flatten_yaml.rb`)
+
+If validation fails, the workflow exits with an error and no pull request is opened.
+For workflow setup, see link:/contribute/pattern-metadata-documentation-sync/#enabling-automatic-sync[Enabling automatic sync to the documentation repository].
+
+[id="catalog-inclusion-rules"]
+== Catalog inclusion rules
+
+A pattern repository is included in the UI catalog only when:
+
+* The repository is public and tagged with `ui-catalog-enabled`
+* `pattern-metadata.yaml` exists on the default branch
+* The file parses and normalizes without error
+
+Repositories missing metadata or with invalid YAML are skipped silently during catalog generation.
+
+[id="alignment-checks"]
+== Alignment checks for contributors
+
+Keep these values consistent across systems:
+
+* `name` matches the Git repository name and `global.pattern` in `values-global.yaml`
+* `repo_url` matches the actual GitHub repository URL
+* `tier`, `docs_url`, and `ci_url` align with Hugo frontmatter and CI badge JSON (see link:/contribute/test-artifacts/[Testing artifacts])
+* `requirements` hub sizing reflects configurations you have actually tested
+
+[id="pattern-missing-from-ui-catalog"]
+== Pattern missing from the UI catalog
+
+Verify the following items:
+
+* The GitHub repository has the `ui-catalog-enabled` topic.
+* `pattern-metadata.yaml` exists on the default branch.
+* The YAML parses correctly (run `yq '.' pattern-metadata.yaml` locally).
+* The catalog has been regenerated and the catalog image redeployed after your change.
+
+[id="metadata-sync-workflow-fails-on-repo-url"]
+== Metadata sync workflow fails on repo URL
+
+The sync workflow compares `repo_url` with the GitHub URL of the repository running the workflow.
+Verify that `repo_url` uses the form `https://github.com/<org>/<repo>`.
+
+[id="schema-validation-fails"]
+== Schema validation fails in pattern-ui-catalog
+
+Common causes:
+
+* Missing required field after normalization (for example, `extra_features` or `requirements.hub`)
+* Invalid `tier` value (must be `maintained`, `tested`, or `sandbox`)
+* `name` contains uppercase letters or underscores
+* `owners` is empty after normalization
+* Undeclared extra fields at the top level
+
+Run `make generate-catalog` and `make schema-validate` locally to reproduce errors before publishing.
+For required fields, see link:/contribute/pattern-metadata-schema-reference/#required-fields-catalog[Required fields (catalog format)].
+
+[id="empty-requirements-section"]
+== Empty requirements section
+
+If `requirements` is empty, the catalog schema validation fails and the documentation cluster sizing template renders incomplete tables.
+Define at least `requirements.hub` with `compute` and `controlPlane` entries for one cloud provider.
+
+For sizing field structure, see link:/contribute/pattern-metadata-schema-reference/#cluster-sizing-fields[Cluster sizing fields].
diff --git a/content/contribute/pattern-metadata.adoc b/content/contribute/pattern-metadata.adoc
new file mode 100644
index 000000000..a1d599992
--- /dev/null
+++ b/content/contribute/pattern-metadata.adoc
@@ -0,0 +1,79 @@
+---
+menu: contribute
+title: Pattern metadata
+weight: 42
+aliases: /pattern-metadata/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+[id="pattern-metadata-overview"]
+= Pattern metadata
+
+Every {solution-name-upstream} pattern repository includes a `pattern-metadata.yaml` file at the repository root.
+This file is the source of truth for pattern identity, cluster sizing, tier information, and links.
+
+Downstream systems read this file to discover patterns, validate metadata, and render information in the {hybrid-console-first}, on validatedpatterns.io, and in quality engineering (QE) workflows.
+If you are contributing a new pattern or updating an existing one, maintain this file in your pattern repository.
+Do not edit the generated metadata modules in the `validatedpatterns/docs` repository by hand.
+
+[id="where-the-file-lives"]
+== Where the file lives
+
+Place `pattern-metadata.yaml` in the top-level directory of your pattern Git repository, alongside files such as `values-global.yaml`, `Makefile`, and `pattern.sh`.
+
+A typical pattern repository includes the metadata file in this layout:
+
+[source,text]
+----
+my-pattern/
+├── charts/
+├── common/
+├── pattern-metadata.yaml
+├── pattern.sh
+├── values-global.yaml
+└── values-prod.yaml
+----
+
+For more information about repository layout, see link:/learn/vp_openshift_framework/[Validated pattern structure].
+
+[id="metadata-consumers"]
+== Who consumes pattern metadata
+
+Three systems consume `pattern-metadata.yaml`, each with different expectations:
+
+[cols="1,3",options="header"]
+|===
+| Consumer | Purpose
+
+| link:https://github.com/validatedpatterns/pattern-ui-catalog[pattern-ui-catalog]
+| Fetches metadata from pattern repositories, normalizes it, validates it against a JSON schema, and publishes a static catalog image for the {validated-patterns-op} console plugin.
+
+| validatedpatterns.io documentation
+| Syncs metadata into cluster sizing pages through GitHub Actions and `utils/flatten_yaml.rb`.
+
+| QE and CI tooling
+| Uses links, tier, and sizing data for test planning and CI dashboard integration.
+|===
+
+The {hybrid-console-first} does not read `pattern-metadata.yaml` from your Git repository directly.
+The console plugin reads normalized `pattern.yaml` files from the catalog image that the operator deploys on-cluster.
+
+[id="pattern-metadata-pages"]
+== In this section
+
+* link:/contribute/pattern-metadata-ui-catalog/[Metadata and the UI catalog] — Source and catalog formats, catalog discovery, and fields the console renders.
+* link:/contribute/pattern-metadata-documentation-sync/[Metadata and documentation] — Docs site sync, Hugo frontmatter alignment, and the metadata GitHub Actions workflow.
+* link:/contribute/pattern-metadata-schema-reference/[Schema and field reference] — JSON schema, required and optional fields, and per-field descriptions.
+* link:/contribute/pattern-metadata-examples/[Example metadata files] — Minimal, GPU, and multi-cloud hub/spoke examples.
+* link:/contribute/pattern-metadata-validation/[Validation and troubleshooting] — Schema validation, inclusion rules, and common errors.
+
+[id="next-steps-pattern-metadata"]
+== Next steps
+
+* Create or extend a pattern with link:/contribute/creating-a-pattern/[Creating a pattern] or link:/learn/creating-patterns-with-patternizer/[Creating a pattern with patternizer].
+* Install patterns through the UI with link:/learn/using-validated-pattern-operator/[Using the Validated Patterns Operator].
+* Learn about pattern tiers in link:/contribute/sandbox/[Sandbox tier requirements] and link:/contribute/tested/[Tested tier requirements].
diff --git a/content/contribute/sandbox.adoc b/content/contribute/sandbox.adoc
index dc75c7242..392d0425b 100644
--- a/content/contribute/sandbox.adoc
+++ b/content/contribute/sandbox.adoc
@@ -50,6 +50,7 @@ A {sandbox} pattern must continue to meet the following criteria to remain in th
 . A {sandbox} pattern must conform to the common technical link:/contribute/implementation/[implementation requirements].
 . A {sandbox} pattern must be able to be deployed onto a freshly deployed OpenShift cluster without prior modification or tuning.
 . A {sandbox} pattern must include a top-level README file that highlights the business problem and how the pattern solves it.
+. A {sandbox} pattern must include a `pattern-metadata.yaml` file at the repository root with pattern identity, tier, and hub cluster sizing (where applicable). For more information, see link:/contribute/pattern-metadata/[Pattern metadata].
 . A {sandbox} pattern must include an architecture drawing. The specific tool or format is flexible as long as the meaning is clear.
 . A {sandbox} pattern must undergo an informal technical review by a community leader to ensure that it meets basic reuse standards.
 . A {sandbox} pattern must undergo an informal architecture review by a community leader to ensure that the solution has the right components, and they are generally being used as intended. For example, not using a database as a message bus.
diff --git a/content/contribute/test-artifacts.adoc b/content/contribute/test-artifacts.adoc
index ab904a617..0765d0ca5 100644
--- a/content/contribute/test-artifacts.adoc
+++ b/content/contribute/test-artifacts.adoc
@@ -17,6 +17,10 @@ include::modules/comm-attributes.adoc[]
 
 To be represented in the CI dashboard, testers can create a publicly available JSON file (for example, in an AWS bucket) that records the result of the latest test for each combination of pattern, platform, and {rh-ocp} version.
 
+Keep `patternRepo` in the testing artifact JSON aligned with `repo_url` in the `pattern-metadata.yaml` file for the pattern repository.
+The `ci_url` field in the metadata file must point to the same pattern entry on the CI dashboard.
+For more information about metadata fields, see link:/contribute/pattern-metadata/[Pattern metadata].
+
 [id="file-naming-convention"]
 == File naming convention
 `{pattern}-{platform}-{openshift version}-stable-badge.json`
diff --git a/content/learn/creating-patterns-with-patternizer.adoc b/content/learn/creating-patterns-with-patternizer.adoc
index 811ad0d1f..708c510c6 100644
--- a/content/learn/creating-patterns-with-patternizer.adoc
+++ b/content/learn/creating-patterns-with-patternizer.adoc
@@ -80,6 +80,11 @@ my-pattern
 └── values-secret.yaml.template # stub for the secrets file
 ----
 
+Patternizer does not currently generate `pattern-metadata.yaml`.
+Add this file manually at the repository root after initialization, or copy it from an existing pattern such as link:https://github.com/validatedpatterns/multicloud-gitops/blob/main/pattern-metadata.yaml[multicloud-gitops].
+For more information about metadata fields, see link:/contribute/pattern-metadata-schema-reference/[Schema and field reference].
+For the documentation sync workflow, see link:/contribute/pattern-metadata-documentation-sync/[Metadata and documentation].
+
 The generated `values-global.yaml` contains:
 
 [source,yaml]
@@ -162,4 +167,5 @@ The `pattern init` command is idempotent and can be run multiple times during pa
 * Learn about link:/learn/vp_structure_vp_pattern/[structuring a validated pattern] and best practices
 * Add operators to your pattern with link:/learn/vp_add_ops_to_pattern/[Adding operators to the framework]
 * Configure secrets with link:/learn/getting-started-secret-management/[Configuring secrets]
+* Add link:/contribute/pattern-metadata/[Pattern metadata] so cluster sizing and CI information stay in sync with the documentation site
 * Visit the link:https://github.com/validatedpatterns/patternizer[patternizer repository on GitHub] for the latest documentation
diff --git a/content/learn/infrastructure.adoc b/content/learn/infrastructure.adoc
index 2cf451fbe..36d6602ef 100644
--- a/content/learn/infrastructure.adoc
+++ b/content/learn/infrastructure.adoc
@@ -18,3 +18,7 @@ Each validated pattern has infrastructure requirements. The majority of the vali
 == Sizing
 
 In this section we provide general minimum sizing requirements for such infrastructure but it is important to review specific requirements for a specific validated pattern. For example, link:/industrial-edge/[Industrial Edge 2.0] employs AI/Ml technology that requires large machine instances to support the applications deployed on OpenShift at the datacenter.
+
+Per-pattern cluster sizing on validatedpatterns.io is generated from `pattern-metadata.yaml` in each pattern repository.
+Pattern maintainers define tested configurations in that file.
+For more information about metadata fields, see link:/contribute/pattern-metadata/[Pattern metadata].
diff --git a/content/learn/vp_openshift_framework.adoc b/content/learn/vp_openshift_framework.adoc
index 34989c625..187e8cffe 100644
--- a/content/learn/vp_openshift_framework.adoc
+++ b/content/learn/vp_openshift_framework.adoc
@@ -72,6 +72,9 @@ The Multicloud GitOps approach enables centralized management of multiple cloud
 ----
 
 First we notice some subdirectories: charts and common, along with `values-` yaml files.
+The `pattern-metadata.yaml` file at the repository root defines pattern identity, tier, links, and cluster sizing.
+The documentation site syncs this file into cluster sizing pages automatically.
+For more information about metadata fields, see link:/contribute/pattern-metadata/[Pattern metadata].
 
 ===  Industrial edge
 
@@ -123,7 +126,8 @@ First we notice some subdirectories: charts and common, along with `values-` yam
 15 directories, 26 files
 ----
 
-We see the same or similar files in the both patterns directories. 
+We see the same or similar files in the both patterns directories.
+Both examples include `pattern-metadata.yaml` at the repository root.
 
 == The `common` directory
 
diff --git a/content/learn/vp_structure_vp_pattern.adoc b/content/learn/vp_structure_vp_pattern.adoc
index d21c255d6..f86b7f6f8 100644
--- a/content/learn/vp_structure_vp_pattern.adoc
+++ b/content/learn/vp_structure_vp_pattern.adoc
@@ -51,6 +51,7 @@ Following these best practices, to create robust, scalable, and maintainable val
 
 9. **Plan for cluster sizing and storage needs**
    - Before deploying a pattern, review its cluster sizing and storage requirements. For instance, patterns using Red Hat OpenShift Data Foundation (ODF) may require substantial storage resources. Consult pattern documentation for accurate sizing.
+   - Define tested cluster configurations in `pattern-metadata.yaml` at the repository root so sizing pages on validatedpatterns.io stay aligned with your pattern. For more information, see link:/contribute/pattern-metadata/[Pattern metadata].
 
 10. **Customize and fork patterns appropriately**
    - When extending a pattern or deploying it at a customer site, create a personal or organizational fork. This allows for experimentation and customization while facilitating potential contributions back to the upstream pattern repository.
@@ -62,4 +63,7 @@ Following these best practices, to create robust, scalable, and maintainable val
     - Use the patterns framework to centrally manage multiple clusters and workloads across public and private clouds. Incorporate tools like Red Hat Advanced Cluster Management (RHACM) and Red Hat OpenShift GitOps (ArgoCD) to streamline operations.
 
 13. **Secure secrets across deployments**
-    - Utilize tools such as Hashicorp Vault to manage secrets securely across multi-cloud deployments, ensuring sensitive data is protected.
\ No newline at end of file
+    - Utilize tools such as Hashicorp Vault to manage secrets securely across multi-cloud deployments, ensuring sensitive data is protected.
+
+14. **Maintain pattern metadata**
+    - Keep `pattern-metadata.yaml` current with the tier, links, owners, and cluster sizing requirements for your pattern. The documentation site and quality engineering workflows use this file as the source of truth. For more information, see link:/contribute/pattern-metadata/[Pattern metadata].
\ No newline at end of file