openshift-eng · chiragkyal · Oct 31, 2025
diff --git a/PLUGINS.md b/PLUGINS.md
@@ -97,16 +97,19 @@ See [plugins/must-gather/README.md](plugins/must-gather/README.md) for detailed
 OLM (Operator Lifecycle Manager) plugin for operator management and debugging
 
 **Commands:**
-- **`/olm:approve` `<operator-name> [namespace] [--all]`** - Approve pending InstallPlans for operator installations and upgrades
-- **`/olm:catalog` `<list|add|remove|refresh|status> [arguments]`** - Manage catalog sources for discovering and installing operators
+- **`/olm:approve` `<operator-name> [namespace] [--all]`** - Approve pending InstallPlans for operator installations and upgrades (OLM v0 only)
+- **`/olm:catalog` `<action> [args] [--version v0|v1]`** - Manage catalog sources (v0) or ClusterCatalogs (v1)
 - **`/olm:debug` `<issue-description> <must-gather-path> [olm-version]`** - Debug OLM issues using must-gather logs and source code analysis
-- **`/olm:diagnose` `[operator-name] [namespace] [--fix] [--cluster]`** - Diagnose and optionally fix common OLM and operator issues
-- **`/olm:install` `<operator-name> [namespace] [channel] [source] [--approval=Automatic|Manual]`** - Install a day-2 operator using Operator Lifecycle Manager
-- **`/olm:list` `[namespace] [--all-namespaces]`** - List installed operators in the cluster
-- **`/olm:search` `[query] [--catalog <catalog-name>]`** - Search for available operators in catalog sources
-- **`/olm:status` `<operator-name> [namespace]`** - Get detailed status and health information for an operator
-- **`/olm:uninstall` `<operator-name> [namespace] [--remove-crds] [--remove-namespace]`** - Uninstall a day-2 operator and optionally remove its resources
-- **`/olm:upgrade` `<operator-name> [namespace] [--channel=<channel>] [--approve]`** - Update an operator to the latest version or switch channels
+- **`/olm:detect-version`** - Auto-detect which OLM version(s) are installed in the cluster
+- **`/olm:diagnose` `[operator-name] [namespace] [--fix] [--cluster]`** - Diagnose and optionally fix common OLM and operator issues (OLM v0 only)
+- **`/olm:fix-rbac` `<extension-name>`** - Fix RBAC permission issues for a ClusterExtension (OLM v1 only)
+- **`/olm:install` `<name> [options] [--version v0|v1]`** - Install an operator (v0) or extension (v1) using OLM
+- **`/olm:list` `[namespace] [--all-namespaces] [--version v0|v1]`** - List installed operators (v0) or extensions (v1) in the cluster
+- **`/olm:search` `[query] [--catalog <name>] [--version v0|v1]`** - Search for available operators (v0) or extensions (v1) in catalogs
+- **`/olm:status` `<name> [namespace] [--version v0|v1]`** - Get detailed status of an operator (v0) or extension (v1)
+- **`/olm:uninstall` `<name> [namespace] [--remove-crds] [--remove-namespace] [--version v0|v1]`** - Uninstall an operator (v0) or extension (v1) from the cluster
+- **`/olm:upgrade` `<name> [namespace] [--channel <channel>] [--approve] [--version v0|v1]`** - Upgrade an operator (v0) or extension (v1) to a new version
+- **`/olm:use-version` `[v0|v1|clear]`** - Set or view the OLM version context for this session
 
 See [plugins/olm/README.md](plugins/olm/README.md) for detailed documentation.
 

