Updated articles

2.-How-Kodo-Works.md

@@ -1,40 +0,0 @@
-# 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.
-

7.-Troubleshooting.md

@@ -1,46 +0,0 @@
-# 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

developer-guide/how-it-works.md

@@ -0,0 +1,42 @@
+# Code Review with Kodo
+
+Kodo is an AI reviewer that automatically checks your code in Pull Requests and answers questions about the code.
+
+## Getting Started
+
+To get an AI review on your Pull Request:
+
+1. Push your branch to the remote repository
+2. Create a Pull Request in Gitea
+3. Add `@kodobot` as a reviewer
+
+That's it — Kodo will automatically review your code once added.
+
+## Starting a Review Manually
+
+If you need to re-run the review or trigger it at a specific moment, just mention `@kodobot` in any PR comment:
+```
+@kodobot please review
+```
+
+## Skipping the Review
+
+**Don't want Kodo to review a specific PR?** Simply don't add `@kodobot` as a reviewer.
+
+**Want to disable the review even if `@kodobot` is added** (e.g. when using `CODEOWNERS`)?
+Add `[no ai]` to the Pull Request title:
+```
+[no ai] Fix typo in README
+```
+
+Kodo will not trigger on this PR — neither on creation nor on new pushes.
+
+## Asking Kodo a Question
+
+You can ask Kodo anything about the code directly in a PR comment:
+```
+@kodobot what does this function do?
+@kodobot is there a risk of a race condition here?
+```
+
+Kodo will reply in the comments.

developer-guide/limitations-and-best-practices.md

@@ -37,7 +37,3 @@
 - **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

techlead-guide/faq-troubleshooting.md

@@ -0,0 +1,31 @@
+# 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`
+- The secrets `CC_GITEATOKEN` and `CC_API_KEY` are set in the repository settings by the `devops` team
+- The runner `kodo-review` is online and available
+- The PR title does **not** contain `[no ai]`
+
+---
+
+## Common Causes & Fixes
+
+### 1. 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

techlead-guide/how-to-integrate.md

@@ -7,12 +7,11 @@ Manually launching and configuring the tool is quite a challenging task and requ
 ## 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
+Use the following script to integrate the Kodo tool into your Gitea actions. Add your `.gitea/workflows/kodo-reviewer.yaml` file with the following content
 
 ``` yml
 name: AI Code Reviewer Assistant for Gitea
@@ -40,6 +39,8 @@ This script will run automatically when a Pull Request is created or updated. If
 
 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.**
+1. The `secrets.CC_GITEATOKEN` environment variable must contain a token for the user @kodobot.
+2. The `secrets.CC_API_KEY` environment variable must contain a token for access to AI model.
+
+**Important:** All these environment variables must be created in advance by the `devops` team, and you use them as they are.
 

what-is-kodo-reviewer.md

@@ -4,6 +4,8 @@
 
 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 |
@@ -21,6 +23,8 @@ Kodo AI Reviewer is an AI-powered automated code review tool. It integrates into
 
 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