# Окружение агентов `.vibe` — и как держать его свежим

← [Дерево документации](../README.md)

## Что это

`.vibe/` в корне проекта — окружение агентов: правила, скиллы, промпты, примеры конфигов. VibeIDE засевает его при открытии проекта из набора, встроенного в релиз (источник — `.vibe-defaults/` в репозитории).

Файлы принадлежат **вам**: правьте под проект. IDE никогда не перезаписывает существующий файл сама.

## Почему копия устаревает

Окружение развивается: в каждом релизе появляются новые скиллы, а старые правятся. При открытии проекта VibeIDE **дописывает недостающие** файлы — их вы получаете автоматически.

Чего засев сделать не может — **обновить файл, который у вас уже есть**. Иначе он затирал бы ваши правки. Поэтому файл, изменённый в новом релизе, остаётся у вас в старой редакции, пока вы сами не решите иначе.

## Две команды

Обе — в меню «мозга» (иконка VibeIDE в заголовке окна) и в палитре команд.

- **«Показать новое в окружении из релиза»** — только отчёт, ничего не меняет.
- **«Обновить окружение из релиза»** — тот же отчёт плюс действия.

## Что показывает отчёт

Состояние считается по трём величинам: версия в релизе, ваш файл и **точка последней сверки** (`.vibe/.defaults.lock.json`). Благодаря ей IDE отличает «релиз обновился» от «вы правили» — без этого любой ваш файл выглядел бы как «расхождение».

| Категория | Что значит | Что делать |
|---|---|---|
| **Новое в релизе** | файла у вас нет | добавится само при открытии |
| **Релиз обновил** | файл изменился в релизе, вы его не трогали | «Обновить безопасно» — терять нечего |
| **Разошлись обе стороны** | и вы правили, и релиз изменил | «Показать различия», решить руками |
| **Не сверялось** | отличается, но сверки не было (окружение старше учёта) | «Показать различия» → решить |
| **Ваши файлы** | отличаются по вашему решению, релиз их не менял | ничего; в напоминаниях не участвуют |

## Действия

- **«Обновить безопасно (N)»** — добавляет новое и обновляет то, чего вы не касались. Потерять правки невозможно. В сомнениях — это правильный выбор.
- **«Показать различия»** — открывает дифф: слева версия из релиза (только для чтения), справа ваш файл. Правьте свой прямо в диффе — это и есть слияние.
- **«Оставить своё (K)»** — фиксирует: «мой файл такой, каким я хочу». Файл переходит в «Ваши файлы» и перестаёт напоминать о себе — до следующего релиза, который его изменит.
- **«Заменить всё»** — сбрасывает окружение к версии релиза. **Ваши правки пропадут безвозвратно** (спросим подтверждение). Единственный способ починить файл, который вы правили, а релиз с тех пор ушёл далеко вперёд.

## Напоминание

Если релиз сдвинул ваши файлы, при открытии проекта появится уведомление с кнопками «Показать» / «Обновить» / «Больше не напоминать».

Оно срабатывает **только когда сдвинулся релиз**. Файлы, которые вы правили сами, поводом не считаются: настроенный файл отличается от релиза всегда, и напоминать об этом каждый запуск — значит превратить уведомление в шум. Отключается настройкой `vibeide.environment.notifyOnRelease`.

## `.vibe/.defaults.lock.json`

Хранит на каждый файл хеш версии релиза и хеш вашей на момент сверки. Пишется сам — руками не нужен.

**Коммитьте его** вместе с `.vibe/`: это решение проекта, а не машинная мелочь. Если он не в репозитории, каждый в команде будет отдельно разбираться с одной и той же вашей общей кастомизацией. В `.vibe/.gitignore` он намеренно не добавлен.