@deeeed/metamask-harness 0.17.5 → 0.19.0

package/docs/CODE-MAP.md

@@ -1,62 +0,0 @@
-# Code map — where things live and how a command flows
-
-One page for humans. The contracts live in docs/UX-PRINCIPLES.md and
-docs/ADAPTER-SURFACE.md; this is the geography.
-
-## How a command flows
-
-```
-bin/mm-harness                 bash front door: MM_HARNESS_BIN dev/prod switch,
-  │                            dist-vs-src selection (dist wins when present;
-  │                            stale-dist warning), deps ensure
-  ▼
-src/mm-harness-cli.ts          commander surface: grouped colored help, per-command
-  │                            --help, retired-name teaching; delegates in-process
-  ▼
-src/cli.ts                     parse + dispatch ONLY — no verb logic lives here
-  │
-  ├── src/commands/<verb>.ts   one module per verb (doctor, stop, call, run,
-  │     │                      provision, fixtures, flows, logs, debug, …)
-  │     ▼
-  │   src/adapters/surface.ts  AdapterSurface registry — per-platform behavior
-  │     │                      (ports, runtime status, dev server, log sources)
-  │     ▼
-  │   src/adapters/{mobile,extension,core}/   TS logic per platform
-  │
-  └── src/harness.ts           overlay lifecycle (install/verify/cleanup) — writes
-        │                      the per-checkout overlay + runner delegate
-        ▼
-      adapters/                SHELL LEAVES (repo root — not src/adapters!):
-        mobile/ extension/     single-OS-op scripts the TS layer spawns
-        core/ shared/          (simctl/adb/tmux/metro/webpack lifecycle)
-```
-
-## The two `adapters/` directories
-
-- `adapters/` (repo root) — executable shell leaves. Thin, OS-facing, spawned by TS.
-- `src/adapters/` — TypeScript platform logic behind the AdapterSurface.
-Rule: logic/decisions in TS; a leaf only executes. A leaf converts to TS only when
-it starts making decisions (see backlog ruling), never as a campaign.
-
-## Other roots
-
-- `library/` — recipe library: actions (`library/actions/<adapter>/…`, executable
-  action modules — importing one RUNS it, see library/README.md), flows, recipes.
-- `tests/contract/` — hermetic bash contract tests (PATH-stubbed OS tools). The
-  launch-leaf-flags test enforces composer↔leaf flag agreement.
-- `dist/` — esbuild output; the ONLY thing published runs. gitignored; in a source
-  checkout it SHADOWS src when present (bin warns when it goes stale).
-- Per-checkout runtime state lives in the TARGET repo: `temp/recipe/runtime/`
-  (context, logs, wallet fixture) and `temp/recipe/harness/<adapter>/` (overlay +
-  runner delegate pinned to the installing bin via `.runner-source`).
-
-## Adding things
-
-- **A verb**: module in `src/commands/`, register in `src/cli.ts` dispatch + the
-  commander metadata in `src/mm-harness-cli.ts` (help group), contract test.
-- **A flag**: parse in the verb module; if it reaches a leaf, the leaf's parser
-  must accept it (launch-leaf-flags test will fail otherwise) — or pass via env.
-- **A leaf**: shell under `adapters/<platform>/`, spawned via the shared spawn
-  helpers (never raw exec), contract test with PATH stubs, errors teach escape.
-- **A platform behavior**: extend the AdapterSurface, implement per platform —
-  verbs must not branch on adapter for surface-owned behavior.

package/docs/DEBUG-HANDOVER.md

