Document export/import modes and migrations

README.md

@@ -101,6 +101,23 @@ pip install --upgrade pip
 pip install -r src/requirements.txt
 ```
 
+## Quick Start
+
+After installing dependencies and activating your virtual environment, launch
+SeedPass and create a backup:
+
+```bash
+# Start the application
+python src/main.py
+
+# Export your index using seed-only encryption
+seedpass export --mode seed-only --file "~/seedpass_backup.json"
+
+# Later you can restore it
+seedpass import --mode seed-only --file "~/seedpass_backup.json"
+```
+
+
 ## Usage
 
 After successfully installing the dependencies, you can run SeedPass using the following command:

docs/advanced_cli.md

@@ -217,7 +217,25 @@ seedpass export --file "backup_passwords.json"
 ```
 
 **Options:**
-- `--file` (`-F`): The destination file path for the exported data.
+- `--file` (`-F`): The destination file path for the exported data. If omitted, the export
+  is saved to the current profile's `exports` directory under `~/.seedpass/<profile>/exports/`.
+- `--mode` (`-M`): Choose the encryption mode for the exported file. Valid values are:
+  `seed-only`, `seed+pw`, `pw-only`, and `plaintext`.
+
+**Examples:**
+```bash
+# Standard encrypted export
+seedpass export --mode seed-only --file "backup.json"
+# Combine seed and master password for the export key
+seedpass export --mode seed+pw --file "backup.json"
+# Derive the key solely from your password
+seedpass export --mode pw-only --file "backup.json"
+# Plaintext JSON export (not recommended)
+seedpass export --mode plaintext --file "backup.json"
+```
+
+**Warning:** The `plaintext` mode writes an unencrypted index to disk. Only use it
+for debugging and delete the file immediately after use.
 
 ---
 
@@ -237,6 +255,15 @@ seedpass import --file "backup_passwords.json"
 
 **Options:**
 - `--file` (`-F`): The source file path containing the password entries to import.
+- `--mode` (`-M`): Indicates the encryption mode used when the file was exported. Accepted values are `seed-only`, `seed+pw`, `pw-only`, and `plaintext`.
+
+**Examples:**
+```bash
+# Import a standard encrypted backup
+seedpass import --mode seed-only --file "backup.json"
+# Import a backup that also used the master password
+seedpass import --mode seed+pw --file "backup.json"
+```
 
 ---
 

docs/migrations.md

@@ -0,0 +1,25 @@
+# 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.