diff --git a/.cursor/rules/cloud-agent.mdc b/.cursor/rules/cloud-agent.mdc
new file mode 100644
index 0000000..f4c2bf4
--- /dev/null
+++ b/.cursor/rules/cloud-agent.mdc
@@ -0,0 +1,12 @@
+---
+description: Cursor Cloud Agent environment details for Trolley Ruby SDK
+globs:
+alwaysApply: true
+---
+
+# Cloud Agent environment
+
+- Ruby 3.2.2 is installed at `/usr/local/bin/ruby`.
+- Sandbox API credentials are available as env vars `SANDBOX_API_KEY` and `SANDBOX_SECRET_KEY` (injected via Cursor Secrets).
+- Write them to `.env` before running live integration tests: `cp .env.template .env` then replace the fake values with `$SANDBOX_API_KEY` / `$SANDBOX_SECRET_KEY`.
+- VCR cassette playback works with fake keys — no secrets needed for `bundle exec rake`.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b6bafba
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,29 @@
+# AGENTS.md
+
+Ruby SDK for the [Trolley](https://trolley.com) payments API. Pure gem — no databases or background services.
+
+## Development
+
+Requires Ruby 3.2.2 (see `.ruby-version`). Setup and test commands are in `CONTRIBUTING.md`. Quick reference:
+
+```
+bundle install                        # install deps
+bundle exec rubocop                   # lint
+bundle exec rake unit_tests           # unit tests only
+bundle exec rake integration_tests    # integration tests only
+bundle exec rake                      # all tests
+gem build trolley.gemspec             # build gem
+```
+
+## Testing without API keys
+
+Integration tests use VCR cassettes (`test/fixtures/`). Copy `.env.template` to `.env` — the fake keys are sufficient for cassette playback. No live API access is needed to run the full test suite.
+
+## Testing with live API
+
+To re-record cassettes or test against the sandbox, add real credentials from [developers.trolley.com](https://developers.trolley.com) to `.env`:
+
+```
+SANDBOX_API_KEY=<your access key>
+SANDBOX_SECRET_KEY=<your secret key>
+```
diff --git a/Gemfile.lock b/Gemfile.lock
index 23b57fb..873b24a 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -11,6 +11,7 @@ GEM
     ast (2.4.2)
     crack (0.4.5)
       rexml
+    docile (1.4.1)
     dotenv (2.8.1)
     hashdiff (1.0.1)
     json (2.6.3)
@@ -36,6 +37,12 @@ GEM
     rubocop-ast (1.28.0)
       parser (>= 3.2.1.0)
     ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
     test-unit (3.5.7)
       power_assert
     unicode-display_width (2.4.2)
@@ -52,6 +59,7 @@ DEPENDENCIES
   dotenv (~> 2)
   rake (~> 13)
   rubocop (~> 1)
+  simplecov (~> 0.22)
   test-unit (~> 3)
   trolley!
   vcr (~> 6.2)