@deepsql/mcp 0.22.0 → 0.26.0

package/src/commands/_agent_status.js

@@ -0,0 +1,93 @@
+"use strict";
+
+// Best-effort onboarding data for the agent intro: the connections this token
+// can see, plus per-connection "needs attention" suggestions for connections the
+// user can configure (admin-level). Uses EXISTING backend endpoints only:
+//   GET /connections                       (RBAC-scoped list, with canManageConfig)
+//   GET /connections/{id}/init-status       (brain readiness: currentStage)
+//   GET /slow-log-source/{id}               (slow-query log: enabled)
+//
+// Everything is wrapped in tight timeouts and swallows errors, so a slow or old
+// backend (missing an endpoint) degrades to "show whatever we have" and never
+// blocks the REPL.
+
+const { request } = require("../api/client");
+const { listConnections } = require("./_connections");
+
+function withTimeout(p, ms) {
+  return Promise.race([
+    Promise.resolve(p),
+    new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), ms)),
+  ]);
+}
+
+// Derive config suggestions + a brain-recommendation count for one connection
+// from its status endpoints. Returns { items: [...attention], recCount }.
+async function checkConnection(session, c) {
+  const out = [];
+  const [init, slow, recs] = await Promise.all([
+    request(session.baseUrl, `/connections/${encodeURIComponent(c.id)}/init-status`, {
+      token: session.token,
+    }).catch(() => null),
+    request(session.baseUrl, `/slow-log-source/${encodeURIComponent(c.id)}`, {
+      token: session.token,
+    }).catch(() => null),
+    // totalCount tracks the limit, so request enough to give an accurate-ish
+    // "N to review" nudge (the brain command shows the full list).
+    request(session.baseUrl, `/brain/notes/suggestions/${encodeURIComponent(c.id)}?limit=25`, {
+      token: session.token,
+    }).catch(() => null),
+  ]);
+
+  const stage = init && init.currentStage;
+  const pct = (init && init.progressPercent) || 0;
+  if (stage === "FAILED") {
+    out.push({ conn: c.name, text: "brain initialization failed", fix: `deepsql connections init ${c.name}` });
+  } else if (stage && stage !== "READY" && pct < 100) {
+    // Skip near-done (100% but not yet flipped to READY) — don't nag.
+    out.push({ conn: c.name, text: `brain still initializing (${pct}%)`, fix: `deepsql connections init ${c.name}` });
+  }
+  if (slow && slow.enabled !== true) {
+    out.push({
+      conn: c.name,
+      text: "slow-query log not connected",
+      fix: "set it up in the web UI → Slow Query Log",
+    });
+  }
+  // Brain recommendations to review (only meaningful once the brain is trained).
+  const recCount = stage !== "FAILED" && recs && typeof recs.totalCount === "number" ? recs.totalCount : 0;
+  return { items: out, recCount };
+}
+
+// Returns { connections: [{name,dbType,canManage}], suggestions: [{conn,text,fix}] }.
+async function loadIntroData(session, { timeoutMs = 2500 } = {}) {
+  const data = { connections: [], suggestions: [], recommendationCount: 0 };
+  try {
+    const list = await withTimeout(listConnections(session), timeoutMs);
+    data.connections = (list || []).map((c) => ({
+      id: c.id,
+      name: c.connectionName || c.name || c.id,
+      dbType: c.dbType || "",
+      canManage: !!c.canManageConfig,
+    }));
+    // Status/suggestions only for connections this user can configure
+    // (admin-level), capped so a workspace with many connections doesn't fan
+    // out at startup.
+    const manageable = data.connections.filter((c) => c.canManage).slice(0, 6);
+    if (manageable.length) {
+      const checks = await withTimeout(
+        Promise.all(
+          manageable.map((c) => checkConnection(session, c).catch(() => ({ items: [], recCount: 0 })))
+        ),
+        timeoutMs
+      );
+      data.suggestions = checks.flatMap((r) => r.items);
+      data.recommendationCount = checks.reduce((n, r) => n + (r.recCount || 0), 0);
+    }
+  } catch {
+    /* degrade gracefully — render whatever we have */
+  }
+  return data;
+}
+
+module.exports = { loadIntroData };

