mailmate 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81aeb9b0f5abd70325c74329db580be4134b27eee50b03f6caef5958b653f288
-  data.tar.gz: c614a5dcc2e4fb2bd6fa797e09d1e959a1ecbf9c26ae7c6a21b0e26899c6a32e
+  metadata.gz: 7d4531494a2e95ee32395c937a293085b055c6868327f9914702da62a7b039c6
+  data.tar.gz: 3251b2608c1ede51d85425c205a274993d51b58b9cace6f04eb53981a04345bb
 SHA512:
-  metadata.gz: 9c27e9400d40047291b3486e6895b47f8e8855985bb74bfe75de2a338c5c5d59356b92d330ad93186828e3aa579f9c6273602432a77f2dbc383b3e7afdfb02aa
-  data.tar.gz: c3d898edeb7fe251c9f816dc333014e915bcb8b1e4d63e503a52192b22ca6353bf5657109688c36a71af04060cda6fc816a95c3b680b526382f8afc47e63851c
+  metadata.gz: 4a162097210b4578cc6118e70607258523cbf1b0a82e50a6c50b9b10a3a30bef05c5dd394ab50204920d7967bb9103073a457259f1e4ec570920daff09b1031e
+  data.tar.gz: 84fa48ec99f5e9df866899d4c805df8de7c1b427fd8ba868732baf79ad9c9b6c3c55cae92e00fec928ecc3c43fca7cd4572d8f2828f4a270494310dbdd7c97f7

data/README.md

@@ -187,6 +187,8 @@ mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
 | `m <term>` | Common headers OR body. |
 | `d <date>` | Received: `Nh` (rolling clock hours, `24h` = last 24 hours), `Nd`/`Nw`/`Nm`/`Ny` (N calendar units ending today — `1d` = today, `2d` = yesterday + today), or absolute `Y`, `Y-M`, `Y-M-D`. Slash dates are month-first American (`8/9/2026` = Aug 9); `--european` flips to day-first. Comparisons on absolute dates: `d >2026-08` (after), `d <2026-08` (before), also `>=`/`<=`. |
 | `T <tag>` | Tags / IMAP keywords (`K` is a synonym). |
+| `is:<state>` | Message state: `is:unread`, `is:read`, `is:flagged`, `is:replied`, `is:draft` (Gmail synonyms `starred`/`answered` work; `-is:unread` negates). |
+| `has:attachment` | Root MIME type is `multipart/mixed` — the standard attachment layout. |
 | `!<value>` | Negate, e.g. `f !smith` = From does NOT contain smith; works on dates too (`d !3d` = more than 3 days ago). |
 
 Dates match on the **display-zone day** — the same day the `date`/`time` output columns show. An impossible date term or combination (`d 2026-02-31`, `d >2026 d <2025`) is a usage error, not a silent empty result. Familiar foreign `key:value` tokens (`from:bob`, `date:today`, `after:2026-08-01`, `older_than:2w`) are auto-translated to quicksearch with each rewrite announced on stderr; unrecognized keys (`is:unread`) are searched as literal text, and an empty result says so.
@@ -360,22 +362,28 @@ EOF
 mm-send -t friend@example.com -s "Photos" /path/to/photo1.jpg /path/to/photo2.jpg <<<"See attached."
 ```
 
-#### Replies and threading
+#### Replies, forwards, and threading
 
-MailMate auto-generates the outgoing `Message-ID` for every send — never the caller's job. `In-Reply-To` and `References` are pure pass-through: whatever you set via `--header` ships verbatim, and **what you don't set is absent**. A reply with a `Re: …` subject but no threading headers shows up as a brand-new conversation in modern mail clients (they thread on headers, not subjects).
+**A `Re:` subject does not thread.** Modern clients thread on headers, so a reply without `In-Reply-To` / `References` shows up in the recipient's client as a brand-new conversation — and nothing in your own view reveals it. MailMate generates the outgoing `Message-ID` itself; that part is never your job.
 
-To make a reply land in-thread, pass both headers:
+Point `mm-send` at the parent and it derives the rest:
 
 ```bash
-mm-send -f you@x -t them@y -s "Re: foo" \
-  --header "In-Reply-To: <parent-message-id@domain>" \
-  --header "References: <root-mid> <parent-mid>" \
-  --send-now <<<"body"
+# Reply — derives In-Reply-To, References, recipient and "Re:" subject.
+mm-send -f you@x --reply-to "<parent-message-id@domain>" --send-now <<<"body"
+
+# Reply-all: adds the other recipients, minus your own identities.
+mm-send -f you@x --reply-all-to 12345 --send-now <<<"body"
+
+# Forward: "Fwd:" subject and the forwarded block; you supply the recipient.
+mm-send -f you@x --forward 12345 -t someone@example.com <<<"FYI"
 ```
 
-Construct `References` as the source message's `References` header (if any) with the source's `Message-ID` appended. If the source is itself a thread root with no `References`, just use its `Message-ID` alone.
+The parent is an eml-id or an RFC Message-ID. **Fields you pass explicitly win; fields you omit follow normal reply rules**, and overriding a visible field never drops the threading headers. `--no-quote` suppresses the quoted original. `--print-prefill` prints the derived fields as JSON and sends nothing — the hook for other tools that fill their own compose form.
+
+Hand-assembly via `--header` still works and is the escape hatch when the parent isn't in MailMate's index. The `mailmate-mcp` `send` / `draft` tools take `in_reply_to` and `references` directly.
 
-The same passthrough applies to the `mailmate-mcp` `send` tool — see the `from`, `in_reply_to`, and `references` fields.
+> **Canonical reference:** [docs/Composing and threading.md](docs/Composing%20and%20threading.md) — the References chain, the merge rule, header safety, identity selection. Everything above summarizes it; when the two disagree, that file is right.
 
 ### `mm-draft` — compose without sending
 
@@ -385,10 +393,9 @@ The same passthrough applies to the `mailmate-mcp` `send` tool — see the `from
 # Opens a draft in MailMate; never sends.
 echo "Quick **markdown** body." | mm-draft -t friend@example.com -s "Hello"
 
-# Threading headers and attachments work exactly as in mm-send.
-mm-draft -f you@x -t them@y -s "Re: foo" \
-  --header "In-Reply-To: <parent-message-id@domain>" \
-  --header "References: <root-mid> <parent-mid>" <<<"body"
+# Reply/forward derivation, threading headers and attachments all work
+# exactly as in mm-send — the only difference is that this cannot send.
+mm-draft -f you@x --reply-to "<parent-message-id@domain>" <<<"body"
 
 # Passing --send-now is refused (exit 2):
 mm-draft -t friend@example.com -s "nope" --send-now <<<"body"
@@ -426,6 +433,12 @@ A few rough edges to be aware of:
 
 ## Status
 
