seedPass/docs/migrations.md

# Index Migrations

SeedPass stores its password index in an encrypted JSON file. Each index contains
a `schema_version` field so the application knows how to upgrade older files.

## How migrations work

When the vault loads the index, `Vault.load_index()` checks the version and
applies migrations defined in `password_manager/migrations.py`. The
`apply_migrations()` function iterates through registered migrations until the
file reaches `LATEST_VERSION`.

If an old file lacks `schema_version`, it is treated as version 0 and upgraded
to the latest format. Attempting to load an index from a future version will
raise an error.

## Upgrading an index

1. The JSON is decrypted and parsed.
2. `apply_migrations()` applies any necessary steps, such as injecting the
   `schema_version` field on first upgrade.
3. After migration, the updated index is saved back to disk.

This process happens automatically; users only need to open their vault to
upgrade older indices.