OAPE-877: Standardize AGENTS.md and agent harness docs for ESO

.coderabbit.yaml

@@ -0,0 +1,54 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# See https://docs.coderabbit.ai/reference/configuration for all fields and default values
+knowledge_base:
+  code_guidelines:
+    filePatterns:
+      - "harness-evals/harness-docs/*-guidelines.md"
+      - "AGENTS.md"
+      - "CONTRIBUTING.md"
+reviews:
+  high_level_summary: true
+  high_level_summary_in_walkthrough: true
+  poem: false
+  review_status: true
+  commit_status: true
+  collapse_walkthrough: true
+  sequence_diagrams: false
+  path_instructions:
+    - path: "api/v1alpha1/**"
+      instructions: |
+        Review CRD type changes for CEL validation rules, immutability markers,
+        bounds constraints, and corresponding .testsuite.yaml test coverage.
+        See harness-evals/harness-docs/api-contracts-guidelines.md.
+    - path: "pkg/controller/**"
+      instructions: |
+        Check error classification (IrrecoverableError/RetryRequiredError/UserConfigurationError),
+        requeue behavior, and that new managed resources are registered in
+        controllerManagedResources and HasObjectChanged. See harness-evals/harness-docs/error-handling-guidelines.md
+        and harness-evals/harness-docs/performance-guidelines.md.
+  tools:
+    github-checks:
+      timeout_ms: 120000
+chat:
+  auto_reply: true
+code_generation:
+  docstrings: false
+instructions:
+  review: |
+    IMPORTANT: The following PR metadata checks are mandatory requirements,
+    not suggestions. Report violations as actionable review comments with
+    severity "important" or "warning", NOT as nitpicks.
+
+    **Commit messages** (REQUIRED): Every commit MUST follow the format
+    `<JIRA-ID>: short imperative description` (e.g., `ESO-142: add proxy egress
+    network policy`). The Jira project can be any valid project (ESO, OAPE, etc.).
+    Reject commits with generic messages like "fix bug", "update code",
+    "address review comments", or commits missing a Jira ticket number.
+
+    **PR title** (REQUIRED): MUST be concise (<70 chars), imperative, and
+    include the Jira ticket number (e.g., "ESO-142: Add proxy egress network
+    policy"). Reject titles that are vague or missing the ticket number.
+
+    **PR description** (REQUIRED): MUST explain what changed, why, and how.
+    Reject PRs with empty or minimal descriptions that don't help reviewers
+    understand the motivation.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,52 @@
+---
+name: Bug Report
+about: Report a bug in the External Secrets Operator
+labels: kind/bug
+---
+
+## Describe the Bug
+
+<!-- A clear description of the bug. -->
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+<!-- What you expected to happen. -->
+
+## Actual Behavior
+
+<!-- What actually happened. Include error messages or logs if available. -->
+
+## Environment
+
+- OpenShift / Kubernetes version:
+- Operator version (`oc get csv -n external-secrets-operator`):
+- External Secrets operand version:
+- Secret provider (AWS, Vault, Azure, GCP, etc.):
+
+## Relevant Resources
+
+> **Redact** secret values, credentials, tokens, private keys, and personal data before posting resources or logs in a public issue.
+
+```yaml
+# oc get esc cluster -o yaml
+```
+
+```yaml
+# oc get esm cluster -o yaml
+```
+
+## Operator Logs
+
+```text
+# oc logs -n external-secrets-operator deployment/external-secrets-operator-controller-manager
+```
+
+## Additional Context
+
+<!-- Any other context: screenshots, related issues, workarounds tried. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+labels: kind/feature
+---
+
+## Summary
+
+<!-- One-sentence description of the feature. -->
+
+## Motivation
+
+<!-- Why is this needed? What problem does it solve? -->
+
+## Proposed Solution
+
+<!-- How should it work? If it involves API changes, describe the CRD field structure. -->
+
+## Alternatives Considered
+
+<!-- Other approaches you've thought about and why they were ruled out. -->
+
+## Additional Context
+
+<!-- Related Jira tickets (ESO, OAPE, etc.), enhancement proposals, upstream issues, or links. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+## Description
+
+### What changed?
+<!-- Summarize the changes made in this PR. -->
+
+### Why?
+<!-- What problem does this solve? What motivated this change? -->
+
+### How?
+<!-- Briefly describe the approach taken. Mention key design decisions, trade-offs, or alternatives considered. -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] CRD / API change
+- [ ] Refactoring (no functional change)
+- [ ] Documentation
+- [ ] CI / build
+
+## Checklist
+
+- [ ] `make verify` passes (vet, fmt, deps, bindata, generated files, govulncheck, git diff)
+- [ ] `make test` passes (unit + API integration tests)
+- [ ] `make lint` passes
+- [ ] New/changed CRD fields have appropriate CEL validation; add `.testsuite.yaml` tests for new CEL rules
+- [ ] New managed resources added to `controllerManagedResources`, `buildCacheObjectList()`, `HasObjectChanged`, and the ordered install sequence
+- [ ] No hand-edits to generated files (`bindata.go`, `zz_generated.deepcopy.go`, CRD YAML, fakes)
+- [ ] Error paths use the correct error type (`IrrecoverableError` / `RetryRequiredError` / `UserConfigurationError`)
+
+## Testing
+
+<!-- How was this tested? Which make targets were run? For E2E, which label filter? -->
+
+## Additional Context
+
+<!-- Screenshots, logs, related PRs, or anything reviewers should know. -->

