Strengthen Hybrid Mesh docs per VP editorial feedback

- Add Problem→Solution table at top of _index.md (Service Mesh + AI ops framing)
- Clarify 3-cluster requirement explicitly (single-cluster not supported)
- Expand prerequisites: OCP version, storage class, RHOAI/GPU, Lightspeed
- Document values-secret.yaml.template secrets table with all 6 secret names
- Add Verify the installation section with concrete oc/bash commands
  (ACM, Skupper, OLSConfig, RHOAI, Industrial Edge, console links)
- Add ASCII topology diagram in architecture.md showing hub+spoke+Skupper VAN

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: maximilianoPizarro

content/patterns/hybrid-mesh-platform/_index.md

@@ -44,7 +44,19 @@ contributor:
 
 **Maintainer:** Maximiliano Pizarro, Specialist Solution Architect at Red Hat
 
-> **Your journey:** Install via the Validated Patterns framework (`./pattern.sh install`), connect three OpenShift clusters (hub + east + west) through ACM managedClusterGroups, and observe IoT sensor data across Grafana and Developer Hub. The pages below follow one continuous story — concept, install, operate, scaffold — so you can read straight through or jump to any chapter.
+## The problem this pattern solves
+
+Operating a multi-cluster OpenShift fleet creates three compounding challenges that a Service Mesh alone cannot address:
+
+| Challenge | Without this pattern | With Hybrid Mesh Platform |
+| --- | --- | --- |
+| **Cross-cluster connectivity** | Site-to-site VPNs, manual firewall rules per pair of clusters | Skupper Virtual Application Network — outbound-only mTLS, no inbound firewall changes |
+| **Fleet governance drift** | Each cluster managed independently; configurations diverge over time | Single `main` branch drives hub + east + west via ACM + dual GitOps (PUSH ApplicationSet + PULL clustergroup) |
+| **AI-assisted operations** | Operators react to incidents by parsing dashboards and YAML | OpenShift Lightspeed + MCP Gateway let operators act on platform state in natural language, reducing MTTA on infrastructure incidents |
+
+**Goal:** This pattern combines Red Hat Service Mesh for secure inter-service connectivity with OpenShift AI (MaaS + vLLM) and OpenShift Lightspeed + MCP for natural-language platform operations — giving teams centralized GitOps governance, secure cross-cluster communication, and AI-assisted incident response in a single deployable reference architecture.
+
+> **Your journey:** Install via the Validated Patterns framework (`./pattern.sh install`), connect three OpenShift clusters (hub + east + west) through ACM `managedClusterGroups`, and observe IoT sensor data across Grafana and Developer Hub. The pages below follow one continuous story — concept, install, operate, scaffold.
 
 ## What is Hybrid Mesh Platform?
 
@@ -55,7 +67,9 @@ contributor:
 - **OpenShift Service Mesh 3** in **ambient mode** provides ztunnel-based L4 encryption and optional waypoint L7 policy across all clusters.
 - **Connectivity Link (Kuadrant)** layers API-aware ingress policies — rate limiting, auth, DNS/TLS automation — on top of Gateway API.
 
