@deeeed/metamask-harness 0.34.4 → 0.35.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.35.0 - 2026-08-12
+
+### Fixed
+
+- Make Extension and Mobile launch verification fail when their in-app EVM network client cannot complete a live RPC, with exact Infura configuration and retry guidance.
+- Make Extension doctor require checkout-pinned Playwright Chromium and report the exact install command when it is missing.
+- Make doctor report the exact dependency-install command when `--fix` finds stale or missing dependencies instead of implying they were repaired.
+- Make the setup prompt reuse configured skill sources and require consent before cloning or editing shell startup files.
+- Keep installed overlays delegated to the source runner that installed them before falling back to a potentially stale global runner.
+
 ## 0.34.4 - 2026-08-12
 
 ### Changed

package/adapters/core/inject.sh

@@ -88,11 +88,11 @@ install_v1_runner_assets() {
     if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
-    # Resolve the runner at run time (override > global install > install-time
-    # record); the recorded path is last resort so a moved checkout is not pinned.
+    # The recorded runner owns the installed overlay and must remain ahead of an
+    # unrelated global version. MM_HARNESS_BIN is the explicit override.
     printf '%s\n' 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi'
-    printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
     printf 'if [ -x %s ]; then exec %s "$@"; fi\n' "$runner_exec_q" "$runner_exec_q"
+    printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
     printf '%s\n' 'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2'
     printf '%s\n' 'exit 127'
   } > "$HARNESS_DIR/runner/bin/mm-harness"

package/adapters/extension/inject.mjs

@@ -69,17 +69,16 @@ fs.mkdirSync(path.join(harnessDir, 'runner/recipes'), { recursive: true });
 fs.rmSync(path.join(harnessDir, 'scripts'), { recursive: true, force: true });
 fs.mkdirSync(path.join(harnessDir, 'scripts/lib'), { recursive: true });
 
-// Resolve the runner at run time so a moved or shared checkout is never bound to
-// an install-time absolute path: explicit override, then a global install, then
-// the runner recorded at install time as a last resort; teach install on miss.
+// Prefer the runner that installed the overlay so its runtime checks match the
+// installed scripts. Explicit overrides still support controlled delegation.
 const pinnedBin = shellQuote(path.join(runnerDir, 'bin/mm-harness'));
 const delegate = [
   '#!/usr/bin/env bash',
   'set -euo pipefail',
   protocolRoot ? `export FARMSLOT_ROOT=\${FARMSLOT_ROOT:-${shellQuote(protocolRoot)}}` : null,
   'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi',
-  'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi',
   `if [ -x ${pinnedBin} ]; then exec ${pinnedBin} "$@"; fi`,
+  'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi',
   'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2',
   'exit 127',
 ].filter(Boolean).join('\n') + '\n';

package/adapters/mobile/inject.sh

@@ -44,7 +44,7 @@ for rel in "$HARNESS_REL" "$HARNESS_REL/runner" "$HARNESS_REL/scripts"; do
   done
 done
 
-rm -rf "$HARNESS_DIR/runner" "$HARNESS_DIR/scripts"
+rm -rf "$HARNESS_DIR/runner" "$HARNESS_DIR/scripts" "$HARNESS_DIR/bridge-runtime"
 mkdir -p "$HARNESS_DIR/runner/bin" "$HARNESS_DIR/runner/manifests" "$HARNESS_DIR/runner/recipes" "$HARNESS_DIR/scripts/lib"
 
 RUNNER_EXEC_Q="$(printf '%q' "$RUNNER_DIR/bin/mm-harness")"
@@ -62,8 +62,8 @@ PROTOCOL_ROOT_Q="$(printf '%q' "$PROTOCOL_ROOT")"
     printf 'export METAMASK_RUNNER_PROTOCOL_ROOT=${METAMASK_RUNNER_PROTOCOL_ROOT:-%s}\n' "$PROTOCOL_ROOT_Q"
   fi
   printf '%s\n' 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "$MM_HARNESS_BIN" ]; then exec "$MM_HARNESS_BIN" "$@"; fi'
-  printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
   printf 'if [ -x %s ]; then exec %s "$@"; fi\n' "$RUNNER_EXEC_Q" "$RUNNER_EXEC_Q"
