docs: add Cursor Cloud development environment setup instructions

[leoisadev1]

Summary

Adds Cursor Cloud-specific development environment instructions to AGENTS.md so future cloud agents can properly set up and use the development environment.

Changes

• Added ## Cursor Cloud specific instructions section to AGENTS.md covering:
  • Environment setup (Bun path, env files)
  • Service table (web, Convex backend, extension)
  • Verification commands (lint, test, typecheck)
  • Known caveats (Convex cloud requirement, Redis optional, no Docker needed)

Testing

• Lint: bun check — 3/3 workspaces pass (warnings only, 0 errors)
• Tests: bun run test — 100 test files, 2589 tests all passing
• Type check: bun check-types — passes for web and extension workspaces
• Dev server: bun dev:web (Vite v7.3.1) starts successfully on port 3000

Notes

• The VM update script installs Bun v1.3.5 and runs bun install
• .env.local files are created at setup time (not committed)
• Pre-existing SSR issue noted: apps/web/src/routes/share/$shareId.tsx uses .validator() which was renamed to .inputValidator() in the locked @tanstack/react-start@1.165.0

  

Note

Add Cursor Cloud development environment setup instructions to AGENTS.md

Adds a new 'Cursor Cloud specific instructions' section to AGENTS.md covering setup steps, required environment variables, and known caveats for running the project in Cursor Cloud.

• Documents Bun install path and PATH requirement, and the need to use bun run test instead of bun test
• Provides minimal .env.local examples for apps/web and apps/server with Convex URL placeholders
• Lists service start commands for Web (Vite dev), Convex backend, and Extension, plus verification commands for lint, tests, and type checks
• Notes that Convex requires a cloud project, Redis is optional, and no Docker or local DB is needed

^{Macroscope summarized 3647403.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
osschat-web	Ignored		Mar 20, 2026 0:17am

[github-actions]

🚀 Preview Deployment Ready

Vercel is rebuilding the frontend with the new Convex backend URL.

Vercel will post the preview URL automatically.

Convex Preview Backend

• Cloud URL: https://rugged-trout-424.convex.cloud
• Site URL: https://rugged-trout-424.convex.site

ℹ️ Preview deployments support email/password auth only (GitHub/Vercel OAuth disabled).

---

_{🤖 Deployed automatically by GitHub Actions}

[greptile-apps]

Greptile Summary

This PR adds a ## Cursor Cloud specific instructions section to AGENTS.md to help cloud-based agents bootstrap the development environment. The content is generally well-structured and informative, but there is one notable inconsistency that could cause setup failures.

• Incorrect Convex URL placeholder (P1): The recommended .env.local default uses http://localhost:3210 for both VITE_CONVEX_URL and VITE_CONVEX_SITE_URL, but the same PR's "Known caveats" section explicitly states that a Convex cloud project is required. There is no local Convex server at port 3210 in the standard cloud workflow — a real cloud URL (e.g. https://<deployment>.convex.cloud) must be used. Following the instructions as written will cause the web app to fail silently when connecting to Convex and break auth.
• Contradictory bun test guidance (P2): The existing ## COMMANDS block lists bun test (bare), while the new section warns that bare bun test triggers Bun's own runner and fails. Both pieces of guidance coexist in the same file, which could confuse agents following the COMMANDS block.
• Incomplete apps/server/.env.local example (P2): The section mentions that both apps/web and apps/server require .env.local files, but only provides variable examples for apps/web. Required server-side variables (AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, BETTER_AUTH_SECRET) are referenced in the caveats but not given as setup examples.

Confidence Score: 3/5

• Safe to merge for docs-only changes, but the incorrect localhost Convex URL placeholder should be corrected before this guidance is followed by agents.
• The change is documentation-only and carries no runtime risk to the codebase itself. However, the core setup instruction contains a factually incorrect placeholder URL (localhost:3210) that directly contradicts the stated cloud-only Convex requirement. An agent or developer following these instructions verbatim will end up with a broken environment, which is the primary purpose of this file. The two additional inconsistencies (bun test contradiction, missing server env example) further reduce polish.
• AGENTS.md — the new Cursor Cloud section has an incorrect Convex URL placeholder and an internal contradiction with the existing COMMANDS block.

Important Files Changed

Filename	Overview
AGENTS.md	Adds a "Cursor Cloud specific instructions" section with environment setup, service commands, verification steps, and known caveats. Contains a notable issue: the recommended VITE_CONVEX_URL=http://localhost:3210 placeholder contradicts the stated requirement for a Convex cloud project, and a minor internal contradiction with bun test vs bun run test in the existing COMMANDS block.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Cursor Cloud Agent Starts] --> B[Install Bun via ~/.bun/bin]
    B --> C[Add ~/.bun/bin to PATH]
    C --> D[Run bun install]
    D --> E{Create .env.local files}
    E --> |apps/web/.env.local| F[Set VITE_CONVEX_URL\nVITE_CONVEX_SITE_URL]
    E --> |apps/server/.env.local| G[Set AUTH_GITHUB_ID\nAUTH_GITHUB_SECRET\nBETTER_AUTH_SECRET]
    F --> H[Start Services]
    G --> H
    H --> I[bun dev:web\nVite on :3000]
    H --> J[bun dev:server\nRequires Convex Cloud credentials]
    H --> K[bun dev:extension\nOptional]
    I --> L{Verify}
    J --> L
    L --> M[bun check — Lint]
    L --> N[bun run test — Vitest]
    L --> O[bun check-types — TypeScript]

Loading

Comments Outside Diff (1)

1. AGENTS.md, line 86-88 (link)

   bun test in COMMANDS contradicts the new Cursor Cloud section

   The existing ## COMMANDS section (lines 86–90 in the final file) lists bun test as a valid top-level command. The new section immediately below warns that bare bun test triggers Bun's built-in runner and fails due to the bunfig.toml configuration. This creates a direct contradiction inside the same file — an agent following the COMMANDS block would use bun test and encounter a failure.

   The COMMANDS section should be updated to match the new guidance:

   Confidence this is a real issue: 3/5 — The inconsistency is real, but bun test may still be intentionally listed for completeness or may work in some environments. Still worth aligning the two sections to avoid confusing future agents.

_{Last reviewed commit: "docs: add Cursor Clo..."}

[greptile-apps]

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.

[greptile-apps]

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.