@event4u/agent-config 1.25.0 → 1.27.0

package/.agent-src/commands/e2e-heal.md

@@ -11,6 +11,8 @@ suggestion:
 
 # e2e-heal
 
+> **Mobile scope:** this command targets Playwright (browser/web) tests only. For Detox / Maestro / Appium / XCUITest / Espresso failures, use the `mobile-e2e-strategy` skill plus the framework's own diagnostic tooling — the Playwright-specific steps below do not apply to native mobile.
+
 ## Instructions
 
 ### 1. Identify failing tests

package/.agent-src/commands/e2e-plan.md

@@ -11,6 +11,8 @@ suggestion:
 
 # e2e-plan
 
+> **Mobile scope:** this command targets browser/web E2E only. For native iOS, native Android, or React Native E2E planning, switch to the `mobile-e2e-strategy` skill — Playwright is not the right tool for native UI flows.
+
 ## Instructions
 
 ### 1. Gather context

package/.agent-src/rules/domain-adoption-policy.md

@@ -0,0 +1,158 @@
+---
+type: "auto"
+tier: "2b"
+alwaysApply: false
+description: "Adopting a new domain track (mobile, ML, blockchain, scientific computing, IoT, gaming) into the suite — gates the import on demand, ownership, CI fit, and Sunset compatibility BEFORE any harvest"
+source: package
+triggers:
+  - intent: "adopt new domain"
+  - intent: "harvest new domain track"
+  - intent: "open a domain plate"
+  - keyword: "mobile track"
+  - keyword: "ml track"
+  - keyword: "blockchain track"
+  - path_prefix: ".agent-src.uncompressed/skills/"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncompressed/"
+    reason: "Rule names the authoring tree as the gated-entry location for new domain plates."
+---
+
+# Domain Adoption Policy
+
+A "domain" is a coherent vertical the suite has not yet entered — mobile, ML,
+blockchain, scientific computing, IoT, gaming, embedded, robotics. Adopting
+one is a structural decision: every new domain plate doubles the surface a
+single maintainer keeps current, and most upstream skill-suites in adjacent
+domains rot within 6-12 months as their underlying SDK churns.
+
+This rule gates that decision. It does **not** gate per-skill adoptions inside
+a domain that is already opened — those run under the regular harvest plate
+process. It gates **opening** the domain in the first place.
+
+## The Iron Law
+
+```
+NEVER OPEN A NEW DOMAIN TRACK WITHOUT THE THREE GATES.
+DEMAND-SIGNAL · NAMED MAINTENANCE OWNER · CI-TOOLING DECISION.
+ALL THREE PASS, OR THE ROADMAP MARKS THE DOMAIN GATED.
+```
+
+The three gates fire before any skill, guideline, command, or rule from the
+domain enters `.agent-src.uncompressed/`. A council session may inform the
+decision but cannot replace the gate evidence.
+
+## Gate 1 — Demand signal
+
+At least one of the following must be **true and citeable** in the roadmap:
+
+- **≥ 2 consumer projects** in the domain. Cite repository names or
+  `agents/contexts/` notes — not "I think there might be".
+- **Named user direction with target.** A specific user ask plus a target
+  project / use case — e.g. "harvest the mobile skills for project X, due
+  next quarter". Vague *"this might be useful"* does not count.
+- **Public-incident pull.** A reproducible incident on a consumer project
+  the domain would have prevented, captured in `agents/contexts/` with
+  the missing surface area named.
+
+If none of the three is citeable, **defer**. Open a watch-only context note
+under `agents/contexts/domain-watch/<domain>.md` listing the missing signal
+so the next harvest can re-evaluate without re-relitigating the case.
+
+## Gate 2 — Named maintenance owner
+
+Domain plates rot. Pick the owner before the import, not after.
+
+- The roadmap names a **single maintainer** (not "the team", not "TBD")
+  responsible for the domain quarterly review.
+- The owner commits to the **refresh cadence** — quarterly review at
+  minimum, faster if the domain is volatile (mobile RN/Expo SDK,
+  ML model APIs).
+- Each adopted artefact carries an **inline upstream-source line** with
+  SHA + last-checked timestamp so refresh is mechanical, not archaeological.
+
+If no owner is named or no cadence is set, **defer**. An unowned domain
+plate becomes broken authoritative-links and stale skills inside two cycles.
+
+## Gate 3 — CI-tooling decision
+
+Either the domain's verification tooling is validated in CI, or the suite
+explicitly accepts platform-bound reference-only status.
+
+- **Validated.** The CI pipeline runs the relevant linters/tests/integration
+  checks for the domain (e.g. `mobile-e2e` runners, ML model validation,
+  contract conformance) on every PR. Cost noted in the roadmap risk
+  register.
+- **Out-of-scope (reference-only).** The domain is a platform fact the
+  suite cannot validate (iOS Simulator on non-macOS runners, GPU-bound
+  ML, hardware-bound IoT). The roadmap states this explicitly; affected
+  artefacts carry a "reference-only on \<unsupported platforms\>" header
+  so consumers do not file false-positive bugs.
+
+If neither line is drawn, **defer**. Half-validated CI silently rots the
+domain — green builds while the underlying tooling drifts.
+
+## Sunset Policy stacks on top
+
+Every domain track inherits the authoritative-link Sunset path documented
+in any plate that imports volatile upstream content:
+
+- Volatile content (SDK-pinned, API-pinned, tool-version-pinned) lives as
+  guideline body + SHA-pinned upstream link, not as forked scripts.
+- Refresh trigger: quarterly cadence or earlier if a SHA-pinned link
+  404s in CI.
+- The `check-refs` and `check-portability` linters apply unchanged.
+
+Adopting a domain does not exempt it from any other suite-wide rule —
+`augment-portability`, `skill-quality`, `size-enforcement`, `docs-sync`,
+`rule-type-governance`. Every domain artefact passes the same gates as a
+core artefact.
+
+## Failure modes
+
+- *"It's just one skill, not a domain."* — Audit the skill's prerequisites.
+  If it pulls in a new toolchain, simulator, language runtime, or
+  platform-specific build system, it **is** a domain entry. Run the gates.
+- *"The upstream is well-maintained, we can just track it."* — Tracking
+  upstream means owning the diff, the breaking changes, and the migrations.
+  Tracking is maintenance work; budget for it under Gate 2 or skip the
+  adoption.
+- *"We'll add CI later."* — Later does not arrive. Either CI is wired in
+  the same plate, or the artefacts ship with explicit reference-only
+  headers so users do not assume validated coverage.
+- *"Council convergence is enough."* — Council informs the gates; it does
+  not replace them. A council session may surface that all three gates
+  pass; the roadmap still cites the evidence.
+- *"Demand-signal is the user asking once."* — Single-shot interest is a
+  watch trigger, not an open trigger. Either name the target use case
+  with project + timeline, or open a watch note and wait.
+
+## What to do when the gates fail
+
+1. Mark the domain plate `[-] gated — <gate name> not met` in the relevant
+   roadmap. Do **not** silently shrink scope to dodge the gate.
+2. Open a watch-only context note under `agents/contexts/domain-watch/`
+   capturing what's missing — citations, owner candidates, CI feasibility.
+3. Re-evaluate at the next harvest cycle. The note is the evidence trail
+   so the same questions are not relitigated.
+
+## Allowed without gates
+
+- Adding **a single skill** to an **already-opened** domain follows the
+  regular harvest plate; the gates do not re-fire per skill.
+- Authoring a **guideline** that documents a domain the suite already
+  ships in — the domain is open, the guideline is a within-domain artefact.
+- A **rule** that constrains an already-opened domain — within-domain.
+
+## See also
+
+- [`augment-portability`](augment-portability.md) — `.agent-src/`
+  must stay project-agnostic; domain plates inherit the floor
+- [`size-enforcement`](size-enforcement.md) — size budgets apply per
+  artefact regardless of domain
+- [`docs-sync`](docs-sync.md) — keep cross-references in sync when
+  opening a domain plate
+- [`rule-type-governance`](rule-type-governance.md) — within-domain rules
+  still pick `always` vs `auto` per the governance table
+- [`skill-quality`](skill-quality.md) — every domain skill passes the
+  same linter floor as a core skill

