@deepsql/mcp 0.18.2 → 0.20.0

package/CLAUDE.md

@@ -33,9 +33,28 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes 21 tools. They all take a `connectionId` (UUID
-returned by `list_connections`) except `apply_index_recommendation`,
-which takes a server-resolved `recommendationId`.
+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
+take a `connectionId` (UUID returned by `list_connections`); a few
+take server-resolved row ids (`apply_index_recommendation` →
+`recommendationId`, `dismiss_index_recommendation` →
+`recommendationId`, `acknowledge_growth_anomaly` → `anomalyId`,
+`get_digest_by_id` → `digestId`); `get_current_user` and
+`list_connections` take no args.
+
+The surface mirrors the `deepsql` CLI for almost every read/diagnostic
+operation. **Three CLI capabilities are intentionally NOT in MCP**:
+
+1. **Connection write ops** (`add`, `update`, `remove`) — they take
+   plaintext DB credentials, which would land in your conversation
+   history. Tell the user to run `deepsql connections add` at a TTY.
+2. **Auth flows** (`login`, `logout`, `setup`, `mcp config --install`) —
+   interactive by nature.
+3. **Streaming AI optimization** (`slow-queries optimize`) — SSE
+   stream, doesn't fit JSON-RPC tools.
+
+Per-user admin ops (`users`, `access`, `permissions`) are also CLI-only
+in this version; ask before mid-session admin work.
 
 | Tool | Purpose |
 |---|---|
@@ -53,7 +72,7 @@ which takes a server-resolved `recommendationId`.
 | `get_slow_query_customers` | Tenants/customers ranked by total slow-query time. Includes resolved customer name when a lookup table is configured. Answers "which customer is driving the load?" |
 | `get_query_samples` | Literal SQL samples (with actual bind values substituted) for a fingerprint, slowest-first. Use to reproduce an execution, get a real EXPLAIN plan, or see how different callers use the same query shape. |
 | `get_slow_query_insights` | Pre-computed AI insights for slow queries grouped by `kind`: `hotspots` (most total DB time), `remediation` (actionable fixes), `tail-risk` (p95/max outliers), `plan-drift` (execution plan changed), `skew` (one tenant disproportionately loaded). Default `all` returns the combined list. Accepts `window` (`LAST_24_HOURS` / `LAST_7_DAYS` / `LAST_30_DAYS`) and `limit`. |
-| `optimize_slow_query` | AI-generated optimization recommendations for a specific SQL — index suggestions, query rewrites, and estimated impact. Synchronous (non-streaming); pass `avgExecutionTimeMs` to anchor the impact estimate. |
+| `optimize_slow_query` | AI query REWRITE + plan diagnosis for one specific SQL. Single-query scoped, synchronous. Does NOT recommend indexes — index/pre-aggregation recs require whole-workload context (`get_index_recommendations` / Workload Analysis). Pass `avgExecutionTimeMs` to anchor the impact estimate. |
 | `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. |
@@ -329,6 +348,7 @@ them at the terminal command rather than trying to fake it through
 
 | Capability | CLI command |
 |---|---|
+| Interactive DBA/BI chat agent (the DeepSQL Agent TUI — backed by this same brain, no LLM key needed) | `deepsql agent` (or bare `deepsql` in a terminal) |
 | Workload-weighted advisor (terminal mirror of `get_index_recommendations`) | `deepsql indexes top [--limit N]` |
 | Apply / dry-run an advisor recommendation (terminal mirror of `apply_index_recommendation`) | `deepsql indexes apply <id> [--mode dry-run\|apply\|apply-and-measure] [--confirm]` |
 | Force a fresh accumulation cycle | `deepsql indexes refresh` |

package/README.md

@@ -1,10 +1,14 @@
 # DeepSQL CLI + MCP server
 
-The `@deepsql/mcp` package ships two things in one binary:
+The `@deepsql/mcp` package ships three things in one binary:
 
 - **`deepsql`** — a CLI for talking to a self-hosted DeepSQL backend from a
   terminal (auth, connections, SQL execution, plan analysis, index
   suggestions, slow-query analyses, admin ops).
+- **`deepsql agent`** (or just **`deepsql`** in a terminal) — the **DeepSQL
+  Agent**, an interactive DBA/BI chat TUI. It uses your saved login and the
+  backend proxies the model, so no LLM key is needed; the first run installs
+  the agent runtime. See [DBA Agent TUI](#dba-agent-tui-deepsql-agent).
 - **`deepsql mcp`** — a stdio MCP server that exposes the same backend to
   editor agents (Claude Code, Cursor, Codex, Claude Desktop) so they can
   query and reason about the user's databases.
@@ -31,6 +35,33 @@ deepsql connections use <connection-name>
 deepsql query "SELECT 1 AS ok"
 ```
 
