npm - @deeeed/metamask-harness - Versions diffs - 0.28.0 → 0.29.0 - Mend

@deeeed/metamask-harness 0.28.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

package/CHANGELOG.md +19 -0
package/README.md +41 -0
package/adapters/extension/build-lavamoat.sh +2 -1
package/adapters/extension/ensure-browser.sh +82 -9
package/adapters/extension/inject.mjs +1 -0
package/adapters/extension/launch-browser.cjs +83 -1
package/adapters/extension/lib/chrome-args.cjs +325 -1
package/adapters/extension/lib/playwright-cdp.cjs +34 -0
package/adapters/extension/lib/slot-title.cjs +2 -4
package/adapters/extension/lib/validation-launch-supervisor.cjs +292 -0
package/adapters/extension/lib/validation-process-ownership.cjs +69 -0
package/adapters/extension/reattach.sh +2 -1
package/adapters/extension/sidepanel-toggle.sh +14 -96
package/adapters/extension/wallet-fixture-state.cjs +8 -31
package/adapters/manifest.json +16 -0
package/adapters/shared/private-atomic-write.cjs +47 -0
package/adapters/shared/setup-base.sh +864 -0
package/dist/adapters/extension/runtime.js +367 -24
package/dist/adapters/extension/validation-process-ownership.js +10 -0
package/dist/cli-commands.js +1 -0
package/dist/command-contract.js +12 -0
package/dist/commands/launch/extension.js +130 -19
package/dist/commands/setup-base.js +24 -0
package/dist/mm-harness-cli.js +28 -2
package/library/actions/extension/analytics/consent.mjs +203 -0
package/library/actions/extension/analytics/set_consent.mjs +19 -143
package/library/actions/extension/perps/perps.mjs +2 -16
package/library/actions/extension/perps/state.mjs +20 -0
package/library/actions/extension/wallet/list_accounts.mjs +3 -25
package/library/actions/extension/wallet/read_state.mjs +3 -23
package/library/actions/extension/wallet/select_account.mjs +6 -33
package/library/actions/extension/wallet/setup.mjs +2 -20
package/library/actions/extension/wallet/state.mjs +111 -0
package/library/recipes/runner/action-validation.extension.recipe.json +1 -1
package/library/recipes/runner/action-validation.mobile.recipe.json +1 -1
package/package.json +7 -4
package/scripts/site-contrast.mjs +538 -0
package/site/architecture.html +415 -0
package/site/assets/progress.mjs +272 -0
package/site/assets/style.css +808 -0
package/site/cheatsheet.html +305 -0
package/site/index.html +643 -0
package/site/recipes.html +396 -0
package/site/reviewers.html +374 -0
package/site/tutorials/index.html +180 -0
package/site/tutorials/v1.html +211 -0
package/site/tutorials/v2.html +207 -0
package/site/tutorials/v3.html +214 -0
package/site/tutorials/v4.html +195 -0
package/site/tutorials/v5.html +163 -0
package/site/tutorials/v6.html +165 -0
package/site/tutorials/v7.html +184 -0

package/site/index.html ADDED Viewed

