@deeeed/metamask-harness 0.83.0 → 0.85.0

package/dist/command-contract.js

@@ -1,11 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
-import { adapterChoices, closest } from "@farmslot/recipe-cli/harness";
+import {
+  adapterChoices,
+  booleanOption as bool,
+  contractOptions as options,
+  optionalValueOption as optionalValue,
+  optionValues,
+  valueOption as value
+} from "@farmslot/recipe-cli/harness";
 import { configuredLibrarySources, operatorLibraryEnv } from "./adapters/plugin-surface.js";
-const bool = () => ({ kind: "boolean" });
-const value = (choices) => ({ kind: "value", ...choices ? { choices } : {} });
-const optionalValue = (choices) => ({ kind: "optional-value", ...choices ? { choices } : {} });
-const options = (...groups) => Object.assign({}, ...groups);
 const HELP = { "--help": bool(), "-h": bool() };
 const JSON = { "--json": bool() };
 const NO_OPEN = { "--no-open": bool() };
@@ -15,19 +18,19 @@ const adapterIds = (tokens) => adapterChoices(optionValues(tokens, "--library"),
   configured: configuredLibrarySources(),
   env: operatorLibraryEnv()
 });
-const ADAPTER = { "--adapter": { kind: "value", choices: adapterIds } };
+const ADAPTER = { "--adapter": value(adapterIds) };
+function selectableAdapters(libraries = []) {
+  return adapterIds(libraries.flatMap((entry) => ["--library", entry]));
+}
+function withAdapterList(text, libraries = []) {
+  return text.replaceAll("{adapters}", selectableAdapters(libraries).join("|"));
+}
 const MOBILE_PLATFORM = { "--platform": value(["ios", "android"]) };
