inboxctl 0.3.0 → 0.4.0

package/README.md

@@ -8,7 +8,7 @@
 
 Most email tools put the intelligence inside the app. `inboxctl` does the opposite: it is the infrastructure layer, and your AI agent is the brain.
 
-Connect any MCP client, including Claude Desktop, Claude Code, or another MCP-compatible agent, and it gets structured access to search your inbox, review sender patterns, detect newsletter noise, triage unread mail, apply labels, archive, create Gmail filters, and manage rules. `inboxctl` handles the Gmail plumbing, audit trail, and undo path.
+Connect any MCP client, including Claude Desktop, Claude Code, or another MCP-compatible agent, and it gets structured access to search your inbox, review sender patterns, analyze uncategorized mail at sender-level, detect newsletter noise, rank unsubscribe opportunities, review categorization anomalies, run structured inbox queries, apply labels, archive, create Gmail filters, and manage rules. `inboxctl` handles the Gmail plumbing, audit trail, and undo path.
 
 The CLI and TUI ship alongside MCP so you can always inspect what an agent did, undo it, or run the same work manually.
 
@@ -18,9 +18,9 @@ Emails are never deleted. The tool can label, archive, mark read, and forward, b
 
 | | Count | Examples |
 |---|---|---|
-| **Tools** | 25 | `search_emails`, `archive_emails`, `label_emails`, `mark_read`, `get_top_senders`, `get_newsletter_senders`, `deploy_rule`, `run_rule`, `create_filter`, `undo_run` |
-| **Resources** | 6 | `inbox://recent`, `inbox://summary`, `rules://deployed`, `rules://history`, `stats://senders`, `stats://overview` |
-| **Prompts** | 5 | `summarize-inbox`, `review-senders`, `find-newsletters`, `suggest-rules`, `triage-inbox` |
+| **Tools** | 32 | `search_emails`, `get_uncategorized_senders`, `batch_apply_actions`, `query_emails`, `get_noise_senders`, `get_unsubscribe_suggestions`, `deploy_rule`, `create_filter`, `undo_run`, `review_categorized` |
+| **Resources** | 8 | `inbox://recent`, `inbox://summary`, `inbox://action-log`, `schema://query-fields`, `rules://deployed`, `rules://history`, `stats://senders`, `stats://overview` |
+| **Prompts** | 6 | `summarize-inbox`, `review-senders`, `find-newsletters`, `suggest-rules`, `triage-inbox`, `categorize-emails` |
 
 An agent can read your inbox summary, review your noisiest senders, suggest a YAML rule to handle them, deploy it in dry-run, show you the results, and apply it, all through MCP calls.
 
@@ -104,11 +104,13 @@ inboxctl demo               # launch the seeded demo mailbox
 ## Features
 
 - **MCP server** with the full feature set exposed as tools, resources, and prompts.
+- **Context-efficient sender workflows** with `get_uncategorized_senders` for large inbox categorization without loading every email into an agent context window.
 - **Rules as code** in YAML, with deploy, dry-run, apply, drift detection, audit logging, and undo.
-- **Local-first analytics** on top senders, unread rates, newsletter detection, labels, and volume trends.
+- **Local-first analytics** on top senders, unread rates, newsletter detection, uncategorized senders, noise scoring, unsubscribe impact, anomaly review, labels, and volume trends.
+- **Structured inbox queries** for fixed filters, aggregations, and grouping across the local cache.
 - **Gmail filter management** for always-on server-side rules on future incoming mail.
 - **Full audit trail** with before/after state snapshots for reversible actions.
-- **Interactive TUI** for inbox triage, email detail, stats, rules, and search.
+- **Interactive TUI** for inbox triage, email detail, expanded stats dashboards, rules, and search.
 - **Guided setup wizard** for Google Cloud and local OAuth configuration.
 - **Demo mode** with realistic seeded data for screenshots, recordings, and safe exploration.
 
@@ -151,6 +153,7 @@ inboxctl sync --full
 inboxctl inbox -n 20
 inboxctl search "from:github.com"
 inboxctl email <id>
