@deeeed/metamask-harness 0.15.2 → 0.17.0

package/docs/CLI-ERGONOMICS-AUDIT.md

@@ -0,0 +1,32 @@
+<!-- Generated by scripts/generate-cli-ergonomics-audit.mjs. Do not edit by hand. -->
+# CLI ergonomics audit
+
+This matrix tracks the public command surface. “Covered” means the shared preflight contract and
+`tests/contract/cli-teaching-errors.test.sh` exercise the behavior without dispatching runtime work.
+Runtime recovery is claimed only where command-specific failures return a stable `userAction`.
+Success hints are intentionally limited to lifecycle transitions with one truthful next command;
+discovery, read-only, and terminal evidence commands do not invent one. ID prefix support is N/A
+unless a command displays a shortened ID that another command accepts.
+
+| Command | Bad flag | First feedback | `--json` recovery | Success next step | Displayed ID prefix |
+|---|---|---|---|---|---|
+| `status` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | structured `next` | N/A: command displays no shortened ID |
+| `checklist` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `actions` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `stop` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | launch `next` when the adapter has one unambiguous launch | N/A: command displays no shortened ID |
+| `call` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `flows` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `run` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `last` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `doctor` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `check` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `recipe-quality` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `provision` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | launch `next` after install | N/A: command displays no shortened ID |
+| `install` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | verify `next` | N/A: command displays no shortened ID |
+| `verify` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | status `next` | N/A: command displays no shortened ID |
+| `cleanup` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | install `next` | N/A: command displays no shortened ID |
+| `launch` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `logs` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `debug` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `update` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `fixtures` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |

package/docs/CLI-ERGONOMICS-HUMAN-QA.md

@@ -0,0 +1,104 @@
+# CLI ergonomics human QA
+
+Use this short pass after installing a release candidate. Automated contracts remain the release gate; this checklist confirms the experience in a real shell and checkout.
+
+## Setup
+
+```bash
+export TARGET=/absolute/path/to/a/metamask-checkout
+export ADAPTER=extension # extension, mobile, or core
+mm-harness --version
+mm-harness doctor --adapter "$ADAPTER" --target "$TARGET" --json | jq .status
+```
+
+Expected: the intended version is printed and `doctor` returns parseable JSON. Resolve required doctor failures before continuing.
+
+## 1. Teaching errors
+
+```bash
+out="$(mm-harness actions --categoriez --adapter "$ADAPTER" --json 2>/dev/null || true)"
+jq '.error | {code, message, userAction}' <<<"$out"
+```
+
+Expected: `code` is stable, the message names the bad flag and valid options, and `userAction` suggests the closest valid invocation.
+
+## 2. In-tool discovery
+
+```bash
+mm-harness actions --adapter "$ADAPTER" --categories
+mm-harness actions status --adapter "$ADAPTER"
+mm-harness actions --action app.status --adapter "$ADAPTER" --json | jq '{actions, relatedActions}'
+```
+
+Expected: category output is compact, fuzzy search is bounded, and action detail includes related actions when available. A missing example action should produce a teaching error, not silent output.
+
+## 3. Machine-output cleanliness and recovery
+
+```bash
+out="$(mm-harness call definitely.not.an.action --adapter "$ADAPTER" --target "$TARGET" --json 2>/dev/null || true)"
+jq '{status, error}' <<<"$out"
+```
+
+Expected: stdout is one parseable JSON document with `error.code`, `error.message`, and `error.userAction`; it contains no spinner, banner, or human-only glyph.
+
+## 4. Immediate human feedback
+
+Run the platform-appropriate launch in an interactive terminal:
+
+```bash
+# Extension
+mm-harness launch --adapter extension --target "$TARGET"
+
+# Mobile: choose the intended platform
+mm-harness launch ios --target "$TARGET"
+# mm-harness launch android --target "$TARGET"
+```
+
+Expected: intent/progress appears immediately, long work continues to report progress, and the app becomes ready. Redirected or `--json` stdout stays decoration-free.
+
+## 5. Lifecycle next step
+
+For Extension:
+
+```bash
+mm-harness stop --adapter extension --target "$TARGET" --json | jq '{status, next}'
+```
+
+Expected: `next` is a target-scoped launch command. Mobile `stop` intentionally omits `next` because Metro does not identify whether iOS or Android should be relaunched.
+
+## 6. Resume after interruption
+
+```bash
+mm-harness last --target "$TARGET" --json | jq '.last | {command, args, verdict, evidencePaths, startedAt, finishedAt}'
+```
+
+Expected: the last operation can be reconstructed without rerunning it, including its arguments, verdict, evidence paths, and timestamps.
+
+## 7. Recipe proof smoke
+
+```bash
+mm-harness run --list --adapter "$ADAPTER" --json | jq '{actions: .actions[0:5], flows: .flows[0:5]}'
+export RECIPE=replace-with-a-safe-recipe-name-or-path
+export ARTIFACTS_DIR="$(mktemp -d)"
+mm-harness run "$RECIPE" --plan --adapter "$ADAPTER" --target "$TARGET" --json | jq '{status, plan}'
+mm-harness run "$RECIPE" --adapter "$ADAPTER" --target "$TARGET" --artifacts-dir "$ARTIFACTS_DIR"
+```
+
+Expected: the plan validates before execution; the final result identifies evidence paths and `mm-harness last --json` records the run.
+
+Optional JSONL check:
+
+```bash
+mm-harness run "$RECIPE" --adapter "$ADAPTER" --target "$TARGET" --artifacts-dir "$ARTIFACTS_DIR-stream" --json-stream | jq -c .
+```
+
+Expected: complete JSON objects arrive line by line while the run is active.
+
+## Cleanup
+
+```bash
+[ "$ADAPTER" = core ] || mm-harness stop --adapter "$ADAPTER" --target "$TARGET"
+mm-harness status --target "$TARGET" --json | jq .
+```
+
+Record the harness version, checkout SHA, adapter/platform, failed command, exit code, and JSON envelope for any discrepancy.