+1.8.0 — Reply derivation, and message-state specs.
+
+**Composing:** replies and forwards are now derived from the parent instead of hand-assembled. `mm-send` / `mm-draft` gain `--reply-to <id>`, `--reply-all-to <id>`, `--forward <id>` (eml-id or Message-ID), which compute `In-Reply-To`, the full `References` chain, recipients and the `Re:`/`Fwd:` subject, plus `--no-quote` and `--print-prefill` (derived fields as JSON, sends nothing). The MCP `send`/`draft` tools take the same `reply_to` / `reply_all_to` / `forward` arguments. Explicitly-passed fields win over derived ones, and overriding a visible field never drops the threading headers. A forward deliberately does *not* thread into the original conversation. The chain is built in exactly one place (`Mailmate::ReplyPrefill`), and `--header` values now route through one sanitizer (`Mailmate::HeaderValue`) — previously the MCP's own argv builder lacked the CR/LF defense that stops a parent `Message-ID` smuggling extra headers. All of it is documented once in [docs/Composing and threading.md](docs/Composing%20and%20threading.md), which the README, `--help` preambles and MCP instructions now point at rather than restate. Every `exe/` command answers `--version`, so consumers can check the installed version instead of probing for a flag (the CLIs pass unknown flags through to `emate`, which makes flag-probing unsafe). The gemspec finally carries `homepage` and `metadata`, so the rubygems page links back to the source.
+
+**Search:** `is:unread`, `is:read`, `is:flagged`, `is:replied`, `is:draft`, and `has:attachment` are first-class quicksearch (the MailMate app has no state vocabulary in its toolbar search — its `A` modifier searches attachment *filenames* — so the familiar Gmail spellings were adopted, including the `starred`/`answered` synonyms and `-is:unread` negation). Flag states read the `#flags` index; attachment presence reads the indexed root `content-type` (`multipart/mixed`). An unknown state value (`is:snoozed`) is a usage error naming the known states, not a silent empty result.
+
 1.7.0 — Search-language release, driven by a study of how LLM agents actually misuse `mmsearch`. The quicksearch syntax reference is now single-sourced (`Mailmate::SearchSyntax`) into both `mmsearch --help` and the MCP `search` description, so the two can no longer drift. Foreign `key:value` dialects (Gmail/Outlook/Spotlight — `from:bob`, `date:today`, `after:2026-08-01`, `older_than:2w`) auto-translate to their exact quicksearch equivalent, loudly: each rewrite is announced on stderr, and untranslatable keys are flagged when a search returns nothing. The language itself grew: boolean `or` (AND binds tighter, no parens; a bare term after `or` inherits the modifier in force), date comparisons (`d >2026-08`, `d <2026-08`, `>=`/`<=`), rolling hour windows (`d 24h`), and American slash dates (`d 8/9/2026`; `--european` for day-first). Two semantic fixes: `d 1d` now means *today* (N calendar units ending today, matching the MailMate app; the old today−N made it span two days), and date matching converts to the display zone — the same conversion the `date`/`time` columns use — so the day a search matches is always the day shown (sender-local index days previously leaked "tomorrow's" mail into `d 1d`). Impossible date terms and combinations (`d 0d`, `d 2026-02-31`, `d >2026 d <2025`) are usage errors instead of silent empty results.
 
 1.6.0 — Distribution release. The repo is now a Claude Code plugin marketplace (`/plugin marketplace add brianmd/mailmate`), and a one-line `install.sh` provisions the MCP server into an isolated `~/.mailmate-mcp` — including a private relocatable Ruby when no Ruby ≥ 3.0 is present — without touching system Ruby, Homebrew, or shell profiles. Every MCP tool now carries a `title` plus `readOnlyHint`/`destructiveHint` annotations (Claude clients use these for permission behavior; Anthropic's directory review requires them), and the README gains a formal Privacy Policy section. No changes to CLI or library behavior.

data/docs/Composing and threading.md

@@ -0,0 +1,69 @@
+# Composing and threading
+
+**This is the canonical description of how mailmate sends mail.** `mm-send`, `mm-draft`, the MCP `send` / `draft` tools, and every downstream consumer behave as described here. Other surfaces (the README, `--help` preambles, MCP tool descriptions) carry deliberately-minimal summaries and point here — they should never restate a rule in their own words, because a second independent statement of the same fact is what drifts.
+
+## The two commands, and why there are exactly two
+
+`mm-send` and `mm-draft` are thin wrappers around MailMate's bundled `emate mailto`, with `--markup markdown` enforced. The body is read from stdin; every other flag passes through to `emate`.
+
+They differ on exactly one axis: **send-ability.** `mm-send` can send (with `--send-now`); `mm-draft` refuses `--send-now` with a nonzero exit and therefore *cannot*, no matter what flags it is handed. That refusal is the entire point — a "compose this but don't send it" instruction can't be silently defeated by a caller (human or model) adding a flag.
+
+That axis, and only that axis, earns a command name. It has to be a name because a name is a guarantee you can reason about before running anything; a flag can be forgotten, mis-copied, or argued away. Every *other* variation — replying, replying-all, forwarding — is a flag, because none of them is safety-critical and because command names multiply where flags add. Cross-producting "threading mode" with "send-ability" would mean `mm-reply`, `mm-reply-all`, `mm-reply-draft`, `mm-reply-all-draft`, and then double again the day forwarding lands. The flag form covers the same matrix with two commands, permanently.
+
+## Threading
+
+**MailMate generates the outgoing `Message-ID` itself.** Never construct or pass one.
+
+`In-Reply-To` and `References` are **pure pass-through**: whatever you set ships verbatim, and *what you don't set is absent*. This is the rule that surprises people, so state it plainly: **a `Re:` subject does not thread.** Modern mail clients thread on headers. A reply with a perfect `Re: …` subject and no threading headers appears in the recipient's client as a brand-new conversation, and nothing about the sender's own view reveals this — the failure is invisible from where you're standing.
+
+The chain is built one way:
+
+> `References` = the parent's own `References` header (if any) + the parent's `Message-ID` appended.
+> If the parent is itself a thread root with no `References`, use its `Message-ID` alone.
+> `In-Reply-To` = the parent's `Message-ID`.
+
+Message-IDs may be written with or without angle brackets on input; they are normalized to the bracketed RFC 5322 form on the wire.
+
+### Deriving it, rather than assembling it
+
+Getting the chain wrong produces a message that looks correct everywhere you can see it and silently fails to thread. So prefer having it derived from the parent rather than assembling it by hand:
+
+- **CLI:** `--reply-to <id>` / `--reply-all-to <id>` / `--forward <id>` on either command take the parent's eml-id or RFC Message-ID and derive the threading headers, recipients, and subject from it. `--no-quote` drops the quoted original.
+- **MCP:** the `send` / `draft` tools take `reply_to` / `reply_all_to` / `forward` (plus `quote: false`), which hand the id to the same CLI. They also still accept `in_reply_to` / `references` directly — if you use those, set **both**.
+- **Library:** `Mailmate::ReplyPrefill.build(id, mode:)` returns the derived fields without sending anything, and `mm-send --reply-to <id> --print-prefill` is the same thing as JSON for non-Ruby callers. That's the hook for a tool filling its own compose form.
+
+Because `forward` derives no recipient, it is the one mode that still requires `to`.
+
+Hand-assembly via `--header` remains available and is the escape hatch when the parent isn't in MailMate's index:
+
+```sh
+mm-send -f you@x -t them@y -s "Re: foo" \
+  --header "In-Reply-To: <parent-message-id@domain>" \
+  --header "References: <root-mid> <parent-mid>" \
+  --send-now <<<"body"
+```
+
+### The merge rule
+
+When a parent is supplied, **explicitly-passed fields always win; omitted fields follow normal reply rules** (parent's sender becomes the recipient, subject becomes `Re: <original>`, the quoted original seeds the body, reply-all additionally carries the other recipients minus your own identities).
+
+This rule is uniform across every surface that composes from a parent — the CLI flags above and markdownr's compose popup — so a caller who learns it once can predict all of them. Overriding a visible field never drops the threading headers.
+
+## Header safety
+
+`--header` values ship verbatim into the message. Any value derived from *another message* is therefore untrusted input: a `Message-ID` or `References` carrying `\r\n` could otherwise smuggle additional RFC 5322 headers into the outgoing message. All header values are collapsed to a single line before injection. If you add a new path that pushes a `--header`, route it through the same sanitization rather than formatting the flag yourself.
+
+## Identity
+
+`-f <address>` picks which configured MailMate identity sends. Without it, MailMate uses its default identity — which, when the recipient is one of your own addresses, may not be the one you expect. Set it explicitly. `mmdiscover` lists the available addresses and writes them to `~/.config/mailmate/config.yml`, where `Mailmate::Identity` reads them.
+
+## Prerequisites for markdown bodies
+
+Bodies are markdown; MailMate renders them to HTML on the way out. For that to reach recipients, MailMate → Preferences → Composer must have **Preview: Display = Always** and **Replying/Forwarding HTML = Always embed**. These are global, one-time settings; without them recipients get plain text.
+
+## Who points here
+
+- `README.md` § `mm-send` / `mm-draft` — short usage orientation.
+- `mm-send --help` / `mm-draft --help` preambles — the minimal operational recipe.
+- The MCP server's `initialize` instructions and `send` / `draft` tool descriptions.
+- markdownr's `.claude/instructions/nested/email.md` (compose popup + routes) and the private `email` skill (sender/signature doctrine). Those own their own layers — markdownr's UI surface and personal doctrine respectively — and defer to this file for anything below them.

data/exe/mailmate-mcp

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/mcp"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mailmate-mcp")
+
 exit Mailmate::MCP.run

data/exe/mm-draft

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/draft"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-draft")
+
 exit Mailmate::CLI::Draft.run(ARGV)