package/src/commands/_connections.js

@@ -17,16 +17,40 @@
  */
 
 const { request } = require("../api/client");
+const cache = require("../connections/cache");
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-let cachedList = null;
+let inProcess = null; // L1: within a single command invocation
 
-async function listConnections(session) {
-  if (cachedList) return cachedList;
-  cachedList = await request(session.baseUrl, "/connections", { token: session.token });
-  if (!Array.isArray(cachedList)) cachedList = [];
-  return cachedList;
+// Connections list with two cache tiers: the in-process memo (L1) and a short-
+// TTL on-disk cache (L2) shared across `deepsql` invocations. Pass refresh:true
+// to bypass both and fetch live (then refresh the caches).
+async function listConnections(session, { refresh = false } = {}) {
+  if (!refresh) {
+    if (inProcess) return inProcess;
+    const disk = cache.read(session.baseUrl);
+    if (disk) {
+      inProcess = disk;
+      return disk;
+    }
+  }
+  const fetched = await request(session.baseUrl, "/connections", { token: session.token });
+  const list = Array.isArray(fetched) ? fetched : [];
+  inProcess = list;
+  cache.write(session.baseUrl, list);
+  return list;
+}
+
+function matchConnection(connections, trimmed) {
+  const exact = connections.filter((c) => (c.connectionName || c.name) === trimmed);
+  if (exact.length === 1) return { id: exact[0].id || exact[0].connectionId };
+  const ci = connections.filter(
+    (c) => String(c.connectionName || c.name || "").toLowerCase() === trimmed.toLowerCase(),
+  );
+  if (ci.length === 1) return { id: ci[0].id || ci[0].connectionId };
+  if (ci.length > 1) return { ambiguous: ci };
+  return null;
 }
 
 /**
@@ -59,17 +83,17 @@ async function resolveConnectionId(session, input) {
   const trimmed = raw.trim();
   if (UUID_RE.test(trimmed)) return trimmed;
 
-  const connections = await listConnections(session);
-  const exact = connections.filter((c) => (c.connectionName || c.name) === trimmed);
-  if (exact.length === 1) return exact[0].id || exact[0].connectionId;
-
-  const ciMatches = connections.filter(
-    (c) => String(c.connectionName || c.name || "").toLowerCase() === trimmed.toLowerCase(),
-  );
-  if (ciMatches.length === 1) return ciMatches[0].id || ciMatches[0].connectionId;
-
-  if (ciMatches.length > 1) {
-    const names = ciMatches.map((c) => `${c.connectionName} (${c.id})`).join(", ");
+  // Try the (possibly cached) list first; on a miss, refetch live once before
+  // failing — so a connection added since the cache was written still resolves.
+  let connections = await listConnections(session);
+  let m = matchConnection(connections, trimmed);
+  if (!m) {
+    connections = await listConnections(session, { refresh: true });
+    m = matchConnection(connections, trimmed);
+  }
+  if (m && m.id) return m.id;
+  if (m && m.ambiguous) {
+    const names = m.ambiguous.map((c) => `${c.connectionName} (${c.id})`).join(", ");
     throw new Error(
       `Multiple connections match "${trimmed}" by case-insensitive name: ${names}. Pass the exact name or the id.`,
     );

package/src/commands/agent.js

@@ -15,6 +15,8 @@ const readline = require("node:readline");
 const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
 const { resolveConnectionId } = require("./_connections");
+const { renderIntro, getVersionLine, promptLabel } = require("./_agent_intro");
+const { loadIntroData } = require("./_agent_status");
 
 // The brokered turn can run a full multi-tool agent loop server-side; allow well
 // past the backend's own per-turn ceiling so we don't abandon a valid answer.
@@ -29,6 +31,31 @@ async function runTurn(session, connectionId, message, conversationId) {
   });
 }
 
+// A server-side turn can run a multi-tool agent loop for a minute or more with
+// no streamed output, so show a live spinner + elapsed timer instead of a
+// static "…thinking" that reads as frozen. No-op (returns the promise) when not
+// a TTY, so piped/one-shot output stays clean.
+function awaitWithSpinner(stdout, promise) {
+  if (!stdout.isTTY) return promise;
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  const start = Date.now();
+  let i = 0;
+  const tick = () => {
+    const s = Math.floor((Date.now() - start) / 1000);
+    stdout.write(`\r\x1b[2m${frames[i++ % frames.length]} thinking… ${s}s\x1b[0m\x1b[K`);
+  };
+  tick();
+  const timer = setInterval(tick, 120);
+  const clear = () => {
+    clearInterval(timer);
+    stdout.write("\r\x1b[K");
+  };
+  return promise.then(
+    (v) => { clear(); return v; },
+    (e) => { clear(); throw e; }
+  );
+}
+
 function renderReply(stdout, resp) {
   if (resp && resp.ok && resp.answer && String(resp.answer).trim()) {
     stdout.write(`\n${String(resp.answer).trim()}\n`);
@@ -63,7 +90,7 @@ async function run(opts, io = {}) {
   // One-shot: a question on the command line.
   if (message) {
     try {
-      const resp = await runTurn(session, connectionId, message, null);
+      const resp = await awaitWithSpinner(stdout, runTurn(session, connectionId, message, null));
       renderReply(stdout, resp);
       return resp && resp.ok ? 0 : 1;
     } catch (e) {
@@ -78,12 +105,35 @@ async function run(opts, io = {}) {
     return 2;
   }
 
-  stdout.write("DeepSQL Agent — connected to your server agent. Type a question; `exit` or Ctrl-C to quit.\n");
+  // Branded one-time intro (compact). Suppress with DEEPSQL_NO_BANNER=1; colors
+  // honor --no-color / NO_COLOR (this branch is already TTY-only).
+  const useColor = !opts.noColor && !process.env.NO_COLOR;
+  if (process.env.DEEPSQL_NO_BANNER) {
+    stdout.write("DeepSQL Agent — connected to your server agent. Type a question; `exit` or Ctrl-C to quit.\n");
+  } else {
+    // Only surface a connection when one was explicitly named; a default/absent
+    // connection shows nothing (the agent asks if a question needs one).
+    const connectionLabel = opts.connection || null;
+    // Version check + connections/suggestions run in parallel (both best-effort,
+    // tight timeouts) so startup waits on the slower one, not the sum.
+    const [versionLine, introData] = await Promise.all([
+      getVersionLine(useColor),
+      loadIntroData(session),
+    ]);
+    renderIntro(stdout, {
+      useColor,
+      connectionLabel,
+      versionLine,
+      connections: introData.connections,
+      suggestions: introData.suggestions,
+      recommendationCount: introData.recommendationCount,
+    });
+  }
   // conversationId stays null on the first turn so the server resumes your most
   // recent conversation for this connection (shared with the web Agent tab);
   // subsequent turns reuse the id it returns.
   let conversationId = null;
-  const rl = readline.createInterface({ input: process.stdin, output: stdout, prompt: "\nyou › " });
+  const rl = readline.createInterface({ input: process.stdin, output: stdout, prompt: promptLabel(useColor) });
   rl.prompt();
 
   return await new Promise((resolve) => {
@@ -98,9 +148,8 @@ async function run(opts, io = {}) {
         return;
       }
       rl.pause();
-      stdout.write("…thinking\n");
       try {
-        const resp = await runTurn(session, connectionId, text, conversationId);
+        const resp = await awaitWithSpinner(stdout, runTurn(session, connectionId, text, conversationId));
         if (resp && resp.conversationId) conversationId = resp.conversationId;
         renderReply(stdout, resp);
       } catch (e) {

package/src/commands/brain.js

@@ -0,0 +1,144 @@
+"use strict";
+
+// `deepsql brain` — review what DeepSQL has learned about a connection and teach
+// it more. The "remember things as people use it" admin loop, on the CLI:
+//   recommendations  AI-proposed things to document/investigate (the inbox)
+//   notes            knowledge already saved to the brain (filterable)
+//   remember         save a fact to the brain (admin: needs manage-content)
+//
+// Backed by existing endpoints — no new backend:
+//   GET  /brain/notes/suggestions/{connectionId}?limit=N   → { suggestions, totalCount }
+//   GET  /brain/notes/{connectionId}[?tableName=&columnName=]
+//   POST /brain/notes   { connectionId, scopeType, tableName, columnName, noteText }
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+// Canonical subcommands (the drift guard compares these keys to the help rows).
+const SUBCOMMANDS = {
+  recommendations: cmdRecommendations,
+  notes: cmdNotes,
+  remember: cmdRemember,
+};
+// Convenience aliases resolved before dispatch (kept out of SUBCOMMANDS so the
+// help-drift test stays clean).
+const ALIASES = { recs: "recommendations", save: "remember" };
+
+async function run(opts, io = {}) {
+  const raw = opts.positional[0];
+  if (!raw) throw new Error("Usage: deepsql brain <recommendations|notes|remember> [options]");
+  const sub = ALIASES[raw] || raw;
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) throw new Error(`Unknown brain subcommand: ${raw}.`);
+  return wrap(handler)({ ...opts, positional: opts.positional.slice(1) }, io);
+}
+
+function wrap(handler) {
+  return async (opts, io) => {
+    try {
+      return await handler(opts, io);
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 403) {
+        throw new Error("Access denied — this brain operation requires manage-content permission on the connection.");
+      }
+      throw err;
+    }
+  };
+}
+
+// ─── recommendations ─────────────────────────────────────────────────────────
+async function cmdRecommendations(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const limit = parseInt(opts.limit, 10) || 10;
+  const res = await request(
+    session.baseUrl,
+    `/brain/notes/suggestions/${encodeURIComponent(connectionId)}?limit=${limit}`,
+    { token: session.token }
+  );
+  const suggestions = (res && res.suggestions) || [];
+  if (opts.json) {
+    stdout.write(JSON.stringify(suggestions, null, 2) + "\n");
+    return 0;
+  }
+  if (!suggestions.length) {
+    stdout.write("No recommendations — the brain has nothing pending to review for this connection.\n");
+    return 0;
+  }
+  stdout.write(`\nBrain recommendations (${res.totalCount ?? suggestions.length}):\n\n`);
+  for (const s of suggestions) {
+    const target = s.columnName ? `${s.tableName}.${s.columnName}` : s.tableName;
+    stdout.write(`  ${String(s.priority || "").padEnd(3)} ${target}\n`);
+    if (s.reason) stdout.write(`      ${s.reason}\n`);
+    if (Array.isArray(s.indicators) && s.indicators.length) {
+      stdout.write(`      ${s.indicators.join(" · ")}\n`);
+    }
+    if (s.suggestedPrompt) stdout.write(`      explore: deepsql agent "${s.suggestedPrompt}"\n`);
+    stdout.write("\n");
+  }
+  stdout.write('Save a fact with:  deepsql brain remember "<note>" --table <t> [--column <c>]\n');
+  return 0;
+}
+
+// ─── notes ───────────────────────────────────────────────────────────────────
+async function cmdNotes(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const qs = [];
+  if (opts.table) qs.push(`tableName=${encodeURIComponent(opts.table)}`);
+  if (opts.column) qs.push(`columnName=${encodeURIComponent(opts.column)}`);
+  const notes = await request(
+    session.baseUrl,
+    `/brain/notes/${encodeURIComponent(connectionId)}${qs.length ? `?${qs.join("&")}` : ""}`,
+    { token: session.token }
+  );
+  const list = Array.isArray(notes) ? notes : [];
+  if (opts.json) {
+    stdout.write(JSON.stringify(list, null, 2) + "\n");
+    return 0;
+  }
+  if (!list.length) {
+    stdout.write("No saved notes for that scope.\n");
+    return 0;
+  }
+  const limit = parseInt(opts.limit, 10) || 20;
+  stdout.write(`\nBrain notes (${list.length}${list.length > limit ? `, showing ${limit}` : ""}):\n\n`);
+  for (const n of list.slice(0, limit)) {
+    const target = n.columnName ? `${n.tableName}.${n.columnName}` : n.tableName;
+    const tags = `${n.source ? `  [${n.source}]` : ""}${n.stale ? "  (stale)" : ""}`;
+    stdout.write(`  ${target}${tags}\n      ${n.noteText}\n\n`);
+  }
+  if (list.length > limit) {
+    stdout.write(`… +${list.length - limit} more — narrow with --table <t> [--column <c>], or --limit N\n`);
+  }
+  return 0;
+}
+
+// ─── remember ────────────────────────────────────────────────────────────────
+async function cmdRemember(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const noteText = (opts.positional || []).join(" ").trim();
+  if (!noteText) {
+    stderr.write('Usage: deepsql brain remember "<note text>" --table <t> [--column <c>]\n');
+    return 2;
+  }
+  if (!opts.table) {
+    stderr.write("A --table is required (add --column for a column-scoped note).\n");
+    return 2;
+  }
+  const body = {
+    connectionId,
+    scopeType: opts.column ? "COLUMN" : "TABLE",
+    tableName: opts.table,
+    columnName: opts.column || null,
+    noteText,
+  };
+  await request(session.baseUrl, "/brain/notes", { method: "POST", token: session.token, json: body });
+  const target = body.columnName ? `${body.tableName}.${body.columnName}` : body.tableName;
+  stdout.write(`✓ Saved to brain — ${target}: ${noteText}\n`);
+  return 0;
+}
+
+module.exports = { run, SUBCOMMANDS };

package/src/commands/connections.js

@@ -27,9 +27,10 @@ const fs = require("node:fs");
 const { ApiError, request } = require("../api/client");
 const store = require("../auth/store");
 const { resolveSession } = require("./_session");
-const { resolveConnectionId } = require("./_connections");
+const { resolveConnectionId, listConnections } = require("./_connections");
 const { resolveSecrets, maskSecrets, SECRET_FIELDS } = require("../connections/secrets");
 const { SCHEMA, validate } = require("../connections/schema");
+const cache = require("../connections/cache");
 const ui = require("../ui/prompts");
 const { promptPassword } = require("../auth/prompt");
 
@@ -59,7 +60,8 @@ async function run(opts, io = {}) {
 
 async function runList(opts, { stdout = process.stdout } = {}) {
   const session = resolveSession(opts);
-  const data = await request(session.baseUrl, "/connections", { token: session.token });
+  // Cached for speed; --refresh (or --no-cache) forces a live fetch.
+  const data = await listConnections(session, { refresh: !!(opts.refresh || opts.noCache) });
   if (opts.json) {
     stdout.write(`${JSON.stringify(data, null, 2)}\n`);
     return;
@@ -228,6 +230,7 @@ async function runAdd(opts, { stdout = process.stdout, stderr = process.stderr }
     throw new Error(saved.message || "Connection save failed.");
   }
   const id = saved?.connectionId || saved?.id;
+  cache.invalidate(session.baseUrl);
   if (saved?.privileges) printPrivilegeReport(stderr, saved);
   stdout.write(`Saved "${cfg.connectionName}" (id ${id || "?"}).\n`);
 
@@ -277,6 +280,7 @@ async function runUpdate(opts, { stdout = process.stdout, stderr = process.stder
   if (saved?.success === false) {
     throw new Error(saved.message || "Connection update failed.");
   }
+  cache.invalidate(session.baseUrl);
   if (saved?.privileges) printPrivilegeReport(stderr, saved);
   stdout.write(`Updated "${target}".\n`);
 }
@@ -303,6 +307,7 @@ async function runRemove(opts, { stdout = process.stdout, stderr = process.stder
     method: "DELETE",
     token: session.token,
   });
+  cache.invalidate(session.baseUrl);
   if (session.defaultConnection === target) {
     store.setDefaultConnection(session.baseUrl, null);
     stderr.write(`[deepsql] Cleared the active-connection pin (was "${target}").\n`);
@@ -391,6 +396,7 @@ async function runInit(opts, { stdout = process.stdout, stderr = process.stderr
     token: session.token,
     json: { force: !!opts.force },
   });
+  cache.invalidate(session.baseUrl);
   stdout.write(`Brain reinit triggered for "${target}".\n`);
   if (opts.wait) await pollInitStatus(session, connectionId, stderr);
 }

package/src/connections/cache.js

@@ -0,0 +1,52 @@
+"use strict";
+
+// Small on-disk cache for the connections list, keyed per DeepSQL instance.
+// Each `deepsql` invocation is a fresh process, so without this every command
+// re-fetches (and re-decrypts, server-side) the whole list just to resolve
+// `--connection`. The list changes rarely, so a short TTL makes the common path
+// (resolve a connection name → id) effectively free while staying fresh.
+//
+// Holds only the same non-secret connection summary the user already sees
+// (name/host/port/etc.; secrets are masked server-side). File is 0600.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { configDir } = require("../auth/store");
+
+const DEFAULT_TTL_MS = 60000; // 60s
+
+function cacheFile(baseUrl) {
+  const key = crypto.createHash("sha1").update(String(baseUrl || "")).digest("hex").slice(0, 16);
+  return path.join(configDir(), "cache", `connections-${key}.json`);
+}
+
+function read(baseUrl, ttlMs = DEFAULT_TTL_MS) {
+  try {
+    const obj = JSON.parse(fs.readFileSync(cacheFile(baseUrl), "utf8"));
+    if (!obj || !Array.isArray(obj.data)) return null;
+    if (Date.now() - (obj.ts || 0) > ttlMs) return null;
+    return obj.data;
+  } catch {
+    return null;
+  }
+}
+
+function write(baseUrl, data) {
+  if (!Array.isArray(data)) return;
+  try {
+    const dir = path.join(configDir(), "cache");
+    fs.mkdirSync(dir, { recursive: true });
+    const file = cacheFile(baseUrl);
+    fs.writeFileSync(file, JSON.stringify({ ts: Date.now(), data }), { mode: 0o600 });
+    try { fs.chmodSync(file, 0o600); } catch { /* best-effort */ }
+  } catch {
+    /* cache is best-effort — never fail a command over it */
+  }
+}
+
+function invalidate(baseUrl) {
+  try { fs.rmSync(cacheFile(baseUrl), { force: true }); } catch { /* ignore */ }
+}
+
+module.exports = { read, write, invalidate, DEFAULT_TTL_MS };

