diff --git a/.DS_Store b/.DS_Store
deleted file mode 100644
index 1ad899d..0000000
Binary files a/.DS_Store and /dev/null differ
diff --git a/.gitignore b/.gitignore
index 4b2b4ab..2ae702c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 *.gem
+.DS_Store
 *.rbc
 .bundle
 .config
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e429db1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,26 @@
+# Agent Guide
+
+Hyperclient is a Ruby client for JSON HAL APIs, built on Faraday 2 and `faraday_hal_middleware`.
+
+## Layout
+
+- `lib/hyperclient.rb`: client entry point and configuration.
+- `lib/hyperclient/`: resources, links, collections, attributes, and CURIEs.
+- `test/`: Minitest tests and fixtures.
+- `features/`: Spinach acceptance tests and supporting code.
+- `examples/`: runnable usage examples.
+
+## Commands
+
+```sh
+bundle install
+bundle exec rake                 # Minitest, Spinach, and RuboCop
+bundle exec rake test            # Minitest only
+bundle exec rake spinach         # Acceptance tests only
+bundle exec rake rubocop         # Lint
+bundle exec ruby -Itest test/hyperclient_test.rb
+```
+
+## Changes
+
+Follow existing Ruby conventions and preserve Ruby 2.7 compatibility. Add regression tests for behavior changes; use existing HTTP stubs rather than depending on external services. Update the README for public API changes and the changelog with the pull request number. See `CONTRIBUTING.md` for the full contribution workflow and `.github/workflows/` for the CI matrix.