diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..7de35d12
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,57 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `src/` — TypeScript API and types (`functions.ts`, `Storage.ts`, `types.ts`).
+- `cpp/` — C++ JSI core and bundled SQLite sources; runs on iOS/Android.
+- `android/` — Kotlin TurboModule + JNI glue (`CMakeLists.txt`, `*.kt`).
+- `ios/` — Objective‑C++ TurboModule (`OPSQLite.mm`) and `.xcframework` assets.
+- `c_sources/` — optional SQLite tokenizers/extensions compiled into the binary.
+- `example/` — React Native demo for local testing (iOS/Android).
+- `lib/` — build output (generated by `bob`); do not commit.
+
+## Build, Test, and Development Commands
+
+- Prereqs: Node 20 (`.nvmrc`), Yarn 4 (`yarn.lock`), Ruby for iOS pods.
+- Install deps: `yarn install`
+- Type check TS: `yarn typecheck`
+- Build JS outputs: `yarn prepare` (runs `bob build` → `lib/`)
+- Format native C/C++: `yarn clang-format-check`
+- Example app:
+  - Install pods: `yarn pods` (runs in `example/`)
+  - iOS run: `cd example && yarn ios`
+  - Android run: `cd example && yarn android` (or `yarn build:android`)
+
+## Coding Style & Naming Conventions
+
+- TypeScript: Prettier enforced via `package.json` (single quotes, 2‑space
+  indent, trailing commas `es5`). Use camelCase for variables/functions;
+  PascalCase for types/classes. Keep strict typing; fix unused vars/params.
+- C/C++: `.clang-format` (LLVM style, 4‑space indent). Run
+  `yarn clang-format-check` before pushing.
+- Kotlin/Obj‑C(++): Follow platform conventions and keep methods focused and
+  small.
+
+## Testing Guidelines
+
+- No Jest configured. Validate changes with the `example/` app. Add minimal,
+  reproducible flows under `example/src` when fixing bugs or adding features.
+- Verify both platforms build cleanly. Always run `yarn typecheck` and a local
+  `yarn prepare` before opening a PR.
+
+## Commit & Pull Request Guidelines
+
+- Commits: clear, imperative messages. Conventional prefixes encouraged
+  (`feat:`, `fix:`, `docs:`, `chore:`) with optional scope (`android`, `ios`,
+  `cpp`, `ts`).
+- PRs: include a summary, motivation, test steps (iOS/Android), linked issues,
+  and any performance notes/screenshots or logs.
+- Hygiene: do not commit `lib/`, `example/ios/Pods/`, or build artifacts. Ensure
+  `yarn prepare` succeeds locally.
+
+## Architecture Notes
+
+- JSI TurboModule: `src/` exposes the public API; native JSI lives in `cpp/`,
+  bridged via `android/` (JNI/Kotlin) and `ios/` (Obj‑C++). Feature flags (FTS5,
+  RTree, SQLCipher, libsql) for the demo are configured in
+  `example/package.json` under `op-sqlite`.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file