@@ -0,0 +1,643 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Start Here — MetaMask agentic coding</title>
+<meta name="description" content="Drive a real MetaMask build from one CLI and leave evidence a reviewer can trust. An interactive walkthrough: discover, drive, prove.">
+<link rel="stylesheet" href="assets/style.css">
+</head>
+<body data-progress-page="start">
+<a class="skip" href="#steps">Skip to the walkthrough</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" aria-current="page">Start Here</a>
+      <a href="recipes.html">Recipes</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>
+<div class="progress-rail">
+  <div class="wrap progress-inner">
+    <div class="progress-track" role="progressbar" aria-label="Walkthrough progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0">
+      <div class="progress-fill"></div>
+    </div>
+    <span class="progress-label">0/8 steps</span>
+    <button type="button" class="progress-reset">Reset</button>
+  </div>
+</div>
+<main>
+<section class="wrap hero">
+  <span class="eyebrow">Agentic coding 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.
+  </p>
+  <div class="hero-meta">
+    <span>requires mm-harness 0.26+</span>
+    <span>~20 minutes</span>
+    <span>progress saves in this browser</span>
+  </div>
+</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 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.
+  </p>
+  <div class="doctrine">
+    <p>
+      <span class="k">You never guess capabilities — you discover them.</span>
+      <code>mm-harness actions</code> prints what this checkout can do, and that list is law. The tool
+      refuses an invented action rather than improvising one, which is why its output is worth
+      trusting.
+    </p>
+  </div>
+</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>
+  <ol class="steps">
+    <li class="step" data-step="install">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-install" aria-labelledby="t-install">
+        <h3 class="step-title" id="t-install">Get the CLI</h3>
+      </div>
+      <p class="step-why">Both paths end with <code>mm-harness</code> on your PATH.</p>
+      <div class="grid grid-2" style="margin:1.2rem 0">
+        <div class="path-card">
+          <div class="path-tag">Path A — from zero</div>
+          <h4 style="margin:0 0 .5rem">No checkout yet</h4>
+          <p style="font-size:.92rem;color:var(--text-dim)">
+            A one-shot bootstrap command is being prepared but is <strong>not published yet</strong> —
+            it is not on the npm package, so do not paste it from elsewhere expecting it to resolve.
+            Until it ships, use the install below and clone <em>one</em> product repo yourself.
+          </p>
+          <p style="margin-bottom:0"><span class="badge soon">bootstrap: shipping soon</span></p>
+        </div>
+        <div class="path-card">
+          <div class="path-tag">Path B — you already have a checkout</div>
+          <h4 style="margin:0 0 .5rem">Install and cd in</h4>
+          <p style="font-size:.92rem;color:var(--text-dim)">
+            Install globally, then work from inside the checkout. The product, ports, and runtime paths
+            are detected from where you are standing; there is no config file to write.
+          </p>
+          <p style="margin-bottom:0"><span class="badge live">available now</span></p>
+        </div>
+      </div>
+      <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-label">Expected</div>
+      <div class="out">0.26.x  <span class="dim">— any 0.26 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>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p>
+            <strong><code>mm-harness: command not found</code></strong> — your global npm bin is not on
+            PATH. <code>npm prefix -g</code> prints the global prefix; add its <code>bin</code>
+            directory to your shell profile.
+          </p>
+          <p>
+            <strong>Older than 0.26</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>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="doctor">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-doctor" aria-labelledby="t-doctor">
+        <h3 class="step-title" id="t-doctor">Run doctor — and learn to read the errors</h3>
+      </div>
+      <p class="step-why">
+        A read-only readiness check that launches nothing and names the exact command that fixes each
+        finding.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness doctor</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
+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)
+capture: <span class="ok">pass</span> (screenshots: capture-helper → cdp; video: capture-helper)
+  <span class="hint">Next: mm-harness launch --adapter extension --target '…'</span></div>
+      <div class="note">
+        <span class="note-title">The habit the toolchain is built around</span>
+        <p>
+          Every failure names one next action. Above, the finding tells you to run
+          <code>doctor --fix</code> and the <code>Next:</code> line says where to go once it passes.
+          Read the message and do what it says — that is also what lets an agent recover on its own
+          instead of guessing.
+        </p>
+      </div>
+      <p class="step-why">Do what it said:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness doctor --fix</code></pre></div>
+      <div class="out-label">Expected — the finding is gone</div>
+      <div class="out"><span class="ok">pass</span> extension bridge present ready=true <span class="ok">fixed=[runtime-context]</span> failed=[]</div>
+      <p class="step-why">
+        <code>--fix</code> repairs runtime state the harness owns. It will not launch the app, invent
+        credentials, or pick a wallet fixture; those are your decisions, so it stops and asks.
+      </p>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p>
+            <strong><code>deps=missing</code></strong> — run <code>yarn install</code> as usual for
+            that repo. The harness does not manage your product repo's dependencies.
+          </p>
+          <p>
+            <strong>A finding you do not understand</strong> — <code>mm-harness doctor --json</code>
+            carries the same findings with structured detail, and is the form to paste to an agent or a
+            bug report.
+          </p>
+          <p>
+            <strong>Still failing after <code>--fix</code></strong> — <code>fixed=[…] failed=[…]</code>
+            separates the two. Anything in <code>failed</code> needs a human decision; the finding says
+            which.
+          </p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="launch">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-launch" aria-labelledby="t-launch">
+        <h3 class="step-title" id="t-launch">Launch the app under harness control</h3>
+      </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.
+      </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>
+      <p class="step-why">
+        Quick relaunch is the default and reuses a healthy runtime. <code>--build</code> is the escape
+        hatch that always clean-builds; reach for it only when native or bundler output changed.
+      </p>
+      <div class="out-label">Core is headless — and says so</div>
+      <div class="out"><span class="bad">✗</span> mm-harness launch: core is headless; there is nothing to launch.
+  <span class="hint">Next: mm-harness verify</span></div>
+      <p class="step-why">
+        In <code>core</code> there is no UI to launch, so you get the equivalent step instead of a
+        silent failure. Run <code>mm-harness verify</code> and continue.
+      </p>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <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>.
+          </p>
+          <p>
+            <strong>Stuck</strong> — <code>mm-harness logs</code> tails the dev server and app logs;
+            <code>mm-harness status</code> shows the adapter, devices, and next command.
+          </p>
+          <p>
+            <strong>Clean slate</strong> — <code>mm-harness stop</code> stops only what this checkout
+            owns, so parallel checkouts are untouched. Stopping nothing is success.
+          </p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="actions">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-actions" aria-labelledby="t-actions">
+        <h3 class="step-title" id="t-actions">Discover what this checkout can do</h3>
+      </div>
+      <p class="step-why">
+        Prints every typed operation available here, with its fields. The set differs per product:
+        Mobile has UI actions, Core is headless and has none.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness actions --categories</code></pre></div>
+      <div class="out-label">Expected — a mobile checkout</div>
+      <div class="out">analytics (4)
+assertion (4)
+control (4)
+evidence (2)
+perps (11)
+runtime (4)
+ui (7)
+utility (1)
+wallet (6)</div>
+      <p class="step-why">Then look inside a category, search, or inspect one action's fields:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness actions --category ui
+<span class="p">$ </span>mm-harness actions positions
+<span class="p">$ </span>mm-harness actions --action read_state</code></pre></div>
+      <div class="doctrine">
+        <p>
+          <span class="k">The discovered list is law.</span> It is the capability boundary, not a
+          subset of some larger API. Call something not on it and the harness refuses, pointing you back
+          at discovery:
+        </p>
+      </div>
+      <div class="out"><span class="bad">✗</span> call: unknown action "totally_made_up" for the extension adapter.
+  <span class="hint">Next: mm-harness actions --adapter extension --json</span></div>
+      <p class="step-why">
+        That refusal is why the evidence is worth reading: a tool that invents an action when asked for
+        something impossible would also produce a plausible-looking result, and you would have no way to
+        tell. Add <code>--json</code> when feeding this to an agent.
+      </p>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p>
+            <strong>Fewer actions than expected</strong> — you are seeing only the bundled set. Team
+            libraries add domain actions and must be declared: <a href="tutorials/v3.html">V3</a>.
+          </p>
+          <p>
+            <strong>Wrong product detected</strong> — pass <code>--adapter mobile|extension|core</code>
+            explicitly, and check you are inside the checkout you meant.
+          </p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="call-read">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-call-read" aria-labelledby="t-call-read">
+        <h3 class="step-title" id="t-call-read">Drive it: read product state</h3>
+      </div>
+      <p class="step-why">
+        <code>call</code> runs one action as a one-node recipe through the real engine — same execution
+        path, trace, and evidence as a full run. Start with a read; reads cannot break anything.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness call read_state</code></pre></div>
+      <div class="note blue">
+        <span class="note-title">Core branch</span>
+        <p>
+          Core has no wallet UI. Exercise its live controller boundary instead:
+          <code>mm-harness call read_positions mode=all</code>.
+        </p>
+      </div>
+      <p class="step-why">
+        Short names resolve when unambiguous: <code>read_state</code> finds
+        <code>metamask.wallet.read_state</code>. An ambiguous one stops and lists the candidates.
+      </p>
+      <div class="out-label">Expected — shape of the result</div>
+      <div class="out">call read_state: <span class="ok">pass</span>
+Result:
+{
+  "action": "metamask.wallet.read_state",
+  "state": {
+    "selectedAccount": { "name": "Account 1", "address": "0x…" },
+    "completedOnboarding": true
+  },
+  "redacted": true
+}</div>
+      <p class="step-why">
+        Note <code>"redacted": true</code> — wallet state passes through redaction before reaching an
+        artifact, because these bundles get attached to pull requests.
+      </p>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p>
+            <strong>Runtime health check failed / CDP not reachable</strong> — the app is not running.
+            Complete the launch step; <code>mm-harness status</code> confirms what is live.
+          </p>
+          <p>
+            <strong>Mobile: more than one device</strong> — <code>call</code> fails fast and lists
+            them. Re-run with <code>--device</code>.
+          </p>
+          <p>
+            <strong><code>unknown action</code></strong> — not in this adapter's set.
+            <code>mm-harness call --list</code> shows what <code>call</code> accepts here.
+          </p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="call-ui">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-call-ui" aria-labelledby="t-call-ui">
+        <h3 class="step-title" id="t-call-ui">Drive it again: UI or headless Core</h3>
+      </div>
+      <p class="step-why">Keep the app visible for this one.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness call navigate page=perps</code></pre></div>
+      <div class="note blue">
+        <span class="note-title">Core branch</span>
+        <p>
+          Prove a second headless action instead:
+          <code>mm-harness call command cmd="echo core-ready"</code>.
+        </p>
+      </div>
+      <p class="step-why">
+        Fields are passed as <code>key=value</code>, or <code>--arg k=v</code> for the same effect.
+      </p>
+      <div class="note blue">
+        <span class="note-title">Semantic intent, not coordinates</span>
+        <p>
+          You asked for a <em>page</em>, not a pixel or a route. The adapter owns the mapping and
+          verifies where it landed, so a drifted route fails loudly instead of quietly doing nothing —
+          which is why these actions survive redesigns.
+          <code>mm-harness actions --action navigate</code> lists accepted values.
+        </p>
+      </div>
+      <p class="step-why">Others worth trying, if your adapter lists them:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness call press text="Account 1"
+<span class="p">$ </span>mm-harness call screenshot path=proof.png</code></pre></div>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p>
+            <strong>Target not found</strong> — the element is not on screen. Actions do not hunt
+            blindly; use <code>wait_for</code> when something needs to mount first.
+          </p>
+          <p>
+            <strong>Core has no UI actions</strong> — correct, it is headless. Try
+            <code>mm-harness call command cmd="echo hello"</code> there instead.
+          </p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="run">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-run" aria-labelledby="t-run">
+        <h3 class="step-title" id="t-run">Prove it: run your first recipe</h3>
+      </div>
+      <p class="step-why">
+        Everything so far was driving by hand. A recipe composes the same operations into a graph that
+        runs identically every time and records what happened. Start with what ships:
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run --list</code></pre></div>
+      <div class="out-label">Expected — an extension checkout</div>
+      <div class="out">runnable recipes (extension)
+Inspect: mm-harness run &lt;recipe&gt; --describe
+  perps.smoke        [metamask] variant=extension — Non-mutating Perps domain smoke…
+  runner.smoke       [metamask] variant=extension — Proves the runner executes manifest-declared actions…
+  wallet.smoke       [metamask] variant=extension — Fixture-backed proof that the wallet is reachable, unlocked…</div>
+      <p class="step-why">
+        Read one first. <code>--describe</code> shows its parameters and every action it composes:
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run wallet.smoke --describe
+<span class="p">$ </span>mm-harness run wallet.smoke --plan</code></pre></div>
+      <p class="step-why">
+        <code>--plan</code> validates and prints the execution plan while touching nothing, exiting 5 if
+        the recipe is invalid. Cheap check before the expensive one.
+      </p>
+      <p class="step-why">Now for real, with the evidence somewhere you chose:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run wallet.smoke --artifacts-dir ./first-recipe-artifacts</code></pre></div>
+      <div class="out-label">Expected</div>
+      <div class="out"><span class="ok">PASS</span> recipe run [extension]
+summary:
+  <span class="ok">PASS</span> status (app.status, 9ms): platform=extension
+  <span class="ok">PASS</span> fixture (metamask.wallet.fixture_status, 17ms): path=temp/recipe/runtime/wallet-fixture.json
+  <span class="ok">PASS</span> unlock (metamask.wallet.ensure_unlocked, 100ms): proof=extension-unlocked-state
+  <span class="ok">PASS</span> state (metamask.wallet.read_state, 94ms): proof=extension-wallet-state
+  <span class="ok">PASS</span> screenshot (ui.screenshot, 6.0s): path=screenshots/wallet-smoke.png
+  <span class="ok">PASS</span> done (end, 0ms)
+artifacts (6):
+  Human run report:  ./first-recipe-artifacts/report.md
+  Run summary:       ./first-recipe-artifacts/summary.json
+  Execution trace:   ./first-recipe-artifacts/trace.json
+  Executed recipe:   ./first-recipe-artifacts/recipe.json
+  <span class="dim">…</span></div>
+      <div class="note">
+        <span class="note-title">Wallet fixtures</span>
+        <p>
+          Recipes needing a signed-in wallet read one canonical fixture per checkout; the password comes
+          <em>from</em> the fixture and is never typed. On a missing fixture,
+          <code>mm-harness fixtures</code> shows its status and the safe next command.
+          <code>fixtures init --dev</code> creates a disposable public test wallet that must never hold
+          real funds.
+        </p>
+      </div>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p>
+            <strong>Exit 5</strong> — validation or trust failure. The recipe is the problem, not your
+            environment; nothing executed. The message names the invalid part.
+          </p>
+          <p>
+            <strong>Exit 1</strong> — it ran and an action failed. A real result, not a tooling
+            problem: find the first node in <code>trace.json</code> with <code>"ok": false</code>.
+          </p>
+          <p>
+            <strong>Exit 3</strong> — infrastructure, not your recipe: the app or dev server fell over.
+            Try <code>mm-harness doctor</code> then <code>mm-harness logs</code>.
+          </p>
+          <p>
+            <strong>Lost track</strong> — <code>mm-harness last</code> prints the last significant
+            command with its verdict and evidence paths.
+          </p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="evidence">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="c-evidence" aria-labelledby="t-evidence">
+        <h3 class="step-title" id="t-evidence">Open the evidence bundle</h3>
+      </div>
+      <p class="step-why">The run left a directory behind. This is the part that beats clicking through by hand.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>ls first-recipe-artifacts
+<span class="p">$ </span>cat first-recipe-artifacts/summary.json
+<span class="p">$ </span>open first-recipe-artifacts/screenshots</code></pre></div>
+      <div class="table-scroll">
+        <table>
+          <thead><tr><th>File</th><th>What it answers</th></tr></thead>
+          <tbody>
+            <tr><td><code>summary.json</code></td><td>Did it pass? How many nodes, how long, which libraries were in play. The verdict.</td></tr>
+            <tr><td><code>trace.json</code></td><td>What happened at every step: per-node verdict, timing, inputs, outputs. Counts come from here.</td></tr>
+            <tr><td><code>recipe.json</code></td><td>The graph that actually executed, including each node's stated intent.</td></tr>
+            <tr><td><code>report.md</code></td><td>The same story in one readable page — the thing to skim first.</td></tr>
+            <tr><td><code>screenshots/</code></td><td>Visual evidence captured during the run.</td></tr>
+            <tr><td><code>diagnostics.json</code></td><td>Warnings and errors the app emitted, kept deliberately separate from the verdict.</td></tr>
+          </tbody>
+        </table>
+      </div>
+      <p class="step-why">
+        Read them in that order: <code>report.md</code>, then <code>summary.json</code> for the verdict,
+        then <code>trace.json</code> when you want to know why. Cite numbers from
+        <code>trace.json</code>, never from prose written around it.
+      </p>
+      <div class="btn-row" style="margin-top:1.2rem">
+        <a class="btn btn-primary" href="reviewers.html">Read a bundle line by line →</a>
+      </div>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p>
+            <strong>Cannot find the directory</strong> — without <code>--artifacts-dir</code> it goes
+            to a checkout-local run directory. <code>mm-harness last</code> prints the path.
+          </p>
+          <p>
+            <strong>No screenshots</strong> — capture differs per platform;
+            <code>mm-harness doctor</code> reports it on a <code>capture:</code> line. A degraded
+            fallback still succeeds and records that it degraded in the artifact metadata.
+          </p>
+        </div>
+      </details>
+    </li>
+  </ol>
+</section>
+<section class="wrap">
+  <hr class="sep">
+  <h2>Next</h2>
+  <div class="grid grid-3">
+    <div class="card">
+      <h3>What a recipe is</h3>
+      <p>The graph, the intents, the assertions, and the test of whether yours is worth keeping.</p>
+      <p><a href="recipes.html">Recipes →</a></p>
+    </div>
+    <div class="card">
+      <h3>Your team's library</h3>
+      <p>Install the skills, declare your library, prove discovery sees it.</p>
+      <p><a href="tutorials/v3.html">Tutorial V3 →</a></p>
+    </div>
+    <div class="card">
+      <h3>Reviewing someone's proof</h3>
+      <p>A real bundle annotated, including a degraded capture that stayed honest about it.</p>
+      <p><a href="reviewers.html">For reviewers →</a></p>
+    </div>
+  </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.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>
+  </div>
+</footer>
+<script type="module" src="assets/progress.mjs"></script>
+</body>
+</html>