From 4a59c2fd4f42941e5b71c429aeca9ab4f444c133 Mon Sep 17 00:00:00 2001
From: Alexey Efimchik <alexey.efimchik@developertools.com>
Date: Thu, 12 Mar 2026 12:03:22 +0700
Subject: [PATCH] Added docs folder

---
 .../ai-reviewer-output-format.md              | 101 ++++++++++++++++++
 docs/develoepr-guide/extension-of-rules.md    |  41 +++++++
 docs/develoepr-guide/faq-troubleshooting.md   |  46 ++++++++
 docs/develoepr-guide/how-to-integrate.md      |  45 ++++++++
 docs/devops-guide/reviewer-token.md           |  37 +++++++
 docs/user-guide/how-it-works.md               |  40 +++++++
 .../limitations-and-best-practices.md         |  43 ++++++++
 docs/user-guide/what-is-kodo-reviewer.md      |  37 +++++++
 8 files changed, 390 insertions(+)
 create mode 100644 docs/develoepr-guide/ai-reviewer-output-format.md
 create mode 100644 docs/develoepr-guide/extension-of-rules.md
 create mode 100644 docs/develoepr-guide/faq-troubleshooting.md
 create mode 100644 docs/develoepr-guide/how-to-integrate.md
 create mode 100644 docs/devops-guide/reviewer-token.md
 create mode 100644 docs/user-guide/how-it-works.md
 create mode 100644 docs/user-guide/limitations-and-best-practices.md
 create mode 100644 docs/user-guide/what-is-kodo-reviewer.md
