@appium/mcp-documentation 1.0.3 → 1.0.5

package/src/resources/submodules/appium-skills/AGENTS.md

@@ -0,0 +1,214 @@
+# AGENTS Guide for Appium Skills
+
+This file defines how AI agents should execute the skills in this repository.
+
+## Execution Rules
+
+- Execute skills one at a time in dependency order.
+- Run commands step-by-step; avoid very long chained command blocks.
+- Re-run checks after each fix.
+- Use Appium doctor required fixes as the pass/fail gate:
+  - Pass: `0 required fixes needed`
+  - Optional warnings are non-blocking.
+- Ask before installing optional dependencies.
+- Avoid `sudo` in setup unless the user explicitly requests it.
+- Prefer user-space installs and local project fallbacks when permissions are restricted.
+- Use global npm/Appium commands by default (`npm -g`, `appium`).
+- Use local execution (`npx appium`) only when the user explicitly asks for a local mode.
+- Use `environment-setup-ffmpeg` as a shared optional dependency across drivers only when the user explicitly requests FFmpeg-related setup.
+- Use `environment-setup-bundletool` as a shared optional dependency for UiAutomator2/Espresso only when the user explicitly requests bundletool setup.
+- If output is incomplete/truncated, rerun only that step and capture logs.
+
+## Recommended Skill Order
+
+### Android + UiAutomator2
+
+1. `environment-setup-node`
+2. `environment-setup-android`
+3. `environment-setup-uiautomator2`
+
+### Android + Espresso
+
+1. `environment-setup-node`
+2. `environment-setup-android`
+3. `environment-setup-espresso`
+
+### Desktop Chromium Browsers (Chrome/Chromium/Edge)
+
+1. `environment-setup-node`
+2. `environment-setup-chromium`
+
+### Shared Optional Skill
+
+1. `environment-setup-ffmpeg` (run only when user explicitly requests FFmpeg-related capabilities)
+2. `environment-setup-bundletool` (run only when user explicitly requests bundletool setup for UiAutomator2/Espresso)
+
+### iOS + XCUITest (macOS only)
+
+1. `environment-setup-node`
+2. `environment-setup-xcuitest`
+
+### iOS + XCUITest + Real Device (macOS only)
+
+1. `environment-setup-node`
+2. `environment-setup-xcuitest`
+3. `xcuitest-real-device-config`
+
+### Troubleshooting
+
+1. If prerequisites or doctor checks are failing, run the relevant environment setup skill first.
+2. Then run `appium-troubleshooting` in the failing driver path and load only the platform reference files that match the symptom.
+
+## Completion Policy
+
+A skill is complete only when its own completion criteria in `SKILL.md` are satisfied.
+
+- Required doctor checks must pass.
+- Optional doctor warnings do not block completion.
+- Validate global command mode (`appium`) as the default completion path.
+- Validate local command mode (`npx appium`) only when the user explicitly requests local execution.
+
+## Prompt Templates
+
+### Template: UiAutomator2
+
+Use this as a starting prompt for an AI agent:
+
+```text
+Use this repository's skills to prepare Android + UiAutomator2.
+Follow exactly, in order:
+1) skills/environment-setup-node/SKILL.md
+2) skills/environment-setup-android/SKILL.md
+3) skills/environment-setup-uiautomator2/SKILL.md
+
+Rules:
+  1) Start Appium server in Terminal A (`appium server`) and keep it running.
+  2) In Terminal B run `curl -s http://127.0.0.1:4723/status` and confirm success.
+  3) In Terminal A logs confirm `Available drivers:` contains `uiautomator2`.
+  4) In Terminal A stop Appium with `Ctrl+C`, then in Terminal B run `pgrep -fl "appium.*server" || echo "no appium server process"`.
+```
+
+### Template: Espresso
+
+Use this as a starting prompt for an AI agent:
+
+```text
+Use this repository's skills to prepare Android + Espresso.
+Follow exactly, in order:
+1) skills/environment-setup-node/SKILL.md
+2) skills/environment-setup-android/SKILL.md
+3) skills/environment-setup-espresso/SKILL.md
+
+Rules:
+- Run one step at a time.
+- Treat `appium driver doctor espresso` required fixes as blocking.
+- Optional warnings are non-blocking.
+- Ask before installing optional dependencies.
+- Do not use sudo unless I explicitly ask.
+- Show command output for each step.
+- Smoke test sequence:
+  1) Start Appium server in Terminal A (`appium server`) and keep it running.
+  2) In Terminal B run `curl -s http://127.0.0.1:4723/status` and confirm success.
+  3) In Terminal A logs confirm `Available drivers:` contains `espresso`.
+  4) In Terminal A stop Appium with `Ctrl+C`, then in Terminal B run `pgrep -fl "appium.*server" || echo "no appium server process"`.
+```
+
+### Template: XCUITest
+
+Use this as a starting prompt for an AI agent:
+
+```text
+Use this repository's skills to prepare macOS + XCUITest.
+Follow exactly, in order:
+1) skills/environment-setup-node/SKILL.md
+2) skills/environment-setup-xcuitest/SKILL.md
+
+Rules:
+- Run one step at a time.
+- Treat `appium driver doctor xcuitest` required fixes as blocking.
+- Optional warnings are non-blocking.
+- Ask before installing optional dependencies.
+- Do not use sudo unless I explicitly ask.
+- Show command output for each step.
+- Smoke test sequence:
+  1) Start Appium server in Terminal A (`appium server`) and keep it running.
+  2) In Terminal B run `curl -s http://127.0.0.1:4723/status` and confirm success.
+  3) In Terminal A logs confirm `Available drivers:` contains `xcuitest`.
+  4) In Terminal A stop Appium with `Ctrl+C`, then in Terminal B run `pgrep -fl "appium.*server" || echo "no appium server process"`.
+```
+
+### Template: Chromium
+
+Use this as a starting prompt for an AI agent:
+
+```text
+Use this repository's skills to prepare Appium Chromium Driver for desktop browser automation.
+Follow exactly, in order:
+1) skills/environment-setup-node/SKILL.md
+2) skills/environment-setup-chromium/SKILL.md
+
+Rules:
+- Run one step at a time.
+- If `appium driver doctor chromium` is supported, treat required fixes as blocking.
+- If doctor is not supported for `chromium`, use install/list/smoke checks as blocking gates.
+- Optional warnings are non-blocking.
+- Ask before installing optional dependencies.
+- Do not use sudo unless I explicitly ask.
+- Show command output for each step.
+- Smoke test sequence:
+  1) Start Appium server in Terminal A (`appium server`) and keep it running.
+  2) In Terminal B run `curl -s http://127.0.0.1:4723/status` and confirm success.
+  3) In Terminal A logs confirm `Available drivers:` contains `chromium`.
+  4) In Terminal A stop Appium with `Ctrl+C`, then in Terminal B run `pgrep -fl "appium.*server" || echo "no appium server process"`.
+```
+
+### Template: XCUITest Real Device
+
+Use this as a starting prompt for an AI agent:
+
+```text
+Use this repository's skills to prepare macOS + XCUITest for a real iOS/tvOS device.
+Follow exactly, in order:
+1) skills/environment-setup-node/SKILL.md
+2) skills/environment-setup-xcuitest/SKILL.md
+3) skills/xcuitest-real-device-config/SKILL.md
+
+Rules:
+- Run one step at a time.
+- Complete environment-setup-xcuitest before starting xcuitest-real-device-config.
+- Ask before installing optional 3rd-party device tools (ios-deploy, go-ios, pymobiledevice3, tidevice).
+- Do not use sudo unless I explicitly ask.
+- For steps requiring physical device interaction (Trust popup, Developer Mode toggle), pause and give the exact on-device instruction.
+- Show command output for each step.
+- When the WDA bundle is modified after signing (frameworks removed for iOS 17+), always re-sign with `codesign` before installing.
+- Completion criteria:
+  1) Device is visible in `xcrun xctrace list devices`.
+  2) A provisioning profile approach has been fully applied (no code-signing errors on WDA install).
+  3) If any WDA bundle was modified, `codesign --verify --verbose` confirms a valid signature.
+  4) At least one WDA deployment method is confirmed working (default xcodebuild, preinstalled, prebuilt, or attach).
+```
+
+### Template: Troubleshooting
+
+Use this as a starting prompt for an AI agent:
+
+```text
+Use this repository's troubleshooting skill to diagnose an Appium failure.
+Follow this order:
+1) If setup or doctor output is failing, run the matching environment setup skill first.
+2) skills/appium-troubleshooting/SKILL.md
+
+Rules:
+- Run one step at a time.
+- Keep troubleshooting scoped to the failing driver unless the user explicitly asks for cross-driver comparison.
+- Re-run the smallest failing check after each fix.
+- Treat Appium doctor required fixes as blocking.
+- Prefer the official Appium references bundled with the troubleshooting skill before using discuss.appium.io.
+- Use discuss.appium.io only when the official references do not explain the exact stack trace or symptom.
+- Show command output for each step.
+```
+
+## Notes for Tooling Integrations
+
+- If your agent platform supports repository-level instruction files, prioritize this file before running skill commands.
+- If your platform does not auto-load this file, copy one prompt template above and provide it manually.

package/src/resources/submodules/appium-skills/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright OpenJS Foundation and other contributors, https://openjsf.org/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/src/resources/submodules/appium-skills/README.md

@@ -0,0 +1,33 @@
+# Appium Agent Skills
+
+This repository contains AI Agent skills for helping with Appium automation, including environment setup, real-device configuration, and troubleshooting common failures.
+
+## Available Skills
+
+| Skill | Description |
+|---|---|
+| [environment-setup-node](skills/environment-setup-node/SKILL.md) | Prepares Node.js and npm environment |
+| [environment-setup-android](skills/environment-setup-android/SKILL.md) | Prepares Android SDK, Java, and ADB prerequisites for Appium Android drivers |
+| [environment-setup-ffmpeg](skills/environment-setup-ffmpeg/SKILL.md) | Optional shared FFmpeg setup for media-related capabilities across drivers |
+| [environment-setup-bundletool](skills/environment-setup-bundletool/SKILL.md) | Optional shared bundletool.jar setup for UiAutomator2/Espresso app-bundle tooling |
+| [environment-setup-uiautomator2](skills/environment-setup-uiautomator2/SKILL.md) | Prepares and validates an Android + UiAutomator2 Appium environment |
+| [environment-setup-espresso](skills/environment-setup-espresso/SKILL.md) | Prepares and validates an Android + Espresso Appium environment |
+| [environment-setup-chromium](skills/environment-setup-chromium/SKILL.md) | Prepares and validates an Appium Chromium Driver environment for desktop Chromium-based browsers |
+| [environment-setup-xcuitest](skills/environment-setup-xcuitest/SKILL.md) | Prepares and validates a macOS + XCUITest Appium environment |
+| [appium-troubleshooting](skills/appium-troubleshooting/SKILL.md) | Troubleshoots UiAutomator2 or XCUITest failures with a driver-scoped workflow that starts from the failing symptom and re-checks the smallest reproduction after each fix |
+| [xcuitest-real-device-config](skills/xcuitest-real-device-config/SKILL.md) | Prepare a real iOS/tvOS device for Appium XCUITest automation |
+
+## Reliable Execution Notes
+
+- Run skill commands step-by-step rather than as one very long chained command.
+- For long-running checks, prefer an isolated background terminal and capture output after completion.
+- If output appears incomplete, rerun only the affected step and collect logs from that step.
+- Treat Appium doctor as the source of truth for pass/fail (`0 required fixes needed`).
+- For FFmpeg-dependent capabilities, run the optional shared skill `environment-setup-ffmpeg` only when explicitly requested.
+- For bundletool-dependent capabilities, run the optional shared skill `environment-setup-bundletool` only when explicitly requested.
+- For startup, WDA, or locator failures after setup is complete, use `appium-troubleshooting` in a single driver path and follow the checks documented in that skill.
+
+## Agent Instructions
+
+- See [AGENTS.md](AGENTS.md) for strict execution rules and copy-paste prompt templates.
+- Use the template matching your target (`uiautomator2`, `espresso`, `chromium`, `xcuitest`, `xcuitest real device`, or `troubleshooting`) and run skills in the documented order.

package/src/resources/submodules/appium-skills/skills/appium-troubleshooting/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: "appium-troubleshooting"
+description: "Diagnose common Appium failures with a driver-scoped flow for UiAutomator2 or XCUITest, covering startup, driver readiness, WebDriverAgent, and element lookup issues"
+metadata:
+  last_modified: "Thu, 19 Mar 2026 12:00:00 GMT"
+
+---
+# appium-troubleshooting
+
+## Goal
+Help the agent narrow a single-driver Appium failure into a small set of common buckets, apply the smallest plausible fix, and re-run the failing check until the root cause is confirmed or clearly handed back to the user.
+
+## Decision Logic
+- Identify the active automation driver first (`uiautomator2` or `xcuitest`). If unknown, stop and ask for the failing session capabilities/log line that names the driver.
+- If the failure is an environment or driver-install problem (`node`, `npm`, `appium`, Java, Android SDK, `Xcode`, doctor failures): run the matching setup skill for the selected driver first.
+- UiAutomator2 path only:
+  - session startup, wrong activity, early drop, or `socket hang up`: read [references/uiautomator2-session-startup.md](references/uiautomator2-session-startup.md).
+  - locator issues: read [references/uiautomator2-locators.md](references/uiautomator2-locators.md).
+- XCUITest path only:
+  - WebDriverAgent startup/install/reachability, app install/launch, device/simulator state: read [references/xcuitest-troubleshooting.md](references/xcuitest-troubleshooting.md).
+  - element lookup or locator issues: read [references/xcuitest-element-lookup.md](references/xcuitest-element-lookup.md) and [references/xcuitest-locators.md](references/xcuitest-locators.md).
+- If the official docs do not explain the exact stack trace or symptom, use [references/community-search.md](references/community-search.md) as a fallback workflow.
+
+## Instructions
+1. **Capture the failing command and lock the driver scope**
+   Record the exact error text, platform, automation driver, and relevant capabilities before changing anything. If the driver is still unclear, ask for one of these before continuing:
+   - the desired capabilities block containing `platformName` and `appium:automationName`
+   - the Appium server log lines from `POST /session` through the first real error after `createSession`
+   If the client hides capabilities, rerun one failing session with Appium server logs enabled and capture that window before troubleshooting further.
+
+2. **Run baseline checks only when the error message alone is not enough**
+   If the error text already points to a known issue, open the matching driver-specific official reference first and confirm the closest symptom before changing anything. Then collect what is needed:
+   - `appium -v` and `appium driver list --installed --json` (fallback to `appium driver list --installed` if `--json` is unsupported) — to confirm driver presence and version.
+   - UiAutomator2: `adb devices -l` and `appium driver doctor uiautomator2` — only if the error suggests a device connectivity or prerequisite problem.
+   - XCUITest: `xcodebuild -version` and `appium driver doctor xcuitest` — only if the error suggests a build, signing, or toolchain problem.
+   If any doctor or prerequisite check fails, switch to the matching setup skill before deeper troubleshooting. Use `references/community-search.md` only after the relevant official reference does not explain the exact stack trace or symptom.
+
+3. **Open only the references that match the selected driver and symptom**
+   Do not load both driver branches in one run. Start with the most direct reference for the observed symptom and only expand if that file does not explain the behavior.
+
+4. **Apply one targeted change, then re-run the smallest failing check**
+   Prefer narrow fixes such as capability corrections, driver cleanup, device reset, or locator updates before broader environment churn. Re-run the doctor command for prerequisite issues, the failing session launch for startup issues, or the failing locator lookup for element issues.
+
+5. **Use official docs first, community second**
+   Official references for this skill:
+   - `https://appium.io/docs/en/latest/`
+   - `https://github.com/appium/appium-uiautomator2-driver`
+   - `https://appium.github.io/appium-xcuitest-driver/latest/`
+   - `https://github.com/appium/appium-xcuitest-driver`
+   Use `discuss.appium.io` only after the official references are exhausted, searching with exact error text plus driver name and platform version.
+
+6. **Report the outcome with command evidence**
+   Include the baseline checks you ran, the change you made, and the smallest reproduction or check you re-ran to confirm the result.
+
+## Completion Criteria
+Mark troubleshooting complete only when one of these is true:
+- the failing check passes after a verified fix, or
+- the exact blocker is isolated to something the user must do manually (for example signing, device trust, app build defects), with the relevant command output and next action captured
+
+## Constraints
+- Run commands one step at a time and re-run checks after each fix.
+- Treat Appium doctor output `0 required fixes needed` as the pass/fail gate; optional warnings are non-blocking.
+- Use global `appium` command mode by default unless the user explicitly asks for local `npx appium`.
+- Prefer the official Appium driver docs referenced by this skill before using community answers.
+- Keep troubleshooting scoped to one driver path (`uiautomator2` or `xcuitest`) per run unless the user explicitly asks for cross-driver comparison.
+- Do not claim success from a theory alone; always tie the conclusion to a reproduced symptom or a passing re-check.