@@ -1,36 +0,0 @@
-# Extension debugger handover
-
-## Objective
-
-Make `mm-harness debug` open the normal Chrome DevTools console attached to the already-running extension page in the current slot. Do not claim success from a URL or JSON response alone.
-
-## Acceptance
-
-1. Start an existing slot runtime with `mm-harness launch --verify`.
-2. Run `mm-harness debug` without relaunching the slot.
-3. Confirm the visible DevTools Console is attached to the existing `chrome-extension://.../home.html#/` target.
-4. Run a harmless console expression and observe its result.
-5. Confirm the debugger remains connected after the extension watcher settles.
-6. Repeat on two isolated extension slots.
-
-## Failed attempts (do not repeat blindly)
-
-This investigation repeatedly reported machine success without proving the visible UI. The following approaches failed:
-
-1. Open the target's hosted `devtoolsFrontendUrl` (`chrome-devtools-frontend.appspot.com`) with macOS `open`. This could select the user's default Chrome profile; when offline it opened an empty tab with `ERR_INTERNET_DISCONNECTED`.
-2. Add `--remote-allow-origins=https://chrome-devtools-frontend.appspot.com`. This fixed one observed HTTP 403 origin rejection but did not make the visible frontend reliable.
-3. Open the hosted URL through the slot profile using `open -na`. It still produced a separate disconnected DevTools tab.
-4. Create a tab through the slot CDP `/json/new` endpoint using `devtools://devtools/bundled/inspector.html?...`. The tab was created, but the visible UI still reported `Debugging connection was closed`.
-5. Add `devtools://devtools` to `--remote-allow-origins`. Direct CDP to the extension target still worked, but the human DevTools UI was not proven connected.
-6. Testing the local checkout while the user invoked the globally installed command caused false confidence: the global command was running a different installation. The global install was temporarily overwritten with unreleased local code; do not assume the published version contains these changes.
-
-Screenshots showed the exact failure: a DevTools tab exists, but displays `Debugging connection was closed — WebSocket disconnected`. Direct CDP to the extension page succeeds, so target discovery is not the failure; the human DevTools frontend attachment/lifecycle remains unresolved.
-
-## Constraints
-
-- Do not open an unrelated/default Chrome profile.
-- Do not silently fall back to another tab and report success.
-- Keep the extension target unchanged.
-- Do not modify product code or commit until the visible acceptance steps pass.
-- Test the actual human UI, not only `--json`, `/json/list`, or a raw CDP handshake.
-- Never report `opened: true` or a present `/json/list` target as proof that the visible DevTools console is attached.

package/docs/MENTAL-MODEL.md

