From 2e2eeef24a67491aa12e5ed00a808d80bb41a6bb Mon Sep 17 00:00:00 2001
From: Diego Mello <diegolmello@gmail.com>
Date: Thu, 25 Jun 2026 17:38:02 -0300
Subject: [PATCH] docs: add CI trigger map (.github/README.md) + CLAUDE.md
 pointer

Document which event triggers which GitHub Actions workflow, the
workflow -> reusable -> composite call graph, and the manual approval
gates, in a single .github/README.md. Add a Continuous Integration
section to CLAUDE.md that points to it.

Claude-Session: https://claude.ai/code/session_013Ai5iqwADTryxoiJRNdhCa
---
 .github/README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md         |  4 ++
 2 files changed, 97 insertions(+)
 create mode 100644 .github/README.md

diff --git a/.github/README.md b/.github/README.md
new file mode 100644
index 00000000000..ca95c1c521d
--- /dev/null
+++ b/.github/README.md
@@ -0,0 +1,93 @@
+# CI workflows
+
+Maps which event triggers which workflow and how they call each other.
+
+## Entrypoints
+
+| Workflow | Trigger | What runs |
+|---|---|---|
+| [build-pr.yml](workflows/build-pr.yml) | `pull_request` (all branches) | ESLint + tests, PR changelog, Android + iOS store builds (gated), E2E build + Maestro shards on both platforms (gated) |
+| [build-develop.yml](workflows/build-develop.yml) | `push: develop` | ESLint + tests, release changelog, Android + iOS store builds, seeds Android AVD + SDK caches for E2E shards |
+| [prettier.yml](workflows/prettier.yml) | `push: * except master, develop, single-server` (main repo) | Auto-formats with Prettier + ESLint and commits any fixes back to the branch |
+| [organize_translations.yml](workflows/organize_translations.yml) | `push` touching `app/i18n/locales/**.json` | Sorts JSON keys and commits the result |
+
+## Call graph
+
+```mermaid
+flowchart TD
+    classDef entry fill:#d4e6f1,stroke:#2980b9
+    classDef reusable fill:#d5f5e3,stroke:#27ae60
+    classDef action fill:#fef9e7,stroke:#f39c12
+
+    PR([build-pr.yml]):::entry
+    DEV([build-develop.yml]):::entry
+    PRET([prettier.yml]):::entry
+    TRANS([organize_translations.yml]):::entry
+
+    ESLINT[eslint.yml]:::reusable
+    CHANGELOG[generate-changelog.yml]:::reusable
+    BUILDAND[build-android.yml]:::reusable
+    BUILDIOS[build-ios.yml]:::reusable
+    E2EAND[e2e-build-android.yml]:::reusable
+    E2EIOS[e2e-build-ios.yml]:::reusable
+    MASTAND[maestro-android.yml]:::reusable
+    MASIOS[maestro-ios.yml]:::reusable
+
+    SN[setup-node]:::action
+    FSV[fetch-supported-versions]:::action
+    GBV[generate-build-version]:::action
+    AACT[build-android action]:::action
+    IACT[build-ios action]:::action
+    UAND[upload-android]:::action
+    UIAND[upload-internal-android]:::action
+    UIOS[upload-ios]:::action
+    PREAND[preinstall-android-sdk]:::action
+    E2EACC[e2e-account]:::action
+
+    PR --> ESLINT
+    PR --> BUILDAND
+    PR --> BUILDIOS
+    PR --> E2EAND
+    PR --> E2EIOS
+    PR --> MASTAND
+    PR --> MASIOS
+
+    DEV --> ESLINT
+    DEV --> CHANGELOG
+    DEV --> BUILDAND
+    DEV --> BUILDIOS
+
+    PRET --> SN
+
+    ESLINT --> SN
+
+    BUILDAND --> SN
+    BUILDAND --> FSV
+    BUILDAND --> GBV
+    BUILDAND --> AACT
+    BUILDAND --> UAND
+    BUILDAND --> UIAND
+
+    BUILDIOS --> SN
+    BUILDIOS --> FSV
+    BUILDIOS --> GBV
+    BUILDIOS --> IACT
+    BUILDIOS --> UIOS
+
+    E2EAND --> SN
+    E2EIOS --> SN
+
+    MASTAND --> PREAND
+    MASTAND --> E2EACC
+
+    MASIOS --> E2EACC
+```
+
+## Manual gates
+
+| Environment | Workflow / job | Fires when |
+|---|---|---|
+| `android_build` | [build-android.yml](workflows/build-android.yml) — `build-hold` | Called with `trigger == pr` (i.e. from `build-pr.yml`) |
+| `upload_android` | [build-android.yml](workflows/build-android.yml) — `upload-hold` | Called with `trigger == pr`, after the Android build completes |
+| `ios_build` | [build-ios.yml](workflows/build-ios.yml) — `build-hold` | Called with `trigger == pr` (i.e. from `build-pr.yml`) |
+| `approve_e2e_testing` | [build-pr.yml](workflows/build-pr.yml) — `e2e-hold` | Every `pull_request` run |
diff --git a/CLAUDE.md b/CLAUDE.md
index 9af5b2b0b40..e774d0998e3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -95,3 +95,7 @@ pnpm storybook-generate    # Generate story snapshots
 - `index.js` — registers app, conditionally loads Storybook
 - `app/index.tsx` — Redux provider, theme, navigation, notifications setup
 - `app/AppContainer.tsx` — root navigation container
+
+## Continuous Integration
+
+CI triggers, call graph, and manual gates: see `.github/README.md`.