# v1 → v2 migration notes

Distilled from upstream `MIGRATION.md` and verified in live sessions. Capture
the renaming + dropping rules — these are the silent-failure hot spots.

## Schema-level changes

| v1.x                                          | v2.0.0                                     |
|-----------------------------------------------|--------------------------------------------|
| `backend.type = "imap"`                       | **removed** — IMAP is now an IMAP table under the account |
| `backend.host` / `backend.port`               | `imap.server = "imaps://host:993"` (URL form) |
| `backend.encryption.type = "tls"`             | encoded in the URL scheme (`imaps://` or `imap://`) |
| `backend.login`                               | `imap.sasl.plain.username` (per-mechanism)  |
| `backend.auth.type = "password"`              | **removed** — choose a SASL mechanism (`plain`, `login`, etc.) |
| `backend.auth.raw = "..."`                    | `imap.sasl.plain.password.raw = "..."`     |
| `backend.auth.cmd = "pass show ..."`          | `imap.sasl.plain.password.command = "pass show ..."` |
| `message.send.backend.*` (SMTP)               | `smtp.*` (moved out of the optional `message.send` nesting) |
| `folder.aliases.X` (plural, dotted)           | `mailbox.alias.X` (**singular**, dotted)     |
| `[accounts.NAME.folder.alias]` (singular table) | **removed** — use `mailbox.alias.X` only   |

## Command-level changes

| v1                                          | v2                                            |
|---------------------------------------------|-----------------------------------------------|
| `himalaya folder list`                      | `himalaya mailbox list`                       |
| `himalaya folder list --folder "Sent"`      | `himalaya mailbox list` (alias-resolved)      |
| `himalaya account configure`               | bare `himalaya` (prompts to stderr, emits config to stdout) |
| `himalaya message send` / `template send`   | `himalaya template send` (MML/stdin)          |
| `himalaya template reply <id>`             | unchanged                                     |
| `himalaya template forward <id>`           | unchanged                                     |

## Silent failures to watch for

These are the most painful — the parser is happy, the command exits 0, but the
intended behavior doesn't happen:

1. **`folder.aliases.X` is silently ignored.** Use `mailbox.alias.X` (singular).
   Old keys exist nowhere in v2. Symptom: `himalaya message send` delivers via
   SMTP successfully, then fails to save to Sent, exits non-zero. Any retry
   produces duplicate emails to recipients.

2. **`backend.auth.raw` is silently ignored.** Move password to
   `imap.sasl.plain.password.raw` (or `password.command`). Symptom: connection
   fails with "no auth mechanism configured" or equivalent.

3. **`message.send.backend.type = "smtp"` is silently ignored.** SMTP section
   is now top-level (`smtp.server`, `smtp.sasl.plain.*`). Symptom: `account
   check` reports "smtp: missing" even though the file looks right.

4. **Tokens stored in `backend.auth.*` don't migrate.** Re-create any
   `oauthbearer` / `xoauth2` setup under `imap.sasl.oauthbearer.*` /
   `imap.sasl.xoauth2.*`.

## What did NOT change

- The `template send` / `template reply` / `template forward` subcommands work
  the same way (MML syntax, stdin friendly).
- The `message read` / `message export --full` / `message delete` /
  `message move` / `message copy` subcommands work the same way.
- The `flag add` / `flag remove` subcommands work the same way.
- The `attachment download <id>` subcommand works the same way.
- `--output json` / `--output plain` still work.
- The `RUST_LOG=debug` / `RUST_BACKTRACE=1` env vars still work.
- MML message composition (`<#multipart>` / `<#part>` tags) is unchanged.

## Checklist for moving a v1 config to v2

```toml
# For each [accounts.NAME] section:

# 1. Backend block → IMAP table
- backend.type = "imap"
- backend.host = "imap.example.com"
- backend.port = 993
- backend.encryption.type = "tls"
- backend.login = "user@example.com"
- backend.auth.type = "password"
- backend.auth.raw = "secret"
+ imap.server = "imaps://imap.example.com:993"
+ imap.sasl.plain.username = "user@example.com"
+ imap.sasl.plain.password.raw = "secret"

# 2. SMTP block (was nested under message.send)
- message.send.backend.type = "smtp"
- message.send.backend.host = "smtp.example.com"
- message.send.backend.port = 587
- message.send.backend.encryption.type = "start-tls"
- message.send.backend.login = "user@example.com"
- message.send.backend.auth.type = "password"
- message.send.backend.auth.raw = "secret"
+ smtp.server = "smtps://smtp.example.com:465"
+ smtp.sasl.plain.username = "user@example.com"
+ smtp.sasl.plain.password.raw = "secret"

# 3. Folder aliases (rename key)
- folder.aliases.inbox = "INBOX"
- folder.aliases.sent = "Sent"
+ mailbox.alias.inbox = "INBOX"
+ mailbox.alias.sent = "Sent"
```

Then run `himalaya account check` to confirm both backends are reachable.