@deeeed/metamask-harness 0.46.0 → 0.47.1

package/adapters/mobile/wait-for-bridge.sh

@@ -1,52 +1,8 @@
 #!/usr/bin/env bash
-# wait-for-bridge — poll the CDP bridge until a route target is registered.
-#
-# Calls cdp-bridge.cjs status in a poll loop. Emits structured diagnostics on
-# each probe failure: Metro reachability, React Native target visibility, bundle
-# progress. Fails with non-zero if the bridge is not ready within the poll limit.
-#
-# Inputs:
-#   --target <metamask-mobile dir>  (default $PWD)
-#   --port <number>                 (default WATCHER_PORT env, else METRO_PORT, else 8081)
-#   --max-polls <n>                 (default MOBILE_BRIDGE_READY_POLLS env, else 90; 2s each = 180s)
-#   --platform ios|android          bind the required platform: the answering target
-#                                   must belong to it, regardless of ambient device env
-# Outputs:
-#   Progress on stderr; exit 0 bridge ready; 1 timeout.
-#
-# Single device op: wait for bridge readiness. Does not start Metro or open the dev client.
+# Resolve the checkout runtime directory, then delegate the bounded bridge wait
+# to Node so one monotonic deadline covers HTTP, CDP, and retry delays.
 set -uo pipefail
 
-TARGET="$PWD"
-PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
-MAX_POLLS="${MOBILE_BRIDGE_READY_POLLS:-90}"
-REQUIRE_PLATFORM=""
-
-while [ "$#" -gt 0 ]; do
-  case "$1" in
-    --target)     [ "$#" -ge 2 ] || { echo "Missing value for --target" >&2; exit 2; }; TARGET="$2"; shift 2 ;;
-    --port)       [ "$#" -ge 2 ] || { echo "Missing value for --port" >&2; exit 2; }; PORT="$2"; shift 2 ;;
-    --max-polls)  [ "$#" -ge 2 ] || { echo "Missing value for --max-polls" >&2; exit 2; }; MAX_POLLS="$2"; shift 2 ;;
-    --platform)   [ "$#" -ge 2 ] || { echo "Missing value for --platform" >&2; exit 2; }; REQUIRE_PLATFORM="$2"; shift 2 ;;
-    -h|--help)
-      printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>] [--platform ios|android]\n'
-      exit 0
-      ;;
-    *) printf 'wait-for-bridge: unknown arg: %s\n' "$1" >&2; exit 2 ;;
-  esac
-done
-
-case "$MAX_POLLS" in
-  ''|*[!0-9]*) echo "wait-for-bridge: --max-polls must be an integer of at least 2." >&2; exit 2 ;;
-esac
-[ "$MAX_POLLS" -ge 2 ] || { echo "wait-for-bridge: --max-polls must be at least 2 for stable readiness." >&2; exit 2; }
-
-TARGET="$(cd "$TARGET" && pwd -P)"
-
-# The matcher reads the required platform from the environment so the value survives
-# into the node subprocess that runs the shared matcher against the status output.
-export WAIT_FOR_BRIDGE_PLATFORM="$REQUIRE_PLATFORM"
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/../shared/harness-path.sh"
@@ -54,109 +10,16 @@ if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
   echo "wait-for-bridge: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
-LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
-mkdir -p "$LOG_DIR"
-
-BRIDGE_CJS="$(dirname "$0")/bridge-runtime/cdp-bridge.cjs"
-MATCH_LIB="$(dirname "$0")/bridge-runtime/lib/match-bridge-target.cjs"
-STATUS_LOG="$LOG_DIR/bridge-status.log"
-METRO_LOG="$LOG_DIR/metro.log"
 