+## DBA Agent TUI (`deepsql agent`)
+
+```bash
+deepsql login --url https://your-deepsql-host.example.com
+deepsql            # bare command in a terminal launches the Agent TUI
+# or, explicitly:
+deepsql agent
+```
+
+The **DeepSQL Agent** is an interactive terminal chat for DBA, BI, and
+database-guard work, backed by the same DeepSQL brain the MCP server
+exposes. It's a branded build of the open-source
+[Hermes Agent](https://github.com/NousResearch/hermes-agent) (MIT) with a
+DBA persona, read-only-by-default tool scoping, and DeepSQL skins.
+
+- **No LLM key needed** — the DeepSQL backend proxies the model
+  (`/api/llm/v1`), authenticated by your `deepsql login` token. The agent
+  never sees a provider key.
+- **First run** installs the agent runtime (Python via the Hermes
+  installer + Node for the TUI) and provisions a local `deepsql` profile.
+  Subsequent launches are instant.
+- **Read-only by default** — only the DeepSQL tools, memory, and skills are
+  enabled; host-affecting toolsets (terminal/file/code-exec/browser) are
+  disabled. `apply_index_recommendation` stays server-side confirm-gated.
+- Bare `deepsql` only launches the TUI when stdout is a TTY; piped or
+  scripted `deepsql` still prints help, so automation is unaffected.
+
 ## Wire into your editor (one command per editor)
 
 The installer writes the MCP server entry into the editor's config AND
@@ -52,31 +83,99 @@ Restart the editor for the entry to load.
 
 ## What the MCP server exposes
 
-21 tools, all read-only at the schema/retrieval layer and policy-gated
-at the SQL layer (only `execute_sql`, `analyze_query_plan` with
-`useAnalyze=true`, and `apply_index_recommendation` can write):
+**41 tools** as of 0.19.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
+triggers like `reinit_connection_brain` and `acknowledge_growth_anomaly`).
+
+The surface mirrors the `deepsql` CLI for every read/diagnostic
+operation. **What's intentionally NOT in MCP**: connection write ops
+(`add`/`update`/`remove` — they'd require plaintext DB credentials in
+agent conversation history; manage at a TTY via `deepsql connections
+add` instead), interactive auth flows (`login`/`logout`/`setup`/`mcp
+config --install`), the SSE streaming `slow-queries optimize` flow, and
+per-user admin ops (`users`/`access`/`permissions`).
+
+### Connections + identity (5)
 
 | Tool | Purpose |
 |---|---|
 | `list_connections` | Connections this token has access to |
+| `get_current_user` | Authenticated user + role + bound DeepSQL host |
+| `show_connection` | One connection's saved config, secrets masked |
+| `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)
+
+| Tool | Purpose |
+|---|---|
 | `get_schema` | Cached schema metadata (tables, columns, FKs, types) |
 | `get_database_objects` | Tables, views, functions, procedures |
 | `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 |
