docs: move better strucure

contexts/tools/appium/setup/references/chromium/chromium-browser-prereqs.md → contexts/browser/chromium/prereqs.md

@@ -1,12 +1,13 @@
 ---
 owner: appium
-id: appium.setup.references.chromium.chromium-browser-prereqs
-name: "chromium-browser-prereqs"
+id: browser.chromium.prereqs
+name: "chromium-prereqs"
 description: "Install or validate Chrome, Chromium, Edge, and Linux browser dependencies"
+status: stable
 
 ---
 
-# chromium-browser-prereqs
+# Chromium Browser Prerequisites
 
 ## Browser Checks
 

contexts/tools/appium/setup/references/gecko/gecko-browser-prereqs.md → contexts/browser/firefox/prereqs.md

@@ -1,12 +1,13 @@
 ---
 owner: appium
-id: appium.setup.references.gecko.gecko-browser-prereqs
-name: "gecko-browser-prereqs"
-description: "Validate Firefox browser availability and host prerequisites for Appium Gecko Driver"
+id: browser.firefox.prereqs
+name: "firefox-prereqs"
+description: "Validate Firefox browser availability and host prerequisites"
+status: stable
 
 ---
 
-# gecko-browser-prereqs
+# Firefox Browser Prerequisites
 
 ## Firefox Detection
 

contexts/browser/safari/prereqs.md

@@ -0,0 +1,32 @@
+---
+owner: appium
+id: browser.safari.prereqs
+name: "safari-prereqs"
+description: "Validate Safari and safaridriver availability plus macOS automation authorization boundaries"
+status: stable
+---
+
+# Safari Browser Prerequisites
+
+## Goal
+
+Validate Safari browser automation prerequisites that are not specific to Appium driver installation.
+
+## Checks
+
+Run read-only checks before changing Safari automation state:
+
+```bash
+sw_vers
+safaridriver --version
+```
+
+## Authorization Boundary
+
+- If `safaridriver` is missing, stop and repair Safari or macOS tooling before Appium driver work.
+- Run `safaridriver --enable` only when Safari automation is required and the user can accept the macOS authorization prompt.
+- Treat Safari automation authorization as an explicit user approval step, not automatic setup.
+
+## Evidence To Report
+
+Report macOS version, `safaridriver --version`, whether Safari automation was already enabled or explicitly enabled, and any user action still required.

contexts/tools/appium/setup/references/environment-setup-bundletool.md → contexts/platform/android/bundletool.md

@@ -1,12 +1,13 @@
 ---
 owner: appium
-id: appium.setup.references.environment-setup-bundletool
-name: "environment-setup-bundletool"
+id: platform.android.bundletool
+name: "android-bundletool"
 description: "Route optional bundletool.jar setup for Android App Bundle support"
+status: stable
 
 ---
 
-# environment-setup-bundletool
+# Android Bundletool
 
 ## Goal
 
@@ -16,9 +17,9 @@ Install and validate `bundletool.jar` from official Google bundletool releases o
 
 Load these references in order:
 
-1. `contexts/tools/appium/setup/references/bundletool/bundletool-decision-logic.md` for optional-use gates and install triggers.
-2. `contexts/tools/appium/setup/references/bundletool/bundletool-install.md` for download and PATH setup.
-3. `contexts/tools/appium/setup/references/bundletool/bundletool-validation.md` for version evidence and completion criteria.
+1. `contexts/platform/android/references/bundletool/decision-logic.md` for optional-use gates and install triggers.
+2. `contexts/platform/android/references/bundletool/install.md` for download and PATH setup.
+3. `contexts/platform/android/references/bundletool/validation.md` for version evidence and completion criteria.
 
 ## Validation Command
 

contexts/tools/appium/setup/android-decision-logic.md → contexts/platform/android/decision-logic.md

@@ -2,7 +2,7 @@
 owner: appium
 id: setup-references-android-android-decision-logic
 status: stable
-source: contexts/tools/appium/setup/android-decision-logic.md
+source: contexts/platform/android/decision-logic.md
 
 ---
 

contexts/tools/appium/setup/references/environment-setup-android.md → contexts/platform/android/emulator-setup.md

@@ -1,13 +1,13 @@
 ---
 owner: appium
-id: appium.setup.references.environment-setup-android
-name: "environment-setup-android"
-description: "Route Android SDK, Java, ADB, package, and emulator setup references for Appium Android drivers"
+id: platform.android.emulator-setup
+name: "android-emulator-setup"
+description: "Route Android SDK, Java, ADB, package, device, and emulator setup references for Android automation"
 last_modified: "Mon, 27 Apr 2026 GMT"
 
 ---
 
-# environment-setup-android
+# Android Emulator Setup
 
 ## Goal
 
