Set up Cursor Cloud dev environment (native backend + frontend + Postgres/Redis) (#18)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Summary

Sets up a full local development environment for DeepSQL (DBA Agent) in
the Cursor Cloud VM and documents the non-obvious caveats for future
agents. No application code was changed — only `AGENTS.md` gained a `##
Cursor Cloud specific instructions` section.

## Environment

Runs the stack **natively (no Docker)**:

- **Java 25** (Temurin) — required by `backend/pom.xml`
(`java.version=25`); set as default `java`/`javac` and `JAVA_HOME`.
- **PostgreSQL 16** + `pgvector` + `pg_stat_statements` — vault DB
`dba_agent` (port 5432), plus a demo target DB `demo_shop` with sample
data.
- **Redis** — cache on port 6379.
- **Backend** — `bash scripts/start-backend.sh` (`./mvnw
spring-boot:run`), Jetty on `:8080/api`.
- **Frontend** — `npm run dev` (Vite on `:3000`, proxies `/api` → 8080).

The startup **update script** is just `npm install` (system deps live in
the VM snapshot). Durable startup/run caveats are captured in
`AGENTS.md`.

## Verified

| Service | Command | Result |
|---|---|---|
| Backend | `bash scripts/start-backend.sh` | Started,
`/api/actuator/health` = `UP` (db, redis, dbScheduler all UP) |
| Frontend | `npm run dev` | Vite serving on `:3000` (HTTP 200) |
| Lint | `npm run lint` | Runs (pre-existing warnings/errors are the
repo baseline) |
| Tests | `./mvnw test -Dtest=ApiSmokeTest` | 3 tests, 0 failures |

## Hello-world

Registered a database connection to the local `demo_shop` DB through the
web UI and browsed its schema, exercising the credential vault,
`ConnectionService`, and schema introspection end to end.

## Key caveats documented in AGENTS.md

- `.env` is `source`d under `set -e` — dotted property keys abort the
script; use UPPERCASE Spring env names.
- `ENCRYPTION_KEYS` (not just `ENCRYPTION_KEY`) must be set or the
`EncryptionService` bean fails with a circular placeholder reference.
- `SECURITY_AUTH_ENABLED=false` enables the dev auto-admin bypass.
- `scheduled_tasks` table + extensions come from
`docker/postgres/init/*.sql` (applied by hand in the native setup).
- Stop the running backend before context-booting tests to avoid
`ddl-auto` deadlocks.

> Please merge the AGENTS.md updates so future agents remember these
setup caveats next time.
<!-- 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

@@ -180,3 +180,65 @@ model work without CORS or cookie special-casing.
 - Database provider anti-pattern → never use if/else for database types
 - Connection pool pollution → always reset session state after benchmark operations
 - Frontend state → use Zustand selector hooks to avoid infinite re-render loops
+
+## Cursor Cloud specific instructions
+
+The dev environment runs the stack **natively (no Docker)**: Java 25 + Maven wrapper backend,
+Vite frontend, and locally-installed PostgreSQL 16 + Redis. System dependencies (JDK 25,
+Postgres, pgvector, Redis) are baked into the VM snapshot; the startup update script only
+refreshes `npm install`. Standard commands live in [`CLAUDE.md`](CLAUDE.md) — this section
+only covers cloud-specific, non-obvious caveats.
+
+### Services (start these each session — systemd is NOT running in the VM)
+
+- **PostgreSQL 16** (vault DB, port 5432): start with `sudo pg_ctlcluster 16 main start`.
+  DB `dba_agent` (user/pass `postgres`/`postgres`), extensions `vector` + `pg_stat_statements`
+  enabled. `shared_preload_libraries=pg_stat_statements` is already set in the cluster config.
+- **Redis** (cache, port 6379): start with `sudo redis-server /etc/redis/redis.conf --daemonize yes`.
+  Redis degrades gracefully but the local `.env` points at it.
+- **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`.
+- A demo target DB `demo_shop` (same Postgres server, sample `customers`/`products`/`orders`)
+  exists for exercising connection/schema features without an external database.
+
+### Non-obvious setup caveats (each cost real debugging time)
+
+- **Java 25 is mandatory** (`pom.xml` sets `java.version=25`); the VM's default `java` is set
+  to Temurin 25 via `update-alternatives`, and `JAVA_HOME` is exported in `~/.bashrc`.
+- **`.env` is loaded by `source` in `scripts/start-backend.sh`, which runs under `set -e`.**
+  Dotted keys like `spring.data.redis.host=...` make bash abort the whole script with
+  "command not found". Use Spring relaxed-binding UPPERCASE env names instead
+  (e.g. `SPRING_DATA_REDIS_HOST`). This is why the local `.env` avoids dotted keys.
+- **`ENCRYPTION_KEYS` must be set, not just `ENCRYPTION_KEY`.** `application.properties`
+  hardcodes `ENCRYPTION_KEYS=${ENCRYPTION_KEYS:}`; with the OS env var unset this is a
+  circular placeholder reference that fails `EncryptionService` bean creation at boot. The
+  local `.env` sets `ENCRYPTION_KEYS=<id>:<base64key>` matching `ENCRYPTION_KEY_ID`.
+- **`SECURITY_AUTH_ENABLED=false`** (set in `.env`) enables the dev auto-admin bypass, so the
+  web UI needs no login. Auth defaults to ON in every profile otherwise (there is no
+  `admin/admin`); a real login needs the localhost admin-bootstrap flow (see README).
+- **The `scheduled_tasks` table and the `vector`/`pg_stat_statements` extensions** come from
+  `docker/postgres/init/*.sql`. In the native (non-Docker) setup those were applied by hand;
+  they persist in the snapshot. If you ever recreate the vault DB, re-apply
+  `docker/postgres/init/*.sql` or db-scheduler logs `relation "scheduled_tasks" does not exist`.
+- **LLM (Azure OpenAI) is configured in the local gitignored `.env`** (not committed). Working
+  values for this environment: `DEEPSQL_CHAT_PROVIDER=openai`,
+  `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
+  (`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
+  `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
+  `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.
+- **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).
+- `npm run lint` currently reports many pre-existing warnings/errors in the repo; that is the
+  baseline, not a setup failure.