AGENTS.md git:20260318.896ce92A

Immutable. This exact content never changes and is served at /api/v1/blob/0ad36e3475d54544.

# 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 `npx 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.

Always use NPX in skills never use bunx. NPX will ensure the correct version of the plugin is used in skills, while Bun is for development and CI/CD tasks.
It's allowed to use bun in skills if the skill is about Bun itself, but for any Capacitor-related skill, use NPX to run plugin commands. This ensures compatibility and prevents issues with different Bun versions across environments.

### 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.