data/exe/mm-mailboxes

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/mailboxes"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-mailboxes")
+
 exit Mailmate::CLI::Mailboxes.run(ARGV)

data/exe/mm-modify

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/modify"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-modify")
+
 exit Mailmate::CLI::Modify.run(ARGV)

data/exe/mm-send

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/send"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-send")
+
 exit Mailmate::CLI::Send.run(ARGV)

data/exe/mm-verify

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/verify"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-verify")
+
 exit Mailmate::CLI::Verify.run(ARGV)

data/exe/mmdiscover

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/discover"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmdiscover")
+
 exit Mailmate::CLI::Discover.run(ARGV)

data/exe/mmmessage

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/message"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmmessage")
+
 exit Mailmate::CLI::Message.run(ARGV)

data/exe/mmopen

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/open"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmopen")
+
 exit Mailmate::CLI::Open.run(ARGV)

data/exe/mmsearch

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/search"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmsearch")
+
 exit Mailmate::CLI::Search.run(ARGV)

data/exe/mmtags

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/tags"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmtags")
+
 exit Mailmate::CLI::Tags.run(ARGV)

data/lib/mailmate/cli/search.rb

@@ -225,8 +225,9 @@ module Mailmate
                "Slash dates are day-first: d 9/8/2026 = Aug 9 (default: month-first American)") { opts[:european] = true }
           o.separator ""
           o.separator "SEARCH-STRING SYNTAX"
-          o.separator "  Mirrors MailMate's toolbar quicksearch. There is no native key:value"
-          o.separator "  form — but familiar foreign tokens are auto-translated (see below)."
+          o.separator "  Mirrors MailMate's toolbar quicksearch, plus native state specs"
+          o.separator "  (is:unread, has:attachment). Other familiar key:value tokens are"
+          o.separator "  auto-translated (see FOREIGN SYNTAX below)."
           o.separator Mailmate::SearchSyntax.reference(indent: "  ")
           o.separator "  (b also takes --all to include un-indexed messages.)"
           o.separator ""
@@ -396,13 +397,23 @@ module Mailmate
           else
             negate = tok.start_with?("!")
             operand = negate ? tok[1..] : tok
-            # A bare term opening an or-group inherits the modifier in force
-            # (`d 2024 or 2025`). Elsewhere it is MailMate's "Common"
-            # specifier — common headers OR body — matching the UI
-            # quicksearch behavior. Pass --headers-only to skip the body scan
-            # when speed matters.
-            target = (i.zero? && !quoted && in_force) ? in_force : :message_or_body
-            specs << [target, operand.downcase, negate]
+            if !quoted && operand =~ /\A-?(?:is|has):\S+\z/i
+              # First-class message-state specs (is:unread, has:attachment).
+              # The app has no state vocabulary to mirror (its A modifier
+              # searches attachment FILENAMES), so the familiar Gmail
+              # spellings are native syntax here. `-` negates too — the form
+              # Gmail callers actually write.
+              negate ||= operand.start_with?("-")
+              specs << [:state, operand.delete_prefix("-").downcase, negate]
+            else
+              # A bare term opening an or-group inherits the modifier in
+              # force (`d 2024 or 2025`). Elsewhere it is MailMate's
+              # "Common" specifier — common headers OR body — matching the
+              # UI quicksearch behavior. Pass --headers-only to skip the
+              # body scan when speed matters.
+              target = (i.zero? && !quoted && in_force) ? in_force : :message_or_body
+              specs << [target, operand.downcase, negate]
+            end
             i += 1
           end
         end
@@ -415,10 +426,25 @@ module Mailmate
       SPEC_COST = {
         date: 0,
         from: 1, recipients: 1, cc: 1, subject: 1, address_any: 1, any: 1,
-        tag: 1, keyword: 1,
+        tag: 1, keyword: 1, state: 1,
         body: 2, message_or_body: 2,
       }.freeze
 
+      # Canonical state names for is:/has: specs, including the spellings
+      # Gmail callers actually use. Values map to a #flags IMAP flag except
+      # :unread (absence of \Seen) and :attachment (root MIME layout).
+      STATE_CANON = {
+        "unread" => :unread, "read" => :read,
+        "flagged" => :flagged, "starred" => :flagged,
+        "replied" => :replied, "answered" => :replied,
+        "draft" => :draft,
+        "attachment" => :attachment, "attachments" => :attachment,
+      }.freeze
+
+      STATE_FLAGS = {
+        read: "\\Seen", flagged: "\\Flagged", replied: "\\Answered", draft: "\\Draft",
+      }.freeze
+
       # Evaluate cheap, selective specs before expensive ones, within each
       # or-group. Specs in a group combine with AND (order-independent), and
       # matches? short-circuits on the first miss — so `b invoice d 7d`
