From 9239bd7a12268fcedebd55152ee9aeee3b742d85 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 20 Jun 2026 13:07:04 +0000 Subject: [PATCH 1/3] docs(agents): add Cursor Cloud setup and run caveats Co-authored-by: Andrea Mazzucchelli --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 749727a..f22b5bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,3 +20,44 @@ Cortex is a TypeScript monorepo for an MCP-first context, policy, and audit plat - Security: [`docs/agents/security.md`](docs/agents/security.md) - Git and PR workflow: [`docs/agents/git-workflow.md`](docs/agents/git-workflow.md) - Deletion candidates audit: [`docs/agents/deletion-candidates.md`](docs/agents/deletion-candidates.md) + +## Cursor Cloud specific instructions + +The startup update script already runs `pnpm install` and generates the Prisma +client. The notes below cover only the non-obvious caveats. + +### Services + +- `@cortex/api` (NestJS, port 4000) — core product (MCP entrypoint + auth). Needs Postgres + env vars. +- `@cortex/web` (Next.js, port 3000) and `@cortex/docs` (port 3001) — run cleanly via `pnpm --filter @cortex/web dev` / `--filter @cortex/docs dev`. Currently default Turborepo starter pages. +- Standard commands (`pnpm lint|check-types|build|test|dev`) are in [`docs/agents/commands.md`](docs/agents/commands.md). All pass. + +### PostgreSQL (installed natively, not Docker) + +- `docker`/`docker-compose` are NOT available; Postgres 16 is installed via apt instead. Data, the `cortex` role/db, and the applied schema persist in the VM snapshot. +- Start it (not auto-started on boot): `sudo pg_ctlcluster 16 main start`. +- Connection (matches `docker-compose.yml`): `postgresql://cortex:cortex@localhost:5432/cortex`. + +### Environment variables + +- The API reads `process.env` directly (no dotenv autoload). Export vars before running: `set -a; . /workspace/.env; set +a`. +- `/workspace/.env` exists (gitignored, persists in snapshot) with dev values for `DATABASE_URL` and `JWT_SECRET`. `JWT_SECRET` is required or `@cortex/api` fails to boot. + +### Migrations (Prisma 7 config gotcha) + +- `prisma migrate deploy` / `db:migrate` fail with "datasource.url property is required": `packages/db/prisma.config.ts` uses `env["DATABASE_URL"]` which does not resolve from `process.env` in Prisma 7. +- The committed migration SQL has already been applied to the DB. To re-apply on a fresh DB, run the files in `packages/db/prisma/migrations/*/migration.sql` directly with `psql`. + +### Running the API end-to-end (known gaps as committed) + +The API builds, type-checks, lints, and its 53 jest tests pass, but it cannot be booted by the committed scripts as-is: + +- `apps/api/tsconfig.json` `paths` map `db/client` to a `.ts` source file; `nest build`/`nest start` emit a require to that `.ts`, so `node dist/...` and `nest start --watch` fail (this is the "dev/build not stable yet" note in `docs/agents/commands.md`). The runnable compiled entry is `apps/api/dist/apps/api/src/main.js`, not `dist/main.js`. +- The Prisma 7 client needs a driver adapter (`@prisma/adapter-pg`), but `PrismaService` constructs `PrismaClient()` with no adapter, so it throws at boot. + +Fully running the API therefore requires small code/config fixes (wire `@prisma/adapter-pg` into `PrismaService`, correct the `db` package paths/exports). Until then, prefer the unit tests and the web/docs apps for verification. + +### Tests + +- `pnpm test` passes (`@cortex/shared` 21, `@cortex/api` 53). The "API/DB test scripts intentionally fail" note in `docs/agents/testing.md` is outdated for `@cortex/api`; `db` simply has no `test` script. +- API tests mock `db/client` (`apps/api/src/__mocks__/db-client.mock.ts`), so they need no database. From cd4c08b246ed530c82617149310e2a04c380cc9f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 20 Jun 2026 13:23:58 +0000 Subject: [PATCH 2/3] docs(agents): move Cursor Cloud notes to dedicated file (progressive disclosure) Co-authored-by: Andrea Mazzucchelli --- AGENTS.md | 40 ++---------------------------------- docs/agents/README.md | 2 ++ docs/agents/cursor-cloud.md | 41 +++++++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 38 deletions(-) create mode 100644 docs/agents/cursor-cloud.md diff --git a/AGENTS.md b/AGENTS.md index f22b5bc..53ca43f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,45 +19,9 @@ Cortex is a TypeScript monorepo for an MCP-first context, policy, and audit plat - Testing: [`docs/agents/testing.md`](docs/agents/testing.md) - Security: [`docs/agents/security.md`](docs/agents/security.md) - Git and PR workflow: [`docs/agents/git-workflow.md`](docs/agents/git-workflow.md) +- Cursor Cloud setup and run caveats: [`docs/agents/cursor-cloud.md`](docs/agents/cursor-cloud.md) - Deletion candidates audit: [`docs/agents/deletion-candidates.md`](docs/agents/deletion-candidates.md) ## Cursor Cloud specific instructions -The startup update script already runs `pnpm install` and generates the Prisma -client. The notes below cover only the non-obvious caveats. - -### Services - -- `@cortex/api` (NestJS, port 4000) — core product (MCP entrypoint + auth). Needs Postgres + env vars. -- `@cortex/web` (Next.js, port 3000) and `@cortex/docs` (port 3001) — run cleanly via `pnpm --filter @cortex/web dev` / `--filter @cortex/docs dev`. Currently default Turborepo starter pages. -- Standard commands (`pnpm lint|check-types|build|test|dev`) are in [`docs/agents/commands.md`](docs/agents/commands.md). All pass. - -### PostgreSQL (installed natively, not Docker) - -- `docker`/`docker-compose` are NOT available; Postgres 16 is installed via apt instead. Data, the `cortex` role/db, and the applied schema persist in the VM snapshot. -- Start it (not auto-started on boot): `sudo pg_ctlcluster 16 main start`. -- Connection (matches `docker-compose.yml`): `postgresql://cortex:cortex@localhost:5432/cortex`. - -### Environment variables - -- The API reads `process.env` directly (no dotenv autoload). Export vars before running: `set -a; . /workspace/.env; set +a`. -- `/workspace/.env` exists (gitignored, persists in snapshot) with dev values for `DATABASE_URL` and `JWT_SECRET`. `JWT_SECRET` is required or `@cortex/api` fails to boot. - -### Migrations (Prisma 7 config gotcha) - -- `prisma migrate deploy` / `db:migrate` fail with "datasource.url property is required": `packages/db/prisma.config.ts` uses `env["DATABASE_URL"]` which does not resolve from `process.env` in Prisma 7. -- The committed migration SQL has already been applied to the DB. To re-apply on a fresh DB, run the files in `packages/db/prisma/migrations/*/migration.sql` directly with `psql`. - -### Running the API end-to-end (known gaps as committed) - -The API builds, type-checks, lints, and its 53 jest tests pass, but it cannot be booted by the committed scripts as-is: - -- `apps/api/tsconfig.json` `paths` map `db/client` to a `.ts` source file; `nest build`/`nest start` emit a require to that `.ts`, so `node dist/...` and `nest start --watch` fail (this is the "dev/build not stable yet" note in `docs/agents/commands.md`). The runnable compiled entry is `apps/api/dist/apps/api/src/main.js`, not `dist/main.js`. -- The Prisma 7 client needs a driver adapter (`@prisma/adapter-pg`), but `PrismaService` constructs `PrismaClient()` with no adapter, so it throws at boot. - -Fully running the API therefore requires small code/config fixes (wire `@prisma/adapter-pg` into `PrismaService`, correct the `db` package paths/exports). Until then, prefer the unit tests and the web/docs apps for verification. - -### Tests - -- `pnpm test` passes (`@cortex/shared` 21, `@cortex/api` 53). The "API/DB test scripts intentionally fail" note in `docs/agents/testing.md` is outdated for `@cortex/api`; `db` simply has no `test` script. -- API tests mock `db/client` (`apps/api/src/__mocks__/db-client.mock.ts`), so they need no database. +- See [`docs/agents/cursor-cloud.md`](docs/agents/cursor-cloud.md) for environment setup, service ports, PostgreSQL startup, env vars, and known API run caveats. diff --git a/docs/agents/README.md b/docs/agents/README.md index 5025cf9..741fbd1 100644 --- a/docs/agents/README.md +++ b/docs/agents/README.md @@ -16,6 +16,7 @@ docs/ api.md web.md db.md + cursor-cloud.md deletion-candidates.md ``` @@ -29,4 +30,5 @@ docs/ - API-specific guidance: [`api.md`](./api.md) - Web-specific guidance: [`web.md`](./web.md) - DB-specific guidance: [`db.md`](./db.md) +- Cursor Cloud setup and run caveats: [`cursor-cloud.md`](./cursor-cloud.md) - Prior guidance flagged for deletion: [`deletion-candidates.md`](./deletion-candidates.md) diff --git a/docs/agents/cursor-cloud.md b/docs/agents/cursor-cloud.md new file mode 100644 index 0000000..c62fbd4 --- /dev/null +++ b/docs/agents/cursor-cloud.md @@ -0,0 +1,41 @@ +# Cursor Cloud + +Setup and run caveats for Cursor Cloud agents. The startup update script already +runs `pnpm install` and generates the Prisma client. The notes below cover only +the non-obvious caveats. + +## Services + +- `@cortex/api` (NestJS, port 4000) — core product (MCP entrypoint + auth). Needs Postgres + env vars. +- `@cortex/web` (Next.js, port 3000) and `@cortex/docs` (port 3001) — run cleanly via `pnpm --filter @cortex/web dev` / `--filter @cortex/docs dev`. Currently default Turborepo starter pages. +- Standard commands (`pnpm lint|check-types|build|test|dev`) are in [`commands.md`](./commands.md). All pass. + +## PostgreSQL (installed natively, not Docker) + +- `docker`/`docker-compose` are NOT available; Postgres 16 is installed via apt instead. Data, the `cortex` role/db, and the applied schema persist in the VM snapshot. +- Start it (not auto-started on boot): `sudo pg_ctlcluster 16 main start`. +- Connection (matches [`../../docker-compose.yml`](../../docker-compose.yml)): `postgresql://cortex:cortex@localhost:5432/cortex`. + +## Environment variables + +- The API reads `process.env` directly (no dotenv autoload). Export vars before running: `set -a; . /workspace/.env; set +a`. +- `/workspace/.env` exists (gitignored, persists in snapshot) with dev values for `DATABASE_URL` and `JWT_SECRET`. `JWT_SECRET` is required or `@cortex/api` fails to boot. + +## Migrations (Prisma 7 config gotcha) + +- `prisma migrate deploy` / `db:migrate` fail with "datasource.url property is required": [`../../packages/db/prisma.config.ts`](../../packages/db/prisma.config.ts) uses `env["DATABASE_URL"]` which does not resolve from `process.env` in Prisma 7. +- The committed migration SQL has already been applied to the DB. To re-apply on a fresh DB, run the files in `../../packages/db/prisma/migrations/*/migration.sql` directly with `psql`. + +## Running the API end-to-end (known gaps as committed) + +The API builds, type-checks, lints, and its 53 jest tests pass, but it cannot be booted by the committed scripts as-is: + +- [`../../apps/api/tsconfig.json`](../../apps/api/tsconfig.json) `paths` map `db/client` to a `.ts` source file; `nest build`/`nest start` emit a require to that `.ts`, so `node dist/...` and `nest start --watch` fail (this is the "dev/build not stable yet" note in [`commands.md`](./commands.md)). The runnable compiled entry is `apps/api/dist/apps/api/src/main.js`, not `dist/main.js`. +- The Prisma 7 client needs a driver adapter (`@prisma/adapter-pg`), but `PrismaService` constructs `PrismaClient()` with no adapter, so it throws at boot. + +Fully running the API therefore requires small code/config fixes (wire `@prisma/adapter-pg` into `PrismaService`, correct the `db` package paths/exports). Until then, prefer the unit tests and the web/docs apps for verification. + +## Tests + +- `pnpm test` passes (`@cortex/shared` 21, `@cortex/api` 53). The "API/DB test scripts intentionally fail" note in [`testing.md`](./testing.md) is outdated for `@cortex/api`; `db` simply has no `test` script. +- API tests mock `db/client` ([`../../apps/api/src/__mocks__/db-client.mock.ts`](../../apps/api/src/__mocks__/db-client.mock.ts)), so they need no database. From f1e06295fc6a6e09c04acc810d2e7a8f32ef346c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 20 Jun 2026 13:26:35 +0000 Subject: [PATCH 3/3] docs(agents): drop redundant Cursor Cloud section (kept progressive-disclosure link) Co-authored-by: Andrea Mazzucchelli --- AGENTS.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 53ca43f..0d09ab3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,3 @@ Cortex is a TypeScript monorepo for an MCP-first context, policy, and audit plat - Git and PR workflow: [`docs/agents/git-workflow.md`](docs/agents/git-workflow.md) - Cursor Cloud setup and run caveats: [`docs/agents/cursor-cloud.md`](docs/agents/cursor-cloud.md) - Deletion candidates audit: [`docs/agents/deletion-candidates.md`](docs/agents/deletion-candidates.md) - -## Cursor Cloud specific instructions - -- See [`docs/agents/cursor-cloud.md`](docs/agents/cursor-cloud.md) for environment setup, service ports, PostgreSQL startup, env vars, and known API run caveats.