docs(agents): Cursor Cloud dev environment setup notes

Draft
TI
2mo ago
+40-0

Why

Sets up and documents the Cloud Agent development environment for this repo (Bun + Playwright/Chromium runtime for browse/make-pdf). No product code changes — only an appended ## Cursor Cloud specific instructions section in AGENTS.md capturing durable, non-obvious setup caveats for future agents.

What changed

  • AGENTS.md: added a ## Cursor Cloud specific instructions section documenting the Bun toolchain location/PATH, Playwright Chromium cache, the authoritative build/test/lint commands, how to run the browse/make-pdf CLI daemons, and — most importantly — a non-obvious gotcha.

Environment setup performed (not committed; captured in the VM)

  • Installed Bun 1.3.14 (~/.bun/bin, symlinked to /usr/local/bin/bun).
  • bun install --frozen-lockfile (256 packages) — also registered as the startup update script.
  • Installed Playwright Chromium 1.62.1 + system deps into ~/.cache/ms-playwright; poppler-utils/fonts-liberation already present.
  • bun run build — compiled browse/dist/browse, make-pdf/dist/pdf, node server bundle, bin/gstack-global-discover (all gitignored).

Live evidence

  • Lint: bun run slop → report generated (277 findings, informational scan; not a gate).
  • Tests: bun run test free suite runs. Diagnosed a flaky-failure root cause: Cursor's injected global ~/.gitconfig (commit.gpgsign=true via cursor-git-ssh-keygen + core.fsmonitor) makes git commit in tests' temp repos intermittently stall past their short spawnSync timeouts. With the global/system git config neutralized, the affected file is green:
    • GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null bun test test/diff-scope.test.ts → 16 pass / 0 fail in 394ms (vs 6 failures/60s otherwise).
    • test/gstack-memory-ingest.test.ts "#2105" is a separate pre-existing flake (passes on re-run).
  • Run (hello-world): the browse headless-Chromium daemon navigated to https://example.com (HTTP 200), extracted page text, and captured a 1280×720 screenshot. make-pdf rendered markdown → PDF via the same daemon.

browse Chromium screenshot of example.com

Scope

  • Changed: AGENTS.md only (docs). Verified live: build, lint, targeted tests, and both browse/make-pdf hello-world runs.
  • Not tested: paid eval/e2e suites (test:evals, test:e2e) — they require ANTHROPIC_API_KEY/provider auth and are out of scope for env setup.

To show artifacts inline, enable in settings.

Open in Web Open in Cursor 

Summary by cubic

Documents the Cursor Cloud dev environment in AGENTS.md so contributors can build, test, and run browse/make-pdf reliably and avoid flaky git-related tests. No product code changes.

  • Adds “Cursor Cloud specific instructions” covering:
    • Runtime: bun (installed at ~/.bun/bin/bun, symlinked into PATH) and playwright@1.62.1 Chromium cache at ~/.cache/ms-playwright with the reinstall command.
    • Authoritative commands: bun run build, bun run test, bun run slop; removes stale script references and points to package.json as source of truth.
    • How to run the CLI daemons (browse auto-starts headless Chromium; make-pdf shells out to it) and output path restrictions (/tmp or /workspace).
    • Test flake mitigation: the VM’s global git config enables SSH signing and fsmonitor, which stalls git commit in tests; run with GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null bun run test for clean runs.