Skip to main content

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.

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

AreaLocal AgentCursor Cloud Agent
RuntimeYour local machine/sandboxIsolated Linux VM
ToolingUses your local installed toolsUses workspace + cloud environment setup
SecretsLocal environment/sessionCloud environment secrets must be configured explicitly
HooksLocal project/user hooksProject hooks only (repo-scoped)
VerificationLocal terminal + browser flowsCloud 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.

​
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: 
# 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 TypeRequired Verification
Docs/config-onlyTargeted lint/docs checks + link validation if docs changed
Backend/migrations/no UI impactTerminal validation + focused tests (RLS/integration as applicable)
UI-impacting, non-critical flowManual cloud UI smoke (browser MCP or computer-use)
UI-impacting, critical flowTargeted Playwright + manual cloud confirmation

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