@deeeed/metamask-harness 0.17.4 → 0.18.0

package/docs/CLI-ERGONOMICS-AUDIT.md

@@ -1,32 +0,0 @@
-<!-- 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

@@ -1,64 +0,0 @@
-# Human QA
-
-Run this from each product checkout before a release. Verify the visible outcome,
-not only the exit code.
-
-Run the non-visual gate first:
-
-```bash
-yarn qa:human \
-  --extension /path/to/metamask-extension \
-  --mobile /path/to/metamask-mobile \
-  --core /path/to/metamask-core \
-  --artifacts-dir temp/human-qa
-```
-
-It verifies live readiness, installed runtime, debugger target resolution, smoke
-evidence, and unchanged tracked product source. The checks below cover outcomes
-that still require eyes or an intentional source edit.
-
-## Common
-
-- [ ] `mm-harness --version` prints the candidate version.
-- [ ] `mm-harness doctor` detects the correct product and reports only current
-      configuration.
-- [ ] Without `capture-helper`, `doctor` names the CDP or simulator/ADB screenshot
-      fallback and says video is unavailable.
-- [ ] A misspelled flag explains the error and gives a runnable next command.
-- [ ] `mm-harness actions` and `mm-harness flows` return useful, bounded discovery.
-- [ ] `mm-harness fixtures set` either applies the fixture or names the missing
-      file and exact recovery action.
-- [ ] `mm-harness run <safe-recipe> --artifacts-dir temp/qa-proof` prints findings,
-      diagnostics, and absolute evidence paths.
-- [ ] `mm-harness last --json` identifies that run without rerunning it.
-- [ ] `mm-harness doctor --json` is one parseable document with no human decoration.
-
-## Extension
-
-- [ ] `mm-harness launch` opens/reuses the checkout's named Chrome profile.
-- [ ] `mm-harness launch --sidepanel` opens the MetaMask sidepanel without extra
-      Extension tabs.
-- [ ] `mm-harness debug` opens connected DevTools for the active MetaMask target.
-- [ ] `mm-harness logs --source extension` shows Extension console events.
-- [ ] `mm-harness logs --source dapp` shows dapp console events separately.
-- [ ] Edit a visible source string twice, waiting for successful incremental
-      compilation after each edit; refresh the browser and confirm both changes.
-- [ ] Revert the edit, confirm a third incremental compilation, and verify the
-      same watcher and Chrome process were reused.
-
-## Mobile
-
-- [ ] `mm-harness launch ios` boots/reuses the intended simulator and opens the app.
-- [ ] `mm-harness launch android` targets the intended emulator/device.
-- [ ] `mm-harness logs --source metro` and `--source app` show distinct streams.
-- [ ] `mm-harness debug` opens the usable React Native developer surface.
-- [ ] Change a visible JS string, confirm Metro rebuilds, reload the app, and see
-      the change without a native rebuild.
-
-## Core
-
-- [ ] `mm-harness status`, `doctor`, `actions`, `flows`, and a safe recipe run work
-      without browser/device assumptions.
-
-Record the command, version, checkout SHA, visible mismatch, exit code, and JSON
-error envelope for any failure.

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 and usage errors; 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/UX-PRINCIPLES.md