-const ADAPTER_OR_MOBILE_PLATFORM = {
-  "--platform": {
-    kind: "value",
-    choices: (tokens) => [...adapterIds(tokens), "ios", "android"]
-  }
-};
+const ADAPTER_OR_MOBILE_PLATFORM = { "--platform": value((tokens) => [...adapterIds(tokens), "ios", "android"]) };
 const DEVICE = { "--device": value() };
 const RUNTIME_PORTS = {
   "--cdp-port": value(),
   "--watcher-port": value(),
-  "--metro-port": value(),
   "--runtime-dir": value()
 };
 const RECIPE_RUNTIME = {
@@ -65,390 +68,1376 @@ const RUNWAY = {
   "--force": bool(),
   "--resolve-only": bool()
 };
-const REMOVED_OPTION_REPLACEMENTS = {
+const REPLACED_OPTIONS = {
   "--project-root": "--target",
-  "--record": "--record-video"
+  "--record": "--record-video",
+  "--metro-port": "--watcher-port",
+  "--arg": "key=value"
 };
-const PUBLIC_COMMAND_CONTRACTS = {
-  help: {
-    options: options(HELP, JSON, TARGET, ADAPTER, { "--domain": value() }),
-    positionals: [{ label: "topic", choices: ["review"] }]
+const MARK_ONLY = [
+  "--mark-last",
+  "--already-fixed",
+  "--no-self-review",
+  "--skip-learnings",
+  "--skip-checklist",
+  "--reason",
+  "--checklist",
+  "--signal"
+];
+const CLOSEOUT_ONLY = ["--json", "--share", "--config", "--destination", "--metadata"];
+const PUBLIC_COMMANDS = [
+  {
+    name: "help",
+    summary: "Load the version-matched recipe guide for a person or agent.",
+    example: "mm-harness help",
+    helpText: `mm-harness help [flags]
+
+  Loads the complete recipe guide shipped with this harness.
+
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Load the same guide as structured agent context
+
+  help review [--domain <name>] prints the review guide: the base review every PR
+  gets, plus the team library's anti-pattern families, parity rule, and shared
+  package notes when --domain names a library (see mm-harness review --help).
+
+Example:
+  mm-harness help
+  mm-harness help --json
+  mm-harness help review --domain perps`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, { "--domain": value() }),
+      positionals: [{ label: "topic", choices: ["review"] }]
+    }
   },
-  review: {
-    options: options(HELP, JSON, TARGET, ADAPTER, {
-      "--domain": value(),
-      "--since": value(),
-      "--base": value(),
-      "--out": value()
-    }),
-    positionals: [{ label: "action", choices: ["checklist"] }],
-    minimumPositionals: 1
+  {
+    name: "review",
+    summary: "Materialize a review checklist: base review + team library patterns + parity + verdict.",
+    example: "mm-harness review checklist --domain perps",
+    helpText: `mm-harness review checklist [flags]
+
+  Writes a phase-structured checklist (Setup, Base review, Domain patterns,
+  Parity, Verdict) that mm-harness checklist mark can track. Domain patterns are
+  one line per "##" section of the library's review/antipatterns.md; Parity names
+  the other platform's checkout when one resolves and says "not checked" otherwise.
+
+  Library resolution for --domain <name>: RECIPE_LIBRARY_PATH entry \u2192 engineer
+  config (mm-harness config) \u2192 sibling directory beside the checkout \u2192 shallow
+  fetch into <checkout>/.skills-cache/<name> (known libraries only). Reference
+  checkout resolution: MM_HARNESS_REF_<ADAPTER> \u2192 engineer config \u2192 sibling
+  checkout of that adapter.
+
+  --domain <name>   Team library to compose (default: MM_HARNESS_DOMAIN; none = base review only)
+  --since <sha>     Incremental re-review: scope the checklist to <sha>..HEAD
+  --base <ref>      Base ref for the diff range (default: origin/main when present)
+  --out <file>      Also write the checklist to <file>
+  --adapter, --target, --json
+
+Example:
+  mm-harness review checklist --domain perps
+  mm-harness review checklist --domain perps --since 4dd9be9 --out temp/tasks/review/CHECKLIST.md
+  mm-harness review checklist --json`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, {
+        "--domain": value(),
+        "--since": value(),
+        "--base": value(),
+        "--out": value()
+      }),
+      positionals: [{ label: "action", choices: ["checklist"] }],
+      minimumPositionals: 1
+    }
   },
-  domain: {
-    options: options(HELP, JSON, TARGET, ADAPTER, {
-      "--domain": value(),
-      "--base": value()
-    })
+  {
+    name: "domain",
+    summary: "Which team library owns the change: declared value first, else owned-paths.json against the changed files.",
+    example: "mm-harness domain",
+    helpText: `mm-harness domain [flags]
+
+  Prints the domain name (or "none"). A declared --domain / MM_HARNESS_DOMAIN wins;
+  otherwise the changed files (base...HEAD, working tree, untracked) are matched
+  against owned-paths.json in every reachable library (RECIPE_LIBRARY_PATH,
+  mm-harness config, sibling directories, .skills-cache).
+
+  --domain <name>   Declared domain (skips classification)
+  --base <ref>      Base ref for the changed-file range (default: origin/main when present)
+  --adapter, --target, --json
+
+Example:
+  mm-harness domain
+  mm-harness domain --json`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, {
+        "--domain": value(),
+        "--base": value()
+      })
+    }
   },
-  "pr-body": {
-    options: options(HELP, JSON, {
-      "--command": value(),
-      "--out": value()
-    }),
-    positionals: [{ label: "action", choices: ["render"] }, { label: "task-dir" }],
-    minimumPositionals: 2
+  {
+    name: "pr-body",
+    summary: "Render the publishable PR body: the authored description plus the recipe and run log sections built from artifacts.",
+    example: "mm-harness pr-body render temp/tasks/dev/TAT-1",
+    helpText: `mm-harness pr-body render <task-dir> [flags]
+
+  Reads <task-dir>/artifacts/pr-description.md (the PR body the worker wrote in
+  the repository PR template shape) and inserts the machine sections rendered
+  from artifacts: "Validation Recipe" from artifacts/recipe.json, "Validation
+  Logs" from artifacts/recipe-run/report.md, and "Recipe Workflow" from
+  artifacts/workflow.mmd when it exists. Any such section the worker pasted by
+  hand is replaced. The sections go before the first checklist section, else at
+  the end. Fences are always longer than any backtick run in the content and
+  close on their own line. Writes <task-dir>/artifacts/pr-body.md.
+
+  --command <text>  Recipe invocation to show above the run log
+  --out <file>      Write elsewhere than artifacts/pr-body.md
+  --json            Machine-readable result
+
+Example:
+  mm-harness pr-body render temp/tasks/dev/TAT-1 --json`,
+    contract: {
+      options: options(HELP, JSON, {
+        "--command": value(),
+        "--out": value()
+      }),
+      positionals: [{ label: "action", choices: ["render"] }, { label: "task-dir" }],
+      minimumPositionals: 2
+    }
   },
-  config: {
-    options: options(HELP, JSON),
-    positionals: [
-      { label: "action", choices: ["list", "path", "get", "set", "unset"] },
-      { label: "key" },
-      { label: "value" }
-    ]
+  {
+    name: "config",
+    summary: "Per-engineer locations and optional recipe advisor settings.",
+    example: "mm-harness config set references.extension ~/dev/metamask-extension",
+    helpText: `mm-harness config <list|path|get <key>|set <key> <value>|unset <key>> [--json]
+
+  Stored outside every repo in ~/.mm-harness/config.json (override: MM_HARNESS_CONFIG).
+  Keys: libraries.<name> (team library checkout), references.<mobile|extension|core|terminal>
+  (the checkout used as the parity reference), advisor.enabled (true/false),
+  advisor.provider, advisor.model, advisor.stages (plan,draft,evidence). Advisor
+  settings contain no credentials and default to disabled with planning only.
+  Env always wins over location config:
+  RECIPE_LIBRARY_PATH for libraries, MM_HARNESS_REF_<ADAPTER> for references.
+
+Example:
+  mm-harness config set libraries.perps ~/dev/experimental-metamask-recipe-perps
+  mm-harness config set references.extension ~/dev/metamask-extension
+  mm-harness config set advisor.provider typesafe
+  mm-harness config set advisor.enabled true
+  mm-harness config list`,
+    contract: {
+      options: options(HELP, JSON),
+      positionals: [
+        { label: "action", choices: ["list", "path", "get", "set", "unset"] },
+        { label: "key" },
+        { label: "value" }
+      ]
+    }
   },
-  tutorial: {
-    options: options(HELP, JSON, NO_OPEN)
+  {
+    name: "tutorial",
+    summary: "Open the protected visual recipe tutorial.",
+    example: "mm-harness tutorial",
+    helpText: `mm-harness tutorial [flags]
+
+  Source checkouts open the local tutorial on port 8765. Installed releases
+  open the protected MetaMask GitHub Pages site.
+
+  --no-open                          Print the tutorial URL without opening it
+  --json                             Print version, URL, and open status as JSON
+
+Example:
+  mm-harness tutorial`,
+    contract: {
+      options: options(HELP, JSON, NO_OPEN)
+    }
   },
-  "setup-base": {
-    options: options(HELP, JSON, {
-      "--dir": value(),
-      "--counts": value(),
-      "--only": value(),
-      "--dry-run": bool(),
-      "--force": bool(),
-      "--show-config": bool(),
-      "--reset-config": bool(),
-      "--skip-harness-update": bool()
-    })
+  {
+    name: "setup-base",
+    summary: "Bootstrap numbered MetaMask product checkouts and install their dependencies.",
+    example: "mm-harness setup-base --only core --counts core=1",
+    helpText: `mm-harness setup-base [flags]
+
+  Bootstrap numbered MetaMask Extension, Mobile, and Core checkouts under one
+  base directory, then run each checkout's pinned dependency install.
+
+  --dir <base>                       Destination root
+  --counts <repo=n,...>              Copies per selected repository
+  --only <extension,mobile,core>     Repository subset
+  --dry-run                          Print the plan without changing anything
+  --force                            Override the free-space refusal
+  --json                             Machine-readable terminal summary
+  --show-config                      Print saved preferences and exit
+  --reset-config                     Remove saved preferences and exit
+  --skip-harness-update              Skip the installed-version notice
+
+Example:
+  mm-harness setup-base --only core --counts core=1`,
+    contract: {
+      options: options(HELP, JSON, {
+        "--dir": value(),
+        "--counts": value(),
+        "--only": value(),
+        "--dry-run": bool(),
+        "--force": bool(),
+        "--show-config": bool(),
+        "--reset-config": bool(),
+        "--skip-harness-update": bool()
+      })
+    }
   },
-  status: {
+  {
+    name: "status",
     aliases: ["health", "home"],
-    options: options(HELP, JSON, TARGET, DEVICE, {
-      "--fast": bool(),
-      "--all-devices": bool(),
-      "--watch": bool(),
-      "--task": value()
-    })
+    summary: "Home dashboard for a checkout: detected adapter, next command, and (mobile) connected devices with the selected target.",
+    example: "mm-harness status",
+    helpText: `mm-harness status [flags]
+
+  Home dashboard for the current checkout \u2014 the detected adapter, the next command
+  to run, and (mobile only) the connected devices with live app state. Aliases: health, home.
+
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable envelope { adapter, target, view, devices[], next }
+  --fast                             Skip all live-state probes (instant output, safe for scripts)
+  --all-devices                      Mobile only: show every connected device instead of the slot-scoped target
+  --watch                            Live read-only view of the task this checkout is working through (refreshes every 2s, Ctrl-C to leave)
+  --task <dir>                       Task directory for the view (default: the most recently marked one under temp/tasks/)
+
+  The task view reads task files only \u2014 no probe, no launch, no write \u2014 and shows
+  the same facts whether a skill or a control plane started the run: slot and
+  device isolation, template and flow, fixture and sandbox readiness, then the
+  checklist with the time each row took, how long the current row has been
+  running, and acceptance criteria with recorded verdicts. The home dashboard
+  also shows criteria for an ongoing task. --task without --watch prints it once.
+  With --json, --watch emits one
+  object per change (newline-delimited) instead of redrawing.
+
+  The checkout view (also under "view" in --json, and printed by doctor) is what
+  this checkout is bound to: the runtime-context fields that keep it off other
+  slots' ports and devices, the recipe libraries this machine resolves, and the
+  wallet fixture it last applied.
+
+  Human output: static device list prints immediately; live-state lines append
+  after the ~2s probe window (screen, wallet, account, fixture per device).
+  By default mobile status shows the configured target only; --device <id>
+  switches the active target for that command. Other devices that answer on the
+  same Metro are reported as additional reachable targets.
+
+  The devices[] section carries per device:
+    { platform, id, name, state, selected }   always present
+    { currentScreen, walletState, selectedAccount, fixtureStatus }  when bridge reachable
+    { liveState: 'no-bridge' }   when bridge unreachable or --fast
+
+  All RN targets attached to the checkout's Metro are probed and matched to their
+  devices; a device whose target cannot be confidently matched (Metro's device
+  description matches neither the serial nor the model name) degrades to
+  liveState:'no-bridge'. An attached target whose build predates __AGENTIC__
+  reports liveState:'bridge-absent'.
+  Extension/core live-state probing is V1-pending (use doctor for runtime status).
+
+Example:
+  mm-harness status
+  mm-harness status --json
+  mm-harness status --fast
+  mm-harness status --watch`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, {
+        "--fast": bool(),
+        "--all-devices": bool(),
+        "--watch": bool(),
+        "--task": value()
+      })
+    }
   },
-  checklist: {
-    usage: "mm-harness checklist <mark <task-dir> <step> | closeout <task-dir>> [options]",
-    options: options(HELP, JSON, {
-      "--mark-last": bool(),
-      "--already-fixed": bool(),
-      "--no-self-review": bool(),
-      "--skip-learnings": bool(),
-      "--skip-checklist": bool(),
-      "--reason": value(),
-      "--checklist": value(),
-      "--signal": value(),
-      "--share": bool(),
-      "--config": value(),
-      "--destination": value(),
-      "--metadata": value()
-    }),
-    positionals: [
-      { label: "action", choices: ["mark", "closeout"] },
-      { label: "task-dir" },
-      {
-        label: "step",
-        validate: (step) => {
-          if (["start", "complete", "no-change", "blocked"].includes(step)) return true;
-          const numeric = Number(step);
-          return Number.isInteger(numeric) && numeric >= 1;
-        },
-        validDescription: "start|complete|no-change|blocked|a positive numeric step"
+  {
+    name: "checklist",
+    summary: "Mark checklist progress and close out scrubbed learning packages.",
+    example: "mm-harness checklist mark <task-dir> start",
+    helpText: `mm-harness checklist <mark|closeout> <task-dir> [step] [options]
+
+  mark delegates checklist state to @farmslot/agent-runtime. Successful complete
+  and no-change marks stage a learning package through @farmslot/handoff.
+  closeout exposes that same Handoff boundary directly; --share remains explicit.
+  The task directory is the one mm-harness task init wrote. Without a
+  checklist-target.json it marks CHECKLIST.md and writes SIGNAL.json; only a
+  role switch writes that manifest, to point at its own checklist.
+
+  Steps: start | 1 | 2 | ... | complete | no-change | blocked
+
+Example:
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> start
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> 1
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> sub start qa-cases --step 2 --from inputs/qa-cases.md
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> sub qa-cases 1
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> complete --mark-last
+  mm-harness checklist closeout temp/tasks/recipe-cook/<task> --share`,
+    contract: {
+      usage: "mm-harness checklist <mark <task-dir> <step> | closeout <task-dir>> [options]",
+      options: options(HELP, JSON, {
+        "--mark-last": bool(),
+        "--already-fixed": bool(),
+        "--no-self-review": bool(),
+        "--skip-learnings": bool(),
+        "--skip-checklist": bool(),
+        "--reason": value(),
+        "--checklist": value(),
+        "--signal": value(),
+        "--share": bool(),
+        "--config": value(),
+        "--destination": value(),
+        "--metadata": value()
+      }),
+      positionals: [
+        { label: "action", choices: ["mark", "closeout"] },
+        { label: "task-dir" },
+        {
+          label: "step",
+          validate: (step) => {
+            if (["start", "complete", "no-change", "blocked"].includes(step)) return true;
+            const numeric = Number(step);
+            return Number.isInteger(numeric) && numeric >= 1;
+          },
+          validDescription: "start|complete|no-change|blocked|a positive numeric step"
+        }
+      ],
+      minimumPositionals: 2,
+      // `mark <task-dir> sub …` is agent-runtime's child-unit grammar; it validates it.
+      bypass: (tokens) => tokens[0] === "mark" && Boolean(tokens[1]) && !tokens[1]?.startsWith("-") && tokens[2] === "sub",
+      refine: (positionals, seen, fail) => {
+        const action = positionals[0];
+        if (action !== "mark" && action !== "closeout") return null;
+        const invalid = (action === "mark" ? CLOSEOUT_ONLY : MARK_ONLY).find((option) => seen.has(option));
+        if (invalid) return fail.usage("CLI_UNKNOWN_OPTION", `${invalid} is not valid with checklist ${action}.`);
+        if (action === "mark" && positionals.length < 3) return fail.missingPositional("checklist mark requires <step>.");
+        if (action === "closeout" && positionals.length > 2) {
+          return fail.usage(
+            "CLI_EXCESS_POSITIONAL",
+            `unexpected positional '${positionals[2]}'; checklist closeout accepts only <task-dir>.`
+          );
+        }
+        return null;
       }
-    ],
-    minimumPositionals: 2
+    }
   },
-  prepare: {
-    usage: "mm-harness prepare [--target <checkout>] [--platform mobile|extension|core] [--mobile-platform ios|android] [--clear-metro] [--artifacts-dir <dir>] [--json]",
-    options: options(HELP, JSON, TARGET, {
-      "--platform": { kind: "value", choices: adapterIds },
-      "--mobile-platform": value(["ios", "android"]),
-      "--clear-metro": bool(),
-      "--artifacts-dir": value(),
-      "--remote-flag": value()
-    })
+  {
+    name: "prepare",
+    summary: "Bring this checkout to a proven-ready state and write the readiness record.",
+    example: "mm-harness prepare --platform extension",
+    helpText: `mm-harness prepare [flags]
+
+  Run the readiness chain for this checkout and record what it did as one
+  protocol readiness record (sandbox.json). Steps run in order and stop at the
+  first failure; later steps are recorded as skipped.
+
+    doctor --fix   status   launch --verify   fixtures set   verify
+
+  Core skips launch and fixtures (headless; verify is its readiness gate).
+  Mobile infers ios|android from the connected devices reported by status and
+  refuses with the numbered choice when that is ambiguous.
+
+  --target <path>                    Checkout path (default: cwd)
+  --platform <{adapters}> Force the platform (auto-detected inside a checkout)
+  --mobile-platform <ios|android>    Mobile target when status cannot decide it
+  --clear-metro                      Mobile only: clear Metro's transform cache in the launch step
+  --artifacts-dir <dir>              Where sandbox.json and the per-step reports land
+                                     (default: <target>/temp/recipe/runtime)
+  --json                             Print the readiness record
+
+  Exit 0 when the record is ready, 1 otherwise.
+
+Example:
+  mm-harness prepare
+  mm-harness prepare --platform mobile --mobile-platform ios --json
+  mm-harness prepare --artifacts-dir temp/tasks/fix/TAT-1/artifacts --json`,
+    contract: {
+      usage: "mm-harness prepare [--target <checkout>] [--platform mobile|extension|core] [--mobile-platform ios|android] [--clear-metro] [--artifacts-dir <dir>] [--json]",
+      options: options(HELP, JSON, TARGET, {
+        "--platform": value(adapterIds),
+        "--mobile-platform": value(["ios", "android"]),
+        "--clear-metro": bool(),
+        "--artifacts-dir": value(),
+        "--remote-flag": value()
+      })
+    }
   },
-  task: {
-    usage: "mm-harness task init <task-dir> --flow f --template id --title t [options]",
-    options: options(HELP, JSON, {
-      "--flow": value(),
-      "--run-mode": value(["autonomous", "interactive", "validation"]),
-      "--platform": value(),
-      "--template": value(),
-      "--title": value(),
-      "--task-text": value(),
-      "--task-file": value(),
-      "--acceptance": value(),
-      "--ticket": value(),
-      "--source-ref": value(),
-      "--surface": value(),
-      "--project": value(),
-      "--repo": value(),
-      "--attempt-id": value(),
-      "--var": value(),
-      "--task-dir-label": value(),
-      "--mode-preamble": value(),
-      "--addendum-file": value(),
-      "--mark-command": value(),
-      "--dir": value(),
-      "--domain-dir": value(),
-      "--project-worker": value(),
-      "--project-name": value(),
-      "--package-templates": value(),
-      "--package-id": value(),
-      "--domain": value()
-    }),
-    positionals: [
-      { label: "action", choices: ["init"] },
-      { label: "task-dir" }
-    ],
-    minimumPositionals: 2
+  {
+    name: "task",
+    summary: "Create the task directory an agent works from, out of a shared execution template.",
+    example: 'mm-harness task init temp/tasks/fix/TAT-1 --flow fix-bug --template fix-bug/mobile --title "Wrong total"',
+    helpText: `mm-harness task init <task-dir> [options]
+
+  Write the task directory from a selected execution template: TASK.md, the
+  CHECKLIST.md whose boxes are the steps, a mark shim routed through
+  mm-harness checklist mark, and inputs/ (handoff.json, worker-terminal-contract.json).
+  checklist-target.json is NOT written \u2014 absent means CHECKLIST.md + SIGNAL.json.
+
+  Applied when you do not pass them: --surface skill, --mark-command for this
+  executable, and --platform from the detected checkout.
+
+Task:
+  --title <t>                        Task title (required)
+  --task-text <s> | --task-file <p>  Task description, inline or from a file
+  --acceptance <criterion>          Authored acceptance criterion (repeatable, preserved in order)
+  --ticket <key>                     Ticket key
+  --source-ref <url>                 Where the task came from
+
+Selection (same catalog as execution-template):
+  --flow <flow>                      Exact flow (required)
+  --run-mode <mode>                  autonomous|interactive|validation (optional;
+                                     set by the Farmslot control plane, omit for
+                                     skill/manual runs)
+  --platform <platform>              Exact platform
+  --template <id>                    Exact template id (required)
+  --domain <domain>                  Exact domain
+  --dir <path>                       Custom flow-tree source (repeatable)
+  --domain-dir <domain=path>         Domain-scoped team source (repeatable)
+  --package-templates <path>         Canonical package flow-tree root
+  --package-id <id>                  Source label for the package root
+  --project-worker <path>            Project template directory
+  --project-name <name>              Source label for project templates
+
+Identity and rendering:
+  --surface <s>                      Handoff surface (default: skill)
+  --project <name>  --repo <owner/name>  --attempt-id <id>
+  --var KEY=VALUE                    Template placeholder value (repeatable)
+  --task-dir-label <label>           Task directory as written into the documents
+  --mode-preamble <text>             Run-mode preamble for TASK.md
+  --addendum-file <path>             Extra task-document section
+  --mark-command <cmd>               Override the recorded mark command
+  --json                             Machine-readable output
+
+Example:
+  mm-harness task init temp/tasks/fix/TAT-1 --flow fix-bug \\
+    --template fix-bug/mobile --package-templates <path> \\
+    --title "Wrong total on the receipt" --ticket TAT-1 --json`,
+    contract: {
+      usage: "mm-harness task init <task-dir> --flow f --template id --title t [options]",
+      options: options(HELP, JSON, {
+        "--flow": value(),
+        "--run-mode": value(["autonomous", "interactive", "validation"]),
+        "--platform": value(),
+        "--template": value(),
+        "--title": value(),
+        "--task-text": value(),
+        "--task-file": value(),
+        "--acceptance": value(),
+        "--ticket": value(),
+        "--source-ref": value(),
+        "--surface": value(),
+        "--project": value(),
+        "--repo": value(),
+        "--attempt-id": value(),
+        "--var": value(),
+        "--task-dir-label": value(),
+        "--mode-preamble": value(),
+        "--addendum-file": value(),
+        "--mark-command": value(),
+        "--dir": value(),
+        "--domain-dir": value(),
+        "--project-worker": value(),
+        "--project-name": value(),
+        "--package-templates": value(),
+        "--package-id": value(),
+        "--domain": value()
+      }),
+      positionals: [
+        { label: "action", choices: ["init"] },
+        { label: "task-dir" }
+      ],
+      minimumPositionals: 2
+    }
   },
-  "execution-template": {
-    usage: "mm-harness execution-template <list|materialize|lint|new> [target] [options]",
-    options: options(HELP, JSON, {
-      "--dir": value(),
-      "--domain-dir": value(),
-      "--project-worker": value(),
-      "--project-name": value(),
-      "--package-templates": value(),
-      "--package-id": value(),
-      "--flow": value(),
-      "--run-mode": value(["autonomous", "interactive", "validation"]),
-      "--platform": value(),
-      "--domain": value(),
-      "--id": value(),
-      "--provenance": value(),
-      "--include-shadowed": bool(),
-      "--no-include-shadowed": bool(),
-      "--title": value(),
-      "--force": bool()
-    }),
-    positionals: [
-      { label: "action", choices: ["list", "materialize", "lint", "new"] }
-    ],
-    minimumPositionals: 1,
-    variadic: { label: "target", validate: (value2) => value2.length > 0 }
+  {
+    name: "execution-template",
+    summary: "Discover, validate, and materialize shared agent checklists.",
+    example: "mm-harness execution-template list --package-templates <path> --json",
+    helpText: `mm-harness execution-template <list|materialize|lint|new> [options]
+
+  Shared Markdown checklist catalog used by direct and orchestrated workflows.
+  Sources use the flow-tree shape <root>/<flow>/<variant>.md.
+
+  list        List compatible templates and portable source provenance.
+  materialize Select one template, copy its immutable snapshot, and optionally
+              write a provenance record.
+  lint        Validate one template file or flow-tree directory.
+  new         Create a minimal starter template.
+
+Common source/filter options:
+  --dir <path>                       Custom flow-tree source (repeatable)
+  --domain-dir <domain=path>         Domain-scoped team source (repeatable)
+  --package-templates <path>         Canonical package flow-tree root
+  --package-id <id>                  Source label for the package root
+  --project-worker <path>            Project template directory
+  --project-name <name>              Source label for project templates
+  --flow <flow>                      Exact flow
+  --platform <platform>              Exact platform
+  --run-mode <mode>                  autonomous|interactive|validation (optional;
+                                     set by the Farmslot control plane, omit for
+                                     skill/manual runs)
+  --domain <domain>                  Exact domain
+  --id <id>                          Exact template id
+  --json                             Machine-readable output
+
+Materialize:
+  mm-harness execution-template materialize <output> --flow fix-bug \\
+    --platform mobile --id fix-bug/mobile \\
+    --package-templates <path> --provenance <path> --json`,
+    contract: {
+      usage: "mm-harness execution-template <list|materialize|lint|new> [target] [options]",
+      options: options(HELP, JSON, {
+        "--dir": value(),
+        "--domain-dir": value(),
+        "--project-worker": value(),
+        "--project-name": value(),
+        "--package-templates": value(),
+        "--package-id": value(),
+        "--flow": value(),
+        "--run-mode": value(["autonomous", "interactive", "validation"]),
+        "--platform": value(),
+        "--domain": value(),
+        "--id": value(),
+        "--provenance": value(),
+        "--include-shadowed": bool(),
+        "--no-include-shadowed": bool(),
+        "--title": value(),
+        "--force": bool()
+      }),
+      positionals: [
+        { label: "action", choices: ["list", "materialize", "lint", "new"] }
+      ],
+      minimumPositionals: 1,
+      variadic: { label: "target", validate: (value2) => value2.length > 0 },
+      refine: (positionals, _seen, fail) => {
+        const action = positionals[0] ?? "";
+        if (!["list", "materialize", "lint", "new"].includes(action)) return null;
+        const targetCount = Math.max(0, positionals.length - 1);
+        if (action === "list" && targetCount > 0) {
+          return fail.usage("CLI_EXCESS_POSITIONAL", `execution-template list does not accept positional '${positionals[1]}'.`);
+        }
+        if (action !== "list" && targetCount === 0) {
+          return fail.missingPositional(`execution-template ${action} requires <target>.`);
+        }
+        if (targetCount > 1) {
+          return fail.usage(
+            "CLI_EXCESS_POSITIONAL",
+            `unexpected positional '${positionals[2]}'; execution-template ${action} accepts one <target>.`
+          );
+        }
+        return null;
+      }
+    }
   },
-  actions: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
-      "--action": value(),
-      "--matrix": bool(),
-      "--categories": bool(),
-      "--category": value(),
-      "--action-manifest": value(),
-      "--library": value(),
-      "--raw": bool()
-    }),
-    positionals: [{ label: "query" }],
-    noPositionalsWith: ["--action", "--categories", "--raw"]
+  {
+    name: "actions",
+    summary: "Discover typed single operations and their fields.",
+    example: "mm-harness actions --adapter mobile",
+    helpText: `mm-harness actions [query] [flags]
+
+  Discover typed single operations and their field schemas for this checkout.
+
+  query                              Search names, categories, fields, and descriptions (typo-tolerant)
+  --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
+  --matrix                           Compare action availability across Mobile, Extension, Core, and Terminal
+  --categories                       List compact action categories and counts
+  --category <name>                  List only one category (for example ui, wallet, or perps)
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --raw                              Dump raw action registry JSON
+  --json                             Machine-readable output
+
+Example:
+  mm-harness actions --adapter mobile
+  mm-harness actions --matrix --json
+  mm-harness actions positions --adapter mobile
+  mm-harness actions --adapter mobile --categories --json
+  mm-harness actions --adapter mobile --category ui --json
+  mm-harness actions --adapter mobile --action assert_orders
+  mm-harness actions --adapter extension --raw`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+        "--action": value(),
+        "--matrix": bool(),
+        "--categories": bool(),
+        "--category": value(),
+        "--action-manifest": value(),
+        "--library": value(),
+        "--raw": bool()
+      }),
+      positionals: [{ label: "query" }],
+      noPositionalsWith: ["--action", "--categories", "--raw"]
+    }
   },
-  stop: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
-      "--port": value(),
-      "--watcher-port": value()
-    })
+  {
+    name: "stop",
+    summary: "Stop this checkout runtime (mobile Metro / Extension watcher + owned browser) and close its log windows.",
+    example: "mm-harness stop",
+    helpText: `mm-harness stop [flags]
+
+  Stop the runtime this checkout owns and close its tmux log-tail windows,
+  scoped to this checkout so concurrent slots are untouched. Idempotent \u2014
+  nothing running is success, not an error. Behavior is per platform:
+    mobile     stop the port-scoped Metro dev server
+    extension  stop webpack watcher, owned Chrome/CDP profile processes, viewers, and stale markers
+    core       headless \u2014 no dev server to stop (teaching error)
+
+  --port <port>                      Metro/webpack port override; Extension CDP remains checkout-context scoped
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness stop
+  mm-harness stop --port 8061`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+        "--port": value(),
+        "--watcher-port": value()
+      })
+    }
   },
