Verify Atlas

Verify Atlas

Drive a running Atlas desktop build over CDP: inspect the DOM, take screenshots, click, type, read the accessibility tree, evaluate JS, and manage checkout-isolated parallel instances.

node .cursor/skills/verify-atlas/control-atlas.mjs --help lists commands, flags, and examples. This sample documents usage only; the driver scripts are not included.

Pick a flow

test -f .git && echo checkout distinguishes an isolated checkout (.git is a file) from the main workspace (.git is a directory).

• Main workspace: the desktop build runs on CDP port 9222 with the shared user-data-dir. Drive it directly without --checkout.
• Isolated checkout: every command takes --checkout so the port and user-data-dir are derived for this tree. That keeps the run from fighting the user's main session or polluting auth.

From a checkout, a connect/launch command without --checkout (and without an explicit --cdp) is refused. Pass --checkout, or --cdp <endpoint> if you mean another instance on purpose.

Run doctor first when anything looks off. It reports checkout context, who owns the CDP port, watcher liveness, and build freshness.

Checkout quick start

# provision an isolated checkout, optionally seed auth, restart, then health-check
node .cursor/skills/verify-atlas/control-atlas.mjs checkout-setup --watch
node .cursor/skills/verify-atlas/control-atlas.mjs clone-userdata --force --overwrite   # optional
node .cursor/skills/verify-atlas/control-atlas.mjs --checkout restart
node .cursor/skills/verify-atlas/control-atlas.mjs --checkout info
node .cursor/skills/verify-atlas/control-atlas.mjs doctor
node .cursor/skills/verify-atlas/control-atlas.mjs cleanup --remove-checkout

Main-workspace quick start

node .cursor/skills/verify-atlas/control-atlas.mjs info
node .cursor/skills/verify-atlas/control-atlas.mjs doctor

The desktop build must already be running with remote debugging enabled (default port 9222 in the Harbor Labs desktop launcher).

Command surface

--help is canonical. Categories:

• Inspection: info, snapshot, screenshot, components
• Navigation: home, new-session, select-project, select-runtime, scroll
• Interaction: send, click, click-xy, aria-click, type, press, eval, upload-image, add-context, feature-flag
• Performance: trace, profile, record, perf-metrics, wait-settle
• Streaming: console, network-log, network-summary
• Health & cleanup: doctor, cleanup, watch --restart

Examples:

# health
node .cursor/skills/verify-atlas/control-atlas.mjs doctor

# open a blank thread and send
node .cursor/skills/verify-atlas/control-atlas.mjs new-session
node .cursor/skills/verify-atlas/control-atlas.mjs send "list open tasks in this project"

# keyboard path
node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+KeyN"

# accessibility snapshot of the live UI
node .cursor/skills/verify-atlas/control-atlas.mjs snapshot

# screenshot for evidence
node .cursor/skills/verify-atlas/control-atlas.mjs screenshot /tmp/atlas-proof.png

# wait for streaming / layout to settle
node .cursor/skills/verify-atlas/control-atlas.mjs wait-settle

# flip a gated path for the session
node .cursor/skills/verify-atlas/control-atlas.mjs feature-flag rooms_v2 on

Proof bar

Do not submit "look, it opens" captures. A proof must exercise the production user path and show the observable result a skeptical reviewer would accept.

• Drive the running build through user-visible UI, registered keybindings, menus, and normal backend plumbing. Use eval to inspect state after the user path ran, not to invoke internal handlers as the primary proof.
• Run doctor first. A video against a stale bundle is not evidence.
• Read the relevant file under references/features/. Exercise every reachable entry point, mode, enabled gated variant, and the success / cancel / error / empty / persistence paths the change can affect.
• For broad regression sweeps, walk references/features/README.md top to bottom, then multi-surface-journeys.md.
• Show the trigger and the stable end state in the same recording.
• Verify side effects, not just pixels: DOM attributes, clipboard, network/RPC log, file contents, or a reload / switch-away round trip.

Driving conventions

• Prefer ARIA labels, data-component, data-action-id, and data-message-* selectors. Class selectors are fallbacks.
• Streaming is non-deterministic. Wait on observable end states with wait-settle, not fixed sleeps.
• Prefer press with the registered chord over coordinate clicks.
• The command service is not on window. Do not invoke atlas.* through eval.
• Use feature-flag for gated paths. Reload when the feature file says the mounted tree needs it.
• Treat real OS file drops, native context menus, and system-browser auth as manual unless the driver has first-class support.

Feature map

The behavior inventory lives in references/features/. Each file uses the same four H2s: Sub-features, How to get to it (user POV), Driving it with control-atlas, Gotchas.