@deeeed/metamask-harness 0.18.0 → 0.19.0

package/dist/commands/run.js

@@ -10,6 +10,7 @@ import {
   resolveAdapter,
   runtimeOptionsFromCli,
   isRecord,
+  parseRecipeParamAssignments,
   shellQuote,
   targetPath,
   usageError
@@ -33,6 +34,7 @@ import { acquireCheckoutLock } from "../checkout-lock.js";
 import { JsonStreamWriter } from "../json-stream.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 import { recipeTrustFailure } from "../recipe-security.js";
+import { recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
 async function handleRun(parsed) {
   const stream = new JsonStreamWriter("run", optionFlag(parsed.options, "jsonStream"));
   const restoreStdout = stream.isolateStdout();
@@ -104,7 +106,11 @@ async function handleRunInner({ positional, options }, stream) {
   }
   const targetRecipe = positional[0];
   if (!targetRecipe) throw usageError("run requires <recipe.json>.");
+  const paramAssignments = positional.slice(1);
   if (optionFlag(options, "describe")) {
+    if (paramAssignments.length > 0) {
+      throw usageError("run --describe does not accept parameter values; inspect the declaration first.");
+    }
     if (stream.enabled) {
       const message = "--json-stream is for recipe execution; use --describe --json for discovery.";
       stream.error({
@@ -116,7 +122,8 @@ async function handleRunInner({ positional, options }, stream) {
     }
     return handleDescribeRecipe(targetRecipe, options);
   }
-  if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options, stream);
+  const params = parseRecipeParamAssignments(paramAssignments);
+  if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, params, options, stream);
   const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
   const jsonOutput = json && !stream.enabled;
@@ -139,7 +146,7 @@ async function handleRunInner({ positional, options }, stream) {
   }
   if (recipeRunning(target)) return emitRunRecipeRunning(jsonOutput, stream, target);
   stream.phase("validate");
-  const validated = await validateRunRecipeStatic(targetRecipe, adapter, options);
+  const validated = await validateRunRecipeStatic(targetRecipe, adapter, options, params);
   if (validated.usageError) {
     const userAction = runUsageRecovery(
       validated.usageError.code,
@@ -160,7 +167,7 @@ async function handleRunInner({ positional, options }, stream) {
   if (validated.errorCount > 0) {
     return emitRunValidationError(jsonOutput, stream, adapter, validated.recipeFile, validated.findings, validated.errorCount);
   }
-  const depsBlock = adapter === "core" && recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
+  const depsBlock = adapter === "core" && await recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
   if (depsBlock) {
     return emitRunUsageError(jsonOutput, stream, adapter, validated.recipeFile, depsBlock.code, depsBlock.message, depsBlock.userAction);
   }
@@ -179,9 +186,11 @@ async function handleRunInner({ positional, options }, stream) {
       "set RECIPE_TASK_DIR/FARMSLOT_TASK_DIR inside the checkout or pass --artifacts-dir <path>"
     );
   }
+  recordCommandEvidence(artifactsDir);
   const librarySources = validated.librarySources;
   const runtimeOptions = {
     ...runtimeOptionsFromCli(options),
+    params,
     ...librarySources ? { librarySources } : {},
     stdoutIsMachineContract: machine,
     onActionEvent: ({ nodeId, action, status }) => stream.node(nodeId, action, status)
@@ -372,19 +381,22 @@ function formatPreviewLine(line, out) {
   const rest = match[2];
   return `${out(status === "PASS" ? "ok" : "err", status)} ${rest}`;
 }
-function recipeUsesCoreController(recipe, librarySources) {
+async function recipeUsesCoreController(recipe, librarySources) {
   if (objectUsesCoreController(recipe)) return true;
   const refs = collectCallRefs(recipe);
   if (refs.length === 0) return false;
-  const flows = loadFlowCatalogs(librarySources ?? []);
+  const sources = librarySources ?? [];
+  if (sources.length === 0) return false;
+  const { loadRecipeLibraries } = await import("@farmslot/recipe-harness");
+  const recipes = (await loadRecipeLibraries(sources, { adapter: "core" })).recipes;
   const visited = /* @__PURE__ */ new Set();
   const visit = (ref) => {
     if (visited.has(ref)) return false;
     visited.add(ref);
-    const flow = flows.get(ref);
-    if (!flow) return false;
-    if (objectUsesCoreController(flow)) return true;
-    return collectCallRefs(flow).some(visit);
+    const dependency = recipes.get(ref);
+    if (!dependency) return false;
+    if (objectUsesCoreController(dependency.document)) return true;
+    return collectCallRefs(dependency.document).some(visit);
   };
   return refs.some(visit);
 }
@@ -408,41 +420,16 @@ function collectCallRefs(value) {
   visit(value);
   return [...new Set(refs)];
 }
-function loadFlowCatalogs(librarySources) {
-  const flows = /* @__PURE__ */ new Map();
-  for (const source of librarySources) {
-    const flowsDir = path.join(source.root, "flows");
-    let entries;
-    try {
-      entries = fs.readdirSync(flowsDir);
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.endsWith(".json")) continue;
-      try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(flowsDir, entry), "utf8"));
-        if (!isRecord(parsed) || !isRecord(parsed.flows)) continue;
-        for (const [id, flow] of Object.entries(parsed.flows)) {
-          if (!flows.has(id)) flows.set(id, flow);
-        }
-      } catch {
-        continue;
-      }
-    }
-  }
-  return flows;
-}
 function actionUsesCoreController(action) {
   return typeof action === "string" && action.startsWith("metamask.perps.");
 }
-async function handleRunPlan(recipeArg, options, stream) {
+async function handleRunPlan(recipeArg, params, options, stream) {
   const json = optionFlag(options, "json");
   const jsonOutput = json && !stream.enabled;
   const { adapter, target } = resolveAdapter(options);
   stream.phase("resolve", { adapter, target, recipe: recipeArg });
   stream.phase("validate");
-  const validated = await validateRunRecipeStatic(recipeArg, adapter, options);
+  const validated = await validateRunRecipeStatic(recipeArg, adapter, options, params);
   if (validated.usageError) {
     const userAction = runUsageRecovery(
       validated.usageError.code,
@@ -460,7 +447,7 @@ async function handleRunPlan(recipeArg, options, stream) {
       userAction
     );
   }
-  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid } = validated;
+  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid, effectiveParams } = validated;
   const status = errorCount === 0 ? "pass" : "fail";
   const nodeCount = countRecipeNodes(recipe);
   const artifactsDir = optionString(options, "artifactsDir");
@@ -519,6 +506,7 @@ async function handleRunPlan(recipeArg, options, stream) {
     status,
     adapter,
     recipe: recipeFile,
+    params: redactStructuredValue(effectiveParams),
     findings,
     plan
   };

package/dist/commands/shared.js

@@ -53,7 +53,7 @@ function flag(options, key) {
   return options[key] === true;
 }
 function targetOf(options) {
-  return path.resolve(str(options, "target") ?? str(options, "projectRoot") ?? process.cwd());
+  return path.resolve(str(options, "target") ?? process.cwd());
 }
 const ADAPTER_TOKENS = ["mobile", "extension", "core"];
 function resolveAdapter(options, target, hint) {

package/dist/heal-bounds.js

@@ -7,6 +7,10 @@ import { EXIT } from "./commands/shared.js";
 function newHealState() {
   return { recovered: [], mutations: [], attemptedRecoveries: [] };
 }
+function conciseFailureForHuman(output) {
+  const errors = output.split(/\r?\n/u).map((line) => /^(?:[A-Za-z]*Error):\s*(.+)$/u.exec(line.trim())?.[1]).filter((line) => Boolean(line));
+  return errors.at(-1) ?? output.trim();
+}
 function parseHeal(options, fallback) {
   const value = options.heal;
   if (value === void 0) return fallback;
@@ -113,6 +117,7 @@ export {
   RECOVERY_CODE,
   checkHealBounds,
   classifyFailure,
+  conciseFailureForHuman,
   ensureOverlay,
   newHealState,
   parseHeal,

package/dist/mm-harness-cli.js

@@ -150,54 +150,45 @@ Example (real actions; run mm-harness actions for this checkout's full set):
   mm-harness call navigate page=perps --adapter mobile
   mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)`
   },
-  {
-    name: "flows",
-    summary: "Browse reusable parameterized action sequences.",
-    example: "mm-harness flows",
-    helpText: `mm-harness flows [list|describe <ref>|promote] [flags]
-
-  Browse reusable parameterized action sequences. Flows resolve by precedence
-  (personal > team > canonical); the highest-tier copy wins and shadows lower ones.
-  Flow resolution is adapter-global, so there is no --adapter flag here.
-
-  --library <name=path>              Add/override a library source (repeatable)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness flows
-  mm-harness flows describe perps.clean_market_testnet
-  mm-harness flows describe perps.clean_market_testnet --json`
-  },
   {
     name: "run",
     summary: "Execute a complete proof and write its evidence.",
     example: "mm-harness run recipe.json",
-    helpText: `mm-harness run <recipe.json> [flags]
+    helpText: `mm-harness run <recipe|recipe.json> [key=value ...] [flags]
 
   Validate and execute a complete proof, then write summary, trace, diagnostics,
-  and artifacts. A recipe may use actions directly or call reusable flows.
+  and artifacts. Inside a checkout, the adapter, target, ports, and artifact
+  directory are normally detected automatically.
 
+Discovery:
   --list                             List complete recipes accepted by run for this adapter; no <recipe> needed
-  --describe                         Show one recipe's metadata, declared inputs, composed actions/flows, and next command
+  --describe                         Show one recipe's parameters, composed actions/recipes, and runnable command
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
+
+Common overrides:
   --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
-  --cdp-port <port>                  Extension CDP port (env: CDP_PORT / RECIPE_CDP_PORT)
-  --launch-existing-dist             Extension: reuse/launch the existing dist without rebuilding
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --platform <ios|android>           Mobile platform preference; use --adapter for the product adapter
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Override evidence output (default: active task/artifacts, otherwise a checkout-local temp/recipe/runs/<run>)
-  --action-manifest <path>           Override the action manifest
   --library <name=path>              Add/override a recipe-library source (repeatable)
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
   --json-stream                      Line-flushed JSONL progress + terminal event
   --record-video=full-run            Record a video of the run
 
+Advanced integrations:
+  runtime: --cdp-port, --watcher-port/--metro-port, --runtime-dir, --slot,
+           --validation-runtime-dir, --launch-existing-dist
+  managed trust boundary (not needed for normal runs; Farmslot supplies it):
+           --source-trust, --source-kind, --source-name, --source-digest,
+           --approve-plan (binds approval to the exact reviewed plan)
+  schema:  --action-manifest
+
 Example:
   mm-harness run wallet.smoke --describe
-  mm-harness run recipe.json --plan --adapter mobile
-  mm-harness run recipe.json --adapter extension`
+  mm-harness run perps.clean-market-testnet market=BTC --plan
+  mm-harness run recipe.json market=ETH --adapter extension`
   },
   {
     name: "last",
@@ -486,9 +477,10 @@ Example:
     name: "fixtures",
     summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / generate / finalize.",
     example: "mm-harness fixtures set",
-    helpText: `mm-harness fixtures <init|sync|set|generate|finalize> [flags]
+    helpText: `mm-harness fixtures [<init|sync|set|generate|finalize>] [flags]
 
   Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
+  With no action, show the current fixture status and safe next command.
   init       Create it from --from <path>, or explicitly choose --dev for a
              disposable public test wallet that must never hold real funds.
   sync       Refresh the wallet fixture files on the target.
@@ -556,8 +548,8 @@ const HELP_GROUPS = [
   },
   {
     title: "DISCOVER",
-    blurb: "compose recipes from the action vocabulary + flow library (--json is the agent-primary form)",
-    commands: ["actions", "call", "flows"]
+    blurb: "discover atomic actions and reusable recipes (--json is the agent-primary form)",
+    commands: ["actions", "call"]
   },
   {
     title: "PROVE",

package/dist/run-diagnostics.js

@@ -180,7 +180,7 @@ function runMobileIssueCommand(projectRoot, command) {
   }
 }
 function redactPreview(value) {
-  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/\b(password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]").slice(0, MAX_PREVIEW_CHARS);
+  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/\b(api[-_]?key|password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization|vault)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]").slice(0, MAX_PREVIEW_CHARS);
 }
 function dedupeFindings(findings) {
   const byFingerprint = /* @__PURE__ */ new Map();

package/dist/run-recording.js

@@ -10,7 +10,7 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
   if (!options.record) return void 0;
   if (process.platform !== "darwin") {
     console.error(
-      "WARN: --record uses capture-helper and is currently supported only on macOS; continuing without video."
+      "WARN: --record-video uses capture-helper and is currently supported only on macOS; continuing without video."
     );
     return void 0;
   }

package/dist/runner.js

@@ -69,7 +69,10 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     (entry) => declaredActions.has(entry.action) && !existing.has(entry.action) && !lifecycle.some((lifecycleEntry) => lifecycleEntry.action === entry.action)
   );
   const autoHudDisabled = options.autoHud === false || process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false";
-  const logger = options.quietStdout ? new console.Console(process.stderr) : console;
+  const logger = deduplicateLibraryResolutionLogs(
+    options.quietStdout ? new console.Console(process.stderr) : console,
+    options.suppressLibraryResolutionLogs
+  );
   return createRecipeRunner({
     actionManifest,
     adapters: withActionProgress(
@@ -101,6 +104,25 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     }
   });
 }
+function deduplicateLibraryResolutionLogs(logger, suppress = false) {
+  const seen = /* @__PURE__ */ new Set();
+  return {
+    info(message) {
+      if (message.startsWith("Recipe libraries:")) {
+        if (suppress) return;
+        if (seen.has(message)) return;
+        seen.add(message);
+      }
+      logger.info(message);
+    },
+    warn(message) {
+      logger.warn(message);
+    },
+    error(message) {
+      logger.error(message);
+    }
+  };
+}
 async function prepareLiveAdapterImplementations(platform, actions, sources, trustTaskActions = false) {
   const prepared = /* @__PURE__ */ new Map();
   if (!sources) return prepared;
@@ -165,7 +187,7 @@ function withActionProgress(adapters, onActionEvent) {
       try {
         const result = await entry.execute(node, context);
         if (reportProgress) {
-          onActionEvent({ ...event, status: result.status === "fail" ? "failed" : "passed" });
+          onActionEvent({ ...event, status: "passed" });
         }
         return result;
       } catch (error) {

package/docs/CONTRIBUTING.md

@@ -11,7 +11,7 @@ bin/mm-harness
   -> @farmslot/recipe-harness    generic execution, UI transports, evidence
   -> @farmslot/protocol          schemas
   -> adapters/                   focused host/browser/device leaves
-  -> library/                    MetaMask actions, flows, recipes
+  -> library/                    MetaMask actions and recipes
   -> MetaMask checkout           product under test
 ```
 
@@ -37,8 +37,7 @@ task-local.
 | `adapters/<platform>/` | focused shell/Node host operations |
 | `adapters/<platform>/inject*` | assemble the checkout overlay from shipped adapter/library files |
 | `library/actions/` | executable MetaMask action adapters |
-| `library/flows/` | reusable parameterized behavior |
-| `library/recipes/` | reusable proofs |
+| `library/recipes/` | reusable parameterized behavior and proofs |
 | `library/manifests/` | declared capability surface |
 | `scripts/` | build/validation tooling and shipped completion/human-QA helpers |
 

package/docs/QA.md

@@ -29,7 +29,6 @@ mm-harness doctor
 mm-harness doctor --json
 mm-harness status
 mm-harness actions
-mm-harness flows
 mm-harness run --list
 mm-harness run runner.smoke --describe
 mm-harness run runner.smoke --plan

package/docs/RECIPES.md

@@ -2,98 +2,84 @@
 
 Use the smallest durable layer that proves the task:
 
-1. bundled actions;
-2. a bundled or team flow;
-3. a task-local recipe;
-4. a trusted task-local action or direct controller/CDP operation when no
-   stable action exists.
+1. call an existing action;
+2. compose existing recipes;
+3. write a task-local recipe;
+4. use a verified controller or CDP path when no stable action exists.
 
-Search before writing code:
+Discover before authoring:
 
 ```bash
 mm-harness actions <intent>
 mm-harness actions --action <name>
-mm-harness flows
-mm-harness flows describe <ref> --json
 mm-harness run --list
 mm-harness run <name> --describe
 ```
 
-Discovery reports the winning source, fields, examples, and shadowed sources.
-Use `--json` when an agent needs exact metadata.
+Discovery reports parameters, selected adapter variant, nested recipes, source,
+and shadows. Use `--json` for exact metadata.
 
-## Compose a proof
+## Author and run
 
-An action performs one operation. A flow packages reusable product setup or
-behavior. A recipe owns the task's acceptance criteria and evidence.
-
-Minimal recipe:
+An action performs one typed operation. A recipe owns a reusable graph or a
+task proof and may call other recipes.
 
 ```json
 {
-  "schema_version": 1,
-  "title": "Wallet readiness proof",
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Wallet readiness",
   "description": "Proves the running wallet is reachable and unlocked.",
-  "validate": {
-    "workflow": {
-      "entry": "unlock",
-      "nodes": {
-        "unlock": {
-          "action": "metamask.wallet.ensure_unlocked",
-          "intent": "Ensure the fixture-backed wallet is unlocked",
-          "next": "done"
-        },
-        "done": { "action": "end", "status": "pass" }
-      }
+  "paramsSchema": {
+    "type": "object",
+    "properties": {
+      "account": { "type": "string", "default": "Account 1" }
+    },
+    "additionalProperties": false
+  },
+  "workflow": {
+    "entry": "unlock",
+    "nodes": {
+      "unlock": {
+        "action": "metamask.wallet.ensure_unlocked",
+        "intent": "Make the fixture-backed wallet ready for use",
+        "next": "done"
+      },
+      "done": { "action": "end", "status": "pass" }
     }
   }
 }
 ```
 
-Validate without side effects, then run:
+Defaults are applied before validation. Root values use `key=value`; a nested
+recipe call uses `action: "call"`, `ref`, and `params`.
 
 ```bash
-mm-harness run recipe.json --plan
-mm-harness run recipe.json
-```
-
-To reuse an existing Extension build on a specific CDP runtime:
-
-```bash
-mm-harness run recipe.json --cdp-port 9500 --launch-existing-dist
+mm-harness run recipe.json account="Account 2" --plan
+mm-harness run recipe.json account="Account 2"
 ```
 
 Rules:
 
-- Use real product paths; never mutate DOM, Redux, controller, or persisted
-  state to fabricate proof.
-- Setup may use supported APIs, but a read/assert or visible UI postcondition
-  must prove the result.
-- Use `ui.*` for human-visible behavior. Keep ticket copy, styling, and layout
-  claims in the task recipe and screenshots.
-- Parameterize repeated behavior instead of multiplying action names.
-- Every `ensure_*` flow must prove a postcondition.
+- Validate with `--plan` before side effects.
+- Use real product paths; never mutate hidden state to fabricate proof.
+- Prove preparation with an independent read/assert or visible UI postcondition.
+- Keep ticket-specific claims in task-local recipes.
+- Parameterize repeated behavior instead of multiplying names.
 - Keep secrets out of recipes, libraries, and evidence.
 
-The Recipe Protocol v1 schema is authoritative:
+The protocol is authoritative:
 <https://farmslot.io/docs/reference/recipe-protocol-v1>.
 
-## Share reusable behavior
-
-A library may contain manifests, action implementations, flows, and complete
-recipes:
+## Share a library
 
 ```text
 team-recipes/
   library.json
   manifests/extension.action-manifest.json
   actions/extension/wallet/ensure_ready.mjs
-  flows/wallet.flows.json
   recipes/onboarding/smoke.extension.recipe.json
 ```
 
-Minimal `library.json`:
-
 ```json
 {
   "kind": "recipe-library",
@@ -103,59 +89,34 @@ Minimal `library.json`:
 }
 ```
 
-Enable it:
-
 ```bash
 export RECIPE_LIBRARY_PATH="wallet=$HOME/shared-library/wallet-team"
-mm-harness flows
 mm-harness run --list
 mm-harness run onboarding.smoke --describe
 mm-harness run onboarding.smoke --plan
 ```
 
-Use `--library wallet=/path/to/library` for one command. Without an explicit
-library, the personal library is `$FARMSLOT_HOME/recipe-library` (default
-`~/.farmslot/recipe-library`). Resolution is task/local configuration first,
-then bundled MetaMask; runs snapshot resolved definitions so shadowing is
-reviewable.
-
-Promote a repeated flow only after it has a useful description, typed params,
-and successful proof:
-
-```bash
-mm-harness flows promote --from recipe.json --flow wallet.ensure_ready --run artifacts
-```
+Use `--library wallet=/path/to/library` for one command. Resolution follows the
+explicit library order, then bundled MetaMask. Adapter-specific variants are
+selected deterministically. Every run records the root recipe, exact resolved
+dependency documents, their digests, call edges, selected sources, and shadows.
 
 ## Direct product access
 
-The bundled catalog is intentionally small. A task may use a real controller or
-CDP path when that is clearer than adding a permanent wrapper.
-
-Before doing so, validate the path in current product source and record:
-
-- the controller/API and supported parameters;
-- whether it reads or mutates state;
-- required preconditions;
-- the independent postcondition;
-- trace redaction.
-
-Do not infer route or controller names from memory. A direct mutation still
-requires a separate read/assert or visible UI proof. If the operation repeats
-across tasks, move it to a reviewed team library; promote it into the bundled
-catalog only when it is broadly reusable and stable across supported products.
-
-## Cross-platform expectations
-
-Mobile and Extension use the same wallet and Perps vocabulary where both expose
-the behavior. Core is headless: it reports fixture-backed controller inputs and
-does not pretend to have a selected UI account or app route.
+The bundled library is intentionally small. A task may use a verified controller
+or CDP path when that is clearer than adding a permanent wrapper. Confirm the
+current source path, mutation risk, preconditions, independent postcondition,
+and redaction. Do not infer route or controller names from memory. Repeated team
+behavior belongs in a reviewed team recipe; only broadly reusable stable
+capabilities belong in the bundled library.
 
-Inspect the current capability instead of assuming parity:
+Mobile and Extension share vocabulary where the product supports it. Core is
+headless and must not fabricate UI state. Inspect the current surface:
 
 ```bash
 mm-harness actions --category wallet --json
 mm-harness actions --category perps --json
-mm-harness actions --action metamask.wallet.list_accounts --json
+mm-harness run --list --json
 ```
 
 See [Security](SECURITY.md) before enabling custom executable actions.

package/library/README.md

@@ -1,8 +1,8 @@
 # Recipe library
 
 - An **action** performs one typed operation.
-- A **flow** packages a reusable parameterized sequence of actions.
-- A **recipe** is a complete proof that may call actions and flows.
+- A **recipe** is a parameterized, composable graph that may call actions and
+  other recipes.
 
 - `actions/<adapter>/<group>/<name>.mjs` — executable action modules.
   **Importing an action module RUNS it**: each ends with `runAdapter(main)` at top
@@ -13,6 +13,6 @@
 - Actions load harness helpers ONLY through `actions/harness-exports.mjs` (the
   dist-preferring bridge) — never deep-import `src/` (published installs have no
   src/, and the entrypoint would close an import cycle through adapters.ts).
-- `recipes/` — runnable smoke/validation recipes (`mm-harness run <file>`).
-- Flow resolution order is personal > team > canonical; shadowing is recorded in
-  summary.json (never silent).
+- `recipes/` — runnable recipes (`mm-harness run <name-or-file>`).
+- Recipe resolution is explicit library order, then bundled MetaMask; selected
+  variants and shadows are recorded in run evidence.