From 855e033fd8463632cd00a091335b96ca59fdfb7d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 16 Mar 2026 20:33:59 +0000 Subject: [PATCH 1/2] Add Cursor Cloud specific instructions to AGENTS.md - Document Docker infrastructure setup (Postgres pgvector on 15432, Redis on 16379) - Document fresh volume gotcha for DB init scripts and pgvector extension - Document app/worker startup commands and health endpoint auth behavior - Note pre-existing test failure in executive-agent-selector - Document minimal .env configuration requirements Co-authored-by: Rushik-B --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f6916b6..5558d89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -348,3 +348,33 @@ Good Clira code is: - small enough to reason about If a change makes the system feel smarter but harder to reason about, it is usually a regression. + +--- + +## Cursor Cloud specific instructions + +### Infrastructure + +- **PostgreSQL 16 + pgvector** runs via Docker Compose on port `15432`. Redis 7 runs on port `16379`. +- Start both with `docker compose up -d db redis` from the repo root. +- The DB init script (`docker/postgres-init/01-create-clira-app-user.sh`) only runs on a **fresh** Postgres volume. If the volume already exists, you must manually create the app DB role or recreate volumes with `docker compose down -v && docker compose up -d db redis`. +- After creating a fresh DB volume, you must also run `docker exec psql -U postgres -d clira -c "CREATE EXTENSION IF NOT EXISTS vector;"` **before** migrations, and grant the app user ownership: `ALTER DATABASE clira OWNER TO "";`. +- Run migrations with `npm run migrate:deploy`. + +### Running the app + +- `npm run dev` starts the Next.js dev server on port 3000. +- Workers require a separate build step: `npm run build:worker` before running `npm run start:worker`, `npm run start:gmail-pull-worker`, or `npm run start:cron`. +- The `/api/health` endpoint requires authentication (not in middleware public paths). Use `/signin` or `/api/auth/providers` to verify the app is responding. + +### Lint, test, build + +- See `README.md` for the full command table (`npm run lint`, `npm test`, `npm run build`). +- Tests use Vitest (`vitest run`). Config is in `vitest.config.ts` with `@/` path alias pointing to `src/`. +- One pre-existing test failure exists in `tests/ea-interrupts/executive-agent-selector.test.ts` (`exposes all packs when selector is disabled`). + +### Environment + +- Copy `.env.example` to `.env` and fill required values. The `.env` file is gitignored. +- Google OAuth credentials (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`) are needed for login. Without real credentials, the OAuth redirect still works but Google will reject the auth attempt. +- `NEXTAUTH_SECRET` and `CRON_SECRET` can be any non-empty strings for local dev. From 50c99cbf07db42749a7d402e735204ad5c22203d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 16 Mar 2026 21:39:05 +0000 Subject: [PATCH 2/2] Add onboarding flow and 2FA notes to AGENTS.md cloud instructions - Document Google 2FA blocker for automated login - Document onboarding flow steps and Gmail/Gemini API dependencies - Note post-onboarding Queue page behavior Co-authored-by: Rushik-B --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5558d89..bed4312 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -378,3 +378,10 @@ If a change makes the system feel smarter but harder to reason about, it is usua - Copy `.env.example` to `.env` and fill required values. The `.env` file is gitignored. - Google OAuth credentials (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`) are needed for login. Without real credentials, the OAuth redirect still works but Google will reject the auth attempt. - `NEXTAUTH_SECRET` and `CRON_SECRET` can be any non-empty strings for local dev. +- The test Google account has 2FA enabled. Automated credential-based login will fail at Google's verification step. Use the Desktop pane for interactive login, or ask the user to log in and preserve the session. + +### First login and onboarding + +- On first authenticated visit, the app redirects to `/onboarding-test-flow` with a multi-step wizard: welcome, phone pairing (skippable), inbox analysis (fetches labels, scans emails, analyzes senders, groups by projects), label selection, and then the main dashboard. +- The inbox analysis step calls the Gmail API and the Gemini API; it requires valid `GOOGLE_GENERATIVE_AI_API_KEY` and a connected Gmail account. +- After onboarding completes, the main view is the Queue page at `/` showing "Your queue is empty. Rest well." until emails are processed by the worker pipeline.