diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..64b738c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini CLI) working in
+this repository. Keep it concise; it is loaded into agent context automatically.
+
+## Overview
+
+This repo contains `USDCFlow`, a Cadence fungible-token contract that implements Circle's
+Bridged USDC Standard on Flow. The single contract (`contracts/USDCFlow.cdc`) conforms to
+`FungibleToken` and `ViewResolver` and integrates with the Flow VM bridge via
+`FlowEVMBridgeHandlerInterfaces` — it is the Cadence-side representation of Flow EVM USDC
+(itself bridged from Ethereum mainnet USDC). It is deployed to mainnet
+(`0xf1ab99c82dee3526`) and testnet (`0x64adf39cbc354fcb`) per `flow.json`.
+
+## Build and Test Commands
+
+All commands run from repo root unless noted.
+
+- `make test` — runs `make generate -C lib/go`, then `make test -C lib/go`, then
+  `flow test --cover --covercode="contracts" tests/*.cdc`.
+- `make ci` — CI entrypoint: `make ci -C lib/go` then the same `flow test` invocation.
+  Used by `.github/workflows/ci.yml` (Go 1.22, installs Flow CLI via `install.sh`).
+- `flow version` — sanity-check that Flow CLI is installed (README prerequisite).
+- `make generate -C lib/go/contracts` — regenerates `lib/go/contracts/internal/assets/assets.go`
+  from `contracts/**/*.cdc` via `go generate` (go-bindata).
+- `make check-tidy -C lib/go/contracts` — runs `generate` + `go mod tidy` and fails if the
+  working tree diffs (enforces committed generated assets).
+
+There is no deploy make target; use Flow CLI directly against `flow.json` deployments
+(`mainnet-usdc-kms` for mainnet, `testnet-usdc` for testnet).
+
+## Architecture
+
+```
+contracts/
+  USDCFlow.cdc                          # the sole production contract
+  utility/                              # test-only copies of bridge deps
+    FlowEVMBridgeConfig.cdc
+    FlowEVMBridgeHandlerInterfaces.cdc
+    FlowEVMBridgeHandlers.cdc
+transactions/
+  mint.cdc, safe_generic_transfer.cdc, setup_account.cdc
+  scripts/{get_balance,get_supply,get_views}.cdc
+tests/
+  wrapped_fiattoken_test.cdc            # Cadence Test suite
+  test_helpers.cdc                      # deployWithArgs / _executeScript / _executeTransaction
+  transactions/ and scripts/            # Cadence called from the test suite
+lib/go/contracts/                       # Go bindings, embed USDCFlow.cdc via go-bindata
+  contracts.go                          # USDCFlow() and USDCFlowBasic() string builders
+  internal/assets/assets.go             # generated — do not hand-edit
+```
+
+`USDCFlow.cdc` imports `FungibleToken`, `FungibleTokenMetadataViews`, `MetadataViews`,
+`Burner`, `ViewResolver`, and `FlowEVMBridgeHandlerInterfaces`. All six have aliases in
+`flow.json` for `mainnet`, `testnet`, and the `testing` network.
+
+## Conventions and Gotchas
+
+- **Testnet has two deployments.** `flow.json` lists `testnet-usdc-broken`
+  (`0x4516677f8083d680`) alongside the working `testnet-usdc` (`0x64adf39cbc354fcb`).
+  Per README, use `0x64adf39cbc354fcb` on testnet — the original did not migrate properly.
+- **`testing` alias for USDCFlow is `0x0000000000000008`** (not the FT or bridge default).
+  Cadence tests import it at this address — see `tests/wrapped_fiattoken_test.cdc`:
+  `let usdcFlowContractAccount = Test.getAccount(0x0000000000000008)`.
+- **Run `make generate` before Go tests** if `contracts/USDCFlow.cdc` changed. The Makefile
+  does this automatically via `make test`, but direct `go test ./...` will embed stale
+  bytes from `internal/assets/assets.go`.
+- **`USDCFlowBasic` strips the bridge minter.** `lib/go/contracts/contracts.go`'s
+  `USDCFlowBasic` removes the `FlowEVMBridgeHandlerInterfaces` import and rewrites
+  `Minter: FlowEVMBridgeHandlerInterfaces.TokenMinter` → `Minter` with `all` entitlement.
+  Use it only when bridge interfaces are unavailable at the deployment address.
+- **Mainnet deploys via Google KMS.** `mainnet-usdc-kms` in `flow.json` references a KMS
+  resource ID; do not attempt to add a local key for mainnet deploys.
+- **Go module is on Go 1.19** (`lib/go/contracts/go.mod`), but CI uses Go 1.22
+  (`.github/workflows/ci.yml`). Match CI when reproducing failures locally.
+- **Commit style** (`CONTRIBUTING.md`): imperative mood, present tense, first line ≤72 chars.
+
+## Files Not to Modify
+
+- `lib/go/contracts/internal/assets/assets.go` — generated by go-bindata from
+  `contracts/**/*.cdc`; regenerate via `make generate -C lib/go/contracts`.
+- `*.pkey`, `.env`, `coverage.json` — gitignored; never commit.
+- `contracts/utility/*.cdc` — present only to satisfy test imports; the canonical sources
+  live in their upstream repos (FungibleToken standard, flow-evm-bridge).
diff --git a/README.md b/README.md
index 5c55519..ba15141 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Flow Bridged USDC
+# bridged-usdc — Flow Bridged USDC Standard
 
 This repo holds the `USDCFlow` smart contract, the Cadence 
 Fungible Token contract that acts as the Cadence bridged version of
@@ -78,4 +78,13 @@ That will run all the tests in the `tests/` directory.
 
 - [Old `FiatToken` code](https://github.com/flow-usdc/flow-usdc)
 - [Blog Post Announcing Migration from old USDC to new USDC](https://www.flow.com/post/stablecoins-on-flow-evolving-for-interoperability)
-- [Flow VM Bridge Github Repo](https://github.com/onflow/flow-evm-bridge/tree/main)
\ No newline at end of file
+- [Flow VM Bridge Github Repo](https://github.com/onflow/flow-evm-bridge/tree/main)
+
+## About Flow
+
+This repo is part of the [Flow network](https://flow.com), a Layer 1 blockchain built for consumer applications, AI agents, and DeFi at scale.
+
+- Developer docs: https://developers.flow.com
+- Cadence language: https://cadence-lang.org
+- Community: [Flow Discord](https://discord.gg/flow) · [Flow Forum](https://forum.flow.com)
+- Governance: [Flow Improvement Proposals](https://github.com/onflow/flips)