@deepsql/mcp 0.22.0 → 0.26.0

package/CLAUDE.md

@@ -33,8 +33,10 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes **41 tools** as of 0.19.0 — the original 16 +
-0.18.x's 5 slow-query tools + 0.19.0's 20 CLI-parity additions. Most
+The MCP server exposes **44 tools** as of 0.26.0 — the original 16 +
+0.18.x's 5 slow-query tools + 0.19.0's 20 CLI-parity additions + 0.26.0's
+3 brain-notes tools (`list_brain_recommendations`, `save_brain_note`,
+`list_brain_notes`). Most
 take a `connectionId` (UUID returned by `list_connections`); a few
 take server-resolved row ids (`apply_index_recommendation` →
 `recommendationId`, `dismiss_index_recommendation` →
@@ -65,6 +67,9 @@ in this version; ask before mid-session admin work.
 | `list_business_rules` | Active business rules and SQL guardrails. Honor these — they encode domain semantics. |
 | `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. |
+| `list_brain_recommendations` | The brain's AI-proposed notes to review for a connection (priority, reason, indicators, suggested prompt). The company-context review queue. |
+| `save_brain_note` | **Accept/save a fact into the shared brain** — grounds every future answer for the connection. TABLE- or COLUMN-scoped. Admin (manage-content), audited. Personal preferences belong in a DeepSQL skill, not here. |
+| `list_brain_notes` | Knowledge already saved to the brain (filter by table/column; can be thousands). |
 | `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. |

package/README.md

@@ -88,7 +88,7 @@ Restart the editor for the entry to load.
 
 ## What the MCP server exposes
 
-**41 tools** as of 0.19.0. Read-only at the schema/retrieval/diagnostics
+**44 tools** as of 0.26.0. Read-only at the schema/retrieval/diagnostics
 layer; policy-gated at the SQL layer (only `execute_sql`,
 `analyze_query_plan` with `useAnalyze=true`, and
 `apply_index_recommendation` can write — the rest are reads or low-stakes
@@ -112,7 +112,7 @@ per-user admin ops (`users`/`access`/`permissions`).
 | `test_connection` | Run the privilege report (+ SSH check); reuses saved creds — no plaintext crosses the wire |
 | `reinit_connection_brain` | Trigger a fresh schema scan + brain re-embed |
 
-### Schema + retrieval brain (5)
+### Schema + retrieval brain (8)
 
 | Tool | Purpose |
 |---|---|
@@ -121,6 +121,9 @@ per-user admin ops (`users`/`access`/`permissions`).
 | `get_brain_context` | Retrieval brain: tables/columns/FKs/training docs/rules for a question |
 | `list_business_rules` | Active business rules and SQL guardrails for a connection |
 | `get_relationships` | Inferred + validated foreign keys with confidence scores |
+| `list_brain_recommendations` | The brain's AI-proposed notes to review (company-context queue) |
+| `save_brain_note` | Accept/save a fact into the shared brain (admin; grounds future answers) |
+| `list_brain_notes` | Knowledge already saved to the brain (filterable) |
 
 ### Anti-patterns + daily digest (4)
 

package/deepsql-phase1-lib.js

@@ -143,6 +143,51 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "list_brain_recommendations",
+    description:
+      "List the brain's AI-proposed recommendations for a connection — high-value tables/columns DeepSQL suggests documenting, each with a priority (P0/P1…), the reason, supporting indicators, and a suggested prompt to explore. This is the company-context review queue: an admin reviews these and accepts the good ones with save_brain_note. Returns { suggestions, totalCount } (totalCount reflects the requested limit, not an absolute total).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        limit: { type: "integer", minimum: 1, maximum: 100, description: "Max recommendations to return (default 10)." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "save_brain_note",
+    description:
+      "Accept/save a fact into the connection's BRAIN — shared, company-level context that grounds EVERY future answer for this connection (not a per-user preference). Use this to accept a recommendation from list_brain_recommendations, or to record any durable fact about a table/column. Scope is TABLE (tableName only) or COLUMN (tableName + columnName). Requires manage-content permission on the connection (admin) — the backend enforces and audits it. NOTE: an individual's personal preference (how *they* like answers formatted, a private shortcut) belongs in a DeepSQL skill on their own profile, NOT here — this writes to the shared brain everyone sees.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: { type: "string", description: "Table the note is about (required)." },
+        columnName: { type: "string", description: "Column the note is about; omit for a table-scoped note." },
+        noteText: { type: "string", description: "The fact/guidance to remember." },
+      },
+      required: ["connectionId", "tableName", "noteText"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_brain_notes",
+    description:
+      "List knowledge already saved to the connection's brain (the notes that ground answers). Optionally filter by tableName and/or columnName — a trained connection can hold thousands of notes, so filtering is recommended. Use this to check whether a fact is already remembered before saving a new one with save_brain_note.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: { type: "string", description: "Filter to one table." },
+        columnName: { type: "string", description: "Filter to one column (use with tableName)." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "apply_index_recommendation",
     description:
@@ -1149,6 +1194,25 @@ function summarizeRelationships(payload) {
   return `${list.length} relationship(s) (${high} high-confidence).`;
 }
 
+function summarizeBrainRecommendations(payload) {
+  const list = (payload && payload.suggestions) || [];
+  if (!list.length) return "No brain recommendations pending review for this connection.";
+  const top = list
+    .slice(0, 5)
+    .map((s) => `${s.priority || ""} ${s.columnName ? `${s.tableName}.${s.columnName}` : s.tableName}`.trim());
+  return `${payload.totalCount ?? list.length} recommendation(s) to review. Top: ${top.join("; ")}. Accept the good ones with save_brain_note.`;
+}
+
+function summarizeBrainNoteSaved(payload) {
+  const target = payload && (payload.columnName ? `${payload.tableName}.${payload.columnName}` : payload.tableName);
+  return `Saved to brain${target ? ` — ${target}` : ""}. It now grounds future answers for this connection (shared, company-level).`;
+}
+
+function summarizeBrainNotes(payload) {
+  const list = Array.isArray(payload) ? payload : (payload && payload.notes) || [];
+  return `${list.length} brain note(s) for the requested scope.`;
+}
+
 function summarizeAntiPatterns(payload, kind) {
   if (kind === "table") {
     const tables = payload && typeof payload === "object" ? Object.keys(payload).length : 0;
@@ -1548,6 +1612,15 @@ function buildToolResult(name, payload, extra = {}) {
     case "get_growth_anomalies":
       summary = summarizeGrowthAnomalies(payload);
       break;
+    case "list_brain_recommendations":
+      summary = summarizeBrainRecommendations(payload);
+      break;
+    case "save_brain_note":
+      summary = summarizeBrainNoteSaved(payload);
+      break;
+    case "list_brain_notes":
+      summary = summarizeBrainNotes(payload);
+      break;
     case "get_index_recommendations":
       summary = summarizeIndexRecommendations(payload);
       break;
@@ -1596,10 +1669,28 @@ function buildToolError(message, extra = {}) {
   };
 }
 
+// Short-TTL in-memory cache for the connections list. The MCP server is a
+// long-lived process and `list_connections` is the "call this first" tool, so an
+// agent hits it repeatedly in a session — caching makes those calls instant. The
+// list changes rarely; a 30s TTL keeps it fresh enough.
+const CONNECTIONS_CACHE_TTL_MS = 30000;
+let _connectionsCache = null; // { key, ts, payload }
+
+async function fetchConnectionsCached(config) {
+  const key = `${(config && config.baseUrl) || ""}|${(config && config.authToken) || ""}`;
+  if (_connectionsCache && _connectionsCache.key === key
+      && Date.now() - _connectionsCache.ts < CONNECTIONS_CACHE_TTL_MS) {
+    return _connectionsCache.payload;
+  }
+  const payload = await callDeepSqlApi(config, "/connections");
+  _connectionsCache = { key, ts: Date.now(), payload };
+  return payload;
+}
+
 async function handleToolCall(config, name, args = {}) {
   switch (name) {
     case "list_connections": {
-      const payload = await callDeepSqlApi(config, "/connections");
+      const payload = await fetchConnectionsCached(config);
       return buildToolResult(name, payload);
     }
 
@@ -1684,6 +1775,52 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload, { kind });
     }
 
+    case "list_brain_recommendations": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const limit = clampInteger(args.limit, 1, 100, 10);
+      const payload = await callDeepSqlApi(
+        config,
+        `/brain/notes/suggestions/${encodeURIComponent(connectionId)}?limit=${limit}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "save_brain_note": {
+      const connectionId = String(args.connectionId || "").trim();
+      const tableName = String(args.tableName || "").trim();
+      const noteText = String(args.noteText || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!tableName) return buildToolError("tableName is required.");
+      if (!noteText) return buildToolError("noteText is required.");
+      const columnName = args.columnName ? String(args.columnName).trim() : null;
+      // Backend enforces manage-content permission (admin) + audits the write.
+      const payload = await callDeepSqlApi(config, "/brain/notes", {
+        method: "POST",
+        json: {
+          connectionId,
+          scopeType: columnName ? "COLUMN" : "TABLE",
+          tableName,
+          columnName,
+          noteText,
+        },
+      });
+      return buildToolResult(name, payload);
+    }
+
+    case "list_brain_notes": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const qs = [];
+      if (args.tableName) qs.push(`tableName=${encodeURIComponent(String(args.tableName))}`);
+      if (args.columnName) qs.push(`columnName=${encodeURIComponent(String(args.columnName))}`);
+      const payload = await callDeepSqlApi(
+        config,
+        `/brain/notes/${encodeURIComponent(connectionId)}${qs.length ? `?${qs.join("&")}` : ""}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
     case "get_index_recommendations": {
       const connectionId = String(args.connectionId || "").trim();
       if (!connectionId) return buildToolError("connectionId is required.");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.22.0",
-  "description": "DeepSQL CLI, DBA Agent TUI, and stdio MCP server for self-hosted deployments",
+  "version": "0.26.0",
+  "description": "DeepSQL CLI, DBA Agent (thin client), and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
     "deepsql-mcp": "deepsql-phase1-server.js"
@@ -15,7 +15,6 @@
     "skills",
     "src",
     "scripts",
-    "agent-profile",
     "deepsql-phase1-server.js",
     "deepsql-phase1-lib.js",
     "claude_desktop_config.customer.example.json",

package/skills/SKILL_BODY.md

@@ -2,7 +2,7 @@
 
 You have two DeepSQL surfaces available:
 
-1. **MCP tools** — JSON-RPC tools loaded into your session (41 of them
+1. **MCP tools** — JSON-RPC tools loaded into your session (44 of them
    as of 0.19.0). The MCP surface mirrors the CLI for almost every
    read/diagnostic operation, plus the two execute tools and the index-
    apply tool.
@@ -91,6 +91,9 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `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. |
+| `list_brain_recommendations(connectionId, limit?)` | The brain's AI-proposed things to document (the review queue). Admin accepts good ones with `save_brain_note`. |
+| `save_brain_note(connectionId, tableName, noteText, columnName?)` | **Accept/save a fact to the SHARED company brain** — grounds every future answer for this connection. Admin (manage-content). NOT for personal prefs — those go in a DeepSQL skill. |
+| `list_brain_notes(connectionId, tableName?, columnName?)` | Knowledge already in the brain; filter before saving a duplicate. |
 | `analyze_slow_queries(connectionId, thresholdMs?, limit?)` | Snapshot of slow queries from live stats. |
 | `get_slow_query_timeline(connectionId, fingerprint)` | Day-by-day timeline for one fingerprint: call count, mean/max time, regression factor per day. Answers "is this query getting slower". |
 | `get_query_regressions(connectionId, minFactor?)` | Slow queries that got slower on the latest daily analysis run, ranked by slowdown factor. |
@@ -138,7 +141,7 @@ called by claude-code via deepsql CLI").
 deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 ```
 
-### Command catalog (20 top-level commands)
+### Command catalog (21 top-level commands)
 
 | Command | What it does | MCP equivalent? |
 |---|---|---|
@@ -154,6 +157,7 @@ deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 | `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 brain recommendations\|notes\|remember` | Review what DeepSQL has learned (AI-proposed notes), list saved notes, and `remember "<note>" --table <t> [--column <c>]` to teach it (admin) | none — CLI/web surface for the brain-notes loop |
 | `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` |

package/src/cli.js

@@ -28,6 +28,7 @@ const COMMANDS = {
   // Brain tools — give a coding agent the same retrieval context the chat
   // pipeline uses, then let the agent generate SQL/answers itself.
   "brain-context": () => require("./commands/brain-context"),
+  brain: () => require("./commands/brain"),
   "business-rules": () => require("./commands/business-rules"),
   relationships: () => require("./commands/relationships"),
   "anti-patterns": () => require("./commands/anti-patterns"),
@@ -60,6 +61,7 @@ const COMMAND_LIST = [
   ["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"],
+  ["brain",          true,  "Review brain recommendations and remember facts (admin)"],
   ["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"],
@@ -161,7 +163,7 @@ const COMMAND_HELP = {
     description: "Manage database connections — list, pin, full CRUD.",
     usage: "deepsql connections <subcommand> [options]",
     subcommands: [
-      ["list [--json]",                              "List database connections (active default marked with *)"],
+      ["list [--json] [--refresh]",                  "List database connections (cached ~60s; --refresh forces live)"],
       ["use <name>",                                 "Pin <name> as the active default for this profile"],
       ["current",                                    "Print the active default (exit 1 if none)"],
       ["unset",                                      "Clear the active default for this profile"],
@@ -174,6 +176,7 @@ const COMMAND_HELP = {
       ["init <name> [--force] [--wait]",             "Trigger brain re-initialization"],
     ],
     options: [
+      ["--refresh",                  "Bypass the connections cache and fetch live (list)"],
       ["--from-file <p>",            "Read connection JSON from file"],
       ["--from-stdin",               "Read connection JSON from stdin"],
       ["--upsert",                   "PUT instead of POST on add if name collision"],
@@ -261,6 +264,24 @@ const COMMAND_HELP = {
     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: {
+    description: "Review what DeepSQL has learned about a connection and teach it more (admin).",
+    usage: "deepsql brain <subcommand> [options]",
+    subcommands: [
+      ["recommendations [--connection <name>] [--limit <n>]",   "AI-proposed things to document/investigate (alias: recs)"],
+      ["notes [--connection <name>] [--table <t>] [--column <c>]", "Knowledge already saved to the brain (filterable)"],
+      ['remember "<note>" --table <t> [--column <c>]',          "Save a fact to the brain (alias: save)"],
+    ],
+    options: [
+      ["--connection <name>", "Connection to act on (default: active connection)"],
+      ["--table <t>",         "Scope notes/remember to a table"],
+      ["--column <c>",        "Scope to a column (with --table)"],
+      ["--limit <n>",         "Cap results"],
+      ["--json",              "Raw JSON output"],
+    ],
+    notes: "`recommendations` reads /brain/notes/suggestions; `remember` writes a brain note (requires manage-content permission on the connection). The same recommendations surface backs the web UI.",
+  },
+
   "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]',
@@ -581,6 +602,9 @@ function buildOpts(parsed) {
     label: f.label || null,
     // Connection / users / chat
     connection: f.connection || f.c || null,
+    // Brain notes scoping
+    table: f.table || null,
+    column: f.column || null,
     chat: f.chat || null,
     user: f.user || null,
     project: f.project || null,

package/src/cli.test.js

@@ -75,7 +75,7 @@ test("every command in the catalog has a COMMAND_HELP entry", () => {
   const expected = [
     "agent",
     "login","logout","whoami","config","mcp","connections","query","analyze","schema",
-    "digest","brain-context","business-rules","relationships","anti-patterns","indexes",
+    "digest","brain-context","brain","business-rules","relationships","anti-patterns","indexes",
     "users","access","permissions","slow-queries","setup",
   ];
   for (const name of expected) {
@@ -137,6 +137,7 @@ test("--no-color suppresses ANSI escapes in help output", async () => {
 // a `SUBCOMMANDS` object whose keys are the dispatchable subcommand names.
 const HELP_DRIFT_TARGETS = [
   { command: "slow-queries", modulePath: "./commands/slow-queries" },
+  { command: "brain", modulePath: "./commands/brain" },
 ];
 
 for (const { command, modulePath } of HELP_DRIFT_TARGETS) {

package/src/commands/_agent_intro.js

@@ -0,0 +1,227 @@
+"use strict";
+
+// Branded one-time intro for the interactive DeepSQL Agent REPL.
+//
+// Compact by design (the REPL is a scrolling buffer, not a full-screen TUI):
+// wordmark + tagline + a rotating sample prompt per category + how to drive it.
+//
+// Colors use 256-color codes (\x1b[38;5;Nm) — macOS Terminal.app does NOT
+// support 24-bit truecolor and garbles \x1b[38;2;r;g;bm into wrong colors, so
+// we stick to the 256 palette which renders correctly everywhere. Body text is
+// left at the terminal's default foreground so it's readable on light AND dark
+// backgrounds. Suppress the whole banner with DEEPSQL_NO_BANNER=1.
+
+const https = require("node:https");
+
+// Installed package version (this file ships inside the package).
+let PKG_VERSION = "";
+try {
+  PKG_VERSION = require("../../package.json").version || "";
+} catch {
+  /* ignore */
+}
+
+// Solid-block "DEEPSQL" wordmark.
+const LOGO = [
+  "████   ████   ████   ████    ████    ███    █     ",
+  "█   █  █      █      █   █   █       █   █   █     ",
+  "█   █  ███    ███    ████     ███    █   █   █     ",
+  "█   █  █      █      █            █  █  ██   █     ",
+  "████   ████   ████   █        ████    ███   █████ ",
+];
+
+// Welcoming purple palette (256-color cube). Light→deep down the wordmark; one
+// clean hue, no grey, so it reads as a single wordmark.
+const PURPLE_LIGHT = 141; // #af87ff
+const PURPLE = 99; //        #875fff
+const PURPLE_DEEP = 98; //   #875fd7
+const AMBER = 178; //        #d7af00 — "needs attention" marker, readable on light & dark
+const LOGO_ROWS = [PURPLE_LIGHT, PURPLE_LIGHT, PURPLE, PURPLE, PURPLE_DEEP];
+
+function c(n, s, on) {
+  return on ? `\x1b[38;5;${n}m${s}\x1b[0m` : s;
+}
+function dim(s, on) {
+  return on ? `\x1b[2m${s}\x1b[0m` : s;
+}
+
+// Several sample prompts per category; one is picked at random each launch.
+const PROMPTS = {
+  DBA: [
+    "why is the orders query slow?",
+    "what indexes should I add?",
+    "is this query using the right index?",
+    "what's my slowest query today?",
+  ],
+  BI: [
+    "revenue by city this month",
+    "how many bookings last week?",
+    "top 10 customers by spend",
+    "signups per day this month",
+  ],
+  Guardian: [
+    "is this migration safe?",
+    "who’s driving DB load?",
+    "any tables bloating?",
+    "what schema changed recently?",
+  ],
+};
+
+function pick(arr) {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+// Prompt label for the readline input line (purple, brand-forward).
+function promptLabel(useColor) {
+  return "\n" + c(PURPLE, "deepsql ›", useColor) + " ";
+}
+
+function renderIntro(
+  stdout,
+  {
+    useColor = true,
+    connectionLabel = null,
+    versionLine = null,
+    connections = [],
+    suggestions = [],
+    recommendationCount = 0,
+  } = {}
+) {
+  const out = [""];
+  LOGO.forEach((row, i) => out.push("  " + c(LOGO_ROWS[i], row, useColor)));
+  out.push("");
+  out.push("  " + dim("I am your DBA and Data agent. DeepSQL is the brain for your database", useColor));
+  out.push("");
+  out.push("  " + c(PURPLE, "Try these prompts", useColor));
+  for (const cat of ["DBA", "BI", "Guardian"]) {
+    // Label reads "<cat> prompt" (not a bare "DBA" that looks like a command);
+    // purple label, prompt text stays default-fg so it's always readable.
+    const label = `${cat} prompt`;
+    out.push("    " + c(PURPLE_LIGHT, label.padEnd(16), useColor) + `"${pick(PROMPTS[cat])}"`);
+  }
+
+  // Connections the token can see (frictionless onboarding: guide to add one if none).
+  out.push("");
+  if (connections.length === 0) {
+    out.push("  " + c(PURPLE, "No databases connected yet", useColor));
+    out.push("    " + dim("→ ", useColor) + "deepsql connections add");
+  } else {
+    out.push("  " + c(PURPLE, `Connections (${connections.length})`, useColor));
+    const width = Math.min(24, Math.max(...connections.map((x) => x.name.length)));
+    for (const conn of connections.slice(0, 8)) {
+      out.push("    " + conn.name.padEnd(width + 2) + dim(conn.dbType, useColor));
+    }
+    if (connections.length > 8) out.push("    " + dim(`… +${connections.length - 8} more`, useColor));
+  }
+
+  // Admin "needs attention" — config suggestions for connections the user manages.
+  if (suggestions.length) {
+    out.push("");
+    out.push("  " + c(AMBER, "Needs attention", useColor));
+    for (const s of suggestions.slice(0, 6)) {
+      out.push(
+        "    " + c(AMBER, "⚠ ", useColor) + s.conn + dim(" · ", useColor) + s.text
+      );
+      if (s.fix) out.push("        " + dim("→ ", useColor) + dim(s.fix, useColor));
+    }
+    if (suggestions.length > 6) out.push("    " + dim(`… +${suggestions.length - 6} more`, useColor));
+  }
+
+  // Brain learning loop: prompt admins to review what DeepSQL wants to remember.
+  if (recommendationCount > 0) {
+    out.push("");
+    out.push(
+      "  " +
+        c(PURPLE, `${recommendationCount} brain recommendation${recommendationCount === 1 ? "" : "s"} to review`, useColor) +
+        dim("  → deepsql brain recs", useColor)
+    );
+  }
+
+  out.push("");
+  if (connectionLabel) {
+    out.push("  " + dim("Grounded on ", useColor) + connectionLabel);
+  }
+  out.push(
+    "  " +
+      dim("Ask a question · ", useColor) +
+      "exit" +
+      dim(" to quit · ", useColor) +
+      "deepsql --help" +
+      dim(" for CLI commands", useColor)
+  );
+  if (versionLine) out.push("  " + versionLine);
+  out.push("");
+  stdout.write(out.join("\n") + "\n");
+}
+
+function compareSemver(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+// Best-effort latest-version lookup from the npm registry, with a tight timeout
+// so it never noticeably delays startup. Resolves null on any failure.
+function fetchLatest(timeoutMs = 1200) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => {
+      if (!done) {
+        done = true;
+        resolve(v);
+      }
+    };
+    try {
+      const req = https.get(
+        "https://registry.npmjs.org/@deepsql/mcp/latest",
+        { timeout: timeoutMs, headers: { accept: "application/json" } },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            return finish(null);
+          }
+          let d = "";
+          res.on("data", (chunk) => (d += chunk));
+          res.on("end", () => {
+            try {
+              finish(JSON.parse(d).version || null);
+            } catch {
+              finish(null);
+            }
+          });
+        }
+      );
+      req.on("timeout", () => {
+        req.destroy();
+        finish(null);
+      });
+      req.on("error", () => finish(null));
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+// "v0.22.0 · latest" / "v0.22.0 · update available → v0.23.0  npm i -g …".
+// Falls back to a plain dim version when the registry can't be reached.
+async function getVersionLine(useColor) {
+  const cur = PKG_VERSION;
+  if (!cur) return null;
+  const latest = await fetchLatest();
+  if (!latest) return dim(`v${cur}`, useColor);
+  if (compareSemver(latest, cur) > 0) {
+    return (
+      c(PURPLE_LIGHT, `v${cur}`, useColor) +
+      dim(" · update available → ", useColor) +
+      c(PURPLE, `v${latest}`, useColor) +
+      dim("   npm i -g @deepsql/mcp@latest", useColor)
+    );
+  }
+  return dim(`v${cur} · latest`, useColor);
+}
+
+module.exports = { renderIntro, getVersionLine, promptLabel };