From c589a216be85050cf6c70146bd0f2d4e5f0589fa Mon Sep 17 00:00:00 2001
From: PTah <papatramp@gmail.com>
Date: Tue, 21 Apr 2026 15:37:43 +1000
Subject: [PATCH] docs: split handbook into docs/ by topic, slim root README,
 add docs index

Made-with: Cursor
---
 README.md                         | 542 ++----------------------------
 docs/README.md                    | 100 ++++++
 docs/START-HERE.md                |  11 +-
 docs/concepts-and-terms.md        |  37 ++
 docs/configure-profiles-direnv.md |  80 +++++
 docs/github-auth-remotes.md       |  50 +++
 docs/hardware-budgets.md          |  70 ++++
 docs/install-openclaude-cli.md    | 148 ++++++++
 docs/linux-server-fixes.md        |  18 +
 docs/local-llm-ollama.md          |  65 ++++
 docs/model-catalog.md             |   2 +
 docs/quickstart-30min.md          |   4 +-
 docs/rag-mcp-stack.md             |  62 ++++
 docs/rag-mcp-starter/README.md    |   4 +
 docs/repository-and-cli.md        |  32 ++
 docs/roadmap-next-steps.md        |  12 +
 16 files changed, 713 insertions(+), 524 deletions(-)
 create mode 100644 docs/README.md
 create mode 100644 docs/concepts-and-terms.md
 create mode 100644 docs/configure-profiles-direnv.md
 create mode 100644 docs/github-auth-remotes.md
 create mode 100644 docs/hardware-budgets.md
 create mode 100644 docs/install-openclaude-cli.md
 create mode 100644 docs/linux-server-fixes.md
 create mode 100644 docs/local-llm-ollama.md
 create mode 100644 docs/rag-mcp-stack.md
 create mode 100644 docs/repository-and-cli.md
 create mode 100644 docs/roadmap-next-steps.md

diff --git a/README.md b/README.md
index 715c3ac..778a6e9 100644
--- a/README.md
+++ b/README.md
@@ -1,532 +1,40 @@
 # OpenClaude + Local LLM Handbook
 
