@deepsql/mcp 0.13.4 → 0.16.0

package/CLAUDE.md

@@ -33,8 +33,9 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes 10 tools. They all take a `connectionId` (UUID
-returned by `list_connections`).
+The MCP server exposes 12 tools. They all take a `connectionId` (UUID
+returned by `list_connections`) except `apply_index_recommendation`,
+which takes a server-resolved `recommendationId`.
 
 | Tool | Purpose |
 |---|---|
@@ -46,6 +47,8 @@ returned by `list_connections`).
 | `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_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. |
 | **`analyze_query_plan`** | **AI-enriched plan analysis** for a query. Returns the parsed plan tree, performance issues, index recommendations, and a written summary that takes the connection's schema and business rules into account. Pass `useAnalyze: true` to run `EXPLAIN ANALYZE` (actually executes the query). |
 
@@ -206,13 +209,27 @@ gates that protect `execute_sql` kick in. You'll get back
 get `requiresConfirmation` — surface the warnings to the user verbatim, wait
 for them to say yes, then re-call with `confirmMutation: true`.
 
-**"What indexes should we add?"** → Not exposed via MCP yet. Tell the user
-to run `deepsql indexes missing` or `deepsql indexes health` in their
-terminal.
+**"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. 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
+Postgres it uses HypoPG to install a virtual index, EXPLAINs each
+contributing query, and reports the planner cost delta — no writes
+hit the database. If the user wants real timings, pass
+`mode: "APPLY_AND_MEASURE"` plus `confirm: true` to actually create
+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
@@ -305,10 +322,16 @@ them at the terminal command rather than trying to fake it through
 
 | Capability | CLI command |
 |---|---|
-| Index recommendations / missing-index advisor | `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 (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

@@ -143,6 +143,56 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "apply_index_recommendation",
+    description:
+      "Apply (or dry-run) an index recommendation and measure the before/after benefit on the queries that motivated it. " +
+      "Default mode is DRY_RUN — no writes; uses HypoPG (Postgres-only) to install a virtual index in the session, EXPLAIN-diffs the cost on each contributing query, then resets. " +
+      "APPLY mode runs the real DDL (CREATE INDEX CONCURRENTLY / DROP INDEX CONCURRENTLY on Postgres so the operation doesn't lock the table). " +
+      "APPLY_AND_MEASURE additionally runs EXPLAIN ANALYZE before and after for wall-clock timings — slowest, only opt in when you're OK executing the contributing queries against the target DB. " +
+      "Both APPLY modes require `confirm: true` — write operations don't happen by accident. " +
+      "Returns the executed DDL, the planner-cost delta, per-sample measurements (each contributing query's before/after cost), and an aggregate improvement percentage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        recommendationId: { type: "string", description: "Recommendation row id (from get_index_recommendations)." },
+        mode: {
+          type: "string",
+          enum: ["DRY_RUN", "APPLY", "APPLY_AND_MEASURE"],
+          description: "Default DRY_RUN. APPLY mutates the database; APPLY_AND_MEASURE also runs EXPLAIN ANALYZE."
+        },
+        confirm: {
+          type: "boolean",
+          description: "Required `true` for APPLY and APPLY_AND_MEASURE. Defaults to false."
+        },
+        concurrent: {
+          type: "boolean",
+          description: "Postgres-only. When true (default), CREATE/DROP runs CONCURRENTLY (no table lock, but waits for every pre-existing transaction). Set false on small dev tables when the brief ACCESS EXCLUSIVE lock is acceptable."
+        }
+      },
+      required: ["recommendationId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_index_recommendations",
+    description:
+      "Get DeepSQL's pre-computed top index recommendations for a connection. Recommendations are workload-weighted (Σ calls × mean_exec_time, the pganalyze / Microsoft DTA 'total time' ROI metric) and aggregated across many slow-query log fetches over a configurable lookback (default 30 days). Column ordering for composite indexes follows industry rules (equality before range, selectivity-ranked, ORDER BY suffix only with full-equality prefix, capped at 3 columns). Covers both CREATE_INDEX and DROP_INDEX (unused + redundant prefix-duplicate) candidates. Each result carries net benefit (workload − write cost), the contributing query fingerprints, and call/duration metrics — so a caller can audit *why* each suggestion exists rather than trust a heuristic. Returns top N (default 5) PENDING recommendations.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 50,
+          description: "Number of recommendations to return. Defaults to 5.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "analyze_slow_queries",
     description:
@@ -551,6 +601,92 @@ function summarizeAntiPatterns(payload, kind) {
   return `${list.length} query anti-pattern(s)${sevStr ? ` (${sevStr})` : ""}.`;
 }
 
+function formatMillisHuman(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms <= 0) return null;
+  if (ms >= 86_400_000) return `${(ms / 86_400_000).toFixed(1)}d`;
+  if (ms >= 3_600_000) return `${(ms / 3_600_000).toFixed(1)}h`;
+  if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
+  if (ms >= 1_000) return `${(ms / 1_000).toFixed(1)}s`;
+  return `${ms}ms`;
+}
+
+function summarizeApplyResult(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "Apply call returned no body.";
+  }
+  const status = payload.status || "?";
+  const mode = payload.mode || "?";
+  if (status === "BLOCKED_NEEDS_CONFIRMATION") {
+    return `[${mode}] blocked — pass confirm=true to mutate the database.`;
+  }
+  if (status === "NOT_FOUND") {
+    return `[${mode}] recommendation not found: ${payload.recommendationId || "?"}`;
+  }
+  if (status === "NO_USABLE_SAMPLES") {
+    return `[${mode}] no literal-bearing contributing queries available; cannot measure.`;
+  }
+  if (status === "FAILED") {
+    return `[${mode}] failed: ${payload.message || "(no message)"}`;
+  }
+
+  const lines = [];
+  lines.push(`[${mode}] ${status} — ${payload.executedDdl || "(no ddl)"}`);
+  if (payload.beforeCost != null && payload.afterCost != null) {
+    const pct = payload.costReductionPct;
+    lines.push(
+      `  planner cost: ${payload.beforeCost.toFixed(0)} → ${payload.afterCost.toFixed(0)}` +
+        (pct != null ? ` (${pct >= 0 ? "−" : "+"}${Math.abs(pct).toFixed(1)}%)` : "")
+    );
+  }
+  if (payload.beforeWallTimeMs != null && payload.afterWallTimeMs != null) {
+    const pct = payload.wallTimeImprovementPct;
+    lines.push(
+      `  wall time: ${payload.beforeWallTimeMs.toFixed(1)}ms → ${payload.afterWallTimeMs.toFixed(1)}ms` +
+        (pct != null ? ` (${pct >= 0 ? "−" : "+"}${Math.abs(pct).toFixed(1)}%)` : "")
+    );
+  }
+  if (Array.isArray(payload.samples) && payload.samples.length) {
+    lines.push(`  ${payload.samples.length} contributing query sample(s):`);
+    for (const s of payload.samples.slice(0, 5)) {
+      const before = s.beforeCost != null ? s.beforeCost.toFixed(0) : "?";
+      const after = s.afterCost != null ? s.afterCost.toFixed(0) : "?";
+      lines.push(
+        `    fp=${(s.fingerprint || "?").slice(0, 12)} cost ${before} → ${after}` +
+          (s.error ? ` (error: ${s.error})` : "")
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+function summarizeIndexRecommendations(payload) {
+  const list = Array.isArray(payload) ? payload : payload?.recommendations || [];
+  if (!list.length) {
+    return "No pending index recommendations. The scheduler may not have run yet, or the workload has none worth flagging.";
+  }
+  const lines = list.slice(0, 10).map((rec, idx) => {
+    const table = rec.tableName || "?";
+    const prio = rec.priority || "?";
+    const occ = rec.occurrenceCount != null ? `seen ${rec.occurrenceCount}×` : "";
+    const net = formatMillisHuman(rec.netBenefitMs);
+    const writeCost = formatMillisHuman(rec.writeCostScore);
+    const evidence = rec.evidenceCount != null && rec.evidenceCount > 0
+      ? `${rec.evidenceCount} ev` : "";
+    const isDrop = rec.kind === "DROP_INDEX";
+    const action = isDrop ? "DROP" : "CREATE";
+    const target = isDrop
+      ? `${table}.${rec.indexName || "?"} (unused)`
+      : `${table}(${rec.columnNames || "?"})`;
+    // Net benefit is the DBA-grade signal — surface it prominently.
+    const benefitClause = net
+      ? `net=${net} saved` + (writeCost ? `, write=${writeCost}` : "")
+      : (rec.estimatedImpact != null ? `impact ${rec.estimatedImpact}` : "");
+    const meta = [prio, occ, benefitClause, evidence].filter(Boolean).join(", ");
+    return `${idx + 1}. [${action}] ${target}${meta ? ` — ${meta}` : ""}`;
+  });
+  return `Top ${list.length} pending index recommendation(s):\n${lines.join("\n")}`;
+}
+
 function summarizeSlowQueries(payload) {
   // Backend returns SlowQueryAnalysis with `topSlowQueries` (the field name
   // varies; tolerate both `queries` and `topSlowQueries`).
@@ -649,6 +785,12 @@ function buildToolResult(name, payload, extra = {}) {
     case "analyze_slow_queries":
       summary = summarizeSlowQueries(payload);
       break;
+    case "get_index_recommendations":
+      summary = summarizeIndexRecommendations(payload);
+      break;
+    case "apply_index_recommendation":
+      summary = summarizeApplyResult(payload);
+      break;
     case "execute_sql":
       summary = summarizeQueryResult(payload);
       break;
@@ -775,6 +917,40 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload, { kind });
     }
 
+    case "get_index_recommendations": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const limit = clampInteger(args.limit, 1, 50, 5);
+      const payload = await callDeepSqlApi(
+        config,
+        `/index-recommendations/${encodeURIComponent(connectionId)}/top?limit=${limit}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "apply_index_recommendation": {
+      const recommendationId = String(args.recommendationId || "").trim();
+      if (!recommendationId) return buildToolError("recommendationId is required.");
+      const mode = String(args.mode || "DRY_RUN").toUpperCase();
+      if (!["DRY_RUN", "APPLY", "APPLY_AND_MEASURE"].includes(mode)) {
+        return buildToolError(`Unknown mode: ${mode}. Expected DRY_RUN, APPLY, or APPLY_AND_MEASURE.`);
+      }
+      const confirm = args.confirm === true;
+      if ((mode === "APPLY" || mode === "APPLY_AND_MEASURE") && !confirm) {
+        return buildToolError(
+          `Mode ${mode} mutates the target database. Re-call with confirm=true to proceed.`,
+        );
+      }
+      const concurrent = args.concurrent === false ? false : true;
+      const qs = `?mode=${encodeURIComponent(mode)}&confirm=${confirm}&concurrent=${concurrent}`;
+      const payload = await callDeepSqlApi(
+        config,
+        `/index-recommendations/${encodeURIComponent(recommendationId)}/apply${qs}`,
+        { method: "POST" },
+      );
+      return buildToolResult(name, payload);
+    }
+
     case "analyze_slow_queries": {
       const connectionId = String(args.connectionId || "").trim();
       if (!connectionId) return buildToolError("connectionId is required.");
@@ -898,5 +1074,7 @@ module.exports = {
   stripTrailingSemicolons,
   stripSqlComments,
   stripSqlStringLiterals,
+  summarizeApplyResult,
+  summarizeIndexRecommendations,
   validateReadOnlySql,
 };

package/package.json

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

package/skills/SKILL_BODY.md

@@ -1,12 +1,22 @@
 # DeepSQL — your database DBA consult
 
-You have DeepSQL's MCP tools loaded. **DeepSQL is the source of truth for
-the live schema, business rules, FK relationships, and anti-patterns of
-the database the user is working against.** Treat it the way a thoughtful
-engineer treats a DBA: consult before you commit anything schema-shaped.
+You have two DeepSQL surfaces available:
 
-This skill triggers any time the user is doing database work. The rules
-below are non-negotiable.
+1. **MCP tools** — JSON-RPC tools loaded into your session (10 of them).
+   Use these for in-session retrieval and SQL execution.
+
+2. **`deepsql` CLI** — a shell binary on the user's PATH (~19 commands).
+   Use this for things the MCP doesn't expose (index health, daily
+   digest, slow-query streaming, connection management, admin ops, the
+   plan-analysis `analyze` command, etc.). You can shell out to the CLI
+   yourself when appropriate; you can also point the user at the
+   command if it's interactive.
+
+**DeepSQL is the source of truth for the live schema, business rules, FK
+relationships, and anti-patterns of the database the user is working
+against.** Treat it the way a thoughtful engineer treats a DBA: consult
+before you commit anything schema-shaped. This skill triggers any time
+the user is doing database work. The rules below are non-negotiable.
 
 ---
 
@@ -65,21 +75,115 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 
 ---
 
-## Running SQL
+## MCP tools — your in-session toolkit
 
-| You want to… | Use this tool |
+| Tool | When to call |
 |---|---|
-| Run any SQL (SELECT / EXPLAIN / DML / DDL) | `execute_sql(connectionId, query, ...)` |
-| Get AI-enriched plan analysis for a query | `analyze_query_plan(connectionId, query, useAnalyze=false)` |
-| Actually execute the query AND get the plan (real timings) | `analyze_query_plan(..., useAnalyze=true)` |
+| `list_connections` | Always first; get the UUID. |
+| `get_brain_context(connectionId, question)` | Step 2 of the checklist above. The most important tool. |
+| `get_schema(connectionId)` | Full column inventory for the tables you're touching. |
+| `get_database_objects(connectionId)` | Tables/views/functions/procedures (broader than schema). |
+| `list_business_rules(connectionId, question?)` | Rules the SQL must respect. |
+| `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. |
+| `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). |
 
 `EXPLAIN` and `EXPLAIN ANALYZE` are just SQL — type them as the query if
 you want raw plan output. Use `analyze_query_plan` when you want the
-AI-enriched analysis (issues, index recommendations, written summary).
+AI-enriched analysis.
 
-### Mutations are role-gated and two-step
+---
 
-`execute_sql` enforces the same policy as the SQL Editor:
+## `deepsql` CLI — for everything the MCP doesn't expose
+
+The CLI is the user's primary interface to DeepSQL. As a coding agent,
+**you can shell out to it** to do things the MCP doesn't have, or to
+help the user when interactive setup is required (login, MCP install,
+new connection registration). Always pass `--caller-agent <your-name>`
+on shell-outs so the audit log captures the chain ("deepsql query
+called by claude-code via deepsql CLI").
+
+```bash
+deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
+```
+
+### Command catalog (19 top-level commands)
+
+| Command | What it does | MCP equivalent? |
+|---|---|---|
+| `deepsql login` | Authorize CLI against a DeepSQL host (browser PKCE / device code / password) | none — interactive only |
+| `deepsql logout` | Revoke the saved token | none |
+| `deepsql whoami` | Show the logged-in user, role, URL, pinned connection | none |
+| `deepsql config show\|set-default <url>\|path` | Manage saved profiles | none |
+| `deepsql mcp` | Run the stdio MCP server | this skill spawns it |
+| `deepsql mcp config --install --for <editor>` | Install MCP entry + this skill into editor config | none — interactive |
+| `deepsql connections list\|use\|current\|unset\|schema\|add\|update\|remove\|test\|show\|init` | Full connection CRUD | partial: `list_connections`, `get_schema` |
+| `deepsql query "<sql>" --connection <c>` | Execute SQL (admin: `--write` for mutations) | `execute_sql` |
+| `deepsql analyze "<sql>" --connection <c>` | AI plan analysis (`--analyze` for EXPLAIN ANALYZE) | `analyze_query_plan` |
+| `deepsql schema [tables\|objects] --connection <c>` | Dump full schema as JSON | `get_schema` / `get_database_objects` |
+| `deepsql brain-context "<question>" --connection <c>` | Same retrieval as the MCP tool | `get_brain_context` |
+| `deepsql business-rules --connection <c>` | List active business rules | `list_business_rules` |
+| `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 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 |
+| `deepsql access list\|grant\|revoke\|policy <user> <conn>` | **Admin-only, CLI-only**: per-connection access grants + chat policy editing in $EDITOR | none |
+| `deepsql permissions list\|override\|reset` | **Admin-only, CLI-only**: role-based permission overrides | none |
+| `deepsql setup` | **Admin-only**: post-install wizard for SMTP/email + Slack | none |
+
+Run `deepsql <command> --help` for option-level detail. Run
+`deepsql --help` for the live catalog (the CLI is the source of truth
+if this table goes stale).
+
+### CLI-only capabilities — point the user at these or run them
+
+When the user asks for something only the CLI does, either run it via
+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) |
+| "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>` |
+| "Index health on this connection" | `deepsql indexes health --connection <c>` |
+| "Indexes on `<table>` and how often they're used" | `deepsql indexes usage <table> --connection <c>` |
+| "Optimize this slow query with AI" / "Stream me a fix" | `deepsql slow-queries optimize --connection <c> --query-id <id>` |
+| "Add a new database connection" | `deepsql connections add` (interactive) or `--from-file <path>` |
+| "Test a connection without saving" | `deepsql connections test --from-file <path>` |
+| "Trigger brain re-initialization for this connection" | `deepsql connections init <name> --wait` |
+| "Add a user / change a user's role" | `deepsql users add` / `deepsql users set-role <ref> <role>` |
+| "Grant / revoke connection access" | `deepsql access grant --user <ref> --connection <c> --level read\|write\|admin` |
+| "Edit the chat data-access policy for `<user>` on `<conn>`" | `deepsql access policy <user> <conn>` (opens `$EDITOR`) |
+
+### Shelling out from the agent — the convention
+
+When you run `deepsql` yourself:
+
+```bash
+deepsql <command> [options] --caller-agent <your-agent-id> --json
+```
+
+- **Always pass `--caller-agent`** (or set `DEEPSQL_CALLER_AGENT` env
+  var once) so the audit row captures the chain. Use a stable id like
+  `claude-code`, `cursor`, or `codex`.
+- **Prefer `--json`** for parseable output. Without it, output is
+  pretty-printed for humans and harder to parse.
+- **Don't chain destructive ops without confirmation.** `deepsql
+  connections remove`, `deepsql users delete`, `deepsql permissions
+  override --revoke`, etc. all support `--yes` to skip the prompt — but
+  YOU should not pass `--yes` unless the user has explicitly approved
+  the specific action.
+
+---
+
+## Mutations are role-gated and two-step (both MCP and CLI)
+
+`execute_sql` (MCP) and `deepsql query` (CLI) enforce the same policy:
 
 - **Developer + SELECT/WITH/SHOW/EXPLAIN** → runs immediately.
 - **Developer + DML/DDL** → 403 `EDITOR_MUTATION_FORBIDDEN`. Don't retry.
@@ -89,26 +193,51 @@ AI-enriched analysis (issues, index recommendations, written summary).
 - **Admin + DML/DDL (no `confirmMutation`)** → returns
   `requiresConfirmation: true` with a `warnings` array. **Show the
   warnings to the user verbatim. Wait for explicit OK.** Then re-call
-  with `confirmMutation: true`. **Do not silently retry with
-  `confirmMutation: true` on the user's behalf** — that defeats the
+  with `confirmMutation: true` (MCP) or `--write` (CLI). **Do not
+  silently retry on the user's behalf** — that defeats the
   confirmation step.
 
-### Row limits
+## Row limits
+
+`execute_sql` / `deepsql query` defaults to 100 rows, max 1000. If you
+asked for "all customers" and got 100, that's the limit kicking in —
+not the real count. Either bump `--limit`/`limit:` or `SELECT COUNT(*)`
+first.
 
-`execute_sql` defaults to 100 rows, max 1000. If you asked for "all
-customers" and got 100, that's the limit kicking in — not the real count.
-Either bump `limit` or `SELECT COUNT(*)` first.
+---
+
+## Helping the user when DeepSQL itself isn't set up
+
+The user might not have DeepSQL fully wired up when they ask their
+first database question. If you get a clear "not configured" error,
+run / suggest these:
+
+| Symptom | Fix |
+|---|---|
+| `deepsql --version` not found / not on PATH | `npm install -g @deepsql/mcp@latest` (Node ≥ 20). |
+| MCP tools missing from your session | Run `deepsql mcp config --install --for claude-code` (or `cursor`/`codex`/`claude-desktop`) on the user's machine. They restart the editor. |
+| CLI says "No saved DeepSQL profile" | `deepsql login --url https://<their-deepsql-host>` (browser flow on desktop, `--device` for SSH boxes). |
+| MCP tools error with 401 | Token expired. `deepsql logout && deepsql login --url <host>` then restart the editor. |
+| `connections list` is empty | Walk the user through `deepsql connections add` interactively, or use `--from-file <path>` with a JSON config file. |
+| `connections test` reports "Missing privileges: SELECT, ..." | The DB user has insufficient grants. The connection saves anyway (read access is enough for some features), but flag it. |
+| Connection config schema | `deepsql connections schema --json` (JSON Schema for the input format). |
 
 ---
 
-## Every call is audited
+## Every call is audited (both surfaces)
 
-Every tool call you make is logged to the DeepSQL `security_events` table
-with the user's identity, the editor that invoked the MCP server
-(claude-desktop, cursor-mcp, codex-mcp), the connection, the truncated
-statement, and the outcome. Workspace admins can search this. Don't do
-anything through these tools you wouldn't be willing to defend in that
-view.
+Every MCP tool call AND every `deepsql` CLI invocation that hits the
+backend is logged to the DeepSQL `security_events` table with:
+
+- the user's identity (from the bearer token or saved profile)
+- the editor / agent that originated the request (`claude-code`,
+  `cursor`, `codex`, etc. — from the `--caller-agent` flag or
+  `DEEPSQL_MCP_USER_ID` env var)
+- the surface (`mcp` vs `cli`)
+- the connection, the truncated statement, and the outcome
+
+Workspace admins can search this. Don't do anything through these
+tools you wouldn't be willing to defend in that view.
 
 ---
 
@@ -116,10 +245,17 @@ view.
 
 The complete runtime guide — every decision-tree branch, every foot-gun,
 all three session playbooks (answer-a-question, mutation, DBA-consult) —
-lives in `node_modules/@deepsql/mcp/CLAUDE.md`. Read it the first time
-you handle a non-trivial database request.
+lives in the package's `CLAUDE.md`. After install:
+
+```
+node_modules/@deepsql/mcp/CLAUDE.md       # local install
+$(npm root -g)/@deepsql/mcp/CLAUDE.md     # global install
+```
+
+The CLI is its own source of truth too — if this table drifts from
+reality, run:
 
-Capabilities that aren't MCP-exposed yet (index recommendations, daily
-digest, slow-query streaming optimization) live in the CLI: `deepsql
-indexes`, `deepsql digest`, `deepsql slow-queries optimize`. Point the
-user at them.
+```bash
+deepsql --help                            # live command list
+deepsql <command> --help                  # full options for one command
+```

package/src/cli.js

@@ -59,7 +59,7 @@ const COMMAND_LIST = [
   ["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)"],
+  ["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)"],
@@ -265,23 +265,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: {
@@ -360,6 +378,7 @@ const COMMAND_HELP = {
     ],
     notes: "Org and LLM config are set at install time and are NOT touched by this wizard.",
   },
+
 };
 
 // ─── Color helpers ──────────────────────────────────────────────────────────
@@ -564,6 +583,10 @@ function buildOpts(parsed) {
     skipComplete: !!f.skipComplete,
     // Confirmations
     yes: !!f.yes || !!f.y,
+    // Index recommendations (apply tool)
+    mode: f.mode || null,
+    confirm: !!f.confirm,
+    noConcurrent: !!f.noConcurrent,
     // Connection management
     fromFile: f.fromFile || null,
     fromStdin: !!f.fromStdin,