@@ -1,295 +0,0 @@
-# mm-harness — Mental Model (review first)
-
-Read this before the code. It is the before→after map for the CLI refactor. Every
-"today" command below is real (from `bin/mm-recipe`, `bin/mme-recipe`,
-`runner/src/cli.ts`, and the `recipe-harness` skill) — nothing invented.
-
-> Skimmable overview. The detailed contract — a complete capability inventory
-> (every verb, with a fate), a per-verb spec, the caller audit, and the env-var
-> audit — is in [CLI-SPEC.md](CLI-SPEC.md).
-
-## The model in one paragraph
-
-**`mm-harness` is built for the agent but easy for the human to use and
-understand.** It is the one front door for the whole recipe loop. The agent gets
-full depth (explicit flags, `--json`, ports, build tiers — machine-grade
-determinism); the human gets short verbs, positional targets, good defaults,
-completions, and teaching help/errors. Under it: the **engine** is
-`@farmslot/recipe-harness` (generic graph execution, adapters, recording, CLI);
-the **runner** (this repo) is the thin **MetaMask adapter** layer (manifests,
-`metamask.*` live adapters, orchestration); the **runtime overlay** is the set of
-files the tool installs into a target checkout (`install`/`verify`/`cleanup`).
-The runner never re-implements engine logic — it imports it. The agent
-composition loop is the harness's thesis made concrete: **discover** actions and
-browse flows (`actions --json` / `flows --json`) → **call** one action in
-isolation to verify it (`call <action> --json`) → **compose** a `recipe.json` →
-**plan** before any device is touched (`run --plan`) → **run** → review
-evidence (`summary.json` / `trace.json`). `run --plan` closes the loop: adapter-aware
-validation (action existence, platform support, fixture preconditions) exits fast
-with a reviewable plan artifact — wrong recipes fail before any device is touched.
-
-## Organizing rule (Arthur)
-
-Identify the MAIN commands a human types daily, then each subcommand — always
-optimizing "how simple for the human," with advanced options for the agent and
-good defaults for easy typing. Enforced rules, visible in every table below:
-
-- **Grammar:** `mm-harness <verb> [target] [flags]`. Target is a positional
-  (`ios` | `android` | `extension`) — the human form. The equivalent explicit
-  flag (`--platform …`) is the agent form.
-- **Depth lives in FLAGS, never in extra command names.** If a daily task needs
-  >1 flag (or >1 step) for a human, the default is wrong — a `[DEFAULT-GAP]`.
-- **No env-var prefixes for humans.** `VAR=x mm-harness …` is agent/CI syntax
-  only; a human-typed value that has no flag/config home is an `[ENV-GAP]`.
-- **One bin, clean break.** End state has exactly one command, `mm-harness`. The
-  `metamask-recipe` / `mm-recipe` / `mme-recipe` names and the `harness <verb>`
-  subcommand form are REMOVED in the same coordinated wave; their capabilities
-  live at their final `mm-harness` home (Part 2 of the spec).
-- **A verb's most common action is its default action.** `mm-harness flows` lists;
-  `mm-harness flows promote` is the explicit subcommand. Never force the user to
-  type `list` when listing is what the verb does by default.
-- **Direct action names are not top-level verbs (REJECTED).** `mm-harness unlock`
-  is rejected — an open action vocabulary collides with the verb namespace; hot
-  actions get deliberately promoted to real verbs instead. Use
-  `mm-harness call unlock` (fuzzy short-name resolution to `metamask.wallet.unlock`
-  when unambiguous).
-- **The overlay is per-checkout, git-ignored plumbing — humans never manage it.**
-  Daily verbs (`launch`, `run`) check for the overlay at startup and
-  auto-install it inline with a one-line notice on first run on that checkout.
-  `install` is the explicit form for CI, agents, and deterministic setup
-  (`--heal=off` on daily verbs disables the inline check and all healing).
-- **Your checkout's settings live in `agentic-runtime.json` — `doctor --fix` creates
-  local identity/resources when absent and `doctor` explains them;
-  you never hunt for the file.** `doctor` prints every field (slotId, extensionId,
-  cdpPort, runtimeStart.*), its current value, its source (file / env var /
-  default), and exactly how to change it. Arthur's rule made concrete: no
-  knowledge lock-in about which file to edit.
-- **Verbs are idempotent — they make reality match intent; the recovery command is
-  the normal command.** `launch` and `run` detect broken runtime state
-  (Metro dead, Chrome/CDP offline, stale tabs) and heal before proceeding (controlled
-  by `--heal`; default `auto` for `launch`, `infra-only` for `run`). The
-  agent does not need a separate recovery verb: re-running `mm-harness launch ios`
-  IS the recovery. `--json` reports what was healed in a `recovered:[...]` field
-  (stable codes). `recoverable:false` + `attemptedRecoveries[]` stop agent retry
-  loops when bounds are hit. `doctor --fix` repairs without launching when healing
-  alone is the goal.
-
-## Status legend
-
-| Tag | Meaning |
-|---|---|
-| **ROUTES-NOW** | Works today through `mm-harness` (this draft) |
-| **STUB** | `mm-harness` verb exists but exits 2 and teaches the working command; spec'd in Part 2 |
-| **ABSORB-LATER** | Capability folds into an `mm-harness` verb (spec'd in Part 2 with a maps-to row) |
-| **KEEP-INTERNAL** | Still reachable, just not a user-facing verb |
-| **REMOVE** | Name/bin/subcommand deleted in the refactor wave; callers updated in the same wave (needs sign-off) |
-
-## Bin & name table (before → after)
-
-| Before | Role today | After |
-|---|---|---|
-| `bin/metamask-recipe` | public typed CLI + platform passthrough | **REMOVE** — becomes `bin/mm-harness` (same entrypoint, one name); no alias kept |
-| `metamask-recipe harness <verb>` | overlay lifecycle subcommand | **REMOVE** — verbs live top-level (`mm-harness install/verify/cleanup`); `live` dissolved into `launch --verify` |
-| `bin/mm-recipe` | mobile porcelain (Metro/sim/bridge) | **REMOVE** — capabilities become `mm-harness` verbs (Part 2); impl kept internal |
-| `bin/mme-recipe` | extension porcelain (Chrome/CDP) | **REMOVE** — capabilities become `mm-harness` verbs (Part 2); impl kept internal |
-| `recipe-harness` skill (~812 lines bash) | overlay lifecycle | **REMOVE** — thins to a caller of `mm-harness` overlay verbs |
-| `completions/_recipe` (zsh; completes `recipe mme-recipe mm-recipe`) | shell completion | **REMOVE** — replaced by bundled `mm-harness` completions (zsh + bash), auto-installed on setup |
-
-**`bin/mm-harness`** is the one user bin. **No per-platform binaries** —
-`mm-mobile-harness` / `mm-extension-harness` are rejected (recreates the
-three-names problem). Platform = auto-detected context; the positional target
-forces it; platform-specific needs are FLAGS on the same verb.
-
----
-
-## BEFORE → AFTER by main command
-
-Columns: **Human form** (bare verb / positional target; zero env prefixes;
-defaults stated) · **Agent / advanced form** (explicit flags, `--json`) · **Status**.
-
-### DAILY LOOP
-
-#### `launch` — start the app (Metro/build + boot)  ·  REAL (wave 3)
-
-Auto-ensures runtime overlay before launching (installs inline with a one-line notice on first run; `--heal=off` to disable). **Idempotent + self-healing (default `--heal=auto`):** detects broken runtime state (Metro dead, Chrome/CDP offline, stale home tabs) and recovers before launching. The agent's recovery command is simply `mm-harness launch <target>` — no separate recovery verb. `--json` gains `"recovered": ["metro.restarted", ...]` (stable codes); `recoverable:false` + `attemptedRecoveries[]` stop retry loops. **`--verify`:** after launch, polls CDP/bridge until ready + runs smoke verify — implements the retired `live` sequence (zero capability lost). **Change detection:** quick launch (no `--build`) checks native/webpack build inputs; if changed → refuses with teaching error pointing at `--build`. Phase state-machine: `resolve → install → healthcheck → recover → launch → verify`.
-
-| | |
-|---|---|
-| **Human form (mobile)** | `mm-harness launch ios` · `mm-harness launch android` — target **MANDATORY**; missing → teaching error: "specify ios or android" |
-| **Human form (extension)** | `mm-harness launch` (no target; default `--fullscreen`; `--sidepanel` to open sidepanel mode) |
-| **Quick vs full build** | bare `launch` = quick relaunch (no native/webpack build); `--build` = full build first |
-| **Runway (mobile only)** | `--runway` runs a post-launch runway check; teaching error on extension |
-| **`live` replacement** | `mm-harness launch ios --verify` (install overlay → launch → poll → smoke verify — never seeds fixtures) |
-| **Agent / advanced** | `mm-harness launch --platform ios --device <udid> --build --verify --heal=off --json` |
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `mm-recipe ios` · `android` · `start` | `launch ios\|android` (positional, mandatory) | ABSORB-LATER |
-| `mm-recipe up` | `launch ios --build` | ABSORB-LATER · [DEFAULT-GAP] tier hidden behind `MOBILE_PREFLIGHT_MODE=…` [ENV-GAP] |
-| `mm-recipe refresh` · `reload` · `relaunch` | `launch ios\|android` (quick) | ABSORB-LATER |
-| `mme-recipe rebuild` · `reopen` · `browser` · `launch` · `reload` · `reset` | `launch` (quick, extension) | ABSORB-LATER |
-| `mme-recipe up` | `launch --build` (extension) | ABSORB-LATER |
-| `mme-recipe watch` **then** `rebuild` | `launch --watch` (extension) | ABSORB-LATER · [DEFAULT-GAP] two commands today |
-| `mme-recipe build` · `refresh` · `refresh-once` | `launch` tiers (extension) | ABSORB-LATER |
-| `mme-recipe sidepanel [cycle\|open]` | `launch --sidepanel` (extension) | ABSORB-LATER |
-
-#### `logs` — tail Metro/webpack + app logs  ·  REAL (wave 3)
-
-| | |
-|---|---|
-| **Human form** | `mm-harness logs` (compact, auto platform) |
-| **Agent / advanced** | `mm-harness logs --full --platform mobile --json` |
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `mm-recipe logs` · `tail` · `logs --full` | `logs [--full]` | ABSORB-LATER · [ENV-GAP] `RECIPE_LOG_UI`/`RECIPE_LOG_EVENTS` → flags |
-| `mme-recipe logs` · `tail` · `tail-webpack` | `logs` | ABSORB-LATER |
-
-#### `debug` — open the debug console  ·  REAL (wave 3)
-
-| | |
-|---|---|
-| **Human form** | `mm-harness debug` (auto platform) |
-| **Agent / advanced** | `mm-harness debug --worker` (extension SW) · `--dev-menu` · `--platform mobile` |
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `mme-recipe debug` · `devtools` · `inspect` · `debug worker` | `debug [--worker]` | ABSORB-LATER |
-| `mm-recipe debug` | `debug` | ABSORB-LATER |
-| `mm-recipe dev-menu` · `devmenu` | `debug --dev-menu` (flag) | ABSORB-LATER · [DEFAULT-GAP] separate verb for one console concept |
-
-#### `fixtures` — initialize/sync fixture files + set up the wallet  ·  REAL (wave 3)
-
-One canonical wallet fixture per checkout (SSOT). Fixture status is reported by `doctor` automatically. Initialize from an existing secure team/test fixture or explicitly choose a disposable public dev wallet; secrets are never typed into chat or command arguments.
-
-Subcommands: `fixtures init`, `fixtures sync`, `fixtures set`, plus Extension generate/finalize helpers.
-
-| | |
-|---|---|
-| **Human form** | `mm-harness fixtures init --from <path>` or explicit `--dev` · `fixtures sync` · `fixtures set` (password read FROM the fixture, never typed) |
-| **Agent / advanced** | `mm-harness fixtures set --fixture <json> --platform mobile` (`--fixture` is agent-only; humans edit the canonical file directly) |
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `mm-recipe sync` · `mme-recipe sync` | `fixtures sync` | ABSORB-LATER |
-| `mme-recipe update` · `sync-runtime` | `fixtures sync` | ABSORB-LATER |
-| `mm-recipe setup-wallet` · `wallet-setup` | `fixtures set` | ABSORB-LATER · [ENV-GAP] `RECIPE_WALLET_FIXTURE` → `--fixture` (agent-only) |
-| `mm-recipe setup:ios` · `setup:android` | `launch ios` **then** `fixtures set` | ABSORB-LATER |
-| `mm-recipe unlock` | `fixtures set` (password from fixture) | ABSORB-LATER · [ENV-GAP] `MM_PASSWORD=… unlock` is the anti-pattern — read the fixture |
-| Extension standalone wallet setup | `fixtures set` | **[GAP]** no standalone verb today — the first-run wallet is seeded by the legacy `mme-recipe up`; end-state home is `fixtures set` (launch / `launch --verify` never seed) |
-
-### DISCOVER  (agent composition layer — `--json` is PRIMARY)
-
-The composition loop: `actions --json` → `call <action>` (try one via real engine path) → `flows --json` → compose `recipe.json` → `run --plan` (adapter-aware validate + plan, no device) → `run`.
-
-`manifest` is **RETIRED**: raw protocol dump → `actions --raw`; validation → `run --plan` / `doctor`. `validate` verb **DISSOLVED** into `run` (`run` validates first; `run --plan` = plan-only; same or richer shape, plus adapter cross-check). **DISCOVER final shape: `actions` · `call` · `flows`** — no manifest verb, no validate verb. Shell completions are sourced from this same layer: `call` completes action names, `run`/`run --plan` complete flow refs, both with a per-checkout short-TTL cache.
-
-#### `actions` · `call` · `flows`  ·  ROUTES-NOW (call: REAL wave 2)
-
-| | |
-|---|---|
-| **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 }] }` |
-| | `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 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 |
-| `mm-harness validate recipe.json` (old stub) | `mm-harness run recipe.json --plan` | **DISSOLVED** — stub teaching message updated to point at `run --plan`; `validate-command.ts` called internally by run engine (phase: `validate`) |
-
-### PROVE
-
-#### `run` — validate + execute a recipe, write evidence  ·  ROUTES-NOW
-
-**Validates first (adapter-aware):** before touching any device, `run` checks action existence, platform support, and fixture preconditions. Exit 5 on validation errors (same code for `run`, `run --plan`, `call`). `--plan` = plan-only: prints what would happen, touches NO device, exits 0/5. Phase state-machine: `resolve → install → healthcheck → recover → validate → launch → execute`. `--heal` defaults `infra-only`; healing never touches wallet state — only the explicit `fixtures set` mutates it.
-
-| | |
-|---|---|
-| **Human form** | `mm-harness run recipe.json` (adapter + artifacts auto-defaulted) |
-| **Plan before run** | `mm-harness run recipe.json --plan` (adapter-aware; no device; exit 0 = valid, exit 5 = errors) |
-| **Agent / advanced** | `mm-harness run recipe.json --adapter mobile --project-root <repo> --artifacts-dir <dir> --record-video=full-run --heal=off --json --json-stream` |
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `metamask-recipe run … --adapter … --artifacts-dir …` | `mm-harness run …` | ROUTES-NOW · [DEFAULT-GAP] `--adapter` + `--artifacts-dir` mandatory today · [ENV-GAP] `RECIPE_LIBRARY_PATH` → `--library`/config |
-| `mm-recipe run recipe.json` · `mme-recipe run recipe.json` (auto adapter+artifacts) | `mm-harness run recipe.json` | ABSORB-LATER — porcelain already supplies the good defaults the typed CLI lacks |
-
-#### `doctor`  ·  ROUTES-NOW
-
-Pure read-only diagnostic. Absorbs the retired `manifest` verb's validation: readiness checks include manifest well-formedness + reports manifest path + protocol version. `--fix` mode runs healing without launching (same path as `launch`/`verify` self-healing but stops short of starting the app).
-
-| | |
-|---|---|
-| **Human form** | `mm-harness doctor` |
-| **Agent / advanced** | `mm-harness doctor --adapter mobile --target <repo> --json` |
-| **Repair without launch** | `mm-harness doctor --fix [--json]` → `{ ..., "fixed": [...], "failed": [...] }` |
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `metamask-recipe doctor --adapter … --target …` | `mm-harness doctor` | ROUTES-NOW · [DEFAULT-GAP] `--adapter`+`--target` required |
-| `mm-recipe`/`mme-recipe` `doctor` (auto adapter/target) | `mm-harness doctor` | ABSORB-LATER — porcelain supplies the missing defaults |
-
-### RUNTIME OVERLAY
-
-#### `install` · `verify` · `cleanup`  ·  ROUTES-NOW
-
-`live` is **REMOVED** — dissolved into `launch --verify` (same sequence: install overlay if missing → launch → CDP poll → smoke verify; zero capability lost — `launch --verify` never seeds fixtures).
-
-| | |
-|---|---|
-| **Human form** | `mm-harness install` · `verify` · `cleanup` (platform auto-detected, target = cwd) |
-| **`live` replacement** | `mm-harness launch [ios\|android] --verify` |
-| **Agent / advanced** | `mm-harness verify --platform extension --target <repo> --json -- --cdp-port <port>` |
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `recipe-harness install\|verify\|cleanup\|live …` (skill) | `mm-harness install\|verify\|cleanup` · `live` → `launch --verify` | ROUTES-NOW; skill REMOVE |
-| `metamask-recipe harness install\|verify\|cleanup\|live …` | `mm-harness install\|verify\|cleanup` (top-level) · `live` → `launch --verify` | ROUTES-NOW; `harness` prefix REMOVE |
-| `mm-recipe prepare` · `mme-recipe prepare` | `install` / `launch` prep | ABSORB-LATER |
-| `mme-recipe ready` · `ensure-ready` | `verify` (or advanced `ensure-ready`) | ABSORB-LATER |
-
-### ADVANCED (agent / internal — rarely typed by hand)
-
-| Today (real) | → mm-harness | Status |
-|---|---|---|
-| `metamask-recipe runtime-health` · `runtime-decision` · `runtime-launch` · `resolve-extension` · `ensure-ready` · `self-test` | logic moves INSIDE `launch`/`verify` self-healing path — no user-facing verb; `self-test` callable via `package.json` scripts only | KEEP-INTERNAL |
-| `metamask-recipe manifest --adapter …` | **RETIRED** — (1) validation → `doctor` readiness check; (2) raw dump → `mm-harness actions --raw`; (3) path + protocol version → `doctor` explain-my-setup | REMOVE |
-| `mm-recipe`/`mme-recipe` `runtime-status` · `decision` · `ports` · `status\|home\|health` · `stop` | operator/infra flags on `mm-harness` (e.g. `--json` status) | ABSORB-LATER |
-| `mm-recipe`/`mme-recipe` `completion\|complete` | bundled `mm-harness` completions (dynamic from DISCOVER layer) | KEEP-INTERNAL / REMOVE (old `_recipe`) |
-| `mm-recipe`/`mme-recipe` `interactive\|menu` | interactive shell | ABSORB-LATER |
-| `mm-recipe` bridge verbs: `app-status` · `route` · `navigate` · `back` · `accounts` · `select-account` · `screenshot` | recipe-driven or future flags | ABSORB-LATER |
-
----
-
-## Decisions (final)
-
-The surface below is settled — the design passed a three-round external review (final verdict: SOUND). The rulings that shape day-to-day use:
-
-- **One bin, clean break.** `mm-harness` is the only command; `metamask-recipe` / `mm-recipe` / `mme-recipe` and the `harness <verb>` form are removed in the coordinated caller-sweep wave (CLI-SPEC.md Part 3).
-- **DISCOVER = `actions · call · flows`.** `manifest` is retired (raw dump → `actions --raw`; validation → `run --plan` / `doctor`; path + protocol version → `doctor`). `validate` is dissolved into `run` (`run` always validates first; `run --plan` = plan-only, no device).
-- **`call` is a one-node recipe** through the real engine path — same trace / evidence / `--json` shape as `run`; one execution path, two doors. `call` inherits `run` semantics in full (default `--heal=infra-only`).
-- **`live` is dissolved into `launch --verify`** (install overlay → launch → CDP poll → smoke verify; zero capability lost — `launch --verify` never seeds fixtures). No `live` verb on any surface.
-- **`--heal` = `off | infra-only | auto`** (+ `--yes` for non-interactive confirmation). `launch` defaults `auto`; `run` and `call` default `infra-only`; `off` is repro-preserving and also disables auto-install. Recovery bounds are ALWAYS enforced (recipe running / app-logic failure / same recovery already failed once → `recoverable:false`); no flag bypasses them. `--heal=off` is the single opt-out (it also disables auto-install).
-- **Wallet state is mutated ONLY by the explicit `fixtures set`.** Healing never touches wallet state — overlay / Metro / Chrome recovery is infra; wallet data is not. If recovery would require a wallet write, the verb stops with `recoverable:false` and `userAction: "run mm-harness fixtures set"`. `fixtures` is wallet DATA only and never touches the overlay.
-- **Overlay install notice** (not a "consent print"): stderr-only in human mode; in `--json` it appears solely as `mutations[]`, so stdout stays clean for machines.
-- **Exit code 5 = validation failure everywhere** (`run`, `run --plan`, `call`) — no mode-specific meanings. `run --plan` items carry `confidence: static | conditional` so a plan never claims live runtime facts. Full taxonomy + agent error contract: CLI-SPEC.md Part 5.
-- **Agent error contract:** structured `error:{code,message,cause,retryable,userAction}`, stable `recovered[]` / `mutations[]`, a phase state-machine, JSONL `--json-stream`, and `recoverable:false` + `attemptedRecoveries[]` to stop retry loops (CLI-SPEC.md Part 5).
-- **Quick-launch change detection:** before a quick launch (no `--build`), `launch` checks native/webpack build inputs; if changed → teaching error pointing at `--build`. Never runs on a stale build.
-- **Daily verbs auto-ensure the overlay**; humans never run `install`. `install` / `verify` / `cleanup` are the explicit top-level forms for CI/agents.
-- **`flows` bare = list**; `flows promote` is the explicit subcommand.
-- **Implementation:** `commander` (the library `@farmslot/recipe-harness` already uses) + bundled dynamic zsh/bash completions sourced from the DISCOVER layer.
-
-**Deferred to later waves (sequencing, not open questions):** the `[DEFAULT-GAP]` auto-defaults (adapter/artifacts for `run` / `doctor` / `actions`), the `[ENV-GAP]` env→flag moves (CLI-SPEC.md Part 4), the caller sweep that deletes the old names (Part 3), and the repo rename.
-
-### Considered and rejected
-
-- **Teaching-tombstone stub bins** (`mm-harness-legacy`, etc.): Rejected. Pre-adoption burden with zero payoff; the coordinated wave (CLI-SPEC.md Part 3) updates all callers atomically. No tombstone bins needed.
-
-## How farmslot calls mm-harness (preflight & the fleet binding)
-
-"Preflight" survives as a capability, not an exposed concept: it is what `launch` does before returning (readiness: Metro/bundle → app → health/bridge poll), with `launch --verify` as the prove-it tier and `doctor` as the read-only view. The fleet is just another agent-grade caller — farmslot prepare profiles keep their git / fixtures / deps phases, and the preflight/health hooks collapse to one call: `mm-harness launch <target> --verify --heal=auto --json`. Same-capability by construction: the machine contract (`--json` schemas, `--heal`, exit-code taxonomy, `recovered[]` / `mutations[]` / `recoverable:false`) is the one agents already use. Three bindings, one verb: the engineer types `mm-harness launch ios`; the slot's prepare hook calls the same verb with slot context; dispatch scales it across the fleet. (Full contract: CLI-SPEC.md Part 6.)