-  call: {
-    options: options(HELP, JSON, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
-      "--list": bool(),
-      "--domain": value(),
-      "--source": value(),
-      "--sort": value(["domain", "name", "library"]),
-      "--arg": value()
-    }),
-    positionals: [{ label: "action" }],
-    minimumPositionals: 0,
-    requiredUnless: ["--list"],
-    noPositionalsWith: ["--list"],
-    leadingPositionals: 1,
-    variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u }
+  {
+    name: "call",
+    summary: "Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; key=value inputs; same trace/evidence as run).",
+    example: "mm-harness call ensure_unlocked",
+    helpText: `mm-harness call <action> [key=value ...] [flags]
+
+  Run one action in isolation as a one-node recipe through the real engine path.
+  Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
+  if unique; ambiguous = exit 2. Pass action fields as key=value; numbers,
+  booleans, arrays, and objects are parsed as JSON-like values.
+  Actions differ per adapter \u2014 list this checkout's with:
+  mm-harness actions.
+
+  --list                             List actions accepted by call for this adapter; no <action> needed
+  --domain <name>                    With --list: filter by action domain, e.g. perps or swap-bridge
+  --source <name>                    With --list: filter by origin, e.g. metamask, perps, or official
+  --sort <domain|name|library>       With --list: grouping/order (default: domain; JSON: name)
+  --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
+  --cdp-port <port>                  Extension only: bind the action to this live browser runtime.
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --artifacts-dir <dir>              Where to write evidence (default: <task>/artifacts/calls/<action>-<id>
+                                     inside a task, else temp/recipe/calls/<action>-<id>)
+  --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
+
+Example (real actions; run mm-harness actions for this checkout's full set):
+  mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
+  mm-harness call navigate page=perps --adapter mobile
+  mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)
+
+Remote feature flags (mobile applies at runtime; extension pins at launch):
+  mm-harness call metamask.feature_flags.read --adapter mobile
+  mm-harness call metamask.feature_flags.set --adapter mobile \\
+    'flags={"perpsTAT3938AbtestScreenVsBottomSheet":"treatment"}'
+  mm-harness call metamask.feature_flags.clear --adapter mobile`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
+        "--list": bool(),
+        "--domain": value(),
+        "--source": value(),
+        "--sort": value(["domain", "name", "library"])
+      }),
+      positionals: [{ label: "action" }],
+      minimumPositionals: 0,
+      requiredUnless: ["--list"],
+      noPositionalsWith: ["--list"],
+      leadingPositionals: 1,
+      variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u },
+      missingPositionalAction: (example) => `List actions: mm-harness call --list
+  Example: ${example}
+  More: mm-harness call --help`
+    }
   },
