[Armaxis]

Integrators increasingly build against Mobile Payments SDK with coding agents, and none of the four public SDK repos carries agent-readable integration guidance. This repo is the exception that proves the point: it already had a CLAUDE.md, but it targets contributors to the wrapper — yarn commands, bob build, the bridge architecture, the mapper files. None of that helps someone consuming the package from npm, which is who almost everyone pointing an agent at this repo actually is.

Ironically, that contributor file held exactly the tribal knowledge integrators burn iterations rediscovering, buried in a "Platform Constraints" bullet list: Proguard must be disabled, and React Native 0.75.x needs a patch-package workaround for Kotlin 2.2.x. Undocumented constraints like these cost agents entire iterations — the Android release build compiles fine and then fails at runtime once R8 has stripped bytecode the SDK loads reflectively. Both are now first-class sections with the reasoning and the failure mode spelled out.

What happened to the existing CLAUDE.md

Not deleted — it's the only written record of how the bridge fits together.

• CLAUDE.md → CONTRIBUTING_AGENTS.md, contents preserved, with a new header naming its audience and pointing integrators at AGENTS.md. It sits next to CONTRIBUTING.md, which serves the same audience for humans
• New AGENTS.md for integrators
• CLAUDE.md is now a symlink to AGENTS.md

So an agent that only knows the filename CLAUDE.md lands on the integrator doc by default — the right guess for the common case — with the contributor doc one clearly-labelled link away. Happy to rename CONTRIBUTING_AGENTS.md if there's a preferred convention.

Contents

All verified against this repo or the published packages:

• npm install, current version (2026.8.1), and the native SDKs it wraps (iOS 2.6.0 / Android 2.6.1)
• Android minSdk 28 / compileSdk 36, AGP 8.9.1+ / Gradle 8.13+, Kotlin 2.2.21, and the Proguard rule
• The Kotlin 2.2.x patch-package workaround, with the two error strings it fixes and a link to docs/KOTLIN_COMPATIBILITY.md
• iOS deployment target 16, and the setup Run Script phase that has to sit after [CP] Embed Pods Frameworks
• Not compatible with Expo Go
• Which files hold the sandbox credentials, and that the checked-in placeholders stay placeholders. Initialization is native and per-platform; only authorize() is JS
• Required permissions on both platforms
• The ordering rule: initialize → request permissions → authorize(). Any manager call before authorization rejects with NOT_AUTHORIZED
• Mock reader testing in Sandbox, including the current limitation: the wrapper exposes only showMockReaderUI() / hideMockReaderUI() because that's all the native frameworks expose, so simulating a card tap needs a human tapping the floating button. Stated plainly, so an agent asks rather than hangs waiting on a promise
• Links to the per-page docs markdown (…/react-native.md) rather than the HTML pages, which are iframe shells that return only nav to a fetch

Ticket: https://linear.app/squareup/issue/DEVMOB-1289

Sibling PRs are going up against the Android, iOS, and Flutter repos.

🤖 Generated with Claude Code