latekvo · Oct 22, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026
diff --git a/Telemetry.md b/Telemetry.md
@@ -63,7 +63,7 @@ When you use the Argent Lens design-review flow (previewing and choosing between
 
 - Argent version, Node.js version, operating system, processor architecture;
 - whether the process runs in an interactive terminal and whether it runs in a CI environment;
-- whether Argent is used in connection with Android, iOS, tvOS (Apple TV), Android TV, VegaOS, or a Chromium-based target, and whether that target is a simulator or emulator, a virtual device, a physical device, or a desktop application. This category is inferred from the form of the device identifier; the identifier itself is never recorded;
+- whether Argent is used in connection with Android, iOS, tvOS (Apple TV), Android TV, VegaOS, HarmonyOS, or a Chromium-based target, and whether that target is a simulator or emulator, a virtual device, a physical device, or a desktop application. This category is inferred from the form of the device identifier; the identifier itself is never recorded;
 - when a device is supplied by an external device provider, a short label for that provider (the leading segment of the name the provider registers under), never the identifier of the device it supplies.
 
 ### Diagnostics

diff --git a/packages/configuration-core/src/flags.ts b/packages/configuration-core/src/flags.ts
@@ -62,6 +62,11 @@ export const FLAG_REGISTRY: readonly FlagDefinition[] = [
     description:
       "Amplify device actions with matching animations of the host window, so what happens on the guest is also visible on the desktop. Purely cosmetic, macOS only, and never affects whether the underlying action succeeds. Off by default.",
   },
+  {
+    name: "harmonyos",
+    description:
+      "HarmonyOS support: list, boot and drive HarmonyOS phones and DevEco Studio emulators over `hdc`. Off by default while the platform is experimental.",
+  },
   {
     name: "video-watermark",
     description:

diff --git a/packages/docs/docs/features/screen-recording.mdx b/packages/docs/docs/features/screen-recording.mdx
@@ -45,7 +45,7 @@ The files stay in the working tree. Add the directory to `.gitignore` when you d
 
 ## Limits
 
-- Argent records iOS simulators, Android emulators, and physical Android devices. Argent does not record tvOS simulators, physical iPhones, Chromium apps, Vega devices, or remote simulators.
+- Argent records iOS simulators, Android emulators, and physical Android devices. Argent does not record tvOS simulators, physical iPhones, Chromium apps, Vega devices, HarmonyOS devices, or remote simulators.
 - One recording per device at a time. Different devices can record at the same time.
 - Argent uses `ffmpeg` to encode the video. Install `ffmpeg` before the first recording.
 - On Android, a secure screen such as a password field or a DRM video comes out black.

diff --git a/packages/docs/docs/features/visual-regression.mdx b/packages/docs/docs/features/visual-regression.mdx
@@ -57,6 +57,6 @@ Thus you can keep visual checks in the repository and run them in CI.
 - The comparison does not replace a check of the accessibility tree, the logs or the network record. The agent uses these sources together with the comparison.
 - The two screenshots must come from the same device class and the same orientation. When the resolution differs, Argent scales one screenshot down, and small differences can come from the scaling.
 - The agent does not use the comparison to find the position of an element for a tap. The agent uses the screen description for that.
-- The comparison works on an iOS simulator, or an Android emulator or device. It does not work on Chromium, Apple TV or Vega apps. On a [physical iPhone](/docs/features/physical-ios-devices), the agent captures full-resolution screenshots and compares them on the host instead.
+- The comparison works on an iOS simulator, an Android emulator or device, or a HarmonyOS device. It does not work on Chromium, Apple TV or Vega apps. On a [physical iPhone](/docs/features/physical-ios-devices), the agent captures full-resolution screenshots and compares them on the host instead.
 
 Argent does this with the `screenshot` and `screenshot-diff` tools. The [tools reference](/docs/reference/tools) contains all tools.
diff --git a/packages/docs/docs/fundamentals/installation.mdx b/packages/docs/docs/fundamentals/installation.mdx
@@ -13,6 +13,7 @@ sidebar_custom_props:
 - **iOS / tvOS**: macOS with **Xcode** installed. Apple TV uses tvOS simulators, and Xcode downloads the tvOS runtime on demand.
 - **Android / Android TV**: **Android SDK Platform Tools** (`adb`) on `PATH`, plus the **Android Emulator** package to boot AVDs from Argent. Create AVDs via Android Studio or `avdmanager`.
 - **Fire TV (Vega)**: the **Vega SDK** (`vega` CLI) on `PATH`, plus **Android SDK Platform Tools** (`adb`) on `PATH`. Most Vega tools, including UI inspection and screenshots, run over `adb`.
+- **HarmonyOS**: **DevEco Studio**, which ships `hdc` (the device connector) and the `Emulator` manager. Argent looks for both in `$DEVECO_STUDIO_HOME` first, then in `/Applications/DevEco-Studio.app` on macOS. Argent also finds `hdc` on `PATH`, for hosts that installed the OpenHarmony command-line tools without the IDE. A phone needs only `hdc`. Run `argent enable harmonyos` to turn on HarmonyOS support.
 - **Electron / Chromium**: nothing extra to control an already running app. Launch it with `--remote-debugging-port`, or let Argent spawn your Electron app for you.
 
 ## Run `init` in your project

diff --git a/packages/docs/docs/fundamentals/supported-platforms.mdx b/packages/docs/docs/fundamentals/supported-platforms.mdx
@@ -14,6 +14,7 @@ Argent drives a growing set of targets through a single toolkit, each with the r
 | **Android**       | Emulators (AVDs) and physical devices over adb                          | Touch / gesture  |
 | **TV**            | Apple TV (tvOS), Android TV / Google TV, Amazon Fire TV (Vega)          | D-pad / remote   |
 | **Desktop & web** | Electron and Chromium apps (incl. React Native Web / Expo web) over CDP | Mouse / keyboard |
+| **HarmonyOS**     | Phones over `hdc`, and DevEco Studio emulator instances                 | Touch / gesture  |
 
 <Video
   src="/video/ios-android-web.mp4"
@@ -46,6 +47,21 @@ The agent folds and unfolds the device with the `fold` tool. `list-devices` mark
 
 Argent also drives a physical iPhone over a USB cable. Physical iPads are not supported yet. Automation on hardware is scoped to one app at a time, and a subset of the simulator tools is available. See [Physical iOS devices](/docs/features/physical-ios-devices).
 
+### HarmonyOS
+
+HarmonyOS support is experimental and off by default. Run `argent enable harmonyos` to turn it on. While the flag is off, `list-devices` shows no HarmonyOS target and Argent refuses every `harmony-` id. See [Feature flags](/docs/reference/configuration#feature-flags).
+
+Argent drives any HarmonyOS phone or emulator that `hdc` is connected to. A phone with USB debugging enabled appears as `harmony-<connectKey>`. A DevEco Studio emulator instance appears as `harmony-emulator-<name>`. `boot-device` starts the instance and returns its `harmony-<connectKey>` id, so the same tools drive a phone and an emulator.
+
+- Argent reads the screen and injects taps, swipes and text through the device's own `uitest`.
+- `gesture-pinch` sends the start and end points of both fingers in one `uinput` call. The device interpolates the movement.
+- `launch-app`, `restart-app` and `open-url` use the `bm` and `aa` shell commands.
+- `reinstall-app` installs a single `.hap` file with `hdc uninstall` and `hdc install`.
+- Argent refuses `gesture-rotate` and `gesture-custom`. The device moves each contact along one straight line per call.
+- Argent also refuses `rotate`, the profilers and the debugger. The device has no orientation command, and the profilers and the debugger have no HarmonyOS ingest path.
+
+Huawei restricts the emulator image download to mainland China. Outside mainland China, you cannot create an emulator instance until you get an image.
+
 ## TV targets
 
 A TV UI is focus-driven rather than touch-driven. Argent reads which element currently holds focus, then moves the cursor with directional remote presses and confirms with select.

diff --git a/packages/docs/docs/reference/configuration.mdx b/packages/docs/docs/reference/configuration.mdx
@@ -105,6 +105,7 @@ argent enable argent-lens --scope project    # this project only
 | `tool-server-event-log`   | Off     | Write the lifecycle events of the tool-server to a JSONL file                                                                 |
 | `boot-sound`              | Off     | Default the `sound` argument of `boot-device` to true, so Android emulators boot with audio output instead of muted           |
 | `microinteractions`       | Off     | Animate the host window to match device actions. Cosmetic only, macOS only                                                    |
+| `harmonyos`               | Off     | Enable HarmonyOS support: list, boot and drive HarmonyOS phones and DevEco Studio emulators over `hdc`                        |
 | `video-watermark`         | On      | Put the Argent watermark in the corner of a recorded screen video                                                             |
 
 The tool-server writes the event log to `~/.argent/tool-server-events.jsonl`. Set the `ARGENT_EVENT_LOG` environment variable to select a different path.

diff --git a/packages/docs/docs/reference/e2e-yaml.mdx b/packages/docs/docs/reference/e2e-yaml.mdx
@@ -119,6 +119,7 @@ The runner resolves a selector against a different tree than the `describe` tool
 | Android         | Full accessibility hierarchy                  | Trimmed interactable nodes |
 | Chromium        | DOM nodes with an id, label, value or handler | Full DOM                   |
 | Vega            | Toolkit page source                           | Same source                |
+| HarmonyOS       | None                                          | `uitest` layout dump       |
 
 On an iOS simulator and Android, an id absent from `describe` can still resolve in an e2e test. On Chromium, an element absent from `describe` cannot resolve. On an iOS simulator, do not copy a `role` from `describe` into a selector: the runner derives the role from the view class, `describe` from the accessibility traits. On a physical iPhone, the runner and `describe` read one tree: copy ids and roles from `describe`.
 
@@ -268,6 +269,8 @@ The identity selector must exist only on the destination. `idle` waits until the
 
 One outcome stops the run: the runner cannot read the UI tree at all. Argent marks the step as errored and skips the later steps.
 
+On HarmonyOS, the runner has no UI tree, so `idle` cannot run. The step errors immediately, names `wait:` as the replacement, and Argent skips the later steps.
+
 `idle` has no `assert` form and no `when` form.
 
 ## Optional steps
@@ -288,11 +291,12 @@ The guard accepts one `exists`, `visible`, `hidden` or `text` condition, or `{ p
 
 A `run:` path resolves against the directory of the e2e test file that contains the step. When nothing is there, the e2e test file is in `.argent/e2e/` or `.argent/flows/`, and the path has no `/`, Argent looks in the other of these directories. The `.yaml` suffix is optional. When you record a nested `e2e-execute` of an e2e test that is only in the other directory, the recorder writes its path from the recording, for example `run: ../flows/login.yaml`.
 
-| Platform     | Behavior                                                                                                                                                                                    |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| iOS, Android | A nested fragment or standalone e2e test runs inline. A nested launch restarts the app                                                                                                      |
-| Chromium     | Each `launch` step boots one instance. A later launch boots a fresh instance and stops the previous one of that app. Argent runs `swipe` as a mouse drag. `pinch` and `rotate` are rejected |
-| Vega         | Use `tool: tv-remote` and `tool: keyboard`. The touch directives are unsupported                                                                                                            |
+| Platform     | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| iOS, Android | A nested fragment or standalone e2e test runs inline. A nested launch restarts the app                                                                                                                                                                                                                                                                                                                                              |
+| Chromium     | Each `launch` step boots one instance. A later launch boots a fresh instance and stops the previous one of that app. Argent runs `swipe` as a mouse drag. `pinch` and `rotate` are rejected                                                                                                                                                                                                                                         |
+| Vega         | Use `tool: tv-remote` and `tool: keyboard`. The touch directives are unsupported                                                                                                                                                                                                                                                                                                                                                    |
+| HarmonyOS    | Pass the device with `--device harmony-<connectKey>`. Argent never detects a HarmonyOS device, and `--platform` and `when: { platform }` do not accept `harmony`. The runner has no UI tree, so each step with a selector fails. A coordinate `tap`, a `swipe` or `pinch` without a selector, `launch` with an app id or `native`, `snapshot` without `cropOn`, `wait` and `tool` steps run. `long-press` and `rotate` are rejected |
 
 A fragment whose `run:` chain reaches a launch cannot declare `executionPrerequisite`. Parsing accepts the file, the run rejects it.