CONSOLE-4871: Add AI context documentation files

.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Bash(make)",
+      "Bash(go)",
+      "Bash(gofmt)",
+      "Bash(oc)",
+      "Bash(kubectl)",
+      "Bash(docker)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(git push --force)"
+    ]
+  }
+}

.coderabbit.yaml

@@ -0,0 +1,56 @@
+# CodeRabbit Configuration
+# https://docs.coderabbit.ai/guides/configure-coderabbit
+
+version: 2
+
+language: en-US
+
+early_access: false
+
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: false
+  path_instructions:
+    - path: "pkg/**/*.go"
+      instructions: |
+        Review Go code following OpenShift operator patterns.
+        See CONVENTIONS.md for coding standards and patterns.
+        Controllers should use the library-go factory pattern.
+        Status conditions should use status.Handle* functions.
+    - path: "bindata/assets/**/*.yaml"
+      instructions: |
+        Review YAML assets for Kubernetes resource correctness.
+        Ensure proper annotations for cluster profiles.
+    - path: "manifests/**/*.yaml"
+      instructions: |
+        Review CVO manifests carefully.
+        These are deployed to clusters and changes have wide impact.
+    - path: "quickstarts/**/*.yaml"
+      instructions: |
+        Review quickstart YAML definitions.
+        Ensure cluster profile annotations are present.
+        See quickstarts/README.md for guidelines.
+
+chat:
+  auto_reply: true
+
+knowledge_base:
+  learnings:
+    scope: auto
+  issues:
+    scope: auto
+  jira:
+    project_keys: []
+  linear:
+    team_keys: []
+  pull_requests:
+    scope: auto
+
+path_filters:
+  - "!vendor/**"
+  - "!**/*_test.go"
+

AGENTS.md