+inboxctl thread <thread-id>
 
 # actions
 inboxctl archive <id>
@@ -164,8 +167,14 @@ inboxctl history
 # analytics
 inboxctl stats
 inboxctl stats senders --top 20
+inboxctl stats noise --top 20
 inboxctl stats newsletters
+inboxctl stats uncategorized --confidence high
+inboxctl stats unsubscribe --top 20
+inboxctl stats anomalies --since 2026-04-01
 inboxctl stats volume --period week
+inboxctl query --group-by domain --aggregate count unread_rate --sort "count desc"
+inboxctl unsubscribe newsletter@example.com --no-archive
 
 # rules
 inboxctl rules deploy

package/dist/{chunk-OLL3OA5B.js → chunk-2PN3TSVQ.js}

@@ -2643,6 +2643,14 @@ function getPeriodStart(period = "all", now2 = Date.now()) {
       return null;
   }
 }
+function extractDomain(email) {
+  const trimmed = email.trim().toLowerCase();
+  const atIndex = trimmed.lastIndexOf("@");
+  if (atIndex <= 0 || atIndex === trimmed.length - 1) {
+    return null;
+  }
+  return trimmed.slice(atIndex + 1);
+}
 function resolveLabelName(labelId) {
   return SYSTEM_LABEL_NAMES.get(labelId) || getCachedLabelName(labelId) || labelId;
 }
@@ -2654,6 +2662,50 @@ function isLikelyAutomatedSenderAddress(sender) {
   const normalized = sender.trim().toLowerCase();
   return AUTOMATED_ADDRESS_MARKERS.some((marker) => normalized.includes(marker));
 }
+function computeConfidence(row) {
+  const signals = [];
+  let score = 0;
+  const hasDefinitiveNewsletterSignal = Boolean(row.listUnsubscribe && row.listUnsubscribe.trim()) || Boolean(row.detectionReason?.includes("list_unsubscribe"));
+  if (row.listUnsubscribe && row.listUnsubscribe.trim()) {
+    signals.push("list_unsubscribe_header");
+    score += 3;
+  }
+  if (row.detectionReason?.includes("list_unsubscribe")) {
+    signals.push("newsletter_list_header");
+    score += 2;
+  }
+  if ((row.totalFromSender ?? 0) >= 20) {
+    signals.push("high_volume_sender");
+    score += 2;
+  } else if ((row.totalFromSender ?? 0) >= 5) {
+    signals.push("moderate_volume_sender");
+    score += 1;
+  }
+  if (row.detectionReason?.includes("known_sender_pattern")) {
+    signals.push("automated_sender_pattern");
+    score += 1;
+  }
+  if (row.detectionReason?.includes("bulk_sender_pattern")) {
+    signals.push("bulk_sender_pattern");
+    score += 1;
+  }
+  if ((row.totalFromSender ?? 0) <= 2 && !hasDefinitiveNewsletterSignal) {
+    signals.push("rare_sender");
+    score -= 3;
+  }
+  if (!row.detectionReason) {
+    signals.push("no_newsletter_signals");
+    score -= 2;
+  }
+  if (!row.detectionReason && !isLikelyAutomatedSenderAddress(row.sender || "")) {
+    signals.push("personal_sender_address");
+    score -= 2;
+  }
+  return {
+    confidence: score >= 3 ? "high" : score >= 0 ? "medium" : "low",
+    signals
+  };
+}
 function startOfLocalDay(now2 = Date.now()) {
   const date = new Date(now2);
   date.setHours(0, 0, 0, 0);
@@ -3841,50 +3893,6 @@ function resolveSinceTimestamp2(since) {
   }
   return parsed;
 }