package/src/resources/submodules/appium-skills/skills/appium-troubleshooting/references/community-search.md

@@ -0,0 +1,51 @@
+# Community Search Fallback
+
+## Source
+- `https://discuss.appium.io/`
+
+## Official-First Rule
+Use community search only after checking the matching official Appium reference first:
+
+- UiAutomator2 startup: `https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/activity-startup.md`
+- UiAutomator2 locators: `https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#element-location`
+- XCUITest element lookup: `https://appium.github.io/appium-xcuitest-driver/latest/guides/elements-lookup-troubleshooting/`
+- XCUITest locators: `https://appium.github.io/appium-xcuitest-driver/latest/reference/locator-strategies/`
+- XCUITest general failures: `https://appium.github.io/appium-xcuitest-driver/latest/guides/troubleshooting/`
+
+## Search Pattern
+- Search the exact error string in quotes.
+- Add the driver name: `uiautomator2` or `xcuitest`.
+- Add the platform version and whether the target is a real device or simulator/emulator.
+- Add the capability name if the issue appears right after changing one capability.
+
+Example queries:
+- `"socket hang up" uiautomator2 Android 14 emulator`
+- `"Activity never started" appWaitActivity uiautomator2`
+- `"WebDriverAgent" xcuitest iOS 18 real device`
+- `"No matches found for Identity Binding" xcuitest`
+
+## Offline Triage Before Searching
+
+Use one of these recurring cases to choose a search query and one local verification step. Keep the detailed remediation in the official references whenever possible.
+
+| Case | Search Query Seed | Verify First |
+|---|---|---|
+| UiAutomator2 wrong startup screen or `Activity never started` | `"Activity never started" appWaitActivity uiautomator2` | confirm the focused activity via `adb shell dumpsys activity activities` |
+| UiAutomator2 early session drop or `socket hang up` | `"socket hang up" uiautomator2 <android-version> <device-type>` | capture `adb logcat -d` and retry one clean session |
+| UiAutomator2 WebView or Chromedriver mismatch | `"chromedriver" uiautomator2 webview` | confirm the WebView/browser version on the device before changing Chromedriver settings |
+| XCUITest WDA build or signing failure | `"WebDriverAgent" "xcodebuild" failed xcuitest` | run `appium driver doctor xcuitest` and verify the signing setup |
+| XCUITest WDA timeout or proxy failure | `"Could not proxy command to remote server" xcuitest` | capture fresh Appium logs and confirm WDA reachability |
+| XCUITest source tree incomplete or element missing | `"elements not visible in source" xcuitest inspector` | collect a fresh source snapshot and verify accessibility exposure or active context |
+
+## How To Filter Results
+- Prefer threads that mention the same Appium major version and the same driver.
+- Prefer posts that include logs or cite official Appium docs.
+- Treat advice that suggests broad resets or unrelated capability changes as low confidence until you can verify it locally.
+
+## Accept/Reject Rule For Forum Advice
+- Accept only if the suggestion maps directly to your exact error text, same driver, and similar OS/device version.
+- Reject or defer suggestions that require unrelated global resets before reproducing the same failure once.
+- Always re-run the smallest failing check immediately after applying a proposed fix.
+
+## Validation Rule
+Never close the issue from a forum answer alone. Reproduce the proposed fix locally and tie it back to the original failing command or locator.

