docs: add Cursor Cloud dev environment setup instructions to AGENTS.md

Co-authored-by: Venkat SF <venkatesh.sakamuri@stayflexi.com>

Author: cursoragent

AGENTS.md

@@ -180,3 +180,52 @@ 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).
+- 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 is unconfigured by default** (no key shipped). The backend boots fine and non-AI
+  features (connections, schema browsing, SQL editor) work; chat/dashboards/brain throw
+  `LlmNotConfiguredException` until `DEEPSQL_CHAT_*` is set in `.env`.
+- **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.