-**Tested on:** Red Hat OpenShift Container Platform **4.17+** on **AWS** (hub + east spoke + west spoke). See [Cluster sizing](cluster-sizing) for recommended instance types.
+**Tested on:** Red Hat OpenShift Container Platform **4.17+** on **AWS** (hub + east spoke + west spoke, 3 workers each).
+
+**Multi-cluster topology:** this is a **hub + two spokes** pattern (not single-cluster). All three clusters are required; standalone single-cluster deployment is not supported by default. See [Cluster sizing](cluster-sizing) for minimum instance types per role.
 
 **Implementation repo:** [hybrid-mesh-platform](https://github.com/maximilianoPizarro/hybrid-mesh-platform) — Validated Patterns layout (`clustergroup`, Vault + External Secrets, ACM managedClusterGroups).
 

content/patterns/hybrid-mesh-platform/architecture.md

@@ -21,10 +21,37 @@ Spokes remain the execution venues for application namespaces, data-plane compon
 | **Observability** | Aggregated metrics, logging, and tracing strategies start at the hub and uniform dashboards span spokes. |
 | **GitOps consistency** | A single Git revision (`main`) with region paths drives spoke drift correction. |
 
+## Multi-cluster topology: three required clusters
+
+This pattern requires **three OpenShift clusters** — not a single-cluster deployment. The topology follows the Validated Patterns hub-spoke model:
+
+```
+              ┌──────────────────────────────────────┐
+              │  Hub cluster (OpenShift on AWS)       │
+              │  ACM · Argo CD · Developer Hub · RHOAI│
+              │  ACS Central · Grafana · Skupper ·    │
+              │  Kuadrant · OpenShift Lightspeed · MCP│
+              └──────┬─────────────────┬──────────────┘
+          ACM push   │                 │  ACM push
+           GitOps    │                 │  GitOps
+              ┌──────▼───────┐  ┌──────▼───────┐
+              │ East spoke   │  │ West spoke   │
+              │ Industrial   │  │ Industrial   │
+              │ Edge · Kafka │  │ Edge · Kafka │
+              │ Camel K · ML │  │ MirrorMaker  │
+              │ DevSpaces    │  │ Skupper      │
+              └──────────────┘  └──────────────┘
+       ◄────────── Skupper VAN (mTLS, outbound-only) ──────────►
+```
+
+Hub and spokes communicate over a **Skupper Virtual Application Network** — outbound-only mTLS tunnels, no inbound firewall rule changes needed. The hub's `ApplicationSet` pushes spoke charts; each spoke's local Argo CD pulls its `clusterGroup` from Git autonomously.
+
 ## Platform architecture overview
 
 ![Hub-spoke platform — Git paths, ApplicationSet, Skupper VAN, and per-cluster components](/images/hybrid-mesh-platform/arch-hub-spoke-flow.png)
+
 *Single `main` branch: hub at `charts/region/hub`, spokes at `charts/region/east` and `charts/region/west`, shared charts under `charts/all/`.*
+
 ## Follow the request — one temperature reading end to end
 
 When a machine sensor on the **east** spoke publishes a temperature sample, the path is: **MQTT** (`messaging` broker) → **Camel K** (`mqtt-to-kafka` integration) → **Kafka** (`dev-cluster` topic) → optional **ML scoring** (KServe) → **line-dashboard** WebSocket consumer. In parallel, **Thanos Querier** on east scrapes Istio and Kafka metrics; a **Skupper Connector** (`prometheus-east`) tunnels HTTP to the hub, where **Grafana** datasource `prometheus-east` plots the series. The **Hub Gateway** can route browser traffic to the east line-dashboard via **spoke-gateway** and Skupper listener `ie-gateway-east`. Developer Hub **Topology** shows the same pods when the catalog entity carries `backstage.io/kubernetes-cluster: east` and spoke API tokens are synced.

content/patterns/hybrid-mesh-platform/getting-started.md

@@ -77,17 +77,34 @@ Use cluster names **`hub`**, **`east`**, and **`west`**. Namespace **`stackrox`*
 
 ## Prerequisites
 
-- Red Hat OpenShift Container Platform **4.20** (reference version; 4.14+ supported per cluster)
-- **Three clusters:** one hub, one east-region spoke, one west-region spoke (ACM labels drive placement)
-- **Helm 3** on your workstation or CI runner (`helm version`)
-- **Git** client and hosting account (GitHub in examples)
-- **`oc` CLI** logged into the hub as cluster-admin for ACM import (recommended)
-- Network access to GitHub (or your fork) and container registries from all clusters
+### OpenShift clusters
+
+| Requirement | Value |
+| --- | --- |
+| **OpenShift version** | 4.17+ (tested on 4.20 on AWS) |
+| **Topology** | **3 clusters** — one hub, one east spoke, one west spoke (single-cluster deployment is not supported by default) |
+| **Storage class** | Dynamic provisioner required on all clusters (AWS gp3-csi or equivalent). Kafka, Gitea, Quay, and Vault all require `PersistentVolumeClaim`. |
+| **Network** | All clusters must reach your Git fork (GitHub by default) and public container registries, or mirrored equivalents. |
+
+### Hub cluster — additional requirements
+
+| Operator / feature | Requirement |
+| --- | --- |
+| **OpenShift AI (RHOAI)** | Required for MaaS / vLLM inference. Needs Node Feature Discovery and GPU operator **only** if you enable GPU-accelerated models. CPU-based inference (Qwen3 / Granite on CPU) works without GPU. |
+| **GPU (optional)** | NVIDIA or AMD GPU node for accelerated vLLM. Without GPU, enable `modelServing.cpuOnly: true` in `values-hub.yaml`. |
+| **OpenShift Lightspeed** | Requires `OLSConfig` CRD and an OpenAI-compatible endpoint (MaaS on hub or external). |
+| **Vault** | HashiCorp Vault is deployed by the pattern operator as the secrets backend. |
+
+### Workstation
+
+- **`oc` CLI** logged into the hub as `cluster-admin` for ACM import
+- **Helm 3** (`helm version`)
+- **Git** client and a GitHub (or Gitea) account
 
 ### Network requirements (connected environments)
 
-1. Access to public container registries (or mirrored equivalents)
-2. Access to your Git repository (fork of `hybrid-mesh-platform`)
+1. Access to public container registries (or mirrored equivalents) from all clusters
+2. Access to your Git fork from all clusters
 
 ### Cluster sizing (AWS — OpenShift 4.20)
 
@@ -129,13 +146,37 @@ Update `main.gitops.repoURL` in `values-global.yaml` and cluster domains in `ove
 
 ## Step 2: Configure secrets and cluster domains
 
-Copy and edit secrets:
+Copy the secrets template and edit before installation. **Do not commit `values-secret.yaml` to Git.**
 
 ```bash
 cp values-secret.yaml.template values-secret.yaml
 ```
 
-Set hub and spoke cluster domains in override files before install. See [MIGRATION.md](https://github.com/maximilianoPizarro/hybrid-mesh-platform/blob/main/MIGRATION.md) for the mapping from legacy RHDP-injected secrets.
+### Required secrets (values-secret.yaml)
+
+The Validated Patterns secrets framework (Vault + External Secrets Operator) reads `values-secret.yaml` at install time and populates Vault. The following secrets are defined in the template:
+
+| Secret name | Fields | When required |
+| --- | --- | --- |
+| `config-demo` | `secret` | Always (auto-generated if left as `onMissingValue: generate`) |
+| `kairos-ai-credentials` | `api-key` | When Kairos SmartScaling AI features are enabled on spokes |
+| `openshift-ai-maas-credentials` | `OPENAI_API_KEY`, `OPENAI_API_BASE` | When OpenShift AI / MaaS inference is enabled on the hub |
+| `mcp-gateway-argocd` | `token` | When MCP Gateway is enabled (OpenShift Lightspeed integration) |
+| `workshop-users` | `defaultPassword` | Workshop Showroom (demo only; use OAuth in production) |
+| AWS credentials | `aws_access_key_id`, `aws_secret_access_key` | Only if using ACM ClusterPools to provision new clusters |
+
+Fields marked `onMissingValue: generate` are auto-generated by Vault for demo environments. For production, set them to `onMissingValue: error` and provide values explicitly.
+
+Set hub and spoke cluster domains in override files before install:
+
+```bash
+# Edit your cloud provider override (AWS example):
+vi overrides/values-aws-hub.yaml
+vi overrides/values-aws-east.yaml
+vi overrides/values-aws-west.yaml
+```
+
+See [MIGRATION.md](https://github.com/maximilianoPizarro/hybrid-mesh-platform/blob/main/MIGRATION.md) for the mapping from legacy RHDP-injected secrets.
 
 ## Step 3: Install with Validated Patterns
 
@@ -325,9 +366,91 @@ oc get job -n developer-hub -l job-name=developer-hub-spoke-token-sync-hook
 
 Never commit registry passwords to Git. Generate dockerconfig and pass via Helm at upgrade time if you enable Quay push from pipelines.
 
+## Verify the installation
+
+Run these checks after all sync waves complete to confirm the pattern is healthy. Run each command from the hub cluster unless noted.
+
+### Fleet and GitOps
+
+```bash
+# ACM: east and west must be Available
+oc get managedcluster
+
+# Hub clustergroup: all Applications Synced
+oc get applications -n openshift-gitops
+
+# ApplicationSet: spoke apps generated
+oc get applicationset fleet-spoke-push -n openshift-gitops
+oc get applications -n openshift-gitops | grep spoke-components
+```
+
+### Service Interconnect (Skupper)
+
+```bash
+# Hub VAN: sitesInNetwork must equal 3 (hub + east + west)
+oc get site hub -n service-interconnect \
+  -o jsonpath='sitesInNetwork={.status.sitesInNetwork}{"\n"}'
+
+# Skupper listeners ready on hub
+oc get listeners -n service-interconnect
+```
+
+### OpenShift Lightspeed (MCP Gateway)
+
+```bash
+# OLSConfig must be Available
+oc get olsconfig cluster -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'
+
+# OpenShift Lightspeed pods running on hub
+oc get pods -n openshift-lightspeed
+
+# MCP Gateway pods running on hub
+oc get pods -n mcp-gateway
+```
+
+### OpenShift AI / RHOAI
+
+```bash
+# DataScienceCluster components: all Managed / Ready
+oc get datasciencecluster default-dsc \
+  -o jsonpath='{range .status.installedComponents[*]}{.name}: {.managementState}{"\n"}{end}'
+
+# Model serving pods (if enabled)
+oc get pods -n rhods-model-mesh-serving 2>/dev/null || \
+oc get pods -n modelmesh-serving 2>/dev/null
+```
+
+### Industrial Edge (run on each spoke)
+
+```bash
+# Switch to east or west context
+oc config use-context east   # adjust to your kubeconfig context name
+
+# Sensors, Kafka, and Camel K running
+oc get pods -n industrial-edge-tst
+oc get kafka dev-cluster -n industrial-edge-tst -o jsonpath='{.status.conditions[0].type}{"\n"}'
+
+# Line dashboard accessible
+oc get route line-dashboard -n industrial-edge-tst
+```
+
+### Console links (hub — 19 expected)
+
+```bash
+# Log in first so OAuth-protected links get a bearer token
+oc login --token=<hub-token> --server=<hub-api-url>
+
+# Expect 19 OK (HTTP 200) on a full hub install
+MIN_OK_CODE=200 bash scripts/verify-console-links.sh
+```
+
+If any check fails, see the [extended troubleshooting guide](https://maximilianopizarro.github.io/hybrid-mesh-platform/validatedpatterns-docs/troubleshooting.html) and the [Validation Guide](https://maximilianopizarro.github.io/hybrid-mesh-platform/validation-guide.html).
+
 ## References
 
 - [ACM documentation](https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/html/about/welcome-to-red-hat-advanced-cluster-management-for-kubernetes)
+- [OpenShift AI documentation](https://docs.redhat.com/en/documentation/red_hat_openshift_ai_self-managed)
+- [OpenShift Lightspeed documentation](https://docs.redhat.com/en/documentation/openshift_lightspeed)
 - [Multicloud GitOps Validated Pattern](/patterns/multicloud-gitops)
 - [RHDP install playbook and extended docs](https://maximilianopizarro.github.io/hybrid-mesh-platform/validatedpatterns-docs/)
 - [ApplicationSet Generators](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/)