diff --git a/README.md b/README.md
index 176a16d..0aae5a8 100644
--- a/README.md
+++ b/README.md
@@ -387,6 +387,7 @@ chmod +x script.sh
 - Точка входа: `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`
diff --git a/docs/github-ssh-setup-and-troubleshooting.md b/docs/github-ssh-setup-and-troubleshooting.md
new file mode 100644
index 0000000..09dd38c
--- /dev/null
+++ b/docs/github-ssh-setup-and-troubleshooting.md
@@ -0,0 +1,176 @@
+# GitHub SSH setup and troubleshooting
+
+Подробная инструкция, чтобы один раз настроить SSH и больше не вводить PAT/пароль при `git pull/push`.
+
+## 1) Проверка текущего состояния
+
+```bash
+git remote -v
+ssh -V
+ls -la ~/.ssh
+```
+
+Если `~/.ssh` пустая - это нормально, создадим ключи.
+
+## 2) Создать ключ ED25519
+
+```bash
+ssh-keygen -t ed25519 -C "you@example.com"
+```
+
+Рекомендуемые ответы:
+
+- путь: `~/.ssh/id_ed25519`
+- passphrase: задать (рекомендуется)
+
+## 3) Запустить ssh-agent и добавить ключ
+
+```bash
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+```
+
+Проверка:
+
+```bash
+ssh-add -l
+```
+
+## 4) Добавить ключ в GitHub
+
+Показать публичный ключ:
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+Скопируйте его в:
+
+- GitHub -> Settings -> SSH and GPG keys -> New SSH key
+
+## 5) Добавить github.com в known_hosts
+
+```bash
+ssh-keyscan github.com >> ~/.ssh/known_hosts
+chmod 700 ~/.ssh
+chmod 600 ~/.ssh/id_ed25519
+chmod 644 ~/.ssh/id_ed25519.pub ~/.ssh/known_hosts
+```
+
+## 6) Перевести репозиторий на SSH remote
+
+```bash
+git remote set-url origin git@github.com:OWNER/REPO.git
+git remote -v
+```
+
+## 7) Тест подключения
+
+```bash
+ssh -T git@github.com
+```
+
+Ожидаемое сообщение: приветствие от GitHub (без shell-доступа).
+
+---
+
+## Частые ошибки и как исправить
+
+### Ошибка: `Permission denied (publickey)`
+
+Проверьте:
+
+```bash
+ssh-add -l
+```
+
+Если "The agent has no identities", добавьте ключ снова:
+
+```bash
+ssh-add ~/.ssh/id_ed25519
+```
+
+Также проверьте, что публичный ключ реально добавлен в GitHub аккаунт.
+
+### Ошибка: `Host key verification failed`
+
+Пересоздайте known_hosts запись:
+
+```bash
+ssh-keygen -R github.com
+ssh-keyscan github.com >> ~/.ssh/known_hosts
+```
+
+### Ошибка: "подхватывается не тот ключ"
+
+Создайте `~/.ssh/config`:
+
+```sshconfig
+Host github.com
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/id_ed25519
+  IdentitiesOnly yes
+```
+
+Права:
+
+```bash
+chmod 600 ~/.ssh/config
+```
+
+### Ошибка при `sudo git ...`
+
+Не запускайте `git pull/push` через `sudo`: root не видит ваш ssh-agent/ключи.
+
+### SSH работает, но всё равно просит PAT
+
+Скорее всего remote остался HTTPS.
+
+Проверьте:
+
+```bash
+git remote -v
+```
+
+Должно быть `git@github.com:...`, а не `https://...`.
+
+---
+
+## Полезный debug-режим
+
+```bash
+ssh -Tv git@github.com
+```
+
+Смотрите:
+
+- какой ключ предлагается (`Offering public key`)
+- принял ли его GitHub (`Server accepts key`)
+
+## Рекомендации для нескольких аккаунтов GitHub
+
+Если личный и рабочий аккаунты:
+
+1. Создайте два ключа (`id_ed25519_personal`, `id_ed25519_work`)
+2. Используйте `~/.ssh/config` с алиасами:
+
+```sshconfig
+Host github-personal
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/id_ed25519_personal
+  IdentitiesOnly yes
+
+Host github-work
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/id_ed25519_work
+  IdentitiesOnly yes
+```
+
+3. Remote для проекта ставьте под нужный алиас:
+
+```bash
+git remote set-url origin git@github-work:ORG/REPO.git
+```
diff --git a/docs/openclaude-with-repositories.md b/docs/openclaude-with-repositories.md
index 573161d..c139b2a 100644
--- a/docs/openclaude-with-repositories.md
+++ b/docs/openclaude-with-repositories.md
@@ -22,6 +22,10 @@
 
 ## 3) Настройка аутентификации без постоянного ввода пароля
 
+Подробный SSH-гайд с типовыми ошибками:
+
+- `docs/github-ssh-setup-and-troubleshooting.md`
+
 ### GitHub
 
 ```bash