docs: prerequisites and Ollama setup in §4, RAG primer in §8, gh/Cursor troubleshooting

Made-with: Cursor

README.md

@@ -36,15 +36,77 @@
 
 ## 4) Быстрый запуск OpenClaude
 
-### 4.1 Установка
+### 4.0 Предварительные требования
+
+Для любого сценария нужны **Node.js 18+** и **npm** (идут вместе с официальной сборкой Node).
+
+Проверка:
+
+```bash
+node -v
+npm -v
+```
+
+Дальше по шагам:
+
+1. установить **OpenClaude CLI** (раздел **4.1**);
+2. для **локальных** моделей через Ollama — установить и запустить **Ollama** (раздел **4.2**), затем профиль из **4.3**;
+3. для облака (OpenAI / DeepSeek) достаточно ключей API — см. **4.4** и **4.5**.
+
+Если при запуске OpenClaude появится предупреждение вроде `ripgrep not found`, установите **ripgrep** (`rg`) и проверьте `rg --version` в том же терминале.
+
+### 4.1 Установка OpenClaude
 
 ```bash
 npm install -g @gitlawb/openclaude
+openclaude --version
 ```
 
-Если при запуске появится предупреждение вроде `ripgrep not found`, установите **ripgrep** (`rg`) в систему и проверьте `rg --version` в том же терминале, где стартуете OpenClaude.
+### 4.2 Установка и запуск Ollama (для локального профиля)
 
