mailmate 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b395d407ecab6e32e9e9d94da136031b0edd5cfa0302809721940a0dcefa2ba7
-  data.tar.gz: 80d7dc99046e899093e57422153e1b413f7688b5e1d080aa9ae7898778b92136
+  metadata.gz: 81aeb9b0f5abd70325c74329db580be4134b27eee50b03f6caef5958b653f288
+  data.tar.gz: c614a5dcc2e4fb2bd6fa797e09d1e959a1ecbf9c26ae7c6a21b0e26899c6a32e
 SHA512:
-  metadata.gz: 55136934383ab2be45fec5c5787242594a33208b6d71bffedf0b0ee4a0e1176f5876b4b09611c9716afcf34e6d7132a687e6c907a27f586b9a89f5ef7c9e4da1
-  data.tar.gz: 481da51efb264b36587908af1ab321d5f63c2174a3f2502be5722bb45600243433c210e30ad869737e531a8d4bffa97ffd371835265346c27dfef177d74ff24f
+  metadata.gz: 9c27e9400d40047291b3486e6895b47f8e8855985bb74bfe75de2a338c5c5d59356b92d330ad93186828e3aa579f9c6273602432a77f2dbc383b3e7afdfb02aa
+  data.tar.gz: c3d898edeb7fe251c9f816dc333014e915bcb8b1e4d63e503a52192b22ca6353bf5657109688c36a71af04060cda6fc816a95c3b680b526382f8afc47e63851c

data/README.md

@@ -60,6 +60,16 @@ This repo doubles as a Claude Code plugin marketplace. Inside Claude Code:
 
 The plugin's MCP server self-provisions on first launch — Ruby (if needed) and gem dependencies go into `~/.mailmate-mcp`; nothing touches your system Ruby, Homebrew, or shell profile. It runs the plugin's bundled source, so plugin updates take effect without waiting for a gem release. Uninstall: `/plugin uninstall mailmate`, then `rm -rf ~/.mailmate-mcp`.
 
+### Claude Cowork (desktop app)
+
+The same plugin works in Cowork on the macOS desktop app — verified end to end, including a from-scratch first run:
+
+1. In Cowork: **Customize → Plugins → + → Add marketplace** → `brianmd/mailmate`, then install **mailmate** from the Discover tab.
+2. Ask Claude about your mail. The first launch provisions the runtime inside Cowork's sandbox, which can take a minute or two, and Cowork will ask you to **allow the connector's commands and file access** — those approvals are the gate to your local mail store.
+3. The Claude desktop app must be running on the Mac where MailMate lives; `send`, `draft`, `modify`, and `open` additionally need the MailMate app running (as always).
+
+Cowork runs the connector through the desktop app's sandboxed bridge, so its provisioning leaves nothing on your real filesystem — not even `~/.mailmate-mcp` (only the Claude Code path creates that directory).
+
 ### One-line installer (any MCP client)
 
 ```bash
@@ -163,7 +173,7 @@ mmsearch 'd 2026-05'
 mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
 ```
 
-**Quicksearch syntax.** The search-string is a list of specs combined with **AND** (`or`/parens not yet supported). Wrap multi-word terms in `"double quotes"`.
+**Quicksearch syntax.** The search-string is a list of specs combined with **AND**; a bare `or` separates alternatives, and AND binds tighter (no parens — write `(f bob or f ann) s invoice` out as `f bob s invoice or f ann s invoice`). After `or`, a bare first term inherits the modifier in force: `d 2024 or 2025 or 2y`. Wrap multi-word terms in `"double quotes"` (also how to search for the literal word "or"). `mmsearch --help` is the canonical, always-current rendering of this table.
 
 | Modifier | Scope |
 |---|---|
@@ -175,9 +185,11 @@ mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
 | `a <term>` | Any address header contains. |
 | `b <term>` | Body (plain text) contains. |
 | `m <term>` | Common headers OR body. |
-| `d <date>` | Received date: `Y`, `Y-M`, `Y-M-D`, or relative `1d`/`2w`/`3m`/`1y`. |
+| `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). |
-| `!<value>` | Negate, e.g. `f !smith` = From does NOT contain smith. |
+| `!<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.
 
 The `--mailbox` argument accepts an account, an `account/path`, a bare mailbox name matched across accounts, or a **smart-mailbox name** (e.g. `Newsletters`, `Receipts`, `Priority`) whose filter is ANDed into the search.
 
@@ -414,6 +426,8 @@ A few rough edges to be aware of:
 
 ## Status
 
+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.
 
 1.5.0 — Reliability and batch-verification for `mm-modify`, plus search/read speedups. `mm-modify` gains a no-window retry guard (a `mid:` open that spawns no viewer would otherwise act on the wrong message) and opt-in effect verification: `--check` confirms a flag/tag/read action landed on the target eml-id by re-reading `#flags` (the only way to catch a duplicate-Message-ID misland). Because MailMate flushes `#flags` to disk ~5 s after acting, a new **`mm-verify`** command plus `mm-modify --emit-check` decouple acting from confirming — collect JSON check-tickets across a batch and verify them all in one flush-wait instead of paying the latency per message. `mmsearch` is substantially faster (compiled date ranges, cheapest-spec-first ordering, bulk-unpack index reader, inverted body search) with bit-identical output; the persistent MCP server now invalidates index caches on disk change. `mmmessage` shows user tags and lazy-loads the `mail` gem (`--raw`/`--mailmate` skip it). MCP: `message` gains `markdown`, `modify` gains a `check` mode (`none｜inline｜defer`), and a new `verify` tool batch-confirms deferred tickets.

data/lib/mailmate/cli/search.rb

@@ -71,7 +71,17 @@ module Mailmate
         parser = build_parser(opts)
         parser.parse!(argv)
 
+        self.date_order = opts[:european] ? :dmy : :mdy
+
         search_string = argv[0] || DEFAULT_SEARCH
