From ab3dd6ee6bda917d33cf07b7b4cf8098376fc99b Mon Sep 17 00:00:00 2001
From: Alexey Efimchik <alexey.efimchik@developertools.com>
Date: Wed, 20 May 2026 08:53:24 +0000
Subject: [PATCH] Update FAQ

---
 FAQ.md                 | 56 ++++++++++++++++++++++++++++++++++++++++++
 faq-troubleshooting.md | 31 -----------------------
 2 files changed, 56 insertions(+), 31 deletions(-)
 create mode 100644 FAQ.md
 delete mode 100644 faq-troubleshooting.md

diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..4cbada9
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,56 @@
+# 🔧 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
+
+### 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.
+
+---
+
+## ⚙️ Issues with Git Extensions (e.g., Git LFS)
+
+**Q: Why does my pipeline fail when using Git extensions like Git LFS?**
+
+A: Our image includes a standard Git installation, but additional Git extensions such as Git LFS are not bundled, as the AI reviewer is designed to work with small, standard code files and does not need to process large files.
+
+However, some extensions (like Git LFS) hook directly into Git at a low level, which can cause errors even if the reviewer never touches the large files themselves.
+
+**Example: Git LFS**
+
+If your repository uses Git LFS, the extension may interfere with the standard Git in our image and cause the review step to fail. The correct solution is to **explicitly disable LFS for the review step**:
+
+```yaml
+clone:
+  depth: full
+  lfs: false
+script:
+  - export GIT_LFS_SKIP_SMUDGE=1
+```
+
+> You do not need to install LFS into the image — disabling it for this step is the recommended approach.
+
+**Q: Can I install a Git extension directly into the image?**
+
+A: Technically yes, but it is not recommended. The reviewer is optimized for small, typical code repository files. Installing heavy extensions adds unnecessary overhead and is outside the intended use case.
+
+**Summary:** If you encounter Git extension-related errors, check whether the extension is hooking into Git globally and disable it explicitly for the review step.
+
+---
+
+## 📨 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
\ No newline at end of file
diff --git a/faq-troubleshooting.md b/faq-troubleshooting.md
deleted file mode 100644
index e2f2e05..0000000
--- a/faq-troubleshooting.md
+++ /dev/null
@@ -1,31 +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`
-- 🔑 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