@@ -559,6 +585,13 @@ module Mailmate
       def date_spec_error(specs)
         day_terms, hour_terms = [], []
         specs.each do |field, term, negate|
+          # State specs validate here too (same pre-pass, same
+          # silent-nothing failure being prevented): an unknown state value
+          # would otherwise quietly match no message ever.
+          if field == :state && !STATE_CANON.key?(term.split(":", 2).last)
+            return "state term cannot match anything: #{term} " \
+                   "(known: is:unread is:read is:flagged is:replied is:draft has:attachment)"
+          end
           next unless field == :date
           range = hour_range_for(term) || date_range_for(term)
           if range.nil? || range[0] > range[1]
@@ -751,6 +784,35 @@ module Mailmate
         flags.reject { |f| f.start_with?("\\", "$") }.join(" ").downcase
       end
 
+      # term is the full lowercased token ("is:unread", "has:attachment").
+      # Flag states read the #flags index; attachment presence reads the
+      # indexed root content-type — multipart/mixed is the standard
+      # attachment layout (a Mail fallback checks real attachments when the
+      # message is already loaded). Unknown state values never reach here:
+      # date_spec_error rejects them up front.
+      def state_matches?(eml_id, mail, term)
+        state = STATE_CANON[term.split(":", 2).last]
+        return false unless state
+
+        case state
+        when :unread
+          eml_id ? !message_flags(eml_id).include?("\\Seen") : false
+        when :attachment
+          ct = eml_id ? (reader_for("content-type")&.value_for(eml_id.to_i) rescue nil).to_s : ""
+          return ct.downcase.include?("multipart/mixed") unless ct.empty?
+          mail ? mail.attachments.any? : false
+        else
+          message_flags(eml_id).include?(STATE_FLAGS[state])
+        end
+      end
+
+      def message_flags(eml_id)
+        return [] unless eml_id
+        reader_for("#flags")&.flags_for(eml_id.to_i) || []
+      rescue StandardError
+        []
+      end
+
       def text_body(mail)
         (mail.text_part&.decoded || mail.body.decoded).to_s.force_encoding("UTF-8").scrub.downcase
       rescue StandardError
@@ -843,6 +905,8 @@ module Mailmate
                 common || (!headers_only && body_matches?(eml_id, mail, path, term, term_b, index_only: index_only, exclude_quoted: exclude_quoted))
               when :date
                 date_matches?(mail, eml_id, term)
+              when :state
+                state_matches?(eml_id, mail, term)
               when :any
                 %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
               end

data/lib/mailmate/cli/send.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../reply_prefill"
 
 module Mailmate
   module CLI
@@ -19,26 +20,25 @@ module Mailmate
         Body is read from stdin. All other flags pass through to emate (its help follows).
 
         Replies and threading
-          MailMate auto-generates the outgoing Message-ID — never your job.
-          In-Reply-To and References are PURE PASS-THROUGH: whatever you set via
-          `--header` ships verbatim; what you don't set is absent (and recipients'
-          clients will see the message as a fresh thread, no matter how `Re:` the
-          subject looks). To make a reply land in-thread, pass both:
+          A `Re:` subject alone does NOT thread — modern clients thread on headers.
+          MailMate generates the outgoing Message-ID; never your job.
 
-            mm-send -f you@x -t them@y -s "Re: foo" \\
-              --header "In-Reply-To: <parent-message-id@domain>" \\
-              --header "References: <root-mid> <parent-mid>" \\
-              --send-now <<<"body"
+            mm-send -f you@x --reply-to "<parent-mid@domain>" --send-now <<<"body"
 
-          References is constructed as the source message's References header (if
-          any) with the source's Message-ID appended. If the source is a thread
-          root with no References, just use its Message-ID alone.
+          derives In-Reply-To, References, recipients and subject from the parent.
+          --reply-all-to replies to all; --forward forwards. Fields you pass
+          explicitly win; fields you omit follow normal reply rules. --header
+          stays available as the escape hatch when the parent isn't indexed.
 
         Identity selection
           `-f <address>` picks which of MailMate's configured identities sends.
           Without `-f`, MailMate uses its default identity. See `mmdiscover` to
           list available addresses.
 
+        Full rules — threading chain, merge rule, header safety:
+          docs/Composing and threading.md (shipped with the gem), or
+          https://github.com/brianmd/mailmate/blob/main/docs/
+
         ──────────────────────────── emate help follows ────────────────────────────
 
       PREAMBLE
@@ -58,16 +58,29 @@ module Mailmate
       # through the `$stdout`/`$stderr` globals so the MCP's capture sees it
       # instead of the protocol stream getting corrupted.
       def run(argv)
+        help = argv.include?("--help") || argv.include?("-h")
+
+        # Our own flags are peeled off BEFORE the platform/emate checks so
+        # `--print-prefill` works as a pure query — markdownr calls it to fill
+        # a form and has no business requiring a launchable MailMate.
+        begin
+          argv, derived = apply_parent!(argv, help: help)
+        rescue Mailmate::ReplyPrefill::NotFound, ArgumentError => e
+          warn "mm-send: #{e.message}"
+          return 1
+        end
+        return print_prefill(derived) if derived && derived[:print_only]
+
         Mailmate::PlatformError.check_darwin!(component: "mm-send")
         unless File.executable?(EMATE_PATH)
           warn "mm-send: emate not found at #{EMATE_PATH}. Is MailMate installed?"
           return 1
         end
-        help = argv.include?("--help") || argv.include?("-h")
         warn PREAMBLE if help
         # --help never reads a body; consuming stdin here would hang an
         # interactive `mm-send --help` waiting for Ctrl-D.
         body = help ? "" : $stdin.read.to_s
+        body = append_quote(body, derived) if derived
         out, err, status = Open3.capture3(EMATE_PATH, "mailto", "--markup", "markdown", *argv, stdin_data: body)
         $stdout.write(out)
         $stderr.write(err)
@@ -75,6 +88,110 @@ module Mailmate
         # `exit run(ARGV)`, which needs an Integer.
         status.exitstatus || 1
       end
