Prerequisite — feature flag. This workflow is gated behind the argent-lens flag (off by default). Run argent enable argent-lens once before using it. If propose_variant / await_user_selection come back not-found, the flag is off — enable it and retry.

1. Overview

You implement several candidate designs, capture each one running on the device, and stage them with propose_variant. Each proposed element shows up as a floating card next to the live simulator stream in the Argent Lens window (a native window that opens automatically), connected by a thin line to the real element. The human picks per element, optionally pins free-form comments to elements, and presses Complete selection. await_user_selection is the single blocking call that returns their decision.

The golden rule: one variant = one real, distinct screenshot. A proposal is only useful if its previewImage shows the variant actually rendered on the device, captured AFTER that specific variant was applied. Never propose a variant you have not built and seen on screen, and never point two variants at the same file path — if two captures end up byte-identical you have not actually changed anything and the Argent Lens degenerates to identical thumbnails. Plan → build → navigate → screenshot → propose, repeated for every variant of every element, then await once.

2. Tools

Tool	Blocking?	Purpose
`propose_variant`	No	Stage ONE variant for ONE element. Call once per variant. Keep working.
`await_user_selection`	Yes	Call ONCE after every variant is staged. Parks until the human is done.

propose_variant params: element (human name), optional match ({ by: "text"|"label"|"identifier"|"role", value }), optional udid (the device id you captured the variants on), and variant ({ name, summary, code?, filePath?, previewImage?, frame? }). Repeated calls with the same element accumulate variants on that element; different element values create separate cards.

Always pass udid (the same simulator/emulator id you screenshotted and described with). The preview window then streams that device directly — the human never has to pick a simulator. Set it on the first propose_variant of a round; later calls may omit it (the last value wins).