@deeeed/metamask-harness 0.33.2 → 0.33.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.33.3 - 2026-08-05
+
+### Changed
+
+- Lead the getting-started site with what a recipe is for — proving a change inside the running app, catching its own regressions on replay, and standing as the trust layer between an agent's change and a human's review — and add copy-paste prompts for first-time setup and the shared Perps recipe library.
+- Add a dedicated Perps workflow page covering library discovery, testnet-first live proof, platform recipe selection, evidence, composition, and drift classification.
+
+### Fixed
+
+- Raise the site's stated harness floor to 0.33+ and make first-time iOS setup pin one simulator UUID through forced Runway provisioning, install verification, launch, and fixture application.
+- Recover Mobile navigation across typed Hermes target transitions after lifecycle foregrounding with at most one route-verified reissue.
+
 ## 0.33.2 - 2026-08-04
 
 ### Fixed

package/library/actions/mobile/platform/bridge.mjs

@@ -442,34 +442,188 @@ export async function evalSync(input, expression) {
   return parseMaybeJson(await bridgeCommand(input, ['eval', expression]));
 }
 
+const TARGET_TRANSITION_CODES = new Set([
+  BRIDGE_ERROR_CODES.NO_TARGET,
+  BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  BRIDGE_ERROR_CODES.WS_CLOSED,
+]);
+
+function isTargetTransition(error) {
+  return TARGET_TRANSITION_CODES.has(error?.code);
+}
+
+function valueContains(actual, expected) {
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) &&
+      actual.length === expected.length &&
+      expected.every((value, index) => valueContains(actual[index], value));
+  }
+  if (expected && typeof expected === 'object') {
+    return actual && typeof actual === 'object' &&
+      Object.entries(expected).every(([key, value]) => valueContains(actual[key], value));
+  }
+  return Object.is(actual, expected);
+}
+
+function routeMatches(route, expectedRoute, expectedParams) {
+  return routeName(route) === expectedRoute &&
+    (expectedParams === undefined || valueContains(route?.params ?? {}, expectedParams));
+}
+
+function routeTransitionProven(previousRoute, currentRoute, expectedRoute, expectedParams) {
+  if (!previousRoute || !routeMatches(currentRoute, expectedRoute, expectedParams)) return false;
+  if (!routeMatches(previousRoute, expectedRoute, expectedParams)) return true;
+  return Boolean(
+    previousRoute.key &&
+      currentRoute?.key &&
+      previousRoute.key !== currentRoute.key,
+  );
+}
+
+async function waitForNextRouteProbe(deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining > 0) await sleep(Math.min(250, remaining));
+}
+
 export async function navigate(input, route, params = {}, expectedRoute) {
-  const navigation = await bridgeCommand(input, ['navigate', route, JSON.stringify(params)]);
-  const verifiedRoute = String(
-    expectedRoute ??
-      (navigation && typeof navigation === 'object' && navigation.navigated
-        ? navigation.navigated
-        : route),
+  const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15000);
+  const requestedRoute = String(expectedRoute ?? route);
+  const requestedParams = requestedRoute === String(route) ? params : undefined;
+  const transitionCodes = [];
+  let lastTransitionError = null;
+  let navigateAttempts = 0;
+  let previousRoute = null;
+  let recoveryDeadline = null;
+  let recoveryPending = false;
+
+  try {
+    previousRoute = await bridgeCommand(input, ['get-route']);
+  } catch (error) {
+    if (!isTargetTransition(error)) throw error;
+  }
+
+  while (navigateAttempts < 2 || recoveryPending) {
+    if (recoveryPending) {
+      const deadline = recoveryDeadline ?? Date.now() + timeoutMs;
+      let currentRoute = null;
+      while (Date.now() < deadline) {
+        try {
+          currentRoute = await bridgeCommand(input, ['get-route']);
+          if (currentRoute !== null) break;
+        } catch (error) {
+          if (!isTargetTransition(error)) throw error;
+          lastTransitionError = error;
+          transitionCodes.push(error.code);
+        }
+        await waitForNextRouteProbe(deadline);
+      }
+      if (routeTransitionProven(
+        previousRoute,
+        currentRoute,
+        requestedRoute,
+        requestedParams,
+      )) {
+        return {
+          navigated: route,
+          params,
+          previousRoute,
+          currentRoute,
+          deviceName: null,
+          platform: null,
+          verifiedRoute: requestedRoute,
+          bridgeRecovery: {
+            codes: [...new Set(transitionCodes)],
+            navigateAttempts,
+          },
+        };
+      }
+      if (!previousRoute && routeMatches(currentRoute, requestedRoute, requestedParams)) {
+        break;
+      }
+      recoveryPending = false;
+      if (Date.now() >= deadline || navigateAttempts >= 2) break;
+      previousRoute = currentRoute;
+    }
+
+    navigateAttempts += 1;
+    try {
+      const navigation = await bridgeCommand(
+        input,
+        ['navigate', route, JSON.stringify(params)],
+      );
+      const verifiedRoute = String(
+        expectedRoute ??
+          (navigation && typeof navigation === 'object' && navigation.navigated
+            ? navigation.navigated
+            : route),
+      );
+      const verifiedParams = verifiedRoute === String(route) ? params : undefined;
+      const currentRoute = await waitForRoute(
+        input,
+        verifiedRoute,
+        timeoutMs,
+        verifiedParams,
+      );
+      return {
+        ...navigation,
+        currentRoute,
+        verifiedRoute,
+        ...(transitionCodes.length > 0
+          ? {
+              bridgeRecovery: {
+                codes: [...new Set(transitionCodes)],
+                navigateAttempts,
+              },
+            }
+          : {}),
+      };
+    } catch (error) {
+      if (!isTargetTransition(error)) throw error;
+      lastTransitionError = error;
+      transitionCodes.push(error.code);
+      recoveryDeadline = Date.now() + timeoutMs;
+      recoveryPending = true;
+      await waitForNextRouteProbe(recoveryDeadline);
+    }
+  }
+
+  throw lastTransitionError ?? new Error(
+    `Timed out navigating Mobile to route '${requestedRoute}' after ${timeoutMs}ms.`,
   );
-  const currentRoute = await waitForRoute(input, verifiedRoute, Number(input.node?.navigation_timeout_ms ?? 15000));
-  return { ...navigation, currentRoute, verifiedRoute };
 }
 
 function routeName(route) {
   return route && typeof route === 'object' ? String(route.name ?? '') : '';
 }
 
