From a415df655afecc4babee5546b1a06408259ef40a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 5 Jul 2026 15:09:12 +0000 Subject: [PATCH 1/2] docs: add Cursor Cloud specific setup instructions to AGENTS.md Co-authored-by: BigSimmo --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6d5a4643d2..983f737a0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -263,3 +263,13 @@ After completing `upload`, summarize the current branch and worktree state, whet - When a repeated repo-specific workflow is discovered, update this file or ask the user whether it should be remembered. + +## Cursor Cloud specific instructions + +Durable notes for Cloud Agents. Standard commands live in `README.md` and `package.json`; only non-obvious caveats are captured here. + +- Runtime: the app hard-requires Node 24.x / npm 11.x (`engine-strict`, and `scripts/dev-free-port.mjs` exits on any other major). Node 24 is installed via nvm and symlinked into `/usr/local/cargo/bin` (first entry in `PATH`) so `node`/`npm` resolve to v24 in every shell. If a shell ever resolves `/exec-daemon/node` (v22) instead, prepend `"$HOME/.nvm/versions/node/v24.18.0/bin"` to `PATH`. +- No live credentials in this environment: no Supabase or OpenAI keys are set. `.env.local` sets `NEXT_PUBLIC_DEMO_MODE=true` (+ `RAG_PROVIDER_MODE=offline`), and in development `isDemoMode()` (`src/lib/env.ts`) auto-enables when Supabase config is absent. Answer/search/documents routes serve the synthetic in-memory corpus from `src/lib/demo-data.ts` and `public/demo-documents/` — good enough to exercise the core ask→cited-answer flow end-to-end. +- What will NOT run without real secrets: `npm run worker` (ingestion), Supabase edge functions, and the ops/eval/governance/backfill scripts (they call `requireServerEnv()`/`requireOpenAIEnv()`). `npm run check:supabase-project` and `verify:release` also fail without live Supabase + OpenAI. Do not treat those failures as environment regressions. +- Dev server: `npm run dev` selects a stable per-project localhost port (e.g. `4461`), binds `0.0.0.0`, and prints the exact URL. Never assume port 3000/3001/3002. `npm run ensure` starts/verifies it in the background. +- Verification without secrets: `npm run lint`, `npm run typecheck`, and `npm run test` (vitest) all pass offline. `npm run verify:cheap` also runs `check:runtime` + `sitemap:check` and is safe offline. From 81ac382c2a21fbce3bc8c2ad84361868dfadca48 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 5 Jul 2026 16:23:49 +0000 Subject: [PATCH 2/2] docs: document live-mode Supabase/OpenAI env vars for Cloud Agents Co-authored-by: BigSimmo --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 983f737a0d..81673123b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -269,7 +269,8 @@ After completing `upload`, summarize the current branch and worktree state, whet Durable notes for Cloud Agents. Standard commands live in `README.md` and `package.json`; only non-obvious caveats are captured here. - Runtime: the app hard-requires Node 24.x / npm 11.x (`engine-strict`, and `scripts/dev-free-port.mjs` exits on any other major). Node 24 is installed via nvm and symlinked into `/usr/local/cargo/bin` (first entry in `PATH`) so `node`/`npm` resolve to v24 in every shell. If a shell ever resolves `/exec-daemon/node` (v22) instead, prepend `"$HOME/.nvm/versions/node/v24.18.0/bin"` to `PATH`. -- No live credentials in this environment: no Supabase or OpenAI keys are set. `.env.local` sets `NEXT_PUBLIC_DEMO_MODE=true` (+ `RAG_PROVIDER_MODE=offline`), and in development `isDemoMode()` (`src/lib/env.ts`) auto-enables when Supabase config is absent. Answer/search/documents routes serve the synthetic in-memory corpus from `src/lib/demo-data.ts` and `public/demo-documents/` — good enough to exercise the core ask→cited-answer flow end-to-end. -- What will NOT run without real secrets: `npm run worker` (ingestion), Supabase edge functions, and the ops/eval/governance/backfill scripts (they call `requireServerEnv()`/`requireOpenAIEnv()`). `npm run check:supabase-project` and `verify:release` also fail without live Supabase + OpenAI. Do not treat those failures as environment regressions. +- Live vs demo mode: the app auto-detects. When the Supabase + OpenAI env vars below are present (set them as Cloud Agent **Secrets** so they inject into `.env.local`/`process.env`), `isDemoMode()` (`src/lib/env.ts`) is false and the app runs against the live `Clinical KB Database` project (~2000 indexed docs) with OpenAI answer generation. When they are absent, dev auto-falls back to demo mode using the synthetic corpus in `src/lib/demo-data.ts` / `public/demo-documents/`. Required for live mode: `NEXT_PUBLIC_SUPABASE_URL`, `SUPABASE_PROJECT_REF`, `SUPABASE_PROJECT_NAME`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (`sb_publishable_…`), `SUPABASE_SERVICE_ROLE_KEY` (accepts the `sb_secret_…` secret key), `OPENAI_API_KEY`. Keep `RAG_PROVIDER_MODE=auto` so OpenAI is used with graceful source-only fallback. `E2E_USER_EMAIL`/`E2E_USER_PASSWORD` power CI env-check and Playwright. +- Live-mode caveat: `RAG_PROVIDER_MODE=auto` attempts OpenAI (fast → strong route); if generation fails the built-in quality gates it silently degrades to a deterministic "Source-only" answer that still cites real documents — this is expected, not a failure. The header sign-in UI exposes magic-link + OAuth only (no password field), but the `/api/answer` + retrieval flow works server-side without a browser session. +- What still won't run in this VM even with secrets: `npm run worker` also needs the Python OCR stack (`worker/python/requirements.txt`) and heavy parsing deps; Supabase edge functions need Deno v2.x + deployment. `verify:release` additionally runs governance/eval gates. Treat missing-secret failures of `check:supabase-project`/`verify:release` in demo mode as expected, not regressions. - Dev server: `npm run dev` selects a stable per-project localhost port (e.g. `4461`), binds `0.0.0.0`, and prints the exact URL. Never assume port 3000/3001/3002. `npm run ensure` starts/verifies it in the background. - Verification without secrets: `npm run lint`, `npm run typecheck`, and `npm run test` (vitest) all pass offline. `npm run verify:cheap` also runs `check:runtime` + `sitemap:check` and is safe offline.