diff --git a/README.md b/README.md
index da27e58..1a25bdd 100644
--- a/README.md
+++ b/README.md
@@ -97,16 +97,23 @@ openspec/
 ## Подключение
 
 Плагин подключается **на уровне проекта**, чтобы был активен у всех, кто
-открывает репозиторий:
+открывает репозиторий. Из терминала, в каталоге проекта:
 
-```
-/plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git --scope project
-/plugin install av-dev-pm@av-dev-skills --scope project
-/plugin install av-dev-pipeline@av-dev-skills --scope project
-/plugin install av-dev-git@av-dev-skills --scope project
+```bash
+cd /path/to/project
+
+# маркетплейс: один раз на проект. --scope project кладёт его
+# в extraKnownMarketplaces этого репозитория (см. ниже), без флага — в user
+claude plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git --scope project
+
+# плагины: scope обязателен, умолчание у команды — user, а нам нужен project
+claude plugin install av-dev-pm@av-dev-skills --scope project
+claude plugin install av-dev-pipeline@av-dev-skills --scope project
+claude plugin install av-dev-git@av-dev-skills --scope project
 ```
 
-…или те же команды из терминала через `claude plugin …`. Обе формы дописывают в
+Те же команды изнутри Claude Code — со слешем: `/plugin marketplace add …`,
+`/plugin install … --scope project`. Обе формы дописывают в
 `.claude/settings.json` проекта то, что можно внести и руками:
 
 ```json
@@ -124,17 +131,61 @@ openspec/
 }
 ```
 
-**Маркетплейс — git-клон удалённого репозитория, и он обновляется явно:**
-`claude plugin marketplace update av-dev-skills`. Локальные коммиты, не
-отправленные на origin, до него не доедут — это уже однажды выглядело как
-«плагин не работает».
-
 **При установке в проект, где лежали проектные копии** скиллов и агентов
 (`.claude/skills/` — голые `task-pipeline`, `review-pipeline`, `task-batch`
 и с префиксом проекта `<проект>-task-pipeline`,
 `.claude/agents/<проект>-review-*.md`) — снеси их. Две копии одного скилла
 расходятся, и побеждает та, что короче названа.
 
+## Обновление
+
+**Обновление — два шага, и первого мало.** `marketplace update` тянет git-клон
+маркетплейса, но снимки плагинов лежат отдельно, в
+`~/.claude/plugins/cache/av-dev-skills/<плагин>/<версия>/`, и обновляются только
+командой `plugin update`. Один шаг без второго выглядит как «обновил, а ничего не
+изменилось» — так и было в первый раз.
+
+```bash
+# 0. отправить свои коммиты: до клона доезжает только то, что на origin
+git -C /path/to/dev-skills push origin master
+
+# 1. клон маркетплейса
+claude plugin marketplace update av-dev-skills
+
+# 2. снимки плагинов — из каталога проекта, где они установлены
+cd /path/to/project
+claude plugin update av-dev-pm@av-dev-skills --scope project
+claude plugin update av-dev-pipeline@av-dev-skills --scope project
+claude plugin update av-dev-git@av-dev-skills --scope project
+```
+
+**`cd` в проект обязателен, и это не педантизм.** Команда правит запись реестра, а
+записей столько, во скольких проектах плагин установлен; за вызов двигается
+**одна**. Запущенная не из проекта, она обновит какую-то из них — наблюдалось:
+`av-dev-git` стоял в шести проектах, один вызов поднял версию ровно в одном, и не
+в том, из которого звали. Проекты обновляются поштучно.
+
+Что стоит и какой версии — одной командой:
+
+```bash
+python3 - <<'EOF'
+import json, pathlib
+d = json.loads(pathlib.Path.home().joinpath(".claude/plugins/installed_plugins.json").read_text())
+for name, entries in sorted(d["plugins"].items()):
+    if "av-dev" not in name:
+        continue
+    for e in entries:
+        print(f"{e['version']:14} {name:30} {e.get('projectPath', e.get('scope', ''))}")
+EOF
+```
+
+Версия — первые 12 знаков хеша коммита этого репозитория, так что сверяется
+глазами с `git rev-parse HEAD | cut -c1-12`. Команда идемпотентна: на уже свежем
+плагине скажет `already at the latest version`.
+
+**Изменения применяются после перезапуска Claude Code** — работающая сессия
+держит скиллы в контексте и про новый снимок не знает.
+
 ## Структура репозитория
 
 ```