package/src/resources/submodules/appium-skills/skills/appium-troubleshooting/references/uiautomator2-locators.md

@@ -0,0 +1,34 @@
+# UiAutomator2 Locators
+
+## Official Reference
+- `https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#element-location`
+
+Use the driver docs for the full strategy list and performance tradeoffs. Keep this page for the extra triage that is easy to miss during debugging.
+
+## Local Guidance
+- Inspect the current page source before changing the selector. Verify whether the target is exposed as `content-desc`, resource id, text, or only as a visual label.
+- If the app is hybrid, confirm the current context before debugging native locators.
+- `-android uiautomator` is useful when ids or accessibility metadata are missing, but keep the query narrow and readable enough to debug from logs.
+- Treat a working `xpath` as proof that the node exists, not as the preferred final fix. Replace it with a stronger native locator when the source exposes one.
+- If the node is not present in source at all, this is usually an app-state, accessibility, or context problem rather than locator syntax.
+
+## Hybrid App Checks
+- If the element is inside a WebView, confirm the failing lookup is happening in a `WEBVIEW_*` context rather than `NATIVE_APP`.
+- If the failure started after a Chrome or Android System WebView update, confirm the WebView/browser version before changing Chromedriver settings.
+- Use the UiAutomator2 driver's Chromedriver compatibility guidance before community fallback. Prefer `appium:chromedriverExecutable`, `appium:chromedriverExecutableDir`, or automatic Chromedriver discovery over ad hoc workarounds.
+- If the node exists only in the WebView DOM and not in native page source, switch context first and re-run the same single lookup before changing selectors.
+
+## Hybrid App Checks With Commands
+```bash
+adb shell dumpsys package com.android.chrome | grep versionName
+adb shell dumpsys package com.google.android.webview | grep versionName
+adb shell dumpsys package com.android.webview | grep versionName
+```
+- Capture the current context list from the failing client run and confirm the target lookup is using the expected `WEBVIEW_*` context.
+- Capture one source snapshot from `NATIVE_APP` and one from the target `WEBVIEW_*` context on the same screen. If the element appears only in the WebView DOM, switch context before changing selectors.
+- If Chromedriver is the likely mismatch, prefer updating `appium:chromedriverExecutable`, `appium:chromedriverExecutableDir`, or the Chromedriver mapping instead of rewriting the locator first.
+
+## Validation
+- Re-run the smallest failing lookup.
+- Compare the returned attributes against the actual source dump.
+- If an `xpath` fix works but a stronger native locator is available, prefer the native locator before closing the issue.