-  run: {
-    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, RUN_FUNDING, {
-      "--list": bool(),
-      "--domain": value(),
-      "--source": value(),
-      "--sort": value(["domain", "name", "library"]),
-      "--plan": bool(),
-      "--proof": bool(),
-      "--describe": bool(),
-      "--hud": value(["auto", "show", "hide"])
-    }),
-    positionals: [{ label: "recipe" }],
-    minimumPositionals: 1,
-    requiredUnless: ["--list"],
-    noPositionalsWith: ["--list"],
-    variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u }
+  {
+    name: "run",
+    summary: "Execute a complete proof and write its evidence.",
+    example: "mm-harness run recipe.json",
+    helpText: `mm-harness run <recipe|recipe.json> [key=value ...] [flags]
+
+  Validate and execute a complete proof, then write summary, trace, diagnostics,
+  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
+  --domain <name>                    With --list: filter by recipe domain, e.g. perps or swap-bridge
+  --source <name>                    With --list: filter by library origin, e.g. metamask or perps
+  --sort <domain|name|library>       With --list: grouping/order (default: domain; JSON: name)
+  --describe                         Show one recipe's parameters, composed actions/recipes, and runnable command
+  --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
+  --proof                            Preflight behavioral proof bindings before planning/execution; runtime evidence is still required.
+
+Common overrides:
+  --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
+  --adapter <{adapters}>  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>)
+  --funding-request <absolute-file>  Original consented mutation request for external-mutation actions
+  --funding-preflight <absolute-file> Eligible funding preflight bound to the request bytes
+  --funding-release-proof <absolute-file> Exact release proof independently bound to funding eligibility
+  --funding-balance-proof <absolute-file> Exact balance proof and contained visible evidence chain
+  --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
+  --hud <show|hide>                  Recipe HUD: each node's intent drawn over the app on every adapter, headless included (default: show)
+
+Advanced integrations:
+  runtime: --cdp-port, --watcher-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 perps.release-market-search query=Bitcoin --plan --adapter mobile
+  mm-harness run recipe.json market=ETH --adapter extension`,
+    contract: {
+      options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, RUN_FUNDING, {
+        "--list": bool(),
+        "--domain": value(),
+        "--source": value(),
+        "--sort": value(["domain", "name", "library"]),
+        "--plan": bool(),
+        "--proof": bool(),
+        "--describe": bool(),
+        "--hud": value(["show", "hide"])
+      }),
+      positionals: [{ label: "recipe" }],
+      minimumPositionals: 1,
+      requiredUnless: ["--list"],
+      noPositionalsWith: ["--list"],
+      variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u },
+      missingPositionalAction: (example) => `List recipes: mm-harness run --list
+  Example: ${example}
+  More: mm-harness run --help`
+    }
   },
-  last: {
-    options: options(HELP, JSON, TARGET, {
-      "--runtime-dir": value()
-    })
+  {
+    name: "last",
+    summary: "Show the last significant command, verdict, timestamps, and evidence paths for this checkout.",
+    example: "mm-harness last --json",
+    helpText: `mm-harness last [flags]
+
+  Read the atomic per-checkout resumability journal. Discovery commands do not
+  replace it, and an interrupted process remains recorded as verdict=running.
+
+  --target <path>                    Checkout path (default: cwd)
+  --runtime-dir <dir>                Runtime dir containing command operation records
+  --json                             Machine-readable envelope
+
+Example:
+  mm-harness last --json`,
+    contract: {
+      options: options(HELP, JSON, TARGET, {
+        "--runtime-dir": value()
+      })
+    }
   },
-  doctor: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
-      "--fix": bool(),
-      "--expect-live": bool(),
-      "--print-ready": bool(),
-      "--all-devices": bool(),
-      "--action-manifest": value(),
-      "--port": value()
-    })
+  {
+    name: "doctor",
+    summary: "Readiness check for a checkout \u2014 no app launch. --fix repairs the overlay/runtime without launching.",
+    example: "mm-harness doctor",
+    helpText: `mm-harness doctor [flags]
+
+  Readiness check for a checkout \u2014 no app launch. Reports the same checkout view
+  status does \u2014 runtime-context isolation, resolved recipe libraries, and the last
+  applied wallet fixture \u2014 so there is no hunting for files.
+
+  --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
+  --expect-live                      Exit-coded liveness gate only (human verdict on stderr). Use without --print-ready when callers need pass/fail without a Farmslot indicator line
+  --print-ready                      Farmslot health_check mode: implies --expect-live and prints health.ready_indicator on stdout (extension/mobile: OK; core: ready)
+  --cdp-port <port>                  Extension CDP port for the liveness probe (env: CDP_PORT / RECIPE_CDP_PORT)
+  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). doctor reports the connected devices; it never gates on ambiguity.
+  --all-devices                      Mobile only: show every connected device instead of the slot-scoped target
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
+  --json                             Machine-readable output (incompatible with --print-ready)
+
+Example:
+  mm-harness doctor
+  mm-harness doctor --fix --json
+  mm-harness doctor --adapter extension --target /path/to/checkout --cdp-port 6662 --print-ready
+  mm-harness doctor --adapter mobile --target /path/to/checkout`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
+        "--fix": bool(),
+        "--expect-live": bool(),
+        "--print-ready": bool(),
+        "--all-devices": bool(),
+        "--action-manifest": value(),
+        "--port": value()
+      })
+    }
   },
