main/PI-BACKUP-README.md

# Бэкап среды Pi Coding Agent

Файлы рядом:

- `pi-env-backup.sh` — скрипт создания, проверки и восстановления бэкапа;
- `PI-BACKUP-README.md` — эта инструкция.

Скрипт переносит именно среду Pi, а не проекты.

## Что сохраняется

- `~/.pi/agent/settings.json` — глобальные настройки Pi;
- `~/.pi/agent/auth.json` — авторизация и API-ключи;
- `~/.pi/agent/mcp.json` и `~/.pi/agent/mcp-oauth/` — MCP;
- `~/.pi/agent/models.json`, `models.yml` — настройки моделей;
- `~/.pi/agent/extensions/`, `skills/`, `npm/`, `git/` — плагины и Pi packages;
- `~/.pi/agent/AGENTS.md`, `keybindings.json`, `trust.json`;
- `~/.pi/agent/sessions/` — история сессий (**по умолчанию не сохраняется**);
- `~/.pi/agent/pi-hermes-memory/` и `projects-memory/` — память;
- `~/.pi/context-mode/` — индексы и локальные данные context-mode (**по умолчанию не сохраняются**);
- `~/.pi/agent/ayu/checkpoints/` — checkpoints (**по умолчанию не сохраняются**);
- `~/.agents/` — дополнительные пользовательские skills;
- `~/.pi/local-docs/`, если каталог существует.

Архив также содержит манифест версий установленных программ и копию самого скрипта для восстановления.

> **Внимание:** архив содержит секреты из `auth.json`, MCP OAuth и других конфигов. Не выкладывай его в публичное хранилище.

---

## 1. Создать полный бэкап

Закрой все запущенные Pi:

```bash
pkill -f pi-coding-agent || true
```

Создай каталог для архивов и запусти:

```bash
mkdir -p ~/pi-backups
cd /home/smog/main
./pi-env-backup.sh backup ~/pi-backups
```

Или сразу на внешний диск:

```bash
./pi-env-backup.sh backup /media/smog/SSD
```

На выходе будут два файла:

```text
pi-backup-YYYYMMDD-HHMMSS.tar.zst
pi-backup-YYYYMMDD-HHMMSS.tar.zst.sha256
```

По умолчанию архив НЕ включает `ayu/checkpoints`, историю Pi-сессий и `context-mode`: это кэш/история, не нужные для работы плагинов. Поэтому архив обычно будет порядка **0.8–1 ГБ до сжатия** и ориентировочно **0.4–0.8 ГБ после zstd**. Точный размер скрипт покажет в конце.

---

## 2. Проверить архив

Посмотреть содержимое:

```bash
./pi-env-backup.sh list ~/pi-backups/pi-backup-*.tar.zst
```

Проверить контрольную сумму:

```bash
sha256sum -c ~/pi-backups/pi-backup-*.tar.zst.sha256
```

---

## 3. Дополнительные варианты бэкапа

По умолчанию уже создаётся облегчённый бэкап: плагины, настройки, auth, MCP, memory и skills сохраняются, а checkpoints/сессии/context-mode — нет.

Включить историю старых Pi-сессий:

```bash
PI_BACKUP_INCLUDE_SESSIONS=1 \
  ./pi-env-backup.sh backup ~/pi-backups
```

Включить context-mode индексы:

```bash
PI_BACKUP_INCLUDE_CONTEXT=1 \
  ./pi-env-backup.sh backup ~/pi-backups
```

Включить старые ayu checkpoints (обычно не нужно):

```bash
PI_BACKUP_INCLUDE_AYU=1 \
  ./pi-env-backup.sh backup ~/pi-backups
```

Включить всё сразу:

```bash
PI_BACKUP_INCLUDE_SESSIONS=1 \
PI_BACKUP_INCLUDE_CONTEXT=1 \
PI_BACKUP_INCLUDE_AYU=1 \
  ./pi-env-backup.sh backup ~/pi-backups
```

Настройки, auth, MCP, memory, плагины и skills сохраняются во всех вариантах.

---

## 4. Восстановить на ноутбуке в WSL

На ноутбуке установи базовые инструменты:

```bash
sudo apt update
sudo apt install -y zstd nodejs npm
```

Передай на ноутбук архив и `.sha256` рядом с ним. Проверь архив:

```bash
sha256sum -c pi-backup-YYYYMMDD-HHMMSS.tar.zst.sha256
```

Если бэкап был скачан из этого Git-репозитория, сначала забери LFS-файлы и собери архив из частей:

```bash
git lfs pull
chmod +x assemble-pi-backup.sh
./assemble-pi-backup.sh pi-backup-YYYYMMDD-HHMMSS.tar.zst
```

Скрипт соберёт `*.part-*` в исходный `.tar.zst` и сразу проверит контрольную сумму.

Извлеки встроенную копию restore-скрипта:

```bash
zstd -dc pi-backup-YYYYMMDD-HHMMSS.tar.zst \
  | tar -xOf - meta/pi-env-backup.sh > pi-env-restore.sh

chmod +x pi-env-restore.sh
```

Запусти восстановление:

```bash
./pi-env-restore.sh restore pi-backup-YYYYMMDD-HHMMSS.tar.zst
```

Скрипт распакует Pi-среду в домашний каталог текущего пользователя WSL. Если `~/.pi/agent` уже существует, он сначала переименует его в каталог вида:

```text
~/.pi/agent.before-restore-YYYYMMDD-HHMMSS
```

Если Pi ещё не установлен, скрипт установит его так:

```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

---

## 5. Проверить восстановление

```bash
pi --version
pi list
```

Запусти Pi в одном из своих проектов:

```bash
cd ~/main/имя-проекта
pi
```

Проверь:

```text
/mcp
/login       # только если OAuth/API-ключ не восстановился
```

Если какие-то внешние программы нужны плагинам, установи их отдельно: `bun`, `pnpm`, `uv`, `gh`, `jj`, `docker` и т.п. Их бинарники не копируются архивом — архив переносит состояние Pi и список обнаруженных инструментов в `meta/MANIFEST.txt`.

---

## 6. Важные замечания

1. Перед созданием архива закрывай Pi, чтобы не копировать активные session/SQLite-файлы.
2. Не используй `PI_BACKUP_ALLOW_RUNNING=1`, если нет особой причины.
3. Архив — это переносимая копия пользовательской Pi-среды, но не копия всей ОС.
4. Проекты не входят в этот архив: они уже есть в WSL отдельно.
5. Project-local файлы вроде `project/.pi/`, `project/.agents/`, `AGENTS.md` и `CLAUDE.md` не входят в глобальный архив, если находятся внутри проектов. Их нужно хранить вместе с проектами или отдельно скопировать.
6. Некоторые OAuth-провайдеры могут потребовать повторный `/login` на новом ноутбуке.