package/src/resources/submodules/appium-skills/skills/appium-troubleshooting/references/uiautomator2-session-startup.md

@@ -0,0 +1,53 @@
+# UiAutomator2 Session Startup
+
+## Official References
+- `https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/activity-startup.md`
+- `https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#troubleshooting`
+
+## When To Read This
+- `Activity never started`
+- app launches the wrong screen or splash flow
+- `appWaitActivity` or `appWaitPackage` mismatches
+- `socket hang up`
+- the UiAutomator2 server appears to die during startup
+
+This file is a shortcut into the official driver docs, not a replacement for them.
+
+## Local Triage
+1. Verify the package and foreground activity from the device state, not from the manifest guess.
+2. Align `appium:appPackage`, `appium:appActivity`, `appium:appWaitPackage`, and `appium:appWaitActivity` with the observed startup flow.
+3. If the app legitimately passes through multiple transient activities, list those wait activities explicitly before increasing `appium:appWaitDuration`.
+4. If logs show `socket hang up`, instrumentation failure, or helper-package errors, treat it as a UiAutomator2 helper or `adb` transport problem first.
+5. If logs show install, ABI, permission, or signing failures, stop tuning startup capabilities and fix that underlying failure first.
+
+## Log Clues To Separate Common Causes
+- Activity mismatch is more likely if `adb shell dumpsys activity activities` shows a different foreground activity than the one implied by `appium:appActivity` or `appium:appWaitActivity`, or if Appium reports `Activity never started`.
+- A UiAutomator2 server crash is more likely if `adb logcat -d` shows instrumentation failure, `io.appium.uiautomator2.server` package errors, or the Appium log says it cannot connect to the UiAutomator2 REST server.
+- An `adb` transport drop is more likely if the device disappears from `adb devices -l`, the Appium log shows proxy/connectivity resets, or multiple commands fail immediately after `adb` communication errors.
+
+## Minimal Checks
+```bash
+adb shell dumpsys window windows
+adb shell dumpsys activity activities
+adb shell pm list packages
+adb logcat -d
+grep -i "socket hang up\|uiautomator2\|instrumentation\|adb\|cannot connect" <appium-server-log-file>
+```
+
+## First Pass Order
+1. Capture `dumpsys activity`, `adb logcat -d`, and the matching Appium server log lines from the failing session.
+2. Decide whether the first failure signal is activity mismatch, UiAutomator2 server crash, or `adb` transport loss.
+3. Apply only the fix for that first signal.
+4. Re-run one fresh session start before changing anything else.
+
+## One Clean Retry
+If startup still dies early after the first log review, do one clean retry:
+
+```bash
+adb kill-server
+adb start-server
+adb uninstall io.appium.uiautomator2.server
+adb uninstall io.appium.uiautomator2.server.test
+```
+
+Then re-run the same single session launch and compare fresh logs before changing anything else.