+
+      # Flags this wrapper consumes itself. Everything else in argv is emate's
+      # and passes through untouched — that pass-through is the design, so the
+      # scan below is deliberately literal rather than an OptionParser (which
+      # would have to be taught every emate flag in order to ignore them).
+      PARENT_FLAGS = { "--reply-to" => "reply", "--reply-all-to" => "reply-all", "--forward" => "forward" }.freeze
+
+      # Returns [argv_for_emate, derived_or_nil]. When a parent flag is
+      # present, derives the reply fields and splices them in as emate flags —
+      # but only for fields the caller did NOT pass. Explicit always wins; see
+      # the merge rule in docs/Composing and threading.md.
+      def apply_parent!(argv, help: false)
+        rest, parent, mode, print_only, quote = extract_flags(argv)
+        return [rest, nil] if parent.nil?
+
+        # --print-prefill is a query, so it answers even under --help; the
+        # send path would otherwise be unreachable for a caller inspecting it.
+        prefill = Mailmate::ReplyPrefill.build(parent, mode: mode)
+        derived = { prefill: prefill, print_only: print_only, quote: quote }
+        return [rest, derived] if print_only || help
+
+        [splice(rest, prefill), derived]
+      end
+
+      def extract_flags(argv)
+        rest = []
+        parent = mode = nil
+        print_only = false
+        quote = true
+        i = 0
+        while i < argv.length
+          arg = argv[i]
+          if PARENT_FLAGS.key?(arg)
+            raise ArgumentError, "#{arg} needs a message id" if argv[i + 1].nil?
+            raise ArgumentError, "pass only one of #{PARENT_FLAGS.keys.join(', ')}" if parent
+
+            mode = PARENT_FLAGS[arg]
+            parent = argv[i + 1]
+            i += 2
+          elsif arg == "--print-prefill"
+            print_only = true
+            i += 1
+          elsif arg == "--no-quote"
+            quote = false
+            i += 1
+          else
+            rest << arg
+            i += 1
+          end
+        end
+        raise ArgumentError, "--print-prefill needs one of #{PARENT_FLAGS.keys.join(', ')}" if print_only && parent.nil?
+
+        [rest, parent, mode, print_only, quote]
+      end
+
+      # Add derived values ONLY where the caller was silent. `passed?` looks
+      # for the flag itself, so `-t a@x --reply-to <id>` keeps a@x and still
+      # threads — overriding a visible field must never drop the headers.
+      def splice(argv, prefill)
+        out = argv.dup
+        out.push("-f", prefill.from) if prefill.from && !passed?(argv, %w[-f --from])
+        unless passed?(argv, %w[-t --to])
+          prefill.to.each { |a| out.push("-t", a) }
+        end
+        unless passed?(argv, %w[-c --cc])
+          prefill.cc.each { |a| out.push("-c", a) }
+        end
+        out.push("-s", prefill.subject) if prefill.subject && !passed?(argv, %w[-s --subject])
+        # Threading headers are NOT subject to the merge rule's "explicit
+        # wins" in the usual sense — a caller who passes their own
+        # --header "In-Reply-To: …" alongside --reply-to gets both, which is
+        # a duplicate header. Skip ours when they've hand-set either one.
+        out.push("--header", "In-Reply-To: #{prefill.in_reply_to}") if prefill.in_reply_to && !header_passed?(argv, "in-reply-to")
+        out.push("--header", "References: #{prefill.references}")   if prefill.references && !header_passed?(argv, "references")
+        out
+      end
+
+      def passed?(argv, flags)
+        argv.any? { |a| flags.include?(a) || flags.any? { |f| f.start_with?("--") && a.start_with?("#{f}=") } }
+      end
+
+      def header_passed?(argv, name)
+        argv.each_with_index.any? do |a, i|
+          (a == "--header" && argv[i + 1].to_s.downcase.start_with?("#{name}:")) ||
+            (a.start_with?("--header=") && a.split("=", 2).last.to_s.downcase.start_with?("#{name}:"))
+        end
+      end
+
+      # Reply rules seed the body with the quoted original BELOW whatever the
+      # caller wrote, matching what a mail client's Reply button produces.
+      def append_quote(body, derived)
+        return body unless derived[:quote]
+
+        quote = derived[:prefill].quoted_body.to_s
+        return body if quote.strip.empty?
+
+        "#{body.to_s.sub(/\n+\z/, '')}\n\n#{quote}"
+      end
+
+      def print_prefill(derived)
+        require "json"
+        $stdout.puts JSON.pretty_generate(derived[:prefill].to_h)
+        0
+      end
     end
   end
 end

data/lib/mailmate/cli/version_flag.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../version"
+
+module Mailmate
+  module CLI
+    # `--version` / `-V`, handled uniformly by every exe shim.
+    #
+    # This exists so a CONSUMER can tell how old an installed mailmate is
+    # without parsing help text or probing for a flag's side effects. That
+    # matters because the CLIs are deliberately pass-through: an older
+    # `mm-send` handed a flag it doesn't know forwards it to `emate` rather
+    # than rejecting it, so "did this flag work?" is not a safe capability
+    # probe — it can open a composer window instead of erroring. A version
+    # string is the honest check.
+    #
+    # Every shim calls this before dispatching, so the answer is available
+    # even from commands whose real work needs macOS or a running MailMate.
+    # test_exe_shims.rb asserts the coverage is total; a new shim that skips
+    # the call fails that test rather than silently becoming the one command
+    # that can't be version-probed.
+    module VersionFlag
+      extend self
+
+      FLAGS = %w[--version -V].freeze
+
+      # Prints "<name> (mailmate X.Y.Z)" and exits 0 when the flag is present.
+      # Returns nil otherwise, so shims can call it unconditionally.
+      def handle!(argv, name)
+        return unless argv.any? { |a| FLAGS.include?(a) }
+
+        $stdout.puts "#{name} (mailmate #{Mailmate::VERSION})"
+        exit 0
+      end
+    end
+  end
+end

data/lib/mailmate/header_value.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # Sanitize a value destined for an `emate --header "Name: value"` flag.
+  #
+  # Header values ship VERBATIM into the outgoing message, and the values we
+  # inject most often (`In-Reply-To`, `References`) are derived from ANOTHER
+  # message — i.e. from input nobody in this process authored. A value
+  # carrying CR/LF would end the header and begin a new one, smuggling
+  # arbitrary RFC 5322 headers (a `Bcc:`, say) into mail the caller believes
+  # they fully specified.
+  #
+  # Every path that builds a `--header` flag must run its value through here.
+  # There is deliberately ONE implementation: this logic previously existed in
+  # two places (the MCP server's argv builder and markdownr's), and only one of
+  # them had the defense — which is exactly the failure mode a shared helper
+  # exists to prevent.
+  module HeaderValue
+    extend self
+
+    # Collapse any CR/LF (and the whitespace that follows it, so an unfolded
+    # continuation doesn't leave a ragged double space) to a single space,
+    # then trim. Returns a String; nil/empty in → "" out.
+    def sanitize(value)
+      value.to_s.gsub(/[\r\n]+\s*/, " ").strip
+    end
+
+    # Wrap a Message-ID in angle brackets unless it already has them. Both
+    # forms are valid input; the on-wire form is bracketed per RFC 5322.
+    # Sanitizes first, so a smuggled newline can't survive by hiding inside
+    # what looks like an already-bracketed id.
+    def bracket_message_id(id)
+      s = sanitize(id)
+      return s if s.empty?
+      return s if s.start_with?("<") && s.end_with?(">")
+
+      "<#{s}>"
+    end
+  end
+end

data/lib/mailmate/mcp.rb

@@ -51,9 +51,18 @@ module Mailmate
       - Prefer `draft` over `send` whenever the user said "don't send" / "just
         draft it" — `draft` physically cannot send, so it's the safe choice.
         `send` also opens a draft and waits unless you pass `send_now: true`.
