docs: add AGENTS.md with contribution and development guidelines

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: riderx

AGENTS.md

@@ -0,0 +1,125 @@
+# AGENTS.md
+
+This file provides guidance to AI agents and contributors working on this Capacitor plugin.
+
+## Quick Start
+
+```bash
+# Install dependencies
+bun install
+
+# Build the plugin (TypeScript + Rollup + docgen)
+bun run build
+
+# Full verification (iOS, Android, Web)
+bun run verify
+
+# Format code (ESLint + Prettier + SwiftLint)
+bun run fmt
+
+# Lint without fixing
+bun run lint
+```
+
+## Development Workflow
+
+1. **Install** - `bun install` (never use npm)
+2. **Build** - `bun run build` compiles TypeScript, generates docs, and bundles with Rollup
+3. **Verify** - `bun run verify` builds for iOS, Android, and Web. Always run this before submitting work
+4. **Format** - `bun run fmt` auto-fixes ESLint, Prettier, and SwiftLint issues
+5. **Lint** - `bun run lint` checks code quality without modifying files
+
+### Individual Platform Verification
+
+```bash
+bun run verify:ios
+bun run verify:android
+bun run verify:web
+```
+
+### Example App
+
+If an `example-app/` directory exists, you can test the plugin locally:
+
+```bash
+cd example-app
+bun install
+bun run start
+```
+
+The example app references the plugin via `file:..`. Use `bunx cap sync <platform>` to sync native platforms.
+
+## Project Structure
+
+- `src/definitions.ts` - TypeScript interfaces and types (source of truth for API docs)
+- `src/index.ts` - Plugin registration
+- `src/web.ts` - Web implementation
+- `ios/Sources/` - iOS native code (Swift)
+- `android/src/main/` - Android native code (Java/Kotlin)
+- `dist/` - Generated output (do not edit manually)
+- `Package.swift` - SwiftPM definition
+- `*.podspec` - CocoaPods spec
+
+## iOS Package Management
+
+We always support both **CocoaPods** and **Swift Package Manager (SPM)**. Every plugin must ship a valid `*.podspec` and `Package.swift`. Do not remove or break either integration — users depend on both.
+
+## API Documentation
+
+API docs in the README are auto-generated from JSDoc in `src/definitions.ts`. **Never edit the `<docgen-index>` or `<docgen-api>` sections in README.md directly.** Instead, update `src/definitions.ts` and run `bun run docgen` (also runs as part of `bun run build`).
+
+## Versioning
+
+The plugin major version follows the Capacitor major version (e.g., plugin v8 for Capacitor 8). **We only ship breaking changes when a new Capacitor native major version is released.** All other changes must be backward compatible.
+
+## Changelog
+
+`CHANGELOG.md` is managed automatically by CI/CD. Do not edit it manually.
+
+## Pull Request Guidelines
+
+We welcome contributions, including AI-generated pull requests. Every PR must include:
+
+### Required Sections
+
+1. **What** - What does this PR change?
+2. **Why** - What is the reason for this change?
+3. **How** - How did you approach the implementation?
+4. **Testing** - What did you test? How did you verify it works?
+5. **Not Tested** - What is not yet tested or needs further validation?
+
+### Rules
+
+- **No breaking changes** unless aligned with a new Capacitor major release.
+- Run `bun run verify` and `bun run fmt` before opening a PR. CI will catch failures, but catching them locally saves time.
+- If you are an AI agent, that is perfectly fine. Just be transparent about it. We care that the code is correct and helpful, not who wrote it.
+- We review PRs on a best-effort basis. We may request changes — you are expected to address them for the PR to be merged.
+- We use automated code review tools (CodeRabbit, and others). You will need to respond to their feedback and resolve any issues they raise.
+- We have automatic releases. Once merged, your change will ship in the next release cycle.
+
+### PR Template
+
+```
+## What
+- [Brief description of the change]
+
+## Why
+- [Motivation for this change]
+
+## How
+- [Implementation approach]
+
+## Testing
+- [What was tested and how]
+
+## Not Tested
+- [What still needs testing, if anything]
+```
+
+## Common Pitfalls
+
+- Always rename Swift/Java classes and package IDs when creating a new plugin from a template — leftover names cause registration conflicts.
+- We only use Java 21 for Android builds.
+- Keep temporary files clean: delete or mark with `deleteOnExit` after use.
+- `dist/` is fully regenerated on every build — never edit generated files.
+- Use Bun for everything. Do not use npm or npx. Use `bunx` if you need to run a package binary.