-function computeConfidence(row) {
-  const signals = [];
-  let score = 0;
-  const hasDefinitiveNewsletterSignal = Boolean(row.listUnsubscribe && row.listUnsubscribe.trim()) || Boolean(row.detectionReason?.includes("list_unsubscribe"));
-  if (row.listUnsubscribe && row.listUnsubscribe.trim()) {
-    signals.push("list_unsubscribe_header");
-    score += 3;
-  }
-  if (row.detectionReason?.includes("list_unsubscribe")) {
-    signals.push("newsletter_list_header");
-    score += 2;
-  }
-  if ((row.totalFromSender ?? 0) >= 20) {
-    signals.push("high_volume_sender");
-    score += 2;
-  } else if ((row.totalFromSender ?? 0) >= 5) {
-    signals.push("moderate_volume_sender");
-    score += 1;
-  }
-  if (row.detectionReason?.includes("known_sender_pattern")) {
-    signals.push("automated_sender_pattern");
-    score += 1;
-  }
-  if (row.detectionReason?.includes("bulk_sender_pattern")) {
-    signals.push("bulk_sender_pattern");
-    score += 1;
-  }
-  if ((row.totalFromSender ?? 0) <= 2 && !hasDefinitiveNewsletterSignal) {
-    signals.push("rare_sender");
-    score -= 3;
-  }
-  if (!row.detectionReason) {
-    signals.push("no_newsletter_signals");
-    score -= 2;
-  }
-  if (!row.detectionReason && !isLikelyAutomatedSenderAddress(row.sender || "")) {
-    signals.push("personal_sender_address");
-    score -= 2;
-  }
-  return {
-    confidence: score >= 3 ? "high" : score >= 0 ? "medium" : "low",
-    signals
-  };
-}
 function buildWhereClause(options) {
   const whereParts = [
     `
@@ -3995,13 +4003,265 @@ async function getUncategorizedEmails(options = {}) {
   };
 }
 
-// src/core/stats/unsubscribe.ts
+// src/core/stats/uncategorized-senders.ts
+var SYSTEM_LABEL_IDS3 = [
+  "INBOX",
+  "UNREAD",
+  "IMPORTANT",
+  "SENT",
+  "DRAFT",
+  "SPAM",
+  "TRASH",
+  "STARRED"
+];
+var CATEGORY_LABEL_PATTERN2 = "CATEGORY\\_%";
+var MAX_EMAIL_IDS = 500;
 function toIsoString5(value) {
   if (!value) {
     return null;
   }
   return new Date(value).toISOString();
 }
+function resolveSinceTimestamp3(since) {
+  if (!since) {
+    return null;
+  }
+  const parsed = Date.parse(since);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`Invalid since value: ${since}`);
+  }
+  return parsed;
+}
+function buildWhereClause2(sinceTimestamp) {
+  const whereParts = [
+    `
+    NOT EXISTS (
+      SELECT 1
+      FROM json_each(COALESCE(e.label_ids, '[]')) AS label
+      WHERE label.value IS NOT NULL
+        AND TRIM(CAST(label.value AS TEXT)) <> ''
+        AND label.value NOT IN (${SYSTEM_LABEL_IDS3.map(() => "?").join(", ")})
+        AND label.value NOT LIKE ? ESCAPE '\\'
+    )
+    `
+  ];
+  const params = [...SYSTEM_LABEL_IDS3, CATEGORY_LABEL_PATTERN2];
+  if (sinceTimestamp !== null) {
+    whereParts.push("COALESCE(e.date, 0) >= ?");
+    params.push(sinceTimestamp);
+  }
+  return {
+    clause: whereParts.join(" AND "),
+    params
+  };
+}
+function parseEmailIds(raw) {
+  const ids = (raw || "").split("\n").map((value) => value.trim()).filter(Boolean);
+  return {
+    emailIds: ids.slice(0, MAX_EMAIL_IDS),
+    truncated: ids.length > MAX_EMAIL_IDS
+  };
+}
+function compareSenders(sortBy) {
+  return (left, right) => {
+    switch (sortBy) {
+      case "newest":
+        return (right.newestDate || "").localeCompare(left.newestDate || "") || right.emailCount - left.emailCount || right.unreadRate - left.unreadRate || left.sender.localeCompare(right.sender);
+      case "unread_rate":
+        return right.unreadRate - left.unreadRate || right.emailCount - left.emailCount || (right.newestDate || "").localeCompare(left.newestDate || "") || left.sender.localeCompare(right.sender);
+      case "email_count":
+      default:
+        return right.emailCount - left.emailCount || (right.newestDate || "").localeCompare(left.newestDate || "") || right.unreadRate - left.unreadRate || left.sender.localeCompare(right.sender);
+    }
+  };
+}
+async function getUncategorizedSenders(options = {}) {
+  await detectNewsletters();
+  const sqlite = getStatsSqlite();
+  const limit = Math.min(500, normalizeLimit(options.limit, 100));
+  const offset = Math.max(0, Math.floor(options.offset ?? 0));
+  const minEmails = Math.max(1, Math.floor(options.minEmails ?? 1));
+  const sinceTimestamp = resolveSinceTimestamp3(options.since);
+  const sortBy = options.sortBy ?? "email_count";
+  const { clause, params } = buildWhereClause2(sinceTimestamp);
+  const rows = sqlite.prepare(
+    `
+      WITH uncategorized AS (
+        SELECT
+          e.id,
+          e.from_address,
+          e.from_name,
+          e.subject,
+          e.snippet,
+          e.date,
+          e.is_read,
+          e.list_unsubscribe
+        FROM emails AS e
+        WHERE e.from_address IS NOT NULL
+          AND TRIM(e.from_address) <> ''
+          AND ${clause}
+      ),
+      sender_totals AS (
+        SELECT
+          LOWER(from_address) AS senderKey,
+          COUNT(*) AS totalFromSender
+        FROM emails
+        WHERE from_address IS NOT NULL
+          AND TRIM(from_address) <> ''
+        GROUP BY LOWER(from_address)
+      )
+      SELECT
+        grouped.sender AS sender,
+        grouped.name AS name,
+        grouped.emailCount AS emailCount,
+        grouped.unreadCount AS unreadCount,
+        grouped.newestDate AS newestDate,
+        (
+          SELECT u2.subject
+          FROM uncategorized AS u2
+          WHERE LOWER(u2.from_address) = grouped.senderKey
+          ORDER BY COALESCE(u2.date, 0) DESC, u2.id ASC
+          LIMIT 1
+        ) AS newestSubject,
+        (
+          SELECT u2.snippet
+          FROM uncategorized AS u2
+          WHERE LOWER(u2.from_address) = grouped.senderKey
+          ORDER BY COALESCE(u2.date, 0) DESC, u2.id ASC
+          LIMIT 1
+        ) AS newestSnippet,
+        (
+          SELECT u2.subject
+          FROM uncategorized AS u2
+          WHERE LOWER(u2.from_address) = grouped.senderKey
+          ORDER BY COALESCE(u2.date, 0) DESC, u2.id ASC
+          LIMIT 1 OFFSET 1
+        ) AS secondSubject,
+        grouped.detectionReason AS detectionReason,
+        grouped.newsletterUnsubscribeLink AS newsletterUnsubscribeLink,
+        grouped.emailUnsubscribeHeaders AS emailUnsubscribeHeaders,
+        COALESCE(sender_totals.totalFromSender, grouped.emailCount) AS totalFromSender,
+        (
+          SELECT GROUP_CONCAT(u2.id, '
+')
+          FROM (
+            SELECT id
+            FROM uncategorized
+            WHERE LOWER(from_address) = grouped.senderKey
+            ORDER BY COALESCE(date, 0) DESC, id ASC
+          ) AS u2
+        ) AS emailIds
+      FROM (
+        SELECT
+          LOWER(u.from_address) AS senderKey,
+          MAX(u.from_address) AS sender,
+          COALESCE(MAX(NULLIF(TRIM(u.from_name), '')), MAX(u.from_address)) AS name,
+          COUNT(*) AS emailCount,
+          SUM(CASE WHEN COALESCE(u.is_read, 0) = 0 THEN 1 ELSE 0 END) AS unreadCount,
+          MAX(u.date) AS newestDate,
+          MAX(ns.detection_reason) AS detectionReason,
+          MAX(NULLIF(TRIM(ns.unsubscribe_link), '')) AS newsletterUnsubscribeLink,
+          GROUP_CONCAT(NULLIF(TRIM(u.list_unsubscribe), ''), '
+') AS emailUnsubscribeHeaders
+        FROM uncategorized AS u
+        LEFT JOIN newsletter_senders AS ns
+          ON LOWER(ns.email) = LOWER(u.from_address)
+        GROUP BY LOWER(u.from_address)
+        HAVING COUNT(*) >= ?
+      ) AS grouped
+      LEFT JOIN sender_totals
+        ON sender_totals.senderKey = grouped.senderKey
+      `
+  ).all(...params, minEmails);
+  const filtered = rows.map((row) => {
+    const confidenceResult = computeConfidence({
+      sender: row.sender,
+      totalFromSender: row.totalFromSender,
+      detectionReason: row.detectionReason,
+      listUnsubscribe: row.emailUnsubscribeHeaders
+    });
+    const emailIds = parseEmailIds(row.emailIds);
+    const unsubscribe2 = resolveUnsubscribeTarget(
+      row.newsletterUnsubscribeLink,
+      row.emailUnsubscribeHeaders
+    );
+    const sender = row.sender?.trim() || "";
+    const domain = extractDomain(sender) || "";
+    return {
+      sender,
+      name: row.name?.trim() || sender,
+      emailCount: row.emailCount,
+      emailIds: emailIds.emailIds,
+      emailIdsTruncated: emailIds.truncated,
+      unreadCount: row.unreadCount,
+      unreadRate: roundPercent(row.unreadCount, row.emailCount),
+      newestDate: toIsoString5(row.newestDate),
+      newestSubject: row.newestSubject || null,
+      newestSnippet: row.newestSnippet || null,
+      secondSubject: row.secondSubject || null,
+      isNewsletter: Boolean(row.detectionReason || unsubscribe2.unsubscribeLink),
+      detectionReason: row.detectionReason,
+      hasUnsubscribe: Boolean(unsubscribe2.unsubscribeLink),
+      confidence: confidenceResult.confidence,
+      signals: confidenceResult.signals,
+      totalFromSender: row.totalFromSender ?? row.emailCount,
+      domain
+    };
+  }).filter((sender) => options.confidence ? sender.confidence === options.confidence : true).sort(compareSenders(sortBy));
+  const totalSenders = filtered.length;
+  const totalEmails = filtered.reduce((sum, sender) => sum + sender.emailCount, 0);
+  const byConfidence = filtered.reduce(
+    (summary, sender) => {
+      summary[sender.confidence].senders += 1;
+      summary[sender.confidence].emails += sender.emailCount;
+      return summary;
+    },
+    {
+      high: { senders: 0, emails: 0 },
+      medium: { senders: 0, emails: 0 },
+      low: { senders: 0, emails: 0 }
+    }
+  );
+  const topDomains = Array.from(
+    filtered.reduce((domains, sender) => {
+      if (!sender.domain) {
+        return domains;
+      }
+      const entry = domains.get(sender.domain) || {
+        domain: sender.domain,
+        emails: 0,
+        senders: 0
+      };
+      entry.emails += sender.emailCount;
+      entry.senders += 1;
+      domains.set(sender.domain, entry);
+      return domains;
+    }, /* @__PURE__ */ new Map())
+  ).map(([, entry]) => entry).sort(
+    (left, right) => right.emails - left.emails || right.senders - left.senders || left.domain.localeCompare(right.domain)
+  ).slice(0, 5);
+  const senders = filtered.slice(offset, offset + limit);
+  return {
+    totalSenders,
+    totalEmails,
+    returned: senders.length,
+    offset,
+    hasMore: offset + senders.length < totalSenders,
+    senders,
+    summary: {
+      byConfidence,
+      topDomains
+    }
+  };
+}
+
+// src/core/stats/unsubscribe.ts
+function toIsoString6(value) {
+  if (!value) {
+    return null;
+  }
+  return new Date(value).toISOString();
+}
 function roundImpactScore(messageCount, unreadRate) {
   return Math.round(messageCount * unreadRate * 10 / 100) / 10;
 }
@@ -4048,8 +4308,8 @@ async function getUnsubscribeSuggestions(options = {}) {
       unreadCount: row.unreadCount,
       unreadRate,
       readRate,
-      lastRead: toIsoString5(row.lastRead),
-      lastReceived: toIsoString5(row.lastReceived),
+      lastRead: toIsoString6(row.lastRead),
+      lastReceived: toIsoString6(row.lastReceived),
       unsubscribeLink: unsubscribe2.unsubscribeLink,
       unsubscribeMethod: unsubscribe2.unsubscribeMethod,
       impactScore: roundImpactScore(row.messageCount, unreadRate),
@@ -5552,7 +5812,7 @@ async function getSyncStatus() {
 
 // src/mcp/server.ts
 var DAY_MS4 = 24 * 60 * 60 * 1e3;
-var MCP_VERSION = "0.3.0";
+var MCP_VERSION = "0.4.0";
 var MCP_TOOLS = [
   "search_emails",
   "get_email",
@@ -5571,6 +5831,7 @@ var MCP_TOOLS = [
   "get_sender_stats",
   "get_newsletter_senders",
   "get_uncategorized_emails",
+  "get_uncategorized_senders",
   "review_categorized",
   "query_emails",
   "get_noise_senders",
@@ -6068,6 +6329,31 @@ async function createMcpServer() {
       since
     }))
   );
+  server.registerTool(
+    "get_uncategorized_senders",
+    {
+      description: "Return uncategorized emails grouped by sender so AI clients can categorize at sender-level instead of one email at a time.",
+      inputSchema: {
+        limit: z4.number().int().positive().max(500).optional().describe("Max senders per page. Default 100."),
+        offset: z4.number().int().min(0).optional().describe("Number of senders to skip for pagination."),
+        min_emails: z4.number().int().positive().optional().describe("Only include senders with at least this many uncategorized emails."),
+        confidence: z4.enum(["high", "medium", "low"]).optional().describe("Filter senders by the confidence score inferred from sender signals."),
+        since: z4.string().min(1).optional().describe("Only include uncategorized emails on or after this ISO date."),
+        sort_by: z4.enum(["email_count", "newest", "unread_rate"]).optional().describe("Sort senders by email volume, most recent email, or unread rate.")
+      },
+      annotations: {
+        readOnlyHint: true
+      }
+    },
+    toolHandler(async ({ limit, offset, min_emails, confidence, since, sort_by }) => getUncategorizedSenders({
+      limit,
+      offset,
+      minEmails: min_emails,
+      confidence,
+      since,
+      sortBy: sort_by
+    }))
+  );
   server.registerTool(
     "review_categorized",
     {
@@ -6375,9 +6661,15 @@ async function createMcpServer() {
       [
         "First, inspect these data sources:",
         "- `rules://deployed` \u2014 existing rules (avoid duplicates)",
+        "- `query_emails` \u2014 find high-volume domains, unread-heavy clusters, and labeling opportunities",
         "- `get_noise_senders` \u2014 high-volume low-read senders",
         "- `get_newsletter_senders` \u2014 detected newsletters and mailing lists",
         "",
+        "Useful `query_emails` patterns before drafting rules:",
+        '- `group_by: "domain"`, `aggregates: ["count", "unread_rate"]`, `having: { count: { gte: 20 } }`',
+        '- `group_by: "domain"`, `aggregates: ["count", "unread_rate"]`, `having: { unread_rate: { gte: 80 } }`',
+        "- Cross-check the results against `list_rules` and `list_filters` before proposing new automation.",
+        "",
         "For each recommendation, generate complete YAML using this schema:",
         "",
         "  name: kebab-case-name          # lowercase, hyphens only",
@@ -6454,14 +6746,16 @@ async function createMcpServer() {
       "Categorise uncategorised emails in the user's inbox.",
       [
         "Step 1 \u2014 Gather data:",
-        "  Use `get_uncategorized_emails` (start with limit 100).",
-        "  If totalUncategorized is more than 500, ask whether to process the recent batch or paginate through the full backlog.",
+        "  Use `get_uncategorized_senders` first (start with limit 100).",
+        "  This groups uncategorized emails by sender and is the primary way to process large inbox backlogs efficiently.",
+        "  Use `get_uncategorized_emails` only when you need to inspect specific emails from an ambiguous sender.",
+        "  If totalSenders is more than 500, ask whether to process the recent batch or paginate through the full backlog.",
         "  Use `get_noise_senders` for sender context.",
         "  Use `get_unsubscribe_suggestions` for likely unsubscribe candidates.",
         "  Use `get_labels` to see what labels already exist.",
         "  Use `rules://deployed` to avoid duplicating existing automation.",
         "",
-        "Step 2 \u2014 Assign each email a category:",
+        "Step 2 \u2014 Assign each sender a category:",
         "  Receipts \u2014 purchase confirmations, invoices, payment notifications",
         "  Shipping \u2014 delivery tracking, dispatch notices, shipping updates",
         "  Newsletters \u2014 editorial content, digests, weekly roundups",
@@ -6473,28 +6767,29 @@ async function createMcpServer() {
         "  Important \u2014 personal or work email requiring attention",
         "",
         "Step 3 \u2014 Present the categorisation plan:",
-        "  Group emails by assigned category.",
-        "  For each group show: count, senders involved, sample subjects.",
+        "  Group senders by assigned category.",
+        "  For each group show: sender count, total emails affected, senders involved, sample subjects.",
         "  Note confidence level: HIGH (clear pattern), MEDIUM (reasonable guess), LOW (uncertain).",
-        "  Flag any LOW confidence items for the user to decide.",
+        "  Flag any LOW confidence senders for the user to decide.",
         "  Present the confidence breakdown: X HIGH (auto-apply), Y MEDIUM (label only), Z LOW (review queue).",
-        "  If any LOW confidence emails are present, note why they were flagged from the `signals` array.",
+        "  If any LOW confidence senders are present, note why they were flagged from the `signals` array.",
         "",
         "Step 3.5 \u2014 Apply confidence gating:",
         "  HIGH confidence \u2014 safe to apply directly (label, mark_read, archive as appropriate).",
         "  MEDIUM confidence \u2014 apply the category label only. Do not archive. Keep the email visible in the inbox.",
         "  LOW confidence \u2014 apply only the label `inboxctl/Review`. Do not archive or mark read.",
-        "  These emails need human review before any further action.",
+        "  These senders need human review before any further action.",
         "",
         "Step 4 \u2014 Apply with user approval:",
         "  Create labels for any new categories (use `create_label`).",
-        "  Use `batch_apply_actions` to apply labels in one call.",
+        "  Use `batch_apply_actions` to apply labels in one call, grouping by action set and reusing each sender's `emailIds`.",
         "  For Newsletters and Promotions with high unread rates, suggest mark_read + archive or `unsubscribe` when a link is available.",
         "  For Receipts/Shipping/Notifications, suggest mark_read only (keep in inbox).",
         "  For Important, do not mark read or archive.",
         "",
         "Step 5 \u2014 Paginate if needed:",
         "  If hasMore is true, ask whether to continue with the next page using offset.",
+        "  Each new page is a new set of senders, not more emails from the same senders.",
         "  Reuse the same sender categorisations on later pages instead of re-evaluating known senders.",
         "",
         "Step 6 \u2014 Suggest ongoing rules:",
@@ -6636,10 +6931,17 @@ export {
   markUnread,
   forwardEmail,
   undoRun,
-  getLabelDistribution,
+  getThread,
+  unsubscribe,
   getNewsletters,
+  reviewCategorized,
+  getLabelDistribution,
+  getNoiseSenders,
+  queryEmails,
   getTopSenders,
   getSenderStats,
+  getUncategorizedSenders,
+  getUnsubscribeSuggestions,
   getVolumeByPeriod,
   getInboxOverview,
   loadRuleFile,
@@ -6668,4 +6970,4 @@ export {
   createMcpServer,
   startMcpServer
 };
-//# sourceMappingURL=chunk-OLL3OA5B.js.map
+//# sourceMappingURL=chunk-2PN3TSVQ.js.map