## Что это
При upgrade с pre-1.0 версий пользовательский data-path был `~/.rox-agent/`. С v1.0 GA — `~/.rox/`. Migration shim запускается one-time при first-launch v1.0:
**State machine** с 4 случаями:
1. **no-legacy** (нет `~/.rox-agent/`) — ничего не делаем
2. **legacy-only** — copy `~/.rox-agent/` → `~/.rox/default/` non-destructive, marker file `~/.rox/.migrated`
3. **both-exist** — UI диалог «Migrate legacy data? (skip/merge/replace)»; merge — preference на newer mtime per-file
4. **already-migrated** (marker exists) — no-op с info-log
Migration сохраняет sessions, credentials (re-encrypted под новый HKDF key), settings, attachments. Никогда не удаляет legacy-path — пользователь чистит manually через settings → «Remove legacy data».
Компоненты: `@rox-one/shared/config/migration`, integration test 4 state-machine cases.
## Зачем
Users с pre-1.0 опытом не должны потерять sessions/credentials при upgrade. Без shim — onboarding с нуля и недовольство. State machine с 4 явными случаями гарантирует idempotent и safe migration.
## Источники вдохновения
- [JerryZLiu/Dayflow](https://github.com/JerryZLiu/Dayflow) — local-first activity timeline с privacy-first migration
- [ThinkInAIXYZ/clawdhome](https://github.com/ThinkInAIXYZ/clawdhome) — multi-instance isolation на Mac
- [JoshuaKGoldberg/TypeStat](https://github.com/JoshuaKGoldberg/TypeStat) — automated TS migration patterns для shim
## 🔗 Linear
- [PZD-433](https://linear.app/kuhjie/issue/PZD-433) — backing ticket