docs(agents): Cursor Cloud dev environment setup notes

[time-attack]

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 "memory-ingest renders all Codex rollout sessions as empty bodies (parser expects payload.message; current format is payload.type=='message' + payload.content) garrytan/gstack#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.}

  

---

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.

^{Written for commit 848feec. Summary will update on new commits.}