feat(gmail): replace +triage with +search for full-metadata Gmail search

.changeset/gmail-search-helper.md

@@ -0,0 +1,12 @@
+---
+"@googleworkspace/cli": minor
+---
+
+Replace `+triage` with `+search` for full-metadata Gmail search with label resolution and pagination.
+
+Breaking: `+triage` is removed. Use `gws gmail +search --query 'is:unread'` instead.
+Breaking: `+read --format json` field names change from snake_case to camelCase
+(e.g. `thread_id` → `threadId`, `body_text` → `bodyText`) for consistency with `+search`
+and the project's camelCase JSON convention.
+Other changes: `--query` is now required, default output format is JSON (was table),
+output schema includes structured from/to/cc, resolved labels, threadId, and snippet.

README.md

@@ -298,7 +298,7 @@ Time-aware helpers (`+agenda`, `+standup-report`, `+weekly-digest`, `+meeting-pr
 Run `gws <service> --help` to see both Discovery methods and helper commands together.
 
 ```bash
-gws gmail --help      # shows +send, +reply, +reply-all, +forward, +triage, +watch …
+gws gmail --help      # shows +send, +reply, +reply-all, +forward, +search, +watch …
 gws calendar --help   # shows +insert, +agenda …
 gws drive --help      # shows +upload …
 ```
@@ -311,7 +311,7 @@ gws drive --help      # shows +upload …
 | `gmail` | `+reply` | Reply to a message (handles threading automatically) |
 | `gmail` | `+reply-all` | Reply-all to a message |
 | `gmail` | `+forward` | Forward a message to new recipients |
-| `gmail` | `+triage` | Show unread inbox summary (sender, subject, date) |
+| `gmail` | `+search` | Search Gmail messages with full metadata |
 | `gmail` | `+watch` | Watch for new emails and stream them as NDJSON |
 | `sheets` | `+append` | Append a row to a spreadsheet |
 | `sheets` | `+read` | Read values from a spreadsheet |

crates/google-workspace-cli/registry/personas.toml

@@ -7,7 +7,7 @@ workflows = [ "+standup-report", "+meeting-prep", "+weekly-digest" ]
 instructions = [
   "Start each day with `gws workflow +standup-report` to get the executive's agenda and open tasks.",
   "Before each meeting, run `gws workflow +meeting-prep` to see attendees, description, and linked docs.",
-  "Triage the inbox with `gws gmail +triage --max 10` — prioritize emails from direct reports and leadership.",
+  "Triage the inbox with `gws gmail +search --query 'is:unread' --max 10` — prioritize emails from direct reports and leadership.",
   "Schedule meetings with `gws calendar +insert` — always check for conflicts first using `gws calendar +agenda`.",
   "Draft replies with `gws gmail +send` — keep tone professional and concise."
 ]
@@ -68,7 +68,7 @@ instructions = [
   "Get a weekly sales pipeline summary with `gws workflow +weekly-digest`."
 ]
 tips = [
-  "Use `gws gmail +triage --query 'from:client-domain.com'` to filter client emails.",
+  "Use `gws gmail +search --query 'from:client-domain.com'` to filter client emails.",
   "Schedule follow-up calls immediately after meetings to maintain momentum.",
   "Keep all client-facing documents in a dedicated shared Drive folder."
 ]
@@ -115,14 +115,14 @@ description = "Manage customer support — track tickets, respond, escalate issu
 services = [ "gmail", "sheets", "chat", "calendar" ]
 workflows = [ "+email-to-task", "+standup-report" ]
 instructions = [
-  "Triage the support inbox with `gws gmail +triage --query 'label:support'`.",
+  "Triage the support inbox with `gws gmail +search --query 'label:support'`.",
   "Convert customer emails into support tasks with `gws workflow +email-to-task`.",
   "Log ticket status updates in a tracking sheet with `gws sheets +append`.",
   "Escalate urgent issues to the team Chat space.",
   "Schedule follow-up calls with customers using `gws calendar +insert`."
 ]
 tips = [
-  "Use `gws gmail +triage --labels` to see email categories at a glance.",
+  "Labels are always included in `+search` output — use them to categorize at a glance.",
   "Set up Gmail filters for auto-labeling support requests.",
   "Use `--format table` for quick status dashboard views."
 ]

crates/google-workspace-cli/src/generate_skills.rs

@@ -171,7 +171,7 @@ pub async fn handle_generate_skills(args: &[String]) -> Result<(), GwsError> {
         // Generate per-helper skills
         for helper in &helpers {
             let helper_name = helper.get_name();
-            // +triage -> triage
+            // +search -> search
             let short = helper_name.trim_start_matches('+');
             let helper_key = format!("{alias}-{short}");
 

crates/google-workspace-cli/src/helpers/README.md

@@ -12,7 +12,7 @@ A `+helper` command should exist only when it provides value that Discovery-base
 |---|---|---|
 | **Multi-step orchestration** | `+subscribe` | Creates Pub/Sub topic → subscription → Workspace Events subscription (3 APIs) |
 | **Format translation** | `+write` | Transforms Markdown → Docs `batchUpdate` JSON |
-| **Multi-API composition** | `+triage` | Lists messages then fetches N metadata payloads concurrently |
+| **Multi-API composition** | `+search` | Lists messages, resolves labels, fetches N metadata payloads concurrently |
 | **Complex body construction** | `+send`, `+reply` | Builds RFC 2822 MIME from simple flags |
 | **Multipart upload** | `+upload` | Handles resumable upload protocol with progress |
 | **Workflow recipes** | `+standup-report` | Chains calls across multiple services |
@@ -31,7 +31,7 @@ If a helper wraps one API call that Discovery already exposes, reject it.
 
 Adding flags to expose data that is already in the API response creates unbounded surface area.
 
-**Real example:** `--thread-id`, `--delivered-to`, `--sent-last` on `+triage` (PR #597) — all three values are already present in the Gmail API response. Agents and users should extract them with `--format` or `jq`, not new flags.
+**Real example:** `--thread-id`, `--delivered-to`, `--sent-last` on `+search` (PR #597) — all three values are already present in the Gmail API response. Agents and users should extract them with `--format` or `jq`, not new flags.
 
 **Why this is harmful:** Every API response contains dozens of fields. If we add a flag for each one, helpers become unbounded maintenance burdens — the exact problem Discovery-driven design solves.
 

crates/google-workspace-cli/src/helpers/gmail/mod.rs

@@ -16,15 +16,15 @@ use super::Helper;
 pub mod forward;
 pub mod read;
 pub mod reply;
+pub mod search;
 pub mod send;
-pub mod triage;
 pub mod watch;
 
 use forward::handle_forward;
 use read::handle_read;
 use reply::handle_reply;
+use search::handle_search;
 use send::handle_send;
-use triage::handle_triage;
 use watch::handle_watch;
 
 pub(super) use crate::auth;
@@ -62,6 +62,7 @@ fn sanitize_control_chars(s: &str) -> String {
 
 /// A parsed RFC 5322 mailbox: optional display name + email address.
 #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
 pub(super) struct Mailbox {
     pub name: Option<String>,
     pub email: String,
@@ -127,6 +128,30 @@ impl std::fmt::Display for Mailbox {
     }
 }
 
+/// A resolved Gmail label: maps the opaque label ID to its human-readable name.
+///
+/// All labels are resolved via the `labels.list` API. System labels (e.g. `INBOX`,
+/// `CATEGORY_FORUMS`) resolve to their canonical API names. User-created labels
+/// have opaque IDs (e.g. `Label_3066`) that resolve to display names.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct Label {
+    pub id: String,
+    pub name: String,
+}
+
+impl Label {
+    /// Resolve a label ID to a `Label` using a pre-fetched ID→name map.
+    /// Falls back to using the raw ID as the display name when the ID is not
+    /// in the map (e.g. the label was created after the map was fetched).
+    pub fn resolve(id: &str, label_map: &std::collections::HashMap<String, String>) -> Self {
+        Self {
+            name: label_map.get(id).cloned().unwrap_or_else(|| id.to_string()),
+            id: id.to_string(),
+        }
+    }
+}
+
 /// Convert a single `Mailbox` to a `mail_builder::Address`.
 pub(super) fn to_mb_address(mailbox: &Mailbox) -> MbAddress<'_> {
     MbAddress::new_address(mailbox.name.as_deref(), &mailbox.email)
@@ -181,6 +206,7 @@ impl OriginalPart {
 /// fields (`cc`, `reply_to`, `date`, `body_html`) use `Option` so the compiler
 /// enforces absence checks.
 #[derive(Default, Serialize)]
+#[serde(rename_all = "camelCase")]
 pub(super) struct OriginalMessage {
     pub thread_id: Option<String>,
     /// Bare message ID (no angle brackets), e.g. `"abc@example.com"`.
@@ -220,17 +246,18 @@ impl OriginalMessage {
 }
 
 /// Raw header values extracted from the Gmail API payload, before parsing into
-/// structured types. Intermediate step: JSON headers → this → `OriginalMessage`.
+/// structured types. Intermediate step between raw JSON headers and domain-specific
+/// message types (`OriginalMessage`, `SearchResult`).
 #[derive(Default)]
-struct ParsedMessageHeaders {
-    from: String,
-    reply_to: String,
-    to: String,
-    cc: String,
-    subject: String,
-    date: String,
-    message_id: String,
-    references: String,
+pub(super) struct ParsedMessageHeaders {
+    pub from: String,
+    pub reply_to: String,
+    pub to: String,
+    pub cc: String,
+    pub subject: String,
+    pub date: String,
+    pub message_id: String,
+    pub references: String,
 }
 
 fn append_header_value(existing: &mut String, value: &str) {
@@ -251,7 +278,7 @@ fn append_address_list_header_value(existing: &mut String, value: &str) {
     existing.push_str(value);
 }
 
-fn parse_message_headers(headers: &[Value]) -> ParsedMessageHeaders {
+pub(super) fn parse_message_headers(headers: &[Value]) -> ParsedMessageHeaders {
     let mut parsed = ParsedMessageHeaders::default();
 
     for header in headers {
@@ -1570,7 +1597,7 @@ fn common_reply_args(cmd: Command) -> Command {
 
 impl Helper for GmailHelper {
     /// Register all Gmail helper subcommands (`+send`, `+reply`, `+reply-all`,
-    /// `+forward`, `+triage`, `+watch`) with their arguments and help text.
+    /// `+forward`, `+read`, `+search`, `+watch`) with their arguments and help text.
     fn inject_commands(
         &self,
         mut cmd: Command,
@@ -1629,38 +1656,41 @@ TIPS:
         );
 
         cmd = cmd.subcommand(
-            Command::new("+triage")
-                .about("[Helper] Show unread inbox summary (sender, subject, date)")
+            Command::new("+search")
+                .about("[Helper] Search Gmail messages with full metadata")
+                .arg(
+                    Arg::new("query")
+                        .long("query")
+                        .help("Gmail search query (e.g., 'from:alice subject:report')")
+                        .required(true)
+                        .value_name("QUERY"),
+                )
                 .arg(
                     Arg::new("max")
                         .long("max")
-                        .help("Maximum messages to show (default: 20)")
+                        .help("Maximum messages to return (default: 20)")
                         .default_value("20")
+                        .value_parser(clap::value_parser!(u32).range(1..=500))
                         .value_name("N"),
                 )
                 .arg(
-                    Arg::new("query")
-                        .long("query")
-                        .help("Gmail search query (default: is:unread)")
-                        .value_name("QUERY"),
-                )
-                .arg(
-                    Arg::new("labels")
-                        .long("labels")
-                        .help("Include label names in output")
-                        .action(ArgAction::SetTrue),
+                    Arg::new("page-token")
+                        .long("page-token")
+                        .help("Page token for continuing a previous search")
+                        .value_name("TOKEN"),
                 )
                 .after_help(
                     "\
 EXAMPLES:
-  gws gmail +triage
-  gws gmail +triage --max 5 --query 'from:boss'
-  gws gmail +triage --format json | jq '.[].subject'
-  gws gmail +triage --labels
+  gws gmail +search --query 'is:unread'
+  gws gmail +search --query 'from:boss subject:urgent' --max 5
+  gws gmail +search --query 'has:attachment' --format table
+  gws gmail +search --query 'newer_than:1d' --page-token <TOKEN>
 
 TIPS:
   Read-only — never modifies your mailbox.
-  Defaults to table output format.",
+  Defaults to JSON output. Labels are resolved to human-readable names.
+  Use --page-token with the nextPageToken from a previous result to paginate.",
                 ),
         );
 
@@ -1951,8 +1981,8 @@ TIPS:
                 return Ok(true);
             }
 
-            if let Some(matches) = matches.subcommand_matches("+triage") {
-                handle_triage(matches).await?;
+            if let Some(matches) = matches.subcommand_matches("+search") {
+                handle_search(matches).await?;
                 return Ok(true);
             }
 
@@ -2331,6 +2361,7 @@ mod tests {
         assert!(subcommands.contains(&"+reply-all"));
         assert!(subcommands.contains(&"+forward"));
         assert!(subcommands.contains(&"+read"));
+        assert!(subcommands.contains(&"+search"));
     }
 
     #[test]