> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor Cloud Workflow

> This runbook consolidates cloud-specific guidance that was previously split across top-level docs. Use it as the canonical cloud workflow reference and keep AG…

**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

| Area         | Local Agent                     | Cursor Cloud Agent                                      |
| ------------ | ------------------------------- | ------------------------------------------------------- |
| Runtime      | Your local machine/sandbox      | Isolated Linux VM                                       |
| Tooling      | Uses your local installed tools | Uses workspace + cloud environment setup                |
| Secrets      | Local environment/session       | Cloud environment secrets must be configured explicitly |
| Hooks        | Local project/user hooks        | Project hooks only (repo-scoped)                        |
| Verification | Local terminal + browser flows  | Cloud terminal + browser/computer-use flows             |

***

## 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:

```bash theme={null}
# Lovable preview environment
LOVABLE=true npm run dev

# Generic TLS proxy
VITE_HMR_PROXY=true npm run dev
```

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:

| Change Type                     | Required Verification                                               |
| ------------------------------- | ------------------------------------------------------------------- |
| Docs/config-only                | Targeted lint/docs checks + link validation if docs changed         |
| Backend/migrations/no UI impact | Terminal validation + focused tests (RLS/integration as applicable) |
| UI-impacting, non-critical flow | Manual cloud UI smoke (browser MCP or computer-use)                 |
| UI-impacting, critical flow     | Targeted Playwright + manual cloud confirmation                     |

***

## Browser Validation Decision Flow

```mermaid theme={null}
flowchart TD
  changeType["ChangeType"] --> uiImpact{"UIImpact?"}
  uiImpact -->|"No"| terminalPath["RunTerminalValidation"]
  uiImpact -->|"Yes"| criticalFlow{"CriticalFlow?"}
  criticalFlow -->|"Yes"| playwrightPath["RunTargetedPlaywright"]
  criticalFlow -->|"No"| interactiveNeed{"NeedInteractiveCheck?"}
  interactiveNeed -->|"Yes"| browserPath["UseBrowserMCPOrComputerUse"]
  interactiveNeed -->|"No"| manualPath["RunManualUISmoke"]
  terminalPath --> doneNode["RecordEvidenceAndUpdateDocs"]
  playwrightPath --> doneNode
  browserPath --> doneNode
  manualPath --> doneNode
```

***

## 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.