package/agent-profile/SOUL.md

@@ -1,28 +0,0 @@
-You are **DeepSQL DBA**, an AI database performance assistant. You answer questions about the user's databases and help them build features against an existing schema. You operate exclusively through the **DeepSQL MCP tools** (server `deepsql`) — they are your source of truth, not your training data and not the user's codebase.
-
-Be direct, concrete, and grounded. Cite the tables and rules you used. Admit uncertainty instead of guessing. Prefer one correct, grounded answer over a verbose survey.
-
-## Non-negotiable rules
-
-1. **Connections are UUIDs.** Everything except `get_current_user` needs a `connectionId`. Get it from `list_connections` once and reuse it. Pass the UUID, never the human name.
-
-2. **Ground before you generate.** ALWAYS call `get_brain_context(connectionId, question)` before writing any non-trivial SQL or proposing schema. The brain knows business rules, anti-patterns, and inferred foreign keys that the raw schema does not. Skipping it produces "technically valid, semantically wrong" SQL — the worst kind.
-
-3. **Schema comes from `get_schema`, not `information_schema`.** It is cached, fast, and authoritative. Never trust column names inferred from the codebase — they drift.
-
-4. **Table-qualify every column** in generated SQL (`table.column`). Honor business rules and anti-patterns silently — if a rule says `always_filter_cancelled`, your query includes the filter without asking permission to follow the user's own rule.
-
-5. **Read-only by default.** Developers cannot mutate; admins can with a **two-step confirmation**. If `execute_sql` returns `requiresConfirmation: true`, surface the warnings verbatim, get explicit human approval, then re-call with `confirmMutation: true`. NEVER auto-confirm — that defeats the safety gate. Never try to work around a 403/`EDITOR_MUTATION_FORBIDDEN`; surface it.
-
-6. **One execution tool, one analysis tool.** Use `execute_sql` to run SQL; use `analyze_query_plan` for plans. Don't hand-wrap `EXPLAIN` inside `execute_sql`, and don't run a query just to see its plan. `EXPLAIN`/`EXPLAIN ANALYZE` are read-only SQL when you do need them — but `analyze_query_plan` gives the AI-enriched summary.
-
-7. **Row limits are real.** `execute_sql` defaults to 100 rows, max 1000. If you need a total, `SELECT COUNT(*)` — don't infer it from a truncated result.
-
-8. **Consult before you commit schema.** When the user says "add a table / track X / write a migration," STOP and run the brain consult (`get_brain_context` → `get_schema` → `list_business_rules` → `get_relationships` → `get_anti_patterns`). There is almost always an existing table or column to extend instead of duplicate. Narrate what you found before proposing DDL.
-
-## Skills
-
-Detailed procedures live in your skills. Load the matching one before acting:
-`bi-query` (answer a data question), `schema-exploration` (map/describe a database), `index-advisor` (what indexes to add/drop), `slow-query-optimize` (why is a query slow / rewrite it), `workload-analysis` (what's driving load, regressions, growth).
-
-Every tool call is logged with your identity and the statement you ran. Don't do anything you wouldn't defend in an audit.

package/agent-profile/distribution.yaml

@@ -1,41 +0,0 @@
-# Hermes profile distribution — DeepSQL DBA agent.
-# Enterprises install this per user:  hermes profile install <git-url|dir> --name <profile>
-# `hermes profile update <profile>` refreshes SOUL.md + skills/ WITHOUT touching
-# the user's memory, sessions, .env, or config.yaml (their identity + history).
-name: deepsql-agent
-version: 0.1.0
-description: "DeepSQL DBA agent — grounded, read-only database assistant over the DeepSQL MCP tools (BI queries, schema exploration, index advice, slow-query optimization, workload analysis)."
-hermes_requires: ">=0.12.0"
-author: "DeepSQL"
-license: "proprietary"
-
-# Per-user runtime values. Secrets + identity live in each profile's .env
-# (user-owned, preserved on update); provision-profile.sh writes them.
-env_requires:
-  - name: AZURE_OPENAI_KEY
-    description: "Azure OpenAI API key for the chat model"
-    required: true
-  - name: AZURE_OPENAI_ENDPOINT
-    description: "Azure OpenAI resource endpoint (…cognitiveservices/…openai.azure.com)"
-    required: false
-    default: "https://dba-agent-3-resource.openai.azure.com/"
-  - name: DEEPSQL_API_BASE_URL
-    description: "DeepSQL backend API base URL"
-    required: false
-    default: "http://localhost:8080/api/"
-  - name: DEEPSQL_MCP_SERVER
-    description: "Absolute path to mcp/deepsql-phase1-server.js"
-    required: true
-  - name: DEEPSQL_MCP_USER_ID
-    description: "DeepSQL user id this profile acts as — backend audit + RBAC attribution"
-    required: true
-  - name: DEEPSQL_AUTH_TOKEN
-    description: "DeepSQL bearer token for this user — server-enforced RBAC/connection-scope"
-    required: false
-
-# The agent persona and skills are the distribution's product surface.
-# Runtime config (model, mcp_servers, approvals, toolset scoping) is applied
-# per-user by provision-profile.sh into the profile's preserved config.yaml.
-distribution_owned:
-  - SOUL.md
-  - skills/

package/agent-profile/skills/bi-query/SKILL.md

@@ -1,40 +0,0 @@
----
-name: bi-query
-description: Answer a question about the data — write and run grounded, read-only SQL against a DeepSQL connection and report the result.
-version: 1.0.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [sql, bi, analytics, query, count, report, deepsql, database]
-    related_skills: [schema-exploration, slow-query-optimize]
----
-
-# BI Query
-
-Use when the user asks a question whose answer is **in the data** ("how many bookings last week?", "revenue by region", "top 10 customers"). The output is a number/table, not schema advice.
-
-## Procedure
-
-1. **Resolve the connection.** If you don't already have the UUID, call `list_connections` and match the user's named database. Pass the UUID to every later call.
-
-2. **Ground.** Call `get_brain_context(connectionId, "<the user's question>")`. Read what it surfaces — relevant tables, columns, inferred FKs, business rules, anti-patterns. Do not skip this even if you think you know the table.
-
-3. **Confirm exact columns** with `get_schema(connectionId)` only if the brain context didn't give you exact column names/types you need. Don't query `information_schema`.
-
-4. **Write ONE statement.** Table-qualify every column. Apply every relevant business rule (e.g. cancelled/soft-delete filters) without being asked. Use a CTE (`WITH …`) instead of multiple statements — `execute_sql` rejects multi-statement input.
-
-5. **Sanity-check the plan** with `analyze_query_plan(connectionId, sql)` (no `useAnalyze`) when the query has non-trivial joins or runs against an unfamiliar schema. It's cheap and catches bad joins before you show the user a wrong number.
-
-6. **Run it** with `execute_sql(connectionId, sql, limit=…)`. Remember: default 100 rows, max 1000. For a total, `SELECT COUNT(*)` rather than counting a truncated result set.
-
-7. **Report concisely:** the answer, the table(s) you used, and any business rule you applied ("excluded CANCELLED per `always_filter_cancelled`").
-
-## Guardrails
-
-- Read-only only. If the question implies a write, switch to the mutation flow (surface warnings, get a human OK, `confirmMutation: true`) and only if the user is an admin.
-- If `get_brain_context` returns nothing useful, do **not** guess a table from memory. First try lightweight discovery against the live DB: `SHOW TABLES LIKE '%<keyword>%'`, then `DESCRIBE <candidate_table>`, then a narrowly-scoped verification query such as `SELECT COUNT(*) ...`. Ask the user only if multiple candidates remain plausible after those probes.
-- If schema/object metadata is too large or `get_database_objects` times out, prefer targeted read-only probes over broad catalog dumps.
-- When the user asks for a chart or ranking and brain context is thin, first identify the fact table and dimension join path with small probes, then run the final aggregation. Example pattern used successfully in `idb_database`: `USER_BOOKINGS.hotel_id -> HOTEL.id` for city-level booking rollups, and `PRICE_BREAKDOWN.booking_id -> USER_BOOKINGS.id -> HOTEL.id` for hotel-level room-price averages.
-- If the user says "active hotels" or similar status language, check brain context for status-source rules before using a status column. In `idb_database`, `HOTEL_PRICING.property_status` is the correct source and `HOTEL.onboarding_status` is specifically the wrong one.
-- For chart requests in chat-only environments, still run the real aggregation query first. If you cannot render a binary image with available tools, provide a clearly labeled text/Markdown chart from the real results rather than fabricating an image.
-- Never present a truncated (limit-capped) result as a total.