package/docs/UX-PRINCIPLES.md

@@ -1,64 +0,0 @@
-# UX principles — the mm-harness interaction contract
-
-Every command surface follows these rules. They are review criteria, not aspirations:
-a PR that adds a command or output path is checked against each one.
-
-**Scope: the HUMAN surface.** The agent contract is exempt and inviolable: under
-`--json`, stdout carries exactly one machine-readable envelope — no color, no
-banners, no decorative lines, schema per CLI-SPEC.md. Progress/streaming exists
-for agents too, but only ever on stderr. When a rule below conflicts with envelope
-purity, the envelope wins.
-
-## 1. Context-aware by default
-The CLI answers relative to the checkout it is standing in.
-- Adapter is auto-detected everywhere (`--adapter` overrides; a bare command never
-  fails on a value detection can supply).
-- The slot context the orchestrator wrote into the checkout
-  (`<runtime_dir>/agentic-runtime.json`) is the authoritative source for device,
-  ports, and slot identity — naming formulas are last-resort fallbacks and never
-  hardcode pool prefixes (they go stale on rename).
-- Output is scoped to the platform: an extension-only field is noise on a mobile
-  slot; help, flag lists, and completion candidates shrink to what applies here.
-- Enforcement: platform-specific behavior is resolved through the adapter surface
-  (`getAdapterSurface(adapter)`), never a per-command `if (adapter === …)` ladder —
-  that ladder is how commands go platform-blind. See docs/ADAPTER-SURFACE.md.
-
-## 2. Never silent, never opaque
-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.
-- 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
-  (window creation is launch-coupled; users re-create separately when they close one).
-
-## 3. Summaries state outcomes
-The final line says what actually happened: target device, what the tier meant,
-resulting state — never a bare status word. Dev-override runs are marked
-(`[dev: MM_HARNESS_BIN]`) so it is always evident which bin served.
-
-## 4. Dev and prod are explicit
-The global install is prod (`mm-harness`); a dev checkout runs via the documented
-`MM_HARNESS_BIN` switch (conventionally aliased `mmdev-harness`). The dev override
-announces itself in help and summaries. Completions cover both names.
-
-## 5. Errors teach the exact escape
-Every failure states the next command for the caller's actual situation. A wrong
-hint (an escape for a different failure mode) is a bug of the same severity as
-the failure itself.
-
-## 6. Lifecycle verbs are symmetric and idempotent
-What a command starts, a sibling verb stops (`launch`/`stop`), scoped to what this
-checkout owns (port-scoped, session-scoped) — never "whatever is running".
-Nothing-to-do is success. Tests never leak into the operator's real tmux.
-
-## 7. Color is consistent and optional
-All human output styles through `cli-color.ts` (headers, ok/warn/err states,
-provenance, "Next:" hints); `NO_COLOR`/non-TTY degrade to plain text. No surface
-invents its own ANSI.
-
-## 8. Doctor is the status surface
-`doctor` reports, per platform: live runtime state (deps currency, dev-server
-up/stale on the slot's resolved port, app/browser presence), the scoped runtime
-context with provenance (`[file]`/`[env]`/`[default]`), and the exact customize
-hint per row. Read-only unless `--fix`.