diff --git a/.claude/skills/android-java-to-kotlin/references/PROJECT-CONVENTIONS.md b/.claude/skills/android-java-to-kotlin/references/PROJECT-CONVENTIONS.md
index 5d2e15f89d00..be6fe9f38fd2 100644
--- a/.claude/skills/android-java-to-kotlin/references/PROJECT-CONVENTIONS.md
+++ b/.claude/skills/android-java-to-kotlin/references/PROJECT-CONVENTIONS.md
@@ -44,8 +44,14 @@ asks for; default to the "Nextcloud GmbH and Nextcloud contributors" line.
 
 - No decorative divider comments (`// ==== ====`, `// ---- Title ----`). `// region` /
   `// endregion` for IDE folding is allowed and should match the file's existing style.
-- Prefer self-explanatory names over per-function KDoc. Preserve genuinely informative
-  Javadoc as KDoc (invariant 4); drop noise.
+- Names carry the explanation, not comments. If a name needs a comment to be understood,
+  rename or decompose instead. Do not add KDoc to a function just because it is new.
+- Preserve genuinely informative Javadoc as KDoc (invariant 4); drop noise. A comment
+  earns its place only for a non-obvious invariant, a platform/server workaround, or an
+  ordering requirement — and it explains **why**, never **what**.
+- Never narrate the conversion itself: no "was a Java thread, now a coroutine", no
+  "changed from X to Y", no references to the PR, the issue, or this conversation.
+  Comments describe the code as it stands. That history belongs in the commit message.
 - Do not use multiple boolean flags to model state — use an `enum`/sealed class.
 
 ## Modern Java Interop
diff --git a/AGENTS.md b/AGENTS.md
index 9614463afedf..7cc05d89e677 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -185,9 +185,7 @@ All contributions generated or assisted by this agent must fully comply with:
 - Line length: **120 characters**
 - Standard Android Studio formatter with EditorConfig.
 - Kotlin preferred for new code; legacy Java still present.
-- Do not use decorative section-divider comments of any kind (e.g. `// ── Title ───`, `// ------`, `// ======`).
 - Every new file must end with exactly one empty trailing line (no more, no less).
-- Do not add comments, documentation for every function you created instead make it self explanatory as much as possible.
 - Create models, states in different files instead of doing it one single file.
 - Do not use magic numbers.
 - Apply fail fast principle instead of using nested if-else statements.
@@ -195,3 +193,26 @@ All contributions generated or assisted by this agent must fully comply with:
 - Use modern Java for Java classes. Optionals, virtual threads, records, streams if necessary.
 - Avoid hardcoded strings, colors, dimensions. Use resources.
 - Run lint, spotbugsGplayDebug, detekt, spotlessKotlinCheck and fix findings inside the files that have been changed.
+
+## Comments
+
+Names carry the explanation, not comments. A function or variable whose purpose is not obvious from its
+name is a naming problem or a decomposition problem — rename it or split it, do not describe it in a comment.
+Assume the reader knows Kotlin, Java and the Android framework.
+
+Write a comment only when the code cannot carry the information itself: a non-obvious invariant, a workaround
+for a platform or server bug, an ordering requirement, or a decision whose alternatives look equally valid and
+are not. When you do write one, explain **why**, never **what**.
+
+Never write:
+
+- Comments that restate the code (`// increase the counter` above `counter++`).
+- KDoc/Javadoc added to a function just because the function is new.
+- Narration of the change or its history: "changed from X to Y", "previously this failed", "this is not a
+  permanent failure so we now retry", "fixes the crash reported in the issue". Comments describe the code as
+  it is today. A reader six months from now has no access to the issue, the PR discussion, or the conversation
+  that produced the change — that context belongs in the commit message and the PR description.
+- Decorative section-divider comments of any kind (e.g. `// ── Title ───`, `// ------`, `// ======`).
+  `// region` / `// endregion` for IDE folding is allowed where the file already uses it.
+
+Existing comments that are still accurate stay. Delete the ones the change makes wrong or obsolete.