Update to Autonom

{
  "description": "Start here for Autonom — the universal mobile test/debug harness for AI agents on Android and the iOS Simulator. The map of the whole system — what it can do, how it works, and how to use it end to end (own a session, see the screen, drive it, watch logs and network, mock responses, capture evidence, journal every step). Read this first when asked to test, debug, profile, reproduce, or validate a running app, or when unsure which Autonom skill to load. Then let project-router narrow to the stack-specific skills.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 364
    }
  ],
  "name": "autonom",
  "skill_md_contents": "---\nname: autonom\ndescription: Start here for Autonom — the universal mobile test/debug harness for AI agents on Android and the iOS Simulator. The map of the whole system — what it can do, how it works, and how to use it end to end (own a session, see the screen, drive it, watch logs and network, mock responses, capture evidence, journal every step). Read this first when asked to test, debug, profile, reproduce, or validate a running app, or when unsure which Autonom skill to load. Then let project-router narrow to the stack-specific skills.\n---\n\n# Autonom — how the whole harness works\n\nAutonom lets an AI agent **test and debug a real mobile app** on an Android\nemulator or an iOS Simulator, with evidence. You describe a goal in plain words;\nthis skill is the map that tells you what the harness can do and how to drive it.\nThe same verbs work on both platforms.\n\n## When this applies\n\nAny task about a *running* app: reproduce a bug, walk a flow, check a screen,\nread logs, see what the app sent and how it reacts to a bad response, profile,\nor validate a release. If the task is only about *writing* code, route straight\nto the stack skills via `project-router`.\n\n## How it is built (the mental model)\n\nThree layers, and it helps to know which is which:\n\n1. **The CLI control plane** — `scripts/autonom.py` (installed as `autonom`).\n   One dependency-free JSON API. Every command prints JSON; an expected failure\n   prints `{\"ok\": false, \"error_code\": \"...\", \"hint\": \"...\"}` on stderr with exit\n   code 2, so you branch on a stable code, never parse prose. This is the source\n   of truth; the skills are how to use it well.\n2. **Thin verb-skills** — `mobile-session`, `mobile-screen`, `mobile-network`\n   wrap the CLI verbs with the judgement to use them.\n3. **Knowledge** — `mobile-memory` (`~/.autonom/apps/<pkg>/`) carries what was\n   learned about an app once, so a flow is replayed, not re-derived.\n\nSessions, mocks, the process registry, and per-app knowledge are all\n**machine-global** under `~/.autonom/` — a run is not tied to the directory it\nwas launched from, and the active session is found from anywhere.\n\n## First moves\n\n```bash\nautonom doctor          # what can this machine actually do? tools, session, orphans\nautonom devices         # Android + iOS in one list; each entry has a `running` flag\n```\n\n`doctor` is honest: green means installed, not proven. If something is missing it\nnames the exact fix.\n\n## The end-to-end loop\n\n```bash\n# 1. Own a target (boot it first if needed)\nautonom devices boot --avd Pixel_9                 # or --udid <sim>; session start also boots a sim\nautonom session start --serial emulator-5554 --app-id com.example.app\n\n# 2. See the screen, then act by meaning (not coordinates)\nautonom ui tree                                    # compact accessibility tree\nautonom ui tap --desc \"Log In\"\nautonom ui type \"test-user\"                        # into the focused field\n\n# 3. Watch what happens\nautonom session outputs                            # what is followable + tail -f hints\nautonom logs follow --source device --grep 'Error' --max-seconds 60   # live, bounded NDJSON\nautonom network start --i-understand-mitm          # decrypt + record (consent-gated)\nautonom network attach --i-understand-mitm\nautonom network requests list --host api.example.com --status 401\nautonom metrics snapshot --label baseline          # memory/CPU point, honest semantics\n\n# 4. Force a failure and check the UI reacts\nautonom network mock add --url '.../v1/login' --status 500 --json '{\"error\":\"x\"}'\nautonom ui tap --desc \"Log In\"\nautonom ui find --text \"Something went wrong\"\n\n# 5. Capture evidence + record what you did\nautonom screenshot --task login --label \"500 error state\"\nautonom note add \"login shows the generic error banner on 500; retry works\" --task login\n\n# 6. Read the run back, then clean up\nautonom journal                                    # the full timeline of this session\nautonom session stop                               # tears down proxy/stream best-effort\n```\n\nEverything from step 1–6 is appended to the session **journal** automatically\n(`~/.autonom/sessions/<id>/journal.ndjson`): every verb, its scrubbed arguments,\nthe result, and your notes. `autonom journal --kind note` / `--verb 'ui tap'`\nreads it back — the record you use to re-check or hand off a flow.\n\n## What you can do (verb catalog)\n\n| Area | Verbs |\n| --- | --- |\n| Discover | `doctor`, `devices`, `devices boot/shutdown` |\n| Session | `session start/show/stop/launch/force-stop/clear/uninstall` |\n| Screen | `ui tree/find/wait/tap/swipe/type/key` (`ui wait --settled`, `ui tree --format outline`); `find`/`tap` resolve on-screen matches first, and a node that is not on screen is `visible: false` in the tree and refused by `tap` (`element_offscreen`); `pinch/rotate/shake` are refused on both platforms; iOS input via idb or AXe, named in `backend` |\n| First run | `tour` — overview, the workflow, this machine's targets, and `--run` to walk three screens into Settings: before/after screenshots, hierarchy, and device log attached to each tap or back, an assertion that the screen changed after each, an HTML/JUnit report, and a written account |\n| Evidence | `screenshot` (with `width`/`height`), `shots list/show`, `record start/stop`, `note add/list`, `journal` |\n| Deterministic state | `simulator status-bar pin\\|clear` (both platforms), `simulator keyboard pin\\|reset\\|show` (iOS), `simulator animations pin\\|reset\\|show` (Android) — remove clock, battery, animation, and autocorrect noise from before/after comparisons; `verified` only after a read-back |\n| Device state | `open` (deep link; Android names the activity that took it in `handled_by`), `permissions`, `location` (iOS + Android emulator), `media add`, `file ls/pull` |\n| Diagnostics | `logs tail`, `crash list/show` |\n| Live observation | `session outputs`, `logs follow`, `network requests follow`, `journal --follow` — bounded NDJSON streams |\n| Metrics | `metrics snapshot/series/list-presets`, `metrics memory capture/analyze/warn`, `metrics frames …`, `metrics trace --preset …` |\n| Network | `network start/stop/status/attach/detach`, `network requests list/show`, `network mock …`, `network export --har` |\n| Flows | `flow check/fmt/list/run` — repeatable Flow v1 files with exact selectors and failure classes |\n| Housekeeping | `processes`, `cleanup` |\n\n## Which skill for what\n\n- **`project-router`** — load next: classifies the repo and narrows to the\n  stack-specific skills. This skill is the map; the router is the dispatcher.\n- **`toolchain-doctor`** — read `autonom doctor`, inspect SDK/toolchain state.\n- **`mobile-session`** — own a target, the artifact dirs, the journal.\n- **`mobile-screen`** — trees, semantic find/tap, gestures, screenshots.\n- **`mobile-network`** — capture, mock, HAR — consent-gated MITM.\n- **`mobile-flow`** — repeatable Flow v1 files: author, validate, run, replay.\n- **`mobile-memory`** — read/write per-app knowledge and flow runbooks.\n- **`android-debugger-agent` / `ios-debugger-agent` / `flutter-debugger-agent`**\n  — build-run-inspect for a specific stack.\n- Domain packs — `flutter-*`, native `android-*` / `compose-*` — for testing,\n  performance, memory, release validation, platform layers.\n- **`autonom-setup`** — install or hand the harness off to another machine/agent.\n\n## The evidence ladder\n\nClimb it; do not skip:\n\n```\ncode → unit/widget test → integration on an explicit target →\nscreenshot + UI tree + logs → profile / memory / network → before/after replay\n```\n\n## Rules that keep the work honest\n\n- **Consent is real.** `network start/attach` decrypt traffic and change device\n  config: they need their `--i-understand-mitm` (and `--install-ca`) flag every\n  time, plus a typed phrase on a terminal. Consent is never cached.\n- **Exit 0 ≠ it worked.** A tap returning ok does not prove the screen changed.\n  Compare before/after trees or screenshots.\n- **A mocked screenshot is a lie waiting to happen.** Captures taken while a mock\n  is active are flagged `screenshot_shows_mocked_data`; never present them as real\n  backend behaviour.\n- **Never surface secrets** — tokens, keystores, `.env`. The journal and captures\n  mask credential-shaped values by default; keep it that way.\n- **One explicit target.** With more than one device attached, pass `--target` /\n  `--serial` / `--udid`; ambiguity is an error listing candidates, never a guess.\n- **iOS text lives in `desc`** (from `AXLabel`), not `text` — select with `--desc`.\n\n## Where things live\n\n```\n~/.autonom/sessions/<id>/   shots, trees (full history), logs, network, recordings,\n                            crashes, files, journal.ndjson, session.json,\n                            flows/<run_id>/events.ndjson  (flow run evidence)\n~/.autonom/apps/<package>/  per-app knowledge: app.md, flows/, bodies/  (mobile-memory)\n~/.local/state/autonom/     mocks registry, process registry  (machine-level, persistent)\n```\nFlow *files* are repository source (conventionally `.autonom/flows/` in the\napp repo — see `mobile-flow`); only run artifacts land under `~/.autonom`.\n\n## Related\n\n- `project-router` — the next skill to load; narrows to the stack.\n- `mobile-session`, `mobile-screen`, `mobile-network`, `mobile-memory` — the verbs.\n- `docs/USAGE.md`, `docs/CAPABILITIES.md`, `AGENTS.md` — deeper reference.\n"
}