refactor(agent): rename agent customization dir and DeepSQL Agent branding (#22)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Summary

Renames the in-repo product customization directory from `hermes/` to
**`agent/`** and updates branding/docs so the product surface is the
**DeepSQL Agent**, not a plain Hermes copy as this is heavily customized for DBA activities.

## What changed

- Docs/comments (`AGENTS.md`, `CLAUDE.md`, Java/JS comments) say
**DeepSQL Agent**
- New [`agent/README.md`](agent/README.md) with an explicit **upstream
disclosure**: runtime is a heavily customized [Nous Hermes
Agent], while DeepSQL owns the
DBA persona, skills, MCP wiring, and branding overlays

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-8ce91e70-c67b-48c6-84b3-05bb9d06231a?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-8ce91e70-c67b-48c6-84b3-05bb9d06231a&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

Author: venkateshsakamuri-lab

AGENTS.md

@@ -178,8 +178,9 @@ only covers cloud-specific, non-obvious caveats.
 - **Backend** (port 8080, base path `/api`): `bash scripts/start-backend.sh` (wraps
   `./mvnw spring-boot:run`; it strips `SPRING_PROFILES_ACTIVE=prod` for local runs → dev mode).
 - **Frontend** (port 3000): `npm run dev` (Vite proxies `/api` → 8080 and `/agent-api` → 8787).
-- **Hermes Agent webui** (port 8787, optional): needed only for the sidebar **Agent** tab.
-  See caveats below for install + `HERMES_WEBUI_ALLOWED_ORIGINS`.
+- **DeepSQL Agent API** (port 8787, optional): needed for the sidebar **Agent** tab.
+  Runtime is a customized Nous Hermes Agent; see caveats below for install +
+  `HERMES_WEBUI_ALLOWED_ORIGINS` (upstream env name).
 - A demo target DB `demo_shop` (same Postgres server, sample `customers`/`products`/`orders`)
   exists for exercising connection/schema features without an external database.
 
@@ -207,15 +208,19 @@ only covers cloud-specific, non-obvious caveats.
   `DEEPSQL_CHAT_ENDPOINT=https://deepsql-selfhost-resource.cognitiveservices.azure.com/`,
   `DEEPSQL_CHAT_MODEL=gpt-5.4` (deployment name), plus matching `DEEPSQL_EMBEDDING_*` with
   `text-embedding-3-large`. Also set `AZURE_OPENAI_KEY` / `AZURE_OPENAI_ENDPOINT` aliases —
-  `hermes/install.sh` reads those. After changing LLM env, restart the backend
+  `agent/install.sh` reads those. After changing LLM env, restart the backend
   (`scripts/start-backend.sh`); `/api/setup/status` should show `hasLlmConfig: true`.
-- **Agent tab (Hermes) is optional but required for the in-app Agent chat UI.** Install via
+- **Agent tab is optional but required for the in-app Agent chat UI.** The Agent tab
+  is DeepSQL’s own React (`AgentChatPanel`); it talks to the DeepSQL Agent HTTP API
+  on `:8787` (a heavily customized [Nous Hermes Agent](https://hermes-agent.nousresearch.com/)
+  runtime — see [`agent/README.md`](agent/README.md)). Install upstream via
   `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive --skip-setup`,
-  symlink `~/.hermes/hermes-agent/.venv` → `venv` (DeepSQL's `hermes/install.sh` expects `.venv`),
-  then `bash hermes/install.sh`. Start the webui with
+  symlink `~/.hermes/hermes-agent/.venv` → `venv` (DeepSQL’s `agent/install.sh` expects `.venv`),
+  then `bash agent/install.sh`. Start the agent API/webui with
   `HERMES_WEBUI_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000`
-  (without this, Vite's Origin header makes Hermes return **403** "Cross-origin mismatch").
-  Webui listens on `:8787`; Vite proxies `/agent-api` → there.
+  (upstream env var; without it Vite’s Origin header yields **403** “Cross-origin mismatch”).
+  Listens on `:8787`; Vite proxies `/agent-api` → there. Profile cookie name
+  `hermes_profile` is an upstream contract — do not rename it in DeepSQL clients.
 - **Before running backend tests that boot the Spring context** (e.g. `ApiSmokeTest`), stop
   the running backend first — both use `ddl-auto=update` on the same `dba_agent` DB and can
   deadlock on an `ALTER TABLE`. Test env vars are documented in `CLAUDE.md` (Testing).

CLAUDE.md

@@ -90,6 +90,7 @@ src/                # Frontend (React)
 
 docs/               # Documentation
 mcp/                # DeepSQL Phase 1 MCP server (Node stdio wrapper around backend APIs)
+agent/              # DeepSQL Agent customization (persona, skills, skins; customized Hermes runtime)
 ```
 
 ## MCP Server
@@ -103,10 +104,11 @@ mcp/                # DeepSQL Phase 1 MCP server (Node stdio wrapper around back
 
 ## Dashboard Generation (artifact model)
 
-Dashboards are **generated by the embedded Hermes agent acting as a coding agent** — it writes the whole dashboard as a single self-contained HTML document, not a JSON spec. The earlier spec+renderer model (metrics/charts/tables + a `{{placeholder}}` substitution engine + `DashboardBuilder.js`) was thrown away: the rigid `col BETWEEN {{name}}` convention couldn't express real SQL (e.g. a Unix-epoch date filter → `near '{range.start}'` syntax errors) and boxed the agent in.
+Dashboards are **generated by the embedded DeepSQL Agent acting as a coding agent**
+(customized Hermes runtime — see [`agent/README.md`](agent/README.md)) — it writes the whole dashboard as a single self-contained HTML document, not a JSON spec. The earlier spec+renderer model (metrics/charts/tables + a `{{placeholder}}` substitution engine + `DashboardBuilder.js`) was thrown away: the rigid `col BETWEEN {{name}}` convention couldn't express real SQL (e.g. a Unix-epoch date filter → `near '{range.start}'` syntax errors) and boxed the agent in.
 
 - `DashboardAgentService` is a thin broker: `ensureProfileForUser` → `ensureSession` (fresh session) → `sendAndAwait` with an **artifact contract**. The agent grounds on the brain/schema, verifies every query with `execute_sql`, then emits ONE HTML doc (in a ` ```html ` block). The broker extracts the HTML and returns `{version:3, renderMode:"artifact", title, html, trace}`, stored verbatim in `saved_dashboards.dashboardConfig`.
-- The agent loads the **`dashboard-design` skill** (`hermes/skills/dashboard-design/SKILL.md`, v2 — artifact contract, the `deepsql.query` runtime, composition/UX rules, an **intent checklist**, and Unix-epoch date handling).
+- The agent loads the **`dashboard-design` skill** (`agent/skills/dashboard-design/SKILL.md`, v2 — artifact contract, the `deepsql.query` runtime, composition/UX rules, an **intent checklist**, and Unix-epoch date handling).
 - **Rendering + data access**: `DashboardArtifact.jsx` renders the HTML in a **sandboxed iframe** (`sandbox="allow-scripts"`, opaque origin + a strict CSP — no external network). The artifact fetches data only through an injected `deepsql.query(sql)` bridge that `postMessage`s to the parent; the parent calls **`POST /api/dashboards/query`** (`DashboardQueryController`), which is **read-only twice over** (`McpSqlGuardService.validateReadOnlySql` + `QueryExecutionContext.api` = `READ_ONLY_ONLY`) and access-scoped via `assertCanReadConnectionContent`. So the agent's code has full creative freedom while every query stays guarded and sandboxed. The bridge also auto-sizes the iframe and forwards runtime errors.
 - Generation endpoints unchanged (`POST /api/dashboards/generate` + `/generate/stream`). `DashboardBuilder.js`/`DashboardInputs.js` remain only because `tabs/Core/PreviewTab.js` still uses them — the dashboard *creation* path no longer touches them.
 - **Sharing**: both share types render a standalone read-only `DashboardViewer` (title + `DashboardArtifact` with an injected `queryFn`). Internal link `/dashboard-view/:id` (auth) uses the authed broker; public link `/share/dashboard/:token` (permitAll) uses `PublicDashboardController` (`GET /api/public/dashboards/{token}` + `/query`), which resolves only while `saved_dashboards.is_public` is true (revoke = flip it) and runs read-only + connection-scoped. `share_token`/`is_public` are set only via `POST|DELETE /api/saved-dashboards/{id}/share` (access-checked), never a general update. `ShareMenu.jsx` drives the UI. The public query path has its own nginx `dashq` limiter.

agent/README.md

@@ -0,0 +1,81 @@
+# DeepSQL Agent
+
+Source of truth for the **DeepSQL Agent** — DeepSQL’s DBA-specialized agent layer:
+persona, skills, skins, and install overlays.
+
+## Upstream disclosure
+
+The runtime is a **heavily customized [Nous Hermes Agent](https://hermes-agent.nousresearch.com/)**
+(plus its optional webui/TUI). DeepSQL does not ship a fork of that runtime in this
+tree. Instead this directory is the product surface we own:
+
+| DeepSQL customization | Purpose |
+|-----------------------|---------|
+| `SOUL.md` | DBA persona / always-on system prompt (grounding, RBAC, read-only defaults) |
+| `skills/*/SKILL.md` | DBA procedures (BI query, schema, indexes, slow queries, workload, dashboards) |
+| `skins/deepsql.yaml` | CLI/TUI skin |
+| `webui/` | Optional overlay that rebrands a Hermes webui checkout to DeepSQL |
+| `tui/` | Optional overlay that rebrands the Hermes TUI checkout to DeepSQL |
+| `install.sh` / `distribution.yaml` | Idempotent install + enterprise profile distribution |
+
+Upstream install paths and CLI names (`~/.hermes`, `hermes` binary, `HERMES_*` env
+vars, `hermes_profile` cookie, skill frontmatter `metadata.hermes`) are **unchanged** —
+those are contracts of the upstream engine. Product UI and docs refer to the
+**DeepSQL Agent**, not Hermes.
+
+The in-app Agent tab is DeepSQL’s own React (`AgentChatPanel`); it consumes the
+agent HTTP API (`/agent-api/*`), not the Hermes webui skin.
+
+## Contents
+
+- `SOUL.md` — DBA persona. Encodes DeepSQL grounding discipline (`get_brain_context`
+  before SQL, table-qualified columns, business rules + anti-patterns, read-only by
+  default, two-step mutation confirm).
+- `skills/<name>/SKILL.md` — procedural skills (agentskills.io format):
+  - `bi-query` — answer a data question with grounded, read-only SQL
+  - `schema-exploration` — map/describe a database
+  - `index-advisor` — recommend (and dry-run/apply) indexes via the workload-weighted advisor
+  - `slow-query-optimize` — diagnose + rewrite one slow query
+  - `workload-analysis` — hotspots, regressions, per-customer load, growth
+  - `dashboard-design` — HTML dashboard artifact contract for the coding-agent path
+- `distribution.yaml` — profile distribution for `hermes profile install/update`
+- `webui/`, `tui/`, `skins/` — optional branding overlays for upstream UIs
+
+These mirror workflows the in-house `AgentOrchestrator` performed, re-expressed as
+agent persona + skills over the DeepSQL MCP tools.
+
+## Install (local / self-host)
+
+1. Install the upstream agent runtime (see [AGENTS.md](../AGENTS.md) Cursor Cloud notes
+   or the [Hermes install docs](https://hermes-agent.nousresearch.com/)).
+2. Apply DeepSQL customization (requires `AZURE_OPENAI_KEY` in the environment or
+   the repo `.env`):
+
+```bash
+bash agent/install.sh
+```
+
+It configures `~/.hermes/config.yaml` from this repo:
+
+- **model** — Azure OpenAI via its OpenAI-compatible `…/openai/v1` endpoint (key from env/.env, never committed)
+- **mcp_servers.deepsql** — this repo’s `mcp/deepsql-phase1-server.js`
+- **skills.external_dirs** — this repo’s `agent/skills` (source of truth; must be a YAML list)
+- **approvals.mode: smart**, **SOUL.md** persona, and disables host-affecting toolsets
+  (terminal/file/code/browser/computer_use) → a read-only `deepsql:*` + memory/todo/skills sandbox
+
+Verify:
+
+```bash
+cd ~/.hermes/hermes-agent && uv run hermes mcp test deepsql   # → Connected, DeepSQL tools
+```
+
+The DeepSQL MCP server and the Spring backend remain the DBA brain; the agent consumes them.
+Optional upstream webui skin: see [`webui/`](webui/).
+
+### Approval UX (operator note)
+
+Because every exposed tool is read-only (`deepsql:*` reads; the one write tool,
+`apply_index_recommendation`, is server-side `confirm`-gated; host toolsets disabled),
+webui per-call approval prompts add friction without adding safety for this deployment.
+Operators can enable session auto-approve (or per-tool “Always allow”) so DBA turns
+flow without clicking. Left as a deliberate operator action, not a baked-in default.

hermes/SOUL.md agent/SOUL.mdhermes/SOUL.md renamed to agent/SOUL.md

@@ -55,8 +55,9 @@ before acting: `bi-query` (answer a data question), `schema-exploration`
 ## Voice
 
 You are **DeepSQL**. Never refer to yourself, your skills, your memory, or your
-runtime as "Hermes" — that is the underlying engine and is invisible to the
-user. They are **DeepSQL skills**, the **DeepSQL agent**, the **DeepSQL brain**.
+runtime as "Hermes" in user-facing replies — users see the **DeepSQL Agent**.
+(Operators know the runtime is a customized Nous Hermes Agent; that detail stays
+out of chat.) They are **DeepSQL skills**, the **DeepSQL agent**, the **DeepSQL brain**.
 Don't surface internal filesystem paths (`~/.hermes/...`) or engine internals;
 speak in DeepSQL product terms.
 

hermes/distribution.yaml agent/distribution.yamlhermes/distribution.yaml renamed to agent/distribution.yaml

@@ -1,7 +1,8 @@
-# DeepSQL Agent profile distribution.
+# DeepSQL Agent profile distribution (runs on the Nous Hermes Agent profile CLI).
 # 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).
+# `hermes_requires` is an upstream schema key — do not rename it.
 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/install.sh agent/install.shhermes/install.sh renamed to agent/install.sh

@@ -1,17 +1,20 @@
 #!/usr/bin/env bash
-# Reproducibly install the DBA customization into an agent home (~/.hermes).
-# Idempotent: safe to re-run. Source of truth is this repo's hermes/ dir.
+# Reproducibly install the DeepSQL Agent customization into an agent home (~/.hermes).
+# Idempotent: safe to re-run. Source of truth is this repo's agent/ dir.
 #
 # Configures:
 #   - model: existing Azure OpenAI gpt-5.4 via its OpenAI-compatible v1 endpoint
 #   - mcp_servers.deepsql: the repo's DeepSQL MCP server (read-only DBA tools)
-#   - skills.external_dirs: this repo's hermes/skills (source of truth)
+#   - skills.external_dirs: this repo's agent/skills (source of truth)
 #   - approvals.mode: smart
 #   - SOUL.md: the DBA persona
 #   - disables host-affecting toolsets (terminal/file/code/browser/computer_use)
 #
 # Secrets are read from the environment (or the repo .env), never committed:
 #   AZURE_OPENAI_KEY, AZURE_OPENAI_ENDPOINT  (endpoint defaults to the repo value)
+#
+# Upstream note: HERMES_HOME / hermes-agent / hermes CLI are contracts of the
+# Nous Hermes Agent runtime this customization runs on — do not rename those.
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -50,14 +53,14 @@ cfg.setdefault("mcp_servers", {})["deepsql"] = {
     "env": {"DEEPSQL_API_BASE_URL": "http://localhost:8080/api/",
             "DEEPSQL_MCP_USER_ID": "deepsql-agent", "DEEPSQL_MCP_PROJECT_ID": "deepsql-agent"},
 }
-cfg.setdefault("skills", {})["external_dirs"] = [f"{repo}/hermes/skills"]
+cfg.setdefault("skills", {})["external_dirs"] = [f"{repo}/agent/skills"]
 cfg.setdefault("approvals", {})["mode"] = "smart"
 cfg_path.write_text(yaml.safe_dump(cfg, sort_keys=False))
 print(f"  config.yaml updated ({cfg_path})")
 PY
 
 # Persona
-cp "$REPO_ROOT/hermes/SOUL.md" "$HERMES_HOME/SOUL.md"
+cp "$REPO_ROOT/agent/SOUL.md" "$HERMES_HOME/SOUL.md"
 echo "  SOUL.md installed"
 
 # Scope to a read-only sandbox: disable host-affecting toolsets.
@@ -66,4 +69,4 @@ echo "  SOUL.md installed"
     >/dev/null 2>&1 ) || echo "  (toolset disable skipped — disable manually with 'hermes tools disable ...')"
 echo "  host toolsets disabled (read-only deepsql + memory/todo/skills remain)"
 
-echo "✓ DBA customization installed. Verify: (cd $AGENT_DIR && uv run hermes mcp test deepsql)"
+echo "✓ DeepSQL Agent customization installed. Verify: (cd $AGENT_DIR && uv run hermes mcp test deepsql)"