Added docs folder

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.
+

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

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