docs: add AGENTS.md

Adds the AGENTS.md open-standard file for AI coding agents (agents.md).
Every claim evidence-backed against Makefile, package.json, source tree,
or equivalent manifest. Zero fabrication.

Author: Aliserag

AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents (Claude Code, Codex, Cursor, Copilot, and others)
+working in this repository. It is loaded into agent context automatically — keep it concise.
+
+## Overview
+
+`github.com/onflow/flow-go-sdk` is the reference Go SDK for the Flow blockchain. It provides
+client packages for the Flow Access API over gRPC and HTTP, Cadence-aware transaction and
+script helpers, ECDSA/BLS crypto primitives, and account-creation templates. The module is
+compatible with the Flow Emulator for local development.
+
+## Build and Test Commands
+
+Targets from the root `Makefile`:
+
+- `make test` — full test suite with coverage (writes `coverage.txt`). Sets `CGO_CFLAGS` via `crypto_adx_flag.mk`.
+- `make coverage` — runs `test`, then `go tool cover -html=coverage.txt`.
+- `make generate` — installs `mockery v2.53.5` and runs `go generate ./...` to regenerate mocks.
+- `make check-tidy` — runs `generate`, then `go mod tidy`, then fails if the working tree is dirty.
+- `make check-headers` — runs `./check-headers.sh`; fails if any `.go` file is missing the Apache-2.0 header.
+- `make ci` — full CI pipeline: `check-tidy` + `test` + `coverage`. Matches `.github/workflows/ci.yml`.
+- `make generate-openapi` — regenerates `access/http/models/` from the upstream Flow OpenAPI spec (requires `swagger-codegen`).
+
+Examples live in a separate Go module under `examples/` with its own `Makefile`. Run via
+`make -C examples <target>` (e.g. `make -C examples send-transactions`). Examples require
+a running Flow Emulator — see `examples/README.md`.
+
+## Architecture
+
+- Root package `flow` — core domain types: `Account`, `Transaction`, `Block`, `Event`, `Collection`, `Address`.
+- `access/` — `Client` interface (the primary SDK surface). Two implementations:
+  - `access/grpc/` — gRPC client (`grpc.NewClient`, `grpc.MainnetHost`, `grpc.TestnetHost`, `grpc.EmulatorHost`). Recommended transport per README.
+  - `access/http/` — REST client. `access/http/models/` is generated from OpenAPI.
+- `crypto/` — key generation, signing, hashing. `crypto/awskms/` and `crypto/cloudkms/` provide AWS KMS and Google Cloud KMS signers.
+- `templates/` — prebuilt Cadence transactions for account creation and key management.
+- `test/` — test fixtures (`entities.go`, `greetings.go`, `signer.go`).
+- `client/` — **deprecated**; re-exports `access/grpc`. New code should import `access/grpc` directly (see `client/client.go` doc comment).
+- `examples/` — runnable end-to-end examples against the Flow Emulator. Separate Go module with a `replace` directive back to the SDK root (`examples/go.mod`).
+
+## Conventions and Gotchas
+
+- **Go 1.25.0** required (`go.mod`). CI pins `go-version: '1.25'` in `.github/workflows/ci.yml`.
+- **CGO is required by default** for BLS support (via `github.com/onflow/crypto`). Build with `CGO_ENABLED=1`. You can build with `CGO_ENABLED=0` but must also pass the `no-cgo` build tag; any BLS call will then panic at runtime (README: Installing).
+- **ADX instructions**: `crypto_adx_flag.mk` detects CPU support and sets `CRYPTO_FLAG` for BLST. Always invoke via the `Makefile` (not raw `go test`) to pick up the flag on older machines.
+- **Regenerate mocks after interface changes**: run `make generate` whenever you touch `access.Client`, `access/grpc.RPCClient`, `access/grpc.ExecutionDataRPCClient`, or `access/http.handler` — `go:generate` directives in those files drive `mockery`. `make check-tidy` fails CI if generated output is not committed.
+- **Apache-2.0 license header required** on every `.go` file — enforced by `check-headers.sh` in CI.
+- **Do not edit `client/`** — deprecated shim retained for backward compatibility.
+- `CONTRIBUTING.md` mentions `make lint` — **no such target exists** in the Makefile. Use `gofmt` and `go vet` directly.
+- When writing portable code, depend on the `access.Client` interface so callers can swap gRPC/HTTP; reach for `grpc.BaseClient` / `http.BaseClient` only when transport-specific options are needed (`access/README.md`).
+
+## Files Not to Modify
+
+- `access/http/models/*.go` — generated by `swagger-codegen` via `make generate-openapi`.
+- `access/grpc/mocks/*.go`, `access/mocks/Client.go`, `access/http/mock_handler.go` — generated by `mockery` via `make generate`.
+- `client/client.go` — deprecated shim.
+- `go.sum` — managed by `go mod`.