package/docs/CLI-SPEC.md

@@ -366,6 +366,8 @@ Installs the cached Runway iOS dev client onto a prepared mobile slot. It does n
 
 **Validates first (adapter-aware):** Before touching any device, `run` validates the recipe: action existence in the adapter's manifest, platform support for each action, and fixture preconditions. Validation errors exit 5 with a structured error list. `--plan` stops here — prints the plan and exits, no device touched. Without `--plan`, validation failures are fatal before any execution begins.
 
+**Run-scoped diagnostics:** Mobile combines its bounded in-app issue buffer with application-log bytes appended while the recipe executes; Extension owns a CDP console subscription for the run. The bounded, redacted result is written to `diagnostics.json`, indexed as a diagnostic artifact, and summarized as non-blocking `sideFindings`; it never changes recipe pass/fail and does not claim causality. Core is headless, so this is N/A.
+
 > **Wave-2 status:** adapter-aware validation (`validateRecipeDocument` +
 > `validateRecipeWithManifest`, shared helper `validateRecipeAdapterAware`) is
 > wired for **`run --plan`** and **`call`** at the pinned deps (`@farmslot/protocol`
@@ -377,7 +379,7 @@ Installs the cached Runway iOS dev client onto a prepared mobile slot. It does n
 > recipe) validate fully; the execute path relies on the engine's own manifest
 > validation. Tagged in code (`runner/src/cli.ts` `validateRecipeAdapterAware`).
 
-**Phase state-machine:** `resolve → install → healthcheck → recover → validate → launch → execute` (phase reported in `--json` as `phase`; `--json-stream` emits one event per phase transition).
+**Execution phases:** `resolve → validate → install → healthcheck → execute`, with `recover` emitted only when bounded recovery actually runs. `--json-stream` emits each transition as it occurs.
 
 **Auto-ensure overlay:** `run` checks for the runtime overlay before executing (phase: `install`). If missing: installs it inline with a one-line notice, then proceeds. **First-install overlay notice:** on the very first install for this checkout, prints `installed mm-harness overlay v<version> → <path>` to stderr in human mode; in `--json` it appears solely as `mutations[]`. Use `--heal=off` to disable all auto-install and healing.
 
@@ -387,6 +389,14 @@ Installs the cached Runway iOS dev client onto a prepared mobile slot. It does n
 **Outputs:** `summary.json`, `trace.json`, `artifact-manifest.json`, screenshots/logs under `--artifacts-dir`.
 **Maps-to:** A:`run` (ROUTES-NOW); C/D:`run` (ABSORB-LATER — supply the auto adapter+artifacts defaults the typed CLI lacks).
 