package/.agent-src/rules/no-unsolicited-rebase.md

@@ -0,0 +1,107 @@
+---
+type: "auto"
+tier: "2a"
+alwaysApply: false
+description: "Working with git history — never rewrite, rebase, squash, fixup, or amend without explicit user request; the linear/squashed shape is the user's call, not a tidiness reflex"
+source: package
+triggers:
+  - intent: "rebase the branch"
+  - intent: "squash commits"
+  - intent: "clean up commit history"
+  - intent: "fold this into the previous commit"
+  - keyword: "git rebase"
+  - keyword: "fixup"
+  - keyword: "--amend"
+  - keyword: "force-push"
+  - keyword: "squash-merge"
+---
+
+# No Unsolicited Rebase
+
+## Iron Law
+
+```
+NEVER REBASE, SQUASH, FIXUP, OR AMEND PUBLISHED OR LOCAL HISTORY
+WITHOUT THE USER ASKING FOR IT THIS TURN.
+LINEAR HISTORY IS A PREFERENCE, NOT A DEFAULT.
+COMMIT-CHUNK ORDER IS NOT A CORRECTNESS GOAL.
+```
+
+Add the next commit on top. Never reorder, fold, drop, or rewrite earlier
+commits to make the log "look right".
+
+## Why this rule exists
+
+Interactive rebase + fixup loops generate disproportionate token cost on
+every iteration: re-running CI per replayed commit, resolving the same
+content conflict in three derived files (`.compression-hashes.json`,
+`router.json`, `.windsurfrules`), losing the working tree to a stash that
+silently re-introduces older state. A single conflict can burn the budget
+of an entire feature. The user pays for it. The "clean history" payoff is
+cosmetic; reviewers read the diff, not the log.
+
+## When rebase / amend / fixup IS allowed
+
+Exactly three:
+
+1. **User says so this turn** — "rebase onto main", "squash these two",
+   "amend that". This operation only, not a standing rule.
+2. **Standing instruction not yet revoked** — the user said earlier in
+   the conversation "always squash before pushing"; honor it.
+3. **Conflict resolution forced by `git pull --rebase`** — the user
+   already invoked the rebase via pull; finish it.
+
+Anything else — chunk-tidiness, "logical order", folding a follow-up fix
+into its parent — **forbidden**. The follow-up ships as its own commit
+(`fix: …`, `chore: …`).
+
+## Equivalents that are also forbidden by default
+
+- `git rebase -i` (interactive)
+- `git rebase --autosquash`
+- `git commit --fixup` / `--squash` (the helper that feeds the autosquash)
+- `git commit --amend` on already-pushed commits
+- `git push --force` / `--force-with-lease`
+- `git reset --hard` past unpushed work the user might want
+- Squash-merge of a PR via API or CLI when the user has not picked the
+  merge strategy
+- Cherry-pick rewriting that drops or reorders commits
+
+`--amend` on the *current local* commit before the first push is the
+narrow exception (treated as continuing to compose the commit, not
+rewriting history).
+
+## When you'd be tempted
+
+- "I want commit 3 to come before commit 2 because the topic flows better."
+  → don't. Reviewers read the PR diff.
+- "There are two `chore: regenerate` commits, ugly." → don't. They are
+  honest checkpoints.
+- "A linter caught an issue in commit 2 — let me fold the fix in."
+  → don't. Add `fix(scope): …` on top.
+- "I want to drop the WIP commit before pushing." → ask the user first.
+- "Squash-merge when I open the PR will clean it anyway." → also true,
+  also irrelevant — let the merge strategy do that work, not you.
+
+## Failure mode catalog
+
+- **Rebase-conflict cascade.** Interactive rebase replays N commits. Any
+  derived file (`.compression-hashes.json`, generated tool projections,
+  index/catalog) carries a hash per commit and conflicts on every replay.
+  Resolution time scales with N, not with the actual change.
+- **Stash-pop reverts work.** A `git stash` issued during rebase recovery
+  can re-introduce older edits that overwrite committed work after the
+  rebase finishes. Hard to spot in `git status` because the file shapes
+  match.
+- **Force-push during review.** Rewriting history on a branch with an
+  open PR invalidates review comments anchored to commits and forces a
+  re-review.
+
+## See also
+
+- [`scope-control`](scope-control.md) — git-ops permission gate ("rebase"
+  already named in the canonical list).
+- [`commit-policy`](commit-policy.md) — commits are the user's call;
+  rewriting them is a stronger version of the same restriction.
+- [`token-efficiency`](token-efficiency.md) — Iron Law on burning the
+  user's tokens for cosmetic gain.