+        # Rewrite Gmail/Outlook-style key:value tokens to their exact
+        # quicksearch equivalent — loudly, never silently: every rewrite is
+        # announced on stderr so the transcript shows what actually ran (and
+        # the caller learns the syntax). stdout stays clean CSV.
+        search_string, translations = Mailmate::SearchSyntax.translate(search_string, european: !!opts[:european])
+        if (notice = Mailmate::SearchSyntax.translation_notice(translations))
+          warn notice
+        end
         fields_arg    = (opts[:fields] || argv[1] || DEFAULT_FIELDS).to_s.strip
         # `+...` means "defaults plus these"; bare list = exactly those columns.
         # Defaults already include `id` as the first column, so `+x` keeps id
@@ -103,6 +113,19 @@ module Mailmate
         end
 
         specs = order_specs(parse_search(search_string))
+        # Validate date specs per or-group: only when EVERY branch is
+        # unsatisfiable is the query itself an error. A single dead branch
+        # in a multi-branch query gets a warning — the other branches still
+        # mean something, and the dead one silently contributing nothing is
+        # exactly the failure mode this validation exists to surface.
+        date_errs = specs.filter_map { |group| date_spec_error(group) }
+        if date_errs.any?
+          if date_errs.size == specs.size
+            warn date_errs.first
+            return 2
+          end
+          date_errs.each { |e| warn "dead or-branch (matches nothing): #{e}" }
+        end
 
         # Compose + parse the smart-mailbox filter exactly once. The same AST
         # feeds the evaluator, the tier classifier, and the literals extractor.
@@ -142,6 +165,15 @@ module Mailmate
 
         sort_rows!(rows, opts[:sort])
         emit_output(rows, fields, opts)
+        # A query written in another mail system's dialect is not a syntax
+        # error here — it parses as a literal term and quietly matches
+        # nothing. Callers (people and agents alike) read that empty result
+        # as "no such mail" and stop. Say so on stderr, so stdout stays
+        # clean CSV and the exit status stays 0: the search DID run, it just
+        # cannot have found what the caller meant.
+        if rows.empty? && (hint = Mailmate::SearchSyntax.zero_result_hint(search_string))
+          warn hint
+        end
         0
       end
 
@@ -189,26 +221,17 @@ module Mailmate
           o.on("--no-align", "Plain CSV (no column padding)") { opts[:align] = false }
           o.on("--sort MODE", %w[asc desc none],
                "Sort rows by date+time: asc (default), desc, none") { |v| opts[:sort] = v.to_sym }
+          o.on("--european",
+               "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. Specs combine with AND."
-          o.separator "  Wrap multi-word terms in \"double quotes\". Prefix operand with ! to negate."
-          o.separator ""
-          o.separator "    <term>    common headers (from/to/cc/subject) OR body contains <term>"
-          o.separator "    f <term>  from contains"
-          o.separator "    t <term>  to/cc (recipients) contains"
-          o.separator "    c <term>  cc contains"
-          o.separator "    s <term>  subject contains"
-          o.separator "    a <term>  any address header contains"
-          o.separator "    b <term>  body contains (reads MailMate's body indexes; --all for un-indexed too)"
-          o.separator "    m <term>  common headers OR body (same as bare term)"
-          o.separator "    d <date>  received date: Nd|Nw|Nm|Ny (relative), or Y, Y-M, Y-M-D"
-          o.separator "    T <tag>   tag / IMAP keyword contains  (K is a synonym)"
+          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 Mailmate::SearchSyntax.reference(indent: "  ")
+          o.separator "  (b also takes --all to include un-indexed messages.)"
           o.separator ""
-          o.separator "  Examples:"
-          o.separator "    mmsearch 'f substack d 7d'         from Substack in last 7 days"
-          o.separator "    mmsearch 's \"invoice due\" !draft'  subject has invoice due, no 'draft'"
-          o.separator "    mmsearch 'd 2026-05'               received in May 2026"
+          o.separator "FOREIGN SYNTAX (Gmail/Outlook-style, auto-translated, announced on stderr)"
+          o.separator Mailmate::SearchSyntax.translation_reference(indent: "  ")
           o.separator ""
           o.separator "FIELDS (for the fields argument / --fields)"
           o.separator "  id          eml-id (always included as first column)"
@@ -303,6 +326,13 @@ module Mailmate
       # ---- search-string parsing ----------------------------------------------
 
       def tokenize(str)
+        tokenize_q(str).map(&:first)
+      end
+
+      # [text, quoted] pairs — quoted-ness must survive tokenization so a
+      # deliberate search for the literal word "or" (`s "or"`) is not taken
+      # as the group separator, and a quoted "f" is never read as a modifier.
+      def tokenize_q(str)
         tokens = []
         i = 0
         while i < str.length
@@ -311,42 +341,72 @@ module Mailmate
             i += 1
           elsif c == "\""
             j = str.index("\"", i + 1) || str.length
-            tokens << str[(i + 1)...j]
+            tokens << [str[(i + 1)...j], true]
             i = j + 1
           else
             j = i
             j += 1 while j < str.length && str[j] != " "
-            tokens << str[i...j]
+            tokens << [str[i...j], false]
             i = j
           end
         end
         tokens
       end
 
+      # A bare `or` splits the query into groups: specs within a group AND
+      # together, groups OR together — `and` (juxtaposition) binds tighter
+      # than `or`, and there are no parens: `(f bob or f ann) s invoice` is
+      # written out as `f bob s invoice or f ann s invoice`. A group that
+      # OPENS with a bare unquoted operand inherits the modifier in force at
+      # the end of the previous group — the app's `d 2024 or 2025 or 2y`
+      # shorthand. Returns an array of spec groups; empty groups (a dangling
+      # `or`) are dropped.
       def parse_search(str)
-        tokens = tokenize(str)
+        token_groups = [[]]
+        tokenize_q(str).each do |tok, quoted|
+          if !quoted && tok.casecmp?("or")
+            token_groups << []
+          else
+            token_groups.last << [tok, quoted]
+          end
+        end
+
+        carried = nil
+        groups = token_groups.map do |tokens|
+          specs, carried = parse_group(tokens, carried)
+          specs
+        end
+        groups.reject(&:empty?)
+      end
+
+      def parse_group(tokens, inherited_field)
         specs = []
+        in_force = inherited_field
         i = 0
         while i < tokens.size
-          tok = tokens[i]
-          field = MODIFIERS[tok]
+          tok, quoted = tokens[i]
+          field = quoted ? nil : MODIFIERS[tok]
           if field && i + 1 < tokens.size
-            operand = tokens[i + 1]
+            operand, = tokens[i + 1]
             negate = operand.start_with?("!")
             operand = operand[1..] if negate
             specs << [field, operand.downcase, negate]
+            in_force = field
             i += 2
           else
             negate = tok.start_with?("!")
             operand = negate ? tok[1..] : tok
-            # Bare terms default to MailMate's "Common" specifier — common
-            # headers OR body — matching the UI quicksearch behavior. Pass
-            # --headers-only to skip the body scan when speed matters.
-            specs << [:message_or_body, operand.downcase, negate]
+            # 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]
             i += 1
           end
         end
-        specs
+        [specs, in_force]
       end
 
       # Static cost rank per spec field for AND evaluation order: compiled
@@ -359,13 +419,16 @@ module Mailmate
         body: 2, message_or_body: 2,
       }.freeze
 