-if [ ! -f "$BRIDGE_CJS" ]; then
-  printf 'wait-for-bridge: cdp-bridge.cjs not found at %s\n' "$BRIDGE_CJS" >&2
+WAIT_CJS="$SCRIPT_DIR/wait-for-bridge.cjs"
+if [ ! -f "$WAIT_CJS" ]; then
+  printf 'wait-for-bridge: helper not found at %s\n' "$WAIT_CJS" >&2
+  exit 1
+fi
+if ! command -v node >/dev/null 2>&1; then
+  echo "wait-for-bridge: node is required." >&2
   exit 1
 fi
 
-metro_ready() {
-  curl -sf --max-time 2 "http://localhost:${PORT}/status" 2>/dev/null | grep -q 'packager-status:running'
-}
-
-bundle_progress() {
-  local log="$1"
-  [ -f "$log" ] || return 0
-  local p
-  p="$(grep -E '^[[:space:]]*(iOS|Android).*index\.(js|tsx?).*%|Bundl(ed|ing)|Finished' "$log" 2>/dev/null | tail -1 | tr -d '\r' || true)"
-  [ -n "$p" ] && printf ' (%s)' "$p"
-}
-
-bridge_wait_reason() {
-  if ! metro_ready; then
-    printf 'Metro not reachable on port %s' "$PORT"
-    return
-  fi
-  local targets
-  targets="$(curl -sf --max-time 2 "http://localhost:${PORT}/json/list" 2>/dev/null || true)"
-  if [ "$targets" = "[]" ] || [ -z "$targets" ]; then
-    printf 'Metro running; no React Native debug target yet'
-    bundle_progress "$METRO_LOG"
-    return
-  fi
-  if [ -s "$STATUS_LOG" ] && grep -qxF '[]' "$STATUS_LOG"; then
-    printf 'React Native target visible; in-app bridge not ready yet'
-    bundle_progress "$METRO_LOG"
-    return
-  fi
-  printf 'bridge probe failed'
-  bundle_progress "$METRO_LOG"
-}
-
-# Matcher is the shared boundary-safe module (match-bridge-target.cjs), so the
-# launch ready-path confirm and this poll enforce identical platform/device rules.
-bridge_has_route() {
-  (cd "$TARGET" && APP_ROOT="$TARGET" node "$BRIDGE_CJS" status > "$STATUS_LOG" 2>&1) \
-  && node -e '
-const { hasMatchingRoute } = require(process.argv[1]);
-const fs = require("fs");
-try {
-  const value = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
-  process.exit(hasMatchingRoute(value) ? 0 : 1);
-} catch { process.exit(1); }
-' "$MATCH_LIB" "$STATUS_LOG"
-}
-
-# The device/platform this run is pinned to — the bridge target must belong to it.
-requested_target() {
-  node -e 'process.stdout.write(require(process.argv[1]).describeRequested())' "$MATCH_LIB" 2>/dev/null \
-    || printf 'any platform'
-}
-
-# Summarise the targets that DID answer (platform / deviceName), so a timeout teaches
-# what responded vs what was requested — e.g. an iOS target answering an android launch.
-answered_targets() {
-  [ -s "$STATUS_LOG" ] || { printf 'none'; return; }
-  node -e '
-const { describeTargets } = require(process.argv[1]);
-const fs = require("fs");
-try {
-  process.stdout.write(describeTargets(JSON.parse(fs.readFileSync(process.argv[2], "utf8"))));
-} catch { process.stdout.write("none"); }
-' "$MATCH_LIB" "$STATUS_LOG" 2>/dev/null || printf 'none'
-}
-
-READY_STREAK=0
-for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
-  if bridge_has_route; then
-    READY_STREAK=$((READY_STREAK + 1))
-    # The bridge can appear briefly while React Native is still completing its
-    # startup navigation/reload. Require two consecutive healthy snapshots so a
-    # following command never inherits that transient gap.
-    if [ "$READY_STREAK" -ge 2 ]; then
-      printf 'Mobile bridge ready\n' >&2
-      exit 0
-    fi
-  else
-    READY_STREAK=0
-  fi
-  if [ "$ATTEMPT" = "1" ] || [ $((ATTEMPT % 5)) -eq 0 ]; then
-    printf 'Waiting for Mobile bridge (%s/%s): %s\n' "$ATTEMPT" "$MAX_POLLS" "$(bridge_wait_reason)" >&2
-  fi
-  [ "$ATTEMPT" -ge "$MAX_POLLS" ] || sleep 2
-done
-
-cat "$STATUS_LOG" >&2 || true
-printf 'wait-for-bridge: no bridge target matched the requested %s on port %s (%s polls × 2s = %ss)\n' \
-  "$(requested_target)" "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
-printf '  requested: %s\n' "$(requested_target)" >&2
-printf '  answered:  %s\n' "$(answered_targets)" >&2
-printf '  Next: check %s — or run mm-harness status --json\n' "$STATUS_LOG" >&2
-exit 1
+MM_HARNESS_WAIT_RUNTIME_DIR="$(recipe_runtime_dir)" \
+  exec node "$WAIT_CJS" "$@"