diff --git a/docs/data.json b/docs/data.json
@@ -263,66 +263,90 @@
       "commands": [
         {
           "name": "approve",
-          "description": "Approve pending InstallPlans for operator installations and upgrades",
+          "description": "Approve pending InstallPlans for operator installations and upgrades (OLM v0 only)",
           "synopsis": "/olm:approve <operator-name> [namespace] [--all]",
           "argument_hint": "<operator-name> [namespace] [--all]"
         },
         {
           "name": "catalog",
-          "description": "Manage catalog sources for discovering and installing operators",
-          "synopsis": "/olm:catalog list",
-          "argument_hint": "<list|add|remove|refresh|status> [arguments]"
+          "description": "Manage catalog sources (v0) or ClusterCatalogs (v1)",
+          "synopsis": "/olm:catalog <action> [args] [--version v0|v1]",
+          "argument_hint": "<action> [args] [--version v0|v1]"
         },
         {
           "name": "debug",
           "description": "Debug OLM issues using must-gather logs and source code analysis",
           "synopsis": "/olm:debug <issue-description> <must-gather-path> [olm-version]",
           "argument_hint": "<issue-description> <must-gather-path> [olm-version]"
         },
+        {
+          "name": "detect-version",
+          "description": "Auto-detect which OLM version(s) are installed in the cluster",
+          "synopsis": "/olm:detect-version",
+          "argument_hint": ""
+        },
         {
           "name": "diagnose",
-          "description": "Diagnose and optionally fix common OLM and operator issues",
+          "description": "Diagnose and optionally fix common OLM and operator issues (OLM v0 only)",
           "synopsis": "/olm:diagnose [operator-name] [namespace] [--fix] [--cluster]",
           "argument_hint": "[operator-name] [namespace] [--fix] [--cluster]"
         },
+        {
+          "name": "fix-rbac",
+          "description": "Fix RBAC permission issues for a ClusterExtension (OLM v1 only)",
+          "synopsis": "/olm:fix-rbac <extension-name>",
+          "argument_hint": "<extension-name>"
+        },
         {
           "name": "install",
-          "description": "Install a day-2 operator using Operator Lifecycle Manager",
-          "synopsis": "/olm:install <operator-name> [namespace] [channel] [source] [--approval=Automatic|Manual]",
-          "argument_hint": "<operator-name> [namespace] [channel] [source] [--approval=Automatic|Manual]"
+          "description": "Install an operator (v0) or extension (v1) using OLM",
+          "synopsis": "/olm:install <name> [options] [--version v0|v1]",
+          "argument_hint": "<name> [options] [--version v0|v1]"
         },
         {
           "name": "list",
-          "description": "List installed operators in the cluster",
-          "synopsis": "/olm:list [namespace] [--all-namespaces]",
-          "argument_hint": "[namespace] [--all-namespaces]"
+          "description": "List installed operators (v0) or extensions (v1) in the cluster",
+          "synopsis": "/olm:list [namespace] [--all-namespaces] [--version v0|v1]",
+          "argument_hint": "[namespace] [--all-namespaces] [--version v0|v1]"
         },
         {
           "name": "search",
-          "description": "Search for available operators in catalog sources",
-          "synopsis": "/olm:search [query] [--catalog <catalog-name>]",
-          "argument_hint": "[query] [--catalog <catalog-name>]"
+          "description": "Search for available operators (v0) or extensions (v1) in catalogs",
+          "synopsis": "/olm:search [query] [--catalog <name>] [--version v0|v1]",
+          "argument_hint": "[query] [--catalog <name>] [--version v0|v1]"
         },
         {
           "name": "status",
-          "description": "Get detailed status and health information for an operator",
-          "synopsis": "/olm:status <operator-name> [namespace]",
-          "argument_hint": "<operator-name> [namespace]"
+          "description": "Get detailed status of an operator (v0) or extension (v1)",
+          "synopsis": "/olm:status <name> [namespace] [--version v0|v1]",
+          "argument_hint": "<name> [namespace] [--version v0|v1]"
         },
         {
           "name": "uninstall",
-          "description": "Uninstall a day-2 operator and optionally remove its resources",
-          "synopsis": "/olm:uninstall <operator-name> [namespace] [--remove-crds] [--remove-namespace]",
-          "argument_hint": "<operator-name> [namespace] [--remove-crds] [--remove-namespace]"
+          "description": "Uninstall an operator (v0) or extension (v1) from the cluster",
+          "synopsis": "/olm:uninstall <name> [namespace] [--remove-crds] [--remove-namespace] [--version v0|v1]",
+          "argument_hint": "<name> [namespace] [--remove-crds] [--remove-namespace] [--version v0|v1]"
         },
         {
           "name": "upgrade",
-          "description": "Update an operator to the latest version or switch channels",
-          "synopsis": "/olm:upgrade <operator-name> [namespace] [--channel=<channel>] [--approve]",
-          "argument_hint": "<operator-name> [namespace] [--channel=<channel>] [--approve]"
+          "description": "Upgrade an operator (v0) or extension (v1) to a new version",
+          "synopsis": "/olm:upgrade <name> [namespace] [--channel <channel>] [--approve] [--version v0|v1]",
+          "argument_hint": "<name> [namespace] [--channel <channel>] [--approve] [--version v0|v1]"
+        },
+        {
+          "name": "use-version",
+          "description": "Set or view the OLM version context for this session",
+          "synopsis": "/olm:use-version [v0|v1|clear]",
+          "argument_hint": "[v0|v1|clear]"
+        }
+      ],
+      "skills": [
+        {
+          "name": "OLM Version Detection",
+          "id": "version-detection",
+          "description": "Determine which OLM version to use based on context and flags"
         }
       ],