@@ -17,12 +17,12 @@ Prepare Android automation by validating Java, Android SDK command-line tools, S
 
 Load these references in order:
 
-1. `contexts/tools/appium/setup/android-decision-logic.md` for supported hosts, preservation rules, optional dependency boundaries, and install triggers.
-2. `android/android-detect-base-tooling.md` for OS, Java, Android SDK, ADB, and emulator binary detection.
-3. `android/android-sdk-commandline-tools.md` for platform default SDK paths and command-line tools bootstrap.
-4. `android/android-java-configuration.md` for Java setup only when `java` or `javac` is missing.
-5. `android/android-sdk-packages-and-path.md` for `ANDROID_HOME`, `PATH`, licenses, and required SDK packages.
-6. `android/android-device-emulator-validation.md` for device inventory, emulator creation, final validation, and evidence.
+1. `contexts/platform/android/decision-logic.md` for supported hosts, preservation rules, optional dependency boundaries, and install triggers.
+2. `contexts/platform/android/references/detect-base-tooling.md` for OS, Java, Android SDK, ADB, and emulator binary detection.
+3. `contexts/platform/android/references/sdk-commandline-tools.md` for platform default SDK paths and command-line tools bootstrap.
+4. `contexts/platform/android/references/java-configuration.md` for Java setup only when `java` or `javac` is missing.
+5. `contexts/platform/android/references/sdk-packages-and-path.md` for `ANDROID_HOME`, `PATH`, licenses, and required SDK packages.
+6. `contexts/platform/android/references/device-emulator-validation.md` for device inventory, emulator creation, final validation, and evidence.
 
 For deterministic read-only validation, run:
 

contexts/tools/appium/setup/references/bundletool/bundletool-decision-logic.md → contexts/platform/android/references/bundletool/decision-logic.md

@@ -1,8 +1,9 @@
 ---
 owner: appium
-id: appium.setup.references.bundletool.bundletool-decision-logic
+id: platform.android.bundletool.decision-logic
 name: "bundletool-decision-logic"
 description: "Optional bundletool setup gates and install triggers"
+status: stable
 
 ---
 

contexts/tools/appium/setup/references/bundletool/bundletool-install.md → contexts/platform/android/references/bundletool/install.md

@@ -1,8 +1,9 @@
 ---
 owner: appium
-id: appium.setup.references.bundletool.bundletool-install
+id: platform.android.bundletool.install
 name: "bundletool-install"
 description: "Download bundletool.jar from official GitHub releases and place it on user PATH"
+status: stable
 
 ---
 

contexts/tools/appium/setup/references/bundletool/bundletool-validation.md → contexts/platform/android/references/bundletool/validation.md

@@ -1,8 +1,9 @@
 ---
 owner: appium
-id: appium.setup.references.bundletool.bundletool-validation
+id: platform.android.bundletool.validation
 name: "bundletool-validation"
 description: "Validate bundletool.jar path, version, and setup evidence"
+status: stable
 
 ---
 

contexts/tools/appium/setup/references/environment-setup-xcuitest.md → contexts/platform/ios/simulator-setup.md

@@ -1,12 +1,12 @@
 ---
 owner: appium
-id: appium.setup.references.environment-setup-xcuitest
-name: "environment-setup-xcuitest"
-description: "Route macOS XCUITest Appium driver setup, Xcode validation, doctor checks, and smoke tests"
+id: platform.ios.simulator-setup
+name: "ios-simulator-setup"
+description: "Route iOS simulator, Xcode, XCUITest driver, doctor, and smoke validation setup"
 
 ---
 
-# appium-xcuitest-environment-setup
+# iOS Simulator Setup
 
 ## Goal
 
@@ -16,9 +16,9 @@ Prepare Appium XCUITest on macOS by validating Node/Appium, Xcode, driver instal
 
 Load these references in order:
 
-1. `contexts/tools/appium/setup/node-environment.md` for Node.js and npm.
+1. `contexts/tools/appium/setup-basics.md` for Node.js and npm.
 2. `contexts/tools/appium/setup/references/xcuitest/xcuitest-decision-logic.md` for macOS-only setup gates and optional dependency boundaries.
-3. `contexts/tools/appium/setup/references/xcuitest/xcuitest-xcode-prereqs.md` for Xcode, command-line tools, license, and first-launch checks.
+3. `contexts/platform/macos/xcode-prereqs.md` for Xcode, command-line tools, license, and first-launch checks.
 4. `contexts/tools/appium/setup/references/xcuitest/xcuitest-driver-doctor.md` for driver install and doctor pass criteria.
 5. `contexts/tools/appium/setup/references/xcuitest/xcuitest-smoke-status.md` for simulator inventory, `/status`, log evidence, and cleanup.
 

contexts/tools/appium/setup/profiles/linux.md → contexts/platform/linux/profile.md

