docs: add pattern metadata documentation and guidelines

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]

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.

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.

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
+----