aco: Instructions file for Claude Code

aco -- Notes for Claude Code

Documentation style: README vs. CLAUDE.md

README.md is for users and is usage-first. Keep it concise: lead with runnable commands and short, scannable examples. Each section should be mostly code blocks with brief one-line framing. Avoid long prose paragraphs that explain how or why a feature works internally (auth wiring, capability merge order, resolution fallbacks, process lifecycle, etc.) -- prefer an inline # comment in the example or a single short sentence. If you find yourself writing a multi-sentence paragraph of mechanics, it belongs here in CLAUDE.md, not in the README. When you add behavior, document the rationale and internals in CLAUDE.md and only the how-to-use in the README.

aco is a CLI on top of Appium. Two command classes:

1. aco session start -- spawns the user's appium (from PATH) and creates a W3C session against an AUT. Runs in the foreground by default (Ctrl-C tears it down); pass --detach to fork it into the background. Targets simulators/emulators and real devices: with no --udid/--avd it prefers a connected real device, falling back to auto-booting the first Android AVD. iOS real devices take code-signing flags (--xcode-org-id, --xcode-signing-id, --allow-provisioning-device-registration, --updated-wda-bundle-id) that map to the corresponding appium:* caps. Pass --server-url <url> to attach to an already-running remote Appium server (a device-farm grid such as TestMu/LambdaTest, BrowserStack, or Sauce Labs) instead of spawning a local one -- in that mode no local appium is launched, the local-server flags are ignored, the record stores pid: 0, and the command exits immediately (like --detach) since there is no local process to own. BASIC auth (--username/--password, the --auth user:pass shorthand, or ACO_REMOTE_USERNAME/ACO_REMOTE_PASSWORD) is forwarded via WebdriverIO's user/key, which attaches Authorization: Basic only to the POST /session request -- matching the verified device-farm contract that only session creation needs auth -- and is never written to the session record. For farms whose capability shape aco's per-flag caps can't express (LambdaTest's lt:options, BrowserStack's bstack:options, ...), pass the entire W3C capabilities object verbatim with --caps-json '<json>' (or --caps-json @file): it bypasses buildCapabilities entirely (the per-device flags and the device auto-detection step are skipped), with any --cap entries shallow-merged on top. aco session list and aco session stop inspect/tear down stored sessions (a remote pid: 0 record is torn down by deleteSession alone).
2. Everything else (aco source, aco screenshot, aco element ..., aco tap, aco swipe, aco context ..., aco ios ..., aco android ..., aco mobile call) -- attaches to an existing session. --session <id>, --server-url <url>, and --platform <ios|android> are all optional: by default they are resolved from the latest live record under ~/.aco/sessions/. Explicit flags always win. When no session has been started and no flags are passed, the resolver errors out cleanly.