diff --git a/docs/bootstrap.md b/docs/bootstrap.md
new file mode 100644
index 0000000..f9726c7
--- /dev/null
+++ b/docs/bootstrap.md
@@ -0,0 +1,135 @@
+# bootstrap
+
+как поднять систему с нуля, если nix-config уже есть, но машина новая/сброшена.
+
+## что есть в `home/`
+
+- `pass` с `pass-otp` (зашифрованный password store)
+- `gpg-agent` с кешированием на 1 час
+- `git` с `delta` (красивый diff)
+- `zsh` с `pure` prompt, autosuggestions, syntax highlighting
+- `kitty` (через import в poppy)
+- `duti` для default apps
+
+## step 1: установить nix
+
+```bash
+# Determinate Nix (рекомендуется)
+curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/installer | sh
+```
+
+## step 2: склонировать nix-config
+
+```bash
+git clone https://git.iscg.dev/mikl/nix-config.git ~/repos/nix-config
+cd ~/repos/nix-config
+```
+
+## step 3: импортировать GPG ключ
+
+**критичный шаг.** без GPG ключа `pass` не работает.
+
+```bash
+# если есть приватная репа с зашифрованным gpg ключом
+git clone https://git.iscg.dev/mikl/gpg-secrets.git /tmp/gpg-setup
+gpg --import /tmp/gpg-setup/gpg-private.asc
+rm -rf /tmp/gpg-setup
+
+# проверить
+gpg --list-secret-keys mikl@iscg.dev
+```
+
+если репы нет, генерируем новый:
+
+```bash
+gpg --full-gen-key
+# email: mikl@iscg.dev
+# имя: mikl
+# passphrase: <strong>
+```
+
+## step 4: первый rebuild
+
+```bash
+# darwin (mac)
+sudo darwin-rebuild switch --flake .#poppy
+
+# nixos (linux)
+sudo nixos-rebuild switch --flake .#muscari
+```
+
+первый rebuild может долгим — скачает все пакеты.
+
+## step 5: настроить pass (ручной шаг)
+
+```bash
+# если есть существующий password store
+git clone https://git.iscg.dev/mikl/password-store.git ~/.password-store
+cd ~/.password-store && git remote remove origin && git remote add origin https://git.iscg.dev/mikl/password-store.git
+
+# если создаёшь с нуля
+pass init <gpg-key-id>   # id от gpg --list-secret-keys
+pass git init
+pass git remote add origin https://git.iscg.dev/mikl/password-store.git
+```
+
+после этого работают алиасы:
+```bash
+pass-sync    # = pass git push
+pass-pull    # = pass git pull
+pass-status  # = pass git status
+```
+
+## step 6: настроить default apps
+
+`duti` уже настроен через nix. но **для системных UTI (url, shell-script, pdf, txt)** на macOS Sonoma+ нужно вручную:
+
+1. правый клик на файл → **Get Info**
+2. **Open with:** → выбрать нужное
+3. **Change All...** → подтвердить
+
+для каких файлов:
+- `.url`, `.xhtml` → Chrome
+- `.sh` → kitty
+- `.pdf` → Skim
+- `.txt` → VSCodium
+
+## step 7: настроить ~/.gitconfig (вручную)
+
+nix генерирует `~/.config/git/config`, но если есть `~/.gitconfig` — он **перебивает**.
+
+```bash
+# если хочешь глобальные настройки
+nano ~/.gitconfig
+
+# пример:
+[filter "lfs"]
+    clean = git-lfs clean -- %f
+    smudge = git-lfs smudge -- %f
+[credential]
+    helper = osxkeychain
+```
+
+или удали `~/.gitconfig` чтобы nix-only.
+
+## post-bootstrap проверка
+
+```bash
+# все пакеты установлены?
+which pass gpg zsh delta duti
+
+# kitty на poppy
+ls /Users/michaotic/Applications/Home\ Manager\ Apps/ | grep kitty
+
+# git config
+git config --get user.name   # mikl
+git config --get user.email  # mikl@iscg.dev
+```
+
+## что не восстанавливается автоматически
+
+- **Obsidian vault** (если заметки локально) — нужна синхронизация через Obsidian Sync или git
+- **SSH ключи** — нужны в `~/.ssh/`, копируй со старой машины или генерируй новые
+- **iCloud** — не в Nix
+- **App Store apps** (Pages, Keynote, Numbers) — `mas` CLI может восстановить
+- **.DS_Store preferences** — настраиваются заново