-### 4.2 Локальный Ollama-профиль (бесплатно)
+Сайт проекта: [https://ollama.com](https://ollama.com)
+
+**Linux** (типовой скрипт установки):
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+После установки сервис часто уже включён (`systemctl status ollama`). При необходимости: `sudo systemctl enable --now ollama`.
+
+**macOS** (Homebrew):
+
+```bash
+brew install --cask ollama
+```
+
+**Windows**: установщик с [страницы загрузки](https://ollama.com/download) или:
+
+```powershell
+winget install Ollama.Ollama
+```
+
+Проверка CLI:
+
+```bash
+ollama --version
+```
+
+Убедитесь, что API доступен на `http://127.0.0.1:11434` (на Windows приложение после установки обычно уже поднимает сервер; при сомнении запустите `ollama serve` в отдельном окне терминала).
+
+Скачайте хотя бы одну модель для работы с OpenClaude (пример ниже совпадает с профилем в **4.3**):
+
+```bash
+ollama pull qwen2.5-coder:7b
+```
+
+Быстрая проверка генерации:
+
+```bash
+ollama run qwen2.5-coder:7b
+```
+
+### 4.3 Локальный Ollama-профиль (бесплатно)
 
 macOS / Linux:
 
@@ -71,7 +133,7 @@ openclaude
 ollama launch openclaude --model qwen2.5-coder:7b
 ```
 
-### 4.3 OpenAI-профиль
+### 4.4 OpenAI-профиль
 
 macOS / Linux:
 
@@ -92,7 +154,7 @@ $env:OPENAI_MODEL="gpt-4o"
 openclaude
 ```
 
-### 4.4 DeepSeek-профиль
+### 4.5 DeepSeek-профиль
 
 macOS / Linux:
 
@@ -228,12 +290,35 @@ direnv allow
 
 ## 8) Минимальный RAG стек (локально)
 
+### Что такое RAG
+
+**RAG (Retrieval-Augmented Generation)** — подход, при котором модель отвечает не только из «общих» весов, а **сначала находит релевантные фрагменты в ваших данных** (документы, база знаний, код), подмешивает их в контекст и уже тогда формулирует ответ.
+
+### Из чего состоит RAG-стек
+
+1. **Документы** — `md` / `pdf` / `txt`, wiki, выгрузки и т.д.
+2. **Chunking** — разбиение текста на фрагменты фиксированного размера с перекрытием.
+3. **Embeddings** — векторное представление каждого фрагмента.
+4. **Vector DB** — хранение векторов и поиск ближайших соседей по запросу.
+5. **Retriever** — например MCP-инструмент `search_docs`: достаёт релевантный контекст по вопросу пользователя.
+6. **LLM** — генерирует ответ с учётом найденного контекста (и при желании с явными ссылками на источники).
+
+Плюсы такого контура:
+
+- ответы опираются на **ваши** материалы;
+- обычно **меньше голых галлюцинаций** по фактам из документации;
+- проще **проверять происхождение** ответа (по найденным чанкам и источникам).
+
+### Минимальная локальная конфигурация (этот репозиторий)
+
 Рекомендуемая база:
 
 - Embeddings: `nomic-embed-text` (через Ollama)
 - Vector DB: Qdrant
 - Retrieval tool: MCP `search_docs`
 
+Готовый пример скриптов и compose: `docs/rag-mcp-starter/`.
+
 Минимальная схема:
 
 1. Сложить документы (`md/txt/pdf`)
@@ -369,6 +454,8 @@ gh auth status
 
 Это самый удобный вариант для GitHub: авторизация один раз и нормальная работа `git pull/push` и `gh`.
 
+Если **`gh repo view`** или API в другой среде (CI, удалённый агент) возвращают ошибку про отсутствие репозитория, хотя у вас локально всё ок — см. пояснение в `docs/openclaude-with-repositories.md` (раздел «Частые ошибки», подраздел про GitHub CLI).
+
 ### 12.2 Через PAT по HTTPS
 
 1. Создать Personal Access Token на GitHub (минимальные нужные scopes).

docs/openclaude-with-repositories.md

@@ -106,6 +106,18 @@ git remote set-url origin git@github.com:OWNER/REPO.git
 - Смешивание нескольких аккаунтов в одном credential helper.
 - Отсутствуют локальные зависимости проекта (тесты не запускаются).
 
+### GitHub CLI: `Could not resolve to a Repository` или `Repository not found`
+
+На **вашей машине** `gh repo view OWNER/REPO` может работать (например, после `gh auth login` или с корректным классическим token), а в **другой среде** (CI, удалённый агент, «облачная» сессия без вашего локального credential store) — нет: там часто **нет той же авторизации** или репозиторий **приватный** и для этой среды не выдан доступ.
+
+Что проверить:
+
+1. **Fine-grained PAT**: в разделе доступа к репозиториям явно добавлен нужный репозиторий (или группа «All repositories», если так задумано). Один только заголовок в UI не гарантирует, что токен передан в ту среду, где выполняется команда.
+2. **Permissions**: для `gh repo view` как минимум чтение метаданных репозитория (в терминах GitHub — **Metadata** read и при необходимости **Contents** read).
+3. **Контекст агента**: удалённый агент должен работать в **workspace = клон нужного репозитория** и иметь способ подставить токен (`GH_TOKEN`, `gh auth login` в этой среде и т.д.). Локальный успех команды у вас в PowerShell не переносится автоматически в облако.
+
+Если цель — чтобы автоматизация сама делала коммиты/PR в приватный репозиторий, выдайте секрет с PAT в этой среде и ограничьте права токена минимально необходимыми scope.
+
 ## 9) Рабочий чек-лист перед началом
 
 ```bash

docs/quickstart-30min.md

@@ -2,7 +2,7 @@
 
 Короткий маршрут "с нуля до рабочего стенда" на Ubuntu.
 
-Если вы на **Windows**, установите Ollama и Node.js локально, затем для запуска OpenClaude на локальной модели используйте блоки **Windows PowerShell** в `README.md` (раздел «4) Быстрый запуск OpenClaude»). Полный стек ниже (Docker, bash-скрипты, пути `~/...`) удобнее повторять в **WSL2** или на Linux-сервере с тем же репозиторием.
+Если вы на **Windows**, установите Ollama и Node.js локально, затем для запуска OpenClaude на локальной модели используйте блоки **Windows PowerShell** в `README.md` (раздел «4) Быстрый запуск OpenClaude»: предусловия **4.0**, установка CLI **4.1**, установка Ollama **4.2**, профиль **4.3**). Полный стек ниже (Docker, bash-скрипты, пути `~/...`) удобнее повторять в **WSL2** или на Linux-сервере с тем же репозиторием.
 
 ## 0) Что получится
 
@@ -21,6 +21,8 @@ sudo systemctl start docker
 
 ## 2) Установка Ollama
 
+Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `README.md`, раздел **4.2**.
+
 ```bash
 curl -fsSL https://ollama.com/install.sh | sh
 sudo systemctl enable ollama