From 353c6e9195b2ba5d3c24f026ee59f8c31c677940 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 16 Mar 2026 13:14:32 +0000 Subject: [PATCH] Add Cursor Cloud specific instructions to AGENTS.md - Document required services (Next.js dev server, Convex backend) - Document required environment variables for .env.local - Document key commands (lint, test, typecheck, dev) - Document gotchas (proxy.ts middleware, bun test guard, env restart) Co-authored-by: Simplereally --- AGENTS.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ee140d8..d5563a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -95,4 +95,41 @@ Add: `bun add ` ## Styling (shadcn/ui + Tailwind) - Use shadcn/ui as the base; extend via composition + variants. - Tailwind utilities in JSX; extract repetition into components, not `@apply`. -- Theme via CSS variables; keep design tokens centralized. \ No newline at end of file +- Theme via CSS variables; keep design tokens centralized. + +--- + +## Cursor Cloud specific instructions + +### Product overview +Bloom Studio is a SaaS AI image/video generation app built with Next.js 16 (App Router, Turbopack), Convex (backend + real-time DB), Clerk (auth), and the Pollinations.AI API. + +### Services + +| Service | How to run | Notes | +|---------|-----------|-------| +| **Next.js dev server** | `bun run dev` | Starts on port 3000 by default | +| **Convex backend** | `bunx convex dev` | Requires a Convex project + `CONVEX_DEPLOYMENT` env var | + +### Environment variables +The app requires a `.env.local` file at the repo root with at minimum: +- `NEXT_PUBLIC_CONVEX_URL` — Convex deployment URL (hard error if missing) +- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` — Clerk publishable key +- `CLERK_SECRET_KEY` — Clerk server-side secret key (Clerk middleware rejects requests without this) +- `NEXT_PUBLIC_APP_URL` — defaults to `http://localhost:3000` + +Without valid Clerk keys the dev server compiles successfully but all page requests return 500. Clerk middleware (`proxy.ts`, which is loaded as the Next.js middleware) validates keys server-side. + +### Key commands +- **Lint:** `bun run lint` (ESLint flat config, caches to `.cache/eslint`) +- **Test:** `bun run test` (Vitest + jsdom + React Testing Library; 205 test files, ~2800 tests) +- **Type-check:** `bun run typecheck` +- **Dev:** `bun run dev` + +### Gotchas +- The middleware file is `proxy.ts` (not the standard `middleware.ts`). Clerk's `@clerk/nextjs` package auto-discovers it. +- Do **not** use `bun test` directly — always use `bun run test` (there's a guard script for this). +- `.env*` files are gitignored; you must create `.env.local` yourself. +- After changing `.env.local`, you must restart the dev server for the changes to take effect. +- The `convex/_generated/` directory is gitignored and created by `bunx convex dev`; Convex functions won't type-check until it exists. +- Never run `bun run build`, `bun run lint`, and `bun run test` in parallel — they can conflict. \ No newline at end of file