.markdownlint-cli2.yaml

@@ -0,0 +1,35 @@
+# markdownlint-cli2 config.
+# globs: files to lint (allowlist).
+# References:
+# - https://github.com/DavidAnson/markdownlint-cli2
+# - https://github.com/DavidAnson/markdownlint
+
+globs:
+  - "*.md"
+  - "harness-evals/harness-docs/**/*.md"
+  - "docs/**/*.md"
+  - ".github/**/*.md"
+  - "test/**/*.md"
+
+# Generated; regenerated by `make docs`.
+ignores:
+  - "docs/api_reference.md"
+
+config:
+  # Disabled rules.
+  MD013: false # line-length
+  MD034: false # no-bare-urls
+  MD033: false # no-inline-html
+  MD010: false # no-hard-tabs
+  MD036: false # no-emphasis-as-heading
+  MD009: false # no-trailing-spaces
+  MD041: false # first-line-heading
+  MD046: false # code-block-style
+  MD032: false # blanks-around-lists
+  MD024: # no-duplicate-heading
+    siblings_only: true
+
+  # Enabled by default (called out for discoverability):
+  # MD022 blanks-around-headings
+  # MD031 blanks-around-fences
+  # MD040 fenced-code-language

AGENTS.md

@@ -0,0 +1,117 @@
+# External Secrets Operator — Agentic Documentation
+
+**Component**: External Secrets Operator for Red Hat OpenShift
+**Repository**: openshift/external-secrets-operator
+
+> **Platform Patterns**: See [openshift/enhancements/ai-docs/](https://github.com/openshift/enhancements/tree/master/ai-docs) for operator patterns, testing practices, security guidelines, and cross-repo ADRs.
+
+## What is ESO?
+
+Manages the lifecycle of the upstream [external-secrets](https://github.com/external-secrets/external-secrets) project on OpenShift. Deploys and configures the operand via static YAML manifests embedded as bindata — it is not a fork.
+
+**Key Principle**: The operator owns the operand deployment; users configure via two singleton CRs (`ExternalSecretsConfig`, `ExternalSecretsManager`), both named `cluster`.
+
+## Core Components
+
+| Component | Purpose | Location |
+|-----------|---------|----------|
+| ExternalSecrets Controller | Operand lifecycle (install, update, delete) | `pkg/controller/external_secrets/` |
+| ESM Controller | Status aggregation, default ESM creation | `pkg/controller/external_secrets_manager/` |
+| CRD Annotator | cert-manager CA injection on CRDs (conditional) | `pkg/controller/crd_annotator/` |
+
+**Quick Start**: `oc get esc cluster -o yaml` | `oc get esm cluster -o yaml` | `oc get pods -n external-secrets`
+
+## Critical Patterns
+
+1. **NOT Server-Side Apply** — all updates use `UpdateWithRetry` (Get → set ResourceVersion → Update). Co-managed resources (Secret, ConfigMap) use `patchResourceMetadata` for metadata-only JSON Patch. Never introduce SSA.
+2. **Bindata pipeline** — operand manifests are pre-rendered from upstream Helm charts at build time (`hack/update-external-secrets-manifests.sh`), embedded via `openshift/build-machinery-go`. `pkg/operator/assets/bindata.go` is generated — **never hand-edit**.
+3. **Immutable cert-manager fields** — `mode`, `injectAnnotations`, `issuerRef` in CertManagerConfig are immutable via CEL `self == oldSelf`. Network policy entries (name+componentName) also cannot be removed once added.
+
+## Domain Guidelines
+
+Detailed rules for each domain are in `harness-evals/harness-docs/`. Read the relevant file before modifying that area.
+
+| Guideline | Scope |
+|-----------|-------|
+| [Security](harness-evals/harness-docs/security-guidelines.md) | CEL validation, annotation/label restrictions, container hardening, RBAC, network policies, TLS |
+| [Performance](harness-evals/harness-docs/performance-guidelines.md) | Label-filtered caches, change detection, event predicates, requeue strategy, concurrency |
+| [Error Handling](harness-evals/harness-docs/error-handling-guidelines.md) | Error classification (Irrecoverable/Retry/UserConfig), status conditions, requeue matrix, events |
+| [API Contracts](harness-evals/harness-docs/api-contracts-guidelines.md) | Singleton enforcement, field immutability, CEL rules, list map keys, `.testsuite.yaml` patterns |
+| [Testing](harness-evals/harness-docs/testing-guidelines.md) | Unit tests, API integration tests (envtest), E2E with Ginkgo labels, make targets |
+| [Integration](harness-evals/harness-docs/integration-guidelines.md) | cert-manager, OLM, proxy, CNO trusted CA, console, metrics, multi-arch, webhooks |
+
+## Cross-Cutting Conventions
+
+- **Generated files**: Never hand-edit `bindata.go`, `fake_ctrl_client.go`, `zz_generated.deepcopy.go`, or CRD YAML in `config/crd/bases/`. Regenerate with `make manifests generate update-bindata` or `go generate`.
+- **Go style**: stdlib `testing` only (no Ginkgo for unit tests, no testify except E2E utils). Table-driven tests with `t.Run`. Call `t.Parallel()` on outer function and each subtest. Use `t.Setenv()` instead of `os.Setenv`.
+- **Constants**: All string constants (asset names, label keys, env var names) live in `constants.go`. Do not scatter literals across source files.
+- **New managed resources**: Must be added to `controllerManagedResources`, `buildCacheObjectList()`, `HasObjectChanged` type-switch, and the ordered install sequence. See `harness-evals/harness-docs/ESO_DEVELOPMENT.md` section 2.
+- **Commit messages**: Always include the Jira ticket number and a clear imperative description. Format: `<JIRA-ID>: short description` (e.g., `ESO-142: add proxy egress network policy`). The Jira project can be any valid project (ESO, OAPE, etc.). If no Jira ticket exists, use a descriptive imperative summary. Never use generic messages like "fix bug" or "update code".
+- **PR checklist**: Run `make verify` (vet, fmt, deps, bindata, generated files, govulncheck, markdownlint, git diff), `make test`, and `make lint` before submitting. `make verify` is the single gate that CI enforces.
+
+## Common Pitfalls
+
+1. **Never return both `RequeueAfter` and a non-nil error** from `Reconcile` — return one or the other.
+2. **Use the cached client for managed resources** (`app=external-secrets`). Use `UncachedClient` only for objects outside the cache (cert-manager Issuers, user-provided Secrets).
+3. **`Decode*ObjBytes` helpers panic on failure** — intentional for build-time-constant assets; do not wrap them in error handling.
+4. **Operator RBAC markers** (`+kubebuilder:rbac`) go in controller Go files; operand RBAC lives in static YAML under `bindata/`.
+5. More contributor pitfalls: `harness-evals/harness-docs/ESO_DEVELOPMENT.md` → Common Mistakes.
+
+## Documentation Structure
+
+```text
+harness-evals/harness-docs/
+├── *-guidelines.md            # Enforceable domain guidelines (security, testing, API, …)
+├── domain/                    # ExternalSecretsConfig, ExternalSecretsManager API docs
+├── architecture/              # Controller internals, resource management, bindata pipeline
+│   └── components.md
+├── decisions/                 # Component-specific ADRs (bindata, update strategy, NP naming)
+├── exec-plans/                # Feature planning
+├── references/
+│   ├── ecosystem.md           # Links to Platform patterns
+│   └── enhancements.md        # Enhancement proposals catalog
+├── ESO_DEVELOPMENT.md         # Development workflows, build targets, common tasks
+└── ESO_TESTING.md             # Test suites, patterns, E2E labels
+```
+
+**AI Agent Path**: `harness-evals/harness-docs/*-guidelines.md` (as needed) → `domain/` → `architecture/` → `decisions/` → `ESO_DEVELOPMENT.md`
+
+## Namespaces & Image Resolution
+
+| Namespace | Purpose |
+|-----------|---------|
+| `external-secrets-operator` | Operator deployment (OLM-managed) |
+| `external-secrets` | Operand namespace (operator-created) |
+
+| Env Var | Purpose |
+|---------|---------|
+| `RELATED_IMAGE_EXTERNAL_SECRETS` | Operand image (OLM disconnected convention) |
+| `RELATED_IMAGE_BITWARDEN_SDK_SERVER` | Bitwarden image |
+
+## Error Classification
+
+| Type | Requeue | Example |
+|------|---------|---------|
+| `IrrecoverableError` | No | Missing RELATED_IMAGE_* env var |
+| `RetryRequiredError` | 30s | Transient API server error |
+| `UserConfigurationError` | Only NotFound | Invalid cert-manager issuer ref |
+
+## Conditional Deployments
+
+| Operand Component | Condition |
+|-------------------|-----------|
+| `external-secrets` (core) | Always |
+| `external-secrets-webhook` | Always |
+| `external-secrets-cert-controller` | cert-manager **disabled** |
+| `bitwarden-sdk-server` | Bitwarden plugin **enabled** |
+
+## Key References
+
+- [Enhancement: ESO on OpenShift](https://github.com/openshift/enhancements/blob/master/enhancements/external-secrets-operator/external-secrets-operator.md)
+- [Enhancement: Network Policies](https://github.com/openshift/enhancements/blob/master/enhancements/external-secrets-operator/external-secrets-network-policy.md)
+- [Enhancement: Component Config](https://github.com/openshift/enhancements/blob/master/enhancements/external-secrets-operator/external-secrets-component-config.md)
+- [Upstream external-secrets](https://github.com/external-secrets/external-secrets) | [OpenShift Docs](https://docs.openshift.com/)
+
+---
+
+**Platform Documentation**: openshift/enhancements/ai-docs/