-  check: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
-      "--base": value(),
-      "--profile": value(["fast", "full"]),
-      "--fix": bool(),
-      "--artifacts-dir": value()
-    }),
-    positionals: [{ label: "action", choices: ["diff"] }],
-    minimumPositionals: 1
+  {
+    name: "check",
+    summary: "Run bounded repo-local checks for an active git diff and write validation artifacts.",
+    example: "mm-harness check diff --profile fast",
+    helpText: `mm-harness check diff [flags]
+
+  Run bounded repo-local checks for the active git diff. Fast profile runs changed-file
+  ESLint, Prettier, and changed test files. Full profile also runs repo typecheck
+  when available. Does not launch an app or run a recipe.
+
+  --target <path>                    Checkout path (default: cwd)
+  --adapter <{adapters}>  Adapter label (auto-detected when possible)
+  --base <ref>                       Diff base (default: PR base, then remote HEAD, then repo fallback)
+  --profile <fast|full>              Validation depth (default: fast)
+  --fix                              Fix changed files, then validate them
+  --artifacts-dir <dir>              Write validation-summary.json/.md and per-check logs
+  --json                             Machine-readable envelope
+
+Example:
+  mm-harness check diff --fix --profile fast --artifacts-dir artifacts/validation
+  mm-harness check diff --profile full --json`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+        "--base": value(),
+        "--profile": value(["fast", "full"]),
+        "--fix": bool(),
+        "--artifacts-dir": value()
+      }),
+      positionals: [{ label: "action", choices: ["diff"] }],
+      minimumPositionals: 1
+    }
   },
-  "recipe-quality": {
-    options: options(HELP, JSON, ADAPTER, {
-      "--input": value(),
-      "--output": value(),
-      "--recipe": value(),
-      "--task": value(),
-      "--evidence": value(),
-      "--params": value(),
-      "--library": value(),
-      "--advisor": value(),
-      "--advisor-model": value(),
-      "--advisor-stages": value()
-    }),
-    positionals: [{ label: "action", choices: ["build", "plan", "advise", "advisor-status"] }]
+  {
+    name: "recipe-quality",
+    summary: "Build canonical recipe quality or request optional recipe advice.",
+    example: "mm-harness recipe-quality build --input compact.json --output artifacts/recipe-quality.json",
+    helpText: `mm-harness recipe-quality build|plan|advise|advisor-status [flags]
+
+  Build artifacts/recipe-quality.json from the compact fields a recipe-quality pass
+  produces (verdict + reasons + optional guidance/dimensions/findings/delta/training).
+  The artifact is validated against the RecipeQualityArtifact schema before it is
+  written \u2014 an invalid input never reaches disk. Shorthand without "build" is
+  also accepted when --input/--output are present.
+
+  Apply the quality bar from mm-harness help to the real graph and
+  evidence, then use this command to build the canonical artifact from that
+  compact verdict. An optional independent reviewer may still critique it.
+
+  --input <compact.json>   Compact verdict JSON: { "verdict": "pass|warn|fail", "reasons": [..],
+                             "betterVersionGuidance"?: [..], "dimensions"?: {..}, "trainingFields"?: {..}, \u2026 }
+  --output <path>          Where to write the built artifact (parent dirs created)
+  --json                   Machine-readable envelope { status, outputPath, artifact }
+
+  Exit: 0 built \xB7 2 missing/unreadable args \xB7 5 invalid input (teaching escape names the invalid field).
+
+Optional advice:
+  advisor-status --json
+    Resolve saved settings and overrides without reading tasks or calling a model.
+  plan --task <task.json> --adapter <{adapters}> --advisor typesafe
+    Assess each acceptance criterion before a recipe exists. Task JSON contains
+    acceptanceCriteria: ["criterion", "..."] (1\u201320 entries), with optional title/description.
+    Returns known candidate refs for reuse/composition, or an explicit discovery gap.
+  advise --recipe <recipe.json> --task <TASK.md> --adapter <{adapters}>
+    --advisor <provider|off> Override saved policy for this task (currently: typesafe)
+    --advisor-model <model> Override the provider default model or alias
+    --advisor-stages <csv>   Select plan,draft,evidence (saved/default: plan)
+    --evidence <file.json>    Explicit trace, summary, or evidence metadata to review
+    --params <json>          Root recipe parameter values
+    --library <name=path>    Resolve the same library sources as run (repeatable)
+    --output <advice.json>   Optional separate advisory artifact
+
+  Precedence: explicit CLI > MM_HARNESS_ADVISOR[_MODEL|_STAGES] > advisor settings > disabled.
+  Set MM_HARNESS_ADVISOR to a provider or off for a Farmslot run. A key never enables advice.
+  Saved settings only run selected stages; an explicit --advisor call can request a stage directly.
+  --advisor off disables calls regardless of saved settings. No disabled advice artifact is written.
+  TypeSafe uses TYPESAFE_API_KEY. Missing keys skip advice; provider failures report unavailable.
+  Results record provider, requestedModel, and the model that answered.
+  Advice never changes recipe execution, canonical quality, or existing exit status.
+  Input must be statically valid. Context beyond the bound is skipped, never truncated.
+
+Example:
+  mm-harness recipe-quality build --input compact.json --output artifacts/recipe-quality.json
+  mm-harness recipe-quality --input compact.json --output artifacts/recipe-quality.json
+  mm-harness recipe-quality build --input compact.json --output artifacts/recipe-quality.json --json
+  mm-harness recipe-quality advise --recipe artifacts/recipe.json --task TASK.md --adapter extension --advisor typesafe --output artifacts/recipe-advice.json --json
+  mm-harness recipe-quality plan --task task.json --adapter extension --advisor typesafe --output artifacts/recipe-plan.json --json`,
+    contract: {
+      options: options(HELP, JSON, ADAPTER, {
+        "--input": value(),
+        "--output": value(),
+        "--recipe": value(),
+        "--task": value(),
+        "--evidence": value(),
+        "--params": value(),
+        "--library": value(),
+        "--advisor": value(),
+        "--advisor-model": value(),
+        "--advisor-stages": value()
+      }),
+      positionals: [{ label: "action", choices: ["build", "plan", "advise", "advisor-status"] }]
+    }
   },
-  provision: {
-    options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, RUNWAY, {
-      "--platform": value(["ios"]),
-      "--device-platform": value(["ios"])
-    }),
-    positionals: [
-      { label: "source", choices: ["runway", "ios"] },
-      { label: "platform", choices: ["ios"] }
-    ]
+  {
+    name: "provision",
+    summary: "Install the cached Runway iOS dev client on a prepared mobile slot (no deps, no Metro).",
+    example: "mm-harness provision runway ios --adapter mobile",
+    helpText: `mm-harness provision [runway ios] [flags]
+
+  Install the cached Runway iOS dev client on the slot simulator. This is a thin
+  provisioning path only: artifact cache + simulator create + simctl install.
+  JavaScript dependencies and Metro remain dispatch-time launch concerns.
+
+  --adapter <{adapters}>  Target adapter (mobile supported; the others teach)
+  --target <path>                    Slot checkout path (default: cwd)
+  --platform <ios>                   Platform (default ios)
+  --simulator <name|udid>            Override agentic-runtime.json simulator (alias: --device)
+  --device <name|udid>               Alias for --simulator
+  --slot <id>                        Farm slot id recorded in the provision baseline
+  --watcher-port <port>              Farm Metro/watcher port carried through context and Next:
+  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
+  --runtime <id>                     iOS runtime id used if simulator must be created
+  --device-type <id>                 Device type id used if simulator must be created
+  --branch <ref>                     Probe this ref before default branch
+  --default-branch <ref>             Fallback ref (default main)
+  --run <id>                         Exact GitHub Actions run id
+  --cache-root <dir>                 Override shared runway cache root
+  --force                            Reinstall even when the app is already present
+  --resolve-only                     Resolve artifact metadata only; no simulator/cache/install
+  --json                             Machine-readable envelope; progress stays stderr
+
+Example:
+  mm-harness provision runway ios --adapter mobile --target /path/to/slot
+  mm-harness provision runway ios --adapter mobile --slot scratch-1 --runtime-dir temp/recipe/runtime-8081
+  mm-harness provision runway ios --run 28676856835 --resolve-only --json`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, RUNWAY, {
+        "--platform": value(["ios"]),
+        "--device-platform": value(["ios"])
+      }),
+      positionals: [
+        { label: "source", choices: ["runway", "ios"] },
+        { label: "platform", choices: ["ios"] }
+      ]
+    }
   },
-  install: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNWAY, {
-      "--runway": bool()
-    }),
-    allowPassthrough: true
+  {
+    name: "install",
+    summary: "Install the per-checkout runtime overlay, or --runway to install a cached mobile dev client.",
+    example: "mm-harness install",
+    helpText: `mm-harness install [flags]
+
+  Install the per-checkout runtime overlay (for CI / agents).
+  Add --runway on a mobile slot to install the cached Runway iOS dev client only:
+  artifact cache + simulator create + simctl install. JavaScript dependencies
+  and Metro remain dispatch-time launch concerns.
+
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --runway                           Thin mobile Runway artifact install instead of overlay install
+  --platform <ios>                   Runway platform (default ios)
+  --simulator <name|udid>            Override agentic-runtime.json simulator
+  --runtime <id>                     iOS runtime id used if simulator must be created
+  --device-type <id>                 Device type id used if simulator must be created
+  --branch <ref>                     Probe this ref before default branch
+  --default-branch <ref>             Fallback ref (default main)
+  --run <id>                         Exact GitHub Actions run id
+  --cache-root <dir>                 Override shared runway cache root
+  --force                            Reinstall even when the app is already present
+  --resolve-only                     Runway metadata only; no simulator/cache/install
+
+Example:
+  mm-harness install
+  mm-harness install --adapter extension --target /path/to/checkout
+  mm-harness install --runway --adapter mobile --target /path/to/slot`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNWAY, {
+        "--runway": bool()
+      }),
+      allowPassthrough: true
+    }
   },
-  verify: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, RUNTIME_PORTS),
-    allowPassthrough: true
+  {
+    name: "verify",
+    summary: "Check the overlay/runtime is present and healthy (no launch).",
+    example: "mm-harness verify",
+    helpText: `mm-harness verify [flags]
+
+  Check the runtime overlay is present and healthy (no app launch).
+  Extension live checks infer the checkout CDP port from runtime context,
+  pool, or slot suffix when --cdp-port is omitted.
+
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness verify
+  mm-harness verify --adapter core --target /path/to/checkout`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, RUNTIME_PORTS),
+      allowPassthrough: true
+    }
   },
