@deepsql/mcp 0.14.0 → 0.17.0

package/CLAUDE.md

@@ -33,7 +33,7 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes 12 tools. They all take a `connectionId` (UUID
+The MCP server exposes 14 tools. They all take a `connectionId` (UUID
 returned by `list_connections`) except `apply_index_recommendation`,
 which takes a server-resolved `recommendationId`.
 
@@ -47,6 +47,8 @@ which takes a server-resolved `recommendationId`.
 | `get_relationships` | Inferred + validated foreign keys with confidence scores. Many real DBs lack declared FKs; this fills the gap. |
 | `get_anti_patterns` | Schema-level (`kind=table`) or query-level (`kind=query`) anti-patterns. |
 | `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples. Read-only; doesn't trigger new work. |
+| `get_slow_query_timeline` | Day-by-day timeline for one query from the 30-day analytics store — call count, mean/max time, regression factor per day. Identify the query by its fingerprint (the `queryId` from `analyze_slow_queries`). Answers "is this query getting slower". |
+| `get_query_regressions` | Slow queries that regressed (got slower) on the latest daily analysis run, ranked by slowdown factor. Read-only. |
 | `get_index_recommendations` | **Workload-weighted DBA-grade index advisor.** Pre-computed top-N (default 5) recommendations ranked by net benefit (`Σ calls × mean_exec_time` − write-cost). Each result carries up to 5 contributing query fingerprints, the role each column played, and optional HypoPG cost-delta on Postgres. Covers both `CREATE_INDEX` and `DROP_INDEX` (unused + redundant-prefix) candidates. |
 | **`apply_index_recommendation`** | **The only write-capable MCP tool.** Apply (or dry-run) a recommendation against its target connection and measure the before/after benefit on contributing queries. `DRY_RUN` (default) uses HypoPG (Postgres-only) for zero-write cost-delta. `APPLY` runs real `CREATE/DROP INDEX CONCURRENTLY` (configurable via `concurrent`). `APPLY_AND_MEASURE` additionally runs `EXPLAIN ANALYZE` for wall-clock timings. Write modes require `confirm: true`. The DDL is server-generated from the recommendation row — clients never supply SQL. |
 | **`execute_sql`** | **Run any SQL statement.** Policy is server-enforced: developers can run SELECT/WITH/SHOW/EXPLAIN; admins can also run DML/DDL with a two-step confirmation. EXPLAIN and EXPLAIN ANALYZE are just SQL — no separate flag. |
@@ -211,9 +213,10 @@ for them to say yes, then re-call with `confirmMutation: true`.
 
 **"What indexes should we add?"** → `get_index_recommendations`. Returns
 the workload-weighted top-N (default 5) with net benefit, contributing
-queries, and HypoPG cost-delta when available. Use `deepsql indexes
-missing` / `deepsql indexes health` in the terminal for catalog-level
-counterparts (usage stats, duplicates).
+queries, and HypoPG cost-delta when available. The terminal equivalent
+is `deepsql indexes top` (same data, same ranking); `deepsql indexes
+missing` / `health` / `unused` / `duplicates` cover the catalog-level
+diagnostics that complement the workload-weighted advisor.
 
 **"How much faster will this index actually make things?"** →
 `apply_index_recommendation` with `mode: "DRY_RUN"` (default). On
@@ -225,7 +228,10 @@ the index (CONCURRENTLY) and run `EXPLAIN ANALYZE` before/after.
 
 **"What changed recently / what should I worry about?"** → Tell the user to
 run `deepsql digest` (today) or `deepsql digest 7` (last seven). The digest
-isn't MCP-exposed.
+isn't MCP-exposed. The digest now includes a workload-weighted **Index Wins**
+section that surfaces the same top-N recommendations `get_index_recommendations`
+returns, with the `deepsql indexes apply <id> --mode dry-run` CTA — so a user
+who skims the digest in Slack can flow directly into the apply path.
 
 **"Are there foreign keys between X and Y?"** → `get_relationships`. Many
 real-world DBs lack declared FKs but DeepSQL's brain infers them; check the
@@ -318,11 +324,16 @@ them at the terminal command rather than trying to fake it through
 
 | Capability | CLI command |
 |---|---|
-| Catalog-level index stats (counterpart to `get_index_recommendations`) | `deepsql indexes list`, `deepsql indexes missing` |
-| Unused / duplicate index detection | `deepsql indexes unused`, `deepsql indexes duplicates` |
-| Per-table index usage stats | `deepsql indexes usage <table>` |
-| Index health report | `deepsql indexes health` |
-| Workload-weighted advisor + apply (DBA-grade) | `deepsql index-recommendations top` / `apply <id>` — same surface as the MCP `get_index_recommendations` + `apply_index_recommendation` tools, useful from a terminal |
+| Workload-weighted advisor (terminal mirror of `get_index_recommendations`) | `deepsql indexes top [--limit N]` |
+| Apply / dry-run an advisor recommendation (terminal mirror of `apply_index_recommendation`) | `deepsql indexes apply <id> [--mode dry-run\|apply\|apply-and-measure] [--confirm]` |
+| Force a fresh accumulation cycle | `deepsql indexes refresh` |
+| Full recommendation detail incl. contributing queries | `deepsql indexes show <id>` |
+| Dismiss a recommendation | `deepsql indexes dismiss <id>` |
+| Browse all recommendations (any status) | `deepsql indexes list [--all\|--status …]` |
+| Catalog: missing-index suggestions | `deepsql indexes missing` |
+| Catalog: unused / duplicate index detection | `deepsql indexes unused`, `deepsql indexes duplicates` |
+| Catalog: per-table index usage stats | `deepsql indexes usage <table>` |
+| Catalog: index health report | `deepsql indexes health` |
 | Daily digest (anomalies + AI commentary) | `deepsql digest`, `deepsql digest 7` |
 | Streaming AI optimization for a slow query | `deepsql slow-queries optimize --query-id <id>` |
 

package/deepsql-phase1-lib.js

@@ -217,6 +217,107 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "get_slow_query_timeline",
+    description:
+      "Get the day-by-day timeline for one slow query from DeepSQL's 30-day analytics store. "
+      + "The query is identified by its stable fingerprint (the MD5 of the normalized query — "
+      + "the `queryId` field returned by analyze_slow_queries). Returns one point per day with "
+      + "call count, mean/max execution time, and the regression factor versus the previous day. "
+      + "Use this to answer 'is this query getting slower over time'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        fingerprint: {
+          type: "string",
+          description: "Stable query fingerprint (MD5 of the normalized query).",
+        },
+      },
+      required: ["connectionId", "fingerprint"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_query_regressions",
+    description:
+      "List slow queries that regressed (got slower) on the most recent daily analysis run. "
+      + "Each result carries the fingerprint, normalized SQL, current mean execution time, and "
+      + "the regression factor (this period's mean / the previous period's mean). Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        minFactor: {
+          type: "number",
+          minimum: 1,
+          description: "Minimum slowdown multiple to report. Defaults to 1.5 (≥50% slower).",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_table_growth",
+    description:
+      "Get table size / row-count growth trends for a connection from DeepSQL's persistent stats history. "
+      + "Returns three parallel time series (sizeOverTime, growthOverTime, rowCountOverTime) plus per-table "
+      + "headline rollups suitable for answering questions like \"which tables are growing fastest?\" or "
+      + "\"how much has `orders` grown in the last month?\". Backed by snapshots stored in DeepSQL's "
+      + "`table_stats_history`, not live `pg_total_relation_size()` probes — so it can show growth velocity "
+      + "and bloat over time without re-scanning the customer's database.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: {
+          type: "string",
+          description: "Optional table name to scope the trends to a single table. Omit for all tables.",
+        },
+        days: {
+          type: "integer",
+          minimum: 1,
+          maximum: 365,
+          description: "Lookback window in days. Defaults to 30.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_growth_anomalies",
+    description:
+      "Get growth anomalies DeepSQL flagged on a connection — sudden size or row spikes that exceeded the "
+      + "configured thresholds (percentage growth, absolute byte growth, statistical z-score). Each anomaly "
+      + "carries severity (CRITICAL / WARNING / INFO), the before/after sizes, an anomaly type "
+      + "(PERCENTAGE_GROWTH, ABSOLUTE_GROWTH, STATISTICAL_ANOMALY, ROW_SPIKE, NEW_TABLE), a human-readable "
+      + "description, and a confidence score. Use this BEFORE walking the user through a plan to optimize a "
+      + "table — the anomaly may be the root cause they should investigate first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: {
+          type: "string",
+          description: "Optional table name to scope to one table. Omit for the whole connection.",
+        },
+        unacknowledgedOnly: {
+          type: "boolean",
+          description: "When true, only return anomalies the operator hasn't acked yet. Defaults to false.",
+        },
+        days: {
+          type: "integer",
+          minimum: 1,
+          maximum: 365,
+          description: "Lookback window in days. Defaults to 30.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "execute_sql",
     description:
@@ -740,6 +841,90 @@ function summarizeSlowQueries(payload) {
     + parts.join("");
 }
 
+function summarizeTableGrowth(payload) {
+  // Backend returns { success, trends: { sizeOverTime[], growthOverTime[],
+  // rowCountOverTime[] }, days }. We don't want to dump the raw arrays into
+  // the agent's context — collapse to a per-table headline and a top-3
+  // "growing fastest" list.
+  const trends = payload?.trends || {};
+  const sizeOverTime = Array.isArray(trends.sizeOverTime) ? trends.sizeOverTime : [];
+  if (sizeOverTime.length === 0) {
+    return "No table-growth history for this connection in the requested window. "
+      + "The customer may not have stats-snapshot collection enabled yet.";
+  }
+
+  // Roll up per-table: first vs last snapshot.
+  const byTable = new Map();
+  for (const point of sizeOverTime) {
+    const t = point.table || "(unknown)";
+    if (!byTable.has(t)) byTable.set(t, []);
+    byTable.get(t).push(point);
+  }
+  const rows = [];
+  for (const [table, points] of byTable.entries()) {
+    points.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+    const first = points[0];
+    const last = points[points.length - 1];
+    const firstBytes = first?.sizeBytes ?? 0;
+    const lastBytes = last?.sizeBytes ?? 0;
+    const deltaBytes = lastBytes - firstBytes;
+    rows.push({ table, firstBytes, lastBytes, deltaBytes });
+  }
+  rows.sort((a, b) => Math.abs(b.deltaBytes) - Math.abs(a.deltaBytes));
+
+  const days = payload?.days != null ? `${payload.days}d` : "window";
+  const top = rows.slice(0, 3).map((r) => {
+    const arrow = r.deltaBytes >= 0 ? "↑" : "↓";
+    const pct = r.firstBytes > 0
+      ? ` (${r.deltaBytes >= 0 ? "+" : ""}${((r.deltaBytes / r.firstBytes) * 100).toFixed(1)}%)`
+      : "";
+    return `${r.table} ${arrow} ${formatBytesHumanLib(Math.abs(r.deltaBytes))}${pct}`;
+  });
+  return `${rows.length} table(s) with growth data over ${days}. `
+    + `Most-changed: ${top.join("; ")}.`;
+}
+
+function summarizeGrowthAnomalies(payload) {
+  // Backend returns { success, anomalies[], statistics: { total, warning,
+  // critical, info, acknowledged, unacknowledged } }. Agents should know
+  // BEFORE drilling into a slow query whether a recent growth anomaly is
+  // the real root cause.
+  const list = Array.isArray(payload?.anomalies) ? payload.anomalies : [];
+  if (list.length === 0) {
+    return "No growth anomalies detected in the requested window.";
+  }
+  const stats = payload?.statistics || {};
+  const total = stats.total ?? list.length;
+  const crit = stats.critical ?? 0;
+  const warn = stats.warning ?? 0;
+  const unack = stats.unacknowledged ?? 0;
+
+  // Surface the worst recent one so the agent has something concrete to
+  // reference without having to walk the structured payload.
+  const worst = list.find((a) => a && a.severity === "CRITICAL")
+    || list.find((a) => a && a.severity === "WARNING")
+    || list[0];
+  const worstLine = worst
+    ? ` Top: [${worst.severity || "INFO"}] ${worst.tableName || "?"} — `
+      + `${worst.anomalyType || "growth"}`
+      + (worst.sizeGrowthPercent != null
+        ? ` ${worst.sizeGrowthPercent > 0 ? "+" : ""}${worst.sizeGrowthPercent.toFixed(1)}%`
+        : "")
+    : "";
+  return `${total} growth anomal${total === 1 ? "y" : "ies"} `
+    + `(${crit} critical, ${warn} warning, ${unack} unacknowledged).${worstLine}`;
+}
+
+function formatBytesHumanLib(bytes) {
+  if (bytes == null) return "?";
+  const abs = Math.abs(bytes);
+  if (abs < 1024) return `${bytes} B`;
+  if (abs < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (abs < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (abs < 1024 * 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+  return `${(bytes / (1024 * 1024 * 1024 * 1024)).toFixed(2)} TB`;
+}
+
 function summarizeQueryResult(payload) {
   const result = payload?.result || payload?.data || payload;
   const rowCount = result?.rowCount ?? 0;
@@ -785,6 +970,12 @@ function buildToolResult(name, payload, extra = {}) {
     case "analyze_slow_queries":
       summary = summarizeSlowQueries(payload);
       break;
+    case "get_table_growth":
+      summary = summarizeTableGrowth(payload);
+      break;
+    case "get_growth_anomalies":
+      summary = summarizeGrowthAnomalies(payload);
+      break;
     case "get_index_recommendations":
       summary = summarizeIndexRecommendations(payload);
       break;
@@ -969,6 +1160,64 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload);
     }
 
+    case "get_slow_query_timeline": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const fingerprint = String(args.fingerprint || "").trim();
+      if (!fingerprint) return buildToolError("fingerprint is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-query-analytics/${encodeURIComponent(connectionId)}/timeline/${encodeURIComponent(fingerprint)}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_query_regressions": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const minFactor = args.minFactor != null ? Number(args.minFactor) : 1.5;
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-query-analytics/${encodeURIComponent(connectionId)}/regressions?minFactor=${minFactor}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_table_growth": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const params = [];
+      const days = clampInteger(args.days, 1, 365, 30);
+      params.push(`days=${days}`);
+      if (args.tableName) {
+        params.push(`tableName=${encodeURIComponent(String(args.tableName))}`);
+      }
+      const payload = await callDeepSqlApi(
+        config,
+        `/growth-monitoring/trends/${encodeURIComponent(connectionId)}?${params.join("&")}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_growth_anomalies": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const params = [];
+      const days = clampInteger(args.days, 1, 365, 30);
+      params.push(`days=${days}`);
+      if (args.tableName) {
+        params.push(`tableName=${encodeURIComponent(String(args.tableName))}`);
+      }
+      if (args.unacknowledgedOnly === true) {
+        params.push("unacknowledgedOnly=true");
+      }
+      const payload = await callDeepSqlApi(
+        config,
+        `/growth-monitoring/anomalies/${encodeURIComponent(connectionId)}?${params.join("&")}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
     case "execute_sql": {
       const connectionId = String(args.connectionId || "").trim();
       const query = String(args.query || "").trim();
@@ -1075,6 +1324,8 @@ module.exports = {
   stripSqlComments,
   stripSqlStringLiterals,
   summarizeApplyResult,
+  summarizeGrowthAnomalies,
   summarizeIndexRecommendations,
+  summarizeTableGrowth,
   validateReadOnlySql,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.14.0",
+  "version": "0.17.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",

package/skills/SKILL_BODY.md

@@ -87,6 +87,8 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `get_relationships(connectionId)` | Foreign keys (declared + inferred-with-confidence). |
 | `get_anti_patterns(connectionId, kind="table"\|"query")` | Patterns to avoid in this DB. |
 | `analyze_slow_queries(connectionId, thresholdMs?, limit?)` | Snapshot of slow queries from live stats. |
+| `get_table_growth(connectionId, tableName?, days?)` | Persistent stats history: per-table size/row time series + headline rollups. Use to answer "which tables are growing fastest?" or "how much has X grown in the last month?" without scanning the live DB. |
+| `get_growth_anomalies(connectionId, tableName?, unacknowledgedOnly?, days?)` | DeepSQL-flagged sudden growth spikes with severity (CRITICAL/WARNING/INFO), anomaly type, before/after sizes, confidence score. Check this BEFORE walking the user through a slow-query plan — a recent growth anomaly is often the real root cause. |
 | `execute_sql(connectionId, query, ...)` | Run any SQL — SELECT for everyone, DML/DDL for admins (two-step confirm). |
 | `analyze_query_plan(connectionId, query, useAnalyze=false)` | AI-enriched plan analysis (issues + index recs + summary). |
 
@@ -128,6 +130,7 @@ deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 | `deepsql relationships --connection <c>` | Inferred + validated FKs | `get_relationships` |
 | `deepsql anti-patterns --connection <c> [--kind table\|query]` | Anti-patterns | `get_anti_patterns` |
 | `deepsql digest [N]\|list\|show <id>` | **CLI-only**: daily digest of slow queries + AI commentary | none |
+| `deepsql growth trends\|history\|anomalies\|ack\|capture\|config` | Table growth analytics (size/row trends, detected anomalies, alert thresholds) | partial: `get_table_growth`, `get_growth_anomalies` |
 | `deepsql indexes list\|missing\|health\|unused\|duplicates\|usage <table>` | **CLI-only**: index recommendations and usage stats | none |
 | `deepsql slow-queries latest\|history\|analyze\|optimize\|delete` | Slow-query analyses; `optimize` streams AI optimization steps live (SSE) | partial: `analyze_slow_queries` |
 | `deepsql users list\|get\|add\|set-role\|lock\|unlock\|disable\|resend-invite\|reset-password\|delete` | **Admin-only, CLI-only**: workspace user management | none |
@@ -147,6 +150,10 @@ shell-out (with `--caller-agent`) or tell the user the exact command:
 | User asks for | Run / suggest |
 |---|---|
 | "What changed in the database recently?" / "Today's report" | `deepsql digest` (most recent) or `deepsql digest 7` (last week) |
+| "Which tables are growing fastest?" / "How big is `<table>` now vs a month ago?" | MCP: `get_table_growth(connectionId, days=30)`. CLI: `deepsql growth trends --connection <c>` (or `--table <name> --days 30`) |
+| "Did any table spike in size recently?" / "Anything weird in growth?" | MCP: `get_growth_anomalies(connectionId, unacknowledgedOnly=true)`. CLI: `deepsql growth anomalies --connection <c> --unack` |
+| "Force a fresh stats snapshot" (admin) | `deepsql growth capture --connection <c>` |
+| "Set / view growth alert thresholds" (admin) | `deepsql growth config show --connection <c>` / `set --file <p>` |
 | "What indexes are we missing?" / "Index advice" | `deepsql indexes missing --connection <c>` |
 | "Are any indexes unused?" / "Index bloat" | `deepsql indexes unused --connection <c>` |
 | "Duplicate indexes?" | `deepsql indexes duplicates --connection <c>` |

package/src/auth/store.js

@@ -30,18 +30,18 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const os = require("node:os");
+const { userHome } = require("../user-home");
 
 function configDir() {
   const override = process.env.DEEPSQL_CONFIG_DIR;
   if (override) return override;
   if (process.platform === "win32") {
-    const base = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    const base = process.env.APPDATA || path.join(userHome(), "AppData", "Roaming");
     return path.join(base, "deepsql");
   }
   const xdg = process.env.XDG_CONFIG_HOME;
   if (xdg) return path.join(xdg, "deepsql");
-  return path.join(os.homedir(), ".config", "deepsql");
+  return path.join(userHome(), ".config", "deepsql");
 }
 
 function authFilePath() {

package/src/cli.js

@@ -31,12 +31,12 @@ const COMMANDS = {
   relationships: () => require("./commands/relationships"),
   "anti-patterns": () => require("./commands/anti-patterns"),
   digest: () => require("./commands/digest"),
+  growth: () => require("./commands/growth"),
   indexes: () => require("./commands/indexes"),
   users: () => require("./commands/users"),
   access: () => require("./commands/access"),
   permissions: () => require("./commands/permissions"),
   "slow-queries": () => require("./commands/slow-queries"),
-  "index-recommendations": () => require("./commands/index-recommendations"),
   setup: () => require("./commands/setup"),
 };
 
@@ -56,12 +56,12 @@ const COMMAND_LIST = [
   ["analyze",        false, "AI-enriched query plan analysis (use --analyze for EXPLAIN ANALYZE)"],
   ["schema",         false, "Dump connection schema or DB objects as JSON"],
   ["digest",         true,  "Show DeepSQL daily digests"],
+  ["growth",         true,  "Table growth analytics — trends, history, anomalies, alert config"],
   ["brain-context",  false, "Retrieve embedding-ranked context for a question"],
   ["business-rules", false, "List active business rules and SQL guardrails"],
   ["relationships",  false, "List inferred and validated FK relationships"],
   ["anti-patterns",  false, "List schema- or query-level anti-patterns"],
-  ["indexes",        true,  "Index suggestions, usage, and health (read-only)"],
-  ["index-recommendations", true, "Workload-weighted index advisor + HypoPG-validated apply tool"],
+  ["indexes",        true,  "Workload-weighted index advisor + catalog diagnostics (top, apply, list, missing, health, unused, duplicates, usage)"],
   ["users",          true,  "Manage workspace users (admin)"],
   ["access",         true,  "Manage per-connection access grants (admin)"],
   ["permissions",    true,  "Manage role-based permission overrides (admin)"],
@@ -226,6 +226,29 @@ const COMMAND_HELP = {
     ],
   },
 
+  growth: {
+    description: "Table growth analytics — size/row trends, detected anomalies, alert thresholds.",
+    usage: "deepsql growth <subcommand> [options]",
+    subcommands: [
+      ["trends    [--table <t>] [--days N=30]",     "Per-table growth headline over the last N days (default)"],
+      ["history   [--table <t>] [--days N=7]",      "Raw snapshot history rows"],
+      ["anomalies [--table <t>] [--unack] [--days N=30]", "Sudden growth spikes flagged by severity"],
+      ["ack       <anomalyId>",                     "Acknowledge an anomaly"],
+      ["capture",                                   "Trigger a fresh stats snapshot (admin; async)"],
+      ["config    show [--table <t>]",              "Show alert thresholds for the connection"],
+      ["config    set --file <path>",               "POST a GrowthAlertConfiguration JSON (admin)"],
+    ],
+    options: [
+      ["--connection <name>",  "Connection to inspect"],
+      ["--table <name>",       "Filter to one table"],
+      ["--days <N>",           "Lookback window in days (max 365)"],
+      ["--unack",              "anomalies: only unacknowledged ones"],
+      ["--file <path>",        "config set: path to GrowthAlertConfiguration JSON"],
+      ["--json",               "Raw JSON output"],
+    ],
+    notes: "`capture` and `config set` are the only mutations; both are admin-level but neither writes user data. Trends + anomalies are the agent-facing subcommands and are also exposed via the MCP tools `get_table_growth` and `get_growth_anomalies`.",
+  },
+
   "brain-context": {
     description: "Retrieve embedding-ranked tables/columns/FKs, training docs, and business rules for a question.",
     usage: 'deepsql brain-context "<question>" --connection <name> [options]',
@@ -267,23 +290,41 @@ const COMMAND_HELP = {
   },
 
   indexes: {
-    description: "Index suggestions, usage, and health — read-only in V1.",
+    description:
+      "Unified index advisor — workload-weighted recommendations + catalog diagnostics. " +
+      "`apply` is the one mutation; dry-run is the default and uses HypoPG on Postgres " +
+      "to estimate cost-delta without writes. Write modes (apply / apply-and-measure) " +
+      "require --confirm.",
     usage: "deepsql indexes <subcommand> [options]",
     subcommands: [
-      ["list [--all] [--status <s>]", "Index recommendations (defaults to PENDING)"],
-      ["missing",                     "Missing-index suggestions from the advisor"],
-      ["health",                      "Comprehensive index health report"],
-      ["unused",                      "Indexes the engine has not used"],
-      ["duplicates",                  "Duplicate or redundant indexes"],
-      ["usage <table>",               "Per-table index usage statistics"],
+      // Advisor (workload-weighted)
+      ["top    [--limit N]",                                  "Pre-computed top-N pending recommendations (default 5, max 50) — ranked by net benefit, with HypoPG cost-delta + contributing-query evidence"],
+      ["list   [--all] [--status PENDING|APPLIED|DISMISSED]", "All recommendations (defaults to PENDING) — simpler view than `top`"],
+      ["show   <id> --connection <name>",                     "Full detail: workload, write-cost, HypoPG cost, contributing queries"],
+      ["refresh",                                              "Force a fresh accumulation cycle (POST /generate)"],
+      ["apply  <id> [--mode <m>] [--confirm] [--no-concurrent]", "Run or dry-run a recommendation with before/after measurement"],
+      ["dismiss <id>",                                         "Mark a recommendation as DISMISSED"],
+      // Catalog diagnostics
+      ["missing",                                              "Missing-index suggestions from the catalog advisor"],
+      ["health",                                               "Comprehensive index health report"],
+      ["unused",                                               "Indexes the engine has not used (live pg_stat_user_indexes / sys.* probe)"],
+      ["duplicates",                                           "Duplicate or redundant indexes"],
+      ["usage  <table>",                                       "Per-table index usage statistics"],
     ],
     options: [
-      ["--connection <name>",            "Connection to inspect"],
-      ["--all",                          "Include APPLIED and DISMISSED in `list`"],
-      ["--status PENDING|APPLIED|DISMISSED", "Filter `list` by status"],
-      ["--json",                         "Raw JSON output"],
+      ["--connection <name>",                       "Connection to inspect"],
+      ["--limit <n>",                               "top: number of recommendations (default 5, max 50)"],
+      ["--all",                                     "list: include APPLIED and DISMISSED rows"],
+      ["--status PENDING|APPLIED|DISMISSED",        "list: filter by status"],
+      ["--mode dry-run|apply|apply-and-measure",    "apply: defaults to dry-run (HypoPG; no writes)"],
+      ["--confirm",                                 "apply: required for apply / apply-and-measure (write modes)"],
+      ["--no-concurrent",                           "apply: skip CREATE/DROP INDEX CONCURRENTLY (small dev tables)"],
+      ["--json",                                    "Raw backend JSON instead of the terminal-friendly table"],
     ],
-    notes: "V1 is read-only. Apply, dismiss, delete, and generate are not exposed by the CLI yet.",
+    notes:
+      "Mirrors the MCP `get_index_recommendations` + `apply_index_recommendation` tools — " +
+      "use this when you're at a terminal, the MCP tools when you're inside an AI client. " +
+      "Same backend, same data, same safety contract.",
   },
 
   users: {
@@ -363,33 +404,6 @@ const COMMAND_HELP = {
     notes: "Org and LLM config are set at install time and are NOT touched by this wizard.",
   },
 
-  "index-recommendations": {
-    description:
-      "DBA-grade workload-weighted index advisor. Default `top` shows pending " +
-      "recommendations ranked by net benefit (workload − write-cost). `apply` " +
-      "is the only mutation — dry-run uses HypoPG (Postgres-only) so no writes " +
-      "leak; the two write modes require --confirm.",
-    usage:
-      "deepsql index-recommendations <top|list|show|refresh|apply|dismiss> [options]",
-    subcommands: [
-      ["top    --connection <name> [--limit N]",     "Pre-computed top-N (default 5, max 50), evidence-bearing"],
-      ["list   --connection <name>",                  "All pending recommendations for the connection"],
-      ["show   <id> --connection <name>",             "Full detail: workload, HypoPG cost, contributing queries"],
-      ["refresh --connection <name>",                 "Force a fresh accumulation cycle (POST /generate)"],
-      ["apply  <id> [--mode <m>] [--confirm]",        "Run / dry-run with before/after measurement"],
-      ["dismiss <id>",                                 "Mark a recommendation as DISMISSED"],
-    ],
-    options: [
-      ["--limit <n>",        "top: number of recommendations (default 5, max 50)"],
-      ["--mode <m>",         "apply: dry-run (default) | apply | apply-and-measure"],
-      ["--confirm",          "apply: required for apply / apply-and-measure (write modes)"],
-      ["--no-concurrent",    "apply: skip CREATE/DROP INDEX CONCURRENTLY (dev / small tables)"],
-      ["--json",             "Emit raw backend JSON instead of the terminal-friendly table"],
-    ],
-    notes:
-      "Complements `deepsql indexes` (catalog-level usage / health). " +
-      "This namespace surfaces the workload-weighted advisor + the apply tool.",
-  },
 };
 
 // ─── Color helpers ──────────────────────────────────────────────────────────
@@ -576,6 +590,11 @@ function buildOpts(parsed) {
     // Indexes
     all: !!f.all,
     status: f.status || null,
+    // Growth analytics (also re-used wherever a per-table / lookback filter
+    // is useful — kept generic on purpose)
+    table: f.table || null,
+    days: f.days || null,
+    unack: !!f.unack,
     // mcp config installer
     install: !!f.install,
     print: !!f.print,