docs: rewrite README and add AGENTS.md

.github/path-filters.yml

@@ -0,0 +1,37 @@
+# Shared path filters for dorny/paths-filter (see heavy CI workflows).
+# Docs-only / AGENTS.md / README changes must NOT set native or e2e.
+
+native:
+  - android/**
+  - ios/**
+  - index.js
+  - index.d.ts
+  - specs/**
+  - app.plugin.js
+  - RNZipArchive.podspec
+  - babel.config.js
+  - playground-rn/**
+  - playground-expo/**
+  - __mocks__/**
+  - .maestro/**
+  - scripts/e2e-*.sh
+  - e2e/**
+
+interop:
+  - scripts/verify-zip-interop.js
+  - scripts/validate-zip-header.js
+  - scripts/ZipInputStreamCheck.java
+  - scripts/generate-interop-fixtures.py
+  - fixtures/interop/**
+  - package.json
+
+js:
+  - index.js
+  - index.d.ts
+  - __tests__/**
+  - __mocks__/**
+  - package.json
+  - babel.config.js
+  - app.plugin.js
+  - scripts/**
+  - jest.config.*

.github/workflows/android-build.yml

@@ -12,8 +12,26 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: Detect native changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      native: ${{ steps.filter.outputs.native }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Path filter
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: .github/path-filters.yml
+
   build-android:
     name: Build Android (${{ matrix.app }})
+    needs: changes
+    if: ${{ needs.changes.outputs.native == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
     timeout-minutes: 45
     strategy:

.github/workflows/docs-sync.yml

@@ -0,0 +1,33 @@
+name: Docs sync
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs-sync:
+    name: README ↔ AGENTS.md
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+
+      - name: Check docs sync
+        env:
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+        run: bash scripts/check-docs-sync.sh

.github/workflows/e2e.yml

@@ -1,5 +1,4 @@
 name: E2E Tests
-# Test trigger for CI verification
 
 on:
   pull_request:
@@ -13,8 +12,26 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: Detect native changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      native: ${{ steps.filter.outputs.native }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Path filter
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: .github/path-filters.yml
+
   e2e-ios:
     name: E2E iOS (${{ matrix.app }})
+    needs: changes
+    if: ${{ needs.changes.outputs.native == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 60
     strategy:
@@ -145,6 +162,8 @@ jobs:
 
   e2e-android:
     name: E2E Android (${{ matrix.app }})
+    needs: changes
+    if: ${{ needs.changes.outputs.native == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
     timeout-minutes: 60
     strategy:

.github/workflows/ios-build.yml

@@ -12,8 +12,26 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: Detect native changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      native: ${{ steps.filter.outputs.native }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Path filter
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: .github/path-filters.yml
+
   build-ios:
     name: Build iOS (${{ matrix.app }})
+    needs: changes
+    if: ${{ needs.changes.outputs.native == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 45
     strategy:

.github/workflows/js-tests.yml

@@ -0,0 +1,53 @@
+name: JS Tests
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  changes:
+    name: Detect JS changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      js: ${{ steps.filter.outputs.js }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Path filter
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: .github/path-filters.yml
+
+  jest:
+    name: Jest
+    needs: changes
+    if: ${{ needs.changes.outputs.js == 'true' || github.event_name == 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run Jest
+        run: npm test
+
+      - name: Lint
+        run: npm run lint

.github/workflows/old-arch.yml

@@ -19,8 +19,26 @@ env:
   RN_OLD_ARCH_CLI: '15.1.3'
 
 jobs:
+  changes:
+    name: Detect native changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      native: ${{ steps.filter.outputs.native }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Path filter
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: .github/path-filters.yml
+
   compile-android-0-81:
     name: Compile Android old-arch (RN 0.81)
+    needs: changes
+    if: ${{ needs.changes.outputs.native == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
     timeout-minutes: 45
     steps:
@@ -96,6 +114,8 @@ jobs:
 
   compile-ios-0-81:
     name: Compile iOS old-arch (RN 0.81)
+    needs: changes
+    if: ${{ needs.changes.outputs.native == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: macos-15
     timeout-minutes: 45
     steps:

.github/workflows/path-filters.md

@@ -0,0 +1,15 @@
+# CI path filters
+
+Heavy workflows use [`dorny/paths-filter`](https://github.com/dorny/paths-filter) with [`.github/path-filters.yml`](../path-filters.yml):
+
+1. Every push still **starts** the workflow (so `concurrency: cancel-in-progress` can stop an outdated run).
+2. A cheap `changes` job decides whether native/E2E work is needed.
+3. Expensive jobs run only when the matching filter is `true`, or on `workflow_dispatch`.
+
+| Filter | Typical workflows |
+|--------|-------------------|
+| `native` | Android Build, iOS Build, E2E, Old Architecture |
+| `interop` | Zip Interop |
+| `js` | JS Tests (Jest) |
+
+Documentation (`*.md`, `AGENTS.md`, `CLAUDE.md`, docs-sync script, pre-commit) does **not** match `native` / `e2e`. `package.json` alone does not trigger native/E2E (it does trigger JS Tests + Zip Interop). Peer bumps that need a native rebuild should include a native/JS file change, or use **Run workflow**.

.github/workflows/zip-interop.yml

@@ -15,8 +15,26 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  changes:
+    name: Detect interop changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      interop: ${{ steps.filter.outputs.interop }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Path filter
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: .github/path-filters.yml
+
   zip-interop:
     name: Node unzipper + Java ZipInputStream
+    needs: changes
+    if: ${{ needs.changes.outputs.interop == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+# Standard pre-commit hooks: https://pre-commit.com/
+# Install once: pip install pre-commit && pre-commit install
+# Runs the same check as CI (scripts/check-docs-sync.sh).
+repos:
+  - repo: local
+    hooks:
+      - id: docs-sync
+        name: README.md ↔ AGENTS.md sync
+        entry: bash scripts/check-docs-sync.sh
+        language: system
+        pass_filenames: false
+        always_run: true