@@ -0,0 +1,89 @@
+# OpenShift Console Operator - AI Context Hub
+
+This file serves as the central AI documentation hub for the OpenShift Console Operator project. AI assistants (Claude, Cursor, Copilot, CodeRabbit, etc.) use this and the linked documents to understand project context.
+## Go Version and Dependencies
+
+- **Go version**: 1.24.0 (toolchain: go1.24.4)
+- **Dependency management**: Uses `go.mod` with vendoring
+- **Build flags**: Use `GOFLAGS="-mod=vendor"` for builds and tests to ensure vendored dependencies are used
+- **Key dependencies**: openshift/api, openshift/library-go, k8s.io client libraries
+## Quick Reference
+
+### This Repository
+
+| Document | Purpose |
+|----------|---------|
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | System architecture, components, repository structure |
+| [CONVENTIONS.md](./CONVENTIONS.md) | Go coding standards, patterns, import organization |
+| [TESTING.md](./TESTING.md) | Testing patterns, commands, debugging |
+| [README.md](./README.md) | Project README with setup instructions |
+
+### Console Repository (openshift/console)
+
+For frontend-related guidelines, see the [openshift/console](https://github.com/openshift/console) repository:
+
+| Document | Purpose |
+|----------|---------|
+| [STYLEGUIDE.md](https://github.com/openshift/console/blob/master/STYLEGUIDE.md) | Frontend code style guidelines |
+| [INTERNATIONALIZATION.md](https://github.com/openshift/console/blob/master/INTERNATIONALIZATION.md) | i18n patterns and translation guidelines |
+| [CONTRIBUTING.md](https://github.com/openshift/console/blob/master/CONTRIBUTING.md) | Contribution guidelines for the console project |
+
+
+## Project Summary
+
+The **console-operator** is an OpenShift operator that installs and maintains the OpenShift web console on a cluster. It manages:
+
+- Console deployment and configuration
+- OAuth client configuration for console authentication
+- CLI downloads (oc, kubectl) deployment
+- Routes, services, and secrets
+- Console plugins and quickstarts
+- Pod disruption budgets
+- Health checks and monitoring
+
+## Essential Commands
+
+```bash
+# Build
+make                           # Build the operator binary
+make build                     # Same as above
+
+# Test
+make test-unit                 # Run unit tests
+make test-e2e                  # Run e2e tests (requires cluster)
+make check                     # Run verify + test-unit
+
+# Code Quality
+gofmt -w ./pkg ./cmd           # Format code
+go vet ./pkg/... ./cmd/...     # Run vet checks
+make verify                    # Run all verification
+```
+
+## Key Namespaces
+
+| Namespace | Purpose |
+|-----------|---------|
+| `openshift-console` | Console deployment and resources |
+| `openshift-console-operator` | Operator deployment |
+| `openshift-config` | Cluster configuration |
+| `openshift-config-managed` | Managed configuration |
+| `openshift-ingress-operator` | Ingress controller (default ingress) |
+
+## Branch Naming
+
+- Feature work: `CONSOLE-####` (Jira story number)
+- Bug fixes: `OCPBUGS-####` (Jira bug number)
+
+## Related Repositories
+
+- [openshift/console](https://github.com/openshift/console) - Web console frontend and backend (see STYLEGUIDE.md, INTERNATIONALIZATION.md, CONTRIBUTING.md)
+- [openshift/api](https://github.com/openshift/api) - OpenShift API definitions
+- [openshift/library-go](https://github.com/openshift/library-go) - Shared operator libraries
+
+## OWNERS
+
+Component: Management Console
+- @spadgett
+- @jhadvig
+- @TheRealJon
+

ARCHITECTURE.md

@@ -0,0 +1,125 @@
+# Architecture
+
+This document outlines the system architecture for the OpenShift Console Operator.
+
+## Repository Structure
+
+```
+console-operator/
+├── cmd/console/           # Main entry point (main.go)
+├── pkg/
+│   ├── api/               # API constants (namespaces, resource names, ports)
+│   ├── cmd/
+│   │   ├── operator/      # Operator command setup
+│   │   └── version/       # Version command
+│   ├── console/
+│   │   ├── clientwrapper/ # Client wrapper utilities
+│   │   ├── controllers/   # All controller implementations
+│   │   │   ├── clidownloads/          # CLI downloads controller
+│   │   │   ├── clioidcclientstatus/   # CLI OIDC client status controller
+│   │   │   ├── downloadsdeployment/   # Downloads deployment controller
+│   │   │   ├── healthcheck/           # Health check controller
+│   │   │   ├── oauthclients/          # OAuth client controller
+│   │   │   ├── oauthclientsecret/     # OAuth client secret controller
+│   │   │   ├── oidcsetup/             # OIDC setup controller
+│   │   │   ├── poddisruptionbudget/   # PDB controller
+│   │   │   ├── route/                 # Route controller
+│   │   │   ├── service/               # Service controller
+│   │   │   ├── storageversionmigration/
+│   │   │   ├── upgradenotification/   # Upgrade notification controller
+│   │   │   └── util/                  # Shared controller utilities
+│   │   ├── errors/        # Custom error types (SyncError, CustomLogoErrors)
+│   │   ├── metrics/       # Prometheus metrics
+│   │   ├── operator/      # Main operator logic (sync_v400.go)
+│   │   ├── starter/       # Operator startup, informer setup, controller wiring
+│   │   ├── status/        # Status condition handling
+│   │   ├── subresource/   # Resource builders for each managed resource
+│   │   │   ├── authentication/  # Authentication config handling
+│   │   │   ├── configmap/       # ConfigMap builders (branding, service CA, trusted CA)
+│   │   │   ├── consoleserver/   # Console server config builder
+│   │   │   ├── crd/             # CRD utilities
+│   │   │   ├── deployment/      # Deployment builder
+│   │   │   ├── infrastructure/  # Infrastructure config
+│   │   │   ├── oauthclient/     # OAuth client builder
+│   │   │   ├── route/           # Route builder
+│   │   │   ├── secret/          # Secret builders (session secret)
+│   │   │   └── util/            # Shared subresource utilities
+│   │   ├── telemetry/     # Telemetry integration
+│   │   └── version/       # Version information
+│   └── crypto/            # Cryptographic utilities (random string generation)
+├── bindata/assets/        # Static YAML assets
+│   ├── configmaps/        # ConfigMap templates
+│   ├── deployments/       # Deployment templates
+│   ├── pdb/               # PodDisruptionBudget templates
+│   ├── routes/            # Route templates (console, downloads, custom)
+│   └── services/          # Service templates
+├── manifests/             # CVO manifest files (deployed to cluster)
+├── profile-patches/       # Profile-specific patches (e.g., IBM Cloud managed)
+├── quickstarts/           # Console quickstart YAML definitions
+├── examples/              # Example configurations
+│   ├── cvo-unmanage-operator.yaml  # Disable CVO management for dev
+│   ├── cvo-manage-operator.yaml    # Re-enable CVO management
+│   └── 07-operator-alt-image.yaml  # Custom operator image deployment
+├── test/e2e/              # End-to-end tests
+└── vendor/                # Vendored dependencies
+```
+
+## Controllers
+
+The operator runs multiple controllers (started in `pkg/console/starter/starter.go`):
+
+| Controller | Purpose |
+|-----------|---------|
+| `ConsoleOperator` | Main operator coordinating deployment, configmaps, secrets |
+| `RouteController` | Manages console and downloads routes |
+| `ServiceController` | Manages console and downloads services |
+| `OAuthClientsController` | Creates/updates OAuth client for console authentication |
+| `OAuthClientSecretController` | Syncs OAuth client secret |
+| `OIDCSetupController` | Handles external OIDC authentication (feature-gated) |
+| `CLIOIDCClientStatusController` | Reports CLI OIDC client status |
+| `CLIDownloadsController` | Manages ConsoleCLIDownload resources |
+| `DownloadsDeploymentController` | Manages the downloads deployment |
+| `HealthCheckController` | Monitors console health |
+| `PodDisruptionBudgetController` | Manages PDBs for console and downloads |
+| `UpgradeNotificationController` | Displays upgrade notifications |
+| `StorageVersionMigrationController` | Handles storage version migrations |
+
+## Key Resources
+
+| Resource | API Group | Purpose |
+|----------|-----------|---------|
+| `Console` | operator.openshift.io/v1 | Operator configuration CR |
+| `Console` | config.openshift.io/v1 | Cluster console configuration |
+| `ClusterOperator` | config.openshift.io/v1 | Cluster operator status |
+| `OAuthClient` | oauth.openshift.io/v1 | Console OAuth client |
+| `ConsoleCLIDownload` | console.openshift.io/v1 | CLI download configurations |
+| `ConsolePlugin` | console.openshift.io/v1 | Dynamic console plugins |
+| `ConsoleNotification` | console.openshift.io/v1 | Console notifications |
+| `ConsoleQuickStart` | console.openshift.io/v1 | Guided tutorials |
+
+## Feature Gates
+
+Feature gates are accessed via `featuregates.FeatureGateAccess` (in `starter.go`):
+
+| Feature Gate | Purpose |
+|-------------|---------|
+| `ExternalOIDC` | External OIDC authentication support |
+| `ConsolePluginContentSecurityPolicy` | Content Security Policy for plugins |
+
+## Resource Syncing
+
+Use `resourcesynccontroller` for syncing ConfigMaps and Secrets between namespaces:
+- `oauth-serving-cert` from `openshift-config-managed` to `openshift-console`
+- `default-ingress-cert` from `openshift-config-managed` to `openshift-console`
+
+## Quickstarts
+
+Console quickstarts are contributed to the `quickstarts/` directory. See [quickstarts/README.md](./quickstarts/README.md) for guidelines. Quickstarts require cluster profile annotations:
+
+```yaml
+annotations:
+  include.release.openshift.io/ibm-cloud-managed: "true"
+  include.release.openshift.io/self-managed-high-availability: "true"
+  include.release.openshift.io/single-node-developer: "true"
+```
+

CLAUDE.md

@@ -0,0 +1,25 @@
+# Claude Code Configuration
+
+This file configures Claude Code for the OpenShift Console Operator project.
+
+## AI Context
+
+See [AGENTS.md](./AGENTS.md) for the central AI documentation hub, which includes:
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) - System architecture, components, repository structure
+- [CONVENTIONS.md](./CONVENTIONS.md) - Go coding standards, patterns, import organization
+- [TESTING.md](./TESTING.md) - Testing patterns, commands, debugging
+
+## Quick Commands
+
+```bash
+# Build
+make
+
+# Test
+make test-unit
+make check
+
+# Format
+gofmt -w ./pkg ./cmd
+```