feat(ci): add Claude workflows and project documentation

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- What does this PR do and why? 1–3 sentences. -->
+
+> PR title must follow Conventional Commits, e.g. `feat(auth): short description`.
+> See https://www.conventionalcommits.org
+
+## Changes
+
+-
+
+## Testing
+
+<!-- How was this verified? Commands run, manual steps, screenshots. -->
+
+- [ ] `yarn lint` passes
+- [ ] `yarn typecheck` passes
+- [ ] `yarn prepare` (library build) succeeds
+- [ ] Native layer unchanged **or** manually verified on device/simulator
+- [ ] `API.md` updated if public exports changed
+
+## Related
+
+<!-- Linked issues or follow-ups. e.g. Closes #123 -->

.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  # Root package (library + workspaces)
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+
+  # Expo example (standalone npm project)
+  - package-ecosystem: npm
+    directory: /examples/expo-example
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 3
+    labels:
+      - dependencies
+
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - ci

.github/workflows/ci.yml

@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - master
+  pull_request:
   workflow_dispatch:
 
 concurrency:

.github/workflows/claude-code-review.yml

@@ -0,0 +1,34 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+  id-token: write
+
+jobs:
+  review:
+    if: github.event.pull_request.user.login != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Claude Code Review
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_GITHUB_ACTIONS }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          direct_prompt: |
+            Review this pull request. Focus on:
+            - Correctness of the TypeScript API surface changes
+            - Whether API.md is updated if src/index.tsx exports changed
+            - Native layer consistency (android/ and ios/ should change together)
+            - Conventional Commits format on the PR title
+            - Any obvious bugs, type errors, or missing edge cases
+          use_sticky_comment: true

.github/workflows/claude.yml