-      "skills": [],
       "has_readme": true
     },
     {

diff --git a/plugins/olm/README.md b/plugins/olm/README.md
@@ -1,33 +1,124 @@
 # OLM Plugin
 
-A comprehensive plugin for managing and debugging Operator Lifecycle Manager (OLM) in OpenShift clusters.
+A comprehensive unified plugin for managing and debugging Operator Lifecycle Manager (OLM) in Kubernetes and OpenShift clusters.
 
 ## Overview
 
-This plugin provides comprehensive OLM capabilities:
+This plugin provides comprehensive OLM capabilities for both **OLM v0** (traditional) and **OLM v1** (next-generation):
 
-- **Operator Discovery**: Search and discover operators across all catalog sources
-- **Lifecycle Management**: Install, upgrade, and uninstall operators with intelligent defaults
-- **Health Monitoring**: List and check detailed operator health status
-- **Update Management**: Check for and install operator updates with approval workflows
-- **Troubleshooting**: Diagnose and fix common OLM issues automatically
-- **Catalog Management**: Add, remove, and manage custom catalog sources
-- **Advanced Debugging**: Troubleshoot OLM issues by correlating must-gather logs with source code and known bugs in Jira
-- **Safety Features**: Orphaned resource cleanup, stuck namespace detection, and confirmation prompts
-- **Context-Aware**: Automatic channel discovery, namespace auto-detection, and smart recommendations
+- **Unified Interface**: Single plugin supporting both OLM versions
+- **Operator/Extension Discovery**: Search and discover packages across catalogs
+- **Lifecycle Management**: Install, upgrade, and uninstall with version-aware commands
+- **Health Monitoring**: List and check detailed status
+- **Update Management**: Handle upgrades with version-specific strategies
+- **Troubleshooting**: Diagnose and fix issues (v0: orphaned resources, v1: RBAC permissions)
+- **Catalog Management**: Manage catalog sources (v0) or ClusterCatalogs (v1)
+- **Advanced Debugging**: Troubleshoot using must-gather logs with source code correlation
+- **RBAC Management**: Automatic RBAC setup and fixing for OLM v1
 
-The plugin supports both OLMv0 (traditional OLM) and OLMv1 (next-generation) architectures.
+## 🔑 Version Management (Important!)
+
+**This plugin requires explicit OLM version selection.** You must specify which OLM version to use via:
+
+### Option 1: Set Context (Recommended)
+```bash
+# Detect what's installed in your cluster
+/olm:detect-version
+
+# Set version context for your session
+/olm:use-version v0  # For traditional OLM
+/olm:use-version v1  # For next-generation OLM
+
+# Now use commands without repeating --version
+/olm:install cert-manager
+/olm:list
+/olm:status cert-manager
+```
+
+### Option 2: Per-Command Flag
+```bash
+# Use --version flag on each command
+/olm:install cert-manager --version v0
+/olm:list --version v1
+/olm:status postgres-operator --version v0
+```
+
+### Version Detection
+```bash
+# Auto-detect which OLM version(s) are installed
+/olm:detect-version
+```
+
+### Key Differences
+
+| Aspect        | OLM v0 (Traditional)              | OLM v1 (Next-Generation)                    |
+| ------------- | --------------------------------- | ------------------------------------------- |
+| **Resources** | Subscription, CSV, InstallPlan    | ClusterExtension, ClusterCatalog            |
+| **Catalogs**  | CatalogSource (namespace-scoped)  | ClusterCatalog (cluster-scoped)             |
+| **CLI**       | `oc` (OpenShift CLI)              | `kubectl`                                   |
+| **RBAC**      | Managed by OLM (cluster-admin)    | User-managed (ServiceAccount + ClusterRole) |
+| **Upgrades**  | Automatic or manual approval      | Version constraints or channel tracking     |
+| **Scope**     | Primarily operators               | Any Kubernetes extension                    |
+| **Best For**  | OpenShift, existing installations | New projects, GitOps, flexible versioning   |
 
 ## Prerequisites
 
+### Common
 - Claude Code installed
+- Access to a Kubernetes/OpenShift cluster with sufficient RBAC permissions
+
+### OLM v0 Specific
 - OpenShift CLI (`oc`) installed and configured
-- Access to an OpenShift cluster with cluster-admin or sufficient RBAC permissions
+- OLM v0 installed (pre-installed on OpenShift)
+
+### OLM v1 Specific
+- `kubectl` installed and configured
+- OLM v1 (operator-controller) installed
+- cert-manager installed (optional, for webhook support)
+
+### Optional
 - `git` (required for debug command)
 - Network access to GitHub and Jira (for debug command)
 
 ## Commands
 
+### Version Management Commands
+
+#### `/olm:use-version` - Set OLM Version Context
+
+Set the OLM version context for your session to avoid repeating `--version` on every command.
+
+**Usage:**
+```bash
+/olm:use-version v0        # Set to OLM v0
+/olm:use-version v1        # Set to OLM v1
+/olm:use-version           # View current context
+/olm:use-version clear     # Clear context
+```
+
+See [commands/use-version.md](commands/use-version.md) for full documentation.
+
+---
+
+#### `/olm:detect-version` - Auto-Detect OLM Version
+
+Automatically detect which OLM version(s) are installed in your cluster.
+
+**Usage:**
+```bash
+/olm:detect-version
+```
+
+**What it does:**
+- Checks for OLM v0 installation (openshift-operator-lifecycle-manager namespace)
+- Checks for OLM v1 installation (olmv1-system namespace)
+- Shows component status and versions
+- Provides recommendations for version selection
+
+See [commands/detect-version.md](commands/detect-version.md) for full documentation.
+
+---
+
 ### Operator Management Commands
 
 #### `/olm:search` - Search for Operators
@@ -166,10 +257,12 @@ See [commands/upgrade.md](commands/upgrade.md) for full documentation.
 
 ---
 
-#### `/olm:approve` - Approve InstallPlans
+#### `/olm:approve` - Approve InstallPlans (v0 only)
 
 Approve pending InstallPlans for operators with manual approval mode.
 
+**⚠️  OLM v0 ONLY**: This command only works with OLM v0.
+
 **Usage:**
 ```bash
 /olm:approve openshift-cert-manager-operator                      # Approve pending plan
@@ -193,6 +286,38 @@ See [commands/approve.md](commands/approve.md) for full documentation.
 
 ---
 
+#### `/olm:fix-rbac` - Fix RBAC Permissions (v1 only)
+
+Diagnose and fix RBAC permission issues for ClusterExtensions.
+
+**⚠️  OLM v1 ONLY**: This command only works with OLM v1.
+
+**Usage:**
+```bash
+/olm:fix-rbac postgres-operator        # Fix RBAC for failed extension
+```
+
+**What it does:**
+- Detects pre-authorization failures in ClusterExtension status
+- Parses missing RBAC permissions from error messages
+- Identifies current ServiceAccount and ClusterRole
+- Offers to automatically update ClusterRole with missing permissions
+- Or displays required RBAC YAML for manual application
+
+**When to use:**
+- Extension installation is stuck in "Progressing" state
+- Status shows "pre-authorization failed" errors
+- You see RBAC-related error messages
+
+**Arguments:**
+- `extension-name` (required): Name of the ClusterExtension to fix
+
+**Note:** Requires the `PreflightPermissions` feature gate to be enabled in operator-controller for detailed permission analysis.
+
+See [commands/fix-rbac.md](commands/fix-rbac.md) for full documentation.
+
+---
+
 #### `/olm:uninstall` - Uninstall Operators
 
 Safely uninstall operators with optional resource cleanup.

diff --git a/plugins/olm/commands/approve.md b/plugins/olm/commands/approve.md
@@ -1,5 +1,5 @@
 ---
-description: Approve pending InstallPlans for operator installations and upgrades
+description: Approve pending InstallPlans for operator installations and upgrades (OLM v0 only)
 argument-hint: <operator-name> [namespace] [--all]
 ---
 
@@ -14,6 +14,8 @@ olm:approve
 ## Description
 The `olm:approve` command approves pending InstallPlans for operators with manual approval mode. This is required for operators that have `installPlanApproval: Manual` in their Subscription to proceed with installation or upgrades.
 
+**⚠️  OLM v0 ONLY**: This command only works with OLM v0. OLM v1 does not use InstallPlans.
+
 This command helps you:
 - Approve operator installations that are waiting for manual approval
 - Approve operator upgrades
@@ -24,7 +26,28 @@ This command helps you:
 
 The command performs the following steps:
 
-1. **Parse Arguments**:
+1. **Check OLM Version** (v0 ONLY):
+   ```bash
+   # Check if version context is set
+   if [ -f .work/olm/context.txt ]; then
+     OLM_VERSION=$(cat .work/olm/context.txt)
+     if [ "$OLM_VERSION" == "v1" ]; then
+       echo "❌ Command not available for OLM v1"
+       echo ""
+       echo "The /olm:approve command is only available for OLM v0."
+       echo "Current context: v1"
+       echo ""
+       echo "OLM v1 does not use InstallPlans. Installations proceed automatically"
+       echo "once RBAC permissions are satisfied."
+       echo ""
+       echo "To use this command, switch to v0:"
+       echo "  /olm:use-version v0"
+       exit 1
+     fi
+   fi
+   ```
+
+2. **Parse Arguments**:
    - `$1`: Operator name (required) - Name of the operator
    - `$2`: Namespace (optional) - Namespace where operator is installed
      - If not provided, searches for the operator across all namespaces