+## `last` (resumability inspect verb)
+
+**Synopsis:** `mm-harness last [--target <checkout>] [--runtime-dir <dir>] [--json]`
+
+Reads `last-command.json`, the atomic per-checkout journal written before and after significant runtime/proof commands. The record contains redacted args, `running|pass|fail` verdict, exit code, explicit evidence/output paths, and start/finish timestamps. A process killed between writes remains `running`, allowing an agent to inspect rather than repeat side effects. Read-only discovery commands do not replace the record, and `last` never journals itself.
+
+The file is mode `0600`; password, credential, auth, mnemonic, private-key, seed/SRP, secret, and token values are redacted before the first write. `--json` returns `{ command:"last", target, journalPath, status, exitCode, last }`. Missing or invalid state returns `LAST_NOT_FOUND` with an exact `userAction`.
+
 ## `doctor` (ROUTES-NOW → PROVE inspect verb)
 
 Readiness check for a checkout without launching the app. Doctor is the single place to understand the full slot context — **no hunting for files**. It also absorbs the retired `manifest` verb's validation function: the readiness checks include manifest well-formedness (schema valid, no unknown action references) and report the manifest path + protocol version in the explain-my-setup section. It includes three grounded sub-sections:
@@ -559,9 +569,9 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
 
 ### `actions` (ROUTES-NOW → DISCOVER verb)
 
-**Synopsis:** `mm-harness actions --adapter <p> [--json] [--action <name>] [--kind official|custom]`
+**Synopsis:** `mm-harness actions [query] --adapter <p> [--json] [--categories | --category <name> | --action <name>]`
 
-**PRIMARY (agent):** `mm-harness actions --adapter mobile --json`
+**PRIMARY (agent):** search from the task vocabulary, for example `mm-harness actions positions --adapter mobile --json`, then request one full `--action` schema. Use `--categories` only when the task does not provide a useful search term.
 
 **`--json` output shape** (grounded — `actions --adapter core --json` confirmed):
 ```json
@@ -571,6 +581,7 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
     {
       "name": "metamask.perps.read_positions",
       "kind": "custom",
+      "category": "perps",
       "description": "Read live Perps positions...",
       "fields": ["account", "action", "market", "markets", "mode", "selector", "side", "symbol", "symbols", "timeout_ms"],
       "examples": [{ "node": { "action": "metamask.perps.read_positions", "account": "...", "symbol": "BTC" } }]
@@ -578,7 +589,7 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
   ]
 }
 ```
-`kind` is `"official"` (engine built-ins) or `"custom"` (MetaMask adapter actions). `fields` lists every accepted parameter name. `examples[].node` is a copy-pasteable recipe node.
+`kind` is `"official"` (engine built-ins) or `"custom"` (MetaMask adapter actions). `category` uses manifest metadata when present, then stable generic groups for protocol primitives and durable action namespaces (`ui.*` → `ui`, `metamask.perps.*` → `perps`). `fields` lists every accepted parameter name. `examples[].node` is a copy-pasteable recipe node.
 
 **Human form:** `mm-harness actions --adapter mobile` — one line per action: `<name> (<kind>) <description>  fields=<f1,f2,...>`.
 
@@ -586,12 +597,13 @@ pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
 |---|---|---|---|---|---|
 | `--adapter <p>` | mobile\|extension\|core | auto-detect | `RECIPE_HARNESS_PLATFORM` | both | Target adapter · [DEFAULT-GAP] required today |
 | `--action <name>` | string | all | — | agent | Filter to one action; full schema + all examples |
-| `--kind <k>` | official\|custom | all | — | agent | Filter by action kind |
+| `--categories` | bool | false | — | agent | Return only sorted category names and action counts |
+| `--category <name>` | string | all | — | agent | Return actions from one namespace-derived category |
 | `--action-manifest <path>` | path | bundled | — | agent | Override manifest |
 | `--raw` | bool | false | — | agent | Dump the underlying action manifest JSON (protocol version, registry version, all entries in raw registry format — same output as `manifest --json` today; replaces the retired `manifest` verb) |
 | `--json` | bool | false | — | **agent PRIMARY** | Full schema + fields + examples per action |
 
-**[DISCOVERY-GAP]:** No `--action <name>` single-action filter today (all or nothing). No `--kind` filter. No keyword search across descriptions or fields.
+The optional positional `query` searches names, categories, fields, and descriptions with typo tolerance. A single `--action` detail also returns up to five compact `relatedActions` names. Flow discovery remains separate.
 **Exit:** 0 / non-zero on engine error.
 **Maps-to:** A:`actions` (ROUTES-NOW); C/D:`actions` (ABSORB-LATER).
 
@@ -897,6 +909,36 @@ Every failure in `--json` mode produces an `error` field at the top level:
 | `retryable` | boolean | `true` = same command may succeed on retry; `false` = agent must change inputs or escalate |
 | `userAction` | string \| null | Exact next command or manual step |
 