-      - Threading: set BOTH `in_reply_to` and `references`. A "Re:" subject
-        alone does not thread in modern clients. MailMate generates the
-        outgoing Message-ID itself.
+      - Replying: pass `reply_to` (the parent's eml-id or Message-ID) and the
+        threading headers, recipient and "Re:" subject are derived for you.
+        `reply_all_to` replies to all; `forward` forwards (supply `to`).
+        Fields you also pass explicitly win; ones you omit follow normal
+        reply rules. Prefer this over hand-setting in_reply_to/references —
+        a mis-built References chain sends fine and simply doesn't thread,
+        and nothing in your own view reveals it. A "Re:" subject alone never
+        threads. MailMate generates the outgoing Message-ID itself.
+        Full rules — the References chain, the merge rule, header safety —
+        are in the gem's docs/Composing and threading.md
+        (github.com/brianmd/mailmate), which is canonical; this summary
+        exists only so you need not follow a link mid-call.
 
       Modifying (modify)
       - Drives MailMate's UI via AppleScript: it briefly takes focus, calls are
@@ -80,13 +89,13 @@ module Mailmate
           Search MailMate's .eml files using MailMate's quicksearch syntax.
           Returns column-aligned CSV. Same engine as the `mmsearch` CLI.
 
-          There is NO native key:value form — write quicksearch directly using
-          the modifiers below. Familiar foreign tokens (`from:bob`,
-          `date:today`, `after:2026-08-01`, `older_than:2w`) are auto-translated
-          to quicksearch, and the rewrite is announced in the result — that
-          announcement means your query was translated, not that it failed.
-          Unrecognized keys (`is:unread`, `has:attachment`) are searched as
-          literal text and match nothing, silently.
+          The only native key:value specs are the state forms below
+          (is:unread, has:attachment). Other familiar foreign tokens
+          (`from:bob`, `date:today`, `after:2026-08-01`, `older_than:2w`) are
+          auto-translated to quicksearch, and the rewrite is announced in the
+          result — that announcement means your query was translated, not
+          that it failed. Unrecognized keys (`in:inbox`, `filename:pdf`) are
+          searched as literal text and match nothing, silently.
 
           #{Mailmate::SearchSyntax.reference(indent: "  ")}
 
@@ -237,11 +246,15 @@ module Mailmate
             subject: { type: "string", description: "Subject line." },
             body: { type: "string", description: "Markdown body." },
             attachments: { type: "array", items: { type: "string" }, description: "Absolute paths to files to attach." },
+            reply_to: { type: "string", description: "Parent message to reply to — eml-id or RFC Message-ID. PREFER THIS over setting in_reply_to/references by hand: it derives In-Reply-To, the full References chain, the recipient and a \"Re:\" subject from the parent. Fields you also pass explicitly win; ones you omit follow normal reply rules." },
+            reply_all_to: { type: "string", description: "Same as reply_to but replies to all — adds the other recipients, minus the user own identities." },
+            forward: { type: "string", description: "Parent message to forward — eml-id or RFC Message-ID. Derives a \"Fwd:\" subject and the forwarded block; you supply `to`. A forward deliberately does NOT thread into the original conversation." },
+            quote: { type: "boolean", description: "Include the quoted original when replying/forwarding (default true). Set false to send only your own text." },
             in_reply_to: { type: "string", description: "Message-ID of the parent message (with or without angle brackets). Sets the In-Reply-To header on the outgoing message so recipients' clients thread it correctly." },
             references: { type: "string", description: "Space-separated chain of Message-IDs (with angle brackets). Conventionally: parent's References header + parent's Message-ID. Required alongside in_reply_to for clean threading in deep chains." },
             send_now: { type: "boolean", description: "Send immediately (skip the Drafts pause)." },
           },
-          required: %w[to subject body],
+          required: %w[body],
           additionalProperties: false,
         },
       },
@@ -260,10 +273,14 @@ module Mailmate
             subject: { type: "string", description: "Subject line." },
             body: { type: "string", description: "Markdown body." },
             attachments: { type: "array", items: { type: "string" }, description: "Absolute paths to files to attach." },
+            reply_to: { type: "string", description: "Parent message to reply to — eml-id or RFC Message-ID. PREFER THIS over setting in_reply_to/references by hand: it derives In-Reply-To, the full References chain, the recipient and a \"Re:\" subject from the parent. Fields you also pass explicitly win; ones you omit follow normal reply rules." },
+            reply_all_to: { type: "string", description: "Same as reply_to but replies to all — adds the other recipients, minus the user own identities." },
+            forward: { type: "string", description: "Parent message to forward — eml-id or RFC Message-ID. Derives a \"Fwd:\" subject and the forwarded block; you supply `to`. A forward deliberately does NOT thread into the original conversation." },
+            quote: { type: "boolean", description: "Include the quoted original when replying/forwarding (default true). Set false to send only your own text." },
             in_reply_to: { type: "string", description: "Message-ID of the parent message (with or without angle brackets). Sets the In-Reply-To header so recipients' clients thread it correctly." },
             references: { type: "string", description: "Space-separated chain of Message-IDs (with angle brackets). Conventionally: parent's References header + parent's Message-ID. Required alongside in_reply_to for clean threading in deep chains." },
           },
-          required: %w[to subject body],
+          required: %w[body],
           additionalProperties: false,
         },
       },
@@ -454,7 +471,21 @@ module Mailmate
       with_stdin(payload) { run_cli(Mailmate::CLI::Verify, argv) }
     end
 
+    # `to` and `subject` used to be schema-required, which stopped working the
+    # moment a parent could supply them. JSON Schema can't say "required
+    # unless another field is present", so the check moved here — dropping it
+    # entirely would let a `to`-less call through to open an empty composer.
+    def recipient_check(args)
+      return nil if args["to"] || args["reply_to"] || args["reply_all_to"]
+      return nil if args["forward"] && args["to"]
+
+      text_error("no recipient: pass `to`, or `reply_to`/`reply_all_to` to derive it from the parent. " \
+                 "(`forward` derives the subject and body but not the recipient — pass `to` with it.)")
+    end
+
     def call_send(args)
+      (err = recipient_check(args)) and return err
+
       argv = compose_argv(args)
       argv << "--send-now" if args["send_now"]
       with_stdin(args["body"].to_s) { run_cli(Mailmate::CLI::Send, argv) }
@@ -463,6 +494,8 @@ module Mailmate
     # `draft` mirrors `send` but never sends — it has no send_now option and
     # routes through CLI::Draft, which refuses `--send-now` outright.
     def call_draft(args)
+      (err = recipient_check(args)) and return err
+
       argv = compose_argv(args)
       with_stdin(args["body"].to_s) { run_cli(Mailmate::CLI::Draft, argv) }
     end
@@ -476,21 +509,28 @@ module Mailmate
       argv.push("-c", args["cc"].to_s)      if args["cc"]
       argv.push("-b", args["bcc"].to_s)     if args["bcc"]
       argv.push("-s", args["subject"].to_s) if args["subject"]