-  cleanup: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM),
-    allowPassthrough: true
+  {
+    name: "cleanup",
+    summary: "Remove the installed overlay and restore the checkout.",
+    example: "mm-harness cleanup",
+    helpText: `mm-harness cleanup [flags]
+
+  Remove the installed overlay and restore the checkout.
+
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+
+Example:
+  mm-harness cleanup
+  mm-harness cleanup --adapter mobile --target /path/to/checkout`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM),
+      allowPassthrough: true
+    }
   },
-  launch: {
-    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
-      "--build": bool(),
-      "--clear-metro": bool(),
-      "--verify": bool(),
-      "--runway": bool(),
-      "--watch": bool(),
-      "--surface": value(["fullscreen", "sidepanel"]),
-      "--sidepanel": bool(),
-      "--fullscreen": bool(),
-      "--url": value(),
-      "--heal": value(["off", "infra-only", "auto"]),
-      "--remote-flag": value(),
-      "--signer": value(["extension", "injected"]),
-      "--account": value(),
-      "--fresh-profile": bool(),
-      "--headless": bool(),
-      "--headful": bool(),
-      "--slow-mo": value(),
-      "--network": value(["testnet", "mainnet"]),
-      "--mainnet-confirmation": value()
-    }),
-    positionals: [{ label: "platform", choices: ["ios", "android"] }]
+  {
+    name: "launch",
+    summary: "Launch the app and adapter dev server, auto-ensuring the runtime overlay first. Mobile: ios|android required.",
+    example: "mm-harness launch ios",
+    helpText: `mm-harness launch [ios|android] [flags]
+
+  Launch the app \u2014 quick relaunch by default; --build for a full native/webpack build.
+  Mobile: target is MANDATORY (ios | android). Extension: no target (--fullscreen default;
+  --sidepanel to override). core is headless (teaching error \u2014 use verify/run).
+  Terminal: starts or reuses the slot browser (visible by default) against the slot dev server.
+  Extension quick launch REUSES a healthy live runtime (reload in place, no rebuild);
+  --build is the escape hatch that always clean-builds + relaunches a fresh runtime.
+
+  --build                            Full production-like build + relaunch (escape hatch; skips extension reuse)
+  --clear-metro                      Mobile only: clear Metro's transform cache before launch
+  --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
+  --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
+  --watch                            Persistent webpack watcher then relaunch (extension only)
+  --surface <fullscreen|sidepanel>   Extension display mode (default: fullscreen)
+  --sidepanel | --fullscreen         Legacy aliases for --surface
+  --url <dapp-url>                    Open a dapp beside the sidepanel (default: MetaMask test dapp)
+  --remote-flag <KEY=VALUE[,...]>    Pin remote feature flags. VALUE is a variant name (treatment),
+                                     true/false, or JSON. Mobile applies it through
+                                     RemoteFeatureFlagController once the bridge is ready and fails the
+                                     launch if it does not read back; Extension pins it into the per-run
+                                     dist snapshot manifest (so it skips the reuse fast path).
+  --heal <off|infra-only|auto>       Healing policy (default auto); bounds always enforced
+  --device <udid|name>               Target simulator/device (env: IOS_SIMULATOR / ADB_SERIAL)
+  --cdp-port <port>                  Extension CDP port (env: CDP_PORT / RECIPE_CDP_PORT)
+  --watcher-port <port>              Metro/webpack port (env: WATCHER_PORT / METRO_PORT)
+  --signer <extension|injected>      Terminal: MetaMask extension (default) or the injected test wallet
+  --account <name>                   Terminal: wallet-fixture account (default dev1)
+  --fresh-profile                    Terminal: start from a new browser profile
+  --headless                         Terminal: hide the browser (env: TERMINAL_HEADLESS=1); default is a
+                                     visible window placed per slot (--headful is accepted as the default)
+  --slow-mo <ms>                     Terminal: pause before each UI action (env: TERMINAL_SLOW_MO; default 0)
+  --network <testnet|mainnet>         Terminal: venue the slot dev server serves (default testnet)
+  --mainnet-confirmation <REAL_FUNDS> Terminal: required with --network mainnet (real funds)
+                                     Terminal flags are rejected for other adapters. The terminal launch
+                                     refuses unless the farm next dev server on --watcher-port forces
+                                     Hyperliquid testnet, or --network mainnet --mainnet-confirmation REAL_FUNDS
+                                     is passed (a recipe launch node carries network/mainnet_confirmation).
+  --adapter <mobile|extension|terminal> Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable summary (recovered[] / mutations[] / phase)
+  --json-stream                      Line-flushed JSONL progress + terminal event
+
+Example:
+  mm-harness launch ios
+  mm-harness launch android --clear-metro --verify
+  mm-harness launch ios --build
+  mm-harness launch --verify --json
+  mm-harness launch --remote-flag perpsTAT3938AbtestScreenVsBottomSheet=treatment`,
+    contract: {
+      options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
+        "--build": bool(),
+        "--clear-metro": bool(),
+        "--verify": bool(),
+        "--runway": bool(),
+        "--watch": bool(),
+        "--surface": value(["fullscreen", "sidepanel"]),
+        "--sidepanel": bool(),
+        "--fullscreen": bool(),
+        "--url": value(),
+        "--heal": value(["off", "infra-only", "auto"]),
+        "--remote-flag": value(),
+        "--signer": value(["extension", "injected"]),
+        "--account": value(),
+        "--fresh-profile": bool(),
+        "--headless": bool(),
+        "--headful": bool(),
+        "--slow-mo": value(),
+        "--network": value(["testnet", "mainnet"]),
+        "--mainnet-confirmation": value()
+      }),
+      positionals: [{ label: "platform", choices: ["ios", "android"] }]
+    }
   },
-  "runtime-launch": {
-    options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, MOBILE_PLATFORM, {
-      "--cdp-port": value(),
-      "--chrome-user-data-dir": value(),
-      "--reset-profile": bool(),
-      "--preserve-profile": bool(),
-      "--artifacts-dir": value(),
-      "--start-watch": bool(),
-      "--build-lavamoat": bool(),
-      "--remote-flag": value(),
-      "--artifact-file": value(),
-      "--artifact-version": value(),
-      "--artifact-build-id": value(),
-      "--artifact-package-id": value(),
-      "--artifact-sha256": value(),
-      "--artifact-cache": value()
-    })
+  {
+    name: "runtime-launch",
+    summary: "Launch and verify an Extension runtime or local Android release artifact.",
+    example: "mm-harness runtime-launch --adapter extension --target <checkout> --cdp-port 9222 --artifact-file <zip> --artifact-version <X.Y.Z> --artifact-sha256 <digest>",
+    helpText: `mm-harness runtime-launch --adapter <extension|mobile> --target <checkout> [flags]
+
+  Verify and run an artifact already downloaded by the validation skill. The
+  harness performs no network acquisition. Extension ZIPs run through the
+  packaged browser/CDP path; Android APKs install to one explicitly named device.
+
+  --artifact-file <path>             Artifact downloaded by the validation skill
+  --artifact-version <X.Y.Z>         Expected manifest or Android version name
+  --artifact-build-id <id>           Android version code
+  --artifact-package-id <id>         Android application ID
+  --artifact-sha256 <digest>         Trusted SHA-256 from the acquisition step
+  --artifact-cache <dir>             Extension artifact cache root
+  --platform <android>               Mobile platform (downloaded iOS is unsupported)
+  --device <serial>                  Explicit Android device serial
+  --cdp-port <port>                  Extension CDP port
+  --chrome-user-data-dir <dir>       Isolated Chrome profile path
+  --reset-profile                    Explicitly clear that profile; default preserves wallet state
+  --artifacts-dir <dir>              Validation evidence directory
+  --start-watch                      Build through the checkout watcher
+  --build-lavamoat                   Build through the production-like path
+  --remote-flag <KEY=VARIANT>        Pin checkout snapshot flags (not allowed for artifacts)
+  --json                             Machine-readable terminal report
+
+Example:
+  mm-harness runtime-launch --adapter extension --target /path/to/checkout --cdp-port 9222 --artifact-file /path/to/metamask-chrome-X.Y.Z.zip --artifact-version X.Y.Z --artifact-sha256 <digest>
+  mm-harness runtime-launch --adapter mobile --platform android --target /path/to/checkout --device <serial> --artifact-file /path/to/app.apk --artifact-version X.Y.Z --artifact-build-id <code> --artifact-package-id io.metamask --artifact-sha256 <digest>`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, MOBILE_PLATFORM, {
+        "--cdp-port": value(),
+        "--chrome-user-data-dir": value(),
+        "--reset-profile": bool(),
+        "--preserve-profile": bool(),
+        "--artifacts-dir": value(),
+        "--start-watch": bool(),
+        "--build-lavamoat": bool(),
+        "--remote-flag": value(),
+        "--artifact-file": value(),
+        "--artifact-version": value(),
+        "--artifact-build-id": value(),
+        "--artifact-package-id": value(),
+        "--artifact-sha256": value(),
+        "--artifact-cache": value()
+      })
+    }
   },
-  logs: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
-      "--full": bool(),
-      "--window": bool(),
-      "--events": value(),
-      "--source": value()
-    })
+  {
+    name: "logs",
+    summary: "Tail Metro/webpack + app logs for the active checkout.",
+    example: "mm-harness logs",
+    helpText: `mm-harness logs [flags]
+
+  Tail Metro/webpack + app logs for the active checkout.
+  Teaching error if nothing is running (points at launch).
+
+  --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
+  --window                           (Re)open the read-only tmux tail window for the resolved dev-server port (leaves the process untouched)
+  --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
+  --source <label>                   Log source per adapter \u2014 mobile: metro|app;
+                                     extension: extension|dapp|webpack|watcher|rebuild.
+                                     Core is headless (teaching error).
+  --adapter <{adapters}>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness logs
+  mm-harness logs --full
+  mm-harness logs --window`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+        "--full": bool(),
+        "--window": bool(),
+        "--events": value(),
+        "--source": value()
+      })
+    }
   },