-      # Evaluate cheap, selective specs before expensive ones. specs combine
-      # with AND (order-independent), and matches? short-circuits on the
-      # first miss — so `b invoice d 7d` should date-reject 47k messages
-      # before body matching ever runs, not after. Stable within a cost rank
-      # to keep the user's order deterministic.
-      def order_specs(specs)
-        specs.sort_by.with_index { |(field, _term, _negate), i| [SPEC_COST.fetch(field, 1), i] }
+      # 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`
+      # should date-reject 47k messages before body matching ever runs, not
+      # after. Stable within a cost rank to keep the user's order
+      # deterministic.
+      def order_specs(groups)
+        groups.map do |specs|
+          specs.sort_by.with_index { |(field, _term, _negate), i| [SPEC_COST.fetch(field, 1), i] }
+        end
       end
 
       # ---- date matching ------------------------------------------------------
@@ -373,44 +436,163 @@ module Mailmate
       # The `#date` index stores fixed-format strings ("2026-03-19 18:55:19
       # -0600", sender-local time with varying UTC offsets — NOT lexically
       # comparable). date_matches? runs once per candidate message, so the
-      # hot path avoids Time.parse (~10× slower than slicing) and per-call
-      # cutoff arithmetic: terms compile once to an inclusive [lo, hi] range
-      # of YYYYMMDD integers, and the indexed value slices straight to the
-      # same integer form. Calendar-date comparison semantics are unchanged.
+      # hot path avoids Time.parse (~10× slower than fast_time's slicing) and
+      # per-call cutoff arithmetic: day terms compile once to an inclusive
+      # [lo, hi] range of YYYYMMDD integers; per message, fast_time slices
+      # the indexed value into a Time (offset preserved) which localize then
+      # converts to the display zone before the day compare. Hour terms
+      # (`24h`) compare the same Time as an epoch instant instead.
+
+      # Slash-date ordering for three-part dates with a trailing 4-digit
+      # year: :mdy (American month-first, the default — `8/9/2026` = Aug 9)
+      # or :dmy (day-first, the --european flag — `9/8/2026` = Aug 9).
+      # ISO Y-M-D is unaffected. Module-level because the compiled-range
+      # memo must reset when it flips (the MCP server outlives any one call).
+      def date_order
+        @date_order || :mdy
+      end
+
+      def date_order=(order)
+        @date_order = order
+      end
 
       # Compiled day-range for a date term, memoized per term. nil = term
       # can't match anything. The memo resets when the calendar day rolls
-      # over so relative terms ("1d") stay correct in long-lived processes
-      # (the MCP server).
+      # over (so relative terms like "1d" stay correct in long-lived
+      # processes — the MCP server) or when date_order flips.
       def date_range_for(term)
         today = Date.today
-        if @date_ranges_day != today
+        if @date_ranges_day != today || @date_ranges_order != date_order
           @date_ranges_day = today
+          @date_ranges_order = date_order
           @date_ranges = {}
         end
         return @date_ranges[term] if @date_ranges.key?(term)
         @date_ranges[term] = compile_date_range(term, today)
       end
 
+      # A term is an optional comparison prefix (>, >=, <, <=) on a period.
+      # The prefix reshapes the period's inclusive [lo, hi] window: `>2026-08`
+      # is "after August" = [20260901, max], `<2026-08` is "before August" =
+      # [min, 20260731]. Bounds are compared as YYYYMMDD integers, so ±1 on a
+      # synthetic bound (a month's "day 31", a year's "Dec 31"+1) is safe —
+      # no real date falls in the gap. A comparison can produce an empty
+      # window (`>3d` — nothing is after a window that already reaches the
+      # future); date_spec_error reports those up front rather than letting
+      # them silently match nothing.
       def compile_date_range(term, today)
+        op = nil
+        if term =~ /\A(>=|<=|>|<)(.+)\z/
+          op, term = Regexp.last_match(1), Regexp.last_match(2)
+        end
+        base = compile_period_range(term, today)
+        return nil unless base
+        return base unless op
+
+        lo, hi = base
+        case op
+        when ">"  then [hi + 1, 9999_12_31]
+        when ">=" then [lo, 9999_12_31]
+        when "<"  then [0, lo - 1]
+        when "<=" then [0, hi]
+        end
+      end
+
+      def compile_period_range(term, today)
         if term =~ /\A(\d+)([dwmy])\z/
           n, u = Regexp.last_match(1).to_i, Regexp.last_match(2)