-Практическая документация по запуску `openclaude` на сервере, подключению локальных и облачных моделей, работе с MCP/RAG и планированию железа под разные бюджеты.
+Репозиторий — **набор практических руководств** по запуску [OpenClaude](https://github.com/Gitlawb/openclaude) на своём железе, работе с **локальными и облачными** моделями, **MCP** и **RAG**, плюс пример минимального стека в `docs/rag-mcp-starter/`.
 
-## 1) Что такое LLM и токены
+Это **не** исходники OpenClaude: CLI ставится отдельно через npm (`@gitlawb/openclaude`). Сами гайды и скрипты вы клонируете отсюда.
 
-- **LLM (Large Language Model)** - большая языковая модель, которая генерирует текст токен за токеном.
-- **Токен** - кусок текста (слово, часть слова, знак, пробел), не всегда "целое слово".
-- **Скорость 1-5 токенов/с** - скорость генерации ответа моделью (decode speed).
-- Очень грубо: `5 ток/с` часто ощущается как `~15-25 символов/с`, но это зависит от языка и модели.
+## Зачем этот репозиторий
 
-## 2) Что такое MCP и зачем он нужен
+- собрать **понятный путь от терминов до рабочего стенда** без пролистывания одного гигантского файла;
+- держать **детали в `docs/`**, а в корне — только обзор и входные точки.
 
-**MCP (Model Context Protocol)** - стандарт для подключения инструментов и источников данных к AI-агенту.
+## С чего начать
 
-Простая схема:
+1. Коротко: **что это за проект vs CLI** → [docs/repository-and-cli.md](docs/repository-and-cli.md)  
+2. Полный указатель «**от простого к сложному**» → **[docs/README.md](docs/README.md)**  
+3. План по дням → [docs/START-HERE.md](docs/START-HERE.md)  
+4. Быстрый практический прогон (Ubuntu ~30 мин) → [docs/quickstart-30min.md](docs/quickstart-30min.md)
 
-- Модель = "мозг"
-- MCP-сервер = "шлюз к инструментам"
-- MCP-инструменты = конкретные действия (`search_docs`, `run_sql`, `create_ticket` и т.д.)
-
-Польза MCP:
-
-- Подключение к актуальным данным (документы, БД, API)
-- Контролируемое выполнение действий через схемы входа/выхода
-- Повторяемая интеграция для локальных и облачных сценариев
-
-## 3) Основные сценарии работы OpenClaude
-
-`openclaude` поддерживает разные провайдеры, включая:
-
-- OpenAI-compatible API
-- Ollama (локально)
-- DeepSeek (через OpenAI-compatible endpoint)
-- Gemini, GitHub Models, Codex и др.
-
-## 4) Быстрый запуск OpenClaude
-
-### 4.0 Предварительные требования
-
-Для любого сценария нужны **Node.js 18+** и **npm** (идут вместе с официальной сборкой Node).
-
-Проверка:
+## Клонирование
 
 ```bash
-node -v
-npm -v
+git clone https://github.com/PTah/openclaude-LLM-local.git
+cd openclaude-LLM-local
 ```
 
-Дальше по шагам:
+Если используете другой remote (fork), подставьте свой URL со страницы репозитория на GitHub.
 
-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` в том же терминале.
+| Тема | Документ |
+|------|-----------|
+| Термины (LLM, MCP, провайдеры) | [docs/concepts-and-terms.md](docs/concepts-and-terms.md) |
+| Установка CLI, Ollama, профили | [docs/install-openclaude-cli.md](docs/install-openclaude-cli.md) |
+| Локальные модели и `ollama` | [docs/local-llm-ollama.md](docs/local-llm-ollama.md) |
+| RAG и MCP, чек-лист подключения | [docs/rag-mcp-stack.md](docs/rag-mcp-stack.md) |
+| Пример стека (скрипты + compose) | [docs/rag-mcp-starter/](docs/rag-mcp-starter/) |
+| GitHub / PAT / SSH | [docs/github-auth-remotes.md](docs/github-auth-remotes.md) |
+| Железо под три бюджета | [docs/hardware-budgets.md](docs/hardware-budgets.md) |
 
-### 4.1 Установка OpenClaude
-
-```bash
-npm install -g @gitlawb/openclaude
-openclaude --version
-```
-
-### 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:
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
-export OPENAI_MODEL=qwen2.5-coder:7b
-openclaude
-```
-
-Windows PowerShell:
-
-```powershell
-$env:CLAUDE_CODE_USE_OPENAI="1"
-$env:OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
-$env:OPENAI_MODEL="qwen2.5-coder:7b"
-
-openclaude
-```
-
-Альтернатива без ручных переменных (если установлен Ollama и доступна команда `ollama launch`):
-
-```bash
-ollama launch openclaude --model qwen2.5-coder:7b
-```
-
-### 4.4 OpenAI-профиль
-
-macOS / Linux:
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-...
-export OPENAI_MODEL=gpt-4o
-openclaude
-```
-
-Windows PowerShell:
-
-```powershell
-$env:CLAUDE_CODE_USE_OPENAI="1"
-$env:OPENAI_API_KEY="sk-..."
-$env:OPENAI_MODEL="gpt-4o"
-
-openclaude
-```
-
-### 4.5 DeepSeek-профиль
-
-macOS / Linux:
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_BASE_URL=https://api.deepseek.com/v1
-export OPENAI_API_KEY=sk-...
-export OPENAI_MODEL=deepseek-chat
-openclaude
-```
-
-Windows PowerShell:
-
-```powershell
-$env:CLAUDE_CODE_USE_OPENAI="1"
-$env:OPENAI_BASE_URL="https://api.deepseek.com/v1"
-$env:OPENAI_API_KEY="sk-..."
-$env:OPENAI_MODEL="deepseek-chat"
-
-openclaude
-```
-
-## 5) Локальные бесплатные модели: где брать и что ставить
-
-### Где брать
-
-- Проще всего через `Ollama`: [https://ollama.com/library](https://ollama.com/library)
-
-### Рекомендуемый старт
-
-- `qwen2.5-coder:7b` - хороший баланс для кода
-- `qwen2.5:3b` - если сервер слабый
-- `llama3.1:8b` - универсальный сильный baseline
-- `deepseek-r1:8b` - reasoning-ориентированный вариант
-
-### Команды
-
-```bash
-ollama pull qwen2.5-coder:7b
-ollama pull qwen2.5:3b
-ollama pull llama3.1:8b
-ollama pull deepseek-r1:8b
-ollama list
-```
-
-## 6) Важный вопрос: локальные модели "дообучаются сами"?
-
-Короткий ответ: **нет**.
-
-- Обычная работа в чате не дообучает модель автоматически.
-- Качество повышают обычно так:
-  - обновляют модель/тег (`ollama pull ...`)
-  - улучшают системные промпты
-  - подключают RAG (документы + retrieval)
-- Полноценный finetune/LoRA - отдельный ML-процесс.
-
-## 7) Профили и переключение через direnv
-
-### 7.1 Профили
-
-Создать:
-
-```bash
-mkdir -p ~/.config/openclaude/profiles
-```
-
-`~/.config/openclaude/profiles/local.env`
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
-export OPENAI_MODEL=qwen2.5-coder:7b
-unset OPENAI_API_KEY
-```
-
-`~/.config/openclaude/profiles/openai.env`
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_BASE_URL=https://api.openai.com/v1
-export OPENAI_API_KEY=sk-REPLACE_ME
-export OPENAI_MODEL=gpt-4o
-```
-
-`~/.config/openclaude/profiles/deepseek.env`
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_BASE_URL=https://api.deepseek.com/v1
-export OPENAI_API_KEY=sk-REPLACE_ME
-export OPENAI_MODEL=deepseek-chat
-```
-
-Права:
-
-```bash
-chmod 600 ~/.config/openclaude/profiles/*.env
-```
-
-### 7.2 Установка direnv
-
-```bash
-sudo apt update
-sudo apt install -y direnv
-```
-
-Для bash:
-
-```bash
-echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
-source ~/.bashrc
-```
-
-Для zsh:
-
-```bash
-echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
-source ~/.zshrc
-```
-
-### 7.3 Автопрофиль на папку проекта
-
-В корне проекта:
-
-```bash
-cat > .envrc <<'EOF'
-source_env ~/.config/openclaude/profiles/local.env
-EOF
-direnv allow
-```
-
-На **Windows** нативный `direnv` используют реже; задайте переменные в текущей сессии PowerShell через `$env:ИМЯ="значение"`, добавьте их в профиль PowerShell, либо работайте в **WSL** и следуйте Linux-инструкциям выше.
-
-## 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`)
-2. Разбить на чанки (`chunk_size ~1000`, overlap `~120`)
-3. Сделать embeddings
-4. Записать в Qdrant
-5. Поднять MCP-инструмент `search_docs`
-6. Вызывать его из OpenClaude
-
-## 9) Быстрый чек-лист, если MCP "не виден"
-
-1. MCP-сервер стартует вручную:
-
-```bash
-python mcp_server.py
-```
-
-2. Импорты и зависимости установлены:
-
-```bash
-python -c "import fastmcp, qdrant_client, requests; print('ok')"
-```
-
-3. Пути в `~/.claude/settings.json` корректны (`command`, `args`)
-4. Qdrant доступен: `curl http://127.0.0.1:6333/collections`
-5. Ollama доступен: `curl http://127.0.0.1:11434/api/tags`
-
-## 10) План закупки железа под 3 бюджета
-
-Ориентиры даны для Linux-сервера и локального запуска LLM (Ollama/OpenAI-compatible).
-
-### Бюджет A: Минимальный (CPU-only)
-
-**Для кого:** старт, RAG, базовые задачи, без требований к высокой скорости.
-
-- CPU: 8-12 vCPU (современные ядра)
-- RAM: 32 GB (минимум 16 GB, но хуже)
-- Disk: NVMe 512 GB
-- GPU: нет
-
-Ожидания:
-
-- модели 3B-7B с умеренной скоростью
-- ориентир decode: примерно `1-6 ток/с` (зависит от модели и квантизации)
-
-Рекомендованные модели:
-
-- `qwen2.5:3b`
-- `qwen2.5-coder:7b` (если хватает RAM/терпения)
-
-### Бюджет B: Комфортный (1x GPU среднего класса)
-
-**Для кого:** ежедневная работа 1-3 пользователей, код + RAG в комфортном режиме.
-
-- CPU: 8-16 vCPU
-- RAM: 32-64 GB
-- GPU: 1x NVIDIA 12-16 GB VRAM (например, RTX 3060 12GB / 4070 Ti Super 16GB)
-- Disk: NVMe 1 TB
-
-Ожидания:
-
-- стабильная работа 7B/8B, лучше latency и throughput
-- ориентир decode: примерно `10-35 ток/с`
-
-Рекомендованные модели:
-
-- `qwen2.5-coder:7b`
-- `llama3.1:8b`
-- `deepseek-r1:8b`
-
-### Бюджет C: Производительный (1-2 GPU высокого класса)
-
-**Для кого:** команда, многозадачность, более тяжелые модели и высокая отзывчивость.
-
-- CPU: 16+ vCPU
-- RAM: 64-128 GB
-- GPU:
-  - вариант 1: 1x NVIDIA 24 GB VRAM (RTX 4090 / L40-class по бюджету)
-  - вариант 2: 2x GPU по 16-24 GB для масштабирования
-- Disk: NVMe 2 TB
-
-Ожидания:
-
-- уверенная работа 14B+ (квантизованные), параллельные запросы
-- ориентир decode: `25-80+ ток/с` в зависимости от модели/батча
-
-Рекомендованные модели:
-
-- 14B-класс инструкт/кодовые варианты
-- mix моделей: одна "быстрая дешевая", одна "качественная тяжелая"
-
-### Что критично кроме железа
-
-- стабильная версия драйверов CUDA (если NVIDIA)
-- быстрый NVMe (модели занимают много места)
-- мониторинг температуры/памяти/IO
-- резерв свободного диска под новые веса
-
-## 11) Практика обновления и обслуживания моделей
-
-- Смотреть установленные:
-
-```bash
-ollama list
-```
-
-- Обновлять нужные:
-
-```bash
-ollama pull qwen2.5-coder:7b
-```
-
-- Удалять старые:
-
-```bash
-ollama rm <model:tag>
-```
-
-- Проверять занятое место:
-
-```bash
-sudo du -h --max-depth=2 /usr/share/ollama /var/lib/ollama 2>/dev/null | sort -h | tail -n 30
-```
-
-## 12) Подключение к GitHub и PAT (без постоянных запросов пароля)
-
-### 12.1 Рекомендуемый путь через GitHub CLI
-
-```bash
-gh auth login
-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).
-2. Проверить, что remote в HTTPS:
-
-```bash
-git remote -v
-git remote set-url origin https://github.com/OWNER/REPO.git
-```
-
-3. Включить credential helper, чтобы не вводить PAT каждый раз:
-
-```bash
-git config --global credential.helper store
-```
-
-4. Выполнить `git pull` или `git push` и один раз ввести логин + PAT.
-
-### 12.3 Через SSH (альтернатива PAT)
-
-```bash
-ssh-keygen -t ed25519 -C "you@example.com"
-# Добавьте публичный ключ в GitHub account settings
-git remote set-url origin git@github.com:OWNER/REPO.git
-```
-
-SSH обычно удобнее для постоянной работы с приватными репозиториями.
-
-## 13) Частые проблемы и быстрые фиксы
-
-### 13.1 Скрипт запуска падает с `#!/usr/bin/env: No such file or directory`
-
-Причина: BOM в начале файла.
-
-Фикс:
-
-```bash
-sed -i '1s/^\xEF\xBB\xBF//' script.sh
-chmod +x script.sh
-```
-
-### 13.2 Почему после выбора зеркала apt все еще ходит в `ru.archive.ubuntu.com`
-
-Обычно источники лежат в `*.sources` (deb822), а не только в `sources.list`.
-Нужно менять и `URIs:` в deb822-блоках.
-
----
-
-## Roadmap продолжения
-
-Когда вернемся к теме, логично идти так:
-
-1. Проверка текущего сервера (CPU/RAM/GPU/NVMe)
-2. Выбор стартового профиля (`local`/`openai`/`deepseek`)
-3. Поднятие `openclaude` + smoke test
-4. Запуск минимального RAG с Qdrant
-5. Добавление MCP-инструментов под ваши рабочие данные
-6. Оптимизация скорости и стоимости (routing между моделями)
-
-## Дополнительные материалы в репозитории
-
-- Быстрый гайд: `docs/quickstart-30min.md`
-- Точка входа: `docs/START-HERE.md`
-- Готовый starter: `docs/rag-mcp-starter/`
-- Работа с GitHub/GitLab/Gitea: `docs/openclaude-with-repositories.md`
-- Подробно про SSH к GitHub: `docs/github-ssh-setup-and-troubleshooting.md`
-- Примеры cron-автоматизации: `docs/cron-examples.md`
-- Автоустановка cron: `scripts/install-cron.sh`
-- Каталог моделей: `docs/model-catalog.md`
-- Выбор runtime: `docs/runtime-choice.md`
-- Локальный Cursor-like стек: `docs/cursor-like-stack.md`
-- Честные ожидания: `docs/expectations.md`
-- Шаблон benchmark: `docs/bench-template.md`
-- Локальная генерация изображений: `docs/image-generation-local.md`
+Остальные файлы перечислены в **[docs/README.md](docs/README.md)**.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..5377fdf
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,100 @@
+# Документация: навигация от простого к сложному
+
+Этот каталог — основной вход: кратко **о чём репозиторий**, затем **термины**, далее **установка OpenClaude**, **локальные модели**, **RAG/MCP**, **эксплуатация**, **Git**, **железо и продвинутые темы**.
+
+---
+
+## 0. Что это за проект и где брать CLI
+
+| Документ | О чём |
+|----------|--------|
+| [repository-and-cli.md](repository-and-cli.md) | Чем этот handbook отличается от OpenClaude CLI; как клонировать репозиторий; откуда ставится `@gitlawb/openclaude` |
+
+---
+
+## 1. Термины и контекст
+
+| Документ | О чём |
+|----------|--------|
+| [concepts-and-terms.md](concepts-and-terms.md) | LLM, токены, MCP, типовые провайдеры |
+
+---
+
+## 2. Установка и конфигурация OpenClaude
+
+| Документ | О чём |
+|----------|--------|
+| [install-openclaude-cli.md](install-openclaude-cli.md) | Node/npm, установка CLI, Ollama по ОС, переменные окружения и профили (локально / OpenAI / DeepSeek), PowerShell |
+| [configure-profiles-direnv.md](configure-profiles-direnv.md) | Файлы профилей в `~/.config/openclaude/profiles`, direnv, Windows vs WSL |
+
+---
+
+## 3. Локальные LLM (Ollama)
+
+| Документ | О чём |
+|----------|--------|
+| [local-llm-ollama.md](local-llm-ollama.md) | Каталог моделей, рекомендации «с чего начать», миф про «самообучение», обслуживание (`pull`/`rm`/место) |
+| [model-catalog.md](model-catalog.md) | Расширенный обзор семейств моделей |
+
+---
+
+## 4. RAG, MCP, стек из этого репозитория
+
+| Документ | О чём |
+|----------|--------|
+| [rag-mcp-stack.md](rag-mcp-stack.md) | Что такое RAG, из чего состоит стек, минимальная связка с Qdrant + MCP, чек-лист если MCP не виден |
+| [rag-mcp-starter/](rag-mcp-starter/) | Docker Compose, `index.py`, `mcp_server.py`, скрипты установки и обслуживания |
+
+---
+
+## 5. Быстрый старт по времени и ролям
+
+| Документ | О чём |
+|----------|--------|
+| [START-HERE.md](START-HERE.md) | План на 1 / 3 / 7 дней |
+| [quickstart-30min.md](quickstart-30min.md) | Пошагово «с нуля» на Ubuntu (~30 минут) |
+| [expectations.md](expectations.md) | Облако vs локально: честные ожидания |
+| [runtime-choice.md](runtime-choice.md) | Выбор рантайма и окружения |
+
+---
+
+## 6. Эксплуатация и автоматизация
+
+| Документ | О чём |
+|----------|--------|
+| [cron-examples.md](cron-examples.md) | Примеры cron для моделей и стека |
+| `../scripts/install-cron.sh` | Установка типовых cron-задач из репозитория |
+
+---
+
+## 7. Git, GitHub, репозитории кода
+
+| Документ | О чём |
+|----------|--------|
+| [github-auth-remotes.md](github-auth-remotes.md) | `gh auth`, PAT, HTTPS, SSH |
+| [github-ssh-setup-and-troubleshooting.md](github-ssh-setup-and-troubleshooting.md) | SSH к GitHub подробно и типовые ошибки |
+| [openclaude-with-repositories.md](openclaude-with-repositories.md) | Поток с кодом, MCP вокруг Git-платформ, проблемы `gh` в CI/облаке |
+
+---
+
+## 8. Железо, бенчмарки, дополнительные сценарии
+
+| Документ | О чём |
+|----------|--------|
+| [hardware-budgets.md](hardware-budgets.md) | Три бюджета железа под локальные LLM |
+| [bench-template.md](bench-template.md) | Шаблон benchmark своих задач |
+| [cursor-like-stack.md](cursor-like-stack.md) | Локальный стек в духе IDE |
+| [image-generation-local.md](image-generation-local.md) | Локальная генерация изображений |
+| [linux-server-fixes.md](linux-server-fixes.md) | BOM в shell-скриптах, зеркала apt |
+
+---
+
+## 9. Куда двигаться после базы
+
+| Документ | О чём |
+|----------|--------|
+| [roadmap-next-steps.md](roadmap-next-steps.md) | Следующие шаги после минимального контура |
+
+---
+
+Вся структура предполагает линейное чтение сверху вниз; для «только поднять стенд за вечер» достаточно цепочки **repository-and-cli** → **install-openclaude-cli** → **quickstart-30min** → **rag-mcp-starter**.
diff --git a/docs/START-HERE.md b/docs/START-HERE.md
index fdef660..8946a33 100644
--- a/docs/START-HERE.md
+++ b/docs/START-HERE.md
@@ -1,15 +1,16 @@
 # START HERE
 
-Рекомендуемый порядок внедрения OpenClaude + local LLM.
+Рекомендуемый порядок внедрения OpenClaude + local LLM. Полная карта всех гайдов (от простого к сложному): [README.md](README.md) в каталоге `docs/`.
 
 ## План на 1 день (минимальный рабочий контур)
 
-1. Прочитать: `docs/quickstart-30min.md`
-2. Поднять минимальный стек:
+1. Определиться, где handbook и где CLI: `docs/repository-and-cli.md`
+2. Прочитать: `docs/quickstart-30min.md`
+3. Поднять минимальный стек:
    - `docs/rag-mcp-starter/install-minimal.sh`
-3. Проверить готовность:
+4. Проверить готовность:
    - `docs/rag-mcp-starter/healthcheck.sh --mode minimal`
-4. Зафиксировать рабочий профиль модели:
+5. Зафиксировать рабочий профиль модели:
    - обычно `qwen2.5-coder:7b`
    - для слабого сервера `qwen2.5:3b`
 
diff --git a/docs/concepts-and-terms.md b/docs/concepts-and-terms.md
new file mode 100644
index 0000000..d2725e0
--- /dev/null
+++ b/docs/concepts-and-terms.md
@@ -0,0 +1,37 @@
+# Термины: LLM, токены, MCP и сценарии OpenClaude
+
+Коротко — что есть что, прежде чем переходить к установке и железу.
+
+## LLM и токены
+
+- **LLM (Large Language Model)** — большая языковая модель, которая генерирует текст токен за токеном.
+- **Токен** — кусок текста (слово, часть слова, знак, пробел), не всегда «целое слово».
+- **Скорость (например 1–5 токенов/с)** — скорость генерации ответа моделью (decode speed).
+- Очень грубо: `5 ток/с` часто ощущается как `~15–25 символов/с`, но это зависит от языка и модели.
+
+## MCP
+
+**MCP (Model Context Protocol)** — стандарт для подключения инструментов и источников данных к AI-агенту.
+
+Простая схема:
+
+- Модель = «мозг»
+- MCP-сервер = «шлюз к инструментам»
+- MCP-инструменты = конкретные действия (`search_docs`, `run_sql`, `create_ticket` и т.д.)
+
+Польза MCP:
+
+- подключение к актуальным данным (документы, БД, API);
+- контролируемое выполнение действий через схемы входа/выхода;
+- повторяемая интеграция для локальных и облачных сценариев.
+
+## Сценарии работы OpenClaude
+
+`openclaude` поддерживает разные провайдеры, в том числе:
+
+- OpenAI-compatible API
+- Ollama (локально)
+- DeepSeek (через OpenAI-compatible endpoint)
+- Gemini, GitHub Models, Codex и др.
+
+Дальше: [установка CLI и зависимостей](install-openclaude-cli.md) → [профили и переменные окружения](configure-profiles-direnv.md).
diff --git a/docs/configure-profiles-direnv.md b/docs/configure-profiles-direnv.md
new file mode 100644
index 0000000..1d18270
--- /dev/null
+++ b/docs/configure-profiles-direnv.md
@@ -0,0 +1,80 @@
+# Профили OpenClaude и direnv
+
+Как хранить отдельные файлы окружения для локального / OpenAI / DeepSeek и подключать их при входе в каталог проекта.
+
+## 1. Файлы профилей
+
+Создайте каталог:
+
+```bash
+mkdir -p ~/.config/openclaude/profiles
+```
+
+`~/.config/openclaude/profiles/local.env`
+
+```bash
+export CLAUDE_CODE_USE_OPENAI=1
+export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
+export OPENAI_MODEL=qwen2.5-coder:7b
+unset OPENAI_API_KEY
+```
+
+`~/.config/openclaude/profiles/openai.env`
+
+```bash
+export CLAUDE_CODE_USE_OPENAI=1
+export OPENAI_BASE_URL=https://api.openai.com/v1
+export OPENAI_API_KEY=sk-REPLACE_ME
+export OPENAI_MODEL=gpt-4o
+```
+
+`~/.config/openclaude/profiles/deepseek.env`
+
+```bash
+export CLAUDE_CODE_USE_OPENAI=1
+export OPENAI_BASE_URL=https://api.deepseek.com/v1
+export OPENAI_API_KEY=sk-REPLACE_ME
+export OPENAI_MODEL=deepseek-chat
+```
+
+Права:
+
+```bash
+chmod 600 ~/.config/openclaude/profiles/*.env
+```
+
+## 2. Установка direnv (Linux)
+
+```bash
+sudo apt update
+sudo apt install -y direnv
+```
+
+Для bash:
+
+```bash
+echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Для zsh:
+
+```bash
+echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## 3. Автопрофиль на папку проекта
+
+В корне проекта:
+
+```bash
+cat > .envrc <<'EOF'
+source_env ~/.config/openclaude/profiles/local.env
+EOF
+direnv allow
+```
+
+На **Windows** нативный `direnv` используют реже; задайте переменные в текущей сессии PowerShell через `$env:ИМЯ="значение"`, добавьте их в профиль PowerShell, либо работайте в **WSL** и следуйте Linux-инструкциям выше.
+
+В OpenClaude также можно пользоваться встроенной настройкой провайдеров (`/provider` в CLI) — см. документацию upstream [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude).
diff --git a/docs/github-auth-remotes.md b/docs/github-auth-remotes.md
new file mode 100644
index 0000000..9b5a1fb
--- /dev/null
+++ b/docs/github-auth-remotes.md
@@ -0,0 +1,50 @@
+# Git: GitHub, PAT, `gh` и remotes
+
+Практичные способы не вводить пароль на каждом `git push` и нормально работать с `gh`.
+
+## 1. Рекомендуемый путь через GitHub CLI
+
+```bash
+gh auth login
+gh auth status
+```
+
+Удобно для GitHub: одна авторизация и нормальная работа `git pull`/`git push` и `gh`.
+
+Если **`gh repo view`** или API в другой среде (CI, удалённый агент) возвращают ошибку про отсутствие репозитория, хотя у вас локально всё ок — см. [openclaude-with-repositories.md](openclaude-with-repositories.md) (раздел «Частые ошибки», подраздел про GitHub CLI).
+
+## 2. Через PAT по HTTPS
+
+1. Создать Personal Access Token на GitHub (минимальные нужные scopes).
+2. Проверить, что remote в HTTPS:
+
+```bash
+git remote -v
+git remote set-url origin https://github.com/OWNER/REPO.git
+```
+
+3. Включить credential helper, чтобы не вводить PAT каждый раз:
+
+```bash
+git config --global credential.helper store
+```
+
+4. Выполнить `git pull` или `git push` и один раз ввести логин + PAT.
+
+## 3. Через SSH (альтернатива PAT)
+
+```bash
+ssh-keygen -t ed25519 -C "you@example.com"
+# Добавьте публичный ключ в GitHub account settings
+git remote set-url origin git@github.com:OWNER/REPO.git
+```
+
+SSH обычно удобнее для постоянной работы с приватными репозиториями.
+
+## 4. Подробности и типовые проблемы SSH
+
+- [github-ssh-setup-and-troubleshooting.md](github-ssh-setup-and-troubleshooting.md)
+
+## 5. OpenClaude и репозитории (потоки разработки, RAG с кода)
+
+- [openclaude-with-repositories.md](openclaude-with-repositories.md)
diff --git a/docs/hardware-budgets.md b/docs/hardware-budgets.md
new file mode 100644
index 0000000..00cb56d
--- /dev/null
+++ b/docs/hardware-budgets.md
@@ -0,0 +1,70 @@
+# Планирование железа под локальные LLM (3 бюджета)
+
+Ориентиры для Linux-сервера и локального запуска LLM (Ollama / OpenAI-compatible). Подробнее про ожидания к качеству: [expectations.md](expectations.md), выбор рантайма: [runtime-choice.md](runtime-choice.md).
+
+## Бюджет A: Минимальный (CPU-only)
+
+**Для кого:** старт, RAG, базовые задачи, без требований к высокой скорости.
+
+- CPU: 8–12 vCPU (современные ядра)
+- RAM: 32 GB (минимум 16 GB, но хуже)
+- Disk: NVMe 512 GB
+- GPU: нет
+
+Ожидания:
+
+- модели 3B–7B с умеренной скоростью
+- ориентир decode: примерно `1–6 ток/с` (зависит от модели и квантизации)
+
+Рекомендованные модели:
+
+- `qwen2.5:3b`
+- `qwen2.5-coder:7b` (если хватает RAM/терпения)
+
+## Бюджет B: Комфортный (1× GPU среднего класса)
+
+**Для кого:** ежедневная работа 1–3 пользователей, код + RAG в комфортном режиме.
+
+- CPU: 8–16 vCPU
+- RAM: 32–64 GB
+- GPU: 1× NVIDIA 12–16 GB VRAM (например, RTX 3060 12GB / 4070 Ti Super 16GB)
+- Disk: NVMe 1 TB
+
+Ожидания:
+
+- стабильная работа 7B/8B, лучше latency и throughput
+- ориентир decode: примерно `10–35 ток/с`
+
+Рекомендованные модели:
+
+- `qwen2.5-coder:7b`
+- `llama3.1:8b`
+- `deepseek-r1:8b`
+
+## Бюджет C: Производительный (1–2 GPU высокого класса)
+
+**Для кого:** команда, многозадачность, более тяжёлые модели и высокая отзывчивость.
+
+- CPU: 16+ vCPU
+- RAM: 64–128 GB
+- GPU:
+  - вариант 1: 1× NVIDIA 24 GB VRAM (RTX 4090 / L40-class по бюджету)
+  - вариант 2: 2× GPU по 16–24 GB для масштабирования
+- Disk: NVMe 2 TB
+
+Ожидания:
+
+- уверенная работа 14B+ (квантизованные), параллельные запросы
+- ориентир decode: `25–80+ ток/с` в зависимости от модели/батча
+
+Рекомендованные модели:
+
+- 14B-класс инструкт/кодовые варианты
+- mix моделей: одна «быстрая дешёвая», одна «качественная тяжёлая»
+
+## Что критично кроме железа
+
+- стабильная версия драйверов CUDA (если NVIDIA);
+- быстрый NVMe (модели занимают много места);
+- мониторинг температуры/памяти/IO;
+- резерв свободного диска под новые веса.
diff --git a/docs/install-openclaude-cli.md b/docs/install-openclaude-cli.md
new file mode 100644
index 0000000..5437ec3
--- /dev/null
+++ b/docs/install-openclaude-cli.md
@@ -0,0 +1,148 @@
+# Установка OpenClaude: предусловия, Ollama, профили провайдеров
+
+Пошагово: Node/npm → CLI → (для локальных моделей) Ollama → переменные окружения для выбранного провайдера.
+
+## 0. Предусловия
+
+Нужны **Node.js 18+** и **npm** (входят в официальную установку Node).
+
+Проверка:
+
+```bash
+node -v
+npm -v
+```
+
+Дальше:
+
+1. установить **OpenClaude CLI** (ниже);
+2. для **локальных** моделей через Ollama — установить и запустить **Ollama**, затем локальный профиль;
+3. для облака (OpenAI / DeepSeek) достаточно ключей API — см. профили ниже.
+
+Если при запуске OpenClaude появится предупреждение вроде `ripgrep not found`, установите **ripgrep** (`rg`) и проверьте `rg --version` в том же терминале.
+
+## 1. Установка OpenClaude
+
+```bash
+npm install -g @gitlawb/openclaude
+openclaude --version
+```
+
+## 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 (пример ниже совпадает с локальным профилем):
+
+```bash
+ollama pull qwen2.5-coder:7b
+```
+
+Быстрая проверка генерации:
+
+```bash
+ollama run qwen2.5-coder:7b
+```
+
+Подробнее про выбор и обслуживание моделей: [local-llm-ollama.md](local-llm-ollama.md).
+
+## 3. Локальный Ollama-профиль (бесплатно)
+
+macOS / Linux:
+
+```bash
+export CLAUDE_CODE_USE_OPENAI=1
+export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
+export OPENAI_MODEL=qwen2.5-coder:7b
+openclaude
+```
+
+Windows PowerShell:
+
+```powershell
+$env:CLAUDE_CODE_USE_OPENAI="1"
+$env:OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
+$env:OPENAI_MODEL="qwen2.5-coder:7b"
+
+openclaude
+```
+
+Альтернатива без ручных переменных (если установлен Ollama и доступна команда `ollama launch`):
+
+```bash
+ollama launch openclaude --model qwen2.5-coder:7b
+```
+
+## 4. OpenAI-профиль
+
+macOS / Linux:
+
+```bash
+export CLAUDE_CODE_USE_OPENAI=1
+export OPENAI_API_KEY=sk-...
+export OPENAI_MODEL=gpt-4o
+openclaude
+```
+
+Windows PowerShell:
+
+```powershell
+$env:CLAUDE_CODE_USE_OPENAI="1"
+$env:OPENAI_API_KEY="sk-..."
+$env:OPENAI_MODEL="gpt-4o"
+
+openclaude
+```
+
+## 5. DeepSeek-профиль
+
+macOS / Linux:
+
+```bash
+export CLAUDE_CODE_USE_OPENAI=1
+export OPENAI_BASE_URL=https://api.deepseek.com/v1
+export OPENAI_API_KEY=sk-...
+export OPENAI_MODEL=deepseek-chat
+openclaude
+```
+
+Windows PowerShell:
+
+```powershell
+$env:CLAUDE_CODE_USE_OPENAI="1"
+$env:OPENAI_BASE_URL="https://api.deepseek.com/v1"
+$env:OPENAI_API_KEY="sk-..."
+$env:OPENAI_MODEL="deepseek-chat"
+
+openclaude
+```
+
+Дальше: закрепить профили на диске и автоподстановку в проектах — [configure-profiles-direnv.md](configure-profiles-direnv.md).
diff --git a/docs/linux-server-fixes.md b/docs/linux-server-fixes.md
new file mode 100644
index 0000000..b39a0d4
--- /dev/null
+++ b/docs/linux-server-fixes.md
@@ -0,0 +1,18 @@
+# Мелкие фиксы на Linux-сервере (BOM, apt-зеркала)
+
+## Скрипт падает с `#!/usr/bin/env: No such file or directory`
+
+Причина: **BOM** (маркер UTF-8) в начале файла.
+
+Фикс:
+
+```bash
+sed -i '1s/^\xEF\xBB\xBF//' script.sh
+chmod +x script.sh
+```
+
+## После смены зеркала apt всё ещё ходит в `ru.archive.ubuntu.com`
+
+Обычно источники лежат в **`*.sources`** (формат deb822), а не только в `sources.list`.
+
+Нужно править **`URIs:`** в соответствующих deb822-блоках под выбранное зеркало.
diff --git a/docs/local-llm-ollama.md b/docs/local-llm-ollama.md
new file mode 100644
index 0000000..147662b
--- /dev/null
+++ b/docs/local-llm-ollama.md
@@ -0,0 +1,65 @@
+# Локальные модели через Ollama: где брать, что ставить, обслуживание
+
+## Где брать модели
+
+Проще всего через каталог Ollama: [https://ollama.com/library](https://ollama.com/library)
+
+Расширенные таблицы и заметки по семействам: [model-catalog.md](model-catalog.md)
+
+## Рекомендуемый старт
+
+- `qwen2.5-coder:7b` — хороший баланс для кода
+- `qwen2.5:3b` — если сервер слабый
+- `llama3.1:8b` — универсальный сильный baseline
+- `deepseek-r1:8b` — reasoning-ориентированный вариант
+
+## Базовые команды
+
+```bash
+ollama pull qwen2.5-coder:7b
+ollama pull qwen2.5:3b
+ollama pull llama3.1:8b
+ollama pull deepseek-r1:8b
+ollama list
+```
+
+Установка самого Ollama по ОС — в [install-openclaude-cli.md](install-openclaude-cli.md#2-установка-и-запуск-ollama-для-локального-профиля).
+
+## «Модель дообучается сама» от работы в чате?
+
+Короткий ответ: **нет**.
+
+- Обычная работа в чате не дообучает модель автоматически.
+- Качество обычно улучшают так:
+  - обновляют модель/тег (`ollama pull ...`);
+  - улучшают системные промпты;
+  - подключают RAG (документы + retrieval).
+- Полноценный finetune/LoRA — отдельный ML-процесс.
+
+## Обновление и обслуживание
+
+Смотреть установленные:
+
+```bash
+ollama list
+```
+
+Обновлять нужные:
+
+```bash
+ollama pull qwen2.5-coder:7b
+```
+
+Удалять старые:
+
+```bash
+ollama rm <model:tag>
+```
+
+Проверять занятое место (Linux):
+
+```bash
+sudo du -h --max-depth=2 /usr/share/ollama /var/lib/ollama 2>/dev/null | sort -h | tail -n 30
+```
+
+Дальше: как подключать документы и MCP — [rag-mcp-stack.md](rag-mcp-stack.md).
diff --git a/docs/model-catalog.md b/docs/model-catalog.md
index a8553b7..fb01c45 100644
--- a/docs/model-catalog.md
+++ b/docs/model-catalog.md
@@ -2,6 +2,8 @@
 
 Практический каталог моделей для code-задач в локальном и гибридном сценарии.
 
+Базовые команды `ollama pull` и обслуживание: [local-llm-ollama.md](local-llm-ollama.md).
+
 > Важно: "лучшая модель" зависит от языка проекта, длины контекста, формата задач и вашего железа.
 
 ## 1) Рекомендуемые семейства
diff --git a/docs/quickstart-30min.md b/docs/quickstart-30min.md
index db29cd6..002b880 100644
--- a/docs/quickstart-30min.md
+++ b/docs/quickstart-30min.md
@@ -2,7 +2,7 @@
 
 Короткий маршрут "с нуля до рабочего стенда" на Ubuntu.
 
-Если вы на **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-сервере с тем же репозиторием.
+Если вы на **Windows**, установите Ollama и Node.js локально, затем для запуска OpenClaude на локальной модели следуйте `docs/install-openclaude-cli.md` (блоки **PowerShell** и порядок шагов там же). Полный стек ниже (Docker, bash-скрипты, пути `~/...`) удобнее повторять в **WSL2** или на Linux-сервере с тем же репозиторием.
 
 ## 0) Что получится
 
@@ -21,7 +21,7 @@ sudo systemctl start docker
 
 ## 2) Установка Ollama
 
-Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `README.md`, раздел **4.2**.
+Ниже — типичный путь для Ubuntu/сервера. Для **macOS**, **Windows** и **winget** см. `docs/install-openclaude-cli.md` (раздел про установку Ollama).
 
 ```bash
 curl -fsSL https://ollama.com/install.sh | sh
diff --git a/docs/rag-mcp-stack.md b/docs/rag-mcp-stack.md
new file mode 100644
index 0000000..4362fde
--- /dev/null
+++ b/docs/rag-mcp-stack.md
@@ -0,0 +1,62 @@
+# RAG, минимальный стек и отладка MCP
+
+## Что такое 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: каталог [rag-mcp-starter/](rag-mcp-starter/).
+
+Минимальная схема:
+
+1. Сложить документы (`md`/`txt`/`pdf`).
+2. Разбить на чанки (`chunk_size ~1000`, overlap `~120`).
+3. Сделать embeddings.
+4. Записать в Qdrant.
+5. Поднять MCP-инструмент `search_docs`.
+6. Вызывать его из OpenClaude.
+
+Быстрый сценарий «с нуля за 30 минут» на Ubuntu: [quickstart-30min.md](quickstart-30min.md).
+
+Интеграция с Git и индексация репозитория как базы знаний: [openclaude-with-repositories.md](openclaude-with-repositories.md).
+
+## Чек-лист, если MCP «не виден»
+
+1. MCP-сервер стартует вручную из каталога starter:
+
+```bash
+cd docs/rag-mcp-starter
+python mcp_server.py
+```
+
+2. Зависимости установлены:
+
+```bash
+python -c "import fastmcp, qdrant_client, requests; print('ok')"
+```
+
+3. Пути в `~/.claude/settings.json` корректны (`command`, `args`).
+4. Qdrant доступен: `curl http://127.0.0.1:6333/collections`
+5. Ollama доступен: `curl http://127.0.0.1:11434/api/tags`
diff --git a/docs/rag-mcp-starter/README.md b/docs/rag-mcp-starter/README.md
index 3dd3031..686fc93 100644
--- a/docs/rag-mcp-starter/README.md
+++ b/docs/rag-mcp-starter/README.md
@@ -149,3 +149,7 @@ chmod +x upgrade.sh
 - `RAG_DOCS_DIR` (default `./docs`)
 - `CHUNK_SIZE` (default `1000`)
 - `CHUNK_OVERLAP` (default `120`)
+
+## См. также
+
+- Обзор RAG и связка с OpenClaude: [../rag-mcp-stack.md](../rag-mcp-stack.md)
diff --git a/docs/repository-and-cli.md b/docs/repository-and-cli.md
new file mode 100644
index 0000000..9018be3
--- /dev/null
+++ b/docs/repository-and-cli.md
@@ -0,0 +1,32 @@
+# Этот репозиторий и установка OpenClaude CLI
+
+## Что лежит в этом репозитории
+
+Проект **openclaude-LLM-local** — это **справочник по эксплуатации**: тексты в `docs/`, пример минимального RAG в `docs/rag-mcp-starter/`, вспомогательные скрипты в `scripts/`.
+
+Это **не** исходный код приложения OpenClaude и **не** форк движка моделей.
+
+## Как получить эти материалы у себя
+
+Клонирование (подставьте свой fork или upstream URL из страницы репозитория на GitHub):
+
+```bash
+git clone https://github.com/PTah/openclaude-LLM-local.git
+cd openclaude-LLM-local
+```
+
+Дальше читайте навигацию в [README.md](README.md) (каталог `docs/`) или краткий план в [START-HERE.md](START-HERE.md).
+
+## Откуда ставится сам OpenClaude
+
+CLI распространяется как **npm-пакет** upstream-проекта:
+
+```bash
+npm install -g @gitlawb/openclaude
+```
+
+Исходники и релизы CLI: репозиторий [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude) на GitHub.
+
+Итого: **документацию и примеры** вы тянете из этого handbook-репозитория; **бинарник/CLI OpenClaude** ставите через `npm` из `@gitlawb/openclaude`.
+
+Следующий шаг по порядку «от простого к сложному»: [install-openclaude-cli.md](install-openclaude-cli.md).
diff --git a/docs/roadmap-next-steps.md b/docs/roadmap-next-steps.md
new file mode 100644
index 0000000..8476eed
--- /dev/null
+++ b/docs/roadmap-next-steps.md
@@ -0,0 +1,12 @@
+# Что делать дальше (дорожная карта)
+
+Если уже есть базовый локальный контур OpenClaude + выбранная модель, логичный следующий порядок:
+
+1. Зафиксировать текущие характеристики сервера (CPU/RAM/GPU/NVMe).
+2. Выбрать стартовый профиль (`local` / OpenAI / DeepSeek) и закрепить его в [configure-profiles-direnv.md](configure-profiles-direnv.md).
+3. Поднять `openclaude` и сделать короткий smoke test на типовой задаче.
+4. Запустить минимальный RAG с Qdrant по [rag-mcp-stack.md](rag-mcp-stack.md) и каталогу [rag-mcp-starter/](rag-mcp-starter/).
+5. Добавить MCP-инструменты под ваши рабочие данные.
+6. Оптимизировать скорость и стоимость (routing между моделями, гибрид с облаком — см. [expectations.md](expectations.md)).
+
+Фазированный план по дням: [START-HERE.md](START-HERE.md).