+Successful lifecycle transitions may add a top-level `next` command when exactly
+one follow-up is correct (for example install → verify or stop → relaunch).
+Discovery, read-only, and terminal evidence commands intentionally omit it rather
+than inventing guidance. Agents must therefore treat `next` as optional.
+
+Public command-grammar failures happen before runtime dispatch and always exit 2.
+Their machine envelope is deliberately smaller and stable: agents branch on
+`error.code`, never on prose.
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "actions",
+  "status": "fail",
+  "error": {
+    "code": "CLI_UNKNOWN_OPTION",
+    "message": "unknown option '--categoriez'. Valid options for mm-harness actions: ...",
+    "userAction": "Did you mean '--categories' instead of '--categoriez'? Try: mm-harness actions --adapter mobile"
+  },
+  "exitCode": 2
+}
+```
+
+Stable grammar codes are `CLI_UNKNOWN_COMMAND`, `CLI_UNKNOWN_OPTION`,
+`CLI_MISSING_OPTION_VALUE`, `CLI_INVALID_OPTION_VALUE`,
+`CLI_MISSING_POSITIONAL`, `CLI_INVALID_POSITIONAL`,
+`CLI_EXCESS_POSITIONAL`, and `CLI_UNEXPECTED_PASSTHROUGH`. Every public
+command is tracked in `docs/CLI-ERGONOMICS-AUDIT.md`; private adapter leaves keep
+their own grammar behind explicit `--` passthrough.
+
 ## §5.2 Stable recovery codes (`recovered[]`)
 
 `recovered[]` in `--json` output lists what was healed. These are stable enum values — not prose, safe to match in agent code:
@@ -937,18 +979,20 @@ Every `--json` response includes `mutations[]` listing all side effects the comm
 
 ## §5.4 Phase state-machine
 
-Every `--json` response includes a `phase` field reflecting the last completed phase. `--json-stream` emits one event per transition. Agents can detect exactly where a failure occurred.
+Summary `--json` responses retain their command-specific `phase` field. `--json-stream` emits transitions as they occur, so an agent can distinguish active work from a stalled command.
 
 **`run` phases:**
 ```
-resolve → install → healthcheck → recover → validate → launch → execute
+resolve → validate → install → healthcheck → execute
 ```
 
 **`launch` phases:**
 ```
-resolve → install → healthcheck → recover → launch → verify
+resolve → install → healthcheck → launch → verify
 ```
 
+`recover` is conditional and appears immediately before a bounded recovery attempt; `verify` appears only for `launch --verify`.
+
 | Phase | What happens |
 |---|---|
 | `resolve` | Recipe/target/adapter resolved; library sources loaded |
@@ -962,20 +1006,20 @@ resolve → install → healthcheck → recover → launch → verify
 
 ## §5.5 JSONL event stream (`--json-stream`)
 
-`--json-stream` emits one JSON object per line on stdout as the command progresses. Parseable with `jq -R 'fromjson?'`. Schema is versioned via `schemaVersion`.
+`run` and `launch` accept `--json-stream`. Each progress event is written as one complete JSON object plus a newline, so a piped reader can parse it before the command finishes. Schema is versioned via `schemaVersion`; every event also carries `command` and `ts`.
+
+Stream mode owns stdout: existing human or subprocess output is routed to stderr. If both `--json` and `--json-stream` are supplied, stream mode wins. The existing summary `--json` bytes are unchanged when stream mode is absent.
 
 ```jsonl
