Skip to main content
Version: 1.0.0
Last Updated: 2026-04-08
Purpose: Unified operational guide for using this repository in Cursor Cloud.

​
Why This Exists

This runbook consolidates cloud-specific guidance that was previously split across top-level docs. Use it as the canonical cloud workflow reference and keep AGENTS.md/AI_GUIDE.md linked here.

​
Local vs Cloud Differences

​
Cloud Setup Baseline

  1. Ensure repository access and branch permissions are configured.
  2. Ensure required env vars are configured for cloud runs:
    • app/runtime vars
    • MCP secrets (STITCH_API_KEY, etc.) when required
  3. Use idempotent setup commands in the workspace (dependency install + validation).
  4. Confirm .cursor/mcp.json uses environment variables for all secrets.
  5. Treat encore-api-surface (http://localhost:3399/mcp) as local-only; Cursor Cloud runs should use committed docs/api/* artifacts instead of a localhost MCP endpoint.

​
HMR behind a reverse proxy (Lovable preview / similar)

The Vite dev server’s HMR WebSocket defaults to a same-origin connection that works for plain localhost:8080. When Vite is served through a reverse proxy that terminates TLS (Lovable’s preview proxy, ngrok, etc.), the browser must connect back via wss://<proxy-host>:443 instead. Set one of these env vars to opt in to the proxy form:
Without those vars, HMR uses the localhost defaults — don’t set them when working on a regular dev box or you’ll see browser console errors like WebSocket connection to 'wss://localhost:443/...' failed.

​
Verification Path by Change Type

Use this matrix to choose the minimum sufficient cloud verification path:

​
Browser Validation Decision Flow

​
Governance Checklist for Cloud Runs

  • No plaintext secrets in committed AI config files.
  • Hook commands are cross-platform and present in the repository.
  • MCP server usage is documented and justified.
  • Verification evidence is captured before completion claims.
  • AI-config changes update related docs in the same PR.