+  printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
   printf '%s\n' 'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness@latest" >&2' 'exit 127'
 } > "$HARNESS_DIR/runner/bin/mm-harness"
 chmod +x "$HARNESS_DIR/runner/bin/mm-harness"
@@ -77,6 +77,7 @@ rsync -a --delete "$RUNNER_DIR/library/recipes/" "$HARNESS_DIR/runner/recipes/"
 rm -rf "$HARNESS_DIR/runner/flows"
 rm -f "$HARNESS_DIR/runner/library.json"
 cp "$RUNNER_DIR/adapters/mobile/verify.sh" "$HARNESS_DIR/scripts/verify.sh"
+cp -R "$RUNNER_DIR/adapters/mobile/bridge-runtime" "$HARNESS_DIR/bridge-runtime"
 cp "$RUNNER_DIR/adapters/shared/harness-path.sh" "$HARNESS_DIR/scripts/lib/harness-path.sh"
 cp "$RUNNER_DIR/adapters/shared/path-defaults.json" "$HARNESS_DIR/scripts/lib/path-defaults.json"
 chmod -R u+rwX,go+rX "$HARNESS_DIR"
@@ -114,7 +115,7 @@ fs.writeFileSync(manifestPath, JSON.stringify({
   actionManifestPath: `${harnessRel}/action-manifest.json`,
   runnerEntrypoint: `${harnessRel}/runner/bin/mm-harness`,
   runtimeHelpers: { verify: `${harnessRel}/scripts/verify.sh` },
-  harnessInstalledPaths: [`${harnessRel}/runner`, `${harnessRel}/scripts`, `${harnessRel}/action-manifest.json`],
+  harnessInstalledPaths: [`${harnessRel}/runner`, `${harnessRel}/scripts`, `${harnessRel}/bridge-runtime`, `${harnessRel}/action-manifest.json`],
   productOwnedPaths: ['app/dev-tools/AgenticService', 'app/core/NavigationService/NavigationService.ts'],
   cleanupCommand,
   productDiffExcludes: [`:(exclude)${harnessRoot}`],

package/adapters/mobile/verify.sh

@@ -325,6 +325,35 @@ JSON
   ) > "$log_path" 2>&1
 }
 
+evm_rpc_ready() {
+  local log_path="$1"
+  local bridge="$HARNESS_DIR/bridge-runtime/cdp-bridge.cjs"
+  local expression
+  expression="(async function(){try{var engine=globalThis.Engine;var controller=engine&&engine.context&&engine.context.NetworkController;if(!controller||typeof controller.getSelectedNetworkClient!=='function')throw new Error('NetworkController selected client is unavailable');var client=controller.getSelectedNetworkClient();if(!client||!client.provider||typeof client.provider.request!=='function')throw new Error('selected EVM provider is unavailable');var result=await client.provider.request({method:'eth_blockNumber'});if(typeof result!=='string'||!/^0x[0-9a-f]+$/i.test(result))throw new Error('eth_blockNumber returned an invalid result');return {ok:true,result:result};}catch(error){return {ok:false,error:error&&(error.message||String(error))};}})()"
+  [ -f "$bridge" ] || {
+    printf 'Mobile bridge is missing at %s\n' "$bridge" > "$log_path"
+    return 1
+  }
+  if ! run_with_timeout "$log_path" 25 env \
+    APP_ROOT="$TARGET" \
+    WATCHER_PORT="$port" \
+    IOS_SIMULATOR="${IOS_SIMULATOR:-$ios_simulator_resolved}" \
+    ADB_SERIAL="${ADB_SERIAL:-$adb_serial_resolved}" \
+    ANDROID_SERIAL="${ANDROID_SERIAL:-$adb_serial_resolved}" \
+    node "$bridge" eval-async "$expression"; then
+    return 1
+  fi
+  node - "$log_path" <<'NODE'
+const fs = require('fs');
+try {
+  const result = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  process.exit(result.ok === true ? 0 : 1);
+} catch {
+  process.exit(1);
+}
+NODE
+}
+
 ensure_live_runtime() {
   local device_target="$1"
   local attempt
@@ -419,6 +448,14 @@ JSON
     add_note "Runner v1 live bridge smoke failed; inspect logs/runner-live-smoke.log and runner-live-smoke/trace.json."
     status="fail"
   fi
+
+  if evm_rpc_ready "$ARTIFACTS/logs/evm-rpc-readiness.log"; then
+    checks+=("{\"name\":\"live EVM RPC readiness\",\"status\":\"pass\"}")
+  else
+    checks+=("{\"name\":\"live EVM RPC readiness\",\"status\":\"fail\",\"detail\":\"see logs/evm-rpc-readiness.log\"}")
+    add_note "EVM RPC readiness probe failed. Infura configured ≠ RPC reachable. Next: confirm $TARGET/.js.env has a real MM_INFURA_PROJECT_ID (not 00000000000), then rerun mm-harness launch $PLATFORM --verify --target '$TARGET'."
+    status="fail"
+  fi
 fi
 
 RECIPE_HARNESS_PREFLIGHT_MODE="$PREFLIGHT_MODE" RECIPE_HARNESS_ROOT_EXCLUDE="$HARNESS_ROOT" node - "$ARTIFACTS" "$TARGET" "$status" "${checks[@]}" <<'NODE'

package/dist/adapters/extension/runtime.js

@@ -153,12 +153,26 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     if (runtime.backgroundUnresponsive === true) {
       findings.push("Extension UI reports background connection unresponsive.");
     }
+    if (runtime.ethereumConnectionUnavailable === true) {
+      findings.push('Extension UI reports "Unable to connect to Ethereum".');
+    }
+    if (runtime.evmRpcProbeOk !== true) {
+      const probeError = String(runtime.evmRpcProbeError ?? "unknown error").replace(/[.\s]+$/u, "");
+      findings.push(
+        `EVM RPC readiness probe failed: ${probeError}. Infura configured \u2260 RPC reachable.`
+      );
+    }
     if (runtime.hasSubmitRequest === true && runtime.backgroundProbeOk !== true) {
       warnings.push(`Perps background read probe failed: ${runtime.backgroundProbeError ?? "unknown error"}.`);
     }
     const extensionId = safeExtensionId(target);
+    const evmRpcUnreachable = runtime.ethereumConnectionUnavailable === true || runtime.evmRpcProbeOk !== true;
     return {
       status: findings.length === 0 ? "PASS" : "FAIL",
+      ...evmRpcUnreachable ? {
+        errorCode: "EVM_RPC_UNREACHABLE",
+        userAction: evmRpcRecoveryAction(projectRoot)
+      } : {},
       warnings,
       cdpPort,
       targetUrl: target.url,
@@ -219,21 +233,42 @@ async function evaluateHealth(session, timeoutMs) {
       const storeState = hooks.store?.getState?.() || {};
       const manager = hooks.getPerpsStreamManager?.();
       const accountCache = manager?.account?.cache;
+      const networkConnectionBanner = storeState.metamask?.networkConnectionBanner;
+      const networkClientId = storeState.metamask?.selectedNetworkClientId || networkConnectionBanner?.networkClientId;
       return Promise.race([
         (async () => {
-          let backgroundProbeOk = false;
-          let backgroundProbeError = null;
-          if (typeof hooks.submitRequestToBackground === 'function') {
-            try {
-              const accountState = await hooks.submitRequestToBackground('perpsGetAccountState', []);
-              backgroundProbeOk = Boolean(accountState && typeof accountState === 'object');
-              if (!backgroundProbeOk) backgroundProbeError = 'perpsGetAccountState returned an empty result';
-            } catch (error) {
-              backgroundProbeError = String(error?.message || error);
-            }
-          } else {
-            backgroundProbeError = 'submitRequestToBackground is not a function';
-          }
+          const [backgroundProbe, evmRpcProbe] = await Promise.all([
+            (async () => {
+              if (typeof hooks.submitRequestToBackground !== 'function') {
+                return { ok: false, error: 'submitRequestToBackground is not a function' };
+              }
+              try {
+                const accountState = await hooks.submitRequestToBackground('perpsGetAccountState', []);
+                const ok = Boolean(accountState && typeof accountState === 'object');
+                return { ok, error: ok ? null : 'perpsGetAccountState returned an empty result' };
+              } catch (error) {
+                return { ok: false, error: String(error?.message || error) };
+              }
+            })(),
+            (async () => {
+              if (typeof hooks.submitRequestToBackground !== 'function') {
+                return { ok: false, error: 'submitRequestToBackground is not a function' };
+              }
+              if (typeof networkClientId !== 'string' || networkClientId.length === 0) {
+                return { ok: false, error: 'selected EVM network client is unavailable' };
+              }
+              try {
+                const code = await hooks.submitRequestToBackground('getCode', [
+                  '0x0000000000000000000000000000000000000000',
+                  networkClientId,
+                ]);
+                const ok = typeof code === 'string' && code.startsWith('0x');
+                return { ok, error: ok ? null : 'background EVM RPC returned an invalid result' };
+              } catch (error) {
+                return { ok: false, error: String(error?.message || error) };
+              }
+            })(),
+          ]);
           return {
             href: location.href,
             title: document.title,
@@ -242,14 +277,17 @@ async function evaluateHealth(session, timeoutMs) {
             hasStore: Boolean(hooks.store),
             hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
             backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+            ethereumConnectionUnavailable: bodyText.includes('Unable to connect to Ethereum'),
             activeProvider: storeState.metamask?.activeProvider || null,
             isTestnet: Boolean(storeState.metamask?.isTestnet),
             perpsManagerInitialized: Boolean(manager?.isInitialized?.()),
             positionsCacheIsArray: Array.isArray(manager?.positions?.cache),
             ordersCacheIsArray: Array.isArray(manager?.orders?.cache),
             accountCachePresent: Boolean(accountCache && typeof accountCache === 'object'),
-            backgroundProbeOk,
-            backgroundProbeError,
+            backgroundProbeOk: backgroundProbe.ok,
+            backgroundProbeError: backgroundProbe.error,
+            evmRpcProbeOk: evmRpcProbe.ok,
+            evmRpcProbeError: evmRpcProbe.error,
           };
         })(),
         new Promise((resolve) => setTimeout(() => resolve({
@@ -260,8 +298,11 @@ async function evaluateHealth(session, timeoutMs) {
           hasStore: Boolean(hooks.store),
           hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
           backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+          ethereumConnectionUnavailable: bodyText.includes('Unable to connect to Ethereum'),
           backgroundProbeOk: false,
           backgroundProbeError: 'perpsGetAccountState timed out after ${backgroundProbeTimeoutMs}ms',
+          evmRpcProbeOk: false,
+          evmRpcProbeError: 'background EVM RPC timed out after ${backgroundProbeTimeoutMs}ms',
         }), ${backgroundProbeTimeoutMs})),
       ]);
     })()`,
@@ -293,6 +334,9 @@ function compositorRecoveryAction(projectRoot) {
   const recovery = `mm-harness launch --verify --target ${JSON.stringify(projectRoot)}`;
   return process.platform === "darwin" ? `Unlock the macOS session, then rerun: ${recovery}` : `Restore an active display compositor, then rerun: ${recovery}`;
 }
+function evmRpcRecoveryAction(projectRoot) {
+  return `Confirm ${shellQuote(path.join(projectRoot, ".metamaskrc"))} has a real INFURA_PROJECT_ID (not 00000000000), then rerun: mm-harness launch --verify --target ${shellQuote(projectRoot)}`;
+}
 function resolveCdpPort(rawPort, slot) {
   const raw = rawPort ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT ?? slot?.cdpPort;
   const port = Number(raw);
@@ -759,6 +803,7 @@ export {
   assertHealthyExtensionRuntime,
   checkExtensionRuntimeHealth,
   compositorRecoveryAction,
+  evmRpcRecoveryAction,
   extensionBackgroundProbeTimeoutMs,
   formatHealthFailure,
   prepareExtensionRuntime

package/dist/adapters/extension/surface.js

@@ -14,6 +14,10 @@ function watcherStatus(buildLog) {
   if (buildLog === "no-watch") return "down";
   return buildLog;
 }
+function extensionRuntimeNextAction(reasonCode, target) {
+  const resolved = shellQuote(path.resolve(target));
+  return reasonCode === "deps-missing" || reasonCode === "deps-stale" ? `cd ${resolved} && yarn install --immutable` : `mm-harness launch --adapter extension --target ${resolved}`;
+}
 const extensionSurface = {
   adapter: "extension",
   headless: false,
@@ -42,7 +46,7 @@ const extensionSurface = {
       decision: report.decision,
       reasonCode: report.reasonCode,
       reasons: report.reasons,
-      nextAction: report.decision === "ready" ? void 0 : `mm-harness launch --adapter extension --target ${shellQuote(path.resolve(target))}`,
+      nextAction: report.decision === "ready" ? void 0 : extensionRuntimeNextAction(report.reasonCode, target),
       deps: report.checks.deps.status,
       devServer: {
         label: "webpack",
@@ -96,5 +100,6 @@ const extensionSurface = {
   }
 };
 export {
+  extensionRuntimeNextAction,
   extensionSurface
 };

package/dist/adapters/mobile/surface.js

@@ -5,6 +5,10 @@ import { shellQuote } from "../../commands/parse-args.js";
 import { resolveMobileSlotPorts } from "../slot-ports.js";
 import { mobileRuntimeStatus } from "./prepare.js";
 import { hasRunwayProvisionBaseline, provisionRunwayMobile } from "./provision.js";
+function mobileRuntimeNextAction(reasonCode, target, platform) {
+  const resolved = shellQuote(path.resolve(target));
+  return reasonCode === "deps-missing" || reasonCode === "deps-partial" || reasonCode === "deps-stale" ? `cd ${resolved} && yarn setup` : `mm-harness launch ${platform} --adapter mobile --target ${resolved}`;
+}
 const mobileSurface = {
   adapter: "mobile",
   headless: false,
@@ -21,7 +25,7 @@ const mobileSurface = {
       decision: depsPending ? "launch" : report.decision,
       reasonCode: depsPending ? "app-installed-deps-pending" : report.reasonCode,
       reasons: depsPending ? ["Runway app is installed; JavaScript dependencies are pending until dispatch-time launch."] : report.reasons,
-      nextAction: report.decision === "ready" && !depsPending ? void 0 : `mm-harness launch ${platform} --adapter mobile --target ${shellQuote(path.resolve(target))}`,
+      nextAction: report.decision === "ready" && !depsPending ? void 0 : mobileRuntimeNextAction(report.reasonCode, target, platform),
       deps: runwayProvisioned && report.checks?.deps?.status !== "current" ? "pending" : report.checks?.deps?.status,
       devServer: { label: "metro", status: report.checks?.metro?.status ?? "unprobed" }
     };
@@ -58,5 +62,6 @@ const mobileSurface = {
   }
 };
 export {
+  mobileRuntimeNextAction,
   mobileSurface
 };

package/dist/doctor.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { color } from "./cli-color.js";
 import {
@@ -148,7 +149,8 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
       required: false,
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
     },
-    ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : []
+    ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : [],
+    ...adapter === "extension" ? [extensionBrowserDoctorCheck(target)] : []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
@@ -169,6 +171,32 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
     manifestValidation: manifestValidation.summary
   };
 }
+function extensionBrowserDoctorCheck(target) {
+  const requireFromTarget = createRequire(path.join(path.resolve(target), "package.json"));
+  for (const packageName of ["@playwright/test", "playwright"]) {
+    try {
+      const playwright = requireFromTarget(packageName);
+      const executable = playwright.chromium?.executablePath?.();
+      if (executable && fs.existsSync(executable)) {
+        return {
+          id: "playwright-chromium",
+          status: "pass",
+          required: true,
+          message: "Checkout-pinned Playwright Chromium is installed.",
+          detail: executable
+        };
+      }
+    } catch {
+    }
+  }
+  return {
+    id: "playwright-chromium",
+    status: "fail",
+    required: true,
+    message: "Checkout-pinned Playwright Chromium is not installed.",
+    userAction: "yarn playwright install chromium"
+  };
+}
 function mobileToolDoctorChecks(platform) {
   const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
     { tool: "adb", platform: "Android" },
@@ -250,6 +278,7 @@ function readJsonObject(file) {
 export {
   compatibilityMode,
   createDoctorReport,
+  extensionBrowserDoctorCheck,
   fixtureFileSummary,
   fixtureSummary,
   mobileToolDoctorChecks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.34.4",
+  "version": "0.35.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/scripts/site-contrast.mjs

@@ -358,6 +358,13 @@ async function checkBehavior(browserEndpoint, port, pages) {
           tab.click();
           const panel = document.getElementById(tab.getAttribute('aria-controls'));
           if (!panel || panel.hidden) throw new Error('tab ' + tab.id + ' did not reveal its panel');
+          // Panels ship visible so a dead module degrades to readable prompts
+          // rather than dead controls — which also means "revealed" alone
+          // proves nothing. Selecting one has to hide the others.
+          const shown = [...document.querySelectorAll('[role="tabpanel"]')].filter((p) => !p.hidden);
+          if (shown.length !== 1) {
+            throw new Error('tab ' + tab.id + ' left ' + shown.length + ' panels visible');
+          }
           out.work.push(await grab(panel.querySelector('.cmd .copy')));
         }
         return out;

package/site/architecture.html

@@ -5,7 +5,8 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Architecture — how the pieces fit</title>
 <meta name="description" content="Skills, mm-harness, team recipe libraries, product repos: what lives where, the three workflows, and the mistakes newcomers make.">
-<link rel="stylesheet" href="assets/style.css">
+<link rel="icon" href="assets/metamask-fox.svg" type="image/svg+xml">
+<link rel="stylesheet" href="assets/style.css?v=4">
 </head>
 <body data-progress-page="architecture">
 <a class="skip" href="#stack">Skip to the stack map</a>
@@ -13,18 +14,16 @@
 <header class="topbar">
   <div class="wrap topbar-inner">
     <a class="brand" href="index.html">
-      <span class="brand-mark" aria-hidden="true"></span>
+      <img class="brand-mark" src="assets/metamask-fox.svg" alt="" width="22" height="22">
       <span class="brand-name">recipes</span>
     </a>
     <nav class="nav" aria-label="Main">
       <a class="nav-cta" href="index.html#prompt">Quick start</a>
       <a href="how-it-works.html">How it works</a>
-      <a href="recipes.html">Recipe anatomy</a>
-      <a href="perps.html">Perps</a>
+      <a href="perps.html">Team / Perps</a>
       <a href="cheatsheet.html">Cheatsheet</a>
       <a href="architecture.html" aria-current="page">Architecture</a>
       <a href="tutorials/index.html">Tutorials</a>
-      <a href="reviewers.html">For Reviewers</a>
     </nav>
   </div>
 </header>
@@ -471,8 +470,16 @@
   </ol>
 
   <hr class="sep">
+  <h2>Which repo is which</h2>
+  <p>
+    The layers above are the design. The <a href="ecosystem.html">Ecosystem map</a> is the concrete
+    version: the six repositories and packages behind a run, each with its URL, and which way the
+    dependencies point.
+  </p>
+
   <div class="btn-row">
-    <a class="btn btn-primary" href="how-it-works.html#steps">Do the walkthrough →</a>
+    <a class="btn btn-primary" href="ecosystem.html">See the repo map →</a>
+    <a class="btn btn-ghost" href="how-it-works.html#steps">Do the walkthrough</a>
     <a class="btn btn-ghost" href="reviewers.html">Read an evidence bundle</a>
   </div>
 </section>
@@ -485,6 +492,6 @@
   </div>
 </footer>
 
-<script type="module" src="assets/progress.mjs"></script>
+<script type="module" src="assets/progress.mjs?v=4"></script>
 </body>
 </html>

package/site/assets/metamask-fox.svg

@@ -0,0 +1,24 @@
+<svg width="35" height="34" viewBox="0 0 35 34" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M32.7077 32.7522L25.1688 30.5174L19.4833 33.9008L15.5167 33.8991L9.82793 30.5174L2.29225 32.7522L0 25.0489L2.29225 16.4993L0 9.27094L2.29225 0.312256L14.0674 7.31554H20.9326L32.7077 0.312256L35 9.27094L32.7077 16.4993L35 25.0489L32.7077 32.7522Z" fill="#FF5C16"/>
+<path d="M2.29395 0.312256L14.0691 7.32047L13.6008 12.1301L2.29395 0.312256Z" fill="#FF5C16"/>
+<path d="M9.82959 25.0522L15.0106 28.9811L9.82959 30.5175V25.0522Z" fill="#FF5C16"/>
+<path d="M14.5966 18.5565L13.6009 12.1333L7.22692 16.5009L7.22363 16.4993V16.5025L7.24335 20.9983L9.82809 18.5565H9.82974H14.5966Z" fill="#FF5C16"/>
+<path d="M32.7077 0.312256L20.9326 7.32047L21.3993 12.1301L32.7077 0.312256Z" fill="#FF5C16"/>
+<path d="M25.1722 25.0522L19.9912 28.9811L25.1722 30.5175V25.0522Z" fill="#FF5C16"/>
+<path d="M27.7766 16.5025H27.7783H27.7766V16.4993L27.775 16.5009L21.401 12.1333L20.4053 18.5565H25.1722L27.7586 20.9983L27.7766 16.5025Z" fill="#FF5C16"/>
+<path d="M9.82793 30.5175L2.29225 32.7522L0 25.0522H9.82793V30.5175Z" fill="#E34807"/>
+<path d="M14.5947 18.5549L16.0341 27.8406L14.0393 22.6777L7.23975 20.9984L9.82613 18.5549H14.593H14.5947Z" fill="#E34807"/>
+<path d="M25.1721 30.5175L32.7078 32.7522L35.0001 25.0522H25.1721V30.5175Z" fill="#E34807"/>
+<path d="M20.4053 18.5549L18.9658 27.8406L20.9607 22.6777L27.7602 20.9984L25.1722 18.5549H20.4053Z" fill="#E34807"/>
+<path d="M0 25.0488L2.29225 16.4993H7.22183L7.23991 20.9967L14.0394 22.676L16.0343 27.8389L15.0089 28.976L9.82793 25.0472H0V25.0488Z" fill="#FF8D5D"/>
+<path d="M35.0001 25.0488L32.7078 16.4993H27.7783L27.7602 20.9967L20.9607 22.676L18.9658 27.8389L19.9912 28.976L25.1722 25.0472H35.0001V25.0488Z" fill="#FF8D5D"/>
+<path d="M20.9325 7.31543H17.4999H14.0673L13.6006 12.1251L16.0342 27.834H18.9656L21.4008 12.1251L20.9325 7.31543Z" fill="#FF8D5D"/>
+<path d="M2.29225 0.312256L0 9.27094L2.29225 16.4993H7.22183L13.5991 12.1301L2.29225 0.312256Z" fill="#661800"/>
+<path d="M13.17 20.4199H10.9369L9.72095 21.6062L14.0409 22.6727L13.17 20.4182V20.4199Z" fill="#661800"/>
+<path d="M32.7077 0.312256L34.9999 9.27094L32.7077 16.4993H27.7781L21.4009 12.1301L32.7077 0.312256Z" fill="#661800"/>
+<path d="M21.833 20.4199H24.0694L25.2853 21.6079L20.9604 22.676L21.833 20.4182V20.4199Z" fill="#661800"/>
+<path d="M19.4817 30.8362L19.9911 28.9794L18.9658 27.8423H16.0327L15.0073 28.9794L15.5167 30.8362" fill="#661800"/>
+<path d="M19.4816 30.8359V33.9021H15.5166V30.8359H19.4816Z" fill="#C0C4CD"/>
+<path d="M9.82959 30.5142L15.52 33.9008V30.8346L15.0106 28.9778L9.82959 30.5142Z" fill="#E7EBF6"/>
+<path d="M25.1721 30.5142L19.4817 33.9008V30.8346L19.9911 28.9778L25.1721 30.5142Z" fill="#E7EBF6"/>
+</svg>

package/site/assets/progress.mjs

@@ -241,11 +241,17 @@
    * One tablist per group, roving tabindex: only the selected tab is in the
    * tab order, arrows move between them. Panels stay in the DOM so their
    * commands remain copyable the moment a tab is shown.
+   *
+   * The markup ships every panel visible and the tablist hidden; hiding is
+   * this function's first act. Without it — stale cache, blocked module,
+   * file:// — the reader gets all three prompts stacked instead of controls
+   * that do nothing.
    */
   function initTabs() {
     [].slice.call(document.querySelectorAll('[role="tablist"]')).forEach(function (list) {
       var tabs = [].slice.call(list.querySelectorAll('[role="tab"]'));
       if (!tabs.length) return;
+      list.hidden = false;
 
       function select(tab, focus) {
         tabs.forEach(function (other) {