Add agentic documentation for OpenShift enhancements

.gitignore

@@ -4,4 +4,12 @@
 enhancement-tool
 tools/bin
 tools/cover.out
-super-linter.log
+super-linter.log
+
+# Node.js dependencies (for promptfoo evals)
+node_modules/
+package-lock.json
+
+# Promptfoo cache and results
+.promptfoo/
+promptfoo-results.json

AGENTS.md

@@ -0,0 +1,189 @@
+# OpenShift Enhancements - Agent Navigation Index
+
+**Version**: 1.0 | **Docs**: ./ai-docs/ | **Role**: Ecosystem Hub
+
+---
+
+## CRITICAL: Retrieval Strategy
+
+**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning.
+
+When working on OpenShift:
+- ✅ **DO**: Read relevant docs from `./ai-docs/` first
+- ✅ **DO**: Verify patterns match current APIs (`oc explain`)
+- ✅ **DO**: Check enhancement guidelines in `./guidelines/`
+- ❌ **DON'T**: Rely solely on training data
+- ❌ **DON'T**: Guess at API structures or enhancement process
+
+---
+
+## AI Navigation: DON'T Read All Docs
+
+**Read 4-5 docs per task, not everything.**
+
+### Common Task Flows
+
+**Writing enhancement proposal?**
+→ `./guidelines/enhancement_template.md` → `./ai-docs/workflows/enhancement-process.md` → `./ai-docs/workflows/topology-considerations-guide.md` → `./ai-docs/practices/development/api-evolution.md`
+
+**Building operator?**
+→ `./ai-docs/DESIGN_PHILOSOPHY.md` → `./ai-docs/platform/operator-patterns/controller-runtime.md` → `./ai-docs/platform/operator-patterns/status-conditions.md` → `./ai-docs/practices/testing/pyramid.md`
+
+**Adding API to existing operator?**
+→ `./ai-docs/practices/development/api-evolution.md` → `./ai-docs/domain/kubernetes/crds.md` → `./ai-docs/platform/operator-patterns/webhooks.md`
+
+**Understanding cluster upgrade process?**
+→ `./ai-docs/domain/openshift/clusterversion.md` → `./ai-docs/platform/openshift-specifics/upgrade-strategies.md` → `./ai-docs/decisions/adr-0001-cvo-orchestration.md`
+
+**Need visual map?**
+→ `./ai-docs/KNOWLEDGE_GRAPH.md`
+
+---
+
+## Quick Navigation by Role
+
+| Role | Start Here | Then Read |
+|------|-----------|-----------|
+| **Enhancement Author** | `./guidelines/enhancement_template.md` | `./ai-docs/workflows/enhancement-process.md` → `./ai-docs/workflows/topology-considerations-guide.md` |
+| **Operator Developer** | `./ai-docs/DESIGN_PHILOSOPHY.md` | `./ai-docs/platform/operator-patterns/` |
+| **API Designer** | `./ai-docs/practices/development/api-evolution.md` | `./dev-guide/` |
+| **Platform Architect** | `./ai-docs/decisions/` | `./ai-docs/DESIGN_PHILOSOPHY.md` |
+
+---
+
+## Core Platform Concepts
+
+| Topic | File | Description |
+|-------|------|-------------|
+| **Design principles** | `./ai-docs/DESIGN_PHILOSOPHY.md` | Core architectural philosophy |
+| **Visual navigation** | `./ai-docs/KNOWLEDGE_GRAPH.md` | Graph-based doc navigation |
+| **Cluster operators** | `./ai-docs/domain/openshift/clusteroperator.md` | Status reporting, lifecycle |
+| **Cluster upgrades** | `./ai-docs/domain/openshift/clusterversion.md` | CVO orchestration, upgrade ordering |
+| **Custom resources** | `./ai-docs/domain/kubernetes/crds.md` | Extending Kubernetes API |
+| **Pods** | `./ai-docs/domain/kubernetes/pod.md` | Container workload fundamentals |
+| **Services** | `./ai-docs/domain/kubernetes/service.md` | Stable networking and discovery |
+
+---
+
+## Standard Operator Patterns
+
+| Pattern | File | When to Use |
+|---------|------|-------------|
+| **Controller runtime** | `./ai-docs/platform/operator-patterns/controller-runtime.md` | Every operator (reconcile loops) |
+| **Status conditions** | `./ai-docs/platform/operator-patterns/status-conditions.md` | Available/Progressing/Degraded reporting |
+| **Webhooks** | `./ai-docs/platform/operator-patterns/webhooks.md` | Validation/mutation/conversion |
+| **Finalizers** | `./ai-docs/platform/operator-patterns/finalizers.md` | Cleanup external resources on deletion |
+| **RBAC** | `./ai-docs/platform/operator-patterns/rbac.md` | Service account permissions |
+| **must-gather** | `./ai-docs/platform/operator-patterns/must-gather.md` | Debugging and diagnostics |
+| **Upgrade safety** | `./ai-docs/platform/openshift-specifics/upgrade-strategies.md` | N→N+1 version skew, CVO coordination |
+
+---
+
+## Engineering Practices
+
+| Area | Index | Description |
+|------|-------|-------------|
+| **Testing** | `./ai-docs/practices/testing/` | Pyramid (60/30/10), e2e framework |
+| **Security** | `./ai-docs/practices/security/` | STRIDE, RBAC patterns, secret handling |
+| **Reliability** | `./ai-docs/practices/reliability/` | SLI/SLO/SLA, degraded-mode patterns |
+| **Development** | `./ai-docs/practices/development/` | API evolution, compatibility |
+
+---
+
+## Workflows
+
+| Workflow | File | Links to Authoritative Source |
+|----------|------|-------------------------------|
+| **Enhancement process** | `./ai-docs/workflows/enhancement-process.md` | `./guidelines/enhancement_template.md` |
+| **Topology considerations** | `./ai-docs/workflows/topology-considerations-guide.md` | Guide for SNO, MicroShift, Hypershift, OKE sections |
+| **Feature implementation** | `./ai-docs/workflows/implementing-features.md` | `./dev-guide/` |
+| **Exec-plan guidance** | `./ai-docs/workflows/exec-plans/` | Template for multi-week features |
+
+---
+
+## Component Repository Index
+
+**Finding component repos**: See `./ai-docs/references/repo-index.md`
+
+**Pattern**: Most components are in `openshift/<component-name>-operator` or `openshift/<component-name>`
+
+**Search**: [GitHub org search](https://github.com/orgs/openshift/repositories)
+
+---
+
+## Cross-Repo Architectural Decisions
+
+**Location**: `./ai-docs/decisions/`
+
+**Index**: See `./ai-docs/decisions/index.md`
+
+**Common ADRs**:
+- Why etcd as backend
+- Why CVO orchestration model
+- Why immutable nodes (RHCOS + rpm-ostree)
+
+---
+
+## Relationship to Other Documentation
+
+| Source | Purpose | When to Use |
+|--------|---------|-------------|
+| **This repo (`./ai-docs/`)** | AI-optimized ecosystem hub | Starting point, cross-repo patterns |
+| **`./guidelines/`** | Authoritative enhancement process | Writing enhancement proposals |
+| **`./dev-guide/`** | Development conventions | Git workflow, CI, coding standards |
+| **`./enhancements/`** | Historical design docs | Understanding past decisions |
+| **Component repos** | Implementation specifics | Component architecture, internal details |
+
+---
+
+## How to Use This Documentation
+
+### For AI Agents
+1. Start with task-specific flow (see "AI Navigation" section)
+2. Read 4-5 linked docs, not entire tree
+3. Use `oc explain <resource>` for field-level API details
+4. Check `./guidelines/` for authoritative enhancement process
+5. Link to component repos for implementation details
+
+### For Humans
+- **Skim**: Read index files (`index.md`) to orient
+- **Search**: Use `grep -r "keyword" ./ai-docs/`
+- **Verify**: Cross-reference with `oc explain` and `./guidelines/`
+- **Navigate**: Use `KNOWLEDGE_GRAPH.md` for visual map
+
+---
+
+## Documentation Structure
+
+```
+./ai-docs/
+├── DESIGN_PHILOSOPHY.md         # Core principles
+├── KNOWLEDGE_GRAPH.md            # Visual navigation
+├── platform/                     # Operator patterns
+│   ├── operator-patterns/        # Controller runtime, status, webhooks
+│   └── openshift-specifics/      # Upgrade safety, CVO coordination
+├── domain/                       # Core API concepts
+│   ├── kubernetes/               # Pod, Service, CRD, Node
+│   └── openshift/                # ClusterOperator, ClusterVersion, Machine
+├── practices/                    # Cross-cutting concerns
+│   ├── testing/                  # Pyramid, e2e framework
+│   ├── security/                 # STRIDE, RBAC, secrets
+│   ├── reliability/              # SLI/SLO, degraded mode
+│   └── development/              # API evolution, compatibility
+├── decisions/                    # Cross-repo ADRs
+├── workflows/                    # AI-optimized process guides
+│   ├── exec-plans/               # Feature tracking templates (Platform)
+│   ├── enhancement-process.md
+│   ├── topology-considerations-guide.md
+│   └── implementing-features.md
+└── references/                   # Pointers (GitHub links, oc commands)
+    ├── repo-index.md
+    ├── glossary.md
+    └── api-reference.md
+```
+
+---
+
+**Navigation**: Start with `KNOWLEDGE_GRAPH.md` for visual overview.
+
+**Feedback**: Report issues at https://github.com/openshift/enhancements/issues

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -53,3 +53,36 @@ HACKMD_IMAGE=enhancements-hackmd-cli:latest # hackmd-cli image
 .PHONY: report-image
 report-image:
 	$(RUNTIME) build -f ./hack/Dockerfile.hackmd-cli --tag $(HACKMD_IMAGE)
+
+##@ Agentic Docs Evaluation
+
+.PHONY: eval
+eval: ## Run all agentic docs evaluations
+	@echo "Running agentic docs evaluations..."
+	test/eval/run-eval.sh
+
+.PHONY: eval-filter
+eval-filter: ## Run evaluations matching FILTER pattern (e.g., FILTER=anti-pattern)
+	@test -n "$(FILTER)" || (echo "Error: FILTER not set. Usage: make eval-filter FILTER=navigation"; exit 1)
+	@echo "Running evaluations (filter: $(FILTER))..."
+	test/eval/run-eval.sh "$(FILTER)"
+
+.PHONY: eval-navigation
+eval-navigation: ## Run navigation scenario tests
+	@echo "Running navigation scenarios..."
+	test/eval/run-eval.sh navigation
+
+.PHONY: eval-anti-pattern
+eval-anti-pattern: ## Run anti-pattern scenarios (tests what docs prevent)
+	@echo "Running anti-pattern scenarios..."
+	test/eval/run-eval.sh anti-pattern
+
+.PHONY: eval-view
+eval-view: ## Open web UI to view evaluation results
+	@echo "Opening evaluation results viewer..."
+	npx --yes promptfoo@latest view
+
+.PHONY: eval-clean
+eval-clean: ## Clean evaluation cache
+	@echo "Cleaning evaluation cache..."
+	rm -rf .promptfoo/

ai-docs/DESIGN_PHILOSOPHY.md

@@ -0,0 +1,121 @@
+# OpenShift Design Philosophy
+
+**Purpose**: Core principles guiding OpenShift architecture and development
+
+**Last Updated**: YYYY-MM-DD
+
+---
+
+## Table of Contents
+
+1. [Kubernetes Foundation](#kubernetes-foundation)
+2. [The Operator Pattern](#the-operator-pattern)
+3. [Immutable Infrastructure](#immutable-infrastructure)
+4. [API-First Design](#api-first-design)
+5. [Declarative Over Imperative](#declarative-over-imperative)
+6. [Upgrade Safety](#upgrade-safety)
+7. [Observability by Default](#observability-by-default)
+
+---
+
+## Kubernetes Foundation
+
+### Desired State vs Current State
+
+**Core Principle**: Describe what you want, Kubernetes makes it happen.
+
+```
+User declares:  "I want 3 replicas"  (Desired State)
+Kubernetes sees: "I have 1 replica"  (Current State)
+Controller:     "I'll create 2 more" (Reconciliation)
+```
+
+**Why This Matters**:
+- Self-healing: If a pod dies, controller recreates it
+- Idempotent: Applying same config multiple times = same result
+- Eventual consistency: System converges to desired state
+
+---
+
+## The Operator Pattern
+
+**Principle**: Extend Kubernetes with domain-specific knowledge.
+
+**Pattern**: CustomResourceDefinition + Controller = Operator
+
+**Benefits**:
+- Codifies operational knowledge
+- Automates Day 2 operations
+- Follows Kubernetes patterns
+
+---
+
+## Immutable Infrastructure
+
+**Principle**: Nodes are immutable. Changes require reboot.
+
+**Implementation**: RHCOS + rpm-ostree + Ignition + MachineConfig
+
+**Benefits**:
+- Predictable state
+- Easier rollback
+- Reduced configuration drift
+
+---
+
+## API-First Design
+
+**Principle**: Everything is an API resource.
+
+**Pattern**: All configuration via Kubernetes/OpenShift APIs (no manual SSH, no local files)
+
+**Benefits**:
+- GitOps-friendly
+- Auditable
+- Version-controlled
+
+---
+
+## Declarative Over Imperative
+
+**Principle**: Declare intent, not steps.
+
+**Example**:
+- ❌ Imperative: "Run pod1, then pod2, then update service"
+- ✅ Declarative: "I want this state" (controller figures out steps)
+
+---
+
+## Upgrade Safety
+
+**Principle**: Zero-downtime upgrades for platform and workloads.
+
+**Mechanisms**:
+- CVO orchestrates operator upgrades
+- Rolling updates for nodes
+- Upgrade ordering (etcd → kube → operators)
+
+---
+
+## Observability by Default
+
+**Principle**: Platform components expose metrics, logs, and health status.
+
+**Implementation**:
+- Prometheus metrics
+- Status conditions (Available/Progressing/Degraded)
+- Structured logging
+
+---
+
+## Cross-Cutting Concerns
+
+- **Security by default**: RBAC, SCCs, network policies
+- **Multi-tenancy**: Namespace isolation
+- **Supportability**: must-gather, diagnostics
+
+---
+
+**See Also**:
+- [Operator Patterns](./platform/operator-patterns/)
+- [Platform APIs](./domain/openshift/)