@deeeed/metamask-harness 0.17.4 → 0.17.5

package/docs/CHEATSHEET.md

@@ -1,48 +1,61 @@
-# mm-harness cheatsheet
+# mm-harness — user cheatsheet
 
-Run inside a MetaMask checkout. Product, slot, ports, and runtime paths are
-auto-detected.
+`mm-harness <command> [target] [flags]` · Run from inside any MetaMask checkout · Platform auto-detected
 
-## Operate
+---
 
-| Need | Command |
+## Daily loop
+
+| Situation | Command |
 |---|---|
-| Extension | `mm-harness launch` |
-| Extension sidepanel | `mm-harness launch --sidepanel` |
-| iOS / Android | `mm-harness launch ios` / `mm-harness launch android` |
-| Clean rebuild | `mm-harness launch --build` |
-| Runtime status | `mm-harness status` |
-| Logs | `mm-harness logs` |
-| Debugger | `mm-harness debug` |
-| Apply wallet fixture | `mm-harness fixtures set` |
-
-Extension log sources: `extension`, `dapp`, `webpack`, `watcher`, `rebuild`.
-Mobile log sources: `app`, `metro`.
-
-## Discover and prove
-
-```bash
-mm-harness actions positions
-mm-harness actions --action metamask.wallet.ensure_unlocked
-mm-harness call metamask.wallet.ensure_unlocked
-mm-harness flows
-mm-harness run recipe.json --plan
-mm-harness run recipe.json --artifacts-dir temp/recipe-proof
-```
+| Start / relaunch iOS | `mm-harness launch ios` |
+| Start / relaunch Android | `mm-harness launch android` |
+| Launch extension (fullscreen) | `mm-harness launch` |
+| Launch extension in sidepanel | `mm-harness launch --sidepanel` |
+| Native code changed — rebuild first | `mm-harness launch ios --build` |
+| Tail Metro / webpack logs | `mm-harness logs` |
+| Open DevTools / RN inspector | `mm-harness debug` |
+| Seed wallet from fixture — no typing | `mm-harness fixtures set` |
+| Refresh wallet fixture files on slot | `mm-harness fixtures sync` |
 
-The run result prints diagnostics plus absolute evidence paths. Resume safely with
-`mm-harness last --json`.
+`launch` auto-installs the overlay on first use.
+`fixtures set` reads the password **from** the fixture — never typed.
 
-## Recover
+---
 
-```bash
-mm-harness doctor
-mm-harness doctor --fix
-mm-harness verify
-mm-harness cleanup
-mm-harness update
+## Proof loop
+
+```
+actions  →  call <action>  →  flows  →  run recipe.json --plan  →  run recipe.json
 ```
 
-For automation, add `--json`. Use `--json-stream` for line-delimited run progress.
-Bad input exits `2`; recipe/action failure exits `1`; recipe validation failure
-exits `5`.
+| Command | What it does |
+|---|---|
+| `mm-harness actions` | Action vocabulary for this adapter |
+| `mm-harness call unlock` | One action through the real engine (fuzzy name ok) |
+| `mm-harness flows` | Reusable flows (personal > team > canonical) |
+| `mm-harness run recipe.json --plan` | Validate + print plan, no device touched; exit 5 if invalid |
+| `mm-harness run recipe.json` | Execute + write evidence (summary / trace / artifacts) |
+
+---
+
+## Health
+
+| Command | What it does |
+|---|---|
+| `mm-harness doctor` | Full readiness check — fixture, runtime context, overlay. No launch. |
+| `mm-harness doctor --fix` | Repair overlay + runtime context without launching the app. |
+| `mm-harness verify` | Check overlay/runtime is present and healthy. No launch. |
+| `mm-harness cleanup` | Remove the overlay and restore the checkout. |
+
+---
+
+## For agents and scripts
+
+**`--json`** — machine-readable output on every command; includes `recovered[]`, `mutations[]`, `schemaVersion`.
+
+**`--heal`** — `off` (fail fast, repro-preserving) · `infra-only` (heal transport, never wallet; `run`/`call` default) · `auto` (auto-ensure overlay + heal; `launch` default).
+
+**Exit codes** — `0` success · `1` recipe/action failed · `2` bad args / missing target · `5` validation failure (fix recipe).
+
+**Tab completion** — `mm-harness completions install` prints the lines to add to `~/.zshrc` / `~/.bashrc`.