+
+### Anti-patterns + daily digest (4)
+
+| Tool | Purpose |
+|---|---|
 | `get_anti_patterns` | Schema-level or query-level anti-patterns |
+| `get_latest_digest` | Most recent DeepSQL daily digest (slow queries + AI commentary) |
+| `list_digests` | Recent digest metadata (find one by date) |
+| `get_digest_by_id` | Full digest body |
+
+### Index advisor — workload-weighted + apply tool (5)
+
+| Tool | Purpose |
+|---|---|
 | `get_index_recommendations` | Pre-computed top-N workload-weighted index recommendations |
 | `apply_index_recommendation` | Apply (or dry-run with HypoPG) an index recommendation and measure benefit |
-| `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples |
-| `get_slow_query_timeline` | Day-by-day timeline for one fingerprint from the 30-day analytics store |
+| `list_index_recommendations` | Browse the full recommendation history by status |
+| `refresh_index_recommendations` | Force a fresh accumulation cycle (skip 6-hour scheduler wait) |
+| `dismiss_index_recommendation` | Reject a recommendation explicitly |
+
+### Index catalog diagnostics — live pg_stat_* / sys.* probes (5)
+
+| Tool | Purpose |
+|---|---|
+| `get_missing_indexes` | Schema-walk view of suspected missing indexes |
+| `get_index_health` | Total/bloated/unused/duplicate/biggest indexes summary |
+| `get_unused_indexes` | Indexes with zero/near-zero scans (drop candidates) |
+| `get_duplicate_indexes` | Redundant prefix-duplicate indexes |
+| `get_table_index_usage` | Per-table scan/read/fetch counts on every index |
+
+### Slow queries (9)
+
+| Tool | Purpose |
+|---|---|
+| `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples (triggers fresh collection) |
+| `get_latest_slow_query_analysis` | Read the most recent persisted analysis (no new work) |
+| `list_slow_query_history` | List past analysis runs (compact metadata) |
+| `get_slow_query_timeline` | Day-by-day timeline for one fingerprint from the 30-day store |
 | `get_query_regressions` | Slow queries that regressed on the latest daily run |
 | `list_tracked_queries` | All fingerprints tracked in the 30-day store |
 | `get_slow_query_customers` | Tenants ranked by total slow-query load |
 | `get_query_samples` | Literal SQL samples (with bind values) for one fingerprint |
 | `get_slow_query_insights` | Pre-computed AI insights — hotspots / remediation / tail-risk / plan-drift / skew |
-| `optimize_slow_query` | AI optimization recommendations (index DDL + query rewrites) for a specific SQL |
+
+(`optimize_slow_query` is also in MCP — see the slow-query family.)
+
+### Growth analytics (5)
+
+| Tool | Purpose |
+|---|---|
 | `get_table_growth` | Per-table size/row growth from persistent stats history |
 | `get_growth_anomalies` | DeepSQL-flagged sudden growth spikes with severity and root-cause hints |
