diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e497aa8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,73 @@
+# AGENTS.md — OneSignal Go SDK
+
+Integration guide for AI agents and LLMs using the OneSignal server SDK for Go. Human-oriented docs are in the [README](./README.md).
+
+## What this SDK does
+
+Server-side access to the OneSignal REST API: send push / email / SMS, manage users, subscriptions, segments, templates and live activities, and administer apps & API keys.
+
+- Module: `github.com/OneSignal/onesignal-go-api/v5`
+- Repository: https://github.com/OneSignal/onesignal-go-api
+
+## Install
+
+```sh
+go get github.com/OneSignal/onesignal-go-api/v5
+```
+
+```go
+import onesignal "github.com/OneSignal/onesignal-go-api/v5"
+```
+
+## Authentication — two key types
+
+OneSignal uses two bearer credentials; each endpoint requires a specific one. In Go you attach the key to the request `context.Context`, then pass that context to the call:
+
+- **REST API key** (`onesignal.RestApiKey`) — used by almost every endpoint (notifications, users, subscriptions, segments, templates, live activities, custom events). Found in **App Settings → Keys & IDs**.
+- **Organization API key** (`onesignal.OrganizationApiKey`) — required *only* for organization-level endpoints: app management (list / create / get / update apps), API-key management (view / create / update / rotate / delete API keys), and copying a template to another app. Found in **Organization Settings**.
+
+Never hard-code keys — read them from environment variables or a secrets manager.
+
+```go
+apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())
+
+// Most endpoints: attach the REST API key.
+restCtx := context.WithValue(context.Background(), onesignal.RestApiKey, os.Getenv("ONESIGNAL_REST_API_KEY"))
+
+// Organization-level endpoints: attach the Organization API key instead.
+orgCtx := context.WithValue(context.Background(), onesignal.OrganizationApiKey, os.Getenv("ONESIGNAL_ORGANIZATION_API_KEY"))
+```
+
+## Calling convention
+
+Calls use the fluent request builder: start with the method (passing the auth context), chain the body, then `.Execute()`.
+
+```go
+notification := onesignal.NewNotification("YOUR_APP_ID")
+contents := onesignal.NewLanguageStringMap()
+contents.SetEn("Hello from OneSignal!")
+notification.SetContents(*contents)
+notification.SetIncludeAliases(map[string][]string{"external_id": {"YOUR_USER_EXTERNAL_ID"}})
+notification.SetTargetChannel("push")
+
+resp, r, err := apiClient.DefaultApi.CreateNotification(restCtx).Notification(*notification).Execute()
+```
+
+## Idempotent sends & retries
+
+Set `idempotency_key` (a UUID) so a create-notification request can be safely retried — the server returns the original result instead of sending twice. The `CreateNotificationWithRetry` helper handles this for you: it generates an `idempotency_key` when absent, retries `429` / `503` / transport errors with the **same** key (honoring `Retry-After`), and reports via `WasReplayed` whether the server answered from a previously completed request.
+
+```go
+opts := &onesignal.CreateNotificationWithRetryOptions{MaxRetries: 5}
+result, err := apiClient.DefaultApi.CreateNotificationWithRetry(restCtx, *notification, opts)
+if err == nil {
+    fmt.Printf("id: %s replayed: %t\n", result.Response.GetId(), result.WasReplayed)
+}
+```
+
+> The notification-level `external_id` field is the **deprecated** idempotency mechanism — prefer `idempotency_key`. Don't confuse it with the `external_id` **alias label** (under `include_aliases`) used to target users.
+
+## Full API reference
+
+- [DefaultApi.md](https://github.com/OneSignal/onesignal-go-api/blob/main/docs/DefaultApi.md) — every endpoint, parameter, and model, with runnable examples.
+- [OneSignal REST API reference](https://documentation.onesignal.com/reference)
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d3f6c39
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+AI agent and LLM integration guidance for this OneSignal server SDK lives in **[AGENTS.md](./AGENTS.md)** — authentication, calling conventions, idempotent retries, and the full API reference.
+
+See [AGENTS.md](./AGENTS.md).
diff --git a/README.md b/README.md
index af2c342..5e30ef0 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 <h1 align="center">Welcome to the official OneSignal Go Client</h1>
 
+> **Building with an AI agent or LLM?** See [AGENTS.md](https://github.com/OneSignal/onesignal-go-api/blob/main/AGENTS.md) for an agent-oriented integration guide — authentication, calling conventions, idempotent retries, and the full API reference.
+
 A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
 - API version: 5.8.0