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/tutorials/v1.html ADDED Viewed

@@ -0,0 +1,211 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>V1 — Getting started with recipes</title>
+<meta name="description" content="Video one of the series: one CLI drives the wallet and proves what happened. With the same checklist as Start Here.">
+<link rel="stylesheet" href="../assets/style.css">
+</head>
+<body data-progress-page="start">
+<a class="skip" href="#steps">Skip to the checklist</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="../cheatsheet.html">Cheatsheet</a>
+      <a href="../architecture.html">Architecture</a>
+      <a href="index.html" aria-current="page">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" style="padding-bottom:1rem">
+  <span class="eyebrow">Tutorial V1 · 5 minutes</span>
+  <h1>Getting started with recipes</h1>
+  <p class="lede">
+    The promise in one sentence: one command-line tool drives a real MetaMask build, and then proves
+    what it did. This is the first video in the series and the shortest path into everything else.
+  </p>
+  <div class="hero-meta">
+    <span>no prerequisites</span>
+    <span>checklist shared with Start Here</span>
+  </div>
+</section>
+<section class="wrap">
+  <div class="vid-thumb" style="border-radius:var(--radius);border:1px solid var(--line);margin-bottom:1.5rem">
+    <div style="text-align:center;padding:1rem">
+      <div class="vid-id" style="font-size:2.6rem">V1</div>
+      <p style="color:var(--text-dim);margin:.5rem 0 0;font-size:.92rem">Video recording in progress</p>
+    </div>
+  </div>
+  <div class="note plain">
+    <span class="note-title">The checklist below is the video</span>
+    <p>
+      Same eight steps, same commands, same expected output — it is genuinely useful before the
+      recording exists, which is why it is here rather than a "coming soon" page. Your progress is
+      shared with <a href="../index.html">Start Here</a>: tick a step in either place and it is ticked
+      in both. Start Here carries the longer explanations and the full "if it fails" notes for each
+      step.
+    </p>
+  </div>
+  <h2>What the video covers</h2>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th>Beat</th><th>What is on screen</th></tr></thead>
+      <tbody>
+        <tr><td><code>0:00</code></td><td>The promise — one CLI drives the wallet and proves what happened.</td></tr>
+        <tr><td><code>0:30</code></td><td>Install into a clean checkout, then <code>doctor</code>. One failure gets fixed by following the error's own instruction — twenty seconds, no dwelling.</td></tr>
+        <tr><td><code>1:15</code></td><td><code>launch</code> — the real app comes up under harness control.</td></tr>
+        <tr><td><code>1:45</code></td><td><code>actions</code>, and the line that matters: you never guess capabilities, you discover them. Then two live <code>call</code>s — read the wallet state, then one UI action visibly moving the app.</td></tr>
+        <tr><td><code>3:00</code></td><td>The same steps as a <em>recipe</em>: <code>run</code> executes the graph and adds assertions. This is the jump from driving to proving.</td></tr>
+        <tr><td><code>4:00</code></td><td>Open the artifacts directory. <code>summary.json</code>, the trace, the screenshot.</td></tr>
+        <tr><td><code>4:30</code></td><td>Close on the cheatsheet — everything just done, on one page.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <p style="font-size:.94rem;color:var(--text-dim)">
+    Artifact you finish with: a green <code>summary.json</code> you produced yourself.
+  </p>
+</section>
+<section class="wrap">
+  <h2 id="steps">Follow along</h2>
+  <ol class="steps">
+    <li class="step" data-step="install">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-install" aria-labelledby="tv-install">
+        <h3 class="step-title" id="tv-install">Get the CLI</h3>
+      </div>
+      <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>
+    </li>
+    <li class="step" data-step="doctor">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-doctor" aria-labelledby="tv-doctor">
+        <h3 class="step-title" id="tv-doctor">Run doctor, follow what it tells you</h3>
+      </div>
+      <p class="step-why">
+        Read-only readiness check. Each finding names the exact command that fixes it — including,
+        often, <code>doctor --fix</code> itself.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness doctor
+<span class="p">$ </span>mm-harness doctor --fix</code></pre></div>
+      <div class="out"><span class="ok">pass</span> extension bridge present ready=true <span class="ok">fixed=[runtime-context]</span> failed=[]</div>
+    </li>
+    <li class="step" data-step="launch">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-launch" aria-labelledby="tv-launch">
+        <h3 class="step-title" id="tv-launch">Launch the app</h3>
+      </div>
+      <p class="step-why">Platform auto-detects. Mobile needs an explicit target; core is headless and says so.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness launch          <span class="dim"># extension</span>
+<span class="p">$ </span>mm-harness launch ios      <span class="dim"># mobile</span></code></pre></div>
+    </li>
+    <li class="step" data-step="actions">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-actions" aria-labelledby="tv-actions">
+        <h3 class="step-title" id="tv-actions">Discover the vocabulary</h3>
+      </div>
+      <p class="step-why">
+        The line to remember: you never guess capabilities, you discover them. This list is the
+        capability boundary, not a sample of one.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness actions --categories
+<span class="p">$ </span>mm-harness actions --category ui</code></pre></div>
+    </li>
+    <li class="step" data-step="call-read">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-call-read" aria-labelledby="tv-call-read">
+        <h3 class="step-title" id="tv-call-read">Drive it: read wallet state</h3>
+      </div>
+      <p class="step-why">One action through the real engine path. Reads first — they cannot break anything.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness call read_state</code></pre></div>
+    </li>
+    <li class="step" data-step="call-ui">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-call-ui" aria-labelledby="tv-call-ui">
+        <h3 class="step-title" id="tv-call-ui">Drive it: move the UI</h3>
+      </div>
+      <p class="step-why">Keep the app on screen. This is the beat where a terminal command visibly moves a real build.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness call navigate page=perps</code></pre></div>
+    </li>
+    <li class="step" data-step="run">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-run" aria-labelledby="tv-run">
+        <h3 class="step-title" id="tv-run">Prove it: run a recipe</h3>
+      </div>
+      <p class="step-why">
+        The same operations composed into a graph with assertions. <code>--plan</code> validates first
+        without touching anything.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run --list
+<span class="p">$ </span>mm-harness run wallet.smoke --plan
+<span class="p">$ </span>mm-harness run wallet.smoke --artifacts-dir ./first-recipe-artifacts</code></pre></div>
+    </li>
+    <li class="step" data-step="evidence">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v-evidence" aria-labelledby="tv-evidence">
+        <h3 class="step-title" id="tv-evidence">Open the evidence</h3>
+      </div>
+      <p class="step-why">
+        The closing shot of the video, and the reason for all of it. Start with <code>report.md</code>,
+        then the summary, then the trace when you want to know why.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>cat first-recipe-artifacts/report.md
+<span class="p">$ </span>cat first-recipe-artifacts/summary.json</code></pre></div>
+    </li>
+  </ol>
+  <hr class="sep">
+  <div class="btn-row">
+    <a class="btn btn-primary" href="../index.html#steps">Full walkthrough, with failure notes →</a>
+    <a class="btn btn-ghost" href="../cheatsheet.html">The cheatsheet</a>
+    <a class="btn btn-ghost" href="index.html">Back to the series</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.26+.</p>
+  </div>
+</footer>
+<script type="module" src="../assets/progress.mjs"></script>
+</body>
+</html>

