From ddc0a5ec39b1cd8e1367241fa6d149068ca8de55 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= <a_meszaros@apple.com>
Date: Fri, 8 May 2026 12:36:56 +0200
Subject: [PATCH 1/2] improve: add documentation guidline for agents
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>
---
 .gitignore                                    |  1 +
 AGENTS.md                                     | 31 ++++++++++++++++++-
 .../en/docs/documentation/reconciler.md       |  4 +--
 3 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index f85f1c7a21..6ba8d23672 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,3 +17,4 @@ target/
 .aider*
 
 docs/content/en/docs/testindex/
+.claude/
diff --git a/AGENTS.md b/AGENTS.md
index 2c311dac1d..f47485cfdb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -188,6 +188,36 @@ public class ConfigMapDependent extends CRUDKubernetesDependentResource<ConfigMa
 - Reference issues in commit messages when applicable
 - Ensure CI checks pass (format, license, tests)
 
+### Documentation Update
+
+When implementing features or making code changes, always evaluate whether the change affects user-facing behavior that should be documented. If so, update the documentation as part of the same change.
+
+#### Documentation Location
+
+Documentation is a Hugo/Docsy site at `docs/content/en/docs/`:
+
+- `documentation/` — core feature docs (reconciler, eventing, error handling, caches, rate limiting, testing, features)
+- `documentation/dependent-resource-and-workflows/` — dependent resources and workflows
+- `documentation/operations/` — operational concerns (config, metrics, logging, health probes, leader election, helm)
+- `getting-started/` — introductory guides and best practices
+- `migration/` — version migration guides
+- `faq/` — frequently asked questions
+
+#### Behavior
+
+1. After implementing a code change, check if it introduces, modifies, or removes user-facing behavior.
+2. Search the docs for pages covering the affected functionality.
+3. Update existing pages or add new sections to reflect the change.
+4. Skip if not relevant — internal refactors, test-only changes, and build tooling changes typically do not need doc updates.
+
+#### Guidelines
+
+- Match the tone and style of the existing documentation
+- Prefer adding code snippets
+- Keep explanations concise with code examples where helpful
+- If a change introduces a new feature, consider whether it belongs in an existing page or warrants a new one
+- For breaking changes, also update the relevant migration guide under `migration/`
+
 ## Common Issues and Solutions
 
 ### Build Issues
@@ -209,7 +239,6 @@ public class ConfigMapDependent extends CRUDKubernetesDependentResource<ConfigMa
 - **Discord:** https://discord.gg/DacEhAy
 - **Fabric8 Client:** https://github.com/fabric8io/kubernetes-client
 
-
 ## Additional Notes for AI Agents
 
 - The codebase makes extensive use of Java generics for type safety
diff --git a/docs/content/en/docs/documentation/reconciler.md b/docs/content/en/docs/documentation/reconciler.md
index bc8065fee5..0681fc2a23 100644
--- a/docs/content/en/docs/documentation/reconciler.md
+++ b/docs/content/en/docs/documentation/reconciler.md
@@ -98,10 +98,10 @@ typically instructs the framework to remove the finalizer after the dependent
 resource are cleaned up in `cleanup` implementation.
 
 ```java
-public DeleteControl cleanup(MyCustomResource customResource,Context context){
+public DeleteControl cleanup(MyCustomResource customResource,Context context) {
         // omitted code
     
-        return DeleteControl.defaultDelete();
+return DeleteControl.defaultDelete();
 }
 ```
 

From a26c400448e489f0be68ba1a2a5a65103e2e646e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= <a_meszaros@apple.com>
Date: Mon, 11 May 2026 10:45:07 +0200
Subject: [PATCH 2/2] wip
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>
---
 AGENTS.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f47485cfdb..c1b0494034 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -205,10 +205,11 @@ Documentation is a Hugo/Docsy site at `docs/content/en/docs/`:
 
 #### Behavior
 
-1. After implementing a code change, check if it introduces, modifies, or removes user-facing behavior.
-2. Search the docs for pages covering the affected functionality.
-3. Update existing pages or add new sections to reflect the change.
-4. Skip if not relevant — internal refactors, test-only changes, and build tooling changes typically do not need doc updates.
+1. Skip if not relevant — internal refactors, test-only changes, and build tooling changes typically do not need doc updates.
+2. After implementing a code change, check if it introduces, modifies, or removes user-facing behavior.
+3. Search the docs for pages covering the affected functionality.
+4. Update existing pages or add new sections to reflect the change.
+
 
 #### Guidelines