docs(okf): agent knowledge kernel for the GMA refactor

.agents/.gitignore

@@ -0,0 +1,2 @@
+reports
+work-queues

AGENTS.md

@@ -0,0 +1,12 @@
+# React Native Google Mobile Ads — agents
+
+`src/` → `lib/` via `yarn prepare`. Native `android/` `ios/`. Expo `plugin/`. Example `RNGoogleMobileAdsExample/`. E2e `e2e/`. Docs `docs/`. Contributor/review norms: `CONTRIBUTING.md`.
+
+Root `yarn`. Shell: [agent-command-policy](okf-bundle/testing/agent-command-policy.md) only. E2e: [running-e2e § agent rule](okf-bundle/testing/running-e2e.md#agent-rule-read-first) and [platform coverage](okf-bundle/testing/running-e2e.md#platform-coverage-gate-blocking). A green e2e workflow is **not** a pass ([continue-on-error](okf-bundle/ci-workflows/index.md#e2e-continue-on-error)); use local counts + `/tmp/rngma-e2e-*.log`. Loop: [change-authoring](okf-bundle/testing/change-authoring-workflow.md#loop) (`documentation?` then frozen [OKF scan](okf-bundle/testing/validation-checklist.md#okf-bundle-review) when `okf-bundle/`, `AGENTS.md`, or `CONTRIBUTING.md` changed; freeze: [§ frozen tree](okf-bundle/testing/change-authoring-workflow.md#frozen-tree)). Before commit or push: [validation evidence package](okf-bundle/testing/validation-checklist.md#validation-evidence-package). [Coverage evidence](okf-bundle/testing/coverage-design.md#coverage-evidence-package) only when `src/` **or** `android/` **or** `ios/` **or** `plugin/` TS is in the diff; `app.plugin.js`-only is `n/a` unless `plugin/` TS changed ([§ gates](okf-bundle/testing/change-authoring-workflow.md#gates)). Index: [okf-bundle](okf-bundle/index.md). Testing: [testing/index.md](okf-bundle/testing/index.md). Match work type and validation tier: [iteration vocabulary](okf-bundle/testing/iteration-vocabulary.md).
+
+Follow [documentation-policy § public vs ephemeral vs private](okf-bundle/documentation-policy.md#durable-vs-ephemeral). Do not stage `.agents/work-queues/` or `.agents/reports/`. Do not add queue files under `okf-bundle/`.
+
+## PR instructions
+
+- Scoped PRs. API/behavior change → tests + docs + types in the same PR.
+- PR titles: [documentation-policy § pull requests](okf-bundle/documentation-policy.md#pull-requests) (single-commit title equals that commit's subject; multi-commit PRs use a summary title). Examples: `CONTRIBUTING.md`.

CONTRIBUTING.md

@@ -8,7 +8,7 @@ We welcome any type of contribution, not just code. You can help with;
 - **Docs**: improve reference coverage, add more examples, fix typos or anything else you can spot.
   - At the bottom of every page on our docs site you can click the `Edit this page` button to go to that pages markdown file or view the [documents](https://github.com/invertase/react-native-google-mobile-ads/tree/main/docs) directly
 - **Community**: presenting the project at meetups, organizing a dedicated meetup for the local community, ...
-- **Code**: take a look at the [open issues](issues). Even if you can't write code, commenting on them, showing that you care about a given issue matters.
+- **Code**: take a look at the [open issues](https://github.com/invertase/react-native-google-mobile-ads/issues). Even if you can't write code, commenting on them, showing that you care about a given issue matters.
 
 ## Project Guidelines
 
@@ -26,9 +26,9 @@ We aim to keep all project discussion inside GitHub issues. This is to make sure
 
 This is normal don't worry - not everyone can develop native code for Obj-C and Java, we understand that.
 
-Although we won't merge Pull Requests unless they support all applicable platforms, we do however recommend that you still submit a PR
+Although we won't merge product features that ship on both OS unless they support all applicable platforms, we do however recommend that you still submit a PR
 for the Platform that you do know and then label it as either `Help: iOS` or `Help: Android` (or post a comment requesting it to be labeled).
-This will allow other contributors to help add the missing platform support by making changes to your existing PR.
+This will allow other contributors to help add the missing platform support by making changes to your existing PR. Test and platform expectations: [platform coverage](okf-bundle/testing/running-e2e.md#platform-coverage-gate-blocking).
 
 ### Our expectations on you as a contributor
 
@@ -38,7 +38,7 @@ To quote [@alloy](https://github.com/alloy) from [this issue](https://github.com
 
 We want contributors to provide ideas, keep the ship shipping and to take some of the load from others. It is non-obligatory; we’re here to get things done in an enjoyable way. :trophy:
 
-We do ask though that you follow the conduct guidelines set out in our [Code of Conduct](/CODE_OF_CONDUCT.md) throughout your contribution journey.
+We do ask though that you follow the conduct guidelines set out in our [Code of Conduct](CODE_OF_CONDUCT.md) throughout your contribution journey.
 
 ### What about if you have problems that cannot be discussed in a public issue?
 
@@ -88,14 +88,13 @@ To aid review we also ask that you fill out the PR template as much as possible.
 
 ### Your PR title
 
-We use the [Conventional Commits](https://www.conventionalcommits.org/) format throughout the project. Your Pull Request title should be
-in this format; however your commits themselves do not need to follow this format as all PRs are eventually squash merged.
+Commit subjects and Pull Request titles use [Conventional Commits](https://www.conventionalcommits.org/). Full rules (single-commit title equals that commit's subject; multi-commit PRs use a summary title; squash/amend is a **fix** for a non-conforming subject, not a skip): [OKF documentation policy § pull requests](okf-bundle/documentation-policy.md#pull-requests).
 
 #### Examples
 
 - `docs(consent, ios): added extra example for GDPR flow on iOS`
 - `tests(perf): should throw invalid arg error`
-- `fix(insterstial, android): fixed NPE crash`
+- `fix(interstitial, android): fixed NPE crash`
 - `feat(video): add support for video load timeouts`
 
 See the [Conventional Commits](https://www.conventionalcommits.org/) specification for more information.
@@ -107,17 +106,16 @@ Pull Requests to the `main` branch require one or more peer-review approvals and
 Reviews of Pull Requests are based on the following acceptance criteria:
 
 - Does the PR provide cross-platform support?
-  - i.e. if adding a new feature then does the implementation provide iOS and Android support.
-  - Pull Requests should not be merged unless both platforms are supported (unless the feature is specific to one platform only)
+  - Product features that ship on both platforms need both.
+  - Which platforms and which tests: [platform coverage](okf-bundle/testing/running-e2e.md#platform-coverage-gate-blocking). Lint/evidence: [work types](okf-bundle/testing/validation-checklist.md#work-types) / [gates](okf-bundle/testing/change-authoring-workflow.md#gates). Frozen review: [§ frozen tree](okf-bundle/testing/change-authoring-workflow.md#frozen-tree).
 - If APIs have changed;
   - Has the documentation been updated?
   - Have the TypeScript types been added?
 - Have the tests been updated or new tests been added to test newly implemented or changed functionality.
-  - E2E tests.
-  - Other tests through Jest.
-- Do all CI checks pass.
+  - E2E and Jest when [platform coverage](okf-bundle/testing/running-e2e.md#platform-coverage-gate-blocking) requires them.
+- Do all CI checks pass. A green e2e GitHub Actions job is not an e2e pass — [continue-on-error](okf-bundle/ci-workflows/index.md#e2e-continue-on-error).
 
-Once a PR is merged into the `main` branch; new versions of the changed packages are automatically created and published to NPM.
+Once a PR is merged into the `main` branch, maintainers publish with `workflow_dispatch` — [CI publish](okf-bundle/ci-workflows/index.md#workflows). Push to `main` does not publish.
 
 ## [No Brown M&M's](http://en.wikipedia.org/wiki/Van_Halen#Contract_riders)
 

okf-bundle/architecture-decisions.md

@@ -0,0 +1,35 @@
+---
+type: Reference
+title: Architecture decisions (ADR)
+description: Canonical owner of durable GMA product and tooling decisions.
+tags: [okf, adr]
+timestamp: 2026-08-22T00:00:00Z
+---
+
+# Architecture decisions (ADR)
+
+**Canonical owner** of durable “what + why” decisions for this repo. Procedures and commands live in [testing](testing/index.md). Do not duplicate these decisions in work queues. Queues stay under `.agents/work-queues/` (gitignored).
+
+**Policy:** [OKF documentation policy](documentation-policy.md).
+
+## Decision ID convention
+
+Cite decisions as **`GMA-AD-<n>`**.
+
+## Status legend
+
+| Status | Meaning |
+|--------|---------|
+| **Accepted** | Decided; follow this. |
+| **Proposed** | Planned; not yet the rule. |
+| **Rejected** | Considered and declined; keep so it is not re-litigated. |
+
+Add rows when a refactor choice lands (module boundaries, codegen, plugin behavior, native backend). Do not paste decisions from other repos.
+
+<a id="gma-ad-1"></a>
+
+## GMA-AD-1 — Expo config plugin is a separate validation path — **Accepted**
+
+The Expo config plugin under `plugin/` is a **separate validation path**: Metro/Expo consume compiled plugin output, not `plugin/src/`. Native e2e does not cover plugin JS/config by itself.
+
+Commands: [validation checklist § Expo plugin](testing/validation-checklist.md#expo-plugin) (root Jest is the gate). When to run e2e vs plugin Jest: [running e2e § platform coverage](testing/running-e2e.md#platform-coverage-gate-blocking).

okf-bundle/ci-workflows/index.md

@@ -0,0 +1,38 @@
+# CI workflows
+
+GitHub Actions job shape and artifact triage for **this** repo. Commands: [agent command policy](../testing/agent-command-policy.md). E2e names: [local e2e](../testing/running-e2e.md#local-e2e-commands). Which e2e to run: [platform coverage](../testing/running-e2e.md#platform-coverage-gate-blocking).
+
+Do not copy other repos’ Detox patch inventories, macOS-app e2e suites, Jacoco merge, or emulator-cloud quota notes.
+
+<a id="workflows"></a>
+
+## Workflows
+
+| Workflow | File | Local equivalent | Artifacts / notes |
+|----------|------|------------------|-------------------|
+| Jest | [`.github/workflows/tests_jest.yml`](../../.github/workflows/tests_jest.yml) | `yarn tests:jest-coverage` | Codecov upload |
+| E2e Android | [`.github/workflows/tests_e2e_android.yml`](../../.github/workflows/tests_e2e_android.yml) | [platform coverage](../testing/running-e2e.md#platform-coverage-gate-blocking) + [named scripts](../testing/running-e2e.md#local-e2e-commands) | `adb_logs`; Codecov; Metro prefetch on `:8081`. **Run Emulator Tests**: [continue-on-error](#e2e-continue-on-error) |
+| E2e iOS | [`.github/workflows/tests_e2e_ios.yml`](../../.github/workflows/tests_e2e_ios.yml) | [platform coverage](../testing/running-e2e.md#platform-coverage-gate-blocking) + [named scripts](../testing/running-e2e.md#local-e2e-commands) | `simulator_log`; Codecov; Metro prefetch on `:8081`. **Build and Run e2e app** and **Create Simulator Log**: [continue-on-error](#e2e-continue-on-error) |
+| Lint | [`.github/workflows/linting.yml`](../../.github/workflows/linting.yml) | [lint-by-tree](../testing/validation-checklist.md#lint-and-formatting) | CI always runs `yarn lint:code`; local agents do not copy that unless `src/` **and** `android/` **and** `ios/` changed. Also `yarn tsc:compile`. `eslint-report.json` |
+| Docs | [`.github/workflows/docs.yml`](../../.github/workflows/docs.yml) | `yarn lint:spellcheck` | Job title mentions Markdown; CI is spellcheck only — [§ lint](../testing/validation-checklist.md#lint-and-formatting) |
+| PR title | [`.github/workflows/pr_title.yml`](../../.github/workflows/pr_title.yml) | [documentation-policy § pull requests](../documentation-policy.md#pull-requests) | Conventional Commits; `validateSingleCommit` |
+| Test patches | [`.github/workflows/create_test_patches.yml`](../../.github/workflows/create_test_patches.yml) | Do not invent a local substitute | `workflow_dispatch` + push/PR; patch-package artifacts |
+| Publish | [`.github/workflows/publish.yml`](../../.github/workflows/publish.yml) | Maintainers only | `on.push` exists; the job `if` runs only on `workflow_dispatch`. Push to `main` does not publish. |
+| Stale | [`.github/workflows/stale.yml`](../../.github/workflows/stale.yml) | n/a | Scheduled issue/PR stale bot |
+
+Jest/e2e/patch workflows `paths-ignore` markdown and `docs/**` (YAML also lists `website/**`; that tree is not in this repo — ignore it). Lint runs on markdown PRs and pushes to `main`. Docs spellcheck is PR-only.
+
+<a id="e2e-continue-on-error"></a>
+
+## E2e continue-on-error
+
+`continue-on-error: true` is on Android **Run Emulator Tests** and iOS **Build and Run e2e app**. iOS **Create Simulator Log** also sets it; that step is log capture, not the e2e pass signal. A green workflow is **not** an e2e pass. Pass signal: local counts + `/tmp/rngma-e2e-*.log`, or triaged `simulator_log` / `adb_logs`.
+
+<a id="triage"></a>
+
+## Triage
+
+- iOS e2e failure: download `simulator_log`, then local `/tmp/rngma-e2e-ios.log`.
+- Android e2e failure: download `adb_logs`, then local `/tmp/rngma-e2e-android.log`.
+- Packager never healthy: Metro must be **this** checkout on `:8081` — [running e2e § pre-flight](../testing/running-e2e.md#pre-flight).
+- Grow platform pages here only after a failure mode is verified on **this** repo.