-export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
+export async function waitForRoute(
+  input,
+  expectedRoute,
+  timeoutMs = 15000,
+  expectedParams,
+) {
   const expected = String(expectedRoute);
   const deadline = Date.now() + timeoutMs;
   // lastRoute is null when bridgeCommand returns null (transient: route not yet
   // settled mid-navigation). Null means "not ready yet" — keep polling.
   let lastRoute = null;
+  let lastTransitionError = null;
   let pollCount = 0;
+  const transitionCodes = [];
   while (Date.now() < deadline) {
-    lastRoute = await bridgeCommand(input, ['get-route']);
-    if (routeName(lastRoute) === expected) return lastRoute;
+    try {
+      lastRoute = await bridgeCommand(input, ['get-route']);
+    } catch (error) {
+      if (!isTargetTransition(error)) throw error;
+      lastTransitionError = error;
+      transitionCodes.push(error.code);
+      pollCount += 1;
+      await waitForNextRouteProbe(deadline);
+      continue;
+    }
+    if (routeMatches(lastRoute, expected, expectedParams)) return lastRoute;
     pollCount += 1;
-    await sleep(250);
+    await waitForNextRouteProbe(deadline);
   }
   const target = resolveMobileTarget(input);
   const deviceHint = [
@@ -483,13 +637,18 @@ export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
   const lastReply = lastRoute === null
     ? 'empty/undefined (route transiently unavailable — bridge not yet settled)'
     : JSON.stringify(lastRoute);
-  throw new Error(
+  const timeoutError = new Error(
     `Timed out waiting for Mobile route '${expected}' after ${timeoutMs}ms (${pollCount} polls).\n` +
     `  Expected route: ${expected}\n` +
+    `  Expected params: ${expectedParams === undefined ? 'any' : JSON.stringify(expectedParams)}\n` +
     `  Last parsed route: ${JSON.stringify(lastRoute)}\n` +
     `  Last bridge reply: ${lastReply}\n` +
+    `  Bridge transitions: ${transitionCodes.length > 0 ? [...new Set(transitionCodes)].join(', ') : 'none'}\n` +
     `  Device: ${deviceHint}`,
   );
+  throw lastTransitionError
+    ? coded(timeoutError, lastTransitionError.code)
+    : timeoutError;
 }
 
 export async function simulatorScreenshot(input, relPath) {

package/package.json

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

package/scripts/site-contrast.mjs

@@ -342,7 +342,9 @@ async function checkBehavior(browserEndpoint, port, pages) {
             },
           },
         });
-        const button = document.querySelector('.prompt .copy');
+        // The onboarding prompt is the hero call to action; it was a collapsible
+        // before, so accept either shape.
+        const button = document.querySelector('.cmd-hero .copy, .prompt .copy');
         if (!button) throw new Error('copy button was not initialized');
         button.click();
         await new Promise((resolve) => setTimeout(resolve, 25));