-{"schemaVersion":1,"event":"phase","phase":"resolve","ts":"2026-07-02T10:00:00.000Z"}
-{"schemaVersion":1,"event":"phase","phase":"install","ts":"2026-07-02T10:00:00.100Z"}
-{"schemaVersion":1,"event":"mutation","mutation":{"type":"file","path":"/...","action":"created"},"ts":"..."}
-{"schemaVersion":1,"event":"phase","phase":"validate","ts":"..."}
-{"schemaVersion":1,"event":"phase","phase":"execute","ts":"..."}
-{"schemaVersion":1,"event":"node","index":0,"action":"metamask.wallet.unlock","status":"running","ts":"..."}
-{"schemaVersion":1,"event":"node","index":0,"action":"metamask.wallet.unlock","status":"passed","ts":"..."}
-{"schemaVersion":1,"event":"complete","status":"pass","exitCode":0,"recovered":[],"mutations":[...],"ts":"..."}
+{"schemaVersion":1,"command":"run","event":"phase","phase":"resolve","ts":"2026-07-02T10:00:00.000Z"}
+{"schemaVersion":1,"command":"run","event":"phase","phase":"validate","ts":"2026-07-02T10:00:00.100Z"}
+{"schemaVersion":1,"command":"run","event":"phase","phase":"execute","ts":"..."}
+{"schemaVersion":1,"command":"run","event":"node","nodeId":"unlock","action":"metamask.wallet.unlock","status":"running","ts":"..."}
+{"schemaVersion":1,"command":"run","event":"node","nodeId":"unlock","action":"metamask.wallet.unlock","status":"passed","ts":"..."}
+{"schemaVersion":1,"command":"run","event":"complete","status":"pass","exitCode":0,"reportPath":"/.../report.md","artifactManifestPath":"/.../artifact-manifest.json","recovered":[],"mutations":[],"ts":"..."}
 ```
 
-Event types: `phase` · `node` · `mutation` · `recovery` · `error` · `complete`. The terminal `complete` event always appears (even on failure) so agents have a clean sentinel.
+Event types: `phase` · `node` · `mutation` · `recovery` · `error` · `complete`. Node events use stable recipe `nodeId` values rather than an inferred numeric order. Exactly one terminal `complete` event is last on normal success or handled failure, giving agents a clean sentinel and compact evidence paths without repeating the full run result.
 
 ## §5.6 Exit code taxonomy
 

package/docs/MENTAL-MODEL.md

@@ -189,14 +189,14 @@ The composition loop: `actions --json` → `call <action>` (try one via real eng
 | | |
 |---|---|
 | **Human form** | `mm-harness actions --adapter mobile` · `mm-harness call unlock` · `mm-harness flows` |
-| **Agent PRIMARY** | `mm-harness actions --adapter mobile --json` → `{ adapter, actions: [{ name, kind, description, fields, examples }] }` |
+| **Agent PRIMARY** | `mm-harness actions <task-term> --adapter mobile --json`, then one focused `--action <name>` schema; use `--categories` only without a useful term |
 | | `mm-harness call metamask.perps.read_positions --arg symbol=BTC --adapter core --json` → `{ action, resolvedAction, args, trace, evidence, recovered, mutations, exitCode, schemaVersion }` (same shape as `run --json`, one-node subset) |
 | | `mm-harness flows --json` → `{ sources, flows: [{ ref, source, file, description?, requiredParams?, shadows?, lastVerified? }] }` |
 | **Plan before run** | `mm-harness run recipe.json --plan --json` → `{ plan[], validation: { status, findings }, schemaVersion }` (adapter-aware; exit 5 on errors) |
 
 | Today (real) | → mm-harness | Status |
 |---|---|---|
-| `metamask-recipe actions --adapter …` | `mm-harness actions --adapter …` | ROUTES-NOW · [DEFAULT-GAP] `--adapter` required · [DISCOVERY-GAP] no `--action <name>` filter, no `--kind` filter, no keyword search |
+| `metamask-recipe actions --adapter …` | `mm-harness actions --adapter …` | ROUTES-NOW · auto-detects in a checkout · bounded category/action views shipped · [DISCOVERY-GAP] no keyword search |
 | `metamask-recipe flows list\|promote` | `mm-harness flows [\|promote]` | ROUTES-NOW · `flows` = browse the reusable flow library (compose, don't rewrite); `promote` publishes a proven flow up a tier · bare `flows` = list · [DISCOVERY-GAP] no keyword filter, no per-flow body fetch, no platform filter |
 | `mm-recipe`/`mme-recipe` `actions`/`doctor` (auto adapter) | same `mm-harness` verbs | ABSORB-LATER — porcelain supplies missing adapter default |
 | hook layer `run-action app.unlock` | `mm-harness call unlock` (fuzzy: `unlock` → `metamask.wallet.unlock`) — **one-node recipe via real engine path** | REAL (wave 2) · ambiguous → exit 2 listing candidates |

package/docs/UX-PRINCIPLES.md

@@ -27,6 +27,8 @@ The CLI answers relative to the checkout it is standing in.
 Long operations show intent immediately and progress continuously.
 - First line within milliseconds: what is being done, where (device/port), and
   where the full log lives.
+- Add an explicit first line only when work can block before existing output. Fast
+  commands use their result as acknowledgement; they do not print a redundant banner.
 - Leaf output streams live to stderr — `--json` reserves stdout for the envelope,
   it never buys silence. Quiet stretches get heartbeats with elapsed time.
 - Each dev server a command starts gets its tmux log-tail window at launch time

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.15.2",
+  "version": "0.17.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
   },
   "scripts": {
     "build": "node scripts/build-dist.mjs",
+    "audit:cli-ergonomics": "node scripts/generate-cli-ergonomics-audit.mjs",
     "prepack": "npm run build",
     "dev:link-farmslot": "node scripts/link-local-farmslot.mjs",
     "check": "node scripts/check.mjs",