docs: add AI agent documentation with progressive disclosure (PROJQUAY-9897)

[HammerMeetNail]

Summary

• Add documentation files for AI coding assistants (Claude Code, Gemini CLI)
• Follow progressive disclosure principles to keep main files concise
• Create detailed topic-specific documentation in agent_docs/ directory

Files Added

• CLAUDE.md: Entry point for Claude Code
• GEMINI.md: Entry point for Gemini CLI
• AGENTS.md: Concise project overview with quick reference
• agent_docs/architecture.md: Component details, CRD structure, configuration
• agent_docs/development.md: Building, testing, code generation
• agent_docs/deployment.md: OLM deployment, container builds

Test plan

• Verify markdown files render correctly on GitHub
• Verify cross-references between files work as expected

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

Six new markdown documentation files introduced: AGENTS.md serves as the main project overview, with CLAUDE.md and GEMINI.md as reference pointers; three detailed documentation files (architecture.md, deployment.md, development.md) under agent_docs/ directory cover project structure, deployment procedures, and local development workflows respectively.

Changes

Cohort / File(s)	Summary
Root-level documentation AGENTS.md, CLAUDE.md, GEMINI.md	New entry-point and reference documentation files introducing the Container Security Operator project overview with cross-references to detailed documentation.
Detailed documentation agent_docs/architecture.md, agent_docs/deployment.md, agent_docs/development.md	New documentation covering project architecture (components, CRDs, configuration), OLM-based deployment procedures, and development workflow (prerequisites, building, testing, code generation, CI checks).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify descriptions in agent_docs/architecture.md align with actual project structure and CRD definitions
• Validate deployment instructions and referenced components in agent_docs/deployment.md
• Confirm development setup steps and commands in agent_docs/development.md are accurate and functional

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (5)

AGENTS.md (2)

15-25: Add language identifier to code block (line 17).

The project structure code block is missing a language identifier, which the markdownlint tool flags as MD040. While not a critical issue, adding a language specifier improves consistency and rendering.

🔎 Proposed fix

-```
+```
 cmd/security-labeller/  # Entrypoint
 labeller/               # Core controller (informers, reconciliation)
 secscan/                # Registry client for vulnerability data
 image/                  # Container image ID parsing
 apis/secscan/v1alpha1/  # CRD types
 generated/              # Auto-generated clients (do not edit)
 bundle/                 # OLM deployment manifests
-```
+```

(Note: This is a text/tree structure, so using an empty language identifier or text is acceptable.)

---

36-42: Use markdown link syntax for cross-references to improve discoverability.

Lines 40–42 use a text-based reference format (@agent_docs/...) that won't render as clickable links on GitHub. Converting these to proper markdown links will improve navigation and user experience.

🔎 Proposed fix

 For specific topics, see:
 
-- @agent_docs/architecture.md - Component details, CRD structure, configuration
-- @agent_docs/development.md - Building, testing, code generation
-- @agent_docs/deployment.md - OLM deployment, container builds
+- [architecture.md](agent_docs/architecture.md) - Component details, CRD structure, configuration
+- [development.md](agent_docs/development.md) - Building, testing, code generation
+- [deployment.md](agent_docs/deployment.md) - OLM deployment, container builds

CLAUDE.md (1)

1-3: Use consistent markdown link syntax and clarify purpose.

Line 3 references AGENTS.md as plain text (@AGENTS.md). This format differs from GEMINI.md (@./AGENTS.md) and won't render as a clickable link. Additionally, the file lacks context explaining what "CLAUDE" is or why users should read AGENTS.md.

🔎 Proposed fix

 # CLAUDE
 
-@AGENTS.md
+Claude Code users: Please see [AGENTS.md](AGENTS.md) for project overview and setup instructions.

(Alternatively, adjust the message to match your preferred entry-point tone.)

GEMINI.md (1)

1-3: Use consistent markdown link syntax and align with CLAUDE.md format.

Line 3 uses @./AGENTS.md, which differs from CLAUDE.md's @AGENTS.md format. Neither renders as a clickable link. Also, the file lacks context about "GEMINI" and why this entry point exists.

🔎 Proposed fix

 # GEMINI
 
-Please follow instructions from @./AGENTS.md
+Gemini CLI users: Please see [AGENTS.md](AGENTS.md) for project overview and setup instructions.

(Adjust the message tone to match your entry-point style.)

agent_docs/deployment.md (1)

50-67: Add language identifiers to YAML code blocks.

The YAML code blocks in the deploy steps (lines 51–54 and 64–67) lack language specifiers. While not critical, adding yaml will improve rendering consistency and syntax highlighting.

🔎 Proposed fix

Apply to both YAML blocks:

-   ```yaml
+   ```yaml
    # bundle/manifests/container-security-operator.v1.0.0.clusterserviceversion.yaml
    image: quay.io/<namespace>/container-security-operator
-   ```
+   ```

-   ```yaml
+   ```yaml
    # bundle/cso.catalogsource.yaml
    image: quay.io/<namespace>/cso-catalog
-   ```
+   ```

(Note: The markdown as rendered may already have language specifiers; verify in the source.)

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between d82a6eb and afecb6a.

📒 Files selected for processing (6)

• AGENTS.md (1 hunks)
• CLAUDE.md (1 hunks)
• GEMINI.md (1 hunks)
• agent_docs/architecture.md (1 hunks)
• agent_docs/deployment.md (1 hunks)
• agent_docs/development.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

AGENTS.md

17-17: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Tests

🔇 Additional comments (3)

agent_docs/architecture.md (1)

1-62: Comprehensive architecture documentation—well organized and clear.

This documentation provides a solid overview of the operator's architecture, components, and CRD structure. The component descriptions, CRD details, and configuration table are well-structured and easy to follow for developers and operators.

agent_docs/development.md (1)

1-86: Development documentation is accurate and comprehensive.

All referenced make targets (build, vendor, installcrds, run, codegen, get-code-generator, devenv) exist in the Makefile and match the documented behavior. The file provides clear, well-structured guidance for building, running, testing, and generating code, with helpful comments throughout.

agent_docs/deployment.md (1)

17-28: Hack scripts verified—all three exist in the repository.

The scripts ./hack/build.sh, ./hack/deploy.sh, and ./hack/teardown.sh are all present and executable. The documentation is ready for merge.