+          return nil if n.zero? # a zero-length window matches nothing
+          # N units ENDING today: `1d` = today only, `7d` = the last 7
+          # calendar days including today. (Off-by-one fixed 2026-08-11 to
+          # match the MailMate app, where `d 1d` is today's mail — the old
+          # cutoff of today-N made `d 1d` span two calendar days. For a
+          # rolling 24-hour clock window, that's `d 24h` now.)
           cutoff = case u
-                   when "d" then today - n
-                   when "w" then today - (n * 7)
-                   when "m" then today << n
-                   when "y" then today << (n * 12)
+                   when "d" then today - (n - 1)
+                   when "w" then today - (n * 7 - 1)
+                   when "m" then (today << n) + 1
+                   when "y" then (today << (n * 12)) + 1
                    end
           return [ymd_int(cutoff), 9999_12_31]
         end
 
         parts = term.tr("/.", "-").split("-")
-        y = parts[0].to_i
-        return nil if y.zero?
+        return nil unless parts.any? && parts.all? { |p| p.match?(/\A\d+\z/) }
+
         case parts.size
-        when 1 then [y * 10_000 + 101, y * 10_000 + 1231]
-        when 2 then [y * 10_000 + parts[1].to_i * 100 + 1, y * 10_000 + parts[1].to_i * 100 + 31]
-        when 3 then [ymd = y * 10_000 + parts[1].to_i * 100 + parts[2].to_i, ymd]
+        when 1
+          y = parts[0].to_i
+          return nil if y.zero?
+          [y * 10_000 + 101, y * 10_000 + 1231]
+        when 2
+          # Year-first (2026-08) or month-first with a 4-digit year (8/2026).
+          y, m = parts[1].length == 4 ? [parts[1], parts[0]] : [parts[0], parts[1]]
+          y, m = y.to_i, m.to_i
+          return nil if y.zero? || !(1..12).cover?(m)
+          [y * 10_000 + m * 100 + 1, y * 10_000 + m * 100 + 31]
+        when 3
+          # ISO year-first, or slash-date with trailing 4-digit year ordered
+          # per date_order. Impossible calendar dates (2026-02-31, month 13)
+          # compile to nil so date_spec_error names them instead of the
+          # search silently matching nothing.
+          y, m, d =
+            if parts[0].length == 4
+              parts.map(&:to_i)
+            elsif parts[2].length == 4
+              a, b, yr = parts.map(&:to_i)
+              date_order == :dmy ? [yr, b, a] : [yr, a, b]
+            end
+          return nil unless y && Date.valid_date?(y, m, d)
+          [ymd = y * 10_000 + m * 100 + d, ymd]
+        end
+      end
+
+      # Usage-error string for the date specs in ONE or-group (specs within a
+      # group AND together; the caller decides how errors across groups
+      # combine), nil when they're fine. Two failure classes, both of which
+      # would otherwise surface as a clean, successful, empty result — the
+      # silent-nothing this gem keeps having to fight: a single term that
+      # cannot match anything (`d >3d`, `d garbage`), and positive terms
+      # whose windows don't intersect (`d >2026 d <2025`). Negated terms
+      # subtract rather than intersect, so they're validated individually
+      # but excluded from the intersection.
+      def date_spec_error(specs)
+        day_terms, hour_terms = [], []
+        specs.each do |field, term, negate|
+          next unless field == :date
+          range = hour_range_for(term) || date_range_for(term)
+          if range.nil? || range[0] > range[1]
+            return "date term cannot match anything: d #{term}#{date_term_hint(term)}"
+          end
+          next if negate
+          (term.end_with?("h") ? hour_terms : day_terms) << [term, range]
+        end
+
+        # Day windows intersect with day windows and hour windows with hour
+        # windows; the two families use different scales (YYYYMMDD ints vs
+        # epoch seconds), and a cross-family contradiction is not worth the
+        # unit conversion to detect.
+        [day_terms, hour_terms].each do |family|
+          next if family.size < 2
+          lo = family.map { |_, r| r[0] }.max
+          hi = family.map { |_, r| r[1] }.min
+          next if lo <= hi
+          return "impossible date range (empty intersection): #{family.map { |t, _| "d #{t}" }.join(" ")}"
+        end
+        nil
+      end
+
+      # `13/8/2026` under month-first ordering is month 13 — almost certainly
+      # a day-first date (and vice versa). Name the likely fix instead of
+      # leaving the generic cannot-match.
+      def date_term_hint(term)
+        parts = term.sub(/\A(>=|<=|>|<)/, "").tr("/.", "-").split("-")
+        return nil unless parts.size == 3 && parts[2].length == 4
+        a, b = parts[0].to_i, parts[1].to_i
+        if date_order == :mdy && a > 12 && (1..12).cover?(b)
+          " (day-first date? pass --european)"
+        elsif date_order == :dmy && b > 12 && (1..12).cover?(a)
+          " (month-first date? drop --european)"
         end
       end
 
@@ -418,39 +600,56 @@ module Mailmate
         d.year * 10_000 + d.month * 100 + d.day
       end
 
-      # "2026-03-19 …" → 20260319 without Time.parse. nil when the value
-      # isn't in the indexed shape (caller falls back to the slow path).
-      def fast_ymd(s)
-        return nil unless s && s.length >= 10 && s.getbyte(4) == 0x2D && s.getbyte(7) == 0x2D
-        y = s[0, 4].to_i
-        m = s[5, 2].to_i
-        d = s[8, 2].to_i
-        return nil if y.zero? || m.zero? || d.zero?
-        y * 10_000 + m * 100 + d
+      # Rolling clock windows: `24h` = the last 24 hours as an instant range,
+      # unlike d/w/m/y which are calendar windows. Returns [lo, hi] epoch
+      # floats (lo > hi means the term cannot match — date_spec_error reports
+      # it), or nil when the term isn't an hour form. Deliberately NOT
+      # memoized: the cutoff moves with the clock, and the MCP server process
+      # lives long enough for a cached one to go stale.
+      def hour_range_for(term)
+        m = /\A(>=|<=|>|<)?(\d+)h\z/.match(term)
+        return nil unless m
+        op, n = m[1], m[2].to_i
+        return [1.0, 0.0] if n.zero?
+
+        cutoff = Time.now.to_f - (n * 3600)
+        case op
+        when nil, ">=" then [cutoff, Float::INFINITY]
+        when ">"       then [1.0, 0.0] # the window already reaches the future
+        when "<"       then [-Float::INFINITY, cutoff]
+        when "<="      then [-Float::INFINITY, Float::INFINITY]
+        end
       end
 