-  debug: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
-      "--worker": bool(),
-      "--dev-menu": bool(),
-      "--no-open": bool()
-    })
+  {
+    name: "debug",
+    summary: "Open the debug console \u2014 extension: Chrome DevTools via CDP; mobile: RN DevTools.",
+    example: "mm-harness debug",
+    helpText: `mm-harness debug [flags]
+
+  Open the debug console \u2014 extension: Chrome DevTools via CDP; mobile: RN DevTools.
+
+  --worker                           Extension service-worker DevTools
+  --dev-menu                         Mobile RN developer menu
+  --no-open                          Resolve target/method/endpoint without opening a UI
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness debug
+  mm-harness debug --worker`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+        "--worker": bool(),
+        "--dev-menu": bool(),
+        "--no-open": bool()
+      })
+    }
   },
-  reload: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM)
+  {
+    name: "reload",
+    summary: "Reload the connected Mobile or Extension runtime without restarting its dev server.",
+    example: "mm-harness reload",
+    helpText: `mm-harness reload [flags]
+
+  Mobile broadcasts the same reload command as Metro's interactive r key.
+  Extension refreshes its loaded UI in place over CDP. Core is headless.
+
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness reload`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM)
+    }
   },
-  update: {
-    options: options(HELP, JSON, { "--check": bool() })
+  {
+    name: "update",
+    summary: "Update the installed mm-harness to the published latest (--check reports only; --json = {current, latest, updateAvailable}).",
+    example: "mm-harness update",
+    helpText: `mm-harness update [flags]
+
+  Update the globally-installed mm-harness to the npm registry's latest.
+  Bare form upgrades (npm i -g @deeeed/metamask-harness@latest) and prints old \u2192 new;
+  already-current exits 0.
+
+  --check                            Report only \u2014 exit 0 up-to-date / exit 1 update available (no install)
+  --json                             Machine-readable { current, latest, updateAvailable }
+
+  A passive once-a-day nudge also prints one stderr line when a newer version exists.
+  Silence it with MM_HARNESS_NO_UPDATE_CHECK=1 (auto-off in CI).
+
+Example:
+  mm-harness update
+  mm-harness update --check --json`,
+    contract: {
+      options: options(HELP, JSON, { "--check": bool() })
+    }
   },
-  pin: {
-    options: options(HELP, JSON)
+  {
+    name: "pin",
+    summary: "Copy this installed mm-harness into an immutable, versioned store and print the copy for a task to run, so a later global upgrade cannot change a running task.",
+    example: "mm-harness pin",
+    helpText: `mm-harness pin [flags]
+
+  Copies the installed mm-harness running this command into an immutable,
+  versioned store (~/.local/share/mm-harness/pins/<version>-<hash>/; APFS clone
+  where available) and prints the copy's executable. A task records that path,
+  so \`npm i -g\` upgrading the global install never changes the harness a running
+  task runs. Idempotent: the same install returns the same pin. A source checkout
+  (MM_HARNESS_BIN) or an existing pin is printed as is.
+
+  --json                             Machine-readable { version, source, executable, pinned, created }
+
+  MM_HARNESS_PIN_ROOT overrides the store location.
+
+Example:
+  mm-harness pin
+  mm-harness pin --json`,
+    contract: {
+      options: options(HELP, JSON)
+    }
   },
-  fixtures: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, {
-      "--from": value(),
-      "--dev": bool(),
-      "--force": bool(),
-      "--fixture": value(),
-      "--out": value(),
-      "--state": value(),
-      "--cdp-port": value(),
-      "--extension-dir": value(),
-      "--extension-id-file": value(),
-      "--action-manifest": value(),
-      "--remote-flag": value()
-    }),
-    positionals: [{ label: "action", choices: ["init", "sync", "set", "reset", "generate", "finalize"] }],
-    minimumPositionals: 0
-  }
-};
-function optionValues(args, name) {
-  const values = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--") break;
-    if (arg === name && args[index + 1] !== void 0) values.push(args[index += 1]);
-    else if (arg.startsWith(`${name}=`)) values.push(arg.slice(name.length + 1));
+  {
+    name: "fixtures",
+    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / reset / generate / finalize.",
+    example: "mm-harness fixtures set",
+    helpText: `mm-harness fixtures [<init|sync|set|reset|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.
+  set        Apply the canonical fixture (SRP/password/accounts); the password is
+             read FROM the fixture, never typed.
+  reset      Delete the current Mobile/Extension wallet, then apply and validate
+             the canonical fixture from a clean state.
+  generate   Render the extension fixture-state.json from a wallet fixture, for
+             pre-launch profile prefill (extension-only). Requires --fixture and --out.
+  finalize   Seed account labels/selection into the LIVE extension over CDP and
+             validate parity (extension-only, post-launch). Requires --fixture,
+             --state, --cdp-port, --extension-dir.
+  Want different accounts? Edit the fixture file directly:
+    <checkout>/temp/recipe/runtime/wallet-fixture.json
+
+  --from <path>                       Existing wallet fixture source (init)
+  --dev                               Create a disposable public test wallet (init)
+  --force                             Replace an existing canonical fixture (init)
+  --fixture <path>                   Wallet fixture path (generate/finalize input; agent override for set/sync \u2014 env: RECIPE_WALLET_FIXTURE)
+  --out <path>                       generate: output fixture-state.json; finalize: optional validation report
+  --state <path>                     finalize: the pre-launch fixture-state.json to seed
+  --cdp-port <port>                  finalize: CDP port of the running extension
+  --extension-dir <path>             finalize: loaded extension dist (e.g. dist/chrome)
+  --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
+  --action-manifest <path>           Extension set: override the wallet action manifest
+  --remote-flag <KEY=VALUE[,...]>    set/reset: one-run override layered over the fixture's remoteFeatureFlags
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --device <udid|serial|name>        Mobile only: target this device for sync/set
+  --json                             Machine-readable output
+
+Example:
+  mm-harness fixtures init --from /secure/path/wallet-fixture.json
+  mm-harness fixtures init --dev
+  mm-harness fixtures sync
+  mm-harness fixtures set
+  mm-harness fixtures reset
+  mm-harness fixtures generate --fixture wallet-fixture.json --out fixture-state.json
+  mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`,
+    contract: {
+      options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, {
+        "--from": value(),
+        "--dev": bool(),
+        "--force": bool(),
+        "--fixture": value(),
+        "--out": value(),
+        "--state": value(),
+        "--cdp-port": value(),
+        "--extension-dir": value(),
+        "--extension-id-file": value(),
+        "--action-manifest": value(),
+        "--remote-flag": value()
+      }),
+      positionals: [{ label: "action", choices: ["init", "sync", "set", "reset", "generate", "finalize"] }],
+      minimumPositionals: 0
+    }
   }
-  return values;
-}
+];
+const HIDDEN_COMMANDS = [
+  "completion-candidates",
+  "runtime-health",
+  "runtime-decision",
+  "resolve-extension",
+  "ensure-ready",
+  "self-test",
+  "completions"
+];
 const LIBRARY_ADAPTERS = {
   terminal: { title: "MetaMask Web Terminal", repository: "MetaMask/experimental-metamask-recipe-terminal" }
 };
 const quoteArg = (value2) => /^[A-Za-z0-9_./:=@%+-]+$/u.test(value2) ? value2 : `'${value2.replaceAll("'", `'\\''`)}'`;
-function missingAdapterLibrary(command, optionName, id, tokens) {
+function explainMissingAdapterLibrary({
+  command,
+  option: optionName,
+  value: id,
+  tokens
+}) {
   const library = LIBRARY_ADAPTERS[id];
-  if (!library || optionName !== "--adapter" && optionName !== "--platform") return void 0;
+  if (!library || optionName !== "--adapter" && optionName !== "--platform") return null;
   const current = operatorLibraryEnv().RECIPE_LIBRARY_PATH;
   const rerun = (libraryPath) => `RECIPE_LIBRARY_PATH=${quoteArg(libraryPath)} mm-harness ${[command, ...tokens].map(quoteArg).join(" ")}`;
   const revision = `a revision whose recipe-library.json declares adapters.${id}`;
@@ -472,292 +1461,11 @@ function missingAdapterLibrary(command, optionName, id, tokens) {
     userAction: `Keep ${optionName} ${id} and put that library, at ${revision}, on RECIPE_LIBRARY_PATH (git clone https://github.com/${library.repository}.git ${checkout}): ${rerun(current ? `${id}=${checkout}:${current}` : `${id}=${checkout}`)}`
   };
 }