-      argv.push("--header", "In-Reply-To: #{bracket_mid(args["in_reply_to"])}") if args["in_reply_to"]
-      argv.push("--header", "References: #{args["references"]}")                if args["references"]
+      # Both values come from ANOTHER message, so both go through the shared
+      # sanitizer — see Mailmate::HeaderValue for why this is not open-coded.
+      argv.push("--header", "In-Reply-To: #{Mailmate::HeaderValue.bracket_message_id(args["in_reply_to"])}") if args["in_reply_to"]
+      argv.push("--header", "References: #{Mailmate::HeaderValue.sanitize(args["references"])}")             if args["references"]
+      # Parent-derived compose: hand the id to the CLI rather than deriving
+      # here. `reply_to` is what a caller should reach for over hand-setting
+      # in_reply_to/references — it builds the References chain from the
+      # parent, the step that is easy to get subtly wrong and impossible to
+      # notice afterwards (a mis-built chain sends fine and simply doesn't
+      # thread).
+      if (parent = args["reply_to"] || args["reply_all_to"] || args["forward"])
+        flag = if args["forward"] then "--forward"
+               elsif args["reply_all_to"] then "--reply-all-to"
+               else "--reply-to"
+               end
+        argv.push(flag, parent.to_s)
+        argv << "--no-quote" if args["quote"] == false
+      end
       Array(args["attachments"]).each { |p| argv << p.to_s }
       argv
     end
 
-    # Wrap a bare Message-ID in `<…>` if it doesn't already have them. Both
-    # forms are valid input to the MCP for ergonomics; the header value
-    # going on the wire needs the brackets per RFC 5322.
-    def bracket_mid(id)
-      s = id.to_s.strip
-      return s if s.start_with?("<") && s.end_with?(">")
-      "<#{s}>"
-    end
-
     def call_open(args)
       argv = [args["id"].to_s]
       argv << "--print" if args["print_only"]

data/lib/mailmate/reply_prefill.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "header_value"
+
+module Mailmate
+  # @api public
+  #
+  # Derive the fields of a reply / reply-all / forward from a parent message:
+  # recipients, subject, threading headers, and the quoted original.
+  #
+  # This is the ONE place the References chain is constructed. It is exposed as
+  # a library call (not just a CLI behavior) because consumers need the pieces
+  # WITHOUT sending — markdownr's compose popup fills a form from them, and
+  # `mm-send --reply-to` turns them into emate flags. Two implementations of
+  # "parent's References + parent's Message-ID" is how one of them silently
+  # stops threading; there is only this one.
+  #
+  # Rules it encodes (canonical prose: docs/Composing and threading.md):
+  #   * In-Reply-To = the parent's Message-ID.
+  #   * References  = the parent's References (if any) + the parent's
+  #     Message-ID appended; the bare Message-ID when the parent is a root.
+  #   * A forward does NOT thread. It is a new conversation sent to someone who
+  #     was not party to the original, so injecting the original's chain would
+  #     graft a stranger into a thread they can't see. Forward derives the
+  #     subject and the quoted original only.
+  module ReplyPrefill
+    extend self
+
+    MODES = %w[reply reply-all forward].freeze
+
+    class NotFound < StandardError; end
+
+    Prefill = Struct.new(
+      :mode, :from, :to, :cc, :subject, :in_reply_to, :references, :quoted_body,
+      :parent_message_id, :parent_eml_id,
+      keyword_init: true
+    ) do
+      def to_h
+        super.transform_keys(&:to_s)
+      end
+    end
+
+    # `input` is an eml-id or an RFC Message-ID (bracketed or not) — anything
+    # EmlLookup.resolve_id accepts. `identities` defaults to the configured
+    # list; pass an explicit array to override (markdownr passes what
+    # mmdiscover reported, which may be broader than config.yml).
+    def build(input, mode: "reply", identities: nil)
+      mode = mode.to_s
+      raise ArgumentError, "mode must be one of: #{MODES.join(', ')}" unless MODES.include?(mode)
+
+      mail, eml_id = load_parent(input)
+      idents = normalize_identities(identities)
+
+      message_id = HeaderValue.bracket_message_id(mail.message_id)
+      threading  = mode == "forward" ? { in_reply_to: nil, references: nil } : {
+        in_reply_to: presence(message_id),
+        references: build_references(mail, message_id)
+      }
+
+      Prefill.new(
+        mode: mode,
+        from: pick_from_identity(mail, idents),
+        to: derive_to(mail, mode),
+        cc: derive_cc(mail, mode, idents),
+        subject: derive_subject(mail, mode),
+        quoted_body: derive_quoted_body(mail, mode),
+        parent_message_id: presence(message_id),
+        parent_eml_id: eml_id,
+        **threading
+      )
+    end
+
+    private
+
+    def load_parent(input)
+      eml_id = Mailmate::EmlLookup.resolve_id(input)
+      raise NotFound, "couldn't resolve #{input.inspect} as an eml-id or Message-ID" if eml_id.nil? || eml_id.zero?
+
+      path = Mailmate::EmlLookup.path_for(eml_id)
+      raise NotFound, "no .eml on disk for eml-id #{eml_id}" unless path
+
+      require "mail"
+      [Mail.read(path), eml_id]
+    end
+
+    # References = parent's own chain + parent's Message-ID. A parent that is
+    # itself a thread root has no References, so the chain is just its id.
+    def build_references(mail, message_id)
+      old = HeaderValue.sanitize(mail["references"]&.value)
+      presence(old.empty? ? message_id : "#{old} #{message_id}".strip)
+    end
+
+    # Reply goes to Reply-To when the sender set one, else From. A forward has
+    # no derivable recipient — that's the caller's whole reason for forwarding.
+    def derive_to(mail, mode)
+      return [] if mode == "forward"
+
+      reply_to = addresses(mail.reply_to).first
+      [reply_to || addresses(mail.from).first].compact
+    end
+
+    # Reply-all carries the other recipients, minus every address of ours (so
+    # switching identity can't leave us Cc'ing ourselves) and minus whoever
+    # already landed in To.
+    def derive_cc(mail, mode, idents)
+      return [] unless mode == "reply-all"
+
+      to_lc = derive_to(mail, mode).map(&:downcase)
+      (addresses(mail.to) + addresses(mail.cc))
+        .reject { |a| idents.include?(a.downcase) || to_lc.include?(a.downcase) }
+        .uniq
+    end
+
+    def derive_subject(mail, mode)
+      subject = mail.subject.to_s.strip
+      mode == "forward" ? ensure_prefix(subject, "Fwd", /\Afwd?\s*:/i) : ensure_prefix(subject, "Re", /\Are\s*(?:\[\d+\])?\s*:/i)
+    end
+
+    # Conservative: never double-prefix, and leave an existing prefix in
+    # whatever case/shape the sender used (`RE:`, `Re[2]:`) alone.
+    def ensure_prefix(subject, word, already)
+      return "#{word}: " if subject.empty?
+      return subject if subject.match?(already)
+
+      "#{word}: #{subject}"
+    end
+
+    # Whichever of OUR addresses the parent was addressed to — so a reply goes
+    # out from the identity that received it, not from whatever MailMate
+    # defaults to. nil when we can't tell; the caller decides the fallback.
+    def pick_from_identity(mail, idents)
+      return nil if idents.empty?
+
+      candidates = addresses(mail.to) + addresses(mail.cc) + addresses(mail.bcc)
+      candidates.find { |a| idents.include?(a.downcase) }
+    end
+
+    # Reply: email-classic "On <date>, <sender> wrote:" + a `> `-prefixed body.
+    # Forward: the conventional un-prefixed forwarded-message block with its
+    # own header summary, since the recipient has never seen the original.
+    def derive_quoted_body(mail, mode)
+      body = plain_body(mail)
+      from = presence(mail["from"]&.value.to_s.strip) || "(unknown sender)"
+      date = mail["date"]&.value.to_s.strip
+
+      if mode == "forward"
+        header = ["---------- Forwarded message ----------",
+                  "From: #{from}",
+                  ("Date: #{date}" unless date.empty?),
+                  "Subject: #{mail.subject.to_s.strip}",
+                  ("To: #{mail['to'].value}" if mail["to"])].compact.join("\n")
+        return "#{header}\n\n#{body}"
+      end
+
+      attribution = date.empty? ? "#{from} wrote:" : "On #{date}, #{from} wrote:"
+      return "#{attribution}\n> [no plain-text alternative — paste the original manually]\n" if body.strip.empty?
+
+      quoted = body.sub(/\n+\z/, "").split("\n", -1).map { |l| "> #{l}".rstrip }.join("\n")
+      "#{attribution}\n#{quoted}\n"
+    end
+
+    # The text/plain alternative, or "" when the message is HTML-only. We do
+    # NOT synthesize text from the HTML part here: a lossy auto-conversion
+    # quoted back to the original sender is worse than an honest placeholder.
+    def plain_body(mail)
+      part = mail.multipart? ? mail.text_part : mail
+      return "" if part.nil?
+      return "" if part.respond_to?(:mime_type) && part.mime_type && part.mime_type != "text/plain"
+
+      part.body.decoded.to_s
+    rescue StandardError
+      ""
+    end
+
+    # Mail's address fields raise on malformed input often enough that a reply
+    # to a slightly-broken message shouldn't blow up the whole derivation.
+    def addresses(field)
+      Array(field).map { |a| a.to_s.strip }.reject(&:empty?)
+    rescue StandardError
+      []
+    end
+
+    def normalize_identities(identities)
+      list = identities.nil? ? Mailmate::Identity.list : Array(identities)
+      list.map { |a| a.to_s.downcase.strip }.reject(&:empty?)
+    end
+
+    def presence(str)
+      s = str.to_s.strip
+      s.empty? ? nil : s
+    end
+  end
+end

