diff --git a/PROJECT_SCRIPTS.md b/PROJECT_SCRIPTS.md
new file mode 100644
index 0000000..c1ebb9d
--- /dev/null
+++ b/PROJECT_SCRIPTS.md
@@ -0,0 +1,189 @@
+# Ansible Home VM Project Scripts
+
+Этот файл описывает playbook-и внутри проекта `ansibleHostsHomeVM`.
+
+## Структура проекта
+
+```text
+ansible.cfg
+inventory.ini
+facts.yml
+add-ssh-key.yml
+bootstrap-new-client.yml
+generate-ssh-config.yml
+```
+
+## ansible.cfg
+
+Локальный конфиг Ansible для этого проекта.
+
+```ini
+[defaults]
+inventory = inventory.ini
+interpreter_python = auto_silent
+host_key_checking = True
+```
+
+Смысл:
+
+- `inventory = inventory.ini` — не нужно каждый раз писать `-i inventory.ini`.
+- `interpreter_python = auto_silent` — Ansible сам ищет Python на VM и не шумит предупреждениями.
+- `host_key_checking = True` — SSH host key checking включён. Это безопаснее: если fingerprint сервера изменился, Ansible не подключится молча.
+
+## inventory.ini
+
+Список управляемых VM.
+
+Пример:
+
+```ini
+[proxmox_vms]
+nginx        ansible_host=192.168.8.170 ansible_user=vrubel
+docker-prod  ansible_host=192.168.8.171 ansible_user=vrubel
+fedoraXfce   ansible_host=192.168.8.172 ansible_user=vrubel
+hermes       ansible_host=192.168.8.173 ansible_user=vrubel
+docker-test  ansible_host=192.168.8.174 ansible_user=vrubel
+cicd         ansible_host=192.168.8.175 ansible_user=vrubel
+monitoring   ansible_host=192.168.8.176 ansible_user=vrubel
+```
+
+Группа `proxmox_vms` используется в командах:
+
+```bash
+ansible proxmox_vms -m ping
+ansible-playbook facts.yml
+```
+
+## facts.yml
+
+Диагностический playbook. Ничего не меняет на серверах.
+
+Он собирает facts и показывает:
+
+- имя хоста;
+- семейство ОС;
+- дистрибутив;
+- версию ОС;
+- пакетный менеджер;
+- путь к Python.
+
+Запуск:
+
+```bash
+ansible-playbook facts.yml
+```
+
+Используется для проверки, какие машины Ubuntu/Debian, какие Fedora/RedHat, и какой пакетный менеджер Ansible видит.
+
+## add-ssh-key.yml
+
+Playbook для добавления публичного SSH-ключа в `authorized_keys` пользователя `vrubel` на всех VM.
+
+По умолчанию берёт ключ текущего пользователя:
+
+```text
+~/.ssh/id_ed25519.pub
+```
+
+Запуск, если доступ по ключу уже есть:
+
+```bash
+ansible-playbook add-ssh-key.yml
+```
+
+Если надо добавить не текущий ключ, а другой публичный ключ из файла:
+
+```bash
+ansible-playbook add-ssh-key.yml -e "key_file=$HOME/Downloads/new-client.pub"
+```
+
+Или, например:
+
+```bash
+ansible-playbook add-ssh-key.yml -e "key_file=$HOME/infra/ansible/keys/laptop.pub"
+```
+
+Важно: файл должен быть именно публичным ключом, то есть `.pub`. Приватный ключ `id_ed25519` в репозиторий не добавлять и никому не передавать.
+
+Этот playbook полезен, когда управляющий комп уже имеет SSH-доступ к VM и нужно добавить новый ключ на все машины.
+
+## bootstrap-new-client.yml
+
+Playbook для первичной настройки нового клиента.
+
+Он делает две вещи:
+
+1. На локальном компьютере добавляет fingerprints VM в `~/.ssh/known_hosts`.
+2. По SSH-паролю подключается к VM и добавляет публичный ключ текущего клиента в `authorized_keys`.
+
+Запуск на новом компьютере:
+
+```bash
+ansible-playbook bootstrap-new-client.yml --ask-pass
+```
+
+Ansible спросит SSH-пароль пользователя `vrubel`.
+
+После успешного выполнения нужно проверить доступ без пароля:
+
+```bash
+ansible proxmox_vms -m ping
+```
+
+Если все VM отвечают `pong`, новый клиент готов.
+
+Этот playbook заменяет ручной `ssh-copy-id` по всем VM.
+
+## generate-ssh-config.yml
+
+Playbook для генерации локального `~/.ssh/config` из `inventory.ini`.
+
+Он добавляет блок вида:
+
+```sshconfig
+# BEGIN ANSIBLE MANAGED HOME VM HOSTS
+Host nginxVM
+  HostName 192.168.8.170
+  User vrubel
+  IdentityFile ~/.ssh/id_ed25519
+
+Host docker-prodVM
+  HostName 192.168.8.171
+  User vrubel
+  IdentityFile ~/.ssh/id_ed25519
+# END ANSIBLE MANAGED HOME VM HOSTS
+```
+
+Сначала безопасная проверка:
+
+```bash
+ansible-playbook generate-ssh-config.yml --check --diff
+```
+
+Если diff выглядит нормально, применить:
+
+```bash
+ansible-playbook generate-ssh-config.yml
+```
+
+После этого можно заходить так:
+
+```bash
+ssh nginxVM
+ssh docker-prodVM
+ssh hermesVM
+```
+
+Playbook управляет только блоком между маркерами `ANSIBLE MANAGED HOME VM HOSTS`. Остальные ручные записи в `~/.ssh/config` не трогает.
+
+## Типовой сценарий для нового компьютера
+
+```bash
+sudo pacman -S ansible sshpass
+git clone git@github.com:vrubelroman/ansibleHostsHomeVM.git
+cd ansibleHostsHomeVM
+ansible-playbook bootstrap-new-client.yml --ask-pass
+ansible proxmox_vms -m ping
+ansible-playbook generate-ssh-config.yml --check --diff
+ansible-playbook generate-ssh-config.yml
+```