+      # Match on the message's absolute send instant, converted to the display
+      # zone via Mailmate.localize — the SAME conversion the date/time output
+      # columns use, so the day a term matches is always the day the caller
+      # sees in the output. (The raw `#date` index value is sender-local time;
+      # matching on its sliced day — the old fast path — made `d 1d` return
+      # mail displayed under yesterday's date whenever the sender's calendar
+      # ran ahead of the display zone, e.g. a UTC sender after 6pm MDT.)
       def date_matches?(mail, eml_id, term)
-        range = date_range_for(term)
-        return false unless range
-
-        ymd = nil
+        t = nil
         if eml_id
           s = (reader_for("#date")&.value_for(eml_id.to_i) rescue nil)
-          if s && !s.empty?
-            ymd = fast_ymd(s)
-            if ymd.nil?
-              t = (Time.parse(s) rescue nil)
-              ymd = t && ymd_int(t.to_date)
-            end
-          end
+          t = fast_time(s) || (Time.parse(s) rescue nil) if s && !s.empty?
         end
-        if ymd.nil? && mail
+        if t.nil? && mail
           raw = mail.date
-          d = raw.respond_to?(:to_time) ? raw.to_time : raw
-          ymd = d && ymd_int(d.to_date)
+          t = raw.respond_to?(:to_time) ? raw.to_time : raw
+        end
+        return false unless t
+
+        if (hours = hour_range_for(term))
+          f = t.to_f
+          return f >= hours[0] && f <= hours[1]
         end
-        return false unless ymd
 
+        range = date_range_for(term)
+        return false unless range
+
+        local = Mailmate.localize(t)
+        ymd = local.year * 10_000 + local.month * 100 + local.day
         ymd >= range[0] && ymd <= range[1]
       rescue StandardError
         false
@@ -627,26 +826,28 @@ module Mailmate
         texts
       end
 
-      def matches?(mail, eml_id, specs, headers_only, path = nil, index_only: false, exclude_quoted: false)
-        specs.all? do |field, term, negate|
-          term_b = term.b
-          hit =
-            case field
-            when :from, :recipients, :cc, :subject, :address_any
-              field_value(eml_id, mail, field).include?(term_b)
-            when :tag, :keyword
-              tag_value(eml_id).include?(term_b)
-            when :body
-              headers_only ? false : body_matches?(eml_id, mail, path, term, term_b, index_only: index_only, exclude_quoted: exclude_quoted)
-            when :message_or_body
-              common = %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
-              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 :any
-              %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
-            end
-          negate ? !hit : hit
+      def matches?(mail, eml_id, groups, headers_only, path = nil, index_only: false, exclude_quoted: false)
+        groups.any? do |specs|
+          specs.all? do |field, term, negate|
+            term_b = term.b
+            hit =
+              case field
+              when :from, :recipients, :cc, :subject, :address_any
+                field_value(eml_id, mail, field).include?(term_b)
+              when :tag, :keyword
+                tag_value(eml_id).include?(term_b)
+              when :body
+                headers_only ? false : body_matches?(eml_id, mail, path, term, term_b, index_only: index_only, exclude_quoted: exclude_quoted)
+              when :message_or_body
+                common = %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
+                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 :any
+                %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
+              end
+            negate ? !hit : hit
+          end
         end
       end
 

data/lib/mailmate/cli/send.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "open3"
+
 module Mailmate
   module CLI
     # `mm-send` — send mail through MailMate's `emate` CLI with a markdown body.
@@ -41,18 +43,37 @@ module Mailmate
 
       PREAMBLE
 
-      # Returns the exit status of the spawned `emate` invocation. Uses
-      # `system` (not `exec`) so the caller — and the test suite — can
-      # actually observe the result.
+      # Returns the exit status of the spawned `emate` invocation.
+      #
+      # emate must NEVER inherit the caller's real stdin/stdout. Inside the
+      # MCP server, fd 0/1 are the JSON-RPC transport, and the previous
+      # `system(...)` handed both to emate: it blocked reading the protocol
+      # pipe for a body and consumed the next frame as one (a cancelled turn
+      # produced a MailMate draft whose entire body was a
+      # `notifications/cancelled` frame — the composed body, swapped in via
+      # the Ruby-level `$stdin` global, was silently discarded). So: read the
+      # body through `$stdin` (honors the MCP's StringIO swap AND a shell
+      # pipe), hand it to emate on a private pipe that capture3 EOFs (no
+      # more hanging until the server dies), and re-emit emate's output
+      # through the `$stdout`/`$stderr` globals so the MCP's capture sees it
+      # instead of the protocol stream getting corrupted.
       def run(argv)
         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
-        warn PREAMBLE if argv.include?("--help") || argv.include?("-h")
-        system(EMATE_PATH, "mailto", "--markup", "markdown", *argv)
-        $?.exitstatus
+        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
+        out, err, status = Open3.capture3(EMATE_PATH, "mailto", "--markup", "markdown", *argv, stdin_data: body)
+        $stdout.write(out)
+        $stderr.write(err)
+        # exitstatus is nil for a signal-killed child; the exe shims do
+        # `exit run(ARGV)`, which needs an Integer.
+        status.exitstatus || 1
       end
     end
   end

