inboxctl 0.2.0 → 0.3.0

package/dist/{chunk-NUN2WRBN.js → chunk-OLL3OA5B.js}

@@ -8,7 +8,7 @@ var __export = (target, all) => {
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z as z2 } from "zod";
+import { z as z4 } from "zod";
 
 // src/core/actions/audit.ts
 import { randomUUID } from "crypto";
@@ -2549,8 +2549,46 @@ async function unsubscribe(options) {
   };
 }
 
+// src/core/stats/anomalies.ts
+import { z } from "zod";
+
 // src/core/stats/common.ts
 var DAY_MS = 24 * 60 * 60 * 1e3;
+var SYSTEM_LABEL_IDS = [
+  "INBOX",
+  "UNREAD",
+  "STARRED",
+  "IMPORTANT",
+  "SENT",
+  "DRAFT",
+  "TRASH",
+  "SPAM",
+  "ALL_MAIL",
+  "SNOOZED",
+  "CHAT",
+  "CATEGORY_PERSONAL",
+  "CATEGORY_SOCIAL",
+  "CATEGORY_PROMOTIONS",
+  "CATEGORY_UPDATES",
+  "CATEGORY_FORUMS"
+];
+var CATEGORY_LABEL_PREFIX = "CATEGORY_";
+var SYSTEM_LABEL_ID_SET = new Set(SYSTEM_LABEL_IDS);
+var AUTOMATED_ADDRESS_MARKERS = [
+  "noreply",
+  "no-reply",
+  "no_reply",
+  "newsletter",
+  "notifications",
+  "notification",
+  "mailer",
+  "info@",
+  "hello@",
+  "support@",
+  "marketing",
+  "promo",
+  "updates"
+];
 var SYSTEM_LABEL_NAMES = /* @__PURE__ */ new Map([
   ["INBOX", "Inbox"],
   ["UNREAD", "Unread"],
@@ -2608,6 +2646,14 @@ function getPeriodStart(period = "all", now2 = Date.now()) {
 function resolveLabelName(labelId) {
   return SYSTEM_LABEL_NAMES.get(labelId) || getCachedLabelName(labelId) || labelId;
 }
+function isUserLabel(labelId) {
+  const trimmed = labelId.trim();
+  return trimmed.length > 0 && !SYSTEM_LABEL_ID_SET.has(trimmed) && !trimmed.startsWith(CATEGORY_LABEL_PREFIX);
+}
+function isLikelyAutomatedSenderAddress(sender) {
+  const normalized = sender.trim().toLowerCase();
+  return AUTOMATED_ADDRESS_MARKERS.some((marker) => normalized.includes(marker));
+}
 function startOfLocalDay(now2 = Date.now()) {
   const date = new Date(now2);
   date.setHours(0, 0, 0, 0);
@@ -2627,28 +2673,6 @@ function startOfLocalMonth(now2 = Date.now()) {
   return date.getTime();
 }
 
-// src/core/stats/labels.ts
-async function getLabelDistribution() {
-  const sqlite = getStatsSqlite();
-  const rows = sqlite.prepare(
-    `
-      SELECT
-        label.value AS labelId,
-        COUNT(*) AS totalMessages,
-        SUM(CASE WHEN e.is_read = 0 THEN 1 ELSE 0 END) AS unreadMessages
-      FROM emails AS e, json_each(e.label_ids) AS label
-      GROUP BY label.value
-      ORDER BY totalMessages DESC, unreadMessages DESC, label.value ASC
-      `
-  ).all();
-  return rows.map((row) => ({
-    labelId: row.labelId,
-    labelName: resolveLabelName(row.labelId),
-    totalMessages: row.totalMessages,
-    unreadMessages: row.unreadMessages
-  }));
-}
-
 // src/core/stats/newsletters.ts
 import { randomUUID as randomUUID2 } from "crypto";
 var KNOWN_NEWSLETTER_LOCAL_PART = /^(newsletter|digest|noreply|no-reply|updates|news)([+._-].*)?$/i;
@@ -2812,8 +2836,277 @@ async function getNewsletters(options = {}) {
   return rows.map(mapNewsletterRow);
 }
 
-// src/core/stats/noise.ts
+// src/core/stats/anomalies.ts
 var DAY_MS2 = 24 * 60 * 60 * 1e3;
+var BULK_LABELS = /* @__PURE__ */ new Set([
+  "newsletter",
+  "newsletters",
+  "promotion",
+  "promotions",
+  "social"
+]);
+var reviewCategorizedInputSchema = z.object({
+  since: z.string().min(1).optional(),
+  limit: z.number().int().positive().max(200).optional()
+}).strict();
+function toIsoString(value) {
+  if (!value) {
+    return null;
+  }
+  return new Date(value).toISOString();
+}
+function parseJsonArray3(raw) {
+  if (!raw) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((value) => typeof value === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function parseActions(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function resolveSinceTimestamp(since) {
+  if (!since) {
+    return Date.now() - 7 * DAY_MS2;
+  }
+  const parsed = Date.parse(since);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`Invalid since value: ${since}`);
+  }
+  return parsed;
+}
+function isArchived(actions, beforeLabelIds, afterLabelIds) {
+  if (actions.some((action) => action.type === "archive")) {
+    return true;
+  }
+  return beforeLabelIds.includes("INBOX") && !afterLabelIds.includes("INBOX");
+}
+function resolveAssignedLabel(actions, beforeLabelIds, afterLabelIds) {
+  const labelAction = actions.find(
+    (action) => action.type === "label" && typeof action.label === "string" && action.label.trim().length > 0
+  );
+  if (labelAction) {
+    return labelAction.label.trim();
+  }
+  const beforeUserLabels = new Set(beforeLabelIds.filter(isUserLabel));
+  const afterUserLabels = afterLabelIds.filter(isUserLabel);
+  const addedLabel = afterUserLabels.find((label) => !beforeUserLabels.has(label));
+  return addedLabel || afterUserLabels[0] || null;
+}
+function resolvePrimaryAction(actions) {
+  if (actions.some((action) => action.type === "archive")) {
+    return "archive";
+  }
+  if (actions.some((action) => action.type === "label")) {
+    return "label";
+  }
+  return actions[0]?.type || "unknown";
+}
+function summarizeReview(totalReviewed, anomalyCount, highCount, mediumCount) {
+  if (anomalyCount === 0) {
+    return `Reviewed ${totalReviewed} recently categorised emails. Found no potential misclassifications.`;
+  }
+  const severityParts = [];
+  if (highCount > 0) {
+    severityParts.push(`${highCount} high severity`);
+  }
+  if (mediumCount > 0) {
+    severityParts.push(`${mediumCount} medium`);
+  }
+  return `Reviewed ${totalReviewed} recently categorised emails. Found ${anomalyCount} potential misclassifications (${severityParts.join(", ")}).`;
+}
+function detectAnomaly(row) {
+  const actions = parseActions(row.appliedActions);
+  const beforeLabelIds = parseJsonArray3(row.beforeLabelIds);
+  const afterLabelIds = parseJsonArray3(row.afterLabelIds);
+  const archived = isArchived(actions, beforeLabelIds, afterLabelIds);
+  const assignedLabel = resolveAssignedLabel(actions, beforeLabelIds, afterLabelIds);
+  const action = resolvePrimaryAction(actions);
+  const totalFromSender = row.totalFromSender ?? 0;
+  const hasNewsletterSignals = Boolean(row.detectionReason) || Boolean(row.listUnsubscribe?.trim());
+  const isBulkLabel = assignedLabel ? BULK_LABELS.has(assignedLabel.toLowerCase()) : false;
+  const automatedSender = isLikelyAutomatedSenderAddress(row.sender || "");
+  const undoAvailable = row.runDryRun !== 1 && row.runStatus !== "undone" && row.runUndoneAt === null && row.itemUndoneAt === null;
+  if (archived && totalFromSender <= 3) {
+    return {
+      emailId: row.emailId,
+      from: row.sender || "",
+      subject: row.subject || "",
+      date: toIsoString(row.date),
+      assignedLabel: assignedLabel || "Unlabeled",
+      action,
+      runId: row.runId,
+      severity: "high",
+      rule: "rare_sender_archived",
+      reason: `Archived email from a rare sender with only ${totalFromSender} total email${totalFromSender === 1 ? "" : "s"}. Rare senders should be reviewed before archiving.`,
+      undoAvailable
+    };
+  }
+  if (isBulkLabel && !hasNewsletterSignals) {
+    return {
+      emailId: row.emailId,
+      from: row.sender || "",
+      subject: row.subject || "",
+      date: toIsoString(row.date),
+      assignedLabel: assignedLabel || "Unlabeled",
+      action,
+      runId: row.runId,
+      severity: "high",
+      rule: "no_newsletter_signals_as_newsletter",
+      reason: `Labeled as ${assignedLabel} but sender has no List-Unsubscribe header and no newsletter detection signals. Sender has only sent ${totalFromSender} total email${totalFromSender === 1 ? "" : "s"}.`,
+      undoAvailable
+    };
+  }
+  if (archived && !automatedSender && totalFromSender < 5) {
+    return {
+      emailId: row.emailId,
+      from: row.sender || "",
+      subject: row.subject || "",
+      date: toIsoString(row.date),
+      assignedLabel: assignedLabel || "Unlabeled",
+      action,
+      runId: row.runId,
+      severity: "high",
+      rule: "personal_address_archived",
+      reason: `Archived email from a likely personal sender address with fewer than 5 total emails. This address does not look automated and should stay visible.`,
+      undoAvailable
+    };
+  }
+  if (isBulkLabel && totalFromSender < 5) {
+    return {
+      emailId: row.emailId,
+      from: row.sender || "",
+      subject: row.subject || "",
+      date: toIsoString(row.date),
+      assignedLabel: assignedLabel || "Unlabeled",
+      action,
+      runId: row.runId,
+      severity: "medium",
+      rule: "low_volume_bulk_label",
+      reason: `Labeled as ${assignedLabel} even though the sender has only ${totalFromSender} total email${totalFromSender === 1 ? "" : "s"}. Bulk labels are safer for higher-volume senders.`,
+      undoAvailable
+    };
+  }
+  if (archived && totalFromSender === 1) {
+    return {
+      emailId: row.emailId,
+      from: row.sender || "",
+      subject: row.subject || "",
+      date: toIsoString(row.date),
+      assignedLabel: assignedLabel || "Unlabeled",
+      action,
+      runId: row.runId,
+      severity: "medium",
+      rule: "first_time_sender_archived",
+      reason: "Archived an email from a first-time sender. First-time senders are better surfaced for review before cleanup.",
+      undoAvailable
+    };
+  }
+  return null;
+}
+async function reviewCategorized(options = {}) {
+  const parsed = reviewCategorizedInputSchema.parse(options);
+  await detectNewsletters();
+  const sqlite = getStatsSqlite();
+  const sinceTimestamp = resolveSinceTimestamp(parsed.since);
+  const limit = Math.min(200, normalizeLimit(parsed.limit, 50));
+  const rows = sqlite.prepare(
+    `
+      SELECT
+        ei.email_id AS emailId,
+        e.from_address AS sender,
+        e.subject AS subject,
+        e.date AS date,
+        e.list_unsubscribe AS listUnsubscribe,
+        ei.before_label_ids AS beforeLabelIds,
+        ei.after_label_ids AS afterLabelIds,
+        ei.applied_actions AS appliedActions,
+        ei.executed_at AS executedAt,
+        ei.undone_at AS itemUndoneAt,
+        ei.run_id AS runId,
+        er.status AS runStatus,
+        er.dry_run AS runDryRun,
+        er.undone_at AS runUndoneAt,
+        ns.detection_reason AS detectionReason,
+        sender_stats.totalFromSender AS totalFromSender
+      FROM execution_items AS ei
+      INNER JOIN emails AS e
+        ON e.id = ei.email_id
+      INNER JOIN execution_runs AS er
+        ON er.id = ei.run_id
+      LEFT JOIN newsletter_senders AS ns
+        ON LOWER(ns.email) = LOWER(e.from_address)
+      LEFT JOIN (
+        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)
+      ) AS sender_stats
+        ON sender_stats.senderKey = LOWER(e.from_address)
+      WHERE ei.status = 'applied'
+        AND er.status IN ('applied', 'partial')
+        AND COALESCE(er.dry_run, 0) = 0
+        AND er.undone_at IS NULL
+        AND ei.undone_at IS NULL
+        AND COALESCE(ei.executed_at, 0) >= ?
+      ORDER BY COALESCE(ei.executed_at, 0) DESC, ei.email_id ASC
+      `
+  ).all(sinceTimestamp);
+  const reviewedRows = rows.filter((row) => {
+    const actions = parseActions(row.appliedActions);
+    const beforeLabelIds = parseJsonArray3(row.beforeLabelIds);
+    const afterLabelIds = parseJsonArray3(row.afterLabelIds);
+    return actions.length > 0 && (resolveAssignedLabel(actions, beforeLabelIds, afterLabelIds) !== null || isArchived(actions, beforeLabelIds, afterLabelIds));
+  });
+  const anomalies = reviewedRows.map((row) => detectAnomaly(row)).filter((anomaly) => anomaly !== null).sort(
+    (left, right) => (left.severity === "high" ? 1 : 0) === (right.severity === "high" ? 1 : 0) ? (right.date || "").localeCompare(left.date || "") || left.emailId.localeCompare(right.emailId) : left.severity === "high" ? -1 : 1
+  );
+  const highCount = anomalies.filter((anomaly) => anomaly.severity === "high").length;
+  const mediumCount = anomalies.filter((anomaly) => anomaly.severity === "medium").length;
+  return {
+    anomalies: anomalies.slice(0, limit),
+    totalReviewed: reviewedRows.length,
+    anomalyCount: anomalies.length,
+    summary: summarizeReview(reviewedRows.length, anomalies.length, highCount, mediumCount)
+  };
+}
+
+// src/core/stats/labels.ts
+async function getLabelDistribution() {
+  const sqlite = getStatsSqlite();
+  const rows = sqlite.prepare(
+    `
+      SELECT
+        label.value AS labelId,
+        COUNT(*) AS totalMessages,
+        SUM(CASE WHEN e.is_read = 0 THEN 1 ELSE 0 END) AS unreadMessages
+      FROM emails AS e, json_each(e.label_ids) AS label
+      GROUP BY label.value
+      ORDER BY totalMessages DESC, unreadMessages DESC, label.value ASC
+      `
+  ).all();
+  return rows.map((row) => ({
+    labelId: row.labelId,
+    labelName: resolveLabelName(row.labelId),
+    totalMessages: row.totalMessages,
+    unreadMessages: row.unreadMessages
+  }));
+}
+
+// src/core/stats/noise.ts
+var DAY_MS3 = 24 * 60 * 60 * 1e3;
 var SUGGESTED_CATEGORY_RULES = [
   { category: "Receipts", keywords: ["receipt", "invoice", "payment", "order"] },
   { category: "Shipping", keywords: ["shipping", "tracking", "delivery", "dispatch"] },
@@ -2822,7 +3115,7 @@ var SUGGESTED_CATEGORY_RULES = [
   { category: "Promotions", keywords: ["promo", "offer", "deal", "sale", "marketing"] },
   { category: "Social", keywords: ["linkedin", "facebook", "twitter", "social"] }
 ];
-function toIsoString(value) {
+function toIsoString2(value) {
   if (!value) {
     return null;
   }
@@ -2861,7 +3154,7 @@ async function getNoiseSenders(options = {}) {
   const limit = Math.min(50, normalizeLimit(options.limit, 20));
   const minNoiseScore = options.minNoiseScore ?? 5;
   const activeDays = Math.max(1, Math.floor(options.activeDays ?? 90));
-  const activeSince = Date.now() - activeDays * DAY_MS2;
+  const activeSince = Date.now() - activeDays * DAY_MS3;
   const sortBy = options.sortBy ?? "noise_score";
   const rows = sqlite.prepare(
     `
@@ -2920,7 +3213,7 @@ async function getNoiseSenders(options = {}) {
       unreadRate,
       noiseScore,
       allTimeNoiseScore,
-      lastSeen: toIsoString(row.lastSeen),
+      lastSeen: toIsoString2(row.lastSeen),
       isNewsletter: row.isNewsletter === 1,
       hasUnsubscribeLink: Boolean(unsubscribe2.unsubscribeLink),
       unsubscribeLink: unsubscribe2.unsubscribeLink,
@@ -2930,6 +3223,427 @@ async function getNoiseSenders(options = {}) {
   return { senders };
 }
 
+// src/core/stats/query.ts
+import { z as z2 } from "zod";
+var QUERY_EMAIL_GROUP_BY_VALUES = [
+  "sender",
+  "domain",
+  "label",
+  "year_month",
+  "year_week",
+  "day_of_week",
+  "is_read",
+  "is_newsletter"
+];
+var QUERY_EMAIL_AGGREGATE_VALUES = [
+  "count",
+  "unread_count",
+  "read_count",
+  "unread_rate",
+  "oldest",
+  "newest",
+  "sender_count"
+];
+var QUERY_EMAIL_HAVING_FIELDS = [
+  "count",
+  "unread_count",
+  "unread_rate",
+  "sender_count"
+];
+var CATEGORY_LABEL_LIKE_PATTERN = `${CATEGORY_LABEL_PREFIX.replace(/_/g, "\\_")}%`;
+var SYSTEM_LABEL_SQL = SYSTEM_LABEL_IDS.map((label) => `'${label}'`).join(", ");
+var DOMAIN_SQL = `
+  LOWER(
+    CASE
+      WHEN INSTR(COALESCE(e.from_address, ''), '@') > 0
+        THEN SUBSTR(e.from_address, INSTR(e.from_address, '@') + 1)
+      ELSE ''
+    END
+  )
+`;
+var queryEmailsFiltersSchema = z2.object({
+  from: z2.string().optional(),
+  from_contains: z2.string().optional(),
+  domain: z2.string().optional(),
+  domain_contains: z2.string().optional(),
+  subject_contains: z2.string().optional(),
+  date_after: z2.string().optional(),
+  date_before: z2.string().optional(),
+  is_read: z2.boolean().optional(),
+  is_newsletter: z2.boolean().optional(),
+  has_label: z2.boolean().optional(),
+  label: z2.string().optional(),
+  has_unsubscribe: z2.boolean().optional(),
+  min_sender_messages: z2.number().int().positive().optional()
+}).strict();
+var havingConditionSchema = z2.object({
+  gte: z2.number().optional(),
+  lte: z2.number().optional()
+}).strict().refine(
+  (value) => value.gte !== void 0 || value.lte !== void 0,
+  { message: "Provide at least one of gte or lte." }
+);
+var queryEmailsHavingSchema = z2.object({
+  count: havingConditionSchema.optional(),
+  unread_count: havingConditionSchema.optional(),
+  unread_rate: havingConditionSchema.optional(),
+  sender_count: havingConditionSchema.optional()
+}).strict();
+var queryEmailsInputSchema = z2.object({
+  filters: queryEmailsFiltersSchema.optional(),
+  group_by: z2.enum(QUERY_EMAIL_GROUP_BY_VALUES).optional(),
+  aggregates: z2.array(z2.enum(QUERY_EMAIL_AGGREGATE_VALUES)).min(1).optional(),
+  having: queryEmailsHavingSchema.optional(),
+  order_by: z2.string().optional(),
+  limit: z2.number().int().positive().max(500).optional()
+}).strict();
+var QUERY_EMAILS_FIELD_SCHEMA = {
+  description: "Available fields for the query_emails tool.",
+  filters: {
+    from: { type: "string", description: "Exact sender email (case-insensitive)" },
+    from_contains: { type: "string", description: "Partial match on sender email" },
+    domain: { type: "string", description: "Exact sender domain" },
+    domain_contains: { type: "string", description: "Partial match on sender domain" },
+    subject_contains: { type: "string", description: "Partial match on subject line" },
+    date_after: { type: "string", description: "ISO date \u2014 emails after this date" },
+    date_before: { type: "string", description: "ISO date \u2014 emails before this date" },
+    is_read: { type: "boolean", description: "Filter by read/unread state" },
+    is_newsletter: { type: "boolean", description: "Sender detected as newsletter" },
+    has_label: { type: "boolean", description: "Has any user-applied label" },
+    label: { type: "string", description: "Has this specific label" },
+    has_unsubscribe: { type: "boolean", description: "Has List-Unsubscribe header" },
+    min_sender_messages: { type: "integer", description: "Sender has at least this many total emails" }
+  },
+  group_by: [
+    { value: "sender", description: "Group by sender email address" },
+    { value: "domain", description: "Group by sender domain" },
+    { value: "label", description: "Group by applied label (expands multi-label emails)" },
+    { value: "year_month", description: "Group by month (YYYY-MM)" },
+    { value: "year_week", description: "Group by week (YYYY-WNN)" },
+    { value: "day_of_week", description: "Group by day of week (0=Sunday)" },
+    { value: "is_read", description: "Group by read/unread state" },
+    { value: "is_newsletter", description: "Group by newsletter detection" }
+  ],
+  aggregates: [
+    { value: "count", description: "Number of emails" },
+    { value: "unread_count", description: "Number of unread emails" },
+    { value: "read_count", description: "Number of read emails" },
+    { value: "unread_rate", description: "Percentage of emails that are unread" },
+    { value: "oldest", description: "Earliest email date (ISO string)" },
+    { value: "newest", description: "Latest email date (ISO string)" },
+    { value: "sender_count", description: "Count of distinct senders" }
+  ],
+  having_fields: [...QUERY_EMAIL_HAVING_FIELDS],
+  example_queries: [
+    {
+      description: "Monthly volume trend for Amazon",
+      query: {
+        filters: { domain_contains: "amazon" },
+        group_by: "year_month",
+        aggregates: ["count", "unread_rate"],
+        order_by: "year_month asc"
+      }
+    },
+    {
+      description: "Domains with 95%+ unread rate and 50+ emails",
+      query: {
+        group_by: "domain",
+        aggregates: ["count", "unread_rate"],
+        having: { count: { gte: 50 }, unread_rate: { gte: 95 } }
+      }
+    },
+    {
+      description: "What day of the week gets the most email?",
+      query: {
+        group_by: "day_of_week",
+        aggregates: ["count", "sender_count"]
+      }
+    }
+  ]
+};
+var GROUP_BY_SQL_MAP = {
+  sender: "LOWER(COALESCE(e.from_address, ''))",
+  domain: DOMAIN_SQL,
+  label: "CAST(grouped_label.value AS TEXT)",
+  year_month: "STRFTIME('%Y-%m', e.date / 1000, 'unixepoch')",
+  year_week: "STRFTIME('%Y-W%W', e.date / 1000, 'unixepoch')",
+  day_of_week: "CAST(STRFTIME('%w', e.date / 1000, 'unixepoch') AS INTEGER)",
+  is_read: "COALESCE(e.is_read, 0)",
+  is_newsletter: "CASE WHEN ns.email IS NOT NULL THEN 1 ELSE 0 END"
+};
+var AGGREGATE_SQL_MAP = {
+  count: "COUNT(*)",
+  unread_count: "SUM(CASE WHEN COALESCE(e.is_read, 0) = 0 THEN 1 ELSE 0 END)",
+  read_count: "SUM(CASE WHEN COALESCE(e.is_read, 0) = 1 THEN 1 ELSE 0 END)",
+  unread_rate: `
+    ROUND(
+      CASE
+        WHEN COUNT(*) = 0 THEN 0
+        ELSE 100.0 * SUM(CASE WHEN COALESCE(e.is_read, 0) = 0 THEN 1 ELSE 0 END) / COUNT(*)
+      END,
+      1
+    )
+  `,
+  oldest: "MIN(e.date)",
+  newest: "MAX(e.date)",
+  sender_count: `
+    COUNT(
+      DISTINCT CASE
+        WHEN e.from_address IS NOT NULL AND TRIM(e.from_address) <> ''
+          THEN LOWER(e.from_address)
+        ELSE NULL
+      END
+    )
+  `
+};
+function userLabelPredicate(column) {
+  return `
+    ${column} IS NOT NULL
+    AND TRIM(CAST(${column} AS TEXT)) <> ''
+    AND CAST(${column} AS TEXT) NOT IN (${SYSTEM_LABEL_SQL})
+    AND CAST(${column} AS TEXT) NOT LIKE '${CATEGORY_LABEL_LIKE_PATTERN}' ESCAPE '\\'
+  `;
+}
+function toIsoString3(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return null;
+  }
+  return new Date(value).toISOString();
+}
+function normalizeGroupValue(groupBy, value) {
+  switch (groupBy) {
+    case "is_read":
+    case "is_newsletter":
+      return Number(value ?? 0) === 1;
+    case "day_of_week":
+      return Number(value ?? 0);
+    case "sender":
+    case "domain":
+    case "label":
+    case "year_month":
+    case "year_week":
+      return typeof value === "string" ? value : value == null ? null : String(value);
+  }
+}
+function normalizeAggregateValue(aggregate, value) {
+  switch (aggregate) {
+    case "oldest":
+    case "newest":
+      return toIsoString3(value);
+    case "count":
+    case "unread_count":
+    case "read_count":
+    case "sender_count":
+      return Number(value ?? 0);
+    case "unread_rate":
+      return Number(value ?? 0);
+  }
+}
+function parseDateFilter(field, value) {
+  const timestamp = Date.parse(value);
+  if (Number.isNaN(timestamp)) {
+    throw new Error(`Invalid ${field} value: ${value}`);
+  }
+  return timestamp;
+}
+function resolveAggregates(aggregates) {
+  return Array.from(new Set(aggregates && aggregates.length > 0 ? aggregates : ["count"]));
+}
+function resolveOrderBy(orderBy, groupBy, aggregates) {
+  const defaultField = aggregates.includes("count") ? "count" : aggregates[0];
+  const rawValue = (orderBy || `${defaultField} desc`).trim();
+  const match = rawValue.match(/^([a-z_]+)\s+(asc|desc)$/i);
+  if (!match) {
+    throw new Error(`Invalid order_by value: ${rawValue}`);
+  }
+  const [, field, direction] = match;
+  const allowedFields = new Set(aggregates);
+  if (groupBy) {
+    allowedFields.add(groupBy);
+  }
+  if (!allowedFields.has(field)) {
+    throw new Error(`Invalid order_by field: ${field}`);
+  }
+  return `${field} ${direction.toLowerCase()}`;
+}
+function buildWhereClauses(filters, groupBy) {
+  const whereParts = [];
+  const params = [];
+  if (filters.from !== void 0) {
+    whereParts.push("LOWER(COALESCE(e.from_address, '')) = LOWER(?)");
+    params.push(filters.from);
+  }
+  if (filters.from_contains !== void 0) {
+    whereParts.push("LOWER(COALESCE(e.from_address, '')) LIKE '%' || LOWER(?) || '%'");
+    params.push(filters.from_contains);
+  }
+  if (filters.domain !== void 0) {
+    whereParts.push(`${DOMAIN_SQL} = LOWER(?)`);
+    params.push(filters.domain);
+  }
+  if (filters.domain_contains !== void 0) {
+    whereParts.push(`${DOMAIN_SQL} LIKE '%' || LOWER(?) || '%'`);
+    params.push(filters.domain_contains);
+  }
+  if (filters.subject_contains !== void 0) {
+    whereParts.push("LOWER(COALESCE(e.subject, '')) LIKE '%' || LOWER(?) || '%'");
+    params.push(filters.subject_contains);
+  }
+  if (filters.date_after !== void 0) {
+    whereParts.push("COALESCE(e.date, 0) >= ?");
+    params.push(parseDateFilter("date_after", filters.date_after));
+  }
+  if (filters.date_before !== void 0) {
+    whereParts.push("COALESCE(e.date, 0) <= ?");
+    params.push(parseDateFilter("date_before", filters.date_before));
+  }
+  if (filters.is_read !== void 0) {
+    whereParts.push("COALESCE(e.is_read, 0) = ?");
+    params.push(filters.is_read ? 1 : 0);
+  }
+  if (filters.is_newsletter !== void 0) {
+    whereParts.push(filters.is_newsletter ? "ns.email IS NOT NULL" : "ns.email IS NULL");
+  }
+  if (filters.has_label !== void 0) {
+    whereParts.push(
+      filters.has_label ? `EXISTS (
+            SELECT 1
+            FROM json_each(COALESCE(e.label_ids, '[]')) AS label_filter
+            WHERE ${userLabelPredicate("label_filter.value")}
+          )` : `NOT EXISTS (
+            SELECT 1
+            FROM json_each(COALESCE(e.label_ids, '[]')) AS label_filter
+            WHERE ${userLabelPredicate("label_filter.value")}
+          )`
+    );
+  }
+  if (filters.label !== void 0) {
+    whereParts.push(`
+      EXISTS (
+        SELECT 1
+        FROM json_each(COALESCE(e.label_ids, '[]')) AS label_filter
+        WHERE LOWER(CAST(label_filter.value AS TEXT)) = LOWER(?)
+      )
+    `);
+    params.push(filters.label);
+  }
+  if (filters.has_unsubscribe !== void 0) {
+    whereParts.push(
+      filters.has_unsubscribe ? "NULLIF(TRIM(e.list_unsubscribe), '') IS NOT NULL" : "(e.list_unsubscribe IS NULL OR TRIM(e.list_unsubscribe) = '')"
+    );
+  }
+  if (filters.min_sender_messages !== void 0) {
+    whereParts.push("COALESCE(sender_stats.totalFromSender, 0) >= ?");
+    params.push(filters.min_sender_messages);
+  }
+  if (groupBy === "label") {
+    whereParts.push(userLabelPredicate("grouped_label.value"));
+  }
+  return {
+    sql: whereParts.length > 0 ? `WHERE ${whereParts.join("\n  AND ")}` : "",
+    params
+  };
+}
+function buildHavingClause(having) {
+  const parts = [];
+  for (const field of QUERY_EMAIL_HAVING_FIELDS) {
+    const condition = having[field];
+    if (!condition) {
+      continue;
+    }
+    const expression = AGGREGATE_SQL_MAP[field];
+    if (condition.gte !== void 0) {
+      parts.push(`${expression} >= ${condition.gte}`);
+    }
+    if (condition.lte !== void 0) {
+      parts.push(`${expression} <= ${condition.lte}`);
+    }
+  }
+  return parts.length > 0 ? `HAVING ${parts.join("\n  AND ")}` : "";
+}
+function normalizeRow(row, groupBy, aggregates) {
+  const normalized = {};
+  if (groupBy) {
+    normalized[groupBy] = normalizeGroupValue(groupBy, row[groupBy]);
+  }
+  for (const aggregate of aggregates) {
+    normalized[aggregate] = normalizeAggregateValue(aggregate, row[aggregate]);
+  }
+  return normalized;
+}
+async function queryEmails(options = {}) {
+  const parsed = queryEmailsInputSchema.parse(options);
+  await detectNewsletters();
+  const sqlite = getStatsSqlite();
+  const filters = parsed.filters ?? {};
+  const groupBy = parsed.group_by;
+  const aggregates = resolveAggregates(parsed.aggregates);
+  const having = parsed.having ?? {};
+  const orderBy = resolveOrderBy(parsed.order_by, groupBy, aggregates);
+  const limit = Math.min(500, normalizeLimit(parsed.limit, 50));
+  const { sql: whereSql, params } = buildWhereClauses(filters, groupBy);
+  const havingSql = buildHavingClause(having);
+  const fromSql = [
+    "FROM emails AS e",
+    "LEFT JOIN newsletter_senders AS ns ON LOWER(ns.email) = LOWER(e.from_address)",
+    `LEFT JOIN (
+      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)
+    ) AS sender_stats ON sender_stats.senderKey = LOWER(e.from_address)`,
+    groupBy === "label" ? "JOIN json_each(COALESCE(e.label_ids, '[]')) AS grouped_label" : ""
+  ].filter(Boolean).join("\n");
+  const selectParts = [];
+  if (groupBy) {
+    selectParts.push(`${GROUP_BY_SQL_MAP[groupBy]} AS ${groupBy}`);
+  }
+  for (const aggregate of aggregates) {
+    selectParts.push(`${AGGREGATE_SQL_MAP[aggregate]} AS ${aggregate}`);
+  }
+  const groupBySql = groupBy ? `GROUP BY ${GROUP_BY_SQL_MAP[groupBy]}` : "";
+  const orderBySql = `ORDER BY ${orderBy.split(" ")[0]} ${orderBy.split(" ")[1].toUpperCase()}`;
+  const totalRow = groupBy ? sqlite.prepare(
+    `
+        SELECT COUNT(*) AS totalRows
+        FROM (
+          SELECT 1
+          ${fromSql}
+          ${whereSql}
+          ${groupBySql}
+          ${havingSql}
+        ) AS grouped_rows
+        `
+  ).get(...params) : void 0;
+  const rows = sqlite.prepare(
+    `
+      SELECT
+        ${selectParts.join(",\n        ")}
+      ${fromSql}
+      ${whereSql}
+      ${groupBySql}
+      ${havingSql}
+      ${orderBySql}
+      LIMIT ?
+      `
+  ).all(...params, limit);
+  return {
+    rows: rows.map((row) => normalizeRow(row, groupBy, aggregates)),
+    totalRows: groupBy ? totalRow?.totalRows ?? 0 : rows.length,
+    query: {
+      filters,
+      group_by: groupBy ?? null,
+      aggregates,
+      having,
+      order_by: orderBy,
+      limit
+    }
+  };
+}
+
 // src/core/stats/sender.ts
 function buildSenderWhereClause(period) {
   const whereParts = [
@@ -3089,7 +3803,7 @@ async function getSenderStats(emailOrDomain) {
 }
 
 // src/core/stats/uncategorized.ts
-var SYSTEM_LABEL_IDS = [
+var SYSTEM_LABEL_IDS2 = [
   "INBOX",
   "UNREAD",
   "IMPORTANT",
@@ -3100,13 +3814,13 @@ var SYSTEM_LABEL_IDS = [
   "STARRED"
 ];
 var CATEGORY_LABEL_PATTERN = "CATEGORY\\_%";
-function toIsoString2(value) {
+function toIsoString4(value) {
   if (!value) {
     return null;
   }
   return new Date(value).toISOString();
 }
-function parseJsonArray3(raw) {
+function parseJsonArray4(raw) {
   if (!raw) {
     return [];
   }
@@ -3117,7 +3831,7 @@ function parseJsonArray3(raw) {
     return [];
   }
 }
-function resolveSinceTimestamp(since) {
+function resolveSinceTimestamp2(since) {
   if (!since) {
     return null;
   }
@@ -3127,6 +3841,50 @@ function resolveSinceTimestamp(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 = [
     `
@@ -3135,12 +3893,12 @@ function buildWhereClause(options) {
       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_IDS.map(() => "?").join(", ")})
+        AND label.value NOT IN (${SYSTEM_LABEL_IDS2.map(() => "?").join(", ")})
         AND label.value NOT LIKE ? ESCAPE '\\'
     )
     `
   ];
-  const params = [...SYSTEM_LABEL_IDS, CATEGORY_LABEL_PATTERN];
+  const params = [...SYSTEM_LABEL_IDS2, CATEGORY_LABEL_PATTERN];
   if (options.unreadOnly) {
     whereParts.push("COALESCE(e.is_read, 0) = 0");
   }
@@ -3158,7 +3916,7 @@ async function getUncategorizedEmails(options = {}) {
   const sqlite = getStatsSqlite();
   const limit = Math.min(1e3, normalizeLimit(options.limit, 50));
   const offset = Math.max(0, Math.floor(options.offset ?? 0));
-  const sinceTimestamp = resolveSinceTimestamp(options.since);
+  const sinceTimestamp = resolveSinceTimestamp2(options.since);
   const { clause, params } = buildWhereClause({
     sinceTimestamp,
     unreadOnly: options.unreadOnly ?? false
@@ -3183,7 +3941,8 @@ async function getUncategorizedEmails(options = {}) {
         e.is_read AS isRead,
         sender_stats.totalFromSender AS totalFromSender,
         sender_stats.unreadFromSender AS unreadFromSender,
-        ns.detection_reason AS detectionReason
+        ns.detection_reason AS detectionReason,
+        e.list_unsubscribe AS listUnsubscribe
       FROM emails AS e
       LEFT JOIN (
         SELECT
@@ -3207,20 +3966,23 @@ async function getUncategorizedEmails(options = {}) {
   const emails2 = rows.map((row) => {
     const totalFromSender = row.totalFromSender ?? 0;
     const unreadFromSender = row.unreadFromSender ?? 0;
+    const confidence = computeConfidence(row);
     return {
       id: row.id,
       threadId: row.threadId || "",
       from: row.sender || "",
       subject: row.subject || "",
-      date: toIsoString2(row.date),
+      date: toIsoString4(row.date),
       snippet: row.snippet || "",
-      labels: parseJsonArray3(row.labelIds),
+      labels: parseJsonArray4(row.labelIds),
       isRead: row.isRead === 1,
       senderContext: {
         totalFromSender,
         unreadRate: roundPercent(unreadFromSender, totalFromSender),
         isNewsletter: Boolean(row.detectionReason),
-        detectionReason: row.detectionReason
+        detectionReason: row.detectionReason,
+        confidence: confidence.confidence,
+        signals: confidence.signals
       }
     };
   });
@@ -3234,7 +3996,7 @@ async function getUncategorizedEmails(options = {}) {
 }
 
 // src/core/stats/unsubscribe.ts
-function toIsoString3(value) {
+function toIsoString5(value) {
   if (!value) {
     return null;
   }
@@ -3286,8 +4048,8 @@ async function getUnsubscribeSuggestions(options = {}) {
       unreadCount: row.unreadCount,
       unreadRate,
       readRate,
-      lastRead: toIsoString3(row.lastRead),
-      lastReceived: toIsoString3(row.lastReceived),
+      lastRead: toIsoString5(row.lastRead),
+      lastReceived: toIsoString5(row.lastReceived),
       unsubscribeLink: unsubscribe2.unsubscribeLink,
       unsubscribeMethod: unsubscribe2.unsubscribeMethod,
       impactScore: roundImpactScore(row.messageCount, unreadRate),
@@ -3439,67 +4201,67 @@ import { join as join2 } from "path";
 import YAML from "yaml";
 
 // src/core/rules/types.ts
-import { z } from "zod";
-var RuleNameSchema = z.string().min(1, "Rule name is required").regex(
+import { z as z3 } from "zod";
+var RuleNameSchema = z3.string().min(1, "Rule name is required").regex(
   /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
   "Rule name must be kebab-case (lowercase letters, numbers, and single hyphens)"
 );
-var RuleFieldSchema = z.enum(["from", "to", "subject", "snippet", "labels"]);
-var RegexStringSchema = z.string().min(1, "Pattern must not be empty").superRefine((value, ctx) => {
+var RuleFieldSchema = z3.enum(["from", "to", "subject", "snippet", "labels"]);
+var RegexStringSchema = z3.string().min(1, "Pattern must not be empty").superRefine((value, ctx) => {
   try {
     new RegExp(value);
   } catch (error) {
     ctx.addIssue({
-      code: z.ZodIssueCode.custom,
+      code: z3.ZodIssueCode.custom,
       message: `Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`
     });
   }
 });
-var MatcherSchema = z.object({
+var MatcherSchema = z3.object({
   // `snippet` is the only cached free-text matcher in MVP.
   field: RuleFieldSchema,
   pattern: RegexStringSchema.optional(),
-  contains: z.array(z.string().min(1)).min(1).optional(),
-  values: z.array(z.string().min(1)).min(1).optional(),
-  exclude: z.boolean().default(false)
+  contains: z3.array(z3.string().min(1)).min(1).optional(),
+  values: z3.array(z3.string().min(1)).min(1).optional(),
+  exclude: z3.boolean().default(false)
 }).strict().superRefine((value, ctx) => {
   if (!value.pattern && !value.contains && !value.values) {
     ctx.addIssue({
-      code: z.ZodIssueCode.custom,
+      code: z3.ZodIssueCode.custom,
       message: "Matcher must provide at least one of pattern, contains, or values",
       path: ["pattern"]
     });
   }
 });
-var ConditionsSchema = z.object({
-  operator: z.enum(["AND", "OR"]),
-  matchers: z.array(MatcherSchema).min(1, "At least one matcher is required")
+var ConditionsSchema = z3.object({
+  operator: z3.enum(["AND", "OR"]),
+  matchers: z3.array(MatcherSchema).min(1, "At least one matcher is required")
 }).strict();
-var LabelActionSchema = z.object({
-  type: z.literal("label"),
-  label: z.string().min(1, "Label name is required")
+var LabelActionSchema = z3.object({
+  type: z3.literal("label"),
+  label: z3.string().min(1, "Label name is required")
 });
-var ArchiveActionSchema = z.object({ type: z.literal("archive") });
-var MarkReadActionSchema = z.object({ type: z.literal("mark_read") });
-var ForwardActionSchema = z.object({
-  type: z.literal("forward"),
-  to: z.string().email("Forward destination must be a valid email address")
+var ArchiveActionSchema = z3.object({ type: z3.literal("archive") });
+var MarkReadActionSchema = z3.object({ type: z3.literal("mark_read") });
+var ForwardActionSchema = z3.object({
+  type: z3.literal("forward"),
+  to: z3.string().email("Forward destination must be a valid email address")
 });
-var MarkSpamActionSchema = z.object({ type: z.literal("mark_spam") });
-var ActionSchema = z.discriminatedUnion("type", [
+var MarkSpamActionSchema = z3.object({ type: z3.literal("mark_spam") });
+var ActionSchema = z3.discriminatedUnion("type", [
   LabelActionSchema,
   ArchiveActionSchema,
   MarkReadActionSchema,
   ForwardActionSchema,
   MarkSpamActionSchema
 ]);
-var RuleSchema = z.object({
+var RuleSchema = z3.object({
   name: RuleNameSchema,
-  description: z.string(),
-  enabled: z.boolean().default(true),
-  priority: z.number().int().min(0).default(50),
+  description: z3.string(),
+  enabled: z3.boolean().default(true),
+  priority: z3.number().int().min(0).default(50),
   conditions: ConditionsSchema,
-  actions: z.array(ActionSchema).min(1, "At least one action is required")
+  actions: z3.array(ActionSchema).min(1, "At least one action is required")
 }).strict();
 
 // src/core/rules/loader.ts
@@ -3829,7 +4591,7 @@ function getDatabase4() {
   const config = loadConfig();
   return getSqlite(config.dbPath);
 }
-function parseJsonArray4(value) {
+function parseJsonArray5(value) {
   if (!value) {
     return [];
   }
@@ -3846,13 +4608,13 @@ function rowToEmail3(row) {
     threadId: row.thread_id ?? "",
     fromAddress: row.from_address ?? "",
     fromName: row.from_name ?? "",
-    toAddresses: parseJsonArray4(row.to_addresses),
+    toAddresses: parseJsonArray5(row.to_addresses),
     subject: row.subject ?? "",
     snippet: row.snippet ?? "",
     date: row.date ?? 0,
     isRead: row.is_read === 1,
     isStarred: row.is_starred === 1,
-    labelIds: parseJsonArray4(row.label_ids),
+    labelIds: parseJsonArray5(row.label_ids),
     sizeEstimate: row.size_estimate ?? 0,
     hasAttachments: row.has_attachments === 1,
     listUnsubscribe: row.list_unsubscribe
@@ -4789,8 +5551,8 @@ async function getSyncStatus() {
 }
 
 // src/mcp/server.ts
-var DAY_MS3 = 24 * 60 * 60 * 1e3;
-var MCP_VERSION = "0.1.0";
+var DAY_MS4 = 24 * 60 * 60 * 1e3;
+var MCP_VERSION = "0.3.0";
 var MCP_TOOLS = [
   "search_emails",
   "get_email",
@@ -4809,6 +5571,8 @@ var MCP_TOOLS = [
   "get_sender_stats",
   "get_newsletter_senders",
   "get_uncategorized_emails",
+  "review_categorized",
+  "query_emails",
   "get_noise_senders",
   "get_unsubscribe_suggestions",
   "unsubscribe",
@@ -4826,6 +5590,7 @@ var MCP_RESOURCES = [
   "inbox://recent",
   "inbox://summary",
   "inbox://action-log",
+  "schema://query-fields",
   "rules://deployed",
   "rules://history",
   "stats://senders",
@@ -4947,7 +5712,7 @@ async function buildStartupWarnings() {
   }
   if (!latestSync) {
     warnings.push("Inbox cache has not been synced yet. Stats and resources will be empty until `sync_inbox` runs.");
-  } else if (Date.now() - latestSync > DAY_MS3) {
+  } else if (Date.now() - latestSync > DAY_MS4) {
     warnings.push("Inbox cache appears stale (last sync older than 24 hours). Call `sync_inbox` if freshness matters.");
   }
   return warnings;
@@ -4958,7 +5723,7 @@ async function buildStatsOverview() {
     topSenders: await getTopSenders({ limit: 10 }),
     labelDistribution: (await getLabelDistribution()).slice(0, 10),
     dailyVolume: await getVolumeByPeriod("day", {
-      start: Date.now() - 30 * DAY_MS3,
+      start: Date.now() - 30 * DAY_MS4,
       end: Date.now()
     })
   };
@@ -4998,9 +5763,9 @@ async function createMcpServer() {
     {
       description: "Search Gmail using Gmail query syntax and return matching email metadata.",
       inputSchema: {
-        query: z2.string().min(1),
-        max_results: z2.number().int().positive().max(100).optional(),
-        label: z2.string().min(1).optional()
+        query: z4.string().min(1),
+        max_results: z4.number().int().positive().max(100).optional(),
+        label: z4.string().min(1).optional()
       },
       annotations: {
         readOnlyHint: true
@@ -5015,7 +5780,7 @@ async function createMcpServer() {
     {
       description: "Fetch a single email with full content by Gmail message ID.",
       inputSchema: {
-        email_id: z2.string().min(1)
+        email_id: z4.string().min(1)
       },
       annotations: {
         readOnlyHint: true
@@ -5028,7 +5793,7 @@ async function createMcpServer() {
     {
       description: "Fetch a full Gmail thread by thread ID.",
       inputSchema: {
-        thread_id: z2.string().min(1)
+        thread_id: z4.string().min(1)
       },
       annotations: {
         readOnlyHint: true
@@ -5041,7 +5806,7 @@ async function createMcpServer() {
     {
       description: "Run inbox sync. Uses incremental sync by default and full sync when requested.",
       inputSchema: {
-        full: z2.boolean().optional()
+        full: z4.boolean().optional()
       },
       annotations: {
         readOnlyHint: false,
@@ -5055,7 +5820,7 @@ async function createMcpServer() {
     {
       description: "Archive one or more Gmail messages by removing the INBOX label.",
       inputSchema: {
-        email_ids: z2.array(z2.string().min(1)).min(1)
+        email_ids: z4.array(z4.string().min(1)).min(1)
       },
       annotations: {
         readOnlyHint: false,
@@ -5069,9 +5834,9 @@ async function createMcpServer() {
     {
       description: "Add and/or remove Gmail labels on one or more messages.",
       inputSchema: {
-        email_ids: z2.array(z2.string().min(1)).min(1),
-        add_labels: z2.array(z2.string().min(1)).optional(),
-        remove_labels: z2.array(z2.string().min(1)).optional()
+        email_ids: z4.array(z4.string().min(1)).min(1),
+        add_labels: z4.array(z4.string().min(1)).optional(),
+        remove_labels: z4.array(z4.string().min(1)).optional()
       },
       annotations: {
         readOnlyHint: false,
@@ -5105,8 +5870,8 @@ async function createMcpServer() {
     {
       description: "Mark one or more Gmail messages as read or unread.",
       inputSchema: {
-        email_ids: z2.array(z2.string().min(1)).min(1),
-        read: z2.boolean()
+        email_ids: z4.array(z4.string().min(1)).min(1),
+        read: z4.boolean()
       },
       annotations: {
         readOnlyHint: false,
@@ -5123,23 +5888,23 @@ async function createMcpServer() {
     {
       description: "Apply grouped inbox actions in one call for faster AI-driven triage and categorization.",
       inputSchema: {
-        groups: z2.array(
-          z2.object({
-            email_ids: z2.array(z2.string().min(1)).min(1).max(500),
-            actions: z2.array(
-              z2.discriminatedUnion("type", [
-                z2.object({
-                  type: z2.literal("label"),
-                  label: z2.string().min(1)
+        groups: z4.array(
+          z4.object({
+            email_ids: z4.array(z4.string().min(1)).min(1).max(500),
+            actions: z4.array(
+              z4.discriminatedUnion("type", [
+                z4.object({
+                  type: z4.literal("label"),
+                  label: z4.string().min(1)
                 }),
-                z2.object({ type: z2.literal("archive") }),
-                z2.object({ type: z2.literal("mark_read") }),
-                z2.object({ type: z2.literal("mark_spam") })
+                z4.object({ type: z4.literal("archive") }),
+                z4.object({ type: z4.literal("mark_read") }),
+                z4.object({ type: z4.literal("mark_spam") })
               ])
             ).min(1).max(5)
           })
         ).min(1).max(20),
-        dry_run: z2.boolean().optional()
+        dry_run: z4.boolean().optional()
       },
       annotations: {
         readOnlyHint: false,
@@ -5159,8 +5924,8 @@ async function createMcpServer() {
     {
       description: "Forward a Gmail message to another address.",
       inputSchema: {
-        email_id: z2.string().min(1),
-        to: z2.string().email()
+        email_id: z4.string().min(1),
+        to: z4.string().email()
       },
       annotations: {
         readOnlyHint: false,
@@ -5174,7 +5939,7 @@ async function createMcpServer() {
     {
       description: "Undo a prior inboxctl action run when the underlying Gmail mutations are reversible.",
       inputSchema: {
-        run_id: z2.string().min(1)
+        run_id: z4.string().min(1)
       },
       annotations: {
         readOnlyHint: false,
@@ -5198,8 +5963,8 @@ async function createMcpServer() {
     {
       description: "Create a Gmail label if it does not already exist.",
       inputSchema: {
-        name: z2.string().min(1),
-        color: z2.string().min(1).optional()
+        name: z4.string().min(1),
+        color: z4.string().min(1).optional()
       },
       annotations: {
         readOnlyHint: false,
@@ -5231,9 +5996,9 @@ async function createMcpServer() {
     {
       description: "Return top senders ranked by cached email volume.",
       inputSchema: {
-        limit: z2.number().int().positive().max(100).optional(),
-        min_unread_rate: z2.number().min(0).max(100).optional(),
-        period: z2.enum(["day", "week", "month", "year", "all"]).optional()
+        limit: z4.number().int().positive().max(100).optional(),
+        min_unread_rate: z4.number().min(0).max(100).optional(),
+        period: z4.enum(["day", "week", "month", "year", "all"]).optional()
       },
       annotations: {
         readOnlyHint: true
@@ -5250,7 +6015,7 @@ async function createMcpServer() {
     {
       description: "Return detailed stats for a sender email address or an @domain aggregate.",
       inputSchema: {
-        email_or_domain: z2.string().min(1)
+        email_or_domain: z4.string().min(1)
       },
       annotations: {
         readOnlyHint: true
@@ -5270,8 +6035,8 @@ async function createMcpServer() {
     {
       description: "Return senders that look like newsletters or mailing lists based on cached heuristics.",
       inputSchema: {
-        min_messages: z2.number().int().positive().optional(),
-        min_unread_rate: z2.number().min(0).max(100).optional()
+        min_messages: z4.number().int().positive().optional(),
+        min_unread_rate: z4.number().min(0).max(100).optional()
       },
       annotations: {
         readOnlyHint: true
@@ -5287,10 +6052,10 @@ async function createMcpServer() {
     {
       description: "Return cached emails that have only Gmail system labels and no user-applied organization.",
       inputSchema: {
-        limit: z2.number().int().positive().max(1e3).optional().describe("Max emails to return per page. Default 50. AI clients should start with 50-100 and paginate."),
-        offset: z2.number().int().min(0).optional().describe("Number of results to skip for pagination. Use with totalUncategorized and hasMore."),
-        unread_only: z2.boolean().optional(),
-        since: z2.string().min(1).optional()
+        limit: z4.number().int().positive().max(1e3).optional().describe("Max emails to return per page. Default 50. AI clients should start with 50-100 and paginate."),
+        offset: z4.number().int().min(0).optional().describe("Number of results to skip for pagination. Use with totalUncategorized and hasMore."),
+        unread_only: z4.boolean().optional(),
+        since: z4.string().min(1).optional()
       },
       annotations: {
         readOnlyHint: true
@@ -5303,15 +6068,37 @@ async function createMcpServer() {
       since
     }))
   );
+  server.registerTool(
+    "review_categorized",
+    {
+      description: "Scan recently categorized emails for anomalies that suggest a misclassification or over-aggressive archive.",
+      inputSchema: reviewCategorizedInputSchema.shape,
+      annotations: {
+        readOnlyHint: true
+      }
+    },
+    toolHandler(async (args) => reviewCategorized(args))
+  );
+  server.registerTool(
+    "query_emails",
+    {
+      description: "Run structured analytics queries over the cached email dataset using fixed filters, groupings, and aggregates.",
+      inputSchema: queryEmailsInputSchema.shape,
+      annotations: {
+        readOnlyHint: true
+      }
+    },
+    toolHandler(async (args) => queryEmails(args))
+  );
   server.registerTool(
     "get_noise_senders",
     {
       description: "Return a focused list of active, high-noise senders worth categorizing, filtering, or unsubscribing.",
       inputSchema: {
-        limit: z2.number().int().positive().max(50).optional(),
-        min_noise_score: z2.number().min(0).optional(),
-        active_days: z2.number().int().positive().optional(),
-        sort_by: z2.enum(["noise_score", "all_time_noise_score", "message_count", "unread_rate"]).optional().describe("Sort order. Default: noise_score. Use all_time_noise_score for lifetime perspective.")
+        limit: z4.number().int().positive().max(50).optional(),
+        min_noise_score: z4.number().min(0).optional(),
+        active_days: z4.number().int().positive().optional(),
+        sort_by: z4.enum(["noise_score", "all_time_noise_score", "message_count", "unread_rate"]).optional().describe("Sort order. Default: noise_score. Use all_time_noise_score for lifetime perspective.")
       },
       annotations: {
         readOnlyHint: true
@@ -5329,9 +6116,9 @@ async function createMcpServer() {
     {
       description: "Return ranked senders with unsubscribe links, sorted by how much inbox noise unsubscribing would remove.",
       inputSchema: {
-        limit: z2.number().int().positive().max(50).optional(),
-        min_messages: z2.number().int().positive().optional(),
-        unread_only_senders: z2.boolean().optional()
+        limit: z4.number().int().positive().max(50).optional(),
+        min_messages: z4.number().int().positive().optional(),
+        unread_only_senders: z4.boolean().optional()
       },
       annotations: {
         readOnlyHint: true
@@ -5348,9 +6135,9 @@ async function createMcpServer() {
     {
       description: "Return the unsubscribe target for a sender and optionally label/archive existing emails in one undoable run.",
       inputSchema: {
-        sender_email: z2.string().min(1),
-        also_archive: z2.boolean().optional(),
-        also_label: z2.string().min(1).optional()
+        sender_email: z4.string().min(1),
+        also_archive: z4.boolean().optional(),
+        also_label: z4.string().min(1).optional()
       },
       annotations: {
         readOnlyHint: false,
@@ -5368,7 +6155,7 @@ async function createMcpServer() {
     {
       description: "Validate and deploy a rule directly from YAML content.",
       inputSchema: {
-        yaml_content: z2.string().min(1)
+        yaml_content: z4.string().min(1)
       },
       annotations: {
         readOnlyHint: false,
@@ -5385,7 +6172,7 @@ async function createMcpServer() {
     {
       description: "List deployed inboxctl rules and their execution status.",
       inputSchema: {
-        enabled_only: z2.boolean().optional()
+        enabled_only: z4.boolean().optional()
       },
       annotations: {
         readOnlyHint: true
@@ -5401,9 +6188,9 @@ async function createMcpServer() {
     {
       description: "Run a deployed rule in dry-run mode by default, or apply it when dry_run is false.",
       inputSchema: {
-        rule_name: z2.string().min(1),
-        dry_run: z2.boolean().optional(),
-        max_emails: z2.number().int().positive().max(1e3).optional()
+        rule_name: z4.string().min(1),
+        dry_run: z4.boolean().optional(),
+        max_emails: z4.number().int().positive().max(1e3).optional()
       },
       annotations: {
         readOnlyHint: false,
@@ -5420,7 +6207,7 @@ async function createMcpServer() {
     {
       description: "Enable a deployed rule by name.",
       inputSchema: {
-        rule_name: z2.string().min(1)
+        rule_name: z4.string().min(1)
       },
       annotations: {
         readOnlyHint: false,
@@ -5434,7 +6221,7 @@ async function createMcpServer() {
     {
       description: "Disable a deployed rule by name.",
       inputSchema: {
-        rule_name: z2.string().min(1)
+        rule_name: z4.string().min(1)
       },
       annotations: {
         readOnlyHint: false,
@@ -5470,6 +6257,15 @@ async function createMcpServer() {
     },
     async (uri) => resourceText(resolveResourceUri(uri, "inbox://action-log"), await buildActionLog())
   );
+  server.registerResource(
+    "query-fields",
+    "schema://query-fields",
+    {
+      description: "Field vocabulary, aggregates, and examples for the query_emails analytics tool.",
+      mimeType: "application/json"
+    },
+    async (uri) => resourceText(resolveResourceUri(uri, "schema://query-fields"), QUERY_EMAILS_FIELD_SCHEMA)
+  );
   server.registerResource(
     "deployed-rules",
     "rules://deployed",
@@ -5529,6 +6325,10 @@ async function createMcpServer() {
     async () => promptResult(
       "Review top senders and recommend cleanup actions.",
       [
+        "Step 0 \u2014 Check for past mistakes:",
+        "  Call `review_categorized` to see if any recent categorisations look incorrect.",
+        "  If anomalies are found, present them first \u2014 fixing past mistakes takes priority over reviewing new senders.",
+        "",
         "Step 1 \u2014 Gather data:",
         "  Use `get_noise_senders` for the most actionable noisy senders.",
         "  Use `rules://deployed` to check for existing rules covering these senders.",
@@ -5626,6 +6426,10 @@ async function createMcpServer() {
         "  FYI \u2014 worth knowing about but no action needed",
         "  NOISE \u2014 bulk, promotional, or irrelevant",
         "",
+        "Step 2.5 \u2014 Flag low-confidence items:",
+        '  For any email with `confidence: "low"` in `senderContext`, always categorise it as ACTION REQUIRED.',
+        "  Better to surface a false positive than bury a real personal or work email.",
+        "",
         "Step 3 \u2014 Present findings:",
         "  List emails grouped by category with: sender, subject, and one-line reason.",
         "  For NOISE, suggest a label and whether to archive.",
@@ -5673,6 +6477,14 @@ async function createMcpServer() {
         "  For each group show: count, 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.",
+        "  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.",
+        "",
+        "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.",
         "",
         "Step 4 \u2014 Apply with user approval:",
         "  Create labels for any new categories (use `create_label`).",
@@ -5688,7 +6500,11 @@ async function createMcpServer() {
         "Step 6 \u2014 Suggest ongoing rules:",
         "  For any category with 3+ emails from the same sender, suggest a YAML rule.",
         "  This prevents the same categorisation from being needed again.",
-        "  Use `deploy_rule` after user reviews the YAML."
+        "  Use `deploy_rule` after user reviews the YAML.",
+        "",
+        "Step 7 \u2014 Post-categorisation audit:",
+        "  After applying actions, call `review_categorized` to check for anomalies.",
+        "  If anomalies are found, present them with the option to undo the relevant run."
       ].join("\n")
     )
   );
@@ -5704,7 +6520,7 @@ async function createMcpServer() {
     {
       description: "Get the details of a specific Gmail server-side filter by ID.",
       inputSchema: {
-        filter_id: z2.string().min(1).describe("Gmail filter ID")
+        filter_id: z4.string().min(1).describe("Gmail filter ID")
       }
     },
     toolHandler(async ({ filter_id }) => getFilter(filter_id))
@@ -5714,20 +6530,20 @@ async function createMcpServer() {
     {
       description: "Create a Gmail server-side filter that applies automatically to all future incoming mail. Useful for simple, always-on rules (e.g. 'label all mail from newsletter@x.com and archive it'). At least one criteria field and one action field are required. Gmail does not support updating filters \u2014 to change one, delete it and create a new one. For regex matching, OR conditions, snippet matching, or processing existing mail, use YAML rules instead.",
       inputSchema: {
-        from: z2.string().optional().describe("Match emails from this address"),
-        to: z2.string().optional().describe("Match emails sent to this address"),
-        subject: z2.string().optional().describe("Match emails with this text in the subject"),
-        query: z2.string().optional().describe("Match using Gmail search syntax (e.g. 'has:attachment')"),
-        negated_query: z2.string().optional().describe("Exclude emails matching this Gmail query"),
-        has_attachment: z2.boolean().optional().describe("Match emails with attachments"),
-        exclude_chats: z2.boolean().optional().describe("Exclude chat messages from matches"),
-        size: z2.number().int().positive().optional().describe("Size threshold in bytes"),
-        size_comparison: z2.enum(["larger", "smaller"]).optional().describe("Use with size: match emails larger or smaller than the threshold"),
-        label: z2.string().optional().describe("Apply this label to matching emails (auto-created if it does not exist)"),
-        archive: z2.boolean().optional().describe("Archive matching emails (remove from inbox)"),
-        mark_read: z2.boolean().optional().describe("Mark matching emails as read"),
-        star: z2.boolean().optional().describe("Star matching emails"),
-        forward: z2.string().email().optional().describe("Forward matching emails to this address (address must be verified in Gmail settings)")
+        from: z4.string().optional().describe("Match emails from this address"),
+        to: z4.string().optional().describe("Match emails sent to this address"),
+        subject: z4.string().optional().describe("Match emails with this text in the subject"),
+        query: z4.string().optional().describe("Match using Gmail search syntax (e.g. 'has:attachment')"),
+        negated_query: z4.string().optional().describe("Exclude emails matching this Gmail query"),
+        has_attachment: z4.boolean().optional().describe("Match emails with attachments"),
+        exclude_chats: z4.boolean().optional().describe("Exclude chat messages from matches"),
+        size: z4.number().int().positive().optional().describe("Size threshold in bytes"),
+        size_comparison: z4.enum(["larger", "smaller"]).optional().describe("Use with size: match emails larger or smaller than the threshold"),
+        label: z4.string().optional().describe("Apply this label to matching emails (auto-created if it does not exist)"),
+        archive: z4.boolean().optional().describe("Archive matching emails (remove from inbox)"),
+        mark_read: z4.boolean().optional().describe("Mark matching emails as read"),
+        star: z4.boolean().optional().describe("Star matching emails"),
+        forward: z4.string().email().optional().describe("Forward matching emails to this address (address must be verified in Gmail settings)")
       }
     },
     toolHandler(
@@ -5754,7 +6570,7 @@ async function createMcpServer() {
     {
       description: "Delete a Gmail server-side filter by ID. The filter stops processing future mail immediately. Already-processed mail is not affected. Use list_filters to find filter IDs.",
       inputSchema: {
-        filter_id: z2.string().min(1).describe("Gmail filter ID to delete")
+        filter_id: z4.string().min(1).describe("Gmail filter ID to delete")
       }
     },
     toolHandler(async ({ filter_id }) => {
@@ -5852,4 +6668,4 @@ export {
   createMcpServer,
   startMcpServer
 };
-//# sourceMappingURL=chunk-NUN2WRBN.js.map
+//# sourceMappingURL=chunk-OLL3OA5B.js.map