package/.agent-src/skills/mobile-e2e-strategy/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: mobile-e2e-strategy
+description: "Use when picking a mobile E2E framework — Detox / Appium / Maestro / XCUITest / Espresso — or planning iOS Simulator / Android Emulator coverage in CI for RN, Expo, or native apps."
+source: package
+---
+
+# mobile-e2e-strategy
+
+## When to use
+
+- Choosing an E2E framework for a mobile app (React Native, Expo, Flutter, native iOS, native Android).
+- Deciding whether to extend existing Playwright/web E2E to mobile or stand up a separate mobile suite.
+- Planning iOS Simulator / Android Emulator coverage in CI (cost, runner type, parallelism).
+- Triaging flaky mobile tests that span the simulator/emulator boundary.
+- Bridging mobile E2E results into the same review surface as web E2E
+  (`playwright-testing`, `e2e-plan`, `e2e-heal`).
+
+**This skill selects and plans — it does not generate test code.** For the chosen framework, apply its own conventions; for the host environment, see the cross-links below.
+
+## Cross-links
+
+- `react-native-setup` — RN/Expo environment, Xcode/Android Studio, EAS Build.
+- `docs/guidelines/agent-infra/ios-simulator-guide.md` — `simctl` / `idb` / accessibility-driven testing on iOS.
+- `playwright-testing` — web E2E baseline (do **not** reuse for native mobile).
+- `e2e-plan` — explore an app and produce an E2E plan in Markdown.
+- `e2e-heal` — debug and fix failing E2E tests.
+
+## Procedure
+
+1. **Classify the app.** Is it native iOS, native Android, React Native, Expo, Flutter, or a web view inside a shell?
+2. **Classify the goal.** Smoke (boots + login + key flow), regression (every release), visual diff, accessibility audit, or performance baseline.
+3. **Pick the framework** using the decision matrix below.
+4. **Confirm host availability.** macOS for iOS Simulator (mandatory); any OS for Android Emulator.
+5. **Plan CI coverage.** Decide runner type, parallelism, and whether iOS coverage runs every PR or nightly only.
+6. **Define the artefact contract.** Screenshots, accessibility trees, video, log archives — name the storage path and retention.
+7. **Validate.** Run a single smoke test locally before wiring CI; verify both iOS and Android paths if both are in scope.
+
+## Decision matrix — framework selection
+
+| Framework | Best for | Avoid when |
+|---|---|---|
+| **Detox** | React Native apps, gray-box testing, deterministic sync with the JS bridge | Native iOS/Android-only; Expo managed without a dev client |
+| **Maestro** | Cross-platform smoke + regression, declarative YAML flows, fast onboarding | Need full programmable assertions or deep native introspection |
+| **Appium** | Truly cross-platform (RN + Flutter + native), one team owning many apps, WebDriver-compatible tooling | Solo project — setup overhead is high; flaky on JS-heavy RN unless tuned |
+| **XCUITest** (iOS) | Native iOS apps, deepest Apple toolchain integration, Xcode Cloud | Cross-platform coverage in one suite |
+| **Espresso** (Android) | Native Android apps, in-process execution, fast reliable runs | Cross-platform coverage in one suite |
+| **Playwright + WebView** | Web app embedded in a thin native shell, purely web flows | Native UI flows of any depth (use a mobile framework instead) |
+
+**Default starting point:**
+
+- React Native / Expo → **Detox** (single-platform RN team) or **Maestro** (cross-platform smoke).
+- Flutter → **Maestro** (smoke) + **Flutter integration_test** (deep) — Flutter-specific, out of scope here.
+- Native iOS only → **XCUITest**.
+- Native Android only → **Espresso**.
+- Mixed native portfolio → **Appium**.
+
+## Host & environment prerequisites
+
+**iOS (macOS-only)**
+- Xcode 16.1+ and matching Command Line Tools — see `react-native-setup`.
+- iOS Simulator boot/install/launch via `simctl` — see `ios-simulator-guide.md`.
+- Optional: `idb` for accessibility-tree access and coordinate-level UI control.
+- Apple developer account only required for physical-device or signed-build runs.
+
+**Android (any host)**
+- Android Studio Ladybug+ with SDK 35, Platform-Tools, Emulator.
+- AVD with API 35 image; verify `emulator -list-avds` and `adb devices`.
+- HAXM/Hypervisor (Intel) or hardware acceleration on Apple Silicon.
+
+**Authoritative upstream docs**
+- iOS Simulator: `https://developer.apple.com/documentation/xcode/running-your-app-in-simulator-or-on-a-device`
+- Android Emulator: `https://developer.android.com/studio/run/emulator`
+- Detox: `https://wix.github.io/Detox/`
+- Maestro: `https://maestro.mobile.dev/`
+- Appium: `https://appium.io/docs/en/latest/`
+- XCUITest: `https://developer.apple.com/documentation/xctest/user_interface_tests`
+- Espresso: `https://developer.android.com/training/testing/espresso`
+
+## CI floor — cost and capacity
+
+| Concern | iOS | Android |
+|---|---|---|
+| Runner OS | macOS only (GitHub `macos-latest`, self-hosted Mac) | Any (Linux fastest) |
+| Boot time | 30–90 s per simulator cold-boot | 60–180 s per emulator cold-boot |
+| Parallelism | 1 simulator per macOS runner is the safe default | KVM-accelerated on Linux scales well |
+| Cost (GitHub Actions) | macOS minutes are ~10× Linux minutes | Standard Linux pricing |
+| Recommended cadence | Nightly + on-release for full suite; smoke on every PR | Every PR feasible |
+
+**Pragmatic split:**
+
+- Every PR: Android emulator full suite + iOS smoke only.
+- Nightly / pre-release: iOS full suite + cross-device matrix.
+- Adjust if the project pays for self-hosted Mac runners or the
+  release cadence demands per-PR iOS parity.
+
+## Artefact contract (recommended)
+
+For every E2E run the suite SHOULD persist:
+
+1. **Screenshots** — per-step PNG, named `{suite}/{test}/{step}.png`.
+2. **Accessibility tree** — JSON dump per failure (iOS via `idb ui describe-all --json --nested`, Android via Espresso accessibility checks).
+3. **Video** — full run on failure; first-class for Detox and Maestro.
+4. **Logs** — structured logcat (Android) or `simctl spawn log` (iOS) filtered to the app under test.
+5. **Result XML / JUnit** — for CI dashboard ingestion.
+
+Retain artefacts for at least one release cycle; promote screenshots
+of failures to the PR comment surface so reviewers see the failure
+without leaving the review.
+
+## Bridging to the existing E2E surface
+
+- **Web + mobile in one repo:** keep Playwright for web, add a separate `mobile/` suite using Detox or Maestro. Do **not** force-fit Playwright onto native UI.
+- **Plan reuse:** the planning patterns in `e2e-plan` (user journeys, test pyramid placement, stable selectors) apply unchanged. The implementation lives in the mobile framework.
+- **Heal reuse:** the diagnostic loop in `e2e-heal` (reproduce → isolate → minimal fix → verify) applies. Replace browser-specific tooling with mobile-framework equivalents (Detox `--loglevel verbose`, Maestro Studio replays, Appium Inspector).
+- **Selectors:** prefer accessibility identifiers (`accessibilityIdentifier` on iOS, `contentDescription` on Android) over coordinate taps — see `ios-simulator-guide.md` Module 1.
+
+## Output format
+
+1. A framework recommendation keyed off app type + team shape + cross-platform need.
+2. A host & runner plan naming the macOS/Linux split for CI.
+3. A cadence plan (per-PR vs nightly) with cost rationale.
+4. An artefact contract listing screenshot/log/video/accessibility-tree paths.
+
+## Auto-trigger keywords
+
+- mobile E2E, React Native E2E, Expo E2E, Flutter E2E
+- Detox, Appium, Maestro, XCUITest, Espresso
+- iOS Simulator, Android Emulator, AVD, simctl, idb
+- mobile CI, mobile test runner, macOS runner cost
+
+## Gotcha
+
+- Mobile E2E is fundamentally slower than web E2E — the test pyramid still applies; do not reach for E2E when a unit or integration test would do.
+- iOS coverage on every PR is expensive on hosted runners; default to smoke on PR + full suite nightly until the cost is measured.
+- React Native + Appium + non-trivial JS bridge timing is the historical flake hotspot — Detox or Maestro avoids the WebDriver layer entirely.
+- Do not chain emulator-only tests from a developer laptop and a CI runner; environment drift (locale, timezone, API level) corrupts deterministic comparisons.
+- Visual regression baselines are tied to a specific simulator/emulator image — pin the image SHA / API level explicitly in CI config.
+- Maestro YAML is concise but not a full language; complex assertions still need Detox / Appium / native frameworks.
+
+## Do NOT
+
+- Do NOT reuse a Playwright suite for native UI flows — accessibility-tree access is wholly different.
+- Do NOT mix two mobile E2E frameworks in one suite — pick one per platform pair, factor shared helpers behind a thin abstraction.
+- Do NOT run iOS E2E on every PR until you measured the macOS-runner cost on the project's actual cadence.
+- Do NOT rely on coordinate taps (`idb ui tap <x> <y>`) for stable tests — use accessibility identifiers instead. Coordinate taps are debug aids, not test selectors.
+- Do NOT fork upstream simulator scripts (`accessibility_audit.py`, `visual_diff.py`, etc.) into the consumer project — link to the upstream SHA per `ios-simulator-guide.md`.
+- Do NOT skip the artefact contract — without screenshots, logs, and accessibility trees, mobile E2E failures are nearly impossible to diagnose.

