From 38c643119529828f8fd46098ec54ab7c4dd3a568 Mon Sep 17 00:00:00 2001
From: Andy Scherzinger <info@andy-scherzinger.de>
Date: Fri, 27 Mar 2026 19:29:29 +0100
Subject: [PATCH] docs: extend guidance

Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
---
 AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ad7b02ebf1ca..a825310a978c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,6 +3,8 @@
   - SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 # Agents.md
+
+This file provides guidance to all AI agents (Claude, Codex, Gemini, etc.) working with code in this repository.
 
 You are an experienced engineer specialized on Java, Kotlin and familiar with the platform-specific details of Android.
 
@@ -34,19 +36,74 @@ The commenting signs need to be used depending on the file type.
 ```plaintext
 SPDX-FileCopyrightText: <YEAR> Nextcloud GmbH and Nextcloud contributors
 SPDX-License-Identifier: AGPL-3.0-or-later
+```
+Kotlin/Java:
+```kotlin
+/*
+ * Nextcloud - Android Client
+ *
+ * SPDX-FileCopyrightText: <year> Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+```
+
+XML:
+```xml
+<!--
+  ~ Nextcloud - Android Client
+  ~
+  ~ SPDX-FileCopyrightText: <year> Nextcloud GmbH and Nextcloud contributors
+  ~ SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 ```
 
 Avoid creating source files that implement multiple types; instead, place each type in its own dedicated source file.
+
+## Design
+
+- Follow Material Design 3 guidelines
+- In addition to any Material Design wording guidelines, follow the Nextcloud wording guidelines at https://docs.nextcloud.com/server/latest/developer_manual/design/foundations.html#wording
+- Ensure the app works in both light and dark theme
+- Ensure the app works with different server primary colors by using the colorTheme of viewThemeUtils
 
-## Commit and Pull Request Guidelines
+## Commit and Pull Request Guidelines
+
+### Commits
+
+- All commits must be signed off (`git commit -s`) per the Developer Certificate of Origin (DCO). All PRs target `master`. Backports use `/backport to stable-X.Y` in a PR comment.
+
+- Commit messages must follow the [Conventional Commits v1.0.0 specification](https://www.conventionalcommits.org/en/v1.0.0/#specification) — e.g. `feat(chat): add voice message playback`, `fix(call): handle MCU disconnect gracefully`.
+
+- Every commit made with AI assistance must include an `AI-assistant` trailer identifying the coding agent, its version, and the model(s) used:
+
+  ```
+  AI-assistant: Claude Code 2.1.80 (Claude Sonnet 4.6)
+  AI-assistant: Copilot 1.0.6 (Claude Sonnet 4.6)
+  ```
+
+  General pattern: `AI-assistant: <coding-agent> <agent-version> (<model-name> <model-version>)`
+
+  If multiple models are used for different roles, extend the trailer with named roles:
+
+  ```
+  AI-assistant: OpenCode v1.0.203 (plan: Claude Opus 4.5, edit: Claude Sonnet 4.5)
+  ```
+
+  Pattern with roles: `AI-assistant: <coding-agent> <agent-version> (<role>: <model-name> <model-version>, <role>: <model-name> <model-version>)`
+
+### Pull Requests
 
-- **Commits**: Follow Conventional Commits format. Use `feat: ...`, `fix: ...`, or `refactor: ...` as appropriate in the commit message prefix.
 - Include a short summary of what changed. *Example:* `fix: prevent crash on empty todo title`.
 - **Pull Request**: When the agent creates a PR, it should include a description summarizing the changes and why they were made. If a GitHub issue exists, reference it (e.g., “Closes #123”).
 
-### Code Style
+## Code Style
 
-- Do not exceed 300 line of code per file.
+- Do not exceed 300 line of code per file.
+- 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 number.