rh-ai-quickstart · Hadar301 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,6 +2,8 @@
 
 Deploy a private, self-hosted AI coding assistant on OpenShift so developers each get their own namespace with an AI-powered IDE — no code leaves the cluster.
 
+User-facing docs: [README.md](README.md) and [docs/](docs/).
+
 ## Inference request path (RHCL + llm-d)
 
 ```mermaid
@@ -75,6 +77,7 @@ Package lives in `tests/cluster-smoke/` (see its README). Optional Langfuse / OT
 ## Directory Structure
 
 ```
+docs/                         # User-facing guides (architecture, requirements, IDE, benchmarks, …)
 charts/                       # Unified Helm charts — single set for ROSA and ARO
 ├── pca-app-of-apps/          # Root ArgoCD AppProject + child Applications
 ├── pca-operators/            # Operator Subscriptions (RHOAI, GPU, DevSpaces, NFD, RHCL, …)

diff --git a/PCA_ARO.md b/PCA_ARO.md
diff --git a/PCA_Deployment_ARO/README.md b/PCA_Deployment_ARO/README.md
@@ -653,7 +653,23 @@ GuideLLM sweep results for Qwen3.6-35B-A3B-FP8 on H100 NVL:
 | Code Review | 4,096 | 1,024 | 16,133 | 5.59 | 157 |
 | File Generation | 8,192 | 2,048 | 13,976 | 11.15 | 208 |
 
-Full results: [`testresults_h100.md`](../testresults_h100.md)
+Full results: [`testresults_h100.md`](testresults_h100.md) · A100 sweep: [`testresults.md`](testresults.md) · Summary: [`docs/benchmarks.md`](../docs/benchmarks.md)
+
+---
+
+## Key differences from ROSA
+
+| Aspect | ROSA (AWS) | ARO (Azure) |
+|--------|------------|-------------|
+| GPU VM | e.g. `g6e` (L40S) via RHCS machine pool | GPU MachineSet (e.g. H100 NVL / A100 family) after cluster create |
+| Storage class | `gp3-csi` | `managed-csi` |
+| Charts | `charts/` + `values-rosa.yaml` | Same `charts/` + `values-aro.yaml` |
+| Cloud values | Terraform sets `gitops.cloud=rosa` | Terraform sets `gitops.cloud=aro` |
+| NSG / network | AWS security groups | ARO-managed subnets (no customer NSG on master/worker) |
+| vLLM image | Chart / RHOAI default path for the ROSA overlay | Upstream vLLM (see [Why Upstream vLLM v0.19.0](#why-upstream-vllm-v0190)) |
+| Tool / reasoning parsers | Set in ROSA `values-rosa.yaml` / ServingRuntime for the chosen model | See [Model Tool Calling & Reasoning Configuration](#model-tool-calling--reasoning-configuration) (e.g. `qwen3_xml` + `qwen3` for Qwen3.6) |
+
+Azure GPU choice depends on quota and model size (A100 80 GB vs H100 NVL 94 GB). Prefer a SKU with native FP8 and enough VRAM for your context window; see [docs/benchmarks.md](../docs/benchmarks.md).
 
 ---
 

diff --git a/PCA_Deployment_ARO/scripts/post-terraform-fullstack.sh b/PCA_Deployment_ARO/scripts/post-terraform-fullstack.sh
@@ -9,7 +9,7 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 BASE_PATH="${SCRIPT_DIR}/../argocd"
-RESULTS_FILE="${SCRIPT_DIR}/../../testresults_h100.md"
+RESULTS_FILE="${SCRIPT_DIR}/../testresults_h100.md"
 
 RED='\033[0;31m'
 GREEN='\033[0;32m'

diff --git a/testresults_h100.md → PCA_Deployment_ARO/testresults_h100.md b/testresults_h100.md → PCA_Deployment_ARO/testresults_h100.md
diff --git a/PCA_Deployment_ROSA/README.md b/PCA_Deployment_ROSA/README.md
@@ -754,6 +754,8 @@ Edit `charts/pca-ai-serving/values-rosa.yaml` → update `llmInferenceService.re
 terraform apply -var="inferentia_pool_enabled=true"
 ```
 
+The chart ships a Neuron ServingRuntime template at `charts/pca-ai-serving/templates/vllm-neuron-runtime-template.yaml`. If Inferentia pods fail to start networking on ROSA HCP, see [Inferentia / Neuron pods fail networking (OVN annotation race)](#inferentia--neuron-pods-fail-networking-ovn-annotation-race).
+
 ### Adding a new developer user
 
 1. Add to `devspaces_users` in `terraform.tfvars` and run `terraform apply` (creates the HTPasswd user)
@@ -829,6 +831,19 @@ oc get node <gpu-node> -o json | jq '.metadata.labels | with_entries(select(.key
 oc label node <gpu-node> feature.node.kubernetes.io/pci-10de.present=true
 ```
 
+### Inferentia / Neuron pods fail networking (OVN annotation race)
+
+On ROSA HCP with OVN-Kubernetes, multi-core Inferentia pods can fail to get a network if the AWS `neuron-scheduler` overwrites the `k8s.ovn.org/pod-networks` annotation during device allocation.
+
+**Symptoms:** Pod stays Pending or never becomes Ready; events or CNI logs show missing / invalid OVN pod-network annotation after Neuron scheduling.
+
+**Mitigations:**
+
+1. **MutatingAdmissionWebhook (verified workaround)** — Admit Neuron-scheduled pods in a way that **preserves** the OVN `k8s.ovn.org/pod-networks` annotation when the scheduler updates device annotations.
+2. **Neuron DRA (preferred long-term)** — Use the Neuron Dynamic Resource Allocation path so the classic `neuron-scheduler` annotation race is avoided when DRA is available in your Neuron / OpenShift stack.
+
+Neuron ServingRuntime template: `charts/pca-ai-serving/templates/vllm-neuron-runtime-template.yaml`. Prefer NVIDIA GPUs for MoE code models unless you specifically need Inferentia overflow capacity.
+
 ### Model pod stuck in Pending
 
 ```bash