data/lib/mailmate/mcp.rb

@@ -80,22 +80,19 @@ module Mailmate
           Search MailMate's .eml files using MailMate's quicksearch syntax.
           Returns column-aligned CSV. Same engine as the `mmsearch` CLI.
 
-          Query = space-separated specs combined with AND (no or/parens yet).
-          Quote multi-word terms ("invoice due"). Modifiers:
-            (bare term)  From/To/Cc/Subject OR body contains
-            f <t> From    t <t> To/Cc    c <t> Cc    s <t> Subject
-            a <t> any address header    b <t> body    m <t> headers OR body
-            d <date>  received: Y, Y-M, Y-M-D, or relative 1d/2w/3m/1y
-            T <tag>   tag / IMAP keyword (K is a synonym)
-            !<value>  negate, e.g. f !smith  (From does NOT contain smith)
+          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.
+
+          #{Mailmate::SearchSyntax.reference(indent: "  ")}
+
           The `mailbox` arg also accepts a smart-mailbox name (e.g. Newsletters,
           Receipts, Priority) whose filter is ANDed into the search.
 
-          Examples:
-            query="f substack d 7d"        from Substack in the last 7 days
-            query="T urgent"               tagged "urgent"
-            query="s 'invoice due' !draft" subject has 'invoice due', not 'draft'
-
           Fields default to: flags date time direction party subject.
           Prefix with "+" to add to the defaults ("+tags +mailbox"); a bare
           list replaces them (id is always the first column). Meanings:
@@ -124,6 +121,7 @@ module Mailmate
             limit: { type: "integer", description: "Stop after N matches." },
             headers_only: { type: "boolean", description: "Skip body matching (much faster on text searches)." },
             sort: { type: "string", enum: %w[asc desc none], description: "Sort by date+time. Default: asc." },
+            european: { type: "boolean", description: "Slash dates in the query are day-first (d 9/8/2026 = Aug 9). Default: month-first American." },
           },
           additionalProperties: false,
         },
@@ -416,6 +414,7 @@ module Mailmate
       argv.push("--limit",   args["limit"].to_i.to_s) if args["limit"]
       argv.push("--headers-only")                    if args["headers_only"]
       argv.push("--sort",    args["sort"].to_s)      if args["sort"]
+      argv.push("--european")                        if args["european"]
       # Positionals: search-string then fields. Only include if the caller
       # gave us either — otherwise let the CLI apply its defaults.
       if args.key?("query") || args["fields"]