-function validatePublicInvocation(argv, examples = {}) {
-  const token = argv[0];
-  if (!token || token === "--help" || token === "-h" || token === "--version" || token === "-v") return null;
-  const resolved = resolveCommand(token);
-  if (!resolved) {
-    const names = publicCommandTokens();
-    const suggestion = closest(token, names);
-    if (token.startsWith("-")) {
-      return {
-        code: "CLI_UNKNOWN_OPTION",
-        command: "mm-harness",
-        message: `unknown top-level option '${token}'. Valid top-level options: --help, --version.`,
-        userAction: actionFor(token, closest(token, ["--help", "--version"]), "mm-harness --help")
-      };
-    }
-    return {
-      code: "CLI_UNKNOWN_COMMAND",
-      command: token,
-      message: `unknown command '${token}'. Valid commands: ${Object.keys(PUBLIC_COMMAND_CONTRACTS).join(", ")}.`,
-      userAction: actionFor(token, suggestion, suggestion ? exampleFor(resolveCommand(suggestion)?.name, examples) : "mm-harness --help")
-    };
-  }
-  const { name, contract } = resolved;
-  const tokens = argv.slice(1);
-  if (name === "checklist" && tokens[0] === "mark" && tokens[1] && !tokens[1].startsWith("-") && tokens[2] === "sub") return null;
-  const positionals = [];
-  const seenOptions = /* @__PURE__ */ new Set();
-  const validOptions = Object.keys(contract.options);
-  for (let index = 0; index < tokens.length; index += 1) {
-    const argument = tokens[index] ?? "";
-    if (argument === "--") {
-      if (!contract.allowPassthrough) {
-        return usageFailure("CLI_UNEXPECTED_PASSTHROUGH", name, "this command does not accept `--` passthrough.", contract, examples);
-      }
-      break;
-    }
-    if (!argument.startsWith("-") || argument === "-") {
-      positionals.push(argument);
-      continue;
-    }
-    const equals = argument.indexOf("=");
-    const optionName = equals === -1 ? argument : argument.slice(0, equals);
-    const inlineValue = equals === -1 ? void 0 : argument.slice(equals + 1);
-    const spec = contract.options[optionName];
-    if (!spec) {
-      const suggestion = REMOVED_OPTION_REPLACEMENTS[optionName] ?? closest(optionName, validOptions);
-      return {
-        code: "CLI_UNKNOWN_OPTION",
-        command: name,
-        message: `unknown option '${optionName}'.`,
-        userAction: actionFor(optionName, suggestion, exampleFor(name, examples))
-      };
-    }
-    seenOptions.add(optionName);
-    if (spec.kind === "boolean") {
-      if (inlineValue !== void 0) {
-        return usageFailure("CLI_INVALID_OPTION_VALUE", name, `${optionName} is a flag and does not take a value.`, contract, examples);
-      }
-      continue;
-    }
-    if (spec.kind === "optional-value" && inlineValue === void 0) continue;
-    const optionValue = inlineValue ?? tokens[index + 1];
-    const nextTokenIsOption = inlineValue === void 0 && (optionValue === "-h" || optionValue === "--" || optionValue?.startsWith("--"));
-    if (optionValue === void 0 || spec.kind === "value" && optionValue === "" || nextTokenIsOption) {
-      return usageFailure("CLI_MISSING_OPTION_VALUE", name, `${optionName} requires a value.`, contract, examples);
-    }
-    if (inlineValue === void 0) index += 1;
-    const choices = typeof spec.choices === "function" ? spec.choices(tokens) : spec.choices;
-    if (choices && !choices.includes(optionValue)) {
-      const missing = missingAdapterLibrary(name, optionName, optionValue, tokens);
-      if (missing) return missing;
-      const suggestion = closest(optionValue, choices);
-      return {
-        code: "CLI_INVALID_OPTION_VALUE",
-        command: name,
-        message: `${optionName} must be ${formatChoiceList(choices)}; received '${optionValue}'.`,
-        userAction: actionFor(optionValue, suggestion, exampleFor(name, examples))
-      };
-    }
-  }
-  if (seenOptions.has("--help") || seenOptions.has("-h")) return null;
-  if (name === "checklist") {
-    const action = positionals[0];
-    const markOnly = [
-      "--mark-last",
-      "--already-fixed",
-      "--no-self-review",
-      "--skip-learnings",
-      "--skip-checklist",
-      "--reason",
-      "--checklist",
-      "--signal"
-    ];
-    const closeoutOnly = [
-      "--json",
-      "--share",
-      "--config",
-      "--destination",
-      "--metadata"
-    ];
-    const invalidOption = (action === "mark" ? closeoutOnly : markOnly).find(
-      (option) => seenOptions.has(option)
-    );
-    if (invalidOption && (action === "mark" || action === "closeout")) {
-      return usageFailure(
-        "CLI_UNKNOWN_OPTION",
-        name,
-        `${invalidOption} is not valid with checklist ${action}.`,
-        contract,
-        examples
-      );
-    }
-    if (action === "mark" && positionals.length < 3) {
-      return missingPositionalFailure(
-        name,
-        "checklist mark requires <step>.",
-        contract,
-        examples
-      );
-    }
-    if (action === "closeout" && positionals.length > 2) {
-      return usageFailure(
-        "CLI_EXCESS_POSITIONAL",
-        name,
-        `unexpected positional '${positionals[2]}'; checklist closeout accepts only <task-dir>.`,
-        contract,
-        examples
-      );
-    }
-  }
-  if (name === "execution-template") {
-    const action = positionals[0];
-    const validAction = ["list", "materialize", "lint", "new"].includes(action ?? "");
-    const targetCount = Math.max(0, positionals.length - 1);
-    if (validAction && action === "list" && targetCount > 0) {
-      return usageFailure(
-        "CLI_EXCESS_POSITIONAL",
-        name,
-        `execution-template list does not accept positional '${positionals[1]}'.`,
-        contract,
-        examples
-      );
-    }
-    if (validAction && (action === "materialize" || action === "lint" || action === "new") && targetCount === 0) {
-      return missingPositionalFailure(
-        name,
-        `execution-template ${action} requires <target>.`,
-        contract,
-        examples
-      );
-    }
-    if (validAction && targetCount > 1) {
-      return usageFailure(
-        "CLI_EXCESS_POSITIONAL",
-        name,
-        `unexpected positional '${positionals[2]}'; execution-template ${action} accepts one <target>.`,
-        contract,
-        examples
-      );
-    }
-  }
-  if (contract.leadingPositionals && !contract.requiredUnless?.some((option) => seenOptions.has(option)) && tokens.slice(0, contract.leadingPositionals).some((argument) => !argument || argument.startsWith("-"))) {
-    const missing = contract.positionals?.[0]?.label ?? "argument";
-    return missingPositionalFailure(name, `${name} requires <${missing}> first.`, contract, examples);
-  }
-  const forbiddingOption = contract.noPositionalsWith?.find((option) => seenOptions.has(option));
-  if (forbiddingOption && positionals.length > 0) {
-    return usageFailure(
-      "CLI_EXCESS_POSITIONAL",
-      name,
-      `${forbiddingOption} does not accept positional '${positionals[0]}'.`,
-      contract,
-      examples
-    );
-  }
-  const minimum = contract.requiredUnless?.some((option) => seenOptions.has(option)) ? 0 : contract.minimumPositionals ?? 0;
-  if (positionals.length < minimum) {
-    const missingSpec = contract.positionals?.[positionals.length];
-    const missing = missingSpec?.label ?? "argument";
-    const valid = missingSpec?.choices?.length ? ` Choose one: ${missingSpec.choices.join("|")}.` : "";
-    const usage = contract.usage ? ` Usage: ${contract.usage}.` : "";
-    return missingPositionalFailure(name, `missing required <${missing}>.${valid}${usage}`, contract, examples);
-  }
-  const fixed = contract.positionals ?? [];
-  for (let index = 0; index < Math.min(positionals.length, fixed.length); index += 1) {
-    const invalid = invalidPositional(positionals[index] ?? "", fixed[index]);
-    if (invalid) return positionalFailure(name, positionals[index] ?? "", fixed[index], contract, examples);
-  }
-  if (positionals.length > fixed.length && !contract.variadic) {
-    const unexpected = positionals[fixed.length] ?? "";
-    return usageFailure("CLI_EXCESS_POSITIONAL", name, `unexpected positional '${unexpected}'; this command accepts ${formatPositionals(contract)}.`, contract, examples);
-  }
-  if (contract.variadic) {
-    for (const positional of positionals.slice(fixed.length)) {
-      if (invalidPositional(positional, contract.variadic)) {
-        return positionalFailure(name, positional, contract.variadic, contract, examples);
-      }
-    }
-  }
-  return null;
-}
-function publicCommandTokens() {
-  const tokens = [];
-  for (const [name, contract] of Object.entries(PUBLIC_COMMAND_CONTRACTS)) {
-    tokens.push(name, ...contract.aliases ?? []);
-  }
-  return tokens;
-}
-function publicCommandNames() {
-  return Object.keys(PUBLIC_COMMAND_CONTRACTS);
-}
-function resolveCommand(token) {
-  const direct = PUBLIC_COMMAND_CONTRACTS[token];
-  if (direct) return { name: token, contract: direct };
-  for (const [name, contract] of Object.entries(PUBLIC_COMMAND_CONTRACTS)) {
-    if (contract.aliases?.includes(token)) return { name, contract };
-  }
-  return null;
-}
-function usageFailure(code, command, message, _contract, examples) {
-  return {
-    code,
-    command,
-    message,
-    userAction: `Try: ${exampleFor(command, examples)}. Inspect options: mm-harness ${command} --help`
-  };
-}
-function missingPositionalFailure(command, message, contract, examples) {
-  if (command === "run") {
-    return {
-      code: "CLI_MISSING_POSITIONAL",
-      command,
-      message,
-      userAction: `List recipes: mm-harness run --list
-  Example: ${exampleFor(command, examples)}
-  More: mm-harness run --help`
-    };
-  }
-  if (command === "call") {
-    return {
-      code: "CLI_MISSING_POSITIONAL",
-      command,
-      message,
-      userAction: `List actions: mm-harness call --list
-  Example: ${exampleFor(command, examples)}
-  More: mm-harness call --help`
-    };
-  }
-  return usageFailure("CLI_MISSING_POSITIONAL", command, message, contract, examples);
-}
-function positionalFailure(command, received, spec, _contract, examples) {
-  const valid = spec.validDescription ?? (spec.choices ? spec.choices.join(", ") : spec.pattern || spec.validate ? `a valid <${spec.label}>` : `<${spec.label}>`);
-  const suggestion = spec.choices ? closest(received, spec.choices) : void 0;
-  return {
-    code: "CLI_INVALID_POSITIONAL",
-    command,
-    message: `invalid <${spec.label}> '${received}'. Valid values: ${valid}.`,
-    userAction: actionFor(received, suggestion, exampleFor(command, examples))
-  };
-}
-function invalidPositional(value2, spec) {
-  if (!spec) return true;
-  if (spec.choices && !spec.choices.includes(value2)) return true;
-  if (spec.validate && !spec.validate(value2)) return true;
-  return Boolean(spec.pattern && !spec.pattern.test(value2));
-}
-function formatChoiceList(choices) {
-  if (choices.length === 1) return choices[0] ?? "";
-  if (choices.length === 2) return `${choices[0]} or ${choices[1]}`;
-  return `${choices.slice(0, -1).join(", ")}, or ${choices[choices.length - 1]}`;
-}
-function formatPositionals(contract) {
-  const fixed = (contract.positionals ?? []).map((spec) => `<${spec.label}>`);
-  if (contract.variadic) fixed.push(`[<${contract.variadic.label}> ...]`);
-  return fixed.length > 0 ? fixed.join(" ") : "no positionals";
-}
-function actionFor(received, suggestion, example) {
-  return `${suggestion ? `Did you mean '${suggestion}' instead of '${received}'? ` : ""}Try: ${example}`;
-}
-function exampleFor(command, examples) {
-  return command ? examples[command] ?? `mm-harness ${command} --help` : "mm-harness --help";
-}
 export {
-  PUBLIC_COMMAND_CONTRACTS,
-  optionValues,
-  publicCommandNames,
-  publicCommandTokens,
-  validatePublicInvocation
+  HIDDEN_COMMANDS,
+  PUBLIC_COMMANDS,
+  REPLACED_OPTIONS,
+  explainMissingAdapterLibrary,
+  selectableAdapters,
+  withAdapterList
 };