package/.agent-src/skills/playwright-testing/SKILL.md

@@ -18,6 +18,7 @@ Use this skill when:
 
 **Guideline:** `../../../docs/guidelines/e2e/playwright.md` — full conventions, config templates, CI setup.
 **Rule:** `.augment/rules/e2e-testing.md` — constraints enforced during E2E test work.
+**Mobile:** for native iOS/Android or React Native E2E, do NOT reuse Playwright — see the `mobile-e2e-strategy` skill for framework selection.
 
 ## Procedure: Write Playwright tests
 

package/.agent-src/skills/react-native-setup/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: react-native-setup
+description: "Use when setting up React Native or Expo dev environments — Xcode, Android Studio, CocoaPods, EAS, Metro, New Architecture — even when the user just says 'my RN build won't start'."
+source: package
+---
+
+# react-native-setup
+
+## When to use
+
+- Initial React Native 0.76+ / Expo SDK 52+ environment setup
+- Installing or configuring Xcode, Android Studio, or their command-line tools
+- Setting up iOS simulators or Android emulators for development
+- Troubleshooting "Command not found", `ANDROID_HOME`, or SDK path errors
+- Fixing CocoaPods install failures (Apple Silicon, FFI, Ruby mismatches)
+- Clearing Metro / Watchman cache or diagnosing reload loops
+- Configuring EAS Build, dev clients, or OTA updates
+- Migrating to or troubleshooting the New Architecture (Fabric / Turbo Modules)
+
+**Cross-links:** `mobile-e2e-strategy` (Detox / Appium / Maestro selection),
+`docs/guidelines/agent-infra/ios-simulator-guide.md` (iOS simulator decision matrix).
+
+## Assess current setup before changing anything
+
+Before installing or upgrading anything, inspect what's already there — modifying a working toolchain blindly is the most common source of wasted hours.
+
+1. **Read `package.json`** — RN version, Expo SDK, scripts, native dependencies.
+2. **Check `ios/Podfile` and `ios/Podfile.lock`** — CocoaPods version, deployment target, RCT_NEW_ARCH_ENABLED flag.
+3. **Check `android/build.gradle` and `android/gradle.properties`** — Gradle version, compile/target SDK, `newArchEnabled`, NDK version.
+4. **Verify host tools** — `node --version`, `xcodebuild -version`, `sdkmanager --list_installed`, `pod --version`, `watchman --version`.
+5. **Check for an existing `.nvmrc`, `.tool-versions`, or `Brewfile`** — honour the project's pinned versions over global ones.
+6. **Read project README and CONTRIBUTING** — many RN repos document one-time setup quirks (Apple Silicon Rosetta, Hermes flags, EAS profile names).
+
+## Procedure
+
+1. **Identify the target stack** — RN CLI vs Expo, target SDK, supported OS, monorepo or single-package.
+2. **Verify prerequisites** — Node, package manager, Watchman, platform SDKs (see matrix below).
+3. **Configure platform tooling** — Xcode + CocoaPods (iOS) or Android Studio + SDK 34/35 (Android).
+4. **Install project dependencies** — `npm`/`yarn`/`pnpm`/`bun install`, then `pod install` for iOS.
+5. **Run a smoke build** — `npm run ios` / `npm run android` / `npx expo start`.
+6. **Validate** — app launches, fast refresh works, Metro bundler runs without warnings.
+7. **On failure** — apply the matching pattern from "Common setup issues" below.
+
+## Prerequisites (2025 baseline)
+
+**Node.js**
+- Node 20.x minimum (Node 18 EOL April 2025); Node 22 LTS recommended.
+- `node --version && npm --version`.
+- npm, yarn, pnpm, bun all supported. Corepack for yarn:
+  `corepack enable && corepack prepare yarn@stable --activate`.
+
+**Xcode (macOS, iOS)**
+- Xcode 16.1+ minimum (RN 0.83), Xcode 26+ for Liquid Glass.
+- `xcode-select --install` then `sudo xcodebuild -license accept`.
+- iOS 15.1+ deployment target; iOS 18+/26 for latest features.
+
+**Android Studio**
+- Ladybug or later (2024.2.1+).
+- SDK Platform 35 (API 35), Build-Tools 35.0.0, Platform-Tools, Emulator.
+- NDK 27.1.12297006 + CMake 3.22.1+ for native modules / Turbo Modules.
+- `compileSdkVersion 35`, `targetSdkVersion 35`, `minSdkVersion 24`.
+- `ANDROID_HOME` exported; edge-to-edge display ready (Android 15+).
+
+**Watchman**
+- macOS: `brew install watchman`.
+- Required for fast refresh on large codebases. Reset: `watchman watch-del-all`.
+
+## Platform setup
+
+**iOS**
+- CocoaPods 1.15+: `sudo gem install cocoapods`.
+- New Architecture pods: `RCT_NEW_ARCH_ENABLED=1 pod install`.
+- Provisioning profiles, certificates managed in Xcode or via EAS.
+- Simulator management: `xcrun simctl list devices`. Liquid Glass requires iOS 26 simulator.
+
+**Android**
+- Gradle 8.10+ (bundled with Ladybug).
+- AVD with API 35 image; verify edge-to-edge layout.
+- New Architecture: `newArchEnabled=true` in `gradle.properties`.
+
+**Metro bundler**
+- Default port 8081. Cache reset: `npx react-native start --reset-cache`.
+- Symlink support and custom resolvers needed for monorepos.
+
+**EAS Build (Expo)**
+- `npm install -g eas-cli` then `eas login`.
+- `eas build:configure` to seed `eas.json`.
+- Dev clients for custom native modules; EAS Update for OTA.
+
+## Common setup issues
+
+**"Command not found"**
+- PATH for Node, Android SDK, Xcode tools missing in `~/.zshrc` or `~/.bash_profile`.
+- Symlink drift with nvm / fnm — re-run `nvm use` after shell reload.
+
+**SDK not found**
+- `echo $ANDROID_HOME` empty → re-export.
+- Re-run SDK Manager; reinstall NDK if native modules fail.
+
+**Pod install failures**
+- CocoaPods < 1.15 incompatible with New Architecture — upgrade.
+- Apple Silicon FFI compile errors → use system Ruby or rbenv-managed Ruby.
+- Stuck pods: `pod deintegrate && pod install`.
+
+**Build failures**
+- Clean iOS: `cd ios && rm -rf build Pods Podfile.lock && pod install && cd ..`.
+- Clean Android: `cd android && ./gradlew clean && cd ..`.
+- Clear Xcode derived data when stale build artefacts persist.
+
+**New Architecture issues**
+- Turbo Module not found → confirm codegen ran during build.
+- Fabric component not rendering → verify native registration.
+- Bridge incompatibility → use the interop layer.
+
+## Quick verification
+
+```bash
+node --version          # 20+ (22 LTS preferred)
+npm --version
+xcodebuild -version     # 16.1+
+pod --version           # 1.15+
+adb --version
+emulator -version
+watchman version
+eas --version           # Expo only
+echo $ANDROID_HOME      # non-empty
+```
+
+## Quick commands
+
+**Create / run RN CLI project**
+```bash
+npx @react-native-community/cli init MyProject
+cd MyProject
+cd ios && RCT_NEW_ARCH_ENABLED=1 pod install && cd ..
+npm start                # Metro
+npm run ios              # in a second terminal
+npm run android          # in a third terminal
+```
+
+**Create / run Expo project**
+```bash
+npx create-expo-app@latest MyProject
+cd MyProject
+npx expo start
+# Custom native code → dev client:
+npx expo install expo-dev-client
+eas build --profile development --platform ios
+eas build --profile development --platform android
+```
+
+**Simulator / emulator**
+```bash
+xcrun simctl list devices
+xcrun simctl boot "iPhone 16 Pro"
+emulator -list-avds
+emulator -avd Pixel_8_API_35
+```
+
+**Reset everything**
+```bash
+watchman watch-del-all
+npx react-native start --reset-cache    # RN CLI
+npx expo start --clear                  # Expo
+```
+
+## Pro tips
+
+1. **Shell profile** — add SDK paths once, reload once:
+   ```bash
+   export ANDROID_HOME=$HOME/Library/Android/sdk
+   export PATH=$PATH:$ANDROID_HOME/emulator
+   export PATH=$PATH:$ANDROID_HOME/platform-tools
+   export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
+   ```
+2. **EAS minimum `eas.json`** — `development` (dev client + internal), `preview` (internal), `production` (defaults).
+3. **Hermes** — RN ≥ 0.70 ships Hermes by default; verify with `global.HermesInternal !== undefined` at runtime.
+4. **Health check** — a single shell function running the verification block above catches 80 % of "it doesn't build" reports.
+
+## Version compatibility (2025)
+
+| Component | Minimum | Recommended | Notes |
+|---|---|---|---|
+| Node.js | 20.x | 22 LTS | Node 18 EOL April 2025 |
+| React Native | 0.76 | 0.83 | New Architecture default since 0.76 |
+| React | 18.3 | 19.2 | `Activity`, `useEffectEvent` |
+| Expo SDK | 52 | 54 | Native tabs, Liquid Glass |
+| Xcode | 16.1 | 26 | iOS 26 required for Liquid Glass |
+| Android SDK | 34 | 35 | Edge-to-edge support |
+| CocoaPods | 1.14 | 1.15+ | New Architecture compatibility |
+| Gradle | 8.6 | 8.10+ | K2 compiler support |
+
+## Output format
+
+1. A short setup plan keyed off the target stack (RN CLI vs Expo, iOS vs Android vs both).
+2. Concrete shell commands the user can paste — no placeholders unless flagged `<…>`.
+3. A verification block confirming the toolchain is healthy before any feature work.
+
+## Auto-trigger keywords
+
+- React Native, Expo, EAS Build
+- Xcode, CocoaPods, pod install
+- Android Studio, ANDROID_HOME, AVD, emulator
+- Metro bundler, Watchman, fast refresh
+- New Architecture, Fabric, Turbo Modules
+
+## Gotcha
+
+- Don't set `RCT_NEW_ARCH_ENABLED=1` selectively — once enabled, every `pod install` for that project must use it or cached artefacts diverge.
+- Apple Silicon + system Ruby + FFI is the single biggest source of "pod install hangs" reports — switch to rbenv before retrying.
+- Watchman left over from a previous project can pin Metro to a stale tree — `watchman watch-del-all` is cheap, run it before deeper debugging.
+- iOS Simulator versions are tied to Xcode versions. Liquid Glass features need both Xcode 26 AND an iOS 26 simulator image installed.
+- Android NDK version drift breaks Turbo Modules silently — pin `27.1.12297006` until the project explicitly upgrades.
+
+## Do NOT
+
+- Do NOT mix `npm`, `yarn`, `pnpm`, and `bun` lockfiles in the same project — pick one, commit its lockfile, delete the others.
+- Do NOT skip `pod install` after pulling iOS-side changes — the JS bundle will load but native modules will be stale.
+- Do NOT enable New Architecture mid-feature — flag it on a clean branch, run a full clean build, validate both platforms.
+- Do NOT hand-edit `Podfile.lock` or `gradle.lock`-style files — re-run the installers instead.
+- Do NOT commit `node_modules`, `ios/Pods`, `android/.gradle`, or platform `build/` directories.