Skip to content

docs: add Cursor Cloud development environment setup instructions #702

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leoisadev1 merged 1 commit into from
Mar 20, 2026
Merged

docs: add Cursor Cloud development environment setup instructions #702

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,3 +95,27 @@ bun run verify:prod
- `git subtree push --prefix=docs-site https://github.com/tryosschat/docs.git main`
- `docs-site/` is external Mintlify docs; `docs/` contains internal deployment docs.
- `bunfig.toml` isolates Bun's own test discovery; use Vitest commands for project tests.

## Cursor Cloud specific instructions

### Environment
- Bun is installed at `~/.bun/bin/bun`; ensure `~/.bun/bin` is on `PATH`.
- Use `bun run test` (not bare `bun test`) to invoke the `vitest run --coverage` script from `package.json`. Bare `bun test` triggers Bun's built-in test runner, which fails because the `bunfig.toml` root (`.bun-tests/`) doesn't exist.
- The `.env.local` files for `apps/web` and `apps/server` are not checked in. They must be created before starting dev servers. Minimal dev defaults: `VITE_CONVEX_URL=http://localhost:3210`, `VITE_CONVEX_SITE_URL=http://localhost:3210` in `apps/web/.env.local`.

@greptile-apps greptile-apps Bot Mar 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Localhost placeholder contradicts Convex cloud requirement

The "Known caveats" section of this same PR explicitly states that bun dev:server requires a Convex cloud project — there is no local Convex server. Setting VITE_CONVEX_URL=http://localhost:3210 as the default will cause the web app to fail to connect to Convex and auth (via VITE_CONVEX_SITE_URL) to break entirely.

Standard Convex cloud dev URLs take the form https://<deployment-name>.convex.cloud. Using localhost:3210 as a placeholder looks like a working local default (which it is not) and will silently fail when a developer follows these instructions.

A more honest placeholder would make clear that a real URL is needed:

Suggested change
- The `.env.local` files for `apps/web` and `apps/server` are not checked in. They must be created before starting dev servers. Minimal dev defaults: `VITE_CONVEX_URL=http://localhost:3210`, `VITE_CONVEX_SITE_URL=http://localhost:3210` in `apps/web/.env.local`.
- The `.env.local` files for `apps/web` and `apps/server` are not checked in. They must be created before starting dev servers. Minimal dev defaults: `VITE_CONVEX_URL=https://<your-deployment>.convex.cloud`, `VITE_CONVEX_SITE_URL=https://<your-deployment>.convex.cloud` in `apps/web/.env.local`.

Confidence this is a real issue: 4/5 — The contradiction between the caveat ("requires a Convex cloud project") and the placeholder (localhost:3210) is clear-cut. Convex does not expose a local endpoint on 3210 in the standard cloud-based dev workflow.

Comment on lines +102 to +104

@greptile-apps greptile-apps Bot Mar 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 apps/server/.env.local mentioned but no example given

The Environment section correctly notes that .env.local files are needed for both apps/web and apps/server, but only provides example variables for apps/web. An agent following these instructions would not know which variables to put in apps/server/.env.local (e.g., CONVEX_DEPLOYMENT, AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, BETTER_AUTH_SECRET are all referenced in the Known caveats as requirements). The omission makes the setup incomplete and could leave agents (and humans) stuck.

Consider adding a minimal example for apps/server/.env.local alongside the web example, even if it is just a list of required variable names with placeholder values.

Confidence this is a real issue: 2/5 — The information gap is real, but it is also possible that the Convex CLI and server setup document required variables elsewhere, making this a minor omission rather than a blocker.


### Services
| Service | Command | Notes |
|---------|---------|-------|
| Web (Vite dev) | `bun dev:web` or `cd apps/web && bunx vite dev` | Runs on port 3000 by default. SSR requires all route modules to load cleanly. |
| Convex backend | `bun dev:server` | Requires Convex cloud credentials; connects to a remote Convex project. |
| Extension | `bun dev:extension` | Optional; not needed for core chat flow. |

### Verification commands
- Lint: `bun check` (runs Oxlint via Turbo across all workspaces)
- Tests: `bun run test` (Vitest with coverage)
- Type check: `bun check-types` (runs `tsc --noEmit` in web and extension workspaces; server uses `|| true`)

### Known caveats
- The Convex backend (`bun dev:server`) requires a Convex cloud project. Without one, the backend won't start. Auth features (GitHub OAuth) also require Convex environment variables (`AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`, `BETTER_AUTH_SECRET`).
- Redis is optional for development; the `scripts/check-redis.ts` script gracefully skips when Redis is unreachable in dev mode.
- No Docker or local database is required; Convex is the sole data store.
Loading