fix(skills/email/himalaya): document v1.2.0 folder.aliases syntax

The bundled himalaya skill documented folder aliases using a stale
TOML schema (`[accounts.NAME.folder.alias]`, singular) that himalaya
v1.2.0 silently ignores. The TOML parses without error, but the
alias resolver never reads the sub-section — every lookup then falls
through to the canonical folder name.

Source: in `pimalaya/core` (the `email-lib` crate himalaya v1.2.0
depends on, currently v0.27.0), `email/src/folder/config.rs` defines
`FolderConfig { aliases: Option<HashMap<String, String>>, ... }`
(plural, no `#[serde(rename)]`/`alias` aliases, no
`deny_unknown_fields`), and `account/config/mod.rs::get_folder_alias`
returns the input verbatim when no alias is found. So the singular
`alias` key deserializes to nothing and lookups silently fall
through.

On Gmail (where `sent` resolves to `[Gmail]/Sent Mail`, not `Sent`)
this means save-to-Sent fails *after* SMTP delivery already
succeeded, and `himalaya message send` exits non-zero. Any caller
(agent, script, user) that retries on that exit code will re-run
the entire send — including SMTP — producing duplicate emails to
recipients. Silent ignore + caller-level retry is significantly
worse than a config that just doesn't work.

This commit updates SKILL.md and references/configuration.md to the
v1.2.0 `folder.aliases.X` syntax (plural, dotted keys, directly
under the account section), adds a Gmail-specific block with the
`[Gmail]/Sent Mail`-style mapping, and adds notes on the failure
mode so future readers don't hit the same trap. SKILL.md version
bumped 1.0.0 → 1.1.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

skills/email/himalaya/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: himalaya
 description: "Himalaya CLI: IMAP/SMTP email from terminal."
-version: 1.0.0
+version: 1.1.0
 author: community
 license: MIT
 metadata:
@@ -71,8 +71,28 @@ message.send.backend.encryption.type = "start-tls"
 message.send.backend.login = "you@example.com"
 message.send.backend.auth.type = "password"
 message.send.backend.auth.cmd = "pass show email/smtp"
+
+# Folder aliases (himalaya v1.2.0+ syntax). Required whenever the
+# server's folder names don't match himalaya's canonical names
+# (inbox/sent/drafts/trash). Gmail is the common case — see
+# `references/configuration.md` for the `[Gmail]/Sent Mail` mapping.
+folder.aliases.inbox = "INBOX"
+folder.aliases.sent = "Sent"
+folder.aliases.drafts = "Drafts"
+folder.aliases.trash = "Trash"
 ```
 
+> **Heads up on the alias syntax.** Pre-v1.2.0 docs used a
+> `[accounts.NAME.folder.alias]` sub-section (singular `alias`).
+> v1.2.0 silently ignores that form — TOML parses fine, but the
+> alias resolver never reads it, so every lookup falls through to
+> the canonical name. On Gmail this means save-to-Sent fails *after*
+> SMTP delivery succeeds, and `himalaya message send` exits non-zero.
+> Any caller (agent, script, user) that retries on that exit code
+> will re-run the entire send — including SMTP — producing duplicate
+> emails to recipients. Always use `folder.aliases.X` (plural, dotted
+> keys, directly under `[accounts.NAME]`).
+
 ## Hermes Integration Notes
 
 - **Reading, listing, searching, moving, deleting** all work directly through the terminal tool

skills/email/himalaya/references/configuration.md

@@ -27,6 +27,13 @@ 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 = "your-password"
+
+# Folder aliases — required whenever server folder names differ
+# from himalaya's canonical names. See "Folder Aliases" below.
+folder.aliases.inbox = "INBOX"
+folder.aliases.sent = "Sent"
+folder.aliases.drafts = "Drafts"
+folder.aliases.trash = "Trash"
 ```
 
 ## Password Options
@@ -75,6 +82,16 @@ message.send.backend.encryption.type = "start-tls"
 message.send.backend.login = "you@gmail.com"
 message.send.backend.auth.type = "password"
 message.send.backend.auth.cmd = "pass show google/app-password"
+
+# Gmail folder mapping. Without these, save-to-Sent fails after
+# SMTP delivery succeeds (Gmail's Sent folder is `[Gmail]/Sent Mail`,
+# not `Sent`), and `himalaya message send` exits non-zero. Any
+# caller that retries on that error will re-run SMTP — duplicate
+# emails to recipients. Always include this block for Gmail.
+folder.aliases.inbox = "INBOX"
+folder.aliases.sent = "[Gmail]/Sent Mail"
+folder.aliases.drafts = "[Gmail]/Drafts"
+folder.aliases.trash = "[Gmail]/Trash"
 ```
 
 **Note:** Gmail requires an App Password if 2FA is enabled.
@@ -107,16 +124,42 @@ message.send.backend.auth.cmd = "pass show icloud/app-password"
 
 ## Folder Aliases
 
-Map custom folder names:
+Map himalaya's canonical folder names (`inbox`, `sent`, `drafts`,
+`trash`) to whatever the server actually calls them. Use the
+v1.2.0 `folder.aliases.X` syntax (plural, dotted keys, directly
+under `[accounts.NAME]`):
 
 ```toml
-[accounts.default.folder.alias]
+[accounts.default]
+# ... other account config ...
+
+folder.aliases.inbox = "INBOX"
+folder.aliases.sent = "Sent"
+folder.aliases.drafts = "Drafts"
+folder.aliases.trash = "Trash"
+```
+
+The equivalent TOML sub-section form also works in v1.2.0:
+
+```toml
+[accounts.default.folder.aliases]
 inbox = "INBOX"
 sent = "Sent"
 drafts = "Drafts"
 trash = "Trash"
 ```
 
+> **Don't use the singular `alias` form.** Pre-v1.2.0 docs showed
+> `[accounts.NAME.folder.alias]` (singular). v1.2.0 silently
+> ignores that sub-section — TOML parses without error, but the
+> alias resolver never reads it. Every lookup then falls through
+> to the canonical name. On Gmail (where `sent` is actually
+> `[Gmail]/Sent Mail`) this means save-to-Sent fails *after* SMTP
+> delivery succeeds, and `himalaya message send` exits non-zero.
+> Any caller (agent, script, user) that retries on that error
+> code will re-run the send — including SMTP — producing duplicate
+> emails to recipients. Always use `folder.aliases.X` (plural).
+
 ## Multiple Accounts
 
 ```toml