data/lib/mailmate/search_syntax.rb

@@ -26,6 +26,8 @@ module Mailmate
       ["m <term>", "common headers OR body (same as a bare term)"],
       ["d <date>", "received: Nh (rolling clock hours), Nd|Nw|Nm|Ny (N calendar units ending today; 1d = today), or Y, Y-M, Y-M-D"],
       ["T <tag>",  "tag / IMAP keyword contains (K is a synonym)"],
+      ["is:<state>", "message state: unread, read, flagged, replied, draft"],
+      ["has:attachment", "root MIME is multipart/mixed (the standard attachment layout)"],
     ].freeze
 
     EXAMPLES = [
@@ -37,6 +39,7 @@ module Mailmate
       ["d 24h",                   "received in the last 24 hours (rolling, not calendar)"],
       ["d >=2026-05 d <2026-08",  "received May through July 2026"],
       ["d 1h or 2026-08-09",      "last hour, plus everything from Aug 9"],
+      ["is:unread d 7d",          "unread, received in the last 7 days"],
       ["T urgent",                "tagged 'urgent'"],
     ].freeze
 
@@ -59,11 +62,13 @@ module Mailmate
     # matches nothing. That silence is the whole problem this list exists to
     # break: an agent or a person gets an empty result set that is
     # indistinguishable from "your mail really has nothing", and believes it.
+    # NOTE: is/has are absent — they are first-class quicksearch now
+    # (is:unread, has:attachment parse as native state specs).
     FOREIGN_KEYS = %w[
       after before older newer older_than newer_than on since until
       date sent received time
       from to cc bcc subject body
-      is has in label folder mailbox category filename
+      in label folder mailbox category filename
     ].freeze
 
     # Spec placeholders for the zero-result hint, for foreign keys whose value

data/lib/mailmate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailmate
-  VERSION = "1.7.0"
+  VERSION = "1.8.0"
 end

data/lib/mailmate.rb

@@ -12,6 +12,8 @@
 #   Mailmate::PartLookup.body_parts_of(envelope_id) → child body-part-ids of an envelope
 #   Mailmate::EmlLookup.path_for(eml_id)       → eml-id → absolute path
 #   Mailmate::HeaderReader.header(path, name)  → read one header from an .eml
+#   Mailmate::HeaderValue.sanitize(v)          → CR/LF-safe --header value (ALL header paths use this)
+#   Mailmate::ReplyPrefill.build(id, mode:)    → reply/reply-all/forward fields from a parent
 #   Mailmate::MidUrl.for(message_id)           → build a mid:%3C...%3E URL
 #   Mailmate::DuplicateScanner.duplicates      → Hash{Message-ID => Array<eml_id>}
 #   Mailmate::AppleScriptDriver.new(...)       → drive MailMate via AppleScript
@@ -35,6 +37,8 @@ require_relative "mailmate/identity"
 require_relative "mailmate/header_reader"
 require_relative "mailmate/mid_url"
 require_relative "mailmate/eml_lookup"
+require_relative "mailmate/header_value"
+require_relative "mailmate/reply_prefill"
 require_relative "mailmate/duplicate_scanner"
 require_relative "mailmate/applescript_driver"
 require_relative "mailmate/ast"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailmate
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Brian Murphy-Dye
@@ -110,6 +110,7 @@ files:
 - LICENSE.txt
 - README.md
 - config.yml.example
+- docs/Composing and threading.md
 - exe/mailmate-mcp
 - exe/mm-draft
 - exe/mm-mailboxes
@@ -135,6 +136,7 @@ files:
 - lib/mailmate/cli/send.rb
 - lib/mailmate/cli/tags.rb
 - lib/mailmate/cli/verify.rb
+- lib/mailmate/cli/version_flag.rb
 - lib/mailmate/config.rb
 - lib/mailmate/duplicate_scanner.rb
 - lib/mailmate/eml_lookup.rb
@@ -142,6 +144,7 @@ files:
 - lib/mailmate/filter_classifier.rb
 - lib/mailmate/flag_check.rb
 - lib/mailmate/header_reader.rb
+- lib/mailmate/header_value.rb
 - lib/mailmate/identity.rb
 - lib/mailmate/index_reader.rb
 - lib/mailmate/lexer.rb
@@ -153,13 +156,18 @@ files:
 - lib/mailmate/parser.rb
 - lib/mailmate/part_lookup.rb
 - lib/mailmate/platform_error.rb
+- lib/mailmate/reply_prefill.rb
 - lib/mailmate/search_syntax.rb
 - lib/mailmate/source_resolver.rb
 - lib/mailmate/var_resolver.rb
 - lib/mailmate/version.rb
+homepage: https://github.com/brianmd/mailmate
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/brianmd/mailmate
+  bug_tracker_uri: https://github.com/brianmd/mailmate/issues
+  documentation_uri: https://github.com/brianmd/mailmate#readme
 rdoc_options: []
 require_paths:
 - lib