package/site/tutorials/v2.html ADDED Viewed

@@ -0,0 +1,207 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>V2 — Reading the evidence</title>
+<meta name="description" content="Walk one finished run file by file, and learn the two rules that make a green verdict worth believing.">
+<link rel="stylesheet" href="../assets/style.css">
+</head>
+<body data-progress-page="v2">
+<a class="skip" href="#steps">Skip to the checklist</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="../cheatsheet.html">Cheatsheet</a>
+      <a href="../architecture.html">Architecture</a>
+      <a href="index.html" aria-current="page">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="Tutorial progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0">
+      <div class="progress-fill"></div>
+    </div>
+    <span class="progress-label">0/5 steps</span>
+    <button type="button" class="progress-reset">Reset</button>
+  </div>
+</div>
+<main>
+<section class="wrap hero" style="padding-bottom:1rem">
+  <span class="eyebrow">Tutorial V2 · 6 minutes</span>
+  <h1>Reading the evidence</h1>
+  <p class="lede">
+    For reviewers and sceptics. A green run is a claim; this is how you check it.
+  </p>
+  <div class="hero-meta">
+    <span>no prerequisites</span>
+    <span>reference: <a href="../reviewers.html">For Reviewers</a></span>
+  </div>
+</section>
+<section class="wrap">
+  <div class="vid-thumb" style="border-radius:var(--radius);border:1px solid var(--line);margin-bottom:1.5rem">
+    <div style="text-align:center;padding:1rem">
+      <div class="vid-id" style="font-size:2.6rem">V2</div>
+      <p style="color:var(--text-dim);margin:.5rem 0 0;font-size:.92rem">Video recording in progress</p>
+    </div>
+  </div>
+  <div class="note plain">
+    <span class="note-title">This page and the reviewer's guide</span>
+    <p>
+      This is the tour: what each file is for, in the order you open them.
+      <a href="../reviewers.html">For Reviewers</a> is the reference — a real bundle annotated line by line,
+      including a screenshot that passed while recording that its capture had degraded. Read this first,
+      keep that one open during a review.
+    </p>
+  </div>
+  <h2>What the video covers</h2>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th>Beat</th><th>On screen</th></tr></thead>
+      <tbody>
+        <tr><td><code>0:00</code></td><td>One finished run directory, opened cold.</td></tr>
+        <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>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>
+    </table>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="rules">The two rules</h2>
+  <p>Both are enforced in code, not by convention.</p>
+  <div class="doctrine">
+    <p>
+      <span class="k">Placeholders are refused, and a missing adapter throws.</span> The harness will not
+      accept a static stand-in where a real observation belongs, and when the adapter that would perform
+      an action is absent it raises instead of returning a plausible-looking object. A system that
+      guessed would produce evidence indistinguishable from the real thing.
+    </p>
+  </div>
+  <p>
+    The practical consequence: a node that passed had a real adapter execute it. That is what makes
+    <code>"ok": true</code> worth anything.
+  </p>
+  <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.
+    </p>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="steps">Follow along</h2>
+  <p>Use a bundle you produced in <a href="../index.html#steps">Start Here</a>, or any run directory.</p>
+  <ol class="steps">
+    <li class="step" data-step="open">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v2-open" aria-labelledby="t2-open">
+        <h3 class="step-title" id="t2-open">Open a bundle</h3>
+      </div>
+      <p class="step-why"><code>last</code> prints the path of the most recent run for this checkout.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness last
+<span class="p">$ </span>ls first-recipe-artifacts</code></pre></div>
+    </li>
+    <li class="step" data-step="report">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v2-report" aria-labelledby="t2-report">
+        <h3 class="step-title" id="t2-report">Skim report.md</h3>
+      </div>
+      <p class="step-why">The whole run on one page. If it disagrees with the pull request description, stop and ask.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>cat first-recipe-artifacts/report.md</code></pre></div>
+    </li>
+    <li class="step" data-step="verdict">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v2-verdict" aria-labelledby="t2-verdict">
+        <h3 class="step-title" id="t2-verdict">Check the verdict and the counts</h3>
+      </div>
+      <p class="step-why">Compare <code>total</code> against what the author claims was proven.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>cat first-recipe-artifacts/summary.json</code></pre></div>
+      <div class="out">{
+  "status": <span class="ok">"pass"</span>,
+  "total": 6,
+  "passed": 6,
+  "failed": 0
+}</div>
+    </li>
+    <li class="step" data-step="trace">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v2-trace" aria-labelledby="t2-trace">
+        <h3 class="step-title" id="t2-trace">Read the intents in order</h3>
+      </div>
+      <p class="step-why">
+        The per-node intents are the argument. If they do not add up to the claim, the bundle does not
+        support it — however green it is.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>cat first-recipe-artifacts/trace.json</code></pre></div>
+      <p class="step-why">
+        Triaging a failure: find the first node with <code>"ok": false</code>. Everything after it is
+        consequence.
+      </p>
+    </li>
+    <li class="step" data-step="artifacts">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v2-artifacts" aria-labelledby="t2-artifacts">
+        <h3 class="step-title" id="t2-artifacts">Open the images, then the diagnostics</h3>
+      </div>
+      <p class="step-why">
+        The trace says a PNG was registered and how it was captured. Only your eyes confirm it shows what
+        the author says.
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>open first-recipe-artifacts/screenshots
+<span class="p">$ </span>cat first-recipe-artifacts/diagnostics.json</code></pre></div>
+      <p class="step-why">
+        <code>diagnostics.json</code> is bracketed to the run window, so <code>"status": "clean"</code>
+        is a claim about this run rather than about the log file.
+      </p>
+    </li>
+  </ol>
+  <hr class="sep">
+  <div class="btn-row">
+    <a class="btn btn-primary" href="../reviewers.html">The annotated reference →</a>
+    <a class="btn btn-ghost" href="v3.html">Next: skills setup</a>
+    <a class="btn btn-ghost" href="index.html">Back to the series</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.26+.</p>
+  </div>
+</footer>
+<script type="module" src="../assets/progress.mjs"></script>
+</body>
+</html>