data/lib/mailmate/search_syntax.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Mailmate
+  # THE one description of quicksearch syntax. Both surfaces that teach the
+  # syntax — `mmsearch --help` and the MCP `search` tool description — render
+  # from the tables here, so the two can no longer drift apart (they already
+  # had: the CLI said "Nd|Nw|Nm|Ny (relative), or Y, Y-M, Y-M-D" while the MCP
+  # said "Y, Y-M, Y-M-D, or relative 1d/2w/3m/1y" — same rules, two wordings,
+  # two things to remember to update).
+  #
+  # Downstream consumers should POINT at these surfaces rather than restate
+  # them. A copy of the syntax in someone else's system prompt is a copy that
+  # goes stale the next time a modifier is added here.
+  module SearchSyntax
+    # [spec, meaning]. Order is the teaching order, not alphabetical.
+    MODIFIERS = [
+      ["<term>",   "common headers (from/to/cc/subject) OR body contains <term>"],
+      ["f <term>", "from contains"],
+      ["t <term>", "to/cc (recipients) contains"],
+      ["c <term>", "cc contains"],
+      ["s <term>", "subject contains"],
+      ["a <term>", "any address header contains"],
+      ["b <term>", "body contains"],
+      ["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)"],
+    ].freeze
+
+    EXAMPLES = [
+      ["f substack d 7d",         "from Substack in the last 7 days"],
+      ["s \"invoice due\" !draft", "subject has 'invoice due', not 'draft'"],
+      ["d 2026-05",               "received in May 2026"],
+      ["d 2026-08-10",            "received on one specific day"],
+      ["d 1d",                    "received today (the default); d 2d = yesterday + today"],
+      ["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"],
+      ["T urgent",                "tagged 'urgent'"],
+    ].freeze
+
+    RULES = [
+      "Specs combine with AND; `or` separates alternatives, and AND binds tighter",
+      "(no parens): (f bob or f ann) s invoice = f bob s invoice or f ann s invoice.",
+      "After `or`, a bare first term inherits the modifier in force: d 2024 or 2025.",
+      "Wrap multi-word terms in \"double quotes\" (also how to search the word \"or\").",
+      "Prefix an operand with ! to negate: f !smith = from does NOT contain smith.",
+      "Negation works on dates too: d !3d = received MORE than 3 days ago.",
+      "Absolute dates compare: d >2026-08 (after Aug), d <2026-08 (before), also >= <=.",
+      "Slash dates are month-first American: d 8/9/2026 = Aug 9 (day-first: --european).",
+      "An impossible date combination (d >2026 d <2025) is an error, not 0 results.",
+    ].freeze
+
+    # Search keys from OTHER mail systems (Gmail, Outlook, Apple Mail, IMAP
+    # dialects). Quicksearch has no `key:value` form at all, so a term like
+    # `date:today` is not a syntax error — it parses as a bare term and
+    # searches for the literal string "date:today" in headers and body, which
+    # 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.
+    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
+    ].freeze
+
+    # Spec placeholders for the zero-result hint, for foreign keys whose value
+    # translate() could NOT rewrite (e.g. `after:8am`). Keys absent here still
+    # get flagged, just without a suggested rewrite.
+    EQUIVALENTS = {
+      "from" => "f <term>", "to" => "t <term>", "cc" => "c <term>",
+      "subject" => "s <term>", "body" => "b <term>", "label" => "T <tag>",
+      "date" => "d <date>", "sent" => "d <date>", "received" => "d <date>",
+      "on" => "d <date>", "after" => "d >=YYYY-MM-DD", "since" => "d >=YYYY-MM-DD",
+      "before" => "d <YYYY-MM-DD", "until" => "d <=YYYY-MM-DD",
+      "newer_than" => "d Nd", "older_than" => "d !Nd",
+      "newer" => "d Nd", "older" => "d !Nd",
+    }.freeze
+
+    # Foreign header-ish keys with a direct quicksearch spec. The value
+    # carries over unchanged, so these translate regardless of what it is.
+    HEADER_EQUIV = {
+      "from" => "f", "to" => "t", "cc" => "c",
+      "subject" => "s", "body" => "b", "label" => "T",
+    }.freeze
+
+    # The --help table for the translator. Symbolic, not computed — <N> is
+    # resolved against the current date at translation time.
+    TRANSLATIONS_HELP = [
+      ["from:bob   (to: cc: subject: body: label:)", "f bob   (t c s b T)"],
+      ["-from:bob or !from:bob",                     "f !bob"],
+      ["date:today / date:yesterday",                "d 1d / d <that day>"],
+      ["date:2026-03-05 or date:3/5/2026 (M/D/Y)",   "d 2026-03-05"],
+      ["newer_than:2d / older_than:2w",              "d 2d / d !2w"],
+      ["after:2026-05 or since:2026-05",             "d >=2026-05"],
+      ["before:2026-08 / until:2026-08",             "d <2026-08 / d <=2026-08"],
+    ].freeze
+
+    module_function
+
+    # The shared syntax reference, indented for embedding. Used verbatim by
+    # `mmsearch --help` and by the MCP tool description.
+    def reference(indent: "  ")
+      width = MODIFIERS.map { |spec, _| spec.length }.max
+      lines = []
+      RULES.each { |r| lines << "#{indent}#{r}" }
+      lines << ""
+      MODIFIERS.each { |spec, meaning| lines << "#{indent}  #{spec.ljust(width)}  #{meaning}" }
+      lines << ""
+      lines << "#{indent}Examples:"
+      ex_width = EXAMPLES.map { |q, _| q.length }.max
+      EXAMPLES.each { |q, meaning| lines << "#{indent}  #{q.ljust(ex_width)}  #{meaning}" }
+      lines.join("\n")
+    end
+
+    # One token: an (optionally key:-prefixed) quoted string, or a bare run
+    # of non-space. Quoted regions survive as single tokens so translate()
+    # can leave a deliberate literal search (`s "date:today"`) alone.
+    TOKEN_RX = /(?:[-!]?[A-Za-z_]+:)?"[^"]*"|(?:[-!]?[A-Za-z_]+:)?'[^']*'|\S+/
+
+    # Rewrite foreign `key:value` tokens to their exact quicksearch
+    # equivalent, leaving everything else byte-for-byte intact. Returns
+    # [query, notes] where notes is [[original_token, replacement], ...] —
+    # callers MUST surface the notes (stderr, tool result); a silent rewrite
+    # would show the reader a query that never ran.
+    #
+    # Only rewrites where the equivalence is exact. A foreign key whose value
+    # can't be translated faithfully (`after:8am`, `date:next week`) stays in
+    # the query as literal text, and zero_result_hint still flags it there.
+    def translate(query, today: Date.today, european: false)
+      notes = []
+      translated = query.to_s.gsub(TOKEN_RX) do |token|
+        replacement = translate_token(token, today, european)
+        notes << [token, replacement] if replacement
+        replacement || token
+      end
+      [translated, notes]
+    end
+
+    # The stderr/tool-result announcement for a rewritten query. nil when
+    # nothing was rewritten.
+    def translation_notice(notes)
+      return nil if notes.empty?
+
+      width = notes.map { |from, _| from.length }.max
+      lines = ["translated foreign search syntax to MailMate quicksearch (`mmsearch --help`):"]
+      notes.each { |from, to| lines << "  #{from.ljust(width)}  ->  #{to}" }
+      lines.join("\n")
+    end
+
+    # The --help table, indented for embedding.
+    def translation_reference(indent: "  ")
+      width = TRANSLATIONS_HELP.map { |from, _| from.length }.max
+      lines = TRANSLATIONS_HELP.map { |from, to| "#{indent}  #{from.ljust(width)}  ->  #{to}" }
+      lines << ""
+      lines << "#{indent}Keys with no equivalent (is: has: in: filename: ...) are searched as"
+      lines << "#{indent}literal text; an empty result will call them out."
+      lines.join("\n")
+    end
+
+    # Foreign `key:value` tokens in a query, lowercased keys, in order of
+    # appearance and de-duplicated. Quoted regions are skipped: a deliberate
+    # search for the literal text `s "date:today"` is not a mistake.
+    def foreign_tokens(query)
+      unquoted = query.to_s.gsub(/"[^"]*"|'[^']*'/, " ")
+      unquoted.scan(/(?<![\w-])!?([A-Za-z_]+):(\S*)/).filter_map do |key, value|
+        k = key.downcase
+        next unless FOREIGN_KEYS.include?(k)
+        ["#{key}:#{value}", k]
+      end.uniq { |_token, k| k }
+    end
+
+    # The advisory a caller should print when a search matched NOTHING and the
+    # query carries foreign syntax. nil when there is nothing to say — an
+    # ordinary empty result stays silent, because polling for mail that has
+    # not arrived yet is a normal, correct thing to do.
+    def zero_result_hint(query)
+      tokens = foreign_tokens(query)
+      return nil if tokens.empty?
+
+      quoted = tokens.map { |token, _| "`#{token}`" }.join(", ")
+      lines = ["0 results, and #{quoted} #{tokens.size == 1 ? "is not" : "are not"} " \
+               "MailMate quicksearch syntax — it was searched for as literal text."]
+      tokens.each do |token, key|
+        eq = EQUIVALENTS[key] or next
+        lines << "  #{token}  ->  #{eq}"
+      end
+      lines << "Run `mmsearch --help` for the full syntax."
+      lines.join("\n")
+    end
+
+    # ---- translation internals -------------------------------------------
+
+    # nil = not a rewritable token (not key:value, unknown key, or a value
+    # with no faithful equivalent).
+    def translate_token(token, today, european = false)
+      m = token.match(/\A(?<neg>[-!])?(?<key>[A-Za-z_]+):(?<value>.+)\z/m)
+      return nil unless m
+
+      key   = m[:key].downcase
+      value = unquote(m[:value])
+      return nil if value.empty?
+
+      if (spec = HEADER_EQUIV[key])
+        negated = !m[:neg].nil?
+        # `f !"a b"` won't tokenize (the ! detaches the quotes) — leave a
+        # negated multi-word value alone rather than emit a broken spec.
+        return nil if negated && value =~ /\s/
+        operand = value =~ /\s/ ? "\"#{value}\"" : value
+        return "#{spec} #{negated ? "!" : ""}#{operand}"
+      end
+
+      # Date keys: Gmail has no negated date form, so a -/! prefix here means
+      # the caller is inventing syntax — don't guess at intent.
+      return nil if m[:neg]
+
+      case key
+      when "date", "on", "sent", "received", "time"
+        translate_point_date(value, today, european)
+      when "after", "since"
+        translate_after(value, today, european)
+      when "before"
+        translate_before(value, today, "<", european)
+      when "until"
+        translate_before(value, today, "<=", european)
+      when "newer_than", "newer"
+        (rel = parse_relative(value)) && "d #{rel}"
+      when "older_than", "older"
+        (rel = parse_relative(value)) && "d !#{rel}"
+      end
+    end
+
+    def unquote(value)
+      case value
+      when /\A"(.*)"\z/m, /\A'(.*)'\z/m then Regexp.last_match(1)
+      else value
+      end
+    end
+
+    # A day-, month-, or year-precision point in time. `d <period>` matches
+    # exactly that period in the engine, so these are exact.
+    def translate_point_date(value, today, european = false)
+      v = value.downcase
+      return "d 1d" if v == "today"
+      return "d #{(today - 1).strftime("%Y-%m-%d")}" if v == "yesterday"
+      # `date:8/10/2026-today` (seen in real transcripts): a range whose end
+      # is now IS an after-window.
+      return translate_after(v.delete_suffix("-today"), today, european) if v.end_with?("-today")
+      return "d #{v}" if v =~ /\A\d+[dwmy]\z/
+
+      (period = normalize_period(v, european)) && "d #{period}"
+    end
+
+    # Gmail's after: includes the named day; since: likewise → >=.
+    def translate_after(value, today, european = false)
+      v = value.downcase
+      return "d 1d" if v == "today"
+      return "d 2d" if v == "yesterday"
+
+      (period = normalize_period(v, european)) && "d >=#{period}"
+    end
+
+    # Gmail's before: excludes the named day → <. until: includes it → <=.
+    def translate_before(value, today, op, european = false)
+      v = value.downcase
+      v = today.strftime("%Y-%m-%d") if v == "today"
+      v = (today - 1).strftime("%Y-%m-%d") if v == "yesterday"
+
+      (period = normalize_period(v, european)) && "d #{op}#{period}"
+    end
+
+    # "2026", "2026-05", "2026-03-05", "3/5/2026", "2026/3/5" → the
+    # normalized absolute period string quicksearch expects, or nil.
+    def normalize_period(value, european = false)
+      if (day = parse_day(value, european))
+        day.strftime("%Y-%m-%d")
+      elsif value =~ %r{\A(\d{4})[-/.](\d{1,2})\z}
+        format("%04d-%02d", Regexp.last_match(1).to_i, Regexp.last_match(2).to_i)
+      elsif value =~ /\A\d{4}\z/
+        value
+      end
+    end
+
+    # Gmail relative units (d/m/y, plus w) carry over as-is: `d N<u>` uses
+    # the same calendar arithmetic.
+    def parse_relative(value)
+      value =~ /\A(\d+)\s*([dwmy])\z/ ? "#{Regexp.last_match(1)}#{Regexp.last_match(2)}" : nil
+    end
+
+    # Y-M-D (any of - / . separators), or slash-dates with a trailing
+    # 4-digit year — US M/D/Y by default, D/M/Y when european. Two-digit
+    # years are ambiguous across dialects — refused rather than guessed.
+    def parse_day(value, european = false)
+      parts = value.split(%r{[-/.]})
+      return nil unless parts.size == 3 && parts.all? { |p| p =~ /\A\d+\z/ }
+
+      y, m, d =
+        if parts[0].length == 4
+          [parts[0], parts[1], parts[2]]
+        elsif parts[2].length == 4
+          european ? [parts[2], parts[1], parts[0]] : [parts[2], parts[0], parts[1]]
+        end
+      return nil unless y
+
+      y, m, d = y.to_i, m.to_i, d.to_i
+      Date.valid_date?(y, m, d) ? Date.new(y, m, d) : nil
+    end
+  end
+end

data/lib/mailmate/version.rb

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

data/lib/mailmate.rb

@@ -50,6 +50,7 @@ require_relative "mailmate/mailbox_graph"
 require_relative "mailmate/source_resolver"
 require_relative "mailmate/var_resolver"
 require_relative "mailmate/filter_classifier"
+require_relative "mailmate/search_syntax"
 
 module Mailmate
   # First-run bootstrap. If ~/.config/mailmate/config.yml is missing,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailmate
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Brian Murphy-Dye
@@ -153,6 +153,7 @@ files:
 - lib/mailmate/parser.rb
 - lib/mailmate/part_lookup.rb
 - lib/mailmate/platform_error.rb
+- lib/mailmate/search_syntax.rb
 - lib/mailmate/source_resolver.rb
 - lib/mailmate/var_resolver.rb
 - lib/mailmate/version.rb