@@ -1,66 +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. 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.
-- 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
-  (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`.

package/docs/VIDEO-DEMO-VALIDATION.md

@@ -1,74 +0,0 @@
-# Video demo validation
-
-Use this checklist against the installed release before recording. Each checkout
-auto-detects its platform, ports, and slot; the paths below are placeholders only.
-
-```bash
-export EXTENSION_CHECKOUT=/path/to/metamask-extension
-export MOBILE_CHECKOUT=/path/to/metamask-mobile
-export CORE_CHECKOUT=/path/to/core
-```
-
-## Common
-
-- [ ] `mm-harness --version` prints the intended release.
-- [ ] `mm-harness doctor` explains any unavailable capability and gives one next step.
-- [ ] Recipe results print diagnostics and absolute artifact paths inline.
-- [ ] `git status --short` is unchanged in each product checkout after validation.
-
-## Extension
-
-```bash
-cd "$EXTENSION_CHECKOUT"
-mm-harness launch --build --verify
-mm-harness doctor
-mm-harness actions positions
-mm-harness flows
-mm-harness run runner.smoke --artifacts-dir temp/demo
-mm-harness run wallet.smoke --artifacts-dir temp/wallet-demo
-mm-harness logs --source app
-mm-harness debug
-```
-
-- [ ] Launch keeps an incremental webpack watcher alive.
-- [ ] Two small source edits compile incrementally; browser refresh shows both changes.
-- [ ] `debug` connects to the active slot's MetaMask target and opens Console.
-- [ ] `logs --source app` shows extension logs; `--source dapp` and `--source webpack`
-      show their separate streams.
-- [ ] Each recipe prints `diagnostics: CLEAN` or expands every warning/error inline.
-- [ ] Each recipe prints absolute paths for its report, trace, diagnostics, screenshots,
-      and artifact manifest.
-
-## Mobile
-
-```bash
-cd "$MOBILE_CHECKOUT"
-mm-harness launch ios --verify
-mm-harness fixtures set
-mm-harness call metamask.wallet.ensure_unlocked
-mm-harness status
-mm-harness logs --source app
-```
-
-- [ ] The intended simulator is running; focus changes only when explicitly requested.
-- [ ] Fixture setup reads the canonical checkout fixture and unlocks the wallet.
-- [ ] Status reports the live route, wallet state, account, and fixture readiness.
-- [ ] App logs are separate from Metro logs (`mm-harness logs --source metro`).
-
-## Core
-
-```bash
-cd "$CORE_CHECKOUT"
-mm-harness doctor
-mm-harness run runner.smoke --artifacts-dir temp/demo
-```
-
-- [ ] Doctor reports the headless controller ready.
-- [ ] The canonical wallet fixture supplies the default account.
-- [ ] Evidence paths are absolute; diagnostics is explicitly `N/A` for headless Core.
-
-## Recording path
-
-Show the Extension discovery and proof commands, then the equivalent Mobile and Core
-commands. The useful story is: one auto-detected CLI, reusable team libraries,
-parameterized recipes, app diagnostics, and proof artifacts that a human can inspect.

package/docs/architecture.md

@@ -1,88 +0,0 @@
-# Architecture
-
-`mm-harness` is the MetaMask adapter and CLI over the generic Recipe Protocol
-engine. Control flows downward only:
-
-```text
-bin/mm-harness
-  → src/                         typed CLI, decisions, orchestration, evidence
-    → @farmslot/recipe-harness  generic graph execution and transports
-    → @farmslot/protocol        recipe, manifest, trace, artifact schemas
-    → adapters/                 focused OS, browser, simulator, and device leaves
-    → library/                  MetaMask actions, flows, recipes, manifests
-      → MetaMask checkout       app under test
-```
-
-Nothing under `adapters/` or `library/` calls back into `mm-harness`. TypeScript
-owns sequencing; a leaf performs one platform operation and exits; the library
-defines composable behavior.
-
-## Ownership
-
-| Layer | Owns | Does not own |
-|---|---|---|
-| `@farmslot/protocol` | Recipe and evidence schemas | execution or product behavior |
-| `@farmslot/recipe-harness` | graph execution, generic `ui.*`, traces and artifacts | MetaMask behavior |
-| this package | MetaMask actions, runtime control, CLI, diagnostics | task acceptance criteria or copied engine logic |
-| skills/checklists | task workflow and proof expectations | runtime or runner implementation |
-| product checkout | application and explicit debug hooks | harness scripts or private workflow logic |
-
-A capability reusable without MetaMask belongs in the generic engine. A durable
-MetaMask operation belongs here. Ticket-specific assertions stay in the task's
-recipe or checklist.
-
-## Repository layout
-
-| Path | Responsibility |
-|---|---|
-| `bin/mm-harness` | one public executable |
-| `src/commands/` | public command behavior |
-| `src/adapters/` | typed product decisions and orchestration |
-| `adapters/<platform>/` | focused shell/Node runtime leaves |
-| `adapters/shared/` | cross-platform OS glue |
-| `adapters/*/overlay/` | the only files installed or patched into a checkout |
-| `library/actions/` | executable MetaMask action adapters |
-| `library/flows/` | reusable parameterized behavior |
-| `library/recipes/` | reusable proof recipes |
-| `library/manifests/` | declared capability surface |
-| `scripts/` | repository development checks only |
-
-All TypeScript belongs under `src/`. New standalone runtime helpers use ESM
-unless their host runtime requires CommonJS. Shell remains limited to operations
-that genuinely need shell/device tools.
-
-## Runtime isolation
-
-Each checkout owns its runtime state:
-
-```text
-temp/recipe/runtime/   ports, processes, fixture, logs, runtime identity
-temp/recipe/harness/   installed runtime overlay
-```
-
-Defaults live in `adapters/shared/path-defaults.json`. Every browser profile,
-simulator/device selection, port, watcher, and evidence directory must resolve
-from the current checkout so parallel slots do not share state.
-
-Extension uses an isolated Chrome profile and CDP port. Its normal watcher builds
-to product `dist/chrome`, then synchronizes successful output into the isolated
-runtime extension. Mobile owns an isolated Metro/device identity. Core remains
-headless.
-
-## Proof boundary
-
-`launch` prepares the runtime. `run` validates and executes a recipe through the
-generic engine. Runtime setup may seed declared fixtures before proof begins;
-proof actions must not mutate hidden product state to fabricate a result.
-
-Each run produces a summary, trace, diagnostics where applicable, and an artifact
-manifest. Application warnings/errors are side findings unless a recipe assertion
-turns them into a proof failure.
-
-## Change checks
-
-- Put the change in the owning layer; do not duplicate behavior in a skill or leaf.
-- Keep actions parameterized and manifests honest.
-- Validate the machine contract and the visible human outcome.
-- Exercise affected platforms on real checkouts when runtime behavior changes.
-- Run `yarn check` and update `CHANGELOG.md` for user-visible changes.

package/docs/live-adapter-contract.md

@@ -1,190 +0,0 @@
-# Live Adapter Contract
-
-The MetaMask runner implements Recipe Protocol v1 through the shared recipe
-harness package. Project-specific live behavior is supplied by
-manifest-declared action adapters.
-
-Official `ui.*` semantics are implemented by
-`createStandardUiAdapters({ transport })` plus shared CDP/React Native base
-transports. The MetaMask runner supplies only tiny runtime bindings that point
-those base transports at the Extension CDP page or Mobile React Native bridge.
-MetaMask-specific actions remain separate manifest-declared live adapters.
-
-For actions that must prove real product behavior, especially `metamask.perps.*`, static placeholders are refused by default. A live adapter script must exist in one of these locations. Domain-grouped paths are preferred so code ownership stays obvious:
-
-```text
-$METAMASK_RECIPE_LIVE_ADAPTER_DIR/<platform>/<domain>/<action-local-name>.mjs
-$METAMASK_RECIPE_LIVE_ADAPTER_DIR/shared/<domain>/<action-local-name>.mjs
-<runner>/library/actions/<platform>/<domain>/<action-local-name>.mjs
-<runner>/library/actions/shared/<domain>/<action-local-name>.mjs
-```
-
-Action adapters are grouped `.mjs` modules. Flat files, CommonJS, and shell
-adapters are not part of the contract. Do not add `ui.*` files here; official UI
-actions go through shared base transports. Examples:
-
-```text
-library/actions/extension/perps/ensure_positions.mjs
-library/actions/extension/perps/close_positions.mjs
-library/actions/extension/perps/close_orders.mjs
-library/actions/mobile/perps/place_order.mjs
-library/actions/mobile/wallet/ensure_unlocked.mjs
-```
-
-The runner invokes the script with one argument: a JSON input file path. The same path is also available as `METAMASK_RECIPE_ADAPTER_INPUT`. The script must write JSON to `outputPath` from the input document, or print JSON to stdout.
-
-Input shape:
-
-```json
-{
-  "schemaVersion": 1,
-  "platform": "mobile|extension",
-  "action": "metamask.perps.ensure_positions",
-  "node": {},
-  "context": {
-    "nodeId": "ensure-clean",
-    "projectRoot": "/path/to/product",
-    "artifactsDir": "/path/to/artifacts"
-  },
-  "outputPath": "/tmp/.../output.json"
-}
-```
-
-Output shape is action-specific, but must be redacted and suitable for `trace.json`. If the adapter captures evidence files, write them under `context.artifactsDir` and return relative artifact paths for the runner adapter to index in a follow-up implementation.
-
-Proof rule: live adapters must drive real supported app/API paths. They must not write directly into UI state, DOM state, React/Redux/MobX state, local storage, controller internals, or any mid-recipe state that fabricates the proof condition.
-
-## Controller/API calls vs visible UI proof
-
-Recipe authors should choose the layer based on what must be proven:
-
-| Need | Use | Rule |
-|---|---|---|
-| Fast reproducible setup/teardown before or after the proof window | `metamask.*` domain actions such as `start_state`, `ensure_positions`, `close_orders` | May use supported product/controller APIs, but must read/assert the final state. |
-| Read-only state proof | `metamask.*.read_*` or `metamask.*.assert_*` | Must return redacted live state in trace output. |
-| Human-visible acceptance criterion | official `ui.*` actions | Drive the actual visible path: press/tap, input/keypad, scroll into view, screenshot. Do not replace it with a controller call. |
-| Ticket-specific visual detail | task-local recipe assertions/evidence | Do not add a reusable action only for one ticket. |
-
-## Shared action-surface boundaries
-
-The manifest is a durable capability contract, not a place to encode one
-ticket's acceptance criteria. Do not add shared `metamask.*` actions for ticket
-IDs, POCs, exact test IDs, exact copy, styling, placement, or other one-off UI
-proof needs.
-
-Use:
-
-- official `ui.*` actions for reusable presence, input, scroll, and screenshot
-  behavior;
-- screenshot `claims` for visual, copy, and layout proof;
-- task-local composed flows under the task artifact directory when a ticket
-  needs a reusable helper for that ticket only;
-- safe direct CDP/controller calls for read/assert or supported setup paths,
-  never state fabrication.
-
-Add or keep a shared action only when it represents a durable parameterized
-domain capability useful across many tasks, such as `metamask.perps.start_state`,
-`metamask.perps.place_order`, `metamask.perps.close_positions`, or
-`metamask.perps.assert_positions`.
-
-`ui.scroll` is part of the current executable contract and runner.action-validation must
-prove both normal scrolling and `scroll_into_view` before screenshot capture.
-`ui.gesture` is intentionally not advertised yet; drag/swipe proof must wait
-until the shared runtime and this runner expose and validate that action on both
-platforms.
-
-
-
-## Flow catalog follow-up
-
-Action adapters fulfill one manifest-declared operation. Production recipes should also be able to call domain flow catalogs that compose these operations into idempotent `ensure_*` start states. These flows are owned by this runner/domain layer, not by shared runtime packages or wrapper glue.
-
-For Perps, recipes should use the runner-provided `metamask.perps.start_state({ network, provider, page, market, positions, orders })` and `metamask.perps.teardown_state(...)` actions as the default reproducibility boundary. These actions compose primitive bulk operations such as `close_positions({ mode: "all" })` and `close_orders({ mode: "all" })` instead of multiplying one-off cleanup actions.
-
-## Built-in Extension live adapters
-
-The first Extension adapter set is bundled under `library/actions/extension/` and talks directly to the Chrome extension page target over CDP. It does not execute a second recipe graph. The v1 runner still owns workflow traversal; each script only fulfills one manifest-declared action.
-
-Runtime input:
-
-```text
-node.cdp_port | CDP_PORT | RECIPE_CDP_PORT
-```
-
-Optional autolaunch input for existing Extension builds:
-
-```text
-METAMASK_RECIPE_EXTENSION_AUTOLAUNCH=1
-METAMASK_RECIPE_EXTENSION_LAUNCH_EXISTING_DIST=1
-node.launch_existing_dist=true
-```
-
-When enabled, the adapter reuses the requested CDP port if a compatible extension target exists; otherwise it launches Chrome from the target checkout's existing `dist/chrome` without rebuilding the product. The runtime copy, profile, logs, and `runtime.json` are written under `context.artifactsDir/extension-runtime/`.
-
-CLI equivalent:
-
-```bash
-mm-harness run <recipe.json> --adapter extension --cdp-port 6664 --launch-existing-dist --artifacts-dir <dir>
-```
-
-The CLI maps `--cdp-port` to `CDP_PORT`/`RECIPE_CDP_PORT` and maps `--launch-existing-dist` to `METAMASK_RECIPE_EXTENSION_AUTOLAUNCH=1` for the duration of the recipe run.
-
-Currently implemented Extension actions:
-
-```text
-ui.navigate                  # extension: page alias or hash/path/url
-metamask.perps.read_positions
-metamask.perps.read_orders
-metamask.perps.close_positions # primitive bulk close selected positions
-metamask.perps.close_orders    # primitive bulk cancel selected orders
-metamask.perps.place_order
-metamask.perps.assert_positions
-metamask.perps.assert_orders
-metamask.perps.ensure_positions # high-level read/close/place/assert wrapper
-metamask.perps.ensure_orders    # high-level read/cancel/assert wrapper
-ui.press
-ui.scroll
-ui.wait_for
-ui.screenshot
-```
-
-Navigation supports a small discoverable `page` alias set (`home`, `perps`, `perps-market`) plus raw extension hash/url fallback. Check the action manifest before hardcoding routes.
-
-Task-specific UI styling checks, such as one ticket proving a banner color or placement, must not be implemented as reusable `metamask.perps.*` actions. Use official `ui.wait_for` for reusable presence/absence checks plus screenshot/task-local validation evidence for that ticket.
-
-Read-only position checks use `stateHooks.submitRequestToBackground('perpsGetPositions', [{ skipCache: true }])`. State-changing actions prefer UI interaction through CDP mouse/keyboard events. Bulk cleanup primitives may call product background APIs such as `perpsClosePositions` or `perpsCancelOrders` when the UI control is unavailable; this is a supported app/API path, not direct state mutation. Adapters must not mutate Redux/React state, DOM state, local storage, or controller internals to fabricate proof.
-
-## Built-in Mobile live adapters
-
-The Mobile adapter is bundled under `library/actions/mobile/`. Its CDP bridge, wallet setup, target discovery, and screenshot helpers run from the runner runtime; the Mobile checkout must not own harness control scripts. The app still needs a development-only in-app bridge/HUD overlay when a historical checkout does not expose the required `globalThis.__AGENTIC__` hooks.
-
-Runtime input:
-
-```text
-node.watcher_port | node.metro_port | node.cdp_port | WATCHER_PORT | CDP_PORT | RECIPE_CDP_PORT
-node.simulator | node.ios_simulator | IOS_SIMULATOR
-node.android_device | ANDROID_DEVICE
-```
-
-Currently implemented Mobile actions:
-
-```text
-ui.navigate                  # mobile: page alias or route/screen + params
-metamask.perps.read_positions
-metamask.perps.read_orders
-metamask.perps.close_positions # primitive bulk close selected positions
-metamask.perps.close_orders    # primitive bulk cancel selected orders
-metamask.perps.place_order
-metamask.perps.assert_positions
-metamask.perps.assert_orders
-metamask.perps.ensure_positions # high-level read/close/place/assert wrapper
-metamask.perps.ensure_orders    # high-level read/cancel/assert wrapper
-ui.press
-ui.scroll
-ui.wait_for
-ui.screenshot
-```
-
-Navigation supports a small discoverable `page` alias set (`home`, `perps`, `perps-market`) plus raw React Navigation route/params fallback. Check the action manifest before hardcoding routes.
-
-Read-only position checks use `Engine.context.PerpsController.getPositions()` through Hermes CDP. State-changing Perps actions use supported controller APIs (`placeOrder`, `closePositions`) through the same app bridge rather than mutating Redux/React/local storage. Mobile `ui.press` uses `press-test-id` for `test_id`/`testID`/`selector` and `press-text` for visible `text`; scrolling uses `scroll-view`. Screenshot capture uses `xcrun simctl io <simulator> screenshot` for iOS simulator proof.

package/docs/package-boundaries.md

@@ -1,47 +0,0 @@
-# Package Boundaries
-
-This package intentionally stays as **one npm package** with a clear internal
-split. Splitting into two packages now would make users choose between packages
-before the runtime API is stable. Instead, keep one install surface and separate
-responsibilities inside the repo.
-
-## Internal split
-
-| Area | Owns | Does not own |
-|---|---|---|
-| Recipe layer | Action manifests, reusable recipes, typed runner binding, Mobile/Extension live adapters, proof semantics. | Starting Metro/Chrome, simulator boot, native builds, git cleanup. |
-| Runtime lifecycle layer | Harness install/cleanup, Metro/dev-client launch, bundle prewarm, Chrome/CDP launch, fixture/profile setup, readiness gates. | Recipe graph execution, action vocabulary decisions, task-specific proof logic. |
-
-## Stable command contract
-
-Keep the public package simple:
-
-```bash
-mm-harness launch ios ...               # runtime lifecycle, then readiness proof (mobile)
-mm-harness launch ...                   # runtime lifecycle, then readiness proof (extension)
-mm-harness run <recipe.json> ...        # recipe execution only
-```
-
-Wrappers such as skills or slot farms should call those commands. They should not
-copy adapter scripts or reimplement Metro/Chrome launch behavior.
-
-## Why not two packages yet?
-
-A future split may be useful, for example:
-
-- `@metamask/recipe-runner` for manifests/adapters/proof execution;
-- `@metamask/recipe-runtime` for Mobile/Extension sandbox launch.
-
-Do that only after the runtime CLI is stable, all wrappers call it exclusively
-(no copied adapter scripts), and the two areas have gone several releases
-without a change that touches both. Until then, two packages would likely
-increase confusion and version skew.
-
-## Change discipline
-
-1. Prefer moving behavior into the runner before changing farms/skills.
-2. Keep compatibility wrappers when renaming files or commands.
-3. Validate both paths after runtime changes:
-   - direct runner/skill path;
-   - Farmslot/Command Center prepare path.
-4. Do not move files just for tidiness if callers still depend on old paths.