Skip to content

cursor-cloud.md

Latest commit

 

History

History
18 lines (13 loc) · 4.53 KB

cursor-cloud.md

File metadata and controls

18 lines (13 loc) · 4.53 KB
Raw

Cursor Cloud Specific Instructions

Cursor Cloud specific instructions (not Codex Cloud)

Durable notes for Cloud Agents. Standard commands live in README.md and package.json; only non-obvious caveats are captured here.

  • Context7 peer-library docs habit (and the Next 16 local-docs carve-out) lives in docs/agents-guide.md. Project MCP is local @upstash/context7-mcp@3.2.5 with CONTEXT7_API_KEY from env/Secrets. If the host-injected Context7 MCP returns quota exceeded, use npx ctx7 library|docs … with the same secret — do not invent peer APIs from training data.
  • Runtime: the app hard-requires Node >=24.15.0 <25 / npm 11.x (engine-strict; the preinstall and runtime gates enforce the minor floor, while scripts/dev-free-port.mjs rejects other majors). A compatible Node 24 is installed via nvm and symlinked into /usr/local/cargo/bin (first entry in PATH) so node/npm resolve to it in every shell. If a shell ever resolves /exec-daemon/node (v22) instead, prepend the installed nvm Node 24 bin to PATH (for example "$HOME/.nvm/versions/node/v24.18.1/bin"; run ls "$HOME/.nvm/versions/node" to confirm the exact patch version).
  • 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 runtime, GitHub Actions pin, CI-scope, and sitemap checks. npm run verify:pr-local adds format, conditional build/client-bundle scanning, and RAG fixture/manifest validation without repeating unit tests; browser, Docker/Supabase, audit, and provider checks remain separate. See docs/testing.md for lock, live-test, Playwright, and flake-ledger rules. If check:installed-lock-parity or check:playwright-browser-revision reports Playwright/image drift (#255), do not force a mismatched Chromium path — delegate browser proof to CI Production UI (see docs/testing.md § Testing speed playbook).
  • For GitHub-related work authorised in this session, prefer the connected GitHub connector/MCP tools first for PR, issue, comment, review-thread, and Actions tasks they support (including run/job/log/artifact inspection and review-thread replies/resolution). A missing gh CLI is not a blocker for connector-supported work; never add a PAT as a workaround. The intended connection is BigSimmo with repository write access. Reserve administrator access for separately approved operations. Verify the exact target and connector result before any write. Ordinary authorised shell git branch publication remains allowed; use shell gh only for a genuine connector gap and only when the task permits it.