diff --git a/docs/develoepr-guide/ai-reviewer-output-format.md b/docs/develoepr-guide/ai-reviewer-output-format.md
new file mode 100644
index 0000000..d39cc43
--- /dev/null
+++ b/docs/develoepr-guide/ai-reviewer-output-format.md
@@ -0,0 +1,101 @@
+# AI Code Reviewer — Output Comment Format
+
+## 1. Summary Comment
+
+The summary comment is posted by the bot as a **top-level PR comment** after the review is complete.
+It provides a high-level assessment of the entire diff.
+
+### Format
+
+```
+🔴 Code quality assessment: <Poor | Acceptable | Excellent>
+
+ℹ️ Conclusion: <Short explanation of the most critical finding and its impact>
+
+❌ Merge: No - <reason>
+✅ Merge: Yes
+```
+
+### Example
+
+> 🔴 Code quality assessment: Poor
+>
+> ℹ️ Conclusion: The commit introduces a critical bug where `Stopwatch.StartNew()` is called twice on consecutive lines (lines 15–16 in `samples/AR/App.cs`). The duplicate assignment statement must be removed.
+>
+> ❌ Merge: No - blocking issue must be resolved first
+
+### Quality Levels
+
+| Badge | Label | Meaning |
+|---|---|---|
+| 🔴 | Poor | Blocking issues found, must not merge |
+| 🟡 | Acceptable | Minor suggestions only |
+| ✅ | Excellent | No issues found |
+
+---
+
+## 2. Inline Comments
+
+Inline comments are posted **directly on the changed lines** in the diff.
+They follow the [**Conventional Comments**](https://conventionalcomments.org/) approach to make severity and intent immediately clear.
+
+### Conventional Comments Format
+
+```
+<emoji> <label> (<optional decoration>): <subject>
+
+<body — explanation of the issue>
+
+💻 Suggested Code:
+<code block with the fix>
+```
+
+### Example
+
+Posted inline on line 16 of `samples/AR/App.cs`:
+
+---
+
+> 🔴 Issue (Blocking): Duplicate Stopwatch initialization
+>
+> The `Stopwatch.StartNew()` call on line 15 is repeated on line 16, which overwrites the first instance. This appears to be an accidental duplicate that should be removed.
+>
+> 💻 Suggested Code:
+> ```csharp
+> public void Run(string reportName, Dictionary<string, object[]>? reportParameters)
+> {
+>     var sw = Stopwatch.StartNew();
+>     Trace.WriteLine($"{sw.ElapsedMilliseconds} : Start { reportName}!");
+>     _reportExport.Run(reportName, reportParameters, sw);
+>     sw.Stop();
+>     Trace.WriteLine($"{sw.ElapsedMilliseconds} : End!");
+> }
+> ```
+
+
+## 3. Request Changes or Approve Pull Request
+
+After posting comments, the bot submits a **formal PR review** with one of two states.
+
+### Request Changes
+
+Triggered when one or more **Blocking** issues are found.
+
+```
+Status:  ❌ Request Changes
+```
+
+The PR is blocked from merging (if branch protection rules are enabled) until:
+- The author fixes the blocking issues
+- The bot re-reviews after a new commit (`synchronize` event)
+- A human reviewer overrides the block
+
+---
+
+### Approved
+
+Triggered when no blocking issues are found.
+
+```
+Status:  ✅ Approved
+```
diff --git a/docs/develoepr-guide/extension-of-rules.md b/docs/develoepr-guide/extension-of-rules.md
new file mode 100644
index 0000000..e474183
--- /dev/null
+++ b/docs/develoepr-guide/extension-of-rules.md
@@ -0,0 +1,41 @@
+# Review Prompt Extension
+
+The Kodo tool supports the ability to extend the built-in prompt for review. This can be done in the following way
+
+## 1. The CONSTITUTION.md file
+
+You can create a `.review` folder if it does not exist and add a `CONSTITUTION.md` file to this folder, which will contain part of the prompt that will be read by the tool during execution.
+
+```
+my-project/
+├── .review/                  ← Create this folder
+│   └── CONSTITUTION.md       ← Your custom rules
+├── src/
+└── ...
+```
+
+The `.review` folder must be placed in the **root of your repository**.
+
+### 1.1. Example of the CONSTITUTION.md file.
+
+Example of a file you can create
+
+``` markdown
+# Additional rules for code reviews.
+1. Do not check dependency declarations in code files
+2. Do not check namespaces
+
+# Knowledge about the project structure
+This project contains the following modules:
+1. DataEngine - the core for processing user data.
+2. Viewer - a tool for visualizing user data.
+```
+
+### 1.2. Recommendations for the CONSTITUTION.md file
+
+There are some recommendations for creating content for this file:
+
+1. Do not provide contradictory instructions and information.
+2. Provide a detailed description of any modules and rules.
+3. Do not make this file large, as it will be part of the prompt, which has a limited context.
+
diff --git a/docs/develoepr-guide/faq-troubleshooting.md b/docs/develoepr-guide/faq-troubleshooting.md
new file mode 100644
index 0000000..a648349
--- /dev/null
+++ b/docs/develoepr-guide/faq-troubleshooting.md
@@ -0,0 +1,46 @@
+# AI Code Reviewer — Troubleshooting: Reviewer Did Not Run
+
+## Quick Checklist
+
+Before diving deeper, verify the basics:
+
+- The workflow file exists at `.gitea/workflows/kodo-reviewer.yaml`
+- Secrets `CC_GITEATOKEN` and `CC_API_KEY` are set in repository settings
+- The runner `kodo-review` is online and available
+- The PR title does **not** contain `[no ai]`
+- The event that triggered the workflow matches one of the configured triggers
+
+---
+
+## Common Causes & Fixes
+
+### 1. Secrets are missing or misconfigured
+
+If `CC_GITEATOKEN` or `CC_API_KEY` are not set, the action will fail silently or error out.
+
+**How to check:**
+1. Go to repository **Settings → Secrets**
+2. Verify both secrets exist:
+   - `CC_GITEATOKEN` — Gitea token with read/write access to PRs
+   - `CC_API_KEY` — Anthropic API key
+
+**Fix:** Add/regenerate missing secrets or contact with `devops` team.
+
+---
+
+### 2. PR title contains `[no ai]`
+
+The action checks for `[no ai]` in the PR title and skips execution if found.
+
+**Fix:** Remove `[no ai]` from the PR title and push a new commit or re-open the PR.
+
+---
+
+## Still Not Working?
+
+Provide the following information when asking for help from `devops` team:
+
+- Runner name and status (`kodo-review`)
+- Workflow run URL
+- Event that was expected to trigger the review
+- Observed and expected behavior
diff --git a/docs/develoepr-guide/how-to-integrate.md b/docs/develoepr-guide/how-to-integrate.md
new file mode 100644
index 0000000..0161954
--- /dev/null
+++ b/docs/develoepr-guide/how-to-integrate.md
@@ -0,0 +1,45 @@
+# CI/CD integration for Gitea VCS
+
+## Introduction
+
+Manually launching and configuring the tool is quite a challenging task and requires a deep understanding of the AI service being used and the built-in operating rules. Therefore, to simplify the task, we have created pre-prepared actions for launching and updating the tool.
+
+## 1. User for review
+
+For the tool to work, you need to add a user who will perform the review. Add to `CODEOWNERS` file for repository if you want it to be assigned automatically, or add it manually if necessary.
+
+Use this Gitea user by default: `@kodobot`.
+
+## 2. Prepared step script for Gitea
+
+Use the following script to integrate the tool into your Gitea actions. All necessary improvements and integrations must be performed independently by each team. Add your `.gitea/workflows/kodo-reviewer.yaml` file with the following content
+
+``` yml
+name: AI Code Reviewer Assistant for Gitea
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  claude-assistant:
+    runs-on: kodo-review
+    steps:
+      - name: Run AI Code Reviewer
+        uses: https://code.wynenterprise.io/kodo/reviewer@main
+        with:
+          gitea_token: ${{ secrets.CC_GITEATOKEN }}
+          anthropic_api_key: ${{ secrets.CC_API_KEY }}
+```
+
+This script will run automatically when a Pull Request is created or updated. If necessary, you can start it manually via the Gitea interface and add additional conditions required for start.
+
+## 2.1. Environment variables for script
+
+When configuring the tool, always strictly adhere to the following rules for certain environment variables:
+
+1. The `secrets.CC_GITEATOKEN` environment variable must contain a token for the user @kodobot. **Request this token from the devops team.**
+2. The `secrets.CC_API_KEY` environment variable must contain a token for access ti AI model. **Request this token from the devops team.**
+
diff --git a/docs/devops-guide/reviewer-token.md b/docs/devops-guide/reviewer-token.md
new file mode 100644
index 0000000..0379294
--- /dev/null
+++ b/docs/devops-guide/reviewer-token.md
@@ -0,0 +1,37 @@
+# Gitea Token Setup for AI Code Reviewer
+
+## Required Token Permissions
+
+| Permission | Level | Reason |
+|---|---|---|
+| **repository** | Read and Write | Read PR details, branches, diff; post review comments |
+| **issue** | Read and Write | Create and delete progress comments on PRs (Gitea treats PR comments as issues internally) |
+| **user** | Read | Fetch current bot user info to verify reviewer assignment |
+
+All other permissions (`activitypub`, `misc`, `notification`, `organization`, `package`) should be set to **No Access**.
+
+## How to Generate the Token
+
+1. Log in to Gitea as the **bot account** that will be assigned as a reviewer
+2. Go to **Settings** → **Applications** (top right avatar → Settings → Applications)
+3. Under **Manage Access Tokens** click **Generate Token**
+4. Fill in:
+   - **Token Name**: `ai-code-reviewer` (or any descriptive name)
+   - **Expiration**: set according to your security policy
+5. Set permissions as described in the table above
+6. Click **Generate Token**
+7. **Copy the token immediately** — it will not be shown again
+
+## Adding the Token to Your Repository
+
+1. Go to your repository → **Settings** → **Secrets**
+2. Click **Add Secret**
+3. Set:
+   - **Name**: `CC_GITEATOKEN`
+   - **Value**: paste the token generated above
+4. Click **Save**
+
+## Important Notes
+
+- The token must belong to the account that is **assigned as a reviewer** on pull requests — this is how the reviewer verification check works
+- Treat the token as a password — never commit it to the repository
\ No newline at end of file
diff --git a/docs/user-guide/how-it-works.md b/docs/user-guide/how-it-works.md
new file mode 100644
index 0000000..cf491f5
--- /dev/null
+++ b/docs/user-guide/how-it-works.md
@@ -0,0 +1,40 @@
+# Gitea VCS Usage
+
+## Introduction
+
+When working with Gitea, you can use several methods to interact with the tool.
+
+## 1. Launch of code review
+
+To start a code review, you must first prepare the following:
+
+1. Push the branch with changes to the remote repository
+2. Create a Pull Request in Gitea VCS, adding the `@kodobot` reviewer user to the Pull Request
+
+# 1.1. Automatic Start
+
+After completing the preparatory stage of creating a Pull Request with the AI reviewer added, the code review **will be launched automatically.**
+
+# 1.2. Manual Start
+
+If for some reason you need to start the review yourself, use the `@kodobot` tag when writing a comment in the pull request.
+
+# 2. Code review prevention
+
+To prevent the review from starting, we can use the following methods
+
+## 2.1. Tag [no ai] in the pull request title
+
+When a pull request is created with the tag `[no ai]` in the pull request title, and when new changes are pushed to the pull request, the reviewer will not be triggered for that pull request.
+This can be useful if you use `CODEOWNERS` file in your repository.
+
+## 2.2. Do not add AI use to PR
+
+You can choose not to add the `@kodobot` AI Reviewer user at all, and then the kodo review tool will never run for this Pull Request.
+
+⚠️ **Important:** you **do not need** to write the `[no ai]` tag if no AI user has been added to the Pull Request for review.
+
+## 3. Questions for AI
+
+You can use the `@kodobot` tag in a Pull Request comment to ask the AI anything. After adding the `@kodobot` tag to your message you will receive a response from AI user.
+
diff --git a/docs/user-guide/limitations-and-best-practices.md b/docs/user-guide/limitations-and-best-practices.md
new file mode 100644
index 0000000..73369ea
--- /dev/null
+++ b/docs/user-guide/limitations-and-best-practices.md
@@ -0,0 +1,43 @@
+# Limitations & Best Practices
+
+## Limitations
+
+### Context & Understanding
+- **No business logic awareness** — AI only sees code, not product requirements
+- **Limited context window** — the model has its own context window, which can hold a limited amount of information.
+- **No decision history** — does not store the history of previous executions, only reads existing information in Pull Request.
+- **Hallucinations** — may confidently suggest incorrect solutions or non-existent APIs
+- **Large PR degradation** — review quality drops significantly for PRs with 1000+ lines changed
+
+### Process Constraints
+- **Does not replace humans** — final decision always belongs to the author and human reviewer
+- **Slower on large PRs** — response time grows with the size of changes
+- **No memory between PRs** — each review starts from scratch with no prior context
+- **Trigger dependency** — only runs on configured events (`[no ai]` in title disables it)
+
+## Best Practices
+
+### Writing PRs for Better AI Review
+
+- **Keep PRs small and focused** — one logical change per PR, ideally under 400 lines
+- **Write a clear PR description** — explain *what* and *why*, not just *what changed*
+- **Add `[no ai]` to title** when the PR is trivial (version bumps, typo fixes, formatting)
+- **Split refactoring from feature changes** — mixed PRs confuse both AI and humans
+
+### Working with AI Comments
+
+- **Treat AI comments as suggestions, not mandates** — use your judgment
+- **Verify all suggested code** before applying — AI can introduce bugs
+- **Use `@kodobot` in comments** to ask follow-up questions about specific lines
+- **Don't blindly resolve AI comments** — acknowledge or explain why you disagree
+- **Re-trigger review after major changes** by pushing a new commit
+
+### Security
+
+- **Never put secrets in PR descriptions or comments** — AI logs may capture them
+- **Store `anthropic_api_key` and `gitea_token` in repository secrets**, not in workflow files
+- **Audit AI comments on security-sensitive PRs** (auth, crypto, infra) with extra care
+
+### Team Workflow
+
+- **Establish a policy** on when to override or ignore AI suggestions
diff --git a/docs/user-guide/what-is-kodo-reviewer.md b/docs/user-guide/what-is-kodo-reviewer.md
new file mode 100644
index 0000000..d41e618
--- /dev/null
+++ b/docs/user-guide/what-is-kodo-reviewer.md
@@ -0,0 +1,37 @@
+# Kodo AI Reviewer
+
+## 🤖 What is it?
+
+Kodo AI Reviewer is an AI-powered automated code review tool. It integrates into your CI/CD pipeline, analyzes pull request changes, and helps teams maintain high code quality — without the bottlenecks of manual review.
+
+---
+
+## 🚀 Why use it?
+
+| | Feature | What it means for you |
+|---|---|---|
+| ⏱️ | **Saves time** | Automates the routine review process so engineers focus on what matters |
+| 📋 | **Single source of truth** | Consistent, reproducible feedback — no human bias or mood swings |
+| 📈 | **Better code quality** | Catches style issues, logic flaws, and potential bugs comprehensively |
+| 🕐 | **Always available** | Reviews code 24/7 — no waiting for a teammate to free up |
+| 🔧 | **Highly customizable** | Extend built-in rules or create entirely new checks for your needs |
+| 💬 | **Interactive** | Ask follow-up questions and get instant responses to your comments |
+
+---
+
+## 🌍 Where does it work?
+
+Kodo AI Reviewer works directly inside your **CI/CD pipeline** — it runs automatically on every pull request, no extra setup required beyond the initial configuration.
+
+---
+
+## ✨ How does it work?
+
+### 🔁 CI/CD Flow
+
+When a pull request is opened or updated, Kodo kicks in automatically:
+
+1. 📥 **Reads the environment** — loads your action configuration and prepares the review context
+2. 🔍 **Analyzes your changes** — scans the diff for issues, improvements, and code quality signals
+3. 💬 **Leaves comments** — posts inline feedback and a summary conclusion on the PR
+4. 🗣️ *(Optional)* **Responds to you** — mention the predefined tag in any comment and Kodo will reply directly to your question or request
\ No newline at end of file
