@event4u/agent-config 1.26.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.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.26.0"
+    "version": "1.27.0"
   },
   "plugins": [
     {
@@ -153,6 +153,7 @@
         "./.claude/skills/memory-propose",
         "./.claude/skills/merge-conflicts",
         "./.claude/skills/migration-creator",
+        "./.claude/skills/mobile-e2e-strategy",
         "./.claude/skills/mode",
         "./.claude/skills/module",
         "./.claude/skills/module-create",
@@ -198,6 +199,7 @@
         "./.claude/skills/prompt-optimizer",
         "./.claude/skills/quality-fix",
         "./.claude/skills/quality-tools",
+        "./.claude/skills/react-native-setup",
         "./.claude/skills/react-shadcn-ui",
         "./.claude/skills/readme-reviewer",
         "./.claude/skills/readme-writing",

package/CHANGELOG.md

@@ -318,6 +318,24 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.27.0](https://github.com/event4u-app/agent-config/compare/1.26.0...1.27.0) (2026-05-08)
+
+### Features
+
+* **governance:** add no-unsolicited-rebase rule ([b17e4bc](https://github.com/event4u-app/agent-config/commit/b17e4bc8482342a8f3b9c47f40994e17a6eab626))
+* **governance:** add domain-adoption-policy rule ([30a45c3](https://github.com/event4u-app/agent-config/commit/30a45c352a7c9b16dfe455f31bf87c253fe95014))
+* **mobile:** add mobile track skills and iOS simulator guideline ([f4dbb5c](https://github.com/event4u-app/agent-config/commit/f4dbb5cc32065e76d39981d18bc4513551a5da8b))
+
+### Bug Fixes
+
+* **governance:** set tier 2a on no-unsolicited-rebase rule ([284ced0](https://github.com/event4u-app/agent-config/commit/284ced0c7b53ec9a394234a37ee5b370d2278802))
+* **governance:** allowlist .agent-src.uncompressed/ substring in domain-adoption-policy ([e2091dc](https://github.com/event4u-app/agent-config/commit/e2091dc660ce4c437c1b5035aaa1179f469e7abe))
+
+### Chores
+
+* **roadmap:** archive road-to-mobile-adoption ([cc5e6ea](https://github.com/event4u-app/agent-config/commit/cc5e6ea4228666b9784fd468095bb2c096430672))
+* regenerate tool projections and counts for mobile + governance ([b36d495](https://github.com/event4u-app/agent-config/commit/b36d4957a43b26d0786ae73f11097091ca28fbbb))
+
 ## [1.26.0](https://github.com/event4u-app/agent-config/compare/1.25.0...1.26.0) (2026-05-08)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>142 Skills</strong> · <strong>58 Rules</strong> · <strong>103 Commands</strong> · <strong>58 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>144 Skills</strong> · <strong>60 Rules</strong> · <strong>103 Commands</strong> · <strong>59 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -368,7 +368,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 142 skills + 103 native commands). Cursor, Cline, Windsurf,
+> package (rules + 144 skills + 103 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.

package/docs/architecture.md

@@ -96,10 +96,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 142 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 58 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Skills** | 144 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 103 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 58 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Guidelines** | 59 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **358 public artefacts** shipped by
+Consumer-facing catalog of all **363 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (142)
+## Skills (144)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -87,6 +87,7 @@ are excluded.
 | skill | [`md-language-check`](../.agent-src/skills/md-language-check/SKILL.md) |  | Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone. |
 | skill | [`merge-conflicts`](../.agent-src/skills/merge-conflicts/SKILL.md) |  | Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow. |
 | skill | [`migration-creator`](../.agent-src/skills/migration-creator/SKILL.md) |  | Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness. |
+| skill | [`mobile-e2e-strategy`](../.agent-src/skills/mobile-e2e-strategy/SKILL.md) |  | 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. |
 | skill | [`module-management`](../.agent-src/skills/module-management/SKILL.md) |  | Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions. |
 | skill | [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) |  | Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations. |
 | skill | [`okr-tree-modeling`](../.agent-src/skills/okr-tree-modeling/SKILL.md) |  | Use when decomposing a company objective into team OKRs, auditing a draft OKR tree, or stress-testing an existing one for measurability and laddering. |
@@ -112,6 +113,7 @@ are excluded.
 | skill | [`project-docs`](../.agent-src/skills/project-docs/SKILL.md) |  | Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs. |
 | skill | [`prompt-optimizer`](../.agent-src/skills/prompt-optimizer/SKILL.md) |  | Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'. |
 | skill | [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) |  | Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned. |
+| skill | [`react-native-setup`](../.agent-src/skills/react-native-setup/SKILL.md) |  | 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'. |
 | skill | [`react-shadcn-ui`](../.agent-src/skills/react-shadcn-ui/SKILL.md) |  | Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack. |
 | skill | [`readme-reviewer`](../.agent-src/skills/readme-reviewer/SKILL.md) |  | Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues. |
 | skill | [`readme-writing`](../.agent-src/skills/readme-writing/SKILL.md) |  | Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience. |
@@ -154,7 +156,7 @@ are excluded.
 | skill | [`verify-completion-evidence`](../.agent-src/skills/verify-completion-evidence/SKILL.md) |  | Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (55)
+## Rules (57)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -175,6 +177,7 @@ are excluded.
 | rule | [`context-hygiene`](../.agent-src/rules/context-hygiene.md) | auto | When debugging, fixing errors, or running long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers |
 | rule | [`direct-answers`](../.agent-src/rules/direct-answers.md) | always | Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default. |
 | rule | [`docker-commands`](../.agent-src/rules/docker-commands.md) | auto | Running PHP commands inside Docker containers — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, and any CLI tool execution |
+| rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | 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 |
 | rule | [`downstream-changes`](../.agent-src/rules/downstream-changes.md) | auto | After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation |
 | rule | [`e2e-testing`](../.agent-src/rules/e2e-testing.md) | auto | Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention |
 | rule | [`guidelines`](../.agent-src/rules/guidelines.md) | manual | Writing or reviewing code — check relevant guideline before writing or reviewing code |
@@ -189,6 +192,7 @@ are excluded.
 | rule | [`no-attribution-footers`](../.agent-src/rules/no-attribution-footers.md) | auto | Generating PR/issue/comment/commit-message bodies — forbids 'Generated with', 'Co-authored by', or 'Pull Request opened by' attribution footers |
 | rule | [`no-cheap-questions`](../.agent-src/rules/no-cheap-questions.md) | always | No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on) |
 | rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Linking transient files (agents/roadmaps/, agents/council-{questions,responses,sessions}/) from a stable artifact — both layers expire; promote findings |
+| rule | [`no-unsolicited-rebase`](../.agent-src/rules/no-unsolicited-rebase.md) | auto | 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 |
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
 | rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt to run /onboard before any request |
 | rule | [`package-ci-checks`](../.agent-src/rules/package-ci-checks.md) | manual | Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first |
@@ -322,7 +326,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (58)
+## Guidelines (59)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -334,6 +338,7 @@ are excluded.
 | guideline | [`developer-judgment`](../docs/guidelines/agent-infra/developer-judgment.md) | agent-infra |  |
 | guideline | [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |
+| guideline | [`ios-simulator-guide`](../docs/guidelines/agent-infra/ios-simulator-guide.md) | agent-infra |  |
 | guideline | [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md) | agent-infra |  |
 | guideline | [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) | agent-infra |  |
 | guideline | [`mcp-request-signing`](../docs/guidelines/agent-infra/mcp-request-signing.md) | agent-infra |  |

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 58 rules. No configuration needed.
+This is enforced automatically by 60 rules. No configuration needed.
 
 ---
 

package/docs/guidelines/agent-infra/ios-simulator-guide.md

@@ -0,0 +1,383 @@
+# iOS Simulator Guide
+
+> Decision matrix and reference modules for driving the iOS Simulator
+> from the command line — `simctl`, `idb`, accessibility-driven
+> testing, and known troubleshooting paths.
+
+## Scope and audience
+
+- Reference material for any work touching the iOS Simulator on macOS
+  hosts: smoke tests, accessibility audits, visual regressions, bug
+  capture, multi-device test sweeps.
+- Intended companions: `react-native-setup` skill (environment),
+  `mobile-e2e-strategy` skill (framework selection), `playwright-testing`
+  / `e2e-plan` skills (cross-platform E2E strategy).
+- **macOS-only:** Xcode + simctl + (optional) idb require a macOS host.
+  On Linux/Windows this guideline is reference-only — no implementation
+  recipes are portable.
+
+## When to consult this guideline
+
+- Picking a simulator interaction surface (simctl vs idb vs xcodebuild).
+- Auditing iOS UI accessibility for a release.
+- Driving the simulator from CI for smoke or visual regression tests.
+- Diagnosing a stuck simulator, missing target, or empty accessibility tree.
+
+## Decision matrix — interaction surface
+
+| Surface | Use when | Avoid when |
+|---|---|---|
+| `xcrun simctl` | Boot/install/launch/screenshot/log capture; default for everything CLI-driven | Need accessibility tree or precise UI coordinates |
+| `idb` (Facebook iOS Debug Bridge) | Accessibility-tree dumps, coordinate taps/swipes/text input, point-level inspection | Plain boot/launch tasks (simctl is lighter) |
+| `xcodebuild` / `xcodebuild test` | Compile, sign, and run XCTest / XCUITest suites; CI integration | Ad-hoc scripted interaction (slow, heavyweight) |
+| Direct UI Automation (XCUITest) | Native iOS app E2E with full Apple toolchain support | Cross-platform E2E (use Detox / Appium / Maestro — see `mobile-e2e-strategy`) |
+
+**Rule of thumb:** start with `simctl`; reach for `idb` only when you
+need accessibility-tree introspection or coordinate-level UI control.
+
+## Authoritative upstream
+
+This guideline inlines five reference modules **verbatim** from the
+upstream `conorluddy/ios-simulator-skill` repository. The 21 Python
+helper scripts that ship with the upstream skill (~8500 LOC, macOS-
+and Xcode-bound) are **not forked** — script references inside the
+modules below resolve against the upstream tree, not this suite.
+
+- Upstream repo: `https://github.com/conorluddy/ios-simulator-skill`
+- Pinned SHA: `3acd0717a1b571b1d051559c01ff230d6da28a05`
+- Last checked: 2026-05-08
+- Refresh trigger: quarterly review or sooner if any link 404s in CI.
+
+When you need an upstream Python helper (`accessibility_audit.py`,
+`visual_diff.py`, `app_state_capture.py`, `test_recorder`) clone the
+upstream repo at the pinned SHA, run the helper from there, do **not**
+copy it into a consumer project.
+
+---
+
+## Module 1 — iOS Accessibility Checklist
+
+_Verbatim from `references/accessibility_checklist.md` at the pinned SHA above._
+
+### Critical Rules (Must Fix)
+
+#### 1. Interactive elements need labels
+**Check:** `accessibilityLabel != nil`
+**Fix:** Add descriptive label
+
+#### 2. Buttons need text
+**Check:** `label || value != ""`
+**Fix:** Set button title or accessibilityLabel
+
+#### 3. Images need descriptions
+**Check:** `isImage && accessibilityLabel`
+**Fix:** Add alt text via accessibilityLabel
+
+### Warnings (Should Fix)
+
+#### 4. Complex controls need hints
+**Check:** `accessibilityHint for custom controls`
+**Fix:** Explain what happens on activation
+
+#### 5. Grouped elements need containers
+**Check:** `isAccessibilityElement on containers`
+**Fix:** Group related elements
+
+#### 6. Text fields need placeholders
+**Check:** `placeholder || accessibilityLabel`
+**Fix:** Add placeholder text
+
+### Info (Nice to Have)
+
+#### 7. Automation identifiers
+**Check:** `accessibilityIdentifier != nil`
+**Fix:** Add for UI testing
+
+#### 8. Trait specification
+**Check:** `accessibilityTraits set correctly`
+**Fix:** Use .button, .link, .header appropriately
+
+#### 9. Frame size adequate
+**Check:** `frame.width >= 44 && frame.height >= 44`
+**Fix:** Minimum touch target 44x44pt
+
+### Quick Audit Command
+
+```bash
+python scripts/accessibility_audit.py
+```
+
+### iOS Code Fixes
+
+```swift
+// Label
+button.accessibilityLabel = "Submit form"
+
+// Hint
+slider.accessibilityHint = "Adjusts volume"
+
+// Identifier
+view.accessibilityIdentifier = "login-button"
+
+// Traits
+label.accessibilityTraits = .header
+```
+
+---
+
+## Module 2 — IDB Quick Reference
+
+_Verbatim from `references/idb_quick.md` at the pinned SHA above._
+
+### UI Automation Commands
+
+#### ui describe-all
+**Usage:** `idb ui describe-all --json --nested`
+**Output:** Complete accessibility tree
+**Key:** Foundation for accessibility auditing
+
+#### ui tap
+**Usage:** `idb ui tap <x> <y>`
+**Output:** None (success) or error
+
+#### ui swipe
+**Usage:** `idb ui swipe <x1> <y1> <x2> <y2>`
+**Output:** None (success) or error
+
+#### ui text
+**Usage:** `idb ui text "<text>"`
+**Output:** None (success) or error
+
+#### ui describe-point
+**Usage:** `idb ui describe-point <x> <y> --json`
+**Output:** Element at coordinates
+
+### Other Essential Commands
+
+#### list-targets
+**Usage:** `idb list-targets`
+**Output:** Available simulators with UDIDs
+
+#### screenshot
+**Usage:** `idb screenshot --udid <udid> output.png`
+**Output:** PNG file saved
+
+#### list-apps
+**Usage:** `idb list-apps --udid <udid>`
+**Output:** Installed apps with bundle IDs
+
+### Common Patterns
+
+```bash
+# Get accessibility tree
+idb ui describe-all --json --nested > tree.json
+
+# Basic interaction
+idb ui tap 200 400
+idb ui text "username@example.com"
+idb ui tap 200 500  # Submit button
+```
+
+### Troubleshooting
+See Module 5 below.
+
+---
+
+## Module 3 — simctl Quick Reference
+
+_Verbatim from `references/simctl_quick.md` at the pinned SHA above._
+
+### Essential Commands Only
+
+#### list devices
+**Usage:** `xcrun simctl list devices`
+**Output:** Device list with UDIDs and states
+**Key:** Use `booted` as UDID for current device
+
+#### boot
+**Usage:** `xcrun simctl boot <device-udid>`
+**Output:** None (success) or error
+
+#### launch
+**Usage:** `xcrun simctl launch booted <bundle-id>`
+**Output:** PID of launched app
+
+#### install
+**Usage:** `xcrun simctl install booted <app-path>`
+**Output:** None (success) or error
+
+#### io screenshot
+**Usage:** `xcrun simctl io booted screenshot <file.png>`
+**Output:** PNG file saved
+**Options:** `--type=png|jpeg` (default: png)
+
+#### io recordVideo
+**Usage:** `xcrun simctl io booted recordVideo <file.mp4>`
+**Output:** Video file (Ctrl+C to stop)
+**Options:** `--codec=h264|hevc` (default: hevc)
+
+#### get_app_container
+**Usage:** `xcrun simctl get_app_container booted <bundle-id> data`
+**Output:** Path to app's data directory
+
+#### spawn log
+**Usage:** `xcrun simctl spawn booted log stream --predicate 'process == "<app>"'`
+**Output:** Live log stream
+
+### Common Patterns
+
+```bash
+# Get booted device UDID
+xcrun simctl list devices | grep Booted
+
+# Quick app test
+xcrun simctl boot <udid>
+xcrun simctl install booted app.app
+xcrun simctl launch booted com.example.app
+xcrun simctl io booted screenshot test.png
+```
+
+### Troubleshooting
+See Module 5 below.
+
+---
+
+## Module 4 — Test Patterns
+
+_Verbatim from `references/test_patterns.md` at the pinned SHA above._
+
+### Smoke Test
+```bash
+xcrun simctl boot <udid>
+xcrun simctl launch booted <bundle-id>
+python scripts/accessibility_audit.py
+xcrun simctl io booted screenshot smoke.png
+```
+
+### Visual Regression
+```bash
+# Baseline
+xcrun simctl io booted screenshot baseline.png
+
+# After changes
+xcrun simctl io booted screenshot current.png
+python scripts/visual_diff.py baseline.png current.png
+```
+
+### Full Accessibility Audit
+```bash
+# Each screen
+for screen in home login settings; do
+  # Navigate to screen (app-specific)
+  python scripts/accessibility_audit.py --output $screen.json
+done
+```
+
+### Bug Report Capture
+```bash
+python scripts/app_state_capture.py \
+  --app-bundle-id com.example.app \
+  --output bug-report/
+```
+
+### Multi-Device Test
+```bash
+for device in "iPhone 15" "iPad Pro"; do
+  udid=$(xcrun simctl create test-$device "$device")
+  xcrun simctl boot $udid
+  xcrun simctl install $udid app.app
+  xcrun simctl launch $udid com.example.app
+  xcrun simctl io $udid screenshot $device.png
+  xcrun simctl delete $udid
+done
+```
+
+### Performance Baseline
+```bash
+# Capture initial state
+xcrun simctl io booted screenshot perf-before.png
+# Run performance test
+xcrun simctl launch booted com.example.app
+sleep 5
+xcrun simctl io booted screenshot perf-after.png
+python scripts/visual_diff.py perf-before.png perf-after.png
+```
+
+### Login Flow Test
+```python
+from scripts.test_recorder import TestRecorder
+
+rec = TestRecorder("Login Test")
+rec.step("Launch app")
+# idb ui tap 200 400  # Login button
+rec.step("Enter credentials")
+# idb ui text "user@example.com"
+rec.step("Submit")
+# idb ui tap 200 500
+rec.generate_report()
+```
+
+---
+
+## Module 5 — Troubleshooting
+
+_Verbatim from `references/troubleshooting.md` at the pinned SHA above._
+
+### Problem → Solution Format
+
+#### Simulator won't boot
+**Fix:** `killall Simulator && xcrun simctl erase <udid>`
+
+#### IDB not connecting
+**Fix:** `idb kill && idb companion --boot-status-check`
+
+#### App won't launch
+**Fix:** `xcrun simctl terminate booted <bundle-id> && xcrun simctl launch booted <bundle-id>`
+
+#### Screenshot fails
+**Fix:** Ensure simulator booted: `xcrun simctl boot <udid>`
+
+#### "No booted devices"
+**Fix:** `open -a Simulator` or `xcrun simctl boot <udid>`
+
+#### IDB "Target not found"
+**Fix:** `idb list-targets` to verify UDID
+
+#### Permission denied
+**Fix:** `chmod +x scripts/*.sh`
+
+#### Python module not found
+**Fix:** `pip3 install pillow` (for visual_diff.py)
+
+#### Accessibility tree empty
+**Fix:** App must be in foreground: `xcrun simctl launch booted <bundle-id>`
+
+#### Video recording hangs
+**Fix:** Ctrl+C to stop recording, file saves on interrupt
+
+#### Logs not showing
+**Fix:** Use correct app name: `xcrun simctl spawn booted log stream --predicate 'process == "AppName"'`
+
+#### Device storage full
+**Fix:** `xcrun simctl erase <udid>` (warning: deletes all data)
+
+### Quick Diagnostics
+
+```bash
+# Check simulator state
+xcrun simctl list devices | grep Booted
+
+# Verify IDB connection
+idb list-targets
+
+# Test basic interaction
+xcrun simctl io booted screenshot test.png
+```
+
+## Source attribution
+
+Modules 1–5 above are reproduced verbatim from
+`conorluddy/ios-simulator-skill` (MIT License) at SHA
+`3acd0717a1b571b1d051559c01ff230d6da28a05`. Header levels were
+demoted by one to integrate with this guideline's outline; module
+content (text, code, command examples) is unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.26.0",
+    "version": "1.27.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,