package/site/tutorials/v3.html ADDED Viewed

@@ -0,0 +1,214 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>V3 — Skills and your team's library</title>
+<meta name="description" content="Install the agentic skills into a checkout and declare your team's recipe library, with the perps library as the worked example.">
+<link rel="stylesheet" href="../assets/style.css">
+</head>
+<body data-progress-page="v3">
+<a class="skip" href="#steps">Skip to the checklist</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="../cheatsheet.html">Cheatsheet</a>
+      <a href="../architecture.html">Architecture</a>
+      <a href="index.html" aria-current="page">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="Tutorial progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0">
+      <div class="progress-fill"></div>
+    </div>
+    <span class="progress-label">0/5 steps</span>
+    <button type="button" class="progress-reset">Reset</button>
+  </div>
+</div>
+<main>
+<section class="wrap hero" style="padding-bottom:1rem">
+  <span class="eyebrow">Tutorial V3 · 5 minutes</span>
+  <h1>Skills and your team's library</h1>
+  <p class="lede">
+    Two things turn a bare harness into your team's setup: skills that carry the workflow, and a library
+    that carries the recipes. Both install into a checkout.
+  </p>
+  <div class="hero-meta">
+    <span>prerequisite: <a href="../index.html#steps">Start Here</a></span>
+    <span>worked example: the perps library</span>
+  </div>
+</section>
+<section class="wrap">
+  <div class="vid-thumb" style="border-radius:var(--radius);border:1px solid var(--line);margin-bottom:1.5rem">
+    <div style="text-align:center;padding:1rem">
+      <div class="vid-id" style="font-size:2.6rem">V3</div>
+      <p style="color:var(--text-dim);margin:.5rem 0 0;font-size:.92rem">Video recording in progress</p>
+    </div>
+  </div>
+  <h2>Skills versus libraries</h2>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th></th><th>Skills</th><th>Recipe library</th></tr></thead>
+      <tbody>
+        <tr><td>Carry</td><td>The workflow an agent follows.</td><td>Recipes and domain actions.</td></tr>
+        <tr><td>Live in</td><td><code>Consensys/skills</code>, installed per checkout.</td><td>A team repo, declared by path.</td></tr>
+        <tr><td>Needed to run a recipe</td><td>No.</td><td>Yes, for your team's recipes.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="note blue">
+    <span class="note-title">Layering</span>
+    <p>
+      Personal beats domain beats default, for skills and libraries alike. Your own overrides your team's,
+      which overrides what ships. A library that shadows another is reported in the run summary's
+      <code>shadowed</code> list rather than silently winning.
+    </p>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="steps">Set it up</h2>
+  <ol class="steps">
+    <li class="step" data-step="skills">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v3-skills" aria-labelledby="t3-skills">
+        <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>
+      <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
+        the authoring and review flows covered in <a href="v4.html">V4</a>.
+      </p>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p><strong>No <code>skills</code> script</strong> — not every repo has the tooling wired yet. Check the skills repo for the current install path for your checkout.</p>
+          <p><strong>The skill does not appear</strong> — confirm experimental maturity is enabled; that is the usual cause.</p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="clone">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v3-clone" aria-labelledby="t3-clone">
+        <h3 class="step-title" id="t3-clone">Clone your team's library</h3>
+      </div>
+      <p class="step-why">The perps library, as the worked example:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>git clone git@github.com:MetaMask/experimental-metamask-recipe-perps.git \
+    "$HOME/shared-library/metamask-recipe-perps"</code></pre></div>
+      <div class="note">
+        <span class="note-title">A 404 means access, not a typo</span>
+        <p>
+          The repository is private. If the clone fails with a 404, your account cannot see it yet — ask
+          for access rather than hunting for the right URL.
+        </p>
+      </div>
+      <p class="step-why">
+        Already have it somewhere? Symlink that checkout instead of making a second copy.
+      </p>
+    </li>
+    <li class="step" data-step="declare">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v3-declare" aria-labelledby="t3-declare">
+        <h3 class="step-title" id="t3-declare">Declare it</h3>
+      </div>
+      <p class="step-why">One <code>name=path</code> entry, absolute path:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>export RECIPE_LIBRARY_PATH="perps=$HOME/shared-library/metamask-recipe-perps"</code></pre></div>
+      <p class="step-why">Several libraries are colon-separated, and the name is how they are labelled in output:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>export RECIPE_LIBRARY_PATH="perps=$HOME/shared-library/metamask-recipe-perps:mine=$HOME/dev/my-recipes"</code></pre></div>
+      <p class="step-why">
+        Put it in your shell profile so every session has it. Per-command, <code>--library
+        perps=&lt;path&gt;</code> does the same thing and is repeatable.
+      </p>
+    </li>
+    <li class="step" data-step="verify">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v3-verify" aria-labelledby="t3-verify">
+        <h3 class="step-title" id="t3-verify">Prove discovery sees it</h3>
+      </div>
+      <p class="step-why">This is the step people skip, then spend an afternoon on.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run --list</code></pre></div>
+      <div class="out-label">Expected — library recipes tagged with your library's name</div>
+      <div class="out">runnable recipes (core)
+Inspect: mm-harness run &lt;recipe&gt; --describe
+  perps.ensure-market-state <span class="hint">[perps]</span> variant=core params=network,market,side,…
+  perps.prove-order <span class="hint">[perps]</span> variant=core params=network,market,side,order_type,…
+  perps.snapshot-market <span class="hint">[perps]</span> variant=core params=network,market
+  perps.smoke <span class="dim">[metamask]</span> variant=core — Non-mutating Perps domain smoke…
+  runner.smoke <span class="dim">[metamask]</span> variant=core — Proves the headless Core runner…</div>
+      <p class="step-why">
+        The tag is the proof: <code>[perps]</code> came from your library, <code>[metamask]</code> ships
+        with the harness. No tags from your library means it was not loaded.
+      </p>
+      <details class="fail">
+        <summary>If it fails</summary>
+        <div class="fail-body">
+          <p><strong>Only <code>[metamask]</code> recipes</strong> — the variable is unset in this shell, or the path is wrong or relative. Echo it and check the path exists.</p>
+          <p><strong>Fewer recipes than expected</strong> — recipes declare which adapters they support. A mobile-only recipe will not appear in a core checkout. <code>--describe</code> shows the variant.</p>
+        </div>
+      </details>
+    </li>
+    <li class="step" data-step="run">
+      <div class="step-head">
+        <input type="checkbox" class="step-check" id="v3-run" aria-labelledby="t3-run">
+        <h3 class="step-title" id="t3-run">Read one before running it</h3>
+      </div>
+      <p class="step-why">Team recipes take parameters and many mutate testnet state.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run perps.prove-order --describe
+<span class="p">$ </span>mm-harness run perps.prove-order market=ETH side=short order_type=limit --plan</code></pre></div>
+      <p class="step-why">
+        Drop <code>--plan</code> when the mutation and its cleanup are what you want. The perps library's
+        <code>README.md</code> is its onboarding doc, and <code>docs/AUTHORING.md</code> covers writing
+        recipes into it.
+      </p>
+    </li>
+  </ol>
+  <div class="doctrine">
+    <p>
+      <span class="k">Your team's library follows the same pattern:</span> a repo of recipes plus domain
+      actions, cloned and declared by path. Nothing about the perps setup above is perps-specific except
+      the URL.
+    </p>
+  </div>
+  <hr class="sep">
+  <div class="btn-row">
+    <a class="btn btn-primary" href="v4.html">Next: cook a recipe →</a>
+    <a class="btn btn-ghost" href="../architecture.html#libraries">Where libraries fit</a>
+    <a class="btn btn-ghost" href="index.html">Back to the series</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.26+.</p>
+  </div>
+</footer>
+<script type="module" src="../assets/progress.mjs"></script>
+</body>
+</html>