package/bin/mm-harness

@@ -144,8 +144,13 @@ if [ -f "$ENTRY_DIST" ] && [ -f "$ENTRY_TS" ]; then
       done < <(find "$RUNNER_DIR/src" -name '*.ts' -newer "$ENTRY_DIST" -print 2>/dev/null)
       if [ -n "$newer_source" ]; then
         export MM_HARNESS_RUN_MODE="src"
-        echo "mm-harness: dist/ is older than src/ — running the current source checkout." >&2
-        echo "  Next: npm run build to refresh dist/" >&2
+        case "${1:-}" in
+          ''|-h|--help|-v|--version|help|tutorial) ;;
+          *)
+            echo "mm-harness: dist/ is older than src/ — running the current source checkout." >&2
+            echo "  Next: npm run build to refresh dist/" >&2
+            ;;
+        esac
       else
         USE_DIST=1
         export MM_HARNESS_RUN_MODE="dist"

package/dist/adapters/mobile/prepare.js

@@ -12,7 +12,7 @@ import {
   mobileMetroEnvCheck,
   recordMobileMetroEnvBaseline
 } from "./metro-env.js";
-const READY_BRIDGE_CONFIRM_POLLS = 3;
+const READY_BRIDGE_CONFIRM_TIMEOUT_MS = 6e3;
 const POD_PROBE_ENV = {
   FORCE_COLOR: "0",
   NO_COLOR: "1",
@@ -69,7 +69,7 @@ async function prepareMobile(target, opts = {}) {
       preflightMode,
       opts.watcherPort
     );
-    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch;
+    return launch;
   }
   if (report.decision === "ready" && clearMetro) {
     const launch = await dispatchActionSequence(
@@ -83,7 +83,7 @@ async function prepareMobile(target, opts = {}) {
       preflightMode,
       opts.watcherPort
     );
-    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch;
+    return launch;
   }
   if (report.decision === "ready") {
     if (restartApp || iosAccessibilityChanged) {
@@ -95,7 +95,7 @@ async function prepareMobile(target, opts = {}) {
         preflightMode,
         opts.watcherPort
       );
-      return launch2.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch2;
+      return launch2;
     }
     const surface = await ensureMobileHumanSurface(
       target,
@@ -104,8 +104,19 @@ async function prepareMobile(target, opts = {}) {
       opts.watcherPort
     );
     if (surface.status !== 0) return surface;
+    const forwarder = await startMobileConsoleForwarder(
+      target,
+      platform,
+      json,
+      opts.watcherPort
+    );
+    if (forwarder.status !== 0) return forwarder;
     const confirm = await dispatchAction(
-      { id: "wait-for-bridge", cwd: target, argv: ["--max-polls", String(READY_BRIDGE_CONFIRM_POLLS)] },
+      {
+        id: "wait-for-bridge",
+        cwd: target,
+        argv: ["--timeout-ms", String(READY_BRIDGE_CONFIRM_TIMEOUT_MS)]
+      },
       target,
       platform,
       json,
@@ -113,12 +124,7 @@ async function prepareMobile(target, opts = {}) {
       opts.watcherPort
     );
     if (confirm.status === 0) {
-      return startMobileConsoleForwarder(
-        target,
-        platform,
-        json,
-        opts.watcherPort
-      );
+      return confirm;
     }
     if (!json) {
       process.stderr.write(
@@ -134,7 +140,7 @@ async function prepareMobile(target, opts = {}) {
       preflightMode,
       opts.watcherPort
     );
-    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch;
+    return launch;
   }
   if (report.decision === "unknown") {
     const msg = "mobile prepare: runtime state unknown\n  Next: run mm-harness verify --adapter mobile --target <checkout>";
@@ -181,6 +187,13 @@ async function prepareMobile(target, opts = {}) {
           opts.watcherPort
         );
         if (surface.status !== 0) return surface;
+        const forwarder = await startMobileConsoleForwarder(
+          target,
+          platform,
+          json,
+          opts.watcherPort
+        );
+        if (forwarder.status !== 0) return forwarder;
         const bridge = await dispatchAction(
           { id: "wait-for-bridge", cwd: target },
           target,
@@ -216,12 +229,7 @@ async function prepareMobile(target, opts = {}) {
       }
     }
   }
-  return startMobileConsoleForwarder(
-    target,
-    platform,
-    json,
-    opts.watcherPort
-  );
+  return actionResult;
 }
 function startMobileConsoleForwarder(target, platform, json, watcherPort) {
   return dispatchAction(

package/dist/adapters/mobile/runtime-decision.js

@@ -96,6 +96,7 @@ const launchActions = (target, clearMetro = false) => {
   });
   actions.push({ id: "prewarm-bundle", cwd: target });
   actions.push({ id: "launch-mobile-runtime" });
+  actions.push({ id: "start-console-forwarder", cwd: target });
   actions.push({ id: "wait-for-bridge", cwd: target });
   return actions;
 };

package/dist/cli-commands.js

@@ -8,6 +8,8 @@ const SPEC = {
     { name: "help", aliases: ["-h", "--help"], desc: "Show usage" }
   ],
   shared: [
+    { name: "help", desc: "Load version-matched recipe guidance", flags: ["--json", "--adapter", "--target"] },
+    { name: "tutorial", desc: "Open the visual recipe tutorial", flags: ["--json", "--no-open"] },
     { name: "setup-base", desc: "Bootstrap numbered product checkouts", flags: ["--dir", "--counts", "--only", "--dry-run", "--force", "--json", "--show-config", "--reset-config", "--skip-harness-update"] },
     { name: "status", aliases: ["health", "home"], desc: "Home status + next commands", flags: ["--json", "--fast"] },
     { name: "ports", desc: "Slot ports and runtime paths", flags: ["--json"] },

package/dist/command-contract.js

@@ -4,6 +4,7 @@ const optionalValue = (choices) => ({ kind: "optional-value", ...choices ? { cho
 const options = (...groups) => Object.assign({}, ...groups);
 const HELP = { "--help": bool(), "-h": bool() };
 const JSON = { "--json": bool() };
+const NO_OPEN = { "--no-open": bool() };
 const JSON_STREAM = { "--json-stream": bool() };
 const TARGET = { "--target": value() };
 const ADAPTER = { "--adapter": value(["mobile", "extension", "core"]) };
@@ -56,6 +57,12 @@ const REMOVED_OPTION_REPLACEMENTS = {
   "--record": "--record-video"
 };
 const PUBLIC_COMMAND_CONTRACTS = {
+  help: {
+    options: options(HELP, JSON, TARGET, ADAPTER)
+  },
+  tutorial: {
+    options: options(HELP, JSON, NO_OPEN)
+  },
   "setup-base": {
     options: options(HELP, JSON, {
       "--dir": value(),

package/dist/commands/checklist.js

@@ -194,6 +194,7 @@ function teachRecipeCompletion(taskDir, step) {
   }
   if (missingQuality) {
     const compactPath = path.join(artifactsDir, "recipe-quality-input.json");
+    console.error("    First run: mm-harness help");
     console.error(`  - ${qualityPath}: write ${compactPath} as:`);
     console.error('    {"verdict":"pass|warn|fail","reasons":["evidence-backed reason"]}');
     console.error(`    then run: mm-harness recipe-quality build --input ${compactPath} --output ${qualityPath}`);

package/dist/commands/help.js

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import { detectAdapter } from "../harness.js";
+import { optionString, parseArgs, targetPath } from "./parse-args.js";
+const UNSCOPED_NEXT = "cd into a MetaMask checkout or pass --adapter <mobile|extension|core>";
+function loadRecipeHelp(packageRoot) {
+  const file = path.join(packageRoot, "site", "assets", "help-recipes.json");
+  const value = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (value.schemaVersion !== 1 || value.topic !== "recipes" || typeof value.title !== "string" || typeof value.summary !== "string" || typeof value.capabilities !== "string" || typeof value.scopeNotice !== "string" || typeof value.recipeProtocolVersion !== "string" || typeof value.safety !== "string" || !Array.isArray(value.sections) || value.sections.length !== 8 || value.sections.some(
+    (section) => !section || typeof section.id !== "string" || typeof section.title !== "string" || typeof section.instruction !== "string" || !Array.isArray(section.details) || section.details.some((detail) => typeof detail !== "string") || !Array.isArray(section.commands) || section.commands.some((command) => typeof command !== "string")
+  )) {
+    throw new Error(`Invalid recipe help data: ${file}`);
+  }
+  return value;
+}
+function recipeHelpPayload(topic, harnessVersion, adapter, target) {
+  const commands = Array.from(new Set(topic.sections.flatMap((section) => section.commands)));
+  const discoveryCommands = topic.sections.find((section) => section.id === "discover")?.commands ?? [];
+  return {
+    schemaVersion: topic.schemaVersion,
+    command: "help",
+    harnessVersion,
+    recipeProtocolVersion: topic.recipeProtocolVersion,
+    adapter,
+    ...adapter === "unscoped" ? { next: UNSCOPED_NEXT } : {},
+    target,
+    topic: topic.topic,
+    title: topic.title,
+    summary: topic.summary,
+    capabilities: topic.capabilities,
+    scopeNotice: topic.scopeNotice,
+    sections: topic.sections,
+    commands,
+    discoveryCommands,
+    safety: topic.safety
+  };
+}
+function renderRecipeHelp(topic, harnessVersion, adapter) {
+  const lines = [
+    `mm-harness ${harnessVersion} recipe guide`,
+    `Context: Recipe Protocol v${topic.recipeProtocolVersion}, adapter ${adapter}`,
+    topic.summary,
+    topic.capabilities,
+    topic.scopeNotice,
+    "Visual tutorial: mm-harness tutorial"
+  ];
+  if (adapter === "unscoped") lines.push(`No MetaMask checkout detected. Next: ${UNSCOPED_NEXT}.`);
+  for (const [index, section] of topic.sections.entries()) {
+    lines.push("", `${index + 1}. ${section.title}`, `   ${section.instruction}`);
+    for (const detail of section.details) lines.push(`   - ${detail}`);
+    for (const command of section.commands) lines.push(`   $ ${command}`);
+  }
+  lines.push("", `Safety: ${topic.safety}`);
+  return `${lines.join("\n")}
+`;
+}
+function handleHelp(argv, context) {
+  const parsed = parseArgs(argv, "help");
+  const target = targetPath(parsed.options);
+  const adapter = optionString(parsed.options, "adapter") ?? detectAdapter(target) ?? "unscoped";
+  const topic = loadRecipeHelp(context.packageRoot);
+  const payload = recipeHelpPayload(topic, context.harnessVersion, adapter, target);
+  if (parsed.options.json === true) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+  } else {
+    process.stdout.write(renderRecipeHelp(topic, context.harnessVersion, adapter));
+  }
+  return 0;
+}
+export {
+  handleHelp,
+  loadRecipeHelp,
+  recipeHelpPayload,
+  renderRecipeHelp
+};

package/dist/commands/parse-args.js

@@ -38,7 +38,8 @@ function parseArgs(argv, command) {
     "printReady",
     "fast",
     "allDevices",
-    "help"
+    "help",
+    "noOpen"
   ]);
   const repeatableOptions = /* @__PURE__ */ new Set(["library"]);
   for (let i = 0; i < argv.length; i += 1) {

package/dist/commands/recipe-quality.js

@@ -6,7 +6,7 @@ import {
 import { EXIT, usageOut } from "./shared.js";
 import { optionFlag, optionString, parseArgs } from "./parse-args.js";
 const BUILD_USAGE = "mm-harness recipe-quality build --input <compact.json> --output <path> [--json]";
-const SHORTHAND_USAGE = "mm-harness recipe-quality build --input <compact.json> --output <path> [--json]\n  Shorthand: mm-harness recipe-quality --input <compact.json> --output <path> [--json]\n  Note: this CLI builds the recipe-quality artifact from an existing compact verdict; recipe critique is performed by the fs-recipe-quality skill.";
+const SHORTHAND_USAGE = "mm-harness recipe-quality build --input <compact.json> --output <path> [--json]\n  Shorthand: mm-harness recipe-quality --input <compact.json> --output <path> [--json]\n  Note: apply the quality bar from mm-harness help, then build its compact verdict here.";
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }

package/dist/commands/tutorial.js

@@ -0,0 +1,46 @@
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "./parse-args.js";
+const PROTECTED_TUTORIAL_URL = "https://glowing-chainsaw-gwzrn8k.pages.github.io/recipes.html#agent-method";
+function recipeTutorialUrl(runMode = process.env.MM_HARNESS_RUN_MODE) {
+  if (runMode === "src") {
+    return "http://127.0.0.1:8765/site/recipes.html#agent-method";
+  }
+  return PROTECTED_TUTORIAL_URL;
+}
+function openUrl(url) {
+  const command = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
+  const result = spawnSync(command[0], command.slice(1), { stdio: "ignore" });
+  return result.status === 0;
+}
+function handleTutorial(argv, context) {
+  const parsed = parseArgs(argv, "tutorial");
+  const url = recipeTutorialUrl();
+  const noOpen = parsed.options.noOpen === true;
+  const opened = noOpen ? false : (context.open ?? openUrl)(url);
+  const payload = {
+    schemaVersion: 1,
+    command: "tutorial",
+    harnessVersion: context.harnessVersion,
+    url,
+    opened
+  };
+  if (parsed.options.json === true) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+    return 0;
+  }
+  if (!noOpen && !opened) {
+    process.stderr.write(`Could not open the browser.
+Next: open ${url}
+`);
+    return 1;
+  }
+  process.stdout.write(`${opened ? "Opened" : "Recipe tutorial"} for mm-harness ${context.harnessVersion}:
+${url}
+`);
+  return 0;
+}
+export {
+  handleTutorial,
+  recipeTutorialUrl
+};

package/dist/mm-harness-cli.js

@@ -8,6 +8,8 @@ import { withCommandJournal } from "./command-journal.js";
 import { JsonStreamWriter } from "./json-stream.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
 import { handleCallHelp } from "./commands/call.js";
+import { handleHelp } from "./commands/help.js";
+import { handleTutorial } from "./commands/tutorial.js";
 import { handleSetupBase } from "./commands/setup-base.js";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { detectAdapter } from "./harness.js";
@@ -21,6 +23,37 @@ globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
 const rawArgv = process.argv.slice(2);
 const REAL = [
+  {
+    name: "help",
+    summary: "Load the version-matched recipe guide for a person or agent.",
+    example: "mm-harness help",
+    helpText: `mm-harness help [flags]
+
+  Loads the complete recipe guide shipped with this harness.
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Load the same guide as structured agent context
+
+Example:
+  mm-harness help
+  mm-harness help --json`
+  },
+  {
+    name: "tutorial",
+    summary: "Open the protected visual recipe tutorial.",
+    example: "mm-harness tutorial",
+    helpText: `mm-harness tutorial [flags]
+
+  Source checkouts open the local tutorial on port 8765. Installed releases
+  open the protected MetaMask GitHub Pages site.
+
+  --no-open                          Print the tutorial URL without opening it
+  --json                             Print version, URL, and open status as JSON
+
+Example:
+  mm-harness tutorial`
+  },
   {
     name: "setup-base",
     summary: "Bootstrap numbered MetaMask product checkouts and install their dependencies.",
@@ -334,9 +367,9 @@ Example:
   written \u2014 an invalid input never reaches disk. Shorthand without "build" is
   also accepted when --input/--output are present.
 
-  This CLI does not run the recipe critique itself; use the fs-recipe-quality
-  skill to judge recipe/evidence quality, then use this command to build the
-  canonical artifact from that compact verdict.
+  Apply the quality bar from mm-harness help to the real graph and
+  evidence, then use this command to build the canonical artifact from that
+  compact verdict. An optional independent reviewer may still critique it.
 
   --input <compact.json>   Compact verdict JSON: { "verdict": "pass|warn|fail", "reasons": [..],
                              "betterVersionGuidance"?: [..], "dimensions"?: {..}, "trainingFields"?: {..}, \u2026 }
@@ -669,7 +702,7 @@ const HELP_GROUPS = [
   {
     title: "DISCOVER",
     blurb: "discover atomic actions and reusable recipes (--json is the agent-primary form)",
-    commands: ["actions", "call", "execution-template"]
+    commands: ["help", "tutorial", "actions", "call", "execution-template"]
   },
   {
     title: "PROVE",
@@ -782,7 +815,7 @@ const pkgVersion = (() => {
   }
 })();
 const program = new Command();
-program.name("mm-harness").description("the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay").version(pkgVersion, "-v, --version", "Print the mm-harness version").helpOption("-h, --help", "Show grouped help").showHelpAfterError("(run `mm-harness --help` for the full surface)").configureHelp({ formatHelp: () => groupedHelp() });
+program.name("mm-harness").description("the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay").version(pkgVersion, "-v, --version", "Print the mm-harness version").addHelpCommand(false).helpOption("-h, --help", "Show grouped help").showHelpAfterError("(run `mm-harness --help` for the full surface)").configureHelp({ formatHelp: () => groupedHelp() });
 for (const command of REAL) {
   const registered = program.command(command.name).description(command.summary).allowUnknownOption().helpOption("-h, --help", "Show command help");
   if (command.aliases?.length) registered.aliases(command.aliases);
@@ -791,6 +824,12 @@ for (const command of REAL) {
     if (command.name === "update") {
       process.exit(await handleUpdate(rawArgv.slice(1)));
     }
+    if (command.name === "help") {
+      process.exit(handleHelp(rawArgv.slice(1), { packageRoot, harnessVersion: pkgVersion }));
+    }
+    if (command.name === "tutorial") {
+      process.exit(handleTutorial(rawArgv.slice(1), { harnessVersion: pkgVersion }));
+    }
     process.exit(await withCommandJournal(command.name, rawArgv, () => delegate(rawArgv)));
   });
 }
@@ -812,7 +851,7 @@ program.command("completions").description("Install/print bundled shell tab-comp
   const result = spawnSync("bash", [script, ...rawArgv.slice(1)], { stdio: "inherit" });
   process.exit(result.status ?? 1);
 });
-const NUDGE_SKIP = ["setup-base", "update", "completions", "completion-candidates"];
+const NUDGE_SKIP = ["help", "tutorial", "setup-base", "update", "completions", "completion-candidates"];
 if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
   maybeNudge();
 }

package/docs/CONTRIBUTING.md

@@ -5,6 +5,8 @@ both the machine contract and the visible human result.
 
 ## Ownership
 
+The generic packages below come from [Farmslot](https://farmslot.io).
+
 ```text
 bin/mm-harness
   -> src/                         typed CLI and product decisions

package/docs/QA.md

@@ -16,7 +16,7 @@ mm-harness --version
 ```
 
 - [ ] The executable and dependencies resolve inside the isolated prefix.
-- [ ] No dependency is a symlink or resolves through a local Farmslot checkout.
+- [ ] No dependency is a symlink or resolves through a local [Farmslot](https://farmslot.io) checkout.
 - [ ] Record the tarball SHA-256 and product SHAs.
 - [ ] Product trees start and finish without tracked changes.
 
@@ -179,7 +179,7 @@ Before release:
 - [ ] Known limits are explicit: Extension requires product Infura setup;
   Mobile requires its normal dev-client/device setup; video requires optional
   `capture-helper`; the harness never invents funded fixtures.
-- [ ] Existing Farmslot slots remain compatible.
+- [ ] Existing [Farmslot](https://farmslot.io) slots remain compatible.
 
 When a slot manager is available, repeat `runner.smoke` in one existing managed
 checkout per product and verify its profile/device, ports, processes, and fixture

package/library/actions/mobile/perps/perps.mjs

@@ -1677,7 +1677,7 @@ async function assertReadyToTrade(input, config) {
   if (config.readyToTrade === undefined || config.readyToTrade === false) return { skipped: true };
   const ready = await evalAsync(
     input,
-    `(function(){ var c=Engine.context.PerpsController; var id=c.state.activeProvider; var p=c.providers && c.providers.get ? c.providers.get(id) : c.getActiveProvider && c.getActiveProvider(); if(!p || typeof p.isReadyToTrade !== 'function') return Promise.resolve(JSON.stringify({ready:false,activeProvider:id || null,error:'provider unavailable'})); return p.isReadyToTrade().then(function(r){ return JSON.stringify({ready:!!(r && r.ready), activeProvider:id || null, authenticatedAddress:(r&&r.authenticatedAddress)||null}); }); })()`,
+    `(function(){ var c=Engine.context.PerpsController; var id=c.state.activeProvider; var p=c.providers && c.providers.get ? c.providers.get(id) : c.getActiveProvider && c.getActiveProvider(); if(!p || typeof p.isReadyToTrade !== 'function') return Promise.resolve(JSON.stringify({ready:false,activeProvider:id || null,error:'provider unavailable'})); return p.isReadyToTrade().then(function(r){ return JSON.stringify({ready:!!(r && r.ready), activeProvider:id || null, authenticatedAddress:(r&&r.authenticatedAddress)||null, error:(r&&r.error)||null, walletConnected:r&&typeof r.walletConnected==='boolean'?r.walletConnected:null, networkSupported:r&&typeof r.networkSupported==='boolean'?r.networkSupported:null}); }); })()`,
   );
   if (!ready.ready) throw new Error(`Perps provider is not ready to trade: ${JSON.stringify(ready)}`);
   return ready;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.46.0",
+  "version": "0.47.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -64,7 +64,7 @@
     "dist",
     "adapters",
     "library",
-    "site",
+    "site/assets/help-recipes.json",
     "scripts/completions.sh",
     "scripts/install-completions.sh",
     "scripts/site-contrast.mjs",