@quantumclaw/quantumclaw 2026.3.22

package/skills/himalaya/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: himalaya
+description: "CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language)."
+homepage: https://github.com/pimalaya/himalaya
+metadata:
+  {
+    "quantumclaw":
+      {
+        "emoji": "📧",
+        "requires": { "bins": ["himalaya"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "himalaya",
+              "bins": ["himalaya"],
+              "label": "Install Himalaya (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Himalaya Email CLI
+
+Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.
+
+## References
+
+- `references/configuration.md` (config file setup + IMAP/SMTP authentication)
+- `references/message-composition.md` (MML syntax for composing emails)
+
+## Prerequisites
+
+1. Himalaya CLI installed (`himalaya --version` to verify)
+2. A configuration file at `~/.config/himalaya/config.toml`
+3. IMAP/SMTP credentials configured (password stored securely)
+
+## Configuration Setup
+
+Run the interactive wizard to set up an account:
+
+```bash
+himalaya account configure
+```
+
+Or create `~/.config/himalaya/config.toml` manually:
+
+```toml
+[accounts.personal]
+email = "you@example.com"
+display-name = "Your Name"
+default = true
+
+backend.type = "imap"
+backend.host = "imap.example.com"
+backend.port = 993
+backend.encryption.type = "tls"
+backend.login = "you@example.com"
+backend.auth.type = "password"
+backend.auth.cmd = "pass show email/imap"  # or use keyring
+
+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 = "you@example.com"
+message.send.backend.auth.type = "password"
+message.send.backend.auth.cmd = "pass show email/smtp"
+```
+
+## Common Operations
+
+### List Folders
+
+```bash
+himalaya folder list
+```
+
+### List Emails
+
+List emails in INBOX (default):
+
+```bash
+himalaya envelope list
+```
+
+List emails in a specific folder:
+
+```bash
+himalaya envelope list --folder "Sent"
+```
+
+List with pagination:
+
+```bash
+himalaya envelope list --page 1 --page-size 20
+```
+
+### Search Emails
+
+```bash
+himalaya envelope list from john@example.com subject meeting
+```
+
+### Read an Email
+
+Read email by ID (shows plain text):
+
+```bash
+himalaya message read 42
+```
+
+Export raw MIME:
+
+```bash
+himalaya message export 42 --full
+```
+
+### Reply to an Email
+
+Interactive reply (opens $EDITOR):
+
+```bash
+himalaya message reply 42
+```
+
+Reply-all:
+
+```bash
+himalaya message reply 42 --all
+```
+
+### Forward an Email
+
+```bash
+himalaya message forward 42
+```
+
+### Write a New Email
+
+Interactive compose (opens $EDITOR):
+
+```bash
+himalaya message write
+```
+
+Send directly using template:
+
+```bash
+cat << 'EOF' | himalaya template send
+From: you@example.com
+To: recipient@example.com
+Subject: Test Message
+
+Hello from Himalaya!
+EOF
+```
+
+Or with headers flag:
+
+```bash
+himalaya message write -H "To:recipient@example.com" -H "Subject:Test" "Message body here"
+```
+
+### Move/Copy Emails
+
+Move to folder:
+
+```bash
+himalaya message move 42 "Archive"
+```
+
+Copy to folder:
+
+```bash
+himalaya message copy 42 "Important"
+```
+
+### Delete an Email
+
+```bash
+himalaya message delete 42
+```
+
+### Manage Flags
+
+Add flag:
+
+```bash
+himalaya flag add 42 --flag seen
+```
+
+Remove flag:
+
+```bash
+himalaya flag remove 42 --flag seen
+```
+
+## Multiple Accounts
+
+List accounts:
+
+```bash
+himalaya account list
+```
+
+Use a specific account:
+
+```bash
+himalaya --account work envelope list
+```
+
+## Attachments
+
+Save attachments from a message:
+
+```bash
+himalaya attachment download 42
+```
+
+Save to specific directory:
+
+```bash
+himalaya attachment download 42 --dir ~/Downloads
+```
+
+## Output Formats
+
+Most commands support `--output` for structured output:
+
+```bash
+himalaya envelope list --output json
+himalaya envelope list --output plain
+```
+
+## Debugging
+
+Enable debug logging:
+
+```bash
+RUST_LOG=debug himalaya envelope list
+```
+
+Full trace with backtrace:
+
+```bash
+RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list
+```
+
+## Tips
+
+- Use `himalaya --help` or `himalaya <command> --help` for detailed usage.
+- Message IDs are relative to the current folder; re-list after folder changes.
+- For composing rich emails with attachments, use MML syntax (see `references/message-composition.md`).
+- Store passwords securely using `pass`, system keyring, or a command that outputs the password.

package/skills/himalaya/references/configuration.md

@@ -0,0 +1,184 @@
+# Himalaya Configuration Reference
+
+Configuration file location: `~/.config/himalaya/config.toml`
+
+## Minimal IMAP + SMTP Setup
+
+```toml
+[accounts.default]
+email = "user@example.com"
+display-name = "Your Name"
+default = true
+
+# IMAP backend for reading emails
+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 = "your-password"
+
+# SMTP backend for sending emails
+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 = "your-password"
+```
+
+## Password Options
+
+### Raw password (testing only, not recommended)
+
+```toml
+backend.auth.raw = "your-password"
+```
+
+### Password from command (recommended)
+
+```toml
+backend.auth.cmd = "pass show email/imap"
+# backend.auth.cmd = "security find-generic-password -a user@example.com -s imap -w"
+```
+
+### System keyring (requires keyring feature)
+
+```toml
+backend.auth.keyring = "imap-example"
+```
+
+Then run `himalaya account configure <account>` to store the password.
+
+## Gmail Configuration
+
+```toml
+[accounts.gmail]
+email = "you@gmail.com"
+display-name = "Your Name"
+default = true
+
+backend.type = "imap"
+backend.host = "imap.gmail.com"
+backend.port = 993
+backend.encryption.type = "tls"
+backend.login = "you@gmail.com"
+backend.auth.type = "password"
+backend.auth.cmd = "pass show google/app-password"
+
+message.send.backend.type = "smtp"
+message.send.backend.host = "smtp.gmail.com"
+message.send.backend.port = 587
+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"
+```
+
+**Note:** Gmail requires an App Password if 2FA is enabled.
+
+## iCloud Configuration
+
+```toml
+[accounts.icloud]
+email = "you@icloud.com"
+display-name = "Your Name"
+
+backend.type = "imap"
+backend.host = "imap.mail.me.com"
+backend.port = 993
+backend.encryption.type = "tls"
+backend.login = "you@icloud.com"
+backend.auth.type = "password"
+backend.auth.cmd = "pass show icloud/app-password"
+
+message.send.backend.type = "smtp"
+message.send.backend.host = "smtp.mail.me.com"
+message.send.backend.port = 587
+message.send.backend.encryption.type = "start-tls"
+message.send.backend.login = "you@icloud.com"
+message.send.backend.auth.type = "password"
+message.send.backend.auth.cmd = "pass show icloud/app-password"
+```
+
+**Note:** Generate an app-specific password at appleid.apple.com
+
+## Folder Aliases
+
+Map custom folder names:
+
+```toml
+[accounts.default.folder.alias]
+inbox = "INBOX"
+sent = "Sent"
+drafts = "Drafts"
+trash = "Trash"
+```
+
+## Multiple Accounts
+
+```toml
+[accounts.personal]
+email = "personal@example.com"
+default = true
+# ... backend config ...
+
+[accounts.work]
+email = "work@company.com"
+# ... backend config ...
+```
+
+Switch accounts with `--account`:
+
+```bash
+himalaya --account work envelope list
+```
+
+## Notmuch Backend (local mail)
+
+```toml
+[accounts.local]
+email = "user@example.com"
+
+backend.type = "notmuch"
+backend.db-path = "~/.mail/.notmuch"
+```
+
+## OAuth2 Authentication (for providers that support it)
+
+```toml
+backend.auth.type = "oauth2"
+backend.auth.client-id = "your-client-id"
+backend.auth.client-secret.cmd = "pass show oauth/client-secret"
+backend.auth.access-token.cmd = "pass show oauth/access-token"
+backend.auth.refresh-token.cmd = "pass show oauth/refresh-token"
+backend.auth.auth-url = "https://provider.com/oauth/authorize"
+backend.auth.token-url = "https://provider.com/oauth/token"
+```
+
+## Additional Options
+
+### Signature
+
+```toml
+[accounts.default]
+signature = "Best regards,\nYour Name"
+signature-delim = "-- \n"
+```
+
+### Downloads directory
+
+```toml
+[accounts.default]
+downloads-dir = "~/Downloads/himalaya"
+```
+
+### Editor for composing
+
+Set via environment variable:
+
+```bash
+export EDITOR="vim"
+```

package/skills/himalaya/references/message-composition.md

@@ -0,0 +1,199 @@
+# Message Composition with MML (MIME Meta Language)
+
+Himalaya uses MML for composing emails. MML is a simple XML-based syntax that compiles to MIME messages.
+
+## Basic Message Structure
+
+An email message is a list of **headers** followed by a **body**, separated by a blank line:
+
+```
+From: sender@example.com
+To: recipient@example.com
+Subject: Hello World
+
+This is the message body.
+```
+
+## Headers
+
+Common headers:
+
+- `From`: Sender address
+- `To`: Primary recipient(s)
+- `Cc`: Carbon copy recipients
+- `Bcc`: Blind carbon copy recipients
+- `Subject`: Message subject
+- `Reply-To`: Address for replies (if different from From)
+- `In-Reply-To`: Message ID being replied to
+
+### Address Formats
+
+```
+To: user@example.com
+To: John Doe <john@example.com>
+To: "John Doe" <john@example.com>
+To: user1@example.com, user2@example.com, "Jane" <jane@example.com>
+```
+
+## Plain Text Body
+
+Simple plain text email:
+
+```
+From: alice@localhost
+To: bob@localhost
+Subject: Plain Text Example
+
+Hello, this is a plain text email.
+No special formatting needed.
+
+Best,
+Alice
+```
+
+## MML for Rich Emails
+
+### Multipart Messages
+
+Alternative text/html parts:
+
+```
+From: alice@localhost
+To: bob@localhost
+Subject: Multipart Example
+
+<#multipart type=alternative>
+This is the plain text version.
+<#part type=text/html>
+<html><body><h1>This is the HTML version</h1></body></html>
+<#/multipart>
+```
+
+### Attachments
+
+Attach a file:
+
+```
+From: alice@localhost
+To: bob@localhost
+Subject: With Attachment
+
+Here is the document you requested.
+
+<#part filename=/path/to/document.pdf><#/part>
+```
+
+Attachment with custom name:
+
+```
+<#part filename=/path/to/file.pdf name=report.pdf><#/part>
+```
+
+Multiple attachments:
+
+```
+<#part filename=/path/to/doc1.pdf><#/part>
+<#part filename=/path/to/doc2.pdf><#/part>
+```
+
+### Inline Images
+
+Embed an image inline:
+
+```
+From: alice@localhost
+To: bob@localhost
+Subject: Inline Image
+
+<#multipart type=related>
+<#part type=text/html>
+<html><body>
+<p>Check out this image:</p>
+<img src="cid:image1">
+</body></html>
+<#part disposition=inline id=image1 filename=/path/to/image.png><#/part>
+<#/multipart>
+```
+
+### Mixed Content (Text + Attachments)
+
+```
+From: alice@localhost
+To: bob@localhost
+Subject: Mixed Content
+
+<#multipart type=mixed>
+<#part type=text/plain>
+Please find the attached files.
+
+Best,
+Alice
+<#part filename=/path/to/file1.pdf><#/part>
+<#part filename=/path/to/file2.zip><#/part>
+<#/multipart>
+```
+
+## MML Tag Reference
+
+### `<#multipart>`
+
+Groups multiple parts together.
+
+- `type=alternative`: Different representations of same content
+- `type=mixed`: Independent parts (text + attachments)
+- `type=related`: Parts that reference each other (HTML + images)
+
+### `<#part>`
+
+Defines a message part.
+
+- `type=<mime-type>`: Content type (e.g., `text/html`, `application/pdf`)
+- `filename=<path>`: File to attach
+- `name=<name>`: Display name for attachment
+- `disposition=inline`: Display inline instead of as attachment
+- `id=<cid>`: Content ID for referencing in HTML
+
+## Composing from CLI
+
+### Interactive compose
+
+Opens your `$EDITOR`:
+
+```bash
+himalaya message write
+```
+
+### Reply (opens editor with quoted message)
+
+```bash
+himalaya message reply 42
+himalaya message reply 42 --all  # reply-all
+```
+
+### Forward
+
+```bash
+himalaya message forward 42
+```
+
+### Send from stdin
+
+```bash
+cat message.txt | himalaya template send
+```
+
+### Prefill headers from CLI
+
+```bash
+himalaya message write \
+  -H "To:recipient@example.com" \
+  -H "Subject:Quick Message" \
+  "Message body here"
+```
+
+## Tips
+
+- The editor opens with a template; fill in headers and body.
+- Save and exit the editor to send; exit without saving to cancel.
+- MML parts are compiled to proper MIME when sending.
+- Use `himalaya message export --full` to inspect the raw MIME structure of received emails.