+| `acknowledge_growth_anomaly` | Mark an anomaly as expected (silences `unacknowledgedOnly` queries) |
+| `get_growth_config` | Read current alert thresholds and sensitivity |
+| `set_growth_config` | Update alert thresholds (admin-gated server-side) |
+
+### Plan + execute (2 — the write-capable pair)
+
+| Tool | Purpose |
+|---|---|
 | `execute_sql` | Run any SQL — backend enforces role-based policy (developers read-only, admins can mutate with two-step confirm) |
 | `analyze_query_plan` | AI-enriched plan analysis (parsed plan tree, performance issues, index recommendations, written summary that uses the connection's schema + business rules) |
 

package/agent-profile/SOUL.md

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,41 @@
+# 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

@@ -0,0 +1,40 @@
+---
+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.

package/agent-profile/skills/index-advisor/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: index-advisor
+description: Recommend which indexes to add or drop for a connection, using DeepSQL's workload-weighted advisor, and optionally dry-run/apply them.
+version: 1.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [index, indexes, advisor, performance, create-index, drop-index, unused, deepsql]
+    related_skills: [slow-query-optimize, workload-analysis]
+---
+
+# Index Advisor
+
+Use when the user asks what indexes to add or drop, or "how do I speed up this workload with indexes?" Indexes are a **whole-workload** decision — never recommend one off a single query in isolation; that's what this advisor is for.
+
+## Procedure
+
+1. **Resolve the connection** (`list_connections` → UUID).
+
+2. **Get the workload-weighted recommendations.** `get_index_recommendations(connectionId)` returns the pre-computed top-N (default 5) ranked by net benefit (`Σ calls × mean_exec_time` − write cost). Each carries the contributing query fingerprints, the role each column played, and (on Postgres) a HypoPG cost-delta. This covers both `CREATE_INDEX` and `DROP_INDEX` (unused / redundant-prefix) candidates.
+
+3. **Add catalog context** when relevant: `get_index_health(connectionId)` for the overall picture, `get_unused_indexes` / `get_duplicate_indexes` for dead weight, `get_missing_indexes` for catalog-level suggestions, `get_table_index_usage(table)` for one hot table.
+
+4. **Explain each recommendation** in terms the user can act on: which queries it helps, expected benefit, and write-cost trade-off. Don't just dump the list.
+
+5. **Estimate impact before applying.** `apply_index_recommendation(recommendationId, mode="DRY_RUN")` (default) uses HypoPG on Postgres to install a virtual index and EXPLAIN the contributing queries — zero writes. Report the planner cost delta.
+
+6. **Apply only on explicit request, admin only.** `mode="APPLY"` (real `CREATE/DROP INDEX CONCURRENTLY`) or `APPLY_AND_MEASURE` (also runs `EXPLAIN ANALYZE` before/after) require `confirm: true`. The DDL is server-generated from the recommendation row — you never supply index SQL. Surface what will run and get a human OK first.
+
+## Guardrails
+
+- Recommend against an existing covering index/constraint instead of a redundant single-column one — `get_index_health` / `get_table_index_usage` will show it.
+- A `DROP_INDEX` recommendation for an "unused" index still deserves a sanity check: confirm with the user it isn't a rarely-used-but-critical path before applying.
+- `apply_index_recommendation` is the only write-capable MCP tool. Treat every `APPLY` like a production change.

package/agent-profile/skills/schema-exploration/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: schema-exploration
+description: Map or describe a database — what it tracks, its tables, relationships, and conventions — grounded in DeepSQL's cached schema and brain.
+version: 1.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [schema, explore, tables, relationships, foreign-keys, describe, deepsql, database]
+    related_skills: [bi-query, workload-analysis]
+---
+
+# Schema Exploration
+
+Use when the user wants to understand the database itself ("what does this DB track?", "what tables exist?", "how are orders and customers related?", "describe the bookings table").
+
+## Procedure
+
+1. **Resolve the connection** (`list_connections` → UUID) if you don't have it.
+
+2. **Get the shape.** `get_schema(connectionId)` for tables, columns, types, declared FKs. `get_database_objects(connectionId)` when you also need views/functions/procedures, not just columns. The schema is cached and authoritative — trust it over the codebase.
+
+3. **Get the meaning.** `get_brain_context(connectionId, "<what the user is asking about>")` for the domain layer: what the tables mean, business terms, documentation. This is what turns "a list of tables" into "what the database tracks."
+
+4. **Fill relationship gaps.** Many real databases lack declared foreign keys. `get_relationships(connectionId)` returns inferred + validated FKs with a `confidence` score and `validationStatus`. Report the confidence — a 0.95 inferred FK is reliable; a 0.4 one is a guess.
+
+5. **Surface the rules and traps.** `list_business_rules(connectionId)` and `get_anti_patterns(connectionId, kind="table")` so the user learns the conventions and known schema smells, not just the structure.
+
+## Reporting
+
+- Lead with **what the database is for**, then the largest/most central tables, then notable relationships.
+- For "largest tables," use the row counts from `get_schema` (don't run `COUNT(*)` across every table).
+- Flag anti-patterns and low-confidence inferred FKs explicitly — they're the things a user most needs to know and least expects.

package/agent-profile/skills/slow-query-optimize/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: slow-query-optimize
+description: Diagnose why a query is slow and propose a rewrite, using DeepSQL's plan analysis and AI query optimizer.
+version: 1.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [slow, query, optimize, explain, plan, performance, rewrite, regression, deepsql]
+    related_skills: [index-advisor, workload-analysis]
+---
+
+# Slow Query Optimize
+
+Use when the user points at a specific query and asks "why is this slow?" or "make this faster." For workload-level "what's slow overall?" use `workload-analysis` instead.
+
+## Procedure
+
+1. **Resolve the connection** (`list_connections` → UUID).
+
+2. **Analyze the plan.** `analyze_query_plan(connectionId, sql)` returns the parsed plan tree, performance issues, missing-index hints, and a written summary that already accounts for the connection's schema and business rules. Use `useAnalyze: false` by default — `useAnalyze: true` actually executes the query (and for a mutation, triggers the same admin + confirm gate as `execute_sql`).
+
+3. **Get an AI rewrite** for a specific statement with `optimize_slow_query(connectionId, sql, avgExecutionTimeMs=…)`. Pass the average execution time to anchor the impact estimate. Note: this is single-query scoped and does NOT recommend indexes — route index questions to the `index-advisor` skill.
+
+4. **If the query came from the live workload**, identify it by fingerprint first: `analyze_slow_queries` (recent slow queries with fingerprints) → `get_query_samples(fingerprint)` for a real statement with bind values to plan against → `get_slow_query_timeline(queryId)` to confirm whether it's actually getting slower.
+
+5. **Report:** the root cause (slow node, bad estimate, missing index, plan drift), the proposed rewrite, and the expected improvement. If the real fix is an index, say so and hand off to `index-advisor`.
+
+## Guardrails
+
+- Don't run a mutation just to time it. `useAnalyze: true` on an `UPDATE`/`DELETE` executes it — only do that with admin role and explicit confirmation.
+- A rewrite that changes result semantics is a bug, not an optimization. Preserve the business rules (filters, soft-deletes) the original query respected.

package/agent-profile/skills/workload-analysis/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: workload-analysis
+description: Explain what's driving database load — slow-query hotspots, regressions, per-customer load, and table growth — across the whole workload.
+version: 1.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [workload, slow-queries, regression, hotspots, growth, anomaly, customers, deepsql]
+    related_skills: [slow-query-optimize, index-advisor]
+---
+
+# Workload Analysis
+
+Use for whole-workload questions: "what's slow right now?", "what regressed this week?", "which customer is driving load?", "what's growing fast?" For a single named query, use `slow-query-optimize`.
+
+## Procedure
+
+1. **Resolve the connection** (`list_connections` → UUID).
+
+2. **Find the hotspots.** `get_slow_query_insights(connectionId, kind="all", window=…)` returns pre-computed AI insights grouped as `hotspots` (most total DB time), `remediation` (actionable fixes), `tail-risk` (p95/max outliers), `plan-drift` (plan changed), `skew` (one tenant overloaded). `analyze_slow_queries` and `list_tracked_queries` give the raw fingerprint list with call counts and mean/max times.
+
+3. **Catch regressions.** `get_query_regressions(connectionId)` ranks queries that got slower on the latest analysis run by slowdown factor. Drill into one with `get_slow_query_timeline(queryId)` to see the day-by-day trend.
+
+4. **Attribute load.** `get_slow_query_customers(connectionId)` ranks tenants/customers by total slow-query time (with resolved customer name when configured) — answers "who is driving the load?"
+
+5. **Watch growth.** `get_table_growth(connectionId)` for size/row-count trends; `get_growth_anomalies(connectionId)` for tables growing abnormally. These predict the next performance cliff before it hits.
+
+6. **Synthesize, then route.** Lead with the few things that matter most (biggest total-time consumer, worst regression, fastest-growing table). For each, hand off to the right next step: a specific slow query → `slow-query-optimize`; an indexing opportunity → `index-advisor`.
+
+## Guardrails
+
+- Rank by **total** impact (`calls × mean_exec_time`), not by single-execution worst case — a 5-second query run twice a day matters less than a 200ms query run a million times.
+- Start with compact persisted analytics (`get_latest_slow_query_analysis`, `get_slow_query_insights`, `list_tracked_queries`). If a persisted payload is too large/truncated to inspect cleanly, pivot to the compact endpoints rather than trying to parse the oversized blob.
+- Use `analyze_slow_queries` when you need a fresh top-N snapshot for the last 24 hours; say explicitly that this triggers fresh analysis work, unlike the persisted analytics endpoints.
+- Everything here is read-only and analytics-store backed unless you intentionally call `analyze_slow_queries` for a fresh collection. Say so if the user worries about adding load.
+- `get_query_samples` exposes literal bind values — treat the output as potentially sensitive data.

package/agent-profile/skins/deepsql.yaml

@@ -0,0 +1,46 @@
+# DeepSQL Agent — terminal skin (subtle mono grey). Rebrands the Hermes TUI/CLI.
+# Ships in the profile distribution under <profile>/skins/, activated via
+# `display.skin: deepsql` in the profile's config.yaml. The DeepSQL wordmark +
+# tagline live in the (vendored) TUI source (banner.ts / branding.tsx); this skin
+# drives colors + branding strings.
+name: deepsql
+description: DeepSQL Agent — subtle mono
+
+colors:
+  # Prominent elements (wordmark, "What I can do" header, category labels, ✨ Try)
+  # use a mid-tone MAROON/garnet — a saturated mid-luminance color contrasts with
+  # BOTH light and dark terminal backgrounds (pure greys vanish on one of them).
+  # Body text is a warm neutral. Wordmark gradient = primary→accent→border.
+  banner_border: "#8E3B4A"   # deep maroon  — wordmark bottom rows + panel border
+  banner_title: "#B14A5C"    # garnet       — wordmark top rows + the section header
+  banner_accent: "#8E3B4A"
+  banner_dim: "#A89BA0"      # warm mid-grey — prompts / metadata (readable on both)
+  banner_text: "#D2C7CB"     # warm light-grey — descriptions
+  ui_accent: "#CC6B7D"       # rose-maroon  — wordmark mid rows + labels + ✨ Try
+  ui_label: "#CC6B7D"
+  ui_ok: "#3FA796"
+  ui_error: "#E5484D"
+  ui_warn: "#E6B15C"
+  prompt: "#DDD4D7"
+  input_rule: "#5A4348"
+  response_border: "#5A4348"
+  status_bar_bg: "#1A1113"
+  status_bar_text: "#D2C7CB"
+  status_bar_strong: "#E8DDE0"
+  status_bar_dim: "#A89BA0"
+  status_bar_good: "#3FA796"
+  status_bar_warn: "#E6B15C"
+  status_bar_bad: "#E5484D"
+  status_bar_critical: "#E5484D"
+  session_label: "#A89BA0"
+  session_border: "#8E3B4A"
+
+branding:
+  agent_name: "DeepSQL Agent"
+  welcome: "DeepSQL Agent — ask about your database, or /help for commands."
+  goodbye: "Bye."
+  response_label: " DeepSQL "
+  prompt_symbol: "❯"
+  help_header: "Commands"
+
+tool_prefix: "│"

package/agent-profile/tui/HERMES_VERSION

@@ -0,0 +1 @@
+0.17.0