@@ -0,0 +1,37 @@
+name: Claude
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened]
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  id-token: write
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_GITHUB_ACTIONS }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -0,0 +1,164 @@
+# AGENTS.md
+
+Single source of truth for agents working in this repo. `CLAUDE.md` imports this file via
+`@AGENTS.md`, so Claude Code, Codex, and any other agent that reads `AGENTS.md` share the same
+instructions.
+
+---
+
+## Behavioral Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes. (Adapted from Andrej Karpathy's
+[CLAUDE.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md).)
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+### 1. Think Before Coding
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 2. Simplicity First
+**Minimum code that solves the problem. Nothing speculative.**
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+**Touch only what you must. Clean up only your own mess.**
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- Remove imports/variables YOUR changes made unused; leave pre-existing dead code unless asked.
+
+The test: every changed line should trace directly to the request.
+
+### 4. Goal-Driven Execution
+**Define success criteria. Loop until verified.**
+- "Add validation" → "Write tests for invalid inputs, then make them pass."
+- "Fix the bug" → "Write a test that reproduces it, then make it pass."
+
+For multi-step tasks, state a brief plan with a verify step for each item.
+
+---
+
+## Third-Party Library Docs
+
+For **any third-party library**, use the **context7** MCP to fetch up-to-date documentation rather
+than relying on training data, which lags real library APIs. If the context7 MCP server is not
+available, set it up: https://context7.com/install
+
+Key libraries in this repo to pull docs for: `react-native`, `react-native-builder-bob`, `turbo`,
+`@0xtrails/api`, `@0xtrails/wallet`, `0xtrails`.
+
+---
+
+## Project Overview
+
+`@0xsequence/oms-react-native-sdk` is a React Native SDK (Turbo Module) for the OMS platform,
+bridging native iOS (Swift) and Android (Kotlin) SDKs to TypeScript. It exposes wallet auth (email
+OTP, OIDC redirect), transaction signing, balance queries, and session management to React Native
+and Expo apps.
+
+## Repository Structure
+
+- `src/` — TypeScript public API and native module bindings
+- `lib/` — built output (CommonJS, ESM, TypeScript declarations); generated by `yarn prepare`
+- `android/` — Kotlin native module
+- `ios/` — ObjC/Swift native module
+- `examples/sdk-example/` — React Native CLI example app
+- `examples/trails-actions-example/` — Trails demo with redirect auth
+- `examples/expo-example/` — standalone Expo example (not in Yarn workspace; uses `npm`)
+- `.github/workflows/` — CI (lint, typecheck, Android + iOS builds)
+
+## Tech Stack
+
+- **Language:** TypeScript (React Native Turbo Module; native layers in Kotlin + Objective-C/Swift)
+- **Package manager:** Yarn 4 (Berry) with workspaces; `examples/expo-example` uses `npm` standalone
+- **Build tool:** `react-native-builder-bob` + Turbo
+- **Linting:** ESLint 9 flat config + Prettier
+- **Node version:** v24.13.0 (see `.nvmrc`)
+
+## Build & Run
+
+```bash
+# Install dependencies
+yarn install
+
+# Build the library
+yarn prepare
+
+# Typecheck
+yarn typecheck
+
+# Lint
+yarn lint
+
+# Run SDK example (React Native CLI)
+yarn sdk-example start
+
+# Run Expo example (standalone — uses npm, not yarn workspace)
+cd examples/expo-example && npm install && npm start
+```
+
+## Testing
+
+See **[TESTING.md](./TESTING.md)** for testing conventions, manual verification checklist, and the
+plan for when automated tests are added.
+
+## Documentation
+
+`API.md` at the repo root documents the full public TypeScript API for consumers.
+
+## Conventions
+
+- Commit messages and PR titles follow [Conventional Commits](https://www.conventionalcommits.org),
+  e.g. `feat(auth): add OIDC refresh token support`.
+- The public API surface is documented in `API.md` — update it whenever `src/index.tsx` exports
+  change.
+- The `lib/` directory is generated; never edit it by hand.
+- `examples/expo-example` is intentionally outside the Yarn workspace (`!examples/expo-example` in
+  `package.json#workspaces`) — install its deps with `npm`, not `yarn`.
+- Native builds (Android/iOS) are slow; validate JS-layer changes with `yarn lint && yarn typecheck`
+  first; leave full native builds to CI.
+- The `resolutions` block in `package.json` pins `0xtrails` / `@0xtrails/*` — update all three
+  entries together when bumping the trails version.
+- Pre-release versions use the `0.x.y-alpha.N` scheme. Publishing steps are in `README.md`.
+
+## CI/CD
+
+Two workflows in `.github/workflows/`:
+- **`ci.yml`** — runs on pull requests, workflow dispatch, and pushes to `master`: lint, typecheck,
+  library build, Android build, iOS build.
+- **`quick-checks.yml`** — runs on push to non-master branches: lint + typecheck only.
+
+Pull requests run full CI, including native builds. If the native layer changed, make sure the
+Android and iOS PR checks pass before merging; validate locally when you need faster feedback.
+
+## Common Pitfalls
+
+- Running `yarn` inside `examples/expo-example` will fail — it's not a Yarn workspace member. Use
+  `npm` there, or `yarn expo-example <script>` from the root.
+- `yarn prepare` regenerates `lib/` — if builds look stale, run `yarn clean && yarn prepare`.
+- The podspec resolves `oms-client-swift-sdk` and the Android module resolves
+  `io.github.0xsequence:oms-client-kotlin-sdk` — bump native SDK versions in the podspec and
+  `android/build.gradle` together.
+- Turbo cache can mask failures: if something seems wrong, run with `--force` to skip the cache.
+- Signed commits are required (enforced by branch protection) — configure `git commit -S` locally.
+
+## Maintenance Matrix
+
+| When this changes…                        | Also update…                                              |
+|-------------------------------------------|-----------------------------------------------------------|
+| `src/index.tsx` exports                   | `API.md`, `lib/` (run `yarn prepare`)                     |
+| Native SDK version (Swift / Kotlin)       | `OmsClientReactNativeSdk.podspec`, `android/build.gradle` |
+| `package.json` scripts or test commands   | `TESTING.md`, `.github/workflows/ci.yml`                  |
+| Node version (`.nvmrc`)                   | `turbo.json#globalDependencies`, CI setup action          |
+| `resolutions` (`0xtrails` / `@0xtrails/*`)| All three resolution entries together                     |
+| Repo structure (new top-level dirs)       | `AGENTS.md` structure section                             |
+| Contributing workflow                     | `CONTRIBUTING.md`, `README.md`                            |

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@0xsequence/oms-react-native-sdk` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0-alpha.1] — 2025-05-27
+
+### Added
+- Initial alpha release of `@0xsequence/oms-react-native-sdk` (renamed from `oms-client-react-native-sdk`).
+- TypeScript public API: `configure`, `startEmailAuth`, `completeEmailAuth`, `startOidcRedirectAuth`,
+  `handleOidcRedirectCallback`, `getWalletAddress`, `signMessage`, `sendTransaction`,
+  `getTokenBalances`, `formatUnits`, `parseUnits`.
+- React Native Turbo Module bridging iOS (Swift `oms-client-swift-sdk`) and Android (Kotlin
+  `oms-client-kotlin-sdk`).
+- SDK example app, Trails actions demo (with redirect auth + pagination), and standalone Expo
+  example.
+- GitHub Actions CI: lint, typecheck, Android build, iOS build.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+## Prerequisites
+
+- Node.js v24.13.0 (use `.nvmrc` — `nvm use` or `fnm use`)
+- Yarn 4 (`corepack enable` then `yarn --version`)
+- For Android builds: Android SDK, `ANDROID_HOME` set
+- For iOS builds: Xcode, CocoaPods, Ruby (`bundle install` inside the example)
+
+## Setup
+
+```bash
+git clone https://github.com/0xsequence/react-native-sdk.git
+cd react-native-sdk
+yarn install
+yarn prepare        # build lib/
+```
+
+## Repo structure
+
+| Path | Purpose |
+|---|---|
+| `src/` | TypeScript public API and Turbo Module bindings |
+| `lib/` | Built output — generated, do not edit directly |
+| `android/` | Kotlin native module |
+| `ios/` | ObjC/Swift native module |
+| `examples/sdk-example/` | React Native CLI example (Yarn workspace) |
+| `examples/trails-actions-example/` | Trails demo (Yarn workspace) |
+| `examples/expo-example/` | Expo example — **not** a Yarn workspace; use `npm` here |
+
+## Development workflow
+
+```bash
+yarn lint           # ESLint + Prettier check
+yarn typecheck      # tsc
+yarn prepare        # rebuild lib/ after src/ changes
+
+# Run the SDK example
+yarn sdk-example start
+
+# Run the Expo example (uses npm, not yarn)
+cd examples/expo-example && npm install && npm start
+```
+
+## Before opening a PR
+
+1. `yarn lint && yarn typecheck && yarn prepare` must pass cleanly.
+2. Update `API.md` if you changed public exports in `src/index.tsx`.
+3. Update `TESTING.md` if you added or changed test commands.
+4. If you changed the native layer (`android/`, `ios/`, `.podspec`), note it in the PR and make
+   sure the Android and iOS CI checks pass before merging.
+5. PR title must follow [Conventional Commits](https://www.conventionalcommits.org), e.g. `fix(auth): handle expired OTP correctly`.
+
+## Publishing (alpha)
+
+Publishing steps are documented in `README.md` under the alpha publishing section. Only maintainers
+with npm publish access should publish.
+
+## Signed commits
+
+This repo requires signed commits. Configure `gpg` or SSH signing in your local git config before
+contributing.