@@ -1,13 +1,12 @@
 ---
 owner: appium
-id: appium.setup.profiles.linux
+id: platform.linux.profile
+status: stable
 
 ---
 
 # Linux Setup Profile
 
-Base skill: `skills/setup/SKILL.md`
-
 Use this profile when setup is running on Linux.
 
 - Prefer user-space installs and require explicit human approval before privileged package-manager elevation.

contexts/tools/appium/setup/profiles/macos.md → contexts/platform/macos/profile.md

@@ -1,13 +1,12 @@
 ---
 owner: appium
-id: appium.setup.profiles.macos
+id: platform.macos.profile
+status: stable
 
 ---
 
 # macOS Setup Profile
 
-Base skill: `skills/setup/SKILL.md`
-
 Use this profile when setup is running on macOS.
 
 - Prefer user-space installs and require explicit human approval before privileged elevation.

contexts/tools/appium/setup/references/mac2/mac2-xcode-prereqs.md → contexts/platform/macos/xcode-command-line-tools.md

@@ -1,12 +1,13 @@
 ---
 owner: appium
-id: appium.setup.references.mac2.mac2-xcode-prereqs
-name: "mac2-xcode-prereqs"
-description: "Validate Xcode and macOS command-line tooling for Appium Mac2 Driver"
+id: platform.macos.xcode-command-line-tools
+name: "macos-xcode-command-line-tools"
+description: "Validate Xcode and macOS command-line tooling for macOS automation"
+status: stable
 
 ---
 
-# mac2-xcode-prereqs
+# macOS Xcode Command-Line Tools
 
 ## Read-Only Checks
 

contexts/tools/appium/setup/references/xcuitest/xcuitest-xcode-prereqs.md → contexts/platform/macos/xcode-prereqs.md

@@ -1,12 +1,13 @@
 ---
 owner: appium
-id: appium.setup.references.xcuitest.xcuitest-xcode-prereqs
-name: "xcuitest-xcode-prereqs"
+id: platform.macos.xcode-prereqs
+name: "macos-xcode-prereqs"
 description: "Validate Xcode, command-line tools, license, first launch, and simulator inventory"
+status: stable
 
 ---
 
-# xcuitest-xcode-prereqs
+# macOS Xcode Prerequisites
 
 ## Xcode Checks
 

contexts/tools/appium/setup/profiles/windows.md → contexts/platform/windows/profile.md

@@ -1,13 +1,12 @@
 ---
 owner: appium
-id: appium.setup.profiles.windows
+id: platform.windows.profile
+status: stable
 
 ---
 
 # Windows Setup Profile
 
-Base skill: `skills/setup/SKILL.md`
-
 Use this profile when setup is running on Windows or PowerShell.
 
 - Prefer `winget` for Node.js manager setup when no maintained version manager exists.

contexts/tools/appium/capabilities.md

@@ -0,0 +1,23 @@
+---
+owner: appium
+id: appium.capabilities
+status: experimental
+---
+
+# Appium Capabilities
+
+## Goal
+
+Use this context when a workflow needs shared Appium capability guidance that is not specific to one setup or troubleshooting procedure.
+
+## Rules
+
+- Identify `platformName` and `appium:automationName` before selecting a driver-specific setup, troubleshooting, or real-device route.
+- Keep capability changes narrow and tied to the observed failure, requested feature, or validated device mode.
+- Prefer W3C namespaced Appium capabilities such as `appium:automationName`, `appium:deviceName`, `appium:app`, and `appium:platformVersion`.
+- Do not use optional capability families such as media recording, app bundle handling, or prebuilt WebDriverAgent unless the user explicitly asks for the related feature or the selected route requires it.
+- For real iOS or tvOS devices, load `skills/xcuitest-real-device-config/SKILL.md` before recommending signing, provisioning, or WebDriverAgent deployment capabilities.
+
+## Evidence To Report
+
+Report the smallest relevant capabilities block, the driver or platform assumption it depends on, and any optional capability that was intentionally skipped.

contexts/tools/appium/real-device/examples/real-device.md

@@ -9,10 +9,10 @@ id: appium.real-device.examples.real-device
 Use this repository's skills to prepare macOS + XCUITest for a real iOS or tvOS device.
 
 1. Load `skills/setup/SKILL.md`.
-2. Load `contexts/tools/appium/setup/profiles/macos.md`.
+2. Load `contexts/platform/macos/profile.md`.
 3. Load `contexts/tools/appium/setup/profiles/xcuitest.md`.