@@ -390,6 +392,17 @@ async function checkBehavior(browserEndpoint, port, pages) {
 
   for (const relative of pages) {
     await withPage(browserEndpoint, `${base}${relative}`, async (page) => {
+      const copyControls = await page.evaluate(String.raw`
+        (() => ({
+          blocks: document.querySelectorAll('.cmd').length,
+          buttons: document.querySelectorAll('.cmd > .copy').length,
+        }))()
+      `);
+      if (copyControls.blocks !== copyControls.buttons) {
+        throw new Error(
+          `${relative} initialized ${copyControls.buttons} copy buttons for ${copyControls.blocks} command blocks`,
+        );
+      }
       const broken = await page.evaluate(String.raw`
         (async () => {
           const links = [...document.querySelectorAll('a[href]')]
@@ -413,6 +426,26 @@ async function checkBehavior(browserEndpoint, port, pages) {
       if (broken.length) {
         throw new Error(`${relative} has broken internal links: ${broken.join(', ')}`);
       }
+      for (const width of [834, 390]) {
+        await page.send('Emulation.setDeviceMetricsOverride', {
+          width,
+          height: 1000,
+          deviceScaleFactor: 1,
+          mobile: false,
+        });
+        const layout = await page.evaluate(String.raw`
+          (() => {
+            const header = document.querySelector('.topbar')?.getBoundingClientRect();
+            const nav = document.querySelector('.nav')?.getBoundingClientRect();
+            return {
+              navOverflow: Boolean(header && nav && nav.bottom > header.bottom + 1),
+            };
+          })()
+        `);
+        if (layout.navOverflow) {
+          throw new Error(`${relative} navigation escapes its header at ${width}px`);
+        }
+      }
     });
   }
 }

package/site/architecture.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="index.html">Start Here</a>
       <a href="recipes.html">Recipes</a>
+      <a href="perps.html">Perps</a>
       <a href="cheatsheet.html">Cheatsheet</a>
       <a href="architecture.html" aria-current="page">Architecture</a>
       <a href="tutorials/index.html">Tutorials</a>
@@ -177,6 +178,12 @@
     these contracts. Evidence returns in the same shape either way, so a fleet result is reviewable by
     whoever wrote the recipe. Parity is structural: one spec, both sides.
   </p>
+  <p>
+    That is what makes the trust layer scale. A proof written once becomes a permanent guard: it is
+    replayed by whoever changes that code next, it stays readable as evidence no matter who or what ran
+    it, and the bug it was written for cannot quietly return. Review does not get weaker as volume
+    grows.
+  </p>
   <p>The seam shows in the CLI's own help — the flags a control plane supplies:</p>
   <div class="out">managed trust boundary (not needed for normal runs; Farmslot supplies it):
   --source-trust, --source-kind, --source-name, --source-digest,
@@ -196,7 +203,10 @@
 
 <section class="wrap">
   <h2 id="loop">The improvement loop</h2>
-  <p>The stack is arranged so each run can leave the next one better informed.</p>
+  <p>
+    A recipe guards the regression it was written for. This is how a team catches the ones nobody has
+    written down yet — each run leaving the next one better informed.
+  </p>
 
   <div class="doctrine">
     <p>
@@ -465,7 +475,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/assets/style.css

@@ -136,9 +136,18 @@ main { padding-bottom: 6rem; }
 
 .brand-name { font-family: var(--mono); font-size: 0.95rem; }
 
-.nav { display: flex; gap: 0.3rem; margin-left: auto; flex-wrap: wrap; }
+.nav {
+  display: flex;
+  gap: 0.3rem;
+  margin-left: auto;
+  min-width: 0;
+  overflow-x: auto;
+  flex-wrap: nowrap;
+  scrollbar-width: thin;
+}
 
 .nav a {
+  flex: none;
   color: var(--text-dim);
   font-size: 0.885rem;
   font-weight: 500;
@@ -333,6 +342,16 @@ main { padding-bottom: 6rem; }
 
 @media (hover: none) { .copy { opacity: 1; } }
 
+/* The one-prompt block is a call to action: its copy control never hides, and
+   the prompt scrolls rather than pushing the page down. */
+.cmd-hero .copy { opacity: 1; }
+.cmd-hero pre {
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 22rem;
+  overflow-y: auto;
+}
+
 /* Expected-output block */
 .out {
   background: var(--bg-raised);

package/site/cheatsheet.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="index.html">Start Here</a>
       <a href="recipes.html">Recipes</a>
+      <a href="perps.html">Perps</a>
       <a href="cheatsheet.html" aria-current="page">Cheatsheet</a>
       <a href="architecture.html">Architecture</a>
       <a href="tutorials/index.html">Tutorials</a>
@@ -37,8 +38,8 @@
     same command. Filter by what you actually work on.
   </p>
   <div class="hero-meta">
-    <span>mm-harness 0.26+</span>
-    <span>one bin, 20 commands</span>
+    <span>mm-harness 0.33+</span>
+    <span>one bin, 21 commands</span>
     <span>--json on everything</span>
   </div>
 </section>
@@ -146,15 +147,15 @@
           <tr data-platforms="all"><td>A recipe with parameters</td><td><code>mm-harness run perps.clean-market-testnet market=BTC</code></td></tr>
           <tr data-platforms="all"><td>A recipe file on disk</td><td><code>mm-harness run ./my-recipe.json</code></td></tr>
           <tr data-platforms="all"><td>Add a team recipe library</td><td><code>mm-harness run &lt;recipe&gt; --library perps=/path/to/library</code></td></tr>
-          <tr data-platforms="mobile"><td>Record video of the whole run</td><td><code>mm-harness run &lt;recipe&gt; --record-video=full-run</code></td></tr>
+          <tr data-platforms="extension mobile"><td>Record video of the whole run (Extension or iOS)</td><td><code>mm-harness run &lt;recipe&gt; --record-video=full-run</code></td></tr>
           <tr data-platforms="all"><td>Streaming progress for an agent</td><td><code>mm-harness run &lt;recipe&gt; --json-stream</code></td></tr>
           <tr data-platforms="all"><td>What did I last run, and how did it go</td><td><code>mm-harness last</code></td></tr>
         </tbody>
       </table>
     </div>
     <p class="step-why" style="font-size:.92rem">
-      iOS carries video; Extension capture is screenshots only. That asymmetry is real — do not promise
-      a reviewer a video of an extension run.
+      Extension and iOS can record full-run video through capture-helper. Android replay video is not
+      implemented yet; use screenshot evidence there.
     </p>
   </div>
 
@@ -296,7 +297,7 @@
 <footer class="footer">
   <div class="wrap-wide">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/index.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="index.html" aria-current="page">Start Here</a>
       <a href="recipes.html">Recipes</a>
+      <a href="perps.html">Perps</a>
       <a href="cheatsheet.html">Cheatsheet</a>
       <a href="architecture.html">Architecture</a>
       <a href="tutorials/index.html">Tutorials</a>
@@ -39,30 +40,118 @@
 
 <main>
 <section class="wrap hero">
-  <span class="eyebrow">Agentic coding at MetaMask</span>
+  <span class="eyebrow">A proposed agentic workflow at MetaMask</span>
   <h1>Drive the wallet. Prove what happened.</h1>
   <p class="lede">
     <code>mm-harness</code> launches a real MetaMask build — Extension, Mobile, or Core — drives it
     through typed actions, and writes evidence a reviewer can check without taking your word for it.
-    Eight steps from an empty terminal to a green run you can open.
+    Paste one prompt and let your agent do it, or walk the eight steps yourself.
   </p>
   <div class="hero-meta">
-    <span>requires mm-harness 0.26+</span>
+    <span>requires mm-harness 0.33+</span>
     <span>~20 minutes</span>
     <span>progress saves in this browser</span>
   </div>
+  <p style="margin-top:.9rem;opacity:.7;font-size:.9rem;max-width:60ch">
+    A proposal for how agents can code at MetaMask — offered for teams to try, not an official standard.
+  </p>
 </section>
 
 <section class="wrap">
-  <h2 id="model">Two words</h2>
+  <div class="agent-card">
+    <h2 style="margin-top:0">Just want to try it? Paste this into your agent.</h2>
+    <p>
+      Start your agent in or near a MetaMask checkout. This installs the harness, proves control of a
+      real build, runs a recipe, and re-runs it — end to end, without reading the rest of this page.
+    </p>
+    <div class="cmd cmd-hero"><pre><code>Task: set me up with the MetaMask recipe workflow and prove it works end to end.
+Follow these steps in order. When a command fails, its message names the exact
+next command — run that instead of improvising.
+
+1. Install the harness: `npm i -g @deeeed/metamask-harness@latest`, then
+   `mm-harness --version` to confirm it resolved.
+2. Checkout: if I started you inside a MetaMask product checkout
+   (metamask-extension, metamask-mobile, or core), use it. If not, run
+   `mm-harness setup-base --dry-run` to show me the layout it would create,
+   and ask me before running it for real.
+3. From inside the checkout, run `mm-harness doctor` and fix every finding by
+   following its own instructions until doctor passes. `mm-harness doctor --fix`
+   repairs harness-owned runtime state; it will not invent credentials or pick
+   a wallet fixture for me.
+4. Run `mm-harness fixtures`. If no fixture exists, run
+   `mm-harness fixtures init --dev`; this creates a disposable public test
+   wallet that must never receive real funds.
+5. Launch and wait for readiness:
+   - Extension: `mm-harness launch --verify`.
+   - Android: `mm-harness launch android --verify`; if more than one device is
+     listed, choose one serial and repeat it with `--device &lt;serial&gt;`.
+   - iOS: run `xcrun simctl list devices available`, choose ONE available iPhone
+     UUID (ask me if the choice is ambiguous), and use that literal UUID in all
+     three commands below — never substitute the simulator name:
+       `mm-harness provision runway ios --device '&lt;UUID&gt;' --force`
+       `xcrun simctl get_app_container '&lt;UUID&gt;' io.metamask.MetaMask app`
+       `mm-harness launch ios --device '&lt;UUID&gt;' --verify`
+   - Core: `mm-harness verify`; it has no app to launch.
+   `--preflight-mode` is an internal adapter flag, not a public launch flag.
+6. On Extension run `mm-harness fixtures set`. On Mobile include the same
+   `--device &lt;UUID-or-serial&gt;` used for launch. Wait for it to succeed.
+7. Discover before acting: run `mm-harness actions`. That list is the ONLY set
+   of capabilities you may use, now and in every later session. Never invent an
+   action or a flag. If you need something not listed, stop and tell me.
+8. Prove control with two calls. On Extension or Mobile, run
+   `mm-harness call read_state` and one listed visible UI action. On Core, run
+   `mm-harness call read_positions mode=all` and
+   `mm-harness call command cmd="echo core-ready"`. Show me both outputs.
+9. Prove a whole task: pick a smoke recipe from `mm-harness run --list`, then
+   `mm-harness run &lt;recipe&gt; --artifacts-dir ./first-recipe-artifacts`.
+   Show me the status from summary.json, the per-node results from trace.json,
+   and the artifact paths.
+10. Without starting a new session, run that same recipe again and confirm it
+   still passes. Checking your own work in the context you did it in is the
+   point; from here on, replay it after every change you make.
+11. Tell me in three sentences: what a recipe proves, where the evidence lives,
+   and which command lists what I can do next.
+
+Not optional: evidence comes only from executed actions — never fabricate a
+result or edit state to manufacture one. If the harness reports a capability as
+unsupported, stop and tell me rather than working around it. If a step fails
+twice after following its error's instructions, stop and show me the exact
+error.</code></pre></div>
+    <p style="margin-bottom:0">
+      Prefer to go step by step? <a href="#steps">Every piece is below.</a>
+    </p>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2 id="why">Why a recipe</h2>
   <p>
-    An <strong>action</strong> is one typed operation: unlock the wallet, press a button, read the
-    account state. A <strong>recipe</strong> is a JSON graph of actions that proves a task. Run one
-    against a real app and the harness records what happened — a per-step trace, a verdict,
-    screenshots. The steps below follow <strong>discover → drive → prove</strong>, which is also the
-    order you will work in from here on.
+    <strong>Proof.</strong> The agent drives a real build, asserts what should be true, and leaves a
+    trace: which actions ran, what they returned, how many times. On-device evidence, not a claim in a
+    pull request description.
+  </p>
+  <p>
+    <strong>Checked before you ever see it.</strong> Replaying a recipe needs no fresh session, no
+    human, and no wait for CI. The agent does it mid-task, in the same context it made the change in —
+    so what arrives at your review has already been verified by the thing that wrote it.
+  </p>
+  <p>
+    <strong>Prevents regressions.</strong> The recipe outlives the change it was written for. Every
+    later change has to pass it too, so the same bug cannot quietly come back: a one-time check becomes
+    a permanent guard.
+  </p>
+  <p>
+    <strong>Trust.</strong> Proven, self-checked, and still proving — so review reads evidence instead
+    of extending credit, and every gate stays yours to steer.
   </p>
+</section>
+
+<section class="wrap">
+  <h2 id="model">Two words</h2>
   <p>
+    An <strong>action</strong> is one typed operation: unlock the wallet, press a button, read the
+    account state. A <strong>recipe</strong> is a JSON graph of actions. The steps below follow
+    <strong>discover → drive → prove</strong>, which is also the order you will work in from here on.
     <code>mm-harness</code> implements the farmslot specification —
     <a href="architecture.html#spec">see Architecture</a>.
   </p>
@@ -78,64 +167,8 @@
 </section>
 
 <section class="wrap">
-  <div class="agent-card">
-    <h2 style="margin-top:0">Or hand it to your agent</h2>
-    <p>
-      Start your agent in (or near) a MetaMask checkout and paste the prompt below. It walks the same
-      eight steps, following each error's own instructions rather than improvising.
-    </p>
-    <p>
-      Do them by hand once anyway — you will be reviewing this workflow's output later, and a bundle
-      you produced yourself is much easier to trust.
-    </p>
-    <details class="prompt">
-      <summary>Show the copyable prompt</summary>
-      <div class="prompt-body">
-        <div class="cmd"><pre><code>Task: set me up with the MetaMask recipe workflow and prove it works end-to-end.
-Follow these steps exactly. Where a tool prints an error, its message contains the
-exact next command — follow that instead of improvising.
-
-1. Install or update the harness: `npm i -g @deeeed/metamask-harness@latest`,
-   then `mm-harness --version` to confirm it resolved.
-2. Repo: use the product checkout I started you in (metamask-extension,
-   metamask-mobile, or core). If I started you outside one, ask me which ONE
-   product to clone and clone just that — do not clone multiples.
-3. Run `mm-harness doctor` from the checkout and fix everything it reports by
-   following each finding's own instructions until doctor passes. `mm-harness
-   doctor --fix` repairs harness-owned runtime state; it will not invent
-   credentials or choose a wallet fixture for me.
-4. Launch the app under harness control: `mm-harness launch` (add `ios` or
-   `android` for mobile; core is headless and has nothing to launch — use
-   `mm-harness verify` there). Wait for the runtime to be ready.
-5. Discovery before anything else: run `mm-harness actions`. That list is the
-   ONLY set of capabilities you may use, now and in every future session.
-   Never invent an action or a flag. If you need something that is not listed,
-   stop and tell me.
-6. Prove basic control with two direct calls. On Extension or Mobile, run
-   `mm-harness call read_state` and one listed visible UI action. On Core, run
-   `mm-harness call read_positions mode=all` and
-   `mm-harness call command cmd="echo core-ready"`. Show me both outputs.
-7. Run one library recipe end-to-end. Pick a smoke recipe from
-   `mm-harness run --list`, then:
-   `mm-harness run &lt;recipe&gt; --artifacts-dir ./first-recipe-artifacts`
-   When it finishes, show me: the status from summary.json, the per-node
-   results from trace.json, and the artifact paths.
-8. Close by telling me, in three sentences: what a recipe is, where the
-   evidence lives, and which command lists what I can do next.
-
-Rules that are not optional: evidence comes only from executed actions — never
-fabricate a result or edit state to manufacture one; if the harness says a
-capability is unsupported, stop and report it rather than working around it;
-if any step fails twice after following its error's instructions, stop and show
-me the exact error.</code></pre></div>
-      </div>
-    </details>
-  </div>
-</section>
-
-<section class="wrap">
-  <h2 id="steps">The walkthrough</h2>
-  <p>Checkboxes persist in this browser, so you can close the tab and come back.</p>
+  <h2 id="steps">Prefer to go step by step?</h2>
+  <p>Here is each piece on its own. Checkboxes persist in this browser, so you can close the tab and come back.</p>
 
   <ol class="steps">
 
@@ -172,7 +205,7 @@ me the exact error.</code></pre></div>
 <span class="p">$ </span>mm-harness --version</code></pre></div>
 
       <div class="out-label">Expected</div>
-      <div class="out">0.26.x  <span class="dim">— any 0.26 or newer</span></div>
+      <div class="out">0.33.x  <span class="dim">— any 0.33 or newer</span></div>
 
       <p class="step-why">Everything from here runs inside a product checkout:</p>
       <div class="cmd"><pre><code><span class="p">$ </span>cd ~/dev/metamask/metamask-extension   <span class="dim"># or metamask-mobile, or core</span></code></pre></div>
@@ -186,7 +219,7 @@ me the exact error.</code></pre></div>
             directory to your shell profile.
           </p>
           <p>
-            <strong>Older than 0.26</strong> — a stale global install is the most common source of
+            <strong>Older than 0.33</strong> — a stale global install is the most common source of
             "the docs don't match my terminal". Run <code>mm-harness update</code>, or
             <code>update --check</code> to look without installing.
           </p>
@@ -208,7 +241,7 @@ me the exact error.</code></pre></div>
 
       <div class="out-label">Expected — a checkout that needs one repair</div>
       <div class="out"><span class="ok">pass</span> extension bridge present manifest=…/extension.action-manifest.json
-harness: @deeeed/metamask-harness@0.26.x
+harness: @deeeed/metamask-harness@0.33.x
 runtime: decision=install (deps-missing) deps=missing webpack=down
   Dependencies are not installed (no yarn install-state markers).
 runtime-context: temp/recipe/runtime/agentic-runtime.json (<span class="bad">absent</span> — run mm-harness doctor --fix)
@@ -264,13 +297,16 @@ capture: <span class="ok">pass</span> (screenshots: capture-helper → cdp; vide
       </div>
       <p class="step-why">
         Starts the app and its dev server, installing the runtime overlay first if missing. Platform is
-        auto-detected; mobile needs an explicit target because the harness will not pick a simulator for
-        you.
+        auto-detected. On iOS, pin one simulator UUID through provisioning and launch so duplicate device
+        names cannot select different simulators.
       </p>
 
-      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness launch          <span class="dim"># extension — fullscreen by default</span>
-<span class="p">$ </span>mm-harness launch ios      <span class="dim"># mobile — target is mandatory</span>
-<span class="p">$ </span>mm-harness launch android</code></pre></div>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness launch --verify          <span class="dim"># extension — fullscreen by default</span>
+<span class="p">$ </span>xcrun simctl list devices available <span class="dim"># choose one iPhone UUID</span>
+<span class="p">$ </span>mm-harness provision runway ios --device '&lt;UUID&gt;' --force
+<span class="p">$ </span>xcrun simctl get_app_container '&lt;UUID&gt;' io.metamask.MetaMask app
+<span class="p">$ </span>mm-harness launch ios --device '&lt;UUID&gt;' --verify
+<span class="p">$ </span>mm-harness launch android --verify</code></pre></div>
 
       <p class="step-why">
         Quick relaunch is the default and reuses a healthy runtime. <code>--build</code> is the escape
@@ -290,7 +326,13 @@ capture: <span class="ok">pass</span> (screenshots: capture-helper → cdp; vide
         <div class="fail-body">
           <p>
             <strong>Mobile: more than one device</strong> — the harness lists what it found rather than
-            guessing. Re-run with <code>--device &lt;udid|serial|name&gt;</code>.
+            guessing. Re-run with <code>--device &lt;udid|serial&gt;</code>. Prefer the iOS UUID over a name,
+            because Xcode can contain several simulators with the same display name.
+          </p>
+          <p>
+            <strong>iOS app missing after provisioning</strong> — repeat the provision command with
+            <code>--force</code> and the same UUID. Do not use <code>--preflight-mode</code>; it is an
+            internal adapter flag, not a public <code>mm-harness launch</code> option.
           </p>
           <p>
             <strong>Stuck</strong> — <code>mm-harness logs</code> tails the dev server and app logs;
@@ -638,7 +680,7 @@ artifacts (6):
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+. If a command here disagrees with your terminal, your terminal is right: run <code>mm-harness update</code>, then trust <code>--help</code>.</p>
+    <p>Verified against mm-harness 0.33+. If a command here disagrees with your terminal, your terminal is right: run <code>mm-harness update</code>, then trust <code>--help</code>.</p>
   </div>
 </footer>
 

package/site/perps.html

@@ -0,0 +1,195 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Perps recipes — MetaMask recipe workflow</title>
+<meta name="description" content="Install the shared MetaMask Perps recipe library and run live, testnet-first proof across Extension, Mobile, and Core.">
+<link rel="stylesheet" href="assets/style.css">
+</head>
+<body>
+<a class="skip" href="#setup">Skip to setup</a>
+
+<header class="topbar">
+  <div class="wrap topbar-inner">
+    <a class="brand" href="index.html">
+      <span class="brand-mark" aria-hidden="true"></span>
+      <span class="brand-name">mm-harness</span>
+    </a>
+    <nav class="nav" aria-label="Main">
+      <a href="index.html">Start Here</a>
+      <a href="recipes.html">Recipes</a>
+      <a href="perps.html" aria-current="page">Perps</a>
+      <a href="cheatsheet.html">Cheatsheet</a>
+      <a href="architecture.html">Architecture</a>
+      <a href="tutorials/index.html">Tutorials</a>
+      <a href="reviewers.html">For Reviewers</a>
+    </nav>
+  </div>
+</header>
+
+<main>
+<section class="wrap hero" style="padding-bottom:1rem">
+  <span class="eyebrow">Shared MetaMask recipe library</span>
+  <h1>Prove Perps changes in the real product</h1>
+  <p class="lede">
+    The private Perps library gives Extension, Mobile, and Core one set of small, parameterized
+    recipes for live UI journeys, controller state, analytics, performance, and testnet mutations.
+  </p>
+  <div class="hero-meta">
+    <span>library name: perps</span>
+    <span>defaults to testnet</span>
+    <span>requires repository access</span>
+  </div>
+</section>
+
+<section class="wrap">
+  <div class="doctrine">
+    <p>
+      <span class="k">The harness supplies the execution standard; the Perps library supplies the domain proof.</span>
+      Keep the shared library small: compose or repair the closest recipe before creating another one.
+    </p>
+  </div>
+
+  <h2>What lives where</h2>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th>Layer</th><th>Owns</th><th>Does not own</th></tr></thead>
+      <tbody>
+        <tr>
+          <td><code>mm-harness</code></td>
+          <td>Launch, typed actions, graph execution, screenshots, video, traces, and artifact contracts.</td>
+          <td>Ticket-specific Perps scenarios.</td>
+        </tr>
+        <tr>
+          <td><code>perps</code> library</td>
+          <td>Reusable Perps setup, journeys, assertions, cleanup, and platform variants.</td>
+          <td>Wallet credentials, generated evidence, or product source.</td>
+        </tr>
+        <tr>
+          <td>Product checkout</td>
+          <td>The real Extension, Mobile, or Core code and runtime being proved.</td>
+          <td>A substitute test implementation.</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2 id="setup">Install and discover it</h2>
+  <p>
+    Run these commands from the MetaMask product checkout you want to exercise. The repository is
+    private; a clone failure means your GitHub account needs access.
+  </p>
+
+  <div class="cmd"><pre><code><span class="p">$ </span>npm i -g @deeeed/metamask-harness@latest
+<span class="p">$ </span>git clone git@github.com:MetaMask/experimental-metamask-recipe-perps.git \
+    "$HOME/shared-library/metamask-recipe-perps"
+<span class="p">$ </span>mm-harness run --list \
+    --library "perps=$HOME/shared-library/metamask-recipe-perps"</code></pre></div>
+
+  <p>
+    If the checkout already exists and is clean, update it with <code>git pull --ff-only</code>.
+    Preserve and report a dirty checkout instead of overwriting it. Keep <code>--library</code> on each
+    command so separate tool shells do not lose an exported variable.
+  </p>
+
+  <div class="note blue">
+    <span class="note-title">Discovery is adapter-aware</span>
+    <p>
+      The list shows only recipes runnable in the current product checkout. A recipe marked
+      <code>[perps]</code> came from the shared library; <code>[metamask]</code> means it ships with the
+      harness. Read the selected platform variant with <code>--describe</code> before running it.
+    </p>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2>Your first live proof</h2>
+  <p>
+    Complete <a href="index.html#steps">Start Here</a> first so the app, device, and wallet fixture are
+    ready. Then use a read-only recipe as the first proof.
+  </p>
+
+  <h3>Extension or Mobile</h3>
+  <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run perps.open-market --describe \
+    --library "perps=$HOME/shared-library/metamask-recipe-perps"
+<span class="p">$ </span>mm-harness run perps.open-market network=testnet market=BTC --plan \
+    --library "perps=$HOME/shared-library/metamask-recipe-perps"
+<span class="p">$ </span>mm-harness run perps.open-market network=testnet market=BTC \
+    --record-video=full-run --artifacts-dir ./perps-open-market-evidence \
+    --library "perps=$HOME/shared-library/metamask-recipe-perps"</code></pre></div>
+
+  <h3>Core</h3>
+  <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run perps.snapshot-market --describe \
+    --library "perps=$HOME/shared-library/metamask-recipe-perps"
+<span class="p">$ </span>mm-harness run perps.snapshot-market network=testnet market=BTC \
+    --artifacts-dir ./perps-market-evidence \
+    --library "perps=$HOME/shared-library/metamask-recipe-perps"</code></pre></div>
+
+  <p>
+    A passing run writes <code>summary.json</code>, per-node results in <code>trace.json</code>, and an
+    artifact manifest beside screenshots or video. Visual review surfaces can render those same
+    recipe-derived artifacts without changing the proof graph.
+  </p>
+</section>
+
+<section class="wrap">
+  <h2>Choose the recipe that owns the claim</h2>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th>Claim</th><th>Recipe</th><th>Platforms</th></tr></thead>
+      <tbody>
+        <tr><td>Reach a live market detail screen</td><td><code>perps.open-market</code></td><td>Mobile, Extension</td></tr>
+        <tr><td>Read positions and orders</td><td><code>perps.snapshot-market</code></td><td>Mobile, Extension, Core</td></tr>
+        <tr><td>Place, assert, and clean up an order</td><td><code>perps.prove-order</code></td><td>Mobile, Extension, Core</td></tr>
+        <tr><td>Manage or close a position</td><td><code>perps.manage-position</code></td><td>Mobile, Extension, Core</td></tr>
+        <tr><td>Prove real MetaMetrics emissions</td><td><code>perps.analytics-lifecycle</code></td><td>Mobile, Extension</td></tr>
+        <tr><td>Measure the open-market journey</td><td><code>perps.performance-open-market</code></td><td>Mobile, Extension</td></tr>
+        <tr><td>Exercise edit-order contracts</td><td><code>perps.prove-edit-order</code></td><td>Core</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <div class="note">
+    <span class="note-title">Mutation boundary</span>
+    <p>
+      Always run <code>--describe</code> and <code>--plan</code> before a state-changing recipe. The
+      library defaults to testnet and cleans up testnet state. Never turn an onboarding proof into a
+      mainnet mutation; mainnet operations require the recipe's explicit real-funds confirmation.
+    </p>
+  </div>
+</section>
+
+<section class="wrap">
+  <h2>Maintain the proof, not a pile of scenarios</h2>
+  <ol>
+    <li>Parameterize stable choices such as market, side, order type, and network.</li>
+    <li>Compose existing setup, assertion, and cleanup recipes before adding a new top-level recipe.</li>
+    <li>Add a platform variant only when the products genuinely differ.</li>
+    <li>
+      If a locator or screen assertion fails, classify it first. Intentional product change may mean
+      small recipe drift; otherwise preserve the failure and fix the product, runtime, or harness layer
+      that owns it.
+    </li>
+    <li>Re-run every caller after a shared node changes and attach the fresh evidence.</li>
+  </ol>
+
+  <div class="btn-row">
+    <a class="btn btn-primary" href="tutorials/v3.html">Install skills and the library →</a>
+    <a class="btn btn-ghost" href="recipes.html">How recipes prove claims</a>
+    <a class="btn btn-ghost" href="reviewers.html">How to review evidence</a>
+  </div>
+</section>
+</main>
+
+<footer class="footer">
+  <div class="wrap">
+    <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
+    <p>Verified against mm-harness 0.33+ and the shared MetaMask Perps recipe library.</p>
+  </div>
+</footer>
+<script type="module" src="assets/progress.mjs"></script>
+</body>
+</html>

package/site/recipes.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="index.html">Start Here</a>
       <a href="recipes.html" aria-current="page">Recipes</a>
+      <a href="perps.html">Perps</a>
       <a href="cheatsheet.html">Cheatsheet</a>
       <a href="architecture.html">Architecture</a>
       <a href="tutorials/index.html">Tutorials</a>
@@ -48,6 +49,27 @@
   </div>
 
   <p>Every clause there does a job against a specific failure mode. Here they are, one at a time.</p>
+
+  <h2 id="why">What it is for</h2>
+  <p>
+    <strong>Proof.</strong> Actions drive a real build and assertions check what should be true —
+    counted, where a count is what distinguishes working from nearly working. What lands is on-device
+    evidence, not a claim in a pull request description.
+  </p>
+  <p>
+    <strong>Self-checking, in the same context.</strong> The agent does not need a fresh session, a
+    reviewer, or a CI round-trip to know whether its change held. It replays the recipe mid-task, where
+    it is already working, and reads the verdict itself — the inner loop, closed before handoff.
+  </p>
+  <p>
+    <strong>Prevents regressions.</strong> The outer loop is the same recipe replayed against every
+    later change. Written once, it keeps refusing the bug it was written for, which is why a recipe is
+    worth authoring rather than checking by hand: the check survives the task.
+  </p>
+  <p>
+    <strong>Trust.</strong> Proven, self-checked, and still proving. Review reads evidence rather than
+    extending credit, and every gate stays yours to steer.
+  </p>
 </section>
 
 <section class="wrap">
@@ -387,7 +409,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+. The annotated recipe is a bundled library recipe, abridged.</p>
+    <p>Verified against mm-harness 0.33+. The annotated recipe is a bundled library recipe, abridged.</p>
   </div>
 </footer>
 

package/site/reviewers.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="index.html">Start Here</a>
       <a href="recipes.html">Recipes</a>
+      <a href="perps.html">Perps</a>
       <a href="cheatsheet.html">Cheatsheet</a>
       <a href="architecture.html">Architecture</a>
       <a href="tutorials/index.html">Tutorials</a>
@@ -365,7 +366,7 @@ Nodes: 6/6 passed
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+. Example bundle is a real run with identifying values redacted.</p>
+    <p>Verified against mm-harness 0.33+. Example bundle is a real run with identifying values redacted.</p>
   </div>
 </footer>
 

package/site/tutorials/index.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -171,7 +172,7 @@
 <footer class="footer">
   <div class="wrap-wide">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/tutorials/v1.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -103,7 +104,7 @@
       <p class="step-why">Install globally, confirm it resolved, then work from inside a product checkout.</p>
       <div class="cmd"><pre><code><span class="p">$ </span>npm i -g @deeeed/metamask-harness@latest
 <span class="p">$ </span>mm-harness --version</code></pre></div>
-      <div class="out">0.26.x  <span class="dim">— any 0.26 or newer</span></div>
+      <div class="out">0.33.x  <span class="dim">— any 0.33 or newer</span></div>
     </li>
 
     <li class="step" data-step="doctor">
@@ -202,7 +203,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/tutorials/v2.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -77,7 +78,7 @@
         <tr><td><code>0:40</code></td><td><code>recipe.json</code> — the graph that executed. Each node's <code>intent</code> is the argument being made.</td></tr>
         <tr><td><code>1:40</code></td><td><code>trace.json</code> — per-node verdicts, timings, outputs. Counts come from here.</td></tr>
         <tr><td><code>2:50</code></td><td><code>summary.json</code> — the verdict, the totals, which libraries were in scope.</td></tr>
-        <tr><td><code>3:30</code></td><td>Screenshots, and on Mobile the run video. Extension captures stills only.</td></tr>
+        <tr><td><code>3:30</code></td><td>Screenshots, plus full-run video on Extension and iOS.</td></tr>
         <tr><td><code>4:20</code></td><td><code>diagnostics.json</code> — application warnings, quarantined from the verdict.</td></tr>
         <tr><td><code>5:10</code></td><td>The two rules that make the whole thing worth reading.</td></tr>
       </tbody>
@@ -106,9 +107,9 @@
   <div class="note blue">
     <span class="note-title">Capture is not symmetric</span>
     <p>
-      Mobile records video of a full run; Extension captures screenshots only. Do not promise a reviewer
-      a video of an Extension run. <code>mm-harness doctor</code> reports what the current checkout can
-      capture on its <code>capture:</code> line.
+      Extension and iOS record full-run video through capture-helper; Android replay video is not
+      implemented yet. <code>mm-harness doctor</code> reports what the current checkout can capture on its
+      <code>capture:</code> line.
     </p>
   </div>
 </section>
@@ -198,7 +199,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/tutorials/v3.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -84,6 +85,46 @@
 <section class="wrap">
   <h2 id="steps">Set it up</h2>
 
+  <div class="agent-card">
+    <h3 style="margin-top:0">Paste this into your agent</h3>
+    <div class="cmd cmd-hero"><pre><code>Task: install the latest recipe skills and shared MetaMask Perps recipe library,
+then prove one real recipe runs end to end.
+
+1. Work from the MetaMask product checkout I started you in. Run
+   `npm i -g @deeeed/metamask-harness@latest` and `mm-harness --version`.
+2. Install the latest Consensys recipe skills into this checkout:
+   `yarn skills --maturity experimental --include
+   agentic/recipe-cook,agentic/recipe-quality --save`
+   This command updates the skills sources before syncing. Show me that
+   recipe-cook and recipe-quality were installed.
+3. Use this exact library directory:
+   `$HOME/shared-library/metamask-recipe-perps`.
+   If it does not exist, clone
+   `git@github.com:MetaMask/experimental-metamask-recipe-perps.git` there.
+   If it exists and is clean, update it with `git pull --ff-only`; if it is
+   dirty, preserve it and report that instead of changing its files.
+   If cloning reports 404 or permission denied, stop and tell me that repository
+   access is missing; do not search for a substitute repository.
+4. Run `mm-harness run --list --library
+   "perps=$HOME/shared-library/metamask-recipe-perps"` and show me the recipes
+   tagged `[perps]`. Use this explicit `--library` on every later command; do not
+   assume an `export` survives between tool shells.
+5. Run `mm-harness status`. If the app is not ready, follow its public `Next:`
+   command while preserving the same device UUID or serial used during setup.
+6. Choose only a recipe actually printed by step 4. Prefer
+   `perps.open-market` on Extension/Mobile or `perps.snapshot-market` on Core.
+   If that shared recipe has no variant for this checkout, use the listed bundled
+   `wallet.smoke` (Extension/Mobile) or `runner.smoke` (Core) recipe.
+7. Run the chosen recipe with `--describe`, then `--plan`, then for real with
+   `--artifacts-dir ./first-team-recipe-artifacts`. Include
+   `--library "perps=$HOME/shared-library/metamask-recipe-perps"` each time.
+   For a Perps recipe use `network=testnet market=BTC`. Never place an order or
+   use mainnet in this setup proof.
+8. Show me summary.json status, every trace.json node result, and all artifact
+   paths. Then confirm the checkout is ready for a bug-fix task using the
+   installed recipe-cook skill.</code></pre></div>
+  </div>
+
   <ol class="steps">
     <li class="step" data-step="skills">
       <div class="step-head">
@@ -91,7 +132,7 @@
         <h3 class="step-title" id="t3-skills">Install the skills into your checkout</h3>
       </div>
       <p class="step-why">Run this from the product checkout you work in.</p>
-      <div class="cmd"><pre><code><span class="p">$ </span>yarn skills --include agentic/recipe-cook,agentic/recipe-quality --save</code></pre></div>
+      <div class="cmd"><pre><code><span class="p">$ </span>yarn skills --maturity experimental --include agentic/recipe-cook,agentic/recipe-quality --save</code></pre></div>
       <p class="step-why">
         The agentic skills carry <code>experimental</code> maturity, so they are visible only when
         experimental skills are enabled. <code>recipe-cook</code> is the one you want first — it owns
@@ -205,7 +246,7 @@ Inspect: mm-harness run &lt;recipe&gt; --describe
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/tutorials/v4.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -186,7 +187,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/tutorials/v5.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -154,7 +155,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/tutorials/v6.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -156,7 +157,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>
 

package/site/tutorials/v7.html

@@ -19,6 +19,7 @@
     <nav class="nav" aria-label="Main">
       <a href="../index.html">Start Here</a>
       <a href="../recipes.html">Recipes</a>
+      <a href="../perps.html">Perps</a>
       <a href="../cheatsheet.html">Cheatsheet</a>
       <a href="../architecture.html">Architecture</a>
       <a href="index.html" aria-current="page">Tutorials</a>
@@ -175,7 +176,7 @@
 <footer class="footer">
   <div class="wrap">
     <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.26+.</p>
+    <p>Verified against mm-harness 0.33+.</p>
   </div>
 </footer>