-4. Load `contexts/tools/appium/setup/node-environment.md`.
-5. Load `contexts/tools/appium/setup/references/environment-setup-xcuitest.md`.
+4. Load `contexts/tools/appium/setup-basics.md`.
+5. Load `contexts/platform/ios/simulator-setup.md`.
 6. Load `skills/xcuitest-real-device-config/SKILL.md`.
 7. Load the signing and WDA deployment profiles that match the user's path.
 8. Load `contexts/tools/appium/real-device/references/real-device-procedure-part1.md`, `contexts/tools/appium/real-device/references/real-device-procedure-part2.md`, `contexts/tools/appium/real-device/references/real-device-procedure-part3.md`, `contexts/tools/appium/real-device/references/real-device-procedure-part4.md`, `contexts/tools/appium/real-device/references/real-device-procedure-part5.md`, `contexts/tools/appium/real-device/references/real-device-procedure-part6.md`, `contexts/tools/appium/real-device/references/real-device-procedure-part7.md`, `contexts/tools/appium/real-device/references/real-device-procedure-part8.md`, and `contexts/tools/appium/real-device/references/real-device-procedure-part9.md` in order.

contexts/tools/appium/setup/node-environment.md → contexts/tools/appium/setup-basics.md

@@ -1,16 +1,16 @@
 ---
 owner: appium
-id: setup-references-environment-setup-node
+id: appium.setup.basics
 status: stable
-source: contexts/tools/appium/setup/node-environment.md
+source: contexts/tools/appium/setup-basics.md
 
 ---
 
-# Node Environment
+# Appium Setup Basics
 
 ## Goal
 
-Prepare a stable Node.js and npm environment by validating the active runtime, npm availability, registry connectivity, and engine compatibility needed by Appium setup workflows.
+Prepare the shared Appium setup baseline by validating the active Node.js runtime, npm availability, registry connectivity, command mode, and engine compatibility needed by Appium setup workflows.
 
 ## Routing
 

contexts/tools/appium/setup/espresso-environment.md

@@ -16,8 +16,8 @@ Prepare Appium Espresso by checking Node/Appium, Android prerequisites, driver i
 
 Load these references in order:
 
-1. First load `contexts/tools/appium/setup/node-environment.md` to validate Node.js and npm.
-2. Then load `contexts/tools/appium/setup/references/environment-setup-android.md` to validate Java, Android SDK, ADB, emulator, and SDK packages.
+1. First load `contexts/tools/appium/setup-basics.md` to validate Node.js and npm.
+2. Then load `contexts/platform/android/emulator-setup.md` to validate Java, Android SDK, ADB, emulator, and SDK packages.
 3. `contexts/tools/appium/setup/references/espresso/espresso-decision-logic.md` for driver setup triggers and optional dependency boundaries.
 4. `contexts/tools/appium/setup/references/espresso/espresso-driver-install.md` for global Appium and Espresso driver installation.
 5. `contexts/tools/appium/setup/references/espresso/espresso-doctor-validation.md` for required doctor pass criteria.

contexts/tools/appium/setup/examples/chromium.md

@@ -11,7 +11,7 @@ Use this repository's skills to prepare Appium Chromium Driver for desktop brows
 1. Load `skills/setup/SKILL.md`.
 2. Load `contexts/tools/appium/setup/profiles/global-appium.md` unless the user requests local mode.
 3. Load `contexts/tools/appium/setup/profiles/chromium.md`.
-4. Load `contexts/tools/appium/setup/node-environment.md`.
+4. Load `contexts/tools/appium/setup-basics.md`.
 5. Load `contexts/tools/appium/setup/references/environment-setup-chromium.md`.
 
 Rules:

contexts/tools/appium/setup/examples/espresso.md

@@ -10,9 +10,9 @@ Use this repository's skills to prepare Android + Espresso.
 
 1. Load `skills/setup/SKILL.md`.
 2. Load `contexts/tools/appium/setup/profiles/global-appium.md` unless the user requests local mode.
-3. Load `contexts/tools/appium/setup/profiles/android.md`.
-4. Load `contexts/tools/appium/setup/node-environment.md`.
-5. Load `contexts/tools/appium/setup/references/environment-setup-android.md`.
+3. Load `contexts/platform/android/profile.md`.
+4. Load `contexts/tools/appium/setup-basics.md`.
+5. Load `contexts/platform/android/emulator-setup.md`.
 6. Load `contexts/tools/appium/setup/espresso-environment.md`.
 
 Rules:

contexts/tools/appium/setup/examples/gecko.md

@@ -11,7 +11,7 @@ Use skills to prepare Appium Gecko Driver for Firefox desktop automation.
 1. Load `skills/setup/SKILL.md`.
 2. Load `contexts/tools/appium/setup/profiles/global-appium.md` unless the user explicitly requested `npx appium`.
 3. Load `contexts/tools/appium/setup/profiles/gecko.md`.
-4. Load `contexts/tools/appium/setup/node-environment.md`.
+4. Load `contexts/tools/appium/setup-basics.md`.
 5. Load `contexts/tools/appium/setup/gecko-environment.md`.
 
 Rules: